JMX

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class JMX

java.lang.Object
    extended by  javax.management.JMX

public class JMX
extends Object

Static methods from the JMX API. There are no instances of this class.

Since:
1.6

Field Summary
static String | DEFAULT_VALUE_FIELD The name of the defaultValue field.
static String | IMMUTABLE_INFO_FIELD The name of the immutableInfo field.
static String | INTERFACE_CLASS_NAME_FIELD The name of the interfaceClassName field.
static String | LEGAL_VALUES_FIELD The name of the legalValues field.
static String | MAX_VALUE_FIELD The name of the maxValue field.
static String | MIN_VALUE_FIELD The name of the minValue field.
static String | MXBEAN_FIELD The name of the mxbean field.
static String | OPEN_TYPE_FIELD The name of the openType field.
static String | ORIGINAL_TYPE_FIELD The name of the originalType field.
Method Summary
static boolean isMXBeanInterface(Class<?> interfaceClass)
Test whether an interface is an MXBean interface.
static
<T> T
newMBeanProxy(MBeanServerConnection connection, ObjectName objectName, Class<T> interfaceClass)
Make a proxy for a Standard MBean in a local or remote MBean Server.
static
<T> T
newMBeanProxy(MBeanServerConnection connection, ObjectName objectName, Class<T> interfaceClass, boolean notificationBroadcaster)
Make a proxy for a Standard MBean in a local or remote MBean Server that may also support the methods of NotificationEmitter.
static
<T> T
newMXBeanProxy(MBeanServerConnection connection, ObjectName objectName, Class<T> interfaceClass)
Make a proxy for an MXBean in a local or remote MBean Server.
static
<T> T
newMXBeanProxy(MBeanServerConnection connection, ObjectName objectName, Class<T> interfaceClass, boolean notificationBroadcaster)
Make a proxy for an MXBean in a local or remote MBean Server that may also support the methods of NotificationEmitter.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_VALUE_FIELD

public static final String DEFAULT_VALUE_FIELD
The name of the defaultValue field.

See Also:
Constant Field Values

IMMUTABLE_INFO_FIELD

public static final String IMMUTABLE_INFO_FIELD
The name of the immutableInfo field.

See Also:
Constant Field Values

INTERFACE_CLASS_NAME_FIELD

public static final String INTERFACE_CLASS_NAME_FIELD
The name of the interfaceClassName field.

See Also:
Constant Field Values

LEGAL_VALUES_FIELD

public static final String LEGAL_VALUES_FIELD
The name of the legalValues field.

See Also:
Constant Field Values

MAX_VALUE_FIELD

public static final String MAX_VALUE_FIELD
The name of the maxValue field.

See Also:
Constant Field Values

MIN_VALUE_FIELD

public static final String MIN_VALUE_FIELD
The name of the minValue field.

See Also:
Constant Field Values

MXBEAN_FIELD

public static final String MXBEAN_FIELD
The name of the mxbean field.

See Also:
Constant Field Values

OPEN_TYPE_FIELD

public static final String OPEN_TYPE_FIELD
The name of the openType field.

See Also:
Constant Field Values

ORIGINAL_TYPE_FIELD

public static final String ORIGINAL_TYPE_FIELD
The name of the originalType field.

See Also:
Constant Field Values
Method Detail

newMBeanProxy

public static <T> T newMBeanProxy(MBeanServerConnection connection,
                                  ObjectName objectName,
                                  Class<T> interfaceClass)

Make a proxy for a Standard MBean in a local or remote MBean Server.

If you have an MBean Server mbs containing an MBean with ObjectName name, and if the MBean's management interface is described by the Java interface MyMBean, you can construct a proxy for the MBean like this:

 MyMBean proxy = JMX.newMBeanProxy(mbs, name, MyMBean.class);

Suppose, for example, MyMBean looks like this:

 public interface MyMBean {
     public String getSomeAttribute();
     public void setSomeAttribute(String value);
     public void someOperation(String param1, int param2);
 }

Then you can execute:

  • proxy.getSomeAttribute() which will result in a call to mbs. getAttribute (name, "SomeAttribute").
  • proxy.setSomeAttribute("whatever") which will result in a call to mbs. setAttribute (name, new Attribute("SomeAttribute", "whatever")).
  • proxy.someOperation("param1", 2) which will be translated into a call to mbs. invoke (name, "someOperation", <etc>).

The object returned by this method is a Proxy whose InvocationHandler is an MBeanServerInvocationHandler.

This method is equivalent to newMBeanProxy(connection, objectName, interfaceClass, false).

Type Parameters:
T - allows the compiler to know that if the interfaceClass parameter is MyMBean.class, for example, then the return type is MyMBean.
Parameters:
connection - the MBean server to forward to.
objectName - the name of the MBean within connection to forward to.
interfaceClass - the management interface that the MBean exports, which will also be implemented by the returned proxy.
Returns:
the new proxy instance.

newMBeanProxy

public static <T> T newMBeanProxy(MBeanServerConnection connection,
                                  ObjectName objectName,
                                  Class<T> interfaceClass,
                                  boolean notificationBroadcaster)

Make a proxy for a Standard MBean in a local or remote MBean Server that may also support the methods of NotificationEmitter.

This method behaves the same as newMBeanProxy(MBeanServerConnection, ObjectName, Class), but additionally, if notificationBroadcaster is true, then the MBean is assumed to be a NotificationBroadcaster or NotificationEmitter and the returned proxy will implement NotificationEmitter as well as interfaceClass. A call to NotificationBroadcaster.addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object) on the proxy will result in a call to MBeanServerConnection.addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object), and likewise for the other methods of NotificationBroadcaster and NotificationEmitter.

Type Parameters:
T - allows the compiler to know that if the interfaceClass parameter is MyMBean.class, for example, then the return type is MyMBean.
Parameters:
connection - the MBean server to forward to.
objectName - the name of the MBean within connection to forward to.
interfaceClass - the management interface that the MBean exports, which will also be implemented by the returned proxy.
notificationBroadcaster - make the returned proxy implement NotificationEmitter by forwarding its methods via connection.
Returns:
the new proxy instance.

newMXBeanProxy

public static <T> T newMXBeanProxy(MBeanServerConnection connection,
                                   ObjectName objectName,
                                   Class<T> interfaceClass)

Make a proxy for an MXBean in a local or remote MBean Server.

If you have an MBean Server mbs containing an MXBean with ObjectName name, and if the MXBean's management interface is described by the Java interface MyMXBean, you can construct a proxy for the MXBean like this:

 MyMXBean proxy = JMX.newMXBeanProxy(mbs, name, MyMXBean.class);

Suppose, for example, MyMXBean looks like this:

 public interface MyMXBean {
     public String getSimpleAttribute();
     public void setSimpleAttribute(String value);
     public MemoryUsage getMappedAttribute();
     public void setMappedAttribute(MemoryUsage memoryUsage);
     public MemoryUsage someOperation(String param1, MemoryUsage param2);
 }

Then:

  • proxy.getSimpleAttribute() will result in a call to mbs. getAttribute (name, "SimpleAttribute").

  • proxy.setSimpleAttribute("whatever") will result in a call to mbs. setAttribute (name, new Attribute("SimpleAttribute", "whatever")).

    Because String is a simple type, in the sense of SimpleType, it is not changed in the context of an MXBean. The MXBean proxy behaves the same as a Standard MBean proxy (see newMBeanProxy) for the attribute SimpleAttribute.

  • proxy.getMappedAttribute() will result in a call to mbs.getAttribute("MappedAttribute"). The MXBean mapping rules mean that the actual type of the attribute MappedAttribute will be CompositeData and that is what the mbs.getAttribute call will return. The proxy will then convert the CompositeData back into the expected type MemoryUsage using the MXBean mapping rules.

  • Similarly, proxy.setMappedAttribute(memoryUsage) will convert the MemoryUsage argument into a CompositeData before calling mbs.setAttribute.

  • proxy.someOperation("whatever", memoryUsage) will convert the MemoryUsage argument into a CompositeData and call mbs.invoke. The value returned by mbs.invoke will be also be a CompositeData, and the proxy will convert this into the expected type MemoryUsage using the MXBean mapping rules.

The object returned by this method is a Proxy whose InvocationHandler is an MBeanServerInvocationHandler.

This method is equivalent to newMXBeanProxy(connection, objectName, interfaceClass, false).

Type Parameters:
T - allows the compiler to know that if the interfaceClass parameter is MyMXBean.class, for example, then the return type is MyMXBean.
Parameters:
connection - the MBean server to forward to.
objectName - the name of the MBean within connection to forward to.
interfaceClass - the MXBean interface, which will also be implemented by the returned proxy.
Returns:
the new proxy instance.

newMXBeanProxy

public static <T> T newMXBeanProxy(MBeanServerConnection connection,
                                   ObjectName objectName,
                                   Class<T> interfaceClass,
                                   boolean notificationBroadcaster)

Make a proxy for an MXBean in a local or remote MBean Server that may also support the methods of NotificationEmitter.

This method behaves the same as newMXBeanProxy(MBeanServerConnection, ObjectName, Class), but additionally, if notificationBroadcaster is true, then the MXBean is assumed to be a NotificationBroadcaster or NotificationEmitter and the returned proxy will implement NotificationEmitter as well as interfaceClass. A call to NotificationBroadcaster.addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object) on the proxy will result in a call to MBeanServerConnection.addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object), and likewise for the other methods of NotificationBroadcaster and NotificationEmitter.

Type Parameters:
T - allows the compiler to know that if the interfaceClass parameter is MyMXBean.class, for example, then the return type is MyMXBean.
Parameters:
connection - the MBean server to forward to.
objectName - the name of the MBean within connection to forward to.
interfaceClass - the MXBean interface, which will also be implemented by the returned proxy.
notificationBroadcaster - make the returned proxy implement NotificationEmitter by forwarding its methods via connection.
Returns:
the new proxy instance.

isMXBeanInterface

public static boolean isMXBeanInterface(Class<?> interfaceClass)

Test whether an interface is an MXBean interface. An interface is an MXBean interface if it is annotated @MXBean or @MXBean(true) or if it does not have an @MXBean annotation and its name ends with "MXBean".

Parameters:
interfaceClass - The candidate interface.
Returns:
true if interfaceClass is an interface and meets the conditions described.
Throws:
NullPointerException - if interfaceClass is null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
For further API reference and developer documentation, see Java SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.


ListenerNotFoundException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class ListenerNotFoundException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.OperationsException
                    extended by  javax.management.ListenerNotFoundException
All Implemented Interfaces:
Serializable
public class ListenerNotFoundException
extends OperationsException

The specified MBean listener does not exist in the repository.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
ListenerNotFoundException()
Default constructor.
ListenerNotFoundException(String message)
Constructor that allows a specific error message to be specified.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ListenerNotFoundException

public ListenerNotFoundException()
Default constructor.

ListenerNotFoundException

public ListenerNotFoundException(String message)
Constructor that allows a specific error message to be specified.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature


loading

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.management.loading

Provides the classes which implement advanced dynamic loading.

See:
Description

Interface Summary
ClassLoaderRepository | Instances of this interface are used to keep the list of ClassLoaders registered in an MBean Server.
MLetMBean | Exposes the remote management interface of the MLet MBean.
PrivateClassLoader | Marker interface indicating that a ClassLoader should not be added to the ClassLoaderRepository.

Class Summary
DefaultLoaderRepository | Deprecated. Use MBeanServer.getClassLoaderRepository()} instead.
MLet | Allows you to instantiate and register one or several MBeans in the MBean server coming from a remote URL.
MLetContent | This class represents the contents of the MLET tag.
PrivateMLet | An MLet that is not added to the ClassLoaderRepository.

Package javax.management.loading Description

Provides the classes which implement advanced dynamic loading. See the chapter Advanced Dynamic Loading in the JMX Specification.

An MBean that is of a subclass of ClassLoader can be used as a class loader to create other MBeans via the method MBeanServer.createMBean(String, ObjectName, ObjectName, Object[], String[]), and to instantiate arbitrary objects via the method MBeanServer.instantiate(String, ObjectName, Object[], String[]). The MLet class is an example of such an MBean. It is a URLClassLoader, so the list of URLs to load classes from can be configured.

Additionally, an MLet can read a configuration file that specifies a set of MBeans to be registered in the same MBean Server as the MLet.

Every MBean Server has a class loader repository containing all MBeans registered in that MBean Server that are of a subclass of ClassLoader. The class loader repository is used by the forms of the createMBean and instantiate methods in the MBeanServer interface that do not have an explicit loader parameter. It is also used by the MLet class when it does not find a class in its own set of URLs.

If an MBean implements the interface PrivateClassLoader, then it is not added to the class loader repository. The class PrivateMLet is a subclass of MLet that implements PrivateClassLoader.

Since:
1.5
See Also:
Java SE 6 Platform documentation on JMX technology, in particular the JMX Specification, version 1.4(pdf).
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.management.loading Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.management.loading

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.ClassLoader
      • java.security.SecureClassLoader
        • java.net.URLClassLoader
          • javax.management.loading.MLet (implements java.io.Externalizable, javax.management.MBeanRegistration, javax.management.loading.MLetMBean)
            • javax.management.loading.PrivateMLet (implements javax.management.loading.PrivateClassLoader)
    • javax.management.loading.DefaultLoaderRepository
    • javax.management.loading.MLetContent

Interface Hierarchy

  • javax.management.loading.ClassLoaderRepository
  • javax.management.loading.MLetMBean
  • javax.management.loading.PrivateClassLoader
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


PrivateClassLoader

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.loading
Interface PrivateClassLoader

All Known Implementing Classes:
PrivateMLet
public interface PrivateClassLoader

Marker interface indicating that a ClassLoader should not be added to the ClassLoaderRepository. When a ClassLoader is registered as an MBean in the MBean server, it is added to the MBean server's ClassLoaderRepository unless it implements this interface.

Since:
1.5

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Package javax.management.loading

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.management.loading

Packages that use javax.management.loading
javax.management | Provides the core classes for the Java Management Extensions.
javax.management.loading | Provides the classes which implement advanced dynamic loading.
javax.management.modelmbean | Provides the definition of the ModelMBean classes.

Classes in javax.management.loading used by javax.management
ClassLoaderRepository
Instances of this interface are used to keep the list of ClassLoaders registered in an MBean Server.

Classes in javax.management.loading used by javax.management.loading
ClassLoaderRepository
Instances of this interface are used to keep the list of ClassLoaders registered in an MBean Server.
MLet
Allows you to instantiate and register one or several MBeans in the MBean server coming from a remote URL.
MLetContent
This class represents the contents of the MLET tag.
MLetMBean
Exposes the remote management interface of the MLet MBean.
PrivateClassLoader
Marker interface indicating that a ClassLoader should not be added to the ClassLoaderRepository.

Classes in javax.management.loading used by javax.management.modelmbean
ClassLoaderRepository
Instances of this interface are used to keep the list of ClassLoaders registered in an MBean Server.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.loading.DefaultLoaderRepository

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.loading.DefaultLoaderRepository

No usage of javax.management.loading.DefaultLoaderRepository

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.loading.MLet

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.loading.MLet

Packages that use MLet
javax.management.loading Provides the classes which implement advanced dynamic loading.

Uses of MLet in javax.management.loading

Subclasses of MLet in javax.management.loading
 class PrivateMLet
An MLet that is not added to the ClassLoaderRepository.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.loading.MLetContent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.loading.MLetContent

Packages that use MLetContent
javax.management.loading Provides the classes which implement advanced dynamic loading.

Uses of MLetContent in javax.management.loading

Methods in javax.management.loading with parameters of type MLetContent
protected  URL MLet.check(String version, URL codebase, String jarfile, MLetContent mlet)
This method is to be overridden when extending this service to support caching and versioning.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.loading.PrivateMLet

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.loading.PrivateMLet

No usage of javax.management.loading.PrivateMLet

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.loading.ClassLoaderRepository

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.loading.ClassLoaderRepository

Packages that use ClassLoaderRepository
javax.management | Provides the core classes for the Java Management Extensions.
javax.management.loading | Provides the classes which implement advanced dynamic loading.
javax.management.modelmbean | Provides the definition of the ModelMBean classes.

Uses of ClassLoaderRepository in javax.management

Methods in javax.management that return ClassLoaderRepository
ClassLoaderRepository | MBeanServer.getClassLoaderRepository() Return the ClassLoaderRepository for this MBeanServer.
static ClassLoaderRepository | MBeanServerFactory.getClassLoaderRepository(MBeanServer server) Return the ClassLoaderRepository used by the given MBeanServer.

Uses of ClassLoaderRepository in javax.management.loading

Methods in javax.management.loading with parameters of type ClassLoaderRepository
 Class<?> MLet.loadClass(String name, ClassLoaderRepository clr)
Load a class, using the given ClassLoaderRepository if the class is not found in this MLet's URLs.

Uses of ClassLoaderRepository in javax.management.modelmbean

Methods in javax.management.modelmbean that return ClassLoaderRepository
protected  ClassLoaderRepository RequiredModelMBean.getClassLoaderRepository()
Return the Class Loader Repository used to perform class loading.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.loading.MLetMBean

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.loading.MLetMBean

Packages that use MLetMBean
javax.management.loading Provides the classes which implement advanced dynamic loading.

Uses of MLetMBean in javax.management.loading

Classes in javax.management.loading that implement MLetMBean
class | MLet Allows you to instantiate and register one or several MBeans in the MBean server coming from a remote URL.
class | PrivateMLet An MLet that is not added to the ClassLoaderRepository.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.loading.PrivateClassLoader

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.loading.PrivateClassLoader

Packages that use PrivateClassLoader
javax.management.loading Provides the classes which implement advanced dynamic loading.

Uses of PrivateClassLoader in javax.management.loading

Classes in javax.management.loading that implement PrivateClassLoader
 class PrivateMLet
An MLet that is not added to the ClassLoaderRepository.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ClassLoaderRepository

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.management.loading
Interface ClassLoaderRepository

public interface ClassLoaderRepository

Instances of this interface are used to keep the list of ClassLoaders registered in an MBean Server. They provide the necessary methods to load classes using the registered ClassLoaders.

The first ClassLoader in a ClassLoaderRepository is always the MBean Server's own ClassLoader.

When an MBean is registered in an MBean Server, if it is of a subclass of ClassLoader and if it does not implement the interface PrivateClassLoader, it is added to the end of the MBean Server's ClassLoaderRepository. If it is subsequently unregistered from the MBean Server, it is removed from the ClassLoaderRepository.

The order of MBeans in the ClassLoaderRepository is significant. For any two MBeans X and Y in the ClassLoaderRepository, X must appear before Y if the registration of X was completed before the registration of Y started. If X and Y were registered concurrently, their order is indeterminate. The registration of an MBean corresponds to the call to MBeanServer.registerMBean(java.lang.Object, javax.management.ObjectName) or one of the MBeanServer .createMBean methods.

Since:
1.5
See Also:
MBeanServerFactory

Method Summary
Class<?> | loadClass(String className) Load the given class name through the list of class loaders.
Class<?> | loadClassBefore(ClassLoader stop, String className) Load the given class name through the list of class loaders, stopping at the given one.
Class<?> | loadClassWithout(ClassLoader exclude, String className) Load the given class name through the list of class loaders, excluding the given one.

Method Detail

loadClass

Class<?> loadClass(String className)
                   throws ClassNotFoundException

Load the given class name through the list of class loaders. Each ClassLoader in turn from the ClassLoaderRepository is asked to load the class via its ClassLoader.loadClass(String) method. If it successfully returns a Class object, that is the result of this method. If it throws a ClassNotFoundException, the search continues with the next ClassLoader. If it throws another exception, the exception is propagated from this method. If the end of the list is reached, a ClassNotFoundException is thrown.

Parameters:
className - The name of the class to be loaded.
Returns:
the loaded class.
Throws:
ClassNotFoundException - The specified class could not be found.

loadClassWithout

Class<?> loadClassWithout(ClassLoader exclude,
                          String className)
                          throws ClassNotFoundException

Load the given class name through the list of class loaders, excluding the given one. Each ClassLoader in turn from the ClassLoaderRepository, except exclude, is asked to load the class via its ClassLoader.loadClass(String) method. If it successfully returns a Class object, that is the result of this method. If it throws a ClassNotFoundException, the search continues with the next ClassLoader. If it throws another exception, the exception is propagated from this method. If the end of the list is reached, a ClassNotFoundException is thrown.

Be aware that if a ClassLoader in the ClassLoaderRepository calls this method from its loadClass method, it exposes itself to a deadlock if another ClassLoader in the ClassLoaderRepository does the same thing at the same time. The loadClassBefore(java.lang.ClassLoader, java.lang.String) method is recommended to avoid the risk of deadlock.

Parameters:
className - The name of the class to be loaded.
exclude - The class loader to be excluded. May be null, in which case this method is equivalent to loadClass(className).
Returns:
the loaded class.
Throws:
ClassNotFoundException - The specified class could not be found.

loadClassBefore

Class<?> loadClassBefore(ClassLoader stop,
                         String className)
                         throws ClassNotFoundException

Load the given class name through the list of class loaders, stopping at the given one. Each ClassLoader in turn from the ClassLoaderRepository is asked to load the class via its ClassLoader.loadClass(String) method. If it successfully returns a Class object, that is the result of this method. If it throws a ClassNotFoundException, the search continues with the next ClassLoader. If it throws another exception, the exception is propagated from this method. If the search reaches stop or the end of the list, a ClassNotFoundException is thrown.

Typically this method is called from the loadClass method of stop, to consult loaders that appear before it in the ClassLoaderRepository. By stopping the search as soon as stop is reached, a potential deadlock with concurrent class loading is avoided.

Parameters:
className - The name of the class to be loaded.
stop - The class loader at which to stop. May be null, in which case this method is equivalent to loadClass(className).
Returns:
the loaded class.
Throws:
ClassNotFoundException - The specified class could not be found.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


DefaultLoaderRepository

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.loading
Class DefaultLoaderRepository

java.lang.Object
    extended by  javax.management.loading.DefaultLoaderRepository
Deprecated. Use MBeanServer.getClassLoaderRepository()} instead.

@Deprecated
public class DefaultLoaderRepository
extends Object

Keeps the list of Class Loaders registered in the MBean Server. It provides the necessary methods to load classes using the registered Class Loaders.

This deprecated class is maintained for compatibility. In previous versions of JMX, there was one DefaultLoaderRepository shared by all MBean servers. As of JMX 1.2, that functionality is approximated by using MBeanServerFactory.findMBeanServer(java.lang.String) to find all known MBean servers, and consulting the ClassLoaderRepository of each one. It is strongly recommended that code referencing DefaultLoaderRepository be rewritten.

Since:
1.5

Constructor Summary
DefaultLoaderRepository()
Deprecated.
Method Summary
static Class | loadClass(String className) Deprecated. Go through the list of class loaders and try to load the requested class.
static Class | loadClassWithout(ClassLoader loader, String className) Deprecated. Go through the list of class loaders but exclude the given class loader, then try to load the requested class.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultLoaderRepository

public DefaultLoaderRepository()
Deprecated.
Method Detail

loadClass

public static Class loadClass(String className)
                       throws ClassNotFoundException
Deprecated.
Go through the list of class loaders and try to load the requested class. The method will stop as soon as the class is found. If the class is not found the method will throw a ClassNotFoundException exception.

Parameters:
className - The name of the class to be loaded.
Returns:
the loaded class.
Throws:
ClassNotFoundException - The specified class could not be found.

loadClassWithout

public static Class loadClassWithout(ClassLoader loader,
                                     String className)
                              throws ClassNotFoundException
Deprecated.
Go through the list of class loaders but exclude the given class loader, then try to load the requested class. The method will stop as soon as the class is found. If the class is not found the method will throw a ClassNotFoundException exception.

Parameters:
className - The name of the class to be loaded.
loader - The class loader to be excluded.
Returns:
the loaded class.
Throws:
ClassNotFoundException - The specified class could not be found.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MLet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.loading
Class MLet

java.lang.Object
    extended by  java.lang.ClassLoader
        extended by  java.security.SecureClassLoader
            extended by  java.net.URLClassLoader
                extended by  javax.management.loading.MLet
All Implemented Interfaces:
Externalizable, Serializable, MLetMBean, MBeanRegistration
Direct Known Subclasses:
PrivateMLet
public class MLet
extends URLClassLoader
implements MLetMBean, MBeanRegistration, Externalizable

Allows you to instantiate and register one or several MBeans in the MBean server coming from a remote URL. M-let is a shortcut for management applet. The m-let service does this by loading an m-let text file, which specifies information on the MBeans to be obtained. The information on each MBean is specified in a single instance of a tag, called the MLET tag. The location of the m-let text file is specified by a URL.

The MLET tag has the following syntax:

<MLET
CODE = class | OBJECT = serfile
ARCHIVE = "archiveList"
[CODEBASE = codebaseURL]
[NAME = mbeanname]
[VERSION = version]
>
[arglist]
</MLET>

where:

CODE = class
This attribute specifies the full Java class name, including package name, of the MBean to be obtained. The compiled .class file of the MBean must be contained in one of the .jar files specified by the ARCHIVE attribute. Either CODE or OBJECT must be present.
OBJECT = serfile
This attribute specifies the .ser file that contains a serialized representation of the MBean to be obtained. This file must be contained in one of the .jar files specified by the ARCHIVE attribute. If the .jar file contains a directory hierarchy, specify the path of the file within this hierarchy. Otherwise a match will not be found. Either CODE or OBJECT must be present.
ARCHIVE = "archiveList"
This mandatory attribute specifies one or more .jar files containing MBeans or other resources used by the MBean to be obtained. One of the .jar files must contain the file specified by the CODE or OBJECT attribute. If archivelist contains more than one file:
  • Each file must be separated from the one that follows it by a comma (,).
  • archivelist must be enclosed in double quote marks.
All .jar files in archivelist must be stored in the directory specified by the code base URL.
CODEBASE = codebaseURL
This optional attribute specifies the code base URL of the MBean to be obtained. It identifies the directory that contains the .jar files specified by the ARCHIVE attribute. Specify this attribute only if the .jar files are not in the same directory as the m-let text file. If this attribute is not specified, the base URL of the m-let text file is used.
NAME = mbeanname
This optional attribute specifies the object name to be assigned to the MBean instance when the m-let service registers it. If mbeanname starts with the colon character (:), the domain part of the object name is the default domain of the MBean server, as returned by MBeanServer.getDefaultDomain().
VERSION = version
This optional attribute specifies the version number of the MBean and associated .jar files to be obtained. This version number can be used to specify that the .jar files are loaded from the server to update those stored locally in the cache the next time the m-let text file is loaded. version must be a series of non-negative decimal integers each separated by a period from the one that precedes it.
arglist
This optional attribute specifies a list of one or more parameters for the MBean to be instantiated. This list describes the parameters to be passed the MBean's constructor. Use the following syntax to specify each item in arglist:

<ARG TYPE=argumentType VALUE=value>

where:
  • argumentType is the type of the argument that will be passed as parameter to the MBean's constructor.

The arguments' type in the argument list should be a Java primitive type or a Java basic type (java.lang.Boolean, java.lang.Byte, java.lang.Short, java.lang.Long, java.lang.Integer, java.lang.Float, java.lang.Double, java.lang.String).

When an m-let text file is loaded, an instance of each MBean specified in the file is created and registered.

The m-let service extends the java.net.URLClassLoader and can be used to load remote classes and jar files in the VM of the agent.

Note - The MLet class loader uses the MBeanServerFactory.getClassLoaderRepository(javax.management.MBeanServer) to load classes that could not be found in the loaded jar files.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
MLet()
Constructs a new MLet using the default delegation parent ClassLoader.
MLet(URL[] urls)
Constructs a new MLet for the specified URLs using the default delegation parent ClassLoader.
MLet(URL[] urls, boolean delegateToCLR)
Constructs a new MLet for the specified URLs using the default delegation parent ClassLoader.
MLet(URL[] urls, ClassLoader parent)
Constructs a new MLet for the given URLs.
MLet(URL[] urls, ClassLoader parent, boolean delegateToCLR)
Constructs a new MLet for the given URLs.
MLet(URL[] urls, ClassLoader parent, URLStreamHandlerFactory factory)
Constructs a new MLet for the specified URLs, parent class loader, and URLStreamHandlerFactory.
MLet(URL[] urls, ClassLoader parent, URLStreamHandlerFactory factory, boolean delegateToCLR)
Constructs a new MLet for the specified URLs, parent class loader, and URLStreamHandlerFactory.
Method Summary
void | addURL(String url) Appends the specified URL to the list of URLs to search for classes and resources.
void | addURL(URL url) Appends the specified URL to the list of URLs to search for classes and resources.
protected URL | check(String version, URL codebase, String jarfile, MLetContent mlet) This method is to be overridden when extending this service to support caching and versioning.
protected Class<?> | findClass(String name) This is the main method for class loaders that is being redefined.
protected String | findLibrary(String libname) Returns the absolute path name of a native library.
String | getLibraryDirectory() Gets the current directory used by the library loader for storing native libraries before they are loaded into memory.
Set<Object> | getMBeansFromURL(String url) Loads a text file containing MLET tags that define the MBeans to be added to the MBean server.
Set<Object> | getMBeansFromURL(URL url) Loads a text file containing MLET tags that define the MBeans to be added to the MBean server.
URL[] | getURLs() Returns the search path of URLs for loading classes and resources.
Class<?> | loadClass(String name, ClassLoaderRepository clr) Load a class, using the given ClassLoaderRepository if the class is not found in this MLet's URLs.
void | postDeregister() Allows the m-let to perform any operations needed after having been unregistered in the MBean server.
void | postRegister(Boolean registrationDone) Allows the m-let to perform any operations needed after having been registered in the MBean server or after the registration has failed.
void | preDeregister() Allows the m-let to perform any operations it needs before being unregistered by the MBean server.
ObjectName | preRegister(MBeanServer server, ObjectName name) Allows the m-let to perform any operations it needs before being registered in the MBean server.
void | readExternal(ObjectInput in) Restore this MLet's contents from the given ObjectInput.
void | setLibraryDirectory(String libdir) Sets the directory used by the library loader for storing native libraries before they are loaded into memory.
void | writeExternal(ObjectOutput out) Save this MLet's contents to the given ObjectOutput.
Methods inherited from class java.net.URLClassLoader
definePackage, findResource, findResources, getPermissions, newInstance, newInstance
Methods inherited from class java.security.SecureClassLoader
defineClass, defineClass
Methods inherited from class java.lang.ClassLoader
clearAssertionStatus, defineClass, defineClass, defineClass, defineClass, definePackage, findLoadedClass, findSystemClass, getPackage, getPackages, getParent, getResource, getResourceAsStream, getResources, getSystemClassLoader, getSystemResource, getSystemResourceAsStream, getSystemResources, loadClass, loadClass, resolveClass, setClassAssertionStatus, setDefaultAssertionStatus, setPackageAssertionStatus, setSigners
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.management.loading.MLetMBean
getResource, getResourceAsStream, getResources

Constructor Detail

MLet

public MLet()
Constructs a new MLet using the default delegation parent ClassLoader.

MLet

public MLet(URL[] urls)
Constructs a new MLet for the specified URLs using the default delegation parent ClassLoader. The URLs will be searched in the order specified for classes and resources after first searching in the parent class loader.

Parameters:
urls - The URLs from which to load classes and resources.

MLet

public MLet(URL[] urls,
            ClassLoader parent)
Constructs a new MLet for the given URLs. The URLs will be searched in the order specified for classes and resources after first searching in the specified parent class loader. The parent argument will be used as the parent class loader for delegation.

Parameters:
urls - The URLs from which to load classes and resources.
parent - The parent class loader for delegation.

MLet

public MLet(URL[] urls,
            ClassLoader parent,
            URLStreamHandlerFactory factory)
Constructs a new MLet for the specified URLs, parent class loader, and URLStreamHandlerFactory. The parent argument will be used as the parent class loader for delegation. The factory argument will be used as the stream handler factory to obtain protocol handlers when creating new URLs.

Parameters:
urls - The URLs from which to load classes and resources.
parent - The parent class loader for delegation.
factory - The URLStreamHandlerFactory to use when creating URLs.

MLet

public MLet(URL[] urls,
            boolean delegateToCLR)
Constructs a new MLet for the specified URLs using the default delegation parent ClassLoader. The URLs will be searched in the order specified for classes and resources after first searching in the parent class loader.

Parameters:
urls - The URLs from which to load classes and resources.
delegateToCLR - True if, when a class is not found in either the parent ClassLoader or the URLs, the MLet should delegate to its containing MBeanServer's ClassLoaderRepository.

MLet

public MLet(URL[] urls,
            ClassLoader parent,
            boolean delegateToCLR)
Constructs a new MLet for the given URLs. The URLs will be searched in the order specified for classes and resources after first searching in the specified parent class loader. The parent argument will be used as the parent class loader for delegation.

Parameters:
urls - The URLs from which to load classes and resources.
parent - The parent class loader for delegation.
delegateToCLR - True if, when a class is not found in either the parent ClassLoader or the URLs, the MLet should delegate to its containing MBeanServer's ClassLoaderRepository.

MLet

public MLet(URL[] urls,
            ClassLoader parent,
            URLStreamHandlerFactory factory,
            boolean delegateToCLR)
Constructs a new MLet for the specified URLs, parent class loader, and URLStreamHandlerFactory. The parent argument will be used as the parent class loader for delegation. The factory argument will be used as the stream handler factory to obtain protocol handlers when creating new URLs.

Parameters:
urls - The URLs from which to load classes and resources.
parent - The parent class loader for delegation.
factory - The URLStreamHandlerFactory to use when creating URLs.
delegateToCLR - True if, when a class is not found in either the parent ClassLoader or the URLs, the MLet should delegate to its containing MBeanServer's ClassLoaderRepository.
Method Detail

addURL

public void addURL(URL url)
Appends the specified URL to the list of URLs to search for classes and resources.

Specified by:
addURL in interface MLetMBean
Overrides:
addURL in class URLClassLoader
Parameters:
url - the URL to be added to the search path of URLs

addURL

public void addURL(String url)
            throws ServiceNotFoundException
Appends the specified URL to the list of URLs to search for classes and resources.

Specified by:
addURL in interface MLetMBean
Parameters:
url - the URL to add.
Throws:
ServiceNotFoundException - The specified URL is malformed.

getURLs

public URL[] getURLs()
Returns the search path of URLs for loading classes and resources. This includes the original list of URLs specified to the constructor, along with any URLs subsequently appended by the addURL() method.

Specified by:
getURLs in interface MLetMBean
Overrides:
getURLs in class URLClassLoader
Returns:
the search path of URLs for loading classes and resources.

getMBeansFromURL

public Set<Object> getMBeansFromURL(URL url)
                             throws ServiceNotFoundException
Loads a text file containing MLET tags that define the MBeans to be added to the MBean server. The location of the text file is specified by a URL. The MBeans specified in the MLET file will be instantiated and registered in the MBean server.

Specified by:
getMBeansFromURL in interface MLetMBean
Parameters:
url - The URL of the text file to be loaded as URL object.
Returns:
A set containing one entry per MLET tag in the m-let text file loaded. Each entry specifies either the ObjectInstance for the created MBean, or a throwable object (that is, an error or an exception) if the MBean could not be created.
Throws:
ServiceNotFoundException - One of the following errors has occurred: The m-let text file does not contain an MLET tag, the m-let text file is not found, a mandatory attribute of the MLET tag is not specified, the value of url is null.
IllegalStateException - MLet MBean is not registered with an MBeanServer.

getMBeansFromURL

public Set<Object> getMBeansFromURL(String url)
                             throws ServiceNotFoundException
Loads a text file containing MLET tags that define the MBeans to be added to the MBean server. The location of the text file is specified by a URL. The MBeans specified in the MLET file will be instantiated and registered in the MBean server.

Specified by:
getMBeansFromURL in interface MLetMBean
Parameters:
url - The URL of the text file to be loaded as String object.
Returns:
A set containing one entry per MLET tag in the m-let text file loaded. Each entry specifies either the ObjectInstance for the created MBean, or a throwable object (that is, an error or an exception) if the MBean could not be created.
Throws:
ServiceNotFoundException - One of the following errors has occurred: The m-let text file does not contain an MLET tag, the m-let text file is not found, a mandatory attribute of the MLET tag is not specified, the url is malformed.
IllegalStateException - MLet MBean is not registered with an MBeanServer.

getLibraryDirectory

public String getLibraryDirectory()
Gets the current directory used by the library loader for storing native libraries before they are loaded into memory.

Specified by:
getLibraryDirectory in interface MLetMBean
Returns:
The current directory used by the library loader.
Throws:
UnsupportedOperationException - if this implementation does not support storing native libraries in this way.
See Also:
setLibraryDirectory(java.lang.String)

setLibraryDirectory

public void setLibraryDirectory(String libdir)
Sets the directory used by the library loader for storing native libraries before they are loaded into memory.

Specified by:
setLibraryDirectory in interface MLetMBean
Parameters:
libdir - The directory used by the library loader.
Throws:
UnsupportedOperationException - if this implementation does not support storing native libraries in this way.
See Also:
getLibraryDirectory()

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception
Allows the m-let to perform any operations it needs before being registered in the MBean server. If the ObjectName is null, the m-let provides a default name for its registration <defaultDomain>:type=MLet

Specified by:
preRegister in interface MBeanRegistration
Parameters:
server - The MBean server in which the m-let will be registered.
name - The object name of the m-let.
Returns:
The name of the m-let registered.
Throws:
Exception - This exception should be caught by the MBean server and re-thrown as an MBeanRegistrationException.

postRegister

public void postRegister(Boolean registrationDone)
Allows the m-let to perform any operations needed after having been registered in the MBean server or after the registration has failed.

Specified by:
postRegister in interface MBeanRegistration
Parameters:
registrationDone - Indicates whether or not the m-let has been successfully registered in the MBean server. The value false means that either the registration phase has failed.

preDeregister

public void preDeregister()
                   throws Exception
Allows the m-let to perform any operations it needs before being unregistered by the MBean server.

Specified by:
preDeregister in interface MBeanRegistration
Throws:
java.langException - This exception should be caught by the MBean server and re-thrown as an MBeanRegistrationException.
Exception - This exception will be caught by the MBean server and re-thrown as an MBeanRegistrationException.

postDeregister

public void postDeregister()
Allows the m-let to perform any operations needed after having been unregistered in the MBean server.

Specified by:
postDeregister in interface MBeanRegistration

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException,
                          UnsupportedOperationException

Save this MLet's contents to the given ObjectOutput. Not all implementations support this method. Those that do not throw UnsupportedOperationException. A subclass may override this method to support it or to change the format of the written data.

The format of the written data is not specified, but if an implementation supports writeExternal(java.io.ObjectOutput) it must also support readExternal(java.io.ObjectInput) in such a way that what is written by the former can be read by the latter.

Specified by:
writeExternal in interface Externalizable
Parameters:
out - The object output stream to write to.
Throws:
IOException - If a problem occurred while writing.
UnsupportedOperationException - If this implementation does not support this operation.

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException,
                         UnsupportedOperationException

Restore this MLet's contents from the given ObjectInput. Not all implementations support this method. Those that do not throw UnsupportedOperationException. A subclass may override this method to support it or to change the format of the read data.

The format of the read data is not specified, but if an implementation supports readExternal(java.io.ObjectInput) it must also support writeExternal(java.io.ObjectOutput) in such a way that what is written by the latter can be read by the former.

Specified by:
readExternal in interface Externalizable
Parameters:
in - The object input stream to read from.
Throws:
IOException - if a problem occurred while reading.
ClassNotFoundException - if the class for the object being restored cannot be found.
UnsupportedOperationException - if this implementation does not support this operation.

loadClass

public Class<?> loadClass(String name,
                          ClassLoaderRepository clr)
                   throws ClassNotFoundException

Load a class, using the given ClassLoaderRepository if the class is not found in this MLet's URLs. The given ClassLoaderRepository can be null, in which case a ClassNotFoundException occurs immediately if the class is not found in this MLet's URLs.

Parameters:
name - The name of the class we want to load.
clr - The ClassLoaderRepository that will be used to search for the given class, if it is not found in this ClassLoader. May be null.
Returns:
The resulting Class object.
Throws:
ClassNotFoundException - The specified class could not be found in this ClassLoader nor in the given ClassLoaderRepository.

findClass

protected Class<?> findClass(String name)
                      throws ClassNotFoundException
This is the main method for class loaders that is being redefined.

Overrides:
findClass in class URLClassLoader
Parameters:
name - The name of the class.
Returns:
The resulting Class object.
Throws:
ClassNotFoundException - The specified class could not be found.

findLibrary

protected String findLibrary(String libname)
Returns the absolute path name of a native library. The VM invokes this method to locate the native libraries that belong to classes loaded with this class loader. Libraries are searched in the JAR files using first just the native library name and if not found the native library name together with the architecture-specific path name (OSName/OSArch/OSVersion/lib/nativelibname), i.e.

the library stat on Solaris SPARC 5.7 will be searched in the JAR file as:

  1. libstat.so
  2. SunOS/sparc/5.7/lib/libstat.so
the library stat on Windows NT 4.0 will be searched in the JAR file as:
  1. stat.dll
  2. WindowsNT/x86/4.0/lib/stat.dll

More specifically, let nativelibname be the result of System.mapLibraryName (libname). Then the following names are searched in the JAR files, in order:
nativelibname
<os.name>/<os.arch>/<os.version>/lib/nativelibname
where <X> means System.getProperty(X) with any spaces in the result removed, and / stands for the file separator character (File.separator).

If this method returns null, i.e. the libraries were not found in any of the JAR files loaded with this class loader, the VM searches the library along the path specified as the java.library.path property.

Overrides:
findLibrary in class ClassLoader
Parameters:
libname - The library name.
Returns:
The absolute path of the native library.
See Also:
System.loadLibrary(String), System.mapLibraryName(String)

check

protected URL check(String version,
                    URL codebase,
                    String jarfile,
                    MLetContent mlet)
             throws Exception

This method is to be overridden when extending this service to support caching and versioning. It is called from getMBeansFromURL when the version, codebase, and jarfile have been extracted from the MLet file, and can be used to verify that it is all right to load the given MBean, or to replace the given URL with a different one.

The default implementation of this method returns codebase unchanged.

Parameters:
version - The version number of the .jar file stored locally.
codebase - The base URL of the remote .jar file.
jarfile - The name of the .jar file to be loaded.
mlet - The MLetContent instance that represents the MLET tag.
Returns:
the codebase to use for the loaded MBean. The returned value should not be null.
Throws:
Exception - if the MBean is not to be loaded for some reason. The exception will be added to the set returned by getMBeansFromURL.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MLetContent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.loading
Class MLetContent

java.lang.Object
    extended by  javax.management.loading.MLetContent

public class MLetContent
extends Object

This class represents the contents of the MLET tag. It can be consulted by a subclass of MLet that overrides the MLet.check method.

Since:
1.6

Constructor Summary
MLetContent(URL url, Map<String,String> attributes, List<String> types, List<String> values)
Creates an MLet instance initialized with attributes read from an MLET tag in an MLet text file.
Method Summary
Map<String,String> | getAttributes() Gets the attributes of the MLET tag.
String | getCode() Gets the value of the CODE attribute of the MLET tag.
URL | getCodeBase() Gets the code base URL.
URL | getDocumentBase() Gets the MLet text file's base URL.
String | getJarFiles() Gets the list of .jar files specified by the ARCHIVE attribute of the MLET tag.
String | getName() Gets the value of the NAME attribute of the MLET tag.
List<String> | getParameterTypes() Gets the list of values of the TYPE attribute in each nested <PARAM> tag within the MLET tag.
List<String> | getParameterValues() Gets the list of values of the VALUE attribute in each nested <PARAM> tag within the MLET tag.
String | getSerializedObject() Gets the value of the OBJECT attribute of the MLET tag.
String | getVersion() Gets the value of the VERSION attribute of the MLET tag.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MLetContent

public MLetContent(URL url,
                   Map<String,String> attributes,
                   List<String> types,
                   List<String> values)
Creates an MLet instance initialized with attributes read from an MLET tag in an MLet text file.

Parameters:
url - The URL of the MLet text file containing the MLET tag.
attributes - A map of the attributes of the MLET tag. The keys in this map are the attribute names in lowercase, for example codebase. The values are the associated attribute values.
types - A list of the TYPE attributes that appeared in nested <PARAM> tags.
values - A list of the VALUE attributes that appeared in nested <PARAM> tags.
Method Detail

getAttributes

public Map<String,String> getAttributes()
Gets the attributes of the MLET tag. The keys in the returned map are the attribute names in lowercase, for example codebase. The values are the associated attribute values.

Returns:
A map of the attributes of the MLET tag and their values.

getDocumentBase

public URL getDocumentBase()
Gets the MLet text file's base URL.

Returns:
The MLet text file's base URL.

getCodeBase

public URL getCodeBase()
Gets the code base URL.

Returns:
The code base URL.

getJarFiles

public String getJarFiles()
Gets the list of .jar files specified by the ARCHIVE attribute of the MLET tag.

Returns:
A comma-separated list of .jar file names.

getCode

public String getCode()
Gets the value of the CODE attribute of the MLET tag.

Returns:
The value of the CODE attribute of the MLET tag.

getSerializedObject

public String getSerializedObject()
Gets the value of the OBJECT attribute of the MLET tag.

Returns:
The value of the OBJECT attribute of the MLET tag.

getName

public String getName()
Gets the value of the NAME attribute of the MLET tag.

Returns:
The value of the NAME attribute of the MLET tag.

getVersion

public String getVersion()
Gets the value of the VERSION attribute of the MLET tag.

Returns:
The value of the VERSION attribute of the MLET tag.

getParameterTypes

public List<String> getParameterTypes()
Gets the list of values of the TYPE attribute in each nested <PARAM> tag within the MLET tag.

Returns:
the list of types.

getParameterValues

public List<String> getParameterValues()
Gets the list of values of the VALUE attribute in each nested <PARAM> tag within the MLET tag.

Returns:
the list of values.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MLetMBean

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.loading
Interface MLetMBean

All Known Implementing Classes:
MLet, PrivateMLet
public interface MLetMBean

Exposes the remote management interface of the MLet MBean.

Since:
1.5

Method Summary
void | addURL(String url) Appends the specified URL to the list of URLs to search for classes and resources.
void | addURL(URL url) Appends the specified URL to the list of URLs to search for classes and resources.
String | getLibraryDirectory() Gets the current directory used by the library loader for storing native libraries before they are loaded into memory.
Set<Object> | getMBeansFromURL(String url) Loads a text file containing MLET tags that define the MBeans to be added to the MBean server.
Set<Object> | getMBeansFromURL(URL url) Loads a text file containing MLET tags that define the MBeans to be added to the MBean server.
URL | getResource(String name) Finds the resource with the given name.
InputStream | getResourceAsStream(String name) Returns an input stream for reading the specified resource.
Enumeration<URL> | getResources(String name) Finds all the resources with the given name.
URL[] | getURLs() Returns the search path of URLs for loading classes and resources.
void | setLibraryDirectory(String libdir) Sets the directory used by the library loader for storing native libraries before they are loaded into memory.

Method Detail

getMBeansFromURL

Set<Object> getMBeansFromURL(String url)
                             throws ServiceNotFoundException
Loads a text file containing MLET tags that define the MBeans to be added to the MBean server. The location of the text file is specified by a URL. The text file is read using the UTF-8 encoding. The MBeans specified in the MLET file will be instantiated and registered in the MBean server.

Parameters:
url - The URL of the text file to be loaded as String object.
Returns:
A set containing one entry per MLET tag in the m-let text file loaded. Each entry specifies either the ObjectInstance for the created MBean, or a throwable object (that is, an error or an exception) if the MBean could not be created.
Throws:
ServiceNotFoundException - One of the following errors has occurred: The m-let text file does not contain an MLET tag, the m-let text file is not found, a mandatory attribute of the MLET tag is not specified, the value of url is malformed.

getMBeansFromURL

Set<Object> getMBeansFromURL(URL url)
                             throws ServiceNotFoundException
Loads a text file containing MLET tags that define the MBeans to be added to the MBean server. The location of the text file is specified by a URL. The text file is read using the UTF-8 encoding. The MBeans specified in the MLET file will be instantiated and registered in the MBean server.

Parameters:
url - The URL of the text file to be loaded as URL object.
Returns:
A set containing one entry per MLET tag in the m-let text file loaded. Each entry specifies either the ObjectInstance for the created MBean, or a throwable object (that is, an error or an exception) if the MBean could not be created.
Throws:
ServiceNotFoundException - One of the following errors has occurred: The m-let text file does not contain an MLET tag, the m-let text file is not found, a mandatory attribute of the MLET tag is not specified, the value of url is null.

addURL

void addURL(URL url)
Appends the specified URL to the list of URLs to search for classes and resources.

Parameters:
url - the URL to add.

addURL

void addURL(String url)
            throws ServiceNotFoundException
Appends the specified URL to the list of URLs to search for classes and resources.

Parameters:
url - the URL to add.
Throws:
ServiceNotFoundException - The specified URL is malformed.

getURLs

URL[] getURLs()
Returns the search path of URLs for loading classes and resources. This includes the original list of URLs specified to the constructor, along with any URLs subsequently appended by the addURL() method.

Returns:
the list of URLs.

getResource

URL getResource(String name)
Finds the resource with the given name. A resource is some data (images, audio, text, etc) that can be accessed by class code in a way that is independent of the location of the code. The name of a resource is a "/"-separated path name that identifies the resource.

Parameters:
name - The resource name
Returns:
An URL for reading the resource, or null if the resource could not be found or the caller doesn't have adequate privileges to get the resource.

getResourceAsStream

InputStream getResourceAsStream(String name)
Returns an input stream for reading the specified resource. The search order is described in the documentation for getResource(String).

Parameters:
name - The resource name
Returns:
An input stream for reading the resource, or null if the resource could not be found

getResources

Enumeration<URL> getResources(String name)
                              throws IOException
Finds all the resources with the given name. A resource is some data (images, audio, text, etc) that can be accessed by class code in a way that is independent of the location of the code. The name of a resource is a "/"-separated path name that identifies the resource.

Parameters:
name - The resource name.
Returns:
An enumeration of URL to the resource. If no resources could be found, the enumeration will be empty. Resources that cannot be accessed will not be in the enumeration.
Throws:
IOException - if an I/O exception occurs when searching for resources.

getLibraryDirectory

String getLibraryDirectory()
Gets the current directory used by the library loader for storing native libraries before they are loaded into memory.

Returns:
The current directory used by the library loader.
Throws:
UnsupportedOperationException - if this implementation does not support storing native libraries in this way.
See Also:
setLibraryDirectory(java.lang.String)

setLibraryDirectory

void setLibraryDirectory(String libdir)
Sets the directory used by the library loader for storing native libraries before they are loaded into memory.

Parameters:
libdir - The directory used by the library loader.
Throws:
UnsupportedOperationException - if this implementation does not support storing native libraries in this way.
See Also:
getLibraryDirectory()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrivateMLet

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.management.loading
Class PrivateMLet

java.lang.Object
    extended by  java.lang.ClassLoader
        extended by  java.security.SecureClassLoader
            extended by  java.net.URLClassLoader
                extended by  javax.management.loading.MLet
                    extended by  javax.management.loading.PrivateMLet
All Implemented Interfaces:
Externalizable, Serializable, MLetMBean, PrivateClassLoader, MBeanRegistration
public class PrivateMLet
extends MLet
implements PrivateClassLoader

An MLet that is not added to the ClassLoaderRepository. This class acts exactly like its parent class, MLet, with one exception. When a PrivateMLet is registered in an MBean server, it is not added to that MBean server's ClassLoaderRepository. This is true because this class implements the interface PrivateClassLoader.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
PrivateMLet(URL[] urls, boolean delegateToCLR)
Constructs a new PrivateMLet for the specified URLs using the default delegation parent ClassLoader.
PrivateMLet(URL[] urls, ClassLoader parent, boolean delegateToCLR)
Constructs a new PrivateMLet for the given URLs.
PrivateMLet(URL[] urls, ClassLoader parent, URLStreamHandlerFactory factory, boolean delegateToCLR)
Constructs a new PrivateMLet for the specified URLs, parent class loader, and URLStreamHandlerFactory.
Method Summary
Methods inherited from class javax.management.loading.MLet
addURL, addURL, check, findClass, findLibrary, getLibraryDirectory, getMBeansFromURL, getMBeansFromURL, getURLs, loadClass, postDeregister, postRegister, preDeregister, preRegister, readExternal, setLibraryDirectory, writeExternal
Methods inherited from class java.net.URLClassLoader
definePackage, findResource, findResources, getPermissions, newInstance, newInstance
Methods inherited from class java.security.SecureClassLoader
defineClass, defineClass
Methods inherited from class java.lang.ClassLoader
clearAssertionStatus, defineClass, defineClass, defineClass, defineClass, definePackage, findLoadedClass, findSystemClass, getPackage, getPackages, getParent, getResource, getResourceAsStream, getResources, getSystemClassLoader, getSystemResource, getSystemResourceAsStream, getSystemResources, loadClass, loadClass, resolveClass, setClassAssertionStatus, setDefaultAssertionStatus, setPackageAssertionStatus, setSigners
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.management.loading.MLetMBean
getResource, getResourceAsStream, getResources

Constructor Detail

PrivateMLet

public PrivateMLet(URL[] urls,
                   boolean delegateToCLR)
Constructs a new PrivateMLet for the specified URLs using the default delegation parent ClassLoader. The URLs will be searched in the order specified for classes and resources after first searching in the parent class loader.

Parameters:
urls - The URLs from which to load classes and resources.
delegateToCLR - True if, when a class is not found in either the parent ClassLoader or the URLs, the MLet should delegate to its containing MBeanServer's ClassLoaderRepository.

PrivateMLet

public PrivateMLet(URL[] urls,
                   ClassLoader parent,
                   boolean delegateToCLR)
Constructs a new PrivateMLet for the given URLs. The URLs will be searched in the order specified for classes and resources after first searching in the specified parent class loader. The parent argument will be used as the parent class loader for delegation.

Parameters:
urls - The URLs from which to load classes and resources.
parent - The parent class loader for delegation.
delegateToCLR - True if, when a class is not found in either the parent ClassLoader or the URLs, the MLet should delegate to its containing MBeanServer's ClassLoaderRepository.

PrivateMLet

public PrivateMLet(URL[] urls,
                   ClassLoader parent,
                   URLStreamHandlerFactory factory,
                   boolean delegateToCLR)
Constructs a new PrivateMLet for the specified URLs, parent class loader, and URLStreamHandlerFactory. The parent argument will be used as the parent class loader for delegation. The factory argument will be used as the stream handler factory to obtain protocol handlers when creating new URLs.

Parameters:
urls - The URLs from which to load classes and resources.
parent - The parent class loader for delegation.
factory - The URLStreamHandlerFactory to use when creating URLs.
delegateToCLR - True if, when a class is not found in either the parent ClassLoader or the URLs, the MLet should delegate to its containing MBeanServer's ClassLoaderRepository.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


MalformedObjectNameException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MalformedObjectNameException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.OperationsException
                    extended by  javax.management.MalformedObjectNameException
All Implemented Interfaces:
Serializable
public class MalformedObjectNameException
extends OperationsException

The format of the string does not correspond to a valid ObjectName.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
MalformedObjectNameException()
Default constructor.
MalformedObjectNameException(String message)
Constructor that allows a specific error message to be specified.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MalformedObjectNameException

public MalformedObjectNameException()
Default constructor.

MalformedObjectNameException

public MalformedObjectNameException(String message)
Constructor that allows a specific error message to be specified.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanAttributeInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MBeanAttributeInfo

java.lang.Object
    extended by  javax.management.MBeanFeatureInfo
        extended by  javax.management.MBeanAttributeInfo
All Implemented Interfaces:
Serializable, Cloneable, DescriptorRead
Direct Known Subclasses:
ModelMBeanAttributeInfo, OpenMBeanAttributeInfoSupport
public class MBeanAttributeInfo
extends MBeanFeatureInfo
implements Cloneable

Describes an MBean attribute exposed for management. Instances of this class are immutable. Subclasses may be mutable but this is not recommended.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.management.MBeanFeatureInfo
description, name
Constructor Summary
MBeanAttributeInfo(String name, String description, Method getter, Method setter)
This constructor takes the name of a simple attribute, and Method objects for reading and writing the attribute.
MBeanAttributeInfo(String name, String type, String description, boolean isReadable, boolean isWritable, boolean isIs)
Constructs an MBeanAttributeInfo object.
MBeanAttributeInfo(String name, String type, String description, boolean isReadable, boolean isWritable, boolean isIs, Descriptor descriptor)
Constructs an MBeanAttributeInfo object.
Method Summary
Object | clone() Returns a shallow clone of this instance.
boolean | equals(Object o) Compare this MBeanAttributeInfo to another.
String | getType() Returns the class name of the attribute.
int | hashCode() Returns a hash code value for the object.
boolean | isIs() Indicates if this attribute has an "is" getter.
boolean | isReadable() Whether the value of the attribute can be read.
boolean | isWritable() Whether new values can be written to the attribute.
String | toString() Returns a string representation of the object.
Methods inherited from class javax.management.MBeanFeatureInfo
getDescription, getDescriptor, getName
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

MBeanAttributeInfo

public MBeanAttributeInfo(String name,
                          String type,
                          String description,
                          boolean isReadable,
                          boolean isWritable,
                          boolean isIs)
Constructs an MBeanAttributeInfo object.

Parameters:
name - The name of the attribute.
type - The type or class name of the attribute.
description - A human readable description of the attribute.
isReadable - True if the attribute has a getter method, false otherwise.
isWritable - True if the attribute has a setter method, false otherwise.
isIs - True if this attribute has an "is" getter, false otherwise.
Throws:
IllegalArgumentException - if isIs is true but isReadable is not, or if isIs is true and type is not boolean or java.lang.Boolean. (New code should always use boolean rather than java.lang.Boolean.)

MBeanAttributeInfo

public MBeanAttributeInfo(String name,
                          String type,
                          String description,
                          boolean isReadable,
                          boolean isWritable,
                          boolean isIs,
                          Descriptor descriptor)
Constructs an MBeanAttributeInfo object.

Parameters:
name - The name of the attribute.
type - The type or class name of the attribute.
description - A human readable description of the attribute.
isReadable - True if the attribute has a getter method, false otherwise.
isWritable - True if the attribute has a setter method, false otherwise.
isIs - True if this attribute has an "is" getter, false otherwise.
descriptor - The descriptor for the attribute. This may be null which is equivalent to an empty descriptor.
Throws:
IllegalArgumentException - if isIs is true but isReadable is not, or if isIs is true and type is not boolean or java.lang.Boolean. (New code should always use boolean rather than java.lang.Boolean.)
Since:
1.6

MBeanAttributeInfo

public MBeanAttributeInfo(String name,
                          String description,
                          Method getter,
                          Method setter)
                   throws IntrospectionException

This constructor takes the name of a simple attribute, and Method objects for reading and writing the attribute. The Descriptor of the constructed object will include fields contributed by any annotations on the Method objects that contain the DescriptorKey meta-annotation.

Parameters:
name - The programmatic name of the attribute.
description - A human readable description of the attribute.
getter - The method used for reading the attribute value. May be null if the property is write-only.
setter - The method used for writing the attribute value. May be null if the attribute is read-only.
Throws:
IntrospectionException - There is a consistency problem in the definition of this attribute.
Method Detail

clone

public Object clone()

Returns a shallow clone of this instance. The clone is obtained by simply calling super.clone(), thus calling the default native shallow cloning mechanism implemented by Object.clone(). No deeper cloning of any internal field is made.

Since this class is immutable, cloning is chiefly of interest to subclasses.

Overrides:
clone in class Object
Returns:
a clone of this instance.
See Also:
Cloneable

getType

public String getType()
Returns the class name of the attribute.

Returns:
the class name.

isReadable

public boolean isReadable()
Whether the value of the attribute can be read.

Returns:
True if the attribute can be read, false otherwise.

isWritable

public boolean isWritable()
Whether new values can be written to the attribute.

Returns:
True if the attribute can be written to, false otherwise.

isIs

public boolean isIs()
Indicates if this attribute has an "is" getter.

Returns:
true if this attribute has an "is" getter.

toString

public String toString()
Description copied from class: Object
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())

Overrides:
toString in class Object
Returns:
a string representation of the object.

equals

public boolean equals(Object o)
Compare this MBeanAttributeInfo to another.

Overrides:
equals in class MBeanFeatureInfo
Parameters:
o - the object to compare to.
Returns:
true if and only if o is an MBeanAttributeInfo such that its MBeanFeatureInfo.getName(), getType(), MBeanFeatureInfo.getDescription(), isReadable(), isWritable(), and isIs() values are equal (not necessarily identical) to those of this MBeanAttributeInfo.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Description copied from class: Object
Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the Object.equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)

Overrides:
hashCode in class MBeanFeatureInfo
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanConstructorInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MBeanConstructorInfo

java.lang.Object
    extended by  javax.management.MBeanFeatureInfo
        extended by  javax.management.MBeanConstructorInfo
All Implemented Interfaces:
Serializable, Cloneable, DescriptorRead
Direct Known Subclasses:
ModelMBeanConstructorInfo, OpenMBeanConstructorInfoSupport
public class MBeanConstructorInfo
extends MBeanFeatureInfo
implements Cloneable

Describes a constructor exposed by an MBean. Instances of this class are immutable. Subclasses may be mutable but this is not recommended.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.management.MBeanFeatureInfo
description, name
Constructor Summary
MBeanConstructorInfo(String description, Constructor constructor)
Constructs an MBeanConstructorInfo object.
MBeanConstructorInfo(String name, String description, MBeanParameterInfo[] signature)
Constructs an MBeanConstructorInfo object.
MBeanConstructorInfo(String name, String description, MBeanParameterInfo[] signature, Descriptor descriptor)
Constructs an MBeanConstructorInfo object.
Method Summary
Object | clone() Returns a shallow clone of this instance.
boolean | equals(Object o) Compare this MBeanConstructorInfo to another.
MBeanParameterInfo[] | getSignature() Returns the list of parameters for this constructor.
int | hashCode() Returns a hash code value for the object.
String | toString() Returns a string representation of the object.
Methods inherited from class javax.management.MBeanFeatureInfo
getDescription, getDescriptor, getName
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

MBeanConstructorInfo

public MBeanConstructorInfo(String description,
                            Constructor constructor)
Constructs an MBeanConstructorInfo object. The Descriptor of the constructed object will include fields contributed by any annotations on the Constructor object that contain the DescriptorKey meta-annotation.

Parameters:
description - A human readable description of the operation.
constructor - The java.lang.reflect.Constructor object describing the MBean constructor.

MBeanConstructorInfo

public MBeanConstructorInfo(String name,
                            String description,
                            MBeanParameterInfo[] signature)
Constructs an MBeanConstructorInfo object.

Parameters:
name - The name of the constructor.
signature - MBeanParameterInfo objects describing the parameters(arguments) of the constructor. This may be null with the same effect as a zero-length array.
description - A human readable description of the constructor.

MBeanConstructorInfo

public MBeanConstructorInfo(String name,
                            String description,
                            MBeanParameterInfo[] signature,
                            Descriptor descriptor)
Constructs an MBeanConstructorInfo object.

Parameters:
name - The name of the constructor.
signature - MBeanParameterInfo objects describing the parameters(arguments) of the constructor. This may be null with the same effect as a zero-length array.
description - A human readable description of the constructor.
descriptor - The descriptor for the constructor. This may be null which is equivalent to an empty descriptor.
Since:
1.6
Method Detail

clone

public Object clone()

Returns a shallow clone of this instance. The clone is obtained by simply calling super.clone(), thus calling the default native shallow cloning mechanism implemented by Object.clone(). No deeper cloning of any internal field is made.

Since this class is immutable, cloning is chiefly of interest to subclasses.

Overrides:
clone in class Object
Returns:
a clone of this instance.
See Also:
Cloneable

getSignature

public MBeanParameterInfo[] getSignature()

Returns the list of parameters for this constructor. Each parameter is described by an MBeanParameterInfo object.

The returned array is a shallow copy of the internal array, which means that it is a copy of the internal array of references to the MBeanParameterInfo objects but that each referenced MBeanParameterInfo object is not copied.

Returns:
An array of MBeanParameterInfo objects.

toString

public String toString()
Description copied from class: Object
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())

Overrides:
toString in class Object
Returns:
a string representation of the object.

equals

public boolean equals(Object o)
Compare this MBeanConstructorInfo to another.

Overrides:
equals in class MBeanFeatureInfo
Parameters:
o - the object to compare to.
Returns:
true if and only if o is an MBeanConstructorInfo such that its MBeanFeatureInfo.getName(), MBeanFeatureInfo.getDescription(), getSignature(), and MBeanFeatureInfo.getDescriptor() values are equal (not necessarily identical) to those of this MBeanConstructorInfo. Two signature arrays are equal if their elements are pairwise equal.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Description copied from class: Object
Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the Object.equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)

Overrides:
hashCode in class MBeanFeatureInfo
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MBeanException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.MBeanException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
MBeanRegistrationException
public class MBeanException
extends JMException

Represents "user defined" exceptions thrown by MBean methods in the agent. It "wraps" the actual "user defined" exception thrown. This exception will be built by the MBeanServer when a call to an MBean method results in an unknown exception.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
MBeanException(Exception e)
Creates an MBeanException that wraps the actual java.lang.Exception.
MBeanException(Exception e, String message)
Creates an MBeanException that wraps the actual java.lang.Exception with a detail message.
Method Summary
Throwable | getCause() Return the actual Exception thrown.
Exception | getTargetException() Return the actual Exception thrown.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MBeanException

public MBeanException(Exception e)
Creates an MBeanException that wraps the actual java.lang.Exception.

Parameters:
e - the wrapped exception.

MBeanException

public MBeanException(Exception e,
                      String message)
Creates an MBeanException that wraps the actual java.lang.Exception with a detail message.

Parameters:
e - the wrapped exception.
message - the detail message.
Method Detail

getTargetException

public Exception getTargetException()
Return the actual Exception thrown.

Returns:
the wrapped exception.

getCause

public Throwable getCause()
Return the actual Exception thrown.

Overrides:
getCause in class Throwable
Returns:
the wrapped exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanFeatureInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MBeanFeatureInfo

java.lang.Object
    extended by  javax.management.MBeanFeatureInfo
All Implemented Interfaces:
Serializable, DescriptorRead
Direct Known Subclasses:
MBeanAttributeInfo, MBeanConstructorInfo, MBeanNotificationInfo, MBeanOperationInfo, MBeanParameterInfo
public class MBeanFeatureInfo
extends Object
implements Serializable, DescriptorRead

Provides general information for an MBean descriptor object. The feature described can be an attribute, an operation, a parameter, or a notification. Instances of this class are immutable. Subclasses may be mutable but this is not recommended.

Since:
1.5
See Also:
Serialized Form

Field Summary
protected String | description The human-readable description of the feature.
protected String | name The name of the feature.
Constructor Summary
MBeanFeatureInfo(String name, String description)
Constructs an MBeanFeatureInfo object.
MBeanFeatureInfo(String name, String description, Descriptor descriptor)
Constructs an MBeanFeatureInfo object.
Method Summary
boolean | equals(Object o) Compare this MBeanFeatureInfo to another.
String | getDescription() Returns the human-readable description of the feature.
Descriptor | getDescriptor() Returns the descriptor for the feature.
String | getName() Returns the name of the feature.
int | hashCode() Returns a hash code value for the object.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

name

protected String name
The name of the feature. It is recommended that subclasses call getName() rather than reading this field, and that they not change it.

description

protected String description
The human-readable description of the feature. It is recommended that subclasses call getDescription() rather than reading this field, and that they not change it.

Constructor Detail

MBeanFeatureInfo

public MBeanFeatureInfo(String name,
                        String description)
Constructs an MBeanFeatureInfo object. This constructor is equivalent to MBeanFeatureInfo(name, description, (Descriptor) null.

Parameters:
name - The name of the feature.
description - A human readable description of the feature.

MBeanFeatureInfo

public MBeanFeatureInfo(String name,
                        String description,
                        Descriptor descriptor)
Constructs an MBeanFeatureInfo object.

Parameters:
name - The name of the feature.
description - A human readable description of the feature.
descriptor - The descriptor for the feature. This may be null which is equivalent to an empty descriptor.
Since:
1.6
Method Detail

getName

public String getName()
Returns the name of the feature.

Returns:
the name of the feature.

getDescription

public String getDescription()
Returns the human-readable description of the feature.

Returns:
the human-readable description of the feature.

getDescriptor

public Descriptor getDescriptor()
Returns the descriptor for the feature. Changing the returned value will have no affect on the original descriptor.

Specified by:
getDescriptor in interface DescriptorRead
Returns:
a descriptor that is either immutable or a copy of the original.
Since:
1.6

equals

public boolean equals(Object o)
Compare this MBeanFeatureInfo to another.

Overrides:
equals in class Object
Parameters:
o - the object to compare to.
Returns:
true if and only if o is an MBeanFeatureInfo such that its getName(), getDescription(), and getDescriptor() values are equal (not necessarily identical) to those of this MBeanFeatureInfo.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Description copied from class: Object
Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the Object.equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MBeanInfo

java.lang.Object
    extended by  javax.management.MBeanInfo
All Implemented Interfaces:
Serializable, Cloneable, DescriptorRead
Direct Known Subclasses:
ModelMBeanInfoSupport, OpenMBeanInfoSupport
public class MBeanInfo
extends Object
implements Cloneable, Serializable, DescriptorRead

Describes the management interface exposed by an MBean; that is, the set of attributes and operations which are available for management operations. Instances of this class are immutable. Subclasses may be mutable but this is not recommended.

The contents of the MBeanInfo for a Dynamic MBean are determined by its getMBeanInfo() method. This includes Open MBeans and Model MBeans, which are kinds of Dynamic MBeans.

The contents of the MBeanInfo for a Standard MBean are determined by the MBean server as follows:

  • getClassName() returns the Java class name of the MBean object;
  • getConstructors() returns the list of all public constructors in that object;
  • getAttributes() returns the list of all attributes whose existence is deduced from the presence in the MBean interface of a getName, isName, or setName method that conforms to the conventions for Standard MBeans;
  • getOperations() returns the list of all methods in the MBean interface that do not represent attributes;
  • getNotifications() returns an empty array if the MBean does not implement the NotificationBroadcaster interface, otherwise the result of calling NotificationBroadcaster.getNotificationInfo() on it;
  • getDescriptor() returns a descriptor containing the contents of any descriptor annotations in the MBean interface.

The description returned by getDescription() and the descriptions of the contained attributes and operations are determined by the corresponding Description annotations if any; otherwise their contents are not specified.

The remaining details of the MBeanInfo for a Standard MBean are not specified. This includes the description of any contained constructors, and notifications; the names of parameters to constructors and operations; and the descriptions of constructor parameters.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
MBeanInfo(String className, String description, MBeanAttributeInfo[] attributes, MBeanConstructorInfo[] constructors, MBeanOperationInfo[] operations, MBeanNotificationInfo[] notifications)
Constructs an MBeanInfo.
MBeanInfo(String className, String description, MBeanAttributeInfo[] attributes, MBeanConstructorInfo[] constructors, MBeanOperationInfo[] operations, MBeanNotificationInfo[] notifications, Descriptor descriptor)
Constructs an MBeanInfo.
Method Summary
Object | clone() Returns a shallow clone of this instance.
boolean | equals(Object o) Compare this MBeanInfo to another.
MBeanAttributeInfo[] | getAttributes() Returns the list of attributes exposed for management.
String | getClassName() Returns the name of the Java class of the MBean described by this MBeanInfo.
MBeanConstructorInfo[] | getConstructors() Returns the list of the public constructors of the MBean.
String | getDescription() Returns a human readable description of the MBean.
Descriptor | getDescriptor() Get the descriptor of this MBeanInfo.
MBeanNotificationInfo[] | getNotifications() Returns the list of the notifications emitted by the MBean.
MBeanOperationInfo[] | getOperations() Returns the list of operations of the MBean.
int | hashCode() Returns a hash code value for the object.
String | toString() Returns a string representation of the object.
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

MBeanInfo

public MBeanInfo(String className,
                 String description,
                 MBeanAttributeInfo[] attributes,
                 MBeanConstructorInfo[] constructors,
                 MBeanOperationInfo[] operations,
                 MBeanNotificationInfo[] notifications)
          throws IllegalArgumentException
Constructs an MBeanInfo.

Parameters:
className - The name of the Java class of the MBean described by this MBeanInfo. This value may be any syntactically legal Java class name. It does not have to be a Java class known to the MBean server or to the MBean's ClassLoader. If it is a Java class known to the MBean's ClassLoader, it is recommended but not required that the class's public methods include those that would appear in a Standard MBean implementing the attributes and operations in this MBeanInfo.
description - A human readable description of the MBean (optional).
attributes - The list of exposed attributes of the MBean. This may be null with the same effect as a zero-length array.
constructors - The list of public constructors of the MBean. This may be null with the same effect as a zero-length array.
operations - The list of operations of the MBean. This may be null with the same effect as a zero-length array.
notifications - The list of notifications emitted. This may be null with the same effect as a zero-length array.
Throws:
IllegalArgumentException

MBeanInfo

public MBeanInfo(String className,
                 String description,
                 MBeanAttributeInfo[] attributes,
                 MBeanConstructorInfo[] constructors,
                 MBeanOperationInfo[] operations,
                 MBeanNotificationInfo[] notifications,
                 Descriptor descriptor)
          throws IllegalArgumentException
Constructs an MBeanInfo.

Parameters:
className - The name of the Java class of the MBean described by this MBeanInfo. This value may be any syntactically legal Java class name. It does not have to be a Java class known to the MBean server or to the MBean's ClassLoader. If it is a Java class known to the MBean's ClassLoader, it is recommended but not required that the class's public methods include those that would appear in a Standard MBean implementing the attributes and operations in this MBeanInfo.
description - A human readable description of the MBean (optional).
attributes - The list of exposed attributes of the MBean. This may be null with the same effect as a zero-length array.
constructors - The list of public constructors of the MBean. This may be null with the same effect as a zero-length array.
operations - The list of operations of the MBean. This may be null with the same effect as a zero-length array.
notifications - The list of notifications emitted. This may be null with the same effect as a zero-length array.
descriptor - The descriptor for the MBean. This may be null which is equivalent to an empty descriptor.
Throws:
IllegalArgumentException
Since:
1.6
Method Detail

clone

public Object clone()

Returns a shallow clone of this instance. The clone is obtained by simply calling super.clone(), thus calling the default native shallow cloning mechanism implemented by Object.clone(). No deeper cloning of any internal field is made.

Since this class is immutable, the clone method is chiefly of interest to subclasses.

Overrides:
clone in class Object
Returns:
a clone of this instance.
See Also:
Cloneable

getClassName

public String getClassName()
Returns the name of the Java class of the MBean described by this MBeanInfo.

Returns:
the class name.

getDescription

public String getDescription()
Returns a human readable description of the MBean.

Returns:
the description.

getAttributes

public MBeanAttributeInfo[] getAttributes()
Returns the list of attributes exposed for management. Each attribute is described by an MBeanAttributeInfo object. The returned array is a shallow copy of the internal array, which means that it is a copy of the internal array of references to the MBeanAttributeInfo objects but that each referenced MBeanAttributeInfo object is not copied.

Returns:
An array of MBeanAttributeInfo objects.

getOperations

public MBeanOperationInfo[] getOperations()
Returns the list of operations of the MBean. Each operation is described by an MBeanOperationInfo object. The returned array is a shallow copy of the internal array, which means that it is a copy of the internal array of references to the MBeanOperationInfo objects but that each referenced MBeanOperationInfo object is not copied.

Returns:
An array of MBeanOperationInfo objects.

getConstructors

public MBeanConstructorInfo[] getConstructors()

Returns the list of the public constructors of the MBean. Each constructor is described by an MBeanConstructorInfo object.

The returned array is a shallow copy of the internal array, which means that it is a copy of the internal array of references to the MBeanConstructorInfo objects but that each referenced MBeanConstructorInfo object is not copied.

The returned list is not necessarily exhaustive. That is, the MBean may have a public constructor that is not in the list. In this case, the MBean server can construct another instance of this MBean's class using that constructor, even though it is not listed here.

Returns:
An array of MBeanConstructorInfo objects.

getNotifications

public MBeanNotificationInfo[] getNotifications()
Returns the list of the notifications emitted by the MBean. Each notification is described by an MBeanNotificationInfo object. The returned array is a shallow copy of the internal array, which means that it is a copy of the internal array of references to the MBeanNotificationInfo objects but that each referenced MBeanNotificationInfo object is not copied.

Returns:
An array of MBeanNotificationInfo objects.

getDescriptor

public Descriptor getDescriptor()
Get the descriptor of this MBeanInfo. Changing the returned value will have no affect on the original descriptor.

Specified by:
getDescriptor in interface DescriptorRead
Returns:
a descriptor that is either immutable or a copy of the original.
Since:
1.6

toString

public String toString()
Description copied from class: Object
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())

Overrides:
toString in class Object
Returns:
a string representation of the object.

equals

public boolean equals(Object o)

Compare this MBeanInfo to another. Two MBeanInfo objects are equal if and only if they return equal values for getClassName(), for getDescription(), and for getDescriptor(), and the arrays returned by the two objects for getAttributes(), getOperations(), getConstructors(), and getNotifications() are pairwise equal. Here "equal" means Object.equals(Object), not identity.

If two MBeanInfo objects return the same values in one of their arrays but in a different order then they are not equal.

Overrides:
equals in class Object
Parameters:
o - the object to compare to.
Returns:
true if and only if o is an MBeanInfo that is equal to this one according to the rules above.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Description copied from class: Object
Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the Object.equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanNotificationInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MBeanNotificationInfo

java.lang.Object
    extended by  javax.management.MBeanFeatureInfo
        extended by  javax.management.MBeanNotificationInfo
All Implemented Interfaces:
Serializable, Cloneable, DescriptorRead
Direct Known Subclasses:
ModelMBeanNotificationInfo
public class MBeanNotificationInfo
extends MBeanFeatureInfo
implements Cloneable

The MBeanNotificationInfo class is used to describe the characteristics of the different notification instances emitted by an MBean, for a given Java class of notification. If an MBean emits notifications that can be instances of different Java classes, then the metadata for that MBean should provide an MBeanNotificationInfo object for each of these notification Java classes.

Instances of this class are immutable. Subclasses may be mutable but this is not recommended.

This class extends javax.management.MBeanFeatureInfo and thus provides name and description fields. The name field should be the fully qualified Java class name of the notification objects described by this class.

The getNotifTypes method returns an array of strings containing the notification types that the MBean may emit. The notification type is a dot-notation string which describes what the emitted notification is about, not the Java class of the notification. A single generic notification class can be used to send notifications of several types. All of these types are returned in the string array result of the getNotifTypes method.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.management.MBeanFeatureInfo
description, name
Constructor Summary
MBeanNotificationInfo(String[] notifTypes, String name, String description)
Constructs an MBeanNotificationInfo object.
MBeanNotificationInfo(String[] notifTypes, String name, String description, Descriptor descriptor)
Constructs an MBeanNotificationInfo object.
Method Summary
Object | clone() Returns a shallow clone of this instance.
boolean | equals(Object o) Compare this MBeanNotificationInfo to another.
String[] | getNotifTypes() Returns the array of strings (in dot notation) containing the notification types that the MBean may emit.
int | hashCode() Returns a hash code value for the object.
String | toString() Returns a string representation of the object.
Methods inherited from class javax.management.MBeanFeatureInfo
getDescription, getDescriptor, getName
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

MBeanNotificationInfo

public MBeanNotificationInfo(String[] notifTypes,
                             String name,
                             String description)
Constructs an MBeanNotificationInfo object.

Parameters:
notifTypes - The array of strings (in dot notation) containing the notification types that the MBean may emit. This may be null with the same effect as a zero-length array.
name - The fully qualified Java class name of the described notifications.
description - A human readable description of the data.

MBeanNotificationInfo

public MBeanNotificationInfo(String[] notifTypes,
                             String name,
                             String description,
                             Descriptor descriptor)
Constructs an MBeanNotificationInfo object.

Parameters:
notifTypes - The array of strings (in dot notation) containing the notification types that the MBean may emit. This may be null with the same effect as a zero-length array.
name - The fully qualified Java class name of the described notifications.
description - A human readable description of the data.
descriptor - The descriptor for the notifications. This may be null which is equivalent to an empty descriptor.
Since:
1.6
Method Detail

clone

public Object clone()
Returns a shallow clone of this instance. The clone is obtained by simply calling super.clone(), thus calling the default native shallow cloning mechanism implemented by Object.clone(). No deeper cloning of any internal field is made.

Overrides:
clone in class Object
Returns:
a clone of this instance.
See Also:
Cloneable

getNotifTypes

public String[] getNotifTypes()
Returns the array of strings (in dot notation) containing the notification types that the MBean may emit.

Returns:
the array of strings. Changing the returned array has no effect on this MBeanNotificationInfo.

toString

public String toString()
Description copied from class: Object
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())

Overrides:
toString in class Object
Returns:
a string representation of the object.

equals

public boolean equals(Object o)
Compare this MBeanNotificationInfo to another.

Overrides:
equals in class MBeanFeatureInfo
Parameters:
o - the object to compare to.
Returns:
true if and only if o is an MBeanNotificationInfo such that its MBeanFeatureInfo.getName(), MBeanFeatureInfo.getDescription(), MBeanFeatureInfo.getDescriptor(), and getNotifTypes() values are equal (not necessarily identical) to those of this MBeanNotificationInfo. Two notification type arrays are equal if their corresponding elements are equal. They are not equal if they have the same elements but in a different order.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Description copied from class: Object
Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the Object.equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)

Overrides:
hashCode in class MBeanFeatureInfo
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanOperationInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MBeanOperationInfo

java.lang.Object
    extended by  javax.management.MBeanFeatureInfo
        extended by  javax.management.MBeanOperationInfo
All Implemented Interfaces:
Serializable, Cloneable, DescriptorRead
Direct Known Subclasses:
ModelMBeanOperationInfo, OpenMBeanOperationInfoSupport
public class MBeanOperationInfo
extends MBeanFeatureInfo
implements Cloneable

Describes a management operation exposed by an MBean. Instances of this class are immutable. Subclasses may be mutable but this is not recommended.

Since:
1.5
See Also:
Serialized Form

Field Summary
static int | ACTION Indicates that the operation is a write-like, and would modify the MBean in some way, typically by writing some value or changing a configuration.
static int | ACTION_INFO Indicates that the operation is both read-like and write-like.
static int | INFO Indicates that the operation is read-like, it basically returns information.
static int | UNKNOWN Indicates that the operation has an "unknown" nature.
Fields inherited from class javax.management.MBeanFeatureInfo
description, name
Constructor Summary
MBeanOperationInfo(String description, Method method)
Constructs an MBeanOperationInfo object.
MBeanOperationInfo(String name, String description, MBeanParameterInfo[] signature, String type, int impact)
Constructs an MBeanOperationInfo object.
MBeanOperationInfo(String name, String description, MBeanParameterInfo[] signature, String type, int impact, Descriptor descriptor)
Constructs an MBeanOperationInfo object.
Method Summary
Object | clone() Returns a shallow clone of this instance.
boolean | equals(Object o) Compare this MBeanOperationInfo to another.
int | getImpact() Returns the impact of the method, one of INFO, ACTION, ACTION_INFO, UNKNOWN.
String | getReturnType() Returns the type of the method's return value.
MBeanParameterInfo[] | getSignature() Returns the list of parameters for this operation.
int | hashCode() Returns a hash code value for the object.
String | toString() Returns a string representation of the object.
Methods inherited from class javax.management.MBeanFeatureInfo
getDescription, getDescriptor, getName
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

INFO

public static final int INFO
Indicates that the operation is read-like, it basically returns information.

See Also:
Constant Field Values

ACTION

public static final int ACTION
Indicates that the operation is a write-like, and would modify the MBean in some way, typically by writing some value or changing a configuration.

See Also:
Constant Field Values

ACTION_INFO

public static final int ACTION_INFO
Indicates that the operation is both read-like and write-like.

See Also:
Constant Field Values

UNKNOWN

public static final int UNKNOWN
Indicates that the operation has an "unknown" nature.

See Also:
Constant Field Values
Constructor Detail

MBeanOperationInfo

public MBeanOperationInfo(String description,
                          Method method)
Constructs an MBeanOperationInfo object. The Descriptor of the constructed object will include fields contributed by any annotations on the Method object that contain the DescriptorKey meta-annotation.

Parameters:
method - The java.lang.reflect.Method object describing the MBean operation.
description - A human readable description of the operation.

MBeanOperationInfo

public MBeanOperationInfo(String name,
                          String description,
                          MBeanParameterInfo[] signature,
                          String type,
                          int impact)
Constructs an MBeanOperationInfo object.

Parameters:
name - The name of the method.
description - A human readable description of the operation.
signature - MBeanParameterInfo objects describing the parameters(arguments) of the method. This may be null with the same effect as a zero-length array.
type - The type of the method's return value.
impact - The impact of the method, one of INFO, ACTION, ACTION_INFO, UNKNOWN.

MBeanOperationInfo

public MBeanOperationInfo(String name,
                          String description,
                          MBeanParameterInfo[] signature,
                          String type,
                          int impact,
                          Descriptor descriptor)
Constructs an MBeanOperationInfo object.

Parameters:
name - The name of the method.
description - A human readable description of the operation.
signature - MBeanParameterInfo objects describing the parameters(arguments) of the method. This may be null with the same effect as a zero-length array.
type - The type of the method's return value.
impact - The impact of the method, one of INFO, ACTION, ACTION_INFO, UNKNOWN.
descriptor - The descriptor for the operation. This may be null which is equivalent to an empty descriptor.
Since:
1.6
Method Detail

clone

public Object clone()

Returns a shallow clone of this instance. The clone is obtained by simply calling super.clone(), thus calling the default native shallow cloning mechanism implemented by Object.clone(). No deeper cloning of any internal field is made.

Since this class is immutable, cloning is chiefly of interest to subclasses.

Overrides:
clone in class Object
Returns:
a clone of this instance.
See Also:
Cloneable

getReturnType

public String getReturnType()
Returns the type of the method's return value.

Returns:
the return type.

getSignature

public MBeanParameterInfo[] getSignature()

Returns the list of parameters for this operation. Each parameter is described by an MBeanParameterInfo object.

The returned array is a shallow copy of the internal array, which means that it is a copy of the internal array of references to the MBeanParameterInfo objects but that each referenced MBeanParameterInfo object is not copied.

Returns:
An array of MBeanParameterInfo objects.

getImpact

public int getImpact()
Returns the impact of the method, one of INFO, ACTION, ACTION_INFO, UNKNOWN.

Returns:
the impact code.

toString

public String toString()
Description copied from class: Object
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())

Overrides:
toString in class Object
Returns:
a string representation of the object.

equals

public boolean equals(Object o)
Compare this MBeanOperationInfo to another.

Overrides:
equals in class MBeanFeatureInfo
Parameters:
o - the object to compare to.
Returns:
true if and only if o is an MBeanOperationInfo such that its MBeanFeatureInfo.getName(), getReturnType(), MBeanFeatureInfo.getDescription(), getImpact(), MBeanFeatureInfo.getDescriptor() and getSignature() values are equal (not necessarily identical) to those of this MBeanConstructorInfo. Two signature arrays are equal if their elements are pairwise equal.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Description copied from class: Object
Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the Object.equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)

Overrides:
hashCode in class MBeanFeatureInfo
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanParameterInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MBeanParameterInfo

java.lang.Object
    extended by  javax.management.MBeanFeatureInfo
        extended by  javax.management.MBeanParameterInfo
All Implemented Interfaces:
Serializable, Cloneable, DescriptorRead
Direct Known Subclasses:
OpenMBeanParameterInfoSupport
public class MBeanParameterInfo
extends MBeanFeatureInfo
implements Cloneable

Describes an argument of an operation exposed by an MBean. Instances of this class are immutable. Subclasses may be mutable but this is not recommended.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.management.MBeanFeatureInfo
description, name
Constructor Summary
MBeanParameterInfo(String name, String type, String description)
Constructs an MBeanParameterInfo object.
MBeanParameterInfo(String name, String type, String description, Descriptor descriptor)
Constructs an MBeanParameterInfo object.
Method Summary
Object | clone() Returns a shallow clone of this instance.
boolean | equals(Object o) Compare this MBeanParameterInfo to another.
String | getType() Returns the type or class name of the data.
int | hashCode() Returns a hash code value for the object.
String | toString() Returns a string representation of the object.
Methods inherited from class javax.management.MBeanFeatureInfo
getDescription, getDescriptor, getName
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

MBeanParameterInfo

public MBeanParameterInfo(String name,
                          String type,
                          String description)
Constructs an MBeanParameterInfo object.

Parameters:
name - The name of the data
type - The type or class name of the data
description - A human readable description of the data. Optional.

MBeanParameterInfo

public MBeanParameterInfo(String name,
                          String type,
                          String description,
                          Descriptor descriptor)
Constructs an MBeanParameterInfo object.

Parameters:
name - The name of the data
type - The type or class name of the data
description - A human readable description of the data. Optional.
descriptor - The descriptor for the operation. This may be null which is equivalent to an empty descriptor.
Since:
1.6
Method Detail

clone

public Object clone()

Returns a shallow clone of this instance. The clone is obtained by simply calling super.clone(), thus calling the default native shallow cloning mechanism implemented by Object.clone(). No deeper cloning of any internal field is made.

Since this class is immutable, cloning is chiefly of interest to subclasses.

Overrides:
clone in class Object
Returns:
a clone of this instance.
See Also:
Cloneable

getType

public String getType()
Returns the type or class name of the data.

Returns:
the type string.

toString

public String toString()
Description copied from class: Object
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())

Overrides:
toString in class Object
Returns:
a string representation of the object.

equals

public boolean equals(Object o)
Compare this MBeanParameterInfo to another.

Overrides:
equals in class MBeanFeatureInfo
Parameters:
o - the object to compare to.
Returns:
true if and only if o is an MBeanParameterInfo such that its MBeanFeatureInfo.getName(), getType(), MBeanFeatureInfo.getDescriptor(), and MBeanFeatureInfo.getDescription() values are equal (not necessarily identical) to those of this MBeanParameterInfo.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Description copied from class: Object
Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the Object.equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)

Overrides:
hashCode in class MBeanFeatureInfo
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanPermission

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MBeanPermission

java.lang.Object
    extended by  java.security.Permission
        extended by  javax.management.MBeanPermission
All Implemented Interfaces:
Serializable, Guard
public class MBeanPermission
extends Permission

Permission controlling access to MBeanServer operations. If a security manager has been set using System.setSecurityManager(java.lang.SecurityManager), most operations on the MBean Server require that the caller's permissions imply an MBeanPermission appropriate for the operation. This is described in detail in the documentation for the MBeanServer interface.

As with other Permission objects, an MBeanPermission can represent either a permission that you have or a permission that you need. When a sensitive operation is being checked for permission, an MBeanPermission is constructed representing the permission you need. The operation is only allowed if the permissions you have imply the permission you need.

An MBeanPermission contains four items of information:

  • The action. For a permission you need, this is one of the actions in the list below. For a permission you have, this is a comma-separated list of those actions, or *, representing all actions.

    The action is returned by getActions().

  • The class name.

    For a permission you need, this is the class name of an MBean you are accessing, as returned by MBeanServer.getMBeanInfo(name).getClassName(). Certain operations do not reference a class name, in which case the class name is null.

    For a permission you have, this is either empty or a class name pattern. A class name pattern is a string following the Java conventions for dot-separated class names. It may end with ".*" meaning that the permission grants access to any class that begins with the string preceding ".*". For instance, "javax.management.*" grants access to javax.management.MBeanServerDelegate and javax.management.timer.Timer, among other classes.

    A class name pattern can also be empty or the single character "*", both of which grant access to any class.

  • The member.

    For a permission you need, this is the name of the attribute or operation you are accessing. For operations that do not reference an attribute or operation, the member is null.

    For a permission you have, this is either the name of an attribute or operation you can access, or it is empty or the single character "*", both of which grant access to any member.

  • The object name.

    For a permission you need, this is the ObjectName of the MBean you are accessing. For operations that do not reference a single MBean, it is null. It is never an object name pattern.

    For a permission you have, this is the ObjectName of the MBean or MBeans you can access. It may be an object name pattern to grant access to all MBeans whose names match the pattern. It may also be empty, which grants access to all MBeans whatever their name.

If you have an MBeanPermission, it allows operations only if all four of the items match.

The class name, member, and object name can be written together as a single string, which is the name of this permission. The name of the permission is the string returned by getName(). The format of the string is:

className#member[objectName]

The object name is written using the usual syntax for ObjectName. It may contain any legal characters, including ]. It is terminated by a ] character that is the last character in the string.

One or more of the className, member, or objectName may be omitted. If the member is omitted, the # may be too (but does not have to be). If the objectName is omitted, the [] may be too (but does not have to be). It is not legal to omit all three items, that is to have a name that is the empty string.

One or more of the className, member, or objectName may be the character "-", which is equivalent to a null value. A null value is implied by any value (including another null value) but does not imply any other value.

The possible actions are these:

  • addNotificationListener
  • getAttribute
  • getClassLoader
  • getClassLoaderFor
  • getClassLoaderRepository
  • getDomains
  • getMBeanInfo
  • getObjectInstance
  • instantiate
  • invoke
  • isInstanceOf
  • queryMBeans
  • queryNames
  • registerMBean
  • removeNotificationListener
  • setAttribute
  • unregisterMBean

In a comma-separated list of actions, spaces are allowed before and after each action.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
MBeanPermission(String name, String actions)
Create a new MBeanPermission object with the specified target name and actions.
MBeanPermission(String className, String member, ObjectName objectName, String actions)
Create a new MBeanPermission object with the specified target name (class name, member, object name) and actions.
Method Summary
boolean | equals(Object obj) Checks two MBeanPermission objects for equality.
String | getActions() Returns the "canonical string representation" of the actions.
int | hashCode() Returns the hash code value for this object.
boolean | implies(Permission p) Checks if this MBeanPermission object "implies" the specified permission.
Methods inherited from class java.security.Permission
checkGuard, getName, newPermissionCollection, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

MBeanPermission

public MBeanPermission(String name,
                       String actions)

Create a new MBeanPermission object with the specified target name and actions.

The target name is of the form "className#member[objectName]" where each part is optional. It must not be empty or null.

The actions parameter contains a comma-separated list of the desired actions granted on the target name. It must not be empty or null.

Parameters:
name - the triplet "className#member[objectName]".
actions - the action string.
Throws:
IllegalArgumentException - if the name or actions is invalid.

MBeanPermission

public MBeanPermission(String className,
                       String member,
                       ObjectName objectName,
                       String actions)

Create a new MBeanPermission object with the specified target name (class name, member, object name) and actions.

The class name, member and object name parameters define a target name of the form "className#member[objectName]" where each part is optional. This will be the result of Permission.getName() on the resultant MBeanPermission.

The actions parameter contains a comma-separated list of the desired actions granted on the target name. It must not be empty or null.

Parameters:
className - the class name to which this permission applies. May be null or "-", which represents a class name that is implied by any class name but does not imply any other class name.
member - the member to which this permission applies. May be null or "-", which represents a member that is implied by any member but does not imply any other member.
objectName - the object name to which this permission applies. May be null, which represents an object name that is implied by any object name but does not imply any other object name.
actions - the action string.
Method Detail

getActions

public String getActions()
Returns the "canonical string representation" of the actions. That is, this method always returns present actions in alphabetical order.

Specified by:
getActions in class Permission
Returns:
the canonical string representation of the actions.

hashCode

public int hashCode()
Returns the hash code value for this object.

Specified by:
hashCode in class Permission
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

implies

public boolean implies(Permission p)

Checks if this MBeanPermission object "implies" the specified permission.

More specifically, this method returns true if:

  • p is an instance of MBeanPermission; and
  • p has a null className or p's className matches this object's className; and
  • p has a null member or p's member matches this object's member; and
  • p has a null object name or p's object name matches this object's object name; and
  • p's actions are a subset of this object's actions

If this object's className is "*", p's className always matches it. If it is "a.*", p's className matches it if it begins with "a.".

If this object's member is "*", p's member always matches it.

If this object's objectName n1 is an object name pattern, p's objectName n2 matches it if n1.equals(n2) or if n1.apply(n2).

A permission that includes the queryMBeans action is considered to include queryNames as well.

Specified by:
implies in class Permission
Parameters:
p - the permission to check against.
Returns:
true if the specified permission is implied by this object, false if not.

equals

public boolean equals(Object obj)
Checks two MBeanPermission objects for equality. Checks that obj is an MBeanPermission, and has the same name and actions as this object.

Specified by:
equals in class Permission
Parameters:
obj - the object we are testing for equality with this object.
Returns:
true if obj is an MBeanPermission, and has the same name and actions as this MBeanPermission object.
See Also:
Object.hashCode(), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanRegistration

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Interface MBeanRegistration

All Known Implementing Classes:
CounterMonitor, GaugeMonitor, JMXConnectorServer, MLet, Monitor, PrivateMLet, RelationService, RelationSupport, RequiredModelMBean, RMIConnectorServer, StandardEmitterMBean, StandardMBean, StringMonitor, Timer
public interface MBeanRegistration

Can be implemented by an MBean in order to carry out operations before and after being registered or unregistered from the MBean server.

Since:
1.5

Method Summary
void | postDeregister() Allows the MBean to perform any operations needed after having been unregistered in the MBean server.
void | postRegister(Boolean registrationDone) Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.
void | preDeregister() Allows the MBean to perform any operations it needs before being unregistered by the MBean server.
ObjectName | preRegister(MBeanServer server, ObjectName name) Allows the MBean to perform any operations it needs before being registered in the MBean server.

Method Detail

preRegister

ObjectName preRegister(MBeanServer server,
                       ObjectName name)
                       throws Exception
Allows the MBean to perform any operations it needs before being registered in the MBean server. If the name of the MBean is not specified, the MBean can provide a name for its registration. If any exception is raised, the MBean will not be registered in the MBean server.

Parameters:
server - The MBean server in which the MBean will be registered.
name - The object name of the MBean. This name is null if the name parameter to one of the createMBean or registerMBean methods in the MBeanServer interface is null. In that case, this method must return a non-null ObjectName for the new MBean.
Returns:
The name under which the MBean is to be registered. This value must not be null. If the name parameter is not null, it will usually but not necessarily be the returned value.
Throws:
Exception - This exception will be caught by the MBean server and re-thrown as an MBeanRegistrationException.

postRegister

void postRegister(Boolean registrationDone)
Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.

Parameters:
registrationDone - Indicates whether or not the MBean has been successfully registered in the MBean server. The value false means that the registration phase has failed.

preDeregister

void preDeregister()
                   throws Exception
Allows the MBean to perform any operations it needs before being unregistered by the MBean server.

Throws:
Exception - This exception will be caught by the MBean server and re-thrown as an MBeanRegistrationException.

postDeregister

void postDeregister()
Allows the MBean to perform any operations needed after having been unregistered in the MBean server.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanRegistrationException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MBeanRegistrationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.MBeanException
                    extended by  javax.management.MBeanRegistrationException
All Implemented Interfaces:
Serializable
public class MBeanRegistrationException
extends MBeanException

Wraps exceptions thrown by the preRegister(), preDeregister() methods of the MBeanRegistration interface.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
MBeanRegistrationException(Exception e)
Creates an MBeanRegistrationException that wraps the actual java.lang.Exception.
MBeanRegistrationException(Exception e, String message)
Creates an MBeanRegistrationException that wraps the actual java.lang.Exception with a detailed message.
Method Summary
Methods inherited from class javax.management.MBeanException
getCause, getTargetException
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MBeanRegistrationException

public MBeanRegistrationException(Exception e)
Creates an MBeanRegistrationException that wraps the actual java.lang.Exception.

Parameters:
e - the wrapped exception.

MBeanRegistrationException

public MBeanRegistrationException(Exception e,
                                  String message)
Creates an MBeanRegistrationException that wraps the actual java.lang.Exception with a detailed message.

Parameters:
e - the wrapped exception.
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanServer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Interface MBeanServer

All Superinterfaces:
MBeanServerConnection
All Known Subinterfaces:
MBeanServerForwarder
public interface MBeanServer
extends MBeanServerConnection

This is the interface for MBean manipulation on the agent side. It contains the methods necessary for the creation, registration, and deletion of MBeans as well as the access methods for registered MBeans. This is the core component of the JMX infrastructure.

User code does not usually implement this interface. Instead, an object that implements this interface is obtained with one of the methods in the MBeanServerFactory class.

Every MBean which is added to the MBean server becomes manageable: its attributes and operations become remotely accessible through the connectors/adaptors connected to that MBean server. A Java object cannot be registered in the MBean server unless it is a JMX compliant MBean.

When an MBean is registered or unregistered in the MBean server a MBeanServerNotification Notification is emitted. To register an object as listener to MBeanServerNotifications you should call the MBean server method addNotificationListener with ObjectName the ObjectName of the MBeanServerDelegate. This ObjectName is:
JMImplementation:type=MBeanServerDelegate.

An object obtained from the createMBeanServer or newMBeanServer methods of the MBeanServerFactory class applies security checks to its methods, as follows.

First, if there is no security manager (System.getSecurityManager() is null), then an implementation of this interface is free not to make any checks.

Assuming that there is a security manager, or that the implementation chooses to make checks anyway, the checks are made as detailed below. In what follows, className is the string returned by MBeanInfo.getClassName() for the target MBean.

If a security check fails, the method throws SecurityException.

For methods that can throw InstanceNotFoundException, this exception is thrown for a non-existent MBean, regardless of permissions. This is because a non-existent MBean has no className.

  • For the invoke method, the caller's permissions must imply MBeanPermission(className, operationName, name, "invoke").

  • For the getAttribute method, the caller's permissions must imply MBeanPermission(className, attribute, name, "getAttribute").

  • For the getAttributes method, the caller's permissions must imply MBeanPermission(className, null, name, "getAttribute"). Additionally, for each attribute a in the AttributeList, if the caller's permissions do not imply MBeanPermission(className, a, name, "getAttribute"), the MBean server will behave as if that attribute had not been in the supplied list.

  • For the setAttribute method, the caller's permissions must imply MBeanPermission(className, attrName, name, "setAttribute"), where attrName is attribute.getName().

  • For the setAttributes method, the caller's permissions must imply MBeanPermission(className, null, name, "setAttribute"). Additionally, for each attribute a in the AttributeList, if the caller's permissions do not imply MBeanPermission(className, a, name, "setAttribute"), the MBean server will behave as if that attribute had not been in the supplied list.

  • For the addNotificationListener methods, the caller's permissions must imply MBeanPermission(className, null, name, "addNotificationListener").

  • For the removeNotificationListener methods, the caller's permissions must imply MBeanPermission(className, null, name, "removeNotificationListener").

  • For the getMBeanInfo method, the caller's permissions must imply MBeanPermission(className, null, name, "getMBeanInfo").

  • For the getObjectInstance method, the caller's permissions must imply MBeanPermission(className, null, name, "getObjectInstance").

  • For the isInstanceOf method, the caller's permissions must imply MBeanPermission(className, null, name, "isInstanceOf").

  • For the queryMBeans method, the caller's permissions must imply MBeanPermission(null, null, name, "queryMBeans"). Additionally, for each MBean that matches name, if the caller's permissions do not imply MBeanPermission(className, null, name, "queryMBeans"), the MBean server will behave as if that MBean did not exist.

    Certain query elements perform operations on the MBean server. If the caller does not have the required permissions for a given MBean, that MBean will not be included in the result of the query. The standard query elements that are affected are Query.attr(String), Query.attr(String,String), and Query.classattr().

  • For the queryNames method, the checks are the same as for queryMBeans except that "queryNames" is used instead of "queryMBeans" in the MBeanPermission objects. Note that a "queryMBeans" permission implies the corresponding "queryNames" permission.

  • For the getDomains method, the caller's permissions must imply MBeanPermission(null, null, name, "getDomains"). Additionally, for each domain d in the returned array, if the caller's permissions do not imply MBeanPermission(null, null, new ObjectName("d:x=x"), "getDomains"), the domain is eliminated from the array. Here, x=x is any key=value pair, needed to satisfy ObjectName's constructor but not otherwise relevant.

  • For the getClassLoader method, the caller's permissions must imply MBeanPermission(className, null, loaderName, "getClassLoader").

  • For the getClassLoaderFor method, the caller's permissions must imply MBeanPermission(className, null, mbeanName, "getClassLoaderFor").

  • For the getClassLoaderRepository method, the caller's permissions must imply MBeanPermission(null, null, null, "getClassLoaderRepository").

  • For the deprecated deserialize methods, the required permissions are the same as for the methods that replace them.

  • For the instantiate methods, the caller's permissions must imply MBeanPermission(className, null, null, "instantiate").

  • For the registerMBean method, the caller's permissions must imply MBeanPermission(className, null, name, "registerMBean"). Here className is the string returned by MBeanInfo.getClassName() for an object of this class.

    If the MBeanPermission check succeeds, the MBean's class is validated by checking that its ProtectionDomain implies MBeanTrustPermission("register").

    Finally, if the name argument is null, another MBeanPermission check is made using the ObjectName returned by MBeanRegistration.preRegister.

  • For the createMBean methods, the caller's permissions must imply the permissions needed by the equivalent instantiate followed by registerMBean.

  • For the unregisterMBean method, the caller's permissions must imply MBeanPermission(className, null, name, "unregisterMBean").

Since:
1.5

Method Summary
 void addNotificationListener(ObjectName name, NotificationListener listener, NotificationFilter filter, Object handback)
Adds a listener to a registered MBean.
 void addNotificationListener(ObjectName name, ObjectName listener, NotificationFilter filter, Object handback)
Adds a listener to a registered MBean.
 ObjectInstance createMBean(String className, ObjectName name)
Instantiates and registers an MBean in the MBean server.
 ObjectInstance createMBean(String className, ObjectName name, Object[] params, String[] signature)
Instantiates and registers an MBean in the MBean server.
 ObjectInstance createMBean(String className, ObjectName name, ObjectName loaderName)
Instantiates and registers an MBean in the MBean server.
 ObjectInstance createMBean(String className, ObjectName name, ObjectName loaderName, Object[] params, String[] signature)
Instantiates and registers an MBean in the MBean server.
 ObjectInputStream deserialize(ObjectName name, byte[] data)
Deprecated. Use getClassLoaderFor to obtain the appropriate class loader for deserialization.
 ObjectInputStream deserialize(String className, byte[] data)
Deprecated. Use getClassLoaderRepository() to obtain the class loader repository and use it to deserialize.
 ObjectInputStream deserialize(String className, ObjectName loaderName, byte[] data)
Deprecated. Use getClassLoader to obtain the class loader for deserialization.
 Object getAttribute(ObjectName name, String attribute)
Gets the value of a specific attribute of a named MBean.
 AttributeList getAttributes(ObjectName name, String[] attributes)
Enables the values of several attributes of a named MBean.
 ClassLoader getClassLoader(ObjectName loaderName)
Return the named ClassLoader.
 ClassLoader getClassLoaderFor(ObjectName mbeanName)
Return the ClassLoader that was used for loading the class of the named MBean.
 ClassLoaderRepository getClassLoaderRepository()
Return the ClassLoaderRepository for this MBeanServer.
 String getDefaultDomain()
Returns the default domain used for naming the MBean.
 String[] getDomains()
Returns the list of domains in which any MBean is currently registered.
 Integer getMBeanCount()
Returns the number of MBeans registered in the MBean server.
 MBeanInfo getMBeanInfo(ObjectName name)
This method discovers the attributes and operations that an MBean exposes for management.
 ObjectInstance getObjectInstance(ObjectName name)
Gets the ObjectInstance for a given MBean registered with the MBean server.
 Object instantiate(String className)
Instantiates an object using the list of all class loaders registered in the MBean server's Class Loader Repository.
 Object instantiate(String className, Object[] params, String[] signature)
Instantiates an object using the list of all class loaders registered in the MBean server Class Loader Repository.
 Object instantiate(String className, ObjectName loaderName)
Instantiates an object using the class Loader specified by its ObjectName.
 Object instantiate(String className, ObjectName loaderName, Object[] params, String[] signature)
Instantiates an object.
 Object invoke(ObjectName name, String operationName, Object[] params, String[] signature)
Invokes an operation on an MBean.
 boolean isInstanceOf(ObjectName name, String className)
Returns true if the MBean specified is an instance of the specified class, false otherwise.
 boolean isRegistered(ObjectName name)
Checks whether an MBean, identified by its object name, is already registered with the MBean server.
 Set<ObjectInstance> queryMBeans(ObjectName name, QueryExp query)
Gets MBeans controlled by the MBean server.
 Set<ObjectName> queryNames(ObjectName name, QueryExp query)
Gets the names of MBeans controlled by the MBean server.
 ObjectInstance registerMBean(Object object, ObjectName name)
Registers a pre-existing object as an MBean with the MBean server.
 void removeNotificationListener(ObjectName name, NotificationListener listener)
Removes a listener from a registered MBean.
 void removeNotificationListener(ObjectName name, NotificationListener listener, NotificationFilter filter, Object handback)
Removes a listener from a registered MBean.
 void removeNotificationListener(ObjectName name, ObjectName listener)
Removes a listener from a registered MBean.
 void removeNotificationListener(ObjectName name, ObjectName listener, NotificationFilter filter, Object handback)
Removes a listener from a registered MBean.
 void setAttribute(ObjectName name, Attribute attribute)
Sets the value of a specific attribute of a named MBean.
 AttributeList setAttributes(ObjectName name, AttributeList attributes)
Sets the values of several attributes of a named MBean.
 void unregisterMBean(ObjectName name)
Unregisters an MBean from the MBean server.

Method Detail

createMBean

ObjectInstance createMBean(String className,
                           ObjectName name)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException
Description copied from interface: MBeanServerConnection

Instantiates and registers an MBean in the MBean server. The MBean server will use its Default Loader Repository to load the class of the MBean. An object name is associated to the MBean. If the object name given is null, the MBean must provide its own name by implementing the MBeanRegistration interface and returning the name from the preRegister method.

This method is equivalent to createMBean(className, name, (Object[]) null, (String[]) null).

Specified by:
createMBean in interface MBeanServerConnection
Parameters:
className - The class name of the MBean to be instantiated.
name - The object name of the MBean. May be null.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception
NotCompliantMBeanException - This class is not a JMX compliant MBean

createMBean

ObjectInstance createMBean(String className,
                           ObjectName name,
                           ObjectName loaderName)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException,
                                  InstanceNotFoundException
Description copied from interface: MBeanServerConnection

Instantiates and registers an MBean in the MBean server. The class loader to be used is identified by its object name. An object name is associated to the MBean. If the object name of the loader is null, the ClassLoader that loaded the MBean server will be used. If the MBean's object name given is null, the MBean must provide its own name by implementing the MBeanRegistration interface and returning the name from the preRegister method.

This method is equivalent to createMBean(className, name, loaderName, (Object[]) null, (String[]) null).

Specified by:
createMBean in interface MBeanServerConnection
Parameters:
className - The class name of the MBean to be instantiated.
name - The object name of the MBean. May be null.
loaderName - The object name of the class loader to be used.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception
NotCompliantMBeanException - This class is not a JMX compliant MBean
InstanceNotFoundException - The specified class loader is not registered in the MBean server.

createMBean

ObjectInstance createMBean(String className,
                           ObjectName name,
                           Object[] params,
                           String[] signature)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException
Description copied from interface: MBeanServerConnection
Instantiates and registers an MBean in the MBean server. The MBean server will use its Default Loader Repository to load the class of the MBean. An object name is associated to the MBean. If the object name given is null, the MBean must provide its own name by implementing the MBeanRegistration interface and returning the name from the preRegister method.

Specified by:
createMBean in interface MBeanServerConnection
Parameters:
className - The class name of the MBean to be instantiated.
name - The object name of the MBean. May be null.
params - An array containing the parameters of the constructor to be invoked.
signature - An array containing the signature of the constructor to be invoked.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception
NotCompliantMBeanException - This class is not a JMX compliant MBean

createMBean

ObjectInstance createMBean(String className,
                           ObjectName name,
                           ObjectName loaderName,
                           Object[] params,
                           String[] signature)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException,
                                  InstanceNotFoundException
Description copied from interface: MBeanServerConnection
Instantiates and registers an MBean in the MBean server. The class loader to be used is identified by its object name. An object name is associated to the MBean. If the object name of the loader is not specified, the ClassLoader that loaded the MBean server will be used. If the MBean object name given is null, the MBean must provide its own name by implementing the MBeanRegistration interface and returning the name from the preRegister method.

Specified by:
createMBean in interface MBeanServerConnection
Parameters:
className - The class name of the MBean to be instantiated.
name - The object name of the MBean. May be null.
loaderName - The object name of the class loader to be used.
params - An array containing the parameters of the constructor to be invoked.
signature - An array containing the signature of the constructor to be invoked.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception
NotCompliantMBeanException - This class is not a JMX compliant MBean
InstanceNotFoundException - The specified class loader is not registered in the MBean server.

registerMBean

ObjectInstance registerMBean(Object object,
                             ObjectName name)
                             throws InstanceAlreadyExistsException,
                                    MBeanRegistrationException,
                                    NotCompliantMBeanException
Registers a pre-existing object as an MBean with the MBean server. If the object name given is null, the MBean must provide its own name by implementing the MBeanRegistration interface and returning the name from the preRegister method.

Parameters:
object - The MBean to be registered as an MBean.
name - The object name of the MBean. May be null.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly registered MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
NotCompliantMBeanException - This object is not a JMX compliant MBean
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object passed in parameter is null or no object name is specified.

unregisterMBean

void unregisterMBean(ObjectName name)
                     throws InstanceNotFoundException,
                            MBeanRegistrationException
Description copied from interface: MBeanServerConnection
Unregisters an MBean from the MBean server. The MBean is identified by its object name. Once the method has been invoked, the MBean may no longer be accessed by its object name.

Specified by:
unregisterMBean in interface MBeanServerConnection
Parameters:
name - The object name of the MBean to be unregistered.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
MBeanRegistrationException - The preDeregister ((MBeanRegistration interface) method of the MBean has thrown an exception.

getObjectInstance

ObjectInstance getObjectInstance(ObjectName name)
                                 throws InstanceNotFoundException
Description copied from interface: MBeanServerConnection
Gets the ObjectInstance for a given MBean registered with the MBean server.

Specified by:
getObjectInstance in interface MBeanServerConnection
Parameters:
name - The object name of the MBean.
Returns:
The ObjectInstance associated with the MBean specified by name. The contained ObjectName is name and the contained class name is getMBeanInfo(name).getClassName().
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.

queryMBeans

Set<ObjectInstance> queryMBeans(ObjectName name,
                                QueryExp query)
Description copied from interface: MBeanServerConnection
Gets MBeans controlled by the MBean server. This method allows any of the following to be obtained: All MBeans, a set of MBeans specified by pattern matching on the ObjectName and/or a Query expression, a specific MBean. When the object name is null or no domain and key properties are specified, all objects are to be selected (and filtered if a query is specified). It returns the set of ObjectInstance objects (containing the ObjectName and the Java Class name) for the selected MBeans.

Specified by:
queryMBeans in interface MBeanServerConnection
Parameters:
name - The object name pattern identifying the MBeans to be retrieved. If null or no domain and key properties are specified, all the MBeans registered will be retrieved.
query - The query expression to be applied for selecting MBeans. If null no query expression will be applied for selecting MBeans.
Returns:
A set containing the ObjectInstance objects for the selected MBeans. If no MBean satisfies the query an empty list is returned.

queryNames

Set<ObjectName> queryNames(ObjectName name,
                           QueryExp query)
Description copied from interface: MBeanServerConnection
Gets the names of MBeans controlled by the MBean server. This method enables any of the following to be obtained: The names of all MBeans, the names of a set of MBeans specified by pattern matching on the ObjectName and/or a Query expression, a specific MBean name (equivalent to testing whether an MBean is registered). When the object name is null or no domain and key properties are specified, all objects are selected (and filtered if a query is specified). It returns the set of ObjectNames for the MBeans selected.

Specified by:
queryNames in interface MBeanServerConnection
Parameters:
name - The object name pattern identifying the MBean names to be retrieved. If null or no domain and key properties are specified, the name of all registered MBeans will be retrieved.
query - The query expression to be applied for selecting MBeans. If null no query expression will be applied for selecting MBeans.
Returns:
A set containing the ObjectNames for the MBeans selected. If no MBean satisfies the query, an empty list is returned.

isRegistered

boolean isRegistered(ObjectName name)
Description copied from interface: MBeanServerConnection
Checks whether an MBean, identified by its object name, is already registered with the MBean server.

Specified by:
isRegistered in interface MBeanServerConnection
Parameters:
name - The object name of the MBean to be checked.
Returns:
True if the MBean is already registered in the MBean server, false otherwise.

getMBeanCount

Integer getMBeanCount()
Returns the number of MBeans registered in the MBean server.

Specified by:
getMBeanCount in interface MBeanServerConnection
Returns:
the number of registered MBeans, wrapped in an Integer. If the caller's permissions are restricted, this number may be greater than the number of MBeans the caller can access.

getAttribute

Object getAttribute(ObjectName name,
                    String attribute)
                    throws MBeanException,
                           AttributeNotFoundException,
                           InstanceNotFoundException,
                           ReflectionException
Description copied from interface: MBeanServerConnection
Gets the value of a specific attribute of a named MBean. The MBean is identified by its object name.

Specified by:
getAttribute in interface MBeanServerConnection
Parameters:
name - The object name of the MBean from which the attribute is to be retrieved.
attribute - A String specifying the name of the attribute to be retrieved.
Returns:
The value of the retrieved attribute.
Throws:
MBeanException - Wraps an exception thrown by the MBean's getter.
AttributeNotFoundException - The attribute specified is not accessible in the MBean.
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
ReflectionException - Wraps a java.lang.Exception thrown when trying to invoke the setter.
See Also:
MBeanServerConnection.setAttribute(javax.management.ObjectName, javax.management.Attribute)

getAttributes

AttributeList getAttributes(ObjectName name,
                            String[] attributes)
                            throws InstanceNotFoundException,
                                   ReflectionException
Description copied from interface: MBeanServerConnection
Enables the values of several attributes of a named MBean. The MBean is identified by its object name.

Specified by:
getAttributes in interface MBeanServerConnection
Parameters:
name - The object name of the MBean from which the attributes are retrieved.
attributes - A list of the attributes to be retrieved.
Returns:
The list of the retrieved attributes.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
ReflectionException - An exception occurred when trying to invoke the getAttributes method of a Dynamic MBean.
See Also:
MBeanServerConnection.setAttributes(javax.management.ObjectName, javax.management.AttributeList)

setAttribute

void setAttribute(ObjectName name,
                  Attribute attribute)
                  throws InstanceNotFoundException,
                         AttributeNotFoundException,
                         InvalidAttributeValueException,
                         MBeanException,
                         ReflectionException
Description copied from interface: MBeanServerConnection
Sets the value of a specific attribute of a named MBean. The MBean is identified by its object name.

Specified by:
setAttribute in interface MBeanServerConnection
Parameters:
name - The name of the MBean within which the attribute is to be set.
attribute - The identification of the attribute to be set and the value it is to be set to.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
AttributeNotFoundException - The attribute specified is not accessible in the MBean.
InvalidAttributeValueException - The value specified for the attribute is not valid.
MBeanException - Wraps an exception thrown by the MBean's setter.
ReflectionException - Wraps a java.lang.Exception thrown when trying to invoke the setter.
See Also:
MBeanServerConnection.getAttribute(javax.management.ObjectName, java.lang.String)

setAttributes

AttributeList setAttributes(ObjectName name,
                            AttributeList attributes)
                            throws InstanceNotFoundException,
                                   ReflectionException
Description copied from interface: MBeanServerConnection
Sets the values of several attributes of a named MBean. The MBean is identified by its object name.

Specified by:
setAttributes in interface MBeanServerConnection
Parameters:
name - The object name of the MBean within which the attributes are to be set.
attributes - A list of attributes: The identification of the attributes to be set and the values they are to be set to.
Returns:
The list of attributes that were set, with their new values.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
ReflectionException - An exception occurred when trying to invoke the getAttributes method of a Dynamic MBean.
See Also:
MBeanServerConnection.getAttributes(javax.management.ObjectName, java.lang.String[])

invoke

Object invoke(ObjectName name,
              String operationName,
              Object[] params,
              String[] signature)
              throws InstanceNotFoundException,
                     MBeanException,
                     ReflectionException
Description copied from interface: MBeanServerConnection
Invokes an operation on an MBean.

Specified by:
invoke in interface MBeanServerConnection
Parameters:
name - The object name of the MBean on which the method is to be invoked.
operationName - The name of the operation to be invoked.
params - An array containing the parameters to be set when the operation is invoked
signature - An array containing the signature of the operation. The class objects will be loaded using the same class loader as the one used for loading the MBean on which the operation was invoked.
Returns:
The object returned by the operation, which represents the result of invoking the operation on the MBean specified.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
MBeanException - Wraps an exception thrown by the MBean's invoked method.
ReflectionException - Wraps a java.lang.Exception thrown while trying to invoke the method.

getDefaultDomain

String getDefaultDomain()
Description copied from interface: MBeanServerConnection
Returns the default domain used for naming the MBean. The default domain name is used as the domain part in the ObjectName of MBeans if no domain is specified by the user.

Specified by:
getDefaultDomain in interface MBeanServerConnection
Returns:
the default domain.

getDomains

String[] getDomains()
Description copied from interface: MBeanServerConnection

Returns the list of domains in which any MBean is currently registered. A string is in the returned array if and only if there is at least one MBean registered with an ObjectName whose getDomain() is equal to that string. The order of strings within the returned array is not defined.

Specified by:
getDomains in interface MBeanServerConnection
Returns:
the list of domains.

addNotificationListener

void addNotificationListener(ObjectName name,
                             NotificationListener listener,
                             NotificationFilter filter,
                             Object handback)
                             throws InstanceNotFoundException
Description copied from interface: MBeanServerConnection

Adds a listener to a registered MBean.

A notification emitted by an MBean will be forwarded by the MBeanServer to the listener. If the source of the notification is a reference to an MBean object, the MBean server will replace it by that MBean's ObjectName. Otherwise the source is unchanged.

Specified by:
addNotificationListener in interface MBeanServerConnection
Parameters:
name - The name of the MBean on which the listener should be added.
listener - The listener object which will handle the notifications emitted by the registered MBean.
filter - The filter object. If filter is null, no filtering will be performed before handling notifications.
handback - The context to be sent to the listener when a notification is emitted.
Throws:
InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.
See Also:
MBeanServerConnection.removeNotificationListener(ObjectName, NotificationListener), MBeanServerConnection.removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)

addNotificationListener

void addNotificationListener(ObjectName name,
                             ObjectName listener,
                             NotificationFilter filter,
                             Object handback)
                             throws InstanceNotFoundException
Description copied from interface: MBeanServerConnection

Adds a listener to a registered MBean.

A notification emitted by an MBean will be forwarded by the MBeanServer to the listener. If the source of the notification is a reference to an MBean object, the MBean server will replace it by that MBean's ObjectName. Otherwise the source is unchanged.

The listener object that receives notifications is the one that is registered with the given name at the time this method is called. Even if it is subsequently unregistered, it will continue to receive notifications.

Specified by:
addNotificationListener in interface MBeanServerConnection
Parameters:
name - The name of the MBean on which the listener should be added.
listener - The object name of the listener which will handle the notifications emitted by the registered MBean.
filter - The filter object. If filter is null, no filtering will be performed before handling notifications.
handback - The context to be sent to the listener when a notification is emitted.
Throws:
InstanceNotFoundException - The MBean name of the notification listener or of the notification broadcaster does not match any of the registered MBeans.
See Also:
MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName), MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName, NotificationFilter, Object)

removeNotificationListener

void removeNotificationListener(ObjectName name,
                                ObjectName listener)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException
Description copied from interface: MBeanServerConnection
Removes a listener from a registered MBean.

If the listener is registered more than once, perhaps with different filters or callbacks, this method will remove all those registrations.

Specified by:
removeNotificationListener in interface MBeanServerConnection
Parameters:
name - The name of the MBean on which the listener should be removed.
listener - The object name of the listener to be removed.
Throws:
InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.
ListenerNotFoundException - The listener is not registered in the MBean.
See Also:
MBeanServerConnection.addNotificationListener(ObjectName, ObjectName, NotificationFilter, Object)

removeNotificationListener

void removeNotificationListener(ObjectName name,
                                ObjectName listener,
                                NotificationFilter filter,
                                Object handback)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException
Description copied from interface: MBeanServerConnection

Removes a listener from a registered MBean.

The MBean must have a listener that exactly matches the given listener, filter, and handback parameters. If there is more than one such listener, only one is removed.

The filter and handback parameters may be null if and only if they are null in a listener to be removed.

Specified by:
removeNotificationListener in interface MBeanServerConnection
Parameters:
name - The name of the MBean on which the listener should be removed.
listener - The object name of the listener to be removed.
filter - The filter that was specified when the listener was added.
handback - The handback that was specified when the listener was added.
Throws:
InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.
ListenerNotFoundException - The listener is not registered in the MBean, or it is not registered with the given filter and handback.
See Also:
MBeanServerConnection.addNotificationListener(ObjectName, ObjectName, NotificationFilter, Object)

removeNotificationListener

void removeNotificationListener(ObjectName name,
                                NotificationListener listener)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException
Description copied from interface: MBeanServerConnection

Removes a listener from a registered MBean.

If the listener is registered more than once, perhaps with different filters or callbacks, this method will remove all those registrations.

Specified by:
removeNotificationListener in interface MBeanServerConnection
Parameters:
name - The name of the MBean on which the listener should be removed.
listener - The listener to be removed.
Throws:
InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.
ListenerNotFoundException - The listener is not registered in the MBean.
See Also:
MBeanServerConnection.addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)

removeNotificationListener

void removeNotificationListener(ObjectName name,
                                NotificationListener listener,
                                NotificationFilter filter,
                                Object handback)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException
Description copied from interface: MBeanServerConnection

Removes a listener from a registered MBean.

The MBean must have a listener that exactly matches the given listener, filter, and handback parameters. If there is more than one such listener, only one is removed.

The filter and handback parameters may be null if and only if they are null in a listener to be removed.

Specified by:
removeNotificationListener in interface MBeanServerConnection
Parameters:
name - The name of the MBean on which the listener should be removed.
listener - The listener to be removed.
filter - The filter that was specified when the listener was added.
handback - The handback that was specified when the listener was added.
Throws:
InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.
ListenerNotFoundException - The listener is not registered in the MBean, or it is not registered with the given filter and handback.
See Also:
MBeanServerConnection.addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)

getMBeanInfo

MBeanInfo getMBeanInfo(ObjectName name)
                       throws InstanceNotFoundException,
                              IntrospectionException,
                              ReflectionException
Description copied from interface: MBeanServerConnection
This method discovers the attributes and operations that an MBean exposes for management.

Specified by:
getMBeanInfo in interface MBeanServerConnection
Parameters:
name - The name of the MBean to analyze
Returns:
An instance of MBeanInfo allowing the retrieval of all attributes and operations of this MBean.
Throws:
InstanceNotFoundException - The MBean specified was not found.
IntrospectionException - An exception occurred during introspection.
ReflectionException - An exception occurred when trying to invoke the getMBeanInfo of a Dynamic MBean.

isInstanceOf

boolean isInstanceOf(ObjectName name,
                     String className)
                     throws InstanceNotFoundException
Description copied from interface: MBeanServerConnection

Returns true if the MBean specified is an instance of the specified class, false otherwise.

If name does not name an MBean, this method throws InstanceNotFoundException.

Otherwise, let
X be the MBean named by name,
L be the ClassLoader of X,
N be the class name in X's MBeanInfo.

If N equals className, the result is true.

Otherwise, if L successfully loads className and X is an instance of this class, the result is true.

Otherwise, if L successfully loads both N and className, and the second class is assignable from the first, the result is true.

Otherwise, the result is false.

Specified by:
isInstanceOf in interface MBeanServerConnection
Parameters:
name - The ObjectName of the MBean.
className - The name of the class.
Returns:
true if the MBean specified is an instance of the specified class according to the rules above, false otherwise.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
See Also:
Class.isInstance(java.lang.Object)

instantiate

Object instantiate(String className)
                   throws ReflectionException,
                          MBeanException

Instantiates an object using the list of all class loaders registered in the MBean server's Class Loader Repository. The object's class should have a public constructor. This method returns a reference to the newly created object. The newly created object is not registered in the MBean server.

This method is equivalent to instantiate(className, (Object[]) null, (String[]) null).

Parameters:
className - The class name of the object to be instantiated.
Returns:
The newly instantiated object.
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or the java.lang.Exception that occurred when trying to invoke the object's constructor.
MBeanException - The constructor of the object has thrown an exception
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The className passed in parameter is null.

instantiate

Object instantiate(String className,
                   ObjectName loaderName)
                   throws ReflectionException,
                          MBeanException,
                          InstanceNotFoundException

Instantiates an object using the class Loader specified by its ObjectName. If the loader name is null, the ClassLoader that loaded the MBean Server will be used. The object's class should have a public constructor. This method returns a reference to the newly created object. The newly created object is not registered in the MBean server.

This method is equivalent to instantiate(className, loaderName, (Object[]) null, (String[]) null).

Parameters:
className - The class name of the MBean to be instantiated.
loaderName - The object name of the class loader to be used.
Returns:
The newly instantiated object.
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or the java.lang.Exception that occurred when trying to invoke the object's constructor.
MBeanException - The constructor of the object has thrown an exception.
InstanceNotFoundException - The specified class loader is not registered in the MBeanServer.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The className passed in parameter is null.

instantiate

Object instantiate(String className,
                   Object[] params,
                   String[] signature)
                   throws ReflectionException,
                          MBeanException

Instantiates an object using the list of all class loaders registered in the MBean server Class Loader Repository. The object's class should have a public constructor. The call returns a reference to the newly created object. The newly created object is not registered in the MBean server.

Parameters:
className - The class name of the object to be instantiated.
params - An array containing the parameters of the constructor to be invoked.
signature - An array containing the signature of the constructor to be invoked.
Returns:
The newly instantiated object.
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or the java.lang.Exception that occurred when trying to invoke the object's constructor.
MBeanException - The constructor of the object has thrown an exception
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The className passed in parameter is null.

instantiate

Object instantiate(String className,
                   ObjectName loaderName,
                   Object[] params,
                   String[] signature)
                   throws ReflectionException,
                          MBeanException,
                          InstanceNotFoundException

Instantiates an object. The class loader to be used is identified by its object name. If the object name of the loader is null, the ClassLoader that loaded the MBean server will be used. The object's class should have a public constructor. The call returns a reference to the newly created object. The newly created object is not registered in the MBean server.

Parameters:
className - The class name of the object to be instantiated.
params - An array containing the parameters of the constructor to be invoked.
signature - An array containing the signature of the constructor to be invoked.
loaderName - The object name of the class loader to be used.
Returns:
The newly instantiated object.
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or the java.lang.Exception that occurred when trying to invoke the object's constructor.
MBeanException - The constructor of the object has thrown an exception
InstanceNotFoundException - The specified class loader is not registered in the MBean server.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The className passed in parameter is null.

deserialize

@Deprecated
ObjectInputStream deserialize(ObjectName name,
                                         byte[] data)
                              throws InstanceNotFoundException,
                                     OperationsException
Deprecated. Use getClassLoaderFor to obtain the appropriate class loader for deserialization.

De-serializes a byte array in the context of the class loader of an MBean.

Parameters:
name - The name of the MBean whose class loader should be used for the de-serialization.
data - The byte array to be de-sererialized.
Returns:
The de-serialized object stream.
Throws:
InstanceNotFoundException - The MBean specified is not found.
OperationsException - Any of the usual Input/Output related exceptions.

deserialize

@Deprecated
ObjectInputStream deserialize(String className,
                                         byte[] data)
                              throws OperationsException,
                                     ReflectionException
Deprecated. Use getClassLoaderRepository() to obtain the class loader repository and use it to deserialize.

De-serializes a byte array in the context of a given MBean class loader. The class loader is found by loading the class className through the Class Loader Repository. The resultant class's class loader is the one to use.

Parameters:
className - The name of the class whose class loader should be used for the de-serialization.
data - The byte array to be de-sererialized.
Returns:
The de-serialized object stream.
Throws:
OperationsException - Any of the usual Input/Output related exceptions.
ReflectionException - The specified class could not be loaded by the class loader repository

deserialize

@Deprecated
ObjectInputStream deserialize(String className,
                                         ObjectName loaderName,
                                         byte[] data)
                              throws InstanceNotFoundException,
                                     OperationsException,
                                     ReflectionException
Deprecated. Use getClassLoader to obtain the class loader for deserialization.

De-serializes a byte array in the context of a given MBean class loader. The class loader is the one that loaded the class with name "className". The name of the class loader to be used for loading the specified class is specified. If null, the MBean Server's class loader will be used.

Parameters:
className - The name of the class whose class loader should be used for the de-serialization.
data - The byte array to be de-sererialized.
loaderName - The name of the class loader to be used for loading the specified class. If null, the MBean Server's class loader will be used.
Returns:
The de-serialized object stream.
Throws:
InstanceNotFoundException - The specified class loader MBean is not found.
OperationsException - Any of the usual Input/Output related exceptions.
ReflectionException - The specified class could not be loaded by the specified class loader.

getClassLoaderFor

ClassLoader getClassLoaderFor(ObjectName mbeanName)
                              throws InstanceNotFoundException

Return the ClassLoader that was used for loading the class of the named MBean.

Parameters:
mbeanName - The ObjectName of the MBean.
Returns:
The ClassLoader used for that MBean. If l is the MBean's actual ClassLoader, and r is the returned value, then either:
  • r is identical to l; or
  • the result of r .loadClass(s) is the same as l .loadClass(s) for any string s.
What this means is that the ClassLoader may be wrapped in another ClassLoader for security or other reasons.
Throws:
InstanceNotFoundException - if the named MBean is not found.

getClassLoader

ClassLoader getClassLoader(ObjectName loaderName)
                           throws InstanceNotFoundException

Return the named ClassLoader.

Parameters:
loaderName - The ObjectName of the ClassLoader. May be null, in which case the MBean server's own ClassLoader is returned.
Returns:
The named ClassLoader. If l is the actual ClassLoader with that name, and r is the returned value, then either:
  • r is identical to l; or
  • the result of r .loadClass(s) is the same as l .loadClass(s) for any string s.
What this means is that the ClassLoader may be wrapped in another ClassLoader for security or other reasons.
Throws:
InstanceNotFoundException - if the named ClassLoader is not found.

getClassLoaderRepository

ClassLoaderRepository getClassLoaderRepository()

Return the ClassLoaderRepository for this MBeanServer.

Returns:
The ClassLoaderRepository for this MBeanServer.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanServerBuilder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MBeanServerBuilder

java.lang.Object
    extended by  javax.management.MBeanServerBuilder

public class MBeanServerBuilder
extends Object

This class represents a builder that creates a default MBeanServer implementation. The JMX MBeanServerFactory allows applications to provide their custom MBeanServer implementation by providing a subclass of this class.

Since:
1.5
See Also:
MBeanServer, MBeanServerFactory

Constructor Summary
MBeanServerBuilder()
Public default constructor.
Method Summary
MBeanServer | newMBeanServer(String defaultDomain, MBeanServer outer, MBeanServerDelegate delegate) This method creates a new MBeanServer implementation object.
MBeanServerDelegate | newMBeanServerDelegate() This method creates a new MBeanServerDelegate for a new MBeanServer.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MBeanServerBuilder

public MBeanServerBuilder()
Public default constructor.

Method Detail

newMBeanServerDelegate

public MBeanServerDelegate newMBeanServerDelegate()
This method creates a new MBeanServerDelegate for a new MBeanServer. When creating a new MBeanServer the MBeanServerFactory first calls this method in order to create a new MBeanServerDelegate.
Then it calls newMBeanServer(defaultDomain,outer,delegate) passing the delegate that should be used by the MBeanServer implementation.

Note that the passed delegate might not be directly the MBeanServerDelegate that was returned by this method. It could be, for instance, a new object wrapping the previously returned object.

Returns:
A new MBeanServerDelegate.

newMBeanServer

public MBeanServer newMBeanServer(String defaultDomain,
                                  MBeanServer outer,
                                  MBeanServerDelegate delegate)
This method creates a new MBeanServer implementation object. When creating a new MBeanServer the MBeanServerFactory first calls newMBeanServerDelegate() in order to obtain a new MBeanServerDelegate for the new MBeanServer. Then it calls newMBeanServer(defaultDomain,outer,delegate) passing the delegate that should be used by the MBeanServer implementation.

Note that the passed delegate might not be directly the MBeanServerDelegate that was returned by this implementation. It could be, for instance, a new object wrapping the previously returned delegate.

The outer parameter is a pointer to the MBeanServer that should be passed to the MBeanRegistration interface when registering MBeans inside the MBeanServer. If outer is null, then the MBeanServer implementation must use its own this reference when invoking the MBeanRegistration interface.

This makes it possible for a MBeanServer implementation to wrap another MBeanServer implementation, in order to implement, e.g, security checks, or to prevent access to the actual MBeanServer implementation by returning a pointer to a wrapping object.

Parameters:
defaultDomain - Default domain of the new MBeanServer.
outer - A pointer to the MBeanServer object that must be passed to the MBeans when invoking their MBeanRegistration interface.
delegate - A pointer to the MBeanServerDelegate associated with the new MBeanServer. The new MBeanServer must register this MBean in its MBean repository.
Returns:
A new private implementation of an MBeanServer.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanServerConnection

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Interface MBeanServerConnection

All Known Subinterfaces:
MBeanServer, MBeanServerForwarder
public interface MBeanServerConnection

This interface represents a way to talk to an MBean server, whether local or remote. The MBeanServer interface, representing a local MBean server, extends this interface.

Since:
1.5

Method Summary
void | addNotificationListener(ObjectName name, NotificationListener listener, NotificationFilter filter, Object handback) Adds a listener to a registered MBean.
void | addNotificationListener(ObjectName name, ObjectName listener, NotificationFilter filter, Object handback) Adds a listener to a registered MBean.
ObjectInstance | createMBean(String className, ObjectName name) Instantiates and registers an MBean in the MBean server.
ObjectInstance | createMBean(String className, ObjectName name, Object[] params, String[] signature) Instantiates and registers an MBean in the MBean server.
ObjectInstance | createMBean(String className, ObjectName name, ObjectName loaderName) Instantiates and registers an MBean in the MBean server.
ObjectInstance | createMBean(String className, ObjectName name, ObjectName loaderName, Object[] params, String[] signature) Instantiates and registers an MBean in the MBean server.
Object | getAttribute(ObjectName name, String attribute) Gets the value of a specific attribute of a named MBean.
AttributeList | getAttributes(ObjectName name, String[] attributes) Enables the values of several attributes of a named MBean.
String | getDefaultDomain() Returns the default domain used for naming the MBean.
String[] | getDomains() Returns the list of domains in which any MBean is currently registered.
Integer | getMBeanCount() Returns the number of MBeans registered in the MBean server.
MBeanInfo | getMBeanInfo(ObjectName name) This method discovers the attributes and operations that an MBean exposes for management.
ObjectInstance | getObjectInstance(ObjectName name) Gets the ObjectInstance for a given MBean registered with the MBean server.
Object | invoke(ObjectName name, String operationName, Object[] params, String[] signature) Invokes an operation on an MBean.
boolean | isInstanceOf(ObjectName name, String className) Returns true if the MBean specified is an instance of the specified class, false otherwise.
boolean | isRegistered(ObjectName name) Checks whether an MBean, identified by its object name, is already registered with the MBean server.
Set<ObjectInstance> | queryMBeans(ObjectName name, QueryExp query) Gets MBeans controlled by the MBean server.
Set<ObjectName> | queryNames(ObjectName name, QueryExp query) Gets the names of MBeans controlled by the MBean server.
void | removeNotificationListener(ObjectName name, NotificationListener listener) Removes a listener from a registered MBean.
void | removeNotificationListener(ObjectName name, NotificationListener listener, NotificationFilter filter, Object handback) Removes a listener from a registered MBean.
void | removeNotificationListener(ObjectName name, ObjectName listener) Removes a listener from a registered MBean.
void | removeNotificationListener(ObjectName name, ObjectName listener, NotificationFilter filter, Object handback) Removes a listener from a registered MBean.
void | setAttribute(ObjectName name, Attribute attribute) Sets the value of a specific attribute of a named MBean.
AttributeList | setAttributes(ObjectName name, AttributeList attributes) Sets the values of several attributes of a named MBean.
void | unregisterMBean(ObjectName name) Unregisters an MBean from the MBean server.

Method Detail

createMBean

ObjectInstance createMBean(String className,
                           ObjectName name)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException,
                                  IOException

Instantiates and registers an MBean in the MBean server. The MBean server will use its Default Loader Repository to load the class of the MBean. An object name is associated to the MBean. If the object name given is null, the MBean must provide its own name by implementing the MBeanRegistration interface and returning the name from the preRegister method.

This method is equivalent to createMBean(className, name, (Object[]) null, (String[]) null).

Parameters:
className - The class name of the MBean to be instantiated.
name - The object name of the MBean. May be null.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception
NotCompliantMBeanException - This class is not a JMX compliant MBean
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The className passed in parameter is null, the ObjectName passed in parameter contains a pattern or no ObjectName is specified for the MBean.
IOException - A communication problem occurred when talking to the MBean server.

createMBean

ObjectInstance createMBean(String className,
                           ObjectName name,
                           ObjectName loaderName)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException,
                                  InstanceNotFoundException,
                                  IOException

Instantiates and registers an MBean in the MBean server. The class loader to be used is identified by its object name. An object name is associated to the MBean. If the object name of the loader is null, the ClassLoader that loaded the MBean server will be used. If the MBean's object name given is null, the MBean must provide its own name by implementing the MBeanRegistration interface and returning the name from the preRegister method.

This method is equivalent to createMBean(className, name, loaderName, (Object[]) null, (String[]) null).

Parameters:
className - The class name of the MBean to be instantiated.
name - The object name of the MBean. May be null.
loaderName - The object name of the class loader to be used.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception
NotCompliantMBeanException - This class is not a JMX compliant MBean
InstanceNotFoundException - The specified class loader is not registered in the MBean server.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The className passed in parameter is null, the ObjectName passed in parameter contains a pattern or no ObjectName is specified for the MBean.
IOException - A communication problem occurred when talking to the MBean server.

createMBean

ObjectInstance createMBean(String className,
                           ObjectName name,
                           Object[] params,
                           String[] signature)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException,
                                  IOException
Instantiates and registers an MBean in the MBean server. The MBean server will use its Default Loader Repository to load the class of the MBean. An object name is associated to the MBean. If the object name given is null, the MBean must provide its own name by implementing the MBeanRegistration interface and returning the name from the preRegister method.

Parameters:
className - The class name of the MBean to be instantiated.
name - The object name of the MBean. May be null.
params - An array containing the parameters of the constructor to be invoked.
signature - An array containing the signature of the constructor to be invoked.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception
NotCompliantMBeanException - This class is not a JMX compliant MBean
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The className passed in parameter is null, the ObjectName passed in parameter contains a pattern or no ObjectName is specified for the MBean.
IOException - A communication problem occurred when talking to the MBean server.

createMBean

ObjectInstance createMBean(String className,
                           ObjectName name,
                           ObjectName loaderName,
                           Object[] params,
                           String[] signature)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException,
                                  InstanceNotFoundException,
                                  IOException
Instantiates and registers an MBean in the MBean server. The class loader to be used is identified by its object name. An object name is associated to the MBean. If the object name of the loader is not specified, the ClassLoader that loaded the MBean server will be used. If the MBean object name given is null, the MBean must provide its own name by implementing the MBeanRegistration interface and returning the name from the preRegister method.

Parameters:
className - The class name of the MBean to be instantiated.
name - The object name of the MBean. May be null.
params - An array containing the parameters of the constructor to be invoked.
signature - An array containing the signature of the constructor to be invoked.
loaderName - The object name of the class loader to be used.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception
NotCompliantMBeanException - This class is not a JMX compliant MBean
InstanceNotFoundException - The specified class loader is not registered in the MBean server.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The className passed in parameter is null, the ObjectName passed in parameter contains a pattern or no ObjectName is specified for the MBean.
IOException - A communication problem occurred when talking to the MBean server.

unregisterMBean

void unregisterMBean(ObjectName name)
                     throws InstanceNotFoundException,
                            MBeanRegistrationException,
                            IOException
Unregisters an MBean from the MBean server. The MBean is identified by its object name. Once the method has been invoked, the MBean may no longer be accessed by its object name.

Parameters:
name - The object name of the MBean to be unregistered.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
MBeanRegistrationException - The preDeregister ((MBeanRegistration interface) method of the MBean has thrown an exception.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object name in parameter is null or the MBean you are when trying to unregister is the MBeanServerDelegate MBean.
IOException - A communication problem occurred when talking to the MBean server.

getObjectInstance

ObjectInstance getObjectInstance(ObjectName name)
                                 throws InstanceNotFoundException,
                                        IOException
Gets the ObjectInstance for a given MBean registered with the MBean server.

Parameters:
name - The object name of the MBean.
Returns:
The ObjectInstance associated with the MBean specified by name. The contained ObjectName is name and the contained class name is getMBeanInfo(name).getClassName().
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
IOException - A communication problem occurred when talking to the MBean server.

queryMBeans

Set<ObjectInstance> queryMBeans(ObjectName name,
                                QueryExp query)
                                throws IOException
Gets MBeans controlled by the MBean server. This method allows any of the following to be obtained: All MBeans, a set of MBeans specified by pattern matching on the ObjectName and/or a Query expression, a specific MBean. When the object name is null or no domain and key properties are specified, all objects are to be selected (and filtered if a query is specified). It returns the set of ObjectInstance objects (containing the ObjectName and the Java Class name) for the selected MBeans.

Parameters:
name - The object name pattern identifying the MBeans to be retrieved. If null or no domain and key properties are specified, all the MBeans registered will be retrieved.
query - The query expression to be applied for selecting MBeans. If null no query expression will be applied for selecting MBeans.
Returns:
A set containing the ObjectInstance objects for the selected MBeans. If no MBean satisfies the query an empty list is returned.
Throws:
IOException - A communication problem occurred when talking to the MBean server.

queryNames

Set<ObjectName> queryNames(ObjectName name,
                           QueryExp query)
                           throws IOException
Gets the names of MBeans controlled by the MBean server. This method enables any of the following to be obtained: The names of all MBeans, the names of a set of MBeans specified by pattern matching on the ObjectName and/or a Query expression, a specific MBean name (equivalent to testing whether an MBean is registered). When the object name is null or no domain and key properties are specified, all objects are selected (and filtered if a query is specified). It returns the set of ObjectNames for the MBeans selected.

Parameters:
name - The object name pattern identifying the MBean names to be retrieved. If null or no domain and key properties are specified, the name of all registered MBeans will be retrieved.
query - The query expression to be applied for selecting MBeans. If null no query expression will be applied for selecting MBeans.
Returns:
A set containing the ObjectNames for the MBeans selected. If no MBean satisfies the query, an empty list is returned.
Throws:
IOException - A communication problem occurred when talking to the MBean server.

isRegistered

boolean isRegistered(ObjectName name)
                     throws IOException
Checks whether an MBean, identified by its object name, is already registered with the MBean server.

Parameters:
name - The object name of the MBean to be checked.
Returns:
True if the MBean is already registered in the MBean server, false otherwise.
Throws:
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object name in parameter is null.
IOException - A communication problem occurred when talking to the MBean server.

getMBeanCount

Integer getMBeanCount()
                      throws IOException
Returns the number of MBeans registered in the MBean server.

Returns:
the number of MBeans registered.
Throws:
IOException - A communication problem occurred when talking to the MBean server.

getAttribute

Object getAttribute(ObjectName name,
                    String attribute)
                    throws MBeanException,
                           AttributeNotFoundException,
                           InstanceNotFoundException,
                           ReflectionException,
                           IOException
Gets the value of a specific attribute of a named MBean. The MBean is identified by its object name.

Parameters:
name - The object name of the MBean from which the attribute is to be retrieved.
attribute - A String specifying the name of the attribute to be retrieved.
Returns:
The value of the retrieved attribute.
Throws:
AttributeNotFoundException - The attribute specified is not accessible in the MBean.
MBeanException - Wraps an exception thrown by the MBean's getter.
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
ReflectionException - Wraps a java.lang.Exception thrown when trying to invoke the setter.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object name in parameter is null or the attribute in parameter is null.
IOException - A communication problem occurred when talking to the MBean server.
See Also:
setAttribute(javax.management.ObjectName, javax.management.Attribute)

getAttributes

AttributeList getAttributes(ObjectName name,
                            String[] attributes)
                            throws InstanceNotFoundException,
                                   ReflectionException,
                                   IOException
Enables the values of several attributes of a named MBean. The MBean is identified by its object name.

Parameters:
name - The object name of the MBean from which the attributes are retrieved.
attributes - A list of the attributes to be retrieved.
Returns:
The list of the retrieved attributes.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
ReflectionException - An exception occurred when trying to invoke the getAttributes method of a Dynamic MBean.
RuntimeOperationsException - Wrap a java.lang.IllegalArgumentException: The object name in parameter is null or attributes in parameter is null.
IOException - A communication problem occurred when talking to the MBean server.
See Also:
setAttributes(javax.management.ObjectName, javax.management.AttributeList)

setAttribute

void setAttribute(ObjectName name,
                  Attribute attribute)
                  throws InstanceNotFoundException,
                         AttributeNotFoundException,
                         InvalidAttributeValueException,
                         MBeanException,
                         ReflectionException,
                         IOException
Sets the value of a specific attribute of a named MBean. The MBean is identified by its object name.

Parameters:
name - The name of the MBean within which the attribute is to be set.
attribute - The identification of the attribute to be set and the value it is to be set to.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
AttributeNotFoundException - The attribute specified is not accessible in the MBean.
InvalidAttributeValueException - The value specified for the attribute is not valid.
MBeanException - Wraps an exception thrown by the MBean's setter.
ReflectionException - Wraps a java.lang.Exception thrown when trying to invoke the setter.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object name in parameter is null or the attribute in parameter is null.
IOException - A communication problem occurred when talking to the MBean server.
See Also:
getAttribute(javax.management.ObjectName, java.lang.String)

setAttributes

AttributeList setAttributes(ObjectName name,
                            AttributeList attributes)
                            throws InstanceNotFoundException,
                                   ReflectionException,
                                   IOException
Sets the values of several attributes of a named MBean. The MBean is identified by its object name.

Parameters:
name - The object name of the MBean within which the attributes are to be set.
attributes - A list of attributes: The identification of the attributes to be set and the values they are to be set to.
Returns:
The list of attributes that were set, with their new values.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
ReflectionException - An exception occurred when trying to invoke the getAttributes method of a Dynamic MBean.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object name in parameter is null or attributes in parameter is null.
IOException - A communication problem occurred when talking to the MBean server.
See Also:
getAttributes(javax.management.ObjectName, java.lang.String[])

invoke

Object invoke(ObjectName name,
              String operationName,
              Object[] params,
              String[] signature)
              throws InstanceNotFoundException,
                     MBeanException,
                     ReflectionException,
                     IOException
Invokes an operation on an MBean.

Parameters:
name - The object name of the MBean on which the method is to be invoked.
operationName - The name of the operation to be invoked.
params - An array containing the parameters to be set when the operation is invoked
signature - An array containing the signature of the operation. The class objects will be loaded using the same class loader as the one used for loading the MBean on which the operation was invoked.
Returns:
The object returned by the operation, which represents the result of invoking the operation on the MBean specified.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
MBeanException - Wraps an exception thrown by the MBean's invoked method.
ReflectionException - Wraps a java.lang.Exception thrown while trying to invoke the method.
IOException - A communication problem occurred when talking to the MBean server.

getDefaultDomain

String getDefaultDomain()
                        throws IOException
Returns the default domain used for naming the MBean. The default domain name is used as the domain part in the ObjectName of MBeans if no domain is specified by the user.

Returns:
the default domain.
Throws:
IOException - A communication problem occurred when talking to the MBean server.

getDomains

String[] getDomains()
                    throws IOException

Returns the list of domains in which any MBean is currently registered. A string is in the returned array if and only if there is at least one MBean registered with an ObjectName whose getDomain() is equal to that string. The order of strings within the returned array is not defined.

Returns:
the list of domains.
Throws:
IOException - A communication problem occurred when talking to the MBean server.

addNotificationListener

void addNotificationListener(ObjectName name,
                             NotificationListener listener,
                             NotificationFilter filter,
                             Object handback)
                             throws InstanceNotFoundException,
                                    IOException

Adds a listener to a registered MBean.

A notification emitted by an MBean will be forwarded by the MBeanServer to the listener. If the source of the notification is a reference to an MBean object, the MBean server will replace it by that MBean's ObjectName. Otherwise the source is unchanged.

Parameters:
name - The name of the MBean on which the listener should be added.
listener - The listener object which will handle the notifications emitted by the registered MBean.
filter - The filter object. If filter is null, no filtering will be performed before handling notifications.
handback - The context to be sent to the listener when a notification is emitted.
Throws:
InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.
IOException - A communication problem occurred when talking to the MBean server.
See Also:
removeNotificationListener(ObjectName, NotificationListener), removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)

addNotificationListener

void addNotificationListener(ObjectName name,
                             ObjectName listener,
                             NotificationFilter filter,
                             Object handback)
                             throws InstanceNotFoundException,
                                    IOException

Adds a listener to a registered MBean.

A notification emitted by an MBean will be forwarded by the MBeanServer to the listener. If the source of the notification is a reference to an MBean object, the MBean server will replace it by that MBean's ObjectName. Otherwise the source is unchanged.

The listener object that receives notifications is the one that is registered with the given name at the time this method is called. Even if it is subsequently unregistered, it will continue to receive notifications.

Parameters:
name - The name of the MBean on which the listener should be added.
listener - The object name of the listener which will handle the notifications emitted by the registered MBean.
filter - The filter object. If filter is null, no filtering will be performed before handling notifications.
handback - The context to be sent to the listener when a notification is emitted.
Throws:
InstanceNotFoundException - The MBean name of the notification listener or of the notification broadcaster does not match any of the registered MBeans.
RuntimeOperationsException - Wraps an IllegalArgumentException. The MBean named by listener exists but does not implement the NotificationListener interface.
IOException - A communication problem occurred when talking to the MBean server.
See Also:
removeNotificationListener(ObjectName, ObjectName), removeNotificationListener(ObjectName, ObjectName, NotificationFilter, Object)

removeNotificationListener

void removeNotificationListener(ObjectName name,
                                ObjectName listener)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException,
                                       IOException
Removes a listener from a registered MBean.

If the listener is registered more than once, perhaps with different filters or callbacks, this method will remove all those registrations.

Parameters:
name - The name of the MBean on which the listener should be removed.
listener - The object name of the listener to be removed.
Throws:
InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.
ListenerNotFoundException - The listener is not registered in the MBean.
IOException - A communication problem occurred when talking to the MBean server.
See Also:
addNotificationListener(ObjectName, ObjectName, NotificationFilter, Object)

removeNotificationListener

void removeNotificationListener(ObjectName name,
                                ObjectName listener,
                                NotificationFilter filter,
                                Object handback)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException,
                                       IOException

Removes a listener from a registered MBean.

The MBean must have a listener that exactly matches the given listener, filter, and handback parameters. If there is more than one such listener, only one is removed.

The filter and handback parameters may be null if and only if they are null in a listener to be removed.

Parameters:
name - The name of the MBean on which the listener should be removed.
listener - The object name of the listener to be removed.
filter - The filter that was specified when the listener was added.
handback - The handback that was specified when the listener was added.
Throws:
InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.
ListenerNotFoundException - The listener is not registered in the MBean, or it is not registered with the given filter and handback.
IOException - A communication problem occurred when talking to the MBean server.
See Also:
addNotificationListener(ObjectName, ObjectName, NotificationFilter, Object)

removeNotificationListener

void removeNotificationListener(ObjectName name,
                                NotificationListener listener)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException,
                                       IOException

Removes a listener from a registered MBean.

If the listener is registered more than once, perhaps with different filters or callbacks, this method will remove all those registrations.

Parameters:
name - The name of the MBean on which the listener should be removed.
listener - The listener to be removed.
Throws:
InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.
ListenerNotFoundException - The listener is not registered in the MBean.
IOException - A communication problem occurred when talking to the MBean server.
See Also:
addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)

removeNotificationListener

void removeNotificationListener(ObjectName name,
                                NotificationListener listener,
                                NotificationFilter filter,
                                Object handback)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException,
                                       IOException

Removes a listener from a registered MBean.

The MBean must have a listener that exactly matches the given listener, filter, and handback parameters. If there is more than one such listener, only one is removed.

The filter and handback parameters may be null if and only if they are null in a listener to be removed.

Parameters:
name - The name of the MBean on which the listener should be removed.
listener - The listener to be removed.
filter - The filter that was specified when the listener was added.
handback - The handback that was specified when the listener was added.
Throws:
InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.
ListenerNotFoundException - The listener is not registered in the MBean, or it is not registered with the given filter and handback.
IOException - A communication problem occurred when talking to the MBean server.
See Also:
addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)

getMBeanInfo

MBeanInfo getMBeanInfo(ObjectName name)
                       throws InstanceNotFoundException,
                              IntrospectionException,
                              ReflectionException,
                              IOException
This method discovers the attributes and operations that an MBean exposes for management.

Parameters:
name - The name of the MBean to analyze
Returns:
An instance of MBeanInfo allowing the retrieval of all attributes and operations of this MBean.
Throws:
IntrospectionException - An exception occurred during introspection.
InstanceNotFoundException - The MBean specified was not found.
ReflectionException - An exception occurred when trying to invoke the getMBeanInfo of a Dynamic MBean.
IOException - A communication problem occurred when talking to the MBean server.

isInstanceOf

boolean isInstanceOf(ObjectName name,
                     String className)
                     throws InstanceNotFoundException,
                            IOException

Returns true if the MBean specified is an instance of the specified class, false otherwise.

If name does not name an MBean, this method throws InstanceNotFoundException.

Otherwise, let
X be the MBean named by name,
L be the ClassLoader of X,
N be the class name in X's MBeanInfo.

If N equals className, the result is true.

Otherwise, if L successfully loads className and X is an instance of this class, the result is true.

Otherwise, if L successfully loads both N and className, and the second class is assignable from the first, the result is true.

Otherwise, the result is false.

Parameters:
name - The ObjectName of the MBean.
className - The name of the class.
Returns:
true if the MBean specified is an instance of the specified class according to the rules above, false otherwise.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
IOException - A communication problem occurred when talking to the MBean server.
See Also:
Class.isInstance(java.lang.Object)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanServerDelegate

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MBeanServerDelegate

java.lang.Object
    extended by  javax.management.MBeanServerDelegate
All Implemented Interfaces:
MBeanServerDelegateMBean, NotificationBroadcaster, NotificationEmitter
public class MBeanServerDelegate
extends Object
implements MBeanServerDelegateMBean, NotificationEmitter

Represents the MBean server from the management point of view. The MBeanServerDelegate MBean emits the MBeanServerNotifications when an MBean is registered/unregistered in the MBean server.

Since:
1.5

Field Summary
static ObjectName DELEGATE_NAME
Defines the default ObjectName of the MBeanServerDelegate.
Constructor Summary
MBeanServerDelegate()
Create a MBeanServerDelegate object.
Method Summary
void | addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Adds a listener to this MBean.
String | getImplementationName() Returns the JMX implementation name (the name of this product).
String | getImplementationVendor() Returns the JMX implementation vendor (the vendor of this product).
String | getImplementationVersion() Returns the JMX implementation version (the version of this product).
String | getMBeanServerId() Returns the MBean server agent identity.
MBeanNotificationInfo[] | getNotificationInfo() Returns an array indicating, for each notification this MBean may send, the name of the Java class of the notification and the notification type.
String | getSpecificationName() Returns the full name of the JMX specification implemented by this product.
String | getSpecificationVendor() Returns the vendor of the JMX specification implemented by this product.
String | getSpecificationVersion() Returns the version of the JMX specification implemented by this product.
void | removeNotificationListener(NotificationListener listener) Removes a listener from this MBean.
void | removeNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Removes a listener from this MBean.
void | sendNotification(Notification notification) Enables the MBean server to send a notification.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DELEGATE_NAME

public static final ObjectName DELEGATE_NAME
Defines the default ObjectName of the MBeanServerDelegate.

Since:
1.6
Constructor Detail

MBeanServerDelegate

public MBeanServerDelegate()
Create a MBeanServerDelegate object.

Method Detail

getMBeanServerId

public String getMBeanServerId()
Returns the MBean server agent identity.

Specified by:
getMBeanServerId in interface MBeanServerDelegateMBean
Returns:
the identity.

getSpecificationName

public String getSpecificationName()
Returns the full name of the JMX specification implemented by this product.

Specified by:
getSpecificationName in interface MBeanServerDelegateMBean
Returns:
the specification name.

getSpecificationVersion

public String getSpecificationVersion()
Returns the version of the JMX specification implemented by this product.

Specified by:
getSpecificationVersion in interface MBeanServerDelegateMBean
Returns:
the specification version.

getSpecificationVendor

public String getSpecificationVendor()
Returns the vendor of the JMX specification implemented by this product.

Specified by:
getSpecificationVendor in interface MBeanServerDelegateMBean
Returns:
the specification vendor.

getImplementationName

public String getImplementationName()
Returns the JMX implementation name (the name of this product).

Specified by:
getImplementationName in interface MBeanServerDelegateMBean
Returns:
the implementation name.

getImplementationVersion

public String getImplementationVersion()
Returns the JMX implementation version (the version of this product).

Specified by:
getImplementationVersion in interface MBeanServerDelegateMBean
Returns:
the implementation version.

getImplementationVendor

public String getImplementationVendor()
Returns the JMX implementation vendor (the vendor of this product).

Specified by:
getImplementationVendor in interface MBeanServerDelegateMBean
Returns:
the implementation vendor.

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()
Description copied from interface: NotificationBroadcaster

Returns an array indicating, for each notification this MBean may send, the name of the Java class of the notification and the notification type.

It is not illegal for the MBean to send notifications not described in this array. However, some clients of the MBean server may depend on the array being complete for their correct functioning.

Specified by:
getNotificationInfo in interface NotificationBroadcaster
Returns:
the array of possible notifications.

addNotificationListener

public void addNotificationListener(NotificationListener listener,
                                    NotificationFilter filter,
                                    Object handback)
                             throws IllegalArgumentException
Description copied from interface: NotificationBroadcaster
Adds a listener to this MBean.

Specified by:
addNotificationListener in interface NotificationBroadcaster
Parameters:
listener - The listener object which will handle the notifications emitted by the broadcaster.
filter - The filter object. If filter is null, no filtering will be performed before handling notifications.
handback - An opaque object to be sent back to the listener when a notification is emitted. This object cannot be used by the Notification broadcaster object. It should be resent unchanged with the notification to the listener.
Throws:
IllegalArgumentException - Listener parameter is null.
See Also:
NotificationBroadcaster.removeNotificationListener(javax.management.NotificationListener)

removeNotificationListener

public void removeNotificationListener(NotificationListener listener,
                                       NotificationFilter filter,
                                       Object handback)
                                throws ListenerNotFoundException
Description copied from interface: NotificationEmitter

Removes a listener from this MBean. The MBean must have a listener that exactly matches the given listener, filter, and handback parameters. If there is more than one such listener, only one is removed.

The filter and handback parameters may be null if and only if they are null in a listener to be removed.

Specified by:
removeNotificationListener in interface NotificationEmitter
Parameters:
listener - A listener that was previously added to this MBean.
filter - The filter that was specified when the listener was added.
handback - The handback that was specified when the listener was added.
Throws:
ListenerNotFoundException - The listener is not registered with the MBean, or it is not registered with the given filter and handback.

removeNotificationListener

public void removeNotificationListener(NotificationListener listener)
                                throws ListenerNotFoundException
Description copied from interface: NotificationBroadcaster
Removes a listener from this MBean. If the listener has been registered with different handback objects or notification filters, all entries corresponding to the listener will be removed.

Specified by:
removeNotificationListener in interface NotificationBroadcaster
Parameters:
listener - A listener that was previously added to this MBean.
Throws:
ListenerNotFoundException - The listener is not registered with the MBean.
See Also:
NotificationBroadcaster.addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object), NotificationEmitter.removeNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

sendNotification

public void sendNotification(Notification notification)
Enables the MBean server to send a notification. If the passed notification has a sequence number lesser or equal to 0, then replace it with the delegate's own sequence number.

Parameters:
notification - The notification to send.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanServerDelegateMBean

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Interface MBeanServerDelegateMBean

All Known Implementing Classes:
MBeanServerDelegate
public interface MBeanServerDelegateMBean

Defines the management interface of an object of class MBeanServerDelegate.

Since:
1.5

Method Summary
String | getImplementationName() Returns the JMX implementation name (the name of this product).
String | getImplementationVendor() Returns the JMX implementation vendor (the vendor of this product).
String | getImplementationVersion() Returns the JMX implementation version (the version of this product).
String | getMBeanServerId() Returns the MBean server agent identity.
String | getSpecificationName() Returns the full name of the JMX specification implemented by this product.
String | getSpecificationVendor() Returns the vendor of the JMX specification implemented by this product.
String | getSpecificationVersion() Returns the version of the JMX specification implemented by this product.

Method Detail

getMBeanServerId

String getMBeanServerId()
Returns the MBean server agent identity.

Returns:
the agent identity.

getSpecificationName

String getSpecificationName()
Returns the full name of the JMX specification implemented by this product.

Returns:
the specification name.

getSpecificationVersion

String getSpecificationVersion()
Returns the version of the JMX specification implemented by this product.

Returns:
the specification version.

getSpecificationVendor

String getSpecificationVendor()
Returns the vendor of the JMX specification implemented by this product.

Returns:
the specification vendor.

getImplementationName

String getImplementationName()
Returns the JMX implementation name (the name of this product).

Returns:
the implementation name.

getImplementationVersion

String getImplementationVersion()
Returns the JMX implementation version (the version of this product).

Returns:
the implementation version.

getImplementationVendor

String getImplementationVendor()
Returns the JMX implementation vendor (the vendor of this product).

Returns:
the implementation vendor.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanServerFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MBeanServerFactory

java.lang.Object
    extended by  javax.management.MBeanServerFactory

public class MBeanServerFactory
extends Object

Provides MBean server references. There are no instances of this class.

Since JMX 1.2 this class makes it possible to replace the default MBeanServer implementation. This is done using the MBeanServerBuilder class. The class of the initial MBeanServerBuilder to be instantiated can be specified through the javax.management.builder.initial system property. The specified class must be a public subclass of MBeanServerBuilder, and must have a public empty constructor.

By default, if no value for that property is specified, an instance of javax.management.MBeanServerBuilder is created. Otherwise, the MBeanServerFactory attempts to load the specified class using Thread.currentThread().getContextClassLoader(), or if that is null, Class.forName(). Then it creates an initial instance of that Class using Class.newInstance(). If any checked exception is raised during this process (e.g. ClassNotFoundException, InstantiationException) the MBeanServerFactory will propagate this exception from within a RuntimeException.

The javax.management.builder.initial system property is consulted every time a new MBeanServer needs to be created, and the class pointed to by that property is loaded. If that class is different from that of the current MBeanServerBuilder, then a new MBeanServerBuilder is created. Otherwise, the MBeanServerFactory may create a new MBeanServerBuilder or reuse the current one.

If the class pointed to by the property cannot be loaded, or does not correspond to a valid subclass of MBeanServerBuilder then an exception is propagated, and no MBeanServer can be created until the javax.management.builder.initial system property is reset to valid value.

The MBeanServerBuilder makes it possible to wrap the MBeanServers returned by the default MBeanServerBuilder implementation, for the purpose of e.g. adding an additional security layer.

Since:
1.5

Method Summary
static MBeanServer | createMBeanServer() Return a new object implementing the MBeanServer interface with a standard default domain name.
static MBeanServer | createMBeanServer(String domain) Return a new object implementing the MBeanServer interface with the specified default domain name.
static ArrayList<MBeanServer> | findMBeanServer(String agentId) Return a list of registered MBeanServer objects.
static ClassLoaderRepository | getClassLoaderRepository(MBeanServer server) Return the ClassLoaderRepository used by the given MBeanServer.
static MBeanServer | newMBeanServer() Return a new object implementing the MBeanServer interface with a standard default domain name, without keeping an internal reference to this new object.
static MBeanServer | newMBeanServer(String domain) Return a new object implementing the MBeanServer interface with the specified default domain name, without keeping an internal reference to this new object.
static void | releaseMBeanServer(MBeanServer mbeanServer) Remove internal MBeanServerFactory references to a created MBeanServer.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

releaseMBeanServer

public static void releaseMBeanServer(MBeanServer mbeanServer)
Remove internal MBeanServerFactory references to a created MBeanServer. This allows the garbage collector to remove the MBeanServer object.

Parameters:
mbeanServer - the MBeanServer object to remove.
Throws:
IllegalArgumentException - if mbeanServer was not generated by one of the createMBeanServer methods, or if releaseMBeanServer was already called on it.
SecurityException - if there is a SecurityManager and the caller's permissions do not include or imply MBeanServerPermission("releaseMBeanServer").

createMBeanServer

public static MBeanServer createMBeanServer()

Return a new object implementing the MBeanServer interface with a standard default domain name. The default domain name is used as the domain part in the ObjectName of MBeans when the domain is specified by the user is null.

The standard default domain name is DefaultDomain.

The MBeanServer reference is internally kept. This will allow findMBeanServer to return a reference to this MBeanServer object.

This method is equivalent to createMBeanServer(null).

Returns:
the newly created MBeanServer.
Throws:
SecurityException - if there is a SecurityManager and the caller's permissions do not include or imply MBeanServerPermission("createMBeanServer").
JMRuntimeException - if the property javax.management.builder.initial exists but the class it names cannot be instantiated through a public no-argument constructor; or if the instantiated builder returns null from its newMBeanServerDelegate or newMBeanServer methods.
ClassCastException - if the property javax.management.builder.initial exists and can be instantiated but is not assignment compatible with MBeanServerBuilder.

createMBeanServer

public static MBeanServer createMBeanServer(String domain)

Return a new object implementing the MBeanServer interface with the specified default domain name. The given domain name is used as the domain part in the ObjectName of MBeans when the domain is specified by the user is null.

The MBeanServer reference is internally kept. This will allow findMBeanServer to return a reference to this MBeanServer object.

Parameters:
domain - the default domain name for the created MBeanServer. This is the value that will be returned by MBeanServer.getDefaultDomain().
Returns:
the newly created MBeanServer.
Throws:
SecurityException - if there is a SecurityManager and the caller's permissions do not include or imply MBeanServerPermission("createMBeanServer").
JMRuntimeException - if the property javax.management.builder.initial exists but the class it names cannot be instantiated through a public no-argument constructor; or if the instantiated builder returns null from its newMBeanServerDelegate or newMBeanServer methods.
ClassCastException - if the property javax.management.builder.initial exists and can be instantiated but is not assignment compatible with MBeanServerBuilder.

newMBeanServer

public static MBeanServer newMBeanServer()

Return a new object implementing the MBeanServer interface with a standard default domain name, without keeping an internal reference to this new object. The default domain name is used as the domain part in the ObjectName of MBeans when the domain is specified by the user is null.

The standard default domain name is DefaultDomain.

No reference is kept. findMBeanServer will not be able to return a reference to this MBeanServer object, but the garbage collector will be able to remove the MBeanServer object when it is no longer referenced.

This method is equivalent to newMBeanServer(null).

Returns:
the newly created MBeanServer.
Throws:
SecurityException - if there is a SecurityManager and the caller's permissions do not include or imply MBeanServerPermission("newMBeanServer").
JMRuntimeException - if the property javax.management.builder.initial exists but the class it names cannot be instantiated through a public no-argument constructor; or if the instantiated builder returns null from its newMBeanServerDelegate or newMBeanServer methods.
ClassCastException - if the property javax.management.builder.initial exists and can be instantiated but is not assignment compatible with MBeanServerBuilder.

newMBeanServer

public static MBeanServer newMBeanServer(String domain)

Return a new object implementing the MBeanServer interface with the specified default domain name, without keeping an internal reference to this new object. The given domain name is used as the domain part in the ObjectName of MBeans when the domain is specified by the user is null.

No reference is kept. findMBeanServer will not be able to return a reference to this MBeanServer object, but the garbage collector will be able to remove the MBeanServer object when it is no longer referenced.

Parameters:
domain - the default domain name for the created MBeanServer. This is the value that will be returned by MBeanServer.getDefaultDomain().
Returns:
the newly created MBeanServer.
Throws:
SecurityException - if there is a SecurityManager and the caller's permissions do not include or imply MBeanServerPermission("newMBeanServer").
JMRuntimeException - if the property javax.management.builder.initial exists but the class it names cannot be instantiated through a public no-argument constructor; or if the instantiated builder returns null from its newMBeanServerDelegate or newMBeanServer methods.
ClassCastException - if the property javax.management.builder.initial exists and can be instantiated but is not assignment compatible with MBeanServerBuilder.

findMBeanServer

public static ArrayList<MBeanServer> findMBeanServer(String agentId)

Return a list of registered MBeanServer objects. A registered MBeanServer object is one that was created by one of the createMBeanServer methods and not subsequently released with releaseMBeanServer.

Parameters:
agentId - The agent identifier of the MBeanServer to retrieve. If this parameter is null, all registered MBeanServers in this JVM are returned. Otherwise, only MBeanServers whose id is equal to agentId are returned. The id of an MBeanServer is the MBeanServerId attribute of its delegate MBean.
Returns:
A list of MBeanServer objects.
Throws:
SecurityException - if there is a SecurityManager and the caller's permissions do not include or imply MBeanServerPermission("findMBeanServer").

getClassLoaderRepository

public static ClassLoaderRepository getClassLoaderRepository(MBeanServer server)
Return the ClassLoaderRepository used by the given MBeanServer. This method is equivalent to server.getClassLoaderRepository().

Parameters:
server - The MBeanServer under examination. Since JMX 1.2, if server is null, the result is a NullPointerException. This behavior differs from what was implemented in JMX 1.1 - where the possibility to use null was deprecated.
Returns:
The Class Loader Repository used by the given MBeanServer.
Throws:
SecurityException - if there is a SecurityManager and the caller's permissions do not include or imply MBeanPermission("getClassLoaderRepository").
NullPointerException - if server is null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanServerInvocationHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MBeanServerInvocationHandler

java.lang.Object
    extended by  javax.management.MBeanServerInvocationHandler
All Implemented Interfaces:
InvocationHandler
public class MBeanServerInvocationHandler
extends Object
implements InvocationHandler

InvocationHandler that forwards methods in an MBean's management interface through the MBean server to the MBean.

Given an MBeanServerConnection, the ObjectName of an MBean within that MBean server, and a Java interface Intf that describes the management interface of the MBean using the patterns for a Standard MBean or an MXBean, this class can be used to construct a proxy for the MBean. The proxy implements the interface Intf such that all of its methods are forwarded through the MBean server to the MBean.

If the InvocationHandler is for an MXBean, then the parameters of a method are converted from the type declared in the MXBean interface into the corresponding mapped type, and the return value is converted from the mapped type into the declared type. For example, with the method
public List<String> reverse(List<String> list);
and given that the mapped type for List<String> is String[], a call to proxy.reverse(someList) will convert someList from a List<String> to a String[], call the MBean operation reverse, then convert the returned String[] into a List<String>.

The method Object.toString(), Object.hashCode(), or Object.equals(Object), when invoked on a proxy using this invocation handler, is forwarded to the MBean server as a method on the proxied MBean only if it appears in one of the proxy's interfaces. For a proxy created with JMX.newMBeanProxy or JMX.newMXBeanProxy, this means that the method must appear in the Standard MBean or MXBean interface. Otherwise these methods have the following behavior:

  • toString() returns a string representation of the proxy
  • hashCode() returns a hash code for the proxy such that two equal proxies have the same hash code
  • equals(Object) returns true if and only if the Object argument is of the same proxy class as this proxy, with an MBeanServerInvocationHandler that has the same MBeanServerConnection and ObjectName; if one of the MBeanServerInvocationHandlers was constructed with a Class argument then the other must have been constructed with the same Class for equals to return true.

Since:
1.5

Constructor Summary
MBeanServerInvocationHandler(MBeanServerConnection connection, ObjectName objectName)
Invocation handler that forwards methods through an MBean server to a Standard MBean.
MBeanServerInvocationHandler(MBeanServerConnection connection, ObjectName objectName, boolean isMXBean)
Invocation handler that can forward methods through an MBean server to a Standard MBean or MXBean.
Method Summary
 MBeanServerConnection getMBeanServerConnection()
The MBean server connection through which the methods of a proxy using this handler are forwarded.
 ObjectName getObjectName()
The name of the MBean within the MBean server to which methods are forwarded.
 Object invoke(Object proxy, Method method, Object[] args)
Processes a method invocation on a proxy instance and returns the result.
 boolean isMXBean()
If true, the proxy is for an MXBean, and appropriate mappings are applied to method parameters and return values.
static
<T> T
newProxyInstance(MBeanServerConnection connection, ObjectName objectName, Class<T> interfaceClass, boolean notificationBroadcaster)
Return a proxy that implements the given interface by forwarding its methods through the given MBean server to the named MBean.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MBeanServerInvocationHandler

public MBeanServerInvocationHandler(MBeanServerConnection connection,
                                    ObjectName objectName)

Invocation handler that forwards methods through an MBean server to a Standard MBean. This constructor may be called instead of relying on JMX.newMBeanProxy, for instance if you need to supply a different ClassLoader to Proxy.newProxyInstance.

This constructor is not appropriate for an MXBean. Use MBeanServerInvocationHandler(MBeanServerConnection, ObjectName, boolean) for that. This constructor is equivalent to new MBeanServerInvocationHandler(connection, objectName, false).

Parameters:
connection - the MBean server connection through which all methods of a proxy using this handler will be forwarded.
objectName - the name of the MBean within the MBean server to which methods will be forwarded.

MBeanServerInvocationHandler

public MBeanServerInvocationHandler(MBeanServerConnection connection,
                                    ObjectName objectName,
                                    boolean isMXBean)

Invocation handler that can forward methods through an MBean server to a Standard MBean or MXBean. This constructor may be called instead of relying on JMX.newMXBeanProxy, for instance if you need to supply a different ClassLoader to Proxy.newProxyInstance.

Parameters:
connection - the MBean server connection through which all methods of a proxy using this handler will be forwarded.
objectName - the name of the MBean within the MBean server to which methods will be forwarded.
isMXBean - if true, the proxy is for an MXBean, and appropriate mappings will be applied to method parameters and return values.
Since:
1.6
Method Detail

getMBeanServerConnection

public MBeanServerConnection getMBeanServerConnection()

The MBean server connection through which the methods of a proxy using this handler are forwarded.

Returns:
the MBean server connection.
Since:
1.6

getObjectName

public ObjectName getObjectName()

The name of the MBean within the MBean server to which methods are forwarded.

Returns:
the object name.
Since:
1.6

isMXBean

public boolean isMXBean()

If true, the proxy is for an MXBean, and appropriate mappings are applied to method parameters and return values.

Returns:
whether the proxy is for an MXBean.
Since:
1.6

newProxyInstance

public static <T> T newProxyInstance(MBeanServerConnection connection,
                                     ObjectName objectName,
                                     Class<T> interfaceClass,
                                     boolean notificationBroadcaster)

Return a proxy that implements the given interface by forwarding its methods through the given MBean server to the named MBean. As of 1.6, the methods JMX.newMBeanProxy(MBeanServerConnection, ObjectName, Class) and JMX.newMBeanProxy(MBeanServerConnection, ObjectName, Class, boolean) are preferred to this method.

This method is equivalent to Proxy.newProxyInstance (interfaceClass.getClassLoader(), interfaces, handler). Here handler is the result of new MBeanServerInvocationHandler(connection, objectName), and interfaces is an array that has one element if notificationBroadcaster is false and two if it is true. The first element of interfaces is interfaceClass and the second, if present, is NotificationEmitter.class.

Type Parameters:
T - allows the compiler to know that if the interfaceClass parameter is MyMBean.class, for example, then the return type is MyMBean.
Parameters:
connection - the MBean server to forward to.
objectName - the name of the MBean within connection to forward to.
interfaceClass - the management interface that the MBean exports, which will also be implemented by the returned proxy.
notificationBroadcaster - make the returned proxy implement NotificationEmitter by forwarding its methods via connection. A call to NotificationBroadcaster.addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object) on the proxy will result in a call to MBeanServerConnection.addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object), and likewise for the other methods of NotificationBroadcaster and NotificationEmitter.
Returns:
the new proxy instance.
See Also:
JMX.newMBeanProxy(MBeanServerConnection, ObjectName, Class)

invoke

public Object invoke(Object proxy,
                     Method method,
                     Object[] args)
              throws Throwable
Description copied from interface: InvocationHandler
Processes a method invocation on a proxy instance and returns the result. This method will be invoked on an invocation handler when a method is invoked on a proxy instance that it is associated with.

Specified by:
invoke in interface InvocationHandler
Parameters:
proxy - the proxy instance that the method was invoked on
method - the Method instance corresponding to the interface method invoked on the proxy instance. The declaring class of the Method object will be the interface that the method was declared in, which may be a superinterface of the proxy interface that the proxy class inherits the method through.
args - an array of objects containing the values of the arguments passed in the method invocation on the proxy instance, or null if interface method takes no arguments. Arguments of primitive types are wrapped in instances of the appropriate primitive wrapper class, such as java.lang.Integer or java.lang.Boolean.
Returns:
the value to return from the method invocation on the proxy instance. If the declared return type of the interface method is a primitive type, then the value returned by this method must be an instance of the corresponding primitive wrapper class; otherwise, it must be a type assignable to the declared return type. If the value returned by this method is null and the interface method's return type is primitive, then a NullPointerException will be thrown by the method invocation on the proxy instance. If the value returned by this method is otherwise not compatible with the interface method's declared return type as described above, a ClassCastException will be thrown by the method invocation on the proxy instance.
Throws:
Throwable - the exception to throw from the method invocation on the proxy instance. The exception's type must be assignable either to any of the exception types declared in the throws clause of the interface method or to the unchecked exception types java.lang.RuntimeException or java.lang.Error. If a checked exception is thrown by this method that is not assignable to any of the exception types declared in the throws clause of the interface method, then an UndeclaredThrowableException containing the exception that was thrown by this method will be thrown by the method invocation on the proxy instance.
See Also:
UndeclaredThrowableException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanServerNotification

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MBeanServerNotification

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.management.Notification
            extended by  javax.management.MBeanServerNotification
All Implemented Interfaces:
Serializable
public class MBeanServerNotification
extends Notification

Represents a notification emitted by the MBean server through the MBeanServerDelegate MBean. The MBean Server emits the following types of notifications: MBean registration, MBean de-registration.

To receive to MBeanServerNotifications, you need to be declared as listener to the javax.management.MBeanServerDelegate MBean that represents the MBeanServer. The ObjectName of the MBeanServerDelegate is: JMImplementation:type=MBeanServerDelegate.

Since:
1.5
See Also:
Serialized Form

Field Summary
static String | REGISTRATION_NOTIFICATION Notification type denoting that an MBean has been registered.
static String | UNREGISTRATION_NOTIFICATION Notification type denoting that an MBean has been unregistered.
Fields inherited from class javax.management.Notification
source
Constructor Summary
MBeanServerNotification(String type, Object source, long sequenceNumber, ObjectName objectName)
Creates an MBeanServerNotification object specifying object names of the MBeans that caused the notification and the specified notification type.
Method Summary
 ObjectName getMBeanName()
Returns the object name of the MBean that caused the notification.
Methods inherited from class javax.management.Notification
getMessage, getSequenceNumber, getTimeStamp, getType, getUserData, setSequenceNumber, setSource, setTimeStamp, setUserData, toString
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

REGISTRATION_NOTIFICATION

public static final String REGISTRATION_NOTIFICATION
Notification type denoting that an MBean has been registered. Value is "JMX.mbean.registered".

See Also:
Constant Field Values

UNREGISTRATION_NOTIFICATION

public static final String UNREGISTRATION_NOTIFICATION
Notification type denoting that an MBean has been unregistered. Value is "JMX.mbean.unregistered".

See Also:
Constant Field Values
Constructor Detail

MBeanServerNotification

public MBeanServerNotification(String type,
                               Object source,
                               long sequenceNumber,
                               ObjectName objectName)
Creates an MBeanServerNotification object specifying object names of the MBeans that caused the notification and the specified notification type.

Parameters:
type - A string denoting the type of the notification. Set it to one these values: REGISTRATION_NOTIFICATION, UNREGISTRATION_NOTIFICATION.
source - The MBeanServerNotification object responsible for forwarding MBean server notification.
sequenceNumber - A sequence number that can be used to order received notifications.
objectName - The object name of the MBean that caused the notification.
Method Detail

getMBeanName

public ObjectName getMBeanName()
Returns the object name of the MBean that caused the notification.

Returns:
the object name of the MBean that caused the notification.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanServerPermission

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MBeanServerPermission

java.lang.Object
    extended by  java.security.Permission
        extended by  java.security.BasicPermission
            extended by  javax.management.MBeanServerPermission
All Implemented Interfaces:
Serializable, Guard
public class MBeanServerPermission
extends BasicPermission

A Permission to perform actions related to MBeanServers. The name of the permission specifies the operation requested or granted by the permission. For a granted permission, it can be * to allow all of the MBeanServer operations specified below. Otherwise, for a granted or requested permission, it must be one of the following:

createMBeanServer
Create a new MBeanServer object using the method MBeanServerFactory.createMBeanServer() or MBeanServerFactory.createMBeanServer(java.lang.String).
findMBeanServer
Find an MBeanServer with a given name, or all MBeanServers in this JVM, using the method MBeanServerFactory.findMBeanServer(java.lang.String).
newMBeanServer
Create a new MBeanServer object without keeping a reference to it, using the method MBeanServerFactory.newMBeanServer() or MBeanServerFactory.newMBeanServer(java.lang.String).
releaseMBeanServer
Remove the MBeanServerFactory's reference to an MBeanServer, using the method MBeanServerFactory.releaseMBeanServer(javax.management.MBeanServer).
The name of the permission can also denote a list of one or more comma-separated operations. Spaces are allowed at the beginning and end of the name and before and after commas.

MBeanServerPermission("createMBeanServer") implies MBeanServerPermission("newMBeanServer").

Since:
1.5
See Also:
Serialized Form

Constructor Summary
MBeanServerPermission(String name)
Create a new MBeanServerPermission with the given name.
MBeanServerPermission(String name, String actions)
Create a new MBeanServerPermission with the given name.
Method Summary
boolean | equals(Object obj) Checks two MBeanServerPermission objects for equality.
int | hashCode() Returns the hash code value for this object.
boolean | implies(Permission p) Checks if this MBeanServerPermission object "implies" the specified permission.
PermissionCollection | newPermissionCollection() Returns a new PermissionCollection object for storing BasicPermission objects.
Methods inherited from class java.security.BasicPermission
getActions
Methods inherited from class java.security.Permission
checkGuard, getName, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

MBeanServerPermission

public MBeanServerPermission(String name)

Create a new MBeanServerPermission with the given name.

This constructor is equivalent to MBeanServerPermission(name,null).

Parameters:
name - the name of the granted permission. It must respect the constraints spelt out in the description of the MBeanServerPermission class.
Throws:
NullPointerException - if the name is null.
IllegalArgumentException - if the name is not * or one of the allowed names or a comma-separated list of the allowed names.

MBeanServerPermission

public MBeanServerPermission(String name,
                             String actions)

Create a new MBeanServerPermission with the given name.

Parameters:
name - the name of the granted permission. It must respect the constraints spelt out in the description of the MBeanServerPermission class.
actions - the associated actions. This parameter is not currently used and must be null or the empty string.
Throws:
NullPointerException - if the name is null.
IllegalArgumentException - if the name is not * or one of the allowed names or a comma-separated list of the allowed names, or if actions is a non-null non-empty string.
NullPointerException - if name is null.
IllegalArgumentException - if name is empty or if arguments are invalid.
Method Detail

hashCode

public int hashCode()
Description copied from class: BasicPermission
Returns the hash code value for this object. The hash code used is the hash code of the name, that is, getName().hashCode(), where getName is from the Permission superclass.

Overrides:
hashCode in class BasicPermission
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

implies

public boolean implies(Permission p)

Checks if this MBeanServerPermission object "implies" the specified permission.

More specifically, this method returns true if:

  • p is an instance of MBeanServerPermission,
  • p's target names are a subset of this object's target names

The createMBeanServer permission implies the newMBeanServer permission.

Overrides:
implies in class BasicPermission
Parameters:
p - the permission to check against.
Returns:
true if the specified permission is implied by this object, false if not.

equals

public boolean equals(Object obj)
Checks two MBeanServerPermission objects for equality. Checks that obj is an MBeanServerPermission, and represents the same list of allowable actions as this object.

Overrides:
equals in class BasicPermission
Parameters:
obj - the object we are testing for equality with this object.
Returns:
true if the objects are equal.
See Also:
Object.hashCode(), Hashtable

newPermissionCollection

public PermissionCollection newPermissionCollection()
Description copied from class: BasicPermission
Returns a new PermissionCollection object for storing BasicPermission objects.

A BasicPermissionCollection stores a collection of BasicPermission permissions.

BasicPermission objects must be stored in a manner that allows them to be inserted in any order, but that also enables the PermissionCollection implies method to be implemented in an efficient (and consistent) manner.

Overrides:
newPermissionCollection in class BasicPermission
Returns:
a new PermissionCollection object suitable for storing BasicPermissions.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanTrustPermission

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class MBeanTrustPermission

java.lang.Object
    extended by  java.security.Permission
        extended by  java.security.BasicPermission
            extended by  javax.management.MBeanTrustPermission
All Implemented Interfaces:
Serializable, Guard
public class MBeanTrustPermission
extends BasicPermission

This permission represents "trust" in a signer or codebase.

MBeanTrustPermission contains a target name but no actions list. A single target name, "register", is defined for this permission. The target "*" is also allowed, permitting "register" and any future targets that may be defined. Only the null value or the empty string are allowed for the action to allow the policy object to create the permissions specified in the policy file.

If a signer, or codesource is granted this permission, then it is considered a trusted source for MBeans. Only MBeans from trusted sources may be registered in the MBeanServer.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
MBeanTrustPermission(String name)
Create a new MBeanTrustPermission with the given name.
MBeanTrustPermission(String name, String actions)
Create a new MBeanTrustPermission with the given name.
Method Summary
Methods inherited from class java.security.BasicPermission
equals, getActions, hashCode, implies, newPermissionCollection
Methods inherited from class java.security.Permission
checkGuard, getName, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

MBeanTrustPermission

public MBeanTrustPermission(String name)

Create a new MBeanTrustPermission with the given name.

This constructor is equivalent to MBeanTrustPermission(name,null).

Parameters:
name - the name of the permission. It must be "register" or "*" for this permission.
Throws:
NullPointerException - if name is null.
IllegalArgumentException - if name is neither "register" nor "*".

MBeanTrustPermission

public MBeanTrustPermission(String name,
                            String actions)

Create a new MBeanTrustPermission with the given name.

Parameters:
name - the name of the permission. It must be "register" or "*" for this permission.
actions - the actions for the permission. It must be null or "".
Throws:
NullPointerException - if name is null.
IllegalArgumentException - if name is neither "register" nor "*"; or if actions is a non-null non-empty string.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


modelmbean

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.management.modelmbean

Provides the definition of the ModelMBean classes.

See:
Description

Interface Summary
ModelMBean | This interface must be implemented by the ModelMBeans.
ModelMBeanInfo | This interface is implemented by the ModelMBeanInfo for every ModelMBean.
ModelMBeanNotificationBroadcaster | This interface must be implemented by the ModelMBeans.

Class Summary
DescriptorSupport | This class represents the metadata set for a ModelMBean element.
ModelMBeanAttributeInfo | The ModelMBeanAttributeInfo object describes an attribute of the ModelMBean.
ModelMBeanConstructorInfo | The ModelMBeanConstructorInfo object describes a constructor of the ModelMBean.
ModelMBeanInfoSupport | This class represents the meta data for ModelMBeans.
ModelMBeanNotificationInfo | The ModelMBeanNotificationInfo object describes a notification emitted by a ModelMBean.
ModelMBeanOperationInfo | The ModelMBeanOperationInfo object describes a management operation of the ModelMBean.
RequiredModelMBean | This class is the implementation of a ModelMBean.

Exception Summary
InvalidTargetObjectTypeException | Exception thrown when an invalid target object type is specified.
XMLParseException | This exception is thrown when an XML formatted string is being parsed into ModelMBean objects or when XML formatted strings are being created from ModelMBean objects.

Package javax.management.modelmbean Description

Provides the definition of the ModelMBean classes. A Model MBean is an MBean that acts as a bridge between the management interface and the underlying managed resource. Both the management interface and the managed resource are specified as Java objects. The same Model MBean implementation can be reused many times with different management interfaces and managed resources, and it can provide common functionality such as persistence and caching.

A Model MBean implements the ModelMBean interface. It is a DynamicMBean whose getMBeanInfo method returns an object implementing ModelMBeanInfo.

Every MBean has an MBeanInfo with information about the MBean itself, and its attributes, operations, constructors, and notifications. A Model MBean augments this MBeanInfo with Descriptors that encode additional information in the form of (key,value) pairs. Usually, Descriptors are instances of DescriptorSupport.

The class RequiredModelMBean provides a standard Model MBean implementation.

The following example shows a Model MBean being used to make the get method of a HashMap available for management through an MBean server. No other methods are available through the MBean server. There is nothing special about HashMap here. Public methods from any public class can be exposed for management in the same way.

import java.lang.reflect.Method;
import java.util.HashMap;
import javax.management.*;
import javax.management.modelmbean.*;

// ...

MBeanServer mbs = MBeanServerFactory.createMBeanServer();
// The MBean Server

HashMap map = new HashMap();
// The resource that will be managed

// Construct the management interface for the Model MBean
Method getMethod = HashMap.class.getMethod("get", new Class[] {Object.class});
ModelMBeanOperationInfo getInfo =
    new ModelMBeanOperationInfo("Get value for key", getMethod);
ModelMBeanInfo mmbi =
    new ModelMBeanInfoSupport(HashMap.class.getName(),
                              "Map of keys and values",
                              null,  // no attributes
                              null,  // no constructors
                              new ModelMBeanOperationInfo[] {getInfo},
                              null); // no notifications

// Make the Model MBean and link it to the resource
ModelMBean mmb = new RequiredModelMBean(mmbi);
mmb.setManagedResource(map, "ObjectReference");

// Register the Model MBean in the MBean Server
ObjectName mapName = new ObjectName(":type=Map,name=whatever");
mbs.registerMBean(mmb, mapName);

// Resource can evolve independently of the MBean
map.put("key", "value");

// Can access the "get" method through the MBean Server
mbs.invoke(mapName, "get", new Object[] {"key"}, new String[] {Object.class.getName()});
// returns "value"

Package Specification

  • See the JMX 1.4 Specification PDF document available from the Java SE 6 Platform documentation on JMX

Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.management.modelmbean Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.management.modelmbean

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.management.modelmbean.DescriptorSupport (implements javax.management.Descriptor)
    • javax.management.MBeanFeatureInfo (implements javax.management.DescriptorRead, java.io.Serializable)
      • javax.management.MBeanAttributeInfo (implements java.lang.Cloneable)
        • javax.management.modelmbean.ModelMBeanAttributeInfo (implements javax.management.DescriptorAccess)
      • javax.management.MBeanConstructorInfo (implements java.lang.Cloneable)
        • javax.management.modelmbean.ModelMBeanConstructorInfo (implements javax.management.DescriptorAccess)
      • javax.management.MBeanNotificationInfo (implements java.lang.Cloneable)
        • javax.management.modelmbean.ModelMBeanNotificationInfo (implements javax.management.DescriptorAccess)
      • javax.management.MBeanOperationInfo (implements java.lang.Cloneable)
        • javax.management.modelmbean.ModelMBeanOperationInfo (implements javax.management.DescriptorAccess)
    • javax.management.MBeanInfo (implements java.lang.Cloneable, javax.management.DescriptorRead, java.io.Serializable)
      • javax.management.modelmbean.ModelMBeanInfoSupport (implements javax.management.modelmbean.ModelMBeanInfo)
    • javax.management.modelmbean.RequiredModelMBean (implements javax.management.MBeanRegistration, javax.management.modelmbean.ModelMBean, javax.management.NotificationEmitter)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.management.modelmbean.InvalidTargetObjectTypeException
        • javax.management.modelmbean.XMLParseException

Interface Hierarchy

  • javax.management.DynamicMBean
    • javax.management.modelmbean.ModelMBean (also extends javax.management.modelmbean.ModelMBeanNotificationBroadcaster, javax.management.PersistentMBean)
  • javax.management.modelmbean.ModelMBeanInfo
  • javax.management.NotificationBroadcaster
    • javax.management.modelmbean.ModelMBeanNotificationBroadcaster
      • javax.management.modelmbean.ModelMBean (also extends javax.management.DynamicMBean, javax.management.PersistentMBean)
  • javax.management.PersistentMBean
    • javax.management.modelmbean.ModelMBean (also extends javax.management.DynamicMBean, javax.management.modelmbean.ModelMBeanNotificationBroadcaster)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.management.modelmbean

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.management.modelmbean

Packages that use javax.management.modelmbean
javax.management.modelmbean Provides the definition of the ModelMBean classes.

Classes in javax.management.modelmbean used by javax.management.modelmbean
DescriptorSupport
This class represents the metadata set for a ModelMBean element.
InvalidTargetObjectTypeException
Exception thrown when an invalid target object type is specified.
ModelMBean
This interface must be implemented by the ModelMBeans.
ModelMBeanAttributeInfo
The ModelMBeanAttributeInfo object describes an attribute of the ModelMBean.
ModelMBeanConstructorInfo
The ModelMBeanConstructorInfo object describes a constructor of the ModelMBean.
ModelMBeanInfo
This interface is implemented by the ModelMBeanInfo for every ModelMBean.
ModelMBeanNotificationBroadcaster
This interface must be implemented by the ModelMBeans.
ModelMBeanNotificationInfo
The ModelMBeanNotificationInfo object describes a notification emitted by a ModelMBean.
ModelMBeanOperationInfo
The ModelMBeanOperationInfo object describes a management operation of the ModelMBean.
XMLParseException
This exception is thrown when an XML formatted string is being parsed into ModelMBean objects or when XML formatted strings are being created from ModelMBean objects.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.modelmbean.DescriptorSupport

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.modelmbean.DescriptorSupport

Packages that use DescriptorSupport
javax.management.modelmbean Provides the definition of the ModelMBean classes.

Uses of DescriptorSupport in javax.management.modelmbean

Constructors in javax.management.modelmbean with parameters of type DescriptorSupport
DescriptorSupport(DescriptorSupport inDescr)
Descriptor constructor taking a Descriptor as parameter.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.modelmbean.InvalidTargetObjectTypeException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.modelmbean.InvalidTargetObjectTypeException

Packages that use InvalidTargetObjectTypeException
javax.management.modelmbean Provides the definition of the ModelMBean classes.

Uses of InvalidTargetObjectTypeException in javax.management.modelmbean

Methods in javax.management.modelmbean that throw InvalidTargetObjectTypeException
void | RequiredModelMBean.setManagedResource(Object mr, String mr_type) Sets the instance handle of the object against which to execute all methods in this ModelMBean management interface (MBeanInfo and Descriptors).
void | ModelMBean.setManagedResource(Object mr, String mr_type) Sets the instance handle of the object against which to execute all methods in this ModelMBean management interface (MBeanInfo and Descriptors).

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.modelmbean.ModelMBeanAttributeInfo

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.modelmbean.ModelMBeanAttributeInfo

Packages that use ModelMBeanAttributeInfo
javax.management.modelmbean Provides the definition of the ModelMBean classes.

Uses of ModelMBeanAttributeInfo in javax.management.modelmbean

Methods in javax.management.modelmbean that return ModelMBeanAttributeInfo
ModelMBeanAttributeInfo | ModelMBeanInfoSupport.getAttribute(String inName)
ModelMBeanAttributeInfo | ModelMBeanInfo.getAttribute(String inName) Returns a ModelMBeanAttributeInfo requested by name.

Constructors in javax.management.modelmbean with parameters of type ModelMBeanAttributeInfo
ModelMBeanAttributeInfo(ModelMBeanAttributeInfo inInfo)
Constructs a new ModelMBeanAttributeInfo object from this ModelMBeanAttributeInfo Object.
ModelMBeanInfoSupport(String className, String description, ModelMBeanAttributeInfo[] attributes, ModelMBeanConstructorInfo[] constructors, ModelMBeanOperationInfo[] operations, ModelMBeanNotificationInfo[] notifications)
Creates a ModelMBeanInfoSupport with the provided information, but the descriptor is a default.
ModelMBeanInfoSupport(String className, String description, ModelMBeanAttributeInfo[] attributes, ModelMBeanConstructorInfo[] constructors, ModelMBeanOperationInfo[] operations, ModelMBeanNotificationInfo[] notifications, Descriptor mbeandescriptor)
Creates a ModelMBeanInfoSupport with the provided information and the descriptor given in parameter.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.modelmbean.ModelMBeanConstructorInfo

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.modelmbean.ModelMBeanConstructorInfo

Packages that use ModelMBeanConstructorInfo
javax.management.modelmbean Provides the definition of the ModelMBean classes.

Uses of ModelMBeanConstructorInfo in javax.management.modelmbean

Methods in javax.management.modelmbean that return ModelMBeanConstructorInfo
 ModelMBeanConstructorInfo ModelMBeanInfoSupport.getConstructor(String inName)
Returns the ModelMBeanConstructorInfo requested by name.

Constructors in javax.management.modelmbean with parameters of type ModelMBeanConstructorInfo
ModelMBeanInfoSupport(String className, String description, ModelMBeanAttributeInfo[] attributes, ModelMBeanConstructorInfo[] constructors, ModelMBeanOperationInfo[] operations, ModelMBeanNotificationInfo[] notifications)
Creates a ModelMBeanInfoSupport with the provided information, but the descriptor is a default.
ModelMBeanInfoSupport(String className, String description, ModelMBeanAttributeInfo[] attributes, ModelMBeanConstructorInfo[] constructors, ModelMBeanOperationInfo[] operations, ModelMBeanNotificationInfo[] notifications, Descriptor mbeandescriptor)
Creates a ModelMBeanInfoSupport with the provided information and the descriptor given in parameter.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.modelmbean.ModelMBeanInfoSupport

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.modelmbean.ModelMBeanInfoSupport

No usage of javax.management.modelmbean.ModelMBeanInfoSupport

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.modelmbean.ModelMBeanNotificationInfo

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.modelmbean.ModelMBeanNotificationInfo

Packages that use ModelMBeanNotificationInfo
javax.management.modelmbean Provides the definition of the ModelMBean classes.

Uses of ModelMBeanNotificationInfo in javax.management.modelmbean

Methods in javax.management.modelmbean that return ModelMBeanNotificationInfo
ModelMBeanNotificationInfo | ModelMBeanInfoSupport.getNotification(String inName)
ModelMBeanNotificationInfo | ModelMBeanInfo.getNotification(String inName) Returns a ModelMBeanNotificationInfo requested by name.

Constructors in javax.management.modelmbean with parameters of type ModelMBeanNotificationInfo
ModelMBeanInfoSupport(String className, String description, ModelMBeanAttributeInfo[] attributes, ModelMBeanConstructorInfo[] constructors, ModelMBeanOperationInfo[] operations, ModelMBeanNotificationInfo[] notifications)
Creates a ModelMBeanInfoSupport with the provided information, but the descriptor is a default.
ModelMBeanInfoSupport(String className, String description, ModelMBeanAttributeInfo[] attributes, ModelMBeanConstructorInfo[] constructors, ModelMBeanOperationInfo[] operations, ModelMBeanNotificationInfo[] notifications, Descriptor mbeandescriptor)
Creates a ModelMBeanInfoSupport with the provided information and the descriptor given in parameter.
ModelMBeanNotificationInfo(ModelMBeanNotificationInfo inInfo)
Constructs a new ModelMBeanNotificationInfo object from this ModelMBeanNotfication Object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.modelmbean.ModelMBeanOperationInfo

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.modelmbean.ModelMBeanOperationInfo

Packages that use ModelMBeanOperationInfo
javax.management.modelmbean Provides the definition of the ModelMBean classes.

Uses of ModelMBeanOperationInfo in javax.management.modelmbean

Methods in javax.management.modelmbean that return ModelMBeanOperationInfo
ModelMBeanOperationInfo | ModelMBeanInfoSupport.getOperation(String inName)
ModelMBeanOperationInfo | ModelMBeanInfo.getOperation(String inName) Returns a ModelMBeanOperationInfo requested by name.

Constructors in javax.management.modelmbean with parameters of type ModelMBeanOperationInfo
ModelMBeanInfoSupport(String className, String description, ModelMBeanAttributeInfo[] attributes, ModelMBeanConstructorInfo[] constructors, ModelMBeanOperationInfo[] operations, ModelMBeanNotificationInfo[] notifications)
Creates a ModelMBeanInfoSupport with the provided information, but the descriptor is a default.
ModelMBeanInfoSupport(String className, String description, ModelMBeanAttributeInfo[] attributes, ModelMBeanConstructorInfo[] constructors, ModelMBeanOperationInfo[] operations, ModelMBeanNotificationInfo[] notifications, Descriptor mbeandescriptor)
Creates a ModelMBeanInfoSupport with the provided information and the descriptor given in parameter.
ModelMBeanOperationInfo(ModelMBeanOperationInfo inInfo)
Constructs a new ModelMBeanOperationInfo object from this ModelMBeanOperation Object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.modelmbean.RequiredModelMBean

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.modelmbean.RequiredModelMBean

No usage of javax.management.modelmbean.RequiredModelMBean

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.modelmbean.XMLParseException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.modelmbean.XMLParseException

Packages that use XMLParseException
javax.management.modelmbean Provides the definition of the ModelMBean classes.

Uses of XMLParseException in javax.management.modelmbean

Constructors in javax.management.modelmbean that throw XMLParseException
DescriptorSupport(String inStr)
Descriptor constructor taking an XML String.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.modelmbean.ModelMBean

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.modelmbean.ModelMBean

Packages that use ModelMBean
javax.management.modelmbean Provides the definition of the ModelMBean classes.

Uses of ModelMBean in javax.management.modelmbean

Classes in javax.management.modelmbean that implement ModelMBean
 class RequiredModelMBean
This class is the implementation of a ModelMBean.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.modelmbean.ModelMBeanInfo

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.modelmbean.ModelMBeanInfo

Packages that use ModelMBeanInfo
javax.management.modelmbean Provides the definition of the ModelMBean classes.

Uses of ModelMBeanInfo in javax.management.modelmbean

Classes in javax.management.modelmbean that implement ModelMBeanInfo
 class ModelMBeanInfoSupport
This class represents the meta data for ModelMBeans.

Methods in javax.management.modelmbean with parameters of type ModelMBeanInfo
void | RequiredModelMBean.setModelMBeanInfo(ModelMBeanInfo mbi) Initializes a ModelMBean object using ModelMBeanInfo passed in.
void | ModelMBean.setModelMBeanInfo(ModelMBeanInfo inModelMBeanInfo) Initializes a ModelMBean object using ModelMBeanInfo passed in.

Constructors in javax.management.modelmbean with parameters of type ModelMBeanInfo
ModelMBeanInfoSupport(ModelMBeanInfo mbi)
Constructs a ModelMBeanInfoSupport which is a duplicate of the given ModelMBeanInfo.
RequiredModelMBean(ModelMBeanInfo mbi)
Constructs a RequiredModelMBean object using ModelMBeanInfo passed in.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.modelmbean.ModelMBeanNotificationBroadcaster

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.modelmbean.ModelMBeanNotificationBroadcaster

Packages that use ModelMBeanNotificationBroadcaster
javax.management.modelmbean Provides the definition of the ModelMBean classes.

Uses of ModelMBeanNotificationBroadcaster in javax.management.modelmbean

Subinterfaces of ModelMBeanNotificationBroadcaster in javax.management.modelmbean
 interface ModelMBean
This interface must be implemented by the ModelMBeans.

Classes in javax.management.modelmbean that implement ModelMBeanNotificationBroadcaster
 class RequiredModelMBean
This class is the implementation of a ModelMBean.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DescriptorSupport

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.management.modelmbean
Class DescriptorSupport

java.lang.Object
    extended by  javax.management.modelmbean.DescriptorSupport
All Implemented Interfaces:
Serializable, Cloneable, Descriptor
public class DescriptorSupport
extends Object
implements Descriptor

This class represents the metadata set for a ModelMBean element. A descriptor is part of the ModelMBeanInfo, ModelMBeanNotificationInfo, ModelMBeanAttributeInfo, ModelMBeanConstructorInfo, and ModelMBeanParameterInfo.

A descriptor consists of a collection of fields. Each field is in fieldname=fieldvalue format. Field names are not case sensitive, case will be preserved on field values.

All field names and values are not predefined. New fields can be defined and added by any program. Some fields have been predefined for consistency of implementation and support by the ModelMBeanInfo, ModelMBeanAttributeInfo, ModelMBeanConstructorInfo, ModelMBeanNotificationInfo, ModelMBeanOperationInfo and ModelMBean classes.

The serialVersionUID of this class is -6292969195866300415L.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
DescriptorSupport()
Descriptor default constructor.
DescriptorSupport(DescriptorSupport inDescr)
Descriptor constructor taking a Descriptor as parameter.
DescriptorSupport(int initNumFields)
Descriptor constructor.
DescriptorSupport(String... fields)
Constructor taking fields in the fieldName=fieldValue format.
DescriptorSupport(String inStr)
Descriptor constructor taking an XML String.
DescriptorSupport(String[] fieldNames, Object[] fieldValues)
Constructor taking field names and field values.
Method Summary
Object | clone() Returns a new Descriptor which is a duplicate of the Descriptor.
boolean | equals(Object o) Compares this descriptor to the given object.
String[] | getFieldNames() Returns all the field names in the descriptor.
String[] | getFields() Returns all of the fields contained in this descriptor as a string array.
Object | getFieldValue(String fieldName) Returns the value for a specific field name, or null if no value is present for that name.
Object[] | getFieldValues(String... fieldNames) Returns all the field values in the descriptor as an array of Objects.
int | hashCode() Returns the hash code value for this descriptor.
boolean | isValid() Returns true if all of the fields have legal values given their names.
void | removeField(String fieldName) Removes a field from the descriptor.
void | setField(String fieldName, Object fieldValue) Sets the value for a specific field name.
void | setFields(String[] fieldNames, Object[] fieldValues) Sets all fields in the field names array to the new value with the same index in the field values array.
String | toString() Returns a human readable string representing the descriptor.
String | toXMLString() Returns an XML String representing the descriptor.
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DescriptorSupport

public DescriptorSupport()
Descriptor default constructor. Default initial descriptor size is 20. It will grow as needed.
Note that the created empty descriptor is not a valid descriptor (the method isValid returns false)

DescriptorSupport

public DescriptorSupport(int initNumFields)
                  throws MBeanException,
                         RuntimeOperationsException
Descriptor constructor. Takes as parameter the initial capacity of the Map that stores the descriptor fields. Capacity will grow as needed.
Note that the created empty descriptor is not a valid descriptor (the method isValid returns false).

Parameters:
initNumFields - The initial capacity of the Map that stores the descriptor fields.
Throws:
RuntimeOperationsException - for illegal value for initNumFields (<= 0)
MBeanException - Wraps a distributed communication Exception.

DescriptorSupport

public DescriptorSupport(DescriptorSupport inDescr)
Descriptor constructor taking a Descriptor as parameter. Creates a new descriptor initialized to the values of the descriptor passed in parameter.

Parameters:
inDescr - the descriptor to be used to initialize the constructed descriptor. If it is null or contains no descriptor fields, an empty Descriptor will be created.

DescriptorSupport

public DescriptorSupport(String inStr)
                  throws MBeanException,
                         RuntimeOperationsException,
                         XMLParseException

Descriptor constructor taking an XML String.

The format of the XML string is not defined, but an implementation must ensure that the string returned by toXMLString() on an existing descriptor can be used to instantiate an equivalent descriptor using this constructor.

In this implementation, all field values will be created as Strings. If the field values are not Strings, the programmer will have to reset or convert these fields correctly.

Parameters:
inStr - An XML-formatted string used to populate this Descriptor. The format is not defined, but any implementation must ensure that the string returned by method toXMLString on an existing descriptor can be used to instantiate an equivalent descriptor when instantiated using this constructor.
Throws:
RuntimeOperationsException - If the String inStr passed in parameter is null
XMLParseException - XML parsing problem while parsing the input String
MBeanException - Wraps a distributed communication Exception.

DescriptorSupport

public DescriptorSupport(String[] fieldNames,
                         Object[] fieldValues)
                  throws RuntimeOperationsException
Constructor taking field names and field values. Neither array can be null.

Parameters:
fieldNames - String array of field names. No elements of this array can be null.
fieldValues - Object array of the corresponding field values. Elements of the array can be null. The fieldValue must be valid for the fieldName (as defined in method isValid)

Note: array sizes of parameters should match. If both arrays are empty, then an empty descriptor is created.

Throws:
RuntimeOperationsException - for illegal value for field Names or field Values. The array lengths must be equal. If the descriptor construction fails for any reason, this exception will be thrown.

DescriptorSupport

public DescriptorSupport(String... fields)
Constructor taking fields in the fieldName=fieldValue format.

Parameters:
fields - String array with each element containing a field name and value. If this array is null or empty, then the default constructor will be executed. Null strings or empty strings will be ignored.

All field values should be Strings. If the field values are not Strings, the programmer will have to reset or convert these fields correctly.

Note: Each string should be of the form fieldName=fieldValue. The field name ends at the first = character; for example if the String is a=b=c then the field name is a and its value is b=c.

Throws:
RuntimeOperationsException - for illegal value for field Names or field Values. The field must contain an "=". "=fieldValue", "fieldName", and "fieldValue" are illegal. FieldName cannot be null. "fieldName=" will cause the value to be null. If the descriptor construction fails for any reason, this exception will be thrown.
Method Detail

getFieldValue

public Object getFieldValue(String fieldName)
                     throws RuntimeOperationsException
Description copied from interface: Descriptor
Returns the value for a specific field name, or null if no value is present for that name.

Specified by:
getFieldValue in interface Descriptor
Parameters:
fieldName - the field name.
Returns:
the corresponding value, or null if the field is not present.
Throws:
RuntimeOperationsException - if the field name is illegal.

setField

public void setField(String fieldName,
                     Object fieldValue)
              throws RuntimeOperationsException
Description copied from interface: Descriptor

Sets the value for a specific field name. This will modify an existing field or add a new field.

The field value will be validated before it is set. If it is not valid, then an exception will be thrown. The meaning of validity is dependent on the descriptor implementation.

Specified by:
setField in interface Descriptor
Parameters:
fieldName - The field name to be set. Cannot be null or empty.
fieldValue - The field value to be set for the field name. Can be null if that is a valid value for the field.
Throws:
RuntimeOperationsException - if the field name or field value is illegal (wrapped exception is IllegalArgumentException); or if the descriptor is immutable (wrapped exception is UnsupportedOperationException).

getFields

public String[] getFields()
Description copied from interface: Descriptor
Returns all of the fields contained in this descriptor as a string array.

Specified by:
getFields in interface Descriptor
Returns:
String array of fields in the format fieldName=fieldValue
If the value of a field is not a String, then the toString() method will be called on it and the returned value, enclosed in parentheses, used as the value for the field in the returned array. If the value of a field is null, then the value of the field in the returned array will be empty. If the descriptor is empty, you will get an empty array.
See Also:
Descriptor.setFields(java.lang.String[], java.lang.Object[])

getFieldNames

public String[] getFieldNames()
Description copied from interface: Descriptor
Returns all the field names in the descriptor.

Specified by:
getFieldNames in interface Descriptor
Returns:
String array of field names. If the descriptor is empty, you will get an empty array.

getFieldValues

public Object[] getFieldValues(String... fieldNames)
Description copied from interface: Descriptor
Returns all the field values in the descriptor as an array of Objects. The returned values are in the same order as the fieldNames String array parameter.

Specified by:
getFieldValues in interface Descriptor
Parameters:
fieldNames - String array of the names of the fields that the values should be returned for. If the array is empty then an empty array will be returned. If the array is null then all values will be returned, as if the parameter were the array returned by Descriptor.getFieldNames(). If a field name in the array does not exist, including the case where it is null or the empty string, then null is returned for the matching array element being returned.
Returns:
Object array of field values. If the list of fieldNames is empty, you will get an empty array.

setFields

public void setFields(String[] fieldNames,
                      Object[] fieldValues)
               throws RuntimeOperationsException
Description copied from interface: Descriptor

Sets all fields in the field names array to the new value with the same index in the field values array. Array sizes must match.

The field value will be validated before it is set. If it is not valid, then an exception will be thrown. If the arrays are empty, then no change will take effect.

Specified by:
setFields in interface Descriptor
Parameters:
fieldNames - String array of field names. The array and array elements cannot be null.
fieldValues - Object array of the corresponding field values. The array cannot be null. Elements of the array can be null.
Throws:
RuntimeOperationsException - if the change fails for any reason. Wrapped exception is IllegalArgumentException if fieldNames or fieldValues is null, or if the arrays are of different lengths, or if there is an illegal value in one of them. Wrapped exception is UnsupportedOperationException if the descriptor is immutable, and the call would change its contents.
See Also:
Descriptor.getFields()

clone

public Object clone()
             throws RuntimeOperationsException
Returns a new Descriptor which is a duplicate of the Descriptor.

Specified by:
clone in interface Descriptor
Overrides:
clone in class Object
Returns:
a clone of this instance.
Throws:
RuntimeOperationsException - for illegal value for field Names or field Values. If the descriptor construction fails for any reason, this exception will be thrown.
See Also:
Cloneable

removeField

public void removeField(String fieldName)
Description copied from interface: Descriptor
Removes a field from the descriptor.

Specified by:
removeField in interface Descriptor
Parameters:
fieldName - String name of the field to be removed. If the field name is illegal or the field is not found, no exception is thrown.

equals

public boolean equals(Object o)
Compares this descriptor to the given object. The objects are equal if the given object is also a Descriptor, and if the two Descriptors have the same field names (possibly differing in case) and the same associated values. The respective values for a field in the two Descriptors are equal if the following conditions hold:

  • If one value is null then the other must be too.
  • If one value is a primitive array then the other must be a primitive array of the same type with the same elements.
  • If one value is an object array then the other must be too and Arrays.deepEquals must return true.
  • Otherwise Object.equals(Object) must return true.

Specified by:
equals in interface Descriptor
Overrides:
equals in class Object
Parameters:
o - the object to compare with.
Returns:
true if the objects are the same; false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()

Returns the hash code value for this descriptor. The hash code is computed as the sum of the hash codes for each field in the descriptor. The hash code of a field with name n and value v is n.toLowerCase().hashCode() ^ h. Here h is the hash code of v, computed as follows:

  • If v is null then h is 0.
  • If v is a primitive array then h is computed using the appropriate overloading of java.util.Arrays.hashCode.
  • If v is an object array then h is computed using Arrays.deepHashCode.
  • Otherwise h is v.hashCode().

Specified by:
hashCode in interface Descriptor
Overrides:
hashCode in class Object
Returns:
A hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

isValid

public boolean isValid()
                throws RuntimeOperationsException
Returns true if all of the fields have legal values given their names.

This implementation does not support interoperating with a directory or lookup service. Thus, conforming to the specification, no checking is done on the "export" field.

Otherwise this implementation returns false if:

  • name and descriptorType fieldNames are not defined, or null, or empty, or not String
  • class, role, getMethod, setMethod fieldNames, if defined, are null or not String
  • persistPeriod, currencyTimeLimit, lastUpdatedTimeStamp, lastReturnedTimeStamp if defined, are null, or not a Numeric String or not a Numeric Value >= -1
  • log fieldName, if defined, is null, or not a Boolean or not a String with value "t", "f", "true", "false". These String values must not be case sensitive.
  • visibility fieldName, if defined, is null, or not a Numeric String or a not Numeric Value >= 1 and <= 4="4" severity fieldName, if defined, is null, or not a Numeric String or not a Numeric Value >= 0 and <= 6
  • persistPolicy fieldName, if defined, is null, or not one of the following strings:
    "OnUpdate", "OnTimer", "NoMoreOftenThan", "OnUnregister", "Always", "Never". These String values must not be case sensitive.

Specified by:
isValid in interface Descriptor
Returns:
true if the values are legal.
Throws:
RuntimeOperationsException - If the validity checking fails for any reason, this exception will be thrown.

toXMLString

public String toXMLString()

Returns an XML String representing the descriptor.

The format is not defined, but an implementation must ensure that the string returned by this method can be used to build an equivalent descriptor when instantiated using the constructor DescriptorSupport(String inStr).

Fields which are not String objects will have toString() called on them to create the value. The value will be enclosed in parentheses. It is not guaranteed that you can reconstruct these objects unless they have been specifically set up to support toString() in a meaningful format and have a matching constructor that accepts a String in the same format.

If the descriptor is empty the following String is returned: <Descriptor></Descriptor>

Returns:
the XML string.
Throws:
RuntimeOperationsException - for illegal value for field Names or field Values. If the XML formatted string construction fails for any reason, this exception will be thrown.

toString

public String toString()
Returns a human readable string representing the descriptor. The string will be in the format of "fieldName=fieldValue,fieldName2=fieldValue2,..."
If there are no fields in the descriptor, then an empty String is returned.
If a fieldValue is an object then the toString() method is called on it and its returned value is used as the value for the field enclosed in parenthesis.

Overrides:
toString in class Object
Returns:
a string representation of the object.
Throws:
RuntimeOperationsException - for illegal value for field Names or field Values. If the descriptor string fails for any reason, this exception will be thrown.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


InvalidTargetObjectTypeException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.modelmbean
Class InvalidTargetObjectTypeException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.modelmbean.InvalidTargetObjectTypeException
All Implemented Interfaces:
Serializable
public class InvalidTargetObjectTypeException
extends Exception

Exception thrown when an invalid target object type is specified.

The serialVersionUID of this class is 1190536278266811217L.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
InvalidTargetObjectTypeException()
Default constructor.
InvalidTargetObjectTypeException(Exception e, String s)
Constructor taking an exception and a string.
InvalidTargetObjectTypeException(String s)
Constructor from a string.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidTargetObjectTypeException

public InvalidTargetObjectTypeException()
Default constructor.

InvalidTargetObjectTypeException

public InvalidTargetObjectTypeException(String s)
Constructor from a string.

Parameters:
s - String value that will be incorporated in the message for this exception.

InvalidTargetObjectTypeException

public InvalidTargetObjectTypeException(Exception e,
                                        String s)
Constructor taking an exception and a string.

Parameters:
e - Exception that we may have caught to reissue as an InvalidTargetObjectTypeException. The message will be used, and we may want to consider overriding the printStackTrace() methods to get data pointing back to original throw stack.
s - String value that will be incorporated in message for this exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ModelMBean

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.modelmbean
Interface ModelMBean

All Superinterfaces:
DynamicMBean, ModelMBeanNotificationBroadcaster, NotificationBroadcaster, PersistentMBean
All Known Implementing Classes:
RequiredModelMBean
public interface ModelMBean
extends DynamicMBean, PersistentMBean, ModelMBeanNotificationBroadcaster

This interface must be implemented by the ModelMBeans. An implementation of this interface must be shipped with every JMX Agent.

Java resources wishing to be manageable instantiate the ModelMBean using the MBeanServer's createMBean method. The resource then sets the ModelMBeanInfo (with Descriptors) for the ModelMBean instance. The attributes and operations exposed via the ModelMBeanInfo for the ModelMBean are accessible from MBeans, connectors/adaptors like other MBeans. Through the ModelMBeanInfo Descriptors, values and methods in the managed application can be defined and mapped to attributes and operations of the ModelMBean. This mapping can be defined during development in an XML formatted file or dynamically and programmatically at runtime.

Every ModelMBean which is instantiated in the MBeanServer becomes manageable: its attributes and operations become remotely accessible through the connectors/adaptors connected to that MBeanServer. A Java object cannot be registered in the MBeanServer unless it is a JMX compliant MBean. By instantiating a ModelMBean, resources are guaranteed that the MBean is valid.

MBeanException and RuntimeOperationsException must be thrown on every public method. This allows for wrapping exceptions from distributed communications (RMI, EJB, etc.). These exceptions do not have to be thrown by the implementation except in the scenarios described in the specification and javadoc.

Since:
1.5

Method Summary
void | setManagedResource(Object mr, String mr_type) Sets the instance handle of the object against which to execute all methods in this ModelMBean management interface (MBeanInfo and Descriptors).
void | setModelMBeanInfo(ModelMBeanInfo inModelMBeanInfo) Initializes a ModelMBean object using ModelMBeanInfo passed in.
Methods inherited from interface javax.management.DynamicMBean
getAttribute, getAttributes, getMBeanInfo, invoke, setAttribute, setAttributes
Methods inherited from interface javax.management.PersistentMBean
load, store
Methods inherited from interface javax.management.modelmbean.ModelMBeanNotificationBroadcaster
addAttributeChangeNotificationListener, removeAttributeChangeNotificationListener, sendAttributeChangeNotification, sendAttributeChangeNotification, sendNotification, sendNotification
Methods inherited from interface javax.management.NotificationBroadcaster
addNotificationListener, getNotificationInfo, removeNotificationListener

Method Detail

setModelMBeanInfo

void setModelMBeanInfo(ModelMBeanInfo inModelMBeanInfo)
                       throws MBeanException,
                              RuntimeOperationsException
Initializes a ModelMBean object using ModelMBeanInfo passed in. This method makes it possible to set a customized ModelMBeanInfo on the ModelMBean as long as it is not registered with the MBeanServer.
Once the ModelMBean's ModelMBeanInfo (with Descriptors) are customized and set on the ModelMBean, the ModelMBean can be registered with the MBeanServer.

If the ModelMBean is currently registered, this method throws a RuntimeOperationsException wrapping an IllegalStateException

Parameters:
inModelMBeanInfo - The ModelMBeanInfo object to be used by the ModelMBean.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException -
  • Wraps an IllegalArgumentException if the MBeanInfo passed in parameter is null.
  • Wraps an IllegalStateException if the ModelMBean is currently registered in the MBeanServer.

setManagedResource

void setManagedResource(Object mr,
                        String mr_type)
                        throws MBeanException,
                               RuntimeOperationsException,
                               InstanceNotFoundException,
                               InvalidTargetObjectTypeException
Sets the instance handle of the object against which to execute all methods in this ModelMBean management interface (MBeanInfo and Descriptors).

Parameters:
mr - Object that is the managed resource
mr_type - The type of reference for the managed resource. Can be: ObjectReference, Handle, IOR, EJBHandle, RMIReference. If the MBeanServer cannot process the mr_type passed in, an InvalidTargetTypeException will be thrown.
Throws:
MBeanException - The initializer of the object has thrown an exception.
RuntimeOperationsException - Wraps an IllegalArgumentException: The managed resource type passed in parameter is null.
InstanceNotFoundException - The managed resource object could not be found
InvalidTargetObjectTypeException - The managed resource type cannot be processed by the ModelMBean or JMX Agent.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ModelMBeanAttributeInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.modelmbean
Class ModelMBeanAttributeInfo

java.lang.Object
    extended by  javax.management.MBeanFeatureInfo
        extended by  javax.management.MBeanAttributeInfo
            extended by  javax.management.modelmbean.ModelMBeanAttributeInfo
All Implemented Interfaces:
Serializable, Cloneable, DescriptorAccess, DescriptorRead
public class ModelMBeanAttributeInfo
extends MBeanAttributeInfo
implements DescriptorAccess

The ModelMBeanAttributeInfo object describes an attribute of the ModelMBean. It is a subclass of MBeanAttributeInfo with the addition of an associated Descriptor and an implementation of the DescriptorAccess interface.

The fields in the descriptor are defined, but not limited to, the following:

 name           : attribute name
 descriptorType : must be "attribute"
 value          : current value for attribute
 default        : default value for attribute
 displayName    : name of attribute to be used in displays
 getMethod      : name of operation descriptor for get method
 setMethod      : name of operation descriptor for set method
 protocolMap    : object which implements the Descriptor interface: mappings must be appropriate for the attribute
                  and entries can be updated or augmented at runtime.
 persistPolicy  : OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never
 persistPeriod  : seconds - frequency of persist cycle. Used when persistPolicy is"OnTimer" or "NoMoreOftenThan".
 currencyTimeLimit : how long value is valid, <0 never, =0 always, >0 seconds
 lastUpdatedTimeStamp : when value was set
 visibility     : 1-4 where 1: always visible 4: rarely visible
 presentationString : xml formatted string to allow presentation of data
The default descriptor contains the name, descriptorType and displayName fields.

Note: because of inconsistencies in previous versions of this specification, it is recommended not to use negative or zero values for currencyTimeLimit. To indicate that a cached value is never valid, omit the currencyTimeLimit field. To indicate that it is always valid, use a very large number for this field.

The serialVersionUID of this class is 6181543027787327345L.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.management.MBeanFeatureInfo
description, name
Constructor Summary
ModelMBeanAttributeInfo(ModelMBeanAttributeInfo inInfo)
Constructs a new ModelMBeanAttributeInfo object from this ModelMBeanAttributeInfo Object.
ModelMBeanAttributeInfo(String name, String description, Method getter, Method setter)
Constructs a ModelMBeanAttributeInfo object with a default descriptor.
ModelMBeanAttributeInfo(String name, String description, Method getter, Method setter, Descriptor descriptor)
Constructs a ModelMBeanAttributeInfo object.
ModelMBeanAttributeInfo(String name, String type, String description, boolean isReadable, boolean isWritable, boolean isIs)
Constructs a ModelMBeanAttributeInfo object with a default descriptor.
ModelMBeanAttributeInfo(String name, String type, String description, boolean isReadable, boolean isWritable, boolean isIs, Descriptor descriptor)
Constructs a ModelMBeanAttributeInfo object with a default descriptor.
Method Summary
Object | clone() Creates and returns a new ModelMBeanAttributeInfo which is a duplicate of this ModelMBeanAttributeInfo.
Descriptor | getDescriptor() Gets a copy of the associated Descriptor for the ModelMBeanAttributeInfo.
void | setDescriptor(Descriptor inDescriptor) Sets associated Descriptor (full replace) for the ModelMBeanAttributeDescriptor.
String | toString() Returns a human-readable version of the ModelMBeanAttributeInfo instance.
Methods inherited from class javax.management.MBeanAttributeInfo
equals, getType, hashCode, isIs, isReadable, isWritable
Methods inherited from class javax.management.MBeanFeatureInfo
getDescription, getName
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ModelMBeanAttributeInfo

public ModelMBeanAttributeInfo(String name,
                               String description,
                               Method getter,
                               Method setter)
                        throws IntrospectionException
Constructs a ModelMBeanAttributeInfo object with a default descriptor. The Descriptor of the constructed object will include fields contributed by any annotations on the Method objects that contain the DescriptorKey meta-annotation.

Parameters:
name - The name of the attribute.
description - A human readable description of the attribute. Optional.
getter - The method used for reading the attribute value. May be null if the property is write-only.
setter - The method used for writing the attribute value. May be null if the attribute is read-only.
Throws:
IntrospectionException - There is a consistency problem in the definition of this attribute.

ModelMBeanAttributeInfo

public ModelMBeanAttributeInfo(String name,
                               String description,
                               Method getter,
                               Method setter,
                               Descriptor descriptor)
                        throws IntrospectionException
Constructs a ModelMBeanAttributeInfo object. The Descriptor of the constructed object will include fields contributed by any annotations on the Method objects that contain the DescriptorKey meta-annotation.

Parameters:
name - The name of the attribute.
description - A human readable description of the attribute. Optional.
getter - The method used for reading the attribute value. May be null if the property is write-only.
setter - The method used for writing the attribute value. May be null if the attribute is read-only.
descriptor - An instance of Descriptor containing the appropriate metadata for this instance of the Attribute. If it is null, then a default descriptor will be created. If the descriptor does not contain the field "displayName" this field is added in the descriptor with its default value.
Throws:
IntrospectionException - There is a consistency problem in the definition of this attribute.
RuntimeOperationsException - Wraps an IllegalArgumentException. The descriptor is invalid, or descriptor field "name" is not equal to name parameter, or descriptor field "DescriptorType" is not equal to "attribute".

ModelMBeanAttributeInfo

public ModelMBeanAttributeInfo(String name,
                               String type,
                               String description,
                               boolean isReadable,
                               boolean isWritable,
                               boolean isIs)
Constructs a ModelMBeanAttributeInfo object with a default descriptor.

Parameters:
name - The name of the attribute
type - The type or class name of the attribute
description - A human readable description of the attribute.
isReadable - True if the attribute has a getter method, false otherwise.
isWritable - True if the attribute has a setter method, false otherwise.
isIs - True if the attribute has an "is" getter, false otherwise.

ModelMBeanAttributeInfo

public ModelMBeanAttributeInfo(String name,
                               String type,
                               String description,
                               boolean isReadable,
                               boolean isWritable,
                               boolean isIs,
                               Descriptor descriptor)
Constructs a ModelMBeanAttributeInfo object with a default descriptor.

Parameters:
name - The name of the attribute
type - The type or class name of the attribute
description - A human readable description of the attribute.
isReadable - True if the attribute has a getter method, false otherwise.
isWritable - True if the attribute has a setter method, false otherwise.
isIs - True if the attribute has an "is" getter, false otherwise.
descriptor - An instance of Descriptor containing the appropriate metadata for this instance of the Attribute. If it is null then a default descriptor will be created. If the descriptor does not contain the field "displayName" this field is added in the descriptor with its default value.
Throws:
RuntimeOperationsException - Wraps an IllegalArgumentException. The descriptor is invalid, or descriptor field "name" is not equal to name parameter, or descriptor field "DescriptorType" is not equal to "attribute".

ModelMBeanAttributeInfo

public ModelMBeanAttributeInfo(ModelMBeanAttributeInfo inInfo)
Constructs a new ModelMBeanAttributeInfo object from this ModelMBeanAttributeInfo Object. A default descriptor will be created.

Parameters:
inInfo - the ModelMBeanAttributeInfo to be duplicated
Method Detail

getDescriptor

public Descriptor getDescriptor()
Gets a copy of the associated Descriptor for the ModelMBeanAttributeInfo.

Specified by:
getDescriptor in interface DescriptorRead
Overrides:
getDescriptor in class MBeanFeatureInfo
Returns:
Descriptor associated with the ModelMBeanAttributeInfo object.
See Also:
setDescriptor(javax.management.Descriptor)

setDescriptor

public void setDescriptor(Descriptor inDescriptor)
Sets associated Descriptor (full replace) for the ModelMBeanAttributeDescriptor. If the new Descriptor is null, then the associated Descriptor reverts to a default descriptor. The Descriptor is validated before it is assigned. If the new Descriptor is invalid, then a RuntimeOperationsException wrapping an IllegalArgumentException is thrown.

Specified by:
setDescriptor in interface DescriptorAccess
Parameters:
inDescriptor - replaces the Descriptor associated with the ModelMBeanAttributeInfo
Throws:
RuntimeOperationsException - Wraps an IllegalArgumentException for an invalid Descriptor
See Also:
getDescriptor()

clone

public Object clone()
Creates and returns a new ModelMBeanAttributeInfo which is a duplicate of this ModelMBeanAttributeInfo.

Overrides:
clone in class MBeanAttributeInfo
Returns:
a clone of this instance.
Throws:
RuntimeOperationsException - for illegal value for field Names or field Values. If the descriptor construction fails for any reason, this exception will be thrown.
See Also:
Cloneable

toString

public String toString()
Returns a human-readable version of the ModelMBeanAttributeInfo instance.

Overrides:
toString in class MBeanAttributeInfo
Returns:
a string representation of the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ModelMBeanConstructorInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.modelmbean
Class ModelMBeanConstructorInfo

java.lang.Object
    extended by  javax.management.MBeanFeatureInfo
        extended by  javax.management.MBeanConstructorInfo
            extended by  javax.management.modelmbean.ModelMBeanConstructorInfo
All Implemented Interfaces:
Serializable, Cloneable, DescriptorAccess, DescriptorRead
public class ModelMBeanConstructorInfo
extends MBeanConstructorInfo
implements DescriptorAccess

The ModelMBeanConstructorInfo object describes a constructor of the ModelMBean. It is a subclass of MBeanConstructorInfo with the addition of an associated Descriptor and an implementation of the DescriptorAccess interface.

 The fields in the descriptor are defined, but not limited to, the following:

 name           : constructor name
 descriptorType : must be "operation"
 role           : must be "constructor"
 displayName    : human readable name of constructor
 visibility            : 1-4 where 1: always visible 4: rarely visible
 presentationString :  xml formatted string to describe how to present operation

The persistPolicy and currencyTimeLimit fields are meaningless for constructors, but are not considered invalid.

The default descriptor will have the name, descriptorType, displayName and role fields.

The serialVersionUID of this class is 3862947819818064362L.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.management.MBeanFeatureInfo
description, name
Constructor Summary
ModelMBeanConstructorInfo(String description, Constructor constructorMethod)
Constructs a ModelMBeanConstructorInfo object with a default descriptor.
ModelMBeanConstructorInfo(String description, Constructor constructorMethod, Descriptor descriptor)
Constructs a ModelMBeanConstructorInfo object.
ModelMBeanConstructorInfo(String name, String description, MBeanParameterInfo[] signature)
Constructs a ModelMBeanConstructorInfo object with a default descriptor.
ModelMBeanConstructorInfo(String name, String description, MBeanParameterInfo[] signature, Descriptor descriptor)
Constructs a ModelMBeanConstructorInfo object.
Method Summary
Object | clone() Creates and returns a new ModelMBeanConstructorInfo which is a duplicate of this ModelMBeanConstructorInfo.
Descriptor | getDescriptor() Returns a copy of the associated Descriptor.
void | setDescriptor(Descriptor inDescriptor) Sets associated Descriptor (full replace) of ModelMBeanConstructorInfo.
String | toString() Returns a string containing the entire contents of the ModelMBeanConstructorInfo in human readable form.
Methods inherited from class javax.management.MBeanConstructorInfo
equals, getSignature, hashCode
Methods inherited from class javax.management.MBeanFeatureInfo
getDescription, getName
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ModelMBeanConstructorInfo

public ModelMBeanConstructorInfo(String description,
                                 Constructor constructorMethod)
Constructs a ModelMBeanConstructorInfo object with a default descriptor. The Descriptor of the constructed object will include fields contributed by any annotations on the Constructor object that contain the DescriptorKey meta-annotation.

Parameters:
description - A human readable description of the constructor.
constructorMethod - The java.lang.reflect.Constructor object describing the MBean constructor.

ModelMBeanConstructorInfo

public ModelMBeanConstructorInfo(String description,
                                 Constructor constructorMethod,
                                 Descriptor descriptor)
Constructs a ModelMBeanConstructorInfo object. The Descriptor of the constructed object will include fields contributed by any annotations on the Constructor object that contain the DescriptorKey meta-annotation.

Parameters:
description - A human readable description of the constructor.
constructorMethod - The java.lang.reflect.Constructor object describing the ModelMBean constructor.
descriptor - An instance of Descriptor containing the appropriate metadata for this instance of the ModelMBeanConstructorInfo. If it is null, then a default descriptor will be created.If the descriptor does not contain the field "displayName" this fields is added in the descriptor with its default value.
Throws:
RuntimeOperationsException - Wraps an IllegalArgumentException. The descriptor is invalid, or descriptor field "name" is not equal to name parameter, or descriptor field "DescriptorType" is not equal to "operation" or descriptor field "role" is not equal to "constructor".

ModelMBeanConstructorInfo

public ModelMBeanConstructorInfo(String name,
                                 String description,
                                 MBeanParameterInfo[] signature)
Constructs a ModelMBeanConstructorInfo object with a default descriptor.

Parameters:
name - The name of the constructor.
description - A human readable description of the constructor.
signature - MBeanParameterInfo object array describing the parameters(arguments) of the constructor.

ModelMBeanConstructorInfo

public ModelMBeanConstructorInfo(String name,
                                 String description,
                                 MBeanParameterInfo[] signature,
                                 Descriptor descriptor)
Constructs a ModelMBeanConstructorInfo object.

Parameters:
name - The name of the constructor.
description - A human readable description of the constructor.
signature - MBeanParameterInfo objects describing the parameters(arguments) of the constructor.
descriptor - An instance of Descriptor containing the appropriate metadata for this instance of the MBeanConstructorInfo. If it is null then a default descriptor will be created. If the descriptor does not contain the field "displayName" this field is added in the descriptor with its default value.
Throws:
RuntimeOperationsException - Wraps an IllegalArgumentException. The descriptor is invalid, or descriptor field "name" is not equal to name parameter, or descriptor field "DescriptorType" is not equal to "operation" or descriptor field "role" is not equal to "constructor".
Method Detail

clone

public Object clone()
Creates and returns a new ModelMBeanConstructorInfo which is a duplicate of this ModelMBeanConstructorInfo.

Overrides:
clone in class MBeanConstructorInfo
Returns:
a clone of this instance.
See Also:
Cloneable

getDescriptor

public Descriptor getDescriptor()
Returns a copy of the associated Descriptor.

Specified by:
getDescriptor in interface DescriptorRead
Overrides:
getDescriptor in class MBeanFeatureInfo
Returns:
Descriptor associated with the ModelMBeanConstructorInfo object.
See Also:
setDescriptor(javax.management.Descriptor)

setDescriptor

public void setDescriptor(Descriptor inDescriptor)
Sets associated Descriptor (full replace) of ModelMBeanConstructorInfo. If the new Descriptor is null, then the associated Descriptor reverts to a default descriptor. The Descriptor is validated before it is assigned. If the new Descriptor is invalid, then a RuntimeOperationsException wrapping an IllegalArgumentException is thrown.

Specified by:
setDescriptor in interface DescriptorAccess
Parameters:
inDescriptor - replaces the Descriptor associated with the ModelMBeanConstructor. If the descriptor does not contain the field "displayName" this field is added in the descriptor with its default value.
Throws:
RuntimeOperationsException - Wraps an IllegalArgumentException. The descriptor is invalid, or descriptor field "name" is not equal to name parameter, or descriptor field "DescriptorType" is not equal to "operation" or descriptor field "role" is not equal to "constructor".
See Also:
getDescriptor()

toString

public String toString()
Returns a string containing the entire contents of the ModelMBeanConstructorInfo in human readable form.

Overrides:
toString in class MBeanConstructorInfo
Returns:
a string representation of the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ModelMBeanInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.modelmbean
Interface ModelMBeanInfo

All Known Implementing Classes:
ModelMBeanInfoSupport
public interface ModelMBeanInfo

This interface is implemented by the ModelMBeanInfo for every ModelMBean. An implementation of this interface must be shipped with every JMX Agent.

Java resources wishing to be manageable instantiate the ModelMBean using the MBeanServer's createMBean method. The resource then sets the ModelMBeanInfo and Descriptors for the ModelMBean instance. The attributes, operations, and notifications exposed via the ModelMBeanInfo for the ModelMBean comprise the management interface and are accessible from MBeans, connectors/adaptors like other MBeans. Through the Descriptors, values and methods in the managed application can be defined and mapped to attributes and operations of the ModelMBean. This mapping can be defined during development in a file or dynamically and programmatically at runtime.

Every ModelMBean which is instantiated in the MBeanServer becomes manageable: its attributes, operations, and notifications become remotely accessible through the connectors/adaptors connected to that MBeanServer. A Java object cannot be registered in the MBeanServer unless it is a JMX compliant MBean. By instantiating a ModelMBean, resources are guaranteed that the MBean is valid. MBeanException and RuntimeOperationsException must be thrown on every public method. This allows for wrapping exceptions from distributed communications (RMI, EJB, etc.)

Since:
1.5

Method Summary
Object | clone() Creates and returns a copy of this object.
ModelMBeanAttributeInfo | getAttribute(String inName) Returns a ModelMBeanAttributeInfo requested by name.
MBeanAttributeInfo[] | getAttributes() Returns the list of attributes exposed for management.
String | getClassName() Returns the name of the Java class of the MBean described by this MBeanInfo.
MBeanConstructorInfo[] | getConstructors() Returns the list of the public constructors of the MBean.
String | getDescription() Returns a human readable description of the MBean.
Descriptor | getDescriptor(String inDescriptorName, String inDescriptorType) Returns a Descriptor requested by name and descriptorType.
Descriptor[] | getDescriptors(String inDescriptorType) Returns a Descriptor array consisting of all Descriptors for the ModelMBeanInfo of type inDescriptorType.
Descriptor | getMBeanDescriptor() Returns the ModelMBean's descriptor which contains MBean wide policies.
ModelMBeanNotificationInfo | getNotification(String inName) Returns a ModelMBeanNotificationInfo requested by name.
MBeanNotificationInfo[] | getNotifications() Returns the list of the notifications emitted by the MBean.
ModelMBeanOperationInfo | getOperation(String inName) Returns a ModelMBeanOperationInfo requested by name.
MBeanOperationInfo[] | getOperations() Returns the list of operations of the MBean.
void | setDescriptor(Descriptor inDescriptor, String inDescriptorType) Sets descriptors in the info array of type inDescriptorType for the ModelMBean.
void | setDescriptors(Descriptor[] inDescriptors) Adds or replaces descriptors in the ModelMBeanInfo.
void | setMBeanDescriptor(Descriptor inDescriptor) Sets the ModelMBean's descriptor.

Method Detail

getDescriptors

Descriptor[] getDescriptors(String inDescriptorType)
                            throws MBeanException,
                                   RuntimeOperationsException
Returns a Descriptor array consisting of all Descriptors for the ModelMBeanInfo of type inDescriptorType.

Parameters:
inDescriptorType - value of descriptorType field that must be set for the descriptor to be returned. Must be "mbean", "attribute", "operation", "constructor" or "notification". If it is null or empty then all types will be returned.
Returns:
Descriptor array containing all descriptors for the ModelMBean if type inDescriptorType.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException when the descriptorType in parameter is not one of: "mbean", "attribute", "operation", "constructor", "notification", empty or null.
See Also:
setDescriptors(javax.management.Descriptor[])

setDescriptors

void setDescriptors(Descriptor[] inDescriptors)
                    throws MBeanException,
                           RuntimeOperationsException
Adds or replaces descriptors in the ModelMBeanInfo.

Parameters:
inDescriptors - The descriptors to be set in the ModelMBeanInfo. Null elements of the list will be ignored. All descriptors must have name and descriptorType fields.
Throws:
RuntimeOperationsException - Wraps an IllegalArgumentException for a null or invalid descriptor.
MBeanException - Wraps a distributed communication Exception.
See Also:
getDescriptors(java.lang.String)

getDescriptor

Descriptor getDescriptor(String inDescriptorName,
                         String inDescriptorType)
                         throws MBeanException,
                                RuntimeOperationsException
Returns a Descriptor requested by name and descriptorType.

Parameters:
inDescriptorName - The name of the descriptor.
inDescriptorType - The type of the descriptor being requested. If this is null or empty then all types are searched. Valid types are 'mbean', 'attribute', 'constructor' 'operation', and 'notification'. This value will be equal to the 'descriptorType' field in the descriptor that is returned.
Returns:
Descriptor containing the descriptor for the ModelMBean with the same name and descriptorType. If no descriptor is found, null is returned.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException for a null descriptor name or null or invalid type. The type must be "mbean","attribute", "constructor", "operation", or "notification".
See Also:
setDescriptor(javax.management.Descriptor, java.lang.String)

setDescriptor

void setDescriptor(Descriptor inDescriptor,
                   String inDescriptorType)
                   throws MBeanException,
                          RuntimeOperationsException
Sets descriptors in the info array of type inDescriptorType for the ModelMBean. The setDescriptor method of the corresponding ModelMBean*Info will be called to set the specified descriptor.

Parameters:
inDescriptor - The descriptor to be set in the ModelMBean. It must NOT be null. All descriptors must have name and descriptorType fields.
inDescriptorType - The type of the descriptor being set. If this is null then the descriptorType field in the descriptor is used. If specified this value must be set in the descriptorType field in the descriptor. Must be "mbean","attribute", "constructor", "operation", or "notification".
Throws:
RuntimeOperationsException - Wraps an IllegalArgumentException for illegal or null arguments or if the name field of the descriptor is not found in the corresponding MBeanAttributeInfo or MBeanConstructorInfo or MBeanNotificationInfo or MBeanOperationInfo.
MBeanException - Wraps a distributed communication Exception.
See Also:
getDescriptor(java.lang.String, java.lang.String)

getMBeanDescriptor

Descriptor getMBeanDescriptor()
                              throws MBeanException,
                                     RuntimeOperationsException
Returns the ModelMBean's descriptor which contains MBean wide policies. This descriptor contains metadata about the MBean and default policies for persistence and caching.

The fields in the descriptor are defined, but not limited to, the following:

 name           : MBean name
 descriptorType : must be "mbean"
 displayName    : name of attribute to be used in displays
 persistPolicy  : OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never
 persistLocation : The fully qualified directory name where the MBean should be persisted (if appropriate)
 persistFile    : File name into which the MBean should be persisted
 persistPeriod  : seconds - frequency of persist cycle for OnTime and NoMoreOftenThan PersistPolicy
 currencyTimeLimit : how long value is valid, <0 never, =0 always, >0 seconds
 log            : where t: log all notifications f: log no notifications
 logfile        : fully qualified filename to log events to
 visibility     : 1-4 where 1: always visible 4: rarely visible
 export         : name to be used to export/expose this MBean so that it is findable by
                  other JMX Agents.
 presentationString : xml formatted string to allow presentation of data to be associated with the MBean.

The default descriptor is: name=mbeanName,descriptorType=mbean, displayName=this.getClassName(), persistPolicy=never,log=F,export=F,visibility=1 If the descriptor does not contain all these fields, they will be added with these default values.

Note: because of inconsistencies in previous versions of this specification, it is recommended not to use negative or zero values for currencyTimeLimit. To indicate that a cached value is never valid, omit the currencyTimeLimit field. To indicate that it is always valid, use a very large number for this field.

Returns:
the MBean descriptor.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - a RuntimeException occurred while getting the descriptor.
See Also:
setMBeanDescriptor(javax.management.Descriptor)

setMBeanDescriptor

void setMBeanDescriptor(Descriptor inDescriptor)
                        throws MBeanException,
                               RuntimeOperationsException
Sets the ModelMBean's descriptor. This descriptor contains default, MBean wide metadata about the MBean and default policies for persistence and caching. This operation does a complete replacement of the descriptor, no merging is done. If the descriptor to set to is null then the default descriptor will be created. The default descriptor is: name=mbeanName,descriptorType=mbean, displayName=this.getClassName(), persistPolicy=never,log=F,export=F,visibility=1 If the descriptor does not contain all these fields, they will be added with these default values. See getMBeanDescriptor method javadoc for description of valid field names.

Parameters:
inDescriptor - the descriptor to set.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException for invalid descriptor.
See Also:
getMBeanDescriptor()

getAttribute

ModelMBeanAttributeInfo getAttribute(String inName)
                                     throws MBeanException,
                                            RuntimeOperationsException
Returns a ModelMBeanAttributeInfo requested by name.

Parameters:
inName - The name of the ModelMBeanAttributeInfo to get. If no ModelMBeanAttributeInfo exists for this name null is returned.
Returns:
the attribute info for the named attribute, or null if there is none.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException for a null attribute name.

getOperation

ModelMBeanOperationInfo getOperation(String inName)
                                     throws MBeanException,
                                            RuntimeOperationsException
Returns a ModelMBeanOperationInfo requested by name.

Parameters:
inName - The name of the ModelMBeanOperationInfo to get. If no ModelMBeanOperationInfo exists for this name null is returned.
Returns:
the operation info for the named operation, or null if there is none.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException for a null operation name.

getNotification

ModelMBeanNotificationInfo getNotification(String inName)
                                           throws MBeanException,
                                                  RuntimeOperationsException
Returns a ModelMBeanNotificationInfo requested by name.

Parameters:
inName - The name of the ModelMBeanNotificationInfo to get. If no ModelMBeanNotificationInfo exists for this name null is returned.
Returns:
the info for the named notification, or null if there is none.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException for a null notification name.

clone

Object clone()
Creates and returns a copy of this object.

getAttributes

MBeanAttributeInfo[] getAttributes()
Returns the list of attributes exposed for management. Each attribute is described by an MBeanAttributeInfo object.

Returns:
An array of MBeanAttributeInfo objects.

getClassName

String getClassName()
Returns the name of the Java class of the MBean described by this MBeanInfo.

Returns:
the Java class name.

getConstructors

MBeanConstructorInfo[] getConstructors()
Returns the list of the public constructors of the MBean. Each constructor is described by an MBeanConstructorInfo object.

Returns:
An array of MBeanConstructorInfo objects.

getDescription

String getDescription()
Returns a human readable description of the MBean.

Returns:
the description.

getNotifications

MBeanNotificationInfo[] getNotifications()
Returns the list of the notifications emitted by the MBean. Each notification is described by an MBeanNotificationInfo object.

In addition to any notification specified by the application, a ModelMBean may always send also two additional notifications:

  • One with descriptor name "GENERIC" and displayName "jmx.modelmbean.generic"
  • Second is a standard attribute change notification with descriptor name "ATTRIBUTE_CHANGE" and displayName "jmx.attribute.change"
Thus any implementation of ModelMBeanInfo should always add those two notifications in addition to those specified by the application.

Returns:
An array of MBeanNotificationInfo objects.

getOperations

MBeanOperationInfo[] getOperations()
Returns the list of operations of the MBean. Each operation is described by an MBeanOperationInfo object.

Returns:
An array of MBeanOperationInfo objects.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ModelMBeanInfoSupport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.modelmbean
Class ModelMBeanInfoSupport

java.lang.Object
    extended by  javax.management.MBeanInfo
        extended by  javax.management.modelmbean.ModelMBeanInfoSupport
All Implemented Interfaces:
Serializable, Cloneable, DescriptorRead, ModelMBeanInfo
public class ModelMBeanInfoSupport
extends MBeanInfo
implements ModelMBeanInfo

This class represents the meta data for ModelMBeans. Descriptors have been added on the meta data objects.

Java resources wishing to be manageable instantiate the ModelMBean using the MBeanServer's createMBean method. The resource then sets the ModelMBeanInfo and Descriptors for the ModelMBean instance. The attributes and operations exposed via the ModelMBeanInfo for the ModelMBean are accessible from MBeans, connectors/adaptors like other MBeans. Through the Descriptors, values and methods in the managed application can be defined and mapped to attributes and operations of the ModelMBean. This mapping can be defined during development in a file or dynamically and programmatically at runtime.

Every ModelMBean which is instantiated in the MBeanServer becomes manageable: its attributes and operations become remotely accessible through the connectors/adaptors connected to that MBeanServer. A Java object cannot be registered in the MBeanServer unless it is a JMX compliant MBean. By instantiating a ModelMBean, resources are guaranteed that the MBean is valid. MBeanException and RuntimeOperationsException must be thrown on every public method. This allows for wrapping exceptions from distributed communications (RMI, EJB, etc.)

The serialVersionUID of this class is -1935722590756516193L.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
ModelMBeanInfoSupport(ModelMBeanInfo mbi)
Constructs a ModelMBeanInfoSupport which is a duplicate of the given ModelMBeanInfo.
ModelMBeanInfoSupport(String className, String description, ModelMBeanAttributeInfo[] attributes, ModelMBeanConstructorInfo[] constructors, ModelMBeanOperationInfo[] operations, ModelMBeanNotificationInfo[] notifications)
Creates a ModelMBeanInfoSupport with the provided information, but the descriptor is a default.
ModelMBeanInfoSupport(String className, String description, ModelMBeanAttributeInfo[] attributes, ModelMBeanConstructorInfo[] constructors, ModelMBeanOperationInfo[] operations, ModelMBeanNotificationInfo[] notifications, Descriptor mbeandescriptor)
Creates a ModelMBeanInfoSupport with the provided information and the descriptor given in parameter.
Method Summary
Object | clone() Returns a shallow clone of this instance.
ModelMBeanAttributeInfo | getAttribute(String inName) Returns a ModelMBeanAttributeInfo requested by name.
ModelMBeanConstructorInfo | getConstructor(String inName) Returns the ModelMBeanConstructorInfo requested by name.
Descriptor | getDescriptor() Get the descriptor of this MBeanInfo.
Descriptor | getDescriptor(String inDescriptorName) Returns a Descriptor requested by name.
Descriptor | getDescriptor(String inDescriptorName, String inDescriptorType) Returns a Descriptor requested by name and descriptorType.
Descriptor[] | getDescriptors(String inDescriptorType) Returns a Descriptor array consisting of all Descriptors for the ModelMBeanInfo of type inDescriptorType.
Descriptor | getMBeanDescriptor() Returns the ModelMBean's descriptor which contains MBean wide policies.
ModelMBeanNotificationInfo | getNotification(String inName) Returns a ModelMBeanNotificationInfo requested by name.
ModelMBeanOperationInfo | getOperation(String inName) Returns a ModelMBeanOperationInfo requested by name.
void | setDescriptor(Descriptor inDescriptor, String inDescriptorType) Sets descriptors in the info array of type inDescriptorType for the ModelMBean.
void | setDescriptors(Descriptor[] inDescriptors) Adds or replaces descriptors in the ModelMBeanInfo.
void | setMBeanDescriptor(Descriptor inMBeanDescriptor) Sets the ModelMBean's descriptor.
Methods inherited from class javax.management.MBeanInfo
equals, getAttributes, getClassName, getConstructors, getDescription, getNotifications, getOperations, hashCode, toString
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface javax.management.modelmbean.ModelMBeanInfo
getAttributes, getClassName, getConstructors, getDescription, getNotifications, getOperations

Constructor Detail

ModelMBeanInfoSupport

public ModelMBeanInfoSupport(ModelMBeanInfo mbi)
Constructs a ModelMBeanInfoSupport which is a duplicate of the given ModelMBeanInfo. The returned object is a shallow copy of the given object. Neither the Descriptor nor the contained arrays (ModelMBeanAttributeInfo[] etc) are cloned. This method is chiefly of interest to modify the Descriptor of the returned instance via setDescriptor without affecting the Descriptor of the original object.

Parameters:
mbi - the ModelMBeanInfo instance from which the ModelMBeanInfo being created is initialized.

ModelMBeanInfoSupport

public ModelMBeanInfoSupport(String className,
                             String description,
                             ModelMBeanAttributeInfo[] attributes,
                             ModelMBeanConstructorInfo[] constructors,
                             ModelMBeanOperationInfo[] operations,
                             ModelMBeanNotificationInfo[] notifications)
Creates a ModelMBeanInfoSupport with the provided information, but the descriptor is a default. The default descriptor is: name=mbeanName, descriptorType=mbean, displayName=ClassName, persistPolicy=never, log=F, visibility=1

Parameters:
className - classname of the MBean
description - human readable description of the ModelMBean
attributes - array of ModelMBeanAttributeInfo objects which have descriptors
constructors - array of ModelMBeanConstructorInfo objects which have descriptors
operations - array of ModelMBeanOperationInfo objects which have descriptors
notifications - array of ModelMBeanNotificationInfo objects which have descriptors

ModelMBeanInfoSupport

public ModelMBeanInfoSupport(String className,
                             String description,
                             ModelMBeanAttributeInfo[] attributes,
                             ModelMBeanConstructorInfo[] constructors,
                             ModelMBeanOperationInfo[] operations,
                             ModelMBeanNotificationInfo[] notifications,
                             Descriptor mbeandescriptor)
Creates a ModelMBeanInfoSupport with the provided information and the descriptor given in parameter.

Parameters:
className - classname of the MBean
description - human readable description of the ModelMBean
attributes - array of ModelMBeanAttributeInfo objects which have descriptors
constructors - array of ModelMBeanConstructorInfo objects which have descriptor
operations - array of ModelMBeanOperationInfo objects which have descriptor
notifications - array of ModelMBeanNotificationInfo objects which have descriptor
mbeandescriptor - descriptor to be used as the MBeanDescriptor containing MBean wide policy. If the descriptor is null, a default descriptor will be constructed. The default descriptor is: name=className, descriptorType=mbean, displayName=className, persistPolicy=never, log=F, visibility=1. If the descriptor does not contain all these fields, they will be added with these default values.
Throws:
RuntimeOperationsException - Wraps an IllegalArgumentException for invalid descriptor passed in parameter. (see getMBeanDescriptor for the definition of a valid MBean descriptor.)
Method Detail

clone

public Object clone()
Returns a shallow clone of this instance. Neither the Descriptor nor the contained arrays (ModelMBeanAttributeInfo[] etc) are cloned. This method is chiefly of interest to modify the Descriptor of the clone via setDescriptor without affecting the Descriptor of the original object.

Specified by:
clone in interface ModelMBeanInfo
Overrides:
clone in class MBeanInfo
Returns:
a shallow clone of this instance.
See Also:
Cloneable

getDescriptors

public Descriptor[] getDescriptors(String inDescriptorType)
                            throws MBeanException,
                                   RuntimeOperationsException
Description copied from interface: ModelMBeanInfo
Returns a Descriptor array consisting of all Descriptors for the ModelMBeanInfo of type inDescriptorType.

Specified by:
getDescriptors in interface ModelMBeanInfo
Parameters:
inDescriptorType - value of descriptorType field that must be set for the descriptor to be returned. Must be "mbean", "attribute", "operation", "constructor" or "notification". If it is null or empty then all types will be returned.
Returns:
Descriptor array containing all descriptors for the ModelMBean if type inDescriptorType.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException when the descriptorType in parameter is not one of: "mbean", "attribute", "operation", "constructor", "notification", empty or null.
See Also:
ModelMBeanInfo.setDescriptors(javax.management.Descriptor[])

setDescriptors

public void setDescriptors(Descriptor[] inDescriptors)
                    throws MBeanException,
                           RuntimeOperationsException
Description copied from interface: ModelMBeanInfo
Adds or replaces descriptors in the ModelMBeanInfo.

Specified by:
setDescriptors in interface ModelMBeanInfo
Parameters:
inDescriptors - The descriptors to be set in the ModelMBeanInfo. Null elements of the list will be ignored. All descriptors must have name and descriptorType fields.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException for a null or invalid descriptor.
See Also:
ModelMBeanInfo.getDescriptors(java.lang.String)

getDescriptor

public Descriptor getDescriptor(String inDescriptorName)
                         throws MBeanException,
                                RuntimeOperationsException
Returns a Descriptor requested by name.

Parameters:
inDescriptorName - The name of the descriptor.
Returns:
Descriptor containing a descriptor for the ModelMBean with the same name. If no descriptor is found, null is returned.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException for null name.
See Also:
setDescriptor(javax.management.Descriptor, java.lang.String)

getDescriptor

public Descriptor getDescriptor(String inDescriptorName,
                                String inDescriptorType)
                         throws MBeanException,
                                RuntimeOperationsException
Description copied from interface: ModelMBeanInfo
Returns a Descriptor requested by name and descriptorType.

Specified by:
getDescriptor in interface ModelMBeanInfo
Parameters:
inDescriptorName - The name of the descriptor.
inDescriptorType - The type of the descriptor being requested. If this is null or empty then all types are searched. Valid types are 'mbean', 'attribute', 'constructor' 'operation', and 'notification'. This value will be equal to the 'descriptorType' field in the descriptor that is returned.
Returns:
Descriptor containing the descriptor for the ModelMBean with the same name and descriptorType. If no descriptor is found, null is returned.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException for a null descriptor name or null or invalid type. The type must be "mbean","attribute", "constructor", "operation", or "notification".
See Also:
ModelMBeanInfo.setDescriptor(javax.management.Descriptor, java.lang.String)

setDescriptor

public void setDescriptor(Descriptor inDescriptor,
                          String inDescriptorType)
                   throws MBeanException,
                          RuntimeOperationsException
Description copied from interface: ModelMBeanInfo
Sets descriptors in the info array of type inDescriptorType for the ModelMBean. The setDescriptor method of the corresponding ModelMBean*Info will be called to set the specified descriptor.

Specified by:
setDescriptor in interface ModelMBeanInfo
Parameters:
inDescriptor - The descriptor to be set in the ModelMBean. It must NOT be null. All descriptors must have name and descriptorType fields.
inDescriptorType - The type of the descriptor being set. If this is null then the descriptorType field in the descriptor is used. If specified this value must be set in the descriptorType field in the descriptor. Must be "mbean","attribute", "constructor", "operation", or "notification".
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException for illegal or null arguments or if the name field of the descriptor is not found in the corresponding MBeanAttributeInfo or MBeanConstructorInfo or MBeanNotificationInfo or MBeanOperationInfo.
See Also:
ModelMBeanInfo.getDescriptor(java.lang.String, java.lang.String)

getAttribute

public ModelMBeanAttributeInfo getAttribute(String inName)
                                     throws MBeanException,
                                            RuntimeOperationsException
Description copied from interface: ModelMBeanInfo
Returns a ModelMBeanAttributeInfo requested by name.

Specified by:
getAttribute in interface ModelMBeanInfo
Parameters:
inName - The name of the ModelMBeanAttributeInfo to get. If no ModelMBeanAttributeInfo exists for this name null is returned.
Returns:
the attribute info for the named attribute, or null if there is none.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException for a null attribute name.

getOperation

public ModelMBeanOperationInfo getOperation(String inName)
                                     throws MBeanException,
                                            RuntimeOperationsException
Description copied from interface: ModelMBeanInfo
Returns a ModelMBeanOperationInfo requested by name.

Specified by:
getOperation in interface ModelMBeanInfo
Parameters:
inName - The name of the ModelMBeanOperationInfo to get. If no ModelMBeanOperationInfo exists for this name null is returned.
Returns:
the operation info for the named operation, or null if there is none.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException for a null operation name.

getConstructor

public ModelMBeanConstructorInfo getConstructor(String inName)
                                         throws MBeanException,
                                                RuntimeOperationsException
Returns the ModelMBeanConstructorInfo requested by name. If no ModelMBeanConstructorInfo exists for this name null is returned.

Parameters:
inName - the name of the constructor.
Returns:
the constructor info for the named constructor, or null if there is none.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException for a null constructor name.

getNotification

public ModelMBeanNotificationInfo getNotification(String inName)
                                           throws MBeanException,
                                                  RuntimeOperationsException
Description copied from interface: ModelMBeanInfo
Returns a ModelMBeanNotificationInfo requested by name.

Specified by:
getNotification in interface ModelMBeanInfo
Parameters:
inName - The name of the ModelMBeanNotificationInfo to get. If no ModelMBeanNotificationInfo exists for this name null is returned.
Returns:
the info for the named notification, or null if there is none.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException for a null notification name.

getDescriptor

public Descriptor getDescriptor()
Description copied from class: MBeanInfo
Get the descriptor of this MBeanInfo. Changing the returned value will have no affect on the original descriptor.

Specified by:
getDescriptor in interface DescriptorRead
Overrides:
getDescriptor in class MBeanInfo
Returns:
a descriptor that is either immutable or a copy of the original.
Since:
1.6

getMBeanDescriptor

public Descriptor getMBeanDescriptor()
                              throws MBeanException
Description copied from interface: ModelMBeanInfo
Returns the ModelMBean's descriptor which contains MBean wide policies. This descriptor contains metadata about the MBean and default policies for persistence and caching.

The fields in the descriptor are defined, but not limited to, the following:

 name           : MBean name
 descriptorType : must be "mbean"
 displayName    : name of attribute to be used in displays
 persistPolicy  : OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never
 persistLocation : The fully qualified directory name where the MBean should be persisted (if appropriate)
 persistFile    : File name into which the MBean should be persisted
 persistPeriod  : seconds - frequency of persist cycle for OnTime and NoMoreOftenThan PersistPolicy
 currencyTimeLimit : how long value is valid, <0 never, =0 always, >0 seconds
 log            : where t: log all notifications f: log no notifications
 logfile        : fully qualified filename to log events to
 visibility     : 1-4 where 1: always visible 4: rarely visible
 export         : name to be used to export/expose this MBean so that it is findable by
                  other JMX Agents.
 presentationString : xml formatted string to allow presentation of data to be associated with the MBean.

The default descriptor is: name=mbeanName,descriptorType=mbean, displayName=this.getClassName(), persistPolicy=never,log=F,export=F,visibility=1 If the descriptor does not contain all these fields, they will be added with these default values.

Note: because of inconsistencies in previous versions of this specification, it is recommended not to use negative or zero values for currencyTimeLimit. To indicate that a cached value is never valid, omit the currencyTimeLimit field. To indicate that it is always valid, use a very large number for this field.

Specified by:
getMBeanDescriptor in interface ModelMBeanInfo
Returns:
the MBean descriptor.
Throws:
MBeanException - Wraps a distributed communication Exception.
See Also:
ModelMBeanInfo.setMBeanDescriptor(javax.management.Descriptor)

setMBeanDescriptor

public void setMBeanDescriptor(Descriptor inMBeanDescriptor)
                        throws MBeanException,
                               RuntimeOperationsException
Description copied from interface: ModelMBeanInfo
Sets the ModelMBean's descriptor. This descriptor contains default, MBean wide metadata about the MBean and default policies for persistence and caching. This operation does a complete replacement of the descriptor, no merging is done. If the descriptor to set to is null then the default descriptor will be created. The default descriptor is: name=mbeanName,descriptorType=mbean, displayName=this.getClassName(), persistPolicy=never,log=F,export=F,visibility=1 If the descriptor does not contain all these fields, they will be added with these default values. See getMBeanDescriptor method javadoc for description of valid field names.

Specified by:
setMBeanDescriptor in interface ModelMBeanInfo
Parameters:
inMBeanDescriptor - the descriptor to set.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException for invalid descriptor.
See Also:
ModelMBeanInfo.getMBeanDescriptor()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ModelMBeanNotificationBroadcaster

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.modelmbean
Interface ModelMBeanNotificationBroadcaster

All Superinterfaces:
NotificationBroadcaster
All Known Subinterfaces:
ModelMBean
All Known Implementing Classes:
RequiredModelMBean
public interface ModelMBeanNotificationBroadcaster
extends NotificationBroadcaster

This interface must be implemented by the ModelMBeans. An implementation of this interface must be shipped with every JMX Agent.

Java resources wishing to be manageable instantiate the ModelMBean using the MBeanServer's createMBean method. The resource then sets the ModelMBeanInfo (with Descriptors) for the ModelMBean instance. The attributes and operations exposed via the ModelMBeanInfo for the ModelMBean are accessible from MBeans, connectors/adaptors like other MBeans. Through the ModelMBeanInfo Descriptors, values and methods in the managed application can be defined and mapped to attributes and operations of the ModelMBean. This mapping can be defined during development in an XML formatted file or dynamically and programmatically at runtime.

Every ModelMBean which is instantiated in the MBeanServer becomes manageable: its attributes and operations become remotely accessible through the connectors/adaptors connected to that MBeanServer. A Java object cannot be registered in the MBeanServer unless it is a JMX compliant MBean. By instantiating a ModelMBean, resources are guaranteed that the MBean is valid.

MBeanException and RuntimeOperationsException must be thrown on every public method. This allows for wrapping exceptions from distributed communications (RMI, EJB, etc.). These exceptions do not have to be thrown by the implementation except in the scenarios described in the specification and javadoc.

Since:
1.5

Method Summary
void | addAttributeChangeNotificationListener(NotificationListener listener, String attributeName, Object handback) Registers an object which implements the NotificationListener interface as a listener.
void | removeAttributeChangeNotificationListener(NotificationListener listener, String attributeName) Removes a listener for attributeChangeNotifications from the RequiredModelMBean.
void | sendAttributeChangeNotification(Attribute oldValue, Attribute newValue) Sends an attributeChangeNotification which contains the old value and new value for the attribute to the registered AttributeChangeNotification listeners on the ModelMBean.
void | sendAttributeChangeNotification(AttributeChangeNotification notification) Sends an attributeChangeNotification which is passed in to the registered attributeChangeNotification listeners on the ModelMBean.
void | sendNotification(Notification ntfyObj) Sends a Notification which is passed in to the registered Notification listeners on the ModelMBean as a jmx.modelmbean.generic notification.
void | sendNotification(String ntfyText) Sends a Notification which contains the text string that is passed in to the registered Notification listeners on the ModelMBean.
Methods inherited from interface javax.management.NotificationBroadcaster
addNotificationListener, getNotificationInfo, removeNotificationListener

Method Detail

sendNotification

void sendNotification(Notification ntfyObj)
                      throws MBeanException,
                             RuntimeOperationsException
Sends a Notification which is passed in to the registered Notification listeners on the ModelMBean as a jmx.modelmbean.generic notification.

Parameters:
ntfyObj - The notification which is to be passed to the 'handleNotification' method of the listener object.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException: The Notification object passed in parameter is null.

sendNotification

void sendNotification(String ntfyText)
                      throws MBeanException,
                             RuntimeOperationsException
Sends a Notification which contains the text string that is passed in to the registered Notification listeners on the ModelMBean.

Parameters:
ntfyText - The text which is to be passed in the Notification to the 'handleNotification' method of the listener object. the constructed Notification will be: type "jmx.modelmbean.generic" source this ModelMBean instance sequence 1
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException: The Notification text string passed in parameter is null.

sendAttributeChangeNotification

void sendAttributeChangeNotification(AttributeChangeNotification notification)
                                     throws MBeanException,
                                            RuntimeOperationsException
Sends an attributeChangeNotification which is passed in to the registered attributeChangeNotification listeners on the ModelMBean.

Parameters:
notification - The notification which is to be passed to the 'handleNotification' method of the listener object.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException: The AttributeChangeNotification object passed in parameter is null.

sendAttributeChangeNotification

void sendAttributeChangeNotification(Attribute oldValue,
                                     Attribute newValue)
                                     throws MBeanException,
                                            RuntimeOperationsException
Sends an attributeChangeNotification which contains the old value and new value for the attribute to the registered AttributeChangeNotification listeners on the ModelMBean.

Parameters:
oldValue - The original value for the Attribute
newValue - The current value for the Attribute

 The constructed attributeChangeNotification will be:
   type        "jmx.attribute.change"
   source      this ModelMBean instance
   sequence    1
   attributeName oldValue.getName()
   attributeType oldValue's class
   attributeOldValue oldValue.getValue()
   attributeNewValue newValue.getValue()
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException: An Attribute object passed in parameter is null or the names of the two Attribute objects in parameter are not the same.

addAttributeChangeNotificationListener

void addAttributeChangeNotificationListener(NotificationListener listener,
                                            String attributeName,
                                            Object handback)
                                            throws MBeanException,
                                                   RuntimeOperationsException,
                                                   IllegalArgumentException
Registers an object which implements the NotificationListener interface as a listener. This object's 'handleNotification()' method will be invoked when any attributeChangeNotification is issued through or by the ModelMBean. This does not include other Notifications. They must be registered for independently. An AttributeChangeNotification will be generated for this attributeName.

Parameters:
listener - The listener object which will handles notifications emitted by the registered MBean.
attributeName - The name of the ModelMBean attribute for which to receive change notifications. If null, then all attribute changes will cause an attributeChangeNotification to be issued.
handback - The context to be sent to the listener with the notification when a notification is emitted.
Throws:
IllegalArgumentException - The listener cannot be null.
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException The attribute name passed in parameter does not exist.
See Also:
removeAttributeChangeNotificationListener(javax.management.NotificationListener, java.lang.String)

removeAttributeChangeNotificationListener

void removeAttributeChangeNotificationListener(NotificationListener listener,
                                               String attributeName)
                                               throws MBeanException,
                                                      RuntimeOperationsException,
                                                      ListenerNotFoundException
Removes a listener for attributeChangeNotifications from the RequiredModelMBean.

Parameters:
listener - The listener name which was handling notifications emitted by the registered MBean. This method will remove all information related to this listener.
attributeName - The attribute for which the listener no longer wants to receive attributeChangeNotifications. If null the listener will be removed for all attributeChangeNotifications.
Throws:
ListenerNotFoundException - The listener is not registered in the MBean or is null.
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException If the inAttributeName parameter does not correspond to an attribute name.
See Also:
addAttributeChangeNotificationListener(javax.management.NotificationListener, java.lang.String, java.lang.Object)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ModelMBeanNotificationInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.modelmbean
Class ModelMBeanNotificationInfo

java.lang.Object
    extended by  javax.management.MBeanFeatureInfo
        extended by  javax.management.MBeanNotificationInfo
            extended by  javax.management.modelmbean.ModelMBeanNotificationInfo
All Implemented Interfaces:
Serializable, Cloneable, DescriptorAccess, DescriptorRead
public class ModelMBeanNotificationInfo
extends MBeanNotificationInfo
implements DescriptorAccess

The ModelMBeanNotificationInfo object describes a notification emitted by a ModelMBean. It is a subclass of MBeanNotificationInfo with the addition of an associated Descriptor and an implementation of the Descriptor interface.

The fields in the descriptor are defined, but not limited to, the following:

 name           : notification name
 descriptorType : must be "notification"
 severity       : 0-6 where 0: unknown; 1: non-recoverable;
                  2: critical, failure; 3: major, severe;
                  4: minor, marginal, error; 5: warning;
                  6: normal, cleared, informative
 messageID      : unique key for message text (to allow translation,
                  analysis)
 messageText    : text of notification
 log            : T - log message F - do not log message
 logfile        : string fully qualified file name appropriate for
                  operating system
 visibility     : 1-4 where 1: always visible 4: rarely visible
 presentationString : xml formatted string to allow presentation of data
The default descriptor contains the name, descriptorType, displayName and severity(=6) fields.

The serialVersionUID of this class is -7445681389570207141L.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.management.MBeanFeatureInfo
description, name
Constructor Summary
ModelMBeanNotificationInfo(ModelMBeanNotificationInfo inInfo)
Constructs a new ModelMBeanNotificationInfo object from this ModelMBeanNotfication Object.
ModelMBeanNotificationInfo(String[] notifTypes, String name, String description)
Constructs a ModelMBeanNotificationInfo object with a default descriptor.
ModelMBeanNotificationInfo(String[] notifTypes, String name, String description, Descriptor descriptor)
Constructs a ModelMBeanNotificationInfo object.
Method Summary
Object | clone() Creates and returns a new ModelMBeanNotificationInfo which is a duplicate of this ModelMBeanNotificationInfo.
Descriptor | getDescriptor() Returns a copy of the associated Descriptor for the ModelMBeanNotificationInfo.
void | setDescriptor(Descriptor inDescriptor) Sets associated Descriptor (full replace) for the ModelMBeanNotificationInfo If the new Descriptor is null, then the associated Descriptor reverts to a default descriptor.
String | toString() Returns a human readable string containing ModelMBeanNotificationInfo.
Methods inherited from class javax.management.MBeanNotificationInfo
equals, getNotifTypes, hashCode
Methods inherited from class javax.management.MBeanFeatureInfo
getDescription, getName
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ModelMBeanNotificationInfo

public ModelMBeanNotificationInfo(String[] notifTypes,
                                  String name,
                                  String description)
Constructs a ModelMBeanNotificationInfo object with a default descriptor.

Parameters:
notifTypes - The array of strings (in dot notation) containing the notification types that may be emitted.
name - The name of the Notification class.
description - A human readable description of the Notification. Optional.

ModelMBeanNotificationInfo

public ModelMBeanNotificationInfo(String[] notifTypes,
                                  String name,
                                  String description,
                                  Descriptor descriptor)
Constructs a ModelMBeanNotificationInfo object.

Parameters:
notifTypes - The array of strings (in dot notation) containing the notification types that may be emitted.
name - The name of the Notification class.
description - A human readable description of the Notification. Optional.
descriptor - An instance of Descriptor containing the appropriate metadata for this instance of the MBeanNotificationInfo. If it is null a default descriptor will be created. If the descriptor does not contain the fields "displayName" or "severity" these fields are added in the descriptor with their default values.
Throws:
RuntimeOperationsException - Wraps an IllegalArgumentException. The descriptor is invalid, or descriptor field "name" is not equal to parameter name, or descriptor field "DescriptorType" is not equal to "notification".

ModelMBeanNotificationInfo

public ModelMBeanNotificationInfo(ModelMBeanNotificationInfo inInfo)
Constructs a new ModelMBeanNotificationInfo object from this ModelMBeanNotfication Object.

Parameters:
inInfo - the ModelMBeanNotificationInfo to be duplicated
Method Detail

clone

public Object clone()
Creates and returns a new ModelMBeanNotificationInfo which is a duplicate of this ModelMBeanNotificationInfo.

Overrides:
clone in class MBeanNotificationInfo
Returns:
a clone of this instance.
See Also:
Cloneable

getDescriptor

public Descriptor getDescriptor()
Returns a copy of the associated Descriptor for the ModelMBeanNotificationInfo.

Specified by:
getDescriptor in interface DescriptorRead
Overrides:
getDescriptor in class MBeanFeatureInfo
Returns:
Descriptor associated with the ModelMBeanNotificationInfo object.
See Also:
setDescriptor(javax.management.Descriptor)

setDescriptor

public void setDescriptor(Descriptor inDescriptor)
Sets associated Descriptor (full replace) for the ModelMBeanNotificationInfo If the new Descriptor is null, then the associated Descriptor reverts to a default descriptor. The Descriptor is validated before it is assigned. If the new Descriptor is invalid, then a RuntimeOperationsException wrapping an IllegalArgumentException is thrown.

Specified by:
setDescriptor in interface DescriptorAccess
Parameters:
inDescriptor - replaces the Descriptor associated with the ModelMBeanNotification interface
Throws:
RuntimeOperationsException - Wraps an IllegalArgumentException for invalid Descriptor.
See Also:
getDescriptor()

toString

public String toString()
Returns a human readable string containing ModelMBeanNotificationInfo.

Overrides:
toString in class MBeanNotificationInfo
Returns:
a string describing this object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ModelMBeanOperationInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.modelmbean
Class ModelMBeanOperationInfo

java.lang.Object
    extended by  javax.management.MBeanFeatureInfo
        extended by  javax.management.MBeanOperationInfo
            extended by  javax.management.modelmbean.ModelMBeanOperationInfo
All Implemented Interfaces:
Serializable, Cloneable, DescriptorAccess, DescriptorRead
public class ModelMBeanOperationInfo
extends MBeanOperationInfo
implements DescriptorAccess

The ModelMBeanOperationInfo object describes a management operation of the ModelMBean. It is a subclass of MBeanOperationInfo with the addition of an associated Descriptor and an implementation of the DescriptorAccess interface.

 The fields in the descriptor are defined, but not limited to, the following:
 name           : operation name
 descriptorType : must be "operation"
 class          : class where method is defined (fully qualified)
 role           : must be "operation", "getter", or "setter
 targetObject   : object on which to execute this method
 targetType     : type of object reference for targetObject. Can be: ObjectReference | Handle | EJBHandle | IOR | RMIReference.
 value          : cached value for operation
 currencyTimeLimit : how long cached value is valid
 lastUpdatedTimeStamp : when cached value was set
 visibility            : 1-4 where 1: always visible 4: rarely visible
 presentationString :  xml formatted string to describe how to present operation
The default descriptor will have name, descriptorType, displayName and role fields set.

Note: because of inconsistencies in previous versions of this specification, it is recommended not to use negative or zero values for currencyTimeLimit. To indicate that a cached value is never valid, omit the currencyTimeLimit field. To indicate that it is always valid, use a very large number for this field.

The serialVersionUID of this class is 6532732096650090465L.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.management.MBeanOperationInfo
ACTION, ACTION_INFO, INFO, UNKNOWN
Fields inherited from class javax.management.MBeanFeatureInfo
description, name
Constructor Summary
ModelMBeanOperationInfo(ModelMBeanOperationInfo inInfo)
Constructs a new ModelMBeanOperationInfo object from this ModelMBeanOperation Object.
ModelMBeanOperationInfo(String description, Method operationMethod)
Constructs a ModelMBeanOperationInfo object with a default descriptor.
ModelMBeanOperationInfo(String description, Method operationMethod, Descriptor descriptor)
Constructs a ModelMBeanOperationInfo object.
ModelMBeanOperationInfo(String name, String description, MBeanParameterInfo[] signature, String type, int impact)
Constructs a ModelMBeanOperationInfo object with a default descriptor.
ModelMBeanOperationInfo(String name, String description, MBeanParameterInfo[] signature, String type, int impact, Descriptor descriptor)
Constructs a ModelMBeanOperationInfo object.
Method Summary
Object | clone() Creates and returns a new ModelMBeanOperationInfo which is a duplicate of this ModelMBeanOperationInfo.
Descriptor | getDescriptor() Returns a copy of the associated Descriptor of the ModelMBeanOperationInfo.
void | setDescriptor(Descriptor inDescriptor) Sets associated Descriptor (full replace) for the ModelMBeanOperationInfo If the new Descriptor is null, then the associated Descriptor reverts to a default descriptor.
String | toString() Returns a string containing the entire contents of the ModelMBeanOperationInfo in human readable form.
Methods inherited from class javax.management.MBeanOperationInfo
equals, getImpact, getReturnType, getSignature, hashCode
Methods inherited from class javax.management.MBeanFeatureInfo
getDescription, getName
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ModelMBeanOperationInfo

public ModelMBeanOperationInfo(String description,
                               Method operationMethod)
Constructs a ModelMBeanOperationInfo object with a default descriptor. The Descriptor of the constructed object will include fields contributed by any annotations on the Method object that contain the DescriptorKey meta-annotation.

Parameters:
operationMethod - The java.lang.reflect.Method object describing the MBean operation.
description - A human readable description of the operation.

ModelMBeanOperationInfo

public ModelMBeanOperationInfo(String description,
                               Method operationMethod,
                               Descriptor descriptor)
Constructs a ModelMBeanOperationInfo object. The Descriptor of the constructed object will include fields contributed by any annotations on the Method object that contain the DescriptorKey meta-annotation.

Parameters:
operationMethod - The java.lang.reflect.Method object describing the MBean operation.
description - A human readable description of the operation.
descriptor - An instance of Descriptor containing the appropriate metadata for this instance of the ModelMBeanOperationInfo. If it is null a default descriptor will be created. If the descriptor does not contain the fields "displayName" or "role" these fields are added in the descriptor with their default values.
Throws:
RuntimeOperationsException - Wraps an IllegalArgumentException. The descriptor is invalid; or descriptor field "name" is not equal to operation name; or descriptor field "DescriptorType" is not equal to "operation"; or descriptor optional field "role" is not equal to "operation", "getter", or "setter".

ModelMBeanOperationInfo

public ModelMBeanOperationInfo(String name,
                               String description,
                               MBeanParameterInfo[] signature,
                               String type,
                               int impact)
Constructs a ModelMBeanOperationInfo object with a default descriptor.

Parameters:
name - The name of the method.
description - A human readable description of the operation.
signature - MBeanParameterInfo objects describing the parameters(arguments) of the method.
type - The type of the method's return value.
impact - The impact of the method, one of INFO, ACTION, ACTION_INFO, UNKNOWN.

ModelMBeanOperationInfo

public ModelMBeanOperationInfo(String name,
                               String description,
                               MBeanParameterInfo[] signature,
                               String type,
                               int impact,
                               Descriptor descriptor)
Constructs a ModelMBeanOperationInfo object.

Parameters:
name - The name of the method.
description - A human readable description of the operation.
signature - MBeanParameterInfo objects describing the parameters(arguments) of the method.
type - The type of the method's return value.
impact - The impact of the method, one of INFO, ACTION, ACTION_INFO, UNKNOWN.
descriptor - An instance of Descriptor containing the appropriate metadata. for this instance of the MBeanOperationInfo.If it is null then a default descriptor will be created. If the descriptor does not contain the fields "displayName" or "role" these fields are added in the descriptor with their default values.
Throws:
RuntimeOperationsException - Wraps an IllegalArgumentException. The descriptor is invalid; or descriptor field "name" is not equal to operation name; or descriptor field "DescriptorType" is not equal to "operation"; or descriptor optional field "role" is not equal to "operation", "getter", or "setter".

ModelMBeanOperationInfo

public ModelMBeanOperationInfo(ModelMBeanOperationInfo inInfo)
Constructs a new ModelMBeanOperationInfo object from this ModelMBeanOperation Object.

Parameters:
inInfo - the ModelMBeanOperationInfo to be duplicated
Method Detail

clone

public Object clone()
Creates and returns a new ModelMBeanOperationInfo which is a duplicate of this ModelMBeanOperationInfo.

Overrides:
clone in class MBeanOperationInfo
Returns:
a clone of this instance.
See Also:
Cloneable

getDescriptor

public Descriptor getDescriptor()
Returns a copy of the associated Descriptor of the ModelMBeanOperationInfo.

Specified by:
getDescriptor in interface DescriptorRead
Overrides:
getDescriptor in class MBeanFeatureInfo
Returns:
Descriptor associated with the ModelMBeanOperationInfo object.
See Also:
setDescriptor(javax.management.Descriptor)

setDescriptor

public void setDescriptor(Descriptor inDescriptor)
Sets associated Descriptor (full replace) for the ModelMBeanOperationInfo If the new Descriptor is null, then the associated Descriptor reverts to a default descriptor. The Descriptor is validated before it is assigned. If the new Descriptor is invalid, then a RuntimeOperationsException wrapping an IllegalArgumentException is thrown.

Specified by:
setDescriptor in interface DescriptorAccess
Parameters:
inDescriptor - replaces the Descriptor associated with the ModelMBeanOperation.
Throws:
RuntimeOperationsException - Wraps an IllegalArgumentException for invalid Descriptor.
See Also:
getDescriptor()

toString

public String toString()
Returns a string containing the entire contents of the ModelMBeanOperationInfo in human readable form.

Overrides:
toString in class MBeanOperationInfo
Returns:
a string representation of the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RequiredModelMBean

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.modelmbean
Class RequiredModelMBean

java.lang.Object
    extended by  javax.management.modelmbean.RequiredModelMBean
All Implemented Interfaces:
DynamicMBean, MBeanRegistration, ModelMBean, ModelMBeanNotificationBroadcaster, NotificationBroadcaster, NotificationEmitter, PersistentMBean
public class RequiredModelMBean
extends Object
implements ModelMBean, MBeanRegistration, NotificationEmitter

This class is the implementation of a ModelMBean. An appropriate implementation of a ModelMBean must be shipped with every JMX Agent and the class must be named RequiredModelMBean.

Java resources wishing to be manageable instantiate the RequiredModelMBean using the MBeanServer's createMBean method. The resource then sets the MBeanInfo and Descriptors for the RequiredModelMBean instance. The attributes and operations exposed via the ModelMBeanInfo for the ModelMBean are accessible from MBeans, connectors/adaptors like other MBeans. Through the Descriptors, values and methods in the managed application can be defined and mapped to attributes and operations of the ModelMBean. This mapping can be defined in an XML formatted file or dynamically and programmatically at runtime.

Every RequiredModelMBean which is instantiated in the MBeanServer becomes manageable:
its attributes and operations become remotely accessible through the connectors/adaptors connected to that MBeanServer.

A Java object cannot be registered in the MBeanServer unless it is a JMX compliant MBean. By instantiating a RequiredModelMBean, resources are guaranteed that the MBean is valid. MBeanException and RuntimeOperationsException must be thrown on every public method. This allows for wrapping exceptions from distributed communications (RMI, EJB, etc.)

Since:
1.5

Constructor Summary
RequiredModelMBean()
Constructs an RequiredModelMBean with an empty ModelMBeanInfo.
RequiredModelMBean(ModelMBeanInfo mbi)
Constructs a RequiredModelMBean object using ModelMBeanInfo passed in.
Method Summary
void | addAttributeChangeNotificationListener(NotificationListener inlistener, String inAttributeName, Object inhandback) Registers an object which implements the NotificationListener interface as a listener.
void | addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Registers an object which implements the NotificationListener interface as a listener.
Object | getAttribute(String attrName) Returns the value of a specific attribute defined for this ModelMBean.
AttributeList | getAttributes(String[] attrNames) Returns the values of several attributes in the ModelMBean.
protected ClassLoaderRepository | getClassLoaderRepository() Return the Class Loader Repository used to perform class loading.
MBeanInfo | getMBeanInfo() Returns the attributes, operations, constructors and notifications that this RequiredModelMBean exposes for management.
MBeanNotificationInfo[] | getNotificationInfo() Returns the array of Notifications always generated by the RequiredModelMBean.
Object | invoke(String opName, Object[] opArgs, String[] sig) Invokes a method on or through a RequiredModelMBean and returns the result of the method execution.
void | load() Instantiates this MBean instance with the data found for the MBean in the persistent store.
void | postDeregister() Allows the MBean to perform any operations needed after having been unregistered in the MBean server.
void | postRegister(Boolean registrationDone) Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.
void | preDeregister() Allows the MBean to perform any operations it needs before being unregistered by the MBean server.
ObjectName | preRegister(MBeanServer server, ObjectName name) Allows the MBean to perform any operations it needs before being registered in the MBean server.
void | removeAttributeChangeNotificationListener(NotificationListener inlistener, String inAttributeName) Removes a listener for attributeChangeNotifications from the RequiredModelMBean.
void | removeNotificationListener(NotificationListener listener) Removes a listener for Notifications from the RequiredModelMBean.
void | removeNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Removes a listener from this MBean.
void | sendAttributeChangeNotification(Attribute inOldVal, Attribute inNewVal) Sends an attributeChangeNotification which contains the old value and new value for the attribute to the registered AttributeChangeNotification listeners on the ModelMBean.
void | sendAttributeChangeNotification(AttributeChangeNotification ntfyObj) Sends an attributeChangeNotification which is passed in to the registered attributeChangeNotification listeners on the ModelMBean.
void | sendNotification(Notification ntfyObj) Sends a Notification which is passed in to the registered Notification listeners on the ModelMBean as a jmx.modelmbean.generic notification.
void | sendNotification(String ntfyText) Sends a Notification which contains the text string that is passed in to the registered Notification listeners on the ModelMBean.
void | setAttribute(Attribute attribute) Sets the value of a specific attribute of a named ModelMBean.
AttributeList | setAttributes(AttributeList attributes) Sets the values of an array of attributes of this ModelMBean.
void | setManagedResource(Object mr, String mr_type) Sets the instance handle of the object against which to execute all methods in this ModelMBean management interface (MBeanInfo and Descriptors).
void | setModelMBeanInfo(ModelMBeanInfo mbi) Initializes a ModelMBean object using ModelMBeanInfo passed in.
void | store() Captures the current state of this MBean instance and writes it out to the persistent store.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RequiredModelMBean

public RequiredModelMBean()
                   throws MBeanException,
                          RuntimeOperationsException
Constructs an RequiredModelMBean with an empty ModelMBeanInfo.

The RequiredModelMBean's MBeanInfo and Descriptors can be customized using the setModelMBeanInfo(javax.management.modelmbean.ModelMBeanInfo) method. After the RequiredModelMBean's MBeanInfo and Descriptors are customized, the RequiredModelMBean can be registered with the MBeanServer.

Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps a RuntimeException during the construction of the object.

RequiredModelMBean

public RequiredModelMBean(ModelMBeanInfo mbi)
                   throws MBeanException,
                          RuntimeOperationsException
Constructs a RequiredModelMBean object using ModelMBeanInfo passed in. As long as the RequiredModelMBean is not registered with the MBeanServer yet, the RequiredModelMBean's MBeanInfo and Descriptors can be customized using the setModelMBeanInfo(javax.management.modelmbean.ModelMBeanInfo) method. After the RequiredModelMBean's MBeanInfo and Descriptors are customized, the RequiredModelMBean can be registered with the MBeanServer.

Parameters:
mbi - The ModelMBeanInfo object to be used by the RequiredModelMBean. The given ModelMBeanInfo is cloned and modified as specified by setModelMBeanInfo(javax.management.modelmbean.ModelMBeanInfo)
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an {link java.lang.IllegalArgumentException}: The MBeanInfo passed in parameter is null.
Method Detail

setModelMBeanInfo

public void setModelMBeanInfo(ModelMBeanInfo mbi)
                       throws MBeanException,
                              RuntimeOperationsException
Initializes a ModelMBean object using ModelMBeanInfo passed in. This method makes it possible to set a customized ModelMBeanInfo on the ModelMBean as long as it is not registered with the MBeanServer.
Once the ModelMBean's ModelMBeanInfo (with Descriptors) are customized and set on the ModelMBean, the ModelMBean be registered with the MBeanServer.

If the ModelMBean is currently registered, this method throws a RuntimeOperationsException wrapping an IllegalStateException

If the given inModelMBeanInfo does not contain any ModelMBeanNotificationInfo for the GENERIC or ATTRIBUTE_CHANGE notifications, then the RequiredModelMBean will supply its own default ModelMBeanNotificationInfos for those missing notifications.

Specified by:
setModelMBeanInfo in interface ModelMBean
Parameters:
mbi - The ModelMBeanInfo object to be used by the ModelMBean.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException -
  • Wraps an IllegalArgumentException if the MBeanInfo passed in parameter is null.
  • Wraps an IllegalStateException if the ModelMBean is currently registered in the MBeanServer.

setManagedResource

public void setManagedResource(Object mr,
                               String mr_type)
                        throws MBeanException,
                               RuntimeOperationsException,
                               InstanceNotFoundException,
                               InvalidTargetObjectTypeException
Sets the instance handle of the object against which to execute all methods in this ModelMBean management interface (MBeanInfo and Descriptors).

Specified by:
setManagedResource in interface ModelMBean
Parameters:
mr - Object that is the managed resource
mr_type - The type of reference for the managed resource.
Can be: "ObjectReference", "Handle", "IOR", "EJBHandle", or "RMIReference".
In this implementation only "ObjectReference" is supported.
Throws:
MBeanException - The initializer of the object has thrown an exception.
InstanceNotFoundException - The managed resource object could not be found
InvalidTargetObjectTypeException - The managed resource type should be "ObjectReference".
RuntimeOperationsException - Wraps a RuntimeException when setting the resource.

load

public void load()
          throws MBeanException,
                 RuntimeOperationsException,
                 InstanceNotFoundException

Instantiates this MBean instance with the data found for the MBean in the persistent store. The data loaded could include attribute and operation values.

This method should be called during construction or initialization of this instance, and before the MBean is registered with the MBeanServer.

If the implementation of this class does not support persistence, an MBeanException wrapping a ServiceNotFoundException is thrown.

Specified by:
load in interface PersistentMBean
Throws:
MBeanException - Wraps another exception, or persistence is not supported
RuntimeOperationsException - Wraps exceptions from the persistence mechanism
InstanceNotFoundException - Could not find or load this MBean from persistent storage

store

public void store()
           throws MBeanException,
                  RuntimeOperationsException,
                  InstanceNotFoundException

Captures the current state of this MBean instance and writes it out to the persistent store. The state stored could include attribute and operation values.

If the implementation of this class does not support persistence, an MBeanException wrapping a ServiceNotFoundException is thrown.

Persistence policy from the MBean and attribute descriptor is used to guide execution of this method. The MBean should be stored if 'persistPolicy' field is:

  != "never"
   = "always"
   = "onTimer" and now > 'lastPersistTime' + 'persistPeriod'
   = "NoMoreOftenThan" and now > 'lastPersistTime' + 'persistPeriod'
   = "onUnregister"

Do not store the MBean if 'persistPolicy' field is:

    = "never"
    = "onUpdate"
    = "onTimer" && now < 'lastPersistTime' + 'persistPeriod'

Specified by:
store in interface PersistentMBean
Throws:
MBeanException - Wraps another exception, or persistence is not supported
RuntimeOperationsException - Wraps exceptions from the persistence mechanism
InstanceNotFoundException - Could not find/access the persistent store

getMBeanInfo

public MBeanInfo getMBeanInfo()
Returns the attributes, operations, constructors and notifications that this RequiredModelMBean exposes for management.

Specified by:
getMBeanInfo in interface DynamicMBean
Returns:
An instance of ModelMBeanInfo allowing retrieval all attributes, operations, and Notifications of this MBean.

invoke

public Object invoke(String opName,
                     Object[] opArgs,
                     String[] sig)
              throws MBeanException,
                     ReflectionException
Invokes a method on or through a RequiredModelMBean and returns the result of the method execution.

If the given method to be invoked, together with the provided signature, matches one of RequiredModelMbean accessible methods, this one will be call. Otherwise the call to the given method will be tried on the managed resource.

The last value returned by an operation may be cached in the operation's descriptor which is in the ModelMBeanOperationInfo's descriptor. The valid value will be in the 'value' field if there is one. If the 'currencyTimeLimit' field in the descriptor is:

  • <0 Then the value is not cached and is never valid. The operation method is invoked. The 'value' and 'lastUpdatedTimeStamp' fields are cleared.
  • =0 Then the value is always cached and always valid. The 'value' field is returned. If there is no 'value' field then the operation method is invoked for the attribute. The 'lastUpdatedTimeStamp' field and `value' fields are set to the operation's return value and the current time stamp.
  • >0 Represents the number of seconds that the 'value' field is valid. The 'value' field is no longer valid when 'lastUpdatedTimeStamp' + 'currencyTimeLimit' > Now.
    • When 'value' is valid, 'value' is returned.
    • When 'value' is no longer valid then the operation method is invoked. The 'lastUpdatedTimeStamp' field and `value' fields are updated.

Note: because of inconsistencies in previous versions of this specification, it is recommended not to use negative or zero values for currencyTimeLimit. To indicate that a cached value is never valid, omit the currencyTimeLimit field. To indicate that it is always valid, use a very large number for this field.

Specified by:
invoke in interface DynamicMBean
Parameters:
opName - The name of the method to be invoked. The name can be the fully qualified method name including the classname, or just the method name if the classname is defined in the 'class' field of the operation descriptor.
opArgs - An array containing the parameters to be set when the operation is invoked
sig - An array containing the signature of the operation. The class objects will be loaded using the same class loader as the one used for loading the MBean on which the operation was invoked.
Returns:
The object returned by the method, which represents the result of invoking the method on the specified managed resource.
Throws:
MBeanException - Wraps one of the following Exceptions:
  • An Exception thrown by the managed object's invoked method.
  • ServiceNotFoundException: No ModelMBeanOperationInfo or no descriptor defined for the specified operation or the managed resource is null.
  • InvalidTargetObjectTypeException: The 'targetType' field value is not 'objectReference'.
ReflectionException - Wraps an Exception thrown while trying to invoke the method.
RuntimeOperationsException - Wraps an IllegalArgumentException Method name is null.

getAttribute

public Object getAttribute(String attrName)
                    throws AttributeNotFoundException,
                           MBeanException,
                           ReflectionException
Returns the value of a specific attribute defined for this ModelMBean. The last value returned by an attribute may be cached in the attribute's descriptor. The valid value will be in the 'value' field if there is one. If the 'currencyTimeLimit' field in the descriptor is:
  • <0 Then the value is not cached and is never valid. The getter method is invoked for the attribute. The 'value' and 'lastUpdatedTimeStamp' fields are cleared.
  • =0 Then the value is always cached and always valid. The 'value' field is returned. If there is no'value' field then the getter method is invoked for the attribute. The 'lastUpdatedTimeStamp' field and `value' fields are set to the attribute's value and the current time stamp.
  • >0 Represents the number of seconds that the 'value' field is valid. The 'value' field is no longer valid when 'lastUpdatedTimeStamp' + 'currencyTimeLimit' > Now.
    • When 'value' is valid, 'value' is returned.
    • When 'value' is no longer valid then the getter method is invoked for the attribute. The 'lastUpdatedTimeStamp' field and `value' fields are updated.

Note: because of inconsistencies in previous versions of this specification, it is recommended not to use negative or zero values for currencyTimeLimit. To indicate that a cached value is never valid, omit the currencyTimeLimit field. To indicate that it is always valid, use a very large number for this field.

If the 'getMethod' field contains the name of a valid operation descriptor, then the method described by the operation descriptor is executed. The response from the method is returned as the value of the attribute. If the operation fails or the returned value is not compatible with the declared type of the attribute, an exception will be thrown.

If no 'getMethod' field is defined then the default value of the attribute is returned. If the returned value is not compatible with the declared type of the attribute, an exception will be thrown.

The declared type of the attribute is the String returned by MBeanAttributeInfo.getType(). A value is compatible with this type if one of the following is true:

  • the value is null;
  • the declared name is a primitive type name (such as "int") and the value is an instance of the corresponding wrapper type (such as java.lang.Integer);
  • the name of the value's class is identical to the declared name;
  • the declared name can be loaded by the value's class loader and produces a class to which the value can be assigned.

In this implementation, in every case where the getMethod needs to be called, because the method is invoked through the standard "invoke" method and thus needs operationInfo, an operation must be specified for that getMethod so that the invocation works correctly.

Specified by:
getAttribute in interface DynamicMBean
Parameters:
attrName - A String specifying the name of the attribute to be retrieved. It must match the name of a ModelMBeanAttributeInfo.
Returns:
The value of the retrieved attribute from the descriptor 'value' field or from the invocation of the operation in the 'getMethod' field of the descriptor.
Throws:
AttributeNotFoundException - The specified attribute is not accessible in the MBean. The following cases may result in an AttributeNotFoundException:
  • No ModelMBeanInfo was found for the Model MBean.
  • No ModelMBeanAttributeInfo was found for the specified attribute name.
  • The ModelMBeanAttributeInfo isReadable method returns 'false'.
MBeanException - Wraps one of the following Exceptions:
  • InvalidAttributeValueException: A wrong value type was received from the attribute's getter method or no 'getMethod' field defined in the descriptor for the attribute and no default value exists.
  • ServiceNotFoundException: No ModelMBeanOperationInfo defined for the attribute's getter method or no descriptor associated with the ModelMBeanOperationInfo or the managed resource is null.
  • InvalidTargetObjectTypeException The 'targetType' field value is not 'objectReference'.
  • An Exception thrown by the managed object's getter.
ReflectionException - Wraps an Exception thrown while trying to invoke the getter.
RuntimeOperationsException - Wraps an IllegalArgumentException: The attribute name in parameter is null.
See Also:
setAttribute(javax.management.Attribute)

getAttributes

public AttributeList getAttributes(String[] attrNames)
Returns the values of several attributes in the ModelMBean. Executes a getAttribute for each attribute name in the attrNames array passed in.

Specified by:
getAttributes in interface DynamicMBean
Parameters:
attrNames - A String array of names of the attributes to be retrieved.
Returns:
The array of the retrieved attributes.
Throws:
RuntimeOperationsException - Wraps an IllegalArgumentException: The object name in parameter is null or attributes in parameter is null.
See Also:
setAttributes(javax.management.AttributeList)

setAttribute

public void setAttribute(Attribute attribute)
                  throws AttributeNotFoundException,
                         InvalidAttributeValueException,
                         MBeanException,
                         ReflectionException
Sets the value of a specific attribute of a named ModelMBean. If the 'setMethod' field of the attribute's descriptor contains the name of a valid operation descriptor, then the method described by the operation descriptor is executed. In this implementation, the operation descriptor must be specified correctly and assigned to the modelMBeanInfo so that the 'setMethod' works correctly. The response from the method is set as the value of the attribute in the descriptor.

If currencyTimeLimit is > 0, then the new value for the attribute is cached in the attribute descriptor's 'value' field and the 'lastUpdatedTimeStamp' field is set to the current time stamp.

If the persist field of the attribute's descriptor is not null then Persistence policy from the attribute descriptor is used to guide storing the attribute in a persistent store.
Store the MBean if 'persistPolicy' field is:

  • != "never"
  • = "always"
  • = "onUpdate"
  • = "onTimer" and now > 'lastPersistTime' + 'persistPeriod'
  • = "NoMoreOftenThan" and now > 'lastPersistTime' + 'persistPeriod'
Do not store the MBean if 'persistPolicy' field is:
  • = "never"
  • = "onTimer" && now < 'lastPersistTime' + 'persistPeriod'
  • = "onUnregister"
  • = "NoMoreOftenThan" and now < 'lastPersistTime' + 'persistPeriod'

The ModelMBeanInfo of the Model MBean is stored in a file.

Specified by:
setAttribute in interface DynamicMBean
Parameters:
attribute - The Attribute instance containing the name of the attribute to be set and the value it is to be set to.
Throws:
AttributeNotFoundException - The specified attribute is not accessible in the MBean.
The following cases may result in an AttributeNotFoundException:
  • No ModelMBeanAttributeInfo is found for the specified attribute.
  • The ModelMBeanAttributeInfo's isWritable method returns 'false'.
InvalidAttributeValueException - No descriptor is defined for the specified attribute.
MBeanException - Wraps one of the following Exceptions:
  • An Exception thrown by the managed object's setter.
  • A ServiceNotFoundException if a setMethod field is defined in the descriptor for the attribute and the managed resource is null; or if no setMethod field is defined and caching is not enabled for the attribute. Note that if there is no getMethod field either, then caching is automatically enabled.
  • InvalidTargetObjectTypeException The 'targetType' field value is not 'objectReference'.
  • An Exception thrown by the managed object's getter.
ReflectionException - Wraps an Exception thrown while trying to invoke the setter.
RuntimeOperationsException - Wraps an IllegalArgumentException: The attribute in parameter is null.
See Also:
getAttribute(java.lang.String)

setAttributes

public AttributeList setAttributes(AttributeList attributes)
Sets the values of an array of attributes of this ModelMBean. Executes the setAttribute() method for each attribute in the list.

Specified by:
setAttributes in interface DynamicMBean
Parameters:
attributes - A list of attributes: The identification of the attributes to be set and the values they are to be set to.
Returns:
The array of attributes that were set, with their new values in Attribute instances.
Throws:
RuntimeOperationsException - Wraps an IllegalArgumentException: The object name in parameter is null or attributes in parameter is null.
See Also:
getAttributes(java.lang.String[])

addNotificationListener

public void addNotificationListener(NotificationListener listener,
                                    NotificationFilter filter,
                                    Object handback)
                             throws IllegalArgumentException
Registers an object which implements the NotificationListener interface as a listener. This object's 'handleNotification()' method will be invoked when any notification is issued through or by the ModelMBean. This does not include attributeChangeNotifications. They must be registered for independently.

Specified by:
addNotificationListener in interface NotificationBroadcaster
Parameters:
listener - The listener object which will handles notifications emitted by the registered MBean.
filter - The filter object. If null, no filtering will be performed before handling notifications.
handback - The context to be sent to the listener with the notification when a notification is emitted.
Throws:
IllegalArgumentException - The listener cannot be null.
See Also:
removeNotificationListener(javax.management.NotificationListener)

removeNotificationListener

public void removeNotificationListener(NotificationListener listener)
                                throws ListenerNotFoundException
Removes a listener for Notifications from the RequiredModelMBean.

Specified by:
removeNotificationListener in interface NotificationBroadcaster
Parameters:
listener - The listener name which was handling notifications emitted by the registered MBean. This method will remove all information related to this listener.
Throws:
ListenerNotFoundException - The listener is not registered in the MBean or is null.
See Also:
addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

removeNotificationListener

public void removeNotificationListener(NotificationListener listener,
                                       NotificationFilter filter,
                                       Object handback)
                                throws ListenerNotFoundException
Description copied from interface: NotificationEmitter

Removes a listener from this MBean. The MBean must have a listener that exactly matches the given listener, filter, and handback parameters. If there is more than one such listener, only one is removed.

The filter and handback parameters may be null if and only if they are null in a listener to be removed.

Specified by:
removeNotificationListener in interface NotificationEmitter
Parameters:
listener - A listener that was previously added to this MBean.
filter - The filter that was specified when the listener was added.
handback - The handback that was specified when the listener was added.
Throws:
ListenerNotFoundException - The listener is not registered with the MBean, or it is not registered with the given filter and handback.

sendNotification

public void sendNotification(Notification ntfyObj)
                      throws MBeanException,
                             RuntimeOperationsException
Description copied from interface: ModelMBeanNotificationBroadcaster
Sends a Notification which is passed in to the registered Notification listeners on the ModelMBean as a jmx.modelmbean.generic notification.

Specified by:
sendNotification in interface ModelMBeanNotificationBroadcaster
Parameters:
ntfyObj - The notification which is to be passed to the 'handleNotification' method of the listener object.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException: The Notification object passed in parameter is null.

sendNotification

public void sendNotification(String ntfyText)
                      throws MBeanException,
                             RuntimeOperationsException
Description copied from interface: ModelMBeanNotificationBroadcaster
Sends a Notification which contains the text string that is passed in to the registered Notification listeners on the ModelMBean.

Specified by:
sendNotification in interface ModelMBeanNotificationBroadcaster
Parameters:
ntfyText - The text which is to be passed in the Notification to the 'handleNotification' method of the listener object. the constructed Notification will be: type "jmx.modelmbean.generic" source this ModelMBean instance sequence 1
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException: The Notification text string passed in parameter is null.

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()
Returns the array of Notifications always generated by the RequiredModelMBean.

RequiredModelMBean may always send also two additional notifications:

  • One with descriptor "name=GENERIC,descriptorType=notification,log=T,severity=6,displayName=jmx.modelmbean.generic"
  • Second is a standard attribute change notification with descriptor "name=ATTRIBUTE_CHANGE,descriptorType=notification,log=T,severity=6,displayName=jmx.attribute.change"
Thus these two notifications are always added to those specified by the application.

Specified by:
getNotificationInfo in interface NotificationBroadcaster
Returns:
MBeanNotificationInfo[]

addAttributeChangeNotificationListener

public void addAttributeChangeNotificationListener(NotificationListener inlistener,
                                                   String inAttributeName,
                                                   Object inhandback)
                                            throws MBeanException,
                                                   RuntimeOperationsException,
                                                   IllegalArgumentException
Description copied from interface: ModelMBeanNotificationBroadcaster
Registers an object which implements the NotificationListener interface as a listener. This object's 'handleNotification()' method will be invoked when any attributeChangeNotification is issued through or by the ModelMBean. This does not include other Notifications. They must be registered for independently. An AttributeChangeNotification will be generated for this attributeName.

Specified by:
addAttributeChangeNotificationListener in interface ModelMBeanNotificationBroadcaster
Parameters:
inlistener - The listener object which will handles notifications emitted by the registered MBean.
inAttributeName - The name of the ModelMBean attribute for which to receive change notifications. If null, then all attribute changes will cause an attributeChangeNotification to be issued.
inhandback - The context to be sent to the listener with the notification when a notification is emitted.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException The attribute name passed in parameter does not exist.
IllegalArgumentException - The listener cannot be null.
See Also:
ModelMBeanNotificationBroadcaster.removeAttributeChangeNotificationListener(javax.management.NotificationListener, java.lang.String)

removeAttributeChangeNotificationListener

public void removeAttributeChangeNotificationListener(NotificationListener inlistener,
                                                      String inAttributeName)
                                               throws MBeanException,
                                                      RuntimeOperationsException,
                                                      ListenerNotFoundException
Description copied from interface: ModelMBeanNotificationBroadcaster
Removes a listener for attributeChangeNotifications from the RequiredModelMBean.

Specified by:
removeAttributeChangeNotificationListener in interface ModelMBeanNotificationBroadcaster
Parameters:
inlistener - The listener name which was handling notifications emitted by the registered MBean. This method will remove all information related to this listener.
inAttributeName - The attribute for which the listener no longer wants to receive attributeChangeNotifications. If null the listener will be removed for all attributeChangeNotifications.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException If the inAttributeName parameter does not correspond to an attribute name.
ListenerNotFoundException - The listener is not registered in the MBean or is null.
See Also:
ModelMBeanNotificationBroadcaster.addAttributeChangeNotificationListener(javax.management.NotificationListener, java.lang.String, java.lang.Object)

sendAttributeChangeNotification

public void sendAttributeChangeNotification(AttributeChangeNotification ntfyObj)
                                     throws MBeanException,
                                            RuntimeOperationsException
Description copied from interface: ModelMBeanNotificationBroadcaster
Sends an attributeChangeNotification which is passed in to the registered attributeChangeNotification listeners on the ModelMBean.

Specified by:
sendAttributeChangeNotification in interface ModelMBeanNotificationBroadcaster
Parameters:
ntfyObj - The notification which is to be passed to the 'handleNotification' method of the listener object.
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException: The AttributeChangeNotification object passed in parameter is null.

sendAttributeChangeNotification

public void sendAttributeChangeNotification(Attribute inOldVal,
                                            Attribute inNewVal)
                                     throws MBeanException,
                                            RuntimeOperationsException
Description copied from interface: ModelMBeanNotificationBroadcaster
Sends an attributeChangeNotification which contains the old value and new value for the attribute to the registered AttributeChangeNotification listeners on the ModelMBean.

Specified by:
sendAttributeChangeNotification in interface ModelMBeanNotificationBroadcaster
Parameters:
inOldVal - The original value for the Attribute
inNewVal - The current value for the Attribute

 The constructed attributeChangeNotification will be:
   type        "jmx.attribute.change"
   source      this ModelMBean instance
   sequence    1
   attributeName oldValue.getName()
   attributeType oldValue's class
   attributeOldValue oldValue.getValue()
   attributeNewValue newValue.getValue()
Throws:
MBeanException - Wraps a distributed communication Exception.
RuntimeOperationsException - Wraps an IllegalArgumentException: An Attribute object passed in parameter is null or the names of the two Attribute objects in parameter are not the same.

getClassLoaderRepository

protected ClassLoaderRepository getClassLoaderRepository()
Return the Class Loader Repository used to perform class loading. Subclasses may wish to redefine this method in order to return the appropriate ClassLoaderRepository that should be used in this object.

Returns:
the Class Loader Repository.

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception
Allows the MBean to perform any operations it needs before being registered in the MBean server. If the name of the MBean is not specified, the MBean can provide a name for its registration. If any exception is raised, the MBean will not be registered in the MBean server.

In order to ensure proper run-time semantics of RequireModelMBean, Any subclass of RequiredModelMBean overloading or overriding this method should call super.preRegister(server, name) in its own preRegister implementation.

Specified by:
preRegister in interface MBeanRegistration
Parameters:
server - The MBean server in which the MBean will be registered.
name - The object name of the MBean. This name is null if the name parameter to one of the createMBean or registerMBean methods in the MBeanServer interface is null. In that case, this method must return a non-null ObjectName for the new MBean.
Returns:
The name under which the MBean is to be registered. This value must not be null. If the name parameter is not null, it will usually but not necessarily be the returned value.
Throws:
Exception - This exception will be caught by the MBean server and re-thrown as an MBeanRegistrationException.

postRegister

public void postRegister(Boolean registrationDone)
Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.

In order to ensure proper run-time semantics of RequireModelMBean, Any subclass of RequiredModelMBean overloading or overriding this method should call super.postRegister(registrationDone) in its own postRegister implementation.

Specified by:
postRegister in interface MBeanRegistration
Parameters:
registrationDone - Indicates whether or not the MBean has been successfully registered in the MBean server. The value false means that the registration phase has failed.

preDeregister

public void preDeregister()
                   throws Exception
Allows the MBean to perform any operations it needs before being unregistered by the MBean server.

In order to ensure proper run-time semantics of RequireModelMBean, Any subclass of RequiredModelMBean overloading or overriding this method should call super.preDeregister() in its own preDeregister implementation.

Specified by:
preDeregister in interface MBeanRegistration
Throws:
Exception - This exception will be caught by the MBean server and re-thrown as an MBeanRegistrationException.

postDeregister

public void postDeregister()
Allows the MBean to perform any operations needed after having been unregistered in the MBean server.

In order to ensure proper run-time semantics of RequireModelMBean, Any subclass of RequiredModelMBean overloading or overriding this method should call super.postDeregister() in its own postDeregister implementation.

Specified by:
postDeregister in interface MBeanRegistration
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLParseException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.management.modelmbean
Class XMLParseException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.modelmbean.XMLParseException
All Implemented Interfaces:
Serializable
public class XMLParseException
extends Exception

This exception is thrown when an XML formatted string is being parsed into ModelMBean objects or when XML formatted strings are being created from ModelMBean objects. It is also used to wrapper exceptions from XML parsers that may be used.

The serialVersionUID of this class is 3176664577895105181L.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
XMLParseException()
Default constructor .
XMLParseException(Exception e, String s)
Constructor taking a string and an exception.
XMLParseException(String s)
Constructor taking a string.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

XMLParseException

public XMLParseException()
Default constructor .

XMLParseException

public XMLParseException(String s)
Constructor taking a string.

Parameters:
s - the detail message.

XMLParseException

public XMLParseException(Exception e,
                         String s)
Constructor taking a string and an exception.

Parameters:
e - the nested exception.
s - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


monitor

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.management.monitor

Provides the definition of the monitor classes.

See:
Description

Interface Summary
CounterMonitorMBean | Exposes the remote management interface of the counter monitor MBean.
GaugeMonitorMBean | Exposes the remote management interface of the gauge monitor MBean.
MonitorMBean | Exposes the remote management interface of monitor MBeans.
StringMonitorMBean | Exposes the remote management interface of the string monitor MBean.

Class Summary
CounterMonitor | Defines a monitor MBean designed to observe the values of a counter attribute.
GaugeMonitor | Defines a monitor MBean designed to observe the values of a gauge attribute.
Monitor | Defines the part common to all monitor MBeans.
MonitorNotification | Provides definitions of the notifications sent by monitor MBeans.
StringMonitor | Defines a monitor MBean designed to observe the values of a string attribute.

Exception Summary
MonitorSettingException Exception thrown by the monitor when a monitor setting becomes invalid while the monitor is running.

Package javax.management.monitor Description

Provides the definition of the monitor classes. A Monitor is an MBean that periodically observes the value of an attribute in one or more other MBeans. If the attribute meets a certain condition, the Monitor emits a MonitorNotification. When the monitor MBean periodically calls getAttribute to retrieve the value of the attribute being monitored it does so within the access control context of the Monitor.start() caller.

The value being monitored can be a simple value contained within a complex type. For example, the MemoryMXBean defined in java.lang.management has an attribute HeapMemoryUsage of type MemoryUsage. To monitor the amount of used memory, described by the used property of MemoryUsage, you could monitor "HeapMemoryUsage.used". That string would be the argument to setObservedAttribute.

The rules used to interpret an ObservedAttribute like "HeapMemoryUsage.used" are as follows. Suppose the string is A.e (so A would be "HeapMemoryUsage" and e would be "used" in the example).

First the value of the attribute A is obtained. Call it v. A value x is extracted from v as follows:

  • If v is a CompositeData and if v.get(e) returns a value then x is that value.
  • If v is an array and e is the string "length" then x is the length of the array.
  • If the above rules do not produce a value, and if Introspector.getBeanInfo for the class of v (v.getClass()) contains a PropertyDescriptor with the name e, then x is the result of calling the property's read method on v.

The third rule means for example that if the attribute HeapMemoryUsage is a MemoryUsage, monitoring "HeapMemoryUsage.used" will obtain the observed value by calling MemoryUsage.getUsed().

If the ObservedAttribute contains more than one period, for example "ConnectionPool.connectionStats.length", then the above rules are applied iteratively. Here, v would initially be the value of the attribute ConnectionPool, and x would be derived by applying the above rules with e equal to "connectionStats". Then v would be set to this x and a new x derived by applying the rules again with e equal to "length".

Although it is recommended that attribute names be valid Java identifiers, it is possible for an attribute to be called HeapMemoryUsage.used. This means that an ObservedAttribute that is HeapMemoryUsage.used could mean that the value to observe is either an attribute of that name, or the property used within an attribute called HeapMemoryUsage. So for compatibility reasons, when the ObservedAttribute contains a period (.), the monitor will check whether an attribute exists whose name is the full ObservedAttribute string (HeapMemoryUsage.used in the example). It does this by calling getMBeanInfo for the observed MBean and looking for a contained MBeanAttributeInfo with the given name. If one is found, then that is what is monitored. If more than one MBean is being observed, the behavior is unspecified if some of them have a HeapMemoryUsage.used attribute and others do not. An implementation may therefore call getMBeanInfo on just one of the MBeans in this case. The behavior is also unspecified if the result of the check changes while the monitor is active.

The exact behavior of monitors is detailed in the JMX Specification. What follows is a summary.

There are three kinds of Monitors:

  • A CounterMonitor observes attributes of integer type. The attributes are assumed to be non-negative, and monotonically increasing except for a possible roll-over at a specified modulus. Each observed attribute has an associated threshold value. A notification is sent when the attribute exceeds its threshold.

    An offset value can be specified. When an observed value exceeds its threshold, the threshold is incremented by the offset, or by a multiple of the offset sufficient to make the threshold greater than the new observed value.

    A CounterMonitor can operate in difference mode. In this mode, the value compared against the threshold is the difference between two successive observations of an attribute.

  • A GaugeMonitor observes attributes of numerical type. Each observed attribute has an associated high threshold and low threshold.

    When an observed attribute crosses the high threshold, if the notify high flag is true, then a notification is sent. Subsequent crossings of the high threshold value will not trigger further notifications until the gauge value becomes less than or equal to the low threshold.

    When an observed attribute crosses the low threshold, if the notify low flag is true, then a notification is sent. Subsequent crossings of the low threshold value will not trigger further notifications until the gauge value becomes greater than or equal to the high threshold.

    Typically, only one of the notify high and notify low flags is set. The other threshold is used to provide a hysteresis mechanism to avoid the repeated triggering of notifications when an attribute makes small oscillations around the threshold value.

    A GaugeMonitor can operate in difference mode. In this mode, the value compared against the high and low thresholds is the difference between two successive observations of an attribute.

  • A StringMonitor observes attributes of type String. A notification is sent when an observed attribute becomes equal and/or not equal to a given string.

Since:
1.5
See Also:
Java SE 6 Platform documentation on JMX technology, in particular the JMX Specification, version 1.4(pdf).
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.management.monitor Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.management.monitor

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.util.EventObject (implements java.io.Serializable)
      • javax.management.Notification
        • javax.management.monitor.MonitorNotification
    • javax.management.NotificationBroadcasterSupport (implements javax.management.NotificationEmitter)
      • javax.management.monitor.Monitor (implements javax.management.MBeanRegistration, javax.management.monitor.MonitorMBean)
        • javax.management.monitor.CounterMonitor (implements javax.management.monitor.CounterMonitorMBean)
        • javax.management.monitor.GaugeMonitor (implements javax.management.monitor.GaugeMonitorMBean)
        • javax.management.monitor.StringMonitor (implements javax.management.monitor.StringMonitorMBean)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.lang.RuntimeException
          • javax.management.JMRuntimeException
            • javax.management.monitor.MonitorSettingException

Interface Hierarchy

  • javax.management.monitor.MonitorMBean
    • javax.management.monitor.CounterMonitorMBean
    • javax.management.monitor.GaugeMonitorMBean
    • javax.management.monitor.StringMonitorMBean
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.management.monitor

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.management.monitor

Packages that use javax.management.monitor
javax.management.monitor Provides the definition of the monitor classes.

Classes in javax.management.monitor used by javax.management.monitor
CounterMonitorMBean
Exposes the remote management interface of the counter monitor MBean.
GaugeMonitorMBean
Exposes the remote management interface of the gauge monitor MBean.
Monitor
Defines the part common to all monitor MBeans.
MonitorMBean
Exposes the remote management interface of monitor MBeans.
StringMonitorMBean
Exposes the remote management interface of the string monitor MBean.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.monitor.CounterMonitor

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.monitor.CounterMonitor

No usage of javax.management.monitor.CounterMonitor

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.monitor.GaugeMonitor

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.monitor.GaugeMonitor

No usage of javax.management.monitor.GaugeMonitor

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.monitor.Monitor

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.monitor.Monitor

Packages that use Monitor
javax.management.monitor Provides the definition of the monitor classes.

Uses of Monitor in javax.management.monitor

Subclasses of Monitor in javax.management.monitor
class | CounterMonitor Defines a monitor MBean designed to observe the values of a counter attribute.
class | GaugeMonitor Defines a monitor MBean designed to observe the values of a gauge attribute.
class | StringMonitor Defines a monitor MBean designed to observe the values of a string attribute.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.monitor.MonitorNotification

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.monitor.MonitorNotification

No usage of javax.management.monitor.MonitorNotification

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.monitor.MonitorSettingException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.monitor.MonitorSettingException

No usage of javax.management.monitor.MonitorSettingException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.monitor.StringMonitor

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.monitor.StringMonitor

No usage of javax.management.monitor.StringMonitor

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.monitor.CounterMonitorMBean

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.monitor.CounterMonitorMBean

Packages that use CounterMonitorMBean
javax.management.monitor Provides the definition of the monitor classes.

Uses of CounterMonitorMBean in javax.management.monitor

Classes in javax.management.monitor that implement CounterMonitorMBean
 class CounterMonitor
Defines a monitor MBean designed to observe the values of a counter attribute.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.monitor.GaugeMonitorMBean

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.monitor.GaugeMonitorMBean

Packages that use GaugeMonitorMBean
javax.management.monitor Provides the definition of the monitor classes.

Uses of GaugeMonitorMBean in javax.management.monitor

Classes in javax.management.monitor that implement GaugeMonitorMBean
 class GaugeMonitor
Defines a monitor MBean designed to observe the values of a gauge attribute.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.monitor.MonitorMBean

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.monitor.MonitorMBean

Packages that use MonitorMBean
javax.management.monitor Provides the definition of the monitor classes.

Uses of MonitorMBean in javax.management.monitor

Subinterfaces of MonitorMBean in javax.management.monitor
interface | CounterMonitorMBean Exposes the remote management interface of the counter monitor MBean.
interface | GaugeMonitorMBean Exposes the remote management interface of the gauge monitor MBean.
interface | StringMonitorMBean Exposes the remote management interface of the string monitor MBean.

Classes in javax.management.monitor that implement MonitorMBean
class | CounterMonitor Defines a monitor MBean designed to observe the values of a counter attribute.
class | GaugeMonitor Defines a monitor MBean designed to observe the values of a gauge attribute.
class | Monitor Defines the part common to all monitor MBeans.
class | StringMonitor Defines a monitor MBean designed to observe the values of a string attribute.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.monitor.StringMonitorMBean

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.monitor.StringMonitorMBean

Packages that use StringMonitorMBean
javax.management.monitor Provides the definition of the monitor classes.

Uses of StringMonitorMBean in javax.management.monitor

Classes in javax.management.monitor that implement StringMonitorMBean
 class StringMonitor
Defines a monitor MBean designed to observe the values of a string attribute.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


CounterMonitor

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.management.monitor
Class CounterMonitor

java.lang.Object
    extended by  javax.management.NotificationBroadcasterSupport
        extended by  javax.management.monitor.Monitor
            extended by  javax.management.monitor.CounterMonitor
All Implemented Interfaces:
MBeanRegistration, CounterMonitorMBean, MonitorMBean, NotificationBroadcaster, NotificationEmitter
public class CounterMonitor
extends Monitor
implements CounterMonitorMBean

Defines a monitor MBean designed to observe the values of a counter attribute.

A counter monitor sends a threshold notification when the value of the counter reaches or exceeds a threshold known as the comparison level. The notify flag must be set to true.

In addition, an offset mechanism enables particular counting intervals to be detected. If the offset value is not zero, whenever the threshold is triggered by the counter value reaching a comparison level, that comparison level is incremented by the offset value. This is regarded as taking place instantaneously, that is, before the count is incremented. Thus, for each level, the threshold triggers an event notification every time the count increases by an interval equal to the offset value.

If the counter can wrap around its maximum value, the modulus needs to be specified. The modulus is the value at which the counter is reset to zero.

If the counter difference mode is used, the value of the derived gauge is calculated as the difference between the observed counter values for two successive observations. If this difference is negative, the value of the derived gauge is incremented by the value of the modulus. The derived gauge value (V[t]) is calculated using the following method:

  • if (counter[t] - counter[t-GP]) is positive then V[t] = counter[t] - counter[t-GP]
  • if (counter[t] - counter[t-GP]) is negative then V[t] = counter[t] - counter[t-GP] + MODULUS
This implementation of the counter monitor requires the observed attribute to be of the type integer (Byte, Integer, Short, Long).

Since:
1.5

Field Summary
Fields inherited from class javax.management.monitor.Monitor
alreadyNotified, alreadyNotifieds, capacityIncrement, dbgTag, elementCount, OBSERVED_ATTRIBUTE_ERROR_NOTIFIED, OBSERVED_ATTRIBUTE_TYPE_ERROR_NOTIFIED, OBSERVED_OBJECT_ERROR_NOTIFIED, RESET_FLAGS_ALREADY_NOTIFIED, RUNTIME_ERROR_NOTIFIED, server
Constructor Summary
CounterMonitor()
Default constructor.
Method Summary
Number | getDerivedGauge() Deprecated. As of JMX 1.2, replaced by getDerivedGauge(ObjectName)
Number | getDerivedGauge(ObjectName object) Gets the derived gauge of the specified object, if this object is contained in the set of observed MBeans, or null otherwise.
long | getDerivedGaugeTimeStamp() Deprecated. As of JMX 1.2, replaced by getDerivedGaugeTimeStamp(ObjectName)
long | getDerivedGaugeTimeStamp(ObjectName object) Gets the derived gauge timestamp of the specified object, if this object is contained in the set of observed MBeans, or 0 otherwise.
boolean | getDifferenceMode() Gets the difference mode flag value common to all observed MBeans.
Number | getInitThreshold() Gets the initial threshold value common to all observed objects.
Number | getModulus() Gets the modulus value common to all observed MBeans.
MBeanNotificationInfo[] | getNotificationInfo() Returns a NotificationInfo object containing the name of the Java class of the notification and the notification types sent by the counter monitor.
boolean | getNotify() Gets the notification's on/off switch value common to all observed MBeans.
Number | getOffset() Gets the offset value common to all observed MBeans.
Number | getThreshold() Deprecated. As of JMX 1.2, replaced by getThreshold(ObjectName)
Number | getThreshold(ObjectName object) Gets the current threshold value of the specified object, if this object is contained in the set of observed MBeans, or null otherwise.
void | setDifferenceMode(boolean value) Sets the difference mode flag value common to all observed MBeans.
void | setInitThreshold(Number value) Sets the initial threshold value common to all observed objects.
void | setModulus(Number value) Sets the modulus value common to all observed MBeans.
void | setNotify(boolean value) Sets the notification's on/off switch value common to all observed MBeans.
void | setOffset(Number value) Sets the offset value common to all observed MBeans.
void | setThreshold(Number value) Deprecated. As of JMX 1.2, replaced by setInitThreshold(java.lang.Number)
void | start() Starts the counter monitor.
void | stop() Stops the counter monitor.
Methods inherited from class javax.management.monitor.Monitor
addObservedObject, containsObservedObject, getGranularityPeriod, getObservedAttribute, getObservedObject, getObservedObjects, isActive, postDeregister, postRegister, preDeregister, preRegister, removeObservedObject, setGranularityPeriod, setObservedAttribute, setObservedObject
Methods inherited from class javax.management.NotificationBroadcasterSupport
addNotificationListener, handleNotification, removeNotificationListener, removeNotificationListener, sendNotification
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.management.monitor.MonitorMBean
addObservedObject, containsObservedObject, getGranularityPeriod, getObservedAttribute, getObservedObject, getObservedObjects, isActive, removeObservedObject, setGranularityPeriod, setObservedAttribute, setObservedObject

Constructor Detail

CounterMonitor

public CounterMonitor()
Default constructor.

Method Detail

start

public void start()
Starts the counter monitor.

Specified by:
start in interface MonitorMBean
Specified by:
start in class Monitor

stop

public void stop()
Stops the counter monitor.

Specified by:
stop in interface MonitorMBean
Specified by:
stop in class Monitor

getDerivedGauge

public Number getDerivedGauge(ObjectName object)
Gets the derived gauge of the specified object, if this object is contained in the set of observed MBeans, or null otherwise.

Specified by:
getDerivedGauge in interface CounterMonitorMBean
Parameters:
object - the name of the object whose derived gauge is to be returned.
Returns:
The derived gauge of the specified object.

getDerivedGaugeTimeStamp

public long getDerivedGaugeTimeStamp(ObjectName object)
Gets the derived gauge timestamp of the specified object, if this object is contained in the set of observed MBeans, or 0 otherwise.

Specified by:
getDerivedGaugeTimeStamp in interface CounterMonitorMBean
Parameters:
object - the name of the object whose derived gauge timestamp is to be returned.
Returns:
The derived gauge timestamp of the specified object.

getThreshold

public Number getThreshold(ObjectName object)
Gets the current threshold value of the specified object, if this object is contained in the set of observed MBeans, or null otherwise.

Specified by:
getThreshold in interface CounterMonitorMBean
Parameters:
object - the name of the object whose threshold is to be returned.
Returns:
The threshold value of the specified object.
See Also:
CounterMonitorMBean.setThreshold(java.lang.Number)

getInitThreshold

public Number getInitThreshold()
Gets the initial threshold value common to all observed objects.

Specified by:
getInitThreshold in interface CounterMonitorMBean
Returns:
The initial threshold.
See Also:
setInitThreshold(java.lang.Number)

setInitThreshold

public void setInitThreshold(Number value)
                      throws IllegalArgumentException
Sets the initial threshold value common to all observed objects.
The current threshold of every object in the set of observed MBeans is updated consequently.

Specified by:
setInitThreshold in interface CounterMonitorMBean
Parameters:
value - The initial threshold value.
Throws:
IllegalArgumentException - The specified threshold is null or the threshold value is less than zero.
See Also:
getInitThreshold()

getDerivedGauge

@Deprecated
public Number getDerivedGauge()
Deprecated. As of JMX 1.2, replaced by getDerivedGauge(ObjectName)

Returns the derived gauge of the first object in the set of observed MBeans.

Specified by:
getDerivedGauge in interface CounterMonitorMBean
Returns:
The derived gauge.

getDerivedGaugeTimeStamp

@Deprecated
public long getDerivedGaugeTimeStamp()
Deprecated. As of JMX 1.2, replaced by getDerivedGaugeTimeStamp(ObjectName)

Gets the derived gauge timestamp of the first object in the set of observed MBeans.

Specified by:
getDerivedGaugeTimeStamp in interface CounterMonitorMBean
Returns:
The derived gauge timestamp.

getThreshold

@Deprecated
public Number getThreshold()
Deprecated. As of JMX 1.2, replaced by getThreshold(ObjectName)

Gets the threshold value of the first object in the set of observed MBeans.

Specified by:
getThreshold in interface CounterMonitorMBean
Returns:
The threshold value.
See Also:
setThreshold(java.lang.Number)

setThreshold

@Deprecated
public void setThreshold(Number value)
                  throws IllegalArgumentException
Deprecated. As of JMX 1.2, replaced by setInitThreshold(java.lang.Number)

Sets the initial threshold value.

Specified by:
setThreshold in interface CounterMonitorMBean
Parameters:
value - The initial threshold value.
Throws:
IllegalArgumentException - The specified threshold is null or the threshold value is less than zero.
See Also:
getThreshold()

getOffset

public Number getOffset()
Gets the offset value common to all observed MBeans.

Specified by:
getOffset in interface CounterMonitorMBean
Returns:
The offset value.
See Also:
setOffset(java.lang.Number)

setOffset

public void setOffset(Number value)
               throws IllegalArgumentException
Sets the offset value common to all observed MBeans.

Specified by:
setOffset in interface CounterMonitorMBean
Parameters:
value - The offset value.
Throws:
IllegalArgumentException - The specified offset is null or the offset value is less than zero.
See Also:
getOffset()

getModulus

public Number getModulus()
Gets the modulus value common to all observed MBeans.

Specified by:
getModulus in interface CounterMonitorMBean
Returns:
The modulus value.
See Also:
setModulus(java.lang.Number)

setModulus

public void setModulus(Number value)
                throws IllegalArgumentException
Sets the modulus value common to all observed MBeans.

Specified by:
setModulus in interface CounterMonitorMBean
Parameters:
value - The modulus value.
Throws:
IllegalArgumentException - The specified modulus is null or the modulus value is less than zero.
See Also:
getModulus()

getNotify

public boolean getNotify()
Gets the notification's on/off switch value common to all observed MBeans.

Specified by:
getNotify in interface CounterMonitorMBean
Returns:
true if the counter monitor notifies when exceeding the threshold, false otherwise.
See Also:
setNotify(boolean)

setNotify

public void setNotify(boolean value)
Sets the notification's on/off switch value common to all observed MBeans.

Specified by:
setNotify in interface CounterMonitorMBean
Parameters:
value - The notification's on/off switch value.
See Also:
getNotify()

getDifferenceMode

public boolean getDifferenceMode()
Gets the difference mode flag value common to all observed MBeans.

Specified by:
getDifferenceMode in interface CounterMonitorMBean
Returns:
true if the difference mode is used, false otherwise.
See Also:
setDifferenceMode(boolean)

setDifferenceMode

public void setDifferenceMode(boolean value)
Sets the difference mode flag value common to all observed MBeans.

Specified by:
setDifferenceMode in interface CounterMonitorMBean
Parameters:
value - The difference mode flag value.
See Also:
getDifferenceMode()

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()
Returns a NotificationInfo object containing the name of the Java class of the notification and the notification types sent by the counter monitor.

Specified by:
getNotificationInfo in interface NotificationBroadcaster
Overrides:
getNotificationInfo in class NotificationBroadcasterSupport
Returns:
the array of possible notifications.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


CounterMonitorMBean

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.monitor
Interface CounterMonitorMBean

All Superinterfaces:
MonitorMBean
All Known Implementing Classes:
CounterMonitor
public interface CounterMonitorMBean
extends MonitorMBean

Exposes the remote management interface of the counter monitor MBean.

Since:
1.5

Method Summary
Number | getDerivedGauge() Deprecated. As of JMX 1.2, replaced by getDerivedGauge(ObjectName)
Number | getDerivedGauge(ObjectName object) Gets the derived gauge for the specified MBean.
long | getDerivedGaugeTimeStamp() Deprecated. As of JMX 1.2, replaced by getDerivedGaugeTimeStamp(ObjectName)
long | getDerivedGaugeTimeStamp(ObjectName object) Gets the derived gauge timestamp for the specified MBean.
boolean | getDifferenceMode() Gets the difference mode flag value.
Number | getInitThreshold() Gets the initial threshold value common to all observed objects.
Number | getModulus() Gets the modulus value.
boolean | getNotify() Gets the notification's on/off switch value.
Number | getOffset() Gets the offset value.
Number | getThreshold() Deprecated. As of JMX 1.2, replaced by getThreshold(ObjectName)
Number | getThreshold(ObjectName object) Gets the threshold value for the specified MBean.
void | setDifferenceMode(boolean value) Sets the difference mode flag value.
void | setInitThreshold(Number value) Sets the initial threshold value common to all observed MBeans.
void | setModulus(Number value) Sets the modulus value.
void | setNotify(boolean value) Sets the notification's on/off switch value.
void | setOffset(Number value) Sets the offset value.
void | setThreshold(Number value) Deprecated. As of JMX 1.2, replaced by setInitThreshold(java.lang.Number)
Methods inherited from interface javax.management.monitor.MonitorMBean
addObservedObject, containsObservedObject, getGranularityPeriod, getObservedAttribute, getObservedObject, getObservedObjects, isActive, removeObservedObject, setGranularityPeriod, setObservedAttribute, setObservedObject, start, stop

Method Detail

getDerivedGauge

@Deprecated
Number getDerivedGauge()
Deprecated. As of JMX 1.2, replaced by getDerivedGauge(ObjectName)

Gets the derived gauge.

Returns:
The derived gauge.

getDerivedGaugeTimeStamp

@Deprecated
long getDerivedGaugeTimeStamp()
Deprecated. As of JMX 1.2, replaced by getDerivedGaugeTimeStamp(ObjectName)

Gets the derived gauge timestamp.

Returns:
The derived gauge timestamp.

getThreshold

@Deprecated
Number getThreshold()
Deprecated. As of JMX 1.2, replaced by getThreshold(ObjectName)

Gets the threshold value.

Returns:
The threshold value.
See Also:
setThreshold(Number)

setThreshold

@Deprecated
void setThreshold(Number value)
                  throws IllegalArgumentException
Deprecated. As of JMX 1.2, replaced by setInitThreshold(java.lang.Number)

Sets the threshold value.

Parameters:
value - The threshold value.
Throws:
IllegalArgumentException - The specified threshold is null or the threshold value is less than zero.
See Also:
getThreshold()

getDerivedGauge

Number getDerivedGauge(ObjectName object)
Gets the derived gauge for the specified MBean.

Parameters:
object - the MBean for which the derived gauge is to be returned
Returns:
The derived gauge for the specified MBean if this MBean is in the set of observed MBeans, or null otherwise.

getDerivedGaugeTimeStamp

long getDerivedGaugeTimeStamp(ObjectName object)
Gets the derived gauge timestamp for the specified MBean.

Parameters:
object - the MBean for which the derived gauge timestamp is to be returned
Returns:
The derived gauge timestamp for the specified MBean if this MBean is in the set of observed MBeans, or null otherwise.

getThreshold

Number getThreshold(ObjectName object)
Gets the threshold value for the specified MBean.

Parameters:
object - the MBean for which the threshold value is to be returned
Returns:
The threshold value for the specified MBean if this MBean is in the set of observed MBeans, or null otherwise.
See Also:
setThreshold(java.lang.Number)

getInitThreshold

Number getInitThreshold()
Gets the initial threshold value common to all observed objects.

Returns:
The initial threshold value.
See Also:
setInitThreshold(java.lang.Number)

setInitThreshold

void setInitThreshold(Number value)
                      throws IllegalArgumentException
Sets the initial threshold value common to all observed MBeans.

Parameters:
value - The initial threshold value.
Throws:
IllegalArgumentException - The specified threshold is null or the threshold value is less than zero.
See Also:
getInitThreshold()

getOffset

Number getOffset()
Gets the offset value.

Returns:
The offset value.
See Also:
setOffset(Number)

setOffset

void setOffset(Number value)
               throws IllegalArgumentException
Sets the offset value.

Parameters:
value - The offset value.
Throws:
IllegalArgumentException - The specified offset is null or the offset value is less than zero.
See Also:
getOffset()

getModulus

Number getModulus()
Gets the modulus value.

Returns:
The modulus value.
See Also:
setModulus(java.lang.Number)

setModulus

void setModulus(Number value)
                throws IllegalArgumentException
Sets the modulus value.

Parameters:
value - The modulus value.
Throws:
IllegalArgumentException - The specified modulus is null or the modulus value is less than zero.
See Also:
getModulus()

getNotify

boolean getNotify()
Gets the notification's on/off switch value.

Returns:
true if the counter monitor notifies when exceeding the threshold, false otherwise.
See Also:
setNotify(boolean)

setNotify

void setNotify(boolean value)
Sets the notification's on/off switch value.

Parameters:
value - The notification's on/off switch value.
See Also:
getNotify()

getDifferenceMode

boolean getDifferenceMode()
Gets the difference mode flag value.

Returns:
true if the difference mode is used, false otherwise.
See Also:
setDifferenceMode(boolean)

setDifferenceMode

void setDifferenceMode(boolean value)
Sets the difference mode flag value.

Parameters:
value - The difference mode flag value.
See Also:
getDifferenceMode()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


GaugeMonitor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.monitor
Class GaugeMonitor

java.lang.Object
    extended by  javax.management.NotificationBroadcasterSupport
        extended by  javax.management.monitor.Monitor
            extended by  javax.management.monitor.GaugeMonitor
All Implemented Interfaces:
MBeanRegistration, GaugeMonitorMBean, MonitorMBean, NotificationBroadcaster, NotificationEmitter
public class GaugeMonitor
extends Monitor
implements GaugeMonitorMBean

Defines a monitor MBean designed to observe the values of a gauge attribute.

A gauge monitor observes an attribute that is continuously variable with time. A gauge monitor sends notifications as follows:

  • if the attribute value is increasing and becomes equal to or greater than the high threshold value, a threshold high notification is sent. The notify high flag must be set to true.
    Subsequent crossings of the high threshold value do not cause further notifications unless the attribute value becomes equal to or less than the low threshold value.
  • if the attribute value is decreasing and becomes equal to or less than the low threshold value, a threshold low notification is sent. The notify low flag must be set to true.
    Subsequent crossings of the low threshold value do not cause further notifications unless the attribute value becomes equal to or greater than the high threshold value.
This provides a hysteresis mechanism to avoid repeated triggering of notifications when the attribute value makes small oscillations around the high or low threshold value.

If the gauge difference mode is used, the value of the derived gauge is calculated as the difference between the observed gauge values for two successive observations.
The derived gauge value (V[t]) is calculated using the following method:

  • V[t] = gauge[t] - gauge[t-GP]
This implementation of the gauge monitor requires the observed attribute to be of the type integer or floating-point (Byte, Integer, Short, Long, Float, Double).

Since:
1.5

Field Summary
Fields inherited from class javax.management.monitor.Monitor
alreadyNotified, alreadyNotifieds, capacityIncrement, dbgTag, elementCount, OBSERVED_ATTRIBUTE_ERROR_NOTIFIED, OBSERVED_ATTRIBUTE_TYPE_ERROR_NOTIFIED, OBSERVED_OBJECT_ERROR_NOTIFIED, RESET_FLAGS_ALREADY_NOTIFIED, RUNTIME_ERROR_NOTIFIED, server
Constructor Summary
GaugeMonitor()
Default constructor.
Method Summary
Number | getDerivedGauge() Deprecated. As of JMX 1.2, replaced by getDerivedGauge(ObjectName)
Number | getDerivedGauge(ObjectName object) Gets the derived gauge of the specified object, if this object is contained in the set of observed MBeans, or null otherwise.
long | getDerivedGaugeTimeStamp() Deprecated. As of JMX 1.2, replaced by getDerivedGaugeTimeStamp(ObjectName)
long | getDerivedGaugeTimeStamp(ObjectName object) Gets the derived gauge timestamp of the specified object, if this object is contained in the set of observed MBeans, or 0 otherwise.
boolean | getDifferenceMode() Gets the difference mode flag value common to all observed MBeans.
Number | getHighThreshold() Gets the high threshold value common to all observed MBeans.
Number | getLowThreshold() Gets the low threshold value common to all observed MBeans.
MBeanNotificationInfo[] | getNotificationInfo() Returns a NotificationInfo object containing the name of the Java class of the notification and the notification types sent by the gauge monitor.
boolean | getNotifyHigh() Gets the high notification's on/off switch value common to all observed MBeans.
boolean | getNotifyLow() Gets the low notification's on/off switch value common to all observed MBeans.
void | setDifferenceMode(boolean value) Sets the difference mode flag value common to all observed MBeans.
void | setNotifyHigh(boolean value) Sets the high notification's on/off switch value common to all observed MBeans.
void | setNotifyLow(boolean value) Sets the low notification's on/off switch value common to all observed MBeans.
void | setThresholds(Number highValue, Number lowValue) Sets the high and the low threshold values common to all observed MBeans.
void | start() Starts the gauge monitor.
void | stop() Stops the gauge monitor.
Methods inherited from class javax.management.monitor.Monitor
addObservedObject, containsObservedObject, getGranularityPeriod, getObservedAttribute, getObservedObject, getObservedObjects, isActive, postDeregister, postRegister, preDeregister, preRegister, removeObservedObject, setGranularityPeriod, setObservedAttribute, setObservedObject
Methods inherited from class javax.management.NotificationBroadcasterSupport
addNotificationListener, handleNotification, removeNotificationListener, removeNotificationListener, sendNotification
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.management.monitor.MonitorMBean
addObservedObject, containsObservedObject, getGranularityPeriod, getObservedAttribute, getObservedObject, getObservedObjects, isActive, removeObservedObject, setGranularityPeriod, setObservedAttribute, setObservedObject

Constructor Detail

GaugeMonitor

public GaugeMonitor()
Default constructor.

Method Detail

start

public void start()
Starts the gauge monitor.

Specified by:
start in interface MonitorMBean
Specified by:
start in class Monitor

stop

public void stop()
Stops the gauge monitor.

Specified by:
stop in interface MonitorMBean
Specified by:
stop in class Monitor

getDerivedGauge

public Number getDerivedGauge(ObjectName object)
Gets the derived gauge of the specified object, if this object is contained in the set of observed MBeans, or null otherwise.

Specified by:
getDerivedGauge in interface GaugeMonitorMBean
Parameters:
object - the name of the MBean.
Returns:
The derived gauge of the specified object.

getDerivedGaugeTimeStamp

public long getDerivedGaugeTimeStamp(ObjectName object)
Gets the derived gauge timestamp of the specified object, if this object is contained in the set of observed MBeans, or 0 otherwise.

Specified by:
getDerivedGaugeTimeStamp in interface GaugeMonitorMBean
Parameters:
object - the name of the object whose derived gauge timestamp is to be returned.
Returns:
The derived gauge timestamp of the specified object.

getDerivedGauge

@Deprecated
public Number getDerivedGauge()
Deprecated. As of JMX 1.2, replaced by getDerivedGauge(ObjectName)

Returns the derived gauge of the first object in the set of observed MBeans.

Specified by:
getDerivedGauge in interface GaugeMonitorMBean
Returns:
The derived gauge.

getDerivedGaugeTimeStamp

@Deprecated
public long getDerivedGaugeTimeStamp()
Deprecated. As of JMX 1.2, replaced by getDerivedGaugeTimeStamp(ObjectName)

Gets the derived gauge timestamp of the first object in the set of observed MBeans.

Specified by:
getDerivedGaugeTimeStamp in interface GaugeMonitorMBean
Returns:
The derived gauge timestamp.

getHighThreshold

public Number getHighThreshold()
Gets the high threshold value common to all observed MBeans.

Specified by:
getHighThreshold in interface GaugeMonitorMBean
Returns:
The high threshold value.
See Also:
setThresholds(java.lang.Number, java.lang.Number)

getLowThreshold

public Number getLowThreshold()
Gets the low threshold value common to all observed MBeans.

Specified by:
getLowThreshold in interface GaugeMonitorMBean
Returns:
The low threshold value.
See Also:
setThresholds(java.lang.Number, java.lang.Number)

setThresholds

public void setThresholds(Number highValue,
                          Number lowValue)
                   throws IllegalArgumentException
Sets the high and the low threshold values common to all observed MBeans.

Specified by:
setThresholds in interface GaugeMonitorMBean
Parameters:
highValue - The high threshold value.
lowValue - The low threshold value.
Throws:
IllegalArgumentException - The specified high/low threshold is null or the low threshold is greater than the high threshold or the high threshold and the low threshold are not of the same type.
See Also:
getHighThreshold(), getLowThreshold()

getNotifyHigh

public boolean getNotifyHigh()
Gets the high notification's on/off switch value common to all observed MBeans.

Specified by:
getNotifyHigh in interface GaugeMonitorMBean
Returns:
true if the gauge monitor notifies when exceeding the high threshold, false otherwise.
See Also:
setNotifyHigh(boolean)

setNotifyHigh

public void setNotifyHigh(boolean value)
Sets the high notification's on/off switch value common to all observed MBeans.

Specified by:
setNotifyHigh in interface GaugeMonitorMBean
Parameters:
value - The high notification's on/off switch value.
See Also:
getNotifyHigh()

getNotifyLow

public boolean getNotifyLow()
Gets the low notification's on/off switch value common to all observed MBeans.

Specified by:
getNotifyLow in interface GaugeMonitorMBean
Returns:
true if the gauge monitor notifies when exceeding the low threshold, false otherwise.
See Also:
setNotifyLow(boolean)

setNotifyLow

public void setNotifyLow(boolean value)
Sets the low notification's on/off switch value common to all observed MBeans.

Specified by:
setNotifyLow in interface GaugeMonitorMBean
Parameters:
value - The low notification's on/off switch value.
See Also:
getNotifyLow()

getDifferenceMode

public boolean getDifferenceMode()
Gets the difference mode flag value common to all observed MBeans.

Specified by:
getDifferenceMode in interface GaugeMonitorMBean
Returns:
true if the difference mode is used, false otherwise.
See Also:
setDifferenceMode(boolean)

setDifferenceMode

public void setDifferenceMode(boolean value)
Sets the difference mode flag value common to all observed MBeans.

Specified by:
setDifferenceMode in interface GaugeMonitorMBean
Parameters:
value - The difference mode flag value.
See Also:
getDifferenceMode()

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()
Returns a NotificationInfo object containing the name of the Java class of the notification and the notification types sent by the gauge monitor.

Specified by:
getNotificationInfo in interface NotificationBroadcaster
Overrides:
getNotificationInfo in class NotificationBroadcasterSupport
Returns:
the array of possible notifications.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


GaugeMonitorMBean

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.monitor
Interface GaugeMonitorMBean

All Superinterfaces:
MonitorMBean
All Known Implementing Classes:
GaugeMonitor
public interface GaugeMonitorMBean
extends MonitorMBean

Exposes the remote management interface of the gauge monitor MBean.

Since:
1.5

Method Summary
Number | getDerivedGauge() Deprecated. As of JMX 1.2, replaced by getDerivedGauge(ObjectName)
Number | getDerivedGauge(ObjectName object) Gets the derived gauge for the specified MBean.
long | getDerivedGaugeTimeStamp() Deprecated. As of JMX 1.2, replaced by getDerivedGaugeTimeStamp(ObjectName)
long | getDerivedGaugeTimeStamp(ObjectName object) Gets the derived gauge timestamp for the specified MBean.
boolean | getDifferenceMode() Gets the difference mode flag value.
Number | getHighThreshold() Gets the high threshold value.
Number | getLowThreshold() Gets the low threshold value.
boolean | getNotifyHigh() Gets the high notification's on/off switch value.
boolean | getNotifyLow() Gets the low notification's on/off switch value.
void | setDifferenceMode(boolean value) Sets the difference mode flag value.
void | setNotifyHigh(boolean value) Sets the high notification's on/off switch value.
void | setNotifyLow(boolean value) Sets the low notification's on/off switch value.
void | setThresholds(Number highValue, Number lowValue) Sets the high and the low threshold values.
Methods inherited from interface javax.management.monitor.MonitorMBean
addObservedObject, containsObservedObject, getGranularityPeriod, getObservedAttribute, getObservedObject, getObservedObjects, isActive, removeObservedObject, setGranularityPeriod, setObservedAttribute, setObservedObject, start, stop

Method Detail

getDerivedGauge

@Deprecated
Number getDerivedGauge()
Deprecated. As of JMX 1.2, replaced by getDerivedGauge(ObjectName)

Gets the derived gauge.

Returns:
The derived gauge.

getDerivedGaugeTimeStamp

@Deprecated
long getDerivedGaugeTimeStamp()
Deprecated. As of JMX 1.2, replaced by getDerivedGaugeTimeStamp(ObjectName)

Gets the derived gauge timestamp.

Returns:
The derived gauge timestamp.

getDerivedGauge

Number getDerivedGauge(ObjectName object)
Gets the derived gauge for the specified MBean.

Parameters:
object - the MBean for which the derived gauge is to be returned
Returns:
The derived gauge for the specified MBean if this MBean is in the set of observed MBeans, or null otherwise.

getDerivedGaugeTimeStamp

long getDerivedGaugeTimeStamp(ObjectName object)
Gets the derived gauge timestamp for the specified MBean.

Parameters:
object - the MBean for which the derived gauge timestamp is to be returned
Returns:
The derived gauge timestamp for the specified MBean if this MBean is in the set of observed MBeans, or null otherwise.

getHighThreshold

Number getHighThreshold()
Gets the high threshold value.

Returns:
The high threshold value.

getLowThreshold

Number getLowThreshold()
Gets the low threshold value.

Returns:
The low threshold value.

setThresholds

void setThresholds(Number highValue,
                   Number lowValue)
                   throws IllegalArgumentException
Sets the high and the low threshold values.

Parameters:
highValue - The high threshold value.
lowValue - The low threshold value.
Throws:
IllegalArgumentException - The specified high/low threshold is null or the low threshold is greater than the high threshold or the high threshold and the low threshold are not of the same type.

getNotifyHigh

boolean getNotifyHigh()
Gets the high notification's on/off switch value.

Returns:
true if the gauge monitor notifies when exceeding the high threshold, false otherwise.
See Also:
setNotifyHigh(boolean)

setNotifyHigh

void setNotifyHigh(boolean value)
Sets the high notification's on/off switch value.

Parameters:
value - The high notification's on/off switch value.
See Also:
getNotifyHigh()

getNotifyLow

boolean getNotifyLow()
Gets the low notification's on/off switch value.

Returns:
true if the gauge monitor notifies when exceeding the low threshold, false otherwise.
See Also:
setNotifyLow(boolean)

setNotifyLow

void setNotifyLow(boolean value)
Sets the low notification's on/off switch value.

Parameters:
value - The low notification's on/off switch value.
See Also:
getNotifyLow()

getDifferenceMode

boolean getDifferenceMode()
Gets the difference mode flag value.

Returns:
true if the difference mode is used, false otherwise.
See Also:
setDifferenceMode(boolean)

setDifferenceMode

void setDifferenceMode(boolean value)
Sets the difference mode flag value.

Parameters:
value - The difference mode flag value.
See Also:
getDifferenceMode()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Monitor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.monitor
Class Monitor

java.lang.Object
    extended by  javax.management.NotificationBroadcasterSupport
        extended by  javax.management.monitor.Monitor
All Implemented Interfaces:
MBeanRegistration, MonitorMBean, NotificationBroadcaster, NotificationEmitter
Direct Known Subclasses:
CounterMonitor, GaugeMonitor, StringMonitor
public abstract class Monitor
extends NotificationBroadcasterSupport
implements MonitorMBean, MBeanRegistration

Defines the part common to all monitor MBeans. A monitor MBean monitors values of an attribute common to a set of observed MBeans. The observed attribute is monitored at intervals specified by the granularity period. A gauge value (derived gauge) is derived from the values of the observed attribute.

Since:
1.5

Field Summary
protected int | alreadyNotified Deprecated. equivalent to alreadyNotifieds[0].
protected int[] | alreadyNotifieds Selected monitor errors that have already been notified.
protected static int | capacityIncrement The amount by which the capacity of the monitor arrays are automatically incremented when their size becomes greater than their capacity.
protected String | dbgTag Deprecated. No replacement.
protected int | elementCount The number of valid components in the vector of observed objects.
protected static int | OBSERVED_ATTRIBUTE_ERROR_NOTIFIED Flag denoting that a notification has occurred after changing the observed attribute.
protected static int | OBSERVED_ATTRIBUTE_TYPE_ERROR_NOTIFIED Flag denoting that a notification has occurred after changing the observed object or the observed attribute.
protected static int | OBSERVED_OBJECT_ERROR_NOTIFIED Flag denoting that a notification has occurred after changing the observed object.
protected static int | RESET_FLAGS_ALREADY_NOTIFIED This flag is used to reset the alreadyNotifieds monitor attribute.
protected static int | RUNTIME_ERROR_NOTIFIED Flag denoting that a notification has occurred after changing the observed object or the observed attribute.
protected MBeanServer | server Reference to the MBean server.
Constructor Summary
Monitor()
Method Summary
 void addObservedObject(ObjectName object)
Adds the specified object in the set of observed MBeans, if this object is not already present.
 boolean containsObservedObject(ObjectName object)
Tests whether the specified object is in the set of observed MBeans.
 long getGranularityPeriod()
Gets the granularity period (in milliseconds).
 String getObservedAttribute()
Gets the attribute being observed.
 ObjectName getObservedObject()
Deprecated. As of JMX 1.2, replaced by getObservedObjects()
 ObjectName[] getObservedObjects()
Returns an array containing the objects being observed.
 boolean isActive()
Tests whether the monitor MBean is active.
 void postDeregister()
Allows the monitor MBean to perform any operations needed after having been unregistered by the MBean server.
 void postRegister(Boolean registrationDone)
Allows the monitor MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.
 void preDeregister()
Allows the monitor MBean to perform any operations it needs before being unregistered by the MBean server.
 ObjectName preRegister(MBeanServer server, ObjectName name)
Allows the monitor MBean to perform any operations it needs before being registered in the MBean server.
 void removeObservedObject(ObjectName object)
Removes the specified object from the set of observed MBeans.
 void setGranularityPeriod(long period)
Sets the granularity period (in milliseconds).
 void setObservedAttribute(String attribute)
Sets the attribute to observe.
 void setObservedObject(ObjectName object)
Deprecated. As of JMX 1.2, replaced by addObservedObject(javax.management.ObjectName)
abstract  void start()
Starts the monitor.
abstract  void stop()
Stops the monitor.
Methods inherited from class javax.management.NotificationBroadcasterSupport
addNotificationListener, getNotificationInfo, handleNotification, removeNotificationListener, removeNotificationListener, sendNotification
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

capacityIncrement

protected static final int capacityIncrement
The amount by which the capacity of the monitor arrays are automatically incremented when their size becomes greater than their capacity.

See Also:
Constant Field Values

elementCount

protected int elementCount
The number of valid components in the vector of observed objects.

alreadyNotified

@Deprecated
protected int alreadyNotified
Deprecated. equivalent to alreadyNotifieds[0].
Monitor errors that have already been notified.

alreadyNotifieds

protected int[] alreadyNotifieds

Selected monitor errors that have already been notified.

Each element in this array corresponds to an observed object in the vector. It contains a bit mask of the flags OBSERVED_OBJECT_ERROR_NOTIFIED etc, indicating whether the corresponding notification has already been sent for the MBean being monitored.

server

protected MBeanServer server
Reference to the MBean server. This reference is null when the monitor MBean is not registered in an MBean server. This reference is initialized before the monitor MBean is registered in the MBean server.

See Also:
preRegister(MBeanServer server, ObjectName name)

RESET_FLAGS_ALREADY_NOTIFIED

protected static final int RESET_FLAGS_ALREADY_NOTIFIED
This flag is used to reset the alreadyNotifieds monitor attribute.

See Also:
Constant Field Values

OBSERVED_OBJECT_ERROR_NOTIFIED

protected static final int OBSERVED_OBJECT_ERROR_NOTIFIED
Flag denoting that a notification has occurred after changing the observed object. This flag is used to check that the new observed object is registered in the MBean server at the time of the first notification.

See Also:
Constant Field Values

OBSERVED_ATTRIBUTE_ERROR_NOTIFIED

protected static final int OBSERVED_ATTRIBUTE_ERROR_NOTIFIED
Flag denoting that a notification has occurred after changing the observed attribute. This flag is used to check that the new observed attribute belongs to the observed object at the time of the first notification.

See Also:
Constant Field Values

OBSERVED_ATTRIBUTE_TYPE_ERROR_NOTIFIED

protected static final int OBSERVED_ATTRIBUTE_TYPE_ERROR_NOTIFIED
Flag denoting that a notification has occurred after changing the observed object or the observed attribute. This flag is used to check that the observed attribute type is correct (depending on the monitor in use) at the time of the first notification.

See Also:
Constant Field Values

RUNTIME_ERROR_NOTIFIED

protected static final int RUNTIME_ERROR_NOTIFIED
Flag denoting that a notification has occurred after changing the observed object or the observed attribute. This flag is used to notify any exception (except the cases described above) when trying to get the value of the observed attribute at the time of the first notification.

See Also:
Constant Field Values

dbgTag

@Deprecated
protected String dbgTag
Deprecated. No replacement.
This field is retained for compatibility but should not be referenced.

Constructor Detail

Monitor

public Monitor()
Method Detail

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception
Allows the monitor MBean to perform any operations it needs before being registered in the MBean server.

Initializes the reference to the MBean server.

Specified by:
preRegister in interface MBeanRegistration
Parameters:
server - The MBean server in which the monitor MBean will be registered.
name - The object name of the monitor MBean.
Returns:
The name of the monitor MBean registered.
Throws:
Exception

postRegister

public void postRegister(Boolean registrationDone)
Allows the monitor MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.

Not used in this context.

Specified by:
postRegister in interface MBeanRegistration
Parameters:
registrationDone - Indicates whether or not the MBean has been successfully registered in the MBean server. The value false means that the registration phase has failed.

preDeregister

public void preDeregister()
                   throws Exception
Allows the monitor MBean to perform any operations it needs before being unregistered by the MBean server.

Stops the monitor.

Specified by:
preDeregister in interface MBeanRegistration
Throws:
Exception

postDeregister

public void postDeregister()
Allows the monitor MBean to perform any operations needed after having been unregistered by the MBean server.

Not used in this context.

Specified by:
postDeregister in interface MBeanRegistration

start

public abstract void start()
Starts the monitor.

Specified by:
start in interface MonitorMBean

stop

public abstract void stop()
Stops the monitor.

Specified by:
stop in interface MonitorMBean

getObservedObject

@Deprecated
public ObjectName getObservedObject()
Deprecated. As of JMX 1.2, replaced by getObservedObjects()

Returns the object name of the first object in the set of observed MBeans, or null if there is no such object.

Specified by:
getObservedObject in interface MonitorMBean
Returns:
The object being observed.
See Also:
setObservedObject(ObjectName)

setObservedObject

@Deprecated
public void setObservedObject(ObjectName object)
                       throws IllegalArgumentException
Deprecated. As of JMX 1.2, replaced by addObservedObject(javax.management.ObjectName)

Removes all objects from the set of observed objects, and then adds the specified object.

Specified by:
setObservedObject in interface MonitorMBean
Parameters:
object - The object to observe.
Throws:
IllegalArgumentException - The specified object is null.
See Also:
getObservedObject()

addObservedObject

public void addObservedObject(ObjectName object)
                       throws IllegalArgumentException
Adds the specified object in the set of observed MBeans, if this object is not already present.

Specified by:
addObservedObject in interface MonitorMBean
Parameters:
object - The object to observe.
Throws:
IllegalArgumentException - The specified object is null.

removeObservedObject

public void removeObservedObject(ObjectName object)
Removes the specified object from the set of observed MBeans.

Specified by:
removeObservedObject in interface MonitorMBean
Parameters:
object - The object to remove.

containsObservedObject

public boolean containsObservedObject(ObjectName object)
Tests whether the specified object is in the set of observed MBeans.

Specified by:
containsObservedObject in interface MonitorMBean
Parameters:
object - The object to check.
Returns:
true if the specified object is present, false otherwise.

getObservedObjects

public ObjectName[] getObservedObjects()
Returns an array containing the objects being observed.

Specified by:
getObservedObjects in interface MonitorMBean
Returns:
The objects being observed.

getObservedAttribute

public String getObservedAttribute()
Gets the attribute being observed.
The observed attribute is not initialized by default (set to null).

Specified by:
getObservedAttribute in interface MonitorMBean
Returns:
The attribute being observed.
See Also:
setObservedAttribute(java.lang.String)

setObservedAttribute

public void setObservedAttribute(String attribute)
                          throws IllegalArgumentException
Sets the attribute to observe.
The observed attribute is not initialized by default (set to null).

Specified by:
setObservedAttribute in interface MonitorMBean
Parameters:
attribute - The attribute to observe.
Throws:
IllegalArgumentException - The specified attribute is null.
See Also:
getObservedAttribute()

getGranularityPeriod

public long getGranularityPeriod()
Gets the granularity period (in milliseconds).
The default value of the granularity period is 10 seconds.

Specified by:
getGranularityPeriod in interface MonitorMBean
Returns:
The granularity period value.
See Also:
setGranularityPeriod(long)

setGranularityPeriod

public void setGranularityPeriod(long period)
                          throws IllegalArgumentException
Sets the granularity period (in milliseconds).
The default value of the granularity period is 10 seconds.

Specified by:
setGranularityPeriod in interface MonitorMBean
Parameters:
period - The granularity period value.
Throws:
IllegalArgumentException - The granularity period is less than or equal to zero.
See Also:
getGranularityPeriod()

isActive

public boolean isActive()
Tests whether the monitor MBean is active. A monitor MBean is marked active when the start method is called. It becomes inactive when the stop method is called.

Specified by:
isActive in interface MonitorMBean
Returns:
true if the monitor MBean is active, false otherwise.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MonitorMBean

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.monitor
Interface MonitorMBean

All Known Subinterfaces:
CounterMonitorMBean, GaugeMonitorMBean, StringMonitorMBean
All Known Implementing Classes:
CounterMonitor, GaugeMonitor, Monitor, StringMonitor
public interface MonitorMBean

Exposes the remote management interface of monitor MBeans.

Since:
1.5

Method Summary
 void addObservedObject(ObjectName object)
Adds the specified object in the set of observed MBeans.
 boolean containsObservedObject(ObjectName object)
Tests whether the specified object is in the set of observed MBeans.
 long getGranularityPeriod()
Gets the granularity period (in milliseconds).
 String getObservedAttribute()
Gets the attribute being observed.
 ObjectName getObservedObject()
Deprecated. As of JMX 1.2, replaced by getObservedObjects()
 ObjectName[] getObservedObjects()
Returns an array containing the objects being observed.
 boolean isActive()
Tests if the monitor MBean is active.
 void removeObservedObject(ObjectName object)
Removes the specified object from the set of observed MBeans.
 void setGranularityPeriod(long period)
Sets the granularity period (in milliseconds).
 void setObservedAttribute(String attribute)
Sets the attribute to observe.
 void setObservedObject(ObjectName object)
Deprecated. As of JMX 1.2, replaced by addObservedObject(javax.management.ObjectName)
 void start()
Starts the monitor.
 void stop()
Stops the monitor.

Method Detail

start

void start()
Starts the monitor.

stop

void stop()
Stops the monitor.

addObservedObject

void addObservedObject(ObjectName object)
                       throws IllegalArgumentException
Adds the specified object in the set of observed MBeans.

Parameters:
object - The object to observe.
Throws:
IllegalArgumentException - the specified object is null.

removeObservedObject

void removeObservedObject(ObjectName object)
Removes the specified object from the set of observed MBeans.

Parameters:
object - The object to remove.

containsObservedObject

boolean containsObservedObject(ObjectName object)
Tests whether the specified object is in the set of observed MBeans.

Parameters:
object - The object to check.
Returns:
true if the specified object is in the set, false otherwise.

getObservedObjects

ObjectName[] getObservedObjects()
Returns an array containing the objects being observed.

Returns:
The objects being observed.

getObservedObject

@Deprecated
ObjectName getObservedObject()
Deprecated. As of JMX 1.2, replaced by getObservedObjects()

Gets the object name of the object being observed.

Returns:
The object being observed.
See Also:
setObservedObject(javax.management.ObjectName)

setObservedObject

@Deprecated
void setObservedObject(ObjectName object)
Deprecated. As of JMX 1.2, replaced by addObservedObject(javax.management.ObjectName)

Sets the object to observe identified by its object name.

Parameters:
object - The object to observe.
See Also:
getObservedObject()

getObservedAttribute

String getObservedAttribute()
Gets the attribute being observed.

Returns:
The attribute being observed.
See Also:
setObservedAttribute(java.lang.String)

setObservedAttribute

void setObservedAttribute(String attribute)
Sets the attribute to observe.

Parameters:
attribute - The attribute to observe.
See Also:
getObservedAttribute()

getGranularityPeriod

long getGranularityPeriod()
Gets the granularity period (in milliseconds).

Returns:
The granularity period.
See Also:
setGranularityPeriod(long)

setGranularityPeriod

void setGranularityPeriod(long period)
                          throws IllegalArgumentException
Sets the granularity period (in milliseconds).

Parameters:
period - The granularity period.
Throws:
IllegalArgumentException - The granularity period is less than or equal to zero.
See Also:
getGranularityPeriod()

isActive

boolean isActive()
Tests if the monitor MBean is active. A monitor MBean is marked active when the start method is called. It becomes inactive when the stop method is called.

Returns:
true if the monitor MBean is active, false otherwise.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MonitorNotification

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.monitor
Class MonitorNotification

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.management.Notification
            extended by  javax.management.monitor.MonitorNotification
All Implemented Interfaces:
Serializable
public class MonitorNotification
extends Notification

Provides definitions of the notifications sent by monitor MBeans.

The notification source and a set of parameters concerning the monitor MBean's state need to be specified when creating a new object of this class. The list of notifications fired by the monitor MBeans is the following:

  • Common to all kind of monitors:
    • The observed object is not registered in the MBean server.
    • The observed attribute is not contained in the observed object.
    • The type of the observed attribute is not correct.
    • Any exception (except the cases described above) occurs when trying to get the value of the observed attribute.
  • Common to the counter and the gauge monitors:
    • The threshold high or threshold low are not of the same type as the gauge (gauge monitors).
    • The threshold or the offset or the modulus are not of the same type as the counter (counter monitors).
  • Counter monitors only:
    • The observed attribute has reached the threshold value.
  • Gauge monitors only:
    • The observed attribute has exceeded the threshold high value.
    • The observed attribute has exceeded the threshold low value.
  • String monitors only:
    • The observed attribute has matched the "string to compare" value.
    • The observed attribute has differed from the "string to compare" value.

Since:
1.5
See Also:
Serialized Form

Field Summary
static String | OBSERVED_ATTRIBUTE_ERROR Notification type denoting that the observed attribute is not contained in the observed object.
static String | OBSERVED_ATTRIBUTE_TYPE_ERROR Notification type denoting that the type of the observed attribute is not correct.
static String | OBSERVED_OBJECT_ERROR Notification type denoting that the observed object is not registered in the MBean server.
static String | RUNTIME_ERROR Notification type denoting that a non-predefined error type has occurred when trying to get the value of the observed attribute.
static String | STRING_TO_COMPARE_VALUE_DIFFERED Notification type denoting that the observed attribute has differed from the "string to compare" value.
static String | STRING_TO_COMPARE_VALUE_MATCHED Notification type denoting that the observed attribute has matched the "string to compare" value.
static String | THRESHOLD_ERROR Notification type denoting that the type of the thresholds, offset or modulus is not correct.
static String | THRESHOLD_HIGH_VALUE_EXCEEDED Notification type denoting that the observed attribute has exceeded the threshold high value.
static String | THRESHOLD_LOW_VALUE_EXCEEDED Notification type denoting that the observed attribute has exceeded the threshold low value.
static String | THRESHOLD_VALUE_EXCEEDED Notification type denoting that the observed attribute has reached the threshold value.
Fields inherited from class javax.management.Notification
source
Method Summary
Object | getDerivedGauge() Gets the derived gauge of this monitor notification.
String | getObservedAttribute() Gets the observed attribute of this monitor notification.
ObjectName | getObservedObject() Gets the observed object of this monitor notification.
Object | getTrigger() Gets the threshold/string (depending on the monitor type) that triggered off this monitor notification.
Methods inherited from class javax.management.Notification
getMessage, getSequenceNumber, getTimeStamp, getType, getUserData, setSequenceNumber, setSource, setTimeStamp, setUserData, toString
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

OBSERVED_OBJECT_ERROR

public static final String OBSERVED_OBJECT_ERROR
Notification type denoting that the observed object is not registered in the MBean server. This notification is fired by all kinds of monitors.
The value of this notification type is jmx.monitor.error.mbean.

See Also:
Constant Field Values

OBSERVED_ATTRIBUTE_ERROR

public static final String OBSERVED_ATTRIBUTE_ERROR
Notification type denoting that the observed attribute is not contained in the observed object. This notification is fired by all kinds of monitors.
The value of this notification type is jmx.monitor.error.attribute.

See Also:
Constant Field Values

OBSERVED_ATTRIBUTE_TYPE_ERROR

public static final String OBSERVED_ATTRIBUTE_TYPE_ERROR
Notification type denoting that the type of the observed attribute is not correct. This notification is fired by all kinds of monitors.
The value of this notification type is jmx.monitor.error.type.

See Also:
Constant Field Values

THRESHOLD_ERROR

public static final String THRESHOLD_ERROR
Notification type denoting that the type of the thresholds, offset or modulus is not correct. This notification is fired by counter and gauge monitors.
The value of this notification type is jmx.monitor.error.threshold.

See Also:
Constant Field Values

RUNTIME_ERROR

public static final String RUNTIME_ERROR
Notification type denoting that a non-predefined error type has occurred when trying to get the value of the observed attribute. This notification is fired by all kinds of monitors.
The value of this notification type is jmx.monitor.error.runtime.

See Also:
Constant Field Values

THRESHOLD_VALUE_EXCEEDED

public static final String THRESHOLD_VALUE_EXCEEDED
Notification type denoting that the observed attribute has reached the threshold value. This notification is only fired by counter monitors.
The value of this notification type is jmx.monitor.counter.threshold.

See Also:
Constant Field Values

THRESHOLD_HIGH_VALUE_EXCEEDED

public static final String THRESHOLD_HIGH_VALUE_EXCEEDED
Notification type denoting that the observed attribute has exceeded the threshold high value. This notification is only fired by gauge monitors.
The value of this notification type is jmx.monitor.gauge.high.

See Also:
Constant Field Values

THRESHOLD_LOW_VALUE_EXCEEDED

public static final String THRESHOLD_LOW_VALUE_EXCEEDED
Notification type denoting that the observed attribute has exceeded the threshold low value. This notification is only fired by gauge monitors.
The value of this notification type is jmx.monitor.gauge.low.

See Also:
Constant Field Values

STRING_TO_COMPARE_VALUE_MATCHED

public static final String STRING_TO_COMPARE_VALUE_MATCHED
Notification type denoting that the observed attribute has matched the "string to compare" value. This notification is only fired by string monitors.
The value of this notification type is jmx.monitor.string.matches.

See Also:
Constant Field Values

STRING_TO_COMPARE_VALUE_DIFFERED

public static final String STRING_TO_COMPARE_VALUE_DIFFERED
Notification type denoting that the observed attribute has differed from the "string to compare" value. This notification is only fired by string monitors.
The value of this notification type is jmx.monitor.string.differs.

See Also:
Constant Field Values
Method Detail

getObservedObject

public ObjectName getObservedObject()
Gets the observed object of this monitor notification.

Returns:
The observed object.

getObservedAttribute

public String getObservedAttribute()
Gets the observed attribute of this monitor notification.

Returns:
The observed attribute.

getDerivedGauge

public Object getDerivedGauge()
Gets the derived gauge of this monitor notification.

Returns:
The derived gauge.

getTrigger

public Object getTrigger()
Gets the threshold/string (depending on the monitor type) that triggered off this monitor notification.

Returns:
The trigger.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MonitorSettingException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.monitor
Class MonitorSettingException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  javax.management.JMRuntimeException
                    extended by  javax.management.monitor.MonitorSettingException
All Implemented Interfaces:
Serializable
public class MonitorSettingException
extends JMRuntimeException

Exception thrown by the monitor when a monitor setting becomes invalid while the monitor is running.

As the monitor attributes may change at runtime, a check is performed before each observation. If a monitor attribute has become invalid, a monitor setting exception is thrown.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
MonitorSettingException()
Default constructor.
MonitorSettingException(String message)
Constructor that allows an error message to be specified.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MonitorSettingException

public MonitorSettingException()
Default constructor.

MonitorSettingException

public MonitorSettingException(String message)
Constructor that allows an error message to be specified.

Parameters:
message - The specific error message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StringMonitor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.monitor
Class StringMonitor

java.lang.Object
    extended by  javax.management.NotificationBroadcasterSupport
        extended by  javax.management.monitor.Monitor
            extended by  javax.management.monitor.StringMonitor
All Implemented Interfaces:
MBeanRegistration, MonitorMBean, StringMonitorMBean, NotificationBroadcaster, NotificationEmitter
public class StringMonitor
extends Monitor
implements StringMonitorMBean

Defines a monitor MBean designed to observe the values of a string attribute.

A string monitor sends notifications as follows:

  • if the attribute value matches the string to compare value, a match notification is sent. The notify match flag must be set to true.
    Subsequent matchings of the string to compare values do not cause further notifications unless the attribute value differs from the string to compare value.
  • if the attribute value differs from the string to compare value, a differ notification is sent. The notify differ flag must be set to true.
    Subsequent differences from the string to compare value do not cause further notifications unless the attribute value matches the string to compare value.

Since:
1.5

Field Summary
Fields inherited from class javax.management.monitor.Monitor
alreadyNotified, alreadyNotifieds, capacityIncrement, dbgTag, elementCount, OBSERVED_ATTRIBUTE_ERROR_NOTIFIED, OBSERVED_ATTRIBUTE_TYPE_ERROR_NOTIFIED, OBSERVED_OBJECT_ERROR_NOTIFIED, RESET_FLAGS_ALREADY_NOTIFIED, RUNTIME_ERROR_NOTIFIED, server
Constructor Summary
StringMonitor()
Default constructor.
Method Summary
String | getDerivedGauge() Deprecated. As of JMX 1.2, replaced by getDerivedGauge(ObjectName)
String | getDerivedGauge(ObjectName object) Gets the derived gauge of the specified object, if this object is contained in the set of observed MBeans, or null otherwise.
long | getDerivedGaugeTimeStamp() Deprecated. As of JMX 1.2, replaced by getDerivedGaugeTimeStamp(ObjectName)
long | getDerivedGaugeTimeStamp(ObjectName object) Gets the derived gauge timestamp of the specified object, if this object is contained in the set of observed MBeans, or 0 otherwise.
MBeanNotificationInfo[] | getNotificationInfo() Returns a NotificationInfo object containing the name of the Java class of the notification and the notification types sent by the string monitor.
boolean | getNotifyDiffer() Gets the differing notification's on/off switch value common to all observed MBeans.
boolean | getNotifyMatch() Gets the matching notification's on/off switch value common to all observed MBeans.
String | getStringToCompare() Gets the string to compare with the observed attribute common to all observed MBeans.
void | setNotifyDiffer(boolean value) Sets the differing notification's on/off switch value common to all observed MBeans.
void | setNotifyMatch(boolean value) Sets the matching notification's on/off switch value common to all observed MBeans.
void | setStringToCompare(String value) Sets the string to compare with the observed attribute common to all observed MBeans.
void | start() Starts the string monitor.
void | stop() Stops the string monitor.
Methods inherited from class javax.management.monitor.Monitor
addObservedObject, containsObservedObject, getGranularityPeriod, getObservedAttribute, getObservedObject, getObservedObjects, isActive, postDeregister, postRegister, preDeregister, preRegister, removeObservedObject, setGranularityPeriod, setObservedAttribute, setObservedObject
Methods inherited from class javax.management.NotificationBroadcasterSupport
addNotificationListener, handleNotification, removeNotificationListener, removeNotificationListener, sendNotification
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.management.monitor.MonitorMBean
addObservedObject, containsObservedObject, getGranularityPeriod, getObservedAttribute, getObservedObject, getObservedObjects, isActive, removeObservedObject, setGranularityPeriod, setObservedAttribute, setObservedObject

Constructor Detail

StringMonitor

public StringMonitor()
Default constructor.

Method Detail

start

public void start()
Starts the string monitor.

Specified by:
start in interface MonitorMBean
Specified by:
start in class Monitor

stop

public void stop()
Stops the string monitor.

Specified by:
stop in interface MonitorMBean
Specified by:
stop in class Monitor

getDerivedGauge

public String getDerivedGauge(ObjectName object)
Gets the derived gauge of the specified object, if this object is contained in the set of observed MBeans, or null otherwise.

Specified by:
getDerivedGauge in interface StringMonitorMBean
Parameters:
object - the name of the MBean whose derived gauge is required.
Returns:
The derived gauge of the specified object.

getDerivedGaugeTimeStamp

public long getDerivedGaugeTimeStamp(ObjectName object)
Gets the derived gauge timestamp of the specified object, if this object is contained in the set of observed MBeans, or 0 otherwise.

Specified by:
getDerivedGaugeTimeStamp in interface StringMonitorMBean
Parameters:
object - the name of the object whose derived gauge timestamp is to be returned.
Returns:
The derived gauge timestamp of the specified object.

getDerivedGauge

@Deprecated
public String getDerivedGauge()
Deprecated. As of JMX 1.2, replaced by getDerivedGauge(ObjectName)

Returns the derived gauge of the first object in the set of observed MBeans.

Specified by:
getDerivedGauge in interface StringMonitorMBean
Returns:
The derived gauge.

getDerivedGaugeTimeStamp

@Deprecated
public long getDerivedGaugeTimeStamp()
Deprecated. As of JMX 1.2, replaced by getDerivedGaugeTimeStamp(ObjectName)

Gets the derived gauge timestamp of the first object in the set of observed MBeans.

Specified by:
getDerivedGaugeTimeStamp in interface StringMonitorMBean
Returns:
The derived gauge timestamp.

getStringToCompare

public String getStringToCompare()
Gets the string to compare with the observed attribute common to all observed MBeans.

Specified by:
getStringToCompare in interface StringMonitorMBean
Returns:
The string value.
See Also:
setStringToCompare(java.lang.String)

setStringToCompare

public void setStringToCompare(String value)
                        throws IllegalArgumentException
Sets the string to compare with the observed attribute common to all observed MBeans.

Specified by:
setStringToCompare in interface StringMonitorMBean
Parameters:
value - The string value.
Throws:
IllegalArgumentException - The specified string to compare is null.
See Also:
getStringToCompare()

getNotifyMatch

public boolean getNotifyMatch()
Gets the matching notification's on/off switch value common to all observed MBeans.

Specified by:
getNotifyMatch in interface StringMonitorMBean
Returns:
true if the string monitor notifies when matching the string to compare, false otherwise.
See Also:
setNotifyMatch(boolean)

setNotifyMatch

public void setNotifyMatch(boolean value)
Sets the matching notification's on/off switch value common to all observed MBeans.

Specified by:
setNotifyMatch in interface StringMonitorMBean
Parameters:
value - The matching notification's on/off switch value.
See Also:
getNotifyMatch()

getNotifyDiffer

public boolean getNotifyDiffer()
Gets the differing notification's on/off switch value common to all observed MBeans.

Specified by:
getNotifyDiffer in interface StringMonitorMBean
Returns:
true if the string monitor notifies when differing from the string to compare, false otherwise.
See Also:
setNotifyDiffer(boolean)

setNotifyDiffer

public void setNotifyDiffer(boolean value)
Sets the differing notification's on/off switch value common to all observed MBeans.

Specified by:
setNotifyDiffer in interface StringMonitorMBean
Parameters:
value - The differing notification's on/off switch value.
See Also:
getNotifyDiffer()

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()
Returns a NotificationInfo object containing the name of the Java class of the notification and the notification types sent by the string monitor.

Specified by:
getNotificationInfo in interface NotificationBroadcaster
Overrides:
getNotificationInfo in class NotificationBroadcasterSupport
Returns:
the array of possible notifications.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StringMonitorMBean

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.management.monitor
Interface StringMonitorMBean

All Superinterfaces:
MonitorMBean
All Known Implementing Classes:
StringMonitor
public interface StringMonitorMBean
extends MonitorMBean

Exposes the remote management interface of the string monitor MBean.

Since:
1.5

Method Summary
String | getDerivedGauge() Deprecated. As of JMX 1.2, replaced by getDerivedGauge(ObjectName)
String | getDerivedGauge(ObjectName object) Gets the derived gauge for the specified MBean.
long | getDerivedGaugeTimeStamp() Deprecated. As of JMX 1.2, replaced by getDerivedGaugeTimeStamp(ObjectName)
long | getDerivedGaugeTimeStamp(ObjectName object) Gets the derived gauge timestamp for the specified MBean.
boolean | getNotifyDiffer() Gets the differing notification's on/off switch value.
boolean | getNotifyMatch() Gets the matching notification's on/off switch value.
String | getStringToCompare() Gets the string to compare with the observed attribute.
void | setNotifyDiffer(boolean value) Sets the differing notification's on/off switch value.
void | setNotifyMatch(boolean value) Sets the matching notification's on/off switch value.
void | setStringToCompare(String value) Sets the string to compare with the observed attribute.
Methods inherited from interface javax.management.monitor.MonitorMBean
addObservedObject, containsObservedObject, getGranularityPeriod, getObservedAttribute, getObservedObject, getObservedObjects, isActive, removeObservedObject, setGranularityPeriod, setObservedAttribute, setObservedObject, start, stop

Method Detail

getDerivedGauge

@Deprecated
String getDerivedGauge()
Deprecated. As of JMX 1.2, replaced by getDerivedGauge(ObjectName)

Gets the derived gauge.

Returns:
The derived gauge.

getDerivedGaugeTimeStamp

@Deprecated
long getDerivedGaugeTimeStamp()
Deprecated. As of JMX 1.2, replaced by getDerivedGaugeTimeStamp(ObjectName)

Gets the derived gauge timestamp.

Returns:
The derived gauge timestamp.

getDerivedGauge

String getDerivedGauge(ObjectName object)
Gets the derived gauge for the specified MBean.

Parameters:
object - the MBean for which the derived gauge is to be returned
Returns:
The derived gauge for the specified MBean if this MBean is in the set of observed MBeans, or null otherwise.

getDerivedGaugeTimeStamp

long getDerivedGaugeTimeStamp(ObjectName object)
Gets the derived gauge timestamp for the specified MBean.

Parameters:
object - the MBean for which the derived gauge timestamp is to be returned
Returns:
The derived gauge timestamp for the specified MBean if this MBean is in the set of observed MBeans, or null otherwise.

getStringToCompare

String getStringToCompare()
Gets the string to compare with the observed attribute.

Returns:
The string value.
See Also:
setStringToCompare(java.lang.String)

setStringToCompare

void setStringToCompare(String value)
                        throws IllegalArgumentException
Sets the string to compare with the observed attribute.

Parameters:
value - The string value.
Throws:
IllegalArgumentException - The specified string to compare is null.
See Also:
getStringToCompare()

getNotifyMatch

boolean getNotifyMatch()
Gets the matching notification's on/off switch value.

Returns:
true if the string monitor notifies when matching, false otherwise.
See Also:
setNotifyMatch(boolean)

setNotifyMatch

void setNotifyMatch(boolean value)
Sets the matching notification's on/off switch value.

Parameters:
value - The matching notification's on/off switch value.
See Also:
getNotifyMatch()

getNotifyDiffer

boolean getNotifyDiffer()
Gets the differing notification's on/off switch value.

Returns:
true if the string monitor notifies when differing, false otherwise.
See Also:
setNotifyDiffer(boolean)

setNotifyDiffer

void setNotifyDiffer(boolean value)
Sets the differing notification's on/off switch value.

Parameters:
value - The differing notification's on/off switch value.
See Also:
getNotifyDiffer()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


MXBean

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.management
Annotation Type MXBean

@Documented
@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface MXBean

Annotation to mark an interface explicitly as being an MXBean interface, or as not being an MXBean interface. By default, an interface is an MXBean interface if its name ends with MXBean, as in SomethingMXBean. The following interfaces are MXBean interfaces:

    public interface WhatsitMXBean {}

    @MXBean
    public interface Whatsit1Interface {}

    @MXBean(true)
    public interface Whatsit2Interface {}

The following interfaces are not MXBean interfaces:

    public interface Whatsit3Interface{}

    @MXBean(false)
    public interface MisleadingMXBean {}

MXBean specification

The MXBean concept provides a simple way to code an MBean that only references a predefined set of types, the ones defined by javax.management.openmbean. In this way, you can be sure that your MBean will be usable by any client, including remote clients, without any requirement that the client have access to model-specific classes representing the types of your MBeans.

The concepts are easier to understand by comparison with the Standard MBean concept. Here is how a managed object might be represented as a Standard MBean, and as an MXBean:

Standard MBean MXBean
public interface MemoryPoolMBean {
    String getName();
    MemoryUsage getUsage();
    // ...
}

public interface MemoryPoolMXBean {
    String getName();
    MemoryUsage getUsage();
    // ...
}

As you can see, the definitions are very similar. The only difference is that the convention for naming the interface is to use SomethingMXBean for MXBeans, rather than SomethingMBean for Standard MBeans.

In this managed object, there is an attribute called Usage of type MemoryUsage. The point of an attribute like this is that it gives a coherent snapshot of a set of data items. For example, it might include the current amount of used memory in the memory pool, and the current maximum of the memory pool. If these were separate items, obtained with separate getAttribute calls, then we could get values seen at different times that were not consistent. We might get a used value that was greater than the max value.

So, we might define MemoryUsage like this:

Standard MBean MXBean
public class MemoryUsage implements Serializable {
    // standard JavaBean conventions with getters

    public MemoryUsage(long init, long used,
                       long committed, long max) {...}
    long getInit() {...}
    long getUsed() {...}
    long getCommitted() {...}
    long getMax() {...}
}

public class MemoryUsage {
    // standard JavaBean conventions with getters
    @ConstructorProperties({"init", "used", "committed", "max"})
    public MemoryUsage(long init, long used,
                       long committed, long max) {...}
    long getInit() {...}
    long getUsed() {...}
    long getCommitted() {...}
    long getMax() {...}
}

The definitions are the same in the two cases, except that with the MXBean, MemoryUsage no longer needs to be marked Serializable (though it can be). On the other hand, we have added a @ConstructorProperties annotation to link the constructor parameters to the corresponding getters. We will see more about this below.

MemoryUsage is a model-specific class. With Standard MBeans, a client of the MBean Server cannot access the Usage attribute if it does not know the class MemoryUsage. Suppose the client is a generic console based on JMX technology. Then the console would have to be configured with the model-specific classes of every application it might connect to. The problem is even worse for clients that are not written in the Java language. Then there may not be any way to tell the client what a MemoryUsage looks like.

This is where MXBeans differ from Standard MBeans. Although we define the management interface in almost exactly the same way, the MXBean framework converts model-specific classes into standard classes from the Java platform. Using arrays and the CompositeData and TabularData classes from the standard javax.management.openmbean package, it is possible to build data structures of arbitrary complexity using only standard classes.

This becomes clearer if we compare what the clients of the two models might look like:

Standard MBean MXBean
String name = (String)
    mbeanServer.getAttribute(objectName, "Name");
MemoryUsage usage = (MemoryUsage)
    mbeanServer.getAttribute(objectName, "Usage");
long used = usage.getUsed();

String name = (String)
    mbeanServer.getAttribute(objectName, "Name");
CompositeData usage = (CompositeData)
    mbeanServer.getAttribute(objectName, "Usage");
long used = (Long) usage.get("used");

For attributes with simple types like String, the code is the same. But for attributes with complex types, the Standard MBean code requires the client to know the model-specific class MemoryUsage, while the MXBean code requires no non-standard classes.

The client code shown here is slightly more complicated for the MXBean client. But, if the client does in fact know the model, here the interface MemoryPoolMXBean and the class MemoryUsage, then it can construct a proxy. This is the recommended way to interact with managed objects when you know the model beforehand, regardless of whether you are using Standard MBeans or MXBeans:

Standard MBean MXBean
MemoryPoolMBean proxy =
    JMX.newMBeanProxy(
        mbeanServer,
        objectName,
        MemoryPoolMBean.class);
String name = proxy.getName();
MemoryUsage usage = proxy.getUsage();
long used = usage.getUsed();

MemoryPoolMXBean proxy =
    JMX.newMXBeanProxy(
        mbeanServer,
        objectName,
        MemoryPoolMXBean.class);
String name = proxy.getName();
MemoryUsage usage = proxy.getUsage();
long used = usage.getUsed();

Implementing the MemoryPool object works similarly for both Standard MBeans and MXBeans.

Standard MBean MXBean
public class MemoryPool
        implements MemoryPoolMBean {
    public String getName() {...}
    public MemoryUsage getUsage() {...}
    // ...
}

public class MemoryPool
        implements MemoryPoolMXBean {
    public String getName() {...}
    public MemoryUsage getUsage() {...}
    // ...
}

Registering the MBean in the MBean Server works in the same way in both cases:

Standard MBean MXBean
{
    MemoryPoolMBean pool = new MemoryPool();
    mbeanServer.registerMBean(pool, objectName);
}

{
    MemoryPoolMXBean pool = new MemoryPool();
    mbeanServer.registerMBean(pool, objectName);
}

Definition of an MXBean

An MXBean is a kind of MBean. An MXBean object can be registered directly in the MBean Server, or it can be used as an argument to StandardMBean and the resultant MBean registered in the MBean Server.

When an object is registered in the MBean Server using the registerMBean or createMBean methods of the MBeanServer interface, the object's class is examined to determine what type of MBean it is:

  • If the class implements the interface DynamicMBean then the MBean is a Dynamic MBean. Note that the class StandardMBean implements this interface, so this case applies to a Standard MBean or MXBean created using the class StandardMBean.
  • Otherwise, if the class matches the Standard MBean naming conventions, then the MBean is a Standard MBean.
  • Otherwise, it may be an MXBean. The set of interfaces implemented by the object is examined for interfaces that:
    • have a class name SMXBean where S is any non-empty string, and do not have an annotation @MXBean(false); and/or
    • have an annotation @MXBean(true) or just @MXBean.
    If there is exactly one such interface, or if there is one such interface that is a subinterface of all the others, then the object is an MXBean. The interface in question is the MXBean interface. In the example above, the MXBean interface is MemoryPoolMXBean.
  • If none of these conditions is met, the MBean is invalid and the attempt to register it will generate NotCompliantMBeanException.

Every Java type that appears as the parameter or return type of a method in an MXBean interface must be convertible using the rules below. Additionally, parameters must be reconstructible as defined below.

An attempt to construct an MXBean that does not conform to the above rules will produce an exception.

Naming conventions

The same naming conventions are applied to the methods in an MXBean as in a Standard MBean:

  1. A method T getN(), where T is a Java type (not void) and N is a non-empty string, specifies that there is a readable attribute called N. The Java type and Open type of the attribute are determined by the mapping rules below. The method final Class getClass() inherited from Object is ignored when looking for getters.
  2. A method boolean isN() specifies that there is a readable attribute called N with Java type boolean and Open type SimpleType.Boolean.
  3. A method void setN(T x) specifies that there is a writeable attribute called N. The Java type and Open type of the attribute are determined by the mapping rules below. (Of course, the name x of the parameter is irrelevant.)
  4. Every other method specifies that there is an operation with the same name as the method. The Java type and Open type of the return value and of each parameter are determined by the mapping rules below.

The rules for getN and isN collectively define the notion of a getter. The rule for setN defines the notion of a setter.

It is an error for there to be two getters with the same name, or two setters with the same name. If there is a getter and a setter for the same name, then the type T in both must be the same. In this case the attribute is read/write. If there is only a getter or only a setter, the attribute is read-only or write-only respectively.

Type mapping rules

An MXBean is a kind of Open MBean, as defined by the javax.management.openmbean package. This means that the types of attributes, operation parameters, and operation return values must all be describable using Open Types, that is the four standard subclasses of OpenType. MXBeans achieve this by mapping Java types into Open Types.

For every Java type J, the MXBean mapping is described by the following information:

  • The corresponding Open Type, opentype(J). This is an instance of a subclass of OpenType.
  • The mapped Java type, opendata(J), which is always the same for any given opentype(J). This is a Java class.
  • How a value is converted from type J to type opendata(J).
  • How a value is converted from type opendata(J) to type J, if it can be.

For example, for the Java type List<String>:

  • The Open Type, opentype(List<String>), is ArrayType (1, SimpleType.STRING ), representing a 1-dimensional array of Strings.
  • The mapped Java type, opendata(List<String>), is String[].
  • A List<String> can be converted to a String[] using List.toArray(new String[0]).
  • A String[] can be converted to a List<String> using Arrays.asList.

If no mapping rules exist to derive opentype(J) from J, then J cannot be the type of a method parameter or return value in an MXBean interface.

If there is a way to convert opendata(J) back to J then we say that J is reconstructible. All method parameters in an MXBean interface must be reconstructible, because when the MXBean framework is invoking a method it will need to convert those parameters from opendata(J) to J. In a proxy generated by JMX.newMXBeanProxy, it is the return values of the methods in the MXBean interface that must be reconstructible.

Null values are allowed for all Java types and Open Types, except primitive Java types where they are not possible. When converting from type J to type opendata(J) or from type opendata(J) to type J, a null value is mapped to a null value.

The following table summarizes the type mapping rules.

Java type J | opentype(J) | opendata(J)
int, boolean, etc (the 8 primitive Java types) | SimpleType.INTEGER, SimpleType.BOOLEAN, etc | Integer, Boolean, etc (the corresponding boxed types)
Integer, ObjectName, etc (the types covered by SimpleType) | the corresponding SimpleType | J, the same type
int[] etc (a one-dimensional array with primitive element type) | ArrayType.getPrimitiveArrayType(int[].class) etc | J, the same type
E[] (an array with non-primitive element type E; this includes int[][], where E is int[]) | ArrayType.getArrayType(opentype(E)) | opendata(E)[]
List<E> Set<E> SortedSet<E> (see below) | same as for E[] | same as for E[]
An enumeration E (declared in Java as enum E {...}) | SimpleType.STRING | String
Map<K,V> SortedMap<K,V> | TabularType (see below) | TabularData (see below)
An MXBean interface | SimpleType.OBJECTNAME (see below) | ObjectName (see below)
Any other type | CompositeType, if possible (see below) | CompositeData

The following sections give further details of these rules.

Mappings for primitive types

The 8 primitive Java types (boolean, byte, short, int, long, float, double, char) are mapped to the corresponding boxed types from java.lang, namely Boolean, Byte, etc. The Open Type is the corresponding SimpleType. Thus, opentype(long) is SimpleType.LONG, and opendata(long) is java.lang.Long.

An array of primitive type such as long[] can be represented directly as an Open Type. Thus, openType(long[]) is ArrayType.getPrimitiveArrayType(long[].class), and opendata(long[]) is long[].

In practice, the difference between a plain int and Integer, etc, does not show up because operations in the JMX API are always on Java objects, not primitives. However, the difference does show up with arrays.

Mappings for collections (List<E> etc)

A List<E> or Set<E>, such as List<String> or Set<ObjectName>, is mapped in the same way as an array of the same element type, such as String[] or ObjectName[].

A SortedSet<E> is also mapped in the same way as an E[], but it is only convertible if E is a class or interface that implements Comparable. Thus, a SortedSet<String> or SortedSet<Integer> is convertible, but a SortedSet<int[]> or SortedSet<List<String>> is not. The conversion of a SortedSet instance will fail with an IllegalArgumentException if it has a non-null comparator().

A List<E> is reconstructed as a java.util.ArrayList<E>; a Set<E> as a java.util.HashSet<E>; a SortedSet<E> as a java.util.TreeSet<E>.

Mappings for maps (Map<K,V> etc)

A Map<K,V> or SortedMap<K,V>, for example Map<String,ObjectName>, has Open Type TabularType and is mapped to a TabularData. The TabularType has two items called key and value. The Open Type of key is opentype(K), and the Open Type of value is opentype(V). The index of the TabularType is the single item key.

For example, the TabularType for a Map<String,ObjectName> might be constructed with code like this:

String typeName =
    "java.util.Map<java.lang.String, javax.management.ObjectName>";
String[] keyValue =
    new String[] {"key", "value"};
OpenType[] openTypes =
    new OpenType[] {SimpleType.STRING, SimpleType.OBJECTNAME};
CompositeType rowType =
    new CompositeType(typeName, typeName, keyValue, keyValue, openTypes);
TabularType tabularType =
    new TabularType(typeName, typeName, rowType, new String[] {"key"});

The typeName here is determined by the type name rules detailed below.

A SortedMap<K,V> is mapped in the same way, but it is only convertible if K is a class or interface that implements Comparable. Thus, a SortedMap<String,int[]> is convertible, but a SortedMap<int[],String> is not. The conversion of a SortedMap instance will fail with an IllegalArgumentException if it has a non-null comparator().

A Map<K,V> is reconstructed as a java.util.HashMap<K,V>; a SortedMap<K,V> as a java.util.TreeMap<K,V>.

TabularData is an interface. The concrete class that is used to represent a Map<K,V> as Open Data is TabularDataSupport, or another class implementing TabularData that serializes as TabularDataSupport.

Mappings for MXBean interfaces

An MXBean interface, or a type referenced within an MXBean interface, can reference another MXBean interface, J. Then opentype(J) is SimpleType.OBJECTNAME and opendata(J) is ObjectName.

For example, suppose you have two MXBean interfaces like this:

public interface ProductMXBean {
    public ModuleMXBean[] getModules();
}

public interface ModuleMXBean {
    public ProductMXBean getProduct();
}

The object implementing the ModuleMXBean interface returns from its getProduct method an object implementing the ProductMXBean interface. The ModuleMXBean object and the returned ProductMXBean objects must both be registered as MXBeans in the same MBean Server.

The method ModuleMXBean.getProduct() defines an attribute called Product. The Open Type for this attribute is SimpleType.OBJECTNAME, and the corresponding ObjectName value will be the name under which the referenced ProductMXBean is registered in the MBean Server.

If you make an MXBean proxy for a ModuleMXBean and call its getProduct() method, the proxy will map the ObjectName back into a ProductMXBean by making another MXBean proxy. More formally, when a proxy made with JMX.newMXBeanProxy(mbeanServerConnection, objectNameX, interfaceX) needs to map objectNameY back into interfaceY, another MXBean interface, it does so with JMX.newMXBeanProxy(mbeanServerConnection, objectNameY, interfaceY). The implementation may return a proxy that was previously created by a call to JMX.newMXBeanProxy with the same parameters, or it may create a new proxy.

The reverse mapping is illustrated by the following change to the ModuleMXBean interface:

public interface ModuleMXBean {
    public ProductMXBean getProduct();
    public void setProduct(ProductMXBean c);
}

The presence of the setProduct method now means that the Product attribute is read/write. As before, the value of this attribute is an ObjectName. When the attribute is set, the ObjectName must be converted into the ProductMXBean object that the setProduct method expects. This object will be an MXBean proxy for the given ObjectName in the same MBean Server.

If you make an MXBean proxy for a ModuleMXBean and call its setProduct method, the proxy will map its ProductMXBean argument back into an ObjectName. This will only work if the argument is in fact another proxy, for a ProductMXBean in the same MBeanServerConnection. The proxy can have been returned from another proxy (like ModuleMXBean.getProduct() which returns a proxy for a ProductMXBean); or it can have been created by JMX.newMXBeanProxy; or it can have been created using Proxy with an invocation handler that is MBeanServerInvocationHandler or a subclass.

If the same MXBean were registered under two different ObjectNames, a reference to that MXBean from another MXBean would be ambiguous. Therefore, if an MXBean object is already registered in an MBean Server and an attempt is made to register it in the same MBean Server under another name, the result is an InstanceAlreadyExistsException. Registering the same MBean object under more than one name is discouraged in general, notably because it does not work well for MBeans that are NotificationBroadcasters.

Mappings for other types

Given a Java class or interface J that does not match the other rules in the table above, the MXBean framework will attempt to map it to a CompositeType as follows. The type name of this CompositeType is determined by the type name rules below.

The class is examined for getters using the conventions above. (Getters must be public instance methods.) If there are no getters, or if any getter has a type that is not convertible, then J is not convertible.

If there is at least one getter and every getter has a convertible type, then opentype(J) is a CompositeType with one item for every getter. If the getter is

T getName()
then the item in the CompositeType is called name and has type opentype(T). For example, if the item is
String getOwner()
then the item is called owner and has Open Type SimpleType.STRING. If the getter is
boolean isName()
then the item in the CompositeType is called name and has type SimpleType.BOOLEAN.

Notice that the first character (or code point) is converted to lower case. This follows the Java Beans convention, which for historical reasons is different from the Standard MBean convention. In a Standard MBean or MXBean interface, a method getOwner defines an attribute called Owner, while in a Java Bean or mapped CompositeType, a method getOwner defines a property or item called owner.

If two methods produce the same item name (for example, getOwner and isOwner, or getOwner and getowner) then the type is not convertible.

When the Open Type is CompositeType, the corresponding mapped Java type (opendata(J)) is CompositeData. The mapping from an instance of J to a CompositeData corresponding to the CompositeType just described is done as follows. First, if J implements the interface CompositeDataView, then that interface's toCompositeData method is called to do the conversion. Otherwise, the CompositeData is constructed by calling the getter for each item and converting it to the corresponding Open Data type. Thus, a getter such as

List<String> getNames()

will have been mapped to an item with name "names" and Open Type ArrayType(1, SimpleType.STRING). The conversion to CompositeData will call getNames() and convert the resultant List<String> into a String[] for the item "names".

CompositeData is an interface. The concrete class that is used to represent a type as Open Data is CompositeDataSupport, or another class implementing CompositeData that serializes as CompositeDataSupport.

Reconstructing an instance of Java type J from a CompositeData

If opendata(J) is CompositeData for a Java type J, then either an instance of J can be reconstructed from a CompositeData, or J is not reconstructible. If any item in the CompositeData is not reconstructible, then J is not reconstructible either.

For any given J, the following rules are consulted to determine how to reconstruct instances of J from CompositeData. The first applicable rule in the list is the one that will be used.

  1. If J has a method
    public static J from(CompositeData cd)
    then that method is called to reconstruct an instance of J.

  2. Otherwise, if J has at least one public constructor with a ConstructorProperties annotation, then one of those constructors (not necessarily always the same one) will be called to reconstruct an instance of J. Every such annotation must list as many strings as the constructor has parameters; each string must name a property corresponding to a getter of J; and the type of this getter must be the same as the corresponding constructor parameter. It is not an error for there to be getters that are not mentioned in the ConstructorProperties annotation (these may correspond to information that is not needed to reconstruct the object).

    An instance of J is reconstructed by calling a constructor with the appropriate reconstructed items from the CompositeData. The constructor to be called will be determined at runtime based on the items actually present in the CompositeData, given that this CompositeData might come from an earlier version of J where not all the items were present. A constructor is applicable if all the properties named in its ConstructorProperties annotation are present as items in the CompositeData. If no constructor is applicable, then the attempt to reconstruct J fails.

    For any possible combination of properties, it must be the case that either (a) there are no applicable constructors, or (b) there is exactly one applicable constructor, or (c) one of the applicable constructors names a proper superset of the properties named by each other applicable constructor. (In other words, there should never be ambiguity over which constructor to choose.) If this condition is not true, then J is not reconstructible.

  3. Otherwise, if J has a public no-arg constructor, and for every getter in J with type T and name N there is a corresponding setter with the same name and type, then an instance of J is constructed with the no-arg constructor and the setters are called with the reconstructed items from the CompositeData to restore the values. For example, if there is a method
    public List<String> getNames()
    then there must also be a method
    public void setNames(List<String> names)
    for this rule to apply.

    If the CompositeData came from an earlier version of J, some items might not be present. In this case, the corresponding setters will not be called.

  4. Otherwise, if J is an interface that has no methods other than getters, an instance of J is constructed using a Proxy with a CompositeDataInvocationHandler backed by the CompositeData being converted.

  5. Otherwise, J is not reconstructible.

Here are examples showing different ways to code a type NamedNumber that consists of an int and a String. In each case, the CompositeType looks like this:

CompositeType(
    "NamedNumber",                      // typeName
    "NamedNumber",                      // description
    new String[] {"number", "name"},    // itemNames
    new String[] {"number", "name"},    // itemDescriptions
    new OpenType[] {SimpleType.INTEGER,
                    SimpleType.STRING}  // itemTypes
);
  1. Static from method:
    public class NamedNumber {
    public int getNumber() {return number;}
    public String getName() {return name;}
    private NamedNumber(int number, String name) {
        this.number = number;
        this.name = name;
    }
    public static NamedNumber from(CompositeData cd) {
        return new NamedNumber((Integer) cd.get("number"),
                               (String) cd.get("name"));
    }
    private final int number;
    private final String name;
}
  2. Public constructor with @ConstructorProperties annotation:
    public class NamedNumber {
    public int getNumber() {return number;}
    public String getName() {return name;}
    @ConstructorProperties({"number", "name"})
    public NamedNumber(int number, String name) {
        this.number = number;
        this.name = name;
    }
    private final int number;
    private final String name;
}
  3. Setter for every getter:
    public class NamedNumber {
    public int getNumber() {return number;}
    public void setNumber(int number) {this.number = number;}
    public String getName() {return name;}
    public void setName(String name) {this.name = name;}
    public NamedNumber() {}
    private int number;
    private String name;
}
  4. Interface with only getters:
    public interface NamedNumber {
    public int getNumber();
    public String getName();
}

It is usually better for classes that simply represent a collection of data to be immutable. An instance of an immutable class cannot be changed after it has been constructed. Notice that CompositeData itself is immutable. Immutability has many advantages, notably with regard to thread-safety and security. So the approach using setters should generally be avoided if possible.

Recursive types

Recursive (self-referential) types cannot be used in MXBean interfaces. This is a consequence of the immutability of CompositeType. For example, the following type could not be the type of an attribute, because it refers to itself:

public interface Node {
    public String getName();
    public int getPriority();
    public Node getNext();
}

It is always possible to rewrite recursive types like this so they are no longer recursive. Doing so may require introducing new types. For example:

public interface NodeList {
    public List<Node> getNodes();
}

public interface Node {
    public String getName();
    public int getPriority();
}

MBeanInfo contents for an MXBean

An MXBean is a type of Open MBean. However, for compatibility reasons, its MBeanInfo is not an OpenMBeanInfo. In particular, when the type of an attribute, parameter, or operation return value is a primitive type such as int, or is void (for a return type), then the attribute, parameter, or operation will be represented respectively by an MBeanAttributeInfo, MBeanParameterInfo, or MBeanOperationInfo whose getType() or getReturnType() returns the primitive name ("int" etc). This is so even though the mapping rules above specify that the opendata mapping is the wrapped type (Integer etc).

The array of public constructors returned by MBeanInfo.getConstructors() for an MXBean that is directly registered in the MBean Server will contain all of the public constructors of that MXBean. If the class of the MXBean is not public then its constructors are not considered public either. The list returned for an MXBean that is constructed using the StandardMBean class is derived in the same way as for Standard MBeans. Regardless of how the MXBean was constructed, its constructor parameters are not subject to MXBean mapping rules and do not have a corresponding OpenType.

The array of notification types returned by MBeanInfo.getNotifications() for an MXBean that is directly registered in the MBean Server will be empty if the MXBean does not implement the NotificationBroadcaster interface. Otherwise, it will be the result of calling NotificationBroadcaster.getNotificationInfo() at the time the MXBean was registered. Even if the result of this method changes subsequently, the result of MBeanInfo.getNotifications() will not. The list returned for an MXBean that is constructed using the StandardMBean or StandardEmitterMBean class is derived in the same way as for Standard MBeans.

The Descriptor for all of the MBeanAttributeInfo, MBeanParameterInfo, and MBeanOperationInfo objects contained in the MBeanInfo will have a field openType whose value is the OpenType specified by the mapping rules above. So even when getType() is "int", getDescriptor().getField("openType") will be SimpleType.INTEGER.

The Descriptor for each of these objects will also have a field originalType that is a string representing the Java type that appeared in the MXBean interface. The format of this string is described in the section Type Names below.

The Descriptor for the MBeanInfo will have a field mxbean whose value is the string "true".

Type Names

Sometimes the unmapped type T of a method parameter or return value in an MXBean must be represented as a string. If T is a non-generic type, this string is the value returned by Class.getName(). Otherwise it is the value of genericstring(T), defined as follows:

  • If T is a non-generic non-array type, genericstring(T) is the value returned by Class.getName(), for example "int" or "java.lang.String".
  • If T is an array E[], genericstring(T) is genericstring(E) followed by "[]". For example, genericstring(int[]) is "int[]", and genericstring(List<String>[][]) is "java.util.List<java.lang.String>[][]".
  • Otherwise, T is a parameterized type such as List<String> and genericstring(T) consists of the following: the fully-qualified name of the parameterized type as returned by Class.getName(); a left angle bracket ("<"); genericstring(A) where A is the first type parameter; if there is a second type parameter B then ", " (a comma and a single space) followed by genericstring(B); a right angle bracket (">").

Note that if a method returns int[], this will be represented by the string "[I" returned by Class.getName(), but if a method returns List<int[]>, this will be represented by the string "java.util.List<int[]>".

Exceptions

A problem with mapping from Java types to Open types is signaled with an OpenDataException. This can happen when an MXBean interface is being analyzed, for example if it references a type like java.util.Random that has no getters. Or it can happen when an instance is being converted (a return value from a method in an MXBean or a parameter to a method in an MXBean proxy), for example when converting from SortedSet<String> to String[] if the SortedSet has a non-null Comparator.

A problem with mapping to Java types from Open types is signaled with an InvalidObjectException. This can happen when an MXBean interface is being analyzed, for example if it references a type that is not reconstructible according to the rules above, in a context where a reconstructible type is required. Or it can happen when an instance is being converted (a parameter to a method in an MXBean or a return value from a method in an MXBean proxy), for example from a String to an Enum if there is no Enum constant with that name.

Depending on the context, the OpenDataException or InvalidObjectException may be wrapped in another exception such as RuntimeMBeanException or UndeclaredThrowableException. For every thrown exception, the condition C will be true: "e is OpenDataException or InvalidObjectException (as appropriate), or C is true of e.getCause()".

Since:
1.6

Optional Element Summary
 boolean value
True if the annotated interface is an MXBean interface.

value

public abstract boolean value
True if the annotated interface is an MXBean interface.

Returns:
true if the annotated interface is an MXBean interface.
Default:
true
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


NotCompliantMBeanException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class NotCompliantMBeanException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.OperationsException
                    extended by  javax.management.NotCompliantMBeanException
All Implemented Interfaces:
Serializable
public class NotCompliantMBeanException
extends OperationsException

Exception which occurs when trying to register an object in the MBean server that is not a JMX compliant MBean.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
NotCompliantMBeanException()
Default constructor.
NotCompliantMBeanException(String message)
Constructor that allows a specific error message to be specified.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NotCompliantMBeanException

public NotCompliantMBeanException()
Default constructor.

NotCompliantMBeanException

public NotCompliantMBeanException(String message)
Constructor that allows a specific error message to be specified.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Notification

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class Notification

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.management.Notification
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
AttributeChangeNotification, JMXConnectionNotification, MBeanServerNotification, MonitorNotification, RelationNotification, TimerNotification
public class Notification
extends EventObject

The Notification class represents a notification emitted by an MBean. It contains a reference to the source MBean: if the notification has been forwarded through the MBean server, and the original source of the notification was a reference to the emitting MBean object, then the MBean server replaces it by the MBean's ObjectName. If the listener has registered directly with the MBean, this is either the object name or a direct reference to the MBean.

It is strongly recommended that notification senders use the object name rather than a reference to the MBean object as the source.

The serialVersionUID of this class is -7516092053498031989L.

Since:
1.5
See Also:
Serialized Form

Field Summary
protected  Object source
This field hides the EventObject.source field in the parent class to make it non-transient and therefore part of the serialized form.
Constructor Summary
Notification(String type, Object source, long sequenceNumber)
Creates a Notification object.
Notification(String type, Object source, long sequenceNumber, long timeStamp)
Creates a Notification object.
Notification(String type, Object source, long sequenceNumber, long timeStamp, String message)
Creates a Notification object.
Notification(String type, Object source, long sequenceNumber, String message)
Creates a Notification object.
Method Summary
String | getMessage() Get the notification message.
long | getSequenceNumber() Get the notification sequence number.
long | getTimeStamp() Get the notification timestamp.
String | getType() Get the notification type.
Object | getUserData() Get the user data.
void | setSequenceNumber(long sequenceNumber) Set the notification sequence number.
void | setSource(Object source) Sets the source.
void | setTimeStamp(long timeStamp) Set the notification timestamp.
void | setUserData(Object userData) Set the user data.
String | toString() Returns a String representation of this notification.
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

source

protected Object source

This field hides the EventObject.source field in the parent class to make it non-transient and therefore part of the serialized form.

Constructor Detail

Notification

public Notification(String type,
                    Object source,
                    long sequenceNumber)
Creates a Notification object. The notification timeStamp is set to the current date.

Parameters:
type - The notification type.
source - The notification source.
sequenceNumber - The notification sequence number within the source object.

Notification

public Notification(String type,
                    Object source,
                    long sequenceNumber,
                    String message)
Creates a Notification object. The notification timeStamp is set to the current date.

Parameters:
type - The notification type.
source - The notification source.
sequenceNumber - The notification sequence number within the source object.
message - The detailed message.

Notification

public Notification(String type,
                    Object source,
                    long sequenceNumber,
                    long timeStamp)
Creates a Notification object.

Parameters:
type - The notification type.
source - The notification source.
sequenceNumber - The notification sequence number within the source object.
timeStamp - The notification emission date.

Notification

public Notification(String type,
                    Object source,
                    long sequenceNumber,
                    long timeStamp,
                    String message)
Creates a Notification object.

Parameters:
type - The notification type.
source - The notification source.
sequenceNumber - The notification sequence number within the source object.
timeStamp - The notification emission date.
message - The detailed message.
Method Detail

setSource

public void setSource(Object source)
Sets the source.

Parameters:
source - the new source for this object.
See Also:
EventObject.getSource()

getSequenceNumber

public long getSequenceNumber()
Get the notification sequence number.

Returns:
The notification sequence number within the source object. It's a serial number identifying a particular instance of notification in the context of the notification source. The notification model does not assume that notifications will be received in the same order that they are sent. The sequence number helps listeners to sort received notifications.
See Also:
setSequenceNumber(long)

setSequenceNumber

public void setSequenceNumber(long sequenceNumber)
Set the notification sequence number.

Parameters:
sequenceNumber - The notification sequence number within the source object. It is a serial number identifying a particular instance of notification in the context of the notification source.
See Also:
getSequenceNumber()

getType

public String getType()
Get the notification type.

Returns:
The notification type. It's a string expressed in a dot notation similar to Java properties. An example of a notification type is network.alarm.router .

getTimeStamp

public long getTimeStamp()
Get the notification timestamp.

Returns:
The notification timestamp.
See Also:
setTimeStamp(long)

setTimeStamp

public void setTimeStamp(long timeStamp)
Set the notification timestamp.

Parameters:
timeStamp - The notification timestamp. It indicates when the notification was generated.
See Also:
getTimeStamp()

getMessage

public String getMessage()
Get the notification message.

Returns:
The message string of this notification object. It contains in a string, which could be the explanation of the notification for displaying to a user

getUserData

public Object getUserData()
Get the user data.

Returns:
The user data object. It is used for whatever data the notification source wishes to communicate to its consumers.
See Also:
setUserData(java.lang.Object)

setUserData

public void setUserData(Object userData)
Set the user data.

Parameters:
userData - The user data object. It is used for whatever data the notification source wishes to communicate to its consumers.
See Also:
getUserData()

toString

public String toString()
Returns a String representation of this notification.

Overrides:
toString in class EventObject
Returns:
A String representation of this notification.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotificationBroadcaster

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Interface NotificationBroadcaster

All Known Subinterfaces:
ModelMBean, ModelMBeanNotificationBroadcaster, NotificationEmitter
All Known Implementing Classes:
CounterMonitor, GaugeMonitor, JMXConnectorServer, MBeanServerDelegate, Monitor, NotificationBroadcasterSupport, RelationService, RequiredModelMBean, RMIConnectorServer, StandardEmitterMBean, StringMonitor, Timer
public interface NotificationBroadcaster

Interface implemented by an MBean that emits Notifications. It allows a listener to be registered with the MBean as a notification listener.

Notification dispatch

When an MBean emits a notification, it considers each listener that has been added with addNotificationListener and not subsequently removed with removeNotificationListener. If a filter was provided with that listener, and if the filter's isNotificationEnabled method returns false, the listener is ignored. Otherwise, the listener's handleNotification method is called with the notification, as well as the handback object that was provided to addNotificationListener.

If the same listener is added more than once, it is considered as many times as it was added. It is often useful to add the same listener with different filters or handback objects.

Implementations of this interface can differ regarding the thread in which the methods of filters and listeners are called.

If the method call of a filter or listener throws an Exception, then that exception should not prevent other listeners from being invoked. However, if the method call throws an Error, then it is recommended that processing of the notification stop at that point, and if it is possible to propagate the Error to the sender of the notification, this should be done.

New code should use the NotificationEmitter interface instead.

Implementations of this interface and of NotificationEmitter should be careful about synchronization. In particular, it is not a good idea for an implementation to hold any locks while it is calling a listener. To deal with the possibility that the list of listeners might change while a notification is being dispatched, a good strategy is to use a CopyOnWriteArrayList for this list.

Since:
1.5

Method Summary
void | addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Adds a listener to this MBean.
MBeanNotificationInfo[] | getNotificationInfo() Returns an array indicating, for each notification this MBean may send, the name of the Java class of the notification and the notification type.
void | removeNotificationListener(NotificationListener listener) Removes a listener from this MBean.

Method Detail

addNotificationListener

void addNotificationListener(NotificationListener listener,
                             NotificationFilter filter,
                             Object handback)
                             throws IllegalArgumentException
Adds a listener to this MBean.

Parameters:
listener - The listener object which will handle the notifications emitted by the broadcaster.
filter - The filter object. If filter is null, no filtering will be performed before handling notifications.
handback - An opaque object to be sent back to the listener when a notification is emitted. This object cannot be used by the Notification broadcaster object. It should be resent unchanged with the notification to the listener.
Throws:
IllegalArgumentException - Listener parameter is null.
See Also:
removeNotificationListener(javax.management.NotificationListener)

removeNotificationListener

void removeNotificationListener(NotificationListener listener)
                                throws ListenerNotFoundException
Removes a listener from this MBean. If the listener has been registered with different handback objects or notification filters, all entries corresponding to the listener will be removed.

Parameters:
listener - A listener that was previously added to this MBean.
Throws:
ListenerNotFoundException - The listener is not registered with the MBean.
See Also:
addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object), NotificationEmitter.removeNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

getNotificationInfo

MBeanNotificationInfo[] getNotificationInfo()

Returns an array indicating, for each notification this MBean may send, the name of the Java class of the notification and the notification type.

It is not illegal for the MBean to send notifications not described in this array. However, some clients of the MBean server may depend on the array being complete for their correct functioning.

Returns:
the array of possible notifications.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotificationBroadcasterSupport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class NotificationBroadcasterSupport

java.lang.Object
    extended by  javax.management.NotificationBroadcasterSupport
All Implemented Interfaces:
NotificationBroadcaster, NotificationEmitter
Direct Known Subclasses:
JMXConnectorServer, Monitor, RelationService, Timer
public class NotificationBroadcasterSupport
extends Object
implements NotificationEmitter

Provides an implementation of NotificationEmitter interface. This can be used as the super class of an MBean that sends notifications.

By default, the notification dispatch model is synchronous. That is, when a thread calls sendNotification, the NotificationListener.handleNotification method of each listener is called within that thread. You can override this default by overriding handleNotification in a subclass, or by passing an Executor to the constructor.

If the method call of a filter or listener throws an Exception, then that exception does not prevent other listeners from being invoked. However, if the method call of a filter or of Executor.execute or of handleNotification (when no Excecutor is specified) throws an Error, then that Error is propagated to the caller of sendNotification.

Remote listeners added using the JMX Remote API (see JMXConnector) are not usually called synchronously. That is, when sendNotification returns, it is not guaranteed that any remote listeners have yet received the notification.

Since:
1.5

Constructor Summary
NotificationBroadcasterSupport()
Constructs a NotificationBroadcasterSupport where each listener is invoked by the thread sending the notification.
NotificationBroadcasterSupport(Executor executor)
Constructs a NotificationBroadcasterSupport where each listener is invoked using the given Executor.
NotificationBroadcasterSupport(Executor executor, MBeanNotificationInfo... info)
Constructs a NotificationBroadcasterSupport with information about the notifications that may be sent, and where each listener is invoked using the given Executor.
NotificationBroadcasterSupport(MBeanNotificationInfo... info)
Constructs a NotificationBroadcasterSupport with information about the notifications that may be sent.
Method Summary
void | addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Adds a listener.
MBeanNotificationInfo[] | getNotificationInfo() Returns an array indicating, for each notification this MBean may send, the name of the Java class of the notification and the notification type.
protected void | handleNotification(NotificationListener listener, Notification notif, Object handback) This method is called by sendNotification for each listener in order to send the notification to that listener.
void | removeNotificationListener(NotificationListener listener) Removes a listener from this MBean.
void | removeNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Removes a listener from this MBean.
void | sendNotification(Notification notification) Sends a notification.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NotificationBroadcasterSupport

public NotificationBroadcasterSupport()
Constructs a NotificationBroadcasterSupport where each listener is invoked by the thread sending the notification. This constructor is equivalent to NotificationBroadcasterSupport(null, null).

NotificationBroadcasterSupport

public NotificationBroadcasterSupport(Executor executor)
Constructs a NotificationBroadcasterSupport where each listener is invoked using the given Executor. When sendNotification is called, a listener is selected if it was added with a null NotificationFilter, or if isNotificationEnabled returns true for the notification being sent. The call to NotificationFilter.isNotificationEnabled takes place in the thread that called sendNotification. Then, for each selected listener, executor.execute is called with a command that calls the handleNotification method. This constructor is equivalent to NotificationBroadcasterSupport(executor, null).

Parameters:
executor - an executor used by the method sendNotification to send each notification. If it is null, the thread calling sendNotification will invoke the handleNotification method itself.
Since:
1.6

NotificationBroadcasterSupport

public NotificationBroadcasterSupport(MBeanNotificationInfo... info)

Constructs a NotificationBroadcasterSupport with information about the notifications that may be sent. Each listener is invoked by the thread sending the notification. This constructor is equivalent to NotificationBroadcasterSupport(null, info).

If the info array is not empty, then it is cloned by the constructor as if by info.clone(), and each call to getNotificationInfo() returns a new clone.

Parameters:
info - an array indicating, for each notification this MBean may send, the name of the Java class of the notification and the notification type. Can be null, which is equivalent to an empty array.
Since:
1.6

NotificationBroadcasterSupport

public NotificationBroadcasterSupport(Executor executor,
                                      MBeanNotificationInfo... info)

Constructs a NotificationBroadcasterSupport with information about the notifications that may be sent, and where each listener is invoked using the given Executor.

When sendNotification is called, a listener is selected if it was added with a null NotificationFilter, or if isNotificationEnabled returns true for the notification being sent. The call to NotificationFilter.isNotificationEnabled takes place in the thread that called sendNotification. Then, for each selected listener, executor.execute is called with a command that calls the handleNotification method.

If the info array is not empty, then it is cloned by the constructor as if by info.clone(), and each call to getNotificationInfo() returns a new clone.

Parameters:
executor - an executor used by the method sendNotification to send each notification. If it is null, the thread calling sendNotification will invoke the handleNotification method itself.
info - an array indicating, for each notification this MBean may send, the name of the Java class of the notification and the notification type. Can be null, which is equivalent to an empty array.
Since:
1.6
Method Detail

addNotificationListener

public void addNotificationListener(NotificationListener listener,
                                    NotificationFilter filter,
                                    Object handback)
Adds a listener.

Specified by:
addNotificationListener in interface NotificationBroadcaster
Parameters:
listener - The listener to receive notifications.
filter - The filter object. If filter is null, no filtering will be performed before handling notifications.
handback - An opaque object to be sent back to the listener when a notification is emitted. This object cannot be used by the Notification broadcaster object. It should be resent unchanged with the notification to the listener.
Throws:
IllegalArgumentException - thrown if the listener is null.
See Also:
removeNotificationListener(javax.management.NotificationListener)

removeNotificationListener

public void removeNotificationListener(NotificationListener listener)
                                throws ListenerNotFoundException
Description copied from interface: NotificationBroadcaster
Removes a listener from this MBean. If the listener has been registered with different handback objects or notification filters, all entries corresponding to the listener will be removed.

Specified by:
removeNotificationListener in interface NotificationBroadcaster
Parameters:
listener - A listener that was previously added to this MBean.
Throws:
ListenerNotFoundException - The listener is not registered with the MBean.
See Also:
NotificationBroadcaster.addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object), NotificationEmitter.removeNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

removeNotificationListener

public void removeNotificationListener(NotificationListener listener,
                                       NotificationFilter filter,
                                       Object handback)
                                throws ListenerNotFoundException
Description copied from interface: NotificationEmitter

Removes a listener from this MBean. The MBean must have a listener that exactly matches the given listener, filter, and handback parameters. If there is more than one such listener, only one is removed.

The filter and handback parameters may be null if and only if they are null in a listener to be removed.

Specified by:
removeNotificationListener in interface NotificationEmitter
Parameters:
listener - A listener that was previously added to this MBean.
filter - The filter that was specified when the listener was added.
handback - The handback that was specified when the listener was added.
Throws:
ListenerNotFoundException - The listener is not registered with the MBean, or it is not registered with the given filter and handback.

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()
Description copied from interface: NotificationBroadcaster

Returns an array indicating, for each notification this MBean may send, the name of the Java class of the notification and the notification type.

It is not illegal for the MBean to send notifications not described in this array. However, some clients of the MBean server may depend on the array being complete for their correct functioning.

Specified by:
getNotificationInfo in interface NotificationBroadcaster
Returns:
the array of possible notifications.

sendNotification

public void sendNotification(Notification notification)
Sends a notification. If an Executor was specified in the constructor, it will be given one task per selected listener to deliver the notification to that listener.

Parameters:
notification - The notification to send.

handleNotification

protected void handleNotification(NotificationListener listener,
                                  Notification notif,
                                  Object handback)

This method is called by sendNotification for each listener in order to send the notification to that listener. It can be overridden in subclasses to change the behavior of notification delivery, for instance to deliver the notification in a separate thread.

The default implementation of this method is equivalent to

 listener.handleNotification(notif, handback);

Parameters:
listener - the listener to which the notification is being delivered.
notif - the notification being delivered to the listener.
handback - the handback object that was supplied when the listener was added.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotificationEmitter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Interface NotificationEmitter

All Superinterfaces:
NotificationBroadcaster
All Known Implementing Classes:
CounterMonitor, GaugeMonitor, JMXConnectorServer, MBeanServerDelegate, Monitor, NotificationBroadcasterSupport, RelationService, RequiredModelMBean, RMIConnectorServer, StandardEmitterMBean, StringMonitor, Timer
public interface NotificationEmitter
extends NotificationBroadcaster

Interface implemented by an MBean that emits Notifications. It allows a listener to be registered with the MBean as a notification listener.

Notification dispatch

When an MBean emits a notification, it considers each listener that has been added with addNotificationListener and not subsequently removed with removeNotificationListener. If a filter was provided with that listener, and if the filter's isNotificationEnabled method returns false, the listener is ignored. Otherwise, the listener's handleNotification method is called with the notification, as well as the handback object that was provided to addNotificationListener.

If the same listener is added more than once, it is considered as many times as it was added. It is often useful to add the same listener with different filters or handback objects.

Implementations of this interface can differ regarding the thread in which the methods of filters and listeners are called.

If the method call of a filter or listener throws an Exception, then that exception should not prevent other listeners from being invoked. However, if the method call throws an Error, then it is recommended that processing of the notification stop at that point, and if it is possible to propagate the Error to the sender of the notification, this should be done.

This interface should be used by new code in preference to the NotificationBroadcaster interface.

Implementations of this interface and of NotificationBroadcaster should be careful about synchronization. In particular, it is not a good idea for an implementation to hold any locks while it is calling a listener. To deal with the possibility that the list of listeners might change while a notification is being dispatched, a good strategy is to use a CopyOnWriteArrayList for this list.

Since:
1.5

Method Summary
 void removeNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback)
Removes a listener from this MBean.
Methods inherited from interface javax.management.NotificationBroadcaster
addNotificationListener, getNotificationInfo, removeNotificationListener

Method Detail

removeNotificationListener

void removeNotificationListener(NotificationListener listener,
                                NotificationFilter filter,
                                Object handback)
                                throws ListenerNotFoundException

Removes a listener from this MBean. The MBean must have a listener that exactly matches the given listener, filter, and handback parameters. If there is more than one such listener, only one is removed.

The filter and handback parameters may be null if and only if they are null in a listener to be removed.

Parameters:
listener - A listener that was previously added to this MBean.
filter - The filter that was specified when the listener was added.
handback - The handback that was specified when the listener was added.
Throws:
ListenerNotFoundException - The listener is not registered with the MBean, or it is not registered with the given filter and handback.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotificationFilter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Interface NotificationFilter

All Superinterfaces:
Serializable
All Known Implementing Classes:
AttributeChangeNotificationFilter, MBeanServerNotificationFilter, NotificationFilterSupport
public interface NotificationFilter
extends Serializable

To be implemented by a any class acting as a notification filter. It allows a registered notification listener to filter the notifications of interest.

Since:
1.5

Method Summary
 boolean isNotificationEnabled(Notification notification)
Invoked before sending the specified notification to the listener.

Method Detail

isNotificationEnabled

boolean isNotificationEnabled(Notification notification)
Invoked before sending the specified notification to the listener.

Parameters:
notification - The notification to be sent.
Returns:
true if the notification has to be sent to the listener, false otherwise.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotificationFilterSupport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class NotificationFilterSupport

java.lang.Object
    extended by  javax.management.NotificationFilterSupport
All Implemented Interfaces:
Serializable, NotificationFilter
Direct Known Subclasses:
MBeanServerNotificationFilter
public class NotificationFilterSupport
extends Object
implements NotificationFilter

Provides an implementation of the NotificationFilter interface. The filtering is performed on the notification type attribute.

Manages a list of enabled notification types. A method allows users to enable/disable as many notification types as required.

Then, before sending a notification to a listener registered with a filter, the notification broadcaster compares this notification type with all notification types enabled by the filter. The notification will be sent to the listener only if its filter enables this notification type.

Example:

 NotificationFilterSupport myFilter = new NotificationFilterSupport();
 myFilter.enableType("my_example.my_type");
 myBroadcaster.addListener(myListener, myFilter, null);
The listener myListener will only receive notifications the type of which equals/starts with "my_example.my_type".

Since:
1.5
See Also:
NotificationBroadcaster.addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object), Serialized Form

Constructor Summary
NotificationFilterSupport()
Method Summary
void | disableAllTypes() Disables all notification types.
void | disableType(String prefix) Removes the given prefix from the prefix list.
void | enableType(String prefix) Enables all the notifications the type of which starts with the specified prefix to be sent to the listener.
Vector<String> | getEnabledTypes() Gets all the enabled notification types for this filter.
boolean | isNotificationEnabled(Notification notification) Invoked before sending the specified notification to the listener.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NotificationFilterSupport

public NotificationFilterSupport()
Method Detail

isNotificationEnabled

public boolean isNotificationEnabled(Notification notification)
Invoked before sending the specified notification to the listener.
This filter compares the type of the specified notification with each enabled type. If the notification type matches one of the enabled types, the notification should be sent to the listener and this method returns true.

Specified by:
isNotificationEnabled in interface NotificationFilter
Parameters:
notification - The notification to be sent.
Returns:
true if the notification should be sent to the listener, false otherwise.

enableType

public void enableType(String prefix)
                throws IllegalArgumentException
Enables all the notifications the type of which starts with the specified prefix to be sent to the listener.
If the specified prefix is already in the list of enabled notification types, this method has no effect.

Example:

 // Enables all notifications the type of which starts with "my_example" to be sent.
 myFilter.enableType("my_example");
 // Enables all notifications the type of which is "my_example.my_type" to be sent.
 myFilter.enableType("my_example.my_type");
Note that:
myFilter.enableType("my_example.*");
will no match any notification type.

Parameters:
prefix - The prefix.
Throws:
IllegalArgumentException - The prefix parameter is null.

disableType

public void disableType(String prefix)
Removes the given prefix from the prefix list.
If the specified prefix is not in the list of enabled notification types, this method has no effect.

Parameters:
prefix - The prefix.

disableAllTypes

public void disableAllTypes()
Disables all notification types.

getEnabledTypes

public Vector<String> getEnabledTypes()
Gets all the enabled notification types for this filter.

Returns:
The list containing all the enabled notification types.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotificationListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Interface NotificationListener

All Superinterfaces:
EventListener
All Known Implementing Classes:
RelationService
public interface NotificationListener
extends EventListener

Should be implemented by an object that wants to receive notifications.

Since:
1.5

Method Summary
 void handleNotification(Notification notification, Object handback)
Invoked when a JMX notification occurs.

Method Detail

handleNotification

void handleNotification(Notification notification,
                        Object handback)
Invoked when a JMX notification occurs. The implementation of this method should return as soon as possible, to avoid blocking its notification broadcaster.

Parameters:
notification - The notification.
handback - An opaque object which helps the listener to associate information regarding the MBean emitter. This object is passed to the MBean during the addListener call and resent, without modification, to the listener. The MBean object should not use or modify the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectInstance

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class ObjectInstance

java.lang.Object
    extended by  javax.management.ObjectInstance
All Implemented Interfaces:
Serializable
public class ObjectInstance
extends Object
implements Serializable

Used to represent the object name of an MBean and its class name. If the MBean is a Dynamic MBean the class name should be retrieved from the MBeanInfo it provides.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
ObjectInstance(ObjectName objectName, String className)
Allows an object instance to be created given an object name and the full class name, including the package name.
ObjectInstance(String objectName, String className)
Allows an object instance to be created given a string representation of an object name and the full class name, including the package name.
Method Summary
boolean | equals(Object object) Compares the current object instance with another object instance.
String | getClassName() Returns the class part.
ObjectName | getObjectName() Returns the object name part.
int | hashCode() Returns a hash code value for the object.
String | toString() Returns a string representing this ObjectInstance object.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ObjectInstance

public ObjectInstance(String objectName,
                      String className)
               throws MalformedObjectNameException
Allows an object instance to be created given a string representation of an object name and the full class name, including the package name.

Parameters:
objectName - A string representation of the object name.
className - The full class name, including the package name, of the object instance. If the MBean is a Dynamic MBean the class name corresponds to its getMBeanInfo() .getClassName().
Throws:
MalformedObjectNameException - The string passed as a parameter does not have the right format.

ObjectInstance

public ObjectInstance(ObjectName objectName,
                      String className)
Allows an object instance to be created given an object name and the full class name, including the package name.

Parameters:
objectName - The object name.
className - The full class name, including the package name, of the object instance. If the MBean is a Dynamic MBean the class name corresponds to its getMBeanInfo() .getClassName(). If the MBean is a Dynamic MBean the class name should be retrieved from the MBeanInfo it provides.
Method Detail

equals

public boolean equals(Object object)
Compares the current object instance with another object instance.

Overrides:
equals in class Object
Parameters:
object - The object instance that the current object instance is to be compared with.
Returns:
True if the two object instances are equal, otherwise false.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Description copied from class: Object
Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the Object.equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

getObjectName

public ObjectName getObjectName()
Returns the object name part.

Returns:
the object name.

getClassName

public String getClassName()
Returns the class part.

Returns:
the class name.

toString

public String toString()
Returns a string representing this ObjectInstance object. The format of this string is not specified, but users can expect that two ObjectInstances return the same string if and only if they are equal.

Overrides:
toString in class Object
Returns:
a string representation of the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectName

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class ObjectName

java.lang.Object
    extended by  javax.management.ObjectName
All Implemented Interfaces:
Serializable, Comparable<ObjectName>, QueryExp
public class ObjectName
extends Object
implements Comparable<ObjectName>, QueryExp

Represents the object name of an MBean, or a pattern that can match the names of several MBeans. Instances of this class are immutable.

An instance of this class can be used to represent:

  • An object name
  • An object name pattern, within the context of a query

An object name consists of two parts, the domain and the key properties.

The domain is a string of characters not including the character colon (:). It is recommended that the domain should not contain the string "//", which is reserved for future use.

If the domain includes at least one occurrence of the wildcard characters asterisk (*) or question mark (?), then the object name is a pattern. The asterisk matches any sequence of zero or more characters, while the question mark matches any single character.

If the domain is empty, it will be replaced in certain contexts by the default domain of the MBean server in which the ObjectName is used.

The key properties are an unordered set of keys and associated values.

Each key is a nonempty string of characters which may not contain any of the characters comma (,), equals (=), colon, asterisk, or question mark. The same key may not occur twice in a given ObjectName.

Each value associated with a key is a string of characters that is either unquoted or quoted.

An unquoted value is a possibly empty string of characters which may not contain any of the characters comma, equals, colon, or quote.

If the unquoted value contains at least one occurrence of the wildcard characters asterisk or question mark, then the object name is a property value pattern. The asterisk matches any sequence of zero or more characters, while the question mark matches any single character.

A quoted value consists of a quote ("), followed by a possibly empty string of characters, followed by another quote. Within the string of characters, the backslash (\) has a special meaning. It must be followed by one of the following characters:

  • Another backslash. The second backslash has no special meaning and the two characters represent a single backslash.
  • The character 'n'. The two characters represent a newline ('\n' in Java).
  • A quote. The two characters represent a quote, and that quote is not considered to terminate the quoted value. An ending closing quote must be present for the quoted value to be valid.
  • A question mark (?) or asterisk (*). The two characters represent a question mark or asterisk respectively.

A quote may not appear inside a quoted value except immediately after an odd number of consecutive backslashes.

The quotes surrounding a quoted value, and any backslashes within that value, are considered to be part of the value.

If the quoted value contains at least one occurrence of the characters asterisk or question mark and they are not preceded by a backslash, then they are considered as wildcard characters and the object name is a property value pattern. The asterisk matches any sequence of zero or more characters, while the question mark matches any single character.

An ObjectName may be a property list pattern. In this case it may have zero or more keys and associated values. It matches a nonpattern ObjectName whose domain matches and that contains the same keys and associated values, as well as possibly other keys and values.

An ObjectName is a property value pattern when at least one of its quoted or unquoted key property values contains the wildcard characters asterisk or question mark as described above. In this case it has one or more keys and associated values, with at least one of the values containing wildcard characters. It matches a nonpattern ObjectName whose domain matches and that contains the same keys whose values match; if the property value pattern is also a property list pattern then the nonpattern ObjectName can contain other keys and values.

An ObjectName is a property pattern if it is either a property list pattern or a property value pattern or both.

An ObjectName is a pattern if its domain contains a wildcard or if the ObjectName is a property pattern.

If an ObjectName is not a pattern, it must contain at least one key with its associated value.

Examples of ObjectName patterns are:

  • *:type=Foo,name=Bar to match names in any domain whose exact set of keys is type=Foo,name=Bar.
  • d:type=Foo,name=Bar,* to match names in the domain d that have the keys type=Foo,name=Bar plus zero or more other keys.
  • *:type=Foo,name=Bar,* to match names in any domain that has the keys type=Foo,name=Bar plus zero or more other keys.
  • d:type=F?o,name=Bar will match e.g. d:type=Foo,name=Bar and d:type=Fro,name=Bar.
  • d:type=F*o,name=Bar will match e.g. d:type=Fo,name=Bar and d:type=Frodo,name=Bar.
  • d:type=Foo,name="B*" will match e.g. d:type=Foo,name="Bling". Wildcards are recognized even inside quotes, and like other special characters can be escaped with \.

An ObjectName can be written as a String with the following elements in order:

  • The domain.
  • A colon (:).
  • A key property list as defined below.

A key property list written as a String is a comma-separated list of elements. Each element is either an asterisk or a key property. A key property consists of a key, an equals (=), and the associated value.

At most one element of a key property list may be an asterisk. If the key property list contains an asterisk element, the ObjectName is a property list pattern.

Spaces have no special significance in a String representing an ObjectName. For example, the String:

 domain: key1 = value1 , key2 = value2
represents an ObjectName with two keys. The name of each key contains six characters, of which the first and last are spaces. The value associated with the key " key1 " also begins and ends with a space.

In addition to the restrictions on characters spelt out above, no part of an ObjectName may contain a newline character ('\n'), whether the domain, a key, or a value, whether quoted or unquoted. The newline character can be represented in a quoted value with the sequence \n.

The rules on special characters and quoting apply regardless of which constructor is used to make an ObjectName.

To avoid collisions between MBeans supplied by different vendors, a useful convention is to begin the domain name with the reverse DNS name of the organization that specifies the MBeans, followed by a period and a string whose interpretation is determined by that organization. For example, MBeans specified by Sun Microsystems Inc., DNS name sun.com, would have domains such as com.sun.MyDomain. This is essentially the same convention as for Java-language package names.

The serialVersionUID of this class is 1081892073854801359L.

Since:
1.5
See Also:
Serialized Form

Field Summary
static ObjectName WILDCARD
Defines the wildcard "*:*" ObjectName.
Constructor Summary
ObjectName(String name)
Construct an object name from the given string.
ObjectName(String domain, Hashtable<String,String> table)
Construct an object name with several key properties from a Hashtable.
ObjectName(String domain, String key, String value)
Construct an object name with exactly one key property.
Method Summary
 boolean apply(ObjectName name)
Test whether this ObjectName, which may be a pattern, matches another ObjectName.
 int compareTo(ObjectName name)
Compares two ObjectName instances.
 boolean equals(Object object)
Compares the current object name with another object name.
 String getCanonicalKeyPropertyListString()
Returns a string representation of the list of key properties, in which the key properties are sorted in lexical order.
 String getCanonicalName()
Returns the canonical form of the name; that is, a string representation where the properties are sorted in lexical order.
 String getDomain()
Returns the domain part.
static ObjectName getInstance(ObjectName name)
Return an instance of ObjectName that can be used anywhere the given object can be used.
static ObjectName getInstance(String name)
Return an instance of ObjectName that can be used anywhere an object obtained with new ObjectName(name) can be used.
static ObjectName getInstance(String domain, Hashtable<String,String> table)
Return an instance of ObjectName that can be used anywhere an object obtained with new ObjectName(domain, table) can be used.
static ObjectName getInstance(String domain, String key, String value)
Return an instance of ObjectName that can be used anywhere an object obtained with new ObjectName(domain, key, value) can be used.
 String getKeyProperty(String property)
Obtains the value associated with a key in a key property.
 Hashtable<String,String> getKeyPropertyList()
Returns the key properties as a Hashtable.
 String getKeyPropertyListString()
Returns a string representation of the list of key properties specified at creation time.
 int hashCode()
Returns a hash code for this object name.
 boolean isDomainPattern()
Checks whether the object name is a pattern on the domain part.
 boolean isPattern()
Checks whether the object name is a pattern.
 boolean isPropertyListPattern()
Checks whether the object name is a pattern on the key property list.
 boolean isPropertyPattern()
Checks whether the object name is a pattern on the key properties.
 boolean isPropertyValuePattern()
Checks whether the object name is a pattern on the value part of at least one of the key properties.
 boolean isPropertyValuePattern(String property)
Checks whether the value associated with a key in a key property is a pattern.
static String quote(String s)
Returns a quoted form of the given String, suitable for inclusion in an ObjectName.
 void setMBeanServer(MBeanServer mbs)
Sets the MBean server on which the query is to be performed.
 String toString()
Returns a string representation of the object name.
static String unquote(String q)
Returns an unquoted form of the given String.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

WILDCARD

public static final ObjectName WILDCARD
Defines the wildcard "*:*" ObjectName.

Since:
1.6
Constructor Detail

ObjectName

public ObjectName(String name)
           throws MalformedObjectNameException,
                  NullPointerException
Construct an object name from the given string.

Parameters:
name - A string representation of the object name.
Throws:
MalformedObjectNameException - The string passed as a parameter does not have the right format.
NullPointerException - The name parameter is null.

ObjectName

public ObjectName(String domain,
                  String key,
                  String value)
           throws MalformedObjectNameException,
                  NullPointerException
Construct an object name with exactly one key property.

Parameters:
domain - The domain part of the object name.
key - The attribute in the key property of the object name.
value - The value in the key property of the object name.
Throws:
MalformedObjectNameException - The domain, key, or value contains an illegal character, or value does not follow the rules for quoting.
NullPointerException - One of the parameters is null.

ObjectName

public ObjectName(String domain,
                  Hashtable<String,String> table)
           throws MalformedObjectNameException,
                  NullPointerException
Construct an object name with several key properties from a Hashtable.

Parameters:
domain - The domain part of the object name.
table - A hash table containing one or more key properties. The key of each entry in the table is the key of a key property in the object name. The associated value in the table is the associated value in the object name.
Throws:
MalformedObjectNameException - The domain contains an illegal character, or one of the keys or values in table contains an illegal character, or one of the values in table does not follow the rules for quoting.
NullPointerException - One of the parameters is null.
Method Detail

getInstance

public static ObjectName getInstance(String name)
                              throws MalformedObjectNameException,
                                     NullPointerException

Return an instance of ObjectName that can be used anywhere an object obtained with new ObjectName(name) can be used. The returned object may be of a subclass of ObjectName. Calling this method twice with the same parameters may return the same object or two equal but not identical objects.

Parameters:
name - A string representation of the object name.
Returns:
an ObjectName corresponding to the given String.
Throws:
MalformedObjectNameException - The string passed as a parameter does not have the right format.
NullPointerException - The name parameter is null.

getInstance

public static ObjectName getInstance(String domain,
                                     String key,
                                     String value)
                              throws MalformedObjectNameException,
                                     NullPointerException

Return an instance of ObjectName that can be used anywhere an object obtained with new ObjectName(domain, key, value) can be used. The returned object may be of a subclass of ObjectName. Calling this method twice with the same parameters may return the same object or two equal but not identical objects.

Parameters:
domain - The domain part of the object name.
key - The attribute in the key property of the object name.
value - The value in the key property of the object name.
Returns:
an ObjectName corresponding to the given domain, key, and value.
Throws:
MalformedObjectNameException - The domain, key, or value contains an illegal character, or value does not follow the rules for quoting.
NullPointerException - One of the parameters is null.

getInstance

public static ObjectName getInstance(String domain,
                                     Hashtable<String,String> table)
                              throws MalformedObjectNameException,
                                     NullPointerException

Return an instance of ObjectName that can be used anywhere an object obtained with new ObjectName(domain, table) can be used. The returned object may be of a subclass of ObjectName. Calling this method twice with the same parameters may return the same object or two equal but not identical objects.

Parameters:
domain - The domain part of the object name.
table - A hash table containing one or more key properties. The key of each entry in the table is the key of a key property in the object name. The associated value in the table is the associated value in the object name.
Returns:
an ObjectName corresponding to the given domain and key mappings.
Throws:
MalformedObjectNameException - The domain contains an illegal character, or one of the keys or values in table contains an illegal character, or one of the values in table does not follow the rules for quoting.
NullPointerException - One of the parameters is null.

getInstance

public static ObjectName getInstance(ObjectName name)
                              throws NullPointerException

Return an instance of ObjectName that can be used anywhere the given object can be used. The returned object may be of a subclass of ObjectName. If name is of a subclass of ObjectName, it is not guaranteed that the returned object will be of the same class.

The returned value may or may not be identical to name. Calling this method twice with the same parameters may return the same object or two equal but not identical objects.

Since ObjectName is immutable, it is not usually useful to make a copy of an ObjectName. The principal use of this method is to guard against a malicious caller who might pass an instance of a subclass with surprising behavior to sensitive code. Such code can call this method to obtain an ObjectName that is known not to have surprising behavior.

Parameters:
name - an instance of the ObjectName class or of a subclass
Returns:
an instance of ObjectName or a subclass that is known to have the same semantics. If name respects the semantics of ObjectName, then the returned object is equal (though not necessarily identical) to name.
Throws:
NullPointerException - The name is null.

isPattern

public boolean isPattern()
Checks whether the object name is a pattern.

An object name is a pattern if its domain contains a wildcard or if the object name is a property pattern.

Returns:
True if the name is a pattern, otherwise false.

isDomainPattern

public boolean isDomainPattern()
Checks whether the object name is a pattern on the domain part.

Returns:
True if the name is a domain pattern, otherwise false.

isPropertyPattern

public boolean isPropertyPattern()
Checks whether the object name is a pattern on the key properties.

An object name is a pattern on the key properties if it is a pattern on the key property list (e.g. "d:k=v,*") or on the property values (e.g. "d:k=*") or on both (e.g. "d:k=*,*").

Returns:
True if the name is a property pattern, otherwise false.

isPropertyListPattern

public boolean isPropertyListPattern()
Checks whether the object name is a pattern on the key property list.

For example, "d:k=v,*" and "d:k=*,*" are key property list patterns whereas "d:k=*" is not.

Returns:
True if the name is a property list pattern, otherwise false.
Since:
1.6

isPropertyValuePattern

public boolean isPropertyValuePattern()
Checks whether the object name is a pattern on the value part of at least one of the key properties.

For example, "d:k=*" and "d:k=*,*" are property value patterns whereas "d:k=v,*" is not.

Returns:
True if the name is a property value pattern, otherwise false.
Since:
1.6

isPropertyValuePattern

public boolean isPropertyValuePattern(String property)
                               throws NullPointerException,
                                      IllegalArgumentException
Checks whether the value associated with a key in a key property is a pattern.

Parameters:
property - The property whose value is to be checked.
Returns:
True if the value associated with the given key property is a pattern, otherwise false.
Throws:
NullPointerException - If property is null.
IllegalArgumentException - If property is not a valid key property for this ObjectName.
Since:
1.6

getCanonicalName

public String getCanonicalName()

Returns the canonical form of the name; that is, a string representation where the properties are sorted in lexical order.

More precisely, the canonical form of the name is a String consisting of the domain part, a colon (:), the canonical key property list, and a pattern indication.

The canonical key property list is the same string as described for getCanonicalKeyPropertyListString().

The pattern indication is:

  • empty for an ObjectName that is not a property list pattern;
  • an asterisk for an ObjectName that is a property list pattern with no keys; or
  • a comma and an asterisk (,*) for an ObjectName that is a property list pattern with at least one key.

Returns:
The canonical form of the name.

getDomain

public String getDomain()
Returns the domain part.

Returns:
The domain.

getKeyProperty

public String getKeyProperty(String property)
                      throws NullPointerException
Obtains the value associated with a key in a key property.

Parameters:
property - The property whose value is to be obtained.
Returns:
The value of the property, or null if there is no such property in this ObjectName.
Throws:
NullPointerException - If property is null.

getKeyPropertyList

public Hashtable<String,String> getKeyPropertyList()

Returns the key properties as a Hashtable. The returned value is a Hashtable in which each key is a key in the ObjectName's key property list and each value is the associated value.

The returned value may be unmodifiable. If it is modifiable, changing it has no effect on this ObjectName.

Returns:
The table of key properties.

getKeyPropertyListString

public String getKeyPropertyListString()

Returns a string representation of the list of key properties specified at creation time. If this ObjectName was constructed with the constructor ObjectName(String), the key properties in the returned String will be in the same order as in the argument to the constructor.

Returns:
The key property list string. This string is independent of whether the ObjectName is a pattern.

getCanonicalKeyPropertyListString

public String getCanonicalKeyPropertyListString()
Returns a string representation of the list of key properties, in which the key properties are sorted in lexical order. This is used in lexicographic comparisons performed in order to select MBeans based on their key property list. Lexical order is the order implied by String.compareTo(String).

Returns:
The canonical key property list string. This string is independent of whether the ObjectName is a pattern.

toString

public String toString()

Returns a string representation of the object name. The format of this string is not specified, but users can expect that two ObjectNames return the same string if and only if they are equal.

Overrides:
toString in class Object
Returns:
a string representation of this object name.

equals

public boolean equals(Object object)
Compares the current object name with another object name. Two ObjectName instances are equal if and only if their canonical forms are equal. The canonical form is the string described for getCanonicalName().

Overrides:
equals in class Object
Parameters:
object - The object name that the current object name is to be compared with.
Returns:
True if object is an ObjectName whose canonical form is equal to that of this ObjectName.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns a hash code for this object name.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

quote

public static String quote(String s)
                    throws NullPointerException

Returns a quoted form of the given String, suitable for inclusion in an ObjectName. The returned value can be used as the value associated with a key in an ObjectName. The String s may contain any character. Appropriate quoting ensures that the returned value is legal in an ObjectName.

The returned value consists of a quote ('"'), a sequence of characters corresponding to the characters of s, and another quote. Characters in s appear unchanged within the returned value except:

  • A quote ('"') is replaced by a backslash (\) followed by a quote.
  • An asterisk ('*') is replaced by a backslash (\) followed by an asterisk.
  • A question mark ('?') is replaced by a backslash (\) followed by a question mark.
  • A backslash ('\') is replaced by two backslashes.
  • A newline character (the character '\n' in Java) is replaced by a backslash followed by the character '\n'.

Parameters:
s - the String to be quoted.
Returns:
the quoted String.
Throws:
NullPointerException - if s is null.

unquote

public static String unquote(String q)
                      throws IllegalArgumentException,
                             NullPointerException

Returns an unquoted form of the given String. If q is a String returned by quote(s), then unquote(q).equals(s). If there is no String s for which quote(s).equals(q), then unquote(q) throws an IllegalArgumentException.

These rules imply that there is a one-to-one mapping between quoted and unquoted forms.

Parameters:
q - the String to be unquoted.
Returns:
the unquoted String.
Throws:
IllegalArgumentException - if q could not have been returned by the quote(java.lang.String) method, for instance if it does not begin and end with a quote (").
NullPointerException - if q is null.

apply

public boolean apply(ObjectName name)
              throws NullPointerException

Test whether this ObjectName, which may be a pattern, matches another ObjectName. If name is a pattern, the result is false. If this ObjectName is a pattern, the result is true if and only if name matches the pattern. If neither this ObjectName nor name is a pattern, the result is true if and only if the two ObjectNames are equal as described for the equals(Object) method.

Specified by:
apply in interface QueryExp
Parameters:
name - The name of the MBean to compare to.
Returns:
True if name matches this ObjectName.
Throws:
NullPointerException - if name is null.

setMBeanServer

public void setMBeanServer(MBeanServer mbs)
Description copied from interface: QueryExp
Sets the MBean server on which the query is to be performed.

Specified by:
setMBeanServer in interface QueryExp
Parameters:
mbs - The MBean server on which the query is to be performed.

compareTo

public int compareTo(ObjectName name)

Compares two ObjectName instances. The ordering relation between ObjectNames is not completely specified but is intended to be such that a sorted list of ObjectNames will appear in an order that is convenient for a person to read.

In particular, if the two ObjectName instances have different domains then their order is the lexicographical order of the domains. The ordering of the key property list remains unspecified.

For example, the ObjectName instances below:

  • Shapes:type=Square,name=3
  • Colors:type=Red,name=2
  • Shapes:type=Triangle,side=isosceles,name=2
  • Colors:type=Red,name=1
  • Shapes:type=Square,name=1
  • Colors:type=Blue,name=1
  • Shapes:type=Square,name=2
  • JMImplementation:type=MBeanServerDelegate
  • Shapes:type=Triangle,side=scalene,name=1

could be ordered as follows:

  • Colors:type=Blue,name=1
  • Colors:type=Red,name=1
  • Colors:type=Red,name=2
  • JMImplementation:type=MBeanServerDelegate
  • Shapes:type=Square,name=1
  • Shapes:type=Square,name=2
  • Shapes:type=Square,name=3
  • Shapes:type=Triangle,side=scalene,name=1
  • Shapes:type=Triangle,side=isosceles,name=2

Specified by:
compareTo in interface Comparable<ObjectName>
Parameters:
name - the ObjectName to be compared.
Returns:
a negative integer, zero, or a positive integer as this ObjectName is less than, equal to, or greater than the specified ObjectName.
Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


openmbean

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.management.openmbean

Provides the open data types and Open MBean descriptor classes.

See:
Description

Interface Summary
CompositeData | The CompositeData interface specifies the behavior of a specific type of complex open data objects which represent composite data structures.
CompositeDataView | A Java class can implement this interface to indicate how it is to be converted into a CompositeData by the MXBean framework.
OpenMBeanAttributeInfo | Describes an attribute of an open MBean.
OpenMBeanConstructorInfo | Describes a constructor of an Open MBean.
OpenMBeanInfo | Describes an Open MBean: an Open MBean is recognized as such if its getMBeanInfo() method returns an instance of a class which implements the OpenMBeanInfo interface, typically OpenMBeanInfoSupport.
OpenMBeanOperationInfo | Describes an operation of an Open MBean.
OpenMBeanParameterInfo | Describes a parameter used in one or more operations or constructors of an open MBean.
TabularData | The TabularData interface specifies the behavior of a specific type of complex open data objects which represent tabular data structures.

Class Summary
ArrayType<T> | The ArrayType class is the open type class whose instances describe all open data values which are n-dimensional arrays of open data values.
CompositeDataInvocationHandler | An InvocationHandler that forwards getter methods to a CompositeData.
CompositeDataSupport | The CompositeDataSupport class is the open data class which implements the CompositeData interface.
CompositeType | The CompositeType class is the open type class whose instances describe the types of CompositeData values.
OpenMBeanAttributeInfoSupport | Describes an attribute of an open MBean.
OpenMBeanConstructorInfoSupport | Describes a constructor of an Open MBean.
OpenMBeanInfoSupport | The OpenMBeanInfoSupport class describes the management information of an open MBean: it is a subclass of MBeanInfo, and it implements the OpenMBeanInfo interface.
OpenMBeanOperationInfoSupport | Describes an operation of an Open MBean.
OpenMBeanParameterInfoSupport | Describes a parameter used in one or more operations or constructors of an open MBean.
OpenType<T> | The OpenType class is the parent abstract class of all classes which describe the actual open type of open data values.
SimpleType<T> | The SimpleType class is the open type class whose instances describe all open data values which are neither arrays, nor CompositeData values, nor TabularData values.
TabularDataSupport | The TabularDataSupport class is the open data class which implements the TabularData and the Map interfaces, and which is internally based on a hash map data structure.
TabularType | The TabularType class is the open type class whose instances describe the types of TabularData values.

Exception Summary
InvalidKeyException | This runtime exception is thrown to indicate that a method parameter which was expected to be an item name of a composite data or a row index of a tabular data is not valid.
InvalidOpenTypeException | This runtime exception is thrown to indicate that the open type of an open data value is not the one expected.
KeyAlreadyExistsException | This runtime exception is thrown to indicate that the index of a row to be added to a tabular data instance is already used to refer to another row in this tabular data instance.
OpenDataException | This checked exception is thrown when an open type, an open data or an open MBean metadata info instance could not be constructed because one or more validity constraints were not met.

Package javax.management.openmbean Description

Provides the open data types and Open MBean descriptor classes. An Open MBean is an MBean where the types of attributes and of operation parameters and return values are built using a small set of predefined Java classes. Open MBeans facilitate operation with remote management programs that do not necessarily have access to application-specific types, including non-Java programs.

Every MBean has an MBeanInfo with information about the MBean itself, and its attributes, operations, constructors, and notifications. In an Open MBean, this MBeanInfo implements the OpenMBeanInfo interface, usually by being an instance of OpenMBeanInfoSupport.

The attribute information returned by MBeanInfo.getAttributes for an Open MBean is an array of objects implementing OpenMBeanAttributeInfo, usually instances of OpenMBeanAttributeInfoSupport. In addition to the usual information about attributes, an OpenMBeanAttributeInfo specifies the OpenType of the attribute. The possible OpenType values are predefined, which is what ensures that remote managers will understand them.

Similar remarks apply to the parameter types of operations and constructors, and to the return types of operations.

There is a distinction between an attribute's Java language type, as returned by getType(), and its OpenType, as returned by getOpenType(). For example, if the Java language type is java.lang.String, the OpenType will be SimpleType.String. If the Java language type is CompositeData, the OpenType will be a CompositeType that describes the items in the CompositeData instances for the attribute.

Default values and constraints

In Open MBeans, attributes and parameters can have default values and/or constraints associated with them in the OpenMBeanAttributeInfo or OpenMBeanParameterInfo. There are two ways to specify these constraints. Either the values are directly specified as parameters to one of the constructors of OpenMBeanAttributeInfoSupport or OpenMBeanParameterInfoSupport, for example OpenMBeanParameterInfoSupport.OpenMBeanParameterInfoSupport( String, String, OpenType, Object, Object[]); or the values are specified in a Descriptor given as a parameter to one of the constructors.

When a Descriptor is used, the fields of interest are these:

  • defaultValue defines the value returned by getDefaultValue();
  • minValue defines the value returned by getMinValue();
  • maxValue defines the value returned by getMaxValue();
  • legalValues defines the values returned by getLegalValues().

For defaultValue, minValue, and maxValue, the associated value must either be of the Java type corresponding to openType, or be a string that can be converted into that type. The conversion uses the static method valueOf(String) if it finds one; otherwise a constructor with a single String parameter if it finds one; otherwise it fails.

For legalValues, the associated value must be either an array or a Set, and the elements of the array or set must be convertible as described for defaultValue etc.

The following conditions must be met for these fields:

  • the values must be of the appropriate type, or be strings that can be converted to the appropriate type as explained above;
  • if legalValues is present then neither minValue nor maxValue must be present;
  • if defaultValue is present then it must satisfy the constraints defined by legalValues, minValue, or maxValue when any of these is also present;
  • if minValue and maxValue are both present then minValue must not be greater than maxValue.

Since:
1.5
See Also:
Java SE 6 Platform documentation on JMX technology, in particular the JMX Specification, version 1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.management.openmbean Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.management.openmbean

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.management.openmbean.CompositeDataInvocationHandler (implements java.lang.reflect.InvocationHandler)
    • javax.management.openmbean.CompositeDataSupport (implements javax.management.openmbean.CompositeData, java.io.Serializable)
    • javax.management.MBeanFeatureInfo (implements javax.management.DescriptorRead, java.io.Serializable)
      • javax.management.MBeanAttributeInfo (implements java.lang.Cloneable)
        • javax.management.openmbean.OpenMBeanAttributeInfoSupport (implements javax.management.openmbean.OpenMBeanAttributeInfo)
      • javax.management.MBeanConstructorInfo (implements java.lang.Cloneable)
        • javax.management.openmbean.OpenMBeanConstructorInfoSupport (implements javax.management.openmbean.OpenMBeanConstructorInfo)
      • javax.management.MBeanOperationInfo (implements java.lang.Cloneable)
        • javax.management.openmbean.OpenMBeanOperationInfoSupport (implements javax.management.openmbean.OpenMBeanOperationInfo)
      • javax.management.MBeanParameterInfo (implements java.lang.Cloneable)
        • javax.management.openmbean.OpenMBeanParameterInfoSupport (implements javax.management.openmbean.OpenMBeanParameterInfo)
    • javax.management.MBeanInfo (implements java.lang.Cloneable, javax.management.DescriptorRead, java.io.Serializable)
      • javax.management.openmbean.OpenMBeanInfoSupport (implements javax.management.openmbean.OpenMBeanInfo)
    • javax.management.openmbean.OpenType<T> (implements java.io.Serializable)
      • javax.management.openmbean.ArrayType<T>
      • javax.management.openmbean.CompositeType
      • javax.management.openmbean.SimpleType<T>
      • javax.management.openmbean.TabularType
    • javax.management.openmbean.TabularDataSupport (implements java.lang.Cloneable, java.util.Map<K,V>, java.io.Serializable, javax.management.openmbean.TabularData)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.management.JMException
          • javax.management.openmbean.OpenDataException
        • java.lang.RuntimeException
          • java.lang.IllegalArgumentException
            • javax.management.openmbean.InvalidKeyException
            • javax.management.openmbean.InvalidOpenTypeException
            • javax.management.openmbean.KeyAlreadyExistsException

Interface Hierarchy

  • javax.management.openmbean.CompositeData
  • javax.management.openmbean.CompositeDataView
  • javax.management.openmbean.OpenMBeanConstructorInfo
  • javax.management.openmbean.OpenMBeanInfo
  • javax.management.openmbean.OpenMBeanOperationInfo
  • javax.management.openmbean.OpenMBeanParameterInfo
    • javax.management.openmbean.OpenMBeanAttributeInfo
  • javax.management.openmbean.TabularData
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.management.openmbean

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.management.openmbean

Packages that use javax.management.openmbean
java.lang.management | Provides the management interface for monitoring and management of the Java virtual machine as well as the operating system on which the Java virtual machine is running.
javax.management.openmbean | Provides the open data types and Open MBean descriptor classes.

Classes in javax.management.openmbean used by java.lang.management
CompositeData
The CompositeData interface specifies the behavior of a specific type of complex open data objects which represent composite data structures.

Classes in javax.management.openmbean used by javax.management.openmbean
ArrayType
The ArrayType class is the open type class whose instances describe all open data values which are n-dimensional arrays of open data values.
CompositeData
The CompositeData interface specifies the behavior of a specific type of complex open data objects which represent composite data structures.
CompositeType
The CompositeType class is the open type class whose instances describe the types of CompositeData values.
OpenDataException
This checked exception is thrown when an open type, an open data or an open MBean metadata info instance could not be constructed because one or more validity constraints were not met.
OpenMBeanAttributeInfo
Describes an attribute of an open MBean.
OpenMBeanConstructorInfo
Describes a constructor of an Open MBean.
OpenMBeanInfo
Describes an Open MBean: an Open MBean is recognized as such if its getMBeanInfo() method returns an instance of a class which implements the OpenMBeanInfo interface, typically OpenMBeanInfoSupport.
OpenMBeanOperationInfo
Describes an operation of an Open MBean.
OpenMBeanParameterInfo
Describes a parameter used in one or more operations or constructors of an open MBean.
OpenType
The OpenType class is the parent abstract class of all classes which describe the actual open type of open data values.
SimpleType
The SimpleType class is the open type class whose instances describe all open data values which are neither arrays, nor CompositeData values, nor TabularData values.
TabularData
The TabularData interface specifies the behavior of a specific type of complex open data objects which represent tabular data structures.
TabularType
The TabularType class is the open type class whose instances describe the types of TabularData values.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ArrayType

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Class ArrayType<T>

java.lang.Object
    extended by  javax.management.openmbean.OpenType<T>
        extended by  javax.management.openmbean.ArrayType<T>
All Implemented Interfaces:
Serializable
public class ArrayType<T>
extends OpenType<T>

The ArrayType class is the open type class whose instances describe all open data values which are n-dimensional arrays of open data values.

Examples of valid ArrayType instances are:

 // 2-dimension array of java.lang.String
 ArrayType a1 = new ArrayType(2, SimpleType.STRING);

 // 1-dimension array of int
 ArrayType a2 = new ArrayType(SimpleType.INTEGER, true);

 // 1-dimension array of java.lang.Integer
 ArrayType a3 = new ArrayType(SimpleType.INTEGER, false);

 // 4-dimension array of int
 ArrayType a4 = new ArrayType(3, a2);

 // 4-dimension array of java.lang.Integer
 ArrayType a5 = new ArrayType(3, a3);

 // 1-dimension array of java.lang.String
 ArrayType a6 = new ArrayType(SimpleType.STRING, false);

 // 1-dimension array of long
 ArrayType a7 = new ArrayType(SimpleType.LONG, true);

 // 1-dimension array of java.lang.Integer
 ArrayType a8 = ArrayType.getArrayType(SimpleType.INTEGER);

 // 2-dimension array of java.lang.Integer
 ArrayType a9 = ArrayType.getArrayType(a8);

 // 2-dimension array of int
 ArrayType a10 = ArrayType.getPrimitiveArrayType(int[][].class);

 // 3-dimension array of int
 ArrayType a11 = ArrayType.getArrayType(a10);

 // 1-dimension array of float
 ArrayType a12 = ArrayType.getPrimitiveArrayType(float[].class);

 // 2-dimension array of float
 ArrayType a13 = ArrayType.getArrayType(a12);

 // 1-dimension array of javax.management.ObjectName
 ArrayType a14 = ArrayType.getArrayType(SimpleType.OBJECTNAME);

 // 2-dimension array of javax.management.ObjectName
 ArrayType a15 = ArrayType.getArrayType(a14);

 // 3-dimension array of java.lang.String
 ArrayType a16 = new ArrayType(3, SimpleType.STRING);

 // 1-dimension array of java.lang.String
 ArrayType a17 = new ArrayType(1, SimpleType.STRING);

 // 2-dimension array of java.lang.String
 ArrayType a18 = new ArrayType(1, a17);

 // 3-dimension array of java.lang.String
 ArrayType a19 = new ArrayType(1, a18);

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.management.openmbean.OpenType
ALLOWED_CLASSNAMES, ALLOWED_CLASSNAMES_LIST
Constructor Summary
ArrayType(int dimension, OpenType<?> elementType)
Constructs an ArrayType instance describing open data values which are arrays with dimension dimension of elements whose open type is elementType.
ArrayType(SimpleType<?> elementType, boolean primitiveArray)
Constructs a unidimensional ArrayType instance for the supplied SimpleType.
Method Summary
 boolean equals(Object obj)
Compares the specified obj parameter with this ArrayType instance for equality.
static
<E> ArrayType<E[]>
getArrayType(OpenType<E> elementType)
Create an ArrayType instance in a type-safe manner.
 int getDimension()
Returns the dimension of arrays described by this ArrayType instance.
 OpenType<?> getElementOpenType()
Returns the open type of element values contained in the arrays described by this ArrayType instance.
static
<T> ArrayType<T>
getPrimitiveArrayType(Class<T> arrayClass)
Create an ArrayType instance in a type-safe manner.
 int hashCode()
Returns the hash code value for this ArrayType instance.
 boolean isPrimitiveArray()
Returns true if the open data values this open type describes are primitive arrays, false otherwise.
 boolean isValue(Object obj)
Tests whether obj is a value for this ArrayType instance.
 String toString()
Returns a string representation of this ArrayType instance.
Methods inherited from class javax.management.openmbean.OpenType
getClassName, getDescription, getTypeName, isArray
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ArrayType

public ArrayType(int dimension,
                 OpenType<?> elementType)
          throws OpenDataException
Constructs an ArrayType instance describing open data values which are arrays with dimension dimension of elements whose open type is elementType.

When invoked on an ArrayType instance, the getClassName method returns the class name of the array instances it describes (following the rules defined by the getName method of java.lang.Class), not the class name of the array elements (which is returned by a call to getElementOpenType().getClassName()).

The internal field corresponding to the type name of this ArrayType instance is also set to the class name of the array instances it describes. In other words, the methods getClassName and getTypeName return the same string value. The internal field corresponding to the description of this ArrayType instance is set to a string value which follows the following template:

  • if non-primitive array: <dimension>-dimension array of <element_class_name>
  • if primitive array: <dimension>-dimension array of <primitive_type_of_the_element_class_name>

As an example, the following piece of code:

 ArrayType t = new ArrayType(3, SimpleType.STRING);
 System.out.println("array class name       = " + t.getClassName());
 System.out.println("element class name     = " + t.getElementOpenType().getClassName());
 System.out.println("array type name        = " + t.getTypeName());
 System.out.println("array type description = " + t.getDescription());
would produce the following output:
 array class name       = [[[Ljava.lang.String;
 element class name     = java.lang.String
 array type name        = [[[Ljava.lang.String;
 array type description = 3-dimension array of java.lang.String
And the following piece of code which is equivalent to the one listed above would also produce the same output:
 ArrayType t1 = new ArrayType(1, SimpleType.STRING);
 ArrayType t2 = new ArrayType(1, t1);
 ArrayType t3 = new ArrayType(1, t2);
 System.out.println("array class name       = " + t3.getClassName());
 System.out.println("element class name     = " + t3.getElementOpenType().getClassName());
 System.out.println("array type name        = " + t3.getTypeName());
 System.out.println("array type description = " + t3.getDescription());

Parameters:
dimension - the dimension of arrays described by this ArrayType instance; must be greater than or equal to 1.
elementType - the open type of element values contained in the arrays described by this ArrayType instance; must be an instance of either SimpleType, CompositeType, TabularType or another ArrayType with a SimpleType, CompositeType or TabularType as its elementType.
Throws:
IllegalArgumentException - if dimension is not a positive integer.
OpenDataException - if elementType's className is not one of the allowed Java class names for open data.

ArrayType

public ArrayType(SimpleType<?> elementType,
                 boolean primitiveArray)
          throws OpenDataException
Constructs a unidimensional ArrayType instance for the supplied SimpleType.

This constructor supports the creation of arrays of primitive types when primitiveArray is true.

For primitive arrays the getElementOpenType() method returns the SimpleType corresponding to the wrapper type of the primitive type of the array.

When invoked on an ArrayType instance, the getClassName method returns the class name of the array instances it describes (following the rules defined by the getName method of java.lang.Class), not the class name of the array elements (which is returned by a call to getElementOpenType().getClassName()).

The internal field corresponding to the type name of this ArrayType instance is also set to the class name of the array instances it describes. In other words, the methods getClassName and getTypeName return the same string value. The internal field corresponding to the description of this ArrayType instance is set to a string value which follows the following template:

  • if non-primitive array: 1-dimension array of <element_class_name>
  • if primitive array: 1-dimension array of <primitive_type_of_the_element_class_name>

As an example, the following piece of code:

 ArrayType t = new ArrayType(SimpleType.INTEGER, true);
 System.out.println("array class name       = " + t.getClassName());
 System.out.println("element class name     = " + t.getElementOpenType().getClassName());
 System.out.println("array type name        = " + t.getTypeName());
 System.out.println("array type description = " + t.getDescription());
would produce the following output:
 array class name       = [I
 element class name     = java.lang.Integer
 array type name        = [I
 array type description = 1-dimension array of int

Parameters:
elementType - the SimpleType of the element values contained in the arrays described by this ArrayType instance.
primitiveArray - true when this array describes primitive arrays.
Throws:
IllegalArgumentException - if dimension is not a positive integer.
OpenDataException - if primitiveArray is true and elementType is not a valid SimpleType for a primitive type.
Since:
1.6
Method Detail

getDimension

public int getDimension()
Returns the dimension of arrays described by this ArrayType instance.

Returns:
the dimension.

getElementOpenType

public OpenType<?> getElementOpenType()
Returns the open type of element values contained in the arrays described by this ArrayType instance.

Returns:
the element type.

isPrimitiveArray

public boolean isPrimitiveArray()
Returns true if the open data values this open type describes are primitive arrays, false otherwise.

Returns:
true if this is a primitive array type.
Since:
1.6

isValue

public boolean isValue(Object obj)
Tests whether obj is a value for this ArrayType instance.

This method returns true if and only if obj is not null, obj is an array and any one of the following is true:

  • if this ArrayType instance describes an array of SimpleType elements or their corresponding primitive types, obj's class name is the same as the className field defined for this ArrayType instance (i.e. the class name returned by the getClassName method, which includes the dimension information),
  • if this ArrayType instance describes an array of classes implementing the TabularData interface or the CompositeData interface, obj is assignable to such a declared array, and each element contained in obj is either null or a valid value for the element's open type specified by this ArrayType instance.

Specified by:
isValue in class OpenType<T>
Parameters:
obj - the object to be tested.
Returns:
true if obj is a value for this ArrayType instance.

equals

public boolean equals(Object obj)
Compares the specified obj parameter with this ArrayType instance for equality.

Two ArrayType instances are equal if and only if they describe array instances which have the same dimension, elements' open type and primitive array flag.

Specified by:
equals in class OpenType<T>
Parameters:
obj - the object to be compared for equality with this ArrayType instance; if obj is null or is not an instance of the class ArrayType this method returns false.
Returns:
true if the specified object is equal to this ArrayType instance.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns the hash code value for this ArrayType instance.

The hash code of an ArrayType instance is the sum of the hash codes of all the elements of information used in equals comparisons (i.e. dimension, elements' open type and primitive array flag). The hashcode for a primitive value is the hashcode of the corresponding boxed object (e.g. the hashcode for true is Boolean.TRUE.hashCode()). This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two ArrayType instances t1 and t2, as required by the general contract of the method Object.hashCode().

As ArrayType instances are immutable, the hash code for this instance is calculated once, on the first call to hashCode, and then the same value is returned for subsequent calls.

Specified by:
hashCode in class OpenType<T>
Returns:
the hash code value for this ArrayType instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Returns a string representation of this ArrayType instance.

The string representation consists of the name of this class (i.e. javax.management.openmbean.ArrayType), the type name, the dimension, the elements' open type and the primitive array flag defined for this instance.

As ArrayType instances are immutable, the string representation for this instance is calculated once, on the first call to toString, and then the same value is returned for subsequent calls.

Specified by:
toString in class OpenType<T>
Returns:
a string representation of this ArrayType instance

getArrayType

public static <E> ArrayType<E[]> getArrayType(OpenType<E> elementType)
                                   throws OpenDataException
Create an ArrayType instance in a type-safe manner.

Multidimensional arrays can be built up by calling this method as many times as necessary.

Calling this method twice with the same parameters may return the same object or two equal but not identical objects.

As an example, the following piece of code:

 ArrayType t1 = ArrayType.getArrayType(SimpleType.STRING);
 ArrayType t2 = ArrayType.getArrayType(t1);
 ArrayType t3 = ArrayType.getArrayType(t2);
 System.out.println("array class name       = " + t3.getClassName());
 System.out.println("element class name     = " + t3.getElementOpenType().getClassName());
 System.out.println("array type name        = " + t3.getTypeName());
 System.out.println("array type description = " + t3.getDescription());
would produce the following output:
 array class name       = [[[Ljava.lang.String;
 element class name     = java.lang.String
 array type name        = [[[Ljava.lang.String;
 array type description = 3-dimension array of java.lang.String

Parameters:
elementType - the open type of element values contained in the arrays described by this ArrayType instance; must be an instance of either SimpleType, CompositeType, TabularType or another ArrayType with a SimpleType, CompositeType or TabularType as its elementType.
Throws:
OpenDataException - if elementType's className is not one of the allowed Java class names for open data.
Since:
1.6

getPrimitiveArrayType

public static <T> ArrayType<T> getPrimitiveArrayType(Class<T> arrayClass)
Create an ArrayType instance in a type-safe manner.

Calling this method twice with the same parameters may return the same object or two equal but not identical objects.

As an example, the following piece of code:

 ArrayType t = ArrayType.getPrimitiveArrayType(int[][][].class);
 System.out.println("array class name       = " + t.getClassName());
 System.out.println("element class name     = " + t.getElementOpenType().getClassName());
 System.out.println("array type name        = " + t.getTypeName());
 System.out.println("array type description = " + t.getDescription());
would produce the following output:
 array class name       = [[[I
 element class name     = java.lang.Integer
 array type name        = [[[I
 array type description = 3-dimension array of int

Parameters:
arrayClass - a primitive array class such as int[].class, boolean[][].class, etc. The getElementOpenType() method of the returned ArrayType returns the SimpleType corresponding to the wrapper type of the primitive type of the array.
Throws:
IllegalArgumentException - if arrayClass is not a primitive array.
Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.management.openmbean.ArrayType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.openmbean.ArrayType

Packages that use ArrayType
javax.management.openmbean Provides the open data types and Open MBean descriptor classes.

Uses of ArrayType in javax.management.openmbean

Methods in javax.management.openmbean that return ArrayType
static
<E> ArrayType<E[]>
ArrayType.getArrayType(OpenType<E> elementType)
Create an ArrayType instance in a type-safe manner.
static
<T> ArrayType<T>
ArrayType.getPrimitiveArrayType(Class<T> arrayClass)
Create an ArrayType instance in a type-safe manner.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.openmbean.CompositeDataInvocationHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.openmbean.CompositeDataInvocationHandler

No usage of javax.management.openmbean.CompositeDataInvocationHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.openmbean.CompositeDataSupport

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.openmbean.CompositeDataSupport

No usage of javax.management.openmbean.CompositeDataSupport

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.openmbean.CompositeType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.openmbean.CompositeType

Packages that use CompositeType
javax.management.openmbean Provides the open data types and Open MBean descriptor classes.

Uses of CompositeType in javax.management.openmbean

Methods in javax.management.openmbean that return CompositeType
CompositeType | CompositeDataSupport.getCompositeType() Returns the composite type of this composite data instance.
CompositeType | CompositeData.getCompositeType() Returns the composite type of this composite data instance.
CompositeType | TabularType.getRowType() Returns the type of the row elements of tabular data values described by this TabularType instance.

Methods in javax.management.openmbean with parameters of type CompositeType
 CompositeData CompositeDataView.toCompositeData(CompositeType ct)
Return a CompositeData corresponding to the values in this object.

Constructors in javax.management.openmbean with parameters of type CompositeType
CompositeDataSupport(CompositeType compositeType, Map<String,?> items)
Constructs a CompositeDataSupport instance with the specified compositeType, whose item names and corresponding values are given by the mappings in the map items.
CompositeDataSupport(CompositeType compositeType, String[] itemNames, Object[] itemValues)
Constructs a CompositeDataSupport instance with the specified compositeType, whose item values are specified by itemValues[], in the same order as in itemNames[].
TabularType(String typeName, String description, CompositeType rowType, String[] indexNames)
Constructs a TabularType instance, checking for the validity of the given parameters.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.openmbean.InvalidKeyException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.openmbean.InvalidKeyException

No usage of javax.management.openmbean.InvalidKeyException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.openmbean.InvalidOpenTypeException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.openmbean.InvalidOpenTypeException

No usage of javax.management.openmbean.InvalidOpenTypeException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.openmbean.KeyAlreadyExistsException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.openmbean.KeyAlreadyExistsException

No usage of javax.management.openmbean.KeyAlreadyExistsException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.openmbean.OpenDataException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.openmbean.OpenDataException

Packages that use OpenDataException
javax.management.openmbean Provides the open data types and Open MBean descriptor classes.

Uses of OpenDataException in javax.management.openmbean

Methods in javax.management.openmbean that throw OpenDataException
static
<E> ArrayType<E[]>
ArrayType.getArrayType(OpenType<E> elementType)
Create an ArrayType instance in a type-safe manner.

Constructors in javax.management.openmbean that throw OpenDataException
ArrayType(int dimension, OpenType<?> elementType)
Constructs an ArrayType instance describing open data values which are arrays with dimension dimension of elements whose open type is elementType.
ArrayType(SimpleType<?> elementType, boolean primitiveArray)
Constructs a unidimensional ArrayType instance for the supplied SimpleType.
CompositeDataSupport(CompositeType compositeType, Map<String,?> items)
Constructs a CompositeDataSupport instance with the specified compositeType, whose item names and corresponding values are given by the mappings in the map items.
CompositeDataSupport(CompositeType compositeType, String[] itemNames, Object[] itemValues)
Constructs a CompositeDataSupport instance with the specified compositeType, whose item values are specified by itemValues[], in the same order as in itemNames[].
CompositeType(String typeName, String description, String[] itemNames, String[] itemDescriptions, OpenType<?>[] itemTypes)
Constructs a CompositeType instance, checking for the validity of the given parameters.
OpenMBeanAttributeInfoSupport(String name, String description, OpenType<T> openType, boolean isReadable, boolean isWritable, boolean isIs, T defaultValue)
Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean with the specified name, openType, description and defaultValue, and the specified read/write access properties.
OpenMBeanAttributeInfoSupport(String name, String description, OpenType<T> openType, boolean isReadable, boolean isWritable, boolean isIs, T defaultValue, Comparable<T> minValue, Comparable<T> maxValue)
Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean, with the specified name, openType, description, defaultValue, minValue and maxValue.
OpenMBeanAttributeInfoSupport(String name, String description, OpenType<T> openType, boolean isReadable, boolean isWritable, boolean isIs, T defaultValue, T[] legalValues)
Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean with the specified name, openType, description, defaultValue and legalValues, and the specified read/write access properties.
OpenMBeanParameterInfoSupport(String name, String description, OpenType<T> openType, T defaultValue)
Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType, description and defaultValue.
OpenMBeanParameterInfoSupport(String name, String description, OpenType<T> openType, T defaultValue, Comparable<T> minValue, Comparable<T> maxValue)
Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType, description, defaultValue, minValue and maxValue.
OpenMBeanParameterInfoSupport(String name, String description, OpenType<T> openType, T defaultValue, T[] legalValues)
Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType, description, defaultValue and legalValues.
OpenType(String className, String typeName, String description)
Constructs an OpenType instance (actually a subclass instance as OpenType is abstract), checking for the validity of the given parameters.
TabularType(String typeName, String description, CompositeType rowType, String[] indexNames)
Constructs a TabularType instance, checking for the validity of the given parameters.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.openmbean.OpenMBeanAttributeInfoSupport

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.openmbean.OpenMBeanAttributeInfoSupport

No usage of javax.management.openmbean.OpenMBeanAttributeInfoSupport

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.openmbean.OpenMBeanConstructorInfoSupport

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.openmbean.OpenMBeanConstructorInfoSupport

No usage of javax.management.openmbean.OpenMBeanConstructorInfoSupport

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.openmbean.OpenMBeanInfoSupport

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.openmbean.OpenMBeanInfoSupport

No usage of javax.management.openmbean.OpenMBeanInfoSupport

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.openmbean.OpenMBeanOperationInfoSupport

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.openmbean.OpenMBeanOperationInfoSupport

No usage of javax.management.openmbean.OpenMBeanOperationInfoSupport

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.openmbean.OpenMBeanParameterInfoSupport

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.openmbean.OpenMBeanParameterInfoSupport

No usage of javax.management.openmbean.OpenMBeanParameterInfoSupport

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.openmbean.OpenType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.openmbean.OpenType

Packages that use OpenType
javax.management.openmbean Provides the open data types and Open MBean descriptor classes.

Uses of OpenType in javax.management.openmbean

Subclasses of OpenType in javax.management.openmbean
class | ArrayType<T> The ArrayType class is the open type class whose instances describe all open data values which are n-dimensional arrays of open data values.
class | CompositeType The CompositeType class is the open type class whose instances describe the types of CompositeData values.
class | SimpleType<T> The SimpleType class is the open type class whose instances describe all open data values which are neither arrays, nor CompositeData values, nor TabularData values.
class | TabularType The TabularType class is the open type class whose instances describe the types of TabularData values.

Methods in javax.management.openmbean that return OpenType
OpenType<?> | ArrayType.getElementOpenType() Returns the open type of element values contained in the arrays described by this ArrayType instance.
OpenType<?> | OpenMBeanAttributeInfoSupport.getOpenType() Returns the open type for the values of the attribute described by this OpenMBeanAttributeInfoSupport instance.
OpenType<?> | OpenMBeanParameterInfoSupport.getOpenType() Returns the open type for the values of the parameter described by this OpenMBeanParameterInfoSupport instance.
OpenType<?> | OpenMBeanParameterInfo.getOpenType() Returns the open type of the values of the parameter described by this OpenMBeanParameterInfo instance.
OpenType<?> | OpenMBeanOperationInfo.getReturnOpenType() Returns the open type of the values returned by the operation described by this OpenMBeanOperationInfo instance.
OpenType<?> | OpenMBeanOperationInfoSupport.getReturnOpenType() Returns the open type of the values returned by the operation described by this OpenMBeanOperationInfo instance.
OpenType<?> | CompositeType.getType(String itemName) Returns the open type of the item whose name is itemName, or null if this CompositeType instance does not define any item whose name is itemName.

Methods in javax.management.openmbean with parameters of type OpenType
static
<E> ArrayType<E[]>
ArrayType.getArrayType(OpenType<E> elementType)
Create an ArrayType instance in a type-safe manner.

Constructors in javax.management.openmbean with parameters of type OpenType
ArrayType(int dimension, OpenType<?> elementType)
Constructs an ArrayType instance describing open data values which are arrays with dimension dimension of elements whose open type is elementType.
CompositeType(String typeName, String description, String[] itemNames, String[] itemDescriptions, OpenType<?>[] itemTypes)
Constructs a CompositeType instance, checking for the validity of the given parameters.
OpenMBeanAttributeInfoSupport(String name, String description, OpenType<?> openType, boolean isReadable, boolean isWritable, boolean isIs)
Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean with the specified name, openType and description, and the specified read/write access properties.
OpenMBeanAttributeInfoSupport(String name, String description, OpenType<?> openType, boolean isReadable, boolean isWritable, boolean isIs, Descriptor descriptor)
Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean with the specified name, openType, description, read/write access properties, and Descriptor.
OpenMBeanAttributeInfoSupport(String name, String description, OpenType<T> openType, boolean isReadable, boolean isWritable, boolean isIs, T defaultValue)
Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean with the specified name, openType, description and defaultValue, and the specified read/write access properties.
OpenMBeanAttributeInfoSupport(String name, String description, OpenType<T> openType, boolean isReadable, boolean isWritable, boolean isIs, T defaultValue, Comparable<T> minValue, Comparable<T> maxValue)
Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean, with the specified name, openType, description, defaultValue, minValue and maxValue.
OpenMBeanAttributeInfoSupport(String name, String description, OpenType<T> openType, boolean isReadable, boolean isWritable, boolean isIs, T defaultValue, T[] legalValues)
Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean with the specified name, openType, description, defaultValue and legalValues, and the specified read/write access properties.
OpenMBeanOperationInfoSupport(String name, String description, OpenMBeanParameterInfo[] signature, OpenType<?> returnOpenType, int impact)
Constructs an OpenMBeanOperationInfoSupport instance, which describes the operation of a class of open MBeans, with the specified name, description, signature, returnOpenType and impact.
OpenMBeanOperationInfoSupport(String name, String description, OpenMBeanParameterInfo[] signature, OpenType<?> returnOpenType, int impact, Descriptor descriptor)
Constructs an OpenMBeanOperationInfoSupport instance, which describes the operation of a class of open MBeans, with the specified name, description, signature, returnOpenType, impact, and descriptor.
OpenMBeanParameterInfoSupport(String name, String description, OpenType<?> openType)
Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType and description.
OpenMBeanParameterInfoSupport(String name, String description, OpenType<?> openType, Descriptor descriptor)
Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType, description, and descriptor.
OpenMBeanParameterInfoSupport(String name, String description, OpenType<T> openType, T defaultValue)
Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType, description and defaultValue.
OpenMBeanParameterInfoSupport(String name, String description, OpenType<T> openType, T defaultValue, Comparable<T> minValue, Comparable<T> maxValue)
Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType, description, defaultValue, minValue and maxValue.
OpenMBeanParameterInfoSupport(String name, String description, OpenType<T> openType, T defaultValue, T[] legalValues)
Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType, description, defaultValue and legalValues.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.openmbean.SimpleType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.openmbean.SimpleType

Packages that use SimpleType
javax.management.openmbean Provides the open data types and Open MBean descriptor classes.

Uses of SimpleType in javax.management.openmbean

Fields in javax.management.openmbean declared as SimpleType
static SimpleType<BigDecimal> | SimpleType.BIGDECIMAL The SimpleType instance describing values whose Java class name is java.math.BigDecimal.
static SimpleType<BigInteger> | SimpleType.BIGINTEGER The SimpleType instance describing values whose Java class name is java.math.BigInteger.
static SimpleType<Boolean> | SimpleType.BOOLEAN The SimpleType instance describing values whose Java class name is java.lang.Boolean.
static SimpleType<Byte> | SimpleType.BYTE The SimpleType instance describing values whose Java class name is java.lang.Byte.
static SimpleType<Character> | SimpleType.CHARACTER The SimpleType instance describing values whose Java class name is java.lang.Character.
static SimpleType<Date> | SimpleType.DATE The SimpleType instance describing values whose Java class name is java.util.Date.
static SimpleType<Double> | SimpleType.DOUBLE The SimpleType instance describing values whose Java class name is java.lang.Double.
static SimpleType<Float> | SimpleType.FLOAT The SimpleType instance describing values whose Java class name is java.lang.Float.
static SimpleType<Integer> | SimpleType.INTEGER The SimpleType instance describing values whose Java class name is java.lang.Integer.
static SimpleType<Long> | SimpleType.LONG The SimpleType instance describing values whose Java class name is java.lang.Long.
static SimpleType<ObjectName> | SimpleType.OBJECTNAME The SimpleType instance describing values whose Java class name is javax.management.ObjectName.
static SimpleType<Short> | SimpleType.SHORT The SimpleType instance describing values whose Java class name is java.lang.Short.
static SimpleType<String> | SimpleType.STRING The SimpleType instance describing values whose Java class name is java.lang.String.
static SimpleType<Void> | SimpleType.VOID The SimpleType instance describing values whose Java class name is java.lang.Void.

Constructors in javax.management.openmbean with parameters of type SimpleType
ArrayType(SimpleType<?> elementType, boolean primitiveArray)
Constructs a unidimensional ArrayType instance for the supplied SimpleType.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.openmbean.TabularDataSupport

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.openmbean.TabularDataSupport

No usage of javax.management.openmbean.TabularDataSupport

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.openmbean.TabularType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.openmbean.TabularType

Packages that use TabularType
javax.management.openmbean Provides the open data types and Open MBean descriptor classes.

Uses of TabularType in javax.management.openmbean

Methods in javax.management.openmbean that return TabularType
TabularType | TabularDataSupport.getTabularType() Returns the tabular type describing this TabularData instance.
TabularType | TabularData.getTabularType() Returns the tabular type describing this TabularData instance.

Constructors in javax.management.openmbean with parameters of type TabularType
TabularDataSupport(TabularType tabularType)
Creates an empty TabularDataSupport instance whose open-type is tabularType, and whose underlying HashMap has a default initial capacity (101) and default load factor (0.75).
TabularDataSupport(TabularType tabularType, int initialCapacity, float loadFactor)
Creates an empty TabularDataSupport instance whose open-type is tabularType, and whose underlying HashMap has the specified initial capacity and load factor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.openmbean.CompositeData

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.openmbean.CompositeData

Packages that use CompositeData
java.lang.management | Provides the management interface for monitoring and management of the Java virtual machine as well as the operating system on which the Java virtual machine is running.
javax.management.openmbean | Provides the open data types and Open MBean descriptor classes.

Uses of CompositeData in java.lang.management

Methods in java.lang.management with parameters of type CompositeData
static MemoryNotificationInfo | MemoryNotificationInfo.from(CompositeData cd) Returns a MemoryNotificationInfo object represented by the given CompositeData.
static MonitorInfo | MonitorInfo.from(CompositeData cd) Returns a MonitorInfo object represented by the given CompositeData.
static ThreadInfo | ThreadInfo.from(CompositeData cd) Returns a ThreadInfo object represented by the given CompositeData.
static MemoryUsage | MemoryUsage.from(CompositeData cd) Returns a MemoryUsage object represented by the given CompositeData.

Uses of CompositeData in javax.management.openmbean

Classes in javax.management.openmbean that implement CompositeData
 class CompositeDataSupport
The CompositeDataSupport class is the open data class which implements the CompositeData interface.

Methods in javax.management.openmbean that return CompositeData
CompositeData | TabularDataSupport.get(Object[] key) Returns the CompositeData value whose index is key, or null if there is no value mapping to key, in this TabularData instance.
CompositeData | TabularData.get(Object[] key) Returns the CompositeData value whose index is key, or null if there is no value mapping to key, in this TabularData instance.
CompositeData | CompositeDataInvocationHandler.getCompositeData() Return the CompositeData that was supplied to the constructor.
CompositeData | TabularDataSupport.remove(Object[] key) Removes the CompositeData value whose index is key from this TabularData instance, and returns the removed value, or returns null if there is no value whose index is key.
CompositeData | TabularData.remove(Object[] key) Removes the CompositeData value whose index is key from this TabularData instance, and returns the removed value, or returns null if there is no value whose index is key.
CompositeData | CompositeDataView.toCompositeData(CompositeType ct) Return a CompositeData corresponding to the values in this object.

Methods in javax.management.openmbean with parameters of type CompositeData
Object[] | TabularDataSupport.calculateIndex(CompositeData value) Calculates the index that would be used in this TabularData instance to refer to the specified composite data value parameter if it were added to this instance.
Object[] | TabularData.calculateIndex(CompositeData value) Calculates the index that would be used in this TabularData instance to refer to the specified composite data value parameter if it were added to this instance.
boolean | TabularDataSupport.containsValue(CompositeData value) Returns true if and only if this TabularData instance contains the specified CompositeData value.
boolean | TabularData.containsValue(CompositeData value) Returns true if and only if this TabularData instance contains the specified CompositeData value.
void | TabularDataSupport.put(CompositeData value)
void | TabularData.put(CompositeData value) Adds value to this TabularData instance.
void | TabularDataSupport.putAll(CompositeData[] values) Add all the elements in values to this TabularData instance.
void | TabularData.putAll(CompositeData[] values) Add all the elements in values to this TabularData instance.

Constructors in javax.management.openmbean with parameters of type CompositeData
CompositeDataInvocationHandler(CompositeData compositeData)
Construct a handler backed by the given CompositeData.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.openmbean.CompositeDataView

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.openmbean.CompositeDataView

No usage of javax.management.openmbean.CompositeDataView

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.openmbean.OpenMBeanAttributeInfo

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.openmbean.OpenMBeanAttributeInfo

Packages that use OpenMBeanAttributeInfo
javax.management.openmbean Provides the open data types and Open MBean descriptor classes.

Uses of OpenMBeanAttributeInfo in javax.management.openmbean

Classes in javax.management.openmbean that implement OpenMBeanAttributeInfo
 class OpenMBeanAttributeInfoSupport
Describes an attribute of an open MBean.

Constructors in javax.management.openmbean with parameters of type OpenMBeanAttributeInfo
OpenMBeanInfoSupport(String className, String description, OpenMBeanAttributeInfo[] openAttributes, OpenMBeanConstructorInfo[] openConstructors, OpenMBeanOperationInfo[] openOperations, MBeanNotificationInfo[] notifications)
Constructs an OpenMBeanInfoSupport instance, which describes a class of open MBeans with the specified className, description, openAttributes, openConstructors , openOperations and notifications.
OpenMBeanInfoSupport(String className, String description, OpenMBeanAttributeInfo[] openAttributes, OpenMBeanConstructorInfo[] openConstructors, OpenMBeanOperationInfo[] openOperations, MBeanNotificationInfo[] notifications, Descriptor descriptor)
Constructs an OpenMBeanInfoSupport instance, which describes a class of open MBeans with the specified className, description, openAttributes, openConstructors , openOperations, notifications, and descriptor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.openmbean.OpenMBeanConstructorInfo

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.openmbean.OpenMBeanConstructorInfo

Packages that use OpenMBeanConstructorInfo
javax.management.openmbean Provides the open data types and Open MBean descriptor classes.

Uses of OpenMBeanConstructorInfo in javax.management.openmbean

Classes in javax.management.openmbean that implement OpenMBeanConstructorInfo
 class OpenMBeanConstructorInfoSupport
Describes a constructor of an Open MBean.

Constructors in javax.management.openmbean with parameters of type OpenMBeanConstructorInfo
OpenMBeanInfoSupport(String className, String description, OpenMBeanAttributeInfo[] openAttributes, OpenMBeanConstructorInfo[] openConstructors, OpenMBeanOperationInfo[] openOperations, MBeanNotificationInfo[] notifications)
Constructs an OpenMBeanInfoSupport instance, which describes a class of open MBeans with the specified className, description, openAttributes, openConstructors , openOperations and notifications.
OpenMBeanInfoSupport(String className, String description, OpenMBeanAttributeInfo[] openAttributes, OpenMBeanConstructorInfo[] openConstructors, OpenMBeanOperationInfo[] openOperations, MBeanNotificationInfo[] notifications, Descriptor descriptor)
Constructs an OpenMBeanInfoSupport instance, which describes a class of open MBeans with the specified className, description, openAttributes, openConstructors , openOperations, notifications, and descriptor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.openmbean.OpenMBeanInfo

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.openmbean.OpenMBeanInfo

Packages that use OpenMBeanInfo
javax.management.openmbean Provides the open data types and Open MBean descriptor classes.

Uses of OpenMBeanInfo in javax.management.openmbean

Classes in javax.management.openmbean that implement OpenMBeanInfo
 class OpenMBeanInfoSupport
The OpenMBeanInfoSupport class describes the management information of an open MBean: it is a subclass of MBeanInfo, and it implements the OpenMBeanInfo interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.openmbean.OpenMBeanOperationInfo

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.openmbean.OpenMBeanOperationInfo

Packages that use OpenMBeanOperationInfo
javax.management.openmbean Provides the open data types and Open MBean descriptor classes.

Uses of OpenMBeanOperationInfo in javax.management.openmbean

Classes in javax.management.openmbean that implement OpenMBeanOperationInfo
 class OpenMBeanOperationInfoSupport
Describes an operation of an Open MBean.

Constructors in javax.management.openmbean with parameters of type OpenMBeanOperationInfo
OpenMBeanInfoSupport(String className, String description, OpenMBeanAttributeInfo[] openAttributes, OpenMBeanConstructorInfo[] openConstructors, OpenMBeanOperationInfo[] openOperations, MBeanNotificationInfo[] notifications)
Constructs an OpenMBeanInfoSupport instance, which describes a class of open MBeans with the specified className, description, openAttributes, openConstructors , openOperations and notifications.
OpenMBeanInfoSupport(String className, String description, OpenMBeanAttributeInfo[] openAttributes, OpenMBeanConstructorInfo[] openConstructors, OpenMBeanOperationInfo[] openOperations, MBeanNotificationInfo[] notifications, Descriptor descriptor)
Constructs an OpenMBeanInfoSupport instance, which describes a class of open MBeans with the specified className, description, openAttributes, openConstructors , openOperations, notifications, and descriptor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.openmbean.OpenMBeanParameterInfo

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.openmbean.OpenMBeanParameterInfo

Packages that use OpenMBeanParameterInfo
javax.management.openmbean Provides the open data types and Open MBean descriptor classes.

Uses of OpenMBeanParameterInfo in javax.management.openmbean

Subinterfaces of OpenMBeanParameterInfo in javax.management.openmbean
 interface OpenMBeanAttributeInfo
Describes an attribute of an open MBean.

Classes in javax.management.openmbean that implement OpenMBeanParameterInfo
class | OpenMBeanAttributeInfoSupport Describes an attribute of an open MBean.
class | OpenMBeanParameterInfoSupport Describes a parameter used in one or more operations or constructors of an open MBean.

Constructors in javax.management.openmbean with parameters of type OpenMBeanParameterInfo
OpenMBeanConstructorInfoSupport(String name, String description, OpenMBeanParameterInfo[] signature)
Constructs an OpenMBeanConstructorInfoSupport instance, which describes the constructor of a class of open MBeans with the specified name, description and signature.
OpenMBeanConstructorInfoSupport(String name, String description, OpenMBeanParameterInfo[] signature, Descriptor descriptor)
Constructs an OpenMBeanConstructorInfoSupport instance, which describes the constructor of a class of open MBeans with the specified name, description, signature, and descriptor.
OpenMBeanOperationInfoSupport(String name, String description, OpenMBeanParameterInfo[] signature, OpenType<?> returnOpenType, int impact)
Constructs an OpenMBeanOperationInfoSupport instance, which describes the operation of a class of open MBeans, with the specified name, description, signature, returnOpenType and impact.
OpenMBeanOperationInfoSupport(String name, String description, OpenMBeanParameterInfo[] signature, OpenType<?> returnOpenType, int impact, Descriptor descriptor)
Constructs an OpenMBeanOperationInfoSupport instance, which describes the operation of a class of open MBeans, with the specified name, description, signature, returnOpenType, impact, and descriptor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.openmbean.TabularData

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.openmbean.TabularData

Packages that use TabularData
javax.management.openmbean Provides the open data types and Open MBean descriptor classes.

Uses of TabularData in javax.management.openmbean

Classes in javax.management.openmbean that implement TabularData
 class TabularDataSupport
The TabularDataSupport class is the open data class which implements the TabularData and the Map interfaces, and which is internally based on a hash map data structure.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


CompositeData

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Interface CompositeData

All Known Implementing Classes:
CompositeDataSupport
public interface CompositeData

The CompositeData interface specifies the behavior of a specific type of complex open data objects which represent composite data structures.

Since:
1.5

Method Summary
boolean | containsKey(String key) Returns true if and only if this CompositeData instance contains an item whose name is key.
boolean | containsValue(Object value) Returns true if and only if this CompositeData instance contains an item whose value is value.
boolean | equals(Object obj) Compares the specified obj parameter with this CompositeData instance for equality.
Object | get(String key) Returns the value of the item whose name is key.
Object[] | getAll(String[] keys) Returns an array of the values of the items whose names are specified by keys, in the same order as keys.
CompositeType | getCompositeType() Returns the composite type of this composite data instance.
int | hashCode() Returns the hash code value for this CompositeData instance.
String | toString() Returns a string representation of this CompositeData instance.
Collection<?> | values() Returns an unmodifiable Collection view of the item values contained in this CompositeData instance.

Method Detail

getCompositeType

CompositeType getCompositeType()
Returns the composite type of this composite data instance.

Returns:
the type of this CompositeData.

get

Object get(String key)
Returns the value of the item whose name is key.

Parameters:
key - the name of the item.
Returns:
the value associated with this key.
Throws:
IllegalArgumentException - if key is a null or empty String.
InvalidKeyException - if key is not an existing item name for this CompositeData instance.

getAll

Object[] getAll(String[] keys)
Returns an array of the values of the items whose names are specified by keys, in the same order as keys.

Parameters:
keys - the names of the items.
Returns:
the values corresponding to the keys.
Throws:
IllegalArgumentException - if an element in keys is a null or empty String.
InvalidKeyException - if an element in keys is not an existing item name for this CompositeData instance.

containsKey

boolean containsKey(String key)
Returns true if and only if this CompositeData instance contains an item whose name is key. If key is a null or empty String, this method simply returns false.

Parameters:
key - the key to be tested.
Returns:
true if this CompositeData contains the key.

containsValue

boolean containsValue(Object value)
Returns true if and only if this CompositeData instance contains an item whose value is value.

Parameters:
value - the value to be tested.
Returns:
true if this CompositeData contains the value.

values

Collection<?> values()
Returns an unmodifiable Collection view of the item values contained in this CompositeData instance. The returned collection's iterator will return the values in the ascending lexicographic order of the corresponding item names.

Returns:
the values.

equals

boolean equals(Object obj)
Compares the specified obj parameter with this CompositeData instance for equality.

Returns true if and only if all of the following statements are true:

  • obj is non null,
  • obj also implements the CompositeData interface,
  • their composite types are equal
  • their contents, i.e. (name, value) pairs are equal. If a value contained in the content is an array, the value comparison is done as if by calling the deepEquals method for arrays of object reference types or the appropriate overloading of Arrays.equals(e1,e2) for arrays of primitive types

This ensures that this equals method works properly for obj parameters which are different implementations of the CompositeData interface, with the restrictions mentioned in the equals method of the java.util.Collection interface.

Overrides:
equals in class Object
Parameters:
obj - the object to be compared for equality with this CompositeData instance.
Returns:
true if the specified object is equal to this CompositeData instance.
See Also:
Object.hashCode(), Hashtable

hashCode

int hashCode()
Returns the hash code value for this CompositeData instance.

The hash code of a CompositeData instance is the sum of the hash codes of all elements of information used in equals comparisons (ie: its composite type and all the item values).

This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two CompositeData instances t1 and t2, as required by the general contract of the method Object.hashCode().

Each item value's hash code is added to the returned hash code. If an item value is an array, its hash code is obtained as if by calling the deepHashCode method for arrays of object reference types or the appropriate overloading of Arrays.hashCode(e) for arrays of primitive types.

Overrides:
hashCode in class Object
Returns:
the hash code value for this CompositeData instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

String toString()
Returns a string representation of this CompositeData instance.

The string representation consists of the name of the implementing class, the string representation of the composite type of this instance, and the string representation of the contents (ie list the itemName=itemValue mappings).

Overrides:
toString in class Object
Returns:
a string representation of this CompositeData instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CompositeDataInvocationHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Class CompositeDataInvocationHandler

java.lang.Object
    extended by  javax.management.openmbean.CompositeDataInvocationHandler
All Implemented Interfaces:
InvocationHandler
public class CompositeDataInvocationHandler
extends Object
implements InvocationHandler

An InvocationHandler that forwards getter methods to a CompositeData. If you have an interface that contains only getter methods (such as String getName() or boolean isActive()) then you can use this class in conjunction with the Proxy class to produce an implementation of the interface where each getter returns the value of the corresponding item in a CompositeData.

For example, suppose you have an interface like this:

   public interface NamedNumber {
       public int getNumber();
       public String getName();
   }
and a CompositeData constructed like this:
   CompositeData cd =
       new CompositeDataSupport(
           someCompositeType,
           new String[] {"number", "name"},
           new Object[] {5, "five"}
       );
then you can construct an object implementing NamedNumber and backed by the object cd like this:
   InvocationHandler handler =
       new CompositeDataInvocationHandler(cd);
   NamedNumber nn = (NamedNumber)
       Proxy.newProxyInstance(NamedNumber.class.getClassLoader(),
                              new Class[] {NamedNumber.class},
                              handler);
A call to nn.getNumber() will then return 5.

If the first letter of the property defined by a getter is a capital, then this handler will look first for an item in the CompositeData beginning with a capital, then, if that is not found, for an item beginning with the corresponding lowercase letter or code point. For a getter called getNumber(), the handler will first look for an item called Number, then for number. If the getter is called getnumber(), then the item must be called number.

If the method given to invoke is the method boolean equals(Object) inherited from Object, then it will return true if and only if the argument is a Proxy whose InvocationHandler is also a CompositeDataInvocationHandler and whose backing CompositeData is equal (not necessarily identical) to this object's. If the method given to invoke is the method int hashCode() inherited from Object, then it will return a value that is consistent with this definition of equals: if two objects are equal according to equals, then they will have the same hashCode.

Since:
1.6

Constructor Summary
CompositeDataInvocationHandler(CompositeData compositeData)
Construct a handler backed by the given CompositeData.
Method Summary
CompositeData | getCompositeData() Return the CompositeData that was supplied to the constructor.
Object | invoke(Object proxy, Method method, Object[] args) Processes a method invocation on a proxy instance and returns the result.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CompositeDataInvocationHandler

public CompositeDataInvocationHandler(CompositeData compositeData)

Construct a handler backed by the given CompositeData.

Parameters:
compositeData - the CompositeData that will supply information to getters.
Throws:
IllegalArgumentException - if compositeData is null.
Method Detail

getCompositeData

public CompositeData getCompositeData()
Return the CompositeData that was supplied to the constructor.

Returns:
the CompositeData that this handler is backed by. This is never null.

invoke

public Object invoke(Object proxy,
                     Method method,
                     Object[] args)
              throws Throwable
Description copied from interface: InvocationHandler
Processes a method invocation on a proxy instance and returns the result. This method will be invoked on an invocation handler when a method is invoked on a proxy instance that it is associated with.

Specified by:
invoke in interface InvocationHandler
Parameters:
proxy - the proxy instance that the method was invoked on
method - the Method instance corresponding to the interface method invoked on the proxy instance. The declaring class of the Method object will be the interface that the method was declared in, which may be a superinterface of the proxy interface that the proxy class inherits the method through.
args - an array of objects containing the values of the arguments passed in the method invocation on the proxy instance, or null if interface method takes no arguments. Arguments of primitive types are wrapped in instances of the appropriate primitive wrapper class, such as java.lang.Integer or java.lang.Boolean.
Returns:
the value to return from the method invocation on the proxy instance. If the declared return type of the interface method is a primitive type, then the value returned by this method must be an instance of the corresponding primitive wrapper class; otherwise, it must be a type assignable to the declared return type. If the value returned by this method is null and the interface method's return type is primitive, then a NullPointerException will be thrown by the method invocation on the proxy instance. If the value returned by this method is otherwise not compatible with the interface method's declared return type as described above, a ClassCastException will be thrown by the method invocation on the proxy instance.
Throws:
Throwable - the exception to throw from the method invocation on the proxy instance. The exception's type must be assignable either to any of the exception types declared in the throws clause of the interface method or to the unchecked exception types java.lang.RuntimeException or java.lang.Error. If a checked exception is thrown by this method that is not assignable to any of the exception types declared in the throws clause of the interface method, then an UndeclaredThrowableException containing the exception that was thrown by this method will be thrown by the method invocation on the proxy instance.
See Also:
UndeclaredThrowableException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CompositeDataSupport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Class CompositeDataSupport

java.lang.Object
    extended by  javax.management.openmbean.CompositeDataSupport
All Implemented Interfaces:
Serializable, CompositeData
public class CompositeDataSupport
extends Object
implements CompositeData, Serializable

The CompositeDataSupport class is the open data class which implements the CompositeData interface.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
CompositeDataSupport(CompositeType compositeType, Map<String,?> items)
Constructs a CompositeDataSupport instance with the specified compositeType, whose item names and corresponding values are given by the mappings in the map items.
CompositeDataSupport(CompositeType compositeType, String[] itemNames, Object[] itemValues)
Constructs a CompositeDataSupport instance with the specified compositeType, whose item values are specified by itemValues[], in the same order as in itemNames[].
Method Summary
boolean | containsKey(String key) Returns true if and only if this CompositeData instance contains an item whose name is key.
boolean | containsValue(Object value) Returns true if and only if this CompositeData instance contains an item whose value is value.
boolean | equals(Object obj) Compares the specified obj parameter with this CompositeDataSupport instance for equality.
Object | get(String key) Returns the value of the item whose name is key.
Object[] | getAll(String[] keys) Returns an array of the values of the items whose names are specified by keys, in the same order as keys.
CompositeType | getCompositeType() Returns the composite type of this composite data instance.
int | hashCode() Returns the hash code value for this CompositeDataSupport instance.
String | toString() Returns a string representation of this CompositeDataSupport instance.
Collection<?> | values() Returns an unmodifiable Collection view of the item values contained in this CompositeData instance.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

CompositeDataSupport

public CompositeDataSupport(CompositeType compositeType,
                            String[] itemNames,
                            Object[] itemValues)
                     throws OpenDataException

Constructs a CompositeDataSupport instance with the specified compositeType, whose item values are specified by itemValues[], in the same order as in itemNames[]. As a CompositeType does not specify any order on its items, the itemNames[] parameter is used to specify the order in which the values are given in itemValues[]. The items contained in this CompositeDataSupport instance are internally stored in a TreeMap, thus sorted in ascending lexicographic order of their names, for faster retrieval of individual item values.

The constructor checks that all the constraints listed below for each parameter are satisfied, and throws the appropriate exception if they are not.

Parameters:
compositeType - the composite type of this composite data instance; must not be null.

itemNames - itemNames must list, in any order, all the item names defined in compositeType; the order in which the names are listed, is used to match values in itemValues[]; must not be null or empty.

itemValues - the values of the items, listed in the same order as their respective names in itemNames; each item value can be null, but if it is non-null it must be a valid value for the open type defined in compositeType for the corresponding item; must be of the same size as itemNames; must not be null or empty.

Throws:
IllegalArgumentException - compositeType is null, or itemNames[] or itemValues[] is null or empty, or one of the elements in itemNames[] is a null or empty string, or itemNames[] and itemValues[] are not of the same size.

OpenDataException - itemNames[] or itemValues[]'s size differs from the number of items defined in compositeType, or one of the elements in itemNames[] does not exist as an item name defined in compositeType, or one of the elements in itemValues[] is not a valid value for the corresponding item as defined in compositeType.

CompositeDataSupport

public CompositeDataSupport(CompositeType compositeType,
                            Map<String,?> items)
                     throws OpenDataException

Constructs a CompositeDataSupport instance with the specified compositeType, whose item names and corresponding values are given by the mappings in the map items. This constructor converts the keys to a string array and the values to an object array and calls CompositeDataSupport(javax.management.openmbean.CompositeType, java.lang.String[], java.lang.Object[]).

Parameters:
compositeType - the composite type of this composite data instance; must not be null.

items - the mappings of all the item names to their values; items must contain all the item names defined in compositeType; must not be null or empty.

Throws:
IllegalArgumentException - compositeType is null, or items is null or empty, or one of the keys in items is a null or empty string, or one of the values in items is null.

OpenDataException - items' size differs from the number of items defined in compositeType, or one of the keys in items does not exist as an item name defined in compositeType, or one of the values in items is not a valid value for the corresponding item as defined in compositeType.

ArrayStoreException - one or more keys in items is not of the class java.lang.String.

Method Detail

getCompositeType

public CompositeType getCompositeType()
Returns the composite type of this composite data instance.

Specified by:
getCompositeType in interface CompositeData
Returns:
the type of this CompositeData.

get

public Object get(String key)
Returns the value of the item whose name is key.

Specified by:
get in interface CompositeData
Parameters:
key - the name of the item.
Returns:
the value associated with this key.
Throws:
IllegalArgumentException - if key is a null or empty String.
InvalidKeyException - if key is not an existing item name for this CompositeData instance.

getAll

public Object[] getAll(String[] keys)
Returns an array of the values of the items whose names are specified by keys, in the same order as keys.

Specified by:
getAll in interface CompositeData
Parameters:
keys - the names of the items.
Returns:
the values corresponding to the keys.
Throws:
IllegalArgumentException - if an element in keys is a null or empty String.
InvalidKeyException - if an element in keys is not an existing item name for this CompositeData instance.

containsKey

public boolean containsKey(String key)
Returns true if and only if this CompositeData instance contains an item whose name is key. If key is a null or empty String, this method simply returns false.

Specified by:
containsKey in interface CompositeData
Parameters:
key - the key to be tested.
Returns:
true if this CompositeData contains the key.

containsValue

public boolean containsValue(Object value)
Returns true if and only if this CompositeData instance contains an item whose value is value.

Specified by:
containsValue in interface CompositeData
Parameters:
value - the value to be tested.
Returns:
true if this CompositeData contains the value.

values

public Collection<?> values()
Returns an unmodifiable Collection view of the item values contained in this CompositeData instance. The returned collection's iterator will return the values in the ascending lexicographic order of the corresponding item names.

Specified by:
values in interface CompositeData
Returns:
the values.

equals

public boolean equals(Object obj)
Compares the specified obj parameter with this CompositeDataSupport instance for equality.

Returns true if and only if all of the following statements are true:

  • obj is non null,
  • obj also implements the CompositeData interface,
  • their composite types are equal
  • their contents, i.e. (name, value) pairs are equal. If a value contained in the content is an array, the value comparison is done as if by calling the deepEquals method for arrays of object reference types or the appropriate overloading of Arrays.equals(e1,e2) for arrays of primitive types

This ensures that this equals method works properly for obj parameters which are different implementations of the CompositeData interface, with the restrictions mentioned in the equals method of the java.util.Collection interface.

Specified by:
equals in interface CompositeData
Overrides:
equals in class Object
Parameters:
obj - the object to be compared for equality with this CompositeDataSupport instance.
Returns:
true if the specified object is equal to this CompositeDataSupport instance.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns the hash code value for this CompositeDataSupport instance.

The hash code of a CompositeDataSupport instance is the sum of the hash codes of all elements of information used in equals comparisons (ie: its composite type and all the item values).

This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two CompositeDataSupport instances t1 and t2, as required by the general contract of the method Object.hashCode().

Each item value's hash code is added to the returned hash code. If an item value is an array, its hash code is obtained as if by calling the deepHashCode method for arrays of object reference types or the appropriate overloading of Arrays.hashCode(e) for arrays of primitive types.

Specified by:
hashCode in interface CompositeData
Overrides:
hashCode in class Object
Returns:
the hash code value for this CompositeDataSupport instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Returns a string representation of this CompositeDataSupport instance.

The string representation consists of the name of this class (ie javax.management.openmbean.CompositeDataSupport), the string representation of the composite type of this instance, and the string representation of the contents (ie list the itemName=itemValue mappings).

Specified by:
toString in interface CompositeData
Overrides:
toString in class Object
Returns:
a string representation of this CompositeDataSupport instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CompositeDataView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Interface CompositeDataView

public interface CompositeDataView

A Java class can implement this interface to indicate how it is to be converted into a CompositeData by the MXBean framework.

A typical way to use this class is to add extra items to the CompositeData in addition to the ones that are declared in the CompositeType supplied by the MXBean framework. To do this, you must create another CompositeType that has all the same items, plus your extra items.

For example, suppose you have a class Measure that consists of a String called units and a value that is either a long or a double. It might look like this:

 public class Measure implements CompositeDataView {
     private String units;
     private Number value; // a Long or a Double

     public Measure(String units, Number value) {
         this.units = units;
         this.value = value;
     }

     public static Measure from(CompositeData cd) {
         return new Measure((String) cd.get("units"),
                            (Number) cd.get("value"));
     }

     public String getUnits() {
         return units;
     }

     // Can't be called getValue(), because Number is not a valid type
     // in an MXBean, so the implied "value" property would be rejected.
     public Number _getValue() {
         return value;
     }

     public CompositeData toCompositeData(CompositeType ct) {
         try {
             List<String> itemNames = new ArrayList<String>(ct.keySet());
             List<String> itemDescriptions = new ArrayList<String>();
             List<OpenType<?>> itemTypes = new ArrayList<OpenType<?>>();
             for (String item : itemNames) {
                 itemDescriptions.add(ct.getDescription(item));
                 itemTypes.add(ct.getType(item));
             }
             itemNames.add("value");
             itemDescriptions.add("long or double value of the measure");
             itemTypes.add((value instanceof Long) ? SimpleType.LONG :
                           SimpleType.DOUBLE);
             CompositeType xct =
                 new CompositeType(ct.getTypeName(),
                                   ct.getDescription(),
                                   itemNames.toArray(new String[0]),
                                   itemDescriptions.toArray(new String[0]),
                                   itemTypes.toArray(new OpenType<?>[0]));
             CompositeData cd =
                 new CompositeDataSupport(xct,
                                          new String[] {"units", "value"},
                                          new Object[] {units, value});
             assert ct.isValue(cd);  // check we've done it right
             return cd;
         } catch (Exception e) {
             throw new RuntimeException(e);
         }
     }
 }

The CompositeType that will appear in the openType field of the Descriptor for an attribute or operation of this type will show only the units item, but the actual CompositeData that is generated will have both units and value.

Since:
1.6
See Also:
MXBean

Method Summary
 CompositeData toCompositeData(CompositeType ct)
Return a CompositeData corresponding to the values in this object.

Method Detail

toCompositeData

CompositeData toCompositeData(CompositeType ct)

Return a CompositeData corresponding to the values in this object. The returned value should usually be an instance of CompositeDataSupport, or a class that serializes as a CompositeDataSupport via a writeReplace method. Otherwise, a remote client that receives the object might not be able to reconstruct it.

Parameters:
ct - The expected CompositeType of the returned value. If the returned value is cd, then cd.getCompositeType().equals(ct) should be true. Typically this will be because cd is a CompositeDataSupport constructed with ct as its CompositeType.
Returns:
the CompositeData.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CompositeType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Class CompositeType

java.lang.Object
    extended by  javax.management.openmbean.OpenType<CompositeData>
        extended by  javax.management.openmbean.CompositeType
All Implemented Interfaces:
Serializable
public class CompositeType
extends OpenType<CompositeData>

The CompositeType class is the open type class whose instances describe the types of CompositeData values.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.management.openmbean.OpenType
ALLOWED_CLASSNAMES, ALLOWED_CLASSNAMES_LIST
Constructor Summary
CompositeType(String typeName, String description, String[] itemNames, String[] itemDescriptions, OpenType<?>[] itemTypes)
Constructs a CompositeType instance, checking for the validity of the given parameters.
Method Summary
boolean | containsKey(String itemName) Returns true if this CompositeType instance defines an item whose name is itemName.
boolean | equals(Object obj) Compares the specified obj parameter with this CompositeType instance for equality.
String | getDescription(String itemName) Returns the description of the item whose name is itemName, or null if this CompositeType instance does not define any item whose name is itemName.
OpenType<?> | getType(String itemName) Returns the open type of the item whose name is itemName, or null if this CompositeType instance does not define any item whose name is itemName.
int | hashCode() Returns the hash code value for this CompositeType instance.
boolean | isValue(Object obj) Tests whether obj is a value which could be described by this CompositeType instance.
Set<String> | keySet() Returns an unmodifiable Set view of all the item names defined by this CompositeType instance.
String | toString() Returns a string representation of this CompositeType instance.
Methods inherited from class javax.management.openmbean.OpenType
getClassName, getDescription, getTypeName, isArray
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

CompositeType

public CompositeType(String typeName,
                     String description,
                     String[] itemNames,
                     String[] itemDescriptions,
                     OpenType<?>[] itemTypes)
              throws OpenDataException
Constructs a CompositeType instance, checking for the validity of the given parameters. The validity constraints are described below for each parameter.

Note that the contents of the three array parameters itemNames, itemDescriptions and itemTypes are internally copied so that any subsequent modification of these arrays by the caller of this constructor has no impact on the constructed CompositeType instance.

The Java class name of composite data values this composite type represents (ie the class name returned by the getClassName method) is set to the string value returned by CompositeData.class.getName().

Parameters:
typeName - The name given to the composite type this instance represents; cannot be a null or empty string.
description - The human readable description of the composite type this instance represents; cannot be a null or empty string.
itemNames - The names of the items contained in the composite data values described by this CompositeType instance; cannot be null and should contain at least one element; no element can be a null or empty string. Note that the order in which the item names are given is not important to differentiate a CompositeType instance from another; the item names are internally stored sorted in ascending alphanumeric order.
itemDescriptions - The descriptions, in the same order as itemNames, of the items contained in the composite data values described by this CompositeType instance; should be of the same size as itemNames; no element can be a null or empty string.
itemTypes - The open type instances, in the same order as itemNames, describing the items contained in the composite data values described by this CompositeType instance; should be of the same size as itemNames; no element can be null.
Throws:
IllegalArgumentException - If typeName or description is a null or empty string, or itemNames or itemDescriptions or itemTypes is null, or any element of itemNames or itemDescriptions is a null or empty string, or any element of itemTypes is null, or itemNames or itemDescriptions or itemTypes are not of the same size.
OpenDataException - If itemNames contains duplicate item names (case sensitive, but leading and trailing whitespaces removed).
Method Detail

containsKey

public boolean containsKey(String itemName)
Returns true if this CompositeType instance defines an item whose name is itemName.

Parameters:
itemName - the name of the item.
Returns:
true if an item of this name is present.

getDescription

public String getDescription(String itemName)
Returns the description of the item whose name is itemName, or null if this CompositeType instance does not define any item whose name is itemName.

Parameters:
itemName - the name of the item.
Returns:
the description.

getType

public OpenType<?> getType(String itemName)
Returns the open type of the item whose name is itemName, or null if this CompositeType instance does not define any item whose name is itemName.

Parameters:
itemName - the name of the time.
Returns:
the type.

keySet

public Set<String> keySet()
Returns an unmodifiable Set view of all the item names defined by this CompositeType instance. The set's iterator will return the item names in ascending order.

Returns:
a Set of String.

isValue

public boolean isValue(Object obj)
Tests whether obj is a value which could be described by this CompositeType instance.

If obj is null or is not an instance of javax.management.openmbean.CompositeData, isValue returns false.

If obj is an instance of javax.management.openmbean.CompositeData, then let ct be its CompositeType as returned by CompositeData.getCompositeType(). The result is true if this is assignable from ct. This means that:

  • this.getTypeName() equals ct.getTypeName(), and
  • there are no item names present in this that are not also present in ct, and
  • for every item in this, its type is assignable from the type of the corresponding item in ct.

A TabularType is assignable from another TabularType if they have the same typeName and index name list, and the row type of the first is assignable from the row type of the second.

An ArrayType is assignable from another ArrayType if they have the same dimension; and both are primitive arrays or neither is; and the element type of the first is assignable from the element type of the second.

In every other case, an OpenType is assignable from another OpenType only if they are equal.

These rules mean that extra items can be added to a CompositeData without making it invalid for a CompositeType that does not have those items.

Specified by:
isValue in class OpenType<CompositeData>
Parameters:
obj - the value whose open type is to be tested for compatibility with this CompositeType instance.
Returns:
true if obj is a value for this composite type, false otherwise.

equals

public boolean equals(Object obj)
Compares the specified obj parameter with this CompositeType instance for equality.

Two CompositeType instances are equal if and only if all of the following statements are true:

  • their type names are equal
  • their items' names and types are equal

Specified by:
equals in class OpenType<CompositeData>
Parameters:
obj - the object to be compared for equality with this CompositeType instance; if obj is null, equals returns false.
Returns:
true if the specified object is equal to this CompositeType instance.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns the hash code value for this CompositeType instance.

The hash code of a CompositeType instance is the sum of the hash codes of all elements of information used in equals comparisons (ie: name, items names, items types). This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two CompositeType instances t1 and t2, as required by the general contract of the method Object.hashCode().

As CompositeType instances are immutable, the hash code for this instance is calculated once, on the first call to hashCode, and then the same value is returned for subsequent calls.

Specified by:
hashCode in class OpenType<CompositeData>
Returns:
the hash code value for this CompositeType instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Returns a string representation of this CompositeType instance.

The string representation consists of the name of this class (ie javax.management.openmbean.CompositeType), the type name for this instance, and the list of the items names and types string representation of this instance.

As CompositeType instances are immutable, the string representation for this instance is calculated once, on the first call to toString, and then the same value is returned for subsequent calls.

Specified by:
toString in class OpenType<CompositeData>
Returns:
a string representation of this CompositeType instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidKeyException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Class InvalidKeyException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  java.lang.IllegalArgumentException
                    extended by  javax.management.openmbean.InvalidKeyException
All Implemented Interfaces:
Serializable
public class InvalidKeyException
extends IllegalArgumentException

This runtime exception is thrown to indicate that a method parameter which was expected to be an item name of a composite data or a row index of a tabular data is not valid.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
InvalidKeyException()
An InvalidKeyException with no detail message.
InvalidKeyException(String msg)
An InvalidKeyException with a detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidKeyException

public InvalidKeyException()
An InvalidKeyException with no detail message.

InvalidKeyException

public InvalidKeyException(String msg)
An InvalidKeyException with a detail message.

Parameters:
msg - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidOpenTypeException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Class InvalidOpenTypeException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  java.lang.IllegalArgumentException
                    extended by  javax.management.openmbean.InvalidOpenTypeException
All Implemented Interfaces:
Serializable
public class InvalidOpenTypeException
extends IllegalArgumentException

This runtime exception is thrown to indicate that the open type of an open data value is not the one expected.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
InvalidOpenTypeException()
An InvalidOpenTypeException with no detail message.
InvalidOpenTypeException(String msg)
An InvalidOpenTypeException with a detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidOpenTypeException

public InvalidOpenTypeException()
An InvalidOpenTypeException with no detail message.

InvalidOpenTypeException

public InvalidOpenTypeException(String msg)
An InvalidOpenTypeException with a detail message.

Parameters:
msg - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


KeyAlreadyExistsException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Class KeyAlreadyExistsException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  java.lang.IllegalArgumentException
                    extended by  javax.management.openmbean.KeyAlreadyExistsException
All Implemented Interfaces:
Serializable
public class KeyAlreadyExistsException
extends IllegalArgumentException

This runtime exception is thrown to indicate that the index of a row to be added to a tabular data instance is already used to refer to another row in this tabular data instance.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
KeyAlreadyExistsException()
A KeyAlreadyExistsException with no detail message.
KeyAlreadyExistsException(String msg)
A KeyAlreadyExistsException with a detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

KeyAlreadyExistsException

public KeyAlreadyExistsException()
A KeyAlreadyExistsException with no detail message.

KeyAlreadyExistsException

public KeyAlreadyExistsException(String msg)
A KeyAlreadyExistsException with a detail message.

Parameters:
msg - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OpenDataException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Class OpenDataException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.openmbean.OpenDataException
All Implemented Interfaces:
Serializable
public class OpenDataException
extends JMException

This checked exception is thrown when an open type, an open data or an open MBean metadata info instance could not be constructed because one or more validity constraints were not met.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
OpenDataException()
An OpenDataException with no detail message.
OpenDataException(String msg)
An OpenDataException with a detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

OpenDataException

public OpenDataException()
An OpenDataException with no detail message.

OpenDataException

public OpenDataException(String msg)
An OpenDataException with a detail message.

Parameters:
msg - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OpenMBeanAttributeInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Interface OpenMBeanAttributeInfo

All Superinterfaces:
OpenMBeanParameterInfo
All Known Implementing Classes:
OpenMBeanAttributeInfoSupport
public interface OpenMBeanAttributeInfo
extends OpenMBeanParameterInfo

Describes an attribute of an open MBean.

This interface declares the same methods as the class MBeanAttributeInfo. A class implementing this interface (typically OpenMBeanAttributeInfoSupport) should extend MBeanAttributeInfo.

Since:
1.5

Method Summary
boolean | equals(Object obj) Compares the specified obj parameter with this OpenMBeanAttributeInfo instance for equality.
int | hashCode() Returns the hash code value for this OpenMBeanAttributeInfo instance.
boolean | isIs() Returns true if the attribute described by this OpenMBeanAttributeInfo instance is accessed through a isXXX getter (applies only to boolean and Boolean values), false otherwise.
boolean | isReadable() Returns true if the attribute described by this OpenMBeanAttributeInfo instance is readable, false otherwise.
boolean | isWritable() Returns true if the attribute described by this OpenMBeanAttributeInfo instance is writable, false otherwise.
String | toString() Returns a string representation of this OpenMBeanAttributeInfo instance.
Methods inherited from interface javax.management.openmbean.OpenMBeanParameterInfo
getDefaultValue, getDescription, getLegalValues, getMaxValue, getMinValue, getName, getOpenType, hasDefaultValue, hasLegalValues, hasMaxValue, hasMinValue, isValue

Method Detail

isReadable

boolean isReadable()
Returns true if the attribute described by this OpenMBeanAttributeInfo instance is readable, false otherwise.

Returns:
true if the attribute is readable.

isWritable

boolean isWritable()
Returns true if the attribute described by this OpenMBeanAttributeInfo instance is writable, false otherwise.

Returns:
true if the attribute is writable.

isIs

boolean isIs()
Returns true if the attribute described by this OpenMBeanAttributeInfo instance is accessed through a isXXX getter (applies only to boolean and Boolean values), false otherwise.

Returns:
true if the attribute is accessed through isXXX.

equals

boolean equals(Object obj)
Compares the specified obj parameter with this OpenMBeanAttributeInfo instance for equality.

Returns true if and only if all of the following statements are true:

  • obj is non null,
  • obj also implements the OpenMBeanAttributeInfo interface,
  • their names are equal
  • their open types are equal
  • their access properties (isReadable, isWritable and isIs) are equal
  • their default, min, max and legal values are equal.
This ensures that this equals method works properly for obj parameters which are different implementations of the OpenMBeanAttributeInfo interface.

Specified by:
equals in interface OpenMBeanParameterInfo
Overrides:
equals in class Object
Parameters:
obj - the object to be compared for equality with this OpenMBeanAttributeInfo instance;
Returns:
true if the specified object is equal to this OpenMBeanAttributeInfo instance.
See Also:
Object.hashCode(), Hashtable

hashCode

int hashCode()
Returns the hash code value for this OpenMBeanAttributeInfo instance.

The hash code of an OpenMBeanAttributeInfo instance is the sum of the hash codes of all elements of information used in equals comparisons (ie: its name, its open type, and its default, min, max and legal values).

This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two OpenMBeanAttributeInfo instances t1 and t2, as required by the general contract of the method Object.hashCode().

Specified by:
hashCode in interface OpenMBeanParameterInfo
Overrides:
hashCode in class Object
Returns:
the hash code value for this OpenMBeanAttributeInfo instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

String toString()
Returns a string representation of this OpenMBeanAttributeInfo instance.

The string representation consists of the name of this class (ie javax.management.openmbean.OpenMBeanAttributeInfo), the string representation of the name and open type of the described attribute, and the string representation of its default, min, max and legal values.

Specified by:
toString in interface OpenMBeanParameterInfo
Overrides:
toString in class Object
Returns:
a string representation of this OpenMBeanAttributeInfo instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OpenMBeanAttributeInfoSupport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Class OpenMBeanAttributeInfoSupport

java.lang.Object
    extended by  javax.management.MBeanFeatureInfo
        extended by  javax.management.MBeanAttributeInfo
            extended by  javax.management.openmbean.OpenMBeanAttributeInfoSupport
All Implemented Interfaces:
Serializable, Cloneable, DescriptorRead, OpenMBeanAttributeInfo, OpenMBeanParameterInfo
public class OpenMBeanAttributeInfoSupport
extends MBeanAttributeInfo
implements OpenMBeanAttributeInfo

Describes an attribute of an open MBean.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.management.MBeanFeatureInfo
description, name
Constructor Summary
OpenMBeanAttributeInfoSupport(String name, String description, OpenType<?> openType, boolean isReadable, boolean isWritable, boolean isIs)
Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean with the specified name, openType and description, and the specified read/write access properties.
OpenMBeanAttributeInfoSupport(String name, String description, OpenType<?> openType, boolean isReadable, boolean isWritable, boolean isIs, Descriptor descriptor)
Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean with the specified name, openType, description, read/write access properties, and Descriptor.
OpenMBeanAttributeInfoSupport(String name, String description, OpenType<T> openType, boolean isReadable, boolean isWritable, boolean isIs, T defaultValue)
Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean with the specified name, openType, description and defaultValue, and the specified read/write access properties.
OpenMBeanAttributeInfoSupport(String name, String description, OpenType<T> openType, boolean isReadable, boolean isWritable, boolean isIs, T defaultValue, Comparable<T> minValue, Comparable<T> maxValue)
Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean, with the specified name, openType, description, defaultValue, minValue and maxValue.
OpenMBeanAttributeInfoSupport(String name, String description, OpenType<T> openType, boolean isReadable, boolean isWritable, boolean isIs, T defaultValue, T[] legalValues)
Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean with the specified name, openType, description, defaultValue and legalValues, and the specified read/write access properties.
Method Summary
boolean | equals(Object obj) Compares the specified obj parameter with this OpenMBeanAttributeInfoSupport instance for equality.
Object | getDefaultValue() Returns the default value for the attribute described by this OpenMBeanAttributeInfoSupport instance, if specified, or null otherwise.
Set<?> | getLegalValues() Returns an unmodifiable Set of legal values for the attribute described by this OpenMBeanAttributeInfoSupport instance, if specified, or null otherwise.
Comparable<?> | getMaxValue() Returns the maximal value for the attribute described by this OpenMBeanAttributeInfoSupport instance, if specified, or null otherwise.
Comparable<?> | getMinValue() Returns the minimal value for the attribute described by this OpenMBeanAttributeInfoSupport instance, if specified, or null otherwise.
OpenType<?> | getOpenType() Returns the open type for the values of the attribute described by this OpenMBeanAttributeInfoSupport instance.
boolean | hasDefaultValue() Returns true if this OpenMBeanAttributeInfoSupport instance specifies a non-null default value for the described attribute, false otherwise.
int | hashCode() Returns the hash code value for this OpenMBeanAttributeInfoSupport instance.
boolean | hasLegalValues() Returns true if this OpenMBeanAttributeInfoSupport instance specifies a non-null set of legal values for the described attribute, false otherwise.
boolean | hasMaxValue() Returns true if this OpenMBeanAttributeInfoSupport instance specifies a non-null maximal value for the described attribute, false otherwise.
boolean | hasMinValue() Returns true if this OpenMBeanAttributeInfoSupport instance specifies a non-null minimal value for the described attribute, false otherwise.
boolean | isValue(Object obj) Tests whether obj is a valid value for the attribute described by this OpenMBeanAttributeInfoSupport instance.
String | toString() Returns a string representation of this OpenMBeanAttributeInfoSupport instance.
Methods inherited from class javax.management.MBeanAttributeInfo
clone, getType, isIs, isReadable, isWritable
Methods inherited from class javax.management.MBeanFeatureInfo
getDescription, getDescriptor, getName
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface javax.management.openmbean.OpenMBeanAttributeInfo
isIs, isReadable, isWritable
Methods inherited from interface javax.management.openmbean.OpenMBeanParameterInfo
getDescription, getName

Constructor Detail

OpenMBeanAttributeInfoSupport

public OpenMBeanAttributeInfoSupport(String name,
                                     String description,
                                     OpenType<?> openType,
                                     boolean isReadable,
                                     boolean isWritable,
                                     boolean isIs)
Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean with the specified name, openType and description, and the specified read/write access properties.

Parameters:
name - cannot be a null or empty string.
description - cannot be a null or empty string.
openType - cannot be null.
isReadable - true if the attribute has a getter exposed for management.
isWritable - true if the attribute has a setter exposed for management.
isIs - true if the attribute's getter is of the form isXXX.
Throws:
IllegalArgumentException - if name or description are null or empty string, or openType is null.

OpenMBeanAttributeInfoSupport

public OpenMBeanAttributeInfoSupport(String name,
                                     String description,
                                     OpenType<?> openType,
                                     boolean isReadable,
                                     boolean isWritable,
                                     boolean isIs,
                                     Descriptor descriptor)

Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean with the specified name, openType, description, read/write access properties, and Descriptor.

The descriptor can contain entries that will define the values returned by certain methods of this class, as explained in the package description.

Parameters:
name - cannot be a null or empty string.
description - cannot be a null or empty string.
openType - cannot be null.
isReadable - true if the attribute has a getter exposed for management.
isWritable - true if the attribute has a setter exposed for management.
isIs - true if the attribute's getter is of the form isXXX.
descriptor - The descriptor for the attribute. This may be null which is equivalent to an empty descriptor.
Throws:
IllegalArgumentException - if name or description are null or empty string, or openType is null, or the descriptor entries are invalid as described in the package description.
Since:
1.6

OpenMBeanAttributeInfoSupport

public OpenMBeanAttributeInfoSupport(String name,
                                     String description,
                                     OpenType<T> openType,
                                     boolean isReadable,
                                     boolean isWritable,
                                     boolean isIs,
                                     T defaultValue)
                              throws OpenDataException
Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean with the specified name, openType, description and defaultValue, and the specified read/write access properties.

Type Parameters:
T - allows the compiler to check that the defaultValue, if non-null, has the correct Java type for the given openType.
Parameters:
name - cannot be a null or empty string.
description - cannot be a null or empty string.
openType - cannot be null.
isReadable - true if the attribute has a getter exposed for management.
isWritable - true if the attribute has a setter exposed for management.
isIs - true if the attribute's getter is of the form isXXX.
defaultValue - must be a valid value for the openType specified for this attribute; default value not supported for ArrayType and TabularType; can be null, in which case it means that no default value is set.
Throws:
IllegalArgumentException - if name or description are null or empty string, or openType is null.
OpenDataException - if defaultValue is not a valid value for the specified openType, or defaultValue is non null and openType is an ArrayType or a TabularType.

OpenMBeanAttributeInfoSupport

public OpenMBeanAttributeInfoSupport(String name,
                                     String description,
                                     OpenType<T> openType,
                                     boolean isReadable,
                                     boolean isWritable,
                                     boolean isIs,
                                     T defaultValue,
                                     T[] legalValues)
                              throws OpenDataException

Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean with the specified name, openType, description, defaultValue and legalValues, and the specified read/write access properties.

The contents of legalValues are copied, so subsequent modifications of the array referenced by legalValues have no impact on this OpenMBeanAttributeInfoSupport instance.

Type Parameters:
T - allows the compiler to check that the defaultValue and legalValues, if non-null, have the correct Java type for the given openType.
Parameters:
name - cannot be a null or empty string.
description - cannot be a null or empty string.
openType - cannot be null.
isReadable - true if the attribute has a getter exposed for management.
isWritable - true if the attribute has a setter exposed for management.
isIs - true if the attribute's getter is of the form isXXX.
defaultValue - must be a valid value for the openType specified for this attribute; default value not supported for ArrayType and TabularType; can be null, in which case it means that no default value is set.
legalValues - each contained value must be valid for the openType specified for this attribute; legal values not supported for ArrayType and TabularType; can be null or empty.
Throws:
IllegalArgumentException - if name or description are null or empty string, or openType is null.
OpenDataException - if defaultValue is not a valid value for the specified openType, or one value in legalValues is not valid for the specified openType, or defaultValue is non null and openType is an ArrayType or a TabularType, or legalValues is non null and non empty and openType is an ArrayType or a TabularType, or legalValues is non null and non empty and defaultValue is not contained in legalValues.

OpenMBeanAttributeInfoSupport

public OpenMBeanAttributeInfoSupport(String name,
                                     String description,
                                     OpenType<T> openType,
                                     boolean isReadable,
                                     boolean isWritable,
                                     boolean isIs,
                                     T defaultValue,
                                     Comparable<T> minValue,
                                     Comparable<T> maxValue)
                              throws OpenDataException
Constructs an OpenMBeanAttributeInfoSupport instance, which describes the attribute of an open MBean, with the specified name, openType, description, defaultValue, minValue and maxValue. It is possible to specify minimal and maximal values only for an open type whose values are Comparable.

Type Parameters:
T - allows the compiler to check that the defaultValue, minValue, and maxValue, if non-null, have the correct Java type for the given openType.
Parameters:
name - cannot be a null or empty string.
description - cannot be a null or empty string.
openType - cannot be null.
isReadable - true if the attribute has a getter exposed for management.
isWritable - true if the attribute has a setter exposed for management.
isIs - true if the attribute's getter is of the form isXXX.
defaultValue - must be a valid value for the openType specified for this attribute; default value not supported for ArrayType and TabularType; can be null, in which case it means that no default value is set.
minValue - must be valid for the openType specified for this attribute; can be null, in which case it means that no minimal value is set.
maxValue - must be valid for the openType specified for this attribute; can be null, in which case it means that no maximal value is set.
Throws:
IllegalArgumentException - if name or description are null or empty string, or openType is null.
OpenDataException - if defaultValue, minValue or maxValue is not a valid value for the specified openType, or defaultValue is non null and openType is an ArrayType or a TabularType, or both minValue and maxValue are non-null and minValue.compareTo(maxValue) > 0 is true, or both defaultValue and minValue are non-null and minValue.compareTo(defaultValue) > 0 is true, or both defaultValue and maxValue are non-null and defaultValue.compareTo(maxValue) > 0 is true.
Method Detail

getOpenType

public OpenType<?> getOpenType()
Returns the open type for the values of the attribute described by this OpenMBeanAttributeInfoSupport instance.

Specified by:
getOpenType in interface OpenMBeanParameterInfo
Returns:
the open type.

getDefaultValue

public Object getDefaultValue()
Returns the default value for the attribute described by this OpenMBeanAttributeInfoSupport instance, if specified, or null otherwise.

Specified by:
getDefaultValue in interface OpenMBeanParameterInfo
Returns:
the default value.

getLegalValues

public Set<?> getLegalValues()
Returns an unmodifiable Set of legal values for the attribute described by this OpenMBeanAttributeInfoSupport instance, if specified, or null otherwise.

Specified by:
getLegalValues in interface OpenMBeanParameterInfo
Returns:
the set of legal values.

getMinValue

public Comparable<?> getMinValue()
Returns the minimal value for the attribute described by this OpenMBeanAttributeInfoSupport instance, if specified, or null otherwise.

Specified by:
getMinValue in interface OpenMBeanParameterInfo
Returns:
the minimum value.

getMaxValue

public Comparable<?> getMaxValue()
Returns the maximal value for the attribute described by this OpenMBeanAttributeInfoSupport instance, if specified, or null otherwise.

Specified by:
getMaxValue in interface OpenMBeanParameterInfo
Returns:
the maximum value.

hasDefaultValue

public boolean hasDefaultValue()
Returns true if this OpenMBeanAttributeInfoSupport instance specifies a non-null default value for the described attribute, false otherwise.

Specified by:
hasDefaultValue in interface OpenMBeanParameterInfo
Returns:
true if there is a default value.

hasLegalValues

public boolean hasLegalValues()
Returns true if this OpenMBeanAttributeInfoSupport instance specifies a non-null set of legal values for the described attribute, false otherwise.

Specified by:
hasLegalValues in interface OpenMBeanParameterInfo
Returns:
true if there is a set of legal values.

hasMinValue

public boolean hasMinValue()
Returns true if this OpenMBeanAttributeInfoSupport instance specifies a non-null minimal value for the described attribute, false otherwise.

Specified by:
hasMinValue in interface OpenMBeanParameterInfo
Returns:
true if there is a minimum value.

hasMaxValue

public boolean hasMaxValue()
Returns true if this OpenMBeanAttributeInfoSupport instance specifies a non-null maximal value for the described attribute, false otherwise.

Specified by:
hasMaxValue in interface OpenMBeanParameterInfo
Returns:
true if there is a maximum value.

isValue

public boolean isValue(Object obj)
Tests whether obj is a valid value for the attribute described by this OpenMBeanAttributeInfoSupport instance.

Specified by:
isValue in interface OpenMBeanParameterInfo
Parameters:
obj - the object to be tested.
Returns:
true if obj is a valid value for the parameter described by this OpenMBeanAttributeInfoSupport instance, false otherwise.

equals

public boolean equals(Object obj)
Compares the specified obj parameter with this OpenMBeanAttributeInfoSupport instance for equality.

Returns true if and only if all of the following statements are true:

  • obj is non null,
  • obj also implements the OpenMBeanAttributeInfo interface,
  • their names are equal
  • their open types are equal
  • their access properties (isReadable, isWritable and isIs) are equal
  • their default, min, max and legal values are equal.
This ensures that this equals method works properly for obj parameters which are different implementations of the OpenMBeanAttributeInfo interface.

If obj also implements DescriptorRead, then its getDescriptor() method must also return the same value as for this object.

Specified by:
equals in interface OpenMBeanAttributeInfo
Specified by:
equals in interface OpenMBeanParameterInfo
Overrides:
equals in class MBeanAttributeInfo
Parameters:
obj - the object to be compared for equality with this OpenMBeanAttributeInfoSupport instance.
Returns:
true if the specified object is equal to this OpenMBeanAttributeInfoSupport instance.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()

Returns the hash code value for this OpenMBeanAttributeInfoSupport instance.

The hash code of an OpenMBeanAttributeInfoSupport instance is the sum of the hash codes of all elements of information used in equals comparisons (ie: its name, its open type, its default, min, max and legal values, and its Descriptor).

This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two OpenMBeanAttributeInfoSupport instances t1 and t2, as required by the general contract of the method Object.hashCode().

However, note that another instance of a class implementing the OpenMBeanAttributeInfo interface may be equal to this OpenMBeanAttributeInfoSupport instance as defined by equals(java.lang.Object), but may have a different hash code if it is calculated differently.

As OpenMBeanAttributeInfoSupport instances are immutable, the hash code for this instance is calculated once, on the first call to hashCode, and then the same value is returned for subsequent calls.

Specified by:
hashCode in interface OpenMBeanAttributeInfo
Specified by:
hashCode in interface OpenMBeanParameterInfo
Overrides:
hashCode in class MBeanAttributeInfo
Returns:
the hash code value for this OpenMBeanAttributeInfoSupport instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Returns a string representation of this OpenMBeanAttributeInfoSupport instance.

The string representation consists of the name of this class (i.e. javax.management.openmbean.OpenMBeanAttributeInfoSupport), the string representation of the name and open type of the described parameter, the string representation of its default, min, max and legal values and the string representation of its descriptor.

As OpenMBeanAttributeInfoSupport instances are immutable, the string representation for this instance is calculated once, on the first call to toString, and then the same value is returned for subsequent calls.

Specified by:
toString in interface OpenMBeanAttributeInfo
Specified by:
toString in interface OpenMBeanParameterInfo
Overrides:
toString in class MBeanAttributeInfo
Returns:
a string representation of this OpenMBeanAttributeInfoSupport instance.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OpenMBeanConstructorInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Interface OpenMBeanConstructorInfo

All Known Implementing Classes:
OpenMBeanConstructorInfoSupport
public interface OpenMBeanConstructorInfo

Describes a constructor of an Open MBean.

This interface declares the same methods as the class MBeanConstructorInfo. A class implementing this interface (typically OpenMBeanConstructorInfoSupport) should extend MBeanConstructorInfo.

The getSignature() method should return at runtime an array of instances of a subclass of MBeanParameterInfo which implements the OpenMBeanParameterInfo interface (typically OpenMBeanParameterInfoSupport).

Since:
1.5

Method Summary
boolean | equals(Object obj) Compares the specified obj parameter with this OpenMBeanConstructorInfo instance for equality.
String | getDescription() Returns a human readable description of the constructor described by this OpenMBeanConstructorInfo instance.
String | getName() Returns the name of the constructor described by this OpenMBeanConstructorInfo instance.
MBeanParameterInfo[] | getSignature() Returns an array of OpenMBeanParameterInfo instances describing each parameter in the signature of the constructor described by this OpenMBeanConstructorInfo instance.
int | hashCode() Returns the hash code value for this OpenMBeanConstructorInfo instance.
String | toString() Returns a string representation of this OpenMBeanConstructorInfo instance.

Method Detail

getDescription

String getDescription()
Returns a human readable description of the constructor described by this OpenMBeanConstructorInfo instance.

Returns:
the description.

getName

String getName()
Returns the name of the constructor described by this OpenMBeanConstructorInfo instance.

Returns:
the name.

getSignature

MBeanParameterInfo[] getSignature()
Returns an array of OpenMBeanParameterInfo instances describing each parameter in the signature of the constructor described by this OpenMBeanConstructorInfo instance.

Returns:
the signature.

equals

boolean equals(Object obj)
Compares the specified obj parameter with this OpenMBeanConstructorInfo instance for equality.

Returns true if and only if all of the following statements are true:

  • obj is non null,
  • obj also implements the OpenMBeanConstructorInfo interface,
  • their names are equal
  • their signatures are equal.
This ensures that this equals method works properly for obj parameters which are different implementations of the OpenMBeanConstructorInfo interface.

Overrides:
equals in class Object
Parameters:
obj - the object to be compared for equality with this OpenMBeanConstructorInfo instance;
Returns:
true if the specified object is equal to this OpenMBeanConstructorInfo instance.
See Also:
Object.hashCode(), Hashtable

hashCode

int hashCode()
Returns the hash code value for this OpenMBeanConstructorInfo instance.

The hash code of an OpenMBeanConstructorInfo instance is the sum of the hash codes of all elements of information used in equals comparisons (ie: its name and signature, where the signature hashCode is calculated by a call to java.util.Arrays.asList(this.getSignature).hashCode()).

This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two OpenMBeanConstructorInfo instances t1 and t2, as required by the general contract of the method Object.hashCode().

Overrides:
hashCode in class Object
Returns:
the hash code value for this OpenMBeanConstructorInfo instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

String toString()
Returns a string representation of this OpenMBeanConstructorInfo instance.

The string representation consists of the name of this class (ie javax.management.openmbean.OpenMBeanConstructorInfo), and the name and signature of the described constructor.

Overrides:
toString in class Object
Returns:
a string representation of this OpenMBeanConstructorInfo instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OpenMBeanConstructorInfoSupport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Class OpenMBeanConstructorInfoSupport

java.lang.Object
    extended by  javax.management.MBeanFeatureInfo
        extended by  javax.management.MBeanConstructorInfo
            extended by  javax.management.openmbean.OpenMBeanConstructorInfoSupport
All Implemented Interfaces:
Serializable, Cloneable, DescriptorRead, OpenMBeanConstructorInfo
public class OpenMBeanConstructorInfoSupport
extends MBeanConstructorInfo
implements OpenMBeanConstructorInfo

Describes a constructor of an Open MBean.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.management.MBeanFeatureInfo
description, name
Constructor Summary
OpenMBeanConstructorInfoSupport(String name, String description, OpenMBeanParameterInfo[] signature)
Constructs an OpenMBeanConstructorInfoSupport instance, which describes the constructor of a class of open MBeans with the specified name, description and signature.
OpenMBeanConstructorInfoSupport(String name, String description, OpenMBeanParameterInfo[] signature, Descriptor descriptor)
Constructs an OpenMBeanConstructorInfoSupport instance, which describes the constructor of a class of open MBeans with the specified name, description, signature, and descriptor.
Method Summary
boolean | equals(Object obj) Compares the specified obj parameter with this OpenMBeanConstructorInfoSupport instance for equality.
int | hashCode() Returns the hash code value for this OpenMBeanConstructorInfoSupport instance.
String | toString() Returns a string representation of this OpenMBeanConstructorInfoSupport instance.
Methods inherited from class javax.management.MBeanConstructorInfo
clone, getSignature
Methods inherited from class javax.management.MBeanFeatureInfo
getDescription, getDescriptor, getName
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface javax.management.openmbean.OpenMBeanConstructorInfo
getDescription, getName, getSignature

Constructor Detail

OpenMBeanConstructorInfoSupport

public OpenMBeanConstructorInfoSupport(String name,
                                       String description,
                                       OpenMBeanParameterInfo[] signature)

Constructs an OpenMBeanConstructorInfoSupport instance, which describes the constructor of a class of open MBeans with the specified name, description and signature.

The signature array parameter is internally copied, so that subsequent changes to the array referenced by signature have no effect on this instance.

Parameters:
name - cannot be a null or empty string.
description - cannot be a null or empty string.
signature - can be null or empty if there are no parameters to describe.
Throws:
IllegalArgumentException - if name or description are null or empty string.
ArrayStoreException - If signature is not an array of instances of a subclass of MBeanParameterInfo.

OpenMBeanConstructorInfoSupport

public OpenMBeanConstructorInfoSupport(String name,
                                       String description,
                                       OpenMBeanParameterInfo[] signature,
                                       Descriptor descriptor)

Constructs an OpenMBeanConstructorInfoSupport instance, which describes the constructor of a class of open MBeans with the specified name, description, signature, and descriptor.

The signature array parameter is internally copied, so that subsequent changes to the array referenced by signature have no effect on this instance.

Parameters:
name - cannot be a null or empty string.
description - cannot be a null or empty string.
signature - can be null or empty if there are no parameters to describe.
descriptor - The descriptor for the constructor. This may be null which is equivalent to an empty descriptor.
Throws:
IllegalArgumentException - if name or description are null or empty string.
ArrayStoreException - If signature is not an array of instances of a subclass of MBeanParameterInfo.
Since:
1.6
Method Detail

equals

public boolean equals(Object obj)

Compares the specified obj parameter with this OpenMBeanConstructorInfoSupport instance for equality.

Returns true if and only if all of the following statements are true:

  • obj is non null,
  • obj also implements the OpenMBeanConstructorInfo interface,
  • their names are equal
  • their signatures are equal.
This ensures that this equals method works properly for obj parameters which are different implementations of the OpenMBeanConstructorInfo interface.

Specified by:
equals in interface OpenMBeanConstructorInfo
Overrides:
equals in class MBeanConstructorInfo
Parameters:
obj - the object to be compared for equality with this OpenMBeanConstructorInfoSupport instance;
Returns:
true if the specified object is equal to this OpenMBeanConstructorInfoSupport instance.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()

Returns the hash code value for this OpenMBeanConstructorInfoSupport instance.

The hash code of an OpenMBeanConstructorInfoSupport instance is the sum of the hash codes of all elements of information used in equals comparisons (ie: its name and signature, where the signature hashCode is calculated by a call to java.util.Arrays.asList(this.getSignature).hashCode()).

This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two OpenMBeanConstructorInfoSupport instances t1 and t2, as required by the general contract of the method Object.hashCode().

However, note that another instance of a class implementing the OpenMBeanConstructorInfo interface may be equal to this OpenMBeanConstructorInfoSupport instance as defined by equals(java.lang.Object), but may have a different hash code if it is calculated differently.

As OpenMBeanConstructorInfoSupport instances are immutable, the hash code for this instance is calculated once, on the first call to hashCode, and then the same value is returned for subsequent calls.

Specified by:
hashCode in interface OpenMBeanConstructorInfo
Overrides:
hashCode in class MBeanConstructorInfo
Returns:
the hash code value for this OpenMBeanConstructorInfoSupport instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()

Returns a string representation of this OpenMBeanConstructorInfoSupport instance.

The string representation consists of the name of this class (ie javax.management.openmbean.OpenMBeanConstructorInfoSupport), the name and signature of the described constructor and the string representation of its descriptor.

As OpenMBeanConstructorInfoSupport instances are immutable, the string representation for this instance is calculated once, on the first call to toString, and then the same value is returned for subsequent calls.

Specified by:
toString in interface OpenMBeanConstructorInfo
Overrides:
toString in class MBeanConstructorInfo
Returns:
a string representation of this OpenMBeanConstructorInfoSupport instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OpenMBeanInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Interface OpenMBeanInfo

All Known Implementing Classes:
OpenMBeanInfoSupport
public interface OpenMBeanInfo

Describes an Open MBean: an Open MBean is recognized as such if its getMBeanInfo() method returns an instance of a class which implements the OpenMBeanInfo interface, typically OpenMBeanInfoSupport.

This interface declares the same methods as the class MBeanInfo. A class implementing this interface (typically OpenMBeanInfoSupport) should extend MBeanInfo.

The getAttributes(), getOperations() and getConstructors() methods of the implementing class should return at runtime an array of instances of a subclass of MBeanAttributeInfo, MBeanOperationInfo or MBeanConstructorInfo respectively which implement the OpenMBeanAttributeInfo, OpenMBeanOperationInfo or OpenMBeanConstructorInfo interface respectively.

Since:
1.5

Method Summary
boolean | equals(Object obj) Compares the specified obj parameter with this OpenMBeanInfo instance for equality.
MBeanAttributeInfo[] | getAttributes() Returns an array of OpenMBeanAttributeInfo instances describing each attribute in the open MBean described by this OpenMBeanInfo instance.
String | getClassName() Returns the fully qualified Java class name of the open MBean instances this OpenMBeanInfo describes.
MBeanConstructorInfo[] | getConstructors() Returns an array of OpenMBeanConstructorInfo instances describing each constructor in the open MBean described by this OpenMBeanInfo instance.
String | getDescription() Returns a human readable description of the type of open MBean instances this OpenMBeanInfo describes.
MBeanNotificationInfo[] | getNotifications() Returns an array of MBeanNotificationInfo instances describing each notification emitted by the open MBean described by this OpenMBeanInfo instance.
MBeanOperationInfo[] | getOperations() Returns an array of OpenMBeanOperationInfo instances describing each operation in the open MBean described by this OpenMBeanInfo instance.
int | hashCode() Returns the hash code value for this OpenMBeanInfo instance.
String | toString() Returns a string representation of this OpenMBeanInfo instance.

Method Detail

getClassName

String getClassName()
Returns the fully qualified Java class name of the open MBean instances this OpenMBeanInfo describes.

Returns:
the class name.

getDescription

String getDescription()
Returns a human readable description of the type of open MBean instances this OpenMBeanInfo describes.

Returns:
the description.

getAttributes

MBeanAttributeInfo[] getAttributes()
Returns an array of OpenMBeanAttributeInfo instances describing each attribute in the open MBean described by this OpenMBeanInfo instance. Each instance in the returned array should actually be a subclass of MBeanAttributeInfo which implements the OpenMBeanAttributeInfo interface (typically OpenMBeanAttributeInfoSupport).

Returns:
the attribute array.

getOperations

MBeanOperationInfo[] getOperations()
Returns an array of OpenMBeanOperationInfo instances describing each operation in the open MBean described by this OpenMBeanInfo instance. Each instance in the returned array should actually be a subclass of MBeanOperationInfo which implements the OpenMBeanOperationInfo interface (typically OpenMBeanOperationInfoSupport).

Returns:
the operation array.

getConstructors

MBeanConstructorInfo[] getConstructors()
Returns an array of OpenMBeanConstructorInfo instances describing each constructor in the open MBean described by this OpenMBeanInfo instance. Each instance in the returned array should actually be a subclass of MBeanConstructorInfo which implements the OpenMBeanConstructorInfo interface (typically OpenMBeanConstructorInfoSupport).

Returns:
the constructor array.

getNotifications

MBeanNotificationInfo[] getNotifications()
Returns an array of MBeanNotificationInfo instances describing each notification emitted by the open MBean described by this OpenMBeanInfo instance.

Returns:
the notification array.

equals

boolean equals(Object obj)
Compares the specified obj parameter with this OpenMBeanInfo instance for equality.

Returns true if and only if all of the following statements are true:

  • obj is non null,
  • obj also implements the OpenMBeanInfo interface,
  • their class names are equal
  • their infos on attributes, constructors, operations and notifications are equal
This ensures that this equals method works properly for obj parameters which are different implementations of the OpenMBeanInfo interface.

Overrides:
equals in class Object
Parameters:
obj - the object to be compared for equality with this OpenMBeanInfo instance;
Returns:
true if the specified object is equal to this OpenMBeanInfo instance.
See Also:
Object.hashCode(), Hashtable

hashCode

int hashCode()
Returns the hash code value for this OpenMBeanInfo instance.

The hash code of an OpenMBeanInfo instance is the sum of the hash codes of all elements of information used in equals comparisons (ie: its class name, and its infos on attributes, constructors, operations and notifications, where the hashCode of each of these arrays is calculated by a call to new java.util.HashSet(java.util.Arrays.asList(this.getSignature)).hashCode()).

This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two OpenMBeanInfo instances t1 and t2, as required by the general contract of the method Object.hashCode().

Overrides:
hashCode in class Object
Returns:
the hash code value for this OpenMBeanInfo instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

String toString()
Returns a string representation of this OpenMBeanInfo instance.

The string representation consists of the name of this class (ie javax.management.openmbean.OpenMBeanInfo), the MBean class name, and the string representation of infos on attributes, constructors, operations and notifications of the described MBean.

Overrides:
toString in class Object
Returns:
a string representation of this OpenMBeanInfo instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OpenMBeanInfoSupport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Class OpenMBeanInfoSupport

java.lang.Object
    extended by  javax.management.MBeanInfo
        extended by  javax.management.openmbean.OpenMBeanInfoSupport
All Implemented Interfaces:
Serializable, Cloneable, DescriptorRead, OpenMBeanInfo
public class OpenMBeanInfoSupport
extends MBeanInfo
implements OpenMBeanInfo

The OpenMBeanInfoSupport class describes the management information of an open MBean: it is a subclass of MBeanInfo, and it implements the OpenMBeanInfo interface. Note that an open MBean is recognized as such if its getMBeanInfo() method returns an instance of a class which implements the OpenMBeanInfo interface, typically OpenMBeanInfoSupport.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
OpenMBeanInfoSupport(String className, String description, OpenMBeanAttributeInfo[] openAttributes, OpenMBeanConstructorInfo[] openConstructors, OpenMBeanOperationInfo[] openOperations, MBeanNotificationInfo[] notifications)
Constructs an OpenMBeanInfoSupport instance, which describes a class of open MBeans with the specified className, description, openAttributes, openConstructors , openOperations and notifications.
OpenMBeanInfoSupport(String className, String description, OpenMBeanAttributeInfo[] openAttributes, OpenMBeanConstructorInfo[] openConstructors, OpenMBeanOperationInfo[] openOperations, MBeanNotificationInfo[] notifications, Descriptor descriptor)
Constructs an OpenMBeanInfoSupport instance, which describes a class of open MBeans with the specified className, description, openAttributes, openConstructors , openOperations, notifications, and descriptor.
Method Summary
boolean | equals(Object obj) Compares the specified obj parameter with this OpenMBeanInfoSupport instance for equality.
int | hashCode() Returns the hash code value for this OpenMBeanInfoSupport instance.
String | toString() Returns a string representation of this OpenMBeanInfoSupport instance.
Methods inherited from class javax.management.MBeanInfo
clone, getAttributes, getClassName, getConstructors, getDescription, getDescriptor, getNotifications, getOperations
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface javax.management.openmbean.OpenMBeanInfo
getAttributes, getClassName, getConstructors, getDescription, getNotifications, getOperations

Constructor Detail

OpenMBeanInfoSupport

public OpenMBeanInfoSupport(String className,
                            String description,
                            OpenMBeanAttributeInfo[] openAttributes,
                            OpenMBeanConstructorInfo[] openConstructors,
                            OpenMBeanOperationInfo[] openOperations,
                            MBeanNotificationInfo[] notifications)

Constructs an OpenMBeanInfoSupport instance, which describes a class of open MBeans with the specified className, description, openAttributes, openConstructors , openOperations and notifications.

The openAttributes, openConstructors, openOperations and notifications array parameters are internally copied, so that subsequent changes to the arrays referenced by these parameters have no effect on this instance.

Parameters:
className - The fully qualified Java class name of the open MBean described by this OpenMBeanInfoSupport instance.
description - A human readable description of the open MBean described by this OpenMBeanInfoSupport instance.
openAttributes - The list of exposed attributes of the described open MBean; Must be an array of instances of a subclass of MBeanAttributeInfo, typically OpenMBeanAttributeInfoSupport.
openConstructors - The list of exposed public constructors of the described open MBean; Must be an array of instances of a subclass of MBeanConstructorInfo, typically OpenMBeanConstructorInfoSupport.
openOperations - The list of exposed operations of the described open MBean. Must be an array of instances of a subclass of MBeanOperationInfo, typically OpenMBeanOperationInfoSupport.
notifications - The list of notifications emitted by the described open MBean.
Throws:
ArrayStoreException - If openAttributes, openConstructors or openOperations is not an array of instances of a subclass of MBeanAttributeInfo, MBeanConstructorInfo or MBeanOperationInfo respectively.

OpenMBeanInfoSupport

public OpenMBeanInfoSupport(String className,
                            String description,
                            OpenMBeanAttributeInfo[] openAttributes,
                            OpenMBeanConstructorInfo[] openConstructors,
                            OpenMBeanOperationInfo[] openOperations,
                            MBeanNotificationInfo[] notifications,
                            Descriptor descriptor)

Constructs an OpenMBeanInfoSupport instance, which describes a class of open MBeans with the specified className, description, openAttributes, openConstructors , openOperations, notifications, and descriptor.

The openAttributes, openConstructors, openOperations and notifications array parameters are internally copied, so that subsequent changes to the arrays referenced by these parameters have no effect on this instance.

Parameters:
className - The fully qualified Java class name of the open MBean described by this OpenMBeanInfoSupport instance.
description - A human readable description of the open MBean described by this OpenMBeanInfoSupport instance.
openAttributes - The list of exposed attributes of the described open MBean; Must be an array of instances of a subclass of MBeanAttributeInfo, typically OpenMBeanAttributeInfoSupport.
openConstructors - The list of exposed public constructors of the described open MBean; Must be an array of instances of a subclass of MBeanConstructorInfo, typically OpenMBeanConstructorInfoSupport.
openOperations - The list of exposed operations of the described open MBean. Must be an array of instances of a subclass of MBeanOperationInfo, typically OpenMBeanOperationInfoSupport.
notifications - The list of notifications emitted by the described open MBean.
descriptor - The descriptor for the MBean. This may be null which is equivalent to an empty descriptor.
Throws:
ArrayStoreException - If openAttributes, openConstructors or openOperations is not an array of instances of a subclass of MBeanAttributeInfo, MBeanConstructorInfo or MBeanOperationInfo respectively.
Since:
1.6
Method Detail

equals

public boolean equals(Object obj)

Compares the specified obj parameter with this OpenMBeanInfoSupport instance for equality.

Returns true if and only if all of the following statements are true:

  • obj is non null,
  • obj also implements the OpenMBeanInfo interface,
  • their class names are equal
  • their infos on attributes, constructors, operations and notifications are equal
This ensures that this equals method works properly for obj parameters which are different implementations of the OpenMBeanInfo interface.

Specified by:
equals in interface OpenMBeanInfo
Overrides:
equals in class MBeanInfo
Parameters:
obj - the object to be compared for equality with this OpenMBeanInfoSupport instance;
Returns:
true if the specified object is equal to this OpenMBeanInfoSupport instance.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()

Returns the hash code value for this OpenMBeanInfoSupport instance.

The hash code of an OpenMBeanInfoSupport instance is the sum of the hash codes of all elements of information used in equals comparisons (ie: its class name, and its infos on attributes, constructors, operations and notifications, where the hashCode of each of these arrays is calculated by a call to new java.util.HashSet(java.util.Arrays.asList(this.getSignature)).hashCode()).

This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two OpenMBeanInfoSupport instances t1 and t2, as required by the general contract of the method Object.hashCode().

However, note that another instance of a class implementing the OpenMBeanInfo interface may be equal to this OpenMBeanInfoSupport instance as defined by equals(java.lang.Object), but may have a different hash code if it is calculated differently.

As OpenMBeanInfoSupport instances are immutable, the hash code for this instance is calculated once, on the first call to hashCode, and then the same value is returned for subsequent calls.

Specified by:
hashCode in interface OpenMBeanInfo
Overrides:
hashCode in class MBeanInfo
Returns:
the hash code value for this OpenMBeanInfoSupport instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()

Returns a string representation of this OpenMBeanInfoSupport instance.

The string representation consists of the name of this class (ie javax.management.openmbean.OpenMBeanInfoSupport), the MBean class name, the string representation of infos on attributes, constructors, operations and notifications of the described MBean and the string representation of the descriptor.

As OpenMBeanInfoSupport instances are immutable, the string representation for this instance is calculated once, on the first call to toString, and then the same value is returned for subsequent calls.

Specified by:
toString in interface OpenMBeanInfo
Overrides:
toString in class MBeanInfo
Returns:
a string representation of this OpenMBeanInfoSupport instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OpenMBeanOperationInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Interface OpenMBeanOperationInfo

All Known Implementing Classes:
OpenMBeanOperationInfoSupport
public interface OpenMBeanOperationInfo

Describes an operation of an Open MBean.

This interface declares the same methods as the class MBeanOperationInfo. A class implementing this interface (typically OpenMBeanOperationInfoSupport) should extend MBeanOperationInfo.

The getSignature() method should return at runtime an array of instances of a subclass of MBeanParameterInfo which implements the OpenMBeanParameterInfo interface (typically OpenMBeanParameterInfoSupport).

Since:
1.5

Method Summary
boolean | equals(Object obj) Compares the specified obj parameter with this OpenMBeanOperationInfo instance for equality.
String | getDescription() Returns a human readable description of the operation described by this OpenMBeanOperationInfo instance.
int | getImpact() Returns an int constant qualifying the impact of the operation described by this OpenMBeanOperationInfo instance.
String | getName() Returns the name of the operation described by this OpenMBeanOperationInfo instance.
OpenType<?> | getReturnOpenType() Returns the open type of the values returned by the operation described by this OpenMBeanOperationInfo instance.
String | getReturnType() Returns the fully qualified Java class name of the values returned by the operation described by this OpenMBeanOperationInfo instance.
MBeanParameterInfo[] | getSignature() Returns an array of OpenMBeanParameterInfo instances describing each parameter in the signature of the operation described by this OpenMBeanOperationInfo instance.
int | hashCode() Returns the hash code value for this OpenMBeanOperationInfo instance.
String | toString() Returns a string representation of this OpenMBeanOperationInfo instance.

Method Detail

getDescription

String getDescription()
Returns a human readable description of the operation described by this OpenMBeanOperationInfo instance.

Returns:
the description.

getName

String getName()
Returns the name of the operation described by this OpenMBeanOperationInfo instance.

Returns:
the name.

getSignature

MBeanParameterInfo[] getSignature()
Returns an array of OpenMBeanParameterInfo instances describing each parameter in the signature of the operation described by this OpenMBeanOperationInfo instance. Each instance in the returned array should actually be a subclass of MBeanParameterInfo which implements the OpenMBeanParameterInfo interface (typically OpenMBeanParameterInfoSupport).

Returns:
the signature.

getImpact

int getImpact()
Returns an int constant qualifying the impact of the operation described by this OpenMBeanOperationInfo instance. The returned constant is one of MBeanOperationInfo.INFO, MBeanOperationInfo.ACTION, MBeanOperationInfo.ACTION_INFO, or MBeanOperationInfo.UNKNOWN.

Returns:
the impact code.

getReturnType

String getReturnType()
Returns the fully qualified Java class name of the values returned by the operation described by this OpenMBeanOperationInfo instance. This method should return the same value as a call to getReturnOpenType().getClassName().

Returns:
the return type.

getReturnOpenType

OpenType<?> getReturnOpenType()
Returns the open type of the values returned by the operation described by this OpenMBeanOperationInfo instance.

Returns:
the return type.

equals

boolean equals(Object obj)
Compares the specified obj parameter with this OpenMBeanOperationInfo instance for equality.

Returns true if and only if all of the following statements are true:

  • obj is non null,
  • obj also implements the OpenMBeanOperationInfo interface,
  • their names are equal
  • their signatures are equal
  • their return open types are equal
  • their impacts are equal
This ensures that this equals method works properly for obj parameters which are different implementations of the OpenMBeanOperationInfo interface.

Overrides:
equals in class Object
Parameters:
obj - the object to be compared for equality with this OpenMBeanOperationInfo instance;
Returns:
true if the specified object is equal to this OpenMBeanOperationInfo instance.
See Also:
Object.hashCode(), Hashtable

hashCode

int hashCode()
Returns the hash code value for this OpenMBeanOperationInfo instance.

The hash code of an OpenMBeanOperationInfo instance is the sum of the hash codes of all elements of information used in equals comparisons (ie: its name, return open type, impact and signature, where the signature hashCode is calculated by a call to java.util.Arrays.asList(this.getSignature).hashCode()).

This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two OpenMBeanOperationInfo instances t1 and t2, as required by the general contract of the method Object.hashCode().

Overrides:
hashCode in class Object
Returns:
the hash code value for this OpenMBeanOperationInfo instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

String toString()
Returns a string representation of this OpenMBeanOperationInfo instance.

The string representation consists of the name of this class (ie javax.management.openmbean.OpenMBeanOperationInfo), and the name, signature, return open type and impact of the described operation.

Overrides:
toString in class Object
Returns:
a string representation of this OpenMBeanOperationInfo instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OpenMBeanOperationInfoSupport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Class OpenMBeanOperationInfoSupport

java.lang.Object
    extended by  javax.management.MBeanFeatureInfo
        extended by  javax.management.MBeanOperationInfo
            extended by  javax.management.openmbean.OpenMBeanOperationInfoSupport
All Implemented Interfaces:
Serializable, Cloneable, DescriptorRead, OpenMBeanOperationInfo
public class OpenMBeanOperationInfoSupport
extends MBeanOperationInfo
implements OpenMBeanOperationInfo

Describes an operation of an Open MBean.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.management.MBeanOperationInfo
ACTION, ACTION_INFO, INFO, UNKNOWN
Fields inherited from class javax.management.MBeanFeatureInfo
description, name
Constructor Summary
OpenMBeanOperationInfoSupport(String name, String description, OpenMBeanParameterInfo[] signature, OpenType<?> returnOpenType, int impact)
Constructs an OpenMBeanOperationInfoSupport instance, which describes the operation of a class of open MBeans, with the specified name, description, signature, returnOpenType and impact.
OpenMBeanOperationInfoSupport(String name, String description, OpenMBeanParameterInfo[] signature, OpenType<?> returnOpenType, int impact, Descriptor descriptor)
Constructs an OpenMBeanOperationInfoSupport instance, which describes the operation of a class of open MBeans, with the specified name, description, signature, returnOpenType, impact, and descriptor.
Method Summary
boolean | equals(Object obj) Compares the specified obj parameter with this OpenMBeanOperationInfoSupport instance for equality.
OpenType<?> | getReturnOpenType() Returns the open type of the values returned by the operation described by this OpenMBeanOperationInfo instance.
int | hashCode() Returns the hash code value for this OpenMBeanOperationInfoSupport instance.
String | toString() Returns a string representation of this OpenMBeanOperationInfoSupport instance.
Methods inherited from class javax.management.MBeanOperationInfo
clone, getImpact, getReturnType, getSignature
Methods inherited from class javax.management.MBeanFeatureInfo
getDescription, getDescriptor, getName
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface javax.management.openmbean.OpenMBeanOperationInfo
getDescription, getImpact, getName, getReturnType, getSignature

Constructor Detail

OpenMBeanOperationInfoSupport

public OpenMBeanOperationInfoSupport(String name,
                                     String description,
                                     OpenMBeanParameterInfo[] signature,
                                     OpenType<?> returnOpenType,
                                     int impact)

Constructs an OpenMBeanOperationInfoSupport instance, which describes the operation of a class of open MBeans, with the specified name, description, signature, returnOpenType and impact.

The signature array parameter is internally copied, so that subsequent changes to the array referenced by signature have no effect on this instance.

Parameters:
name - cannot be a null or empty string.
description - cannot be a null or empty string.
signature - can be null or empty if there are no parameters to describe.
returnOpenType - cannot be null: use SimpleType.VOID for operations that return nothing.
impact - must be one of ACTION, ACTION_INFO, INFO, or UNKNOWN.
Throws:
IllegalArgumentException - if name or description are null or empty string, or returnOpenType is null, or impact is not one of ACTION, ACTION_INFO, INFO, or UNKNOWN.
ArrayStoreException - If signature is not an array of instances of a subclass of MBeanParameterInfo.

OpenMBeanOperationInfoSupport

public OpenMBeanOperationInfoSupport(String name,
                                     String description,
                                     OpenMBeanParameterInfo[] signature,
                                     OpenType<?> returnOpenType,
                                     int impact,
                                     Descriptor descriptor)

Constructs an OpenMBeanOperationInfoSupport instance, which describes the operation of a class of open MBeans, with the specified name, description, signature, returnOpenType, impact, and descriptor.

The signature array parameter is internally copied, so that subsequent changes to the array referenced by signature have no effect on this instance.

Parameters:
name - cannot be a null or empty string.
description - cannot be a null or empty string.
signature - can be null or empty if there are no parameters to describe.
returnOpenType - cannot be null: use SimpleType.VOID for operations that return nothing.
impact - must be one of ACTION, ACTION_INFO, INFO, or UNKNOWN.
descriptor - The descriptor for the operation. This may be null, which is equivalent to an empty descriptor.
Throws:
IllegalArgumentException - if name or description are null or empty string, or returnOpenType is null, or impact is not one of ACTION, ACTION_INFO, INFO, or UNKNOWN.
ArrayStoreException - If signature is not an array of instances of a subclass of MBeanParameterInfo.
Since:
1.6
Method Detail

getReturnOpenType

public OpenType<?> getReturnOpenType()
Returns the open type of the values returned by the operation described by this OpenMBeanOperationInfo instance.

Specified by:
getReturnOpenType in interface OpenMBeanOperationInfo
Returns:
the return type.

equals

public boolean equals(Object obj)

Compares the specified obj parameter with this OpenMBeanOperationInfoSupport instance for equality.

Returns true if and only if all of the following statements are true:

  • obj is non null,
  • obj also implements the OpenMBeanOperationInfo interface,
  • their names are equal
  • their signatures are equal
  • their return open types are equal
  • their impacts are equal
This ensures that this equals method works properly for obj parameters which are different implementations of the OpenMBeanOperationInfo interface.

Specified by:
equals in interface OpenMBeanOperationInfo
Overrides:
equals in class MBeanOperationInfo
Parameters:
obj - the object to be compared for equality with this OpenMBeanOperationInfoSupport instance;
Returns:
true if the specified object is equal to this OpenMBeanOperationInfoSupport instance.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()

Returns the hash code value for this OpenMBeanOperationInfoSupport instance.

The hash code of an OpenMBeanOperationInfoSupport instance is the sum of the hash codes of all elements of information used in equals comparisons (ie: its name, return open type, impact and signature, where the signature hashCode is calculated by a call to java.util.Arrays.asList(this.getSignature).hashCode()).

This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two OpenMBeanOperationInfoSupport instances t1 and t2, as required by the general contract of the method Object.hashCode().

However, note that another instance of a class implementing the OpenMBeanOperationInfo interface may be equal to this OpenMBeanOperationInfoSupport instance as defined by equals(java.lang.Object), but may have a different hash code if it is calculated differently.

As OpenMBeanOperationInfoSupport instances are immutable, the hash code for this instance is calculated once, on the first call to hashCode, and then the same value is returned for subsequent calls.

Specified by:
hashCode in interface OpenMBeanOperationInfo
Overrides:
hashCode in class MBeanOperationInfo
Returns:
the hash code value for this OpenMBeanOperationInfoSupport instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()

Returns a string representation of this OpenMBeanOperationInfoSupport instance.

The string representation consists of the name of this class (ie javax.management.openmbean.OpenMBeanOperationInfoSupport), and the name, signature, return open type and impact of the described operation and the string representation of its descriptor.

As OpenMBeanOperationInfoSupport instances are immutable, the string representation for this instance is calculated once, on the first call to toString, and then the same value is returned for subsequent calls.

Specified by:
toString in interface OpenMBeanOperationInfo
Overrides:
toString in class MBeanOperationInfo
Returns:
a string representation of this OpenMBeanOperationInfoSupport instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OpenMBeanParameterInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Interface OpenMBeanParameterInfo

All Known Subinterfaces:
OpenMBeanAttributeInfo
All Known Implementing Classes:
OpenMBeanAttributeInfoSupport, OpenMBeanParameterInfoSupport
public interface OpenMBeanParameterInfo

Describes a parameter used in one or more operations or constructors of an open MBean.

This interface declares the same methods as the class MBeanParameterInfo. A class implementing this interface (typically OpenMBeanParameterInfoSupport) should extend MBeanParameterInfo.

Since:
1.5

Method Summary
boolean | equals(Object obj) Compares the specified obj parameter with this OpenMBeanParameterInfo instance for equality.
Object | getDefaultValue() Returns the default value for this parameter, if it has one, or null otherwise.
String | getDescription() Returns a human readable description of the parameter described by this OpenMBeanParameterInfo instance.
Set<?> | getLegalValues() Returns the set of legal values for this parameter, if it has one, or null otherwise.
Comparable<?> | getMaxValue() Returns the maximal value for this parameter, if it has one, or null otherwise.
Comparable<?> | getMinValue() Returns the minimal value for this parameter, if it has one, or null otherwise.
String | getName() Returns the name of the parameter described by this OpenMBeanParameterInfo instance.
OpenType<?> | getOpenType() Returns the open type of the values of the parameter described by this OpenMBeanParameterInfo instance.
boolean | hasDefaultValue() Returns true if this parameter has a specified default value, or false otherwise.
int | hashCode() Returns the hash code value for this OpenMBeanParameterInfo instance.
boolean | hasLegalValues() Returns true if this parameter has a specified set of legal values, or false otherwise.
boolean | hasMaxValue() Returns true if this parameter has a specified maximal value, or false otherwise.
boolean | hasMinValue() Returns true if this parameter has a specified minimal value, or false otherwise.
boolean | isValue(Object obj) Tests whether obj is a valid value for the parameter described by this OpenMBeanParameterInfo instance.
String | toString() Returns a string representation of this OpenMBeanParameterInfo instance.

Method Detail

getDescription

String getDescription()
Returns a human readable description of the parameter described by this OpenMBeanParameterInfo instance.

Returns:
the description.

getName

String getName()
Returns the name of the parameter described by this OpenMBeanParameterInfo instance.

Returns:
the name.

getOpenType

OpenType<?> getOpenType()
Returns the open type of the values of the parameter described by this OpenMBeanParameterInfo instance.

Returns:
the open type.

getDefaultValue

Object getDefaultValue()
Returns the default value for this parameter, if it has one, or null otherwise.

Returns:
the default value.

getLegalValues

Set<?> getLegalValues()
Returns the set of legal values for this parameter, if it has one, or null otherwise.

Returns:
the set of legal values.

getMinValue

Comparable<?> getMinValue()
Returns the minimal value for this parameter, if it has one, or null otherwise.

Returns:
the minimum value.

getMaxValue

Comparable<?> getMaxValue()
Returns the maximal value for this parameter, if it has one, or null otherwise.

Returns:
the maximum value.

hasDefaultValue

boolean hasDefaultValue()
Returns true if this parameter has a specified default value, or false otherwise.

Returns:
true if there is a default value.

hasLegalValues

boolean hasLegalValues()
Returns true if this parameter has a specified set of legal values, or false otherwise.

Returns:
true if there is a set of legal values.

hasMinValue

boolean hasMinValue()
Returns true if this parameter has a specified minimal value, or false otherwise.

Returns:
true if there is a minimum value.

hasMaxValue

boolean hasMaxValue()
Returns true if this parameter has a specified maximal value, or false otherwise.

Returns:
true if there is a maximum value.

isValue

boolean isValue(Object obj)
Tests whether obj is a valid value for the parameter described by this OpenMBeanParameterInfo instance.

Parameters:
obj - the object to be tested.
Returns:
true if obj is a valid value for the parameter described by this OpenMBeanParameterInfo instance, false otherwise.

equals

boolean equals(Object obj)
Compares the specified obj parameter with this OpenMBeanParameterInfo instance for equality.

Returns true if and only if all of the following statements are true:

  • obj is non null,
  • obj also implements the OpenMBeanParameterInfo interface,
  • their names are equal
  • their open types are equal
  • their default, min, max and legal values are equal.
This ensures that this equals method works properly for obj parameters which are different implementations of the OpenMBeanParameterInfo interface.

Overrides:
equals in class Object
Parameters:
obj - the object to be compared for equality with this OpenMBeanParameterInfo instance;
Returns:
true if the specified object is equal to this OpenMBeanParameterInfo instance.
See Also:
Object.hashCode(), Hashtable

hashCode

int hashCode()
Returns the hash code value for this OpenMBeanParameterInfo instance.

The hash code of an OpenMBeanParameterInfo instance is the sum of the hash codes of all elements of information used in equals comparisons (ie: its name, its open type, and its default, min, max and legal values).

This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two OpenMBeanParameterInfo instances t1 and t2, as required by the general contract of the method Object.hashCode().

Overrides:
hashCode in class Object
Returns:
the hash code value for this OpenMBeanParameterInfo instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

String toString()
Returns a string representation of this OpenMBeanParameterInfo instance.

The string representation consists of the name of this class (ie javax.management.openmbean.OpenMBeanParameterInfo), the string representation of the name and open type of the described parameter, and the string representation of its default, min, max and legal values.

Overrides:
toString in class Object
Returns:
a string representation of this OpenMBeanParameterInfo instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OpenMBeanParameterInfoSupport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Class OpenMBeanParameterInfoSupport

java.lang.Object
    extended by  javax.management.MBeanFeatureInfo
        extended by  javax.management.MBeanParameterInfo
            extended by  javax.management.openmbean.OpenMBeanParameterInfoSupport
All Implemented Interfaces:
Serializable, Cloneable, DescriptorRead, OpenMBeanParameterInfo
public class OpenMBeanParameterInfoSupport
extends MBeanParameterInfo
implements OpenMBeanParameterInfo

Describes a parameter used in one or more operations or constructors of an open MBean.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.management.MBeanFeatureInfo
description, name
Constructor Summary
OpenMBeanParameterInfoSupport(String name, String description, OpenType<?> openType)
Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType and description.
OpenMBeanParameterInfoSupport(String name, String description, OpenType<?> openType, Descriptor descriptor)
Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType, description, and descriptor.
OpenMBeanParameterInfoSupport(String name, String description, OpenType<T> openType, T defaultValue)
Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType, description and defaultValue.
OpenMBeanParameterInfoSupport(String name, String description, OpenType<T> openType, T defaultValue, Comparable<T> minValue, Comparable<T> maxValue)
Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType, description, defaultValue, minValue and maxValue.
OpenMBeanParameterInfoSupport(String name, String description, OpenType<T> openType, T defaultValue, T[] legalValues)
Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType, description, defaultValue and legalValues.
Method Summary
boolean | equals(Object obj) Compares the specified obj parameter with this OpenMBeanParameterInfoSupport instance for equality.
Object | getDefaultValue() Returns the default value for the parameter described by this OpenMBeanParameterInfoSupport instance, if specified, or null otherwise.
Set<?> | getLegalValues() Returns an unmodifiable Set of legal values for the parameter described by this OpenMBeanParameterInfoSupport instance, if specified, or null otherwise.
Comparable<?> | getMaxValue() Returns the maximal value for the parameter described by this OpenMBeanParameterInfoSupport instance, if specified, or null otherwise.
Comparable<?> | getMinValue() Returns the minimal value for the parameter described by this OpenMBeanParameterInfoSupport instance, if specified, or null otherwise.
OpenType<?> | getOpenType() Returns the open type for the values of the parameter described by this OpenMBeanParameterInfoSupport instance.
boolean | hasDefaultValue() Returns true if this OpenMBeanParameterInfoSupport instance specifies a non-null default value for the described parameter, false otherwise.
int | hashCode() Returns the hash code value for this OpenMBeanParameterInfoSupport instance.
boolean | hasLegalValues() Returns true if this OpenMBeanParameterInfoSupport instance specifies a non-null set of legal values for the described parameter, false otherwise.
boolean | hasMaxValue() Returns true if this OpenMBeanParameterInfoSupport instance specifies a non-null maximal value for the described parameter, false otherwise.
boolean | hasMinValue() Returns true if this OpenMBeanParameterInfoSupport instance specifies a non-null minimal value for the described parameter, false otherwise.
boolean | isValue(Object obj) Tests whether obj is a valid value for the parameter described by this OpenMBeanParameterInfo instance.
String | toString() Returns a string representation of this OpenMBeanParameterInfoSupport instance.
Methods inherited from class javax.management.MBeanParameterInfo
clone, getType
Methods inherited from class javax.management.MBeanFeatureInfo
getDescription, getDescriptor, getName
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface javax.management.openmbean.OpenMBeanParameterInfo
getDescription, getName

Constructor Detail

OpenMBeanParameterInfoSupport

public OpenMBeanParameterInfoSupport(String name,
                                     String description,
                                     OpenType<?> openType)
Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType and description.

Parameters:
name - cannot be a null or empty string.
description - cannot be a null or empty string.
openType - cannot be null.
Throws:
IllegalArgumentException - if name or description are null or empty string, or openType is null.

OpenMBeanParameterInfoSupport

public OpenMBeanParameterInfoSupport(String name,
                                     String description,
                                     OpenType<?> openType,
                                     Descriptor descriptor)

Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType, description, and descriptor.

The descriptor can contain entries that will define the values returned by certain methods of this class, as explained in the package description.

Parameters:
name - cannot be a null or empty string.
description - cannot be a null or empty string.
openType - cannot be null.
descriptor - The descriptor for the parameter. This may be null which is equivalent to an empty descriptor.
Throws:
IllegalArgumentException - if name or description are null or empty string, or openType is null, or the descriptor entries are invalid as described in the package description.
Since:
1.6

OpenMBeanParameterInfoSupport

public OpenMBeanParameterInfoSupport(String name,
                                     String description,
                                     OpenType<T> openType,
                                     T defaultValue)
                              throws OpenDataException
Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType, description and defaultValue.

Type Parameters:
T - allows the compiler to check that the defaultValue, if non-null, has the correct Java type for the given openType.
Parameters:
name - cannot be a null or empty string.
description - cannot be a null or empty string.
openType - cannot be null.
defaultValue - must be a valid value for the openType specified for this parameter; default value not supported for ArrayType and TabularType; can be null, in which case it means that no default value is set.
Throws:
IllegalArgumentException - if name or description are null or empty string, or openType is null.
OpenDataException - if defaultValue is not a valid value for the specified openType, or defaultValue is non null and openType is an ArrayType or a TabularType.

OpenMBeanParameterInfoSupport

public OpenMBeanParameterInfoSupport(String name,
                                     String description,
                                     OpenType<T> openType,
                                     T defaultValue,
                                     T[] legalValues)
                              throws OpenDataException

Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType, description, defaultValue and legalValues.

The contents of legalValues are copied, so subsequent modifications of the array referenced by legalValues have no impact on this OpenMBeanParameterInfoSupport instance.

Type Parameters:
T - allows the compiler to check that the defaultValue and legalValues, if non-null, have the correct Java type for the given openType.
Parameters:
name - cannot be a null or empty string.
description - cannot be a null or empty string.
openType - cannot be null.
defaultValue - must be a valid value for the openType specified for this parameter; default value not supported for ArrayType and TabularType; can be null, in which case it means that no default value is set.
legalValues - each contained value must be valid for the openType specified for this parameter; legal values not supported for ArrayType and TabularType; can be null or empty.
Throws:
IllegalArgumentException - if name or description are null or empty string, or openType is null.
OpenDataException - if defaultValue is not a valid value for the specified openType, or one value in legalValues is not valid for the specified openType, or defaultValue is non null and openType is an ArrayType or a TabularType, or legalValues is non null and non empty and openType is an ArrayType or a TabularType, or legalValues is non null and non empty and defaultValue is not contained in legalValues.

OpenMBeanParameterInfoSupport

public OpenMBeanParameterInfoSupport(String name,
                                     String description,
                                     OpenType<T> openType,
                                     T defaultValue,
                                     Comparable<T> minValue,
                                     Comparable<T> maxValue)
                              throws OpenDataException
Constructs an OpenMBeanParameterInfoSupport instance, which describes the parameter used in one or more operations or constructors of a class of open MBeans, with the specified name, openType, description, defaultValue, minValue and maxValue. It is possible to specify minimal and maximal values only for an open type whose values are Comparable.

Type Parameters:
T - allows the compiler to check that the defaultValue, minValue, and maxValue, if non-null, have the correct Java type for the given openType.
Parameters:
name - cannot be a null or empty string.
description - cannot be a null or empty string.
openType - cannot be null.
defaultValue - must be a valid value for the openType specified for this parameter; default value not supported for ArrayType and TabularType; can be null, in which case it means that no default value is set.
minValue - must be valid for the openType specified for this parameter; can be null, in which case it means that no minimal value is set.
maxValue - must be valid for the openType specified for this parameter; can be null, in which case it means that no maximal value is set.
Throws:
IllegalArgumentException - if name or description are null or empty string, or openType is null.
OpenDataException - if defaultValue, minValue or maxValue is not a valid value for the specified openType, or defaultValue is non null and openType is an ArrayType or a TabularType, or both minValue and maxValue are non-null and minValue.compareTo(maxValue) > 0 is true, or both defaultValue and minValue are non-null and minValue.compareTo(defaultValue) > 0 is true, or both defaultValue and maxValue are non-null and defaultValue.compareTo(maxValue) > 0 is true.
Method Detail

getOpenType

public OpenType<?> getOpenType()
Returns the open type for the values of the parameter described by this OpenMBeanParameterInfoSupport instance.

Specified by:
getOpenType in interface OpenMBeanParameterInfo
Returns:
the open type.

getDefaultValue

public Object getDefaultValue()
Returns the default value for the parameter described by this OpenMBeanParameterInfoSupport instance, if specified, or null otherwise.

Specified by:
getDefaultValue in interface OpenMBeanParameterInfo
Returns:
the default value.

getLegalValues

public Set<?> getLegalValues()
Returns an unmodifiable Set of legal values for the parameter described by this OpenMBeanParameterInfoSupport instance, if specified, or null otherwise.

Specified by:
getLegalValues in interface OpenMBeanParameterInfo
Returns:
the set of legal values.

getMinValue

public Comparable<?> getMinValue()
Returns the minimal value for the parameter described by this OpenMBeanParameterInfoSupport instance, if specified, or null otherwise.

Specified by:
getMinValue in interface OpenMBeanParameterInfo
Returns:
the minimum value.

getMaxValue

public Comparable<?> getMaxValue()
Returns the maximal value for the parameter described by this OpenMBeanParameterInfoSupport instance, if specified, or null otherwise.

Specified by:
getMaxValue in interface OpenMBeanParameterInfo
Returns:
the maximum value.

hasDefaultValue

public boolean hasDefaultValue()
Returns true if this OpenMBeanParameterInfoSupport instance specifies a non-null default value for the described parameter, false otherwise.

Specified by:
hasDefaultValue in interface OpenMBeanParameterInfo
Returns:
true if there is a default value.

hasLegalValues

public boolean hasLegalValues()
Returns true if this OpenMBeanParameterInfoSupport instance specifies a non-null set of legal values for the described parameter, false otherwise.

Specified by:
hasLegalValues in interface OpenMBeanParameterInfo
Returns:
true if there is a set of legal values.

hasMinValue

public boolean hasMinValue()
Returns true if this OpenMBeanParameterInfoSupport instance specifies a non-null minimal value for the described parameter, false otherwise.

Specified by:
hasMinValue in interface OpenMBeanParameterInfo
Returns:
true if there is a minimum value.

hasMaxValue

public boolean hasMaxValue()
Returns true if this OpenMBeanParameterInfoSupport instance specifies a non-null maximal value for the described parameter, false otherwise.

Specified by:
hasMaxValue in interface OpenMBeanParameterInfo
Returns:
true if there is a maximum value.

isValue

public boolean isValue(Object obj)
Tests whether obj is a valid value for the parameter described by this OpenMBeanParameterInfo instance.

Specified by:
isValue in interface OpenMBeanParameterInfo
Parameters:
obj - the object to be tested.
Returns:
true if obj is a valid value for the parameter described by this OpenMBeanParameterInfo instance, false otherwise.

equals

public boolean equals(Object obj)

Compares the specified obj parameter with this OpenMBeanParameterInfoSupport instance for equality.

Returns true if and only if all of the following statements are true:

  • obj is non null,
  • obj also implements the OpenMBeanParameterInfo interface,
  • their names are equal
  • their open types are equal
  • their default, min, max and legal values are equal.
This ensures that this equals method works properly for obj parameters which are different implementations of the OpenMBeanParameterInfo interface.

If obj also implements DescriptorRead, then its getDescriptor() method must also return the same value as for this object.

Specified by:
equals in interface OpenMBeanParameterInfo
Overrides:
equals in class MBeanParameterInfo
Parameters:
obj - the object to be compared for equality with this OpenMBeanParameterInfoSupport instance.
Returns:
true if the specified object is equal to this OpenMBeanParameterInfoSupport instance.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()

Returns the hash code value for this OpenMBeanParameterInfoSupport instance.

The hash code of an OpenMBeanParameterInfoSupport instance is the sum of the hash codes of all elements of information used in equals comparisons (ie: its name, its open type, its default, min, max and legal values, and its Descriptor).

This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two OpenMBeanParameterInfoSupport instances t1 and t2, as required by the general contract of the method Object.hashCode().

However, note that another instance of a class implementing the OpenMBeanParameterInfo interface may be equal to this OpenMBeanParameterInfoSupport instance as defined by equals(java.lang.Object), but may have a different hash code if it is calculated differently.

As OpenMBeanParameterInfoSupport instances are immutable, the hash code for this instance is calculated once, on the first call to hashCode, and then the same value is returned for subsequent calls.

Specified by:
hashCode in interface OpenMBeanParameterInfo
Overrides:
hashCode in class MBeanParameterInfo
Returns:
the hash code value for this OpenMBeanParameterInfoSupport instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Returns a string representation of this OpenMBeanParameterInfoSupport instance.

The string representation consists of the name of this class (i.e. javax.management.openmbean.OpenMBeanParameterInfoSupport), the string representation of the name and open type of the described parameter, the string representation of its default, min, max and legal values and the string representation of its descriptor.

As OpenMBeanParameterInfoSupport instances are immutable, the string representation for this instance is calculated once, on the first call to toString, and then the same value is returned for subsequent calls.

Specified by:
toString in interface OpenMBeanParameterInfo
Overrides:
toString in class MBeanParameterInfo
Returns:
a string representation of this OpenMBeanParameterInfoSupport instance.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OpenType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Class OpenType<T>

java.lang.Object
    extended by  javax.management.openmbean.OpenType<T>
Type Parameters:
T - the Java type that instances described by this type must have. For example, SimpleType.INTEGER is a SimpleType<Integer> which is a subclass of OpenType<Integer>, meaning that an attribute, parameter, or return value that is described as a SimpleType.INTEGER must have Java type Integer.
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
ArrayType, CompositeType, SimpleType, TabularType
public abstract class OpenType<T>
extends Object
implements Serializable

The OpenType class is the parent abstract class of all classes which describe the actual open type of open data values.

An open type is defined by:

  • the fully qualified Java class name of the open data values this type describes; note that only a limited set of Java classes is allowed for open data values (see ALLOWED_CLASSNAMES_LIST),
  • its name,
  • its description.

Since:
1.5
See Also:
Serialized Form

Field Summary
static String[] | ALLOWED_CLASSNAMES Deprecated. Use ALLOWED_CLASSNAMES_LIST instead.
static List<String> | ALLOWED_CLASSNAMES_LIST List of the fully qualified names of the Java classes allowed for open data values.
Constructor Summary
protected OpenType(String className, String typeName, String description)
Constructs an OpenType instance (actually a subclass instance as OpenType is abstract), checking for the validity of the given parameters.
Method Summary
abstract boolean | equals(Object obj) Compares the specified obj parameter with this open type instance for equality.
String | getClassName() Returns the fully qualified Java class name of the open data values this open type describes.
String | getDescription() Returns the text description of this OpenType instance.
String | getTypeName() Returns the name of this OpenType instance.
abstract int | hashCode() Returns a hash code value for the object.
boolean | isArray() Returns true if the open data values this open type describes are arrays, false otherwise.
abstract boolean | isValue(Object obj) Tests whether obj is a value for this open type.
abstract String | toString() Returns a string representation of this open type instance.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ALLOWED_CLASSNAMES_LIST

public static final List<String> ALLOWED_CLASSNAMES_LIST
List of the fully qualified names of the Java classes allowed for open data values. A multidimensional array of any one of these classes or their corresponding primitive types is also an allowed class for open data values.
ALLOWED_CLASSNAMES_LIST = {
        "java.lang.Void",
        "java.lang.Boolean",
        "java.lang.Character",
        "java.lang.Byte",
        "java.lang.Short",
        "java.lang.Integer",
        "java.lang.Long",
        "java.lang.Float",
        "java.lang.Double",
        "java.lang.String",
        "java.math.BigDecimal",
        "java.math.BigInteger",
        "java.util.Date",
        "javax.management.ObjectName",
        CompositeData.class.getName(),
        TabularData.class.getName() } ;

ALLOWED_CLASSNAMES

@Deprecated
public static final String[] ALLOWED_CLASSNAMES
Deprecated. Use ALLOWED_CLASSNAMES_LIST instead.
Constructor Detail

OpenType

protected OpenType(String className,
                   String typeName,
                   String description)
            throws OpenDataException
Constructs an OpenType instance (actually a subclass instance as OpenType is abstract), checking for the validity of the given parameters. The validity constraints are described below for each parameter.

Parameters:
className - The fully qualified Java class name of the open data values this open type describes. The valid Java class names allowed for open data values are listed in ALLOWED_CLASSNAMES_LIST. A multidimensional array of any one of these classes or their corresponding primitive types is also an allowed class, in which case the class name follows the rules defined by the method getName() of java.lang.Class. For example, a 3-dimensional array of Strings has for class name "[[[Ljava.lang.String;" (without the quotes).
typeName - The name given to the open type this instance represents; cannot be a null or empty string.
description - The human readable description of the open type this instance represents; cannot be a null or empty string.
Throws:
IllegalArgumentException - if className, typeName or description is a null or empty string
OpenDataException - if className is not one of the allowed Java class names for open data
Method Detail

getClassName

public String getClassName()
Returns the fully qualified Java class name of the open data values this open type describes. The only possible Java class names for open data values are listed in ALLOWED_CLASSNAMES_LIST. A multidimensional array of any one of these classes or their corresponding primitive types is also an allowed class, in which case the class name follows the rules defined by the method getName() of java.lang.Class. For example, a 3-dimensional array of Strings has for class name "[[[Ljava.lang.String;" (without the quotes), a 3-dimensional array of Integers has for class name "[[[Ljava.lang.Integer;" (without the quotes), and a 3-dimensional array of int has for class name "[[[I" (without the quotes)

Returns:
the class name.

getTypeName

public String getTypeName()
Returns the name of this OpenType instance.

Returns:
the type name.

getDescription

public String getDescription()
Returns the text description of this OpenType instance.

Returns:
the description.

isArray

public boolean isArray()
Returns true if the open data values this open type describes are arrays, false otherwise.

Returns:
true if this is an array type.

isValue

public abstract boolean isValue(Object obj)
Tests whether obj is a value for this open type.

Parameters:
obj - the object to be tested for validity.
Returns:
true if obj is a value for this open type, false otherwise.

equals

public abstract boolean equals(Object obj)
Compares the specified obj parameter with this open type instance for equality.

Overrides:
equals in class Object
Parameters:
obj - the object to compare to.
Returns:
true if this object and obj are equal.
See Also:
Object.hashCode(), Hashtable

hashCode

public abstract int hashCode()
Description copied from class: Object
Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the Object.equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public abstract String toString()
Returns a string representation of this open type instance.

Overrides:
toString in class Object
Returns:
the string representation.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SimpleType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Class SimpleType<T>

java.lang.Object
    extended by  javax.management.openmbean.OpenType<T>
        extended by  javax.management.openmbean.SimpleType<T>
All Implemented Interfaces:
Serializable
public final class SimpleType<T>
extends OpenType<T>

The SimpleType class is the open type class whose instances describe all open data values which are neither arrays, nor CompositeData values, nor TabularData values. It predefines all its possible instances as static fields, and has no public constructor.

Given a SimpleType instance describing values whose Java class name is className, the internal fields corresponding to the name and description of this SimpleType instance are also set to className. In other words, its methods getClassName, getTypeName and getDescription all return the same string value className.

Since:
1.5
See Also:
Serialized Form

Field Summary
static SimpleType<BigDecimal> | BIGDECIMAL The SimpleType instance describing values whose Java class name is java.math.BigDecimal.
static SimpleType<BigInteger> | BIGINTEGER The SimpleType instance describing values whose Java class name is java.math.BigInteger.
static SimpleType<Boolean> | BOOLEAN The SimpleType instance describing values whose Java class name is java.lang.Boolean.
static SimpleType<Byte> | BYTE The SimpleType instance describing values whose Java class name is java.lang.Byte.
static SimpleType<Character> | CHARACTER The SimpleType instance describing values whose Java class name is java.lang.Character.
static SimpleType<Date> | DATE The SimpleType instance describing values whose Java class name is java.util.Date.
static SimpleType<Double> | DOUBLE The SimpleType instance describing values whose Java class name is java.lang.Double.
static SimpleType<Float> | FLOAT The SimpleType instance describing values whose Java class name is java.lang.Float.
static SimpleType<Integer> | INTEGER The SimpleType instance describing values whose Java class name is java.lang.Integer.
static SimpleType<Long> | LONG The SimpleType instance describing values whose Java class name is java.lang.Long.
static SimpleType<ObjectName> | OBJECTNAME The SimpleType instance describing values whose Java class name is javax.management.ObjectName.
static SimpleType<Short> | SHORT The SimpleType instance describing values whose Java class name is java.lang.Short.
static SimpleType<String> | STRING The SimpleType instance describing values whose Java class name is java.lang.String.
static SimpleType<Void> | VOID The SimpleType instance describing values whose Java class name is java.lang.Void.
Fields inherited from class javax.management.openmbean.OpenType
ALLOWED_CLASSNAMES, ALLOWED_CLASSNAMES_LIST
Method Summary
boolean | equals(Object obj) Compares the specified obj parameter with this SimpleType instance for equality.
int | hashCode() Returns the hash code value for this SimpleType instance.
boolean | isValue(Object obj) Tests whether obj is a value for this SimpleType instance.
Object | readResolve() Replace an object read from an ObjectInputStream with the unique instance for that value.
String | toString() Returns a string representation of this SimpleType instance.
Methods inherited from class javax.management.openmbean.OpenType
getClassName, getDescription, getTypeName, isArray
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

VOID

public static final SimpleType<Void> VOID
The SimpleType instance describing values whose Java class name is java.lang.Void.

BOOLEAN

public static final SimpleType<Boolean> BOOLEAN
The SimpleType instance describing values whose Java class name is java.lang.Boolean.

CHARACTER

public static final SimpleType<Character> CHARACTER
The SimpleType instance describing values whose Java class name is java.lang.Character.

BYTE

public static final SimpleType<Byte> BYTE
The SimpleType instance describing values whose Java class name is java.lang.Byte.

SHORT

public static final SimpleType<Short> SHORT
The SimpleType instance describing values whose Java class name is java.lang.Short.

INTEGER

public static final SimpleType<Integer> INTEGER
The SimpleType instance describing values whose Java class name is java.lang.Integer.

LONG

public static final SimpleType<Long> LONG
The SimpleType instance describing values whose Java class name is java.lang.Long.

FLOAT

public static final SimpleType<Float> FLOAT
The SimpleType instance describing values whose Java class name is java.lang.Float.

DOUBLE

public static final SimpleType<Double> DOUBLE
The SimpleType instance describing values whose Java class name is java.lang.Double.

STRING

public static final SimpleType<String> STRING
The SimpleType instance describing values whose Java class name is java.lang.String.

BIGDECIMAL

public static final SimpleType<BigDecimal> BIGDECIMAL
The SimpleType instance describing values whose Java class name is java.math.BigDecimal.

BIGINTEGER

public static final SimpleType<BigInteger> BIGINTEGER
The SimpleType instance describing values whose Java class name is java.math.BigInteger.

DATE

public static final SimpleType<Date> DATE
The SimpleType instance describing values whose Java class name is java.util.Date.

OBJECTNAME

public static final SimpleType<ObjectName> OBJECTNAME
The SimpleType instance describing values whose Java class name is javax.management.ObjectName.

Method Detail

isValue

public boolean isValue(Object obj)
Tests whether obj is a value for this SimpleType instance.

This method returns true if and only if obj is not null and obj's class name is the same as the className field defined for this SimpleType instance (ie the class name returned by the getClassName method).

Specified by:
isValue in class OpenType<T>
Parameters:
obj - the object to be tested.
Returns:
true if obj is a value for this SimpleType instance.

equals

public boolean equals(Object obj)
Compares the specified obj parameter with this SimpleType instance for equality.

Two SimpleType instances are equal if and only if their getClassName methods return the same value.

Specified by:
equals in class OpenType<T>
Parameters:
obj - the object to be compared for equality with this SimpleType instance; if obj is null or is not an instance of the class SimpleType, equals returns false.
Returns:
true if the specified object is equal to this SimpleType instance.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns the hash code value for this SimpleType instance. The hash code of a SimpleType instance is the the hash code of the string value returned by the getClassName method.

As SimpleType instances are immutable, the hash code for this instance is calculated once, on the first call to hashCode, and then the same value is returned for subsequent calls.

Specified by:
hashCode in class OpenType<T>
Returns:
the hash code value for this SimpleType instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Returns a string representation of this SimpleType instance.

The string representation consists of the name of this class (ie javax.management.openmbean.SimpleType) and the type name for this instance (which is the java class name of the values this SimpleType instance represents).

As SimpleType instances are immutable, the string representation for this instance is calculated once, on the first call to toString, and then the same value is returned for subsequent calls.

Specified by:
toString in class OpenType<T>
Returns:
a string representation of this SimpleType instance

readResolve

public Object readResolve()
                   throws ObjectStreamException
Replace an object read from an ObjectInputStream with the unique instance for that value.

Returns:
the replacement object.
Throws:
ObjectStreamException - if the read object cannot be resolved.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TabularData

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Interface TabularData

All Known Implementing Classes:
TabularDataSupport
public interface TabularData

The TabularData interface specifies the behavior of a specific type of complex open data objects which represent tabular data structures.

Since:
1.5

Method Summary
Object[] | calculateIndex(CompositeData value) Calculates the index that would be used in this TabularData instance to refer to the specified composite data value parameter if it were added to this instance.
void | clear() Removes all CompositeData values (ie rows) from this TabularData instance.
boolean | containsKey(Object[] key) Returns true if and only if this TabularData instance contains a CompositeData value (ie a row) whose index is the specified key.
boolean | containsValue(CompositeData value) Returns true if and only if this TabularData instance contains the specified CompositeData value.
boolean | equals(Object obj) Compares the specified obj parameter with this TabularData instance for equality.
CompositeData | get(Object[] key) Returns the CompositeData value whose index is key, or null if there is no value mapping to key, in this TabularData instance.
TabularType | getTabularType() Returns the tabular type describing this TabularData instance.
int | hashCode() Returns the hash code value for this TabularData instance.
boolean | isEmpty() Returns true if the number of CompositeData values (ie the number of rows) contained in this TabularData instance is zero.
Set<?> | keySet() Returns a set view of the keys (ie the index values) of the CompositeData values (ie the rows) contained in this TabularData instance.
void | put(CompositeData value) Adds value to this TabularData instance.
void | putAll(CompositeData[] values) Add all the elements in values to this TabularData instance.
CompositeData | remove(Object[] key) Removes the CompositeData value whose index is key from this TabularData instance, and returns the removed value, or returns null if there is no value whose index is key.
int | size() Returns the number of CompositeData values (ie the number of rows) contained in this TabularData instance.
String | toString() Returns a string representation of this TabularData instance.
Collection<?> | values() Returns a collection view of the CompositeData values (ie the rows) contained in this TabularData instance.

Method Detail

getTabularType

TabularType getTabularType()
Returns the tabular type describing this TabularData instance.

Returns:
the tabular type.

calculateIndex

Object[] calculateIndex(CompositeData value)
Calculates the index that would be used in this TabularData instance to refer to the specified composite data value parameter if it were added to this instance. This method checks for the type validity of the specified value, but does not check if the calculated index is already used to refer to a value in this TabularData instance.

Parameters:
value - the composite data value whose index in this TabularData instance is to be calculated; must be of the same composite type as this instance's row type; must not be null.
Returns:
the index that the specified value would have in this TabularData instance.
Throws:
NullPointerException - if value is null
InvalidOpenTypeException - if value does not conform to this TabularData instance's row type definition.

size

int size()
Returns the number of CompositeData values (ie the number of rows) contained in this TabularData instance.

Returns:
the number of values contained.

isEmpty

boolean isEmpty()
Returns true if the number of CompositeData values (ie the number of rows) contained in this TabularData instance is zero.

Returns:
true if this TabularData is empty.

containsKey

boolean containsKey(Object[] key)
Returns true if and only if this TabularData instance contains a CompositeData value (ie a row) whose index is the specified key. If key is null or does not conform to this TabularData instance's TabularType definition, this method simply returns false.

Parameters:
key - the index value whose presence in this TabularData instance is to be tested.
Returns:
true if this TabularData indexes a row value with the specified key.

containsValue

boolean containsValue(CompositeData value)
Returns true if and only if this TabularData instance contains the specified CompositeData value. If value is null or does not conform to this TabularData instance's row type definition, this method simply returns false.

Parameters:
value - the row value whose presence in this TabularData instance is to be tested.
Returns:
true if this TabularData instance contains the specified row value.

get

CompositeData get(Object[] key)
Returns the CompositeData value whose index is key, or null if there is no value mapping to key, in this TabularData instance.

Parameters:
key - the key of the row to return.
Returns:
the value corresponding to key.
Throws:
NullPointerException - if the key is null
InvalidKeyException - if the key does not conform to this TabularData instance's * TabularType definition

put

void put(CompositeData value)
Adds value to this TabularData instance. The composite type of value must be the same as this instance's row type (ie the composite type returned by this.getTabularType().getRowType()), and there must not already be an existing value in this TabularData instance whose index is the same as the one calculated for the value to be added. The index for value is calculated according to this TabularData instance's TabularType definition (see TabularType.getIndexNames()).

Parameters:
value - the composite data value to be added as a new row to this TabularData instance; must be of the same composite type as this instance's row type; must not be null.
Throws:
NullPointerException - if value is null
InvalidOpenTypeException - if value does not conform to this TabularData instance's row type definition.
KeyAlreadyExistsException - if the index for value, calculated according to this TabularData instance's TabularType definition already maps to an existing value in the underlying HashMap.

remove

CompositeData remove(Object[] key)
Removes the CompositeData value whose index is key from this TabularData instance, and returns the removed value, or returns null if there is no value whose index is key.

Parameters:
key - the index of the value to get in this TabularData instance; must be valid with this TabularData instance's row type definition; must not be null.
Returns:
previous value associated with specified key, or null if there was no mapping for key.
Throws:
NullPointerException - if the key is null
InvalidKeyException - if the key does not conform to this TabularData instance's TabularType definition

putAll

void putAll(CompositeData[] values)
Add all the elements in values to this TabularData instance. If any element in values does not satisfy the constraints defined in put, or if any two elements in values have the same index calculated according to this TabularData instance's TabularType definition, then an exception describing the failure is thrown and no element of values is added, thus leaving this TabularData instance unchanged.

Parameters:
values - the array of composite data values to be added as new rows to this TabularData instance; if values is null or empty, this method returns without doing anything.
Throws:
NullPointerException - if an element of values is null
InvalidOpenTypeException - if an element of values does not conform to this TabularData instance's row type definition
KeyAlreadyExistsException - if the index for an element of values, calculated according to this TabularData instance's TabularType definition already maps to an existing value in this instance, or two elements of values have the same index.

clear

void clear()
Removes all CompositeData values (ie rows) from this TabularData instance.

keySet

Set<?> keySet()
Returns a set view of the keys (ie the index values) of the CompositeData values (ie the rows) contained in this TabularData instance. The returned Set is a Set<List<?>> but is declared as a Set<?> for compatibility reasons. The returned set can be used to iterate over the keys.

Returns:
a set view (Set<List<?>>) of the index values used in this TabularData instance.

values

Collection<?> values()
Returns a collection view of the CompositeData values (ie the rows) contained in this TabularData instance. The returned Collection is a Collection<CompositeData> but is declared as a Collection<?> for compatibility reasons. The returned collection can be used to iterate over the values.

Returns:
a collection view (Collection<CompositeData>) of the rows contained in this TabularData instance.

equals

boolean equals(Object obj)
Compares the specified obj parameter with this TabularData instance for equality.

Returns true if and only if all of the following statements are true:

  • obj is non null,
  • obj also implements the TabularData interface,
  • their row types are equal
  • their contents (ie index to value mappings) are equal
This ensures that this equals method works properly for obj parameters which are different implementations of the TabularData interface.

Overrides:
equals in class Object
Parameters:
obj - the object to be compared for equality with this TabularData instance;
Returns:
true if the specified object is equal to this TabularData instance.
See Also:
Object.hashCode(), Hashtable

hashCode

int hashCode()
Returns the hash code value for this TabularData instance.

The hash code of a TabularData instance is the sum of the hash codes of all elements of information used in equals comparisons (ie: its tabular type and its content, where the content is defined as all the index to value mappings).

This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two TabularDataSupport instances t1 and t2, as required by the general contract of the method Object.hashCode().

Overrides:
hashCode in class Object
Returns:
the hash code value for this TabularDataSupport instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

String toString()
Returns a string representation of this TabularData instance.

The string representation consists of the name of the implementing class, and the tabular type of this instance.

Overrides:
toString in class Object
Returns:
a string representation of this TabularData instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TabularDataSupport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Class TabularDataSupport

java.lang.Object
    extended by  javax.management.openmbean.TabularDataSupport
All Implemented Interfaces:
Serializable, Cloneable, Map<Object,Object>, TabularData
public class TabularDataSupport
extends Object
implements TabularData, Map<Object,Object>, Cloneable, Serializable

The TabularDataSupport class is the open data class which implements the TabularData and the Map interfaces, and which is internally based on a hash map data structure.

Since:
1.5
See Also:
Serialized Form

Nested Class Summary
Nested classes/interfaces inherited from interface java.util.Map
Map.Entry<K,V>
Constructor Summary
TabularDataSupport(TabularType tabularType)
Creates an empty TabularDataSupport instance whose open-type is tabularType, and whose underlying HashMap has a default initial capacity (101) and default load factor (0.75).
TabularDataSupport(TabularType tabularType, int initialCapacity, float loadFactor)
Creates an empty TabularDataSupport instance whose open-type is tabularType, and whose underlying HashMap has the specified initial capacity and load factor.
Method Summary
 Object[] calculateIndex(CompositeData value)
Calculates the index that would be used in this TabularData instance to refer to the specified composite data value parameter if it were added to this instance.
 void clear()
Removes all rows from this TabularDataSupport instance.
 Object clone()
Returns a clone of this TabularDataSupport instance: the clone is obtained by calling super.clone(), and then cloning the underlying map.
 boolean containsKey(Object key)
Returns true if and only if this TabularData instance contains a CompositeData value (ie a row) whose index is the specified key.
 boolean containsKey(Object[] key)
Returns true if and only if this TabularData instance contains a CompositeData value (ie a row) whose index is the specified key.
 boolean containsValue(CompositeData value)
Returns true if and only if this TabularData instance contains the specified CompositeData value.
 boolean containsValue(Object value)
Returns true if and only if this TabularData instance contains the specified value.
 Set<Map.Entry<Object,Object>> entrySet()
Returns a collection view of the index to row mappings contained in this TabularDataSupport instance.
 boolean equals(Object obj)
Compares the specified obj parameter with this TabularDataSupport instance for equality.
 Object get(Object key)
This method simply calls get((Object[]) key).
 CompositeData get(Object[] key)
Returns the CompositeData value whose index is key, or null if there is no value mapping to key, in this TabularData instance.
 TabularType getTabularType()
Returns the tabular type describing this TabularData instance.
 int hashCode()
Returns the hash code value for this TabularDataSupport instance.
 boolean isEmpty()
Returns true if this TabularDataSupport instance contains no rows.
 Set<Object> keySet()
Returns a set view of the keys contained in the underlying map of this TabularDataSupport instance used to index the rows.
 void put(CompositeData value)
Adds value to this TabularData instance.
 Object put(Object key, Object value)
This method simply calls put((CompositeData) value) and therefore ignores its key parameter which can be null.
 void putAll(CompositeData[] values)
Add all the elements in values to this TabularData instance.
 void putAll(Map<?,?> t)
Add all the values contained in the specified map t to this TabularData instance.
 Object remove(Object key)
This method simply calls remove((Object[]) key).
 CompositeData remove(Object[] key)
Removes the CompositeData value whose index is key from this TabularData instance, and returns the removed value, or returns null if there is no value whose index is key.
 int size()
Returns the number of rows in this TabularDataSupport instance.
 String toString()
Returns a string representation of this TabularDataSupport instance.
 Collection<Object> values()
Returns a collection view of the rows contained in this TabularDataSupport instance.
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

TabularDataSupport

public TabularDataSupport(TabularType tabularType)
Creates an empty TabularDataSupport instance whose open-type is tabularType, and whose underlying HashMap has a default initial capacity (101) and default load factor (0.75).

This constructor simply calls this(tabularType, 101, 0.75f);

Parameters:
tabularType - the tabular type describing this TabularData instance; cannot be null.
Throws:
IllegalArgumentException - if the tabular type is null.

TabularDataSupport

public TabularDataSupport(TabularType tabularType,
                          int initialCapacity,
                          float loadFactor)
Creates an empty TabularDataSupport instance whose open-type is tabularType, and whose underlying HashMap has the specified initial capacity and load factor.

Parameters:
tabularType - the tabular type describing this TabularData instance; cannot be null.
initialCapacity - the initial capacity of the HashMap.
loadFactor - the load factor of the HashMap
Throws:
IllegalArgumentException - if the initial capacity is less than zero, or the load factor is nonpositive, or the tabular type is null.
Method Detail

getTabularType

public TabularType getTabularType()
Returns the tabular type describing this TabularData instance.

Specified by:
getTabularType in interface TabularData
Returns:
the tabular type.

calculateIndex

public Object[] calculateIndex(CompositeData value)
Calculates the index that would be used in this TabularData instance to refer to the specified composite data value parameter if it were added to this instance. This method checks for the type validity of the specified value, but does not check if the calculated index is already used to refer to a value in this TabularData instance.

Specified by:
calculateIndex in interface TabularData
Parameters:
value - the composite data value whose index in this TabularData instance is to be calculated; must be of the same composite type as this instance's row type; must not be null.
Returns:
the index that the specified value would have in this TabularData instance.
Throws:
NullPointerException - if value is null.
InvalidOpenTypeException - if value does not conform to this TabularData instance's row type definition.

containsKey

public boolean containsKey(Object key)
Returns true if and only if this TabularData instance contains a CompositeData value (ie a row) whose index is the specified key. If key cannot be cast to a one dimension array of Object instances, this method simply returns false; otherwise it returns the the result of the call to this.containsKey((Object[]) key).

Specified by:
containsKey in interface Map<Object,Object>
Parameters:
key - the index value whose presence in this TabularData instance is to be tested.
Returns:
true if this TabularData indexes a row value with the specified key.

containsKey

public boolean containsKey(Object[] key)
Returns true if and only if this TabularData instance contains a CompositeData value (ie a row) whose index is the specified key. If key is null or does not conform to this TabularData instance's TabularType definition, this method simply returns false.

Specified by:
containsKey in interface TabularData
Parameters:
key - the index value whose presence in this TabularData instance is to be tested.
Returns:
true if this TabularData indexes a row value with the specified key.

containsValue

public boolean containsValue(CompositeData value)
Returns true if and only if this TabularData instance contains the specified CompositeData value. If value is null or does not conform to this TabularData instance's row type definition, this method simply returns false.

Specified by:
containsValue in interface TabularData
Parameters:
value - the row value whose presence in this TabularData instance is to be tested.
Returns:
true if this TabularData instance contains the specified row value.

containsValue

public boolean containsValue(Object value)
Returns true if and only if this TabularData instance contains the specified value.

Specified by:
containsValue in interface Map<Object,Object>
Parameters:
value - the row value whose presence in this TabularData instance is to be tested.
Returns:
true if this TabularData instance contains the specified row value.

get

public Object get(Object key)
This method simply calls get((Object[]) key).

Specified by:
get in interface Map<Object,Object>
Parameters:
key - the key whose associated value is to be returned
Returns:
the value to which the specified key is mapped, or null if this map contains no mapping for the key
Throws:
NullPointerException - if the key is null
ClassCastException - if the key is not of the type Object[]
InvalidKeyException - if the key does not conform to this TabularData instance's TabularType definition

get

public CompositeData get(Object[] key)
Returns the CompositeData value whose index is key, or null if there is no value mapping to key, in this TabularData instance.

Specified by:
get in interface TabularData
Parameters:
key - the index of the value to get in this TabularData instance; * must be valid with this TabularData instance's row type definition; * must not be null.
Returns:
the value corresponding to key.
Throws:
NullPointerException - if the key is null
InvalidKeyException - if the key does not conform to this TabularData instance's TabularType type definition.

put

public Object put(Object key,
                  Object value)
This method simply calls put((CompositeData) value) and therefore ignores its key parameter which can be null.

Specified by:
put in interface Map<Object,Object>
Parameters:
key - an ignored parameter.
value - the CompositeData to put.
Returns:
the value which is put
Throws:
NullPointerException - if the value is null
ClassCastException - if the value is not of the type CompositeData
InvalidOpenTypeException - if the value does not conform to this TabularData instance's TabularType definition
KeyAlreadyExistsException - if the key for the value parameter, calculated according to this TabularData instance's TabularType definition already maps to an existing value

put

public void put(CompositeData value)
Description copied from interface: TabularData
Adds value to this TabularData instance. The composite type of value must be the same as this instance's row type (ie the composite type returned by this.getTabularType().getRowType()), and there must not already be an existing value in this TabularData instance whose index is the same as the one calculated for the value to be added. The index for value is calculated according to this TabularData instance's TabularType definition (see TabularType.getIndexNames()).

Specified by:
put in interface TabularData
Parameters:
value - the composite data value to be added as a new row to this TabularData instance; must be of the same composite type as this instance's row type; must not be null.

remove

public Object remove(Object key)
This method simply calls remove((Object[]) key).

Specified by:
remove in interface Map<Object,Object>
Parameters:
key - an Object[] representing the key to remove.
Returns:
previous value associated with specified key, or null if there was no mapping for key.
Throws:
NullPointerException - if the key is null
ClassCastException - if the key is not of the type Object[]
InvalidKeyException - if the key does not conform to this TabularData instance's TabularType definition

remove

public CompositeData remove(Object[] key)
Removes the CompositeData value whose index is key from this TabularData instance, and returns the removed value, or returns null if there is no value whose index is key.

Specified by:
remove in interface TabularData
Parameters:
key - the index of the value to get in this TabularData instance; must be valid with this TabularData instance's row type definition; must not be null.
Returns:
previous value associated with specified key, or null if there was no mapping for key.
Throws:
NullPointerException - if the key is null
InvalidKeyException - if the key does not conform to this TabularData instance's TabularType definition

putAll

public void putAll(Map<?,?> t)
Add all the values contained in the specified map t to this TabularData instance. This method converts the collection of values contained in this map into an array of CompositeData values, if possible, and then call the method putAll(CompositeData[]). Note that the keys used in the specified map t are ignored. This method allows, for example to add the content of another TabularData instance with the same row type (but possibly different index names) into this instance.

Specified by:
putAll in interface Map<Object,Object>
Parameters:
t - the map whose values are to be added as new rows to this TabularData instance; if t is null or empty, this method returns without doing anything.
Throws:
NullPointerException - if a value in t is null.
ClassCastException - if a value in t is not an instance of CompositeData.
InvalidOpenTypeException - if a value in t does not conform to this TabularData instance's row type definition.
KeyAlreadyExistsException - if the index for a value in t, calculated according to this TabularData instance's TabularType definition already maps to an existing value in this instance, or two values in t have the same index.

putAll

public void putAll(CompositeData[] values)
Add all the elements in values to this TabularData instance. If any element in values does not satisfy the constraints defined in put, or if any two elements in values have the same index calculated according to this TabularData instance's TabularType definition, then an exception describing the failure is thrown and no element of values is added, thus leaving this TabularData instance unchanged.

Specified by:
putAll in interface TabularData
Parameters:
values - the array of composite data values to be added as new rows to this TabularData instance; if values is null or empty, this method returns without doing anything.
Throws:
NullPointerException - if an element of values is null
InvalidOpenTypeException - if an element of values does not conform to this TabularData instance's row type definition (ie its TabularType definition)
KeyAlreadyExistsException - if the index for an element of values, calculated according to this TabularData instance's TabularType definition already maps to an existing value in this instance, or two elements of values have the same index

clear

public void clear()
Removes all rows from this TabularDataSupport instance.

Specified by:
clear in interface Map<Object,Object>
Specified by:
clear in interface TabularData

size

public int size()
Returns the number of rows in this TabularDataSupport instance.

Specified by:
size in interface Map<Object,Object>
Specified by:
size in interface TabularData
Returns:
the number of rows in this TabularDataSupport instance.

isEmpty

public boolean isEmpty()
Returns true if this TabularDataSupport instance contains no rows.

Specified by:
isEmpty in interface Map<Object,Object>
Specified by:
isEmpty in interface TabularData
Returns:
true if this TabularDataSupport instance contains no rows.

keySet

public Set<Object> keySet()
Returns a set view of the keys contained in the underlying map of this TabularDataSupport instance used to index the rows. Each key contained in this Set is an unmodifiable List<?> so the returned set view is a Set<List<?>> but is declared as a Set<Object> for compatibility reasons. The set is backed by the underlying map of this TabularDataSupport instance, so changes to the TabularDataSupport instance are reflected in the set, and vice-versa. The set supports element removal, which removes the corresponding row from this TabularDataSupport instance, via the Iterator.remove(), Set.remove(java.lang.Object), Set.removeAll(java.util.Collection), Set.retainAll(java.util.Collection), and Set.clear() operations. It does not support the Set.add(E) or Set.addAll(java.util.Collection) operations.

Specified by:
keySet in interface Map<Object,Object>
Specified by:
keySet in interface TabularData
Returns:
a set view (Set<List<?>>) of the keys used to index the rows of this TabularDataSupport instance.

values

public Collection<Object> values()
Returns a collection view of the rows contained in this TabularDataSupport instance. The returned Collection is a Collection<CompositeData> but is declared as a Collection<Object> for compatibility reasons. The returned collection can be used to iterate over the values. The collection is backed by the underlying map, so changes to the TabularDataSupport instance are reflected in the collection, and vice-versa. The collection supports element removal, which removes the corresponding index to row mapping from this TabularDataSupport instance, via the Iterator.remove(), Collection.remove(java.lang.Object), Collection.removeAll(java.util.Collection), Collection.retainAll(java.util.Collection), and Collection.clear() operations. It does not support the Collection.add(E) or Collection.addAll(java.util.Collection) operations.

Specified by:
values in interface Map<Object,Object>
Specified by:
values in interface TabularData
Returns:
a collection view (Collection<CompositeData>) of the values contained in this TabularDataSupport instance.

entrySet

public Set<Map.Entry<Object,Object>> entrySet()
Returns a collection view of the index to row mappings contained in this TabularDataSupport instance. Each element in the returned collection is a Map.Entry<List<?>,CompositeData> but is declared as a Map.Entry<Object,Object> for compatibility reasons. Each of the map entry keys is an unmodifiable List<?>. The collection is backed by the underlying map of this TabularDataSupport instance, so changes to the TabularDataSupport instance are reflected in the collection, and vice-versa. The collection supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove(), Collection.remove(java.lang.Object), Collection.removeAll(java.util.Collection), Collection.retainAll(java.util.Collection), and Collection.clear() operations. It does not support the Collection.add(E) or Collection.addAll(java.util.Collection) operations.

IMPORTANT NOTICE: Do not use the setValue method of the Map.Entry elements contained in the returned collection view. Doing so would corrupt the index to row mappings contained in this TabularDataSupport instance.

Specified by:
entrySet in interface Map<Object,Object>
Returns:
a collection view (Set<Map.Entry<List<?>,CompositeData>>) of the mappings contained in this map.
See Also:
Map.Entry

clone

public Object clone()
Returns a clone of this TabularDataSupport instance: the clone is obtained by calling super.clone(), and then cloning the underlying map. Only a shallow clone of the underlying map is made, i.e. no cloning of the indexes and row values is made as they are immutable.

Overrides:
clone in class Object
Returns:
a clone of this instance.
See Also:
Cloneable

equals

public boolean equals(Object obj)
Compares the specified obj parameter with this TabularDataSupport instance for equality.

Returns true if and only if all of the following statements are true:

  • obj is non null,
  • obj also implements the TabularData interface,
  • their tabular types are equal
  • their contents (ie all CompositeData values) are equal.
This ensures that this equals method works properly for obj parameters which are different implementations of the TabularData interface.

Specified by:
equals in interface Map<Object,Object>
Specified by:
equals in interface TabularData
Overrides:
equals in class Object
Parameters:
obj - the object to be compared for equality with this TabularDataSupport instance;
Returns:
true if the specified object is equal to this TabularDataSupport instance.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns the hash code value for this TabularDataSupport instance.

The hash code of a TabularDataSupport instance is the sum of the hash codes of all elements of information used in equals comparisons (ie: its tabular type and its content, where the content is defined as all the CompositeData values).

This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two TabularDataSupport instances t1 and t2, as required by the general contract of the method Object.hashCode().

However, note that another instance of a class implementing the TabularData interface may be equal to this TabularDataSupport instance as defined by equals(java.lang.Object), but may have a different hash code if it is calculated differently.

Specified by:
hashCode in interface Map<Object,Object>
Specified by:
hashCode in interface TabularData
Overrides:
hashCode in class Object
Returns:
the hash code value for this TabularDataSupport instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Returns a string representation of this TabularDataSupport instance.

The string representation consists of the name of this class (ie javax.management.openmbean.TabularDataSupport), the string representation of the tabular type of this instance, and the string representation of the contents (ie list the key=value mappings as returned by a call to dataMap. toString()).

Specified by:
toString in interface TabularData
Overrides:
toString in class Object
Returns:
a string representation of this TabularDataSupport instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TabularType

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.management.openmbean
Class TabularType

java.lang.Object
    extended by  javax.management.openmbean.OpenType<TabularData>
        extended by  javax.management.openmbean.TabularType
All Implemented Interfaces:
Serializable
public class TabularType
extends OpenType<TabularData>

The TabularType class is the open type class whose instances describe the types of TabularData values.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.management.openmbean.OpenType
ALLOWED_CLASSNAMES, ALLOWED_CLASSNAMES_LIST
Constructor Summary
TabularType(String typeName, String description, CompositeType rowType, String[] indexNames)
Constructs a TabularType instance, checking for the validity of the given parameters.
Method Summary
boolean | equals(Object obj) Compares the specified obj parameter with this TabularType instance for equality.
List<String> | getIndexNames() Returns, in the same order as was given to this instance's constructor, an unmodifiable List of the names of the items the values of which are used to uniquely index each row element of tabular data values described by this TabularType instance.
CompositeType | getRowType() Returns the type of the row elements of tabular data values described by this TabularType instance.
int | hashCode() Returns the hash code value for this TabularType instance.
boolean | isValue(Object obj) Tests whether obj is a value which could be described by this TabularType instance.
String | toString() Returns a string representation of this TabularType instance.
Methods inherited from class javax.management.openmbean.OpenType
getClassName, getDescription, getTypeName, isArray
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

TabularType

public TabularType(String typeName,
                   String description,
                   CompositeType rowType,
                   String[] indexNames)
            throws OpenDataException
Constructs a TabularType instance, checking for the validity of the given parameters. The validity constraints are described below for each parameter.

The Java class name of tabular data values this tabular type represents (ie the class name returned by the getClassName method) is set to the string value returned by TabularData.class.getName().

Parameters:
typeName - The name given to the tabular type this instance represents; cannot be a null or empty string.
description - The human readable description of the tabular type this instance represents; cannot be a null or empty string.
rowType - The type of the row elements of tabular data values described by this tabular type instance; cannot be null.
indexNames - The names of the items the values of which are used to uniquely index each row element in the tabular data values described by this tabular type instance; cannot be null or empty. Each element should be an item name defined in rowType (no null or empty string allowed). It is important to note that the order of the item names in indexNames is used by the methods get and remove of class TabularData to match their array of values parameter to items.
Throws:
IllegalArgumentException - if rowType is null, or indexNames is a null or empty array, or an element in indexNames is a null or empty string, or typeName or description is a null or empty string.
OpenDataException - if an element's value of indexNames is not an item name defined in rowType.
Method Detail

getRowType

public CompositeType getRowType()
Returns the type of the row elements of tabular data values described by this TabularType instance.

Returns:
the type of each row.

getIndexNames

public List<String> getIndexNames()

Returns, in the same order as was given to this instance's constructor, an unmodifiable List of the names of the items the values of which are used to uniquely index each row element of tabular data values described by this TabularType instance.

Returns:
a List of String representing the names of the index items.

isValue

public boolean isValue(Object obj)
Tests whether obj is a value which could be described by this TabularType instance.

If obj is null or is not an instance of javax.management.openmbean.TabularData, isValue returns false.

If obj is an instance of javax.management.openmbean.TabularData, say td, the result is true if this TabularType is assignable from td.getTabularType(), as defined in CompositeType.isValue.

Specified by:
isValue in class OpenType<TabularData>
Parameters:
obj - the value whose open type is to be tested for compatibility with this TabularType instance.
Returns:
true if obj is a value for this tabular type, false otherwise.

equals

public boolean equals(Object obj)
Compares the specified obj parameter with this TabularType instance for equality.

Two TabularType instances are equal if and only if all of the following statements are true:

  • their type names are equal
  • their row types are equal
  • they use the same index names, in the same order

Specified by:
equals in class OpenType<TabularData>
Parameters:
obj - the object to be compared for equality with this TabularType instance; if obj is null, equals returns false.
Returns:
true if the specified object is equal to this TabularType instance.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns the hash code value for this TabularType instance.

The hash code of a TabularType instance is the sum of the hash codes of all elements of information used in equals comparisons (ie: name, row type, index names). This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two TabularType instances t1 and t2, as required by the general contract of the method Object.hashCode().

As TabularType instances are immutable, the hash code for this instance is calculated once, on the first call to hashCode, and then the same value is returned for subsequent calls.

Specified by:
hashCode in class OpenType<TabularData>
Returns:
the hash code value for this TabularType instance
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Returns a string representation of this TabularType instance.

The string representation consists of the name of this class (ie javax.management.openmbean.TabularType), the type name for this instance, the row type string representation of this instance, and the index names of this instance.

As TabularType instances are immutable, the string representation for this instance is calculated once, on the first call to toString, and then the same value is returned for subsequent calls.

Specified by:
toString in class OpenType<TabularData>
Returns:
a string representation of this TabularType instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


OperationsException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class OperationsException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.OperationsException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
AttributeNotFoundException, InstanceAlreadyExistsException, InstanceNotFoundException, IntrospectionException, InvalidAttributeValueException, ListenerNotFoundException, MalformedObjectNameException, NotCompliantMBeanException, ServiceNotFoundException
public class OperationsException
extends JMException

Represents exceptions thrown in the MBean server when performing operations on MBeans.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
OperationsException()
Default constructor.
OperationsException(String message)
Constructor that allows a specific error message to be specified.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

OperationsException

public OperationsException()
Default constructor.

OperationsException

public OperationsException(String message)
Constructor that allows a specific error message to be specified.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PersistentMBean

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Interface PersistentMBean

All Known Subinterfaces:
ModelMBean
All Known Implementing Classes:
RequiredModelMBean
public interface PersistentMBean

This class is the interface to be implemented by MBeans that are meant to be persistent. MBeans supporting this interface should call the load method during construction in order to prime the MBean from the persistent store. In the case of a ModelMBean, the store method should be called by the MBeanServer based on the descriptors in the ModelMBean or by the MBean itself during normal processing of the ModelMBean.

Since:
1.5

Method Summary
void | load() Instantiates thisMBean instance with the data found for the MBean in the persistent store.
void | store() Captures the current state of this MBean instance and writes it out to the persistent store.

Method Detail

load

void load()
          throws MBeanException,
                 RuntimeOperationsException,
                 InstanceNotFoundException
Instantiates thisMBean instance with the data found for the MBean in the persistent store. The data loaded could include attribute and operation values. This method should be called during construction or initialization of this instance, and before the MBean is registered with the MBeanServer.

Throws:
MBeanException - Wraps another exception or persistence is not supported
RuntimeOperationsException - Wraps exceptions from the persistence mechanism
InstanceNotFoundException - Could not find or load this MBean from persistent storage

store

void store()
           throws MBeanException,
                  RuntimeOperationsException,
                  InstanceNotFoundException
Captures the current state of this MBean instance and writes it out to the persistent store. The state stored could include attribute and operation values. If one of these methods of persistence is not supported a "serviceNotFound" exception will be thrown.

Persistence policy from the MBean and attribute descriptor is used to guide execution of this method. The MBean should be stored if 'persistPolicy' field is:

  != "never"
   = "always"
   = "onTimer" and now > 'lastPersistTime' + 'persistPeriod'
   = "NoMoreOftenThan" and now > 'lastPersistTime' + 'persistPeriod'
   = "onUnregister"

 Do not store the MBean if 'persistPolicy' field is:
    = "never"
    = "onUpdate"
    = "onTimer" && now < 'lastPersistTime' + 'persistPeriod'

Throws:
MBeanException - Wraps another exception or persistence is not supported
RuntimeOperationsException - Wraps exceptions from the persistence mechanism
InstanceNotFoundException - Could not find/access the persistent store
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Query

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class Query

java.lang.Object
    extended by  javax.management.Query

public class Query
extends Object

Constructs query object constraints. The static methods provided return query expressions that may be used in listing and enumerating MBeans. Individual constraint construction methods allow only appropriate types as arguments. Composition of calls can construct arbitrary nestings of constraints, as the following example illustrates:

 QueryExp exp = Query.and(Query.gt(Query.attr("age"),Query.value(5)),
                          Query.match(Query.attr("name"),
                                      Query.value("Smith")));

Since:
1.5

Field Summary
static int | DIV A code representing the div(javax.management.ValueExp, javax.management.ValueExp) expression.
static int | EQ A code representing the eq(javax.management.ValueExp, javax.management.ValueExp) query.
static int | GE A code representing the geq(javax.management.ValueExp, javax.management.ValueExp) query.
static int | GT A code representing the gt(javax.management.ValueExp, javax.management.ValueExp) query.
static int | LE A code representing the leq(javax.management.ValueExp, javax.management.ValueExp) query.
static int | LT A code representing the lt(javax.management.ValueExp, javax.management.ValueExp) query.
static int | MINUS A code representing the minus(javax.management.ValueExp, javax.management.ValueExp) expression.
static int | PLUS A code representing the plus(javax.management.ValueExp, javax.management.ValueExp) expression.
static int | TIMES A code representing the times(javax.management.ValueExp, javax.management.ValueExp) expression.
Constructor Summary
Query()
Basic constructor.
Method Summary
static QueryExp | and(QueryExp q1, QueryExp q2) Returns a query expression that is the conjunction of two other query expressions.
static QueryExp | anySubString(AttributeValueExp a, StringValueExp s) Returns a query expression that represents a matching constraint on a string argument.
static AttributeValueExp | attr(String name) Returns a new attribute expression.
static AttributeValueExp | attr(String className, String name) Returns a new qualified attribute expression.
static QueryExp | between(ValueExp v1, ValueExp v2, ValueExp v3) Returns a query expression that represents the constraint that one value is between two other values.
static AttributeValueExp | classattr() Returns a new class attribute expression which can be used in any Query call that expects a ValueExp.
static ValueExp | div(ValueExp value1, ValueExp value2) Returns a binary expression representing the quotient of two numeric values.
static QueryExp | eq(ValueExp v1, ValueExp v2) Returns a query expression that represents an equality constraint on two values.
static QueryExp | finalSubString(AttributeValueExp a, StringValueExp s) Returns a query expression that represents a matching constraint on a string argument.
static QueryExp | geq(ValueExp v1, ValueExp v2) Returns a query expression that represents a "greater than or equal to" constraint on two values.
static QueryExp | gt(ValueExp v1, ValueExp v2) Returns a query expression that represents a "greater than" constraint on two values.
static QueryExp | in(ValueExp val, ValueExp[] valueList) Returns an expression constraining a value to be one of an explicit list.
static QueryExp | initialSubString(AttributeValueExp a, StringValueExp s) Returns a query expression that represents a matching constraint on a string argument.
static QueryExp | isInstanceOf(StringValueExp classNameValue) Returns a query expression that represents an inheritance constraint on an MBean class.
static QueryExp | leq(ValueExp v1, ValueExp v2) Returns a query expression that represents a "less than or equal to" constraint on two values.
static QueryExp | lt(ValueExp v1, ValueExp v2) Returns a query expression that represents a "less than" constraint on two values.
static QueryExp | match(AttributeValueExp a, StringValueExp s) Returns a query expression that represents a matching constraint on a string argument.
static ValueExp | minus(ValueExp value1, ValueExp value2) Returns a binary expression representing the difference between two numeric values.
static QueryExp | not(QueryExp queryExp) Returns a constraint that is the negation of its argument.
static QueryExp | or(QueryExp q1, QueryExp q2) Returns a query expression that is the disjunction of two other query expressions.
static ValueExp | plus(ValueExp value1, ValueExp value2) Returns a binary expression representing the sum of two numeric values, or the concatenation of two string values.
static ValueExp | times(ValueExp value1, ValueExp value2) Returns a binary expression representing the product of two numeric values.
static ValueExp | value(boolean val) Returns a boolean value expression that can be used in any Query call that expects a ValueExp.
static ValueExp | value(double val) Returns a numeric value expression that can be used in any Query call that expects a ValueExp.
static ValueExp | value(float val) Returns a numeric value expression that can be used in any Query call that expects a ValueExp.
static ValueExp | value(int val) Returns a numeric value expression that can be used in any Query call that expects a ValueExp.
static ValueExp | value(long val) Returns a numeric value expression that can be used in any Query call that expects a ValueExp.
static ValueExp | value(Number val) Returns a numeric value expression that can be used in any Query call that expects a ValueExp.
static StringValueExp | value(String val) Returns a new string expression.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

GT

public static final int GT
A code representing the gt(javax.management.ValueExp, javax.management.ValueExp) query. This is chiefly of interest for the serialized form of queries.

See Also:
Constant Field Values

LT

public static final int LT
A code representing the lt(javax.management.ValueExp, javax.management.ValueExp) query. This is chiefly of interest for the serialized form of queries.

See Also:
Constant Field Values

GE

public static final int GE
A code representing the geq(javax.management.ValueExp, javax.management.ValueExp) query. This is chiefly of interest for the serialized form of queries.

See Also:
Constant Field Values

LE

public static final int LE
A code representing the leq(javax.management.ValueExp, javax.management.ValueExp) query. This is chiefly of interest for the serialized form of queries.

See Also:
Constant Field Values

EQ

public static final int EQ
A code representing the eq(javax.management.ValueExp, javax.management.ValueExp) query. This is chiefly of interest for the serialized form of queries.

See Also:
Constant Field Values

PLUS

public static final int PLUS
A code representing the plus(javax.management.ValueExp, javax.management.ValueExp) expression. This is chiefly of interest for the serialized form of queries.

See Also:
Constant Field Values

MINUS

public static final int MINUS
A code representing the minus(javax.management.ValueExp, javax.management.ValueExp) expression. This is chiefly of interest for the serialized form of queries.

See Also:
Constant Field Values

TIMES

public static final int TIMES
A code representing the times(javax.management.ValueExp, javax.management.ValueExp) expression. This is chiefly of interest for the serialized form of queries.

See Also:
Constant Field Values

DIV

public static final int DIV
A code representing the div(javax.management.ValueExp, javax.management.ValueExp) expression. This is chiefly of interest for the serialized form of queries.

See Also:
Constant Field Values
Constructor Detail

Query

public Query()
Basic constructor.

Method Detail

and

public static QueryExp and(QueryExp q1,
                           QueryExp q2)
Returns a query expression that is the conjunction of two other query expressions.

Parameters:
q1 - A query expression.
q2 - Another query expression.
Returns:
The conjunction of the two arguments. The returned object will be serialized as an instance of the non-public class javax.management.AndQueryExp.

or

public static QueryExp or(QueryExp q1,
                          QueryExp q2)
Returns a query expression that is the disjunction of two other query expressions.

Parameters:
q1 - A query expression.
q2 - Another query expression.
Returns:
The disjunction of the two arguments. The returned object will be serialized as an instance of the non-public class javax.management.OrQueryExp.

gt

public static QueryExp gt(ValueExp v1,
                          ValueExp v2)
Returns a query expression that represents a "greater than" constraint on two values.

Parameters:
v1 - A value expression.
v2 - Another value expression.
Returns:
A "greater than" constraint on the arguments. The returned object will be serialized as an instance of the non-public class javax.management.BinaryRelQueryExp with a relOp equal to GT.

geq

public static QueryExp geq(ValueExp v1,
                           ValueExp v2)
Returns a query expression that represents a "greater than or equal to" constraint on two values.

Parameters:
v1 - A value expression.
v2 - Another value expression.
Returns:
A "greater than or equal to" constraint on the arguments. The returned object will be serialized as an instance of the non-public class javax.management.BinaryRelQueryExp with a relOp equal to GE.

leq

public static QueryExp leq(ValueExp v1,
                           ValueExp v2)
Returns a query expression that represents a "less than or equal to" constraint on two values.

Parameters:
v1 - A value expression.
v2 - Another value expression.
Returns:
A "less than or equal to" constraint on the arguments. The returned object will be serialized as an instance of the non-public class javax.management.BinaryRelQueryExp with a relOp equal to LE.

lt

public static QueryExp lt(ValueExp v1,
                          ValueExp v2)
Returns a query expression that represents a "less than" constraint on two values.

Parameters:
v1 - A value expression.
v2 - Another value expression.
Returns:
A "less than" constraint on the arguments. The returned object will be serialized as an instance of the non-public class javax.management.BinaryRelQueryExp with a relOp equal to LT.

eq

public static QueryExp eq(ValueExp v1,
                          ValueExp v2)
Returns a query expression that represents an equality constraint on two values.

Parameters:
v1 - A value expression.
v2 - Another value expression.
Returns:
A "equal to" constraint on the arguments. The returned object will be serialized as an instance of the non-public class javax.management.BinaryRelQueryExp with a relOp equal to EQ.

between

public static QueryExp between(ValueExp v1,
                               ValueExp v2,
                               ValueExp v3)
Returns a query expression that represents the constraint that one value is between two other values.

Parameters:
v1 - A value expression that is "between" v2 and v3.
v2 - Value expression that represents a boundary of the constraint.
v3 - Value expression that represents a boundary of the constraint.
Returns:
The constraint that v1 lies between v2 and v3. The returned object will be serialized as an instance of the non-public class javax.management.BetweenQueryExp.

match

public static QueryExp match(AttributeValueExp a,
                             StringValueExp s)
Returns a query expression that represents a matching constraint on a string argument. The matching syntax is consistent with file globbing: supports "?", "*", "[", each of which may be escaped with "\"; character classes may use "!" for negation and "-" for range. (* for any character sequence, ? for a single arbitrary character, [...] for a character sequence). For example: a*b?c would match a string starting with the character a, followed by any number of characters, followed by a b, any single character, and a c.

Parameters:
a - An attribute expression
s - A string value expression representing a matching constraint
Returns:
A query expression that represents the matching constraint on the string argument. The returned object will be serialized as an instance of the non-public class javax.management.MatchQueryExp.

attr

public static AttributeValueExp attr(String name)

Returns a new attribute expression.

Evaluating this expression for a given objectName includes performing MBeanServer.getAttribute(objectName, name).

Parameters:
name - The name of the attribute.
Returns:
An attribute expression for the attribute named name.

attr

public static AttributeValueExp attr(String className,
                                     String name)

Returns a new qualified attribute expression.

Evaluating this expression for a given objectName includes performing MBeanServer.getObjectInstance(objectName) and MBeanServer.getAttribute(objectName, name).

Parameters:
className - The name of the class possessing the attribute.
name - The name of the attribute.
Returns:
An attribute expression for the attribute named name. The returned object will be serialized as an instance of the non-public class javax.management.QualifiedAttributeValueExp.

classattr

public static AttributeValueExp classattr()

Returns a new class attribute expression which can be used in any Query call that expects a ValueExp.

Evaluating this expression for a given objectName includes performing MBeanServer.getObjectInstance(objectName).

Returns:
A class attribute expression. The returned object will be serialized as an instance of the non-public class javax.management.ClassAttributeValueExp.

not

public static QueryExp not(QueryExp queryExp)
Returns a constraint that is the negation of its argument.

Parameters:
queryExp - The constraint to negate.
Returns:
A negated constraint. The returned object will be serialized as an instance of the non-public class javax.management.NotQueryExp.

in

public static QueryExp in(ValueExp val,
                          ValueExp[] valueList)
Returns an expression constraining a value to be one of an explicit list.

Parameters:
val - A value to be constrained.
valueList - An array of ValueExps.
Returns:
A QueryExp that represents the constraint. The returned object will be serialized as an instance of the non-public class javax.management.InQueryExp.

value

public static StringValueExp value(String val)
Returns a new string expression.

Parameters:
val - The string value.
Returns:
A ValueExp object containing the string argument.

value

public static ValueExp value(Number val)
Returns a numeric value expression that can be used in any Query call that expects a ValueExp.

Parameters:
val - An instance of Number.
Returns:
A ValueExp object containing the argument. The returned object will be serialized as an instance of the non-public class javax.management.NumericValueExp.

value

public static ValueExp value(int val)
Returns a numeric value expression that can be used in any Query call that expects a ValueExp.

Parameters:
val - An int value.
Returns:
A ValueExp object containing the argument. The returned object will be serialized as an instance of the non-public class javax.management.NumericValueExp.

value

public static ValueExp value(long val)
Returns a numeric value expression that can be used in any Query call that expects a ValueExp.

Parameters:
val - A long value.
Returns:
A ValueExp object containing the argument. The returned object will be serialized as an instance of the non-public class javax.management.NumericValueExp.

value

public static ValueExp value(float val)
Returns a numeric value expression that can be used in any Query call that expects a ValueExp.

Parameters:
val - A float value.
Returns:
A ValueExp object containing the argument. The returned object will be serialized as an instance of the non-public class javax.management.NumericValueExp.

value

public static ValueExp value(double val)
Returns a numeric value expression that can be used in any Query call that expects a ValueExp.

Parameters:
val - A double value.
Returns:
A ValueExp object containing the argument. The returned object will be serialized as an instance of the non-public class javax.management.NumericValueExp.

value

public static ValueExp value(boolean val)
Returns a boolean value expression that can be used in any Query call that expects a ValueExp.

Parameters:
val - A boolean value.
Returns:
A ValueExp object containing the argument. The returned object will be serialized as an instance of the non-public class javax.management.BooleanValueExp.

plus

public static ValueExp plus(ValueExp value1,
                            ValueExp value2)
Returns a binary expression representing the sum of two numeric values, or the concatenation of two string values.

Parameters:
value1 - The first '+' operand.
value2 - The second '+' operand.
Returns:
A ValueExp representing the sum or concatenation of the two arguments. The returned object will be serialized as an instance of the non-public class javax.management.BinaryOpValueExp with an op equal to PLUS.

times

public static ValueExp times(ValueExp value1,
                             ValueExp value2)
Returns a binary expression representing the product of two numeric values.

Parameters:
value1 - The first '*' operand.
value2 - The second '*' operand.
Returns:
A ValueExp representing the product. The returned object will be serialized as an instance of the non-public class javax.management.BinaryOpValueExp with an op equal to TIMES.

minus

public static ValueExp minus(ValueExp value1,
                             ValueExp value2)
Returns a binary expression representing the difference between two numeric values.

Parameters:
value1 - The first '-' operand.
value2 - The second '-' operand.
Returns:
A ValueExp representing the difference between two arguments. The returned object will be serialized as an instance of the non-public class javax.management.BinaryOpValueExp with an op equal to MINUS.

div

public static ValueExp div(ValueExp value1,
                           ValueExp value2)
Returns a binary expression representing the quotient of two numeric values.

Parameters:
value1 - The first '/' operand.
value2 - The second '/' operand.
Returns:
A ValueExp representing the quotient of two arguments. The returned object will be serialized as an instance of the non-public class javax.management.BinaryOpValueExp with an op equal to DIV.

initialSubString

public static QueryExp initialSubString(AttributeValueExp a,
                                        StringValueExp s)
Returns a query expression that represents a matching constraint on a string argument. The value must start with the given literal string value.

Parameters:
a - An attribute expression.
s - A string value expression representing the beginning of the string value.
Returns:
The constraint that a matches s. The returned object will be serialized as an instance of the non-public class javax.management.MatchQueryExp.

anySubString

public static QueryExp anySubString(AttributeValueExp a,
                                    StringValueExp s)
Returns a query expression that represents a matching constraint on a string argument. The value must contain the given literal string value.

Parameters:
a - An attribute expression.
s - A string value expression representing the substring.
Returns:
The constraint that a matches s. The returned object will be serialized as an instance of the non-public class javax.management.MatchQueryExp.

finalSubString

public static QueryExp finalSubString(AttributeValueExp a,
                                      StringValueExp s)
Returns a query expression that represents a matching constraint on a string argument. The value must end with the given literal string value.

Parameters:
a - An attribute expression.
s - A string value expression representing the end of the string value.
Returns:
The constraint that a matches s. The returned object will be serialized as an instance of the non-public class javax.management.MatchQueryExp.

isInstanceOf

public static QueryExp isInstanceOf(StringValueExp classNameValue)
Returns a query expression that represents an inheritance constraint on an MBean class.

Example: to find MBeans that are instances of NotificationBroadcaster, use Query.isInstanceOf(Query.value(NotificationBroadcaster.class.getName())).

Evaluating this expression for a given objectName includes performing MBeanServer.isInstanceOf(objectName, ((StringValueExp)classNameValue.apply(objectName)).getValue().

Parameters:
classNameValue - The StringValueExp returning the name of the class of which selected MBeans should be instances.
Returns:
a query expression that represents an inheritance constraint on an MBean class. The returned object will be serialized as an instance of the non-public class javax.management.InstanceOfQueryExp.
Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


QueryEval

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class QueryEval

java.lang.Object
    extended by  javax.management.QueryEval
All Implemented Interfaces:
Serializable
public abstract class QueryEval
extends Object
implements Serializable

Allows a query to be performed in the context of a specific MBean server.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
QueryEval()
Method Summary
static MBeanServer | getMBeanServer() Return the MBean server that was most recently given to the setMBeanServer method by this thread.
void | setMBeanServer(MBeanServer s) Sets the MBean server on which the query is to be performed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

QueryEval

public QueryEval()
Method Detail

setMBeanServer

public void setMBeanServer(MBeanServer s)

Sets the MBean server on which the query is to be performed. The setting is valid for the thread performing the set. It is copied to any threads created by that thread at the moment of their creation.

For historical reasons, this method is not static, but its behavior does not depend on the instance on which it is called.

Parameters:
s - The MBean server on which the query is to be performed.
See Also:
getMBeanServer()

getMBeanServer

public static MBeanServer getMBeanServer()

Return the MBean server that was most recently given to the setMBeanServer method by this thread. If this thread never called that method, the result is the value its parent thread would have obtained from getMBeanServer at the moment of the creation of this thread, or null if there is no parent thread.

Returns:
the MBean server.
See Also:
setMBeanServer(javax.management.MBeanServer)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


QueryExp

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Interface QueryExp

All Superinterfaces:
Serializable
All Known Implementing Classes:
ObjectName
public interface QueryExp
extends Serializable

Represents relational constraints that can be used in database query "where clauses". Instances of QueryExp are returned by the static methods of the Query class.

It is possible, but not recommended, to create custom queries by implementing this interface. In that case, it is better to extend the QueryEval class than to implement the interface directly, so that the setMBeanServer(javax.management.MBeanServer) method works correctly.

Since:
1.5

Method Summary
boolean | apply(ObjectName name) Applies the QueryExp on an MBean.
void | setMBeanServer(MBeanServer s) Sets the MBean server on which the query is to be performed.

Method Detail

apply

boolean apply(ObjectName name)
              throws BadStringOperationException,
                     BadBinaryOpValueExpException,
                     BadAttributeValueExpException,
                     InvalidApplicationException
Applies the QueryExp on an MBean.

Parameters:
name - The name of the MBean on which the QueryExp will be applied.
Returns:
True if the query was successfully applied to the MBean, false otherwise
Throws:
BadStringOperationException
BadBinaryOpValueExpException
BadAttributeValueExpException
InvalidApplicationException

setMBeanServer

void setMBeanServer(MBeanServer s)
Sets the MBean server on which the query is to be performed.

Parameters:
s - The MBean server on which the query is to be performed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ReflectionException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class ReflectionException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.ReflectionException
All Implemented Interfaces:
Serializable
public class ReflectionException
extends JMException

Represents exceptions thrown in the MBean server when using the java.lang.reflect classes to invoke methods on MBeans. It "wraps" the actual java.lang.Exception thrown.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
ReflectionException(Exception e)
Creates a ReflectionException that wraps the actual java.lang.Exception.
ReflectionException(Exception e, String message)
Creates a ReflectionException that wraps the actual java.lang.Exception with a detail message.
Method Summary
Throwable | getCause() Returns the actual Exception thrown.
Exception | getTargetException() Returns the actual Exception thrown.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ReflectionException

public ReflectionException(Exception e)
Creates a ReflectionException that wraps the actual java.lang.Exception.

Parameters:
e - the wrapped exception.

ReflectionException

public ReflectionException(Exception e,
                           String message)
Creates a ReflectionException that wraps the actual java.lang.Exception with a detail message.

Parameters:
e - the wrapped exception.
message - the detail message.
Method Detail

getTargetException

public Exception getTargetException()
Returns the actual Exception thrown.

Returns:
the wrapped Exception.

getCause

public Throwable getCause()
Returns the actual Exception thrown.

Overrides:
getCause in class Throwable
Returns:
the wrapped Exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


relation

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.management.relation

Provides the definition of the Relation Service.

See:
Description

Interface Summary
Relation | This interface has to be implemented by any MBean class expected to represent a relation managed using the Relation Service.
RelationServiceMBean | The Relation Service is in charge of creating and deleting relation types and relations, of handling the consistency and of providing query mechanisms.
RelationSupportMBean | A RelationSupport object is used internally by the Relation Service to represent simple relations (only roles, no properties or methods), with an unlimited number of roles, of any relation type.
RelationType | The RelationType interface has to be implemented by any class expected to represent a relation type.

Class Summary
MBeanServerNotificationFilter | Filter for MBeanServerNotification.
RelationNotification | A notification of a change in the Relation Service.
RelationService | The Relation Service is in charge of creating and deleting relation types and relations, of handling the consistency and of providing query mechanisms.
RelationSupport | A RelationSupport object is used internally by the Relation Service to represent simple relations (only roles, no properties or methods), with an unlimited number of roles, of any relation type.
RelationTypeSupport | A RelationTypeSupport object implements the RelationType interface.
Role | Represents a role: includes a role name and referenced MBeans (via their ObjectNames).
RoleInfo | A RoleInfo object summarises a role in a relation type.
RoleList | A RoleList represents a list of roles (Role objects).
RoleResult | Represents the result of a multiple access to several roles of a relation (either for reading or writing).
RoleStatus | This class describes the various problems which can be encountered when accessing a role.
RoleUnresolved | Represents an unresolved role: a role not retrieved from a relation due to a problem.
RoleUnresolvedList | A RoleUnresolvedList represents a list of RoleUnresolved objects, representing roles not retrieved from a relation due to a problem encountered when trying to access (read or write) the roles.

Exception Summary
InvalidRelationIdException | This exception is raised when relation id provided for a relation is already used.
InvalidRelationServiceException | This exception is raised when an invalid Relation Service is provided.
InvalidRelationTypeException | Invalid relation type.
InvalidRoleInfoException | This exception is raised when, in a role info, its minimum degree is greater than its maximum degree.
InvalidRoleValueException | Role value is invalid.
RelationException | This class is the superclass of any exception which can be raised during relation management.
RelationNotFoundException | This exception is raised when there is no relation for a given relation id in a Relation Service.
RelationServiceNotRegisteredException | This exception is raised when an access is done to the Relation Service and that one is not registered.
RelationTypeNotFoundException | This exception is raised when there is no relation type with given name in Relation Service.
RoleInfoNotFoundException | This exception is raised when there is no role info with given name in a given relation type.
RoleNotFoundException | This exception is raised when a role in a relation does not exist, or is not readable, or is not settable.

Package javax.management.relation Description

Provides the definition of the Relation Service. The Relation Service is used to record relationships between MBeans in an MBean Server. The Relation Service is itself an MBean. More than one instance of a RelationService MBean can be registered in an MBean Server.

A relation type defines a relationship between MBeans. It contains roles that the MBeans play in the relationship. Usually there are at least two roles in a relation type.

A relation is a named instance of a relation type, where specific MBeans appear in the roles, represented by their ObjectNames.

For example, suppose there are Module MBeans, representing modules within an application. A DependsOn relation type could express the relationship that some modules depend on others, which could be used to determine the order in which the modules are started or stopped. The DependsOn relation type would have two roles, dependent and dependedOn.

Every role is typed, meaning that an MBean that appears in that role must be an instance of the role's type. In the DependsOn example, both roles would be of type Module.

Every role has a cardinality, which provides lower and upper bounds on the number of MBeans that can appear in that role in a given relation instance. Usually, the lower and upper bounds are both 1, with exactly one MBean appearing in the role. The cardinality only limits the number of MBeans in the role per relation instance. The same MBean can appear in the same role in any number of instances of a relation type. In the DependsOn example, a given module can depend on many other modules, and be depended on by many others, but any given relation instance links exactly one dependent module with exactly one dependedOn module.

A relation type can be created explicitly, as an object implementing the RelationType interface, typically a RelationTypeSupport. Alternatively, it can be created implicitly using the Relation Service's createRelationType method.

A relation instance can be created explicitly, as an object implementing the Relation interface, typically a RelationSupport. (A RelationSupport is itself a valid MBean, so it can be registered in the MBean Server, though this is not required.) Alternatively, a relation instance can be created implicitly using the Relation Service's createRelation method.

The DependsOn example might be coded as follows.

import java.util.*;
import javax.management.*;
import javax.management.relation.*;

// ...
MBeanServer mbs = ...;

// Create the Relation Service MBean
ObjectName relSvcName = new ObjectName(":type=RelationService");
RelationService relSvcObject = new RelationService(true);
mbs.registerMBean(relSvcObject, relSvcName);

// Create an MBean proxy for easier access to the Relation Service
RelationServiceMBean relSvc =
    MBeanServerInvocationHandler.newProxyInstance(mbs, relSvcName,
                                                  RelationServiceMBean.class,
                                                  false);

// Define the DependsOn relation type
RoleInfo[] dependsOnRoles = {
    new RoleInfo("dependent", Module.class.getName()),
    new RoleInfo("dependedOn", Module.class.getName())
};
relSvc.createRelationType("DependsOn", dependsOnRoles);

// Now define a relation instance "moduleA DependsOn moduleB"

ObjectName moduleA = new ObjectName(":type=Module,name=A");
ObjectName moduleB = new ObjectName(":type=Module,name=B");

Role dependent = new Role("dependent", Collections.singletonList(moduleA));
Role dependedOn = new Role("dependedOn", Collections.singletonList(moduleB));
Role[] roleArray = {dependent, dependedOn};
RoleList roles = new RoleList(Arrays.asList(roleArray));
relSvc.createRelation("A-DependsOn-B", "DependsOn", roles);

// Query the Relation Service to find what modules moduleA depends on
Map<ObjectName,List<String>> dependentAMap =
    relSvc.findAssociatedMBeans(moduleA, "DependsOn", "dependent");
Set<ObjectName> dependentASet = dependentAMap.keySet();
// Set of ObjectName containing moduleB

Since:
1.5
See Also:
Java SE 6 Platform documentation on JMX technology, in particular the JMX Specification, version 1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.management.relation Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.management.relation

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.util.AbstractCollection<E> (implements java.util.Collection<E>)
      • java.util.AbstractList<E> (implements java.util.List<E>)
        • java.util.ArrayList<E> (implements java.lang.Cloneable, java.util.List<E>, java.util.RandomAccess, java.io.Serializable)
          • javax.management.relation.RoleList
          • javax.management.relation.RoleUnresolvedList
    • java.util.EventObject (implements java.io.Serializable)
      • javax.management.Notification
        • javax.management.relation.RelationNotification
    • javax.management.NotificationBroadcasterSupport (implements javax.management.NotificationEmitter)
      • javax.management.relation.RelationService (implements javax.management.MBeanRegistration, javax.management.NotificationListener, javax.management.relation.RelationServiceMBean)
    • javax.management.NotificationFilterSupport (implements javax.management.NotificationFilter)
      • javax.management.relation.MBeanServerNotificationFilter
    • javax.management.relation.RelationSupport (implements javax.management.MBeanRegistration, javax.management.relation.RelationSupportMBean)
    • javax.management.relation.RelationTypeSupport (implements javax.management.relation.RelationType)
    • javax.management.relation.Role (implements java.io.Serializable)
    • javax.management.relation.RoleInfo (implements java.io.Serializable)
    • javax.management.relation.RoleResult (implements java.io.Serializable)
    • javax.management.relation.RoleStatus
    • javax.management.relation.RoleUnresolved (implements java.io.Serializable)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.management.JMException
          • javax.management.relation.RelationException
            • javax.management.relation.InvalidRelationIdException
            • javax.management.relation.InvalidRelationServiceException
            • javax.management.relation.InvalidRelationTypeException
            • javax.management.relation.InvalidRoleInfoException
            • javax.management.relation.InvalidRoleValueException
            • javax.management.relation.RelationNotFoundException
            • javax.management.relation.RelationServiceNotRegisteredException
            • javax.management.relation.RelationTypeNotFoundException
            • javax.management.relation.RoleInfoNotFoundException
            • javax.management.relation.RoleNotFoundException

Interface Hierarchy

  • javax.management.relation.Relation
    • javax.management.relation.RelationSupportMBean
  • javax.management.relation.RelationServiceMBean
  • java.io.Serializable
    • javax.management.relation.RelationType
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.management.relation

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.management.relation

Packages that use javax.management.relation
javax.management.relation Provides the definition of the Relation Service.

Classes in javax.management.relation used by javax.management.relation
InvalidRelationIdException
This exception is raised when relation id provided for a relation is already used.
InvalidRelationServiceException
This exception is raised when an invalid Relation Service is provided.
InvalidRelationTypeException
Invalid relation type.
InvalidRoleInfoException
This exception is raised when, in a role info, its minimum degree is greater than its maximum degree.
InvalidRoleValueException
Role value is invalid.
Relation
This interface has to be implemented by any MBean class expected to represent a relation managed using the Relation Service.
RelationException
This class is the superclass of any exception which can be raised during relation management.
RelationNotFoundException
This exception is raised when there is no relation for a given relation id in a Relation Service.
RelationServiceMBean
The Relation Service is in charge of creating and deleting relation types and relations, of handling the consistency and of providing query mechanisms.
RelationServiceNotRegisteredException
This exception is raised when an access is done to the Relation Service and that one is not registered.
RelationSupportMBean
A RelationSupport object is used internally by the Relation Service to represent simple relations (only roles, no properties or methods), with an unlimited number of roles, of any relation type.
RelationType
The RelationType interface has to be implemented by any class expected to represent a relation type.
RelationTypeNotFoundException
This exception is raised when there is no relation type with given name in Relation Service.
Role
Represents a role: includes a role name and referenced MBeans (via their ObjectNames).
RoleInfo
A RoleInfo object summarises a role in a relation type.
RoleInfoNotFoundException
This exception is raised when there is no role info with given name in a given relation type.
RoleList
A RoleList represents a list of roles (Role objects).
RoleNotFoundException
This exception is raised when a role in a relation does not exist, or is not readable, or is not settable.
RoleResult
Represents the result of a multiple access to several roles of a relation (either for reading or writing).
RoleUnresolved
Represents an unresolved role: a role not retrieved from a relation due to a problem.
RoleUnresolvedList
A RoleUnresolvedList represents a list of RoleUnresolved objects, representing roles not retrieved from a relation due to a problem encountered when trying to access (read or write) the roles.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.InvalidRelationIdException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.InvalidRelationIdException

Packages that use InvalidRelationIdException
javax.management.relation Provides the definition of the Relation Service.

Uses of InvalidRelationIdException in javax.management.relation

Methods in javax.management.relation that throw InvalidRelationIdException
void | RelationServiceMBean.addRelation(ObjectName relationObjectName) Adds an MBean created by the user (and registered by him in the MBean Server) as a relation in the Relation Service.
void | RelationService.addRelation(ObjectName relationObjectName) Adds an MBean created by the user (and registered by him in the MBean Server) as a relation in the Relation Service.
void | RelationServiceMBean.createRelation(String relationId, String relationTypeName, RoleList roleList) Creates a simple relation (represented by a RelationSupport object) of given relation type, and adds it in the Relation Service.
void | RelationService.createRelation(String relationId, String relationTypeName, RoleList roleList) Creates a simple relation (represented by a RelationSupport object) of given relation type, and adds it in the Relation Service.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.InvalidRelationServiceException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.InvalidRelationServiceException

Packages that use InvalidRelationServiceException
javax.management.relation Provides the definition of the Relation Service.

Uses of InvalidRelationServiceException in javax.management.relation

Methods in javax.management.relation that throw InvalidRelationServiceException
void | RelationServiceMBean.addRelation(ObjectName relationObjectName) Adds an MBean created by the user (and registered by him in the MBean Server) as a relation in the Relation Service.
void | RelationService.addRelation(ObjectName relationObjectName) Adds an MBean created by the user (and registered by him in the MBean Server) as a relation in the Relation Service.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.InvalidRelationTypeException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.InvalidRelationTypeException

Packages that use InvalidRelationTypeException
javax.management.relation Provides the definition of the Relation Service.

Uses of InvalidRelationTypeException in javax.management.relation

Methods in javax.management.relation that throw InvalidRelationTypeException
void | RelationServiceMBean.addRelationType(RelationType relationTypeObj) Adds given object as a relation type.
void | RelationService.addRelationType(RelationType relationTypeObj) Adds given object as a relation type.
protected void | RelationTypeSupport.addRoleInfo(RoleInfo roleInfo) Add a role info.
void | RelationServiceMBean.createRelationType(String relationTypeName, RoleInfo[] roleInfoArray) Creates a relation type (RelationTypeSupport object) with given role infos (provided by the RoleInfo objects), and adds it in the Relation Service.
void | RelationService.createRelationType(String relationTypeName, RoleInfo[] roleInfoArray) Creates a relation type (a RelationTypeSupport object) with given role infos (provided by the RoleInfo objects), and adds it in the Relation Service.

Constructors in javax.management.relation that throw InvalidRelationTypeException
RelationTypeSupport(String relationTypeName, RoleInfo[] roleInfoArray)
Constructor where all role definitions are dynamically created and passed as parameter.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.InvalidRoleInfoException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.InvalidRoleInfoException

Packages that use InvalidRoleInfoException
javax.management.relation Provides the definition of the Relation Service.

Uses of InvalidRoleInfoException in javax.management.relation

Constructors in javax.management.relation that throw InvalidRoleInfoException
RoleInfo(String roleName, String mbeanClassName, boolean read, boolean write, int min, int max, String descr)
Constructor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.InvalidRoleValueException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.InvalidRoleValueException

Packages that use InvalidRoleValueException
javax.management.relation Provides the definition of the Relation Service.

Uses of InvalidRoleValueException in javax.management.relation

Methods in javax.management.relation that throw InvalidRoleValueException
void | RelationServiceMBean.addRelation(ObjectName relationObjectName) Adds an MBean created by the user (and registered by him in the MBean Server) as a relation in the Relation Service.
void | RelationService.addRelation(ObjectName relationObjectName) Adds an MBean created by the user (and registered by him in the MBean Server) as a relation in the Relation Service.
void | RelationServiceMBean.createRelation(String relationId, String relationTypeName, RoleList roleList) Creates a simple relation (represented by a RelationSupport object) of given relation type, and adds it in the Relation Service.
void | RelationService.createRelation(String relationId, String relationTypeName, RoleList roleList) Creates a simple relation (represented by a RelationSupport object) of given relation type, and adds it in the Relation Service.
void | RelationSupport.handleMBeanUnregistration(ObjectName objectName, String roleName) Callback used by the Relation Service when a MBean referenced in a role is unregistered.
void | Relation.handleMBeanUnregistration(ObjectName objectName, String roleName) Callback used by the Relation Service when a MBean referenced in a role is unregistered.
void | RelationSupport.setRole(Role role) Sets the given role.
void | Relation.setRole(Role role) Sets the given role.
void | RelationServiceMBean.setRole(String relationId, Role role) Sets the given role in given relation.
void | RelationService.setRole(String relationId, Role role) Sets the given role in given relation.

Constructors in javax.management.relation that throw InvalidRoleValueException
RelationSupport(String relationId, ObjectName relationServiceName, MBeanServer relationServiceMBeanServer, String relationTypeName, RoleList list)
Creates a RelationSupport object.
RelationSupport(String relationId, ObjectName relationServiceName, String relationTypeName, RoleList list)
Creates a RelationSupport object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.MBeanServerNotificationFilter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.MBeanServerNotificationFilter

No usage of javax.management.relation.MBeanServerNotificationFilter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.RelationException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.RelationException

Packages that use RelationException
javax.management.relation Provides the definition of the Relation Service.

Uses of RelationException in javax.management.relation

Subclasses of RelationException in javax.management.relation
class | InvalidRelationIdException This exception is raised when relation id provided for a relation is already used.
class | InvalidRelationServiceException This exception is raised when an invalid Relation Service is provided.
class | InvalidRelationTypeException Invalid relation type.
class | InvalidRoleInfoException This exception is raised when, in a role info, its minimum degree is greater than its maximum degree.
class | InvalidRoleValueException Role value is invalid.
class | RelationNotFoundException This exception is raised when there is no relation for a given relation id in a Relation Service.
class | RelationServiceNotRegisteredException This exception is raised when an access is done to the Relation Service and that one is not registered.
class | RelationTypeNotFoundException This exception is raised when there is no relation type with given name in Relation Service.
class | RoleInfoNotFoundException This exception is raised when there is no role info with given name in a given relation type.
class | RoleNotFoundException This exception is raised when a role in a relation does not exist, or is not readable, or is not settable.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.RelationNotFoundException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.RelationNotFoundException

Packages that use RelationNotFoundException
javax.management.relation Provides the definition of the Relation Service.

Uses of RelationNotFoundException in javax.management.relation

Methods in javax.management.relation that throw RelationNotFoundException
RoleResult | RelationServiceMBean.getAllRoles(String relationId) Returns all roles present in the relation.
RoleResult | RelationService.getAllRoles(String relationId) Returns all roles present in the relation.
Map<ObjectName,List<String>> | RelationServiceMBean.getReferencedMBeans(String relationId) Retrieves MBeans referenced in the various roles of the relation.
Map<ObjectName,List<String>> | RelationService.getReferencedMBeans(String relationId) Retrieves MBeans referenced in the various roles of the relation.
String | RelationServiceMBean.getRelationTypeName(String relationId) Returns name of associated relation type for given relation.
String | RelationService.getRelationTypeName(String relationId) Returns name of associated relation type for given relation.
List<ObjectName> | RelationServiceMBean.getRole(String relationId, String roleName) Retrieves role value for given role name in given relation.
List<ObjectName> | RelationService.getRole(String relationId, String roleName) Retrieves role value for given role name in given relation.
Integer | RelationServiceMBean.getRoleCardinality(String relationId, String roleName) Retrieves the number of MBeans currently referenced in the given role.
Integer | RelationService.getRoleCardinality(String relationId, String roleName) Retrieves the number of MBeans currently referenced in the given role.
RoleResult | RelationServiceMBean.getRoles(String relationId, String[] roleNameArray) Retrieves values of roles with given names in given relation.
RoleResult | RelationService.getRoles(String relationId, String[] roleNameArray) Retrieves values of roles with given names in given relation.
void | RelationSupport.handleMBeanUnregistration(ObjectName objectName, String roleName) Callback used by the Relation Service when a MBean referenced in a role is unregistered.
void | Relation.handleMBeanUnregistration(ObjectName objectName, String roleName) Callback used by the Relation Service when a MBean referenced in a role is unregistered.
ObjectName | RelationServiceMBean.isRelationMBean(String relationId) If the relation is represented by an MBean (created by the user and added as a relation in the Relation Service), returns the ObjectName of the MBean.
ObjectName | RelationService.isRelationMBean(String relationId) If the relation is represented by an MBean (created by the user and added as a relation in the Relation Service), returns the ObjectName of the MBean.
void | RelationServiceMBean.removeRelation(String relationId) Removes given relation from the Relation Service.
void | RelationService.removeRelation(String relationId) Removes given relation from the Relation Service.
void | RelationServiceMBean.sendRelationCreationNotification(String relationId) Sends a notification (RelationNotification) for a relation creation.
void | RelationService.sendRelationCreationNotification(String relationId) Sends a notification (RelationNotification) for a relation creation.
void | RelationServiceMBean.sendRelationRemovalNotification(String relationId, List<ObjectName> unregMBeanList) Sends a notification (RelationNotification) for a relation removal.
void | RelationService.sendRelationRemovalNotification(String relationId, List<ObjectName> unregMBeanList) Sends a notification (RelationNotification) for a relation removal.
void | RelationServiceMBean.sendRoleUpdateNotification(String relationId, Role newRole, List<ObjectName> oldRoleValue) Sends a notification (RelationNotification) for a role update in the given relation.
void | RelationService.sendRoleUpdateNotification(String relationId, Role newRole, List<ObjectName> oldValue) Sends a notification (RelationNotification) for a role update in the given relation.
void | RelationSupport.setRole(Role role) Sets the given role.
void | Relation.setRole(Role role) Sets the given role.
void | RelationServiceMBean.setRole(String relationId, Role role) Sets the given role in given relation.
void | RelationService.setRole(String relationId, Role role) Sets the given role in given relation.
RoleResult | RelationSupport.setRoles(RoleList list) Sets the given roles.
RoleResult | Relation.setRoles(RoleList roleList) Sets the given roles.
RoleResult | RelationServiceMBean.setRoles(String relationId, RoleList roleList) Sets the given roles in given relation.
RoleResult | RelationService.setRoles(String relationId, RoleList roleList) Sets the given roles in given relation.
void | RelationServiceMBean.updateRoleMap(String relationId, Role newRole, List<ObjectName> oldRoleValue) Handles update of the Relation Service role map for the update of given role in given relation.
void | RelationService.updateRoleMap(String relationId, Role newRole, List<ObjectName> oldValue) Handles update of the Relation Service role map for the update of given role in given relation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.RelationNotification

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.RelationNotification

No usage of javax.management.relation.RelationNotification

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.RelationService

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.RelationService

No usage of javax.management.relation.RelationService

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.RelationServiceNotRegisteredException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.RelationServiceNotRegisteredException

Packages that use RelationServiceNotRegisteredException
javax.management.relation Provides the definition of the Relation Service.

Uses of RelationServiceNotRegisteredException in javax.management.relation

Methods in javax.management.relation that throw RelationServiceNotRegisteredException
void | RelationServiceMBean.addRelation(ObjectName relationObjectName) Adds an MBean created by the user (and registered by him in the MBean Server) as a relation in the Relation Service.
void | RelationService.addRelation(ObjectName relationObjectName) Adds an MBean created by the user (and registered by him in the MBean Server) as a relation in the Relation Service.
void | RelationServiceMBean.createRelation(String relationId, String relationTypeName, RoleList roleList) Creates a simple relation (represented by a RelationSupport object) of given relation type, and adds it in the Relation Service.
void | RelationService.createRelation(String relationId, String relationTypeName, RoleList roleList) Creates a simple relation (represented by a RelationSupport object) of given relation type, and adds it in the Relation Service.
RoleResult | RelationSupport.getAllRoles() Returns all roles present in the relation.
RoleResult | Relation.getAllRoles() Returns all roles present in the relation.
RoleResult | RelationServiceMBean.getAllRoles(String relationId) Returns all roles present in the relation.
RoleResult | RelationService.getAllRoles(String relationId) Returns all roles present in the relation.
List<ObjectName> | RelationSupport.getRole(String roleName) Retrieves role value for given role name.
List<ObjectName> | Relation.getRole(String roleName) Retrieves role value for given role name.
List<ObjectName> | RelationServiceMBean.getRole(String relationId, String roleName) Retrieves role value for given role name in given relation.
List<ObjectName> | RelationService.getRole(String relationId, String roleName) Retrieves role value for given role name in given relation.
RoleResult | RelationSupport.getRoles(String[] roleNameArray) Retrieves values of roles with given names.
RoleResult | Relation.getRoles(String[] roleNameArray) Retrieves values of roles with given names.
RoleResult | RelationServiceMBean.getRoles(String relationId, String[] roleNameArray) Retrieves values of roles with given names in given relation.
RoleResult | RelationService.getRoles(String relationId, String[] roleNameArray) Retrieves values of roles with given names in given relation.
void | RelationSupport.handleMBeanUnregistration(ObjectName objectName, String roleName) Callback used by the Relation Service when a MBean referenced in a role is unregistered.
void | Relation.handleMBeanUnregistration(ObjectName objectName, String roleName) Callback used by the Relation Service when a MBean referenced in a role is unregistered.
void | RelationServiceMBean.isActive() Checks if the Relation Service is active.
void | RelationService.isActive() Checks if the Relation Service is active.
void | RelationServiceMBean.purgeRelations() Purges the relations.
void | RelationService.purgeRelations() Purges the relations.
void | RelationServiceMBean.removeRelation(String relationId) Removes given relation from the Relation Service.
void | RelationService.removeRelation(String relationId) Removes given relation from the Relation Service.
void | RelationServiceMBean.removeRelationType(String relationTypeName) Removes given relation type from Relation Service.
void | RelationService.removeRelationType(String relationTypeName) Removes given relation type from Relation Service.
void | RelationSupport.setRole(Role role) Sets the given role.
void | Relation.setRole(Role role) Sets the given role.
void | RelationServiceMBean.setRole(String relationId, Role role) Sets the given role in given relation.
void | RelationService.setRole(String relationId, Role role) Sets the given role in given relation.
RoleResult | RelationSupport.setRoles(RoleList list) Sets the given roles.
RoleResult | Relation.setRoles(RoleList roleList) Sets the given roles.
RoleResult | RelationServiceMBean.setRoles(String relationId, RoleList roleList) Sets the given roles in given relation.
RoleResult | RelationService.setRoles(String relationId, RoleList roleList) Sets the given roles in given relation.
void | RelationServiceMBean.updateRoleMap(String relationId, Role newRole, List<ObjectName> oldRoleValue) Handles update of the Relation Service role map for the update of given role in given relation.
void | RelationService.updateRoleMap(String relationId, Role newRole, List<ObjectName> oldValue) Handles update of the Relation Service role map for the update of given role in given relation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.RelationSupport

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.RelationSupport

No usage of javax.management.relation.RelationSupport

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.RelationTypeNotFoundException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.RelationTypeNotFoundException

Packages that use RelationTypeNotFoundException
javax.management.relation Provides the definition of the Relation Service.

Uses of RelationTypeNotFoundException in javax.management.relation

Methods in javax.management.relation that throw RelationTypeNotFoundException
void | RelationServiceMBean.addRelation(ObjectName relationObjectName) Adds an MBean created by the user (and registered by him in the MBean Server) as a relation in the Relation Service.
void | RelationService.addRelation(ObjectName relationObjectName) Adds an MBean created by the user (and registered by him in the MBean Server) as a relation in the Relation Service.
Integer | RelationServiceMBean.checkRoleReading(String roleName, String relationTypeName) Checks if given Role can be read in a relation of the given type.
Integer | RelationService.checkRoleReading(String roleName, String relationTypeName) Checks if given Role can be read in a relation of the given type.
Integer | RelationServiceMBean.checkRoleWriting(Role role, String relationTypeName, Boolean initFlag) Checks if given Role can be set in a relation of given type.
Integer | RelationService.checkRoleWriting(Role role, String relationTypeName, Boolean initFlag) Checks if given Role can be set in a relation of given type.
void | RelationServiceMBean.createRelation(String relationId, String relationTypeName, RoleList roleList) Creates a simple relation (represented by a RelationSupport object) of given relation type, and adds it in the Relation Service.
void | RelationService.createRelation(String relationId, String relationTypeName, RoleList roleList) Creates a simple relation (represented by a RelationSupport object) of given relation type, and adds it in the Relation Service.
List<String> | RelationServiceMBean.findRelationsOfType(String relationTypeName) Returns the relation ids for relations of the given type.
List<String> | RelationService.findRelationsOfType(String relationTypeName) Returns the relation ids for relations of the given type.
RoleInfo | RelationServiceMBean.getRoleInfo(String relationTypeName, String roleInfoName) Retrieves role info for given role of a given relation type.
RoleInfo | RelationService.getRoleInfo(String relationTypeName, String roleInfoName) Retrieves role info for given role name of a given relation type.
List<RoleInfo> | RelationServiceMBean.getRoleInfos(String relationTypeName) Retrieves list of role infos (RoleInfo objects) of a given relation type.
List<RoleInfo> | RelationService.getRoleInfos(String relationTypeName) Retrieves list of role infos (RoleInfo objects) of a given relation type.
void | RelationSupport.handleMBeanUnregistration(ObjectName objectName, String roleName) Callback used by the Relation Service when a MBean referenced in a role is unregistered.
void | Relation.handleMBeanUnregistration(ObjectName objectName, String roleName) Callback used by the Relation Service when a MBean referenced in a role is unregistered.
void | RelationServiceMBean.removeRelationType(String relationTypeName) Removes given relation type from Relation Service.
void | RelationService.removeRelationType(String relationTypeName) Removes given relation type from Relation Service.
void | RelationSupport.setRole(Role role) Sets the given role.
void | Relation.setRole(Role role) Sets the given role.
void | RelationServiceMBean.setRole(String relationId, Role role) Sets the given role in given relation.
RoleResult | RelationSupport.setRoles(RoleList list) Sets the given roles.
RoleResult | Relation.setRoles(RoleList roleList) Sets the given roles.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.RelationTypeSupport

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.RelationTypeSupport

No usage of javax.management.relation.RelationTypeSupport

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.Role

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.Role

Packages that use Role
javax.management.relation Provides the definition of the Relation Service.

Uses of Role in javax.management.relation

Methods in javax.management.relation that return types with arguments of type Role
 List<Role> RoleList.asList()
Return a view of this list as a List<Role>.

Methods in javax.management.relation with parameters of type Role
void | RoleList.add(int index, Role role) Inserts the role specified as an element at the position specified.
void | RoleList.add(Role role) Adds the Role specified as the last element of the list.
Integer | RelationServiceMBean.checkRoleWriting(Role role, String relationTypeName, Boolean initFlag) Checks if given Role can be set in a relation of given type.
Integer | RelationService.checkRoleWriting(Role role, String relationTypeName, Boolean initFlag) Checks if given Role can be set in a relation of given type.
void | RelationServiceMBean.sendRoleUpdateNotification(String relationId, Role newRole, List<ObjectName> oldRoleValue) Sends a notification (RelationNotification) for a role update in the given relation.
void | RelationService.sendRoleUpdateNotification(String relationId, Role newRole, List<ObjectName> oldValue) Sends a notification (RelationNotification) for a role update in the given relation.
void | RoleList.set(int index, Role role) Sets the element at the position specified to be the role specified.
void | RelationSupport.setRole(Role role) Sets the given role.
void | Relation.setRole(Role role) Sets the given role.
void | RelationServiceMBean.setRole(String relationId, Role role) Sets the given role in given relation.
void | RelationService.setRole(String relationId, Role role) Sets the given role in given relation.
void | RelationServiceMBean.updateRoleMap(String relationId, Role newRole, List<ObjectName> oldRoleValue) Handles update of the Relation Service role map for the update of given role in given relation.
void | RelationService.updateRoleMap(String relationId, Role newRole, List<ObjectName> oldValue) Handles update of the Relation Service role map for the update of given role in given relation.

Constructor parameters in javax.management.relation with type arguments of type Role
RoleList(List<Role> list)
Constructs a RoleList containing the elements of the List specified, in the order in which they are returned by the List's iterator.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.RoleInfo

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.RoleInfo

Packages that use RoleInfo
javax.management.relation Provides the definition of the Relation Service.

Uses of RoleInfo in javax.management.relation

Methods in javax.management.relation that return RoleInfo
RoleInfo | RelationTypeSupport.getRoleInfo(String roleInfoName) Returns the role info (RoleInfo object) for the given role info name (null if not found).
RoleInfo | RelationType.getRoleInfo(String roleInfoName) Returns the role info (RoleInfo object) for the given role info name (null if not found).
RoleInfo | RelationServiceMBean.getRoleInfo(String relationTypeName, String roleInfoName) Retrieves role info for given role of a given relation type.
RoleInfo | RelationService.getRoleInfo(String relationTypeName, String roleInfoName) Retrieves role info for given role name of a given relation type.

Methods in javax.management.relation that return types with arguments of type RoleInfo
List<RoleInfo> | RelationTypeSupport.getRoleInfos() Returns the list of role definitions (ArrayList of RoleInfo objects).
List<RoleInfo> | RelationType.getRoleInfos() Returns the list of role definitions (ArrayList of RoleInfo objects).
List<RoleInfo> | RelationServiceMBean.getRoleInfos(String relationTypeName) Retrieves list of role infos (RoleInfo objects) of a given relation type.
List<RoleInfo> | RelationService.getRoleInfos(String relationTypeName) Retrieves list of role infos (RoleInfo objects) of a given relation type.

Methods in javax.management.relation with parameters of type RoleInfo
protected void | RelationTypeSupport.addRoleInfo(RoleInfo roleInfo) Add a role info.
void | RelationServiceMBean.createRelationType(String relationTypeName, RoleInfo[] roleInfoArray) Creates a relation type (RelationTypeSupport object) with given role infos (provided by the RoleInfo objects), and adds it in the Relation Service.
void | RelationService.createRelationType(String relationTypeName, RoleInfo[] roleInfoArray) Creates a relation type (a RelationTypeSupport object) with given role infos (provided by the RoleInfo objects), and adds it in the Relation Service.

Constructors in javax.management.relation with parameters of type RoleInfo
RelationTypeSupport(String relationTypeName, RoleInfo[] roleInfoArray)
Constructor where all role definitions are dynamically created and passed as parameter.
RoleInfo(RoleInfo roleInfo)
Copy constructor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.RoleInfoNotFoundException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.RoleInfoNotFoundException

Packages that use RoleInfoNotFoundException
javax.management.relation Provides the definition of the Relation Service.

Uses of RoleInfoNotFoundException in javax.management.relation

Methods in javax.management.relation that throw RoleInfoNotFoundException
RoleInfo | RelationTypeSupport.getRoleInfo(String roleInfoName) Returns the role info (RoleInfo object) for the given role info name (null if not found).
RoleInfo | RelationType.getRoleInfo(String roleInfoName) Returns the role info (RoleInfo object) for the given role info name (null if not found).
RoleInfo | RelationServiceMBean.getRoleInfo(String relationTypeName, String roleInfoName) Retrieves role info for given role of a given relation type.
RoleInfo | RelationService.getRoleInfo(String relationTypeName, String roleInfoName) Retrieves role info for given role name of a given relation type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.RoleList

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.RoleList

Packages that use RoleList
javax.management.relation Provides the definition of the Relation Service.

Uses of RoleList in javax.management.relation

Methods in javax.management.relation that return RoleList
RoleList | RoleResult.getRoles() Retrieves list of roles successfully accessed.
RoleList | RelationSupport.retrieveAllRoles() Returns all roles in the relation without checking read mode.
RoleList | Relation.retrieveAllRoles() Returns all roles in the relation without checking read mode.

Methods in javax.management.relation with parameters of type RoleList
boolean | RoleList.addAll(int index, RoleList roleList) Inserts all of the elements in the RoleList specified into this list, starting at the specified position, in the order in which they are returned by the Iterator of the RoleList specified.
boolean | RoleList.addAll(RoleList roleList) Appends all the elements in the RoleList specified to the end of the list, in the order in which they are returned by the Iterator of the RoleList specified.
void | RelationServiceMBean.createRelation(String relationId, String relationTypeName, RoleList roleList) Creates a simple relation (represented by a RelationSupport object) of given relation type, and adds it in the Relation Service.
void | RelationService.createRelation(String relationId, String relationTypeName, RoleList roleList) Creates a simple relation (represented by a RelationSupport object) of given relation type, and adds it in the Relation Service.
RoleResult | RelationSupport.setRoles(RoleList list) Sets the given roles.
void | RoleResult.setRoles(RoleList list) Sets list of roles successfully accessed.
RoleResult | Relation.setRoles(RoleList roleList) Sets the given roles.
RoleResult | RelationServiceMBean.setRoles(String relationId, RoleList roleList) Sets the given roles in given relation.
RoleResult | RelationService.setRoles(String relationId, RoleList roleList) Sets the given roles in given relation.

Constructors in javax.management.relation with parameters of type RoleList
RelationSupport(String relationId, ObjectName relationServiceName, MBeanServer relationServiceMBeanServer, String relationTypeName, RoleList list)
Creates a RelationSupport object.
RelationSupport(String relationId, ObjectName relationServiceName, String relationTypeName, RoleList list)
Creates a RelationSupport object.
RoleResult(RoleList list, RoleUnresolvedList unresolvedList)
Constructor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.RoleNotFoundException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.RoleNotFoundException

Packages that use RoleNotFoundException
javax.management.relation Provides the definition of the Relation Service.

Uses of RoleNotFoundException in javax.management.relation

Methods in javax.management.relation that throw RoleNotFoundException
void | RelationServiceMBean.addRelation(ObjectName relationObjectName) Adds an MBean created by the user (and registered by him in the MBean Server) as a relation in the Relation Service.
void | RelationService.addRelation(ObjectName relationObjectName) Adds an MBean created by the user (and registered by him in the MBean Server) as a relation in the Relation Service.
void | RelationServiceMBean.createRelation(String relationId, String relationTypeName, RoleList roleList) Creates a simple relation (represented by a RelationSupport object) of given relation type, and adds it in the Relation Service.
void | RelationService.createRelation(String relationId, String relationTypeName, RoleList roleList) Creates a simple relation (represented by a RelationSupport object) of given relation type, and adds it in the Relation Service.
List<ObjectName> | RelationSupport.getRole(String roleName) Retrieves role value for given role name.
List<ObjectName> | Relation.getRole(String roleName) Retrieves role value for given role name.
List<ObjectName> | RelationServiceMBean.getRole(String relationId, String roleName) Retrieves role value for given role name in given relation.
List<ObjectName> | RelationService.getRole(String relationId, String roleName) Retrieves role value for given role name in given relation.
Integer | RelationSupport.getRoleCardinality(String roleName) Returns the number of MBeans currently referenced in the given role.
Integer | Relation.getRoleCardinality(String roleName) Returns the number of MBeans currently referenced in the given role.
Integer | RelationServiceMBean.getRoleCardinality(String relationId, String roleName) Retrieves the number of MBeans currently referenced in the given role.
Integer | RelationService.getRoleCardinality(String relationId, String roleName) Retrieves the number of MBeans currently referenced in the given role.
void | RelationSupport.handleMBeanUnregistration(ObjectName objectName, String roleName) Callback used by the Relation Service when a MBean referenced in a role is unregistered.
void | Relation.handleMBeanUnregistration(ObjectName objectName, String roleName) Callback used by the Relation Service when a MBean referenced in a role is unregistered.
void | RelationSupport.setRole(Role role) Sets the given role.
void | Relation.setRole(Role role) Sets the given role.
void | RelationServiceMBean.setRole(String relationId, Role role) Sets the given role in given relation.
void | RelationService.setRole(String relationId, Role role) Sets the given role in given relation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.RoleResult

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.RoleResult

Packages that use RoleResult
javax.management.relation Provides the definition of the Relation Service.

Uses of RoleResult in javax.management.relation

Methods in javax.management.relation that return RoleResult
RoleResult | RelationSupport.getAllRoles() Returns all roles present in the relation.
RoleResult | Relation.getAllRoles() Returns all roles present in the relation.
RoleResult | RelationServiceMBean.getAllRoles(String relationId) Returns all roles present in the relation.
RoleResult | RelationService.getAllRoles(String relationId) Returns all roles present in the relation.
RoleResult | RelationSupport.getRoles(String[] roleNameArray) Retrieves values of roles with given names.
RoleResult | Relation.getRoles(String[] roleNameArray) Retrieves values of roles with given names.
RoleResult | RelationServiceMBean.getRoles(String relationId, String[] roleNameArray) Retrieves values of roles with given names in given relation.
RoleResult | RelationService.getRoles(String relationId, String[] roleNameArray) Retrieves values of roles with given names in given relation.
RoleResult | RelationSupport.setRoles(RoleList list) Sets the given roles.
RoleResult | Relation.setRoles(RoleList roleList) Sets the given roles.
RoleResult | RelationServiceMBean.setRoles(String relationId, RoleList roleList) Sets the given roles in given relation.
RoleResult | RelationService.setRoles(String relationId, RoleList roleList) Sets the given roles in given relation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.RoleStatus

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.RoleStatus

No usage of javax.management.relation.RoleStatus

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.RoleUnresolved

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.RoleUnresolved

Packages that use RoleUnresolved
javax.management.relation Provides the definition of the Relation Service.

Uses of RoleUnresolved in javax.management.relation

Methods in javax.management.relation that return types with arguments of type RoleUnresolved
 List<RoleUnresolved> RoleUnresolvedList.asList()
Return a view of this list as a List<RoleUnresolved>.

Methods in javax.management.relation with parameters of type RoleUnresolved
void | RoleUnresolvedList.add(int index, RoleUnresolved role) Inserts the unresolved role specified as an element at the position specified.
void | RoleUnresolvedList.add(RoleUnresolved role) Adds the RoleUnresolved specified as the last element of the list.
void | RoleUnresolvedList.set(int index, RoleUnresolved role) Sets the element at the position specified to be the unresolved role specified.

Constructor parameters in javax.management.relation with type arguments of type RoleUnresolved
RoleUnresolvedList(List<RoleUnresolved> list)
Constructs a RoleUnresolvedList containing the elements of the List specified, in the order in which they are returned by the List's iterator.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.relation.RoleUnresolvedList

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.relation.RoleUnresolvedList

Packages that use RoleUnresolvedList
javax.management.relation Provides the definition of the Relation Service.

Uses of RoleUnresolvedList in javax.management.relation

Methods in javax.management.relation that return RoleUnresolvedList
 RoleUnresolvedList RoleResult.getRolesUnresolved()
Retrieves list of roles unsuccessfully accessed.

Methods in javax.management.relation with parameters of type RoleUnresolvedList
boolean | RoleUnresolvedList.addAll(int index, RoleUnresolvedList roleList) Inserts all of the elements in the RoleUnresolvedList specified into this list, starting at the specified position, in the order in which they are returned by the Iterator of the RoleUnresolvedList specified.
boolean | RoleUnresolvedList.addAll(RoleUnresolvedList roleList) Appends all the elements in the RoleUnresolvedList specified to the end of the list, in the order in which they are returned by the Iterator of the RoleUnresolvedList specified.
void | RoleResult.setRolesUnresolved(RoleUnresolvedList unresolvedList) Sets list of roles unsuccessfully accessed.

Constructors in javax.management.relation with parameters of type RoleUnresolvedList
RoleResult(RoleList list, RoleUnresolvedList unresolvedList)
Constructor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.relation.Relation

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.relation.Relation

Packages that use Relation
javax.management.relation Provides the definition of the Relation Service.

Uses of Relation in javax.management.relation

Subinterfaces of Relation in javax.management.relation
 interface RelationSupportMBean
A RelationSupport object is used internally by the Relation Service to represent simple relations (only roles, no properties or methods), with an unlimited number of roles, of any relation type.

Classes in javax.management.relation that implement Relation
 class RelationSupport
A RelationSupport object is used internally by the Relation Service to represent simple relations (only roles, no properties or methods), with an unlimited number of roles, of any relation type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.relation.RelationServiceMBean

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.relation.RelationServiceMBean

Packages that use RelationServiceMBean
javax.management.relation Provides the definition of the Relation Service.

Uses of RelationServiceMBean in javax.management.relation

Classes in javax.management.relation that implement RelationServiceMBean
 class RelationService
The Relation Service is in charge of creating and deleting relation types and relations, of handling the consistency and of providing query mechanisms.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.relation.RelationSupportMBean

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.relation.RelationSupportMBean

Packages that use RelationSupportMBean
javax.management.relation Provides the definition of the Relation Service.

Uses of RelationSupportMBean in javax.management.relation

Classes in javax.management.relation that implement RelationSupportMBean
 class RelationSupport
A RelationSupport object is used internally by the Relation Service to represent simple relations (only roles, no properties or methods), with an unlimited number of roles, of any relation type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.relation.RelationType

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.relation.RelationType

Packages that use RelationType
javax.management.relation Provides the definition of the Relation Service.

Uses of RelationType in javax.management.relation

Classes in javax.management.relation that implement RelationType
 class RelationTypeSupport
A RelationTypeSupport object implements the RelationType interface.

Methods in javax.management.relation with parameters of type RelationType
void | RelationServiceMBean.addRelationType(RelationType relationTypeObj) Adds given object as a relation type.
void | RelationService.addRelationType(RelationType relationTypeObj) Adds given object as a relation type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


InvalidRelationIdException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class InvalidRelationIdException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.relation.RelationException
                    extended by  javax.management.relation.InvalidRelationIdException
All Implemented Interfaces:
Serializable
public class InvalidRelationIdException
extends RelationException

This exception is raised when relation id provided for a relation is already used.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
InvalidRelationIdException()
Default constructor, no message put in exception.
InvalidRelationIdException(String message)
Constructor with given message put in exception.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidRelationIdException

public InvalidRelationIdException()
Default constructor, no message put in exception.

InvalidRelationIdException

public InvalidRelationIdException(String message)
Constructor with given message put in exception.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


InvalidRelationServiceException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class InvalidRelationServiceException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.relation.RelationException
                    extended by  javax.management.relation.InvalidRelationServiceException
All Implemented Interfaces:
Serializable
public class InvalidRelationServiceException
extends RelationException

This exception is raised when an invalid Relation Service is provided.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
InvalidRelationServiceException()
Default constructor, no message put in exception.
InvalidRelationServiceException(String message)
Constructor with given message put in exception.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidRelationServiceException

public InvalidRelationServiceException()
Default constructor, no message put in exception.

InvalidRelationServiceException

public InvalidRelationServiceException(String message)
Constructor with given message put in exception.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidRelationTypeException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class InvalidRelationTypeException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.relation.RelationException
                    extended by  javax.management.relation.InvalidRelationTypeException
All Implemented Interfaces:
Serializable
public class InvalidRelationTypeException
extends RelationException

Invalid relation type. This exception is raised when, in a relation type, there is already a relation type with that name, or the same name has been used for two different role infos, or no role info provided, or one null role info provided.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
InvalidRelationTypeException()
Default constructor, no message put in exception.
InvalidRelationTypeException(String message)
Constructor with given message put in exception.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidRelationTypeException

public InvalidRelationTypeException()
Default constructor, no message put in exception.

InvalidRelationTypeException

public InvalidRelationTypeException(String message)
Constructor with given message put in exception.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidRoleInfoException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class InvalidRoleInfoException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.relation.RelationException
                    extended by  javax.management.relation.InvalidRoleInfoException
All Implemented Interfaces:
Serializable
public class InvalidRoleInfoException
extends RelationException

This exception is raised when, in a role info, its minimum degree is greater than its maximum degree.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
InvalidRoleInfoException()
Default constructor, no message put in exception.
InvalidRoleInfoException(String message)
Constructor with given message put in exception.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidRoleInfoException

public InvalidRoleInfoException()
Default constructor, no message put in exception.

InvalidRoleInfoException

public InvalidRoleInfoException(String message)
Constructor with given message put in exception.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidRoleValueException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class InvalidRoleValueException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.relation.RelationException
                    extended by  javax.management.relation.InvalidRoleValueException
All Implemented Interfaces:
Serializable
public class InvalidRoleValueException
extends RelationException

Role value is invalid. This exception is raised when, in a role, the number of referenced MBeans in given value is less than expected minimum degree, or the number of referenced MBeans in provided value exceeds expected maximum degree, or one referenced MBean in the value is not an Object of the MBean class expected for that role, or an MBean provided for that role does not exist.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
InvalidRoleValueException()
Default constructor, no message put in exception.
InvalidRoleValueException(String message)
Constructor with given message put in exception.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidRoleValueException

public InvalidRoleValueException()
Default constructor, no message put in exception.

InvalidRoleValueException

public InvalidRoleValueException(String message)
Constructor with given message put in exception.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanServerNotificationFilter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class MBeanServerNotificationFilter

java.lang.Object
    extended by  javax.management.NotificationFilterSupport
        extended by  javax.management.relation.MBeanServerNotificationFilter
All Implemented Interfaces:
Serializable, NotificationFilter
public class MBeanServerNotificationFilter
extends NotificationFilterSupport

Filter for MBeanServerNotification. This filter filters MBeanServerNotification notifications by selecting the ObjectNames of interest and the operations (registration, unregistration, both) of interest (corresponding to notification types).

The serialVersionUID of this class is 2605900539589789736L.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
MBeanServerNotificationFilter()
Creates a filter selecting all MBeanServerNotification notifications for all ObjectNames.
Method Summary
void | disableAllObjectNames() Disables any MBeanServerNotification (all ObjectNames are deselected).
void | disableObjectName(ObjectName objectName) Disables MBeanServerNotifications concerning given ObjectName.
void | enableAllObjectNames() Enables all MBeanServerNotifications (all ObjectNames are selected).
void | enableObjectName(ObjectName objectName) Enables MBeanServerNotifications concerning given ObjectName.
Vector<ObjectName> | getDisabledObjectNames() Gets all the ObjectNames disabled.
Vector<ObjectName> | getEnabledObjectNames() Gets all the ObjectNames enabled.
boolean | isNotificationEnabled(Notification notif) Invoked before sending the specified notification to the listener.
Methods inherited from class javax.management.NotificationFilterSupport
disableAllTypes, disableType, enableType, getEnabledTypes
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MBeanServerNotificationFilter

public MBeanServerNotificationFilter()
Creates a filter selecting all MBeanServerNotification notifications for all ObjectNames.

Method Detail

disableAllObjectNames

public void disableAllObjectNames()
Disables any MBeanServerNotification (all ObjectNames are deselected).

disableObjectName

public void disableObjectName(ObjectName objectName)
                       throws IllegalArgumentException
Disables MBeanServerNotifications concerning given ObjectName.

Parameters:
objectName - ObjectName no longer of interest
Throws:
IllegalArgumentException - if the given ObjectName is null

enableAllObjectNames

public void enableAllObjectNames()
Enables all MBeanServerNotifications (all ObjectNames are selected).

enableObjectName

public void enableObjectName(ObjectName objectName)
                      throws IllegalArgumentException
Enables MBeanServerNotifications concerning given ObjectName.

Parameters:
objectName - ObjectName of interest
Throws:
IllegalArgumentException - if the given ObjectName is null

getEnabledObjectNames

public Vector<ObjectName> getEnabledObjectNames()
Gets all the ObjectNames enabled.

Returns:
Vector of ObjectNames:

- null means all ObjectNames are implicitly selected, except the ObjectNames explicitly deselected

- empty means all ObjectNames are deselected, i.e. no ObjectName selected.

getDisabledObjectNames

public Vector<ObjectName> getDisabledObjectNames()
Gets all the ObjectNames disabled.

Returns:
Vector of ObjectNames:

- null means all ObjectNames are implicitly deselected, except the ObjectNames explicitly selected

- empty means all ObjectNames are selected, i.e. no ObjectName deselected.

isNotificationEnabled

public boolean isNotificationEnabled(Notification notif)
                              throws IllegalArgumentException
Invoked before sending the specified notification to the listener.

If:

- the ObjectName of the concerned MBean is selected (explicitly OR (implicitly and not explicitly deselected))

AND

- the type of the operation (registration or unregistration) is selected

then the notification is sent to the listener.

Specified by:
isNotificationEnabled in interface NotificationFilter
Overrides:
isNotificationEnabled in class NotificationFilterSupport
Parameters:
notif - The notification to be sent.
Returns:
true if the notification has to be sent to the listener, false otherwise.
Throws:
IllegalArgumentException - if null parameter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Relation

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Interface Relation

All Known Subinterfaces:
RelationSupportMBean
All Known Implementing Classes:
RelationSupport
public interface Relation

This interface has to be implemented by any MBean class expected to represent a relation managed using the Relation Service.

Simple relations, i.e. having only roles, no properties or methods, can be created directly by the Relation Service (represented as RelationSupport objects, internally handled by the Relation Service).

If the user wants to represent more complex relations, involving properties and/or methods, he has to provide his own class implementing the Relation interface. This can be achieved either by inheriting from RelationSupport class, or by implementing the interface (fully or delegation to a RelationSupport object member).

Specifying such user relation class is to introduce properties and/or methods. Those have to be exposed for remote management. So this means that any user relation class must be a MBean class.

Since:
1.5

Method Summary
RoleResult | getAllRoles() Returns all roles present in the relation.
Map<ObjectName,List<String>> | getReferencedMBeans() Retrieves MBeans referenced in the various roles of the relation.
String | getRelationId() Returns relation identifier (used to uniquely identify the relation inside the Relation Service).
ObjectName | getRelationServiceName() Returns ObjectName of the Relation Service handling the relation.
String | getRelationTypeName() Returns name of associated relation type.
List<ObjectName> | getRole(String roleName) Retrieves role value for given role name.
Integer | getRoleCardinality(String roleName) Returns the number of MBeans currently referenced in the given role.
RoleResult | getRoles(String[] roleNameArray) Retrieves values of roles with given names.
void | handleMBeanUnregistration(ObjectName objectName, String roleName) Callback used by the Relation Service when a MBean referenced in a role is unregistered.
RoleList | retrieveAllRoles() Returns all roles in the relation without checking read mode.
void | setRole(Role role) Sets the given role.
RoleResult | setRoles(RoleList roleList) Sets the given roles.

Method Detail

getRole

List<ObjectName> getRole(String roleName)
                         throws IllegalArgumentException,
                                RoleNotFoundException,
                                RelationServiceNotRegisteredException
Retrieves role value for given role name.

Checks if the role exists and is readable according to the relation type.

Parameters:
roleName - name of role
Returns:
the ArrayList of ObjectName objects being the role value
Throws:
IllegalArgumentException - if null role name
RoleNotFoundException - if:

- there is no role with given name

- the role is not readable.

RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
See Also:
setRole(javax.management.relation.Role)

getRoles

RoleResult getRoles(String[] roleNameArray)
                    throws IllegalArgumentException,
                           RelationServiceNotRegisteredException
Retrieves values of roles with given names.

Checks for each role if it exists and is readable according to the relation type.

Parameters:
roleNameArray - array of names of roles to be retrieved
Returns:
a RoleResult object, including a RoleList (for roles successfully retrieved) and a RoleUnresolvedList (for roles not retrieved).
Throws:
IllegalArgumentException - if null role name
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
See Also:
setRoles(javax.management.relation.RoleList)

getRoleCardinality

Integer getRoleCardinality(String roleName)
                           throws IllegalArgumentException,
                                  RoleNotFoundException
Returns the number of MBeans currently referenced in the given role.

Parameters:
roleName - name of role
Returns:
the number of currently referenced MBeans in that role
Throws:
IllegalArgumentException - if null role name
RoleNotFoundException - if there is no role with given name

getAllRoles

RoleResult getAllRoles()
                       throws RelationServiceNotRegisteredException
Returns all roles present in the relation.

Returns:
a RoleResult object, including a RoleList (for roles successfully retrieved) and a RoleUnresolvedList (for roles not readable).
Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server

retrieveAllRoles

RoleList retrieveAllRoles()
Returns all roles in the relation without checking read mode.

Returns:
a RoleList.

setRole

void setRole(Role role)
             throws IllegalArgumentException,
                    RoleNotFoundException,
                    RelationTypeNotFoundException,
                    InvalidRoleValueException,
                    RelationServiceNotRegisteredException,
                    RelationNotFoundException
Sets the given role.

Will check the role according to its corresponding role definition provided in relation's relation type

Will send a notification (RelationNotification with type RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the relation is a MBean or not).

Parameters:
role - role to be set (name and new value)
Throws:
IllegalArgumentException - if null role
RoleNotFoundException - if there is no role with the supplied role's name or if the role is not writable (no test on the write access mode performed when initializing the role)
InvalidRoleValueException - if value provided for role is not valid, i.e.:

- the number of referenced MBeans in given value is less than expected minimum degree

- the number of referenced MBeans in provided value exceeds expected maximum degree

- one referenced MBean in the value is not an Object of the MBean class expected for that role

- a MBean provided for that role does not exist.

RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
RelationTypeNotFoundException - if the relation type has not been declared in the Relation Service.
RelationNotFoundException - if the relation has not been added in the Relation Service.
See Also:
getRole(java.lang.String)

setRoles

RoleResult setRoles(RoleList roleList)
                    throws IllegalArgumentException,
                           RelationServiceNotRegisteredException,
                           RelationTypeNotFoundException,
                           RelationNotFoundException
Sets the given roles.

Will check the role according to its corresponding role definition provided in relation's relation type

Will send one notification (RelationNotification with type RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the relation is a MBean or not) per updated role.

Parameters:
roleList - list of roles to be set
Returns:
a RoleResult object, including a RoleList (for roles successfully set) and a RoleUnresolvedList (for roles not set).
Throws:
IllegalArgumentException - if null role list
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
RelationTypeNotFoundException - if the relation type has not been declared in the Relation Service.
RelationNotFoundException - if the relation MBean has not been added in the Relation Service.
See Also:
getRoles(java.lang.String[])

handleMBeanUnregistration

void handleMBeanUnregistration(ObjectName objectName,
                               String roleName)
                               throws IllegalArgumentException,
                                      RoleNotFoundException,
                                      InvalidRoleValueException,
                                      RelationServiceNotRegisteredException,
                                      RelationTypeNotFoundException,
                                      RelationNotFoundException
Callback used by the Relation Service when a MBean referenced in a role is unregistered.

The Relation Service will call this method to let the relation take action to reflect the impact of such unregistration.

BEWARE. the user is not expected to call this method.

Current implementation is to set the role with its current value (list of ObjectNames of referenced MBeans) without the unregistered one.

Parameters:
objectName - ObjectName of unregistered MBean
roleName - name of role where the MBean is referenced
Throws:
IllegalArgumentException - if null parameter
RoleNotFoundException - if role does not exist in the relation or is not writable
InvalidRoleValueException - if role value does not conform to the associated role info (this will never happen when called from the Relation Service)
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
RelationTypeNotFoundException - if the relation type has not been declared in the Relation Service.
RelationNotFoundException - if this method is called for a relation MBean not added in the Relation Service.

getReferencedMBeans

Map<ObjectName,List<String>> getReferencedMBeans()
Retrieves MBeans referenced in the various roles of the relation.

Returns:
a HashMap mapping:

ObjectName -> ArrayList of String (role names)

getRelationTypeName

String getRelationTypeName()
Returns name of associated relation type.

Returns:
the name of the relation type.

getRelationServiceName

ObjectName getRelationServiceName()
Returns ObjectName of the Relation Service handling the relation.

Returns:
the ObjectName of the Relation Service.

getRelationId

String getRelationId()
Returns relation identifier (used to uniquely identify the relation inside the Relation Service).

Returns:
the relation id.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RelationException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class RelationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.relation.RelationException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
InvalidRelationIdException, InvalidRelationServiceException, InvalidRelationTypeException, InvalidRoleInfoException, InvalidRoleValueException, RelationNotFoundException, RelationServiceNotRegisteredException, RelationTypeNotFoundException, RoleInfoNotFoundException, RoleNotFoundException
public class RelationException
extends JMException

This class is the superclass of any exception which can be raised during relation management.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
RelationException()
Default constructor, no message put in exception.
RelationException(String message)
Constructor with given message put in exception.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RelationException

public RelationException()
Default constructor, no message put in exception.

RelationException

public RelationException(String message)
Constructor with given message put in exception.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RelationNotFoundException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class RelationNotFoundException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.relation.RelationException
                    extended by  javax.management.relation.RelationNotFoundException
All Implemented Interfaces:
Serializable
public class RelationNotFoundException
extends RelationException

This exception is raised when there is no relation for a given relation id in a Relation Service.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
RelationNotFoundException()
Default constructor, no message put in exception.
RelationNotFoundException(String message)
Constructor with given message put in exception.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RelationNotFoundException

public RelationNotFoundException()
Default constructor, no message put in exception.

RelationNotFoundException

public RelationNotFoundException(String message)
Constructor with given message put in exception.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RelationNotification

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class RelationNotification

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.management.Notification
            extended by  javax.management.relation.RelationNotification
All Implemented Interfaces:
Serializable
public class RelationNotification
extends Notification

A notification of a change in the Relation Service. A RelationNotification notification is sent when a relation is created via the Relation Service, or an MBean is added as a relation in the Relation Service, or a role is updated in a relation, or a relation is removed from the Relation Service.

The serialVersionUID of this class is -6871117877523310399L.

Since:
1.5
See Also:
Serialized Form

Field Summary
static String | RELATION_BASIC_CREATION Type for the creation of an internal relation.
static String | RELATION_BASIC_REMOVAL Type for the removal from the Relation Service of an internal relation.
static String | RELATION_BASIC_UPDATE Type for an update of an internal relation.
static String | RELATION_MBEAN_CREATION Type for the relation MBean added into the Relation Service.
static String | RELATION_MBEAN_REMOVAL Type for the removal from the Relation Service of a relation MBean.
static String | RELATION_MBEAN_UPDATE Type for the update of a relation MBean.
Fields inherited from class javax.management.Notification
source
Constructor Summary
RelationNotification(String notifType, Object sourceObj, long sequence, long timeStamp, String message, String id, String typeName, ObjectName objectName, List<ObjectName> unregMBeanList)
Creates a notification for either a relation creation (RelationSupport object created internally in the Relation Service, or an MBean added as a relation) or for a relation removal from the Relation Service.
RelationNotification(String notifType, Object sourceObj, long sequence, long timeStamp, String message, String id, String typeName, ObjectName objectName, String name, List<ObjectName> newValue, List<ObjectName> oldValue)
Creates a notification for a role update in a relation.
Method Summary
List<ObjectName> | getMBeansToUnregister() Returns the list of ObjectNames of MBeans expected to be unregistered due to a relation removal (only for relation removal).
List<ObjectName> | getNewRoleValue() Returns new value of updated role (only for role update).
ObjectName | getObjectName() Returns the ObjectName of the created/removed/updated relation.
List<ObjectName> | getOldRoleValue() Returns old value of updated role (only for role update).
String | getRelationId() Returns the relation identifier of created/removed/updated relation.
String | getRelationTypeName() Returns the relation type name of created/removed/updated relation.
String | getRoleName() Returns name of updated role of updated relation (only for role update).
Methods inherited from class javax.management.Notification
getMessage, getSequenceNumber, getTimeStamp, getType, getUserData, setSequenceNumber, setSource, setTimeStamp, setUserData, toString
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

RELATION_BASIC_CREATION

public static final String RELATION_BASIC_CREATION
Type for the creation of an internal relation.

See Also:
Constant Field Values

RELATION_MBEAN_CREATION

public static final String RELATION_MBEAN_CREATION
Type for the relation MBean added into the Relation Service.

See Also:
Constant Field Values

RELATION_BASIC_UPDATE

public static final String RELATION_BASIC_UPDATE
Type for an update of an internal relation.

See Also:
Constant Field Values

RELATION_MBEAN_UPDATE

public static final String RELATION_MBEAN_UPDATE
Type for the update of a relation MBean.

See Also:
Constant Field Values

RELATION_BASIC_REMOVAL

public static final String RELATION_BASIC_REMOVAL
Type for the removal from the Relation Service of an internal relation.

See Also:
Constant Field Values

RELATION_MBEAN_REMOVAL

public static final String RELATION_MBEAN_REMOVAL
Type for the removal from the Relation Service of a relation MBean.

See Also:
Constant Field Values
Constructor Detail

RelationNotification

public RelationNotification(String notifType,
                            Object sourceObj,
                            long sequence,
                            long timeStamp,
                            String message,
                            String id,
                            String typeName,
                            ObjectName objectName,
                            List<ObjectName> unregMBeanList)
                     throws IllegalArgumentException
Creates a notification for either a relation creation (RelationSupport object created internally in the Relation Service, or an MBean added as a relation) or for a relation removal from the Relation Service.

Parameters:
notifType - type of the notification; either:

- RELATION_BASIC_CREATION

- RELATION_MBEAN_CREATION

- RELATION_BASIC_REMOVAL

- RELATION_MBEAN_REMOVAL

sourceObj - source object, sending the notification. This is either an ObjectName or a RelationService object. In the latter case it must be the MBean emitting the notification; the MBean Server will rewrite the source to be the ObjectName under which that MBean is registered.
sequence - sequence number to identify the notification
timeStamp - time stamp
message - human-readable message describing the notification
id - relation id identifying the relation in the Relation Service
typeName - name of the relation type
objectName - ObjectName of the relation object if it is an MBean (null for relations internally handled by the Relation Service)
unregMBeanList - list of ObjectNames of referenced MBeans expected to be unregistered due to relation removal (only for removal, due to CIM qualifiers, can be null)
Throws:
IllegalArgumentException - if:

- no value for the notification type

- the notification type is not RELATION_BASIC_CREATION, RELATION_MBEAN_CREATION, RELATION_BASIC_REMOVAL or RELATION_MBEAN_REMOVAL

- no source object

- the source object is not a Relation Service

- no relation id

- no relation type name

RelationNotification

public RelationNotification(String notifType,
                            Object sourceObj,
                            long sequence,
                            long timeStamp,
                            String message,
                            String id,
                            String typeName,
                            ObjectName objectName,
                            String name,
                            List<ObjectName> newValue,
                            List<ObjectName> oldValue)
                     throws IllegalArgumentException
Creates a notification for a role update in a relation.

Parameters:
notifType - type of the notification; either:

- RELATION_BASIC_UPDATE

- RELATION_MBEAN_UPDATE

sourceObj - source object, sending the notification. This is either an ObjectName or a RelationService object. In the latter case it must be the MBean emitting the notification; the MBean Server will rewrite the source to be the ObjectName under which that MBean is registered.
sequence - sequence number to identify the notification
timeStamp - time stamp
message - human-readable message describing the notification
id - relation id identifying the relation in the Relation Service
typeName - name of the relation type
objectName - ObjectName of the relation object if it is an MBean (null for relations internally handled by the Relation Service)
name - name of the updated role
newValue - new role value (List of ObjectName objects)
oldValue - old role value (List of ObjectName objects)
Throws:
IllegalArgumentException - if null parameter
Method Detail

getRelationId

public String getRelationId()
Returns the relation identifier of created/removed/updated relation.

Returns:
the relation id.

getRelationTypeName

public String getRelationTypeName()
Returns the relation type name of created/removed/updated relation.

Returns:
the relation type name.

getObjectName

public ObjectName getObjectName()
Returns the ObjectName of the created/removed/updated relation.

Returns:
the ObjectName if the relation is an MBean, otherwise null.

getMBeansToUnregister

public List<ObjectName> getMBeansToUnregister()
Returns the list of ObjectNames of MBeans expected to be unregistered due to a relation removal (only for relation removal).

Returns:
a List of ObjectName.

getRoleName

public String getRoleName()
Returns name of updated role of updated relation (only for role update).

Returns:
the name of the updated role.

getOldRoleValue

public List<ObjectName> getOldRoleValue()
Returns old value of updated role (only for role update).

Returns:
the old value of the updated role.

getNewRoleValue

public List<ObjectName> getNewRoleValue()
Returns new value of updated role (only for role update).

Returns:
the new value of the updated role.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RelationService

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class RelationService

java.lang.Object
    extended by  javax.management.NotificationBroadcasterSupport
        extended by  javax.management.relation.RelationService
All Implemented Interfaces:
EventListener, MBeanRegistration, NotificationBroadcaster, NotificationEmitter, NotificationListener, RelationServiceMBean
public class RelationService
extends NotificationBroadcasterSupport
implements RelationServiceMBean, MBeanRegistration, NotificationListener

The Relation Service is in charge of creating and deleting relation types and relations, of handling the consistency and of providing query mechanisms.

It implements the NotificationBroadcaster by extending NotificationBroadcasterSupport to send notifications when a relation is removed from it.

It implements the NotificationListener interface to be able to receive notifications concerning unregistration of MBeans referenced in relation roles and of relation MBeans.

It implements the MBeanRegistration interface to be able to retrieve its ObjectName and MBean Server.

Since:
1.5

Constructor Summary
RelationService(boolean immediatePurgeFlag)
Constructor.
Method Summary
void | addRelation(ObjectName relationObjectName) Adds an MBean created by the user (and registered by him in the MBean Server) as a relation in the Relation Service.
void | addRelationType(RelationType relationTypeObj) Adds given object as a relation type.
Integer | checkRoleReading(String roleName, String relationTypeName) Checks if given Role can be read in a relation of the given type.
Integer | checkRoleWriting(Role role, String relationTypeName, Boolean initFlag) Checks if given Role can be set in a relation of given type.
void | createRelation(String relationId, String relationTypeName, RoleList roleList) Creates a simple relation (represented by a RelationSupport object) of given relation type, and adds it in the Relation Service.
void | createRelationType(String relationTypeName, RoleInfo[] roleInfoArray) Creates a relation type (a RelationTypeSupport object) with given role infos (provided by the RoleInfo objects), and adds it in the Relation Service.
Map<ObjectName,List<String>> | findAssociatedMBeans(ObjectName mbeanName, String relationTypeName, String roleName) Retrieves the MBeans associated to given one in a relation.
Map<String,List<String>> | findReferencingRelations(ObjectName mbeanName, String relationTypeName, String roleName) Retrieves the relations where a given MBean is referenced.
List<String> | findRelationsOfType(String relationTypeName) Returns the relation ids for relations of the given type.
List<String> | getAllRelationIds() Returns all the relation ids for all the relations handled by the Relation Service.
List<String> | getAllRelationTypeNames() Retrieves names of all known relation types.
RoleResult | getAllRoles(String relationId) Returns all roles present in the relation.
MBeanNotificationInfo[] | getNotificationInfo() Returns a NotificationInfo object containing the name of the Java class of the notification and the notification types sent.
boolean | getPurgeFlag() Returns the flag to indicate if when a notification is received for the unregistration of an MBean referenced in a relation, if an immediate "purge" of the relations (look for the relations no longer valid) has to be performed , or if that will be performed only when the purgeRelations method will be explicitly called.
Map<ObjectName,List<String>> | getReferencedMBeans(String relationId) Retrieves MBeans referenced in the various roles of the relation.
String | getRelationTypeName(String relationId) Returns name of associated relation type for given relation.
List<ObjectName> | getRole(String relationId, String roleName) Retrieves role value for given role name in given relation.
Integer | getRoleCardinality(String relationId, String roleName) Retrieves the number of MBeans currently referenced in the given role.
RoleInfo | getRoleInfo(String relationTypeName, String roleInfoName) Retrieves role info for given role name of a given relation type.
List<RoleInfo> | getRoleInfos(String relationTypeName) Retrieves list of role infos (RoleInfo objects) of a given relation type.
RoleResult | getRoles(String relationId, String[] roleNameArray) Retrieves values of roles with given names in given relation.
void | handleNotification(Notification notif, Object handback) Invoked when a JMX notification occurs.
Boolean | hasRelation(String relationId) Checks if there is a relation identified in Relation Service with given relation id.
void | isActive() Checks if the Relation Service is active.
String | isRelation(ObjectName objectName) Returns the relation id associated to the given ObjectName if the MBean has been added as a relation in the Relation Service.
ObjectName | isRelationMBean(String relationId) If the relation is represented by an MBean (created by the user and added as a relation in the Relation Service), returns the ObjectName of the MBean.
void | postDeregister() Allows the MBean to perform any operations needed after having been unregistered in the MBean server.
void | postRegister(Boolean registrationDone) Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.
void | preDeregister() Allows the MBean to perform any operations it needs before being unregistered by the MBean server.
ObjectName | preRegister(MBeanServer server, ObjectName name) Allows the MBean to perform any operations it needs before being registered in the MBean server.
void | purgeRelations() Purges the relations.
void | removeRelation(String relationId) Removes given relation from the Relation Service.
void | removeRelationType(String relationTypeName) Removes given relation type from Relation Service.
void | sendRelationCreationNotification(String relationId) Sends a notification (RelationNotification) for a relation creation.
void | sendRelationRemovalNotification(String relationId, List<ObjectName> unregMBeanList) Sends a notification (RelationNotification) for a relation removal.
void | sendRoleUpdateNotification(String relationId, Role newRole, List<ObjectName> oldValue) Sends a notification (RelationNotification) for a role update in the given relation.
void | setPurgeFlag(boolean purgeFlag) Sets the flag to indicate if when a notification is received for the unregistration of an MBean referenced in a relation, if an immediate "purge" of the relations (look for the relations no longer valid) has to be performed , or if that will be performed only when the purgeRelations method will be explicitly called.
void | setRole(String relationId, Role role) Sets the given role in given relation.
RoleResult | setRoles(String relationId, RoleList roleList) Sets the given roles in given relation.
void | updateRoleMap(String relationId, Role newRole, List<ObjectName> oldValue) Handles update of the Relation Service role map for the update of given role in given relation.
Methods inherited from class javax.management.NotificationBroadcasterSupport
addNotificationListener, handleNotification, removeNotificationListener, removeNotificationListener, sendNotification
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RelationService

public RelationService(boolean immediatePurgeFlag)
Constructor.

Parameters:
immediatePurgeFlag - flag to indicate when a notification is received for the unregistration of an MBean referenced in a relation, if an immediate "purge" of the relations (look for the relations no longer valid) has to be performed , or if that will be performed only when the purgeRelations method will be explicitly called.

true is immediate purge.

Method Detail

isActive

public void isActive()
              throws RelationServiceNotRegisteredException
Checks if the Relation Service is active. Current condition is that the Relation Service must be registered in the MBean Server

Specified by:
isActive in interface RelationServiceMBean
Throws:
RelationServiceNotRegisteredException - if it is not registered

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception
Description copied from interface: MBeanRegistration
Allows the MBean to perform any operations it needs before being registered in the MBean server. If the name of the MBean is not specified, the MBean can provide a name for its registration. If any exception is raised, the MBean will not be registered in the MBean server.

Specified by:
preRegister in interface MBeanRegistration
Parameters:
server - The MBean server in which the MBean will be registered.
name - The object name of the MBean. This name is null if the name parameter to one of the createMBean or registerMBean methods in the MBeanServer interface is null. In that case, this method must return a non-null ObjectName for the new MBean.
Returns:
The name under which the MBean is to be registered. This value must not be null. If the name parameter is not null, it will usually but not necessarily be the returned value.
Throws:
Exception - This exception will be caught by the MBean server and re-thrown as an MBeanRegistrationException.

postRegister

public void postRegister(Boolean registrationDone)
Description copied from interface: MBeanRegistration
Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.

Specified by:
postRegister in interface MBeanRegistration
Parameters:
registrationDone - Indicates whether or not the MBean has been successfully registered in the MBean server. The value false means that the registration phase has failed.

preDeregister

public void preDeregister()
                   throws Exception
Description copied from interface: MBeanRegistration
Allows the MBean to perform any operations it needs before being unregistered by the MBean server.

Specified by:
preDeregister in interface MBeanRegistration
Throws:
Exception - This exception will be caught by the MBean server and re-thrown as an MBeanRegistrationException.

postDeregister

public void postDeregister()
Description copied from interface: MBeanRegistration
Allows the MBean to perform any operations needed after having been unregistered in the MBean server.

Specified by:
postDeregister in interface MBeanRegistration

getPurgeFlag

public boolean getPurgeFlag()
Returns the flag to indicate if when a notification is received for the unregistration of an MBean referenced in a relation, if an immediate "purge" of the relations (look for the relations no longer valid) has to be performed , or if that will be performed only when the purgeRelations method will be explicitly called.

true is immediate purge.

Specified by:
getPurgeFlag in interface RelationServiceMBean
Returns:
true if purges are automatic.
See Also:
setPurgeFlag(boolean)

setPurgeFlag

public void setPurgeFlag(boolean purgeFlag)
Sets the flag to indicate if when a notification is received for the unregistration of an MBean referenced in a relation, if an immediate "purge" of the relations (look for the relations no longer valid) has to be performed , or if that will be performed only when the purgeRelations method will be explicitly called.

true is immediate purge.

Specified by:
setPurgeFlag in interface RelationServiceMBean
Parameters:
purgeFlag - flag
See Also:
getPurgeFlag()

createRelationType

public void createRelationType(String relationTypeName,
                               RoleInfo[] roleInfoArray)
                        throws IllegalArgumentException,
                               InvalidRelationTypeException
Creates a relation type (a RelationTypeSupport object) with given role infos (provided by the RoleInfo objects), and adds it in the Relation Service.

Specified by:
createRelationType in interface RelationServiceMBean
Parameters:
relationTypeName - name of the relation type
roleInfoArray - array of role infos
Throws:
IllegalArgumentException - if null parameter
InvalidRelationTypeException - If:

- there is already a relation type with that name

- the same name has been used for two different role infos

- no role info provided

- one null role info provided

addRelationType

public void addRelationType(RelationType relationTypeObj)
                     throws IllegalArgumentException,
                            InvalidRelationTypeException
Adds given object as a relation type. The object is expected to implement the RelationType interface.

Specified by:
addRelationType in interface RelationServiceMBean
Parameters:
relationTypeObj - relation type object (implementing the RelationType interface)
Throws:
IllegalArgumentException - if null parameter or if relationTypeObj.getRelationTypeName() returns null.
InvalidRelationTypeException - if:

- the same name has been used for two different roles

- no role info provided

- one null role info provided

- there is already a relation type with that name

getAllRelationTypeNames

public List<String> getAllRelationTypeNames()
Retrieves names of all known relation types.

Specified by:
getAllRelationTypeNames in interface RelationServiceMBean
Returns:
ArrayList of relation type names (Strings)

getRoleInfos

public List<RoleInfo> getRoleInfos(String relationTypeName)
                            throws IllegalArgumentException,
                                   RelationTypeNotFoundException
Retrieves list of role infos (RoleInfo objects) of a given relation type.

Specified by:
getRoleInfos in interface RelationServiceMBean
Parameters:
relationTypeName - name of relation type
Returns:
ArrayList of RoleInfo.
Throws:
IllegalArgumentException - if null parameter
RelationTypeNotFoundException - if there is no relation type with that name.

getRoleInfo

public RoleInfo getRoleInfo(String relationTypeName,
                            String roleInfoName)
                     throws IllegalArgumentException,
                            RelationTypeNotFoundException,
                            RoleInfoNotFoundException
Retrieves role info for given role name of a given relation type.

Specified by:
getRoleInfo in interface RelationServiceMBean
Parameters:
relationTypeName - name of relation type
roleInfoName - name of role
Returns:
RoleInfo object.
Throws:
IllegalArgumentException - if null parameter
RelationTypeNotFoundException - if the relation type is not known in the Relation Service
RoleInfoNotFoundException - if the role is not part of the relation type.

removeRelationType

public void removeRelationType(String relationTypeName)
                        throws RelationServiceNotRegisteredException,
                               IllegalArgumentException,
                               RelationTypeNotFoundException
Removes given relation type from Relation Service.

The relation objects of that type will be removed from the Relation Service.

Specified by:
removeRelationType in interface RelationServiceMBean
Parameters:
relationTypeName - name of the relation type to be removed
Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
IllegalArgumentException - if null parameter
RelationTypeNotFoundException - If there is no relation type with that name

createRelation

public void createRelation(String relationId,
                           String relationTypeName,
                           RoleList roleList)
                    throws RelationServiceNotRegisteredException,
                           IllegalArgumentException,
                           RoleNotFoundException,
                           InvalidRelationIdException,
                           RelationTypeNotFoundException,
                           InvalidRoleValueException
Creates a simple relation (represented by a RelationSupport object) of given relation type, and adds it in the Relation Service.

Roles are initialized according to the role list provided in parameter. The ones not initialized in this way are set to an empty ArrayList of ObjectNames.

A RelationNotification, with type RELATION_BASIC_CREATION, is sent.

Specified by:
createRelation in interface RelationServiceMBean
Parameters:
relationId - relation identifier, to identify uniquely the relation inside the Relation Service
relationTypeName - name of the relation type (has to be created in the Relation Service)
roleList - role list to initialize roles of the relation (can be null).
Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
IllegalArgumentException - if null parameter, except the role list which can be null if no role initialization
RoleNotFoundException - if a value is provided for a role that does not exist in the relation type
InvalidRelationIdException - if relation id already used
RelationTypeNotFoundException - if relation type not known in Relation Service
InvalidRoleValueException - if:

- the same role name is used for two different roles

- the number of referenced MBeans in given value is less than expected minimum degree

- the number of referenced MBeans in provided value exceeds expected maximum degree

- one referenced MBean in the value is not an Object of the MBean class expected for that role

- an MBean provided for that role does not exist

addRelation

public void addRelation(ObjectName relationObjectName)
                 throws IllegalArgumentException,
                        RelationServiceNotRegisteredException,
                        NoSuchMethodException,
                        InvalidRelationIdException,
                        InstanceNotFoundException,
                        InvalidRelationServiceException,
                        RelationTypeNotFoundException,
                        RoleNotFoundException,
                        InvalidRoleValueException
Adds an MBean created by the user (and registered by him in the MBean Server) as a relation in the Relation Service.

To be added as a relation, the MBean must conform to the following:

- implement the Relation interface

- have for RelationService ObjectName the ObjectName of current Relation Service

- have a relation id unique and unused in current Relation Service

- have for relation type a relation type created in the Relation Service

- have roles conforming to the role info provided in the relation type.

Specified by:
addRelation in interface RelationServiceMBean
Parameters:
relationObjectName - ObjectName of the relation MBean to be added.
Throws:
IllegalArgumentException - if null parameter
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
NoSuchMethodException - If the MBean does not implement the Relation interface
InvalidRelationIdException - if:

- no relation identifier in MBean

- the relation identifier is already used in the Relation Service

InstanceNotFoundException - if the MBean for given ObjectName has not been registered
InvalidRelationServiceException - if:

- no Relation Service name in MBean

- the Relation Service name in the MBean is not the one of the current Relation Service

RelationTypeNotFoundException - if:

- no relation type name in MBean

- the relation type name in MBean does not correspond to a relation type created in the Relation Service

InvalidRoleValueException - if:

- the number of referenced MBeans in a role is less than expected minimum degree

- the number of referenced MBeans in a role exceeds expected maximum degree

- one referenced MBean in the value is not an Object of the MBean class expected for that role

- an MBean provided for a role does not exist

RoleNotFoundException - if a value is provided for a role that does not exist in the relation type

isRelationMBean

public ObjectName isRelationMBean(String relationId)
                           throws IllegalArgumentException,
                                  RelationNotFoundException
If the relation is represented by an MBean (created by the user and added as a relation in the Relation Service), returns the ObjectName of the MBean.

Specified by:
isRelationMBean in interface RelationServiceMBean
Parameters:
relationId - relation id identifying the relation
Returns:
ObjectName of the corresponding relation MBean, or null if the relation is not an MBean.
Throws:
IllegalArgumentException - if null parameter
RelationNotFoundException - there is no relation associated to that id

isRelation

public String isRelation(ObjectName objectName)
                  throws IllegalArgumentException
Returns the relation id associated to the given ObjectName if the MBean has been added as a relation in the Relation Service.

Specified by:
isRelation in interface RelationServiceMBean
Parameters:
objectName - ObjectName of supposed relation
Returns:
relation id (String) or null (if the ObjectName is not a relation handled by the Relation Service)
Throws:
IllegalArgumentException - if null parameter

hasRelation

public Boolean hasRelation(String relationId)
                    throws IllegalArgumentException
Checks if there is a relation identified in Relation Service with given relation id.

Specified by:
hasRelation in interface RelationServiceMBean
Parameters:
relationId - relation id identifying the relation
Returns:
boolean: true if there is a relation, false else
Throws:
IllegalArgumentException - if null parameter

getAllRelationIds

public List<String> getAllRelationIds()
Returns all the relation ids for all the relations handled by the Relation Service.

Specified by:
getAllRelationIds in interface RelationServiceMBean
Returns:
ArrayList of String

checkRoleReading

public Integer checkRoleReading(String roleName,
                                String relationTypeName)
                         throws IllegalArgumentException,
                                RelationTypeNotFoundException
Checks if given Role can be read in a relation of the given type.

Specified by:
checkRoleReading in interface RelationServiceMBean
Parameters:
roleName - name of role to be checked
relationTypeName - name of the relation type
Returns:
an Integer wrapping an integer corresponding to possible problems represented as constants in RoleUnresolved:

- 0 if role can be read

- integer corresponding to RoleStatus.NO_ROLE_WITH_NAME

- integer corresponding to RoleStatus.ROLE_NOT_READABLE

Throws:
IllegalArgumentException - if null parameter
RelationTypeNotFoundException - if the relation type is not known in the Relation Service

checkRoleWriting

public Integer checkRoleWriting(Role role,
                                String relationTypeName,
                                Boolean initFlag)
                         throws IllegalArgumentException,
                                RelationTypeNotFoundException
Checks if given Role can be set in a relation of given type.

Specified by:
checkRoleWriting in interface RelationServiceMBean
Parameters:
role - role to be checked
relationTypeName - name of relation type
initFlag - flag to specify that the checking is done for the initialization of a role, write access shall not be verified.
Returns:
an Integer wrapping an integer corresponding to possible problems represented as constants in RoleUnresolved:

- 0 if role can be set

- integer corresponding to RoleStatus.NO_ROLE_WITH_NAME

- integer for RoleStatus.ROLE_NOT_WRITABLE

- integer for RoleStatus.LESS_THAN_MIN_ROLE_DEGREE

- integer for RoleStatus.MORE_THAN_MAX_ROLE_DEGREE

- integer for RoleStatus.REF_MBEAN_OF_INCORRECT_CLASS

- integer for RoleStatus.REF_MBEAN_NOT_REGISTERED

Throws:
IllegalArgumentException - if null parameter
RelationTypeNotFoundException - if unknown relation type

sendRelationCreationNotification

public void sendRelationCreationNotification(String relationId)
                                      throws IllegalArgumentException,
                                             RelationNotFoundException
Sends a notification (RelationNotification) for a relation creation. The notification type is:

- RelationNotification.RELATION_BASIC_CREATION if the relation is an object internal to the Relation Service

- RelationNotification.RELATION_MBEAN_CREATION if the relation is a MBean added as a relation.

The source object is the Relation Service itself.

It is called in Relation Service createRelation() and addRelation() methods.

Specified by:
sendRelationCreationNotification in interface RelationServiceMBean
Parameters:
relationId - relation identifier of the updated relation
Throws:
IllegalArgumentException - if null parameter
RelationNotFoundException - if there is no relation for given relation id

sendRoleUpdateNotification

public void sendRoleUpdateNotification(String relationId,
                                       Role newRole,
                                       List<ObjectName> oldValue)
                                throws IllegalArgumentException,
                                       RelationNotFoundException
Sends a notification (RelationNotification) for a role update in the given relation. The notification type is:

- RelationNotification.RELATION_BASIC_UPDATE if the relation is an object internal to the Relation Service

- RelationNotification.RELATION_MBEAN_UPDATE if the relation is a MBean added as a relation.

The source object is the Relation Service itself.

It is called in relation MBean setRole() (for given role) and setRoles() (for each role) methods (implementation provided in RelationSupport class).

It is also called in Relation Service setRole() (for given role) and setRoles() (for each role) methods.

Specified by:
sendRoleUpdateNotification in interface RelationServiceMBean
Parameters:
relationId - relation identifier of the updated relation
newRole - new role (name and new value)
oldValue - old role value (List of ObjectName objects)
Throws:
IllegalArgumentException - if null parameter
RelationNotFoundException - if there is no relation for given relation id

sendRelationRemovalNotification

public void sendRelationRemovalNotification(String relationId,
                                            List<ObjectName> unregMBeanList)
                                     throws IllegalArgumentException,
                                            RelationNotFoundException
Sends a notification (RelationNotification) for a relation removal. The notification type is:

- RelationNotification.RELATION_BASIC_REMOVAL if the relation is an object internal to the Relation Service

- RelationNotification.RELATION_MBEAN_REMOVAL if the relation is a MBean added as a relation.

The source object is the Relation Service itself.

It is called in Relation Service removeRelation() method.

Specified by:
sendRelationRemovalNotification in interface RelationServiceMBean
Parameters:
relationId - relation identifier of the updated relation
unregMBeanList - List of ObjectNames of MBeans expected to be unregistered due to relation removal (can be null)
Throws:
IllegalArgumentException - if null parameter
RelationNotFoundException - if there is no relation for given relation id

updateRoleMap

public void updateRoleMap(String relationId,
                          Role newRole,
                          List<ObjectName> oldValue)
                   throws IllegalArgumentException,
                          RelationServiceNotRegisteredException,
                          RelationNotFoundException
Handles update of the Relation Service role map for the update of given role in given relation.

It is called in relation MBean setRole() (for given role) and setRoles() (for each role) methods (implementation provided in RelationSupport class).

It is also called in Relation Service setRole() (for given role) and setRoles() (for each role) methods.

To allow the Relation Service to maintain the consistency (in case of MBean unregistration) and to be able to perform queries, this method must be called when a role is updated.

Specified by:
updateRoleMap in interface RelationServiceMBean
Parameters:
relationId - relation identifier of the updated relation
newRole - new role (name and new value)
oldValue - old role value (List of ObjectName objects)
Throws:
IllegalArgumentException - if null parameter
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
RelationNotFoundException - if no relation for given id.

removeRelation

public void removeRelation(String relationId)
                    throws RelationServiceNotRegisteredException,
                           IllegalArgumentException,
                           RelationNotFoundException
Removes given relation from the Relation Service.

A RelationNotification notification is sent, its type being:

- RelationNotification.RELATION_BASIC_REMOVAL if the relation was only internal to the Relation Service

- RelationNotification.RELATION_MBEAN_REMOVAL if the relation is registered as an MBean.

For MBeans referenced in such relation, nothing will be done,

Specified by:
removeRelation in interface RelationServiceMBean
Parameters:
relationId - relation id of the relation to be removed
Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation corresponding to given relation id

purgeRelations

public void purgeRelations()
                    throws RelationServiceNotRegisteredException
Purges the relations.

Depending on the purgeFlag value, this method is either called automatically when a notification is received for the unregistration of an MBean referenced in a relation (if the flag is set to true), or not (if the flag is set to false).

In that case it is up to the user to call it to maintain the consistency of the relations. To be kept in mind that if an MBean is unregistered and the purge not done immediately, if the ObjectName is reused and assigned to another MBean referenced in a relation, calling manually this purgeRelations() method will cause trouble, as will consider the ObjectName as corresponding to the unregistered MBean, not seeing the new one.

The behavior depends on the cardinality of the role where the unregistered MBean is referenced:

- if removing one MBean reference in the role makes its number of references less than the minimum degree, the relation has to be removed.

- if the remaining number of references after removing the MBean reference is still in the cardinality range, keep the relation and update it calling its handleMBeanUnregistration() callback.

Specified by:
purgeRelations in interface RelationServiceMBean
Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server.

findReferencingRelations

public Map<String,List<String>> findReferencingRelations(ObjectName mbeanName,
                                                         String relationTypeName,
                                                         String roleName)
                                                  throws IllegalArgumentException
Retrieves the relations where a given MBean is referenced.

This corresponds to the CIM "References" and "ReferenceNames" operations.

Specified by:
findReferencingRelations in interface RelationServiceMBean
Parameters:
mbeanName - ObjectName of MBean
relationTypeName - can be null; if specified, only the relations of that type will be considered in the search. Else all relation types are considered.
roleName - can be null; if specified, only the relations where the MBean is referenced in that role will be returned. Else all roles are considered.
Returns:
an HashMap, where the keys are the relation ids of the relations where the MBean is referenced, and the value is, for each key, an ArrayList of role names (as an MBean can be referenced in several roles in the same relation).
Throws:
IllegalArgumentException - if null parameter

findAssociatedMBeans

public Map<ObjectName,List<String>> findAssociatedMBeans(ObjectName mbeanName,
                                                         String relationTypeName,
                                                         String roleName)
                                                  throws IllegalArgumentException
Retrieves the MBeans associated to given one in a relation.

This corresponds to CIM Associators and AssociatorNames operations.

Specified by:
findAssociatedMBeans in interface RelationServiceMBean
Parameters:
mbeanName - ObjectName of MBean
relationTypeName - can be null; if specified, only the relations of that type will be considered in the search. Else all relation types are considered.
roleName - can be null; if specified, only the relations where the MBean is referenced in that role will be considered. Else all roles are considered.
Returns:
an HashMap, where the keys are the ObjectNames of the MBeans associated to given MBean, and the value is, for each key, an ArrayList of the relation ids of the relations where the key MBean is associated to given one (as they can be associated in several different relations).
Throws:
IllegalArgumentException - if null parameter

findRelationsOfType

public List<String> findRelationsOfType(String relationTypeName)
                                 throws IllegalArgumentException,
                                        RelationTypeNotFoundException
Returns the relation ids for relations of the given type.

Specified by:
findRelationsOfType in interface RelationServiceMBean
Parameters:
relationTypeName - relation type name
Returns:
an ArrayList of relation ids.
Throws:
IllegalArgumentException - if null parameter
RelationTypeNotFoundException - if there is no relation type with that name.

getRole

public List<ObjectName> getRole(String relationId,
                                String roleName)
                         throws RelationServiceNotRegisteredException,
                                IllegalArgumentException,
                                RelationNotFoundException,
                                RoleNotFoundException
Retrieves role value for given role name in given relation.

Specified by:
getRole in interface RelationServiceMBean
Parameters:
relationId - relation id
roleName - name of role
Returns:
the ArrayList of ObjectName objects being the role value
Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation with given id
RoleNotFoundException - if:

- there is no role with given name

or

- the role is not readable.

See Also:
setRole(java.lang.String, javax.management.relation.Role)

getRoles

public RoleResult getRoles(String relationId,
                           String[] roleNameArray)
                    throws RelationServiceNotRegisteredException,
                           IllegalArgumentException,
                           RelationNotFoundException
Retrieves values of roles with given names in given relation.

Specified by:
getRoles in interface RelationServiceMBean
Parameters:
relationId - relation id
roleNameArray - array of names of roles to be retrieved
Returns:
a RoleResult object, including a RoleList (for roles successfully retrieved) and a RoleUnresolvedList (for roles not retrieved).
Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation with given id
See Also:
setRoles(java.lang.String, javax.management.relation.RoleList)

getAllRoles

public RoleResult getAllRoles(String relationId)
                       throws IllegalArgumentException,
                              RelationNotFoundException,
                              RelationServiceNotRegisteredException
Returns all roles present in the relation.

Specified by:
getAllRoles in interface RelationServiceMBean
Parameters:
relationId - relation id
Returns:
a RoleResult object, including a RoleList (for roles successfully retrieved) and a RoleUnresolvedList (for roles not readable).
Throws:
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation for given id
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server

getRoleCardinality

public Integer getRoleCardinality(String relationId,
                                  String roleName)
                           throws IllegalArgumentException,
                                  RelationNotFoundException,
                                  RoleNotFoundException
Retrieves the number of MBeans currently referenced in the given role.

Specified by:
getRoleCardinality in interface RelationServiceMBean
Parameters:
relationId - relation id
roleName - name of role
Returns:
the number of currently referenced MBeans in that role
Throws:
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation with given id
RoleNotFoundException - if there is no role with given name

setRole

public void setRole(String relationId,
                    Role role)
             throws RelationServiceNotRegisteredException,
                    IllegalArgumentException,
                    RelationNotFoundException,
                    RoleNotFoundException,
                    InvalidRoleValueException
Sets the given role in given relation.

Will check the role according to its corresponding role definition provided in relation's relation type

The Relation Service will keep track of the change to keep the consistency of relations by handling referenced MBean unregistrations.

Specified by:
setRole in interface RelationServiceMBean
Parameters:
relationId - relation id
role - role to be set (name and new value)
Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation with given id
RoleNotFoundException - if the role does not exist or is not writable
InvalidRoleValueException - if value provided for role is not valid:

- the number of referenced MBeans in given value is less than expected minimum degree

or

- the number of referenced MBeans in provided value exceeds expected maximum degree

or

- one referenced MBean in the value is not an Object of the MBean class expected for that role

or

- an MBean provided for that role does not exist

See Also:
getRole(java.lang.String, java.lang.String)

setRoles

public RoleResult setRoles(String relationId,
                           RoleList roleList)
                    throws RelationServiceNotRegisteredException,
                           IllegalArgumentException,
                           RelationNotFoundException
Sets the given roles in given relation.

Will check the role according to its corresponding role definition provided in relation's relation type

The Relation Service keeps track of the changes to keep the consistency of relations by handling referenced MBean unregistrations.

Specified by:
setRoles in interface RelationServiceMBean
Parameters:
relationId - relation id
roleList - list of roles to be set
Returns:
a RoleResult object, including a RoleList (for roles successfully set) and a RoleUnresolvedList (for roles not set).
Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation with given id
See Also:
getRoles(java.lang.String, java.lang.String[])

getReferencedMBeans

public Map<ObjectName,List<String>> getReferencedMBeans(String relationId)
                                                 throws IllegalArgumentException,
                                                        RelationNotFoundException
Retrieves MBeans referenced in the various roles of the relation.

Specified by:
getReferencedMBeans in interface RelationServiceMBean
Parameters:
relationId - relation id
Returns:
a HashMap mapping:

ObjectName -> ArrayList of String (role names)

Throws:
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation for given relation id

getRelationTypeName

public String getRelationTypeName(String relationId)
                           throws IllegalArgumentException,
                                  RelationNotFoundException
Returns name of associated relation type for given relation.

Specified by:
getRelationTypeName in interface RelationServiceMBean
Parameters:
relationId - relation id
Returns:
the name of the associated relation type.
Throws:
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation for given relation id

handleNotification

public void handleNotification(Notification notif,
                               Object handback)
Invoked when a JMX notification occurs. Currently handles notifications for unregistration of MBeans, either referenced in a relation role or being a relation itself.

Specified by:
handleNotification in interface NotificationListener
Parameters:
notif - The notification.
handback - An opaque object which helps the listener to associate information regarding the MBean emitter (can be null).

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()
Returns a NotificationInfo object containing the name of the Java class of the notification and the notification types sent.

Specified by:
getNotificationInfo in interface NotificationBroadcaster
Overrides:
getNotificationInfo in class NotificationBroadcasterSupport
Returns:
the array of possible notifications.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RelationServiceMBean

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Interface RelationServiceMBean

All Known Implementing Classes:
RelationService
public interface RelationServiceMBean

The Relation Service is in charge of creating and deleting relation types and relations, of handling the consistency and of providing query mechanisms.

Since:
1.5

Method Summary
void | addRelation(ObjectName relationObjectName) Adds an MBean created by the user (and registered by him in the MBean Server) as a relation in the Relation Service.
void | addRelationType(RelationType relationTypeObj) Adds given object as a relation type.
Integer | checkRoleReading(String roleName, String relationTypeName) Checks if given Role can be read in a relation of the given type.
Integer | checkRoleWriting(Role role, String relationTypeName, Boolean initFlag) Checks if given Role can be set in a relation of given type.
void | createRelation(String relationId, String relationTypeName, RoleList roleList) Creates a simple relation (represented by a RelationSupport object) of given relation type, and adds it in the Relation Service.
void | createRelationType(String relationTypeName, RoleInfo[] roleInfoArray) Creates a relation type (RelationTypeSupport object) with given role infos (provided by the RoleInfo objects), and adds it in the Relation Service.
Map<ObjectName,List<String>> | findAssociatedMBeans(ObjectName mbeanName, String relationTypeName, String roleName) Retrieves the MBeans associated to given one in a relation.
Map<String,List<String>> | findReferencingRelations(ObjectName mbeanName, String relationTypeName, String roleName) Retrieves the relations where a given MBean is referenced.
List<String> | findRelationsOfType(String relationTypeName) Returns the relation ids for relations of the given type.
List<String> | getAllRelationIds() Returns all the relation ids for all the relations handled by the Relation Service.
List<String> | getAllRelationTypeNames() Retrieves names of all known relation types.
RoleResult | getAllRoles(String relationId) Returns all roles present in the relation.
boolean | getPurgeFlag() Returns the flag to indicate if when a notification is received for the unregistration of an MBean referenced in a relation, if an immediate "purge" of the relations (look for the relations no longer valid) has to be performed, or if that will be performed only when the purgeRelations method is explicitly called.
Map<ObjectName,List<String>> | getReferencedMBeans(String relationId) Retrieves MBeans referenced in the various roles of the relation.
String | getRelationTypeName(String relationId) Returns name of associated relation type for given relation.
List<ObjectName> | getRole(String relationId, String roleName) Retrieves role value for given role name in given relation.
Integer | getRoleCardinality(String relationId, String roleName) Retrieves the number of MBeans currently referenced in the given role.
RoleInfo | getRoleInfo(String relationTypeName, String roleInfoName) Retrieves role info for given role of a given relation type.
List<RoleInfo> | getRoleInfos(String relationTypeName) Retrieves list of role infos (RoleInfo objects) of a given relation type.
RoleResult | getRoles(String relationId, String[] roleNameArray) Retrieves values of roles with given names in given relation.
Boolean | hasRelation(String relationId) Checks if there is a relation identified in Relation Service with given relation id.
void | isActive() Checks if the Relation Service is active.
String | isRelation(ObjectName objectName) Returns the relation id associated to the given ObjectName if the MBean has been added as a relation in the Relation Service.
ObjectName | isRelationMBean(String relationId) If the relation is represented by an MBean (created by the user and added as a relation in the Relation Service), returns the ObjectName of the MBean.
void | purgeRelations() Purges the relations.
void | removeRelation(String relationId) Removes given relation from the Relation Service.
void | removeRelationType(String relationTypeName) Removes given relation type from Relation Service.
void | sendRelationCreationNotification(String relationId) Sends a notification (RelationNotification) for a relation creation.
void | sendRelationRemovalNotification(String relationId, List<ObjectName> unregMBeanList) Sends a notification (RelationNotification) for a relation removal.
void | sendRoleUpdateNotification(String relationId, Role newRole, List<ObjectName> oldRoleValue) Sends a notification (RelationNotification) for a role update in the given relation.
void | setPurgeFlag(boolean purgeFlag) Sets the flag to indicate if when a notification is received for the unregistration of an MBean referenced in a relation, if an immediate "purge" of the relations (look for the relations no longer valid) has to be performed, or if that will be performed only when the purgeRelations method is explicitly called.
void | setRole(String relationId, Role role) Sets the given role in given relation.
RoleResult | setRoles(String relationId, RoleList roleList) Sets the given roles in given relation.
void | updateRoleMap(String relationId, Role newRole, List<ObjectName> oldRoleValue) Handles update of the Relation Service role map for the update of given role in given relation.

Method Detail

isActive

void isActive()
              throws RelationServiceNotRegisteredException
Checks if the Relation Service is active. Current condition is that the Relation Service must be registered in the MBean Server

Throws:
RelationServiceNotRegisteredException - if it is not registered

getPurgeFlag

boolean getPurgeFlag()
Returns the flag to indicate if when a notification is received for the unregistration of an MBean referenced in a relation, if an immediate "purge" of the relations (look for the relations no longer valid) has to be performed, or if that will be performed only when the purgeRelations method is explicitly called.

true is immediate purge.

Returns:
true if purges are immediate.
See Also:
setPurgeFlag(boolean)

setPurgeFlag

void setPurgeFlag(boolean purgeFlag)
Sets the flag to indicate if when a notification is received for the unregistration of an MBean referenced in a relation, if an immediate "purge" of the relations (look for the relations no longer valid) has to be performed, or if that will be performed only when the purgeRelations method is explicitly called.

true is immediate purge.

Parameters:
purgeFlag - flag
See Also:
getPurgeFlag()

createRelationType

void createRelationType(String relationTypeName,
                        RoleInfo[] roleInfoArray)
                        throws IllegalArgumentException,
                               InvalidRelationTypeException
Creates a relation type (RelationTypeSupport object) with given role infos (provided by the RoleInfo objects), and adds it in the Relation Service.

Parameters:
relationTypeName - name of the relation type
roleInfoArray - array of role infos
Throws:
IllegalArgumentException - if null parameter
InvalidRelationTypeException - If:

- there is already a relation type with that name

- the same name has been used for two different role infos

- no role info provided

- one null role info provided

addRelationType

void addRelationType(RelationType relationTypeObj)
                     throws IllegalArgumentException,
                            InvalidRelationTypeException
Adds given object as a relation type. The object is expected to implement the RelationType interface.

Parameters:
relationTypeObj - relation type object (implementing the RelationType interface)
Throws:
IllegalArgumentException - if null parameter or if relationTypeObj.getRelationTypeName() returns null.
InvalidRelationTypeException - if there is already a relation type with that name

getAllRelationTypeNames

List<String> getAllRelationTypeNames()
Retrieves names of all known relation types.

Returns:
ArrayList of relation type names (Strings)

getRoleInfos

List<RoleInfo> getRoleInfos(String relationTypeName)
                            throws IllegalArgumentException,
                                   RelationTypeNotFoundException
Retrieves list of role infos (RoleInfo objects) of a given relation type.

Parameters:
relationTypeName - name of relation type
Returns:
ArrayList of RoleInfo.
Throws:
IllegalArgumentException - if null parameter
RelationTypeNotFoundException - if there is no relation type with that name.

getRoleInfo

RoleInfo getRoleInfo(String relationTypeName,
                     String roleInfoName)
                     throws IllegalArgumentException,
                            RelationTypeNotFoundException,
                            RoleInfoNotFoundException
Retrieves role info for given role of a given relation type.

Parameters:
relationTypeName - name of relation type
roleInfoName - name of role
Returns:
RoleInfo object.
Throws:
IllegalArgumentException - if null parameter
RelationTypeNotFoundException - if the relation type is not known in the Relation Service
RoleInfoNotFoundException - if the role is not part of the relation type.

removeRelationType

void removeRelationType(String relationTypeName)
                        throws RelationServiceNotRegisteredException,
                               IllegalArgumentException,
                               RelationTypeNotFoundException
Removes given relation type from Relation Service.

The relation objects of that type will be removed from the Relation Service.

Parameters:
relationTypeName - name of the relation type to be removed
Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
IllegalArgumentException - if null parameter
RelationTypeNotFoundException - If there is no relation type with that name

createRelation

void createRelation(String relationId,
                    String relationTypeName,
                    RoleList roleList)
                    throws RelationServiceNotRegisteredException,
                           IllegalArgumentException,
                           RoleNotFoundException,
                           InvalidRelationIdException,
                           RelationTypeNotFoundException,
                           InvalidRoleValueException
Creates a simple relation (represented by a RelationSupport object) of given relation type, and adds it in the Relation Service.

Roles are initialized according to the role list provided in parameter. The ones not initialized in this way are set to an empty ArrayList of ObjectNames.

A RelationNotification, with type RELATION_BASIC_CREATION, is sent.

Parameters:
relationId - relation identifier, to identify uniquely the relation inside the Relation Service
relationTypeName - name of the relation type (has to be created in the Relation Service)
roleList - role list to initialize roles of the relation (can be null).
Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
IllegalArgumentException - if null parameter
RoleNotFoundException - if a value is provided for a role that does not exist in the relation type
InvalidRelationIdException - if relation id already used
RelationTypeNotFoundException - if relation type not known in Relation Service
InvalidRoleValueException - if:

- the same role name is used for two different roles

- the number of referenced MBeans in given value is less than expected minimum degree

- the number of referenced MBeans in provided value exceeds expected maximum degree

- one referenced MBean in the value is not an Object of the MBean class expected for that role

- an MBean provided for that role does not exist

addRelation

void addRelation(ObjectName relationObjectName)
                 throws IllegalArgumentException,
                        RelationServiceNotRegisteredException,
                        NoSuchMethodException,
                        InvalidRelationIdException,
                        InstanceNotFoundException,
                        InvalidRelationServiceException,
                        RelationTypeNotFoundException,
                        RoleNotFoundException,
                        InvalidRoleValueException
Adds an MBean created by the user (and registered by him in the MBean Server) as a relation in the Relation Service.

To be added as a relation, the MBean must conform to the following:

- implement the Relation interface

- have for RelationService ObjectName the ObjectName of current Relation Service

- have a relation id that is unique and unused in current Relation Service

- have for relation type a relation type created in the Relation Service

- have roles conforming to the role info provided in the relation type.

Parameters:
relationObjectName - ObjectName of the relation MBean to be added.
Throws:
IllegalArgumentException - if null parameter
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
NoSuchMethodException - If the MBean does not implement the Relation interface
InvalidRelationIdException - if:

- no relation identifier in MBean

- the relation identifier is already used in the Relation Service

InstanceNotFoundException - if the MBean for given ObjectName has not been registered
InvalidRelationServiceException - if:

- no Relation Service name in MBean

- the Relation Service name in the MBean is not the one of the current Relation Service

RelationTypeNotFoundException - if:

- no relation type name in MBean

- the relation type name in MBean does not correspond to a relation type created in the Relation Service

InvalidRoleValueException - if:

- the number of referenced MBeans in a role is less than expected minimum degree

- the number of referenced MBeans in a role exceeds expected maximum degree

- one referenced MBean in the value is not an Object of the MBean class expected for that role

- an MBean provided for a role does not exist

RoleNotFoundException - if a value is provided for a role that does not exist in the relation type

isRelationMBean

ObjectName isRelationMBean(String relationId)
                           throws IllegalArgumentException,
                                  RelationNotFoundException
If the relation is represented by an MBean (created by the user and added as a relation in the Relation Service), returns the ObjectName of the MBean.

Parameters:
relationId - relation id identifying the relation
Returns:
ObjectName of the corresponding relation MBean, or null if the relation is not an MBean.
Throws:
IllegalArgumentException - if null parameter
RelationNotFoundException - there is no relation associated to that id

isRelation

String isRelation(ObjectName objectName)
                  throws IllegalArgumentException
Returns the relation id associated to the given ObjectName if the MBean has been added as a relation in the Relation Service.

Parameters:
objectName - ObjectName of supposed relation
Returns:
relation id (String) or null (if the ObjectName is not a relation handled by the Relation Service)
Throws:
IllegalArgumentException - if null parameter

hasRelation

Boolean hasRelation(String relationId)
                    throws IllegalArgumentException
Checks if there is a relation identified in Relation Service with given relation id.

Parameters:
relationId - relation id identifying the relation
Returns:
boolean: true if there is a relation, false else
Throws:
IllegalArgumentException - if null parameter

getAllRelationIds

List<String> getAllRelationIds()
Returns all the relation ids for all the relations handled by the Relation Service.

Returns:
ArrayList of String

checkRoleReading

Integer checkRoleReading(String roleName,
                         String relationTypeName)
                         throws IllegalArgumentException,
                                RelationTypeNotFoundException
Checks if given Role can be read in a relation of the given type.

Parameters:
roleName - name of role to be checked
relationTypeName - name of the relation type
Returns:
an Integer wrapping an integer corresponding to possible problems represented as constants in RoleUnresolved:

- 0 if role can be read

- integer corresponding to RoleStatus.NO_ROLE_WITH_NAME

- integer corresponding to RoleStatus.ROLE_NOT_READABLE

Throws:
IllegalArgumentException - if null parameter
RelationTypeNotFoundException - if the relation type is not known in the Relation Service

checkRoleWriting

Integer checkRoleWriting(Role role,
                         String relationTypeName,
                         Boolean initFlag)
                         throws IllegalArgumentException,
                                RelationTypeNotFoundException
Checks if given Role can be set in a relation of given type.

Parameters:
role - role to be checked
relationTypeName - name of relation type
initFlag - flag to specify that the checking is done for the initialization of a role, write access shall not be verified.
Returns:
an Integer wrapping an integer corresponding to possible problems represented as constants in RoleUnresolved:

- 0 if role can be set

- integer corresponding to RoleStatus.NO_ROLE_WITH_NAME

- integer for RoleStatus.ROLE_NOT_WRITABLE

- integer for RoleStatus.LESS_THAN_MIN_ROLE_DEGREE

- integer for RoleStatus.MORE_THAN_MAX_ROLE_DEGREE

- integer for RoleStatus.REF_MBEAN_OF_INCORRECT_CLASS

- integer for RoleStatus.REF_MBEAN_NOT_REGISTERED

Throws:
IllegalArgumentException - if null parameter
RelationTypeNotFoundException - if unknown relation type

sendRelationCreationNotification

void sendRelationCreationNotification(String relationId)
                                      throws IllegalArgumentException,
                                             RelationNotFoundException
Sends a notification (RelationNotification) for a relation creation. The notification type is:

- RelationNotification.RELATION_BASIC_CREATION if the relation is an object internal to the Relation Service

- RelationNotification.RELATION_MBEAN_CREATION if the relation is a MBean added as a relation.

The source object is the Relation Service itself.

It is called in Relation Service createRelation() and addRelation() methods.

Parameters:
relationId - relation identifier of the updated relation
Throws:
IllegalArgumentException - if null parameter
RelationNotFoundException - if there is no relation for given relation id

sendRoleUpdateNotification

void sendRoleUpdateNotification(String relationId,
                                Role newRole,
                                List<ObjectName> oldRoleValue)
                                throws IllegalArgumentException,
                                       RelationNotFoundException
Sends a notification (RelationNotification) for a role update in the given relation. The notification type is:

- RelationNotification.RELATION_BASIC_UPDATE if the relation is an object internal to the Relation Service

- RelationNotification.RELATION_MBEAN_UPDATE if the relation is a MBean added as a relation.

The source object is the Relation Service itself.

It is called in relation MBean setRole() (for given role) and setRoles() (for each role) methods (implementation provided in RelationSupport class).

It is also called in Relation Service setRole() (for given role) and setRoles() (for each role) methods.

Parameters:
relationId - relation identifier of the updated relation
newRole - new role (name and new value)
oldRoleValue - old role value (List of ObjectName objects)
Throws:
IllegalArgumentException - if null parameter
RelationNotFoundException - if there is no relation for given relation id

sendRelationRemovalNotification

void sendRelationRemovalNotification(String relationId,
                                     List<ObjectName> unregMBeanList)
                                     throws IllegalArgumentException,
                                            RelationNotFoundException
Sends a notification (RelationNotification) for a relation removal. The notification type is:

- RelationNotification.RELATION_BASIC_REMOVAL if the relation is an object internal to the Relation Service

- RelationNotification.RELATION_MBEAN_REMOVAL if the relation is a MBean added as a relation.

The source object is the Relation Service itself.

It is called in Relation Service removeRelation() method.

Parameters:
relationId - relation identifier of the updated relation
unregMBeanList - List of ObjectNames of MBeans expected to be unregistered due to relation removal (can be null)
Throws:
IllegalArgumentException - if null parameter
RelationNotFoundException - if there is no relation for given relation id

updateRoleMap

void updateRoleMap(String relationId,
                   Role newRole,
                   List<ObjectName> oldRoleValue)
                   throws IllegalArgumentException,
                          RelationServiceNotRegisteredException,
                          RelationNotFoundException
Handles update of the Relation Service role map for the update of given role in given relation.

It is called in relation MBean setRole() (for given role) and setRoles() (for each role) methods (implementation provided in RelationSupport class).

It is also called in Relation Service setRole() (for given role) and setRoles() (for each role) methods.

To allow the Relation Service to maintain the consistency (in case of MBean unregistration) and to be able to perform queries, this method must be called when a role is updated.

Parameters:
relationId - relation identifier of the updated relation
newRole - new role (name and new value)
oldRoleValue - old role value (List of ObjectName objects)
Throws:
IllegalArgumentException - if null parameter
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
RelationNotFoundException - if no relation for given id.

removeRelation

void removeRelation(String relationId)
                    throws RelationServiceNotRegisteredException,
                           IllegalArgumentException,
                           RelationNotFoundException
Removes given relation from the Relation Service.

A RelationNotification notification is sent, its type being:

- RelationNotification.RELATION_BASIC_REMOVAL if the relation was only internal to the Relation Service

- RelationNotification.RELATION_MBEAN_REMOVAL if the relation is registered as an MBean.

For MBeans referenced in such relation, nothing will be done,

Parameters:
relationId - relation id of the relation to be removed
Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation corresponding to given relation id

purgeRelations

void purgeRelations()
                    throws RelationServiceNotRegisteredException
Purges the relations.

Depending on the purgeFlag value, this method is either called automatically when a notification is received for the unregistration of an MBean referenced in a relation (if the flag is set to true), or not (if the flag is set to false).

In that case it is up to the user to call it to maintain the consistency of the relations. To be kept in mind that if an MBean is unregistered and the purge not done immediately, if the ObjectName is reused and assigned to another MBean referenced in a relation, calling manually this purgeRelations() method will cause trouble, as will consider the ObjectName as corresponding to the unregistered MBean, not seeing the new one.

The behavior depends on the cardinality of the role where the unregistered MBean is referenced:

- if removing one MBean reference in the role makes its number of references less than the minimum degree, the relation has to be removed.

- if the remaining number of references after removing the MBean reference is still in the cardinality range, keep the relation and update it calling its handleMBeanUnregistration() callback.

Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server.

findReferencingRelations

Map<String,List<String>> findReferencingRelations(ObjectName mbeanName,
                                                  String relationTypeName,
                                                  String roleName)
                                                  throws IllegalArgumentException
Retrieves the relations where a given MBean is referenced.

This corresponds to the CIM "References" and "ReferenceNames" operations.

Parameters:
mbeanName - ObjectName of MBean
relationTypeName - can be null; if specified, only the relations of that type will be considered in the search. Else all relation types are considered.
roleName - can be null; if specified, only the relations where the MBean is referenced in that role will be returned. Else all roles are considered.
Returns:
an HashMap, where the keys are the relation ids of the relations where the MBean is referenced, and the value is, for each key, an ArrayList of role names (as an MBean can be referenced in several roles in the same relation).
Throws:
IllegalArgumentException - if null parameter

findAssociatedMBeans

Map<ObjectName,List<String>> findAssociatedMBeans(ObjectName mbeanName,
                                                  String relationTypeName,
                                                  String roleName)
                                                  throws IllegalArgumentException
Retrieves the MBeans associated to given one in a relation.

This corresponds to CIM Associators and AssociatorNames operations.

Parameters:
mbeanName - ObjectName of MBean
relationTypeName - can be null; if specified, only the relations of that type will be considered in the search. Else all relation types are considered.
roleName - can be null; if specified, only the relations where the MBean is referenced in that role will be considered. Else all roles are considered.
Returns:
an HashMap, where the keys are the ObjectNames of the MBeans associated to given MBean, and the value is, for each key, an ArrayList of the relation ids of the relations where the key MBean is associated to given one (as they can be associated in several different relations).
Throws:
IllegalArgumentException - if null parameter

findRelationsOfType

List<String> findRelationsOfType(String relationTypeName)
                                 throws IllegalArgumentException,
                                        RelationTypeNotFoundException
Returns the relation ids for relations of the given type.

Parameters:
relationTypeName - relation type name
Returns:
an ArrayList of relation ids.
Throws:
IllegalArgumentException - if null parameter
RelationTypeNotFoundException - if there is no relation type with that name.

getRole

List<ObjectName> getRole(String relationId,
                         String roleName)
                         throws RelationServiceNotRegisteredException,
                                IllegalArgumentException,
                                RelationNotFoundException,
                                RoleNotFoundException
Retrieves role value for given role name in given relation.

Parameters:
relationId - relation id
roleName - name of role
Returns:
the ArrayList of ObjectName objects being the role value
Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation with given id
RoleNotFoundException - if:

- there is no role with given name

or

- the role is not readable.

See Also:
setRole(java.lang.String, javax.management.relation.Role)

getRoles

RoleResult getRoles(String relationId,
                    String[] roleNameArray)
                    throws RelationServiceNotRegisteredException,
                           IllegalArgumentException,
                           RelationNotFoundException
Retrieves values of roles with given names in given relation.

Parameters:
relationId - relation id
roleNameArray - array of names of roles to be retrieved
Returns:
a RoleResult object, including a RoleList (for roles successfully retrieved) and a RoleUnresolvedList (for roles not retrieved).
Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation with given id
See Also:
setRoles(java.lang.String, javax.management.relation.RoleList)

getAllRoles

RoleResult getAllRoles(String relationId)
                       throws IllegalArgumentException,
                              RelationNotFoundException,
                              RelationServiceNotRegisteredException
Returns all roles present in the relation.

Parameters:
relationId - relation id
Returns:
a RoleResult object, including a RoleList (for roles successfully retrieved) and a RoleUnresolvedList (for roles not readable).
Throws:
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation for given id
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server

getRoleCardinality

Integer getRoleCardinality(String relationId,
                           String roleName)
                           throws IllegalArgumentException,
                                  RelationNotFoundException,
                                  RoleNotFoundException
Retrieves the number of MBeans currently referenced in the given role.

Parameters:
relationId - relation id
roleName - name of role
Returns:
the number of currently referenced MBeans in that role
Throws:
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation with given id
RoleNotFoundException - if there is no role with given name

setRole

void setRole(String relationId,
             Role role)
             throws RelationServiceNotRegisteredException,
                    IllegalArgumentException,
                    RelationNotFoundException,
                    RoleNotFoundException,
                    InvalidRoleValueException,
                    RelationTypeNotFoundException
Sets the given role in given relation.

Will check the role according to its corresponding role definition provided in relation's relation type

The Relation Service will keep track of the change to keep the consistency of relations by handling referenced MBean unregistrations.

Parameters:
relationId - relation id
role - role to be set (name and new value)
Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation with given id
RoleNotFoundException - if:

- internal relation

and

- the role does not exist or is not writable

InvalidRoleValueException - if internal relation and value provided for role is not valid:

- the number of referenced MBeans in given value is less than expected minimum degree

or

- the number of referenced MBeans in provided value exceeds expected maximum degree

or

- one referenced MBean in the value is not an Object of the MBean class expected for that role

or

- an MBean provided for that role does not exist

RelationTypeNotFoundException - if unknown relation type
See Also:
getRole(java.lang.String, java.lang.String)

setRoles

RoleResult setRoles(String relationId,
                    RoleList roleList)
                    throws RelationServiceNotRegisteredException,
                           IllegalArgumentException,
                           RelationNotFoundException
Sets the given roles in given relation.

Will check the role according to its corresponding role definition provided in relation's relation type

The Relation Service keeps track of the changes to keep the consistency of relations by handling referenced MBean unregistrations.

Parameters:
relationId - relation id
roleList - list of roles to be set
Returns:
a RoleResult object, including a RoleList (for roles successfully set) and a RoleUnresolvedList (for roles not set).
Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation with given id
See Also:
getRoles(java.lang.String, java.lang.String[])

getReferencedMBeans

Map<ObjectName,List<String>> getReferencedMBeans(String relationId)
                                                 throws IllegalArgumentException,
                                                        RelationNotFoundException
Retrieves MBeans referenced in the various roles of the relation.

Parameters:
relationId - relation id
Returns:
a HashMap mapping:

ObjectName -> ArrayList of String (role names)

Throws:
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation for given relation id

getRelationTypeName

String getRelationTypeName(String relationId)
                           throws IllegalArgumentException,
                                  RelationNotFoundException
Returns name of associated relation type for given relation.

Parameters:
relationId - relation id
Returns:
the name of the associated relation type.
Throws:
IllegalArgumentException - if null parameter
RelationNotFoundException - if no relation for given relation id
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RelationServiceNotRegisteredException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class RelationServiceNotRegisteredException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.relation.RelationException
                    extended by  javax.management.relation.RelationServiceNotRegisteredException
All Implemented Interfaces:
Serializable
public class RelationServiceNotRegisteredException
extends RelationException

This exception is raised when an access is done to the Relation Service and that one is not registered.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
RelationServiceNotRegisteredException()
Default constructor, no message put in exception.
RelationServiceNotRegisteredException(String message)
Constructor with given message put in exception.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RelationServiceNotRegisteredException

public RelationServiceNotRegisteredException()
Default constructor, no message put in exception.

RelationServiceNotRegisteredException

public RelationServiceNotRegisteredException(String message)
Constructor with given message put in exception.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RelationSupport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class RelationSupport

java.lang.Object
    extended by  javax.management.relation.RelationSupport
All Implemented Interfaces:
MBeanRegistration, Relation, RelationSupportMBean
public class RelationSupport
extends Object
implements RelationSupportMBean, MBeanRegistration

A RelationSupport object is used internally by the Relation Service to represent simple relations (only roles, no properties or methods), with an unlimited number of roles, of any relation type. As internal representation, it is not exposed to the user.

RelationSupport class conforms to the design patterns of standard MBean. So the user can decide to instantiate a RelationSupport object himself as a MBean (as it follows the MBean design patterns), to register it in the MBean Server, and then to add it in the Relation Service.

The user can also, when creating his own MBean relation class, have it extending RelationSupport, to retrieve the implementations of required interfaces (see below).

It is also possible to have in a user relation MBean class a member being a RelationSupport object, and to implement the required interfaces by delegating all to this member.

RelationSupport implements the Relation interface (to be handled by the Relation Service).

It implements also the MBeanRegistration interface to be able to retrieve the MBean Server where it is registered (if registered as a MBean) to access to its Relation Service.

Since:
1.5

Constructor Summary
RelationSupport(String relationId, ObjectName relationServiceName, MBeanServer relationServiceMBeanServer, String relationTypeName, RoleList list)
Creates a RelationSupport object.
RelationSupport(String relationId, ObjectName relationServiceName, String relationTypeName, RoleList list)
Creates a RelationSupport object.
Method Summary
RoleResult | getAllRoles() Returns all roles present in the relation.
Map<ObjectName,List<String>> | getReferencedMBeans() Retrieves MBeans referenced in the various roles of the relation.
String | getRelationId() Returns relation identifier (used to uniquely identify the relation inside the Relation Service).
ObjectName | getRelationServiceName() Returns ObjectName of the Relation Service handling the relation.
String | getRelationTypeName() Returns name of associated relation type.
List<ObjectName> | getRole(String roleName) Retrieves role value for given role name.
Integer | getRoleCardinality(String roleName) Returns the number of MBeans currently referenced in the given role.
RoleResult | getRoles(String[] roleNameArray) Retrieves values of roles with given names.
void | handleMBeanUnregistration(ObjectName objectName, String roleName) Callback used by the Relation Service when a MBean referenced in a role is unregistered.
Boolean | isInRelationService() Returns an internal flag specifying if the object is still handled by the Relation Service.
void | postDeregister() Allows the MBean to perform any operations needed after having been unregistered in the MBean server.
void | postRegister(Boolean registrationDone) Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.
void | preDeregister() Allows the MBean to perform any operations it needs before being unregistered by the MBean server.
ObjectName | preRegister(MBeanServer server, ObjectName name) Allows the MBean to perform any operations it needs before being registered in the MBean server.
RoleList | retrieveAllRoles() Returns all roles in the relation without checking read mode.
void | setRelationServiceManagementFlag(Boolean flag) Specifies whether this relation is handled by the Relation Service.
void | setRole(Role role) Sets the given role.
RoleResult | setRoles(RoleList list) Sets the given roles.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RelationSupport

public RelationSupport(String relationId,
                       ObjectName relationServiceName,
                       String relationTypeName,
                       RoleList list)
                throws InvalidRoleValueException,
                       IllegalArgumentException
Creates a RelationSupport object.

This constructor has to be used when the RelationSupport object will be registered as a MBean by the user, or when creating a user relation MBean whose class extends RelationSupport.

Nothing is done at the Relation Service level, i.e. the RelationSupport object is not added to the RelationService and no checks are performed to see if the provided values are correct. The object is always created, EXCEPT if:

- any of the required parameters is null.

- the same name is used for two roles.

To be handled as a relation, the RelationSupport object has to be added to the Relation Service using the Relation Service method addRelation().

Parameters:
relationId - relation identifier, to identify the relation in the Relation Service.

Expected to be unique in the given Relation Service.

relationServiceName - ObjectName of the Relation Service where the relation will be registered.

This parameter is required as it is the Relation Service that is aware of the definition of the relation type of the given relation, so that will be able to check update operations (set).

relationTypeName - Name of relation type.

Expected to have been created in the given Relation Service.

list - list of roles (Role objects) to initialize the relation. Can be null.

Expected to conform to relation info in associated relation type.

Throws:
InvalidRoleValueException - if the same name is used for two roles.
IllegalArgumentException - if any of the required parameters (relation id, relation service ObjectName, or relation type name) is null.

RelationSupport

public RelationSupport(String relationId,
                       ObjectName relationServiceName,
                       MBeanServer relationServiceMBeanServer,
                       String relationTypeName,
                       RoleList list)
                throws InvalidRoleValueException,
                       IllegalArgumentException
Creates a RelationSupport object.

This constructor has to be used when the user relation MBean implements the interfaces expected to be supported by a relation by delegating to a RelationSupport object.

This object needs to know the Relation Service expected to handle the relation. So it has to know the MBean Server where the Relation Service is registered.

According to a limitation, a relation MBean must be registered in the same MBean Server as the Relation Service expected to handle it. So the user relation MBean has to be created and registered, and then the wrapped RelationSupport object can be created within the identified MBean Server.

Nothing is done at the Relation Service level, i.e. the RelationSupport object is not added to the RelationService and no checks are performed to see if the provided values are correct. The object is always created, EXCEPT if:

- any of the required parameters is null.

- the same name is used for two roles.

To be handled as a relation, the RelationSupport object has to be added to the Relation Service using the Relation Service method addRelation().

Parameters:
relationId - relation identifier, to identify the relation in the Relation Service.

Expected to be unique in the given Relation Service.

relationServiceName - ObjectName of the Relation Service where the relation will be registered.

This parameter is required as it is the Relation Service that is aware of the definition of the relation type of the given relation, so that will be able to check update operations (set).

relationServiceMBeanServer - MBean Server where the wrapping MBean is or will be registered.

Expected to be the MBean Server where the Relation Service is or will be registered.

relationTypeName - Name of relation type.

Expected to have been created in the given Relation Service.

list - list of roles (Role objects) to initialize the relation. Can be null.

Expected to conform to relation info in associated relation type.

Throws:
InvalidRoleValueException - if the same name is used for two roles.
IllegalArgumentException - if any of the required parameters (relation id, relation service ObjectName, relation service MBeanServer, or relation type name) is null.
Method Detail

getRole

public List<ObjectName> getRole(String roleName)
                         throws IllegalArgumentException,
                                RoleNotFoundException,
                                RelationServiceNotRegisteredException
Retrieves role value for given role name.

Checks if the role exists and is readable according to the relation type.

Specified by:
getRole in interface Relation
Parameters:
roleName - name of role
Returns:
the ArrayList of ObjectName objects being the role value
Throws:
IllegalArgumentException - if null role name
RoleNotFoundException - if:

- there is no role with given name

- the role is not readable.

RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
See Also:
setRole(javax.management.relation.Role)

getRoles

public RoleResult getRoles(String[] roleNameArray)
                    throws IllegalArgumentException,
                           RelationServiceNotRegisteredException
Retrieves values of roles with given names.

Checks for each role if it exists and is readable according to the relation type.

Specified by:
getRoles in interface Relation
Parameters:
roleNameArray - array of names of roles to be retrieved
Returns:
a RoleResult object, including a RoleList (for roles successfully retrieved) and a RoleUnresolvedList (for roles not retrieved).
Throws:
IllegalArgumentException - if null role name
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
See Also:
setRoles(javax.management.relation.RoleList)

getAllRoles

public RoleResult getAllRoles()
                       throws RelationServiceNotRegisteredException
Returns all roles present in the relation.

Specified by:
getAllRoles in interface Relation
Returns:
a RoleResult object, including a RoleList (for roles successfully retrieved) and a RoleUnresolvedList (for roles not readable).
Throws:
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server

retrieveAllRoles

public RoleList retrieveAllRoles()
Returns all roles in the relation without checking read mode.

Specified by:
retrieveAllRoles in interface Relation
Returns:
a RoleList

getRoleCardinality

public Integer getRoleCardinality(String roleName)
                           throws IllegalArgumentException,
                                  RoleNotFoundException
Returns the number of MBeans currently referenced in the given role.

Specified by:
getRoleCardinality in interface Relation
Parameters:
roleName - name of role
Returns:
the number of currently referenced MBeans in that role
Throws:
IllegalArgumentException - if null role name
RoleNotFoundException - if there is no role with given name

setRole

public void setRole(Role role)
             throws IllegalArgumentException,
                    RoleNotFoundException,
                    RelationTypeNotFoundException,
                    InvalidRoleValueException,
                    RelationServiceNotRegisteredException,
                    RelationNotFoundException
Sets the given role.

Will check the role according to its corresponding role definition provided in relation's relation type

Will send a notification (RelationNotification with type RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the relation is a MBean or not).

Specified by:
setRole in interface Relation
Parameters:
role - role to be set (name and new value)
Throws:
IllegalArgumentException - if null role
RoleNotFoundException - if there is no role with the supplied role's name or if the role is not writable (no test on the write access mode performed when initializing the role)
InvalidRoleValueException - if value provided for role is not valid, i.e.:

- the number of referenced MBeans in given value is less than expected minimum degree

- the number of referenced MBeans in provided value exceeds expected maximum degree

- one referenced MBean in the value is not an Object of the MBean class expected for that role

- a MBean provided for that role does not exist

RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
RelationTypeNotFoundException - if the relation type has not been declared in the Relation Service
RelationNotFoundException - if the relation has not been added in the Relation Service.
See Also:
getRole(java.lang.String)

setRoles

public RoleResult setRoles(RoleList list)
                    throws IllegalArgumentException,
                           RelationServiceNotRegisteredException,
                           RelationTypeNotFoundException,
                           RelationNotFoundException
Sets the given roles.

Will check the role according to its corresponding role definition provided in relation's relation type

Will send one notification (RelationNotification with type RELATION_BASIC_UPDATE or RELATION_MBEAN_UPDATE, depending if the relation is a MBean or not) per updated role.

Specified by:
setRoles in interface Relation
Parameters:
list - list of roles to be set
Returns:
a RoleResult object, including a RoleList (for roles successfully set) and a RoleUnresolvedList (for roles not set).
Throws:
IllegalArgumentException - if null role list
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
RelationTypeNotFoundException - if the relation type has not been declared in the Relation Service.
RelationNotFoundException - if the relation MBean has not been added in the Relation Service.
See Also:
getRoles(java.lang.String[])

handleMBeanUnregistration

public void handleMBeanUnregistration(ObjectName objectName,
                                      String roleName)
                               throws IllegalArgumentException,
                                      RoleNotFoundException,
                                      InvalidRoleValueException,
                                      RelationServiceNotRegisteredException,
                                      RelationTypeNotFoundException,
                                      RelationNotFoundException
Callback used by the Relation Service when a MBean referenced in a role is unregistered.

The Relation Service will call this method to let the relation take action to reflect the impact of such unregistration.

BEWARE. the user is not expected to call this method.

Current implementation is to set the role with its current value (list of ObjectNames of referenced MBeans) without the unregistered one.

Specified by:
handleMBeanUnregistration in interface Relation
Parameters:
objectName - ObjectName of unregistered MBean
roleName - name of role where the MBean is referenced
Throws:
IllegalArgumentException - if null parameter
RoleNotFoundException - if role does not exist in the relation or is not writable
InvalidRoleValueException - if role value does not conform to the associated role info (this will never happen when called from the Relation Service)
RelationServiceNotRegisteredException - if the Relation Service is not registered in the MBean Server
RelationTypeNotFoundException - if the relation type has not been declared in the Relation Service.
RelationNotFoundException - if this method is called for a relation MBean not added in the Relation Service.

getReferencedMBeans

public Map<ObjectName,List<String>> getReferencedMBeans()
Retrieves MBeans referenced in the various roles of the relation.

Specified by:
getReferencedMBeans in interface Relation
Returns:
a HashMap mapping:

ObjectName -> ArrayList of String (role names)

getRelationTypeName

public String getRelationTypeName()
Returns name of associated relation type.

Specified by:
getRelationTypeName in interface Relation
Returns:
the name of the relation type.

getRelationServiceName

public ObjectName getRelationServiceName()
Returns ObjectName of the Relation Service handling the relation.

Specified by:
getRelationServiceName in interface Relation
Returns:
the ObjectName of the Relation Service.

getRelationId

public String getRelationId()
Returns relation identifier (used to uniquely identify the relation inside the Relation Service).

Specified by:
getRelationId in interface Relation
Returns:
the relation id.

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception
Description copied from interface: MBeanRegistration
Allows the MBean to perform any operations it needs before being registered in the MBean server. If the name of the MBean is not specified, the MBean can provide a name for its registration. If any exception is raised, the MBean will not be registered in the MBean server.

Specified by:
preRegister in interface MBeanRegistration
Parameters:
server - The MBean server in which the MBean will be registered.
name - The object name of the MBean. This name is null if the name parameter to one of the createMBean or registerMBean methods in the MBeanServer interface is null. In that case, this method must return a non-null ObjectName for the new MBean.
Returns:
The name under which the MBean is to be registered. This value must not be null. If the name parameter is not null, it will usually but not necessarily be the returned value.
Throws:
Exception - This exception will be caught by the MBean server and re-thrown as an MBeanRegistrationException.

postRegister

public void postRegister(Boolean registrationDone)
Description copied from interface: MBeanRegistration
Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.

Specified by:
postRegister in interface MBeanRegistration
Parameters:
registrationDone - Indicates whether or not the MBean has been successfully registered in the MBean server. The value false means that the registration phase has failed.

preDeregister

public void preDeregister()
                   throws Exception
Description copied from interface: MBeanRegistration
Allows the MBean to perform any operations it needs before being unregistered by the MBean server.

Specified by:
preDeregister in interface MBeanRegistration
Throws:
Exception - This exception will be caught by the MBean server and re-thrown as an MBeanRegistrationException.

postDeregister

public void postDeregister()
Description copied from interface: MBeanRegistration
Allows the MBean to perform any operations needed after having been unregistered in the MBean server.

Specified by:
postDeregister in interface MBeanRegistration

isInRelationService

public Boolean isInRelationService()
Returns an internal flag specifying if the object is still handled by the Relation Service.

Specified by:
isInRelationService in interface RelationSupportMBean
Returns:
a Boolean equal to Boolean.TRUE if the object is still handled by the Relation Service and Boolean.FALSE otherwise.

setRelationServiceManagementFlag

public void setRelationServiceManagementFlag(Boolean flag)
                                      throws IllegalArgumentException
Description copied from interface: RelationSupportMBean

Specifies whether this relation is handled by the Relation Service.

BEWARE, this method has to be exposed as the Relation Service will access the relation through its management interface. It is RECOMMENDED NOT to use this method. Using it does not affect the registration of the relation object in the Relation Service, but will provide wrong information about it!

Specified by:
setRelationServiceManagementFlag in interface RelationSupportMBean
Parameters:
flag - whether the relation is handled by the Relation Service.
Throws:
IllegalArgumentException - if null parameter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RelationSupportMBean

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Interface RelationSupportMBean

All Superinterfaces:
Relation
All Known Implementing Classes:
RelationSupport
public interface RelationSupportMBean
extends Relation

A RelationSupport object is used internally by the Relation Service to represent simple relations (only roles, no properties or methods), with an unlimited number of roles, of any relation type. As internal representation, it is not exposed to the user.

RelationSupport class conforms to the design patterns of standard MBean. So the user can decide to instantiate a RelationSupport object himself as a MBean (as it follows the MBean design patterns), to register it in the MBean Server, and then to add it in the Relation Service.

The user can also, when creating his own MBean relation class, have it extending RelationSupport, to retrieve the implementations of required interfaces (see below).

It is also possible to have in a user relation MBean class a member being a RelationSupport object, and to implement the required interfaces by delegating all to this member.

RelationSupport implements the Relation interface (to be handled by the Relation Service).

Since:
1.5

Method Summary
Boolean | isInRelationService() Returns an internal flag specifying if the object is still handled by the Relation Service.
void | setRelationServiceManagementFlag(Boolean flag) Specifies whether this relation is handled by the Relation Service.
Methods inherited from interface javax.management.relation.Relation
getAllRoles, getReferencedMBeans, getRelationId, getRelationServiceName, getRelationTypeName, getRole, getRoleCardinality, getRoles, handleMBeanUnregistration, retrieveAllRoles, setRole, setRoles

Method Detail

isInRelationService

Boolean isInRelationService()
Returns an internal flag specifying if the object is still handled by the Relation Service.

Returns:
a Boolean equal to Boolean.TRUE if the object is still handled by the Relation Service and Boolean.FALSE otherwise.

setRelationServiceManagementFlag

void setRelationServiceManagementFlag(Boolean flag)
                                      throws IllegalArgumentException

Specifies whether this relation is handled by the Relation Service.

BEWARE, this method has to be exposed as the Relation Service will access the relation through its management interface. It is RECOMMENDED NOT to use this method. Using it does not affect the registration of the relation object in the Relation Service, but will provide wrong information about it!

Parameters:
flag - whether the relation is handled by the Relation Service.
Throws:
IllegalArgumentException - if null parameter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RelationType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Interface RelationType

All Superinterfaces:
Serializable
All Known Implementing Classes:
RelationTypeSupport
public interface RelationType
extends Serializable

The RelationType interface has to be implemented by any class expected to represent a relation type.

Since:
1.5

Method Summary
String | getRelationTypeName() Returns the relation type name.
RoleInfo | getRoleInfo(String roleInfoName) Returns the role info (RoleInfo object) for the given role info name (null if not found).
List<RoleInfo> | getRoleInfos() Returns the list of role definitions (ArrayList of RoleInfo objects).

Method Detail

getRelationTypeName

String getRelationTypeName()
Returns the relation type name.

Returns:
the relation type name.

getRoleInfos

List<RoleInfo> getRoleInfos()
Returns the list of role definitions (ArrayList of RoleInfo objects).

Returns:
an ArrayList of RoleInfo.

getRoleInfo

RoleInfo getRoleInfo(String roleInfoName)
                     throws IllegalArgumentException,
                            RoleInfoNotFoundException
Returns the role info (RoleInfo object) for the given role info name (null if not found).

Parameters:
roleInfoName - role info name
Returns:
RoleInfo object providing role definition does not exist
Throws:
IllegalArgumentException - if null parameter
RoleInfoNotFoundException - if no role info with that name in relation type.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RelationTypeNotFoundException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class RelationTypeNotFoundException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.relation.RelationException
                    extended by  javax.management.relation.RelationTypeNotFoundException
All Implemented Interfaces:
Serializable
public class RelationTypeNotFoundException
extends RelationException

This exception is raised when there is no relation type with given name in Relation Service.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
RelationTypeNotFoundException()
Default constructor, no message put in exception.
RelationTypeNotFoundException(String message)
Constructor with given message put in exception.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RelationTypeNotFoundException

public RelationTypeNotFoundException()
Default constructor, no message put in exception.

RelationTypeNotFoundException

public RelationTypeNotFoundException(String message)
Constructor with given message put in exception.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RelationTypeSupport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class RelationTypeSupport

java.lang.Object
    extended by  javax.management.relation.RelationTypeSupport
All Implemented Interfaces:
Serializable, RelationType
public class RelationTypeSupport
extends Object
implements RelationType

A RelationTypeSupport object implements the RelationType interface.

It represents a relation type, providing role information for each role expected to be supported in every relation of that type.

A relation type includes a relation type name and a list of role infos (represented by RoleInfo objects).

A relation type has to be declared in the Relation Service:

- either using the createRelationType() method, where a RelationTypeSupport object will be created and kept in the Relation Service

- either using the addRelationType() method where the user has to create an object implementing the RelationType interface, and this object will be used as representing a relation type in the Relation Service.

The serialVersionUID of this class is 4611072955724144607L.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
protected | RelationTypeSupport(String relationTypeName) Constructor to be used for subclasses.
 | RelationTypeSupport(String relationTypeName, RoleInfo[] roleInfoArray) Constructor where all role definitions are dynamically created and passed as parameter.
Method Summary
protected void | addRoleInfo(RoleInfo roleInfo) Add a role info.
String | getRelationTypeName() Returns the relation type name.
RoleInfo | getRoleInfo(String roleInfoName) Returns the role info (RoleInfo object) for the given role info name (null if not found).
List<RoleInfo> | getRoleInfos() Returns the list of role definitions (ArrayList of RoleInfo objects).
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RelationTypeSupport

public RelationTypeSupport(String relationTypeName,
                           RoleInfo[] roleInfoArray)
                    throws IllegalArgumentException,
                           InvalidRelationTypeException
Constructor where all role definitions are dynamically created and passed as parameter.

Parameters:
relationTypeName - Name of relation type
roleInfoArray - List of role definitions (RoleInfo objects)
Throws:
IllegalArgumentException - if null parameter
InvalidRelationTypeException - if:

- the same name has been used for two different roles

- no role info provided

- one null role info provided

RelationTypeSupport

protected RelationTypeSupport(String relationTypeName)
Constructor to be used for subclasses.

Parameters:
relationTypeName - Name of relation type.
Throws:
IllegalArgumentException - if null parameter.
Method Detail

getRelationTypeName

public String getRelationTypeName()
Returns the relation type name.

Specified by:
getRelationTypeName in interface RelationType
Returns:
the relation type name.

getRoleInfos

public List<RoleInfo> getRoleInfos()
Returns the list of role definitions (ArrayList of RoleInfo objects).

Specified by:
getRoleInfos in interface RelationType
Returns:
an ArrayList of RoleInfo.

getRoleInfo

public RoleInfo getRoleInfo(String roleInfoName)
                     throws IllegalArgumentException,
                            RoleInfoNotFoundException
Returns the role info (RoleInfo object) for the given role info name (null if not found).

Specified by:
getRoleInfo in interface RelationType
Parameters:
roleInfoName - role info name
Returns:
RoleInfo object providing role definition does not exist
Throws:
IllegalArgumentException - if null parameter
RoleInfoNotFoundException - if no role info with that name in relation type.

addRoleInfo

protected void addRoleInfo(RoleInfo roleInfo)
                    throws IllegalArgumentException,
                           InvalidRelationTypeException
Add a role info. This method of course should not be used after the creation of the relation type, because updating it would invalidate that the relations created associated to that type still conform to it. Can throw a RuntimeException if trying to update a relation type declared in the Relation Service.

Parameters:
roleInfo - role info to be added.
Throws:
IllegalArgumentException - if null parameter.
InvalidRelationTypeException - if there is already a role info in current relation type with the same name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Role

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class Role

java.lang.Object
    extended by  javax.management.relation.Role
All Implemented Interfaces:
Serializable
public class Role
extends Object
implements Serializable

Represents a role: includes a role name and referenced MBeans (via their ObjectNames). The role value is always represented as an ArrayList collection (of ObjectNames) to homogenize the access.

The serialVersionUID of this class is -279985518429862552L.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
Role(String roleName, List<ObjectName> roleValue)
Make a new Role object.
Method Summary
Object | clone() Clone the role object.
String | getRoleName() Retrieves role name.
List<ObjectName> | getRoleValue() Retrieves role value.
static String | roleValueToString(List<ObjectName> roleValue) Returns a string for the given role value.
void | setRoleName(String roleName) Sets role name.
void | setRoleValue(List<ObjectName> roleValue) Sets role value.
String | toString() Returns a string describing the role.
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Role

public Role(String roleName,
            List<ObjectName> roleValue)
     throws IllegalArgumentException

Make a new Role object. No check is made that the ObjectNames in the role value exist in an MBean server. That check will be made when the role is set in a relation.

Parameters:
roleName - role name
roleValue - role value (List of ObjectName objects)
Throws:
IllegalArgumentException - if null parameter
Method Detail

getRoleName

public String getRoleName()
Retrieves role name.

Returns:
the role name.
See Also:
setRoleName(java.lang.String)

getRoleValue

public List<ObjectName> getRoleValue()
Retrieves role value.

Returns:
ArrayList of ObjectName objects for referenced MBeans.
See Also:
setRoleValue(java.util.List)

setRoleName

public void setRoleName(String roleName)
                 throws IllegalArgumentException
Sets role name.

Parameters:
roleName - role name
Throws:
IllegalArgumentException - if null parameter
See Also:
getRoleName()

setRoleValue

public void setRoleValue(List<ObjectName> roleValue)
                  throws IllegalArgumentException
Sets role value.

Parameters:
roleValue - List of ObjectName objects for referenced MBeans.
Throws:
IllegalArgumentException - if null parameter
See Also:
getRoleValue()

toString

public String toString()
Returns a string describing the role.

Overrides:
toString in class Object
Returns:
the description of the role.

clone

public Object clone()
Clone the role object.

Overrides:
clone in class Object
Returns:
a Role that is an independent copy of the current Role object.
See Also:
Cloneable

roleValueToString

public static String roleValueToString(List<ObjectName> roleValue)
                                throws IllegalArgumentException
Returns a string for the given role value.

Parameters:
roleValue - List of ObjectName objects
Returns:
A String consisting of the ObjectNames separated by newlines (\n).
Throws:
IllegalArgumentException - if null parameter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RoleInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class RoleInfo

java.lang.Object
    extended by  javax.management.relation.RoleInfo
All Implemented Interfaces:
Serializable
public class RoleInfo
extends Object
implements Serializable

A RoleInfo object summarises a role in a relation type.

The serialVersionUID of this class is 2504952983494636987L.

Since:
1.5
See Also:
Serialized Form

Field Summary
static int ROLE_CARDINALITY_INFINITY
To specify an unlimited cardinality.
Constructor Summary
RoleInfo(RoleInfo roleInfo)
Copy constructor.
RoleInfo(String roleName, String mbeanClassName)
Constructor.
RoleInfo(String roleName, String mbeanClassName, boolean read, boolean write)
Constructor.
RoleInfo(String roleName, String mbeanClassName, boolean read, boolean write, int min, int max, String descr)
Constructor.
Method Summary
boolean | checkMaxDegree(int value) Returns true if the value parameter is lower than or equal to the expected maximum degree, false otherwise.
boolean | checkMinDegree(int value) Returns true if the value parameter is greater than or equal to the expected minimum degree, false otherwise.
String | getDescription() Returns description text for the role.
int | getMaxDegree() Returns maximum degree for corresponding role reference.
int | getMinDegree() Returns minimum degree for corresponding role reference.
String | getName() Returns the name of the role.
String | getRefMBeanClassName() Returns name of type of MBean expected to be referenced in corresponding role.
boolean | isReadable() Returns read access mode for the role (true if it is readable).
boolean | isWritable() Returns write access mode for the role (true if it is writable).
String | toString() Returns a string describing the role info.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ROLE_CARDINALITY_INFINITY

public static final int ROLE_CARDINALITY_INFINITY
To specify an unlimited cardinality.

See Also:
Constant Field Values
Constructor Detail

RoleInfo

public RoleInfo(String roleName,
                String mbeanClassName,
                boolean read,
                boolean write,
                int min,
                int max,
                String descr)
         throws IllegalArgumentException,
                InvalidRoleInfoException,
                ClassNotFoundException,
                NotCompliantMBeanException
Constructor.

Parameters:
roleName - name of the role.
mbeanClassName - name of the class of MBean(s) expected to be referenced in corresponding role. If an MBean M is in this role, then the MBean server must return true for isInstanceOf(M, mbeanClassName).
read - flag to indicate if the corresponding role can be read
write - flag to indicate if the corresponding role can be set
min - minimum degree for role, i.e. minimum number of MBeans to provide in corresponding role Must be less than or equal to max. (ROLE_CARDINALITY_INFINITY for unlimited)
max - maximum degree for role, i.e. maximum number of MBeans to provide in corresponding role Must be greater than or equal to min (ROLE_CARDINALITY_INFINITY for unlimited)
descr - description of the role (can be null)
Throws:
IllegalArgumentException - if null parameter
InvalidRoleInfoException - if the minimum degree is greater than the maximum degree.
ClassNotFoundException - As of JMX 1.2, this exception can no longer be thrown. It is retained in the declaration of this class for compatibility with existing code.
NotCompliantMBeanException - if the class mbeanClassName is not a MBean class.

RoleInfo

public RoleInfo(String roleName,
                String mbeanClassName,
                boolean read,
                boolean write)
         throws IllegalArgumentException,
                ClassNotFoundException,
                NotCompliantMBeanException
Constructor.

Parameters:
roleName - name of the role
mbeanClassName - name of the class of MBean(s) expected to be referenced in corresponding role. If an MBean M is in this role, then the MBean server must return true for isInstanceOf(M, mbeanClassName).
read - flag to indicate if the corresponding role can be read
write - flag to indicate if the corresponding role can be set

Minimum and maximum degrees defaulted to 1.

Description of role defaulted to null.

Throws:
IllegalArgumentException - if null parameter
ClassNotFoundException - As of JMX 1.2, this exception can no longer be thrown. It is retained in the declaration of this class for compatibility with existing code.
NotCompliantMBeanException - As of JMX 1.2, this exception can no longer be thrown. It is retained in the declaration of this class for compatibility with existing code.

RoleInfo

public RoleInfo(String roleName,
                String mbeanClassName)
         throws IllegalArgumentException,
                ClassNotFoundException,
                NotCompliantMBeanException
Constructor.

Parameters:
roleName - name of the role
mbeanClassName - name of the class of MBean(s) expected to be referenced in corresponding role. If an MBean M is in this role, then the MBean server must return true for isInstanceOf(M, mbeanClassName).

IsReadable and IsWritable defaulted to true.

Minimum and maximum degrees defaulted to 1.

Description of role defaulted to null.

Throws:
IllegalArgumentException - if null parameter
ClassNotFoundException - As of JMX 1.2, this exception can no longer be thrown. It is retained in the declaration of this class for compatibility with existing code.
NotCompliantMBeanException - As of JMX 1.2, this exception can no longer be thrown. It is retained in the declaration of this class for compatibility with existing code.

RoleInfo

public RoleInfo(RoleInfo roleInfo)
         throws IllegalArgumentException
Copy constructor.

Parameters:
roleInfo - the RoleInfo instance to be copied.
Throws:
IllegalArgumentException - if null parameter
Method Detail

getName

public String getName()
Returns the name of the role.

Returns:
the name of the role.

isReadable

public boolean isReadable()
Returns read access mode for the role (true if it is readable).

Returns:
true if the role is readable.

isWritable

public boolean isWritable()
Returns write access mode for the role (true if it is writable).

Returns:
true if the role is writable.

getDescription

public String getDescription()
Returns description text for the role.

Returns:
the description of the role.

getMinDegree

public int getMinDegree()
Returns minimum degree for corresponding role reference.

Returns:
the minimum degree.

getMaxDegree

public int getMaxDegree()
Returns maximum degree for corresponding role reference.

Returns:
the maximum degree.

getRefMBeanClassName

public String getRefMBeanClassName()

Returns name of type of MBean expected to be referenced in corresponding role.

Returns:
the name of the referenced type.

checkMinDegree

public boolean checkMinDegree(int value)
Returns true if the value parameter is greater than or equal to the expected minimum degree, false otherwise.

Parameters:
value - the value to be checked
Returns:
true if greater than or equal to minimum degree, false otherwise.

checkMaxDegree

public boolean checkMaxDegree(int value)
Returns true if the value parameter is lower than or equal to the expected maximum degree, false otherwise.

Parameters:
value - the value to be checked
Returns:
true if lower than or equal to maximum degree, false otherwise.

toString

public String toString()
Returns a string describing the role info.

Overrides:
toString in class Object
Returns:
a description of the role info.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RoleInfoNotFoundException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class RoleInfoNotFoundException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.relation.RelationException
                    extended by  javax.management.relation.RoleInfoNotFoundException
All Implemented Interfaces:
Serializable
public class RoleInfoNotFoundException
extends RelationException

This exception is raised when there is no role info with given name in a given relation type.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
RoleInfoNotFoundException()
Default constructor, no message put in exception.
RoleInfoNotFoundException(String message)
Constructor with given message put in exception.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RoleInfoNotFoundException

public RoleInfoNotFoundException()
Default constructor, no message put in exception.

RoleInfoNotFoundException

public RoleInfoNotFoundException(String message)
Constructor with given message put in exception.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RoleList

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class RoleList

java.lang.Object
    extended by  java.util.AbstractCollection<E>
        extended by  java.util.AbstractList<E>
            extended by  java.util.ArrayList<Object>
                extended by  javax.management.relation.RoleList
All Implemented Interfaces:
Serializable, Cloneable, Iterable<Object>, Collection<Object>, List<Object>, RandomAccess
public class RoleList
extends ArrayList<Object>

A RoleList represents a list of roles (Role objects). It is used as parameter when creating a relation, and when trying to set several roles in a relation (via 'setRoles()' method). It is returned as part of a RoleResult, to provide roles successfully retrieved.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class java.util.AbstractList
modCount
Constructor Summary
RoleList()
Constructs an empty RoleList.
RoleList(int initialCapacity)
Constructs an empty RoleList with the initial capacity specified.
RoleList(List<Role> list)
Constructs a RoleList containing the elements of the List specified, in the order in which they are returned by the List's iterator.
Method Summary
void | add(int index, Object element) Inserts the specified element at the specified position in this list.
void | add(int index, Role role) Inserts the role specified as an element at the position specified.
boolean | add(Object o) Appends the specified element to the end of this list.
void | add(Role role) Adds the Role specified as the last element of the list.
boolean | addAll(Collection<?> c) Appends all of the elements in the specified collection to the end of this list, in the order that they are returned by the specified collection's Iterator.
boolean | addAll(int index, Collection<?> c) Inserts all of the elements in the specified collection into this list, starting at the specified position.
boolean | addAll(int index, RoleList roleList) Inserts all of the elements in the RoleList specified into this list, starting at the specified position, in the order in which they are returned by the Iterator of the RoleList specified.
boolean | addAll(RoleList roleList) Appends all the elements in the RoleList specified to the end of the list, in the order in which they are returned by the Iterator of the RoleList specified.
List<Role> | asList() Return a view of this list as a List<Role>.
Object | set(int index, Object element) Replaces the element at the specified position in this list with the specified element.
void | set(int index, Role role) Sets the element at the position specified to be the role specified.
Methods inherited from class java.util.ArrayList
clear, clone, contains, ensureCapacity, get, indexOf, isEmpty, lastIndexOf, remove, remove, removeRange, size, toArray, toArray, trimToSize
Methods inherited from class java.util.AbstractList
equals, hashCode, iterator, listIterator, listIterator, subList
Methods inherited from class java.util.AbstractCollection
containsAll, removeAll, retainAll, toString
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.util.List
containsAll, equals, hashCode, iterator, listIterator, listIterator, removeAll, retainAll, subList

Constructor Detail

RoleList

public RoleList()
Constructs an empty RoleList.

RoleList

public RoleList(int initialCapacity)
Constructs an empty RoleList with the initial capacity specified.

Parameters:
initialCapacity - initial capacity

RoleList

public RoleList(List<Role> list)
         throws IllegalArgumentException
Constructs a RoleList containing the elements of the List specified, in the order in which they are returned by the List's iterator. The RoleList instance has an initial capacity of 110% of the size of the List specified.

Parameters:
list - the List that defines the initial contents of the new RoleList.
Throws:
IllegalArgumentException - if the list parameter is null or if the list parameter contains any non-Role objects.
See Also:
ArrayList.ArrayList(java.util.Collection)
Method Detail

asList

public List<Role> asList()
Return a view of this list as a List<Role>. Changes to the returned value are reflected by changes to the original RoleList and vice versa.

Returns:
a List<Role> whose contents reflect the contents of this RoleList.

If this method has ever been called on a given RoleList instance, a subsequent attempt to add an object to that instance which is not a Role will fail with an IllegalArgumentException. For compatibility reasons, a RoleList on which this method has never been called does allow objects other than Roles to be added.

Throws:
IllegalArgumentException - if this RoleList contains an element that is not a Role.
Since:
1.6

add

public void add(Role role)
         throws IllegalArgumentException
Adds the Role specified as the last element of the list.

Parameters:
role - the role to be added.
Throws:
IllegalArgumentException - if the role is null.

add

public void add(int index,
                Role role)
         throws IllegalArgumentException,
                IndexOutOfBoundsException
Inserts the role specified as an element at the position specified. Elements with an index greater than or equal to the current position are shifted up.

Parameters:
index - The position in the list where the new Role object is to be inserted.
role - The Role object to be inserted.
Throws:
IllegalArgumentException - if the role is null.
IndexOutOfBoundsException - if accessing with an index outside of the list.

set

public void set(int index,
                Role role)
         throws IllegalArgumentException,
                IndexOutOfBoundsException
Sets the element at the position specified to be the role specified. The previous element at that position is discarded.

Parameters:
index - The position specified.
role - The value to which the role element should be set.
Throws:
IllegalArgumentException - if the role is null.
IndexOutOfBoundsException - if accessing with an index outside of the list.

addAll

public boolean addAll(RoleList roleList)
               throws IndexOutOfBoundsException
Appends all the elements in the RoleList specified to the end of the list, in the order in which they are returned by the Iterator of the RoleList specified.

Parameters:
roleList - Elements to be inserted into the list (can be null)
Returns:
true if this list changed as a result of the call.
Throws:
IndexOutOfBoundsException - if accessing with an index outside of the list.
See Also:
ArrayList.addAll(Collection)

addAll

public boolean addAll(int index,
                      RoleList roleList)
               throws IllegalArgumentException,
                      IndexOutOfBoundsException
Inserts all of the elements in the RoleList specified into this list, starting at the specified position, in the order in which they are returned by the Iterator of the RoleList specified.

Parameters:
index - Position at which to insert the first element from the RoleList specified.
roleList - Elements to be inserted into the list.
Returns:
true if this list changed as a result of the call.
Throws:
IllegalArgumentException - if the role is null.
IndexOutOfBoundsException - if accessing with an index outside of the list.
See Also:
ArrayList.addAll(int, Collection)

add

public boolean add(Object o)
Description copied from class: ArrayList
Appends the specified element to the end of this list.

Specified by:
add in interface Collection<Object>
Specified by:
add in interface List<Object>
Overrides:
add in class ArrayList<Object>
Parameters:
o - element to be appended to this list
Returns:
true (as specified by Collection.add(E))

add

public void add(int index,
                Object element)
Description copied from class: ArrayList
Inserts the specified element at the specified position in this list. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).

Specified by:
add in interface List<Object>
Overrides:
add in class ArrayList<Object>
Parameters:
index - index at which the specified element is to be inserted
element - element to be inserted

addAll

public boolean addAll(Collection<?> c)
Description copied from class: ArrayList
Appends all of the elements in the specified collection to the end of this list, in the order that they are returned by the specified collection's Iterator. The behavior of this operation is undefined if the specified collection is modified while the operation is in progress. (This implies that the behavior of this call is undefined if the specified collection is this list, and this list is nonempty.)

Specified by:
addAll in interface Collection<Object>
Specified by:
addAll in interface List<Object>
Overrides:
addAll in class ArrayList<Object>
Parameters:
c - collection containing elements to be added to this list
Returns:
true if this list changed as a result of the call
See Also:
AbstractCollection.add(Object)

addAll

public boolean addAll(int index,
                      Collection<?> c)
Description copied from class: ArrayList
Inserts all of the elements in the specified collection into this list, starting at the specified position. Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices). The new elements will appear in the list in the order that they are returned by the specified collection's iterator.

Specified by:
addAll in interface List<Object>
Overrides:
addAll in class ArrayList<Object>
Parameters:
index - index at which to insert the first element from the specified collection
c - collection containing elements to be added to this list
Returns:
true if this list changed as a result of the call

set

public Object set(int index,
                  Object element)
Description copied from class: ArrayList
Replaces the element at the specified position in this list with the specified element.

Specified by:
set in interface List<Object>
Overrides:
set in class ArrayList<Object>
Parameters:
index - index of the element to replace
element - element to be stored at the specified position
Returns:
the element previously at the specified position
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RoleNotFoundException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class RoleNotFoundException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.relation.RelationException
                    extended by  javax.management.relation.RoleNotFoundException
All Implemented Interfaces:
Serializable
public class RoleNotFoundException
extends RelationException

This exception is raised when a role in a relation does not exist, or is not readable, or is not settable.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
RoleNotFoundException()
Default constructor, no message put in exception.
RoleNotFoundException(String message)
Constructor with given message put in exception.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RoleNotFoundException

public RoleNotFoundException()
Default constructor, no message put in exception.

RoleNotFoundException

public RoleNotFoundException(String message)
Constructor with given message put in exception.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RoleResult

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class RoleResult

java.lang.Object
    extended by  javax.management.relation.RoleResult
All Implemented Interfaces:
Serializable
public class RoleResult
extends Object
implements Serializable

Represents the result of a multiple access to several roles of a relation (either for reading or writing).

The serialVersionUID of this class is -6304063118040985512L.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
RoleResult(RoleList list, RoleUnresolvedList unresolvedList)
Constructor.
Method Summary
RoleList | getRoles() Retrieves list of roles successfully accessed.
RoleUnresolvedList | getRolesUnresolved() Retrieves list of roles unsuccessfully accessed.
void | setRoles(RoleList list) Sets list of roles successfully accessed.
void | setRolesUnresolved(RoleUnresolvedList unresolvedList) Sets list of roles unsuccessfully accessed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RoleResult

public RoleResult(RoleList list,
                  RoleUnresolvedList unresolvedList)
Constructor.

Parameters:
list - list of roles successfully accessed.
unresolvedList - list of roles not accessed (with problem descriptions).
Method Detail

getRoles

public RoleList getRoles()
Retrieves list of roles successfully accessed.

Returns:
a RoleList
See Also:
setRoles(javax.management.relation.RoleList)

getRolesUnresolved

public RoleUnresolvedList getRolesUnresolved()
Retrieves list of roles unsuccessfully accessed.

Returns:
a RoleUnresolvedList.
See Also:
setRolesUnresolved(javax.management.relation.RoleUnresolvedList)

setRoles

public void setRoles(RoleList list)
Sets list of roles successfully accessed.

Parameters:
list - list of roles successfully accessed
See Also:
getRoles()

setRolesUnresolved

public void setRolesUnresolved(RoleUnresolvedList unresolvedList)
Sets list of roles unsuccessfully accessed.

Parameters:
unresolvedList - list of roles unsuccessfully accessed
See Also:
getRolesUnresolved()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RoleStatus

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class RoleStatus

java.lang.Object
    extended by  javax.management.relation.RoleStatus

public class RoleStatus
extends Object

This class describes the various problems which can be encountered when accessing a role.

Since:
1.5

Field Summary
static int | LESS_THAN_MIN_ROLE_DEGREE Problem type when trying to set a role value with less ObjectNames than the minimum expected cardinality.
static int | MORE_THAN_MAX_ROLE_DEGREE Problem type when trying to set a role value with more ObjectNames than the maximum expected cardinality.
static int | NO_ROLE_WITH_NAME Problem type when trying to access an unknown role.
static int | REF_MBEAN_NOT_REGISTERED Problem type when trying to set a role value including the ObjectName of a MBean not registered in the MBean Server.
static int | REF_MBEAN_OF_INCORRECT_CLASS Problem type when trying to set a role value including the ObjectName of a MBean not of the class expected for that role.
static int | ROLE_NOT_READABLE Problem type when trying to read a non-readable attribute.
static int | ROLE_NOT_WRITABLE Problem type when trying to update a non-writable attribute.
Constructor Summary
RoleStatus()
Method Summary
static boolean isRoleStatus(int status)
Returns true if given value corresponds to a known role status, false otherwise.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_ROLE_WITH_NAME

public static final int NO_ROLE_WITH_NAME
Problem type when trying to access an unknown role.

See Also:
Constant Field Values

ROLE_NOT_READABLE

public static final int ROLE_NOT_READABLE
Problem type when trying to read a non-readable attribute.

See Also:
Constant Field Values

ROLE_NOT_WRITABLE

public static final int ROLE_NOT_WRITABLE
Problem type when trying to update a non-writable attribute.

See Also:
Constant Field Values

LESS_THAN_MIN_ROLE_DEGREE

public static final int LESS_THAN_MIN_ROLE_DEGREE
Problem type when trying to set a role value with less ObjectNames than the minimum expected cardinality.

See Also:
Constant Field Values

MORE_THAN_MAX_ROLE_DEGREE

public static final int MORE_THAN_MAX_ROLE_DEGREE
Problem type when trying to set a role value with more ObjectNames than the maximum expected cardinality.

See Also:
Constant Field Values

REF_MBEAN_OF_INCORRECT_CLASS

public static final int REF_MBEAN_OF_INCORRECT_CLASS
Problem type when trying to set a role value including the ObjectName of a MBean not of the class expected for that role.

See Also:
Constant Field Values

REF_MBEAN_NOT_REGISTERED

public static final int REF_MBEAN_NOT_REGISTERED
Problem type when trying to set a role value including the ObjectName of a MBean not registered in the MBean Server.

See Also:
Constant Field Values
Constructor Detail

RoleStatus

public RoleStatus()
Method Detail

isRoleStatus

public static boolean isRoleStatus(int status)
Returns true if given value corresponds to a known role status, false otherwise.

Parameters:
status - a status code.
Returns:
true if this value is a known role status.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RoleUnresolved

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class RoleUnresolved

java.lang.Object
    extended by  javax.management.relation.RoleUnresolved
All Implemented Interfaces:
Serializable
public class RoleUnresolved
extends Object
implements Serializable

Represents an unresolved role: a role not retrieved from a relation due to a problem. It provides the role name, value (if problem when trying to set the role) and an integer defining the problem (constants defined in RoleStatus).

The serialVersionUID of this class is -48350262537070138L.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
RoleUnresolved(String name, List<ObjectName> value, int pbType)
Constructor.
Method Summary
Object | clone() Clone this object.
int | getProblemType() Retrieves problem type.
String | getRoleName() Retrieves role name.
List<ObjectName> | getRoleValue() Retrieves role value.
void | setProblemType(int pbType) Sets problem type.
void | setRoleName(String name) Sets role name.
void | setRoleValue(List<ObjectName> value) Sets role value.
String | toString() Return a string describing this object.
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RoleUnresolved

public RoleUnresolved(String name,
                      List<ObjectName> value,
                      int pbType)
               throws IllegalArgumentException
Constructor.

Parameters:
name - name of the role
value - value of the role (if problem when setting the role)
pbType - type of problem (according to known problem types, listed as static final members).
Throws:
IllegalArgumentException - if null parameter or incorrect problem type
Method Detail

getRoleName

public String getRoleName()
Retrieves role name.

Returns:
the role name.
See Also:
setRoleName(java.lang.String)

getRoleValue

public List<ObjectName> getRoleValue()
Retrieves role value.

Returns:
an ArrayList of ObjectName objects, the one provided to be set in given role. Null if the unresolved role is returned for a read access.
See Also:
setRoleValue(java.util.List)

getProblemType

public int getProblemType()
Retrieves problem type.

Returns:
an integer corresponding to a problem, those being described as static final members of current class.
See Also:
setProblemType(int)

setRoleName

public void setRoleName(String name)
                 throws IllegalArgumentException
Sets role name.

Parameters:
name - the new role name.
Throws:
IllegalArgumentException - if null parameter
See Also:
getRoleName()

setRoleValue

public void setRoleValue(List<ObjectName> value)
Sets role value.

Parameters:
value - List of ObjectName objects for referenced MBeans not set in role.
See Also:
getRoleValue()

setProblemType

public void setProblemType(int pbType)
                    throws IllegalArgumentException
Sets problem type.

Parameters:
pbType - integer corresponding to a problem. Must be one of those described as static final members of current class.
Throws:
IllegalArgumentException - if incorrect problem type
See Also:
getProblemType()

clone

public Object clone()
Clone this object.

Overrides:
clone in class Object
Returns:
an independent clone.
See Also:
Cloneable

toString

public String toString()
Return a string describing this object.

Overrides:
toString in class Object
Returns:
a description of this RoleUnresolved object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RoleUnresolvedList

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.management.relation
Class RoleUnresolvedList

java.lang.Object
    extended by  java.util.AbstractCollection<E>
        extended by  java.util.AbstractList<E>
            extended by  java.util.ArrayList<Object>
                extended by  javax.management.relation.RoleUnresolvedList
All Implemented Interfaces:
Serializable, Cloneable, Iterable<Object>, Collection<Object>, List<Object>, RandomAccess
public class RoleUnresolvedList
extends ArrayList<Object>

A RoleUnresolvedList represents a list of RoleUnresolved objects, representing roles not retrieved from a relation due to a problem encountered when trying to access (read or write) the roles.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class java.util.AbstractList
modCount
Constructor Summary
RoleUnresolvedList()
Constructs an empty RoleUnresolvedList.
RoleUnresolvedList(int initialCapacity)
Constructs an empty RoleUnresolvedList with the initial capacity specified.
RoleUnresolvedList(List<RoleUnresolved> list)
Constructs a RoleUnresolvedList containing the elements of the List specified, in the order in which they are returned by the List's iterator.
Method Summary
void | add(int index, Object element) Inserts the specified element at the specified position in this list.
void | add(int index, RoleUnresolved role) Inserts the unresolved role specified as an element at the position specified.
boolean | add(Object o) Appends the specified element to the end of this list.
void | add(RoleUnresolved role) Adds the RoleUnresolved specified as the last element of the list.
boolean | addAll(Collection<?> c) Appends all of the elements in the specified collection to the end of this list, in the order that they are returned by the specified collection's Iterator.
boolean | addAll(int index, Collection<?> c) Inserts all of the elements in the specified collection into this list, starting at the specified position.
boolean | addAll(int index, RoleUnresolvedList roleList) Inserts all of the elements in the RoleUnresolvedList specified into this list, starting at the specified position, in the order in which they are returned by the Iterator of the RoleUnresolvedList specified.
boolean | addAll(RoleUnresolvedList roleList) Appends all the elements in the RoleUnresolvedList specified to the end of the list, in the order in which they are returned by the Iterator of the RoleUnresolvedList specified.
List<RoleUnresolved> | asList() Return a view of this list as a List<RoleUnresolved>.
Object | set(int index, Object element) Replaces the element at the specified position in this list with the specified element.
void | set(int index, RoleUnresolved role) Sets the element at the position specified to be the unresolved role specified.
Methods inherited from class java.util.ArrayList
clear, clone, contains, ensureCapacity, get, indexOf, isEmpty, lastIndexOf, remove, remove, removeRange, size, toArray, toArray, trimToSize
Methods inherited from class java.util.AbstractList
equals, hashCode, iterator, listIterator, listIterator, subList
Methods inherited from class java.util.AbstractCollection
containsAll, removeAll, retainAll, toString
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.util.List
containsAll, equals, hashCode, iterator, listIterator, listIterator, removeAll, retainAll, subList

Constructor Detail

RoleUnresolvedList

public RoleUnresolvedList()
Constructs an empty RoleUnresolvedList.

RoleUnresolvedList

public RoleUnresolvedList(int initialCapacity)
Constructs an empty RoleUnresolvedList with the initial capacity specified.

Parameters:
initialCapacity - initial capacity

RoleUnresolvedList

public RoleUnresolvedList(List<RoleUnresolved> list)
                   throws IllegalArgumentException
Constructs a RoleUnresolvedList containing the elements of the List specified, in the order in which they are returned by the List's iterator. The RoleUnresolvedList instance has an initial capacity of 110% of the size of the List specified.

Parameters:
list - the List that defines the initial contents of the new RoleUnresolvedList.
Throws:
IllegalArgumentException - if the list parameter is null or if the list parameter contains any non-RoleUnresolved objects.
See Also:
ArrayList.ArrayList(java.util.Collection)
Method Detail

asList

public List<RoleUnresolved> asList()
Return a view of this list as a List<RoleUnresolved>. Changes to the returned value are reflected by changes to the original RoleUnresolvedList and vice versa.

Returns:
a List<RoleUnresolved> whose contents reflect the contents of this RoleUnresolvedList.

If this method has ever been called on a given RoleUnresolvedList instance, a subsequent attempt to add an object to that instance which is not a RoleUnresolved will fail with an IllegalArgumentException. For compatibility reasons, a RoleUnresolvedList on which this method has never been called does allow objects other than RoleUnresolveds to be added.

Throws:
IllegalArgumentException - if this RoleUnresolvedList contains an element that is not a RoleUnresolved.
Since:
1.6

add

public void add(RoleUnresolved role)
         throws IllegalArgumentException
Adds the RoleUnresolved specified as the last element of the list.

Parameters:
role - - the unresolved role to be added.
Throws:
IllegalArgumentException - if the unresolved role is null.

add

public void add(int index,
                RoleUnresolved role)
         throws IllegalArgumentException,
                IndexOutOfBoundsException
Inserts the unresolved role specified as an element at the position specified. Elements with an index greater than or equal to the current position are shifted up.

Parameters:
index - - The position in the list where the new RoleUnresolved object is to be inserted.
role - - The RoleUnresolved object to be inserted.
Throws:
IllegalArgumentException - if the unresolved role is null.
IndexOutOfBoundsException - if index is out of range (index < 0 || index > size()).

set

public void set(int index,
                RoleUnresolved role)
         throws IllegalArgumentException,
                IndexOutOfBoundsException
Sets the element at the position specified to be the unresolved role specified. The previous element at that position is discarded.

Parameters:
index - - The position specified.
role - - The value to which the unresolved role element should be set.
Throws:
IllegalArgumentException - if the unresolved role is null.
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= size()).

addAll

public boolean addAll(RoleUnresolvedList roleList)
               throws IndexOutOfBoundsException
Appends all the elements in the RoleUnresolvedList specified to the end of the list, in the order in which they are returned by the Iterator of the RoleUnresolvedList specified.

Parameters:
roleList - - Elements to be inserted into the list (can be null).
Returns:
true if this list changed as a result of the call.
Throws:
IndexOutOfBoundsException - if accessing with an index outside of the list.

addAll

public boolean addAll(int index,
                      RoleUnresolvedList roleList)
               throws IllegalArgumentException,
                      IndexOutOfBoundsException
Inserts all of the elements in the RoleUnresolvedList specified into this list, starting at the specified position, in the order in which they are returned by the Iterator of the RoleUnresolvedList specified.

Parameters:
index - - Position at which to insert the first element from the RoleUnresolvedList specified.
roleList - - Elements to be inserted into the list.
Returns:
true if this list changed as a result of the call.
Throws:
IllegalArgumentException - if the role is null.
IndexOutOfBoundsException - if index is out of range (index < 0 || index > size()).

add

public boolean add(Object o)
Description copied from class: ArrayList
Appends the specified element to the end of this list.

Specified by:
add in interface Collection<Object>
Specified by:
add in interface List<Object>
Overrides:
add in class ArrayList<Object>
Parameters:
o - element to be appended to this list
Returns:
true (as specified by Collection.add(E))

add

public void add(int index,
                Object element)
Description copied from class: ArrayList
Inserts the specified element at the specified position in this list. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).

Specified by:
add in interface List<Object>
Overrides:
add in class ArrayList<Object>
Parameters:
index - index at which the specified element is to be inserted
element - element to be inserted

addAll

public boolean addAll(Collection<?> c)
Description copied from class: ArrayList
Appends all of the elements in the specified collection to the end of this list, in the order that they are returned by the specified collection's Iterator. The behavior of this operation is undefined if the specified collection is modified while the operation is in progress. (This implies that the behavior of this call is undefined if the specified collection is this list, and this list is nonempty.)

Specified by:
addAll in interface Collection<Object>
Specified by:
addAll in interface List<Object>
Overrides:
addAll in class ArrayList<Object>
Parameters:
c - collection containing elements to be added to this list
Returns:
true if this list changed as a result of the call
See Also:
AbstractCollection.add(Object)

addAll

public boolean addAll(int index,
                      Collection<?> c)
Description copied from class: ArrayList
Inserts all of the elements in the specified collection into this list, starting at the specified position. Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices). The new elements will appear in the list in the order that they are returned by the specified collection's iterator.

Specified by:
addAll in interface List<Object>
Overrides:
addAll in class ArrayList<Object>
Parameters:
index - index at which to insert the first element from the specified collection
c - collection containing elements to be added to this list
Returns:
true if this list changed as a result of the call

set

public Object set(int index,
                  Object element)
Description copied from class: ArrayList
Replaces the element at the specified position in this list with the specified element.

Specified by:
set in interface List<Object>
Overrides:
set in class ArrayList<Object>
Parameters:
index - index of the element to replace
element - element to be stored at the specified position
Returns:
the element previously at the specified position
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


remote

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.management.remote

Interfaces for remote access to JMX MBean servers.

See:
Description

Interface Summary
JMXAddressable | Implemented by objects that can have a JMXServiceURL address.
JMXAuthenticator | Interface to define how remote credentials are converted into a JAAS Subject.
JMXConnector | The client end of a JMX API connector.
JMXConnectorProvider | A provider for creating JMX API connector clients using a given protocol.
JMXConnectorServerMBean | MBean interface for connector servers.
JMXConnectorServerProvider | A provider for creating JMX API connector servers using a given protocol.
MBeanServerForwarder | An object of this class implements the MBeanServer interface and wraps another object that also implements that interface.

Class Summary
JMXConnectionNotification | Notification emitted when a client connection is opened or closed or when notifications are lost.
JMXConnectorFactory | Factory to create JMX API connector clients.
JMXConnectorServer | Superclass of every connector server.
JMXConnectorServerFactory | Factory to create JMX API connector servers.
JMXPrincipal | The identity of a remote client of the JMX Remote API.
JMXServiceURL | The address of a JMX API connector server.
NotificationResult | Result of a query for buffered notifications.
SubjectDelegationPermission | Permission required by an authentication identity to perform operations on behalf of an authorization identity.
TargetedNotification | A (Notification, Listener ID) pair.

Exception Summary
JMXProviderException | Exception thrown by JMXConnectorFactory and JMXConnectorServerFactory when a provider exists for the required protocol but cannot be used for some reason.
JMXServerErrorException | Exception thrown as the result of a remote MBeanServer method invocation when an Error is thrown while processing the invocation in the remote MBean server.

Package javax.management.remote Description

Interfaces for remote access to JMX MBean servers. This package defines the essential interfaces for making a JMX MBean server manageable remotely. The specification of this functionality is completed by Part III of the JMX Specification, version 1.4 PDF document.

The JMX specification defines the notion of connectors. A connector is attached to a JMX API MBean server and makes it accessible to remote Java clients. The client end of a connector exports essentially the same interface as the MBean server, specifically the MBeanServerConnection interface.

A connector makes an MBean server remotely accessible through a given protocol. The JMX Remote API allows the use of different type of connectors:

  • The JMX Remote API defines a standard connector, the RMI Connector, which provides remote access to an MBeanServer through RMI.
  • The JMX Remote API also defines an optional connector called JMXMP Connector implementing the JMX Message Protocol (JMXMP). As it is optional, it is not part of this bundle (see note below).
  • User-defined connector protocols are also possible using the JMXConnectorFactory and, optionally, the Generic Connector (not part of this bundle, see note below).

Note: the optional packages implementing the optional part of the JMX Remote API are not included in the Java SE Platform but are available from the JMX Remote API Reference Implementation.

Connector addresses

Typically, a connector server has an address, represented by the class JMXServiceURL. An address for the RMI Connector can look like this:

      service:jmx:rmi:///jndi/rmi://myhost:1099/myname

In this JMXServiceURL, the first rmi: specifies the RMI connector, while the second rmi: specifies the RMI registry into which the RMI connector server has stored its stub.

The example above shows only one form of address. An address for the RMI Connector can take several forms, as detailed in the documentation for the package javax.management.remote.rmi.

Creating a connector server

A connector server is created by constructing an instance of a subclass of JMXConnectorServer. Usually, this instance is created using the method JMXConnectorServerFactory.newJMXConnectorServer.

Typically, a connector server is associated with an MBean server either by registering it in that MBean server, or by supplying the MBean server as a parameter when creating the connector server.

Creating a connector client

A connector client is usually created by supplying the JMXServiceURL of the connector server to connect to to the JMXConnectorFactory.connect method.

For more specialized uses, a connector client can be created by directly instantiating a class that implements the JMXConnector interface, for example the class RMIConnector.

Additional client or server parameters

When creating a connector client or server, it is possible to supply an object of type Map that defines additional parameters. Each entry in this Map has a key that is a string and an associated value whose type is appropriate for that key. The standard keys defined by the JMX Remote API all begin with the string "jmx.remote.". The document JMX Remote API lists these standard keys.

Connection identifiers

Every connection opened by a connector server has a string identifier, called its connection id. This identifier appears in the JMXConnectionNotification events emitted by the connector server, in the list returned by getConnectionIds(), and in the value returned by the client's getConnectionId() method.

As an example, a connection ID can look something like this:

rmi://192.18.1.9 username 1

The formal grammar for connection ids that follow this convention is as follows (using the grammar notation from The Java Language Specification, Second Edition):

ConnectionId:
    Protocol : ClientAddressopt Space ClientIdopt Space ArbitraryText

ClientAddress:
    // HostAddress ClientPortopt

ClientPort
    : HostPort

The Protocol is a protocol that would be recognized by JMXConnectorFactory.

The ClientAddress is the address and port of the connecting client, if these can be determined, otherwise nothing. The HostAddress is the Internet address of the host that the client is connecting from, in numeric or DNS form. Numeric IPv6 addresses are enclosed in square brackets []. The HostPort is the decimal port number that the client is connecting from.

The ClientId is the identity of the client entity, typically a string returned by JMXPrincipal.getName(). This string must not contain spaces.

The ArbitraryText is any additional text that the connector server adds when creating the client id. At a minimum, it must be enough to distinguish this connection ID from the ID of any other connection currently opened by this connector server.

Since:
1.5
See Also:
Java SE 6 Platform documentation on JMX technology, in particular the JMX Specification, version 1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.management.remote Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.management.remote

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.util.EventObject (implements java.io.Serializable)
      • javax.management.Notification
        • javax.management.remote.JMXConnectionNotification
    • javax.management.remote.JMXConnectorFactory
    • javax.management.remote.JMXConnectorServerFactory
    • javax.management.remote.JMXPrincipal (implements java.security.Principal, java.io.Serializable)
    • javax.management.remote.JMXServiceURL (implements java.io.Serializable)
    • javax.management.NotificationBroadcasterSupport (implements javax.management.NotificationEmitter)
      • javax.management.remote.JMXConnectorServer (implements javax.management.remote.JMXAddressable, javax.management.remote.JMXConnectorServerMBean, javax.management.MBeanRegistration)
    • javax.management.remote.NotificationResult (implements java.io.Serializable)
    • java.security.Permission (implements java.security.Guard, java.io.Serializable)
      • java.security.BasicPermission (implements java.io.Serializable)
        • javax.management.remote.SubjectDelegationPermission
    • javax.management.remote.TargetedNotification (implements java.io.Serializable)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.io.IOException
          • javax.management.remote.JMXProviderException
          • javax.management.remote.JMXServerErrorException

Interface Hierarchy

  • java.io.Closeable
    • javax.management.remote.JMXConnector
  • javax.management.remote.JMXAddressable
  • javax.management.remote.JMXAuthenticator
  • javax.management.remote.JMXConnectorProvider
  • javax.management.remote.JMXConnectorServerMBean
  • javax.management.remote.JMXConnectorServerProvider
  • javax.management.MBeanServerConnection
    • javax.management.MBeanServer
      • javax.management.remote.MBeanServerForwarder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.management.remote

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.management.remote

Packages that use javax.management.remote
javax.management.remote | Interfaces for remote access to JMX MBean servers.
javax.management.remote.rmi | The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server.

Classes in javax.management.remote used by javax.management.remote
JMXAddressable
Implemented by objects that can have a JMXServiceURL address.
JMXConnector
The client end of a JMX API connector.
JMXConnectorServer
Superclass of every connector server.
JMXConnectorServerMBean
MBean interface for connector servers.
JMXServiceURL
The address of a JMX API connector server.
MBeanServerForwarder
An object of this class implements the MBeanServer interface and wraps another object that also implements that interface.
TargetedNotification
A (Notification, Listener ID) pair.

Classes in javax.management.remote used by javax.management.remote.rmi
JMXAddressable
Implemented by objects that can have a JMXServiceURL address.
JMXConnector
The client end of a JMX API connector.
JMXConnectorServer
Superclass of every connector server.
JMXConnectorServerMBean
MBean interface for connector servers.
JMXServiceURL
The address of a JMX API connector server.
MBeanServerForwarder
An object of this class implements the MBeanServer interface and wraps another object that also implements that interface.
NotificationResult
Result of a query for buffered notifications.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.JMXConnectionNotification

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.JMXConnectionNotification

No usage of javax.management.remote.JMXConnectionNotification

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.JMXConnectorFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.JMXConnectorFactory

No usage of javax.management.remote.JMXConnectorFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.JMXConnectorServer

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.JMXConnectorServer

Packages that use JMXConnectorServer
javax.management.remote | Interfaces for remote access to JMX MBean servers.
javax.management.remote.rmi | The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server.

Uses of JMXConnectorServer in javax.management.remote

Methods in javax.management.remote that return JMXConnectorServer
JMXConnectorServer | JMXConnectorServerProvider.newJMXConnectorServer(JMXServiceURL serviceURL, Map<String,?> environment, MBeanServer mbeanServer) Creates a new connector server at the given address.
static JMXConnectorServer | JMXConnectorServerFactory.newJMXConnectorServer(JMXServiceURL serviceURL, Map<String,?> environment, MBeanServer mbeanServer) Creates a connector server at the given address.

Uses of JMXConnectorServer in javax.management.remote.rmi

Subclasses of JMXConnectorServer in javax.management.remote.rmi
 class RMIConnectorServer
A JMX API connector server that creates RMI-based connections from remote clients.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.JMXConnectorServerFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.JMXConnectorServerFactory

No usage of javax.management.remote.JMXConnectorServerFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.JMXPrincipal

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.JMXPrincipal

No usage of javax.management.remote.JMXPrincipal

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.JMXProviderException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.JMXProviderException

No usage of javax.management.remote.JMXProviderException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.JMXServerErrorException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.JMXServerErrorException

No usage of javax.management.remote.JMXServerErrorException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.JMXServiceURL

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.JMXServiceURL

Packages that use JMXServiceURL
javax.management.remote | Interfaces for remote access to JMX MBean servers.
javax.management.remote.rmi | The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server.

Uses of JMXServiceURL in javax.management.remote

Methods in javax.management.remote that return JMXServiceURL
JMXServiceURL | JMXAddressable.getAddress() The address of this object.
JMXServiceURL | JMXConnectorServerMBean.getAddress() The address of this connector server.

Methods in javax.management.remote with parameters of type JMXServiceURL
static JMXConnector | JMXConnectorFactory.connect(JMXServiceURL serviceURL) Creates a connection to the connector server at the given address.
static JMXConnector | JMXConnectorFactory.connect(JMXServiceURL serviceURL, Map<String,?> environment) Creates a connection to the connector server at the given address.
JMXConnector | JMXConnectorProvider.newJMXConnector(JMXServiceURL serviceURL, Map<String,?> environment) Creates a new connector client that is ready to connect to the connector server at the given address.
static JMXConnector | JMXConnectorFactory.newJMXConnector(JMXServiceURL serviceURL, Map<String,?> environment) Creates a connector client for the connector server at the given address.
JMXConnectorServer | JMXConnectorServerProvider.newJMXConnectorServer(JMXServiceURL serviceURL, Map<String,?> environment, MBeanServer mbeanServer) Creates a new connector server at the given address.
static JMXConnectorServer | JMXConnectorServerFactory.newJMXConnectorServer(JMXServiceURL serviceURL, Map<String,?> environment, MBeanServer mbeanServer) Creates a connector server at the given address.

Uses of JMXServiceURL in javax.management.remote.rmi

Methods in javax.management.remote.rmi that return JMXServiceURL
JMXServiceURL | RMIConnector.getAddress() The address of this connector.
JMXServiceURL | RMIConnectorServer.getAddress()

Constructors in javax.management.remote.rmi with parameters of type JMXServiceURL
RMIConnector(JMXServiceURL url, Map<String,?> environment)
Constructs an RMIConnector that will connect the RMI connector server with the given address.
RMIConnectorServer(JMXServiceURL url, Map<String,?> environment)
Makes an RMIConnectorServer.
RMIConnectorServer(JMXServiceURL url, Map<String,?> environment, MBeanServer mbeanServer)
Makes an RMIConnectorServer for the given MBean server.
RMIConnectorServer(JMXServiceURL url, Map<String,?> environment, RMIServerImpl rmiServerImpl, MBeanServer mbeanServer)
Makes an RMIConnectorServer for the given MBean server.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.NotificationResult

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.NotificationResult

Packages that use NotificationResult
javax.management.remote.rmi The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server.

Uses of NotificationResult in javax.management.remote.rmi

Methods in javax.management.remote.rmi that return NotificationResult
NotificationResult | RMIConnectionImpl_Stub.fetchNotifications(long $param_long_1, int $param_int_2, long $param_long_3)
NotificationResult | RMIConnectionImpl.fetchNotifications(long clientSequenceNumber, int maxNotifications, long timeout)
NotificationResult | RMIConnection.fetchNotifications(long clientSequenceNumber, int maxNotifications, long timeout) Retrieves notifications from the connector server.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.SubjectDelegationPermission

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.SubjectDelegationPermission

No usage of javax.management.remote.SubjectDelegationPermission

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.TargetedNotification

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.TargetedNotification

Packages that use TargetedNotification
javax.management.remote Interfaces for remote access to JMX MBean servers.

Uses of TargetedNotification in javax.management.remote

Methods in javax.management.remote that return TargetedNotification
 TargetedNotification[] NotificationResult.getTargetedNotifications()
Returns the notifications resulting from the query, and the listeners they correspond to.

Constructors in javax.management.remote with parameters of type TargetedNotification
NotificationResult(long earliestSequenceNumber, long nextSequenceNumber, TargetedNotification[] targetedNotifications)
Constructs a notification query result.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.remote.JMXAddressable

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.remote.JMXAddressable

Packages that use JMXAddressable
javax.management.remote | Interfaces for remote access to JMX MBean servers.
javax.management.remote.rmi | The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server.

Uses of JMXAddressable in javax.management.remote

Classes in javax.management.remote that implement JMXAddressable
 class JMXConnectorServer
Superclass of every connector server.

Uses of JMXAddressable in javax.management.remote.rmi

Classes in javax.management.remote.rmi that implement JMXAddressable
class | RMIConnector A connection to a remote RMI connector.
class | RMIConnectorServer A JMX API connector server that creates RMI-based connections from remote clients.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.remote.JMXAuthenticator

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.remote.JMXAuthenticator

No usage of javax.management.remote.JMXAuthenticator

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.remote.JMXConnector

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.remote.JMXConnector

Packages that use JMXConnector
javax.management.remote | Interfaces for remote access to JMX MBean servers.
javax.management.remote.rmi | The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server.

Uses of JMXConnector in javax.management.remote

Methods in javax.management.remote that return JMXConnector
static JMXConnector | JMXConnectorFactory.connect(JMXServiceURL serviceURL) Creates a connection to the connector server at the given address.
static JMXConnector | JMXConnectorFactory.connect(JMXServiceURL serviceURL, Map<String,?> environment) Creates a connection to the connector server at the given address.
JMXConnector | JMXConnectorProvider.newJMXConnector(JMXServiceURL serviceURL, Map<String,?> environment) Creates a new connector client that is ready to connect to the connector server at the given address.
static JMXConnector | JMXConnectorFactory.newJMXConnector(JMXServiceURL serviceURL, Map<String,?> environment) Creates a connector client for the connector server at the given address.
JMXConnector | JMXConnectorServer.toJMXConnector(Map<String,?> env) Returns a client stub for this connector server.
JMXConnector | JMXConnectorServerMBean.toJMXConnector(Map<String,?> env) Returns a client stub for this connector server.

Uses of JMXConnector in javax.management.remote.rmi

Classes in javax.management.remote.rmi that implement JMXConnector
 class RMIConnector
A connection to a remote RMI connector.

Methods in javax.management.remote.rmi that return JMXConnector
 JMXConnector RMIConnectorServer.toJMXConnector(Map<String,?> env)
Returns a client stub for this connector server.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.remote.JMXConnectorProvider

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.remote.JMXConnectorProvider

No usage of javax.management.remote.JMXConnectorProvider

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.remote.JMXConnectorServerMBean

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.remote.JMXConnectorServerMBean

Packages that use JMXConnectorServerMBean
javax.management.remote | Interfaces for remote access to JMX MBean servers.
javax.management.remote.rmi | The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server.

Uses of JMXConnectorServerMBean in javax.management.remote

Classes in javax.management.remote that implement JMXConnectorServerMBean
 class JMXConnectorServer
Superclass of every connector server.

Uses of JMXConnectorServerMBean in javax.management.remote.rmi

Classes in javax.management.remote.rmi that implement JMXConnectorServerMBean
 class RMIConnectorServer
A JMX API connector server that creates RMI-based connections from remote clients.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.remote.JMXConnectorServerProvider

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.remote.JMXConnectorServerProvider

No usage of javax.management.remote.JMXConnectorServerProvider

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.remote.MBeanServerForwarder

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.remote.MBeanServerForwarder

Packages that use MBeanServerForwarder
javax.management.remote | Interfaces for remote access to JMX MBean servers.
javax.management.remote.rmi | The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server.

Uses of MBeanServerForwarder in javax.management.remote

Methods in javax.management.remote with parameters of type MBeanServerForwarder
void | JMXConnectorServer.setMBeanServerForwarder(MBeanServerForwarder mbsf)
void | JMXConnectorServerMBean.setMBeanServerForwarder(MBeanServerForwarder mbsf) Adds an object that intercepts requests for the MBean server that arrive through this connector server.

Uses of MBeanServerForwarder in javax.management.remote.rmi

Methods in javax.management.remote.rmi with parameters of type MBeanServerForwarder
 void RMIConnectorServer.setMBeanServerForwarder(MBeanServerForwarder mbsf)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


JMXAddressable

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Interface JMXAddressable

All Known Implementing Classes:
JMXConnectorServer, RMIConnector, RMIConnectorServer
public interface JMXAddressable

Implemented by objects that can have a JMXServiceURL address. All JMXConnectorServer objects implement this interface. Depending on the connector implementation, a JMXConnector object may implement this interface too. JMXConnector objects for the RMI Connector are instances of RMIConnector which implements this interface.

An object implementing this interface might not have an address at a given moment. This is indicated by a null return value from getAddress().

Since:
1.6

Method Summary
 JMXServiceURL getAddress()
The address of this object.

Method Detail

getAddress

JMXServiceURL getAddress()

The address of this object.

Returns:
the address of this object, or null if it does not have one.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


JMXAuthenticator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Interface JMXAuthenticator

public interface JMXAuthenticator

Interface to define how remote credentials are converted into a JAAS Subject. This interface is used by the RMI Connector Server, and can be used by other connector servers.

The user-defined authenticator instance is passed to the connector server in the environment map as the value of the attribute JMXConnectorServer.AUTHENTICATOR. For connector servers that use only this authentication system, if this attribute is not present or its value is null then no user authentication will be performed and full access to the methods exported by the MBeanServerConnection object will be allowed.

If authentication is successful then an authenticated subject filled in with its associated principals is returned. Authorization checks will be then performed based on the given set of principals.

Since:
1.5

Method Summary
 Subject authenticate(Object credentials)
Authenticates the MBeanServerConnection client with the given client credentials.

Method Detail

authenticate

Subject authenticate(Object credentials)

Authenticates the MBeanServerConnection client with the given client credentials.

Parameters:
credentials - the user-defined credentials to be passed into the server in order to authenticate the user before creating the MBeanServerConnection. The actual type of this parameter, and whether it can be null, depends on the connector.
Returns:
the authenticated subject containing its associated principals.
Throws:
SecurityException - if the server cannot authenticate the user with the provided credentials.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMXConnectionNotification

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Class JMXConnectionNotification

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.management.Notification
            extended by  javax.management.remote.JMXConnectionNotification
All Implemented Interfaces:
Serializable
public class JMXConnectionNotification
extends Notification

Notification emitted when a client connection is opened or closed or when notifications are lost. These notifications are sent by connector servers (instances of JMXConnectorServer) and by connector clients (instances of JMXConnector). For certain connectors, a session can consist of a sequence of connections. Connection-opened and connection-closed notifications will be sent for each one.

The notification type is one of the following:

Type | Meaning
jmx.remote.connection.opened | A new client connection has been opened.
jmx.remote.connection.closed | A client connection has been closed.
jmx.remote.connection.failed | A client connection has failed unexpectedly.
jmx.remote.connection.notifs.lost | A client connection has potentially lost notifications. This notification only appears on the client side.

The timeStamp of the notification is a time value (consistent with System.currentTimeMillis()) indicating when the notification was constructed.

Since:
1.5
See Also:
Serialized Form

Field Summary
static String | CLOSED Notification type string for a connection-closed notification.
static String | FAILED Notification type string for a connection-failed notification.
static String | NOTIFS_LOST Notification type string for a connection that has possibly lost notifications.
static String | OPENED Notification type string for a connection-opened notification.
Fields inherited from class javax.management.Notification
source
Constructor Summary
JMXConnectionNotification(String type, Object source, String connectionId, long sequenceNumber, String message, Object userData)
Constructs a new connection notification.
Method Summary
 String getConnectionId()
The connection ID to which this notification pertains.
Methods inherited from class javax.management.Notification
getMessage, getSequenceNumber, getTimeStamp, getType, getUserData, setSequenceNumber, setSource, setTimeStamp, setUserData, toString
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

OPENED

public static final String OPENED

Notification type string for a connection-opened notification.

See Also:
Constant Field Values

CLOSED

public static final String CLOSED

Notification type string for a connection-closed notification.

See Also:
Constant Field Values

FAILED

public static final String FAILED

Notification type string for a connection-failed notification.

See Also:
Constant Field Values

NOTIFS_LOST

public static final String NOTIFS_LOST

Notification type string for a connection that has possibly lost notifications.

See Also:
Constant Field Values
Constructor Detail

JMXConnectionNotification

public JMXConnectionNotification(String type,
                                 Object source,
                                 String connectionId,
                                 long sequenceNumber,
                                 String message,
                                 Object userData)
Constructs a new connection notification. The source of the notification depends on whether it is being sent by a connector server or a connector client:
  • For a connector server, if it is registered in an MBean server, the source is the ObjectName under which it is registered. Otherwise, it is a reference to the connector server object itself, an instance of a subclass of JMXConnectorServer.
  • For a connector client, the source is a reference to the connector client object, an instance of a class implementing JMXConnector.

Parameters:
type - the type of the notification. This is usually one of the constants OPENED, CLOSED, FAILED, NOTIFS_LOST. It is not an error for it to be a different string.
source - the connector server or client emitting the notification.
connectionId - the ID of the connection within its connector server.
sequenceNumber - a non-negative integer. It is expected but not required that this number will be greater than any previous sequenceNumber in a notification from this source.
message - an unspecified text message, typically containing a human-readable description of the event. Can be null.
userData - an object whose type and meaning is defined by the connector server. Can be null.
Throws:
NullPointerException - if type, source, or connectionId is null.
IllegalArgumentException - if sequenceNumber is negative.
Method Detail

getConnectionId

public String getConnectionId()

The connection ID to which this notification pertains.

Returns:
the connection ID.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMXConnector

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Interface JMXConnector

All Superinterfaces:
Closeable
All Known Implementing Classes:
RMIConnector
public interface JMXConnector
extends Closeable

The client end of a JMX API connector. An object of this type can be used to establish a connection to a connector server.

A newly-created object of this type is unconnected. Its connect method must be called before it can be used. However, objects created by JMXConnectorFactory.connect are already connected.

Since:
1.5

Field Summary
static String CREDENTIALS
Name of the attribute that specifies the credentials to send to the connector server during connection.
Method Summary
void | addConnectionNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Adds a listener to be informed of changes in connection status.
void | close() Closes the client connection to its server.
void | connect() Establishes the connection to the connector server.
void | connect(Map<String,?> env) Establishes the connection to the connector server.
String | getConnectionId() Gets this connection's ID from the connector server.
MBeanServerConnection | getMBeanServerConnection() Returns an MBeanServerConnection object representing a remote MBean server.
MBeanServerConnection | getMBeanServerConnection(Subject delegationSubject) Returns an MBeanServerConnection object representing a remote MBean server on which operations are performed on behalf of the supplied delegation subject.
void | removeConnectionNotificationListener(NotificationListener listener) Removes a listener from the list to be informed of changes in status.
void | removeConnectionNotificationListener(NotificationListener l, NotificationFilter f, Object handback) Removes a listener from the list to be informed of changes in status.

Field Detail

CREDENTIALS

static final String CREDENTIALS

Name of the attribute that specifies the credentials to send to the connector server during connection. The value associated with this attribute, if any, is a serializable object of an appropriate type for the server's JMXAuthenticator.

See Also:
Constant Field Values
Method Detail

connect

void connect()
             throws IOException

Establishes the connection to the connector server. This method is equivalent to connect(null).

Throws:
IOException - if the connection could not be made because of a communication problem.
SecurityException - if the connection could not be made for security reasons.

connect

void connect(Map<String,?> env)
             throws IOException

Establishes the connection to the connector server.

If connect has already been called successfully on this object, calling it again has no effect. If, however, close() was called after connect, the new connect will throw an IOException.

Otherwise, either connect has never been called on this object, or it has been called but produced an exception. Then calling connect will attempt to establish a connection to the connector server.

Parameters:
env - the properties of the connection. Properties in this map override properties in the map specified when the JMXConnector was created, if any. This parameter can be null, which is equivalent to an empty map.
Throws:
IOException - if the connection could not be made because of a communication problem.
SecurityException - if the connection could not be made for security reasons.

getMBeanServerConnection

MBeanServerConnection getMBeanServerConnection()
                                               throws IOException

Returns an MBeanServerConnection object representing a remote MBean server. For a given JMXConnector, two successful calls to this method will usually return the same MBeanServerConnection object, though this is not required.

For each method in the returned MBeanServerConnection, calling the method causes the corresponding method to be called in the remote MBean server. The value returned by the MBean server method is the value returned to the client. If the MBean server method produces an Exception, the same Exception is seen by the client. If the MBean server method, or the attempt to call it, produces an Error, the Error is wrapped in a JMXServerErrorException, which is seen by the client.

Calling this method is equivalent to calling getMBeanServerConnection(null) meaning that no delegation subject is specified and that all the operations called on the MBeanServerConnection must use the authenticated subject, if any.

Returns:
an object that implements the MBeanServerConnection interface by forwarding its methods to the remote MBean server.
Throws:
IOException - if a valid MBeanServerConnection cannot be created, for instance because the connection to the remote MBean server has not yet been established (with the connect method), or it has been closed, or it has broken.

getMBeanServerConnection

MBeanServerConnection getMBeanServerConnection(Subject delegationSubject)
                                               throws IOException

Returns an MBeanServerConnection object representing a remote MBean server on which operations are performed on behalf of the supplied delegation subject. For a given JMXConnector and Subject, two successful calls to this method will usually return the same MBeanServerConnection object, though this is not required.

For each method in the returned MBeanServerConnection, calling the method causes the corresponding method to be called in the remote MBean server on behalf of the given delegation subject instead of the authenticated subject. The value returned by the MBean server method is the value returned to the client. If the MBean server method produces an Exception, the same Exception is seen by the client. If the MBean server method, or the attempt to call it, produces an Error, the Error is wrapped in a JMXServerErrorException, which is seen by the client.

Parameters:
delegationSubject - the Subject on behalf of which requests will be performed. Can be null, in which case requests will be performed on behalf of the authenticated Subject, if any.
Returns:
an object that implements the MBeanServerConnection interface by forwarding its methods to the remote MBean server on behalf of a given delegation subject.
Throws:
IOException - if a valid MBeanServerConnection cannot be created, for instance because the connection to the remote MBean server has not yet been established (with the connect method), or it has been closed, or it has broken.

close

void close()
           throws IOException

Closes the client connection to its server. Any ongoing or new request using the MBeanServerConnection returned by getMBeanServerConnection() will get an IOException.

If close has already been called successfully on this object, calling it again has no effect. If close has never been called, or if it was called but produced an exception, an attempt will be made to close the connection. This attempt can succeed, in which case close will return normally, or it can generate an exception.

Closing a connection is a potentially slow operation. For example, if the server has crashed, the close operation might have to wait for a network protocol timeout. Callers that do not want to block in a close operation should do it in a separate thread.

Specified by:
close in interface Closeable
Throws:
IOException - if the connection cannot be closed cleanly. If this exception is thrown, it is not known whether the server end of the connection has been cleanly closed.

addConnectionNotificationListener

void addConnectionNotificationListener(NotificationListener listener,
                                       NotificationFilter filter,
                                       Object handback)

Adds a listener to be informed of changes in connection status. The listener will receive notifications of type JMXConnectionNotification. An implementation can send other types of notifications too.

Any number of listeners can be added with this method. The same listener can be added more than once with the same or different values for the filter and handback. There is no special treatment of a duplicate entry. For example, if a listener is registered twice with no filter, then its handleNotification method will be called twice for each notification.

Parameters:
listener - a listener to receive connection status notifications.
filter - a filter to select which notifications are to be delivered to the listener, or null if all notifications are to be delivered.
handback - an object to be given to the listener along with each notification. Can be null.
Throws:
NullPointerException - if listener is null.
See Also:
removeConnectionNotificationListener(javax.management.NotificationListener), NotificationBroadcaster.addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

removeConnectionNotificationListener

void removeConnectionNotificationListener(NotificationListener listener)
                                          throws ListenerNotFoundException

Removes a listener from the list to be informed of changes in status. The listener must previously have been added. If there is more than one matching listener, all are removed.

Parameters:
listener - a listener to receive connection status notifications.
Throws:
NullPointerException - if listener is null.
ListenerNotFoundException - if the listener is not registered with this JMXConnector.
See Also:
removeConnectionNotificationListener(NotificationListener, NotificationFilter, Object), addConnectionNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object), NotificationEmitter.removeNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

removeConnectionNotificationListener

void removeConnectionNotificationListener(NotificationListener l,
                                          NotificationFilter f,
                                          Object handback)
                                          throws ListenerNotFoundException

Removes a listener from the list to be informed of changes in status. The listener must previously have been added with the same three parameters. If there is more than one matching listener, only one is removed.

Parameters:
l - a listener to receive connection status notifications.
f - a filter to select which notifications are to be delivered to the listener. Can be null.
handback - an object to be given to the listener along with each notification. Can be null.
Throws:
ListenerNotFoundException - if the listener is not registered with this JMXConnector, or is not registered with the given filter and handback.
See Also:
removeConnectionNotificationListener(NotificationListener), addConnectionNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object), NotificationEmitter.removeNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

getConnectionId

String getConnectionId()
                       throws IOException

Gets this connection's ID from the connector server. For a given connector server, every connection will have a unique id which does not change during the lifetime of the connection.

Returns:
the unique ID of this connection. This is the same as the ID that the connector server includes in its JMXConnectionNotifications. The package description describes the conventions for connection IDs.
Throws:
IOException - if the connection ID cannot be obtained, for instance because the connection is closed or broken.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMXConnectorFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Class JMXConnectorFactory

java.lang.Object
    extended by  javax.management.remote.JMXConnectorFactory

public class JMXConnectorFactory
extends Object

Factory to create JMX API connector clients. There are no instances of this class.

Connections are usually made using the connect method of this class. More advanced applications can separate the creation of the connector client, using newJMXConnector and the establishment of the connection itself, using JMXConnector.connect(Map).

Each client is created by an instance of JMXConnectorProvider. This instance is found as follows. Suppose the given JMXServiceURL looks like "service:jmx:protocol:remainder". Then the factory will attempt to find the appropriate JMXConnectorProvider for protocol. Each occurrence of the character + or - in protocol is replaced by . or _, respectively.

A provider package list is searched for as follows:

  1. If the environment parameter to newJMXConnector contains the key jmx.remote.protocol.provider.pkgs then the associated value is the provider package list.
  2. Otherwise, if the system property jmx.remote.protocol.provider.pkgs exists, then its value is the provider package list.
  3. Otherwise, there is no provider package list.

The provider package list is a string that is interpreted as a list of non-empty Java package names separated by vertical bars (|). If the string is empty, then so is the provider package list. If the provider package list is not a String, or if it contains an element that is an empty string, a JMXProviderException is thrown.

If the provider package list exists and is not empty, then for each element pkg of the list, the factory will attempt to load the class

pkg.protocol.ClientProvider

If the environment parameter to newJMXConnector contains the key jmx.remote.protocol.provider.class.loader then the associated value is the class loader to use to load the provider. If the associated value is not an instance of ClassLoader, an IllegalArgumentException is thrown.

If the jmx.remote.protocol.provider.class.loader key is not present in the environment parameter, the calling thread's context class loader is used.

If the attempt to load this class produces a ClassNotFoundException, the search for a handler continues with the next element of the list.

Otherwise, a problem with the provider found is signalled by a JMXProviderException whose cause indicates the underlying exception, as follows:

  • if the attempt to load the class produces an exception other than ClassNotFoundException, that is the cause;
  • if Class.newInstance() for the class produces an exception, that is the cause.

If no provider is found by the above steps, including the default case where there is no provider package list, then the implementation will use its own provider for protocol, or it will throw a MalformedURLException if there is none. An implementation may choose to find providers by other means. For example, it may support the JAR conventions for service providers, where the service interface is JMXConnectorProvider.

Every implementation must support the RMI connector protocols, specified with the string rmi or iiop.

Once a provider is found, the result of the newJMXConnector method is the result of calling newJMXConnector on the provider.

The Map parameter passed to the JMXConnectorProvider is a new read-only Map that contains all the entries that were in the environment parameter to JMXConnectorFactory.newJMXConnector, if there was one. Additionally, if the jmx.remote.protocol.provider.class.loader key is not present in the environment parameter, it is added to the new read-only Map. The associated value is the calling thread's context class loader.

Since:
1.5

Field Summary
static String | DEFAULT_CLASS_LOADER Name of the attribute that specifies the default class loader.
static String | PROTOCOL_PROVIDER_CLASS_LOADER Name of the attribute that specifies the class loader for loading protocol providers.
static String | PROTOCOL_PROVIDER_PACKAGES Name of the attribute that specifies the provider packages that are consulted when looking for the handler for a protocol.
Method Summary
static JMXConnector | connect(JMXServiceURL serviceURL) Creates a connection to the connector server at the given address.
static JMXConnector | connect(JMXServiceURL serviceURL, Map<String,?> environment) Creates a connection to the connector server at the given address.
static JMXConnector | newJMXConnector(JMXServiceURL serviceURL, Map<String,?> environment) Creates a connector client for the connector server at the given address.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_CLASS_LOADER

public static final String DEFAULT_CLASS_LOADER

Name of the attribute that specifies the default class loader. This class loader is used to deserialize return values and exceptions from remote MBeanServerConnection calls. The value associated with this attribute is an instance of ClassLoader.

See Also:
Constant Field Values

PROTOCOL_PROVIDER_PACKAGES

public static final String PROTOCOL_PROVIDER_PACKAGES

Name of the attribute that specifies the provider packages that are consulted when looking for the handler for a protocol. The value associated with this attribute is a string with package names separated by vertical bars (|).

See Also:
Constant Field Values

PROTOCOL_PROVIDER_CLASS_LOADER

public static final String PROTOCOL_PROVIDER_CLASS_LOADER

Name of the attribute that specifies the class loader for loading protocol providers. The value associated with this attribute is an instance of ClassLoader.

See Also:
Constant Field Values
Method Detail

connect

public static JMXConnector connect(JMXServiceURL serviceURL)
                            throws IOException

Creates a connection to the connector server at the given address.

This method is equivalent to connect(serviceURL, null).

Parameters:
serviceURL - the address of the connector server to connect to.
Returns:
a JMXConnector whose connect method has been called.
Throws:
NullPointerException - if serviceURL is null.
IOException - if the connector client or the connection cannot be made because of a communication problem.
SecurityException - if the connection cannot be made for security reasons.

connect

public static JMXConnector connect(JMXServiceURL serviceURL,
                                   Map<String,?> environment)
                            throws IOException

Creates a connection to the connector server at the given address.

This method is equivalent to:

 JMXConnector conn = JMXConnectorFactory.newJMXConnector(serviceURL,
                                                         environment);
 conn.connect(environment);

Parameters:
serviceURL - the address of the connector server to connect to.
environment - a set of attributes to determine how the connection is made. This parameter can be null. Keys in this map must be Strings. The appropriate type of each associated value depends on the attribute. The contents of environment are not changed by this call.
Returns:
a JMXConnector representing the newly-made connection. Each successful call to this method produces a different object.
Throws:
NullPointerException - if serviceURL is null.
IOException - if the connector client or the connection cannot be made because of a communication problem.
SecurityException - if the connection cannot be made for security reasons.

newJMXConnector

public static JMXConnector newJMXConnector(JMXServiceURL serviceURL,
                                           Map<String,?> environment)
                                    throws IOException

Creates a connector client for the connector server at the given address. The resultant client is not connected until its connect method is called.

Parameters:
serviceURL - the address of the connector server to connect to.
environment - a set of attributes to determine how the connection is made. This parameter can be null. Keys in this map must be Strings. The appropriate type of each associated value depends on the attribute. The contents of environment are not changed by this call.
Returns:
a JMXConnector representing the new connector client. Each successful call to this method produces a different object.
Throws:
NullPointerException - if serviceURL is null.
IOException - if the connector client cannot be made because of a communication problem.
MalformedURLException - if there is no provider for the protocol in serviceURL.
JMXProviderException - if there is a provider for the protocol in serviceURL but it cannot be used for some reason.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMXConnectorProvider

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Interface JMXConnectorProvider

public interface JMXConnectorProvider

A provider for creating JMX API connector clients using a given protocol. Instances of this interface are created by JMXConnectorFactory as part of its newJMXConnector method.

Since:
1.5

Method Summary
 JMXConnector newJMXConnector(JMXServiceURL serviceURL, Map<String,?> environment)
Creates a new connector client that is ready to connect to the connector server at the given address.

Method Detail

newJMXConnector

JMXConnector newJMXConnector(JMXServiceURL serviceURL,
                             Map<String,?> environment)
                             throws IOException

Creates a new connector client that is ready to connect to the connector server at the given address. Each successful call to this method produces a different JMXConnector object.

Parameters:
serviceURL - the address of the connector server to connect to.
environment - a read-only Map containing named attributes to determine how the connection is made. Keys in this map must be Strings. The appropriate type of each associated value depends on the attribute.

Returns:
a JMXConnector representing the new connector client. Each successful call to this method produces a different object.
Throws:
NullPointerException - if serviceURL or environment is null.
IOException - It is recommended for a provider implementation to throw MalformedURLException if the protocol in the serviceURL is not recognized by this provider, JMXProviderException if this is a provider for the protocol in serviceURL but it cannot be used for some reason or any other IOException if the connection cannot be made because of a communication problem.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMXConnectorServer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Class JMXConnectorServer

java.lang.Object
    extended by  javax.management.NotificationBroadcasterSupport
        extended by  javax.management.remote.JMXConnectorServer
All Implemented Interfaces:
MBeanRegistration, NotificationBroadcaster, NotificationEmitter, JMXAddressable, JMXConnectorServerMBean
Direct Known Subclasses:
RMIConnectorServer
public abstract class JMXConnectorServer
extends NotificationBroadcasterSupport
implements JMXConnectorServerMBean, MBeanRegistration, JMXAddressable

Superclass of every connector server. A connector server is attached to an MBean server. It listens for client connection requests and creates a connection for each one.

A connector server is associated with an MBean server either by registering it in that MBean server, or by passing the MBean server to its constructor.

A connector server is inactive when created. It only starts listening for client connections when the start method is called. A connector server stops listening for client connections when the stop method is called or when the connector server is unregistered from its MBean server.

Stopping a connector server does not unregister it from its MBean server. A connector server once stopped cannot be restarted.

Each time a client connection is made or broken, a notification of class JMXConnectionNotification is emitted.

Since:
1.5

Field Summary
static String AUTHENTICATOR
Name of the attribute that specifies the authenticator for a connector server.
Constructor Summary
JMXConnectorServer()
Constructs a connector server that will be registered as an MBean in the MBean server it is attached to.
JMXConnectorServer(MBeanServer mbeanServer)
Constructs a connector server that is attached to the given MBean server.
Method Summary
protected void | connectionClosed(String connectionId, String message, Object userData) Called by a subclass when a client connection is closed normally.
protected void | connectionFailed(String connectionId, String message, Object userData) Called by a subclass when a client connection fails.
protected void | connectionOpened(String connectionId, String message, Object userData) Called by a subclass when a new client connection is opened.
String[] | getConnectionIds() The list of IDs for currently-open connections to this connector server.
MBeanServer | getMBeanServer() Returns the MBean server that this connector server is attached to.
MBeanNotificationInfo[] | getNotificationInfo() Returns an array indicating the notifications that this MBean sends.
void | postDeregister() Allows the MBean to perform any operations needed after having been unregistered in the MBean server.
void | postRegister(Boolean registrationDone) Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.
void | preDeregister() Called by an MBean server when this connector server is unregistered from that MBean server.
ObjectName | preRegister(MBeanServer mbs, ObjectName name) Called by an MBean server when this connector server is registered in that MBean server.
void | setMBeanServerForwarder(MBeanServerForwarder mbsf) Adds an object that intercepts requests for the MBean server that arrive through this connector server.
JMXConnector | toJMXConnector(Map<String,?> env) Returns a client stub for this connector server.
Methods inherited from class javax.management.NotificationBroadcasterSupport
addNotificationListener, handleNotification, removeNotificationListener, removeNotificationListener, sendNotification
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.management.remote.JMXConnectorServerMBean
getAddress, getAttributes, isActive, start, stop
Methods inherited from interface javax.management.remote.JMXAddressable
getAddress

Field Detail

AUTHENTICATOR

public static final String AUTHENTICATOR

Name of the attribute that specifies the authenticator for a connector server. The value associated with this attribute, if any, must be an object that implements the interface JMXAuthenticator.

See Also:
Constant Field Values
Constructor Detail

JMXConnectorServer

public JMXConnectorServer()

Constructs a connector server that will be registered as an MBean in the MBean server it is attached to. This constructor is typically called by one of the createMBean methods when creating, within an MBean server, a connector server that makes it available remotely.

JMXConnectorServer

public JMXConnectorServer(MBeanServer mbeanServer)

Constructs a connector server that is attached to the given MBean server. A connector server that is created in this way can be registered in a different MBean server.

Parameters:
mbeanServer - the MBean server that this connector server is attached to. Null if this connector server will be attached to an MBean server by being registered in it.
Method Detail

getMBeanServer

public MBeanServer getMBeanServer()

Returns the MBean server that this connector server is attached to.

Returns:
the MBean server that this connector server is attached to, or null if it is not yet attached to an MBean server.

setMBeanServerForwarder

public void setMBeanServerForwarder(MBeanServerForwarder mbsf)
Description copied from interface: JMXConnectorServerMBean

Adds an object that intercepts requests for the MBean server that arrive through this connector server. This object will be supplied as the MBeanServer for any new connection created by this connector server. Existing connections are unaffected.

If this connector server is already associated with an MBeanServer object, then that object is given to mbsf.setMBeanServer. If doing so produces an exception, this method throws the same exception without any other effect.

If this connector is not already associated with an MBeanServer object, or if the mbsf.setMBeanServer call just mentioned succeeds, then mbsf becomes this connector server's MBeanServer.

Specified by:
setMBeanServerForwarder in interface JMXConnectorServerMBean
Parameters:
mbsf - the new MBeanServerForwarder.

getConnectionIds

public String[] getConnectionIds()
Description copied from interface: JMXConnectorServerMBean

The list of IDs for currently-open connections to this connector server.

Specified by:
getConnectionIds in interface JMXConnectorServerMBean
Returns:
a new string array containing the list of IDs. If there are no currently-open connections, this array will be empty.

toJMXConnector

public JMXConnector toJMXConnector(Map<String,?> env)
                            throws IOException

Returns a client stub for this connector server. A client stub is a serializable object whose connect method can be used to make one new connection to this connector server.

A given connector need not support the generation of client stubs. However, the connectors specified by the JMX Remote API do (JMXMP Connector and RMI Connector).

The default implementation of this method uses JMXConnectorServerMBean.getAddress() and JMXConnectorFactory to generate the stub, with code equivalent to the following:

 JMXServiceURL addr = getAddress();
 return JMXConnectorFactory.newJMXConnector(addr, env);

A connector server for which this is inappropriate must override this method so that it either implements the appropriate logic or throws UnsupportedOperationException.

Specified by:
toJMXConnector in interface JMXConnectorServerMBean
Parameters:
env - client connection parameters of the same sort that could be provided to JMXConnector.connect(Map). Can be null, which is equivalent to an empty map.
Returns:
a client stub that can be used to make a new connection to this connector server.
Throws:
UnsupportedOperationException - if this connector server does not support the generation of client stubs.
IllegalStateException - if the JMXConnectorServer is not started (see JMXConnectorServerMBean.isActive()).
IOException - if a communications problem means that a stub cannot be created.

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()

Returns an array indicating the notifications that this MBean sends. The implementation in JMXConnectorServer returns an array with one element, indicating that it can emit notifications of class JMXConnectionNotification with the types defined in that class. A subclass that can emit other notifications should return an array that contains this element plus descriptions of the other notifications.

Specified by:
getNotificationInfo in interface NotificationBroadcaster
Overrides:
getNotificationInfo in class NotificationBroadcasterSupport
Returns:
the array of possible notifications.

connectionOpened

protected void connectionOpened(String connectionId,
                                String message,
                                Object userData)

Called by a subclass when a new client connection is opened. Adds connectionId to the list returned by getConnectionIds(), then emits a JMXConnectionNotification with type JMXConnectionNotification.OPENED.

Parameters:
connectionId - the ID of the new connection. This must be different from the ID of any connection previously opened by this connector server.
message - the message for the emitted JMXConnectionNotification. Can be null. See Notification.getMessage().
userData - the userData for the emitted JMXConnectionNotification. Can be null. See Notification.getUserData().
Throws:
NullPointerException - if connectionId is null.

connectionClosed

protected void connectionClosed(String connectionId,
                                String message,
                                Object userData)

Called by a subclass when a client connection is closed normally. Removes connectionId from the list returned by getConnectionIds(), then emits a JMXConnectionNotification with type JMXConnectionNotification.CLOSED.

Parameters:
connectionId - the ID of the closed connection.
message - the message for the emitted JMXConnectionNotification. Can be null. See Notification.getMessage().
userData - the userData for the emitted JMXConnectionNotification. Can be null. See Notification.getUserData().
Throws:
NullPointerException - if connectionId is null.

connectionFailed

protected void connectionFailed(String connectionId,
                                String message,
                                Object userData)

Called by a subclass when a client connection fails. Removes connectionId from the list returned by getConnectionIds(), then emits a JMXConnectionNotification with type JMXConnectionNotification.FAILED.

Parameters:
connectionId - the ID of the failed connection.
message - the message for the emitted JMXConnectionNotification. Can be null. See Notification.getMessage().
userData - the userData for the emitted JMXConnectionNotification. Can be null. See Notification.getUserData().
Throws:
NullPointerException - if connectionId is null.

preRegister

public ObjectName preRegister(MBeanServer mbs,
                              ObjectName name)

Called by an MBean server when this connector server is registered in that MBean server. This connector server becomes attached to the MBean server and its getMBeanServer() method will return mbs.

If this connector server is already attached to an MBean server, this method has no effect. The MBean server it is attached to is not necessarily the one it is being registered in.

Specified by:
preRegister in interface MBeanRegistration
Parameters:
mbs - the MBean server in which this connection server is being registered.
name - The object name of the MBean.
Returns:
The name under which the MBean is to be registered.
Throws:
NullPointerException - if mbs or name is null.

postRegister

public void postRegister(Boolean registrationDone)
Description copied from interface: MBeanRegistration
Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.

Specified by:
postRegister in interface MBeanRegistration
Parameters:
registrationDone - Indicates whether or not the MBean has been successfully registered in the MBean server. The value false means that the registration phase has failed.

preDeregister

public void preDeregister()
                   throws Exception

Called by an MBean server when this connector server is unregistered from that MBean server. If this connector server was attached to that MBean server by being registered in it, and if the connector server is still active, then unregistering it will call the stop method. If the stop method throws an exception, the unregistration attempt will fail. It is recommended to call the stop method explicitly before unregistering the MBean.

Specified by:
preDeregister in interface MBeanRegistration
Throws:
IOException - if thrown by the stop method.
Exception - This exception will be caught by the MBean server and re-thrown as an MBeanRegistrationException.

postDeregister

public void postDeregister()
Description copied from interface: MBeanRegistration
Allows the MBean to perform any operations needed after having been unregistered in the MBean server.

Specified by:
postDeregister in interface MBeanRegistration
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMXConnectorServerFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Class JMXConnectorServerFactory

java.lang.Object
    extended by  javax.management.remote.JMXConnectorServerFactory

public class JMXConnectorServerFactory
extends Object

Factory to create JMX API connector servers. There are no instances of this class.

Each connector server is created by an instance of JMXConnectorServerProvider. This instance is found as follows. Suppose the given JMXServiceURL looks like "service:jmx:protocol:remainder". Then the factory will attempt to find the appropriate JMXConnectorServerProvider for protocol. Each occurrence of the character + or - in protocol is replaced by . or _, respectively.

A provider package list is searched for as follows:

  1. If the environment parameter to newJMXConnectorServer contains the key jmx.remote.protocol.provider.pkgs then the associated value is the provider package list.
  2. Otherwise, if the system property jmx.remote.protocol.provider.pkgs exists, then its value is the provider package list.
  3. Otherwise, there is no provider package list.

The provider package list is a string that is interpreted as a list of non-empty Java package names separated by vertical bars (|). If the string is empty, then so is the provider package list. If the provider package list is not a String, or if it contains an element that is an empty string, a JMXProviderException is thrown.

If the provider package list exists and is not empty, then for each element pkg of the list, the factory will attempt to load the class

pkg.protocol.ServerProvider

If the environment parameter to newJMXConnectorServer contains the key jmx.remote.protocol.provider.class.loader then the associated value is the class loader to use to load the provider. If the associated value is not an instance of ClassLoader, an IllegalArgumentException is thrown.

If the jmx.remote.protocol.provider.class.loader key is not present in the environment parameter, the calling thread's context class loader is used.

If the attempt to load this class produces a ClassNotFoundException, the search for a handler continues with the next element of the list.

Otherwise, a problem with the provider found is signalled by a JMXProviderException whose cause indicates the underlying exception, as follows:

  • if the attempt to load the class produces an exception other than ClassNotFoundException, that is the cause;
  • if Class.newInstance() for the class produces an exception, that is the cause.

If no provider is found by the above steps, including the default case where there is no provider package list, then the implementation will use its own provider for protocol, or it will throw a MalformedURLException if there is none. An implementation may choose to find providers by other means. For example, it may support the JAR conventions for service providers, where the service interface is JMXConnectorServerProvider.

Every implementation must support the RMI connector protocols, specified with the string rmi or iiop.

Once a provider is found, the result of the newJMXConnectorServer method is the result of calling newJMXConnectorServer on the provider.

The Map parameter passed to the JMXConnectorServerProvider is a new read-only Map that contains all the entries that were in the environment parameter to JMXConnectorServerFactory.newJMXConnectorServer, if there was one. Additionally, if the jmx.remote.protocol.provider.class.loader key is not present in the environment parameter, it is added to the new read-only Map. The associated value is the calling thread's context class loader.

Since:
1.5

Field Summary
static String | DEFAULT_CLASS_LOADER Name of the attribute that specifies the default class loader.
static String | DEFAULT_CLASS_LOADER_NAME Name of the attribute that specifies the default class loader MBean name.
static String | PROTOCOL_PROVIDER_CLASS_LOADER Name of the attribute that specifies the class loader for loading protocol providers.
static String | PROTOCOL_PROVIDER_PACKAGES Name of the attribute that specifies the provider packages that are consulted when looking for the handler for a protocol.
Method Summary
static JMXConnectorServer newJMXConnectorServer(JMXServiceURL serviceURL, Map<String,?> environment, MBeanServer mbeanServer)
Creates a connector server at the given address.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_CLASS_LOADER

public static final String DEFAULT_CLASS_LOADER

Name of the attribute that specifies the default class loader. This class loader is used to deserialize objects in requests received from the client, possibly after consulting an MBean-specific class loader. The value associated with this attribute is an instance of ClassLoader.

See Also:
Constant Field Values

DEFAULT_CLASS_LOADER_NAME

public static final String DEFAULT_CLASS_LOADER_NAME

Name of the attribute that specifies the default class loader MBean name. This class loader is used to deserialize objects in requests received from the client, possibly after consulting an MBean-specific class loader. The value associated with this attribute is an instance of ObjectName.

See Also:
Constant Field Values

PROTOCOL_PROVIDER_PACKAGES

public static final String PROTOCOL_PROVIDER_PACKAGES

Name of the attribute that specifies the provider packages that are consulted when looking for the handler for a protocol. The value associated with this attribute is a string with package names separated by vertical bars (|).

See Also:
Constant Field Values

PROTOCOL_PROVIDER_CLASS_LOADER

public static final String PROTOCOL_PROVIDER_CLASS_LOADER

Name of the attribute that specifies the class loader for loading protocol providers. The value associated with this attribute is an instance of ClassLoader.

See Also:
Constant Field Values
Method Detail

newJMXConnectorServer

public static JMXConnectorServer newJMXConnectorServer(JMXServiceURL serviceURL,
                                                       Map<String,?> environment,
                                                       MBeanServer mbeanServer)
                                                throws IOException

Creates a connector server at the given address. The resultant server is not started until its start method is called.

Parameters:
serviceURL - the address of the new connector server. The actual address of the new connector server, as returned by its getAddress method, will not necessarily be exactly the same. For example, it might include a port number if the original address did not.
environment - a set of attributes to control the new connector server's behavior. This parameter can be null. Keys in this map must be Strings. The appropriate type of each associated value depends on the attribute. The contents of environment are not changed by this call.
mbeanServer - the MBean server that this connector server is attached to. Null if this connector server will be attached to an MBean server by being registered in it.
Returns:
a JMXConnectorServer representing the new connector server. Each successful call to this method produces a different object.
Throws:
NullPointerException - if serviceURL is null.
IOException - if the connector server cannot be made because of a communication problem.
MalformedURLException - if there is no provider for the protocol in serviceURL.
JMXProviderException - if there is a provider for the protocol in serviceURL but it cannot be used for some reason.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMXConnectorServerMBean

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Interface JMXConnectorServerMBean

All Known Implementing Classes:
JMXConnectorServer, RMIConnectorServer
public interface JMXConnectorServerMBean

MBean interface for connector servers. A JMX API connector server is attached to an MBean server, and establishes connections to that MBean server for remote clients.

A newly-created connector server is inactive, and does not yet listen for connections. Only when its start method has been called does it start listening for connections.

Since:
1.5

Method Summary
JMXServiceURL | getAddress() The address of this connector server.
Map<String,?> | getAttributes() The attributes for this connector server.
String[] | getConnectionIds() The list of IDs for currently-open connections to this connector server.
boolean | isActive() Determines whether the connector server is active.
void | setMBeanServerForwarder(MBeanServerForwarder mbsf) Adds an object that intercepts requests for the MBean server that arrive through this connector server.
void | start() Activates the connector server, that is, starts listening for client connections.
void | stop() Deactivates the connector server, that is, stops listening for client connections.
JMXConnector | toJMXConnector(Map<String,?> env) Returns a client stub for this connector server.

Method Detail

start

void start()
           throws IOException

Activates the connector server, that is, starts listening for client connections. Calling this method when the connector server is already active has no effect. Calling this method when the connector server has been stopped will generate an IOException.

Throws:
IOException - if it is not possible to start listening or if the connector server has been stopped.
IllegalStateException - if the connector server has not been attached to an MBean server.

stop

void stop()
          throws IOException

Deactivates the connector server, that is, stops listening for client connections. Calling this method will also close all client connections that were made by this server. After this method returns, whether normally or with an exception, the connector server will not create any new client connections.

Once a connector server has been stopped, it cannot be started again.

Calling this method when the connector server has already been stopped has no effect. Calling this method when the connector server has not yet been started will disable the connector server object permanently.

If closing a client connection produces an exception, that exception is not thrown from this method. A JMXConnectionNotification with type JMXConnectionNotification.FAILED is emitted from this MBean with the connection ID of the connection that could not be closed.

Closing a connector server is a potentially slow operation. For example, if a client machine with an open connection has crashed, the close operation might have to wait for a network protocol timeout. Callers that do not want to block in a close operation should do it in a separate thread.

Throws:
IOException - if the server cannot be closed cleanly. When this exception is thrown, the server has already attempted to close all client connections. All client connections are closed except possibly those that generated exceptions when the server attempted to close them.

isActive

boolean isActive()

Determines whether the connector server is active. A connector server starts being active when its start method returns successfully and remains active until either its stop method is called or the connector server fails.

Returns:
true if the connector server is active.

setMBeanServerForwarder

void setMBeanServerForwarder(MBeanServerForwarder mbsf)

Adds an object that intercepts requests for the MBean server that arrive through this connector server. This object will be supplied as the MBeanServer for any new connection created by this connector server. Existing connections are unaffected.

If this connector server is already associated with an MBeanServer object, then that object is given to mbsf.setMBeanServer. If doing so produces an exception, this method throws the same exception without any other effect.

If this connector is not already associated with an MBeanServer object, or if the mbsf.setMBeanServer call just mentioned succeeds, then mbsf becomes this connector server's MBeanServer.

Parameters:
mbsf - the new MBeanServerForwarder.
Throws:
IllegalArgumentException - if the call to mbsf.setMBeanServer fails with IllegalArgumentException. This includes the case where mbsf is null.

getConnectionIds

String[] getConnectionIds()

The list of IDs for currently-open connections to this connector server.

Returns:
a new string array containing the list of IDs. If there are no currently-open connections, this array will be empty.

getAddress

JMXServiceURL getAddress()

The address of this connector server.

Returns:
the address of this connector server, or null if it does not have one.

getAttributes

Map<String,?> getAttributes()

The attributes for this connector server.

Returns:
a read-only map containing the attributes for this connector server. Attributes whose values are not serializable are omitted from this map. If there are no serializable attributes, the returned map is empty.

toJMXConnector

JMXConnector toJMXConnector(Map<String,?> env)
                            throws IOException

Returns a client stub for this connector server. A client stub is a serializable object whose connect method can be used to make one new connection to this connector server.

A given connector need not support the generation of client stubs. However, the connectors specified by the JMX Remote API do (JMXMP Connector and RMI Connector).

Parameters:
env - client connection parameters of the same sort that can be provided to JMXConnector.connect(Map). Can be null, which is equivalent to an empty map.
Returns:
a client stub that can be used to make a new connection to this connector server.
Throws:
UnsupportedOperationException - if this connector server does not support the generation of client stubs.
IllegalStateException - if the JMXConnectorServer is not started (see isActive()).
IOException - if a communications problem means that a stub cannot be created.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMXConnectorServerProvider

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Interface JMXConnectorServerProvider

public interface JMXConnectorServerProvider

A provider for creating JMX API connector servers using a given protocol. Instances of this interface are created by JMXConnectorServerFactory as part of its newJMXConnectorServer method.

Since:
1.5

Method Summary
 JMXConnectorServer newJMXConnectorServer(JMXServiceURL serviceURL, Map<String,?> environment, MBeanServer mbeanServer)
Creates a new connector server at the given address.

Method Detail

newJMXConnectorServer

JMXConnectorServer newJMXConnectorServer(JMXServiceURL serviceURL,
                                         Map<String,?> environment,
                                         MBeanServer mbeanServer)
                                         throws IOException

Creates a new connector server at the given address. Each successful call to this method produces a different JMXConnectorServer object.

Parameters:
serviceURL - the address of the new connector server. The actual address of the new connector server, as returned by its getAddress method, will not necessarily be exactly the same. For example, it might include a port number if the original address did not.
environment - a read-only Map containing named attributes to control the new connector server's behavior. Keys in this map must be Strings. The appropriate type of each associated value depends on the attribute.
mbeanServer - the MBean server that this connector server is attached to. Null if this connector server will be attached to an MBean server by being registered in it.
Returns:
a JMXConnectorServer representing the new connector server. Each successful call to this method produces a different object.
Throws:
NullPointerException - if serviceURL or environment is null.
IOException - It is recommended for a provider implementation to throw MalformedURLException if the protocol in the serviceURL is not recognized by this provider, JMXProviderException if this is a provider for the protocol in serviceURL but it cannot be used for some reason or any other IOException if the connector server cannot be created.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMXPrincipal

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Class JMXPrincipal

java.lang.Object
    extended by  javax.management.remote.JMXPrincipal
All Implemented Interfaces:
Serializable, Principal
public class JMXPrincipal
extends Object
implements Principal, Serializable

The identity of a remote client of the JMX Remote API.

Principals such as this JMXPrincipal may be associated with a particular Subject to augment that Subject with an additional identity. Refer to the Subject class for more information on how to achieve this. Authorization decisions can then be based upon the Principals associated with a Subject.

Since:
1.5
See Also:
Principal, Subject, Serialized Form

Constructor Summary
JMXPrincipal(String name)
Creates a JMXPrincipal for a given identity.
Method Summary
boolean | equals(Object o) Compares the specified Object with this JMXPrincipal for equality.
String | getName() Returns the name of this principal.
int | hashCode() Returns a hash code for this JMXPrincipal.
String | toString() Returns a string representation of this JMXPrincipal.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JMXPrincipal

public JMXPrincipal(String name)

Creates a JMXPrincipal for a given identity.

Parameters:
name - the JMX Remote API name for this identity.
Throws:
NullPointerException - if the name is null.
Method Detail

getName

public String getName()
Returns the name of this principal.

Specified by:
getName in interface Principal
Returns:
the name of this JMXPrincipal.

toString

public String toString()
Returns a string representation of this JMXPrincipal.

Specified by:
toString in interface Principal
Overrides:
toString in class Object
Returns:
a string representation of this JMXPrincipal.

equals

public boolean equals(Object o)
Compares the specified Object with this JMXPrincipal for equality. Returns true if the given object is also a JMXPrincipal and the two JMXPrincipals have the same name.

Specified by:
equals in interface Principal
Overrides:
equals in class Object
Parameters:
o - Object to be compared for equality with this JMXPrincipal.
Returns:
true if the specified Object is equal to this JMXPrincipal.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns a hash code for this JMXPrincipal.

Specified by:
hashCode in interface Principal
Overrides:
hashCode in class Object
Returns:
a hash code for this JMXPrincipal.
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMXProviderException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Class JMXProviderException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.io.IOException
                extended by  javax.management.remote.JMXProviderException
All Implemented Interfaces:
Serializable
public class JMXProviderException
extends IOException

Exception thrown by JMXConnectorFactory and JMXConnectorServerFactory when a provider exists for the required protocol but cannot be used for some reason.

Since:
1.5
See Also:
JMXConnectorFactory.newJMXConnector(javax.management.remote.JMXServiceURL, java.util.Map), JMXConnectorServerFactory.newJMXConnectorServer(javax.management.remote.JMXServiceURL, java.util.Map, javax.management.MBeanServer), Serialized Form

Constructor Summary
JMXProviderException()
Constructs a JMXProviderException with no specified detail message.
JMXProviderException(String message)
Constructs a JMXProviderException with the specified detail message.
JMXProviderException(String message, Throwable cause)
Constructs a JMXProviderException with the specified detail message and nested exception.
Method Summary
 Throwable getCause()
Returns the cause of this throwable or null if the cause is nonexistent or unknown.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JMXProviderException

public JMXProviderException()

Constructs a JMXProviderException with no specified detail message.

JMXProviderException

public JMXProviderException(String message)

Constructs a JMXProviderException with the specified detail message.

Parameters:
message - the detail message

JMXProviderException

public JMXProviderException(String message,
                            Throwable cause)

Constructs a JMXProviderException with the specified detail message and nested exception.

Parameters:
message - the detail message
cause - the nested exception
Method Detail

getCause

public Throwable getCause()
Description copied from class: Throwable
Returns the cause of this throwable or null if the cause is nonexistent or unknown. (The cause is the throwable that caused this throwable to get thrown.)

This implementation returns the cause that was supplied via one of the constructors requiring a Throwable, or that was set after creation with the Throwable.initCause(Throwable) method. While it is typically unnecessary to override this method, a subclass can override it to return a cause set by some other means. This is appropriate for a "legacy chained throwable" that predates the addition of chained exceptions to Throwable. Note that it is not necessary to override any of the PrintStackTrace methods, all of which invoke the getCause method to determine the cause of a throwable.

Overrides:
getCause in class Throwable
Returns:
the cause of this throwable or null if the cause is nonexistent or unknown.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMXServerErrorException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Class JMXServerErrorException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.io.IOException
                extended by  javax.management.remote.JMXServerErrorException
All Implemented Interfaces:
Serializable
public class JMXServerErrorException
extends IOException

Exception thrown as the result of a remote MBeanServer method invocation when an Error is thrown while processing the invocation in the remote MBean server. A JMXServerErrorException instance contains the original Error that occurred as its cause.

Since:
1.5
See Also:
ServerError, Serialized Form

Constructor Summary
JMXServerErrorException(String s, Error err)
Constructs a JMXServerErrorException with the specified detail message and nested error.
Method Summary
 Throwable getCause()
Returns the cause of this throwable or null if the cause is nonexistent or unknown.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JMXServerErrorException

public JMXServerErrorException(String s,
                               Error err)
Constructs a JMXServerErrorException with the specified detail message and nested error.

Parameters:
s - the detail message.
err - the nested error. An instance of this class can be constructed where this parameter is null, but the standard connectors will never do so.
Method Detail

getCause

public Throwable getCause()
Description copied from class: Throwable
Returns the cause of this throwable or null if the cause is nonexistent or unknown. (The cause is the throwable that caused this throwable to get thrown.)

This implementation returns the cause that was supplied via one of the constructors requiring a Throwable, or that was set after creation with the Throwable.initCause(Throwable) method. While it is typically unnecessary to override this method, a subclass can override it to return a cause set by some other means. This is appropriate for a "legacy chained throwable" that predates the addition of chained exceptions to Throwable. Note that it is not necessary to override any of the PrintStackTrace methods, all of which invoke the getCause method to determine the cause of a throwable.

Overrides:
getCause in class Throwable
Returns:
the cause of this throwable or null if the cause is nonexistent or unknown.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMXServiceURL

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Class JMXServiceURL

java.lang.Object
    extended by  javax.management.remote.JMXServiceURL
All Implemented Interfaces:
Serializable
public class JMXServiceURL
extends Object
implements Serializable

The address of a JMX API connector server. Instances of this class are immutable.

The address is an Abstract Service URL for SLP, as defined in RFC 2609 and amended by RFC 3111. It must look like this:

service:jmx:protocol:sap

Here, protocol is the transport protocol to be used to connect to the connector server. It is a string of one or more ASCII characters, each of which is a letter, a digit, or one of the characters + or -. The first character must be a letter. Uppercase letters are converted into lowercase ones.

sap is the address at which the connector server is found. This address uses a subset of the syntax defined by RFC 2609 for IP-based protocols. It is a subset because the user@host syntax is not supported.

The other syntaxes defined by RFC 2609 are not currently supported by this class.

The supported syntax is:

//[host[:port]][url-path]

Square brackets [] indicate optional parts of the address. Not all protocols will recognize all optional parts.

The host is a host name, an IPv4 numeric host address, or an IPv6 numeric address enclosed in square brackets.

The port is a decimal port number. 0 means a default or anonymous port, depending on the protocol.

The host and port can be omitted. The port cannot be supplied without a host.

The url-path, if any, begins with a slash (/) or a semicolon (;) and continues to the end of the address. It can contain attributes using the semicolon syntax specified in RFC 2609. Those attributes are not parsed by this class and incorrect attribute syntax is not detected.

Although it is legal according to RFC 2609 to have a url-path that begins with a semicolon, not all implementations of SLP allow it, so it is recommended to avoid that syntax.

Case is not significant in the initial service:jmx:protocol string or in the host part of the address. Depending on the protocol, case can be significant in the url-path.

Since:
1.5
See Also:
RFC 2609, "Service Templates and Service: Schemes", RFC 3111, "Service Location Protocol Modifications for IPv6", Serialized Form

Constructor Summary
JMXServiceURL(String serviceURL)
Constructs a JMXServiceURL by parsing a Service URL string.
JMXServiceURL(String protocol, String host, int port)
Constructs a JMXServiceURL with the given protocol, host, and port.
JMXServiceURL(String protocol, String host, int port, String urlPath)
Constructs a JMXServiceURL with the given parts.
Method Summary
boolean | equals(Object obj) Indicates whether some other object is equal to this one.
String | getHost() The host part of the Service URL.
int | getPort() The port of the Service URL.
String | getProtocol() The protocol part of the Service URL.
String | getURLPath() The URL Path part of the Service URL.
int | hashCode() Returns a hash code value for the object.
String | toString() The string representation of this Service URL.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JMXServiceURL

public JMXServiceURL(String serviceURL)
              throws MalformedURLException

Constructs a JMXServiceURL by parsing a Service URL string.

Parameters:
serviceURL - the URL string to be parsed.
Throws:
NullPointerException - if serviceURL is null.
MalformedURLException - if serviceURL does not conform to the syntax for an Abstract Service URL or if it is not a valid name for a JMX Remote API service. A JMXServiceURL must begin with the string "service:jmx:" (case-insensitive). It must not contain any characters that are not printable ASCII characters.

JMXServiceURL

public JMXServiceURL(String protocol,
                     String host,
                     int port)
              throws MalformedURLException

Constructs a JMXServiceURL with the given protocol, host, and port. This constructor is equivalent to JMXServiceURL(protocol, host, port, null).

Parameters:
protocol - the protocol part of the URL. If null, defaults to jmxmp.
host - the host part of the URL. If null, defaults to the local host name, as determined by InetAddress.getLocalHost().getHostName(). If it is a numeric IPv6 address, it can optionally be enclosed in square brackets [].
port - the port part of the URL.
Throws:
MalformedURLException - if one of the parts is syntactically incorrect, or if host is null and it is not possible to find the local host name, or if port is negative.

JMXServiceURL

public JMXServiceURL(String protocol,
                     String host,
                     int port,
                     String urlPath)
              throws MalformedURLException

Constructs a JMXServiceURL with the given parts.

Parameters:
protocol - the protocol part of the URL. If null, defaults to jmxmp.
host - the host part of the URL. If null, defaults to the local host name, as determined by InetAddress.getLocalHost().getHostName(). If it is a numeric IPv6 address, it can optionally be enclosed in square brackets [].
port - the port part of the URL.
urlPath - the URL path part of the URL. If null, defaults to the empty string.
Throws:
MalformedURLException - if one of the parts is syntactically incorrect, or if host is null and it is not possible to find the local host name, or if port is negative.
Method Detail

getProtocol

public String getProtocol()

The protocol part of the Service URL.

Returns:
the protocol part of the Service URL. This is never null.

getHost

public String getHost()

The host part of the Service URL. If the Service URL was constructed with the constructor that takes a URL string parameter, the result is the substring specifying the host in that URL. If the Service URL was constructed with a constructor that takes a separate host parameter, the result is the string that was specified. If that string was null, the result is InetAddress.getLocalHost().getHostName().

In either case, if the host was specified using the [...] syntax for numeric IPv6 addresses, the square brackets are not included in the return value here.

Returns:
the host part of the Service URL. This is never null.

getPort

public int getPort()

The port of the Service URL. If no port was specified, the returned value is 0.

Returns:
the port of the Service URL, or 0 if none.

getURLPath

public String getURLPath()

The URL Path part of the Service URL. This is an empty string, or a string beginning with a slash (/), or a string beginning with a semicolon (;).

Returns:
the URL Path part of the Service URL. This is never null.

toString

public String toString()

The string representation of this Service URL. If the value returned by this method is supplied to the JMXServiceURL constructor, the resultant object is equal to this one.

The host part of the returned string is the value returned by getHost(). If that value specifies a numeric IPv6 address, it is surrounded by square brackets [].

The port part of the returned string is the value returned by getPort() in its shortest decimal form. If the value is zero, it is omitted.

Overrides:
toString in class Object
Returns:
the string representation of this Service URL.

equals

public boolean equals(Object obj)

Indicates whether some other object is equal to this one. This method returns true if and only if obj is an instance of JMXServiceURL whose getProtocol(), getHost(), getPort(), and getURLPath() methods return the same values as for this object. The values for getProtocol() and getHost() can differ in case without affecting equality.

Overrides:
equals in class Object
Parameters:
obj - the reference object with which to compare.
Returns:
true if this object is the same as the obj argument; false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Description copied from class: Object
Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the Object.equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MBeanServerForwarder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Interface MBeanServerForwarder

All Superinterfaces:
MBeanServer, MBeanServerConnection
public interface MBeanServerForwarder
extends MBeanServer

An object of this class implements the MBeanServer interface and wraps another object that also implements that interface. Typically, an implementation of this interface performs some action in some or all methods of the MBeanServer interface before and/or after forwarding the method to the wrapped object. Examples include security checking and logging.

Since:
1.5

Method Summary
MBeanServer | getMBeanServer() Returns the MBeanServer object to which requests will be forwarded.
void | setMBeanServer(MBeanServer mbs) Sets the MBeanServer object to which requests will be forwarded after treatment by this object.
Methods inherited from interface javax.management.MBeanServer
addNotificationListener, addNotificationListener, createMBean, createMBean, createMBean, createMBean, deserialize, deserialize, deserialize, getAttribute, getAttributes, getClassLoader, getClassLoaderFor, getClassLoaderRepository, getDefaultDomain, getDomains, getMBeanCount, getMBeanInfo, getObjectInstance, instantiate, instantiate, instantiate, instantiate, invoke, isInstanceOf, isRegistered, queryMBeans, queryNames, registerMBean, removeNotificationListener, removeNotificationListener, removeNotificationListener, removeNotificationListener, setAttribute, setAttributes, unregisterMBean

Method Detail

getMBeanServer

MBeanServer getMBeanServer()
Returns the MBeanServer object to which requests will be forwarded.

Returns:
the MBeanServer object to which requests will be forwarded, or null if there is none.
See Also:
setMBeanServer(javax.management.MBeanServer)

setMBeanServer

void setMBeanServer(MBeanServer mbs)
Sets the MBeanServer object to which requests will be forwarded after treatment by this object.

Parameters:
mbs - the MBeanServer object to which requests will be forwarded.
Throws:
IllegalArgumentException - if this object is already forwarding to an MBeanServer object or if mbs is null or if mbs is identical to this object.
See Also:
getMBeanServer()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotificationResult

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Class NotificationResult

java.lang.Object
    extended by  javax.management.remote.NotificationResult
All Implemented Interfaces:
Serializable
public class NotificationResult
extends Object
implements Serializable

Result of a query for buffered notifications. Notifications in a notification buffer have positive, monotonically increasing sequence numbers. The result of a notification query contains the following elements:

  • The sequence number of the earliest notification still in the buffer.
  • The sequence number of the next notification available for querying. This will be the starting sequence number for the next notification query.
  • An array of (Notification,listenerID) pairs corresponding to the returned notifications and the listeners they correspond to.

It is possible for the nextSequenceNumber to be less than the earliestSequenceNumber. This signifies that notifications between the two might have been lost.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
NotificationResult(long earliestSequenceNumber, long nextSequenceNumber, TargetedNotification[] targetedNotifications)
Constructs a notification query result.
Method Summary
long | getEarliestSequenceNumber() Returns the sequence number of the earliest notification still in the buffer.
long | getNextSequenceNumber() Returns the sequence number of the next notification available for querying.
TargetedNotification[] | getTargetedNotifications() Returns the notifications resulting from the query, and the listeners they correspond to.
String | toString() Returns a string representation of the object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NotificationResult

public NotificationResult(long earliestSequenceNumber,
                          long nextSequenceNumber,
                          TargetedNotification[] targetedNotifications)

Constructs a notification query result.

Parameters:
earliestSequenceNumber - the sequence number of the earliest notification still in the buffer.
nextSequenceNumber - the sequence number of the next notification available for querying.
targetedNotifications - the notifications resulting from the query, and the listeners they correspond to. This array can be empty.
Throws:
IllegalArgumentException - if targetedNotifications is null or if earliestSequenceNumber or nextSequenceNumber is negative.
Method Detail

getEarliestSequenceNumber

public long getEarliestSequenceNumber()
Returns the sequence number of the earliest notification still in the buffer.

Returns:
the sequence number of the earliest notification still in the buffer.

getNextSequenceNumber

public long getNextSequenceNumber()
Returns the sequence number of the next notification available for querying.

Returns:
the sequence number of the next notification available for querying.

getTargetedNotifications

public TargetedNotification[] getTargetedNotifications()
Returns the notifications resulting from the query, and the listeners they correspond to.

Returns:
the notifications resulting from the query, and the listeners they correspond to. This array can be empty.

toString

public String toString()
Returns a string representation of the object. The result should be a concise but informative representation that is easy for a person to read.

Overrides:
toString in class Object
Returns:
a string representation of the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


rmi

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.management.remote.rmi

The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server.

See:
Description

Interface Summary
RMIConnection | RMI object used to forward an MBeanServer request from a client to its MBeanServer implementation on the server side.
RMIServer | RMI object used to establish connections to an RMI connector.

Class Summary
RMIConnectionImpl | Implementation of the RMIConnection interface.
RMIConnectionImpl_Stub |
RMIConnector | A connection to a remote RMI connector.
RMIConnectorServer | A JMX API connector server that creates RMI-based connections from remote clients.
RMIIIOPServerImpl | An RMIServerImpl that is exported through IIOP and that creates client connections as RMI objects exported through IIOP.
RMIJRMPServerImpl | An RMIServer object that is exported through JRMP and that creates client connections as RMI objects exported through JRMP.
RMIServerImpl | An RMI object representing a connector server.
RMIServerImpl_Stub |

Package javax.management.remote.rmi Description

The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server. This package defines the classes that the user of an RMI connector needs to reference directly, for both the client and server sides. It also defines certain classes that the user will not usually reference directly, but that must be defined so that different implementations of the RMI connector can interoperate.

The RMI connector supports both the JRMP and the IIOP transports for RMI.

Like most connectors in the JMX Remote API, an RMI connector usually has an address, which is a JMXServiceURL. The protocol part of this address is rmi for a connector that uses the default RMI transport (JRMP), or iiop for a connector that uses RMI/IIOP.

There are two forms for RMI connector addresses:

  • In the JNDI form, the URL indicates where to find an RMI stub for the connector. This RMI stub is a Java object of type RMIServer that gives remote access to the connector server. With this address form, the RMI stub is obtained from an external directory entry included in the URL. An external directory is any directory recognized by JNDI, typically the RMI registry, LDAP, or COS Naming.
  • In the encoded form, the URL directly includes the information needed to connect to the connector server. When using RMI/JRMP, the encoded form is the serialized RMI stub for the server object, encoded using BASE64 without embedded newlines. When using RMI/IIOP, the encoded form is the CORBA IOR for the server object.

Addresses are covered in more detail below.

Creating an RMI connector server

The usual way to create an RMI connector server is to supply an RMI connector address to the method JMXConnectorServerFactory.newJMXConnectorServer. The MBean server to which the connector server is attached can be specified as a parameter to that method. Alternatively, the connector server can be registered as an MBean in that MBean server.

An RMI connector server can also be created by constructing an instance of RMIConnectorServer, explicitly or through the MBean server's createMBean method.

Choosing the RMI transport

You can choose the RMI transport (JRMP or IIOP) by specifying rmi or iiop in the protocol part of the serviceURL when creating the connector server. You can also create specialised connector servers by instantiating an appropriate subclass of RMIServerImpl and supplying it to the RMIConnectorServer constructor.

Connector addresses generated by the server

If the serviceURL you specify has an empty URL path (after the optional host and port), or if you do not specify a serviceURL, then the connector server will fabricate a new JMXServiceURL that clients can use to connect:

  • If the serviceURL looks like:

            service:jmx:rmi://host:port

    then the connector server will generate an RMIJRMPServerImpl and the returned JMXServiceURL looks like:

            service:jmx:rmi://host:port/stub/XXXX

    where XXXX is the serialized form of the stub for the generated object, encoded in BASE64 without newlines.

  • If the serviceURL looks like:

            service:jmx:iiop://host:port

    then the connector server will generate an RMIIIOPServerImpl and the returned JMXServiceURL looks like:

            service:jmx:iiop://host:port/ior/IOR:XXXX

    where IOR:XXXX is the standard CORBA encoding of the Interoperable Object Reference for the generated object.

  • If there is no serviceURL, there must be a user-provided RMIServerImpl. If the toStub method on this object returns an instance of Stub, then the connector server will generate a JMXServiceURL using the iiop form above. Otherwise, it will generate a JMXServiceURL using the rmi form.

The host in a user-provided serviceURL is optional. If present, it is copied into the generated JMXServiceURL but otherwise ignored. If absent, the generated JXMServiceURL will have the local host name.

The port in a user-provided serviceURL is also optional. If present, it is also copied into the generated JMXServiceURL; otherwise, the generated JMXServiceURL has no port. For an serviceURL using the rmi protocol, the port, if present, indicates what port the generated remote object should be exported on. It has no other effect.

If the user provides an RMIServerImpl rather than a JMXServiceURL, then the generated JMXServiceURL will have the local host name in its host part and no port.

Connector addresses based on directory entries

As an alternative to the generated addresses just described, the serviceURL address supplied when creating a connector server can specify a directory address in which to store the provided or generated RMIServer stub. This directory address is then used by both client and server.

In this case, the serviceURL has one of these two forms:

    service:jmx:rmi://host:port/jndi/jndi-name
    service:jmx:iiop://host:port/jndi/jndi-name

Here, jndi-name is a string that can be supplied to javax.naming.InitialContext.bind.

As usual, the host and :port can be omitted.

The connector server will generate an RMIServerImpl based on the protocol (rmi or iiop) and, for rmi, the port if any. When the connector server is started, it will derive a stub from this object using its toStub method and store the object using the given jndi-name. The properties defined by the JNDI API are consulted as usual.

For example, if the JMXServiceURL is:

      service:jmx:rmi://ignoredhost/jndi/rmi://myhost/myname
then the connector server will generate an RMIJRMPServerImpl and store its stub using the JNDI name
      rmi://myhost/myname
which means entry myname in the RMI registry running on the default port of host myhost. Note that the RMI registry only allows registration from the local host. So, in this case, myhost must be the name (or a name) of the host that the connector server is running on.

In this JMXServiceURL, the first rmi: specifies the RMI connector, while the second rmi: specifies the RMI registry.

As another example, if the JMXServiceURL is:

      service:jmx:iiop://ignoredhost/jndi/ldap://dirhost:9999/cn=this,ou=that
then the connector server will generate an RMIIIOPServerImpl and store its stub using the JNDI name
      ldap://dirhost:9999/cn=this,ou=that
which means entry cn=this,ou=that in the LDAP directory running on port 9999 of host dirhost.

If the JMXServiceURL is:

      service:jmx:iiop://ignoredhost/jndi/cn=this,ou=that
then the connector server will generate an RMIIIOPServerImpl and store its stub using the JNDI name
      cn=this,ou=that
For this case to work, the JNDI API must have been configured appropriately to supply the information about what directory to use.

In these examples, the host name ignoredhost is not used by the connector server or its clients. It can be omitted, for example:

      service:jmx:iiop:///jndi/cn=this,ou=that

However, it is good practice to use the name of the host where the connector server is running. This is often different from the name of the directory host.

Connector server attributes

When using the default JRMP transport, RMI socket factories can be specified using the attributes jmx.remote.rmi.client.socket.factory and jmx.remote.rmi.server.socket.factory in the environment given to the RMIConnectorServer constructor. The values of these attributes must be of type RMIClientSocketFactory and RMIServerSocketFactory, respectively. These factories are used when creating the RMI objects associated with the connector.

Creating an RMI connector client

An RMI connector client is usually constructed using JMXConnectorFactory, with a JMXServiceURL that has rmi or iiop as its protocol.

If the JMXServiceURL was generated by the server, as described above under "connector addresses generated by the server", then the client will need to obtain it directly or indirectly from the server. Typically, the server makes the JMXServiceURL available by storing it in a file or a lookup service.

If the JMXServiceURL uses the directory syntax, as described above under "connector addresses based on directory entries", then the client may obtain it as just explained, or client and server may both know the appropriate directory entry to use. For example, if the connector server for the Whatsit agent uses the entry whatsit-agent-connector in the RMI registry on host myhost, then client and server can both know that the appropriate JMXServiceURL is:

    service:jmx:rmi:///jndi/rmi://myhost/whatsit-agent-connector

If you have an RMI stub of type RMIServer, you can construct an RMI connection directly by using the appropriate constructor of RMIConnector.

Specifying an ORB for the RMI/IIOP connector

When using the IIOP transport, the client and server can specify what ORB to use with the attribute java.naming.corba.orb. Connection to the ORB happens at start time for the connector server, and at connect time for the connector client. If the java.naming.corba.orb attribute is contained in the environment Map, then its value (an ORB), is used to connect the IIOP Stubs. Otherwise, a new org.omg.CORBA.ORB is created by calling org.omg.CORBA.ORB.init((String[])null,(Properties)null). A later RMI connector client or server in the same JVM can reuse this ORB, or it can create another one in the same way.

If the java.naming.corba.orb attribute is specified and does not point to an ORB, then an IllegalArgumentException will be thrown.

The mechanism described here does not apply when the IIOP Remote objects (Stubs or Servers) are created and connected to an ORB manually before being passed to the RMIConnector and RMIConnectorServer.

Dynamic code downloading

If an RMI connector client or server receives from its peer an instance of a class that it does not know, and if dynamic code downloading is active for the RMI connection, then the class can be downloaded from a codebase specified by the peer. The article Dynamic code downloading using Java RMI explains this in more detail.

Since:
1.5
See Also:
JavaTM Remote Method Invocation (RMI), Java Naming and Directory InterfaceTM (JNDI), RFC 2045, section 6.8, "Base64 Content-Transfer-Encoding"
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.management.remote.rmi Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.management.remote.rmi

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.management.NotificationBroadcasterSupport (implements javax.management.NotificationEmitter)
      • javax.management.remote.JMXConnectorServer (implements javax.management.remote.JMXAddressable, javax.management.remote.JMXConnectorServerMBean, javax.management.MBeanRegistration)
        • javax.management.remote.rmi.RMIConnectorServer
    • java.rmi.server.RemoteObject (implements java.rmi.Remote, java.io.Serializable)
      • java.rmi.server.RemoteStub
        • javax.management.remote.rmi.RMIConnectionImpl_Stub (implements javax.management.remote.rmi.RMIConnection)
        • javax.management.remote.rmi.RMIServerImpl_Stub (implements javax.management.remote.rmi.RMIServer)
    • javax.management.remote.rmi.RMIConnectionImpl (implements javax.management.remote.rmi.RMIConnection, java.rmi.server.Unreferenced)
    • javax.management.remote.rmi.RMIConnector (implements javax.management.remote.JMXAddressable, javax.management.remote.JMXConnector, java.io.Serializable)
    • javax.management.remote.rmi.RMIServerImpl (implements java.io.Closeable, javax.management.remote.rmi.RMIServer)
      • javax.management.remote.rmi.RMIIIOPServerImpl
      • javax.management.remote.rmi.RMIJRMPServerImpl

Interface Hierarchy

  • java.io.Closeable
    • javax.management.remote.rmi.RMIConnection (also extends java.rmi.Remote)
  • java.rmi.Remote
    • javax.management.remote.rmi.RMIConnection (also extends java.io.Closeable)
    • javax.management.remote.rmi.RMIServer
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.management.remote.rmi

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.management.remote.rmi

Packages that use javax.management.remote.rmi
javax.management.remote.rmi The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server.

Classes in javax.management.remote.rmi used by javax.management.remote.rmi
RMIConnection
RMI object used to forward an MBeanServer request from a client to its MBeanServer implementation on the server side.
RMIServer
RMI object used to establish connections to an RMI connector.
RMIServerImpl
An RMI object representing a connector server.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.rmi.RMIConnectionImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.rmi.RMIConnectionImpl

No usage of javax.management.remote.rmi.RMIConnectionImpl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.rmi.RMIConnectionImpl_Stub

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.rmi.RMIConnectionImpl_Stub

No usage of javax.management.remote.rmi.RMIConnectionImpl_Stub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.rmi.RMIConnector

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.rmi.RMIConnector

No usage of javax.management.remote.rmi.RMIConnector

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.rmi.RMIConnectorServer

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.rmi.RMIConnectorServer

No usage of javax.management.remote.rmi.RMIConnectorServer

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.rmi.RMIIIOPServerImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.rmi.RMIIIOPServerImpl

No usage of javax.management.remote.rmi.RMIIIOPServerImpl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.rmi.RMIJRMPServerImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.rmi.RMIJRMPServerImpl

No usage of javax.management.remote.rmi.RMIJRMPServerImpl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.rmi.RMIServerImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.rmi.RMIServerImpl

Packages that use RMIServerImpl
javax.management.remote.rmi The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server.

Uses of RMIServerImpl in javax.management.remote.rmi

Subclasses of RMIServerImpl in javax.management.remote.rmi
class | RMIIIOPServerImpl An RMIServerImpl that is exported through IIOP and that creates client connections as RMI objects exported through IIOP.
class | RMIJRMPServerImpl An RMIServer object that is exported through JRMP and that creates client connections as RMI objects exported through JRMP.

Constructors in javax.management.remote.rmi with parameters of type RMIServerImpl
RMIConnectionImpl(RMIServerImpl rmiServer, String connectionId, ClassLoader defaultClassLoader, Subject subject, Map<String,?> env)
Constructs a new RMIConnection.
RMIConnectorServer(JMXServiceURL url, Map<String,?> environment, RMIServerImpl rmiServerImpl, MBeanServer mbeanServer)
Makes an RMIConnectorServer for the given MBean server.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.remote.rmi.RMIServerImpl_Stub

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.remote.rmi.RMIServerImpl_Stub

No usage of javax.management.remote.rmi.RMIServerImpl_Stub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.remote.rmi.RMIConnection

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.remote.rmi.RMIConnection

Packages that use RMIConnection
javax.management.remote.rmi The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server.

Uses of RMIConnection in javax.management.remote.rmi

Classes in javax.management.remote.rmi that implement RMIConnection
class | RMIConnectionImpl Implementation of the RMIConnection interface.
class | RMIConnectionImpl_Stub

Methods in javax.management.remote.rmi that return RMIConnection
protected RMIConnection | RMIIIOPServerImpl.makeClient(String connectionId, Subject subject) Creates a new client connection as an RMI object exported through IIOP.
protected RMIConnection | RMIJRMPServerImpl.makeClient(String connectionId, Subject subject) Creates a new client connection as an RMI object exported through JRMP.
protected abstract RMIConnection | RMIServerImpl.makeClient(String connectionId, Subject subject) Creates a new client connection.
RMIConnection | RMIServerImpl_Stub.newClient(Object $param_Object_1)
RMIConnection | RMIServer.newClient(Object credentials) Makes a new connection through this RMI connector.
RMIConnection | RMIServerImpl.newClient(Object credentials) Creates a new client connection.

Methods in javax.management.remote.rmi with parameters of type RMIConnection
protected void | RMIServerImpl.clientClosed(RMIConnection client) Method called when a client connection created by makeClient is closed.
protected void | RMIIIOPServerImpl.closeClient(RMIConnection client)
protected void | RMIJRMPServerImpl.closeClient(RMIConnection client)
protected abstract void | RMIServerImpl.closeClient(RMIConnection client) Closes a client connection made by makeClient.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.remote.rmi.RMIServer

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.remote.rmi.RMIServer

Packages that use RMIServer
javax.management.remote.rmi The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server.

Uses of RMIServer in javax.management.remote.rmi

Classes in javax.management.remote.rmi that implement RMIServer
class | RMIIIOPServerImpl An RMIServerImpl that is exported through IIOP and that creates client connections as RMI objects exported through IIOP.
class | RMIJRMPServerImpl An RMIServer object that is exported through JRMP and that creates client connections as RMI objects exported through JRMP.
class | RMIServerImpl An RMI object representing a connector server.
class | RMIServerImpl_Stub

Constructors in javax.management.remote.rmi with parameters of type RMIServer
RMIConnector(RMIServer rmiServer, Map<String,?> environment)
Constructs an RMIConnector using the given RMI stub.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


RMIConnection

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.management.remote.rmi
Interface RMIConnection

All Superinterfaces:
Closeable, Remote
All Known Implementing Classes:
RMIConnectionImpl, RMIConnectionImpl_Stub
public interface RMIConnection
extends Closeable, Remote

RMI object used to forward an MBeanServer request from a client to its MBeanServer implementation on the server side. There is one Remote object implementing this interface for each remote client connected to an RMI connector.

User code does not usually refer to this interface. It is specified as part of the public API so that different implementations of that API will interoperate.

To ensure that client parameters will be deserialized at the server side with the correct classloader, client parameters such as parameters used to invoke a method are wrapped in a MarshalledObject. An implementation of this interface must first get the appropriate class loader for the operation and its target, then deserialize the marshalled parameters with this classloader. Except as noted, a parameter that is a MarshalledObject or MarshalledObject[] must not be null; the behavior is unspecified if it is.

Class loading aspects are detailed in the JMX Specification, version 1.4 PDF document.

Most methods in this interface parallel methods in the MBeanServerConnection interface. Where an aspect of the behavior of a method is not specified here, it is the same as in the corresponding MBeanServerConnection method.

Since:
1.5

Method Summary
 void addNotificationListener(ObjectName name, ObjectName listener, MarshalledObject filter, MarshalledObject handback, Subject delegationSubject)
Handles the method MBeanServerConnection.addNotificationListener(ObjectName, ObjectName, NotificationFilter, Object).
 Integer[] addNotificationListeners(ObjectName[] names, MarshalledObject[] filters, Subject[] delegationSubjects)
Handles the method MBeanServerConnection.addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object).
 void close()
Closes this connection.
 ObjectInstance createMBean(String className, ObjectName name, MarshalledObject params, String[] signature, Subject delegationSubject)
Handles the method MBeanServerConnection.createMBean(String, ObjectName, Object[], String[]).
 ObjectInstance createMBean(String className, ObjectName name, ObjectName loaderName, MarshalledObject params, String[] signature, Subject delegationSubject)
Handles the method MBeanServerConnection.createMBean(String, ObjectName, ObjectName, Object[], String[]).
 ObjectInstance createMBean(String className, ObjectName name, ObjectName loaderName, Subject delegationSubject)
Handles the method MBeanServerConnection.createMBean(String, ObjectName, ObjectName).
 ObjectInstance createMBean(String className, ObjectName name, Subject delegationSubject)
Handles the method MBeanServerConnection.createMBean(String, ObjectName).
 NotificationResult fetchNotifications(long clientSequenceNumber, int maxNotifications, long timeout)
Retrieves notifications from the connector server.
 Object getAttribute(ObjectName name, String attribute, Subject delegationSubject)
Handles the method MBeanServerConnection.getAttribute(ObjectName, String).
 AttributeList getAttributes(ObjectName name, String[] attributes, Subject delegationSubject)
Handles the method MBeanServerConnection.getAttributes(ObjectName, String[]).
 String getConnectionId()
Returns the connection ID.
 String getDefaultDomain(Subject delegationSubject)
Handles the method MBeanServerConnection.getDefaultDomain().
 String[] getDomains(Subject delegationSubject)
Handles the method MBeanServerConnection.getDomains().
 Integer getMBeanCount(Subject delegationSubject)
Handles the method MBeanServerConnection.getMBeanCount().
 MBeanInfo getMBeanInfo(ObjectName name, Subject delegationSubject)
Handles the method MBeanServerConnection.getMBeanInfo(ObjectName).
 ObjectInstance getObjectInstance(ObjectName name, Subject delegationSubject)
Handles the method MBeanServerConnection.getObjectInstance(ObjectName).
 Object invoke(ObjectName name, String operationName, MarshalledObject params, String[] signature, Subject delegationSubject)
Handles the method MBeanServerConnection.invoke(ObjectName, String, Object[], String[]).
 boolean isInstanceOf(ObjectName name, String className, Subject delegationSubject)
Handles the method MBeanServerConnection.isInstanceOf(ObjectName, String).
 boolean isRegistered(ObjectName name, Subject delegationSubject)
Handles the method MBeanServerConnection.isRegistered(ObjectName).
 Set<ObjectInstance> queryMBeans(ObjectName name, MarshalledObject query, Subject delegationSubject)
Handles the method MBeanServerConnection.queryMBeans(ObjectName, QueryExp).
 Set<ObjectName> queryNames(ObjectName name, MarshalledObject query, Subject delegationSubject)
Handles the method MBeanServerConnection.queryNames(ObjectName, QueryExp).
 void removeNotificationListener(ObjectName name, ObjectName listener, MarshalledObject filter, MarshalledObject handback, Subject delegationSubject)
Handles the method MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName, NotificationFilter, Object).
 void removeNotificationListener(ObjectName name, ObjectName listener, Subject delegationSubject)
Handles the method MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName).
 void removeNotificationListeners(ObjectName name, Integer[] listenerIDs, Subject delegationSubject)
Handles the removeNotificationListener(ObjectName, NotificationListener) and removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object) methods.
 void setAttribute(ObjectName name, MarshalledObject attribute, Subject delegationSubject)
Handles the method MBeanServerConnection.setAttribute(ObjectName, Attribute).
 AttributeList setAttributes(ObjectName name, MarshalledObject attributes, Subject delegationSubject)
Handles the method MBeanServerConnection.setAttributes(ObjectName, AttributeList).
 void unregisterMBean(ObjectName name, Subject delegationSubject)
Handles the method MBeanServerConnection.unregisterMBean(ObjectName).

Method Detail

getConnectionId

String getConnectionId()
                       throws IOException

Returns the connection ID. This string is different for every open connection to a given RMI connector server.

Returns:
the connection ID
Throws:
IOException - if a general communication exception occurred.
See Also:
RMIConnector.connect

close

void close()
           throws IOException

Closes this connection. On return from this method, the RMI object implementing this interface is unexported, so further remote calls to it will fail.

Specified by:
close in interface Closeable
Throws:
IOException - if the connection could not be closed, or the Remote object could not be unexported, or there was a communication failure when transmitting the remote close request.

createMBean

ObjectInstance createMBean(String className,
                           ObjectName name,
                           Subject delegationSubject)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException,
                                  IOException
Handles the method MBeanServerConnection.createMBean(String, ObjectName).

Parameters:
className - The class name of the MBean to be instantiated.
name - The object name of the MBean. May be null.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception.
NotCompliantMBeanException - This class is not a JMX compliant MBean.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The className passed in parameter is null, the ObjectName passed in parameter contains a pattern or no ObjectName is specified for the MBean.
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.

createMBean

ObjectInstance createMBean(String className,
                           ObjectName name,
                           ObjectName loaderName,
                           Subject delegationSubject)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException,
                                  InstanceNotFoundException,
                                  IOException
Handles the method MBeanServerConnection.createMBean(String, ObjectName, ObjectName).

Parameters:
className - The class name of the MBean to be instantiated.
name - The object name of the MBean. May be null.
loaderName - The object name of the class loader to be used.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception.
NotCompliantMBeanException - This class is not a JMX compliant MBean.
InstanceNotFoundException - The specified class loader is not registered in the MBean server.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The className passed in parameter is null, the ObjectName passed in parameter contains a pattern or no ObjectName is specified for the MBean.
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.

createMBean

ObjectInstance createMBean(String className,
                           ObjectName name,
                           MarshalledObject params,
                           String[] signature,
                           Subject delegationSubject)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException,
                                  IOException
Handles the method MBeanServerConnection.createMBean(String, ObjectName, Object[], String[]). The Object[] parameter is wrapped in a MarshalledObject.

Parameters:
className - The class name of the MBean to be instantiated.
name - The object name of the MBean. May be null.
params - An array containing the parameters of the constructor to be invoked, encapsulated into a MarshalledObject. The encapsulated array can be null, equivalent to an empty array.
signature - An array containing the signature of the constructor to be invoked. Can be null, equivalent to an empty array.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception.
NotCompliantMBeanException - This class is not a JMX compliant MBean.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The className passed in parameter is null, the ObjectName passed in parameter contains a pattern, or no ObjectName is specified for the MBean.
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.

createMBean

ObjectInstance createMBean(String className,
                           ObjectName name,
                           ObjectName loaderName,
                           MarshalledObject params,
                           String[] signature,
                           Subject delegationSubject)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException,
                                  InstanceNotFoundException,
                                  IOException
Handles the method MBeanServerConnection.createMBean(String, ObjectName, ObjectName, Object[], String[]). The Object[] parameter is wrapped in a MarshalledObject.

Parameters:
className - The class name of the MBean to be instantiated.
name - The object name of the MBean. May be null.
loaderName - The object name of the class loader to be used.
params - An array containing the parameters of the constructor to be invoked, encapsulated into a MarshalledObject. The encapsulated array can be null, equivalent to an empty array.
signature - An array containing the signature of the constructor to be invoked. Can be null, equivalent to an empty array.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception.
NotCompliantMBeanException - This class is not a JMX compliant MBean.
InstanceNotFoundException - The specified class loader is not registered in the MBean server.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The className passed in parameter is null, the ObjectName passed in parameter contains a pattern, or no ObjectName is specified for the MBean.
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.

unregisterMBean

void unregisterMBean(ObjectName name,
                     Subject delegationSubject)
                     throws InstanceNotFoundException,
                            MBeanRegistrationException,
                            IOException
Handles the method MBeanServerConnection.unregisterMBean(ObjectName).

Parameters:
name - The object name of the MBean to be unregistered.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
MBeanRegistrationException - The preDeregister ((MBeanRegistration interface) method of the MBean has thrown an exception.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object name in parameter is null or the MBean you are when trying to unregister is the MBeanServerDelegate MBean.
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.

getObjectInstance

ObjectInstance getObjectInstance(ObjectName name,
                                 Subject delegationSubject)
                                 throws InstanceNotFoundException,
                                        IOException
Handles the method MBeanServerConnection.getObjectInstance(ObjectName).

Parameters:
name - The object name of the MBean.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
The ObjectInstance associated with the MBean specified by name. The contained ObjectName is name and the contained class name is getMBeanInfo(name).getClassName().
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object name in parameter is null.
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.

queryMBeans

Set<ObjectInstance> queryMBeans(ObjectName name,
                                MarshalledObject query,
                                Subject delegationSubject)
                                throws IOException
Handles the method MBeanServerConnection.queryMBeans(ObjectName, QueryExp). The QueryExp is wrapped in a MarshalledObject.

Parameters:
name - The object name pattern identifying the MBeans to be retrieved. If null or no domain and key properties are specified, all the MBeans registered will be retrieved.
query - The query expression to be applied for selecting MBeans, encapsulated into a MarshalledObject. If the MarshalledObject encapsulates a null value no query expression will be applied for selecting MBeans.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
A set containing the ObjectInstance objects for the selected MBeans. If no MBean satisfies the query an empty list is returned.
Throws:
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.

queryNames

Set<ObjectName> queryNames(ObjectName name,
                           MarshalledObject query,
                           Subject delegationSubject)
                           throws IOException
Handles the method MBeanServerConnection.queryNames(ObjectName, QueryExp). The QueryExp is wrapped in a MarshalledObject.

Parameters:
name - The object name pattern identifying the MBean names to be retrieved. If null or no domain and key properties are specified, the name of all registered MBeans will be retrieved.
query - The query expression to be applied for selecting MBeans, encapsulated into a MarshalledObject. If the MarshalledObject encapsulates a null value no query expression will be applied for selecting MBeans.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
A set containing the ObjectNames for the MBeans selected. If no MBean satisfies the query, an empty list is returned.
Throws:
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.

isRegistered

boolean isRegistered(ObjectName name,
                     Subject delegationSubject)
                     throws IOException
Handles the method MBeanServerConnection.isRegistered(ObjectName).

Parameters:
name - The object name of the MBean to be checked.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
True if the MBean is already registered in the MBean server, false otherwise.
Throws:
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object name in parameter is null.
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.

getMBeanCount

Integer getMBeanCount(Subject delegationSubject)
                      throws IOException
Handles the method MBeanServerConnection.getMBeanCount().

Parameters:
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
the number of MBeans registered.
Throws:
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.

getAttribute

Object getAttribute(ObjectName name,
                    String attribute,
                    Subject delegationSubject)
                    throws MBeanException,
                           AttributeNotFoundException,
                           InstanceNotFoundException,
                           ReflectionException,
                           IOException
Handles the method MBeanServerConnection.getAttribute(ObjectName, String).

Parameters:
name - The object name of the MBean from which the attribute is to be retrieved.
attribute - A String specifying the name of the attribute to be retrieved.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
The value of the retrieved attribute.
Throws:
AttributeNotFoundException - The attribute specified is not accessible in the MBean.
MBeanException - Wraps an exception thrown by the MBean's getter.
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
ReflectionException - Wraps a java.lang.Exception thrown when trying to invoke the getter.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object name in parameter is null or the attribute in parameter is null.
RuntimeMBeanException - Wraps a runtime exception thrown by the MBean's getter.
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.
See Also:
setAttribute(javax.management.ObjectName, java.rmi.MarshalledObject, javax.security.auth.Subject)

getAttributes

AttributeList getAttributes(ObjectName name,
                            String[] attributes,
                            Subject delegationSubject)
                            throws InstanceNotFoundException,
                                   ReflectionException,
                                   IOException
Handles the method MBeanServerConnection.getAttributes(ObjectName, String[]).

Parameters:
name - The object name of the MBean from which the attributes are retrieved.
attributes - A list of the attributes to be retrieved.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
The list of the retrieved attributes.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
ReflectionException - An exception occurred when trying to invoke the getAttributes method of a Dynamic MBean.
RuntimeOperationsException - Wrap a java.lang.IllegalArgumentException: The object name in parameter is null or attributes in parameter is null.
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.
See Also:
setAttributes(javax.management.ObjectName, java.rmi.MarshalledObject, javax.security.auth.Subject)

setAttribute

void setAttribute(ObjectName name,
                  MarshalledObject attribute,
                  Subject delegationSubject)
                  throws InstanceNotFoundException,
                         AttributeNotFoundException,
                         InvalidAttributeValueException,
                         MBeanException,
                         ReflectionException,
                         IOException
Handles the method MBeanServerConnection.setAttribute(ObjectName, Attribute). The Attribute parameter is wrapped in a MarshalledObject.

Parameters:
name - The name of the MBean within which the attribute is to be set.
attribute - The identification of the attribute to be set and the value it is to be set to, encapsulated into a MarshalledObject.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
AttributeNotFoundException - The attribute specified is not accessible in the MBean.
InvalidAttributeValueException - The value specified for the attribute is not valid.
MBeanException - Wraps an exception thrown by the MBean's setter.
ReflectionException - Wraps a java.lang.Exception thrown when trying to invoke the setter.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object name in parameter is null or the attribute in parameter is null.
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.
See Also:
getAttribute(javax.management.ObjectName, java.lang.String, javax.security.auth.Subject)

setAttributes

AttributeList setAttributes(ObjectName name,
                            MarshalledObject attributes,
                            Subject delegationSubject)
                            throws InstanceNotFoundException,
                                   ReflectionException,
                                   IOException
Handles the method MBeanServerConnection.setAttributes(ObjectName, AttributeList). The AttributeList parameter is wrapped in a MarshalledObject.

Parameters:
name - The object name of the MBean within which the attributes are to be set.
attributes - A list of attributes: The identification of the attributes to be set and the values they are to be set to, encapsulated into a MarshalledObject.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
The list of attributes that were set, with their new values.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
ReflectionException - An exception occurred when trying to invoke the getAttributes method of a Dynamic MBean.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object name in parameter is null or attributes in parameter is null.
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.
See Also:
getAttributes(javax.management.ObjectName, java.lang.String[], javax.security.auth.Subject)

invoke

Object invoke(ObjectName name,
              String operationName,
              MarshalledObject params,
              String[] signature,
              Subject delegationSubject)
              throws InstanceNotFoundException,
                     MBeanException,
                     ReflectionException,
                     IOException
Handles the method MBeanServerConnection.invoke(ObjectName, String, Object[], String[]). The Object[] parameter is wrapped in a MarshalledObject.

Parameters:
name - The object name of the MBean on which the method is to be invoked.
operationName - The name of the operation to be invoked.
params - An array containing the parameters to be set when the operation is invoked, encapsulated into a MarshalledObject. The encapsulated array can be null, equivalent to an empty array.
signature - An array containing the signature of the operation. The class objects will be loaded using the same class loader as the one used for loading the MBean on which the operation was invoked. Can be null, equivalent to an empty array.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
The object returned by the operation, which represents the result of invoking the operation on the MBean specified.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
MBeanException - Wraps an exception thrown by the MBean's invoked method.
ReflectionException - Wraps a java.lang.Exception thrown while trying to invoke the method.
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.
RuntimeOperationsException - Wraps an IllegalArgumentException when name or operationName is null.

getDefaultDomain

String getDefaultDomain(Subject delegationSubject)
                        throws IOException
Handles the method MBeanServerConnection.getDefaultDomain().

Parameters:
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
the default domain.
Throws:
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.

getDomains

String[] getDomains(Subject delegationSubject)
                    throws IOException
Handles the method MBeanServerConnection.getDomains().

Parameters:
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
the list of domains.
Throws:
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.

getMBeanInfo

MBeanInfo getMBeanInfo(ObjectName name,
                       Subject delegationSubject)
                       throws InstanceNotFoundException,
                              IntrospectionException,
                              ReflectionException,
                              IOException
Handles the method MBeanServerConnection.getMBeanInfo(ObjectName).

Parameters:
name - The name of the MBean to analyze
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
An instance of MBeanInfo allowing the retrieval of all attributes and operations of this MBean.
Throws:
IntrospectionException - An exception occurred during introspection.
InstanceNotFoundException - The MBean specified was not found.
ReflectionException - An exception occurred when trying to invoke the getMBeanInfo of a Dynamic MBean.
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object name in parameter is null.

isInstanceOf

boolean isInstanceOf(ObjectName name,
                     String className,
                     Subject delegationSubject)
                     throws InstanceNotFoundException,
                            IOException
Handles the method MBeanServerConnection.isInstanceOf(ObjectName, String).

Parameters:
name - The ObjectName of the MBean.
className - The name of the class.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
true if the MBean specified is an instance of the specified class according to the rules above, false otherwise.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.
RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object name in parameter is null.

addNotificationListener

void addNotificationListener(ObjectName name,
                             ObjectName listener,
                             MarshalledObject filter,
                             MarshalledObject handback,
                             Subject delegationSubject)
                             throws InstanceNotFoundException,
                                    IOException
Handles the method MBeanServerConnection.addNotificationListener(ObjectName, ObjectName, NotificationFilter, Object). The NotificationFilter parameter is wrapped in a MarshalledObject. The Object (handback) parameter is also wrapped in a MarshalledObject.

Parameters:
name - The name of the MBean on which the listener should be added.
listener - The object name of the listener which will handle the notifications emitted by the registered MBean.
filter - The filter object, encapsulated into a MarshalledObject. If filter encapsulated in the MarshalledObject has a null value, no filtering will be performed before handling notifications.
handback - The context to be sent to the listener when a notification is emitted, encapsulated into a MarshalledObject.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
InstanceNotFoundException - The MBean name of the notification listener or of the notification broadcaster does not match any of the registered MBeans.
RuntimeOperationsException - Wraps an IllegalArgumentException. The MBean named by listener exists but does not implement the NotificationListener interface, or name or listener is null.
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.
See Also:
removeNotificationListener(ObjectName, ObjectName, Subject), removeNotificationListener(ObjectName, ObjectName, MarshalledObject, MarshalledObject, Subject)

removeNotificationListener

void removeNotificationListener(ObjectName name,
                                ObjectName listener,
                                Subject delegationSubject)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException,
                                       IOException
Handles the method MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName).

Parameters:
name - The name of the MBean on which the listener should be removed.
listener - The object name of the listener to be removed.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.
ListenerNotFoundException - The listener is not registered in the MBean.
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.
RuntimeOperationsException - Wraps an IllegalArgumentException when name or listener is null.
See Also:
addNotificationListener(javax.management.ObjectName, javax.management.ObjectName, java.rmi.MarshalledObject, java.rmi.MarshalledObject, javax.security.auth.Subject)

removeNotificationListener

void removeNotificationListener(ObjectName name,
                                ObjectName listener,
                                MarshalledObject filter,
                                MarshalledObject handback,
                                Subject delegationSubject)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException,
                                       IOException
Handles the method MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName, NotificationFilter, Object). The NotificationFilter parameter is wrapped in a MarshalledObject. The Object parameter is also wrapped in a MarshalledObject.

Parameters:
name - The name of the MBean on which the listener should be removed.
listener - A listener that was previously added to this MBean.
filter - The filter that was specified when the listener was added, encapsulated into a MarshalledObject.
handback - The handback that was specified when the listener was added, encapsulated into a MarshalledObject.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.
ListenerNotFoundException - The listener is not registered in the MBean, or it is not registered with the given filter and handback.
SecurityException - if the client, or the delegated Subject if any, does not have permission to perform this operation.
IOException - if a general communication exception occurred.
RuntimeOperationsException - Wraps an IllegalArgumentException when name or listener is null.
See Also:
addNotificationListener(javax.management.ObjectName, javax.management.ObjectName, java.rmi.MarshalledObject, java.rmi.MarshalledObject, javax.security.auth.Subject)

addNotificationListeners

Integer[] addNotificationListeners(ObjectName[] names,
                                   MarshalledObject[] filters,
                                   Subject[] delegationSubjects)
                                   throws InstanceNotFoundException,
                                          IOException

Handles the method MBeanServerConnection.addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object).

Register for notifications from the given MBeans that match the given filters. The remote client can subsequently retrieve the notifications using the fetchNotifications method.

For each listener, the original NotificationListener and handback are kept on the client side; in order for the client to be able to identify them, the server generates and returns a unique listenerID. This listenerID is forwarded with the Notifications to the remote client.

If any one of the given (name, filter) pairs cannot be registered, then the operation fails with an exception, and no names or filters are registered.

Parameters:
names - the ObjectNames identifying the MBeans emitting the Notifications.
filters - an array of marshalled representations of the NotificationFilters. Elements of this array can be null.
delegationSubjects - the Subjects on behalf of which the listeners are being added. Elements of this array can be null. Also, the delegationSubjects parameter itself can be null, which is equivalent to an array of null values with the same size as the names and filters arrays.
Returns:
an array of listenerIDs identifying the local listeners. This array has the same number of elements as the parameters.
Throws:
IllegalArgumentException - if names or filters is null, or if names contains a null element, or if the three arrays do not all have the same size.
ClassCastException - if one of the elements of filters unmarshalls as a non-null object that is not a NotificationFilter.
InstanceNotFoundException - if one of the names does not correspond to any registered MBean.
SecurityException - if, for one of the MBeans, the client, or the delegated Subject if any, does not have permission to add a listener.
IOException - if a general communication exception occurred.

removeNotificationListeners

void removeNotificationListeners(ObjectName name,
                                 Integer[] listenerIDs,
                                 Subject delegationSubject)
                                 throws InstanceNotFoundException,
                                        ListenerNotFoundException,
                                        IOException

Handles the removeNotificationListener(ObjectName, NotificationListener) and removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object) methods.

This method removes one or more NotificationListeners from a given MBean in the MBean server.

The NotificationListeners are identified by the IDs which were returned by the addNotificationListeners(ObjectName[], MarshalledObject[], Subject[]) method.

Parameters:
name - the ObjectName identifying the MBean emitting the Notifications.
listenerIDs - the list of the IDs corresponding to the listeners to remove.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
InstanceNotFoundException - if the given name does not correspond to any registered MBean.
ListenerNotFoundException - if one of the listeners was not found on the server side. This exception can happen if the MBean discarded a listener for some reason other than a call to MBeanServer.removeNotificationListener.
SecurityException - if the client, or the delegated Subject if any, does not have permission to remove the listeners.
IOException - if a general communication exception occurred.
IllegalArgumentException - if ObjectName or listenerIds is null or if listenerIds contains a null element.

fetchNotifications

NotificationResult fetchNotifications(long clientSequenceNumber,
                                      int maxNotifications,
                                      long timeout)
                                      throws IOException

Retrieves notifications from the connector server. This method can block until there is at least one notification or until the specified timeout is reached. The method can also return at any time with zero notifications.

A notification can be included in the result if its sequence number is no less than clientSequenceNumber and this client has registered at least one listener for the MBean generating the notification, with a filter that accepts the notification. Each listener that is interested in the notification is identified by an Integer ID that was returned by addNotificationListeners(ObjectName[], MarshalledObject[], Subject[]).

Parameters:
clientSequenceNumber - the first sequence number that the client is interested in. If negative, it is interpreted as meaning the sequence number that the next notification will have.
maxNotifications - the maximum number of different notifications to return. The TargetedNotification array in the returned NotificationResult can have more elements than this if the same notification appears more than once. The behavior is unspecified if this parameter is negative.
timeout - the maximum time in milliseconds to wait for a notification to arrive. This can be 0 to indicate that the method should not wait if there are no notifications, but should return at once. It can be Long.MAX_VALUE to indicate that there is no timeout. The behavior is unspecified if this parameter is negative.
Returns:
A NotificationResult.
Throws:
IOException - if a general communication exception occurred.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


RMIConnectionImpl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote.rmi
Class RMIConnectionImpl

java.lang.Object
    extended by  javax.management.remote.rmi.RMIConnectionImpl
All Implemented Interfaces:
Closeable, Remote, Unreferenced, RMIConnection
public class RMIConnectionImpl
extends Object
implements RMIConnection, Unreferenced

Implementation of the RMIConnection interface. User code will not usually reference this class.

Since:
1.5

Constructor Summary
RMIConnectionImpl(RMIServerImpl rmiServer, String connectionId, ClassLoader defaultClassLoader, Subject subject, Map<String,?> env)
Constructs a new RMIConnection.
Method Summary
 void addNotificationListener(ObjectName name, ObjectName listener, MarshalledObject filter, MarshalledObject handback, Subject delegationSubject)
Handles the method MBeanServerConnection.addNotificationListener(ObjectName, ObjectName, NotificationFilter, Object).
 Integer[] addNotificationListeners(ObjectName[] names, MarshalledObject[] filters, Subject[] delegationSubjects)
Handles the method MBeanServerConnection.addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object).
 void close()
Closes this connection.
 ObjectInstance createMBean(String className, ObjectName name, MarshalledObject params, String[] signature, Subject delegationSubject)
Handles the method MBeanServerConnection.createMBean(String, ObjectName, Object[], String[]).
 ObjectInstance createMBean(String className, ObjectName name, ObjectName loaderName, MarshalledObject params, String[] signature, Subject delegationSubject)
Handles the method MBeanServerConnection.createMBean(String, ObjectName, ObjectName, Object[], String[]).
 ObjectInstance createMBean(String className, ObjectName name, ObjectName loaderName, Subject delegationSubject)
Handles the method MBeanServerConnection.createMBean(String, ObjectName, ObjectName).
 ObjectInstance createMBean(String className, ObjectName name, Subject delegationSubject)
Handles the method MBeanServerConnection.createMBean(String, ObjectName).
 NotificationResult fetchNotifications(long clientSequenceNumber, int maxNotifications, long timeout)
Retrieves notifications from the connector server.
 Object getAttribute(ObjectName name, String attribute, Subject delegationSubject)
Handles the method MBeanServerConnection.getAttribute(ObjectName, String).
 AttributeList getAttributes(ObjectName name, String[] attributes, Subject delegationSubject)
Handles the method MBeanServerConnection.getAttributes(ObjectName, String[]).
 String getConnectionId()
Returns the connection ID.
 String getDefaultDomain(Subject delegationSubject)
Handles the method MBeanServerConnection.getDefaultDomain().
 String[] getDomains(Subject delegationSubject)
Handles the method MBeanServerConnection.getDomains().
 Integer getMBeanCount(Subject delegationSubject)
Handles the method MBeanServerConnection.getMBeanCount().
 MBeanInfo getMBeanInfo(ObjectName name, Subject delegationSubject)
Handles the method MBeanServerConnection.getMBeanInfo(ObjectName).
 ObjectInstance getObjectInstance(ObjectName name, Subject delegationSubject)
Handles the method MBeanServerConnection.getObjectInstance(ObjectName).
 Object invoke(ObjectName name, String operationName, MarshalledObject params, String[] signature, Subject delegationSubject)
Handles the method MBeanServerConnection.invoke(ObjectName, String, Object[], String[]).
 boolean isInstanceOf(ObjectName name, String className, Subject delegationSubject)
Handles the method MBeanServerConnection.isInstanceOf(ObjectName, String).
 boolean isRegistered(ObjectName name, Subject delegationSubject)
Handles the method MBeanServerConnection.isRegistered(ObjectName).
 Set<ObjectInstance> queryMBeans(ObjectName name, MarshalledObject query, Subject delegationSubject)
Handles the method MBeanServerConnection.queryMBeans(ObjectName, QueryExp).
 Set<ObjectName> queryNames(ObjectName name, MarshalledObject query, Subject delegationSubject)
Handles the method MBeanServerConnection.queryNames(ObjectName, QueryExp).
 void removeNotificationListener(ObjectName name, ObjectName listener, MarshalledObject filter, MarshalledObject handback, Subject delegationSubject)
Handles the method MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName, NotificationFilter, Object).
 void removeNotificationListener(ObjectName name, ObjectName listener, Subject delegationSubject)
Handles the method MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName).
 void removeNotificationListeners(ObjectName name, Integer[] listenerIDs, Subject delegationSubject)
Handles the removeNotificationListener(ObjectName, NotificationListener) and removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object) methods.
 void setAttribute(ObjectName name, MarshalledObject attribute, Subject delegationSubject)
Handles the method MBeanServerConnection.setAttribute(ObjectName, Attribute).
 AttributeList setAttributes(ObjectName name, MarshalledObject attributes, Subject delegationSubject)
Handles the method MBeanServerConnection.setAttributes(ObjectName, AttributeList).
 String toString()
Returns a string representation of this object.
 void unreferenced()
Called by the RMI runtime sometime after the runtime determines that the reference list, the list of clients referencing the remote object, becomes empty.
 void unregisterMBean(ObjectName name, Subject delegationSubject)
Handles the method MBeanServerConnection.unregisterMBean(ObjectName).
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RMIConnectionImpl

public RMIConnectionImpl(RMIServerImpl rmiServer,
                         String connectionId,
                         ClassLoader defaultClassLoader,
                         Subject subject,
                         Map<String,?> env)
Constructs a new RMIConnection. This connection can be used with either the JRMP or IIOP transport. This object does not export itself: it is the responsibility of the caller to export it appropriately (see RMIJRMPServerImpl.makeClient(String,Subject) and RMIIIOPServerImpl.makeClient(String,Subject).

Parameters:
rmiServer - The RMIServerImpl object for which this connection is created. The behavior is unspecified if this parameter is null.
connectionId - The ID for this connection. The behavior is unspecified if this parameter is null.
defaultClassLoader - The default ClassLoader to be used when deserializing marshalled objects. Can be null, to signify the bootstrap class loader.
subject - the authenticated subject to be used for authorization. Can be null, to signify that no subject has been authenticated.
env - the environment containing attributes for the new RMIServerImpl. Can be null, equivalent to an empty map.
Method Detail

getConnectionId

public String getConnectionId()
                       throws IOException
Description copied from interface: RMIConnection

Returns the connection ID. This string is different for every open connection to a given RMI connector server.

Specified by:
getConnectionId in interface RMIConnection
Returns:
the connection ID
Throws:
IOException - if a general communication exception occurred.
See Also:
RMIConnector.connect

close

public void close()
           throws IOException
Description copied from interface: RMIConnection

Closes this connection. On return from this method, the RMI object implementing this interface is unexported, so further remote calls to it will fail.

Specified by:
close in interface Closeable
Specified by:
close in interface RMIConnection
Throws:
IOException - if the connection could not be closed, or the Remote object could not be unexported, or there was a communication failure when transmitting the remote close request.

unreferenced

public void unreferenced()
Description copied from interface: Unreferenced
Called by the RMI runtime sometime after the runtime determines that the reference list, the list of clients referencing the remote object, becomes empty.

Specified by:
unreferenced in interface Unreferenced

createMBean

public ObjectInstance createMBean(String className,
                                  ObjectName name,
                                  Subject delegationSubject)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException,
                                  IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.createMBean(String, ObjectName).

Specified by:
createMBean in interface RMIConnection
Parameters:
className - The class name of the MBean to be instantiated.
name - The object name of the MBean. May be null.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception.
NotCompliantMBeanException - This class is not a JMX compliant MBean.
IOException - if a general communication exception occurred.

createMBean

public ObjectInstance createMBean(String className,
                                  ObjectName name,
                                  ObjectName loaderName,
                                  Subject delegationSubject)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException,
                                  InstanceNotFoundException,
                                  IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.createMBean(String, ObjectName, ObjectName).

Specified by:
createMBean in interface RMIConnection
Parameters:
className - The class name of the MBean to be instantiated.
name - The object name of the MBean. May be null.
loaderName - The object name of the class loader to be used.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception.
NotCompliantMBeanException - This class is not a JMX compliant MBean.
InstanceNotFoundException - The specified class loader is not registered in the MBean server.
IOException - if a general communication exception occurred.

createMBean

public ObjectInstance createMBean(String className,
                                  ObjectName name,
                                  MarshalledObject params,
                                  String[] signature,
                                  Subject delegationSubject)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException,
                                  IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.createMBean(String, ObjectName, Object[], String[]). The Object[] parameter is wrapped in a MarshalledObject.

Specified by:
createMBean in interface RMIConnection
Parameters:
className - The class name of the MBean to be instantiated.
name - The object name of the MBean. May be null.
params - An array containing the parameters of the constructor to be invoked, encapsulated into a MarshalledObject. The encapsulated array can be null, equivalent to an empty array.
signature - An array containing the signature of the constructor to be invoked. Can be null, equivalent to an empty array.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception.
NotCompliantMBeanException - This class is not a JMX compliant MBean.
IOException - if a general communication exception occurred.

createMBean

public ObjectInstance createMBean(String className,
                                  ObjectName name,
                                  ObjectName loaderName,
                                  MarshalledObject params,
                                  String[] signature,
                                  Subject delegationSubject)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException,
                                  InstanceNotFoundException,
                                  IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.createMBean(String, ObjectName, ObjectName, Object[], String[]). The Object[] parameter is wrapped in a MarshalledObject.

Specified by:
createMBean in interface RMIConnection
Parameters:
className - The class name of the MBean to be instantiated.
name - The object name of the MBean. May be null.
loaderName - The object name of the class loader to be used.
params - An array containing the parameters of the constructor to be invoked, encapsulated into a MarshalledObject. The encapsulated array can be null, equivalent to an empty array.
signature - An array containing the signature of the constructor to be invoked. Can be null, equivalent to an empty array.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception.
NotCompliantMBeanException - This class is not a JMX compliant MBean.
InstanceNotFoundException - The specified class loader is not registered in the MBean server.
IOException - if a general communication exception occurred.

unregisterMBean

public void unregisterMBean(ObjectName name,
                            Subject delegationSubject)
                     throws InstanceNotFoundException,
                            MBeanRegistrationException,
                            IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.unregisterMBean(ObjectName).

Specified by:
unregisterMBean in interface RMIConnection
Parameters:
name - The object name of the MBean to be unregistered.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
MBeanRegistrationException - The preDeregister ((MBeanRegistration interface) method of the MBean has thrown an exception.
IOException - if a general communication exception occurred.

getObjectInstance

public ObjectInstance getObjectInstance(ObjectName name,
                                        Subject delegationSubject)
                                 throws InstanceNotFoundException,
                                        IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.getObjectInstance(ObjectName).

Specified by:
getObjectInstance in interface RMIConnection
Parameters:
name - The object name of the MBean.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
The ObjectInstance associated with the MBean specified by name. The contained ObjectName is name and the contained class name is getMBeanInfo(name).getClassName().
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
IOException - if a general communication exception occurred.

queryMBeans

public Set<ObjectInstance> queryMBeans(ObjectName name,
                                       MarshalledObject query,
                                       Subject delegationSubject)
                                throws IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.queryMBeans(ObjectName, QueryExp). The QueryExp is wrapped in a MarshalledObject.

Specified by:
queryMBeans in interface RMIConnection
Parameters:
name - The object name pattern identifying the MBeans to be retrieved. If null or no domain and key properties are specified, all the MBeans registered will be retrieved.
query - The query expression to be applied for selecting MBeans, encapsulated into a MarshalledObject. If the MarshalledObject encapsulates a null value no query expression will be applied for selecting MBeans.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
A set containing the ObjectInstance objects for the selected MBeans. If no MBean satisfies the query an empty list is returned.
Throws:
IOException - if a general communication exception occurred.

queryNames

public Set<ObjectName> queryNames(ObjectName name,
                                  MarshalledObject query,
                                  Subject delegationSubject)
                           throws IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.queryNames(ObjectName, QueryExp). The QueryExp is wrapped in a MarshalledObject.

Specified by:
queryNames in interface RMIConnection
Parameters:
name - The object name pattern identifying the MBean names to be retrieved. If null or no domain and key properties are specified, the name of all registered MBeans will be retrieved.
query - The query expression to be applied for selecting MBeans, encapsulated into a MarshalledObject. If the MarshalledObject encapsulates a null value no query expression will be applied for selecting MBeans.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
A set containing the ObjectNames for the MBeans selected. If no MBean satisfies the query, an empty list is returned.
Throws:
IOException - if a general communication exception occurred.

isRegistered

public boolean isRegistered(ObjectName name,
                            Subject delegationSubject)
                     throws IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.isRegistered(ObjectName).

Specified by:
isRegistered in interface RMIConnection
Parameters:
name - The object name of the MBean to be checked.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
True if the MBean is already registered in the MBean server, false otherwise.
Throws:
IOException - if a general communication exception occurred.

getMBeanCount

public Integer getMBeanCount(Subject delegationSubject)
                      throws IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.getMBeanCount().

Specified by:
getMBeanCount in interface RMIConnection
Parameters:
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
the number of MBeans registered.
Throws:
IOException - if a general communication exception occurred.

getAttribute

public Object getAttribute(ObjectName name,
                           String attribute,
                           Subject delegationSubject)
                    throws MBeanException,
                           AttributeNotFoundException,
                           InstanceNotFoundException,
                           ReflectionException,
                           IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.getAttribute(ObjectName, String).

Specified by:
getAttribute in interface RMIConnection
Parameters:
name - The object name of the MBean from which the attribute is to be retrieved.
attribute - A String specifying the name of the attribute to be retrieved.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
The value of the retrieved attribute.
Throws:
MBeanException - Wraps an exception thrown by the MBean's getter.
AttributeNotFoundException - The attribute specified is not accessible in the MBean.
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
ReflectionException - Wraps a java.lang.Exception thrown when trying to invoke the getter.
IOException - if a general communication exception occurred.
See Also:
RMIConnection.setAttribute(javax.management.ObjectName, java.rmi.MarshalledObject, javax.security.auth.Subject)

getAttributes

public AttributeList getAttributes(ObjectName name,
                                   String[] attributes,
                                   Subject delegationSubject)
                            throws InstanceNotFoundException,
                                   ReflectionException,
                                   IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.getAttributes(ObjectName, String[]).

Specified by:
getAttributes in interface RMIConnection
Parameters:
name - The object name of the MBean from which the attributes are retrieved.
attributes - A list of the attributes to be retrieved.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
The list of the retrieved attributes.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
ReflectionException - An exception occurred when trying to invoke the getAttributes method of a Dynamic MBean.
IOException - if a general communication exception occurred.
See Also:
RMIConnection.setAttributes(javax.management.ObjectName, java.rmi.MarshalledObject, javax.security.auth.Subject)

setAttribute

public void setAttribute(ObjectName name,
                         MarshalledObject attribute,
                         Subject delegationSubject)
                  throws InstanceNotFoundException,
                         AttributeNotFoundException,
                         InvalidAttributeValueException,
                         MBeanException,
                         ReflectionException,
                         IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.setAttribute(ObjectName, Attribute). The Attribute parameter is wrapped in a MarshalledObject.

Specified by:
setAttribute in interface RMIConnection
Parameters:
name - The name of the MBean within which the attribute is to be set.
attribute - The identification of the attribute to be set and the value it is to be set to, encapsulated into a MarshalledObject.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
AttributeNotFoundException - The attribute specified is not accessible in the MBean.
InvalidAttributeValueException - The value specified for the attribute is not valid.
MBeanException - Wraps an exception thrown by the MBean's setter.
ReflectionException - Wraps a java.lang.Exception thrown when trying to invoke the setter.
IOException - if a general communication exception occurred.
See Also:
RMIConnection.getAttribute(javax.management.ObjectName, java.lang.String, javax.security.auth.Subject)

setAttributes

public AttributeList setAttributes(ObjectName name,
                                   MarshalledObject attributes,
                                   Subject delegationSubject)
                            throws InstanceNotFoundException,
                                   ReflectionException,
                                   IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.setAttributes(ObjectName, AttributeList). The AttributeList parameter is wrapped in a MarshalledObject.

Specified by:
setAttributes in interface RMIConnection
Parameters:
name - The object name of the MBean within which the attributes are to be set.
attributes - A list of attributes: The identification of the attributes to be set and the values they are to be set to, encapsulated into a MarshalledObject.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
The list of attributes that were set, with their new values.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
ReflectionException - An exception occurred when trying to invoke the getAttributes method of a Dynamic MBean.
IOException - if a general communication exception occurred.
See Also:
RMIConnection.getAttributes(javax.management.ObjectName, java.lang.String[], javax.security.auth.Subject)

invoke

public Object invoke(ObjectName name,
                     String operationName,
                     MarshalledObject params,
                     String[] signature,
                     Subject delegationSubject)
              throws InstanceNotFoundException,
                     MBeanException,
                     ReflectionException,
                     IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.invoke(ObjectName, String, Object[], String[]). The Object[] parameter is wrapped in a MarshalledObject.

Specified by:
invoke in interface RMIConnection
Parameters:
name - The object name of the MBean on which the method is to be invoked.
operationName - The name of the operation to be invoked.
params - An array containing the parameters to be set when the operation is invoked, encapsulated into a MarshalledObject. The encapsulated array can be null, equivalent to an empty array.
signature - An array containing the signature of the operation. The class objects will be loaded using the same class loader as the one used for loading the MBean on which the operation was invoked. Can be null, equivalent to an empty array.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
The object returned by the operation, which represents the result of invoking the operation on the MBean specified.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
MBeanException - Wraps an exception thrown by the MBean's invoked method.
ReflectionException - Wraps a java.lang.Exception thrown while trying to invoke the method.
IOException - if a general communication exception occurred.

getDefaultDomain

public String getDefaultDomain(Subject delegationSubject)
                        throws IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.getDefaultDomain().

Specified by:
getDefaultDomain in interface RMIConnection
Parameters:
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
the default domain.
Throws:
IOException - if a general communication exception occurred.

getDomains

public String[] getDomains(Subject delegationSubject)
                    throws IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.getDomains().

Specified by:
getDomains in interface RMIConnection
Parameters:
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
the list of domains.
Throws:
IOException - if a general communication exception occurred.

getMBeanInfo

public MBeanInfo getMBeanInfo(ObjectName name,
                              Subject delegationSubject)
                       throws InstanceNotFoundException,
                              IntrospectionException,
                              ReflectionException,
                              IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.getMBeanInfo(ObjectName).

Specified by:
getMBeanInfo in interface RMIConnection
Parameters:
name - The name of the MBean to analyze
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
An instance of MBeanInfo allowing the retrieval of all attributes and operations of this MBean.
Throws:
InstanceNotFoundException - The MBean specified was not found.
IntrospectionException - An exception occurred during introspection.
ReflectionException - An exception occurred when trying to invoke the getMBeanInfo of a Dynamic MBean.
IOException - if a general communication exception occurred.

isInstanceOf

public boolean isInstanceOf(ObjectName name,
                            String className,
                            Subject delegationSubject)
                     throws InstanceNotFoundException,
                            IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.isInstanceOf(ObjectName, String).

Specified by:
isInstanceOf in interface RMIConnection
Parameters:
name - The ObjectName of the MBean.
className - The name of the class.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
true if the MBean specified is an instance of the specified class according to the rules above, false otherwise.
Throws:
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
IOException - if a general communication exception occurred.

addNotificationListeners

public Integer[] addNotificationListeners(ObjectName[] names,
                                          MarshalledObject[] filters,
                                          Subject[] delegationSubjects)
                                   throws InstanceNotFoundException,
                                          IOException
Description copied from interface: RMIConnection

Handles the method MBeanServerConnection.addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object).

Register for notifications from the given MBeans that match the given filters. The remote client can subsequently retrieve the notifications using the fetchNotifications method.

For each listener, the original NotificationListener and handback are kept on the client side; in order for the client to be able to identify them, the server generates and returns a unique listenerID. This listenerID is forwarded with the Notifications to the remote client.

If any one of the given (name, filter) pairs cannot be registered, then the operation fails with an exception, and no names or filters are registered.

Specified by:
addNotificationListeners in interface RMIConnection
Parameters:
names - the ObjectNames identifying the MBeans emitting the Notifications.
filters - an array of marshalled representations of the NotificationFilters. Elements of this array can be null.
delegationSubjects - the Subjects on behalf of which the listeners are being added. Elements of this array can be null. Also, the delegationSubjects parameter itself can be null, which is equivalent to an array of null values with the same size as the names and filters arrays.
Returns:
an array of listenerIDs identifying the local listeners. This array has the same number of elements as the parameters.
Throws:
InstanceNotFoundException - if one of the names does not correspond to any registered MBean.
IOException - if a general communication exception occurred.

addNotificationListener

public void addNotificationListener(ObjectName name,
                                    ObjectName listener,
                                    MarshalledObject filter,
                                    MarshalledObject handback,
                                    Subject delegationSubject)
                             throws InstanceNotFoundException,
                                    IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.addNotificationListener(ObjectName, ObjectName, NotificationFilter, Object). The NotificationFilter parameter is wrapped in a MarshalledObject. The Object (handback) parameter is also wrapped in a MarshalledObject.

Specified by:
addNotificationListener in interface RMIConnection
Parameters:
name - The name of the MBean on which the listener should be added.
listener - The object name of the listener which will handle the notifications emitted by the registered MBean.
filter - The filter object, encapsulated into a MarshalledObject. If filter encapsulated in the MarshalledObject has a null value, no filtering will be performed before handling notifications.
handback - The context to be sent to the listener when a notification is emitted, encapsulated into a MarshalledObject.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
InstanceNotFoundException - The MBean name of the notification listener or of the notification broadcaster does not match any of the registered MBeans.
IOException - if a general communication exception occurred.
See Also:
RMIConnection.removeNotificationListener(ObjectName, ObjectName, Subject), RMIConnection.removeNotificationListener(ObjectName, ObjectName, MarshalledObject, MarshalledObject, Subject)

removeNotificationListeners

public void removeNotificationListeners(ObjectName name,
                                        Integer[] listenerIDs,
                                        Subject delegationSubject)
                                 throws InstanceNotFoundException,
                                        ListenerNotFoundException,
                                        IOException
Description copied from interface: RMIConnection

Handles the removeNotificationListener(ObjectName, NotificationListener) and removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object) methods.

This method removes one or more NotificationListeners from a given MBean in the MBean server.

The NotificationListeners are identified by the IDs which were returned by the RMIConnection.addNotificationListeners(ObjectName[], MarshalledObject[], Subject[]) method.

Specified by:
removeNotificationListeners in interface RMIConnection
Parameters:
name - the ObjectName identifying the MBean emitting the Notifications.
listenerIDs - the list of the IDs corresponding to the listeners to remove.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
InstanceNotFoundException - if the given name does not correspond to any registered MBean.
ListenerNotFoundException - if one of the listeners was not found on the server side. This exception can happen if the MBean discarded a listener for some reason other than a call to MBeanServer.removeNotificationListener.
IOException - if a general communication exception occurred.

removeNotificationListener

public void removeNotificationListener(ObjectName name,
                                       ObjectName listener,
                                       Subject delegationSubject)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException,
                                       IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName).

Specified by:
removeNotificationListener in interface RMIConnection
Parameters:
name - The name of the MBean on which the listener should be removed.
listener - The object name of the listener to be removed.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.
ListenerNotFoundException - The listener is not registered in the MBean.
IOException - if a general communication exception occurred.
See Also:
RMIConnection.addNotificationListener(javax.management.ObjectName, javax.management.ObjectName, java.rmi.MarshalledObject, java.rmi.MarshalledObject, javax.security.auth.Subject)

removeNotificationListener

public void removeNotificationListener(ObjectName name,
                                       ObjectName listener,
                                       MarshalledObject filter,
                                       MarshalledObject handback,
                                       Subject delegationSubject)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException,
                                       IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName, NotificationFilter, Object). The NotificationFilter parameter is wrapped in a MarshalledObject. The Object parameter is also wrapped in a MarshalledObject.

Specified by:
removeNotificationListener in interface RMIConnection
Parameters:
name - The name of the MBean on which the listener should be removed.
listener - A listener that was previously added to this MBean.
filter - The filter that was specified when the listener was added, encapsulated into a MarshalledObject.
handback - The handback that was specified when the listener was added, encapsulated into a MarshalledObject.
delegationSubject - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.
ListenerNotFoundException - The listener is not registered in the MBean, or it is not registered with the given filter and handback.
IOException - if a general communication exception occurred.
See Also:
RMIConnection.addNotificationListener(javax.management.ObjectName, javax.management.ObjectName, java.rmi.MarshalledObject, java.rmi.MarshalledObject, javax.security.auth.Subject)

fetchNotifications

public NotificationResult fetchNotifications(long clientSequenceNumber,
                                             int maxNotifications,
                                             long timeout)
                                      throws IOException
Description copied from interface: RMIConnection

Retrieves notifications from the connector server. This method can block until there is at least one notification or until the specified timeout is reached. The method can also return at any time with zero notifications.

A notification can be included in the result if its sequence number is no less than clientSequenceNumber and this client has registered at least one listener for the MBean generating the notification, with a filter that accepts the notification. Each listener that is interested in the notification is identified by an Integer ID that was returned by RMIConnection.addNotificationListeners(ObjectName[], MarshalledObject[], Subject[]).

Specified by:
fetchNotifications in interface RMIConnection
Parameters:
clientSequenceNumber - the first sequence number that the client is interested in. If negative, it is interpreted as meaning the sequence number that the next notification will have.
maxNotifications - the maximum number of different notifications to return. The TargetedNotification array in the returned NotificationResult can have more elements than this if the same notification appears more than once. The behavior is unspecified if this parameter is negative.
timeout - the maximum time in milliseconds to wait for a notification to arrive. This can be 0 to indicate that the method should not wait if there are no notifications, but should return at once. It can be Long.MAX_VALUE to indicate that there is no timeout. The behavior is unspecified if this parameter is negative.
Returns:
A NotificationResult.
Throws:
IOException - if a general communication exception occurred.

toString

public String toString()

Returns a string representation of this object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read.

Overrides:
toString in class Object
Returns:
a String representation of this object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RMIConnectionImpl_Stub

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote.rmi
Class RMIConnectionImpl_Stub

java.lang.Object
    extended by  java.rmi.server.RemoteObject
        extended by  java.rmi.server.RemoteStub
            extended by  javax.management.remote.rmi.RMIConnectionImpl_Stub
All Implemented Interfaces:
Closeable, Serializable, Remote, RMIConnection
public final class RMIConnectionImpl_Stub
extends RemoteStub
implements RMIConnection

See Also:
Serialized Form

Field Summary
Fields inherited from class java.rmi.server.RemoteObject
ref
Constructor Summary
RMIConnectionImpl_Stub(RemoteRef ref)
Method Summary
 void addNotificationListener(ObjectName $param_ObjectName_1, ObjectName $param_ObjectName_2, MarshalledObject $param_MarshalledObject_3, MarshalledObject $param_MarshalledObject_4, Subject $param_Subject_5)
Handles the method MBeanServerConnection.addNotificationListener(ObjectName, ObjectName, NotificationFilter, Object).
 Integer[] addNotificationListeners(ObjectName[] $param_arrayOf_ObjectName_1, MarshalledObject[] $param_arrayOf_MarshalledObject_2, Subject[] $param_arrayOf_Subject_3)
Handles the method MBeanServerConnection.addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object).
 void close()
Closes this connection.
 ObjectInstance createMBean(String $param_String_1, ObjectName $param_ObjectName_2, MarshalledObject $param_MarshalledObject_3, String[] $param_arrayOf_String_4, Subject $param_Subject_5)
Handles the method MBeanServerConnection.createMBean(String, ObjectName, Object[], String[]).
 ObjectInstance createMBean(String $param_String_1, ObjectName $param_ObjectName_2, ObjectName $param_ObjectName_3, MarshalledObject $param_MarshalledObject_4, String[] $param_arrayOf_String_5, Subject $param_Subject_6)
Handles the method MBeanServerConnection.createMBean(String, ObjectName, ObjectName, Object[], String[]).
 ObjectInstance createMBean(String $param_String_1, ObjectName $param_ObjectName_2, ObjectName $param_ObjectName_3, Subject $param_Subject_4)
Handles the method MBeanServerConnection.createMBean(String, ObjectName, ObjectName).
 ObjectInstance createMBean(String $param_String_1, ObjectName $param_ObjectName_2, Subject $param_Subject_3)
Handles the method MBeanServerConnection.createMBean(String, ObjectName).
 NotificationResult fetchNotifications(long $param_long_1, int $param_int_2, long $param_long_3)
Retrieves notifications from the connector server.
 Object getAttribute(ObjectName $param_ObjectName_1, String $param_String_2, Subject $param_Subject_3)
Handles the method MBeanServerConnection.getAttribute(ObjectName, String).
 AttributeList getAttributes(ObjectName $param_ObjectName_1, String[] $param_arrayOf_String_2, Subject $param_Subject_3)
Handles the method MBeanServerConnection.getAttributes(ObjectName, String[]).
 String getConnectionId()
Returns the connection ID.
 String getDefaultDomain(Subject $param_Subject_1)
Handles the method MBeanServerConnection.getDefaultDomain().
 String[] getDomains(Subject $param_Subject_1)
Handles the method MBeanServerConnection.getDomains().
 Integer getMBeanCount(Subject $param_Subject_1)
Handles the method MBeanServerConnection.getMBeanCount().
 MBeanInfo getMBeanInfo(ObjectName $param_ObjectName_1, Subject $param_Subject_2)
Handles the method MBeanServerConnection.getMBeanInfo(ObjectName).
 ObjectInstance getObjectInstance(ObjectName $param_ObjectName_1, Subject $param_Subject_2)
Handles the method MBeanServerConnection.getObjectInstance(ObjectName).
 Object invoke(ObjectName $param_ObjectName_1, String $param_String_2, MarshalledObject $param_MarshalledObject_3, String[] $param_arrayOf_String_4, Subject $param_Subject_5)
Handles the method MBeanServerConnection.invoke(ObjectName, String, Object[], String[]).
 boolean isInstanceOf(ObjectName $param_ObjectName_1, String $param_String_2, Subject $param_Subject_3)
Handles the method MBeanServerConnection.isInstanceOf(ObjectName, String).
 boolean isRegistered(ObjectName $param_ObjectName_1, Subject $param_Subject_2)
Handles the method MBeanServerConnection.isRegistered(ObjectName).
 Set queryMBeans(ObjectName $param_ObjectName_1, MarshalledObject $param_MarshalledObject_2, Subject $param_Subject_3)
Handles the method MBeanServerConnection.queryMBeans(ObjectName, QueryExp).
 Set queryNames(ObjectName $param_ObjectName_1, MarshalledObject $param_MarshalledObject_2, Subject $param_Subject_3)
Handles the method MBeanServerConnection.queryNames(ObjectName, QueryExp).
 void removeNotificationListener(ObjectName $param_ObjectName_1, ObjectName $param_ObjectName_2, MarshalledObject $param_MarshalledObject_3, MarshalledObject $param_MarshalledObject_4, Subject $param_Subject_5)
Handles the method MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName, NotificationFilter, Object).
 void removeNotificationListener(ObjectName $param_ObjectName_1, ObjectName $param_ObjectName_2, Subject $param_Subject_3)
Handles the method MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName).
 void removeNotificationListeners(ObjectName $param_ObjectName_1, Integer[] $param_arrayOf_Integer_2, Subject $param_Subject_3)
Handles the removeNotificationListener(ObjectName, NotificationListener) and removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object) methods.
 void setAttribute(ObjectName $param_ObjectName_1, MarshalledObject $param_MarshalledObject_2, Subject $param_Subject_3)
Handles the method MBeanServerConnection.setAttribute(ObjectName, Attribute).
 AttributeList setAttributes(ObjectName $param_ObjectName_1, MarshalledObject $param_MarshalledObject_2, Subject $param_Subject_3)
Handles the method MBeanServerConnection.setAttributes(ObjectName, AttributeList).
 void unregisterMBean(ObjectName $param_ObjectName_1, Subject $param_Subject_2)
Handles the method MBeanServerConnection.unregisterMBean(ObjectName).
Methods inherited from class java.rmi.server.RemoteStub
setRef
Methods inherited from class java.rmi.server.RemoteObject
equals, getRef, hashCode, toString, toStub
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

RMIConnectionImpl_Stub

public RMIConnectionImpl_Stub(RemoteRef ref)
Method Detail

addNotificationListener

public void addNotificationListener(ObjectName $param_ObjectName_1,
                                    ObjectName $param_ObjectName_2,
                                    MarshalledObject $param_MarshalledObject_3,
                                    MarshalledObject $param_MarshalledObject_4,
                                    Subject $param_Subject_5)
                             throws IOException,
                                    InstanceNotFoundException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.addNotificationListener(ObjectName, ObjectName, NotificationFilter, Object). The NotificationFilter parameter is wrapped in a MarshalledObject. The Object (handback) parameter is also wrapped in a MarshalledObject.

Specified by:
addNotificationListener in interface RMIConnection
Parameters:
$param_ObjectName_1 - The name of the MBean on which the listener should be added.
$param_ObjectName_2 - The object name of the listener which will handle the notifications emitted by the registered MBean.
$param_MarshalledObject_3 - The filter object, encapsulated into a MarshalledObject. If filter encapsulated in the MarshalledObject has a null value, no filtering will be performed before handling notifications.
$param_MarshalledObject_4 - The context to be sent to the listener when a notification is emitted, encapsulated into a MarshalledObject.
$param_Subject_5 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
IOException - if a general communication exception occurred.
InstanceNotFoundException - The MBean name of the notification listener or of the notification broadcaster does not match any of the registered MBeans.
See Also:
RMIConnection.removeNotificationListener(ObjectName, ObjectName, Subject), RMIConnection.removeNotificationListener(ObjectName, ObjectName, MarshalledObject, MarshalledObject, Subject)

addNotificationListeners

public Integer[] addNotificationListeners(ObjectName[] $param_arrayOf_ObjectName_1,
                                          MarshalledObject[] $param_arrayOf_MarshalledObject_2,
                                          Subject[] $param_arrayOf_Subject_3)
                                   throws IOException,
                                          InstanceNotFoundException
Description copied from interface: RMIConnection

Handles the method MBeanServerConnection.addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object).

Register for notifications from the given MBeans that match the given filters. The remote client can subsequently retrieve the notifications using the fetchNotifications method.

For each listener, the original NotificationListener and handback are kept on the client side; in order for the client to be able to identify them, the server generates and returns a unique listenerID. This listenerID is forwarded with the Notifications to the remote client.

If any one of the given (name, filter) pairs cannot be registered, then the operation fails with an exception, and no names or filters are registered.

Specified by:
addNotificationListeners in interface RMIConnection
Parameters:
$param_arrayOf_ObjectName_1 - the ObjectNames identifying the MBeans emitting the Notifications.
$param_arrayOf_MarshalledObject_2 - an array of marshalled representations of the NotificationFilters. Elements of this array can be null.
$param_arrayOf_Subject_3 - the Subjects on behalf of which the listeners are being added. Elements of this array can be null. Also, the delegationSubjects parameter itself can be null, which is equivalent to an array of null values with the same size as the names and filters arrays.
Returns:
an array of listenerIDs identifying the local listeners. This array has the same number of elements as the parameters.
Throws:
IOException - if a general communication exception occurred.
InstanceNotFoundException - if one of the names does not correspond to any registered MBean.

close

public void close()
           throws IOException
Description copied from interface: RMIConnection

Closes this connection. On return from this method, the RMI object implementing this interface is unexported, so further remote calls to it will fail.

Specified by:
close in interface Closeable
Specified by:
close in interface RMIConnection
Throws:
IOException - if the connection could not be closed, or the Remote object could not be unexported, or there was a communication failure when transmitting the remote close request.

createMBean

public ObjectInstance createMBean(String $param_String_1,
                                  ObjectName $param_ObjectName_2,
                                  MarshalledObject $param_MarshalledObject_3,
                                  String[] $param_arrayOf_String_4,
                                  Subject $param_Subject_5)
                           throws IOException,
                                  InstanceAlreadyExistsException,
                                  MBeanException,
                                  MBeanRegistrationException,
                                  NotCompliantMBeanException,
                                  ReflectionException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.createMBean(String, ObjectName, Object[], String[]). The Object[] parameter is wrapped in a MarshalledObject.

Specified by:
createMBean in interface RMIConnection
Parameters:
$param_String_1 - The class name of the MBean to be instantiated.
$param_ObjectName_2 - The object name of the MBean. May be null.
$param_MarshalledObject_3 - An array containing the parameters of the constructor to be invoked, encapsulated into a MarshalledObject. The encapsulated array can be null, equivalent to an empty array.
$param_arrayOf_String_4 - An array containing the signature of the constructor to be invoked. Can be null, equivalent to an empty array.
$param_Subject_5 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
IOException - if a general communication exception occurred.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception.
NotCompliantMBeanException - This class is not a JMX compliant MBean.
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.

createMBean

public ObjectInstance createMBean(String $param_String_1,
                                  ObjectName $param_ObjectName_2,
                                  ObjectName $param_ObjectName_3,
                                  MarshalledObject $param_MarshalledObject_4,
                                  String[] $param_arrayOf_String_5,
                                  Subject $param_Subject_6)
                           throws IOException,
                                  InstanceAlreadyExistsException,
                                  InstanceNotFoundException,
                                  MBeanException,
                                  MBeanRegistrationException,
                                  NotCompliantMBeanException,
                                  ReflectionException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.createMBean(String, ObjectName, ObjectName, Object[], String[]). The Object[] parameter is wrapped in a MarshalledObject.

Specified by:
createMBean in interface RMIConnection
Parameters:
$param_String_1 - The class name of the MBean to be instantiated.
$param_ObjectName_2 - The object name of the MBean. May be null.
$param_ObjectName_3 - The object name of the class loader to be used.
$param_MarshalledObject_4 - An array containing the parameters of the constructor to be invoked, encapsulated into a MarshalledObject. The encapsulated array can be null, equivalent to an empty array.
$param_arrayOf_String_5 - An array containing the signature of the constructor to be invoked. Can be null, equivalent to an empty array.
$param_Subject_6 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
IOException - if a general communication exception occurred.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
InstanceNotFoundException - The specified class loader is not registered in the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception.
NotCompliantMBeanException - This class is not a JMX compliant MBean.
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.

createMBean

public ObjectInstance createMBean(String $param_String_1,
                                  ObjectName $param_ObjectName_2,
                                  ObjectName $param_ObjectName_3,
                                  Subject $param_Subject_4)
                           throws IOException,
                                  InstanceAlreadyExistsException,
                                  InstanceNotFoundException,
                                  MBeanException,
                                  MBeanRegistrationException,
                                  NotCompliantMBeanException,
                                  ReflectionException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.createMBean(String, ObjectName, ObjectName).

Specified by:
createMBean in interface RMIConnection
Parameters:
$param_String_1 - The class name of the MBean to be instantiated.
$param_ObjectName_2 - The object name of the MBean. May be null.
$param_ObjectName_3 - The object name of the class loader to be used.
$param_Subject_4 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
IOException - if a general communication exception occurred.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
InstanceNotFoundException - The specified class loader is not registered in the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception.
NotCompliantMBeanException - This class is not a JMX compliant MBean.
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.

createMBean

public ObjectInstance createMBean(String $param_String_1,
                                  ObjectName $param_ObjectName_2,
                                  Subject $param_Subject_3)
                           throws IOException,
                                  InstanceAlreadyExistsException,
                                  MBeanException,
                                  MBeanRegistrationException,
                                  NotCompliantMBeanException,
                                  ReflectionException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.createMBean(String, ObjectName).

Specified by:
createMBean in interface RMIConnection
Parameters:
$param_String_1 - The class name of the MBean to be instantiated.
$param_ObjectName_2 - The object name of the MBean. May be null.
$param_Subject_3 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().
Throws:
IOException - if a general communication exception occurred.
InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.
MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.
MBeanException - The constructor of the MBean has thrown an exception.
NotCompliantMBeanException - This class is not a JMX compliant MBean.
ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.

fetchNotifications

public NotificationResult fetchNotifications(long $param_long_1,
                                             int $param_int_2,
                                             long $param_long_3)
                                      throws IOException
Description copied from interface: RMIConnection

Retrieves notifications from the connector server. This method can block until there is at least one notification or until the specified timeout is reached. The method can also return at any time with zero notifications.

A notification can be included in the result if its sequence number is no less than clientSequenceNumber and this client has registered at least one listener for the MBean generating the notification, with a filter that accepts the notification. Each listener that is interested in the notification is identified by an Integer ID that was returned by RMIConnection.addNotificationListeners(ObjectName[], MarshalledObject[], Subject[]).

Specified by:
fetchNotifications in interface RMIConnection
Parameters:
$param_long_1 - the first sequence number that the client is interested in. If negative, it is interpreted as meaning the sequence number that the next notification will have.
$param_int_2 - the maximum number of different notifications to return. The TargetedNotification array in the returned NotificationResult can have more elements than this if the same notification appears more than once. The behavior is unspecified if this parameter is negative.
$param_long_3 - the maximum time in milliseconds to wait for a notification to arrive. This can be 0 to indicate that the method should not wait if there are no notifications, but should return at once. It can be Long.MAX_VALUE to indicate that there is no timeout. The behavior is unspecified if this parameter is negative.
Returns:
A NotificationResult.
Throws:
IOException - if a general communication exception occurred.

getAttribute

public Object getAttribute(ObjectName $param_ObjectName_1,
                           String $param_String_2,
                           Subject $param_Subject_3)
                    throws IOException,
                           AttributeNotFoundException,
                           InstanceNotFoundException,
                           MBeanException,
                           ReflectionException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.getAttribute(ObjectName, String).

Specified by:
getAttribute in interface RMIConnection
Parameters:
$param_ObjectName_1 - The object name of the MBean from which the attribute is to be retrieved.
$param_String_2 - A String specifying the name of the attribute to be retrieved.
$param_Subject_3 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
The value of the retrieved attribute.
Throws:
IOException - if a general communication exception occurred.
AttributeNotFoundException - The attribute specified is not accessible in the MBean.
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
MBeanException - Wraps an exception thrown by the MBean's getter.
ReflectionException - Wraps a java.lang.Exception thrown when trying to invoke the getter.
See Also:
RMIConnection.setAttribute(javax.management.ObjectName, java.rmi.MarshalledObject, javax.security.auth.Subject)

getAttributes

public AttributeList getAttributes(ObjectName $param_ObjectName_1,
                                   String[] $param_arrayOf_String_2,
                                   Subject $param_Subject_3)
                            throws IOException,
                                   InstanceNotFoundException,
                                   ReflectionException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.getAttributes(ObjectName, String[]).

Specified by:
getAttributes in interface RMIConnection
Parameters:
$param_ObjectName_1 - The object name of the MBean from which the attributes are retrieved.
$param_arrayOf_String_2 - A list of the attributes to be retrieved.
$param_Subject_3 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
The list of the retrieved attributes.
Throws:
IOException - if a general communication exception occurred.
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
ReflectionException - An exception occurred when trying to invoke the getAttributes method of a Dynamic MBean.
See Also:
RMIConnection.setAttributes(javax.management.ObjectName, java.rmi.MarshalledObject, javax.security.auth.Subject)

getConnectionId

public String getConnectionId()
                       throws IOException
Description copied from interface: RMIConnection

Returns the connection ID. This string is different for every open connection to a given RMI connector server.

Specified by:
getConnectionId in interface RMIConnection
Returns:
the connection ID
Throws:
IOException - if a general communication exception occurred.
See Also:
RMIConnector.connect

getDefaultDomain

public String getDefaultDomain(Subject $param_Subject_1)
                        throws IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.getDefaultDomain().

Specified by:
getDefaultDomain in interface RMIConnection
Parameters:
$param_Subject_1 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
the default domain.
Throws:
IOException - if a general communication exception occurred.

getDomains

public String[] getDomains(Subject $param_Subject_1)
                    throws IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.getDomains().

Specified by:
getDomains in interface RMIConnection
Parameters:
$param_Subject_1 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
the list of domains.
Throws:
IOException - if a general communication exception occurred.

getMBeanCount

public Integer getMBeanCount(Subject $param_Subject_1)
                      throws IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.getMBeanCount().

Specified by:
getMBeanCount in interface RMIConnection
Parameters:
$param_Subject_1 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
the number of MBeans registered.
Throws:
IOException - if a general communication exception occurred.

getMBeanInfo

public MBeanInfo getMBeanInfo(ObjectName $param_ObjectName_1,
                              Subject $param_Subject_2)
                       throws IOException,
                              InstanceNotFoundException,
                              IntrospectionException,
                              ReflectionException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.getMBeanInfo(ObjectName).

Specified by:
getMBeanInfo in interface RMIConnection
Parameters:
$param_ObjectName_1 - The name of the MBean to analyze
$param_Subject_2 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
An instance of MBeanInfo allowing the retrieval of all attributes and operations of this MBean.
Throws:
IOException - if a general communication exception occurred.
InstanceNotFoundException - The MBean specified was not found.
IntrospectionException - An exception occurred during introspection.
ReflectionException - An exception occurred when trying to invoke the getMBeanInfo of a Dynamic MBean.

getObjectInstance

public ObjectInstance getObjectInstance(ObjectName $param_ObjectName_1,
                                        Subject $param_Subject_2)
                                 throws IOException,
                                        InstanceNotFoundException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.getObjectInstance(ObjectName).

Specified by:
getObjectInstance in interface RMIConnection
Parameters:
$param_ObjectName_1 - The object name of the MBean.
$param_Subject_2 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
The ObjectInstance associated with the MBean specified by name. The contained ObjectName is name and the contained class name is getMBeanInfo(name).getClassName().
Throws:
IOException - if a general communication exception occurred.
InstanceNotFoundException - The MBean specified is not registered in the MBean server.

invoke

public Object invoke(ObjectName $param_ObjectName_1,
                     String $param_String_2,
                     MarshalledObject $param_MarshalledObject_3,
                     String[] $param_arrayOf_String_4,
                     Subject $param_Subject_5)
              throws IOException,
                     InstanceNotFoundException,
                     MBeanException,
                     ReflectionException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.invoke(ObjectName, String, Object[], String[]). The Object[] parameter is wrapped in a MarshalledObject.

Specified by:
invoke in interface RMIConnection
Parameters:
$param_ObjectName_1 - The object name of the MBean on which the method is to be invoked.
$param_String_2 - The name of the operation to be invoked.
$param_MarshalledObject_3 - An array containing the parameters to be set when the operation is invoked, encapsulated into a MarshalledObject. The encapsulated array can be null, equivalent to an empty array.
$param_arrayOf_String_4 - An array containing the signature of the operation. The class objects will be loaded using the same class loader as the one used for loading the MBean on which the operation was invoked. Can be null, equivalent to an empty array.
$param_Subject_5 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
The object returned by the operation, which represents the result of invoking the operation on the MBean specified.
Throws:
IOException - if a general communication exception occurred.
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
MBeanException - Wraps an exception thrown by the MBean's invoked method.
ReflectionException - Wraps a java.lang.Exception thrown while trying to invoke the method.

isInstanceOf

public boolean isInstanceOf(ObjectName $param_ObjectName_1,
                            String $param_String_2,
                            Subject $param_Subject_3)
                     throws IOException,
                            InstanceNotFoundException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.isInstanceOf(ObjectName, String).

Specified by:
isInstanceOf in interface RMIConnection
Parameters:
$param_ObjectName_1 - The ObjectName of the MBean.
$param_String_2 - The name of the class.
$param_Subject_3 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
true if the MBean specified is an instance of the specified class according to the rules above, false otherwise.
Throws:
IOException - if a general communication exception occurred.
InstanceNotFoundException - The MBean specified is not registered in the MBean server.

isRegistered

public boolean isRegistered(ObjectName $param_ObjectName_1,
                            Subject $param_Subject_2)
                     throws IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.isRegistered(ObjectName).

Specified by:
isRegistered in interface RMIConnection
Parameters:
$param_ObjectName_1 - The object name of the MBean to be checked.
$param_Subject_2 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
True if the MBean is already registered in the MBean server, false otherwise.
Throws:
IOException - if a general communication exception occurred.

queryMBeans

public Set queryMBeans(ObjectName $param_ObjectName_1,
                       MarshalledObject $param_MarshalledObject_2,
                       Subject $param_Subject_3)
                throws IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.queryMBeans(ObjectName, QueryExp). The QueryExp is wrapped in a MarshalledObject.

Specified by:
queryMBeans in interface RMIConnection
Parameters:
$param_ObjectName_1 - The object name pattern identifying the MBeans to be retrieved. If null or no domain and key properties are specified, all the MBeans registered will be retrieved.
$param_MarshalledObject_2 - The query expression to be applied for selecting MBeans, encapsulated into a MarshalledObject. If the MarshalledObject encapsulates a null value no query expression will be applied for selecting MBeans.
$param_Subject_3 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
A set containing the ObjectInstance objects for the selected MBeans. If no MBean satisfies the query an empty list is returned.
Throws:
IOException - if a general communication exception occurred.

queryNames

public Set queryNames(ObjectName $param_ObjectName_1,
                      MarshalledObject $param_MarshalledObject_2,
                      Subject $param_Subject_3)
               throws IOException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.queryNames(ObjectName, QueryExp). The QueryExp is wrapped in a MarshalledObject.

Specified by:
queryNames in interface RMIConnection
Parameters:
$param_ObjectName_1 - The object name pattern identifying the MBean names to be retrieved. If null or no domain and key properties are specified, the name of all registered MBeans will be retrieved.
$param_MarshalledObject_2 - The query expression to be applied for selecting MBeans, encapsulated into a MarshalledObject. If the MarshalledObject encapsulates a null value no query expression will be applied for selecting MBeans.
$param_Subject_3 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
A set containing the ObjectNames for the MBeans selected. If no MBean satisfies the query, an empty list is returned.
Throws:
IOException - if a general communication exception occurred.

removeNotificationListener

public void removeNotificationListener(ObjectName $param_ObjectName_1,
                                       ObjectName $param_ObjectName_2,
                                       MarshalledObject $param_MarshalledObject_3,
                                       MarshalledObject $param_MarshalledObject_4,
                                       Subject $param_Subject_5)
                                throws IOException,
                                       InstanceNotFoundException,
                                       ListenerNotFoundException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName, NotificationFilter, Object). The NotificationFilter parameter is wrapped in a MarshalledObject. The Object parameter is also wrapped in a MarshalledObject.

Specified by:
removeNotificationListener in interface RMIConnection
Parameters:
$param_ObjectName_1 - The name of the MBean on which the listener should be removed.
$param_ObjectName_2 - A listener that was previously added to this MBean.
$param_MarshalledObject_3 - The filter that was specified when the listener was added, encapsulated into a MarshalledObject.
$param_MarshalledObject_4 - The handback that was specified when the listener was added, encapsulated into a MarshalledObject.
$param_Subject_5 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
IOException - if a general communication exception occurred.
InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.
ListenerNotFoundException - The listener is not registered in the MBean, or it is not registered with the given filter and handback.
See Also:
RMIConnection.addNotificationListener(javax.management.ObjectName, javax.management.ObjectName, java.rmi.MarshalledObject, java.rmi.MarshalledObject, javax.security.auth.Subject)

removeNotificationListener

public void removeNotificationListener(ObjectName $param_ObjectName_1,
                                       ObjectName $param_ObjectName_2,
                                       Subject $param_Subject_3)
                                throws IOException,
                                       InstanceNotFoundException,
                                       ListenerNotFoundException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName).

Specified by:
removeNotificationListener in interface RMIConnection
Parameters:
$param_ObjectName_1 - The name of the MBean on which the listener should be removed.
$param_ObjectName_2 - The object name of the listener to be removed.
$param_Subject_3 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
IOException - if a general communication exception occurred.
InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.
ListenerNotFoundException - The listener is not registered in the MBean.
See Also:
RMIConnection.addNotificationListener(javax.management.ObjectName, javax.management.ObjectName, java.rmi.MarshalledObject, java.rmi.MarshalledObject, javax.security.auth.Subject)

removeNotificationListeners

public void removeNotificationListeners(ObjectName $param_ObjectName_1,
                                        Integer[] $param_arrayOf_Integer_2,
                                        Subject $param_Subject_3)
                                 throws IOException,
                                        InstanceNotFoundException,
                                        ListenerNotFoundException
Description copied from interface: RMIConnection

Handles the removeNotificationListener(ObjectName, NotificationListener) and removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object) methods.

This method removes one or more NotificationListeners from a given MBean in the MBean server.

The NotificationListeners are identified by the IDs which were returned by the RMIConnection.addNotificationListeners(ObjectName[], MarshalledObject[], Subject[]) method.

Specified by:
removeNotificationListeners in interface RMIConnection
Parameters:
$param_ObjectName_1 - the ObjectName identifying the MBean emitting the Notifications.
$param_arrayOf_Integer_2 - the list of the IDs corresponding to the listeners to remove.
$param_Subject_3 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
IOException - if a general communication exception occurred.
InstanceNotFoundException - if the given name does not correspond to any registered MBean.
ListenerNotFoundException - if one of the listeners was not found on the server side. This exception can happen if the MBean discarded a listener for some reason other than a call to MBeanServer.removeNotificationListener.

setAttribute

public void setAttribute(ObjectName $param_ObjectName_1,
                         MarshalledObject $param_MarshalledObject_2,
                         Subject $param_Subject_3)
                  throws IOException,
                         AttributeNotFoundException,
                         InstanceNotFoundException,
                         InvalidAttributeValueException,
                         MBeanException,
                         ReflectionException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.setAttribute(ObjectName, Attribute). The Attribute parameter is wrapped in a MarshalledObject.

Specified by:
setAttribute in interface RMIConnection
Parameters:
$param_ObjectName_1 - The name of the MBean within which the attribute is to be set.
$param_MarshalledObject_2 - The identification of the attribute to be set and the value it is to be set to, encapsulated into a MarshalledObject.
$param_Subject_3 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
IOException - if a general communication exception occurred.
AttributeNotFoundException - The attribute specified is not accessible in the MBean.
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
InvalidAttributeValueException - The value specified for the attribute is not valid.
MBeanException - Wraps an exception thrown by the MBean's setter.
ReflectionException - Wraps a java.lang.Exception thrown when trying to invoke the setter.
See Also:
RMIConnection.getAttribute(javax.management.ObjectName, java.lang.String, javax.security.auth.Subject)

setAttributes

public AttributeList setAttributes(ObjectName $param_ObjectName_1,
                                   MarshalledObject $param_MarshalledObject_2,
                                   Subject $param_Subject_3)
                            throws IOException,
                                   InstanceNotFoundException,
                                   ReflectionException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.setAttributes(ObjectName, AttributeList). The AttributeList parameter is wrapped in a MarshalledObject.

Specified by:
setAttributes in interface RMIConnection
Parameters:
$param_ObjectName_1 - The object name of the MBean within which the attributes are to be set.
$param_MarshalledObject_2 - A list of attributes: The identification of the attributes to be set and the values they are to be set to, encapsulated into a MarshalledObject.
$param_Subject_3 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Returns:
The list of attributes that were set, with their new values.
Throws:
IOException - if a general communication exception occurred.
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
ReflectionException - An exception occurred when trying to invoke the getAttributes method of a Dynamic MBean.
See Also:
RMIConnection.getAttributes(javax.management.ObjectName, java.lang.String[], javax.security.auth.Subject)

unregisterMBean

public void unregisterMBean(ObjectName $param_ObjectName_1,
                            Subject $param_Subject_2)
                     throws IOException,
                            InstanceNotFoundException,
                            MBeanRegistrationException
Description copied from interface: RMIConnection
Handles the method MBeanServerConnection.unregisterMBean(ObjectName).

Specified by:
unregisterMBean in interface RMIConnection
Parameters:
$param_ObjectName_1 - The object name of the MBean to be unregistered.
$param_Subject_2 - The Subject containing the delegation principals or null if the authentication principal is used instead.
Throws:
IOException - if a general communication exception occurred.
InstanceNotFoundException - The MBean specified is not registered in the MBean server.
MBeanRegistrationException - The preDeregister ((MBeanRegistration interface) method of the MBean has thrown an exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RMIConnector

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote.rmi
Class RMIConnector

java.lang.Object
    extended by  javax.management.remote.rmi.RMIConnector
All Implemented Interfaces:
Closeable, Serializable, JMXAddressable, JMXConnector
public class RMIConnector
extends Object
implements JMXConnector, Serializable, JMXAddressable

A connection to a remote RMI connector. Usually, such connections are made using JMXConnectorFactory. However, specialized applications can use this class directly, for example with an RMIServer stub obtained without going through JNDI.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from interface javax.management.remote.JMXConnector
CREDENTIALS
Constructor Summary
RMIConnector(JMXServiceURL url, Map<String,?> environment)
Constructs an RMIConnector that will connect the RMI connector server with the given address.
RMIConnector(RMIServer rmiServer, Map<String,?> environment)
Constructs an RMIConnector using the given RMI stub.
Method Summary
void | addConnectionNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Adds a listener to be informed of changes in connection status.
void | close() Closes the client connection to its server.
void | connect() Establishes the connection to the connector server.
void | connect(Map<String,?> environment) Establishes the connection to the connector server.
JMXServiceURL | getAddress() The address of this connector.
String | getConnectionId() Gets this connection's ID from the connector server.
MBeanServerConnection | getMBeanServerConnection() Returns an MBeanServerConnection object representing a remote MBean server.
MBeanServerConnection | getMBeanServerConnection(Subject delegationSubject) Returns an MBeanServerConnection object representing a remote MBean server on which operations are performed on behalf of the supplied delegation subject.
void | removeConnectionNotificationListener(NotificationListener listener) Removes a listener from the list to be informed of changes in status.
void | removeConnectionNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Removes a listener from the list to be informed of changes in status.
String | toString() Returns a string representation of this object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RMIConnector

public RMIConnector(JMXServiceURL url,
                    Map<String,?> environment)

Constructs an RMIConnector that will connect the RMI connector server with the given address.

The address can refer directly to the connector server, using one of the following syntaxes:

 service:jmx:rmi://[host[:port]]/stub/encoded-stub
 service:jmx:iiop://[host[:port]]/ior/encoded-IOR

(Here, the square brackets [] are not part of the address but indicate that the host and port are optional.)

The address can instead indicate where to find an RMI stub through JNDI, using one of the following syntaxes:

 service:jmx:rmi://[host[:port]]/jndi/jndi-name
 service:jmx:iiop://[host[:port]]/jndi/jndi-name

An implementation may also recognize additional address syntaxes, for example:

 service:jmx:iiop://[host[:port]]/stub/encoded-stub

Parameters:
url - the address of the RMI connector server.
environment - additional attributes specifying how to make the connection. For JNDI-based addresses, these attributes can usefully include JNDI attributes recognized by InitialContext. This parameter can be null, which is equivalent to an empty Map.
Throws:
IllegalArgumentException - if url is null.

RMIConnector

public RMIConnector(RMIServer rmiServer,
                    Map<String,?> environment)

Constructs an RMIConnector using the given RMI stub.

Parameters:
rmiServer - an RMI stub representing the RMI connector server.
environment - additional attributes specifying how to make the connection. This parameter can be null, which is equivalent to an empty Map.
Throws:
IllegalArgumentException - if rmiServer is null.
Method Detail

toString

public String toString()

Returns a string representation of this object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read.

Overrides:
toString in class Object
Returns:
a String representation of this object.

getAddress

public JMXServiceURL getAddress()

The address of this connector.

Specified by:
getAddress in interface JMXAddressable
Returns:
the address of this connector, or null if it does not have one.
Since:
1.6

connect

public void connect()
             throws IOException
Description copied from interface: JMXConnector

Establishes the connection to the connector server. This method is equivalent to connect(null).

Specified by:
connect in interface JMXConnector
Throws:
IOException - if the connection could not be made because of a communication problem.

connect

public void connect(Map<String,?> environment)
             throws IOException
Description copied from interface: JMXConnector

Establishes the connection to the connector server.

If connect has already been called successfully on this object, calling it again has no effect. If, however, JMXConnector.close() was called after connect, the new connect will throw an IOException.

Otherwise, either connect has never been called on this object, or it has been called but produced an exception. Then calling connect will attempt to establish a connection to the connector server.

Specified by:
connect in interface JMXConnector
Parameters:
environment - the properties of the connection. Properties in this map override properties in the map specified when the JMXConnector was created, if any. This parameter can be null, which is equivalent to an empty map.
Throws:
IOException - if the connection could not be made because of a communication problem.

getConnectionId

public String getConnectionId()
                       throws IOException
Description copied from interface: JMXConnector

Gets this connection's ID from the connector server. For a given connector server, every connection will have a unique id which does not change during the lifetime of the connection.

Specified by:
getConnectionId in interface JMXConnector
Returns:
the unique ID of this connection. This is the same as the ID that the connector server includes in its JMXConnectionNotifications. The package description describes the conventions for connection IDs.
Throws:
IOException - if the connection ID cannot be obtained, for instance because the connection is closed or broken.

getMBeanServerConnection

public MBeanServerConnection getMBeanServerConnection()
                                               throws IOException
Description copied from interface: JMXConnector

Returns an MBeanServerConnection object representing a remote MBean server. For a given JMXConnector, two successful calls to this method will usually return the same MBeanServerConnection object, though this is not required.

For each method in the returned MBeanServerConnection, calling the method causes the corresponding method to be called in the remote MBean server. The value returned by the MBean server method is the value returned to the client. If the MBean server method produces an Exception, the same Exception is seen by the client. If the MBean server method, or the attempt to call it, produces an Error, the Error is wrapped in a JMXServerErrorException, which is seen by the client.

Calling this method is equivalent to calling getMBeanServerConnection(null) meaning that no delegation subject is specified and that all the operations called on the MBeanServerConnection must use the authenticated subject, if any.

Specified by:
getMBeanServerConnection in interface JMXConnector
Returns:
an object that implements the MBeanServerConnection interface by forwarding its methods to the remote MBean server.
Throws:
IOException - if a valid MBeanServerConnection cannot be created, for instance because the connection to the remote MBean server has not yet been established (with the connect method), or it has been closed, or it has broken.

getMBeanServerConnection

public MBeanServerConnection getMBeanServerConnection(Subject delegationSubject)
                                               throws IOException
Description copied from interface: JMXConnector

Returns an MBeanServerConnection object representing a remote MBean server on which operations are performed on behalf of the supplied delegation subject. For a given JMXConnector and Subject, two successful calls to this method will usually return the same MBeanServerConnection object, though this is not required.

For each method in the returned MBeanServerConnection, calling the method causes the corresponding method to be called in the remote MBean server on behalf of the given delegation subject instead of the authenticated subject. The value returned by the MBean server method is the value returned to the client. If the MBean server method produces an Exception, the same Exception is seen by the client. If the MBean server method, or the attempt to call it, produces an Error, the Error is wrapped in a JMXServerErrorException, which is seen by the client.

Specified by:
getMBeanServerConnection in interface JMXConnector
Parameters:
delegationSubject - the Subject on behalf of which requests will be performed. Can be null, in which case requests will be performed on behalf of the authenticated Subject, if any.
Returns:
an object that implements the MBeanServerConnection interface by forwarding its methods to the remote MBean server on behalf of a given delegation subject.
Throws:
IOException - if a valid MBeanServerConnection cannot be created, for instance because the connection to the remote MBean server has not yet been established (with the connect method), or it has been closed, or it has broken.

addConnectionNotificationListener

public void addConnectionNotificationListener(NotificationListener listener,
                                              NotificationFilter filter,
                                              Object handback)
Description copied from interface: JMXConnector

Adds a listener to be informed of changes in connection status. The listener will receive notifications of type JMXConnectionNotification. An implementation can send other types of notifications too.

Any number of listeners can be added with this method. The same listener can be added more than once with the same or different values for the filter and handback. There is no special treatment of a duplicate entry. For example, if a listener is registered twice with no filter, then its handleNotification method will be called twice for each notification.

Specified by:
addConnectionNotificationListener in interface JMXConnector
Parameters:
listener - a listener to receive connection status notifications.
filter - a filter to select which notifications are to be delivered to the listener, or null if all notifications are to be delivered.
handback - an object to be given to the listener along with each notification. Can be null.
See Also:
JMXConnector.removeConnectionNotificationListener(javax.management.NotificationListener), NotificationBroadcaster.addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

removeConnectionNotificationListener

public void removeConnectionNotificationListener(NotificationListener listener)
                                          throws ListenerNotFoundException
Description copied from interface: JMXConnector

Removes a listener from the list to be informed of changes in status. The listener must previously have been added. If there is more than one matching listener, all are removed.

Specified by:
removeConnectionNotificationListener in interface JMXConnector
Parameters:
listener - a listener to receive connection status notifications.
Throws:
ListenerNotFoundException - if the listener is not registered with this JMXConnector.
See Also:
JMXConnector.removeConnectionNotificationListener(NotificationListener, NotificationFilter, Object), JMXConnector.addConnectionNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object), NotificationEmitter.removeNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

removeConnectionNotificationListener

public void removeConnectionNotificationListener(NotificationListener listener,
                                                 NotificationFilter filter,
                                                 Object handback)
                                          throws ListenerNotFoundException
Description copied from interface: JMXConnector

Removes a listener from the list to be informed of changes in status. The listener must previously have been added with the same three parameters. If there is more than one matching listener, only one is removed.

Specified by:
removeConnectionNotificationListener in interface JMXConnector
Parameters:
listener - a listener to receive connection status notifications.
filter - a filter to select which notifications are to be delivered to the listener. Can be null.
handback - an object to be given to the listener along with each notification. Can be null.
Throws:
ListenerNotFoundException - if the listener is not registered with this JMXConnector, or is not registered with the given filter and handback.
See Also:
JMXConnector.removeConnectionNotificationListener(NotificationListener),
JMXConnector.addConnectionNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object),
NotificationEmitter.removeNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

close

public void close()
           throws IOException
Description copied from interface: JMXConnector

Closes the client connection to its server. Any ongoing or new request using the MBeanServerConnection returned by JMXConnector.getMBeanServerConnection() will get an IOException.

If close has already been called successfully on this object, calling it again has no effect. If close has never been called, or if it was called but produced an exception, an attempt will be made to close the connection. This attempt can succeed, in which case close will return normally, or it can generate an exception.

Closing a connection is a potentially slow operation. For example, if the server has crashed, the close operation might have to wait for a network protocol timeout. Callers that do not want to block in a close operation should do it in a separate thread.

Specified by:
close in interface Closeable
Specified by:
close in interface JMXConnector
Throws:
IOException - if the connection cannot be closed cleanly. If this exception is thrown, it is not known whether the server end of the connection has been cleanly closed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RMIConnectorServer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote.rmi
Class RMIConnectorServer

java.lang.Object
    extended by  javax.management.NotificationBroadcasterSupport
        extended by  javax.management.remote.JMXConnectorServer
            extended by  javax.management.remote.rmi.RMIConnectorServer
All Implemented Interfaces:
MBeanRegistration, NotificationBroadcaster, NotificationEmitter, JMXAddressable, JMXConnectorServerMBean
public class RMIConnectorServer
extends JMXConnectorServer

A JMX API connector server that creates RMI-based connections from remote clients. Usually, such connector servers are made using JMXConnectorServerFactory. However, specialized applications can use this class directly, for example with an RMIServerImpl object.

Since:
1.5

Field Summary
static String | JNDI_REBIND_ATTRIBUTE Name of the attribute that specifies whether the RMIServer stub that represents an RMI connector server should override an existing stub at the same address.
static String | RMI_CLIENT_SOCKET_FACTORY_ATTRIBUTE Name of the attribute that specifies the RMIClientSocketFactory for the RMI objects created in conjunction with this connector.
static String | RMI_SERVER_SOCKET_FACTORY_ATTRIBUTE Name of the attribute that specifies the RMIServerSocketFactory for the RMI objects created in conjunction with this connector.
Fields inherited from class javax.management.remote.JMXConnectorServer
AUTHENTICATOR
Constructor Summary
RMIConnectorServer(JMXServiceURL url, Map<String,?> environment)
Makes an RMIConnectorServer.
RMIConnectorServer(JMXServiceURL url, Map<String,?> environment, MBeanServer mbeanServer)
Makes an RMIConnectorServer for the given MBean server.
RMIConnectorServer(JMXServiceURL url, Map<String,?> environment, RMIServerImpl rmiServerImpl, MBeanServer mbeanServer)
Makes an RMIConnectorServer for the given MBean server.
Method Summary
protected void | connectionClosed(String connectionId, String message, Object userData) Called by a subclass when a client connection is closed normally.
protected void | connectionFailed(String connectionId, String message, Object userData) Called by a subclass when a client connection fails.
protected void | connectionOpened(String connectionId, String message, Object userData) Called by a subclass when a new client connection is opened.
JMXServiceURL | getAddress() The address of this connector server.
Map<String,?> | getAttributes() The attributes for this connector server.
boolean | isActive() Determines whether the connector server is active.
void | setMBeanServerForwarder(MBeanServerForwarder mbsf) Adds an object that intercepts requests for the MBean server that arrive through this connector server.
void | start() Activates the connector server, that is starts listening for client connections.
void | stop() Deactivates the connector server, that is, stops listening for client connections.
JMXConnector | toJMXConnector(Map<String,?> env) Returns a client stub for this connector server.
Methods inherited from class javax.management.remote.JMXConnectorServer
getConnectionIds, getMBeanServer, getNotificationInfo, postDeregister, postRegister, preDeregister, preRegister
Methods inherited from class javax.management.NotificationBroadcasterSupport
addNotificationListener, handleNotification, removeNotificationListener, removeNotificationListener, sendNotification
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

JNDI_REBIND_ATTRIBUTE

public static final String JNDI_REBIND_ATTRIBUTE

Name of the attribute that specifies whether the RMIServer stub that represents an RMI connector server should override an existing stub at the same address. The value associated with this attribute, if any, should be a string that is equal, ignoring case, to "true" or "false". The default value is false.

See Also:
Constant Field Values

RMI_CLIENT_SOCKET_FACTORY_ATTRIBUTE

public static final String RMI_CLIENT_SOCKET_FACTORY_ATTRIBUTE

Name of the attribute that specifies the RMIClientSocketFactory for the RMI objects created in conjunction with this connector. The value associated with this attribute must be of type RMIClientSocketFactory and can only be specified in the Map argument supplied when creating a connector server.

See Also:
Constant Field Values

RMI_SERVER_SOCKET_FACTORY_ATTRIBUTE

public static final String RMI_SERVER_SOCKET_FACTORY_ATTRIBUTE

Name of the attribute that specifies the RMIServerSocketFactory for the RMI objects created in conjunction with this connector. The value associated with this attribute must be of type RMIServerSocketFactory and can only be specified in the Map argument supplied when creating a connector server.

See Also:
Constant Field Values
Constructor Detail

RMIConnectorServer

public RMIConnectorServer(JMXServiceURL url,
                          Map<String,?> environment)
                   throws IOException

Makes an RMIConnectorServer. This is equivalent to calling RMIConnectorServer(directoryURL,environment,null,null)

Parameters:
url - the URL defining how to create the connector server. Cannot be null.
environment - attributes governing the creation and storing of the RMI object. Can be null, which is equivalent to an empty Map.
Throws:
IllegalArgumentException - if url is null.
MalformedURLException - if url does not conform to the syntax for an RMI connector, or if its protocol is not recognized by this implementation. Only "rmi" and "iiop" are valid when this constructor is used.
IOException - if the connector server cannot be created for some reason or if it is inevitable that its start method will fail.

RMIConnectorServer

public RMIConnectorServer(JMXServiceURL url,
                          Map<String,?> environment,
                          MBeanServer mbeanServer)
                   throws IOException

Makes an RMIConnectorServer for the given MBean server. This is equivalent to calling RMIConnectorServer(directoryURL,environment,null,mbeanServer)

Parameters:
url - the URL defining how to create the connector server. Cannot be null.
environment - attributes governing the creation and storing of the RMI object. Can be null, which is equivalent to an empty Map.
mbeanServer - the MBean server to which the new connector server is attached, or null if it will be attached by being registered as an MBean in the MBean server.
Throws:
IllegalArgumentException - if url is null.
MalformedURLException - if url does not conform to the syntax for an RMI connector, or if its protocol is not recognized by this implementation. Only "rmi" and "iiop" are valid when this constructor is used.
IOException - if the connector server cannot be created for some reason or if it is inevitable that its start method will fail.

RMIConnectorServer

public RMIConnectorServer(JMXServiceURL url,
                          Map<String,?> environment,
                          RMIServerImpl rmiServerImpl,
                          MBeanServer mbeanServer)
                   throws IOException

Makes an RMIConnectorServer for the given MBean server.

Parameters:
url - the URL defining how to create the connector server. Cannot be null.
environment - attributes governing the creation and storing of the RMI object. Can be null, which is equivalent to an empty Map.
rmiServerImpl - An implementation of the RMIServer interface, consistent with the protocol type specified in url. If this parameter is non null, the protocol type specified by url is not constrained, and is assumed to be valid. Otherwise, only "rmi" and "iiop" will be recognized.
mbeanServer - the MBean server to which the new connector server is attached, or null if it will be attached by being registered as an MBean in the MBean server.
Throws:
IllegalArgumentException - if url is null.
MalformedURLException - if url does not conform to the syntax for an RMI connector, or if its protocol is not recognized by this implementation. Only "rmi" and "iiop" are recognized when rmiServerImpl is null.
IOException - if the connector server cannot be created for some reason or if it is inevitable that its start method will fail.
See Also:
start()
Method Detail

toJMXConnector

public JMXConnector toJMXConnector(Map<String,?> env)
                            throws IOException

Returns a client stub for this connector server. A client stub is a serializable object whose connect method can be used to make one new connection to this connector server.

Specified by:
toJMXConnector in interface JMXConnectorServerMBean
Overrides:
toJMXConnector in class JMXConnectorServer
Parameters:
env - client connection parameters of the same sort that could be provided to JMXConnector.connect(Map). Can be null, which is equivalent to an empty map.
Returns:
a client stub that can be used to make a new connection to this connector server.
Throws:
UnsupportedOperationException - if this connector server does not support the generation of client stubs.
IllegalStateException - if the JMXConnectorServer is not started (see isActive()).
IOException - if a communications problem means that a stub cannot be created.

start

public void start()
           throws IOException

Activates the connector server, that is starts listening for client connections. Calling this method when the connector server is already active has no effect. Calling this method when the connector server has been stopped will generate an IOException.

The behavior of this method when called for the first time depends on the parameters that were supplied at construction, as described below.

First, an object of a subclass of RMIServerImpl is required, to export the connector server through RMI:

  • If an RMIServerImpl was supplied to the constructor, it is used.
  • Otherwise, if the protocol part of the JMXServiceURL supplied to the constructor was iiop, an object of type RMIIIOPServerImpl is created.
  • Otherwise, if the JMXServiceURL was null, or its protocol part was rmi, an object of type RMIJRMPServerImpl is created.
  • Otherwise, the implementation can create an implementation-specific RMIServerImpl or it can throw MalformedURLException.

If the given address includes a JNDI directory URL as specified in the package documentation for javax.management.remote.rmi, then this RMIConnectorServer will bootstrap by binding the RMIServerImpl to the given address.

If the URL path part of the JMXServiceURL was empty or a single slash (/), then the RMI object will not be bound to a directory. Instead, a reference to it will be encoded in the URL path of the RMIConnectorServer address (returned by getAddress()). The encodings for rmi and iiop are described in the package documentation for javax.management.remote.rmi.

The behavior when the URL path is neither empty nor a JNDI directory URL, or when the protocol is neither rmi nor iiop, is implementation defined, and may include throwing MalformedURLException when the connector server is created or when it is started.

Throws:
IllegalStateException - if the connector server has not been attached to an MBean server.
IOException - if the connector server cannot be started.

stop

public void stop()
          throws IOException

Deactivates the connector server, that is, stops listening for client connections. Calling this method will also close all client connections that were made by this server. After this method returns, whether normally or with an exception, the connector server will not create any new client connections.

Once a connector server has been stopped, it cannot be started again.

Calling this method when the connector server has already been stopped has no effect. Calling this method when the connector server has not yet been started will disable the connector server object permanently.

If closing a client connection produces an exception, that exception is not thrown from this method. A JMXConnectionNotification is emitted from this MBean with the connection ID of the connection that could not be closed.

Closing a connector server is a potentially slow operation. For example, if a client machine with an open connection has crashed, the close operation might have to wait for a network protocol timeout. Callers that do not want to block in a close operation should do it in a separate thread.

This method calls the method close on the connector server's RMIServerImpl object.

If the RMIServerImpl was bound to a JNDI directory by the start method, it is unbound from the directory by this method.

Throws:
IOException - if the server cannot be closed cleanly, or if the RMIServerImpl cannot be unbound from the directory. When this exception is thrown, the server has already attempted to close all client connections, if appropriate; to call RMIServerImpl.close(); and to unbind the RMIServerImpl from its directory, if appropriate. All client connections are closed except possibly those that generated exceptions when the server attempted to close them.

isActive

public boolean isActive()
Description copied from interface: JMXConnectorServerMBean

Determines whether the connector server is active. A connector server starts being active when its start method returns successfully and remains active until either its stop method is called or the connector server fails.

Returns:
true if the connector server is active.

getAddress

public JMXServiceURL getAddress()
Description copied from interface: JMXConnectorServerMBean

The address of this connector server.

Returns:
the address of this connector server, or null if it does not have one.

getAttributes

public Map<String,?> getAttributes()
Description copied from interface: JMXConnectorServerMBean

The attributes for this connector server.

Returns:
a read-only map containing the attributes for this connector server. Attributes whose values are not serializable are omitted from this map. If there are no serializable attributes, the returned map is empty.

setMBeanServerForwarder

public void setMBeanServerForwarder(MBeanServerForwarder mbsf)
Description copied from interface: JMXConnectorServerMBean

Adds an object that intercepts requests for the MBean server that arrive through this connector server. This object will be supplied as the MBeanServer for any new connection created by this connector server. Existing connections are unaffected.

If this connector server is already associated with an MBeanServer object, then that object is given to mbsf.setMBeanServer. If doing so produces an exception, this method throws the same exception without any other effect.

If this connector is not already associated with an MBeanServer object, or if the mbsf.setMBeanServer call just mentioned succeeds, then mbsf becomes this connector server's MBeanServer.

Specified by:
setMBeanServerForwarder in interface JMXConnectorServerMBean
Overrides:
setMBeanServerForwarder in class JMXConnectorServer
Parameters:
mbsf - the new MBeanServerForwarder.

connectionOpened

protected void connectionOpened(String connectionId,
                                String message,
                                Object userData)
Description copied from class: JMXConnectorServer

Called by a subclass when a new client connection is opened. Adds connectionId to the list returned by JMXConnectorServer.getConnectionIds(), then emits a JMXConnectionNotification with type JMXConnectionNotification.OPENED.

Overrides:
connectionOpened in class JMXConnectorServer
Parameters:
connectionId - the ID of the new connection. This must be different from the ID of any connection previously opened by this connector server.
message - the message for the emitted JMXConnectionNotification. Can be null. See Notification.getMessage().
userData - the userData for the emitted JMXConnectionNotification. Can be null. See Notification.getUserData().

connectionClosed

protected void connectionClosed(String connectionId,
                                String message,
                                Object userData)
Description copied from class: JMXConnectorServer

Called by a subclass when a client connection is closed normally. Removes connectionId from the list returned by JMXConnectorServer.getConnectionIds(), then emits a JMXConnectionNotification with type JMXConnectionNotification.CLOSED.

Overrides:
connectionClosed in class JMXConnectorServer
Parameters:
connectionId - the ID of the closed connection.
message - the message for the emitted JMXConnectionNotification. Can be null. See Notification.getMessage().
userData - the userData for the emitted JMXConnectionNotification. Can be null. See Notification.getUserData().

connectionFailed

protected void connectionFailed(String connectionId,
                                String message,
                                Object userData)
Description copied from class: JMXConnectorServer

Called by a subclass when a client connection fails. Removes connectionId from the list returned by JMXConnectorServer.getConnectionIds(), then emits a JMXConnectionNotification with type JMXConnectionNotification.FAILED.

Overrides:
connectionFailed in class JMXConnectorServer
Parameters:
connectionId - the ID of the failed connection.
message - the message for the emitted JMXConnectionNotification. Can be null. See Notification.getMessage().
userData - the userData for the emitted JMXConnectionNotification. Can be null. See Notification.getUserData().
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RMIIIOPServerImpl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote.rmi
Class RMIIIOPServerImpl

java.lang.Object
    extended by  javax.management.remote.rmi.RMIServerImpl
        extended by  javax.management.remote.rmi.RMIIIOPServerImpl
All Implemented Interfaces:
Closeable, Remote, RMIServer
public class RMIIIOPServerImpl
extends RMIServerImpl

An RMIServerImpl that is exported through IIOP and that creates client connections as RMI objects exported through IIOP. User code does not usually reference this class directly.

Since:
1.5
See Also:
RMIServerImpl

Constructor Summary
RMIIIOPServerImpl(Map<String,?> env)
Creates a new RMIServerImpl.
Method Summary
protected  void closeClient(RMIConnection client)
Closes a client connection made by makeClient.
protected  void closeServer()
Called by RMIServerImpl.close() to close the connector server by unexporting this object.
protected  void export()
Exports this RMI object.
protected  String getProtocol()
Returns the protocol string for this object.
protected  RMIConnection makeClient(String connectionId, Subject subject)
Creates a new client connection as an RMI object exported through IIOP.
 Remote toStub()
Returns an IIOP stub.
Methods inherited from class javax.management.remote.rmi.RMIServerImpl
clientClosed, close, getDefaultClassLoader, getMBeanServer, getVersion, newClient, setDefaultClassLoader, setMBeanServer
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RMIIIOPServerImpl

public RMIIIOPServerImpl(Map<String,?> env)
                  throws IOException

Creates a new RMIServerImpl.

Parameters:
env - the environment containing attributes for the new RMIServerImpl. Can be null, which is equivalent to an empty Map.
Throws:
IOException - if the RMI object cannot be created.
Method Detail

export

protected void export()
               throws IOException
Description copied from class: RMIServerImpl

Exports this RMI object.

Specified by:
export in class RMIServerImpl
Throws:
IOException - if this RMI object cannot be exported.

getProtocol

protected String getProtocol()
Description copied from class: RMIServerImpl

Returns the protocol string for this object. The string is rmi for RMI/JRMP and iiop for RMI/IIOP.

Specified by:
getProtocol in class RMIServerImpl
Returns:
the protocol string for this object.

toStub

public Remote toStub()
              throws IOException

Returns an IIOP stub.

The stub might not yet be connected to the ORB. The stub will be serializable only if it is connected to the ORB.

Specified by:
toStub in class RMIServerImpl
Returns:
an IIOP stub.
Throws:
IOException - if the stub cannot be created - e.g the RMIIIOPServerImpl has not been exported yet.

makeClient

protected RMIConnection makeClient(String connectionId,
                                   Subject subject)
                            throws IOException

Creates a new client connection as an RMI object exported through IIOP.

Specified by:
makeClient in class RMIServerImpl
Parameters:
connectionId - the ID of the new connection. Every connection opened by this connector server will have a different ID. The behavior is unspecified if this parameter is null.
subject - the authenticated subject. Can be null.
Returns:
the newly-created RMIConnection.
Throws:
IOException - if the new client object cannot be created or exported.

closeClient

protected void closeClient(RMIConnection client)
                    throws IOException
Description copied from class: RMIServerImpl

Closes a client connection made by makeClient.

Specified by:
closeClient in class RMIServerImpl
Parameters:
client - a connection previously returned by makeClient on which the closeClient method has not previously been called. The behavior is unspecified if these conditions are violated, including the case where client is null.
Throws:
IOException - if the client connection cannot be closed.

closeServer

protected void closeServer()
                    throws IOException

Called by RMIServerImpl.close() to close the connector server by unexporting this object. After returning from this method, the connector server must not accept any new connections.

Specified by:
closeServer in class RMIServerImpl
Throws:
IOException - if the attempt to close the connector server failed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RMIJRMPServerImpl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote.rmi
Class RMIJRMPServerImpl

java.lang.Object
    extended by  javax.management.remote.rmi.RMIServerImpl
        extended by  javax.management.remote.rmi.RMIJRMPServerImpl
All Implemented Interfaces:
Closeable, Remote, RMIServer
public class RMIJRMPServerImpl
extends RMIServerImpl

An RMIServer object that is exported through JRMP and that creates client connections as RMI objects exported through JRMP. User code does not usually reference this class directly.

Since:
1.5
See Also:
RMIServerImpl

Constructor Summary
RMIJRMPServerImpl(int port, RMIClientSocketFactory csf, RMIServerSocketFactory ssf, Map<String,?> env)
Creates a new RMIServer object that will be exported on the given port using the given socket factories.
Method Summary
protected  void closeClient(RMIConnection client)
Closes a client connection made by makeClient.
protected  void closeServer()
Called by RMIServerImpl.close() to close the connector server by unexporting this object.
protected  void export()
Exports this RMI object.
protected  String getProtocol()
Returns the protocol string for this object.
protected  RMIConnection makeClient(String connectionId, Subject subject)
Creates a new client connection as an RMI object exported through JRMP.
 Remote toStub()
Returns a serializable stub for this RMIServer object.
Methods inherited from class javax.management.remote.rmi.RMIServerImpl
clientClosed, close, getDefaultClassLoader, getMBeanServer, getVersion, newClient, setDefaultClassLoader, setMBeanServer
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RMIJRMPServerImpl

public RMIJRMPServerImpl(int port,
                         RMIClientSocketFactory csf,
                         RMIServerSocketFactory ssf,
                         Map<String,?> env)
                  throws IOException

Creates a new RMIServer object that will be exported on the given port using the given socket factories.

Parameters:
port - the port on which this object and the RMIConnectionImpl objects it creates will be exported. Can be zero, to indicate any available port.
csf - the client socket factory for the created RMI objects. Can be null.
ssf - the server socket factory for the created RMI objects. Can be null.
env - the environment map. Can be null.
Throws:
IOException - if the RMIServer object cannot be created.
IllegalArgumentException - if port is negative.
Method Detail

export

protected void export()
               throws IOException
Description copied from class: RMIServerImpl

Exports this RMI object.

Specified by:
export in class RMIServerImpl
Throws:
IOException - if this RMI object cannot be exported.

getProtocol

protected String getProtocol()
Description copied from class: RMIServerImpl

Returns the protocol string for this object. The string is rmi for RMI/JRMP and iiop for RMI/IIOP.

Specified by:
getProtocol in class RMIServerImpl
Returns:
the protocol string for this object.

toStub

public Remote toStub()
              throws IOException

Returns a serializable stub for this RMIServer object.

Specified by:
toStub in class RMIServerImpl
Returns:
a serializable stub.
Throws:
IOException - if the stub cannot be obtained - e.g the RMIJRMPServerImpl has not been exported yet.

makeClient

protected RMIConnection makeClient(String connectionId,
                                   Subject subject)
                            throws IOException

Creates a new client connection as an RMI object exported through JRMP. The port and socket factories for the new RMIConnection object are the ones supplied to the RMIJRMPServerImpl constructor.

Specified by:
makeClient in class RMIServerImpl
Parameters:
connectionId - the ID of the new connection. Every connection opened by this connector server will have a different id. The behavior is unspecified if this parameter is null.
subject - the authenticated subject. Can be null.
Returns:
the newly-created RMIConnection.
Throws:
IOException - if the new RMIConnection object cannot be created or exported.

closeClient

protected void closeClient(RMIConnection client)
                    throws IOException
Description copied from class: RMIServerImpl

Closes a client connection made by makeClient.

Specified by:
closeClient in class RMIServerImpl
Parameters:
client - a connection previously returned by makeClient on which the closeClient method has not previously been called. The behavior is unspecified if these conditions are violated, including the case where client is null.
Throws:
IOException - if the client connection cannot be closed.

closeServer

protected void closeServer()
                    throws IOException

Called by RMIServerImpl.close() to close the connector server by unexporting this object. After returning from this method, the connector server must not accept any new connections.

Specified by:
closeServer in class RMIServerImpl
Throws:
IOException - if the attempt to close the connector server failed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RMIServer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote.rmi
Interface RMIServer

All Superinterfaces:
Remote
All Known Implementing Classes:
RMIIIOPServerImpl, RMIJRMPServerImpl, RMIServerImpl, RMIServerImpl_Stub
public interface RMIServer
extends Remote

RMI object used to establish connections to an RMI connector. There is one Remote object implementing this interface for each RMI connector.

User code does not usually refer to this interface. It is specified as part of the public API so that different implementations of that API will interoperate.

Since:
1.5

Method Summary
String | getVersion() The version of the RMI Connector Protocol understood by this connector server.
RMIConnection | newClient(Object credentials) Makes a new connection through this RMI connector.

Method Detail

getVersion

String getVersion()
                  throws RemoteException

The version of the RMI Connector Protocol understood by this connector server. This is a string with the following format:

 protocol-version implementation-name

The protocol-version is a series of two or more non-negative integers separated by periods (.). An implementation of the version described by this documentation must use the string 1.0 here.

After the protocol version there must be a space, followed by the implementation name. The format of the implementation name is unspecified. It is recommended that it include an implementation version number. An implementation can use an empty string as its implementation name, for example for security reasons.

Returns:
a string with the format described here.
Throws:
RemoteException - if there is a communication exception during the remote method call.

newClient

RMIConnection newClient(Object credentials)
                        throws IOException

Makes a new connection through this RMI connector. Each remote client calls this method to obtain a new RMI object representing its connection.

Parameters:
credentials - this object specifies the user-defined credentials to be passed in to the server in order to authenticate the user before creating the RMIConnection. Can be null.
Returns:
the newly-created connection object.
Throws:
IOException - if the new client object cannot be created or exported, or if there is a communication exception during the remote method call.
SecurityException - if the given credentials do not allow the server to authenticate the caller successfully.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RMIServerImpl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote.rmi
Class RMIServerImpl

java.lang.Object
    extended by  javax.management.remote.rmi.RMIServerImpl
All Implemented Interfaces:
Closeable, Remote, RMIServer
Direct Known Subclasses:
RMIIIOPServerImpl, RMIJRMPServerImpl
public abstract class RMIServerImpl
extends Object
implements Closeable, RMIServer

An RMI object representing a connector server. Remote clients can make connections using the newClient(Object) method. This method returns an RMI object representing the connection.

User code does not usually reference this class directly. RMI connection servers are usually created with the class RMIConnectorServer. Remote clients usually create connections either with JMXConnectorFactory or by instantiating RMIConnector.

This is an abstract class. Concrete subclasses define the details of the client connection objects, such as whether they use JRMP or IIOP.

Since:
1.5

Constructor Summary
RMIServerImpl(Map<String,?> env)
Constructs a new RMIServerImpl.
Method Summary
protected  void clientClosed(RMIConnection client)
Method called when a client connection created by makeClient is closed.
 void close()
Closes this connection server.
protected abstract  void closeClient(RMIConnection client)
Closes a client connection made by makeClient.
protected abstract  void closeServer()
Called by close() to close the connector server.
protected abstract  void export()
Exports this RMI object.
 ClassLoader getDefaultClassLoader()
Gets the default ClassLoader used by this connector server.
 MBeanServer getMBeanServer()
The MBeanServer to which this connector server is attached.
protected abstract  String getProtocol()
Returns the protocol string for this object.
 String getVersion()
The version of the RMI Connector Protocol understood by this connector server.
protected abstract  RMIConnection makeClient(String connectionId, Subject subject)
Creates a new client connection.
 RMIConnection newClient(Object credentials)
Creates a new client connection.
 void setDefaultClassLoader(ClassLoader cl)
Sets the default ClassLoader for this connector server.
 void setMBeanServer(MBeanServer mbs)
Sets the MBeanServer to which this connector server is attached.
abstract  Remote toStub()
Returns a remotable stub for this server object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RMIServerImpl

public RMIServerImpl(Map<String,?> env)

Constructs a new RMIServerImpl.

Parameters:
env - the environment containing attributes for the new RMIServerImpl. Can be null, which is equivalent to an empty Map.
Method Detail

export

protected abstract void export()
                        throws IOException

Exports this RMI object.

Throws:
IOException - if this RMI object cannot be exported.

toStub

public abstract Remote toStub()
                       throws IOException
Returns a remotable stub for this server object.

Returns:
a remotable stub.
Throws:
IOException - if the stub cannot be obtained - e.g the RMIServerImpl has not been exported yet.

setDefaultClassLoader

public void setDefaultClassLoader(ClassLoader cl)

Sets the default ClassLoader for this connector server. New client connections will use this classloader. Existing client connections are unaffected.

Parameters:
cl - the new ClassLoader to be used by this connector server.
See Also:
getDefaultClassLoader()

getDefaultClassLoader

public ClassLoader getDefaultClassLoader()

Gets the default ClassLoader used by this connector server.

Returns:
the default ClassLoader used by this connector server.

See Also:
setDefaultClassLoader(java.lang.ClassLoader)

setMBeanServer

public void setMBeanServer(MBeanServer mbs)

Sets the MBeanServer to which this connector server is attached. New client connections will interact with this MBeanServer. Existing client connections are unaffected.

Parameters:
mbs - the new MBeanServer. Can be null, but new client connections will be refused as long as it is.
See Also:
getMBeanServer()

getMBeanServer

public MBeanServer getMBeanServer()

The MBeanServer to which this connector server is attached. This is the last value passed to setMBeanServer(javax.management.MBeanServer) on this object, or null if that method has never been called.

Returns:
the MBeanServer to which this connector is attached.
See Also:
setMBeanServer(javax.management.MBeanServer)

getVersion

public String getVersion()
Description copied from interface: RMIServer

The version of the RMI Connector Protocol understood by this connector server. This is a string with the following format:

 protocol-version implementation-name

The protocol-version is a series of two or more non-negative integers separated by periods (.). An implementation of the version described by this documentation must use the string 1.0 here.

After the protocol version there must be a space, followed by the implementation name. The format of the implementation name is unspecified. It is recommended that it include an implementation version number. An implementation can use an empty string as its implementation name, for example for security reasons.

Specified by:
getVersion in interface RMIServer
Returns:
a string with the format described here.

newClient

public RMIConnection newClient(Object credentials)
                        throws IOException

Creates a new client connection. This method calls makeClient and adds the returned client connection object to an internal list. When this RMIServerImpl is shut down via its close() method, the close() method of each object remaining in the list is called.

The fact that a client connection object is in this internal list does not prevent it from being garbage collected.

Specified by:
newClient in interface RMIServer
Parameters:
credentials - this object specifies the user-defined credentials to be passed in to the server in order to authenticate the caller before creating the RMIConnection. Can be null.
Returns:
the newly-created RMIConnection. This is usually the object created by makeClient, though an implementation may choose to wrap that object in another object implementing RMIConnection.
Throws:
IOException - if the new client object cannot be created or exported.
SecurityException - if the given credentials do not allow the server to authenticate the user successfully.
IllegalStateException - if getMBeanServer() is null.

makeClient

protected abstract RMIConnection makeClient(String connectionId,
                                            Subject subject)
                                     throws IOException

Creates a new client connection. This method is called by the public method newClient(Object).

Parameters:
connectionId - the ID of the new connection. Every connection opened by this connector server will have a different ID. The behavior is unspecified if this parameter is null.
subject - the authenticated subject. Can be null.
Returns:
the newly-created RMIConnection.
Throws:
IOException - if the new client object cannot be created or exported.

closeClient

protected abstract void closeClient(RMIConnection client)
                             throws IOException

Closes a client connection made by makeClient.

Parameters:
client - a connection previously returned by makeClient on which the closeClient method has not previously been called. The behavior is unspecified if these conditions are violated, including the case where client is null.
Throws:
IOException - if the client connection cannot be closed.

getProtocol

protected abstract String getProtocol()

Returns the protocol string for this object. The string is rmi for RMI/JRMP and iiop for RMI/IIOP.

Returns:
the protocol string for this object.

clientClosed

protected void clientClosed(RMIConnection client)
                     throws IOException

Method called when a client connection created by makeClient is closed. A subclass that defines makeClient must arrange for this method to be called when the resultant object's close method is called. This enables it to be removed from the RMIServerImpl's list of connections. It is not an error for client not to be in that list.

After removing client from the list of connections, this method calls closeClient(client).

Parameters:
client - the client connection that has been closed.
Throws:
IOException - if closeClient(javax.management.remote.rmi.RMIConnection) throws this exception.
NullPointerException - if client is null.

close

public void close()
           throws IOException

Closes this connection server. This method first calls the closeServer() method so that no new client connections will be accepted. Then, for each remaining RMIConnection object returned by makeClient, its close method is called.

The behavior when this method is called more than once is unspecified.

If closeServer() throws an IOException, the individual connections are nevertheless closed, and then the IOException is thrown from this method.

If closeServer() returns normally but one or more of the individual connections throws an IOException, then, after closing all the connections, one of those IOExceptions is thrown from this method. If more than one connection throws an IOException, it is unspecified which one is thrown from this method.

Specified by:
close in interface Closeable
Throws:
IOException - if closeServer() or one of the RMIConnection.close() calls threw IOException.

closeServer

protected abstract void closeServer()
                             throws IOException

Called by close() to close the connector server. After returning from this method, the connector server must not accept any new connections.

Throws:
IOException - if the attempt to close the connector server failed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RMIServerImpl_Stub

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.management.remote.rmi
Class RMIServerImpl_Stub

java.lang.Object
    extended by  java.rmi.server.RemoteObject
        extended by  java.rmi.server.RemoteStub
            extended by  javax.management.remote.rmi.RMIServerImpl_Stub
All Implemented Interfaces:
Serializable, Remote, RMIServer
public final class RMIServerImpl_Stub
extends RemoteStub
implements RMIServer

See Also:
Serialized Form

Field Summary
Fields inherited from class java.rmi.server.RemoteObject
ref
Constructor Summary
RMIServerImpl_Stub(RemoteRef ref)
Method Summary
String | getVersion() The version of the RMI Connector Protocol understood by this connector server.
RMIConnection | newClient(Object $param_Object_1) Makes a new connection through this RMI connector.
Methods inherited from class java.rmi.server.RemoteStub
setRef
Methods inherited from class java.rmi.server.RemoteObject
equals, getRef, hashCode, toString, toStub
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

RMIServerImpl_Stub

public RMIServerImpl_Stub(RemoteRef ref)
Method Detail

getVersion

public String getVersion()
                  throws RemoteException
Description copied from interface: RMIServer

The version of the RMI Connector Protocol understood by this connector server. This is a string with the following format:

 protocol-version implementation-name

The protocol-version is a series of two or more non-negative integers separated by periods (.). An implementation of the version described by this documentation must use the string 1.0 here.

After the protocol version there must be a space, followed by the implementation name. The format of the implementation name is unspecified. It is recommended that it include an implementation version number. An implementation can use an empty string as its implementation name, for example for security reasons.

Specified by:
getVersion in interface RMIServer
Returns:
a string with the format described here.
Throws:
RemoteException - if there is a communication exception during the remote method call.

newClient

public RMIConnection newClient(Object $param_Object_1)
                        throws IOException
Description copied from interface: RMIServer

Makes a new connection through this RMI connector. Each remote client calls this method to obtain a new RMI object representing its connection.

Specified by:
newClient in interface RMIServer
Parameters:
$param_Object_1 - this object specifies the user-defined credentials to be passed in to the server in order to authenticate the user before creating the RMIConnection. Can be null.
Returns:
the newly-created connection object.
Throws:
IOException - if the new client object cannot be created or exported, or if there is a communication exception during the remote method call.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


SubjectDelegationPermission

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Class SubjectDelegationPermission

java.lang.Object
    extended by  java.security.Permission
        extended by  java.security.BasicPermission
            extended by  javax.management.remote.SubjectDelegationPermission
All Implemented Interfaces:
Serializable, Guard
public final class SubjectDelegationPermission
extends BasicPermission

Permission required by an authentication identity to perform operations on behalf of an authorization identity.

A SubjectDelegationPermission contains a name (also referred to as a "target name") but no actions list; you either have the named permission or you don't.

The target name is the name of the authorization principal classname followed by a period and the authorization principal name, that is "PrincipalClassName.PrincipalName".

An asterisk may appear by itself, or if immediately preceded by a "." may appear at the end of the target name, to signify a wildcard match.

For example, "*", "javax.management.remote.JMXPrincipal.*" and "javax.management.remote.JMXPrincipal.delegate" are valid target names. The first one denotes any principal name from any principal class, the second one denotes any principal name of the concrete principal class javax.management.remote.JMXPrincipal and the third one denotes a concrete principal name delegate of the concrete principal class javax.management.remote.JMXPrincipal.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
SubjectDelegationPermission(String name)
Creates a new SubjectDelegationPermission with the specified name.
SubjectDelegationPermission(String name, String actions)
Creates a new SubjectDelegationPermission object with the specified name.
Method Summary
Methods inherited from class java.security.BasicPermission
equals, getActions, hashCode, implies, newPermissionCollection
Methods inherited from class java.security.Permission
checkGuard, getName, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

SubjectDelegationPermission

public SubjectDelegationPermission(String name)
Creates a new SubjectDelegationPermission with the specified name. The name is the symbolic name of the SubjectDelegationPermission.

Parameters:
name - the name of the SubjectDelegationPermission
Throws:
NullPointerException - if name is null.
IllegalArgumentException - if name is empty.

SubjectDelegationPermission

public SubjectDelegationPermission(String name,
                                   String actions)
Creates a new SubjectDelegationPermission object with the specified name. The name is the symbolic name of the SubjectDelegationPermission, and the actions String is currently unused and must be null.

Parameters:
name - the name of the SubjectDelegationPermission
actions - must be null.
Throws:
NullPointerException - if name is null.
IllegalArgumentException - if name is empty or actions is not null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TargetedNotification

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.management.remote
Class TargetedNotification

java.lang.Object
    extended by  javax.management.remote.TargetedNotification
All Implemented Interfaces:
Serializable
public class TargetedNotification
extends Object
implements Serializable

A (Notification, Listener ID) pair.

This class is used to associate an emitted notification with the listener ID to which it is targeted.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
TargetedNotification(Notification notification, Integer listenerID)
Constructs a TargetedNotification object.
Method Summary
Integer | getListenerID() The ID of the listener to which the notification is targeted.
Notification | getNotification() The emitted notification.
String | toString() Returns a textual representation of this Targeted Notification.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TargetedNotification

public TargetedNotification(Notification notification,
                            Integer listenerID)

Constructs a TargetedNotification object. The object contains a pair (Notification, Listener ID). The Listener ID identifies the client listener to which that notification is targeted. The client listener ID is one previously returned by the connector server in response to an addNotificationListener request.

Parameters:
notification - Notification emitted from the MBean server.
listenerID - The ID of the listener to which this notification is targeted.
Throws:
IllegalArgumentException - if the listenerID or notification is null.
Method Detail

getNotification

public Notification getNotification()

The emitted notification.

Returns:
The notification.

getListenerID

public Integer getListenerID()

The ID of the listener to which the notification is targeted.

Returns:
The listener ID.

toString

public String toString()
Returns a textual representation of this Targeted Notification.

Overrides:
toString in class Object
Returns:
a String representation of this Targeted Notification.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


RuntimeErrorException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class RuntimeErrorException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  javax.management.JMRuntimeException
                    extended by  javax.management.RuntimeErrorException
All Implemented Interfaces:
Serializable
public class RuntimeErrorException
extends JMRuntimeException

When a java.lang.Error occurs in the agent it should be caught and re-thrown as a RuntimeErrorException.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
RuntimeErrorException(Error e)
Default constructor.
RuntimeErrorException(Error e, String message)
Constructor that allows a specific error message to be specified.
Method Summary
Throwable | getCause() Returns the actual Error thrown.
Error | getTargetError() Returns the actual Error thrown.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RuntimeErrorException

public RuntimeErrorException(Error e)
Default constructor.

Parameters:
e - the wrapped error.

RuntimeErrorException

public RuntimeErrorException(Error e,
                             String message)
Constructor that allows a specific error message to be specified.

Parameters:
e - the wrapped error.
message - the detail message.
Method Detail

getTargetError

public Error getTargetError()
Returns the actual Error thrown.

Returns:
the wrapped Error.

getCause

public Throwable getCause()
Returns the actual Error thrown.

Overrides:
getCause in class Throwable
Returns:
the wrapped Error.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RuntimeMBeanException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class RuntimeMBeanException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  javax.management.JMRuntimeException
                    extended by  javax.management.RuntimeMBeanException
All Implemented Interfaces:
Serializable
public class RuntimeMBeanException
extends JMRuntimeException

Represents runtime exceptions thrown by MBean methods in the agent. It "wraps" the actual java.lang.RuntimeException exception thrown. This exception will be built by the MBeanServer when a call to an MBean method throws a runtime exception.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
RuntimeMBeanException(RuntimeException e)
Creates a RuntimeMBeanException that wraps the actual java.lang.RuntimeException.
RuntimeMBeanException(RuntimeException e, String message)
Creates a RuntimeMBeanException that wraps the actual java.lang.RuntimeException with a detailed message.
Method Summary
Throwable | getCause() Returns the actual RuntimeException thrown.
RuntimeException | getTargetException() Returns the actual RuntimeException thrown.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RuntimeMBeanException

public RuntimeMBeanException(RuntimeException e)
Creates a RuntimeMBeanException that wraps the actual java.lang.RuntimeException.

Parameters:
e - the wrapped exception.

RuntimeMBeanException

public RuntimeMBeanException(RuntimeException e,
                             String message)
Creates a RuntimeMBeanException that wraps the actual java.lang.RuntimeException with a detailed message.

Parameters:
e - the wrapped exception.
message - the detail message.
Method Detail

getTargetException

public RuntimeException getTargetException()
Returns the actual RuntimeException thrown.

Returns:
the wrapped RuntimeException.

getCause

public Throwable getCause()
Returns the actual RuntimeException thrown.

Overrides:
getCause in class Throwable
Returns:
the wrapped RuntimeException.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RuntimeOperationsException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class RuntimeOperationsException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  javax.management.JMRuntimeException
                    extended by  javax.management.RuntimeOperationsException
All Implemented Interfaces:
Serializable
public class RuntimeOperationsException
extends JMRuntimeException

Represents runtime exceptions thrown in the agent when performing operations on MBeans. It wraps the actual java.lang.RuntimeException thrown.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
RuntimeOperationsException(RuntimeException e)
Creates a RuntimeOperationsException that wraps the actual java.lang.RuntimeException.
RuntimeOperationsException(RuntimeException e, String message)
Creates a RuntimeOperationsException that wraps the actual java.lang.RuntimeException with a detailed message.
Method Summary
Throwable | getCause() Returns the actual RuntimeException thrown.
RuntimeException | getTargetException() Returns the actual RuntimeException thrown.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RuntimeOperationsException

public RuntimeOperationsException(RuntimeException e)
Creates a RuntimeOperationsException that wraps the actual java.lang.RuntimeException.

Parameters:
e - the wrapped exception.

RuntimeOperationsException

public RuntimeOperationsException(RuntimeException e,
                                  String message)
Creates a RuntimeOperationsException that wraps the actual java.lang.RuntimeException with a detailed message.

Parameters:
e - the wrapped exception.
message - the detail message.
Method Detail

getTargetException

public RuntimeException getTargetException()
Returns the actual RuntimeException thrown.

Returns:
the wrapped RuntimeException.

getCause

public Throwable getCause()
Returns the actual RuntimeException thrown.

Overrides:
getCause in class Throwable
Returns:
the wrapped RuntimeException.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServiceNotFoundException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class ServiceNotFoundException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.management.JMException
                extended by  javax.management.OperationsException
                    extended by  javax.management.ServiceNotFoundException
All Implemented Interfaces:
Serializable
public class ServiceNotFoundException
extends OperationsException

Represents exceptions raised when a requested service is not supported.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
ServiceNotFoundException()
Default constructor.
ServiceNotFoundException(String message)
Constructor that allows a specific error message to be specified.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ServiceNotFoundException

public ServiceNotFoundException()
Default constructor.

ServiceNotFoundException

public ServiceNotFoundException(String message)
Constructor that allows a specific error message to be specified.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StandardEmitterMBean

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class StandardEmitterMBean

java.lang.Object
    extended by  javax.management.StandardMBean
        extended by  javax.management.StandardEmitterMBean
All Implemented Interfaces:
DynamicMBean, MBeanRegistration, NotificationBroadcaster, NotificationEmitter
public class StandardEmitterMBean
extends StandardMBean
implements NotificationEmitter

An MBean whose management interface is determined by reflection on a Java interface, and that emits notifications.

The following example shows how to use the public constructor StandardEmitterMBean(implementation, mbeanInterface, emitter) to create an MBean emitting notifications with any implementation class name Impl, with a management interface defined (as for current Standard MBeans) by any interface Intf, and with any implementation of the interface NotificationEmitter. The example uses the class NotificationBroadcasterSupport as an implementation of the interface NotificationEmitter.

     MBeanServer mbs;
     ...
     final String[] types = new String[] {"sun.disc.space","sun.disc.alarm"};
     final MBeanNotificationInfo info = new MBeanNotificationInfo(
                                          types,
                                          Notification.class.getName(),
                                          "Notification about disc info.");
     final NotificationEmitter emitter =
                    new NotificationBroadcasterSupport(info);

     final Intf impl = new Impl(...);
     final Object mbean = new StandardEmitterMBean(
                                     impl, Intf.class, emitter);
     mbs.registerMBean(mbean, objectName);

Since:
1.6
See Also:
StandardMBean

Constructor Summary
protected | StandardEmitterMBean(Class<?> mbeanInterface, boolean isMXBean, NotificationEmitter emitter) Make an MBean whose management interface is specified by mbeanInterface, and where notifications are handled by the given NotificationEmitter.
protected | StandardEmitterMBean(Class<?> mbeanInterface, NotificationEmitter emitter) Make an MBean whose management interface is specified by mbeanInterface, and where notifications are handled by the given NotificationEmitter.
 | StandardEmitterMBean(T implementation, Class<T> mbeanInterface, boolean isMXBean, NotificationEmitter emitter) Make an MBean whose management interface is specified by mbeanInterface, with the given implementation and where notifications are handled by the given NotificationEmitter.
 | StandardEmitterMBean(T implementation, Class<T> mbeanInterface, NotificationEmitter emitter) Make an MBean whose management interface is specified by mbeanInterface, with the given implementation and where notifications are handled by the given NotificationEmitter.
Method Summary
void | addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Adds a listener to this MBean.
MBeanNotificationInfo[] | getNotificationInfo() Returns an array indicating, for each notification this MBean may send, the name of the Java class of the notification and the notification type.
void | removeNotificationListener(NotificationListener listener) Removes a listener from this MBean.
void | removeNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Removes a listener from this MBean.
void | sendNotification(Notification n) Sends a notification.
Methods inherited from class javax.management.StandardMBean
cacheMBeanInfo, getAttribute, getAttributes, getCachedMBeanInfo, getClassName, getConstructors, getDescription, getDescription, getDescription, getDescription, getDescription, getDescription, getDescription, getImpact, getImplementation, getImplementationClass, getMBeanInfo, getMBeanInterface, getParameterName, getParameterName, invoke, postDeregister, postRegister, preDeregister, preRegister, setAttribute, setAttributes, setImplementation
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StandardEmitterMBean

public StandardEmitterMBean(T implementation,
                            Class<T> mbeanInterface,
                            NotificationEmitter emitter)

Make an MBean whose management interface is specified by mbeanInterface, with the given implementation and where notifications are handled by the given NotificationEmitter. The resultant MBean implements the NotificationEmitter interface by forwarding its methods to emitter. It is legal and useful for implementation and emitter to be the same object.

If emitter is an instance of NotificationBroadcasterSupport then the MBean's sendNotification method will call emitter. sendNotification.

The array returned by getNotificationInfo() on the new MBean is a copy of the array returned by emitter. getNotificationInfo() at the time of construction. If the array returned by emitter.getNotificationInfo() later changes, that will have no effect on this object's getNotificationInfo().

Parameters:
implementation - the implementation of the MBean interface.
mbeanInterface - a Standard MBean interface.
emitter - the object that will handle notifications.
Throws:
IllegalArgumentException - if the mbeanInterface does not follow JMX design patterns for Management Interfaces, or if the given implementation does not implement the specified interface, or if emitter is null.

StandardEmitterMBean

public StandardEmitterMBean(T implementation,
                            Class<T> mbeanInterface,
                            boolean isMXBean,
                            NotificationEmitter emitter)

Make an MBean whose management interface is specified by mbeanInterface, with the given implementation and where notifications are handled by the given NotificationEmitter. This constructor can be used to make either Standard MBeans or MXBeans. The resultant MBean implements the NotificationEmitter interface by forwarding its methods to emitter. It is legal and useful for implementation and emitter to be the same object.

If emitter is an instance of NotificationBroadcasterSupport then the MBean's sendNotification method will call emitter. sendNotification.

The array returned by getNotificationInfo() on the new MBean is a copy of the array returned by emitter. getNotificationInfo() at the time of construction. If the array returned by emitter.getNotificationInfo() later changes, that will have no effect on this object's getNotificationInfo().

Parameters:
implementation - the implementation of the MBean interface.
mbeanInterface - a Standard MBean interface.
isMXBean - If true, the mbeanInterface parameter names an MXBean interface and the resultant MBean is an MXBean.
emitter - the object that will handle notifications.
Throws:
IllegalArgumentException - if the mbeanInterface does not follow JMX design patterns for Management Interfaces, or if the given implementation does not implement the specified interface, or if emitter is null.

StandardEmitterMBean

protected StandardEmitterMBean(Class<?> mbeanInterface,
                               NotificationEmitter emitter)

Make an MBean whose management interface is specified by mbeanInterface, and where notifications are handled by the given NotificationEmitter. The resultant MBean implements the NotificationEmitter interface by forwarding its methods to emitter.

If emitter is an instance of NotificationBroadcasterSupport then the MBean's sendNotification method will call emitter. sendNotification.

The array returned by getNotificationInfo() on the new MBean is a copy of the array returned by emitter. getNotificationInfo() at the time of construction. If the array returned by emitter.getNotificationInfo() later changes, that will have no effect on this object's getNotificationInfo().

This constructor must be called from a subclass that implements the given mbeanInterface.

Parameters:
mbeanInterface - a StandardMBean interface.
emitter - the object that will handle notifications.
Throws:
IllegalArgumentException - if the mbeanInterface does not follow JMX design patterns for Management Interfaces, or if this does not implement the specified interface, or if emitter is null.

StandardEmitterMBean

protected StandardEmitterMBean(Class<?> mbeanInterface,
                               boolean isMXBean,
                               NotificationEmitter emitter)

Make an MBean whose management interface is specified by mbeanInterface, and where notifications are handled by the given NotificationEmitter. This constructor can be used to make either Standard MBeans or MXBeans. The resultant MBean implements the NotificationEmitter interface by forwarding its methods to emitter.

If emitter is an instance of NotificationBroadcasterSupport then the MBean's sendNotification method will call emitter. sendNotification.

The array returned by getNotificationInfo() on the new MBean is a copy of the array returned by emitter. getNotificationInfo() at the time of construction. If the array returned by emitter.getNotificationInfo() later changes, that will have no effect on this object's getNotificationInfo().

This constructor must be called from a subclass that implements the given mbeanInterface.

Parameters:
mbeanInterface - a StandardMBean interface.
isMXBean - If true, the mbeanInterface parameter names an MXBean interface and the resultant MBean is an MXBean.
emitter - the object that will handle notifications.
Throws:
IllegalArgumentException - if the mbeanInterface does not follow JMX design patterns for Management Interfaces, or if this does not implement the specified interface, or if emitter is null.
Method Detail

removeNotificationListener

public void removeNotificationListener(NotificationListener listener)
                                throws ListenerNotFoundException
Description copied from interface: NotificationBroadcaster
Removes a listener from this MBean. If the listener has been registered with different handback objects or notification filters, all entries corresponding to the listener will be removed.

Specified by:
removeNotificationListener in interface NotificationBroadcaster
Parameters:
listener - A listener that was previously added to this MBean.
Throws:
ListenerNotFoundException - The listener is not registered with the MBean.
See Also:
NotificationBroadcaster.addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object), NotificationEmitter.removeNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

removeNotificationListener

public void removeNotificationListener(NotificationListener listener,
                                       NotificationFilter filter,
                                       Object handback)
                                throws ListenerNotFoundException
Description copied from interface: NotificationEmitter

Removes a listener from this MBean. The MBean must have a listener that exactly matches the given listener, filter, and handback parameters. If there is more than one such listener, only one is removed.

The filter and handback parameters may be null if and only if they are null in a listener to be removed.

Specified by:
removeNotificationListener in interface NotificationEmitter
Parameters:
listener - A listener that was previously added to this MBean.
filter - The filter that was specified when the listener was added.
handback - The handback that was specified when the listener was added.
Throws:
ListenerNotFoundException - The listener is not registered with the MBean, or it is not registered with the given filter and handback.

addNotificationListener

public void addNotificationListener(NotificationListener listener,
                                    NotificationFilter filter,
                                    Object handback)
Description copied from interface: NotificationBroadcaster
Adds a listener to this MBean.

Specified by:
addNotificationListener in interface NotificationBroadcaster
Parameters:
listener - The listener object which will handle the notifications emitted by the broadcaster.
filter - The filter object. If filter is null, no filtering will be performed before handling notifications.
handback - An opaque object to be sent back to the listener when a notification is emitted. This object cannot be used by the Notification broadcaster object. It should be resent unchanged with the notification to the listener.
See Also:
NotificationBroadcaster.removeNotificationListener(javax.management.NotificationListener)

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()
Description copied from interface: NotificationBroadcaster

Returns an array indicating, for each notification this MBean may send, the name of the Java class of the notification and the notification type.

It is not illegal for the MBean to send notifications not described in this array. However, some clients of the MBean server may depend on the array being complete for their correct functioning.

Specified by:
getNotificationInfo in interface NotificationBroadcaster
Returns:
the array of possible notifications.

sendNotification

public void sendNotification(Notification n)

Sends a notification.

If the emitter parameter to the constructor was an instance of NotificationBroadcasterSupport then this method will call emitter. sendNotification.

Parameters:
n - the notification to send.
Throws:
ClassCastException - if the emitter parameter to the constructor was not a NotificationBroadcasterSupport.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StandardMBean

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class StandardMBean

java.lang.Object
    extended by  javax.management.StandardMBean
All Implemented Interfaces:
DynamicMBean, MBeanRegistration
Direct Known Subclasses:
StandardEmitterMBean
public class StandardMBean
extends Object
implements DynamicMBean, MBeanRegistration

An MBean whose management interface is determined by reflection on a Java interface.

This class brings more flexibility to the notion of Management Interface in the use of Standard MBeans. Straightforward use of the patterns for Standard MBeans described in the JMX Specification means that there is a fixed relationship between the implementation class of an MBean and its management interface (i.e., if the implementation class is Thing, the management interface must be ThingMBean). This class makes it possible to keep the convenience of specifying the management interface with a Java interface, without requiring that there be any naming relationship between the implementation and interface classes.

By making a DynamicMBean out of an MBean, this class makes it possible to select any interface implemented by the MBean as its management interface, provided that it complies with JMX patterns (i.e., attributes defined by getter/setter etc...).

This class also provides hooks that make it possible to supply custom descriptions and names for the MBeanInfo returned by the DynamicMBean interface.

Using this class, an MBean can be created with any implementation class name Impl and with a management interface defined (as for current Standard MBeans) by any interface Intf, in one of two general ways:

  • Using the public constructor StandardMBean(impl,interface):
         MBeanServer mbs;
     ...
     Impl impl = new Impl(...);
     StandardMBean mbean = new StandardMBean(impl, Intf.class, false);
     mbs.registerMBean(mbean, objectName);
  • Subclassing StandardMBean:
         public class Impl extends StandardMBean implements Intf {
        public Impl() {
          super(Intf.class, false);
       }
       // implement methods of Intf
     }

     [...]

     MBeanServer mbs;
     ....
     Impl impl = new Impl();
     mbs.registerMBean(impl, objectName);

In either case, the class Impl must implement the interface Intf.

Standard MBeans based on the naming relationship between implementation and interface classes are of course still available.

This class may also be used to construct MXBeans. The usage is exactly the same as for Standard MBeans except that in the examples above, the false parameter to the constructor or super(...) invocation is instead true.

Since:
1.5

Constructor Summary
protected | StandardMBean(Class<?> mbeanInterface) Make a DynamicMBean out of this, using the specified mbeanInterface class.
protected | StandardMBean(Class<?> mbeanInterface, boolean isMXBean) Make a DynamicMBean out of this, using the specified mbeanInterface class.
 | StandardMBean(T implementation, Class<T> mbeanInterface) Make a DynamicMBean out of the object implementation, using the specified mbeanInterface class.
 | StandardMBean(T implementation, Class<T> mbeanInterface, boolean isMXBean) Make a DynamicMBean out of the object implementation, using the specified mbeanInterface class.
Method Summary
protected void | cacheMBeanInfo(MBeanInfo info) Customization hook: cache the MBeanInfo built for this object.
Object | getAttribute(String attribute) Obtain the value of a specific attribute of the Dynamic MBean.
AttributeList | getAttributes(String[] attributes) Get the values of several attributes of the Dynamic MBean.
protected MBeanInfo | getCachedMBeanInfo() Customization hook: Return the MBeanInfo cached for this object.
protected String | getClassName(MBeanInfo info) Customization hook: Get the className that will be used in the MBeanInfo returned by this MBean.
protected MBeanConstructorInfo[] | getConstructors(MBeanConstructorInfo[] ctors, Object impl) Customization hook: Get the MBeanConstructorInfo[] that will be used in the MBeanInfo returned by this MBean.
protected String | getDescription(MBeanAttributeInfo info) Customization hook: Get the description that will be used in the MBeanAttributeInfo returned by this MBean.
protected String | getDescription(MBeanConstructorInfo info) Customization hook: Get the description that will be used in the MBeanConstructorInfo returned by this MBean.
protected String | getDescription(MBeanConstructorInfo ctor, MBeanParameterInfo param, int sequence) Customization hook: Get the description that will be used for the sequence MBeanParameterInfo of the MBeanConstructorInfo returned by this MBean.
protected String | getDescription(MBeanFeatureInfo info) Customization hook: Get the description that will be used in the MBeanFeatureInfo returned by this MBean.
protected String | getDescription(MBeanInfo info) Customization hook: Get the description that will be used in the MBeanInfo returned by this MBean.
protected String | getDescription(MBeanOperationInfo info) Customization hook: Get the description that will be used in the MBeanOperationInfo returned by this MBean.
protected String | getDescription(MBeanOperationInfo op, MBeanParameterInfo param, int sequence) Customization hook: Get the description that will be used for the sequence MBeanParameterInfo of the MBeanOperationInfo returned by this MBean.
protected int | getImpact(MBeanOperationInfo info) Customization hook: Get the impact flag of the operation that will be used in the MBeanOperationInfo returned by this MBean.
Object | getImplementation() Get the implementation of this Standard MBean (or MXBean).
Class<?> | getImplementationClass() Get the class of the implementation of this Standard MBean (or MXBean).
MBeanInfo | getMBeanInfo() Get the MBeanInfo for this MBean.
Class<?> | getMBeanInterface() Get the Management Interface of this Standard MBean (or MXBean).
protected String | getParameterName(MBeanConstructorInfo ctor, MBeanParameterInfo param, int sequence) Customization hook: Get the name that will be used for the sequence MBeanParameterInfo of the MBeanConstructorInfo returned by this MBean.
protected String | getParameterName(MBeanOperationInfo op, MBeanParameterInfo param, int sequence) Customization hook: Get the name that will be used for the sequence MBeanParameterInfo of the MBeanOperationInfo returned by this MBean.
Object | invoke(String actionName, Object[] params, String[] signature) Allows an action to be invoked on the Dynamic MBean.
void | postDeregister() Allows the MBean to perform any operations needed after having been unregistered in the MBean server.
void | postRegister(Boolean registrationDone) Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.
void | preDeregister() Allows the MBean to perform any operations it needs before being unregistered by the MBean server.
ObjectName | preRegister(MBeanServer server, ObjectName name) Allows the MBean to perform any operations it needs before being registered in the MBean server.
void | setAttribute(Attribute attribute) Set the value of a specific attribute of the Dynamic MBean.
AttributeList | setAttributes(AttributeList attributes) Sets the values of several attributes of the Dynamic MBean.
void | setImplementation(Object implementation) Replace the implementation object wrapped in this object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StandardMBean

public StandardMBean(T implementation,
                     Class<T> mbeanInterface)
              throws NotCompliantMBeanException

Make a DynamicMBean out of the object implementation, using the specified mbeanInterface class.

Type Parameters:
T - Allows the compiler to check that implementation does indeed implement the class described by mbeanInterface. The compiler can only check this if mbeanInterface is a class literal such as MyMBean.class.
Parameters:
implementation - The implementation of this MBean.
mbeanInterface - The Management Interface exported by this MBean's implementation. If null, then this object will use standard JMX design pattern to determine the management interface associated with the given implementation.
Throws:
IllegalArgumentException - if the given implementation is null.
NotCompliantMBeanException - if the mbeanInterface does not follow JMX design patterns for Management Interfaces, or if the given implementation does not implement the specified interface.

StandardMBean

protected StandardMBean(Class<?> mbeanInterface)
                 throws NotCompliantMBeanException

Make a DynamicMBean out of this, using the specified mbeanInterface class.

Call this(this,mbeanInterface). This constructor is reserved to subclasses.

Parameters:
mbeanInterface - The Management Interface exported by this MBean.
Throws:
NotCompliantMBeanException - if the mbeanInterface does not follow JMX design patterns for Management Interfaces, or if this does not implement the specified interface.

StandardMBean

public StandardMBean(T implementation,
                     Class<T> mbeanInterface,
                     boolean isMXBean)

Make a DynamicMBean out of the object implementation, using the specified mbeanInterface class. This constructor can be used to make either Standard MBeans or MXBeans. Unlike the constructor StandardMBean(Object, Class), it does not throw NotCompliantMBeanException.

Type Parameters:
T - Allows the compiler to check that implementation does indeed implement the class described by mbeanInterface. The compiler can only check this if mbeanInterface is a class literal such as MyMBean.class.
Parameters:
implementation - The implementation of this MBean.
mbeanInterface - The Management Interface exported by this MBean's implementation. If null, then this object will use standard JMX design pattern to determine the management interface associated with the given implementation.
isMXBean - If true, the mbeanInterface parameter names an MXBean interface and the resultant MBean is an MXBean.
Throws:
IllegalArgumentException - if the given implementation is null, or if the mbeanInterface does not follow JMX design patterns for Management Interfaces, or if the given implementation does not implement the specified interface.
Since:
1.6

StandardMBean

protected StandardMBean(Class<?> mbeanInterface,
                        boolean isMXBean)

Make a DynamicMBean out of this, using the specified mbeanInterface class. This constructor can be used to make either Standard MBeans or MXBeans. Unlike the constructor StandardMBean(Object, Class), it does not throw NotCompliantMBeanException.

Call this(this, mbeanInterface, isMXBean). This constructor is reserved to subclasses.

Parameters:
mbeanInterface - The Management Interface exported by this MBean.
isMXBean - If true, the mbeanInterface parameter names an MXBean interface and the resultant MBean is an MXBean.
Throws:
IllegalArgumentException - if the mbeanInterface does not follow JMX design patterns for Management Interfaces, or if this does not implement the specified interface.
Since:
1.6
Method Detail

setImplementation

public void setImplementation(Object implementation)
                       throws NotCompliantMBeanException

Replace the implementation object wrapped in this object.

Parameters:
implementation - The new implementation of this Standard MBean (or MXBean). The implementation object must implement the Standard MBean (or MXBean) interface that was supplied when this StandardMBean was constructed.
Throws:
IllegalArgumentException - if the given implementation is null.
NotCompliantMBeanException - if the given implementation does not implement the Standard MBean (or MXBean) interface that was supplied at construction.
See Also:
getImplementation()

getImplementation

public Object getImplementation()
Get the implementation of this Standard MBean (or MXBean).

Returns:
The implementation of this Standard MBean (or MXBean).
See Also:
setImplementation(java.lang.Object)

getMBeanInterface

public final Class<?> getMBeanInterface()
Get the Management Interface of this Standard MBean (or MXBean).

Returns:
The management interface of this Standard MBean (or MXBean).

getImplementationClass

public Class<?> getImplementationClass()
Get the class of the implementation of this Standard MBean (or MXBean).

Returns:
The class of the implementation of this Standard MBean (or MXBean).

getAttribute

public Object getAttribute(String attribute)
                    throws AttributeNotFoundException,
                           MBeanException,
                           ReflectionException
Description copied from interface: DynamicMBean
Obtain the value of a specific attribute of the Dynamic MBean.

Specified by:
getAttribute in interface DynamicMBean
Parameters:
attribute - The name of the attribute to be retrieved
Returns:
The value of the attribute retrieved.
Throws:
AttributeNotFoundException
MBeanException - Wraps a java.lang.Exception thrown by the MBean's getter.
ReflectionException - Wraps a java.lang.Exception thrown while trying to invoke the getter.
See Also:
DynamicMBean.setAttribute(javax.management.Attribute)

setAttribute

public void setAttribute(Attribute attribute)
                  throws AttributeNotFoundException,
                         InvalidAttributeValueException,
                         MBeanException,
                         ReflectionException
Description copied from interface: DynamicMBean
Set the value of a specific attribute of the Dynamic MBean.

Specified by:
setAttribute in interface DynamicMBean
Parameters:
attribute - The identification of the attribute to be set and the value it is to be set to.
Throws:
AttributeNotFoundException
InvalidAttributeValueException
MBeanException - Wraps a java.lang.Exception thrown by the MBean's setter.
ReflectionException - Wraps a java.lang.Exception thrown while trying to invoke the MBean's setter.
See Also:
DynamicMBean.getAttribute(java.lang.String)

getAttributes

public AttributeList getAttributes(String[] attributes)
Description copied from interface: DynamicMBean
Get the values of several attributes of the Dynamic MBean.

Specified by:
getAttributes in interface DynamicMBean
Parameters:
attributes - A list of the attributes to be retrieved.
Returns:
The list of attributes retrieved.
See Also:
DynamicMBean.setAttributes(javax.management.AttributeList)

setAttributes

public AttributeList setAttributes(AttributeList attributes)
Description copied from interface: DynamicMBean
Sets the values of several attributes of the Dynamic MBean.

Specified by:
setAttributes in interface DynamicMBean
Parameters:
attributes - A list of attributes: The identification of the attributes to be set and the values they are to be set to.
Returns:
The list of attributes that were set, with their new values.
See Also:
DynamicMBean.getAttributes(java.lang.String[])

invoke

public Object invoke(String actionName,
                     Object[] params,
                     String[] signature)
              throws MBeanException,
                     ReflectionException
Description copied from interface: DynamicMBean
Allows an action to be invoked on the Dynamic MBean.

Specified by:
invoke in interface DynamicMBean
Parameters:
actionName - The name of the action to be invoked.
params - An array containing the parameters to be set when the action is invoked.
signature - An array containing the signature of the action. The class objects will be loaded through the same class loader as the one used for loading the MBean on which the action is invoked.
Returns:
The object returned by the action, which represents the result of invoking the action on the MBean specified.
Throws:
MBeanException - Wraps a java.lang.Exception thrown by the MBean's invoked method.
ReflectionException - Wraps a java.lang.Exception thrown while trying to invoke the method

getMBeanInfo

public MBeanInfo getMBeanInfo()
Get the MBeanInfo for this MBean.

This method implements DynamicMBean.getMBeanInfo().

This method first calls getCachedMBeanInfo() in order to retrieve the cached MBeanInfo for this MBean, if any. If the MBeanInfo returned by getCachedMBeanInfo() is not null, then it is returned.
Otherwise, this method builds a default MBeanInfo for this MBean, using the Management Interface specified for this MBean.

While building the MBeanInfo, this method calls the customization hooks that make it possible for subclasses to supply their custom descriptions, parameter names, etc...
Finally, it calls cacheMBeanInfo() in order to cache the new MBeanInfo.

Specified by:
getMBeanInfo in interface DynamicMBean
Returns:
The cached MBeanInfo for that MBean, if not null, or a newly built MBeanInfo if none was cached.

getClassName

protected String getClassName(MBeanInfo info)
Customization hook: Get the className that will be used in the MBeanInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom class name. The default implementation returns info.getClassName().

Parameters:
info - The default MBeanInfo derived by reflection.
Returns:
the class name for the new MBeanInfo.

getDescription

protected String getDescription(MBeanInfo info)
Customization hook: Get the description that will be used in the MBeanInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom MBean description. The default implementation returns info.getDescription().

Parameters:
info - The default MBeanInfo derived by reflection.
Returns:
the description for the new MBeanInfo.

getDescription

protected String getDescription(MBeanFeatureInfo info)

Customization hook: Get the description that will be used in the MBeanFeatureInfo returned by this MBean.

Subclasses may redefine this method in order to supply their custom description. The default implementation returns info.getDescription().

This method is called by getDescription(MBeanAttributeInfo), getDescription(MBeanOperationInfo), getDescription(MBeanConstructorInfo).

Parameters:
info - The default MBeanFeatureInfo derived by reflection.
Returns:
the description for the given MBeanFeatureInfo.

getDescription

protected String getDescription(MBeanAttributeInfo info)
Customization hook: Get the description that will be used in the MBeanAttributeInfo returned by this MBean.

Subclasses may redefine this method in order to supply their custom description. The default implementation returns getDescription((MBeanFeatureInfo) info).

Parameters:
info - The default MBeanAttributeInfo derived by reflection.
Returns:
the description for the given MBeanAttributeInfo.

getDescription

protected String getDescription(MBeanConstructorInfo info)
Customization hook: Get the description that will be used in the MBeanConstructorInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom description. The default implementation returns getDescription((MBeanFeatureInfo) info).

Parameters:
info - The default MBeanConstructorInfo derived by reflection.
Returns:
the description for the given MBeanConstructorInfo.

getDescription

protected String getDescription(MBeanConstructorInfo ctor,
                                MBeanParameterInfo param,
                                int sequence)
Customization hook: Get the description that will be used for the sequence MBeanParameterInfo of the MBeanConstructorInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom description. The default implementation returns param.getDescription().

Parameters:
ctor - The default MBeanConstructorInfo derived by reflection.
param - The default MBeanParameterInfo derived by reflection.
sequence - The sequence number of the parameter considered ("0" for the first parameter, "1" for the second parameter, etc...).
Returns:
the description for the given MBeanParameterInfo.

getParameterName

protected String getParameterName(MBeanConstructorInfo ctor,
                                  MBeanParameterInfo param,
                                  int sequence)
Customization hook: Get the name that will be used for the sequence MBeanParameterInfo of the MBeanConstructorInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom parameter name. The default implementation returns param.getName().

Parameters:
ctor - The default MBeanConstructorInfo derived by reflection.
param - The default MBeanParameterInfo derived by reflection.
sequence - The sequence number of the parameter considered ("0" for the first parameter, "1" for the second parameter, etc...).
Returns:
the name for the given MBeanParameterInfo.

getDescription

protected String getDescription(MBeanOperationInfo info)
Customization hook: Get the description that will be used in the MBeanOperationInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom description. The default implementation returns getDescription((MBeanFeatureInfo) info).

Parameters:
info - The default MBeanOperationInfo derived by reflection.
Returns:
the description for the given MBeanOperationInfo.

getImpact

protected int getImpact(MBeanOperationInfo info)
Customization hook: Get the impact flag of the operation that will be used in the MBeanOperationInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom impact flag. The default implementation returns info.getImpact().

Parameters:
info - The default MBeanOperationInfo derived by reflection.
Returns:
the impact flag for the given MBeanOperationInfo.

getParameterName

protected String getParameterName(MBeanOperationInfo op,
                                  MBeanParameterInfo param,
                                  int sequence)
Customization hook: Get the name that will be used for the sequence MBeanParameterInfo of the MBeanOperationInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom parameter name. The default implementation returns param.getName().

Parameters:
op - The default MBeanOperationInfo derived by reflection.
param - The default MBeanParameterInfo derived by reflection.
sequence - The sequence number of the parameter considered ("0" for the first parameter, "1" for the second parameter, etc...).
Returns:
the name to use for the given MBeanParameterInfo.

getDescription

protected String getDescription(MBeanOperationInfo op,
                                MBeanParameterInfo param,
                                int sequence)
Customization hook: Get the description that will be used for the sequence MBeanParameterInfo of the MBeanOperationInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom description. The default implementation returns param.getDescription().

Parameters:
op - The default MBeanOperationInfo derived by reflection.
param - The default MBeanParameterInfo derived by reflection.
sequence - The sequence number of the parameter considered ("0" for the first parameter, "1" for the second parameter, etc...).
Returns:
the description for the given MBeanParameterInfo.

getConstructors

protected MBeanConstructorInfo[] getConstructors(MBeanConstructorInfo[] ctors,
                                                 Object impl)
Customization hook: Get the MBeanConstructorInfo[] that will be used in the MBeanInfo returned by this MBean.
By default, this method returns null if the wrapped implementation is not this. Indeed, if the wrapped implementation is not this object itself, it will not be possible to recreate a wrapped implementation by calling the implementation constructors through MBeanServer.createMBean(...).
Otherwise, if the wrapped implementation is this, ctors is returned.
Subclasses may redefine this method in order to modify this behavior, if needed.

Parameters:
ctors - The default MBeanConstructorInfo[] derived by reflection.
impl - The wrapped implementation. If null is passed, the wrapped implementation is ignored and ctors is returned.
Returns:
the MBeanConstructorInfo[] for the new MBeanInfo.

getCachedMBeanInfo

protected MBeanInfo getCachedMBeanInfo()
Customization hook: Return the MBeanInfo cached for this object.

Subclasses may redefine this method in order to implement their own caching policy. The default implementation stores one MBeanInfo object per instance.

Returns:
The cached MBeanInfo, or null if no MBeanInfo is cached.
See Also:
cacheMBeanInfo(MBeanInfo)

cacheMBeanInfo

protected void cacheMBeanInfo(MBeanInfo info)
Customization hook: cache the MBeanInfo built for this object.

Subclasses may redefine this method in order to implement their own caching policy. The default implementation stores info in this instance. A subclass can define other policies, such as not saving info (so it is reconstructed every time getMBeanInfo() is called) or sharing a unique MBeanInfo object when several StandardMBean instances have equal MBeanInfo values.

Parameters:
info - the new MBeanInfo to cache. Any previously cached value is discarded. This parameter may be null, in which case there is no new cached value.

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception

Allows the MBean to perform any operations it needs before being registered in the MBean server. If the name of the MBean is not specified, the MBean can provide a name for its registration. If any exception is raised, the MBean will not be registered in the MBean server.

The default implementation of this method returns the name parameter. It does nothing else for Standard MBeans. For MXBeans, it records the MBeanServer and ObjectName parameters so they can be used to translate inter-MXBean references.

It is good practice for a subclass that overrides this method to call the overridden method via super.preRegister(...). This is necessary if this object is an MXBean that is referenced by attributes or operations in other MXBeans.

Specified by:
preRegister in interface MBeanRegistration
Parameters:
server - The MBean server in which the MBean will be registered.
name - The object name of the MBean. This name is null if the name parameter to one of the createMBean or registerMBean methods in the MBeanServer interface is null. In that case, this method must return a non-null ObjectName for the new MBean.
Returns:
The name under which the MBean is to be registered. This value must not be null. If the name parameter is not null, it will usually but not necessarily be the returned value.
Throws:
IllegalArgumentException - if this is an MXBean and name is null.
InstanceAlreadyExistsException - if this is an MXBean and it has already been registered under another name (in this MBean Server or another).
Exception - no other checked exceptions are thrown by this method but Exception is declared so that subclasses can override the method and throw their own exceptions.
Since:
1.6

postRegister

public void postRegister(Boolean registrationDone)

Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.

The default implementation of this method does nothing for Standard MBeans. For MXBeans, it undoes any work done by preRegister if registration fails.

It is good practice for a subclass that overrides this method to call the overridden method via super.postRegister(...). This is necessary if this object is an MXBean that is referenced by attributes or operations in other MXBeans.

Specified by:
postRegister in interface MBeanRegistration
Parameters:
registrationDone - Indicates whether or not the MBean has been successfully registered in the MBean server. The value false means that the registration phase has failed.
Since:
1.6

preDeregister

public void preDeregister()
                   throws Exception

Allows the MBean to perform any operations it needs before being unregistered by the MBean server.

The default implementation of this method does nothing.

It is good practice for a subclass that overrides this method to call the overridden method via super.preDeegister(...).

Specified by:
preDeregister in interface MBeanRegistration
Throws:
Exception - no checked exceptions are throw by this method but Exception is declared so that subclasses can override this method and throw their own exceptions.
Since:
1.6

postDeregister

public void postDeregister()

Allows the MBean to perform any operations needed after having been unregistered in the MBean server.

The default implementation of this method does nothing for Standard MBeans. For MXBeans, it removes any information that was recorded by the preRegister method.

It is good practice for a subclass that overrides this method to call the overridden method via super.postRegister(...). This is necessary if this object is an MXBean that is referenced by attributes or operations in other MXBeans.

Specified by:
postDeregister in interface MBeanRegistration
Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StringValueExp

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management
Class StringValueExp

java.lang.Object
    extended by  javax.management.StringValueExp
All Implemented Interfaces:
Serializable, ValueExp
public class StringValueExp
extends Object
implements ValueExp

Represents strings that are arguments to relational constraints. A StringValueExp may be used anywhere a ValueExp is required.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
StringValueExp()
Basic constructor.
StringValueExp(String val)
Creates a new StringValueExp representing the given string.
Method Summary
ValueExp | apply(ObjectName name) Applies the ValueExp on a MBean.
String | getValue() Returns the string represented by the StringValueExp instance.
void | setMBeanServer(MBeanServer s) Sets the MBean server on which the query is to be performed.
String | toString() Returns the string representing the object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

StringValueExp

public StringValueExp()
Basic constructor.

StringValueExp

public StringValueExp(String val)
Creates a new StringValueExp representing the given string.

Parameters:
val - the string that will be the value of this expression
Method Detail

getValue

public String getValue()
Returns the string represented by the StringValueExp instance.

Returns:
the string.

toString

public String toString()
Returns the string representing the object.

Overrides:
toString in class Object
Returns:
a string representation of the object.

setMBeanServer

public void setMBeanServer(MBeanServer s)
Sets the MBean server on which the query is to be performed.

Specified by:
setMBeanServer in interface ValueExp
Parameters:
s - The MBean server on which the query is to be performed.

apply

public ValueExp apply(ObjectName name)
               throws BadStringOperationException,
                      BadBinaryOpValueExpException,
                      BadAttributeValueExpException,
                      InvalidApplicationException
Applies the ValueExp on a MBean.

Specified by:
apply in interface ValueExp
Parameters:
name - The name of the MBean on which the ValueExp will be applied.
Returns:
The ValueExp.
Throws:
BadStringOperationException
BadBinaryOpValueExpException
BadAttributeValueExpException
InvalidApplicationException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


timer

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.management.timer

Provides the definition of the Timer MBean.

See:
Description

Interface Summary
TimerMBean Exposes the management interface of the timer MBean.

Class Summary
Timer | Provides the implementation of the timer MBean.
TimerNotification | This class provides definitions of the notifications sent by timer MBeans.

Package javax.management.timer Description

Provides the definition of the Timer MBean. A Timer MBean maintains a list of scheduled notifications and, because it is a NotificationBroadcaster, a list of listeners for those notifications. Whenever the time for one of the scheduled notifications is reached, each listener receives the notification. Notifications can be repeated at a fixed interval, and the number of repetitions can be bounded.

A listener for a Timer MBean can itself be an MBean, using the method MBeanServer.addNotificationListener(ObjectName, ObjectName, NotificationFilter, Object). In this way, a management application can create an MBean representing a task, then schedule that task using a Timer MBean.

Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.management.timer Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.management.timer

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.util.EventObject (implements java.io.Serializable)
      • javax.management.Notification
        • javax.management.timer.TimerNotification
    • javax.management.NotificationBroadcasterSupport (implements javax.management.NotificationEmitter)
      • javax.management.timer.Timer (implements javax.management.MBeanRegistration, javax.management.timer.TimerMBean)

Interface Hierarchy

  • javax.management.timer.TimerMBean
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.management.timer

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.management.timer

Packages that use javax.management.timer
javax.management.timer Provides the definition of the Timer MBean.

Classes in javax.management.timer used by javax.management.timer
TimerMBean
Exposes the management interface of the timer MBean.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.timer.Timer

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.timer.Timer

No usage of javax.management.timer.Timer

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.management.timer.TimerNotification

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.management.timer.TimerNotification

No usage of javax.management.timer.TimerNotification

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.management.timer.TimerMBean

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.management.timer.TimerMBean

Packages that use TimerMBean
javax.management.timer Provides the definition of the Timer MBean.

Uses of TimerMBean in javax.management.timer

Classes in javax.management.timer that implement TimerMBean
 class Timer
Provides the implementation of the timer MBean.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Timer

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.management.timer
Class Timer

java.lang.Object
    extended by  javax.management.NotificationBroadcasterSupport
        extended by  javax.management.timer.Timer
All Implemented Interfaces:
MBeanRegistration, NotificationBroadcaster, NotificationEmitter, TimerMBean
public class Timer
extends NotificationBroadcasterSupport
implements TimerMBean, MBeanRegistration

Provides the implementation of the timer MBean. The timer MBean sends out an alarm at a specified time that wakes up all the listeners registered to receive timer notifications.

This class manages a list of dated timer notifications. A method allows users to add/remove as many notifications as required. When a timer notification is emitted by the timer and becomes obsolete, it is automatically removed from the list of timer notifications.
Additional timer notifications can be added into regularly repeating notifications.

Note:

  1. When sending timer notifications, the timer updates the notification sequence number irrespective of the notification type.
  2. The timer service relies on the system date of the host where the Timer class is loaded. Listeners may receive untimely notifications if their host has a different system date. To avoid such problems, synchronize the system date of all host machines where timing is needed.
  3. The default behavior for periodic notifications is fixed-delay execution, as specified in Timer. In order to use fixed-rate execution, use the overloaded addNotification(String, String, Object, Date, long, long, boolean) method.
  4. Notification listeners are potentially all executed in the same thread. Therefore, they should execute rapidly to avoid holding up other listeners or perturbing the regularity of fixed-delay executions. See NotificationBroadcasterSupport.

Since:
1.5

Field Summary
static long | ONE_DAY Number of milliseconds in one day.
static long | ONE_HOUR Number of milliseconds in one hour.
static long | ONE_MINUTE Number of milliseconds in one minute.
static long | ONE_SECOND Number of milliseconds in one second.
static long | ONE_WEEK Number of milliseconds in one week.
Constructor Summary
Timer()
Default constructor.
Method Summary
Integer | addNotification(String type, String message, Object userData, Date date) Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date and a null period and number of occurrences.
Integer | addNotification(String type, String message, Object userData, Date date, long period) Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date and period and a null number of occurrences.
Integer | addNotification(String type, String message, Object userData, Date date, long period, long nbOccurences) Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date, period and number of occurrences.
Integer | addNotification(String type, String message, Object userData, Date date, long period, long nbOccurences, boolean fixedRate) Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date, period and number of occurrences.
Vector<Integer> | getAllNotificationIDs() Gets all timer notification identifiers registered into the list of notifications.
Date | getDate(Integer id) Gets a copy of the date associated to a timer notification.
Boolean | getFixedRate(Integer id) Gets a copy of the flag indicating whether a periodic notification is executed at fixed-delay or at fixed-rate.
int | getNbNotifications() Gets the number of timer notifications registered into the list of notifications.
Long | getNbOccurences(Integer id) Gets a copy of the remaining number of occurrences associated to a timer notification.
Vector<Integer> | getNotificationIDs(String type) Gets all the identifiers of timer notifications corresponding to the specified type.
MBeanNotificationInfo[] | getNotificationInfo() Returns an array indicating, for each notification this MBean may send, the name of the Java class of the notification and the notification type.
String | getNotificationMessage(Integer id) Gets the timer notification detailed message corresponding to the specified identifier.
String | getNotificationType(Integer id) Gets the timer notification type corresponding to the specified identifier.
Object | getNotificationUserData(Integer id) Gets the timer notification user data object corresponding to the specified identifier.
Long | getPeriod(Integer id) Gets a copy of the period (in milliseconds) associated to a timer notification.
boolean | getSendPastNotifications() Gets the flag indicating whether or not the timer sends past notifications.
boolean | isActive() Tests whether the timer MBean is active.
boolean | isEmpty() Tests whether the list of timer notifications is empty.
void | postDeregister() Allows the timer MBean to perform any operations needed after having been unregistered by the MBean server.
void | postRegister(Boolean registrationDone) Allows the timer MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.
void | preDeregister() Allows the timer MBean to perform any operations it needs before being unregistered by the MBean server.
ObjectName | preRegister(MBeanServer server, ObjectName name) Allows the timer MBean to perform any operations it needs before being registered in the MBean server.
void | removeAllNotifications() Removes all the timer notifications from the list of notifications and resets the counter used to update the timer notification identifiers.
void | removeNotification(Integer id) Removes the timer notification corresponding to the specified identifier from the list of notifications.
void | removeNotifications(String type) Removes all the timer notifications corresponding to the specified type from the list of notifications.
void | setSendPastNotifications(boolean value) Sets the flag indicating whether the timer sends past notifications or not.
void | start() Starts the timer.
void | stop() Stops the timer.
Methods inherited from class javax.management.NotificationBroadcasterSupport
addNotificationListener, handleNotification, removeNotificationListener, removeNotificationListener, sendNotification
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ONE_SECOND

public static final long ONE_SECOND
Number of milliseconds in one second. Useful constant for the addNotification method.

See Also:
Constant Field Values

ONE_MINUTE

public static final long ONE_MINUTE
Number of milliseconds in one minute. Useful constant for the addNotification method.

See Also:
Constant Field Values

ONE_HOUR

public static final long ONE_HOUR
Number of milliseconds in one hour. Useful constant for the addNotification method.

See Also:
Constant Field Values

ONE_DAY

public static final long ONE_DAY
Number of milliseconds in one day. Useful constant for the addNotification method.

See Also:
Constant Field Values

ONE_WEEK

public static final long ONE_WEEK
Number of milliseconds in one week. Useful constant for the addNotification method.

See Also:
Constant Field Values
Constructor Detail

Timer

public Timer()
Default constructor.

Method Detail

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception
Allows the timer MBean to perform any operations it needs before being registered in the MBean server.

Not used in this context.

Specified by:
preRegister in interface MBeanRegistration
Parameters:
server - The MBean server in which the timer MBean will be registered.
name - The object name of the timer MBean.
Returns:
The name of the timer MBean registered.
Throws:
Exception

postRegister

public void postRegister(Boolean registrationDone)
Allows the timer MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.

Not used in this context.

Specified by:
postRegister in interface MBeanRegistration
Parameters:
registrationDone - Indicates whether or not the MBean has been successfully registered in the MBean server. The value false means that the registration phase has failed.

preDeregister

public void preDeregister()
                   throws Exception
Allows the timer MBean to perform any operations it needs before being unregistered by the MBean server.

Stops the timer.

Specified by:
preDeregister in interface MBeanRegistration
Throws:
Exception

postDeregister

public void postDeregister()
Allows the timer MBean to perform any operations needed after having been unregistered by the MBean server.

Not used in this context.

Specified by:
postDeregister in interface MBeanRegistration

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()
Description copied from interface: NotificationBroadcaster

Returns an array indicating, for each notification this MBean may send, the name of the Java class of the notification and the notification type.

It is not illegal for the MBean to send notifications not described in this array. However, some clients of the MBean server may depend on the array being complete for their correct functioning.

Specified by:
getNotificationInfo in interface NotificationBroadcaster
Overrides:
getNotificationInfo in class NotificationBroadcasterSupport
Returns:
the array of possible notifications.

start

public void start()
Starts the timer.

If there is one or more timer notifications before the time in the list of notifications, the notification is sent according to the sendPastNotifications flag and then, updated according to its period and remaining number of occurrences. If the timer notification date remains earlier than the current date, this notification is just removed from the list of notifications.

Specified by:
start in interface TimerMBean

stop

public void stop()
Stops the timer.

Specified by:
stop in interface TimerMBean

addNotification

public Integer addNotification(String type,
                               String message,
                               Object userData,
                               Date date,
                               long period,
                               long nbOccurences,
                               boolean fixedRate)
                        throws IllegalArgumentException
Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date, period and number of occurrences.

If the timer notification to be inserted has a date that is before the current date, the method behaves as if the specified date were the current date.
For once-off notifications, the notification is delivered immediately.
For periodic notifications, the first notification is delivered immediately and the subsequent ones are spaced as specified by the period parameter.

Note that once the timer notification has been added into the list of notifications, its associated date, period and number of occurrences cannot be updated.

In the case of a periodic notification, the value of parameter fixedRate is used to specify the execution scheme, as specified in Timer.

Specified by:
addNotification in interface TimerMBean
Parameters:
type - The timer notification type.
message - The timer notification detailed message.
userData - The timer notification user data object.
date - The date when the notification occurs.
period - The period of the timer notification (in milliseconds).
nbOccurences - The total number the timer notification will be emitted.
fixedRate - If true and if the notification is periodic, the notification is scheduled with a fixed-rate execution scheme. If false and if the notification is periodic, the notification is scheduled with a fixed-delay execution scheme. Ignored if the notification is not periodic.
Returns:
The identifier of the new created timer notification.
Throws:
IllegalArgumentException - The date is null or the period or the number of occurrences is negative.
See Also:
addNotification(String, String, Object, Date, long, long)

addNotification

public Integer addNotification(String type,
                               String message,
                               Object userData,
                               Date date,
                               long period,
                               long nbOccurences)
                        throws IllegalArgumentException
Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date, period and number of occurrences.

If the timer notification to be inserted has a date that is before the current date, the method behaves as if the specified date were the current date.
For once-off notifications, the notification is delivered immediately.
For periodic notifications, the first notification is delivered immediately and the subsequent ones are spaced as specified by the period parameter.

Note that once the timer notification has been added into the list of notifications, its associated date, period and number of occurrences cannot be updated.

In the case of a periodic notification, uses a fixed-delay execution scheme, as specified in Timer. In order to use a fixed-rate execution scheme, use addNotification(String, String, Object, Date, long, long, boolean) instead.

Specified by:
addNotification in interface TimerMBean
Parameters:
type - The timer notification type.
message - The timer notification detailed message.
userData - The timer notification user data object.
date - The date when the notification occurs.
period - The period of the timer notification (in milliseconds).
nbOccurences - The total number the timer notification will be emitted.
Returns:
The identifier of the new created timer notification.
Throws:
IllegalArgumentException - The date is null or the period or the number of occurrences is negative.
See Also:
addNotification(String, String, Object, Date, long, long, boolean)

addNotification

public Integer addNotification(String type,
                               String message,
                               Object userData,
                               Date date,
                               long period)
                        throws IllegalArgumentException
Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date and period and a null number of occurrences.

The timer notification will repeat continuously using the timer period using a fixed-delay execution scheme, as specified in Timer. In order to use a fixed-rate execution scheme, use addNotification(String, String, Object, Date, long, long, boolean) instead.

If the timer notification to be inserted has a date that is before the current date, the method behaves as if the specified date were the current date. The first notification is delivered immediately and the subsequent ones are spaced as specified by the period parameter.

Specified by:
addNotification in interface TimerMBean
Parameters:
type - The timer notification type.
message - The timer notification detailed message.
userData - The timer notification user data object.
date - The date when the notification occurs.
period - The period of the timer notification (in milliseconds).
Returns:
The identifier of the new created timer notification.
Throws:
IllegalArgumentException - The date is null or the period is negative.

addNotification

public Integer addNotification(String type,
                               String message,
                               Object userData,
                               Date date)
                        throws IllegalArgumentException
Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date and a null period and number of occurrences.

The timer notification will be handled once at the specified date.

If the timer notification to be inserted has a date that is before the current date, the method behaves as if the specified date were the current date and the notification is delivered immediately.

Specified by:
addNotification in interface TimerMBean
Parameters:
type - The timer notification type.
message - The timer notification detailed message.
userData - The timer notification user data object.
date - The date when the notification occurs.
Returns:
The identifier of the new created timer notification.
Throws:
IllegalArgumentException - The date is null.

removeNotification

public void removeNotification(Integer id)
                        throws InstanceNotFoundException
Removes the timer notification corresponding to the specified identifier from the list of notifications.

Specified by:
removeNotification in interface TimerMBean
Parameters:
id - The timer notification identifier.
Throws:
InstanceNotFoundException - The specified identifier does not correspond to any timer notification in the list of notifications of this timer MBean.

removeNotifications

public void removeNotifications(String type)
                         throws InstanceNotFoundException
Removes all the timer notifications corresponding to the specified type from the list of notifications.

Specified by:
removeNotifications in interface TimerMBean
Parameters:
type - The timer notification type.
Throws:
InstanceNotFoundException - The specified type does not correspond to any timer notification in the list of notifications of this timer MBean.

removeAllNotifications

public void removeAllNotifications()
Removes all the timer notifications from the list of notifications and resets the counter used to update the timer notification identifiers.

Specified by:
removeAllNotifications in interface TimerMBean

getNbNotifications

public int getNbNotifications()
Gets the number of timer notifications registered into the list of notifications.

Specified by:
getNbNotifications in interface TimerMBean
Returns:
The number of timer notifications.

getAllNotificationIDs

public Vector<Integer> getAllNotificationIDs()
Gets all timer notification identifiers registered into the list of notifications.

Specified by:
getAllNotificationIDs in interface TimerMBean
Returns:
A vector of Integer objects containing all the timer notification identifiers.
The vector is empty if there is no timer notification registered for this timer MBean.

getNotificationIDs

public Vector<Integer> getNotificationIDs(String type)
Gets all the identifiers of timer notifications corresponding to the specified type.

Specified by:
getNotificationIDs in interface TimerMBean
Parameters:
type - The timer notification type.
Returns:
A vector of Integer objects containing all the identifiers of timer notifications with the specified type.
The vector is empty if there is no timer notifications registered for this timer MBean with the specified type.

getNotificationType

public String getNotificationType(Integer id)
Gets the timer notification type corresponding to the specified identifier.

Specified by:
getNotificationType in interface TimerMBean
Parameters:
id - The timer notification identifier.
Returns:
The timer notification type or null if the identifier is not mapped to any timer notification registered for this timer MBean.

getNotificationMessage

public String getNotificationMessage(Integer id)
Gets the timer notification detailed message corresponding to the specified identifier.

Specified by:
getNotificationMessage in interface TimerMBean
Parameters:
id - The timer notification identifier.
Returns:
The timer notification detailed message or null if the identifier is not mapped to any timer notification registered for this timer MBean.

getNotificationUserData

public Object getNotificationUserData(Integer id)
Gets the timer notification user data object corresponding to the specified identifier.

Specified by:
getNotificationUserData in interface TimerMBean
Parameters:
id - The timer notification identifier.
Returns:
The timer notification user data object or null if the identifier is not mapped to any timer notification registered for this timer MBean.

getDate

public Date getDate(Integer id)
Gets a copy of the date associated to a timer notification.

Specified by:
getDate in interface TimerMBean
Parameters:
id - The timer notification identifier.
Returns:
A copy of the date or null if the identifier is not mapped to any timer notification registered for this timer MBean.

getPeriod

public Long getPeriod(Integer id)
Gets a copy of the period (in milliseconds) associated to a timer notification.

Specified by:
getPeriod in interface TimerMBean
Parameters:
id - The timer notification identifier.
Returns:
A copy of the period or null if the identifier is not mapped to any timer notification registered for this timer MBean.

getNbOccurences

public Long getNbOccurences(Integer id)
Gets a copy of the remaining number of occurrences associated to a timer notification.

Specified by:
getNbOccurences in interface TimerMBean
Parameters:
id - The timer notification identifier.
Returns:
A copy of the remaining number of occurrences or null if the identifier is not mapped to any timer notification registered for this timer MBean.

getFixedRate

public Boolean getFixedRate(Integer id)
Gets a copy of the flag indicating whether a periodic notification is executed at fixed-delay or at fixed-rate.

Specified by:
getFixedRate in interface TimerMBean
Parameters:
id - The timer notification identifier.
Returns:
A copy of the flag indicating whether a periodic notification is executed at fixed-delay or at fixed-rate.

getSendPastNotifications

public boolean getSendPastNotifications()
Gets the flag indicating whether or not the timer sends past notifications.
The default value of the past notifications sending on/off flag is false.

Specified by:
getSendPastNotifications in interface TimerMBean
Returns:
The past notifications sending on/off flag value.
See Also:
setSendPastNotifications(boolean)

setSendPastNotifications

public void setSendPastNotifications(boolean value)
Sets the flag indicating whether the timer sends past notifications or not.
The default value of the past notifications sending on/off flag is false.

Specified by:
setSendPastNotifications in interface TimerMBean
Parameters:
value - The past notifications sending on/off flag value.
See Also:
getSendPastNotifications()

isActive

public boolean isActive()
Tests whether the timer MBean is active. A timer MBean is marked active when the start method is called. It becomes inactive when the stop method is called.
The default value of the active on/off flag is false.

Specified by:
isActive in interface TimerMBean
Returns:
true if the timer MBean is active, false otherwise.

isEmpty

public boolean isEmpty()
Tests whether the list of timer notifications is empty.

Specified by:
isEmpty in interface TimerMBean
Returns:
true if the list of timer notifications is empty, false otherwise.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


TimerMBean

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.management.timer
Interface TimerMBean

All Known Implementing Classes:
Timer
public interface TimerMBean

Exposes the management interface of the timer MBean.

Since:
1.5

Method Summary
Integer | addNotification(String type, String message, Object userData, Date date) Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date and a null period and number of occurrences.
Integer | addNotification(String type, String message, Object userData, Date date, long period) Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date and period and a null number of occurrences.
Integer | addNotification(String type, String message, Object userData, Date date, long period, long nbOccurences) Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date, period and number of occurrences.
Integer | addNotification(String type, String message, Object userData, Date date, long period, long nbOccurences, boolean fixedRate) Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date, period and number of occurrences.
Vector<Integer> | getAllNotificationIDs() Gets all timer notification identifiers registered into the list of notifications.
Date | getDate(Integer id) Gets a copy of the date associated to a timer notification.
Boolean | getFixedRate(Integer id) Gets a copy of the flag indicating whether a periodic notification is executed at fixed-delay or at fixed-rate.
int | getNbNotifications() Gets the number of timer notifications registered into the list of notifications.
Long | getNbOccurences(Integer id) Gets a copy of the remaining number of occurrences associated to a timer notification.
Vector<Integer> | getNotificationIDs(String type) Gets all the identifiers of timer notifications corresponding to the specified type.
String | getNotificationMessage(Integer id) Gets the timer notification detailed message corresponding to the specified identifier.
String | getNotificationType(Integer id) Gets the timer notification type corresponding to the specified identifier.
Object | getNotificationUserData(Integer id) Gets the timer notification user data object corresponding to the specified identifier.
Long | getPeriod(Integer id) Gets a copy of the period (in milliseconds) associated to a timer notification.
boolean | getSendPastNotifications() Gets the flag indicating whether or not the timer sends past notifications.
boolean | isActive() Tests whether the timer MBean is active.
boolean | isEmpty() Tests whether the list of timer notifications is empty.
void | removeAllNotifications() Removes all the timer notifications from the list of notifications and resets the counter used to update the timer notification identifiers.
void | removeNotification(Integer id) Removes the timer notification corresponding to the specified identifier from the list of notifications.
void | removeNotifications(String type) Removes all the timer notifications corresponding to the specified type from the list of notifications.
void | setSendPastNotifications(boolean value) Sets the flag indicating whether the timer sends past notifications or not.
void | start() Starts the timer.
void | stop() Stops the timer.

Method Detail

start

void start()
Starts the timer.

If there is one or more timer notifications before the time in the list of notifications, the notification is sent according to the sendPastNotifications flag and then, updated according to its period and remaining number of occurrences. If the timer notification date remains earlier than the current date, this notification is just removed from the list of notifications.

stop

void stop()
Stops the timer.

addNotification

Integer addNotification(String type,
                        String message,
                        Object userData,
                        Date date,
                        long period,
                        long nbOccurences,
                        boolean fixedRate)
                        throws IllegalArgumentException
Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date, period and number of occurrences.

If the timer notification to be inserted has a date that is before the current date, the method behaves as if the specified date were the current date.
For once-off notifications, the notification is delivered immediately.
For periodic notifications, the first notification is delivered immediately and the subsequent ones are spaced as specified by the period parameter.

Note that once the timer notification has been added into the list of notifications, its associated date, period and number of occurrences cannot be updated.

In the case of a periodic notification, the value of parameter fixedRate is used to specify the execution scheme, as specified in Timer.

Parameters:
type - The timer notification type.
message - The timer notification detailed message.
userData - The timer notification user data object.
date - The date when the notification occurs.
period - The period of the timer notification (in milliseconds).
nbOccurences - The total number the timer notification will be emitted.
fixedRate - If true and if the notification is periodic, the notification is scheduled with a fixed-rate execution scheme. If false and if the notification is periodic, the notification is scheduled with a fixed-delay execution scheme. Ignored if the notification is not periodic.
Returns:
The identifier of the new created timer notification.
Throws:
IllegalArgumentException - The date is null or the period or the number of occurrences is negative.
See Also:
addNotification(String, String, Object, Date, long, long)

addNotification

Integer addNotification(String type,
                        String message,
                        Object userData,
                        Date date,
                        long period,
                        long nbOccurences)
                        throws IllegalArgumentException
Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date, period and number of occurrences.

If the timer notification to be inserted has a date that is before the current date, the method behaves as if the specified date were the current date.
For once-off notifications, the notification is delivered immediately.
For periodic notifications, the first notification is delivered immediately and the subsequent ones are spaced as specified by the period parameter.

Note that once the timer notification has been added into the list of notifications, its associated date, period and number of occurrences cannot be updated.

In the case of a periodic notification, uses a fixed-delay execution scheme, as specified in Timer. In order to use a fixed-rate execution scheme, use addNotification(String, String, Object, Date, long, long, boolean) instead.

Parameters:
type - The timer notification type.
message - The timer notification detailed message.
userData - The timer notification user data object.
date - The date when the notification occurs.
period - The period of the timer notification (in milliseconds).
nbOccurences - The total number the timer notification will be emitted.
Returns:
The identifier of the new created timer notification.
Throws:
IllegalArgumentException - The date is null or the period or the number of occurrences is negative.
See Also:
addNotification(String, String, Object, Date, long, long, boolean)

addNotification

Integer addNotification(String type,
                        String message,
                        Object userData,
                        Date date,
                        long period)
                        throws IllegalArgumentException
Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date and period and a null number of occurrences.

The timer notification will repeat continuously using the timer period using a fixed-delay execution scheme, as specified in Timer. In order to use a fixed-rate execution scheme, use addNotification(String, String, Object, Date, long, long, boolean) instead.

If the timer notification to be inserted has a date that is before the current date, the method behaves as if the specified date were the current date. The first notification is delivered immediately and the subsequent ones are spaced as specified by the period parameter.

Parameters:
type - The timer notification type.
message - The timer notification detailed message.
userData - The timer notification user data object.
date - The date when the notification occurs.
period - The period of the timer notification (in milliseconds).
Returns:
The identifier of the new created timer notification.
Throws:
IllegalArgumentException - The date is null or the period is negative.

addNotification

Integer addNotification(String type,
                        String message,
                        Object userData,
                        Date date)
                        throws IllegalArgumentException
Creates a new timer notification with the specified type, message and userData and inserts it into the list of notifications with a given date and a null period and number of occurrences.

The timer notification will be handled once at the specified date.

If the timer notification to be inserted has a date that is before the current date, the method behaves as if the specified date were the current date and the notification is delivered immediately.

Parameters:
type - The timer notification type.
message - The timer notification detailed message.
userData - The timer notification user data object.
date - The date when the notification occurs.
Returns:
The identifier of the new created timer notification.
Throws:
IllegalArgumentException - The date is null.

removeNotification

void removeNotification(Integer id)
                        throws InstanceNotFoundException
Removes the timer notification corresponding to the specified identifier from the list of notifications.

Parameters:
id - The timer notification identifier.
Throws:
InstanceNotFoundException - The specified identifier does not correspond to any timer notification in the list of notifications of this timer MBean.

removeNotifications

void removeNotifications(String type)
                         throws InstanceNotFoundException
Removes all the timer notifications corresponding to the specified type from the list of notifications.

Parameters:
type - The timer notification type.
Throws:
InstanceNotFoundException - The specified type does not correspond to any timer notification in the list of notifications of this timer MBean.

removeAllNotifications

void removeAllNotifications()
Removes all the timer notifications from the list of notifications and resets the counter used to update the timer notification identifiers.

getNbNotifications

int getNbNotifications()
Gets the number of timer notifications registered into the list of notifications.

Returns:
The number of timer notifications.

getAllNotificationIDs

Vector<Integer> getAllNotificationIDs()
Gets all timer notification identifiers registered into the list of notifications.

Returns:
A vector of Integer objects containing all the timer notification identifiers.
The vector is empty if there is no timer notification registered for this timer MBean.

getNotificationIDs

Vector<Integer> getNotificationIDs(String type)
Gets all the identifiers of timer notifications corresponding to the specified type.

Parameters:
type - The timer notification type.
Returns:
A vector of Integer objects containing all the identifiers of timer notifications with the specified type.
The vector is empty if there is no timer notifications registered for this timer MBean with the specified type.

getNotificationType

String getNotificationType(Integer id)
Gets the timer notification type corresponding to the specified identifier.

Parameters:
id - The timer notification identifier.
Returns:
The timer notification type or null if the identifier is not mapped to any timer notification registered for this timer MBean.

getNotificationMessage

String getNotificationMessage(Integer id)
Gets the timer notification detailed message corresponding to the specified identifier.

Parameters:
id - The timer notification identifier.
Returns:
The timer notification detailed message or null if the identifier is not mapped to any timer notification registered for this timer MBean.

getNotificationUserData

Object getNotificationUserData(Integer id)
Gets the timer notification user data object corresponding to the specified identifier.

Parameters:
id - The timer notification identifier.
Returns:
The timer notification user data object or null if the identifier is not mapped to any timer notification registered for this timer MBean.

getDate

Date getDate(Integer id)
Gets a copy of the date associated to a timer notification.

Parameters:
id - The timer notification identifier.
Returns:
A copy of the date or null if the identifier is not mapped to any timer notification registered for this timer MBean.

getPeriod

Long getPeriod(Integer id)
Gets a copy of the period (in milliseconds) associated to a timer notification.

Parameters:
id - The timer notification identifier.
Returns:
A copy of the period or null if the identifier is not mapped to any timer notification registered for this timer MBean.

getNbOccurences

Long getNbOccurences(Integer id)
Gets a copy of the remaining number of occurrences associated to a timer notification.

Parameters:
id - The timer notification identifier.
Returns:
A copy of the remaining number of occurrences or null if the identifier is not mapped to any timer notification registered for this timer MBean.

getFixedRate

Boolean getFixedRate(Integer id)
Gets a copy of the flag indicating whether a periodic notification is executed at fixed-delay or at fixed-rate.

Parameters:
id - The timer notification identifier.
Returns:
A copy of the flag indicating whether a periodic notification is executed at fixed-delay or at fixed-rate.

getSendPastNotifications

boolean getSendPastNotifications()
Gets the flag indicating whether or not the timer sends past notifications.

Returns:
The past notifications sending on/off flag value.
See Also:
setSendPastNotifications(boolean)

setSendPastNotifications

void setSendPastNotifications(boolean value)
Sets the flag indicating whether the timer sends past notifications or not.

Parameters:
value - The past notifications sending on/off flag value.
See Also:
getSendPastNotifications()

isActive

boolean isActive()
Tests whether the timer MBean is active. A timer MBean is marked active when the start method is called. It becomes inactive when the stop method is called.

Returns:
true if the timer MBean is active, false otherwise.

isEmpty

boolean isEmpty()
Tests whether the list of timer notifications is empty.

Returns:
true if the list of timer notifications is empty, false otherwise.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TimerNotification

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.management.timer
Class TimerNotification

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.management.Notification
            extended by  javax.management.timer.TimerNotification
All Implemented Interfaces:
Serializable
public class TimerNotification
extends Notification

This class provides definitions of the notifications sent by timer MBeans.
It defines a timer notification identifier which allows to retrieve a timer notification from the list of notifications of a timer MBean.

The timer notifications are created and handled by the timer MBean.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.management.Notification
source
Constructor Summary
TimerNotification(String type, Object source, long sequenceNumber, long timeStamp, String msg, Integer id)
Creates a timer notification object.
Method Summary
 Integer getNotificationID()
Gets the identifier of this timer notification.
Methods inherited from class javax.management.Notification
getMessage, getSequenceNumber, getTimeStamp, getType, getUserData, setSequenceNumber, setSource, setTimeStamp, setUserData, toString
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TimerNotification

public TimerNotification(String type,
                         Object source,
                         long sequenceNumber,
                         long timeStamp,
                         String msg,
                         Integer id)
Creates a timer notification object.

Parameters:
type - The notification type.
source - The notification producer.
sequenceNumber - The notification sequence number within the source object.
timeStamp - The notification emission date.
msg - The notification message.
id - The notification identifier.
Method Detail

getNotificationID

public Integer getNotificationID()
Gets the identifier of this timer notification.

Returns:
The identifier.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


ValueExp

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.management
Interface ValueExp

All Superinterfaces:
Serializable
All Known Implementing Classes:
AttributeValueExp, StringValueExp
public interface ValueExp
extends Serializable

Represents values that can be passed as arguments to relational expressions. Strings, numbers, attributes are valid values and should be represented by implementations of ValueExp.

Since:
1.5

Method Summary
ValueExp | apply(ObjectName name) Applies the ValueExp on a MBean.
void | setMBeanServer(MBeanServer s) Deprecated. This method is not needed because a ValueExp can access the MBean server in which it is being evaluated by using QueryEval.getMBeanServer().

Method Detail

apply

ValueExp apply(ObjectName name)
               throws BadStringOperationException,
                      BadBinaryOpValueExpException,
                      BadAttributeValueExpException,
                      InvalidApplicationException
Applies the ValueExp on a MBean.

Parameters:
name - The name of the MBean on which the ValueExp will be applied.
Returns:
The ValueExp.
Throws:
BadStringOperationException
BadBinaryOpValueExpException
BadAttributeValueExpException
InvalidApplicationException

setMBeanServer

@Deprecated
void setMBeanServer(MBeanServer s)
Deprecated. This method is not needed because a ValueExp can access the MBean server in which it is being evaluated by using QueryEval.getMBeanServer().

Sets the MBean server on which the query is to be performed.

Parameters:
s - The MBean server on which the query is to be performed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


naming

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.naming

Provides the classes and interfaces for accessing naming services.

See:
Description

Interface Summary
Context | This interface represents a naming context, which consists of a set of name-to-object bindings.
Name | The Name interface represents a generic name -- an ordered sequence of components.
NameParser | This interface is used for parsing names from a hierarchical namespace.
NamingEnumeration<T> | This interface is for enumerating lists returned by methods in the javax.naming and javax.naming.directory packages.
Referenceable | This interface is implemented by an object that can provide a Reference to itself.

Class Summary
BinaryRefAddr | This class represents the binary form of the address of a communications end-point.
Binding | This class represents a name-to-object binding found in a context.
CompositeName | This class represents a composite name -- a sequence of component names spanning multiple namespaces.
CompoundName | This class represents a compound name -- a name from a hierarchical name space.
InitialContext | This class is the starting context for performing naming operations.
LinkRef | This class represents a Reference whose contents is a name, called the link name, that is bound to an atomic name in a context.
NameClassPair | This class represents the object name and class name pair of a binding found in a context.
RefAddr | This class represents the address of a communications end-point.
Reference | This class represents a reference to an object that is found outside of the naming/directory system.
StringRefAddr | This class represents the string form of the address of a communications end-point.

Exception Summary
AuthenticationException | This exception is thrown when an authentication error occurs while accessing the naming or directory service.
AuthenticationNotSupportedException | This exception is thrown when the particular flavor of authentication requested is not supported.
CannotProceedException | This exception is thrown to indicate that the operation reached a point in the name where the operation cannot proceed any further.
CommunicationException | This exception is thrown when the client is unable to communicate with the directory or naming service.
ConfigurationException | This exception is thrown when there is a configuration problem.
ContextNotEmptyException | This exception is thrown when attempting to destroy a context that is not empty.
InsufficientResourcesException | This exception is thrown when resources are not available to complete the requested operation.
InterruptedNamingException | This exception is thrown when the naming operation being invoked has been interrupted.
InvalidNameException | This exception indicates that the name being specified does not conform to the naming syntax of a naming system.
LimitExceededException | This exception is thrown when a method terminates abnormally due to a user or system specified limit.
LinkException | This exception is used to describe problems encounter while resolving links.
LinkLoopException | This exception is thrown when a loop was detected will attempting to resolve a link, or an implementation specific limit on link counts has been reached.
MalformedLinkException | This exception is thrown when a malformed link was encountered while resolving or constructing a link.
NameAlreadyBoundException | This exception is thrown by methods to indicate that a binding cannot be added because the name is already bound to another object.
NameNotFoundException | This exception is thrown when a component of the name cannot be resolved because it is not bound.
NamingException | This is the superclass of all exceptions thrown by operations in the Context and DirContext interfaces.
NamingSecurityException | This is the superclass of security-related exceptions thrown by operations in the Context and DirContext interfaces.
NoInitialContextException | This exception is thrown when no initial context implementation can be created.
NoPermissionException | This exception is thrown when attempting to perform an operation for which the client has no permission.
NotContextException | This exception is thrown when a naming operation proceeds to a point where a context is required to continue the operation, but the resolved object is not a context.
OperationNotSupportedException | This exception is thrown when a context implementation does not support the operation being invoked.
PartialResultException | This exception is thrown to indicate that the result being returned or returned so far is partial, and that the operation cannot be completed.
ReferralException | This abstract class is used to represent a referral exception, which is generated in response to a referral such as that returned by LDAP v3 servers.
ServiceUnavailableException | This exception is thrown when attempting to communicate with a directory or naming service and that service is not available.
SizeLimitExceededException | This exception is thrown when a method produces a result that exceeds a size-related limit.
TimeLimitExceededException | This exception is thrown when a method does not terminate within the specified time limit.

Package javax.naming Description

Provides the classes and interfaces for accessing naming services.

This package defines the naming operations of the Java Naming and Directory InterfaceTM (JNDI). JNDI provides naming and directory functionality to applications written in the Java programming language. It is designed to be independent of any specific naming or directory service implementation. Thus a variety of services--new, emerging, and already deployed ones--can be accessed in a common way.

Context

This package defines the notion of a context, represented by the Context interface. A context consists of a set of name-to-object bindings. Context is the core interface for looking up, binding, unbinding, and renaming objects, and for creating and destroying subcontexts.

lookup() is the most commonly used operation. You supply lookup() the name of the object you want to look up, and it returns the object bound to that name. For example, the following code fragment looks up a printer and sends a document to the printer object to be printed:

Printer printer = (Printer)ctx.lookup("treekiller");
printer.print(report);

Names

Every naming method in the Context interface has two overloads: one that accepts a Name argument and one that accepts a string name. Name is an interface that represents a generic name--an ordered sequence of zero of more components. For these methods, Name can be used to represent a composite name (CompositeName) so that you can name an object using a name which spans multiple namespaces.

The overloads that accept Name are useful for applications that need to manipulate names: composing them, comparing components, and so on. The overloads that accept string names are likely to be more useful for simple applications, such as those that simply read in a name and look up the corresponding object.

Bindings

The Binding class represents a name-to-object binding. It is a tuple containing the name of the bound object, the name of the object's class, and the object itself.

The Binding class is actually a subclass of NameClassPair, which consists simply of the object's name and the object's class name. The NameClassPair is useful when you only want information about the object's class and do not want to pay the extra cost of getting the object.

References

Objects are stored in naming and directory services in different ways. If an object store supports storing Java objects, it might support storing an object in its serialized form. However, some naming and directory services do not support the storing of Java objects. Furthermore, for some objects in the directory, Java programs are but one group of applications that access them. In this case, a serialized Java object might not be the most appropriate representation. JNDI defines a reference, represented by the Reference class, which contains information on how to construct a copy of the object. JNDI will attempt to turn references looked up from the directory into the Java objects they represent, so that JNDI clients have the illusion that what is stored in the directory are Java objects.

The Initial Context

In JNDI, all naming and directory operations are performed relative to a context. There are no absolute roots. Therefore JNDI defines an initial context, InitialContext, which provides a starting point for naming and directory operations. Once you have an initial context, you can use it to look up other contexts and objects.

Exceptions

JNDI defines a class hierarchy for exceptions that can be thrown in the course of performing naming and directory operations. The root of this class hierarchy is NamingException. Programs interested in dealing with a particular exception can catch the corresponding subclass of the exception. Otherwise, programs should catch NamingException.

Package Specification

The JNDI API Specification and related documents can be found in the JNDI documentation.

Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.naming Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.naming

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.naming.CompositeName (implements javax.naming.Name)
    • javax.naming.CompoundName (implements javax.naming.Name)
    • javax.naming.InitialContext (implements javax.naming.Context)
    • javax.naming.NameClassPair (implements java.io.Serializable)
      • javax.naming.Binding
    • javax.naming.RefAddr (implements java.io.Serializable)
      • javax.naming.BinaryRefAddr
      • javax.naming.StringRefAddr
    • javax.naming.Reference (implements java.lang.Cloneable, java.io.Serializable)
      • javax.naming.LinkRef
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.naming.NamingException
          • javax.naming.CannotProceedException
          • javax.naming.CommunicationException
          • javax.naming.ConfigurationException
          • javax.naming.ContextNotEmptyException
          • javax.naming.InsufficientResourcesException
          • javax.naming.InterruptedNamingException
          • javax.naming.InvalidNameException
          • javax.naming.LimitExceededException
            • javax.naming.SizeLimitExceededException
            • javax.naming.TimeLimitExceededException
          • javax.naming.LinkException
            • javax.naming.LinkLoopException
            • javax.naming.MalformedLinkException
          • javax.naming.NameAlreadyBoundException
          • javax.naming.NameNotFoundException
          • javax.naming.NamingSecurityException
            • javax.naming.AuthenticationException
            • javax.naming.AuthenticationNotSupportedException
            • javax.naming.NoPermissionException
          • javax.naming.NoInitialContextException
          • javax.naming.NotContextException
          • javax.naming.OperationNotSupportedException
          • javax.naming.PartialResultException
          • javax.naming.ReferralException
          • javax.naming.ServiceUnavailableException

Interface Hierarchy

  • java.lang.Cloneable
    • javax.naming.Name (also extends java.lang.Comparable<T>, java.io.Serializable)
  • java.lang.Comparable<T>
    • javax.naming.Name (also extends java.lang.Cloneable, java.io.Serializable)
  • javax.naming.Context
  • java.util.Enumeration<E>
    • javax.naming.NamingEnumeration<T>
  • javax.naming.NameParser
  • javax.naming.Referenceable
  • java.io.Serializable
    • javax.naming.Name (also extends java.lang.Cloneable, java.lang.Comparable<T>)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.naming

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.naming

Packages that use javax.naming
javax.naming | Provides the classes and interfaces for accessing naming services.
javax.naming.directory | Extends the javax.naming package to provide functionality for accessing directory services.
javax.naming.event | Provides support for event notification when accessing naming and directory services.
javax.naming.ldap | Provides support for LDAPv3 extended operations and controls.
javax.naming.spi | Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.
javax.sql.rowset.spi | The standard classes and interfaces that a third party vendor has to use in its implementation of a synchronization provider.

Classes in javax.naming used by javax.naming
Binding
This class represents a name-to-object binding found in a context.
Context
This interface represents a naming context, which consists of a set of name-to-object bindings.
InvalidNameException
This exception indicates that the name being specified does not conform to the naming syntax of a naming system.
LimitExceededException
This exception is thrown when a method terminates abnormally due to a user or system specified limit.
LinkException
This exception is used to describe problems encounter while resolving links.
Name
The Name interface represents a generic name -- an ordered sequence of components.
NameClassPair
This class represents the object name and class name pair of a binding found in a context.
NameParser
This interface is used for parsing names from a hierarchical namespace.
NamingEnumeration
This interface is for enumerating lists returned by methods in the javax.naming and javax.naming.directory packages.
NamingException
This is the superclass of all exceptions thrown by operations in the Context and DirContext interfaces.
NamingSecurityException
This is the superclass of security-related exceptions thrown by operations in the Context and DirContext interfaces.
RefAddr
This class represents the address of a communications end-point.
Reference
This class represents a reference to an object that is found outside of the naming/directory system.

Classes in javax.naming used by javax.naming.directory
Binding
This class represents a name-to-object binding found in a context.
Context
This interface represents a naming context, which consists of a set of name-to-object bindings.
InitialContext
This class is the starting context for performing naming operations.
Name
The Name interface represents a generic name -- an ordered sequence of components.
NameClassPair
This class represents the object name and class name pair of a binding found in a context.
NamingEnumeration
This interface is for enumerating lists returned by methods in the javax.naming and javax.naming.directory packages.
NamingException
This is the superclass of all exceptions thrown by operations in the Context and DirContext interfaces.

Classes in javax.naming used by javax.naming.event
Binding
This class represents a name-to-object binding found in a context.
Context
This interface represents a naming context, which consists of a set of name-to-object bindings.
Name
The Name interface represents a generic name -- an ordered sequence of components.
NamingException
This is the superclass of all exceptions thrown by operations in the Context and DirContext interfaces.

Classes in javax.naming used by javax.naming.ldap
Context
This interface represents a naming context, which consists of a set of name-to-object bindings.
InitialContext
This class is the starting context for performing naming operations.
InvalidNameException
This exception indicates that the name being specified does not conform to the naming syntax of a naming system.
Name
The Name interface represents a generic name -- an ordered sequence of components.
NamingException
This is the superclass of all exceptions thrown by operations in the Context and DirContext interfaces.
ReferralException
This abstract class is used to represent a referral exception, which is generated in response to a referral such as that returned by LDAP v3 servers.

Classes in javax.naming used by javax.naming.spi
CannotProceedException
This exception is thrown to indicate that the operation reached a point in the name where the operation cannot proceed any further.
Context
This interface represents a naming context, which consists of a set of name-to-object bindings.
Name
The Name interface represents a generic name -- an ordered sequence of components.
NamingException
This is the superclass of all exceptions thrown by operations in the Context and DirContext interfaces.

Classes in javax.naming used by javax.sql.rowset.spi
Context
This interface represents a naming context, which consists of a set of name-to-object bindings.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AuthenticationException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class AuthenticationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.NamingSecurityException
                    extended by  javax.naming.AuthenticationException
All Implemented Interfaces:
Serializable
public class AuthenticationException
extends NamingSecurityException

This exception is thrown when an authentication error occurs while accessing the naming or directory service. An authentication error can happen, for example, when the credentials supplied by the user program is invalid or otherwise fails to authenticate the user to the naming/directory service.

If the program wants to handle this exception in particular, it should catch AuthenticationException explicitly before attempting to catch NamingException. After catching AuthenticationException, the program could reattempt the authentication by updating the resolved context's environment properties with the appropriate appropriate credentials.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
AuthenticationException()
Constructs a new instance of AuthenticationException.
AuthenticationException(String explanation)
Constructs a new instance of AuthenticationException using the explanation supplied.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AuthenticationException

public AuthenticationException(String explanation)
Constructs a new instance of AuthenticationException using the explanation supplied. All other fields default to null.

Parameters:
explanation - A possibly null string containing additional detail about this exception.
See Also:
Throwable.getMessage()

AuthenticationException

public AuthenticationException()
Constructs a new instance of AuthenticationException. All fields are set to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AuthenticationNotSupportedException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class AuthenticationNotSupportedException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.NamingSecurityException
                    extended by  javax.naming.AuthenticationNotSupportedException
All Implemented Interfaces:
Serializable
public class AuthenticationNotSupportedException
extends NamingSecurityException

This exception is thrown when the particular flavor of authentication requested is not supported. For example, if the program is attempting to use strong authentication but the directory/naming supports only simple authentication, this exception would be thrown. Identification of a particular flavor of authentication is provider- and server-specific. It may be specified using specific authentication schemes such those identified using SASL, or a generic authentication specifier (such as "simple" and "strong").

If the program wants to handle this exception in particular, it should catch AuthenticationNotSupportedException explicitly before attempting to catch NamingException. After catching AuthenticationNotSupportedException, the program could reattempt the authentication using a different authentication flavor by updating the resolved context's environment properties accordingly.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
AuthenticationNotSupportedException()
Constructs a new instance of AuthenticationNotSupportedException all name resolution fields and explanation initialized to null.
AuthenticationNotSupportedException(String explanation)
Constructs a new instance of AuthenticationNotSupportedException using an explanation.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AuthenticationNotSupportedException

public AuthenticationNotSupportedException(String explanation)
Constructs a new instance of AuthenticationNotSupportedException using an explanation. All other fields default to null.

Parameters:
explanation - A possibly null string containing additional detail about this exception.
See Also:
Throwable.getMessage()

AuthenticationNotSupportedException

public AuthenticationNotSupportedException()
Constructs a new instance of AuthenticationNotSupportedException all name resolution fields and explanation initialized to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BinaryRefAddr

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class BinaryRefAddr

java.lang.Object
    extended by  javax.naming.RefAddr
        extended by  javax.naming.BinaryRefAddr
All Implemented Interfaces:
Serializable
public class BinaryRefAddr
extends RefAddr

This class represents the binary form of the address of a communications end-point.

A BinaryRefAddr consists of a type that describes the communication mechanism and an opaque buffer containing the address description specific to that communication mechanism. The format and interpretation of the address type and the contents of the opaque buffer are based on the agreement of three parties: the client that uses the address, the object/server that can be reached using the address, and the administrator or program that creates the address.

An example of a binary reference address is an BER X.500 presentation address. Another example of a binary reference address is a serialized form of a service's object handle.

A binary reference address is immutable in the sense that its fields once created, cannot be replaced. However, it is possible to access the byte array used to hold the opaque buffer. Programs are strongly recommended against changing this byte array. Changes to this byte array need to be explicitly synchronized.

Since:
1.3
See Also:
RefAddr, StringRefAddr, Serialized Form

Field Summary
Fields inherited from class javax.naming.RefAddr
addrType
Constructor Summary
BinaryRefAddr(String addrType, byte[] src)
Constructs a new instance of BinaryRefAddr using its address type and a byte array for contents.
BinaryRefAddr(String addrType, byte[] src, int offset, int count)
Constructs a new instance of BinaryRefAddr using its address type and a region of a byte array for contents.
Method Summary
boolean | equals(Object obj) Determines whether obj is equal to this address.
Object | getContent() Retrieves the contents of this address as an Object.
int | hashCode() Computes the hash code of this address using its address type and contents.
String | toString() Generates the string representation of this address.
Methods inherited from class javax.naming.RefAddr
getType
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

BinaryRefAddr

public BinaryRefAddr(String addrType,
                     byte[] src)
Constructs a new instance of BinaryRefAddr using its address type and a byte array for contents.

Parameters:
addrType - A non-null string describing the type of the address.
src - The non-null contents of the address as a byte array. The contents of src is copied into the new BinaryRefAddr.

BinaryRefAddr

public BinaryRefAddr(String addrType,
                     byte[] src,
                     int offset,
                     int count)
Constructs a new instance of BinaryRefAddr using its address type and a region of a byte array for contents.

Parameters:
addrType - A non-null string describing the type of the address.
src - The non-null contents of the address as a byte array. The contents of src is copied into the new BinaryRefAddr.
offset - The starting index in src to get the bytes. 0 <= offset="offset" <="src.length.count - The number of bytes to extract from src. 0 <= count="count" <="src.length-offset.
Method Detail

getContent

public Object getContent()
Retrieves the contents of this address as an Object. The result is a byte array. Changes to this array will affect this BinaryRefAddr's contents. Programs are recommended against changing this array's contents and to lock the buffer if they need to change it.

Specified by:
getContent in class RefAddr
Returns:
The non-null buffer containing this address's contents.

equals

public boolean equals(Object obj)
Determines whether obj is equal to this address. It is equal if it contains the same address type and their contents are byte-wise equivalent.

Overrides:
equals in class RefAddr
Parameters:
obj - The possibly null object to check.
Returns:
true if the object is equal; false otherwise.
See Also:
RefAddr.getContent(), RefAddr.getType()

hashCode

public int hashCode()
Computes the hash code of this address using its address type and contents. Two BinaryRefAddrs have the same hash code if they have the same address type and the same contents. It is also possible for different BinaryRefAddrs to have the same hash code.

Overrides:
hashCode in class RefAddr
Returns:
The hash code of this address as an int.
See Also:
Object.hashCode()

toString

public String toString()
Generates the string representation of this address. The string consists of the address's type and contents with labels. The first 32 bytes of contents are displayed (in hexadecimal). If there are more than 32 bytes, "..." is used to indicate more. This string is meant to used for debugging purposes and not meant to be interpreted programmatically.

Overrides:
toString in class RefAddr
Returns:
The non-null string representation of this address.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Binding

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class Binding

java.lang.Object
    extended by  javax.naming.NameClassPair
        extended by  javax.naming.Binding
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
SearchResult
public class Binding
extends NameClassPair

This class represents a name-to-object binding found in a context.

A context consists of name-to-object bindings. The Binding class represents such a binding. It consists of a name and an object. The Context.listBindings() method returns an enumeration of Binding.

Use subclassing for naming systems that generate contents of a binding dynamically.

A Binding instance is not synchronized against concurrent access by multiple threads. Threads that need to access a Binding concurrently should synchronize amongst themselves and provide the necessary locking.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
Binding(String name, Object obj)
Constructs an instance of a Binding given its name and object.
Binding(String name, Object obj, boolean isRelative)
Constructs an instance of a Binding given its name, object, and whether the name is relative.
Binding(String name, String className, Object obj)
Constructs an instance of a Binding given its name, class name, and object.
Binding(String name, String className, Object obj, boolean isRelative)
Constructs an instance of a Binding given its name, class name, object, and whether the name is relative.
Method Summary
String | getClassName() Retrieves the class name of the object bound to the name of this binding.
Object | getObject() Retrieves the object bound to the name of this binding.
void | setObject(Object obj) Sets the object associated with this binding.
String | toString() Generates the string representation of this binding.
Methods inherited from class javax.naming.NameClassPair
getName, getNameInNamespace, isRelative, setClassName, setName, setNameInNamespace, setRelative
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Binding

public Binding(String name,
               Object obj)
Constructs an instance of a Binding given its name and object.

getClassName() will return the class name of obj (or null if obj is null) unless the class name has been explicitly set using setClassName()

Parameters:
name - The non-null name of the object. It is relative to the target context (which is named by the first parameter of the listBindings() method)
obj - The possibly null object bound to name.
See Also:
NameClassPair.setClassName(java.lang.String)

Binding

public Binding(String name,
               Object obj,
               boolean isRelative)
Constructs an instance of a Binding given its name, object, and whether the name is relative.

getClassName() will return the class name of obj (or null if obj is null) unless the class name has been explicitly set using setClassName()

Parameters:
name - The non-null string name of the object.
obj - The possibly null object bound to name.
isRelative - true if name is a name relative to the target context (which is named by the first parameter of the listBindings() method); false if name is a URL string.
See Also:
NameClassPair.isRelative(),
NameClassPair.setRelative(boolean),
NameClassPair.setClassName(java.lang.String)

Binding

public Binding(String name,
               String className,
               Object obj)
Constructs an instance of a Binding given its name, class name, and object.

Parameters:
name - The non-null name of the object. It is relative to the target context (which is named by the first parameter of the listBindings() method)
className - The possibly null class name of the object bound to name. If null, the class name of obj is returned by getClassName(). If obj is also null, getClassName() will return null.
obj - The possibly null object bound to name.
See Also:
NameClassPair.setClassName(java.lang.String)

Binding

public Binding(String name,
               String className,
               Object obj,
               boolean isRelative)
Constructs an instance of a Binding given its name, class name, object, and whether the name is relative.

Parameters:
name - The non-null string name of the object.
className - The possibly null class name of the object bound to name. If null, the class name of obj is returned by getClassName(). If obj is also null, getClassName() will return null.
obj - The possibly null object bound to name.
isRelative - true if name is a name relative to the target context (which is named by the first parameter of the listBindings() method); false if name is a URL string.
See Also:
NameClassPair.isRelative(),
NameClassPair.setRelative(boolean),
NameClassPair.setClassName(java.lang.String)
Method Detail

getClassName

public String getClassName()
Retrieves the class name of the object bound to the name of this binding. If the class name has been set explicitly, return it. Otherwise, if this binding contains a non-null object, that object's class name is used. Otherwise, null is returned.

Overrides:
getClassName in class NameClassPair
Returns:
A possibly null string containing class name of object bound.
See Also:
getObject(),
getClassName(),
NameClassPair.setClassName(java.lang.String)

getObject

public Object getObject()
Retrieves the object bound to the name of this binding.

Returns:
The object bound; null if this binding does not contain an object.
See Also:
setObject(java.lang.Object)

setObject

public void setObject(Object obj)
Sets the object associated with this binding.

Parameters:
obj - The possibly null object to use.
See Also:
getObject()

toString

public String toString()
Generates the string representation of this binding. The string representation consists of the string representation of the name/class pair and the string representation of this binding's object, separated by ':'. The contents of this string is useful for debugging and is not meant to be interpreted programmatically.

Overrides:
toString in class NameClassPair
Returns:
The non-null string representation of this binding.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CannotProceedException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class CannotProceedException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.CannotProceedException
All Implemented Interfaces:
Serializable
public class CannotProceedException
extends NamingException

This exception is thrown to indicate that the operation reached a point in the name where the operation cannot proceed any further. When performing an operation on a composite name, a naming service provider may reach a part of the name that does not belong to its namespace. At that point, it can construct a CannotProceedException and then invoke methods provided by javax.naming.spi.NamingManager (such as getContinuationContext()) to locate another provider to continue the operation. If this is not possible, this exception is raised to the caller of the context operation.

If the program wants to handle this exception in particular, it should catch CannotProceedException explicitly before attempting to catch NamingException.

A CannotProceedException instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify CannotProceedException should lock the object.

Since:
1.3
See Also:
Serialized Form

Field Summary
protected Name | altName Contains the name of the resolved object, relative to the context altNameCtx.
protected Context | altNameCtx Contains the context relative to which altName is specified.
protected Hashtable<?,?> | environment Contains the environment relevant for the Context or DirContext method that cannot proceed.
protected Name | remainingNewName Contains the remaining unresolved part of the second "name" argument to Context.rename().
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
CannotProceedException()
Constructs a new instance of CannotProceedException.
CannotProceedException(String explanation)
Constructs a new instance of CannotProceedException using an explanation.
Method Summary
 Name getAltName()
Retrieves the altName field of this exception.
 Context getAltNameCtx()
Retrieves the altNameCtx field of this exception.
 Hashtable<?,?> getEnvironment()
Retrieves the environment that was in effect when this exception was created.
 Name getRemainingNewName()
Retrieves the "remaining new name" field of this exception, which is used when this exception is thrown during a rename() operation.
 void setAltName(Name altName)
Sets the altName field of this exception.
 void setAltNameCtx(Context altNameCtx)
Sets the altNameCtx field of this exception.
 void setEnvironment(Hashtable<?,?> environment)
Sets the environment that will be returned when getEnvironment() is called.
 void setRemainingNewName(Name newName)
Sets the "remaining new name" field of this exception.
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

remainingNewName

protected Name remainingNewName
Contains the remaining unresolved part of the second "name" argument to Context.rename(). This information necessary for continuing the Context.rename() operation.

This field is initialized to null. It should not be manipulated directly: it should be accessed and updated using getRemainingName() and setRemainingName().

See Also:
getRemainingNewName(), setRemainingNewName(javax.naming.Name)

environment

protected Hashtable<?,?> environment
Contains the environment relevant for the Context or DirContext method that cannot proceed.

This field is initialized to null. It should not be manipulated directly: it should be accessed and updated using getEnvironment() and setEnvironment().

See Also:
getEnvironment(), setEnvironment(java.util.Hashtable)

altName

protected Name altName
Contains the name of the resolved object, relative to the context altNameCtx. It is a composite name. If null, then no name is specified. See the javax.naming.spi.ObjectFactory.getObjectInstance method for details on how this is used.

This field is initialized to null. It should not be manipulated directly: it should be accessed and updated using getAltName() and setAltName().

See Also:
getAltName(), setAltName(javax.naming.Name), altNameCtx, ObjectFactory.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable)

altNameCtx

protected Context altNameCtx
Contains the context relative to which altName is specified. If null, then the default initial context is implied. See the javax.naming.spi.ObjectFactory.getObjectInstance method for details on how this is used.

This field is initialized to null. It should not be manipulated directly: it should be accessed and updated using getAltNameCtx() and setAltNameCtx().

See Also:
getAltNameCtx(), setAltNameCtx(javax.naming.Context), altName, ObjectFactory.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable)
Constructor Detail

CannotProceedException

public CannotProceedException(String explanation)
Constructs a new instance of CannotProceedException using an explanation. All unspecified fields default to null.

Parameters:
explanation - A possibly null string containing additional detail about this exception. If null, this exception has no detail message.
See Also:
Throwable.getMessage()

CannotProceedException

public CannotProceedException()
Constructs a new instance of CannotProceedException. All fields default to null.

Method Detail

getEnvironment

public Hashtable<?,?> getEnvironment()
Retrieves the environment that was in effect when this exception was created.

Returns:
Possibly null environment property set. null means no environment was recorded for this exception.
See Also:
setEnvironment(java.util.Hashtable)

setEnvironment

public void setEnvironment(Hashtable<?,?> environment)
Sets the environment that will be returned when getEnvironment() is called.

Parameters:
environment - A possibly null environment property set. null means no environment is being recorded for this exception.
See Also:
getEnvironment()

getRemainingNewName

public Name getRemainingNewName()
Retrieves the "remaining new name" field of this exception, which is used when this exception is thrown during a rename() operation.

Returns:
The possibly null part of the new name that has not been resolved. It is a composite name. It can be null, which means the remaining new name field has not been set.
See Also:
setRemainingNewName(javax.naming.Name)

setRemainingNewName

public void setRemainingNewName(Name newName)
Sets the "remaining new name" field of this exception. This is the value returned by getRemainingNewName().

newName is a composite name. If the intent is to set this field using a compound name or string, you must "stringify" the compound name, and create a composite name with a single component using the string. You can then invoke this method using the resulting composite name.

A copy of newName is made and stored. Subsequent changes to name does not affect the copy in this NamingException and vice versa.

Parameters:
newName - The possibly null name to set the "remaining new name" to. If null, it sets the remaining name field to null.
See Also:
getRemainingNewName()

getAltName

public Name getAltName()
Retrieves the altName field of this exception. This is the name of the resolved object, relative to the context altNameCtx. It will be used during a subsequent call to the javax.naming.spi.ObjectFactory.getObjectInstance method.

Returns:
The name of the resolved object, relative to altNameCtx. It is a composite name. If null, then no name is specified.
See Also:
setAltName(javax.naming.Name),
getAltNameCtx(),
ObjectFactory.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable)

setAltName

public void setAltName(Name altName)
Sets the altName field of this exception.

Parameters:
altName - The name of the resolved object, relative to altNameCtx. It is a composite name. If null, then no name is specified.
See Also:
getAltName(), setAltNameCtx(javax.naming.Context)

getAltNameCtx

public Context getAltNameCtx()
Retrieves the altNameCtx field of this exception. This is the context relative to which altName is named. It will be used during a subsequent call to the javax.naming.spi.ObjectFactory.getObjectInstance method.

Returns:
The context relative to which altName is named. If null, then the default initial context is implied.
See Also:
setAltNameCtx(javax.naming.Context),
getAltName(),
ObjectFactory.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable)

setAltNameCtx

public void setAltNameCtx(Context altNameCtx)
Sets the altNameCtx field of this exception.

Parameters:
altNameCtx - The context relative to which altName is named. If null, then the default initial context is implied.
See Also:
getAltNameCtx(), setAltName(javax.naming.Name)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.naming.AuthenticationException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.AuthenticationException

No usage of javax.naming.AuthenticationException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.AuthenticationNotSupportedException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.AuthenticationNotSupportedException

No usage of javax.naming.AuthenticationNotSupportedException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.BinaryRefAddr

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.BinaryRefAddr

No usage of javax.naming.BinaryRefAddr

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.Binding

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.Binding

Packages that use Binding
javax.naming | Provides the classes and interfaces for accessing naming services.
javax.naming.directory | Extends the javax.naming package to provide functionality for accessing directory services.
javax.naming.event | Provides support for event notification when accessing naming and directory services.

Uses of Binding in javax.naming

Methods in javax.naming that return types with arguments of type Binding
NamingEnumeration<Binding> | Context.listBindings(Name name) Enumerates the names bound in the named context, along with the objects bound to them.
NamingEnumeration<Binding> | InitialContext.listBindings(Name name)
NamingEnumeration<Binding> | Context.listBindings(String name) Enumerates the names bound in the named context, along with the objects bound to them.
NamingEnumeration<Binding> | InitialContext.listBindings(String name)

Uses of Binding in javax.naming.directory

Subclasses of Binding in javax.naming.directory
 class SearchResult
This class represents an item in the NamingEnumeration returned as a result of the DirContext.search() methods.

Uses of Binding in javax.naming.event

Fields in javax.naming.event declared as Binding
protected Binding | NamingEvent.newBinding Contains information about the object after the change.
protected Binding | NamingEvent.oldBinding Contains information about the object before the change.

Methods in javax.naming.event that return Binding
Binding | NamingEvent.getNewBinding() Retrieves the binding of the object after the change.
Binding | NamingEvent.getOldBinding() Retrieves the binding of the object before the change.

Constructors in javax.naming.event with parameters of type Binding
NamingEvent(EventContext source, int type, Binding newBd, Binding oldBd, Object changeInfo)
Constructs an instance of NamingEvent.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.CannotProceedException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.CannotProceedException

Packages that use CannotProceedException
javax.naming.spi Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.

Uses of CannotProceedException in javax.naming.spi

Methods in javax.naming.spi with parameters of type CannotProceedException
static Context | NamingManager.getContinuationContext(CannotProceedException cpe) Creates a context in which to continue a context operation.
static DirContext | DirectoryManager.getContinuationDirContext(CannotProceedException cpe) Creates a context in which to continue a DirContext operation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.CommunicationException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.CommunicationException

No usage of javax.naming.CommunicationException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.CompositeName

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.CompositeName

No usage of javax.naming.CompositeName

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.CompoundName

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.CompoundName

No usage of javax.naming.CompoundName

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ConfigurationException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ConfigurationException

No usage of javax.naming.ConfigurationException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ContextNotEmptyException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ContextNotEmptyException

No usage of javax.naming.ContextNotEmptyException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.InitialContext

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.InitialContext

Packages that use InitialContext
javax.naming.directory | Extends the javax.naming package to provide functionality for accessing directory services.
javax.naming.ldap | Provides support for LDAPv3 extended operations and controls.

Uses of InitialContext in javax.naming.directory

Subclasses of InitialContext in javax.naming.directory
 class InitialDirContext
This class is the starting context for performing directory operations.

Uses of InitialContext in javax.naming.ldap

Subclasses of InitialContext in javax.naming.ldap
 class InitialLdapContext
This class is the starting context for performing LDAPv3-style extended operations and controls.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.InsufficientResourcesException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.InsufficientResourcesException

No usage of javax.naming.InsufficientResourcesException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.InterruptedNamingException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.InterruptedNamingException

No usage of javax.naming.InterruptedNamingException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.InvalidNameException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.InvalidNameException

Packages that use InvalidNameException
javax.naming | Provides the classes and interfaces for accessing naming services.
javax.naming.ldap | Provides support for LDAPv3 extended operations and controls.

Uses of InvalidNameException in javax.naming

Methods in javax.naming that throw InvalidNameException
Name | CompoundName.add(int posn, String comp) Adds a single component at a specified position within this compound name.
Name | CompositeName.add(int posn, String comp) Adds a single component at a specified position within this composite name.
Name | Name.add(int posn, String comp) Adds a single component at a specified position within this name.
Name | CompoundName.add(String comp) Adds a single component to the end of this compound name.
Name | CompositeName.add(String comp) Adds a single component to the end of this composite name.
Name | Name.add(String comp) Adds a single component to the end of this name.
Name | CompoundName.addAll(int posn, Name n) Adds the components of a compound name -- in order -- at a specified position within this compound name.
Name | CompositeName.addAll(int posn, Name n) Adds the components of a composite name -- in order -- at a specified position within this composite name.
Name | Name.addAll(int posn, Name n) Adds the components of a name -- in order -- at a specified position within this name.
Name | CompoundName.addAll(Name suffix) Adds the components of a compound name -- in order -- to the end of this compound name.
Name | CompositeName.addAll(Name suffix) Adds the components of a composite name -- in order -- to the end of this composite name.
Name | Name.addAll(Name suffix) Adds the components of a name -- in order -- to the end of this name.
Object | CompoundName.remove(int posn) Deletes a component from this compound name.
Object | CompositeName.remove(int posn) Deletes a component from this composite name.
Object | Name.remove(int posn) Removes a component from this name.

Constructors in javax.naming that throw InvalidNameException
CompositeName(String n)
Constructs a new composite name instance by parsing the string n using the composite name syntax (left-to-right, slash separated).
CompoundName(String n, Properties syntax)
Constructs a new compound name instance by parsing the string n using the syntax specified by the syntax properties supplied.

Uses of InvalidNameException in javax.naming.ldap

Methods in javax.naming.ldap that throw InvalidNameException
Name | LdapName.add(int posn, String comp) Adds a single component at a specified position within this LDAP name.
Name | LdapName.add(String comp) Adds a single component to the end of this LDAP name.
Name | LdapName.addAll(int posn, Name suffix) Adds the components of a name -- in order -- at a specified position within this name.
Name | LdapName.addAll(Name suffix) Adds the components of a name -- in order -- to the end of this name.
Object | LdapName.remove(int posn) Removes a component from this LDAP name.

Constructors in javax.naming.ldap that throw InvalidNameException
LdapName(String name)
Constructs an LDAP name from the given distinguished name.
Rdn(Attributes attrSet)
Constructs an Rdn from the given attribute set.
Rdn(String rdnString)
Constructs an Rdn from the given string.
Rdn(String type, Object value)
Constructs an Rdn from the given attribute type and value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.LimitExceededException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.LimitExceededException

Packages that use LimitExceededException
javax.naming Provides the classes and interfaces for accessing naming services.

Uses of LimitExceededException in javax.naming

Subclasses of LimitExceededException in javax.naming
class | SizeLimitExceededException This exception is thrown when a method produces a result that exceeds a size-related limit.
class | TimeLimitExceededException This exception is thrown when a method does not terminate within the specified time limit.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.LinkException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.LinkException

Packages that use LinkException
javax.naming Provides the classes and interfaces for accessing naming services.

Uses of LinkException in javax.naming

Subclasses of LinkException in javax.naming
class | LinkLoopException This exception is thrown when a loop was detected will attempting to resolve a link, or an implementation specific limit on link counts has been reached.
class | MalformedLinkException This exception is thrown when a malformed link was encountered while resolving or constructing a link.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.LinkLoopException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.LinkLoopException

No usage of javax.naming.LinkLoopException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.LinkRef

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.LinkRef

No usage of javax.naming.LinkRef

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.MalformedLinkException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.MalformedLinkException

No usage of javax.naming.MalformedLinkException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.NameAlreadyBoundException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.NameAlreadyBoundException

No usage of javax.naming.NameAlreadyBoundException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.NameClassPair

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.NameClassPair

Packages that use NameClassPair
javax.naming | Provides the classes and interfaces for accessing naming services.
javax.naming.directory | Extends the javax.naming package to provide functionality for accessing directory services.

Uses of NameClassPair in javax.naming

Subclasses of NameClassPair in javax.naming
 class Binding
This class represents a name-to-object binding found in a context.

Methods in javax.naming that return types with arguments of type NameClassPair
NamingEnumeration<NameClassPair> | Context.list(Name name) Enumerates the names bound in the named context, along with the class names of objects bound to them.
NamingEnumeration<NameClassPair> | InitialContext.list(Name name)
NamingEnumeration<NameClassPair> | Context.list(String name) Enumerates the names bound in the named context, along with the class names of objects bound to them.
NamingEnumeration<NameClassPair> | InitialContext.list(String name)

Uses of NameClassPair in javax.naming.directory

Subclasses of NameClassPair in javax.naming.directory
 class SearchResult
This class represents an item in the NamingEnumeration returned as a result of the DirContext.search() methods.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.NameNotFoundException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.NameNotFoundException

No usage of javax.naming.NameNotFoundException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.NamingException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.NamingException

Packages that use NamingException
javax.naming | Provides the classes and interfaces for accessing naming services.
javax.naming.directory | Extends the javax.naming package to provide functionality for accessing directory services.
javax.naming.event | Provides support for event notification when accessing naming and directory services.
javax.naming.ldap | Provides support for LDAPv3 extended operations and controls.
javax.naming.spi | Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.

Uses of NamingException in javax.naming

Subclasses of NamingException in javax.naming
class | AuthenticationException This exception is thrown when an authentication error occurs while accessing the naming or directory service.
class | AuthenticationNotSupportedException This exception is thrown when the particular flavor of authentication requested is not supported.
class | CannotProceedException This exception is thrown to indicate that the operation reached a point in the name where the operation cannot proceed any further.
class | CommunicationException This exception is thrown when the client is unable to communicate with the directory or naming service.
class | ConfigurationException This exception is thrown when there is a configuration problem.
class | ContextNotEmptyException This exception is thrown when attempting to destroy a context that is not empty.
class | InsufficientResourcesException This exception is thrown when resources are not available to complete the requested operation.
class | InterruptedNamingException This exception is thrown when the naming operation being invoked has been interrupted.
class | InvalidNameException This exception indicates that the name being specified does not conform to the naming syntax of a naming system.
class | LimitExceededException This exception is thrown when a method terminates abnormally due to a user or system specified limit.
class | LinkException This exception is used to describe problems encounter while resolving links.
class | LinkLoopException This exception is thrown when a loop was detected will attempting to resolve a link, or an implementation specific limit on link counts has been reached.
class | MalformedLinkException This exception is thrown when a malformed link was encountered while resolving or constructing a link.
class | NameAlreadyBoundException This exception is thrown by methods to indicate that a binding cannot be added because the name is already bound to another object.
class | NameNotFoundException This exception is thrown when a component of the name cannot be resolved because it is not bound.
class | NamingSecurityException This is the superclass of security-related exceptions thrown by operations in the Context and DirContext interfaces.
class | NoInitialContextException This exception is thrown when no initial context implementation can be created.
class | NoPermissionException This exception is thrown when attempting to perform an operation for which the client has no permission.
class | NotContextException This exception is thrown when a naming operation proceeds to a point where a context is required to continue the operation, but the resolved object is not a context.
class | OperationNotSupportedException This exception is thrown when a context implementation does not support the operation being invoked.
class | PartialResultException This exception is thrown to indicate that the result being returned or returned so far is partial, and that the operation cannot be completed.
class | ReferralException This abstract class is used to represent a referral exception, which is generated in response to a referral such as that returned by LDAP v3 servers.
class | ServiceUnavailableException This exception is thrown when attempting to communicate with a directory or naming service and that service is not available.
class | SizeLimitExceededException This exception is thrown when a method produces a result that exceeds a size-related limit.
class | TimeLimitExceededException This exception is thrown when a method does not terminate within the specified time limit.

Methods in javax.naming that throw NamingException
 Object Context.addToEnvironment(String propName, Object propVal)
Adds a new environment property to the environment of this context.
 Object InitialContext.addToEnvironment(String propName, Object propVal)
 void Context.bind(Name name, Object obj)
Binds a name to an object.
 void InitialContext.bind(Name name, Object obj)
 void Context.bind(String name, Object obj)
Binds a name to an object.
 void InitialContext.bind(String name, Object obj)
 void NamingEnumeration.close()
Closes this enumeration.
 void Context.close()
Closes this context.
 void InitialContext.close()
 Name Context.composeName(Name name, Name prefix)
Composes the name of this context with a name relative to this context.
 Name InitialContext.composeName(Name name, Name prefix)
Composes the name of this context with a name relative to this context.
 String Context.composeName(String name, String prefix)
Composes the name of this context with a name relative to this context.
 String InitialContext.composeName(String name, String prefix)
Composes the name of this context with a name relative to this context.
 Context Context.createSubcontext(Name name)
Creates and binds a new context.
 Context InitialContext.createSubcontext(Name name)
 Context Context.createSubcontext(String name)
Creates and binds a new context.
 Context InitialContext.createSubcontext(String name)
 void Context.destroySubcontext(Name name)
Destroys the named context and removes it from the namespace.
 void InitialContext.destroySubcontext(Name name)
 void Context.destroySubcontext(String name)
Destroys the named context and removes it from the namespace.
 void InitialContext.destroySubcontext(String name)
static
<T> T
InitialContext.doLookup(Name name)
A static method to retrieve the named object.
static
<T> T
InitialContext.doLookup(String name)
A static method to retrieve the named object.
protected  Context InitialContext.getDefaultInitCtx()
Retrieves the initial context by calling NamingManager.getInitialContext() and cache it in defaultInitCtx.
 Hashtable<?,?> Context.getEnvironment()
Retrieves the environment in effect for this context.
 Hashtable<?,?> InitialContext.getEnvironment()
 String LinkRef.getLinkName()
Retrieves the name of this link.
 String Context.getNameInNamespace()
Retrieves the full name of this context within its own namespace.
 String InitialContext.getNameInNamespace()
 NameParser Context.getNameParser(Name name)
Retrieves the parser associated with the named context.
 NameParser InitialContext.getNameParser(Name name)
 NameParser Context.getNameParser(String name)
Retrieves the parser associated with the named context.
 NameParser InitialContext.getNameParser(String name)
 Reference Referenceable.getReference()
Retrieves the Reference of this object.
abstract  Context ReferralException.getReferralContext()
Retrieves the context at which to continue the method.
abstract  Context ReferralException.getReferralContext(Hashtable<?,?> env)
Retrieves the context at which to continue the method using environment properties.
protected  Context InitialContext.getURLOrDefaultInitCtx(Name name)
Retrieves a context for resolving name.
protected  Context InitialContext.getURLOrDefaultInitCtx(String name)
Retrieves a context for resolving the string name name.
 boolean NamingEnumeration.hasMore()
Determines whether there are any more elements in the enumeration.
protected  void InitialContext.init(Hashtable<?,?> environment)
Initializes the initial context using the supplied environment.
 NamingEnumeration<NameClassPair> Context.list(Name name)
Enumerates the names bound in the named context, along with the class names of objects bound to them.
 NamingEnumeration<NameClassPair> InitialContext.list(Name name)
 NamingEnumeration<NameClassPair> Context.list(String name)
Enumerates the names bound in the named context, along with the class names of objects bound to them.
 NamingEnumeration<NameClassPair> InitialContext.list(String name)
 NamingEnumeration<Binding> Context.listBindings(Name name)
Enumerates the names bound in the named context, along with the objects bound to them.
 NamingEnumeration<Binding> InitialContext.listBindings(Name name)
 NamingEnumeration<Binding> Context.listBindings(String name)
Enumerates the names bound in the named context, along with the objects bound to them.
 NamingEnumeration<Binding> InitialContext.listBindings(String name)
 Object Context.lookup(Name name)
Retrieves the named object.
 Object InitialContext.lookup(Name name)
 Object Context.lookup(String name)
Retrieves the named object.
 Object InitialContext.lookup(String name)
 Object Context.lookupLink(Name name)
Retrieves the named object, following links except for the terminal atomic component of the name.
 Object InitialContext.lookupLink(Name name)
 Object Context.lookupLink(String name)
Retrieves the named object, following links except for the terminal atomic component of the name.
 Object InitialContext.lookupLink(String name)
 T NamingEnumeration.next()
Retrieves the next element in the enumeration.
 Name NameParser.parse(String name)
Parses a name into its components.
 void Context.rebind(Name name, Object obj)
Binds a name to an object, overwriting any existing binding.
 void InitialContext.rebind(Name name, Object obj)
 void Context.rebind(String name, Object obj)
Binds a name to an object, overwriting any existing binding.
 void InitialContext.rebind(String name, Object obj)
 Object Context.removeFromEnvironment(String propName)
Removes an environment property from the environment of this context.
 Object InitialContext.removeFromEnvironment(String propName)
 void Context.rename(Name oldName, Name newName)
Binds a new name to the object bound to an old name, and unbinds the old name.
 void InitialContext.rename(Name oldName, Name newName)
 void Context.rename(String oldName, String newName)
Binds a new name to the object bound to an old name, and unbinds the old name.
 void InitialContext.rename(String oldName, String newName)
 void Context.unbind(Name name)
Unbinds the named object.
 void InitialContext.unbind(Name name)
 void Context.unbind(String name)
Unbinds the named object.
 void InitialContext.unbind(String name)

Constructors in javax.naming that throw NamingException
InitialContext()
Constructs an initial context.
InitialContext(boolean lazy)
Constructs an initial context with the option of not initializing it.
InitialContext(Hashtable<?,?> environment)
Constructs an initial context using the supplied environment.

Uses of NamingException in javax.naming.directory

Subclasses of NamingException in javax.naming.directory
class | AttributeInUseException This exception is thrown when an operation attempts to add an attribute that already exists.
class | AttributeModificationException This exception is thrown when an attempt is made to add, or remove, or modify an attribute, its identifier, or its values that conflicts with the attribute's (schema) definition or the attribute's state.
class | InvalidAttributeIdentifierException This exception is thrown when an attempt is made to add to create an attribute with an invalid attribute identifier.
class | InvalidAttributesException This exception is thrown when an attempt is made to add or modify an attribute set that has been specified incompletely or incorrectly.
class | InvalidAttributeValueException This class is thrown when an attempt is made to add to an attribute a value that conflicts with the attribute's schema definition.
class | InvalidSearchControlsException This exception is thrown when the specification of the SearchControls for a search operation is invalid.
class | InvalidSearchFilterException This exception is thrown when the specification of a search filter is invalid.
class | NoSuchAttributeException This exception is thrown when attempting to access an attribute that does not exist.
class | SchemaViolationException This exception is thrown when a method in some ways violates the schema.

Methods in javax.naming.directory that throw NamingException
void | InitialDirContext.bind(Name name, Object obj, Attributes attrs)
void | DirContext.bind(Name name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes.
void | InitialDirContext.bind(String name, Object obj, Attributes attrs)
void | DirContext.bind(String name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes.
DirContext | InitialDirContext.createSubcontext(Name name, Attributes attrs)
DirContext | DirContext.createSubcontext(Name name, Attributes attrs) Creates and binds a new context, along with associated attributes.
DirContext | InitialDirContext.createSubcontext(String name, Attributes attrs)
DirContext | DirContext.createSubcontext(String name, Attributes attrs) Creates and binds a new context, along with associated attributes.
Object | BasicAttribute.get() Retrieves one of this attribute's values.
Object | Attribute.get() Retrieves one of this attribute's values.
Object | BasicAttribute.get(int ix)
Object | Attribute.get(int ix) Retrieves the attribute value from the ordered list of attribute values.
NamingEnumeration<?> | BasicAttribute.getAll() Retrieves an enumeration of this attribute's values.
NamingEnumeration<?> | Attribute.getAll() Retrieves an enumeration of the attribute's values.
DirContext | BasicAttribute.getAttributeDefinition() Retrieves this attribute's schema definition.
DirContext | Attribute.getAttributeDefinition() Retrieves the attribute's schema definition.
Attributes | InitialDirContext.getAttributes(Name name)
Attributes | DirContext.getAttributes(Name name) Retrieves all of the attributes associated with a named object.
Attributes | InitialDirContext.getAttributes(Name name, String[] attrIds)
Attributes | DirContext.getAttributes(Name name, String[] attrIds) Retrieves selected attributes associated with a named object.
Attributes | InitialDirContext.getAttributes(String name)
Attributes | DirContext.getAttributes(String name) Retrieves all of the attributes associated with a named object.
Attributes | InitialDirContext.getAttributes(String name, String[] attrIds)
Attributes | DirContext.getAttributes(String name, String[] attrIds) Retrieves selected attributes associated with a named object.
DirContext | BasicAttribute.getAttributeSyntaxDefinition() Retrieves the syntax definition associated with this attribute.
DirContext | Attribute.getAttributeSyntaxDefinition() Retrieves the syntax definition associated with the attribute.
DirContext | InitialDirContext.getSchema(Name name)
DirContext | DirContext.getSchema(Name name) Retrieves the schema associated with the named object.
DirContext | InitialDirContext.getSchema(String name)
DirContext | DirContext.getSchema(String name) Retrieves the schema associated with the named object.
DirContext | InitialDirContext.getSchemaClassDefinition(Name name)
DirContext | DirContext.getSchemaClassDefinition(Name name) Retrieves a context containing the schema objects of the named object's class definitions.
DirContext | InitialDirContext.getSchemaClassDefinition(String name)
DirContext | DirContext.getSchemaClassDefinition(String name) Retrieves a context containing the schema objects of the named object's class definitions.
void | InitialDirContext.modifyAttributes(Name name, int mod_op, Attributes attrs)
void | DirContext.modifyAttributes(Name name, int mod_op, Attributes attrs) Modifies the attributes associated with a named object.
void | InitialDirContext.modifyAttributes(Name name, ModificationItem[] mods)
void | DirContext.modifyAttributes(Name name, ModificationItem[] mods) Modifies the attributes associated with a named object using an ordered list of modifications.
void | InitialDirContext.modifyAttributes(String name, int mod_op, Attributes attrs)
void | DirContext.modifyAttributes(String name, int mod_op, Attributes attrs) Modifies the attributes associated with a named object.
void | InitialDirContext.modifyAttributes(String name, ModificationItem[] mods)
void | DirContext.modifyAttributes(String name, ModificationItem[] mods) Modifies the attributes associated with a named object using an ordered list of modifications.
void | InitialDirContext.rebind(Name name, Object obj, Attributes attrs)
void | DirContext.rebind(Name name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes, overwriting any existing binding.
void | InitialDirContext.rebind(String name, Object obj, Attributes attrs)
void | DirContext.rebind(String name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes, overwriting any existing binding.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, Attributes matchingAttributes)
NamingEnumeration<SearchResult> | DirContext.search(Name name, Attributes matchingAttributes) Searches in a single context for objects that contain a specified set of attributes.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, Attributes matchingAttributes, String[] attributesToReturn)
NamingEnumeration<SearchResult> | DirContext.search(Name name, Attributes matchingAttributes, String[] attributesToReturn) Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, String filter, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(Name name, String filter, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | InitialDirContext.search(String name, Attributes matchingAttributes)
NamingEnumeration<SearchResult> | DirContext.search(String name, Attributes matchingAttributes) Searches in a single context for objects that contain a specified set of attributes.
NamingEnumeration<SearchResult> | InitialDirContext.search(String name, Attributes matchingAttributes, String[] attributesToReturn)
NamingEnumeration<SearchResult> | DirContext.search(String name, Attributes matchingAttributes, String[] attributesToReturn) Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes.
NamingEnumeration<SearchResult> | InitialDirContext.search(String name, String filterExpr, Object[] filterArgs, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(String name, String filterExpr, Object[] filterArgs, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | InitialDirContext.search(String name, String filter, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(String name, String filter, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.

Constructors in javax.naming.directory that throw NamingException
InitialDirContext()
Constructs an initial DirContext.
InitialDirContext(boolean lazy)
Constructs an initial DirContext with the option of not initializing it.
InitialDirContext(Hashtable<?,?> environment)
Constructs an initial DirContext using the supplied environment.

Uses of NamingException in javax.naming.event

Methods in javax.naming.event that return NamingException
 NamingException NamingExceptionEvent.getException()
Retrieves the exception that was thrown.

Methods in javax.naming.event that throw NamingException
void | EventContext.addNamingListener(Name target, int scope, NamingListener l) Adds a listener for receiving naming events fired when the object(s) identified by a target and scope changes.
void | EventDirContext.addNamingListener(Name target, String filter, Object[] filterArgs, SearchControls ctls, NamingListener l) Adds a listener for receiving naming events fired when objects identified by the search filter filter and filter arguments at the object named by the target are modified.
void | EventDirContext.addNamingListener(Name target, String filter, SearchControls ctls, NamingListener l) Adds a listener for receiving naming events fired when objects identified by the search filter filter at the object named by target are modified.
void | EventContext.addNamingListener(String target, int scope, NamingListener l) Adds a listener for receiving naming events fired when the object named by the string target name and scope changes.
void | EventDirContext.addNamingListener(String target, String filter, Object[] filterArgs, SearchControls ctls, NamingListener l) Adds a listener for receiving naming events fired when objects identified by the search filter filter and filter arguments at the object named by the string target name are modified.
void | EventDirContext.addNamingListener(String target, String filter, SearchControls ctls, NamingListener l) Adds a listener for receiving naming events fired when objects identified by the search filter filter at the object named by the string target name are modified.
void | EventContext.removeNamingListener(NamingListener l) Removes a listener from receiving naming events fired by this EventContext.
boolean | EventContext.targetMustExist() Determines whether a listener can register interest in a target that does not exist.

Constructors in javax.naming.event with parameters of type NamingException
NamingExceptionEvent(EventContext source, NamingException exc)
Constructs an instance of NamingExceptionEvent using the context in which the NamingException was thrown and the exception that was thrown.

Uses of NamingException in javax.naming.ldap

Subclasses of NamingException in javax.naming.ldap
 class LdapReferralException
This abstract class is used to represent an LDAP referral exception.

Methods in javax.naming.ldap that return NamingException
NamingException | UnsolicitedNotification.getException() Retrieves the exception as constructed using information sent by the server.
NamingException | SortResponseControl.getException() Retrieves the NamingException appropriate for the result code.

Methods in javax.naming.ldap that throw NamingException
ExtendedResponse | StartTlsRequest.createExtendedResponse(String id, byte[] berValue, int offset, int length) Creates an extended response object that corresponds to the LDAP StartTLS extended request.
ExtendedResponse | ExtendedRequest.createExtendedResponse(String id, byte[] berValue, int offset, int length) Creates the response object that corresponds to this request.
ExtendedResponse | InitialLdapContext.extendedOperation(ExtendedRequest request)
ExtendedResponse | LdapContext.extendedOperation(ExtendedRequest request) Performs an extended operation.
Control[] | InitialLdapContext.getConnectControls()
Control[] | LdapContext.getConnectControls() Retrieves the connection request controls in effect for this context.
abstract Control | ControlFactory.getControlInstance(Control ctl) Creates a control using this control factory.
static Control | ControlFactory.getControlInstance(Control ctl, Context ctx, Hashtable<?,?> env) Creates a control using known control factories.
Control[] | HasControls.getControls() Retrieves an array of Controls from the object that implements this interface.
abstract Context | LdapReferralException.getReferralContext() Retrieves the context at which to continue the method using the context's environment and no controls.
abstract Context | LdapReferralException.getReferralContext(Hashtable<?,?> env) Retrieves the context at which to continue the method using environment properties and no controls.
abstract Context | LdapReferralException.getReferralContext(Hashtable<?,?> env, Control[] reqCtls) Retrieves the context at which to continue the method using request controls and environment properties.
Control[] | InitialLdapContext.getRequestControls()
Control[] | LdapContext.getRequestControls() Retrieves the request controls in effect for this context.
Control[] | InitialLdapContext.getResponseControls()
Control[] | LdapContext.getResponseControls() Retrieves the response controls produced as a result of the last method invoked on this context.
LdapContext | InitialLdapContext.newInstance(Control[] reqCtls)
LdapContext | LdapContext.newInstance(Control[] requestControls) Creates a new instance of this context initialized using request controls.
void | InitialLdapContext.reconnect(Control[] connCtls)
void | LdapContext.reconnect(Control[] connCtls) Reconnects to the LDAP server using the supplied controls and this context's environment.
void | InitialLdapContext.setRequestControls(Control[] requestControls)
void | LdapContext.setRequestControls(Control[] requestControls) Sets the request controls for methods subsequently invoked on this context.

Constructors in javax.naming.ldap that throw NamingException
InitialLdapContext()
Constructs an initial context using no environment properties or connection request controls.
InitialLdapContext(Hashtable<?,?> environment, Control[] connCtls)
Constructs an initial context using environment properties and connection request controls.

Uses of NamingException in javax.naming.spi

Methods in javax.naming.spi that throw NamingException
InitialContextFactory | InitialContextFactoryBuilder.createInitialContextFactory(Hashtable<?,?> environment) Creates an initial context factory using the specified environment.
ObjectFactory | ObjectFactoryBuilder.createObjectFactory(Object obj, Hashtable<?,?> environment) Creates a new object factory using the environment supplied.
static Context | NamingManager.getContinuationContext(CannotProceedException cpe) Creates a context in which to continue a context operation.
static DirContext | DirectoryManager.getContinuationDirContext(CannotProceedException cpe) Creates a context in which to continue a DirContext operation.
Context | InitialContextFactory.getInitialContext(Hashtable<?,?> environment) Creates an Initial Context for beginning name resolution.
static Context | NamingManager.getInitialContext(Hashtable<?,?> env) Creates an initial context using the specified environment properties.
Object | StateFactory.getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment) Retrieves the state of an object for binding.
static Object | NamingManager.getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment) Retrieves the state of an object for binding.
static DirStateFactory.Result | DirectoryManager.getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes attrs) Retrieves the state of an object for binding when given the original object and its attributes.
DirStateFactory.Result | DirStateFactory.getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes inAttrs) Retrieves the state of an object for binding given the object and attributes to be transformed.
static Context | NamingManager.getURLContext(String scheme, Hashtable<?,?> environment) Creates a context for the given URL scheme id.
ResolveResult | Resolver.resolveToClass(Name name, Class<? extends Context> contextType) Partially resolves a name.
ResolveResult | Resolver.resolveToClass(String name, Class<? extends Context> contextType) Partially resolves a name.
static void | NamingManager.setInitialContextFactoryBuilder(InitialContextFactoryBuilder builder) Sets the InitialContextFactory builder to be builder.
static void | NamingManager.setObjectFactoryBuilder(ObjectFactoryBuilder builder) The ObjectFactoryBuilder determines the policy used when trying to load object factories.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.NamingSecurityException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.NamingSecurityException

Packages that use NamingSecurityException
javax.naming Provides the classes and interfaces for accessing naming services.

Uses of NamingSecurityException in javax.naming

Subclasses of NamingSecurityException in javax.naming
class | AuthenticationException This exception is thrown when an authentication error occurs while accessing the naming or directory service.
class | AuthenticationNotSupportedException This exception is thrown when the particular flavor of authentication requested is not supported.
class | NoPermissionException This exception is thrown when attempting to perform an operation for which the client has no permission.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.NoInitialContextException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.NoInitialContextException

No usage of javax.naming.NoInitialContextException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.NoPermissionException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.NoPermissionException

No usage of javax.naming.NoPermissionException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.NotContextException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.NotContextException

No usage of javax.naming.NotContextException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.OperationNotSupportedException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.OperationNotSupportedException

No usage of javax.naming.OperationNotSupportedException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.PartialResultException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.PartialResultException

No usage of javax.naming.PartialResultException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.RefAddr

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.RefAddr

Packages that use RefAddr
javax.naming Provides the classes and interfaces for accessing naming services.

Uses of RefAddr in javax.naming

Subclasses of RefAddr in javax.naming
class | BinaryRefAddr This class represents the binary form of the address of a communications end-point.
class | StringRefAddr This class represents the string form of the address of a communications end-point.

Fields in javax.naming with type parameters of type RefAddr
protected  Vector<RefAddr> Reference.addrs
Contains the addresses contained in this Reference.

Methods in javax.naming that return RefAddr
RefAddr | Reference.get(int posn) Retrieves the address at index posn.
RefAddr | Reference.get(String addrType) Retrieves the first address that has the address type 'addrType'.

Methods in javax.naming that return types with arguments of type RefAddr
 Enumeration<RefAddr> Reference.getAll()
Retrieves an enumeration of the addresses in this reference.

Methods in javax.naming with parameters of type RefAddr
void | Reference.add(int posn, RefAddr addr) Adds an address to the list of addresses at index posn.
void | Reference.add(RefAddr addr) Adds an address to the end of the list of addresses.

Constructors in javax.naming with parameters of type RefAddr
Reference(String className, RefAddr addr)
Constructs a new reference for an object with class name 'className' and an address.
Reference(String className, RefAddr addr, String factory, String factoryLocation)
Constructs a new reference for an object with class name 'className', the class name and location of the object's factory, and the address for the object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.Reference

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.Reference

Packages that use Reference
javax.naming Provides the classes and interfaces for accessing naming services.

Uses of Reference in javax.naming

Subclasses of Reference in javax.naming
 class LinkRef
This class represents a Reference whose contents is a name, called the link name, that is bound to an atomic name in a context.

Methods in javax.naming that return Reference
 Reference Referenceable.getReference()
Retrieves the Reference of this object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ReferralException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ReferralException

Packages that use ReferralException
javax.naming.ldap Provides support for LDAPv3 extended operations and controls.

Uses of ReferralException in javax.naming.ldap

Subclasses of ReferralException in javax.naming.ldap
 class LdapReferralException
This abstract class is used to represent an LDAP referral exception.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ServiceUnavailableException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ServiceUnavailableException

No usage of javax.naming.ServiceUnavailableException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.SizeLimitExceededException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.SizeLimitExceededException

No usage of javax.naming.SizeLimitExceededException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.StringRefAddr

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.StringRefAddr

No usage of javax.naming.StringRefAddr

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.TimeLimitExceededException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.TimeLimitExceededException

No usage of javax.naming.TimeLimitExceededException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.Context

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.Context

Packages that use Context
javax.naming | Provides the classes and interfaces for accessing naming services.
javax.naming.directory | Extends the javax.naming package to provide functionality for accessing directory services.
javax.naming.event | Provides support for event notification when accessing naming and directory services.
javax.naming.ldap | Provides support for LDAPv3 extended operations and controls.
javax.naming.spi | Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.
javax.sql.rowset.spi | The standard classes and interfaces that a third party vendor has to use in its implementation of a synchronization provider.

Uses of Context in javax.naming

Classes in javax.naming that implement Context
 class InitialContext
This class is the starting context for performing naming operations.

Fields in javax.naming declared as Context
protected Context | CannotProceedException.altNameCtx Contains the context relative to which altName is specified.
protected Context | InitialContext.defaultInitCtx Field holding the result of calling NamingManager.getInitialContext().

Methods in javax.naming that return Context
 Context Context.createSubcontext(Name name)
Creates and binds a new context.
 Context InitialContext.createSubcontext(Name name)
 Context Context.createSubcontext(String name)
Creates and binds a new context.
 Context InitialContext.createSubcontext(String name)
 Context CannotProceedException.getAltNameCtx()
Retrieves the altNameCtx field of this exception.
protected  Context InitialContext.getDefaultInitCtx()
Retrieves the initial context by calling NamingManager.getInitialContext() and cache it in defaultInitCtx.
abstract  Context ReferralException.getReferralContext()
Retrieves the context at which to continue the method.
abstract  Context ReferralException.getReferralContext(Hashtable<?,?> env)
Retrieves the context at which to continue the method using environment properties.
protected  Context InitialContext.getURLOrDefaultInitCtx(Name name)
Retrieves a context for resolving name.
protected  Context InitialContext.getURLOrDefaultInitCtx(String name)
Retrieves a context for resolving the string name name.

Methods in javax.naming with parameters of type Context
 void CannotProceedException.setAltNameCtx(Context altNameCtx)
Sets the altNameCtx field of this exception.

Uses of Context in javax.naming.directory

Subinterfaces of Context in javax.naming.directory
 interface DirContext
The directory service interface, containing methods for examining and updating attributes associated with objects, and for searching the directory.

Classes in javax.naming.directory that implement Context
 class InitialDirContext
This class is the starting context for performing directory operations.

Uses of Context in javax.naming.event

Subinterfaces of Context in javax.naming.event
interface | EventContext Contains methods for registering/deregistering listeners to be notified of events fired when objects named in a context changes.
interface | EventDirContext Contains methods for registering listeners to be notified of events fired when objects named in a directory context changes.

Uses of Context in javax.naming.ldap

Subinterfaces of Context in javax.naming.ldap
 interface LdapContext
This interface represents a context in which you can perform operations with LDAPv3-style controls and perform LDAPv3-style extended operations.

Classes in javax.naming.ldap that implement Context
 class InitialLdapContext
This class is the starting context for performing LDAPv3-style extended operations and controls.

Methods in javax.naming.ldap that return Context
abstract Context | LdapReferralException.getReferralContext() Retrieves the context at which to continue the method using the context's environment and no controls.
abstract Context | LdapReferralException.getReferralContext(Hashtable<?,?> env) Retrieves the context at which to continue the method using environment properties and no controls.
abstract Context | LdapReferralException.getReferralContext(Hashtable<?,?> env, Control[] reqCtls) Retrieves the context at which to continue the method using request controls and environment properties.

Methods in javax.naming.ldap with parameters of type Context
static Control ControlFactory.getControlInstance(Control ctl, Context ctx, Hashtable<?,?> env)
Creates a control using known control factories.

Uses of Context in javax.naming.spi

Methods in javax.naming.spi that return Context
static Context | NamingManager.getContinuationContext(CannotProceedException cpe) Creates a context in which to continue a context operation.
Context | InitialContextFactory.getInitialContext(Hashtable<?,?> environment) Creates an Initial Context for beginning name resolution.
static Context | NamingManager.getInitialContext(Hashtable<?,?> env) Creates an initial context using the specified environment properties.
static Context | NamingManager.getURLContext(String scheme, Hashtable<?,?> environment) Creates a context for the given URL scheme id.

Methods in javax.naming.spi with parameters of type Context
Object | ObjectFactory.getObjectInstance(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment) Creates an object using the location or reference information specified.
static Object | NamingManager.getObjectInstance(Object refInfo, Name name, Context nameCtx, Hashtable<?,?> environment) Creates an instance of an object for the specified object and environment.
static Object | DirectoryManager.getObjectInstance(Object refInfo, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes attrs) Creates an instance of an object for the specified object, attributes, and environment.
Object | DirObjectFactory.getObjectInstance(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes attrs) Creates an object using the location or reference information, and attributes specified.
Object | StateFactory.getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment) Retrieves the state of an object for binding.
static Object | NamingManager.getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment) Retrieves the state of an object for binding.
static DirStateFactory.Result | DirectoryManager.getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes attrs) Retrieves the state of an object for binding when given the original object and its attributes.
DirStateFactory.Result | DirStateFactory.getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes inAttrs) Retrieves the state of an object for binding given the object and attributes to be transformed.

Method parameters in javax.naming.spi with type arguments of type Context
ResolveResult | Resolver.resolveToClass(Name name, Class<? extends Context> contextType) Partially resolves a name.
ResolveResult | Resolver.resolveToClass(String name, Class<? extends Context> contextType) Partially resolves a name.

Uses of Context in javax.sql.rowset.spi

Methods in javax.sql.rowset.spi with parameters of type Context
static void SyncFactory.setJNDIContext(Context ctx)
Sets the initial JNDI context from which SyncProvider implementations can be retrieved from a JNDI namespace

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.Name

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.Name

Packages that use Name
javax.naming | Provides the classes and interfaces for accessing naming services.
javax.naming.directory | Extends the javax.naming package to provide functionality for accessing directory services.
javax.naming.event | Provides support for event notification when accessing naming and directory services.
javax.naming.ldap | Provides support for LDAPv3 extended operations and controls.
javax.naming.spi | Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.

Uses of Name in javax.naming

Classes in javax.naming that implement Name
class | CompositeName This class represents a composite name -- a sequence of component names spanning multiple namespaces.
class | CompoundName This class represents a compound name -- a name from a hierarchical name space.

Fields in javax.naming declared as Name
protected Name | CannotProceedException.altName Contains the name of the resolved object, relative to the context altNameCtx.
protected Name | LinkException.linkRemainingName Contains the remaining link name that has not been resolved yet.
protected Name | LinkException.linkResolvedName Contains the part of the link that has been successfully resolved.
protected Name | NamingException.remainingName Contains the remaining name that has not been resolved yet.
protected Name | CannotProceedException.remainingNewName Contains the remaining unresolved part of the second "name" argument to Context.rename().
protected Name | NamingException.resolvedName Contains the part of the name that has been successfully resolved.

Methods in javax.naming that return Name
 Name CompoundName.add(int posn, String comp)
Adds a single component at a specified position within this compound name.
 Name CompositeName.add(int posn, String comp)
Adds a single component at a specified position within this composite name.
 Name Name.add(int posn, String comp)
Adds a single component at a specified position within this name.
 Name CompoundName.add(String comp)
Adds a single component to the end of this compound name.
 Name CompositeName.add(String comp)
Adds a single component to the end of this composite name.
 Name Name.add(String comp)
Adds a single component to the end of this name.
 Name CompoundName.addAll(int posn, Name n)
Adds the components of a compound name -- in order -- at a specified position within this compound name.
 Name CompositeName.addAll(int posn, Name n)
Adds the components of a composite name -- in order -- at a specified position within this composite name.
 Name Name.addAll(int posn, Name n)
Adds the components of a name -- in order -- at a specified position within this name.
 Name CompoundName.addAll(Name suffix)
Adds the components of a compound name -- in order -- to the end of this compound name.
 Name CompositeName.addAll(Name suffix)
Adds the components of a composite name -- in order -- to the end of this composite name.
 Name Name.addAll(Name suffix)
Adds the components of a name -- in order -- to the end of this name.
 Name Context.composeName(Name name, Name prefix)
Composes the name of this context with a name relative to this context.
 Name InitialContext.composeName(Name name, Name prefix)
Composes the name of this context with a name relative to this context.
 Name CannotProceedException.getAltName()
Retrieves the altName field of this exception.
 Name LinkException.getLinkRemainingName()
Retrieves the remaining unresolved portion of the link name.
 Name LinkException.getLinkResolvedName()
Retrieves the leading portion of the link name that was resolved successfully.
 Name CompoundName.getPrefix(int posn)
Creates a compound name whose components consist of a prefix of the components in this compound name.
 Name CompositeName.getPrefix(int posn)
Creates a composite name whose components consist of a prefix of the components in this composite name.
 Name Name.getPrefix(int posn)
Creates a name whose components consist of a prefix of the components of this name.
 Name NamingException.getRemainingName()
Retrieves the remaining unresolved portion of the name.
 Name CannotProceedException.getRemainingNewName()
Retrieves the "remaining new name" field of this exception, which is used when this exception is thrown during a rename() operation.
 Name NamingException.getResolvedName()
Retrieves the leading portion of the name that was resolved successfully.
 Name CompoundName.getSuffix(int posn)
Creates a compound name whose components consist of a suffix of the components in this compound name.
 Name CompositeName.getSuffix(int posn)
Creates a composite name whose components consist of a suffix of the components in this composite name.
 Name Name.getSuffix(int posn)
Creates a name whose components consist of a suffix of the components in this name.
 Name NameParser.parse(String name)
Parses a name into its components.

Methods in javax.naming with parameters of type Name
 Name CompoundName.addAll(int posn, Name n)
Adds the components of a compound name -- in order -- at a specified position within this compound name.
 Name CompositeName.addAll(int posn, Name n)
Adds the components of a composite name -- in order -- at a specified position within this composite name.
 Name Name.addAll(int posn, Name n)
Adds the components of a name -- in order -- at a specified position within this name.
 Name CompoundName.addAll(Name suffix)
Adds the components of a compound name -- in order -- to the end of this compound name.
 Name CompositeName.addAll(Name suffix)
Adds the components of a composite name -- in order -- to the end of this composite name.
 Name Name.addAll(Name suffix)
Adds the components of a name -- in order -- to the end of this name.
 void NamingException.appendRemainingName(Name name)
Add components from 'name' as the last components in remaining name.
 void Context.bind(Name name, Object obj)
Binds a name to an object.
 void InitialContext.bind(Name name, Object obj)
 Name Context.composeName(Name name, Name prefix)
Composes the name of this context with a name relative to this context.
 Name InitialContext.composeName(Name name, Name prefix)
Composes the name of this context with a name relative to this context.
 Context Context.createSubcontext(Name name)
Creates and binds a new context.
 Context InitialContext.createSubcontext(Name name)
 void Context.destroySubcontext(Name name)
Destroys the named context and removes it from the namespace.
 void InitialContext.destroySubcontext(Name name)
static
<T> T
InitialContext.doLookup(Name name)
A static method to retrieve the named object.
 boolean CompoundName.endsWith(Name n)
Determines whether a compound name is a suffix of this compound name.
 boolean CompositeName.endsWith(Name n)
Determines whether a composite name is a suffix of this composite name.
 boolean Name.endsWith(Name n)
Determines whether this name ends with a specified suffix.
 NameParser Context.getNameParser(Name name)
Retrieves the parser associated with the named context.
 NameParser InitialContext.getNameParser(Name name)
protected  Context InitialContext.getURLOrDefaultInitCtx(Name name)
Retrieves a context for resolving name.
 NamingEnumeration<NameClassPair> Context.list(Name name)
Enumerates the names bound in the named context, along with the class names of objects bound to them.
 NamingEnumeration<NameClassPair> InitialContext.list(Name name)
 NamingEnumeration<Binding> Context.listBindings(Name name)
Enumerates the names bound in the named context, along with the objects bound to them.
 NamingEnumeration<Binding> InitialContext.listBindings(Name name)
 Object Context.lookup(Name name)
Retrieves the named object.
 Object InitialContext.lookup(Name name)
 Object Context.lookupLink(Name name)
Retrieves the named object, following links except for the terminal atomic component of the name.
 Object InitialContext.lookupLink(Name name)
 void Context.rebind(Name name, Object obj)
Binds a name to an object, overwriting any existing binding.
 void InitialContext.rebind(Name name, Object obj)
 void Context.rename(Name oldName, Name newName)
Binds a new name to the object bound to an old name, and unbinds the old name.
 void InitialContext.rename(Name oldName, Name newName)
 void CannotProceedException.setAltName(Name altName)
Sets the altName field of this exception.
 void LinkException.setLinkRemainingName(Name name)
Sets the remaining link name field of this exception.
 void LinkException.setLinkResolvedName(Name name)
Sets the resolved link name field of this exception.
 void NamingException.setRemainingName(Name name)
Sets the remaining name field of this exception.
 void CannotProceedException.setRemainingNewName(Name newName)
Sets the "remaining new name" field of this exception.
 void NamingException.setResolvedName(Name name)
Sets the resolved name field of this exception.
 boolean CompoundName.startsWith(Name n)
Determines whether a compound name is a prefix of this compound name.
 boolean CompositeName.startsWith(Name n)
Determines whether a composite name is a prefix of this composite name.
 boolean Name.startsWith(Name n)
Determines whether this name starts with a specified prefix.
 void Context.unbind(Name name)
Unbinds the named object.
 void InitialContext.unbind(Name name)

Constructors in javax.naming with parameters of type Name
LinkRef(Name linkName)
Constructs a LinkRef for a name.

Uses of Name in javax.naming.directory

Methods in javax.naming.directory with parameters of type Name
void | InitialDirContext.bind(Name name, Object obj, Attributes attrs)
void | DirContext.bind(Name name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes.
DirContext | InitialDirContext.createSubcontext(Name name, Attributes attrs)
DirContext | DirContext.createSubcontext(Name name, Attributes attrs) Creates and binds a new context, along with associated attributes.
Attributes | InitialDirContext.getAttributes(Name name)
Attributes | DirContext.getAttributes(Name name) Retrieves all of the attributes associated with a named object.
Attributes | InitialDirContext.getAttributes(Name name, String[] attrIds)
Attributes | DirContext.getAttributes(Name name, String[] attrIds) Retrieves selected attributes associated with a named object.
DirContext | InitialDirContext.getSchema(Name name)
DirContext | DirContext.getSchema(Name name) Retrieves the schema associated with the named object.
DirContext | InitialDirContext.getSchemaClassDefinition(Name name)
DirContext | DirContext.getSchemaClassDefinition(Name name) Retrieves a context containing the schema objects of the named object's class definitions.
void | InitialDirContext.modifyAttributes(Name name, int mod_op, Attributes attrs)
void | DirContext.modifyAttributes(Name name, int mod_op, Attributes attrs) Modifies the attributes associated with a named object.
void | InitialDirContext.modifyAttributes(Name name, ModificationItem[] mods)
void | DirContext.modifyAttributes(Name name, ModificationItem[] mods) Modifies the attributes associated with a named object using an ordered list of modifications.
void | InitialDirContext.rebind(Name name, Object obj, Attributes attrs)
void | DirContext.rebind(Name name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes, overwriting any existing binding.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, Attributes matchingAttributes)
NamingEnumeration<SearchResult> | DirContext.search(Name name, Attributes matchingAttributes) Searches in a single context for objects that contain a specified set of attributes.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, Attributes matchingAttributes, String[] attributesToReturn)
NamingEnumeration<SearchResult> | DirContext.search(Name name, Attributes matchingAttributes, String[] attributesToReturn) Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, String filter, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(Name name, String filter, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.

Uses of Name in javax.naming.event

Methods in javax.naming.event with parameters of type Name
void | EventContext.addNamingListener(Name target, int scope, NamingListener l) Adds a listener for receiving naming events fired when the object(s) identified by a target and scope changes.
void | EventDirContext.addNamingListener(Name target, String filter, Object[] filterArgs, SearchControls ctls, NamingListener l) Adds a listener for receiving naming events fired when objects identified by the search filter filter and filter arguments at the object named by the target are modified.
void | EventDirContext.addNamingListener(Name target, String filter, SearchControls ctls, NamingListener l) Adds a listener for receiving naming events fired when objects identified by the search filter filter at the object named by target are modified.

Uses of Name in javax.naming.ldap

Classes in javax.naming.ldap that implement Name
 class LdapName
This class represents a distinguished name as specified by RFC 2253.

Methods in javax.naming.ldap that return Name
Name | LdapName.add(int posn, Rdn comp) Adds a single RDN at a specified position within this LDAP name.
Name | LdapName.add(int posn, String comp) Adds a single component at a specified position within this LDAP name.
Name | LdapName.add(Rdn comp) Adds a single RDN to the end of this LDAP name.
Name | LdapName.add(String comp) Adds a single component to the end of this LDAP name.
Name | LdapName.addAll(int posn, List<Rdn> suffixRdns) Adds the RDNs of a name -- in order -- at a specified position within this name.
Name | LdapName.addAll(int posn, Name suffix) Adds the components of a name -- in order -- at a specified position within this name.
Name | LdapName.addAll(List<Rdn> suffixRdns) Adds the RDNs of a name -- in order -- to the end of this name.
Name | LdapName.addAll(Name suffix) Adds the components of a name -- in order -- to the end of this name.
Name | LdapName.getPrefix(int posn) Creates a name whose components consist of a prefix of the components of this LDAP name.
Name | LdapName.getSuffix(int posn) Creates a name whose components consist of a suffix of the components in this LDAP name.

Methods in javax.naming.ldap with parameters of type Name
Name | LdapName.addAll(int posn, Name suffix) Adds the components of a name -- in order -- at a specified position within this name.
Name | LdapName.addAll(Name suffix) Adds the components of a name -- in order -- to the end of this name.
boolean | LdapName.endsWith(Name n) Determines whether this LDAP name ends with a specified LDAP name suffix.
boolean | LdapName.startsWith(Name n) Determines whether this LDAP name starts with a specified LDAP name prefix.

Uses of Name in javax.naming.spi

Fields in javax.naming.spi declared as Name
protected  Name ResolveResult.remainingName
Field containing the remaining name yet to be resolved.

Methods in javax.naming.spi that return Name
 Name ResolveResult.getRemainingName()
Retrieves the remaining unresolved portion of the name.

Methods in javax.naming.spi with parameters of type Name
void | ResolveResult.appendRemainingName(Name name) Adds components to the end of remaining name.
Object | ObjectFactory.getObjectInstance(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment) Creates an object using the location or reference information specified.
static Object | NamingManager.getObjectInstance(Object refInfo, Name name, Context nameCtx, Hashtable<?,?> environment) Creates an instance of an object for the specified object and environment.
static Object | DirectoryManager.getObjectInstance(Object refInfo, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes attrs) Creates an instance of an object for the specified object, attributes, and environment.
Object | DirObjectFactory.getObjectInstance(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes attrs) Creates an object using the location or reference information, and attributes specified.
Object | StateFactory.getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment) Retrieves the state of an object for binding.
static Object | NamingManager.getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment) Retrieves the state of an object for binding.
static DirStateFactory.Result | DirectoryManager.getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes attrs) Retrieves the state of an object for binding when given the original object and its attributes.
DirStateFactory.Result | DirStateFactory.getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes inAttrs) Retrieves the state of an object for binding given the object and attributes to be transformed.
ResolveResult | Resolver.resolveToClass(Name name, Class<? extends Context> contextType) Partially resolves a name.
void | ResolveResult.setRemainingName(Name name) Sets the remaining name field of this result to name.

Constructors in javax.naming.spi with parameters of type Name
ResolveResult(Object robj, Name rname)
Constructs a new instance of ResolveResult consisting of the resolved Object and the remaining name.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.NameParser

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.NameParser

Packages that use NameParser
javax.naming Provides the classes and interfaces for accessing naming services.

Uses of NameParser in javax.naming

Methods in javax.naming that return NameParser
NameParser | Context.getNameParser(Name name) Retrieves the parser associated with the named context.
NameParser | InitialContext.getNameParser(Name name)
NameParser | Context.getNameParser(String name) Retrieves the parser associated with the named context.
NameParser | InitialContext.getNameParser(String name)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.NamingEnumeration

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.NamingEnumeration

Packages that use NamingEnumeration
javax.naming | Provides the classes and interfaces for accessing naming services.
javax.naming.directory | Extends the javax.naming package to provide functionality for accessing directory services.

Uses of NamingEnumeration in javax.naming

Methods in javax.naming that return NamingEnumeration
NamingEnumeration<NameClassPair> | Context.list(Name name) Enumerates the names bound in the named context, along with the class names of objects bound to them.
NamingEnumeration<NameClassPair> | InitialContext.list(Name name)
NamingEnumeration<NameClassPair> | Context.list(String name) Enumerates the names bound in the named context, along with the class names of objects bound to them.
NamingEnumeration<NameClassPair> | InitialContext.list(String name)
NamingEnumeration<Binding> | Context.listBindings(Name name) Enumerates the names bound in the named context, along with the objects bound to them.
NamingEnumeration<Binding> | InitialContext.listBindings(Name name)
NamingEnumeration<Binding> | Context.listBindings(String name) Enumerates the names bound in the named context, along with the objects bound to them.
NamingEnumeration<Binding> | InitialContext.listBindings(String name)

Uses of NamingEnumeration in javax.naming.directory

Methods in javax.naming.directory that return NamingEnumeration
NamingEnumeration<Attribute> | BasicAttributes.getAll()
NamingEnumeration<?> | BasicAttribute.getAll() Retrieves an enumeration of this attribute's values.
NamingEnumeration<?> | Attribute.getAll() Retrieves an enumeration of the attribute's values.
NamingEnumeration<? extends Attribute> | Attributes.getAll() Retrieves an enumeration of the attributes in the attribute set.
NamingEnumeration<String> | BasicAttributes.getIDs()
NamingEnumeration<String> | Attributes.getIDs() Retrieves an enumeration of the ids of the attributes in the attribute set.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, Attributes matchingAttributes)
NamingEnumeration<SearchResult> | DirContext.search(Name name, Attributes matchingAttributes) Searches in a single context for objects that contain a specified set of attributes.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, Attributes matchingAttributes, String[] attributesToReturn)
NamingEnumeration<SearchResult> | DirContext.search(Name name, Attributes matchingAttributes, String[] attributesToReturn) Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, String filter, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(Name name, String filter, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | InitialDirContext.search(String name, Attributes matchingAttributes)
NamingEnumeration<SearchResult> | DirContext.search(String name, Attributes matchingAttributes) Searches in a single context for objects that contain a specified set of attributes.
NamingEnumeration<SearchResult> | InitialDirContext.search(String name, Attributes matchingAttributes, String[] attributesToReturn)
NamingEnumeration<SearchResult> | DirContext.search(String name, Attributes matchingAttributes, String[] attributesToReturn) Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes.
NamingEnumeration<SearchResult> | InitialDirContext.search(String name, String filterExpr, Object[] filterArgs, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(String name, String filterExpr, Object[] filterArgs, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | InitialDirContext.search(String name, String filter, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(String name, String filter, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.Referenceable

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.Referenceable

No usage of javax.naming.Referenceable

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


CommunicationException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class CommunicationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.CommunicationException
All Implemented Interfaces:
Serializable
public class CommunicationException
extends NamingException

This exception is thrown when the client is unable to communicate with the directory or naming service. The inability to communicate with the service might be a result of many factors, such as network partitioning, hardware or interface problems, failures on either the client or server side. This exception is meant to be used to capture such communication problems.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
CommunicationException()
Constructs a new instance of CommunicationException.
CommunicationException(String explanation)
Constructs a new instance of CommunicationException using the arguments supplied.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CommunicationException

public CommunicationException(String explanation)
Constructs a new instance of CommunicationException using the arguments supplied.

Parameters:
explanation - Additional detail about this exception.
See Also:
Throwable.getMessage()

CommunicationException

public CommunicationException()
Constructs a new instance of CommunicationException.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CompositeName

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class CompositeName

java.lang.Object
    extended by  javax.naming.CompositeName
All Implemented Interfaces:
Serializable, Cloneable, Comparable<Object>, Name
public class CompositeName
extends Object
implements Name

This class represents a composite name -- a sequence of component names spanning multiple namespaces. Each component is a string name from the namespace of a naming system. If the component comes from a hierarchical namespace, that component can be further parsed into its atomic parts by using the CompoundName class.

The components of a composite name are numbered. The indexes of a composite name with N components range from 0 up to, but not including, N. This range may be written as [0,N). The most significant component is at index 0. An empty composite name has no components.

JNDI Composite Name Syntax

JNDI defines a standard string representation for composite names. This representation is the concatenation of the components of a composite name from left to right using the component separator (a forward slash character (/)) to separate each component. The JNDI syntax defines the following meta characters:
  • escape (backward slash \),
  • quote characters (single (') and double quotes (")), and
  • component separator (forward slash character (/)).
Any occurrence of a leading quote, an escape preceding any meta character, an escape at the end of a component, or a component separator character in an unquoted component must be preceded by an escape character when that component is being composed into a composite name string. Alternatively, to avoid adding escape characters as described, the entire component can be quoted using matching single quotes or matching double quotes. A single quote occurring within a double-quoted component is not considered a meta character (and need not be escaped), and vice versa.

When two composite names are compared, the case of the characters is significant.

A leading component separator (the composite name string begins with a separator) denotes a leading empty component (a component consisting of an empty string). A trailing component separator (the composite name string ends with a separator) denotes a trailing empty component. Adjacent component separators denote an empty component.

Composite Name Examples

This table shows examples of some composite names. Each row shows the string form of a composite name and its corresponding structural form (CompositeName).

String Name | CompositeName
"" | {} (the empty name == new CompositeName("") == new CompositeName())
"x" | {"x"}
"x/y" | {"x", "y"}
"x/" | {"x", ""}
"/x" | {"", "x"}
"/" | {""}
"//" | {"", ""}
"/x/" | {"", "x", ""}
"x//y" | {"x", "", "y"}

Composition Examples

Here are some composition examples. The right column shows composing string composite names while the left column shows composing the corresponding CompositeNames. Notice that composing the string forms of two composite names simply involves concatenating their string forms together.

String Names | CompositeNames
"x/y" + "/" = x/y/ | {"x", "y"} + {""} = {"x", "y", ""}
"" + "x" = "x" | {} + {"x"} = {"x"}
"/" + "x" = "/x" | {""} + {"x"} = {"", "x"}
"x" + "" + "" = "x" | {"x"} + {} + {} = {"x"}

Multithreaded Access

A CompositeName instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify a CompositeName should lock the object.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
 | CompositeName() Constructs a new empty composite name.
protected | CompositeName(Enumeration<String> comps) Constructs a new composite name instance using the components specified by 'comps'.
 | CompositeName(String n) Constructs a new composite name instance by parsing the string n using the composite name syntax (left-to-right, slash separated).
Method Summary
Name | add(int posn, String comp) Adds a single component at a specified position within this composite name.
Name | add(String comp) Adds a single component to the end of this composite name.
Name | addAll(int posn, Name n) Adds the components of a composite name -- in order -- at a specified position within this composite name.
Name | addAll(Name suffix) Adds the components of a composite name -- in order -- to the end of this composite name.
Object | clone() Generates a copy of this composite name.
int | compareTo(Object obj) Compares this CompositeName with the specified Object for order.
boolean | endsWith(Name n) Determines whether a composite name is a suffix of this composite name.
boolean | equals(Object obj) Determines whether two composite names are equal.
String | get(int posn) Retrieves a component of this composite name.
Enumeration<String> | getAll() Retrieves the components of this composite name as an enumeration of strings.
Name | getPrefix(int posn) Creates a composite name whose components consist of a prefix of the components in this composite name.
Name | getSuffix(int posn) Creates a composite name whose components consist of a suffix of the components in this composite name.
int | hashCode() Computes the hash code of this composite name.
boolean | isEmpty() Determines whether this composite name is empty.
Object | remove(int posn) Deletes a component from this composite name.
int | size() Retrieves the number of components in this composite name.
boolean | startsWith(Name n) Determines whether a composite name is a prefix of this composite name.
String | toString() Generates the string representation of this composite name.
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

CompositeName

protected CompositeName(Enumeration<String> comps)
Constructs a new composite name instance using the components specified by 'comps'. This protected method is intended to be to be used by subclasses of CompositeName when they override methods such as clone(), getPrefix(), getSuffix().

Parameters:
comps - A non-null enumeration containing the components for the new composite name. Each element is of class String. The enumeration will be consumed to extract its elements.

CompositeName

public CompositeName(String n)
              throws InvalidNameException
Constructs a new composite name instance by parsing the string n using the composite name syntax (left-to-right, slash separated). The composite name syntax is described in detail in the class description.

Parameters:
n - The non-null string to parse.
Throws:
InvalidNameException - If n has invalid composite name syntax.

CompositeName

public CompositeName()
Constructs a new empty composite name. Such a name returns true when isEmpty() is invoked on it.

Method Detail

toString

public String toString()
Generates the string representation of this composite name. The string representation consists of enumerating in order each component of the composite name and separating each component by a forward slash character. Quoting and escape characters are applied where necessary according to the JNDI syntax, which is described in the class description. An empty component is represented by an empty string. The string representation thus generated can be passed to the CompositeName constructor to create a new equivalent composite name.

Overrides:
toString in class Object
Returns:
A non-null string representation of this composite name.

equals

public boolean equals(Object obj)
Determines whether two composite names are equal. If obj is null or not a composite name, false is returned. Two composite names are equal if each component in one is equal to the corresponding component in the other. This implies both have the same number of components, and each component's equals() test against the corresponding component in the other name returns true.

Overrides:
equals in class Object
Parameters:
obj - The possibly null object to compare against.
Returns:
true if obj is equal to this composite name, false otherwise.
See Also:
hashCode()

hashCode

public int hashCode()
Computes the hash code of this composite name. The hash code is the sum of the hash codes of individual components of this composite name.

Overrides:
hashCode in class Object
Returns:
An int representing the hash code of this name.
See Also:
equals(java.lang.Object)

compareTo

public int compareTo(Object obj)
Compares this CompositeName with the specified Object for order. Returns a negative integer, zero, or a positive integer as this Name is less than, equal to, or greater than the given Object.

If obj is null or not an instance of CompositeName, ClassCastException is thrown.

See equals() for what it means for two composite names to be equal. If two composite names are equal, 0 is returned.

Ordering of composite names follows the lexicographical rules for string comparison, with the extension that this applies to all the components in the composite name. The effect is as if all the components were lined up in their specified ordered and the lexicographical rules applied over the two line-ups. If this composite name is "lexicographically" lesser than obj, a negative number is returned. If this composite name is "lexicographically" greater than obj, a positive number is returned.

Specified by:
compareTo in interface Comparable<Object>
Specified by:
compareTo in interface Name
Parameters:
obj - The non-null object to compare against.
Returns:
a negative integer, zero, or a positive integer as this Name is less than, equal to, or greater than the given Object.
Throws:
ClassCastException - if obj is not a CompositeName.
See Also:
Comparable.compareTo(Object)

clone

public Object clone()
Generates a copy of this composite name. Changes to the components of this composite name won't affect the new copy and vice versa.

Specified by:
clone in interface Name
Overrides:
clone in class Object
Returns:
A non-null copy of this composite name.
See Also:
Cloneable

size

public int size()
Retrieves the number of components in this composite name.

Specified by:
size in interface Name
Returns:
The nonnegative number of components in this composite name.

isEmpty

public boolean isEmpty()
Determines whether this composite name is empty. A composite name is empty if it has zero components.

Specified by:
isEmpty in interface Name
Returns:
true if this composite name is empty, false otherwise.

getAll

public Enumeration<String> getAll()
Retrieves the components of this composite name as an enumeration of strings. The effects of updates to this composite name on this enumeration is undefined.

Specified by:
getAll in interface Name
Returns:
A non-null enumeration of the components of this composite name. Each element of the enumeration is of class String.

get

public String get(int posn)
Retrieves a component of this composite name.

Specified by:
get in interface Name
Parameters:
posn - The 0-based index of the component to retrieve. Must be in the range [0,size()).
Returns:
The non-null component at index posn.
Throws:
ArrayIndexOutOfBoundsException - if posn is outside the specified range.

getPrefix

public Name getPrefix(int posn)
Creates a composite name whose components consist of a prefix of the components in this composite name. Subsequent changes to this composite name does not affect the name that is returned.

Specified by:
getPrefix in interface Name
Parameters:
posn - The 0-based index of the component at which to stop. Must be in the range [0,size()].
Returns:
A composite name consisting of the components at indexes in the range [0,posn).
Throws:
ArrayIndexOutOfBoundsException - If posn is outside the specified range.

getSuffix

public Name getSuffix(int posn)
Creates a composite name whose components consist of a suffix of the components in this composite name. Subsequent changes to this composite name does not affect the name that is returned.

Specified by:
getSuffix in interface Name
Parameters:
posn - The 0-based index of the component at which to start. Must be in the range [0,size()].
Returns:
A composite name consisting of the components at indexes in the range [posn,size()). If posn is equal to size(), an empty composite name is returned.
Throws:
ArrayIndexOutOfBoundsException - If posn is outside the specified range.

startsWith

public boolean startsWith(Name n)
Determines whether a composite name is a prefix of this composite name. A composite name 'n' is a prefix if it is equal to getPrefix(n.size())--in other words, this composite name starts with 'n'. If 'n' is null or not a composite name, false is returned.

Specified by:
startsWith in interface Name
Parameters:
n - The possibly null name to check.
Returns:
true if n is a CompositeName and is a prefix of this composite name, false otherwise.

endsWith

public boolean endsWith(Name n)
Determines whether a composite name is a suffix of this composite name. A composite name 'n' is a suffix if it it is equal to getSuffix(size()-n.size())--in other words, this composite name ends with 'n'. If n is null or not a composite name, false is returned.

Specified by:
endsWith in interface Name
Parameters:
n - The possibly null name to check.
Returns:
true if n is a CompositeName and is a suffix of this composite name, false otherwise.

addAll

public Name addAll(Name suffix)
            throws InvalidNameException
Adds the components of a composite name -- in order -- to the end of this composite name.

Specified by:
addAll in interface Name
Parameters:
suffix - The non-null components to add.
Returns:
The updated CompositeName, not a new one. Cannot be null.
Throws:
InvalidNameException - If suffix is not a composite name.

addAll

public Name addAll(int posn,
                   Name n)
            throws InvalidNameException
Adds the components of a composite name -- in order -- at a specified position within this composite name. Components of this composite name at or after the index of the first new component are shifted up (away from index 0) to accommodate the new components.

Specified by:
addAll in interface Name
Parameters:
n - The non-null components to add.
posn - The index in this name at which to add the new components. Must be in the range [0,size()].
Returns:
The updated CompositeName, not a new one. Cannot be null.
Throws:
InvalidNameException - If n is not a composite name.
ArrayIndexOutOfBoundsException - If posn is outside the specified range.

add

public Name add(String comp)
         throws InvalidNameException
Adds a single component to the end of this composite name.

Specified by:
add in interface Name
Parameters:
comp - The non-null component to add.
Returns:
The updated CompositeName, not a new one. Cannot be null.
Throws:
InvalidNameException - If adding comp at end of the name would violate the name's syntax.

add

public Name add(int posn,
                String comp)
         throws InvalidNameException
Adds a single component at a specified position within this composite name. Components of this composite name at or after the index of the new component are shifted up by one (away from index 0) to accommodate the new component.

Specified by:
add in interface Name
Parameters:
comp - The non-null component to add.
posn - The index at which to add the new component. Must be in the range [0,size()].
Returns:
The updated CompositeName, not a new one. Cannot be null.
Throws:
ArrayIndexOutOfBoundsException - If posn is outside the specified range.
InvalidNameException - If adding comp at the specified position would violate the name's syntax.

remove

public Object remove(int posn)
              throws InvalidNameException
Deletes a component from this composite name. The component of this composite name at position 'posn' is removed, and components at indices greater than 'posn' are shifted down (towards index 0) by one.

Specified by:
remove in interface Name
Parameters:
posn - The index of the component to delete. Must be in the range [0,size()).
Returns:
The component removed (a String).
Throws:
ArrayIndexOutOfBoundsException - If posn is outside the specified range (includes case where composite name is empty).
InvalidNameException - If deleting the component would violate the name's syntax.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CompoundName

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class CompoundName

java.lang.Object
    extended by  javax.naming.CompoundName
All Implemented Interfaces:
Serializable, Cloneable, Comparable<Object>, Name
public class CompoundName
extends Object
implements Name

This class represents a compound name -- a name from a hierarchical name space. Each component in a compound name is an atomic name.

The components of a compound name are numbered. The indexes of a compound name with N components range from 0 up to, but not including, N. This range may be written as [0,N). The most significant component is at index 0. An empty compound name has no components.

Compound Name Syntax

The syntax of a compound name is specified using a set of properties:
jndi.syntax.direction
Direction for parsing ("right_to_left", "left_to_right", "flat"). If unspecified, defaults to "flat", which means the namespace is flat with no hierarchical structure.
jndi.syntax.separator
Separator between atomic name components. Required unless direction is "flat".
jndi.syntax.ignorecase
If present, "true" means ignore the case when comparing name components. If its value is not "true", or if the property is not present, case is considered when comparing name components.
jndi.syntax.escape
If present, specifies the escape string for overriding separator, escapes and quotes.
jndi.syntax.beginquote
If present, specifies the string delimiting start of a quoted string.
jndi.syntax.endquote
String delimiting end of quoted string. If present, specifies the string delimiting the end of a quoted string. If not present, use syntax.beginquote as end quote.
jndi.syntax.beginquote2
Alternative set of begin/end quotes.
jndi.syntax.endquote2
Alternative set of begin/end quotes.
jndi.syntax.trimblanks
If present, "true" means trim any leading and trailing whitespaces in a name component for comparison purposes. If its value is not "true", or if the property is not present, blanks are significant.
jndi.syntax.separator.ava
If present, specifies the string that separates attribute-value-assertions when specifying multiple attribute/value pairs. (e.g. "," in age=65,gender=male).
jndi.syntax.separator.typeval
If present, specifies the string that separators attribute from value (e.g. "=" in "age=65")
These properties are interpreted according to the following rules:
  1. In a string without quotes or escapes, any instance of the separator delimits two atomic names. Each atomic name is referred to as a component.
  2. A separator, quote or escape is escaped if preceded immediately (on the left) by the escape.
  3. If there are two sets of quotes, a specific begin-quote must be matched by its corresponding end-quote.
  4. A non-escaped begin-quote which precedes a component must be matched by a non-escaped end-quote at the end of the component. A component thus quoted is referred to as a quoted component. It is parsed by removing the being- and end- quotes, and by treating the intervening characters as ordinary characters unless one of the rules involving quoted components listed below applies.
  5. Quotes embedded in non-quoted components are treated as ordinary strings and need not be matched.
  6. A separator that is escaped or appears between non-escaped quotes is treated as an ordinary string and not a separator.
  7. An escape string within a quoted component acts as an escape only when followed by the corresponding end-quote string. This can be used to embed an escaped quote within a quoted component.
  8. An escaped escape string is not treated as an escape string.
  9. An escape string that does not precede a meta string (quotes or separator) and is not at the end of a component is treated as an ordinary string.
  10. A leading separator (the compound name string begins with a separator) denotes a leading empty atomic component (consisting of an empty string). A trailing separator (the compound name string ends with a separator) denotes a trailing empty atomic component. Adjacent separators denote an empty atomic component.

The string form of the compound name follows the syntax described above. When the components of the compound name are turned into their string representation, the reserved syntax rules described above are applied (e.g. embedded separators are escaped or quoted) so that when the same string is parsed, it will yield the same components of the original compound name.

Multithreaded Access

A CompoundName instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify a CompoundName should lock the object.

Since:
1.3
See Also:
Serialized Form

Field Summary
protected javax.naming.NameImpl | impl Implementation of this compound name.
protected Properties | mySyntax Syntax properties for this compound name.
Constructor Summary
protected | CompoundName(Enumeration<String> comps, Properties syntax) Constructs a new compound name instance using the components specified in comps and syntax.
 | CompoundName(String n, Properties syntax) Constructs a new compound name instance by parsing the string n using the syntax specified by the syntax properties supplied.
Method Summary
Name | add(int posn, String comp) Adds a single component at a specified position within this compound name.
Name | add(String comp) Adds a single component to the end of this compound name.
Name | addAll(int posn, Name n) Adds the components of a compound name -- in order -- at a specified position within this compound name.
Name | addAll(Name suffix) Adds the components of a compound name -- in order -- to the end of this compound name.
Object | clone() Creates a copy of this compound name.
int | compareTo(Object obj) Compares this CompoundName with the specified Object for order.
boolean | endsWith(Name n) Determines whether a compound name is a suffix of this compound name.
boolean | equals(Object obj) Determines whether obj is syntactically equal to this compound name.
String | get(int posn) Retrieves a component of this compound name.
Enumeration<String> | getAll() Retrieves the components of this compound name as an enumeration of strings.
Name | getPrefix(int posn) Creates a compound name whose components consist of a prefix of the components in this compound name.
Name | getSuffix(int posn) Creates a compound name whose components consist of a suffix of the components in this compound name.
int | hashCode() Computes the hash code of this compound name.
boolean | isEmpty() Determines whether this compound name is empty.
Object | remove(int posn) Deletes a component from this compound name.
int | size() Retrieves the number of components in this compound name.
boolean | startsWith(Name n) Determines whether a compound name is a prefix of this compound name.
String | toString() Generates the string representation of this compound name, using the syntax rules of the compound name.
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

impl

protected transient javax.naming.NameImpl impl
Implementation of this compound name. This field is initialized by the constructors and cannot be null. It should be treated as a read-only variable by subclasses.

mySyntax

protected transient Properties mySyntax
Syntax properties for this compound name. This field is initialized by the constructors and cannot be null. It should be treated as a read-only variable by subclasses. Any necessary changes to mySyntax should be made within constructors and not after the compound name has been instantiated.

Constructor Detail

CompoundName

protected CompoundName(Enumeration<String> comps,
                       Properties syntax)
Constructs a new compound name instance using the components specified in comps and syntax. This protected method is intended to be to be used by subclasses of CompoundName when they override methods such as clone(), getPrefix(), getSuffix().

Parameters:
comps - A non-null enumeration of the components to add. Each element of the enumeration is of class String. The enumeration will be consumed to extract its elements.
syntax - A non-null properties that specify the syntax of this compound name. See class description for contents of properties.

CompoundName

public CompoundName(String n,
                    Properties syntax)
             throws InvalidNameException
Constructs a new compound name instance by parsing the string n using the syntax specified by the syntax properties supplied.

Parameters:
n - The non-null string to parse.
syntax - A non-null list of properties that specify the syntax of this compound name. See class description for contents of properties.
Throws:
InvalidNameException - If 'n' violates the syntax specified by syntax.
Method Detail

toString

public String toString()
Generates the string representation of this compound name, using the syntax rules of the compound name. The syntax rules are described in the class description. An empty component is represented by an empty string. The string representation thus generated can be passed to the CompoundName constructor with the same syntax properties to create a new equivalent compound name.

Overrides:
toString in class Object
Returns:
A non-null string representation of this compound name.

equals

public boolean equals(Object obj)
Determines whether obj is syntactically equal to this compound name. If obj is null or not a CompoundName, false is returned. Two compound names are equal if each component in one is "equal" to the corresponding component in the other.

Equality is also defined in terms of the syntax of this compound name. The default implementation of CompoundName uses the syntax properties jndi.syntax.ignorecase and jndi.syntax.trimblanks when comparing two components for equality. If case is ignored, two strings with the same sequence of characters but with different cases are considered equal. If blanks are being trimmed, leading and trailing blanks are ignored for the purpose of the comparison.

Both compound names must have the same number of components.

Implementation note: Currently the syntax properties of the two compound names are not compared for equality. They might be in the future.

Overrides:
equals in class Object
Parameters:
obj - The possibly null object to compare against.
Returns:
true if obj is equal to this compound name, false otherwise.
See Also:
compareTo(java.lang.Object obj)

hashCode

public int hashCode()
Computes the hash code of this compound name. The hash code is the sum of the hash codes of the "canonicalized" forms of individual components of this compound name. Each component is "canonicalized" according to the compound name's syntax before its hash code is computed. For a case-insensitive name, for example, the uppercased form of a name has the same hash code as its lowercased equivalent.

Overrides:
hashCode in class Object
Returns:
An int representing the hash code of this name.
See Also:
Object.equals(java.lang.Object), Hashtable

clone

public Object clone()
Creates a copy of this compound name. Changes to the components of this compound name won't affect the new copy and vice versa. The clone and this compound name share the same syntax.

Specified by:
clone in interface Name
Overrides:
clone in class Object
Returns:
A non-null copy of this compound name.
See Also:
Cloneable

compareTo

public int compareTo(Object obj)
Compares this CompoundName with the specified Object for order. Returns a negative integer, zero, or a positive integer as this Name is less than, equal to, or greater than the given Object.

If obj is null or not an instance of CompoundName, ClassCastException is thrown.

See equals() for what it means for two compound names to be equal. If two compound names are equal, 0 is returned.

Ordering of compound names depend on the syntax of the compound name. By default, they follow lexicographical rules for string comparison with the extension that this applies to all the components in the compound name and that comparison of individual components is affected by the jndi.syntax.ignorecase and jndi.syntax.trimblanks properties, identical to how they affect equals(). If this compound name is "lexicographically" lesser than obj, a negative number is returned. If this compound name is "lexicographically" greater than obj, a positive number is returned.

Implementation note: Currently the syntax properties of the two compound names are not compared when checking order. They might be in the future.

Specified by:
compareTo in interface Comparable<Object>
Specified by:
compareTo in interface Name
Parameters:
obj - The non-null object to compare against.
Returns:
a negative integer, zero, or a positive integer as this Name is less than, equal to, or greater than the given Object.
Throws:
ClassCastException - if obj is not a CompoundName.
See Also:
equals(java.lang.Object)

size

public int size()
Retrieves the number of components in this compound name.

Specified by:
size in interface Name
Returns:
The nonnegative number of components in this compound name.

isEmpty

public boolean isEmpty()
Determines whether this compound name is empty. A compound name is empty if it has zero components.

Specified by:
isEmpty in interface Name
Returns:
true if this compound name is empty, false otherwise.

getAll

public Enumeration<String> getAll()
Retrieves the components of this compound name as an enumeration of strings. The effects of updates to this compound name on this enumeration is undefined.

Specified by:
getAll in interface Name
Returns:
A non-null enumeration of the components of this compound name. Each element of the enumeration is of class String.

get

public String get(int posn)
Retrieves a component of this compound name.

Specified by:
get in interface Name
Parameters:
posn - The 0-based index of the component to retrieve. Must be in the range [0,size()).
Returns:
The component at index posn.
Throws:
ArrayIndexOutOfBoundsException - if posn is outside the specified range.

getPrefix

public Name getPrefix(int posn)
Creates a compound name whose components consist of a prefix of the components in this compound name. The result and this compound name share the same syntax. Subsequent changes to this compound name does not affect the name that is returned and vice versa.

Specified by:
getPrefix in interface Name
Parameters:
posn - The 0-based index of the component at which to stop. Must be in the range [0,size()].
Returns:
A compound name consisting of the components at indexes in the range [0,posn).
Throws:
ArrayIndexOutOfBoundsException - If posn is outside the specified range.

getSuffix

public Name getSuffix(int posn)
Creates a compound name whose components consist of a suffix of the components in this compound name. The result and this compound name share the same syntax. Subsequent changes to this compound name does not affect the name that is returned.

Specified by:
getSuffix in interface Name
Parameters:
posn - The 0-based index of the component at which to start. Must be in the range [0,size()].
Returns:
A compound name consisting of the components at indexes in the range [posn,size()). If posn is equal to size(), an empty compound name is returned.
Throws:
ArrayIndexOutOfBoundsException - If posn is outside the specified range.

startsWith

public boolean startsWith(Name n)
Determines whether a compound name is a prefix of this compound name. A compound name 'n' is a prefix if it is equal to getPrefix(n.size())--in other words, this compound name starts with 'n'. If n is null or not a compound name, false is returned.

Implementation note: Currently the syntax properties of n are not used when doing the comparison. They might be in the future.

Specified by:
startsWith in interface Name
Parameters:
n - The possibly null compound name to check.
Returns:
true if n is a CompoundName and is a prefix of this compound name, false otherwise.

endsWith

public boolean endsWith(Name n)
Determines whether a compound name is a suffix of this compound name. A compound name 'n' is a suffix if it it is equal to getSuffix(size()-n.size())--in other words, this compound name ends with 'n'. If n is null or not a compound name, false is returned.

Implementation note: Currently the syntax properties of n are not used when doing the comparison. They might be in the future.

Specified by:
endsWith in interface Name
Parameters:
n - The possibly null compound name to check.
Returns:
true if n is a CompoundName and is a suffix of this compound name, false otherwise.

addAll

public Name addAll(Name suffix)
            throws InvalidNameException
Adds the components of a compound name -- in order -- to the end of this compound name.

Implementation note: Currently the syntax properties of suffix is not used or checked. They might be in the future.

Specified by:
addAll in interface Name
Parameters:
suffix - The non-null components to add.
Returns:
The updated CompoundName, not a new one. Cannot be null.
Throws:
InvalidNameException - If suffix is not a compound name, or if the addition of the components violates the syntax of this compound name (e.g. exceeding number of components).

addAll

public Name addAll(int posn,
                   Name n)
            throws InvalidNameException
Adds the components of a compound name -- in order -- at a specified position within this compound name. Components of this compound name at or after the index of the first new component are shifted up (away from index 0) to accommodate the new components.

Implementation note: Currently the syntax properties of suffix is not used or checked. They might be in the future.

Specified by:
addAll in interface Name
Parameters:
n - The non-null components to add.
posn - The index in this name at which to add the new components. Must be in the range [0,size()].
Returns:
The updated CompoundName, not a new one. Cannot be null.
Throws:
ArrayIndexOutOfBoundsException - If posn is outside the specified range.
InvalidNameException - If n is not a compound name, or if the addition of the components violates the syntax of this compound name (e.g. exceeding number of components).

add

public Name add(String comp)
         throws InvalidNameException
Adds a single component to the end of this compound name.

Specified by:
add in interface Name
Parameters:
comp - The non-null component to add.
Returns:
The updated CompoundName, not a new one. Cannot be null.
Throws:
InvalidNameException - If adding comp at end of the name would violate the compound name's syntax.

add

public Name add(int posn,
                String comp)
         throws InvalidNameException
Adds a single component at a specified position within this compound name. Components of this compound name at or after the index of the new component are shifted up by one (away from index 0) to accommodate the new component.

Specified by:
add in interface Name
Parameters:
comp - The non-null component to add.
posn - The index at which to add the new component. Must be in the range [0,size()].
Returns:
The updated CompoundName, not a new one. Cannot be null.
Throws:
ArrayIndexOutOfBoundsException - If posn is outside the specified range.
InvalidNameException - If adding comp at the specified position would violate the compound name's syntax.

remove

public Object remove(int posn)
              throws InvalidNameException
Deletes a component from this compound name. The component of this compound name at position 'posn' is removed, and components at indices greater than 'posn' are shifted down (towards index 0) by one.

Specified by:
remove in interface Name
Parameters:
posn - The index of the component to delete. Must be in the range [0,size()).
Returns:
The component removed (a String).
Throws:
ArrayIndexOutOfBoundsException - If posn is outside the specified range (includes case where compound name is empty).
InvalidNameException - If deleting the component would violate the compound name's syntax.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ConfigurationException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class ConfigurationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.ConfigurationException
All Implemented Interfaces:
Serializable
public class ConfigurationException
extends NamingException

This exception is thrown when there is a configuration problem. This can arise when installation of a provider was not done correctly, or if there are configuration problems with the server, or if configuration information required to access the provider or service is malformed or missing. For example, a request to use SSL as the security protocol when the service provider software was not configured with the SSL component would cause such an exception. Another example is if the provider requires that a URL be specified as one of the environment properties but the client failed to provide it.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
ConfigurationException()
Constructs a new instance of ConfigurationException with all name resolution fields and explanation initialized to null.
ConfigurationException(String explanation)
Constructs a new instance of ConfigurationException using an explanation.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ConfigurationException

public ConfigurationException(String explanation)
Constructs a new instance of ConfigurationException using an explanation. All other fields default to null.

Parameters:
explanation - A possibly null string containing additional detail about this exception.
See Also:
Throwable.getMessage()

ConfigurationException

public ConfigurationException()
Constructs a new instance of ConfigurationException with all name resolution fields and explanation initialized to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Context

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Interface Context

All Known Subinterfaces:
DirContext, EventContext, EventDirContext, LdapContext
All Known Implementing Classes:
InitialContext, InitialDirContext, InitialLdapContext
public interface Context

This interface represents a naming context, which consists of a set of name-to-object bindings. It contains methods for examining and updating these bindings.

Names

Each name passed as an argument to a Context method is relative to that context. The empty name is used to name the context itself. A name parameter may never be null.

Most of the methods have overloaded versions with one taking a Name parameter and one taking a String. These overloaded versions are equivalent in that if the Name and String parameters are just different representations of the same name, then the overloaded versions of the same methods behave the same. In the method descriptions below, only one version is fully documented. The second version instead has a link to the first: the same documentation applies to both.

For systems that support federation, String name arguments to Context methods are composite names. Name arguments that are instances of CompositeName are treated as composite names, while Name arguments that are not instances of CompositeName are treated as compound names (which might be instances of CompoundName or other implementations of compound names). This allows the results of NameParser.parse() to be used as arguments to the Context methods. Prior to JNDI 1.2, all name arguments were treated as composite names.

Furthermore, for systems that support federation, all names returned in a NamingEnumeration from list() and listBindings() are composite names represented as strings. See CompositeName for the string syntax of names.

For systems that do not support federation, the name arguments (in either Name or String forms) and the names returned in NamingEnumeration may be names in their own namespace rather than names in a composite namespace, at the discretion of the service provider.

Exceptions

All the methods in this interface can throw a NamingException or any of its subclasses. See NamingException and their subclasses for details on each exception.

Concurrent Access

A Context instance is not guaranteed to be synchronized against concurrent access by multiple threads. Threads that need to access a single Context instance concurrently should synchronize amongst themselves and provide the necessary locking. Multiple threads each manipulating a different Context instance need not synchronize. Note that the lookup method, when passed an empty name, will return a new Context instance representing the same naming context.

For purposes of concurrency control, a Context operation that returns a NamingEnumeration is not considered to have completed while the enumeration is still in use, or while any referrals generated by that operation are still being followed.

Parameters

A Name parameter passed to any method of the Context interface or one of its subinterfaces will not be modified by the service provider. The service provider may keep a reference to it for the duration of the operation, including any enumeration of the method's results and the processing of any referrals generated. The caller should not modify the object during this time. A Name returned by any such method is owned by the caller. The caller may subsequently modify it; the service provider may not.

Environment Properties

JNDI applications need a way to communicate various preferences and properties that define the environment in which naming and directory services are accessed. For example, a context might require specification of security credentials in order to access the service. Another context might require that server configuration information be supplied. These are referred to as the environment of a context. The Context interface provides methods for retrieving and updating this environment.

The environment is inherited from the parent context as context methods proceed from one context to the next. Changes to the environment of one context do not directly affect those of other contexts.

It is implementation-dependent when environment properties are used and/or verified for validity. For example, some of the security-related properties are used by service providers to "log in" to the directory. This login process might occur at the time the context is created, or the first time a method is invoked on the context. When, and whether this occurs at all, is implementation-dependent. When environment properties are added or removed from the context, verifying the validity of the changes is again implementation-dependent. For example, verification of some properties might occur at the time the change is made, or at the time the next operation is performed on the context, or not at all.

Any object with a reference to a context may examine that context's environment. Sensitive information such as clear-text passwords should not be stored there unless the implementation is known to protect it.

Resource Files

To simplify the task of setting up the environment required by a JNDI application, application components and service providers may be distributed along with resource files. A JNDI resource file is a file in the properties file format (see java.util.Properties), containing a list of key/value pairs. The key is the name of the property (e.g. "java.naming.factory.object") and the value is a string in the format defined for that property. Here is an example of a JNDI resource file:

 java.naming.factory.object=com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person
 java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person
 java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory
The JNDI class library reads the resource files and makes the property values freely available. Thus JNDI resource files should be considered to be "world readable", and sensitive information such as clear-text passwords should not be stored there.

There are two kinds of JNDI resource files: provider and application.

Provider Resource Files
Each service provider has an optional resource that lists properties specific to that provider. The name of this resource is:
[prefix/]jndiprovider.properties
where prefix is the package name of the provider's context implementation(s), with each period (".") converted to a slash ("/"). For example, suppose a service provider defines a context implementation with class name com.sun.jndi.ldap.LdapCtx. The provider resource for this provider is named com/sun/jndi/ldap/jndiprovider.properties. If the class is not in a package, the resource's name is simply jndiprovider.properties.

Certain methods in the JNDI class library make use of the standard JNDI properties that specify lists of JNDI factories:

  • java.naming.factory.object
  • java.naming.factory.state
  • java.naming.factory.control
  • java.naming.factory.url.pkgs
The JNDI library will consult the provider resource file when determining the values of these properties. Properties other than these may be set in the provider resource file at the discretion of the service provider. The service provider's documentation should clearly state which properties are allowed; other properties in the file will be ignored.
Application Resource Files
When an application is deployed, it will generally have several codebase directories and JARs in its classpath. Similarly, when an applet is deployed, it will have a codebase and archives specifying where to find the applet's classes. JNDI locates (using ClassLoader.getResources()) all application resource files named jndi.properties in the classpath. In addition, if the file java.home/lib/jndi.properties exists and is readable, JNDI treats it as an additional application resource file. (java.home indicates the directory named by the java.home system property.) All of the properties contained in these files are placed into the environment of the initial context. This environment is then inherited by other contexts.

For each property found in more than one application resource file, JNDI uses the first value found or, in a few cases where it makes sense to do so, it concatenates all of the values (details are given below). For example, if the "java.naming.factory.object" property is found in three jndi.properties resource files, the list of object factories is a concatenation of the property values from all three files. Using this scheme, each deployable component is responsible for listing the factories that it exports. JNDI automatically collects and uses all of these export lists when searching for factory classes.

Search Algorithm for Properties
When JNDI constructs an initial context, the context's environment is initialized with properties defined in the environment parameter passed to the constructor, the system properties, the applet parameters, and the application resource files. See InitialContext for details. This initial environment is then inherited by other context instances.

When the JNDI class library needs to determine the value of a property, it does so by merging the values from the following two sources, in order:

  1. The environment of the context being operated on.
  2. The provider resource file (jndiprovider.properties) for the context being operated on.
For each property found in both of these two sources, JNDI determines the property's value as follows. If the property is one of the standard JNDI properties that specify a list of JNDI factories (listed above), the values are concatenated into a single colon-separated list. For other properties, only the first value found is used.

When a service provider needs to determine the value of a property, it will generally take that value directly from the environment. A service provider may define provider-specific properties to be placed in its own provider resource file. In that case it should merge values as described in the previous paragraph.

In this way, each service provider developer can specify a list of factories to use with that service provider. These can be modified by the application resources specified by the deployer of the application or applet, which in turn can be modified by the user.

Since:
1.3

Field Summary
static String | APPLET Constant that holds the name of the environment property for specifying an applet for the initial context constructor to use when searching for other properties.
static String | AUTHORITATIVE Constant that holds the name of the environment property for specifying the authoritativeness of the service requested.
static String | BATCHSIZE Constant that holds the name of the environment property for specifying the batch size to use when returning data via the service's protocol.
static String | DNS_URL Constant that holds the name of the environment property for specifying the DNS host and domain names to use for the JNDI URL context (for example, "dns://somehost/wiz.com").
static String | INITIAL_CONTEXT_FACTORY Constant that holds the name of the environment property for specifying the initial context factory to use.
static String | LANGUAGE Constant that holds the name of the environment property for specifying the preferred language to use with the service.
static String | OBJECT_FACTORIES Constant that holds the name of the environment property for specifying the list of object factories to use.
static String | PROVIDER_URL Constant that holds the name of the environment property for specifying configuration information for the service provider to use.
static String | REFERRAL Constant that holds the name of the environment property for specifying how referrals encountered by the service provider are to be processed.
static String | SECURITY_AUTHENTICATION Constant that holds the name of the environment property for specifying the security level to use.
static String | SECURITY_CREDENTIALS Constant that holds the name of the environment property for specifying the credentials of the principal for authenticating the caller to the service.
static String | SECURITY_PRINCIPAL Constant that holds the name of the environment property for specifying the identity of the principal for authenticating the caller to the service.
static String | SECURITY_PROTOCOL Constant that holds the name of the environment property for specifying the security protocol to use.
static String | STATE_FACTORIES Constant that holds the name of the environment property for specifying the list of state factories to use.
static String | URL_PKG_PREFIXES Constant that holds the name of the environment property for specifying the list of package prefixes to use when loading in URL context factories.
Method Summary
Object | addToEnvironment(String propName, Object propVal) Adds a new environment property to the environment of this context.
void | bind(Name name, Object obj) Binds a name to an object.
void | bind(String name, Object obj) Binds a name to an object.
void | close() Closes this context.
Name | composeName(Name name, Name prefix) Composes the name of this context with a name relative to this context.
String | composeName(String name, String prefix) Composes the name of this context with a name relative to this context.
Context | createSubcontext(Name name) Creates and binds a new context.
Context | createSubcontext(String name) Creates and binds a new context.
void | destroySubcontext(Name name) Destroys the named context and removes it from the namespace.
void | destroySubcontext(String name) Destroys the named context and removes it from the namespace.
Hashtable<?,?> | getEnvironment() Retrieves the environment in effect for this context.
String | getNameInNamespace() Retrieves the full name of this context within its own namespace.
NameParser | getNameParser(Name name) Retrieves the parser associated with the named context.
NameParser | getNameParser(String name) Retrieves the parser associated with the named context.
NamingEnumeration<NameClassPair> | list(Name name) Enumerates the names bound in the named context, along with the class names of objects bound to them.
NamingEnumeration<NameClassPair> | list(String name) Enumerates the names bound in the named context, along with the class names of objects bound to them.
NamingEnumeration<Binding> | listBindings(Name name) Enumerates the names bound in the named context, along with the objects bound to them.
NamingEnumeration<Binding> | listBindings(String name) Enumerates the names bound in the named context, along with the objects bound to them.
Object | lookup(Name name) Retrieves the named object.
Object | lookup(String name) Retrieves the named object.
Object | lookupLink(Name name) Retrieves the named object, following links except for the terminal atomic component of the name.
Object | lookupLink(String name) Retrieves the named object, following links except for the terminal atomic component of the name.
void | rebind(Name name, Object obj) Binds a name to an object, overwriting any existing binding.
void | rebind(String name, Object obj) Binds a name to an object, overwriting any existing binding.
Object | removeFromEnvironment(String propName) Removes an environment property from the environment of this context.
void | rename(Name oldName, Name newName) Binds a new name to the object bound to an old name, and unbinds the old name.
void | rename(String oldName, String newName) Binds a new name to the object bound to an old name, and unbinds the old name.
void | unbind(Name name) Unbinds the named object.
void | unbind(String name) Unbinds the named object.

Field Detail

INITIAL_CONTEXT_FACTORY

static final String INITIAL_CONTEXT_FACTORY
Constant that holds the name of the environment property for specifying the initial context factory to use. The value of the property should be the fully qualified class name of the factory class that will create an initial context. This property may be specified in the environment parameter passed to the initial context constructor, an applet parameter, a system property, or an application resource file. If it is not specified in any of these sources, NoInitialContextException is thrown when an initial context is required to complete an operation.

The value of this constant is "java.naming.factory.initial".

See Also:
InitialContext, InitialDirContext, NamingManager.getInitialContext(java.util.Hashtable), InitialContextFactory, NoInitialContextException, addToEnvironment(String, Object), removeFromEnvironment(String), APPLET, Constant Field Values

OBJECT_FACTORIES

static final String OBJECT_FACTORIES
Constant that holds the name of the environment property for specifying the list of object factories to use. The value of the property should be a colon-separated list of the fully qualified class names of factory classes that will create an object given information about the object. This property may be specified in the environment, an applet parameter, a system property, or one or more resource files.

The value of this constant is "java.naming.factory.object".

See Also:
NamingManager.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), ObjectFactory, addToEnvironment(String, Object), removeFromEnvironment(String), APPLET, Constant Field Values

STATE_FACTORIES

static final String STATE_FACTORIES
Constant that holds the name of the environment property for specifying the list of state factories to use. The value of the property should be a colon-separated list of the fully qualified class names of state factory classes that will be used to get an object's state given the object itself. This property may be specified in the environment, an applet parameter, a system property, or one or more resource files.

The value of this constant is "java.naming.factory.state".

Since:
1.3
See Also:
NamingManager.getStateToBind(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), StateFactory, addToEnvironment(String, Object), removeFromEnvironment(String), APPLET, Constant Field Values

URL_PKG_PREFIXES

static final String URL_PKG_PREFIXES
Constant that holds the name of the environment property for specifying the list of package prefixes to use when loading in URL context factories. The value of the property should be a colon-separated list of package prefixes for the class name of the factory class that will create a URL context factory. This property may be specified in the environment, an applet parameter, a system property, or one or more resource files. The prefix com.sun.jndi.url is always appended to the possibly empty list of package prefixes.

The value of this constant is "java.naming.factory.url.pkgs".

See Also:
NamingManager.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), NamingManager.getURLContext(java.lang.String, java.util.Hashtable), ObjectFactory, addToEnvironment(String, Object), removeFromEnvironment(String), APPLET, Constant Field Values

PROVIDER_URL

static final String PROVIDER_URL
Constant that holds the name of the environment property for specifying configuration information for the service provider to use. The value of the property should contain a URL string (e.g. "ldap://somehost:389"). This property may be specified in the environment, an applet parameter, a system property, or a resource file. If it is not specified in any of these sources, the default configuration is determined by the service provider.

The value of this constant is "java.naming.provider.url".

See Also:
addToEnvironment(String, Object), removeFromEnvironment(String), APPLET, Constant Field Values

DNS_URL

static final String DNS_URL
Constant that holds the name of the environment property for specifying the DNS host and domain names to use for the JNDI URL context (for example, "dns://somehost/wiz.com"). This property may be specified in the environment, an applet parameter, a system property, or a resource file. If it is not specified in any of these sources and the program attempts to use a JNDI URL containing a DNS name, a ConfigurationException will be thrown.

The value of this constant is "java.naming.dns.url".

See Also:
addToEnvironment(String, Object), removeFromEnvironment(String), Constant Field Values

AUTHORITATIVE

static final String AUTHORITATIVE
Constant that holds the name of the environment property for specifying the authoritativeness of the service requested. If the value of the property is the string "true", it means that the access is to the most authoritative source (i.e. bypass any cache or replicas). If the value is anything else, the source need not be (but may be) authoritative. If unspecified, the value defaults to "false".

The value of this constant is "java.naming.authoritative".

See Also:
addToEnvironment(String, Object), removeFromEnvironment(String), Constant Field Values

BATCHSIZE

static final String BATCHSIZE
Constant that holds the name of the environment property for specifying the batch size to use when returning data via the service's protocol. This is a hint to the provider to return the results of operations in batches of the specified size, so the provider can optimize its performance and usage of resources. The value of the property is the string representation of an integer. If unspecified, the batch size is determined by the service provider.

The value of this constant is "java.naming.batchsize".

See Also:
addToEnvironment(String, Object), removeFromEnvironment(String), Constant Field Values

REFERRAL

static final String REFERRAL
Constant that holds the name of the environment property for specifying how referrals encountered by the service provider are to be processed. The value of the property is one of the following strings:
"follow"
follow referrals automatically
"ignore"
ignore referrals
"throw"
throw ReferralException when a referral is encountered.
If this property is not specified, the default is determined by the provider.

The value of this constant is "java.naming.referral".

See Also:
addToEnvironment(String, Object), removeFromEnvironment(String), Constant Field Values

SECURITY_PROTOCOL

static final String SECURITY_PROTOCOL
Constant that holds the name of the environment property for specifying the security protocol to use. Its value is a string determined by the service provider (e.g. "ssl"). If this property is unspecified, the behaviour is determined by the service provider.

The value of this constant is "java.naming.security.protocol".

See Also:
addToEnvironment(String, Object), removeFromEnvironment(String), Constant Field Values

SECURITY_AUTHENTICATION

static final String SECURITY_AUTHENTICATION
Constant that holds the name of the environment property for specifying the security level to use. Its value is one of the following strings: "none", "simple", "strong". If this property is unspecified, the behaviour is determined by the service provider.

The value of this constant is "java.naming.security.authentication".

See Also:
addToEnvironment(String, Object), removeFromEnvironment(String), Constant Field Values

SECURITY_PRINCIPAL

static final String SECURITY_PRINCIPAL
Constant that holds the name of the environment property for specifying the identity of the principal for authenticating the caller to the service. The format of the principal depends on the authentication scheme. If this property is unspecified, the behaviour is determined by the service provider.

The value of this constant is "java.naming.security.principal".

See Also:
addToEnvironment(String, Object), removeFromEnvironment(String), Constant Field Values

SECURITY_CREDENTIALS

static final String SECURITY_CREDENTIALS
Constant that holds the name of the environment property for specifying the credentials of the principal for authenticating the caller to the service. The value of the property depends on the authentication scheme. For example, it could be a hashed password, clear-text password, key, certificate, and so on. If this property is unspecified, the behaviour is determined by the service provider.

The value of this constant is "java.naming.security.credentials".

See Also:
addToEnvironment(String, Object), removeFromEnvironment(String), Constant Field Values

LANGUAGE

static final String LANGUAGE
Constant that holds the name of the environment property for specifying the preferred language to use with the service. The value of the property is a colon-separated list of language tags as defined in RFC 1766. If this property is unspecified, the language preference is determined by the service provider.

The value of this constant is "java.naming.language".

See Also:
addToEnvironment(String, Object), removeFromEnvironment(String), Constant Field Values

APPLET

static final String APPLET
Constant that holds the name of the environment property for specifying an applet for the initial context constructor to use when searching for other properties. The value of this property is the java.applet.Applet instance that is being executed. This property may be specified in the environment parameter passed to the initial context constructor. When this property is set, each property that the initial context constructor looks for in the system properties is first looked for in the applet's parameter list. If this property is unspecified, the initial context constructor will search for properties only in the environment parameter passed to it, the system properties, and application resource files.

The value of this constant is "java.naming.applet".

Since:
1.3
See Also:
addToEnvironment(String, Object), removeFromEnvironment(String), InitialContext, Constant Field Values
Method Detail

lookup

Object lookup(Name name)
              throws NamingException
Retrieves the named object. If name is empty, returns a new instance of this context (which represents the same naming context as this context, but its environment may be modified independently and it may be accessed concurrently).

Parameters:
name - the name of the object to look up
Returns:
the object bound to name
Throws:
NamingException - if a naming exception is encountered
See Also:
lookup(String), lookupLink(Name)

lookup

Object lookup(String name)
              throws NamingException
Retrieves the named object. See lookup(Name) for details.

Parameters:
name - the name of the object to look up
Returns:
the object bound to name
Throws:
NamingException - if a naming exception is encountered

bind

void bind(Name name,
          Object obj)
          throws NamingException
Binds a name to an object. All intermediate contexts and the target context (that named by all but terminal atomic component of the name) must already exist.

Parameters:
name - the name to bind; may not be empty
obj - the object to bind; possibly null
Throws:
NameAlreadyBoundException - if name is already bound
InvalidAttributesException - if object did not supply all mandatory attributes
NamingException - if a naming exception is encountered
See Also:
bind(String, Object), rebind(Name, Object), DirContext.bind(Name, Object, javax.naming.directory.Attributes)

bind

void bind(String name,
          Object obj)
          throws NamingException
Binds a name to an object. See bind(Name, Object) for details.

Parameters:
name - the name to bind; may not be empty
obj - the object to bind; possibly null
Throws:
NameAlreadyBoundException - if name is already bound
InvalidAttributesException - if object did not supply all mandatory attributes
NamingException - if a naming exception is encountered

rebind

void rebind(Name name,
            Object obj)
            throws NamingException
Binds a name to an object, overwriting any existing binding. All intermediate contexts and the target context (that named by all but terminal atomic component of the name) must already exist.

If the object is a DirContext, any existing attributes associated with the name are replaced with those of the object. Otherwise, any existing attributes associated with the name remain unchanged.

Parameters:
name - the name to bind; may not be empty
obj - the object to bind; possibly null
Throws:
InvalidAttributesException - if object did not supply all mandatory attributes
NamingException - if a naming exception is encountered
See Also:
rebind(String, Object), bind(Name, Object), DirContext.rebind(Name, Object, javax.naming.directory.Attributes), DirContext

rebind

void rebind(String name,
            Object obj)
            throws NamingException
Binds a name to an object, overwriting any existing binding. See rebind(Name, Object) for details.

Parameters:
name - the name to bind; may not be empty
obj - the object to bind; possibly null
Throws:
InvalidAttributesException - if object did not supply all mandatory attributes
NamingException - if a naming exception is encountered

unbind

void unbind(Name name)
            throws NamingException
Unbinds the named object. Removes the terminal atomic name in name from the target context--that named by all but the terminal atomic part of name.

This method is idempotent. It succeeds even if the terminal atomic name is not bound in the target context, but throws NameNotFoundException if any of the intermediate contexts do not exist.

Any attributes associated with the name are removed. Intermediate contexts are not changed.

Parameters:
name - the name to unbind; may not be empty
Throws:
NameNotFoundException - if an intermediate context does not exist
NamingException - if a naming exception is encountered
See Also:
unbind(String)

unbind

void unbind(String name)
            throws NamingException
Unbinds the named object. See unbind(Name) for details.

Parameters:
name - the name to unbind; may not be empty
Throws:
NameNotFoundException - if an intermediate context does not exist
NamingException - if a naming exception is encountered

rename

void rename(Name oldName,
            Name newName)
            throws NamingException
Binds a new name to the object bound to an old name, and unbinds the old name. Both names are relative to this context. Any attributes associated with the old name become associated with the new name. Intermediate contexts of the old name are not changed.

Parameters:
oldName - the name of the existing binding; may not be empty
newName - the name of the new binding; may not be empty
Throws:
NameAlreadyBoundException - if newName is already bound
NamingException - if a naming exception is encountered
See Also:
rename(String, String),
bind(Name, Object),
rebind(Name, Object)

rename

void rename(String oldName,
            String newName)
            throws NamingException
Binds a new name to the object bound to an old name, and unbinds the old name. See rename(Name, Name) for details.

Parameters:
oldName - the name of the existing binding; may not be empty
newName - the name of the new binding; may not be empty
Throws:
NameAlreadyBoundException - if newName is already bound
NamingException - if a naming exception is encountered

list

NamingEnumeration<NameClassPair> list(Name name)
                                      throws NamingException
Enumerates the names bound in the named context, along with the class names of objects bound to them. The contents of any subcontexts are not included.

If a binding is added to or removed from this context, its effect on an enumeration previously returned is undefined.

Parameters:
name - the name of the context to list
Returns:
an enumeration of the names and class names of the bindings in this context. Each element of the enumeration is of type NameClassPair.
Throws:
NamingException - if a naming exception is encountered
See Also:
list(String), listBindings(Name), NameClassPair

list

NamingEnumeration<NameClassPair> list(String name)
                                      throws NamingException
Enumerates the names bound in the named context, along with the class names of objects bound to them. See list(Name) for details.

Parameters:
name - the name of the context to list
Returns:
an enumeration of the names and class names of the bindings in this context. Each element of the enumeration is of type NameClassPair.
Throws:
NamingException - if a naming exception is encountered

listBindings

NamingEnumeration<Binding> listBindings(Name name)
                                        throws NamingException
Enumerates the names bound in the named context, along with the objects bound to them. The contents of any subcontexts are not included.

If a binding is added to or removed from this context, its effect on an enumeration previously returned is undefined.

Parameters:
name - the name of the context to list
Returns:
an enumeration of the bindings in this context. Each element of the enumeration is of type Binding.
Throws:
NamingException - if a naming exception is encountered
See Also:
listBindings(String), list(Name), Binding

listBindings

NamingEnumeration<Binding> listBindings(String name)
                                        throws NamingException
Enumerates the names bound in the named context, along with the objects bound to them. See listBindings(Name) for details.

Parameters:
name - the name of the context to list
Returns:
an enumeration of the bindings in this context. Each element of the enumeration is of type Binding.
Throws:
NamingException - if a naming exception is encountered

destroySubcontext

void destroySubcontext(Name name)
                       throws NamingException
Destroys the named context and removes it from the namespace. Any attributes associated with the name are also removed. Intermediate contexts are not destroyed.

This method is idempotent. It succeeds even if the terminal atomic name is not bound in the target context, but throws NameNotFoundException if any of the intermediate contexts do not exist.

In a federated naming system, a context from one naming system may be bound to a name in another. One can subsequently look up and perform operations on the foreign context using a composite name. However, an attempt destroy the context using this composite name will fail with NotContextException, because the foreign context is not a "subcontext" of the context in which it is bound. Instead, use unbind() to remove the binding of the foreign context. Destroying the foreign context requires that the destroySubcontext() be performed on a context from the foreign context's "native" naming system.

Parameters:
name - the name of the context to be destroyed; may not be empty
Throws:
NameNotFoundException - if an intermediate context does not exist
NotContextException - if the name is bound but does not name a context, or does not name a context of the appropriate type
ContextNotEmptyException - if the named context is not empty
NamingException - if a naming exception is encountered
See Also:
destroySubcontext(String)

destroySubcontext

void destroySubcontext(String name)
                       throws NamingException
Destroys the named context and removes it from the namespace. See destroySubcontext(Name) for details.

Parameters:
name - the name of the context to be destroyed; may not be empty
Throws:
NameNotFoundException - if an intermediate context does not exist
NotContextException - if the name is bound but does not name a context, or does not name a context of the appropriate type
ContextNotEmptyException - if the named context is not empty
NamingException - if a naming exception is encountered

createSubcontext

Context createSubcontext(Name name)
                         throws NamingException
Creates and binds a new context. Creates a new context with the given name and binds it in the target context (that named by all but terminal atomic component of the name). All intermediate contexts and the target context must already exist.

Parameters:
name - the name of the context to create; may not be empty
Returns:
the newly created context
Throws:
NameAlreadyBoundException - if name is already bound
InvalidAttributesException - if creation of the subcontext requires specification of mandatory attributes
NamingException - if a naming exception is encountered
See Also:
createSubcontext(String), DirContext.createSubcontext(javax.naming.Name, javax.naming.directory.Attributes)

createSubcontext

Context createSubcontext(String name)
                         throws NamingException
Creates and binds a new context. See createSubcontext(Name) for details.

Parameters:
name - the name of the context to create; may not be empty
Returns:
the newly created context
Throws:
NameAlreadyBoundException - if name is already bound
InvalidAttributesException - if creation of the subcontext requires specification of mandatory attributes
NamingException - if a naming exception is encountered

lookupLink

Object lookupLink(Name name)
                  throws NamingException
Retrieves the named object, following links except for the terminal atomic component of the name. If the object bound to name is not a link, returns the object itself.

Parameters:
name - the name of the object to look up
Returns:
the object bound to name, not following the terminal link (if any).
Throws:
NamingException - if a naming exception is encountered
See Also:
lookupLink(String)

lookupLink

Object lookupLink(String name)
                  throws NamingException
Retrieves the named object, following links except for the terminal atomic component of the name. See lookupLink(Name) for details.

Parameters:
name - the name of the object to look up
Returns:
the object bound to name, not following the terminal link (if any)
Throws:
NamingException - if a naming exception is encountered

getNameParser

NameParser getNameParser(Name name)
                         throws NamingException
Retrieves the parser associated with the named context. In a federation of namespaces, different naming systems will parse names differently. This method allows an application to get a parser for parsing names into their atomic components using the naming convention of a particular naming system. Within any single naming system, NameParser objects returned by this method must be equal (using the equals() test).

Parameters:
name - the name of the context from which to get the parser
Returns:
a name parser that can parse compound names into their atomic components
Throws:
NamingException - if a naming exception is encountered
See Also:
getNameParser(String), CompoundName

getNameParser

NameParser getNameParser(String name)
                         throws NamingException
Retrieves the parser associated with the named context. See getNameParser(Name) for details.

Parameters:
name - the name of the context from which to get the parser
Returns:
a name parser that can parse compound names into their atomic components
Throws:
NamingException - if a naming exception is encountered

composeName

Name composeName(Name name,
                 Name prefix)
                 throws NamingException
Composes the name of this context with a name relative to this context. Given a name (name) relative to this context, and the name (prefix) of this context relative to one of its ancestors, this method returns the composition of the two names using the syntax appropriate for the naming system(s) involved. That is, if name names an object relative to this context, the result is the name of the same object, but relative to the ancestor context. None of the names may be null.

For example, if this context is named "wiz.com" relative to the initial context, then

        composeName("east", "wiz.com")
might return "east.wiz.com". If instead this context is named "org/research", then
        composeName("user/jane", "org/research")
might return "org/research/user/jane" while
        composeName("user/jane", "research")
returns "research/user/jane".

Parameters:
name - a name relative to this context
prefix - the name of this context relative to one of its ancestors
Returns:
the composition of prefix and name
Throws:
NamingException - if a naming exception is encountered
See Also:
composeName(String, String)

composeName

String composeName(String name,
                   String prefix)
                   throws NamingException
Composes the name of this context with a name relative to this context. See composeName(Name, Name) for details.

Parameters:
name - a name relative to this context
prefix - the name of this context relative to one of its ancestors
Returns:
the composition of prefix and name
Throws:
NamingException - if a naming exception is encountered

addToEnvironment

Object addToEnvironment(String propName,
                        Object propVal)
                        throws NamingException
Adds a new environment property to the environment of this context. If the property already exists, its value is overwritten. See class description for more details on environment properties.

Parameters:
propName - the name of the environment property to add; may not be null
propVal - the value of the property to add; may not be null
Returns:
the previous value of the property, or null if the property was not in the environment before
Throws:
NamingException - if a naming exception is encountered
See Also:
getEnvironment(), removeFromEnvironment(String)

removeFromEnvironment

Object removeFromEnvironment(String propName)
                             throws NamingException
Removes an environment property from the environment of this context. See class description for more details on environment properties.

Parameters:
propName - the name of the environment property to remove; may not be null
Returns:
the previous value of the property, or null if the property was not in the environment
Throws:
NamingException - if a naming exception is encountered
See Also:
getEnvironment(), addToEnvironment(String, Object)

getEnvironment

Hashtable<?,?> getEnvironment()
                              throws NamingException
Retrieves the environment in effect for this context. See class description for more details on environment properties.

The caller should not make any changes to the object returned: their effect on the context is undefined. The environment of this context may be changed using addToEnvironment() and removeFromEnvironment().

Returns:
the environment of this context; never null
Throws:
NamingException - if a naming exception is encountered
See Also:
addToEnvironment(String, Object), removeFromEnvironment(String)

close

void close()
           throws NamingException
Closes this context. This method releases this context's resources immediately, instead of waiting for them to be released automatically by the garbage collector.

This method is idempotent: invoking it on a context that has already been closed has no effect. Invoking any other method on a closed context is not allowed, and results in undefined behaviour.

Throws:
NamingException - if a naming exception is encountered

getNameInNamespace

String getNameInNamespace()
                          throws NamingException
Retrieves the full name of this context within its own namespace.

Many naming services have a notion of a "full name" for objects in their respective namespaces. For example, an LDAP entry has a distinguished name, and a DNS record has a fully qualified name. This method allows the client application to retrieve this name. The string returned by this method is not a JNDI composite name and should not be passed directly to context methods. In naming systems for which the notion of full name does not make sense, OperationNotSupportedException is thrown.

Returns:
this context's name in its own namespace; never null
Throws:
OperationNotSupportedException - if the naming system does not have the notion of a full name
NamingException - if a naming exception is encountered
Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ContextNotEmptyException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class ContextNotEmptyException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.ContextNotEmptyException
All Implemented Interfaces:
Serializable
public class ContextNotEmptyException
extends NamingException

This exception is thrown when attempting to destroy a context that is not empty.

If the program wants to handle this exception in particular, it should catch ContextNotEmptyException explicitly before attempting to catch NamingException. For example, after catching ContextNotEmptyException, the program might try to remove the contents of the context before reattempting the destroy.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Context.destroySubcontext(javax.naming.Name), Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
ContextNotEmptyException()
Constructs a new instance of ContextNotEmptyException with all name resolution fields and explanation initialized to null.
ContextNotEmptyException(String explanation)
Constructs a new instance of ContextNotEmptyException using an explanation.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ContextNotEmptyException

public ContextNotEmptyException(String explanation)
Constructs a new instance of ContextNotEmptyException using an explanation. All other fields default to null.

Parameters:
explanation - Possibly null string containing additional detail about this exception.
See Also:
Throwable.getMessage()

ContextNotEmptyException

public ContextNotEmptyException()
Constructs a new instance of ContextNotEmptyException with all name resolution fields and explanation initialized to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


directory

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.naming.directory

Extends the javax.naming package to provide functionality for accessing directory services.

See:
Description

Interface Summary
Attribute | This interface represents an attribute associated with a named object.
Attributes | This interface represents a collection of attributes.
DirContext | The directory service interface, containing methods for examining and updating attributes associated with objects, and for searching the directory.

Class Summary
BasicAttribute | This class provides a basic implementation of the Attribute interface.
BasicAttributes | This class provides a basic implementation of the Attributes interface.
InitialDirContext | This class is the starting context for performing directory operations.
ModificationItem | This class represents a modification item.
SearchControls | This class encapsulates factors that determine scope of search and what gets returned as a result of the search.
SearchResult | This class represents an item in the NamingEnumeration returned as a result of the DirContext.search() methods.

Exception Summary
AttributeInUseException | This exception is thrown when an operation attempts to add an attribute that already exists.
AttributeModificationException | This exception is thrown when an attempt is made to add, or remove, or modify an attribute, its identifier, or its values that conflicts with the attribute's (schema) definition or the attribute's state.
InvalidAttributeIdentifierException | This exception is thrown when an attempt is made to add to create an attribute with an invalid attribute identifier.
InvalidAttributesException | This exception is thrown when an attempt is made to add or modify an attribute set that has been specified incompletely or incorrectly.
InvalidAttributeValueException | This class is thrown when an attempt is made to add to an attribute a value that conflicts with the attribute's schema definition.
InvalidSearchControlsException | This exception is thrown when the specification of the SearchControls for a search operation is invalid.
InvalidSearchFilterException | This exception is thrown when the specification of a search filter is invalid.
NoSuchAttributeException | This exception is thrown when attempting to access an attribute that does not exist.
SchemaViolationException | This exception is thrown when a method in some ways violates the schema.

Package javax.naming.directory Description

Extends the javax.naming package to provide functionality for accessing directory services.

This package defines the directory operations of the Java Naming and Directory InterfaceTM (JNDI). JNDI provides naming and directory functionality to applications written in the Java programming language. It is designed to be independent of any specific naming or directory service implementation. Thus a variety of services--new, emerging, and already deployed ones--can be accessed in a common way.

This package allows applications to retrieve and update attributes associated with objects stored in a directory, and to search for objects using specified attributes.

The Directory Context

The DirContext interface represents a directory context. It defines methods for examining and updating attributes associated with a directory object, or directory entry as it is sometimes called.

You use getAttributes() to retrieve the attributes associated with a directory object (for which you supply the name). Attributes are modified using modifyAttributes(). You can add, replace, or remove attributes and/or attribute values using this operation.

DirContext also behaves as a naming context by extending the Context interface in the javax.naming package. This means that any directory object can also provide a naming context. For example, the directory object for a person might contain the attributes of that person, and at the same time provide a context for naming objects relative to that person such as his printers and home directory.

Searches

DirContext contains methods for performing content-based searching of the directory. In the simplest and most common form of usage, the application specifies a set of attributes--possibly with specific values--to match, and submits this attribute set, to the search() method. There are other overloaded forms of search() that support more sophisticated search filters.

Package Specification

The JNDI API Specification and related documents can be found in the JNDI documentation.

Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.naming.directory Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.naming.directory

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.naming.directory.BasicAttribute (implements javax.naming.directory.Attribute)
    • javax.naming.directory.BasicAttributes (implements javax.naming.directory.Attributes)
    • javax.naming.InitialContext (implements javax.naming.Context)
      • javax.naming.directory.InitialDirContext (implements javax.naming.directory.DirContext)
    • javax.naming.directory.ModificationItem (implements java.io.Serializable)
    • javax.naming.NameClassPair (implements java.io.Serializable)
      • javax.naming.Binding
        • javax.naming.directory.SearchResult
    • javax.naming.directory.SearchControls (implements java.io.Serializable)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.naming.NamingException
          • javax.naming.directory.AttributeInUseException
          • javax.naming.directory.AttributeModificationException
          • javax.naming.directory.InvalidAttributeIdentifierException
          • javax.naming.directory.InvalidAttributesException
          • javax.naming.directory.InvalidAttributeValueException
          • javax.naming.directory.InvalidSearchControlsException
          • javax.naming.directory.InvalidSearchFilterException
          • javax.naming.directory.NoSuchAttributeException
          • javax.naming.directory.SchemaViolationException

Interface Hierarchy

  • java.lang.Cloneable
    • javax.naming.directory.Attribute (also extends java.io.Serializable)
    • javax.naming.directory.Attributes (also extends java.io.Serializable)
  • javax.naming.Context
    • javax.naming.directory.DirContext
  • java.io.Serializable
    • javax.naming.directory.Attribute (also extends java.lang.Cloneable)
    • javax.naming.directory.Attributes (also extends java.lang.Cloneable)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.naming.directory

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.naming.directory

Packages that use javax.naming.directory
javax.naming.directory | Extends the javax.naming package to provide functionality for accessing directory services.
javax.naming.event | Provides support for event notification when accessing naming and directory services.
javax.naming.ldap | Provides support for LDAPv3 extended operations and controls.
javax.naming.spi | Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.

Classes in javax.naming.directory used by javax.naming.directory
Attribute
This interface represents an attribute associated with a named object.
Attributes
This interface represents a collection of attributes.
DirContext
The directory service interface, containing methods for examining and updating attributes associated with objects, and for searching the directory.
ModificationItem
This class represents a modification item.
SearchControls
This class encapsulates factors that determine scope of search and what gets returned as a result of the search.
SearchResult
This class represents an item in the NamingEnumeration returned as a result of the DirContext.search() methods.

Classes in javax.naming.directory used by javax.naming.event
DirContext
The directory service interface, containing methods for examining and updating attributes associated with objects, and for searching the directory.
SearchControls
This class encapsulates factors that determine scope of search and what gets returned as a result of the search.

Classes in javax.naming.directory used by javax.naming.ldap
Attributes
This interface represents a collection of attributes.
DirContext
The directory service interface, containing methods for examining and updating attributes associated with objects, and for searching the directory.
InitialDirContext
This class is the starting context for performing directory operations.

Classes in javax.naming.directory used by javax.naming.spi
Attributes
This interface represents a collection of attributes.
DirContext
The directory service interface, containing methods for examining and updating attributes associated with objects, and for searching the directory.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Attribute

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Interface Attribute

All Superinterfaces:
Cloneable, Serializable
All Known Implementing Classes:
BasicAttribute
public interface Attribute
extends Cloneable, Serializable

This interface represents an attribute associated with a named object.

In a directory, named objects can have associated with them attributes. The Attribute interface represents an attribute associated with a named object. An attribute contains 0 or more, possibly null, values. The attribute values can be ordered or unordered (see isOrdered()). If the values are unordered, no duplicates are allowed. If the values are ordered, duplicates are allowed.

The content and representation of an attribute and its values is defined by the attribute's schema. The schema contains information about the attribute's syntax and other properties about the attribute. See getAttributeDefinition() and getAttributeSyntaxDefinition() for details regarding how to get schema information about an attribute if the underlying directory service supports schemas.

Equality of two attributes is determined by the implementation class. A simple implementation can use Object.equals() to determine equality of attribute values, while a more sophisticated implementation might make use of schema information to determine equality. Similarly, one implementation might provide a static storage structure which simply returns the values passed to its constructor, while another implementation might define get() and getAll(). to get the values dynamically from the directory.

Note that updates to Attribute (such as adding or removing a value) do not affect the corresponding representation of the attribute in the directory. Updates to the directory can only be effected using operations in the DirContext interface.

Since:
1.3
See Also:
BasicAttribute

Field Summary
static long serialVersionUID
Use serialVersionUID from JNDI 1.1.1 for interoperability.
Method Summary
void | add(int ix, Object attrVal) Adds an attribute value to the ordered list of attribute values.
boolean | add(Object attrVal) Adds a new value to the attribute.
void | clear() Removes all values from this attribute.
Object | clone() Makes a copy of the attribute.
boolean | contains(Object attrVal) Determines whether a value is in the attribute.
Object | get() Retrieves one of this attribute's values.
Object | get(int ix) Retrieves the attribute value from the ordered list of attribute values.
NamingEnumeration<?> | getAll() Retrieves an enumeration of the attribute's values.
DirContext | getAttributeDefinition() Retrieves the attribute's schema definition.
DirContext | getAttributeSyntaxDefinition() Retrieves the syntax definition associated with the attribute.
String | getID() Retrieves the id of this attribute.
boolean | isOrdered() Determines whether this attribute's values are ordered.
Object | remove(int ix) Removes an attribute value from the ordered list of attribute values.
boolean | remove(Object attrval) Removes a specified value from the attribute.
Object | set(int ix, Object attrVal) Sets an attribute value in the ordered list of attribute values.
int | size() Retrieves the number of values in this attribute.

Field Detail

serialVersionUID

static final long serialVersionUID
Use serialVersionUID from JNDI 1.1.1 for interoperability.

See Also:
Constant Field Values
Method Detail

getAll

NamingEnumeration<?> getAll()
                            throws NamingException
Retrieves an enumeration of the attribute's values. The behaviour of this enumeration is unspecified if the attribute's values are added, changed, or removed while the enumeration is in progress. If the attribute values are ordered, the enumeration's items will be ordered.

Returns:
A non-null enumeration of the attribute's values. Each element of the enumeration is a possibly null Object. The object's class is the class of the attribute value. The element is null if the attribute's value is null. If the attribute has zero values, an empty enumeration is returned.
Throws:
NamingException - If a naming exception was encountered while retrieving the values.
See Also:
isOrdered()

get

Object get()
           throws NamingException
Retrieves one of this attribute's values. If the attribute has more than one value and is unordered, any one of the values is returned. If the attribute has more than one value and is ordered, the first value is returned.

Returns:
A possibly null object representing one of the attribute's value. It is null if the attribute's value is null.
Throws:
NamingException - If a naming exception was encountered while retrieving the value.
NoSuchElementException - If this attribute has no values.

size

int size()
Retrieves the number of values in this attribute.

Returns:
The nonnegative number of values in this attribute.

getID

String getID()
Retrieves the id of this attribute.

Returns:
The id of this attribute. It cannot be null.

contains

boolean contains(Object attrVal)
Determines whether a value is in the attribute. Equality is determined by the implementation, which may use Object.equals() or schema information to determine equality.

Parameters:
attrVal - The possibly null value to check. If null, check whether the attribute has an attribute value whose value is null.
Returns:
true if attrVal is one of this attribute's values; false otherwise.
See Also:
Object.equals(java.lang.Object), BasicAttribute.equals(java.lang.Object)

add

boolean add(Object attrVal)
Adds a new value to the attribute. If the attribute values are unordered and attrVal is already in the attribute, this method does nothing. If the attribute values are ordered, attrVal is added to the end of the list of attribute values.

Equality is determined by the implementation, which may use Object.equals() or schema information to determine equality.

Parameters:
attrVal - The new possibly null value to add. If null, null is added as an attribute value.
Returns:
true if a value was added; false otherwise.

remove

boolean remove(Object attrval)
Removes a specified value from the attribute. If attrval is not in the attribute, this method does nothing. If the attribute values are ordered, the first occurrence of attrVal is removed and attribute values at indices greater than the removed value are shifted up towards the head of the list (and their indices decremented by one).

Equality is determined by the implementation, which may use Object.equals() or schema information to determine equality.

Parameters:
attrval - The possibly null value to remove from this attribute. If null, remove the attribute value that is null.
Returns:
true if the value was removed; false otherwise.

clear

void clear()
Removes all values from this attribute.

getAttributeSyntaxDefinition

DirContext getAttributeSyntaxDefinition()
                                        throws NamingException
Retrieves the syntax definition associated with the attribute. An attribute's syntax definition specifies the format of the attribute's value(s). Note that this is different from the attribute value's representation as a Java object. Syntax definition refers to the directory's notion of syntax.

For example, even though a value might be a Java String object, its directory syntax might be "Printable String" or "Telephone Number". Or a value might be a byte array, and its directory syntax is "JPEG" or "Certificate". For example, if this attribute's syntax is "JPEG", this method would return the syntax definition for "JPEG".

The information that you can retrieve from a syntax definition is directory-dependent.

If an implementation does not support schemas, it should throw OperationNotSupportedException. If an implementation does support schemas, it should define this method to return the appropriate information.

Returns:
The attribute's syntax definition. Null if the implementation supports schemas but this particular attribute does not have any schema information.
Throws:
OperationNotSupportedException - If getting the schema is not supported.
NamingException - If a naming exception occurs while getting the schema.

getAttributeDefinition

DirContext getAttributeDefinition()
                                  throws NamingException
Retrieves the attribute's schema definition. An attribute's schema definition contains information such as whether the attribute is multivalued or single-valued, the matching rules to use when comparing the attribute's values. The information that you can retrieve from an attribute definition is directory-dependent.

If an implementation does not support schemas, it should throw OperationNotSupportedException. If an implementation does support schemas, it should define this method to return the appropriate information.

Returns:
This attribute's schema definition. Null if the implementation supports schemas but this particular attribute does not have any schema information.
Throws:
OperationNotSupportedException - If getting the schema is not supported.
NamingException - If a naming exception occurs while getting the schema.

clone

Object clone()
Makes a copy of the attribute. The copy contains the same attribute values as the original attribute: the attribute values are not themselves cloned. Changes to the copy will not affect the original and vice versa.

Returns:
A non-null copy of the attribute.

isOrdered

boolean isOrdered()
Determines whether this attribute's values are ordered. If an attribute's values are ordered, duplicate values are allowed. If an attribute's values are unordered, they are presented in any order and there are no duplicate values.

Returns:
true if this attribute's values are ordered; false otherwise.
See Also:
get(int), remove(int), add(int, java.lang.Object), set(int, java.lang.Object)

get

Object get(int ix)
           throws NamingException
Retrieves the attribute value from the ordered list of attribute values. This method returns the value at the ix index of the list of attribute values. If the attribute values are unordered, this method returns the value that happens to be at that index.

Parameters:
ix - The index of the value in the ordered list of attribute values. 0 <= ix < size().
Returns:
The possibly null attribute value at index ix; null if the attribute value is null.
Throws:
NamingException - If a naming exception was encountered while retrieving the value.
IndexOutOfBoundsException - If ix is outside the specified range.

remove

Object remove(int ix)
Removes an attribute value from the ordered list of attribute values. This method removes the value at the ix index of the list of attribute values. If the attribute values are unordered, this method removes the value that happens to be at that index. Values located at indices greater than ix are shifted up towards the front of the list (and their indices decremented by one).

Parameters:
ix - The index of the value to remove. 0 <= ix < size().
Returns:
The possibly null attribute value at index ix that was removed; null if the attribute value is null.
Throws:
IndexOutOfBoundsException - If ix is outside the specified range.

add

void add(int ix,
         Object attrVal)
Adds an attribute value to the ordered list of attribute values. This method adds attrVal to the list of attribute values at index ix. Values located at indices at or greater than ix are shifted down towards the end of the list (and their indices incremented by one). If the attribute values are unordered and already have attrVal, IllegalStateException is thrown.

Parameters:
ix - The index in the ordered list of attribute values to add the new value. 0 <= ix <= size().
attrVal - The possibly null attribute value to add; if null, null is the value added.
Throws:
IndexOutOfBoundsException - If ix is outside the specified range.
IllegalStateException - If the attribute values are unordered and attrVal is one of those values.

set

Object set(int ix,
           Object attrVal)
Sets an attribute value in the ordered list of attribute values. This method sets the value at the ix index of the list of attribute values to be attrVal. The old value is removed. If the attribute values are unordered, this method sets the value that happens to be at that index to attrVal, unless attrVal is already one of the values. In that case, IllegalStateException is thrown.

Parameters:
ix - The index of the value in the ordered list of attribute values. 0 <= ix < size().
attrVal - The possibly null attribute value to use. If null, 'null' replaces the old value.
Returns:
The possibly null attribute value at index ix that was replaced. Null if the attribute value was null.
Throws:
IndexOutOfBoundsException - If ix is outside the specified range.
IllegalStateException - If attrVal already exists and the attribute values are unordered.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AttributeInUseException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Class AttributeInUseException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.directory.AttributeInUseException
All Implemented Interfaces:
Serializable
public class AttributeInUseException
extends NamingException

This exception is thrown when an operation attempts to add an attribute that already exists.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
DirContext.modifyAttributes(javax.naming.Name, int, javax.naming.directory.Attributes), Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
AttributeInUseException()
Constructs a new instance of AttributeInUseException.
AttributeInUseException(String explanation)
Constructs a new instance of AttributeInUseException with an explanation.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AttributeInUseException

public AttributeInUseException(String explanation)
Constructs a new instance of AttributeInUseException with an explanation. All other fields are set to null.

Parameters:
explanation - Possibly null additional detail about this exception.
See Also:
Throwable.getMessage()

AttributeInUseException

public AttributeInUseException()
Constructs a new instance of AttributeInUseException. All fields are initialized to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AttributeModificationException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Class AttributeModificationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.directory.AttributeModificationException
All Implemented Interfaces:
Serializable
public class AttributeModificationException
extends NamingException

This exception is thrown when an attempt is made to add, or remove, or modify an attribute, its identifier, or its values that conflicts with the attribute's (schema) definition or the attribute's state. It is thrown in response to DirContext.modifyAttributes(). It contains a list of modifications that have not been performed, in the order that they were supplied to modifyAttributes(). If the list is null, none of the modifications were performed successfully.

An AttributeModificationException instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify a single AttributeModification instance should lock the object.

Since:
1.3
See Also:
DirContext.modifyAttributes(javax.naming.Name, int, javax.naming.directory.Attributes), Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
AttributeModificationException()
Constructs a new instance of AttributeModificationException.
AttributeModificationException(String explanation)
Constructs a new instance of AttributeModificationException using an explanation.
Method Summary
ModificationItem[] | getUnexecutedModifications() Retrieves the unexecuted modification list.
void | setUnexecutedModifications(ModificationItem[] e) Sets the unexecuted modification list to be e.
String | toString() The string representation of this exception consists of information about where the error occurred, and the first unexecuted modification.
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AttributeModificationException

public AttributeModificationException(String explanation)
Constructs a new instance of AttributeModificationException using an explanation. All other fields are set to null.

Parameters:
explanation - Possibly null additional detail about this exception. If null, this exception has no detail message.
See Also:
Throwable.getMessage()

AttributeModificationException

public AttributeModificationException()
Constructs a new instance of AttributeModificationException. All fields are set to null.

Method Detail

setUnexecutedModifications

public void setUnexecutedModifications(ModificationItem[] e)
Sets the unexecuted modification list to be e. Items in the list must appear in the same order in which they were originally supplied in DirContext.modifyAttributes(). The first item in the list is the first one that was not executed. If this list is null, none of the operations originally submitted to modifyAttributes() were executed.

Parameters:
e - The possibly null list of unexecuted modifications.
See Also:
getUnexecutedModifications()

getUnexecutedModifications

public ModificationItem[] getUnexecutedModifications()
Retrieves the unexecuted modification list. Items in the list appear in the same order in which they were originally supplied in DirContext.modifyAttributes(). The first item in the list is the first one that was not executed. If this list is null, none of the operations originally submitted to modifyAttributes() were executed.

Returns:
The possibly null unexecuted modification list.
See Also:
setUnexecutedModifications(javax.naming.directory.ModificationItem[])

toString

public String toString()
The string representation of this exception consists of information about where the error occurred, and the first unexecuted modification. This string is meant for debugging and not mean to be interpreted programmatically.

Overrides:
toString in class NamingException
Returns:
The non-null string representation of this exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Attributes

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Interface Attributes

All Superinterfaces:
Cloneable, Serializable
All Known Implementing Classes:
BasicAttributes
public interface Attributes
extends Cloneable, Serializable

This interface represents a collection of attributes.

In a directory, named objects can have associated with them attributes. The Attributes interface represents a collection of attributes. For example, you can request from the directory the attributes associated with an object. Those attributes are returned in an object that implements the Attributes interface.

Attributes in an object that implements the Attributes interface are unordered. The object can have zero or more attributes. Attributes is either case-sensitive or case-insensitive (case-ignore). This property is determined at the time the Attributes object is created. (see BasicAttributes constructor for example). In a case-insensitive Attributes, the case of its attribute identifiers is ignored when searching for an attribute, or adding attributes. In a case-sensitive Attributes, the case is significant.

Note that updates to Attributes (such as adding or removing an attribute) do not affect the corresponding representation in the directory. Updates to the directory can only be effected using operations in the DirContext interface.

Since:
1.3
See Also:
DirContext.getAttributes(javax.naming.Name),
DirContext.modifyAttributes(javax.naming.Name, int, javax.naming.directory.Attributes),
DirContext.bind(javax.naming.Name, java.lang.Object, javax.naming.directory.Attributes),
DirContext.rebind(javax.naming.Name, java.lang.Object, javax.naming.directory.Attributes),
DirContext.createSubcontext(javax.naming.Name, javax.naming.directory.Attributes),
DirContext.search(javax.naming.Name, javax.naming.directory.Attributes, java.lang.String[]),
BasicAttributes

Method Summary
Object | clone() Makes a copy of the attribute set.
Attribute | get(String attrID) Retrieves the attribute with the given attribute id from the attribute set.
NamingEnumeration<? extends Attribute> | getAll() Retrieves an enumeration of the attributes in the attribute set.
NamingEnumeration<String> | getIDs() Retrieves an enumeration of the ids of the attributes in the attribute set.
boolean | isCaseIgnored() Determines whether the attribute set ignores the case of attribute identifiers when retrieving or adding attributes.
Attribute | put(Attribute attr) Adds a new attribute to the attribute set.
Attribute | put(String attrID, Object val) Adds a new attribute to the attribute set.
Attribute | remove(String attrID) Removes the attribute with the attribute id 'attrID' from the attribute set.
int | size() Retrieves the number of attributes in the attribute set.

Method Detail

isCaseIgnored

boolean isCaseIgnored()
Determines whether the attribute set ignores the case of attribute identifiers when retrieving or adding attributes.

Returns:
true if case is ignored; false otherwise.

size

int size()
Retrieves the number of attributes in the attribute set.

Returns:
The nonnegative number of attributes in this attribute set.

get

Attribute get(String attrID)
Retrieves the attribute with the given attribute id from the attribute set.

Parameters:
attrID - The non-null id of the attribute to retrieve. If this attribute set ignores the character case of its attribute ids, the case of attrID is ignored.
Returns:
The attribute identified by attrID; null if not found.
See Also:
put(java.lang.String, java.lang.Object), remove(java.lang.String)

getAll

NamingEnumeration<? extends Attribute> getAll()
Retrieves an enumeration of the attributes in the attribute set. The effects of updates to this attribute set on this enumeration are undefined.

Returns:
A non-null enumeration of the attributes in this attribute set. Each element of the enumeration is of class Attribute. If attribute set has zero attributes, an empty enumeration is returned.

getIDs

NamingEnumeration<String> getIDs()
Retrieves an enumeration of the ids of the attributes in the attribute set. The effects of updates to this attribute set on this enumeration are undefined.

Returns:
A non-null enumeration of the attributes' ids in this attribute set. Each element of the enumeration is of class String. If attribute set has zero attributes, an empty enumeration is returned.

put

Attribute put(String attrID,
              Object val)
Adds a new attribute to the attribute set.

Parameters:
attrID - non-null The id of the attribute to add. If the attribute set ignores the character case of its attribute ids, the case of attrID is ignored.
val - The possibly null value of the attribute to add. If null, the attribute does not have any values.
Returns:
The Attribute with attrID that was previous in this attribute set; null if no such attribute existed.
See Also:
remove(java.lang.String)

put

Attribute put(Attribute attr)
Adds a new attribute to the attribute set.

Parameters:
attr - The non-null attribute to add. If the attribute set ignores the character case of its attribute ids, the case of attr's identifier is ignored.
Returns:
The Attribute with the same ID as attr that was previous in this attribute set; null if no such attribute existed.
See Also:
remove(java.lang.String)

remove

Attribute remove(String attrID)
Removes the attribute with the attribute id 'attrID' from the attribute set. If the attribute does not exist, ignore.

Parameters:
attrID - The non-null id of the attribute to remove. If the attribute set ignores the character case of its attribute ids, the case of attrID is ignored.
Returns:
The Attribute with the same ID as attrID that was previous in the attribute set; null if no such attribute existed.

clone

Object clone()
Makes a copy of the attribute set. The new set contains the same attributes as the original set: the attributes are not themselves cloned. Changes to the copy will not affect the original and vice versa.

Returns:
A non-null copy of this attribute set.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicAttribute

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Class BasicAttribute

java.lang.Object
    extended by  javax.naming.directory.BasicAttribute
All Implemented Interfaces:
Serializable, Cloneable, Attribute
public class BasicAttribute
extends Object
implements Attribute

This class provides a basic implementation of the Attribute interface.

This implementation does not support the schema methods getAttributeDefinition() and getAttributeSyntaxDefinition(). They simply throw OperationNotSupportedException. Subclasses of BasicAttribute should override these methods if they support them.

The BasicAttribute class by default uses Object.equals() to determine equality of attribute values when testing for equality or when searching for values, except when the value is an array. For an array, each element of the array is checked using Object.equals(). Subclasses of BasicAttribute can make use of schema information when doing similar equality checks by overriding methods in which such use of schema is meaningful. Similarly, the BasicAttribute class by default returns the values passed to its constructor and/or manipulated using the add/remove methods. Subclasses of BasicAttribute can override get() and getAll() to get the values dynamically from the directory (or implement the Attribute interface directly instead of subclassing BasicAttribute).

Note that updates to BasicAttribute (such as adding or removing a value) does not affect the corresponding representation of the attribute in the directory. Updates to the directory can only be effected using operations in the DirContext interface.

A BasicAttribute instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify a BasicAttribute should lock the object.

Since:
1.3
See Also:
Serialized Form

Field Summary
protected String | attrID Holds the attribute's id.
protected boolean | ordered A flag for recording whether this attribute's values are ordered.
protected Vector<Object> | values Holds the attribute's values.
Constructor Summary
BasicAttribute(String id)
Constructs a new instance of an unordered attribute with no value.
BasicAttribute(String id, boolean ordered)
Constructs a new instance of a possibly ordered attribute with no value.
BasicAttribute(String id, Object value)
Constructs a new instance of an unordered attribute with a single value.
BasicAttribute(String id, Object value, boolean ordered)
Constructs a new instance of a possibly ordered attribute with a single value.
Method Summary
void | add(int ix, Object attrVal) Adds an attribute value to the ordered list of attribute values.
boolean | add(Object attrVal) Adds a new value to this attribute.
void | clear() Removes all values from this attribute.
Object | clone() Creates and returns a copy of this object.
boolean | contains(Object attrVal) Determines whether a value is in this attribute.
boolean | equals(Object obj) Determines whether obj is equal to this attribute.
Object | get() Retrieves one of this attribute's values.
Object | get(int ix) Retrieves the attribute value from the ordered list of attribute values.
NamingEnumeration<?> | getAll() Retrieves an enumeration of this attribute's values.
DirContext | getAttributeDefinition() Retrieves this attribute's schema definition.
DirContext | getAttributeSyntaxDefinition() Retrieves the syntax definition associated with this attribute.
String | getID() Retrieves the id of this attribute.
int | hashCode() Calculates the hash code of this attribute.
boolean | isOrdered() Determines whether this attribute's values are ordered.
Object | remove(int ix) Removes an attribute value from the ordered list of attribute values.
boolean | remove(Object attrval) Removes a specified value from this attribute.
Object | set(int ix, Object attrVal) Sets an attribute value in the ordered list of attribute values.
int | size() Retrieves the number of values in this attribute.
String | toString() Generates the string representation of this attribute.
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

attrID

protected String attrID
Holds the attribute's id. It is initialized by the public constructor and cannot be null unless methods in BasicAttribute that use attrID have been overridden.

values

protected transient Vector<Object> values
Holds the attribute's values. Initialized by public constructors. Cannot be null unless methods in BasicAttribute that use values have been overridden.

ordered

protected boolean ordered
A flag for recording whether this attribute's values are ordered.

Constructor Detail

BasicAttribute

public BasicAttribute(String id)
Constructs a new instance of an unordered attribute with no value.

Parameters:
id - The attribute's id. It cannot be null.

BasicAttribute

public BasicAttribute(String id,
                      Object value)
Constructs a new instance of an unordered attribute with a single value.

Parameters:
id - The attribute's id. It cannot be null.
value - The attribute's value. If null, a null value is added to the attribute.

BasicAttribute

public BasicAttribute(String id,
                      boolean ordered)
Constructs a new instance of a possibly ordered attribute with no value.

Parameters:
id - The attribute's id. It cannot be null.
ordered - true means the attribute's values will be ordered; false otherwise.

BasicAttribute

public BasicAttribute(String id,
                      Object value,
                      boolean ordered)
Constructs a new instance of a possibly ordered attribute with a single value.

Parameters:
id - The attribute's id. It cannot be null.
value - The attribute's value. If null, a null value is added to the attribute.
ordered - true means the attribute's values will be ordered; false otherwise.
Method Detail

clone

public Object clone()
Description copied from class: Object
Creates and returns a copy of this object. The precise meaning of "copy" may depend on the class of the object. The general intent is that, for any object x, the expression:
 x.clone() != x
will be true, and that the expression:
 x.clone().getClass() == x.getClass()
will be true, but these are not absolute requirements. While it is typically the case that:
 x.clone().equals(x)
will be true, this is not an absolute requirement.

By convention, the returned object should be obtained by calling super.clone. If a class and all of its superclasses (except Object) obey this convention, it will be the case that x.clone().getClass() == x.getClass().

By convention, the object returned by this method should be independent of this object (which is being cloned). To achieve this independence, it may be necessary to modify one or more fields of the object returned by super.clone before returning it. Typically, this means copying any mutable objects that comprise the internal "deep structure" of the object being cloned and replacing the references to these objects with references to the copies. If a class contains only primitive fields or references to immutable objects, then it is usually the case that no fields in the object returned by super.clone need to be modified.

The method clone for class Object performs a specific cloning operation. First, if the class of this object does not implement the interface Cloneable, then a CloneNotSupportedException is thrown. Note that all arrays are considered to implement the interface Cloneable. Otherwise, this method creates a new instance of the class of this object and initializes all its fields with exactly the contents of the corresponding fields of this object, as if by assignment; the contents of the fields are not themselves cloned. Thus, this method performs a "shallow copy" of this object, not a "deep copy" operation.

The class Object does not itself implement the interface Cloneable, so calling the clone method on an object whose class is Object will result in throwing an exception at run time.

Specified by:
clone in interface Attribute
Overrides:
clone in class Object
Returns:
a clone of this instance.
See Also:
Cloneable

equals

public boolean equals(Object obj)
Determines whether obj is equal to this attribute. Two attributes are equal if their attribute-ids, syntaxes and values are equal. If the attribute values are unordered, the order that the values were added are irrelevant. If the attribute values are ordered, then the order the values must match. If obj is null or not an Attribute, false is returned.

By default Object.equals() is used when comparing the attribute id and its values except when a value is an array. For an array, each element of the array is checked using Object.equals(). A subclass may override this to make use of schema syntax information and matching rules, which define what it means for two attributes to be equal. How and whether a subclass makes use of the schema information is determined by the subclass. If a subclass overrides equals(), it should also override hashCode() such that two attributes that are equal have the same hash code.

Overrides:
equals in class Object
Parameters:
obj - The possibly null object to check.
Returns:
true if obj is equal to this attribute; false otherwise.
See Also:
hashCode(), contains(java.lang.Object)

hashCode

public int hashCode()
Calculates the hash code of this attribute.

The hash code is computed by adding the hash code of the attribute's id and that of all of its values except for values that are arrays. For an array, the hash code of each element of the array is summed. If a subclass overrides hashCode(), it should override equals() as well so that two attributes that are equal have the same hash code.

Overrides:
hashCode in class Object
Returns:
an int representing the hash code of this attribute.
See Also:
equals(java.lang.Object)

toString

public String toString()
Generates the string representation of this attribute. The string consists of the attribute's id and its values. This string is meant for debugging and not meant to be interpreted programmatically.

Overrides:
toString in class Object
Returns:
The non-null string representation of this attribute.

getAll

public NamingEnumeration<?> getAll()
                            throws NamingException
Retrieves an enumeration of this attribute's values.

By default, the values returned are those passed to the constructor and/or manipulated using the add/replace/remove methods. A subclass may override this to retrieve the values dynamically from the directory.

Specified by:
getAll in interface Attribute
Returns:
A non-null enumeration of the attribute's values. Each element of the enumeration is a possibly null Object. The object's class is the class of the attribute value. The element is null if the attribute's value is null. If the attribute has zero values, an empty enumeration is returned.
Throws:
NamingException - If a naming exception was encountered while retrieving the values.
See Also:
Attribute.isOrdered()

get

public Object get()
           throws NamingException
Retrieves one of this attribute's values.

By default, the value returned is one of those passed to the constructor and/or manipulated using the add/replace/remove methods. A subclass may override this to retrieve the value dynamically from the directory.

Specified by:
get in interface Attribute
Returns:
A possibly null object representing one of the attribute's value. It is null if the attribute's value is null.
Throws:
NamingException - If a naming exception was encountered while retrieving the value.

size

public int size()
Description copied from interface: Attribute
Retrieves the number of values in this attribute.

Specified by:
size in interface Attribute
Returns:
The nonnegative number of values in this attribute.

getID

public String getID()
Description copied from interface: Attribute
Retrieves the id of this attribute.

Specified by:
getID in interface Attribute
Returns:
The id of this attribute. It cannot be null.

contains

public boolean contains(Object attrVal)
Determines whether a value is in this attribute.

By default, Object.equals() is used when comparing attrVal with this attribute's values except when attrVal is an array. For an array, each element of the array is checked using Object.equals(). A subclass may use schema information to determine equality.

Specified by:
contains in interface Attribute
Parameters:
attrVal - The possibly null value to check. If null, check whether the attribute has an attribute value whose value is null.
Returns:
true if attrVal is one of this attribute's values; false otherwise.
See Also:
Object.equals(java.lang.Object), equals(java.lang.Object)

add

public boolean add(Object attrVal)
Adds a new value to this attribute.

By default, Object.equals() is used when comparing attrVal with this attribute's values except when attrVal is an array. For an array, each element of the array is checked using Object.equals(). A subclass may use schema information to determine equality.

Specified by:
add in interface Attribute
Parameters:
attrVal - The new possibly null value to add. If null, null is added as an attribute value.
Returns:
true if a value was added; false otherwise.

remove

public boolean remove(Object attrval)
Removes a specified value from this attribute.

By default, Object.equals() is used when comparing attrVal with this attribute's values except when attrVal is an array. For an array, each element of the array is checked using Object.equals(). A subclass may use schema information to determine equality.

Specified by:
remove in interface Attribute
Parameters:
attrval - The possibly null value to remove from this attribute. If null, remove the attribute value that is null.
Returns:
true if the value was removed; false otherwise.

clear

public void clear()
Description copied from interface: Attribute
Removes all values from this attribute.

Specified by:
clear in interface Attribute

isOrdered

public boolean isOrdered()
Description copied from interface: Attribute
Determines whether this attribute's values are ordered. If an attribute's values are ordered, duplicate values are allowed. If an attribute's values are unordered, they are presented in any order and there are no duplicate values.

Specified by:
isOrdered in interface Attribute
Returns:
true if this attribute's values are ordered; false otherwise.
See Also:
Attribute.get(int),
Attribute.remove(int),
Attribute.add(int, java.lang.Object),
Attribute.set(int, java.lang.Object)

get

public Object get(int ix)
           throws NamingException
Description copied from interface: Attribute
Retrieves the attribute value from the ordered list of attribute values. This method returns the value at the ix index of the list of attribute values. If the attribute values are unordered, this method returns the value that happens to be at that index.

Specified by:
get in interface Attribute
Parameters:
ix - The index of the value in the ordered list of attribute values. 0 <= ix < size().
Returns:
The possibly null attribute value at index ix; null if the attribute value is null.
Throws:
NamingException - If a naming exception was encountered while retrieving the value.

remove

public Object remove(int ix)
Description copied from interface: Attribute
Removes an attribute value from the ordered list of attribute values. This method removes the value at the ix index of the list of attribute values. If the attribute values are unordered, this method removes the value that happens to be at that index. Values located at indices greater than ix are shifted up towards the front of the list (and their indices decremented by one).

Specified by:
remove in interface Attribute
Parameters:
ix - The index of the value to remove. 0 <= ix < size().
Returns:
The possibly null attribute value at index ix that was removed; null if the attribute value is null.

add

public void add(int ix,
                Object attrVal)
Description copied from interface: Attribute
Adds an attribute value to the ordered list of attribute values. This method adds attrVal to the list of attribute values at index ix. Values located at indices at or greater than ix are shifted down towards the end of the list (and their indices incremented by one). If the attribute values are unordered and already have attrVal, IllegalStateException is thrown.

Specified by:
add in interface Attribute
Parameters:
ix - The index in the ordered list of attribute values to add the new value. 0 <= ix <= size().
attrVal - The possibly null attribute value to add; if null, null is the value added.

set

public Object set(int ix,
                  Object attrVal)
Description copied from interface: Attribute
Sets an attribute value in the ordered list of attribute values. This method sets the value at the ix index of the list of attribute values to be attrVal. The old value is removed. If the attribute values are unordered, this method sets the value that happens to be at that index to attrVal, unless attrVal is already one of the values. In that case, IllegalStateException is thrown.

Specified by:
set in interface Attribute
Parameters:
ix - The index of the value in the ordered list of attribute values. 0 <= ix < size().
attrVal - The possibly null attribute value to use. If null, 'null' replaces the old value.
Returns:
The possibly null attribute value at index ix that was replaced. Null if the attribute value was null.

getAttributeSyntaxDefinition

public DirContext getAttributeSyntaxDefinition()
                                        throws NamingException
Retrieves the syntax definition associated with this attribute.

This method by default throws OperationNotSupportedException. A subclass should override this method if it supports schema.

Specified by:
getAttributeSyntaxDefinition in interface Attribute
Returns:
The attribute's syntax definition. Null if the implementation supports schemas but this particular attribute does not have any schema information.
Throws:
OperationNotSupportedException - If getting the schema is not supported.
NamingException - If a naming exception occurs while getting the schema.

getAttributeDefinition

public DirContext getAttributeDefinition()
                                  throws NamingException
Retrieves this attribute's schema definition.

This method by default throws OperationNotSupportedException. A subclass should override this method if it supports schema.

Specified by:
getAttributeDefinition in interface Attribute
Returns:
This attribute's schema definition. Null if the implementation supports schemas but this particular attribute does not have any schema information.
Throws:
OperationNotSupportedException - If getting the schema is not supported.
NamingException - If a naming exception occurs while getting the schema.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicAttributes

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Class BasicAttributes

java.lang.Object
    extended by  javax.naming.directory.BasicAttributes
All Implemented Interfaces:
Serializable, Cloneable, Attributes
public class BasicAttributes
extends Object
implements Attributes

This class provides a basic implementation of the Attributes interface.

BasicAttributes is either case-sensitive or case-insensitive (case-ignore). This property is determined at the time the BasicAttributes constructor is called. In a case-insensitive BasicAttributes, the case of its attribute identifiers is ignored when searching for an attribute, or adding attributes. In a case-sensitive BasicAttributes, the case is significant.

When the BasicAttributes class needs to create an Attribute, it uses BasicAttribute. There is no other dependency on BasicAttribute.

Note that updates to BasicAttributes (such as adding or removing an attribute) does not affect the corresponding representation in the directory. Updates to the directory can only be effected using operations in the DirContext interface.

A BasicAttributes instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify a single BasicAttributes instance should lock the object.

Since:
1.3
See Also:
DirContext.getAttributes(javax.naming.Name),
DirContext.modifyAttributes(javax.naming.Name, int, javax.naming.directory.Attributes),
DirContext.bind(javax.naming.Name, java.lang.Object, javax.naming.directory.Attributes),
DirContext.rebind(javax.naming.Name, java.lang.Object, javax.naming.directory.Attributes),
DirContext.createSubcontext(javax.naming.Name, javax.naming.directory.Attributes),
DirContext.search(javax.naming.Name, javax.naming.directory.Attributes, java.lang.String[]),
Serialized Form

Constructor Summary
BasicAttributes()
Constructs a new instance of Attributes.
BasicAttributes(boolean ignoreCase)
Constructs a new instance of Attributes.
BasicAttributes(String attrID, Object val)
Constructs a new instance of Attributes with one attribute.
BasicAttributes(String attrID, Object val, boolean ignoreCase)
Constructs a new instance of Attributes with one attribute.
Method Summary
Object | clone() Creates and returns a copy of this object.
boolean | equals(Object obj) Determines whether this BasicAttributes is equal to another Attributes Two Attributes are equal if they are both instances of Attributes, treat the case of attribute IDs the same way, and contain the same attributes.
Attribute | get(String attrID) Retrieves the attribute with the given attribute id from the attribute set.
NamingEnumeration<Attribute> | getAll() Retrieves an enumeration of the attributes in the attribute set.
NamingEnumeration<String> | getIDs() Retrieves an enumeration of the ids of the attributes in the attribute set.
int | hashCode() Calculates the hash code of this BasicAttributes.
boolean | isCaseIgnored() Determines whether the attribute set ignores the case of attribute identifiers when retrieving or adding attributes.
Attribute | put(Attribute attr) Adds a new attribute to the attribute set.
Attribute | put(String attrID, Object val) Adds a new attribute to the attribute set.
Attribute | remove(String attrID) Removes the attribute with the attribute id 'attrID' from the attribute set.
int | size() Retrieves the number of attributes in the attribute set.
String | toString() Generates the string representation of this attribute set.
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

BasicAttributes

public BasicAttributes()
Constructs a new instance of Attributes. The character case of attribute identifiers is significant when subsequently retrieving or adding attributes.

BasicAttributes

public BasicAttributes(boolean ignoreCase)
Constructs a new instance of Attributes. If ignoreCase is true, the character case of attribute identifiers is ignored; otherwise the case is significant.

Parameters:
ignoreCase - true means this attribute set will ignore the case of its attribute identifiers when retrieving or adding attributes; false means case is respected.

BasicAttributes

public BasicAttributes(String attrID,
                       Object val)
Constructs a new instance of Attributes with one attribute. The attribute specified by attrID and val are added to the newly created attribute. The character case of attribute identifiers is significant when subsequently retrieving or adding attributes.

Parameters:
attrID - non-null The id of the attribute to add.
val - The value of the attribute to add. If null, a null value is added to the attribute.

BasicAttributes

public BasicAttributes(String attrID,
                       Object val,
                       boolean ignoreCase)
Constructs a new instance of Attributes with one attribute. The attribute specified by attrID and val are added to the newly created attribute. If ignoreCase is true, the character case of attribute identifiers is ignored; otherwise the case is significant.

Parameters:
attrID - non-null The id of the attribute to add. If this attribute set ignores the character case of its attribute ids, the case of attrID is ignored.
val - The value of the attribute to add. If null, a null value is added to the attribute.
ignoreCase - true means this attribute set will ignore the case of its attribute identifiers when retrieving or adding attributes; false means case is respected.
Method Detail

clone

public Object clone()
Description copied from class: Object
Creates and returns a copy of this object. The precise meaning of "copy" may depend on the class of the object. The general intent is that, for any object x, the expression:
 x.clone() != x
will be true, and that the expression:
 x.clone().getClass() == x.getClass()
will be true, but these are not absolute requirements. While it is typically the case that:
 x.clone().equals(x)
will be true, this is not an absolute requirement.

By convention, the returned object should be obtained by calling super.clone. If a class and all of its superclasses (except Object) obey this convention, it will be the case that x.clone().getClass() == x.getClass().

By convention, the object returned by this method should be independent of this object (which is being cloned). To achieve this independence, it may be necessary to modify one or more fields of the object returned by super.clone before returning it. Typically, this means copying any mutable objects that comprise the internal "deep structure" of the object being cloned and replacing the references to these objects with references to the copies. If a class contains only primitive fields or references to immutable objects, then it is usually the case that no fields in the object returned by super.clone need to be modified.

The method clone for class Object performs a specific cloning operation. First, if the class of this object does not implement the interface Cloneable, then a CloneNotSupportedException is thrown. Note that all arrays are considered to implement the interface Cloneable. Otherwise, this method creates a new instance of the class of this object and initializes all its fields with exactly the contents of the corresponding fields of this object, as if by assignment; the contents of the fields are not themselves cloned. Thus, this method performs a "shallow copy" of this object, not a "deep copy" operation.

The class Object does not itself implement the interface Cloneable, so calling the clone method on an object whose class is Object will result in throwing an exception at run time.

Specified by:
clone in interface Attributes
Overrides:
clone in class Object
Returns:
a clone of this instance.
See Also:
Cloneable

isCaseIgnored

public boolean isCaseIgnored()
Description copied from interface: Attributes
Determines whether the attribute set ignores the case of attribute identifiers when retrieving or adding attributes.

Specified by:
isCaseIgnored in interface Attributes
Returns:
true if case is ignored; false otherwise.

size

public int size()
Description copied from interface: Attributes
Retrieves the number of attributes in the attribute set.

Specified by:
size in interface Attributes
Returns:
The nonnegative number of attributes in this attribute set.

get

public Attribute get(String attrID)
Description copied from interface: Attributes
Retrieves the attribute with the given attribute id from the attribute set.

Specified by:
get in interface Attributes
Parameters:
attrID - The non-null id of the attribute to retrieve. If this attribute set ignores the character case of its attribute ids, the case of attrID is ignored.
Returns:
The attribute identified by attrID; null if not found.
See Also:
Attributes.put(java.lang.String, java.lang.Object), Attributes.remove(java.lang.String)

getAll

public NamingEnumeration<Attribute> getAll()
Description copied from interface: Attributes
Retrieves an enumeration of the attributes in the attribute set. The effects of updates to this attribute set on this enumeration are undefined.

Specified by:
getAll in interface Attributes
Returns:
A non-null enumeration of the attributes in this attribute set. Each element of the enumeration is of class Attribute. If attribute set has zero attributes, an empty enumeration is returned.

getIDs

public NamingEnumeration<String> getIDs()
Description copied from interface: Attributes
Retrieves an enumeration of the ids of the attributes in the attribute set. The effects of updates to this attribute set on this enumeration are undefined.

Specified by:
getIDs in interface Attributes
Returns:
A non-null enumeration of the attributes' ids in this attribute set. Each element of the enumeration is of class String. If attribute set has zero attributes, an empty enumeration is returned.

put

public Attribute put(String attrID,
                     Object val)
Description copied from interface: Attributes
Adds a new attribute to the attribute set.

Specified by:
put in interface Attributes
Parameters:
attrID - non-null The id of the attribute to add. If the attribute set ignores the character case of its attribute ids, the case of attrID is ignored.
val - The possibly null value of the attribute to add. If null, the attribute does not have any values.
Returns:
The Attribute with attrID that was previous in this attribute set; null if no such attribute existed.
See Also:
Attributes.remove(java.lang.String)

put

public Attribute put(Attribute attr)
Description copied from interface: Attributes
Adds a new attribute to the attribute set.

Specified by:
put in interface Attributes
Parameters:
attr - The non-null attribute to add. If the attribute set ignores the character case of its attribute ids, the case of attr's identifier is ignored.
Returns:
The Attribute with the same ID as attr that was previous in this attribute set; null if no such attribute existed.
See Also:
Attributes.remove(java.lang.String)

remove

public Attribute remove(String attrID)
Description copied from interface: Attributes
Removes the attribute with the attribute id 'attrID' from the attribute set. If the attribute does not exist, ignore.

Specified by:
remove in interface Attributes
Parameters:
attrID - The non-null id of the attribute to remove. If the attribute set ignores the character case of its attribute ids, the case of attrID is ignored.
Returns:
The Attribute with the same ID as attrID that was previous in the attribute set; null if no such attribute existed.

toString

public String toString()
Generates the string representation of this attribute set. The string consists of each attribute identifier and the contents of each attribute. The contents of this string is useful for debugging and is not meant to be interpreted programmatically.

Overrides:
toString in class Object
Returns:
A non-null string listing the contents of this attribute set.

equals

public boolean equals(Object obj)
Determines whether this BasicAttributes is equal to another Attributes Two Attributes are equal if they are both instances of Attributes, treat the case of attribute IDs the same way, and contain the same attributes. Each Attribute in this BasicAttributes is checked for equality using Object.equals(), which may have be overridden by implementations of Attribute). If a subclass overrides equals(), it should override hashCode() as well so that two Attributes instances that are equal have the same hash code.

Overrides:
equals in class Object
Parameters:
obj - the possibly null object to compare against.
Returns:
true If obj is equal to this BasicAttributes.
See Also:
hashCode()

hashCode

public int hashCode()
Calculates the hash code of this BasicAttributes.

The hash code is computed by adding the hash code of the attributes of this object. If this BasicAttributes ignores case of its attribute IDs, one is added to the hash code. If a subclass overrides hashCode(), it should override equals() as well so that two Attributes instances that are equal have the same hash code.

Overrides:
hashCode in class Object
Returns:
an int representing the hash code of this BasicAttributes instance.
See Also:
equals(java.lang.Object)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.naming.directory.AttributeInUseException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.directory.AttributeInUseException

No usage of javax.naming.directory.AttributeInUseException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.directory.AttributeModificationException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.directory.AttributeModificationException

No usage of javax.naming.directory.AttributeModificationException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.directory.BasicAttribute

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.directory.BasicAttribute

No usage of javax.naming.directory.BasicAttribute

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.directory.BasicAttributes

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.directory.BasicAttributes

No usage of javax.naming.directory.BasicAttributes

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.directory.InitialDirContext

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.directory.InitialDirContext

Packages that use InitialDirContext
javax.naming.ldap Provides support for LDAPv3 extended operations and controls.

Uses of InitialDirContext in javax.naming.ldap

Subclasses of InitialDirContext in javax.naming.ldap
 class InitialLdapContext
This class is the starting context for performing LDAPv3-style extended operations and controls.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.directory.InvalidAttributeIdentifierException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.directory.InvalidAttributeIdentifierException

No usage of javax.naming.directory.InvalidAttributeIdentifierException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.directory.InvalidAttributesException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.directory.InvalidAttributesException

No usage of javax.naming.directory.InvalidAttributesException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.directory.InvalidAttributeValueException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.directory.InvalidAttributeValueException

No usage of javax.naming.directory.InvalidAttributeValueException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.directory.InvalidSearchControlsException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.directory.InvalidSearchControlsException

No usage of javax.naming.directory.InvalidSearchControlsException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.directory.InvalidSearchFilterException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.directory.InvalidSearchFilterException

No usage of javax.naming.directory.InvalidSearchFilterException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.directory.ModificationItem

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.directory.ModificationItem

Packages that use ModificationItem
javax.naming.directory Extends the javax.naming package to provide functionality for accessing directory services.

Uses of ModificationItem in javax.naming.directory

Methods in javax.naming.directory that return ModificationItem
 ModificationItem[] AttributeModificationException.getUnexecutedModifications()
Retrieves the unexecuted modification list.

Methods in javax.naming.directory with parameters of type ModificationItem
void | InitialDirContext.modifyAttributes(Name name, ModificationItem[] mods)
void | DirContext.modifyAttributes(Name name, ModificationItem[] mods) Modifies the attributes associated with a named object using an ordered list of modifications.
void | InitialDirContext.modifyAttributes(String name, ModificationItem[] mods)
void | DirContext.modifyAttributes(String name, ModificationItem[] mods) Modifies the attributes associated with a named object using an ordered list of modifications.
void | AttributeModificationException.setUnexecutedModifications(ModificationItem[] e) Sets the unexecuted modification list to be e.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.directory.NoSuchAttributeException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.directory.NoSuchAttributeException

No usage of javax.naming.directory.NoSuchAttributeException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.directory.SchemaViolationException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.directory.SchemaViolationException

No usage of javax.naming.directory.SchemaViolationException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.directory.SearchControls

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.directory.SearchControls

Packages that use SearchControls
javax.naming.directory | Extends the javax.naming package to provide functionality for accessing directory services.
javax.naming.event | Provides support for event notification when accessing naming and directory services.

Uses of SearchControls in javax.naming.directory

Methods in javax.naming.directory with parameters of type SearchControls
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, String filter, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(Name name, String filter, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | InitialDirContext.search(String name, String filterExpr, Object[] filterArgs, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(String name, String filterExpr, Object[] filterArgs, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | InitialDirContext.search(String name, String filter, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(String name, String filter, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.

Uses of SearchControls in javax.naming.event

Methods in javax.naming.event with parameters of type SearchControls
void | EventDirContext.addNamingListener(Name target, String filter, Object[] filterArgs, SearchControls ctls, NamingListener l) Adds a listener for receiving naming events fired when objects identified by the search filter filter and filter arguments at the object named by the target are modified.
void | EventDirContext.addNamingListener(Name target, String filter, SearchControls ctls, NamingListener l) Adds a listener for receiving naming events fired when objects identified by the search filter filter at the object named by target are modified.
void | EventDirContext.addNamingListener(String target, String filter, Object[] filterArgs, SearchControls ctls, NamingListener l) Adds a listener for receiving naming events fired when objects identified by the search filter filter and filter arguments at the object named by the string target name are modified.
void | EventDirContext.addNamingListener(String target, String filter, SearchControls ctls, NamingListener l) Adds a listener for receiving naming events fired when objects identified by the search filter filter at the object named by the string target name are modified.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.directory.SearchResult

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.directory.SearchResult

Packages that use SearchResult
javax.naming.directory Extends the javax.naming package to provide functionality for accessing directory services.

Uses of SearchResult in javax.naming.directory

Methods in javax.naming.directory that return types with arguments of type SearchResult
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, Attributes matchingAttributes)
NamingEnumeration<SearchResult> | DirContext.search(Name name, Attributes matchingAttributes) Searches in a single context for objects that contain a specified set of attributes.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, Attributes matchingAttributes, String[] attributesToReturn)
NamingEnumeration<SearchResult> | DirContext.search(Name name, Attributes matchingAttributes, String[] attributesToReturn) Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, String filter, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(Name name, String filter, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | InitialDirContext.search(String name, Attributes matchingAttributes)
NamingEnumeration<SearchResult> | DirContext.search(String name, Attributes matchingAttributes) Searches in a single context for objects that contain a specified set of attributes.
NamingEnumeration<SearchResult> | InitialDirContext.search(String name, Attributes matchingAttributes, String[] attributesToReturn)
NamingEnumeration<SearchResult> | DirContext.search(String name, Attributes matchingAttributes, String[] attributesToReturn) Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes.
NamingEnumeration<SearchResult> | InitialDirContext.search(String name, String filterExpr, Object[] filterArgs, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(String name, String filterExpr, Object[] filterArgs, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | InitialDirContext.search(String name, String filter, SearchControls cons)
NamingEnumeration<SearchResult> | DirContext.search(String name, String filter, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.directory.Attribute

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.directory.Attribute

Packages that use Attribute
javax.naming.directory Extends the javax.naming package to provide functionality for accessing directory services.

Uses of Attribute in javax.naming.directory

Classes in javax.naming.directory that implement Attribute
 class BasicAttribute
This class provides a basic implementation of the Attribute interface.

Methods in javax.naming.directory that return Attribute
Attribute | BasicAttributes.get(String attrID)
Attribute | Attributes.get(String attrID) Retrieves the attribute with the given attribute id from the attribute set.
Attribute | ModificationItem.getAttribute() Retrieves the attribute associated with this modification item.
Attribute | BasicAttributes.put(Attribute attr)
Attribute | Attributes.put(Attribute attr) Adds a new attribute to the attribute set.
Attribute | BasicAttributes.put(String attrID, Object val)
Attribute | Attributes.put(String attrID, Object val) Adds a new attribute to the attribute set.
Attribute | BasicAttributes.remove(String attrID)
Attribute | Attributes.remove(String attrID) Removes the attribute with the attribute id 'attrID' from the attribute set.

Methods in javax.naming.directory that return types with arguments of type Attribute
NamingEnumeration<Attribute> | BasicAttributes.getAll()
NamingEnumeration<? extends Attribute> | Attributes.getAll() Retrieves an enumeration of the attributes in the attribute set.

Methods in javax.naming.directory with parameters of type Attribute
Attribute | BasicAttributes.put(Attribute attr)
Attribute | Attributes.put(Attribute attr) Adds a new attribute to the attribute set.

Constructors in javax.naming.directory with parameters of type Attribute
ModificationItem(int mod_op, Attribute attr)
Creates a new instance of ModificationItem.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.directory.Attributes

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.directory.Attributes

Packages that use Attributes
javax.naming.directory | Extends the javax.naming package to provide functionality for accessing directory services.
javax.naming.ldap | Provides support for LDAPv3 extended operations and controls.
javax.naming.spi | Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.

Uses of Attributes in javax.naming.directory

Classes in javax.naming.directory that implement Attributes
 class BasicAttributes
This class provides a basic implementation of the Attributes interface.

Methods in javax.naming.directory that return Attributes
Attributes | SearchResult.getAttributes() Retrieves the attributes in this search result.
Attributes | InitialDirContext.getAttributes(Name name)
Attributes | DirContext.getAttributes(Name name) Retrieves all of the attributes associated with a named object.
Attributes | InitialDirContext.getAttributes(Name name, String[] attrIds)
Attributes | DirContext.getAttributes(Name name, String[] attrIds) Retrieves selected attributes associated with a named object.
Attributes | InitialDirContext.getAttributes(String name)
Attributes | DirContext.getAttributes(String name) Retrieves all of the attributes associated with a named object.
Attributes | InitialDirContext.getAttributes(String name, String[] attrIds)
Attributes | DirContext.getAttributes(String name, String[] attrIds) Retrieves selected attributes associated with a named object.

Methods in javax.naming.directory with parameters of type Attributes
void | InitialDirContext.bind(Name name, Object obj, Attributes attrs)
void | DirContext.bind(Name name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes.
void | InitialDirContext.bind(String name, Object obj, Attributes attrs)
void | DirContext.bind(String name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes.
DirContext | InitialDirContext.createSubcontext(Name name, Attributes attrs)
DirContext | DirContext.createSubcontext(Name name, Attributes attrs) Creates and binds a new context, along with associated attributes.
DirContext | InitialDirContext.createSubcontext(String name, Attributes attrs)
DirContext | DirContext.createSubcontext(String name, Attributes attrs) Creates and binds a new context, along with associated attributes.
void | InitialDirContext.modifyAttributes(Name name, int mod_op, Attributes attrs)
void | DirContext.modifyAttributes(Name name, int mod_op, Attributes attrs) Modifies the attributes associated with a named object.
void | InitialDirContext.modifyAttributes(String name, int mod_op, Attributes attrs)
void | DirContext.modifyAttributes(String name, int mod_op, Attributes attrs) Modifies the attributes associated with a named object.
void | InitialDirContext.rebind(Name name, Object obj, Attributes attrs)
void | DirContext.rebind(Name name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes, overwriting any existing binding.
void | InitialDirContext.rebind(String name, Object obj, Attributes attrs)
void | DirContext.rebind(String name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes, overwriting any existing binding.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, Attributes matchingAttributes)
NamingEnumeration<SearchResult> | DirContext.search(Name name, Attributes matchingAttributes) Searches in a single context for objects that contain a specified set of attributes.
NamingEnumeration<SearchResult> | InitialDirContext.search(Name name, Attributes matchingAttributes, String[] attributesToReturn)
NamingEnumeration<SearchResult> | DirContext.search(Name name, Attributes matchingAttributes, String[] attributesToReturn) Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes.
NamingEnumeration<SearchResult> | InitialDirContext.search(String name, Attributes matchingAttributes)
NamingEnumeration<SearchResult> | DirContext.search(String name, Attributes matchingAttributes) Searches in a single context for objects that contain a specified set of attributes.
NamingEnumeration<SearchResult> | InitialDirContext.search(String name, Attributes matchingAttributes, String[] attributesToReturn)
NamingEnumeration<SearchResult> | DirContext.search(String name, Attributes matchingAttributes, String[] attributesToReturn) Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes.
void | SearchResult.setAttributes(Attributes attrs) Sets the attributes of this search result to attrs.

Constructors in javax.naming.directory with parameters of type Attributes
SearchResult(String name, Object obj, Attributes attrs)
Constructs a search result using the result's name, its bound object, and its attributes.
SearchResult(String name, Object obj, Attributes attrs, boolean isRelative)
Constructs a search result using the result's name, its bound object, and its attributes, and whether the name is relative.
SearchResult(String name, String className, Object obj, Attributes attrs)
Constructs a search result using the result's name, its class name, its bound object, and its attributes.
SearchResult(String name, String className, Object obj, Attributes attrs, boolean isRelative)
Constructs a search result using the result's name, its class name, its bound object, its attributes, and whether the name is relative.

Uses of Attributes in javax.naming.ldap

Methods in javax.naming.ldap that return Attributes
 Attributes Rdn.toAttributes()
Retrieves the Attributes view of the type/value mappings contained in this Rdn.

Constructors in javax.naming.ldap with parameters of type Attributes
Rdn(Attributes attrSet)
Constructs an Rdn from the given attribute set.

Uses of Attributes in javax.naming.spi

Methods in javax.naming.spi that return Attributes
 Attributes DirStateFactory.Result.getAttributes()
Retrieves the attributes to be bound.

Methods in javax.naming.spi with parameters of type Attributes
static Object | DirectoryManager.getObjectInstance(Object refInfo, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes attrs) Creates an instance of an object for the specified object, attributes, and environment.
Object | DirObjectFactory.getObjectInstance(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes attrs) Creates an object using the location or reference information, and attributes specified.
static DirStateFactory.Result | DirectoryManager.getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes attrs) Retrieves the state of an object for binding when given the original object and its attributes.
DirStateFactory.Result | DirStateFactory.getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes inAttrs) Retrieves the state of an object for binding given the object and attributes to be transformed.

Constructors in javax.naming.spi with parameters of type Attributes
DirStateFactory.Result(Object obj, Attributes outAttrs)
Constructs an instance of Result.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.directory.DirContext

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.directory.DirContext

Packages that use DirContext
javax.naming.directory | Extends the javax.naming package to provide functionality for accessing directory services.
javax.naming.event | Provides support for event notification when accessing naming and directory services.
javax.naming.ldap | Provides support for LDAPv3 extended operations and controls.
javax.naming.spi | Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.

Uses of DirContext in javax.naming.directory

Classes in javax.naming.directory that implement DirContext
 class InitialDirContext
This class is the starting context for performing directory operations.

Methods in javax.naming.directory that return DirContext
DirContext | InitialDirContext.createSubcontext(Name name, Attributes attrs)
DirContext | DirContext.createSubcontext(Name name, Attributes attrs) Creates and binds a new context, along with associated attributes.
DirContext | InitialDirContext.createSubcontext(String name, Attributes attrs)
DirContext | DirContext.createSubcontext(String name, Attributes attrs) Creates and binds a new context, along with associated attributes.
DirContext | BasicAttribute.getAttributeDefinition() Retrieves this attribute's schema definition.
DirContext | Attribute.getAttributeDefinition() Retrieves the attribute's schema definition.
DirContext | BasicAttribute.getAttributeSyntaxDefinition() Retrieves the syntax definition associated with this attribute.
DirContext | Attribute.getAttributeSyntaxDefinition() Retrieves the syntax definition associated with the attribute.
DirContext | InitialDirContext.getSchema(Name name)
DirContext | DirContext.getSchema(Name name) Retrieves the schema associated with the named object.
DirContext | InitialDirContext.getSchema(String name)
DirContext | DirContext.getSchema(String name) Retrieves the schema associated with the named object.
DirContext | InitialDirContext.getSchemaClassDefinition(Name name)
DirContext | DirContext.getSchemaClassDefinition(Name name) Retrieves a context containing the schema objects of the named object's class definitions.
DirContext | InitialDirContext.getSchemaClassDefinition(String name)
DirContext | DirContext.getSchemaClassDefinition(String name) Retrieves a context containing the schema objects of the named object's class definitions.

Uses of DirContext in javax.naming.event

Subinterfaces of DirContext in javax.naming.event
 interface EventDirContext
Contains methods for registering listeners to be notified of events fired when objects named in a directory context changes.

Uses of DirContext in javax.naming.ldap

Subinterfaces of DirContext in javax.naming.ldap
 interface LdapContext
This interface represents a context in which you can perform operations with LDAPv3-style controls and perform LDAPv3-style extended operations.

Classes in javax.naming.ldap that implement DirContext
 class InitialLdapContext
This class is the starting context for performing LDAPv3-style extended operations and controls.

Uses of DirContext in javax.naming.spi

Methods in javax.naming.spi that return DirContext
static DirContext DirectoryManager.getContinuationDirContext(CannotProceedException cpe)
Creates a context in which to continue a DirContext operation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DirContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Interface DirContext

All Superinterfaces:
Context
All Known Subinterfaces:
EventDirContext, LdapContext
All Known Implementing Classes:
InitialDirContext, InitialLdapContext
public interface DirContext
extends Context

The directory service interface, containing methods for examining and updating attributes associated with objects, and for searching the directory.

Names

Each name passed as an argument to a DirContext method is relative to that context. The empty name is used to name the context itself. The name parameter may never be null.

Most of the methods have overloaded versions with one taking a Name parameter and one taking a String. These overloaded versions are equivalent in that if the Name and String parameters are just different representations of the same name, then the overloaded versions of the same methods behave the same. In the method descriptions below, only one version is documented. The second version instead has a link to the first: the same documentation applies to both.

See Context for a discussion on the interpretation of the name argument to the Context methods. These same rules apply to the name argument to the DirContext methods.

Attribute Models

There are two basic models of what attributes should be associated with. First, attributes may be directly associated with a DirContext object. In this model, an attribute operation on the named object is roughly equivalent to a lookup on the name (which returns the DirContext object), followed by the attribute operation invoked on the DirContext object in which the caller supplies an empty name. The attributes can be viewed as being stored along with the object (note that this does not imply that the implementation must do so).

The second model is that attributes are associated with a name (typically an atomic name) in a DirContext. In this model, an attribute operation on the named object is roughly equivalent to a lookup on the name of the parent DirContext of the named object, followed by the attribute operation invoked on the parent in which the caller supplies the terminal atomic name. The attributes can be viewed as being stored in the parent DirContext (again, this does not imply that the implementation must do so). Objects that are not DirContexts can have attributes, as long as their parents are DirContexts.

JNDI support both of these models. It is up to the individual service providers to decide where to "store" attributes. JNDI clients are safest when they do not make assumptions about whether an object's attributes are stored as part of the object, or stored within the parent object and associated with the object's name.

Attribute Type Names

In the getAttributes() and search() methods, you can supply the attributes to return by supplying a list of attribute names (strings). The attributes that you get back might not have the same names as the attribute names you have specified. This is because some directories support features that cause them to return other attributes. Such features include attribute subclassing, attribute name synonyms, and attribute language codes.

In attribute subclassing, attributes are defined in a class hierarchy. In some directories, for example, the "name" attribute might be the superclass of all name-related attributes, including "commonName" and "surName". Asking for the "name" attribute might return both the "commonName" and "surName" attributes.

With attribute type synonyms, a directory can assign multiple names to the same attribute. For example, "cn" and "commonName" might both refer to the same attribute. Asking for "cn" might return the "commonName" attribute.

Some directories support the language codes for attributes. Asking such a directory for the "description" attribute, for example, might return all of the following attributes:

  • description
  • description;lang-en
  • description;lang-de
  • description;lang-fr

Operational Attributes

Some directories have the notion of "operational attributes" which are attributes associated with a directory object for administrative purposes. An example of operational attributes is the access control list for an object.

In the getAttributes() and search() methods, you can specify that all attributes associated with the requested objects be returned by supply null as the list of attributes to return. The attributes returned do not include operational attributes. In order to retrieve operational attributes, you must name them explicitly.

Named Context

There are certain methods in which the name must resolve to a context (for example, when searching a single level context). The documentation of such methods use the term named context to describe their name parameter. For these methods, if the named object is not a DirContext, NotContextException is thrown. Aside from these methods, there is no requirement that the named object be a DirContext.

Parameters

An Attributes, SearchControls, or array object passed as a parameter to any method will not be modified by the service provider. The service provider may keep a reference to it for the duration of the operation, including any enumeration of the method's results and the processing of any referrals generated. The caller should not modify the object during this time. An Attributes object returned by any method is owned by the caller. The caller may subsequently modify it; the service provider will not.

Exceptions

All the methods in this interface can throw a NamingException or any of its subclasses. See NamingException and their subclasses for details on each exception.

Since:
1.3
See Also:
Context

Field Summary
static int | ADD_ATTRIBUTE This constant specifies to add an attribute with the specified values.
static int | REMOVE_ATTRIBUTE This constant specifies to delete the specified attribute values from the attribute.
static int | REPLACE_ATTRIBUTE This constant specifies to replace an attribute with specified values.
Fields inherited from interface javax.naming.Context
APPLET, AUTHORITATIVE, BATCHSIZE, DNS_URL, INITIAL_CONTEXT_FACTORY, LANGUAGE, OBJECT_FACTORIES, PROVIDER_URL, REFERRAL, SECURITY_AUTHENTICATION, SECURITY_CREDENTIALS, SECURITY_PRINCIPAL, SECURITY_PROTOCOL, STATE_FACTORIES, URL_PKG_PREFIXES
Method Summary
void | bind(Name name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes.
void | bind(String name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes.
DirContext | createSubcontext(Name name, Attributes attrs) Creates and binds a new context, along with associated attributes.
DirContext | createSubcontext(String name, Attributes attrs) Creates and binds a new context, along with associated attributes.
Attributes | getAttributes(Name name) Retrieves all of the attributes associated with a named object.
Attributes | getAttributes(Name name, String[] attrIds) Retrieves selected attributes associated with a named object.
Attributes | getAttributes(String name) Retrieves all of the attributes associated with a named object.
Attributes | getAttributes(String name, String[] attrIds) Retrieves selected attributes associated with a named object.
DirContext | getSchema(Name name) Retrieves the schema associated with the named object.
DirContext | getSchema(String name) Retrieves the schema associated with the named object.
DirContext | getSchemaClassDefinition(Name name) Retrieves a context containing the schema objects of the named object's class definitions.
DirContext | getSchemaClassDefinition(String name) Retrieves a context containing the schema objects of the named object's class definitions.
void | modifyAttributes(Name name, int mod_op, Attributes attrs) Modifies the attributes associated with a named object.
void | modifyAttributes(Name name, ModificationItem[] mods) Modifies the attributes associated with a named object using an ordered list of modifications.
void | modifyAttributes(String name, int mod_op, Attributes attrs) Modifies the attributes associated with a named object.
void | modifyAttributes(String name, ModificationItem[] mods) Modifies the attributes associated with a named object using an ordered list of modifications.
void | rebind(Name name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes, overwriting any existing binding.
void | rebind(String name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes, overwriting any existing binding.
NamingEnumeration<SearchResult> | search(Name name, Attributes matchingAttributes) Searches in a single context for objects that contain a specified set of attributes.
NamingEnumeration<SearchResult> | search(Name name, Attributes matchingAttributes, String[] attributesToReturn) Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes.
NamingEnumeration<SearchResult> | search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | search(Name name, String filter, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | search(String name, Attributes matchingAttributes) Searches in a single context for objects that contain a specified set of attributes.
NamingEnumeration<SearchResult> | search(String name, Attributes matchingAttributes, String[] attributesToReturn) Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes.
NamingEnumeration<SearchResult> | search(String name, String filterExpr, Object[] filterArgs, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | search(String name, String filter, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
Methods inherited from interface javax.naming.Context
addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getEnvironment, getNameInNamespace, getNameParser, getNameParser, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind

Field Detail

ADD_ATTRIBUTE

static final int ADD_ATTRIBUTE
This constant specifies to add an attribute with the specified values.

If attribute does not exist, create the attribute. The resulting attribute has a union of the specified value set and the prior value set. Adding an attribute with no value will throw InvalidAttributeValueException if the attribute must have at least one value. For a single-valued attribute where that attribute already exists, throws AttributeInUseException. If attempting to add more than one value to a single-valued attribute, throws InvalidAttributeValueException.

The value of this constant is 1.

See Also:
ModificationItem, modifyAttributes(javax.naming.Name, int, javax.naming.directory.Attributes), Constant Field Values

REPLACE_ATTRIBUTE

static final int REPLACE_ATTRIBUTE
This constant specifies to replace an attribute with specified values.

If attribute already exists, replaces all existing values with new specified values. If the attribute does not exist, creates it. If no value is specified, deletes all the values of the attribute. Removal of the last value will remove the attribute if the attribute is required to have at least one value. If attempting to add more than one value to a single-valued attribute, throws InvalidAttributeValueException.

The value of this constant is 2.

See Also:
ModificationItem, modifyAttributes(javax.naming.Name, int, javax.naming.directory.Attributes), Constant Field Values

REMOVE_ATTRIBUTE

static final int REMOVE_ATTRIBUTE
This constant specifies to delete the specified attribute values from the attribute.

The resulting attribute has the set difference of its prior value set and the specified value set. If no values are specified, deletes the entire attribute. If the attribute does not exist, or if some or all members of the specified value set do not exist, this absence may be ignored and the operation succeeds, or a NamingException may be thrown to indicate the absence. Removal of the last value will remove the attribute if the attribute is required to have at least one value.

The value of this constant is 3.

See Also:
ModificationItem, modifyAttributes(javax.naming.Name, int, javax.naming.directory.Attributes), Constant Field Values
Method Detail

getAttributes

Attributes getAttributes(Name name)
                         throws NamingException
Retrieves all of the attributes associated with a named object. See the class description regarding attribute models, attribute type names, and operational attributes.

Parameters:
name - the name of the object from which to retrieve attributes
Returns:
the set of attributes associated with name. Returns an empty attribute set if name has no attributes; never null.
Throws:
NamingException - if a naming exception is encountered
See Also:
getAttributes(String), getAttributes(Name, String[])

getAttributes

Attributes getAttributes(String name)
                         throws NamingException
Retrieves all of the attributes associated with a named object. See getAttributes(Name) for details.

Parameters:
name - the name of the object from which to retrieve attributes
Returns:
the set of attributes associated with name
Throws:
NamingException - if a naming exception is encountered

getAttributes

Attributes getAttributes(Name name,
                         String[] attrIds)
                         throws NamingException
Retrieves selected attributes associated with a named object. See the class description regarding attribute models, attribute type names, and operational attributes.

If the object does not have an attribute specified, the directory will ignore the nonexistent attribute and return those requested attributes that the object does have.

A directory might return more attributes than was requested (see Attribute Type Names in the class description), but is not allowed to return arbitrary, unrelated attributes.

See also Operational Attributes in the class description.

Parameters:
name - the name of the object from which to retrieve attributes
attrIds - the identifiers of the attributes to retrieve. null indicates that all attributes should be retrieved; an empty array indicates that none should be retrieved.
Returns:
the requested attributes; never null
Throws:
NamingException - if a naming exception is encountered

getAttributes

Attributes getAttributes(String name,
                         String[] attrIds)
                         throws NamingException
Retrieves selected attributes associated with a named object. See getAttributes(Name, String[]) for details.

Parameters:
name - The name of the object from which to retrieve attributes
attrIds - the identifiers of the attributes to retrieve. null indicates that all attributes should be retrieved; an empty array indicates that none should be retrieved.
Returns:
the requested attributes; never null
Throws:
NamingException - if a naming exception is encountered

modifyAttributes

void modifyAttributes(Name name,
                      int mod_op,
                      Attributes attrs)
                      throws NamingException
Modifies the attributes associated with a named object. The order of the modifications is not specified. Where possible, the modifications are performed atomically.

Parameters:
name - the name of the object whose attributes will be updated
mod_op - the modification operation, one of: ADD_ATTRIBUTE, REPLACE_ATTRIBUTE, REMOVE_ATTRIBUTE.
attrs - the attributes to be used for the modification; may not be null
Throws:
AttributeModificationException - if the modification cannot be completed successfully
NamingException - if a naming exception is encountered
See Also:
modifyAttributes(Name, ModificationItem[])

modifyAttributes

void modifyAttributes(String name,
                      int mod_op,
                      Attributes attrs)
                      throws NamingException
Modifies the attributes associated with a named object. See modifyAttributes(Name, int, Attributes) for details.

Parameters:
name - the name of the object whose attributes will be updated
mod_op - the modification operation, one of: ADD_ATTRIBUTE, REPLACE_ATTRIBUTE, REMOVE_ATTRIBUTE.
attrs - the attributes to be used for the modification; may not be null
Throws:
AttributeModificationException - if the modification cannot be completed successfully
NamingException - if a naming exception is encountered

modifyAttributes

void modifyAttributes(Name name,
                      ModificationItem[] mods)
                      throws NamingException
Modifies the attributes associated with a named object using an ordered list of modifications. The modifications are performed in the order specified. Each modification specifies a modification operation code and an attribute on which to operate. Where possible, the modifications are performed atomically.

Parameters:
name - the name of the object whose attributes will be updated
mods - an ordered sequence of modifications to be performed; may not be null
Throws:
AttributeModificationException - if the modifications cannot be completed successfully
NamingException - if a naming exception is encountered
See Also:
modifyAttributes(Name, int, Attributes), ModificationItem

modifyAttributes

void modifyAttributes(String name,
                      ModificationItem[] mods)
                      throws NamingException
Modifies the attributes associated with a named object using an ordered list of modifications. See modifyAttributes(Name, ModificationItem[]) for details.

Parameters:
name - the name of the object whose attributes will be updated
mods - an ordered sequence of modifications to be performed; may not be null
Throws:
AttributeModificationException - if the modifications cannot be completed successfully
NamingException - if a naming exception is encountered

bind

void bind(Name name,
          Object obj,
          Attributes attrs)
          throws NamingException
Binds a name to an object, along with associated attributes. If attrs is null, the resulting binding will have the attributes associated with obj if obj is a DirContext, and no attributes otherwise. If attrs is non-null, the resulting binding will have attrs as its attributes; any attributes associated with obj are ignored.

Parameters:
name - the name to bind; may not be empty
obj - the object to bind; possibly null
attrs - the attributes to associate with the binding
Throws:
NameAlreadyBoundException - if name is already bound
InvalidAttributesException - if some "mandatory" attributes of the binding are not supplied
NamingException - if a naming exception is encountered
See Also:
Context.bind(Name, Object), rebind(Name, Object, Attributes)

bind

void bind(String name,
          Object obj,
          Attributes attrs)
          throws NamingException
Binds a name to an object, along with associated attributes. See bind(Name, Object, Attributes) for details.

Parameters:
name - the name to bind; may not be empty
obj - the object to bind; possibly null
attrs - the attributes to associate with the binding
Throws:
NameAlreadyBoundException - if name is already bound
InvalidAttributesException - if some "mandatory" attributes of the binding are not supplied
NamingException - if a naming exception is encountered

rebind

void rebind(Name name,
            Object obj,
            Attributes attrs)
            throws NamingException
Binds a name to an object, along with associated attributes, overwriting any existing binding. If attrs is null and obj is a DirContext, the attributes from obj are used. If attrs is null and obj is not a DirContext, any existing attributes associated with the object already bound in the directory remain unchanged. If attrs is non-null, any existing attributes associated with the object already bound in the directory are removed and attrs is associated with the named object. If obj is a DirContext and attrs is non-null, the attributes of obj are ignored.

Parameters:
name - the name to bind; may not be empty
obj - the object to bind; possibly null
attrs - the attributes to associate with the binding
Throws:
InvalidAttributesException - if some "mandatory" attributes of the binding are not supplied
NamingException - if a naming exception is encountered
See Also:
Context.bind(Name, Object), bind(Name, Object, Attributes)

rebind

void rebind(String name,
            Object obj,
            Attributes attrs)
            throws NamingException
Binds a name to an object, along with associated attributes, overwriting any existing binding. See rebind(Name, Object, Attributes) for details.

Parameters:
name - the name to bind; may not be empty
obj - the object to bind; possibly null
attrs - the attributes to associate with the binding
Throws:
InvalidAttributesException - if some "mandatory" attributes of the binding are not supplied
NamingException - if a naming exception is encountered

createSubcontext

DirContext createSubcontext(Name name,
                            Attributes attrs)
                            throws NamingException
Creates and binds a new context, along with associated attributes. This method creates a new subcontext with the given name, binds it in the target context (that named by all but terminal atomic component of the name), and associates the supplied attributes with the newly created object. All intermediate and target contexts must already exist. If attrs is null, this method is equivalent to Context.createSubcontext().

Parameters:
name - the name of the context to create; may not be empty
attrs - the attributes to associate with the newly created context
Returns:
the newly created context
Throws:
NameAlreadyBoundException - if the name is already bound
InvalidAttributesException - if attrs does not contain all the mandatory attributes required for creation
NamingException - if a naming exception is encountered
See Also:
Context.createSubcontext(Name)

createSubcontext

DirContext createSubcontext(String name,
                            Attributes attrs)
                            throws NamingException
Creates and binds a new context, along with associated attributes. See createSubcontext(Name, Attributes) for details.

Parameters:
name - the name of the context to create; may not be empty
attrs - the attributes to associate with the newly created context
Returns:
the newly created context
Throws:
NameAlreadyBoundException - if the name is already bound
InvalidAttributesException - if attrs does not contain all the mandatory attributes required for creation
NamingException - if a naming exception is encountered

getSchema

DirContext getSchema(Name name)
                     throws NamingException
Retrieves the schema associated with the named object. The schema describes rules regarding the structure of the namespace and the attributes stored within it. The schema specifies what types of objects can be added to the directory and where they can be added; what mandatory and optional attributes an object can have. The range of support for schemas is directory-specific.

This method returns the root of the schema information tree that is applicable to the named object. Several named objects (or even an entire directory) might share the same schema.

Issues such as structure and contents of the schema tree, permission to modify to the contents of the schema tree, and the effect of such modifications on the directory are dependent on the underlying directory.

Parameters:
name - the name of the object whose schema is to be retrieved
Returns:
the schema associated with the context; never null
Throws:
OperationNotSupportedException - if schema not supported
NamingException - if a naming exception is encountered

getSchema

DirContext getSchema(String name)
                     throws NamingException
Retrieves the schema associated with the named object. See getSchema(Name) for details.

Parameters:
name - the name of the object whose schema is to be retrieved
Returns:
the schema associated with the context; never null
Throws:
OperationNotSupportedException - if schema not supported
NamingException - if a naming exception is encountered

getSchemaClassDefinition

DirContext getSchemaClassDefinition(Name name)
                                    throws NamingException
Retrieves a context containing the schema objects of the named object's class definitions.

One category of information found in directory schemas is class definitions. An "object class" definition specifies the object's type and what attributes (mandatory and optional) the object must/can have. Note that the term "object class" being referred to here is in the directory sense rather than in the Java sense. For example, if the named object is a directory object of "Person" class, getSchemaClassDefinition() would return a DirContext representing the (directory's) object class definition of "Person".

The information that can be retrieved from an object class definition is directory-dependent.

Prior to JNDI 1.2, this method returned a single schema object representing the class definition of the named object. Since JNDI 1.2, this method returns a DirContext containing all of the named object's class definitions.

Parameters:
name - the name of the object whose object class definition is to be retrieved
Returns:
the DirContext containing the named object's class definitions; never null
Throws:
OperationNotSupportedException - if schema not supported
NamingException - if a naming exception is encountered

getSchemaClassDefinition

DirContext getSchemaClassDefinition(String name)
                                    throws NamingException
Retrieves a context containing the schema objects of the named object's class definitions. See getSchemaClassDefinition(Name) for details.

Parameters:
name - the name of the object whose object class definition is to be retrieved
Returns:
the DirContext containing the named object's class definitions; never null
Throws:
OperationNotSupportedException - if schema not supported
NamingException - if a naming exception is encountered

search

NamingEnumeration<SearchResult> search(Name name,
                                       Attributes matchingAttributes,
                                       String[] attributesToReturn)
                                       throws NamingException
Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes. The search is performed using the default SearchControls settings.

For an object to be selected, each attribute in matchingAttributes must match some attribute of the object. If matchingAttributes is empty or null, all objects in the target context are returned.

An attribute A1 in matchingAttributes is considered to match an attribute A2 of an object if A1 and A2 have the same identifier, and each value of A1 is equal to some value of A2. This implies that the order of values is not significant, and that A2 may contain "extra" values not found in A1 without affecting the comparison. It also implies that if A1 has no values, then testing for a match is equivalent to testing for the presence of an attribute A2 with the same identifier.

The precise definition of "equality" used in comparing attribute values is defined by the underlying directory service. It might use the Object.equals method, for example, or might use a schema to specify a different equality operation. For matching based on operations other than equality (such as substring comparison) use the version of the search method that takes a filter argument.

When changes are made to this DirContext, the effect on enumerations returned by prior calls to this method is undefined.

If the object does not have the attribute specified, the directory will ignore the nonexistent attribute and return the requested attributes that the object does have.

A directory might return more attributes than was requested (see Attribute Type Names in the class description), but is not allowed to return arbitrary, unrelated attributes.

See also Operational Attributes in the class description.

Parameters:
name - the name of the context to search
matchingAttributes - the attributes to search for. If empty or null, all objects in the target context are returned.
attributesToReturn - the attributes to return. null indicates that all attributes are to be returned; an empty array indicates that none are to be returned.
Returns:
a non-null enumeration of SearchResult objects. Each SearchResult contains the attributes identified by attributesToReturn and the name of the corresponding object, named relative to the context named by name.
Throws:
NamingException - if a naming exception is encountered
See Also:
SearchControls, SearchResult, search(Name, String, Object[], SearchControls)

search

NamingEnumeration<SearchResult> search(String name,
                                       Attributes matchingAttributes,
                                       String[] attributesToReturn)
                                       throws NamingException
Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes. See search(Name, Attributes, String[]) for details.

Parameters:
name - the name of the context to search
matchingAttributes - the attributes to search for
attributesToReturn - the attributes to return
Returns:
a non-null enumeration of SearchResult objects
Throws:
NamingException - if a naming exception is encountered

search

NamingEnumeration<SearchResult> search(Name name,
                                       Attributes matchingAttributes)
                                       throws NamingException
Searches in a single context for objects that contain a specified set of attributes. This method returns all the attributes of such objects. It is equivalent to supplying null as the atributesToReturn parameter to the method search(Name, Attributes, String[]).
See search(Name, Attributes, String[]) for a full description.

Parameters:
name - the name of the context to search
matchingAttributes - the attributes to search for
Returns:
an enumeration of SearchResult objects
Throws:
NamingException - if a naming exception is encountered
See Also:
search(Name, Attributes, String[])

search

NamingEnumeration<SearchResult> search(String name,
                                       Attributes matchingAttributes)
                                       throws NamingException
Searches in a single context for objects that contain a specified set of attributes. See search(Name, Attributes) for details.

Parameters:
name - the name of the context to search
matchingAttributes - the attributes to search for
Returns:
an enumeration of SearchResult objects
Throws:
NamingException - if a naming exception is encountered

search

NamingEnumeration<SearchResult> search(Name name,
                                       String filter,
                                       SearchControls cons)
                                       throws NamingException
Searches in the named context or object for entries that satisfy the given search filter. Performs the search as specified by the search controls.

The format and interpretation of filter follows RFC 2254 with the following interpretations for attr and value mentioned in the RFC.

attr is the attribute's identifier.

value is the string representation the attribute's value. The translation of this string representation into the attribute's value is directory-specific.

For the assertion "someCount=127", for example, attr is "someCount" and value is "127". The provider determines, based on the attribute ID ("someCount") (and possibly its schema), that the attribute's value is an integer. It then parses the string "127" appropriately.

Any non-ASCII characters in the filter string should be represented by the appropriate Java (Unicode) characters, and not encoded as UTF-8 octets. Alternately, the "backslash-hexcode" notation described in RFC 2254 may be used.

If the directory does not support a string representation of some or all of its attributes, the form of search that accepts filter arguments in the form of Objects can be used instead. The service provider for such a directory would then translate the filter arguments to its service-specific representation for filter evaluation. See search(Name, String, Object[], SearchControls).

RFC 2254 defines certain operators for the filter, including substring matches, equality, approximate match, greater than, less than. These operators are mapped to operators with corresponding semantics in the underlying directory. For example, for the equals operator, suppose the directory has a matching rule defining "equality" of the attributes in the filter. This rule would be used for checking equality of the attributes specified in the filter with the attributes of objects in the directory. Similarly, if the directory has a matching rule for ordering, this rule would be used for making "greater than" and "less than" comparisons.

Not all of the operators defined in RFC 2254 are applicable to all attributes. When an operator is not applicable, the exception InvalidSearchFilterException is thrown.

The result is returned in an enumeration of SearchResults. Each SearchResult contains the name of the object and other information about the object (see SearchResult). The name is either relative to the target context of the search (which is named by the name parameter), or it is a URL string. If the target context is included in the enumeration (as is possible when cons specifies a search scope of SearchControls.OBJECT_SCOPE or SearchControls.SUBSTREE_SCOPE), its name is the empty string. The SearchResult may also contain attributes of the matching object if the cons argument specified that attributes be returned.

If the object does not have a requested attribute, that nonexistent attribute will be ignored. Those requested attributes that the object does have will be returned.

A directory might return more attributes than were requested (see Attribute Type Names in the class description) but is not allowed to return arbitrary, unrelated attributes.

See also Operational Attributes in the class description.

Parameters:
name - the name of the context or object to search
filter - the filter expression to use for the search; may not be null
cons - the search controls that control the search. If null, the default search controls are used (equivalent to (new SearchControls())).
Returns:
an enumeration of SearchResults of the objects that satisfy the filter; never null
Throws:
InvalidSearchFilterException - if the search filter specified is not supported or understood by the underlying directory
InvalidSearchControlsException - if the search controls contain invalid settings
NamingException - if a naming exception is encountered
See Also:
search(Name, String, Object[], SearchControls), SearchControls, SearchResult

search

NamingEnumeration<SearchResult> search(String name,
                                       String filter,
                                       SearchControls cons)
                                       throws NamingException
Searches in the named context or object for entries that satisfy the given search filter. Performs the search as specified by the search controls. See search(Name, String, SearchControls) for details.

Parameters:
name - the name of the context or object to search
filter - the filter expression to use for the search; may not be null
cons - the search controls that control the search. If null, the default search controls are used (equivalent to (new SearchControls())).
Returns:
an enumeration of SearchResults for the objects that satisfy the filter.
Throws:
InvalidSearchFilterException - if the search filter specified is not supported or understood by the underlying directory
InvalidSearchControlsException - if the search controls contain invalid settings
NamingException - if a naming exception is encountered

search

NamingEnumeration<SearchResult> search(Name name,
                                       String filterExpr,
                                       Object[] filterArgs,
                                       SearchControls cons)
                                       throws NamingException
Searches in the named context or object for entries that satisfy the given search filter. Performs the search as specified by the search controls.

The interpretation of filterExpr is based on RFC 2254. It may additionally contain variables of the form {i} -- where i is an integer -- that refer to objects in the filterArgs array. The interpretation of filterExpr is otherwise identical to that of the filter parameter of the method search(Name, String, SearchControls).

When a variable {i} appears in a search filter, it indicates that the filter argument filterArgs[i] is to be used in that place. Such variables may be used wherever an attr, value, or matchingrule production appears in the filter grammar of RFC 2254, section 4. When a string-valued filter argument is substituted for a variable, the filter is interpreted as if the string were given in place of the variable, with any characters having special significance within filters (such as '*') having been escaped according to the rules of RFC 2254.

For directories that do not use a string representation for some or all of their attributes, the filter argument corresponding to an attribute value may be of a type other than String. Directories that support unstructured binary-valued attributes, for example, should accept byte arrays as filter arguments. The interpretation (if any) of filter arguments of any other type is determined by the service provider for that directory, which maps the filter operations onto operations with corresponding semantics in the underlying directory.

This method returns an enumeration of the results. Each element in the enumeration contains the name of the object and other information about the object (see SearchResult). The name is either relative to the target context of the search (which is named by the name parameter), or it is a URL string. If the target context is included in the enumeration (as is possible when cons specifies a search scope of SearchControls.OBJECT_SCOPE or SearchControls.SUBSTREE_SCOPE), its name is the empty string.

The SearchResult may also contain attributes of the matching object if the cons argument specifies that attributes be returned.

If the object does not have a requested attribute, that nonexistent attribute will be ignored. Those requested attributes that the object does have will be returned.

A directory might return more attributes than were requested (see Attribute Type Names in the class description) but is not allowed to return arbitrary, unrelated attributes.

If a search filter with invalid variable substitutions is provided to this method, the result is undefined. When changes are made to this DirContext, the effect on enumerations returned by prior calls to this method is undefined.

See also Operational Attributes in the class description.

Parameters:
name - the name of the context or object to search
filterExpr - the filter expression to use for the search. The expression may contain variables of the form "{i}" where i is a nonnegative integer. May not be null.
filterArgs - the array of arguments to substitute for the variables in filterExpr. The value of filterArgs[i] will replace each occurrence of "{i}". If null, equivalent to an empty array.
cons - the search controls that control the search. If null, the default search controls are used (equivalent to (new SearchControls())).
Returns:
an enumeration of SearchResults of the objects that satisfy the filter; never null
Throws:
ArrayIndexOutOfBoundsException - if filterExpr contains {i} expressions where i is outside the bounds of the array filterArgs
InvalidSearchControlsException - if cons contains invalid settings
InvalidSearchFilterException - if filterExpr with filterArgs represents an invalid search filter
NamingException - if a naming exception is encountered
See Also:
search(Name, Attributes, String[]), MessageFormat

search

NamingEnumeration<SearchResult> search(String name,
                                       String filterExpr,
                                       Object[] filterArgs,
                                       SearchControls cons)
                                       throws NamingException
Searches in the named context or object for entries that satisfy the given search filter. Performs the search as specified by the search controls. See search(Name, String, Object[], SearchControls) for details.

Parameters:
name - the name of the context or object to search
filterExpr - the filter expression to use for the search. The expression may contain variables of the form "{i}" where i is a nonnegative integer. May not be null.
filterArgs - the array of arguments to substitute for the variables in filterExpr. The value of filterArgs[i] will replace each occurrence of "{i}". If null, equivalent to an empty array.
cons - the search controls that control the search. If null, the default search controls are used (equivalent to (new SearchControls())).
Returns:
an enumeration of SearchResults of the objects that satisfy the filter; never null
Throws:
ArrayIndexOutOfBoundsException - if filterExpr contains {i} expressions where i is outside the bounds of the array filterArgs
InvalidSearchControlsException - if cons contains invalid settings
InvalidSearchFilterException - if filterExpr with filterArgs represents an invalid search filter
NamingException - if a naming exception is encountered
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InitialDirContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Class InitialDirContext

java.lang.Object
    extended by  javax.naming.InitialContext
        extended by  javax.naming.directory.InitialDirContext
All Implemented Interfaces:
Context, DirContext
Direct Known Subclasses:
InitialLdapContext
public class InitialDirContext
extends InitialContext
implements DirContext

This class is the starting context for performing directory operations. The documentation in the class description of InitialContext (including those for synchronization) apply here.

Since:
1.3
See Also:
InitialContext

Field Summary
Fields inherited from class javax.naming.InitialContext
defaultInitCtx, gotDefault, myProps
Fields inherited from interface javax.naming.directory.DirContext
ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE
Fields inherited from interface javax.naming.Context
APPLET, AUTHORITATIVE, BATCHSIZE, DNS_URL, INITIAL_CONTEXT_FACTORY, LANGUAGE, OBJECT_FACTORIES, PROVIDER_URL, REFERRAL, SECURITY_AUTHENTICATION, SECURITY_CREDENTIALS, SECURITY_PRINCIPAL, SECURITY_PROTOCOL, STATE_FACTORIES, URL_PKG_PREFIXES
Constructor Summary
 | InitialDirContext() Constructs an initial DirContext.
protected | InitialDirContext(boolean lazy) Constructs an initial DirContext with the option of not initializing it.
 | InitialDirContext(Hashtable<?,?> environment) Constructs an initial DirContext using the supplied environment.
Method Summary
void | bind(Name name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes.
void | bind(String name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes.
DirContext | createSubcontext(Name name, Attributes attrs) Creates and binds a new context, along with associated attributes.
DirContext | createSubcontext(String name, Attributes attrs) Creates and binds a new context, along with associated attributes.
Attributes | getAttributes(Name name) Retrieves all of the attributes associated with a named object.
Attributes | getAttributes(Name name, String[] attrIds) Retrieves selected attributes associated with a named object.
Attributes | getAttributes(String name) Retrieves all of the attributes associated with a named object.
Attributes | getAttributes(String name, String[] attrIds) Retrieves selected attributes associated with a named object.
DirContext | getSchema(Name name) Retrieves the schema associated with the named object.
DirContext | getSchema(String name) Retrieves the schema associated with the named object.
DirContext | getSchemaClassDefinition(Name name) Retrieves a context containing the schema objects of the named object's class definitions.
DirContext | getSchemaClassDefinition(String name) Retrieves a context containing the schema objects of the named object's class definitions.
void | modifyAttributes(Name name, int mod_op, Attributes attrs) Modifies the attributes associated with a named object.
void | modifyAttributes(Name name, ModificationItem[] mods) Modifies the attributes associated with a named object using an ordered list of modifications.
void | modifyAttributes(String name, int mod_op, Attributes attrs) Modifies the attributes associated with a named object.
void | modifyAttributes(String name, ModificationItem[] mods) Modifies the attributes associated with a named object using an ordered list of modifications.
void | rebind(Name name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes, overwriting any existing binding.
void | rebind(String name, Object obj, Attributes attrs) Binds a name to an object, along with associated attributes, overwriting any existing binding.
NamingEnumeration<SearchResult> | search(Name name, Attributes matchingAttributes) Searches in a single context for objects that contain a specified set of attributes.
NamingEnumeration<SearchResult> | search(Name name, Attributes matchingAttributes, String[] attributesToReturn) Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes.
NamingEnumeration<SearchResult> | search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | search(Name name, String filter, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | search(String name, Attributes matchingAttributes) Searches in a single context for objects that contain a specified set of attributes.
NamingEnumeration<SearchResult> | search(String name, Attributes matchingAttributes, String[] attributesToReturn) Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes.
NamingEnumeration<SearchResult> | search(String name, String filterExpr, Object[] filterArgs, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
NamingEnumeration<SearchResult> | search(String name, String filter, SearchControls cons) Searches in the named context or object for entries that satisfy the given search filter.
Methods inherited from class javax.naming.InitialContext
addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, doLookup, doLookup, getDefaultInitCtx, getEnvironment, getNameInNamespace, getNameParser, getNameParser, getURLOrDefaultInitCtx, getURLOrDefaultInitCtx, init, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.naming.Context
addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getEnvironment, getNameInNamespace, getNameParser, getNameParser, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind

Constructor Detail

InitialDirContext

protected InitialDirContext(boolean lazy)
                     throws NamingException
Constructs an initial DirContext with the option of not initializing it. This may be used by a constructor in a subclass when the value of the environment parameter is not yet known at the time the InitialDirContext constructor is called. The subclass's constructor will call this constructor, compute the value of the environment, and then call init() before returning.

Parameters:
lazy - true means do not initialize the initial DirContext; false is equivalent to calling new InitialDirContext()
Throws:
NamingException - if a naming exception is encountered
Since:
1.3
See Also:
InitialContext.init(Hashtable)

InitialDirContext

public InitialDirContext()
                  throws NamingException
Constructs an initial DirContext. No environment properties are supplied. Equivalent to new InitialDirContext(null).

Throws:
NamingException - if a naming exception is encountered
See Also:
InitialDirContext(Hashtable)

InitialDirContext

public InitialDirContext(Hashtable<?,?> environment)
                  throws NamingException
Constructs an initial DirContext using the supplied environment. Environment properties are discussed in the javax.naming.InitialContext class description.

This constructor will not modify environment or save a reference to it, but may save a clone.

Parameters:
environment - environment used to create the initial DirContext. Null indicates an empty environment.
Throws:
NamingException - if a naming exception is encountered
Method Detail

getAttributes

public Attributes getAttributes(String name)
                         throws NamingException
Description copied from interface: DirContext
Retrieves all of the attributes associated with a named object. See DirContext.getAttributes(Name) for details.

Specified by:
getAttributes in interface DirContext
Parameters:
name - the name of the object from which to retrieve attributes
Returns:
the set of attributes associated with name
Throws:
NamingException - if a naming exception is encountered

getAttributes

public Attributes getAttributes(String name,
                                String[] attrIds)
                         throws NamingException
Description copied from interface: DirContext
Retrieves selected attributes associated with a named object. See DirContext.getAttributes(Name, String[]) for details.

Specified by:
getAttributes in interface DirContext
Parameters:
name - The name of the object from which to retrieve attributes
attrIds - the identifiers of the attributes to retrieve. null indicates that all attributes should be retrieved; an empty array indicates that none should be retrieved.
Returns:
the requested attributes; never null
Throws:
NamingException - if a naming exception is encountered

getAttributes

public Attributes getAttributes(Name name)
                         throws NamingException
Description copied from interface: DirContext
Retrieves all of the attributes associated with a named object. See the class description regarding attribute models, attribute type names, and operational attributes.

Specified by:
getAttributes in interface DirContext
Parameters:
name - the name of the object from which to retrieve attributes
Returns:
the set of attributes associated with name. Returns an empty attribute set if name has no attributes; never null.
Throws:
NamingException - if a naming exception is encountered
See Also:
DirContext.getAttributes(String), DirContext.getAttributes(Name, String[])

getAttributes

public Attributes getAttributes(Name name,
                                String[] attrIds)
                         throws NamingException
Description copied from interface: DirContext
Retrieves selected attributes associated with a named object. See the class description regarding attribute models, attribute type names, and operational attributes.

If the object does not have an attribute specified, the directory will ignore the nonexistent attribute and return those requested attributes that the object does have.

A directory might return more attributes than was requested (see Attribute Type Names in the class description), but is not allowed to return arbitrary, unrelated attributes.

See also Operational Attributes in the class description.

Specified by:
getAttributes in interface DirContext
Parameters:
name - the name of the object from which to retrieve attributes
attrIds - the identifiers of the attributes to retrieve. null indicates that all attributes should be retrieved; an empty array indicates that none should be retrieved.
Returns:
the requested attributes; never null
Throws:
NamingException - if a naming exception is encountered

modifyAttributes

public void modifyAttributes(String name,
                             int mod_op,
                             Attributes attrs)
                      throws NamingException
Description copied from interface: DirContext
Modifies the attributes associated with a named object. See DirContext.modifyAttributes(Name, int, Attributes) for details.

Specified by:
modifyAttributes in interface DirContext
Parameters:
name - the name of the object whose attributes will be updated
mod_op - the modification operation, one of: ADD_ATTRIBUTE, REPLACE_ATTRIBUTE, REMOVE_ATTRIBUTE.
attrs - the attributes to be used for the modification; may not be null
Throws:
AttributeModificationException - if the modification cannot be completed successfully
NamingException - if a naming exception is encountered

modifyAttributes

public void modifyAttributes(Name name,
                             int mod_op,
                             Attributes attrs)
                      throws NamingException
Description copied from interface: DirContext
Modifies the attributes associated with a named object. The order of the modifications is not specified. Where possible, the modifications are performed atomically.

Specified by:
modifyAttributes in interface DirContext
Parameters:
name - the name of the object whose attributes will be updated
mod_op - the modification operation, one of: ADD_ATTRIBUTE, REPLACE_ATTRIBUTE, REMOVE_ATTRIBUTE.
attrs - the attributes to be used for the modification; may not be null
Throws:
AttributeModificationException - if the modification cannot be completed successfully
NamingException - if a naming exception is encountered
See Also:
DirContext.modifyAttributes(Name, ModificationItem[])

modifyAttributes

public void modifyAttributes(String name,
                             ModificationItem[] mods)
                      throws NamingException
Description copied from interface: DirContext
Modifies the attributes associated with a named object using an ordered list of modifications. See DirContext.modifyAttributes(Name, ModificationItem[]) for details.

Specified by:
modifyAttributes in interface DirContext
Parameters:
name - the name of the object whose attributes will be updated
mods - an ordered sequence of modifications to be performed; may not be null
Throws:
AttributeModificationException - if the modifications cannot be completed successfully
NamingException - if a naming exception is encountered

modifyAttributes

public void modifyAttributes(Name name,
                             ModificationItem[] mods)
                      throws NamingException
Description copied from interface: DirContext
Modifies the attributes associated with a named object using an ordered list of modifications. The modifications are performed in the order specified. Each modification specifies a modification operation code and an attribute on which to operate. Where possible, the modifications are performed atomically.

Specified by:
modifyAttributes in interface DirContext
Parameters:
name - the name of the object whose attributes will be updated
mods - an ordered sequence of modifications to be performed; may not be null
Throws:
AttributeModificationException - if the modifications cannot be completed successfully
NamingException - if a naming exception is encountered
See Also:
DirContext.modifyAttributes(Name, int, Attributes), ModificationItem

bind

public void bind(String name,
                 Object obj,
                 Attributes attrs)
          throws NamingException
Description copied from interface: DirContext
Binds a name to an object, along with associated attributes. See DirContext.bind(Name, Object, Attributes) for details.

Specified by:
bind in interface DirContext
Parameters:
name - the name to bind; may not be empty
obj - the object to bind; possibly null
attrs - the attributes to associate with the binding
Throws:
NameAlreadyBoundException - if name is already bound
InvalidAttributesException - if some "mandatory" attributes of the binding are not supplied
NamingException - if a naming exception is encountered

bind

public void bind(Name name,
                 Object obj,
                 Attributes attrs)
          throws NamingException
Description copied from interface: DirContext
Binds a name to an object, along with associated attributes. If attrs is null, the resulting binding will have the attributes associated with obj if obj is a DirContext, and no attributes otherwise. If attrs is non-null, the resulting binding will have attrs as its attributes; any attributes associated with obj are ignored.

Specified by:
bind in interface DirContext
Parameters:
name - the name to bind; may not be empty
obj - the object to bind; possibly null
attrs - the attributes to associate with the binding
Throws:
NameAlreadyBoundException - if name is already bound
InvalidAttributesException - if some "mandatory" attributes of the binding are not supplied
NamingException - if a naming exception is encountered
See Also:
Context.bind(Name, Object), DirContext.rebind(Name, Object, Attributes)

rebind

public void rebind(String name,
                   Object obj,
                   Attributes attrs)
            throws NamingException
Description copied from interface: DirContext
Binds a name to an object, along with associated attributes, overwriting any existing binding. See DirContext.rebind(Name, Object, Attributes) for details.

Specified by:
rebind in interface DirContext
Parameters:
name - the name to bind; may not be empty
obj - the object to bind; possibly null
attrs - the attributes to associate with the binding
Throws:
InvalidAttributesException - if some "mandatory" attributes of the binding are not supplied
NamingException - if a naming exception is encountered

rebind

public void rebind(Name name,
                   Object obj,
                   Attributes attrs)
            throws NamingException
Description copied from interface: DirContext
Binds a name to an object, along with associated attributes, overwriting any existing binding. If attrs is null and obj is a DirContext, the attributes from obj are used. If attrs is null and obj is not a DirContext, any existing attributes associated with the object already bound in the directory remain unchanged. If attrs is non-null, any existing attributes associated with the object already bound in the directory are removed and attrs is associated with the named object. If obj is a DirContext and attrs is non-null, the attributes of obj are ignored.

Specified by:
rebind in interface DirContext
Parameters:
name - the name to bind; may not be empty
obj - the object to bind; possibly null
attrs - the attributes to associate with the binding
Throws:
InvalidAttributesException - if some "mandatory" attributes of the binding are not supplied
NamingException - if a naming exception is encountered
See Also:
Context.bind(Name, Object), DirContext.bind(Name, Object, Attributes)

createSubcontext

public DirContext createSubcontext(String name,
                                   Attributes attrs)
                            throws NamingException
Description copied from interface: DirContext
Creates and binds a new context, along with associated attributes. See DirContext.createSubcontext(Name, Attributes) for details.

Specified by:
createSubcontext in interface DirContext
Parameters:
name - the name of the context to create; may not be empty
attrs - the attributes to associate with the newly created context
Returns:
the newly created context
Throws:
NameAlreadyBoundException - if the name is already bound
InvalidAttributesException - if attrs does not contain all the mandatory attributes required for creation
NamingException - if a naming exception is encountered

createSubcontext

public DirContext createSubcontext(Name name,
                                   Attributes attrs)
                            throws NamingException
Description copied from interface: DirContext
Creates and binds a new context, along with associated attributes. This method creates a new subcontext with the given name, binds it in the target context (that named by all but terminal atomic component of the name), and associates the supplied attributes with the newly created object. All intermediate and target contexts must already exist. If attrs is null, this method is equivalent to Context.createSubcontext().

Specified by:
createSubcontext in interface DirContext
Parameters:
name - the name of the context to create; may not be empty
attrs - the attributes to associate with the newly created context
Returns:
the newly created context
Throws:
NameAlreadyBoundException - if the name is already bound
InvalidAttributesException - if attrs does not contain all the mandatory attributes required for creation
NamingException - if a naming exception is encountered
See Also:
Context.createSubcontext(Name)

getSchema

public DirContext getSchema(String name)
                     throws NamingException
Description copied from interface: DirContext
Retrieves the schema associated with the named object. See DirContext.getSchema(Name) for details.

Specified by:
getSchema in interface DirContext
Parameters:
name - the name of the object whose schema is to be retrieved
Returns:
the schema associated with the context; never null
Throws:
OperationNotSupportedException - if schema not supported
NamingException - if a naming exception is encountered

getSchema

public DirContext getSchema(Name name)
                     throws NamingException
Description copied from interface: DirContext
Retrieves the schema associated with the named object. The schema describes rules regarding the structure of the namespace and the attributes stored within it. The schema specifies what types of objects can be added to the directory and where they can be added; what mandatory and optional attributes an object can have. The range of support for schemas is directory-specific.

This method returns the root of the schema information tree that is applicable to the named object. Several named objects (or even an entire directory) might share the same schema.

Issues such as structure and contents of the schema tree, permission to modify to the contents of the schema tree, and the effect of such modifications on the directory are dependent on the underlying directory.

Specified by:
getSchema in interface DirContext
Parameters:
name - the name of the object whose schema is to be retrieved
Returns:
the schema associated with the context; never null
Throws:
OperationNotSupportedException - if schema not supported
NamingException - if a naming exception is encountered

getSchemaClassDefinition

public DirContext getSchemaClassDefinition(String name)
                                    throws NamingException
Description copied from interface: DirContext
Retrieves a context containing the schema objects of the named object's class definitions. See DirContext.getSchemaClassDefinition(Name) for details.

Specified by:
getSchemaClassDefinition in interface DirContext
Parameters:
name - the name of the object whose object class definition is to be retrieved
Returns:
the DirContext containing the named object's class definitions; never null
Throws:
OperationNotSupportedException - if schema not supported
NamingException - if a naming exception is encountered

getSchemaClassDefinition

public DirContext getSchemaClassDefinition(Name name)
                                    throws NamingException
Description copied from interface: DirContext
Retrieves a context containing the schema objects of the named object's class definitions.

One category of information found in directory schemas is class definitions. An "object class" definition specifies the object's type and what attributes (mandatory and optional) the object must/can have. Note that the term "object class" being referred to here is in the directory sense rather than in the Java sense. For example, if the named object is a directory object of "Person" class, getSchemaClassDefinition() would return a DirContext representing the (directory's) object class definition of "Person".

The information that can be retrieved from an object class definition is directory-dependent.

Prior to JNDI 1.2, this method returned a single schema object representing the class definition of the named object. Since JNDI 1.2, this method returns a DirContext containing all of the named object's class definitions.

Specified by:
getSchemaClassDefinition in interface DirContext
Parameters:
name - the name of the object whose object class definition is to be retrieved
Returns:
the DirContext containing the named object's class definitions; never null
Throws:
OperationNotSupportedException - if schema not supported
NamingException - if a naming exception is encountered

search

public NamingEnumeration<SearchResult> search(String name,
                                              Attributes matchingAttributes)
                                       throws NamingException
Description copied from interface: DirContext
Searches in a single context for objects that contain a specified set of attributes. See DirContext.search(Name, Attributes) for details.

Specified by:
search in interface DirContext
Parameters:
name - the name of the context to search
matchingAttributes - the attributes to search for
Returns:
an enumeration of SearchResult objects
Throws:
NamingException - if a naming exception is encountered

search

public NamingEnumeration<SearchResult> search(Name name,
                                              Attributes matchingAttributes)
                                       throws NamingException
Description copied from interface: DirContext
Searches in a single context for objects that contain a specified set of attributes. This method returns all the attributes of such objects. It is equivalent to supplying null as the atributesToReturn parameter to the method search(Name, Attributes, String[]).
See DirContext.search(Name, Attributes, String[]) for a full description.

Specified by:
search in interface DirContext
Parameters:
name - the name of the context to search
matchingAttributes - the attributes to search for
Returns:
an enumeration of SearchResult objects
Throws:
NamingException - if a naming exception is encountered
See Also:
DirContext.search(Name, Attributes, String[])

search

public NamingEnumeration<SearchResult> search(String name,
                                              Attributes matchingAttributes,
                                              String[] attributesToReturn)
                                       throws NamingException
Description copied from interface: DirContext
Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes. See DirContext.search(Name, Attributes, String[]) for details.

Specified by:
search in interface DirContext
Parameters:
name - the name of the context to search
matchingAttributes - the attributes to search for
attributesToReturn - the attributes to return
Returns:
a non-null enumeration of SearchResult objects
Throws:
NamingException - if a naming exception is encountered

search

public NamingEnumeration<SearchResult> search(Name name,
                                              Attributes matchingAttributes,
                                              String[] attributesToReturn)
                                       throws NamingException
Description copied from interface: DirContext
Searches in a single context for objects that contain a specified set of attributes, and retrieves selected attributes. The search is performed using the default SearchControls settings.

For an object to be selected, each attribute in matchingAttributes must match some attribute of the object. If matchingAttributes is empty or null, all objects in the target context are returned.

An attribute A1 in matchingAttributes is considered to match an attribute A2 of an object if A1 and A2 have the same identifier, and each value of A1 is equal to some value of A2. This implies that the order of values is not significant, and that A2 may contain "extra" values not found in A1 without affecting the comparison. It also implies that if A1 has no values, then testing for a match is equivalent to testing for the presence of an attribute A2 with the same identifier.

The precise definition of "equality" used in comparing attribute values is defined by the underlying directory service. It might use the Object.equals method, for example, or might use a schema to specify a different equality operation. For matching based on operations other than equality (such as substring comparison) use the version of the search method that takes a filter argument.

When changes are made to this DirContext, the effect on enumerations returned by prior calls to this method is undefined.

If the object does not have the attribute specified, the directory will ignore the nonexistent attribute and return the requested attributes that the object does have.

A directory might return more attributes than was requested (see Attribute Type Names in the class description), but is not allowed to return arbitrary, unrelated attributes.

See also Operational Attributes in the class description.

Specified by:
search in interface DirContext
Parameters:
name - the name of the context to search
matchingAttributes - the attributes to search for. If empty or null, all objects in the target context are returned.
attributesToReturn - the attributes to return. null indicates that all attributes are to be returned; an empty array indicates that none are to be returned.
Returns:
a non-null enumeration of SearchResult objects. Each SearchResult contains the attributes identified by attributesToReturn and the name of the corresponding object, named relative to the context named by name.
Throws:
NamingException - if a naming exception is encountered
See Also:
SearchControls, SearchResult, DirContext.search(Name, String, Object[], SearchControls)

search

public NamingEnumeration<SearchResult> search(String name,
                                              String filter,
                                              SearchControls cons)
                                       throws NamingException
Description copied from interface: DirContext
Searches in the named context or object for entries that satisfy the given search filter. Performs the search as specified by the search controls. See DirContext.search(Name, String, SearchControls) for details.

Specified by:
search in interface DirContext
Parameters:
name - the name of the context or object to search
filter - the filter expression to use for the search; may not be null
cons - the search controls that control the search. If null, the default search controls are used (equivalent to (new SearchControls())).
Returns:
an enumeration of SearchResults for the objects that satisfy the filter.
Throws:
InvalidSearchFilterException - if the search filter specified is not supported or understood by the underlying directory
InvalidSearchControlsException - if the search controls contain invalid settings
NamingException - if a naming exception is encountered

search

public NamingEnumeration<SearchResult> search(Name name,
                                              String filter,
                                              SearchControls cons)
                                       throws NamingException
Description copied from interface: DirContext
Searches in the named context or object for entries that satisfy the given search filter. Performs the search as specified by the search controls.

The format and interpretation of filter follows RFC 2254 with the following interpretations for attr and value mentioned in the RFC.

attr is the attribute's identifier.

value is the string representation the attribute's value. The translation of this string representation into the attribute's value is directory-specific.

For the assertion "someCount=127", for example, attr is "someCount" and value is "127". The provider determines, based on the attribute ID ("someCount") (and possibly its schema), that the attribute's value is an integer. It then parses the string "127" appropriately.

Any non-ASCII characters in the filter string should be represented by the appropriate Java (Unicode) characters, and not encoded as UTF-8 octets. Alternately, the "backslash-hexcode" notation described in RFC 2254 may be used.

If the directory does not support a string representation of some or all of its attributes, the form of search that accepts filter arguments in the form of Objects can be used instead. The service provider for such a directory would then translate the filter arguments to its service-specific representation for filter evaluation. See search(Name, String, Object[], SearchControls).

RFC 2254 defines certain operators for the filter, including substring matches, equality, approximate match, greater than, less than. These operators are mapped to operators with corresponding semantics in the underlying directory. For example, for the equals operator, suppose the directory has a matching rule defining "equality" of the attributes in the filter. This rule would be used for checking equality of the attributes specified in the filter with the attributes of objects in the directory. Similarly, if the directory has a matching rule for ordering, this rule would be used for making "greater than" and "less than" comparisons.

Not all of the operators defined in RFC 2254 are applicable to all attributes. When an operator is not applicable, the exception InvalidSearchFilterException is thrown.

The result is returned in an enumeration of SearchResults. Each SearchResult contains the name of the object and other information about the object (see SearchResult). The name is either relative to the target context of the search (which is named by the name parameter), or it is a URL string. If the target context is included in the enumeration (as is possible when cons specifies a search scope of SearchControls.OBJECT_SCOPE or SearchControls.SUBSTREE_SCOPE), its name is the empty string. The SearchResult may also contain attributes of the matching object if the cons argument specified that attributes be returned.

If the object does not have a requested attribute, that nonexistent attribute will be ignored. Those requested attributes that the object does have will be returned.

A directory might return more attributes than were requested (see Attribute Type Names in the class description) but is not allowed to return arbitrary, unrelated attributes.

See also Operational Attributes in the class description.

Specified by:
search in interface DirContext
Parameters:
name - the name of the context or object to search
filter - the filter expression to use for the search; may not be null
cons - the search controls that control the search. If null, the default search controls are used (equivalent to (new SearchControls())).
Returns:
an enumeration of SearchResults of the objects that satisfy the filter; never null
Throws:
InvalidSearchFilterException - if the search filter specified is not supported or understood by the underlying directory
InvalidSearchControlsException - if the search controls contain invalid settings
NamingException - if a naming exception is encountered
See Also:
DirContext.search(Name, String, Object[], SearchControls), SearchControls, SearchResult

search

public NamingEnumeration<SearchResult> search(String name,
                                              String filterExpr,
                                              Object[] filterArgs,
                                              SearchControls cons)
                                       throws NamingException
Description copied from interface: DirContext
Searches in the named context or object for entries that satisfy the given search filter. Performs the search as specified by the search controls. See DirContext.search(Name, String, Object[], SearchControls) for details.

Specified by:
search in interface DirContext
Parameters:
name - the name of the context or object to search
filterExpr - the filter expression to use for the search. The expression may contain variables of the form "{i}" where i is a nonnegative integer. May not be null.
filterArgs - the array of arguments to substitute for the variables in filterExpr. The value of filterArgs[i] will replace each occurrence of "{i}". If null, equivalent to an empty array.
cons - the search controls that control the search. If null, the default search controls are used (equivalent to (new SearchControls())).
Returns:
an enumeration of SearchResults of the objects that satisfy the filter; never null
Throws:
InvalidSearchControlsException - if cons contains invalid settings
InvalidSearchFilterException - if filterExpr with filterArgs represents an invalid search filter
NamingException - if a naming exception is encountered

search

public NamingEnumeration<SearchResult> search(Name name,
                                              String filterExpr,
                                              Object[] filterArgs,
                                              SearchControls cons)
                                       throws NamingException
Description copied from interface: DirContext
Searches in the named context or object for entries that satisfy the given search filter. Performs the search as specified by the search controls.

The interpretation of filterExpr is based on RFC 2254. It may additionally contain variables of the form {i} -- where i is an integer -- that refer to objects in the filterArgs array. The interpretation of filterExpr is otherwise identical to that of the filter parameter of the method search(Name, String, SearchControls).

When a variable {i} appears in a search filter, it indicates that the filter argument filterArgs[i] is to be used in that place. Such variables may be used wherever an attr, value, or matchingrule production appears in the filter grammar of RFC 2254, section 4. When a string-valued filter argument is substituted for a variable, the filter is interpreted as if the string were given in place of the variable, with any characters having special significance within filters (such as '*') having been escaped according to the rules of RFC 2254.

For directories that do not use a string representation for some or all of their attributes, the filter argument corresponding to an attribute value may be of a type other than String. Directories that support unstructured binary-valued attributes, for example, should accept byte arrays as filter arguments. The interpretation (if any) of filter arguments of any other type is determined by the service provider for that directory, which maps the filter operations onto operations with corresponding semantics in the underlying directory.

This method returns an enumeration of the results. Each element in the enumeration contains the name of the object and other information about the object (see SearchResult). The name is either relative to the target context of the search (which is named by the name parameter), or it is a URL string. If the target context is included in the enumeration (as is possible when cons specifies a search scope of SearchControls.OBJECT_SCOPE or SearchControls.SUBSTREE_SCOPE), its name is the empty string.

The SearchResult may also contain attributes of the matching object if the cons argument specifies that attributes be returned.

If the object does not have a requested attribute, that nonexistent attribute will be ignored. Those requested attributes that the object does have will be returned.

A directory might return more attributes than were requested (see Attribute Type Names in the class description) but is not allowed to return arbitrary, unrelated attributes.

If a search filter with invalid variable substitutions is provided to this method, the result is undefined. When changes are made to this DirContext, the effect on enumerations returned by prior calls to this method is undefined.

See also Operational Attributes in the class description.

Specified by:
search in interface DirContext
Parameters:
name - the name of the context or object to search
filterExpr - the filter expression to use for the search. The expression may contain variables of the form "{i}" where i is a nonnegative integer. May not be null.
filterArgs - the array of arguments to substitute for the variables in filterExpr. The value of filterArgs[i] will replace each occurrence of "{i}". If null, equivalent to an empty array.
cons - the search controls that control the search. If null, the default search controls are used (equivalent to (new SearchControls())).
Returns:
an enumeration of SearchResults of the objects that satisfy the filter; never null
Throws:
InvalidSearchControlsException - if cons contains invalid settings
InvalidSearchFilterException - if filterExpr with filterArgs represents an invalid search filter
NamingException - if a naming exception is encountered
See Also:
DirContext.search(Name, Attributes, String[]), MessageFormat
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidAttributeIdentifierException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Class InvalidAttributeIdentifierException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.directory.InvalidAttributeIdentifierException
All Implemented Interfaces:
Serializable
public class InvalidAttributeIdentifierException
extends NamingException

This exception is thrown when an attempt is made to add to create an attribute with an invalid attribute identifier. The validity of an attribute identifier is directory-specific.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
InvalidAttributeIdentifierException()
Constructs a new instance of InvalidAttributeIdentifierException.
InvalidAttributeIdentifierException(String explanation)
Constructs a new instance of InvalidAttributeIdentifierException using the explanation supplied.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidAttributeIdentifierException

public InvalidAttributeIdentifierException(String explanation)
Constructs a new instance of InvalidAttributeIdentifierException using the explanation supplied. All other fields set to null.

Parameters:
explanation - Possibly null string containing additional detail about this exception.
See Also:
Throwable.getMessage()

InvalidAttributeIdentifierException

public InvalidAttributeIdentifierException()
Constructs a new instance of InvalidAttributeIdentifierException. All fields are set to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidAttributesException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Class InvalidAttributesException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.directory.InvalidAttributesException
All Implemented Interfaces:
Serializable
public class InvalidAttributesException
extends NamingException

This exception is thrown when an attempt is made to add or modify an attribute set that has been specified incompletely or incorrectly. This could happen, for example, when attempting to add or modify a binding, or to create a new subcontext without specifying all the mandatory attributes required for creation of the object. Another situation in which this exception is thrown is by specification of incompatible attributes within the same attribute set, or attributes in conflict with that specified by the object's schema.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
InvalidAttributesException()
Constructs a new instance of InvalidAttributesException.
InvalidAttributesException(String explanation)
Constructs a new instance of InvalidAttributesException using an explanation.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidAttributesException

public InvalidAttributesException(String explanation)
Constructs a new instance of InvalidAttributesException using an explanation. All other fields are set to null.

Parameters:
explanation - Additional detail about this exception. Can be null.
See Also:
Throwable.getMessage()

InvalidAttributesException

public InvalidAttributesException()
Constructs a new instance of InvalidAttributesException. All fields are set to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidAttributeValueException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Class InvalidAttributeValueException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.directory.InvalidAttributeValueException
All Implemented Interfaces:
Serializable
public class InvalidAttributeValueException
extends NamingException

This class is thrown when an attempt is made to add to an attribute a value that conflicts with the attribute's schema definition. This could happen, for example, if attempting to add an attribute with no value when the attribute is required to have at least one value, or if attempting to add more than one value to a single valued-attribute, or if attempting to add a value that conflicts with the syntax of the attribute.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
InvalidAttributeValueException()
Constructs a new instance of InvalidAttributeValueException.
InvalidAttributeValueException(String explanation)
Constructs a new instance of InvalidAttributeValueException using an explanation.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidAttributeValueException

public InvalidAttributeValueException(String explanation)
Constructs a new instance of InvalidAttributeValueException using an explanation. All other fields are set to null.

Parameters:
explanation - Additional detail about this exception. Can be null.
See Also:
Throwable.getMessage()

InvalidAttributeValueException

public InvalidAttributeValueException()
Constructs a new instance of InvalidAttributeValueException. All fields are set to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidSearchControlsException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Class InvalidSearchControlsException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.directory.InvalidSearchControlsException
All Implemented Interfaces:
Serializable
public class InvalidSearchControlsException
extends NamingException

This exception is thrown when the specification of the SearchControls for a search operation is invalid. For example, if the scope is set to a value other than OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE, this exception is thrown.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
InvalidSearchControlsException()
Constructs a new instance of InvalidSearchControlsException.
InvalidSearchControlsException(String msg)
Constructs a new instance of InvalidSearchControlsException with an explanation.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidSearchControlsException

public InvalidSearchControlsException()
Constructs a new instance of InvalidSearchControlsException. All fields are set to null.

InvalidSearchControlsException

public InvalidSearchControlsException(String msg)
Constructs a new instance of InvalidSearchControlsException with an explanation. All other fields set to null.

Parameters:
msg - Detail about this exception. Can be null.
See Also:
Throwable.getMessage()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidSearchFilterException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Class InvalidSearchFilterException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.directory.InvalidSearchFilterException
All Implemented Interfaces:
Serializable
public class InvalidSearchFilterException
extends NamingException

This exception is thrown when the specification of a search filter is invalid. The expression of the filter may be invalid, or there may be a problem with one of the parameters passed to the filter.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
InvalidSearchFilterException()
Constructs a new instance of InvalidSearchFilterException.
InvalidSearchFilterException(String msg)
Constructs a new instance of InvalidSearchFilterException with an explanation.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidSearchFilterException

public InvalidSearchFilterException()
Constructs a new instance of InvalidSearchFilterException. All fields are set to null.

InvalidSearchFilterException

public InvalidSearchFilterException(String msg)
Constructs a new instance of InvalidSearchFilterException with an explanation. All other fields are set to null.

Parameters:
msg - Detail about this exception. Can be null.
See Also:
Throwable.getMessage()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ModificationItem

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Class ModificationItem

java.lang.Object
    extended by  javax.naming.directory.ModificationItem
All Implemented Interfaces:
Serializable
public class ModificationItem
extends Object
implements Serializable

This class represents a modification item. It consists of a modification code and an attribute on which to operate.

A ModificationItem instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify a single ModificationItem instance should lock the object.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
ModificationItem(int mod_op, Attribute attr)
Creates a new instance of ModificationItem.
Method Summary
Attribute | getAttribute() Retrieves the attribute associated with this modification item.
int | getModificationOp() Retrieves the modification code of this modification item.
String | toString() Generates the string representation of this modification item, which consists of the modification operation and its related attribute.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ModificationItem

public ModificationItem(int mod_op,
                        Attribute attr)
Creates a new instance of ModificationItem.

Parameters:
mod_op - Modification to apply. It must be one of: DirContext.ADD_ATTRIBUTE DirContext.REPLACE_ATTRIBUTE DirContext.REMOVE_ATTRIBUTE
attr - The non-null attribute to use for modification.
Throws:
IllegalArgumentException - If attr is null, or if mod_op is not one of the ones specified above.
Method Detail

getModificationOp

public int getModificationOp()
Retrieves the modification code of this modification item.

Returns:
The modification code. It is one of: DirContext.ADD_ATTRIBUTE DirContext.REPLACE_ATTRIBUTE DirContext.REMOVE_ATTRIBUTE

getAttribute

public Attribute getAttribute()
Retrieves the attribute associated with this modification item.

Returns:
The non-null attribute to use for the modification.

toString

public String toString()
Generates the string representation of this modification item, which consists of the modification operation and its related attribute. The string representation is meant for debugging and not to be interpreted programmatically.

Overrides:
toString in class Object
Returns:
The non-null string representation of this modification item.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NoSuchAttributeException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Class NoSuchAttributeException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.directory.NoSuchAttributeException
All Implemented Interfaces:
Serializable
public class NoSuchAttributeException
extends NamingException

This exception is thrown when attempting to access an attribute that does not exist.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
NoSuchAttributeException()
Constructs a new instance of NoSuchAttributeException.
NoSuchAttributeException(String explanation)
Constructs a new instance of NoSuchAttributeException using an explanation.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NoSuchAttributeException

public NoSuchAttributeException(String explanation)
Constructs a new instance of NoSuchAttributeException using an explanation. All other fields are set to null.

Parameters:
explanation - Additional detail about this exception. Can be null.
See Also:
Throwable.getMessage()

NoSuchAttributeException

public NoSuchAttributeException()
Constructs a new instance of NoSuchAttributeException. All fields are initialized to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SchemaViolationException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Class SchemaViolationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.directory.SchemaViolationException
All Implemented Interfaces:
Serializable
public class SchemaViolationException
extends NamingException

This exception is thrown when a method in some ways violates the schema. An example of schema violation is modifying attributes of an object that violates the object's schema definition. Another example is renaming or moving an object to a part of the namespace that violates the namespace's schema definition.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Context.bind(javax.naming.Name, java.lang.Object),
DirContext.bind(javax.naming.Name, java.lang.Object, javax.naming.directory.Attributes),
Context.rebind(javax.naming.Name, java.lang.Object),
DirContext.rebind(javax.naming.Name, java.lang.Object, javax.naming.directory.Attributes),
DirContext.createSubcontext(javax.naming.Name, javax.naming.directory.Attributes),
Context.createSubcontext(javax.naming.Name),
DirContext.modifyAttributes(javax.naming.Name, int, javax.naming.directory.Attributes),
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
SchemaViolationException()
Constructs a new instance of SchemaViolationException.
SchemaViolationException(String explanation)
Constructs a new instance of SchemaViolationException using the explanation supplied.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SchemaViolationException

public SchemaViolationException()
Constructs a new instance of SchemaViolationException. All fields are set to null.

SchemaViolationException

public SchemaViolationException(String explanation)
Constructs a new instance of SchemaViolationException using the explanation supplied. All other fields are set to null.

Parameters:
explanation - Detail about this exception. Can be null.
See Also:
Throwable.getMessage()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SearchControls

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Class SearchControls

java.lang.Object
    extended by  javax.naming.directory.SearchControls
All Implemented Interfaces:
Serializable
public class SearchControls
extends Object
implements Serializable

This class encapsulates factors that determine scope of search and what gets returned as a result of the search.

A SearchControls instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify a single SearchControls instance should lock the object.

Since:
1.3
See Also:
Serialized Form

Field Summary
static int | OBJECT_SCOPE Search the named object.
static int | ONELEVEL_SCOPE Search one level of the named context.
static int | SUBTREE_SCOPE Search the entire subtree rooted at the named object.
Constructor Summary
SearchControls()
Constructs a search constraints using defaults.
SearchControls(int scope, long countlim, int timelim, String[] attrs, boolean retobj, boolean deref)
Constructs a search constraints using arguments.
Method Summary
long | getCountLimit() Retrieves the maximum number of entries that will be returned as a result of the search.
boolean | getDerefLinkFlag() Determines whether links will be dereferenced during the search.
String[] | getReturningAttributes() Retrieves the attributes that will be returned as part of the search.
boolean | getReturningObjFlag() Determines whether objects will be returned as part of the result.
int | getSearchScope() Retrieves the search scope of these SearchControls.
int | getTimeLimit() Retrieves the time limit of these SearchControls in milliseconds.
void | setCountLimit(long limit) Sets the maximum number of entries to be returned as a result of the search.
void | setDerefLinkFlag(boolean on) Enables/disables link dereferencing during the search.
void | setReturningAttributes(String[] attrs) Specifies the attributes that will be returned as part of the search.
void | setReturningObjFlag(boolean on) Enables/disables returning objects returned as part of the result.
void | setSearchScope(int scope) Sets the search scope to one of: OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE.
void | setTimeLimit(int ms) Sets the time limit of these SearchControls in milliseconds.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OBJECT_SCOPE

public static final int OBJECT_SCOPE
Search the named object.

The NamingEnumeration that results from search() using OBJECT_SCOPE will contain one or zero element. The enumeration contains one element if the named object satisfies the search filter specified in search(). The element will have as its name the empty string because the names of elements in the NamingEnumeration are relative to the target context--in this case, the target context is the named object. It contains zero element if the named object does not satisfy the search filter specified in search().

The value of this constant is 0.

See Also:
Constant Field Values

ONELEVEL_SCOPE

public static final int ONELEVEL_SCOPE
Search one level of the named context.

The NamingEnumeration that results from search() using ONELEVEL_SCOPE contains elements with objects in the named context that satisfy the search filter specified in search(). The names of elements in the NamingEnumeration are atomic names relative to the named context.

The value of this constant is 1.

See Also:
Constant Field Values

SUBTREE_SCOPE

public static final int SUBTREE_SCOPE
Search the entire subtree rooted at the named object.

If the named object is not a DirContext, search only the object. If the named object is a DirContext, search the subtree rooted at the named object, including the named object itself.

The search will not cross naming system boundaries.

The NamingEnumeration that results from search() using SUBTREE_SCOPE contains elements of objects from the subtree (including the named context) that satisfy the search filter specified in search(). The names of elements in the NamingEnumeration are either relative to the named context or is a URL string. If the named context satisfies the search filter, it is included in the enumeration with the empty string as its name.

The value of this constant is 2.

See Also:
Constant Field Values
Constructor Detail

SearchControls

public SearchControls()
Constructs a search constraints using defaults.

The defaults are:

  • search one level
  • no maximum return limit for search results
  • no time limit for search
  • return all attributes associated with objects that satisfy the search filter.
  • do not return named object (return only name and class)
  • do not dereference links during search

SearchControls

public SearchControls(int scope,
                      long countlim,
                      int timelim,
                      String[] attrs,
                      boolean retobj,
                      boolean deref)
Constructs a search constraints using arguments.

Parameters:
scope - The search scope. One of: OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE.
timelim - The number of milliseconds to wait before returning. If 0, wait indefinitely.
deref - If true, dereference links during search.
countlim - The maximum number of entries to return. If 0, return all entries that satisfy filter.
retobj - If true, return the object bound to the name of the entry; if false, do not return object.
attrs - The identifiers of the attributes to return along with the entry. If null, return all attributes. If empty return no attributes.
Method Detail

getSearchScope

public int getSearchScope()
Retrieves the search scope of these SearchControls.

One of OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE.

Returns:
The search scope of this SearchControls.
See Also:
setSearchScope(int)

getTimeLimit

public int getTimeLimit()
Retrieves the time limit of these SearchControls in milliseconds.

If the value is 0, this means to wait indefinitely.

Returns:
The time limit of these SearchControls in milliseconds.
See Also:
setTimeLimit(int)

getDerefLinkFlag

public boolean getDerefLinkFlag()
Determines whether links will be dereferenced during the search.

Returns:
true if links will be dereferenced; false otherwise.
See Also:
setDerefLinkFlag(boolean)

getReturningObjFlag

public boolean getReturningObjFlag()
Determines whether objects will be returned as part of the result.

Returns:
true if objects will be returned; false otherwise.
See Also:
setReturningObjFlag(boolean)

getCountLimit

public long getCountLimit()
Retrieves the maximum number of entries that will be returned as a result of the search.

0 indicates that all entries will be returned.

Returns:
The maximum number of entries that will be returned.
See Also:
setCountLimit(long)

getReturningAttributes

public String[] getReturningAttributes()
Retrieves the attributes that will be returned as part of the search.

A value of null indicates that all attributes will be returned. An empty array indicates that no attributes are to be returned.

Returns:
An array of attribute ids identifying the attributes that will be returned. Can be null.
See Also:
setReturningAttributes(java.lang.String[])

setSearchScope

public void setSearchScope(int scope)
Sets the search scope to one of: OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE.

Parameters:
scope - The search scope of this SearchControls.
See Also:
getSearchScope()

setTimeLimit

public void setTimeLimit(int ms)
Sets the time limit of these SearchControls in milliseconds.

If the value is 0, this means to wait indefinitely.

Parameters:
ms - The time limit of these SearchControls in milliseconds.
See Also:
getTimeLimit()

setDerefLinkFlag

public void setDerefLinkFlag(boolean on)
Enables/disables link dereferencing during the search.

Parameters:
on - if true links will be dereferenced; if false, not followed.
See Also:
getDerefLinkFlag()

setReturningObjFlag

public void setReturningObjFlag(boolean on)
Enables/disables returning objects returned as part of the result.

If disabled, only the name and class of the object is returned. If enabled, the object will be returned.

Parameters:
on - if true, objects will be returned; if false, objects will not be returned.
See Also:
getReturningObjFlag()

setCountLimit

public void setCountLimit(long limit)
Sets the maximum number of entries to be returned as a result of the search.

0 indicates no limit: all entries will be returned.

Parameters:
limit - The maximum number of entries that will be returned.
See Also:
getCountLimit()

setReturningAttributes

public void setReturningAttributes(String[] attrs)
Specifies the attributes that will be returned as part of the search.

null indicates that all attributes will be returned. An empty array indicates no attributes are returned.

Parameters:
attrs - An array of attribute ids identifying the attributes that will be returned. Can be null.
See Also:
getReturningAttributes()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SearchResult

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.naming.directory
Class SearchResult

java.lang.Object
    extended by  javax.naming.NameClassPair
        extended by  javax.naming.Binding
            extended by  javax.naming.directory.SearchResult
All Implemented Interfaces:
Serializable
public class SearchResult
extends Binding

This class represents an item in the NamingEnumeration returned as a result of the DirContext.search() methods.

A SearchResult instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify a single SearchResult instance should lock the object.

Since:
1.3
See Also:
DirContext.search(javax.naming.Name, javax.naming.directory.Attributes, java.lang.String[]), Serialized Form

Constructor Summary
SearchResult(String name, Object obj, Attributes attrs)
Constructs a search result using the result's name, its bound object, and its attributes.
SearchResult(String name, Object obj, Attributes attrs, boolean isRelative)
Constructs a search result using the result's name, its bound object, and its attributes, and whether the name is relative.
SearchResult(String name, String className, Object obj, Attributes attrs)
Constructs a search result using the result's name, its class name, its bound object, and its attributes.
SearchResult(String name, String className, Object obj, Attributes attrs, boolean isRelative)
Constructs a search result using the result's name, its class name, its bound object, its attributes, and whether the name is relative.
Method Summary
Attributes | getAttributes() Retrieves the attributes in this search result.
void | setAttributes(Attributes attrs) Sets the attributes of this search result to attrs.
String | toString() Generates the string representation of this SearchResult.
Methods inherited from class javax.naming.Binding
getClassName, getObject, setObject
Methods inherited from class javax.naming.NameClassPair
getName, getNameInNamespace, isRelative, setClassName, setName, setNameInNamespace, setRelative
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SearchResult

public SearchResult(String name,
                    Object obj,
                    Attributes attrs)
Constructs a search result using the result's name, its bound object, and its attributes.

getClassName() will return the class name of obj (or null if obj is null) unless the class name has been explicitly set using setClassName().

Parameters:
name - The non-null name of the search item. It is relative to the target context of the search (which is named by the first parameter of the search() method)
obj - The object bound to name. Can be null.
attrs - The attributes that were requested to be returned with this search item. Cannot be null.
See Also:
NameClassPair.setClassName(java.lang.String), NameClassPair.getClassName()

SearchResult

public SearchResult(String name,
                    Object obj,
                    Attributes attrs,
                    boolean isRelative)
Constructs a search result using the result's name, its bound object, and its attributes, and whether the name is relative.

getClassName() will return the class name of obj (or null if obj is null) unless the class name has been explicitly set using setClassName()

Parameters:
name - The non-null name of the search item.
obj - The object bound to name. Can be null.
attrs - The attributes that were requested to be returned with this search item. Cannot be null.
isRelative - true if name is relative to the target context of the search (which is named by the first parameter of the search() method); false if name is a URL string.
See Also:
NameClassPair.setClassName(java.lang.String), NameClassPair.getClassName()

SearchResult

public SearchResult(String name,
                    String className,
                    Object obj,
                    Attributes attrs)
Constructs a search result using the result's name, its class name, its bound object, and its attributes.

Parameters:
name - The non-null name of the search item. It is relative to the target context of the search (which is named by the first parameter of the search() method)
className - The possibly null class name of the object bound to name. If null, the class name of obj is returned by getClassName(). If obj is also null, getClassName() will return null.
obj - The object bound to name. Can be null.
attrs - The attributes that were requested to be returned with this search item. Cannot be null.
See Also:
NameClassPair.setClassName(java.lang.String), NameClassPair.getClassName()

SearchResult

public SearchResult(String name,
                    String className,
                    Object obj,
                    Attributes attrs,
                    boolean isRelative)
Constructs a search result using the result's name, its class name, its bound object, its attributes, and whether the name is relative.

Parameters:
name - The non-null name of the search item.
className - The possibly null class name of the object bound to name. If null, the class name of obj is returned by getClassName(). If obj is also null, getClassName() will return null.
obj - The object bound to name. Can be null.
attrs - The attributes that were requested to be returned with this search item. Cannot be null.
isRelative - true if name is relative to the target context of the search (which is named by the first parameter of the search() method); false if name is a URL string.
See Also:
NameClassPair.setClassName(java.lang.String), NameClassPair.getClassName()
Method Detail

getAttributes

public Attributes getAttributes()
Retrieves the attributes in this search result.

Returns:
The non-null attributes in this search result. Can be empty.
See Also:
setAttributes(javax.naming.directory.Attributes)

setAttributes

public void setAttributes(Attributes attrs)
Sets the attributes of this search result to attrs.

Parameters:
attrs - The non-null attributes to use. Can be empty.
See Also:
getAttributes()

toString

public String toString()
Generates the string representation of this SearchResult. The string representation consists of the string representation of the binding and the string representation of this search result's attributes, separated by ':'. The contents of this string is useful for debugging and is not meant to be interpreted programmatically.

Overrides:
toString in class Binding
Returns:
The string representation of this SearchResult. Cannot be null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


event

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.naming.event

Provides support for event notification when accessing naming and directory services.

See:
Description

Interface Summary
EventContext | Contains methods for registering/deregistering listeners to be notified of events fired when objects named in a context changes.
EventDirContext | Contains methods for registering listeners to be notified of events fired when objects named in a directory context changes.
NamespaceChangeListener | Specifies the methods that a listener interested in namespace changes must implement.
NamingListener | This interface is the root of listener interfaces that handle NamingEvents.
ObjectChangeListener | Specifies the method that a listener of a NamingEvent with event type of OBJECT_CHANGED must implement.

Class Summary
NamingEvent | This class represents an event fired by a naming/directory service.
NamingExceptionEvent | This class represents an event fired when the procedures/processes used to collect information for notifying listeners of NamingEvents threw a NamingException.

Package javax.naming.event Description

Provides support for event notification when accessing naming and directory services.

This package defines the event notification operations of the Java Naming and Directory InterfaceTM (JNDI). JNDI provides naming and directory functionality to applications written in the Java programming language. It is designed to be independent of any specific naming or directory service implementation. Thus a variety of services--new, emerging, and already deployed ones--can be accessed in a common way.

Naming Events

This package defines a NamingEvent class to represent an event that is generated by a naming/directory service. It also defines subinterfaces of Context and DirContext, called EventContext and EventDirContext, through which applications can register their interest in events fired by the context.

NamingEvent represents an event that occurs in a naming or directory service. There are two categories of naming events:

  • Those that affect the namespace (add/remove/rename an object)
  • Those that affect the objects' contents.
Each category of events is handled by a corresponding listener: NamespaceChangeListener, ObjectChangeListener.

An application, for example, can register its interest in changes to objects in a context as follows:

EventContext src =
    (EventContext)(new InitialContext()).lookup("o=wiz,c=us");
src.addNamingListener("ou=users", EventContext.ONELEVEL_SCOPE,
    new ChangeHandler());
...
class ChangeHandler implements ObjectChangeListener {
    public void objectChanged(NamingEvent evt) {
        System.out.println(evt.getNewBinding());
    }
    public void namingExceptionThrown(NamingExceptionEvent evt) {
        System.out.println(evt.getException());
    }
}

Threading Issues

When an event is dispatched to a listener, the listener method (such as objectChanged()) may be executed in a thread other than the one in which the call to addNamingListener() was executed. The choice of which thread to use is made by the service provider. When an event is dispatched to multiple listeners, the service provider may choose (and is generally encouraged) to execute the listener methods concurrently in separate threads.

When a listener instance invokes NamingEvent.getEventContext(), it must take into account the possibility that other threads will be working with that context concurrently. Likewise, when a listener is registered via addNamingListener(), the registering thread must take into account the likely possibility that the service provider will later invoke the listeners in newly-created threads. As Context instances are not guaranteed to be thread-safe in general, all context operations must be synchronized as needed.

Exception Handling

When a listener registers for events with a context, the context might need to do some internal processing in order to collect information required to generate the events. The context, for example, might need to make a request to the server to register interest in changes on the server that will eventually be translated into events. If an exception occurs that prevents information about the events from being collected, the listener will never be notified of the events. When such an exception occurs, a NamingExceptionEvent is fired to notify the listener. The listener's namingExceptionThrown() method is invoked, as shown in the sample code above, and the listener is automatically deregistered.

Package Specification

The JNDI API Specification and related documents can be found in the JNDI documentation.

Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.naming.event Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.naming.event

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.util.EventObject (implements java.io.Serializable)
      • javax.naming.event.NamingEvent
      • javax.naming.event.NamingExceptionEvent

Interface Hierarchy

  • javax.naming.Context
    • javax.naming.directory.DirContext
      • javax.naming.event.EventDirContext (also extends javax.naming.event.EventContext)
    • javax.naming.event.EventContext
      • javax.naming.event.EventDirContext (also extends javax.naming.directory.DirContext)
  • java.util.EventListener
    • javax.naming.event.NamingListener
      • javax.naming.event.NamespaceChangeListener
      • javax.naming.event.ObjectChangeListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.naming.event

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.naming.event

Packages that use javax.naming.event
javax.naming.event | Provides support for event notification when accessing naming and directory services.
javax.naming.ldap | Provides support for LDAPv3 extended operations and controls.

Classes in javax.naming.event used by javax.naming.event
EventContext
Contains methods for registering/deregistering listeners to be notified of events fired when objects named in a context changes.
NamingEvent
This class represents an event fired by a naming/directory service.
NamingExceptionEvent
This class represents an event fired when the procedures/processes used to collect information for notifying listeners of NamingEvents threw a NamingException.
NamingListener
This interface is the root of listener interfaces that handle NamingEvents.

Classes in javax.naming.event used by javax.naming.ldap
NamingListener
This interface is the root of listener interfaces that handle NamingEvents.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.event.NamingEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.event.NamingEvent

Packages that use NamingEvent
javax.naming.event Provides support for event notification when accessing naming and directory services.

Uses of NamingEvent in javax.naming.event

Methods in javax.naming.event with parameters of type NamingEvent
void | NamespaceChangeListener.objectAdded(NamingEvent evt) Called when an object has been added.
void | ObjectChangeListener.objectChanged(NamingEvent evt) Called when an object has been changed.
void | NamespaceChangeListener.objectRemoved(NamingEvent evt) Called when an object has been removed.
void | NamespaceChangeListener.objectRenamed(NamingEvent evt) Called when an object has been renamed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.event.NamingExceptionEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.event.NamingExceptionEvent

Packages that use NamingExceptionEvent
javax.naming.event Provides support for event notification when accessing naming and directory services.

Uses of NamingExceptionEvent in javax.naming.event

Methods in javax.naming.event with parameters of type NamingExceptionEvent
 void NamingListener.namingExceptionThrown(NamingExceptionEvent evt)
Called when a naming exception is thrown while attempting to fire a NamingEvent.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.event.EventContext

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.event.EventContext

Packages that use EventContext
javax.naming.event Provides support for event notification when accessing naming and directory services.

Uses of EventContext in javax.naming.event

Subinterfaces of EventContext in javax.naming.event
 interface EventDirContext
Contains methods for registering listeners to be notified of events fired when objects named in a directory context changes.

Methods in javax.naming.event that return EventContext
EventContext | NamingEvent.getEventContext() Retrieves the event source that fired this event.
EventContext | NamingExceptionEvent.getEventContext() Retrieves the EventContext that fired this event.

Constructors in javax.naming.event with parameters of type EventContext
NamingEvent(EventContext source, int type, Binding newBd, Binding oldBd, Object changeInfo)
Constructs an instance of NamingEvent.
NamingExceptionEvent(EventContext source, NamingException exc)
Constructs an instance of NamingExceptionEvent using the context in which the NamingException was thrown and the exception that was thrown.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.event.EventDirContext

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.event.EventDirContext

No usage of javax.naming.event.EventDirContext

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.event.NamespaceChangeListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.event.NamespaceChangeListener

No usage of javax.naming.event.NamespaceChangeListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.event.NamingListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.event.NamingListener

Packages that use NamingListener
javax.naming.event | Provides support for event notification when accessing naming and directory services.
javax.naming.ldap | Provides support for LDAPv3 extended operations and controls.

Uses of NamingListener in javax.naming.event

Subinterfaces of NamingListener in javax.naming.event
interface | NamespaceChangeListener Specifies the methods that a listener interested in namespace changes must implement.
interface | ObjectChangeListener Specifies the method that a listener of a NamingEvent with event type of OBJECT_CHANGED must implement.

Methods in javax.naming.event with parameters of type NamingListener
 void EventContext.addNamingListener(Name target, int scope, NamingListener l)
Adds a listener for receiving naming events fired when the object(s) identified by a target and scope changes.
 void EventDirContext.addNamingListener(Name target, String filter, Object[] filterArgs, SearchControls ctls, NamingListener l)
Adds a listener for receiving naming events fired when objects identified by the search filter filter and filter arguments at the object named by the target are modified.
 void EventDirContext.addNamingListener(Name target, String filter, SearchControls ctls, NamingListener l)
Adds a listener for receiving naming events fired when objects identified by the search filter filter at the object named by target are modified.
 void EventContext.addNamingListener(String target, int scope, NamingListener l)
Adds a listener for receiving naming events fired when the object named by the string target name and scope changes.
 void EventDirContext.addNamingListener(String target, String filter, Object[] filterArgs, SearchControls ctls, NamingListener l)
Adds a listener for receiving naming events fired when objects identified by the search filter filter and filter arguments at the object named by the string target name are modified.
 void EventDirContext.addNamingListener(String target, String filter, SearchControls ctls, NamingListener l)
Adds a listener for receiving naming events fired when objects identified by the search filter filter at the object named by the string target name are modified.
 void NamingEvent.dispatch(NamingListener listener)
Invokes the appropriate listener method on this event.
 void NamingExceptionEvent.dispatch(NamingListener listener)
Invokes the namingExceptionThrown() method on a listener using this event.
 void EventContext.removeNamingListener(NamingListener l)
Removes a listener from receiving naming events fired by this EventContext.

Uses of NamingListener in javax.naming.ldap

Subinterfaces of NamingListener in javax.naming.ldap
 interface UnsolicitedNotificationListener
This interface is for handling UnsolicitedNotificationEvent.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.event.ObjectChangeListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.event.ObjectChangeListener

No usage of javax.naming.event.ObjectChangeListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


EventContext

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.naming.event
Interface EventContext

All Superinterfaces:
Context
All Known Subinterfaces:
EventDirContext
public interface EventContext
extends Context

Contains methods for registering/deregistering listeners to be notified of events fired when objects named in a context changes.

Target

The name parameter in the addNamingListener() methods is referred to as the target. The target, along with the scope, identify the object(s) that the listener is interested in. It is possible to register interest in a target that does not exist, but there might be limitations in the extent to which this can be supported by the service provider and underlying protocol/service.

If a service only supports registration for existing targets, an attempt to register for a nonexistent target results in a NameNotFoundException being thrown as early as possible, preferably at the time addNamingListener() is called, or if that is not possible, the listener will receive the exception through the NamingExceptionEvent.

Also, for service providers that only support registration for existing targets, when the target that a listener has registered for is subsequently removed from the namespace, the listener is notified via a NamingExceptionEvent (containing a NameNotFoundException).

An application can use the method targetMustExist() to check whether a EventContext supports registration of nonexistent targets.

Event Source

The EventContext instance on which you invoke the registration methods is the event source of the events that are (potentially) generated. The source is not necessarily the object named by the target. Only when the target is the empty name is the object named by the target the source. In other words, the target, along with the scope parameter, are used to identify the object(s) that the listener is interested in, but the event source is the EventContext instance with which the listener has registered.

For example, suppose a listener makes the following registration:

        NamespaceChangeListener listener = ...;
        src.addNamingListener("x", SUBTREE_SCOPE, listener);
When an object named "x/y" is subsequently deleted, the corresponding NamingEvent (evt) must contain:
        evt.getEventContext() == src
        evt.getOldBinding().getName().equals("x/y")

Furthermore, listener registration/deregistration is with the EventContext instance, and not with the corresponding object in the namespace. If the program intends at some point to remove a listener, then it needs to keep a reference to the EventContext instance on which it invoked addNamingListener() (just as it needs to keep a reference to the listener in order to remove it later). It cannot expect to do a lookup() and get another instance of a EventContext on which to perform the deregistration.

Lifetime of Registration

A registered listener becomes deregistered when:
  • It is removed using removeNamingListener().
  • An exception is thrown while collecting information about the events. That is, when the listener receives a NamingExceptionEvent.
  • Context.close() is invoked on the EventContext instance with which it has registered.
Until that point, a EventContext instance that has outstanding listeners will continue to exist and be maintained by the service provider.

Listener Implementations

The registration/deregistration methods accept an instance of NamingListener. There are subinterfaces of NamingListener for different of event types of NamingEvent. For example, the ObjectChangeListener interface is for the NamingEvent.OBJECT_CHANGED event type. To register interest in multiple event types, the listener implementation should implement multiple NamingListener subinterfaces and use a single invocation of addNamingListener(). In addition to reducing the number of method calls and possibly the code size of the listeners, this allows some service providers to optimize the registration.

Threading Issues

Like Context instances in general, instances of EventContext are not guaranteed to be thread-safe. Care must be taken when multiple threads are accessing the same EventContext concurrently. See the package description for more information on threading issues.

Since:
1.3

Field Summary
static int | OBJECT_SCOPE Constant for expressing interest in events concerning the object named by the target.
static int | ONELEVEL_SCOPE Constant for expressing interest in events concerning objects in the context named by the target, excluding the context named by the target.
static int | SUBTREE_SCOPE Constant for expressing interest in events concerning objects in the subtree of the object named by the target, including the object named by the target.
Fields inherited from interface javax.naming.Context
APPLET, AUTHORITATIVE, BATCHSIZE, DNS_URL, INITIAL_CONTEXT_FACTORY, LANGUAGE, OBJECT_FACTORIES, PROVIDER_URL, REFERRAL, SECURITY_AUTHENTICATION, SECURITY_CREDENTIALS, SECURITY_PRINCIPAL, SECURITY_PROTOCOL, STATE_FACTORIES, URL_PKG_PREFIXES
Method Summary
void | addNamingListener(Name target, int scope, NamingListener l) Adds a listener for receiving naming events fired when the object(s) identified by a target and scope changes.
void | addNamingListener(String target, int scope, NamingListener l) Adds a listener for receiving naming events fired when the object named by the string target name and scope changes.
void | removeNamingListener(NamingListener l) Removes a listener from receiving naming events fired by this EventContext.
boolean | targetMustExist() Determines whether a listener can register interest in a target that does not exist.
Methods inherited from interface javax.naming.Context
addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getEnvironment, getNameInNamespace, getNameParser, getNameParser, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind

Field Detail

OBJECT_SCOPE

static final int OBJECT_SCOPE
Constant for expressing interest in events concerning the object named by the target.

The value of this constant is 0.

See Also:
Constant Field Values

ONELEVEL_SCOPE

static final int ONELEVEL_SCOPE
Constant for expressing interest in events concerning objects in the context named by the target, excluding the context named by the target.

The value of this constant is 1.

See Also:
Constant Field Values

SUBTREE_SCOPE

static final int SUBTREE_SCOPE
Constant for expressing interest in events concerning objects in the subtree of the object named by the target, including the object named by the target.

The value of this constant is 2.

See Also:
Constant Field Values
Method Detail

addNamingListener

void addNamingListener(Name target,
                       int scope,
                       NamingListener l)
                       throws NamingException
Adds a listener for receiving naming events fired when the object(s) identified by a target and scope changes. The event source of those events is this context. See the class description for a discussion on event source and target. See the descriptions of the constants OBJECT_SCOPE, ONELEVEL_SCOPE, and SUBTREE_SCOPE to see how scope affects the registration.

target needs to name a context only when scope is ONELEVEL_SCOPE. target may name a non-context if scope is either OBJECT_SCOPE or SUBTREE_SCOPE. Using SUBTREE_SCOPE for a non-context might be useful, for example, if the caller does not know in advance whether target is a context and just wants to register interest in the (possibly degenerate subtree) rooted at target.

When the listener is notified of an event, the listener may in invoked in a thread other than the one in which addNamingListener() is executed. Care must be taken when multiple threads are accessing the same EventContext concurrently. See the package description for more information on threading issues.

Parameters:
target - A nonnull name to be resolved relative to this context.
scope - One of OBJECT_SCOPE, ONELEVEL_SCOPE, or SUBTREE_SCOPE.
l - The nonnull listener.
Throws:
NamingException - If a problem was encountered while adding the listener.
See Also:
removeNamingListener(javax.naming.event.NamingListener)

addNamingListener

void addNamingListener(String target,
                       int scope,
                       NamingListener l)
                       throws NamingException
Adds a listener for receiving naming events fired when the object named by the string target name and scope changes. See the overload that accepts a Name for details.

Parameters:
target - The nonnull string name of the object resolved relative to this context.
scope - One of OBJECT_SCOPE, ONELEVEL_SCOPE, or SUBTREE_SCOPE.
l - The nonnull listener.
Throws:
NamingException - If a problem was encountered while adding the listener.
See Also:
removeNamingListener(javax.naming.event.NamingListener)

removeNamingListener

void removeNamingListener(NamingListener l)
                          throws NamingException
Removes a listener from receiving naming events fired by this EventContext. The listener may have registered more than once with this EventContext, perhaps with different target/scope arguments. After this method is invoked, the listener will no longer receive events with this EventContext instance as the event source (except for those events already in the process of being dispatched). If the listener was not, or is no longer, registered with this EventContext instance, this method does not do anything.

Parameters:
l - The nonnull listener.
Throws:
NamingException - If a problem was encountered while removing the listener.
See Also:
addNamingListener(javax.naming.Name, int, javax.naming.event.NamingListener)

targetMustExist

boolean targetMustExist()
                        throws NamingException
Determines whether a listener can register interest in a target that does not exist.

Returns:
true if the target must exist; false if the target need not exist.
Throws:
NamingException - If the context's behavior in this regard cannot be determined.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


EventDirContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.event
Interface EventDirContext

All Superinterfaces:
Context, DirContext, EventContext
public interface EventDirContext
extends EventContext, DirContext

Contains methods for registering listeners to be notified of events fired when objects named in a directory context changes.

The methods in this interface support identification of objects by RFC 2254 search filters.

Using the search filter, it is possible to register interest in objects that do not exist at the time of registration but later come into existence and satisfy the filter. However, there might be limitations in the extent to which this can be supported by the service provider and underlying protocol/service. If the caller submits a filter that cannot be supported in this way, addNamingListener() throws an InvalidSearchFilterException.

See EventContext for a description of event source and target, and information about listener registration/deregistration that are also applicable to methods in this interface. See the package description for information on threading issues.

A SearchControls or array object passed as a parameter to any method is owned by the caller. The service provider will not modify the object or keep a reference to it.

Since:
1.3

Field Summary
Fields inherited from interface javax.naming.event.EventContext
OBJECT_SCOPE, ONELEVEL_SCOPE, SUBTREE_SCOPE
Fields inherited from interface javax.naming.directory.DirContext
ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE
Fields inherited from interface javax.naming.Context
APPLET, AUTHORITATIVE, BATCHSIZE, DNS_URL, INITIAL_CONTEXT_FACTORY, LANGUAGE, OBJECT_FACTORIES, PROVIDER_URL, REFERRAL, SECURITY_AUTHENTICATION, SECURITY_CREDENTIALS, SECURITY_PRINCIPAL, SECURITY_PROTOCOL, STATE_FACTORIES, URL_PKG_PREFIXES
Method Summary
void | addNamingListener(Name target, String filter, Object[] filterArgs, SearchControls ctls, NamingListener l) Adds a listener for receiving naming events fired when objects identified by the search filter filter and filter arguments at the object named by the target are modified.
void | addNamingListener(Name target, String filter, SearchControls ctls, NamingListener l) Adds a listener for receiving naming events fired when objects identified by the search filter filter at the object named by target are modified.
void | addNamingListener(String target, String filter, Object[] filterArgs, SearchControls ctls, NamingListener l) Adds a listener for receiving naming events fired when objects identified by the search filter filter and filter arguments at the object named by the string target name are modified.
void | addNamingListener(String target, String filter, SearchControls ctls, NamingListener l) Adds a listener for receiving naming events fired when objects identified by the search filter filter at the object named by the string target name are modified.
Methods inherited from interface javax.naming.event.EventContext
addNamingListener, addNamingListener, removeNamingListener, targetMustExist
Methods inherited from interface javax.naming.directory.DirContext
bind, bind, createSubcontext, createSubcontext, getAttributes, getAttributes, getAttributes, getAttributes, getSchema, getSchema, getSchemaClassDefinition, getSchemaClassDefinition, modifyAttributes, modifyAttributes, modifyAttributes, modifyAttributes, rebind, rebind, search, search, search, search, search, search, search, search
Methods inherited from interface javax.naming.Context
addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getEnvironment, getNameInNamespace, getNameParser, getNameParser, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind

Method Detail

addNamingListener

void addNamingListener(Name target,
                       String filter,
                       SearchControls ctls,
                       NamingListener l)
                       throws NamingException
Adds a listener for receiving naming events fired when objects identified by the search filter filter at the object named by target are modified.

The scope, returningObj flag, and returningAttributes flag from the search controls ctls are used to control the selection of objects that the listener is interested in, and determines what information is returned in the eventual NamingEvent object. Note that the requested information to be returned might not be present in the NamingEvent object if they are unavailable or could not be obtained by the service provider or service.

Parameters:
target - The nonnull name of the object resolved relative to this context.
filter - The nonnull string filter (see RFC2254).
ctls - The possibly null search controls. If null, the default search controls are used.
l - The nonnull listener.
Throws:
NamingException - If a problem was encountered while adding the listener.
See Also:
EventContext.removeNamingListener(javax.naming.event.NamingListener), DirContext.search(javax.naming.Name, java.lang.String, javax.naming.directory.SearchControls)

addNamingListener

void addNamingListener(String target,
                       String filter,
                       SearchControls ctls,
                       NamingListener l)
                       throws NamingException
Adds a listener for receiving naming events fired when objects identified by the search filter filter at the object named by the string target name are modified. See the overload that accepts a Name for details of how this method behaves.

Parameters:
target - The nonnull string name of the object resolved relative to this context.
filter - The nonnull string filter (see RFC2254).
ctls - The possibly null search controls. If null, the default search controls is used.
l - The nonnull listener.
Throws:
NamingException - If a problem was encountered while adding the listener.
See Also:
EventContext.removeNamingListener(javax.naming.event.NamingListener), DirContext.search(java.lang.String, java.lang.String, javax.naming.directory.SearchControls)

addNamingListener

void addNamingListener(Name target,
                       String filter,
                       Object[] filterArgs,
                       SearchControls ctls,
                       NamingListener l)
                       throws NamingException
Adds a listener for receiving naming events fired when objects identified by the search filter filter and filter arguments at the object named by the target are modified. The scope, returningObj flag, and returningAttributes flag from the search controls ctls are used to control the selection of objects that the listener is interested in, and determines what information is returned in the eventual NamingEvent object. Note that the requested information to be returned might not be present in the NamingEvent object if they are unavailable or could not be obtained by the service provider or service.

Parameters:
target - The nonnull name of the object resolved relative to this context.
filter - The nonnull string filter (see RFC2254).
filterArgs - The possibly null array of arguments for the filter.
ctls - The possibly null search controls. If null, the default search controls are used.
l - The nonnull listener.
Throws:
NamingException - If a problem was encountered while adding the listener.
See Also:
EventContext.removeNamingListener(javax.naming.event.NamingListener), DirContext.search(javax.naming.Name, java.lang.String, java.lang.Object[], javax.naming.directory.SearchControls)

addNamingListener

void addNamingListener(String target,
                       String filter,
                       Object[] filterArgs,
                       SearchControls ctls,
                       NamingListener l)
                       throws NamingException
Adds a listener for receiving naming events fired when objects identified by the search filter filter and filter arguments at the object named by the string target name are modified. See the overload that accepts a Name for details of how this method behaves.

Parameters:
target - The nonnull string name of the object resolved relative to this context.
filter - The nonnull string filter (see RFC2254).
filterArgs - The possibly null array of arguments for the filter.
ctls - The possibly null search controls. If null, the default search controls is used.
l - The nonnull listener.
Throws:
NamingException - If a problem was encountered while adding the listener.
See Also:
EventContext.removeNamingListener(javax.naming.event.NamingListener), DirContext.search(java.lang.String, java.lang.String, java.lang.Object[], javax.naming.directory.SearchControls)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamespaceChangeListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.event
Interface NamespaceChangeListener

All Superinterfaces:
EventListener, NamingListener
public interface NamespaceChangeListener
extends NamingListener

Specifies the methods that a listener interested in namespace changes must implement. Specifically, the listener is interested in NamingEvents with event types of OBJECT_ADDED, OBJECT_RENAMED, or OBJECT_REMOVED.

Such a listener must:

  1. Implement this interface and its methods.
  2. Implement NamingListener.namingExceptionThrown() so that it will be notified of exceptions thrown while attempting to collect information about the events.
  3. Register with the source using the source's addNamingListener() method.
A listener that wants to be notified of OBJECT_CHANGED event types should also implement the ObjectChangeListener interface.

Since:
1.3
See Also:
NamingEvent, ObjectChangeListener, EventContext, EventDirContext

Method Summary
void | objectAdded(NamingEvent evt) Called when an object has been added.
void | objectRemoved(NamingEvent evt) Called when an object has been removed.
void | objectRenamed(NamingEvent evt) Called when an object has been renamed.
Methods inherited from interface javax.naming.event.NamingListener
namingExceptionThrown

Method Detail

objectAdded

void objectAdded(NamingEvent evt)
Called when an object has been added.

The binding of the newly added object can be obtained using evt.getNewBinding().

Parameters:
evt - The nonnull event.
See Also:
NamingEvent.OBJECT_ADDED

objectRemoved

void objectRemoved(NamingEvent evt)
Called when an object has been removed.

The binding of the newly removed object can be obtained using evt.getOldBinding().

Parameters:
evt - The nonnull event.
See Also:
NamingEvent.OBJECT_REMOVED

objectRenamed

void objectRenamed(NamingEvent evt)
Called when an object has been renamed.

The binding of the renamed object can be obtained using evt.getNewBinding(). Its old binding (before the rename) can be obtained using evt.getOldBinding(). One of these may be null if the old/new binding was outside the scope in which the listener has registered interest.

Parameters:
evt - The nonnull event.
See Also:
NamingEvent.OBJECT_RENAMED
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamingEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.event
Class NamingEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.naming.event.NamingEvent
All Implemented Interfaces:
Serializable
public class NamingEvent
extends EventObject

This class represents an event fired by a naming/directory service.

The NamingEvent's state consists of

  • The event source: the EventContext which fired this event.
  • The event type.
  • The new binding: information about the object after the change.
  • The old binding: information about the object before the change.
  • Change information: information about the change that triggered this event; usually service provider-specific or server-specific information.

Note that the event source is always the same EventContext instance that the listener has registered with. Furthermore, the names of the bindings in the NamingEvent are always relative to that instance. For example, suppose a listener makes the following registration:

        NamespaceChangeListener listener = ...;
        src.addNamingListener("x", SUBTREE_SCOPE, listener);
When an object named "x/y" is subsequently deleted, the corresponding NamingEvent (evt) must contain:
        evt.getEventContext() == src
        evt.getOldBinding().getName().equals("x/y")
Care must be taken when multiple threads are accessing the same EventContext concurrently. See the package description for more information on threading issues.

Since:
1.3
See Also:
NamingListener, EventContext, Serialized Form

Field Summary
protected Object | changeInfo Contains information about the change that generated this event.
protected Binding | newBinding Contains information about the object after the change.
static int | OBJECT_ADDED Naming event type for indicating that a new object has been added.
static int | OBJECT_CHANGED Naming event type for indicating that an object has been changed.
static int | OBJECT_REMOVED Naming event type for indicating that an object has been removed.
static int | OBJECT_RENAMED Naming event type for indicating that an object has been renamed.
protected Binding | oldBinding Contains information about the object before the change.
protected int | type Contains the type of this event.
Fields inherited from class java.util.EventObject
source
Constructor Summary
NamingEvent(EventContext source, int type, Binding newBd, Binding oldBd, Object changeInfo)
Constructs an instance of NamingEvent.
Method Summary
void | dispatch(NamingListener listener) Invokes the appropriate listener method on this event.
Object | getChangeInfo() Retrieves the change information for this event.
EventContext | getEventContext() Retrieves the event source that fired this event.
Binding | getNewBinding() Retrieves the binding of the object after the change.
Binding | getOldBinding() Retrieves the binding of the object before the change.
int | getType() Returns the type of this event.
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

OBJECT_ADDED

public static final int OBJECT_ADDED
Naming event type for indicating that a new object has been added. The value of this constant is 0.

See Also:
Constant Field Values

OBJECT_REMOVED

public static final int OBJECT_REMOVED
Naming event type for indicating that an object has been removed. The value of this constant is 1.

See Also:
Constant Field Values

OBJECT_RENAMED

public static final int OBJECT_RENAMED
Naming event type for indicating that an object has been renamed. Note that some services might fire multiple events for a single logical rename operation. For example, the rename operation might be implemented by adding a binding with the new name and removing the old binding.

The old/new binding in NamingEvent may be null if the old name or new name is outside of the scope for which the listener has registered.

When an interior node in the namespace tree has been renamed, the topmost node which is part of the listener's scope should used to generate a rename event. The extent to which this can be supported is provider-specific. For example, a service might generate rename notifications for all descendants of the changed interior node and the corresponding provider might not be able to prevent those notifications from being propagated to the listeners.

The value of this constant is 2.

See Also:
Constant Field Values

OBJECT_CHANGED

public static final int OBJECT_CHANGED
Naming event type for indicating that an object has been changed. The changes might include the object's attributes, or the object itself. Note that some services might fire multiple events for a single modification. For example, the modification might be implemented by first removing the old binding and adding a new binding containing the same name but a different object.

The value of this constant is 3.

See Also:
Constant Field Values

changeInfo

protected Object changeInfo
Contains information about the change that generated this event.

type

protected int type
Contains the type of this event.

See Also:
OBJECT_ADDED, OBJECT_REMOVED, OBJECT_RENAMED, OBJECT_CHANGED

oldBinding

protected Binding oldBinding
Contains information about the object before the change.

newBinding

protected Binding newBinding
Contains information about the object after the change.

Constructor Detail

NamingEvent

public NamingEvent(EventContext source,
                   int type,
                   Binding newBd,
                   Binding oldBd,
                   Object changeInfo)
Constructs an instance of NamingEvent.

The names in newBd and oldBd are to be resolved relative to the event source source. For an OBJECT_ADDED event type, newBd must not be null. For an OBJECT_REMOVED event type, oldBd must not be null. For an OBJECT_CHANGED event type, newBd and oldBd must not be null. For an OBJECT_RENAMED event type, one of newBd or oldBd may be null if the new or old binding is outside of the scope for which the listener has registered.

Parameters:
source - The non-null context that fired this event.
type - The type of the event.
newBd - A possibly null binding before the change. See method description.
oldBd - A possibly null binding after the change. See method description.
changeInfo - A possibly null object containing information about the change.
See Also:
OBJECT_ADDED, OBJECT_REMOVED, OBJECT_RENAMED, OBJECT_CHANGED
Method Detail

getType

public int getType()
Returns the type of this event.

Returns:
The type of this event.
See Also:
OBJECT_ADDED, OBJECT_REMOVED, OBJECT_RENAMED, OBJECT_CHANGED

getEventContext

public EventContext getEventContext()
Retrieves the event source that fired this event. This returns the same object as EventObject.getSource().

If the result of this method is used to access the event source, for example, to look up the object or get its attributes, then it needs to be locked because implementations of Context are not guaranteed to be thread-safe (and EventContext is a subinterface of Context). See the package description for more information on threading issues.

Returns:
The non-null context that fired this event.

getOldBinding

public Binding getOldBinding()
Retrieves the binding of the object before the change.

The binding must be nonnull if the object existed before the change relative to the source context (getEventContext()). That is, it must be nonnull for OBJECT_REMOVED and OBJECT_CHANGED. For OBJECT_RENAMED, it is null if the object before the rename is outside of the scope for which the listener has registered interest; it is nonnull if the object is inside the scope before the rename.

The name in the binding is to be resolved relative to the event source getEventContext(). The object returned by Binding.getObject() may be null if such information is unavailable.

Returns:
The possibly null binding of the object before the change.

getNewBinding

public Binding getNewBinding()
Retrieves the binding of the object after the change.

The binding must be nonnull if the object existed after the change relative to the source context (getEventContext()). That is, it must be nonnull for OBJECT_ADDED and OBJECT_CHANGED. For OBJECT_RENAMED, it is null if the object after the rename is outside the scope for which the listener registered interest; it is nonnull if the object is inside the scope after the rename.

The name in the binding is to be resolved relative to the event source getEventContext(). The object returned by Binding.getObject() may be null if such information is unavailable.

Returns:
The possibly null binding of the object after the change.

getChangeInfo

public Object getChangeInfo()
Retrieves the change information for this event. The value of the change information is service-specific. For example, it could be an ID that identifies the change in a change log on the server.

Returns:
The possibly null change information of this event.

dispatch

public void dispatch(NamingListener listener)
Invokes the appropriate listener method on this event. The default implementation of this method handles the following event types: OBJECT_ADDED, OBJECT_REMOVED, OBJECT_RENAMED, OBJECT_CHANGED.

The listener method is executed in the same thread as this method. See the package description for more information on threading issues.

Parameters:
listener - The nonnull listener.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamingExceptionEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.event
Class NamingExceptionEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.naming.event.NamingExceptionEvent
All Implemented Interfaces:
Serializable
public class NamingExceptionEvent
extends EventObject

This class represents an event fired when the procedures/processes used to collect information for notifying listeners of NamingEvents threw a NamingException. This can happen, for example, if the server which the listener is using aborts subsequent to the addNamingListener() call.

Since:
1.3
See Also:
NamingListener.namingExceptionThrown(javax.naming.event.NamingExceptionEvent), EventContext, Serialized Form

Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
NamingExceptionEvent(EventContext source, NamingException exc)
Constructs an instance of NamingExceptionEvent using the context in which the NamingException was thrown and the exception that was thrown.
Method Summary
void | dispatch(NamingListener listener) Invokes the namingExceptionThrown() method on a listener using this event.
EventContext | getEventContext() Retrieves the EventContext that fired this event.
NamingException | getException() Retrieves the exception that was thrown.
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NamingExceptionEvent

public NamingExceptionEvent(EventContext source,
                            NamingException exc)
Constructs an instance of NamingExceptionEvent using the context in which the NamingException was thrown and the exception that was thrown.

Parameters:
source - The non-null context in which the exception was thrown.
exc - The non-null NamingException that was thrown.
Method Detail

getException

public NamingException getException()
Retrieves the exception that was thrown.

Returns:
The exception that was thrown.

getEventContext

public EventContext getEventContext()
Retrieves the EventContext that fired this event. This returns the same object as EventObject.getSource().

Returns:
The non-null EventContext that fired this event.

dispatch

public void dispatch(NamingListener listener)
Invokes the namingExceptionThrown() method on a listener using this event.

Parameters:
listener - The non-null naming listener on which to invoke the method.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamingListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.event
Interface NamingListener

All Superinterfaces:
EventListener
All Known Subinterfaces:
NamespaceChangeListener, ObjectChangeListener, UnsolicitedNotificationListener
public interface NamingListener
extends EventListener

This interface is the root of listener interfaces that handle NamingEvents. It does not make sense for a listener to implement just this interface. A listener typically implements a subinterface of NamingListener, such as ObjectChangeListener or NamespaceChangeListener.

This interface contains a single method, namingExceptionThrown(), that must be implemented so that the listener can be notified of exceptions that are thrown (by the service provider) while gathering information about the events that they're interested in. When this method is invoked, the listener has been automatically deregistered from the EventContext with which it has registered.

For example, suppose a listener implements ObjectChangeListener and registers with a EventContext. Then, if the connection to the server is subsequently broken, the listener will receive a NamingExceptionEvent and may take some corrective action, such as notifying the user of the application.

Since:
1.3
See Also:
NamingEvent, NamingExceptionEvent, EventContext, EventDirContext

Method Summary
 void namingExceptionThrown(NamingExceptionEvent evt)
Called when a naming exception is thrown while attempting to fire a NamingEvent.

Method Detail

namingExceptionThrown

void namingExceptionThrown(NamingExceptionEvent evt)
Called when a naming exception is thrown while attempting to fire a NamingEvent.

Parameters:
evt - The nonnull event.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectChangeListener

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.naming.event
Interface ObjectChangeListener

All Superinterfaces:
EventListener, NamingListener
public interface ObjectChangeListener
extends NamingListener

Specifies the method that a listener of a NamingEvent with event type of OBJECT_CHANGED must implement.

An OBJECT_CHANGED event type is fired when (the contents of) an object has changed. This might mean that its attributes have been modified, added, or removed, and/or that the object itself has been replaced. How the object has changed can be determined by examining the NamingEvent's old and new bindings.

A listener interested in OBJECT_CHANGED event types must:

  1. Implement this interface and its method (objectChanged())
  2. Implement NamingListener.namingExceptionThrown() so that it will be notified of exceptions thrown while attempting to collect information about the events.
  3. Register with the source using the source's addNamingListener() method.
A listener that wants to be notified of namespace change events should also implement the NamespaceChangeListener interface.

Since:
1.3
See Also:
NamingEvent, NamespaceChangeListener, EventContext, EventDirContext

Method Summary
 void objectChanged(NamingEvent evt)
Called when an object has been changed.
Methods inherited from interface javax.naming.event.NamingListener
namingExceptionThrown

Method Detail

objectChanged

void objectChanged(NamingEvent evt)
Called when an object has been changed.

The binding of the changed object can be obtained using evt.getNewBinding(). Its old binding (before the change) can be obtained using evt.getOldBinding().

Parameters:
evt - The nonnull naming event.
See Also:
NamingEvent.OBJECT_CHANGED
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


InitialContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class InitialContext

java.lang.Object
    extended by  javax.naming.InitialContext
All Implemented Interfaces:
Context
Direct Known Subclasses:
InitialDirContext
public class InitialContext
extends Object
implements Context

This class is the starting context for performing naming operations.

All naming operations are relative to a context. The initial context implements the Context interface and provides the starting point for resolution of names.

When the initial context is constructed, its environment is initialized with properties defined in the environment parameter passed to the constructor, and in any application resource files. In addition, a small number of standard JNDI properties may be specified as system properties or as applet parameters (through the use of Context.APPLET). These special properties are listed in the field detail sections of the Context and LdapContext interface documentation.

JNDI determines each property's value by merging the values from the following two sources, in order:

  1. The first occurrence of the property from the constructor's environment parameter and (for appropriate properties) the applet parameters and system properties.
  2. The application resource files (jndi.properties).
For each property found in both of these two sources, or in more than one application resource file, the property's value is determined as follows. If the property is one of the standard JNDI properties that specify a list of JNDI factories (see Context), all of the values are concatenated into a single colon-separated list. For other properties, only the first value found is used.

The initial context implementation is determined at runtime. The default policy uses the environment property "java.naming.factory.initial", which contains the class name of the initial context factory. An exception to this policy is made when resolving URL strings, as described below.

When a URL string (a String of the form scheme_id:rest_of_name) is passed as a name parameter to any method, a URL context factory for handling that scheme is located and used to resolve the URL. If no such factory is found, the initial context specified by "java.naming.factory.initial" is used. Similarly, when a CompositeName object whose first component is a URL string is passed as a name parameter to any method, a URL context factory is located and used to resolve the first name component. See NamingManager.getURLContext() for a description of how URL context factories are located.

This default policy of locating the initial context and URL context factories may be overridden by calling NamingManager.setInitialContextFactoryBuilder().

NoInitialContextException is thrown when an initial context cannot be instantiated. This exception can be thrown during any interaction with the InitialContext, not only when the InitialContext is constructed. For example, the implementation of the initial context might lazily retrieve the context only when actual methods are invoked on it. The application should not have any dependency on when the existence of an initial context is determined.

When the environment property "java.naming.factory.initial" is non-null, the InitialContext constructor will attempt to create the initial context specified therein. At that time, the initial context factory involved might throw an exception if a problem is encountered. However, it is provider implementation-dependent when it verifies and indicates to the users of the initial context any environment property- or connection- related problems. It can do so lazily--delaying until an operation is performed on the context, or eagerly, at the time the context is constructed.

An InitialContext instance is not synchronized against concurrent access by multiple threads. Multiple threads each manipulating a different InitialContext instance need not synchronize. Threads that need to access a single InitialContext instance concurrently should synchronize amongst themselves and provide the necessary locking.

Since:
JNDI 1.1 / Java 2 Platform, Standard Edition, v 1.3
See Also:
Context, NamingManager.setInitialContextFactoryBuilder

Field Summary
protected Context | defaultInitCtx Field holding the result of calling NamingManager.getInitialContext().
protected boolean | gotDefault Field indicating whether the initial context has been obtained by calling NamingManager.getInitialContext().
protected Hashtable<Object,Object> | myProps The environment associated with this InitialContext.
Fields inherited from interface javax.naming.Context
APPLET, AUTHORITATIVE, BATCHSIZE, DNS_URL, INITIAL_CONTEXT_FACTORY, LANGUAGE, OBJECT_FACTORIES, PROVIDER_URL, REFERRAL, SECURITY_AUTHENTICATION, SECURITY_CREDENTIALS, SECURITY_PRINCIPAL, SECURITY_PROTOCOL, STATE_FACTORIES, URL_PKG_PREFIXES
Constructor Summary
 | InitialContext() Constructs an initial context.
protected | InitialContext(boolean lazy) Constructs an initial context with the option of not initializing it.
 | InitialContext(Hashtable<?,?> environment) Constructs an initial context using the supplied environment.
Method Summary
 Object addToEnvironment(String propName, Object propVal)
Adds a new environment property to the environment of this context.
 void bind(Name name, Object obj)
Binds a name to an object.
 void bind(String name, Object obj)
Binds a name to an object.
 void close()
Closes this context.
 Name composeName(Name name, Name prefix)
Composes the name of this context with a name relative to this context.
 String composeName(String name, String prefix)
Composes the name of this context with a name relative to this context.
 Context createSubcontext(Name name)
Creates and binds a new context.
 Context createSubcontext(String name)
Creates and binds a new context.
 void destroySubcontext(Name name)
Destroys the named context and removes it from the namespace.
 void destroySubcontext(String name)
Destroys the named context and removes it from the namespace.
static
<T> T
doLookup(Name name)
A static method to retrieve the named object.
static
<T> T
doLookup(String name)
A static method to retrieve the named object.
protected  Context getDefaultInitCtx()
Retrieves the initial context by calling NamingManager.getInitialContext() and cache it in defaultInitCtx.
 Hashtable<?,?> getEnvironment()
Retrieves the environment in effect for this context.
 String getNameInNamespace()
Retrieves the full name of this context within its own namespace.
 NameParser getNameParser(Name name)
Retrieves the parser associated with the named context.
 NameParser getNameParser(String name)
Retrieves the parser associated with the named context.
protected  Context getURLOrDefaultInitCtx(Name name)
Retrieves a context for resolving name.
protected  Context getURLOrDefaultInitCtx(String name)
Retrieves a context for resolving the string name name.
protected  void init(Hashtable<?,?> environment)
Initializes the initial context using the supplied environment.
 NamingEnumeration<NameClassPair> list(Name name)
Enumerates the names bound in the named context, along with the class names of objects bound to them.
 NamingEnumeration<NameClassPair> list(String name)
Enumerates the names bound in the named context, along with the class names of objects bound to them.
 NamingEnumeration<Binding> listBindings(Name name)
Enumerates the names bound in the named context, along with the objects bound to them.
 NamingEnumeration<Binding> listBindings(String name)
Enumerates the names bound in the named context, along with the objects bound to them.
 Object lookup(Name name)
Retrieves the named object.
 Object lookup(String name)
Retrieves the named object.
 Object lookupLink(Name name)
Retrieves the named object, following links except for the terminal atomic component of the name.
 Object lookupLink(String name)
Retrieves the named object, following links except for the terminal atomic component of the name.
 void rebind(Name name, Object obj)
Binds a name to an object, overwriting any existing binding.
 void rebind(String name, Object obj)
Binds a name to an object, overwriting any existing binding.
 Object removeFromEnvironment(String propName)
Removes an environment property from the environment of this context.
 void rename(Name oldName, Name newName)
Binds a new name to the object bound to an old name, and unbinds the old name.
 void rename(String oldName, String newName)
Binds a new name to the object bound to an old name, and unbinds the old name.
 void unbind(Name name)
Unbinds the named object.
 void unbind(String name)
Unbinds the named object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

myProps

protected Hashtable<Object,Object> myProps
The environment associated with this InitialContext. It is initialized to null and is updated by the constructor that accepts an environment or by the init() method.

See Also:
addToEnvironment(java.lang.String, java.lang.Object),
removeFromEnvironment(java.lang.String),
getEnvironment()

defaultInitCtx

protected Context defaultInitCtx
Field holding the result of calling NamingManager.getInitialContext(). It is set by getDefaultInitCtx() the first time getDefaultInitCtx() is called. Subsequent invocations of getDefaultInitCtx() return the value of defaultInitCtx.

See Also:
getDefaultInitCtx()

gotDefault

protected boolean gotDefault
Field indicating whether the initial context has been obtained by calling NamingManager.getInitialContext(). If true, its result is in defaultInitCtx.

Constructor Detail

InitialContext

protected InitialContext(boolean lazy)
                  throws NamingException
Constructs an initial context with the option of not initializing it. This may be used by a constructor in a subclass when the value of the environment parameter is not yet known at the time the InitialContext constructor is called. The subclass's constructor will call this constructor, compute the value of the environment, and then call init() before returning.

Parameters:
lazy - true means do not initialize the initial context; false is equivalent to calling new InitialContext()
Throws:
NamingException - if a naming exception is encountered
Since:
1.3
See Also:
init(Hashtable)

InitialContext

public InitialContext()
               throws NamingException
Constructs an initial context. No environment properties are supplied. Equivalent to new InitialContext(null).

Throws:
NamingException - if a naming exception is encountered
See Also:
InitialContext(Hashtable)

InitialContext

public InitialContext(Hashtable<?,?> environment)
               throws NamingException
Constructs an initial context using the supplied environment. Environment properties are discussed in the class description.

This constructor will not modify environment or save a reference to it, but may save a clone.

Parameters:
environment - environment used to create the initial context. Null indicates an empty environment.
Throws:
NamingException - if a naming exception is encountered
Method Detail

init

protected void init(Hashtable<?,?> environment)
             throws NamingException
Initializes the initial context using the supplied environment. Environment properties are discussed in the class description.

This method will modify environment and save a reference to it. The caller may no longer modify it.

Parameters:
environment - environment used to create the initial context. Null indicates an empty environment.
Throws:
NamingException - if a naming exception is encountered
Since:
1.3
See Also:
InitialContext(boolean)

doLookup

public static <T> T doLookup(Name name)
                  throws NamingException
A static method to retrieve the named object. This is a shortcut method equivalent to invoking:

InitialContext ic = new InitialContext(); Object obj = ic.lookup();

If name is empty, returns a new instance of this context (which represents the same naming context as this context, but its environment may be modified independently and it may be accessed concurrently).

Parameters:
name - the name of the object to look up
Returns:
the object bound to name
Throws:
NamingException - if a naming exception is encountered
Since:
1.6
See Also:
doLookup(String), lookup(Name)

doLookup

public static <T> T doLookup(String name)
                  throws NamingException
A static method to retrieve the named object. See doLookup(Name) for details.

Parameters:
name - the name of the object to look up
Returns:
the object bound to name
Throws:
NamingException - if a naming exception is encountered
Since:
1.6

getDefaultInitCtx

protected Context getDefaultInitCtx()
                             throws NamingException
Retrieves the initial context by calling NamingManager.getInitialContext() and cache it in defaultInitCtx. Set gotDefault so that we know we've tried this before.

Returns:
The non-null cached initial context.
Throws:
NoInitialContextException - If cannot find an initial context.
NamingException - If a naming exception was encountered.

getURLOrDefaultInitCtx

protected Context getURLOrDefaultInitCtx(String name)
                                  throws NamingException
Retrieves a context for resolving the string name name. If name name is a URL string, then attempt to find a URL context for it. If none is found, or if name is not a URL string, then return getDefaultInitCtx().

See getURLOrDefaultInitCtx(Name) for description of how a subclass should use this method.

Parameters:
name - The non-null name for which to get the context.
Returns:
A URL context for name or the cached initial context. The result cannot be null.
Throws:
NoInitialContextException - If cannot find an initial context.
NamingException - In a naming exception is encountered.
See Also:
NamingManager.getURLContext(java.lang.String, java.util.Hashtable)

getURLOrDefaultInitCtx

protected Context getURLOrDefaultInitCtx(Name name)
                                  throws NamingException
Retrieves a context for resolving name. If the first component of name name is a URL string, then attempt to find a URL context for it. If none is found, or if the first component of name is not a URL string, then return getDefaultInitCtx().

When creating a subclass of InitialContext, use this method as follows. Define a new method that uses this method to get an initial context of the desired subclass.

 protected XXXContext getURLOrDefaultInitXXXCtx(Name name)
 throws NamingException {
  Context answer = getURLOrDefaultInitCtx(name);
  if (!(answer instanceof XXXContext)) {
    if (answer == null) {
            throw new NoInitialContextException();
    } else {
            throw new NotContextException("Not an XXXContext");
    }
        }
        return (XXXContext)answer;
 }
When providing implementations for the new methods in the subclass, use this newly defined method to get the initial context.

 public Object XXXMethod1(Name name, ...) {
        throws NamingException {
    return getURLOrDefaultInitXXXCtx(name).XXXMethod1(name, ...);
 }

Parameters:
name - The non-null name for which to get the context.
Returns:
A URL context for name or the cached initial context. The result cannot be null.
Throws:
NoInitialContextException - If cannot find an initial context.
NamingException - In a naming exception is encountered.
See Also:
NamingManager.getURLContext(java.lang.String, java.util.Hashtable)

lookup

public Object lookup(String name)
              throws NamingException
Description copied from interface: Context
Retrieves the named object. See Context.lookup(Name) for details.

Specified by:
lookup in interface Context
Parameters:
name - the name of the object to look up
Returns:
the object bound to name
Throws:
NamingException - if a naming exception is encountered

lookup

public Object lookup(Name name)
              throws NamingException
Description copied from interface: Context
Retrieves the named object. If name is empty, returns a new instance of this context (which represents the same naming context as this context, but its environment may be modified independently and it may be accessed concurrently).

Specified by:
lookup in interface Context
Parameters:
name - the name of the object to look up
Returns:
the object bound to name
Throws:
NamingException - if a naming exception is encountered
See Also:
Context.lookup(String), Context.lookupLink(Name)

bind

public void bind(String name,
                 Object obj)
          throws NamingException
Description copied from interface: Context
Binds a name to an object. See Context.bind(Name, Object) for details.

Specified by:
bind in interface Context
Parameters:
name - the name to bind; may not be empty
obj - the object to bind; possibly null
Throws:
NameAlreadyBoundException - if name is already bound
InvalidAttributesException - if object did not supply all mandatory attributes
NamingException - if a naming exception is encountered

bind

public void bind(Name name,
                 Object obj)
          throws NamingException
Description copied from interface: Context
Binds a name to an object. All intermediate contexts and the target context (that named by all but terminal atomic component of the name) must already exist.

Specified by:
bind in interface Context
Parameters:
name - the name to bind; may not be empty
obj - the object to bind; possibly null
Throws:
NameAlreadyBoundException - if name is already bound
InvalidAttributesException - if object did not supply all mandatory attributes
NamingException - if a naming exception is encountered
See Also:
Context.bind(String, Object), Context.rebind(Name, Object), DirContext.bind(Name, Object, javax.naming.directory.Attributes)

rebind

public void rebind(String name,
                   Object obj)
            throws NamingException
Description copied from interface: Context
Binds a name to an object, overwriting any existing binding. See Context.rebind(Name, Object) for details.

Specified by:
rebind in interface Context
Parameters:
name - the name to bind; may not be empty
obj - the object to bind; possibly null
Throws:
InvalidAttributesException - if object did not supply all mandatory attributes
NamingException - if a naming exception is encountered

rebind

public void rebind(Name name,
                   Object obj)
            throws NamingException
Description copied from interface: Context
Binds a name to an object, overwriting any existing binding. All intermediate contexts and the target context (that named by all but terminal atomic component of the name) must already exist.

If the object is a DirContext, any existing attributes associated with the name are replaced with those of the object. Otherwise, any existing attributes associated with the name remain unchanged.

Specified by:
rebind in interface Context
Parameters:
name - the name to bind; may not be empty
obj - the object to bind; possibly null
Throws:
InvalidAttributesException - if object did not supply all mandatory attributes
NamingException - if a naming exception is encountered
See Also:
Context.rebind(String, Object), Context.bind(Name, Object), DirContext.rebind(Name, Object, javax.naming.directory.Attributes), DirContext

unbind

public void unbind(String name)
            throws NamingException
Description copied from interface: Context
Unbinds the named object. See Context.unbind(Name) for details.

Specified by:
unbind in interface Context
Parameters:
name - the name to unbind; may not be empty
Throws:
NameNotFoundException - if an intermediate context does not exist
NamingException - if a naming exception is encountered

unbind

public void unbind(Name name)
            throws NamingException
Description copied from interface: Context
Unbinds the named object. Removes the terminal atomic name in name from the target context--that named by all but the terminal atomic part of name.

This method is idempotent. It succeeds even if the terminal atomic name is not bound in the target context, but throws NameNotFoundException if any of the intermediate contexts do not exist.

Any attributes associated with the name are removed. Intermediate contexts are not changed.

Specified by:
unbind in interface Context
Parameters:
name - the name to unbind; may not be empty
Throws:
NameNotFoundException - if an intermediate context does not exist
NamingException - if a naming exception is encountered
See Also:
Context.unbind(String)

rename

public void rename(String oldName,
                   String newName)
            throws NamingException
Description copied from interface: Context
Binds a new name to the object bound to an old name, and unbinds the old name. See Context.rename(Name, Name) for details.

Specified by:
rename in interface Context
Parameters:
oldName - the name of the existing binding; may not be empty
newName - the name of the new binding; may not be empty
Throws:
NameAlreadyBoundException - if newName is already bound
NamingException - if a naming exception is encountered

rename

public void rename(Name oldName,
                   Name newName)
            throws NamingException
Description copied from interface: Context
Binds a new name to the object bound to an old name, and unbinds the old name. Both names are relative to this context. Any attributes associated with the old name become associated with the new name. Intermediate contexts of the old name are not changed.

Specified by:
rename in interface Context
Parameters:
oldName - the name of the existing binding; may not be empty
newName - the name of the new binding; may not be empty
Throws:
NameAlreadyBoundException - if newName is already bound
NamingException - if a naming exception is encountered
See Also:
Context.rename(String, String),
Context.bind(Name, Object),
Context.rebind(Name, Object)

list

public NamingEnumeration<NameClassPair> list(String name)
                                      throws NamingException
Description copied from interface: Context
Enumerates the names bound in the named context, along with the class names of objects bound to them. See Context.list(Name) for details.

Specified by:
list in interface Context
Parameters:
name - the name of the context to list
Returns:
an enumeration of the names and class names of the bindings in this context. Each element of the enumeration is of type NameClassPair.
Throws:
NamingException - if a naming exception is encountered

list

public NamingEnumeration<NameClassPair> list(Name name)
                                      throws NamingException
Description copied from interface: Context
Enumerates the names bound in the named context, along with the class names of objects bound to them. The contents of any subcontexts are not included.

If a binding is added to or removed from this context, its effect on an enumeration previously returned is undefined.

Specified by:
list in interface Context
Parameters:
name - the name of the context to list
Returns:
an enumeration of the names and class names of the bindings in this context. Each element of the enumeration is of type NameClassPair.
Throws:
NamingException - if a naming exception is encountered
See Also:
Context.list(String), Context.listBindings(Name), NameClassPair

listBindings

public NamingEnumeration<Binding> listBindings(String name)
                                        throws NamingException
Description copied from interface: Context
Enumerates the names bound in the named context, along with the objects bound to them. See Context.listBindings(Name) for details.

Specified by:
listBindings in interface Context
Parameters:
name - the name of the context to list
Returns:
an enumeration of the bindings in this context. Each element of the enumeration is of type Binding.
Throws:
NamingException - if a naming exception is encountered

listBindings

public NamingEnumeration<Binding> listBindings(Name name)
                                        throws NamingException
Description copied from interface: Context
Enumerates the names bound in the named context, along with the objects bound to them. The contents of any subcontexts are not included.

If a binding is added to or removed from this context, its effect on an enumeration previously returned is undefined.

Specified by:
listBindings in interface Context
Parameters:
name - the name of the context to list
Returns:
an enumeration of the bindings in this context. Each element of the enumeration is of type Binding.
Throws:
NamingException - if a naming exception is encountered
See Also:
Context.listBindings(String), Context.list(Name), Binding

destroySubcontext

public void destroySubcontext(String name)
                       throws NamingException
Description copied from interface: Context
Destroys the named context and removes it from the namespace. See Context.destroySubcontext(Name) for details.

Specified by:
destroySubcontext in interface Context
Parameters:
name - the name of the context to be destroyed; may not be empty
Throws:
NameNotFoundException - if an intermediate context does not exist
NotContextException - if the name is bound but does not name a context, or does not name a context of the appropriate type
ContextNotEmptyException - if the named context is not empty
NamingException - if a naming exception is encountered

destroySubcontext

public void destroySubcontext(Name name)
                       throws NamingException
Description copied from interface: Context
Destroys the named context and removes it from the namespace. Any attributes associated with the name are also removed. Intermediate contexts are not destroyed.

This method is idempotent. It succeeds even if the terminal atomic name is not bound in the target context, but throws NameNotFoundException if any of the intermediate contexts do not exist.

In a federated naming system, a context from one naming system may be bound to a name in another. One can subsequently look up and perform operations on the foreign context using a composite name. However, an attempt destroy the context using this composite name will fail with NotContextException, because the foreign context is not a "subcontext" of the context in which it is bound. Instead, use unbind() to remove the binding of the foreign context. Destroying the foreign context requires that the destroySubcontext() be performed on a context from the foreign context's "native" naming system.

Specified by:
destroySubcontext in interface Context
Parameters:
name - the name of the context to be destroyed; may not be empty
Throws:
NameNotFoundException - if an intermediate context does not exist
NotContextException - if the name is bound but does not name a context, or does not name a context of the appropriate type
ContextNotEmptyException - if the named context is not empty
NamingException - if a naming exception is encountered
See Also:
Context.destroySubcontext(String)

createSubcontext

public Context createSubcontext(String name)
                         throws NamingException
Description copied from interface: Context
Creates and binds a new context. See Context.createSubcontext(Name) for details.

Specified by:
createSubcontext in interface Context
Parameters:
name - the name of the context to create; may not be empty
Returns:
the newly created context
Throws:
NameAlreadyBoundException - if name is already bound
InvalidAttributesException - if creation of the subcontext requires specification of mandatory attributes
NamingException - if a naming exception is encountered

createSubcontext

public Context createSubcontext(Name name)
                         throws NamingException
Description copied from interface: Context
Creates and binds a new context. Creates a new context with the given name and binds it in the target context (that named by all but terminal atomic component of the name). All intermediate contexts and the target context must already exist.

Specified by:
createSubcontext in interface Context
Parameters:
name - the name of the context to create; may not be empty
Returns:
the newly created context
Throws:
NameAlreadyBoundException - if name is already bound
InvalidAttributesException - if creation of the subcontext requires specification of mandatory attributes
NamingException - if a naming exception is encountered
See Also:
Context.createSubcontext(String), DirContext.createSubcontext(javax.naming.Name, javax.naming.directory.Attributes)

lookupLink

public Object lookupLink(String name)
                  throws NamingException
Description copied from interface: Context
Retrieves the named object, following links except for the terminal atomic component of the name. See Context.lookupLink(Name) for details.

Specified by:
lookupLink in interface Context
Parameters:
name - the name of the object to look up
Returns:
the object bound to name, not following the terminal link (if any)
Throws:
NamingException - if a naming exception is encountered

lookupLink

public Object lookupLink(Name name)
                  throws NamingException
Description copied from interface: Context
Retrieves the named object, following links except for the terminal atomic component of the name. If the object bound to name is not a link, returns the object itself.

Specified by:
lookupLink in interface Context
Parameters:
name - the name of the object to look up
Returns:
the object bound to name, not following the terminal link (if any).
Throws:
NamingException - if a naming exception is encountered
See Also:
Context.lookupLink(String)

getNameParser

public NameParser getNameParser(String name)
                         throws NamingException
Description copied from interface: Context
Retrieves the parser associated with the named context. See Context.getNameParser(Name) for details.

Specified by:
getNameParser in interface Context
Parameters:
name - the name of the context from which to get the parser
Returns:
a name parser that can parse compound names into their atomic components
Throws:
NamingException - if a naming exception is encountered

getNameParser

public NameParser getNameParser(Name name)
                         throws NamingException
Description copied from interface: Context
Retrieves the parser associated with the named context. In a federation of namespaces, different naming systems will parse names differently. This method allows an application to get a parser for parsing names into their atomic components using the naming convention of a particular naming system. Within any single naming system, NameParser objects returned by this method must be equal (using the equals() test).

Specified by:
getNameParser in interface Context
Parameters:
name - the name of the context from which to get the parser
Returns:
a name parser that can parse compound names into their atomic components
Throws:
NamingException - if a naming exception is encountered
See Also:
Context.getNameParser(String), CompoundName

composeName

public String composeName(String name,
                          String prefix)
                   throws NamingException
Composes the name of this context with a name relative to this context. Since an initial context may never be named relative to any context other than itself, the value of the prefix parameter must be an empty name ("").

Specified by:
composeName in interface Context
Parameters:
name - a name relative to this context
prefix - the name of this context relative to one of its ancestors
Returns:
the composition of prefix and name
Throws:
NamingException - if a naming exception is encountered

composeName

public Name composeName(Name name,
                        Name prefix)
                 throws NamingException
Composes the name of this context with a name relative to this context. Since an initial context may never be named relative to any context other than itself, the value of the prefix parameter must be an empty name.

Specified by:
composeName in interface Context
Parameters:
name - a name relative to this context
prefix - the name of this context relative to one of its ancestors
Returns:
the composition of prefix and name
Throws:
NamingException - if a naming exception is encountered
See Also:
Context.composeName(String, String)

addToEnvironment

public Object addToEnvironment(String propName,
                               Object propVal)
                        throws NamingException
Description copied from interface: Context
Adds a new environment property to the environment of this context. If the property already exists, its value is overwritten. See class description for more details on environment properties.

Specified by:
addToEnvironment in interface Context
Parameters:
propName - the name of the environment property to add; may not be null
propVal - the value of the property to add; may not be null
Returns:
the previous value of the property, or null if the property was not in the environment before
Throws:
NamingException - if a naming exception is encountered
See Also:
Context.getEnvironment(), Context.removeFromEnvironment(String)

removeFromEnvironment

public Object removeFromEnvironment(String propName)
                             throws NamingException
Description copied from interface: Context
Removes an environment property from the environment of this context. See class description for more details on environment properties.

Specified by:
removeFromEnvironment in interface Context
Parameters:
propName - the name of the environment property to remove; may not be null
Returns:
the previous value of the property, or null if the property was not in the environment
Throws:
NamingException - if a naming exception is encountered
See Also:
Context.getEnvironment(), Context.addToEnvironment(String, Object)

getEnvironment

public Hashtable<?,?> getEnvironment()
                              throws NamingException
Description copied from interface: Context
Retrieves the environment in effect for this context. See class description for more details on environment properties.

The caller should not make any changes to the object returned: their effect on the context is undefined. The environment of this context may be changed using addToEnvironment() and removeFromEnvironment().

Specified by:
getEnvironment in interface Context
Returns:
the environment of this context; never null
Throws:
NamingException - if a naming exception is encountered
See Also:
Context.addToEnvironment(String, Object), Context.removeFromEnvironment(String)

close

public void close()
           throws NamingException
Description copied from interface: Context
Closes this context. This method releases this context's resources immediately, instead of waiting for them to be released automatically by the garbage collector.

This method is idempotent: invoking it on a context that has already been closed has no effect. Invoking any other method on a closed context is not allowed, and results in undefined behaviour.

Specified by:
close in interface Context
Throws:
NamingException - if a naming exception is encountered

getNameInNamespace

public String getNameInNamespace()
                          throws NamingException
Description copied from interface: Context
Retrieves the full name of this context within its own namespace.

Many naming services have a notion of a "full name" for objects in their respective namespaces. For example, an LDAP entry has a distinguished name, and a DNS record has a fully qualified name. This method allows the client application to retrieve this name. The string returned by this method is not a JNDI composite name and should not be passed directly to context methods. In naming systems for which the notion of full name does not make sense, OperationNotSupportedException is thrown.

Specified by:
getNameInNamespace in interface Context
Returns:
this context's name in its own namespace; never null
Throws:
OperationNotSupportedException - if the naming system does not have the notion of a full name
NamingException - if a naming exception is encountered
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InsufficientResourcesException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class InsufficientResourcesException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.InsufficientResourcesException
All Implemented Interfaces:
Serializable
public class InsufficientResourcesException
extends NamingException

This exception is thrown when resources are not available to complete the requested operation. This might due to a lack of resources on the server or on the client. There are no restrictions to resource types, as different services might make use of different resources. Such restrictions might be due to physical limits and/or adminstrative quotas. Examples of limited resources are internal buffers, memory, network bandwidth.

InsufficientResourcesException is different from LimitExceededException in that the latter is due to user/system specified limits. See LimitExceededException for details.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
InsufficientResourcesException()
Constructs a new instance of InsufficientResourcesException with all name resolution fields and explanation initialized to null.
InsufficientResourcesException(String explanation)
Constructs a new instance of InsufficientResourcesException using an explanation.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InsufficientResourcesException

public InsufficientResourcesException(String explanation)
Constructs a new instance of InsufficientResourcesException using an explanation. All other fields default to null.

Parameters:
explanation - Possibly null additional detail about this exception.
See Also:
Throwable.getMessage()

InsufficientResourcesException

public InsufficientResourcesException()
Constructs a new instance of InsufficientResourcesException with all name resolution fields and explanation initialized to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InterruptedNamingException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class InterruptedNamingException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.InterruptedNamingException
All Implemented Interfaces:
Serializable
public class InterruptedNamingException
extends NamingException

This exception is thrown when the naming operation being invoked has been interrupted. For example, an application might interrupt a thread that is performing a search. If the search supports being interrupted, it will throw InterruptedNamingException. Whether an operation is interruptible and when depends on its implementation (as provided by the service providers). Different implementations have different ways of protecting their resources and objects from being damaged due to unexpected interrupts.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Context, DirContext, Thread.interrupt(), InterruptedException, Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
InterruptedNamingException()
Constructs an instance of InterruptedNamingException with all name resolution fields and explanation initialized to null.
InterruptedNamingException(String explanation)
Constructs an instance of InterruptedNamingException using an explanation of the problem.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InterruptedNamingException

public InterruptedNamingException(String explanation)
Constructs an instance of InterruptedNamingException using an explanation of the problem. All name resolution-related fields are initialized to null.

Parameters:
explanation - A possibly null message explaining the problem.
See Also:
Throwable.getMessage()

InterruptedNamingException

public InterruptedNamingException()
Constructs an instance of InterruptedNamingException with all name resolution fields and explanation initialized to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidNameException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class InvalidNameException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.InvalidNameException
All Implemented Interfaces:
Serializable
public class InvalidNameException
extends NamingException

This exception indicates that the name being specified does not conform to the naming syntax of a naming system. This exception is thrown by any of the methods that does name parsing (such as those in Context, DirContext, CompositeName and CompoundName).

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Context, DirContext, CompositeName, CompoundName, NameParser, Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
InvalidNameException()
Constructs an instance of InvalidNameException with all fields set to null.
InvalidNameException(String explanation)
Constructs an instance of InvalidNameException using an explanation of the problem.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidNameException

public InvalidNameException(String explanation)
Constructs an instance of InvalidNameException using an explanation of the problem. All other fields are initialized to null.

Parameters:
explanation - A possibly null message explaining the problem.
See Also:
Throwable.getMessage()

InvalidNameException

public InvalidNameException()
Constructs an instance of InvalidNameException with all fields set to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ldap

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.naming.ldap

Provides support for LDAPv3 extended operations and controls.

See:
Description

Interface Summary
Control | This interface represents an LDAPv3 control as defined in RFC 2251.
ExtendedRequest | This interface represents an LDAPv3 extended operation request as defined in RFC 2251.
ExtendedResponse | This interface represents an LDAP extended operation response as defined in RFC 2251.
HasControls | This interface is for returning controls with objects returned in NamingEnumerations.
LdapContext | This interface represents a context in which you can perform operations with LDAPv3-style controls and perform LDAPv3-style extended operations.
UnsolicitedNotification | This interface represents an unsolicited notification as defined in RFC 2251.
UnsolicitedNotificationListener | This interface is for handling UnsolicitedNotificationEvent.

Class Summary
BasicControl | This class provides a basic implementation of the Control interface.
ControlFactory | This abstract class represents a factory for creating LDAPv3 controls.
InitialLdapContext | This class is the starting context for performing LDAPv3-style extended operations and controls.
LdapName | This class represents a distinguished name as specified by RFC 2253.
ManageReferralControl | Requests that referral and other special LDAP objects be manipulated as normal LDAP objects.
PagedResultsControl | Requests that the results of a search operation be returned by the LDAP server in batches of a specified size.
PagedResultsResponseControl | Indicates the end of a batch of search results.
Rdn | This class represents a relative distinguished name, or RDN, which is a component of a distinguished name as specified by RFC 2253.
SortControl | Requests that the results of a search operation be sorted by the LDAP server before being returned.
SortKey | A sort key and its associated sort parameters.
SortResponseControl | Indicates whether the requested sort of search results was successful or not.
StartTlsRequest | This class implements the LDAPv3 Extended Request for StartTLS as defined in Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security The object identifier for StartTLS is 1.3.6.1.4.1.1466.20037 and no extended request value is defined.
StartTlsResponse | This class implements the LDAPv3 Extended Response for StartTLS as defined in Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security The object identifier for StartTLS is 1.3.6.1.4.1.1466.20037 and no extended response value is defined.
UnsolicitedNotificationEvent | This class represents an event fired in response to an unsolicited notification sent by the LDAP server.

Exception Summary
LdapReferralException This abstract class is used to represent an LDAP referral exception.

Package javax.naming.ldap Description

Provides support for LDAPv3 extended operations and controls.

This package extends the directory operations of the Java Naming and Directory InterfaceTM (JNDI). JNDI provides naming and directory functionality to applications written in the Java programming language. It is designed to be independent of any specific naming or directory service implementation. Thus a variety of services--new, emerging, and already deployed ones--can be accessed in a common way.

This package is for applications and service providers that deal with LDAPv3 extended operations and controls, as defined by RFC 2251. The core interface in this package is LdapContext, which defines methods on a context for performing extended operations and handling controls.

Extended Operations

This package defines the interface ExtendedRequest to represent the argument to an extended operation, and the interface ExtendedResponse to represent the result of the extended operation. An extended response is always paired with an extended request but not necessarily vice versa. That is, you can have an extended request that has no corresponding extended response.

An application typically does not deal directly with these interfaces. Instead, it deals with classes that implement these interfaces. The application gets these classes either as part of a repertoire of extended operations standardized through the IETF, or from directory vendors for vendor-specific extended operations. The request classes should have constructors that accept arguments in a type-safe and user-friendly manner, while the response classes should have access methods for getting the data of the response in a type-safe and user-friendly manner. Internally, the request/response classes deal with encoding and decoding BER values.

For example, suppose an LDAP server supports a "get time" extended operation. It would supply classes such as GetTimeRequest and GetTimeResponse, so that applications can use this feature. An application would use these classes as follows:

GetTimeResponse resp =
    (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
long time = resp.getTime();

The GetTimeRequest and GetTimeResponse classes might be defined as follows:

public class GetTimeRequest implements ExtendedRequest {
    // User-friendly constructor
    public GetTimeRequest() {
    };

    // Methods used by service providers
    public String getID() {
        return GETTIME_REQ_OID;
    }
    public byte[] getEncodedValue() {
        return null;  // no value needed for get time request
    }
    public ExtendedResponse createExtendedResponse(
        String id, byte[] berValue, int offset, int length) throws NamingException {
        return new GetTimeResponse(id, berValue, offset, length);
    }
}
public class GetTimeResponse() implements ExtendedResponse {
    long time;
    // called by GetTimeRequest.createExtendedResponse()
    public GetTimeResponse(String id, byte[] berValue, int offset, int length)
        throws NamingException {
        // check validity of id
        long time =  ... // decode berValue to get time
    }

    // Type-safe and User-friendly methods
    public java.util.Date getDate() { return new java.util.Date(time); }
    public long getTime() { return time; }

    // Low level methods
    public byte[] getEncodedValue() {
        return // berValue saved;
    }
    public String getID() {
        return GETTIME_RESP_OID;
    }
}

Controls

This package defines the interface Control to represent an LDAPv3 control. It can be a control that is sent to an LDAP server (request control) or a control returned by an LDAP server (response control). Unlike extended requests and responses, there is not necessarily any pairing between request controls and response controls. You can send request controls and expect no response controls back, or receive response controls without sending any request controls.

An application typically does not deal directly with this interface. Instead, it deals with classes that implement this interface. The application gets control classes either as part of a repertoire of controls standardized through the IETF, or from directory vendors for vendor-specific controls. The request control classes should have constructors that accept arguments in a type-safe and user-friendly manner, while the response control classes should have access methods for getting the data of the response in a type-safe and user-friendly manner. Internally, the request/response control classes deal with encoding and decoding BER values.

For example, suppose an LDAP server supports a "signed results" request control, which when sent with a request, asks the server to digitally sign the results of an operation. It would supply a class SignedResultsControl so that applications can use this feature. An application would use this class as follows:

Control[] reqCtls = new Control[] {new SignedResultsControl(Control.CRITICAL)};
ectx.setRequestControls(reqCtls);
NamingEnumeration enum = ectx.search(...);
The SignedResultsControl class might be defined as follows:
public class SignedResultsControl implements Control {
    // User-friendly constructor
    public SignedResultsControl(boolean criticality) {
        // assemble the components of the request control
    };

    // Methods used by service providers
    public String getID() {
        return // control's object identifier
    }
    public byte[] getEncodedValue() {
        return // ASN.1 BER encoded control value
    }
    ...
}

When a service provider receives response controls, it uses the ControlFactory class to produce specific classes that implement the Control interface.

An LDAP server can send back response controls with an LDAP operation and also with enumeration results, such as those returned by a list or search operation. The LdapContext provides a method (getResponseControls()) for getting the response controls sent with an LDAP operation, while the HasControls interface is used to retrieve response controls associated with enumeration results.

For example, suppose an LDAP server sends back a "change ID" control in response to a successful modification. It would supply a class ChangeIDControl so that the application can use this feature. An application would perform an update, and then try to get the change ID.

// Perform update
Context ctx = ectx.createSubsubcontext("cn=newobj");

// Get response controls
Control[] respCtls = ectx.getResponseControls();
if (respCtls != null) {
    // Find the one we want
    for (int i = 0; i < respCtls; i++) {
        if(respCtls[i] instanceof ChangeIDControl) {
            ChangeIDControl cctl = (ChangeIDControl)respCtls[i];
            System.out.println(cctl.getChangeID());
        }
    }
}
The vendor might supply the following ChangeIDControl and VendorXControlFactory classes. The VendorXControlFactory will be used by the service provider when the provider receives response controls from the LDAP server.
public class ChangeIDControl implements Control {
    long id;

    // Constructor used by ControlFactory
    public ChangeIDControl(String OID, byte[] berVal) throws NamingException {
        // check validity of OID
        id = // extract change ID from berVal
    };

    // Type-safe and User-friendly method
    public long getChangeID() {
        return id;
    }

    // Low-level methods
    public String getID() {
        return CHANGEID_OID;
    }
    public byte[] getEncodedValue() {
        return // original berVal
    }
    ...
}
public class VendorXControlFactory extends ControlFactory {
    public VendorXControlFactory () {
    }

    public Control getControlInstance(Control orig) throws NamingException {
        if (isOneOfMyControls(orig.getID())) {
            ...

            // determine which of ours it is and call its constructor
            return (new ChangeIDControl(orig.getID(), orig.getEncodedValue()));
        }
        return null;  // not one of ours
    }
}

Package Specification

The JNDI API Specification and related documents can be found in the JNDI documentation.

Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.naming.ldap Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.naming.ldap

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.naming.ldap.BasicControl (implements javax.naming.ldap.Control)
      • javax.naming.ldap.ManageReferralControl
      • javax.naming.ldap.PagedResultsControl
      • javax.naming.ldap.PagedResultsResponseControl
      • javax.naming.ldap.SortControl
      • javax.naming.ldap.SortResponseControl
    • javax.naming.ldap.ControlFactory
    • java.util.EventObject (implements java.io.Serializable)
      • javax.naming.ldap.UnsolicitedNotificationEvent
    • javax.naming.InitialContext (implements javax.naming.Context)
      • javax.naming.directory.InitialDirContext (implements javax.naming.directory.DirContext)
        • javax.naming.ldap.InitialLdapContext (implements javax.naming.ldap.LdapContext)
    • javax.naming.ldap.LdapName (implements javax.naming.Name)
    • javax.naming.ldap.Rdn (implements java.lang.Comparable<T>, java.io.Serializable)
    • javax.naming.ldap.SortKey
    • javax.naming.ldap.StartTlsRequest (implements javax.naming.ldap.ExtendedRequest)
    • javax.naming.ldap.StartTlsResponse (implements javax.naming.ldap.ExtendedResponse)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.naming.NamingException
          • javax.naming.ReferralException
            • javax.naming.ldap.LdapReferralException

Interface Hierarchy

  • javax.naming.Context
    • javax.naming.directory.DirContext
      • javax.naming.ldap.LdapContext
  • java.util.EventListener
    • javax.naming.event.NamingListener
      • javax.naming.ldap.UnsolicitedNotificationListener
  • javax.naming.ldap.HasControls
    • javax.naming.ldap.UnsolicitedNotification (also extends javax.naming.ldap.ExtendedResponse)
  • java.io.Serializable
    • javax.naming.ldap.Control
    • javax.naming.ldap.ExtendedRequest
    • javax.naming.ldap.ExtendedResponse
      • javax.naming.ldap.UnsolicitedNotification (also extends javax.naming.ldap.HasControls)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.naming.ldap

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.naming.ldap

Packages that use javax.naming.ldap
javax.naming.ldap Provides support for LDAPv3 extended operations and controls.

Classes in javax.naming.ldap used by javax.naming.ldap
BasicControl
This class provides a basic implementation of the Control interface.
Control
This interface represents an LDAPv3 control as defined in RFC 2251.
ExtendedRequest
This interface represents an LDAPv3 extended operation request as defined in RFC 2251.
ExtendedResponse
This interface represents an LDAP extended operation response as defined in RFC 2251.
HasControls
This interface is for returning controls with objects returned in NamingEnumerations.
LdapContext
This interface represents a context in which you can perform operations with LDAPv3-style controls and perform LDAPv3-style extended operations.
Rdn
This class represents a relative distinguished name, or RDN, which is a component of a distinguished name as specified by RFC 2253.
SortKey
A sort key and its associated sort parameters.
UnsolicitedNotification
This interface represents an unsolicited notification as defined in RFC 2251.
UnsolicitedNotificationEvent
This class represents an event fired in response to an unsolicited notification sent by the LDAP server.
UnsolicitedNotificationListener
This interface is for handling UnsolicitedNotificationEvent.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


BasicControl

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Class BasicControl

java.lang.Object
    extended by  javax.naming.ldap.BasicControl
All Implemented Interfaces:
Serializable, Control
Direct Known Subclasses:
ManageReferralControl, PagedResultsControl, PagedResultsResponseControl, SortControl, SortResponseControl
public class BasicControl
extends Object
implements Control

This class provides a basic implementation of the Control interface. It represents an LDAPv3 Control as defined in RFC 2251.

Since:
1.5
See Also:
Serialized Form

Field Summary
protected boolean | criticality The control's criticality.
protected String | id The control's object identifier string.
protected byte[] | value The control's ASN.1 BER encoded value.
Fields inherited from interface javax.naming.ldap.Control
CRITICAL, NONCRITICAL
Constructor Summary
BasicControl(String id)
Constructs a non-critical control.
BasicControl(String id, boolean criticality, byte[] value)
Constructs a control using the supplied arguments.
Method Summary
byte[] | getEncodedValue() Retrieves the control's ASN.1 BER encoded value.
String | getID() Retrieves the control's object identifier string.
boolean | isCritical() Determines the control's criticality.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

id

protected String id
The control's object identifier string.

criticality

protected boolean criticality
The control's criticality.

value

protected byte[] value
The control's ASN.1 BER encoded value.

Constructor Detail

BasicControl

public BasicControl(String id)
Constructs a non-critical control.

Parameters:
id - The control's object identifier string.

BasicControl

public BasicControl(String id,
                    boolean criticality,
                    byte[] value)
Constructs a control using the supplied arguments.

Parameters:
id - The control's object identifier string.
criticality - The control's criticality.
value - The control's ASN.1 BER encoded value. It is not cloned - any changes to value will affect the contents of the control. It may be null.
Method Detail

getID

public String getID()
Retrieves the control's object identifier string.

Specified by:
getID in interface Control
Returns:
The non-null object identifier string.

isCritical

public boolean isCritical()
Determines the control's criticality.

Specified by:
isCritical in interface Control
Returns:
true if the control is critical; false otherwise.

getEncodedValue

public byte[] getEncodedValue()
Retrieves the control's ASN.1 BER encoded value. The result includes the BER tag and length for the control's value but does not include the control's object identifier and criticality setting.

Specified by:
getEncodedValue in interface Control
Returns:
A possibly null byte array representing the control's ASN.1 BER encoded value. It is not cloned - any changes to the returned value will affect the contents of the control.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.naming.ldap.BasicControl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ldap.BasicControl

Packages that use BasicControl
javax.naming.ldap Provides support for LDAPv3 extended operations and controls.

Uses of BasicControl in javax.naming.ldap

Subclasses of BasicControl in javax.naming.ldap
class | ManageReferralControl Requests that referral and other special LDAP objects be manipulated as normal LDAP objects.
class | PagedResultsControl Requests that the results of a search operation be returned by the LDAP server in batches of a specified size.
class | PagedResultsResponseControl Indicates the end of a batch of search results.
class | SortControl Requests that the results of a search operation be sorted by the LDAP server before being returned.
class | SortResponseControl Indicates whether the requested sort of search results was successful or not.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ldap.ControlFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ldap.ControlFactory

No usage of javax.naming.ldap.ControlFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ldap.InitialLdapContext

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ldap.InitialLdapContext

No usage of javax.naming.ldap.InitialLdapContext

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ldap.LdapName

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ldap.LdapName

No usage of javax.naming.ldap.LdapName

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ldap.LdapReferralException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ldap.LdapReferralException

No usage of javax.naming.ldap.LdapReferralException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ldap.ManageReferralControl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ldap.ManageReferralControl

No usage of javax.naming.ldap.ManageReferralControl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ldap.PagedResultsControl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ldap.PagedResultsControl

No usage of javax.naming.ldap.PagedResultsControl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ldap.PagedResultsResponseControl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ldap.PagedResultsResponseControl

No usage of javax.naming.ldap.PagedResultsResponseControl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ldap.Rdn

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ldap.Rdn

Packages that use Rdn
javax.naming.ldap Provides support for LDAPv3 extended operations and controls.

Uses of Rdn in javax.naming.ldap

Methods in javax.naming.ldap that return Rdn
 Rdn LdapName.getRdn(int posn)
Retrieves an RDN of this LDAP name as an Rdn.

Methods in javax.naming.ldap that return types with arguments of type Rdn
 List<Rdn> LdapName.getRdns()
Retrieves the list of relative distinguished names.

Methods in javax.naming.ldap with parameters of type Rdn
Name | LdapName.add(int posn, Rdn comp) Adds a single RDN at a specified position within this LDAP name.
Name | LdapName.add(Rdn comp) Adds a single RDN to the end of this LDAP name.

Method parameters in javax.naming.ldap with type arguments of type Rdn
Name | LdapName.addAll(int posn, List<Rdn> suffixRdns) Adds the RDNs of a name -- in order -- at a specified position within this name.
Name | LdapName.addAll(List<Rdn> suffixRdns) Adds the RDNs of a name -- in order -- to the end of this name.
boolean | LdapName.endsWith(List<Rdn> rdns) Determines whether the specified RDN sequence forms a suffix of this LDAP name.
boolean | LdapName.startsWith(List<Rdn> rdns) Determines whether the specified RDN sequence forms a prefix of this LDAP name.

Constructors in javax.naming.ldap with parameters of type Rdn
Rdn(Rdn rdn)
Constructs an Rdn from the given rdn.

Constructor parameters in javax.naming.ldap with type arguments of type Rdn
LdapName(List<Rdn> rdns)
Constructs an LDAP name given its parsed RDN components.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ldap.SortControl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ldap.SortControl

No usage of javax.naming.ldap.SortControl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ldap.SortKey

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ldap.SortKey

Packages that use SortKey
javax.naming.ldap Provides support for LDAPv3 extended operations and controls.

Uses of SortKey in javax.naming.ldap

Constructors in javax.naming.ldap with parameters of type SortKey
SortControl(SortKey[] sortBy, boolean criticality)
Constructs a control to sort on a list of sort keys.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ldap.SortResponseControl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ldap.SortResponseControl

No usage of javax.naming.ldap.SortResponseControl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ldap.StartTlsRequest

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ldap.StartTlsRequest

No usage of javax.naming.ldap.StartTlsRequest

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ldap.StartTlsResponse

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ldap.StartTlsResponse

No usage of javax.naming.ldap.StartTlsResponse

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.ldap.UnsolicitedNotificationEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.ldap.UnsolicitedNotificationEvent

Packages that use UnsolicitedNotificationEvent
javax.naming.ldap Provides support for LDAPv3 extended operations and controls.

Uses of UnsolicitedNotificationEvent in javax.naming.ldap

Methods in javax.naming.ldap with parameters of type UnsolicitedNotificationEvent
 void UnsolicitedNotificationListener.notificationReceived(UnsolicitedNotificationEvent evt)
Called when an unsolicited notification has been received.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.ldap.Control

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.ldap.Control

Packages that use Control
javax.naming.ldap Provides support for LDAPv3 extended operations and controls.

Uses of Control in javax.naming.ldap

Classes in javax.naming.ldap that implement Control
class | BasicControl This class provides a basic implementation of the Control interface.
class | ManageReferralControl Requests that referral and other special LDAP objects be manipulated as normal LDAP objects.
class | PagedResultsControl Requests that the results of a search operation be returned by the LDAP server in batches of a specified size.
class | PagedResultsResponseControl Indicates the end of a batch of search results.
class | SortControl Requests that the results of a search operation be sorted by the LDAP server before being returned.
class | SortResponseControl Indicates whether the requested sort of search results was successful or not.

Methods in javax.naming.ldap that return Control
Control[] | InitialLdapContext.getConnectControls()
Control[] | LdapContext.getConnectControls() Retrieves the connection request controls in effect for this context.
abstract Control | ControlFactory.getControlInstance(Control ctl) Creates a control using this control factory.
static Control | ControlFactory.getControlInstance(Control ctl, Context ctx, Hashtable<?,?> env) Creates a control using known control factories.
Control[] | HasControls.getControls() Retrieves an array of Controls from the object that implements this interface.
Control[] | InitialLdapContext.getRequestControls()
Control[] | LdapContext.getRequestControls() Retrieves the request controls in effect for this context.
Control[] | InitialLdapContext.getResponseControls()
Control[] | LdapContext.getResponseControls() Retrieves the response controls produced as a result of the last method invoked on this context.

Methods in javax.naming.ldap with parameters of type Control
abstract Control | ControlFactory.getControlInstance(Control ctl) Creates a control using this control factory.
static Control | ControlFactory.getControlInstance(Control ctl, Context ctx, Hashtable<?,?> env) Creates a control using known control factories.
abstract Context | LdapReferralException.getReferralContext(Hashtable<?,?> env, Control[] reqCtls) Retrieves the context at which to continue the method using request controls and environment properties.
LdapContext | InitialLdapContext.newInstance(Control[] reqCtls)
LdapContext | LdapContext.newInstance(Control[] requestControls) Creates a new instance of this context initialized using request controls.
void | InitialLdapContext.reconnect(Control[] connCtls)
void | LdapContext.reconnect(Control[] connCtls) Reconnects to the LDAP server using the supplied controls and this context's environment.
void | InitialLdapContext.setRequestControls(Control[] requestControls)
void | LdapContext.setRequestControls(Control[] requestControls) Sets the request controls for methods subsequently invoked on this context.

Constructors in javax.naming.ldap with parameters of type Control
InitialLdapContext(Hashtable<?,?> environment, Control[] connCtls)
Constructs an initial context using environment properties and connection request controls.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.ldap.ExtendedRequest

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.ldap.ExtendedRequest

Packages that use ExtendedRequest
javax.naming.ldap Provides support for LDAPv3 extended operations and controls.

Uses of ExtendedRequest in javax.naming.ldap

Classes in javax.naming.ldap that implement ExtendedRequest
 class StartTlsRequest
This class implements the LDAPv3 Extended Request for StartTLS as defined in Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security The object identifier for StartTLS is 1.3.6.1.4.1.1466.20037 and no extended request value is defined.

Methods in javax.naming.ldap with parameters of type ExtendedRequest
ExtendedResponse | InitialLdapContext.extendedOperation(ExtendedRequest request)
ExtendedResponse | LdapContext.extendedOperation(ExtendedRequest request) Performs an extended operation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.ldap.ExtendedResponse

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.ldap.ExtendedResponse

Packages that use ExtendedResponse
javax.naming.ldap Provides support for LDAPv3 extended operations and controls.

Uses of ExtendedResponse in javax.naming.ldap

Subinterfaces of ExtendedResponse in javax.naming.ldap
 interface UnsolicitedNotification
This interface represents an unsolicited notification as defined in RFC 2251.

Classes in javax.naming.ldap that implement ExtendedResponse
 class StartTlsResponse
This class implements the LDAPv3 Extended Response for StartTLS as defined in Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security The object identifier for StartTLS is 1.3.6.1.4.1.1466.20037 and no extended response value is defined.

Methods in javax.naming.ldap that return ExtendedResponse
ExtendedResponse | StartTlsRequest.createExtendedResponse(String id, byte[] berValue, int offset, int length) Creates an extended response object that corresponds to the LDAP StartTLS extended request.
ExtendedResponse | ExtendedRequest.createExtendedResponse(String id, byte[] berValue, int offset, int length) Creates the response object that corresponds to this request.
ExtendedResponse | InitialLdapContext.extendedOperation(ExtendedRequest request)
ExtendedResponse | LdapContext.extendedOperation(ExtendedRequest request) Performs an extended operation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.ldap.HasControls

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.ldap.HasControls

Packages that use HasControls
javax.naming.ldap Provides support for LDAPv3 extended operations and controls.

Uses of HasControls in javax.naming.ldap

Subinterfaces of HasControls in javax.naming.ldap
 interface UnsolicitedNotification
This interface represents an unsolicited notification as defined in RFC 2251.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.ldap.LdapContext

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.ldap.LdapContext

Packages that use LdapContext
javax.naming.ldap Provides support for LDAPv3 extended operations and controls.

Uses of LdapContext in javax.naming.ldap

Classes in javax.naming.ldap that implement LdapContext
 class InitialLdapContext
This class is the starting context for performing LDAPv3-style extended operations and controls.

Methods in javax.naming.ldap that return LdapContext
LdapContext | InitialLdapContext.newInstance(Control[] reqCtls)
LdapContext | LdapContext.newInstance(Control[] requestControls) Creates a new instance of this context initialized using request controls.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.ldap.UnsolicitedNotification

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.ldap.UnsolicitedNotification

Packages that use UnsolicitedNotification
javax.naming.ldap Provides support for LDAPv3 extended operations and controls.

Uses of UnsolicitedNotification in javax.naming.ldap

Methods in javax.naming.ldap that return UnsolicitedNotification
 UnsolicitedNotification UnsolicitedNotificationEvent.getNotification()
Returns the unsolicited notification.

Constructors in javax.naming.ldap with parameters of type UnsolicitedNotification
UnsolicitedNotificationEvent(Object src, UnsolicitedNotification notice)
Constructs a new instance of UnsolicitedNotificationEvent.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.ldap.UnsolicitedNotificationListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.ldap.UnsolicitedNotificationListener

Packages that use UnsolicitedNotificationListener
javax.naming.ldap Provides support for LDAPv3 extended operations and controls.

Uses of UnsolicitedNotificationListener in javax.naming.ldap

Methods in javax.naming.ldap with parameters of type UnsolicitedNotificationListener
 void UnsolicitedNotificationEvent.dispatch(UnsolicitedNotificationListener listener)
Invokes the notificationReceived() method on a listener using this event.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Control

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Interface Control

All Superinterfaces:
Serializable
All Known Implementing Classes:
BasicControl, ManageReferralControl, PagedResultsControl, PagedResultsResponseControl, SortControl, SortResponseControl
public interface Control
extends Serializable

This interface represents an LDAPv3 control as defined in RFC 2251.

The LDAPv3 protocol uses controls to send and receive additional data to affect the behavior of predefined operations. Controls can be sent along with any LDAP operation to the server. These are referred to as request controls. For example, a "sort" control can be sent with an LDAP search operation to request that the results be returned in a particular order. Solicited and unsolicited controls can also be returned with responses from the server. Such controls are referred to as response controls. For example, an LDAP server might define a special control to return change notifications.

This interface is used to represent both request and response controls.

Since:
1.3
See Also:
ControlFactory

Field Summary
static boolean | CRITICAL Indicates a critical control.
static boolean | NONCRITICAL Indicates a non-critical control.
Method Summary
byte[] | getEncodedValue() Retrieves the ASN.1 BER encoded value of the LDAP control.
String | getID() Retrieves the object identifier assigned for the LDAP control.
boolean | isCritical() Determines the criticality of the LDAP control.

Field Detail

CRITICAL

static final boolean CRITICAL
Indicates a critical control. The value of this constant is true.

See Also:
Constant Field Values

NONCRITICAL

static final boolean NONCRITICAL
Indicates a non-critical control. The value of this constant is false.

See Also:
Constant Field Values
Method Detail

getID

String getID()
Retrieves the object identifier assigned for the LDAP control.

Returns:
The non-null object identifier string.

isCritical

boolean isCritical()
Determines the criticality of the LDAP control. A critical control must not be ignored by the server. In other words, if the server receives a critical control that it does not support, regardless of whether the control makes sense for the operation, the operation will not be performed and an OperationNotSupportedException will be thrown.

Returns:
true if this control is critical; false otherwise.

getEncodedValue

byte[] getEncodedValue()
Retrieves the ASN.1 BER encoded value of the LDAP control. The result is the raw BER bytes including the tag and length of the control's value. It does not include the controls OID or criticality. Null is returned if the value is absent.

Returns:
A possibly null byte array representing the ASN.1 BER encoded value of the LDAP control.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ControlFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Class ControlFactory

java.lang.Object
    extended by  javax.naming.ldap.ControlFactory

public abstract class ControlFactory
extends Object

This abstract class represents a factory for creating LDAPv3 controls. LDAPv3 controls are defined in RFC 2251.

When a service provider receives a response control, it uses control factories to return the specific/appropriate control class implementation.

Since:
1.3
See Also:
Control

Constructor Summary
protected ControlFactory()
Method Summary
abstract Control | getControlInstance(Control ctl) Creates a control using this control factory.
static Control | getControlInstance(Control ctl, Context ctx, Hashtable<?,?> env) Creates a control using known control factories.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ControlFactory

protected ControlFactory()
Method Detail

getControlInstance

public abstract Control getControlInstance(Control ctl)
                                    throws NamingException
Creates a control using this control factory.

The factory is used by the service provider to return controls that it reads from the LDAP protocol as specialized control classes. Without this mechanism, the provider would be returning controls that only contained data in BER encoded format.

Typically, ctl is a "basic" control containing BER encoded data. The factory is used to create a specialized control implementation, usually by decoding the BER encoded data, that provides methods to access that data in a type-safe and friendly manner.

For example, a factory might use the BER encoded data in basic control and return an instance of a VirtualListReplyControl.

If this factory cannot create a control using the argument supplied, it should return null. A factory should only throw an exception if it is sure that it is the only intended factory and that no other control factories should be tried. This might happen, for example, if the BER data in the control does not match what is expected of a control with the given OID. Since this method throws NamingException, any other internally generated exception that should be propagated must be wrapped inside a NamingException.

Parameters:
ctl - A non-null control.
Returns:
A possibly null Control.
Throws:
NamingException - If ctl contains invalid data that prevents it from being used to create a control. A factory should only throw an exception if it knows how to produce the control (identified by the OID) but is unable to because of, for example invalid BER data.

getControlInstance

public static Control getControlInstance(Control ctl,
                                         Context ctx,
                                         Hashtable<?,?> env)
                                  throws NamingException
Creates a control using known control factories.

The following rule is used to create the control:

  • Use the control factories specified in the LdapContext.CONTROL_FACTORIES property of the environment, and of the provider resource file associated with ctx, in that order. The value of this property is a colon-separated list of factory class names that are tried in order, and the first one that succeeds in creating the control is the one used. If none of the factories can be loaded, return ctl. If an exception is encountered while creating the control, the exception is passed up to the caller.

Note that a control factory must be public and must have a public constructor that accepts no arguments.

Parameters:
ctl - The non-null control object containing the OID and BER data.
ctx - The possibly null context in which the control is being created. If null, no such information is available.
env - The possibly null environment of the context. This is used to find the value of the LdapContext.CONTROL_FACTORIES property.
Returns:
A control object created using ctl; or ctl if a control object cannot be created using the algorithm described above.
Throws:
NamingException - if a naming exception was encountered while attempting to create the control object. If one of the factories accessed throws an exception, it is propagated up to the caller. If an error was encountered while loading and instantiating the factory and object classes, the exception is wrapped inside a NamingException and then rethrown.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ExtendedRequest

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Interface ExtendedRequest

All Superinterfaces:
Serializable
All Known Implementing Classes:
StartTlsRequest
public interface ExtendedRequest
extends Serializable

This interface represents an LDAPv3 extended operation request as defined in RFC 2251.

     ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
              requestName      [0] LDAPOID,
              requestValue     [1] OCTET STRING OPTIONAL }
It comprises an object identifier string and an optional ASN.1 BER encoded value.

The methods in this class are used by the service provider to construct the bits to send to the LDAP server. Applications typically only deal with the classes that implement this interface, supplying them with any information required for a particular extended operation request. It would then pass such a class as an argument to the LdapContext.extendedOperation() method for performing the LDAPv3 extended operation.

For example, suppose the LDAP server supported a 'get time' extended operation. It would supply GetTimeRequest and GetTimeResponse classes:

 public class GetTimeRequest implements ExtendedRequest {
     public GetTimeRequest() {... };
     public ExtendedResponse createExtendedResponse(String id,
            byte[] berValue, int offset, int length)
            throws NamingException {
         return new GetTimeResponse(id, berValue, offset, length);
     }
     ...
 }
 public class GetTimeResponse implements ExtendedResponse {
     long time;
     public GetTimeResponse(String id, byte[] berValue, int offset,
            int length) throws NamingException {
         time = ... // decode berValue to get time
     }
     public java.util.Date getDate() { return new java.util.Date(time) };
     public long getTime() { return time };
     ...
 }
A program would use then these classes as follows:
 GetTimeResponse resp =
        (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
 long time = resp.getTime();

Since:
1.3
See Also:
ExtendedResponse, LdapContext.extendedOperation(javax.naming.ldap.ExtendedRequest)

Method Summary
ExtendedResponse | createExtendedResponse(String id, byte[] berValue, int offset, int length) Creates the response object that corresponds to this request.
byte[] | getEncodedValue() Retrieves the ASN.1 BER encoded value of the LDAP extended operation request.
String | getID() Retrieves the object identifier of the request.

Method Detail

getID

String getID()
Retrieves the object identifier of the request.

Returns:
The non-null object identifier string representing the LDAP ExtendedRequest.requestName component.

getEncodedValue

byte[] getEncodedValue()
Retrieves the ASN.1 BER encoded value of the LDAP extended operation request. Null is returned if the value is absent. The result is the raw BER bytes including the tag and length of the request value. It does not include the request OID. This method is called by the service provider to get the bits to put into the extended operation to be sent to the LDAP server.

Returns:
A possibly null byte array representing the ASN.1 BER encoded contents of the LDAP ExtendedRequest.requestValue component.
Throws:
IllegalStateException - If the encoded value cannot be retrieved because the request contains insufficient or invalid data/state.

createExtendedResponse

ExtendedResponse createExtendedResponse(String id,
                                        byte[] berValue,
                                        int offset,
                                        int length)
                                        throws NamingException
Creates the response object that corresponds to this request.

After the service provider has sent the extended operation request to the LDAP server, it will receive a response from the server. If the operation failed, the provider will throw a NamingException. If the operation succeeded, the provider will invoke this method using the data that it got back in the response. It is the job of this method to return a class that implements the ExtendedResponse interface that is appropriate for the extended operation request.

For example, a Start TLS extended request class would need to know how to process a Start TLS extended response. It does this by creating a class that implements ExtendedResponse.

Parameters:
id - The possibly null object identifier of the response control.
berValue - The possibly null ASN.1 BER encoded value of the response control. This is the raw BER bytes including the tag and length of the response value. It does not include the response OID.
offset - The starting position in berValue of the bytes to use.
length - The number of bytes in berValue to use.
Returns:
A non-null object.
Throws:
NamingException - if cannot create extended response due to an error.
See Also:
ExtendedResponse
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ExtendedResponse

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Interface ExtendedResponse

All Superinterfaces:
Serializable
All Known Subinterfaces:
UnsolicitedNotification
All Known Implementing Classes:
StartTlsResponse
public interface ExtendedResponse
extends Serializable

This interface represents an LDAP extended operation response as defined in RFC 2251.

     ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
          COMPONENTS OF LDAPResult,
          responseName     [10] LDAPOID OPTIONAL,
          response         [11] OCTET STRING OPTIONAL }
It comprises an optional object identifier and an optional ASN.1 BER encoded value.

The methods in this class can be used by the application to get low level information about the extended operation response. However, typically, the application will be using methods specific to the class that implements this interface. Such a class should have decoded the BER buffer in the response and should provide methods that allow the user to access that data in the response in a type-safe and friendly manner.

For example, suppose the LDAP server supported a 'get time' extended operation. It would supply GetTimeRequest and GetTimeResponse classes. The GetTimeResponse class might look like:

 public class GetTimeResponse implements ExtendedResponse {
     public java.util.Date getDate() {...};
     public long getTime() {...};
     ....
 }
A program would use then these classes as follows:
 GetTimeResponse resp =
        (GetTimeResponse) ectx.extendedOperation(new GetTimeRequest());
 java.util.Date now = resp.getDate();

Since:
1.3
See Also:
ExtendedRequest

Method Summary
byte[] | getEncodedValue() Retrieves the ASN.1 BER encoded value of the LDAP extended operation response.
String | getID() Retrieves the object identifier of the response.

Method Detail

getID

String getID()
Retrieves the object identifier of the response. The LDAP protocol specifies that the response object identifier is optional. If the server does not send it, the response will contain no ID (i.e. null).

Returns:
A possibly null object identifier string representing the LDAP ExtendedResponse.responseName component.

getEncodedValue

byte[] getEncodedValue()
Retrieves the ASN.1 BER encoded value of the LDAP extended operation response. Null is returned if the value is absent from the response sent by the LDAP server. The result is the raw BER bytes including the tag and length of the response value. It does not include the response OID.

Returns:
A possibly null byte array representing the ASN.1 BER encoded contents of the LDAP ExtendedResponse.response component.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HasControls

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Interface HasControls

All Known Subinterfaces:
UnsolicitedNotification
public interface HasControls

This interface is for returning controls with objects returned in NamingEnumerations. For example, suppose a server sends back controls with the results of a search operation, the service provider would return a NamingEnumeration of objects that are both SearchResult and implement HasControls.

   NamingEnumeration elts = ectx.search((Name)name, filter, sctls);
   while (elts.hasMore()) {
        Object entry = elts.next();

        // Get search result
        SearchResult res = (SearchResult)entry;
        // do something with it

        // Get entry controls
        if (entry instanceof HasControls) {
            Control[] entryCtls = ((HasControls)entry).getControls();
            // do something with controls
        }
   }

Since:
1.3

Method Summary
 Control[] getControls()
Retrieves an array of Controls from the object that implements this interface.

Method Detail

getControls

Control[] getControls()
                      throws NamingException
Retrieves an array of Controls from the object that implements this interface. It is null if there are no controls.

Returns:
A possibly null array of Control objects.
Throws:
NamingException - If cannot return controls due to an error.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InitialLdapContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Class InitialLdapContext

java.lang.Object
    extended by  javax.naming.InitialContext
        extended by  javax.naming.directory.InitialDirContext
            extended by  javax.naming.ldap.InitialLdapContext
All Implemented Interfaces:
Context, DirContext, LdapContext
public class InitialLdapContext
extends InitialDirContext
implements LdapContext

This class is the starting context for performing LDAPv3-style extended operations and controls.

See javax.naming.InitialContext and javax.naming.InitialDirContext for details on synchronization, and the policy for how an initial context is created.

Request Controls

When you create an initial context (InitialLdapContext), you can specify a list of request controls. These controls will be used as the request controls for any implicit LDAP "bind" operation performed by the context or contexts derived from the context. These are called connection request controls. Use getConnectControls() to get a context's connection request controls.

The request controls supplied to the initial context constructor are not used as the context request controls for subsequent context operations such as searches and lookups. Context request controls are set and updated by using setRequestControls().

As shown, there can be two different sets of request controls associated with a context: connection request controls and context request controls. This is required for those applications needing to send critical controls that might not be applicable to both the context operation and any implicit LDAP "bind" operation. A typical user program would do the following:

 InitialLdapContext lctx = new InitialLdapContext(env, critConnCtls);
 lctx.setRequestControls(critModCtls);
 lctx.modifyAttributes(name, mods);
 Controls[] respCtls =  lctx.getResponseControls();
It specifies first the critical controls for creating the initial context (critConnCtls), and then sets the context's request controls (critModCtls) for the context operation. If for some reason lctx needs to reconnect to the server, it will use critConnCtls. See the LdapContext interface for more discussion about request controls.

Service provider implementors should read the "Service Provider" section in the LdapContext class description for implementation details.

Since:
1.3
See Also:
LdapContext, InitialContext, InitialDirContext, NamingManager.setInitialContextFactoryBuilder(javax.naming.spi.InitialContextFactoryBuilder)

Field Summary
Fields inherited from class javax.naming.InitialContext
defaultInitCtx, gotDefault, myProps
Fields inherited from interface javax.naming.ldap.LdapContext
CONTROL_FACTORIES
Fields inherited from interface javax.naming.directory.DirContext
ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE
Fields inherited from interface javax.naming.Context
APPLET, AUTHORITATIVE, BATCHSIZE, DNS_URL, INITIAL_CONTEXT_FACTORY, LANGUAGE, OBJECT_FACTORIES, PROVIDER_URL, REFERRAL, SECURITY_AUTHENTICATION, SECURITY_CREDENTIALS, SECURITY_PRINCIPAL, SECURITY_PROTOCOL, STATE_FACTORIES, URL_PKG_PREFIXES
Constructor Summary
InitialLdapContext()
Constructs an initial context using no environment properties or connection request controls.
InitialLdapContext(Hashtable<?,?> environment, Control[] connCtls)
Constructs an initial context using environment properties and connection request controls.
Method Summary
ExtendedResponse | extendedOperation(ExtendedRequest request) Performs an extended operation.
Control[] | getConnectControls() Retrieves the connection request controls in effect for this context.
Control[] | getRequestControls() Retrieves the request controls in effect for this context.
Control[] | getResponseControls() Retrieves the response controls produced as a result of the last method invoked on this context.
LdapContext | newInstance(Control[] reqCtls) Creates a new instance of this context initialized using request controls.
void | reconnect(Control[] connCtls) Reconnects to the LDAP server using the supplied controls and this context's environment.
void | setRequestControls(Control[] requestControls) Sets the request controls for methods subsequently invoked on this context.
Methods inherited from class javax.naming.directory.InitialDirContext
bind, bind, createSubcontext, createSubcontext, getAttributes, getAttributes, getAttributes, getAttributes, getSchema, getSchema, getSchemaClassDefinition, getSchemaClassDefinition, modifyAttributes, modifyAttributes, modifyAttributes, modifyAttributes, rebind, rebind, search, search, search, search, search, search, search, search
Methods inherited from class javax.naming.InitialContext
addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, doLookup, doLookup, getDefaultInitCtx, getEnvironment, getNameInNamespace, getNameParser, getNameParser, getURLOrDefaultInitCtx, getURLOrDefaultInitCtx, init, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.naming.directory.DirContext
bind, bind, createSubcontext, createSubcontext, getAttributes, getAttributes, getAttributes, getAttributes, getSchema, getSchema, getSchemaClassDefinition, getSchemaClassDefinition, modifyAttributes, modifyAttributes, modifyAttributes, modifyAttributes, rebind, rebind, search, search, search, search, search, search, search, search
Methods inherited from interface javax.naming.Context
addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getEnvironment, getNameInNamespace, getNameParser, getNameParser, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind

Constructor Detail

InitialLdapContext

public InitialLdapContext()
                   throws NamingException
Constructs an initial context using no environment properties or connection request controls. Equivalent to new InitialLdapContext(null, null).

Throws:
NamingException - if a naming exception is encountered

InitialLdapContext

public InitialLdapContext(Hashtable<?,?> environment,
                          Control[] connCtls)
                   throws NamingException
Constructs an initial context using environment properties and connection request controls. See javax.naming.InitialContext for a discussion of environment properties.

This constructor will not modify its parameters or save references to them, but may save a clone or copy.

connCtls is used as the underlying context instance's connection request controls. See the class description for details.

Parameters:
environment - environment used to create the initial DirContext. Null indicates an empty environment.
connCtls - connection request controls for the initial context. If null, no connection request controls are used.
Throws:
NamingException - if a naming exception is encountered
See Also:
reconnect(javax.naming.ldap.Control[]), LdapContext.reconnect(javax.naming.ldap.Control[])
Method Detail

extendedOperation

public ExtendedResponse extendedOperation(ExtendedRequest request)
                                   throws NamingException
Description copied from interface: LdapContext
Performs an extended operation. This method is used to support LDAPv3 extended operations.

Specified by:
extendedOperation in interface LdapContext
Parameters:
request - The non-null request to be performed.
Returns:
The possibly null response of the operation. null means the operation did not generate any response.
Throws:
NamingException - If an error occurred while performing the extended operation.

newInstance

public LdapContext newInstance(Control[] reqCtls)
                        throws NamingException
Description copied from interface: LdapContext
Creates a new instance of this context initialized using request controls. This method is a convenience method for creating a new instance of this context for the purposes of multithreaded access. For example, if multiple threads want to use different context request controls, each thread may use this method to get its own copy of this context and set/get context request controls without having to synchronize with other threads.

The new context has the same environment properties and connection request controls as this context. See the class description for details. Implementations might also allow this context and the new context to share the same network connection or other resources if doing so does not impede the independence of either context.

Specified by:
newInstance in interface LdapContext
Parameters:
reqCtls - The possibly null request controls to use for the new context. If null, the context is initialized with no request controls.
Returns:
A non-null LdapContext instance.
Throws:
NamingException - If an error occurred while creating the new instance.
See Also:
InitialLdapContext

reconnect

public void reconnect(Control[] connCtls)
               throws NamingException
Description copied from interface: LdapContext
Reconnects to the LDAP server using the supplied controls and this context's environment.

This method is a way to explicitly initiate an LDAP "bind" operation. For example, you can use this method to set request controls for the LDAP "bind" operation, or to explicitly connect to the server to get response controls returned by the LDAP "bind" operation.

This method sets this context's connCtls to be its new connection request controls. This context's context request controls are not affected. After this method has been invoked, any subsequent implicit reconnections will be done using connCtls. connCtls are also used as connection request controls for new context instances derived from this context. These connection request controls are not affected by setRequestControls().

Service provider implementors should read the "Service Provider" section in the class description for implementation details.

Specified by:
reconnect in interface LdapContext
Parameters:
connCtls - The possibly null controls to use. If null, no controls are used.
Throws:
NamingException - If an error occurred while reconnecting.
See Also:
LdapContext.getConnectControls(), LdapContext.newInstance(javax.naming.ldap.Control[])

getConnectControls

public Control[] getConnectControls()
                             throws NamingException
Description copied from interface: LdapContext
Retrieves the connection request controls in effect for this context. The controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

Specified by:
getConnectControls in interface LdapContext
Returns:
A possibly-null array of controls. null means no connect controls have been set for this context.
Throws:
NamingException - If an error occurred while getting the request controls.

setRequestControls

public void setRequestControls(Control[] requestControls)
                        throws NamingException
Description copied from interface: LdapContext
Sets the request controls for methods subsequently invoked on this context. The request controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

This removes any previous request controls and adds requestControls for use by subsequent methods invoked on this context. This method does not affect this context's connection request controls.

Note that requestControls will be in effect until the next invocation of setRequestControls(). You need to explicitly invoke setRequestControls() with null or an empty array to clear the controls if you don't want them to affect the context methods any more. To check what request controls are in effect for this context, use getRequestControls().

Specified by:
setRequestControls in interface LdapContext
Parameters:
requestControls - The possibly null controls to use. If null, no controls are used.
Throws:
NamingException - If an error occurred while setting the request controls.
See Also:
LdapContext.getRequestControls()

getRequestControls

public Control[] getRequestControls()
                             throws NamingException
Description copied from interface: LdapContext
Retrieves the request controls in effect for this context. The request controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

Specified by:
getRequestControls in interface LdapContext
Returns:
A possibly-null array of controls. null means no request controls have been set for this context.
Throws:
NamingException - If an error occurred while getting the request controls.
See Also:
LdapContext.setRequestControls(javax.naming.ldap.Control[])

getResponseControls

public Control[] getResponseControls()
                              throws NamingException
Description copied from interface: LdapContext
Retrieves the response controls produced as a result of the last method invoked on this context. The response controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

These response controls might have been generated by a successful or failed operation.

When a context method that may return response controls is invoked, response controls from the previous method invocation are cleared. getResponseControls() returns all of the response controls generated by LDAP operations used by the context method in the order received from the LDAP server. Invoking getResponseControls() does not clear the response controls. You can call it many times (and get back the same controls) until the next context method that may return controls is invoked.

Specified by:
getResponseControls in interface LdapContext
Returns:
A possibly null array of controls. If null, the previous method invoked on this context did not produce any controls.
Throws:
NamingException - If an error occurred while getting the response controls.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LdapContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Interface LdapContext

All Superinterfaces:
Context, DirContext
All Known Implementing Classes:
InitialLdapContext
public interface LdapContext
extends DirContext

This interface represents a context in which you can perform operations with LDAPv3-style controls and perform LDAPv3-style extended operations. For applications that do not require such controls or extended operations, the more generic javax.naming.directory.DirContext should be used instead.

Usage Details About Controls

This interface provides support for LDAP v3 controls. At a high level, this support allows a user program to set request controls for LDAP operations that are executed in the course of the user program's invocation of Context/DirContext methods, and read response controls resulting from LDAP operations. At the implementation level, there are some details that developers of both the user program and service providers need to understand in order to correctly use request and response controls.

Request Controls

There are two types of request controls:

  • Request controls that affect how a connection is created
  • Request controls that affect context methods
The former is used whenever a connection needs to be established or re-established with an LDAP server. The latter is used when all other LDAP operations are sent to the LDAP server. The reason why a distinction between these two types of request controls is necessary is because JNDI is a high-level API that does not deal directly with connections. It is the job of service providers to do any necessary connection management. Consequently, a single connection may be shared by multiple context instances, and a service provider is free to use its own algorithms to conserve connection and network usage. Thus, when a method is invoked on the context instance, the service provider might need to do some connection management in addition to performing the corresponding LDAP operations. For connection management, it uses the connection request controls, while for the normal LDAP operations, it uses the context request controls.

Unless explicitly qualified, the term "request controls" refers to context request controls.

Context Request Controls

There are two ways in which a context instance gets its request controls:
  1. ldapContext.newInstance(reqCtls)
  2. ldapContext.setRequestControls(reqCtls)
where ldapContext is an instance of LdapContext. Specifying null or an empty array for reqCtls means no request controls. newInstance() creates a new instance of a context using reqCtls, while setRequestControls() updates an existing context instance's request controls to reqCtls.

Unlike environment properties, request controls of a context instance are not inherited by context instances that are derived from it. Derived context instances have null as their context request controls. You must set the request controls of a derived context instance explicitly using setRequestControls().

A context instance's request controls are retrieved using the method getRequestControls().

Connection Request Controls

There are three ways in which connection request controls are set:
  1. new InitialLdapContext(env, connCtls)
  2. refException.getReferralContext(env, connCtls)
  3. ldapContext.reconnect(connCtls);
where refException is an instance of LdapReferralException, and ldapContext is an instance of LdapContext. Specifying null or an empty array for connCtls means no connection request controls.

Like environment properties, connection request controls of a context are inherited by contexts that are derived from it. Typically, you initialize the connection request controls using the InitialLdapContext constructor or LdapReferralContext.getReferralContext(). These connection request controls are inherited by contexts that share the same connection--that is, contexts derived from the initial or referral contexts.

Use reconnect() to change the connection request controls of a context. Invoking ldapContext.reconnect() affects only the connection used by ldapContext and any new contexts instances that are derived form ldapContext. Contexts that previously shared the connection with ldapContext remain unchanged. That is, a context's connection request controls must be explicitly changed and is not affected by changes to another context's connection request controls.

A context instance's connection request controls are retrieved using the method getConnectControls().

Service Provider Requirements

A service provider supports connection and context request controls in the following ways. Context request controls must be associated on a per context instance basis while connection request controls must be associated on a per connection instance basis. The service provider must look for the connection request controls in the environment property "java.naming.ldap.control.connect" and pass this environment property on to context instances that it creates.

Response Controls

The method LdapContext.getResponseControls() is used to retrieve the response controls generated by LDAP operations executed as the result of invoking a Context/DirContext operation. The result is all of the responses controls generated by the underlying LDAP operations, including any implicit reconnection. To get only the reconnection response controls, use reconnect() followed by getResponseControls().

Parameters

A Control[] array passed as a parameter to any method is owned by the caller. The service provider will not modify the array or keep a reference to it, although it may keep references to the individual Control objects in the array. A Control[] array returned by any method is immutable, and may not subsequently be modified by either the caller or the service provider.

Since:
1.3
See Also:
InitialLdapContext, LdapReferralException.getReferralContext(java.util.Hashtable,javax.naming.ldap.Control[])

Field Summary
static String CONTROL_FACTORIES
Constant that holds the name of the environment property for specifying the list of control factories to use.
Fields inherited from interface javax.naming.directory.DirContext
ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE
Fields inherited from interface javax.naming.Context
APPLET, AUTHORITATIVE, BATCHSIZE, DNS_URL, INITIAL_CONTEXT_FACTORY, LANGUAGE, OBJECT_FACTORIES, PROVIDER_URL, REFERRAL, SECURITY_AUTHENTICATION, SECURITY_CREDENTIALS, SECURITY_PRINCIPAL, SECURITY_PROTOCOL, STATE_FACTORIES, URL_PKG_PREFIXES
Method Summary
ExtendedResponse | extendedOperation(ExtendedRequest request) Performs an extended operation.
Control[] | getConnectControls() Retrieves the connection request controls in effect for this context.
Control[] | getRequestControls() Retrieves the request controls in effect for this context.
Control[] | getResponseControls() Retrieves the response controls produced as a result of the last method invoked on this context.
LdapContext | newInstance(Control[] requestControls) Creates a new instance of this context initialized using request controls.
void | reconnect(Control[] connCtls) Reconnects to the LDAP server using the supplied controls and this context's environment.
void | setRequestControls(Control[] requestControls) Sets the request controls for methods subsequently invoked on this context.
Methods inherited from interface javax.naming.directory.DirContext
bind, bind, createSubcontext, createSubcontext, getAttributes, getAttributes, getAttributes, getAttributes, getSchema, getSchema, getSchemaClassDefinition, getSchemaClassDefinition, modifyAttributes, modifyAttributes, modifyAttributes, modifyAttributes, rebind, rebind, search, search, search, search, search, search, search, search
Methods inherited from interface javax.naming.Context
addToEnvironment, bind, bind, close, composeName, composeName, createSubcontext, createSubcontext, destroySubcontext, destroySubcontext, getEnvironment, getNameInNamespace, getNameParser, getNameParser, list, list, listBindings, listBindings, lookup, lookup, lookupLink, lookupLink, rebind, rebind, removeFromEnvironment, rename, rename, unbind, unbind

Field Detail

CONTROL_FACTORIES

static final String CONTROL_FACTORIES
Constant that holds the name of the environment property for specifying the list of control factories to use. The value of the property should be a colon-separated list of the fully qualified class names of factory classes that will create a control given another control. See ControlFactory.getControlInstance() for details. This property may be specified in the environment, an applet parameter, a system property, or one or more resource files.

The value of this constant is "java.naming.factory.control".

See Also:
ControlFactory, Context.addToEnvironment(java.lang.String, java.lang.Object), Context.removeFromEnvironment(java.lang.String), Constant Field Values
Method Detail

extendedOperation

ExtendedResponse extendedOperation(ExtendedRequest request)
                                   throws NamingException
Performs an extended operation. This method is used to support LDAPv3 extended operations.

Parameters:
request - The non-null request to be performed.
Returns:
The possibly null response of the operation. null means the operation did not generate any response.
Throws:
NamingException - If an error occurred while performing the extended operation.

newInstance

LdapContext newInstance(Control[] requestControls)
                        throws NamingException
Creates a new instance of this context initialized using request controls. This method is a convenience method for creating a new instance of this context for the purposes of multithreaded access. For example, if multiple threads want to use different context request controls, each thread may use this method to get its own copy of this context and set/get context request controls without having to synchronize with other threads.

The new context has the same environment properties and connection request controls as this context. See the class description for details. Implementations might also allow this context and the new context to share the same network connection or other resources if doing so does not impede the independence of either context.

Parameters:
requestControls - The possibly null request controls to use for the new context. If null, the context is initialized with no request controls.
Returns:
A non-null LdapContext instance.
Throws:
NamingException - If an error occurred while creating the new instance.
See Also:
InitialLdapContext

reconnect

void reconnect(Control[] connCtls)
               throws NamingException
Reconnects to the LDAP server using the supplied controls and this context's environment.

This method is a way to explicitly initiate an LDAP "bind" operation. For example, you can use this method to set request controls for the LDAP "bind" operation, or to explicitly connect to the server to get response controls returned by the LDAP "bind" operation.

This method sets this context's connCtls to be its new connection request controls. This context's context request controls are not affected. After this method has been invoked, any subsequent implicit reconnections will be done using connCtls. connCtls are also used as connection request controls for new context instances derived from this context. These connection request controls are not affected by setRequestControls().

Service provider implementors should read the "Service Provider" section in the class description for implementation details.

Parameters:
connCtls - The possibly null controls to use. If null, no controls are used.
Throws:
NamingException - If an error occurred while reconnecting.
See Also:
getConnectControls(), newInstance(javax.naming.ldap.Control[])

getConnectControls

Control[] getConnectControls()
                             throws NamingException
Retrieves the connection request controls in effect for this context. The controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

Returns:
A possibly-null array of controls. null means no connect controls have been set for this context.
Throws:
NamingException - If an error occurred while getting the request controls.

setRequestControls

void setRequestControls(Control[] requestControls)
                        throws NamingException
Sets the request controls for methods subsequently invoked on this context. The request controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

This removes any previous request controls and adds requestControls for use by subsequent methods invoked on this context. This method does not affect this context's connection request controls.

Note that requestControls will be in effect until the next invocation of setRequestControls(). You need to explicitly invoke setRequestControls() with null or an empty array to clear the controls if you don't want them to affect the context methods any more. To check what request controls are in effect for this context, use getRequestControls().

Parameters:
requestControls - The possibly null controls to use. If null, no controls are used.
Throws:
NamingException - If an error occurred while setting the request controls.
See Also:
getRequestControls()

getRequestControls

Control[] getRequestControls()
                             throws NamingException
Retrieves the request controls in effect for this context. The request controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

Returns:
A possibly-null array of controls. null means no request controls have been set for this context.
Throws:
NamingException - If an error occurred while getting the request controls.
See Also:
setRequestControls(javax.naming.ldap.Control[])

getResponseControls

Control[] getResponseControls()
                              throws NamingException
Retrieves the response controls produced as a result of the last method invoked on this context. The response controls are owned by the JNDI implementation and are immutable. Neither the array nor the controls may be modified by the caller.

These response controls might have been generated by a successful or failed operation.

When a context method that may return response controls is invoked, response controls from the previous method invocation are cleared. getResponseControls() returns all of the response controls generated by LDAP operations used by the context method in the order received from the LDAP server. Invoking getResponseControls() does not clear the response controls. You can call it many times (and get back the same controls) until the next context method that may return controls is invoked.

Returns:
A possibly null array of controls. If null, the previous method invoked on this context did not produce any controls.
Throws:
NamingException - If an error occurred while getting the response controls.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LdapName

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Class LdapName

java.lang.Object
    extended by  javax.naming.ldap.LdapName
All Implemented Interfaces:
Serializable, Cloneable, Comparable<Object>, Name
public class LdapName
extends Object
implements Name

This class represents a distinguished name as specified by RFC 2253. A distinguished name, or DN, is composed of an ordered list of components called relative distinguished names, or RDNs. Details of a DN's syntax are described in RFC 2253.

This class resolves a few ambiguities found in RFC 2253 as follows:

  • RFC 2253 leaves the term "whitespace" undefined. The ASCII space character 0x20 (" ") is used in its place.
  • Whitespace is allowed on either side of ',', ';', '=', and '+'. Such whitespace is accepted but not generated by this code, and is ignored when comparing names.
  • AttributeValue strings containing '=' or non-leading '#' characters (unescaped) are accepted.

String names passed to LdapName or returned by it use the full Unicode character set. They may also contain characters encoded into UTF-8 with each octet represented by a three-character substring such as "\\B4". They may not, however, contain characters encoded into UTF-8 with each octet represented by a single character in the string: the meaning would be ambiguous.

LdapName will properly parse all valid names, but does not attempt to detect all possible violations when parsing invalid names. It is "generous" in accepting invalid names. The "validity" of a name is determined ultimately when it is supplied to an LDAP server, which may accept or reject the name based on factors such as its schema information and interoperability considerations.

When names are tested for equality, attribute types, both binary and string values, are case-insensitive. String values with different but equivalent usage of quoting, escaping, or UTF8-hex-encoding are considered equal. The order of components in multi-valued RDNs (such as "ou=Sales+cn=Bob") is not significant.

The components of a LDAP name, that is, RDNs, are numbered. The indexes of a LDAP name with n RDNs range from 0 to n-1. This range may be written as [0,n). The right most RDN is at index 0, and the left most RDN is at index n-1. For example, the distinguished name: "CN=Steve Kille, O=Isode Limited, C=GB" is numbered in the following sequence ranging from 0 to 2: {C=GB, O=Isode Limited, CN=Steve Kille}. An empty LDAP name is represented by an empty RDN list.

Concurrent multithreaded read-only access of an instance of LdapName need not be synchronized.

Unless otherwise noted, the behavior of passing a null argument to a constructor or method in this class will cause a NullPointerException to be thrown.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
LdapName(List<Rdn> rdns)
Constructs an LDAP name given its parsed RDN components.
LdapName(String name)
Constructs an LDAP name from the given distinguished name.
Method Summary
Name | add(int posn, Rdn comp) Adds a single RDN at a specified position within this LDAP name.
Name | add(int posn, String comp) Adds a single component at a specified position within this LDAP name.
Name | add(Rdn comp) Adds a single RDN to the end of this LDAP name.
Name | add(String comp) Adds a single component to the end of this LDAP name.
Name | addAll(int posn, List<Rdn> suffixRdns) Adds the RDNs of a name -- in order -- at a specified position within this name.
Name | addAll(int posn, Name suffix) Adds the components of a name -- in order -- at a specified position within this name.
Name | addAll(List<Rdn> suffixRdns) Adds the RDNs of a name -- in order -- to the end of this name.
Name | addAll(Name suffix) Adds the components of a name -- in order -- to the end of this name.
Object | clone() Generates a new copy of this name.
int | compareTo(Object obj) Compares this LdapName with the specified Object for order.
boolean | endsWith(List<Rdn> rdns) Determines whether the specified RDN sequence forms a suffix of this LDAP name.
boolean | endsWith(Name n) Determines whether this LDAP name ends with a specified LDAP name suffix.
boolean | equals(Object obj) Determines whether two LDAP names are equal.
String | get(int posn) Retrieves a component of this LDAP name as a string.
Enumeration<String> | getAll() Retrieves the components of this name as an enumeration of strings.
Name | getPrefix(int posn) Creates a name whose components consist of a prefix of the components of this LDAP name.
Rdn | getRdn(int posn) Retrieves an RDN of this LDAP name as an Rdn.
List<Rdn> | getRdns() Retrieves the list of relative distinguished names.
Name | getSuffix(int posn) Creates a name whose components consist of a suffix of the components in this LDAP name.
int | hashCode() Computes the hash code of this LDAP name.
boolean | isEmpty() Determines whether this LDAP name is empty.
Object | remove(int posn) Removes a component from this LDAP name.
int | size() Retrieves the number of components in this LDAP name.
boolean | startsWith(List<Rdn> rdns) Determines whether the specified RDN sequence forms a prefix of this LDAP name.
boolean | startsWith(Name n) Determines whether this LDAP name starts with a specified LDAP name prefix.
String | toString() Returns a string representation of this LDAP name in a format defined by RFC 2253 and described in the class description.
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

LdapName

public LdapName(String name)
         throws InvalidNameException
Constructs an LDAP name from the given distinguished name.

Parameters:
name - This is a non-null distinguished name formatted according to the rules defined in RFC 2253.
Throws:
InvalidNameException - if a syntax violation is detected.
See Also:
Rdn.escapeValue(Object value)

LdapName

public LdapName(List<Rdn> rdns)
Constructs an LDAP name given its parsed RDN components.

The indexing of RDNs in the list follows the numbering of RDNs described in the class description.

Parameters:
rdns - The non-null list of Rdns forming this LDAP name.
Method Detail

size

public int size()
Retrieves the number of components in this LDAP name.

Specified by:
size in interface Name
Returns:
The non-negative number of components in this LDAP name.

isEmpty

public boolean isEmpty()
Determines whether this LDAP name is empty. An empty name is one with zero components.

Specified by:
isEmpty in interface Name
Returns:
true if this LDAP name is empty, false otherwise.

getAll

public Enumeration<String> getAll()
Retrieves the components of this name as an enumeration of strings. The effect of updates to this name on this enumeration is undefined. If the name has zero components, an empty (non-null) enumeration is returned. The order of the components returned by the enumeration is same as the order in which the components are numbered as described in the class description.

Specified by:
getAll in interface Name
Returns:
A non-null enumeration of the components of this LDAP name. Each element of the enumeration is of class String.

get

public String get(int posn)
Retrieves a component of this LDAP name as a string.

Specified by:
get in interface Name
Parameters:
posn - The 0-based index of the component to retrieve. Must be in the range [0,size()).
Returns:
The non-null component at index posn.
Throws:
IndexOutOfBoundsException - if posn is outside the specified range.

getRdn

public Rdn getRdn(int posn)
Retrieves an RDN of this LDAP name as an Rdn.

Parameters:
posn - The 0-based index of the RDN to retrieve. Must be in the range [0,size()).
Returns:
The non-null RDN at index posn.
Throws:
IndexOutOfBoundsException - if posn is outside the specified range.

getPrefix

public Name getPrefix(int posn)
Creates a name whose components consist of a prefix of the components of this LDAP name. Subsequent changes to this name will not affect the name that is returned and vice versa.

Specified by:
getPrefix in interface Name
Parameters:
posn - The 0-based index of the component at which to stop. Must be in the range [0,size()].
Returns:
An instance of LdapName consisting of the components at indexes in the range [0,posn). If posn is zero, an empty LDAP name is returned.
Throws:
IndexOutOfBoundsException - If posn is outside the specified range.

getSuffix

public Name getSuffix(int posn)
Creates a name whose components consist of a suffix of the components in this LDAP name. Subsequent changes to this name do not affect the name that is returned and vice versa.

Specified by:
getSuffix in interface Name
Parameters:
posn - The 0-based index of the component at which to start. Must be in the range [0,size()].
Returns:
An instance of LdapName consisting of the components at indexes in the range [posn,size()). If posn is equal to size(), an empty LDAP name is returned.
Throws:
IndexOutOfBoundsException - If posn is outside the specified range.

startsWith

public boolean startsWith(Name n)
Determines whether this LDAP name starts with a specified LDAP name prefix. A name n is a prefix if it is equal to getPrefix(n.size())--in other words this LDAP name starts with 'n'. If n is null or not a RFC2253 formatted name as described in the class description, false is returned.

Specified by:
startsWith in interface Name
Parameters:
n - The LDAP name to check.
Returns:
true if n is a prefix of this LDAP name, false otherwise.
See Also:
getPrefix(int posn)

startsWith

public boolean startsWith(List<Rdn> rdns)
Determines whether the specified RDN sequence forms a prefix of this LDAP name. Returns true if this LdapName is at least as long as rdns, and for every position p in the range [0, rdns.size()) the component getRdn(p) matches rdns.get(p). Returns false otherwise. If rdns is null, false is returned.

Parameters:
rdns - The sequence of Rdns to check.
Returns:
true if rdns form a prefix of this LDAP name, false otherwise.

endsWith

public boolean endsWith(Name n)
Determines whether this LDAP name ends with a specified LDAP name suffix. A name n is a suffix if it is equal to getSuffix(size()-n.size())--in other words this LDAP name ends with 'n'. If n is null or not a RFC2253 formatted name as described in the class description, false is returned.

Specified by:
endsWith in interface Name
Parameters:
n - The LDAP name to check.
Returns:
true if n is a suffix of this name, false otherwise.
See Also:
getSuffix(int posn)

endsWith

public boolean endsWith(List<Rdn> rdns)
Determines whether the specified RDN sequence forms a suffix of this LDAP name. Returns true if this LdapName is at least as long as rdns, and for every position p in the range [size() - rdns.size(), size()) the component getRdn(p) matches rdns.get(p). Returns false otherwise. If rdns is null, false is returned.

Parameters:
rdns - The sequence of Rdns to check.
Returns:
true if rdns form a suffix of this LDAP name, false otherwise.

addAll

public Name addAll(Name suffix)
            throws InvalidNameException
Adds the components of a name -- in order -- to the end of this name.

Specified by:
addAll in interface Name
Parameters:
suffix - The non-null components to add.
Returns:
The updated name (not a new instance).
Throws:
InvalidNameException - if suffix is not a valid LDAP name, or if the addition of the components would violate the syntax rules of this LDAP name.

addAll

public Name addAll(List<Rdn> suffixRdns)
Adds the RDNs of a name -- in order -- to the end of this name.

Parameters:
suffixRdns - The non-null suffix Rdns to add.
Returns:
The updated name (not a new instance).

addAll

public Name addAll(int posn,
                   Name suffix)
            throws InvalidNameException
Adds the components of a name -- in order -- at a specified position within this name. Components of this LDAP name at or after the index (if any) of the first new component are shifted up (away from index 0) to accomodate the new components.

Specified by:
addAll in interface Name
Parameters:
suffix - The non-null components to add.
posn - The index at which to add the new component. Must be in the range [0,size()].
Returns:
The updated name (not a new instance).
Throws:
InvalidNameException - if suffix is not a valid LDAP name, or if the addition of the components would violate the syntax rules of this LDAP name.
IndexOutOfBoundsException. - If posn is outside the specified range.

addAll

public Name addAll(int posn,
                   List<Rdn> suffixRdns)
Adds the RDNs of a name -- in order -- at a specified position within this name. RDNs of this LDAP name at or after the index (if any) of the first new RDN are shifted up (away from index 0) to accomodate the new RDNs.

Parameters:
suffixRdns - The non-null suffix Rdns to add.
posn - The index at which to add the suffix RDNs. Must be in the range [0,size()].
Returns:
The updated name (not a new instance).
Throws:
IndexOutOfBoundsException. - If posn is outside the specified range.

add

public Name add(String comp)
         throws InvalidNameException
Adds a single component to the end of this LDAP name.

Specified by:
add in interface Name
Parameters:
comp - The non-null component to add.
Returns:
The updated LdapName, not a new instance. Cannot be null.
Throws:
InvalidNameException - If adding comp at end of the name would violate the name's syntax.

add

public Name add(Rdn comp)
Adds a single RDN to the end of this LDAP name.

Parameters:
comp - The non-null RDN to add.
Returns:
The updated LdapName, not a new instance. Cannot be null.

add

public Name add(int posn,
                String comp)
         throws InvalidNameException
Adds a single component at a specified position within this LDAP name. Components of this LDAP name at or after the index (if any) of the new component are shifted up by one (away from index 0) to accommodate the new component.

Specified by:
add in interface Name
Parameters:
comp - The non-null component to add.
posn - The index at which to add the new component. Must be in the range [0,size()].
Returns:
The updated LdapName, not a new instance. Cannot be null.
Throws:
IndexOutOfBoundsException. - If posn is outside the specified range.
InvalidNameException - If adding comp at the specified position would violate the name's syntax.

add

public Name add(int posn,
                Rdn comp)
Adds a single RDN at a specified position within this LDAP name. RDNs of this LDAP name at or after the index (if any) of the new RDN are shifted up by one (away from index 0) to accommodate the new RDN.

Parameters:
comp - The non-null RDN to add.
posn - The index at which to add the new RDN. Must be in the range [0,size()].
Returns:
The updated LdapName, not a new instance. Cannot be null.
Throws:
IndexOutOfBoundsException - If posn is outside the specified range.

remove

public Object remove(int posn)
              throws InvalidNameException
Removes a component from this LDAP name. The component of this name at the specified position is removed. Components with indexes greater than this position (if any) are shifted down (toward index 0) by one.

Specified by:
remove in interface Name
Parameters:
posn - The index of the component to remove. Must be in the range [0,size()).
Returns:
The component removed (a String).
Throws:
IndexOutOfBoundsException - if posn is outside the specified range.
InvalidNameException - if deleting the component would violate the syntax rules of the name.

getRdns

public List<Rdn> getRdns()
Retrieves the list of relative distinguished names. The contents of the list are unmodifiable. The indexing of RDNs in the returned list follows the numbering of RDNs as described in the class description. If the name has zero components, an empty list is returned.

Returns:
The name as a list of RDNs which are instances of the class Rdn.

clone

public Object clone()
Generates a new copy of this name. Subsequent changes to the components of this name will not affect the new copy, and vice versa.

Specified by:
clone in interface Name
Overrides:
clone in class Object
Returns:
A copy of the this LDAP name.
See Also:
Cloneable

toString

public String toString()
Returns a string representation of this LDAP name in a format defined by RFC 2253 and described in the class description. If the name has zero components an empty string is returned.

Overrides:
toString in class Object
Returns:
The string representation of the LdapName.

equals

public boolean equals(Object obj)
Determines whether two LDAP names are equal. If obj is null or not an LDAP name, false is returned.

Two LDAP names are equal if each RDN in one is equal to the corresponding RDN in the other. This implies both have the same number of RDNs, and each RDN's equals() test against the corresponding RDN in the other name returns true. See Rdn.equals(Object obj) for a definition of RDN equality.

Overrides:
equals in class Object
Parameters:
obj - The possibly null object to compare against.
Returns:
true if obj is equal to this LDAP name, false otherwise.
See Also:
hashCode()

compareTo

public int compareTo(Object obj)
Compares this LdapName with the specified Object for order. Returns a negative integer, zero, or a positive integer as this Name is less than, equal to, or greater than the given Object.

If obj is null or not an instance of LdapName, ClassCastException is thrown.

Ordering of LDAP names follows the lexicographical rules for string comparison, with the extension that this applies to all the RDNs in the LDAP name. All the RDNs are lined up in their specified order and compared lexicographically. See Rdn.compareTo(Object obj) for RDN comparison rules.

If this LDAP name is lexicographically lesser than obj, a negative number is returned. If this LDAP name is lexicographically greater than obj, a positive number is returned.

Specified by:
compareTo in interface Comparable<Object>
Specified by:
compareTo in interface Name
Parameters:
obj - The non-null LdapName instance to compare against.
Returns:
A negative integer, zero, or a positive integer as this Name is less than, equal to, or greater than the given obj.
Throws:
ClassCastException - if obj is null or not a LdapName.
See Also:
Comparable.compareTo(Object)

hashCode

public int hashCode()
Computes the hash code of this LDAP name. The hash code is the sum of the hash codes of individual RDNs of this name.

Overrides:
hashCode in class Object
Returns:
An int representing the hash code of this name.
See Also:
equals(java.lang.Object)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LdapReferralException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Class LdapReferralException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.ReferralException
                    extended by  javax.naming.ldap.LdapReferralException
All Implemented Interfaces:
Serializable
public abstract class LdapReferralException
extends ReferralException

This abstract class is used to represent an LDAP referral exception. It extends the base ReferralException by providing a getReferralContext() method that accepts request controls. LdapReferralException is an abstract class. Concrete implementations of it determine its synchronization and serialization properties.

A Control[] array passed as a parameter to the getReferralContext() method is owned by the caller. The service provider will not modify the array or keep a reference to it, although it may keep references to the individual Control objects in the array.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
protected | LdapReferralException() Constructs a new instance of LdapReferralException.
protected | LdapReferralException(String explanation) Constructs a new instance of LdapReferralException using the explanation supplied.
Method Summary
abstract Context | getReferralContext() Retrieves the context at which to continue the method using the context's environment and no controls.
abstract Context | getReferralContext(Hashtable<?,?> env) Retrieves the context at which to continue the method using environment properties and no controls.
abstract Context | getReferralContext(Hashtable<?,?> env, Control[] reqCtls) Retrieves the context at which to continue the method using request controls and environment properties.
Methods inherited from class javax.naming.ReferralException
getReferralInfo, retryReferral, skipReferral
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

LdapReferralException

protected LdapReferralException(String explanation)
Constructs a new instance of LdapReferralException using the explanation supplied. All other fields are set to null.

Parameters:
explanation - Additional detail about this exception. Can be null.
See Also:
Throwable.getMessage()

LdapReferralException

protected LdapReferralException()
Constructs a new instance of LdapReferralException. All fields are set to null.

Method Detail

getReferralContext

public abstract Context getReferralContext()
                                    throws NamingException
Retrieves the context at which to continue the method using the context's environment and no controls. The referral context is created using the environment properties of the context that threw the ReferralException and no controls.

This method is equivalent to

 getReferralContext(ctx.getEnvironment(), null);
where ctx is the context that threw the ReferralException.

It is overridden in this class for documentation purposes only. See ReferralException for how to use this method.

Specified by:
getReferralContext in class ReferralException
Returns:
The non-null context at which to continue the method.
Throws:
NamingException - If a naming exception was encountered. Call either retryReferral() or skipReferral() to continue processing referrals.

getReferralContext

public abstract Context getReferralContext(Hashtable<?,?> env)
                                    throws NamingException
Retrieves the context at which to continue the method using environment properties and no controls. The referral context is created using env as its environment properties and no controls.

This method is equivalent to

 getReferralContext(env, null);

It is overridden in this class for documentation purposes only. See ReferralException for how to use this method.

Specified by:
getReferralContext in class ReferralException
Parameters:
env - The possibly null environment to use when retrieving the referral context. If null, no environment properties will be used.
Returns:
The non-null context at which to continue the method.
Throws:
NamingException - If a naming exception was encountered. Call either retryReferral() or skipReferral() to continue processing referrals.

getReferralContext

public abstract Context getReferralContext(Hashtable<?,?> env,
                                           Control[] reqCtls)
                                    throws NamingException
Retrieves the context at which to continue the method using request controls and environment properties. Regardless of whether a referral is encountered directly during a context operation, or indirectly, for example, during a search enumeration, the referral exception should provide a context at which to continue the operation. To continue the operation, the client program should re-invoke the method using the same arguments as the original invocation.

reqCtls is used when creating the connection to the referred server. These controls will be used as the connection request controls for the context and context instances derived from the context. reqCtls will also be the context's request controls for subsequent context operations. See the LdapContext class description for details.

This method should be used instead of the other two overloaded forms when the caller needs to supply request controls for creating the referral context. It might need to do this, for example, when it needs to supply special controls relating to authentication.

Service provider implementors should read the "Service Provider" section in the LdapContext class description for implementation details.

Parameters:
reqCtls - The possibly null request controls to use for the new context. If null or the empty array means use no request controls.
env - The possibly null environment properties to use when for the new context. If null, the context is initialized with no environment properties.
Returns:
The non-null context at which to continue the method.
Throws:
NamingException - If a naming exception was encountered. Call either retryReferral() or skipReferral() to continue processing referrals.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ManageReferralControl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Class ManageReferralControl

java.lang.Object
    extended by  javax.naming.ldap.BasicControl
        extended by  javax.naming.ldap.ManageReferralControl
All Implemented Interfaces:
Serializable, Control
public final class ManageReferralControl
extends BasicControl

Requests that referral and other special LDAP objects be manipulated as normal LDAP objects. It enables the requestor to interrogate or update such objects.

This class implements the LDAPv3 Request Control for ManageDsaIT as defined in RFC 3296. The control has no control value.

Since:
1.5
See Also:
Serialized Form

Field Summary
static String OID
The ManageReferral control's assigned object identifier is 2.16.840.1.113730.3.4.2.
Fields inherited from class javax.naming.ldap.BasicControl
criticality, id, value
Fields inherited from interface javax.naming.ldap.Control
CRITICAL, NONCRITICAL
Constructor Summary
ManageReferralControl()
Constructs a critical ManageReferral control.
ManageReferralControl(boolean criticality)
Constructs a ManageReferral control.
Method Summary
Methods inherited from class javax.naming.ldap.BasicControl
getEncodedValue, getID, isCritical
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OID

public static final String OID
The ManageReferral control's assigned object identifier is 2.16.840.1.113730.3.4.2.

See Also:
Constant Field Values
Constructor Detail

ManageReferralControl

public ManageReferralControl()
Constructs a critical ManageReferral control.

ManageReferralControl

public ManageReferralControl(boolean criticality)
Constructs a ManageReferral control.

Parameters:
criticality - The control's criticality setting.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PagedResultsControl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Class PagedResultsControl

java.lang.Object
    extended by  javax.naming.ldap.BasicControl
        extended by  javax.naming.ldap.PagedResultsControl
All Implemented Interfaces:
Serializable, Control
public final class PagedResultsControl
extends BasicControl

Requests that the results of a search operation be returned by the LDAP server in batches of a specified size. The requestor controls the rate at which batches are returned by the rate at which it invokes search operations.

The following code sample shows how the class may be used:

     // Open an LDAP association
     LdapContext ctx = new InitialLdapContext();

     // Activate paged results
     int pageSize = 20; // 20 entries per page
     byte[] cookie = null;
     int total;
     ctx.setRequestControls(new Control[]{
         new PagedResultsControl(pageSize, Control.CRITICAL) });

     do {
         // Perform the search
         NamingEnumeration results =
             ctx.search("", "(objectclass=*)", new SearchControls());

         // Iterate over a batch of search results
         while (results != null && results.hasMore()) {
             // Display an entry
             SearchResult entry = (SearchResult)results.next();
             System.out.println(entry.getName());
             System.out.println(entry.getAttributes());

             // Handle the entry's response controls (if any)
             if (entry instanceof HasControls) {
                 // ((HasControls)entry).getControls();
             }
         }
         // Examine the paged results control response
         Control[] controls = ctx.getResponseControls();
         if (controls != null) {
             for (int i = 0; i < controls.length; i++) {
                 if (controls[i] instanceof PagedResultsResponseControl) {
                     PagedResultsResponseControl prrc =
                         (PagedResultsResponseControl)controls[i];
                     total = prrc.getResultSize();
                     cookie = prrc.getCookie();
                 } else {
                     // Handle other response controls (if any)
                 }
             }
         }

         // Re-activate paged results
         ctx.setRequestControls(new Control[]{
             new PagedResultsControl(pageSize, cookie, Control.CRITICAL) });
     } while (cookie != null);

     // Close the LDAP association
     ctx.close();
     ...

This class implements the LDAPv3 Control for paged-results as defined in RFC 2696. The control's value has the following ASN.1 definition:

     realSearchControlValue ::= SEQUENCE {
         size      INTEGER (0..maxInt),
                           -- requested page size from client
                           -- result set size estimate from server
         cookie    OCTET STRING
     }

Since:
1.5
See Also:
PagedResultsResponseControl, Serialized Form

Field Summary
static String OID
The paged-results control's assigned object identifier is 1.2.840.113556.1.4.319.
Fields inherited from class javax.naming.ldap.BasicControl
criticality, id, value
Fields inherited from interface javax.naming.ldap.Control
CRITICAL, NONCRITICAL
Constructor Summary
PagedResultsControl(int pageSize, boolean criticality)
Constructs a control to set the number of entries to be returned per page of results.
PagedResultsControl(int pageSize, byte[] cookie, boolean criticality)
Constructs a control to set the number of entries to be returned per page of results.
Method Summary
Methods inherited from class javax.naming.ldap.BasicControl
getEncodedValue, getID, isCritical
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OID

public static final String OID
The paged-results control's assigned object identifier is 1.2.840.113556.1.4.319.

See Also:
Constant Field Values
Constructor Detail

PagedResultsControl

public PagedResultsControl(int pageSize,
                           boolean criticality)
                    throws IOException
Constructs a control to set the number of entries to be returned per page of results.

Parameters:
pageSize - The number of entries to return in a page.
criticality - If true then the server must honor the control and return search results as indicated by pageSize or refuse to perform the search. If false, then the server need not honor the control.
Throws:
IOException - If an error was encountered while encoding the supplied arguments into a control.

PagedResultsControl

public PagedResultsControl(int pageSize,
                           byte[] cookie,
                           boolean criticality)
                    throws IOException
Constructs a control to set the number of entries to be returned per page of results. The cookie is provided by the server and may be obtained from the paged-results response control.

A sequence of paged-results can be abandoned by setting the pageSize to zero and setting the cookie to the last cookie received from the server.

Parameters:
pageSize - The number of entries to return in a page.
cookie - A possibly null server-generated cookie.
criticality - If true then the server must honor the control and return search results as indicated by pageSize or refuse to perform the search. If false, then the server need not honor the control.
Throws:
IOException - If an error was encountered while encoding the supplied arguments into a control.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PagedResultsResponseControl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Class PagedResultsResponseControl

java.lang.Object
    extended by  javax.naming.ldap.BasicControl
        extended by  javax.naming.ldap.PagedResultsResponseControl
All Implemented Interfaces:
Serializable, Control
public final class PagedResultsResponseControl
extends BasicControl

Indicates the end of a batch of search results. Contains an estimate of the total number of entries in the result set and an opaque cookie. The cookie must be supplied to the next search operation in order to get the next batch of results.

The code sample in PagedResultsControl shows how this class may be used.

This class implements the LDAPv3 Response Control for paged-results as defined in RFC 2696. The control's value has the following ASN.1 definition:

     realSearchControlValue ::= SEQUENCE {
         size      INTEGER (0..maxInt),
                           -- requested page size from client
                           -- result set size estimate from server
         cookie    OCTET STRING
     }

Since:
1.5
See Also:
PagedResultsControl, Serialized Form

Field Summary
static String OID
The paged-results response control's assigned object identifier is 1.2.840.113556.1.4.319.
Fields inherited from class javax.naming.ldap.BasicControl
criticality, id, value
Fields inherited from interface javax.naming.ldap.Control
CRITICAL, NONCRITICAL
Constructor Summary
PagedResultsResponseControl(String id, boolean criticality, byte[] value)
Constructs a paged-results response control.
Method Summary
byte[] | getCookie() Retrieves the server-generated cookie.
int | getResultSize() Retrieves (an estimate of) the number of entries in the search result.
Methods inherited from class javax.naming.ldap.BasicControl
getEncodedValue, getID, isCritical
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OID

public static final String OID
The paged-results response control's assigned object identifier is 1.2.840.113556.1.4.319.

See Also:
Constant Field Values
Constructor Detail

PagedResultsResponseControl

public PagedResultsResponseControl(String id,
                                   boolean criticality,
                                   byte[] value)
                            throws IOException
Constructs a paged-results response control.

Parameters:
id - The control's object identifier string.
criticality - The control's criticality.
value - The control's ASN.1 BER encoded value. It is not cloned - any changes to value will affect the contents of the control.
Throws:
IOException - If an error was encountered while decoding the control's value.
Method Detail

getResultSize

public int getResultSize()
Retrieves (an estimate of) the number of entries in the search result.

Returns:
The number of entries in the search result, or zero if unknown.

getCookie

public byte[] getCookie()
Retrieves the server-generated cookie. Null is returned when there are no more entries for the server to return.

Returns:
A possibly null server-generated cookie. It is not cloned - any changes to the cookie will update the control's state and thus are not recommended.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Rdn

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Class Rdn

java.lang.Object
    extended by  javax.naming.ldap.Rdn
All Implemented Interfaces:
Serializable, Comparable<Object>
public class Rdn
extends Object
implements Serializable, Comparable<Object>

This class represents a relative distinguished name, or RDN, which is a component of a distinguished name as specified by RFC 2253. An example of an RDN is "OU=Sales+CN=J.Smith". In this example, the RDN consist of multiple attribute type/value pairs. The RDN is parsed as described in the class description for LdapName.

The Rdn class represents an RDN as attribute type/value mappings, which can be viewed using Attributes. In addition, it contains convenience methods that allow easy retrieval of type and value when the Rdn consist of a single type/value pair, which is how it appears in a typical usage. It also contains helper methods that allow escaping of the unformatted attribute value and unescaping of the value formatted according to the escaping syntax defined in RFC2253. For methods that take or return attribute value as an Object, the value is either a String (in unescaped form) or a byte array.

Rdn will properly parse all valid RDNs, but does not attempt to detect all possible violations when parsing invalid RDNs. It is "generous" in accepting invalid RDNs. The "validity" of a name is determined ultimately when it is supplied to an LDAP server, which may accept or reject the name based on factors such as its schema information and interoperability considerations.

The following code example shows how to construct an Rdn using the constructor that takes type and value as arguments:

        Rdn rdn = new Rdn("cn", "Juicy, Fruit");
        System.out.println(rdn.toString());
The last line will print cn=Juicy\, Fruit. The unescapeValue() method can be used to unescape the escaped comma resulting in the original value "Juicy, Fruit". The escapeValue() method adds the escape back preceding the comma.

This class can be instantiated by a string representation of the RDN defined in RFC 2253 as shown in the following code example:

        Rdn rdn = new Rdn("cn=Juicy\\, Fruit");
        System.out.println(rdn.toString());
The last line will print cn=Juicy\, Fruit.

Concurrent multithreaded read-only access of an instance of Rdn need not be synchronized.

Unless otherwise noted, the behavior of passing a null argument to a constructor or method in this class will cause NullPointerException to be thrown.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
Rdn(Attributes attrSet)
Constructs an Rdn from the given attribute set.
Rdn(Rdn rdn)
Constructs an Rdn from the given rdn.
Rdn(String rdnString)
Constructs an Rdn from the given string.
Rdn(String type, Object value)
Constructs an Rdn from the given attribute type and value.
Method Summary
int | compareTo(Object obj) Compares this Rdn with the specified Object for order.
boolean | equals(Object obj) Compares the specified Object with this Rdn for equality.
static String | escapeValue(Object val) Given the value of an attribute, returns a string escaped according to the rules specified in RFC 2253.
String | getType() Retrieves one of this Rdn's type.
Object | getValue() Retrieves one of this Rdn's value.
int | hashCode() Returns the hash code of this RDN.
int | size() Retrieves the number of attribute type/value pairs in this Rdn.
Attributes | toAttributes() Retrieves the Attributes view of the type/value mappings contained in this Rdn.
String | toString() Returns this Rdn as a string represented in a format defined by RFC 2253 and described in the class description for LdapName.
static Object | unescapeValue(String val) Given an attribute value string formated according to the rules specified in RFC 2253, returns the unformated value.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Rdn

public Rdn(Attributes attrSet)
    throws InvalidNameException
Constructs an Rdn from the given attribute set. See Attributes.

The string attribute values are not interpretted as RFC 2253 formatted RDN strings. That is, the values are used literally (not parsed) and assumed to be unescaped.

Parameters:
attrSet - The non-null and non-empty attributes containing type/value mappings.
Throws:
InvalidNameException - If contents of attrSet cannot be used to construct a valid RDN.

Rdn

public Rdn(String rdnString)
    throws InvalidNameException
Constructs an Rdn from the given string. This constructor takes a string formatted according to the rules defined in RFC 2253 and described in the class description for LdapName.

Parameters:
rdnString - The non-null and non-empty RFC2253 formatted string.
Throws:
InvalidNameException - If a syntax error occurs during parsing of the rdnString.

Rdn

public Rdn(Rdn rdn)
Constructs an Rdn from the given rdn. The contents of the rdn are simply copied into the newly created Rdn.

Parameters:
rdn - The non-null Rdn to be copied.

Rdn

public Rdn(String type,
           Object value)
    throws InvalidNameException
Constructs an Rdn from the given attribute type and value. The string attribute values are not interpretted as RFC 2253 formatted RDN strings. That is, the values are used literally (not parsed) and assumed to be unescaped.

Parameters:
type - The non-null and non-empty string attribute type.
value - The non-null and non-empty attribute value.
Throws:
InvalidNameException - If type/value cannot be used to construct a valid RDN.
See Also:
toString()
Method Detail

getValue

public Object getValue()
Retrieves one of this Rdn's value. This is a convenience method for obtaining the value, when the RDN contains a single type and value mapping, which is the common RDN usage.

For a multi-valued RDN, this method returns value corresponding to the type returned by getType() method.

Returns:
The non-null attribute value.

getType

public String getType()
Retrieves one of this Rdn's type. This is a convenience method for obtaining the type, when the RDN contains a single type and value mapping, which is the common RDN usage.

For a multi-valued RDN, the type/value pairs have no specific order defined on them. In that case, this method returns type of one of the type/value pairs. The getValue() method returns the value corresponding to the type returned by this method.

Returns:
The non-null attribute type.

toString

public String toString()
Returns this Rdn as a string represented in a format defined by RFC 2253 and described in the class description for LdapName.

Overrides:
toString in class Object
Returns:
The string representation of the Rdn.

compareTo

public int compareTo(Object obj)
Compares this Rdn with the specified Object for order. Returns a negative integer, zero, or a positive integer as this Rdn is less than, equal to, or greater than the given Object.

If obj is null or not an instance of Rdn, ClassCastException is thrown.

The attribute type and value pairs of the RDNs are lined up against each other and compared lexicographically. The order of components in multi-valued Rdns (such as "ou=Sales+cn=Bob") is not significant.

Specified by:
compareTo in interface Comparable<Object>
Parameters:
obj - The non-null object to compare against.
Returns:
A negative integer, zero, or a positive integer as this Rdn is less than, equal to, or greater than the given Object.
Throws:
ClassCastException - if obj is null or not a Rdn.

equals

public boolean equals(Object obj)
Compares the specified Object with this Rdn for equality. Returns true if the given object is also a Rdn and the two Rdns represent the same attribute type and value mappings. The order of components in multi-valued Rdns (such as "ou=Sales+cn=Bob") is not significant.

Type and value equalilty matching is done as below:

  • The types are compared for equality with their case ignored.
  • String values with different but equivalent usage of quoting, escaping, or UTF8-hex-encoding are considered equal. The case of the values is ignored during the comparison.

If obj is null or not an instance of Rdn, false is returned.

Overrides:
equals in class Object
Parameters:
obj - object to be compared for equality with this Rdn.
Returns:
true if the specified object is equal to this Rdn.
See Also:
hashCode()

hashCode

public int hashCode()
Returns the hash code of this RDN. Two RDNs that are equal (according to the equals method) will have the same hash code.

Overrides:
hashCode in class Object
Returns:
An int representing the hash code of this Rdn.
See Also:
equals(java.lang.Object)

toAttributes

public Attributes toAttributes()
Retrieves the Attributes view of the type/value mappings contained in this Rdn.

Returns:
The non-null attributes containing the type/value mappings of this Rdn.

size

public int size()
Retrieves the number of attribute type/value pairs in this Rdn.

Returns:
The non-negative number of type/value pairs in this Rdn.

escapeValue

public static String escapeValue(Object val)
Given the value of an attribute, returns a string escaped according to the rules specified in RFC 2253.

For example, if the val is "Sue, Grabbit and Runn", the escaped value returned by this method is "Sue\, Grabbit and Runn".

A string value is represented as a String and binary value as a byte array.

Parameters:
val - The non-null object to be escaped.
Returns:
Escaped string value.
Throws:
ClassCastException - if val is is not a String or byte array.

unescapeValue

public static Object unescapeValue(String val)
Given an attribute value string formated according to the rules specified in RFC 2253, returns the unformated value. Escapes and quotes are stripped away, and hex-encoded UTF-8 is converted to equivalent UTF-16 characters. Returns a string value as a String, and a binary value as a byte array.

Legal and illegal values are defined in RFC 2253. This method is generous in accepting the values and does not catch all illegal values. Therefore, passing in an illegal value might not necessarily trigger an IllegalArgumentException.

Parameters:
val - The non-null string to be unescaped.
Returns:
Unescaped value.
Throws:
IllegalArgumentException - When an Illegal value is provided.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SortControl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Class SortControl

java.lang.Object
    extended by  javax.naming.ldap.BasicControl
        extended by  javax.naming.ldap.SortControl
All Implemented Interfaces:
Serializable, Control
public final class SortControl
extends BasicControl

Requests that the results of a search operation be sorted by the LDAP server before being returned. The sort criteria are specified using an ordered list of one or more sort keys, with associated sort parameters. Search results are sorted at the LDAP server according to the parameters supplied in the sort control and then returned to the requestor. If sorting is not supported at the server (and the sort control is marked as critical) then the search operation is not performed and an error is returned.

The following code sample shows how the class may be used:

     // Open an LDAP association
     LdapContext ctx = new InitialLdapContext();

     // Activate sorting
     String sortKey = "cn";
     ctx.setRequestControls(new Control[]{
         new SortControl(sortKey, Control.CRITICAL) });

     // Perform a search
     NamingEnumeration results =
         ctx.search("", "(objectclass=*)", new SearchControls());

     // Iterate over search results
     while (results != null && results.hasMore()) {
         // Display an entry
         SearchResult entry = (SearchResult)results.next();
         System.out.println(entry.getName());
         System.out.println(entry.getAttributes());

         // Handle the entry's response controls (if any)
         if (entry instanceof HasControls) {
             // ((HasControls)entry).getControls();
         }
     }
     // Examine the sort control response
     Control[] controls = ctx.getResponseControls();
     if (controls != null) {
         for (int i = 0; i < controls.length; i++) {
             if (controls[i] instanceof SortResponseControl) {
                 SortResponseControl src = (SortResponseControl)controls[i];
                 if (! src.isSorted()) {
                     throw src.getException();
                 }
             } else {
                 // Handle other response controls (if any)
             }
         }
     }

     // Close the LDAP association
     ctx.close();
     ...

This class implements the LDAPv3 Request Control for server-side sorting as defined in RFC 2891. The control's value has the following ASN.1 definition:

     SortKeyList ::= SEQUENCE OF SEQUENCE {
         attributeType     AttributeDescription,
         orderingRule  [0] MatchingRuleId OPTIONAL,
         reverseOrder  [1] BOOLEAN DEFAULT FALSE }

Since:
1.5
See Also:
SortKey, SortResponseControl, Serialized Form

Field Summary
static String OID
The server-side sort control's assigned object identifier is 1.2.840.113556.1.4.473.
Fields inherited from class javax.naming.ldap.BasicControl
criticality, id, value
Fields inherited from interface javax.naming.ldap.Control
CRITICAL, NONCRITICAL
Constructor Summary
SortControl(SortKey[] sortBy, boolean criticality)
Constructs a control to sort on a list of sort keys.
SortControl(String[] sortBy, boolean criticality)
Constructs a control to sort on a list of attributes in ascending order.
SortControl(String sortBy, boolean criticality)
Constructs a control to sort on a single attribute in ascending order.
Method Summary
Methods inherited from class javax.naming.ldap.BasicControl
getEncodedValue, getID, isCritical
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OID

public static final String OID
The server-side sort control's assigned object identifier is 1.2.840.113556.1.4.473.

See Also:
Constant Field Values
Constructor Detail

SortControl

public SortControl(String sortBy,
                   boolean criticality)
            throws IOException
Constructs a control to sort on a single attribute in ascending order. Sorting will be performed using the ordering matching rule defined for use with the specified attribute.

Parameters:
sortBy - An attribute ID to sort by.
criticality - If true then the server must honor the control and return the search results sorted as requested or refuse to perform the search. If false, then the server need not honor the control.
Throws:
IOException - If an error was encountered while encoding the supplied arguments into a control.

SortControl

public SortControl(String[] sortBy,
                   boolean criticality)
            throws IOException
Constructs a control to sort on a list of attributes in ascending order. Sorting will be performed using the ordering matching rule defined for use with each of the specified attributes.

Parameters:
sortBy - A non-null list of attribute IDs to sort by. The list is in order of highest to lowest sort key precedence.
criticality - If true then the server must honor the control and return the search results sorted as requested or refuse to perform the search. If false, then the server need not honor the control.
Throws:
IOException - If an error was encountered while encoding the supplied arguments into a control.

SortControl

public SortControl(SortKey[] sortBy,
                   boolean criticality)
            throws IOException
Constructs a control to sort on a list of sort keys. Each sort key specifies the sort order and ordering matching rule to use.

Parameters:
sortBy - A non-null list of keys to sort by. The list is in order of highest to lowest sort key precedence.
criticality - If true then the server must honor the control and return the search results sorted as requested or refuse to perform the search. If false, then the server need not honor the control.
Throws:
IOException - If an error was encountered while encoding the supplied arguments into a control.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SortKey

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Class SortKey

java.lang.Object
    extended by  javax.naming.ldap.SortKey

public class SortKey
extends Object

A sort key and its associated sort parameters. This class implements a sort key which is used by the LDAPv3 Control for server-side sorting of search results as defined in RFC 2891.

Since:
1.5
See Also:
SortControl

Constructor Summary
SortKey(String attrID)
Creates the default sort key for an attribute.
SortKey(String attrID, boolean ascendingOrder, String matchingRuleID)
Creates a sort key for an attribute.
Method Summary
String | getAttributeID() Retrieves the attribute ID of the sort key.
String | getMatchingRuleID() Retrieves the matching rule ID used to order the attribute values.
boolean | isAscending() Determines the sort order.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SortKey

public SortKey(String attrID)
Creates the default sort key for an attribute. Entries will be sorted according to the specified attribute in ascending order using the ordering matching rule defined for use with that attribute.

Parameters:
attrID - The non-null ID of the attribute to be used as a sort key.

SortKey

public SortKey(String attrID,
               boolean ascendingOrder,
               String matchingRuleID)
Creates a sort key for an attribute. Entries will be sorted according to the specified attribute in the specified sort order and using the specified matching rule, if supplied.

Parameters:
attrID - The non-null ID of the attribute to be used as a sort key.
ascendingOrder - If true then entries are arranged in ascending order. Otherwise there are arranged in descending order.
matchingRuleID - The possibly null ID of the matching rule to use to order the attribute values. If not specified then the ordering matching rule defined for the sort key attribute is used.
Method Detail

getAttributeID

public String getAttributeID()
Retrieves the attribute ID of the sort key.

Returns:
The non-null Attribute ID of the sort key.

isAscending

public boolean isAscending()
Determines the sort order.

Returns:
true if the sort order is ascending, false if descending.

getMatchingRuleID

public String getMatchingRuleID()
Retrieves the matching rule ID used to order the attribute values.

Returns:
The possibly null matching rule ID. If null then the ordering matching rule defined for the sort key attribute is used.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SortResponseControl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Class SortResponseControl

java.lang.Object
    extended by  javax.naming.ldap.BasicControl
        extended by  javax.naming.ldap.SortResponseControl
All Implemented Interfaces:
Serializable, Control
public final class SortResponseControl
extends BasicControl

Indicates whether the requested sort of search results was successful or not. When the result code indicates success then the results have been sorted as requested. Otherwise the sort was unsuccessful and additional details regarding the cause of the error may have been provided by the server.

The code sample in SortControl shows how this class may be used.

This class implements the LDAPv3 Response Control for server-side sorting as defined in RFC 2891. The control's value has the following ASN.1 definition:

     SortResult ::= SEQUENCE {
        sortResult  ENUMERATED {
            success                   (0), -- results are sorted
            operationsError           (1), -- server internal failure
            timeLimitExceeded         (3), -- timelimit reached before
                                           -- sorting was completed
            strongAuthRequired        (8), -- refused to return sorted
                                           -- results via insecure
                                           -- protocol
            adminLimitExceeded       (11), -- too many matching entries
                                           -- for the server to sort
            noSuchAttribute          (16), -- unrecognized attribute
                                           -- type in sort key
            inappropriateMatching    (18), -- unrecognized or inappro-
                                           -- priate matching rule in
                                           -- sort key
            insufficientAccessRights (50), -- refused to return sorted
                                           -- results to this client
            busy                     (51), -- too busy to process
            unwillingToPerform       (53), -- unable to sort
            other                    (80)
            },
      attributeType [0] AttributeType OPTIONAL }

Since:
1.5
See Also:
SortControl, Serialized Form

Field Summary
static String OID
The server-side sort response control's assigned object identifier is 1.2.840.113556.1.4.474.
Fields inherited from class javax.naming.ldap.BasicControl
criticality, id, value
Fields inherited from interface javax.naming.ldap.Control
CRITICAL, NONCRITICAL
Constructor Summary
SortResponseControl(String id, boolean criticality, byte[] value)
Constructs a control to indicate the outcome of a sort request.
Method Summary
String | getAttributeID() Retrieves the ID of the attribute that caused the sort to fail.
NamingException | getException() Retrieves the NamingException appropriate for the result code.
int | getResultCode() Retrieves the LDAP result code of the sort operation.
boolean | isSorted() Determines if the search results have been successfully sorted.
Methods inherited from class javax.naming.ldap.BasicControl
getEncodedValue, getID, isCritical
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OID

public static final String OID
The server-side sort response control's assigned object identifier is 1.2.840.113556.1.4.474.

See Also:
Constant Field Values
Constructor Detail

SortResponseControl

public SortResponseControl(String id,
                           boolean criticality,
                           byte[] value)
                    throws IOException
Constructs a control to indicate the outcome of a sort request.

Parameters:
id - The control's object identifier string.
criticality - The control's criticality.
value - The control's ASN.1 BER encoded value. It is not cloned - any changes to value will affect the contents of the control.
Throws:
IOException - if an error is encountered while decoding the control's value.
Method Detail

isSorted

public boolean isSorted()
Determines if the search results have been successfully sorted. If an error occurred during sorting a NamingException is thrown.

Returns:
true if the search results have been sorted.

getResultCode

public int getResultCode()
Retrieves the LDAP result code of the sort operation.

Returns:
The result code. A zero value indicates success.

getAttributeID

public String getAttributeID()
Retrieves the ID of the attribute that caused the sort to fail. Returns null if no ID was returned by the server.

Returns:
The possibly null ID of the bad attribute.

getException

public NamingException getException()
Retrieves the NamingException appropriate for the result code.

Returns:
A NamingException or null if the result code indicates success.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StartTlsRequest

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Class StartTlsRequest

java.lang.Object
    extended by  javax.naming.ldap.StartTlsRequest
All Implemented Interfaces:
Serializable, ExtendedRequest
public class StartTlsRequest
extends Object
implements ExtendedRequest

This class implements the LDAPv3 Extended Request for StartTLS as defined in Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security The object identifier for StartTLS is 1.3.6.1.4.1.1466.20037 and no extended request value is defined.

StartTlsRequest/StartTlsResponse are used to establish a TLS connection over the existing LDAP connection associated with the JNDI context on which extendedOperation() is invoked. Typically, a JNDI program uses these classes as follows.

 import javax.naming.ldap.*;

 // Open an LDAP association
 LdapContext ctx = new InitialLdapContext();

 // Perform a StartTLS extended operation
 StartTlsResponse tls =
     (StartTlsResponse) ctx.extendedOperation(new StartTlsRequest());

 // Open a TLS connection (over the existing LDAP association) and get details
 // of the negotiated TLS session: cipher suite, peer certificate, etc.
 SSLSession session = tls.negotiate();

 // ... use ctx to perform protected LDAP operations

 // Close the TLS connection (revert back to the underlying LDAP association)
 tls.close();

 // ... use ctx to perform unprotected LDAP operations

 // Close the LDAP association
 ctx.close;

Since:
1.4
See Also:
StartTlsResponse, Serialized Form

Field Summary
static String OID
The StartTLS extended request's assigned object identifier is 1.3.6.1.4.1.1466.20037.
Constructor Summary
StartTlsRequest()
Constructs a StartTLS extended request.
Method Summary
ExtendedResponse | createExtendedResponse(String id, byte[] berValue, int offset, int length) Creates an extended response object that corresponds to the LDAP StartTLS extended request.
byte[] | getEncodedValue() Retrieves the StartTLS request's ASN.1 BER encoded value.
String | getID() Retrieves the StartTLS request's object identifier string.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OID

public static final String OID
The StartTLS extended request's assigned object identifier is 1.3.6.1.4.1.1466.20037.

See Also:
Constant Field Values
Constructor Detail

StartTlsRequest

public StartTlsRequest()
Constructs a StartTLS extended request.

Method Detail

getID

public String getID()
Retrieves the StartTLS request's object identifier string.

Specified by:
getID in interface ExtendedRequest
Returns:
The object identifier string, "1.3.6.1.4.1.1466.20037".

getEncodedValue

public byte[] getEncodedValue()
Retrieves the StartTLS request's ASN.1 BER encoded value. Since the request has no defined value, null is always returned.

Specified by:
getEncodedValue in interface ExtendedRequest
Returns:
The null value.

createExtendedResponse

public ExtendedResponse createExtendedResponse(String id,
                                               byte[] berValue,
                                               int offset,
                                               int length)
                                        throws NamingException
Creates an extended response object that corresponds to the LDAP StartTLS extended request.

The result must be a concrete subclass of StartTlsResponse and must have a public zero-argument constructor.

This method locates the implementation class by locating configuration files that have the name:

META-INF/services/javax.naming.ldap.StartTlsResponse
The configuration files and their corresponding implementation classes must be accessible to the calling thread's context class loader.

Each configuration file should contain a list of fully-qualified class names, one per line. Space and tab characters surrounding each name, as well as blank lines, are ignored. The comment character is '#' (0x23); on each line all characters following the first comment character are ignored. The file must be encoded in UTF-8.

This method will return an instance of the first implementation class that it is able to load and instantiate successfully from the list of class names collected from the configuration files. This method uses the calling thread's context classloader to find the configuration files and to load the implementation class.

If no class can be found in this way, this method will use an implementation-specific way to locate an implementation. If none is found, a NamingException is thrown.

Specified by:
createExtendedResponse in interface ExtendedRequest
Parameters:
id - The object identifier of the extended response. Its value must be "1.3.6.1.4.1.1466.20037" or null. Both values are equivalent.
berValue - The possibly null ASN.1 BER encoded value of the extended response. This is the raw BER bytes including the tag and length of the response value. It does not include the response OID. Its value is ignored because a Start TLS response is not expected to contain any response value.
offset - The starting position in berValue of the bytes to use. Its value is ignored because a Start TLS response is not expected to contain any response value.
length - The number of bytes in berValue to use. Its value is ignored because a Start TLS response is not expected to contain any response value.
Returns:
The StartTLS extended response object.
Throws:
NamingException - If a naming exception was encountered while creating the StartTLS extended response object.
See Also:
ExtendedResponse
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StartTlsResponse

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Class StartTlsResponse

java.lang.Object
    extended by  javax.naming.ldap.StartTlsResponse
All Implemented Interfaces:
Serializable, ExtendedResponse
public abstract class StartTlsResponse
extends Object
implements ExtendedResponse

This class implements the LDAPv3 Extended Response for StartTLS as defined in Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security The object identifier for StartTLS is 1.3.6.1.4.1.1466.20037 and no extended response value is defined.

The Start TLS extended request and response are used to establish a TLS connection over the existing LDAP connection associated with the JNDI context on which extendedOperation() is invoked. Typically, a JNDI program uses the StartTLS extended request and response classes as follows.

 import javax.naming.ldap.*;

 // Open an LDAP association
 LdapContext ctx = new InitialLdapContext();

 // Perform a StartTLS extended operation
 StartTlsResponse tls =
     (StartTlsResponse) ctx.extendedOperation(new StartTlsRequest());

 // Open a TLS connection (over the existing LDAP association) and get details
 // of the negotiated TLS session: cipher suite, peer certificate, ...
 SSLSession session = tls.negotiate();

 // ... use ctx to perform protected LDAP operations

 // Close the TLS connection (revert back to the underlying LDAP association)
 tls.close();

 // ... use ctx to perform unprotected LDAP operations

 // Close the LDAP association
 ctx.close;

Since:
1.4
See Also:
StartTlsRequest, Serialized Form

Field Summary
static String OID
The StartTLS extended response's assigned object identifier is 1.3.6.1.4.1.1466.20037.
Constructor Summary
protected StartTlsResponse()
Constructs a StartTLS extended response.
Method Summary
abstract void | close() Closes the TLS connection gracefully and reverts back to the underlying connection.
byte[] | getEncodedValue() Retrieves the StartTLS response's ASN.1 BER encoded value.
String | getID() Retrieves the StartTLS response's object identifier string.
abstract SSLSession | negotiate() Negotiates a TLS session using the default SSL socket factory.
abstract SSLSession | negotiate(SSLSocketFactory factory) Negotiates a TLS session using an SSL socket factory.
abstract void | setEnabledCipherSuites(String[] suites) Overrides the default list of cipher suites enabled for use on the TLS connection.
abstract void | setHostnameVerifier(HostnameVerifier verifier) Sets the hostname verifier used by negotiate() after the TLS handshake has completed and the default hostname verification has failed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OID

public static final String OID
The StartTLS extended response's assigned object identifier is 1.3.6.1.4.1.1466.20037.

See Also:
Constant Field Values
Constructor Detail

StartTlsResponse

protected StartTlsResponse()
Constructs a StartTLS extended response. A concrete subclass must have a public no-arg constructor.

Method Detail

getID

public String getID()
Retrieves the StartTLS response's object identifier string.

Specified by:
getID in interface ExtendedResponse
Returns:
The object identifier string, "1.3.6.1.4.1.1466.20037".

getEncodedValue

public byte[] getEncodedValue()
Retrieves the StartTLS response's ASN.1 BER encoded value. Since the response has no defined value, null is always returned.

Specified by:
getEncodedValue in interface ExtendedResponse
Returns:
The null value.

setEnabledCipherSuites

public abstract void setEnabledCipherSuites(String[] suites)
Overrides the default list of cipher suites enabled for use on the TLS connection. The cipher suites must have already been listed by SSLSocketFactory.getSupportedCipherSuites() as being supported. Even if a suite has been enabled, it still might not be used because the peer does not support it, or because the requisite certificates (and private keys) are not available.

Parameters:
suites - The non-null list of names of all the cipher suites to enable.
See Also:
negotiate()

setHostnameVerifier

public abstract void setHostnameVerifier(HostnameVerifier verifier)
Sets the hostname verifier used by negotiate() after the TLS handshake has completed and the default hostname verification has failed. setHostnameVerifier() must be called before negotiate() is invoked for it to have effect. If called after negotiate(), this method does not do anything.

Parameters:
verifier - The non-null hostname verifier callback.
See Also:
negotiate()

negotiate

public abstract SSLSession negotiate()
                              throws IOException
Negotiates a TLS session using the default SSL socket factory.

This method is equivalent to negotiate(null).

Returns:
The negotiated SSL session
Throws:
IOException - If an IO error was encountered while establishing the TLS session.
See Also:
setEnabledCipherSuites(java.lang.String[]), setHostnameVerifier(javax.net.ssl.HostnameVerifier)

negotiate

public abstract SSLSession negotiate(SSLSocketFactory factory)
                              throws IOException
Negotiates a TLS session using an SSL socket factory.

Creates an SSL socket using the supplied SSL socket factory and attaches it to the existing connection. Performs the TLS handshake and returns the negotiated session information.

If cipher suites have been set via setEnabledCipherSuites then they are enabled before the TLS handshake begins.

Hostname verification is performed after the TLS handshake completes. The default hostname verification performs a match of the server's hostname against the hostname information found in the server's certificate. If this verification fails and no callback has been set via setHostnameVerifier then the negotiation fails. If this verification fails and a callback has been set via setHostnameVerifier, then the callback is used to determine whether the negotiation succeeds.

If an error occurs then the SSL socket is closed and an IOException is thrown. The underlying connection remains intact.

Parameters:
factory - The possibly null SSL socket factory to use. If null, the default SSL socket factory is used.
Returns:
The negotiated SSL session
Throws:
IOException - If an IO error was encountered while establishing the TLS session.
See Also:
setEnabledCipherSuites(java.lang.String[]), setHostnameVerifier(javax.net.ssl.HostnameVerifier)

close

public abstract void close()
                    throws IOException
Closes the TLS connection gracefully and reverts back to the underlying connection.

Throws:
IOException - If an IO error was encountered while closing the TLS connection
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UnsolicitedNotification

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Interface UnsolicitedNotification

All Superinterfaces:
ExtendedResponse, HasControls, Serializable
public interface UnsolicitedNotification
extends ExtendedResponse, HasControls

This interface represents an unsolicited notification as defined in RFC 2251. An unsolicited notification is sent by the LDAP server to the LDAP client without any provocation from the client. Its format is that of an extended response (ExtendedResponse).

Since:
1.3
See Also:
ExtendedResponse, UnsolicitedNotificationEvent, UnsolicitedNotificationListener

Method Summary
NamingException | getException() Retrieves the exception as constructed using information sent by the server.
String[] | getReferrals() Retrieves the referral(s) sent by the server.
Methods inherited from interface javax.naming.ldap.ExtendedResponse
getEncodedValue, getID
Methods inherited from interface javax.naming.ldap.HasControls
getControls

Method Detail

getReferrals

String[] getReferrals()
Retrieves the referral(s) sent by the server.

Returns:
A possibly null array of referrals, each of which is represented by a URL string. If null, no referral was sent by the server.

getException

NamingException getException()
Retrieves the exception as constructed using information sent by the server.

Returns:
A possibly null exception as constructed using information sent by the server. If null, a "success" status was indicated by the server.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UnsolicitedNotificationEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Class UnsolicitedNotificationEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.naming.ldap.UnsolicitedNotificationEvent
All Implemented Interfaces:
Serializable
public class UnsolicitedNotificationEvent
extends EventObject

This class represents an event fired in response to an unsolicited notification sent by the LDAP server.

Since:
1.3
See Also:
UnsolicitedNotification, UnsolicitedNotificationListener, EventContext.addNamingListener(javax.naming.Name, int, javax.naming.event.NamingListener), EventDirContext.addNamingListener(javax.naming.Name, java.lang.String, javax.naming.directory.SearchControls, javax.naming.event.NamingListener), EventContext.removeNamingListener(javax.naming.event.NamingListener), Serialized Form

Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
UnsolicitedNotificationEvent(Object src, UnsolicitedNotification notice)
Constructs a new instance of UnsolicitedNotificationEvent.
Method Summary
void | dispatch(UnsolicitedNotificationListener listener) Invokes the notificationReceived() method on a listener using this event.
UnsolicitedNotification | getNotification() Returns the unsolicited notification.
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UnsolicitedNotificationEvent

public UnsolicitedNotificationEvent(Object src,
                                    UnsolicitedNotification notice)
Constructs a new instance of UnsolicitedNotificationEvent.

Parameters:
src - The non-null source that fired the event.
notice - The non-null unsolicited notification.
Method Detail

getNotification

public UnsolicitedNotification getNotification()
Returns the unsolicited notification.

Returns:
The non-null unsolicited notification that caused this event to be fired.

dispatch

public void dispatch(UnsolicitedNotificationListener listener)
Invokes the notificationReceived() method on a listener using this event.

Parameters:
listener - The non-null listener on which to invoke notificationReceived.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UnsolicitedNotificationListener

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.naming.ldap
Interface UnsolicitedNotificationListener

All Superinterfaces:
EventListener, NamingListener
public interface UnsolicitedNotificationListener
extends NamingListener

This interface is for handling UnsolicitedNotificationEvent. "Unsolicited notification" is defined in RFC 2251. It allows the server to send unsolicited notifications to the client. A UnsolicitedNotificationListener must:

  1. Implement this interface and its method
  2. Implement NamingListener.namingExceptionThrown() so that it will be notified of exceptions thrown while attempting to collect unsolicited notification events.
  3. Register with the context using one of the addNamingListener() methods from EventContext or EventDirContext. Only the NamingListener argument of these methods are applicable; the rest are ignored for a UnsolicitedNotificationListener. (These arguments might be applicable to the listener if it implements other listener interfaces).

Since:
1.3
See Also:
UnsolicitedNotificationEvent,
UnsolicitedNotification,
EventContext.addNamingListener(javax.naming.Name, int, javax.naming.event.NamingListener),
EventDirContext.addNamingListener(javax.naming.Name, java.lang.String, javax.naming.directory.SearchControls, javax.naming.event.NamingListener),
EventContext.removeNamingListener(javax.naming.event.NamingListener)

Method Summary
 void notificationReceived(UnsolicitedNotificationEvent evt)
Called when an unsolicited notification has been received.
Methods inherited from interface javax.naming.event.NamingListener
namingExceptionThrown

Method Detail

notificationReceived

void notificationReceived(UnsolicitedNotificationEvent evt)
Called when an unsolicited notification has been received.

Parameters:
evt - The non-null UnsolicitedNotificationEvent
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


LimitExceededException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class LimitExceededException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.LimitExceededException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
SizeLimitExceededException, TimeLimitExceededException
public class LimitExceededException
extends NamingException

This exception is thrown when a method terminates abnormally due to a user or system specified limit. This is different from a InsufficientResourceException in that LimitExceededException is due to a user/system specified limit. For example, running out of memory to complete the request would be an insufficient resource. The client asking for 10 answers and getting back 11 is a size limit exception.

Examples of these limits include client and server configuration limits such as size, time, number of hops, etc.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
LimitExceededException()
Constructs a new instance of LimitExceededException with all name resolution fields and explanation initialized to null.
LimitExceededException(String explanation)
Constructs a new instance of LimitExceededException using an explanation.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

LimitExceededException

public LimitExceededException()
Constructs a new instance of LimitExceededException with all name resolution fields and explanation initialized to null.

LimitExceededException

public LimitExceededException(String explanation)
Constructs a new instance of LimitExceededException using an explanation. All other fields default to null.

Parameters:
explanation - Possibly null detail about this exception.
See Also:
Throwable.getMessage()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LinkException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class LinkException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.LinkException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
LinkLoopException, MalformedLinkException
public class LinkException
extends NamingException

This exception is used to describe problems encounter while resolving links. Addition information is added to the base NamingException for pinpointing the problem with the link.

Analogous to how NamingException captures name resolution information, LinkException captures "link"-name resolution information pinpointing the problem encountered while resolving a link. All these fields may be null.

  • Link Resolved Name. Portion of link name that has been resolved.
  • Link Resolved Object. Object to which resolution of link name proceeded.
  • Link Remaining Name. Portion of link name that has not been resolved.
  • Link Explanation. Detail explaining why link resolution failed.

A LinkException instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify a single LinkException instance should lock the object.

Since:
1.3
See Also:
Context.lookupLink(javax.naming.Name), LinkRef, Serialized Form

Field Summary
protected String | linkExplanation Contains the exception of why resolution of the link failed.
protected Name | linkRemainingName Contains the remaining link name that has not been resolved yet.
protected Name | linkResolvedName Contains the part of the link that has been successfully resolved.
protected Object | linkResolvedObj Contains the object to which resolution of the part of the link was successful.
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
LinkException()
Constructs a new instance of LinkException.
LinkException(String explanation)
Constructs a new instance of LinkException with an explanation All the other fields are initialized to null.
Method Summary
String | getLinkExplanation() Retrieves the explanation associated with the problem encounter when resolving a link.
Name | getLinkRemainingName() Retrieves the remaining unresolved portion of the link name.
Name | getLinkResolvedName() Retrieves the leading portion of the link name that was resolved successfully.
Object | getLinkResolvedObj() Retrieves the object to which resolution was successful.
void | setLinkExplanation(String msg) Sets the explanation associated with the problem encounter when resolving a link.
void | setLinkRemainingName(Name name) Sets the remaining link name field of this exception.
void | setLinkResolvedName(Name name) Sets the resolved link name field of this exception.
void | setLinkResolvedObj(Object obj) Sets the link resolved object field of this exception.
String | toString() Generates the string representation of this exception.
String | toString(boolean detail) Generates the string representation of this exception.
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

linkResolvedName

protected Name linkResolvedName
Contains the part of the link that has been successfully resolved. It is a composite name and can be null. This field is initialized by the constructors. You should access and manipulate this field through its get and set methods.

See Also:
getLinkResolvedName(), setLinkResolvedName(javax.naming.Name)

linkResolvedObj

protected Object linkResolvedObj
Contains the object to which resolution of the part of the link was successful. Can be null. This field is initialized by the constructors. You should access and manipulate this field through its get and set methods.

See Also:
getLinkResolvedObj(), setLinkResolvedObj(java.lang.Object)

linkRemainingName

protected Name linkRemainingName
Contains the remaining link name that has not been resolved yet. It is a composite name and can be null. This field is initialized by the constructors. You should access and manipulate this field through its get and set methods.

See Also:
getLinkRemainingName(), setLinkRemainingName(javax.naming.Name)

linkExplanation

protected String linkExplanation
Contains the exception of why resolution of the link failed. Can be null. This field is initialized by the constructors. You should access and manipulate this field through its get and set methods.

See Also:
getLinkExplanation(), setLinkExplanation(java.lang.String)
Constructor Detail

LinkException

public LinkException(String explanation)
Constructs a new instance of LinkException with an explanation All the other fields are initialized to null.

Parameters:
explanation - A possibly null string containing additional detail about this exception.
See Also:
Throwable.getMessage()

LinkException

public LinkException()
Constructs a new instance of LinkException. All the non-link-related and link-related fields are initialized to null.

Method Detail

getLinkResolvedName

public Name getLinkResolvedName()
Retrieves the leading portion of the link name that was resolved successfully.

Returns:
The part of the link name that was resolved successfully. It is a composite name. It can be null, which means the link resolved name field has not been set.
See Also:
getLinkResolvedObj(), setLinkResolvedName(javax.naming.Name)

getLinkRemainingName

public Name getLinkRemainingName()
Retrieves the remaining unresolved portion of the link name.

Returns:
The part of the link name that has not been resolved. It is a composite name. It can be null, which means the link remaining name field has not been set.
See Also:
setLinkRemainingName(javax.naming.Name)

getLinkResolvedObj

public Object getLinkResolvedObj()
Retrieves the object to which resolution was successful. This is the object to which the resolved link name is bound.

Returns:
The possibly null object that was resolved so far. If null, it means the link resolved object field has not been set.
See Also:
getLinkResolvedName(), setLinkResolvedObj(java.lang.Object)

getLinkExplanation

public String getLinkExplanation()
Retrieves the explanation associated with the problem encounter when resolving a link.

Returns:
The possibly null detail string explaining more about the problem with resolving a link. If null, it means there is no link detail message for this exception.
See Also:
setLinkExplanation(java.lang.String)

setLinkExplanation

public void setLinkExplanation(String msg)
Sets the explanation associated with the problem encounter when resolving a link.

Parameters:
msg - The possibly null detail string explaining more about the problem with resolving a link. If null, it means no detail will be recorded.
See Also:
getLinkExplanation()

setLinkResolvedName

public void setLinkResolvedName(Name name)
Sets the resolved link name field of this exception.

name is a composite name. If the intent is to set this field using a compound name or string, you must "stringify" the compound name, and create a composite name with a single component using the string. You can then invoke this method using the resulting composite name.

A copy of name is made and stored. Subsequent changes to name does not affect the copy in this NamingException and vice versa.

Parameters:
name - The name to set resolved link name to. This can be null. If null, it sets the link resolved name field to null.
See Also:
getLinkResolvedName()

setLinkRemainingName

public void setLinkRemainingName(Name name)
Sets the remaining link name field of this exception.

name is a composite name. If the intent is to set this field using a compound name or string, you must "stringify" the compound name, and create a composite name with a single component using the string. You can then invoke this method using the resulting composite name.

A copy of name is made and stored. Subsequent changes to name does not affect the copy in this NamingException and vice versa.

Parameters:
name - The name to set remaining link name to. This can be null. If null, it sets the remaining name field to null.
See Also:
getLinkRemainingName()

setLinkResolvedObj

public void setLinkResolvedObj(Object obj)
Sets the link resolved object field of this exception. This indicates the last successfully resolved object of link name.

Parameters:
obj - The object to set link resolved object to. This can be null. If null, the link resolved object field is set to null.
See Also:
getLinkResolvedObj()

toString

public String toString()
Generates the string representation of this exception. This string consists of the NamingException information plus the link's remaining name. This string is used for debugging and not meant to be interpreted programmatically.

Overrides:
toString in class NamingException
Returns:
The non-null string representation of this link exception.

toString

public String toString(boolean detail)
Generates the string representation of this exception. This string consists of the NamingException information plus the additional information of resolving the link. If 'detail' is true, the string also contains information on the link resolved object. If false, this method is the same as the form of toString() that accepts no parameters. This string is used for debugging and not meant to be interpreted programmatically.

Overrides:
toString in class NamingException
Parameters:
detail - If true, add information about the link resolved object.
Returns:
The non-null string representation of this link exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LinkLoopException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class LinkLoopException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.LinkException
                    extended by  javax.naming.LinkLoopException
All Implemented Interfaces:
Serializable
public class LinkLoopException
extends LinkException

This exception is thrown when a loop was detected will attempting to resolve a link, or an implementation specific limit on link counts has been reached.

Synchronization and serialization issues that apply to LinkException apply directly here.

Since:
1.3
See Also:
LinkRef, Serialized Form

Field Summary
Fields inherited from class javax.naming.LinkException
linkExplanation, linkRemainingName, linkResolvedName, linkResolvedObj
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
LinkLoopException()
Constructs a new instance of LinkLoopException.
LinkLoopException(String explanation)
Constructs a new instance of LinkLoopException with an explanation All the other fields are initialized to null.
Method Summary
Methods inherited from class javax.naming.LinkException
getLinkExplanation, getLinkRemainingName, getLinkResolvedName, getLinkResolvedObj, setLinkExplanation, setLinkRemainingName, setLinkResolvedName, setLinkResolvedObj, toString, toString
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

LinkLoopException

public LinkLoopException(String explanation)
Constructs a new instance of LinkLoopException with an explanation All the other fields are initialized to null.

Parameters:
explanation - A possibly null string containing additional detail about this exception.
See Also:
Throwable.getMessage()

LinkLoopException

public LinkLoopException()
Constructs a new instance of LinkLoopException. All the non-link-related and link-related fields are initialized to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LinkRef

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class LinkRef

java.lang.Object
    extended by  javax.naming.Reference
        extended by  javax.naming.LinkRef
All Implemented Interfaces:
Serializable, Cloneable
public class LinkRef
extends Reference

This class represents a Reference whose contents is a name, called the link name, that is bound to an atomic name in a context.

The name is a URL, or a name to be resolved relative to the initial context, or if the first character of the name is ".", the name is relative to the context in which the link is bound.

Normal resolution of names in context operations always follow links. Resolution of the link name itself may cause resolution to pass through other links. This gives rise to the possibility of a cycle of links whose resolution could not terminate normally. As a simple means to avoid such non-terminating resolutions, service providers may define limits on the number of links that may be involved in any single operation invoked by the caller.

A LinkRef contains a single StringRefAddr, whose type is "LinkAddress", and whose contents is the link name. The class name field of the Reference is that of this (LinkRef) class.

LinkRef is bound to a name using the normal Context.bind()/rebind(), and DirContext.bind()/rebind(). Context.lookupLink() is used to retrieve the link itself if the terminal atomic name is bound to a link.

Many naming systems support a native notion of link that may be used within the naming system itself. JNDI does not specify whether there is any relationship between such native links and JNDI links.

A LinkRef instance is not synchronized against concurrent access by multiple threads. Threads that need to access a LinkRef instance concurrently should synchronize amongst themselves and provide the necessary locking.

Since:
1.3
See Also:
LinkException, LinkLoopException, MalformedLinkException, Context.lookupLink(javax.naming.Name), Serialized Form

Field Summary
Fields inherited from class javax.naming.Reference
addrs, classFactory, classFactoryLocation, className
Constructor Summary
LinkRef(Name linkName)
Constructs a LinkRef for a name.
LinkRef(String linkName)
Constructs a LinkRef for a string name.
Method Summary
 String getLinkName()
Retrieves the name of this link.
Methods inherited from class javax.naming.Reference
add, add, clear, clone, equals, get, get, getAll, getClassName, getFactoryClassLocation, getFactoryClassName, hashCode, remove, size, toString
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

LinkRef

public LinkRef(Name linkName)
Constructs a LinkRef for a name.

Parameters:
linkName - The non-null name for which to create this link.

LinkRef

public LinkRef(String linkName)
Constructs a LinkRef for a string name.

Parameters:
linkName - The non-null name for which to create this link.
Method Detail

getLinkName

public String getLinkName()
                   throws NamingException
Retrieves the name of this link.

Returns:
The non-null name of this link.
Throws:
MalformedLinkException - If a link name could not be extracted
NamingException - If a naming exception was encountered.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MalformedLinkException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class MalformedLinkException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.LinkException
                    extended by  javax.naming.MalformedLinkException
All Implemented Interfaces:
Serializable
public class MalformedLinkException
extends LinkException

This exception is thrown when a malformed link was encountered while resolving or constructing a link.

Synchronization and serialization issues that apply to LinkException apply directly here.

Since:
1.3
See Also:
LinkRef.getLinkName(), LinkRef, Serialized Form

Field Summary
Fields inherited from class javax.naming.LinkException
linkExplanation, linkRemainingName, linkResolvedName, linkResolvedObj
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
MalformedLinkException()
Constructs a new instance of Malformed LinkException.
MalformedLinkException(String explanation)
Constructs a new instance of MalformedLinkException with an explanation All the other fields are initialized to null.
Method Summary
Methods inherited from class javax.naming.LinkException
getLinkExplanation, getLinkRemainingName, getLinkResolvedName, getLinkResolvedObj, setLinkExplanation, setLinkRemainingName, setLinkResolvedName, setLinkResolvedObj, toString, toString
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MalformedLinkException

public MalformedLinkException(String explanation)
Constructs a new instance of MalformedLinkException with an explanation All the other fields are initialized to null.

Parameters:
explanation - A possibly null string containing additional detail about this exception.

MalformedLinkException

public MalformedLinkException()
Constructs a new instance of Malformed LinkException. All fields are initialized to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Name

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Interface Name

All Superinterfaces:
Cloneable, Comparable<Object>, Serializable
All Known Implementing Classes:
CompositeName, CompoundName, LdapName
public interface Name
extends Cloneable, Serializable, Comparable<Object>

The Name interface represents a generic name -- an ordered sequence of components. It can be a composite name (names that span multiple namespaces), or a compound name (names that are used within individual hierarchical naming systems).

There can be different implementations of Name; for example, composite names, URLs, or namespace-specific compound names.

The components of a name are numbered. The indexes of a name with N components range from 0 up to, but not including, N. This range may be written as [0,N). The most significant component is at index 0. An empty name has no components.

None of the methods in this interface accept null as a valid value for a parameter that is a name or a name component. Likewise, methods that return a name or name component never return null.

An instance of a Name may not be synchronized against concurrent multithreaded access if that access is not read-only.

Since:
1.3

Field Summary
static long serialVersionUID
The class fingerprint that is set to indicate serialization compatibility with a previous version of the class.
Method Summary
Name | add(int posn, String comp) Adds a single component at a specified position within this name.
Name | add(String comp) Adds a single component to the end of this name.
Name | addAll(int posn, Name n) Adds the components of a name -- in order -- at a specified position within this name.
Name | addAll(Name suffix) Adds the components of a name -- in order -- to the end of this name.
Object | clone() Generates a new copy of this name.
int | compareTo(Object obj) Compares this name with another name for order.
boolean | endsWith(Name n) Determines whether this name ends with a specified suffix.
String | get(int posn) Retrieves a component of this name.
Enumeration<String> | getAll() Retrieves the components of this name as an enumeration of strings.
Name | getPrefix(int posn) Creates a name whose components consist of a prefix of the components of this name.
Name | getSuffix(int posn) Creates a name whose components consist of a suffix of the components in this name.
boolean | isEmpty() Determines whether this name is empty.
Object | remove(int posn) Removes a component from this name.
int | size() Returns the number of components in this name.
boolean | startsWith(Name n) Determines whether this name starts with a specified prefix.

Field Detail

serialVersionUID

static final long serialVersionUID
The class fingerprint that is set to indicate serialization compatibility with a previous version of the class.

See Also:
Constant Field Values
Method Detail

clone

Object clone()
Generates a new copy of this name. Subsequent changes to the components of this name will not affect the new copy, and vice versa.

Returns:
a copy of this name
See Also:
Object.clone()

compareTo

int compareTo(Object obj)
Compares this name with another name for order. Returns a negative integer, zero, or a positive integer as this name is less than, equal to, or greater than the given name.

As with Object.equals(), the notion of ordering for names depends on the class that implements this interface. For example, the ordering may be based on lexicographical ordering of the name components. Specific attributes of the name, such as how it treats case, may affect the ordering. In general, two names of different classes may not be compared.

Specified by:
compareTo in interface Comparable<Object>
Parameters:
obj - the non-null object to compare against.
Returns:
a negative integer, zero, or a positive integer as this name is less than, equal to, or greater than the given name
Throws:
ClassCastException - if obj is not a Name of a type that may be compared with this name
See Also:
Comparable.compareTo(Object)

size

int size()
Returns the number of components in this name.

Returns:
the number of components in this name

isEmpty

boolean isEmpty()
Determines whether this name is empty. An empty name is one with zero components.

Returns:
true if this name is empty, false otherwise

getAll

Enumeration<String> getAll()
Retrieves the components of this name as an enumeration of strings. The effect on the enumeration of updates to this name is undefined. If the name has zero components, an empty (non-null) enumeration is returned.

Returns:
an enumeration of the components of this name, each a string

get

String get(int posn)
Retrieves a component of this name.

Parameters:
posn - the 0-based index of the component to retrieve. Must be in the range [0,size()).
Returns:
the component at index posn
Throws:
ArrayIndexOutOfBoundsException - if posn is outside the specified range

getPrefix

Name getPrefix(int posn)
Creates a name whose components consist of a prefix of the components of this name. Subsequent changes to this name will not affect the name that is returned and vice versa.

Parameters:
posn - the 0-based index of the component at which to stop. Must be in the range [0,size()].
Returns:
a name consisting of the components at indexes in the range [0,posn).
Throws:
ArrayIndexOutOfBoundsException - if posn is outside the specified range

getSuffix

Name getSuffix(int posn)
Creates a name whose components consist of a suffix of the components in this name. Subsequent changes to this name do not affect the name that is returned and vice versa.

Parameters:
posn - the 0-based index of the component at which to start. Must be in the range [0,size()].
Returns:
a name consisting of the components at indexes in the range [posn,size()). If posn is equal to size(), an empty name is returned.
Throws:
ArrayIndexOutOfBoundsException - if posn is outside the specified range

startsWith

boolean startsWith(Name n)
Determines whether this name starts with a specified prefix. A name n is a prefix if it is equal to getPrefix(n.size()).

Parameters:
n - the name to check
Returns:
true if n is a prefix of this name, false otherwise

endsWith

boolean endsWith(Name n)
Determines whether this name ends with a specified suffix. A name n is a suffix if it is equal to getSuffix(size()-n.size()).

Parameters:
n - the name to check
Returns:
true if n is a suffix of this name, false otherwise

addAll

Name addAll(Name suffix)
            throws InvalidNameException
Adds the components of a name -- in order -- to the end of this name.

Parameters:
suffix - the components to add
Returns:
the updated name (not a new one)
Throws:
InvalidNameException - if suffix is not a valid name, or if the addition of the components would violate the syntax rules of this name

addAll

Name addAll(int posn,
            Name n)
            throws InvalidNameException
Adds the components of a name -- in order -- at a specified position within this name. Components of this name at or after the index of the first new component are shifted up (away from 0) to accommodate the new components.

Parameters:
n - the components to add
posn - the index in this name at which to add the new components. Must be in the range [0,size()].
Returns:
the updated name (not a new one)
Throws:
ArrayIndexOutOfBoundsException - if posn is outside the specified range
InvalidNameException - if n is not a valid name, or if the addition of the components would violate the syntax rules of this name

add

Name add(String comp)
         throws InvalidNameException
Adds a single component to the end of this name.

Parameters:
comp - the component to add
Returns:
the updated name (not a new one)
Throws:
InvalidNameException - if adding comp would violate the syntax rules of this name

add

Name add(int posn,
         String comp)
         throws InvalidNameException
Adds a single component at a specified position within this name. Components of this name at or after the index of the new component are shifted up by one (away from index 0) to accommodate the new component.

Parameters:
comp - the component to add
posn - the index at which to add the new component. Must be in the range [0,size()].
Returns:
the updated name (not a new one)
Throws:
ArrayIndexOutOfBoundsException - if posn is outside the specified range
InvalidNameException - if adding comp would violate the syntax rules of this name

remove

Object remove(int posn)
              throws InvalidNameException
Removes a component from this name. The component of this name at the specified position is removed. Components with indexes greater than this position are shifted down (toward index 0) by one.

Parameters:
posn - the index of the component to remove. Must be in the range [0,size()).
Returns:
the component removed (a String)
Throws:
ArrayIndexOutOfBoundsException - if posn is outside the specified range
InvalidNameException - if deleting the component would violate the syntax rules of the name
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameAlreadyBoundException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class NameAlreadyBoundException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.NameAlreadyBoundException
All Implemented Interfaces:
Serializable
public class NameAlreadyBoundException
extends NamingException

This exception is thrown by methods to indicate that a binding cannot be added because the name is already bound to another object.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Context.bind(javax.naming.Name, java.lang.Object),
Context.rebind(javax.naming.Name, java.lang.Object),
Context.createSubcontext(javax.naming.Name),
DirContext.bind(javax.naming.Name, java.lang.Object, javax.naming.directory.Attributes),
DirContext.rebind(javax.naming.Name, java.lang.Object, javax.naming.directory.Attributes),
DirContext.createSubcontext(javax.naming.Name, javax.naming.directory.Attributes),
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
NameAlreadyBoundException()
Constructs a new instance of NameAlreadyBoundException.
NameAlreadyBoundException(String explanation)
Constructs a new instance of NameAlreadyBoundException using the explanation supplied.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NameAlreadyBoundException

public NameAlreadyBoundException(String explanation)
Constructs a new instance of NameAlreadyBoundException using the explanation supplied. All other fields default to null.

Parameters:
explanation - Possibly null additional detail about this exception.
See Also:
Throwable.getMessage()

NameAlreadyBoundException

public NameAlreadyBoundException()
Constructs a new instance of NameAlreadyBoundException. All fields are set to null;

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameClassPair

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class NameClassPair

java.lang.Object
    extended by  javax.naming.NameClassPair
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
Binding
public class NameClassPair
extends Object
implements Serializable

This class represents the object name and class name pair of a binding found in a context.

A context consists of name-to-object bindings. The NameClassPair class represents the name and the class of the bound object. It consists of a name and a string representing the package-qualified class name.

Use subclassing for naming systems that generate contents of a name/class pair dynamically.

A NameClassPair instance is not synchronized against concurrent access by multiple threads. Threads that need to access a NameClassPair concurrently should synchronize amongst themselves and provide the necessary locking.

Since:
1.3
See Also:
Context.list(javax.naming.Name), Serialized Form

Constructor Summary
NameClassPair(String name, String className)
Constructs an instance of a NameClassPair given its name and class name.
NameClassPair(String name, String className, boolean isRelative)
Constructs an instance of a NameClassPair given its name, class name, and whether it is relative to the listing context.
Method Summary
 String getClassName()
Retrieves the class name of the object bound to the name of this binding.
 String getName()
Retrieves the name of this binding.
 String getNameInNamespace()
Retrieves the full name of this binding.
 boolean isRelative()
Determines whether the name of this binding is relative to the target context (which is named by the first parameter of the list() method).
 void setClassName(String name)
Sets the class name of this binding.
 void setName(String name)
Sets the name of this binding.
 void setNameInNamespace(String fullName)
Sets the full name of this binding.
 void setRelative(boolean r)
Sets whether the name of this binding is relative to the target context (which is named by the first parameter of the list() method).
 String toString()
Generates the string representation of this name/class pair.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NameClassPair

public NameClassPair(String name,
                     String className)
Constructs an instance of a NameClassPair given its name and class name.

Parameters:
name - The non-null name of the object. It is relative to the target context (which is named by the first parameter of the list() method)
className - The possibly null class name of the object bound to name. It is null if the object bound is null.
See Also:
getClassName(),
setClassName(java.lang.String),
getName(),
setName(java.lang.String)

NameClassPair

public NameClassPair(String name,
                     String className,
                     boolean isRelative)
Constructs an instance of a NameClassPair given its name, class name, and whether it is relative to the listing context.

Parameters:
name - The non-null name of the object.
className - The possibly null class name of the object bound to name. It is null if the object bound is null.
isRelative - true if name is a name relative to the target context (which is named by the first parameter of the list() method); false if name is a URL string.
See Also:
getClassName(),
setClassName(java.lang.String),
getName(),
setName(java.lang.String),
isRelative(),
setRelative(boolean)
Method Detail

getClassName

public String getClassName()
Retrieves the class name of the object bound to the name of this binding. If a reference or some other indirect information is bound, retrieves the class name of the eventual object that will be returned by Binding.getObject().

Returns:
The possibly null class name of object bound. It is null if the object bound is null.
See Also:
Binding.getObject(),
Binding.getClassName(),
setClassName(java.lang.String)

getName

public String getName()
Retrieves the name of this binding. If isRelative() is true, this name is relative to the target context (which is named by the first parameter of the list()). If isRelative() is false, this name is a URL string.

Returns:
The non-null name of this binding.
See Also:
isRelative(), setName(java.lang.String)

setName

public void setName(String name)
Sets the name of this binding.

Parameters:
name - the non-null string to use as the name.
See Also:
getName(), setRelative(boolean)

setClassName

public void setClassName(String name)
Sets the class name of this binding.

Parameters:
name - the possibly null string to use as the class name. If null, Binding.getClassName() will return the actual class name of the object in the binding. The class name will be null if the object bound is null.
See Also:
getClassName(), Binding.getClassName()

isRelative

public boolean isRelative()
Determines whether the name of this binding is relative to the target context (which is named by the first parameter of the list() method).

Returns:
true if the name of this binding is relative to the target context; false if the name of this binding is a URL string.
See Also:
setRelative(boolean), getName()

setRelative

public void setRelative(boolean r)
Sets whether the name of this binding is relative to the target context (which is named by the first parameter of the list() method).

Parameters:
r - If true, the name of binding is relative to the target context; if false, the name of binding is a URL string.
See Also:
isRelative(), setName(java.lang.String)

getNameInNamespace

public String getNameInNamespace()
Retrieves the full name of this binding. The full name is the absolute name of this binding within its own namespace. See Context.getNameInNamespace().

In naming systems for which the notion of full name does not apply to this binding an UnsupportedOperationException is thrown. This exception is also thrown when a service provider written before the introduction of the method is in use.

The string returned by this method is not a JNDI composite name and should not be passed directly to context methods.

Returns:
The full name of this binding.
Throws:
UnsupportedOperationException - if the notion of full name does not apply to this binding in the naming system.
Since:
1.5
See Also:
setNameInNamespace(java.lang.String), getName()

setNameInNamespace

public void setNameInNamespace(String fullName)
Sets the full name of this binding. This method must be called to set the full name whenever a NameClassPair is created and a full name is applicable to this binding.

Setting the full name to null, or not setting it at all, will cause getNameInNamespace() to throw an exception.

Parameters:
fullName - The full name to use.
Since:
1.5
See Also:
getNameInNamespace(), setName(java.lang.String)

toString

public String toString()
Generates the string representation of this name/class pair. The string representation consists of the name and class name separated by a colon (':'). The contents of this string is useful for debugging and is not meant to be interpreted programmatically.

Overrides:
toString in class Object
Returns:
The string representation of this name/class pair.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameNotFoundException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class NameNotFoundException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.NameNotFoundException
All Implemented Interfaces:
Serializable
public class NameNotFoundException
extends NamingException

This exception is thrown when a component of the name cannot be resolved because it is not bound.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
NameNotFoundException()
Constructs a new instance of NameNotFoundException.
NameNotFoundException(String explanation)
Constructs a new instance of NameNotFoundException using the explanation supplied.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NameNotFoundException

public NameNotFoundException(String explanation)
Constructs a new instance of NameNotFoundException using the explanation supplied. All other fields default to null.

Parameters:
explanation - Possibly null additional detail about this exception.
See Also:
Throwable.getMessage()

NameNotFoundException

public NameNotFoundException()
Constructs a new instance of NameNotFoundException. all name resolution fields and explanation initialized to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameParser

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Interface NameParser

public interface NameParser

This interface is used for parsing names from a hierarchical namespace. The NameParser contains knowledge of the syntactic information (like left-to-right orientation, name separator, etc.) needed to parse names. The equals() method, when used to compare two NameParsers, returns true if and only if they serve the same namespace.

Since:
1.3
See Also:
CompoundName, Name

Method Summary
 Name parse(String name)
Parses a name into its components.

Method Detail

parse

Name parse(String name)
           throws NamingException
Parses a name into its components.

Parameters:
name - The non-null string name to parse.
Returns:
A non-null parsed form of the name using the naming convention of this parser.
Throws:
InvalidNameException - If name does not conform to syntax defined for the namespace.
NamingException - If a naming exception was encountered.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamingEnumeration

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Interface NamingEnumeration<T>

All Superinterfaces:
Enumeration<T>
public interface NamingEnumeration<T>
extends Enumeration<T>

This interface is for enumerating lists returned by methods in the javax.naming and javax.naming.directory packages. It extends Enumeration to allow as exceptions to be thrown during the enumeration.

When a method such as list(), listBindings(), or search() returns a NamingEnumeration, any exceptions encountered are reserved until all results have been returned. At the end of the enumeration, the exception is thrown (by hasMore());

For example, if the list() is returning only a partial answer, the corresponding exception would be PartialResultException. list() would first return a NamingEnumeration. When the last of the results has been returned by the NamingEnumeration's next(), invoking hasMore() would result in PartialResultException being thrown.

In another example, if a search() method was invoked with a specified size limit of 'n'. If the answer consists of more than 'n' results, search() would first return a NamingEnumeration. When the n'th result has been returned by invoking next() on the NamingEnumeration, a SizeLimitExceedException would then thrown when hasMore() is invoked.

Note that if the program uses hasMoreElements() and nextElement() instead to iterate through the NamingEnumeration, because these methods cannot throw exceptions, no exception will be thrown. Instead, in the previous example, after the n'th result has been returned by nextElement(), invoking hasMoreElements() would return false.

Note also that NoSuchElementException is thrown if the program invokes next() or nextElement() when there are no elements left in the enumeration. The program can always avoid this exception by using hasMore() and hasMoreElements() to check whether the end of the enumeration has been reached.

If an exception is thrown during an enumeration, the enumeration becomes invalid. Subsequent invocation of any method on that enumeration will yield undefined results.

Since:
1.3
See Also:
Context.list(javax.naming.Name),
Context.listBindings(javax.naming.Name),
DirContext.search(javax.naming.Name, javax.naming.directory.Attributes, java.lang.String[]),
Attributes.getAll(),
Attributes.getIDs(),
Attribute.getAll()

Method Summary
void | close() Closes this enumeration.
boolean | hasMore() Determines whether there are any more elements in the enumeration.
T | next() Retrieves the next element in the enumeration.
Methods inherited from interface java.util.Enumeration
hasMoreElements, nextElement

Method Detail

next

T next()
       throws NamingException
Retrieves the next element in the enumeration. This method allows naming exceptions encountered while retrieving the next element to be caught and handled by the application.

Note that next() can also throw the runtime exception NoSuchElementException to indicate that the caller is attempting to enumerate beyond the end of the enumeration. This is different from a NamingException, which indicates that there was a problem in obtaining the next element, for example, due to a referral or server unavailability, etc.

Returns:
The possibly null element in the enumeration. null is only valid for enumerations that can return null (e.g. Attribute.getAll() returns an enumeration of attribute values, and an attribute value can be null).
Throws:
NamingException - If a naming exception is encountered while attempting to retrieve the next element. See NamingException and its subclasses for the possible naming exceptions.
NoSuchElementException - If attempting to get the next element when none is available.
See Also:
Enumeration.nextElement()

hasMore

boolean hasMore()
                throws NamingException
Determines whether there are any more elements in the enumeration. This method allows naming exceptions encountered while determining whether there are more elements to be caught and handled by the application.

Returns:
true if there is more in the enumeration ; false otherwise.
Throws:
NamingException - If a naming exception is encountered while attempting to determine whether there is another element in the enumeration. See NamingException and its subclasses for the possible naming exceptions.
See Also:
Enumeration.hasMoreElements()

close

void close()
           throws NamingException
Closes this enumeration. After this method has been invoked on this enumeration, the enumeration becomes invalid and subsequent invocation of any of its methods will yield undefined results. This method is intended for aborting an enumeration to free up resources. If an enumeration proceeds to the end--that is, until hasMoreElements() or hasMore() returns false-- resources will be freed up automatically and there is no need to explicitly call close().

This method indicates to the service provider that it is free to release resources associated with the enumeration, and can notify servers to cancel any outstanding requests. The close() method is a hint to implementations for managing their resources. Implementations are encouraged to use appropriate algorithms to manage their resources when client omits the close() calls.

Throws:
NamingException - If a naming exception is encountered while closing the enumeration.
Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamingException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class NamingException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
AttributeInUseException, AttributeModificationException, CannotProceedException, CommunicationException, ConfigurationException, ContextNotEmptyException, InsufficientResourcesException, InterruptedNamingException, InvalidAttributeIdentifierException, InvalidAttributesException, InvalidAttributeValueException, InvalidNameException, InvalidSearchControlsException, InvalidSearchFilterException, LimitExceededException, LinkException, NameAlreadyBoundException, NameNotFoundException, NamingSecurityException, NoInitialContextException, NoSuchAttributeException, NotContextException, OperationNotSupportedException, PartialResultException, ReferralException, SchemaViolationException, ServiceUnavailableException
public class NamingException
extends Exception

This is the superclass of all exceptions thrown by operations in the Context and DirContext interfaces. The nature of the failure is described by the name of the subclass. This exception captures the information pinpointing where the operation failed, such as where resolution last proceeded to.

  • Resolved Name. Portion of name that has been resolved.
  • Resolved Object. Object to which resolution of name proceeded.
  • Remaining Name. Portion of name that has not been resolved.
  • Explanation. Detail explaining why name resolution failed.
  • Root Exception. The exception that caused this naming exception to be thrown.
null is an acceptable value for any of these fields. When null, it means that no such information has been recorded for that field.

A NamingException instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify a single NamingException instance should lock the object.

This exception has been retrofitted to conform to the general purpose exception-chaining mechanism. The root exception (or root cause) is the same object as the cause returned by the Throwable.getCause() method.

Since:
1.3
See Also:
Serialized Form

Field Summary
protected Name | remainingName Contains the remaining name that has not been resolved yet.
protected Name | resolvedName Contains the part of the name that has been successfully resolved.
protected Object | resolvedObj Contains the object to which resolution of the part of the name was successful.
protected Throwable | rootException Contains the original exception that caused this NamingException to be thrown.
Constructor Summary
NamingException()
Constructs a new NamingException.
NamingException(String explanation)
Constructs a new NamingException with an explanation.
Method Summary
void | appendRemainingComponent(String name) Add name as the last component in remaining name.
void | appendRemainingName(Name name) Add components from 'name' as the last components in remaining name.
Throwable | getCause() Returns the cause of this exception.
String | getExplanation() Retrieves the explanation associated with this exception.
Name | getRemainingName() Retrieves the remaining unresolved portion of the name.
Name | getResolvedName() Retrieves the leading portion of the name that was resolved successfully.
Object | getResolvedObj() Retrieves the object to which resolution was successful.
Throwable | getRootCause() Retrieves the root cause of this NamingException, if any.
Throwable | initCause(Throwable cause) Initializes the cause of this exception to the specified value.
void | setRemainingName(Name name) Sets the remaining name field of this exception.
void | setResolvedName(Name name) Sets the resolved name field of this exception.
void | setResolvedObj(Object obj) Sets the resolved object field of this exception.
void | setRootCause(Throwable e) Records the root cause of this NamingException.
String | toString() Generates the string representation of this exception.
String | toString(boolean detail) Generates the string representation in more detail.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

resolvedName

protected Name resolvedName
Contains the part of the name that has been successfully resolved. It is a composite name and can be null. This field is initialized by the constructors. You should access and manipulate this field through its get and set methods.

See Also:
getResolvedName(), setResolvedName(javax.naming.Name)

resolvedObj

protected Object resolvedObj
Contains the object to which resolution of the part of the name was successful. Can be null. This field is initialized by the constructors. You should access and manipulate this field through its get and set methods.

See Also:
getResolvedObj(), setResolvedObj(java.lang.Object)

remainingName

protected Name remainingName
Contains the remaining name that has not been resolved yet. It is a composite name and can be null. This field is initialized by the constructors. You should access and manipulate this field through its get, set, "append" methods.

See Also:
getRemainingName(),
setRemainingName(javax.naming.Name),
appendRemainingName(javax.naming.Name),
appendRemainingComponent(java.lang.String)

rootException

protected Throwable rootException
Contains the original exception that caused this NamingException to be thrown. This field is set if there is additional information that could be obtained from the original exception, or if the original exception could not be mapped to a subclass of NamingException. Can be null.

This field predates the general-purpose exception chaining facility. The initCause(Throwable) and getCause() methods are now the preferred means of accessing this information.

See Also:
getRootCause(), setRootCause(Throwable), initCause(Throwable), getCause()
Constructor Detail

NamingException

public NamingException(String explanation)
Constructs a new NamingException with an explanation. All unspecified fields are set to null.

Parameters:
explanation - A possibly null string containing additional detail about this exception.
See Also:
Throwable.getMessage()

NamingException

public NamingException()
Constructs a new NamingException. All fields are set to null.

Method Detail

getResolvedName

public Name getResolvedName()
Retrieves the leading portion of the name that was resolved successfully.

Returns:
The part of the name that was resolved successfully. It is a composite name. It can be null, which means the resolved name field has not been set.
See Also:
getResolvedObj(), setResolvedName(javax.naming.Name)

getRemainingName

public Name getRemainingName()
Retrieves the remaining unresolved portion of the name.

Returns:
The part of the name that has not been resolved. It is a composite name. It can be null, which means the remaining name field has not been set.
See Also:
setRemainingName(javax.naming.Name),
appendRemainingName(javax.naming.Name),
appendRemainingComponent(java.lang.String)

getResolvedObj

public Object getResolvedObj()
Retrieves the object to which resolution was successful. This is the object to which the resolved name is bound.

Returns:
The possibly null object that was resolved so far. null means that the resolved object field has not been set.
See Also:
getResolvedName(), setResolvedObj(java.lang.Object)

getExplanation

public String getExplanation()
Retrieves the explanation associated with this exception.

Returns:
The possibly null detail string explaining more about this exception. If null, it means there is no detail message for this exception.
See Also:
Throwable.getMessage()

setResolvedName

public void setResolvedName(Name name)
Sets the resolved name field of this exception.

name is a composite name. If the intent is to set this field using a compound name or string, you must "stringify" the compound name, and create a composite name with a single component using the string. You can then invoke this method using the resulting composite name.

A copy of name is made and stored. Subsequent changes to name does not affect the copy in this NamingException and vice versa.

Parameters:
name - The possibly null name to set resolved name to. If null, it sets the resolved name field to null.
See Also:
getResolvedName()

setRemainingName

public void setRemainingName(Name name)
Sets the remaining name field of this exception.

name is a composite name. If the intent is to set this field using a compound name or string, you must "stringify" the compound name, and create a composite name with a single component using the string. You can then invoke this method using the resulting composite name.

A copy of name is made and stored. Subsequent changes to name does not affect the copy in this NamingException and vice versa.

Parameters:
name - The possibly null name to set remaining name to. If null, it sets the remaining name field to null.
See Also:
getRemainingName(),
appendRemainingName(javax.naming.Name),
appendRemainingComponent(java.lang.String)

setResolvedObj

public void setResolvedObj(Object obj)
Sets the resolved object field of this exception.

Parameters:
obj - The possibly null object to set resolved object to. If null, the resolved object field is set to null.
See Also:
getResolvedObj()

appendRemainingComponent

public void appendRemainingComponent(String name)
Add name as the last component in remaining name.

Parameters:
name - The component to add. If name is null, this method does not do anything.
See Also:
setRemainingName(javax.naming.Name),
getRemainingName(),
appendRemainingName(javax.naming.Name)

appendRemainingName

public void appendRemainingName(Name name)
Add components from 'name' as the last components in remaining name.

name is a composite name. If the intent is to append a compound name, you should "stringify" the compound name then invoke the overloaded form that accepts a String parameter.

Subsequent changes to name does not affect the remaining name field in this NamingException and vice versa.

Parameters:
name - The possibly null name containing ordered components to add. If name is null, this method does not do anything.
See Also:
setRemainingName(javax.naming.Name),
getRemainingName(),
appendRemainingComponent(java.lang.String)

getRootCause

public Throwable getRootCause()
Retrieves the root cause of this NamingException, if any. The root cause of a naming exception is used when the service provider wants to indicate to the caller a non-naming related exception but at the same time wants to use the NamingException structure to indicate how far the naming operation proceeded.

This method predates the general-purpose exception chaining facility. The getCause() method is now the preferred means of obtaining this information.

Returns:
The possibly null exception that caused this naming exception. If null, it means no root cause has been set for this naming exception.
See Also:
setRootCause(java.lang.Throwable), rootException, getCause()

setRootCause

public void setRootCause(Throwable e)
Records the root cause of this NamingException. If e is this, this method does not do anything.

This method predates the general-purpose exception chaining facility. The initCause(Throwable) method is now the preferred means of recording this information.

Parameters:
e - The possibly null exception that caused the naming operation to fail. If null, it means this naming exception has no root cause.
See Also:
getRootCause(), rootException, initCause(java.lang.Throwable)

getCause

public Throwable getCause()
Returns the cause of this exception. The cause is the throwable that caused this naming exception to be thrown. Returns null if the cause is nonexistent or unknown.

Overrides:
getCause in class Throwable
Returns:
the cause of this exception, or null if the cause is nonexistent or unknown.
Since:
1.4
See Also:
initCause(Throwable)

initCause

public Throwable initCause(Throwable cause)
Initializes the cause of this exception to the specified value. The cause is the throwable that caused this naming exception to be thrown.

This method may be called at most once.

Overrides:
initCause in class Throwable
Parameters:
cause - the cause, which is saved for later retrieval by the getCause() method. A null value indicates that the cause is nonexistent or unknown.
Returns:
a reference to this NamingException instance.
Throws:
IllegalArgumentException - if cause is this exception. (A throwable cannot be its own cause.)
IllegalStateException - if this method has already been called on this exception.
Since:
1.4
See Also:
getCause()

toString

public String toString()
Generates the string representation of this exception. The string representation consists of this exception's class name, its detailed message, and if it has a root cause, the string representation of the root cause exception, followed by the remaining name (if it is not null). This string is used for debugging and not meant to be interpreted programmatically.

Overrides:
toString in class Throwable
Returns:
The non-null string containing the string representation of this exception.

toString

public String toString(boolean detail)
Generates the string representation in more detail. This string representation consists of the information returned by the toString() that takes no parameters, plus the string representation of the resolved object (if it is not null). This string is used for debugging and not meant to be interpreted programmatically.

Parameters:
detail - If true, include details about the resolved object in addition to the other information.
Returns:
The non-null string containing the string representation.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamingSecurityException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class NamingSecurityException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.NamingSecurityException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
AuthenticationException, AuthenticationNotSupportedException, NoPermissionException
public abstract class NamingSecurityException
extends NamingException

This is the superclass of security-related exceptions thrown by operations in the Context and DirContext interfaces. The nature of the failure is described by the name of the subclass.

If the program wants to handle this exception in particular, it should catch NamingSecurityException explicitly before attempting to catch NamingException. A program might want to do this, for example, if it wants to treat security-related exceptions specially from other sorts of naming exception.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
NamingSecurityException()
Constructs a new instance of NamingSecurityException.
NamingSecurityException(String explanation)
Constructs a new instance of NamingSecurityException using the explanation supplied.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NamingSecurityException

public NamingSecurityException(String explanation)
Constructs a new instance of NamingSecurityException using the explanation supplied. All other fields default to null.

Parameters:
explanation - Possibly null additional detail about this exception.
See Also:
Throwable.getMessage()

NamingSecurityException

public NamingSecurityException()
Constructs a new instance of NamingSecurityException. All fields are initialized to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NoInitialContextException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class NoInitialContextException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.NoInitialContextException
All Implemented Interfaces:
Serializable
public class NoInitialContextException
extends NamingException

This exception is thrown when no initial context implementation can be created. The policy of how an initial context implementation is selected is described in the documentation of the InitialContext class.

This exception can be thrown during any interaction with the InitialContext, not only when the InitialContext is constructed. For example, the implementation of the initial context might lazily retrieve the context only when actual methods are invoked on it. The application should not have any dependency on when the existence of an initial context is determined.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
InitialContext, InitialDirContext, NamingManager.getInitialContext(java.util.Hashtable), NamingManager.setInitialContextFactoryBuilder(javax.naming.spi.InitialContextFactoryBuilder), Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
NoInitialContextException()
Constructs an instance of NoInitialContextException.
NoInitialContextException(String explanation)
Constructs an instance of NoInitialContextException with an explanation.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NoInitialContextException

public NoInitialContextException()
Constructs an instance of NoInitialContextException. All fields are initialized to null.

NoInitialContextException

public NoInitialContextException(String explanation)
Constructs an instance of NoInitialContextException with an explanation. All other fields are initialized to null.

Parameters:
explanation - Possibly null additional detail about this exception.
See Also:
Throwable.getMessage()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NoPermissionException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class NoPermissionException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.NamingSecurityException
                    extended by  javax.naming.NoPermissionException
All Implemented Interfaces:
Serializable
public class NoPermissionException
extends NamingSecurityException

This exception is thrown when attempting to perform an operation for which the client has no permission. The access control/permission model is dictated by the directory/naming server.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
NoPermissionException()
Constructs a new instance of NoPermissionException.
NoPermissionException(String explanation)
Constructs a new instance of NoPermissionException using an explanation.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NoPermissionException

public NoPermissionException(String explanation)
Constructs a new instance of NoPermissionException using an explanation. All other fields default to null.

Parameters:
explanation - Possibly null additional detail about this exception.

NoPermissionException

public NoPermissionException()
Constructs a new instance of NoPermissionException. All fields are initialized to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotContextException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class NotContextException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.NotContextException
All Implemented Interfaces:
Serializable
public class NotContextException
extends NamingException

This exception is thrown when a naming operation proceeds to a point where a context is required to continue the operation, but the resolved object is not a context. For example, Context.destroy() requires that the named object be a context. If it is not, NotContextException is thrown. Another example is a non-context being encountered during the resolution phase of the Context methods.

It is also thrown when a particular subtype of context is required, such as a DirContext, and the resolved object is a context but not of the required subtype.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Context.destroySubcontext(javax.naming.Name), Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
NotContextException()
Constructs a new instance of NotContextException.
NotContextException(String explanation)
Constructs a new instance of NotContextException using an explanation.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NotContextException

public NotContextException(String explanation)
Constructs a new instance of NotContextException using an explanation. All other fields default to null.

Parameters:
explanation - Possibly null additional detail about this exception.
See Also:
Throwable.getMessage()

NotContextException

public NotContextException()
Constructs a new instance of NotContextException. All fields default to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OperationNotSupportedException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class OperationNotSupportedException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.OperationNotSupportedException
All Implemented Interfaces:
Serializable
public class OperationNotSupportedException
extends NamingException

This exception is thrown when a context implementation does not support the operation being invoked. For example, if a server does not support the Context.bind() method it would throw OperationNotSupportedException when the bind() method is invoked on it.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
OperationNotSupportedException()
Constructs a new instance of OperationNotSupportedException.
OperationNotSupportedException(String explanation)
Constructs a new instance of OperationNotSupportedException using an explanation.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

OperationNotSupportedException

public OperationNotSupportedException()
Constructs a new instance of OperationNotSupportedException. All fields default to null.

OperationNotSupportedException

public OperationNotSupportedException(String explanation)
Constructs a new instance of OperationNotSupportedException using an explanation. All other fields default to null.

Parameters:
explanation - Possibly null additional detail about this exception
See Also:
Throwable.getMessage()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PartialResultException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class PartialResultException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.PartialResultException
All Implemented Interfaces:
Serializable
public class PartialResultException
extends NamingException

This exception is thrown to indicate that the result being returned or returned so far is partial, and that the operation cannot be completed. For example, when listing a context, this exception indicates that returned results only represents some of the bindings in the context.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
PartialResultException()
Constructs a new instance of PartialResultException.
PartialResultException(String explanation)
Constructs a new instance of the exception using the explanation message specified.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PartialResultException

public PartialResultException(String explanation)
Constructs a new instance of the exception using the explanation message specified. All other fields default to null.

Parameters:
explanation - Possibly null detail explaining the exception.

PartialResultException

public PartialResultException()
Constructs a new instance of PartialResultException. All fields default to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RefAddr

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class RefAddr

java.lang.Object
    extended by  javax.naming.RefAddr
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
BinaryRefAddr, StringRefAddr
public abstract class RefAddr
extends Object
implements Serializable

This class represents the address of a communications end-point. It consists of a type that describes the communication mechanism and an address contents determined by an RefAddr subclass.

For example, an address type could be "BSD Printer Address", which specifies that it is an address to be used with the BSD printing protocol. Its contents could be the machine name identifying the location of the printer server that understands this protocol.

A RefAddr is contained within a Reference.

RefAddr is an abstract class. Concrete implementations of it determine its synchronization properties.

Since:
1.3
See Also:
Reference, LinkRef, StringRefAddr, BinaryRefAddr, Serialized Form

Field Summary
protected  String addrType
Contains the type of this address.
Constructor Summary
protected RefAddr(String addrType)
Constructs a new instance of RefAddr using its address type.
Method Summary
boolean | equals(Object obj) Determines whether obj is equal to this RefAddr.
abstract Object | getContent() Retrieves the contents of this address.
String | getType() Retrieves the address type of this address.
int | hashCode() Computes the hash code of this address using its address type and contents.
String | toString() Generates the string representation of this address.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

addrType

protected String addrType
Contains the type of this address.

Constructor Detail

RefAddr

protected RefAddr(String addrType)
Constructs a new instance of RefAddr using its address type.

Parameters:
addrType - A non-null string describing the type of the address.
Method Detail

getType

public String getType()
Retrieves the address type of this address.

Returns:
The non-null address type of this address.

getContent

public abstract Object getContent()
Retrieves the contents of this address.

Returns:
The possibly null address contents.

equals

public boolean equals(Object obj)
Determines whether obj is equal to this RefAddr.

obj is equal to this RefAddr all of these conditions are true

    non-null
  • instance of RefAddr
  • obj has the same address type as this RefAddr (using String.compareTo())
  • both obj and this RefAddr's contents are null or they are equal (using the equals() test).

Overrides:
equals in class Object
Parameters:
obj - possibly null obj to check.
Returns:
true if obj is equal to this refaddr; false otherwise.
See Also:
getContent(), getType()

hashCode

public int hashCode()
Computes the hash code of this address using its address type and contents. The hash code is the sum of the hash code of the address type and the hash code of the address contents.

Overrides:
hashCode in class Object
Returns:
The hash code of this address as an int.
See Also:
Object.hashCode()

toString

public String toString()
Generates the string representation of this address. The string consists of the address's type and contents with labels. This representation is intended for display only and not to be parsed.

Overrides:
toString in class Object
Returns:
The non-null string representation of this address.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Reference

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class Reference

java.lang.Object
    extended by  javax.naming.Reference
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
LinkRef
public class Reference
extends Object
implements Cloneable, Serializable

This class represents a reference to an object that is found outside of the naming/directory system.

Reference provides a way of recording address information about objects which themselves are not directly bound to the naming/directory system.

A Reference consists of an ordered list of addresses and class information about the object being referenced. Each address in the list identifies a communications endpoint for the same conceptual object. The "communications endpoint" is information that indicates how to contact the object. It could be, for example, a network address, a location in memory on the local machine, another process on the same machine, etc. The order of the addresses in the list may be of significance to object factories that interpret the reference.

Multiple addresses may arise for various reasons, such as replication or the object offering interfaces over more than one communication mechanism. The addresses are indexed starting with zero.

A Reference also contains information to assist in creating an instance of the object to which this Reference refers. It contains the class name of that object, and the class name and location of the factory to be used to create the object. The class factory location is a space-separated list of URLs representing the class path used to load the factory. When the factory class (or any class or resource upon which it depends) needs to be loaded, each URL is used (in order) to attempt to load the class.

A Reference instance is not synchronized against concurrent access by multiple threads. Threads that need to access a single Reference concurrently should synchronize amongst themselves and provide the necessary locking.

Since:
1.3
See Also:
RefAddr, StringRefAddr, BinaryRefAddr, Serialized Form

Field Summary
protected Vector<RefAddr> | addrs Contains the addresses contained in this Reference.
protected String | classFactory Contains the name of the factory class for creating an instance of the object to which this Reference refers.
protected String | classFactoryLocation Contains the location of the factory class.
protected String | className Contains the fully-qualified name of the class of the object to which this Reference refers.
Constructor Summary
Reference(String className)
Constructs a new reference for an object with class name 'className'.
Reference(String className, RefAddr addr)
Constructs a new reference for an object with class name 'className' and an address.
Reference(String className, RefAddr addr, String factory, String factoryLocation)
Constructs a new reference for an object with class name 'className', the class name and location of the object's factory, and the address for the object.
Reference(String className, String factory, String factoryLocation)
Constructs a new reference for an object with class name 'className', and the class name and location of the object's factory.
Method Summary
void | add(int posn, RefAddr addr) Adds an address to the list of addresses at index posn.
void | add(RefAddr addr) Adds an address to the end of the list of addresses.
void | clear() Deletes all addresses from this reference.
Object | clone() Makes a copy of this reference using its class name list of addresses, class factory name and class factory location.
boolean | equals(Object obj) Determines whether obj is a reference with the same addresses (in same order) as this reference.
RefAddr | get(int posn) Retrieves the address at index posn.
RefAddr | get(String addrType) Retrieves the first address that has the address type 'addrType'.
Enumeration<RefAddr> | getAll() Retrieves an enumeration of the addresses in this reference.
String | getClassName() Retrieves the class name of the object to which this reference refers.
String | getFactoryClassLocation() Retrieves the location of the factory of the object to which this reference refers.
String | getFactoryClassName() Retrieves the class name of the factory of the object to which this reference refers.
int | hashCode() Computes the hash code of this reference.
Object | remove(int posn) Deletes the address at index posn from the list of addresses.
int | size() Retrieves the number of addresses in this reference.
String | toString() Generates the string representation of this reference.
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

className

protected String className
Contains the fully-qualified name of the class of the object to which this Reference refers.

See Also:
Class.getName()

addrs

protected Vector<RefAddr> addrs
Contains the addresses contained in this Reference. Initialized by constructor.

classFactory

protected String classFactory
Contains the name of the factory class for creating an instance of the object to which this Reference refers. Initialized to null.

classFactoryLocation

protected String classFactoryLocation
Contains the location of the factory class. Initialized to null.

Constructor Detail

Reference

public Reference(String className)
Constructs a new reference for an object with class name 'className'. Class factory and class factory location are set to null. The newly created reference contains zero addresses.

Parameters:
className - The non-null class name of the object to which this reference refers.

Reference

public Reference(String className,
                 RefAddr addr)
Constructs a new reference for an object with class name 'className' and an address. Class factory and class factory location are set to null.

Parameters:
className - The non-null class name of the object to which this reference refers.
addr - The non-null address of the object.

Reference

public Reference(String className,
                 String factory,
                 String factoryLocation)
Constructs a new reference for an object with class name 'className', and the class name and location of the object's factory.

Parameters:
className - The non-null class name of the object to which this reference refers.
factory - The possibly null class name of the object's factory.
factoryLocation - The possibly null location from which to load the factory (e.g. URL)
See Also:
ObjectFactory, NamingManager.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable)

Reference

public Reference(String className,
                 RefAddr addr,
                 String factory,
                 String factoryLocation)
Constructs a new reference for an object with class name 'className', the class name and location of the object's factory, and the address for the object.

Parameters:
className - The non-null class name of the object to which this reference refers.
factory - The possibly null class name of the object's factory.
factoryLocation - The possibly null location from which to load the factory (e.g. URL)
addr - The non-null address of the object.
See Also:
ObjectFactory, NamingManager.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable)
Method Detail

getClassName

public String getClassName()
Retrieves the class name of the object to which this reference refers.

Returns:
The non-null fully-qualified class name of the object. (e.g. "java.lang.String")

getFactoryClassName

public String getFactoryClassName()
Retrieves the class name of the factory of the object to which this reference refers.

Returns:
The possibly null fully-qualified class name of the factory. (e.g. "java.lang.String")

getFactoryClassLocation

public String getFactoryClassLocation()
Retrieves the location of the factory of the object to which this reference refers. If it is a codebase, then it is an ordered list of URLs, separated by spaces, listing locations from where the factory class definition should be loaded.

Returns:
The possibly null string containing the location for loading in the factory's class.

get

public RefAddr get(String addrType)
Retrieves the first address that has the address type 'addrType'. String.compareTo() is used to test the equality of the address types.

Parameters:
addrType - The non-null address type for which to find the address.
Returns:
The address in this reference with address type 'addrType; null if no such address exist.

get

public RefAddr get(int posn)
Retrieves the address at index posn.

Parameters:
posn - The index of the address to retrieve.
Returns:
The address at the 0-based index posn. It must be in the range [0,getAddressCount()).
Throws:
ArrayIndexOutOfBoundsException - If posn not in the specified range.

getAll

public Enumeration<RefAddr> getAll()
Retrieves an enumeration of the addresses in this reference. When addresses are added, changed or removed from this reference, its effects on this enumeration are undefined.

Returns:
An non-null enumeration of the addresses (RefAddr) in this reference. If this reference has zero addresses, an enumeration with zero elements is returned.

size

public int size()
Retrieves the number of addresses in this reference.

Returns:
The nonnegative number of addresses in this reference.

add

public void add(RefAddr addr)
Adds an address to the end of the list of addresses.

Parameters:
addr - The non-null address to add.

add

public void add(int posn,
                RefAddr addr)
Adds an address to the list of addresses at index posn. All addresses at index posn or greater are shifted up the list by one (away from index 0).

Parameters:
posn - The 0-based index of the list to insert addr.
addr - The non-null address to add.
Throws:
ArrayIndexOutOfBoundsException - If posn not in the specified range.

remove

public Object remove(int posn)
Deletes the address at index posn from the list of addresses. All addresses at index greater than posn are shifted down the list by one (towards index 0).

Parameters:
posn - The 0-based index of in address to delete.
Returns:
The address removed.
Throws:
ArrayIndexOutOfBoundsException - If posn not in the specified range.

clear

public void clear()
Deletes all addresses from this reference.

equals

public boolean equals(Object obj)
Determines whether obj is a reference with the same addresses (in same order) as this reference. The addresses are checked using RefAddr.equals(). In addition to having the same addresses, the Reference also needs to have the same class name as this reference. The class factory and class factory location are not checked. If obj is null or not an instance of Reference, null is returned.

Overrides:
equals in class Object
Parameters:
obj - The possibly null object to check.
Returns:
true if obj is equal to this reference; false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Computes the hash code of this reference. The hash code is the sum of the hash code of its addresses.

Overrides:
hashCode in class Object
Returns:
A hash code of this reference as an int.
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Generates the string representation of this reference. The string consists of the class name to which this reference refers, and the string representation of each of its addresses. This representation is intended for display only and not to be parsed.

Overrides:
toString in class Object
Returns:
The non-null string representation of this reference.

clone

public Object clone()
Makes a copy of this reference using its class name list of addresses, class factory name and class factory location. Changes to the newly created copy does not affect this Reference and vice versa.

Overrides:
clone in class Object
Returns:
a clone of this instance.
See Also:
Cloneable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Referenceable

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Interface Referenceable

public interface Referenceable

This interface is implemented by an object that can provide a Reference to itself.

A Reference represents a way of recording address information about objects which themselves are not directly bound to the naming system. Such objects can implement the Referenceable interface as a way for programs that use that object to determine what its Reference is. For example, when binding a object, if an object implements the Referenceable interface, getReference() can be invoked on the object to get its Reference to use for binding.

Since:
1.3
See Also:
Context.bind(javax.naming.Name, java.lang.Object), NamingManager.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), Reference

Method Summary
 Reference getReference()
Retrieves the Reference of this object.

Method Detail

getReference

Reference getReference()
                       throws NamingException
Retrieves the Reference of this object.

Returns:
The non-null Reference of this object.
Throws:
NamingException - If a naming exception was encountered while retrieving the reference.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ReferralException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class ReferralException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.ReferralException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
LdapReferralException
public abstract class ReferralException
extends NamingException

This abstract class is used to represent a referral exception, which is generated in response to a referral such as that returned by LDAP v3 servers.

A service provider provides a subclass of ReferralException by providing implementations for getReferralInfo() and getReferralContext() (and appropriate constructors and/or corresponding "set" methods).

The following code sample shows how ReferralException can be used.

        while (true) {
            try {
                bindings = ctx.listBindings(name);
                while (bindings.hasMore()) {
                    b = bindings.next();
                    ...
                }
                break;
            } catch (ReferralException e) {
                ctx = e.getReferralContext();
            }
        }

ReferralException is an abstract class. Concrete implementations determine its synchronization and serialization properties.

An environment parameter passed to the getReferralContext() method is owned by the caller. The service provider will not modify the object or keep a reference to it, but may keep a reference to a clone of it.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
protected | ReferralException() Constructs a new instance of ReferralException.
protected | ReferralException(String explanation) Constructs a new instance of ReferralException using the explanation supplied.
Method Summary
abstract Context | getReferralContext() Retrieves the context at which to continue the method.
abstract Context | getReferralContext(Hashtable<?,?> env) Retrieves the context at which to continue the method using environment properties.
abstract Object | getReferralInfo() Retrieves information (such as URLs) related to this referral.
abstract void | retryReferral() Retries the referral currently being processed.
abstract boolean | skipReferral() Discards the referral about to be processed.
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ReferralException

protected ReferralException(String explanation)
Constructs a new instance of ReferralException using the explanation supplied. All other fields are set to null.

Parameters:
explanation - Additional detail about this exception. Can be null.
See Also:
Throwable.getMessage()

ReferralException

protected ReferralException()
Constructs a new instance of ReferralException. All fields are set to null.

Method Detail

getReferralInfo

public abstract Object getReferralInfo()
Retrieves information (such as URLs) related to this referral. The program may examine or display this information to the user to determine whether to continue with the referral, or to determine additional information needs to be supplied in order to continue with the referral.

Returns:
Non-null referral information related to this referral.

getReferralContext

public abstract Context getReferralContext()
                                    throws NamingException
Retrieves the context at which to continue the method. Regardless of whether a referral is encountered directly during a context operation, or indirectly, for example, during a search enumeration, the referral exception should provide a context at which to continue the operation. The referral context is created using the environment properties of the context that threw the ReferralException.

To continue the operation, the client program should re-invoke the method using the same arguments as the original invocation.

Returns:
The non-null context at which to continue the method.
Throws:
NamingException - If a naming exception was encountered. Call either retryReferral() or skipReferral() to continue processing referrals.

getReferralContext

public abstract Context getReferralContext(Hashtable<?,?> env)
                                    throws NamingException
Retrieves the context at which to continue the method using environment properties. Regardless of whether a referral is encountered directly during a context operation, or indirectly, for example, during a search enumeration, the referral exception should provide a context at which to continue the operation.

The referral context is created using env as its environment properties. This method should be used instead of the no-arg overloaded form when the caller needs to use different environment properties for the referral context. It might need to do this, for example, when it needs to supply different authentication information to the referred server in order to create the referral context.

To continue the operation, the client program should re-invoke the method using the same arguments as the original invocation.

Parameters:
env - The possibly null environment to use when retrieving the referral context. If null, no environment properties will be used.
Returns:
The non-null context at which to continue the method.
Throws:
NamingException - If a naming exception was encountered. Call either retryReferral() or skipReferral() to continue processing referrals.

skipReferral

public abstract boolean skipReferral()
Discards the referral about to be processed. A call to this method should be followed by a call to getReferralContext to allow the processing of other referrals to continue. The following code fragment shows a typical usage pattern.

        } catch (ReferralException e) {
            if (!shallIFollow(e.getReferralInfo())) {
                if (!e.skipReferral()) {
                    return;
                }
            }
            ctx = e.getReferralContext();
        }

Returns:
true If more referral processing is pending; false otherwise.

retryReferral

public abstract void retryReferral()
Retries the referral currently being processed. A call to this method should be followed by a call to getReferralContext to allow the current referral to be retried. The following code fragment shows a typical usage pattern.

        } catch (ReferralException e) {
            while (true) {
                try {
                    ctx = e.getReferralContext(env);
                    break;
                } catch (NamingException ne) {
                    if (! shallIRetry()) {
                        return;
                    }
                    // modify environment properties (env), if necessary
                    e.retryReferral();
                }
            }
        }

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServiceUnavailableException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class ServiceUnavailableException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.ServiceUnavailableException
All Implemented Interfaces:
Serializable
public class ServiceUnavailableException
extends NamingException

This exception is thrown when attempting to communicate with a directory or naming service and that service is not available. It might be unavailable for different reasons. For example, the server might be too busy to service the request, or the server might not be registered to service any requests, etc.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
ServiceUnavailableException()
Constructs a new instance of ServiceUnavailableException.
ServiceUnavailableException(String explanation)
Constructs a new instance of ServiceUnavailableException using an explanation.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ServiceUnavailableException

public ServiceUnavailableException(String explanation)
Constructs a new instance of ServiceUnavailableException using an explanation. All other fields default to null.

Parameters:
explanation - Possibly null additional detail about this exception.
See Also:
Throwable.getMessage()

ServiceUnavailableException

public ServiceUnavailableException()
Constructs a new instance of ServiceUnavailableException. All fields default to null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SizeLimitExceededException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class SizeLimitExceededException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.LimitExceededException
                    extended by  javax.naming.SizeLimitExceededException
All Implemented Interfaces:
Serializable
public class SizeLimitExceededException
extends LimitExceededException

This exception is thrown when a method produces a result that exceeds a size-related limit. This can happen, for example, if the result contains more objects than the user requested, or when the size of the result exceeds some implementation-specific limit.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
SizeLimitExceededException()
Constructs a new instance of SizeLimitExceededException.
SizeLimitExceededException(String explanation)
Constructs a new instance of SizeLimitExceededException using an explanation.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SizeLimitExceededException

public SizeLimitExceededException()
Constructs a new instance of SizeLimitExceededException. All fields default to null.

SizeLimitExceededException

public SizeLimitExceededException(String explanation)
Constructs a new instance of SizeLimitExceededException using an explanation. All other fields default to null.

Parameters:
explanation - Possibly null detail about this exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


spi

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.naming.spi

Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.

See:
Description

Interface Summary
DirObjectFactory | This interface represents a factory for creating an object given an object and attributes about the object.
DirStateFactory | This interface represents a factory for obtaining the state of an object and corresponding attributes for binding.
InitialContextFactory | This interface represents a factory that creates an initial context.
InitialContextFactoryBuilder | This interface represents a builder that creates initial context factories.
ObjectFactory | This interface represents a factory for creating an object.
ObjectFactoryBuilder | This interface represents a builder that creates object factories.
Resolver | This interface represents an "intermediate context" for name resolution.
StateFactory | This interface represents a factory for obtaining the state of an object for binding.

Class Summary
DirectoryManager | This class contains methods for supporting DirContext implementations.
DirStateFactory.Result | An object/attributes pair for returning the result of DirStateFactory.getStateToBind().
NamingManager | This class contains methods for creating context objects and objects referred to by location information in the naming or directory service.
ResolveResult | This class represents the result of resolution of a name.

Package javax.naming.spi Description

Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.

This package defines the service provider interface (SPI) of the Java Naming and Directory InterfaceTM (JNDI). JNDI provides naming and directory functionality to applications written in the Java programming language. It is designed to be independent of any specific naming or directory service implementation. Thus a variety of services--new, emerging, and already deployed ones--can be accessed in a common way.

The JNDI SPI provides the means for creating JNDI service providers, through which JNDI applications access different naming and directory services.

Plug-in Architecture

The service provider package allows different implementations to be plugged in dynamically. These different implementations include those for the initial context, and implementations for contexts that can be reached from the initial context.

Java Object Support

The service provider package provides support for implementors of the javax.naming.Context.lookup() method and related methods to return Java objects that are natural and intuitive for the Java programmer. For example, when looking up a printer name from the directory, it is natural for you to expect to get back a printer object on which to operate.

Multiple Naming Systems (Federation)

JNDI operations allow applications to supply names that span multiple naming systems. So in the process of completing an operation, one service provider might need to interact with another service provider, for example, to pass on the operation to be continued in the next naming system. The service provider package provides support for different providers to cooperate to complete JNDI operations.

Package Specification

The JNDI SPI Specification and related documents can be found in the JNDI documentation.

Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.naming.spi Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.naming.spi

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.naming.spi.DirStateFactory.Result
    • javax.naming.spi.NamingManager
      • javax.naming.spi.DirectoryManager
    • javax.naming.spi.ResolveResult (implements java.io.Serializable)

Interface Hierarchy

  • javax.naming.spi.InitialContextFactory
  • javax.naming.spi.InitialContextFactoryBuilder
  • javax.naming.spi.ObjectFactory
    • javax.naming.spi.DirObjectFactory
  • javax.naming.spi.ObjectFactoryBuilder
  • javax.naming.spi.Resolver
  • javax.naming.spi.StateFactory
    • javax.naming.spi.DirStateFactory
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.naming.spi

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.naming.spi

Packages that use javax.naming.spi
javax.naming.spi Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.

Classes in javax.naming.spi used by javax.naming.spi
DirStateFactory.Result
An object/attributes pair for returning the result of DirStateFactory.getStateToBind().
InitialContextFactory
This interface represents a factory that creates an initial context.
InitialContextFactoryBuilder
This interface represents a builder that creates initial context factories.
NamingManager
This class contains methods for creating context objects and objects referred to by location information in the naming or directory service.
ObjectFactory
This interface represents a factory for creating an object.
ObjectFactoryBuilder
This interface represents a builder that creates object factories.
ResolveResult
This class represents the result of resolution of a name.
StateFactory
This interface represents a factory for obtaining the state of an object for binding.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.spi.DirectoryManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.spi.DirectoryManager

No usage of javax.naming.spi.DirectoryManager

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.spi.DirStateFactory.Result

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.spi.DirStateFactory.Result

Packages that use DirStateFactory.Result
javax.naming.spi Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.

Uses of DirStateFactory.Result in javax.naming.spi

Methods in javax.naming.spi that return DirStateFactory.Result
static DirStateFactory.Result | DirectoryManager.getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes attrs) Retrieves the state of an object for binding when given the original object and its attributes.
DirStateFactory.Result | DirStateFactory.getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes inAttrs) Retrieves the state of an object for binding given the object and attributes to be transformed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.spi.NamingManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.spi.NamingManager

Packages that use NamingManager
javax.naming.spi Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.

Uses of NamingManager in javax.naming.spi

Subclasses of NamingManager in javax.naming.spi
 class DirectoryManager
This class contains methods for supporting DirContext implementations.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.naming.spi.ResolveResult

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.naming.spi.ResolveResult

Packages that use ResolveResult
javax.naming.spi Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.

Uses of ResolveResult in javax.naming.spi

Methods in javax.naming.spi that return ResolveResult
ResolveResult | Resolver.resolveToClass(Name name, Class<? extends Context> contextType) Partially resolves a name.
ResolveResult | Resolver.resolveToClass(String name, Class<? extends Context> contextType) Partially resolves a name.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.spi.DirObjectFactory

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.spi.DirObjectFactory

No usage of javax.naming.spi.DirObjectFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.spi.DirStateFactory

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.spi.DirStateFactory

No usage of javax.naming.spi.DirStateFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.spi.InitialContextFactory

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.spi.InitialContextFactory

Packages that use InitialContextFactory
javax.naming.spi Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.

Uses of InitialContextFactory in javax.naming.spi

Methods in javax.naming.spi that return InitialContextFactory
 InitialContextFactory InitialContextFactoryBuilder.createInitialContextFactory(Hashtable<?,?> environment)
Creates an initial context factory using the specified environment.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.spi.InitialContextFactoryBuilder

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.spi.InitialContextFactoryBuilder

Packages that use InitialContextFactoryBuilder
javax.naming.spi Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.

Uses of InitialContextFactoryBuilder in javax.naming.spi

Methods in javax.naming.spi with parameters of type InitialContextFactoryBuilder
static void NamingManager.setInitialContextFactoryBuilder(InitialContextFactoryBuilder builder)
Sets the InitialContextFactory builder to be builder.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.spi.ObjectFactory

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.spi.ObjectFactory

Packages that use ObjectFactory
javax.naming.spi Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.

Uses of ObjectFactory in javax.naming.spi

Subinterfaces of ObjectFactory in javax.naming.spi
 interface DirObjectFactory
This interface represents a factory for creating an object given an object and attributes about the object.

Methods in javax.naming.spi that return ObjectFactory
 ObjectFactory ObjectFactoryBuilder.createObjectFactory(Object obj, Hashtable<?,?> environment)
Creates a new object factory using the environment supplied.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.spi.ObjectFactoryBuilder

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.spi.ObjectFactoryBuilder

Packages that use ObjectFactoryBuilder
javax.naming.spi Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.

Uses of ObjectFactoryBuilder in javax.naming.spi

Methods in javax.naming.spi with parameters of type ObjectFactoryBuilder
static void NamingManager.setObjectFactoryBuilder(ObjectFactoryBuilder builder)
The ObjectFactoryBuilder determines the policy used when trying to load object factories.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.spi.Resolver

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.spi.Resolver

No usage of javax.naming.spi.Resolver

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.naming.spi.StateFactory

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.naming.spi.StateFactory

Packages that use StateFactory
javax.naming.spi Provides the means for dynamically plugging in support for accessing naming and directory services through the javax.naming and related packages.

Uses of StateFactory in javax.naming.spi

Subinterfaces of StateFactory in javax.naming.spi
 interface DirStateFactory
This interface represents a factory for obtaining the state of an object and corresponding attributes for binding.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DirectoryManager

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.naming.spi
Class DirectoryManager

java.lang.Object
    extended by  javax.naming.spi.NamingManager
        extended by  javax.naming.spi.DirectoryManager

public class DirectoryManager
extends NamingManager

This class contains methods for supporting DirContext implementations.

This class is an extension of NamingManager. It contains methods for use by service providers for accessing object factories and state factories, and for getting continuation contexts for supporting federation.

DirectoryManager is safe for concurrent access by multiple threads.

Except as otherwise noted, a Name, Attributes, or environment parameter passed to any method is owned by the caller. The implementation will not modify the object or keep a reference to it, although it may keep a reference to a clone or copy.

Since:
1.3
See Also:
DirObjectFactory, DirStateFactory

Field Summary
Fields inherited from class javax.naming.spi.NamingManager
CPE
Method Summary
static DirContext | getContinuationDirContext(CannotProceedException cpe) Creates a context in which to continue a DirContext operation.
static Object | getObjectInstance(Object refInfo, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes attrs) Creates an instance of an object for the specified object, attributes, and environment.
static DirStateFactory.Result | getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes attrs) Retrieves the state of an object for binding when given the original object and its attributes.
Methods inherited from class javax.naming.spi.NamingManager
getContinuationContext, getInitialContext, getObjectInstance, getStateToBind, getURLContext, hasInitialContextFactoryBuilder, setInitialContextFactoryBuilder, setObjectFactoryBuilder
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getContinuationDirContext

public static DirContext getContinuationDirContext(CannotProceedException cpe)
                                            throws NamingException
Creates a context in which to continue a DirContext operation. Operates just like NamingManager.getContinuationContext(), only the continuation context returned is a DirContext.

Parameters:
cpe - The non-null exception that triggered this continuation.
Returns:
A non-null DirContext object for continuing the operation.
Throws:
NamingException - If a naming exception occurred.
See Also:
NamingManager.getContinuationContext(CannotProceedException)

getObjectInstance

public static Object getObjectInstance(Object refInfo,
                                       Name name,
                                       Context nameCtx,
                                       Hashtable<?,?> environment,
                                       Attributes attrs)
                                throws Exception
Creates an instance of an object for the specified object, attributes, and environment.

This method is the same as NamingManager.getObjectInstance except for the following differences:

  • It accepts an Attributes parameter that contains attributes associated with the object. The DirObjectFactory might use these attributes to save having to look them up from the directory.
  • The object factories tried must implement either ObjectFactory or DirObjectFactory. If it implements DirObjectFactory, DirObjectFactory.getObjectInstance() is used, otherwise, ObjectFactory.getObjectInstance() is used.
Service providers that implement the DirContext interface should use this method, not NamingManager.getObjectInstance().

Parameters:
refInfo - The possibly null object for which to create an object.
name - The name of this object relative to nameCtx. Specifying a name is optional; if it is omitted, name should be null.
nameCtx - The context relative to which the name parameter is specified. If null, name is relative to the default initial context.
environment - The possibly null environment to be used in the creation of the object factory and the object.
attrs - The possibly null attributes associated with refInfo. This might not be the complete set of attributes for refInfo; you might be able to read more attributes from the directory.
Returns:
An object created using refInfo and attrs; or refInfo if an object cannot be created by a factory.
Throws:
NamingException - If a naming exception was encountered while attempting to get a URL context, or if one of the factories accessed throws a NamingException.
Exception - If one of the factories accessed throws an exception, or if an error was encountered while loading and instantiating the factory and object classes. A factory should only throw an exception if it does not want other factories to be used in an attempt to create an object. See DirObjectFactory.getObjectInstance().
Since:
1.3
See Also:
NamingManager.getURLContext(java.lang.String, java.util.Hashtable), DirObjectFactory, DirObjectFactory.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable, javax.naming.directory.Attributes)

getStateToBind

public static DirStateFactory.Result getStateToBind(Object obj,
                                                    Name name,
                                                    Context nameCtx,
                                                    Hashtable<?,?> environment,
                                                    Attributes attrs)
                                             throws NamingException
Retrieves the state of an object for binding when given the original object and its attributes.

This method is like NamingManager.getStateToBind except for the following differences:

  • It accepts an Attributes parameter containing attributes that were passed to the DirContext.bind() method.
  • It returns a non-null DirStateFactory.Result instance containing the object to be bound, and the attributes to accompany the binding. Either the object or the attributes may be null.
  • The state factories tried must each implement either StateFactory or DirStateFactory. If it implements DirStateFactory, then DirStateFactory.getStateToBind() is called; otherwise, StateFactory.getStateToBind() is called.
Service providers that implement the DirContext interface should use this method, not NamingManager.getStateToBind().

See NamingManager.getStateToBind() for a description of how the list of state factories to be tried is determined.

The object returned by this method is owned by the caller. The implementation will not subsequently modify it. It will contain either a new Attributes object that is likewise owned by the caller, or a reference to the original attrs parameter.

Parameters:
obj - The non-null object for which to get state to bind.
name - The name of this object relative to nameCtx, or null if no name is specified.
nameCtx - The context relative to which the name parameter is specified, or null if name is relative to the default initial context.
environment - The possibly null environment to be used in the creation of the state factory and the object's state.
attrs - The possibly null Attributes that is to be bound with the object.
Returns:
A non-null DirStateFactory.Result containing the object and attributes to be bound. If no state factory returns a non-null answer, the result will contain the object (obj) itself with the original attributes.
Throws:
NamingException - If a naming exception was encountered while using the factories. A factory should only throw an exception if it does not want other factories to be used in an attempt to create an object. See DirStateFactory.getStateToBind().
Since:
1.3
See Also:
DirStateFactory, DirStateFactory.getStateToBind(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable, javax.naming.directory.Attributes), NamingManager.getStateToBind(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


DirObjectFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.spi
Interface DirObjectFactory

All Superinterfaces:
ObjectFactory
public interface DirObjectFactory
extends ObjectFactory

This interface represents a factory for creating an object given an object and attributes about the object.

The JNDI framework allows for object implementations to be loaded in dynamically via object factories. See ObjectFactory for details.

A DirObjectFactory extends ObjectFactory by allowing an Attributes instance to be supplied to the getObjectInstance() method. DirObjectFactory implementations are intended to be used by DirContext service providers. The service provider, in addition reading an object from the directory, might already have attributes that are useful for the object factory to check to see whether the factory is supposed to process the object. For instance, an LDAP-style service provider might have read the "objectclass" of the object. A CORBA object factory might be interested only in LDAP entries with "objectclass=corbaObject". By using the attributes supplied by the LDAP service provider, the CORBA object factory can quickly eliminate objects that it need not worry about, and non-CORBA object factories can quickly eliminate CORBA-related LDAP entries.

Since:
1.3
See Also:
NamingManager.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), DirectoryManager.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable, javax.naming.directory.Attributes), ObjectFactory

Method Summary
 Object getObjectInstance(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes attrs)
Creates an object using the location or reference information, and attributes specified.
Methods inherited from interface javax.naming.spi.ObjectFactory
getObjectInstance

Method Detail

getObjectInstance

Object getObjectInstance(Object obj,
                         Name name,
                         Context nameCtx,
                         Hashtable<?,?> environment,
                         Attributes attrs)
                         throws Exception
Creates an object using the location or reference information, and attributes specified.

Special requirements of this object are supplied using environment. An example of such an environment property is user identity information.

DirectoryManager.getObjectInstance() successively loads in object factories. If it encounters a DirObjectFactory, it will invoke DirObjectFactory.getObjectInstance(); otherwise, it invokes ObjectFactory.getObjectInstance(). It does this until a factory produces a non-null answer.

When an exception is thrown by an object factory, the exception is passed on to the caller of DirectoryManager.getObjectInstance(). The search for other factories that may produce a non-null answer is halted. An object factory should only throw an exception if it is sure that it is the only intended factory and that no other object factories should be tried. If this factory cannot create an object using the arguments supplied, it should return null.

Since DirObjectFactory extends ObjectFactory, it effectively has two getObjectInstance() methods, where one differs from the other by the attributes argument. Given a factory that implements DirObjectFactory, DirectoryManager.getObjectInstance() will only use the method that accepts the attributes argument, while NamingManager.getObjectInstance() will only use the one that does not accept the attributes argument.

See ObjectFactory for a description URL context factories and other properties of object factories that apply equally to DirObjectFactory.

The name, attrs, and environment parameters are owned by the caller. The implementation will not modify these objects or keep references to them, although it may keep references to clones or copies.

Parameters:
obj - The possibly null object containing location or reference information that can be used in creating an object.
name - The name of this object relative to nameCtx, or null if no name is specified.
nameCtx - The context relative to which the name parameter is specified, or null if name is relative to the default initial context.
environment - The possibly null environment that is used in creating the object.
attrs - The possibly null attributes containing some of obj's attributes. attrs might not necessarily have all of obj's attributes. If the object factory requires more attributes, it needs to get it, either using obj, or name and nameCtx. The factory must not modify attrs.
Returns:
The object created; null if an object cannot be created.
Throws:
Exception - If this object factory encountered an exception while attempting to create an object, and no other object factories are to be tried.
See Also:
DirectoryManager.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable, javax.naming.directory.Attributes), NamingManager.getURLContext(java.lang.String, java.util.Hashtable)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DirStateFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.spi
Interface DirStateFactory

All Superinterfaces:
StateFactory
public interface DirStateFactory
extends StateFactory

This interface represents a factory for obtaining the state of an object and corresponding attributes for binding.

The JNDI framework allows for object implementations to be loaded in dynamically via object factories.

A DirStateFactory extends StateFactory by allowing an Attributes instance to be supplied to and be returned by the getStateToBind() method. DirStateFactory implementations are intended to be used by DirContext service providers. When a caller binds an object using DirContext.bind(), he might also specify a set of attributes to be bound with the object. The object and attributes to be bound are passed to the getStateToBind() method of a factory. If the factory processes the object and attributes, it returns a corresponding pair of object and attributes to be bound. If the factory does not process the object, it must return null.

For example, a caller might bind a printer object with some printer-related attributes.

 ctx.rebind("inky", printer, printerAttrs);
An LDAP service provider for ctx uses a DirStateFactory (indirectly via DirectoryManager.getStateToBind()) and gives it printer and printerAttrs. A factory for an LDAP directory might turn printer into a set of attributes and merge that with printerAttrs. The service provider then uses the resulting attributes to create an LDAP entry and updates the directory.

Since DirStateFactory extends StateFactory, it has two getStateToBind() methods, where one differs from the other by the attributes argument. DirectoryManager.getStateToBind() will only use the form that accepts the attributes argument, while NamingManager.getStateToBind() will only use the form that does not accept the attributes argument.

Either form of the getStateToBind() method of a DirStateFactory may be invoked multiple times, possibly using different parameters. The implementation is thread-safe.

Since:
1.3
See Also:
DirectoryManager.getStateToBind(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable, javax.naming.directory.Attributes), DirObjectFactory

Nested Class Summary
static class DirStateFactory.Result
An object/attributes pair for returning the result of DirStateFactory.getStateToBind().
Method Summary
 DirStateFactory.Result getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment, Attributes inAttrs)
Retrieves the state of an object for binding given the object and attributes to be transformed.
Methods inherited from interface javax.naming.spi.StateFactory
getStateToBind

Method Detail

getStateToBind

DirStateFactory.Result getStateToBind(Object obj,
                                      Name name,
                                      Context nameCtx,
                                      Hashtable<?,?> environment,
                                      Attributes inAttrs)
                                      throws NamingException
Retrieves the state of an object for binding given the object and attributes to be transformed.

DirectoryManager.getStateToBind() successively loads in state factories. If a factory implements DirStateFactory, DirectoryManager invokes this method; otherwise, it invokes StateFactory.getStateToBind(). It does this until a factory produces a non-null answer.

When an exception is thrown by a factory, the exception is passed on to the caller of DirectoryManager.getStateToBind(). The search for other factories that may produce a non-null answer is halted. A factory should only throw an exception if it is sure that it is the only intended factory and that no other factories should be tried. If this factory cannot create an object using the arguments supplied, it should return null.

The name and nameCtx parameters may optionally be used to specify the name of the object being created. See the description of "Name and Context Parameters" in ObjectFactory.getObjectInstance() for details. If a factory uses nameCtx it should synchronize its use against concurrent access, since context implementations are not guaranteed to be thread-safe.

The name, inAttrs, and environment parameters are owned by the caller. The implementation will not modify these objects or keep references to them, although it may keep references to clones or copies. The object returned by this method is owned by the caller. The implementation will not subsequently modify it. It will contain either a new Attributes object that is likewise owned by the caller, or a reference to the original inAttrs parameter.

Parameters:
obj - A possibly null object whose state is to be retrieved.
name - The name of this object relative to nameCtx, or null if no name is specified.
nameCtx - The context relative to which the name parameter is specified, or null if name is relative to the default initial context.
environment - The possibly null environment to be used in the creation of the object's state.
inAttrs - The possibly null attributes to be bound with the object. The factory must not modify inAttrs.
Returns:
A Result containing the object's state for binding and the corresponding attributes to be bound; null if the object don't use this factory.
Throws:
NamingException - If this factory encountered an exception while attempting to get the object's state, and no other factories are to be tried.
See Also:
DirectoryManager.getStateToBind(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable, javax.naming.directory.Attributes)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DirStateFactory.Result

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.spi
Class DirStateFactory.Result

java.lang.Object
    extended by  javax.naming.spi.DirStateFactory.Result
Enclosing interface:
DirStateFactory
public static class DirStateFactory.Result
extends Object

An object/attributes pair for returning the result of DirStateFactory.getStateToBind().

Constructor Summary
DirStateFactory.Result(Object obj, Attributes outAttrs)
Constructs an instance of Result.
Method Summary
Attributes | getAttributes() Retrieves the attributes to be bound.
Object | getObject() Retrieves the object to be bound.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DirStateFactory.Result

public DirStateFactory.Result(Object obj,
                              Attributes outAttrs)
Constructs an instance of Result.

Parameters:
obj - The possibly null object to be bound.
outAttrs - The possibly null attributes to be bound.
Method Detail

getObject

public Object getObject()
Retrieves the object to be bound.

Returns:
The possibly null object to be bound.

getAttributes

public Attributes getAttributes()
Retrieves the attributes to be bound.

Returns:
The possibly null attributes to be bound.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InitialContextFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.spi
Interface InitialContextFactory

public interface InitialContextFactory

This interface represents a factory that creates an initial context.

The JNDI framework allows for different initial context implementations to be specified at runtime. The initial context is created using an initial context factory. An initial context factory must implement the InitialContextFactory interface, which provides a method for creating instances of initial context that implement the Context interface. In addition, the factory class must be public and must have a public constructor that accepts no arguments.

Since:
1.3
See Also:
InitialContextFactoryBuilder, NamingManager.getInitialContext(java.util.Hashtable), InitialContext, InitialDirContext

Method Summary
 Context getInitialContext(Hashtable<?,?> environment)
Creates an Initial Context for beginning name resolution.

Method Detail

getInitialContext

Context getInitialContext(Hashtable<?,?> environment)
                          throws NamingException
Creates an Initial Context for beginning name resolution. Special requirements of this context are supplied using environment.

The environment parameter is owned by the caller. The implementation will not modify the object or keep a reference to it, although it may keep a reference to a clone or copy.

Parameters:
environment - The possibly null environment specifying information to be used in the creation of the initial context.
Returns:
A non-null initial context object that implements the Context interface.
Throws:
NamingException - If cannot create an initial context.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InitialContextFactoryBuilder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.spi
Interface InitialContextFactoryBuilder

public interface InitialContextFactoryBuilder

This interface represents a builder that creates initial context factories.

The JNDI framework allows for different initial context implementations to be specified at runtime. An initial context is created using an initial context factory. A program can install its own builder that creates initial context factories, thereby overriding the default policies used by the framework, by calling NamingManager.setInitialContextFactoryBuilder(). The InitialContextFactoryBuilder interface must be implemented by such a builder.

Since:
1.3
See Also:
InitialContextFactory, NamingManager.getInitialContext(java.util.Hashtable), NamingManager.setInitialContextFactoryBuilder(javax.naming.spi.InitialContextFactoryBuilder), NamingManager.hasInitialContextFactoryBuilder(), InitialContext, InitialDirContext

Method Summary
 InitialContextFactory createInitialContextFactory(Hashtable<?,?> environment)
Creates an initial context factory using the specified environment.

Method Detail

createInitialContextFactory

InitialContextFactory createInitialContextFactory(Hashtable<?,?> environment)
                                                  throws NamingException
Creates an initial context factory using the specified environment.

The environment parameter is owned by the caller. The implementation will not modify the object or keep a reference to it, although it may keep a reference to a clone or copy.

Parameters:
environment - Environment used in creating an initial context implementation. Can be null.
Returns:
A non-null initial context factory.
Throws:
NamingException - If an initial context factory could not be created.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamingManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.spi
Class NamingManager

java.lang.Object
    extended by  javax.naming.spi.NamingManager
Direct Known Subclasses:
DirectoryManager
public class NamingManager
extends Object

This class contains methods for creating context objects and objects referred to by location information in the naming or directory service.

This class cannot be instantiated. It has only static methods.

The mention of URL in the documentation for this class refers to a URL string as defined by RFC 1738 and its related RFCs. It is any string that conforms to the syntax described therein, and may not always have corresponding support in the java.net.URL class or Web browsers.

NamingManager is safe for concurrent access by multiple threads.

Except as otherwise noted, a Name or environment parameter passed to any method is owned by the caller. The implementation will not modify the object or keep a reference to it, although it may keep a reference to a clone or copy.

Since:
1.3

Field Summary
static String CPE
Constant that holds the name of the environment property into which getContinuationContext() stores the value of its CannotProceedException parameter.
Method Summary
static Context | getContinuationContext(CannotProceedException cpe) Creates a context in which to continue a context operation.
static Context | getInitialContext(Hashtable<?,?> env) Creates an initial context using the specified environment properties.
static Object | getObjectInstance(Object refInfo, Name name, Context nameCtx, Hashtable<?,?> environment) Creates an instance of an object for the specified object and environment.
static Object | getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment) Retrieves the state of an object for binding.
static Context | getURLContext(String scheme, Hashtable<?,?> environment) Creates a context for the given URL scheme id.
static boolean | hasInitialContextFactoryBuilder() Determines whether an initial context factory builder has been set.
static void | setInitialContextFactoryBuilder(InitialContextFactoryBuilder builder) Sets the InitialContextFactory builder to be builder.
static void | setObjectFactoryBuilder(ObjectFactoryBuilder builder) The ObjectFactoryBuilder determines the policy used when trying to load object factories.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CPE

public static final String CPE
Constant that holds the name of the environment property into which getContinuationContext() stores the value of its CannotProceedException parameter. This property is inherited by the continuation context, and may be used by that context's service provider to inspect the fields of the exception.

The value of this constant is "java.naming.spi.CannotProceedException".

Since:
1.3
See Also:
getContinuationContext(javax.naming.CannotProceedException), Constant Field Values
Method Detail

setObjectFactoryBuilder

public static void setObjectFactoryBuilder(ObjectFactoryBuilder builder)
                                    throws NamingException
The ObjectFactoryBuilder determines the policy used when trying to load object factories. See getObjectInstance() and class ObjectFactory for a description of the default policy. setObjectFactoryBuilder() overrides this default policy by installing an ObjectFactoryBuilder. Subsequent object factories will be loaded and created using the installed builder.

The builder can only be installed if the executing thread is allowed (by the security manager's checkSetFactory() method) to do so. Once installed, the builder cannot be replaced.

Parameters:
builder - The factory builder to install. If null, no builder is installed.
Throws:
SecurityException - builder cannot be installed for security reasons.
NamingException - builder cannot be installed for a non-security-related reason.
IllegalStateException - If a factory has already been installed.
See Also:
getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), ObjectFactory, ObjectFactoryBuilder, SecurityManager.checkSetFactory()

getObjectInstance

public static Object getObjectInstance(Object refInfo,
                                       Name name,
                                       Context nameCtx,
                                       Hashtable<?,?> environment)
                                throws Exception
Creates an instance of an object for the specified object and environment.

If an object factory builder has been installed, it is used to create a factory for creating the object. Otherwise, the following rules are used to create the object:

  1. If refInfo is a Reference or Referenceable containing a factory class name, use the named factory to create the object. Return refInfo if the factory cannot be created. Under JDK 1.1, if the factory class must be loaded from a location specified in the reference, a SecurityManager must have been installed or the factory creation will fail. If an exception is encountered while creating the factory, it is passed up to the caller.
  2. If refInfo is a Reference or Referenceable with no factory class name, and the address or addresses are StringRefAddrs with address type "URL", try the URL context factory corresponding to each URL's scheme id to create the object (see getURLContext()). If that fails, continue to the next step.
  3. Use the object factories specified in the Context.OBJECT_FACTORIES property of the environment, and of the provider resource file associated with nameCtx, in that order. The value of this property is a colon-separated list of factory class names that are tried in order, and the first one that succeeds in creating an object is the one used. If none of the factories can be loaded, return refInfo. If an exception is encountered while creating the object, the exception is passed up to the caller.

Service providers that implement the DirContext interface should use DirectoryManager.getObjectInstance(), not this method. Service providers that implement only the Context interface should use this method.

Note that an object factory (an object that implements the ObjectFactory interface) must be public and must have a public constructor that accepts no arguments.

The name and nameCtx parameters may optionally be used to specify the name of the object being created. name is the name of the object, relative to context nameCtx. This information could be useful to the object factory or to the object implementation. If there are several possible contexts from which the object could be named -- as will often be the case -- it is up to the caller to select one. A good rule of thumb is to select the "deepest" context available. If nameCtx is null, name is relative to the default initial context. If no name is being specified, the name parameter should be null.

Parameters:
refInfo - The possibly null object for which to create an object.
name - The name of this object relative to nameCtx. Specifying a name is optional; if it is omitted, name should be null.
nameCtx - The context relative to which the name parameter is specified. If null, name is relative to the default initial context.
environment - The possibly null environment to be used in the creation of the object factory and the object.
Returns:
An object created using refInfo; or refInfo if an object cannot be created using the algorithm described above.
Throws:
NamingException - if a naming exception was encountered while attempting to get a URL context, or if one of the factories accessed throws a NamingException.
Exception - if one of the factories accessed throws an exception, or if an error was encountered while loading and instantiating the factory and object classes. A factory should only throw an exception if it does not want other factories to be used in an attempt to create an object. See ObjectFactory.getObjectInstance().
See Also:
getURLContext(java.lang.String, java.util.Hashtable), ObjectFactory, ObjectFactory.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable)

getURLContext

public static Context getURLContext(String scheme,
                                    Hashtable<?,?> environment)
                             throws NamingException
Creates a context for the given URL scheme id.

The resulting context is for resolving URLs of the scheme scheme. The resulting context is not tied to a specific URL. It is able to handle arbitrary URLs with the specified scheme.

The class name of the factory that creates the resulting context has the naming convention scheme-idURLContextFactory (e.g. "ftpURLContextFactory" for the "ftp" scheme-id), in the package specified as follows. The Context.URL_PKG_PREFIXES environment property (which may contain values taken from applet parameters, system properties, or application resource files) contains a colon-separated list of package prefixes. Each package prefix in the property is tried in the order specified to load the factory class. The default package prefix is "com.sun.jndi.url" (if none of the specified packages work, this default is tried). The complete package name is constructed using the package prefix, concatenated with the scheme id.

For example, if the scheme id is "ldap", and the Context.URL_PKG_PREFIXES property contains "com.widget:com.wiz.jndi", the naming manager would attempt to load the following classes until one is successfully instantiated:

  • com.widget.ldap.ldapURLContextFactory
  • com.wiz.jndi.ldap.ldapURLContextFactory
  • com.sun.jndi.url.ldap.ldapURLContextFactory
If none of the package prefixes work, null is returned.

If a factory is instantiated, it is invoked with the following parameters to produce the resulting context.

factory.getObjectInstance(null, environment);

For example, invoking getObjectInstance() as shown above on a LDAP URL context factory would return a context that can resolve LDAP urls (e.g. "ldap://ldap.wiz.com/o=wiz,c=us", "ldap://ldap.umich.edu/o=umich,c=us", ...).

Note that an object factory (an object that implements the ObjectFactory interface) must be public and must have a public constructor that accepts no arguments.

Parameters:
scheme - The non-null scheme-id of the URLs supported by the context.
environment - The possibly null environment properties to be used in the creation of the object factory and the context.
Returns:
A context for resolving URLs with the scheme id scheme; null if the factory for creating the context is not found.
Throws:
NamingException - If a naming exception occurs while creating the context.
See Also:
getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), ObjectFactory.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable)

getInitialContext

public static Context getInitialContext(Hashtable<?,?> env)
                                 throws NamingException
Creates an initial context using the specified environment properties.

If an InitialContextFactoryBuilder has been installed, it is used to create the factory for creating the initial context. Otherwise, the class specified in the Context.INITIAL_CONTEXT_FACTORY environment property is used. Note that an initial context factory (an object that implements the InitialContextFactory interface) must be public and must have a public constructor that accepts no arguments.

Parameters:
env - The possibly null environment properties used when creating the context.
Returns:
A non-null initial context.
Throws:
NoInitialContextException - If the Context.INITIAL_CONTEXT_FACTORY property is not found or names a nonexistent class or a class that cannot be instantiated, or if the initial context could not be created for some other reason.
NamingException - If some other naming exception was encountered.
See Also:
InitialContext, InitialDirContext

setInitialContextFactoryBuilder

public static void setInitialContextFactoryBuilder(InitialContextFactoryBuilder builder)
                                            throws NamingException
Sets the InitialContextFactory builder to be builder.

The builder can only be installed if the executing thread is allowed by the security manager to do so. Once installed, the builder cannot be replaced.

Parameters:
builder - The initial context factory builder to install. If null, no builder is set.
Throws:
SecurityException - builder cannot be installed for security reasons.
NamingException - builder cannot be installed for a non-security-related reason.
IllegalStateException - If a builder was previous installed.
See Also:
hasInitialContextFactoryBuilder(), SecurityManager.checkSetFactory()

hasInitialContextFactoryBuilder

public static boolean hasInitialContextFactoryBuilder()
Determines whether an initial context factory builder has been set.

Returns:
true if an initial context factory builder has been set; false otherwise.
See Also:
setInitialContextFactoryBuilder(javax.naming.spi.InitialContextFactoryBuilder)

getContinuationContext

public static Context getContinuationContext(CannotProceedException cpe)
                                      throws NamingException
Creates a context in which to continue a context operation.

In performing an operation on a name that spans multiple namespaces, a context from one naming system may need to pass the operation on to the next naming system. The context implementation does this by first constructing a CannotProceedException containing information pinpointing how far it has proceeded. It then obtains a continuation context from JNDI by calling getContinuationContext. The context implementation should then resume the context operation by invoking the same operation on the continuation context, using the remainder of the name that has not yet been resolved.

Before making use of the cpe parameter, this method updates the environment associated with that object by setting the value of the property CPE to cpe. This property will be inherited by the continuation context, and may be used by that context's service provider to inspect the fields of this exception.

Parameters:
cpe - The non-null exception that triggered this continuation.
Returns:
A non-null Context object for continuing the operation.
Throws:
NamingException - If a naming exception occurred.

getStateToBind

public static Object getStateToBind(Object obj,
                                    Name name,
                                    Context nameCtx,
                                    Hashtable<?,?> environment)
                             throws NamingException
Retrieves the state of an object for binding.

Service providers that implement the DirContext interface should use DirectoryManager.getStateToBind(), not this method. Service providers that implement only the Context interface should use this method.

This method uses the specified state factories in the Context.STATE_FACTORIES property from the environment properties, and from the provider resource file associated with nameCtx, in that order. The value of this property is a colon-separated list of factory class names that are tried in order, and the first one that succeeds in returning the object's state is the one used. If no object's state can be retrieved in this way, return the object itself. If an exception is encountered while retrieving the state, the exception is passed up to the caller.

Note that a state factory (an object that implements the StateFactory interface) must be public and must have a public constructor that accepts no arguments.

The name and nameCtx parameters may optionally be used to specify the name of the object being created. See the description of "Name and Context Parameters" in ObjectFactory.getObjectInstance() for details.

This method may return a Referenceable object. The service provider obtaining this object may choose to store it directly, or to extract its reference (using Referenceable.getReference()) and store that instead.

Parameters:
obj - The non-null object for which to get state to bind.
name - The name of this object relative to nameCtx, or null if no name is specified.
nameCtx - The context relative to which the name parameter is specified, or null if name is relative to the default initial context.
environment - The possibly null environment to be used in the creation of the state factory and the object's state.
Returns:
The non-null object representing obj's state for binding. It could be the object (obj) itself.
Throws:
NamingException - If one of the factories accessed throws an exception, or if an error was encountered while loading and instantiating the factory and object classes. A factory should only throw an exception if it does not want other factories to be used in an attempt to create an object. See StateFactory.getStateToBind().
Since:
1.3
See Also:
StateFactory, StateFactory.getStateToBind(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), DirectoryManager.getStateToBind(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable, javax.naming.directory.Attributes)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.spi
Interface ObjectFactory

All Known Subinterfaces:
DirObjectFactory
public interface ObjectFactory

This interface represents a factory for creating an object.

The JNDI framework allows for object implementations to be loaded in dynamically via object factories. For example, when looking up a printer bound in the name space, if the print service binds printer names to References, the printer Reference could be used to create a printer object, so that the caller of lookup can directly operate on the printer object after the lookup.

An ObjectFactory is responsible for creating objects of a specific type. In the above example, you may have a PrinterObjectFactory for creating Printer objects.

An object factory must implement the ObjectFactory interface. In addition, the factory class must be public and must have a public constructor that accepts no parameters.

The getObjectInstance() method of an object factory may be invoked multiple times, possibly using different parameters. The implementation is thread-safe.

The mention of URL in the documentation for this class refers to a URL string as defined by RFC 1738 and its related RFCs. It is any string that conforms to the syntax described therein, and may not always have corresponding support in the java.net.URL class or Web browsers.

Since:
1.3
See Also:
NamingManager.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), NamingManager.getURLContext(java.lang.String, java.util.Hashtable), ObjectFactoryBuilder, StateFactory

Method Summary
 Object getObjectInstance(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment)
Creates an object using the location or reference information specified.

Method Detail

getObjectInstance

Object getObjectInstance(Object obj,
                         Name name,
                         Context nameCtx,
                         Hashtable<?,?> environment)
                         throws Exception
Creates an object using the location or reference information specified.

Special requirements of this object are supplied using environment. An example of such an environment property is user identity information.

NamingManager.getObjectInstance() successively loads in object factories and invokes this method on them until one produces a non-null answer. When an exception is thrown by an object factory, the exception is passed on to the caller of NamingManager.getObjectInstance() (and no search is made for other factories that may produce a non-null answer). An object factory should only throw an exception if it is sure that it is the only intended factory and that no other object factories should be tried. If this factory cannot create an object using the arguments supplied, it should return null.

A URL context factory is a special ObjectFactory that creates contexts for resolving URLs or objects whose locations are specified by URLs. The getObjectInstance() method of a URL context factory will obey the following rules.

  1. If obj is null, create a context for resolving URLs of the scheme associated with this factory. The resulting context is not tied to a specific URL: it is able to handle arbitrary URLs with this factory's scheme id. For example, invoking getObjectInstance() with obj set to null on an LDAP URL context factory would return a context that can resolve LDAP URLs such as "ldap://ldap.wiz.com/o=wiz,c=us" and "ldap://ldap.umich.edu/o=umich,c=us".
  2. If obj is a URL string, create an object (typically a context) identified by the URL. For example, suppose this is an LDAP URL context factory. If obj is "ldap://ldap.wiz.com/o=wiz,c=us", getObjectInstance() would return the context named by the distinguished name "o=wiz, c=us" at the LDAP server ldap.wiz.com. This context can then be used to resolve LDAP names (such as "cn=George") relative to that context.
  3. If obj is an array of URL strings, the assumption is that the URLs are equivalent in terms of the context to which they refer. Verification of whether the URLs are, or need to be, equivalent is up to the context factory. The order of the URLs in the array is not significant. The object returned by getObjectInstance() is like that of the single URL case. It is the object named by the URLs.
  4. If obj is of any other type, the behavior of getObjectInstance() is determined by the context factory implementation.

The name and environment parameters are owned by the caller. The implementation will not modify these objects or keep references to them, although it may keep references to clones or copies.

Name and Context Parameters. The name and nameCtx parameters may optionally be used to specify the name of the object being created. name is the name of the object, relative to context nameCtx. If there are several possible contexts from which the object could be named -- as will often be the case -- it is up to the caller to select one. A good rule of thumb is to select the "deepest" context available. If nameCtx is null, name is relative to the default initial context. If no name is being specified, the name parameter should be null. If a factory uses nameCtx it should synchronize its use against concurrent access, since context implementations are not guaranteed to be thread-safe.

Parameters:
obj - The possibly null object containing location or reference information that can be used in creating an object.
name - The name of this object relative to nameCtx, or null if no name is specified.
nameCtx - The context relative to which the name parameter is specified, or null if name is relative to the default initial context.
environment - The possibly null environment that is used in creating the object.
Returns:
The object created; null if an object cannot be created.
Throws:
Exception - if this object factory encountered an exception while attempting to create an object, and no other object factories are to be tried.
See Also:
NamingManager.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), NamingManager.getURLContext(java.lang.String, java.util.Hashtable)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectFactoryBuilder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.spi
Interface ObjectFactoryBuilder

public interface ObjectFactoryBuilder

This interface represents a builder that creates object factories.

The JNDI framework allows for object implementations to be loaded in dynamically via object factories. For example, when looking up a printer bound in the name space, if the print service binds printer names to References, the printer Reference could be used to create a printer object, so that the caller of lookup can directly operate on the printer object after the lookup. An ObjectFactory is responsible for creating objects of a specific type. JNDI uses a default policy for using and loading object factories. You can override this default policy by calling NamingManager.setObjectFactoryBuilder() with an ObjectFactoryBuilder, which contains the program-defined way of creating/loading object factories. Any ObjectFactoryBuilder implementation must implement this interface that for creating object factories.

Since:
1.3
See Also:
ObjectFactory, NamingManager.getObjectInstance(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), NamingManager.setObjectFactoryBuilder(javax.naming.spi.ObjectFactoryBuilder)

Method Summary
 ObjectFactory createObjectFactory(Object obj, Hashtable<?,?> environment)
Creates a new object factory using the environment supplied.

Method Detail

createObjectFactory

ObjectFactory createObjectFactory(Object obj,
                                  Hashtable<?,?> environment)
                                  throws NamingException
Creates a new object factory using the environment supplied.

The environment parameter is owned by the caller. The implementation will not modify the object or keep a reference to it, although it may keep a reference to a clone or copy.

Parameters:
obj - The possibly null object for which to create a factory.
environment - Environment to use when creating the factory. Can be null.
Returns:
A non-null new instance of an ObjectFactory.
Throws:
NamingException - If an object factory cannot be created.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Resolver

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.spi
Interface Resolver

public interface Resolver

This interface represents an "intermediate context" for name resolution.

The Resolver interface contains methods that are implemented by contexts that do not support subtypes of Context, but which can act as intermediate contexts for resolution purposes.

A Name parameter passed to any method is owned by the caller. The service provider will not modify the object or keep a reference to it. A ResolveResult object returned by any method is owned by the caller. The caller may subsequently modify it; the service provider may not.

Since:
1.3

Method Summary
ResolveResult | resolveToClass(Name name, Class<? extends Context> contextType) Partially resolves a name.
ResolveResult | resolveToClass(String name, Class<? extends Context> contextType) Partially resolves a name.

Method Detail

resolveToClass

ResolveResult resolveToClass(Name name,
                             Class<? extends Context> contextType)
                             throws NamingException
Partially resolves a name. Stops at the first context that is an instance of a given subtype of Context.

Parameters:
name - the name to resolve
contextType - the type of object to resolve. This should be a subtype of Context.
Returns:
the object that was found, along with the unresolved suffix of name. Cannot be null.
Throws:
NotContextException - if no context of the appropriate type is found
NamingException - if a naming exception was encountered
See Also:
resolveToClass(String, Class)

resolveToClass

ResolveResult resolveToClass(String name,
                             Class<? extends Context> contextType)
                             throws NamingException
Partially resolves a name. See resolveToClass(Name, Class) for details.

Parameters:
name - the name to resolve
contextType - the type of object to resolve. This should be a subtype of Context.
Returns:
the object that was found, along with the unresolved suffix of name. Cannot be null.
Throws:
NotContextException - if no context of the appropriate type is found
NamingException - if a naming exception was encountered
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ResolveResult

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming.spi
Class ResolveResult

java.lang.Object
    extended by  javax.naming.spi.ResolveResult
All Implemented Interfaces:
Serializable
public class ResolveResult
extends Object
implements Serializable

This class represents the result of resolution of a name. It contains the object to which name was resolved, and the portion of the name that has not been resolved.

A ResolveResult instance is not synchronized against concurrent multithreaded access. Multiple threads trying to access and modify a single ResolveResult instance should lock the object.

Since:
1.3
See Also:
Serialized Form

Field Summary
protected Name | remainingName Field containing the remaining name yet to be resolved.
protected Object | resolvedObj Field containing the Object that was resolved to successfully.
Constructor Summary
protected | ResolveResult() Constructs an instance of ResolveResult with the resolved object and remaining name both initialized to null.
 | ResolveResult(Object robj, Name rname) Constructs a new instance of ResolveResult consisting of the resolved Object and the remaining name.
 | ResolveResult(Object robj, String rcomp) Constructs a new instance of ResolveResult consisting of the resolved object and the remaining unresolved component.
Method Summary
void | appendRemainingComponent(String name) Adds a single component to the end of remaining name.
void | appendRemainingName(Name name) Adds components to the end of remaining name.
Name | getRemainingName() Retrieves the remaining unresolved portion of the name.
Object | getResolvedObj() Retrieves the Object to which resolution was successful.
void | setRemainingName(Name name) Sets the remaining name field of this result to name.
void | setResolvedObj(Object obj) Sets the resolved Object field of this result to obj.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

resolvedObj

protected Object resolvedObj
Field containing the Object that was resolved to successfully. It can be null only when constructed using a subclass. Constructors should always initialize this.

remainingName

protected Name remainingName
Field containing the remaining name yet to be resolved. It can be null only when constructed using a subclass. Constructors should always initialize this.

Constructor Detail

ResolveResult

protected ResolveResult()
Constructs an instance of ResolveResult with the resolved object and remaining name both initialized to null.

ResolveResult

public ResolveResult(Object robj,
                     String rcomp)
Constructs a new instance of ResolveResult consisting of the resolved object and the remaining unresolved component.

Parameters:
robj - The non-null object resolved to.
rcomp - The single remaining name component that has yet to be resolved. Cannot be null (but can be empty).

ResolveResult

public ResolveResult(Object robj,
                     Name rname)
Constructs a new instance of ResolveResult consisting of the resolved Object and the remaining name.

Parameters:
robj - The non-null Object resolved to.
rname - The non-null remaining name that has yet to be resolved.
Method Detail

getRemainingName

public Name getRemainingName()
Retrieves the remaining unresolved portion of the name.

Returns:
The remaining unresolved portion of the name. Cannot be null but empty OK.
See Also:
appendRemainingName(javax.naming.Name),
appendRemainingComponent(java.lang.String),
setRemainingName(javax.naming.Name)

getResolvedObj

public Object getResolvedObj()
Retrieves the Object to which resolution was successful.

Returns:
The Object to which resolution was successful. Cannot be null.
See Also:
setResolvedObj(java.lang.Object)

setRemainingName

public void setRemainingName(Name name)
Sets the remaining name field of this result to name. A copy of name is made so that modifying the copy within this ResolveResult does not affect name and vice versa.

Parameters:
name - The name to set remaining name to. Cannot be null.
See Also:
getRemainingName(),
appendRemainingName(javax.naming.Name),
appendRemainingComponent(java.lang.String)

appendRemainingName

public void appendRemainingName(Name name)
Adds components to the end of remaining name.

Parameters:
name - The components to add. Can be null.
See Also:
getRemainingName(),
setRemainingName(javax.naming.Name),
appendRemainingComponent(java.lang.String)

appendRemainingComponent

public void appendRemainingComponent(String name)
Adds a single component to the end of remaining name.

Parameters:
name - The component to add. Can be null.
See Also:
getRemainingName(), appendRemainingName(javax.naming.Name)

setResolvedObj

public void setResolvedObj(Object obj)
Sets the resolved Object field of this result to obj.

Parameters:
obj - The object to use for setting the resolved obj field. Cannot be null.
See Also:
getResolvedObj()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StateFactory

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.naming.spi
Interface StateFactory

All Known Subinterfaces:
DirStateFactory
public interface StateFactory

This interface represents a factory for obtaining the state of an object for binding.

The JNDI framework allows for object implementations to be loaded in dynamically via object factories. For example, when looking up a printer bound in the name space, if the print service binds printer names to References, the printer Reference could be used to create a printer object, so that the caller of lookup can directly operate on the printer object after the lookup.

An ObjectFactory is responsible for creating objects of a specific type. In the above example, you may have a PrinterObjectFactory for creating Printer objects.

For the reverse process, when an object is bound into the namespace, JNDI provides state factories. Continuing with the printer example, suppose the printer object is updated and rebound:

 ctx.rebind("inky", printer);
The service provider for ctx uses a state factory to obtain the state of printer for binding into its namespace. A state factory for the Printer type object might return a more compact object for storage in the naming system.

A state factory must implement the StateFactory interface. In addition, the factory class must be public and must have a public constructor that accepts no parameters.

The getStateToBind() method of a state factory may be invoked multiple times, possibly using different parameters. The implementation is thread-safe.

StateFactory is intended for use with service providers that implement only the Context interface. DirStateFactory is intended for use with service providers that implement the DirContext interface.

Since:
1.3
See Also:
NamingManager.getStateToBind(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), DirectoryManager.getStateToBind(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable, javax.naming.directory.Attributes), ObjectFactory, DirStateFactory

Method Summary
 Object getStateToBind(Object obj, Name name, Context nameCtx, Hashtable<?,?> environment)
Retrieves the state of an object for binding.

Method Detail

getStateToBind

Object getStateToBind(Object obj,
                      Name name,
                      Context nameCtx,
                      Hashtable<?,?> environment)
                      throws NamingException
Retrieves the state of an object for binding.

NamingManager.getStateToBind() successively loads in state factories and invokes this method on them until one produces a non-null answer. DirectoryManager.getStateToBind() successively loads in state factories. If a factory implements DirStateFactory, then DirectoryManager invokes DirStateFactory.getStateToBind(); otherwise it invokes StateFactory.getStateToBind().

When an exception is thrown by a factory, the exception is passed on to the caller of NamingManager.getStateToBind() and DirectoryManager.getStateToBind(). The search for other factories that may produce a non-null answer is halted. A factory should only throw an exception if it is sure that it is the only intended factory and that no other factories should be tried. If this factory cannot create an object using the arguments supplied, it should return null.

The name and nameCtx parameters may optionally be used to specify the name of the object being created. See the description of "Name and Context Parameters" in ObjectFactory.getObjectInstance() for details. If a factory uses nameCtx it should synchronize its use against concurrent access, since context implementations are not guaranteed to be thread-safe.

The name and environment parameters are owned by the caller. The implementation will not modify these objects or keep references to them, although it may keep references to clones or copies.

Parameters:
obj - A non-null object whose state is to be retrieved.
name - The name of this object relative to nameCtx, or null if no name is specified.
nameCtx - The context relative to which the name parameter is specified, or null if name is relative to the default initial context.
environment - The possibly null environment to be used in the creation of the object's state.
Returns:
The object's state for binding; null if the factory is not returning any changes.
Throws:
NamingException - if this factory encountered an exception while attempting to get the object's state, and no other factories are to be tried.
See Also:
NamingManager.getStateToBind(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable), DirectoryManager.getStateToBind(java.lang.Object, javax.naming.Name, javax.naming.Context, java.util.Hashtable, javax.naming.directory.Attributes)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


StringRefAddr

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class StringRefAddr

java.lang.Object
    extended by  javax.naming.RefAddr
        extended by  javax.naming.StringRefAddr
All Implemented Interfaces:
Serializable
public class StringRefAddr
extends RefAddr

This class represents the string form of the address of a communications end-point. It consists of a type that describes the communication mechanism and a string contents specific to that communication mechanism. The format and interpretation of the address type and the contents of the address are based on the agreement of three parties: the client that uses the address, the object/server that can be reached using the address, and the administrator or program that creates the address.

An example of a string reference address is a host name. Another example of a string reference address is a URL.

A string reference address is immutable: once created, it cannot be changed. Multithreaded access to a single StringRefAddr need not be synchronized.

Since:
1.3
See Also:
RefAddr, BinaryRefAddr, Serialized Form

Field Summary
Fields inherited from class javax.naming.RefAddr
addrType
Constructor Summary
StringRefAddr(String addrType, String addr)
Constructs a new instance of StringRefAddr using its address type and contents.
Method Summary
 Object getContent()
Retrieves the contents of this address.
Methods inherited from class javax.naming.RefAddr
equals, getType, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

StringRefAddr

public StringRefAddr(String addrType,
                     String addr)
Constructs a new instance of StringRefAddr using its address type and contents.

Parameters:
addrType - A non-null string describing the type of the address.
addr - The possibly null contents of the address in the form of a string.
Method Detail

getContent

public Object getContent()
Retrieves the contents of this address. The result is a string.

Specified by:
getContent in class RefAddr
Returns:
The possibly null address contents.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TimeLimitExceededException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.naming
Class TimeLimitExceededException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.naming.NamingException
                extended by  javax.naming.LimitExceededException
                    extended by  javax.naming.TimeLimitExceededException
All Implemented Interfaces:
Serializable
public class TimeLimitExceededException
extends LimitExceededException

This exception is thrown when a method does not terminate within the specified time limit. This can happen, for example, if the user specifies that the method should take no longer than 10 seconds, and the method fails to complete with 10 seconds.

Synchronization and serialization issues that apply to NamingException apply directly here.

Since:
1.3
See Also:
Serialized Form

Field Summary
Fields inherited from class javax.naming.NamingException
remainingName, resolvedName, resolvedObj, rootException
Constructor Summary
TimeLimitExceededException()
Constructs a new instance of TimeLimitExceededException.
TimeLimitExceededException(String explanation)
Constructs a new instance of TimeLimitExceededException using the argument supplied.
Method Summary
Methods inherited from class javax.naming.NamingException
appendRemainingComponent, appendRemainingName, getCause, getExplanation, getRemainingName, getResolvedName, getResolvedObj, getRootCause, initCause, setRemainingName, setResolvedName, setResolvedObj, setRootCause, toString, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TimeLimitExceededException

public TimeLimitExceededException()
Constructs a new instance of TimeLimitExceededException. All fields default to null.

TimeLimitExceededException

public TimeLimitExceededException(String explanation)
Constructs a new instance of TimeLimitExceededException using the argument supplied.

Parameters:
explanation - possibly null detail about this exception.
See Also:
Throwable.getMessage()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


net

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.net

Provides classes for networking applications.

See:
Description

Class Summary
ServerSocketFactory | This class creates server sockets.
SocketFactory | This class creates sockets.

Package javax.net Description

Provides classes for networking applications. These classes include factories for creating sockets. Using socket factories you can encapsulate socket creation and configuration behavior.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.net Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.net

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.net.ServerSocketFactory
    • javax.net.SocketFactory
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.net

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.net

Packages that use javax.net
javax.net | Provides classes for networking applications.
javax.net.ssl | Provides classes for the secure socket package.

Classes in javax.net used by javax.net
ServerSocketFactory
This class creates server sockets.
SocketFactory
This class creates sockets.

Classes in javax.net used by javax.net.ssl
ServerSocketFactory
This class creates server sockets.
SocketFactory
This class creates sockets.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ServerSocketFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ServerSocketFactory

Packages that use ServerSocketFactory
javax.net | Provides classes for networking applications.
javax.net.ssl | Provides classes for the secure socket package.

Uses of ServerSocketFactory in javax.net

Methods in javax.net that return ServerSocketFactory
static ServerSocketFactory ServerSocketFactory.getDefault()
Returns a copy of the environment's default socket factory.

Uses of ServerSocketFactory in javax.net.ssl

Subclasses of ServerSocketFactory in javax.net.ssl
 class SSLServerSocketFactory
SSLServerSocketFactorys create SSLServerSockets.

Methods in javax.net.ssl that return ServerSocketFactory
static ServerSocketFactory SSLServerSocketFactory.getDefault()
Returns the default SSL server socket factory.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.SocketFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.SocketFactory

Packages that use SocketFactory
javax.net | Provides classes for networking applications.
javax.net.ssl | Provides classes for the secure socket package.

Uses of SocketFactory in javax.net

Methods in javax.net that return SocketFactory
static SocketFactory SocketFactory.getDefault()
Returns a copy of the environment's default socket factory.

Uses of SocketFactory in javax.net.ssl

Subclasses of SocketFactory in javax.net.ssl
 class SSLSocketFactory
SSLSocketFactorys create SSLSockets.

Methods in javax.net.ssl that return SocketFactory
static SocketFactory SSLSocketFactory.getDefault()
Returns the default SSL socket factory.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ServerSocketFactory

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.net
Class ServerSocketFactory

java.lang.Object
    extended by  javax.net.ServerSocketFactory
Direct Known Subclasses:
SSLServerSocketFactory
public abstract class ServerSocketFactory
extends Object

This class creates server sockets. It may be subclassed by other factories, which create particular types of server sockets. This provides a general framework for the addition of public socket-level functionality. It is the server side analogue of a socket factory, and similarly provides a way to capture a variety of policies related to the sockets being constructed.

Like socket factories, server Socket factory instances have methods used to create sockets. There is also an environment specific default server socket factory; frameworks will often use their own customized factory.

Since:
1.4
See Also:
SocketFactory

Constructor Summary
protected ServerSocketFactory()
Creates a server socket factory.
Method Summary
ServerSocket | createServerSocket() Returns an unbound server socket.
abstract ServerSocket | createServerSocket(int port) Returns a server socket bound to the specified port.
abstract ServerSocket | createServerSocket(int port, int backlog) Returns a server socket bound to the specified port, and uses the specified connection backlog.
abstract ServerSocket | createServerSocket(int port, int backlog, InetAddress ifAddress) Returns a server socket bound to the specified port, with a specified listen backlog and local IP.
static ServerSocketFactory | getDefault() Returns a copy of the environment's default socket factory.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServerSocketFactory

protected ServerSocketFactory()
Creates a server socket factory.

Method Detail

getDefault

public static ServerSocketFactory getDefault()
Returns a copy of the environment's default socket factory.

Returns:
the ServerSocketFactory

createServerSocket

public ServerSocket createServerSocket()
                                throws IOException
Returns an unbound server socket. The socket is configured with the socket options (such as accept timeout) given to this factory.

Returns:
the unbound socket
Throws:
IOException - if the socket cannot be created
See Also:
ServerSocket.bind(java.net.SocketAddress),
ServerSocket.bind(java.net.SocketAddress, int),
ServerSocket.ServerSocket()

createServerSocket

public abstract ServerSocket createServerSocket(int port)
                                         throws IOException
Returns a server socket bound to the specified port. The socket is configured with the socket options (such as accept timeout) given to this factory.

Parameters:
port - the port to listen to
Returns:
the ServerSocket
Throws:
IOException - for networking errors
See Also:
ServerSocket.ServerSocket(int)

createServerSocket

public abstract ServerSocket createServerSocket(int port,
                                                int backlog)
                                         throws IOException
Returns a server socket bound to the specified port, and uses the specified connection backlog. The socket is configured with the socket options (such as accept timeout) given to this factory.

Parameters:
port - the port to listen to
backlog - how many connections are queued
Returns:
the ServerSocket
Throws:
IOException - for networking errors
See Also:
ServerSocket.ServerSocket(int, int)

createServerSocket

public abstract ServerSocket createServerSocket(int port,
                                                int backlog,
                                                InetAddress ifAddress)
                                         throws IOException
Returns a server socket bound to the specified port, with a specified listen backlog and local IP. The ifAddress argument can be used on a multi-homed host for a ServerSocket that will only accept connect requests to one of its addresses. If ifAddress is null, it will accept connections on all local addresses. The socket is configured with the socket options (such as accept timeout) given to this factory.

Parameters:
port - the port to listen to
backlog - how many connections are queued
ifAddress - the network interface address to use
Returns:
the ServerSocket
Throws:
IOException - for networking errors
See Also:
ServerSocket.ServerSocket(int, int, java.net.InetAddress)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


SocketFactory

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.net
Class SocketFactory

java.lang.Object
    extended by  javax.net.SocketFactory
Direct Known Subclasses:
SSLSocketFactory
public abstract class SocketFactory
extends Object

This class creates sockets. It may be subclassed by other factories, which create particular subclasses of sockets and thus provide a general framework for the addition of public socket-level functionality.

Socket factories are a simple way to capture a variety of policies related to the sockets being constructed, producing such sockets in a way which does not require special configuration of the code which asks for the sockets:

  • Due to polymorphism of both factories and sockets, different kinds of sockets can be used by the same application code just by passing it different kinds of factories.
  • Factories can themselves be customized with parameters used in socket construction. So for example, factories could be customized to return sockets with different networking timeouts or security parameters already configured.
  • The sockets returned to the application can be subclasses of java.net.Socket, so that they can directly expose new APIs for features such as compression, security, record marking, statistics collection, or firewall tunneling.

Factory classes are specified by environment-specific configuration mechanisms. For example, the getDefault method could return a factory that was appropriate for a particular user or applet, and a framework could use a factory customized to its own purposes.

Since:
1.4
See Also:
ServerSocketFactory

Constructor Summary
protected SocketFactory()
Creates a SocketFactory.
Method Summary
Socket | createSocket() Creates an unconnected socket.
abstract Socket | createSocket(InetAddress host, int port) Creates a socket and connects it to the specified port number at the specified address.
abstract Socket | createSocket(InetAddress address, int port, InetAddress localAddress, int localPort) Creates a socket and connect it to the specified remote address on the specified remote port.
abstract Socket | createSocket(String host, int port) Creates a socket and connects it to the specified remote host at the specified remote port.
abstract Socket | createSocket(String host, int port, InetAddress localHost, int localPort) Creates a socket and connects it to the specified remote host on the specified remote port.
static SocketFactory | getDefault() Returns a copy of the environment's default socket factory.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SocketFactory

protected SocketFactory()
Creates a SocketFactory.

Method Detail

getDefault

public static SocketFactory getDefault()
Returns a copy of the environment's default socket factory.

Returns:
the default SocketFactory

createSocket

public Socket createSocket()
                    throws IOException
Creates an unconnected socket.

Returns:
the unconnected socket
Throws:
IOException - if the socket cannot be created
See Also:
Socket.connect(java.net.SocketAddress),
Socket.connect(java.net.SocketAddress, int),
Socket.Socket()

createSocket

public abstract Socket createSocket(String host,
                                    int port)
                             throws IOException,
                                    UnknownHostException
Creates a socket and connects it to the specified remote host at the specified remote port. This socket is configured using the socket options established for this factory.

Parameters:
host - the server host
port - the server port
Returns:
the Socket
Throws:
IOException - if an I/O error occurs when creating the socket
UnknownHostException - if the host is not known
See Also:
Socket.Socket(String, int)

createSocket

public abstract Socket createSocket(String host,
                                    int port,
                                    InetAddress localHost,
                                    int localPort)
                             throws IOException,
                                    UnknownHostException
Creates a socket and connects it to the specified remote host on the specified remote port. The socket will also be bound to the local address and port supplied. This socket is configured using the socket options established for this factory.

Parameters:
host - the server host
port - the server port
localHost - the local address the socket is bound to
localPort - the local port the socket is bound to
Returns:
the Socket
Throws:
IOException - if an I/O error occurs when creating the socket
UnknownHostException - if the host is not known
See Also:
Socket.Socket(String, int, java.net.InetAddress, int)

createSocket

public abstract Socket createSocket(InetAddress host,
                                    int port)
                             throws IOException
Creates a socket and connects it to the specified port number at the specified address. This socket is configured using the socket options established for this factory.

Parameters:
host - the server host
port - the server port
Returns:
the Socket
Throws:
IOException - if an I/O error occurs when creating the socket
See Also:
Socket.Socket(java.net.InetAddress, int)

createSocket

public abstract Socket createSocket(InetAddress address,
                                    int port,
                                    InetAddress localAddress,
                                    int localPort)
                             throws IOException
Creates a socket and connect it to the specified remote address on the specified remote port. The socket will also be bound to the local address and port suplied. The socket is configured using the socket options established for this factory.

Parameters:
address - the server network address
port - the server port
localAddress - the client network address
localPort - the client port
Returns:
the Socket
Throws:
IOException - if an I/O error occurs when creating the socket
See Also:
Socket.Socket(java.net.InetAddress, int, java.net.InetAddress, int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


ssl

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.net.ssl

Provides classes for the secure socket package.

See:
Description

Interface Summary
HandshakeCompletedListener | This interface is implemented by any class which wants to receive notifications about the completion of an SSL protocol handshake on a given SSL connection.
HostnameVerifier | This class is the base interface for hostname verification.
KeyManager | This is the base interface for JSSE key managers.
ManagerFactoryParameters | This class is the base interface for providing algorithm-specific information to a KeyManagerFactory or TrustManagerFactory.
SSLSession | In SSL, sessions are used to describe an ongoing relationship between two entities.
SSLSessionBindingListener | This interface is implemented by objects which want to know when they are being bound or unbound from a SSLSession.
SSLSessionContext | A SSLSessionContext represents a set of SSLSessions associated with a single entity.
TrustManager | This is the base interface for JSSE trust managers.
X509KeyManager | Instances of this interface manage which X509 certificate-based key pairs are used to authenticate the local side of a secure socket.
X509TrustManager | Instance of this interface manage which X509 certificates may be used to authenticate the remote side of a secure socket.

Class Summary
CertPathTrustManagerParameters | A wrapper for CertPathParameters.
HandshakeCompletedEvent | This event indicates that an SSL handshake completed on a given SSL connection.
HttpsURLConnection | HttpsURLConnection extends HttpURLConnection with support for https-specific features.
KeyManagerFactory | This class acts as a factory for key managers based on a source of key material.
KeyManagerFactorySpi | This class defines the Service Provider Interface (SPI) for the KeyManagerFactory class.
KeyStoreBuilderParameters | A parameters object for X509KeyManagers that encapsulates a List of KeyStore.Builders.
SSLContext | Instances of this class represent a secure socket protocol implementation which acts as a factory for secure socket factories or SSLEngines.
SSLContextSpi | This class defines the Service Provider Interface (SPI) for the SSLContext class.
SSLEngine | A class which enables secure communications using protocols such as the Secure Sockets Layer (SSL) or IETF RFC 2246 "Transport Layer Security" (TLS) protocols, but is transport independent.
SSLEngineResult | An encapsulation of the result state produced by SSLEngine I/O calls.
SSLParameters | Encapsulates parameters for an SSL/TLS connection.
SSLPermission | This class is for various network permissions.
SSLServerSocket | This class extends ServerSockets and provides secure server sockets using protocols such as the Secure Sockets Layer (SSL) or Transport Layer Security (TLS) protocols.
SSLServerSocketFactory | SSLServerSocketFactorys create SSLServerSockets.
SSLSessionBindingEvent | This event is propagated to a SSLSessionBindingListener.
SSLSocket | This class extends Sockets and provides secure socket using protocols such as the "Secure Sockets Layer" (SSL) or IETF "Transport Layer Security" (TLS) protocols.
SSLSocketFactory | SSLSocketFactorys create SSLSockets.
TrustManagerFactory | This class acts as a factory for trust managers based on a source of trust material.
TrustManagerFactorySpi | This class defines the Service Provider Interface (SPI) for the TrustManagerFactory class.
X509ExtendedKeyManager | Abstract class that provides for extension of the X509KeyManager interface.

Enum Summary
SSLEngineResult.HandshakeStatus | An SSLEngineResult enum describing the current handshaking state of this SSLEngine.
SSLEngineResult.Status | An SSLEngineResult enum describing the overall result of the SSLEngine operation.

Exception Summary
SSLException | Indicates some kind of error detected by an SSL subsystem.
SSLHandshakeException | Indicates that the client and server could not negotiate the desired level of security.
SSLKeyException | Reports a bad SSL key.
SSLPeerUnverifiedException | Indicates that the peer's identity has not been verified.
SSLProtocolException | Reports an error in the operation of the SSL protocol.

Package javax.net.ssl Description

Provides classes for the secure socket package. Using the secure socket classes, you can communicate using SSL or a related security protocol to reliably detect any errors introduced into the network byte stream and to optionally encrypt the data and/or authenticate the communicating peers.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.net.ssl Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.net.ssl

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.net.ssl.CertPathTrustManagerParameters (implements javax.net.ssl.ManagerFactoryParameters)
    • java.util.EventObject (implements java.io.Serializable)
      • javax.net.ssl.HandshakeCompletedEvent
      • javax.net.ssl.SSLSessionBindingEvent
    • javax.net.ssl.KeyManagerFactory
    • javax.net.ssl.KeyManagerFactorySpi
    • javax.net.ssl.KeyStoreBuilderParameters (implements javax.net.ssl.ManagerFactoryParameters)
    • java.security.Permission (implements java.security.Guard, java.io.Serializable)
      • java.security.BasicPermission (implements java.io.Serializable)
        • javax.net.ssl.SSLPermission
    • java.net.ServerSocket
      • javax.net.ssl.SSLServerSocket
    • javax.net.ServerSocketFactory
      • javax.net.ssl.SSLServerSocketFactory
    • java.net.Socket
      • javax.net.ssl.SSLSocket
    • javax.net.SocketFactory
      • javax.net.ssl.SSLSocketFactory
    • javax.net.ssl.SSLContext
    • javax.net.ssl.SSLContextSpi
    • javax.net.ssl.SSLEngine
    • javax.net.ssl.SSLEngineResult
    • javax.net.ssl.SSLParameters
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.io.IOException
          • javax.net.ssl.SSLException
            • javax.net.ssl.SSLHandshakeException
            • javax.net.ssl.SSLKeyException
            • javax.net.ssl.SSLPeerUnverifiedException
            • javax.net.ssl.SSLProtocolException
    • javax.net.ssl.TrustManagerFactory
    • javax.net.ssl.TrustManagerFactorySpi
    • java.net.URLConnection
      • java.net.HttpURLConnection
        • javax.net.ssl.HttpsURLConnection
    • javax.net.ssl.X509ExtendedKeyManager (implements javax.net.ssl.X509KeyManager)

Interface Hierarchy

  • java.util.EventListener
    • javax.net.ssl.HandshakeCompletedListener
    • javax.net.ssl.SSLSessionBindingListener
  • javax.net.ssl.HostnameVerifier
  • javax.net.ssl.KeyManager
    • javax.net.ssl.X509KeyManager
  • javax.net.ssl.ManagerFactoryParameters
  • javax.net.ssl.SSLSession
  • javax.net.ssl.SSLSessionContext
  • javax.net.ssl.TrustManager
    • javax.net.ssl.X509TrustManager

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • javax.net.ssl.SSLEngineResult.Status
      • javax.net.ssl.SSLEngineResult.HandshakeStatus
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


KeyManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Interface KeyManager

All Known Subinterfaces:
X509KeyManager
All Known Implementing Classes:
X509ExtendedKeyManager
public interface KeyManager

This is the base interface for JSSE key managers.

KeyManagers are responsible for managing the key material which is used to authenticate the local SSLSocket to its peer. If no key material is available, the socket will be unable to present authentication credentials.

KeyManagers are created by either using a KeyManagerFactory, or by implementing one of the KeyManager subclasses.

Since:
1.4
See Also:
KeyManagerFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ManagerFactoryParameters

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Interface ManagerFactoryParameters

All Known Implementing Classes:
CertPathTrustManagerParameters, KeyStoreBuilderParameters
public interface ManagerFactoryParameters

This class is the base interface for providing algorithm-specific information to a KeyManagerFactory or TrustManagerFactory.

In some cases, initialization parameters other than keystores may be needed by a provider. Users of that particular provider are expected to pass an implementation of the appropriate sub-interface of this class as defined by the provider. The provider can then call the specified methods in the ManagerFactoryParameters implementation to obtain the needed information.

Since:
1.4

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TrustManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Interface TrustManager

All Known Subinterfaces:
X509TrustManager
public interface TrustManager

This is the base interface for JSSE trust managers.

TrustManagers are responsible for managing the trust material that is used when making trust decisions, and for deciding whether credentials presented by a peer should be accepted.

TrustManagers are created by either using a TrustManagerFactory, or by implementing one of the TrustManager subclasses.

Since:
1.4
See Also:
TrustManagerFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Package javax.net.ssl

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.net.ssl

Packages that use javax.net.ssl
java.net | Provides the classes for implementing networking applications.
javax.naming.ldap | Provides support for LDAPv3 extended operations and controls.
javax.net.ssl | Provides classes for the secure socket package.

Classes in javax.net.ssl used by java.net
SSLPeerUnverifiedException
Indicates that the peer's identity has not been verified.

Classes in javax.net.ssl used by javax.naming.ldap
HostnameVerifier
This class is the base interface for hostname verification.
SSLSession
In SSL, sessions are used to describe an ongoing relationship between two entities.
SSLSocketFactory
SSLSocketFactorys create SSLSockets.

Classes in javax.net.ssl used by javax.net.ssl
HandshakeCompletedEvent
This event indicates that an SSL handshake completed on a given SSL connection.
HandshakeCompletedListener
This interface is implemented by any class which wants to receive notifications about the completion of an SSL protocol handshake on a given SSL connection.
HostnameVerifier
This class is the base interface for hostname verification.
KeyManager
This is the base interface for JSSE key managers.
KeyManagerFactory
This class acts as a factory for key managers based on a source of key material.
KeyManagerFactorySpi
This class defines the Service Provider Interface (SPI) for the KeyManagerFactory class.
ManagerFactoryParameters
This class is the base interface for providing algorithm-specific information to a KeyManagerFactory or TrustManagerFactory.
SSLContext
Instances of this class represent a secure socket protocol implementation which acts as a factory for secure socket factories or SSLEngines.
SSLContextSpi
This class defines the Service Provider Interface (SPI) for the SSLContext class.
SSLEngine
A class which enables secure communications using protocols such as the Secure Sockets Layer (SSL) or IETF RFC 2246 "Transport Layer Security" (TLS) protocols, but is transport independent.
SSLEngineResult
An encapsulation of the result state produced by SSLEngine I/O calls.
SSLEngineResult.HandshakeStatus
An SSLEngineResult enum describing the current handshaking state of this SSLEngine.
SSLEngineResult.Status
An SSLEngineResult enum describing the overall result of the SSLEngine operation.
SSLException
Indicates some kind of error detected by an SSL subsystem.
SSLParameters
Encapsulates parameters for an SSL/TLS connection.
SSLPeerUnverifiedException
Indicates that the peer's identity has not been verified.
SSLServerSocketFactory
SSLServerSocketFactorys create SSLServerSockets.
SSLSession
In SSL, sessions are used to describe an ongoing relationship between two entities.
SSLSessionBindingEvent
This event is propagated to a SSLSessionBindingListener.
SSLSessionContext
A SSLSessionContext represents a set of SSLSessions associated with a single entity.
SSLSocket
This class extends Sockets and provides secure socket using protocols such as the "Secure Sockets Layer" (SSL) or IETF "Transport Layer Security" (TLS) protocols.
SSLSocketFactory
SSLSocketFactorys create SSLSockets.
TrustManager
This is the base interface for JSSE trust managers.
TrustManagerFactory
This class acts as a factory for trust managers based on a source of trust material.
TrustManagerFactorySpi
This class defines the Service Provider Interface (SPI) for the TrustManagerFactory class.
X509KeyManager
Instances of this interface manage which X509 certificate-based key pairs are used to authenticate the local side of a secure socket.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


CertPathTrustManagerParameters

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class CertPathTrustManagerParameters

java.lang.Object
    extended by  javax.net.ssl.CertPathTrustManagerParameters
All Implemented Interfaces:
ManagerFactoryParameters
public class CertPathTrustManagerParameters
extends Object
implements ManagerFactoryParameters

A wrapper for CertPathParameters. This class is used to pass validation settings to CertPath based TrustManagers using the TrustManagerFactory.init() method.

Instances of this class are immutable.

Since:
1.5
See Also:
X509TrustManager, TrustManagerFactory, CertPathParameters

Constructor Summary
CertPathTrustManagerParameters(CertPathParameters parameters)
Construct new CertPathTrustManagerParameters from the specified parameters.
Method Summary
 CertPathParameters getParameters()
Return a clone of the CertPathParameters encapsulated by this class.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CertPathTrustManagerParameters

public CertPathTrustManagerParameters(CertPathParameters parameters)
Construct new CertPathTrustManagerParameters from the specified parameters. The parameters are cloned to protect against subsequent modification.

Parameters:
parameters - the CertPathParameters to be used
Throws:
NullPointerException - if parameters is null
Method Detail

getParameters

public CertPathParameters getParameters()
Return a clone of the CertPathParameters encapsulated by this class.

Returns:
a clone of the CertPathParameters encapsulated by this class.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.net.ssl.CertPathTrustManagerParameters

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.CertPathTrustManagerParameters

No usage of javax.net.ssl.CertPathTrustManagerParameters

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.HandshakeCompletedEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.HandshakeCompletedEvent

Packages that use HandshakeCompletedEvent
javax.net.ssl Provides classes for the secure socket package.

Uses of HandshakeCompletedEvent in javax.net.ssl

Methods in javax.net.ssl with parameters of type HandshakeCompletedEvent
 void HandshakeCompletedListener.handshakeCompleted(HandshakeCompletedEvent event)
This method is invoked on registered objects when a SSL handshake is completed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.HttpsURLConnection

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.HttpsURLConnection

No usage of javax.net.ssl.HttpsURLConnection

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.KeyManagerFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.KeyManagerFactory

Packages that use KeyManagerFactory
javax.net.ssl Provides classes for the secure socket package.

Uses of KeyManagerFactory in javax.net.ssl

Methods in javax.net.ssl that return KeyManagerFactory
static KeyManagerFactory | KeyManagerFactory.getInstance(String algorithm) Returns a KeyManagerFactory object that acts as a factory for key managers.
static KeyManagerFactory | KeyManagerFactory.getInstance(String algorithm, Provider provider) Returns a KeyManagerFactory object that acts as a factory for key managers.
static KeyManagerFactory | KeyManagerFactory.getInstance(String algorithm, String provider) Returns a KeyManagerFactory object that acts as a factory for key managers.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.KeyManagerFactorySpi

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.KeyManagerFactorySpi

Packages that use KeyManagerFactorySpi
javax.net.ssl Provides classes for the secure socket package.

Uses of KeyManagerFactorySpi in javax.net.ssl

Constructors in javax.net.ssl with parameters of type KeyManagerFactorySpi
KeyManagerFactory(KeyManagerFactorySpi factorySpi, Provider provider, String algorithm)
Creates a KeyManagerFactory object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.KeyStoreBuilderParameters

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.KeyStoreBuilderParameters

No usage of javax.net.ssl.KeyStoreBuilderParameters

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLContext

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLContext

Packages that use SSLContext
javax.net.ssl Provides classes for the secure socket package.

Uses of SSLContext in javax.net.ssl

Methods in javax.net.ssl that return SSLContext
static SSLContext | SSLContext.getDefault() Returns the default SSL context.
static SSLContext | SSLContext.getInstance(String protocol) Returns a SSLContext object that implements the specified secure socket protocol.
static SSLContext | SSLContext.getInstance(String protocol, Provider provider) Returns a SSLContext object that implements the specified secure socket protocol.
static SSLContext | SSLContext.getInstance(String protocol, String provider) Returns a SSLContext object that implements the specified secure socket protocol.

Methods in javax.net.ssl with parameters of type SSLContext
static void SSLContext.setDefault(SSLContext context)
Sets the default SSL context.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLContextSpi

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLContextSpi

Packages that use SSLContextSpi
javax.net.ssl Provides classes for the secure socket package.

Uses of SSLContextSpi in javax.net.ssl

Constructors in javax.net.ssl with parameters of type SSLContextSpi
SSLContext(SSLContextSpi contextSpi, Provider provider, String protocol)
Creates an SSLContext object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLEngine

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLEngine

Packages that use SSLEngine
javax.net.ssl Provides classes for the secure socket package.

Uses of SSLEngine in javax.net.ssl

Methods in javax.net.ssl that return SSLEngine
SSLEngine | SSLContext.createSSLEngine() Creates a new SSLEngine using this context.
SSLEngine | SSLContext.createSSLEngine(String peerHost, int peerPort) Creates a new SSLEngine using this context using advisory peer information.
protected abstract SSLEngine | SSLContextSpi.engineCreateSSLEngine() Creates a new SSLEngine using this context.
protected abstract SSLEngine | SSLContextSpi.engineCreateSSLEngine(String host, int port) Creates a SSLEngine using this context.

Methods in javax.net.ssl with parameters of type SSLEngine
String | X509ExtendedKeyManager.chooseEngineClientAlias(String[] keyType, Principal[] issuers, SSLEngine engine) Choose an alias to authenticate the client side of an SSLEngine connection given the public key type and the list of certificate issuer authorities recognized by the peer (if any).
String | X509ExtendedKeyManager.chooseEngineServerAlias(String keyType, Principal[] issuers, SSLEngine engine) Choose an alias to authenticate the server side of an SSLEngine connection given the public key type and the list of certificate issuer authorities recognized by the peer (if any).

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLEngineResult

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLEngineResult

Packages that use SSLEngineResult
javax.net.ssl Provides classes for the secure socket package.

Uses of SSLEngineResult in javax.net.ssl

Methods in javax.net.ssl that return SSLEngineResult
SSLEngineResult | SSLEngine.unwrap(ByteBuffer src, ByteBuffer dst) Attempts to decode SSL/TLS network data into a plaintext application data buffer.
SSLEngineResult | SSLEngine.unwrap(ByteBuffer src, ByteBuffer[] dsts) Attempts to decode SSL/TLS network data into a sequence of plaintext application data buffers.
abstract SSLEngineResult | SSLEngine.unwrap(ByteBuffer src, ByteBuffer[] dsts, int offset, int length) Attempts to decode SSL/TLS network data into a subsequence of plaintext application data buffers.
SSLEngineResult | SSLEngine.wrap(ByteBuffer[] srcs, ByteBuffer dst) Attempts to encode plaintext bytes from a sequence of data buffers into SSL/TLS network data.
abstract SSLEngineResult | SSLEngine.wrap(ByteBuffer[] srcs, int offset, int length, ByteBuffer dst) Attempts to encode plaintext bytes from a subsequence of data buffers into SSL/TLS network data.
SSLEngineResult | SSLEngine.wrap(ByteBuffer src, ByteBuffer dst) Attempts to encode a buffer of plaintext application data into SSL/TLS network data.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLEngineResult.HandshakeStatus

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLEngineResult.HandshakeStatus

Packages that use SSLEngineResult.HandshakeStatus
javax.net.ssl Provides classes for the secure socket package.

Uses of SSLEngineResult.HandshakeStatus in javax.net.ssl

Methods in javax.net.ssl that return SSLEngineResult.HandshakeStatus
abstract SSLEngineResult.HandshakeStatus | SSLEngine.getHandshakeStatus() Returns the current handshake status for this SSLEngine.
SSLEngineResult.HandshakeStatus | SSLEngineResult.getHandshakeStatus() Gets the handshake status of this SSLEngine operation.
static SSLEngineResult.HandshakeStatus | SSLEngineResult.HandshakeStatus.valueOf(String name) Returns the enum constant of this type with the specified name.
static SSLEngineResult.HandshakeStatus[] | SSLEngineResult.HandshakeStatus.values() Returns an array containing the constants of this enum type, in the order they are declared.

Constructors in javax.net.ssl with parameters of type SSLEngineResult.HandshakeStatus
SSLEngineResult(SSLEngineResult.Status status, SSLEngineResult.HandshakeStatus handshakeStatus, int bytesConsumed, int bytesProduced)
Initializes a new instance of this class.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLEngineResult.Status

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLEngineResult.Status

Packages that use SSLEngineResult.Status
javax.net.ssl Provides classes for the secure socket package.

Uses of SSLEngineResult.Status in javax.net.ssl

Methods in javax.net.ssl that return SSLEngineResult.Status
SSLEngineResult.Status | SSLEngineResult.getStatus() Gets the return value of this SSLEngine operation.
static SSLEngineResult.Status | SSLEngineResult.Status.valueOf(String name) Returns the enum constant of this type with the specified name.
static SSLEngineResult.Status[] | SSLEngineResult.Status.values() Returns an array containing the constants of this enum type, in the order they are declared.

Constructors in javax.net.ssl with parameters of type SSLEngineResult.Status
SSLEngineResult(SSLEngineResult.Status status, SSLEngineResult.HandshakeStatus handshakeStatus, int bytesConsumed, int bytesProduced)
Initializes a new instance of this class.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLException

Packages that use SSLException
javax.net.ssl Provides classes for the secure socket package.

Uses of SSLException in javax.net.ssl

Subclasses of SSLException in javax.net.ssl
class | SSLHandshakeException Indicates that the client and server could not negotiate the desired level of security.
class | SSLKeyException Reports a bad SSL key.
class | SSLPeerUnverifiedException Indicates that the peer's identity has not been verified.
class | SSLProtocolException Reports an error in the operation of the SSL protocol.

Methods in javax.net.ssl that throw SSLException
abstract void | SSLEngine.beginHandshake() Initiates handshaking (initial or renegotiation) on this SSLEngine.
abstract void | SSLEngine.closeInbound() Signals that no more inbound network data will be sent to this SSLEngine.
SSLEngineResult | SSLEngine.unwrap(ByteBuffer src, ByteBuffer dst) Attempts to decode SSL/TLS network data into a plaintext application data buffer.
SSLEngineResult | SSLEngine.unwrap(ByteBuffer src, ByteBuffer[] dsts) Attempts to decode SSL/TLS network data into a sequence of plaintext application data buffers.
abstract SSLEngineResult | SSLEngine.unwrap(ByteBuffer src, ByteBuffer[] dsts, int offset, int length) Attempts to decode SSL/TLS network data into a subsequence of plaintext application data buffers.
SSLEngineResult | SSLEngine.wrap(ByteBuffer[] srcs, ByteBuffer dst) Attempts to encode plaintext bytes from a sequence of data buffers into SSL/TLS network data.
abstract SSLEngineResult | SSLEngine.wrap(ByteBuffer[] srcs, int offset, int length, ByteBuffer dst) Attempts to encode plaintext bytes from a subsequence of data buffers into SSL/TLS network data.
SSLEngineResult | SSLEngine.wrap(ByteBuffer src, ByteBuffer dst) Attempts to encode a buffer of plaintext application data into SSL/TLS network data.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLHandshakeException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLHandshakeException

No usage of javax.net.ssl.SSLHandshakeException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLKeyException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLKeyException

No usage of javax.net.ssl.SSLKeyException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLParameters

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLParameters

Packages that use SSLParameters
javax.net.ssl Provides classes for the secure socket package.

Uses of SSLParameters in javax.net.ssl

Methods in javax.net.ssl that return SSLParameters
protected SSLParameters | SSLContextSpi.engineGetDefaultSSLParameters() Returns a copy of the SSLParameters indicating the default settings for this SSL context.
protected SSLParameters | SSLContextSpi.engineGetSupportedSSLParameters() Returns a copy of the SSLParameters indicating the maximum supported settings for this SSL context.
SSLParameters | SSLContext.getDefaultSSLParameters() Returns a copy of the SSLParameters indicating the default settings for this SSL context.
SSLParameters | SSLSocket.getSSLParameters() Returns the SSLParameters in effect for this SSLSocket.
SSLParameters | SSLEngine.getSSLParameters() Returns the SSLParameters in effect for this SSLEngine.
SSLParameters | SSLContext.getSupportedSSLParameters() Returns a copy of the SSLParameters indicating the supported settings for this SSL context.

Methods in javax.net.ssl with parameters of type SSLParameters
void | SSLSocket.setSSLParameters(SSLParameters params) Applies SSLParameters to this socket.
void | SSLEngine.setSSLParameters(SSLParameters params) Applies SSLParameters to this engine.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLPeerUnverifiedException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLPeerUnverifiedException

Packages that use SSLPeerUnverifiedException
java.net | Provides the classes for implementing networking applications.
javax.net.ssl | Provides classes for the secure socket package.

Uses of SSLPeerUnverifiedException in java.net

Methods in java.net that throw SSLPeerUnverifiedException
abstract Principal | SecureCacheResponse.getPeerPrincipal() Returns the server's principal which was established as part of defining the session during the original connection that retrieved the network resource.
abstract List<Certificate> | SecureCacheResponse.getServerCertificateChain() Returns the server's certificate chain, which was established as part of defining the session in the original connection that retrieved the network resource, from cache.

Uses of SSLPeerUnverifiedException in javax.net.ssl

Methods in javax.net.ssl that throw SSLPeerUnverifiedException
X509Certificate[] | HandshakeCompletedEvent.getPeerCertificateChain() Returns the identity of the peer which was identified as part of defining the session.
X509Certificate[] | SSLSession.getPeerCertificateChain() Returns the identity of the peer which was identified as part of defining the session.
Certificate[] | HandshakeCompletedEvent.getPeerCertificates() Returns the identity of the peer which was established as part of defining the session.
Certificate[] | SSLSession.getPeerCertificates() Returns the identity of the peer which was established as part of defining the session.
Principal | HandshakeCompletedEvent.getPeerPrincipal() Returns the identity of the peer which was established as part of defining the session.
Principal | SSLSession.getPeerPrincipal() Returns the identity of the peer which was established as part of defining the session.
Principal | HttpsURLConnection.getPeerPrincipal() Returns the server's principal which was established as part of defining the session.
abstract Certificate[] | HttpsURLConnection.getServerCertificates() Returns the server's certificate chain which was established as part of defining the session.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLPermission

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLPermission

No usage of javax.net.ssl.SSLPermission

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLProtocolException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLProtocolException

No usage of javax.net.ssl.SSLProtocolException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLServerSocket

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLServerSocket

No usage of javax.net.ssl.SSLServerSocket

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLServerSocketFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLServerSocketFactory

Packages that use SSLServerSocketFactory
javax.net.ssl Provides classes for the secure socket package.

Uses of SSLServerSocketFactory in javax.net.ssl

Methods in javax.net.ssl that return SSLServerSocketFactory
protected abstract SSLServerSocketFactory | SSLContextSpi.engineGetServerSocketFactory() Returns a ServerSocketFactory object for this context.
SSLServerSocketFactory | SSLContext.getServerSocketFactory() Returns a ServerSocketFactory object for this context.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLSessionBindingEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLSessionBindingEvent

Packages that use SSLSessionBindingEvent
javax.net.ssl Provides classes for the secure socket package.

Uses of SSLSessionBindingEvent in javax.net.ssl

Methods in javax.net.ssl with parameters of type SSLSessionBindingEvent
void | SSLSessionBindingListener.valueBound(SSLSessionBindingEvent event) This is called to notify the listener that it is being bound into an SSLSession.
void | SSLSessionBindingListener.valueUnbound(SSLSessionBindingEvent event) This is called to notify the listener that it is being unbound from a SSLSession.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLSocket

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLSocket

Packages that use SSLSocket
javax.net.ssl Provides classes for the secure socket package.

Uses of SSLSocket in javax.net.ssl

Methods in javax.net.ssl that return SSLSocket
 SSLSocket HandshakeCompletedEvent.getSocket()
Returns the socket which is the source of this event.

Constructors in javax.net.ssl with parameters of type SSLSocket
HandshakeCompletedEvent(SSLSocket sock, SSLSession s)
Constructs a new HandshakeCompletedEvent.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.SSLSocketFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.SSLSocketFactory

Packages that use SSLSocketFactory
javax.naming.ldap | Provides support for LDAPv3 extended operations and controls.
javax.net.ssl | Provides classes for the secure socket package.

Uses of SSLSocketFactory in javax.naming.ldap

Methods in javax.naming.ldap with parameters of type SSLSocketFactory
abstract  SSLSession StartTlsResponse.negotiate(SSLSocketFactory factory)
Negotiates a TLS session using an SSL socket factory.

Uses of SSLSocketFactory in javax.net.ssl

Methods in javax.net.ssl that return SSLSocketFactory
protected abstract SSLSocketFactory | SSLContextSpi.engineGetSocketFactory() Returns a SocketFactory object for this context.
static SSLSocketFactory | HttpsURLConnection.getDefaultSSLSocketFactory() Gets the default static SSLSocketFactory that is inherited by new instances of this class.
SSLSocketFactory | SSLContext.getSocketFactory() Returns a SocketFactory object for this context.
SSLSocketFactory | HttpsURLConnection.getSSLSocketFactory() Gets the SSL socket factory to be used when creating sockets for secure https URL connections.

Methods in javax.net.ssl with parameters of type SSLSocketFactory
static void | HttpsURLConnection.setDefaultSSLSocketFactory(SSLSocketFactory sf) Sets the default SSLSocketFactory inherited by new instances of this class.
void | HttpsURLConnection.setSSLSocketFactory(SSLSocketFactory sf) Sets the SSLSocketFactory to be used when this instance creates sockets for secure https URL connections.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.TrustManagerFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.TrustManagerFactory

Packages that use TrustManagerFactory
javax.net.ssl Provides classes for the secure socket package.

Uses of TrustManagerFactory in javax.net.ssl

Methods in javax.net.ssl that return TrustManagerFactory
static TrustManagerFactory | TrustManagerFactory.getInstance(String algorithm) Returns a TrustManagerFactory object that acts as a factory for trust managers.
static TrustManagerFactory | TrustManagerFactory.getInstance(String algorithm, Provider provider) Returns a TrustManagerFactory object that acts as a factory for trust managers.
static TrustManagerFactory | TrustManagerFactory.getInstance(String algorithm, String provider) Returns a TrustManagerFactory object that acts as a factory for trust managers.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.TrustManagerFactorySpi

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.TrustManagerFactorySpi

Packages that use TrustManagerFactorySpi
javax.net.ssl Provides classes for the secure socket package.

Uses of TrustManagerFactorySpi in javax.net.ssl

Constructors in javax.net.ssl with parameters of type TrustManagerFactorySpi
TrustManagerFactory(TrustManagerFactorySpi factorySpi, Provider provider, String algorithm)
Creates a TrustManagerFactory object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.net.ssl.X509ExtendedKeyManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.net.ssl.X509ExtendedKeyManager

No usage of javax.net.ssl.X509ExtendedKeyManager

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.net.ssl.HandshakeCompletedListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.net.ssl.HandshakeCompletedListener

Packages that use HandshakeCompletedListener
javax.net.ssl Provides classes for the secure socket package.

Uses of HandshakeCompletedListener in javax.net.ssl

Methods in javax.net.ssl with parameters of type HandshakeCompletedListener
abstract void | SSLSocket.addHandshakeCompletedListener(HandshakeCompletedListener listener) Registers an event listener to receive notifications that an SSL handshake has completed on this connection.
abstract void | SSLSocket.removeHandshakeCompletedListener(HandshakeCompletedListener listener) Removes a previously registered handshake completion listener.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.net.ssl.HostnameVerifier

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.net.ssl.HostnameVerifier

Packages that use HostnameVerifier
javax.naming.ldap | Provides support for LDAPv3 extended operations and controls.
javax.net.ssl | Provides classes for the secure socket package.

Uses of HostnameVerifier in javax.naming.ldap

Methods in javax.naming.ldap with parameters of type HostnameVerifier
abstract  void StartTlsResponse.setHostnameVerifier(HostnameVerifier verifier)
Sets the hostname verifier used by negotiate() after the TLS handshake has completed and the default hostname verification has failed.

Uses of HostnameVerifier in javax.net.ssl

Fields in javax.net.ssl declared as HostnameVerifier
protected  HostnameVerifier HttpsURLConnection.hostnameVerifier
The hostnameVerifier for this object.

Methods in javax.net.ssl that return HostnameVerifier
static HostnameVerifier | HttpsURLConnection.getDefaultHostnameVerifier() Gets the default HostnameVerifier that is inherited by new instances of this class.
HostnameVerifier | HttpsURLConnection.getHostnameVerifier() Gets the HostnameVerifier in place on this instance.

Methods in javax.net.ssl with parameters of type HostnameVerifier
static void | HttpsURLConnection.setDefaultHostnameVerifier(HostnameVerifier v) Sets the default HostnameVerifier inherited by a new instance of this class.
void | HttpsURLConnection.setHostnameVerifier(HostnameVerifier v) Sets the HostnameVerifier for this instance.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.net.ssl.KeyManager

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.net.ssl.KeyManager

Packages that use KeyManager
javax.net.ssl Provides classes for the secure socket package.

Uses of KeyManager in javax.net.ssl

Subinterfaces of KeyManager in javax.net.ssl
 interface X509KeyManager
Instances of this interface manage which X509 certificate-based key pairs are used to authenticate the local side of a secure socket.

Classes in javax.net.ssl that implement KeyManager
 class X509ExtendedKeyManager
Abstract class that provides for extension of the X509KeyManager interface.

Methods in javax.net.ssl that return KeyManager
protected abstract KeyManager[] | KeyManagerFactorySpi.engineGetKeyManagers() Returns one key manager for each type of key material.
KeyManager[] | KeyManagerFactory.getKeyManagers() Returns one key manager for each type of key material.

Methods in javax.net.ssl with parameters of type KeyManager
protected abstract void | SSLContextSpi.engineInit(KeyManager[] km, TrustManager[] tm, SecureRandom sr) Initializes this context.
void | SSLContext.init(KeyManager[] km, TrustManager[] tm, SecureRandom random) Initializes this context.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.net.ssl.ManagerFactoryParameters

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.net.ssl.ManagerFactoryParameters

Packages that use ManagerFactoryParameters
javax.net.ssl Provides classes for the secure socket package.

Uses of ManagerFactoryParameters in javax.net.ssl

Classes in javax.net.ssl that implement ManagerFactoryParameters
class | CertPathTrustManagerParameters A wrapper for CertPathParameters.
class | KeyStoreBuilderParameters A parameters object for X509KeyManagers that encapsulates a List of KeyStore.Builders.

Methods in javax.net.ssl with parameters of type ManagerFactoryParameters
protected abstract void | KeyManagerFactorySpi.engineInit(ManagerFactoryParameters spec) Initializes this factory with a source of key material.
protected abstract void | TrustManagerFactorySpi.engineInit(ManagerFactoryParameters spec) Initializes this factory with a source of provider-specific key material.
void | KeyManagerFactory.init(ManagerFactoryParameters spec) Initializes this factory with a source of provider-specific key material.
void | TrustManagerFactory.init(ManagerFactoryParameters spec) Initializes this factory with a source of provider-specific trust material.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.net.ssl.SSLSession

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.net.ssl.SSLSession

Packages that use SSLSession
javax.naming.ldap | Provides support for LDAPv3 extended operations and controls.
javax.net.ssl | Provides classes for the secure socket package.

Uses of SSLSession in javax.naming.ldap

Methods in javax.naming.ldap that return SSLSession
abstract SSLSession | StartTlsResponse.negotiate() Negotiates a TLS session using the default SSL socket factory.
abstract SSLSession | StartTlsResponse.negotiate(SSLSocketFactory factory) Negotiates a TLS session using an SSL socket factory.

Uses of SSLSession in javax.net.ssl

Methods in javax.net.ssl that return SSLSession
SSLSession | HandshakeCompletedEvent.getSession() Returns the session that triggered this event.
abstract SSLSession | SSLSocket.getSession() Returns the SSL Session in use by this connection.
abstract SSLSession | SSLEngine.getSession() Returns the SSLSession in use in this SSLEngine.
SSLSession | SSLSessionBindingEvent.getSession() Returns the SSLSession into which the listener is being bound or from which the listener is being unbound.
SSLSession | SSLSessionContext.getSession(byte[] sessionId) Returns the SSLSession bound to the specified session id.

Methods in javax.net.ssl with parameters of type SSLSession
 boolean HostnameVerifier.verify(String hostname, SSLSession session)
Verify that the host name is an acceptable match with the server's authentication scheme.

Constructors in javax.net.ssl with parameters of type SSLSession
HandshakeCompletedEvent(SSLSocket sock, SSLSession s)
Constructs a new HandshakeCompletedEvent.
SSLSessionBindingEvent(SSLSession session, String name)
Constructs a new SSLSessionBindingEvent.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.net.ssl.SSLSessionBindingListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.net.ssl.SSLSessionBindingListener

No usage of javax.net.ssl.SSLSessionBindingListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.net.ssl.SSLSessionContext

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.net.ssl.SSLSessionContext

Packages that use SSLSessionContext
javax.net.ssl Provides classes for the secure socket package.

Uses of SSLSessionContext in javax.net.ssl

Methods in javax.net.ssl that return SSLSessionContext
protected abstract SSLSessionContext | SSLContextSpi.engineGetClientSessionContext() Returns a client SSLSessionContext object for this context.
protected abstract SSLSessionContext | SSLContextSpi.engineGetServerSessionContext() Returns a server SSLSessionContext object for this context.
SSLSessionContext | SSLContext.getClientSessionContext() Returns the client session context, which represents the set of SSL sessions available for use during the handshake phase of client-side SSL sockets.
SSLSessionContext | SSLContext.getServerSessionContext() Returns the server session context, which represents the set of SSL sessions available for use during the handshake phase of server-side SSL sockets.
SSLSessionContext | SSLSession.getSessionContext() Returns the context in which this session is bound.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.net.ssl.TrustManager

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.net.ssl.TrustManager

Packages that use TrustManager
javax.net.ssl Provides classes for the secure socket package.

Uses of TrustManager in javax.net.ssl

Subinterfaces of TrustManager in javax.net.ssl
 interface X509TrustManager
Instance of this interface manage which X509 certificates may be used to authenticate the remote side of a secure socket.

Methods in javax.net.ssl that return TrustManager
protected abstract TrustManager[] | TrustManagerFactorySpi.engineGetTrustManagers() Returns one trust manager for each type of trust material.
TrustManager[] | TrustManagerFactory.getTrustManagers() Returns one trust manager for each type of trust material.

Methods in javax.net.ssl with parameters of type TrustManager
protected abstract void | SSLContextSpi.engineInit(KeyManager[] km, TrustManager[] tm, SecureRandom sr) Initializes this context.
void | SSLContext.init(KeyManager[] km, TrustManager[] tm, SecureRandom random) Initializes this context.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.net.ssl.X509KeyManager

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.net.ssl.X509KeyManager

Packages that use X509KeyManager
javax.net.ssl Provides classes for the secure socket package.

Uses of X509KeyManager in javax.net.ssl

Classes in javax.net.ssl that implement X509KeyManager
 class X509ExtendedKeyManager
Abstract class that provides for extension of the X509KeyManager interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.net.ssl.X509TrustManager

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.net.ssl.X509TrustManager

No usage of javax.net.ssl.X509TrustManager

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


HandshakeCompletedEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class HandshakeCompletedEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.net.ssl.HandshakeCompletedEvent
All Implemented Interfaces:
Serializable
public class HandshakeCompletedEvent
extends EventObject

This event indicates that an SSL handshake completed on a given SSL connection. All of the core information about that handshake's result is captured through an "SSLSession" object. As a convenience, this event class provides direct access to some important session attributes.

The source of this event is the SSLSocket on which handshaking just completed.

Since:
1.4
See Also:
SSLSocket, HandshakeCompletedListener, SSLSession, Serialized Form

Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
HandshakeCompletedEvent(SSLSocket sock, SSLSession s)
Constructs a new HandshakeCompletedEvent.
Method Summary
String | getCipherSuite() Returns the cipher suite in use by the session which was produced by the handshake.
Certificate[] | getLocalCertificates() Returns the certificate(s) that were sent to the peer during handshaking.
Principal | getLocalPrincipal() Returns the principal that was sent to the peer during handshaking.
X509Certificate[] | getPeerCertificateChain() Returns the identity of the peer which was identified as part of defining the session.
Certificate[] | getPeerCertificates() Returns the identity of the peer which was established as part of defining the session.
Principal | getPeerPrincipal() Returns the identity of the peer which was established as part of defining the session.
SSLSession | getSession() Returns the session that triggered this event.
SSLSocket | getSocket() Returns the socket which is the source of this event.
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

HandshakeCompletedEvent

public HandshakeCompletedEvent(SSLSocket sock,
                               SSLSession s)
Constructs a new HandshakeCompletedEvent.

Parameters:
sock - the SSLSocket acting as the source of the event
s - the SSLSession this event is associated with
Method Detail

getSession

public SSLSession getSession()
Returns the session that triggered this event.

Returns:
the SSLSession for this handshake

getCipherSuite

public String getCipherSuite()
Returns the cipher suite in use by the session which was produced by the handshake. (This is a convenience method for getting the ciphersuite from the SSLsession.)

Returns:
the name of the cipher suite negotiated during this session.

getLocalCertificates

public Certificate[] getLocalCertificates()
Returns the certificate(s) that were sent to the peer during handshaking. Note: This method is useful only when using certificate-based cipher suites. When multiple certificates are available for use in a handshake, the implementation chooses what it considers the "best" certificate chain available, and transmits that to the other side. This method allows the caller to know which certificate chain was actually used.

Returns:
an ordered array of certificates, with the local certificate first followed by any certificate authorities. If no certificates were sent, then null is returned.
See Also:
getLocalPrincipal()

getPeerCertificates

public Certificate[] getPeerCertificates()
                                  throws SSLPeerUnverifiedException
Returns the identity of the peer which was established as part of defining the session. Note: This method can be used only when using certificate-based cipher suites; using it with non-certificate-based cipher suites, such as Kerberos, will throw an SSLPeerUnverifiedException.

Returns:
an ordered array of the peer certificates, with the peer's own certificate first followed by any certificate authorities.
Throws:
SSLPeerUnverifiedException - if the peer is not verified.
See Also:
getPeerPrincipal()

getPeerCertificateChain

public X509Certificate[] getPeerCertificateChain()
                                          throws SSLPeerUnverifiedException
Returns the identity of the peer which was identified as part of defining the session. Note: This method can be used only when using certificate-based cipher suites; using it with non-certificate-based cipher suites, such as Kerberos, will throw an SSLPeerUnverifiedException.

Note: this method exists for compatibility with previous releases. New applications should use getPeerCertificates() instead.

Returns:
an ordered array of peer X.509 certificates, with the peer's own certificate first followed by any certificate authorities. (The certificates are in the original JSSE X509Certificate format).
Throws:
SSLPeerUnverifiedException - if the peer is not verified.
See Also:
getPeerPrincipal()

getPeerPrincipal

public Principal getPeerPrincipal()
                           throws SSLPeerUnverifiedException
Returns the identity of the peer which was established as part of defining the session.

Returns:
the peer's principal. Returns an X500Principal of the end-entity certiticate for X509-based cipher suites, and KerberosPrincipal for Kerberos cipher suites.
Throws:
SSLPeerUnverifiedException - if the peer's identity has not been verified
Since:
1.5
See Also:
getPeerCertificates(), getLocalPrincipal()

getLocalPrincipal

public Principal getLocalPrincipal()
Returns the principal that was sent to the peer during handshaking.

Returns:
the principal sent to the peer. Returns an X500Principal of the end-entity certificate for X509-based cipher suites, and KerberosPrincipal for Kerberos cipher suites. If no principal was sent, then null is returned.
Since:
1.5
See Also:
getLocalCertificates(), getPeerPrincipal()

getSocket

public SSLSocket getSocket()
Returns the socket which is the source of this event. (This is a convenience function, to let applications write code without type casts.)

Returns:
the socket on which the connection was made.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HandshakeCompletedListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Interface HandshakeCompletedListener

All Superinterfaces:
EventListener
public interface HandshakeCompletedListener
extends EventListener

This interface is implemented by any class which wants to receive notifications about the completion of an SSL protocol handshake on a given SSL connection.

When an SSL handshake completes, new security parameters will have been established. Those parameters always include the security keys used to protect messages. They may also include parameters associated with a new session such as authenticated peer identity and a new SSL cipher suite.

Since:
1.4

Method Summary
 void handshakeCompleted(HandshakeCompletedEvent event)
This method is invoked on registered objects when a SSL handshake is completed.

Method Detail

handshakeCompleted

void handshakeCompleted(HandshakeCompletedEvent event)
This method is invoked on registered objects when a SSL handshake is completed.

Parameters:
event - the event identifying when the SSL Handshake completed on a given SSL connection
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HostnameVerifier

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Interface HostnameVerifier

public interface HostnameVerifier

This class is the base interface for hostname verification.

During handshaking, if the URL's hostname and the server's identification hostname mismatch, the verification mechanism can call back to implementers of this interface to determine if this connection should be allowed.

The policies can be certificate-based or may depend on other authentication schemes.

These callbacks are used when the default rules for URL hostname verification fail.

Since:
1.4

Method Summary
 boolean verify(String hostname, SSLSession session)
Verify that the host name is an acceptable match with the server's authentication scheme.

Method Detail

verify

boolean verify(String hostname,
               SSLSession session)
Verify that the host name is an acceptable match with the server's authentication scheme.

Parameters:
hostname - the host name
session - SSLSession used on the connection to host
Returns:
true if the host name is acceptable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HttpsURLConnection

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class HttpsURLConnection

java.lang.Object
    extended by  java.net.URLConnection
        extended by  java.net.HttpURLConnection
            extended by  javax.net.ssl.HttpsURLConnection

public abstract class HttpsURLConnection
extends HttpURLConnection

HttpsURLConnection extends HttpURLConnection with support for https-specific features.

See http://www.w3.org/pub/WWW/Protocols/ and RFC 2818 for more details on the https specification.

This class uses HostnameVerifier and SSLSocketFactory. There are default implementations defined for both classes. However, the implementations can be replaced on a per-class (static) or per-instance basis. All new HttpsURLConnections instances will be assigned the "default" static values at instance creation, but they can be overriden by calling the appropriate per-instance set method(s) before connecting.

Since:
1.4

Field Summary
protected  HostnameVerifier hostnameVerifier
The hostnameVerifier for this object.
Fields inherited from class java.net.HttpURLConnection
chunkLength, fixedContentLength, HTTP_ACCEPTED, HTTP_BAD_GATEWAY, HTTP_BAD_METHOD, HTTP_BAD_REQUEST, HTTP_CLIENT_TIMEOUT, HTTP_CONFLICT, HTTP_CREATED, HTTP_ENTITY_TOO_LARGE, HTTP_FORBIDDEN, HTTP_GATEWAY_TIMEOUT, HTTP_GONE, HTTP_INTERNAL_ERROR, HTTP_LENGTH_REQUIRED, HTTP_MOVED_PERM, HTTP_MOVED_TEMP, HTTP_MULT_CHOICE, HTTP_NO_CONTENT, HTTP_NOT_ACCEPTABLE, HTTP_NOT_AUTHORITATIVE, HTTP_NOT_FOUND, HTTP_NOT_IMPLEMENTED, HTTP_NOT_MODIFIED, HTTP_OK, HTTP_PARTIAL, HTTP_PAYMENT_REQUIRED, HTTP_PRECON_FAILED, HTTP_PROXY_AUTH, HTTP_REQ_TOO_LONG, HTTP_RESET, HTTP_SEE_OTHER, HTTP_SERVER_ERROR, HTTP_UNAUTHORIZED, HTTP_UNAVAILABLE, HTTP_UNSUPPORTED_TYPE, HTTP_USE_PROXY, HTTP_VERSION, instanceFollowRedirects, method, responseCode, responseMessage
Fields inherited from class java.net.URLConnection
allowUserInteraction, connected, doInput, doOutput, ifModifiedSince, url, useCaches
Constructor Summary
protected HttpsURLConnection(URL url)
Creates an HttpsURLConnection using the URL specified.
Method Summary
abstract String | getCipherSuite() Returns the cipher suite in use on this connection.
static HostnameVerifier | getDefaultHostnameVerifier() Gets the default HostnameVerifier that is inherited by new instances of this class.
static SSLSocketFactory | getDefaultSSLSocketFactory() Gets the default static SSLSocketFactory that is inherited by new instances of this class.
HostnameVerifier | getHostnameVerifier() Gets the HostnameVerifier in place on this instance.
abstract Certificate[] | getLocalCertificates() Returns the certificate(s) that were sent to the server during handshaking.
Principal | getLocalPrincipal() Returns the principal that was sent to the server during handshaking.
Principal | getPeerPrincipal() Returns the server's principal which was established as part of defining the session.
abstract Certificate[] | getServerCertificates() Returns the server's certificate chain which was established as part of defining the session.
SSLSocketFactory | getSSLSocketFactory() Gets the SSL socket factory to be used when creating sockets for secure https URL connections.
static void | setDefaultHostnameVerifier(HostnameVerifier v) Sets the default HostnameVerifier inherited by a new instance of this class.
static void | setDefaultSSLSocketFactory(SSLSocketFactory sf) Sets the default SSLSocketFactory inherited by new instances of this class.
void | setHostnameVerifier(HostnameVerifier v) Sets the HostnameVerifier for this instance.
void | setSSLSocketFactory(SSLSocketFactory sf) Sets the SSLSocketFactory to be used when this instance creates sockets for secure https URL connections.
Methods inherited from class java.net.HttpURLConnection
disconnect, getErrorStream, getFollowRedirects, getHeaderField, getHeaderFieldDate, getHeaderFieldKey, getInstanceFollowRedirects, getPermission, getRequestMethod, getResponseCode, getResponseMessage, setChunkedStreamingMode, setFixedLengthStreamingMode, setFollowRedirects, setInstanceFollowRedirects, setRequestMethod, usingProxy
Methods inherited from class java.net.URLConnection
addRequestProperty, connect, getAllowUserInteraction, getConnectTimeout, getContent, getContent, getContentEncoding, getContentLength, getContentType, getDate, getDefaultAllowUserInteraction, getDefaultRequestProperty, getDefaultUseCaches, getDoInput, getDoOutput, getExpiration, getFileNameMap, getHeaderField, getHeaderFieldInt, getHeaderFields, getIfModifiedSince, getInputStream, getLastModified, getOutputStream, getReadTimeout, getRequestProperties, getRequestProperty, getURL, getUseCaches, guessContentTypeFromName, guessContentTypeFromStream, setAllowUserInteraction, setConnectTimeout, setContentHandlerFactory, setDefaultAllowUserInteraction, setDefaultRequestProperty, setDefaultUseCaches, setDoInput, setDoOutput, setFileNameMap, setIfModifiedSince, setReadTimeout, setRequestProperty, setUseCaches, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

hostnameVerifier

protected HostnameVerifier hostnameVerifier
The hostnameVerifier for this object.

Constructor Detail

HttpsURLConnection

protected HttpsURLConnection(URL url)
Creates an HttpsURLConnection using the URL specified.

Parameters:
url - the URL
Method Detail

getCipherSuite

public abstract String getCipherSuite()
Returns the cipher suite in use on this connection.

Returns:
the cipher suite
Throws:
IllegalStateException - if this method is called before the connection has been established.

getLocalCertificates

public abstract Certificate[] getLocalCertificates()
Returns the certificate(s) that were sent to the server during handshaking.

Note: This method is useful only when using certificate-based cipher suites.

When multiple certificates are available for use in a handshake, the implementation chooses what it considers the "best" certificate chain available, and transmits that to the other side. This method allows the caller to know which certificate chain was actually sent.

Returns:
an ordered array of certificates, with the client's own certificate first followed by any certificate authorities. If no certificates were sent, then null is returned.
Throws:
IllegalStateException - if this method is called before the connection has been established.
See Also:
getLocalPrincipal()

getServerCertificates

public abstract Certificate[] getServerCertificates()
                                             throws SSLPeerUnverifiedException
Returns the server's certificate chain which was established as part of defining the session.

Note: This method can be used only when using certificate-based cipher suites; using it with non-certificate-based cipher suites, such as Kerberos, will throw an SSLPeerUnverifiedException.

Returns:
an ordered array of server certificates, with the peer's own certificate first followed by any certificate authorities.
Throws:
SSLPeerUnverifiedException - if the peer is not verified.
IllegalStateException - if this method is called before the connection has been established.
See Also:
getPeerPrincipal()

getPeerPrincipal

public Principal getPeerPrincipal()
                           throws SSLPeerUnverifiedException
Returns the server's principal which was established as part of defining the session.

Note: Subclasses should override this method. If not overridden, it will default to returning the X500Principal of the server's end-entity certificate for certificate-based ciphersuites, or throw an SSLPeerUnverifiedException for non-certificate based ciphersuites, such as Kerberos.

Returns:
the server's principal. Returns an X500Principal of the end-entity certiticate for X509-based cipher suites, and KerberosPrincipal for Kerberos cipher suites.
Throws:
SSLPeerUnverifiedException - if the peer was not verified
IllegalStateException - if this method is called before the connection has been established.
Since:
1.5
See Also:
getServerCertificates(), getLocalPrincipal()

getLocalPrincipal

public Principal getLocalPrincipal()
Returns the principal that was sent to the server during handshaking.

Note: Subclasses should override this method. If not overridden, it will default to returning the X500Principal of the end-entity certificate that was sent to the server for certificate-based ciphersuites or, return null for non-certificate based ciphersuites, such as Kerberos.

Returns:
the principal sent to the server. Returns an X500Principal of the end-entity certificate for X509-based cipher suites, and KerberosPrincipal for Kerberos cipher suites. If no principal was sent, then null is returned.
Throws:
IllegalStateException - if this method is called before the connection has been established.
Since:
1.5
See Also:
getLocalCertificates(), getPeerPrincipal()

setDefaultHostnameVerifier

public static void setDefaultHostnameVerifier(HostnameVerifier v)
Sets the default HostnameVerifier inherited by a new instance of this class.

If this method is not called, the default HostnameVerifier assumes the connection should not be permitted.

Parameters:
v - the default host name verifier
Throws:
IllegalArgumentException - if the HostnameVerifier parameter is null.
SecurityException - if a security manager exists and its checkPermission method does not allow SSLPermission("setHostnameVerifier")
See Also:
getDefaultHostnameVerifier()

getDefaultHostnameVerifier

public static HostnameVerifier getDefaultHostnameVerifier()
Gets the default HostnameVerifier that is inherited by new instances of this class.

Returns:
the default host name verifier
See Also:
setDefaultHostnameVerifier(HostnameVerifier)

setHostnameVerifier

public void setHostnameVerifier(HostnameVerifier v)
Sets the HostnameVerifier for this instance.

New instances of this class inherit the default static hostname verifier set by setDefaultHostnameVerifier. Calls to this method replace this object's HostnameVerifier.

Parameters:
v - the host name verifier
Throws:
IllegalArgumentException - if the HostnameVerifier parameter is null.
See Also:
getHostnameVerifier(), setDefaultHostnameVerifier(HostnameVerifier)

getHostnameVerifier

public HostnameVerifier getHostnameVerifier()
Gets the HostnameVerifier in place on this instance.

Returns:
the host name verifier
See Also:
setHostnameVerifier(HostnameVerifier), setDefaultHostnameVerifier(HostnameVerifier)

setDefaultSSLSocketFactory

public static void setDefaultSSLSocketFactory(SSLSocketFactory sf)
Sets the default SSLSocketFactory inherited by new instances of this class.

The socket factories are used when creating sockets for secure https URL connections.

Parameters:
sf - the default SSL socket factory
Throws:
IllegalArgumentException - if the SSLSocketFactory parameter is null.
SecurityException - if a security manager exists and its checkSetFactory method does not allow a socket factory to be specified.
See Also:
getDefaultSSLSocketFactory()

getDefaultSSLSocketFactory

public static SSLSocketFactory getDefaultSSLSocketFactory()
Gets the default static SSLSocketFactory that is inherited by new instances of this class.

The socket factories are used when creating sockets for secure https URL connections.

Returns:
the default SSLSocketFactory
See Also:
setDefaultSSLSocketFactory(SSLSocketFactory)

setSSLSocketFactory

public void setSSLSocketFactory(SSLSocketFactory sf)
Sets the SSLSocketFactory to be used when this instance creates sockets for secure https URL connections.

New instances of this class inherit the default static SSLSocketFactory set by setDefaultSSLSocketFactory. Calls to this method replace this object's SSLSocketFactory.

Parameters:
sf - the SSL socket factory
Throws:
IllegalArgumentException - if the SSLSocketFactory parameter is null.
See Also:
getSSLSocketFactory()

getSSLSocketFactory

public SSLSocketFactory getSSLSocketFactory()
Gets the SSL socket factory to be used when creating sockets for secure https URL connections.

Returns:
the SSLSocketFactory
See Also:
setSSLSocketFactory(SSLSocketFactory)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


KeyManagerFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class KeyManagerFactory

java.lang.Object
    extended by  javax.net.ssl.KeyManagerFactory

public class KeyManagerFactory
extends Object

This class acts as a factory for key managers based on a source of key material. Each key manager manages a specific type of key material for use by secure sockets. The key material is based on a KeyStore and/or provider specific sources.

Since:
1.4
See Also:
KeyManager

Constructor Summary
protected KeyManagerFactory(KeyManagerFactorySpi factorySpi, Provider provider, String algorithm)
Creates a KeyManagerFactory object.
Method Summary
String | getAlgorithm() Returns the algorithm name of this KeyManagerFactory object.
static String | getDefaultAlgorithm() Obtains the default KeyManagerFactory algorithm name.
static KeyManagerFactory | getInstance(String algorithm) Returns a KeyManagerFactory object that acts as a factory for key managers.
static KeyManagerFactory | getInstance(String algorithm, Provider provider) Returns a KeyManagerFactory object that acts as a factory for key managers.
static KeyManagerFactory | getInstance(String algorithm, String provider) Returns a KeyManagerFactory object that acts as a factory for key managers.
KeyManager[] | getKeyManagers() Returns one key manager for each type of key material.
Provider | getProvider() Returns the provider of this KeyManagerFactory object.
void | init(KeyStore ks, char[] password) Initializes this factory with a source of key material.
void | init(ManagerFactoryParameters spec) Initializes this factory with a source of provider-specific key material.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

KeyManagerFactory

protected KeyManagerFactory(KeyManagerFactorySpi factorySpi,
                            Provider provider,
                            String algorithm)
Creates a KeyManagerFactory object.

Parameters:
factorySpi - the delegate
provider - the provider
algorithm - the algorithm
Method Detail

getDefaultAlgorithm

public static final String getDefaultAlgorithm()
Obtains the default KeyManagerFactory algorithm name.

The default algorithm can be changed at runtime by setting the value of the "ssl.KeyManagerFactory.algorithm" security property (set in the Java security properties file or by calling Security.setProperty(java.lang.String, java.lang.String)) to the desired algorithm name.

Returns:
the default algorithm name as specified in the Java security properties, or an implementation-specific default if no such property exists.
See Also:
Security.setProperty(java.lang.String, java.lang.String)

getAlgorithm

public final String getAlgorithm()
Returns the algorithm name of this KeyManagerFactory object.

This is the same name that was specified in one of the getInstance calls that created this KeyManagerFactory object.

Returns:
the algorithm name of this KeyManagerFactory object.

getInstance

public static final KeyManagerFactory getInstance(String algorithm)
                                           throws NoSuchAlgorithmException
Returns a KeyManagerFactory object that acts as a factory for key managers.

This method traverses the list of registered security Providers, starting with the most preferred Provider. A new KeyManagerFactory object encapsulating the KeyManagerFactorySpi implementation from the first Provider that supports the specified algorithm is returned.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters:
algorithm - the standard name of the requested algorithm. See the Java Secure Socket Extension Reference Guide for information about standard algorithm names.
Returns:
the new KeyManagerFactory object.
Throws:
NoSuchAlgorithmException - if no Provider supports a KeyManagerFactorySpi implementation for the specified algorithm.
See Also:
Provider

getInstance

public static final KeyManagerFactory getInstance(String algorithm,
                                                  String provider)
                                           throws NoSuchAlgorithmException,
                                                  NoSuchProviderException
Returns a KeyManagerFactory object that acts as a factory for key managers.

A new KeyManagerFactory object encapsulating the KeyManagerFactorySpi implementation from the specified provider is returned. The specified provider must be registered in the security provider list.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters:
algorithm - the standard name of the requested algorithm. See the Java Secure Socket Extension Reference Guide for information about standard algorithm names.
provider - the name of the provider.
Returns:
the new KeyManagerFactory object.
Throws:
NoSuchAlgorithmException - if a KeyManagerFactorySpi implementation for the specified algorithm is not available from the specified provider.
NoSuchProviderException - if the specified provider is not registered in the security provider list.
IllegalArgumentException - if the provider name is null or empty.
See Also:
Provider

getInstance

public static final KeyManagerFactory getInstance(String algorithm,
                                                  Provider provider)
                                           throws NoSuchAlgorithmException
Returns a KeyManagerFactory object that acts as a factory for key managers.

A new KeyManagerFactory object encapsulating the KeyManagerFactorySpi implementation from the specified Provider object is returned. Note that the specified Provider object does not have to be registered in the provider list.

Parameters:
algorithm - the standard name of the requested algorithm. See the Java Secure Socket Extension Reference Guide for information about standard algorithm names.
provider - an instance of the provider.
Returns:
the new KeyManagerFactory object.
Throws:
NoSuchAlgorithmException - if a KeyManagerFactorySpi implementation for the specified algorithm is not available from the specified Provider object.
IllegalArgumentException - if provider is null.
See Also:
Provider

getProvider

public final Provider getProvider()
Returns the provider of this KeyManagerFactory object.

Returns:
the provider of this KeyManagerFactory object

init

public final void init(KeyStore ks,
                       char[] password)
                throws KeyStoreException,
                       NoSuchAlgorithmException,
                       UnrecoverableKeyException
Initializes this factory with a source of key material.

The provider typically uses a KeyStore for obtaining key material for use during secure socket negotiations. The KeyStore is generally password-protected.

For more flexible initialization, please see init(ManagerFactoryParameters).

Parameters:
ks - the key store or null
password - the password for recovering keys in the KeyStore
Throws:
KeyStoreException - if this operation fails
NoSuchAlgorithmException - if the specified algorithm is not available from the specified provider.
UnrecoverableKeyException - if the key cannot be recovered (e.g. the given password is wrong).

init

public final void init(ManagerFactoryParameters spec)
                throws InvalidAlgorithmParameterException
Initializes this factory with a source of provider-specific key material.

In some cases, initialization parameters other than a keystore and password may be needed by a provider. Users of that particular provider are expected to pass an implementation of the appropriate ManagerFactoryParameters as defined by the provider. The provider can then call the specified methods in the ManagerFactoryParameters implementation to obtain the needed information.

Parameters:
spec - an implementation of a provider-specific parameter specification
Throws:
InvalidAlgorithmParameterException - if an error is encountered

getKeyManagers

public final KeyManager[] getKeyManagers()
Returns one key manager for each type of key material.

Returns:
the key managers
Throws:
IllegalStateException - if the KeyManagerFactory is not initialized
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


KeyManagerFactorySpi

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class KeyManagerFactorySpi

java.lang.Object
    extended by  javax.net.ssl.KeyManagerFactorySpi

public abstract class KeyManagerFactorySpi
extends Object

This class defines the Service Provider Interface (SPI) for the KeyManagerFactory class.

All the abstract methods in this class must be implemented by each cryptographic service provider who wishes to supply the implementation of a particular key manager factory.

Since:
1.4
See Also:
KeyManagerFactory, KeyManager

Constructor Summary
KeyManagerFactorySpi()
Method Summary
protected abstract KeyManager[] | engineGetKeyManagers() Returns one key manager for each type of key material.
protected abstract void | engineInit(KeyStore ks, char[] password) Initializes this factory with a source of key material.
protected abstract void | engineInit(ManagerFactoryParameters spec) Initializes this factory with a source of key material.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

KeyManagerFactorySpi

public KeyManagerFactorySpi()
Method Detail

engineInit

protected abstract void engineInit(KeyStore ks,
                                   char[] password)
                            throws KeyStoreException,
                                   NoSuchAlgorithmException,
                                   UnrecoverableKeyException
Initializes this factory with a source of key material.

Parameters:
ks - the key store or null
password - the password for recovering keys
Throws:
KeyStoreException - if this operation fails
NoSuchAlgorithmException - if the specified algorithm is not available from the specified provider.
UnrecoverableKeyException - if the key cannot be recovered
See Also:
KeyManagerFactory.init(KeyStore, char[])

engineInit

protected abstract void engineInit(ManagerFactoryParameters spec)
                            throws InvalidAlgorithmParameterException
Initializes this factory with a source of key material.

In some cases, initialization parameters other than a keystore and password may be needed by a provider. Users of that particular provider are expected to pass an implementation of the appropriate ManagerFactoryParameters as defined by the provider. The provider can then call the specified methods in the ManagerFactoryParameters implementation to obtain the needed information.

Parameters:
spec - an implementation of a provider-specific parameter specification
Throws:
InvalidAlgorithmParameterException - if there is problem with the parameters
See Also:
KeyManagerFactory.init(ManagerFactoryParameters spec)

engineGetKeyManagers

protected abstract KeyManager[] engineGetKeyManagers()
Returns one key manager for each type of key material.

Returns:
the key managers
Throws:
IllegalStateException - if the KeyManagerFactorySpi is not initialized
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


KeyStoreBuilderParameters

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class KeyStoreBuilderParameters

java.lang.Object
    extended by  javax.net.ssl.KeyStoreBuilderParameters
All Implemented Interfaces:
ManagerFactoryParameters
public class KeyStoreBuilderParameters
extends Object
implements ManagerFactoryParameters

A parameters object for X509KeyManagers that encapsulates a List of KeyStore.Builders.

Since:
1.5
See Also:
KeyStore.Builder, X509KeyManager

Constructor Summary
KeyStoreBuilderParameters(KeyStore.Builder builder)
Construct new KeyStoreBuilderParameters from the specified KeyStore.Builder.
KeyStoreBuilderParameters(List parameters)
Construct new KeyStoreBuilderParameters from a List of KeyStore.Builders.
Method Summary
 List getParameters()
Return the unmodifiable List of the KeyStore.Builders encapsulated by this object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

KeyStoreBuilderParameters

public KeyStoreBuilderParameters(KeyStore.Builder builder)
Construct new KeyStoreBuilderParameters from the specified KeyStore.Builder.

Parameters:
builder - the Builder object
Throws:
NullPointerException - if builder is null

KeyStoreBuilderParameters

public KeyStoreBuilderParameters(List parameters)
Construct new KeyStoreBuilderParameters from a List of KeyStore.Builders. Note that the list is cloned to protect against subsequent modification.

Parameters:
parameters - the List of Builder objects
Throws:
NullPointerException - if parameters is null
IllegalArgumentException - if parameters is an empty list
Method Detail

getParameters

public List getParameters()
Return the unmodifiable List of the KeyStore.Builders encapsulated by this object.

Returns:
the unmodifiable List of the KeyStore.Builders encapsulated by this object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class SSLContext

java.lang.Object
    extended by  javax.net.ssl.SSLContext

public class SSLContext
extends Object

Instances of this class represent a secure socket protocol implementation which acts as a factory for secure socket factories or SSLEngines. This class is initialized with an optional set of key and trust managers and source of secure random bytes.

Since:
1.4

Constructor Summary
protected SSLContext(SSLContextSpi contextSpi, Provider provider, String protocol)
Creates an SSLContext object.
Method Summary
SSLEngine | createSSLEngine() Creates a new SSLEngine using this context.
SSLEngine | createSSLEngine(String peerHost, int peerPort) Creates a new SSLEngine using this context using advisory peer information.
SSLSessionContext | getClientSessionContext() Returns the client session context, which represents the set of SSL sessions available for use during the handshake phase of client-side SSL sockets.
static SSLContext | getDefault() Returns the default SSL context.
SSLParameters | getDefaultSSLParameters() Returns a copy of the SSLParameters indicating the default settings for this SSL context.
static SSLContext | getInstance(String protocol) Returns a SSLContext object that implements the specified secure socket protocol.
static SSLContext | getInstance(String protocol, Provider provider) Returns a SSLContext object that implements the specified secure socket protocol.
static SSLContext | getInstance(String protocol, String provider) Returns a SSLContext object that implements the specified secure socket protocol.
String | getProtocol() Returns the protocol name of this SSLContext object.
Provider | getProvider() Returns the provider of this SSLContext object.
SSLSessionContext | getServerSessionContext() Returns the server session context, which represents the set of SSL sessions available for use during the handshake phase of server-side SSL sockets.
SSLServerSocketFactory | getServerSocketFactory() Returns a ServerSocketFactory object for this context.
SSLSocketFactory | getSocketFactory() Returns a SocketFactory object for this context.
SSLParameters | getSupportedSSLParameters() Returns a copy of the SSLParameters indicating the supported settings for this SSL context.
void | init(KeyManager[] km, TrustManager[] tm, SecureRandom random) Initializes this context.
static void | setDefault(SSLContext context) Sets the default SSL context.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SSLContext

protected SSLContext(SSLContextSpi contextSpi,
                     Provider provider,
                     String protocol)
Creates an SSLContext object.

Parameters:
contextSpi - the delegate
provider - the provider
protocol - the protocol
Method Detail

getDefault

public static SSLContext getDefault()
                             throws NoSuchAlgorithmException
Returns the default SSL context.

If a default context was set using the SSLContext.setDefault() method, it is returned. Otherwise, the first call of this method triggers the call SSLContext.getInstance("Default"). If successful, that object is made the default SSL context and returned.

The default context is immediately usable and does not require initialization.

Returns:
the default SSL context
Throws:
NoSuchAlgorithmException - if the SSLContext.getInstance() call fails
Since:
1.6

setDefault

public static void setDefault(SSLContext context)
Sets the default SSL context. It will be returned by subsequent calls to getDefault(). The default context must be immediately usable and not require initialization.

Parameters:
context - the SSLContext
Throws:
NullPointerException - if context is null
SecurityException - if a security manager exists and its checkPermission method does not allow SSLPermission("setDefaultSSLContext")
Since:
1.6

getInstance

public static SSLContext getInstance(String protocol)
                              throws NoSuchAlgorithmException
Returns a SSLContext object that implements the specified secure socket protocol.

This method traverses the list of registered security Providers, starting with the most preferred Provider. A new SSLContext object encapsulating the SSLContextSpi implementation from the first Provider that supports the specified protocol is returned.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters:
protocol - the standard name of the requested protocol. See Appendix A in the Java Secure Socket Extension Reference Guide for information about standard protocol names.
Returns:
the new SSLContext object.
Throws:
NoSuchAlgorithmException - if no Provider supports a TrustManagerFactorySpi implementation for the specified protocol.
See Also:
Provider

getInstance

public static SSLContext getInstance(String protocol,
                                     String provider)
                              throws NoSuchAlgorithmException,
                                     NoSuchProviderException
Returns a SSLContext object that implements the specified secure socket protocol.

A new SSLContext object encapsulating the SSLContextSpi implementation from the specified provider is returned. The specified provider must be registered in the security provider list.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters:
protocol - the standard name of the requested protocol. See Appendix A in the Java Secure Socket Extension Reference Guide for information about standard protocol names.
provider - the name of the provider.
Returns:
the new SSLContext object.
Throws:
NoSuchAlgorithmException - if a SSLContextSpi implementation for the specified protocol is not available from the specified provider.
NoSuchProviderException - if the specified provider is not registered in the security provider list.
IllegalArgumentException - if the provider name is null or empty.
See Also:
Provider

getInstance

public static SSLContext getInstance(String protocol,
                                     Provider provider)
                              throws NoSuchAlgorithmException
Returns a SSLContext object that implements the specified secure socket protocol.

A new SSLContext object encapsulating the SSLContextSpi implementation from the specified Provider object is returned. Note that the specified Provider object does not have to be registered in the provider list.

Parameters:
protocol - the standard name of the requested protocol. See Appendix A in the Java Secure Socket Extension Reference Guide for information about standard protocol names.
provider - an instance of the provider.
Returns:
the new SSLContext object.
Throws:
NoSuchAlgorithmException - if a KeyManagerFactorySpi implementation for the specified protocol is not available from the specified Provider object.
IllegalArgumentException - if the provider name is null.
See Also:
Provider

getProtocol

public final String getProtocol()
Returns the protocol name of this SSLContext object.

This is the same name that was specified in one of the getInstance calls that created this SSLContext object.

Returns:
the protocol name of this SSLContext object.

getProvider

public final Provider getProvider()
Returns the provider of this SSLContext object.

Returns:
the provider of this SSLContext object

init

public final void init(KeyManager[] km,
                       TrustManager[] tm,
                       SecureRandom random)
                throws KeyManagementException
Initializes this context. Either of the first two parameters may be null in which case the installed security providers will be searched for the highest priority implementation of the appropriate factory. Likewise, the secure random parameter may be null in which case the default implementation will be used.

Only the first instance of a particular key and/or trust manager implementation type in the array is used. (For example, only the first javax.net.ssl.X509KeyManager in the array will be used.)

Parameters:
km - the sources of authentication keys or null
tm - the sources of peer authentication trust decisions or null
random - the source of randomness for this generator or null
Throws:
KeyManagementException - if this operation fails

getSocketFactory

public final SSLSocketFactory getSocketFactory()
Returns a SocketFactory object for this context.

Returns:
the SocketFactory object
Throws:
IllegalStateException - if the SSLContextImpl requires initialization and the init() has not been called

getServerSocketFactory

public final SSLServerSocketFactory getServerSocketFactory()
Returns a ServerSocketFactory object for this context.

Returns:
the ServerSocketFactory object
Throws:
IllegalStateException - if the SSLContextImpl requires initialization and the init() has not been called

createSSLEngine

public final SSLEngine createSSLEngine()
Creates a new SSLEngine using this context.

Applications using this factory method are providing no hints for an internal session reuse strategy. If hints are desired, createSSLEngine(String, int) should be used instead.

Some cipher suites (such as Kerberos) require remote hostname information, in which case this factory method should not be used.

Returns:
the SSLEngine object
Throws:
UnsupportedOperationException - if the underlying provider does not implement the operation.
IllegalStateException - if the SSLContextImpl requires initialization and the init() has not been called
Since:
1.5

createSSLEngine

public final SSLEngine createSSLEngine(String peerHost,
                                       int peerPort)
Creates a new SSLEngine using this context using advisory peer information.

Applications using this factory method are providing hints for an internal session reuse strategy.

Some cipher suites (such as Kerberos) require remote hostname information, in which case peerHost needs to be specified.

Parameters:
peerHost - the non-authoritative name of the host
peerPort - the non-authoritative port
Returns:
the new SSLEngine object
Throws:
UnsupportedOperationException - if the underlying provider does not implement the operation.
IllegalStateException - if the SSLContextImpl requires initialization and the init() has not been called
Since:
1.5

getServerSessionContext

public final SSLSessionContext getServerSessionContext()
Returns the server session context, which represents the set of SSL sessions available for use during the handshake phase of server-side SSL sockets.

This context may be unavailable in some environments, in which case this method returns null. For example, when the underlying SSL provider does not provide an implementation of SSLSessionContext interface, this method returns null. A non-null session context is returned otherwise.

Returns:
server session context bound to this SSL context

getClientSessionContext

public final SSLSessionContext getClientSessionContext()
Returns the client session context, which represents the set of SSL sessions available for use during the handshake phase of client-side SSL sockets.

This context may be unavailable in some environments, in which case this method returns null. For example, when the underlying SSL provider does not provide an implementation of SSLSessionContext interface, this method returns null. A non-null session context is returned otherwise.

Returns:
client session context bound to this SSL context

getDefaultSSLParameters

public final SSLParameters getDefaultSSLParameters()
Returns a copy of the SSLParameters indicating the default settings for this SSL context.

The parameters will always have the ciphersuites and protocols arrays set to non-null values.

Returns:
a copy of the SSLParameters object with the default settings
Throws:
UnsupportedOperationException - if the default SSL parameters could not be obtained.
Since:
1.6

getSupportedSSLParameters

public final SSLParameters getSupportedSSLParameters()
Returns a copy of the SSLParameters indicating the supported settings for this SSL context.

The parameters will always have the ciphersuites and protocols arrays set to non-null values.

Returns:
a copy of the SSLParameters object with the supported settings
Throws:
UnsupportedOperationException - if the supported SSL parameters could not be obtained.
Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLContextSpi

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class SSLContextSpi

java.lang.Object
    extended by  javax.net.ssl.SSLContextSpi

public abstract class SSLContextSpi
extends Object

This class defines the Service Provider Interface (SPI) for the SSLContext class.

All the abstract methods in this class must be implemented by each cryptographic service provider who wishes to supply the implementation of a particular SSL context.

Since:
1.4
See Also:
SSLContext

Constructor Summary
SSLContextSpi()
Method Summary
protected abstract SSLEngine | engineCreateSSLEngine() Creates a new SSLEngine using this context.
protected abstract SSLEngine | engineCreateSSLEngine(String host, int port) Creates a SSLEngine using this context.
protected abstract SSLSessionContext | engineGetClientSessionContext() Returns a client SSLSessionContext object for this context.
protected SSLParameters | engineGetDefaultSSLParameters() Returns a copy of the SSLParameters indicating the default settings for this SSL context.
protected abstract SSLSessionContext | engineGetServerSessionContext() Returns a server SSLSessionContext object for this context.
protected abstract SSLServerSocketFactory | engineGetServerSocketFactory() Returns a ServerSocketFactory object for this context.
protected abstract SSLSocketFactory | engineGetSocketFactory() Returns a SocketFactory object for this context.
protected SSLParameters | engineGetSupportedSSLParameters() Returns a copy of the SSLParameters indicating the maximum supported settings for this SSL context.
protected abstract void | engineInit(KeyManager[] km, TrustManager[] tm, SecureRandom sr) Initializes this context.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SSLContextSpi

public SSLContextSpi()
Method Detail

engineInit

protected abstract void engineInit(KeyManager[] km,
                                   TrustManager[] tm,
                                   SecureRandom sr)
                            throws KeyManagementException
Initializes this context.

Parameters:
km - the sources of authentication keys
tm - the sources of peer authentication trust decisions
sr - the source of randomness
Throws:
KeyManagementException - if this operation fails
See Also:
SSLContext.init(KeyManager [], TrustManager [], SecureRandom)

engineGetSocketFactory

protected abstract SSLSocketFactory engineGetSocketFactory()
Returns a SocketFactory object for this context.

Returns:
the SocketFactory object
Throws:
IllegalStateException - if the SSLContextImpl requires initialization and the engineInit() has not been called
See Also:
SSLContext.getSocketFactory()

engineGetServerSocketFactory

protected abstract SSLServerSocketFactory engineGetServerSocketFactory()
Returns a ServerSocketFactory object for this context.

Returns:
the ServerSocketFactory object
Throws:
IllegalStateException - if the SSLContextImpl requires initialization and the engineInit() has not been called
See Also:
SSLContext.getServerSocketFactory()

engineCreateSSLEngine

protected abstract SSLEngine engineCreateSSLEngine()
Creates a new SSLEngine using this context.

Applications using this factory method are providing no hints for an internal session reuse strategy. If hints are desired, engineCreateSSLEngine(String, int) should be used instead.

Some cipher suites (such as Kerberos) require remote hostname information, in which case this factory method should not be used.

Returns:
the SSLEngine Object
Throws:
IllegalStateException - if the SSLContextImpl requires initialization and the engineInit() has not been called
Since:
1.5
See Also:
SSLContext.createSSLEngine()

engineCreateSSLEngine

protected abstract SSLEngine engineCreateSSLEngine(String host,
                                                   int port)
Creates a SSLEngine using this context.

Applications using this factory method are providing hints for an internal session reuse strategy.

Some cipher suites (such as Kerberos) require remote hostname information, in which case peerHost needs to be specified.

Parameters:
host - the non-authoritative name of the host
port - the non-authoritative port
Returns:
the SSLEngine Object
Throws:
IllegalStateException - if the SSLContextImpl requires initialization and the engineInit() has not been called
Since:
1.5
See Also:
SSLContext.createSSLEngine(String, int)

engineGetServerSessionContext

protected abstract SSLSessionContext engineGetServerSessionContext()
Returns a server SSLSessionContext object for this context.

Returns:
the SSLSessionContext object
See Also:
SSLContext.getServerSessionContext()

engineGetClientSessionContext

protected abstract SSLSessionContext engineGetClientSessionContext()
Returns a client SSLSessionContext object for this context.

Returns:
the SSLSessionContext object
See Also:
SSLContext.getClientSessionContext()

engineGetDefaultSSLParameters

protected SSLParameters engineGetDefaultSSLParameters()
Returns a copy of the SSLParameters indicating the default settings for this SSL context.

The parameters will always have the ciphersuite and protocols arrays set to non-null values.

The default implementation obtains the parameters from an SSLSocket created by calling the SocketFactory.createSocket() method of this context's SocketFactory.

Returns:
a copy of the SSLParameters object with the default settings
Throws:
UnsupportedOperationException - if the default SSL parameters could not be obtained.
Since:
1.6

engineGetSupportedSSLParameters

protected SSLParameters engineGetSupportedSSLParameters()
Returns a copy of the SSLParameters indicating the maximum supported settings for this SSL context.

The parameters will always have the ciphersuite and protocols arrays set to non-null values.

The default implementation obtains the parameters from an SSLSocket created by calling the SocketFactory.createSocket() method of this context's SocketFactory.

Returns:
a copy of the SSLParameters object with the maximum supported settings
Throws:
UnsupportedOperationException - if the supported SSL parameters could not be obtained.
Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLEngine

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class SSLEngine

java.lang.Object
    extended by  javax.net.ssl.SSLEngine

public abstract class SSLEngine
extends Object

A class which enables secure communications using protocols such as the Secure Sockets Layer (SSL) or IETF RFC 2246 "Transport Layer Security" (TLS) protocols, but is transport independent.

The secure communications modes include:

  • Integrity Protection. SSL/TLS protects against modification of messages by an active wiretapper.
  • Authentication. In most modes, SSL/TLS provides peer authentication. Servers are usually authenticated, and clients may be authenticated as requested by servers.
  • Confidentiality (Privacy Protection). In most modes, SSL/TLS encrypts data being sent between client and server. This protects the confidentiality of data, so that passive wiretappers won't see sensitive data such as financial information or personal information of many kinds.
These kinds of protection are specified by a "cipher suite", which is a combination of cryptographic algorithms used by a given SSL connection. During the negotiation process, the two endpoints must agree on a cipher suite that is available in both environments. If there is no such suite in common, no SSL connection can be established, and no data can be exchanged.

The cipher suite used is established by a negotiation process called "handshaking". The goal of this process is to create or rejoin a "session", which may protect many connections over time. After handshaking has completed, you can access session attributes by using the getSession() method.

The SSLSocket class provides much of the same security functionality, but all of the inbound and outbound data is automatically transported using the underlying Socket, which by design uses a blocking model. While this is appropriate for many applications, this model does not provide the scalability required by large servers.

The primary distinction of an SSLEngine is that it operates on inbound and outbound byte streams, independent of the transport mechanism. It is the responsibility of the SSLEngine user to arrange for reliable I/O transport to the peer. By separating the SSL/TLS abstraction from the I/O transport mechanism, the SSLEngine can be used for a wide variety of I/O types, such as non-blocking I/O (polling), selectable non-blocking I/O, Socket and the traditional Input/OutputStreams, local ByteBuffers or byte arrays, future asynchronous I/O models , and so on.

At a high level, the SSLEngine appears thus:

                   app data

                |           ^
                |     |     |
                v     |     |
           +----+-----|-----+----+
           |          |          |
           |       SSL|Engine    |
   wrap()  |          |          |  unwrap()
           | OUTBOUND | INBOUND  |
           |          |          |
           +----+-----|-----+----+
                |     |     ^
                |     |     |
                v           |

                   net data
Application data (also known as plaintext or cleartext) is data which is produced or consumed by an application. Its counterpart is network data, which consists of either handshaking and/or ciphertext (encrypted) data, and destined to be transported via an I/O mechanism. Inbound data is data which has been received from the peer, and outbound data is destined for the peer.

(In the context of an SSLEngine, the term "handshake data" is taken to mean any data exchanged to establish and control a secure connection. Handshake data includes the SSL/TLS messages "alert", "change_cipher_spec," and "handshake.")

There are five distinct phases to an SSLEngine.

  1. Creation - The SSLEngine has been created and initialized, but has not yet been used. During this phase, an application may set any SSLEngine-specific settings (enabled cipher suites, whether the SSLEngine should handshake in client or server mode, and so on). Once handshaking has begun, though, any new settings (except client/server mode, see below) will be used for the next handshake.
  2. Initial Handshake - The initial handshake is a procedure by which the two peers exchange communication parameters until an SSLSession is established. Application data can not be sent during this phase.
  3. Application Data - Once the communication parameters have been established and the handshake is complete, application data may flow through the SSLEngine. Outbound application messages are encrypted and integrity protected, and inbound messages reverse the process.
  4. Rehandshaking - Either side may request a renegotiation of the session at any time during the Application Data phase. New handshaking data can be intermixed among the application data. Before starting the rehandshake phase, the application may reset the SSL/TLS communication parameters such as the list of enabled ciphersuites and whether to use client authentication, but can not change between client/server modes. As before, once handshaking has begun, any new SSLEngine configuration settings will not be used until the next handshake.
  5. Closure - When the connection is no longer needed, the application should close the SSLEngine and should send/receive any remaining messages to the peer before closing the underlying transport mechanism. Once an engine is closed, it is not reusable: a new SSLEngine must be created.
An SSLEngine is created by calling SSLContext.createSSLEngine() from an initialized SSLContext. Any configuration parameters should be set before making the first call to wrap(), unwrap(), or beginHandshake(). These methods all trigger the initial handshake.

Data moves through the engine by calling wrap() or unwrap() on outbound or inbound data, respectively. Depending on the state of the SSLEngine, a wrap() call may consume application data from the source buffer and may produce network data in the destination buffer. The outbound data may contain application and/or handshake data. A call to unwrap() will examine the source buffer and may advance the handshake if the data is handshaking information, or may place application data in the destination buffer if the data is application. The state of the underlying SSL/TLS algorithm will determine when data is consumed and produced.

Calls to wrap() and unwrap() return an SSLEngineResult which indicates the status of the operation, and (optionally) how to interact with the engine to make progress.

The SSLEngine produces/consumes complete SSL/TLS packets only, and does not store application data internally between calls to wrap()/unwrap(). Thus input and output ByteBuffers must be sized appropriately to hold the maximum record that can be produced. Calls to SSLSession.getPacketBufferSize() and SSLSession.getApplicationBufferSize() should be used to determine the appropriate buffer sizes. The size of the outbound application data buffer generally does not matter. If buffer conditions do not allow for the proper consumption/production of data, the application must determine (via SSLEngineResult) and correct the problem, and then try the call again.

For example, unwrap() will return a SSLEngineResult.Status.BUFFER_OVERFLOW result if the engine determines that there is not enough destination buffer space available. Applications should call SSLSession.getApplicationBufferSize() and compare that value with the space available in the destination buffer, enlarging the buffer if necessary. Similarly, if unwrap() were to return a SSLEngineResult.Status.BUFFER_UNDERFLOW, the application should call SSLSession.getPacketBufferSize() to ensure that the source buffer has enough room to hold a record (enlarging if necessary), and then obtain more inbound data.

   SSLEngineResult r = engine.unwrap(src, dst);
   switch (r.getStatus()) {
   BUFFER_OVERFLOW:
       // Could attempt to drain the dst buffer of any already obtained
       // data, but we'll just increase it to the size needed.
       int appSize = engine.getSession().getApplicationBufferSize();
       ByteBuffer b = ByteBuffer.allocate(appSize + dst.position());
       dst.flip();
       b.put(dst);
       dst = b;
       // retry the operation.
       break;
   BUFFER_UNDERFLOW:
       int netSize = engine.getSession().getPacketBufferSize();
       // Resize buffer if needed.
       if (netSize > dst.capacity()) {
           ByteBuffer b = ByteBuffer.allocate(netSize);
           src.flip();
           b.put(src);
           src = b;
       }
       // Obtain more inbound network data for src,
       // then retry the operation.
       break;
   // other cases: CLOSED, OK.
   }

Unlike SSLSocket, all methods of SSLEngine are non-blocking. SSLEngine implementations may require the results of tasks that may take an extended period of time to complete, or may even block. For example, a TrustManager may need to connect to a remote certificate validation service, or a KeyManager might need to prompt a user to determine which certificate to use as part of client authentication. Additionally, creating cryptographic signatures and verifying them can be slow, seemingly blocking.

For any operation which may potentially block, the SSLEngine will create a Runnable delegated task. When SSLEngineResult indicates that a delegated task result is needed, the application must call getDelegatedTask() to obtain an outstanding delegated task and call its run() method (possibly using a different thread depending on the compute strategy). The application should continue obtaining delegated tasks until no more exist, and try the original operation again.

At the end of a communication session, applications should properly close the SSL/TLS link. The SSL/TLS protocols have closure handshake messages, and these messages should be communicated to the peer before releasing the SSLEngine and closing the underlying transport mechanism. A close can be initiated by one of: an SSLException, an inbound closure handshake message, or one of the close methods. In all cases, closure handshake messages are generated by the engine, and wrap() should be repeatedly called until the resulting SSLEngineResult's status returns "CLOSED", or isOutboundDone() returns true. All data obtained from the wrap() method should be sent to the peer.

closeOutbound() is used to signal the engine that the application will not be sending any more data.

A peer will signal its intent to close by sending its own closure handshake message. After this message has been received and processed by the local SSLEngine's unwrap() call, the application can detect the close by calling unwrap() and looking for a SSLEngineResult with status "CLOSED", or if isInboundDone() returns true. If for some reason the peer closes the communication link without sending the proper SSL/TLS closure message, the application can detect the end-of-stream and can signal the engine via closeInbound() that there will no more inbound messages to process. Some applications might choose to require orderly shutdown messages from a peer, in which case they can check that the closure was generated by a handshake message and not by an end-of-stream condition.

There are two groups of cipher suites which you will need to know about when managing cipher suites:

  • Supported cipher suites: all the suites which are supported by the SSL implementation. This list is reported using getSupportedCipherSuites().
  • Enabled cipher suites, which may be fewer than the full set of supported suites. This group is set using the setEnabledCipherSuites(String []) method, and queried using the getEnabledCipherSuites() method. Initially, a default set of cipher suites will be enabled on a new engine that represents the minimum suggested configuration.
Implementation defaults require that only cipher suites which authenticate servers and provide confidentiality be enabled by default. Only if both sides explicitly agree to unauthenticated and/or non-private (unencrypted) communications will such a cipher suite be selected.

Each SSL/TLS connection must have one client and one server, thus each endpoint must decide which role to assume. This choice determines who begins the handshaking process as well as which type of messages should be sent by each party. The method setUseClientMode(boolean) configures the mode. Once the initial handshaking has started, an SSLEngine can not switch between client and server modes, even when performing renegotiations.

Applications might choose to process delegated tasks in different threads. When an SSLEngine is created, the current AccessControlContext is saved. All future delegated tasks will be processed using this context: that is, all access control decisions will be made using the context captured at engine creation.

Concurrency Notes: There are two concurrency issues to be aware of:
  1. The wrap() and unwrap() methods may execute concurrently of each other.
  2. The SSL/TLS protocols employ ordered packets. Applications must take care to ensure that generated packets are delivered in sequence. If packets arrive out-of-order, unexpected or fatal results may occur.

    For example:

                    synchronized (outboundLock) {
                    sslEngine.wrap(src, dst);
                    outboundQueue.put(dst);
                }
    As a corollary, two threads must not attempt to call the same method (either wrap() or unwrap()) concurrently, because there is no way to guarantee the eventual packet ordering.

Since:
1.5
See Also:
SSLContext, SSLSocket, SSLServerSocket, SSLSession, Socket

Constructor Summary
protected | SSLEngine() Constructor for an SSLEngine providing no hints for an internal session reuse strategy.
protected | SSLEngine(String peerHost, int peerPort) Constructor for an SSLEngine.
Method Summary
abstract  void beginHandshake()
Initiates handshaking (initial or renegotiation) on this SSLEngine.
abstract  void closeInbound()
Signals that no more inbound network data will be sent to this SSLEngine.
abstract  void closeOutbound()
Signals that no more outbound application data will be sent on this SSLEngine.
abstract  Runnable getDelegatedTask()
Returns a delegated Runnable task for this SSLEngine.
abstract  String[] getEnabledCipherSuites()
Returns the names of the SSL cipher suites which are currently enabled for use on this engine.
abstract  String[] getEnabledProtocols()
Returns the names of the protocol versions which are currently enabled for use with this SSLEngine.
abstract  boolean getEnableSessionCreation()
Returns true if new SSL sessions may be established by this engine.
abstract  SSLEngineResult.HandshakeStatus getHandshakeStatus()
Returns the current handshake status for this SSLEngine.
abstract  boolean getNeedClientAuth()
Returns true if the engine will require client authentication.
 String getPeerHost()
Returns the host name of the peer.
 int getPeerPort()
Returns the port number of the peer.
abstract  SSLSession getSession()
Returns the SSLSession in use in this SSLEngine.
 SSLParameters getSSLParameters()
Returns the SSLParameters in effect for this SSLEngine.
abstract  String[] getSupportedCipherSuites()
Returns the names of the cipher suites which could be enabled for use on this engine.
abstract  String[] getSupportedProtocols()
Returns the names of the protocols which could be enabled for use with this SSLEngine.
abstract  boolean getUseClientMode()
Returns true if the engine is set to use client mode when handshaking.
abstract  boolean getWantClientAuth()
Returns true if the engine will request client authentication.
abstract  boolean isInboundDone()
Returns whether unwrap(ByteBuffer, ByteBuffer) will accept any more inbound data messages.
abstract  boolean isOutboundDone()
Returns whether wrap(ByteBuffer, ByteBuffer) will produce any more outbound data messages.
abstract  void setEnabledCipherSuites(String[] suites)
Sets the cipher suites enabled for use on this engine.
abstract  void setEnabledProtocols(String[] protocols)
Set the protocol versions enabled for use on this engine.
abstract  void setEnableSessionCreation(boolean flag)
Controls whether new SSL sessions may be established by this engine.
abstract  void setNeedClientAuth(boolean need)
Configures the engine to require client authentication.
 void setSSLParameters(SSLParameters params)
Applies SSLParameters to this engine.
abstract  void setUseClientMode(boolean mode)
Configures the engine to use client (or server) mode when handshaking.
abstract  void setWantClientAuth(boolean want)
Configures the engine to request client authentication.
 SSLEngineResult unwrap(ByteBuffer src, ByteBuffer dst)
Attempts to decode SSL/TLS network data into a plaintext application data buffer.
 SSLEngineResult unwrap(ByteBuffer src, ByteBuffer[] dsts)
Attempts to decode SSL/TLS network data into a sequence of plaintext application data buffers.
abstract  SSLEngineResult unwrap(ByteBuffer src, ByteBuffer[] dsts, int offset, int length)
Attempts to decode SSL/TLS network data into a subsequence of plaintext application data buffers.
 SSLEngineResult wrap(ByteBuffer[] srcs, ByteBuffer dst)
Attempts to encode plaintext bytes from a sequence of data buffers into SSL/TLS network data.
abstract  SSLEngineResult wrap(ByteBuffer[] srcs, int offset, int length, ByteBuffer dst)
Attempts to encode plaintext bytes from a subsequence of data buffers into SSL/TLS network data.
 SSLEngineResult wrap(ByteBuffer src, ByteBuffer dst)
Attempts to encode a buffer of plaintext application data into SSL/TLS network data.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SSLEngine

protected SSLEngine()
Constructor for an SSLEngine providing no hints for an internal session reuse strategy.

See Also:
SSLContext.createSSLEngine(), SSLSessionContext

SSLEngine

protected SSLEngine(String peerHost,
                    int peerPort)
Constructor for an SSLEngine.

SSLEngine implementations may use the peerHost and peerPort parameters as hints for their internal session reuse strategy.

Some cipher suites (such as Kerberos) require remote hostname information. Implementations of this class should use this constructor to use Kerberos.

The parameters are not authenticated by the SSLEngine.

Parameters:
peerHost - the name of the peer host
peerPort - the port number of the peer
See Also:
SSLContext.createSSLEngine(String, int), SSLSessionContext
Method Detail

getPeerHost

public String getPeerHost()
Returns the host name of the peer.

Note that the value is not authenticated, and should not be relied upon.

Returns:
the host name of the peer, or null if nothing is available.

getPeerPort

public int getPeerPort()
Returns the port number of the peer.

Note that the value is not authenticated, and should not be relied upon.

Returns:
the port number of the peer, or -1 if nothing is available.

wrap

public SSLEngineResult wrap(ByteBuffer src,
                            ByteBuffer dst)
                     throws SSLException
Attempts to encode a buffer of plaintext application data into SSL/TLS network data.

An invocation of this method behaves in exactly the same manner as the invocation:

 engine.wrap(new ByteBuffer [] { src }, 0, 1, dst);

Parameters:
src - a ByteBuffer containing outbound application data
dst - a ByteBuffer to hold outbound network data

Returns:
an SSLEngineResult describing the result
                of this operation.

Throws:

SSLException - A problem was encountered while processing the
                data that caused the SSLEngine to abort.
                See the class description for more information on
                engine closure.

ReadOnlyBufferException - if the dst buffer is read-only.

IllegalArgumentException - if either src or dst
                is null.

IllegalStateException - if the client/server mode
                has not yet been set.
See Also:
wrap(ByteBuffer [], int, int, ByteBuffer)

wrap

public SSLEngineResult wrap(ByteBuffer[] srcs,
                            ByteBuffer dst)
                     throws SSLException
Attempts to encode plaintext bytes from a sequence of data buffers into SSL/TLS network data.

An invocation of this method behaves in exactly the same manner as the invocation:

 engine.wrap(srcs, 0, srcs.length, dst);

Parameters:
srcs - an array of ByteBuffers containing the
                outbound application data
dst - a ByteBuffer to hold outbound network data

Returns:
an SSLEngineResult describing the result
                of this operation.

Throws:

SSLException - A problem was encountered while processing the
                data that caused the SSLEngine to abort.
                See the class description for more information on
                engine closure.

ReadOnlyBufferException - if the dst buffer is read-only.

IllegalArgumentException - if either srcs or dst
                is null, or if any element in srcs is null.

IllegalStateException - if the client/server mode
                has not yet been set.
See Also:
wrap(ByteBuffer [], int, int, ByteBuffer)

wrap

public abstract SSLEngineResult wrap(ByteBuffer[] srcs,
                                     int offset,
                                     int length,
                                     ByteBuffer dst)
                              throws SSLException
Attempts to encode plaintext bytes from a subsequence of data buffers into SSL/TLS network data. This "gathering" operation encodes, in a single invocation, a sequence of bytes from one or more of a given sequence of buffers. Gathering wraps are often useful when implementing network protocols or file formats that, for example, group data into segments consisting of one or more fixed-length headers followed by a variable-length body. See GatheringByteChannel for more information on gathering, and GatheringByteChannel.write(ByteBuffer[], int, int) for more information on the subsequence behavior.

Depending on the state of the SSLEngine, this method may produce network data without consuming any application data (for example, it may generate handshake data.)

The application is responsible for reliably transporting the network data to the peer, and for ensuring that data created by multiple calls to wrap() is transported in the same order in which it was generated. The application must properly synchronize multiple calls to this method.

If this SSLEngine has not yet started its initial handshake, this method will automatically start the handshake.

This method will attempt to produce one SSL/TLS packet, and will consume as much source data as possible, but will never consume more than the sum of the bytes remaining in each buffer. Each ByteBuffer's position is updated to reflect the amount of data consumed or produced. The limits remain the same.

The underlying memory used by the srcs and dst ByteBuffers must not be the same.

See the class description for more information on engine closure.

Parameters:
srcs - an array of ByteBuffers containing the outbound application data
offset - The offset within the buffer array of the first buffer from which bytes are to be retrieved; it must be non-negative and no larger than srcs.length
length - The maximum number of buffers to be accessed; it must be non-negative and no larger than srcs.length - offset
dst - a ByteBuffer to hold outbound network data
Returns:
an SSLEngineResult describing the result of this operation.
Throws:
SSLException - A problem was encountered while processing the data that caused the SSLEngine to abort. See the class description for more information on engine closure.
IndexOutOfBoundsException - if the preconditions on the offset and length parameters do not hold.
ReadOnlyBufferException - if the dst buffer is read-only.
IllegalArgumentException - if either srcs or dst is null, or if any element in the srcs subsequence specified is null.
IllegalStateException - if the client/server mode has not yet been set.
See Also:
GatheringByteChannel, GatheringByteChannel.write( ByteBuffer[], int, int)

unwrap

public SSLEngineResult unwrap(ByteBuffer src,
                              ByteBuffer dst)
                       throws SSLException
Attempts to decode SSL/TLS network data into a plaintext application data buffer.

An invocation of this method behaves in exactly the same manner as the invocation:

 engine.unwrap(src, new ByteBuffer [] { dst }, 0, 1);

Parameters:
src - a ByteBuffer containing inbound network data.
dst - a ByteBuffer to hold inbound application data.

Returns:
an SSLEngineResult describing the result
                of this operation.

Throws:

SSLException - A problem was encountered while processing the
                data that caused the SSLEngine to abort.
                See the class description for more information on
                engine closure.

ReadOnlyBufferException - if the dst buffer is read-only.

IllegalArgumentException - if either src or dst
                is null.

IllegalStateException - if the client/server mode
                has not yet been set.
See Also:
unwrap(ByteBuffer, ByteBuffer [], int, int)

unwrap

public SSLEngineResult unwrap(ByteBuffer src,
                              ByteBuffer[] dsts)
                       throws SSLException
Attempts to decode SSL/TLS network data into a sequence of plaintext application data buffers.

An invocation of this method behaves in exactly the same manner as the invocation:

 engine.unwrap(src, dsts, 0, dsts.length);

Parameters:
src - a ByteBuffer containing inbound network data.
dsts - an array of ByteBuffers to hold inbound
                application data.

Returns:
an SSLEngineResult describing the result
                of this operation.

Throws:

SSLException - A problem was encountered while processing the
                data that caused the SSLEngine to abort.
                See the class description for more information on
                engine closure.

ReadOnlyBufferException - if any of the dst buffers are read-only.

IllegalArgumentException - if either src or dsts
                is null, or if any element in dsts is null.

IllegalStateException - if the client/server mode
                has not yet been set.
See Also:
unwrap(ByteBuffer, ByteBuffer [], int, int)

unwrap

public abstract SSLEngineResult unwrap(ByteBuffer src,
                                       ByteBuffer[] dsts,
                                       int offset,
                                       int length)
                                throws SSLException
Attempts to decode SSL/TLS network data into a subsequence of plaintext application data buffers. This "scattering" operation decodes, in a single invocation, a sequence of bytes into one or more of a given sequence of buffers. Scattering unwraps are often useful when implementing network protocols or file formats that, for example, group data into segments consisting of one or more fixed-length headers followed by a variable-length body. See ScatteringByteChannel for more information on scattering, and ScatteringByteChannel.read(ByteBuffer[], int, int) for more information on the subsequence behavior.

Depending on the state of the SSLEngine, this method may consume network data without producing any application data (for example, it may consume handshake data.)

The application is responsible for reliably obtaining the network data from the peer, and for invoking unwrap() on the data in the order it was received. The application must properly synchronize multiple calls to this method.

If this SSLEngine has not yet started its initial handshake, this method will automatically start the handshake.

This method will attempt to consume one complete SSL/TLS network packet, but will never consume more than the sum of the bytes remaining in the buffers. Each ByteBuffer's position is updated to reflect the amount of data consumed or produced. The limits remain the same.

The underlying memory used by the src and dsts ByteBuffers must not be the same.

The inbound network buffer may be modified as a result of this call: therefore if the network data packet is required for some secondary purpose, the data should be duplicated before calling this method. Note: the network data will not be useful to a second SSLEngine, as each SSLEngine contains unique random state which influences the SSL/TLS messages.

See the class description for more information on engine closure.

Parameters:
src - a ByteBuffer containing inbound network data.
dsts - an array of ByteBuffers to hold inbound application data.
offset - The offset within the buffer array of the first buffer from which bytes are to be transferred; it must be non-negative and no larger than dsts.length.
length - The maximum number of buffers to be accessed; it must be non-negative and no larger than dsts.length - offset.
Returns:
an SSLEngineResult describing the result of this operation.
Throws:
SSLException - A problem was encountered while processing the data that caused the SSLEngine to abort. See the class description for more information on engine closure.
IndexOutOfBoundsException - If the preconditions on the offset and length parameters do not hold.
ReadOnlyBufferException - if any of the dst buffers are read-only.
IllegalArgumentException - if either src or dsts is null, or if any element in the dsts subsequence specified is null.
IllegalStateException - if the client/server mode has not yet been set.
See Also:
ScatteringByteChannel, ScatteringByteChannel.read( ByteBuffer[], int, int)

getDelegatedTask

public abstract Runnable getDelegatedTask()
Returns a delegated Runnable task for this SSLEngine.

SSLEngine operations may require the results of operations that block, or may take an extended period of time to complete. This method is used to obtain an outstanding Runnable operation (task). Each task must be assigned a thread (possibly the current) to perform the run operation. Once the run method returns, the Runnable object is no longer needed and may be discarded.

Delegated tasks run in the AccessControlContext in place when this object was created.

A call to this method will return each outstanding task exactly once.

Multiple delegated tasks can be run in parallel.

Returns:
a delegated Runnable task, or null if none are available.

closeInbound

public abstract void closeInbound()
                           throws SSLException
Signals that no more inbound network data will be sent to this SSLEngine.

If the application initiated the closing process by calling closeOutbound(), under some circumstances it is not required that the initiator wait for the peer's corresponding close message. (See section 7.2.1 of the TLS specification (RFC 2246) for more information on waiting for closure alerts.) In such cases, this method need not be called.

But if the application did not initiate the closure process, or if the circumstances above do not apply, this method should be called whenever the end of the SSL/TLS data stream is reached. This ensures closure of the inbound side, and checks that the peer followed the SSL/TLS close procedure properly, thus detecting possible truncation attacks.

This method is idempotent: if the inbound side has already been closed, this method does not do anything.

wrap() should be called to flush any remaining handshake data.

Throws:
SSLException - if this engine has not received the proper SSL/TLS close notification message from the peer.
See Also:
isInboundDone(), isOutboundDone()

isInboundDone

public abstract boolean isInboundDone()
Returns whether unwrap(ByteBuffer, ByteBuffer) will accept any more inbound data messages.

Returns:
true if the SSLEngine will not consume anymore network data (and by implication, will not produce any more application data.)
See Also:
closeInbound()

closeOutbound

public abstract void closeOutbound()
Signals that no more outbound application data will be sent on this SSLEngine.

This method is idempotent: if the outbound side has already been closed, this method does not do anything.

wrap(ByteBuffer, ByteBuffer) should be called to flush any remaining handshake data.

See Also:
isOutboundDone()

isOutboundDone

public abstract boolean isOutboundDone()
Returns whether wrap(ByteBuffer, ByteBuffer) will produce any more outbound data messages.

Note that during the closure phase, a SSLEngine may generate handshake closure data that must be sent to the peer. wrap() must be called to generate this data. When this method returns true, no more outbound data will be created.

Returns:
true if the SSLEngine will not produce any more network data
See Also:
closeOutbound(), closeInbound()

getSupportedCipherSuites

public abstract String[] getSupportedCipherSuites()
Returns the names of the cipher suites which could be enabled for use on this engine. Normally, only a subset of these will actually be enabled by default, since this list may include cipher suites which do not meet quality of service requirements for those defaults. Such cipher suites might be useful in specialized applications.

Returns:
an array of cipher suite names
See Also:
getEnabledCipherSuites(), setEnabledCipherSuites(String [])

getEnabledCipherSuites

public abstract String[] getEnabledCipherSuites()
Returns the names of the SSL cipher suites which are currently enabled for use on this engine. When an SSLEngine is first created, all enabled cipher suites support a minimum quality of service. Thus, in some environments this value might be empty.

Even if a suite has been enabled, it might never be used. (For example, the peer does not support it, the requisite certificates/private keys for the suite are not available, or an anonymous suite is enabled but authentication is required.)

Returns:
an array of cipher suite names
See Also:
getSupportedCipherSuites(), setEnabledCipherSuites(String [])

setEnabledCipherSuites

public abstract void setEnabledCipherSuites(String[] suites)
Sets the cipher suites enabled for use on this engine.

Each cipher suite in the suites parameter must have been listed by getSupportedCipherSuites(), or the method will fail. Following a successful call to this method, only suites listed in the suites parameter are enabled for use.

See getEnabledCipherSuites() for more information on why a specific cipher suite may never be used on a engine.

Parameters:
suites - Names of all the cipher suites to enable
Throws:
IllegalArgumentException - when one or more of the ciphers named by the parameter is not supported, or when the parameter is null.
See Also:
getSupportedCipherSuites(), getEnabledCipherSuites()

getSupportedProtocols

public abstract String[] getSupportedProtocols()
Returns the names of the protocols which could be enabled for use with this SSLEngine.

Returns:
an array of protocols supported

getEnabledProtocols

public abstract String[] getEnabledProtocols()
Returns the names of the protocol versions which are currently enabled for use with this SSLEngine.

Returns:
an array of protocols
See Also:
setEnabledProtocols(String [])

setEnabledProtocols

public abstract void setEnabledProtocols(String[] protocols)
Set the protocol versions enabled for use on this engine.

The protocols must have been listed by getSupportedProtocols() as being supported. Following a successful call to this method, only protocols listed in the protocols parameter are enabled for use.

Parameters:
protocols - Names of all the protocols to enable.
Throws:
IllegalArgumentException - when one or more of the protocols named by the parameter is not supported or when the protocols parameter is null.
See Also:
getEnabledProtocols()

getSession

public abstract SSLSession getSession()
Returns the SSLSession in use in this SSLEngine.

These can be long lived, and frequently correspond to an entire login session for some user. The session specifies a particular cipher suite which is being actively used by all connections in that session, as well as the identities of the session's client and server.

Unlike SSLSocket.getSession() this method does not block until handshaking is complete.

Until the initial handshake has completed, this method returns a session object which reports an invalid cipher suite of "SSL_NULL_WITH_NULL_NULL".

Returns:
the SSLSession for this SSLEngine
See Also:
SSLSession

beginHandshake

public abstract void beginHandshake()
                             throws SSLException
Initiates handshaking (initial or renegotiation) on this SSLEngine.

This method is not needed for the initial handshake, as the wrap() and unwrap() methods will implicitly call this method if handshaking has not already begun.

Note that the peer may also request a session renegotiation with this SSLEngine by sending the appropriate session renegotiate handshake message.

Unlike the SSLSocket#startHandshake() method, this method does not block until handshaking is completed.

To force a complete SSL/TLS session renegotiation, the current session should be invalidated prior to calling this method.

Some protocols may not support multiple handshakes on an existing engine and may throw an SSLException.

Throws:
SSLException - if a problem was encountered while signaling the SSLEngine to begin a new handshake. See the class description for more information on engine closure.
IllegalStateException - if the client/server mode has not yet been set.
See Also:
SSLSession.invalidate()

getHandshakeStatus

public abstract SSLEngineResult.HandshakeStatus getHandshakeStatus()
Returns the current handshake status for this SSLEngine.

Returns:
the current SSLEngineResult.HandshakeStatus.

setUseClientMode

public abstract void setUseClientMode(boolean mode)
Configures the engine to use client (or server) mode when handshaking.

This method must be called before any handshaking occurs. Once handshaking has begun, the mode can not be reset for the life of this engine.

Servers normally authenticate themselves, and clients are not required to do so.

Parameters:
mode - true if the engine should start its handshaking in "client" mode
Throws:
IllegalArgumentException - if a mode change is attempted after the initial handshake has begun.
See Also:
getUseClientMode()

getUseClientMode

public abstract boolean getUseClientMode()
Returns true if the engine is set to use client mode when handshaking.

Returns:
true if the engine should do handshaking in "client" mode
See Also:
setUseClientMode(boolean)

setNeedClientAuth

public abstract void setNeedClientAuth(boolean need)
Configures the engine to require client authentication. This option is only useful for engines in the server mode.

An engine's client authentication setting is one of the following:

  • client authentication required
  • client authentication requested
  • no client authentication desired

Unlike setWantClientAuth(boolean), if this option is set and the client chooses not to provide authentication information about itself, the negotiations will stop and the engine will begin its closure procedure.

Calling this method overrides any previous setting made by this method or setWantClientAuth(boolean).

Parameters:
need - set to true if client authentication is required, or false if no client authentication is desired.
See Also:
getNeedClientAuth(), setWantClientAuth(boolean), getWantClientAuth(), setUseClientMode(boolean)

getNeedClientAuth

public abstract boolean getNeedClientAuth()
Returns true if the engine will require client authentication. This option is only useful to engines in the server mode.

Returns:
true if client authentication is required, or false if no client authentication is desired.
See Also:
setNeedClientAuth(boolean), setWantClientAuth(boolean), getWantClientAuth(), setUseClientMode(boolean)

setWantClientAuth

public abstract void setWantClientAuth(boolean want)
Configures the engine to request client authentication. This option is only useful for engines in the server mode.

An engine's client authentication setting is one of the following:

  • client authentication required
  • client authentication requested
  • no client authentication desired

Unlike setNeedClientAuth(boolean), if this option is set and the client chooses not to provide authentication information about itself, the negotiations will continue.

Calling this method overrides any previous setting made by this method or setNeedClientAuth(boolean).

Parameters:
want - set to true if client authentication is requested, or false if no client authentication is desired.
See Also:
getWantClientAuth(), setNeedClientAuth(boolean), getNeedClientAuth(), setUseClientMode(boolean)

getWantClientAuth

public abstract boolean getWantClientAuth()
Returns true if the engine will request client authentication. This option is only useful for engines in the server mode.

Returns:
true if client authentication is requested, or false if no client authentication is desired.
See Also:
setNeedClientAuth(boolean), getNeedClientAuth(), setWantClientAuth(boolean), setUseClientMode(boolean)

setEnableSessionCreation

public abstract void setEnableSessionCreation(boolean flag)
Controls whether new SSL sessions may be established by this engine. If session creations are not allowed, and there are no existing sessions to resume, there will be no successful handshaking.

Parameters:
flag - true indicates that sessions may be created; this is the default. false indicates that an existing session must be resumed
See Also:
getEnableSessionCreation()

getEnableSessionCreation

public abstract boolean getEnableSessionCreation()
Returns true if new SSL sessions may be established by this engine.

Returns:
true indicates that sessions may be created; this is the default. false indicates that an existing session must be resumed
See Also:
setEnableSessionCreation(boolean)

getSSLParameters

public SSLParameters getSSLParameters()
Returns the SSLParameters in effect for this SSLEngine. The ciphersuites and protocols of the returned SSLParameters are always non-null.

Returns:
the SSLParameters in effect for this SSLEngine.
Since:
1.6

setSSLParameters

public void setSSLParameters(SSLParameters params)
Applies SSLParameters to this engine.

This means:

  • if params.getCipherSuites() is non-null, setEnabledCipherSuites() is called with that value
  • if params.getProtocols() is non-null, setEnabledProtocols() is called with that value
  • if params.getNeedClientAuth() or params.getWantClientAuth() return true, setNeedClientAuth(true) and setWantClientAuth(true) are called, respectively; otherwise setWantClientAuth(false) is called.

Parameters:
params - the parameters
Throws:
IllegalArgumentException - if the setEnabledCipherSuites() or the setEnabledProtocols() call fails
Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLEngineResult

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class SSLEngineResult

java.lang.Object
    extended by  javax.net.ssl.SSLEngineResult

public class SSLEngineResult
extends Object

An encapsulation of the result state produced by SSLEngine I/O calls.

A SSLEngine provides a means for establishing secure communication sessions between two peers. SSLEngine operations typically consume bytes from an input buffer and produce bytes in an output buffer. This class provides operational result values describing the state of the SSLEngine, including indications of what operations are needed to finish an ongoing handshake. Lastly, it reports the number of bytes consumed and produced as a result of this operation.

Since:
1.5
See Also:
SSLEngine, SSLEngine.wrap(ByteBuffer, ByteBuffer), SSLEngine.unwrap(ByteBuffer, ByteBuffer)

Nested Class Summary
static class | SSLEngineResult.HandshakeStatus An SSLEngineResult enum describing the current handshaking state of this SSLEngine.
static class | SSLEngineResult.Status An SSLEngineResult enum describing the overall result of the SSLEngine operation.
Constructor Summary
SSLEngineResult(SSLEngineResult.Status status, SSLEngineResult.HandshakeStatus handshakeStatus, int bytesConsumed, int bytesProduced)
Initializes a new instance of this class.
Method Summary
int | bytesConsumed() Returns the number of bytes consumed from the input buffer.
int | bytesProduced() Returns the number of bytes written to the output buffer.
SSLEngineResult.HandshakeStatus | getHandshakeStatus() Gets the handshake status of this SSLEngine operation.
SSLEngineResult.Status | getStatus() Gets the return value of this SSLEngine operation.
String | toString() Returns a String representation of this object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SSLEngineResult

public SSLEngineResult(SSLEngineResult.Status status,
                       SSLEngineResult.HandshakeStatus handshakeStatus,
                       int bytesConsumed,
                       int bytesProduced)
Initializes a new instance of this class.

Parameters:
status - the return value of the operation.
handshakeStatus - the current handshaking status.
bytesConsumed - the number of bytes consumed from the source ByteBuffer
bytesProduced - the number of bytes placed into the destination ByteBuffer
Throws:
IllegalArgumentException - if the status or handshakeStatus arguments are null, or if <<code>bytesConsumed or bytesProduced is negative.
Method Detail

getStatus

public final SSLEngineResult.Status getStatus()
Gets the return value of this SSLEngine operation.

Returns:
the return value

getHandshakeStatus

public final SSLEngineResult.HandshakeStatus getHandshakeStatus()
Gets the handshake status of this SSLEngine operation.

Returns:
the handshake status

bytesConsumed

public final int bytesConsumed()
Returns the number of bytes consumed from the input buffer.

Returns:
the number of bytes consumed.

bytesProduced

public final int bytesProduced()
Returns the number of bytes written to the output buffer.

Returns:
the number of bytes produced

toString

public String toString()
Returns a String representation of this object.

Overrides:
toString in class Object
Returns:
a string representation of the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLEngineResult.HandshakeStatus

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.net.ssl
Enum SSLEngineResult.HandshakeStatus

java.lang.Object
    extended by  java.lang.Enum<SSLEngineResult.HandshakeStatus>
        extended by  javax.net.ssl.SSLEngineResult.HandshakeStatus
All Implemented Interfaces:
Serializable, Comparable<SSLEngineResult.HandshakeStatus>
Enclosing class:
SSLEngineResult
public static enum SSLEngineResult.HandshakeStatus
extends Enum<SSLEngineResult.HandshakeStatus>

An SSLEngineResult enum describing the current handshaking state of this SSLEngine.

Since:
1.5

Enum Constant Summary
FINISHED
The SSLEngine has just finished handshaking.
NEED_TASK
The SSLEngine needs the results of one (or more) delegated tasks before handshaking can continue.
NEED_UNWRAP
The SSLEngine needs to receive data from the remote side before handshaking can continue.
NEED_WRAP
The SSLEngine must send data to the remote side before handshaking can continue, so SSLEngine.wrap() should be called.
NOT_HANDSHAKING
The SSLEngine is not currently handshaking.
Method Summary
static SSLEngineResult.HandshakeStatus | valueOf(String name) Returns the enum constant of this type with the specified name.
static SSLEngineResult.HandshakeStatus[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

NOT_HANDSHAKING

public static final SSLEngineResult.HandshakeStatus NOT_HANDSHAKING
The SSLEngine is not currently handshaking.

FINISHED

public static final SSLEngineResult.HandshakeStatus FINISHED
The SSLEngine has just finished handshaking.

This value is only generated by a call to SSLEngine.wrap()/unwrap() when that call finishes a handshake. It is never generated by SSLEngine.getHandshakeStatus().

See Also:
SSLEngine.wrap(ByteBuffer, ByteBuffer),
SSLEngine.unwrap(ByteBuffer, ByteBuffer),
SSLEngine.getHandshakeStatus()

NEED_TASK

public static final SSLEngineResult.HandshakeStatus NEED_TASK
The SSLEngine needs the results of one (or more) delegated tasks before handshaking can continue.

See Also:
SSLEngine.getDelegatedTask()

NEED_WRAP

public static final SSLEngineResult.HandshakeStatus NEED_WRAP
The SSLEngine must send data to the remote side before handshaking can continue, so SSLEngine.wrap() should be called.

See Also:
SSLEngine.wrap(ByteBuffer, ByteBuffer)

NEED_UNWRAP

public static final SSLEngineResult.HandshakeStatus NEED_UNWRAP
The SSLEngine needs to receive data from the remote side before handshaking can continue.

Method Detail

values

public static SSLEngineResult.HandshakeStatus[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (SSLEngineResult.HandshakeStatus c : SSLEngineResult.HandshakeStatus.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static SSLEngineResult.HandshakeStatus valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


SSLEngineResult.Status

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.net.ssl
Enum SSLEngineResult.Status

java.lang.Object
    extended by  java.lang.Enum<SSLEngineResult.Status>
        extended by  javax.net.ssl.SSLEngineResult.Status
All Implemented Interfaces:
Serializable, Comparable<SSLEngineResult.Status>
Enclosing class:
SSLEngineResult
public static enum SSLEngineResult.Status
extends Enum<SSLEngineResult.Status>

An SSLEngineResult enum describing the overall result of the SSLEngine operation. The Status value does not reflect the state of a SSLEngine handshake currently in progress. The SSLEngineResult's HandshakeStatus should be consulted for that information.

Since:
1.5

Enum Constant Summary
BUFFER_OVERFLOW
The SSLEngine was not able to process the operation because there are not enough bytes available in the destination buffer to hold the result.
BUFFER_UNDERFLOW
The SSLEngine was not able to unwrap the incoming data because there were not enough source bytes available to make a complete packet.
CLOSED
The operation just closed this side of the SSLEngine, or the operation could not be completed because it was already closed.
OK
The SSLEngine completed the operation, and is available to process similar calls.
Method Summary
static SSLEngineResult.Status | valueOf(String name) Returns the enum constant of this type with the specified name.
static SSLEngineResult.Status[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

BUFFER_UNDERFLOW

public static final SSLEngineResult.Status BUFFER_UNDERFLOW
The SSLEngine was not able to unwrap the incoming data because there were not enough source bytes available to make a complete packet.

Repeat the call once more bytes are available.

BUFFER_OVERFLOW

public static final SSLEngineResult.Status BUFFER_OVERFLOW
The SSLEngine was not able to process the operation because there are not enough bytes available in the destination buffer to hold the result.

Repeat the call once more bytes are available.

See Also:
SSLSession.getPacketBufferSize(), SSLSession.getApplicationBufferSize()

OK

public static final SSLEngineResult.Status OK
The SSLEngine completed the operation, and is available to process similar calls.

CLOSED

public static final SSLEngineResult.Status CLOSED
The operation just closed this side of the SSLEngine, or the operation could not be completed because it was already closed.

Method Detail

values

public static SSLEngineResult.Status[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (SSLEngineResult.Status c : SSLEngineResult.Status.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static SSLEngineResult.Status valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


SSLException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class SSLException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.io.IOException
                extended by  javax.net.ssl.SSLException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
SSLHandshakeException, SSLKeyException, SSLPeerUnverifiedException, SSLProtocolException
public class SSLException
extends IOException

Indicates some kind of error detected by an SSL subsystem. This class is the general class of exceptions produced by failed SSL-related operations.

Since:
1.4
See Also:
Serialized Form

Constructor Summary
SSLException(String reason)
Constructs an exception reporting an error found by an SSL subsystem.
SSLException(String message, Throwable cause)
Creates a SSLException with the specified detail message and cause.
SSLException(Throwable cause)
Creates a SSLException with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SSLException

public SSLException(String reason)
Constructs an exception reporting an error found by an SSL subsystem.

Parameters:
reason - describes the problem.

SSLException

public SSLException(String message,
                    Throwable cause)
Creates a SSLException with the specified detail message and cause.

Parameters:
message - the detail message (which is saved for later retrieval by the Throwable.getMessage() method).
cause - the cause (which is saved for later retrieval by the Throwable.getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
Since:
1.5

SSLException

public SSLException(Throwable cause)
Creates a SSLException with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).

Parameters:
cause - the cause (which is saved for later retrieval by the Throwable.getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLHandshakeException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class SSLHandshakeException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.io.IOException
                extended by  javax.net.ssl.SSLException
                    extended by  javax.net.ssl.SSLHandshakeException
All Implemented Interfaces:
Serializable
public class SSLHandshakeException
extends SSLException

Indicates that the client and server could not negotiate the desired level of security. The connection is no longer usable.

Since:
1.4
See Also:
Serialized Form

Constructor Summary
SSLHandshakeException(String reason)
Constructs an exception reporting an error found by an SSL subsystem during handshaking.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SSLHandshakeException

public SSLHandshakeException(String reason)
Constructs an exception reporting an error found by an SSL subsystem during handshaking.

Parameters:
reason - describes the problem.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLKeyException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class SSLKeyException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.io.IOException
                extended by  javax.net.ssl.SSLException
                    extended by  javax.net.ssl.SSLKeyException
All Implemented Interfaces:
Serializable
public class SSLKeyException
extends SSLException

Reports a bad SSL key. Normally, this indicates misconfiguration of the server or client SSL certificate and private key.

Since:
1.4
See Also:
Serialized Form

Constructor Summary
SSLKeyException(String reason)
Constructs an exception reporting a key management error found by an SSL subsystem.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SSLKeyException

public SSLKeyException(String reason)
Constructs an exception reporting a key management error found by an SSL subsystem.

Parameters:
reason - describes the problem.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLParameters

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class SSLParameters

java.lang.Object
    extended by  javax.net.ssl.SSLParameters

public class SSLParameters
extends Object

Encapsulates parameters for an SSL/TLS connection. The parameters are the list of ciphersuites to be accepted in an SSL/TLS handshake, the list of protocols to be allowed, and whether SSL/TLS servers should request or require client authentication.

SSLParameters can be created via the constructors in this class. Objects can also be obtained using the getSSLParameters() methods in SSLSocket and SSLEngine or the getDefaultSSLParameters() and getSupportedSSLParameters() methods in SSLContext.

SSLParameters can be applied to a connection via the methods SSLSocket.setSSLParameters() and SSLEngine.getSSLParameters().

Since:
1.6
See Also:
SSLSocket, SSLEngine, SSLContext

Constructor Summary
SSLParameters()
Constructs SSLParameters.
SSLParameters(String[] cipherSuites)
Constructs SSLParameters from the specified array of ciphersuites.
SSLParameters(String[] cipherSuites, String[] protocols)
Constructs SSLParameters from the specified array of ciphersuites and protocols.
Method Summary
String[] | getCipherSuites() Returns a copy of the array of ciphersuites or null if none have been set.
boolean | getNeedClientAuth() Returns whether client authentication should be required.
String[] | getProtocols() Returns a copy of the array of protocols or null if none have been set.
boolean | getWantClientAuth() Returns whether client authentication should be requested.
void | setCipherSuites(String[] cipherSuites) Sets the array of ciphersuites.
void | setNeedClientAuth(boolean needClientAuth) Sets whether client authentication should be required.
void | setProtocols(String[] protocols) Sets the array of protocols.
void | setWantClientAuth(boolean wantClientAuth) Sets whether client authentication should be requested.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SSLParameters

public SSLParameters()
Constructs SSLParameters.

The cipherSuites and protocols values are set to null, wantClientAuth and needClientAuth are set to false.

SSLParameters

public SSLParameters(String[] cipherSuites)
Constructs SSLParameters from the specified array of ciphersuites. Calling this constructor is equivalent to calling the no-args constructor followed by setCipherSuites(cipherSuites);.

Parameters:
cipherSuites - the array of ciphersuites (or null)

SSLParameters

public SSLParameters(String[] cipherSuites,
                     String[] protocols)
Constructs SSLParameters from the specified array of ciphersuites and protocols. Calling this constructor is equivalent to calling the no-args constructor followed by setCipherSuites(cipherSuites); setProtocols(protocols);.

Parameters:
cipherSuites - the array of ciphersuites (or null)
protocols - the array of protocols (or null)
Method Detail

getCipherSuites

public String[] getCipherSuites()
Returns a copy of the array of ciphersuites or null if none have been set.

Returns:
a copy of the array of ciphersuites or null if none have been set.

setCipherSuites

public void setCipherSuites(String[] cipherSuites)
Sets the array of ciphersuites.

Parameters:
cipherSuites - the array of ciphersuites (or null)

getProtocols

public String[] getProtocols()
Returns a copy of the array of protocols or null if none have been set.

Returns:
a copy of the array of protocols or null if none have been set.

setProtocols

public void setProtocols(String[] protocols)
Sets the array of protocols.

Parameters:
protocols - the array of protocols (or null)

getWantClientAuth

public boolean getWantClientAuth()
Returns whether client authentication should be requested.

Returns:
whether client authentication should be requested.

setWantClientAuth

public void setWantClientAuth(boolean wantClientAuth)
Sets whether client authentication should be requested. Calling this method clears the needClientAuth flag.

Parameters:
wantClientAuth - whether client authentication should be requested

getNeedClientAuth

public boolean getNeedClientAuth()
Returns whether client authentication should be required.

Returns:
whether client authentication should be required.

setNeedClientAuth

public void setNeedClientAuth(boolean needClientAuth)
Sets whether client authentication should be required. Calling this method clears the wantClientAuth flag.

Parameters:
needClientAuth - whether client authentication should be required
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLPeerUnverifiedException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class SSLPeerUnverifiedException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.io.IOException
                extended by  javax.net.ssl.SSLException
                    extended by  javax.net.ssl.SSLPeerUnverifiedException
All Implemented Interfaces:
Serializable
public class SSLPeerUnverifiedException
extends SSLException

Indicates that the peer's identity has not been verified.

When the peer was not able to identify itself (for example; no certificate, the particular cipher suite being used does not support authentication, or no peer authentication was established during SSL handshaking) this exception is thrown.

Since:
1.4
See Also:
Serialized Form

Constructor Summary
SSLPeerUnverifiedException(String reason)
Constructs an exception reporting that the SSL peer's identity has not been verifiied.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SSLPeerUnverifiedException

public SSLPeerUnverifiedException(String reason)
Constructs an exception reporting that the SSL peer's identity has not been verifiied.

Parameters:
reason - describes the problem.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLPermission

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class SSLPermission

java.lang.Object
    extended by  java.security.Permission
        extended by  java.security.BasicPermission
            extended by  javax.net.ssl.SSLPermission
All Implemented Interfaces:
Serializable, Guard
public final class SSLPermission
extends BasicPermission

This class is for various network permissions. An SSLPermission contains a name (also referred to as a "target name") but no actions list; you either have the named permission or you don't.

The target name is the name of the network permission (see below). The naming convention follows the hierarchical property naming convention. Also, an asterisk may appear at the end of the name, following a ".", or by itself, to signify a wildcard match. For example: "foo.*" or "*" is valid, "*foo" or "a*b" is not valid.

The following table lists all the possible SSLPermission target names, and for each provides a description of what the permission allows and a discussion of the risks of granting code the permission.

Permission Target Name | What the Permission Allows | Risks of Allowing this Permission
setHostnameVerifier | The ability to set a callback which can decide whether to allow a mismatch between the host being connected to by an HttpsURLConnection and the common name field in server certificate. | Malicious code can set a verifier that monitors host names visited by HttpsURLConnection requests or that allows server certificates with invalid common names.
getSSLSessionContext | The ability to get the SSLSessionContext of an SSLSession. | Malicious code may monitor sessions which have been established with SSL peers or might invalidate sessions to slow down performance.
setDefaultSSLContext | The ability to set the default SSL context | Malicious code can set a context that monitors the opening of connections or the plaintext data that is transmitted.

Since:
1.4
See Also:
BasicPermission, Permission, Permissions, PermissionCollection, SecurityManager, Serialized Form

Constructor Summary
SSLPermission(String name)
Creates a new SSLPermission with the specified name.
SSLPermission(String name, String actions)
Creates a new SSLPermission object with the specified name.
Method Summary
Methods inherited from class java.security.BasicPermission
equals, getActions, hashCode, implies, newPermissionCollection
Methods inherited from class java.security.Permission
checkGuard, getName, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

SSLPermission

public SSLPermission(String name)
Creates a new SSLPermission with the specified name. The name is the symbolic name of the SSLPermission, such as "setDefaultAuthenticator", etc. An asterisk may appear at the end of the name, following a ".", or by itself, to signify a wildcard match.

Parameters:
name - the name of the SSLPermission.
Throws:
NullPointerException - if name is null.
IllegalArgumentException - if name is empty.

SSLPermission

public SSLPermission(String name,
                     String actions)
Creates a new SSLPermission object with the specified name. The name is the symbolic name of the SSLPermission, and the actions String is currently unused and should be null.

Parameters:
name - the name of the SSLPermission.
actions - ignored.
Throws:
NullPointerException - if name is null.
IllegalArgumentException - if name is empty.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLProtocolException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class SSLProtocolException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.io.IOException
                extended by  javax.net.ssl.SSLException
                    extended by  javax.net.ssl.SSLProtocolException
All Implemented Interfaces:
Serializable
public class SSLProtocolException
extends SSLException

Reports an error in the operation of the SSL protocol. Normally this indicates a flaw in one of the protocol implementations.

Since:
1.4
See Also:
Serialized Form

Constructor Summary
SSLProtocolException(String reason)
Constructs an exception reporting an SSL protocol error detected by an SSL subsystem.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SSLProtocolException

public SSLProtocolException(String reason)
Constructs an exception reporting an SSL protocol error detected by an SSL subsystem.

Parameters:
reason - describes the problem.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLServerSocket

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class SSLServerSocket

java.lang.Object
    extended by  java.net.ServerSocket
        extended by  javax.net.ssl.SSLServerSocket

public abstract class SSLServerSocket
extends ServerSocket

This class extends ServerSockets and provides secure server sockets using protocols such as the Secure Sockets Layer (SSL) or Transport Layer Security (TLS) protocols.

Instances of this class are generally created using a SSLServerSocketFactory. The primary function of SSLServerSockets is to create SSLSockets by accepting connections.

SSLServerSockets contain several pieces of state data which are inherited by the SSLSocket at socket creation. These include the enabled cipher suites and protocols, whether client authentication is necessary, and whether created sockets should begin handshaking in client or server mode. The state inherited by the created SSLSocket can be overriden by calling the appropriate methods.

Since:
1.4
See Also:
ServerSocket, SSLSocket

Constructor Summary
protected | SSLServerSocket() Used only by subclasses.
protected | SSLServerSocket(int port) Used only by subclasses.
protected | SSLServerSocket(int port, int backlog) Used only by subclasses.
protected | SSLServerSocket(int port, int backlog, InetAddress address) Used only by subclasses.
Method Summary
abstract String[] | getEnabledCipherSuites() Returns the list of cipher suites which are currently enabled for use by newly accepted connections.
abstract String[] | getEnabledProtocols() Returns the names of the protocols which are currently enabled for use by the newly accepted connections.
abstract boolean | getEnableSessionCreation() Returns true if new SSL sessions may be established by the sockets which are created from this server socket.
abstract boolean | getNeedClientAuth() Returns true if client authentication will be required on newly accepted server-mode SSLSockets.
abstract String[] | getSupportedCipherSuites() Returns the names of the cipher suites which could be enabled for use on an SSL connection.
abstract String[] | getSupportedProtocols() Returns the names of the protocols which could be enabled for use.
abstract boolean | getUseClientMode() Returns true if accepted connections will be in SSL client mode.
abstract boolean | getWantClientAuth() Returns true if client authentication will be requested on newly accepted server-mode connections.
abstract void | setEnabledCipherSuites(String[] suites) Sets the cipher suites enabled for use by accepted connections.
abstract void | setEnabledProtocols(String[] protocols) Controls which particular protocols are enabled for use by accepted connections.
abstract void | setEnableSessionCreation(boolean flag) Controls whether new SSL sessions may be established by the sockets which are created from this server socket.
abstract void | setNeedClientAuth(boolean need) Controls whether accepted server-mode SSLSockets will be initially configured to require client authentication.
abstract void | setUseClientMode(boolean mode) Controls whether accepted connections are in the (default) SSL server mode, or the SSL client mode.
abstract void | setWantClientAuth(boolean want) Controls whether accepted server-mode SSLSockets will be initially configured to request client authentication.
Methods inherited from class java.net.ServerSocket
accept, bind, bind, close, getChannel, getInetAddress, getLocalPort, getLocalSocketAddress, getReceiveBufferSize, getReuseAddress, getSoTimeout, implAccept, isBound, isClosed, setPerformancePreferences, setReceiveBufferSize, setReuseAddress, setSocketFactory, setSoTimeout, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SSLServerSocket

protected SSLServerSocket()
                   throws IOException
Used only by subclasses.

Create an unbound TCP server socket using the default authentication context.

Throws:
IOException - if an I/O error occurs when creating the socket

SSLServerSocket

protected SSLServerSocket(int port)
                   throws IOException
Used only by subclasses.

Create a TCP server socket on a port, using the default authentication context. The connection backlog defaults to fifty connections queued up before the system starts to reject new connection requests.

Parameters:
port - the port on which to listen
Throws:
IOException - if an I/O error occurs when creating the socket

SSLServerSocket

protected SSLServerSocket(int port,
                          int backlog)
                   throws IOException
Used only by subclasses.

Create a TCP server socket on a port, using the default authentication context and a specified backlog of connections.

Parameters:
port - the port on which to listen
backlog - how many connections may be pending before the system should start rejecting new requests
Throws:
IOException - if an I/O error occurs when creating the socket

SSLServerSocket

protected SSLServerSocket(int port,
                          int backlog,
                          InetAddress address)
                   throws IOException
Used only by subclasses.

Create a TCP server socket on a port, using the default authentication context and a specified backlog of connections as well as a particular specified network interface. This constructor is used on multihomed hosts, such as those used for firewalls or as routers, to control through which interface a network service is provided.

Parameters:
port - the port on which to listen
backlog - how many connections may be pending before the system should start rejecting new requests
address - the address of the network interface through which connections will be accepted
Throws:
IOException - if an I/O error occurs when creating the socket
Method Detail

getEnabledCipherSuites

public abstract String[] getEnabledCipherSuites()
Returns the list of cipher suites which are currently enabled for use by newly accepted connections.

If this list has not been explicitly modified, a system-provided default guarantees a minimum quality of service in all enabled cipher suites.

There are several reasons why an enabled cipher suite might not actually be used. For example: the server socket might not have appropriate private keys available to it or the cipher suite might be anonymous, precluding the use of client authentication, while the server socket has been told to require that sort of authentication.

Returns:
an array of cipher suites enabled
See Also:
getSupportedCipherSuites(), setEnabledCipherSuites(String [])

setEnabledCipherSuites

public abstract void setEnabledCipherSuites(String[] suites)
Sets the cipher suites enabled for use by accepted connections.

The cipher suites must have been listed by getSupportedCipherSuites() as being supported. Following a successful call to this method, only suites listed in the suites parameter are enabled for use.

Suites that require authentication information which is not available in this ServerSocket's authentication context will not be used in any case, even if they are enabled.

SSLSockets returned from accept() inherit this setting.

Parameters:
suites - Names of all the cipher suites to enable
Throws:
IllegalArgumentException - when one or more of ciphers named by the parameter is not supported, or when the parameter is null.
See Also:
getSupportedCipherSuites(), getEnabledCipherSuites()

getSupportedCipherSuites

public abstract String[] getSupportedCipherSuites()
Returns the names of the cipher suites which could be enabled for use on an SSL connection.

Normally, only a subset of these will actually be enabled by default, since this list may include cipher suites which do not meet quality of service requirements for those defaults. Such cipher suites are useful in specialized applications.

Returns:
an array of cipher suite names
See Also:
getEnabledCipherSuites(), setEnabledCipherSuites(String [])

getSupportedProtocols

public abstract String[] getSupportedProtocols()
Returns the names of the protocols which could be enabled for use.

Returns:
an array of protocol names supported
See Also:
getEnabledProtocols(), setEnabledProtocols(String [])

getEnabledProtocols

public abstract String[] getEnabledProtocols()
Returns the names of the protocols which are currently enabled for use by the newly accepted connections.

Returns:
an array of protocol names
See Also:
getSupportedProtocols(), setEnabledProtocols(String [])

setEnabledProtocols

public abstract void setEnabledProtocols(String[] protocols)
Controls which particular protocols are enabled for use by accepted connections.

The protocols must have been listed by getSupportedProtocols() as being supported. Following a successful call to this method, only protocols listed in the protocols parameter are enabled for use.

SSLSockets returned from accept() inherit this setting.

Parameters:
protocols - Names of all the protocols to enable.
Throws:
IllegalArgumentException - when one or more of the protocols named by the parameter is not supported or when the protocols parameter is null.
See Also:
getEnabledProtocols(), getSupportedProtocols()

setNeedClientAuth

public abstract void setNeedClientAuth(boolean need)
Controls whether accepted server-mode SSLSockets will be initially configured to require client authentication.

A socket's client authentication setting is one of the following:

  • client authentication required
  • client authentication requested
  • no client authentication desired

Unlike setWantClientAuth(boolean), if the accepted socket's option is set and the client chooses not to provide authentication information about itself, the negotiations will stop and the connection will be dropped.

Calling this method overrides any previous setting made by this method or setWantClientAuth(boolean).

The initial inherited setting may be overridden by calling SSLSocket.setNeedClientAuth(boolean) or SSLSocket.setWantClientAuth(boolean).

Parameters:
need - set to true if client authentication is required, or false if no client authentication is desired.
See Also:
getNeedClientAuth(), setWantClientAuth(boolean), getWantClientAuth(), setUseClientMode(boolean)

getNeedClientAuth

public abstract boolean getNeedClientAuth()
Returns true if client authentication will be required on newly accepted server-mode SSLSockets.

The initial inherited setting may be overridden by calling SSLSocket.setNeedClientAuth(boolean) or SSLSocket.setWantClientAuth(boolean).

Returns:
true if client authentication is required, or false if no client authentication is desired.
See Also:
setNeedClientAuth(boolean), setWantClientAuth(boolean), getWantClientAuth(), setUseClientMode(boolean)

setWantClientAuth

public abstract void setWantClientAuth(boolean want)
Controls whether accepted server-mode SSLSockets will be initially configured to request client authentication.

A socket's client authentication setting is one of the following:

  • client authentication required
  • client authentication requested
  • no client authentication desired

Unlike setNeedClientAuth(boolean), if the accepted socket's option is set and the client chooses not to provide authentication information about itself, the negotiations will continue.

Calling this method overrides any previous setting made by this method or setNeedClientAuth(boolean).

The initial inherited setting may be overridden by calling SSLSocket.setNeedClientAuth(boolean) or SSLSocket.setWantClientAuth(boolean).

Parameters:
want - set to true if client authentication is requested, or false if no client authentication is desired.
See Also:
getWantClientAuth(), setNeedClientAuth(boolean), getNeedClientAuth(), setUseClientMode(boolean)

getWantClientAuth

public abstract boolean getWantClientAuth()
Returns true if client authentication will be requested on newly accepted server-mode connections.

The initial inherited setting may be overridden by calling SSLSocket.setNeedClientAuth(boolean) or SSLSocket.setWantClientAuth(boolean).

Returns:
true if client authentication is requested, or false if no client authentication is desired.
See Also:
setWantClientAuth(boolean), setNeedClientAuth(boolean), getNeedClientAuth(), setUseClientMode(boolean)

setUseClientMode

public abstract void setUseClientMode(boolean mode)
Controls whether accepted connections are in the (default) SSL server mode, or the SSL client mode.

Servers normally authenticate themselves, and clients are not required to do so.

In rare cases, TCP servers need to act in the SSL client mode on newly accepted connections. For example, FTP clients acquire server sockets and listen there for reverse connections from the server. An FTP client would use an SSLServerSocket in "client" mode to accept the reverse connection while the FTP server uses an SSLSocket with "client" mode disabled to initiate the connection. During the resulting handshake, existing SSL sessions may be reused.

SSLSockets returned from accept() inherit this setting.

Parameters:
mode - true if newly accepted connections should use SSL client mode.
See Also:
getUseClientMode()

getUseClientMode

public abstract boolean getUseClientMode()
Returns true if accepted connections will be in SSL client mode.

Returns:
true if the connection should use SSL client mode.
See Also:
setUseClientMode(boolean)

setEnableSessionCreation

public abstract void setEnableSessionCreation(boolean flag)
Controls whether new SSL sessions may be established by the sockets which are created from this server socket.

SSLSockets returned from accept() inherit this setting.

Parameters:
flag - true indicates that sessions may be created; this is the default. false indicates that an existing session must be resumed.
See Also:
getEnableSessionCreation()

getEnableSessionCreation

public abstract boolean getEnableSessionCreation()
Returns true if new SSL sessions may be established by the sockets which are created from this server socket.

Returns:
true indicates that sessions may be created; this is the default. false indicates that an existing session must be resumed.
See Also:
setEnableSessionCreation(boolean)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLServerSocketFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class SSLServerSocketFactory

java.lang.Object
    extended by  javax.net.ServerSocketFactory
        extended by  javax.net.ssl.SSLServerSocketFactory

public abstract class SSLServerSocketFactory
extends ServerSocketFactory

SSLServerSocketFactorys create SSLServerSockets.

Since:
1.4
See Also:
SSLSocket, SSLServerSocket

Constructor Summary
protected SSLServerSocketFactory()
Constructor is used only by subclasses.
Method Summary
static ServerSocketFactory | getDefault() Returns the default SSL server socket factory.
abstract String[] | getDefaultCipherSuites() Returns the list of cipher suites which are enabled by default.
abstract String[] | getSupportedCipherSuites() Returns the names of the cipher suites which could be enabled for use on an SSL connection created by this factory.
Methods inherited from class javax.net.ServerSocketFactory
createServerSocket, createServerSocket, createServerSocket, createServerSocket
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SSLServerSocketFactory

protected SSLServerSocketFactory()
Constructor is used only by subclasses.

Method Detail

getDefault

public static ServerSocketFactory getDefault()
Returns the default SSL server socket factory.

The first time this method is called, the security property "ssl.ServerSocketFactory.provider" is examined. If it is non-null, a class by that name is loaded and instantiated. If that is successful and the object is an instance of SSLServerSocketFactory, it is made the default SSL server socket factory.

Otherwise, this method returns SSLContext.getDefault().getServerSocketFactory(). If that call fails, an inoperative factory is returned.

Returns:
the default ServerSocketFactory
See Also:
SSLContext.getDefault()

getDefaultCipherSuites

public abstract String[] getDefaultCipherSuites()
Returns the list of cipher suites which are enabled by default. Unless a different list is enabled, handshaking on an SSL connection will use one of these cipher suites. The minimum quality of service for these defaults requires confidentiality protection and server authentication (that is, no anonymous cipher suites).

Returns:
array of the cipher suites enabled by default
See Also:
getSupportedCipherSuites()

getSupportedCipherSuites

public abstract String[] getSupportedCipherSuites()
Returns the names of the cipher suites which could be enabled for use on an SSL connection created by this factory. Normally, only a subset of these will actually be enabled by default, since this list may include cipher suites which do not meet quality of service requirements for those defaults. Such cipher suites are useful in specialized applications.

Returns:
an array of cipher suite names
See Also:
getDefaultCipherSuites()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLSession

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Interface SSLSession

public interface SSLSession

In SSL, sessions are used to describe an ongoing relationship between two entities. Each SSL connection involves one session at a time, but that session may be used on many connections between those entities, simultaneously or sequentially. The session used on a connection may also be replaced by a different session. Sessions are created, or rejoined, as part of the SSL handshaking protocol. Sessions may be invalidated due to policies affecting security or resource usage, or by an application explicitly calling invalidate. Session management policies are typically used to tune performance.

In addition to the standard session attributes, SSL sessions expose these read-only attributes:

  • Peer Identity. Sessions are between a particular client and a particular server. The identity of the peer may have been established as part of session setup. Peers are generally identified by X.509 certificate chains.
  • Cipher Suite Name. Cipher suites describe the kind of cryptographic protection that's used by connections in a particular session.
  • Peer Host. All connections in a session are between the same two hosts. The address of the host on the other side of the connection is available.

Sessions may be explicitly invalidated. Invalidation may also be done implicitly, when faced with certain kinds of errors.

Since:
1.4

Method Summary
int | getApplicationBufferSize() Gets the current size of the largest application data that is expected when using this session.
String | getCipherSuite() Returns the name of the SSL cipher suite which is used for all connections in the session.
long | getCreationTime() Returns the time at which this Session representation was created, in milliseconds since midnight, January 1, 1970 UTC.
byte[] | getId() Returns the identifier assigned to this Session.
long | getLastAccessedTime() Returns the last time this Session representation was accessed by the session level infrastructure, in milliseconds since midnight, January 1, 1970 UTC.
Certificate[] | getLocalCertificates() Returns the certificate(s) that were sent to the peer during handshaking.
Principal | getLocalPrincipal() Returns the principal that was sent to the peer during handshaking.
int | getPacketBufferSize() Gets the current size of the largest SSL/TLS packet that is expected when using this session.
X509Certificate[] | getPeerCertificateChain() Returns the identity of the peer which was identified as part of defining the session.
Certificate[] | getPeerCertificates() Returns the identity of the peer which was established as part of defining the session.
String | getPeerHost() Returns the host name of the peer in this session.
int | getPeerPort() Returns the port number of the peer in this session.
Principal | getPeerPrincipal() Returns the identity of the peer which was established as part of defining the session.
String | getProtocol() Returns the standard name of the protocol used for all connections in the session.
SSLSessionContext | getSessionContext() Returns the context in which this session is bound.
Object | getValue(String name) Returns the object bound to the given name in the session's application layer data.
String[] | getValueNames() Returns an array of the names of all the application layer data objects bound into the Session.
void | invalidate() Invalidates the session.
boolean | isValid() Returns whether this session is valid and available for resuming or joining.
void | putValue(String name, Object value) Binds the specified value object into the session's application layer data with the given name.
void | removeValue(String name) Removes the object bound to the given name in the session's application layer data.

Method Detail

getId

byte[] getId()
Returns the identifier assigned to this Session.

Returns:
the Session identifier

getSessionContext

SSLSessionContext getSessionContext()
Returns the context in which this session is bound.

This context may be unavailable in some environments, in which case this method returns null.

If the context is available and there is a security manager installed, the caller may require permission to access it or a security exception may be thrown. In a Java environment, the security manager's checkPermission method is called with a SSLPermission("getSSLSessionContext") permission.

Returns:
the session context used for this session, or null if the context is unavailable.
Throws:
SecurityException - if the calling thread does not have permission to get SSL session context.

getCreationTime

long getCreationTime()
Returns the time at which this Session representation was created, in milliseconds since midnight, January 1, 1970 UTC.

Returns:
the time this Session was created

getLastAccessedTime

long getLastAccessedTime()
Returns the last time this Session representation was accessed by the session level infrastructure, in milliseconds since midnight, January 1, 1970 UTC.

Access indicates a new connection being established using session data. Application level operations, such as getting or setting a value associated with the session, are not reflected in this access time.

This information is particularly useful in session management policies. For example, a session manager thread could leave all sessions in a given context which haven't been used in a long time; or, the sessions might be sorted according to age to optimize some task.

Returns:
the last time this Session was accessed

invalidate

void invalidate()
Invalidates the session.

Future connections will not be able to resume or join this session. However, any existing connection using this session can continue to use the session until the connection is closed.

See Also:
isValid()

isValid

boolean isValid()
Returns whether this session is valid and available for resuming or joining.

Returns:
true if this session may be rejoined.
Since:
1.5
See Also:
invalidate()

putValue

void putValue(String name,
              Object value)
Binds the specified value object into the session's application layer data with the given name.

Any existing binding using the same name is replaced. If the new (or existing) value implements the SSLSessionBindingListener interface, the object represented by value is notified appropriately.

For security reasons, the same named values may not be visible across different access control contexts.

Parameters:
name - the name to which the data object will be bound. This may not be null.
value - the data object to be bound. This may not be null.
Throws:
IllegalArgumentException - if either argument is null.

getValue

Object getValue(String name)
Returns the object bound to the given name in the session's application layer data. Returns null if there is no such binding.

For security reasons, the same named values may not be visible across different access control contexts.

Parameters:
name - the name of the binding to find.
Returns:
the value bound to that name, or null if the binding does not exist.
Throws:
IllegalArgumentException - if the argument is null.

removeValue

void removeValue(String name)
Removes the object bound to the given name in the session's application layer data. Does nothing if there is no object bound to the given name. If the bound existing object implements the SessionBindingListener interface, it is notified appropriately.

For security reasons, the same named values may not be visible across different access control contexts.

Parameters:
name - the name of the object to remove visible across different access control contexts
Throws:
IllegalArgumentException - if the argument is null.

getValueNames

String[] getValueNames()
Returns an array of the names of all the application layer data objects bound into the Session.

For security reasons, the same named values may not be visible across different access control contexts.

Returns:
a non-null (possibly empty) array of names of the objects bound to this Session.

getPeerCertificates

Certificate[] getPeerCertificates()
                                  throws SSLPeerUnverifiedException
Returns the identity of the peer which was established as part of defining the session.

Note: This method can be used only when using certificate-based cipher suites; using it with non-certificate-based cipher suites, such as Kerberos, will throw an SSLPeerUnverifiedException.

Returns:
an ordered array of peer certificates, with the peer's own certificate first followed by any certificate authorities.
Throws:
SSLPeerUnverifiedException - if the peer's identity has not been verified
See Also:
getPeerPrincipal()

getLocalCertificates

Certificate[] getLocalCertificates()
Returns the certificate(s) that were sent to the peer during handshaking.

Note: This method is useful only when using certificate-based cipher suites.

When multiple certificates are available for use in a handshake, the implementation chooses what it considers the "best" certificate chain available, and transmits that to the other side. This method allows the caller to know which certificate chain was actually used.

Returns:
an ordered array of certificates, with the local certificate first followed by any certificate authorities. If no certificates were sent, then null is returned.
See Also:
getLocalPrincipal()

getPeerCertificateChain

X509Certificate[] getPeerCertificateChain()
                                          throws SSLPeerUnverifiedException
Returns the identity of the peer which was identified as part of defining the session.

Note: This method can be used only when using certificate-based cipher suites; using it with non-certificate-based cipher suites, such as Kerberos, will throw an SSLPeerUnverifiedException.

Note: this method exists for compatibility with previous releases. New applications should use getPeerCertificates() instead.

Returns:
an ordered array of peer X.509 certificates, with the peer's own certificate first followed by any certificate authorities. (The certificates are in the original JSSE certificate X509Certificate format.)
Throws:
SSLPeerUnverifiedException - if the peer's identity has not been verified
See Also:
getPeerPrincipal()

getPeerPrincipal

Principal getPeerPrincipal()
                           throws SSLPeerUnverifiedException
Returns the identity of the peer which was established as part of defining the session.

Returns:
the peer's principal. Returns an X500Principal of the end-entity certiticate for X509-based cipher suites, and KerberosPrincipal for Kerberos cipher suites.
Throws:
SSLPeerUnverifiedException - if the peer's identity has not been verified
Since:
1.5
See Also:
getPeerCertificates(), getLocalPrincipal()

getLocalPrincipal

Principal getLocalPrincipal()
Returns the principal that was sent to the peer during handshaking.

Returns:
the principal sent to the peer. Returns an X500Principal of the end-entity certificate for X509-based cipher suites, and KerberosPrincipal for Kerberos cipher suites. If no principal was sent, then null is returned.
Since:
1.5
See Also:
getLocalCertificates(), getPeerPrincipal()

getCipherSuite

String getCipherSuite()
Returns the name of the SSL cipher suite which is used for all connections in the session.

This defines the level of protection provided to the data sent on the connection, including the kind of encryption used and most aspects of how authentication is done.

Returns:
the name of the session's cipher suite

getProtocol

String getProtocol()
Returns the standard name of the protocol used for all connections in the session.

This defines the protocol used in the connection.

Returns:
the standard name of the protocol used for all connections in the session.

getPeerHost

String getPeerHost()
Returns the host name of the peer in this session.

For the server, this is the client's host; and for the client, it is the server's host. The name may not be a fully qualified host name or even a host name at all as it may represent a string encoding of the peer's network address. If such a name is desired, it might be resolved through a name service based on the value returned by this method.

This value is not authenticated and should not be relied upon. It is mainly used as a hint for SSLSession caching strategies.

Returns:
the host name of the peer host, or null if no information is available.

getPeerPort

int getPeerPort()
Returns the port number of the peer in this session.

For the server, this is the client's port number; and for the client, it is the server's port number.

This value is not authenticated and should not be relied upon. It is mainly used as a hint for SSLSession caching strategies.

Returns:
the port number of the peer host, or -1 if no information is available.
Since:
1.5

getPacketBufferSize

int getPacketBufferSize()
Gets the current size of the largest SSL/TLS packet that is expected when using this session.

A SSLEngine using this session may generate SSL/TLS packets of any size up to and including the value returned by this method. All SSLEngine network buffers should be sized at least this large to avoid insufficient space problems when performing wrap and unwrap calls.

Returns:
the current maximum expected network packet size
Since:
1.5
See Also:
SSLEngine.wrap(ByteBuffer, ByteBuffer), SSLEngine.unwrap(ByteBuffer, ByteBuffer)

getApplicationBufferSize

int getApplicationBufferSize()
Gets the current size of the largest application data that is expected when using this session.

SSLEngine application data buffers must be large enough to hold the application data from any inbound network application data packet received. Typically, outbound application data buffers can be of any size.

Returns:
the current maximum expected application packet size
Since:
1.5
See Also:
SSLEngine.wrap(ByteBuffer, ByteBuffer), SSLEngine.unwrap(ByteBuffer, ByteBuffer)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLSessionBindingEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class SSLSessionBindingEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.net.ssl.SSLSessionBindingEvent
All Implemented Interfaces:
Serializable
public class SSLSessionBindingEvent
extends EventObject

This event is propagated to a SSLSessionBindingListener. When a listener object is bound or unbound to an SSLSession by SSLSession.putValue(String, Object) or SSLSession.removeValue(String), objects which implement the SSLSessionBindingListener will be receive an event of this type. The event's name field is the key in which the listener is being bound or unbound.

Since:
1.4
See Also:
SSLSession, SSLSessionBindingListener, Serialized Form

Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
SSLSessionBindingEvent(SSLSession session, String name)
Constructs a new SSLSessionBindingEvent.
Method Summary
String | getName() Returns the name to which the object is being bound, or the name from which the object is being unbound.
SSLSession | getSession() Returns the SSLSession into which the listener is being bound or from which the listener is being unbound.
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SSLSessionBindingEvent

public SSLSessionBindingEvent(SSLSession session,
                              String name)
Constructs a new SSLSessionBindingEvent.

Parameters:
session - the SSLSession acting as the source of the event
name - the name to which the object is being bound or unbound
Throws:
IllegalArgumentException - if session is null.
Method Detail

getName

public String getName()
Returns the name to which the object is being bound, or the name from which the object is being unbound.

Returns:
the name to which the object is being bound or unbound

getSession

public SSLSession getSession()
Returns the SSLSession into which the listener is being bound or from which the listener is being unbound.

Returns:
the SSLSession
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLSessionBindingListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Interface SSLSessionBindingListener

All Superinterfaces:
EventListener
public interface SSLSessionBindingListener
extends EventListener

This interface is implemented by objects which want to know when they are being bound or unbound from a SSLSession. When either event occurs via SSLSession.putValue(String, Object) or SSLSession.removeValue(String), the event is communicated through a SSLSessionBindingEvent identifying the session.

Since:
1.4
See Also:
SSLSession, SSLSessionBindingEvent

Method Summary
void | valueBound(SSLSessionBindingEvent event) This is called to notify the listener that it is being bound into an SSLSession.
void | valueUnbound(SSLSessionBindingEvent event) This is called to notify the listener that it is being unbound from a SSLSession.

Method Detail

valueBound

void valueBound(SSLSessionBindingEvent event)
This is called to notify the listener that it is being bound into an SSLSession.

Parameters:
event - the event identifying the SSLSession into which the listener is being bound.

valueUnbound

void valueUnbound(SSLSessionBindingEvent event)
This is called to notify the listener that it is being unbound from a SSLSession.

Parameters:
event - the event identifying the SSLSession from which the listener is being unbound.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLSessionContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Interface SSLSessionContext

public interface SSLSessionContext

A SSLSessionContext represents a set of SSLSessions associated with a single entity. For example, it could be associated with a server or client who participates in many sessions concurrently.

Not all environments will contain session contexts.

There are SSLSessionContext parameters that affect how sessions are stored:

  • Sessions can be set to expire after a specified time limit.
  • The number of sessions that can be stored in context can be limited.
A session can be retrieved based on its session id, and all session id's in a SSLSessionContext can be listed.

Since:
1.4
See Also:
SSLSession

Method Summary
Enumeration | getIds() Returns an Enumeration of all session id's grouped under this SSLSessionContext.
SSLSession | getSession(byte[] sessionId) Returns the SSLSession bound to the specified session id.
int | getSessionCacheSize() Returns the size of the cache used for storing SSLSession objects grouped under this SSLSessionContext.
int | getSessionTimeout() Returns the timeout limit of SSLSession objects grouped under this SSLSessionContext.
void | setSessionCacheSize(int size) Sets the size of the cache used for storing SSLSession objects grouped under this SSLSessionContext.
void | setSessionTimeout(int seconds) Sets the timeout limit for SSLSession objects grouped under this SSLSessionContext.

Method Detail

getSession

SSLSession getSession(byte[] sessionId)
Returns the SSLSession bound to the specified session id.

Parameters:
sessionId - the Session identifier
Returns:
the SSLSession or null if the specified session id does not refer to a valid SSLSession.
Throws:
NullPointerException - if sessionId is null.

getIds

Enumeration getIds()
Returns an Enumeration of all session id's grouped under this SSLSessionContext.

Returns:
an enumeration of all the Session id's

setSessionTimeout

void setSessionTimeout(int seconds)
                       throws IllegalArgumentException
Sets the timeout limit for SSLSession objects grouped under this SSLSessionContext.

If the timeout limit is set to 't' seconds, a session exceeds the timeout limit 't' seconds after its creation time. When the timeout limit is exceeded for a session, the SSLSession object is invalidated and future connections cannot resume or rejoin the session. A check for sessions exceeding the timeout is made immediately whenever the timeout limit is changed for this SSLSessionContext.

Parameters:
seconds - the new session timeout limit in seconds; zero means there is no limit.
Throws:
IllegalArgumentException - if the timeout specified is < 0.
See Also:
getSessionTimeout()

getSessionTimeout

int getSessionTimeout()
Returns the timeout limit of SSLSession objects grouped under this SSLSessionContext.

If the timeout limit is set to 't' seconds, a session exceeds the timeout limit 't' seconds after its creation time. When the timeout limit is exceeded for a session, the SSLSession object is invalidated and future connections cannot resume or rejoin the session. A check for sessions exceeding the timeout limit is made immediately whenever the timeout limit is changed for this SSLSessionContext.

Returns:
the session timeout limit in seconds; zero means there is no limit.
See Also:
setSessionTimeout(int)

setSessionCacheSize

void setSessionCacheSize(int size)
                         throws IllegalArgumentException
Sets the size of the cache used for storing SSLSession objects grouped under this SSLSessionContext.

Parameters:
size - the new session cache size limit; zero means there is no limit.
Throws:
IllegalArgumentException - if the specified size is < 0.
See Also:
getSessionCacheSize()

getSessionCacheSize

int getSessionCacheSize()
Returns the size of the cache used for storing SSLSession objects grouped under this SSLSessionContext.

Returns:
size of the session cache; zero means there is no size limit.
See Also:
setSessionCacheSize(int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLSocket

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class SSLSocket

java.lang.Object
    extended by  java.net.Socket
        extended by  javax.net.ssl.SSLSocket

public abstract class SSLSocket
extends Socket

This class extends Sockets and provides secure socket using protocols such as the "Secure Sockets Layer" (SSL) or IETF "Transport Layer Security" (TLS) protocols.

Such sockets are normal stream sockets, but they add a layer of security protections over the underlying network transport protocol, such as TCP. Those protections include:

  • Integrity Protection. SSL protects against modification of messages by an active wiretapper.
  • Authentication. In most modes, SSL provides peer authentication. Servers are usually authenticated, and clients may be authenticated as requested by servers.
  • Confidentiality (Privacy Protection). In most modes, SSL encrypts data being sent between client and server. This protects the confidentiality of data, so that passive wiretappers won't see sensitive data such as financial information or personal information of many kinds.

These kinds of protection are specified by a "cipher suite", which is a combination of cryptographic algorithms used by a given SSL connection. During the negotiation process, the two endpoints must agree on a ciphersuite that is available in both environments. If there is no such suite in common, no SSL connection can be established, and no data can be exchanged.

The cipher suite used is established by a negotiation process called "handshaking". The goal of this process is to create or rejoin a "session", which may protect many connections over time. After handshaking has completed, you can access session attributes by using the getSession method. The initial handshake on this connection can be initiated in one of three ways:

  • calling startHandshake which explicitly begins handshakes, or
  • any attempt to read or write application data on this socket causes an implicit handshake, or
  • a call to getSession tries to set up a session if there is no currently valid session, and an implicit handshake is done.

If handshaking fails for any reason, the SSLSocket is closed, and no futher communications can be done.

There are two groups of cipher suites which you will need to know about when managing cipher suites:

  • Supported cipher suites: all the suites which are supported by the SSL implementation. This list is reported using getSupportedCipherSuites.
  • Enabled cipher suites, which may be fewer than the full set of supported suites. This group is set using the setEnabledCipherSuites method, and queried using the getEnabledCipherSuites method. Initially, a default set of cipher suites will be enabled on a new socket that represents the minimum suggested configuration.

Implementation defaults require that only cipher suites which authenticate servers and provide confidentiality be enabled by default. Only if both sides explicitly agree to unauthenticated and/or non-private (unencrypted) communications will such a ciphersuite be selected.

When SSLSockets are first created, no handshaking is done so that applications may first set their communication preferences: what cipher suites to use, whether the socket should be in client or server mode, etc. However, security is always provided by the time that application data is sent over the connection.

You may register to receive event notification of handshake completion. This involves the use of two additional classes. HandshakeCompletedEvent objects are passed to HandshakeCompletedListener instances, which are registered by users of this API. SSLSockets are created by SSLSocketFactorys, or by accepting a connection from a SSLServerSocket.

A SSL socket must choose to operate in the client or server mode. This will determine who begins the handshaking process, as well as which messages should be sent by each party. Each connection must have one client and one server, or handshaking will not progress properly. Once the initial handshaking has started, a socket can not switch between client and server modes, even when performing renegotiations.

Since:
1.4
See Also:
Socket, SSLServerSocket, SSLSocketFactory

Constructor Summary
protected | SSLSocket() Used only by subclasses.
protected | SSLSocket(InetAddress address, int port) Used only by subclasses.
protected | SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort) Used only by subclasses.
protected | SSLSocket(String host, int port) Used only by subclasses.
protected | SSLSocket(String host, int port, InetAddress clientAddress, int clientPort) Used only by subclasses.
Method Summary
abstract void | addHandshakeCompletedListener(HandshakeCompletedListener listener) Registers an event listener to receive notifications that an SSL handshake has completed on this connection.
abstract String[] | getEnabledCipherSuites() Returns the names of the SSL cipher suites which are currently enabled for use on this connection.
abstract String[] | getEnabledProtocols() Returns the names of the protocol versions which are currently enabled for use on this connection.
abstract boolean | getEnableSessionCreation() Returns true if new SSL sessions may be established by this socket.
abstract boolean | getNeedClientAuth() Returns true if the socket will require client authentication.
abstract SSLSession | getSession() Returns the SSL Session in use by this connection.
SSLParameters | getSSLParameters() Returns the SSLParameters in effect for this SSLSocket.
abstract String[] | getSupportedCipherSuites() Returns the names of the cipher suites which could be enabled for use on this connection.
abstract String[] | getSupportedProtocols() Returns the names of the protocols which could be enabled for use on an SSL connection.
abstract boolean | getUseClientMode() Returns true if the socket is set to use client mode when handshaking.
abstract boolean | getWantClientAuth() Returns true if the socket will request client authentication.
abstract void | removeHandshakeCompletedListener(HandshakeCompletedListener listener) Removes a previously registered handshake completion listener.
abstract void | setEnabledCipherSuites(String[] suites) Sets the cipher suites enabled for use on this connection.
abstract void | setEnabledProtocols(String[] protocols) Sets the protocol versions enabled for use on this connection.
abstract void | setEnableSessionCreation(boolean flag) Controls whether new SSL sessions may be established by this socket.
abstract void | setNeedClientAuth(boolean need) Configures the socket to require client authentication.
void | setSSLParameters(SSLParameters params) Applies SSLParameters to this socket.
abstract void | setUseClientMode(boolean mode) Configures the socket to use client (or server) mode when handshaking.
abstract void | setWantClientAuth(boolean want) Configures the socket to request client authentication.
abstract void | startHandshake() Starts an SSL handshake on this connection.
Methods inherited from class java.net.Socket
bind, close, connect, connect, getChannel, getInetAddress, getInputStream, getKeepAlive, getLocalAddress, getLocalPort, getLocalSocketAddress, getOOBInline, getOutputStream, getPort, getReceiveBufferSize, getRemoteSocketAddress, getReuseAddress, getSendBufferSize, getSoLinger, getSoTimeout, getTcpNoDelay, getTrafficClass, isBound, isClosed, isConnected, isInputShutdown, isOutputShutdown, sendUrgentData, setKeepAlive, setOOBInline, setPerformancePreferences, setReceiveBufferSize, setReuseAddress, setSendBufferSize, setSocketImplFactory, setSoLinger, setSoTimeout, setTcpNoDelay, setTrafficClass, shutdownInput, shutdownOutput, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SSLSocket

protected SSLSocket()
Used only by subclasses. Constructs an uninitialized, unconnected TCP socket.

SSLSocket

protected SSLSocket(String host,
                    int port)
             throws IOException,
                    UnknownHostException
Used only by subclasses. Constructs a TCP connection to a named host at a specified port. This acts as the SSL client.

Parameters:
host - name of the host with which to connect
port - number of the server's port
Throws:
IOException - if an I/O error occurs when creating the socket
UnknownHostException - if the host is not known

SSLSocket

protected SSLSocket(InetAddress address,
                    int port)
             throws IOException
Used only by subclasses. Constructs a TCP connection to a server at a specified address and port. This acts as the SSL client.

Parameters:
address - the server's host
port - its port
Throws:
IOException - if an I/O error occurs when creating the socket

SSLSocket

protected SSLSocket(String host,
                    int port,
                    InetAddress clientAddress,
                    int clientPort)
             throws IOException,
                    UnknownHostException
Used only by subclasses. Constructs an SSL connection to a named host at a specified port, binding the client side of the connection a given address and port. This acts as the SSL client.

Parameters:
host - name of the host with which to connect
port - number of the server's port
clientAddress - the client's host
clientPort - number of the client's port
Throws:
IOException - if an I/O error occurs when creating the socket
UnknownHostException - if the host is not known

SSLSocket

protected SSLSocket(InetAddress address,
                    int port,
                    InetAddress clientAddress,
                    int clientPort)
             throws IOException
Used only by subclasses. Constructs an SSL connection to a server at a specified address and TCP port, binding the client side of the connection a given address and port. This acts as the SSL client.

Parameters:
address - the server's host
port - its port
clientAddress - the client's host
clientPort - number of the client's port
Throws:
IOException - if an I/O error occurs when creating the socket
Method Detail

getSupportedCipherSuites

public abstract String[] getSupportedCipherSuites()
Returns the names of the cipher suites which could be enabled for use on this connection. Normally, only a subset of these will actually be enabled by default, since this list may include cipher suites which do not meet quality of service requirements for those defaults. Such cipher suites might be useful in specialized applications.

Returns:
an array of cipher suite names
See Also:
getEnabledCipherSuites(), setEnabledCipherSuites(String [])

getEnabledCipherSuites

public abstract String[] getEnabledCipherSuites()
Returns the names of the SSL cipher suites which are currently enabled for use on this connection. When an SSLSocket is first created, all enabled cipher suites support a minimum quality of service. Thus, in some environments this value might be empty.

Even if a suite has been enabled, it might never be used. (For example, the peer does not support it, the requisite certificates (and private keys) for the suite are not available, or an anonymous suite is enabled but authentication is required.

Returns:
an array of cipher suite names
See Also:
getSupportedCipherSuites(), setEnabledCipherSuites(String [])

setEnabledCipherSuites

public abstract void setEnabledCipherSuites(String[] suites)
Sets the cipher suites enabled for use on this connection.

Each cipher suite in the suites parameter must have been listed by getSupportedCipherSuites(), or the method will fail. Following a successful call to this method, only suites listed in the suites parameter are enabled for use.

See getEnabledCipherSuites() for more information on why a specific ciphersuite may never be used on a connection.

Parameters:
suites - Names of all the cipher suites to enable
Throws:
IllegalArgumentException - when one or more of the ciphers named by the parameter is not supported, or when the parameter is null.
See Also:
getSupportedCipherSuites(), getEnabledCipherSuites()

getSupportedProtocols

public abstract String[] getSupportedProtocols()
Returns the names of the protocols which could be enabled for use on an SSL connection.

Returns:
an array of protocols supported

getEnabledProtocols

public abstract String[] getEnabledProtocols()
Returns the names of the protocol versions which are currently enabled for use on this connection.

Returns:
an array of protocols
See Also:
setEnabledProtocols(String [])

setEnabledProtocols

public abstract void setEnabledProtocols(String[] protocols)
Sets the protocol versions enabled for use on this connection.

The protocols must have been listed by getSupportedProtocols() as being supported. Following a successful call to this method, only protocols listed in the protocols parameter are enabled for use.

Parameters:
protocols - Names of all the protocols to enable.
Throws:
IllegalArgumentException - when one or more of the protocols named by the parameter is not supported or when the protocols parameter is null.
See Also:
getEnabledProtocols()

getSession

public abstract SSLSession getSession()
Returns the SSL Session in use by this connection. These can be long lived, and frequently correspond to an entire login session for some user. The session specifies a particular cipher suite which is being actively used by all connections in that session, as well as the identities of the session's client and server.

This method will initiate the initial handshake if necessary and then block until the handshake has been established.

If an error occurs during the initial handshake, this method returns an invalid session object which reports an invalid cipher suite of "SSL_NULL_WITH_NULL_NULL".

Returns:
the SSLSession

addHandshakeCompletedListener

public abstract void addHandshakeCompletedListener(HandshakeCompletedListener listener)
Registers an event listener to receive notifications that an SSL handshake has completed on this connection.

Parameters:
listener - the HandShake Completed event listener
Throws:
IllegalArgumentException - if the argument is null.
See Also:
startHandshake(), removeHandshakeCompletedListener(HandshakeCompletedListener)

removeHandshakeCompletedListener

public abstract void removeHandshakeCompletedListener(HandshakeCompletedListener listener)
Removes a previously registered handshake completion listener.

Parameters:
listener - the HandShake Completed event listener
Throws:
IllegalArgumentException - if the listener is not registered, or the argument is null.
See Also:
addHandshakeCompletedListener(HandshakeCompletedListener)

startHandshake

public abstract void startHandshake()
                             throws IOException
Starts an SSL handshake on this connection. Common reasons include a need to use new encryption keys, to change cipher suites, or to initiate a new session. To force complete reauthentication, the current session could be invalidated before starting this handshake.

If data has already been sent on the connection, it continues to flow during this handshake. When the handshake completes, this will be signaled with an event. This method is synchronous for the initial handshake on a connection and returns when the negotiated handshake is complete. Some protocols may not support multiple handshakes on an existing socket and may throw an IOException.

Throws:
IOException - on a network level error
See Also:
addHandshakeCompletedListener(HandshakeCompletedListener)

setUseClientMode

public abstract void setUseClientMode(boolean mode)
Configures the socket to use client (or server) mode when handshaking.

This method must be called before any handshaking occurs. Once handshaking has begun, the mode can not be reset for the life of this socket.

Servers normally authenticate themselves, and clients are not required to do so.

Parameters:
mode - true if the socket should start its handshaking in "client" mode
Throws:
IllegalArgumentException - if a mode change is attempted after the initial handshake has begun.
See Also:
getUseClientMode()

getUseClientMode

public abstract boolean getUseClientMode()
Returns true if the socket is set to use client mode when handshaking.

Returns:
true if the socket should do handshaking in "client" mode
See Also:
setUseClientMode(boolean)

setNeedClientAuth

public abstract void setNeedClientAuth(boolean need)
Configures the socket to require client authentication. This option is only useful for sockets in the server mode.

A socket's client authentication setting is one of the following:

  • client authentication required
  • client authentication requested
  • no client authentication desired

Unlike setWantClientAuth(boolean), if this option is set and the client chooses not to provide authentication information about itself, the negotiations will stop and the connection will be dropped.

Calling this method overrides any previous setting made by this method or setWantClientAuth(boolean).

Parameters:
need - set to true if client authentication is required, or false if no client authentication is desired.
See Also:
getNeedClientAuth(), setWantClientAuth(boolean), getWantClientAuth(), setUseClientMode(boolean)

getNeedClientAuth

public abstract boolean getNeedClientAuth()
Returns true if the socket will require client authentication. This option is only useful to sockets in the server mode.

Returns:
true if client authentication is required, or false if no client authentication is desired.
See Also:
setNeedClientAuth(boolean), setWantClientAuth(boolean), getWantClientAuth(), setUseClientMode(boolean)

setWantClientAuth

public abstract void setWantClientAuth(boolean want)
Configures the socket to request client authentication. This option is only useful for sockets in the server mode.

A socket's client authentication setting is one of the following:

  • client authentication required
  • client authentication requested
  • no client authentication desired

Unlike setNeedClientAuth(boolean), if this option is set and the client chooses not to provide authentication information about itself, the negotiations will continue.

Calling this method overrides any previous setting made by this method or setNeedClientAuth(boolean).

Parameters:
want - set to true if client authentication is requested, or false if no client authentication is desired.
See Also:
getWantClientAuth(), setNeedClientAuth(boolean), getNeedClientAuth(), setUseClientMode(boolean)

getWantClientAuth

public abstract boolean getWantClientAuth()
Returns true if the socket will request client authentication. This option is only useful for sockets in the server mode.

Returns:
true if client authentication is requested, or false if no client authentication is desired.
See Also:
setNeedClientAuth(boolean), getNeedClientAuth(), setWantClientAuth(boolean), setUseClientMode(boolean)

setEnableSessionCreation

public abstract void setEnableSessionCreation(boolean flag)
Controls whether new SSL sessions may be established by this socket. If session creations are not allowed, and there are no existing sessions to resume, there will be no successful handshaking.

Parameters:
flag - true indicates that sessions may be created; this is the default. false indicates that an existing session must be resumed
See Also:
getEnableSessionCreation()

getEnableSessionCreation

public abstract boolean getEnableSessionCreation()
Returns true if new SSL sessions may be established by this socket.

Returns:
true indicates that sessions may be created; this is the default. false indicates that an existing session must be resumed
See Also:
setEnableSessionCreation(boolean)

getSSLParameters

public SSLParameters getSSLParameters()
Returns the SSLParameters in effect for this SSLSocket. The ciphersuites and protocols of the returned SSLParameters are always non-null.

Returns:
the SSLParameters in effect for this SSLSocket.
Since:
1.6

setSSLParameters

public void setSSLParameters(SSLParameters params)
Applies SSLParameters to this socket.

This means:

  • if params.getCipherSuites() is non-null, setEnabledCipherSuites() is called with that value
  • if params.getProtocols() is non-null, setEnabledProtocols() is called with that value
  • if params.getNeedClientAuth() or params.getWantClientAuth() return true, setNeedClientAuth(true) and setWantClientAuth(true) are called, respectively; otherwise setWantClientAuth(false) is called.

Parameters:
params - the parameters
Throws:
IllegalArgumentException - if the setEnabledCipherSuites() or the setEnabledProtocols() call fails
Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SSLSocketFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class SSLSocketFactory

java.lang.Object
    extended by  javax.net.SocketFactory
        extended by  javax.net.ssl.SSLSocketFactory

public abstract class SSLSocketFactory
extends SocketFactory

SSLSocketFactorys create SSLSockets.

Since:
1.4
See Also:
SSLSocket

Constructor Summary
SSLSocketFactory()
Constructor is used only by subclasses.
Method Summary
abstract Socket | createSocket(Socket s, String host, int port, boolean autoClose) Returns a socket layered over an existing socket connected to the named host, at the given port.
static SocketFactory | getDefault() Returns the default SSL socket factory.
abstract String[] | getDefaultCipherSuites() Returns the list of cipher suites which are enabled by default.
abstract String[] | getSupportedCipherSuites() Returns the names of the cipher suites which could be enabled for use on an SSL connection.
Methods inherited from class javax.net.SocketFactory
createSocket, createSocket, createSocket, createSocket, createSocket
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SSLSocketFactory

public SSLSocketFactory()
Constructor is used only by subclasses.

Method Detail

getDefault

public static SocketFactory getDefault()
Returns the default SSL socket factory.

The first time this method is called, the security property "ssl.SocketFactory.provider" is examined. If it is non-null, a class by that name is loaded and instantiated. If that is successful and the object is an instance of SSLSocketFactory, it is made the default SSL socket factory.

Otherwise, this method returns SSLContext.getDefault().getSocketFactory(). If that call fails, an inoperative factory is returned.

Returns:
the default SocketFactory
See Also:
SSLContext.getDefault()

getDefaultCipherSuites

public abstract String[] getDefaultCipherSuites()
Returns the list of cipher suites which are enabled by default. Unless a different list is enabled, handshaking on an SSL connection will use one of these cipher suites. The minimum quality of service for these defaults requires confidentiality protection and server authentication (that is, no anonymous cipher suites).

Returns:
array of the cipher suites enabled by default
See Also:
getSupportedCipherSuites()

getSupportedCipherSuites

public abstract String[] getSupportedCipherSuites()
Returns the names of the cipher suites which could be enabled for use on an SSL connection. Normally, only a subset of these will actually be enabled by default, since this list may include cipher suites which do not meet quality of service requirements for those defaults. Such cipher suites are useful in specialized applications.

Returns:
an array of cipher suite names
See Also:
getDefaultCipherSuites()

createSocket

public abstract Socket createSocket(Socket s,
                                    String host,
                                    int port,
                                    boolean autoClose)
                             throws IOException
Returns a socket layered over an existing socket connected to the named host, at the given port. This constructor can be used when tunneling SSL through a proxy or when negotiating the use of SSL over an existing socket. The host and port refer to the logical peer destination. This socket is configured using the socket options established for this factory.

Parameters:
s - the existing socket
host - the server host
port - the server port
autoClose - close the underlying socket when this socket is closed
Returns:
a socket connected to the specified host and port
Throws:
IOException - if an I/O error occurs when creating the socket
UnknownHostException - if the host is not known
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TrustManagerFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class TrustManagerFactory

java.lang.Object
    extended by  javax.net.ssl.TrustManagerFactory

public class TrustManagerFactory
extends Object

This class acts as a factory for trust managers based on a source of trust material. Each trust manager manages a specific type of trust material for use by secure sockets. The trust material is based on a KeyStore and/or provider specific sources.

Since:
1.4
See Also:
TrustManager

Constructor Summary
protected TrustManagerFactory(TrustManagerFactorySpi factorySpi, Provider provider, String algorithm)
Creates a TrustManagerFactory object.
Method Summary
String | getAlgorithm() Returns the algorithm name of this TrustManagerFactory object.
static String | getDefaultAlgorithm() Obtains the default TrustManagerFactory algorithm name.
static TrustManagerFactory | getInstance(String algorithm) Returns a TrustManagerFactory object that acts as a factory for trust managers.
static TrustManagerFactory | getInstance(String algorithm, Provider provider) Returns a TrustManagerFactory object that acts as a factory for trust managers.
static TrustManagerFactory | getInstance(String algorithm, String provider) Returns a TrustManagerFactory object that acts as a factory for trust managers.
Provider | getProvider() Returns the provider of this TrustManagerFactory object.
TrustManager[] | getTrustManagers() Returns one trust manager for each type of trust material.
void | init(KeyStore ks) Initializes this factory with a source of certificate authorities and related trust material.
void | init(ManagerFactoryParameters spec) Initializes this factory with a source of provider-specific trust material.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TrustManagerFactory

protected TrustManagerFactory(TrustManagerFactorySpi factorySpi,
                              Provider provider,
                              String algorithm)
Creates a TrustManagerFactory object.

Parameters:
factorySpi - the delegate
provider - the provider
algorithm - the algorithm
Method Detail

getDefaultAlgorithm

public static final String getDefaultAlgorithm()
Obtains the default TrustManagerFactory algorithm name.

The default TrustManager can be changed at runtime by setting the value of the "ssl.TrustManagerFactory.algorithm" security property (set in the Java security properties file or by calling Security.setProperty(String, String)) to the desired algorithm name.

Returns:
the default algorithm name as specified in the Java security properties, or an implementation-specific default if no such property exists.

getAlgorithm

public final String getAlgorithm()
Returns the algorithm name of this TrustManagerFactory object.

This is the same name that was specified in one of the getInstance calls that created this TrustManagerFactory object.

Returns:
the algorithm name of this TrustManagerFactory object

getInstance

public static final TrustManagerFactory getInstance(String algorithm)
                                             throws NoSuchAlgorithmException
Returns a TrustManagerFactory object that acts as a factory for trust managers.

This method traverses the list of registered security Providers, starting with the most preferred Provider. A new TrustManagerFactory object encapsulating the TrustManagerFactorySpi implementation from the first Provider that supports the specified algorithm is returned.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters:
algorithm - the standard name of the requested trust management algorithm. See the Java Secure Socket Extension Reference Guide for information about standard algorithm names.
Returns:
the new TrustManagerFactory object.
Throws:
NoSuchAlgorithmException - if no Provider supports a TrustManagerFactorySpi implementation for the specified algorithm.
See Also:
Provider

getInstance

public static final TrustManagerFactory getInstance(String algorithm,
                                                    String provider)
                                             throws NoSuchAlgorithmException,
                                                    NoSuchProviderException
Returns a TrustManagerFactory object that acts as a factory for trust managers.

A new KeyManagerFactory object encapsulating the KeyManagerFactorySpi implementation from the specified provider is returned. The specified provider must be registered in the security provider list.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters:
algorithm - the standard name of the requested trust management algorithm. See the Java Secure Socket Extension Reference Guide for information about standard algorithm names.
provider - the name of the provider.
Returns:
the new TrustManagerFactory object
Throws:
NoSuchAlgorithmException - if a TrustManagerFactorySpi implementation for the specified algorithm is not available from the specified provider.
NoSuchProviderException - if the specified provider is not registered in the security provider list.
IllegalArgumentException - if the provider name is null or empty.
See Also:
Provider

getInstance

public static final TrustManagerFactory getInstance(String algorithm,
                                                    Provider provider)
                                             throws NoSuchAlgorithmException
Returns a TrustManagerFactory object that acts as a factory for trust managers.

A new TrustManagerFactory object encapsulating the TrustManagerFactorySpi implementation from the specified Provider object is returned. Note that the specified Provider object does not have to be registered in the provider list.

Parameters:
algorithm - the standard name of the requested trust management algorithm. See the Java Secure Socket Extension Reference Guide for information about standard algorithm names.
provider - an instance of the provider.
Returns:
the new TrustManagerFactory object.
Throws:
NoSuchAlgorithmException - if a TrustManagerFactorySpi implementation for the specified algorithm is not available from the specified Provider object.
IllegalArgumentException - if the provider is null.
See Also:
Provider

getProvider

public final Provider getProvider()
Returns the provider of this TrustManagerFactory object.

Returns:
the provider of this TrustManagerFactory object

init

public final void init(KeyStore ks)
                throws KeyStoreException
Initializes this factory with a source of certificate authorities and related trust material.

The provider typically uses a KeyStore as a basis for making trust decisions.

For more flexible initialization, please see init(ManagerFactoryParameters).

Parameters:
ks - the key store, or null
Throws:
KeyStoreException - if this operation fails

init

public final void init(ManagerFactoryParameters spec)
                throws InvalidAlgorithmParameterException
Initializes this factory with a source of provider-specific trust material.

In some cases, initialization parameters other than a keystore may be needed by a provider. Users of that particular provider are expected to pass an implementation of the appropriate ManagerFactoryParameters as defined by the provider. The provider can then call the specified methods in the ManagerFactoryParameters implementation to obtain the needed information.

Parameters:
spec - an implementation of a provider-specific parameter specification
Throws:
InvalidAlgorithmParameterException - if an error is encountered

getTrustManagers

public final TrustManager[] getTrustManagers()
Returns one trust manager for each type of trust material.

Returns:
the trust managers
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TrustManagerFactorySpi

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class TrustManagerFactorySpi

java.lang.Object
    extended by  javax.net.ssl.TrustManagerFactorySpi

public abstract class TrustManagerFactorySpi
extends Object

This class defines the Service Provider Interface (SPI) for the TrustManagerFactory class.

All the abstract methods in this class must be implemented by each cryptographic service provider who wishes to supply the implementation of a particular trust manager factory.

Since:
1.4
See Also:
TrustManagerFactory, TrustManager

Constructor Summary
TrustManagerFactorySpi()
Method Summary
protected abstract TrustManager[] | engineGetTrustManagers() Returns one trust manager for each type of trust material.
protected abstract void | engineInit(KeyStore ks) Initializes this factory with a source of certificate authorities and related trust material.
protected abstract void | engineInit(ManagerFactoryParameters spec) Initializes this factory with a source of provider-specific key material.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TrustManagerFactorySpi

public TrustManagerFactorySpi()
Method Detail

engineInit

protected abstract void engineInit(KeyStore ks)
                            throws KeyStoreException
Initializes this factory with a source of certificate authorities and related trust material.

Parameters:
ks - the key store or null
Throws:
KeyStoreException - if this operation fails
See Also:
TrustManagerFactory.init(KeyStore)

engineInit

protected abstract void engineInit(ManagerFactoryParameters spec)
                            throws InvalidAlgorithmParameterException
Initializes this factory with a source of provider-specific key material.

In some cases, initialization parameters other than a keystore may be needed by a provider. Users of that particular provider are expected to pass an implementation of the appropriate ManagerFactoryParameters as defined by the provider. The provider can then call the specified methods in the ManagerFactoryParameters implementation to obtain the needed information.

Parameters:
spec - an implementation of a provider-specific parameter specification
Throws:
InvalidAlgorithmParameterException - if there is problem with the parameters
See Also:
TrustManagerFactory.init(ManagerFactoryParameters spec)

engineGetTrustManagers

protected abstract TrustManager[] engineGetTrustManagers()
Returns one trust manager for each type of trust material.

Returns:
the trust managers
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


X509ExtendedKeyManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Class X509ExtendedKeyManager

java.lang.Object
    extended by  javax.net.ssl.X509ExtendedKeyManager
All Implemented Interfaces:
KeyManager, X509KeyManager
public abstract class X509ExtendedKeyManager
extends Object
implements X509KeyManager

Abstract class that provides for extension of the X509KeyManager interface.

Methods in this class should be overriden to provide actual implementations.

Since:
1.5

Constructor Summary
protected X509ExtendedKeyManager()
Constructor used by subclasses only.
Method Summary
String | chooseEngineClientAlias(String[] keyType, Principal[] issuers, SSLEngine engine) Choose an alias to authenticate the client side of an SSLEngine connection given the public key type and the list of certificate issuer authorities recognized by the peer (if any).
String | chooseEngineServerAlias(String keyType, Principal[] issuers, SSLEngine engine) Choose an alias to authenticate the server side of an SSLEngine connection given the public key type and the list of certificate issuer authorities recognized by the peer (if any).
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.net.ssl.X509KeyManager
chooseClientAlias, chooseServerAlias, getCertificateChain, getClientAliases, getPrivateKey, getServerAliases

Constructor Detail

X509ExtendedKeyManager

protected X509ExtendedKeyManager()
Constructor used by subclasses only.

Method Detail

chooseEngineClientAlias

public String chooseEngineClientAlias(String[] keyType,
                                      Principal[] issuers,
                                      SSLEngine engine)
Choose an alias to authenticate the client side of an SSLEngine connection given the public key type and the list of certificate issuer authorities recognized by the peer (if any).

The default implementation returns null.

Parameters:
keyType - the key algorithm type name(s), ordered with the most-preferred key type first.
issuers - the list of acceptable CA issuer subject names or null if it does not matter which issuers are used.
engine - the SSLEngine to be used for this connection. This parameter can be null, which indicates that implementations of this interface are free to select an alias applicable to any engine.
Returns:
the alias name for the desired key, or null if there are no matches.

chooseEngineServerAlias

public String chooseEngineServerAlias(String keyType,
                                      Principal[] issuers,
                                      SSLEngine engine)
Choose an alias to authenticate the server side of an SSLEngine connection given the public key type and the list of certificate issuer authorities recognized by the peer (if any).

The default implementation returns null.

Parameters:
keyType - the key algorithm type name.
issuers - the list of acceptable CA issuer subject names or null if it does not matter which issuers are used.
engine - the SSLEngine to be used for this connection. This parameter can be null, which indicates that implementations of this interface are free to select an alias applicable to any engine.
Returns:
the alias name for the desired key, or null if there are no matches.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


X509KeyManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Interface X509KeyManager

All Superinterfaces:
KeyManager
All Known Implementing Classes:
X509ExtendedKeyManager
public interface X509KeyManager
extends KeyManager

Instances of this interface manage which X509 certificate-based key pairs are used to authenticate the local side of a secure socket.

During secure socket negotiations, implentations call methods in this interface to:

  • determine the set of aliases that are available for negotiations based on the criteria presented,
  • select the best alias based on the criteria presented, and
  • obtain the corresponding key material for given aliases.

Note: the X509ExtendedKeyManager should be used in favor of this class.

Since:
1.4

Method Summary
String | chooseClientAlias(String[] keyType, Principal[] issuers, Socket socket) Choose an alias to authenticate the client side of a secure socket given the public key type and the list of certificate issuer authorities recognized by the peer (if any).
String | chooseServerAlias(String keyType, Principal[] issuers, Socket socket) Choose an alias to authenticate the server side of a secure socket given the public key type and the list of certificate issuer authorities recognized by the peer (if any).
X509Certificate[] | getCertificateChain(String alias) Returns the certificate chain associated with the given alias.
String[] | getClientAliases(String keyType, Principal[] issuers) Get the matching aliases for authenticating the client side of a secure socket given the public key type and the list of certificate issuer authorities recognized by the peer (if any).
PrivateKey | getPrivateKey(String alias) Returns the key associated with the given alias.
String[] | getServerAliases(String keyType, Principal[] issuers) Get the matching aliases for authenticating the server side of a secure socket given the public key type and the list of certificate issuer authorities recognized by the peer (if any).

Method Detail

getClientAliases

String[] getClientAliases(String keyType,
                          Principal[] issuers)
Get the matching aliases for authenticating the client side of a secure socket given the public key type and the list of certificate issuer authorities recognized by the peer (if any).

Parameters:
keyType - the key algorithm type name
issuers - the list of acceptable CA issuer subject names, or null if it does not matter which issuers are used.
Returns:
an array of the matching alias names, or null if there were no matches.

chooseClientAlias

String chooseClientAlias(String[] keyType,
                         Principal[] issuers,
                         Socket socket)
Choose an alias to authenticate the client side of a secure socket given the public key type and the list of certificate issuer authorities recognized by the peer (if any).

Parameters:
keyType - the key algorithm type name(s), ordered with the most-preferred key type first.
issuers - the list of acceptable CA issuer subject names or null if it does not matter which issuers are used.
socket - the socket to be used for this connection. This parameter can be null, which indicates that implementations are free to select an alias applicable to any socket.
Returns:
the alias name for the desired key, or null if there are no matches.

getServerAliases

String[] getServerAliases(String keyType,
                          Principal[] issuers)
Get the matching aliases for authenticating the server side of a secure socket given the public key type and the list of certificate issuer authorities recognized by the peer (if any).

Parameters:
keyType - the key algorithm type name
issuers - the list of acceptable CA issuer subject names or null if it does not matter which issuers are used.
Returns:
an array of the matching alias names, or null if there were no matches.

chooseServerAlias

String chooseServerAlias(String keyType,
                         Principal[] issuers,
                         Socket socket)
Choose an alias to authenticate the server side of a secure socket given the public key type and the list of certificate issuer authorities recognized by the peer (if any).

Parameters:
keyType - the key algorithm type name.
issuers - the list of acceptable CA issuer subject names or null if it does not matter which issuers are used.
socket - the socket to be used for this connection. This parameter can be null, which indicates that implementations are free to select an alias applicable to any socket.
Returns:
the alias name for the desired key, or null if there are no matches.

getCertificateChain

X509Certificate[] getCertificateChain(String alias)
Returns the certificate chain associated with the given alias.

Parameters:
alias - the alias name
Returns:
the certificate chain (ordered with the user's certificate first and the root certificate authority last), or null if the alias can't be found.

getPrivateKey

PrivateKey getPrivateKey(String alias)
Returns the key associated with the given alias.

Parameters:
alias - the alias name
Returns:
the requested key, or null if the alias can't be found.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


X509TrustManager

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.net.ssl
Interface X509TrustManager

All Superinterfaces:
TrustManager
public interface X509TrustManager
extends TrustManager

Instance of this interface manage which X509 certificates may be used to authenticate the remote side of a secure socket. Decisions may be based on trusted certificate authorities, certificate revocation lists, online status checking or other means.

Since:
1.4

Method Summary
void | checkClientTrusted(X509Certificate[] chain, String authType) Given the partial or complete certificate chain provided by the peer, build a certificate path to a trusted root and return if it can be validated and is trusted for client SSL authentication based on the authentication type.
void | checkServerTrusted(X509Certificate[] chain, String authType) Given the partial or complete certificate chain provided by the peer, build a certificate path to a trusted root and return if it can be validated and is trusted for server SSL authentication based on the authentication type.
X509Certificate[] | getAcceptedIssuers() Return an array of certificate authority certificates which are trusted for authenticating peers.

Method Detail

checkClientTrusted

void checkClientTrusted(X509Certificate[] chain,
                        String authType)
                        throws CertificateException
Given the partial or complete certificate chain provided by the peer, build a certificate path to a trusted root and return if it can be validated and is trusted for client SSL authentication based on the authentication type.

The authentication type is determined by the actual certificate used. For instance, if RSAPublicKey is used, the authType should be "RSA". Checking is case-sensitive.

Parameters:
chain - the peer certificate chain
authType - the authentication type based on the client certificate
Throws:
IllegalArgumentException - if null or zero-length chain is passed in for the chain parameter or if null or zero-length string is passed in for the authType parameter
CertificateException - if the certificate chain is not trusted by this TrustManager.

checkServerTrusted

void checkServerTrusted(X509Certificate[] chain,
                        String authType)
                        throws CertificateException
Given the partial or complete certificate chain provided by the peer, build a certificate path to a trusted root and return if it can be validated and is trusted for server SSL authentication based on the authentication type.

The authentication type is the key exchange algorithm portion of the cipher suites represented as a String, such as "RSA", "DHE_DSS". Note: for some exportable cipher suites, the key exchange algorithm is determined at run time during the handshake. For instance, for TLS_RSA_EXPORT_WITH_RC4_40_MD5, the authType should be RSA_EXPORT when an ephemeral RSA key is used for the key exchange, and RSA when the key from the server certificate is used. Checking is case-sensitive.

Parameters:
chain - the peer certificate chain
authType - the key exchange algorithm used
Throws:
IllegalArgumentException - if null or zero-length chain is passed in for the chain parameter or if null or zero-length string is passed in for the authType parameter
CertificateException - if the certificate chain is not trusted by this TrustManager.

getAcceptedIssuers

X509Certificate[] getAcceptedIssuers()
Return an array of certificate authority certificates which are trusted for authenticating peers.

Returns:
a non-null (possibly empty) array of acceptable CA issuer certificates.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


print

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.print

Provides the principal classes and interfaces for the JavaTM Print Service API.

See:
Description

Interface Summary
AttributeException | Interface AttributeException is a mixin interface which a subclass of PrintException can implement to report an error condition involving one or more printing attributes that a particular Print Service instance does not support.
CancelablePrintJob | This interface is used by a printing application to cancel a print job.
Doc | Interface Doc specifies the interface for an object that supplies one piece of print data for a Print Job.
DocPrintJob | This interface represents a print job that can print a specified document with a set of job attributes.
FlavorException | Interface FlavorException is a mixin interface which a subclass of PrintException can implement to report an error condition involving a doc flavor or flavors (class DocFlavor).
MultiDoc | Interface MultiDoc specifies the interface for an object that supplies more than one piece of print data for a Print Job.
MultiDocPrintJob | Obtained from a MultiDocPrintService, a MultiDocPrintJob can print a specified collection of documents as a single print job with a set of job attributes.
MultiDocPrintService | Interface MultiPrintService is the factory for a MultiDocPrintJob.
PrintService | Interface PrintService is the factory for a DocPrintJob.
URIException | Interface URIException is a mixin interface which a subclass of PrintException can implement to report an error condition involving a URI address.

Class Summary
DocFlavor | Class DocFlavor encapsulates an object that specifies the format in which print data is supplied to a DocPrintJob.
DocFlavor.BYTE_ARRAY | Class DocFlavor.BYTE_ARRAY provides predefined static constant DocFlavor objects for example doc flavors using a byte array (byte[]) as the print data representation class.
DocFlavor.CHAR_ARRAY | Class DocFlavor.CHAR_ARRAY provides predefined static constant DocFlavor objects for example doc flavors using a character array (char[]) as the print data representation class.
DocFlavor.INPUT_STREAM | Class DocFlavor.INPUT_STREAM provides predefined static constant DocFlavor objects for example doc flavors using a byte stream (java.io.InputStream) as the print data representation class.
DocFlavor.READER | Class DocFlavor.READER provides predefined static constant DocFlavor objects for example doc flavors using a character stream (java.io.Reader) as the print data representation class.
DocFlavor.SERVICE_FORMATTED | Class DocFlavor.SERVICE_FORMATTED provides predefined static constant DocFlavor objects for example doc flavors for service formatted print data.
DocFlavor.STRING | Class DocFlavor.STRING provides predefined static constant DocFlavor objects for example doc flavors using a string (java.lang.String) as the print data representation class.
DocFlavor.URL | Class DocFlavor.URL provides predefined static constant DocFlavor objects.
PrintServiceLookup | Implementations of this class provide lookup services for print services (typically equivalent to printers) of a particular type.
ServiceUI | This class is a collection of UI convenience methods which provide a graphical user dialog for browsing print services looked up through the Java Print Service API.
ServiceUIFactory | Services may optionally provide UIs which allow different styles of interaction in different roles.
SimpleDoc | This class is an implementation of interface Doc that can be used in many common printing requests.
StreamPrintService | This class extends PrintService and represents a print service that prints data in different formats to a client-provided output stream.
StreamPrintServiceFactory | A StreamPrintServiceFactory is the factory for StreamPrintService instances, which can print to an output stream in a particular document format described as a mime type.

Exception Summary
PrintException Class PrintException encapsulates a printing-related error condition that occurred while using a Print Service instance.

Package javax.print Description

Provides the principal classes and interfaces for the JavaTM Print Service API. The Java Print Service API enables client and server applications to:

  • Discover and select print services based on their capabilities
  • Specify the format of print data
  • Submit print jobs to services that support the document type to be printed.

Print Service Discovery

An application invokes the static methods of the abstract class PrintServiceLookup to locate print services that have the capabilities to satisfy the application's print request. For example, to print a double-sided document, the application first needs to find printers that have the double-sided printing capability.

The JDK includes PrintServiceLookup implementations that can locate the standard platform printers. To locate other types of printers, such as IPP printers or JINI printers, a print-service provider can write implementations of PrintServiceLookup. The print-service provider can dynamically install these PrintServiceLookup implementations using the SPI JAR file specification.

Attribute Definitions

The javax.print.attribute and javax.print.attribute.standard packages define print attributes, which describe the capabilities of a print service, specify the requirements of a print job, and track the progress of a print job.

The javax.print.attribute package describes the types of attributes and how they can be collected into sets. The javax.print.attribute.standard package enumerates all of the standard attributes supported by the API, most of which are implementations of attributes specified in the IETF Specification, RFC 2911 Internet Printing Protocol, 1.1: Model and Semantics, dated September 2000. The attributes specified in javax.print.attribute.standard include common capabilites, such as: resolution, copies, media sizes, job priority, and page ranges.

Document Type Specification

The DocFlavor class represents the print data format, such as JPEG or PostScript. A DocFlavor object consists of a MIME type, which describes the format, and a document representation class name that indicates how the document is delivered to the printer or output stream. An application uses the DocFlavor and an attribute set to find printers that can print the document type specified by the DocFlavor and have the capabilities specified by the attribute set.

Using the API

A typical application using the Java Print Service API performs these steps to process a print request:
  1. Chooses a DocFlavor.
  2. Creates a set of attributes.
  3. Locates a print service that can handle the print request as specified by the DocFlavor and the attribute set.
  4. Creates a Doc object encapsulating the DocFlavor and the actual print data, which can take many forms including: a Postscript file, a JPEG image, a URL, or plain text.
  5. Gets a print job, represented by DocPrintJob, from the print service.
  6. Calls the print method of the print job.
The following code sample demonstrates a typical use of the Java Print Service API: locating printers that can print five double-sided copies of a Postscript document on size A4 paper, creating a print job from one of the returned print services, and calling print.

FileInputStream psStream;
try {
   psStream = new FileInputStream("file.ps");
} catch (FileNotFoundException ffne) {
}
if (psStream == null) {
    return;
}

DocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;
Doc myDoc = new SimpleDoc(psStream, psInFormat, null);
PrintRequestAttributeSet aset =
        new HashPrintRequestAttributeSet();
aset.add(new Copies(5));
aset.add(MediaSize.A4);
aset.add(Sides.DUPLEX);
PrintService[] services =
  PrintServiceLookup.lookupPrintServices(psInFormat, aset);
if (services.length > 0) {
   DocPrintJob job = services[0].createPrintJob();
   try {
        job.print(myDoc, aset);
   } catch (PrintException pe) {}
}

Please note: In the javax.print APIs, a null reference parameter to methods is incorrect unless explicitly documented on the method as having a meaningful interpretation. Usage to the contrary is incorrect coding and may result in a run time exception either immediately or at some later time. IllegalArgumentException and NullPointerException are examples of typical and acceptable run time exceptions for such cases.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.print Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.print

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.print.DocFlavor (implements java.lang.Cloneable, java.io.Serializable)
      • javax.print.DocFlavor.BYTE_ARRAY
      • javax.print.DocFlavor.CHAR_ARRAY
      • javax.print.DocFlavor.INPUT_STREAM
      • javax.print.DocFlavor.READER
      • javax.print.DocFlavor.SERVICE_FORMATTED
      • javax.print.DocFlavor.STRING
      • javax.print.DocFlavor.URL
    • javax.print.PrintServiceLookup
    • javax.print.ServiceUI
    • javax.print.ServiceUIFactory
    • javax.print.SimpleDoc (implements javax.print.Doc)
    • javax.print.StreamPrintService (implements javax.print.PrintService)
    • javax.print.StreamPrintServiceFactory
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.print.PrintException

Interface Hierarchy

  • javax.print.AttributeException
  • javax.print.Doc
  • javax.print.DocPrintJob
    • javax.print.CancelablePrintJob
    • javax.print.MultiDocPrintJob
  • javax.print.FlavorException
  • javax.print.MultiDoc
  • javax.print.PrintService
    • javax.print.MultiDocPrintService
  • javax.print.URIException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.print

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.print

Packages that use javax.print
java.awt.print | Provides classes and interfaces for a general printing API.
javax.print | Provides the principal classes and interfaces for the JavaTM Print Service API.
javax.print.event | Package javax.print.event contains event classes and listener interfaces.
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Classes in javax.print used by java.awt.print
PrintService
Interface PrintService is the factory for a DocPrintJob.
StreamPrintServiceFactory
A StreamPrintServiceFactory is the factory for StreamPrintService instances, which can print to an output stream in a particular document format described as a mime type.

Classes in javax.print used by javax.print
Doc
Interface Doc specifies the interface for an object that supplies one piece of print data for a Print Job.
DocFlavor
Class DocFlavor encapsulates an object that specifies the format in which print data is supplied to a DocPrintJob.
DocFlavor.BYTE_ARRAY
Class DocFlavor.BYTE_ARRAY provides predefined static constant DocFlavor objects for example doc flavors using a byte array (byte[]) as the print data representation class.
DocFlavor.CHAR_ARRAY
Class DocFlavor.CHAR_ARRAY provides predefined static constant DocFlavor objects for example doc flavors using a character array (char[]) as the print data representation class.
DocFlavor.INPUT_STREAM
Class DocFlavor.INPUT_STREAM provides predefined static constant DocFlavor objects for example doc flavors using a byte stream (java.io.InputStream) as the print data representation class.
DocFlavor.READER
Class DocFlavor.READER provides predefined static constant DocFlavor objects for example doc flavors using a character stream (java.io.Reader) as the print data representation class.
DocFlavor.SERVICE_FORMATTED
Class DocFlavor.SERVICE_FORMATTED provides predefined static constant DocFlavor objects for example doc flavors for service formatted print data.
DocFlavor.STRING
Class DocFlavor.STRING provides predefined static constant DocFlavor objects for example doc flavors using a string (java.lang.String) as the print data representation class.
DocFlavor.URL
Class DocFlavor.URL provides predefined static constant DocFlavor objects.
DocPrintJob
This interface represents a print job that can print a specified document with a set of job attributes.
MultiDoc
Interface MultiDoc specifies the interface for an object that supplies more than one piece of print data for a Print Job.
MultiDocPrintJob
Obtained from a MultiDocPrintService, a MultiDocPrintJob can print a specified collection of documents as a single print job with a set of job attributes.
MultiDocPrintService
Interface MultiPrintService is the factory for a MultiDocPrintJob.
PrintException
Class PrintException encapsulates a printing-related error condition that occurred while using a Print Service instance.
PrintService
Interface PrintService is the factory for a DocPrintJob.
PrintServiceLookup
Implementations of this class provide lookup services for print services (typically equivalent to printers) of a particular type.
ServiceUIFactory
Services may optionally provide UIs which allow different styles of interaction in different roles.
StreamPrintService
This class extends PrintService and represents a print service that prints data in different formats to a client-provided output stream.
StreamPrintServiceFactory
A StreamPrintServiceFactory is the factory for StreamPrintService instances, which can print to an output stream in a particular document format described as a mime type.

Classes in javax.print used by javax.print.event
DocPrintJob
This interface represents a print job that can print a specified document with a set of job attributes.
PrintService
Interface PrintService is the factory for a DocPrintJob.

Classes in javax.print used by javax.swing
PrintService
Interface PrintService is the factory for a DocPrintJob.

Classes in javax.print used by javax.swing.text
PrintService
Interface PrintService is the factory for a DocPrintJob.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


attribute

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.print.attribute

Provides classes and interfaces that describe the types of JavaTM Print Service attributes and how they can be collected into attribute sets.

See:
Description

Interface Summary
Attribute | Interface Attribute is the base interface implemented by any and every printing attribute class to indicate that the class represents a printing attribute.
AttributeSet | Interface AttributeSet specifies the interface for a set of printing attributes.
DocAttribute | Interface DocAttribute is a tagging interface which a printing attribute class implements to indicate the attribute denotes a setting for a doc.
DocAttributeSet | Interface DocAttributeSet specifies the interface for a set of doc attributes, i.e.
PrintJobAttribute | PrintJobAttribute is a tagging interface which a printing attribute class implements to indicate the attribute describes the status of a Print Job or some other characteristic of a Print Job.
PrintJobAttributeSet | Interface PrintJobAttributeSet specifies the interface for a set of print job attributes, i.e.
PrintRequestAttribute | Interface PrintRequestAttribute is a tagging interface which a printing attribute class implements to indicate the attribute denotes a requested setting for a print job.
PrintRequestAttributeSet | Interface PrintRequestAttributeSet specifies the interface for a set of print request attributes, i.e.
PrintServiceAttribute | Interface PrintServiceAttribute is a tagging interface which a printing attribute class implements to indicate the attribute describes the status of a Print Service or some other characteristic of a Print Service.
PrintServiceAttributeSet | Interface PrintServiceAttributeSet specifies the interface for a set of print job attributes, i.e.
SupportedValuesAttribute | Interface SupportedValuesAttribute is a tagging interface which a printing attribute class implements to indicate the attribute describes the supported values for another attribute.

Class Summary
AttributeSetUtilities | Class AttributeSetUtilities provides static methods for manipulating AttributeSets.
DateTimeSyntax | Class DateTimeSyntax is an abstract base class providing the common implementation of all attributes whose value is a date and time.
EnumSyntax | Class EnumSyntax is an abstract base class providing the common implementation of all "type safe enumeration" objects.
HashAttributeSet | Class HashAttributeSet provides an AttributeSet implementation with characteristics of a hash map.
HashDocAttributeSet | Class HashDocAttributeSet provides an attribute set which inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface DocAttributeSet.
HashPrintJobAttributeSet | Class HashPrintJobAttributeSet provides an attribute set which inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface PrintJobAttributeSet.
HashPrintRequestAttributeSet | Class HashPrintRequestAttributeSet inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface PrintRequestAttributeSet.
HashPrintServiceAttributeSet | Class HashPrintServiceAttributeSet provides an attribute set which inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface PrintServiceAttributeSet.
IntegerSyntax | Class IntegerSyntax is an abstract base class providing the common implementation of all attributes with integer values.
ResolutionSyntax | Class ResolutionSyntax is an abstract base class providing the common implementation of all attributes denoting a printer resolution.
SetOfIntegerSyntax | Class SetOfIntegerSyntax is an abstract base class providing the common implementation of all attributes whose value is a set of nonnegative integers.
Size2DSyntax | Class Size2DSyntax is an abstract base class providing the common implementation of all attributes denoting a size in two dimensions.
TextSyntax | Class TextSyntax is an abstract base class providing the common implementation of all attributes whose value is a string.
URISyntax | Class URISyntax is an abstract base class providing the common implementation of all attributes whose value is a Uniform Resource Identifier (URI).

Exception Summary
UnmodifiableSetException Thrown to indicate that the requested operation cannot be performed because the set is unmodifiable.

Package javax.print.attribute Description

Provides classes and interfaces that describe the types of JavaTM Print Service attributes and how they can be collected into attribute sets.

What is an Attribute?

When setting up a print job, a client specifies two things: print data and processing instructions. The print data is the actual content to be printed. The processing instructions tell the printer how to print the print data, such as: what media to use, how many copies to print, and whether to print on one or both sides of a sheet. The client specifies these processing instructions with the attribute definitions of the Java Print Service API.

The print data and the processing instructions are separate entities. This means that:

  • You can print the same print data at different times using different processing instructions.
    For example, you can print a slide presentation on US letter-sized white paper, double-sided, stapled, 20 copies to make handouts for a talk; and you could print the same slide presentation on US letter-sized transparencies, single-sided, one copy to make the actual slides for the talk.
  • You can use the same processing instructions at different times to print different data. For example, you could set your default processing instructions to: US letter-sized paper, double sided, stapled. Whenever you print a job, it prints with these settings, unless you explicitly override them.

The processing instruction does not specify how the print job processes the request; each processing instruction is only a description of the results of a print job. The print job determines the manner in which it achieves the results specified by the processing instructions. Representing processing instructions as descriptive items provides more flexibility for implementing print jobs.

Attribute Categories and Values

Each printer has a set of capabilities, such as the ability to print on different paper sizes or the ability to print more than one copy. Each of the capabilities has a range of values. For example, a printer's orientation capability might have this range of values: [landscape, portrait]. For each print request, the capability is set to one of these values. The Java Print Service API uses the term attribute category to refer to a printer capability and the term attribute value to refer to the value of the capability.

In the Java Print Service API, an attribute category is represented by a Java class implementing the Attribute interface. Attribute values are instances of such a class or one of its subclasses. For example, to specify the number of copies, an application constructs an instance of the Copies class with the number of desired copies and uses the Copies instance as part of the print request. In this case, the Copies class represents the attribute category, and the Copies instance represents the attribute value.

Attribute Roles

When submitting a print job to a printer, the client provides the attributes describing the characteristics of the print data, such as the document name, and how the print data should be printed, such as double-sided, five copies. If a print job consists of multiple pieces of print data, different pieces might have different processing instructions, such as 8 x 11 inch media for the first document, and 11 x 17 inch media for another document.

Once the printer starts processing the print job, additional information about the job becomes available, which might include: the job state (such as completed or queued) and the number of pages printed so far. These pieces of information are also attributes. Attributes can also describe the printer itself, such as: the printer name, the printer location, and the number of jobs queued.

The Java Print Service API defines these different kinds of attributes with five subinterfaces of Attribute:

  • DocAttribute specifies a characteristic of an individual document and the print job settings to be applied to an individual document.
  • PrintRequestAttribute specifies a setting applied to a whole print job and to all the documents in the print job.
  • PrintJobAttribute reports the status of a print job.
  • PrintServiceAttribute reports the status of a print service.
  • SupportedValuesAttribute gives the supported values for another attribute.
Each attribute class implements one or more of these tagging subinterfaces to indicate where the attribute can be used in the API. If an attribute class implements multiple tagging subinterfaces, the attribute can be used in multiple contexts. For example, the media attribute can apply to one document in a print job as a DocAttribute or to an entire print job as a PrintRequestAttribute. Certain low-level attributes are never used on their own but are always aggregated into higher-level attributes. These low-level attribute classes only implement interface Attribute, not any of the tagging subinterfaces.

The Java Print Service API defines a group of standard attribute classes modeled upon the attributes in the Internet Printing Protocol (IPP) version 1.1. The standard attribute classes are in the subpackage javax.print.attribute.standard to keep the actual attribute classes conceptually separate from the generic apparatus defined in package javax.print.attribute.

Attribute Sets

A client usually needs to provide more than one processing instruction when submitting a print job. For example, the client might need to specify a media size of A4 and a landscape orientation. To send more than one processing instruction, the client collects the attributes into an attribute set, which the Java Print Service API represents with the AttributeSet interface.

The AttributeSet interface is similar to the Map interface: it provides a map of key to values, in which each key is unique and can contain no more than one value. However, the AttributeSet interface is designed to specifically support the needs of the Java Print Service API. An AttributeSet requires that:

  1. Each key in an AttributeSet corresponds to a category, and the value of the key can only be one of the attribute values that belong to the category represented by the key. Thus, unlike a Map, an AttributeSet restricts the possible values of a key: an attribute category cannot be set to an attribute value that does not belong to that category.
  2. No two attributes from the same category can exist in the same set. For example, an attribute collection must not contain both a "one-sided" attribute and a "two-sided" attribute because these two attributes give the printer conflicting instructions.
  3. Only attributes implementing the Attribute interface can be added to the set.

The javax.print.attribute package includes HashAttributeSet as a concrete implementation of the attribute set interface. HashAttributeSet provides an attribute set based on a hash map. You can use this implementation or provide your own implementation of interface AttributeSet.

The Java Print Service API provides four specializations of an attribute set that are restricted to contain just one of the four kinds of attributes, as discussed in the Attribute Roles section:

  • DocAttributeSet
  • PrintRequestAttributeSet
  • PrintJobAttributeSet
  • PrintServiceAttributeSet
Notice that only four kinds of attribute sets are listed here, but there are five kinds of attributes. Interface SupportedValuesAttribute denotes an attribute that gives the supported values for another attribute. Supported-values attributes are never aggregated into attribute sets, so there is no attribute set subinterface defined for them.

In some contexts, an attribute set is read-only, which means that the client is only allowed to examine an attribute set's contents but not change them. In other contexts, the attribute set is read-write, which means that the client is allowed both to examine and to change an attribute set's contents. For a read-only attribute set, calling a mutating operation throws an UnmodifiableSetException.

Package javax.print.attribute includes one concrete implementation of each of the attribute set subinterfaces:

  • HashDocAttributeSet
  • HashPrintRequestAttributeSet,
  • HashPrintJobAttributeSet,
  • HashPrintServiceAttributeSet.
All of these classes extend HashAttributeSet and enforce the restriction that the attribute set is only allowed to contain the corresponding kind of attribute.

Attribute Class Design

An attribute value is a small, atomic data item, such as an integer or an enumerated value. The Java Print Service API does not use primitive data types, such as int, to represent attribute values for these reasons:
  • Primitive data types are not type-safe. For example, a compiler should not allow a "copies" attribute value to be used for a "sides" attribute.
  • Some attributes must be represented as a record of several values. One example is printer resolution, which requires two numbers, such as 600 and 300 representing 600 x 300 dpi.
For type-safety and to represent all attributes uniformly, the Java Print Service API defines each attribute category as a class, such as class Copies, class Sides, and class PrinterResolution. Each attribute class wraps one or more primitive data items containing the attribute's value. Attribute set operations perform frequent comparisons between attribute category objects when adding attributes, finding existing attributes in the same category, and looking up an attribute given its category. Because an attribute category is represented by a class, fast attribute-value comparisons can be performed with the Class.equals method.

Even though the Java Print Service API includes a large number of different attribute categories, there are only a few different types of attribute values. Most attributes can be represented by a small number of data types, such as: integer values, integer ranges, text, or an enumeration of integer values. The type of the attribute value that a category accepts is called the attribute's abstract syntax. To provide consistency and reduce code duplication, the Java Print Service API defines abstract syntax classes to represent each abstract syntax, and these classes are used as the parent of standard attributes whenever possible. The abstract syntax classes are:

  • EnumSyntax provides a type-safe enumeration in which enumerated values are represented as singleton objects. Each enumeration singleton is an instance of the enumeration class that wraps a hidden int value.
  • IntegerSyntax is the abstract syntax for integer-valued attributes.
  • TextSyntax is the abstract syntax for text-valued attributes, and includes a locale giving the text string's natural language.
  • SetOfIntegerSyntax is the abstract syntax for attributes representing a range or set of integers
  • ResolutionSyntax is the abstract syntax for attributes representing resolution values, such as 600x300 dpi.
  • Size2DSyntax is the abstract syntax for attributes representing a two-dimensional size, such as a paper size of 8.5 x 11 inches.
  • DateTimeSyntax is the abstract syntax for attributes whose value is a date and time.
  • URISyntax is the abstract syntax for attributes whose value is a Uniform Resource Indicator.
The abstract syntax classes are independent of the attributes that use them. In fact, applications that have nothing to do with printing can use the abstract syntax classes. Although most of the standard attribute classes extend one of the abstract syntax classes, no attribute class is required to extend one of these classes. The abstract syntax classes merely provide a convenient implementation that can be shared by many attribute classes.

Each attribute class implements the Attribute interface, either directly or indirectly, to mark it as a printing attribute. An attribute class that can appear in restricted attribute sets in certain contexts also implements one or more subinterfaces of Attribute. Most attribute classes also extend the appropriate abstract syntax class to get the implementation. Consider the Sides attribute class:

public class Sides
  extends EnumSyntax
  implements DocAttribute, PrintRequestAttribute, PrintJobAttribute
  {
  public final Object getCategory()
    {
    return Sides.class;
    }
  ...
  }

Since every attribute class implements Attribute, every attribute class must provide an implementation for the getCategory method, which returns the attribute category. In the case of Sides, the getCategory method returns Sides.class. The getCategory method is final to ensure that any vendor-defined subclasses of a standard attribute class appear in the same category. Every attribute object is immutable once constructed so that attribute object references can be passed around freely. To get a different attribute value, construct a different attribute object.

Attribute Vendors

The Java Print Service API is designed so that vendors can:
  • define new vendor-specific values for any standard attribute defined in javax.print.attribute.standard.
  • define new attribute categories representing the vendor printer's proprietary capabilities not already supported by the standard attributes.
To define a new value for an attribute, a client can construct instances of such attributes with arbitrary values at runtime. However, an enumerated attribute using an abstract syntax class of EnumSyntax specifies all the possible attribute values at compile time as singleton instances of the attribute class. This means that new enumerated values cannot be constructed at run time. To define new vendor-specific values for a standard enumerated attribute, the vendor must define a new attribute class specifying the new singleton instances. To ensure that the new attribute values fall in the same category as the standard attribute values, the new attribute class must be a subclass of the standard attribute class.

To define a new attribute category, a vendor defines a new attribute class. This attribute class, like the standard attribute classes, implements Attribute or one of its subinterfaces and extends an abstract syntax class. The vendor can either use an existing abstract syntax class or define a new one. The new vendor-defined attribute can be used wherever an Attribute is used, such as in an AttributeSet.

Using Attributes

A typical printing application uses the PrintRequestAttributeSet because print-request attributes are the types of attributes that client usually specifies. This example demonstrates creating an attribute set of print-request attributes and locating a printer that can print the document according to the specified attributes:

FileInputStream psStream;
try {
   psstream = new FileInputStream("file.ps");
} catch (FileNotFoundException ffne) {
}
if (psstream == null) {
    return;
}
//Set the document type.  See the DocFlavor documentation for
//more information.
DocFlavor psInFormat = DocFlavor.INPUT_STREAM.POSTSCRIPT;
Doc myDoc = new SimpleDoc(pstream, psInFormat, null);
PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
aset.add(new Copies(5));
aset.add(MediaSize.A4);
aset.add(Sides.DUPLEX);

PrintService[] services =
                PrintServiceLookup.lookupPrintServices(psInFormat, aset);
if (services.length > 0) {
   DocPrintJob job = services[0].createPrintJob();
   try {
        job.print(myDoc, aset);
   } catch (PrintException pe) {}
}

Please note: In the javax.print APIs, a null reference parameter to methods is incorrect unless explicitly documented on the method as having a meaningful interpretation. Usage to the contrary is incorrect coding and may result in a run time exception either immediately or at some later time. IllegalArgumentException and NullPointerException are examples of typical and acceptable run time exceptions for such cases.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


DocAttribute

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Interface DocAttribute

All Superinterfaces:
Attribute, Serializable
All Known Implementing Classes:
Chromaticity, Compression, DocumentName, Finishings, Media, MediaName, MediaPrintableArea, MediaSizeName, MediaTray, NumberUp, OrientationRequested, PageRanges, PrinterResolution, PrintQuality, SheetCollate, Sides
public interface DocAttribute
extends Attribute

Interface DocAttribute is a tagging interface which a printing attribute class implements to indicate the attribute denotes a setting for a doc. ("Doc" is a short, easy-to-pronounce term that means "a piece of print data.") The client may include a DocAttribute in a Doc's attribute set to specify a characteristic of that doc. If an attribute implements PrintRequestAttribute as well as DocAttribute, the client may include the attribute in a attribute set which specifies a print job to specify a characteristic for all the docs in that job.

See Also:
DocAttributeSet, PrintRequestAttributeSet

Method Summary
Methods inherited from interface javax.print.attribute.Attribute
getCategory, getName

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


javax.print.attribute Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.print.attribute

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.print.attribute.AttributeSetUtilities
    • javax.print.attribute.DateTimeSyntax (implements java.lang.Cloneable, java.io.Serializable)
    • javax.print.attribute.EnumSyntax (implements java.lang.Cloneable, java.io.Serializable)
    • javax.print.attribute.HashAttributeSet (implements javax.print.attribute.AttributeSet, java.io.Serializable)
      • javax.print.attribute.HashDocAttributeSet (implements javax.print.attribute.DocAttributeSet, java.io.Serializable)
      • javax.print.attribute.HashPrintJobAttributeSet (implements javax.print.attribute.PrintJobAttributeSet, java.io.Serializable)
      • javax.print.attribute.HashPrintRequestAttributeSet (implements javax.print.attribute.PrintRequestAttributeSet, java.io.Serializable)
      • javax.print.attribute.HashPrintServiceAttributeSet (implements javax.print.attribute.PrintServiceAttributeSet, java.io.Serializable)
    • javax.print.attribute.IntegerSyntax (implements java.lang.Cloneable, java.io.Serializable)
    • javax.print.attribute.ResolutionSyntax (implements java.lang.Cloneable, java.io.Serializable)
    • javax.print.attribute.SetOfIntegerSyntax (implements java.lang.Cloneable, java.io.Serializable)
    • javax.print.attribute.Size2DSyntax (implements java.lang.Cloneable, java.io.Serializable)
    • javax.print.attribute.TextSyntax (implements java.lang.Cloneable, java.io.Serializable)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.lang.RuntimeException
          • javax.print.attribute.UnmodifiableSetException
    • javax.print.attribute.URISyntax (implements java.lang.Cloneable, java.io.Serializable)

Interface Hierarchy

  • javax.print.attribute.AttributeSet
    • javax.print.attribute.DocAttributeSet
    • javax.print.attribute.PrintJobAttributeSet
    • javax.print.attribute.PrintRequestAttributeSet
    • javax.print.attribute.PrintServiceAttributeSet
  • java.io.Serializable
    • javax.print.attribute.Attribute
      • javax.print.attribute.DocAttribute
      • javax.print.attribute.PrintJobAttribute
      • javax.print.attribute.PrintRequestAttribute
      • javax.print.attribute.PrintServiceAttribute
      • javax.print.attribute.SupportedValuesAttribute
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


PrintJobAttribute

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Interface PrintJobAttribute

All Superinterfaces:
Attribute, Serializable
All Known Implementing Classes:
Chromaticity, Copies, DateTimeAtCompleted, DateTimeAtCreation, DateTimeAtProcessing, Destination, Fidelity, Finishings, JobHoldUntil, JobImpressions, JobImpressionsCompleted, JobKOctets, JobKOctetsProcessed, JobMediaSheets, JobMediaSheetsCompleted, JobMessageFromOperator, JobName, JobOriginatingUserName, JobPriority, JobSheets, JobState, JobStateReasons, Media, MediaName, MediaPrintableArea, MediaSizeName, MediaTray, MultipleDocumentHandling, NumberOfDocuments, NumberOfInterveningJobs, NumberUp, OrientationRequested, OutputDeviceAssigned, PageRanges, PresentationDirection, PrinterResolution, PrintQuality, SheetCollate, Sides
public interface PrintJobAttribute
extends Attribute

PrintJobAttribute is a tagging interface which a printing attribute class implements to indicate the attribute describes the status of a Print Job or some other characteristic of a Print Job. A Print Service instance adds a number of PrintJobAttributes to a Print Job's attribute set to report the Print Job's status. If an attribute implements PrintRequestAttribute as well as PrintJobAttribute, the client may include the attribute in a attribute set to specify the attribute's value for the Print Job.

See Also:
PrintRequestAttributeSet, PrintJobAttributeSet

Method Summary
Methods inherited from interface javax.print.attribute.Attribute
getCategory, getName

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrintRequestAttribute

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Interface PrintRequestAttribute

All Superinterfaces:
Attribute, Serializable
All Known Implementing Classes:
Chromaticity, Copies, Destination, Fidelity, Finishings, JobHoldUntil, JobImpressions, JobKOctets, JobMediaSheets, JobName, JobPriority, JobSheets, Media, MediaName, MediaPrintableArea, MediaSizeName, MediaTray, MultipleDocumentHandling, NumberUp, OrientationRequested, PageRanges, PresentationDirection, PrinterResolution, PrintQuality, RequestingUserName, SheetCollate, Sides
public interface PrintRequestAttribute
extends Attribute

Interface PrintRequestAttribute is a tagging interface which a printing attribute class implements to indicate the attribute denotes a requested setting for a print job.

Attributes which are tagged with PrintRequestAttribute and are also tagged as PrintJobAttribute, represent the subset of job attributes which can be part of the specification of a job request.

If an attribute implements DocAttribute as well as PrintRequestAttribute, the client may include the attribute in a Doc}'s attribute set to specify a job setting which pertains just to that doc.

See Also:
DocAttributeSet, PrintRequestAttributeSet

Method Summary
Methods inherited from interface javax.print.attribute.Attribute
getCategory, getName

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrintServiceAttribute

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Interface PrintServiceAttribute

All Superinterfaces:
Attribute, Serializable
All Known Implementing Classes:
ColorSupported, PagesPerMinute, PagesPerMinuteColor, PDLOverrideSupported, PrinterInfo, PrinterIsAcceptingJobs, PrinterLocation, PrinterMakeAndModel, PrinterMessageFromOperator, PrinterMoreInfo, PrinterMoreInfoManufacturer, PrinterName, PrinterState, PrinterStateReasons, PrinterURI, QueuedJobCount
public interface PrintServiceAttribute
extends Attribute

Interface PrintServiceAttribute is a tagging interface which a printing attribute class implements to indicate the attribute describes the status of a Print Service or some other characteristic of a Print Service. A Print Service instance adds a number of PrintServiceAttributes to a Print service's attribute set to report the Print Service's status.

See Also:
PrintServiceAttributeSet

Method Summary
Methods inherited from interface javax.print.attribute.Attribute
getCategory, getName

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SupportedValuesAttribute

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Interface SupportedValuesAttribute

All Superinterfaces:
Attribute, Serializable
All Known Implementing Classes:
CopiesSupported, JobImpressionsSupported, JobKOctetsSupported, JobMediaSheetsSupported, JobPrioritySupported, NumberUpSupported
public interface SupportedValuesAttribute
extends Attribute

Interface SupportedValuesAttribute is a tagging interface which a printing attribute class implements to indicate the attribute describes the supported values for another attribute. For example, if a Print Service instance supports the Copies attribute, the Print Service instance will have a CopiesSupported attribute, which is a SupportedValuesAttribute giving the legal values a client may specify for the Copies attribute.

Method Summary
Methods inherited from interface javax.print.attribute.Attribute
getCategory, getName

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Package javax.print.attribute

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.print.attribute

Packages that use javax.print.attribute
java.awt.print | Provides classes and interfaces for a general printing API.
javax.print | Provides the principal classes and interfaces for the JavaTM Print Service API.
javax.print.attribute | Provides classes and interfaces that describe the types of JavaTM Print Service attributes and how they can be collected into attribute sets.
javax.print.attribute.standard | Package javax.print.attribute.standard contains classes for specific printing attributes.
javax.print.event | Package javax.print.event contains event classes and listener interfaces.
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Classes in javax.print.attribute used by java.awt.print
PrintRequestAttributeSet
Interface PrintRequestAttributeSet specifies the interface for a set of print request attributes, i.e.

Classes in javax.print.attribute used by javax.print
Attribute
Interface Attribute is the base interface implemented by any and every printing attribute class to indicate that the class represents a printing attribute.
AttributeSet
Interface AttributeSet specifies the interface for a set of printing attributes.
DocAttributeSet
Interface DocAttributeSet specifies the interface for a set of doc attributes, i.e.
PrintJobAttributeSet
Interface PrintJobAttributeSet specifies the interface for a set of print job attributes, i.e.
PrintRequestAttributeSet
Interface PrintRequestAttributeSet specifies the interface for a set of print request attributes, i.e.
PrintServiceAttribute
Interface PrintServiceAttribute is a tagging interface which a printing attribute class implements to indicate the attribute describes the status of a Print Service or some other characteristic of a Print Service.
PrintServiceAttributeSet
Interface PrintServiceAttributeSet specifies the interface for a set of print job attributes, i.e.

Classes in javax.print.attribute used by javax.print.attribute
Attribute
Interface Attribute is the base interface implemented by any and every printing attribute class to indicate that the class represents a printing attribute.
AttributeSet
Interface AttributeSet specifies the interface for a set of printing attributes.
DocAttribute
Interface DocAttribute is a tagging interface which a printing attribute class implements to indicate the attribute denotes a setting for a doc.
DocAttributeSet
Interface DocAttributeSet specifies the interface for a set of doc attributes, i.e.
EnumSyntax
Class EnumSyntax is an abstract base class providing the common implementation of all "type safe enumeration" objects.
HashAttributeSet
Class HashAttributeSet provides an AttributeSet implementation with characteristics of a hash map.
IntegerSyntax
Class IntegerSyntax is an abstract base class providing the common implementation of all attributes with integer values.
PrintJobAttribute
PrintJobAttribute is a tagging interface which a printing attribute class implements to indicate the attribute describes the status of a Print Job or some other characteristic of a Print Job.
PrintJobAttributeSet
Interface PrintJobAttributeSet specifies the interface for a set of print job attributes, i.e.
PrintRequestAttribute
Interface PrintRequestAttribute is a tagging interface which a printing attribute class implements to indicate the attribute denotes a requested setting for a print job.
PrintRequestAttributeSet
Interface PrintRequestAttributeSet specifies the interface for a set of print request attributes, i.e.
PrintServiceAttribute
Interface PrintServiceAttribute is a tagging interface which a printing attribute class implements to indicate the attribute describes the status of a Print Service or some other characteristic of a Print Service.
PrintServiceAttributeSet
Interface PrintServiceAttributeSet specifies the interface for a set of print job attributes, i.e.
ResolutionSyntax
Class ResolutionSyntax is an abstract base class providing the common implementation of all attributes denoting a printer resolution.

Classes in javax.print.attribute used by javax.print.attribute.standard
Attribute
Interface Attribute is the base interface implemented by any and every printing attribute class to indicate that the class represents a printing attribute.
DateTimeSyntax
Class DateTimeSyntax is an abstract base class providing the common implementation of all attributes whose value is a date and time.
DocAttribute
Interface DocAttribute is a tagging interface which a printing attribute class implements to indicate the attribute denotes a setting for a doc.
EnumSyntax
Class EnumSyntax is an abstract base class providing the common implementation of all "type safe enumeration" objects.
IntegerSyntax
Class IntegerSyntax is an abstract base class providing the common implementation of all attributes with integer values.
PrintJobAttribute
PrintJobAttribute is a tagging interface which a printing attribute class implements to indicate the attribute describes the status of a Print Job or some other characteristic of a Print Job.
PrintRequestAttribute
Interface PrintRequestAttribute is a tagging interface which a printing attribute class implements to indicate the attribute denotes a requested setting for a print job.
PrintServiceAttribute
Interface PrintServiceAttribute is a tagging interface which a printing attribute class implements to indicate the attribute describes the status of a Print Service or some other characteristic of a Print Service.
ResolutionSyntax
Class ResolutionSyntax is an abstract base class providing the common implementation of all attributes denoting a printer resolution.
SetOfIntegerSyntax
Class SetOfIntegerSyntax is an abstract base class providing the common implementation of all attributes whose value is a set of nonnegative integers.
Size2DSyntax
Class Size2DSyntax is an abstract base class providing the common implementation of all attributes denoting a size in two dimensions.
SupportedValuesAttribute
Interface SupportedValuesAttribute is a tagging interface which a printing attribute class implements to indicate the attribute describes the supported values for another attribute.
TextSyntax
Class TextSyntax is an abstract base class providing the common implementation of all attributes whose value is a string.
URISyntax
Class URISyntax is an abstract base class providing the common implementation of all attributes whose value is a Uniform Resource Identifier (URI).

Classes in javax.print.attribute used by javax.print.event
PrintJobAttributeSet
Interface PrintJobAttributeSet specifies the interface for a set of print job attributes, i.e.
PrintServiceAttributeSet
Interface PrintServiceAttributeSet specifies the interface for a set of print job attributes, i.e.

Classes in javax.print.attribute used by javax.swing
PrintRequestAttributeSet
Interface PrintRequestAttributeSet specifies the interface for a set of print request attributes, i.e.

Classes in javax.print.attribute used by javax.swing.text
PrintRequestAttributeSet
Interface PrintRequestAttributeSet specifies the interface for a set of print request attributes, i.e.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Attribute

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Interface Attribute

All Superinterfaces:
Serializable
All Known Subinterfaces:
DocAttribute, PrintJobAttribute, PrintRequestAttribute, PrintServiceAttribute, SupportedValuesAttribute
All Known Implementing Classes:
Chromaticity, ColorSupported, Compression, Copies, CopiesSupported, DateTimeAtCompleted, DateTimeAtCreation, DateTimeAtProcessing, Destination, DocumentName, Fidelity, Finishings, JobHoldUntil, JobImpressions, JobImpressionsCompleted, JobImpressionsSupported, JobKOctets, JobKOctetsProcessed, JobKOctetsSupported, JobMediaSheets, JobMediaSheetsCompleted, JobMediaSheetsSupported, JobMessageFromOperator, JobName, JobOriginatingUserName, JobPriority, JobPrioritySupported, JobSheets, JobState, JobStateReason, JobStateReasons, Media, MediaName, MediaPrintableArea, MediaSize, MediaSizeName, MediaTray, MultipleDocumentHandling, NumberOfDocuments, NumberOfInterveningJobs, NumberUp, NumberUpSupported, OrientationRequested, OutputDeviceAssigned, PageRanges, PagesPerMinute, PagesPerMinuteColor, PDLOverrideSupported, PresentationDirection, PrinterInfo, PrinterIsAcceptingJobs, PrinterLocation, PrinterMakeAndModel, PrinterMessageFromOperator, PrinterMoreInfo, PrinterMoreInfoManufacturer, PrinterName, PrinterResolution, PrinterState, PrinterStateReason, PrinterStateReasons, PrinterURI, PrintQuality, QueuedJobCount, ReferenceUriSchemesSupported, RequestingUserName, Severity, SheetCollate, Sides
public interface Attribute
extends Serializable

Interface Attribute is the base interface implemented by any and every printing attribute class to indicate that the class represents a printing attribute. All printing attributes are serializable.

Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value when it is added to an attribute set.
String | getName() Get the name of the category of which this attribute value is an instance.

Method Detail

getCategory

Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value when it is added to an attribute set.

Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

String getName()
Get the name of the category of which this attribute value is an instance.

Note: This method is intended to provide a default, nonlocalized string for the attribute's category. If two attribute objects return the same category from the getCategory() method, they should return the same name from the getName() method.

Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AttributeSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Interface AttributeSet

All Known Subinterfaces:
DocAttributeSet, PrintJobAttributeSet, PrintRequestAttributeSet, PrintServiceAttributeSet
All Known Implementing Classes:
HashAttributeSet, HashDocAttributeSet, HashPrintJobAttributeSet, HashPrintRequestAttributeSet, HashPrintServiceAttributeSet
public interface AttributeSet

Interface AttributeSet specifies the interface for a set of printing attributes. A printing attribute is an object whose class implements interface Attribute.

An attribute set contains a group of attribute values, where duplicate values are not allowed in the set. Furthermore, each value in an attribute set is a member of some category, and at most one value in any particular category is allowed in the set. For an attribute set, the values are Attribute objects, and the categories are Class objects. An attribute's category is the class (or interface) at the root of the class hierarchy for that kind of attribute. Note that an attribute object's category may be a superclass of the attribute object's class rather than the attribute object's class itself. An attribute object's category is determined by calling the getCategory() method defined in interface Attribute.

The interfaces of an AttributeSet resemble those of the Java Collections API's java.util.Map interface, but is more restrictive in the types it will accept, and combines keys and values into an Attribute.

Attribute sets are used in several places in the Print Service API. In each context, only certain kinds of attributes are allowed to appear in the attribute set, as determined by the tagging interfaces which the attribute class implements -- DocAttribute, PrintRequestAttribute, PrintJobAttribute, and PrintServiceAttribute. There are four specializations of an attribute set that are restricted to contain just one of the four kinds of attribute -- DocAttributeSet, PrintRequestAttributeSet, PrintJobAttributeSet, and PrintServiceAttributeSet, respectively. Note that many attribute classes implement more than one tagging interface and so may appear in more than one context.

  • A DocAttributeSet, containing DocAttributes, specifies the characteristics of an individual doc and the print job settings to be applied to an individual doc.

  • A PrintRequestAttributeSet, containing PrintRequestAttributes, specifies the settings to be applied to a whole print job and to all the docs in the print job.

  • A PrintJobAttributeSet, containing PrintJobAttributes, reports the status of a print job.

  • A PrintServiceAttributeSet, containing PrintServiceAttributes, reports the status of a Print Service instance.

In some contexts, the client is only allowed to examine an attribute set's contents but not change them (the set is read-only). In other places, the client is allowed both to examine and to change an attribute set's contents (the set is read-write). For a read-only attribute set, calling a mutating operation throws an UnmodifiableSetException.

The Print Service API provides one implementation of interface AttributeSet, class HashAttributeSet. A client can use class HashAttributeSet or provide its own implementation of interface AttributeSet. The Print Service API also provides implementations of interface AttributeSet's subinterfaces -- classes HashDocAttributeSet, HashPrintRequestAttributeSet, HashPrintJobAttributeSet, and HashPrintServiceAttributeSet.

Method Summary
boolean | add(Attribute attribute) Adds the specified attribute to this attribute set if it is not already present, first removing any existing value in the same attribute category as the specified attribute value.
boolean | addAll(AttributeSet attributes) Adds all of the elements in the specified set to this attribute.
void | clear() Removes all attributes from this attribute set.
boolean | containsKey(Class<?> category) Returns true if this attribute set contains an attribute for the specified category.
boolean | containsValue(Attribute attribute) Returns true if this attribute set contains the given attribute value.
boolean | equals(Object object) Compares the specified object with this attribute set for equality.
Attribute | get(Class<?> category) Returns the attribute value which this attribute set contains in the given attribute category.
int | hashCode() Returns the hash code value for this attribute set.
boolean | isEmpty() Returns true if this attribute set contains no attributes.
boolean | remove(Attribute attribute) Removes the specified attribute from this attribute set if present.
boolean | remove(Class<?> category) Removes any attribute for this category from this attribute set if present.
int | size() Returns the number of attributes in this attribute set.
Attribute[] | toArray() Returns an array of the attributes contained in this set.

Method Detail

get

Attribute get(Class<?> category)
Returns the attribute value which this attribute set contains in the given attribute category. Returns null if this attribute set does not contain any attribute value in the given attribute category.

Parameters:
category - Attribute category whose associated attribute value is to be returned. It must be a Class that implements interface Attribute.
Returns:
The attribute value in the given attribute category contained in this attribute set, or null if this attribute set does not contain any attribute value in the given attribute category.
Throws:
NullPointerException - (unchecked exception) Thrown if the category is null.
ClassCastException - (unchecked exception) Thrown if the category is not a Class that implements interface Attribute.

add

boolean add(Attribute attribute)
Adds the specified attribute to this attribute set if it is not already present, first removing any existing value in the same attribute category as the specified attribute value.

Parameters:
attribute - Attribute value to be added to this attribute set.
Returns:
true if this attribute set changed as a result of the call, i.e., the given attribute value was not already a member of this attribute set.
Throws:
NullPointerException - (unchecked exception) Thrown if the attribute is null.
UnmodifiableSetException - (unchecked exception) Thrown if this attribute set does not support the add() operation.

remove

boolean remove(Class<?> category)
Removes any attribute for this category from this attribute set if present. If category is null, then remove() does nothing and returns false.

Parameters:
category - Attribute category to be removed from this attribute set.
Returns:
true if this attribute set changed as a result of the call, i.e., the given attribute value had been a member of this attribute set.
Throws:
UnmodifiableSetException - (unchecked exception) Thrown if this attribute set does not support the remove() operation.

remove

boolean remove(Attribute attribute)
Removes the specified attribute from this attribute set if present. If attribute is null, then remove() does nothing and returns false.

Parameters:
attribute - Attribute value to be removed from this attribute set.
Returns:
true if this attribute set changed as a result of the call, i.e., the given attribute value had been a member of this attribute set.
Throws:
UnmodifiableSetException - (unchecked exception) Thrown if this attribute set does not support the remove() operation.

containsKey

boolean containsKey(Class<?> category)
Returns true if this attribute set contains an attribute for the specified category.

Parameters:
category - whose presence in this attribute set is to be tested.
Returns:
true if this attribute set contains an attribute value for the specified category.

containsValue

boolean containsValue(Attribute attribute)
Returns true if this attribute set contains the given attribute value.

Parameters:
attribute - Attribute value whose presence in this attribute set is to be tested.
Returns:
true if this attribute set contains the given attribute value.

addAll

boolean addAll(AttributeSet attributes)
Adds all of the elements in the specified set to this attribute. The outcome is the same as if the = add(Attribute) operation had been applied to this attribute set successively with each element from the specified set. The behavior of the addAll(AttributeSet) operation is unspecified if the specified set is modified while the operation is in progress.

If the addAll(AttributeSet) operation throws an exception, the effect on this attribute set's state is implementation dependent; elements from the specified set before the point of the exception may or may not have been added to this attribute set.

Parameters:
attributes - whose elements are to be added to this attribute set.
Returns:
true if this attribute set changed as a result of the call.
Throws:
UnmodifiableSetException - (Unchecked exception) Thrown if this attribute set does not support the addAll(AttributeSet) method.
NullPointerException - (Unchecked exception) Thrown if some element in the specified set is null.
See Also:
add(Attribute)

size

int size()
Returns the number of attributes in this attribute set. If this attribute set contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Returns:
The number of attributes in this attribute set.

toArray

Attribute[] toArray()
Returns an array of the attributes contained in this set.

Returns:
the Attributes contained in this set as an array, zero length if the AttributeSet is empty.

clear

void clear()
Removes all attributes from this attribute set.

Throws:
UnmodifiableSetException - (unchecked exception) Thrown if this attribute set does not support the clear() operation.

isEmpty

boolean isEmpty()
Returns true if this attribute set contains no attributes.

Returns:
true if this attribute set contains no attributes.

equals

boolean equals(Object object)
Compares the specified object with this attribute set for equality. Returns true if the given object is also an attribute set and the two attribute sets contain the same attribute category-attribute value mappings. This ensures that the equals() method works properly across different implementations of the AttributeSet interface.

Overrides:
equals in class Object
Parameters:
object - to be compared for equality with this attribute set.
Returns:
true if the specified object is equal to this attribute set.
See Also:
Object.hashCode(), Hashtable

hashCode

int hashCode()
Returns the hash code value for this attribute set. The hash code of an attribute set is defined to be the sum of the hash codes of each entry in the AttributeSet. This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two attribute sets t1 and t2, as required by the general contract of Object.hashCode().

Overrides:
hashCode in class Object
Returns:
The hash code value for this attribute set.
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AttributeSetUtilities

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Class AttributeSetUtilities

java.lang.Object
    extended by  javax.print.attribute.AttributeSetUtilities

public final class AttributeSetUtilities
extends Object

Class AttributeSetUtilities provides static methods for manipulating AttributeSets.

  • Methods for creating unmodifiable and synchronized views of attribute sets.
  • operations useful for building implementations of interface AttributeSet

An unmodifiable view U of an AttributeSet S provides a client with "read-only" access to S. Query operations on U "read through" to S; thus, changes in S are reflected in U. However, any attempt to modify U, results in an UnmodifiableSetException. The unmodifiable view object U will be serializable if the attribute set object S is serializable.

A synchronized view V of an attribute set S provides a client with synchronized (multiple thread safe) access to S. Each operation of V is synchronized using V itself as the lock object and then merely invokes the corresponding operation of S. In order to guarantee mutually exclusive access, it is critical that all access to S is accomplished through V. The synchronized view object V will be serializable if the attribute set object S is serializable.

As mentioned in the package description of javax.print, a null reference parameter to methods is incorrect unless explicitly documented on the method as having a meaningful interpretation. Usage to the contrary is incorrect coding and may result in a run time exception either immediately or at some later time. IllegalArgumentException and NullPointerException are examples of typical and acceptable run time exceptions for such cases.

Method Summary
static AttributeSet | synchronizedView(AttributeSet attributeSet) Creates a synchronized view of the given attribute set.
static DocAttributeSet | synchronizedView(DocAttributeSet attributeSet) Creates a synchronized view of the given doc attribute set.
static PrintJobAttributeSet | synchronizedView(PrintJobAttributeSet attributeSet) Creates a synchronized view of the given print job attribute set.
static PrintRequestAttributeSet | synchronizedView(PrintRequestAttributeSet attributeSet) Creates a synchronized view of the given print request attribute set.
static PrintServiceAttributeSet | synchronizedView(PrintServiceAttributeSet attributeSet) Creates a synchronized view of the given print service attribute set.
static AttributeSet | unmodifiableView(AttributeSet attributeSet) Creates an unmodifiable view of the given attribute set.
static DocAttributeSet | unmodifiableView(DocAttributeSet attributeSet) Creates an unmodifiable view of the given doc attribute set.
static PrintJobAttributeSet | unmodifiableView(PrintJobAttributeSet attributeSet) Creates an unmodifiable view of the given print job attribute set.
static PrintRequestAttributeSet | unmodifiableView(PrintRequestAttributeSet attributeSet) Creates an unmodifiable view of the given print request attribute set.
static PrintServiceAttributeSet | unmodifiableView(PrintServiceAttributeSet attributeSet) Creates an unmodifiable view of the given print service attribute set.
static Class<?> | verifyAttributeCategory(Object object, Class<?> interfaceName) Verify that the given object is a Class that implements the given interface, which is assumed to be interface Attribute or a subinterface thereof.
static Attribute | verifyAttributeValue(Object object, Class<?> interfaceName) Verify that the given object is an instance of the given interface, which is assumed to be interface Attribute or a subinterface thereof.
static void | verifyCategoryForValue(Class<?> category, Attribute attribute) Verify that the given attribute category object is equal to the category of the given attribute value object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

unmodifiableView

public static AttributeSet unmodifiableView(AttributeSet attributeSet)
Creates an unmodifiable view of the given attribute set.

Parameters:
attributeSet - Underlying attribute set.
Returns:
Unmodifiable view of attributeSet.
Throws:
NullPointerException - Thrown if attributeSet is null. Null is never a

unmodifiableView

public static DocAttributeSet unmodifiableView(DocAttributeSet attributeSet)
Creates an unmodifiable view of the given doc attribute set.

Parameters:
attributeSet - Underlying doc attribute set.
Returns:
Unmodifiable view of attributeSet.
Throws:
NullPointerException - Thrown if attributeSet is null.

unmodifiableView

public static PrintRequestAttributeSet unmodifiableView(PrintRequestAttributeSet attributeSet)
Creates an unmodifiable view of the given print request attribute set.

Parameters:
attributeSet - Underlying print request attribute set.
Returns:
Unmodifiable view of attributeSet.
Throws:
NullPointerException - Thrown if attributeSet is null.

unmodifiableView

public static PrintJobAttributeSet unmodifiableView(PrintJobAttributeSet attributeSet)
Creates an unmodifiable view of the given print job attribute set.

Parameters:
attributeSet - Underlying print job attribute set.
Returns:
Unmodifiable view of attributeSet.
Throws:
NullPointerException - Thrown if attributeSet is null.

unmodifiableView

public static PrintServiceAttributeSet unmodifiableView(PrintServiceAttributeSet attributeSet)
Creates an unmodifiable view of the given print service attribute set.

Parameters:
attributeSet - Underlying print service attribute set.
Returns:
Unmodifiable view of attributeSet.
Throws:
NullPointerException - Thrown if attributeSet is null.

synchronizedView

public static AttributeSet synchronizedView(AttributeSet attributeSet)
Creates a synchronized view of the given attribute set.

Parameters:
attributeSet - Underlying attribute set.
Returns:
Synchronized view of attributeSet.
Throws:
NullPointerException - Thrown if attributeSet is null.

synchronizedView

public static DocAttributeSet synchronizedView(DocAttributeSet attributeSet)
Creates a synchronized view of the given doc attribute set.

Parameters:
attributeSet - Underlying doc attribute set.
Returns:
Synchronized view of attributeSet.
Throws:
NullPointerException - Thrown if attributeSet is null.

synchronizedView

public static PrintRequestAttributeSet synchronizedView(PrintRequestAttributeSet attributeSet)
Creates a synchronized view of the given print request attribute set.

Parameters:
attributeSet - Underlying print request attribute set.
Returns:
Synchronized view of attributeSet.
Throws:
NullPointerException - Thrown if attributeSet is null.

synchronizedView

public static PrintJobAttributeSet synchronizedView(PrintJobAttributeSet attributeSet)
Creates a synchronized view of the given print job attribute set.

Parameters:
attributeSet - Underlying print job attribute set.
Returns:
Synchronized view of attributeSet.
Throws:
NullPointerException - Thrown if attributeSet is null.

synchronizedView

public static PrintServiceAttributeSet synchronizedView(PrintServiceAttributeSet attributeSet)
Creates a synchronized view of the given print service attribute set.

Parameters:
attributeSet - Underlying print service attribute set.
Returns:
Synchronized view of attributeSet.

verifyAttributeCategory

public static Class<?> verifyAttributeCategory(Object object,
                                               Class<?> interfaceName)
Verify that the given object is a Class that implements the given interface, which is assumed to be interface Attribute or a subinterface thereof.

Parameters:
object - Object to test.
interfaceName - Interface the object must implement.
Returns:
If object is a Class that implements interfaceName, object is returned downcast to type Class; otherwise an exception is thrown.
Throws:
NullPointerException - (unchecked exception) Thrown if object is null.
ClassCastException - (unchecked exception) Thrown if object is not a Class that implements interfaceName.

verifyAttributeValue

public static Attribute verifyAttributeValue(Object object,
                                             Class<?> interfaceName)
Verify that the given object is an instance of the given interface, which is assumed to be interface Attribute or a subinterface thereof.

Parameters:
object - Object to test.
interfaceName - Interface of which the object must be an instance.
Returns:
If object is an instance of interfaceName, object is returned downcast to type Attribute; otherwise an exception is thrown.
Throws:
NullPointerException - (unchecked exception) Thrown if object is null.
ClassCastException - (unchecked exception) Thrown if object is not an instance of interfaceName.

verifyCategoryForValue

public static void verifyCategoryForValue(Class<?> category,
                                          Attribute attribute)
Verify that the given attribute category object is equal to the category of the given attribute value object. If so, this method returns doing nothing. If not, this method throws an exception.

Parameters:
category - Attribute category to test.
attribute - Attribute value to test.
Throws:
NullPointerException - (unchecked exception) Thrown if the category is null or if the attribute is null.
IllegalArgumentException - (unchecked exception) Thrown if the category is not equal to the category of the attribute.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.print.attribute.AttributeSetUtilities

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.AttributeSetUtilities

No usage of javax.print.attribute.AttributeSetUtilities

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.DateTimeSyntax

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.DateTimeSyntax

Packages that use DateTimeSyntax
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of DateTimeSyntax in javax.print.attribute.standard

Subclasses of DateTimeSyntax in javax.print.attribute.standard
class | DateTimeAtCompleted Class DateTimeAtCompleted is a printing attribute class, a date-time attribute, that indicates the date and time at which the Print Job completed (or was canceled or aborted).
class | DateTimeAtCreation Class DateTimeAtCreation is a printing attribute class, a date-time attribute, that indicates the date and time at which the Print Job was created.
class | DateTimeAtProcessing Class DateTimeAtProcessing is a printing attribute class, a date-time attribute, that indicates the date and time at which the Print Job first began processing.
class | JobHoldUntil Class JobHoldUntil is a printing attribute class, a date-time attribute, that specifies the exact date and time at which the job must become a candidate for printing.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.EnumSyntax

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.EnumSyntax

Packages that use EnumSyntax
javax.print.attribute | Provides classes and interfaces that describe the types of JavaTM Print Service attributes and how they can be collected into attribute sets.
javax.print.attribute.standard | Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of EnumSyntax in javax.print.attribute

Methods in javax.print.attribute that return EnumSyntax
protected  EnumSyntax[] EnumSyntax.getEnumValueTable()
Returns the enumeration value table for this enumeration value's enumeration class.

Uses of EnumSyntax in javax.print.attribute.standard

Subclasses of EnumSyntax in javax.print.attribute.standard
class | Chromaticity Class Chromaticity is a printing attribute class, an enumeration, that specifies monochrome or color printing.
class | ColorSupported Class ColorSupported is a printing attribute class, an enumeration, that identifies whether the device is capable of any type of color printing at all, including highlight color as well as full process color.
class | Compression Class Compression is a printing attribute class, an enumeration, that specifies how print data is compressed.
class | Fidelity Class Fidelity is a printing attribute class, an enumeration, that indicates whether total fidelity to client supplied print request attributes is required.
class | Finishings Class Finishings is a printing attribute class, an enumeration, that identifies whether the printer applies a finishing operation of some kind of binding to each copy of each printed document in the job.
class | JobSheets Class JobSheets is a printing attribute class, an enumeration, that determines which job start and end sheets, if any, must be printed with a job.
class | JobState JobState is a printing attribute class, an enumeration, that identifies the current state of a print job.
class | JobStateReason Class JobStateReason is a printing attribute class, an enumeration, that provides additional information about the job's current state, i.e., information that augments the value of the job's JobState attribute.
class | Media Class Media is a printing attribute class that specifies the medium on which to print.
class | MediaName Class MediaName is a subclass of Media, a printing attribute class (an enumeration) that specifies the media for a print job as a name.
class | MediaSizeName Class MediaSizeName is a subclass of Media.
class | MediaTray Class MediaTray is a subclass of Media.
class | MultipleDocumentHandling Class MultipleDocumentHandling is a printing attribute class, an enumeration, that controls finishing operations and the placement of one or more print-stream pages into impressions and onto media sheets.
class | OrientationRequested Class OrientationRequested is a printing attribute class, an enumeration, that indicates the desired orientation for printed print-stream pages; it does not describe the orientation of the client-supplied print-stream pages.
class | PDLOverrideSupported Class PDLOverrideSupported is a printing attribute class, an enumeration, that expresses the printer's ability to attempt to override processing instructions embedded in documents' print data with processing instructions specified as attributes outside the print data.
class | PresentationDirection Class PresentationDirection is a printing attribute class, an enumeration, that is used in conjunction with the NumberUp attribute to indicate the layout of multiple print-stream pages to impose upon a single side of an instance of a selected medium.
class | PrinterIsAcceptingJobs Class PrinterIsAcceptingJobs is a printing attribute class, an enumeration, that indicates whether the printer is currently able to accept jobs.
class | PrinterState Class PrinterState is a printing attribute class, an enumeration, that identifies the current state of a printer.
class | PrinterStateReason Class PrinterStateReason is a printing attribute class, an enumeration, that provides additional information about the printer's current state, i.e., information that augments the value of the printer's PrinterState attribute.
class | PrintQuality Class PrintQuality is a printing attribute class, an enumeration, that specifies the print quality that the printer uses for the job.
class | ReferenceUriSchemesSupported Class ReferenceUriSchemesSupported is a printing attribute class an enumeration, that indicates a "URI scheme," such as "http:" or "ftp:", that a printer can use to retrieve print data stored at a URI location.
class | Severity Class Severity is a printing attribute class, an enumeration, that denotes the severity of a PrinterStateReason attribute.
class | SheetCollate Class SheetCollate is a printing attribute class, an enumeration, that specifies whether or not the media sheets of each copy of each printed document in a job are to be in sequence, when multiple copies of the document are specified by the Copies attribute.
class | Sides Class Sides is a printing attribute class, an enumeration, that specifies how print-stream pages are to be imposed upon the sides of an instance of a selected medium, i.e., an impression.

Methods in javax.print.attribute.standard that return EnumSyntax
protected EnumSyntax[] | ReferenceUriSchemesSupported.getEnumValueTable() Returns the enumeration value table for class ReferenceUriSchemesSupported.
protected EnumSyntax[] | PresentationDirection.getEnumValueTable() Returns the enumeration value table for class PresentationDirection.
protected EnumSyntax[] | PDLOverrideSupported.getEnumValueTable() Returns the enumeration value table for class PDLOverrideSupported.
protected EnumSyntax[] | MultipleDocumentHandling.getEnumValueTable() Returns the enumeration value table for class MultipleDocumentHandling.
protected EnumSyntax[] | MediaName.getEnumValueTable() Returns the enumeration value table for class MediaTray.
protected EnumSyntax[] | JobStateReason.getEnumValueTable() Returns the enumeration value table for class JobStateReason.
protected EnumSyntax[] | JobState.getEnumValueTable() Returns the enumeration value table for class JobState.
protected EnumSyntax[] | Finishings.getEnumValueTable() Returns the enumeration value table for class Finishings.
protected EnumSyntax[] | Compression.getEnumValueTable() Returns the enumeration value table for class Compression.
protected EnumSyntax[] | PrintQuality.getEnumValueTable() Returns the enumeration value table for class PrintQuality.
protected EnumSyntax[] | MediaTray.getEnumValueTable() Returns the enumeration value table for class MediaTray.
protected EnumSyntax[] | ColorSupported.getEnumValueTable() Returns the enumeration value table for class ColorSupported.
protected EnumSyntax[] | MediaSizeName.getEnumValueTable() Returns the enumeration value table for class MediaSizeName.
protected EnumSyntax[] | SheetCollate.getEnumValueTable() Returns the enumeration value table for class SheetCollate.
protected EnumSyntax[] | PrinterIsAcceptingJobs.getEnumValueTable() Returns the enumeration value table for class PrinterIsAcceptingJobs.
protected EnumSyntax[] | Severity.getEnumValueTable() Returns the enumeration value table for class Severity.
protected EnumSyntax[] | PrinterStateReason.getEnumValueTable() Returns the enumeration value table for class PrinterStateReason.
protected EnumSyntax[] | PrinterState.getEnumValueTable() Returns the enumeration value table for class PrinterState.
protected EnumSyntax[] | JobSheets.getEnumValueTable() Returns the enumeration value table for class JobSheets.
protected EnumSyntax[] | Fidelity.getEnumValueTable() Returns the enumeration value table for class Fidelity.
protected EnumSyntax[] | Chromaticity.getEnumValueTable() Returns the enumeration value table for class Chromaticity.
protected EnumSyntax[] | Sides.getEnumValueTable() Returns the enumeration value table for class Sides.
protected EnumSyntax[] | OrientationRequested.getEnumValueTable() Returns the enumeration value table for class OrientationRequested.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.HashAttributeSet

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.HashAttributeSet

Packages that use HashAttributeSet
javax.print.attribute Provides classes and interfaces that describe the types of JavaTM Print Service attributes and how they can be collected into attribute sets.

Uses of HashAttributeSet in javax.print.attribute

Subclasses of HashAttributeSet in javax.print.attribute
class | HashDocAttributeSet Class HashDocAttributeSet provides an attribute set which inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface DocAttributeSet.
class | HashPrintJobAttributeSet Class HashPrintJobAttributeSet provides an attribute set which inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface PrintJobAttributeSet.
class | HashPrintRequestAttributeSet Class HashPrintRequestAttributeSet inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface PrintRequestAttributeSet.
class | HashPrintServiceAttributeSet Class HashPrintServiceAttributeSet provides an attribute set which inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface PrintServiceAttributeSet.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.HashDocAttributeSet

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.HashDocAttributeSet

No usage of javax.print.attribute.HashDocAttributeSet

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.HashPrintJobAttributeSet

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.HashPrintJobAttributeSet

No usage of javax.print.attribute.HashPrintJobAttributeSet

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.HashPrintRequestAttributeSet

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.HashPrintRequestAttributeSet

No usage of javax.print.attribute.HashPrintRequestAttributeSet

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.HashPrintServiceAttributeSet

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.HashPrintServiceAttributeSet

No usage of javax.print.attribute.HashPrintServiceAttributeSet

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.IntegerSyntax

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.IntegerSyntax

Packages that use IntegerSyntax
javax.print.attribute | Provides classes and interfaces that describe the types of JavaTM Print Service attributes and how they can be collected into attribute sets.
javax.print.attribute.standard | Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of IntegerSyntax in javax.print.attribute

Methods in javax.print.attribute with parameters of type IntegerSyntax
 boolean SetOfIntegerSyntax.contains(IntegerSyntax attribute)
Determine if this set-of-integer attribute contains the given integer attribute's value.

Uses of IntegerSyntax in javax.print.attribute.standard

Subclasses of IntegerSyntax in javax.print.attribute.standard
class | Copies Class Copies is an integer valued printing attribute class that specifies the number of copies to be printed.
class | JobImpressions Class JobImpressions is an integer valued printing attribute class that specifies the total size in number of impressions of the document(s) being submitted.
class | JobImpressionsCompleted Class JobImpressionsCompleted is an integer valued printing attribute class that specifies the number of impressions completed for the job so far.
class | JobKOctets Class JobKOctets is an integer valued printing attribute class that specifies the total size of the document(s) in K octets, i.e., in units of 1024 octets requested to be processed in the job.
class | JobKOctetsProcessed Class JobKOctetsProcessed is an integer valued printing attribute class that specifies the total number of print data octets processed so far in K octets, i.e., in units of 1024 octets.
class | JobMediaSheets Class JobMediaSheets is an integer valued printing attribute class that specifies the total number of media sheets to be produced for this job.
class | JobMediaSheetsCompleted Class JobMediaSheetsCompleted is an integer valued printing attribute class that specifies the number of media sheets which have completed marking and stacking for the entire job so far, whether those sheets have been processed on one side or on both.
class | JobPriority Class JobPriority is an integer valued printing attribute class that specifies a print job's priority.
class | JobPrioritySupported Class JobPrioritySupported is an integer valued printing attribute class that specifies whether a Print Service instance supports the JobPriority attribute and the number of different job priority levels supported.
class | NumberOfDocuments Class NumberOfDocuments is an integer valued printing attribute that indicates the number of individual docs the printer has accepted for this job, regardless of whether the docs' print data has reached the printer or not.
class | NumberOfInterveningJobs Class NumberOfInterveningJobs is an integer valued printing attribute that indicates the number of jobs that are ahead of this job in the relative chronological order of expected time to complete (i.e., the current scheduled order).
class | NumberUp Class NumberUp is an integer valued printing attribute class that specifies the number of print-stream pages to impose upon a single side of an instance of a selected medium.
class | PagesPerMinute Class PagesPerMinute is an integer valued printing attribute that indicates the nominal number of pages per minute to the nearest whole number which may be generated by this printer (e.g., simplex, black-and-white).
class | PagesPerMinuteColor Class PagesPerMinuteColor is an integer valued printing attribute that indicates the nominal number of pages per minute to the nearest whole number which may be generated by this printer when printing color (e.g., simplex, color).
class | QueuedJobCount Class QueuedJobCount is an integer valued printing attribute that indicates the number of jobs in the printer whose JobState is either PENDING, PENDING_HELD, PROCESSING, or PROCESSING_STOPPED.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.ResolutionSyntax

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.ResolutionSyntax

Packages that use ResolutionSyntax
javax.print.attribute | Provides classes and interfaces that describe the types of JavaTM Print Service attributes and how they can be collected into attribute sets.
javax.print.attribute.standard | Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of ResolutionSyntax in javax.print.attribute

Methods in javax.print.attribute with parameters of type ResolutionSyntax
 boolean ResolutionSyntax.lessThanOrEquals(ResolutionSyntax other)
Determine whether this resolution attribute's value is less than or equal to the given resolution attribute's value.

Uses of ResolutionSyntax in javax.print.attribute.standard

Subclasses of ResolutionSyntax in javax.print.attribute.standard
 class PrinterResolution
Class PrinterResolution is a printing attribute class that specifies an exact resolution supported by a printer or to be used for a print job.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.SetOfIntegerSyntax

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.SetOfIntegerSyntax

Packages that use SetOfIntegerSyntax
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of SetOfIntegerSyntax in javax.print.attribute.standard

Subclasses of SetOfIntegerSyntax in javax.print.attribute.standard
class | CopiesSupported Class CopiesSupported is a printing attribute class, a set of integers, that gives the supported values for a Copies attribute.
class | JobImpressionsSupported Class JobImpressionsSupported is a printing attribute class, a set of integers, that gives the supported values for a JobImpressions attribute.
class | JobKOctetsSupported Class JobKOctetsSupported is a printing attribute class, a set of integers, that gives the supported values for a JobKOctets attribute.
class | JobMediaSheetsSupported Class JobMediaSheetsSupported is a printing attribute class, a set of integers, that gives the supported values for a JobMediaSheets attribute.
class | NumberUpSupported Class NumberUpSupported is a printing attribute class, a set of integers, that gives the supported values for a NumberUp attribute.
class | PageRanges Class PageRanges is a printing attribute class, a set of integers, that identifies the range(s) of print-stream pages that the Printer object uses for each copy of each document which are to be printed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.Size2DSyntax

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.Size2DSyntax

Packages that use Size2DSyntax
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of Size2DSyntax in javax.print.attribute.standard

Subclasses of Size2DSyntax in javax.print.attribute.standard
 class MediaSize
Class MediaSize is a two-dimensional size valued printing attribute class that indicates the dimensions of the medium in a portrait orientation, with the X dimension running along the bottom edge and the Y dimension running along the left edge.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.TextSyntax

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.TextSyntax

Packages that use TextSyntax
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of TextSyntax in javax.print.attribute.standard

Subclasses of TextSyntax in javax.print.attribute.standard
class | DocumentName Class DocumentName is a printing attribute class, a text attribute, that specifies the name of a document.
class | JobMessageFromOperator Class JobMessageFromOperator is a printing attribute class, a text attribute, that provides a message from an operator, system administrator, or "intelligent" process to indicate to the end user the reasons for modification or other management action taken on a job.
class | JobName Class JobName is a printing attribute class, a text attribute, that specifies the name of a print job.
class | JobOriginatingUserName Class JobOriginatingUserName is a printing attribute class, a text attribute, that contains the name of the end user that submitted the print job.
class | OutputDeviceAssigned Class OutputDeviceAssigned is a printing attribute class, a text attribute, that identifies the output device to which the service has assigned this job.
class | PrinterInfo Class PrinterInfo is a printing attribute class, a text attribute, that provides descriptive information about a printer.
class | PrinterLocation Class PrinterLocation is a printing attribute class, a text attribute, that identifies the location of the device.
class | PrinterMakeAndModel Class PrinterMakeAndModel is a printing attribute class, a text attribute, that the make and model of the printer.
class | PrinterMessageFromOperator Class PrinterMessageFromOperator is a printing attribute class, a text attribute, that provides a message from an operator, system administrator, or "intelligent" process to indicate to the end user information about or status of the printer, such as why it is unavailable or when it is expected to be available.
class | PrinterName Class PrinterName is a printing attribute class, a text attribute, that specifies the name of a printer.
class | RequestingUserName Class RequestingUserName is a printing attribute class, a text attribute, that specifies the name of the end user that submitted the print job.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.UnmodifiableSetException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.UnmodifiableSetException

No usage of javax.print.attribute.UnmodifiableSetException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.URISyntax

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.URISyntax

Packages that use URISyntax
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of URISyntax in javax.print.attribute.standard

Subclasses of URISyntax in javax.print.attribute.standard
class | Destination Class Destination is a printing attribute class, a URI, that is used to indicate an alternate destination for the spooled printer formatted data.
class | PrinterMoreInfo Class PrinterMoreInfo is a printing attribute class, a URI, that is used to obtain more information about this specific printer.
class | PrinterMoreInfoManufacturer Class PrinterMoreInfoManufacturer is a printing attribute class, a URI, that is used to obtain more information about this type of device.
class | PrinterURI Class PrinterURI is a printing attribute class, a URI, that specifies the globally unique name of a printer.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.attribute.Attribute

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.attribute.Attribute

Packages that use Attribute
javax.print | Provides the principal classes and interfaces for the JavaTM Print Service API.
javax.print.attribute | Provides classes and interfaces that describe the types of JavaTM Print Service attributes and how they can be collected into attribute sets.
javax.print.attribute.standard | Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of Attribute in javax.print

Methods in javax.print that return Attribute
 Attribute[] AttributeException.getUnsupportedValues()
Returns the array of printing attributes for which the Print Service instance supports the attribute but does not support that particular value of the attribute, or null if there are no such attribute values.

Methods in javax.print with parameters of type Attribute
 boolean PrintService.isAttributeValueSupported(Attribute attrval, DocFlavor flavor, AttributeSet attributes)
Determines whether a client can specify the given printing attribute value when setting up a job for this Print Service.

Method parameters in javax.print with type arguments of type Attribute
Object | PrintService.getDefaultAttributeValue(Class<? extends Attribute> category) Determines this print service's default printing attribute value in the given category.
Object | PrintService.getSupportedAttributeValues(Class<? extends Attribute> category, DocFlavor flavor, AttributeSet attributes) Determines the printing attribute values a client can specify in the given category when setting up a job for this print service.
boolean | PrintService.isAttributeCategorySupported(Class<? extends Attribute> category) Determines whether a client can specify the given printing attribute category when setting up a job for this print service.

Uses of Attribute in javax.print.attribute

Subinterfaces of Attribute in javax.print.attribute
interface | DocAttribute Interface DocAttribute is a tagging interface which a printing attribute class implements to indicate the attribute denotes a setting for a doc.
interface | PrintJobAttribute PrintJobAttribute is a tagging interface which a printing attribute class implements to indicate the attribute describes the status of a Print Job or some other characteristic of a Print Job.
interface | PrintRequestAttribute Interface PrintRequestAttribute is a tagging interface which a printing attribute class implements to indicate the attribute denotes a requested setting for a print job.
interface | PrintServiceAttribute Interface PrintServiceAttribute is a tagging interface which a printing attribute class implements to indicate the attribute describes the status of a Print Service or some other characteristic of a Print Service.
interface | SupportedValuesAttribute Interface SupportedValuesAttribute is a tagging interface which a printing attribute class implements to indicate the attribute describes the supported values for another attribute.

Methods in javax.print.attribute that return Attribute
Attribute | HashAttributeSet.get(Class<?> category) Returns the attribute value which this attribute set contains in the given attribute category.
Attribute | AttributeSet.get(Class<?> category) Returns the attribute value which this attribute set contains in the given attribute category.
Attribute[] | HashAttributeSet.toArray()
Attribute[] | AttributeSet.toArray() Returns an array of the attributes contained in this set.
static Attribute | AttributeSetUtilities.verifyAttributeValue(Object object, Class<?> interfaceName) Verify that the given object is an instance of the given interface, which is assumed to be interface Attribute or a subinterface thereof.

Methods in javax.print.attribute that return types with arguments of type Attribute
 Class<? extends Attribute> Attribute.getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value when it is added to an attribute set.

Methods in javax.print.attribute with parameters of type Attribute
boolean | HashAttributeSet.add(Attribute attribute) Adds the specified attribute to this attribute set if it is not already present, first removing any existing in the same attribute category as the specified attribute value.
boolean | DocAttributeSet.add(Attribute attribute) Adds the specified attribute value to this attribute set if it is not already present, first removing any existing value in the same attribute category as the specified attribute value (optional operation).
boolean | PrintJobAttributeSet.add(Attribute attribute) Adds the specified attribute value to this attribute set if it is not already present, first removing any existing value in the same attribute category as the specified attribute value (optional operation).
boolean | PrintServiceAttributeSet.add(Attribute attribute) Adds the specified attribute value to this attribute set if it is not already present, first removing any existing value in the same attribute category as the specified attribute value (optional operation).
boolean | AttributeSet.add(Attribute attribute) Adds the specified attribute to this attribute set if it is not already present, first removing any existing value in the same attribute category as the specified attribute value.
boolean | PrintRequestAttributeSet.add(Attribute attribute) Adds the specified attribute value to this attribute set if it is not already present, first removing any existing value in the same attribute category as the specified attribute value (optional operation).
boolean | HashAttributeSet.containsValue(Attribute attribute) Returns true if this attribute set contains the given attribute.
boolean | AttributeSet.containsValue(Attribute attribute) Returns true if this attribute set contains the given attribute value.
boolean | HashAttributeSet.remove(Attribute attribute) Removes the specified attribute from this attribute set if present.
boolean | AttributeSet.remove(Attribute attribute) Removes the specified attribute from this attribute set if present.
static void | AttributeSetUtilities.verifyCategoryForValue(Class<?> category, Attribute attribute) Verify that the given attribute category object is equal to the category of the given attribute value object.

Constructors in javax.print.attribute with parameters of type Attribute
HashAttributeSet(Attribute attribute)
Construct a new attribute set, initially populated with the given attribute.
HashAttributeSet(Attribute[] attributes)
Construct a new attribute set, initially populated with the values from the given array.
HashAttributeSet(Attribute[] attributes, Class<?> interfaceName)
Construct a new attribute set, where the members of the attribute set are restricted to the given interface.
HashAttributeSet(Attribute attribute, Class<?> interfaceName)
Construct a new attribute set, initially populated with the given attribute, where the members of the attribute set are restricted to the given interface.

Uses of Attribute in javax.print.attribute.standard

Methods in javax.print.attribute.standard that return types with arguments of type Attribute
Class<? extends Attribute> | ReferenceUriSchemesSupported.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | QueuedJobCount.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PrinterURI.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PrinterResolution.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PrinterName.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PrinterMoreInfoManufacturer.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PrinterMoreInfo.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PrinterMessageFromOperator.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PrinterLocation.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PresentationDirection.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PagesPerMinuteColor.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PagesPerMinute.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PDLOverrideSupported.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | OutputDeviceAssigned.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | NumberUpSupported.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | NumberUp.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | NumberOfInterveningJobs.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | NumberOfDocuments.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | MultipleDocumentHandling.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobStateReasons.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobStateReason.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobState.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobPrioritySupported.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobMessageFromOperator.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobMediaSheetsSupported.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobMediaSheetsCompleted.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobKOctetsSupported.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobKOctetsProcessed.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobMediaSheets.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobKOctets.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobImpressionsSupported.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobImpressionsCompleted.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobImpressions.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobHoldUntil.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | Finishings.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | DateTimeAtProcessing.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | DateTimeAtCreation.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | DateTimeAtCompleted.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | Compression.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobOriginatingUserName.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | DocumentName.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobPriority.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PrintQuality.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PrinterInfo.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PrinterMakeAndModel.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobName.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | Destination.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PageRanges.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | CopiesSupported.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | ColorSupported.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | MediaSize.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | Media.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | SheetCollate.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | RequestingUserName.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PrinterIsAcceptingJobs.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | Severity.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PrinterStateReasons.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PrinterStateReason.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | PrinterState.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | JobSheets.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | Fidelity.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | Copies.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | Chromaticity.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | Sides.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | OrientationRequested.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
Class<? extends Attribute> | MediaPrintableArea.getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.attribute.AttributeSet

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.attribute.AttributeSet

Packages that use AttributeSet
javax.print | Provides the principal classes and interfaces for the JavaTM Print Service API.
javax.print.attribute | Provides classes and interfaces that describe the types of JavaTM Print Service attributes and how they can be collected into attribute sets.

Uses of AttributeSet in javax.print

Methods in javax.print that return AttributeSet
 AttributeSet PrintService.getUnsupportedAttributes(DocFlavor flavor, AttributeSet attributes)
Identifies the attributes that are unsupported for a print request in the context of a particular DocFlavor.

Methods in javax.print with parameters of type AttributeSet
abstract MultiDocPrintService[] | PrintServiceLookup.getMultiDocPrintServices(DocFlavor[] flavors, AttributeSet attributes) Not called directly by applications.
abstract PrintService[] | PrintServiceLookup.getPrintServices(DocFlavor flavor, AttributeSet attributes) Locates services that can be positively confirmed to support the combination of attributes and DocFlavors specified.
Object | PrintService.getSupportedAttributeValues(Class<? extends Attribute> category, DocFlavor flavor, AttributeSet attributes) Determines the printing attribute values a client can specify in the given category when setting up a job for this print service.
AttributeSet | PrintService.getUnsupportedAttributes(DocFlavor flavor, AttributeSet attributes) Identifies the attributes that are unsupported for a print request in the context of a particular DocFlavor.
boolean | PrintService.isAttributeValueSupported(Attribute attrval, DocFlavor flavor, AttributeSet attributes) Determines whether a client can specify the given printing attribute value when setting up a job for this Print Service.
static MultiDocPrintService[] | PrintServiceLookup.lookupMultiDocPrintServices(DocFlavor[] flavors, AttributeSet attributes) Locates MultiDoc print Services capable of printing MultiDocs containing all the specified doc flavors.
static PrintService[] | PrintServiceLookup.lookupPrintServices(DocFlavor flavor, AttributeSet attributes) Locates print services capable of printing the specified DocFlavor.

Uses of AttributeSet in javax.print.attribute

Subinterfaces of AttributeSet in javax.print.attribute
interface | DocAttributeSet Interface DocAttributeSet specifies the interface for a set of doc attributes, i.e.
interface | PrintJobAttributeSet Interface PrintJobAttributeSet specifies the interface for a set of print job attributes, i.e.
interface | PrintRequestAttributeSet Interface PrintRequestAttributeSet specifies the interface for a set of print request attributes, i.e.
interface | PrintServiceAttributeSet Interface PrintServiceAttributeSet specifies the interface for a set of print job attributes, i.e.

Classes in javax.print.attribute that implement AttributeSet
class | HashAttributeSet Class HashAttributeSet provides an AttributeSet implementation with characteristics of a hash map.
class | HashDocAttributeSet Class HashDocAttributeSet provides an attribute set which inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface DocAttributeSet.
class | HashPrintJobAttributeSet Class HashPrintJobAttributeSet provides an attribute set which inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface PrintJobAttributeSet.
class | HashPrintRequestAttributeSet Class HashPrintRequestAttributeSet inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface PrintRequestAttributeSet.
class | HashPrintServiceAttributeSet Class HashPrintServiceAttributeSet provides an attribute set which inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface PrintServiceAttributeSet.

Methods in javax.print.attribute that return AttributeSet
static AttributeSet | AttributeSetUtilities.synchronizedView(AttributeSet attributeSet) Creates a synchronized view of the given attribute set.
static AttributeSet | AttributeSetUtilities.unmodifiableView(AttributeSet attributeSet) Creates an unmodifiable view of the given attribute set.

Methods in javax.print.attribute with parameters of type AttributeSet
boolean | HashAttributeSet.addAll(AttributeSet attributes) Adds all of the elements in the specified set to this attribute.
boolean | DocAttributeSet.addAll(AttributeSet attributes) Adds all of the elements in the specified set to this attribute.
boolean | PrintJobAttributeSet.addAll(AttributeSet attributes) Adds all of the elements in the specified set to this attribute.
boolean | PrintServiceAttributeSet.addAll(AttributeSet attributes) Adds all of the elements in the specified set to this attribute.
boolean | AttributeSet.addAll(AttributeSet attributes) Adds all of the elements in the specified set to this attribute.
boolean | PrintRequestAttributeSet.addAll(AttributeSet attributes) Adds all of the elements in the specified set to this attribute.
static AttributeSet | AttributeSetUtilities.synchronizedView(AttributeSet attributeSet) Creates a synchronized view of the given attribute set.
static AttributeSet | AttributeSetUtilities.unmodifiableView(AttributeSet attributeSet) Creates an unmodifiable view of the given attribute set.

Constructors in javax.print.attribute with parameters of type AttributeSet
HashAttributeSet(AttributeSet attributes)
Construct a new attribute set, initially populated with the values from the given set.
HashAttributeSet(AttributeSet attributes, Class<?> interfaceName)
Construct a new attribute set, initially populated with the values from the given set where the members of the attribute set are restricted to the given interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.attribute.DocAttribute

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.attribute.DocAttribute

Packages that use DocAttribute
javax.print.attribute | Provides classes and interfaces that describe the types of JavaTM Print Service attributes and how they can be collected into attribute sets.
javax.print.attribute.standard | Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of DocAttribute in javax.print.attribute

Constructors in javax.print.attribute with parameters of type DocAttribute
HashDocAttributeSet(DocAttribute attribute)
Construct a new hash doc attribute set, initially populated with the given value.
HashDocAttributeSet(DocAttribute[] attributes)
Construct a new hash doc attribute set, initially populated with the values from the given array.

Uses of DocAttribute in javax.print.attribute.standard

Classes in javax.print.attribute.standard that implement DocAttribute
class | Chromaticity Class Chromaticity is a printing attribute class, an enumeration, that specifies monochrome or color printing.
class | Compression Class Compression is a printing attribute class, an enumeration, that specifies how print data is compressed.
class | DocumentName Class DocumentName is a printing attribute class, a text attribute, that specifies the name of a document.
class | Finishings Class Finishings is a printing attribute class, an enumeration, that identifies whether the printer applies a finishing operation of some kind of binding to each copy of each printed document in the job.
class | Media Class Media is a printing attribute class that specifies the medium on which to print.
class | MediaName Class MediaName is a subclass of Media, a printing attribute class (an enumeration) that specifies the media for a print job as a name.
class | MediaPrintableArea Class MediaPrintableArea is a printing attribute used to distinguish the printable and non-printable areas of media.
class | MediaSizeName Class MediaSizeName is a subclass of Media.
class | MediaTray Class MediaTray is a subclass of Media.
class | NumberUp Class NumberUp is an integer valued printing attribute class that specifies the number of print-stream pages to impose upon a single side of an instance of a selected medium.
class | OrientationRequested Class OrientationRequested is a printing attribute class, an enumeration, that indicates the desired orientation for printed print-stream pages; it does not describe the orientation of the client-supplied print-stream pages.
class | PageRanges Class PageRanges is a printing attribute class, a set of integers, that identifies the range(s) of print-stream pages that the Printer object uses for each copy of each document which are to be printed.
class | PrinterResolution Class PrinterResolution is a printing attribute class that specifies an exact resolution supported by a printer or to be used for a print job.
class | PrintQuality Class PrintQuality is a printing attribute class, an enumeration, that specifies the print quality that the printer uses for the job.
class | SheetCollate Class SheetCollate is a printing attribute class, an enumeration, that specifies whether or not the media sheets of each copy of each printed document in a job are to be in sequence, when multiple copies of the document are specified by the Copies attribute.
class | Sides Class Sides is a printing attribute class, an enumeration, that specifies how print-stream pages are to be imposed upon the sides of an instance of a selected medium, i.e., an impression.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.attribute.DocAttributeSet

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.attribute.DocAttributeSet

Packages that use DocAttributeSet
javax.print | Provides the principal classes and interfaces for the JavaTM Print Service API.
javax.print.attribute | Provides classes and interfaces that describe the types of JavaTM Print Service attributes and how they can be collected into attribute sets.

Uses of DocAttributeSet in javax.print

Methods in javax.print that return DocAttributeSet
DocAttributeSet | SimpleDoc.getAttributes() Obtains the set of printing attributes for this doc object.
DocAttributeSet | Doc.getAttributes() Obtains the set of printing attributes for this doc object.

Constructors in javax.print with parameters of type DocAttributeSet
SimpleDoc(Object printData, DocFlavor flavor, DocAttributeSet attributes)
Constructs a SimpleDoc with the specified print data, doc flavor and doc attribute set.

Uses of DocAttributeSet in javax.print.attribute

Classes in javax.print.attribute that implement DocAttributeSet
 class HashDocAttributeSet
Class HashDocAttributeSet provides an attribute set which inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface DocAttributeSet.

Methods in javax.print.attribute that return DocAttributeSet
static DocAttributeSet | AttributeSetUtilities.synchronizedView(DocAttributeSet attributeSet) Creates a synchronized view of the given doc attribute set.
static DocAttributeSet | AttributeSetUtilities.unmodifiableView(DocAttributeSet attributeSet) Creates an unmodifiable view of the given doc attribute set.

Methods in javax.print.attribute with parameters of type DocAttributeSet
static DocAttributeSet | AttributeSetUtilities.synchronizedView(DocAttributeSet attributeSet) Creates a synchronized view of the given doc attribute set.
static DocAttributeSet | AttributeSetUtilities.unmodifiableView(DocAttributeSet attributeSet) Creates an unmodifiable view of the given doc attribute set.

Constructors in javax.print.attribute with parameters of type DocAttributeSet
HashDocAttributeSet(DocAttributeSet attributes)
Construct a new attribute set, initially populated with the values from the given set where the members of the attribute set are restricted to the DocAttribute interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.attribute.PrintJobAttribute

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.attribute.PrintJobAttribute

Packages that use PrintJobAttribute
javax.print.attribute | Provides classes and interfaces that describe the types of JavaTM Print Service attributes and how they can be collected into attribute sets.
javax.print.attribute.standard | Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of PrintJobAttribute in javax.print.attribute

Constructors in javax.print.attribute with parameters of type PrintJobAttribute
HashPrintJobAttributeSet(PrintJobAttribute attribute)
Construct a new hash print job attribute set, initially populated with the given value.
HashPrintJobAttributeSet(PrintJobAttribute[] attributes)
Construct a new hash print job attribute set, initially populated with the values from the given array.

Uses of PrintJobAttribute in javax.print.attribute.standard

Classes in javax.print.attribute.standard that implement PrintJobAttribute
class | Chromaticity Class Chromaticity is a printing attribute class, an enumeration, that specifies monochrome or color printing.
class | Copies Class Copies is an integer valued printing attribute class that specifies the number of copies to be printed.
class | DateTimeAtCompleted Class DateTimeAtCompleted is a printing attribute class, a date-time attribute, that indicates the date and time at which the Print Job completed (or was canceled or aborted).
class | DateTimeAtCreation Class DateTimeAtCreation is a printing attribute class, a date-time attribute, that indicates the date and time at which the Print Job was created.
class | DateTimeAtProcessing Class DateTimeAtProcessing is a printing attribute class, a date-time attribute, that indicates the date and time at which the Print Job first began processing.
class | Destination Class Destination is a printing attribute class, a URI, that is used to indicate an alternate destination for the spooled printer formatted data.
class | Fidelity Class Fidelity is a printing attribute class, an enumeration, that indicates whether total fidelity to client supplied print request attributes is required.
class | Finishings Class Finishings is a printing attribute class, an enumeration, that identifies whether the printer applies a finishing operation of some kind of binding to each copy of each printed document in the job.
class | JobHoldUntil Class JobHoldUntil is a printing attribute class, a date-time attribute, that specifies the exact date and time at which the job must become a candidate for printing.
class | JobImpressions Class JobImpressions is an integer valued printing attribute class that specifies the total size in number of impressions of the document(s) being submitted.
class | JobImpressionsCompleted Class JobImpressionsCompleted is an integer valued printing attribute class that specifies the number of impressions completed for the job so far.
class | JobKOctets Class JobKOctets is an integer valued printing attribute class that specifies the total size of the document(s) in K octets, i.e., in units of 1024 octets requested to be processed in the job.
class | JobKOctetsProcessed Class JobKOctetsProcessed is an integer valued printing attribute class that specifies the total number of print data octets processed so far in K octets, i.e., in units of 1024 octets.
class | JobMediaSheets Class JobMediaSheets is an integer valued printing attribute class that specifies the total number of media sheets to be produced for this job.
class | JobMediaSheetsCompleted Class JobMediaSheetsCompleted is an integer valued printing attribute class that specifies the number of media sheets which have completed marking and stacking for the entire job so far, whether those sheets have been processed on one side or on both.
class | JobMessageFromOperator Class JobMessageFromOperator is a printing attribute class, a text attribute, that provides a message from an operator, system administrator, or "intelligent" process to indicate to the end user the reasons for modification or other management action taken on a job.
class | JobName Class JobName is a printing attribute class, a text attribute, that specifies the name of a print job.
class | JobOriginatingUserName Class JobOriginatingUserName is a printing attribute class, a text attribute, that contains the name of the end user that submitted the print job.
class | JobPriority Class JobPriority is an integer valued printing attribute class that specifies a print job's priority.
class | JobSheets Class JobSheets is a printing attribute class, an enumeration, that determines which job start and end sheets, if any, must be printed with a job.
class | JobState JobState is a printing attribute class, an enumeration, that identifies the current state of a print job.
class | JobStateReasons Class JobStateReasons is a printing attribute class, a set of enumeration values, that provides additional information about the job's current state, i.e., information that augments the value of the job's JobState attribute.
class | Media Class Media is a printing attribute class that specifies the medium on which to print.
class | MediaName Class MediaName is a subclass of Media, a printing attribute class (an enumeration) that specifies the media for a print job as a name.
class | MediaPrintableArea Class MediaPrintableArea is a printing attribute used to distinguish the printable and non-printable areas of media.
class | MediaSizeName Class MediaSizeName is a subclass of Media.
class | MediaTray Class MediaTray is a subclass of Media.
class | MultipleDocumentHandling Class MultipleDocumentHandling is a printing attribute class, an enumeration, that controls finishing operations and the placement of one or more print-stream pages into impressions and onto media sheets.
class | NumberOfDocuments Class NumberOfDocuments is an integer valued printing attribute that indicates the number of individual docs the printer has accepted for this job, regardless of whether the docs' print data has reached the printer or not.
class | NumberOfInterveningJobs Class NumberOfInterveningJobs is an integer valued printing attribute that indicates the number of jobs that are ahead of this job in the relative chronological order of expected time to complete (i.e., the current scheduled order).
class | NumberUp Class NumberUp is an integer valued printing attribute class that specifies the number of print-stream pages to impose upon a single side of an instance of a selected medium.
class | OrientationRequested Class OrientationRequested is a printing attribute class, an enumeration, that indicates the desired orientation for printed print-stream pages; it does not describe the orientation of the client-supplied print-stream pages.
class | OutputDeviceAssigned Class OutputDeviceAssigned is a printing attribute class, a text attribute, that identifies the output device to which the service has assigned this job.
class | PageRanges Class PageRanges is a printing attribute class, a set of integers, that identifies the range(s) of print-stream pages that the Printer object uses for each copy of each document which are to be printed.
class | PresentationDirection Class PresentationDirection is a printing attribute class, an enumeration, that is used in conjunction with the NumberUp attribute to indicate the layout of multiple print-stream pages to impose upon a single side of an instance of a selected medium.
class | PrinterResolution Class PrinterResolution is a printing attribute class that specifies an exact resolution supported by a printer or to be used for a print job.
class | PrintQuality Class PrintQuality is a printing attribute class, an enumeration, that specifies the print quality that the printer uses for the job.
class | SheetCollate Class SheetCollate is a printing attribute class, an enumeration, that specifies whether or not the media sheets of each copy of each printed document in a job are to be in sequence, when multiple copies of the document are specified by the Copies attribute.
class | Sides Class Sides is a printing attribute class, an enumeration, that specifies how print-stream pages are to be imposed upon the sides of an instance of a selected medium, i.e., an impression.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.attribute.PrintJobAttributeSet

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.attribute.PrintJobAttributeSet

Packages that use PrintJobAttributeSet
javax.print | Provides the principal classes and interfaces for the JavaTM Print Service API.
javax.print.attribute | Provides classes and interfaces that describe the types of JavaTM Print Service attributes and how they can be collected into attribute sets.
javax.print.event | Package javax.print.event contains event classes and listener interfaces.

Uses of PrintJobAttributeSet in javax.print

Methods in javax.print that return PrintJobAttributeSet
 PrintJobAttributeSet DocPrintJob.getAttributes()
Obtains this Print Job's set of printing attributes.

Methods in javax.print with parameters of type PrintJobAttributeSet
 void DocPrintJob.addPrintJobAttributeListener(PrintJobAttributeListener listener, PrintJobAttributeSet attributes)
Registers a listener for changes in the specified attributes.

Uses of PrintJobAttributeSet in javax.print.attribute

Classes in javax.print.attribute that implement PrintJobAttributeSet
 class HashPrintJobAttributeSet
Class HashPrintJobAttributeSet provides an attribute set which inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface PrintJobAttributeSet.

Methods in javax.print.attribute that return PrintJobAttributeSet
static PrintJobAttributeSet | AttributeSetUtilities.synchronizedView(PrintJobAttributeSet attributeSet) Creates a synchronized view of the given print job attribute set.
static PrintJobAttributeSet | AttributeSetUtilities.unmodifiableView(PrintJobAttributeSet attributeSet) Creates an unmodifiable view of the given print job attribute set.

Methods in javax.print.attribute with parameters of type PrintJobAttributeSet
static PrintJobAttributeSet | AttributeSetUtilities.synchronizedView(PrintJobAttributeSet attributeSet) Creates a synchronized view of the given print job attribute set.
static PrintJobAttributeSet | AttributeSetUtilities.unmodifiableView(PrintJobAttributeSet attributeSet) Creates an unmodifiable view of the given print job attribute set.

Constructors in javax.print.attribute with parameters of type PrintJobAttributeSet
HashPrintJobAttributeSet(PrintJobAttributeSet attributes)
Construct a new attribute set, initially populated with the values from the given set where the members of the attribute set are restricted to the PrintJobAttribute interface.

Uses of PrintJobAttributeSet in javax.print.event

Methods in javax.print.event that return PrintJobAttributeSet
 PrintJobAttributeSet PrintJobAttributeEvent.getAttributes()
Determine the printing attributes that changed and their new values.

Constructors in javax.print.event with parameters of type PrintJobAttributeSet
PrintJobAttributeEvent(DocPrintJob source, PrintJobAttributeSet attributes)
Constructs a PrintJobAttributeEvent object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.attribute.PrintRequestAttribute

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.attribute.PrintRequestAttribute

Packages that use PrintRequestAttribute
javax.print.attribute | Provides classes and interfaces that describe the types of JavaTM Print Service attributes and how they can be collected into attribute sets.
javax.print.attribute.standard | Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of PrintRequestAttribute in javax.print.attribute

Constructors in javax.print.attribute with parameters of type PrintRequestAttribute
HashPrintRequestAttributeSet(PrintRequestAttribute attribute)
Construct a new print request attribute set, initially populated with the given value.
HashPrintRequestAttributeSet(PrintRequestAttribute[] attributes)
Construct a new print request attribute set, initially populated with the values from the given array.

Uses of PrintRequestAttribute in javax.print.attribute.standard

Classes in javax.print.attribute.standard that implement PrintRequestAttribute
class | Chromaticity Class Chromaticity is a printing attribute class, an enumeration, that specifies monochrome or color printing.
class | Copies Class Copies is an integer valued printing attribute class that specifies the number of copies to be printed.
class | Destination Class Destination is a printing attribute class, a URI, that is used to indicate an alternate destination for the spooled printer formatted data.
class | Fidelity Class Fidelity is a printing attribute class, an enumeration, that indicates whether total fidelity to client supplied print request attributes is required.
class | Finishings Class Finishings is a printing attribute class, an enumeration, that identifies whether the printer applies a finishing operation of some kind of binding to each copy of each printed document in the job.
class | JobHoldUntil Class JobHoldUntil is a printing attribute class, a date-time attribute, that specifies the exact date and time at which the job must become a candidate for printing.
class | JobImpressions Class JobImpressions is an integer valued printing attribute class that specifies the total size in number of impressions of the document(s) being submitted.
class | JobKOctets Class JobKOctets is an integer valued printing attribute class that specifies the total size of the document(s) in K octets, i.e., in units of 1024 octets requested to be processed in the job.
class | JobMediaSheets Class JobMediaSheets is an integer valued printing attribute class that specifies the total number of media sheets to be produced for this job.
class | JobName Class JobName is a printing attribute class, a text attribute, that specifies the name of a print job.
class | JobPriority Class JobPriority is an integer valued printing attribute class that specifies a print job's priority.
class | JobSheets Class JobSheets is a printing attribute class, an enumeration, that determines which job start and end sheets, if any, must be printed with a job.
class | Media Class Media is a printing attribute class that specifies the medium on which to print.
class | MediaName Class MediaName is a subclass of Media, a printing attribute class (an enumeration) that specifies the media for a print job as a name.
class | MediaPrintableArea Class MediaPrintableArea is a printing attribute used to distinguish the printable and non-printable areas of media.
class | MediaSizeName Class MediaSizeName is a subclass of Media.
class | MediaTray Class MediaTray is a subclass of Media.
class | MultipleDocumentHandling Class MultipleDocumentHandling is a printing attribute class, an enumeration, that controls finishing operations and the placement of one or more print-stream pages into impressions and onto media sheets.
class | NumberUp Class NumberUp is an integer valued printing attribute class that specifies the number of print-stream pages to impose upon a single side of an instance of a selected medium.
class | OrientationRequested Class OrientationRequested is a printing attribute class, an enumeration, that indicates the desired orientation for printed print-stream pages; it does not describe the orientation of the client-supplied print-stream pages.
class | PageRanges Class PageRanges is a printing attribute class, a set of integers, that identifies the range(s) of print-stream pages that the Printer object uses for each copy of each document which are to be printed.
class | PresentationDirection Class PresentationDirection is a printing attribute class, an enumeration, that is used in conjunction with the NumberUp attribute to indicate the layout of multiple print-stream pages to impose upon a single side of an instance of a selected medium.
class | PrinterResolution Class PrinterResolution is a printing attribute class that specifies an exact resolution supported by a printer or to be used for a print job.
class | PrintQuality Class PrintQuality is a printing attribute class, an enumeration, that specifies the print quality that the printer uses for the job.
class | RequestingUserName Class RequestingUserName is a printing attribute class, a text attribute, that specifies the name of the end user that submitted the print job.
class | SheetCollate Class SheetCollate is a printing attribute class, an enumeration, that specifies whether or not the media sheets of each copy of each printed document in a job are to be in sequence, when multiple copies of the document are specified by the Copies attribute.
class | Sides Class Sides is a printing attribute class, an enumeration, that specifies how print-stream pages are to be imposed upon the sides of an instance of a selected medium, i.e., an impression.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.attribute.PrintRequestAttributeSet

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.attribute.PrintRequestAttributeSet

Packages that use PrintRequestAttributeSet
java.awt.print | Provides classes and interfaces for a general printing API.
javax.print | Provides the principal classes and interfaces for the JavaTM Print Service API.
javax.print.attribute | Provides classes and interfaces that describe the types of JavaTM Print Service attributes and how they can be collected into attribute sets.
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of PrintRequestAttributeSet in java.awt.print

Methods in java.awt.print with parameters of type PrintRequestAttributeSet
 PageFormat PrinterJob.getPageFormat(PrintRequestAttributeSet attributes)
Calculates a PageFormat with values consistent with those supported by the current PrintService for this job (ie the value returned by getPrintService()) and media, printable area and orientation contained in attributes.
 PageFormat PrinterJob.pageDialog(PrintRequestAttributeSet attributes)
A convenience method which displays a cross-platform page setup dialog.
 void PrinterJob.print(PrintRequestAttributeSet attributes)
Prints a set of pages using the settings in the attribute set.
 boolean PrinterJob.printDialog(PrintRequestAttributeSet attributes)
A convenience method which displays a cross-platform print dialog for all services which are capable of printing 2D graphics using the Pageable interface.

Uses of PrintRequestAttributeSet in javax.print

Methods in javax.print with parameters of type PrintRequestAttributeSet
void | DocPrintJob.print(Doc doc, PrintRequestAttributeSet attributes) Prints a document with the specified job attributes.
void | MultiDocPrintJob.print(MultiDoc multiDoc, PrintRequestAttributeSet attributes) Print a MultiDoc with the specified job attributes.
static PrintService | ServiceUI.printDialog(GraphicsConfiguration gc, int x, int y, PrintService[] services, PrintService defaultService, DocFlavor flavor, PrintRequestAttributeSet attributes) Presents a dialog to the user for selecting a print service (printer).

Uses of PrintRequestAttributeSet in javax.print.attribute

Classes in javax.print.attribute that implement PrintRequestAttributeSet
 class HashPrintRequestAttributeSet
Class HashPrintRequestAttributeSet inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface PrintRequestAttributeSet.

Methods in javax.print.attribute that return PrintRequestAttributeSet
static PrintRequestAttributeSet | AttributeSetUtilities.synchronizedView(PrintRequestAttributeSet attributeSet) Creates a synchronized view of the given print request attribute set.
static PrintRequestAttributeSet | AttributeSetUtilities.unmodifiableView(PrintRequestAttributeSet attributeSet) Creates an unmodifiable view of the given print request attribute set.

Methods in javax.print.attribute with parameters of type PrintRequestAttributeSet
static PrintRequestAttributeSet | AttributeSetUtilities.synchronizedView(PrintRequestAttributeSet attributeSet) Creates a synchronized view of the given print request attribute set.
static PrintRequestAttributeSet | AttributeSetUtilities.unmodifiableView(PrintRequestAttributeSet attributeSet) Creates an unmodifiable view of the given print request attribute set.

Constructors in javax.print.attribute with parameters of type PrintRequestAttributeSet
HashPrintRequestAttributeSet(PrintRequestAttributeSet attributes)
Construct a new attribute set, initially populated with the values from the given set where the members of the attribute set are restricted to the (PrintRequestAttributeSe interface.

Uses of PrintRequestAttributeSet in javax.swing

Methods in javax.swing with parameters of type PrintRequestAttributeSet
boolean | JTable.print(JTable.PrintMode printMode, MessageFormat headerFormat, MessageFormat footerFormat, boolean showPrintDialog, PrintRequestAttributeSet attr, boolean interactive) Prints this table, as specified by the fully featured print method, with the default printer specified as the print service.
boolean | JTable.print(JTable.PrintMode printMode, MessageFormat headerFormat, MessageFormat footerFormat, boolean showPrintDialog, PrintRequestAttributeSet attr, boolean interactive, PrintService service) Prints this JTable.

Uses of PrintRequestAttributeSet in javax.swing.text

Methods in javax.swing.text with parameters of type PrintRequestAttributeSet
 boolean JTextComponent.print(MessageFormat headerFormat, MessageFormat footerFormat, boolean showPrintDialog, PrintService service, PrintRequestAttributeSet attributes, boolean interactive)
Prints the content of this JTextComponent.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.attribute.PrintServiceAttribute

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.attribute.PrintServiceAttribute

Packages that use PrintServiceAttribute
javax.print | Provides the principal classes and interfaces for the JavaTM Print Service API.
javax.print.attribute | Provides classes and interfaces that describe the types of JavaTM Print Service attributes and how they can be collected into attribute sets.
javax.print.attribute.standard | Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of PrintServiceAttribute in javax.print

Methods in javax.print with type parameters of type PrintServiceAttribute
<T extends PrintServiceAttribute>
T
PrintService.getAttribute(Class<T> category)
Gets the value of the single specified service attribute.

Uses of PrintServiceAttribute in javax.print.attribute

Constructors in javax.print.attribute with parameters of type PrintServiceAttribute
HashPrintServiceAttributeSet(PrintServiceAttribute attribute)
Construct a new hash print service attribute set, initially populated with the given value.
HashPrintServiceAttributeSet(PrintServiceAttribute[] attributes)
Construct a new print service attribute set, initially populated with the values from the given array.

Uses of PrintServiceAttribute in javax.print.attribute.standard

Classes in javax.print.attribute.standard that implement PrintServiceAttribute
class | ColorSupported Class ColorSupported is a printing attribute class, an enumeration, that identifies whether the device is capable of any type of color printing at all, including highlight color as well as full process color.
class | PagesPerMinute Class PagesPerMinute is an integer valued printing attribute that indicates the nominal number of pages per minute to the nearest whole number which may be generated by this printer (e.g., simplex, black-and-white).
class | PagesPerMinuteColor Class PagesPerMinuteColor is an integer valued printing attribute that indicates the nominal number of pages per minute to the nearest whole number which may be generated by this printer when printing color (e.g., simplex, color).
class | PDLOverrideSupported Class PDLOverrideSupported is a printing attribute class, an enumeration, that expresses the printer's ability to attempt to override processing instructions embedded in documents' print data with processing instructions specified as attributes outside the print data.
class | PrinterInfo Class PrinterInfo is a printing attribute class, a text attribute, that provides descriptive information about a printer.
class | PrinterIsAcceptingJobs Class PrinterIsAcceptingJobs is a printing attribute class, an enumeration, that indicates whether the printer is currently able to accept jobs.
class | PrinterLocation Class PrinterLocation is a printing attribute class, a text attribute, that identifies the location of the device.
class | PrinterMakeAndModel Class PrinterMakeAndModel is a printing attribute class, a text attribute, that the make and model of the printer.
class | PrinterMessageFromOperator Class PrinterMessageFromOperator is a printing attribute class, a text attribute, that provides a message from an operator, system administrator, or "intelligent" process to indicate to the end user information about or status of the printer, such as why it is unavailable or when it is expected to be available.
class | PrinterMoreInfo Class PrinterMoreInfo is a printing attribute class, a URI, that is used to obtain more information about this specific printer.
class | PrinterMoreInfoManufacturer Class PrinterMoreInfoManufacturer is a printing attribute class, a URI, that is used to obtain more information about this type of device.
class | PrinterName Class PrinterName is a printing attribute class, a text attribute, that specifies the name of a printer.
class | PrinterState Class PrinterState is a printing attribute class, an enumeration, that identifies the current state of a printer.
class | PrinterStateReasons Class PrinterStateReasons is a printing attribute class, a set of enumeration values, that provides additional information about the printer's current state, i.e., information that augments the value of the printer's PrinterState attribute.
class | PrinterURI Class PrinterURI is a printing attribute class, a URI, that specifies the globally unique name of a printer.
class | QueuedJobCount Class QueuedJobCount is an integer valued printing attribute that indicates the number of jobs in the printer whose JobState is either PENDING, PENDING_HELD, PROCESSING, or PROCESSING_STOPPED.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.attribute.PrintServiceAttributeSet

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.attribute.PrintServiceAttributeSet

Packages that use PrintServiceAttributeSet
javax.print | Provides the principal classes and interfaces for the JavaTM Print Service API.
javax.print.attribute | Provides classes and interfaces that describe the types of JavaTM Print Service attributes and how they can be collected into attribute sets.
javax.print.event | Package javax.print.event contains event classes and listener interfaces.

Uses of PrintServiceAttributeSet in javax.print

Methods in javax.print that return PrintServiceAttributeSet
 PrintServiceAttributeSet PrintService.getAttributes()
Obtains this print service's set of printer description attributes giving this Print Service's status.

Uses of PrintServiceAttributeSet in javax.print.attribute

Classes in javax.print.attribute that implement PrintServiceAttributeSet
 class HashPrintServiceAttributeSet
Class HashPrintServiceAttributeSet provides an attribute set which inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface PrintServiceAttributeSet.

Methods in javax.print.attribute that return PrintServiceAttributeSet
static PrintServiceAttributeSet | AttributeSetUtilities.synchronizedView(PrintServiceAttributeSet attributeSet) Creates a synchronized view of the given print service attribute set.
static PrintServiceAttributeSet | AttributeSetUtilities.unmodifiableView(PrintServiceAttributeSet attributeSet) Creates an unmodifiable view of the given print service attribute set.

Methods in javax.print.attribute with parameters of type PrintServiceAttributeSet
static PrintServiceAttributeSet | AttributeSetUtilities.synchronizedView(PrintServiceAttributeSet attributeSet) Creates a synchronized view of the given print service attribute set.
static PrintServiceAttributeSet | AttributeSetUtilities.unmodifiableView(PrintServiceAttributeSet attributeSet) Creates an unmodifiable view of the given print service attribute set.

Constructors in javax.print.attribute with parameters of type PrintServiceAttributeSet
HashPrintServiceAttributeSet(PrintServiceAttributeSet attributes)
Construct a new attribute set, initially populated with the values from the given set where the members of the attribute set are restricted to the PrintServiceAttribute interface.

Uses of PrintServiceAttributeSet in javax.print.event

Methods in javax.print.event that return PrintServiceAttributeSet
 PrintServiceAttributeSet PrintServiceAttributeEvent.getAttributes()
Determine the printing service attributes that changed and their new values.

Constructors in javax.print.event with parameters of type PrintServiceAttributeSet
PrintServiceAttributeEvent(PrintService source, PrintServiceAttributeSet attributes)
Constructs a PrintServiceAttributeEvent object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.attribute.SupportedValuesAttribute

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.attribute.SupportedValuesAttribute

Packages that use SupportedValuesAttribute
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of SupportedValuesAttribute in javax.print.attribute.standard

Classes in javax.print.attribute.standard that implement SupportedValuesAttribute
class | CopiesSupported Class CopiesSupported is a printing attribute class, a set of integers, that gives the supported values for a Copies attribute.
class | JobImpressionsSupported Class JobImpressionsSupported is a printing attribute class, a set of integers, that gives the supported values for a JobImpressions attribute.
class | JobKOctetsSupported Class JobKOctetsSupported is a printing attribute class, a set of integers, that gives the supported values for a JobKOctets attribute.
class | JobMediaSheetsSupported Class JobMediaSheetsSupported is a printing attribute class, a set of integers, that gives the supported values for a JobMediaSheets attribute.
class | JobPrioritySupported Class JobPrioritySupported is an integer valued printing attribute class that specifies whether a Print Service instance supports the JobPriority attribute and the number of different job priority levels supported.
class | NumberUpSupported Class NumberUpSupported is a printing attribute class, a set of integers, that gives the supported values for a NumberUp attribute.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DateTimeSyntax

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Class DateTimeSyntax

java.lang.Object
    extended by  javax.print.attribute.DateTimeSyntax
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
DateTimeAtCompleted, DateTimeAtCreation, DateTimeAtProcessing, JobHoldUntil
public abstract class DateTimeSyntax
extends Object
implements Serializable, Cloneable

Class DateTimeSyntax is an abstract base class providing the common implementation of all attributes whose value is a date and time.

Under the hood, a date-time attribute is stored as a value of class java.util.Date. You can get a date-time attribute's Date value by calling getValue(). A date-time attribute's Date value is established when it is constructed (see DateTimeSyntax(Date)). Once constructed, a date-time attribute's value is immutable.

To construct a date-time attribute from separate values of the year, month, day, hour, minute, and so on, use a java.util.Calendar object to construct a java.util.Date object, then use the java.util.Date object to construct the date-time attribute. To convert a date-time attribute to separate values of the year, month, day, hour, minute, and so on, create a java.util.Calendar object and set it to the java.util.Date from the date-time attribute. Class DateTimeSyntax stores its value in the form of a java.util.Date rather than a java.util.Calendar because it typically takes less memory to store and less time to compare a java.util.Date than a java.util.Calendar.

See Also:
Serialized Form

Constructor Summary
protected DateTimeSyntax(Date value)
Construct a new date-time attribute with the given java.util.Date value.
Method Summary
boolean | equals(Object object) Returns whether this date-time attribute is equivalent to the passed in object.
Date | getValue() Returns this date-time attribute's java.util.Date value.
int | hashCode() Returns a hash code value for this date-time attribute.
String | toString() Returns a string value corresponding to this date-time attribute.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DateTimeSyntax

protected DateTimeSyntax(Date value)
Construct a new date-time attribute with the given java.util.Date value.

Parameters:
value - java.util.Date value.
Throws:
NullPointerException - (unchecked exception) Thrown if theValue is null.
Method Detail

getValue

public Date getValue()
Returns this date-time attribute's java.util.Date value.

Returns:
the Date.

equals

public boolean equals(Object object)
Returns whether this date-time attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class DateTimeSyntax.
  3. This date-time attribute's java.util.Date value and object's java.util.Date value are equal.

Overrides:
equals in class Object
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this date-time attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns a hash code value for this date-time attribute. The hashcode is that of this attribute's java.util.Date value.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Returns a string value corresponding to this date-time attribute. The string value is just this attribute's java.util.Date value converted to a string.

Overrides:
toString in class Object
Returns:
a string representation of the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocAttributeSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Interface DocAttributeSet

All Superinterfaces:
AttributeSet
All Known Implementing Classes:
HashDocAttributeSet
public interface DocAttributeSet
extends AttributeSet

Interface DocAttributeSet specifies the interface for a set of doc attributes, i.e. printing attributes that implement interface DocAttribute. In the Print Service API, the client uses a DocAttributeSet to specify the characteristics of an individual doc and the print job settings to be applied to an individual doc.

A DocAttributeSet is just an AttributeSet whose constructors and mutating operations guarantee an additional invariant, namely that all attribute values in the DocAttributeSet must be instances of interface DocAttribute. The add(Attribute), and addAll(AttributeSet) operations are respecified below to guarantee this additional invariant.

Method Summary
boolean | add(Attribute attribute) Adds the specified attribute value to this attribute set if it is not already present, first removing any existing value in the same attribute category as the specified attribute value (optional operation).
boolean | addAll(AttributeSet attributes) Adds all of the elements in the specified set to this attribute.
Methods inherited from interface javax.print.attribute.AttributeSet
clear, containsKey, containsValue, equals, get, hashCode, isEmpty, remove, remove, size, toArray

Method Detail

add

boolean add(Attribute attribute)
Adds the specified attribute value to this attribute set if it is not already present, first removing any existing value in the same attribute category as the specified attribute value (optional operation).

Specified by:
add in interface AttributeSet
Parameters:
attribute - Attribute value to be added to this attribute set.
Returns:
true if this attribute set changed as a result of the call, i.e., the given attribute value was not already a member of this attribute set.
Throws:
UnmodifiableSetException - (unchecked exception) Thrown if this attribute set does not support the add() operation.
ClassCastException - (unchecked exception) Thrown if the attribute is not an instance of interface DocAttribute.
NullPointerException - (unchecked exception) Thrown if the attribute is null.

addAll

boolean addAll(AttributeSet attributes)
Adds all of the elements in the specified set to this attribute. The outcome is the same as if the add(Attribute) operation had been applied to this attribute set successively with each element from the specified set. If none of the categories in the specified set are the same as any categories in this attribute set, the addAll() operation effectively modifies this attribute set so that its value is the union of the two sets.

The behavior of the addAll() operation is unspecified if the specified set is modified while the operation is in progress.

If the addAll() operation throws an exception, the effect on this attribute set's state is implementation dependent; elements from the specified set before the point of the exception may or may not have been added to this attribute set.

Specified by:
addAll in interface AttributeSet
Parameters:
attributes - whose elements are to be added to this attribute set.
Returns:
true if this attribute set changed as a result of the call.
Throws:
UnmodifiableSetException - (Unchecked exception) Thrown if this attribute set does not support the addAll() method.
ClassCastException - (Unchecked exception) Thrown if some element in the specified set is not an instance of interface DocAttribute.
NullPointerException - (Unchecked exception) Thrown if the specified set is null.
See Also:
add(Attribute)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EnumSyntax

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Class EnumSyntax

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
Chromaticity, ColorSupported, Compression, Fidelity, Finishings, JobSheets, JobState, JobStateReason, Media, MultipleDocumentHandling, OrientationRequested, PDLOverrideSupported, PresentationDirection, PrinterIsAcceptingJobs, PrinterState, PrinterStateReason, PrintQuality, ReferenceUriSchemesSupported, Severity, SheetCollate, Sides
public abstract class EnumSyntax
extends Object
implements Serializable, Cloneable

Class EnumSyntax is an abstract base class providing the common implementation of all "type safe enumeration" objects. An enumeration class (which extends class EnumSyntax) provides a group of enumeration values (objects) that are singleton instances of the enumeration class; for example:

     public class Bach extends EnumSyntax {
         public static final Bach JOHANN_SEBASTIAN     = new Bach(0);
         public static final Bach WILHELM_FRIEDEMANN   = new Bach(1);
         public static final Bach CARL_PHILIP_EMMANUEL = new Bach(2);
         public static final Bach JOHANN_CHRISTIAN     = new Bach(3);
         public static final Bach P_D_Q                = new Bach(4);

         private static final String[] stringTable = {
             "Johann Sebastian Bach",
              "Wilhelm Friedemann Bach",
              "Carl Philip Emmanuel Bach",
              "Johann Christian Bach",
              "P.D.Q. Bach"
         };

         protected String[] getStringTable() {
             return stringTable;
         }

         private static final Bach[] enumValueTable = {
             JOHANN_SEBASTIAN,
              WILHELM_FRIEDEMANN,
              CARL_PHILIP_EMMANUEL,
              JOHANN_CHRISTIAN,
              P_D_Q
         };

         protected EnumSyntax[] getEnumValueTable() {
             return enumValueTable;
         }
     }
You can then write code that uses the == and != operators to test enumeration values; for example:
     Bach theComposer;
     . . .
     if (theComposer == Bach.JOHANN_SEBASTIAN) {
         System.out.println ("The greatest composer of all time!");
     }
The equals() method for an enumeration class just does a test for identical objects (==).

You can convert an enumeration value to a string by calling toString(). The string is obtained from a table supplied by the enumeration class.

Under the hood, an enumeration value is just an integer, a different integer for each enumeration value within an enumeration class. You can get an enumeration value's integer value by calling getValue(). An enumeration value's integer value is established when it is constructed (see EnumSyntax(int)). Since the constructor is protected, the only possible enumeration values are the singleton objects declared in the enumeration class; additional enumeration values cannot be created at run time.

You can define a subclass of an enumeration class that extends it with additional enumeration values. The subclass's enumeration values' integer values need not be distinct from the superclass's enumeration values' integer values; the ==, !=, equals(), and toString() methods will still work properly even if the subclass uses some of the same integer values as the superclass. However, the application in which the enumeration class and subclass are used may need to have distinct integer values in the superclass and subclass.

See Also:
Serialized Form

Constructor Summary
protected EnumSyntax(int value)
Construct a new enumeration value with the given integer value.
Method Summary
Object | clone() Returns a clone of this enumeration value, which to preserve the semantics of enumeration values is the same object as this enumeration value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for this enumeration value's enumeration class.
protected int | getOffset() Returns the lowest integer value used by this enumeration value's enumeration class.
protected String[] | getStringTable() Returns the string table for this enumeration value's enumeration class.
int | getValue() Returns this enumeration value's integer value.
int | hashCode() Returns a hash code value for this enumeration value.
protected Object | readResolve() During object input, convert this deserialized enumeration instance to the proper enumeration value defined in the enumeration attribute class.
String | toString() Returns a string value corresponding to this enumeration value.
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

EnumSyntax

protected EnumSyntax(int value)
Construct a new enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getValue

public int getValue()
Returns this enumeration value's integer value.

Returns:
the value

clone

public Object clone()
Returns a clone of this enumeration value, which to preserve the semantics of enumeration values is the same object as this enumeration value.

Overrides:
clone in class Object
Returns:
a clone of this instance.
See Also:
Cloneable

hashCode

public int hashCode()
Returns a hash code value for this enumeration value. The hash code is just this enumeration value's integer value.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Returns a string value corresponding to this enumeration value.

Overrides:
toString in class Object
Returns:
a string representation of the object.

readResolve

protected Object readResolve()
                      throws ObjectStreamException
During object input, convert this deserialized enumeration instance to the proper enumeration value defined in the enumeration attribute class.

Returns:
The enumeration singleton value stored at index i-L in the enumeration value table returned by getEnumValueTable(), where i is this enumeration value's integer value and L is the value returned by getOffset().
Throws:
ObjectStreamException - if the stream can't be deserialised
InvalidObjectException - Thrown if the enumeration value table is null, this enumeration value's integer value does not correspond to an element in the enumeration value table, or the corresponding element in the enumeration value table is null. (Note: InvalidObjectException is a subclass of ObjectStreamException, which readResolve() is declared to throw.)

getStringTable

protected String[] getStringTable()
Returns the string table for this enumeration value's enumeration class. The enumeration class's integer values are assumed to lie in the range L..L+N-1, where L is the value returned by getOffset() and N is the length of the string table. The element in the string table at index i-L is the value returned by toString() for the enumeration value whose integer value is i. If an integer within the above range is not used by any enumeration value, leave the corresponding table element null.

The default implementation returns null. If the enumeration class (a subclass of class EnumSyntax) does not override this method to return a non-null string table, and the subclass does not override the toString() method, the base class toString() method will return just a string representation of this enumeration value's integer value.

Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for this enumeration value's enumeration class. The enumeration class's integer values are assumed to lie in the range L..L+N-1, where L is the value returned by getOffset() and N is the length of the enumeration value table. The element in the enumeration value table at index i-L is the enumeration value object whose integer value is i; the readResolve() method needs this to preserve singleton semantics during deserialization of an enumeration instance. If an integer within the above range is not used by any enumeration value, leave the corresponding table element null.

The default implementation returns null. If the enumeration class (a subclass of class EnumSyntax) does not override this method to return a non-null enumeration value table, and the subclass does not override the readResolve() method, the base class readResolve() method will throw an exception whenever an enumeration instance is deserialized from an object input stream.

Returns:
the value table

getOffset

protected int getOffset()
Returns the lowest integer value used by this enumeration value's enumeration class.

The default implementation returns 0. If the enumeration class (a subclass of class EnumSyntax) uses integer values starting at other than 0, override this method in the subclass.

Returns:
the offset of the lowest enumeration value.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HashAttributeSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Class HashAttributeSet

java.lang.Object
    extended by  javax.print.attribute.HashAttributeSet
All Implemented Interfaces:
Serializable, AttributeSet
Direct Known Subclasses:
HashDocAttributeSet, HashPrintJobAttributeSet, HashPrintRequestAttributeSet, HashPrintServiceAttributeSet
public class HashAttributeSet
extends Object
implements AttributeSet, Serializable

Class HashAttributeSet provides an AttributeSet implementation with characteristics of a hash map.

See Also:
Serialized Form

Constructor Summary
 | HashAttributeSet() Construct a new, empty attribute set.
 | HashAttributeSet(Attribute attribute) Construct a new attribute set, initially populated with the given attribute.
 | HashAttributeSet(Attribute[] attributes) Construct a new attribute set, initially populated with the values from the given array.
protected | HashAttributeSet(Attribute[] attributes, Class<?> interfaceName) Construct a new attribute set, where the members of the attribute set are restricted to the given interface.
protected | HashAttributeSet(Attribute attribute, Class<?> interfaceName) Construct a new attribute set, initially populated with the given attribute, where the members of the attribute set are restricted to the given interface.
 | HashAttributeSet(AttributeSet attributes) Construct a new attribute set, initially populated with the values from the given set.
protected | HashAttributeSet(AttributeSet attributes, Class<?> interfaceName) Construct a new attribute set, initially populated with the values from the given set where the members of the attribute set are restricted to the given interface.
protected | HashAttributeSet(Class<?> interfaceName) Construct a new, empty attribute set, where the members of the attribute set are restricted to the given interface.
Method Summary
boolean | add(Attribute attribute) Adds the specified attribute to this attribute set if it is not already present, first removing any existing in the same attribute category as the specified attribute value.
boolean | addAll(AttributeSet attributes) Adds all of the elements in the specified set to this attribute.
void | clear() Removes all attributes from this attribute set.
boolean | containsKey(Class<?> category) Returns true if this attribute set contains an attribute for the specified category.
boolean | containsValue(Attribute attribute) Returns true if this attribute set contains the given attribute.
boolean | equals(Object object) Compares the specified object with this attribute set for equality.
Attribute | get(Class<?> category) Returns the attribute value which this attribute set contains in the given attribute category.
int | hashCode() Returns the hash code value for this attribute set.
boolean | isEmpty() Returns true if this attribute set contains no attributes.
boolean | remove(Attribute attribute) Removes the specified attribute from this attribute set if present.
boolean | remove(Class<?> category) Removes any attribute for this category from this attribute set if present.
int | size() Returns the number of attributes in this attribute set.
Attribute[] | toArray() Returns an array of the attributes contained in this set.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HashAttributeSet

public HashAttributeSet()
Construct a new, empty attribute set.

HashAttributeSet

public HashAttributeSet(Attribute attribute)
Construct a new attribute set, initially populated with the given attribute.

Parameters:
attribute - Attribute value to add to the set.
Throws:
NullPointerException - (unchecked exception) Thrown if attribute is null.

HashAttributeSet

public HashAttributeSet(Attribute[] attributes)
Construct a new attribute set, initially populated with the values from the given array. The new attribute set is populated by adding the elements of attributes array to the set in sequence, starting at index 0. Thus, later array elements may replace earlier array elements if the array contains duplicate attribute values or attribute categories.

Parameters:
attributes - Array of attribute values to add to the set. If null, an empty attribute set is constructed.
Throws:
NullPointerException - (unchecked exception) Thrown if any element of attributes is null.

HashAttributeSet

public HashAttributeSet(AttributeSet attributes)
Construct a new attribute set, initially populated with the values from the given set.

Parameters:
attributes - Set of attributes from which to initialise this set. If null, an empty attribute set is constructed.

HashAttributeSet

protected HashAttributeSet(Class<?> interfaceName)
Construct a new, empty attribute set, where the members of the attribute set are restricted to the given interface.

Parameters:
interfaceName - The interface of which all members of this attribute set must be an instance. It is assumed to be interface Attribute or a subinterface thereof.
Throws:
NullPointerException - if interfaceName is null.

HashAttributeSet

protected HashAttributeSet(Attribute attribute,
                           Class<?> interfaceName)
Construct a new attribute set, initially populated with the given attribute, where the members of the attribute set are restricted to the given interface.

Parameters:
attribute - Attribute value to add to the set.
interfaceName - The interface of which all members of this attribute set must be an instance. It is assumed to be interface Attribute or a subinterface thereof.
Throws:
NullPointerException - (unchecked exception) Thrown if attribute is null.
NullPointerException - if interfaceName is null.
ClassCastException - (unchecked exception) Thrown if attribute is not an instance of interfaceName.

HashAttributeSet

protected HashAttributeSet(Attribute[] attributes,
                           Class<?> interfaceName)
Construct a new attribute set, where the members of the attribute set are restricted to the given interface. The new attribute set is populated by adding the elements of attributes array to the set in sequence, starting at index 0. Thus, later array elements may replace earlier array elements if the array contains duplicate attribute values or attribute categories.

Parameters:
attributes - Array of attribute values to add to the set. If null, an empty attribute set is constructed.
interfaceName - The interface of which all members of this attribute set must be an instance. It is assumed to be interface Attribute or a subinterface thereof.
Throws:
NullPointerException - (unchecked exception) Thrown if any element of attributes is null.
NullPointerException - if interfaceName is null.
ClassCastException - (unchecked exception) Thrown if any element of attributes is not an instance of interfaceName.

HashAttributeSet

protected HashAttributeSet(AttributeSet attributes,
                           Class<?> interfaceName)
Construct a new attribute set, initially populated with the values from the given set where the members of the attribute set are restricted to the given interface.

Parameters:
attributes - set of attribute values to initialise the set. If null, an empty attribute set is constructed.
interfaceName - The interface of which all members of this attribute set must be an instance. It is assumed to be interface Attribute or a subinterface thereof.
Throws:
ClassCastException - (unchecked exception) Thrown if any element of attributes is not an instance of interfaceName.
Method Detail

get

public Attribute get(Class<?> category)
Returns the attribute value which this attribute set contains in the given attribute category. Returns null if this attribute set does not contain any attribute value in the given attribute category.

Specified by:
get in interface AttributeSet
Parameters:
category - Attribute category whose associated attribute value is to be returned. It must be a Class that implements interface Attribute.
Returns:
The attribute value in the given attribute category contained in this attribute set, or null if this attribute set does not contain any attribute value in the given attribute category.
Throws:
NullPointerException - (unchecked exception) Thrown if the category is null.
ClassCastException - (unchecked exception) Thrown if the category is not a Class that implements interface Attribute.

add

public boolean add(Attribute attribute)
Adds the specified attribute to this attribute set if it is not already present, first removing any existing in the same attribute category as the specified attribute value.

Specified by:
add in interface AttributeSet
Parameters:
attribute - Attribute value to be added to this attribute set.
Returns:
true if this attribute set changed as a result of the call, i.e., the given attribute value was not already a member of this attribute set.
Throws:
NullPointerException - (unchecked exception) Thrown if the attribute is null.
UnmodifiableSetException - (unchecked exception) Thrown if this attribute set does not support the add() operation.

remove

public boolean remove(Class<?> category)
Removes any attribute for this category from this attribute set if present. If category is null, then remove() does nothing and returns false.

Specified by:
remove in interface AttributeSet
Parameters:
category - Attribute category to be removed from this attribute set.
Returns:
true if this attribute set changed as a result of the call, i.e., the given attribute category had been a member of this attribute set.
Throws:
UnmodifiableSetException - (unchecked exception) Thrown if this attribute set does not support the remove() operation.

remove

public boolean remove(Attribute attribute)
Removes the specified attribute from this attribute set if present. If attribute is null, then remove() does nothing and returns false.

Specified by:
remove in interface AttributeSet
Parameters:
attribute - Attribute value to be removed from this attribute set.
Returns:
true if this attribute set changed as a result of the call, i.e., the given attribute value had been a member of this attribute set.
Throws:
UnmodifiableSetException - (unchecked exception) Thrown if this attribute set does not support the remove() operation.

containsKey

public boolean containsKey(Class<?> category)
Returns true if this attribute set contains an attribute for the specified category.

Specified by:
containsKey in interface AttributeSet
Parameters:
category - whose presence in this attribute set is to be tested.
Returns:
true if this attribute set contains an attribute value for the specified category.

containsValue

public boolean containsValue(Attribute attribute)
Returns true if this attribute set contains the given attribute.

Specified by:
containsValue in interface AttributeSet
Parameters:
attribute - value whose presence in this attribute set is to be tested.
Returns:
true if this attribute set contains the given attribute value.

addAll

public boolean addAll(AttributeSet attributes)
Adds all of the elements in the specified set to this attribute. The outcome is the same as if the add(Attribute) operation had been applied to this attribute set successively with each element from the specified set. The behavior of the addAll(AttributeSet) operation is unspecified if the specified set is modified while the operation is in progress.

If the addAll(AttributeSet) operation throws an exception, the effect on this attribute set's state is implementation dependent; elements from the specified set before the point of the exception may or may not have been added to this attribute set.

Specified by:
addAll in interface AttributeSet
Parameters:
attributes - whose elements are to be added to this attribute set.
Returns:
true if this attribute set changed as a result of the call.
Throws:
UnmodifiableSetException - (Unchecked exception) Thrown if this attribute set does not support the addAll(AttributeSet) method.
NullPointerException - (Unchecked exception) Thrown if some element in the specified set is null, or the set is null.
See Also:
add(Attribute)

size

public int size()
Returns the number of attributes in this attribute set. If this attribute set contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Specified by:
size in interface AttributeSet
Returns:
The number of attributes in this attribute set.

toArray

public Attribute[] toArray()
Description copied from interface: AttributeSet
Returns an array of the attributes contained in this set.

Specified by:
toArray in interface AttributeSet
Returns:
the Attributes contained in this set as an array, zero length if the AttributeSet is empty.

clear

public void clear()
Removes all attributes from this attribute set.

Specified by:
clear in interface AttributeSet
Throws:
UnmodifiableSetException - (unchecked exception) Thrown if this attribute set does not support the clear() operation.

isEmpty

public boolean isEmpty()
Returns true if this attribute set contains no attributes.

Specified by:
isEmpty in interface AttributeSet
Returns:
true if this attribute set contains no attributes.

equals

public boolean equals(Object object)
Compares the specified object with this attribute set for equality. Returns true if the given object is also an attribute set and the two attribute sets contain the same attribute category-attribute value mappings. This ensures that the equals() method works properly across different implementations of the AttributeSet interface.

Specified by:
equals in interface AttributeSet
Overrides:
equals in class Object
Parameters:
object - to be compared for equality with this attribute set.
Returns:
true if the specified object is equal to this attribute set.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns the hash code value for this attribute set. The hash code of an attribute set is defined to be the sum of the hash codes of each entry in the AttributeSet. This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two attribute sets t1 and t2, as required by the general contract of Object.hashCode().

Specified by:
hashCode in interface AttributeSet
Overrides:
hashCode in class Object
Returns:
The hash code value for this attribute set.
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HashDocAttributeSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Class HashDocAttributeSet

java.lang.Object
    extended by  javax.print.attribute.HashAttributeSet
        extended by  javax.print.attribute.HashDocAttributeSet
All Implemented Interfaces:
Serializable, AttributeSet, DocAttributeSet
public class HashDocAttributeSet
extends HashAttributeSet
implements DocAttributeSet, Serializable

Class HashDocAttributeSet provides an attribute set which inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface DocAttributeSet.

See Also:
Serialized Form

Constructor Summary
HashDocAttributeSet()
Construct a new, empty hash doc attribute set.
HashDocAttributeSet(DocAttribute attribute)
Construct a new hash doc attribute set, initially populated with the given value.
HashDocAttributeSet(DocAttribute[] attributes)
Construct a new hash doc attribute set, initially populated with the values from the given array.
HashDocAttributeSet(DocAttributeSet attributes)
Construct a new attribute set, initially populated with the values from the given set where the members of the attribute set are restricted to the DocAttribute interface.
Method Summary
Methods inherited from class javax.print.attribute.HashAttributeSet
add, addAll, clear, containsKey, containsValue, equals, get, hashCode, isEmpty, remove, remove, size, toArray
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.print.attribute.DocAttributeSet
add, addAll
Methods inherited from interface javax.print.attribute.AttributeSet
clear, containsKey, containsValue, equals, get, hashCode, isEmpty, remove, remove, size, toArray

Constructor Detail

HashDocAttributeSet

public HashDocAttributeSet()
Construct a new, empty hash doc attribute set.

HashDocAttributeSet

public HashDocAttributeSet(DocAttribute attribute)
Construct a new hash doc attribute set, initially populated with the given value.

Parameters:
attribute - Attribute value to add to the set.
Throws:
NullPointerException - (unchecked exception) Thrown if attribute is null.

HashDocAttributeSet

public HashDocAttributeSet(DocAttribute[] attributes)
Construct a new hash doc attribute set, initially populated with the values from the given array. The new attribute set is populated by adding the elements of attributes array to the set in sequence, starting at index 0. Thus, later array elements may replace earlier array elements if the array contains duplicate attribute values or attribute categories.

Parameters:
attributes - Array of attribute values to add to the set. If null, an empty attribute set is constructed.
Throws:
NullPointerException - (unchecked exception) Thrown if any element of attributes is null.

HashDocAttributeSet

public HashDocAttributeSet(DocAttributeSet attributes)
Construct a new attribute set, initially populated with the values from the given set where the members of the attribute set are restricted to the DocAttribute interface.

Parameters:
attributes - set of attribute values to initialise the set. If null, an empty attribute set is constructed.
Throws:
ClassCastException - (unchecked exception) Thrown if any element of attributes is not an instance of DocAttribute.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HashPrintJobAttributeSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Class HashPrintJobAttributeSet

java.lang.Object
    extended by  javax.print.attribute.HashAttributeSet
        extended by  javax.print.attribute.HashPrintJobAttributeSet
All Implemented Interfaces:
Serializable, AttributeSet, PrintJobAttributeSet
public class HashPrintJobAttributeSet
extends HashAttributeSet
implements PrintJobAttributeSet, Serializable

Class HashPrintJobAttributeSet provides an attribute set which inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface PrintJobAttributeSet.

See Also:
Serialized Form

Constructor Summary
HashPrintJobAttributeSet()
Construct a new, empty hash print job attribute set.
HashPrintJobAttributeSet(PrintJobAttribute attribute)
Construct a new hash print job attribute set, initially populated with the given value.
HashPrintJobAttributeSet(PrintJobAttribute[] attributes)
Construct a new hash print job attribute set, initially populated with the values from the given array.
HashPrintJobAttributeSet(PrintJobAttributeSet attributes)
Construct a new attribute set, initially populated with the values from the given set where the members of the attribute set are restricted to the PrintJobAttribute interface.
Method Summary
Methods inherited from class javax.print.attribute.HashAttributeSet
add, addAll, clear, containsKey, containsValue, equals, get, hashCode, isEmpty, remove, remove, size, toArray
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.print.attribute.PrintJobAttributeSet
add, addAll
Methods inherited from interface javax.print.attribute.AttributeSet
clear, containsKey, containsValue, equals, get, hashCode, isEmpty, remove, remove, size, toArray

Constructor Detail

HashPrintJobAttributeSet

public HashPrintJobAttributeSet()
Construct a new, empty hash print job attribute set.

HashPrintJobAttributeSet

public HashPrintJobAttributeSet(PrintJobAttribute attribute)
Construct a new hash print job attribute set, initially populated with the given value.

Parameters:
attribute - Attribute value to add to the set.
Throws:
NullPointerException - (unchecked exception) Thrown if attribute is null.

HashPrintJobAttributeSet

public HashPrintJobAttributeSet(PrintJobAttribute[] attributes)
Construct a new hash print job attribute set, initially populated with the values from the given array. The new attribute set is populated by adding the elements of attributes array to the set in sequence, starting at index 0. Thus, later array elements may replace earlier array elements if the array contains duplicate attribute values or attribute categories.

Parameters:
attributes - Array of attribute values to add to the set. If null, an empty attribute set is constructed.
Throws:
NullPointerException - (unchecked exception) Thrown if any element of attributes is null.

HashPrintJobAttributeSet

public HashPrintJobAttributeSet(PrintJobAttributeSet attributes)
Construct a new attribute set, initially populated with the values from the given set where the members of the attribute set are restricted to the PrintJobAttribute interface.

Parameters:
attributes - set of attribute values to initialise the set. If null, an empty attribute set is constructed.
Throws:
ClassCastException - (unchecked exception) Thrown if any element of attributes is not an instance of PrintJobAttribute.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HashPrintRequestAttributeSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Class HashPrintRequestAttributeSet

java.lang.Object
    extended by  javax.print.attribute.HashAttributeSet
        extended by  javax.print.attribute.HashPrintRequestAttributeSet
All Implemented Interfaces:
Serializable, AttributeSet, PrintRequestAttributeSet
public class HashPrintRequestAttributeSet
extends HashAttributeSet
implements PrintRequestAttributeSet, Serializable

Class HashPrintRequestAttributeSet inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface PrintRequestAttributeSet.

See Also:
Serialized Form

Constructor Summary
HashPrintRequestAttributeSet()
Construct a new, empty print request attribute set.
HashPrintRequestAttributeSet(PrintRequestAttribute attribute)
Construct a new print request attribute set, initially populated with the given value.
HashPrintRequestAttributeSet(PrintRequestAttribute[] attributes)
Construct a new print request attribute set, initially populated with the values from the given array.
HashPrintRequestAttributeSet(PrintRequestAttributeSet attributes)
Construct a new attribute set, initially populated with the values from the given set where the members of the attribute set are restricted to the (PrintRequestAttributeSe interface.
Method Summary
Methods inherited from class javax.print.attribute.HashAttributeSet
add, addAll, clear, containsKey, containsValue, equals, get, hashCode, isEmpty, remove, remove, size, toArray
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.print.attribute.PrintRequestAttributeSet
add, addAll
Methods inherited from interface javax.print.attribute.AttributeSet
clear, containsKey, containsValue, equals, get, hashCode, isEmpty, remove, remove, size, toArray

Constructor Detail

HashPrintRequestAttributeSet

public HashPrintRequestAttributeSet()
Construct a new, empty print request attribute set.

HashPrintRequestAttributeSet

public HashPrintRequestAttributeSet(PrintRequestAttribute attribute)
Construct a new print request attribute set, initially populated with the given value.

Parameters:
attribute - Attribute value to add to the set.
Throws:
NullPointerException - (unchecked exception) Thrown if attribute is null.

HashPrintRequestAttributeSet

public HashPrintRequestAttributeSet(PrintRequestAttribute[] attributes)
Construct a new print request attribute set, initially populated with the values from the given array. The new attribute set is populated by adding the elements of attributes array to the set in sequence, starting at index 0. Thus, later array elements may replace earlier array elements if the array contains duplicate attribute values or attribute categories.

Parameters:
attributes - Array of attribute values to add to the set. If null, an empty attribute set is constructed.
Throws:
NullPointerException - (unchecked exception) Thrown if any element of attributes is null.

HashPrintRequestAttributeSet

public HashPrintRequestAttributeSet(PrintRequestAttributeSet attributes)
Construct a new attribute set, initially populated with the values from the given set where the members of the attribute set are restricted to the (PrintRequestAttributeSe interface.

Parameters:
attributes - set of attribute values to initialise the set. If null, an empty attribute set is constructed.
Throws:
ClassCastException - (unchecked exception) Thrown if any element of attributes is not an instance of (PrintRequestAttributeSe.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HashPrintServiceAttributeSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Class HashPrintServiceAttributeSet

java.lang.Object
    extended by  javax.print.attribute.HashAttributeSet
        extended by  javax.print.attribute.HashPrintServiceAttributeSet
All Implemented Interfaces:
Serializable, AttributeSet, PrintServiceAttributeSet
public class HashPrintServiceAttributeSet
extends HashAttributeSet
implements PrintServiceAttributeSet, Serializable

Class HashPrintServiceAttributeSet provides an attribute set which inherits its implementation from class HashAttributeSet and enforces the semantic restrictions of interface PrintServiceAttributeSet.

See Also:
Serialized Form

Constructor Summary
HashPrintServiceAttributeSet()
Construct a new, empty hash print service attribute set.
HashPrintServiceAttributeSet(PrintServiceAttribute attribute)
Construct a new hash print service attribute set, initially populated with the given value.
HashPrintServiceAttributeSet(PrintServiceAttribute[] attributes)
Construct a new print service attribute set, initially populated with the values from the given array.
HashPrintServiceAttributeSet(PrintServiceAttributeSet attributes)
Construct a new attribute set, initially populated with the values from the given set where the members of the attribute set are restricted to the PrintServiceAttribute interface.
Method Summary
Methods inherited from class javax.print.attribute.HashAttributeSet
add, addAll, clear, containsKey, containsValue, equals, get, hashCode, isEmpty, remove, remove, size, toArray
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.print.attribute.PrintServiceAttributeSet
add, addAll
Methods inherited from interface javax.print.attribute.AttributeSet
clear, containsKey, containsValue, equals, get, hashCode, isEmpty, remove, remove, size, toArray

Constructor Detail

HashPrintServiceAttributeSet

public HashPrintServiceAttributeSet()
Construct a new, empty hash print service attribute set.

HashPrintServiceAttributeSet

public HashPrintServiceAttributeSet(PrintServiceAttribute attribute)
Construct a new hash print service attribute set, initially populated with the given value.

Parameters:
attribute - Attribute value to add to the set.
Throws:
NullPointerException - (unchecked exception) Thrown if attribute is null.

HashPrintServiceAttributeSet

public HashPrintServiceAttributeSet(PrintServiceAttribute[] attributes)
Construct a new print service attribute set, initially populated with the values from the given array. The new attribute set is populated by adding the elements of attributes array to the set in sequence, starting at index 0. Thus, later array elements may replace earlier array elements if the array contains duplicate attribute values or attribute categories.

Parameters:
attributes - Array of attribute values to add to the set. If null, an empty attribute set is constructed.
Throws:
NullPointerException - (unchecked exception) Thrown if any element of attributes is null.

HashPrintServiceAttributeSet

public HashPrintServiceAttributeSet(PrintServiceAttributeSet attributes)
Construct a new attribute set, initially populated with the values from the given set where the members of the attribute set are restricted to the PrintServiceAttribute interface.

Parameters:
attributes - set of attribute values to initialise the set. If null, an empty attribute set is constructed.
Throws:
ClassCastException - (unchecked exception) Thrown if any element of attributes is not an instance of PrintServiceAttribute.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IntegerSyntax

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Class IntegerSyntax

java.lang.Object
    extended by  javax.print.attribute.IntegerSyntax
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
Copies, JobImpressions, JobImpressionsCompleted, JobKOctets, JobKOctetsProcessed, JobMediaSheets, JobMediaSheetsCompleted, JobPriority, JobPrioritySupported, NumberOfDocuments, NumberOfInterveningJobs, NumberUp, PagesPerMinute, PagesPerMinuteColor, QueuedJobCount
public abstract class IntegerSyntax
extends Object
implements Serializable, Cloneable

Class IntegerSyntax is an abstract base class providing the common implementation of all attributes with integer values.

Under the hood, an integer attribute is just an integer. You can get an integer attribute's integer value by calling getValue(). An integer attribute's integer value is established when it is constructed (see IntegerSyntax(int)). Once constructed, an integer attribute's value is immutable.

See Also:
Serialized Form

Constructor Summary
protected | IntegerSyntax(int value) Construct a new integer attribute with the given integer value.
protected | IntegerSyntax(int value, int lowerBound, int upperBound) Construct a new integer attribute with the given integer value, which must lie within the given range.
Method Summary
boolean | equals(Object object) Returns whether this integer attribute is equivalent to the passed in object.
int | getValue() Returns this integer attribute's integer value.
int | hashCode() Returns a hash code value for this integer attribute.
String | toString() Returns a string value corresponding to this integer attribute.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

IntegerSyntax

protected IntegerSyntax(int value)
Construct a new integer attribute with the given integer value.

Parameters:
value - Integer value.

IntegerSyntax

protected IntegerSyntax(int value,
                        int lowerBound,
                        int upperBound)
Construct a new integer attribute with the given integer value, which must lie within the given range.

Parameters:
value - Integer value.
lowerBound - Lower bound.
upperBound - Upper bound.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if value is less than lowerBound or greater than upperBound.
Method Detail

getValue

public int getValue()
Returns this integer attribute's integer value.

Returns:
the integer value

equals

public boolean equals(Object object)
Returns whether this integer attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class IntegerSyntax.
  3. This integer attribute's value and object's value are equal.

Overrides:
equals in class Object
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this integer attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns a hash code value for this integer attribute. The hash code is just this integer attribute's integer value.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Returns a string value corresponding to this integer attribute. The string value is just this integer attribute's integer value converted to a string.

Overrides:
toString in class Object
Returns:
a string representation of the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrintJobAttributeSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Interface PrintJobAttributeSet

All Superinterfaces:
AttributeSet
All Known Implementing Classes:
HashPrintJobAttributeSet
public interface PrintJobAttributeSet
extends AttributeSet

Interface PrintJobAttributeSet specifies the interface for a set of print job attributes, i.e. printing attributes that implement interface PrintJobAttribute. In the Print Service API, a service uses a PrintJobAttributeSet to report the status of a print job.

A PrintJobAttributeSet is just an AttributeSet whose constructors and mutating operations guarantee an additional invariant, namely that all attribute values in the PrintJobAttributeSet must be instances of interface PrintJobAttribute. The add(Attribute), and addAll(AttributeSet) operations are respecified below to guarantee this additional invariant.

Method Summary
boolean | add(Attribute attribute) Adds the specified attribute value to this attribute set if it is not already present, first removing any existing value in the same attribute category as the specified attribute value (optional operation).
boolean | addAll(AttributeSet attributes) Adds all of the elements in the specified set to this attribute.
Methods inherited from interface javax.print.attribute.AttributeSet
clear, containsKey, containsValue, equals, get, hashCode, isEmpty, remove, remove, size, toArray

Method Detail

add

boolean add(Attribute attribute)
Adds the specified attribute value to this attribute set if it is not already present, first removing any existing value in the same attribute category as the specified attribute value (optional operation).

Specified by:
add in interface AttributeSet
Parameters:
attribute - Attribute value to be added to this attribute set.
Returns:
true if this attribute set changed as a result of the call, i.e., the given attribute value was not already a member of this attribute set.
Throws:
UnmodifiableSetException - (unchecked exception) Thrown if this attribute set does not support the add() operation.
ClassCastException - (unchecked exception) Thrown if the attribute is not an instance of interface PrintJobAttribute.
NullPointerException - (unchecked exception) Thrown if the attribute is null.

addAll

boolean addAll(AttributeSet attributes)
Adds all of the elements in the specified set to this attribute. The outcome is the same as if the add(Attribute) operation had been applied to this attribute set successively with each element from the specified set. If none of the categories in the specified set are the same as any categories in this attribute set, the addAll() operation effectively modifies this attribute set so that its value is the union of the two sets.

The behavior of the addAll() operation is unspecified if the specified set is modified while the operation is in progress.

If the addAll() operation throws an exception, the effect on this attribute set's state is implementation dependent; elements from the specified set before the point of the exception may or may not have been added to this attribute set.

Specified by:
addAll in interface AttributeSet
Parameters:
attributes - whose elements are to be added to this attribute set.
Returns:
true if this attribute set changed as a result of the call.
Throws:
UnmodifiableSetException - (Unchecked exception) Thrown if this attribute set does not support the addAll() method.
ClassCastException - (Unchecked exception) Thrown if some element in the specified set is not an instance of interface PrintJobAttribute.
NullPointerException - (Unchecked exception) Thrown if the specified set is null.
See Also:
add(Attribute)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrintRequestAttributeSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Interface PrintRequestAttributeSet

All Superinterfaces:
AttributeSet
All Known Implementing Classes:
HashPrintRequestAttributeSet
public interface PrintRequestAttributeSet
extends AttributeSet

Interface PrintRequestAttributeSet specifies the interface for a set of print request attributes, i.e. printing attributes that implement interface PrintRequestAttribute. The client uses a PrintRequestAttributeSet to specify the settings to be applied to a whole print job and to all the docs in the print job.

PrintRequestAttributeSet is just an AttributeSet whose constructors and mutating operations guarantee an additional invariant, namely that all attribute values in the PrintRequestAttributeSet must be instances of interface PrintRequestAttribute. The add(Attribute), and addAll(AttributeSet) operations are respecified below to guarantee this additional invariant.

Method Summary
boolean | add(Attribute attribute) Adds the specified attribute value to this attribute set if it is not already present, first removing any existing value in the same attribute category as the specified attribute value (optional operation).
boolean | addAll(AttributeSet attributes) Adds all of the elements in the specified set to this attribute.
Methods inherited from interface javax.print.attribute.AttributeSet
clear, containsKey, containsValue, equals, get, hashCode, isEmpty, remove, remove, size, toArray

Method Detail

add

boolean add(Attribute attribute)
Adds the specified attribute value to this attribute set if it is not already present, first removing any existing value in the same attribute category as the specified attribute value (optional operation).

Specified by:
add in interface AttributeSet
Parameters:
attribute - Attribute value to be added to this attribute set.
Returns:
true if this attribute set changed as a result of the call, i.e., the given attribute value was not already a member of this attribute set.
Throws:
UnmodifiableSetException - (unchecked exception) Thrown if this attribute set does not support the add() operation.
ClassCastException - (unchecked exception) Thrown if the attribute is not an instance of interface PrintRequestAttribute.
NullPointerException - (unchecked exception) Thrown if the attribute is null.

addAll

boolean addAll(AttributeSet attributes)
Adds all of the elements in the specified set to this attribute. The outcome is the same as if the add(Attribute) operation had been applied to this attribute set successively with each element from the specified set. If none of the categories in the specified set are the same as any categories in this attribute set, the addAll() operation effectively modifies this attribute set so that its value is the union of the two sets.

The behavior of the addAll() operation is unspecified if the specified set is modified while the operation is in progress.

If the addAll() operation throws an exception, the effect on this attribute set's state is implementation dependent; elements from the specified set before the point of the exception may or may not have been added to this attribute set.

Specified by:
addAll in interface AttributeSet
Parameters:
attributes - whose elements are to be added to this attribute set.
Returns:
true if this attribute set changed as a result of the call.
Throws:
UnmodifiableSetException - (Unchecked exception) Thrown if this attribute set does not support the addAll() method.
ClassCastException - (Unchecked exception) Thrown if some element in the specified set is not an instance of interface PrintRequestAttribute.
NullPointerException - (Unchecked exception) Thrown if the specified set is null.
See Also:
add(Attribute)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrintServiceAttributeSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Interface PrintServiceAttributeSet

All Superinterfaces:
AttributeSet
All Known Implementing Classes:
HashPrintServiceAttributeSet
public interface PrintServiceAttributeSet
extends AttributeSet

Interface PrintServiceAttributeSet specifies the interface for a set of print job attributes, i.e. printing attributes that implement interface PrintServiceAttribute. In the Print Service API, the Print Service instance uses a PrintServiceAttributeSet to report the status of the print service.

A PrintServiceAttributeSet is just an AttributeSet whose constructors and mutating operations guarantee an additional invariant, namely that all attribute values in the PrintServiceAttributeSet must be instances of interface PrintServiceAttribute. The add(Attribute), and addAll(AttributeSet) operations are respecified below to guarantee this additional invariant.

Method Summary
boolean | add(Attribute attribute) Adds the specified attribute value to this attribute set if it is not already present, first removing any existing value in the same attribute category as the specified attribute value (optional operation).
boolean | addAll(AttributeSet attributes) Adds all of the elements in the specified set to this attribute.
Methods inherited from interface javax.print.attribute.AttributeSet
clear, containsKey, containsValue, equals, get, hashCode, isEmpty, remove, remove, size, toArray

Method Detail

add

boolean add(Attribute attribute)
Adds the specified attribute value to this attribute set if it is not already present, first removing any existing value in the same attribute category as the specified attribute value (optional operation).

Specified by:
add in interface AttributeSet
Parameters:
attribute - Attribute value to be added to this attribute set.
Returns:
true if this attribute set changed as a result of the call, i.e., the given attribute value was not already a member of this attribute set.
Throws:
UnmodifiableSetException - (unchecked exception) Thrown if this attribute set does not support the add() operation.
ClassCastException - (unchecked exception) Thrown if the attribute is not an instance of interface PrintServiceAttribute.
NullPointerException - (unchecked exception) Thrown if the attribute is null.

addAll

boolean addAll(AttributeSet attributes)
Adds all of the elements in the specified set to this attribute. The outcome is the same as if the add(Attribute) operation had been applied to this attribute set successively with each element from the specified set. If none of the categories in the specified set are the same as any categories in this attribute set, the addAll() operation effectively modifies this attribute set so that its value is the union of the two sets.

The behavior of the addAll() operation is unspecified if the specified set is modified while the operation is in progress.

If the addAll() operation throws an exception, the effect on this attribute set's state is implementation dependent; elements from the specified set before the point of the exception may or may not have been added to this attribute set.

Specified by:
addAll in interface AttributeSet
Parameters:
attributes - whose elements are to be added to this attribute set.
Returns:
true if this attribute set changed as a result of the call.
Throws:
UnmodifiableSetException - (Unchecked exception) Thrown if this attribute set does not support the addAll() method.
ClassCastException - (Unchecked exception) Thrown if some element in the specified set is not an instance of interface PrintServiceAttribute.
NullPointerException - (Unchecked exception) Thrown if the specified set is null.
See Also:
add(Attribute)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ResolutionSyntax

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Class ResolutionSyntax

java.lang.Object
    extended by  javax.print.attribute.ResolutionSyntax
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
PrinterResolution
public abstract class ResolutionSyntax
extends Object
implements Serializable, Cloneable

Class ResolutionSyntax is an abstract base class providing the common implementation of all attributes denoting a printer resolution.

A resolution attribute's value consists of two items, the cross feed direction resolution and the feed direction resolution. A resolution attribute may be constructed by supplying the two values and indicating the units in which the values are measured. Methods are provided to return a resolution attribute's values, indicating the units in which the values are to be returned. The two most common resolution units are dots per inch (dpi) and dots per centimeter (dpcm), and exported constants DPI and DPCM are provided for indicating those units.

Once constructed, a resolution attribute's value is immutable.

Design

A resolution attribute's cross feed direction resolution and feed direction resolution values are stored internally using units of dots per 100 inches (dphi). Storing the values in dphi rather than, say, metric units allows precise integer arithmetic conversions between dpi and dphi and between dpcm and dphi: 1 dpi = 100 dphi, 1 dpcm = 254 dphi. Thus, the values can be stored into and retrieved back from a resolution attribute in either units with no loss of precision. This would not be guaranteed if a floating point representation were used. However, roundoff error will in general occur if a resolution attribute's values are created in one units and retrieved in different units; for example, 600 dpi will be rounded to 236 dpcm, whereas the true value (to five figures) is 236.22 dpcm.

Storing the values internally in common units of dphi lets two resolution attributes be compared without regard to the units in which they were created; for example, 300 dpcm will compare equal to 762 dpi, as they both are stored as 76200 dphi. In particular, a lookup service can match resolution attributes based on equality of their serialized representations regardless of the units in which they were created. Again, using integers for internal storage allows precise equality comparisons to be done, which would not be guaranteed if a floating point representation were used.

The exported constant DPI is actually the conversion factor by which to multiply a value in dpi to get the value in dphi. Likewise, the exported constant DPCM is the conversion factor by which to multiply a value in dpcm to get the value in dphi. A client can specify a resolution value in units other than dpi or dpcm by supplying its own conversion factor. However, since the internal units of dphi was chosen with supporting only the external units of dpi and dpcm in mind, there is no guarantee that the conversion factor for the client's units will be an exact integer. If the conversion factor isn't an exact integer, resolution values in the client's units won't be stored precisely.

See Also:
Serialized Form

Field Summary
static int | DPCM Value to indicate units of dots per centimeter (dpcm).
static int | DPI Value to indicate units of dots per inch (dpi).
Constructor Summary
ResolutionSyntax(int crossFeedResolution, int feedResolution, int units)
Construct a new resolution attribute from the given items.
Method Summary
boolean | equals(Object object) Returns whether this resolution attribute is equivalent to the passed in object.
int | getCrossFeedResolution(int units) Returns this resolution attribute's cross feed direction resolution in the given units.
protected int | getCrossFeedResolutionDphi() Returns this resolution attribute's cross feed direction resolution in units of dphi.
int | getFeedResolution(int units) Returns this resolution attribute's feed direction resolution in the given units.
protected int | getFeedResolutionDphi() Returns this resolution attribute's feed direction resolution in units of dphi.
int[] | getResolution(int units) Get this resolution attribute's resolution values in the given units.
int | hashCode() Returns a hash code value for this resolution attribute.
boolean | lessThanOrEquals(ResolutionSyntax other) Determine whether this resolution attribute's value is less than or equal to the given resolution attribute's value.
String | toString() Returns a string version of this resolution attribute.
String | toString(int units, String unitsName) Returns a string version of this resolution attribute in the given units.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

DPI

public static final int DPI
Value to indicate units of dots per inch (dpi). It is actually the conversion factor by which to multiply dpi to yield dphi (100).

See Also:
Constant Field Values

DPCM

public static final int DPCM
Value to indicate units of dots per centimeter (dpcm). It is actually the conversion factor by which to multiply dpcm to yield dphi (254).

See Also:
Constant Field Values
Constructor Detail

ResolutionSyntax

public ResolutionSyntax(int crossFeedResolution,
                        int feedResolution,
                        int units)
Construct a new resolution attribute from the given items.

Parameters:
crossFeedResolution - Cross feed direction resolution.
feedResolution - Feed direction resolution.
units - Unit conversion factor, e.g. DPI or DPCM.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if crossFeedResolution < 1 or feedResolution < 1 or units < 1.
Method Detail

getResolution

public int[] getResolution(int units)
Get this resolution attribute's resolution values in the given units. The values are rounded to the nearest integer.

Parameters:
units - Unit conversion factor, e.g. DPI or DPCM.
Returns:
A two-element array with the cross feed direction resolution at index 0 and the feed direction resolution at index 1.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if units < 1.

getCrossFeedResolution

public int getCrossFeedResolution(int units)
Returns this resolution attribute's cross feed direction resolution in the given units. The value is rounded to the nearest integer.

Parameters:
units - Unit conversion factor, e.g. DPI or DPCM.
Returns:
Cross feed direction resolution.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if units < 1.

getFeedResolution

public int getFeedResolution(int units)
Returns this resolution attribute's feed direction resolution in the given units. The value is rounded to the nearest integer.

Parameters:
units - Unit conversion factor, e.g. DPI or DPCM.
Returns:
Feed direction resolution.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if units < 1.

toString

public String toString(int units,
                       String unitsName)
Returns a string version of this resolution attribute in the given units. The string takes the form "CxF U", where C is the cross feed direction resolution, F is the feed direction resolution, and U is the units name. The values are rounded to the nearest integer.

Parameters:
units - Unit conversion factor, e.g. DPI or DPCM.
unitsName - Units name string, e.g. "dpi" or "dpcm". If null, no units name is appended to the result.
Returns:
String version of this resolution attribute.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if units < 1.

lessThanOrEquals

public boolean lessThanOrEquals(ResolutionSyntax other)
Determine whether this resolution attribute's value is less than or equal to the given resolution attribute's value. This is true if all of the following conditions are true:
  • This attribute's cross feed direction resolution is less than or equal to the other attribute's cross feed direction resolution.
  • This attribute's feed direction resolution is less than or equal to the other attribute's feed direction resolution.

Parameters:
other - Resolution attribute to compare with.
Returns:
True if this resolution attribute is less than or equal to the other resolution attribute, false otherwise.
Throws:
NullPointerException - (unchecked exception) Thrown if other is null.

equals

public boolean equals(Object object)
Returns whether this resolution attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class ResolutionSyntax.
  3. This attribute's cross feed direction resolution is equal to object's cross feed direction resolution.
  4. This attribute's feed direction resolution is equal to object's feed direction resolution.

Overrides:
equals in class Object
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this resolution attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns a hash code value for this resolution attribute.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Returns a string version of this resolution attribute. The string takes the form "CxF dphi", where C is the cross feed direction resolution and F is the feed direction resolution. The values are reported in the internal units of dphi.

Overrides:
toString in class Object
Returns:
a string representation of the object.

getCrossFeedResolutionDphi

protected int getCrossFeedResolutionDphi()
Returns this resolution attribute's cross feed direction resolution in units of dphi. (For use in a subclass.)

Returns:
Cross feed direction resolution.

getFeedResolutionDphi

protected int getFeedResolutionDphi()
Returns this resolution attribute's feed direction resolution in units of dphi. (For use in a subclass.)

Returns:
Feed direction resolution.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SetOfIntegerSyntax

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Class SetOfIntegerSyntax

java.lang.Object
    extended by  javax.print.attribute.SetOfIntegerSyntax
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
CopiesSupported, JobImpressionsSupported, JobKOctetsSupported, JobMediaSheetsSupported, NumberUpSupported, PageRanges
public abstract class SetOfIntegerSyntax
extends Object
implements Serializable, Cloneable

Class SetOfIntegerSyntax is an abstract base class providing the common implementation of all attributes whose value is a set of nonnegative integers. This includes attributes whose value is a single range of integers and attributes whose value is a set of ranges of integers.

You can construct an instance of SetOfIntegerSyntax by giving it in "string form." The string consists of zero or more comma-separated integer groups. Each integer group consists of either one integer, two integers separated by a hyphen (-), or two integers separated by a colon (:). Each integer consists of one or more decimal digits (0 through 9). Whitespace characters cannot appear within an integer but are otherwise ignored. For example: "", "1", "5-10", "1:2, 4".

You can also construct an instance of SetOfIntegerSyntax by giving it in "array form." Array form consists of an array of zero or more integer groups where each integer group is a length-1 or length-2 array of ints; for example, int[0][], int[][]{{1}}, int[][]{{5,10}}, int[][]{{1,2},{4}}.

In both string form and array form, each successive integer group gives a range of integers to be included in the set. The first integer in each group gives the lower bound of the range; the second integer in each group gives the upper bound of the range; if there is only one integer in the group, the upper bound is the same as the lower bound. If the upper bound is less than the lower bound, it denotes a null range (no values). If the upper bound is equal to the lower bound, it denotes a range consisting of a single value. If the upper bound is greater than the lower bound, it denotes a range consisting of more than one value. The ranges may appear in any order and are allowed to overlap. The union of all the ranges gives the set's contents. Once a SetOfIntegerSyntax instance is constructed, its value is immutable.

The SetOfIntegerSyntax object's value is actually stored in "canonical array form." This is the same as array form, except there are no null ranges; the members of the set are represented in as few ranges as possible (i.e., overlapping ranges are coalesced); the ranges appear in ascending order; and each range is always represented as a length-two array of ints in the form {lower bound, upper bound}. An empty set is represented as a zero-length array.

Class SetOfIntegerSyntax has operations to return the set's members in canonical array form, to test whether a given integer is a member of the set, and to iterate through the members of the set.

See Also:
Serialized Form

Constructor Summary
protected | SetOfIntegerSyntax(int member) Construct a new set-of-integer attribute containing a single integer.
protected | SetOfIntegerSyntax(int[][] members) Construct a new set-of-integer attribute with the given members in array form.
protected | SetOfIntegerSyntax(int lowerBound, int upperBound) Construct a new set-of-integer attribute containing a single range of integers.
protected | SetOfIntegerSyntax(String members) Construct a new set-of-integer attribute with the given members in string form.
Method Summary
boolean | contains(int x) Determine if this set-of-integer attribute contains the given value.
boolean | contains(IntegerSyntax attribute) Determine if this set-of-integer attribute contains the given integer attribute's value.
boolean | equals(Object object) Returns whether this set-of-integer attribute is equivalent to the passed in object.
int[][] | getMembers() Obtain this set-of-integer attribute's members in canonical array form.
int | hashCode() Returns a hash code value for this set-of-integer attribute.
int | next(int x) Determine the smallest integer in this set-of-integer attribute that is greater than the given value.
String | toString() Returns a string value corresponding to this set-of-integer attribute.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

SetOfIntegerSyntax

protected SetOfIntegerSyntax(String members)
Construct a new set-of-integer attribute with the given members in string form.

Parameters:
members - Set members in string form. If null, an empty set is constructed.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if members does not obey the proper syntax.

SetOfIntegerSyntax

protected SetOfIntegerSyntax(int[][] members)
Construct a new set-of-integer attribute with the given members in array form.

Parameters:
members - Set members in array form. If null, an empty set is constructed.
Throws:
NullPointerException - (Unchecked exception) Thrown if any element of members is null.
IllegalArgumentException - (Unchecked exception) Thrown if any element of members is not a length-one or length-two array or if any non-null range in members has a lower bound less than zero.

SetOfIntegerSyntax

protected SetOfIntegerSyntax(int member)
Construct a new set-of-integer attribute containing a single integer.

Parameters:
member - Set member.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if member is less than zero.

SetOfIntegerSyntax

protected SetOfIntegerSyntax(int lowerBound,
                             int upperBound)
Construct a new set-of-integer attribute containing a single range of integers. If the lower bound is greater than the upper bound (a null range), an empty set is constructed.

Parameters:
lowerBound - Lower bound of the range.
upperBound - Upper bound of the range.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if the range is non-null and lowerBound is less than zero.
Method Detail

getMembers

public int[][] getMembers()
Obtain this set-of-integer attribute's members in canonical array form. The returned array is "safe;" the client may alter it without affecting this set-of-integer attribute.

Returns:
This set-of-integer attribute's members in canonical array form.

contains

public boolean contains(int x)
Determine if this set-of-integer attribute contains the given value.

Parameters:
x - Integer value.
Returns:
True if this set-of-integer attribute contains the value x, false otherwise.

contains

public boolean contains(IntegerSyntax attribute)
Determine if this set-of-integer attribute contains the given integer attribute's value.

Parameters:
attribute - Integer attribute.
Returns:
True if this set-of-integer attribute contains theAttribute's value, false otherwise.

next

public int next(int x)
Determine the smallest integer in this set-of-integer attribute that is greater than the given value. If there are no integers in this set-of-integer attribute greater than the given value, -1 is returned. (Since a set-of-integer attribute can only contain nonnegative values, -1 will never appear in the set.) You can use the next() method to iterate through the integer values in a set-of-integer attribute in ascending order, like this:
     SetOfIntegerSyntax attribute = . . .;
     int i = -1;
     while ((i = attribute.next (i)) != -1)
         {
         foo (i);
         }

Parameters:
x - Integer value.
Returns:
The smallest integer in this set-of-integer attribute that is greater than x, or -1 if no integer in this set-of-integer attribute is greater than x.

equals

public boolean equals(Object object)
Returns whether this set-of-integer attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class SetOfIntegerSyntax.
  3. This set-of-integer attribute's members and object's members are the same.

Overrides:
equals in class Object
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this set-of-integer attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns a hash code value for this set-of-integer attribute. The hash code is the sum of the lower and upper bounds of the ranges in the canonical array form, or 0 for an empty set.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Returns a string value corresponding to this set-of-integer attribute. The string value is a zero-length string if this set is empty. Otherwise, the string value is a comma-separated list of the ranges in the canonical array form, where each range is represented as "i" if the lower bound equals the upper bound or "i-j" otherwise.

Overrides:
toString in class Object
Returns:
a string representation of the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Size2DSyntax

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Class Size2DSyntax

java.lang.Object
    extended by  javax.print.attribute.Size2DSyntax
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
MediaSize
public abstract class Size2DSyntax
extends Object
implements Serializable, Cloneable

Class Size2DSyntax is an abstract base class providing the common implementation of all attributes denoting a size in two dimensions.

A two-dimensional size attribute's value consists of two items, the X dimension and the Y dimension. A two-dimensional size attribute may be constructed by supplying the two values and indicating the units in which the values are measured. Methods are provided to return a two-dimensional size attribute's values, indicating the units in which the values are to be returned. The two most common size units are inches (in) and millimeters (mm), and exported constants INCH and MM are provided for indicating those units.

Once constructed, a two-dimensional size attribute's value is immutable.

Design

A two-dimensional size attribute's X and Y dimension values are stored internally as integers in units of micrometers (µm), where 1 micrometer = 10-6 meter = 1/1000 millimeter = 1/25400 inch. This permits dimensions to be represented exactly to a precision of 1/1000 mm (= 1 µm) or 1/100 inch (= 254 µm). If fractional inches are expressed in negative powers of two, this permits dimensions to be represented exactly to a precision of 1/8 inch (= 3175 µm) but not 1/16 inch (because 1/16 inch does not equal an integral number of µm).

Storing the dimensions internally in common units of µm lets two size attributes be compared without regard to the units in which they were created; for example, 8.5 in will compare equal to 215.9 mm, as they both are stored as 215900 µm. For example, a lookup service can match resolution attributes based on equality of their serialized representations regardless of the units in which they were created. Using integers for internal storage allows precise equality comparisons to be done, which would not be guaranteed if an internal floating point representation were used. Note that if you're looking for U.S. letter sized media in metric units, you have to search for a media size of 215.9 x 279.4 mm; rounding off to an integral 216 x 279 mm will not match.

The exported constant INCH is actually the conversion factor by which to multiply a value in inches to get the value in µm. Likewise, the exported constant MM is the conversion factor by which to multiply a value in mm to get the value in µm. A client can specify a resolution value in units other than inches or mm by supplying its own conversion factor. However, since the internal units of µm was chosen with supporting only the external units of inch and mm in mind, there is no guarantee that the conversion factor for the client's units will be an exact integer. If the conversion factor isn't an exact integer, resolution values in the client's units won't be stored precisely.

See Also:
Serialized Form

Field Summary
static int | INCH Value to indicate units of inches (in).
static int | MM Value to indicate units of millimeters (mm).
Constructor Summary
protected | Size2DSyntax(float x, float y, int units) Construct a new two-dimensional size attribute from the given floating-point values.
protected | Size2DSyntax(int x, int y, int units) Construct a new two-dimensional size attribute from the given integer values.
Method Summary
boolean | equals(Object object) Returns whether this two-dimensional size attribute is equivalent to the passed in object.
float[] | getSize(int units) Get this two-dimensional size attribute's dimensions in the given units as floating-point values.
float | getX(int units) Returns this two-dimensional size attribute's X dimension in the given units as a floating-point value.
protected int | getXMicrometers() Returns this two-dimensional size attribute's X dimension in units of micrometers (µm).
float | getY(int units) Returns this two-dimensional size attribute's Y dimension in the given units as a floating-point value.
protected int | getYMicrometers() Returns this two-dimensional size attribute's Y dimension in units of micrometers (µm).
int | hashCode() Returns a hash code value for this two-dimensional size attribute.
String | toString() Returns a string version of this two-dimensional size attribute.
String | toString(int units, String unitsName) Returns a string version of this two-dimensional size attribute in the given units.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

INCH

public static final int INCH
Value to indicate units of inches (in). It is actually the conversion factor by which to multiply inches to yield µm (25400).

See Also:
Constant Field Values

MM

public static final int MM
Value to indicate units of millimeters (mm). It is actually the conversion factor by which to multiply mm to yield µm (1000).

See Also:
Constant Field Values
Constructor Detail

Size2DSyntax

protected Size2DSyntax(float x,
                       float y,
                       int units)
Construct a new two-dimensional size attribute from the given floating-point values.

Parameters:
x - X dimension.
y - Y dimension.
units - Unit conversion factor, e.g. INCH or MM.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if x < 0 or y < 0 or units < 1.

Size2DSyntax

protected Size2DSyntax(int x,
                       int y,
                       int units)
Construct a new two-dimensional size attribute from the given integer values.

Parameters:
x - X dimension.
y - Y dimension.
units - Unit conversion factor, e.g. INCH or MM.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if x < 0 or y < 0 or units < 1.
Method Detail

getSize

public float[] getSize(int units)
Get this two-dimensional size attribute's dimensions in the given units as floating-point values.

Parameters:
units - Unit conversion factor, e.g. INCH or MM.
Returns:
A two-element array with the X dimension at index 0 and the Y dimension at index 1.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if units < 1.

getX

public float getX(int units)
Returns this two-dimensional size attribute's X dimension in the given units as a floating-point value.

Parameters:
units - Unit conversion factor, e.g. INCH or MM.
Returns:
X dimension.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if units < 1.

getY

public float getY(int units)
Returns this two-dimensional size attribute's Y dimension in the given units as a floating-point value.

Parameters:
units - Unit conversion factor, e.g. INCH or MM.
Returns:
Y dimension.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if units < 1.

toString

public String toString(int units,
                       String unitsName)
Returns a string version of this two-dimensional size attribute in the given units. The string takes the form "XxY U", where X is the X dimension, Y is the Y dimension, and U is the units name. The values are displayed in floating point.

Parameters:
units - Unit conversion factor, e.g. INCH or MM.
unitsName - Units name string, e.g. "in" or "mm". If null, no units name is appended to the result.
Returns:
String version of this two-dimensional size attribute.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if units < 1.

equals

public boolean equals(Object object)
Returns whether this two-dimensional size attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class Size2DSyntax.
  3. This attribute's X dimension is equal to object's X dimension.
  4. This attribute's Y dimension is equal to object's Y dimension.

Overrides:
equals in class Object
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this two-dimensional size attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns a hash code value for this two-dimensional size attribute.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Returns a string version of this two-dimensional size attribute. The string takes the form "XxY um", where X is the X dimension and Y is the Y dimension. The values are reported in the internal units of micrometers.

Overrides:
toString in class Object
Returns:
a string representation of the object.

getXMicrometers

protected int getXMicrometers()
Returns this two-dimensional size attribute's X dimension in units of micrometers (µm). (For use in a subclass.)

Returns:
X dimension (µm).

getYMicrometers

protected int getYMicrometers()
Returns this two-dimensional size attribute's Y dimension in units of micrometers (µm). (For use in a subclass.)

Returns:
Y dimension (µm).
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


standard

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.print.attribute.standard

Package javax.print.attribute.standard contains classes for specific printing attributes.

See:
Description

Class Summary
Chromaticity | Class Chromaticity is a printing attribute class, an enumeration, that specifies monochrome or color printing.
ColorSupported | Class ColorSupported is a printing attribute class, an enumeration, that identifies whether the device is capable of any type of color printing at all, including highlight color as well as full process color.
Compression | Class Compression is a printing attribute class, an enumeration, that specifies how print data is compressed.
Copies | Class Copies is an integer valued printing attribute class that specifies the number of copies to be printed.
CopiesSupported | Class CopiesSupported is a printing attribute class, a set of integers, that gives the supported values for a Copies attribute.
DateTimeAtCompleted | Class DateTimeAtCompleted is a printing attribute class, a date-time attribute, that indicates the date and time at which the Print Job completed (or was canceled or aborted).
DateTimeAtCreation | Class DateTimeAtCreation is a printing attribute class, a date-time attribute, that indicates the date and time at which the Print Job was created.
DateTimeAtProcessing | Class DateTimeAtProcessing is a printing attribute class, a date-time attribute, that indicates the date and time at which the Print Job first began processing.
Destination | Class Destination is a printing attribute class, a URI, that is used to indicate an alternate destination for the spooled printer formatted data.
DocumentName | Class DocumentName is a printing attribute class, a text attribute, that specifies the name of a document.
Fidelity | Class Fidelity is a printing attribute class, an enumeration, that indicates whether total fidelity to client supplied print request attributes is required.
Finishings | Class Finishings is a printing attribute class, an enumeration, that identifies whether the printer applies a finishing operation of some kind of binding to each copy of each printed document in the job.
JobHoldUntil | Class JobHoldUntil is a printing attribute class, a date-time attribute, that specifies the exact date and time at which the job must become a candidate for printing.
JobImpressions | Class JobImpressions is an integer valued printing attribute class that specifies the total size in number of impressions of the document(s) being submitted.
JobImpressionsCompleted | Class JobImpressionsCompleted is an integer valued printing attribute class that specifies the number of impressions completed for the job so far.
JobImpressionsSupported | Class JobImpressionsSupported is a printing attribute class, a set of integers, that gives the supported values for a JobImpressions attribute.
JobKOctets | Class JobKOctets is an integer valued printing attribute class that specifies the total size of the document(s) in K octets, i.e., in units of 1024 octets requested to be processed in the job.
JobKOctetsProcessed | Class JobKOctetsProcessed is an integer valued printing attribute class that specifies the total number of print data octets processed so far in K octets, i.e., in units of 1024 octets.
JobKOctetsSupported | Class JobKOctetsSupported is a printing attribute class, a set of integers, that gives the supported values for a JobKOctets attribute.
JobMediaSheets | Class JobMediaSheets is an integer valued printing attribute class that specifies the total number of media sheets to be produced for this job.
JobMediaSheetsCompleted | Class JobMediaSheetsCompleted is an integer valued printing attribute class that specifies the number of media sheets which have completed marking and stacking for the entire job so far, whether those sheets have been processed on one side or on both.
JobMediaSheetsSupported | Class JobMediaSheetsSupported is a printing attribute class, a set of integers, that gives the supported values for a JobMediaSheets attribute.
JobMessageFromOperator | Class JobMessageFromOperator is a printing attribute class, a text attribute, that provides a message from an operator, system administrator, or "intelligent" process to indicate to the end user the reasons for modification or other management action taken on a job.
JobName | Class JobName is a printing attribute class, a text attribute, that specifies the name of a print job.
JobOriginatingUserName | Class JobOriginatingUserName is a printing attribute class, a text attribute, that contains the name of the end user that submitted the print job.
JobPriority | Class JobPriority is an integer valued printing attribute class that specifies a print job's priority.
JobPrioritySupported | Class JobPrioritySupported is an integer valued printing attribute class that specifies whether a Print Service instance supports the JobPriority attribute and the number of different job priority levels supported.
JobSheets | Class JobSheets is a printing attribute class, an enumeration, that determines which job start and end sheets, if any, must be printed with a job.
JobState | JobState is a printing attribute class, an enumeration, that identifies the current state of a print job.
JobStateReason | Class JobStateReason is a printing attribute class, an enumeration, that provides additional information about the job's current state, i.e., information that augments the value of the job's JobState attribute.
JobStateReasons | Class JobStateReasons is a printing attribute class, a set of enumeration values, that provides additional information about the job's current state, i.e., information that augments the value of the job's JobState attribute.
Media | Class Media is a printing attribute class that specifies the medium on which to print.
MediaName | Class MediaName is a subclass of Media, a printing attribute class (an enumeration) that specifies the media for a print job as a name.
MediaPrintableArea | Class MediaPrintableArea is a printing attribute used to distinguish the printable and non-printable areas of media.
MediaSize | Class MediaSize is a two-dimensional size valued printing attribute class that indicates the dimensions of the medium in a portrait orientation, with the X dimension running along the bottom edge and the Y dimension running along the left edge.
MediaSize.Engineering | Class MediaSize.Engineering includes MediaSize values for engineering media.
MediaSize.ISO | Class MediaSize.ISO includes MediaSize values for ISO media.
MediaSize.JIS | Class MediaSize.JIS includes MediaSize values for JIS (Japanese) media.
MediaSize.NA | Class MediaSize.NA includes MediaSize values for North American media.
MediaSize.Other | Class MediaSize.Other includes MediaSize values for miscellaneous media.
MediaSizeName | Class MediaSizeName is a subclass of Media.
MediaTray | Class MediaTray is a subclass of Media.
MultipleDocumentHandling | Class MultipleDocumentHandling is a printing attribute class, an enumeration, that controls finishing operations and the placement of one or more print-stream pages into impressions and onto media sheets.
NumberOfDocuments | Class NumberOfDocuments is an integer valued printing attribute that indicates the number of individual docs the printer has accepted for this job, regardless of whether the docs' print data has reached the printer or not.
NumberOfInterveningJobs | Class NumberOfInterveningJobs is an integer valued printing attribute that indicates the number of jobs that are ahead of this job in the relative chronological order of expected time to complete (i.e., the current scheduled order).
NumberUp | Class NumberUp is an integer valued printing attribute class that specifies the number of print-stream pages to impose upon a single side of an instance of a selected medium.
NumberUpSupported | Class NumberUpSupported is a printing attribute class, a set of integers, that gives the supported values for a NumberUp attribute.
OrientationRequested | Class OrientationRequested is a printing attribute class, an enumeration, that indicates the desired orientation for printed print-stream pages; it does not describe the orientation of the client-supplied print-stream pages.
OutputDeviceAssigned | Class OutputDeviceAssigned is a printing attribute class, a text attribute, that identifies the output device to which the service has assigned this job.
PageRanges | Class PageRanges is a printing attribute class, a set of integers, that identifies the range(s) of print-stream pages that the Printer object uses for each copy of each document which are to be printed.
PagesPerMinute | Class PagesPerMinute is an integer valued printing attribute that indicates the nominal number of pages per minute to the nearest whole number which may be generated by this printer (e.g., simplex, black-and-white).
PagesPerMinuteColor | Class PagesPerMinuteColor is an integer valued printing attribute that indicates the nominal number of pages per minute to the nearest whole number which may be generated by this printer when printing color (e.g., simplex, color).
PDLOverrideSupported | Class PDLOverrideSupported is a printing attribute class, an enumeration, that expresses the printer's ability to attempt to override processing instructions embedded in documents' print data with processing instructions specified as attributes outside the print data.
PresentationDirection | Class PresentationDirection is a printing attribute class, an enumeration, that is used in conjunction with the NumberUp attribute to indicate the layout of multiple print-stream pages to impose upon a single side of an instance of a selected medium.
PrinterInfo | Class PrinterInfo is a printing attribute class, a text attribute, that provides descriptive information about a printer.
PrinterIsAcceptingJobs | Class PrinterIsAcceptingJobs is a printing attribute class, an enumeration, that indicates whether the printer is currently able to accept jobs.
PrinterLocation | Class PrinterLocation is a printing attribute class, a text attribute, that identifies the location of the device.
PrinterMakeAndModel | Class PrinterMakeAndModel is a printing attribute class, a text attribute, that the make and model of the printer.
PrinterMessageFromOperator | Class PrinterMessageFromOperator is a printing attribute class, a text attribute, that provides a message from an operator, system administrator, or "intelligent" process to indicate to the end user information about or status of the printer, such as why it is unavailable or when it is expected to be available.
PrinterMoreInfo | Class PrinterMoreInfo is a printing attribute class, a URI, that is used to obtain more information about this specific printer.
PrinterMoreInfoManufacturer | Class PrinterMoreInfoManufacturer is a printing attribute class, a URI, that is used to obtain more information about this type of device.
PrinterName | Class PrinterName is a printing attribute class, a text attribute, that specifies the name of a printer.
PrinterResolution | Class PrinterResolution is a printing attribute class that specifies an exact resolution supported by a printer or to be used for a print job.
PrinterState | Class PrinterState is a printing attribute class, an enumeration, that identifies the current state of a printer.
PrinterStateReason | Class PrinterStateReason is a printing attribute class, an enumeration, that provides additional information about the printer's current state, i.e., information that augments the value of the printer's PrinterState attribute.
PrinterStateReasons | Class PrinterStateReasons is a printing attribute class, a set of enumeration values, that provides additional information about the printer's current state, i.e., information that augments the value of the printer's PrinterState attribute.
PrinterURI | Class PrinterURI is a printing attribute class, a URI, that specifies the globally unique name of a printer.
PrintQuality | Class PrintQuality is a printing attribute class, an enumeration, that specifies the print quality that the printer uses for the job.
QueuedJobCount | Class QueuedJobCount is an integer valued printing attribute that indicates the number of jobs in the printer whose JobState is either PENDING, PENDING_HELD, PROCESSING, or PROCESSING_STOPPED.
ReferenceUriSchemesSupported | Class ReferenceUriSchemesSupported is a printing attribute class an enumeration, that indicates a "URI scheme," such as "http:" or "ftp:", that a printer can use to retrieve print data stored at a URI location.
RequestingUserName | Class RequestingUserName is a printing attribute class, a text attribute, that specifies the name of the end user that submitted the print job.
Severity | Class Severity is a printing attribute class, an enumeration, that denotes the severity of a PrinterStateReason attribute.
SheetCollate | Class SheetCollate is a printing attribute class, an enumeration, that specifies whether or not the media sheets of each copy of each printed document in a job are to be in sequence, when multiple copies of the document are specified by the Copies attribute.
Sides | Class Sides is a printing attribute class, an enumeration, that specifies how print-stream pages are to be imposed upon the sides of an instance of a selected medium, i.e., an impression.

Package javax.print.attribute.standard Description

Package javax.print.attribute.standard contains classes for specific printing attributes. The parent package, javax.print.attribute, provides classes and interfaces that describe the types of Java Print Service attributes and how they can be collected into attribute sets.

An attribute represents a printing feature that a print service can provide. For each attribute, a print service either does or does not support the attribute. For each possible value of a supported attribute, a print service either does or does not support the value.

The API requires every print service to support certain attributes; other attributes are optional and the service can choose whether or not to support them. Each attribute has a set of values that it accepts. The API requires every print service to support certain values for certain attributes; other attribute values are optional and the service can choose whether or not to support them. These support requirements are recorded in the documentation for each attribute class.

Package javax.print.attribute.standard contains standard printing attributes and standard printing attribute values that are widely used in the printing domain. A print service vendor can provide new vendor-specific printing attributes in addition to the standard ones. A vendor can also provide vendor-specific extensions (subclasses) of the standard printing attributes -- for example, to provide additional vendor-specific values for an existing standard attribute. Of course, if a vendor wants clients to be able to use any added or extended attributes, the vendor must publish the new attribute classes.

Many of the standard attribute classes extend one of the abstract syntax classes of the javax.print.attribute package. These abstract syntax classes each represent a different type. The EnumSyntax class, for example, represents a type-safe enumeration. The abstract syntax class provides a wrapper for the attribute value.

If an attribute class extends EnumSyntax, and the value of the attribute is an IPP-compatible value, the attribute's toString method returns the IPP string representation of the attribute value, such as "processing-stopped" for the JobState attribute. However, because the EnumSyntax class is extensible, vendors can define their own attribute values. If an attribute uses the EnumSyntax class and is set to one of these vendor-defined values then the toString method will not return the IPP string representation of the value.

A printing client application will typically not need to use all the printing attribute classes in package javax.print.attribute.standard, just the ones that pertain to the application.

The attribute classes in package javax.print.attribute.standard are based on the Internet Printing Protocol (IPP) attributes as defined in the Internet RFC document, RFC 2911 Internet Printing Protocol/1.1: Model and Semantics dated September 2000. See RFC 2911 for more information. The descriptive text for each attribute class was taken largely from the above documents. The above authors' contribution to the API is gratefully acknowledged.

Attribute Organization

There are five kinds of printing attributes: doc attributes, print request attributes, print job attributes, print service attributes, and supported-values attributes.

Doc Attributes

Doc attributes specify the characteristics of an individual doc and the print job settings to be applied to an individual doc. A doc attribute class implements interface DocAttribute. A doc attribute can appear in a DocAttributeSet.

Print Request Attributes

Print request attributes specify the settings to be applied to a whole print job and to all the docs in the print job. A print request attribute class implements interface PrintRequestAttribute. A print request attribute can appear in a PrintRequestAttributeSet.

Some attributes are doc attributes but not print request attributes and may only be specified at the doc level. Some attributes are print request attributes but not doc attributes and may only be specified at the Print Request level. Some attributes are both doc attributes and print request attributes and may be specified either at the doc level or at the Print Request level.

When specified at the doc level, an attribute applies just to that one doc. When specified at the Print Request level, an attribute applies to the whole job, including all the docs in the job. However, an attribute specified at the doc level overrides an attribute in the same category specified at the Print Request level.

Print Job Attributes

Print job attributes report the status of a Print Job. A print job attribute class implements interface PrintJobAttribute. A print job attribute can appear in a PrintJobAttributeSet.

Some attributes are both print request attributes and print job attributes; a client may include such attributes in a Print Request to specify characteristics for the ensuing Print Job, and those attributes then also appear in the Print Job's attribute set. Some attributes are print job attributes but not print request attributes; the print service itself adds these attributes to the Print Job's attribute set.

Print Service Attributes

Print service attributes report the status of a print service. A print service attribute class implements interface PrintServiceAttribute. A print service attribute can appear in a PrintServiceAttributeSet.

Supported-Values Attributes

A supported-value attribute indicates the legal values for another attribute that a print service supports. A supported-values attribute class implements interface SupportedValuesAttribute. However, supported-values attributes never appear in attribute sets, so there is no restricted AttributeSet subinterface for them.

Attribute Table

The table below lists all the printing attributes. The table shows the tagging interfaces each attribute class implements in addition to interface Attribute, thus indicating how each attribute is used in the API. For each doc attribute and print request attribute, the column marked "SupportedValuesAttribute" lists the supported-values attribute class, if any, with which a print service indicates the supported values for that attribute category.

Attribute Class | Doc Attribute | Print Request Attribute | Print Job Attribute | Print Service Attribute | SupportedValuesAttribute
Compression | X |  |  |  |
DocumentName | X |  |  |  |
Chromaticity | X | X | X |  |
Copies |  | X | X |  | CopiesSupported
Finishings | X | X | X |  |
JobHoldUntil |  | X | X |  |
JobImpressions |  | X | X |  | JobImpressionsSupported
JobKOctets |  | X | X |  | JobKOctetsSupported
JobMediaSheets |  | X | X |  | JobMediaSheetsSupported
JobName |  | X | X |  |
JobPriority |  | X | X |  | JobPrioritySupported
JobSheets |  | X | X |  |
Media | X | X | X |  |
MediaSize |  |  |  |  |
MultipleDocumentHandling |  | X | X |  |
NumberUp | X | X | X |  | NumberUpSupported
OrientationRequested | X | X | X |  |
PageRanges | X | X | X |  |
PresentationDirection | X | X | X |  |
PrinterResolution | X | X | X |  |
PrintQuality | X | X | X |  |
RequestingUserName |  | X | X |  |
SheetCollate | X | X | X |  |
Sides | X | X | X |  |
DateTimeAtCompleted |  |  | X |  |
DateTimeAtCreation |  |  | X |  |
DateTimeAtProcessing |  |  | X |  |
JobImpressionsCompleted |  |  | X |  |
JobKOctetsProcessed |  |  | X |  |
JobMediaSheetsCompleted |  |  | X |  |
JobMessageFromOperator |  |  | X |  |
JobOriginatingUserName |  |  | X |  |
JobState |  |  | X |  |
JobStateReasons Contains zero or more -- |  |  | X |  |
-- JobStateReason |  |  |  |  |
NumberOfDocuments |  |  | X |  |
NumberOfInterveningJobs |  |  | X |  |
OutputDeviceAssigned |  |  | X |  |
ColorSupported |  |  |  | X |
PagesPerMinute |  |  |  | X |
PagesPerMinuteColor |  |  |  | X |
PDLOverrideSupported |  |  |  | X |
PrinterIsAcceptingJobs |  |  |  | X |
PrinterInfo |  |  |  | X |
PrinterLocation |  |  |  | X |
PrinterMessageFromOperator |  |  |  | X |
PrinterMakeAndModel |  |  |  | X |
PrinterMoreInfo |  |  |  | X |
PrinterMoreInfoManufacturer |  |  |  | X |
PrinterName |  |  |  | X |
PrinterState |  |  |  | X |
PrinterStateReasons Contains zero or more -- |  |  |  | X |
-- PrinterStateReason |  |  |  |  |
-- Severity |  |  |  |  |
QueuedJobCount |  |  |  | X |
ReferenceUriSchemesSupported |  |  |  |  |

Please note: In the javax.print APIs, a null reference parameter to methods is incorrect unless explicitly documented on the method as having a meaningful interpretation. Usage to the contrary is incorrect coding and may result in a run time exception either immediately or at some later time. IllegalArgumentException and NullPointerException are examples of typical and acceptable run time exceptions for such cases.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.print.attribute.standard Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.print.attribute.standard

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.util.AbstractCollection<E> (implements java.util.Collection<E>)
      • java.util.AbstractSet<E> (implements java.util.Set<E>)
        • java.util.HashSet<E> (implements java.lang.Cloneable, java.io.Serializable, java.util.Set<E>)
          • javax.print.attribute.standard.JobStateReasons (implements javax.print.attribute.PrintJobAttribute)
    • java.util.AbstractMap<K,V> (implements java.util.Map<K,V>)
      • java.util.HashMap<K,V> (implements java.lang.Cloneable, java.util.Map<K,V>, java.io.Serializable)
        • javax.print.attribute.standard.PrinterStateReasons (implements javax.print.attribute.PrintServiceAttribute)
    • javax.print.attribute.DateTimeSyntax (implements java.lang.Cloneable, java.io.Serializable)
      • javax.print.attribute.standard.DateTimeAtCompleted (implements javax.print.attribute.PrintJobAttribute)
      • javax.print.attribute.standard.DateTimeAtCreation (implements javax.print.attribute.PrintJobAttribute)
      • javax.print.attribute.standard.DateTimeAtProcessing (implements javax.print.attribute.PrintJobAttribute)
      • javax.print.attribute.standard.JobHoldUntil (implements javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
    • javax.print.attribute.EnumSyntax (implements java.lang.Cloneable, java.io.Serializable)
      • javax.print.attribute.standard.Chromaticity (implements javax.print.attribute.DocAttribute, javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
      • javax.print.attribute.standard.ColorSupported (implements javax.print.attribute.PrintServiceAttribute)
      • javax.print.attribute.standard.Compression (implements javax.print.attribute.DocAttribute)
      • javax.print.attribute.standard.Fidelity (implements javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
      • javax.print.attribute.standard.Finishings (implements javax.print.attribute.DocAttribute, javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
      • javax.print.attribute.standard.JobSheets (implements javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
      • javax.print.attribute.standard.JobState (implements javax.print.attribute.PrintJobAttribute)
      • javax.print.attribute.standard.JobStateReason (implements javax.print.attribute.Attribute)
      • javax.print.attribute.standard.Media (implements javax.print.attribute.DocAttribute, javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
        • javax.print.attribute.standard.MediaName (implements javax.print.attribute.Attribute)
        • javax.print.attribute.standard.MediaSizeName
        • javax.print.attribute.standard.MediaTray (implements javax.print.attribute.Attribute)
      • javax.print.attribute.standard.MultipleDocumentHandling (implements javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
      • javax.print.attribute.standard.OrientationRequested (implements javax.print.attribute.DocAttribute, javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
      • javax.print.attribute.standard.PDLOverrideSupported (implements javax.print.attribute.PrintServiceAttribute)
      • javax.print.attribute.standard.PresentationDirection (implements javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
      • javax.print.attribute.standard.PrinterIsAcceptingJobs (implements javax.print.attribute.PrintServiceAttribute)
      • javax.print.attribute.standard.PrinterState (implements javax.print.attribute.PrintServiceAttribute)
      • javax.print.attribute.standard.PrinterStateReason (implements javax.print.attribute.Attribute)
      • javax.print.attribute.standard.PrintQuality (implements javax.print.attribute.DocAttribute, javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
      • javax.print.attribute.standard.ReferenceUriSchemesSupported (implements javax.print.attribute.Attribute)
      • javax.print.attribute.standard.Severity (implements javax.print.attribute.Attribute)
      • javax.print.attribute.standard.SheetCollate (implements javax.print.attribute.DocAttribute, javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
      • javax.print.attribute.standard.Sides (implements javax.print.attribute.DocAttribute, javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
    • javax.print.attribute.IntegerSyntax (implements java.lang.Cloneable, java.io.Serializable)
      • javax.print.attribute.standard.Copies (implements javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
      • javax.print.attribute.standard.JobImpressions (implements javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
      • javax.print.attribute.standard.JobImpressionsCompleted (implements javax.print.attribute.PrintJobAttribute)
      • javax.print.attribute.standard.JobKOctets (implements javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
      • javax.print.attribute.standard.JobKOctetsProcessed (implements javax.print.attribute.PrintJobAttribute)
      • javax.print.attribute.standard.JobMediaSheets (implements javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
      • javax.print.attribute.standard.JobMediaSheetsCompleted (implements javax.print.attribute.PrintJobAttribute)
      • javax.print.attribute.standard.JobPriority (implements javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
      • javax.print.attribute.standard.JobPrioritySupported (implements javax.print.attribute.SupportedValuesAttribute)
      • javax.print.attribute.standard.NumberOfDocuments (implements javax.print.attribute.PrintJobAttribute)
      • javax.print.attribute.standard.NumberOfInterveningJobs (implements javax.print.attribute.PrintJobAttribute)
      • javax.print.attribute.standard.NumberUp (implements javax.print.attribute.DocAttribute, javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
      • javax.print.attribute.standard.PagesPerMinute (implements javax.print.attribute.PrintServiceAttribute)
      • javax.print.attribute.standard.PagesPerMinuteColor (implements javax.print.attribute.PrintServiceAttribute)
      • javax.print.attribute.standard.QueuedJobCount (implements javax.print.attribute.PrintServiceAttribute)
    • javax.print.attribute.standard.MediaPrintableArea (implements javax.print.attribute.DocAttribute, javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
    • javax.print.attribute.standard.MediaSize.Engineering
    • javax.print.attribute.standard.MediaSize.ISO
    • javax.print.attribute.standard.MediaSize.JIS
    • javax.print.attribute.standard.MediaSize.NA
    • javax.print.attribute.standard.MediaSize.Other
    • javax.print.attribute.ResolutionSyntax (implements java.lang.Cloneable, java.io.Serializable)
      • javax.print.attribute.standard.PrinterResolution (implements javax.print.attribute.DocAttribute, javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
    • javax.print.attribute.SetOfIntegerSyntax (implements java.lang.Cloneable, java.io.Serializable)
      • javax.print.attribute.standard.CopiesSupported (implements javax.print.attribute.SupportedValuesAttribute)
      • javax.print.attribute.standard.JobImpressionsSupported (implements javax.print.attribute.SupportedValuesAttribute)
      • javax.print.attribute.standard.JobKOctetsSupported (implements javax.print.attribute.SupportedValuesAttribute)
      • javax.print.attribute.standard.JobMediaSheetsSupported (implements javax.print.attribute.SupportedValuesAttribute)
      • javax.print.attribute.standard.NumberUpSupported (implements javax.print.attribute.SupportedValuesAttribute)
      • javax.print.attribute.standard.PageRanges (implements javax.print.attribute.DocAttribute, javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
    • javax.print.attribute.Size2DSyntax (implements java.lang.Cloneable, java.io.Serializable)
      • javax.print.attribute.standard.MediaSize (implements javax.print.attribute.Attribute)
    • javax.print.attribute.TextSyntax (implements java.lang.Cloneable, java.io.Serializable)
      • javax.print.attribute.standard.DocumentName (implements javax.print.attribute.DocAttribute)
      • javax.print.attribute.standard.JobMessageFromOperator (implements javax.print.attribute.PrintJobAttribute)
      • javax.print.attribute.standard.JobName (implements javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
      • javax.print.attribute.standard.JobOriginatingUserName (implements javax.print.attribute.PrintJobAttribute)
      • javax.print.attribute.standard.OutputDeviceAssigned (implements javax.print.attribute.PrintJobAttribute)
      • javax.print.attribute.standard.PrinterInfo (implements javax.print.attribute.PrintServiceAttribute)
      • javax.print.attribute.standard.PrinterLocation (implements javax.print.attribute.PrintServiceAttribute)
      • javax.print.attribute.standard.PrinterMakeAndModel (implements javax.print.attribute.PrintServiceAttribute)
      • javax.print.attribute.standard.PrinterMessageFromOperator (implements javax.print.attribute.PrintServiceAttribute)
      • javax.print.attribute.standard.PrinterName (implements javax.print.attribute.PrintServiceAttribute)
      • javax.print.attribute.standard.RequestingUserName (implements javax.print.attribute.PrintRequestAttribute)
    • javax.print.attribute.URISyntax (implements java.lang.Cloneable, java.io.Serializable)
      • javax.print.attribute.standard.Destination (implements javax.print.attribute.PrintJobAttribute, javax.print.attribute.PrintRequestAttribute)
      • javax.print.attribute.standard.PrinterMoreInfo (implements javax.print.attribute.PrintServiceAttribute)
      • javax.print.attribute.standard.PrinterMoreInfoManufacturer (implements javax.print.attribute.PrintServiceAttribute)
      • javax.print.attribute.standard.PrinterURI (implements javax.print.attribute.PrintServiceAttribute)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.print.attribute.standard

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.print.attribute.standard

Packages that use javax.print.attribute.standard
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Classes in javax.print.attribute.standard used by javax.print.attribute.standard
Chromaticity
Class Chromaticity is a printing attribute class, an enumeration, that specifies monochrome or color printing.
ColorSupported
Class ColorSupported is a printing attribute class, an enumeration, that identifies whether the device is capable of any type of color printing at all, including highlight color as well as full process color.
Compression
Class Compression is a printing attribute class, an enumeration, that specifies how print data is compressed.
Fidelity
Class Fidelity is a printing attribute class, an enumeration, that indicates whether total fidelity to client supplied print request attributes is required.
Finishings
Class Finishings is a printing attribute class, an enumeration, that identifies whether the printer applies a finishing operation of some kind of binding to each copy of each printed document in the job.
JobSheets
Class JobSheets is a printing attribute class, an enumeration, that determines which job start and end sheets, if any, must be printed with a job.
JobState
JobState is a printing attribute class, an enumeration, that identifies the current state of a print job.
JobStateReason
Class JobStateReason is a printing attribute class, an enumeration, that provides additional information about the job's current state, i.e., information that augments the value of the job's JobState attribute.
Media
Class Media is a printing attribute class that specifies the medium on which to print.
MediaName
Class MediaName is a subclass of Media, a printing attribute class (an enumeration) that specifies the media for a print job as a name.
MediaSize
Class MediaSize is a two-dimensional size valued printing attribute class that indicates the dimensions of the medium in a portrait orientation, with the X dimension running along the bottom edge and the Y dimension running along the left edge.
MediaSizeName
Class MediaSizeName is a subclass of Media.
MediaTray
Class MediaTray is a subclass of Media.
MultipleDocumentHandling
Class MultipleDocumentHandling is a printing attribute class, an enumeration, that controls finishing operations and the placement of one or more print-stream pages into impressions and onto media sheets.
OrientationRequested
Class OrientationRequested is a printing attribute class, an enumeration, that indicates the desired orientation for printed print-stream pages; it does not describe the orientation of the client-supplied print-stream pages.
PDLOverrideSupported
Class PDLOverrideSupported is a printing attribute class, an enumeration, that expresses the printer's ability to attempt to override processing instructions embedded in documents' print data with processing instructions specified as attributes outside the print data.
PresentationDirection
Class PresentationDirection is a printing attribute class, an enumeration, that is used in conjunction with the NumberUp attribute to indicate the layout of multiple print-stream pages to impose upon a single side of an instance of a selected medium.
PrinterIsAcceptingJobs
Class PrinterIsAcceptingJobs is a printing attribute class, an enumeration, that indicates whether the printer is currently able to accept jobs.
PrinterState
Class PrinterState is a printing attribute class, an enumeration, that identifies the current state of a printer.
PrinterStateReason
Class PrinterStateReason is a printing attribute class, an enumeration, that provides additional information about the printer's current state, i.e., information that augments the value of the printer's PrinterState attribute.
PrintQuality
Class PrintQuality is a printing attribute class, an enumeration, that specifies the print quality that the printer uses for the job.
ReferenceUriSchemesSupported
Class ReferenceUriSchemesSupported is a printing attribute class an enumeration, that indicates a "URI scheme," such as "http:" or "ftp:", that a printer can use to retrieve print data stored at a URI location.
Severity
Class Severity is a printing attribute class, an enumeration, that denotes the severity of a PrinterStateReason attribute.
SheetCollate
Class SheetCollate is a printing attribute class, an enumeration, that specifies whether or not the media sheets of each copy of each printed document in a job are to be in sequence, when multiple copies of the document are specified by the Copies attribute.
Sides
Class Sides is a printing attribute class, an enumeration, that specifies how print-stream pages are to be imposed upon the sides of an instance of a selected medium, i.e., an impression.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Chromaticity

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class Chromaticity

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.Chromaticity
All Implemented Interfaces:
Serializable, Cloneable, Attribute, DocAttribute, PrintJobAttribute, PrintRequestAttribute
public final class Chromaticity
extends EnumSyntax
implements DocAttribute, PrintRequestAttribute, PrintJobAttribute

Class Chromaticity is a printing attribute class, an enumeration, that specifies monochrome or color printing. This is used by a print client to specify how the print data should be generated or processed. It is not descriptive of the color capabilities of the device. Query the service's ColorSupported attribute to determine if the device can be verified to support color printing.

The table below shows the effects of specifying a Chromaticity attribute of MONOCHROME or COLOR for a monochrome or color document.

Chromaticity Attribute | Effect on Monochrome Document | Effect on Color Document
MONOCHROME | Printed as is, in monochrome | Printed in monochrome, with colors converted to shades of gray
COLOR | Printed as is, in monochrome | Printed as is, in color

IPP Compatibility: Chromaticity is not an IPP attribute at present.

See Also:
Serialized Form

Field Summary
static Chromaticity | COLOR Color printing.
static Chromaticity | MONOCHROME Monochrome printing.
Constructor Summary
protected Chromaticity(int value)
Construct a new chromaticity enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class Chromaticity.
String | getName() Get the name of the category of which this attribute value is an instance.
protected String[] | getStringTable() Returns the string table for class Chromaticity.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

MONOCHROME

public static final Chromaticity MONOCHROME
Monochrome printing.

COLOR

public static final Chromaticity COLOR
Color printing.

Constructor Detail

Chromaticity

protected Chromaticity(int value)
Construct a new chromaticity enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class Chromaticity.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class Chromaticity.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class Chromaticity, the category is the class Chromaticity itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class Chromaticity, the category name is "chromaticity".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.print.attribute.standard.Chromaticity

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.Chromaticity

Packages that use Chromaticity
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of Chromaticity in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as Chromaticity
static Chromaticity | Chromaticity.COLOR Color printing.
static Chromaticity | Chromaticity.MONOCHROME Monochrome printing.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.ColorSupported

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.ColorSupported

Packages that use ColorSupported
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of ColorSupported in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as ColorSupported
static ColorSupported | ColorSupported.NOT_SUPPORTED The printer is not capable of any type of color printing.
static ColorSupported | ColorSupported.SUPPORTED The printer is capable of some type of color printing, such as highlight color or full process color.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.Compression

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.Compression

Packages that use Compression
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of Compression in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as Compression
static Compression | Compression.COMPRESS UNIX compression technology.
static Compression | Compression.DEFLATE ZIP public domain inflate/deflate compression technology.
static Compression | Compression.GZIP GNU zip compression technology described in RFC 1952.
static Compression | Compression.NONE No compression is used.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.Copies

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.Copies

No usage of javax.print.attribute.standard.Copies

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.CopiesSupported

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.CopiesSupported

No usage of javax.print.attribute.standard.CopiesSupported

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.DateTimeAtCompleted

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.DateTimeAtCompleted

No usage of javax.print.attribute.standard.DateTimeAtCompleted

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.DateTimeAtCreation

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.DateTimeAtCreation

No usage of javax.print.attribute.standard.DateTimeAtCreation

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.DateTimeAtProcessing

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.DateTimeAtProcessing

No usage of javax.print.attribute.standard.DateTimeAtProcessing

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.Destination

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.Destination

No usage of javax.print.attribute.standard.Destination

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.DocumentName

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.DocumentName

No usage of javax.print.attribute.standard.DocumentName

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.Fidelity

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.Fidelity

Packages that use Fidelity
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of Fidelity in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as Fidelity
static Fidelity | Fidelity.FIDELITY_FALSE The printer should make reasonable attempts to print the job, even if it cannot print it exactly as specified.
static Fidelity | Fidelity.FIDELITY_TRUE The job must be printed exactly as specified.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.Finishings

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.Finishings

Packages that use Finishings
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of Finishings in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as Finishings
static Finishings | Finishings.BIND This value indicates that a binding is to be applied to the document; the type and placement of the binding is site-defined.
static Finishings | Finishings.COVER This value is specified when it is desired to select a non-printed (or pre-printed) cover for the document.
static Finishings | Finishings.EDGE_STITCH Bind the document(s) with one or more staples (wire stitches) along one edge.
static Finishings | Finishings.EDGE_STITCH_BOTTOM Bind the document(s) with one or more staples (wire stitches) along the bottom edge.
static Finishings | Finishings.EDGE_STITCH_LEFT Bind the document(s) with one or more staples (wire stitches) along the left edge.
static Finishings | Finishings.EDGE_STITCH_RIGHT Bind the document(s) with one or more staples (wire stitches) along the right edge.
static Finishings | Finishings.EDGE_STITCH_TOP Bind the document(s) with one or more staples (wire stitches) along the top edge.
static Finishings | Finishings.NONE Perform no binding.
static Finishings | Finishings.SADDLE_STITCH Bind the document(s) with one or more staples (wire stitches) along the middle fold.
static Finishings | Finishings.STAPLE Bind the document(s) with one or more staples.
static Finishings | Finishings.STAPLE_BOTTOM_LEFT Bind the document(s) with one or more staples in the bottom left corner.
static Finishings | Finishings.STAPLE_BOTTOM_RIGHT Bind the document(s) with one or more staples in the bottom right corner.
static Finishings | Finishings.STAPLE_DUAL_BOTTOM Bind the document(s) with two staples (wire stitches) along the bottom edge assuming a portrait document (see above).
static Finishings | Finishings.STAPLE_DUAL_LEFT Bind the document(s) with two staples (wire stitches) along the left edge assuming a portrait document (see above).
static Finishings | Finishings.STAPLE_DUAL_RIGHT Bind the document(s) with two staples (wire stitches) along the right edge assuming a portrait document (see above).
static Finishings | Finishings.STAPLE_DUAL_TOP Bind the document(s) with two staples (wire stitches) along the top edge assuming a portrait document (see above).
static Finishings | Finishings.STAPLE_TOP_LEFT Bind the document(s) with one or more staples in the top left corner.
static Finishings | Finishings.STAPLE_TOP_RIGHT Bind the document(s) with one or more staples in the top right corner.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobHoldUntil

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobHoldUntil

No usage of javax.print.attribute.standard.JobHoldUntil

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobImpressions

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobImpressions

No usage of javax.print.attribute.standard.JobImpressions

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobImpressionsCompleted

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobImpressionsCompleted

No usage of javax.print.attribute.standard.JobImpressionsCompleted

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobImpressionsSupported

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobImpressionsSupported

No usage of javax.print.attribute.standard.JobImpressionsSupported

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobKOctets

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobKOctets

No usage of javax.print.attribute.standard.JobKOctets

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobKOctetsProcessed

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobKOctetsProcessed

No usage of javax.print.attribute.standard.JobKOctetsProcessed

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobKOctetsSupported

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobKOctetsSupported

No usage of javax.print.attribute.standard.JobKOctetsSupported

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobMediaSheets

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobMediaSheets

No usage of javax.print.attribute.standard.JobMediaSheets

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobMediaSheetsCompleted

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobMediaSheetsCompleted

No usage of javax.print.attribute.standard.JobMediaSheetsCompleted

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobMediaSheetsSupported

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobMediaSheetsSupported

No usage of javax.print.attribute.standard.JobMediaSheetsSupported

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobMessageFromOperator

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobMessageFromOperator

No usage of javax.print.attribute.standard.JobMessageFromOperator

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobName

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobName

No usage of javax.print.attribute.standard.JobName

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobOriginatingUserName

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobOriginatingUserName

No usage of javax.print.attribute.standard.JobOriginatingUserName

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobPriority

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobPriority

No usage of javax.print.attribute.standard.JobPriority

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobPrioritySupported

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobPrioritySupported

No usage of javax.print.attribute.standard.JobPrioritySupported

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobSheets

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobSheets

Packages that use JobSheets
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of JobSheets in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as JobSheets
static JobSheets | JobSheets.NONE No job sheets are printed.
static JobSheets | JobSheets.STANDARD One or more site specific standard job sheets are printed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobState

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobState

Packages that use JobState
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of JobState in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as JobState
static JobState | JobState.ABORTED The job has been aborted by the system (usually while the job was in the PROCESSING or PROCESSING_STOPPED state), the printer has completed aborting the job, and all job status attributes have reached their final values for the job.
static JobState | JobState.CANCELED The job has been canceled by some human agency, the printer has completed canceling the job, and all job status attributes have reached their final values for the job.
static JobState | JobState.COMPLETED The job has completed successfully or with warnings or errors after processing, all of the job media sheets have been successfully stacked in the appropriate output bin(s), and all job status attributes have reached their final values for the job.
static JobState | JobState.PENDING The job is a candidate to start processing, but is not yet processing.
static JobState | JobState.PENDING_HELD The job is not a candidate for processing for any number of reasons but will return to the PENDING state as soon as the reasons are no longer present.
static JobState | JobState.PROCESSING The job is processing.
static JobState | JobState.PROCESSING_STOPPED The job has stopped while processing for any number of reasons and will return to the PROCESSING state as soon as the reasons are no longer present.
static JobState | JobState.UNKNOWN The job state is unknown.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobStateReason

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobStateReason

Packages that use JobStateReason
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of JobStateReason in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as JobStateReason
static JobStateReason | JobStateReason.ABORTED_BY_SYSTEM The job was aborted by the system.
static JobStateReason | JobStateReason.COMPRESSION_ERROR The job was aborted by the system because the printer encountered an error in the document data while decompressing it.
static JobStateReason | JobStateReason.DOCUMENT_ACCESS_ERROR The Printer could not access one or more documents passed by reference (i.e., the print data representation object is a URL).
static JobStateReason | JobStateReason.DOCUMENT_FORMAT_ERROR The job was aborted by the system because the printer encountered an error in the document data while processing it.
static JobStateReason | JobStateReason.JOB_CANCELED_AT_DEVICE The job was canceled by an unidentified local user, i.e., a user at a console at the device.
static JobStateReason | JobStateReason.JOB_CANCELED_BY_OPERATOR The job was canceled by the operator, i.e., by a user who has been authenticated as having operator privileges (whether local or remote).
static JobStateReason | JobStateReason.JOB_CANCELED_BY_USER The job was canceled by the owner of the job, i.e., by a user whose authenticated identity is the same as the value of the originating user that created the Print Job, or by some other authorized end-user, such as a member of the job owner's security group.
static JobStateReason | JobStateReason.JOB_COMPLETED_SUCCESSFULLY The job completed successfully.
static JobStateReason | JobStateReason.JOB_COMPLETED_WITH_ERRORS The job completed with errors (and possibly warnings too).
static JobStateReason | JobStateReason.JOB_COMPLETED_WITH_WARNINGS The job completed with warnings.
static JobStateReason | JobStateReason.JOB_DATA_INSUFFICIENT The printer has created the Print Job, but the printer is expecting additional print data before it can move the job into the PROCESSING state.
static JobStateReason | JobStateReason.JOB_HOLD_UNTIL_SPECIFIED The value of the job's JobHoldUntil attribute was specified with a date-time that is still in the future.
static JobStateReason | JobStateReason.JOB_INCOMING The printer has created the Print Job, but the printer has not finished accessing or accepting all the print data yet.
static JobStateReason | JobStateReason.JOB_INTERPRETING The job is in the PROCESSING state, but more specifically, the printer ia interpreting the document data.
static JobStateReason | JobStateReason.JOB_OUTGOING The printer is transmitting the job to the output device.
static JobStateReason | JobStateReason.JOB_PRINTING The output device is marking media.
static JobStateReason | JobStateReason.JOB_QUEUED The job is in the PROCESSING state, but more specifically, the printer has queued the document data.
static JobStateReason | JobStateReason.JOB_QUEUED_FOR_MARKER The job is in the PENDING_HELD, PENDING, or PROCESSING state, but more specifically, the printer has completed enough processing of the document to be able to start marking and the job is waiting for the marker.
static JobStateReason | JobStateReason.JOB_RESTARTABLE This job is retained and is currently able to be restarted.
static JobStateReason | JobStateReason.JOB_TRANSFORMING The job is in the PROCESSING state, but more specifically, the printer is interpreting document data and producing another electronic representation.
static JobStateReason | JobStateReason.PRINTER_STOPPED The value of the printer's PrinterState attribute ia STOPPED.
static JobStateReason | JobStateReason.PRINTER_STOPPED_PARTLY The value of the printer's PrinterStateReasons attribute contains a PrinterStateReason value of STOPPED_PARTLY.
static JobStateReason | JobStateReason.PROCESSING_TO_STOP_POINT The requester has canceled the job or the printer has aborted the job, but the printer is still performing some actions on the job until a specified stop point occurs or job termination/cleanup is completed.
static JobStateReason | JobStateReason.QUEUED_IN_DEVICE The job has been forwarded to a device or print system that is unable to send back status.
static JobStateReason | JobStateReason.RESOURCES_ARE_NOT_READY At least one of the resources needed by the job, such as media, fonts, resource objects, etc., is not ready on any of the physical printers for which the job is a candidate.
static JobStateReason | JobStateReason.SERVICE_OFF_LINE The printer is off-line and accepting no jobs.
static JobStateReason | JobStateReason.SUBMISSION_INTERRUPTED The job was not completely submitted for some unforeseen reason.
static JobStateReason | JobStateReason.UNSUPPORTED_COMPRESSION The job was aborted by the system because the printer determined while attempting to decompress the document's data that the compression is actually not among those supported by the printer.
static JobStateReason | JobStateReason.UNSUPPORTED_DOCUMENT_FORMAT The job was aborted by the system because the document data's document format (doc flavor) is not among those supported by the printer.

Methods in javax.print.attribute.standard with parameters of type JobStateReason
 boolean JobStateReasons.add(JobStateReason o)
Adds the specified element to this job state reasons attribute if it is not already present.

Constructor parameters in javax.print.attribute.standard with type arguments of type JobStateReason
JobStateReasons(Collection<JobStateReason> collection)
Construct a new job state reasons attribute that contains the same JobStateReason objects as the given collection.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.JobStateReasons

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.JobStateReasons

No usage of javax.print.attribute.standard.JobStateReasons

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.Media

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.Media

Packages that use Media
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of Media in javax.print.attribute.standard

Subclasses of Media in javax.print.attribute.standard
class | MediaName Class MediaName is a subclass of Media, a printing attribute class (an enumeration) that specifies the media for a print job as a name.
class | MediaSizeName Class MediaSizeName is a subclass of Media.
class | MediaTray Class MediaTray is a subclass of Media.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.MediaName

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.MediaName

Packages that use MediaName
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of MediaName in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as MediaName
static MediaName | MediaName.ISO_A4_TRANSPARENT A4 transparency.
static MediaName | MediaName.ISO_A4_WHITE white A4 paper.
static MediaName | MediaName.NA_LETTER_TRANSPARENT letter transparency.
static MediaName | MediaName.NA_LETTER_WHITE white letter paper.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.MediaPrintableArea

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.MediaPrintableArea

No usage of javax.print.attribute.standard.MediaPrintableArea

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.MediaSize

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.MediaSize

Packages that use MediaSize
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of MediaSize in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as MediaSize
static MediaSize | MediaSize.Engineering.A Specifies the engineering A size, 8.5 inch by 11 inch.
static MediaSize | MediaSize.ISO.A0 Specifies the ISO A0 size, 841 mm by 1189 mm.
static MediaSize | MediaSize.ISO.A1 Specifies the ISO A1 size, 594 mm by 841 mm.
static MediaSize | MediaSize.ISO.A10 Specifies the ISO A10 size, 26 mm by 37 mm.
static MediaSize | MediaSize.ISO.A2 Specifies the ISO A2 size, 420 mm by 594 mm.
static MediaSize | MediaSize.ISO.A3 Specifies the ISO A3 size, 297 mm by 420 mm.
static MediaSize | MediaSize.ISO.A4 Specifies the ISO A4 size, 210 mm by 297 mm.
static MediaSize | MediaSize.ISO.A5 Specifies the ISO A5 size, 148 mm by 210 mm.
static MediaSize | MediaSize.ISO.A6 Specifies the ISO A6 size, 105 mm by 148 mm.
static MediaSize | MediaSize.ISO.A7 Specifies the ISO A7 size, 74 mm by 105 mm.
static MediaSize | MediaSize.ISO.A8 Specifies the ISO A8 size, 52 mm by 74 mm.
static MediaSize | MediaSize.ISO.A9 Specifies the ISO A9 size, 37 mm by 52 mm.
static MediaSize | MediaSize.Engineering.B Specifies the engineering B size, 11 inch by 17 inch.
static MediaSize | MediaSize.ISO.B0 Specifies the ISO B0 size, 1000 mm by 1414 mm.
static MediaSize | MediaSize.JIS.B0 Specifies the JIS B0 size, 1030 mm by 1456 mm.
static MediaSize | MediaSize.ISO.B1 Specifies the ISO B1 size, 707 mm by 1000 mm.
static MediaSize | MediaSize.JIS.B1 Specifies the JIS B1 size, 728 mm by 1030 mm.
static MediaSize | MediaSize.ISO.B10 Specifies the ISO B10 size, 31 mm by 44 mm.
static MediaSize | MediaSize.JIS.B10 Specifies the JIS B10 size, 32 mm by 45 mm.
static MediaSize | MediaSize.ISO.B2 Specifies the ISO B2 size, 500 mm by 707 mm.
static MediaSize | MediaSize.JIS.B2 Specifies the JIS B2 size, 515 mm by 728 mm.
static MediaSize | MediaSize.ISO.B3 Specifies the ISO B3 size, 353 mm by 500 mm.
static MediaSize | MediaSize.JIS.B3 Specifies the JIS B3 size, 364 mm by 515 mm.
static MediaSize | MediaSize.ISO.B4 Specifies the ISO B4 size, 250 mm by 353 mm.
static MediaSize | MediaSize.JIS.B4 Specifies the JIS B4 size, 257 mm by 364 mm.
static MediaSize | MediaSize.ISO.B5 Specifies the ISO B5 size, 176 mm by 250 mm.
static MediaSize | MediaSize.JIS.B5 Specifies the JIS B5 size, 182 mm by 257 mm.
static MediaSize | MediaSize.ISO.B6 Specifies the ISO B6 size, 125 mm by 176 mm.
static MediaSize | MediaSize.JIS.B6 Specifies the JIS B6 size, 128 mm by 182 mm.
static MediaSize | MediaSize.ISO.B7 Specifies the ISO B7 size, 88 mm by 125 mm.
static MediaSize | MediaSize.JIS.B7 Specifies the JIS B7 size, 91 mm by 128 mm.
static MediaSize | MediaSize.ISO.B8 Specifies the ISO B8 size, 62 mm by 88 mm.
static MediaSize | MediaSize.JIS.B8 Specifies the JIS B8 size, 64 mm by 91 mm.
static MediaSize | MediaSize.ISO.B9 Specifies the ISO B9 size, 44 mm by 62 mm.
static MediaSize | MediaSize.JIS.B9 Specifies the JIS B9 size, 45 mm by 64 mm.
static MediaSize | MediaSize.Engineering.C Specifies the engineering C size, 17 inch by 22 inch.
static MediaSize | MediaSize.ISO.C3 Specifies the ISO C3 size, 324 mm by 458 mm.
static MediaSize | MediaSize.ISO.C4 Specifies the ISO C4 size, 229 mm by 324 mm.
static MediaSize | MediaSize.ISO.C5 Specifies the ISO C5 size, 162 mm by 229 mm.
static MediaSize | MediaSize.ISO.C6 Specifies the ISO C6 size, 114 mm by 162 mm.
static MediaSize | MediaSize.JIS.CHOU_1 Specifies the JIS Chou ("long") #1 envelope size, 142 mm by 332 mm.
static MediaSize | MediaSize.JIS.CHOU_2 Specifies the JIS Chou ("long") #2 envelope size, 119 mm by 277 mm.
static MediaSize | MediaSize.JIS.CHOU_3 Specifies the JIS Chou ("long") #3 envelope size, 120 mm by 235 mm.
static MediaSize | MediaSize.JIS.CHOU_30 Specifies the JIS Chou ("long") #30 envelope size, 92 mm by 235 mm.
static MediaSize | MediaSize.JIS.CHOU_4 Specifies the JIS Chou ("long") #4 envelope size, 90 mm by 205 mm.
static MediaSize | MediaSize.JIS.CHOU_40 Specifies the JIS Chou ("long") #40 envelope size, 90 mm by 225 mm.
static MediaSize | MediaSize.Engineering.D Specifies the engineering D size, 22 inch by 34 inch.
static MediaSize | MediaSize.ISO.DESIGNATED_LONG Specifies the ISO Designated Long size, 110 mm by 220 mm.
static MediaSize | MediaSize.Engineering.E Specifies the engineering E size, 34 inch by 44 inch.
static MediaSize | MediaSize.Other.EXECUTIVE Specifies the executive size, 7.25 inches by 10.5 inches.
static MediaSize | MediaSize.Other.FOLIO Specifies the folio size, 8.5 inches by 13 inches.
static MediaSize | MediaSize.Other.INVOICE Specifies the invoice size, 5.5 inches by 8.5 inches.
static MediaSize | MediaSize.Other.ITALY_ENVELOPE Specifies the Italy envelope size, 110 mm by 230 mm.
static MediaSize | MediaSize.Other.JAPANESE_DOUBLE_POSTCARD Specifies the Japanese Double postcard size, 148 mm by 200 mm.
static MediaSize | MediaSize.Other.JAPANESE_POSTCARD Specifies the Japanese postcard size, 100 mm by 148 mm.
static MediaSize | MediaSize.JIS.KAKU_0 Specifies the JIS Kaku ("square") #0 envelope size, 287 mm by 382 mm.
static MediaSize | MediaSize.JIS.KAKU_1 Specifies the JIS Kaku ("square") #1 envelope size, 270 mm by 382 mm.
static MediaSize | MediaSize.JIS.KAKU_2 Specifies the JIS Kaku ("square") #2 envelope size, 240 mm by 332 mm.
static MediaSize | MediaSize.JIS.KAKU_20 Specifies the JIS Kaku ("square") #20 envelope size, 229 mm by 324 mm.
static MediaSize | MediaSize.JIS.KAKU_3 Specifies the JIS Kaku ("square") #3 envelope size, 216 mm by 277 mm.
static MediaSize | MediaSize.JIS.KAKU_4 Specifies the JIS Kaku ("square") #4 envelope size, 197 mm by 267 mm.
static MediaSize | MediaSize.JIS.KAKU_5 Specifies the JIS Kaku ("square") #5 envelope size, 190 mm by 240 mm.
static MediaSize | MediaSize.JIS.KAKU_6 Specifies the JIS Kaku ("square") #6 envelope size, 162 mm by 229 mm.
static MediaSize | MediaSize.JIS.KAKU_7 Specifies the JIS Kaku ("square") #7 envelope size, 142 mm by 205 mm.
static MediaSize | MediaSize.JIS.KAKU_8 Specifies the JIS Kaku ("square") #8 envelope size, 119 mm by 197 mm.
static MediaSize | MediaSize.JIS.KAKU_A4 Specifies the JIS Kaku ("square") A4 envelope size, 228 mm by 312 mm.
static MediaSize | MediaSize.Other.LEDGER Specifies the ledger size, 11 inches by 17 inches.
static MediaSize | MediaSize.NA.LEGAL Specifies the North American legal size, 8.5 inches by 14 inches.
static MediaSize | MediaSize.NA.LETTER Specifies the North American letter size, 8.5 inches by 11 inches.
static MediaSize | MediaSize.Other.MONARCH_ENVELOPE Specifies the Monarch envelope size, 3.87 inch by 7.5 inch.
static MediaSize | MediaSize.NA.NA_10x13_ENVELOPE Specifies the North American 10 inch by 13 inch envelope size.
static MediaSize | MediaSize.NA.NA_10x14_ENVELOPE Specifies the North American 10 inch by 14 inch envelope size.
static MediaSize | MediaSize.NA.NA_10X15_ENVELOPE Specifies the North American 10 inch by 15 inch envelope size.
static MediaSize | MediaSize.NA.NA_5X7 Specifies the North American 5 inch by 7 inch paper.
static MediaSize | MediaSize.NA.NA_6X9_ENVELOPE Specifies the North American 6 inch by 9 inch envelope size.
static MediaSize | MediaSize.NA.NA_7X9_ENVELOPE Specifies the North American 7 inch by 9 inch envelope size.
static MediaSize | MediaSize.NA.NA_8X10 Specifies the North American 8 inch by 10 inch paper.
static MediaSize | MediaSize.NA.NA_9x11_ENVELOPE Specifies the North American 9 inch by 11 inch envelope size.
static MediaSize | MediaSize.NA.NA_9x12_ENVELOPE Specifies the North American 9 inch by 12 inch envelope size.
static MediaSize | MediaSize.NA.NA_NUMBER_10_ENVELOPE Specifies the North American Number 10 business envelope size, 4.125 inches by 9.5 inches.
static MediaSize | MediaSize.NA.NA_NUMBER_11_ENVELOPE Specifies the North American Number 11 business envelope size, 4.5 inches by 10.375 inches.
static MediaSize | MediaSize.NA.NA_NUMBER_12_ENVELOPE Specifies the North American Number 12 business envelope size, 4.75 inches by 11 inches.
static MediaSize | MediaSize.NA.NA_NUMBER_14_ENVELOPE Specifies the North American Number 14 business envelope size, 5 inches by 11.5 inches.
static MediaSize | MediaSize.NA.NA_NUMBER_9_ENVELOPE Specifies the North American Number 9 business envelope size, 3.875 inches by 8.875 inches.
static MediaSize | MediaSize.Other.PERSONAL_ENVELOPE Specifies the Personal envelope size, 3.625 inch by 6.5 inch.
static MediaSize | MediaSize.Other.QUARTO Specifies the quarto size, 8.5 inches by 10.83 inches.
static MediaSize | MediaSize.Other.TABLOID Specifies the tabloid size, 11 inches by 17 inches.
static MediaSize | MediaSize.JIS.YOU_1 Specifies the JIS You ("Western") #1 envelope size, 120 mm by 176 mm.
static MediaSize | MediaSize.JIS.YOU_2 Specifies the JIS You ("Western") #2 envelope size, 114 mm by 162 mm.
static MediaSize | MediaSize.JIS.YOU_3 Specifies the JIS You ("Western") #3 envelope size, 98 mm by 148 mm.
static MediaSize | MediaSize.JIS.YOU_4 Specifies the JIS You ("Western") #4 envelope size, 105 mm by 235 mm.
static MediaSize | MediaSize.JIS.YOU_5 Specifies the JIS You ("Western") #5 envelope size, 95 mm by 217 mm.
static MediaSize | MediaSize.JIS.YOU_6 Specifies the JIS You ("Western") #6 envelope size, 98 mm by 190 mm.
static MediaSize | MediaSize.JIS.YOU_7 Specifies the JIS You ("Western") #7 envelope size, 92 mm by 165 mm.

Methods in javax.print.attribute.standard that return MediaSize
static MediaSize MediaSize.getMediaSizeForName(MediaSizeName media)
Get the MediaSize for the specified named media.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.MediaSize.Engineering

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.MediaSize.Engineering

No usage of javax.print.attribute.standard.MediaSize.Engineering

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.MediaSize.ISO

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.MediaSize.ISO

No usage of javax.print.attribute.standard.MediaSize.ISO

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.MediaSize.JIS

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.MediaSize.JIS

No usage of javax.print.attribute.standard.MediaSize.JIS

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.MediaSize.NA

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.MediaSize.NA

No usage of javax.print.attribute.standard.MediaSize.NA

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.MediaSize.Other

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.MediaSize.Other

No usage of javax.print.attribute.standard.MediaSize.Other

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.MediaSizeName

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.MediaSizeName

Packages that use MediaSizeName
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of MediaSizeName in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as MediaSizeName
static MediaSizeName | MediaSizeName.A A size .
static MediaSizeName | MediaSizeName.B B size .
static MediaSizeName | MediaSizeName.C C size .
static MediaSizeName | MediaSizeName.D D size .
static MediaSizeName | MediaSizeName.E E size .
static MediaSizeName | MediaSizeName.EXECUTIVE executive size .
static MediaSizeName | MediaSizeName.FOLIO folio size .
static MediaSizeName | MediaSizeName.INVOICE invoice size .
static MediaSizeName | MediaSizeName.ISO_A0 A0 size.
static MediaSizeName | MediaSizeName.ISO_A1 A1 size.
static MediaSizeName | MediaSizeName.ISO_A10 A10 size.
static MediaSizeName | MediaSizeName.ISO_A2 A2 size.
static MediaSizeName | MediaSizeName.ISO_A3 A3 size.
static MediaSizeName | MediaSizeName.ISO_A4 A4 size.
static MediaSizeName | MediaSizeName.ISO_A5 A5 size.
static MediaSizeName | MediaSizeName.ISO_A6 A6 size.
static MediaSizeName | MediaSizeName.ISO_A7 A7 size.
static MediaSizeName | MediaSizeName.ISO_A8 A8 size.
static MediaSizeName | MediaSizeName.ISO_A9 A9 size.
static MediaSizeName | MediaSizeName.ISO_B0 ISO B0 size.
static MediaSizeName | MediaSizeName.ISO_B1 ISO B1 size.
static MediaSizeName | MediaSizeName.ISO_B10 ISO B10 size.
static MediaSizeName | MediaSizeName.ISO_B2 ISO B2 size.
static MediaSizeName | MediaSizeName.ISO_B3 ISO B3 size.
static MediaSizeName | MediaSizeName.ISO_B4 ISO B4 size.
static MediaSizeName | MediaSizeName.ISO_B5 ISO B5 size.
static MediaSizeName | MediaSizeName.ISO_B6 ISO B6 size.
static MediaSizeName | MediaSizeName.ISO_B7 ISO B7 size.
static MediaSizeName | MediaSizeName.ISO_B8 ISO B8 size.
static MediaSizeName | MediaSizeName.ISO_B9 ISO B9 size.
static MediaSizeName | MediaSizeName.ISO_C0 ISO C0 size.
static MediaSizeName | MediaSizeName.ISO_C1 ISO C1 size.
static MediaSizeName | MediaSizeName.ISO_C2 ISO C2 size.
static MediaSizeName | MediaSizeName.ISO_C3 ISO C3 size.
static MediaSizeName | MediaSizeName.ISO_C4 ISO C4 size.
static MediaSizeName | MediaSizeName.ISO_C5 ISO C5 size.
static MediaSizeName | MediaSizeName.ISO_C6 letter size.
static MediaSizeName | MediaSizeName.ISO_DESIGNATED_LONG ISO designated long size .
static MediaSizeName | MediaSizeName.ITALY_ENVELOPE Italy envelope size .
static MediaSizeName | MediaSizeName.JAPANESE_DOUBLE_POSTCARD Japanese Double Postcard size.
static MediaSizeName | MediaSizeName.JAPANESE_POSTCARD Japanese Postcard size.
static MediaSizeName | MediaSizeName.JIS_B0 JIS B0 size.
static MediaSizeName | MediaSizeName.JIS_B1 JIS B1 size.
static MediaSizeName | MediaSizeName.JIS_B10 JIS B10 size.
static MediaSizeName | MediaSizeName.JIS_B2 JIS B2 size.
static MediaSizeName | MediaSizeName.JIS_B3 JIS B3 size.
static MediaSizeName | MediaSizeName.JIS_B4 JIS B4 size.
static MediaSizeName | MediaSizeName.JIS_B5 JIS B5 size.
static MediaSizeName | MediaSizeName.JIS_B6 JIS B6 size.
static MediaSizeName | MediaSizeName.JIS_B7 JIS B7 size.
static MediaSizeName | MediaSizeName.JIS_B8 JIS B8 size.
static MediaSizeName | MediaSizeName.JIS_B9 JIS B9 size.
static MediaSizeName | MediaSizeName.LEDGER ledger size .
static MediaSizeName | MediaSizeName.MONARCH_ENVELOPE monarch envelope size .
static MediaSizeName | MediaSizeName.NA_10X13_ENVELOPE 10x13 North American envelope size .
static MediaSizeName | MediaSizeName.NA_10X14_ENVELOPE 10x14North American envelope size .
static MediaSizeName | MediaSizeName.NA_10X15_ENVELOPE 10x15 North American envelope size.
static MediaSizeName | MediaSizeName.NA_5X7 5x7 North American paper.
static MediaSizeName | MediaSizeName.NA_6X9_ENVELOPE 6x9 North American envelope size.
static MediaSizeName | MediaSizeName.NA_7X9_ENVELOPE 7x9 North American envelope size.
static MediaSizeName | MediaSizeName.NA_8X10 8x10 North American paper.
static MediaSizeName | MediaSizeName.NA_9X11_ENVELOPE 9x11 North American envelope size.
static MediaSizeName | MediaSizeName.NA_9X12_ENVELOPE 9x12 North American envelope size.
static MediaSizeName | MediaSizeName.NA_LEGAL legal size .
static MediaSizeName | MediaSizeName.NA_LETTER letter size.
static MediaSizeName | MediaSizeName.NA_NUMBER_10_ENVELOPE number 10 envelope size .
static MediaSizeName | MediaSizeName.NA_NUMBER_11_ENVELOPE number 11 envelope size .
static MediaSizeName | MediaSizeName.NA_NUMBER_12_ENVELOPE number 12 envelope size .
static MediaSizeName | MediaSizeName.NA_NUMBER_14_ENVELOPE number 14 envelope size .
static MediaSizeName | MediaSizeName.NA_NUMBER_9_ENVELOPE number 9 envelope size .
static MediaSizeName | MediaSizeName.PERSONAL_ENVELOPE personal envelope size .
static MediaSizeName | MediaSizeName.QUARTO quarto size .
static MediaSizeName | MediaSizeName.TABLOID tabloid size .

Methods in javax.print.attribute.standard that return MediaSizeName
static MediaSizeName | MediaSize.findMedia(float x, float y, int units) The specified dimensions are used to locate a matching MediaSize instance from amongst all the standard MediaSize instances.
MediaSizeName | MediaSize.getMediaSizeName() Get the media name, if any, for this size.

Methods in javax.print.attribute.standard with parameters of type MediaSizeName
static MediaSize MediaSize.getMediaSizeForName(MediaSizeName media)
Get the MediaSize for the specified named media.

Constructors in javax.print.attribute.standard with parameters of type MediaSizeName
MediaSize(float x, float y, int units, MediaSizeName media)
Construct a new media size attribute from the given floating-point values.
MediaSize(int x, int y, int units, MediaSizeName media)
Construct a new media size attribute from the given integer values.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.MediaTray

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.MediaTray

Packages that use MediaTray
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of MediaTray in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as MediaTray
static MediaTray | MediaTray.BOTTOM The bottom input tray in the printer.
static MediaTray | MediaTray.ENVELOPE The envelope input tray in the printer.
static MediaTray | MediaTray.LARGE_CAPACITY The large capacity input tray in the printer.
static MediaTray | MediaTray.MAIN The main input tray in the printer.
static MediaTray | MediaTray.MANUAL The manual feed input tray in the printer.
static MediaTray | MediaTray.MIDDLE The middle input tray in the printe.
static MediaTray | MediaTray.SIDE The side input tray.
static MediaTray | MediaTray.TOP The top input tray in the printer.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.MultipleDocumentHandling

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.MultipleDocumentHandling

Packages that use MultipleDocumentHandling
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of MultipleDocumentHandling in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as MultipleDocumentHandling
static MultipleDocumentHandling | MultipleDocumentHandling.SEPARATE_DOCUMENTS_COLLATED_COPIES Separate documents collated copies -- see above for further information.
static MultipleDocumentHandling | MultipleDocumentHandling.SEPARATE_DOCUMENTS_UNCOLLATED_COPIES Separate documents uncollated copies -- see above for further information.
static MultipleDocumentHandling | MultipleDocumentHandling.SINGLE_DOCUMENT Single document -- see above for further information.
static MultipleDocumentHandling | MultipleDocumentHandling.SINGLE_DOCUMENT_NEW_SHEET Single document new sheet -- see above for further information.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.NumberOfDocuments

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.NumberOfDocuments

No usage of javax.print.attribute.standard.NumberOfDocuments

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.NumberOfInterveningJobs

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.NumberOfInterveningJobs

No usage of javax.print.attribute.standard.NumberOfInterveningJobs

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.NumberUp

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.NumberUp

No usage of javax.print.attribute.standard.NumberUp

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.NumberUpSupported

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.NumberUpSupported

No usage of javax.print.attribute.standard.NumberUpSupported

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.OrientationRequested

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.OrientationRequested

Packages that use OrientationRequested
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of OrientationRequested in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as OrientationRequested
static OrientationRequested | OrientationRequested.LANDSCAPE The content will be imaged across the long edge of the medium.
static OrientationRequested | OrientationRequested.PORTRAIT The content will be imaged across the short edge of the medium.
static OrientationRequested | OrientationRequested.REVERSE_LANDSCAPE The content will be imaged across the long edge of the medium, but in the opposite manner from landscape.
static OrientationRequested | OrientationRequested.REVERSE_PORTRAIT The content will be imaged across the short edge of the medium, but in the opposite manner from portrait.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.OutputDeviceAssigned

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.OutputDeviceAssigned

No usage of javax.print.attribute.standard.OutputDeviceAssigned

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PageRanges

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PageRanges

No usage of javax.print.attribute.standard.PageRanges

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PagesPerMinute

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PagesPerMinute

No usage of javax.print.attribute.standard.PagesPerMinute

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PagesPerMinuteColor

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PagesPerMinuteColor

No usage of javax.print.attribute.standard.PagesPerMinuteColor

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PDLOverrideSupported

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PDLOverrideSupported

Packages that use PDLOverrideSupported
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of PDLOverrideSupported in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as PDLOverrideSupported
static PDLOverrideSupported | PDLOverrideSupported.ATTEMPTED The printer attempts to make the external job attribute values take precedence over embedded instructions in the documents' print data, however there is no guarantee.
static PDLOverrideSupported | PDLOverrideSupported.NOT_ATTEMPTED The printer makes no attempt to make the external job attribute values take precedence over embedded instructions in the documents' print data.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PresentationDirection

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PresentationDirection

Packages that use PresentationDirection
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of PresentationDirection in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as PresentationDirection
static PresentationDirection | PresentationDirection.TOBOTTOM_TOLEFT Pages are laid out in columns starting at the top right, proceeeding towards the bottom & left.
static PresentationDirection | PresentationDirection.TOBOTTOM_TORIGHT Pages are laid out in columns starting at the top left, proceeeding towards the bottom & right.
static PresentationDirection | PresentationDirection.TOLEFT_TOBOTTOM Pages are laid out in rows starting at the top right, proceeeding towards the left & bottom.
static PresentationDirection | PresentationDirection.TOLEFT_TOTOP Pages are laid out in rows starting at the bottom right, proceeeding towards the left & top.
static PresentationDirection | PresentationDirection.TORIGHT_TOBOTTOM Pages are laid out in rows starting at the top left, proceeeding towards the right & bottom.
static PresentationDirection | PresentationDirection.TORIGHT_TOTOP Pages are laid out in rows starting at the bottom left, proceeeding towards the right & top.
static PresentationDirection | PresentationDirection.TOTOP_TOLEFT Pages are laid out in columns starting at the bottom right, proceeeding towards the top & left.
static PresentationDirection | PresentationDirection.TOTOP_TORIGHT Pages are laid out in columns starting at the bottom left, proceeeding towards the top & right.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PrinterInfo

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PrinterInfo

No usage of javax.print.attribute.standard.PrinterInfo

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PrinterIsAcceptingJobs

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PrinterIsAcceptingJobs

Packages that use PrinterIsAcceptingJobs
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of PrinterIsAcceptingJobs in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as PrinterIsAcceptingJobs
static PrinterIsAcceptingJobs | PrinterIsAcceptingJobs.ACCEPTING_JOBS The printer is currently acccepting jobs.
static PrinterIsAcceptingJobs | PrinterIsAcceptingJobs.NOT_ACCEPTING_JOBS The printer is currently rejecting any jobs sent to it.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PrinterLocation

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PrinterLocation

No usage of javax.print.attribute.standard.PrinterLocation

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PrinterMakeAndModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PrinterMakeAndModel

No usage of javax.print.attribute.standard.PrinterMakeAndModel

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PrinterMessageFromOperator

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PrinterMessageFromOperator

No usage of javax.print.attribute.standard.PrinterMessageFromOperator

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PrinterMoreInfo

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PrinterMoreInfo

No usage of javax.print.attribute.standard.PrinterMoreInfo

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PrinterMoreInfoManufacturer

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PrinterMoreInfoManufacturer

No usage of javax.print.attribute.standard.PrinterMoreInfoManufacturer

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PrinterName

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PrinterName

No usage of javax.print.attribute.standard.PrinterName

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PrinterResolution

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PrinterResolution

No usage of javax.print.attribute.standard.PrinterResolution

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PrinterState

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PrinterState

Packages that use PrinterState
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of PrinterState in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as PrinterState
static PrinterState | PrinterState.IDLE Indicates that new jobs can start processing without waiting.
static PrinterState | PrinterState.PROCESSING Indicates that jobs are processing; new jobs will wait before processing.
static PrinterState | PrinterState.STOPPED Indicates that no jobs can be processed and intervention is required.
static PrinterState | PrinterState.UNKNOWN The printer state is unknown.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PrinterStateReason

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PrinterStateReason

Packages that use PrinterStateReason
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of PrinterStateReason in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as PrinterStateReason
static PrinterStateReason | PrinterStateReason.CONNECTING_TO_DEVICE The printer has scheduled a job on the output device and is in the process of connecting to a shared network output device (and might not be able to actually start printing the job for an arbitrarily long time depending on the usage of the output device by other servers on the network).
static PrinterStateReason | PrinterStateReason.COVER_OPEN One or more covers on the device are open.
static PrinterStateReason | PrinterStateReason.DEVELOPER_EMPTY The device is out of developer.
static PrinterStateReason | PrinterStateReason.DEVELOPER_LOW The device is low on developer.
static PrinterStateReason | PrinterStateReason.DOOR_OPEN One or more doors on the device are open.
static PrinterStateReason | PrinterStateReason.FUSER_OVER_TEMP The fuser temperature is above normal.
static PrinterStateReason | PrinterStateReason.FUSER_UNDER_TEMP The fuser temperature is below normal.
static PrinterStateReason | PrinterStateReason.INPUT_TRAY_MISSING One or more input trays are not in the device.
static PrinterStateReason | PrinterStateReason.INTERLOCK_OPEN One or more interlock devices on the printer are unlocked.
static PrinterStateReason | PrinterStateReason.INTERPRETER_RESOURCE_UNAVAILABLE An interpreter resource is unavailable (e.g., font, form).
static PrinterStateReason | PrinterStateReason.MARKER_SUPPLY_EMPTY The device is out of at least one marker supply (e.g.
static PrinterStateReason | PrinterStateReason.MARKER_SUPPLY_LOW The device is low on at least one marker supply (e.g.
static PrinterStateReason | PrinterStateReason.MARKER_WASTE_ALMOST_FULL The device marker supply waste receptacle is almost full.
static PrinterStateReason | PrinterStateReason.MARKER_WASTE_FULL The device marker supply waste receptacle is full.
static PrinterStateReason | PrinterStateReason.MEDIA_EMPTY At least one input tray is empty.
static PrinterStateReason | PrinterStateReason.MEDIA_JAM The device has a media jam.
static PrinterStateReason | PrinterStateReason.MEDIA_LOW At least one input tray is low on media.
static PrinterStateReason | PrinterStateReason.MEDIA_NEEDED A tray has run out of media.
static PrinterStateReason | PrinterStateReason.MOVING_TO_PAUSED Someone has paused the printer, but the device(s) are taking an appreciable time to stop.
static PrinterStateReason | PrinterStateReason.OPC_LIFE_OVER The optical photo conductor is no longer functioning.
static PrinterStateReason | PrinterStateReason.OPC_NEAR_EOL The optical photo conductor is near end of life.
static PrinterStateReason | PrinterStateReason.OTHER The printer has detected an error other than ones listed below.
static PrinterStateReason | PrinterStateReason.OUTPUT_AREA_ALMOST_FULL One or more output areas are almost full (e.g.
static PrinterStateReason | PrinterStateReason.OUTPUT_AREA_FULL One or more output areas are full (e.g.
static PrinterStateReason | PrinterStateReason.OUTPUT_TRAY_MISSING One or more output trays are not in the device.
static PrinterStateReason | PrinterStateReason.PAUSED Someone has paused the printer and the printer's PrinterState is STOPPED.
static PrinterStateReason | PrinterStateReason.SHUTDOWN Someone has removed a printer from service, and the device may be powered down or physically removed.
static PrinterStateReason | PrinterStateReason.SPOOL_AREA_FULL The limit of persistent storage allocated for spooling has been reached.
static PrinterStateReason | PrinterStateReason.STOPPED_PARTLY When a printer controls more than one output device, this reason indicates that one or more output devices are stopped.
static PrinterStateReason | PrinterStateReason.STOPPING The printer is in the process of stopping the device and will be stopped in a while.
static PrinterStateReason | PrinterStateReason.TIMED_OUT The server was able to connect to the output device (or is always connected), but was unable to get a response from the output device.
static PrinterStateReason | PrinterStateReason.TONER_EMPTY The device is out of toner.
static PrinterStateReason | PrinterStateReason.TONER_LOW The device is low on toner.

Methods in javax.print.attribute.standard that return types with arguments of type PrinterStateReason
 Set<PrinterStateReason> PrinterStateReasons.printerStateReasonSet(Severity severity)
Obtain an unmodifiable set view of the individual printer state reason attributes at the given severity level in this PrinterStateReasons attribute.

Methods in javax.print.attribute.standard with parameters of type PrinterStateReason
 Severity PrinterStateReasons.put(PrinterStateReason reason, Severity severity)
Adds the given printer state reason to this printer state reasons attribute, associating it with the given severity level.

Constructor parameters in javax.print.attribute.standard with type arguments of type PrinterStateReason
PrinterStateReasons(Map<PrinterStateReason,Severity> map)
Construct a new printer state reasons attribute that contains the same PrinterStateReason-to-Severity mappings as the given map.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PrinterStateReasons

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PrinterStateReasons

No usage of javax.print.attribute.standard.PrinterStateReasons

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PrinterURI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PrinterURI

No usage of javax.print.attribute.standard.PrinterURI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.PrintQuality

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.PrintQuality

Packages that use PrintQuality
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of PrintQuality in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as PrintQuality
static PrintQuality | PrintQuality.DRAFT Lowest quality available on the printer.
static PrintQuality | PrintQuality.HIGH Highest quality available on the printer.
static PrintQuality | PrintQuality.NORMAL Normal or intermediate quality on the printer.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.QueuedJobCount

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.QueuedJobCount

No usage of javax.print.attribute.standard.QueuedJobCount

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.ReferenceUriSchemesSupported

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.ReferenceUriSchemesSupported

Packages that use ReferenceUriSchemesSupported
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of ReferenceUriSchemesSupported in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as ReferenceUriSchemesSupported
static ReferenceUriSchemesSupported | ReferenceUriSchemesSupported.FILE Host-specific file names.
static ReferenceUriSchemesSupported | ReferenceUriSchemesSupported.FTP File Transfer Protocol (FTP).
static ReferenceUriSchemesSupported | ReferenceUriSchemesSupported.GOPHER Gopher Protocol.
static ReferenceUriSchemesSupported | ReferenceUriSchemesSupported.HTTP HyperText Transfer Protocol (HTTP).
static ReferenceUriSchemesSupported | ReferenceUriSchemesSupported.HTTPS Secure HyperText Transfer Protocol (HTTPS).
static ReferenceUriSchemesSupported | ReferenceUriSchemesSupported.NEWS USENET news.
static ReferenceUriSchemesSupported | ReferenceUriSchemesSupported.NNTP USENET news using Network News Transfer Protocol (NNTP).
static ReferenceUriSchemesSupported | ReferenceUriSchemesSupported.WAIS Wide Area Information Server (WAIS) protocol.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.RequestingUserName

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.RequestingUserName

No usage of javax.print.attribute.standard.RequestingUserName

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.Severity

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.Severity

Packages that use Severity
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of Severity in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as Severity
static Severity | Severity.ERROR Indicates that the PrinterStateReason is an "error" (most severe).
static Severity | Severity.REPORT Indicates that the PrinterStateReason is a "report" (least severe).
static Severity | Severity.WARNING Indicates that the PrinterStateReason is a "warning." An implementation may choose to omit some or all warnings.

Methods in javax.print.attribute.standard that return Severity
 Severity PrinterStateReasons.put(PrinterStateReason reason, Severity severity)
Adds the given printer state reason to this printer state reasons attribute, associating it with the given severity level.

Methods in javax.print.attribute.standard with parameters of type Severity
Set<PrinterStateReason> | PrinterStateReasons.printerStateReasonSet(Severity severity) Obtain an unmodifiable set view of the individual printer state reason attributes at the given severity level in this PrinterStateReasons attribute.
Severity | PrinterStateReasons.put(PrinterStateReason reason, Severity severity) Adds the given printer state reason to this printer state reasons attribute, associating it with the given severity level.

Constructor parameters in javax.print.attribute.standard with type arguments of type Severity
PrinterStateReasons(Map<PrinterStateReason,Severity> map)
Construct a new printer state reasons attribute that contains the same PrinterStateReason-to-Severity mappings as the given map.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.SheetCollate

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.SheetCollate

Packages that use SheetCollate
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of SheetCollate in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as SheetCollate
static SheetCollate | SheetCollate.COLLATED Sheets within a document appear in collated order when multiple copies are printed.
static SheetCollate | SheetCollate.UNCOLLATED Sheets within a document appear in uncollated order when multiple copies are printed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.attribute.standard.Sides

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.attribute.standard.Sides

Packages that use Sides
javax.print.attribute.standard Package javax.print.attribute.standard contains classes for specific printing attributes.

Uses of Sides in javax.print.attribute.standard

Fields in javax.print.attribute.standard declared as Sides
static Sides | Sides.DUPLEX An alias for "two sided long edge" (see TWO_SIDED_LONG_EDGE).
static Sides | Sides.ONE_SIDED Imposes each consecutive print-stream page upon the same side of consecutive media sheets.
static Sides | Sides.TUMBLE An alias for "two sided short edge" (see TWO_SIDED_SHORT_EDGE).
static Sides | Sides.TWO_SIDED_LONG_EDGE Imposes each consecutive pair of print-stream pages upon front and back sides of consecutive media sheets, such that the orientation of each pair of print-stream pages on the medium would be correct for the reader as if for binding on the long edge.
static Sides | Sides.TWO_SIDED_SHORT_EDGE Imposes each consecutive pair of print-stream pages upon front and back sides of consecutive media sheets, such that the orientation of each pair of print-stream pages on the medium would be correct for the reader as if for binding on the short edge.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ColorSupported

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class ColorSupported

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.ColorSupported
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintServiceAttribute
public final class ColorSupported
extends EnumSyntax
implements PrintServiceAttribute

Class ColorSupported is a printing attribute class, an enumeration, that identifies whether the device is capable of any type of color printing at all, including highlight color as well as full process color. All document instructions having to do with color are embedded within the print data (none are attributes attached to the job outside the print data).

Note: End users are able to determine the nature and details of the color support by querying the PrinterMoreInfoManufacturer attribute.

Don't confuse the ColorSupported attribute with the Chromaticity attribute. Chromaticity is an attribute the client can specify for a job to tell the printer whether to print a document in monochrome or color, possibly causing the printer to print a color document in monochrome. ColorSupported is a printer description attribute that tells whether the printer can print in color regardless of how the client specifies to print any particular document.

IPP Compatibility: The IPP boolean value is "true" for SUPPORTED and "false" for NOT_SUPPORTED. The category name returned by getName() is the IPP attribute name. The enumeration's integer value is the IPP enum value. The toString() method returns the IPP string representation of the attribute value.

See Also:
Serialized Form

Field Summary
static ColorSupported | NOT_SUPPORTED The printer is not capable of any type of color printing.
static ColorSupported | SUPPORTED The printer is capable of some type of color printing, such as highlight color or full process color.
Constructor Summary
protected ColorSupported(int value)
Construct a new color supported enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class ColorSupported.
String | getName() Get the name of the category of which this attribute value is an instance.
protected String[] | getStringTable() Returns the string table for class ColorSupported.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

NOT_SUPPORTED

public static final ColorSupported NOT_SUPPORTED
The printer is not capable of any type of color printing.

SUPPORTED

public static final ColorSupported SUPPORTED
The printer is capable of some type of color printing, such as highlight color or full process color.

Constructor Detail

ColorSupported

protected ColorSupported(int value)
Construct a new color supported enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class ColorSupported.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class ColorSupported.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class ColorSupported, the category is class ColorSupported itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class ColorSupported, the category name is "color-supported".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Compression

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class Compression

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.Compression
All Implemented Interfaces:
Serializable, Cloneable, Attribute, DocAttribute
public class Compression
extends EnumSyntax
implements DocAttribute

Class Compression is a printing attribute class, an enumeration, that specifies how print data is compressed. Compression is an attribute of the print data (the doc), not of the Print Job. If a Compression attribute is not specified for a doc, the printer assumes the doc's print data is uncompressed (i.e., the default Compression value is always NONE).

IPP Compatibility: The category name returned by getName() is the IPP attribute name. The enumeration's integer value is the IPP enum value. The toString() method returns the IPP string representation of the attribute value.

See Also:
Serialized Form

Field Summary
static Compression | COMPRESS UNIX compression technology.
static Compression | DEFLATE ZIP public domain inflate/deflate compression technology.
static Compression | GZIP GNU zip compression technology described in RFC 1952.
static Compression | NONE No compression is used.
Constructor Summary
protected Compression(int value)
Construct a new compression enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class Compression.
String | getName() Get the name of the category of which this attribute value is an instance.
protected String[] | getStringTable() Returns the string table for class Compression.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

NONE

public static final Compression NONE
No compression is used.

DEFLATE

public static final Compression DEFLATE
ZIP public domain inflate/deflate compression technology.

GZIP

public static final Compression GZIP
GNU zip compression technology described in RFC 1952.

COMPRESS

public static final Compression COMPRESS
UNIX compression technology.

Constructor Detail

Compression

protected Compression(int value)
Construct a new compression enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class Compression.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class Compression.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class Compression and any vendor-defined subclasses, the category is class Compression itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class Compression and any vendor-defined subclasses, the category name is "compression".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Copies

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class Copies

java.lang.Object
    extended by  javax.print.attribute.IntegerSyntax
        extended by  javax.print.attribute.standard.Copies
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute, PrintRequestAttribute
public final class Copies
extends IntegerSyntax
implements PrintRequestAttribute, PrintJobAttribute

Class Copies is an integer valued printing attribute class that specifies the number of copies to be printed.

On many devices the supported number of collated copies will be limited by the number of physical output bins on the device, and may be different from the number of uncollated copies which can be supported.

The effect of a Copies attribute with a value of n on a multidoc print job (a job with multiple documents) depends on the (perhaps defaulted) value of the MultipleDocumentHandling attribute:

  • SINGLE_DOCUMENT -- The result will be n copies of a single output document comprising all the input docs.

  • SINGLE_DOCUMENT_NEW_SHEET -- The result will be n copies of a single output document comprising all the input docs, and the first impression of each input doc will always start on a new media sheet.

  • SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- The result will be n copies of the first input document, followed by n copies of the second input document, . . . followed by n copies of the last input document.

  • SEPARATE_DOCUMENTS_COLLATED_COPIES -- The result will be the first input document, the second input document, . . . the last input document, the group of documents being repeated n times.

IPP Compatibility: The integer value gives the IPP integer value. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
Copies(int value)
Construct a new copies attribute with the given integer value.
Method Summary
boolean | equals(Object object) Returns whether this copies attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.IntegerSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Copies

public Copies(int value)
Construct a new copies attribute with the given integer value.

Parameters:
value - Integer value.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if value is less than 1.
Method Detail

equals

public boolean equals(Object object)
Returns whether this copies attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class Copies.
  3. This copies attribute's value and object's value are equal.

Overrides:
equals in class IntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this copies attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class Copies, the category is class Copies itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class Copies, the category name is "copies".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CopiesSupported

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class CopiesSupported

java.lang.Object
    extended by  javax.print.attribute.SetOfIntegerSyntax
        extended by  javax.print.attribute.standard.CopiesSupported
All Implemented Interfaces:
Serializable, Cloneable, Attribute, SupportedValuesAttribute
public final class CopiesSupported
extends SetOfIntegerSyntax
implements SupportedValuesAttribute

Class CopiesSupported is a printing attribute class, a set of integers, that gives the supported values for a Copies attribute. It is restricted to a single contiguous range of integers; multiple non-overlapping ranges are not allowed.

IPP Compatibility: The CopiesSupported attribute's canonical array form gives the lower and upper bound for the range of copies to be included in an IPP "copies-supported" attribute. See class SetOfIntegerSyntax for an explanation of canonical array form. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
CopiesSupported(int member)
Construct a new copies supported attribute containing a single integer.
CopiesSupported(int lowerBound, int upperBound)
Construct a new copies supported attribute containing a single range of integers.
Method Summary
boolean | equals(Object object) Returns whether this copies supported attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.SetOfIntegerSyntax
contains, contains, getMembers, hashCode, next, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

CopiesSupported

public CopiesSupported(int member)
Construct a new copies supported attribute containing a single integer. That is, only the one value of Copies is supported.

Parameters:
member - Set member.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if member is less than 1.

CopiesSupported

public CopiesSupported(int lowerBound,
                       int upperBound)
Construct a new copies supported attribute containing a single range of integers. That is, only those values of Copies in the one range are supported.

Parameters:
lowerBound - Lower bound of the range.
upperBound - Upper bound of the range.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if a null range is specified or if a non-null range is specified with lowerBound less than 1.
Method Detail

equals

public boolean equals(Object object)
Returns whether this copies supported attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class CopiesSupported.
  3. This copies supported attribute's members and object's members are the same.

Overrides:
equals in class SetOfIntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this copies supported attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class CopiesSupported, the category is class CopiesSupported itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class CopiesSupported, the category name is "copies-supported".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DateTimeAtCompleted

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class DateTimeAtCompleted

java.lang.Object
    extended by  javax.print.attribute.DateTimeSyntax
        extended by  javax.print.attribute.standard.DateTimeAtCompleted
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute
public final class DateTimeAtCompleted
extends DateTimeSyntax
implements PrintJobAttribute

Class DateTimeAtCompleted is a printing attribute class, a date-time attribute, that indicates the date and time at which the Print Job completed (or was canceled or aborted).

To construct a DateTimeAtCompleted attribute from separate values of the year, month, day, hour, minute, and so on, use a Calendar object to construct a Date object, then use the Date object to construct the DateTimeAtCompleted attribute. To convert a DateTimeAtCompleted attribute to separate values of the year, month, day, hour, minute, and so on, create a Calendar object and set it to the Date from the DateTimeAtCompleted attribute.

IPP Compatibility: The information needed to construct an IPP "date-time-at-completed" attribute can be obtained as described above. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
DateTimeAtCompleted(Date dateTime)
Construct a new date-time at completed attribute with the given Date value.
Method Summary
boolean | equals(Object object) Returns whether this date-time at completed attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.DateTimeSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DateTimeAtCompleted

public DateTimeAtCompleted(Date dateTime)
Construct a new date-time at completed attribute with the given Date value.

Parameters:
dateTime - Date value.
Throws:
NullPointerException - (unchecked exception) Thrown if dateTime is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this date-time at completed attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class DateTimeAtCompleted.
  3. This date-time at completed attribute's Date value and object's Date value are equal.

Overrides:
equals in class DateTimeSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this date-time at completed attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class DateTimeAtCompleted, the category is class DateTimeAtCompleted itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class DateTimeAtCompleted, the category name is "date-time-at-completed".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DateTimeAtCreation

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class DateTimeAtCreation

java.lang.Object
    extended by  javax.print.attribute.DateTimeSyntax
        extended by  javax.print.attribute.standard.DateTimeAtCreation
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute
public final class DateTimeAtCreation
extends DateTimeSyntax
implements PrintJobAttribute

Class DateTimeAtCreation is a printing attribute class, a date-time attribute, that indicates the date and time at which the Print Job was created.

To construct a DateTimeAtCreation attribute from separate values of the year, month, day, hour, minute, and so on, use a Calendar object to construct a Date object, then use the Date object to construct the DateTimeAtCreation attribute. To convert a DateTimeAtCreation attribute to separate values of the year, month, day, hour, minute, and so on, create a Calendar object and set it to the Date from the DateTimeAtCreation attribute.

IPP Compatibility: The information needed to construct an IPP "date-time-at-creation" attribute can be obtained as described above. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
DateTimeAtCreation(Date dateTime)
Construct a new date-time at creation attribute with the given Date value.
Method Summary
boolean | equals(Object object) Returns whether this date-time at creation attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.DateTimeSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DateTimeAtCreation

public DateTimeAtCreation(Date dateTime)
Construct a new date-time at creation attribute with the given Date value.

Parameters:
dateTime - Date value.
Throws:
NullPointerException - (unchecked exception) Thrown if dateTime is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this date-time at creation attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class DateTimeAtCreation.
  3. This date-time at creation attribute's Date value and object's Date value are equal.

Overrides:
equals in class DateTimeSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this date-time at creation attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class DateTimeAtCreation, the category is class DateTimeAtCreation itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class DateTimeAtCreation, the category name is "date-time-at-creation".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DateTimeAtProcessing

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class DateTimeAtProcessing

java.lang.Object
    extended by  javax.print.attribute.DateTimeSyntax
        extended by  javax.print.attribute.standard.DateTimeAtProcessing
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute
public final class DateTimeAtProcessing
extends DateTimeSyntax
implements PrintJobAttribute

Class DateTimeAtProcessing is a printing attribute class, a date-time attribute, that indicates the date and time at which the Print Job first began processing.

To construct a DateTimeAtProcessing attribute from separate values of the year, month, day, hour, minute, and so on, use a Calendar object to construct a Date object, then use the Date object to construct the DateTimeAtProcessing attribute. To convert a DateTimeAtProcessing attribute to separate values of the year, month, day, hour, minute, and so on, create a Calendar object and set it to the Date from the DateTimeAtProcessing attribute.

IPP Compatibility: The information needed to construct an IPP "date-time-at-processing" attribute can be obtained as described above. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
DateTimeAtProcessing(Date dateTime)
Construct a new date-time at processing attribute with the given Date value.
Method Summary
boolean | equals(Object object) Returns whether this date-time at processing attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.DateTimeSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DateTimeAtProcessing

public DateTimeAtProcessing(Date dateTime)
Construct a new date-time at processing attribute with the given Date value.

Parameters:
dateTime - Date value.
Throws:
NullPointerException - (unchecked exception) Thrown if dateTime is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this date-time at processing attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class DateTimeAtProcessing.
  3. This date-time at processing attribute's Date value and object's Date value are equal.

Overrides:
equals in class DateTimeSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this date-time at processing attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class DateTimeAtProcessing, the category is class DateTimeAtProcessing itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class DateTimeAtProcessing, the category name is "date-time-at-processing".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Destination

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class Destination

java.lang.Object
    extended by  javax.print.attribute.URISyntax
        extended by  javax.print.attribute.standard.Destination
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute, PrintRequestAttribute
public final class Destination
extends URISyntax
implements PrintJobAttribute, PrintRequestAttribute

Class Destination is a printing attribute class, a URI, that is used to indicate an alternate destination for the spooled printer formatted data. Many PrintServices will not support the notion of a destination other than the printer device, and so will not support this attribute.

A common use for this attribute will be applications which want to redirect output to a local disk file : eg."file:out.prn". Note that proper construction of "file:" scheme URI instances should be performed using the toURI() method of class File. See the documentation on that class for more information.

If a destination URI is specified in a PrintRequest and it is not accessible for output by the PrintService, a PrintException will be thrown. The PrintException may implement URIException to provide a more specific cause.

IPP Compatibility: Destination is not an IPP attribute.

See Also:
Serialized Form

Constructor Summary
Destination(URI uri)
Constructs a new destination attribute with the specified URI.
Method Summary
boolean | equals(Object object) Returns whether this destination attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.URISyntax
getURI, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Destination

public Destination(URI uri)
Constructs a new destination attribute with the specified URI.

Parameters:
uri - URI.
Throws:
NullPointerException - (unchecked exception) Thrown if uri is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this destination attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class Destination.
  3. This destination attribute's URI and object's URI are equal.

Overrides:
equals in class URISyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this destination attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class Destination, the category is class Destination itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class Destination, the category name is "spool-data-destination".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocumentName

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class DocumentName

java.lang.Object
    extended by  javax.print.attribute.TextSyntax
        extended by  javax.print.attribute.standard.DocumentName
All Implemented Interfaces:
Serializable, Cloneable, Attribute, DocAttribute
public final class DocumentName
extends TextSyntax
implements DocAttribute

Class DocumentName is a printing attribute class, a text attribute, that specifies the name of a document. DocumentName is an attribute of the print data (the doc), not of the Print Job. A document's name is an arbitrary string defined by the client. However if a JobName is not specified, the DocumentName should be used instead, which implies that supporting specification of DocumentName requires reporting of JobName and vice versa. See JobName for more information.

IPP Compatibility: The string value gives the IPP name value. The locale gives the IPP natural language. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
DocumentName(String documentName, Locale locale)
Constructs a new document name attribute with the given document name and locale.
Method Summary
boolean | equals(Object object) Returns whether this document name attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.TextSyntax
getLocale, getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DocumentName

public DocumentName(String documentName,
                    Locale locale)
Constructs a new document name attribute with the given document name and locale.

Parameters:
documentName - Document name.
locale - Natural language of the text string. null is interpreted to mean the default locale as returned by Locale.getDefault()
Throws:
NullPointerException - (unchecked exception) Thrown if documentName is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this document name attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class DocumentName.
  3. This document name attribute's underlying string and object's underlying string are equal.
  4. This document name attribute's locale and object's locale are equal.

Overrides:
equals in class TextSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this document name attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class DocumentName, the category is class DocumentName itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class DocumentName, the category name is "document-name".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Fidelity

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class Fidelity

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.Fidelity
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute, PrintRequestAttribute
public final class Fidelity
extends EnumSyntax
implements PrintJobAttribute, PrintRequestAttribute

Class Fidelity is a printing attribute class, an enumeration, that indicates whether total fidelity to client supplied print request attributes is required. If FIDELITY_TRUE is specified and a service cannot print the job exactly as specified it must reject the job. If FIDELITY_FALSE is specified a reasonable attempt to print the job is acceptable. If not supplied the default is FIDELITY_FALSE.

IPP Compatibility: The IPP boolean value is "true" for FIDELITY_TRUE and "false" for FIDELITY_FALSE. The category name returned by getName() is the IPP attribute name. The enumeration's integer value is the IPP enum value. The toString() method returns the IPP string representation of the attribute value. See RFC 2911 Section 15.1 for a fuller description of the IPP fidelity attribute.

See Also:
Serialized Form

Field Summary
static Fidelity | FIDELITY_FALSE The printer should make reasonable attempts to print the job, even if it cannot print it exactly as specified.
static Fidelity | FIDELITY_TRUE The job must be printed exactly as specified.
Constructor Summary
protected Fidelity(int value)
Construct a new fidelity enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class Fidelity.
String | getName() Get the name of the category of which this attribute value is an instance.
protected String[] | getStringTable() Returns the string table for class Fidelity.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

FIDELITY_TRUE

public static final Fidelity FIDELITY_TRUE
The job must be printed exactly as specified. or else rejected.

FIDELITY_FALSE

public static final Fidelity FIDELITY_FALSE
The printer should make reasonable attempts to print the job, even if it cannot print it exactly as specified.

Constructor Detail

Fidelity

protected Fidelity(int value)
Construct a new fidelity enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class Fidelity.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class Fidelity.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class Fidelity the category is class Fidelity itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class Fidelity the category name is "ipp-attribute-fidelity".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Finishings

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class Finishings

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.Finishings
All Implemented Interfaces:
Serializable, Cloneable, Attribute, DocAttribute, PrintJobAttribute, PrintRequestAttribute
public class Finishings
extends EnumSyntax
implements DocAttribute, PrintRequestAttribute, PrintJobAttribute

Class Finishings is a printing attribute class, an enumeration, that identifies whether the printer applies a finishing operation of some kind of binding to each copy of each printed document in the job. For multidoc print jobs (jobs with multiple documents), the MultipleDocumentHandling attribute determines what constitutes a "copy" for purposes of finishing.

Standard Finishings values are:
NONE | STAPLE | EDGE_STITCH
BIND | SADDLE_STITCH | COVER

The following Finishings values are more specific; they indicate a corner or an edge as if the document were a portrait document:
STAPLE_TOP_LEFT | EDGE_STITCH_LEFT | STAPLE_DUAL_LEFT
STAPLE_BOTTOM_LEFT | EDGE_STITCH_TOP | STAPLE_DUAL_TOP
STAPLE_TOP_RIGHT | EDGE_STITCH_RIGHT | STAPLE_DUAL_RIGHT
STAPLE_BOTTOM_RIGHT | EDGE_STITCH_BOTTOM | STAPLE_DUAL_BOTTOM

The STAPLE_XXX values are specified with respect to the document as if the document were a portrait document. If the document is actually a landscape or a reverse-landscape document, the client supplies the appropriate transformed value. For example, to position a staple in the upper left hand corner of a landscape document when held for reading, the client supplies the STAPLE_BOTTOM_LEFT value (since landscape is defined as a +90 degree rotation from portrait, i.e., anti-clockwise). On the other hand, to position a staple in the upper left hand corner of a reverse-landscape document when held for reading, the client supplies the STAPLE_TOP_RIGHT value (since reverse-landscape is defined as a -90 degree rotation from portrait, i.e., clockwise).

The angle (vertical, horizontal, angled) of each staple with respect to the document depends on the implementation which may in turn depend on the value of the attribute.

The effect of a Finishings attribute on a multidoc print job (a job with multiple documents) depends on whether all the docs have the same binding specified or whether different docs have different bindings specified, and on the (perhaps defaulted) value of the MultipleDocumentHandling attribute.

  • If all the docs have the same binding specified, then any value of MultipleDocumentHandling makes sense, and the printer's processing depends on the MultipleDocumentHandling value:
    • SINGLE_DOCUMENT -- All the input docs will be bound together as one output document with the specified binding.

    • SINGLE_DOCUMENT_NEW_SHEET -- All the input docs will be bound together as one output document with the specified binding, and the first impression of each input doc will always start on a new media sheet.

    • SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- Each input doc will be bound separately with the specified binding.

    • SEPARATE_DOCUMENTS_COLLATED_COPIES -- Each input doc will be bound separately with the specified binding.

  • If different docs have different bindings specified, then only two values of MultipleDocumentHandling make sense, and the printer reports an error when the job is submitted if any other value is specified:
    • SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- Each input doc will be bound separately with its own specified binding.

    • SEPARATE_DOCUMENTS_COLLATED_COPIES -- Each input doc will be bound separately with its own specified binding.

IPP Compatibility: Class Finishings encapsulates some of the IPP enum values that can be included in an IPP "finishings" attribute, which is a set of enums. The category name returned by getName() is the IPP attribute name. The enumeration's integer value is the IPP enum value. The toString() method returns the IPP string representation of the attribute value. In IPP Finishings is a multi-value attribute, this API currently allows only one binding to be specified.

See Also:
Serialized Form

Field Summary
static Finishings | BIND This value indicates that a binding is to be applied to the document; the type and placement of the binding is site-defined.
static Finishings | COVER This value is specified when it is desired to select a non-printed (or pre-printed) cover for the document.
static Finishings | EDGE_STITCH Bind the document(s) with one or more staples (wire stitches) along one edge.
static Finishings | EDGE_STITCH_BOTTOM Bind the document(s) with one or more staples (wire stitches) along the bottom edge.
static Finishings | EDGE_STITCH_LEFT Bind the document(s) with one or more staples (wire stitches) along the left edge.
static Finishings | EDGE_STITCH_RIGHT Bind the document(s) with one or more staples (wire stitches) along the right edge.
static Finishings | EDGE_STITCH_TOP Bind the document(s) with one or more staples (wire stitches) along the top edge.
static Finishings | NONE Perform no binding.
static Finishings | SADDLE_STITCH Bind the document(s) with one or more staples (wire stitches) along the middle fold.
static Finishings | STAPLE Bind the document(s) with one or more staples.
static Finishings | STAPLE_BOTTOM_LEFT Bind the document(s) with one or more staples in the bottom left corner.
static Finishings | STAPLE_BOTTOM_RIGHT Bind the document(s) with one or more staples in the bottom right corner.
static Finishings | STAPLE_DUAL_BOTTOM Bind the document(s) with two staples (wire stitches) along the bottom edge assuming a portrait document (see above).
static Finishings | STAPLE_DUAL_LEFT Bind the document(s) with two staples (wire stitches) along the left edge assuming a portrait document (see above).
static Finishings | STAPLE_DUAL_RIGHT Bind the document(s) with two staples (wire stitches) along the right edge assuming a portrait document (see above).
static Finishings | STAPLE_DUAL_TOP Bind the document(s) with two staples (wire stitches) along the top edge assuming a portrait document (see above).
static Finishings | STAPLE_TOP_LEFT Bind the document(s) with one or more staples in the top left corner.
static Finishings | STAPLE_TOP_RIGHT Bind the document(s) with one or more staples in the top right corner.
Constructor Summary
protected Finishings(int value)
Construct a new finishings binding enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class Finishings.
String | getName() Get the name of the category of which this attribute value is an instance.
protected int | getOffset() Returns the lowest integer value used by class Finishings.
protected String[] | getStringTable() Returns the string table for class Finishings.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

NONE

public static final Finishings NONE
Perform no binding.

STAPLE

public static final Finishings STAPLE
Bind the document(s) with one or more staples. The exact number and placement of the staples is site-defined.

COVER

public static final Finishings COVER
This value is specified when it is desired to select a non-printed (or pre-printed) cover for the document. This does not supplant the specification of a printed cover (on cover stock medium) by the document itself.

BIND

public static final Finishings BIND
This value indicates that a binding is to be applied to the document; the type and placement of the binding is site-defined.

SADDLE_STITCH

public static final Finishings SADDLE_STITCH
Bind the document(s) with one or more staples (wire stitches) along the middle fold. The exact number and placement of the staples and the middle fold is implementation- and/or site-defined.

EDGE_STITCH

public static final Finishings EDGE_STITCH
Bind the document(s) with one or more staples (wire stitches) along one edge. The exact number and placement of the staples is implementation- and/or site- defined.

STAPLE_TOP_LEFT

public static final Finishings STAPLE_TOP_LEFT
Bind the document(s) with one or more staples in the top left corner.

STAPLE_BOTTOM_LEFT

public static final Finishings STAPLE_BOTTOM_LEFT
Bind the document(s) with one or more staples in the bottom left corner.

STAPLE_TOP_RIGHT

public static final Finishings STAPLE_TOP_RIGHT
Bind the document(s) with one or more staples in the top right corner.

STAPLE_BOTTOM_RIGHT

public static final Finishings STAPLE_BOTTOM_RIGHT
Bind the document(s) with one or more staples in the bottom right corner.

EDGE_STITCH_LEFT

public static final Finishings EDGE_STITCH_LEFT
Bind the document(s) with one or more staples (wire stitches) along the left edge. The exact number and placement of the staples is implementation- and/or site-defined.

EDGE_STITCH_TOP

public static final Finishings EDGE_STITCH_TOP
Bind the document(s) with one or more staples (wire stitches) along the top edge. The exact number and placement of the staples is implementation- and/or site-defined.

EDGE_STITCH_RIGHT

public static final Finishings EDGE_STITCH_RIGHT
Bind the document(s) with one or more staples (wire stitches) along the right edge. The exact number and placement of the staples is implementation- and/or site-defined.

EDGE_STITCH_BOTTOM

public static final Finishings EDGE_STITCH_BOTTOM
Bind the document(s) with one or more staples (wire stitches) along the bottom edge. The exact number and placement of the staples is implementation- and/or site-defined.

STAPLE_DUAL_LEFT

public static final Finishings STAPLE_DUAL_LEFT
Bind the document(s) with two staples (wire stitches) along the left edge assuming a portrait document (see above).

STAPLE_DUAL_TOP

public static final Finishings STAPLE_DUAL_TOP
Bind the document(s) with two staples (wire stitches) along the top edge assuming a portrait document (see above).

STAPLE_DUAL_RIGHT

public static final Finishings STAPLE_DUAL_RIGHT
Bind the document(s) with two staples (wire stitches) along the right edge assuming a portrait document (see above).

STAPLE_DUAL_BOTTOM

public static final Finishings STAPLE_DUAL_BOTTOM
Bind the document(s) with two staples (wire stitches) along the bottom edge assuming a portrait document (see above).

Constructor Detail

Finishings

protected Finishings(int value)
Construct a new finishings binding enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class Finishings.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class Finishings.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getOffset

protected int getOffset()
Returns the lowest integer value used by class Finishings.

Overrides:
getOffset in class EnumSyntax
Returns:
the offset of the lowest enumeration value.

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class Finishings and any vendor-defined subclasses, the category is class Finishings itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class Finishings and any vendor-defined subclasses, the category name is "finishings".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobHoldUntil

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobHoldUntil

java.lang.Object
    extended by  javax.print.attribute.DateTimeSyntax
        extended by  javax.print.attribute.standard.JobHoldUntil
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute, PrintRequestAttribute
public final class JobHoldUntil
extends DateTimeSyntax
implements PrintRequestAttribute, PrintJobAttribute

Class JobHoldUntil is a printing attribute class, a date-time attribute, that specifies the exact date and time at which the job must become a candidate for printing.

If the value of this attribute specifies a date-time that is in the future, the printer should add the JobStateReason value of JOB_HOLD_UNTIL_SPECIFIED to the job's JobStateReasons attribute, must move the job to the PENDING_HELD state, and must not schedule the job for printing until the specified date-time arrives.

When the specified date-time arrives, the printer must remove the JobStateReason value of JOB_HOLD_UNTIL_SPECIFIED from the job's JobStateReasons attribute, if present. If there are no other job state reasons that keep the job in the PENDING_HELD state, the printer must consider the job as a candidate for processing by moving the job to the PENDING state.

If the specified date-time has already passed, the job must be a candidate for processing immediately. Thus, one way to make the job immediately become a candidate for processing is to specify a JobHoldUntil attribute constructed like this (denoting a date-time of January 1, 1970, 00:00:00 GMT):

     JobHoldUntil immediately = new JobHoldUntil (new Date (0L));

If the client does not supply this attribute in a Print Request and the printer supports this attribute, the printer must use its (implementation-dependent) default JobHoldUntil value at job submission time (unlike most job template attributes that are used if necessary at job processing time).

To construct a JobHoldUntil attribute from separate values of the year, month, day, hour, minute, and so on, use a Calendar object to construct a Date object, then use the Date object to construct the JobHoldUntil attribute. To convert a JobHoldUntil attribute to separate values of the year, month, day, hour, minute, and so on, create a Calendar object and set it to the Date from the JobHoldUntil attribute.

IPP Compatibility: Although IPP supports a "job-hold-until" attribute specified as a keyword, IPP does not at this time support a "job-hold-until" attribute specified as a date and time. However, the date and time can be converted to one of the standard IPP keywords with some loss of precision; for example, a JobHoldUntil value with today's date and 9:00pm local time might be converted to the standard IPP keyword "night". The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
JobHoldUntil(Date dateTime)
Construct a new job hold until date-time attribute with the given Date value.
Method Summary
boolean | equals(Object object) Returns whether this job hold until attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.DateTimeSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JobHoldUntil

public JobHoldUntil(Date dateTime)
Construct a new job hold until date-time attribute with the given Date value.

Parameters:
dateTime - Date value.
Throws:
NullPointerException - (unchecked exception) Thrown if dateTime is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this job hold until attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class JobHoldUntil.
  3. This job hold until attribute's Date value and object's Date value are equal.

Overrides:
equals in class DateTimeSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this job hold until attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobHoldUntil, the category is class JobHoldUntil itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobHoldUntil, the category name is "job-hold-until".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobImpressions

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobImpressions

java.lang.Object
    extended by  javax.print.attribute.IntegerSyntax
        extended by  javax.print.attribute.standard.JobImpressions
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute, PrintRequestAttribute
public final class JobImpressions
extends IntegerSyntax
implements PrintRequestAttribute, PrintJobAttribute

Class JobImpressions is an integer valued printing attribute class that specifies the total size in number of impressions of the document(s) being submitted. An "impression" is the image (possibly many print-stream pages in different configurations) imposed onto a single media page.

The JobImpressions attribute describes the size of the job. This attribute is not intended to be a counter; it is intended to be useful routing and scheduling information if known. The printer may try to compute the JobImpressions attribute's value if it is not supplied in the Print Request. Even if the client does supply a value for the JobImpressions attribute in the Print Request, the printer may choose to change the value if the printer is able to compute a value which is more accurate than the client supplied value. The printer may be able to determine the correct value for the JobImpressions attribute either right at job submission time or at any later point in time.

As with JobKOctets, the JobImpressions value must not include the multiplicative factors contributed by the number of copies specified by the Copies attribute, independent of whether the device can process multiple copies without making multiple passes over the job or document data and independent of whether the output is collated or not. Thus the value is independent of the implementation and reflects the size of the document(s) measured in impressions independent of the number of copies.

As with JobKOctets, the JobImpressions value must also not include the multiplicative factor due to a copies instruction embedded in the document data. If the document data actually includes replications of the document data, this value will include such replication. In other words, this value is always the number of impressions in the source document data, rather than a measure of the number of impressions to be produced by the job.

IPP Compatibility: The integer value gives the IPP integer value. The category name returned by getName() gives the IPP attribute name.

See Also:
JobImpressionsSupported, JobImpressionsCompleted, JobKOctets, JobMediaSheets, Serialized Form

Constructor Summary
JobImpressions(int value)
Construct a new job impressions attribute with the given integer value.
Method Summary
boolean | equals(Object object) Returns whether this job impressions attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.IntegerSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JobImpressions

public JobImpressions(int value)
Construct a new job impressions attribute with the given integer value.

Parameters:
value - Integer value.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if value is less than 0.
Method Detail

equals

public boolean equals(Object object)
Returns whether this job impressions attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class JobImpressions.
  3. This job impressions attribute's value and object's value are equal.

Overrides:
equals in class IntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this job impressions attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobImpressions, the category is class JobImpressions itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobImpressions, the category name is "job-impressions".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobImpressionsCompleted

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobImpressionsCompleted

java.lang.Object
    extended by  javax.print.attribute.IntegerSyntax
        extended by  javax.print.attribute.standard.JobImpressionsCompleted
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute
public final class JobImpressionsCompleted
extends IntegerSyntax
implements PrintJobAttribute

Class JobImpressionsCompleted is an integer valued printing attribute class that specifies the number of impressions completed for the job so far. For printing devices, the impressions completed includes interpreting, marking, and stacking the output.

The JobImpressionsCompleted attribute describes the progress of the job. This attribute is intended to be a counter. That is, the JobImpressionsCompleted value for a job that has not started processing must be 0. When the job's JobState is PROCESSING or PROCESSING_STOPPED, the JobImpressionsCompleted value is intended to increase as the job is processed; it indicates the amount of the job that has been processed at the time the Print Job's attribute set is queried or at the time a print job event is reported. When the job enters the COMPLETED, CANCELED, or ABORTED states, the JobImpressionsCompleted value is the final value for the job.

IPP Compatibility: The integer value gives the IPP integer value. The category name returned by getName() gives the IPP attribute name.

See Also:
JobImpressions, JobImpressionsSupported, JobKOctetsProcessed, JobMediaSheetsCompleted, Serialized Form

Constructor Summary
JobImpressionsCompleted(int value)
Construct a new job impressions completed attribute with the given integer value.
Method Summary
boolean | equals(Object object) Returns whether this job impressions completed attribute is equivalent tp the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.IntegerSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JobImpressionsCompleted

public JobImpressionsCompleted(int value)
Construct a new job impressions completed attribute with the given integer value.

Parameters:
value - Integer value.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if value is less than 0.
Method Detail

equals

public boolean equals(Object object)
Returns whether this job impressions completed attribute is equivalent tp the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class JobImpressionsCompleted.
  3. This job impressions completed attribute's value and object's value are equal.

Overrides:
equals in class IntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this job impressions completed attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobImpressionsCompleted, the category is class JobImpressionsCompleted itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobImpressionsCompleted, the category name is "job-impressions-completed".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobImpressionsSupported

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobImpressionsSupported

java.lang.Object
    extended by  javax.print.attribute.SetOfIntegerSyntax
        extended by  javax.print.attribute.standard.JobImpressionsSupported
All Implemented Interfaces:
Serializable, Cloneable, Attribute, SupportedValuesAttribute
public final class JobImpressionsSupported
extends SetOfIntegerSyntax
implements SupportedValuesAttribute

Class JobImpressionsSupported is a printing attribute class, a set of integers, that gives the supported values for a JobImpressions attribute. It is restricted to a single contiguous range of integers; multiple non-overlapping ranges are not allowed. This gives the lower and upper bounds of the total sizes of print jobs in number of impressions that the printer will accept.

IPP Compatibility: The JobImpressionsSupported attribute's canonical array form gives the lower and upper bound for the range of values to be included in an IPP "job-impressions-supported" attribute. See class SetOfIntegerSyntax for an explanation of canonical array form. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
JobImpressionsSupported(int lowerBound, int upperBound)
Construct a new job impressions supported attribute containing a single range of integers.
Method Summary
boolean | equals(Object object) Returns whether this job impressions supported attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.SetOfIntegerSyntax
contains, contains, getMembers, hashCode, next, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JobImpressionsSupported

public JobImpressionsSupported(int lowerBound,
                               int upperBound)
Construct a new job impressions supported attribute containing a single range of integers. That is, only those values of JobImpressions in the one range are supported.

Parameters:
lowerBound - Lower bound of the range.
upperBound - Upper bound of the range.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if a null range is specified or if a non-null range is specified with lowerBound less than 0.
Method Detail

equals

public boolean equals(Object object)
Returns whether this job impressions supported attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class JobImpressionsSupported.
  3. This job impressions supported attribute's members and object's members are the same.

Overrides:
equals in class SetOfIntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this job impressions supported attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobImpressionsSupported, the category is class JobImpressionsSupported itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobImpressionsSupported, the category name is "job-impressions-supported".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobKOctets

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobKOctets

java.lang.Object
    extended by  javax.print.attribute.IntegerSyntax
        extended by  javax.print.attribute.standard.JobKOctets
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute, PrintRequestAttribute
public final class JobKOctets
extends IntegerSyntax
implements PrintRequestAttribute, PrintJobAttribute

Class JobKOctets is an integer valued printing attribute class that specifies the total size of the document(s) in K octets, i.e., in units of 1024 octets requested to be processed in the job. The value must be rounded up, so that a job between 1 and 1024 octets must be indicated as being 1K octets, 1025 to 2048 must be 2K octets, etc. For a multidoc print job (a job with multiple documents), the JobKOctets value is computed by adding up the individual documents' sizes in octets, then rounding up to the next K octets value.

The JobKOctets attribute describes the size of the job. This attribute is not intended to be a counter; it is intended to be useful routing and scheduling information if known. The printer may try to compute the JobKOctets attribute's value if it is not supplied in the Print Request. Even if the client does supply a value for the JobKOctets attribute in the Print Request, the printer may choose to change the value if the printer is able to compute a value which is more accurate than the client supplied value. The printer may be able to determine the correct value for the JobKOctets attribute either right at job submission time or at any later point in time.

The JobKOctets value must not include the multiplicative factors contributed by the number of copies specified by the Copies attribute, independent of whether the device can process multiple copies without making multiple passes over the job or document data and independent of whether the output is collated or not. Thus the value is independent of the implementation and indicates the size of the document(s) measured in K octets independent of the number of copies.

The JobKOctets value must also not include the multiplicative factor due to a copies instruction embedded in the document data. If the document data actually includes replications of the document data, this value will include such replication. In other words, this value is always the size of the source document data, rather than a measure of the hardcopy output to be produced.

The size of a doc is computed based on the print data representation class as specified by the doc's DocFlavor, as shown in the table below.

Representation Class | Document Size
byte[] | Length of the byte array
java.io.InputStream | Number of bytes read from the stream
char[] | Length of the character array x 2
java.lang.String | Length of the string x 2
java.io.Reader | Number of characters read from the stream x 2
java.net.URL | Number of bytes read from the file at the given URL address
java.awt.image.renderable.RenderableImage | Implementation dependent*
java.awt.print.Printable | Implementation dependent*
java.awt.print.Pageable | Implementation dependent*

* In these cases the Print Service itself generates the print data sent to the printer. If the Print Service supports the JobKOctets attribute, for these cases the Print Service itself must calculate the size of the print data, replacing any JobKOctets value the client specified.

IPP Compatibility: The integer value gives the IPP integer value. The category name returned by getName() gives the IPP attribute name.

See Also:
JobKOctetsSupported, JobKOctetsProcessed, JobImpressions, JobMediaSheets, Serialized Form

Constructor Summary
JobKOctets(int value)
Construct a new job K octets attribute with the given integer value.
Method Summary
boolean | equals(Object object) Returns whether this job K octets attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.IntegerSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JobKOctets

public JobKOctets(int value)
Construct a new job K octets attribute with the given integer value.

Parameters:
value - Integer value.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if value is less than 0.
Method Detail

equals

public boolean equals(Object object)
Returns whether this job K octets attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class JobKOctets.
  3. This job K octets attribute's value and object's value are equal.

Overrides:
equals in class IntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this job K octets attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobKOctets, the category is class JobKOctets itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobKOctets, the category name is "job-k-octets".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobKOctetsProcessed

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobKOctetsProcessed

java.lang.Object
    extended by  javax.print.attribute.IntegerSyntax
        extended by  javax.print.attribute.standard.JobKOctetsProcessed
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute
public final class JobKOctetsProcessed
extends IntegerSyntax
implements PrintJobAttribute

Class JobKOctetsProcessed is an integer valued printing attribute class that specifies the total number of print data octets processed so far in K octets, i.e., in units of 1024 octets. The value must be rounded up, so that a job between 1 and 1024 octets inclusive must be indicated as being 1K octets, 1025 to 2048 inclusive must be 2K, etc. For a multidoc print job (a job with multiple documents), the JobKOctetsProcessed value is computed by adding up the individual documents' number of octets processed so far, then rounding up to the next K octets value.

The JobKOctetsProcessed attribute describes the progress of the job. This attribute is intended to be a counter. That is, the JobKOctetsProcessed value for a job that has not started processing must be 0. When the job's JobState is PROCESSING or PROCESSING_STOPPED, the JobKOctetsProcessed value is intended to increase as the job is processed; it indicates the amount of the job that has been processed at the time the Print Job's attribute set is queried or at the time a print job event is reported. When the job enters the COMPLETED, CANCELED, or ABORTED states, the JobKOctetsProcessed value is the final value for the job.

For implementations where multiple copies are produced by the interpreter with only a single pass over the data, the final value of the JobKOctetsProcessed attribute must be equal to the value of the JobKOctets attribute. For implementations where multiple copies are produced by the interpreter by processing the data for each copy, the final value must be a multiple of the value of the JobKOctets attribute.

IPP Compatibility: The integer value gives the IPP integer value. The category name returned by getName() gives the IPP attribute name.

See Also:
JobKOctets, JobKOctetsSupported, JobImpressionsCompleted, JobMediaSheetsCompleted, Serialized Form

Constructor Summary
JobKOctetsProcessed(int value)
Construct a new job K octets processed attribute with the given integer value.
Method Summary
boolean | equals(Object object) Returns whether this job K octets processed attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.IntegerSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JobKOctetsProcessed

public JobKOctetsProcessed(int value)
Construct a new job K octets processed attribute with the given integer value.

Parameters:
value - Integer value.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if value is less than 0.
Method Detail

equals

public boolean equals(Object object)
Returns whether this job K octets processed attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class JobKOctetsProcessed.
  3. This job K octets processed attribute's value and object's value are equal.

Overrides:
equals in class IntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this job K octets processed attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobKOctetsProcessed, the category is class JobKOctetsProcessed itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobKOctetsProcessed, the category name is "job-k-octets-processed".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobKOctetsSupported

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobKOctetsSupported

java.lang.Object
    extended by  javax.print.attribute.SetOfIntegerSyntax
        extended by  javax.print.attribute.standard.JobKOctetsSupported
All Implemented Interfaces:
Serializable, Cloneable, Attribute, SupportedValuesAttribute
public final class JobKOctetsSupported
extends SetOfIntegerSyntax
implements SupportedValuesAttribute

Class JobKOctetsSupported is a printing attribute class, a set of integers, that gives the supported values for a JobKOctets attribute. It is restricted to a single contiguous range of integers; multiple non-overlapping ranges are not allowed. This gives the lower and upper bounds of the total sizes of print jobs in units of K octets (1024 octets) that the printer will accept.

IPP Compatibility: The JobKOctetsSupported attribute's canonical array form gives the lower and upper bound for the range of values to be included in an IPP "job-k-octets-supported" attribute. See class SetOfIntegerSyntax for an explanation of canonical array form. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
JobKOctetsSupported(int lowerBound, int upperBound)
Construct a new job K octets supported attribute containing a single range of integers.
Method Summary
boolean | equals(Object object) Returns whether this job K octets supported attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.SetOfIntegerSyntax
contains, contains, getMembers, hashCode, next, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JobKOctetsSupported

public JobKOctetsSupported(int lowerBound,
                           int upperBound)
Construct a new job K octets supported attribute containing a single range of integers. That is, only those values of JobKOctets in the one range are supported.

Parameters:
lowerBound - Lower bound of the range.
upperBound - Upper bound of the range.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if a null range is specified or if a non-null range is specified with lowerBound less than 0.
Method Detail

equals

public boolean equals(Object object)
Returns whether this job K octets supported attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class JobKOctetsSupported.
  3. This job K octets supported attribute's members and object's members are the same.

Overrides:
equals in class SetOfIntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this job K octets supported attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobKOctetsSupported, the category is class JobKOctetsSupported itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobKOctetsSupported, the category name is "job-k-octets-supported".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobMediaSheets

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobMediaSheets

java.lang.Object
    extended by  javax.print.attribute.IntegerSyntax
        extended by  javax.print.attribute.standard.JobMediaSheets
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute, PrintRequestAttribute
public class JobMediaSheets
extends IntegerSyntax
implements PrintRequestAttribute, PrintJobAttribute

Class JobMediaSheets is an integer valued printing attribute class that specifies the total number of media sheets to be produced for this job.

The JobMediaSheets attribute describes the size of the job. This attribute is not intended to be a counter; it is intended to be useful routing and scheduling information if known. The printer may try to compute the JobMediaSheets attribute's value if it is not supplied in the Print Request. Even if the client does supply a value for the JobMediaSheets attribute in the Print Request, the printer may choose to change the value if the printer is able to compute a value which is more accurate than the client supplied value. The printer may be able to determine the correct value for the JobMediaSheets attribute either right at job submission time or at any later point in time.

Unlike the JobKOctets and JobImpressions attributes, the JobMediaSheets value must include the multiplicative factors contributed by the number of copies specified by the Copies attribute and a "number of copies" instruction embedded in the document data, if any. This difference allows the system administrator to control the lower and upper bounds of both (1) the size of the document(s) with JobKOctetsSupported and JobImpressionsSupported and (2) the size of the job with JobMediaSheetsSupported.

IPP Compatibility: The integer value gives the IPP integer value. The category name returned by getName() gives the IPP attribute name.

See Also:
JobMediaSheetsSupported, JobMediaSheetsCompleted, JobKOctets, JobImpressions, Serialized Form

Constructor Summary
JobMediaSheets(int value)
Construct a new job media sheets attribute with the given integer value.
Method Summary
boolean | equals(Object object) Returns whether this job media sheets attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.IntegerSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JobMediaSheets

public JobMediaSheets(int value)
Construct a new job media sheets attribute with the given integer value.

Parameters:
value - Integer value.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if value is less than 0.
Method Detail

equals

public boolean equals(Object object)
Returns whether this job media sheets attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class JobMediaSheets.
  3. This job media sheets attribute's value and object's value are equal.

Overrides:
equals in class IntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this job media sheets attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobMediaSheets and any vendor-defined subclasses, the category is class JobMediaSheets itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobMediaSheets and any vendor-defined subclasses, the category name is "job-media-sheets".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobMediaSheetsCompleted

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobMediaSheetsCompleted

java.lang.Object
    extended by  javax.print.attribute.IntegerSyntax
        extended by  javax.print.attribute.standard.JobMediaSheetsCompleted
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute
public final class JobMediaSheetsCompleted
extends IntegerSyntax
implements PrintJobAttribute

Class JobMediaSheetsCompleted is an integer valued printing attribute class that specifies the number of media sheets which have completed marking and stacking for the entire job so far, whether those sheets have been processed on one side or on both.

The JobMediaSheetsCompleted attribute describes the progress of the job. This attribute is intended to be a counter. That is, the JobMediaSheetsCompleted value for a job that has not started processing must be 0. When the job's JobState is PROCESSING or PROCESSING_STOPPED, the JobMediaSheetsCompleted value is intended to increase as the job is processed; it indicates the amount of the job that has been processed at the time the Print Job's attribute set is queried or at the time a print job event is reported. When the job enters the COMPLETED, CANCELED, or ABORTED states, the JobMediaSheetsCompleted value is the final value for the job.

IPP Compatibility: The integer value gives the IPP integer value. The category name returned by getName() gives the IPP attribute name.

See Also:
JobMediaSheets, JobMediaSheetsSupported, JobKOctetsProcessed, JobImpressionsCompleted, Serialized Form

Constructor Summary
JobMediaSheetsCompleted(int value)
Construct a new job media sheets completed attribute with the given integer value.
Method Summary
boolean | equals(Object object) Returns whether this job media sheets completed attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.IntegerSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JobMediaSheetsCompleted

public JobMediaSheetsCompleted(int value)
Construct a new job media sheets completed attribute with the given integer value.

Parameters:
value - Integer value.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if value is less than 0.
Method Detail

equals

public boolean equals(Object object)
Returns whether this job media sheets completed attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class JobMediaSheetsCompleted.
  3. This job media sheets completed attribute's value and object's value are equal.

Overrides:
equals in class IntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this job media sheets completed attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobMediaSheetsCompleted, the category is class JobMediaSheetsCompleted itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobMediaSheetsCompleted, the category name is "job-media-sheets-completed".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobMediaSheetsSupported

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobMediaSheetsSupported

java.lang.Object
    extended by  javax.print.attribute.SetOfIntegerSyntax
        extended by  javax.print.attribute.standard.JobMediaSheetsSupported
All Implemented Interfaces:
Serializable, Cloneable, Attribute, SupportedValuesAttribute
public final class JobMediaSheetsSupported
extends SetOfIntegerSyntax
implements SupportedValuesAttribute

Class JobMediaSheetsSupported is a printing attribute class, a set of integers, that gives the supported values for a JobMediaSheets attribute. It is restricted to a single contiguous range of integers; multiple non-overlapping ranges are not allowed. This gives the lower and upper bounds of the total sizes of print jobs in number of media sheets that the printer will accept.

IPP Compatibility: The JobMediaSheetsSupported attribute's canonical array form gives the lower and upper bound for the range of values to be included in an IPP "job-media-sheets-supported" attribute. See class SetOfIntegerSyntax for an explanation of canonical array form. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
JobMediaSheetsSupported(int lowerBound, int upperBound)
Construct a new job media sheets supported attribute containing a single range of integers.
Method Summary
boolean | equals(Object object) Returns whether this job media sheets supported attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.SetOfIntegerSyntax
contains, contains, getMembers, hashCode, next, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JobMediaSheetsSupported

public JobMediaSheetsSupported(int lowerBound,
                               int upperBound)
Construct a new job media sheets supported attribute containing a single range of integers. That is, only those values of JobMediaSheets in the one range are supported.

Parameters:
lowerBound - Lower bound of the range.
upperBound - Upper bound of the range.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if a null range is specified or if a non-null range is specified with lowerBound less than 0.
Method Detail

equals

public boolean equals(Object object)
Returns whether this job media sheets supported attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class JobMediaSheetsSupported.
  3. This job media sheets supported attribute's members and object's members are the same.

Overrides:
equals in class SetOfIntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this job media sheets supported attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobMediaSheetsSupported, the category is class JobMediaSheetsSupported itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobMediaSheetsSupported, the category name is "job-media-sheets-supported".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobMessageFromOperator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobMessageFromOperator

java.lang.Object
    extended by  javax.print.attribute.TextSyntax
        extended by  javax.print.attribute.standard.JobMessageFromOperator
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute
public final class JobMessageFromOperator
extends TextSyntax
implements PrintJobAttribute

Class JobMessageFromOperator is a printing attribute class, a text attribute, that provides a message from an operator, system administrator, or "intelligent" process to indicate to the end user the reasons for modification or other management action taken on a job.

A Print Job's attribute set includes zero instances or one instance of a JobMessageFromOperator attribute, not more than one instance. A new JobMessageFromOperator attribute replaces an existing JobMessageFromOperator attribute, if any. In other words, JobMessageFromOperator is not intended to be a history log. If it wishes, the client can detect changes to a Print Job's JobMessageFromOperator attribute and maintain the client's own history log of the JobMessageFromOperator attribute values.

IPP Compatibility: The string value gives the IPP name value. The locale gives the IPP natural language. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
JobMessageFromOperator(String message, Locale locale)
Constructs a new job message from operator attribute with the given message and locale.
Method Summary
boolean | equals(Object object) Returns whether this job message from operator attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.TextSyntax
getLocale, getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JobMessageFromOperator

public JobMessageFromOperator(String message,
                              Locale locale)
Constructs a new job message from operator attribute with the given message and locale.

Parameters:
message - Message.
locale - Natural language of the text string. null is interpreted to mean the default locale as returned by Locale.getDefault()
Throws:
NullPointerException - (unchecked exception) Thrown if message is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this job message from operator attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class JobMessageFromOperator.
  3. This job message from operator attribute's underlying string and object's underlying string are equal.
  4. This job message from operator attribute's locale and object's locale are equal.

Overrides:
equals in class TextSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this job message from operator attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobMessageFromOperator, the category is class JobMessageFromOperator itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobMessageFromOperator, the category name is "job-message-from-operator".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobName

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobName

java.lang.Object
    extended by  javax.print.attribute.TextSyntax
        extended by  javax.print.attribute.standard.JobName
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute, PrintRequestAttribute
public final class JobName
extends TextSyntax
implements PrintRequestAttribute, PrintJobAttribute

Class JobName is a printing attribute class, a text attribute, that specifies the name of a print job. A job's name is an arbitrary string defined by the client. It does not need to be unique between different jobs. A Print Job's JobName attribute is set to the value supplied by the client in the Print Request's attribute set. If, however, the client does not supply a JobName attribute in the Print Request, the printer, when it creates the Print Job, must generate a JobName. The printer should generate the value of the Print Job's JobName attribute from the first of the following sources that produces a value: (1) the DocumentName attribute of the first (or only) doc in the job, (2) the URL of the first (or only) doc in the job, if the doc's print data representation object is a URL, or (3) any other piece of Print Job specific and/or document content information.

IPP Compatibility: The string value gives the IPP name value. The locale gives the IPP natural language. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
JobName(String jobName, Locale locale)
Constructs a new job name attribute with the given job name and locale.
Method Summary
boolean | equals(Object object) Returns whether this job name attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.TextSyntax
getLocale, getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JobName

public JobName(String jobName,
               Locale locale)
Constructs a new job name attribute with the given job name and locale.

Parameters:
jobName - Job name.
locale - Natural language of the text string. null is interpreted to mean the default locale as returned by Locale.getDefault()
Throws:
NullPointerException - (unchecked exception) Thrown if jobName is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this job name attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class JobName.
  3. This job name attribute's underlying string and object's underlying string are equal.
  4. This job name attribute's locale and object's locale are equal.

Overrides:
equals in class TextSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this job name attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobName, the category is class JobName itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobName, the category name is "job-name".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobOriginatingUserName

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobOriginatingUserName

java.lang.Object
    extended by  javax.print.attribute.TextSyntax
        extended by  javax.print.attribute.standard.JobOriginatingUserName
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute
public final class JobOriginatingUserName
extends TextSyntax
implements PrintJobAttribute

Class JobOriginatingUserName is a printing attribute class, a text attribute, that contains the name of the end user that submitted the print job. If possible, the printer sets this attribute to the most authenticated printable user name that it can obtain from the authentication service that authenticated the submitted Print Request. If such is not available, the printer uses the value of the RequestingUserName attribute supplied by the client in the Print Request's attribute set. If no authentication service is available, and the client did not supply a RequestingUserName attribute, the printer sets the JobOriginatingUserName attribute to an empty (zero-length) string.

IPP Compatibility: The string value gives the IPP name value. The locale gives the IPP natural language. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
JobOriginatingUserName(String userName, Locale locale)
Constructs a new job originating user name attribute with the given user name and locale.
Method Summary
boolean | equals(Object object) Returns whether this job originating user name attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.TextSyntax
getLocale, getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JobOriginatingUserName

public JobOriginatingUserName(String userName,
                              Locale locale)
Constructs a new job originating user name attribute with the given user name and locale.

Parameters:
userName - User name.
locale - Natural language of the text string. null is interpreted to mean the default locale as returned by Locale.getDefault()
Throws:
NullPointerException - (unchecked exception) Thrown if userName is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this job originating user name attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class JobOriginatingUserName.
  3. This job originating user name attribute's underlying string and object's underlying string are equal.
  4. This job originating user name attribute's locale and object's locale are equal.

Overrides:
equals in class TextSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this job originating user name attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobOriginatingUserName, the category is class JobOriginatingUserName itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobOriginatingUserName, the category name is "job-originating-user-name".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobPriority

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobPriority

java.lang.Object
    extended by  javax.print.attribute.IntegerSyntax
        extended by  javax.print.attribute.standard.JobPriority
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute, PrintRequestAttribute
public final class JobPriority
extends IntegerSyntax
implements PrintRequestAttribute, PrintJobAttribute

Class JobPriority is an integer valued printing attribute class that specifies a print job's priority.

If a JobPriority attribute is specified for a Print Job, it specifies a priority for scheduling the job. A higher value specifies a higher priority. The value 1 indicates the lowest possible priority. The value 100 indicates the highest possible priority. Among those jobs that are ready to print, a printer must print all jobs with a priority value of n before printing those with a priority value of n-1 for all n.

If the client does not specify a JobPriority attribute for a Print Job and the printer does support the JobPriority attribute, the printer must use an implementation-defined default JobPriority value.

The client can always specify any job priority value from 1 to 100 for a job. However, a Print Service instance may support fewer than 100 different job priority levels. If this is the case, the Print Service instance automatically maps the client-specified job priority value to one of the supported job priority levels, dividing the 100 job priority values equally among the available job priority levels.

IPP Compatibility: The integer value gives the IPP integer value. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
JobPriority(int value)
Construct a new job priority attribute with the given integer value.
Method Summary
boolean | equals(Object object) Returns whether this job priority attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.IntegerSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JobPriority

public JobPriority(int value)
Construct a new job priority attribute with the given integer value.

Parameters:
value - Integer value.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if value is less than 1 or greater than 100.
Method Detail

equals

public boolean equals(Object object)
Returns whether this job priority attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class JobPriority.
  3. This job priority attribute's value and object's value are equal.

Overrides:
equals in class IntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this job priority attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobPriority, the category is class JobPriority itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobPriority, the category name is "job-priority".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobPrioritySupported

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobPrioritySupported

java.lang.Object
    extended by  javax.print.attribute.IntegerSyntax
        extended by  javax.print.attribute.standard.JobPrioritySupported
All Implemented Interfaces:
Serializable, Cloneable, Attribute, SupportedValuesAttribute
public final class JobPrioritySupported
extends IntegerSyntax
implements SupportedValuesAttribute

Class JobPrioritySupported is an integer valued printing attribute class that specifies whether a Print Service instance supports the JobPriority attribute and the number of different job priority levels supported.

The client can always specify any JobPriority value from 1 to 100 for a job. However, the Print Service instance may support fewer than 100 different job priority levels. If this is the case, the Print Service instance automatically maps the client-specified job priority value to one of the supported job priority levels, dividing the 100 job priority values equally among the available job priority levels.

IPP Compatibility: The integer value gives the IPP integer value. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
JobPrioritySupported(int value)
Construct a new job priority supported attribute with the given integer value.
Method Summary
boolean | equals(Object object) Returns whether this job priority supported attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.IntegerSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JobPrioritySupported

public JobPrioritySupported(int value)
Construct a new job priority supported attribute with the given integer value.

Parameters:
value - Number of different job priority levels supported.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if value is less than 1 or greater than 100.
Method Detail

equals

public boolean equals(Object object)
Returns whether this job priority supported attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class JobPrioritySupported.
  3. This job priority supported attribute's value and object's value are equal.

Overrides:
equals in class IntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this job priority supported attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobPrioritySupported, the category is class JobPrioritySupported itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobPrioritySupported, the category name is "job-priority-supported".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobSheets

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobSheets

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.JobSheets
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute, PrintRequestAttribute
public class JobSheets
extends EnumSyntax
implements PrintRequestAttribute, PrintJobAttribute

Class JobSheets is a printing attribute class, an enumeration, that determines which job start and end sheets, if any, must be printed with a job. Class JobSheets declares keywords for standard job sheets values. Implementation- or site-defined names for a job sheets attribute may also be created by defining a subclass of class JobSheets.

The effect of a JobSheets attribute on multidoc print jobs (jobs with multiple documents) may be affected by the MultipleDocumentHandling job attribute, depending on the meaning of the particular JobSheets value.

IPP Compatibility: The category name returned by getName() is the IPP attribute name. The enumeration's integer value is the IPP enum value. The toString() method returns the IPP string representation of the attribute value. For a subclass, the attribute value must be localized to give the IPP name and natural language values.

See Also:
Serialized Form

Field Summary
static JobSheets | NONE No job sheets are printed.
static JobSheets | STANDARD One or more site specific standard job sheets are printed.
Constructor Summary
protected JobSheets(int value)
Construct a new job sheets enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class JobSheets.
String | getName() Get the name of the category of which this attribute value is an instance.
protected String[] | getStringTable() Returns the string table for class JobSheets.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

NONE

public static final JobSheets NONE
No job sheets are printed.

STANDARD

public static final JobSheets STANDARD
One or more site specific standard job sheets are printed. e.g. a single start sheet is printed, or both start and end sheets are printed.

Constructor Detail

JobSheets

protected JobSheets(int value)
Construct a new job sheets enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class JobSheets.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class JobSheets.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobSheets and any vendor-defined subclasses, the category is class JobSheets itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobSheets and any vendor-defined subclasses, the category name is "job-sheets".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobState

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobState

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.JobState
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute
public class JobState
extends EnumSyntax
implements PrintJobAttribute

JobState is a printing attribute class, an enumeration, that identifies the current state of a print job. Class JobState defines standard job state values. A Print Service implementation only needs to report those job states which are appropriate for the particular implementation; it does not have to report every defined job state. The JobStateReasons attribute augments the JobState attribute to give more detailed information about the job in the given job state.

IPP Compatibility: The category name returned by getName() is the IPP attribute name. The enumeration's integer value is the IPP enum value. The toString() method returns the IPP string representation of the attribute value.

See Also:
Serialized Form

Field Summary
static JobState | ABORTED The job has been aborted by the system (usually while the job was in the PROCESSING or PROCESSING_STOPPED state), the printer has completed aborting the job, and all job status attributes have reached their final values for the job.
static JobState | CANCELED The job has been canceled by some human agency, the printer has completed canceling the job, and all job status attributes have reached their final values for the job.
static JobState | COMPLETED The job has completed successfully or with warnings or errors after processing, all of the job media sheets have been successfully stacked in the appropriate output bin(s), and all job status attributes have reached their final values for the job.
static JobState | PENDING The job is a candidate to start processing, but is not yet processing.
static JobState | PENDING_HELD The job is not a candidate for processing for any number of reasons but will return to the PENDING state as soon as the reasons are no longer present.
static JobState | PROCESSING The job is processing.
static JobState | PROCESSING_STOPPED The job has stopped while processing for any number of reasons and will return to the PROCESSING state as soon as the reasons are no longer present.
static JobState | UNKNOWN The job state is unknown.
Constructor Summary
protected JobState(int value)
Construct a new job state enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class JobState.
String | getName() Get the name of the category of which this attribute value is an instance.
protected String[] | getStringTable() Returns the string table for class JobState.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

UNKNOWN

public static final JobState UNKNOWN
The job state is unknown.

PENDING

public static final JobState PENDING
The job is a candidate to start processing, but is not yet processing.

PENDING_HELD

public static final JobState PENDING_HELD
The job is not a candidate for processing for any number of reasons but will return to the PENDING state as soon as the reasons are no longer present. The job's JobStateReasons attribute must indicate why the job is no longer a candidate for processing.

PROCESSING

public static final JobState PROCESSING
The job is processing. One or more of the following activities is occurring:
  1. The job is using, or is attempting to use, one or more purely software processes that are analyzing, creating, or interpreting a PDL, etc.

  2. The job is using, or is attempting to use, one or more hardware devices that are interpreting a PDL, making marks on a medium, and/or performing finishing, such as stapling, etc.

  3. The printer has made the job ready for printing, but the output device is not yet printing it, either because the job hasn't reached the output device or because the job is queued in the output device or some other spooler, awaiting the output device to print it.

When the job is in the PROCESSING state, the entire job state includes the detailed status represented in the printer's PrinterState and PrinterStateReasons attributes.

Implementations may, though they need not, include additional values in the job's JobStateReasons attribute to indicate the progress of the job, such as adding the JOB_PRINTING value to indicate when the output device is actually making marks on paper and/or the PROCESSING_TO_STOP_POINT value to indicate that the printer is in the process of canceling or aborting the job.

PROCESSING_STOPPED

public static final JobState PROCESSING_STOPPED
The job has stopped while processing for any number of reasons and will return to the PROCESSING state as soon as the reasons are no longer present.

The job's JobStateReasons attribute may indicate why the job has stopped processing. For example, if the output device is stopped, the PRINTER_STOPPED value may be included in the job's JobStateReasons attribute.

Note: When an output device is stopped, the device usually indicates its condition in human readable form locally at the device. A client can obtain more complete device status remotely by querying the printer's PrinterState and PrinterStateReasons attributes.

CANCELED

public static final JobState CANCELED
The job has been canceled by some human agency, the printer has completed canceling the job, and all job status attributes have reached their final values for the job. While the printer is canceling the job, the job remains in its current state, but the job's JobStateReasons attribute should contain the PROCESSING_TO_STOP_POINT value and one of the CANCELED_BY_USER, CANCELED_BY_OPERATOR, or CANCELED_AT_DEVICE values. When the job moves to the CANCELED state, the PROCESSING_TO_STOP_POINT value, if present, must be removed, but the CANCELED_BY_xxx value, if present, must remain.

ABORTED

public static final JobState ABORTED
The job has been aborted by the system (usually while the job was in the PROCESSING or PROCESSING_STOPPED state), the printer has completed aborting the job, and all job status attributes have reached their final values for the job. While the printer is aborting the job, the job remains in its current state, but the job's JobStateReasons attribute should contain the PROCESSING_TO_STOP_POINT and ABORTED_BY_SYSTEM values. When the job moves to the ABORTED state, the PROCESSING_TO_STOP_POINT value, if present, must be removed, but the ABORTED_BY_SYSTEM value, if present, must remain.

COMPLETED

public static final JobState COMPLETED
The job has completed successfully or with warnings or errors after processing, all of the job media sheets have been successfully stacked in the appropriate output bin(s), and all job status attributes have reached their final values for the job. The job's JobStateReasons attribute should contain one of these values: COMPLETED_SUCCESSFULLY, COMPLETED_WITH_WARNINGS, or COMPLETED_WITH_ERRORS.

Constructor Detail

JobState

protected JobState(int value)
Construct a new job state enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class JobState.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class JobState.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobState and any vendor-defined subclasses, the category is class JobState itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobState and any vendor-defined subclasses, the category name is "job-state".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobStateReason

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobStateReason

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.JobStateReason
All Implemented Interfaces:
Serializable, Cloneable, Attribute
public class JobStateReason
extends EnumSyntax
implements Attribute

Class JobStateReason is a printing attribute class, an enumeration, that provides additional information about the job's current state, i.e., information that augments the value of the job's JobState attribute. Class JobStateReason defines standard job state reason values. A Print Service implementation only needs to report those job state reasons which are appropriate for the particular implementation; it does not have to report every defined job state reason.

Instances of JobStateReason do not appear in a Print Job's attribute set directly. Rather, a JobStateReasons attribute appears in the Print Job's attribute set. The JobStateReasons attribute contains zero, one, or more than one JobStateReason objects which pertain to the Print Job's status. The printer adds a JobStateReason object to the Print Job's JobStateReasons attribute when the corresponding condition becomes true of the Print Job, and the printer removes the JobStateReason object again when the corresponding condition becomes false, regardless of whether the Print Job's overall JobState also changed.

IPP Compatibility: The category name returned by getName() is the IPP attribute name. The enumeration's integer value is the IPP enum value. The toString() method returns the IPP string representation of the attribute value.

See Also:
Serialized Form

Field Summary
static JobStateReason | ABORTED_BY_SYSTEM The job was aborted by the system.
static JobStateReason | COMPRESSION_ERROR The job was aborted by the system because the printer encountered an error in the document data while decompressing it.
static JobStateReason | DOCUMENT_ACCESS_ERROR The Printer could not access one or more documents passed by reference (i.e., the print data representation object is a URL).
static JobStateReason | DOCUMENT_FORMAT_ERROR The job was aborted by the system because the printer encountered an error in the document data while processing it.
static JobStateReason | JOB_CANCELED_AT_DEVICE The job was canceled by an unidentified local user, i.e., a user at a console at the device.
static JobStateReason | JOB_CANCELED_BY_OPERATOR The job was canceled by the operator, i.e., by a user who has been authenticated as having operator privileges (whether local or remote).
static JobStateReason | JOB_CANCELED_BY_USER The job was canceled by the owner of the job, i.e., by a user whose authenticated identity is the same as the value of the originating user that created the Print Job, or by some other authorized end-user, such as a member of the job owner's security group.
static JobStateReason | JOB_COMPLETED_SUCCESSFULLY The job completed successfully.
static JobStateReason | JOB_COMPLETED_WITH_ERRORS The job completed with errors (and possibly warnings too).
static JobStateReason | JOB_COMPLETED_WITH_WARNINGS The job completed with warnings.
static JobStateReason | JOB_DATA_INSUFFICIENT The printer has created the Print Job, but the printer is expecting additional print data before it can move the job into the PROCESSING state.
static JobStateReason | JOB_HOLD_UNTIL_SPECIFIED The value of the job's JobHoldUntil attribute was specified with a date-time that is still in the future.
static JobStateReason | JOB_INCOMING The printer has created the Print Job, but the printer has not finished accessing or accepting all the print data yet.
static JobStateReason | JOB_INTERPRETING The job is in the PROCESSING state, but more specifically, the printer ia interpreting the document data.
static JobStateReason | JOB_OUTGOING The printer is transmitting the job to the output device.
static JobStateReason | JOB_PRINTING The output device is marking media.
static JobStateReason | JOB_QUEUED The job is in the PROCESSING state, but more specifically, the printer has queued the document data.
static JobStateReason | JOB_QUEUED_FOR_MARKER The job is in the PENDING_HELD, PENDING, or PROCESSING state, but more specifically, the printer has completed enough processing of the document to be able to start marking and the job is waiting for the marker.
static JobStateReason | JOB_RESTARTABLE This job is retained and is currently able to be restarted.
static JobStateReason | JOB_TRANSFORMING The job is in the PROCESSING state, but more specifically, the printer is interpreting document data and producing another electronic representation.
static JobStateReason | PRINTER_STOPPED The value of the printer's PrinterState attribute ia STOPPED.
static JobStateReason | PRINTER_STOPPED_PARTLY The value of the printer's PrinterStateReasons attribute contains a PrinterStateReason value of STOPPED_PARTLY.
static JobStateReason | PROCESSING_TO_STOP_POINT The requester has canceled the job or the printer has aborted the job, but the printer is still performing some actions on the job until a specified stop point occurs or job termination/cleanup is completed.
static JobStateReason | QUEUED_IN_DEVICE The job has been forwarded to a device or print system that is unable to send back status.
static JobStateReason | RESOURCES_ARE_NOT_READY At least one of the resources needed by the job, such as media, fonts, resource objects, etc., is not ready on any of the physical printers for which the job is a candidate.
static JobStateReason | SERVICE_OFF_LINE The printer is off-line and accepting no jobs.
static JobStateReason | SUBMISSION_INTERRUPTED The job was not completely submitted for some unforeseen reason.
static JobStateReason | UNSUPPORTED_COMPRESSION The job was aborted by the system because the printer determined while attempting to decompress the document's data that the compression is actually not among those supported by the printer.
static JobStateReason | UNSUPPORTED_DOCUMENT_FORMAT The job was aborted by the system because the document data's document format (doc flavor) is not among those supported by the printer.
Constructor Summary
protected JobStateReason(int value)
Construct a new job state reason enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class JobStateReason.
String | getName() Get the name of the category of which this attribute value is an instance.
protected String[] | getStringTable() Returns the string table for class JobStateReason.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

JOB_INCOMING

public static final JobStateReason JOB_INCOMING
The printer has created the Print Job, but the printer has not finished accessing or accepting all the print data yet.

JOB_DATA_INSUFFICIENT

public static final JobStateReason JOB_DATA_INSUFFICIENT
The printer has created the Print Job, but the printer is expecting additional print data before it can move the job into the PROCESSING state. If a printer starts processing before it has received all data, the printer removes the JOB_DATA_INSUFFICIENT reason, but the JOB_INCOMING reason remains. If a printer starts processing after it has received all data, the printer removes the JOB_DATA_INSUFFICIENT and JOB_INCOMING reasons at the same time.

DOCUMENT_ACCESS_ERROR

public static final JobStateReason DOCUMENT_ACCESS_ERROR
The Printer could not access one or more documents passed by reference (i.e., the print data representation object is a URL). This reason is intended to cover any file access problem,including file does not exist and access denied because of an access control problem. Whether the printer aborts the job and moves the job to the ABORTED job state or prints all documents that are accessible and moves the job to the COMPLETED job state and adds the COMPLETED_WITH_ERRORS reason to the job's JobStateReasons attribute depends on implementation and/or site policy. This value should be supported if the printer supports doc flavors with URL print data representation objects.

SUBMISSION_INTERRUPTED

public static final JobStateReason SUBMISSION_INTERRUPTED
The job was not completely submitted for some unforeseen reason. Possibilities include (1) the printer has crashed before the job was fully submitted by the client, (2) the printer or the document transfer method has crashed in some non-recoverable way before the document data was entirely transferred to the printer, (3) the client crashed before the job was fully submitted.

JOB_OUTGOING

public static final JobStateReason JOB_OUTGOING
The printer is transmitting the job to the output device.

JOB_HOLD_UNTIL_SPECIFIED

public static final JobStateReason JOB_HOLD_UNTIL_SPECIFIED
The value of the job's JobHoldUntil attribute was specified with a date-time that is still in the future. The job must not be a candidate for processing until this reason is removed and there are no other reasons to hold the job. This value should be supported if the JobHoldUntil job template attribute is supported.

RESOURCES_ARE_NOT_READY

public static final JobStateReason RESOURCES_ARE_NOT_READY
At least one of the resources needed by the job, such as media, fonts, resource objects, etc., is not ready on any of the physical printers for which the job is a candidate. This condition may be detected when the job is accepted, or subsequently while the job is pending or processing, depending on implementation. The job may remain in its current state or be moved to the PENDING_HELD state, depending on implementation and/or job scheduling policy.

PRINTER_STOPPED_PARTLY

public static final JobStateReason PRINTER_STOPPED_PARTLY
The value of the printer's PrinterStateReasons attribute contains a PrinterStateReason value of STOPPED_PARTLY.

PRINTER_STOPPED

public static final JobStateReason PRINTER_STOPPED
The value of the printer's PrinterState attribute ia STOPPED.

JOB_INTERPRETING

public static final JobStateReason JOB_INTERPRETING
The job is in the PROCESSING state, but more specifically, the printer ia interpreting the document data.

JOB_QUEUED

public static final JobStateReason JOB_QUEUED
The job is in the PROCESSING state, but more specifically, the printer has queued the document data.

JOB_TRANSFORMING

public static final JobStateReason JOB_TRANSFORMING
The job is in the PROCESSING state, but more specifically, the printer is interpreting document data and producing another electronic representation.

JOB_QUEUED_FOR_MARKER

public static final JobStateReason JOB_QUEUED_FOR_MARKER
The job is in the PENDING_HELD, PENDING, or PROCESSING state, but more specifically, the printer has completed enough processing of the document to be able to start marking and the job is waiting for the marker. Systems that require human intervention to release jobs put the job into the PENDING_HELD job state. Systems that automatically select a job to use the marker put the job into the PENDING job state or keep the job in the PROCESSING job state while waiting for the marker, depending on implementation. All implementations put the job into (or back into) the PROCESSING state when marking does begin.

JOB_PRINTING

public static final JobStateReason JOB_PRINTING
The output device is marking media. This value is useful for printers which spend a great deal of time processing (1) when no marking is happening and then want to show that marking is now happening or (2) when the job is in the process of being canceled or aborted while the job remains in the PROCESSING state, but the marking has not yet stopped so that impression or sheet counts are still increasing for the job.

JOB_CANCELED_BY_USER

public static final JobStateReason JOB_CANCELED_BY_USER
The job was canceled by the owner of the job, i.e., by a user whose authenticated identity is the same as the value of the originating user that created the Print Job, or by some other authorized end-user, such as a member of the job owner's security group. This value should be supported.

JOB_CANCELED_BY_OPERATOR

public static final JobStateReason JOB_CANCELED_BY_OPERATOR
The job was canceled by the operator, i.e., by a user who has been authenticated as having operator privileges (whether local or remote). If the security policy is to allow anyone to cancel anyone's job, then this value may be used when the job is canceled by someone other than the owner of the job. For such a security policy, in effect, everyone is an operator as far as canceling jobs is concerned. This value should be supported if the implementation permits canceling by someone other than the owner of the job.

JOB_CANCELED_AT_DEVICE

public static final JobStateReason JOB_CANCELED_AT_DEVICE
The job was canceled by an unidentified local user, i.e., a user at a console at the device. This value should be supported if the implementation supports canceling jobs at the console.

ABORTED_BY_SYSTEM

public static final JobStateReason ABORTED_BY_SYSTEM
The job was aborted by the system. Either the job (1) is in the process of being aborted, (2) has been aborted by the system and placed in the ABORTED state, or (3) has been aborted by the system and placed in the PENDING_HELD state, so that a user or operator can manually try the job again. This value should be supported.

UNSUPPORTED_COMPRESSION

public static final JobStateReason UNSUPPORTED_COMPRESSION
The job was aborted by the system because the printer determined while attempting to decompress the document's data that the compression is actually not among those supported by the printer. This value must be supported, since Compression is a required doc description attribute.

COMPRESSION_ERROR

public static final JobStateReason COMPRESSION_ERROR
The job was aborted by the system because the printer encountered an error in the document data while decompressing it. If the printer posts this reason, the document data has already passed any tests that would have led to the UNSUPPORTED_COMPRESSION job state reason.

UNSUPPORTED_DOCUMENT_FORMAT

public static final JobStateReason UNSUPPORTED_DOCUMENT_FORMAT
The job was aborted by the system because the document data's document format (doc flavor) is not among those supported by the printer. If the client specifies a doc flavor with a MIME type of "application/octet-stream", the printer may abort the job if the printer cannot determine the document data's actual format through auto-sensing (even if the printer supports the document format if specified explicitly). This value must be supported, since a doc flavor is required to be specified for each doc.

DOCUMENT_FORMAT_ERROR

public static final JobStateReason DOCUMENT_FORMAT_ERROR
The job was aborted by the system because the printer encountered an error in the document data while processing it. If the printer posts this reason, the document data has already passed any tests that would have led to the UNSUPPORTED_DOCUMENT_FORMAT job state reason.

PROCESSING_TO_STOP_POINT

public static final JobStateReason PROCESSING_TO_STOP_POINT
The requester has canceled the job or the printer has aborted the job, but the printer is still performing some actions on the job until a specified stop point occurs or job termination/cleanup is completed.

If the implementation requires some measurable time to cancel the job in the PROCESSING or PROCESSING_STOPPED job states, the printer must use this reason to indicate that the printer is still performing some actions on the job while the job remains in the PROCESSING or PROCESSING_STOPPED state. After all the job's job description attributes have stopped incrementing, the printer moves the job from the PROCESSING state to the CANCELED or ABORTED job states.

SERVICE_OFF_LINE

public static final JobStateReason SERVICE_OFF_LINE
The printer is off-line and accepting no jobs. All PENDING jobs are put into the PENDING_HELD state. This situation could be true if the service's or document transform's input is impaired or broken.

JOB_COMPLETED_SUCCESSFULLY

public static final JobStateReason JOB_COMPLETED_SUCCESSFULLY
The job completed successfully. This value should be supported.

JOB_COMPLETED_WITH_WARNINGS

public static final JobStateReason JOB_COMPLETED_WITH_WARNINGS
The job completed with warnings. This value should be supported if the implementation detects warnings.

JOB_COMPLETED_WITH_ERRORS

public static final JobStateReason JOB_COMPLETED_WITH_ERRORS
The job completed with errors (and possibly warnings too). This value should be supported if the implementation detects errors.

JOB_RESTARTABLE

public static final JobStateReason JOB_RESTARTABLE
This job is retained and is currently able to be restarted. If JOB_RESTARTABLE is contained in the job's JobStateReasons attribute, then the printer must accept a request to restart that job. This value should be supported if restarting jobs is supported. [The capability for restarting jobs is not in the Java Print Service API at present.]

QUEUED_IN_DEVICE

public static final JobStateReason QUEUED_IN_DEVICE
The job has been forwarded to a device or print system that is unable to send back status. The printer sets the job's JobState attribute to COMPLETED and adds the QUEUED_IN_DEVICE reason to the job's JobStateReasons attribute to indicate that the printer has no additional information about the job and never will have any better information.

Constructor Detail

JobStateReason

protected JobStateReason(int value)
Construct a new job state reason enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class JobStateReason.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class JobStateReason.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobStateReason and any vendor-defined subclasses, the category is class JobStateReason itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobStateReason and any vendor-defined subclasses, the category name is "job-state-reason".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JobStateReasons

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class JobStateReasons

java.lang.Object
    extended by  java.util.AbstractCollection<E>
        extended by  java.util.AbstractSet<E>
            extended by  java.util.HashSet<JobStateReason>
                extended by  javax.print.attribute.standard.JobStateReasons
All Implemented Interfaces:
Serializable, Cloneable, Iterable<JobStateReason>, Collection<JobStateReason>, Set<JobStateReason>, Attribute, PrintJobAttribute
public final class JobStateReasons
extends HashSet<JobStateReason>
implements PrintJobAttribute

Class JobStateReasons is a printing attribute class, a set of enumeration values, that provides additional information about the job's current state, i.e., information that augments the value of the job's JobState attribute.

Instances of JobStateReason do not appear in a Print Job's attribute set directly. Rather, a JobStateReasons attribute appears in the Print Job's attribute set. The JobStateReasons attribute contains zero, one, or more than one JobStateReason objects which pertain to the Print Job's status. The printer adds a JobStateReason object to the Print Job's JobStateReasons attribute when the corresponding condition becomes true of the Print Job, and the printer removes the JobStateReason object again when the corresponding condition becomes false, regardless of whether the Print Job's overall JobState also changed.

Class JobStateReasons inherits its implementation from class java.util.HashSet. Unlike most printing attributes which are immutable once constructed, class JobStateReasons is designed to be mutable; you can add JobStateReason objects to an existing JobStateReasons object and remove them again. However, like class java.util.HashSet, class JobStateReasons is not multiple thread safe. If a JobStateReasons object will be used by multiple threads, be sure to synchronize its operations (e.g., using a synchronized set view obtained from class java.util.Collections).

IPP Compatibility: The string value returned by each individual JobStateReason object's toString() method gives the IPP keyword value. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
JobStateReasons()
Construct a new, empty job state reasons attribute; the underlying hash set has the default initial capacity and load factor.
JobStateReasons(Collection<JobStateReason> collection)
Construct a new job state reasons attribute that contains the same JobStateReason objects as the given collection.
JobStateReasons(int initialCapacity)
Construct a new, empty job state reasons attribute; the underlying hash set has the given initial capacity and the default load factor.
JobStateReasons(int initialCapacity, float loadFactor)
Construct a new, empty job state reasons attribute; the underlying hash set has the given initial capacity and load factor.
Method Summary
boolean | add(JobStateReason o) Adds the specified element to this job state reasons attribute if it is not already present.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class java.util.HashSet
clear, clone, contains, isEmpty, iterator, remove, size
Methods inherited from class java.util.AbstractSet
equals, hashCode, removeAll
Methods inherited from class java.util.AbstractCollection
addAll, containsAll, retainAll, toArray, toArray, toString
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.util.Set
addAll, containsAll, equals, hashCode, removeAll, retainAll, toArray, toArray

Constructor Detail

JobStateReasons

public JobStateReasons()
Construct a new, empty job state reasons attribute; the underlying hash set has the default initial capacity and load factor.

JobStateReasons

public JobStateReasons(int initialCapacity)
Construct a new, empty job state reasons attribute; the underlying hash set has the given initial capacity and the default load factor.

Parameters:
initialCapacity - Initial capacity.
Throws:
IllegalArgumentException - if the initial capacity is less than zero.

JobStateReasons

public JobStateReasons(int initialCapacity,
                       float loadFactor)
Construct a new, empty job state reasons attribute; the underlying hash set has the given initial capacity and load factor.

Parameters:
initialCapacity - Initial capacity.
loadFactor - Load factor.
Throws:
IllegalArgumentException - if the initial capacity is less than zero.

JobStateReasons

public JobStateReasons(Collection<JobStateReason> collection)
Construct a new job state reasons attribute that contains the same JobStateReason objects as the given collection. The underlying hash set's initial capacity and load factor are as specified in the superclass constructor HashSet(Collection).

Parameters:
collection - Collection to copy.
Throws:
NullPointerException - (unchecked exception) Thrown if collection is null or if any element in collection is null.
ClassCastException - (unchecked exception) Thrown if any element in collection is not an instance of class JobStateReason.
Method Detail

add

public boolean add(JobStateReason o)
Adds the specified element to this job state reasons attribute if it is not already present. The element to be added must be an instance of class JobStateReason. If this job state reasons attribute already contains the specified element, the call leaves this job state reasons attribute unchanged and returns false.

Specified by:
add in interface Collection<JobStateReason>
Specified by:
add in interface Set<JobStateReason>
Overrides:
add in class HashSet<JobStateReason>
Parameters:
o - Element to be added to this job state reasons attribute.
Returns:
true if this job state reasons attribute did not already contain the specified element.
Throws:
NullPointerException - (unchecked exception) Thrown if the specified element is null.
ClassCastException - (unchecked exception) Thrown if the specified element is not an instance of class JobStateReason.
Since:
1.5

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class JobStateReasons, the category is class JobStateReasons itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class JobStateReasons, the category name is "job-state-reasons".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Media

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class Media

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.Media
All Implemented Interfaces:
Serializable, Cloneable, Attribute, DocAttribute, PrintJobAttribute, PrintRequestAttribute
Direct Known Subclasses:
MediaName, MediaSizeName, MediaTray
public abstract class Media
extends EnumSyntax
implements DocAttribute, PrintRequestAttribute, PrintJobAttribute

Class Media is a printing attribute class that specifies the medium on which to print.

Media may be specified in different ways.

  • it may be specified by paper source - eg paper tray
  • it may be specified by a standard size - eg "A4"
  • it may be specified by a name - eg "letterhead"
Each of these corresponds to the IPP "media" attribute. The current API does not support describing media by characteristics (eg colour, opacity). This may be supported in a later revision of the specification.

A Media object is constructed with a value which represents one of the ways in which the Media attribute can be specified.

IPP Compatibility: The category name returned by getName() is the IPP attribute name. The enumeration's integer value is the IPP enum value. The toString() method returns the IPP string representation of the attribute value.

See Also:
Serialized Form

Constructor Summary
protected Media(int value)
Constructs a new media attribute specified by name.
Method Summary
boolean | equals(Object object) Returns whether this media attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getEnumValueTable, getOffset, getStringTable, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Media

protected Media(int value)
Constructs a new media attribute specified by name.

Parameters:
value - a value
Method Detail

equals

public boolean equals(Object object)
Returns whether this media attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is of the same subclass of Media as this object.
  3. The values are equal.

Overrides:
equals in class Object
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this media attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class Media and any vendor-defined subclasses, the category is class Media itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class Media and any vendor-defined subclasses, the category name is "media".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MediaName

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class MediaName

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.Media
            extended by  javax.print.attribute.standard.MediaName
All Implemented Interfaces:
Serializable, Cloneable, Attribute, DocAttribute, PrintJobAttribute, PrintRequestAttribute
public class MediaName
extends Media
implements Attribute

Class MediaName is a subclass of Media, a printing attribute class (an enumeration) that specifies the media for a print job as a name.

This attribute can be used instead of specifying MediaSize or MediaTray.

Class MediaName currently declares a few standard media names. Implementation- or site-defined names for a media name attribute may also be created by defining a subclass of class MediaName.

IPP Compatibility: MediaName is a representation class for values of the IPP "media" attribute which names media.

See Also:
Serialized Form

Field Summary
static MediaName | ISO_A4_TRANSPARENT A4 transparency.
static MediaName | ISO_A4_WHITE white A4 paper.
static MediaName | NA_LETTER_TRANSPARENT letter transparency.
static MediaName | NA_LETTER_WHITE white letter paper.
Constructor Summary
protected MediaName(int value)
Constructs a new media name enumeration value with the given integer value.
Method Summary
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class MediaTray.
protected String[] | getStringTable() Returns the string table for class MediaTray.
Methods inherited from class javax.print.attribute.standard.Media
equals, getCategory, getName
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface javax.print.attribute.Attribute
getCategory, getName

Field Detail

NA_LETTER_WHITE

public static final MediaName NA_LETTER_WHITE
white letter paper.

NA_LETTER_TRANSPARENT

public static final MediaName NA_LETTER_TRANSPARENT
letter transparency.

ISO_A4_WHITE

public static final MediaName ISO_A4_WHITE
white A4 paper.

ISO_A4_TRANSPARENT

public static final MediaName ISO_A4_TRANSPARENT
A4 transparency.

Constructor Detail

MediaName

protected MediaName(int value)
Constructs a new media name enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class MediaTray.

Overrides:
getStringTable in class EnumSyntax
Returns:
the String table.

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class MediaTray.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the enumeration value table.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MediaPrintableArea

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class MediaPrintableArea

java.lang.Object
    extended by  javax.print.attribute.standard.MediaPrintableArea
All Implemented Interfaces:
Serializable, Attribute, DocAttribute, PrintJobAttribute, PrintRequestAttribute
public final class MediaPrintableArea
extends Object
implements DocAttribute, PrintRequestAttribute, PrintJobAttribute

Class MediaPrintableArea is a printing attribute used to distinguish the printable and non-printable areas of media.

The printable area is specified to be a rectangle, within the overall dimensions of a media.

Most printers cannot print on the entire surface of the media, due to printer hardware limitations. This class can be used to query the acceptable values for a supposed print job, and to request an area within the constraints of the printable area to be used in a print job.

To query for the printable area, a client must supply a suitable context. Without specifying at the very least the size of the media being used no meaningful value for printable area can be obtained.

The attribute is not described in terms of the distance from the edge of the paper, in part to emphasise that this attribute is not independent of a particular media, but must be described within the context of a choice of other attributes. Additionally it is usually more convenient for a client to use the printable area.

The hardware's minimum margins is not just a property of the printer, but may be a function of the media size, orientation, media type, and any specified finishings. PrintService provides the method to query the supported values of an attribute in a suitable context : See PrintService.getSupportedAttributeValues()

The rectangular printable area is defined thus: The (x,y) origin is positioned at the top-left of the paper in portrait mode regardless of the orientation specified in the requesting context. For example a printable area for A4 paper in portrait or landscape orientation will have height > width.

A printable area attribute's values are stored internally as integers in units of micrometers (µm), where 1 micrometer = 10-6 meter = 1/1000 millimeter = 1/25400 inch. This permits dimensions to be represented exactly to a precision of 1/1000 mm (= 1 µm) or 1/100 inch (= 254 µm). If fractional inches are expressed in negative powers of two, this permits dimensions to be represented exactly to a precision of 1/8 inch (= 3175 µm) but not 1/16 inch (because 1/16 inch does not equal an integral number of µm).

IPP Compatibility: MediaPrintableArea is not an IPP attribute.

See Also:
Serialized Form

Field Summary
static int | INCH Value to indicate units of inches (in).
static int | MM Value to indicate units of millimeters (mm).
Constructor Summary
MediaPrintableArea(float x, float y, float w, float h, int units)
Constructs a MediaPrintableArea object from floating point values.
MediaPrintableArea(int x, int y, int w, int h, int units)
Constructs a MediaPrintableArea object from integer values.
Method Summary
boolean | equals(Object object) Returns whether this media margins attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
float | getHeight(int units) Get the height of the printable area in the specified units.
String | getName() Get the name of the category of which this attribute value is an instance.
float[] | getPrintableArea(int units) Get the printable area as an array of 4 values in the order x, y, w, h.
float | getWidth(int units) Get the width of the printable area in the specified units.
float | getX(int units) Get the x location of the origin of the printable area in the specified units.
float | getY(int units) Get the y location of the origin of the printable area in the specified units.
int | hashCode() Returns a hash code value for this attribute.
String | toString() Returns a string version of this rectangular size attribute in mm.
String | toString(int units, String unitsName) Returns a string version of this rectangular size attribute in the given units.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

INCH

public static final int INCH
Value to indicate units of inches (in). It is actually the conversion factor by which to multiply inches to yield µm (25400).

See Also:
Constant Field Values

MM

public static final int MM
Value to indicate units of millimeters (mm). It is actually the conversion factor by which to multiply mm to yield µm (1000).

See Also:
Constant Field Values
Constructor Detail

MediaPrintableArea

public MediaPrintableArea(float x,
                          float y,
                          float w,
                          float h,
                          int units)
Constructs a MediaPrintableArea object from floating point values.

Parameters:
x - printable x
y - printable y
w - printable width
h - printable height
units - in which the values are expressed.
Throws:
IllegalArgumentException - Thrown if x < 0 or y < 0 or w <= 0="0" or="or" h <= 0="0" or="or" units < 1.

MediaPrintableArea

public MediaPrintableArea(int x,
                          int y,
                          int w,
                          int h,
                          int units)
Constructs a MediaPrintableArea object from integer values.

Parameters:
x - printable x
y - printable y
w - printable width
h - printable height
units - in which the values are expressed.
Throws:
IllegalArgumentException - Thrown if x < 0 or y < 0 or w <= 0="0" or="or" h <= 0="0" or="or" units < 1.
Method Detail

getPrintableArea

public float[] getPrintableArea(int units)
Get the printable area as an array of 4 values in the order x, y, w, h. The values returned are in the given units.

Parameters:
units - Unit conversion factor, e.g. INCH or MM.
Returns:
printable area as array of x, y, w, h in the specified units.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if units < 1.

getX

public float getX(int units)
Get the x location of the origin of the printable area in the specified units.

Parameters:
units - Unit conversion factor, e.g. INCH or MM.
Returns:
x location of the origin of the printable area in the specified units.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if units < 1.

getY

public float getY(int units)
Get the y location of the origin of the printable area in the specified units.

Parameters:
units - Unit conversion factor, e.g. INCH or MM.
Returns:
y location of the origin of the printable area in the specified units.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if units < 1.

getWidth

public float getWidth(int units)
Get the width of the printable area in the specified units.

Parameters:
units - Unit conversion factor, e.g. INCH or MM.
Returns:
width of the printable area in the specified units.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if units < 1.

getHeight

public float getHeight(int units)
Get the height of the printable area in the specified units.

Parameters:
units - Unit conversion factor, e.g. INCH or MM.
Returns:
height of the printable area in the specified units.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if units < 1.

equals

public boolean equals(Object object)
Returns whether this media margins attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class MediaPrintableArea.
  3. The origin and dimensions are the same.

Overrides:
equals in class Object
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this media margins attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class MediaPrintableArea, the category is class MediaPrintableArea itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class MediaPrintableArea, the category name is "media-printable-area".

This is not an IPP V1.1 attribute.

Specified by:
getName in interface Attribute
Returns:
Attribute category name.

toString

public String toString(int units,
                       String unitsName)
Returns a string version of this rectangular size attribute in the given units.

Parameters:
units - Unit conversion factor, e.g. INCH or MM.
unitsName - Units name string, e.g. "in" or "mm". If null, no units name is appended to the result.
Returns:
String version of this two-dimensional size attribute.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if units < 1.

toString

public String toString()
Returns a string version of this rectangular size attribute in mm.

Overrides:
toString in class Object
Returns:
a string representation of the object.

hashCode

public int hashCode()
Returns a hash code value for this attribute.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MediaSize

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class MediaSize

java.lang.Object
    extended by  javax.print.attribute.Size2DSyntax
        extended by  javax.print.attribute.standard.MediaSize
All Implemented Interfaces:
Serializable, Cloneable, Attribute
public class MediaSize
extends Size2DSyntax
implements Attribute

Class MediaSize is a two-dimensional size valued printing attribute class that indicates the dimensions of the medium in a portrait orientation, with the X dimension running along the bottom edge and the Y dimension running along the left edge. Thus, the Y dimension must be greater than or equal to the X dimension. Class MediaSize declares many standard media size values, organized into nested classes for ISO, JIS, North American, engineering, and other media.

MediaSize is not yet used to specify media. Its current role is as a mapping for named media (see MediaSizeName). Clients can use the mapping method MediaSize.getMediaSizeForName(MediaSizeName) to find the physical dimensions of the MediaSizeName instances enumerated in this API. This is useful for clients which need this information to format & paginate printing.

See Also:
Serialized Form

Nested Class Summary
static class | MediaSize.Engineering Class MediaSize.Engineering includes MediaSize values for engineering media.
static class | MediaSize.ISO Class MediaSize.ISO includes MediaSize values for ISO media.
static class | MediaSize.JIS Class MediaSize.JIS includes MediaSize values for JIS (Japanese) media.
static class | MediaSize.NA Class MediaSize.NA includes MediaSize values for North American media.
static class | MediaSize.Other Class MediaSize.Other includes MediaSize values for miscellaneous media.
Field Summary
Fields inherited from class javax.print.attribute.Size2DSyntax
INCH, MM
Constructor Summary
MediaSize(float x, float y, int units)
Construct a new media size attribute from the given floating-point values.
MediaSize(float x, float y, int units, MediaSizeName media)
Construct a new media size attribute from the given floating-point values.
MediaSize(int x, int y, int units)
Construct a new media size attribute from the given integer values.
MediaSize(int x, int y, int units, MediaSizeName media)
Construct a new media size attribute from the given integer values.
Method Summary
boolean | equals(Object object) Returns whether this media size attribute is equivalent to the passed in object.
static MediaSizeName | findMedia(float x, float y, int units) The specified dimensions are used to locate a matching MediaSize instance from amongst all the standard MediaSize instances.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
static MediaSize | getMediaSizeForName(MediaSizeName media) Get the MediaSize for the specified named media.
MediaSizeName | getMediaSizeName() Get the media name, if any, for this size.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.Size2DSyntax
getSize, getX, getXMicrometers, getY, getYMicrometers, hashCode, toString, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

MediaSize

public MediaSize(float x,
                 float y,
                 int units)
Construct a new media size attribute from the given floating-point values.

Parameters:
x - X dimension.
y - Y dimension.
units - Unit conversion factor, e.g. Size2DSyntax.INCH or Size2DSyntax.MM.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if x < 0 or y < 0 or units < 1 or x > y.

MediaSize

public MediaSize(int x,
                 int y,
                 int units)
Construct a new media size attribute from the given integer values.

Parameters:
x - X dimension.
y - Y dimension.
units - Unit conversion factor, e.g. Size2DSyntax.INCH or Size2DSyntax.MM.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if x < 0 or y < 0 or units < 1 or x > y.

MediaSize

public MediaSize(float x,
                 float y,
                 int units,
                 MediaSizeName media)
Construct a new media size attribute from the given floating-point values.

Parameters:
x - X dimension.
y - Y dimension.
units - Unit conversion factor, e.g. Size2DSyntax.INCH or Size2DSyntax.MM.
media - a media name to associate with this MediaSize
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if x < 0 or y < 0 or units < 1 or x > y.

MediaSize

public MediaSize(int x,
                 int y,
                 int units,
                 MediaSizeName media)
Construct a new media size attribute from the given integer values.

Parameters:
x - X dimension.
y - Y dimension.
units - Unit conversion factor, e.g. Size2DSyntax.INCH or Size2DSyntax.MM.
media - a media name to associate with this MediaSize
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if x < 0 or y < 0 or units < 1 or x > y.
Method Detail

getMediaSizeName

public MediaSizeName getMediaSizeName()
Get the media name, if any, for this size.

Returns:
the name for this media size, or null if no name was associated with this size (an anonymous size).

getMediaSizeForName

public static MediaSize getMediaSizeForName(MediaSizeName media)
Get the MediaSize for the specified named media.

Parameters:
media - - the name of the media for which the size is sought
Returns:
size of the media, or null if this media is not associated with any size.

findMedia

public static MediaSizeName findMedia(float x,
                                      float y,
                                      int units)
The specified dimensions are used to locate a matching MediaSize instance from amongst all the standard MediaSize instances. If there is no exact match, the closest match is used.

The MediaSize is in turn used to locate the MediaSizeName object. This method may return null if the closest matching MediaSize has no corresponding Media instance.

This method is useful for clients which have only dimensions and want to find a Media which corresponds to the dimensions.

Parameters:
x - - X dimension
y - - Y dimension.
units - Unit conversion factor, e.g. Size2DSyntax.INCH or Size2DSyntax.MM
Returns:
MediaSizeName matching these dimensions, or null.
Throws:
IllegalArgumentException - if x <= 0,="0," y="y" <="0," or="or" units="units" <="<" 1

equals

public boolean equals(Object object)
Returns whether this media size attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class MediaSize.
  3. This media size attribute's X dimension is equal to object's X dimension.
  4. This media size attribute's Y dimension is equal to object's Y dimension.

Overrides:
equals in class Size2DSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this media size attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class MediaSize and any vendor-defined subclasses, the category is class MediaSize itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class MediaSize and any vendor-defined subclasses, the category name is "media-size".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MediaSize.Engineering

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class MediaSize.Engineering

java.lang.Object
    extended by  javax.print.attribute.standard.MediaSize.Engineering
Enclosing class:
MediaSize
public static final class MediaSize.Engineering
extends Object

Class MediaSize.Engineering includes MediaSize values for engineering media.

Field Summary
static MediaSize | A Specifies the engineering A size, 8.5 inch by 11 inch.
static MediaSize | B Specifies the engineering B size, 11 inch by 17 inch.
static MediaSize | C Specifies the engineering C size, 17 inch by 22 inch.
static MediaSize | D Specifies the engineering D size, 22 inch by 34 inch.
static MediaSize | E Specifies the engineering E size, 34 inch by 44 inch.
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

A

public static final MediaSize A
Specifies the engineering A size, 8.5 inch by 11 inch.

B

public static final MediaSize B
Specifies the engineering B size, 11 inch by 17 inch.

C

public static final MediaSize C
Specifies the engineering C size, 17 inch by 22 inch.

D

public static final MediaSize D
Specifies the engineering D size, 22 inch by 34 inch.

E

public static final MediaSize E
Specifies the engineering E size, 34 inch by 44 inch.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MediaSize.ISO

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class MediaSize.ISO

java.lang.Object
    extended by  javax.print.attribute.standard.MediaSize.ISO
Enclosing class:
MediaSize
public static final class MediaSize.ISO
extends Object

Class MediaSize.ISO includes MediaSize values for ISO media.

Field Summary
static MediaSize | A0 Specifies the ISO A0 size, 841 mm by 1189 mm.
static MediaSize | A1 Specifies the ISO A1 size, 594 mm by 841 mm.
static MediaSize | A10 Specifies the ISO A10 size, 26 mm by 37 mm.
static MediaSize | A2 Specifies the ISO A2 size, 420 mm by 594 mm.
static MediaSize | A3 Specifies the ISO A3 size, 297 mm by 420 mm.
static MediaSize | A4 Specifies the ISO A4 size, 210 mm by 297 mm.
static MediaSize | A5 Specifies the ISO A5 size, 148 mm by 210 mm.
static MediaSize | A6 Specifies the ISO A6 size, 105 mm by 148 mm.
static MediaSize | A7 Specifies the ISO A7 size, 74 mm by 105 mm.
static MediaSize | A8 Specifies the ISO A8 size, 52 mm by 74 mm.
static MediaSize | A9 Specifies the ISO A9 size, 37 mm by 52 mm.
static MediaSize | B0 Specifies the ISO B0 size, 1000 mm by 1414 mm.
static MediaSize | B1 Specifies the ISO B1 size, 707 mm by 1000 mm.
static MediaSize | B10 Specifies the ISO B10 size, 31 mm by 44 mm.
static MediaSize | B2 Specifies the ISO B2 size, 500 mm by 707 mm.
static MediaSize | B3 Specifies the ISO B3 size, 353 mm by 500 mm.
static MediaSize | B4 Specifies the ISO B4 size, 250 mm by 353 mm.
static MediaSize | B5 Specifies the ISO B5 size, 176 mm by 250 mm.
static MediaSize | B6 Specifies the ISO B6 size, 125 mm by 176 mm.
static MediaSize | B7 Specifies the ISO B7 size, 88 mm by 125 mm.
static MediaSize | B8 Specifies the ISO B8 size, 62 mm by 88 mm.
static MediaSize | B9 Specifies the ISO B9 size, 44 mm by 62 mm.
static MediaSize | C3 Specifies the ISO C3 size, 324 mm by 458 mm.
static MediaSize | C4 Specifies the ISO C4 size, 229 mm by 324 mm.
static MediaSize | C5 Specifies the ISO C5 size, 162 mm by 229 mm.
static MediaSize | C6 Specifies the ISO C6 size, 114 mm by 162 mm.
static MediaSize | DESIGNATED_LONG Specifies the ISO Designated Long size, 110 mm by 220 mm.
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

A0

public static final MediaSize A0
Specifies the ISO A0 size, 841 mm by 1189 mm.

A1

public static final MediaSize A1
Specifies the ISO A1 size, 594 mm by 841 mm.

A2

public static final MediaSize A2
Specifies the ISO A2 size, 420 mm by 594 mm.

A3

public static final MediaSize A3
Specifies the ISO A3 size, 297 mm by 420 mm.

A4

public static final MediaSize A4
Specifies the ISO A4 size, 210 mm by 297 mm.

A5

public static final MediaSize A5
Specifies the ISO A5 size, 148 mm by 210 mm.

A6

public static final MediaSize A6
Specifies the ISO A6 size, 105 mm by 148 mm.

A7

public static final MediaSize A7
Specifies the ISO A7 size, 74 mm by 105 mm.

A8

public static final MediaSize A8
Specifies the ISO A8 size, 52 mm by 74 mm.

A9

public static final MediaSize A9
Specifies the ISO A9 size, 37 mm by 52 mm.

A10

public static final MediaSize A10
Specifies the ISO A10 size, 26 mm by 37 mm.

B0

public static final MediaSize B0
Specifies the ISO B0 size, 1000 mm by 1414 mm.

B1

public static final MediaSize B1
Specifies the ISO B1 size, 707 mm by 1000 mm.

B2

public static final MediaSize B2
Specifies the ISO B2 size, 500 mm by 707 mm.

B3

public static final MediaSize B3
Specifies the ISO B3 size, 353 mm by 500 mm.

B4

public static final MediaSize B4
Specifies the ISO B4 size, 250 mm by 353 mm.

B5

public static final MediaSize B5
Specifies the ISO B5 size, 176 mm by 250 mm.

B6

public static final MediaSize B6
Specifies the ISO B6 size, 125 mm by 176 mm.

B7

public static final MediaSize B7
Specifies the ISO B7 size, 88 mm by 125 mm.

B8

public static final MediaSize B8
Specifies the ISO B8 size, 62 mm by 88 mm.

B9

public static final MediaSize B9
Specifies the ISO B9 size, 44 mm by 62 mm.

B10

public static final MediaSize B10
Specifies the ISO B10 size, 31 mm by 44 mm.

C3

public static final MediaSize C3
Specifies the ISO C3 size, 324 mm by 458 mm.

C4

public static final MediaSize C4
Specifies the ISO C4 size, 229 mm by 324 mm.

C5

public static final MediaSize C5
Specifies the ISO C5 size, 162 mm by 229 mm.

C6

public static final MediaSize C6
Specifies the ISO C6 size, 114 mm by 162 mm.

DESIGNATED_LONG

public static final MediaSize DESIGNATED_LONG
Specifies the ISO Designated Long size, 110 mm by 220 mm.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MediaSize.JIS

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class MediaSize.JIS

java.lang.Object
    extended by  javax.print.attribute.standard.MediaSize.JIS
Enclosing class:
MediaSize
public static final class MediaSize.JIS
extends Object

Class MediaSize.JIS includes MediaSize values for JIS (Japanese) media. *

Field Summary
static MediaSize | B0 Specifies the JIS B0 size, 1030 mm by 1456 mm.
static MediaSize | B1 Specifies the JIS B1 size, 728 mm by 1030 mm.
static MediaSize | B10 Specifies the JIS B10 size, 32 mm by 45 mm.
static MediaSize | B2 Specifies the JIS B2 size, 515 mm by 728 mm.
static MediaSize | B3 Specifies the JIS B3 size, 364 mm by 515 mm.
static MediaSize | B4 Specifies the JIS B4 size, 257 mm by 364 mm.
static MediaSize | B5 Specifies the JIS B5 size, 182 mm by 257 mm.
static MediaSize | B6 Specifies the JIS B6 size, 128 mm by 182 mm.
static MediaSize | B7 Specifies the JIS B7 size, 91 mm by 128 mm.
static MediaSize | B8 Specifies the JIS B8 size, 64 mm by 91 mm.
static MediaSize | B9 Specifies the JIS B9 size, 45 mm by 64 mm.
static MediaSize | CHOU_1 Specifies the JIS Chou ("long") #1 envelope size, 142 mm by 332 mm.
static MediaSize | CHOU_2 Specifies the JIS Chou ("long") #2 envelope size, 119 mm by 277 mm.
static MediaSize | CHOU_3 Specifies the JIS Chou ("long") #3 envelope size, 120 mm by 235 mm.
static MediaSize | CHOU_30 Specifies the JIS Chou ("long") #30 envelope size, 92 mm by 235 mm.
static MediaSize | CHOU_4 Specifies the JIS Chou ("long") #4 envelope size, 90 mm by 205 mm.
static MediaSize | CHOU_40 Specifies the JIS Chou ("long") #40 envelope size, 90 mm by 225 mm.
static MediaSize | KAKU_0 Specifies the JIS Kaku ("square") #0 envelope size, 287 mm by 382 mm.
static MediaSize | KAKU_1 Specifies the JIS Kaku ("square") #1 envelope size, 270 mm by 382 mm.
static MediaSize | KAKU_2 Specifies the JIS Kaku ("square") #2 envelope size, 240 mm by 332 mm.
static MediaSize | KAKU_20 Specifies the JIS Kaku ("square") #20 envelope size, 229 mm by 324 mm.
static MediaSize | KAKU_3 Specifies the JIS Kaku ("square") #3 envelope size, 216 mm by 277 mm.
static MediaSize | KAKU_4 Specifies the JIS Kaku ("square") #4 envelope size, 197 mm by 267 mm.
static MediaSize | KAKU_5 Specifies the JIS Kaku ("square") #5 envelope size, 190 mm by 240 mm.
static MediaSize | KAKU_6 Specifies the JIS Kaku ("square") #6 envelope size, 162 mm by 229 mm.
static MediaSize | KAKU_7 Specifies the JIS Kaku ("square") #7 envelope size, 142 mm by 205 mm.
static MediaSize | KAKU_8 Specifies the JIS Kaku ("square") #8 envelope size, 119 mm by 197 mm.
static MediaSize | KAKU_A4 Specifies the JIS Kaku ("square") A4 envelope size, 228 mm by 312 mm.
static MediaSize | YOU_1 Specifies the JIS You ("Western") #1 envelope size, 120 mm by 176 mm.
static MediaSize | YOU_2 Specifies the JIS You ("Western") #2 envelope size, 114 mm by 162 mm.
static MediaSize | YOU_3 Specifies the JIS You ("Western") #3 envelope size, 98 mm by 148 mm.
static MediaSize | YOU_4 Specifies the JIS You ("Western") #4 envelope size, 105 mm by 235 mm.
static MediaSize | YOU_5 Specifies the JIS You ("Western") #5 envelope size, 95 mm by 217 mm.
static MediaSize | YOU_6 Specifies the JIS You ("Western") #6 envelope size, 98 mm by 190 mm.
static MediaSize | YOU_7 Specifies the JIS You ("Western") #7 envelope size, 92 mm by 165 mm.
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

B0

public static final MediaSize B0
Specifies the JIS B0 size, 1030 mm by 1456 mm.

B1

public static final MediaSize B1
Specifies the JIS B1 size, 728 mm by 1030 mm.

B2

public static final MediaSize B2
Specifies the JIS B2 size, 515 mm by 728 mm.

B3

public static final MediaSize B3
Specifies the JIS B3 size, 364 mm by 515 mm.

B4

public static final MediaSize B4
Specifies the JIS B4 size, 257 mm by 364 mm.

B5

public static final MediaSize B5
Specifies the JIS B5 size, 182 mm by 257 mm.

B6

public static final MediaSize B6
Specifies the JIS B6 size, 128 mm by 182 mm.

B7

public static final MediaSize B7
Specifies the JIS B7 size, 91 mm by 128 mm.

B8

public static final MediaSize B8
Specifies the JIS B8 size, 64 mm by 91 mm.

B9

public static final MediaSize B9
Specifies the JIS B9 size, 45 mm by 64 mm.

B10

public static final MediaSize B10
Specifies the JIS B10 size, 32 mm by 45 mm.

CHOU_1

public static final MediaSize CHOU_1
Specifies the JIS Chou ("long") #1 envelope size, 142 mm by 332 mm.

CHOU_2

public static final MediaSize CHOU_2
Specifies the JIS Chou ("long") #2 envelope size, 119 mm by 277 mm.

CHOU_3

public static final MediaSize CHOU_3
Specifies the JIS Chou ("long") #3 envelope size, 120 mm by 235 mm.

CHOU_4

public static final MediaSize CHOU_4
Specifies the JIS Chou ("long") #4 envelope size, 90 mm by 205 mm.

CHOU_30

public static final MediaSize CHOU_30
Specifies the JIS Chou ("long") #30 envelope size, 92 mm by 235 mm.

CHOU_40

public static final MediaSize CHOU_40
Specifies the JIS Chou ("long") #40 envelope size, 90 mm by 225 mm.

KAKU_0

public static final MediaSize KAKU_0
Specifies the JIS Kaku ("square") #0 envelope size, 287 mm by 382 mm.

KAKU_1

public static final MediaSize KAKU_1
Specifies the JIS Kaku ("square") #1 envelope size, 270 mm by 382 mm.

KAKU_2

public static final MediaSize KAKU_2
Specifies the JIS Kaku ("square") #2 envelope size, 240 mm by 332 mm.

KAKU_3

public static final MediaSize KAKU_3
Specifies the JIS Kaku ("square") #3 envelope size, 216 mm by 277 mm.

KAKU_4

public static final MediaSize KAKU_4
Specifies the JIS Kaku ("square") #4 envelope size, 197 mm by 267 mm.

KAKU_5

public static final MediaSize KAKU_5
Specifies the JIS Kaku ("square") #5 envelope size, 190 mm by 240 mm.

KAKU_6

public static final MediaSize KAKU_6
Specifies the JIS Kaku ("square") #6 envelope size, 162 mm by 229 mm.

KAKU_7

public static final MediaSize KAKU_7
Specifies the JIS Kaku ("square") #7 envelope size, 142 mm by 205 mm.

KAKU_8

public static final MediaSize KAKU_8
Specifies the JIS Kaku ("square") #8 envelope size, 119 mm by 197 mm.

KAKU_20

public static final MediaSize KAKU_20
Specifies the JIS Kaku ("square") #20 envelope size, 229 mm by 324 mm.

KAKU_A4

public static final MediaSize KAKU_A4
Specifies the JIS Kaku ("square") A4 envelope size, 228 mm by 312 mm.

YOU_1

public static final MediaSize YOU_1
Specifies the JIS You ("Western") #1 envelope size, 120 mm by 176 mm.

YOU_2

public static final MediaSize YOU_2
Specifies the JIS You ("Western") #2 envelope size, 114 mm by 162 mm.

YOU_3

public static final MediaSize YOU_3
Specifies the JIS You ("Western") #3 envelope size, 98 mm by 148 mm.

YOU_4

public static final MediaSize YOU_4
Specifies the JIS You ("Western") #4 envelope size, 105 mm by 235 mm.

YOU_5

public static final MediaSize YOU_5
Specifies the JIS You ("Western") #5 envelope size, 95 mm by 217 mm.

YOU_6

public static final MediaSize YOU_6
Specifies the JIS You ("Western") #6 envelope size, 98 mm by 190 mm.

YOU_7

public static final MediaSize YOU_7
Specifies the JIS You ("Western") #7 envelope size, 92 mm by 165 mm.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MediaSize.NA

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class MediaSize.NA

java.lang.Object
    extended by  javax.print.attribute.standard.MediaSize.NA
Enclosing class:
MediaSize
public static final class MediaSize.NA
extends Object

Class MediaSize.NA includes MediaSize values for North American media.

Field Summary
static MediaSize | LEGAL Specifies the North American legal size, 8.5 inches by 14 inches.
static MediaSize | LETTER Specifies the North American letter size, 8.5 inches by 11 inches.
static MediaSize | NA_10x13_ENVELOPE Specifies the North American 10 inch by 13 inch envelope size.
static MediaSize | NA_10x14_ENVELOPE Specifies the North American 10 inch by 14 inch envelope size.
static MediaSize | NA_10X15_ENVELOPE Specifies the North American 10 inch by 15 inch envelope size.
static MediaSize | NA_5X7 Specifies the North American 5 inch by 7 inch paper.
static MediaSize | NA_6X9_ENVELOPE Specifies the North American 6 inch by 9 inch envelope size.
static MediaSize | NA_7X9_ENVELOPE Specifies the North American 7 inch by 9 inch envelope size.
static MediaSize | NA_8X10 Specifies the North American 8 inch by 10 inch paper.
static MediaSize | NA_9x11_ENVELOPE Specifies the North American 9 inch by 11 inch envelope size.
static MediaSize | NA_9x12_ENVELOPE Specifies the North American 9 inch by 12 inch envelope size.
static MediaSize | NA_NUMBER_10_ENVELOPE Specifies the North American Number 10 business envelope size, 4.125 inches by 9.5 inches.
static MediaSize | NA_NUMBER_11_ENVELOPE Specifies the North American Number 11 business envelope size, 4.5 inches by 10.375 inches.
static MediaSize | NA_NUMBER_12_ENVELOPE Specifies the North American Number 12 business envelope size, 4.75 inches by 11 inches.
static MediaSize | NA_NUMBER_14_ENVELOPE Specifies the North American Number 14 business envelope size, 5 inches by 11.5 inches.
static MediaSize | NA_NUMBER_9_ENVELOPE Specifies the North American Number 9 business envelope size, 3.875 inches by 8.875 inches.
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LETTER

public static final MediaSize LETTER
Specifies the North American letter size, 8.5 inches by 11 inches.

LEGAL

public static final MediaSize LEGAL
Specifies the North American legal size, 8.5 inches by 14 inches.

NA_5X7

public static final MediaSize NA_5X7
Specifies the North American 5 inch by 7 inch paper.

NA_8X10

public static final MediaSize NA_8X10
Specifies the North American 8 inch by 10 inch paper.

NA_NUMBER_9_ENVELOPE

public static final MediaSize NA_NUMBER_9_ENVELOPE
Specifies the North American Number 9 business envelope size, 3.875 inches by 8.875 inches.

NA_NUMBER_10_ENVELOPE

public static final MediaSize NA_NUMBER_10_ENVELOPE
Specifies the North American Number 10 business envelope size, 4.125 inches by 9.5 inches.

NA_NUMBER_11_ENVELOPE

public static final MediaSize NA_NUMBER_11_ENVELOPE
Specifies the North American Number 11 business envelope size, 4.5 inches by 10.375 inches.

NA_NUMBER_12_ENVELOPE

public static final MediaSize NA_NUMBER_12_ENVELOPE
Specifies the North American Number 12 business envelope size, 4.75 inches by 11 inches.

NA_NUMBER_14_ENVELOPE

public static final MediaSize NA_NUMBER_14_ENVELOPE
Specifies the North American Number 14 business envelope size, 5 inches by 11.5 inches.

NA_6X9_ENVELOPE

public static final MediaSize NA_6X9_ENVELOPE
Specifies the North American 6 inch by 9 inch envelope size.

NA_7X9_ENVELOPE

public static final MediaSize NA_7X9_ENVELOPE
Specifies the North American 7 inch by 9 inch envelope size.

NA_9x11_ENVELOPE

public static final MediaSize NA_9x11_ENVELOPE
Specifies the North American 9 inch by 11 inch envelope size.

NA_9x12_ENVELOPE

public static final MediaSize NA_9x12_ENVELOPE
Specifies the North American 9 inch by 12 inch envelope size.

NA_10x13_ENVELOPE

public static final MediaSize NA_10x13_ENVELOPE
Specifies the North American 10 inch by 13 inch envelope size.

NA_10x14_ENVELOPE

public static final MediaSize NA_10x14_ENVELOPE
Specifies the North American 10 inch by 14 inch envelope size.

NA_10X15_ENVELOPE

public static final MediaSize NA_10X15_ENVELOPE
Specifies the North American 10 inch by 15 inch envelope size.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MediaSize.Other

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class MediaSize.Other

java.lang.Object
    extended by  javax.print.attribute.standard.MediaSize.Other
Enclosing class:
MediaSize
public static final class MediaSize.Other
extends Object

Class MediaSize.Other includes MediaSize values for miscellaneous media.

Field Summary
static MediaSize | EXECUTIVE Specifies the executive size, 7.25 inches by 10.5 inches.
static MediaSize | FOLIO Specifies the folio size, 8.5 inches by 13 inches.
static MediaSize | INVOICE Specifies the invoice size, 5.5 inches by 8.5 inches.
static MediaSize | ITALY_ENVELOPE Specifies the Italy envelope size, 110 mm by 230 mm.
static MediaSize | JAPANESE_DOUBLE_POSTCARD Specifies the Japanese Double postcard size, 148 mm by 200 mm.
static MediaSize | JAPANESE_POSTCARD Specifies the Japanese postcard size, 100 mm by 148 mm.
static MediaSize | LEDGER Specifies the ledger size, 11 inches by 17 inches.
static MediaSize | MONARCH_ENVELOPE Specifies the Monarch envelope size, 3.87 inch by 7.5 inch.
static MediaSize | PERSONAL_ENVELOPE Specifies the Personal envelope size, 3.625 inch by 6.5 inch.
static MediaSize | QUARTO Specifies the quarto size, 8.5 inches by 10.83 inches.
static MediaSize | TABLOID Specifies the tabloid size, 11 inches by 17 inches.
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EXECUTIVE

public static final MediaSize EXECUTIVE
Specifies the executive size, 7.25 inches by 10.5 inches.

LEDGER

public static final MediaSize LEDGER
Specifies the ledger size, 11 inches by 17 inches.

TABLOID

public static final MediaSize TABLOID
Specifies the tabloid size, 11 inches by 17 inches.

Since:
1.5

INVOICE

public static final MediaSize INVOICE
Specifies the invoice size, 5.5 inches by 8.5 inches.

FOLIO

public static final MediaSize FOLIO
Specifies the folio size, 8.5 inches by 13 inches.

QUARTO

public static final MediaSize QUARTO
Specifies the quarto size, 8.5 inches by 10.83 inches.

ITALY_ENVELOPE

public static final MediaSize ITALY_ENVELOPE
Specifies the Italy envelope size, 110 mm by 230 mm.

MONARCH_ENVELOPE

public static final MediaSize MONARCH_ENVELOPE
Specifies the Monarch envelope size, 3.87 inch by 7.5 inch.

PERSONAL_ENVELOPE

public static final MediaSize PERSONAL_ENVELOPE
Specifies the Personal envelope size, 3.625 inch by 6.5 inch.

JAPANESE_POSTCARD

public static final MediaSize JAPANESE_POSTCARD
Specifies the Japanese postcard size, 100 mm by 148 mm.

JAPANESE_DOUBLE_POSTCARD

public static final MediaSize JAPANESE_DOUBLE_POSTCARD
Specifies the Japanese Double postcard size, 148 mm by 200 mm.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MediaSizeName

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class MediaSizeName

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.Media
            extended by  javax.print.attribute.standard.MediaSizeName
All Implemented Interfaces:
Serializable, Cloneable, Attribute, DocAttribute, PrintJobAttribute, PrintRequestAttribute
public class MediaSizeName
extends Media

Class MediaSizeName is a subclass of Media.

This attribute can be used instead of specifying MediaName or MediaTray.

Class MediaSizeName currently declares a few standard media name values.

IPP Compatibility: MediaSizeName is a representation class for values of the IPP "media" attribute which names media sizes. The names of the media sizes correspond to those in the IPP 1.1 RFC RFC 2911

See Also:
Serialized Form

Field Summary
static MediaSizeName | A A size .
static MediaSizeName | B B size .
static MediaSizeName | C C size .
static MediaSizeName | D D size .
static MediaSizeName | E E size .
static MediaSizeName | EXECUTIVE executive size .
static MediaSizeName | FOLIO folio size .
static MediaSizeName | INVOICE invoice size .
static MediaSizeName | ISO_A0 A0 size.
static MediaSizeName | ISO_A1 A1 size.
static MediaSizeName | ISO_A10 A10 size.
static MediaSizeName | ISO_A2 A2 size.
static MediaSizeName | ISO_A3 A3 size.
static MediaSizeName | ISO_A4 A4 size.
static MediaSizeName | ISO_A5 A5 size.
static MediaSizeName | ISO_A6 A6 size.
static MediaSizeName | ISO_A7 A7 size.
static MediaSizeName | ISO_A8 A8 size.
static MediaSizeName | ISO_A9 A9 size.
static MediaSizeName | ISO_B0 ISO B0 size.
static MediaSizeName | ISO_B1 ISO B1 size.
static MediaSizeName | ISO_B10 ISO B10 size.
static MediaSizeName | ISO_B2 ISO B2 size.
static MediaSizeName | ISO_B3 ISO B3 size.
static MediaSizeName | ISO_B4 ISO B4 size.
static MediaSizeName | ISO_B5 ISO B5 size.
static MediaSizeName | ISO_B6 ISO B6 size.
static MediaSizeName | ISO_B7 ISO B7 size.
static MediaSizeName | ISO_B8 ISO B8 size.
static MediaSizeName | ISO_B9 ISO B9 size.
static MediaSizeName | ISO_C0 ISO C0 size.
static MediaSizeName | ISO_C1 ISO C1 size.
static MediaSizeName | ISO_C2 ISO C2 size.
static MediaSizeName | ISO_C3 ISO C3 size.
static MediaSizeName | ISO_C4 ISO C4 size.
static MediaSizeName | ISO_C5 ISO C5 size.
static MediaSizeName | ISO_C6 letter size.
static MediaSizeName | ISO_DESIGNATED_LONG ISO designated long size .
static MediaSizeName | ITALY_ENVELOPE Italy envelope size .
static MediaSizeName | JAPANESE_DOUBLE_POSTCARD Japanese Double Postcard size.
static MediaSizeName | JAPANESE_POSTCARD Japanese Postcard size.
static MediaSizeName | JIS_B0 JIS B0 size.
static MediaSizeName | JIS_B1 JIS B1 size.
static MediaSizeName | JIS_B10 JIS B10 size.
static MediaSizeName | JIS_B2 JIS B2 size.
static MediaSizeName | JIS_B3 JIS B3 size.
static MediaSizeName | JIS_B4 JIS B4 size.
static MediaSizeName | JIS_B5 JIS B5 size.
static MediaSizeName | JIS_B6 JIS B6 size.
static MediaSizeName | JIS_B7 JIS B7 size.
static MediaSizeName | JIS_B8 JIS B8 size.
static MediaSizeName | JIS_B9 JIS B9 size.
static MediaSizeName | LEDGER ledger size .
static MediaSizeName | MONARCH_ENVELOPE monarch envelope size .
static MediaSizeName | NA_10X13_ENVELOPE 10x13 North American envelope size .
static MediaSizeName | NA_10X14_ENVELOPE 10x14North American envelope size .
static MediaSizeName | NA_10X15_ENVELOPE 10x15 North American envelope size.
static MediaSizeName | NA_5X7 5x7 North American paper.
static MediaSizeName | NA_6X9_ENVELOPE 6x9 North American envelope size.
static MediaSizeName | NA_7X9_ENVELOPE 7x9 North American envelope size.
static MediaSizeName | NA_8X10 8x10 North American paper.
static MediaSizeName | NA_9X11_ENVELOPE 9x11 North American envelope size.
static MediaSizeName | NA_9X12_ENVELOPE 9x12 North American envelope size.
static MediaSizeName | NA_LEGAL legal size .
static MediaSizeName | NA_LETTER letter size.
static MediaSizeName | NA_NUMBER_10_ENVELOPE number 10 envelope size .
static MediaSizeName | NA_NUMBER_11_ENVELOPE number 11 envelope size .
static MediaSizeName | NA_NUMBER_12_ENVELOPE number 12 envelope size .
static MediaSizeName | NA_NUMBER_14_ENVELOPE number 14 envelope size .
static MediaSizeName | NA_NUMBER_9_ENVELOPE number 9 envelope size .
static MediaSizeName | PERSONAL_ENVELOPE personal envelope size .
static MediaSizeName | QUARTO quarto size .
static MediaSizeName | TABLOID tabloid size .
Constructor Summary
protected MediaSizeName(int value)
Construct a new media size enumeration value with the given integer value.
Method Summary
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class MediaSizeName.
protected String[] | getStringTable() Returns the string table for class MediaSizeName.
Methods inherited from class javax.print.attribute.standard.Media
equals, getCategory, getName
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ISO_A0

public static final MediaSizeName ISO_A0
A0 size.

ISO_A1

public static final MediaSizeName ISO_A1
A1 size.

ISO_A2

public static final MediaSizeName ISO_A2
A2 size.

ISO_A3

public static final MediaSizeName ISO_A3
A3 size.

ISO_A4

public static final MediaSizeName ISO_A4
A4 size.

ISO_A5

public static final MediaSizeName ISO_A5
A5 size.

ISO_A6

public static final MediaSizeName ISO_A6
A6 size.

ISO_A7

public static final MediaSizeName ISO_A7
A7 size.

ISO_A8

public static final MediaSizeName ISO_A8
A8 size.

ISO_A9

public static final MediaSizeName ISO_A9
A9 size.

ISO_A10

public static final MediaSizeName ISO_A10
A10 size.

ISO_B0

public static final MediaSizeName ISO_B0
ISO B0 size.

ISO_B1

public static final MediaSizeName ISO_B1
ISO B1 size.

ISO_B2

public static final MediaSizeName ISO_B2
ISO B2 size.

ISO_B3

public static final MediaSizeName ISO_B3
ISO B3 size.

ISO_B4

public static final MediaSizeName ISO_B4
ISO B4 size.

ISO_B5

public static final MediaSizeName ISO_B5
ISO B5 size.

ISO_B6

public static final MediaSizeName ISO_B6
ISO B6 size.

ISO_B7

public static final MediaSizeName ISO_B7
ISO B7 size.

ISO_B8

public static final MediaSizeName ISO_B8
ISO B8 size.

ISO_B9

public static final MediaSizeName ISO_B9
ISO B9 size.

ISO_B10

public static final MediaSizeName ISO_B10
ISO B10 size.

JIS_B0

public static final MediaSizeName JIS_B0
JIS B0 size.

JIS_B1

public static final MediaSizeName JIS_B1
JIS B1 size.

JIS_B2

public static final MediaSizeName JIS_B2
JIS B2 size.

JIS_B3

public static final MediaSizeName JIS_B3
JIS B3 size.

JIS_B4

public static final MediaSizeName JIS_B4
JIS B4 size.

JIS_B5

public static final MediaSizeName JIS_B5
JIS B5 size.

JIS_B6

public static final MediaSizeName JIS_B6
JIS B6 size.

JIS_B7

public static final MediaSizeName JIS_B7
JIS B7 size.

JIS_B8

public static final MediaSizeName JIS_B8
JIS B8 size.

JIS_B9

public static final MediaSizeName JIS_B9
JIS B9 size.

JIS_B10

public static final MediaSizeName JIS_B10
JIS B10 size.

ISO_C0

public static final MediaSizeName ISO_C0
ISO C0 size.

ISO_C1

public static final MediaSizeName ISO_C1
ISO C1 size.

ISO_C2

public static final MediaSizeName ISO_C2
ISO C2 size.

ISO_C3

public static final MediaSizeName ISO_C3
ISO C3 size.

ISO_C4

public static final MediaSizeName ISO_C4
ISO C4 size.

ISO_C5

public static final MediaSizeName ISO_C5
ISO C5 size.

ISO_C6

public static final MediaSizeName ISO_C6
letter size.

NA_LETTER

public static final MediaSizeName NA_LETTER
letter size.

NA_LEGAL

public static final MediaSizeName NA_LEGAL
legal size .

EXECUTIVE

public static final MediaSizeName EXECUTIVE
executive size .

LEDGER

public static final MediaSizeName LEDGER
ledger size .

TABLOID

public static final MediaSizeName TABLOID
tabloid size .

INVOICE

public static final MediaSizeName INVOICE
invoice size .

FOLIO

public static final MediaSizeName FOLIO
folio size .

QUARTO

public static final MediaSizeName QUARTO
quarto size .

JAPANESE_POSTCARD

public static final MediaSizeName JAPANESE_POSTCARD
Japanese Postcard size.

JAPANESE_DOUBLE_POSTCARD

public static final MediaSizeName JAPANESE_DOUBLE_POSTCARD
Japanese Double Postcard size.

A

public static final MediaSizeName A
A size .

B

public static final MediaSizeName B
B size .

C

public static final MediaSizeName C
C size .

D

public static final MediaSizeName D
D size .

E

public static final MediaSizeName E
E size .

ISO_DESIGNATED_LONG

public static final MediaSizeName ISO_DESIGNATED_LONG
ISO designated long size .

ITALY_ENVELOPE

public static final MediaSizeName ITALY_ENVELOPE
Italy envelope size .

MONARCH_ENVELOPE

public static final MediaSizeName MONARCH_ENVELOPE
monarch envelope size .

PERSONAL_ENVELOPE

public static final MediaSizeName PERSONAL_ENVELOPE
personal envelope size .

NA_NUMBER_9_ENVELOPE

public static final MediaSizeName NA_NUMBER_9_ENVELOPE
number 9 envelope size .

NA_NUMBER_10_ENVELOPE

public static final MediaSizeName NA_NUMBER_10_ENVELOPE
number 10 envelope size .

NA_NUMBER_11_ENVELOPE

public static final MediaSizeName NA_NUMBER_11_ENVELOPE
number 11 envelope size .

NA_NUMBER_12_ENVELOPE

public static final MediaSizeName NA_NUMBER_12_ENVELOPE
number 12 envelope size .

NA_NUMBER_14_ENVELOPE

public static final MediaSizeName NA_NUMBER_14_ENVELOPE
number 14 envelope size .

NA_6X9_ENVELOPE

public static final MediaSizeName NA_6X9_ENVELOPE
6x9 North American envelope size.

NA_7X9_ENVELOPE

public static final MediaSizeName NA_7X9_ENVELOPE
7x9 North American envelope size.

NA_9X11_ENVELOPE

public static final MediaSizeName NA_9X11_ENVELOPE
9x11 North American envelope size.

NA_9X12_ENVELOPE

public static final MediaSizeName NA_9X12_ENVELOPE
9x12 North American envelope size.

NA_10X13_ENVELOPE

public static final MediaSizeName NA_10X13_ENVELOPE
10x13 North American envelope size .

NA_10X14_ENVELOPE

public static final MediaSizeName NA_10X14_ENVELOPE
10x14North American envelope size .

NA_10X15_ENVELOPE

public static final MediaSizeName NA_10X15_ENVELOPE
10x15 North American envelope size.

NA_5X7

public static final MediaSizeName NA_5X7
5x7 North American paper.

NA_8X10

public static final MediaSizeName NA_8X10
8x10 North American paper.

Constructor Detail

MediaSizeName

protected MediaSizeName(int value)
Construct a new media size enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class MediaSizeName.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class MediaSizeName.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MediaTray

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class MediaTray

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.Media
            extended by  javax.print.attribute.standard.MediaTray
All Implemented Interfaces:
Serializable, Cloneable, Attribute, DocAttribute, PrintJobAttribute, PrintRequestAttribute
public class MediaTray
extends Media
implements Attribute

Class MediaTray is a subclass of Media. Class MediaTray is a printing attribute class, an enumeration, that specifies the media tray or bin for the job. This attribute can be used instead of specifying MediaSize or MediaName.

Class MediaTray declares keywords for standard media kind values. Implementation- or site-defined names for a media kind attribute may also be created by defining a subclass of class MediaTray.

IPP Compatibility: MediaTray is a representation class for values of the IPP "media" attribute which name paper trays.

See Also:
Serialized Form

Field Summary
static MediaTray | BOTTOM The bottom input tray in the printer.
static MediaTray | ENVELOPE The envelope input tray in the printer.
static MediaTray | LARGE_CAPACITY The large capacity input tray in the printer.
static MediaTray | MAIN The main input tray in the printer.
static MediaTray | MANUAL The manual feed input tray in the printer.
static MediaTray | MIDDLE The middle input tray in the printe.
static MediaTray | SIDE The side input tray.
static MediaTray | TOP The top input tray in the printer.
Constructor Summary
protected MediaTray(int value)
Construct a new media tray enumeration value with the given integer value.
Method Summary
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class MediaTray.
protected String[] | getStringTable() Returns the string table for class MediaTray.
Methods inherited from class javax.print.attribute.standard.Media
equals, getCategory, getName
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface javax.print.attribute.Attribute
getCategory, getName

Field Detail

TOP

public static final MediaTray TOP
The top input tray in the printer.

MIDDLE

public static final MediaTray MIDDLE
The middle input tray in the printe.

BOTTOM

public static final MediaTray BOTTOM
The bottom input tray in the printer.

ENVELOPE

public static final MediaTray ENVELOPE
The envelope input tray in the printer.

MANUAL

public static final MediaTray MANUAL
The manual feed input tray in the printer.

LARGE_CAPACITY

public static final MediaTray LARGE_CAPACITY
The large capacity input tray in the printer.

MAIN

public static final MediaTray MAIN
The main input tray in the printer.

SIDE

public static final MediaTray SIDE
The side input tray.

Constructor Detail

MediaTray

protected MediaTray(int value)
Construct a new media tray enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class MediaTray.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class MediaTray.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultipleDocumentHandling

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class MultipleDocumentHandling

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.MultipleDocumentHandling
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute, PrintRequestAttribute
public class MultipleDocumentHandling
extends EnumSyntax
implements PrintRequestAttribute, PrintJobAttribute

Class MultipleDocumentHandling is a printing attribute class, an enumeration, that controls finishing operations and the placement of one or more print-stream pages into impressions and onto media sheets. When the value of the Copies attribute exceeds 1, MultipleDocumentHandling also controls the order in which the copies that result from processing the documents are produced. This attribute is relevant only for a multidoc print job consisting of two or more individual docs.

Briefly, MultipleDocumentHandling determines the relationship between the multiple input (electronic) documents fed into a multidoc print job and the output (physical) document or documents produced by the multidoc print job. There are two possibilities:

  • The multiple input documents are combined into a single output document. Finishing operations (Finishings), are performed on this single output document. The Copies attribute tells how many copies of this single output document to produce. The MultipleDocumentHandling values SINGLE_DOCUMENT and SINGLE_DOCUMENT_NEW_SHEET specify two variations of this possibility.

  • The multiple input documents remain separate output documents. Finishing operations (Finishings), are performed on each output document separately. The Copies attribute tells how many copies of each separate output document to produce. The MultipleDocumentHandling values SEPARATE_DOCUMENTS_UNCOLLATED_COPIES and SEPARATE_DOCUMENTS_COLLATED_COPIES specify two variations of this possibility.

In the detailed explanations below, if "a" represents an instance of document data, then the result of processing the data in document "a" is a sequence of media sheets represented by "a(*)".

The standard MultipleDocumentHandling values are:

  • SINGLE_DOCUMENT. If a print job has multiple documents -- say, the document data is called a and b -- then the result of processing all the document data (a and then b) must be treated as a single sequence of media sheets for finishing operations; that is, finishing would be performed on the concatenation of the sequences a(*),b(*). The printer must not force the data in each document instance to be formatted onto a new print-stream page, nor to start a new impression on a new media sheet. If more than one copy is made, the ordering of the sets of media sheets resulting from processing the document data must be a(*),b(*),a(*),b(*),..., and the printer object must force each copy (a(*),b(*)) to start on a new media sheet.

  • SEPARATE_DOCUMENTS_UNCOLLATED_COPIES. If a print job has multiple documents -- say, the document data is called a and b -- then the result of processing the data in each document instance must be treated as a single sequence of media sheets for finishing operations; that is, the sets a(*) and b(*) would each be finished separately. The printer must force each copy of the result of processing the data in a single document to start on a new media sheet. If more than one copy is made, the ordering of the sets of media sheets resulting from processing the document data must be a(*),a(*),...,b(*),b(*)....

  • SEPARATE_DOCUMENTS_COLLATED_COPIES. If a print job has multiple documents -- say, the document data is called a and b -- then the result of processing the data in each document instance must be treated as a single sequence of media sheets for finishing operations; that is, the sets a(*) and b(*) would each be finished separately. The printer must force each copy of the result of processing the data in a single document to start on a new media sheet. If more than one copy is made, the ordering of the sets of media sheets resulting from processing the document data must be a(*),b(*),a(*),b(*),....

  • SINGLE_DOCUMENT_NEW_SHEET. Same as SINGLE_DOCUMENT, except that the printer must ensure that the first impression of each document instance in the job is placed on a new media sheet. This value allows multiple documents to be stapled together with a single staple where each document starts on a new sheet.

SINGLE_DOCUMENT is the same as SEPARATE_DOCUMENTS_COLLATED_COPIES with respect to ordering of print-stream pages, but not media sheet generation, since SINGLE_DOCUMENT will put the first page of the next document on the back side of a sheet if an odd number of pages have been produced so far for the job, while SEPARATE_DOCUMENTS_COLLATED_COPIES always forces the next document or document copy on to a new sheet.

In addition, if a Finishings attribute of STAPLE is specified, then:

  • With SINGLE_DOCUMENT, documents a and b are stapled together as a single document with no regard to new sheets.

  • With SINGLE_DOCUMENT_NEW_SHEET, documents a and b are stapled together as a single document, but document b starts on a new sheet.

  • With SEPARATE_DOCUMENTS_UNCOLLATED_COPIES and SEPARATE_DOCUMENTS_COLLATED_COPIES, documents a and b are stapled separately.

Note: None of these values provide means to produce uncollated sheets within a document, i.e., where multiple copies of sheet n are produced before sheet n+1 of the same document. To specify that, see the SheetCollate attribute.

IPP Compatibility: The category name returned by getName() is the IPP attribute name. The enumeration's integer value is the IPP enum value. The toString() method returns the IPP string representation of the attribute value.

See Also:
Copies, Finishings, NumberUp, PageRanges, SheetCollate, Sides, Serialized Form

Field Summary
static MultipleDocumentHandling | SEPARATE_DOCUMENTS_COLLATED_COPIES Separate documents collated copies -- see above for further information.
static MultipleDocumentHandling | SEPARATE_DOCUMENTS_UNCOLLATED_COPIES Separate documents uncollated copies -- see above for further information.
static MultipleDocumentHandling | SINGLE_DOCUMENT Single document -- see above for further information.
static MultipleDocumentHandling | SINGLE_DOCUMENT_NEW_SHEET Single document new sheet -- see above for further information.
Constructor Summary
protected MultipleDocumentHandling(int value)
Construct a new multiple document handling enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class MultipleDocumentHandling.
String | getName() Get the name of the category of which this attribute value is an instance.
protected String[] | getStringTable() Returns the string table for class MultipleDocumentHandling.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

SINGLE_DOCUMENT

public static final MultipleDocumentHandling SINGLE_DOCUMENT
Single document -- see above for further information.

SEPARATE_DOCUMENTS_UNCOLLATED_COPIES

public static final MultipleDocumentHandling SEPARATE_DOCUMENTS_UNCOLLATED_COPIES
Separate documents uncollated copies -- see above for further information.

SEPARATE_DOCUMENTS_COLLATED_COPIES

public static final MultipleDocumentHandling SEPARATE_DOCUMENTS_COLLATED_COPIES
Separate documents collated copies -- see above for further information.

SINGLE_DOCUMENT_NEW_SHEET

public static final MultipleDocumentHandling SINGLE_DOCUMENT_NEW_SHEET
Single document new sheet -- see above for further information.

Constructor Detail

MultipleDocumentHandling

protected MultipleDocumentHandling(int value)
Construct a new multiple document handling enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class MultipleDocumentHandling.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class MultipleDocumentHandling.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class MultipleDocumentHandling and any vendor-defined subclasses, the category is class MultipleDocumentHandling itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class MultipleDocumentHandling and any vendor-defined subclasses, the category name is "multiple-document-handling".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NumberOfDocuments

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class NumberOfDocuments

java.lang.Object
    extended by  javax.print.attribute.IntegerSyntax
        extended by  javax.print.attribute.standard.NumberOfDocuments
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute
public final class NumberOfDocuments
extends IntegerSyntax
implements PrintJobAttribute

Class NumberOfDocuments is an integer valued printing attribute that indicates the number of individual docs the printer has accepted for this job, regardless of whether the docs' print data has reached the printer or not.

IPP Compatibility: The integer value gives the IPP integer value. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
NumberOfDocuments(int value)
Construct a new number of documents attribute with the given integer value.
Method Summary
boolean | equals(Object object) Returns whether this number of documents attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.IntegerSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

NumberOfDocuments

public NumberOfDocuments(int value)
Construct a new number of documents attribute with the given integer value.

Parameters:
value - Integer value.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if value is less than 0.
Method Detail

equals

public boolean equals(Object object)
Returns whether this number of documents attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class NumberOfDocuments.
  3. This number of documents attribute's value and object's value are equal.

Overrides:
equals in class IntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this number of documents attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class NumberOfDocuments, the category is class NumberOfDocuments itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class NumberOfDocuments, the category name is "number-of-documents".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NumberOfInterveningJobs

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class NumberOfInterveningJobs

java.lang.Object
    extended by  javax.print.attribute.IntegerSyntax
        extended by  javax.print.attribute.standard.NumberOfInterveningJobs
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute
public final class NumberOfInterveningJobs
extends IntegerSyntax
implements PrintJobAttribute

Class NumberOfInterveningJobs is an integer valued printing attribute that indicates the number of jobs that are ahead of this job in the relative chronological order of expected time to complete (i.e., the current scheduled order).

IPP Compatibility: The integer value gives the IPP integer value. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
NumberOfInterveningJobs(int value)
Construct a new number of intervening jobs attribute with the given integer value.
Method Summary
boolean | equals(Object object) Returns whether this number of intervening jobs attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.IntegerSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

NumberOfInterveningJobs

public NumberOfInterveningJobs(int value)
Construct a new number of intervening jobs attribute with the given integer value.

Parameters:
value - Integer value.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if value is less than 0.
Method Detail

equals

public boolean equals(Object object)
Returns whether this number of intervening jobs attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class NumberOfInterveningJobs.
  3. This number of intervening jobs attribute's value and object's value are equal.

Overrides:
equals in class IntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this number of intervening jobs attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class NumberOfInterveningJobs, the category is class NumberOfInterveningJobs itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class NumberOfInterveningJobs, the category name is "number-of-intervening-jobs".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NumberUp

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class NumberUp

java.lang.Object
    extended by  javax.print.attribute.IntegerSyntax
        extended by  javax.print.attribute.standard.NumberUp
All Implemented Interfaces:
Serializable, Cloneable, Attribute, DocAttribute, PrintJobAttribute, PrintRequestAttribute
public final class NumberUp
extends IntegerSyntax
implements DocAttribute, PrintRequestAttribute, PrintJobAttribute

Class NumberUp is an integer valued printing attribute class that specifies the number of print-stream pages to impose upon a single side of an instance of a selected medium. That is, if the NumberUp value is n, the printer must place n print-stream pages on a single side of an instance of the selected medium. To accomplish this, the printer may add some sort of translation, scaling, or rotation. This attribute primarily controls the translation, scaling and rotation of print-stream pages.

The effect of a NumberUp attribute on a multidoc print job (a job with multiple documents) depends on whether all the docs have the same number up values specified or whether different docs have different number up values specified, and on the (perhaps defaulted) value of the MultipleDocumentHandling attribute.

  • If all the docs have the same number up value n specified, then any value of MultipleDocumentHandling makes sense, and the printer's processing depends on the MultipleDocumentHandling value:
    • SINGLE_DOCUMENT -- All the input docs will be combined together into one output document. Each media impression will consist of nm print-stream pages from the output document.

    • SINGLE_DOCUMENT_NEW_SHEET -- All the input docs will be combined together into one output document. Each media impression will consist of n print-stream pages from the output document. However, the first impression of each input doc will always start on a new media sheet; this means the last impression of an input doc may have fewer than n print-stream pages on it.

    • SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- The input docs will remain separate. Each media impression will consist of n print-stream pages from the input doc. Since the input docs are separate, the first impression of each input doc will always start on a new media sheet; this means the last impression of an input doc may have fewer than n print-stream pages on it.

    • SEPARATE_DOCUMENTS_COLLATED_COPIES -- The input docs will remain separate. Each media impression will consist of n print-stream pages from the input doc. Since the input docs are separate, the first impression of each input doc will always start on a new media sheet; this means the last impression of an input doc may have fewer than n print-stream pages on it.
    • SINGLE_DOCUMENT -- All the input docs will be combined together into one output document. Each media impression will consist of ni print-stream pages from the output document, where i is the number of the input doc corresponding to that point in the output document. When the next input doc has a different number up value from the previous input doc, the first print-stream page of the next input doc goes at the start of the next media impression, possibly leaving fewer than the full number of print-stream pages on the previous media impression.

    • SINGLE_DOCUMENT_NEW_SHEET -- All the input docs will be combined together into one output document. Each media impression will consist of n print-stream pages from the output document. However, the first impression of each input doc will always start on a new media sheet; this means the last impression of an input doc may have fewer than n print-stream pages on it.

    • SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- The input docs will remain separate. For input doc i, each media impression will consist of ni print-stream pages from the input doc. Since the input docs are separate, the first impression of each input doc will always start on a new media sheet; this means the last impression of an input doc may have fewer than ni print-stream pages on it.

    • SEPARATE_DOCUMENTS_COLLATED_COPIES -- The input docs will remain separate. For input doc i, each media impression will consist of ni print-stream pages from the input doc. Since the input docs are separate, the first impression of each input doc will always start on a new media sheet; this means the last impression of an input doc may have fewer than ni print-stream pages on it.
IPP Compatibility: The integer value gives the IPP integer value. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
NumberUp(int value)
Construct a new number up attribute with the given integer value.
Method Summary
boolean | equals(Object object) Returns whether this number up attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.IntegerSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

NumberUp

public NumberUp(int value)
Construct a new number up attribute with the given integer value.

Parameters:
value - Integer value.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if value is less than 1.
Method Detail

equals

public boolean equals(Object object)
Returns whether this number up attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class NumberUp.
  3. This number up attribute's value and object's value are equal.

Overrides:
equals in class IntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this number up attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class NumberUp, the category is class NumberUp itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class NumberUp, the category name is "number-up".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NumberUpSupported

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class NumberUpSupported

java.lang.Object
    extended by  javax.print.attribute.SetOfIntegerSyntax
        extended by  javax.print.attribute.standard.NumberUpSupported
All Implemented Interfaces:
Serializable, Cloneable, Attribute, SupportedValuesAttribute
public final class NumberUpSupported
extends SetOfIntegerSyntax
implements SupportedValuesAttribute

Class NumberUpSupported is a printing attribute class, a set of integers, that gives the supported values for a NumberUp attribute.

IPP Compatibility: The NumberUpSupported attribute's canonical array form gives the lower and upper bound for each range of number-up to be included in an IPP "number-up-supported" attribute. See class SetOfIntegerSyntax for an explanation of canonical array form. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
NumberUpSupported(int member)
Construct a new number up supported attribute containing a single integer.
NumberUpSupported(int[][] members)
Construct a new number up supported attribute with the given members.
NumberUpSupported(int lowerBound, int upperBound)
Construct a new number up supported attribute containing a single range of integers.
Method Summary
boolean | equals(Object object) Returns whether this number up supported attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.SetOfIntegerSyntax
contains, contains, getMembers, hashCode, next, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

NumberUpSupported

public NumberUpSupported(int[][] members)
Construct a new number up supported attribute with the given members. The supported values for NumberUp are specified in "array form;" see class SetOfIntegerSyntax for an explanation of array form.

Parameters:
members - Set members in array form.
Throws:
NullPointerException - (unchecked exception) Thrown if members is null or any element of members is null.
IllegalArgumentException - (unchecked exception) Thrown if any element of members is not a length-one or length-two array. Also thrown if members is a zero-length array or if any member of the set is less than 1.

NumberUpSupported

public NumberUpSupported(int member)
Construct a new number up supported attribute containing a single integer. That is, only the one value of NumberUp is supported.

Parameters:
member - Set member.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if member is less than 1.

NumberUpSupported

public NumberUpSupported(int lowerBound,
                         int upperBound)
Construct a new number up supported attribute containing a single range of integers. That is, only those values of NumberUp in the one range are supported.

Parameters:
lowerBound - Lower bound of the range.
upperBound - Upper bound of the range.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if a null range is specified or if a non-null range is specified with lowerBound less than 1.
Method Detail

equals

public boolean equals(Object object)
Returns whether this number up supported attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class NumberUpSupported.
  3. This number up supported attribute's members and object's members are the same.

Overrides:
equals in class SetOfIntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this number up supported attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class NumberUpSupported, the category is class NumberUpSupported itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class NumberUpSupported, the category name is "number-up-supported".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OrientationRequested

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class OrientationRequested

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.OrientationRequested
All Implemented Interfaces:
Serializable, Cloneable, Attribute, DocAttribute, PrintJobAttribute, PrintRequestAttribute
public final class OrientationRequested
extends EnumSyntax
implements DocAttribute, PrintRequestAttribute, PrintJobAttribute

Class OrientationRequested is a printing attribute class, an enumeration, that indicates the desired orientation for printed print-stream pages; it does not describe the orientation of the client-supplied print-stream pages.

For some document formats (such as "application/postscript"), the desired orientation of the print-stream pages is specified within the document data. This information is generated by a device driver prior to the submission of the print job. Other document formats (such as "text/plain") do not include the notion of desired orientation within the document data. In the latter case it is possible for the printer to bind the desired orientation to the document data after it has been submitted. It is expected that a printer would only support the OrientationRequested attribute for some document formats (e.g., "text/plain" or "text/html") but not others (e.g. "application/postscript"). This is no different from any other job template attribute, since a print job can always impose constraints among the values of different job template attributes. However, a special mention is made here since it is very likely that a printer will support the OrientationRequested attribute for only a subset of the supported document formats.

IPP Compatibility: The category name returned by getName() is the IPP attribute name. The enumeration's integer value is the IPP enum value. The toString() method returns the IPP string representation of the attribute value.

See Also:
Serialized Form

Field Summary
static OrientationRequested | LANDSCAPE The content will be imaged across the long edge of the medium.
static OrientationRequested | PORTRAIT The content will be imaged across the short edge of the medium.
static OrientationRequested | REVERSE_LANDSCAPE The content will be imaged across the long edge of the medium, but in the opposite manner from landscape.
static OrientationRequested | REVERSE_PORTRAIT The content will be imaged across the short edge of the medium, but in the opposite manner from portrait.
Constructor Summary
protected OrientationRequested(int value)
Construct a new orientation requested enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class OrientationRequested.
String | getName() Get the name of the category of which this attribute value is an instance.
protected int | getOffset() Returns the lowest integer value used by class OrientationRequested.
protected String[] | getStringTable() Returns the string table for class OrientationRequested.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

PORTRAIT

public static final OrientationRequested PORTRAIT
The content will be imaged across the short edge of the medium.

LANDSCAPE

public static final OrientationRequested LANDSCAPE
The content will be imaged across the long edge of the medium. Landscape is defined to be a rotation of the print-stream page to be imaged by +90 degrees with respect to the medium (i.e. anti-clockwise) from the portrait orientation. Note: The +90 direction was chosen because simple finishing on the long edge is the same edge whether portrait or landscape.

REVERSE_LANDSCAPE

public static final OrientationRequested REVERSE_LANDSCAPE
The content will be imaged across the long edge of the medium, but in the opposite manner from landscape. Reverse-landscape is defined to be a rotation of the print-stream page to be imaged by -90 degrees with respect to the medium (i.e. clockwise) from the portrait orientation. Note: The REVERSE_LANDSCAPE value was added because some applications rotate landscape -90 degrees from portrait, rather than +90 degrees.

REVERSE_PORTRAIT

public static final OrientationRequested REVERSE_PORTRAIT
The content will be imaged across the short edge of the medium, but in the opposite manner from portrait. Reverse-portrait is defined to be a rotation of the print-stream page to be imaged by 180 degrees with respect to the medium from the portrait orientation. Note: The REVERSE_PORTRAIT value was added for use with the Finishings attribute in cases where the opposite edge is desired for finishing a portrait document on simple finishing devices that have only one finishing position. Thus a "text/plain" portrait document can be stapled "on the right" by a simple finishing device as is common use with some Middle Eastern languages such as Hebrew.

Constructor Detail

OrientationRequested

protected OrientationRequested(int value)
Construct a new orientation requested enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class OrientationRequested.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class OrientationRequested.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getOffset

protected int getOffset()
Returns the lowest integer value used by class OrientationRequested.

Overrides:
getOffset in class EnumSyntax
Returns:
the offset of the lowest enumeration value.

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class OrientationRequested, the category is class OrientationRequested itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class OrientationRequested, the category name is "orientation-requested".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OutputDeviceAssigned

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class OutputDeviceAssigned

java.lang.Object
    extended by  javax.print.attribute.TextSyntax
        extended by  javax.print.attribute.standard.OutputDeviceAssigned
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute
public final class OutputDeviceAssigned
extends TextSyntax
implements PrintJobAttribute

Class OutputDeviceAssigned is a printing attribute class, a text attribute, that identifies the output device to which the service has assigned this job. If an output device implements an embedded Print Service instance, the printer need not set this attribute. If a print server implements a Print Service instance, the value may be empty (zero- length string) or not returned until the service assigns an output device to the job. This attribute is particularly useful when a single service supports multiple devices (so called "fan-out").

IPP Compatibility: The string value gives the IPP name value. The locale gives the IPP natural language. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
OutputDeviceAssigned(String deviceName, Locale locale)
Constructs a new output device assigned attribute with the given device name and locale.
Method Summary
boolean | equals(Object object) Returns whether this output device assigned attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.TextSyntax
getLocale, getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

OutputDeviceAssigned

public OutputDeviceAssigned(String deviceName,
                            Locale locale)
Constructs a new output device assigned attribute with the given device name and locale.

Parameters:
deviceName - Device name.
locale - Natural language of the text string. null is interpreted to mean the default locale as returned by Locale.getDefault()
Throws:
NullPointerException - (unchecked exception) Thrown if deviceName is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this output device assigned attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class OutputDeviceAssigned.
  3. This output device assigned attribute's underlying string and object's underlying string are equal.
  4. This output device assigned attribute's locale and object's locale are equal.

Overrides:
equals in class TextSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this output device assigned attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class OutputDeviceAssigned, the category is class OutputDeviceAssigned itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class OutputDeviceAssigned, the category name is "output-device-assigned".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PageRanges

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PageRanges

java.lang.Object
    extended by  javax.print.attribute.SetOfIntegerSyntax
        extended by  javax.print.attribute.standard.PageRanges
All Implemented Interfaces:
Serializable, Cloneable, Attribute, DocAttribute, PrintJobAttribute, PrintRequestAttribute
public final class PageRanges
extends SetOfIntegerSyntax
implements DocAttribute, PrintRequestAttribute, PrintJobAttribute

Class PageRanges is a printing attribute class, a set of integers, that identifies the range(s) of print-stream pages that the Printer object uses for each copy of each document which are to be printed. Nothing is printed for any pages identified that do not exist in the document(s). The attribute is associated with print-stream pages, not application-numbered pages (for example, the page numbers found in the headers and or footers for certain word processing applications).

In most cases, the exact pages to be printed will be generated by a device driver and this attribute would not be required. However, when printing an archived document which has already been formatted, the end user may elect to print just a subset of the pages contained in the document. In this case, if a page range of "n-m" is specified, the first page to be printed will be page n. All subsequent pages of the document will be printed through and including page m.

If a PageRanges attribute is not specified for a print job, all pages of the document will be printed. In other words, the default value for the PageRanges attribute is always {{1, Integer.MAX_VALUE}}.

The effect of a PageRanges attribute on a multidoc print job (a job with multiple documents) depends on whether all the docs have the same page ranges specified or whether different docs have different page ranges specified, and on the (perhaps defaulted) value of the MultipleDocumentHandling attribute.

  • If all the docs have the same page ranges specified, then any value of MultipleDocumentHandling makes sense, and the printer's processing depends on the MultipleDocumentHandling value:
    • SINGLE_DOCUMENT -- All the input docs will be combined together into one output document. The specified page ranges of that output document will be printed.

    • SINGLE_DOCUMENT_NEW_SHEET -- All the input docs will be combined together into one output document, and the first impression of each input doc will always start on a new media sheet. The specified page ranges of that output document will be printed.

    • SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- For each separate input doc, the specified page ranges will be printed.

    • SEPARATE_DOCUMENTS_COLLATED_COPIES -- For each separate input doc, the specified page ranges will be printed.
    • SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- For each separate input doc, its own specified page ranges will be printed..

    • SEPARATE_DOCUMENTS_COLLATED_COPIES -- For each separate input doc, its own specified page ranges will be printed..

IPP Compatibility: The PageRanges attribute's canonical array form gives the lower and upper bound for each range of pages to be included in and IPP "page-ranges" attribute. See class SetOfIntegerSyntax for an explanation of canonical array form. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
PageRanges(int member)
Construct a new page ranges attribute containing a single integer.
PageRanges(int[][] members)
Construct a new page ranges attribute with the given members.
PageRanges(int lowerBound, int upperBound)
Construct a new page ranges attribute containing a single range of integers.
PageRanges(String members)
Construct a new page ranges attribute with the given members in string form.
Method Summary
boolean | equals(Object object) Returns whether this page ranges attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.SetOfIntegerSyntax
contains, contains, getMembers, hashCode, next, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

PageRanges

public PageRanges(int[][] members)
Construct a new page ranges attribute with the given members. The members are specified in "array form;" see class SetOfIntegerSyntax for an explanation of array form.

Parameters:
members - Set members in array form.
Throws:
NullPointerException - (unchecked exception) Thrown if members is null or any element of members is null.
IllegalArgumentException - (unchecked exception) Thrown if any element of members is not a length-one or length-two array. Also thrown if members is a zero-length array or if any member of the set is less than 1.

PageRanges

public PageRanges(String members)
Construct a new page ranges attribute with the given members in string form. See class SetOfIntegerSyntax for explanation of the syntax.

Parameters:
members - Set members in string form.
Throws:
NullPointerException - (unchecked exception) Thrown if members is null or any element of members is null.
IllegalArgumentException - (Unchecked exception) Thrown if members does not obey the proper syntax. Also thrown if the constructed set-of-integer is a zero-length array or if any member of the set is less than 1.

PageRanges

public PageRanges(int member)
Construct a new page ranges attribute containing a single integer. That is, only the one page is to be printed.

Parameters:
member - Set member.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if member is less than 1.

PageRanges

public PageRanges(int lowerBound,
                  int upperBound)
Construct a new page ranges attribute containing a single range of integers. That is, only those pages in the one range are to be printed.

Parameters:
lowerBound - Lower bound of the range.
upperBound - Upper bound of the range.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if a null range is specified or if a non-null range is specified with lowerBound less than 1.
Method Detail

equals

public boolean equals(Object object)
Returns whether this page ranges attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class PageRanges.
  3. This page ranges attribute's members and object's members are the same.

Overrides:
equals in class SetOfIntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this page ranges attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PageRanges, the category is class PageRanges itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PageRanges, the category name is "page-ranges".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PagesPerMinute

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PagesPerMinute

java.lang.Object
    extended by  javax.print.attribute.IntegerSyntax
        extended by  javax.print.attribute.standard.PagesPerMinute
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintServiceAttribute
public final class PagesPerMinute
extends IntegerSyntax
implements PrintServiceAttribute

Class PagesPerMinute is an integer valued printing attribute that indicates the nominal number of pages per minute to the nearest whole number which may be generated by this printer (e.g., simplex, black-and-white). This attribute is informative, not a service guarantee. Generally, it is the value used in the marketing literature to describe the device. A value of 0 indicates a device that takes more than two minutes to process a page.

IPP Compatibility: The integer value gives the IPP integer value. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
PagesPerMinute(int value)
Construct a new pages per minute attribute with the given integer value.
Method Summary
boolean | equals(Object object) Returns whether this pages per minute attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.IntegerSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

PagesPerMinute

public PagesPerMinute(int value)
Construct a new pages per minute attribute with the given integer value.

Parameters:
value - Integer value.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if value is less than 0.
Method Detail

equals

public boolean equals(Object object)
Returns whether this pages per minute attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class PagesPerMinute.
  3. This pages per minute attribute's value and object's value are equal.

Overrides:
equals in class IntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this pages per minute attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PagesPerMinute, the category is class PagesPerMinute itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PagesPerMinute, the category name is "pages-per-minute".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PagesPerMinuteColor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PagesPerMinuteColor

java.lang.Object
    extended by  javax.print.attribute.IntegerSyntax
        extended by  javax.print.attribute.standard.PagesPerMinuteColor
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintServiceAttribute
public final class PagesPerMinuteColor
extends IntegerSyntax
implements PrintServiceAttribute

Class PagesPerMinuteColor is an integer valued printing attribute that indicates the nominal number of pages per minute to the nearest whole number which may be generated by this printer when printing color (e.g., simplex, color). For purposes of this attribute, "color" means the same as for the ColorSupported attribute, namely, the device is capable of any type of color printing at all, including highlight color as well as full process color. This attribute is informative, not a service guarantee. Generally, it is the value used in the marketing literature to describe the color capabilities of this device. A value of 0 indicates a device that takes more than two minutes to process a page. If a color device has several color modes, it may use the pages-per- minute value for this attribute that corresponds to the mode that produces the highest number.

A black and white only printer must not include the PagesPerMinuteColor attribute in its attribute set or service registration. If this attribute is present, then the ColorSupported printer description attribute must also be present and have a value of SUPPORTED.

IPP Compatibility: The integer value gives the IPP integer value. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
PagesPerMinuteColor(int value)
Construct a new pages per minute color attribute with the given integer value.
Method Summary
boolean | equals(Object object) Returns whether this pages per minute color attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.IntegerSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

PagesPerMinuteColor

public PagesPerMinuteColor(int value)
Construct a new pages per minute color attribute with the given integer value.

Parameters:
value - Integer value.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if value is less than 0.
Method Detail

equals

public boolean equals(Object object)
Returns whether this pages per minute color attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class PagesPerMinuteColor.
  3. This pages per minute attribute's value and object's value are equal.

Overrides:
equals in class IntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this pages per minute color attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PagesPerMinuteColor, the category is class PagesPerMinuteColor itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PagesPerMinuteColor, the category name is "pages-per-minute-color".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PDLOverrideSupported

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PDLOverrideSupported

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.PDLOverrideSupported
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintServiceAttribute
public class PDLOverrideSupported
extends EnumSyntax
implements PrintServiceAttribute

Class PDLOverrideSupported is a printing attribute class, an enumeration, that expresses the printer's ability to attempt to override processing instructions embedded in documents' print data with processing instructions specified as attributes outside the print data.

IPP Compatibility: The category name returned by getName() is the IPP attribute name. The enumeration's integer value is the IPP enum value. The toString() method returns the IPP string representation of the attribute value.

See Also:
Serialized Form

Field Summary
static PDLOverrideSupported | ATTEMPTED The printer attempts to make the external job attribute values take precedence over embedded instructions in the documents' print data, however there is no guarantee.
static PDLOverrideSupported | NOT_ATTEMPTED The printer makes no attempt to make the external job attribute values take precedence over embedded instructions in the documents' print data.
Constructor Summary
protected PDLOverrideSupported(int value)
Construct a new PDL override supported enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class PDLOverrideSupported.
String | getName() Get the name of the category of which this attribute value is an instance.
protected String[] | getStringTable() Returns the string table for class PDLOverrideSupported.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

NOT_ATTEMPTED

public static final PDLOverrideSupported NOT_ATTEMPTED
The printer makes no attempt to make the external job attribute values take precedence over embedded instructions in the documents' print data.

ATTEMPTED

public static final PDLOverrideSupported ATTEMPTED
The printer attempts to make the external job attribute values take precedence over embedded instructions in the documents' print data, however there is no guarantee.

Constructor Detail

PDLOverrideSupported

protected PDLOverrideSupported(int value)
Construct a new PDL override supported enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class PDLOverrideSupported.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class PDLOverrideSupported.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PDLOverrideSupported and any vendor-defined subclasses, the category is class PDLOverrideSupported itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PDLOverrideSupported and any vendor-defined subclasses, the category name is "pdl-override-supported".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PresentationDirection

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PresentationDirection

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.PresentationDirection
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintJobAttribute, PrintRequestAttribute
public final class PresentationDirection
extends EnumSyntax
implements PrintJobAttribute, PrintRequestAttribute

Class PresentationDirection is a printing attribute class, an enumeration, that is used in conjunction with the NumberUp attribute to indicate the layout of multiple print-stream pages to impose upon a single side of an instance of a selected medium. This is useful to mirror the text layout conventions of different scripts. For example, English is "toright-tobottom", Hebrew is "toleft-tobottom" and Japanese is usually "tobottom-toleft".

IPP Compatibility: This attribute is not an IPP 1.1 attribute; it is an attribute in the Production Printing Extension (PDF) of IPP 1.1. The category name returned by getName() is the IPP attribute name. The enumeration's integer value is the IPP enum value. The toString() method returns the IPP string representation of the attribute value.

See Also:
Serialized Form

Field Summary
static PresentationDirection | TOBOTTOM_TOLEFT Pages are laid out in columns starting at the top right, proceeeding towards the bottom & left.
static PresentationDirection | TOBOTTOM_TORIGHT Pages are laid out in columns starting at the top left, proceeeding towards the bottom & right.
static PresentationDirection | TOLEFT_TOBOTTOM Pages are laid out in rows starting at the top right, proceeeding towards the left & bottom.
static PresentationDirection | TOLEFT_TOTOP Pages are laid out in rows starting at the bottom right, proceeeding towards the left & top.
static PresentationDirection | TORIGHT_TOBOTTOM Pages are laid out in rows starting at the top left, proceeeding towards the right & bottom.
static PresentationDirection | TORIGHT_TOTOP Pages are laid out in rows starting at the bottom left, proceeeding towards the right & top.
static PresentationDirection | TOTOP_TOLEFT Pages are laid out in columns starting at the bottom right, proceeeding towards the top & left.
static PresentationDirection | TOTOP_TORIGHT Pages are laid out in columns starting at the bottom left, proceeeding towards the top & right.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class PresentationDirection.
String | getName() Get the name of the category of which this attribute value is an instance.
protected String[] | getStringTable() Returns the string table for class PresentationDirection.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

TOBOTTOM_TORIGHT

public static final PresentationDirection TOBOTTOM_TORIGHT
Pages are laid out in columns starting at the top left, proceeeding towards the bottom & right.

TOBOTTOM_TOLEFT

public static final PresentationDirection TOBOTTOM_TOLEFT
Pages are laid out in columns starting at the top right, proceeeding towards the bottom & left.

TOTOP_TORIGHT

public static final PresentationDirection TOTOP_TORIGHT
Pages are laid out in columns starting at the bottom left, proceeeding towards the top & right.

TOTOP_TOLEFT

public static final PresentationDirection TOTOP_TOLEFT
Pages are laid out in columns starting at the bottom right, proceeeding towards the top & left.

TORIGHT_TOBOTTOM

public static final PresentationDirection TORIGHT_TOBOTTOM
Pages are laid out in rows starting at the top left, proceeeding towards the right & bottom.

TORIGHT_TOTOP

public static final PresentationDirection TORIGHT_TOTOP
Pages are laid out in rows starting at the bottom left, proceeeding towards the right & top.

TOLEFT_TOBOTTOM

public static final PresentationDirection TOLEFT_TOBOTTOM
Pages are laid out in rows starting at the top right, proceeeding towards the left & bottom.

TOLEFT_TOTOP

public static final PresentationDirection TOLEFT_TOTOP
Pages are laid out in rows starting at the bottom right, proceeeding towards the left & top.

Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class PresentationDirection.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class PresentationDirection.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PresentationDirection the category is class PresentationDirection itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PresentationDirection the category name is "presentation-direction".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrinterInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PrinterInfo

java.lang.Object
    extended by  javax.print.attribute.TextSyntax
        extended by  javax.print.attribute.standard.PrinterInfo
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintServiceAttribute
public final class PrinterInfo
extends TextSyntax
implements PrintServiceAttribute

Class PrinterInfo is a printing attribute class, a text attribute, that provides descriptive information about a printer. This could include things like: "This printer can be used for printing color transparencies for HR presentations", or "Out of courtesy for others, please print only small (1-5 page) jobs at this printer", or even \ "This printer is going away on July 1, 1997, please find a new printer".

IPP Compatibility: The string value gives the IPP name value. The locale gives the IPP natural language. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
PrinterInfo(String info, Locale locale)
Constructs a new printer info attribute with the given information string and locale.
Method Summary
boolean | equals(Object object) Returns whether this printer info attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.TextSyntax
getLocale, getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

PrinterInfo

public PrinterInfo(String info,
                   Locale locale)
Constructs a new printer info attribute with the given information string and locale.

Parameters:
info - Printer information string.
locale - Natural language of the text string. null is interpreted to mean the default locale as returned by Locale.getDefault()
Throws:
NullPointerException - (unchecked exception) Thrown if info is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this printer info attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class PrinterInfo.
  3. This printer info attribute's underlying string and object's underlying string are equal.
  4. This printer info attribute's locale and object's locale are equal.

Overrides:
equals in class TextSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this printer info attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PrinterInfo, the category is class PrinterInfo itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PrinterInfo, the category name is "printer-info".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrinterIsAcceptingJobs

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PrinterIsAcceptingJobs

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.PrinterIsAcceptingJobs
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintServiceAttribute
public final class PrinterIsAcceptingJobs
extends EnumSyntax
implements PrintServiceAttribute

Class PrinterIsAcceptingJobs is a printing attribute class, an enumeration, that indicates whether the printer is currently able to accept jobs. This value is independent of the PrinterState and PrinterStateReasons attributes because its value does not affect the current job; rather it affects future jobs. If the value is NOT_ACCEPTING_JOBS, the printer will reject jobs even when the PrinterState is IDLE. If value is ACCEPTING_JOBS, the Printer will accept jobs even when the PrinterState is STOPPED.

IPP Compatibility: The IPP boolean value is "true" for ACCEPTING_JOBS and "false" for NOT_ACCEPTING_JOBS. TThe category name returned by getName() is the IPP attribute name. The enumeration's integer value is the IPP enum value. The toString() method returns the IPP string representation of the attribute value.

See Also:
Serialized Form

Field Summary
static PrinterIsAcceptingJobs | ACCEPTING_JOBS The printer is currently acccepting jobs.
static PrinterIsAcceptingJobs | NOT_ACCEPTING_JOBS The printer is currently rejecting any jobs sent to it.
Constructor Summary
protected PrinterIsAcceptingJobs(int value)
Construct a new printer is accepting jobs enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class PrinterIsAcceptingJobs.
String | getName() Get the name of the category of which this attribute value is an instance.
protected String[] | getStringTable() Returns the string table for class PrinterIsAcceptingJobs.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

NOT_ACCEPTING_JOBS

public static final PrinterIsAcceptingJobs NOT_ACCEPTING_JOBS
The printer is currently rejecting any jobs sent to it.

ACCEPTING_JOBS

public static final PrinterIsAcceptingJobs ACCEPTING_JOBS
The printer is currently acccepting jobs.

Constructor Detail

PrinterIsAcceptingJobs

protected PrinterIsAcceptingJobs(int value)
Construct a new printer is accepting jobs enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class PrinterIsAcceptingJobs.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class PrinterIsAcceptingJobs.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PrinterIsAcceptingJobs, the category is class PrinterIsAcceptingJobs itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PrinterIsAcceptingJobs, the category name is "printer-is-accepting-jobs".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrinterLocation

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PrinterLocation

java.lang.Object
    extended by  javax.print.attribute.TextSyntax
        extended by  javax.print.attribute.standard.PrinterLocation
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintServiceAttribute
public final class PrinterLocation
extends TextSyntax
implements PrintServiceAttribute

Class PrinterLocation is a printing attribute class, a text attribute, that identifies the location of the device. This could include things like: "in Room 123A, second floor of building XYZ".

IPP Compatibility: The string value gives the IPP name value. The locale gives the IPP natural language. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
PrinterLocation(String location, Locale locale)
Constructs a new printer location attribute with the given location and locale.
Method Summary
boolean | equals(Object object) Returns whether this printer location attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.TextSyntax
getLocale, getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

PrinterLocation

public PrinterLocation(String location,
                       Locale locale)
Constructs a new printer location attribute with the given location and locale.

Parameters:
location - Printer location.
locale - Natural language of the text string. null is interpreted to mean the default locale as returned by Locale.getDefault()
Throws:
NullPointerException - (unchecked exception) Thrown if location is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this printer location attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class PrinterLocation.
  3. This printer location attribute's underlying string and object's underlying string are equal.
  4. This printer location attribute's locale and object's locale are equal.

Overrides:
equals in class TextSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this printer location attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PrinterLocation, the category is class PrinterLocation itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PrinterLocation, the category name is "printer-location".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrinterMakeAndModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PrinterMakeAndModel

java.lang.Object
    extended by  javax.print.attribute.TextSyntax
        extended by  javax.print.attribute.standard.PrinterMakeAndModel
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintServiceAttribute
public final class PrinterMakeAndModel
extends TextSyntax
implements PrintServiceAttribute

Class PrinterMakeAndModel is a printing attribute class, a text attribute, that the make and model of the printer.

IPP Compatibility: The string value gives the IPP name value. The locale gives the IPP natural language. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
PrinterMakeAndModel(String makeAndModel, Locale locale)
Constructs a new printer make and model attribute with the given make and model string and locale.
Method Summary
boolean | equals(Object object) Returns whether this printer make and model attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.TextSyntax
getLocale, getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

PrinterMakeAndModel

public PrinterMakeAndModel(String makeAndModel,
                           Locale locale)
Constructs a new printer make and model attribute with the given make and model string and locale.

Parameters:
makeAndModel - Printer make and model string.
locale - Natural language of the text string. null is interpreted to mean the default locale as returned by Locale.getDefault()
Throws:
NullPointerException - (unchecked exception) Thrown if makeAndModel is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this printer make and model attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class PrinterMakeAndModel.
  3. This printer make and model attribute's underlying string and object's underlying string are equal.
  4. This printer make and model attribute's locale and object's locale are equal.

Overrides:
equals in class TextSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this printer make and model attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PrinterMakeAndModel, the category is class PrinterMakeAndModel itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PrinterMakeAndModel, the category name is "printer-make-and-model".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrinterMessageFromOperator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PrinterMessageFromOperator

java.lang.Object
    extended by  javax.print.attribute.TextSyntax
        extended by  javax.print.attribute.standard.PrinterMessageFromOperator
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintServiceAttribute
public final class PrinterMessageFromOperator
extends TextSyntax
implements PrintServiceAttribute

Class PrinterMessageFromOperator is a printing attribute class, a text attribute, that provides a message from an operator, system administrator, or "intelligent" process to indicate to the end user information about or status of the printer, such as why it is unavailable or when it is expected to be available.

A Print Service's attribute set includes zero instances or one instance of a PrinterMessageFromOperator attribute, not more than one instance. A new PrinterMessageFromOperator attribute replaces an existing PrinterMessageFromOperator attribute, if any. In other words, PrinterMessageFromOperator is not intended to be a history log. If it wishes, the client can detect changes to a Print Service's PrinterMessageFromOperator attribute and maintain the client's own history log of the PrinterMessageFromOperator attribute values.

IPP Compatibility: The string value gives the IPP name value. The locale gives the IPP natural language. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
PrinterMessageFromOperator(String message, Locale locale)
Constructs a new printer message from operator attribute with the given message and locale.
Method Summary
boolean | equals(Object object) Returns whether this printer message from operator attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.TextSyntax
getLocale, getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

PrinterMessageFromOperator

public PrinterMessageFromOperator(String message,
                                  Locale locale)
Constructs a new printer message from operator attribute with the given message and locale.

Parameters:
message - Message.
locale - Natural language of the text string. null is interpreted to mean the default locale as returned by Locale.getDefault()
Throws:
NullPointerException - (unchecked exception) Thrown if message is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this printer message from operator attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class PrinterMessageFromOperator.
  3. This printer message from operator attribute's underlying string and object's underlying string are equal.
  4. This printer message from operator attribute's locale and object's locale are equal.

Overrides:
equals in class TextSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this printer message from operator attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PrinterMessageFromOperator, the category is class PrinterMessageFromOperator itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PrinterMessageFromOperator, the category name is "printer-message-from-operator".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrinterMoreInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PrinterMoreInfo

java.lang.Object
    extended by  javax.print.attribute.URISyntax
        extended by  javax.print.attribute.standard.PrinterMoreInfo
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintServiceAttribute
public final class PrinterMoreInfo
extends URISyntax
implements PrintServiceAttribute

Class PrinterMoreInfo is a printing attribute class, a URI, that is used to obtain more information about this specific printer. For example, this could be an HTTP type URI referencing an HTML page accessible to a web browser. The information obtained from this URI is intended for end user consumption. Features outside the scope of the Print Service API can be accessed from this URI. The information is intended to be specific to this printer instance and site specific services (e.g. job pricing, services offered, end user assistance).

In contrast, the PrinterMoreInfoManufacturer attribute is used to find out more information about this general kind of printer rather than this specific printer.

IPP Compatibility: The string form returned by toString() gives the IPP uri value. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
PrinterMoreInfo(URI uri)
Constructs a new printer more info attribute with the specified URI.
Method Summary
boolean | equals(Object object) Returns whether this printer more info attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.URISyntax
getURI, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

PrinterMoreInfo

public PrinterMoreInfo(URI uri)
Constructs a new printer more info attribute with the specified URI.

Parameters:
uri - URI.
Throws:
NullPointerException - (unchecked exception) Thrown if uri is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this printer more info attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class PrinterMoreInfo.
  3. This printer more info attribute's URI and object's URI are equal.

Overrides:
equals in class URISyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this printer more info attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PrinterMoreInfo, the category is class PrinterMoreInfo itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PrinterMoreInfo, the category name is "printer-more-info".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrinterMoreInfoManufacturer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PrinterMoreInfoManufacturer

java.lang.Object
    extended by  javax.print.attribute.URISyntax
        extended by  javax.print.attribute.standard.PrinterMoreInfoManufacturer
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintServiceAttribute
public final class PrinterMoreInfoManufacturer
extends URISyntax
implements PrintServiceAttribute

Class PrinterMoreInfoManufacturer is a printing attribute class, a URI, that is used to obtain more information about this type of device. The information obtained from this URI is intended for end user consumption. Features outside the scope of the Print Service API can be accessed from this URI (e.g., latest firmware, upgrades, service proxies, optional features available, details on color support). The information is intended to be germane to this kind of printer without regard to site specific modifications or services.

PrinterMoreInfo attribute is used to find out more information about this specific printer rather than this general kind of printer.

IPP Compatibility: The string form returned by toString() gives the IPP uri value. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
PrinterMoreInfoManufacturer(URI uri)
Constructs a new printer more info manufacturer attribute with the specified URI.
Method Summary
boolean | equals(Object object) Returns whether this printer more info manufacturer attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.URISyntax
getURI, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

PrinterMoreInfoManufacturer

public PrinterMoreInfoManufacturer(URI uri)
Constructs a new printer more info manufacturer attribute with the specified URI.

Parameters:
uri - URI.
Throws:
NullPointerException - (unchecked exception) Thrown if uri is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this printer more info manufacturer attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class PrinterMoreInfoManufacturer.
  3. This printer more info manufacturer attribute's URI and object's URI are equal.

Overrides:
equals in class URISyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this printer more info manufacturer attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PrinterMoreInfoManufacturer, the category is class PrinterMoreInfoManufacturer itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PrinterMoreInfoManufacturer, the category name is "printer-more-info-manufacturer".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrinterName

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PrinterName

java.lang.Object
    extended by  javax.print.attribute.TextSyntax
        extended by  javax.print.attribute.standard.PrinterName
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintServiceAttribute
public final class PrinterName
extends TextSyntax
implements PrintServiceAttribute

Class PrinterName is a printing attribute class, a text attribute, that specifies the name of a printer. It is a name that is more end-user friendly than a URI. An administrator determines a printer's name and sets this attribute to that name. This name may be the last part of the printer's URI or it may be unrelated. In non-US-English locales, a name may contain characters that are not allowed in a URI.

IPP Compatibility: The string value gives the IPP name value. The locale gives the IPP natural language. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
PrinterName(String printerName, Locale locale)
Constructs a new printer name attribute with the given name and locale.
Method Summary
boolean | equals(Object object) Returns whether this printer name attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.TextSyntax
getLocale, getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

PrinterName

public PrinterName(String printerName,
                   Locale locale)
Constructs a new printer name attribute with the given name and locale.

Parameters:
printerName - Printer name.
locale - Natural language of the text string. null is interpreted to mean the default locale as returned by Locale.getDefault()
Throws:
NullPointerException - (unchecked exception) Thrown if printerName is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this printer name attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class PrinterName.
  3. This printer name attribute's underlying string and object's underlying string are equal.
  4. This printer name attribute's locale and object's locale are equal.

Overrides:
equals in class TextSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this printer name attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PrinterName, the category is class PrinterName itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PrinterName, the category name is "printer-name".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrinterResolution

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PrinterResolution

java.lang.Object
    extended by  javax.print.attribute.ResolutionSyntax
        extended by  javax.print.attribute.standard.PrinterResolution
All Implemented Interfaces:
Serializable, Cloneable, Attribute, DocAttribute, PrintJobAttribute, PrintRequestAttribute
public final class PrinterResolution
extends ResolutionSyntax
implements DocAttribute, PrintRequestAttribute, PrintJobAttribute

Class PrinterResolution is a printing attribute class that specifies an exact resolution supported by a printer or to be used for a print job. This attribute assumes that printers have a small set of device resolutions at which they can operate rather than a continuum.

PrinterResolution is used in multiple ways:

  1. When a client searches looking for a printer that supports the client's desired resolution exactly (no more, no less), the client specifies an instance of class PrinterResolution indicating the exact resolution the client wants. Only printers supporting that exact resolution will match the search.

  2. When a client needs to print a job using the client's desired resolution exactly (no more, no less), the client specifies an instance of class PrinterResolution as an attribute of the Print Job. This will fail if the Print Job doesn't support that exact resolution, and Fidelity is set to true.
If a client wants to locate a printer supporting a resolution greater than some required minimum, then it may be necessary to exclude this attribute from a lookup request and to directly query the set of supported resolutions, and specify the one that most closely meets the client's requirements. In some cases this may be more simply achieved by specifying a PrintQuality attribute which often controls resolution.

IPP Compatibility: The information needed to construct an IPP "printer-resolution" attribute can be obtained by calling methods on the PrinterResolution object. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Field Summary
Fields inherited from class javax.print.attribute.ResolutionSyntax
DPCM, DPI
Constructor Summary
PrinterResolution(int crossFeedResolution, int feedResolution, int units)
Construct a new printer resolution attribute from the given items.
Method Summary
boolean | equals(Object object) Returns whether this printer resolution attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.ResolutionSyntax
getCrossFeedResolution, getCrossFeedResolutionDphi, getFeedResolution, getFeedResolutionDphi, getResolution, hashCode, lessThanOrEquals, toString, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

PrinterResolution

public PrinterResolution(int crossFeedResolution,
                         int feedResolution,
                         int units)
Construct a new printer resolution attribute from the given items.

Parameters:
crossFeedResolution - Cross feed direction resolution.
feedResolution - Feed direction resolution.
units - Unit conversion factor, e.g. ResolutionSyntax.DPI or ResolutionSyntax.>DPCM.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if crossFeedResolution < 1 or feedResolution < 1 or units < 1.
Method Detail

equals

public boolean equals(Object object)
Returns whether this printer resolution attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class PrinterResolution.
  3. This attribute's cross feed direction resolution is equal to object's cross feed direction resolution.
  4. This attribute's feed direction resolution is equal to object's feed direction resolution.

Overrides:
equals in class ResolutionSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this printer resolution attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PrinterResolution, the category is class PrinterResolution itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PrinterResolution, the category name is "printer-resolution".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrinterState

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PrinterState

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.PrinterState
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintServiceAttribute
public final class PrinterState
extends EnumSyntax
implements PrintServiceAttribute

Class PrinterState is a printing attribute class, an enumeration, that identifies the current state of a printer. Class PrinterState defines standard printer state values. A Print Service implementation only needs to report those printer states which are appropriate for the particular implementation; it does not have to report every defined printer state. The PrinterStateReasons attribute augments the PrinterState attribute to give more detailed information about the printer in given printer state.

IPP Compatibility: The category name returned by getName() is the IPP attribute name. The enumeration's integer value is the IPP enum value. The toString() method returns the IPP string representation of the attribute value.

See Also:
Serialized Form

Field Summary
static PrinterState | IDLE Indicates that new jobs can start processing without waiting.
static PrinterState | PROCESSING Indicates that jobs are processing; new jobs will wait before processing.
static PrinterState | STOPPED Indicates that no jobs can be processed and intervention is required.
static PrinterState | UNKNOWN The printer state is unknown.
Constructor Summary
protected PrinterState(int value)
Construct a new printer state enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class PrinterState.
String | getName() Get the name of the category of which this attribute value is an instance.
protected String[] | getStringTable() Returns the string table for class PrinterState.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

UNKNOWN

public static final PrinterState UNKNOWN
The printer state is unknown.

IDLE

public static final PrinterState IDLE
Indicates that new jobs can start processing without waiting.

PROCESSING

public static final PrinterState PROCESSING
Indicates that jobs are processing; new jobs will wait before processing.

STOPPED

public static final PrinterState STOPPED
Indicates that no jobs can be processed and intervention is required.

Constructor Detail

PrinterState

protected PrinterState(int value)
Construct a new printer state enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class PrinterState.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class PrinterState.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PrinterState, the category is class PrinterState itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PrinterState, the category name is "printer-state".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrinterStateReason

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PrinterStateReason

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.PrinterStateReason
All Implemented Interfaces:
Serializable, Cloneable, Attribute
public class PrinterStateReason
extends EnumSyntax
implements Attribute

Class PrinterStateReason is a printing attribute class, an enumeration, that provides additional information about the printer's current state, i.e., information that augments the value of the printer's PrinterState attribute. Class PrinterStateReason defines standard printer state reason values. A Print Service implementation only needs to report those printer state reasons which are appropriate for the particular implementation; it does not have to report every defined printer state reason.

Instances of PrinterStateReason do not appear in a Print Service's attribute set directly. Rather, a PrinterStateReasons attribute appears in the Print Service's attribute set. The PrinterStateReasons attribute contains zero, one, or more than one PrinterStateReason objects which pertain to the Print Service's status, and each PrinterStateReason object is associated with a Severity level of REPORT (least severe), WARNING, or ERROR (most severe). The printer adds a PrinterStateReason object to the Print Service's PrinterStateReasons attribute when the corresponding condition becomes true of the printer, and the printer removesthe PrinterStateReason object again when the corresponding condition becomes false, regardless of whether the Print Service's overall PrinterState also changed.

IPP Compatibility: The string values returned by each individual PrinterStateReason and associated Severity object's toString() methods, concatenated together with a hyphen ("-") in between, gives the IPP keyword value for a PrinterStateReasons. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Field Summary
static PrinterStateReason | CONNECTING_TO_DEVICE The printer has scheduled a job on the output device and is in the process of connecting to a shared network output device (and might not be able to actually start printing the job for an arbitrarily long time depending on the usage of the output device by other servers on the network).
static PrinterStateReason | COVER_OPEN One or more covers on the device are open.
static PrinterStateReason | DEVELOPER_EMPTY The device is out of developer.
static PrinterStateReason | DEVELOPER_LOW The device is low on developer.
static PrinterStateReason | DOOR_OPEN One or more doors on the device are open.
static PrinterStateReason | FUSER_OVER_TEMP The fuser temperature is above normal.
static PrinterStateReason | FUSER_UNDER_TEMP The fuser temperature is below normal.
static PrinterStateReason | INPUT_TRAY_MISSING One or more input trays are not in the device.
static PrinterStateReason | INTERLOCK_OPEN One or more interlock devices on the printer are unlocked.
static PrinterStateReason | INTERPRETER_RESOURCE_UNAVAILABLE An interpreter resource is unavailable (e.g., font, form).
static PrinterStateReason | MARKER_SUPPLY_EMPTY The device is out of at least one marker supply (e.g.
static PrinterStateReason | MARKER_SUPPLY_LOW The device is low on at least one marker supply (e.g.
static PrinterStateReason | MARKER_WASTE_ALMOST_FULL The device marker supply waste receptacle is almost full.
static PrinterStateReason | MARKER_WASTE_FULL The device marker supply waste receptacle is full.
static PrinterStateReason | MEDIA_EMPTY At least one input tray is empty.
static PrinterStateReason | MEDIA_JAM The device has a media jam.
static PrinterStateReason | MEDIA_LOW At least one input tray is low on media.
static PrinterStateReason | MEDIA_NEEDED A tray has run out of media.
static PrinterStateReason | MOVING_TO_PAUSED Someone has paused the printer, but the device(s) are taking an appreciable time to stop.
static PrinterStateReason | OPC_LIFE_OVER The optical photo conductor is no longer functioning.
static PrinterStateReason | OPC_NEAR_EOL The optical photo conductor is near end of life.
static PrinterStateReason | OTHER The printer has detected an error other than ones listed below.
static PrinterStateReason | OUTPUT_AREA_ALMOST_FULL One or more output areas are almost full (e.g.
static PrinterStateReason | OUTPUT_AREA_FULL One or more output areas are full (e.g.
static PrinterStateReason | OUTPUT_TRAY_MISSING One or more output trays are not in the device.
static PrinterStateReason | PAUSED Someone has paused the printer and the printer's PrinterState is STOPPED.
static PrinterStateReason | SHUTDOWN Someone has removed a printer from service, and the device may be powered down or physically removed.
static PrinterStateReason | SPOOL_AREA_FULL The limit of persistent storage allocated for spooling has been reached.
static PrinterStateReason | STOPPED_PARTLY When a printer controls more than one output device, this reason indicates that one or more output devices are stopped.
static PrinterStateReason | STOPPING The printer is in the process of stopping the device and will be stopped in a while.
static PrinterStateReason | TIMED_OUT The server was able to connect to the output device (or is always connected), but was unable to get a response from the output device.
static PrinterStateReason | TONER_EMPTY The device is out of toner.
static PrinterStateReason | TONER_LOW The device is low on toner.
Constructor Summary
protected PrinterStateReason(int value)
Construct a new printer state reason enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class PrinterStateReason.
String | getName() Get the name of the category of which this attribute value is an instance.
protected String[] | getStringTable() Returns the string table for class PrinterStateReason.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

OTHER

public static final PrinterStateReason OTHER
The printer has detected an error other than ones listed below.

MEDIA_NEEDED

public static final PrinterStateReason MEDIA_NEEDED
A tray has run out of media.

MEDIA_JAM

public static final PrinterStateReason MEDIA_JAM
The device has a media jam.

MOVING_TO_PAUSED

public static final PrinterStateReason MOVING_TO_PAUSED
Someone has paused the printer, but the device(s) are taking an appreciable time to stop. Later, when all output has stopped, the PrinterState becomes STOPPED, and the PAUSED value replaces the MOVING_TO_PAUSED value in the PrinterStateReasons attribute. This value must be supported if the printer can be paused and the implementation takes significant time to pause a device in certain circumstances.

PAUSED

public static final PrinterStateReason PAUSED
Someone has paused the printer and the printer's PrinterState is STOPPED. In this state, a printer must not produce printed output, but it must perform other operations requested by a client. If a printer had been printing a job when the printer was paused, the Printer must resume printing that job when the printer is no longer paused and leave no evidence in the printed output of such a pause. This value must be supported if the printer can be paused.

SHUTDOWN

public static final PrinterStateReason SHUTDOWN
Someone has removed a printer from service, and the device may be powered down or physically removed. In this state, a printer must not produce printed output, and unless the printer is realized by a print server that is still active, the printer must perform no other operations requested by a client. If a printer had been printing a job when it was shut down, the printer need not resume printing that job when the printer is no longer shut down. If the printer resumes printing such a job, it may leave evidence in the printed output of such a shutdown, e.g. the part printed before the shutdown may be printed a second time after the shutdown.

CONNECTING_TO_DEVICE

public static final PrinterStateReason CONNECTING_TO_DEVICE
The printer has scheduled a job on the output device and is in the process of connecting to a shared network output device (and might not be able to actually start printing the job for an arbitrarily long time depending on the usage of the output device by other servers on the network).

TIMED_OUT

public static final PrinterStateReason TIMED_OUT
The server was able to connect to the output device (or is always connected), but was unable to get a response from the output device.

STOPPING

public static final PrinterStateReason STOPPING
The printer is in the process of stopping the device and will be stopped in a while. When the device is stopped, the printer will change the PrinterState to STOPPED. The STOPPING reason is never an error, even for a printer with a single output device. When an output device ceases accepting jobs, the printer's PrinterStateReasons will have this reason while the output device completes printing.

STOPPED_PARTLY

public static final PrinterStateReason STOPPED_PARTLY
When a printer controls more than one output device, this reason indicates that one or more output devices are stopped. If the reason's severity is a report, fewer than half of the output devices are stopped. If the reason's severity is a warning, half or more but fewer than all of the output devices are stopped.

TONER_LOW

public static final PrinterStateReason TONER_LOW
The device is low on toner.

TONER_EMPTY

public static final PrinterStateReason TONER_EMPTY
The device is out of toner.

SPOOL_AREA_FULL

public static final PrinterStateReason SPOOL_AREA_FULL
The limit of persistent storage allocated for spooling has been reached. The printer is temporarily unable to accept more jobs. The printer will remove this reason when it is able to accept more jobs. This value should be used by a non-spooling printer that only accepts one or a small number jobs at a time or a spooling printer that has filled the spool space.

COVER_OPEN

public static final PrinterStateReason COVER_OPEN
One or more covers on the device are open.

INTERLOCK_OPEN

public static final PrinterStateReason INTERLOCK_OPEN
One or more interlock devices on the printer are unlocked.

DOOR_OPEN

public static final PrinterStateReason DOOR_OPEN
One or more doors on the device are open.

INPUT_TRAY_MISSING

public static final PrinterStateReason INPUT_TRAY_MISSING
One or more input trays are not in the device.

MEDIA_LOW

public static final PrinterStateReason MEDIA_LOW
At least one input tray is low on media.

MEDIA_EMPTY

public static final PrinterStateReason MEDIA_EMPTY
At least one input tray is empty.

OUTPUT_TRAY_MISSING

public static final PrinterStateReason OUTPUT_TRAY_MISSING
One or more output trays are not in the device.

OUTPUT_AREA_ALMOST_FULL

public static final PrinterStateReason OUTPUT_AREA_ALMOST_FULL
One or more output areas are almost full (e.g. tray, stacker, collator).

OUTPUT_AREA_FULL

public static final PrinterStateReason OUTPUT_AREA_FULL
One or more output areas are full (e.g. tray, stacker, collator).

MARKER_SUPPLY_LOW

public static final PrinterStateReason MARKER_SUPPLY_LOW
The device is low on at least one marker supply (e.g. toner, ink, ribbon).

MARKER_SUPPLY_EMPTY

public static final PrinterStateReason MARKER_SUPPLY_EMPTY
The device is out of at least one marker supply (e.g. toner, ink, ribbon).

MARKER_WASTE_ALMOST_FULL

public static final PrinterStateReason MARKER_WASTE_ALMOST_FULL
The device marker supply waste receptacle is almost full.

MARKER_WASTE_FULL

public static final PrinterStateReason MARKER_WASTE_FULL
The device marker supply waste receptacle is full.

FUSER_OVER_TEMP

public static final PrinterStateReason FUSER_OVER_TEMP
The fuser temperature is above normal.

FUSER_UNDER_TEMP

public static final PrinterStateReason FUSER_UNDER_TEMP
The fuser temperature is below normal.

OPC_NEAR_EOL

public static final PrinterStateReason OPC_NEAR_EOL
The optical photo conductor is near end of life.

OPC_LIFE_OVER

public static final PrinterStateReason OPC_LIFE_OVER
The optical photo conductor is no longer functioning.

DEVELOPER_LOW

public static final PrinterStateReason DEVELOPER_LOW
The device is low on developer.

DEVELOPER_EMPTY

public static final PrinterStateReason DEVELOPER_EMPTY
The device is out of developer.

INTERPRETER_RESOURCE_UNAVAILABLE

public static final PrinterStateReason INTERPRETER_RESOURCE_UNAVAILABLE
An interpreter resource is unavailable (e.g., font, form).

Constructor Detail

PrinterStateReason

protected PrinterStateReason(int value)
Construct a new printer state reason enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class PrinterStateReason.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class PrinterStateReason.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PrinterStateReason and any vendor-defined subclasses, the category is class PrinterStateReason itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PrinterStateReason and any vendor-defined subclasses, the category name is "printer-state-reason".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrinterStateReasons

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PrinterStateReasons

java.lang.Object
    extended by  java.util.AbstractMap<K,V>
        extended by  java.util.HashMap<PrinterStateReason,Severity>
            extended by  javax.print.attribute.standard.PrinterStateReasons
All Implemented Interfaces:
Serializable, Cloneable, Map<PrinterStateReason,Severity>, Attribute, PrintServiceAttribute
public final class PrinterStateReasons
extends HashMap<PrinterStateReason,Severity>
implements PrintServiceAttribute

Class PrinterStateReasons is a printing attribute class, a set of enumeration values, that provides additional information about the printer's current state, i.e., information that augments the value of the printer's PrinterState attribute.

Instances of PrinterStateReason do not appear in a Print Service's attribute set directly. Rather, a PrinterStateReasons attribute appears in the Print Service's attribute set. The PrinterStateReasons attribute contains zero, one, or more than one PrinterStateReason objects which pertain to the Print Service's status, and each PrinterStateReason object is associated with a Severity level of REPORT (least severe), WARNING, or ERROR (most severe). The printer adds a PrinterStateReason object to the Print Service's PrinterStateReasons attribute when the corresponding condition becomes true of the printer, and the printer removes the PrinterStateReason object again when the corresponding condition becomes false, regardless of whether the Print Service's overall PrinterState also changed.

Class PrinterStateReasons inherits its implementation from class java.util.HashMap. Each entry in the map consists of a PrinterStateReason object (key) mapping to a Severity object (value):

Unlike most printing attributes which are immutable once constructed, class PrinterStateReasons is designed to be mutable; you can add PrinterStateReason objects to an existing PrinterStateReasons object and remove them again. However, like class java.util.HashMap, class PrinterStateReasons is bot multiple thread safe. If a PrinterStateReasons object will be used by multiple threads, be sure to synchronize its operations (e.g., using a synchronized map view obtained from class java.util.Collections).

IPP Compatibility: The string values returned by each individual PrinterStateReason object's and the associated Severity object's toString() methods, concatenated together with a hyphen ("-") in between, gives the IPP keyword value. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Nested Class Summary
Nested classes/interfaces inherited from class java.util.AbstractMap
AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>
Constructor Summary
PrinterStateReasons()
Construct a new, empty printer state reasons attribute; the underlying hash map has the default initial capacity and load factor.
PrinterStateReasons(int initialCapacity)
super a new, empty printer state reasons attribute; the underlying hash map has the given initial capacity and the default load factor.
PrinterStateReasons(int initialCapacity, float loadFactor)
Construct a new, empty printer state reasons attribute; the underlying hash map has the given initial capacity and load factor.
PrinterStateReasons(Map<PrinterStateReason,Severity> map)
Construct a new printer state reasons attribute that contains the same PrinterStateReason-to-Severity mappings as the given map.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Set<PrinterStateReason> | printerStateReasonSet(Severity severity) Obtain an unmodifiable set view of the individual printer state reason attributes at the given severity level in this PrinterStateReasons attribute.
Severity | put(PrinterStateReason reason, Severity severity) Adds the given printer state reason to this printer state reasons attribute, associating it with the given severity level.
Methods inherited from class java.util.HashMap
clear, clone, containsKey, containsValue, entrySet, get, isEmpty, keySet, putAll, remove, size, values
Methods inherited from class java.util.AbstractMap
equals, hashCode, toString
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.util.Map
equals, hashCode

Constructor Detail

PrinterStateReasons

public PrinterStateReasons()
Construct a new, empty printer state reasons attribute; the underlying hash map has the default initial capacity and load factor.

PrinterStateReasons

public PrinterStateReasons(int initialCapacity)
super a new, empty printer state reasons attribute; the underlying hash map has the given initial capacity and the default load factor.

Parameters:
initialCapacity - Initial capacity.
Throws:
IllegalArgumentException - if the initial capacity is less than zero.

PrinterStateReasons

public PrinterStateReasons(int initialCapacity,
                           float loadFactor)
Construct a new, empty printer state reasons attribute; the underlying hash map has the given initial capacity and load factor.

Parameters:
initialCapacity - Initial capacity.
loadFactor - Load factor.
Throws:
IllegalArgumentException - if the initial capacity is less than zero.

PrinterStateReasons

public PrinterStateReasons(Map<PrinterStateReason,Severity> map)
Construct a new printer state reasons attribute that contains the same PrinterStateReason-to-Severity mappings as the given map. The underlying hash map's initial capacity and load factor are as specified in the superclass constructor HashMap(Map).

Parameters:
map - Map to copy.
Throws:
NullPointerException - (unchecked exception) Thrown if map is null or if any key or value in map is null.
ClassCastException - (unchecked exception) Thrown if any key in map is not an instance of class PrinterStateReason or if any value in map is not an instance of class Severity.
Method Detail

put

public Severity put(PrinterStateReason reason,
                    Severity severity)
Adds the given printer state reason to this printer state reasons attribute, associating it with the given severity level. If this printer state reasons attribute previously contained a mapping for the given printer state reason, the old value is replaced.

Specified by:
put in interface Map<PrinterStateReason,Severity>
Overrides:
put in class HashMap<PrinterStateReason,Severity>
Parameters:
reason - Printer state reason. This must be an instance of class PrinterStateReason.
severity - Severity of the printer state reason. This must be an instance of class Severity.
Returns:
Previous severity associated with the given printer state reason, or null if the given printer state reason was not present.
Throws:
NullPointerException - (unchecked exception) Thrown if reason is null or severity is null.
ClassCastException - (unchecked exception) Thrown if reason is not an instance of class PrinterStateReason or if severity is not an instance of class Severity.
Since:
1.5

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PrinterStateReasons, the category is class PrinterStateReasons itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PrinterStateReasons, the category name is "printer-state-reasons".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.

printerStateReasonSet

public Set<PrinterStateReason> printerStateReasonSet(Severity severity)
Obtain an unmodifiable set view of the individual printer state reason attributes at the given severity level in this PrinterStateReasons attribute. Each element in the set view is a PrinterStateReason object. The only elements in the set view are the PrinterStateReason objects that map to the given severity value. The set view is backed by this PrinterStateReasons attribute, so changes to this PrinterStateReasons attribute are reflected in the set view. The set view does not support element insertion or removal. The set view's iterator does not support element removal.

Parameters:
severity - Severity level.
Returns:
Set view of the individual PrinterStateReason attributes at the given Severity level.
Throws:
NullPointerException - (unchecked exception) Thrown if severity is null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrinterURI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PrinterURI

java.lang.Object
    extended by  javax.print.attribute.URISyntax
        extended by  javax.print.attribute.standard.PrinterURI
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintServiceAttribute
public final class PrinterURI
extends URISyntax
implements PrintServiceAttribute

Class PrinterURI is a printing attribute class, a URI, that specifies the globally unique name of a printer. If it has such a name, an administrator determines a printer's URI and sets this attribute to that name.

IPP Compatibility: This implements the IPP printer-uri attribute. The string form returned by toString() gives the IPP printer-uri value. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
PrinterURI(URI uri)
Constructs a new PrinterURI attribute with the specified URI.
Method Summary
boolean | equals(Object object) Returns whether this printer name attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.URISyntax
getURI, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

PrinterURI

public PrinterURI(URI uri)
Constructs a new PrinterURI attribute with the specified URI.

Parameters:
uri - URI of the printer
Throws:
NullPointerException - (unchecked exception) Thrown if uri is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this printer name attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class PrinterURI.
  3. This PrinterURI attribute's underlying URI and object's underlying URI are equal.

Overrides:
equals in class URISyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this PrinterURI attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PrinterURI and any vendor-defined subclasses, the category is class PrinterURI itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PrinterURI and any vendor-defined subclasses, the category name is "printer-uri".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrintQuality

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class PrintQuality

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.PrintQuality
All Implemented Interfaces:
Serializable, Cloneable, Attribute, DocAttribute, PrintJobAttribute, PrintRequestAttribute
public class PrintQuality
extends EnumSyntax
implements DocAttribute, PrintRequestAttribute, PrintJobAttribute

Class PrintQuality is a printing attribute class, an enumeration, that specifies the print quality that the printer uses for the job.

IPP Compatibility: The category name returned by getName() is the IPP attribute name. The enumeration's integer value is the IPP enum value. The toString() method returns the IPP string representation of the attribute value.

See Also:
Serialized Form

Field Summary
static PrintQuality | DRAFT Lowest quality available on the printer.
static PrintQuality | HIGH Highest quality available on the printer.
static PrintQuality | NORMAL Normal or intermediate quality on the printer.
Constructor Summary
protected PrintQuality(int value)
Construct a new print quality enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class PrintQuality.
String | getName() Get the name of the category of which this attribute value is an instance.
protected int | getOffset() Returns the lowest integer value used by class PrintQuality.
protected String[] | getStringTable() Returns the string table for class PrintQuality.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

DRAFT

public static final PrintQuality DRAFT
Lowest quality available on the printer.

NORMAL

public static final PrintQuality NORMAL
Normal or intermediate quality on the printer.

HIGH

public static final PrintQuality HIGH
Highest quality available on the printer.

Constructor Detail

PrintQuality

protected PrintQuality(int value)
Construct a new print quality enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class PrintQuality.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class PrintQuality.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getOffset

protected int getOffset()
Returns the lowest integer value used by class PrintQuality.

Overrides:
getOffset in class EnumSyntax
Returns:
the offset of the lowest enumeration value.

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class PrintQuality and any vendor-defined subclasses, the category is class PrintQuality itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class PrintQuality and any vendor-defined subclasses, the category name is "print-quality".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


QueuedJobCount

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class QueuedJobCount

java.lang.Object
    extended by  javax.print.attribute.IntegerSyntax
        extended by  javax.print.attribute.standard.QueuedJobCount
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintServiceAttribute
public final class QueuedJobCount
extends IntegerSyntax
implements PrintServiceAttribute

Class QueuedJobCount is an integer valued printing attribute that indicates the number of jobs in the printer whose JobState is either PENDING, PENDING_HELD, PROCESSING, or PROCESSING_STOPPED.

IPP Compatibility: The integer value gives the IPP integer value. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
QueuedJobCount(int value)
Construct a new queued job count attribute with the given integer value.
Method Summary
boolean | equals(Object object) Returns whether this queued job count attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.IntegerSyntax
getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

QueuedJobCount

public QueuedJobCount(int value)
Construct a new queued job count attribute with the given integer value.

Parameters:
value - Integer value.
Throws:
IllegalArgumentException - (Unchecked exception) Thrown if value is less than 0.
Method Detail

equals

public boolean equals(Object object)
Returns whether this queued job count attribute is equivalent to the passed in object. To be equivalent, all of the following conditions mus be true:
  1. object is not null.
  2. object is an instance of class QueuedJobCount.
  3. This queued job count attribute's value and object's value are equal.

Overrides:
equals in class IntegerSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this queued job count attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class QueuedJobCount, the category is class QueuedJobCount itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class QueuedJobCount, the category name is "queued-job-count".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ReferenceUriSchemesSupported

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class ReferenceUriSchemesSupported

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.ReferenceUriSchemesSupported
All Implemented Interfaces:
Serializable, Cloneable, Attribute
public class ReferenceUriSchemesSupported
extends EnumSyntax
implements Attribute

Class ReferenceUriSchemesSupported is a printing attribute class an enumeration, that indicates a "URI scheme," such as "http:" or "ftp:", that a printer can use to retrieve print data stored at a URI location. If a printer supports doc flavors with a print data representation class of "java.net.URL", the printer uses instances of class ReferenceUriSchemesSupported to advertise the URI schemes it can accept. The acceptable URI schemes are included as service attributes in the lookup service; this lets clients search the for printers that can get print data using a certain URI scheme. The acceptable URI schemes can also be queried using the capability methods in interface PrintService. However, ReferenceUriSchemesSupported attributes are used solely for determining acceptable URI schemes, they are never included in a doc's, print request's, print job's, or print service's attribute set.

The Internet Assigned Numbers Authority maintains the official list of URI schemes.

Class ReferenceUriSchemesSupported defines enumeration values for widely used URI schemes. A printer that supports additional URI schemes can define them in a subclass of class ReferenceUriSchemesSupported.

IPP Compatibility: The category name returned by getName() is the IPP attribute name. The enumeration's integer value is the IPP enum value. The toString() method returns the IPP string representation of the attribute value.

See Also:
Serialized Form

Field Summary
static ReferenceUriSchemesSupported | FILE Host-specific file names.
static ReferenceUriSchemesSupported | FTP File Transfer Protocol (FTP).
static ReferenceUriSchemesSupported | GOPHER Gopher Protocol.
static ReferenceUriSchemesSupported | HTTP HyperText Transfer Protocol (HTTP).
static ReferenceUriSchemesSupported | HTTPS Secure HyperText Transfer Protocol (HTTPS).
static ReferenceUriSchemesSupported | NEWS USENET news.
static ReferenceUriSchemesSupported | NNTP USENET news using Network News Transfer Protocol (NNTP).
static ReferenceUriSchemesSupported | WAIS Wide Area Information Server (WAIS) protocol.
Constructor Summary
protected ReferenceUriSchemesSupported(int value)
Construct a new reference URI scheme enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class ReferenceUriSchemesSupported.
String | getName() Get the name of the category of which this attribute value is an instance.
protected String[] | getStringTable() Returns the string table for class ReferenceUriSchemesSupported.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

FTP

public static final ReferenceUriSchemesSupported FTP
File Transfer Protocol (FTP).

HTTP

public static final ReferenceUriSchemesSupported HTTP
HyperText Transfer Protocol (HTTP).

HTTPS

public static final ReferenceUriSchemesSupported HTTPS
Secure HyperText Transfer Protocol (HTTPS).

GOPHER

public static final ReferenceUriSchemesSupported GOPHER
Gopher Protocol.

NEWS

public static final ReferenceUriSchemesSupported NEWS
USENET news.

NNTP

public static final ReferenceUriSchemesSupported NNTP
USENET news using Network News Transfer Protocol (NNTP).

WAIS

public static final ReferenceUriSchemesSupported WAIS
Wide Area Information Server (WAIS) protocol.

FILE

public static final ReferenceUriSchemesSupported FILE
Host-specific file names.

Constructor Detail

ReferenceUriSchemesSupported

protected ReferenceUriSchemesSupported(int value)
Construct a new reference URI scheme enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class ReferenceUriSchemesSupported.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class ReferenceUriSchemesSupported.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class ReferenceUriSchemesSupported and any vendor-defined subclasses, the category is class ReferenceUriSchemesSupported itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class ReferenceUriSchemesSupported and any vendor-defined subclasses, the category name is "reference-uri-schemes-supported".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RequestingUserName

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class RequestingUserName

java.lang.Object
    extended by  javax.print.attribute.TextSyntax
        extended by  javax.print.attribute.standard.RequestingUserName
All Implemented Interfaces:
Serializable, Cloneable, Attribute, PrintRequestAttribute
public final class RequestingUserName
extends TextSyntax
implements PrintRequestAttribute

Class RequestingUserName is a printing attribute class, a text attribute, that specifies the name of the end user that submitted the print job. A requesting user name is an arbitrary string defined by the client. The printer does not put the client-specified RequestingUserName attribute into the Print Job's attribute set; rather, the printer puts in a JobOriginatingUserName attribute. This means that services which support specifying a username with this attribute should also report a JobOriginatingUserName in the job's attribute set. Note that many print services may have a way to independently authenticate the user name, and so may state support for a requesting user name, but in practice will then report the user name authenticated by the service rather than that specified via this attribute.

IPP Compatibility: The string value gives the IPP name value. The locale gives the IPP natural language. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Constructor Summary
RequestingUserName(String userName, Locale locale)
Constructs a new requesting user name attribute with the given user name and locale.
Method Summary
boolean | equals(Object object) Returns whether this requesting user name attribute is equivalent to the passed in object.
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
String | getName() Get the name of the category of which this attribute value is an instance.
Methods inherited from class javax.print.attribute.TextSyntax
getLocale, getValue, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

RequestingUserName

public RequestingUserName(String userName,
                          Locale locale)
Constructs a new requesting user name attribute with the given user name and locale.

Parameters:
userName - User name.
locale - Natural language of the text string. null is interpreted to mean the default locale as returned by Locale.getDefault()
Throws:
NullPointerException - (unchecked exception) Thrown if userName is null.
Method Detail

equals

public boolean equals(Object object)
Returns whether this requesting user name attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class RequestingUserName.
  3. This requesting user name attribute's underlying string and object's underlying string are equal.
  4. This requesting user name attribute's locale and object's locale are equal.

Overrides:
equals in class TextSyntax
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this requesting user name attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class RequestingUserName, the category is class RequestingUserName itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class RequestingUserName, the category name is "requesting-user-name".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Severity

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class Severity

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.Severity
All Implemented Interfaces:
Serializable, Cloneable, Attribute
public final class Severity
extends EnumSyntax
implements Attribute

Class Severity is a printing attribute class, an enumeration, that denotes the severity of a PrinterStateReason attribute.

Instances of Severity do not appear in a Print Service's attribute set directly. Rather, a PrinterStateReasons attribute appears in the Print Service's attribute set. The PrinterStateReasons attribute contains zero, one, or more than one PrinterStateReason objects which pertain to the Print Service's status, and each PrinterStateReason object is associated with a Severity level of REPORT (least severe), WARNING, or ERROR (most severe). The printer adds a PrinterStateReason object to the Print Service's PrinterStateReasons attribute when the corresponding condition becomes true of the printer, and the printer removes the PrinterStateReason object again when the corresponding condition becomes false, regardless of whether the Print Service's overall PrinterState also changed.

IPP Compatibility: Severity.toString() returns either "error", "warning", or "report". The string values returned by each individual PrinterStateReason and associated Severity object's toString() methods, concatenated together with a hyphen ("-") in between, gives the IPP keyword value for a PrinterStateReasons. The category name returned by getName() gives the IPP attribute name.

See Also:
Serialized Form

Field Summary
static Severity | ERROR Indicates that the PrinterStateReason is an "error" (most severe).
static Severity | REPORT Indicates that the PrinterStateReason is a "report" (least severe).
static Severity | WARNING Indicates that the PrinterStateReason is a "warning." An implementation may choose to omit some or all warnings.
Constructor Summary
protected Severity(int value)
Construct a new severity enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class Severity.
String | getName() Get the name of the category of which this attribute value is an instance.
protected String[] | getStringTable() Returns the string table for class Severity.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

REPORT

public static final Severity REPORT
Indicates that the PrinterStateReason is a "report" (least severe). An implementation may choose to omit some or all reports. Some reports specify finer granularity about the printer state; others serve as a precursor to a warning. A report must contain nothing that could affect the printed output.

WARNING

public static final Severity WARNING
Indicates that the PrinterStateReason is a "warning." An implementation may choose to omit some or all warnings. Warnings serve as a precursor to an error. A warning must contain nothing that prevents a job from completing, though in some cases the output may be of lower quality.

ERROR

public static final Severity ERROR
Indicates that the PrinterStateReason is an "error" (most severe). An implementation must include all errors. If this attribute contains one or more errors, the printer's PrinterState must be STOPPED.

Constructor Detail

Severity

protected Severity(int value)
Construct a new severity enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class Severity.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class Severity.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class Severity, the category is class Severity itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class Severit, the category name is "severity".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SheetCollate

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class SheetCollate

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.SheetCollate
All Implemented Interfaces:
Serializable, Cloneable, Attribute, DocAttribute, PrintJobAttribute, PrintRequestAttribute
public final class SheetCollate
extends EnumSyntax
implements DocAttribute, PrintRequestAttribute, PrintJobAttribute

Class SheetCollate is a printing attribute class, an enumeration, that specifies whether or not the media sheets of each copy of each printed document in a job are to be in sequence, when multiple copies of the document are specified by the Copies attribute. When SheetCollate is COLLATED, each copy of each document is printed with the print-stream sheets in sequence. When SheetCollate is UNCOLLATED, each print-stream sheet is printed a number of times equal to the value of the Copies attribute in succession. For example, suppose a document produces two media sheets as output, Copies is 6, and SheetCollate is UNCOLLATED; in this case six copies of the first media sheet are printed followed by six copies of the second media sheet.

Whether the effect of sheet collation is achieved by placing copies of a document in multiple output bins or in the same output bin with implementation defined document separation is implementation dependent. Also whether it is achieved by making multiple passes over the job or by using an output sorter is implementation dependent.

If a printer does not support the SheetCollate attribute (meaning the client cannot specify any particular sheet collation), the printer must behave as though SheetCollate were always set to COLLATED.

The SheetCollate attribute interacts with the MultipleDocumentHandling attribute. The MultipleDocumentHandling attribute describes the collation of entire documents, and the SheetCollate attribute describes the semantics of collating individual pages within a document.

The effect of a SheetCollate attribute on a multidoc print job (a job with multiple documents) depends on whether all the docs have the same sheet collation specified or whether different docs have different sheet collations specified, and on the (perhaps defaulted) value of the MultipleDocumentHandling attribute.

  • If all the docs have the same sheet collation specified, then the following combinations of SheetCollate and MultipleDocumentHandling are permitted, and the printer reports an error when the job is submitted if any other combination is specified:
    • SheetCollate = COLLATED, MultipleDocumentHandling = SINGLE_DOCUMENT -- All the input docs will be combined into one output document. Multiple copies of the output document will be produced with pages in collated order, i.e. pages 1, 2, 3, . . ., 1, 2, 3, . . .

    • SheetCollate = COLLATED, MultipleDocumentHandling = SINGLE_DOCUMENT_NEW_SHEET -- All the input docs will be combined into one output document, and the first impression of each input doc will always start on a new media sheet. Multiple copies of the output document will be produced with pages in collated order, i.e. pages 1, 2, 3, . . ., 1, 2, 3, . . .

    • SheetCollate = COLLATED, MultipleDocumentHandling = SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- Each input doc will remain a separate output document. Multiple copies of each output document (call them A, B, . . .) will be produced with each document's pages in collated order, but the documents themselves in uncollated order, i.e. pages A1, A2, A3, . . ., A1, A2, A3, . . ., B1, B2, B3, . . ., B1, B2, B3, . . .

    • SheetCollate = COLLATED, MultipleDocumentHandling = SEPARATE_DOCUMENTS_COLLATED_COPIES -- Each input doc will remain a separate output document. Multiple copies of each output document (call them A, B, . . .) will be produced with each document's pages in collated order, with the documents themselves also in collated order, i.e. pages A1, A2, A3, . . ., B1, B2, B3, . . ., A1, A2, A3, . . ., B1, B2, B3, . . .

    • SheetCollate = UNCOLLATED, MultipleDocumentHandling = SINGLE_DOCUMENT -- All the input docs will be combined into one output document. Multiple copies of the output document will be produced with pages in uncollated order, i.e. pages 1, 1, . . ., 2, 2, . . ., 3, 3, . . .

    • SheetCollate = UNCOLLATED, MultipleDocumentHandling = SINGLE_DOCUMENT_NEW_SHEET -- All the input docs will be combined into one output document, and the first impression of each input doc will always start on a new media sheet. Multiple copies of the output document will be produced with pages in uncollated order, i.e. pages 1, 1, . . ., 2, 2, . . ., 3, 3, . . .

    • SheetCollate = UNCOLLATED, MultipleDocumentHandling = SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- Each input doc will remain a separate output document. Multiple copies of each output document (call them A, B, . . .) will be produced with each document's pages in uncollated order, with the documents themselves also in uncollated order, i.e. pages A1, A1, . . ., A2, A2, . . ., A3, A3, . . ., B1, B1, . . ., B2, B2, . . ., B3, B3, . . .

  • If different docs have different sheet collations specified, then only one value of MultipleDocumentHandling is permitted, and the printer reports an error when the job is submitted if any other value is specified:
    • MultipleDocumentHandling = SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- Each input doc will remain a separate output document. Multiple copies of each output document (call them A, B, . . .) will be produced with each document's pages in collated or uncollated order as the corresponding input doc's SheetCollate attribute specifies, and with the documents themselves in uncollated order. If document A had SheetCollate = UNCOLLATED and document B had SheetCollate = COLLATED, the following pages would be produced: A1, A1, . . ., A2, A2, . . ., A3, A3, . . ., B1, B2, B3, . . ., B1, B2, B3, . . .

IPP Compatibility: SheetCollate is not an IPP attribute at present.

See Also:
MultipleDocumentHandling, Serialized Form

Field Summary
static SheetCollate | COLLATED Sheets within a document appear in collated order when multiple copies are printed.
static SheetCollate | UNCOLLATED Sheets within a document appear in uncollated order when multiple copies are printed.
Constructor Summary
protected SheetCollate(int value)
Construct a new sheet collate enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class SheetCollate.
String | getName() Get the name of the category of which this attribute value is an instance.
protected String[] | getStringTable() Returns the string table for class SheetCollate.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

UNCOLLATED

public static final SheetCollate UNCOLLATED
Sheets within a document appear in uncollated order when multiple copies are printed.

COLLATED

public static final SheetCollate COLLATED
Sheets within a document appear in collated order when multiple copies are printed.

Constructor Detail

SheetCollate

protected SheetCollate(int value)
Construct a new sheet collate enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class SheetCollate.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class SheetCollate.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class SheetCollate, the category is class SheetCollate itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class SheetCollate, the category name is "sheet-collate".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Sides

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute.standard
Class Sides

java.lang.Object
    extended by  javax.print.attribute.EnumSyntax
        extended by  javax.print.attribute.standard.Sides
All Implemented Interfaces:
Serializable, Cloneable, Attribute, DocAttribute, PrintJobAttribute, PrintRequestAttribute
public final class Sides
extends EnumSyntax
implements DocAttribute, PrintRequestAttribute, PrintJobAttribute

Class Sides is a printing attribute class, an enumeration, that specifies how print-stream pages are to be imposed upon the sides of an instance of a selected medium, i.e., an impression.

The effect of a Sides attribute on a multidoc print job (a job with multiple documents) depends on whether all the docs have the same sides values specified or whether different docs have different sides values specified, and on the (perhaps defaulted) value of the MultipleDocumentHandling attribute.

  • If all the docs have the same sides value n specified, then any value of MultipleDocumentHandling makes sense, and the printer's processing depends on the MultipleDocumentHandling value:
    • SINGLE_DOCUMENT -- All the input docs will be combined together into one output document. Each media sheet will consist of n impressions from the output document.

    • SINGLE_DOCUMENT_NEW_SHEET -- All the input docs will be combined together into one output document. Each media sheet will consist of n impressions from the output document. However, the first impression of each input doc will always start on a new media sheet; this means the last media sheet of an input doc may have only one impression on it.

    • SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- The input docs will remain separate. Each media sheet will consist of n impressions from the input doc. Since the input docs are separate, the first impression of each input doc will always start on a new media sheet; this means the last media sheet of an input doc may have only one impression on it.

    • SEPARATE_DOCUMENTS_COLLATED_COPIES -- The input docs will remain separate. Each media sheet will consist of n impressions from the input doc. Since the input docs are separate, the first impression of each input doc will always start on a new media sheet; this means the last media sheet of an input doc may have only one impression on it.

    • SINGLE_DOCUMENT -- All the input docs will be combined together into one output document. Each media sheet will consist of ni impressions from the output document, where i is the number of the input doc corresponding to that point in the output document. When the next input doc has a different sides value from the previous input doc, the first print-stream page of the next input doc goes at the start of the next media sheet, possibly leaving only one impression on the previous media sheet.

    • SINGLE_DOCUMENT_NEW_SHEET -- All the input docs will be combined together into one output document. Each media sheet will consist of n impressions from the output document. However, the first impression of each input doc will always start on a new media sheet; this means the last impression of an input doc may have only one impression on it.

    • SEPARATE_DOCUMENTS_UNCOLLATED_COPIES -- The input docs will remain separate. For input doc i, each media sheet will consist of ni impressions from the input doc. Since the input docs are separate, the first impression of each input doc will always start on a new media sheet; this means the last media sheet of an input doc may have only one impression on it.

    • SEPARATE_DOCUMENTS_COLLATED_COPIES -- The input docs will remain separate. For input doc i, each media sheet will consist of ni impressions from the input doc. Since the input docs are separate, the first impression of each input doc will always start on a new media sheet; this means the last media sheet of an input doc may have only one impression on it.

IPP Compatibility: The category name returned by getName() is the IPP attribute name. The enumeration's integer value is the IPP enum value. The toString() method returns the IPP string representation of the attribute value.

See Also:
Serialized Form

Field Summary
static Sides | DUPLEX An alias for "two sided long edge" (see TWO_SIDED_LONG_EDGE).
static Sides | ONE_SIDED Imposes each consecutive print-stream page upon the same side of consecutive media sheets.
static Sides | TUMBLE An alias for "two sided short edge" (see TWO_SIDED_SHORT_EDGE).
static Sides | TWO_SIDED_LONG_EDGE Imposes each consecutive pair of print-stream pages upon front and back sides of consecutive media sheets, such that the orientation of each pair of print-stream pages on the medium would be correct for the reader as if for binding on the long edge.
static Sides | TWO_SIDED_SHORT_EDGE Imposes each consecutive pair of print-stream pages upon front and back sides of consecutive media sheets, such that the orientation of each pair of print-stream pages on the medium would be correct for the reader as if for binding on the short edge.
Constructor Summary
protected Sides(int value)
Construct a new sides enumeration value with the given integer value.
Method Summary
Class<? extends Attribute> | getCategory() Get the printing attribute class which is to be used as the "category" for this printing attribute value.
protected EnumSyntax[] | getEnumValueTable() Returns the enumeration value table for class Sides.
String | getName() Get the name of the category of which this attribute value is an instance.
protected String[] | getStringTable() Returns the string table for class Sides.
Methods inherited from class javax.print.attribute.EnumSyntax
clone, getOffset, getValue, hashCode, readResolve, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ONE_SIDED

public static final Sides ONE_SIDED
Imposes each consecutive print-stream page upon the same side of consecutive media sheets.

TWO_SIDED_LONG_EDGE

public static final Sides TWO_SIDED_LONG_EDGE
Imposes each consecutive pair of print-stream pages upon front and back sides of consecutive media sheets, such that the orientation of each pair of print-stream pages on the medium would be correct for the reader as if for binding on the long edge. This imposition is also known as "duplex" (see DUPLEX).

TWO_SIDED_SHORT_EDGE

public static final Sides TWO_SIDED_SHORT_EDGE
Imposes each consecutive pair of print-stream pages upon front and back sides of consecutive media sheets, such that the orientation of each pair of print-stream pages on the medium would be correct for the reader as if for binding on the short edge. This imposition is also known as "tumble" (see TUMBLE).

DUPLEX

public static final Sides DUPLEX
An alias for "two sided long edge" (see TWO_SIDED_LONG_EDGE).

TUMBLE

public static final Sides TUMBLE
An alias for "two sided short edge" (see TWO_SIDED_SHORT_EDGE).

Constructor Detail

Sides

protected Sides(int value)
Construct a new sides enumeration value with the given integer value.

Parameters:
value - Integer value.
Method Detail

getStringTable

protected String[] getStringTable()
Returns the string table for class Sides.

Overrides:
getStringTable in class EnumSyntax
Returns:
the string table

getEnumValueTable

protected EnumSyntax[] getEnumValueTable()
Returns the enumeration value table for class Sides.

Overrides:
getEnumValueTable in class EnumSyntax
Returns:
the value table

getCategory

public final Class<? extends Attribute> getCategory()
Get the printing attribute class which is to be used as the "category" for this printing attribute value.

For class Sides, the category is class Sides itself.

Specified by:
getCategory in interface Attribute
Returns:
Printing attribute class (category), an instance of class java.lang.Class.

getName

public final String getName()
Get the name of the category of which this attribute value is an instance.

For class Sides, the category name is "sides".

Specified by:
getName in interface Attribute
Returns:
Attribute category name.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


TextSyntax

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Class TextSyntax

java.lang.Object
    extended by  javax.print.attribute.TextSyntax
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
DocumentName, JobMessageFromOperator, JobName, JobOriginatingUserName, OutputDeviceAssigned, PrinterInfo, PrinterLocation, PrinterMakeAndModel, PrinterMessageFromOperator, PrinterName, RequestingUserName
public abstract class TextSyntax
extends Object
implements Serializable, Cloneable

Class TextSyntax is an abstract base class providing the common implementation of all attributes whose value is a string. The text attribute includes a locale to indicate the natural language. Thus, a text attribute always represents a localized string. Once constructed, a text attribute's value is immutable.

See Also:
Serialized Form

Constructor Summary
protected TextSyntax(String value, Locale locale)
Constructs a TextAttribute with the specified string and locale.
Method Summary
boolean | equals(Object object) Returns whether this text attribute is equivalent to the passed in object.
Locale | getLocale() Returns this text attribute's text string's natural language (locale).
String | getValue() Returns this text attribute's text string.
int | hashCode() Returns a hashcode for this text attribute.
String | toString() Returns a String identifying this text attribute.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

TextSyntax

protected TextSyntax(String value,
                     Locale locale)
Constructs a TextAttribute with the specified string and locale.

Parameters:
value - Text string.
locale - Natural language of the text string. null is interpreted to mean the default locale for as returned by Locale.getDefault()
Throws:
NullPointerException - (unchecked exception) Thrown if value is null.
Method Detail

getValue

public String getValue()
Returns this text attribute's text string.

Returns:
the text string.

getLocale

public Locale getLocale()
Returns this text attribute's text string's natural language (locale).

Returns:
the locale

hashCode

public int hashCode()
Returns a hashcode for this text attribute.

Overrides:
hashCode in class Object
Returns:
A hashcode value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object object)
Returns whether this text attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class TextSyntax.
  3. This text attribute's underlying string and object's underlying string are equal.
  4. This text attribute's locale and object's locale are equal.

Overrides:
equals in class Object
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this text attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

toString

public String toString()
Returns a String identifying this text attribute. The String is the attribute's underlying text string.

Overrides:
toString in class Object
Returns:
A String identifying this object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UnmodifiableSetException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Class UnmodifiableSetException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  javax.print.attribute.UnmodifiableSetException
All Implemented Interfaces:
Serializable
public class UnmodifiableSetException
extends RuntimeException

Thrown to indicate that the requested operation cannot be performed because the set is unmodifiable.

Since:
1.4
See Also:
Serialized Form

Constructor Summary
UnmodifiableSetException()
Constructs an UnsupportedOperationException with no detail message.
UnmodifiableSetException(String message)
Constructs an UnmodifiableSetException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UnmodifiableSetException

public UnmodifiableSetException()
Constructs an UnsupportedOperationException with no detail message.

UnmodifiableSetException

public UnmodifiableSetException(String message)
Constructs an UnmodifiableSetException with the specified detail message.

Parameters:
message - the detail message
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


URISyntax

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.print.attribute
Class URISyntax

java.lang.Object
    extended by  javax.print.attribute.URISyntax
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
Destination, PrinterMoreInfo, PrinterMoreInfoManufacturer, PrinterURI
public abstract class URISyntax
extends Object
implements Serializable, Cloneable

Class URISyntax is an abstract base class providing the common implementation of all attributes whose value is a Uniform Resource Identifier (URI). Once constructed, a URI attribute's value is immutable.

See Also:
Serialized Form

Constructor Summary
protected URISyntax(URI uri)
Constructs a URI attribute with the specified URI.
Method Summary
boolean | equals(Object object) Returns whether this URI attribute is equivalent to the passed in object.
URI | getURI() Returns this URI attribute's URI value.
int | hashCode() Returns a hashcode for this URI attribute.
String | toString() Returns a String identifying this URI attribute.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

URISyntax

protected URISyntax(URI uri)
Constructs a URI attribute with the specified URI.

Parameters:
uri - URI.
Throws:
NullPointerException - (unchecked exception) Thrown if uri is null.
Method Detail

getURI

public URI getURI()
Returns this URI attribute's URI value.

Returns:
the URI.

hashCode

public int hashCode()
Returns a hashcode for this URI attribute.

Overrides:
hashCode in class Object
Returns:
A hashcode value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object object)
Returns whether this URI attribute is equivalent to the passed in object. To be equivalent, all of the following conditions must be true:
  1. object is not null.
  2. object is an instance of class URISyntax.
  3. This URI attribute's underlying URI and object's underlying URI are equal.

Overrides:
equals in class Object
Parameters:
object - Object to compare to.
Returns:
True if object is equivalent to this URI attribute, false otherwise.
See Also:
Object.hashCode(), Hashtable

toString

public String toString()
Returns a String identifying this URI attribute. The String is the string representation of the attribute's underlying URI.

Overrides:
toString in class Object
Returns:
A String identifying this object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AttributeException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.print
Interface AttributeException

public interface AttributeException

Interface AttributeException is a mixin interface which a subclass of PrintException can implement to report an error condition involving one or more printing attributes that a particular Print Service instance does not support. Either the attribute is not supported at all, or the attribute is supported but the particular specified value is not supported. The Print Service API does not define any print exception classes that implement interface AttributeException, that being left to the Print Service implementor's discretion.

Method Summary
Class[] | getUnsupportedAttributes() Returns the array of printing attribute classes for which the Print Service instance does not support the attribute at all, or null if there are no such attributes.
Attribute[] | getUnsupportedValues() Returns the array of printing attributes for which the Print Service instance supports the attribute but does not support that particular value of the attribute, or null if there are no such attribute values.

Method Detail

getUnsupportedAttributes

Class[] getUnsupportedAttributes()
Returns the array of printing attribute classes for which the Print Service instance does not support the attribute at all, or null if there are no such attributes. The objects in the returned array are classes that extend the base interface Attribute.

Returns:
unsupported attribute classes

getUnsupportedValues

Attribute[] getUnsupportedValues()
Returns the array of printing attributes for which the Print Service instance supports the attribute but does not support that particular value of the attribute, or null if there are no such attribute values.

Returns:
unsupported attribute values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


CancelablePrintJob

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Interface CancelablePrintJob

All Superinterfaces:
DocPrintJob
public interface CancelablePrintJob
extends DocPrintJob

This interface is used by a printing application to cancel a print job. This interface extends DocPrintJob. A DocPrintJob implementation returned from a print service implements this interface if the print job can be cancelled. Before trying to cancel a print job, the client needs to test if the DocPrintJob object returned from the print service actually implements this interface. Clients should never assume that a DocPrintJob implements this interface. A print service might support cancellation only for certain types of print data and representation class names. This means that only some of the DocPrintJob objects returned from a service will implement this interface.

Service implementors are encouraged to implement this optional interface and to deliver a javax.print.event.PrintJobEvent.JOB_CANCELLED event to any listeners if a job is successfully cancelled with an implementation of this interface. Services should also note that an implementation of this method may be made from a separate client thread than that which made the print request. Thus the implementation of this interface must be made thread safe.

Method Summary
 void cancel()
Stops further processing of a print job.
Methods inherited from interface javax.print.DocPrintJob
addPrintJobAttributeListener, addPrintJobListener, getAttributes, getPrintService, print, removePrintJobAttributeListener, removePrintJobListener

Method Detail

cancel

void cancel()
            throws PrintException
Stops further processing of a print job.

If a service supports this method it cannot be concluded that job cancellation will always suceeed. A job may not be able to be cancelled once it has reached and passed some point in its processing. A successful cancellation means only that the entire job was not printed, some portion may already have printed when cancel returns.

The service will throw a PrintException if the cancellation did not succeed. A job which has not yet been submitted for printing should throw this exception. Cancelling an already successfully cancelled Print Job is not considered an error and will always succeed.

Cancellation in some services may be a lengthy process, involving requests to a server and processing of its print queue. Clients may wish to execute cancel in a thread which does not affect application execution.

Throws:
PrintException - if the job could not be successfully cancelled.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.print.DocFlavor

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.DocFlavor

Packages that use DocFlavor
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of DocFlavor in javax.print

Subclasses of DocFlavor in javax.print
static class | DocFlavor.BYTE_ARRAY Class DocFlavor.BYTE_ARRAY provides predefined static constant DocFlavor objects for example doc flavors using a byte array (byte[]) as the print data representation class.
static class | DocFlavor.CHAR_ARRAY Class DocFlavor.CHAR_ARRAY provides predefined static constant DocFlavor objects for example doc flavors using a character array (char[]) as the print data representation class.
static class | DocFlavor.INPUT_STREAM Class DocFlavor.INPUT_STREAM provides predefined static constant DocFlavor objects for example doc flavors using a byte stream (java.io.InputStream) as the print data representation class.
static class | DocFlavor.READER Class DocFlavor.READER provides predefined static constant DocFlavor objects for example doc flavors using a character stream (java.io.Reader) as the print data representation class.
static class | DocFlavor.SERVICE_FORMATTED Class DocFlavor.SERVICE_FORMATTED provides predefined static constant DocFlavor objects for example doc flavors for service formatted print data.
static class | DocFlavor.STRING Class DocFlavor.STRING provides predefined static constant DocFlavor objects for example doc flavors using a string (java.lang.String) as the print data representation class.
static class | DocFlavor.URL Class DocFlavor.URL provides predefined static constant DocFlavor objects.

Methods in javax.print that return DocFlavor
DocFlavor | SimpleDoc.getDocFlavor() Determines the doc flavor in which this doc object will supply its piece of print data.
DocFlavor | Doc.getDocFlavor() Determines the doc flavor in which this doc object will supply its piece of print data.
abstract DocFlavor[] | StreamPrintServiceFactory.getSupportedDocFlavors() Queries the factory for the document flavors that can be accepted by printers obtained from this factory.
DocFlavor[] | PrintService.getSupportedDocFlavors() Determines the print data formats a client can specify when setting up a job for this PrintService.
DocFlavor[] | FlavorException.getUnsupportedFlavors() Returns the unsupported flavors.

Methods in javax.print with parameters of type DocFlavor
abstract MultiDocPrintService[] | PrintServiceLookup.getMultiDocPrintServices(DocFlavor[] flavors, AttributeSet attributes) Not called directly by applications.
abstract PrintService[] | PrintServiceLookup.getPrintServices(DocFlavor flavor, AttributeSet attributes) Locates services that can be positively confirmed to support the combination of attributes and DocFlavors specified.
Object | PrintService.getSupportedAttributeValues(Class<? extends Attribute> category, DocFlavor flavor, AttributeSet attributes) Determines the printing attribute values a client can specify in the given category when setting up a job for this print service.
AttributeSet | PrintService.getUnsupportedAttributes(DocFlavor flavor, AttributeSet attributes) Identifies the attributes that are unsupported for a print request in the context of a particular DocFlavor.
boolean | PrintService.isAttributeValueSupported(Attribute attrval, DocFlavor flavor, AttributeSet attributes) Determines whether a client can specify the given printing attribute value when setting up a job for this Print Service.
boolean | PrintService.isDocFlavorSupported(DocFlavor flavor) Determines if this print service supports a specific DocFlavor.
static MultiDocPrintService[] | PrintServiceLookup.lookupMultiDocPrintServices(DocFlavor[] flavors, AttributeSet attributes) Locates MultiDoc print Services capable of printing MultiDocs containing all the specified doc flavors.
static PrintService[] | PrintServiceLookup.lookupPrintServices(DocFlavor flavor, AttributeSet attributes) Locates print services capable of printing the specified DocFlavor.
static StreamPrintServiceFactory[] | StreamPrintServiceFactory.lookupStreamPrintServiceFactories(DocFlavor flavor, String outputMimeType) Locates factories for print services that can be used with a print job to output a stream of data in the format specified by flavor.
static PrintService | ServiceUI.printDialog(GraphicsConfiguration gc, int x, int y, PrintService[] services, PrintService defaultService, DocFlavor flavor, PrintRequestAttributeSet attributes) Presents a dialog to the user for selecting a print service (printer).

Constructors in javax.print with parameters of type DocFlavor
SimpleDoc(Object printData, DocFlavor flavor, DocAttributeSet attributes)
Constructs a SimpleDoc with the specified print data, doc flavor and doc attribute set.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.DocFlavor.BYTE_ARRAY

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.DocFlavor.BYTE_ARRAY

Packages that use DocFlavor.BYTE_ARRAY
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of DocFlavor.BYTE_ARRAY in javax.print

Fields in javax.print declared as DocFlavor.BYTE_ARRAY
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.AUTOSENSE Doc flavor with MIME type = "application/octet-stream", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.GIF Doc flavor with MIME type = "image/gif", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.JPEG Doc flavor with MIME type = "image/jpeg", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.PCL Doc flavor with MIME type = "application/vnd.hp-PCL", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.PDF Doc flavor with MIME type = "application/pdf", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.PNG Doc flavor with MIME type = "image/png", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.POSTSCRIPT Doc flavor with MIME type = "application/postscript", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.TEXT_HTML_HOST Doc flavor with MIME type = "text/html", encoded in the host platform encoding.
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.TEXT_HTML_US_ASCII Doc flavor with MIME type = "text/html; charset=us-ascii", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.TEXT_HTML_UTF_16 Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.TEXT_HTML_UTF_16BE Doc flavor with MIME type = "text/html; charset=utf-16be" (big-endian byte ordering), print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.TEXT_HTML_UTF_16LE Doc flavor with MIME type = "text/html; charset=utf-16le" (little-endian byte ordering), print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.TEXT_HTML_UTF_8 Doc flavor with MIME type = "text/html; charset=utf-8", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.TEXT_PLAIN_HOST Doc flavor with MIME type = "text/plain", encoded in the host platform encoding.
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.TEXT_PLAIN_US_ASCII Doc flavor with MIME type = "text/plain; charset=us-ascii", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.TEXT_PLAIN_UTF_16 Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.TEXT_PLAIN_UTF_16BE Doc flavor with MIME type = "text/plain; charset=utf-16be" (big-endian byte ordering), print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.TEXT_PLAIN_UTF_16LE Doc flavor with MIME type = "text/plain; charset=utf-16le" (little-endian byte ordering), print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | DocFlavor.BYTE_ARRAY.TEXT_PLAIN_UTF_8 Doc flavor with MIME type = "text/plain; charset=utf-8", print data representation class name = "[B" (byte array).

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.DocFlavor.CHAR_ARRAY

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.DocFlavor.CHAR_ARRAY

Packages that use DocFlavor.CHAR_ARRAY
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of DocFlavor.CHAR_ARRAY in javax.print

Fields in javax.print declared as DocFlavor.CHAR_ARRAY
static DocFlavor.CHAR_ARRAY | DocFlavor.CHAR_ARRAY.TEXT_HTML Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "[C" (character array).
static DocFlavor.CHAR_ARRAY | DocFlavor.CHAR_ARRAY.TEXT_PLAIN Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = "[C" (character array).

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.DocFlavor.INPUT_STREAM

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.DocFlavor.INPUT_STREAM

Packages that use DocFlavor.INPUT_STREAM
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of DocFlavor.INPUT_STREAM in javax.print

Fields in javax.print declared as DocFlavor.INPUT_STREAM
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.AUTOSENSE Doc flavor with MIME type = "application/octet-stream", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.GIF Doc flavor with MIME type = "image/gif", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.JPEG Doc flavor with MIME type = "image/jpeg", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.PCL Doc flavor with MIME type = "application/vnd.hp-PCL", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.PDF Doc flavor with MIME type = "application/pdf", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.PNG Doc flavor with MIME type = "image/png", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.POSTSCRIPT Doc flavor with MIME type = "application/postscript", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.TEXT_HTML_HOST Doc flavor with MIME type = "text/html", encoded in the host platform encoding.
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.TEXT_HTML_US_ASCII Doc flavor with MIME type = "text/html; charset=us-ascii", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.TEXT_HTML_UTF_16 Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.TEXT_HTML_UTF_16BE Doc flavor with MIME type = "text/html; charset=utf-16be" (big-endian byte ordering), print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.TEXT_HTML_UTF_16LE Doc flavor with MIME type = "text/html; charset=utf-16le" (little-endian byte ordering), print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.TEXT_HTML_UTF_8 Doc flavor with MIME type = "text/html; charset=utf-8", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.TEXT_PLAIN_HOST Doc flavor with MIME type = "text/plain", encoded in the host platform encoding.
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.TEXT_PLAIN_US_ASCII Doc flavor with MIME type = "text/plain; charset=us-ascii", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.TEXT_PLAIN_UTF_16 Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.TEXT_PLAIN_UTF_16BE Doc flavor with MIME type = "text/plain; charset=utf-16be" (big-endian byte ordering), print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.TEXT_PLAIN_UTF_16LE Doc flavor with MIME type = "text/plain; charset=utf-16le" (little-endian byte ordering), print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | DocFlavor.INPUT_STREAM.TEXT_PLAIN_UTF_8 Doc flavor with MIME type = "text/plain; charset=utf-8", print data representation class name = "java.io.InputStream" (byte stream).

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.DocFlavor.READER

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.DocFlavor.READER

Packages that use DocFlavor.READER
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of DocFlavor.READER in javax.print

Fields in javax.print declared as DocFlavor.READER
static DocFlavor.READER | DocFlavor.READER.TEXT_HTML Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "java.io.Reader" (character stream).
static DocFlavor.READER | DocFlavor.READER.TEXT_PLAIN Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = "java.io.Reader" (character stream).

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.DocFlavor.SERVICE_FORMATTED

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.DocFlavor.SERVICE_FORMATTED

Packages that use DocFlavor.SERVICE_FORMATTED
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of DocFlavor.SERVICE_FORMATTED in javax.print

Fields in javax.print declared as DocFlavor.SERVICE_FORMATTED
static DocFlavor.SERVICE_FORMATTED | DocFlavor.SERVICE_FORMATTED.PAGEABLE Service formatted print data doc flavor with print data representation class name = "java.awt.print.Pageable" (pageable object).
static DocFlavor.SERVICE_FORMATTED | DocFlavor.SERVICE_FORMATTED.PRINTABLE Service formatted print data doc flavor with print data representation class name = "java.awt.print.Printable" (printable object).
static DocFlavor.SERVICE_FORMATTED | DocFlavor.SERVICE_FORMATTED.RENDERABLE_IMAGE Service formatted print data doc flavor with print data representation class name = "java.awt.image.renderable.RenderableImage" (renderable image object).

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.DocFlavor.STRING

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.DocFlavor.STRING

Packages that use DocFlavor.STRING
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of DocFlavor.STRING in javax.print

Fields in javax.print declared as DocFlavor.STRING
static DocFlavor.STRING | DocFlavor.STRING.TEXT_HTML Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "java.lang.String".
static DocFlavor.STRING | DocFlavor.STRING.TEXT_PLAIN Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = "java.lang.String".

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.DocFlavor.URL

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.DocFlavor.URL

Packages that use DocFlavor.URL
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of DocFlavor.URL in javax.print

Fields in javax.print declared as DocFlavor.URL
static DocFlavor.URL | DocFlavor.URL.AUTOSENSE Doc flavor with MIME type = "application/octet-stream", print data representation class name = "java.net.URL".
static DocFlavor.URL | DocFlavor.URL.GIF Doc flavor with MIME type = "image/gif", print data representation class name = "java.net.URL".
static DocFlavor.URL | DocFlavor.URL.JPEG Doc flavor with MIME type = "image/jpeg", print data representation class name = "java.net.URL".
static DocFlavor.URL | DocFlavor.URL.PCL Doc flavor with MIME type = "application/vnd.hp-PCL", print data representation class name = "java.net.URL".
static DocFlavor.URL | DocFlavor.URL.PDF Doc flavor with MIME type = "application/pdf", print data representation class name = "java.net.URL".
static DocFlavor.URL | DocFlavor.URL.PNG Doc flavor with MIME type = "image/png", print data representation class name = "java.net.URL".
static DocFlavor.URL | DocFlavor.URL.POSTSCRIPT Doc flavor with MIME type = "application/postscript", print data representation class name = "java.net.URL".
static DocFlavor.URL | DocFlavor.URL.TEXT_HTML_HOST Doc flavor with MIME type = "text/html", encoded in the host platform encoding.
static DocFlavor.URL | DocFlavor.URL.TEXT_HTML_US_ASCII Doc flavor with MIME type = "text/html; charset=us-ascii", print data representation class name = "java.net.URL" (byte stream).
static DocFlavor.URL | DocFlavor.URL.TEXT_HTML_UTF_16 Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "java.net.URL" (byte stream).
static DocFlavor.URL | DocFlavor.URL.TEXT_HTML_UTF_16BE Doc flavor with MIME type = "text/html; charset=utf-16be" (big-endian byte ordering), print data representation class name = "java.net.URL" (byte stream).
static DocFlavor.URL | DocFlavor.URL.TEXT_HTML_UTF_16LE Doc flavor with MIME type = "text/html; charset=utf-16le" (little-endian byte ordering), print data representation class name = "java.net.URL" (byte stream).
static DocFlavor.URL | DocFlavor.URL.TEXT_HTML_UTF_8 Doc flavor with MIME type = "text/html; charset=utf-8", print data representation class name = "java.net.URL" (byte stream).
static DocFlavor.URL | DocFlavor.URL.TEXT_PLAIN_HOST Doc flavor with MIME type = "text/plain", encoded in the host platform encoding.
static DocFlavor.URL | DocFlavor.URL.TEXT_PLAIN_US_ASCII Doc flavor with MIME type = "text/plain; charset=us-ascii", print data representation class name = "java.net.URL" (byte stream).
static DocFlavor.URL | DocFlavor.URL.TEXT_PLAIN_UTF_16 Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = java.net.URL"" (byte stream).
static DocFlavor.URL | DocFlavor.URL.TEXT_PLAIN_UTF_16BE Doc flavor with MIME type = "text/plain; charset=utf-16be" (big-endian byte ordering), print data representation class name = "java.net.URL" (byte stream).
static DocFlavor.URL | DocFlavor.URL.TEXT_PLAIN_UTF_16LE Doc flavor with MIME type = "text/plain; charset=utf-16le" (little-endian byte ordering), print data representation class name = "java.net.URL" (byte stream).
static DocFlavor.URL | DocFlavor.URL.TEXT_PLAIN_UTF_8 Doc flavor with MIME type = "text/plain; charset=utf-8", print data representation class name = "java.net.URL" (byte stream).

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.PrintException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.PrintException

Packages that use PrintException
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of PrintException in javax.print

Methods in javax.print that throw PrintException
void | CancelablePrintJob.cancel() Stops further processing of a print job.
void | DocPrintJob.print(Doc doc, PrintRequestAttributeSet attributes) Prints a document with the specified job attributes.
void | MultiDocPrintJob.print(MultiDoc multiDoc, PrintRequestAttributeSet attributes) Print a MultiDoc with the specified job attributes.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.PrintServiceLookup

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.PrintServiceLookup

Packages that use PrintServiceLookup
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of PrintServiceLookup in javax.print

Methods in javax.print with parameters of type PrintServiceLookup
static boolean PrintServiceLookup.registerServiceProvider(PrintServiceLookup sp)
Allows an application to explicitly register a class that implements lookup services.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.ServiceUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.ServiceUI

No usage of javax.print.ServiceUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.ServiceUIFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.ServiceUIFactory

Packages that use ServiceUIFactory
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of ServiceUIFactory in javax.print

Methods in javax.print that return ServiceUIFactory
 ServiceUIFactory PrintService.getServiceUIFactory()
Returns a factory for UI components which allow users to interact with the service in various roles.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.SimpleDoc

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.SimpleDoc

No usage of javax.print.SimpleDoc

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.StreamPrintService

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.StreamPrintService

Packages that use StreamPrintService
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of StreamPrintService in javax.print

Methods in javax.print that return StreamPrintService
abstract  StreamPrintService StreamPrintServiceFactory.getPrintService(OutputStream out)
Returns a StreamPrintService that can print to the specified output stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.StreamPrintServiceFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.StreamPrintServiceFactory

Packages that use StreamPrintServiceFactory
java.awt.print | Provides classes and interfaces for a general printing API.
javax.print | Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of StreamPrintServiceFactory in java.awt.print

Methods in java.awt.print that return StreamPrintServiceFactory
static StreamPrintServiceFactory[] PrinterJob.lookupStreamPrintServices(String mimeType)
A convenience method which locates factories for stream print services which can image 2D graphics.

Uses of StreamPrintServiceFactory in javax.print

Methods in javax.print that return StreamPrintServiceFactory
static StreamPrintServiceFactory[] StreamPrintServiceFactory.lookupStreamPrintServiceFactories(DocFlavor flavor, String outputMimeType)
Locates factories for print services that can be used with a print job to output a stream of data in the format specified by flavor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.AttributeException

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.AttributeException

No usage of javax.print.AttributeException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.CancelablePrintJob

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.CancelablePrintJob

No usage of javax.print.CancelablePrintJob

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.Doc

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.Doc

Packages that use Doc
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of Doc in javax.print

Classes in javax.print that implement Doc
 class SimpleDoc
This class is an implementation of interface Doc that can be used in many common printing requests.

Methods in javax.print that return Doc
 Doc MultiDoc.getDoc()
Obtain the current doc object.

Methods in javax.print with parameters of type Doc
 void DocPrintJob.print(Doc doc, PrintRequestAttributeSet attributes)
Prints a document with the specified job attributes.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.DocPrintJob

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.DocPrintJob

Packages that use DocPrintJob
javax.print | Provides the principal classes and interfaces for the JavaTM Print Service API.
javax.print.event | Package javax.print.event contains event classes and listener interfaces.

Uses of DocPrintJob in javax.print

Subinterfaces of DocPrintJob in javax.print
interface | CancelablePrintJob This interface is used by a printing application to cancel a print job.
interface | MultiDocPrintJob Obtained from a MultiDocPrintService, a MultiDocPrintJob can print a specified collection of documents as a single print job with a set of job attributes.

Methods in javax.print that return DocPrintJob
 DocPrintJob PrintService.createPrintJob()
Creates and returns a PrintJob capable of handling data from any of the supported document flavors.

Uses of DocPrintJob in javax.print.event

Methods in javax.print.event that return DocPrintJob
DocPrintJob | PrintJobAttributeEvent.getPrintJob() Determine the Print Job to which this print job event pertains.
DocPrintJob | PrintJobEvent.getPrintJob() Determines the DocPrintJob to which this print job event pertains.

Constructors in javax.print.event with parameters of type DocPrintJob
PrintJobAttributeEvent(DocPrintJob source, PrintJobAttributeSet attributes)
Constructs a PrintJobAttributeEvent object.
PrintJobEvent(DocPrintJob source, int reason)
Constructs a PrintJobEvent object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.FlavorException

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.FlavorException

No usage of javax.print.FlavorException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.MultiDoc

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.MultiDoc

Packages that use MultiDoc
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of MultiDoc in javax.print

Methods in javax.print that return MultiDoc
 MultiDoc MultiDoc.next()
Go to the multidoc object that contains the next doc object in the sequence of doc objects.

Methods in javax.print with parameters of type MultiDoc
 void MultiDocPrintJob.print(MultiDoc multiDoc, PrintRequestAttributeSet attributes)
Print a MultiDoc with the specified job attributes.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.MultiDocPrintJob

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.MultiDocPrintJob

Packages that use MultiDocPrintJob
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of MultiDocPrintJob in javax.print

Methods in javax.print that return MultiDocPrintJob
 MultiDocPrintJob MultiDocPrintService.createMultiDocPrintJob()
Create a job which can print a multiDoc.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.MultiDocPrintService

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.MultiDocPrintService

Packages that use MultiDocPrintService
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of MultiDocPrintService in javax.print

Methods in javax.print that return MultiDocPrintService
abstract MultiDocPrintService[] | PrintServiceLookup.getMultiDocPrintServices(DocFlavor[] flavors, AttributeSet attributes) Not called directly by applications.
static MultiDocPrintService[] | PrintServiceLookup.lookupMultiDocPrintServices(DocFlavor[] flavors, AttributeSet attributes) Locates MultiDoc print Services capable of printing MultiDocs containing all the specified doc flavors.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.PrintService

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.PrintService

Packages that use PrintService
java.awt.print | Provides classes and interfaces for a general printing API.
javax.print | Provides the principal classes and interfaces for the JavaTM Print Service API.
javax.print.event | Package javax.print.event contains event classes and listener interfaces.
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of PrintService in java.awt.print

Methods in java.awt.print that return PrintService
PrintService | PrinterJob.getPrintService() Returns the service (printer) for this printer job.
static PrintService[] | PrinterJob.lookupPrintServices() A convenience method which looks up 2D print services.

Methods in java.awt.print with parameters of type PrintService
 void PrinterJob.setPrintService(PrintService service)
Associate this PrinterJob with a new PrintService.

Uses of PrintService in javax.print

Subinterfaces of PrintService in javax.print
 interface MultiDocPrintService
Interface MultiPrintService is the factory for a MultiDocPrintJob.

Classes in javax.print that implement PrintService
 class StreamPrintService
This class extends PrintService and represents a print service that prints data in different formats to a client-provided output stream.

Methods in javax.print that return PrintService
abstract PrintService | PrintServiceLookup.getDefaultPrintService() Not called directly by applications.
PrintService | DocPrintJob.getPrintService() Determines the PrintService object to which this print job object is bound.
abstract PrintService[] | PrintServiceLookup.getPrintServices() Not called directly by applications.
abstract PrintService[] | PrintServiceLookup.getPrintServices(DocFlavor flavor, AttributeSet attributes) Locates services that can be positively confirmed to support the combination of attributes and DocFlavors specified.
static PrintService | PrintServiceLookup.lookupDefaultPrintService() Locates the default print service for this environment.
static PrintService[] | PrintServiceLookup.lookupPrintServices(DocFlavor flavor, AttributeSet attributes) Locates print services capable of printing the specified DocFlavor.
static PrintService | ServiceUI.printDialog(GraphicsConfiguration gc, int x, int y, PrintService[] services, PrintService defaultService, DocFlavor flavor, PrintRequestAttributeSet attributes) Presents a dialog to the user for selecting a print service (printer).

Methods in javax.print with parameters of type PrintService
static PrintService | ServiceUI.printDialog(GraphicsConfiguration gc, int x, int y, PrintService[] services, PrintService defaultService, DocFlavor flavor, PrintRequestAttributeSet attributes) Presents a dialog to the user for selecting a print service (printer).
static PrintService | ServiceUI.printDialog(GraphicsConfiguration gc, int x, int y, PrintService[] services, PrintService defaultService, DocFlavor flavor, PrintRequestAttributeSet attributes) Presents a dialog to the user for selecting a print service (printer).
static boolean | PrintServiceLookup.registerService(PrintService service) Allows an application to directly register an instance of a class which implements a print service.

Uses of PrintService in javax.print.event

Methods in javax.print.event that return PrintService
 PrintService PrintServiceAttributeEvent.getPrintService()
Returns the print service.

Constructors in javax.print.event with parameters of type PrintService
PrintServiceAttributeEvent(PrintService source, PrintServiceAttributeSet attributes)
Constructs a PrintServiceAttributeEvent object.

Uses of PrintService in javax.swing

Methods in javax.swing with parameters of type PrintService
 boolean JTable.print(JTable.PrintMode printMode, MessageFormat headerFormat, MessageFormat footerFormat, boolean showPrintDialog, PrintRequestAttributeSet attr, boolean interactive, PrintService service)
Prints this JTable.

Uses of PrintService in javax.swing.text

Methods in javax.swing.text with parameters of type PrintService
 boolean JTextComponent.print(MessageFormat headerFormat, MessageFormat footerFormat, boolean showPrintDialog, PrintService service, PrintRequestAttributeSet attributes, boolean interactive)
Prints the content of this JTextComponent.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.URIException

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.URIException

No usage of javax.print.URIException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Doc

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Interface Doc

All Known Implementing Classes:
SimpleDoc
public interface Doc

Interface Doc specifies the interface for an object that supplies one piece of print data for a Print Job. "Doc" is a short, easy-to-pronounce term that means "a piece of print data." The client passes to the Print Job an object that implements interface Doc, and the Print Job calls methods on that object to obtain the print data. The Doc interface lets a Print Job:

  • Determine the format, or "doc flavor" (class DocFlavor), in which the print data is available. A doc flavor designates the print data format (a MIME type) and the representation class of the object from which the print data comes.

  • Obtain the print data representation object, which is an instance of the doc flavor's representation class. The Print Job can then obtain the actual print data from the representation object.

  • Obtain the printing attributes that specify additional characteristics of the doc or that specify processing instructions to be applied to the doc. Printing attributes are defined in package javax.print.attribute. The doc returns its printing attributes stored in an javax.print.attribute.DocAttributeSet.

Each method in an implementation of interface Doc is permitted always to return the same object each time the method is called. This has implications for a Print Job or other caller of a doc object whose print data representation object "consumes" the print data as the caller obtains the print data, such as a print data representation object which is a stream. Once the Print Job has called getPrintData() and obtained the stream, any further calls to getPrintData() will return the same stream object upon which reading may already be in progress, not a new stream object that will re-read the print data from the beginning. Specifying a doc object to behave this way simplifies the implementation of doc objects, and is justified on the grounds that a particular doc is intended to convey print data only to one Print Job, not to several different Print Jobs. (To convey the same print data to several different Print Jobs, you have to create several different doc objects on top of the same print data source.)

Interface Doc affords considerable implementation flexibility. The print data might already be in existence when the doc object is constructed. In this case the objects returned by the doc's methods can be supplied to the doc's constructor, be stored in the doc ahead of time, and simply be returned when called for. Alternatively, the print data might not exist yet when the doc object is constructed. In this case the doc object might provide a "lazy" implementation that generates the print data representation object (and/or the print data) only when the Print Job calls for it (when the Print Job calls the getPrintData() method).

There is no restriction on the number of client threads that may be simultaneously accessing the same doc. Therefore, all implementations of interface Doc must be designed to be multiple thread safe.

However there can only be one consumer of the print data obtained from a Doc.

If print data is obtained from the client as a stream, by calling Doc's getReaderForText() or getStreamForBytes() methods, or because the print data source is already an InputStream or Reader, then the print service should always close these streams for the client on all job completion conditions. With the following caveat. If the print data is itself a stream, the service will always close it. If the print data is otherwise something that can be requested as a stream, the service will only close the stream if it has obtained the stream before terminating. That is, just because a print service might request data as a stream does not mean that it will, with the implications that Doc implementors which rely on the service to close them should create such streams only in response to a request from the service.

Method Summary
DocAttributeSet | getAttributes() Obtains the set of printing attributes for this doc object.
DocFlavor | getDocFlavor() Determines the doc flavor in which this doc object will supply its piece of print data.
Object | getPrintData() Obtains the print data representation object that contains this doc object's piece of print data in the format corresponding to the supported doc flavor.
Reader | getReaderForText() Obtains a reader for extracting character print data from this doc.
InputStream | getStreamForBytes() Obtains an input stream for extracting byte print data from this doc.

Method Detail

getDocFlavor

DocFlavor getDocFlavor()
Determines the doc flavor in which this doc object will supply its piece of print data.

Returns:
Doc flavor.

getPrintData

Object getPrintData()
                    throws IOException
Obtains the print data representation object that contains this doc object's piece of print data in the format corresponding to the supported doc flavor. The getPrintData() method returns an instance of the representation class whose name is given by getDocFlavor().getRepresentationClassName(), and the return value can be cast from class Object to that representation class.

Returns:
Print data representation object.
Throws:
IOException - Thrown if the representation class is a stream and there was an I/O error while constructing the stream.

getAttributes

DocAttributeSet getAttributes()
Obtains the set of printing attributes for this doc object. If the returned attribute set includes an instance of a particular attribute X, the printer must use that attribute value for this doc, overriding any value of attribute X in the job's attribute set. If the returned attribute set does not include an instance of a particular attribute X or if null is returned, the printer must consult the job's attribute set to obtain the value for attribute X, and if not found there, the printer must use an implementation-dependent default value. The returned attribute set is unmodifiable.

Returns:
Unmodifiable set of printing attributes for this doc, or null to obtain all attribute values from the job's attribute set.

getReaderForText

Reader getReaderForText()
                        throws IOException
Obtains a reader for extracting character print data from this doc. The Doc implementation is required to support this method if the DocFlavor has one of the following print data representation classes, and return null otherwise:
  • char[]
  • java.lang.String
  • java.io.Reader
The doc's print data representation object is used to construct and return a Reader for reading the print data as a stream of characters from the print data representation object. However, if the print data representation object is itself a Reader, then the print data representation object is simply returned.

Returns:
Reader for reading the print data characters from this doc. If a reader cannot be provided because this doc does not meet the criteria stated above, null is returned.
Throws:
IOException - Thrown if there was an I/O error while creating the reader.

getStreamForBytes

InputStream getStreamForBytes()
                              throws IOException
Obtains an input stream for extracting byte print data from this doc. The Doc implementation is required to support this method if the DocFlavor has one of the following print data representation classes, and return null otherwise:
  • byte[]
  • java.io.InputStream
This doc's print data representation object is obtained, then an input stream for reading the print data from the print data representation object as a stream of bytes is created and returned. However, if the print data representation object is itself an input stream, then the print data representation object is simply returned.

Returns:
Input stream for reading the print data bytes from this doc. If an input stream cannot be provided because this doc does not meet the criteria stated above, null is returned.
Throws:
IOException - Thrown if there was an I/O error while creating the input stream.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocFlavor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Class DocFlavor

java.lang.Object
    extended by  javax.print.DocFlavor
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
DocFlavor.BYTE_ARRAY, DocFlavor.CHAR_ARRAY, DocFlavor.INPUT_STREAM, DocFlavor.READER, DocFlavor.SERVICE_FORMATTED, DocFlavor.STRING, DocFlavor.URL
public class DocFlavor
extends Object
implements Serializable, Cloneable

Class DocFlavor encapsulates an object that specifies the format in which print data is supplied to a DocPrintJob. "Doc" is a short, easy-to-pronounce term that means "a piece of print data." The print data format, or "doc flavor", consists of two things:

  • MIME type. This is a Multipurpose Internet Mail Extensions (MIME) media type (as defined in RFC 2045 and RFC 2046) that specifies how the print data is to be interpreted. The charset of text data should be the IANA MIME-preferred name, or its canonical name if no preferred name is specified. Additionally a few historical names supported by earlier versions of the Java platform may be recognized. See character encodings for more information on the character encodings supported on the Java platform.

  • Representation class name. This specifies the fully-qualified name of the class of the object from which the actual print data comes, as returned by the Class.getName() method. (Thus the class name for byte[] is "[B", for char[] it is "[C".)

A DocPrintJob obtains its print data by means of interface Doc. A Doc object lets the DocPrintJob determine the doc flavor the client can supply. A Doc object also lets the DocPrintJob obtain an instance of the doc flavor's representation class, from which the DocPrintJob then obtains the actual print data.

Client Formatted Print Data

There are two broad categories of print data, client formatted print data and service formatted print data.

For client formatted print data, the client determines or knows the print data format. For example the client may have a JPEG encoded image, a URL for HTML code, or a disk file containing plain text in some encoding, possibly obtained from an external source, and requires a way to describe the data format to the print service.

The doc flavor's representation class is a conduit for the JPS DocPrintJob to obtain a sequence of characters or bytes from the client. The doc flavor's MIME type is one of the standard media types telling how to interpret the sequence of characters or bytes. For a list of standard media types, see the Internet Assigned Numbers Authority's (IANA's) Media Types Directory. Interface Doc provides two utility operations, getReaderForText and getStreamForBytes(), to help a Doc object's client extract client formatted print data.

For client formatted print data, the print data representation class is typically one of the following (although other representation classes are permitted):

  • Character array (char[]) -- The print data consists of the Unicde characters in the array.

  • String -- The print data consists of the Unicode characters in the string.

  • Character stream (java.io.Reader) -- The print data consists of the Unicode characters read from the stream up to the end-of-stream.

  • Byte array (byte[]) -- The print data consists of the bytes in the array. The bytes are encoded in the character set specified by the doc flavor's MIME type. If the MIME type does not specify a character set, the default character set is US-ASCII.

  • Byte stream (java.io.InputStream) -- The print data consists of the bytes read from the stream up to the end-of-stream. The bytes are encoded in the character set specified by the doc flavor's MIME type. If the MIME type does not specify a character set, the default character set is US-ASCII.
  • Uniform Resource Locator (URL) -- The print data consists of the bytes read from the URL location. The bytes are encoded in the character set specified by the doc flavor's MIME type. If the MIME type does not specify a character set, the default character set is US-ASCII.

    When the representation class is a URL, the print service itself accesses and downloads the document directly from its URL address, without involving the client. The service may be some form of network print service which is executing in a different environment. This means you should not use a URL print data flavor to print a document at a restricted URL that the client can see but the printer cannot see. This also means you should not use a URL print data flavor to print a document stored in a local file that is not available at a URL accessible independently of the client. For example, a file that is not served up by an HTTP server or FTP server. To print such documents, let the client open an input stream on the URL or file and use an input stream data flavor.

Default and Platform Encodings

For byte print data where the doc flavor's MIME type does not include a charset parameter, the Java Print Service instance assumes the US-ASCII character set by default. This is in accordance with RFC 2046, which says the default character set is US-ASCII. Note that US-ASCII is a subset of UTF-8, so in the future this may be widened if a future RFC endorses UTF-8 as the default in a compatible manner.

Also note that this is different than the behaviour of the Java runtime when interpreting a stream of bytes as text data. That assumes the default encoding for the user's locale. Thus, when spooling a file in local encoding to a Java Print Service it is important to correctly specify the encoding. Developers working in the English locales should be particularly conscious of this, as their platform encoding corresponds to the default mime charset. By this coincidence that particular case may work without specifying the encoding of platform data.

Every instance of the Java virtual machine has a default character encoding determined during virtual-machine startup and typically depends upon the locale and charset being used by the underlying operating system. In a distributed environment there is no gurantee that two VM's share the same default encoding. Thus clients which want to stream platform encoded text data from the host platform to a Java Print Service instance must explicitly declare the charset and not rely on defaults.

The preferred form is the official IANA primary name for an encoding. Applications which stream text data should always specify the charset in the mime type, which necessitates obtaining the encoding of the host platform for data (eg files) stored in that platform's encoding. A CharSet which corresponds to this and is suitable for use in a mime-type for a DocFlavor can be obtained from DocFlavor.hostEncoding This may not always be the primary IANA name but is guaranteed to be understood by this VM. For common flavors, the pre-defined *HOST DocFlavors may be used.

See character encodings for more information on the character encodings supported on the Java platform.

Recommended DocFlavors

The Java Print Service API does not define any mandatorily supported DocFlavors. However, here are some examples of MIME types that a Java Print Service instance might support for client formatted print data. Nested classes inside class DocFlavor declare predefined static constant DocFlavor objects for these example doc flavors; class DocFlavor's constructor can be used to create an arbitrary doc flavor.

  • Preformatted text

    MIME-Type | Description
    "text/plain" | Plain text in the default character set (US-ASCII)
    "text/plain; charset=xxx" | Plain text in character set xxx
    "text/html" | HyperText Markup Language in the default character set (US-ASCII)
    "text/html; charset=xxx" | HyperText Markup Language in character set xxx

    In general, preformatted text print data is provided either in a character oriented representation class (character array, String, Reader) or in a byte oriented representation class (byte array, InputStream, URL).

  • Preformatted page description language (PDL) documents

    MIME-Type | Description
    "application/pdf" | Portable Document Format document
    "application/postscript" | PostScript document
    "application/vnd.hp-PCL" | Printer Control Language document

    In general, preformatted PDL print data is provided in a byte oriented representation class (byte array, InputStream, URL).

  • Preformatted images

    MIME-Type | Description
    "image/gif" | Graphics Interchange Format image
    "image/jpeg" | Joint Photographic Experts Group image
    "image/png" | Portable Network Graphics image

    In general, preformatted image print data is provided in a byte oriented representation class (byte array, InputStream, URL).

  • Preformatted autosense print data

    MIME-Type | Description
    "application/octet-stream" | The print data format is unspecified (just an octet stream)

    The printer decides how to interpret the print data; the way this "autosensing" works is implementation dependent. In general, preformatted autosense print data is provided in a byte oriented representation class (byte array, InputStream, URL).

    Service Formatted Print Data

    For service formatted print data, the Java Print Service instance determines the print data format. The doc flavor's representation class denotes an interface whose methods the DocPrintJob invokes to determine the content to be printed -- such as a renderable image interface or a Java printable interface. The doc flavor's MIME type is the special value "application/x-java-jvm-local-objectref" indicating the client will supply a reference to a Java object that implements the interface named as the representation class. This MIME type is just a placeholder; what's important is the print data representation class.

    For service formatted print data, the print data representation class is typically one of the following (although other representation classes are permitted). Nested classes inside class DocFlavor declare predefined static constant DocFlavor objects for these example doc flavors; class DocFlavor's constructor can be used to create an arbitrary doc flavor.

    • Renderable image object -- The client supplies an object that implements interface RenderableImage. The printer calls methods in that interface to obtain the image to be printed.

    • Printable object -- The client supplies an object that implements interface Printable. The printer calls methods in that interface to obtain the pages to be printed, one by one. For each page, the printer supplies a graphics context, and whatever the client draws in that graphics context gets printed.

    • Pageable object -- The client supplies an object that implements interface Pageable. The printer calls methods in that interface to obtain the pages to be printed, one by one. For each page, the printer supplies a graphics context, and whatever the client draws in that graphics context gets printed.

    Pre-defined Doc Flavors

    A Java Print Service instance is not required to support the following print data formats and print data representation classes. In fact, a developer using this class should never assume that a particular print service supports the document types corresponding to these pre-defined doc flavors. Always query the print service to determine what doc flavors it supports. However, developers who have print services that support these doc flavors are encouraged to refer to the predefined singleton instances created here.
    • Plain text print data provided through a byte stream. Specifically, the following doc flavors are recommended to be supported:
      · ("text/plain", "java.io.InputStream")
      · ("text/plain; charset=us-ascii", "java.io.InputStream")
      · ("text/plain; charset=utf-8", "java.io.InputStream")

    • Renderable image objects. Specifically, the following doc flavor is recommended to be supported:
      · ("application/x-java-jvm-local-objectref", "java.awt.image.renderable.RenderableImage")

    A Java Print Service instance is allowed to support any other doc flavors (or none) in addition to the above mandatory ones, at the implementation's choice.

    Support for the above doc flavors is desirable so a printing client can rely on being able to print on any JPS printer, regardless of which doc flavors the printer supports. If the printer doesn't support the client's preferred doc flavor, the client can at least print plain text, or the client can convert its data to a renderable image and print the image.

    Furthermore, every Java Print Service instance must fulfill these requirements for processing plain text print data:

    • The character pair carriage return-line feed (CR-LF) means "go to column 1 of the next line."
    • A carriage return (CR) character standing by itself means "go to column 1 of the next line."
    • A line feed (LF) character standing by itself means "go to column 1 of the next line."

    The client must itself perform all plain text print data formatting not addressed by the above requirements.

    Design Rationale

    Class DocFlavor in package javax.print.data is similar to class DataFlavor. Class DataFlavor is not used in the Java Print Service (JPS) API for three reasons which are all rooted in allowing the JPS API to be shared by other print services APIs which may need to run on Java profiles which do not include all of the Java Platform, Standard Edition.

    1. The JPS API is designed to be used in Java profiles which do not support AWT.

    2. The implementation of class java.awt.datatransfer.DataFlavor does not guarantee that equivalent data flavors will have the same serialized representation. DocFlavor does, and can be used in services which need this.

    3. The implementation of class java.awt.datatransfer.DataFlavor includes a human presentable name as part of the serialized representation. This is not appropriate as part of a service matching constraint.

    Class DocFlavor's serialized representation uses the following canonical form of a MIME type string. Thus, two doc flavors with MIME types that are not identical but that are equivalent (that have the same canonical form) may be considered equal.

    • The media type, media subtype, and parameters are retained, but all comments and whitespace characters are discarded.
    • The media type, media subtype, and parameter names are converted to lowercase.
    • The parameter values retain their original case, except a charset parameter value for a text media type is converted to lowercase.
    • Quote characters surrounding parameter values are removed.
    • Quoting backslash characters inside parameter values are removed.
    • The parameters are arranged in ascending order of parameter name.

    Class DocFlavor's serialized representation also contains the fully-qualified class name of the representation class (a String object), rather than the representation class itself (a Class object). This allows a client to examine the doc flavors a Java Print Service instance supports without having to load the representation classes, which may be problematic for limited-resource clients.

    See Also:
    Serialized Form

    Nested Class Summary
    static class DocFlavor.BYTE_ARRAY
    Class DocFlavor.BYTE_ARRAY provides predefined static constant DocFlavor objects for example doc flavors using a byte array (byte[]) as the print data representation class.
    static class DocFlavor.CHAR_ARRAY
    Class DocFlavor.CHAR_ARRAY provides predefined static constant DocFlavor objects for example doc flavors using a character array (char[]) as the print data representation class.
    static class DocFlavor.INPUT_STREAM
    Class DocFlavor.INPUT_STREAM provides predefined static constant DocFlavor objects for example doc flavors using a byte stream (java.io.InputStream) as the print data representation class.
    static class DocFlavor.READER
    Class DocFlavor.READER provides predefined static constant DocFlavor objects for example doc flavors using a character stream (java.io.Reader) as the print data representation class.
    static class DocFlavor.SERVICE_FORMATTED
    Class DocFlavor.SERVICE_FORMATTED provides predefined static constant DocFlavor objects for example doc flavors for service formatted print data.
    static class DocFlavor.STRING
    Class DocFlavor.STRING provides predefined static constant DocFlavor objects for example doc flavors using a string (java.lang.String) as the print data representation class.
    static class DocFlavor.URL
    Class DocFlavor.URL provides predefined static constant DocFlavor objects.
    Field Summary
    static String hostEncoding
    A String representing the host operating system encoding.
    Constructor Summary
    DocFlavor(String mimeType, String className)
    Constructs a new doc flavor object from the given MIME type and representation class name.
    Method Summary
     boolean equals(Object obj)
    Determines if this doc flavor object is equal to the given object.
     String getMediaSubtype()
    Returns this doc flavor object's media subtype (from the MIME type).
     String getMediaType()
    Returns this doc flavor object's media type (from the MIME type).
     String getMimeType()
    Returns this doc flavor object's MIME type string based on the canonical form.
     String getParameter(String paramName)
    Returns a String representing a MIME parameter.
     String getRepresentationClassName()
    Returns the name of this doc flavor object's representation class.
     int hashCode()
    Returns a hash code for this doc flavor object.
     String toString()
    Converts this DocFlavor to a string.
    Methods inherited from class java.lang.Object
    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    Field Detail

    hostEncoding

    public static final String hostEncoding
    A String representing the host operating system encoding. This will follow the conventions documented in RFC 2278: IANA Charset Registration Procedures except where historical names are returned for compatibility with previous versions of the Java platform. The value returned from method is valid only for the VM which returns it, for use in a DocFlavor. This is the charset for all the "HOST" pre-defined DocFlavors in the executing VM.

    Constructor Detail

    DocFlavor

    public DocFlavor(String mimeType,
                 String className)
    Constructs a new doc flavor object from the given MIME type and representation class name. The given MIME type is converted into canonical form and stored internally.

    Parameters:
    mimeType - MIME media type string.
    className - Fully-qualified representation class name.
    Throws:
    NullPointerException - (unchecked exception) Thrown if mimeType is null or className is null.
    IllegalArgumentException - (unchecked exception) Thrown if mimeType does not obey the syntax for a MIME media type string.
    Method Detail

    getMimeType

    public String getMimeType()
    Returns this doc flavor object's MIME type string based on the canonical form. Each parameter value is enclosed in quotes.

    Returns:
    the mime type

    getMediaType

    public String getMediaType()
    Returns this doc flavor object's media type (from the MIME type).

    Returns:
    the media type

    getMediaSubtype

    public String getMediaSubtype()
    Returns this doc flavor object's media subtype (from the MIME type).

    Returns:
    the media sub-type

    getParameter

    public String getParameter(String paramName)
    Returns a String representing a MIME parameter. Mime types may include parameters which are usually optional. The charset for text types is a commonly useful example. This convenience method will return the value of the specified parameter if one was specified in the mime type for this flavor.

    Parameters:
    paramName - the name of the paramater. This name is internally converted to the canonical lower case format before performing the match.
    Returns:
    String representing a mime parameter, or null if that parameter is not in the mime type string.
    Throws:
    throws - NullPointerException if paramName is null.

    getRepresentationClassName

    public String getRepresentationClassName()
    Returns the name of this doc flavor object's representation class.

    Returns:
    the name of the representation class.

    toString

    public String toString()
    Converts this DocFlavor to a string.

    Overrides:
    toString in class Object
    Returns:
    MIME type string based on the canonical form. Each parameter value is enclosed in quotes. A "class=" parameter is appended to the MIME type string to indicate the representation class name.

    hashCode

    public int hashCode()
    Returns a hash code for this doc flavor object.

    Overrides:
    hashCode in class Object
    Returns:
    a hash code value for this object.
    See Also:
    Object.equals(java.lang.Object), Hashtable

    equals

    public boolean equals(Object obj)
    Determines if this doc flavor object is equal to the given object. The two are equal if the given object is not null, is an instance of DocFlavor, has a MIME type equivalent to this doc flavor object's MIME type (that is, the MIME types have the same media type, media subtype, and parameters), and has the same representation class name as this doc flavor object. Thus, if two doc flavor objects' MIME types are the same except for comments, they are considered equal. However, two doc flavor objects with MIME types of "text/plain" and "text/plain; charset=US-ASCII" are not considered equal, even though they represent the same media type (because the default character set for plain text is US-ASCII).

    Overrides:
    equals in class Object
    Parameters:
    obj - Object to test.
    Returns:
    True if this doc flavor object equals obj, false otherwise.
    See Also:
    Object.hashCode(), Hashtable
    Overview Package Class Use Tree Deprecated Index Help
            Java™ Platform
    Standard Ed. 6
    PREV CLASS NEXT CLASS FRAMES NO FRAMES
    SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocFlavor.BYTE_ARRAY

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Class DocFlavor.BYTE_ARRAY

java.lang.Object
    extended by  javax.print.DocFlavor
        extended by  javax.print.DocFlavor.BYTE_ARRAY
All Implemented Interfaces:
Serializable, Cloneable
Enclosing class:
DocFlavor
public static class DocFlavor.BYTE_ARRAY
extends DocFlavor

Class DocFlavor.BYTE_ARRAY provides predefined static constant DocFlavor objects for example doc flavors using a byte array (byte[]) as the print data representation class.

See Also:
Serialized Form

Nested Class Summary
Nested classes/interfaces inherited from class javax.print.DocFlavor
DocFlavor.BYTE_ARRAY, DocFlavor.CHAR_ARRAY, DocFlavor.INPUT_STREAM, DocFlavor.READER, DocFlavor.SERVICE_FORMATTED, DocFlavor.STRING, DocFlavor.URL
Field Summary
static DocFlavor.BYTE_ARRAY | AUTOSENSE Doc flavor with MIME type = "application/octet-stream", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | GIF Doc flavor with MIME type = "image/gif", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | JPEG Doc flavor with MIME type = "image/jpeg", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | PCL Doc flavor with MIME type = "application/vnd.hp-PCL", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | PDF Doc flavor with MIME type = "application/pdf", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | PNG Doc flavor with MIME type = "image/png", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | POSTSCRIPT Doc flavor with MIME type = "application/postscript", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | TEXT_HTML_HOST Doc flavor with MIME type = "text/html", encoded in the host platform encoding.
static DocFlavor.BYTE_ARRAY | TEXT_HTML_US_ASCII Doc flavor with MIME type = "text/html; charset=us-ascii", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | TEXT_HTML_UTF_16 Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | TEXT_HTML_UTF_16BE Doc flavor with MIME type = "text/html; charset=utf-16be" (big-endian byte ordering), print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | TEXT_HTML_UTF_16LE Doc flavor with MIME type = "text/html; charset=utf-16le" (little-endian byte ordering), print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | TEXT_HTML_UTF_8 Doc flavor with MIME type = "text/html; charset=utf-8", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | TEXT_PLAIN_HOST Doc flavor with MIME type = "text/plain", encoded in the host platform encoding.
static DocFlavor.BYTE_ARRAY | TEXT_PLAIN_US_ASCII Doc flavor with MIME type = "text/plain; charset=us-ascii", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | TEXT_PLAIN_UTF_16 Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | TEXT_PLAIN_UTF_16BE Doc flavor with MIME type = "text/plain; charset=utf-16be" (big-endian byte ordering), print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | TEXT_PLAIN_UTF_16LE Doc flavor with MIME type = "text/plain; charset=utf-16le" (little-endian byte ordering), print data representation class name = "[B" (byte array).
static DocFlavor.BYTE_ARRAY | TEXT_PLAIN_UTF_8 Doc flavor with MIME type = "text/plain; charset=utf-8", print data representation class name = "[B" (byte array).
Fields inherited from class javax.print.DocFlavor
hostEncoding
Constructor Summary
DocFlavor.BYTE_ARRAY(String mimeType)
Constructs a new doc flavor with the given MIME type and a print data representation class name of "[B" (byte array).
Method Summary
Methods inherited from class javax.print.DocFlavor
equals, getMediaSubtype, getMediaType, getMimeType, getParameter, getRepresentationClassName, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

TEXT_PLAIN_HOST

public static final DocFlavor.BYTE_ARRAY TEXT_PLAIN_HOST
Doc flavor with MIME type = "text/plain", encoded in the host platform encoding. See hostEncoding Print data representation class name = "[B" (byte array).

TEXT_PLAIN_UTF_8

public static final DocFlavor.BYTE_ARRAY TEXT_PLAIN_UTF_8
Doc flavor with MIME type = "text/plain; charset=utf-8", print data representation class name = "[B" (byte array).

TEXT_PLAIN_UTF_16

public static final DocFlavor.BYTE_ARRAY TEXT_PLAIN_UTF_16
Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = "[B" (byte array).

TEXT_PLAIN_UTF_16BE

public static final DocFlavor.BYTE_ARRAY TEXT_PLAIN_UTF_16BE
Doc flavor with MIME type = "text/plain; charset=utf-16be" (big-endian byte ordering), print data representation class name = "[B" (byte array).

TEXT_PLAIN_UTF_16LE

public static final DocFlavor.BYTE_ARRAY TEXT_PLAIN_UTF_16LE
Doc flavor with MIME type = "text/plain; charset=utf-16le" (little-endian byte ordering), print data representation class name = "[B" (byte array).

TEXT_PLAIN_US_ASCII

public static final DocFlavor.BYTE_ARRAY TEXT_PLAIN_US_ASCII
Doc flavor with MIME type = "text/plain; charset=us-ascii", print data representation class name = "[B" (byte array).

TEXT_HTML_HOST

public static final DocFlavor.BYTE_ARRAY TEXT_HTML_HOST
Doc flavor with MIME type = "text/html", encoded in the host platform encoding. See hostEncoding Print data representation class name = "[B" (byte array).

TEXT_HTML_UTF_8

public static final DocFlavor.BYTE_ARRAY TEXT_HTML_UTF_8
Doc flavor with MIME type = "text/html; charset=utf-8", print data representation class name = "[B" (byte array).

TEXT_HTML_UTF_16

public static final DocFlavor.BYTE_ARRAY TEXT_HTML_UTF_16
Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "[B" (byte array).

TEXT_HTML_UTF_16BE

public static final DocFlavor.BYTE_ARRAY TEXT_HTML_UTF_16BE
Doc flavor with MIME type = "text/html; charset=utf-16be" (big-endian byte ordering), print data representation class name = "[B" (byte array).

TEXT_HTML_UTF_16LE

public static final DocFlavor.BYTE_ARRAY TEXT_HTML_UTF_16LE
Doc flavor with MIME type = "text/html; charset=utf-16le" (little-endian byte ordering), print data representation class name = "[B" (byte array).

TEXT_HTML_US_ASCII

public static final DocFlavor.BYTE_ARRAY TEXT_HTML_US_ASCII
Doc flavor with MIME type = "text/html; charset=us-ascii", print data representation class name = "[B" (byte array).

PDF

public static final DocFlavor.BYTE_ARRAY PDF
Doc flavor with MIME type = "application/pdf", print data representation class name = "[B" (byte array).

POSTSCRIPT

public static final DocFlavor.BYTE_ARRAY POSTSCRIPT
Doc flavor with MIME type = "application/postscript", print data representation class name = "[B" (byte array).

PCL

public static final DocFlavor.BYTE_ARRAY PCL
Doc flavor with MIME type = "application/vnd.hp-PCL", print data representation class name = "[B" (byte array).

GIF

public static final DocFlavor.BYTE_ARRAY GIF
Doc flavor with MIME type = "image/gif", print data representation class name = "[B" (byte array).

JPEG

public static final DocFlavor.BYTE_ARRAY JPEG
Doc flavor with MIME type = "image/jpeg", print data representation class name = "[B" (byte array).

PNG

public static final DocFlavor.BYTE_ARRAY PNG
Doc flavor with MIME type = "image/png", print data representation class name = "[B" (byte array).

AUTOSENSE

public static final DocFlavor.BYTE_ARRAY AUTOSENSE
Doc flavor with MIME type = "application/octet-stream", print data representation class name = "[B" (byte array). The client must determine that data described using this DocFlavor is valid for the printer.

Constructor Detail

DocFlavor.BYTE_ARRAY

public DocFlavor.BYTE_ARRAY(String mimeType)
Constructs a new doc flavor with the given MIME type and a print data representation class name of "[B" (byte array).

Parameters:
mimeType - MIME media type string.
Throws:
NullPointerException - (unchecked exception) Thrown if mimeType is null.
IllegalArgumentException - (unchecked exception) Thrown if mimeType does not obey the syntax for a MIME media type string.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocFlavor.CHAR_ARRAY

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Class DocFlavor.CHAR_ARRAY

java.lang.Object
    extended by  javax.print.DocFlavor
        extended by  javax.print.DocFlavor.CHAR_ARRAY
All Implemented Interfaces:
Serializable, Cloneable
Enclosing class:
DocFlavor
public static class DocFlavor.CHAR_ARRAY
extends DocFlavor

Class DocFlavor.CHAR_ARRAY provides predefined static constant DocFlavor objects for example doc flavors using a character array (char[]) as the print data representation class. As such, the character set is Unicode.

See Also:
Serialized Form

Nested Class Summary
Nested classes/interfaces inherited from class javax.print.DocFlavor
DocFlavor.BYTE_ARRAY, DocFlavor.CHAR_ARRAY, DocFlavor.INPUT_STREAM, DocFlavor.READER, DocFlavor.SERVICE_FORMATTED, DocFlavor.STRING, DocFlavor.URL
Field Summary
static DocFlavor.CHAR_ARRAY | TEXT_HTML Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "[C" (character array).
static DocFlavor.CHAR_ARRAY | TEXT_PLAIN Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = "[C" (character array).
Fields inherited from class javax.print.DocFlavor
hostEncoding
Constructor Summary
DocFlavor.CHAR_ARRAY(String mimeType)
Constructs a new doc flavor with the given MIME type and a print data representation class name of "[C" (character array).
Method Summary
Methods inherited from class javax.print.DocFlavor
equals, getMediaSubtype, getMediaType, getMimeType, getParameter, getRepresentationClassName, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

TEXT_PLAIN

public static final DocFlavor.CHAR_ARRAY TEXT_PLAIN
Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = "[C" (character array).

TEXT_HTML

public static final DocFlavor.CHAR_ARRAY TEXT_HTML
Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "[C" (character array).

Constructor Detail

DocFlavor.CHAR_ARRAY

public DocFlavor.CHAR_ARRAY(String mimeType)
Constructs a new doc flavor with the given MIME type and a print data representation class name of "[C" (character array).

Parameters:
mimeType - MIME media type string. If it is a text media type, it is assumed to contain a "charset=utf-16" parameter.
Throws:
NullPointerException - (unchecked exception) Thrown if mimeType is null.
IllegalArgumentException - (unchecked exception) Thrown if mimeType does not obey the syntax for a MIME media type string.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocFlavor.INPUT_STREAM

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Class DocFlavor.INPUT_STREAM

java.lang.Object
    extended by  javax.print.DocFlavor
        extended by  javax.print.DocFlavor.INPUT_STREAM
All Implemented Interfaces:
Serializable, Cloneable
Enclosing class:
DocFlavor
public static class DocFlavor.INPUT_STREAM
extends DocFlavor

Class DocFlavor.INPUT_STREAM provides predefined static constant DocFlavor objects for example doc flavors using a byte stream (java.io.InputStream) as the print data representation class.

See Also:
Serialized Form

Nested Class Summary
Nested classes/interfaces inherited from class javax.print.DocFlavor
DocFlavor.BYTE_ARRAY, DocFlavor.CHAR_ARRAY, DocFlavor.INPUT_STREAM, DocFlavor.READER, DocFlavor.SERVICE_FORMATTED, DocFlavor.STRING, DocFlavor.URL
Field Summary
static DocFlavor.INPUT_STREAM | AUTOSENSE Doc flavor with MIME type = "application/octet-stream", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | GIF Doc flavor with MIME type = "image/gif", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | JPEG Doc flavor with MIME type = "image/jpeg", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | PCL Doc flavor with MIME type = "application/vnd.hp-PCL", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | PDF Doc flavor with MIME type = "application/pdf", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | PNG Doc flavor with MIME type = "image/png", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | POSTSCRIPT Doc flavor with MIME type = "application/postscript", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | TEXT_HTML_HOST Doc flavor with MIME type = "text/html", encoded in the host platform encoding.
static DocFlavor.INPUT_STREAM | TEXT_HTML_US_ASCII Doc flavor with MIME type = "text/html; charset=us-ascii", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | TEXT_HTML_UTF_16 Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | TEXT_HTML_UTF_16BE Doc flavor with MIME type = "text/html; charset=utf-16be" (big-endian byte ordering), print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | TEXT_HTML_UTF_16LE Doc flavor with MIME type = "text/html; charset=utf-16le" (little-endian byte ordering), print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | TEXT_HTML_UTF_8 Doc flavor with MIME type = "text/html; charset=utf-8", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | TEXT_PLAIN_HOST Doc flavor with MIME type = "text/plain", encoded in the host platform encoding.
static DocFlavor.INPUT_STREAM | TEXT_PLAIN_US_ASCII Doc flavor with MIME type = "text/plain; charset=us-ascii", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | TEXT_PLAIN_UTF_16 Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | TEXT_PLAIN_UTF_16BE Doc flavor with MIME type = "text/plain; charset=utf-16be" (big-endian byte ordering), print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | TEXT_PLAIN_UTF_16LE Doc flavor with MIME type = "text/plain; charset=utf-16le" (little-endian byte ordering), print data representation class name = "java.io.InputStream" (byte stream).
static DocFlavor.INPUT_STREAM | TEXT_PLAIN_UTF_8 Doc flavor with MIME type = "text/plain; charset=utf-8", print data representation class name = "java.io.InputStream" (byte stream).
Fields inherited from class javax.print.DocFlavor
hostEncoding
Constructor Summary
DocFlavor.INPUT_STREAM(String mimeType)
Constructs a new doc flavor with the given MIME type and a print data representation class name of "java.io.InputStream" (byte stream).
Method Summary
Methods inherited from class javax.print.DocFlavor
equals, getMediaSubtype, getMediaType, getMimeType, getParameter, getRepresentationClassName, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

TEXT_PLAIN_HOST

public static final DocFlavor.INPUT_STREAM TEXT_PLAIN_HOST
Doc flavor with MIME type = "text/plain", encoded in the host platform encoding. See hostEncoding Print data representation class name = "java.io.InputStream" (byte stream).

TEXT_PLAIN_UTF_8

public static final DocFlavor.INPUT_STREAM TEXT_PLAIN_UTF_8
Doc flavor with MIME type = "text/plain; charset=utf-8", print data representation class name = "java.io.InputStream" (byte stream).

TEXT_PLAIN_UTF_16

public static final DocFlavor.INPUT_STREAM TEXT_PLAIN_UTF_16
Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = "java.io.InputStream" (byte stream).

TEXT_PLAIN_UTF_16BE

public static final DocFlavor.INPUT_STREAM TEXT_PLAIN_UTF_16BE
Doc flavor with MIME type = "text/plain; charset=utf-16be" (big-endian byte ordering), print data representation class name = "java.io.InputStream" (byte stream).

TEXT_PLAIN_UTF_16LE

public static final DocFlavor.INPUT_STREAM TEXT_PLAIN_UTF_16LE
Doc flavor with MIME type = "text/plain; charset=utf-16le" (little-endian byte ordering), print data representation class name = "java.io.InputStream" (byte stream).

TEXT_PLAIN_US_ASCII

public static final DocFlavor.INPUT_STREAM TEXT_PLAIN_US_ASCII
Doc flavor with MIME type = "text/plain; charset=us-ascii", print data representation class name = "java.io.InputStream" (byte stream).

TEXT_HTML_HOST

public static final DocFlavor.INPUT_STREAM TEXT_HTML_HOST
Doc flavor with MIME type = "text/html", encoded in the host platform encoding. See hostEncoding Print data representation class name = "java.io.InputStream" (byte stream).

TEXT_HTML_UTF_8

public static final DocFlavor.INPUT_STREAM TEXT_HTML_UTF_8
Doc flavor with MIME type = "text/html; charset=utf-8", print data representation class name = "java.io.InputStream" (byte stream).

TEXT_HTML_UTF_16

public static final DocFlavor.INPUT_STREAM TEXT_HTML_UTF_16
Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "java.io.InputStream" (byte stream).

TEXT_HTML_UTF_16BE

public static final DocFlavor.INPUT_STREAM TEXT_HTML_UTF_16BE
Doc flavor with MIME type = "text/html; charset=utf-16be" (big-endian byte ordering), print data representation class name = "java.io.InputStream" (byte stream).

TEXT_HTML_UTF_16LE

public static final DocFlavor.INPUT_STREAM TEXT_HTML_UTF_16LE
Doc flavor with MIME type = "text/html; charset=utf-16le" (little-endian byte ordering), print data representation class name = "java.io.InputStream" (byte stream).

TEXT_HTML_US_ASCII

public static final DocFlavor.INPUT_STREAM TEXT_HTML_US_ASCII
Doc flavor with MIME type = "text/html; charset=us-ascii", print data representation class name = "java.io.InputStream" (byte stream).

PDF

public static final DocFlavor.INPUT_STREAM PDF
Doc flavor with MIME type = "application/pdf", print data representation class name = "java.io.InputStream" (byte stream).

POSTSCRIPT

public static final DocFlavor.INPUT_STREAM POSTSCRIPT
Doc flavor with MIME type = "application/postscript", print data representation class name = "java.io.InputStream" (byte stream).

PCL

public static final DocFlavor.INPUT_STREAM PCL
Doc flavor with MIME type = "application/vnd.hp-PCL", print data representation class name = "java.io.InputStream" (byte stream).

GIF

public static final DocFlavor.INPUT_STREAM GIF
Doc flavor with MIME type = "image/gif", print data representation class name = "java.io.InputStream" (byte stream).

JPEG

public static final DocFlavor.INPUT_STREAM JPEG
Doc flavor with MIME type = "image/jpeg", print data representation class name = "java.io.InputStream" (byte stream).

PNG

public static final DocFlavor.INPUT_STREAM PNG
Doc flavor with MIME type = "image/png", print data representation class name = "java.io.InputStream" (byte stream).

AUTOSENSE

public static final DocFlavor.INPUT_STREAM AUTOSENSE
Doc flavor with MIME type = "application/octet-stream", print data representation class name = "java.io.InputStream" (byte stream). The client must determine that data described using this DocFlavor is valid for the printer.

Constructor Detail

DocFlavor.INPUT_STREAM

public DocFlavor.INPUT_STREAM(String mimeType)
Constructs a new doc flavor with the given MIME type and a print data representation class name of "java.io.InputStream" (byte stream).

Parameters:
mimeType - MIME media type string.
Throws:
NullPointerException - (unchecked exception) Thrown if mimeType is null.
IllegalArgumentException - (unchecked exception) Thrown if mimeType does not obey the syntax for a MIME media type string.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocFlavor.READER

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Class DocFlavor.READER

java.lang.Object
    extended by  javax.print.DocFlavor
        extended by  javax.print.DocFlavor.READER
All Implemented Interfaces:
Serializable, Cloneable
Enclosing class:
DocFlavor
public static class DocFlavor.READER
extends DocFlavor

Class DocFlavor.READER provides predefined static constant DocFlavor objects for example doc flavors using a character stream (java.io.Reader) as the print data representation class. As such, the character set is Unicode.

See Also:
Serialized Form

Nested Class Summary
Nested classes/interfaces inherited from class javax.print.DocFlavor
DocFlavor.BYTE_ARRAY, DocFlavor.CHAR_ARRAY, DocFlavor.INPUT_STREAM, DocFlavor.READER, DocFlavor.SERVICE_FORMATTED, DocFlavor.STRING, DocFlavor.URL
Field Summary
static DocFlavor.READER | TEXT_HTML Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "java.io.Reader" (character stream).
static DocFlavor.READER | TEXT_PLAIN Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = "java.io.Reader" (character stream).
Fields inherited from class javax.print.DocFlavor
hostEncoding
Constructor Summary
DocFlavor.READER(String mimeType)
Constructs a new doc flavor with the given MIME type and a print data representation class name of\ "java.io.Reader" (character stream).
Method Summary
Methods inherited from class javax.print.DocFlavor
equals, getMediaSubtype, getMediaType, getMimeType, getParameter, getRepresentationClassName, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

TEXT_PLAIN

public static final DocFlavor.READER TEXT_PLAIN
Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = "java.io.Reader" (character stream).

TEXT_HTML

public static final DocFlavor.READER TEXT_HTML
Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "java.io.Reader" (character stream).

Constructor Detail

DocFlavor.READER

public DocFlavor.READER(String mimeType)
Constructs a new doc flavor with the given MIME type and a print data representation class name of\ "java.io.Reader" (character stream).

Parameters:
mimeType - MIME media type string. If it is a text media type, it is assumed to contain a "charset=utf-16" parameter.
Throws:
NullPointerException - (unchecked exception) Thrown if mimeType is null.
IllegalArgumentException - (unchecked exception) Thrown if mimeType does not obey the syntax for a MIME media type string.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocFlavor.SERVICE_FORMATTED

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Class DocFlavor.SERVICE_FORMATTED

java.lang.Object
    extended by  javax.print.DocFlavor
        extended by  javax.print.DocFlavor.SERVICE_FORMATTED
All Implemented Interfaces:
Serializable, Cloneable
Enclosing class:
DocFlavor
public static class DocFlavor.SERVICE_FORMATTED
extends DocFlavor

Class DocFlavor.SERVICE_FORMATTED provides predefined static constant DocFlavor objects for example doc flavors for service formatted print data.

See Also:
Serialized Form

Nested Class Summary
Nested classes/interfaces inherited from class javax.print.DocFlavor
DocFlavor.BYTE_ARRAY, DocFlavor.CHAR_ARRAY, DocFlavor.INPUT_STREAM, DocFlavor.READER, DocFlavor.SERVICE_FORMATTED, DocFlavor.STRING, DocFlavor.URL
Field Summary
static DocFlavor.SERVICE_FORMATTED | PAGEABLE Service formatted print data doc flavor with print data representation class name = "java.awt.print.Pageable" (pageable object).
static DocFlavor.SERVICE_FORMATTED | PRINTABLE Service formatted print data doc flavor with print data representation class name = "java.awt.print.Printable" (printable object).
static DocFlavor.SERVICE_FORMATTED | RENDERABLE_IMAGE Service formatted print data doc flavor with print data representation class name = "java.awt.image.renderable.RenderableImage" (renderable image object).
Fields inherited from class javax.print.DocFlavor
hostEncoding
Constructor Summary
DocFlavor.SERVICE_FORMATTED(String className)
Constructs a new doc flavor with a MIME type of "application/x-java-jvm-local-objectref" indicating service formatted print data and the given print data representation class name.
Method Summary
Methods inherited from class javax.print.DocFlavor
equals, getMediaSubtype, getMediaType, getMimeType, getParameter, getRepresentationClassName, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

RENDERABLE_IMAGE

public static final DocFlavor.SERVICE_FORMATTED RENDERABLE_IMAGE
Service formatted print data doc flavor with print data representation class name = "java.awt.image.renderable.RenderableImage" (renderable image object).

PRINTABLE

public static final DocFlavor.SERVICE_FORMATTED PRINTABLE
Service formatted print data doc flavor with print data representation class name = "java.awt.print.Printable" (printable object).

PAGEABLE

public static final DocFlavor.SERVICE_FORMATTED PAGEABLE
Service formatted print data doc flavor with print data representation class name = "java.awt.print.Pageable" (pageable object).

Constructor Detail

DocFlavor.SERVICE_FORMATTED

public DocFlavor.SERVICE_FORMATTED(String className)
Constructs a new doc flavor with a MIME type of "application/x-java-jvm-local-objectref" indicating service formatted print data and the given print data representation class name.

Parameters:
className - Fully-qualified representation class name.
Throws:
NullPointerException - (unchecked exception) Thrown if className is null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocFlavor.STRING

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Class DocFlavor.STRING

java.lang.Object
    extended by  javax.print.DocFlavor
        extended by  javax.print.DocFlavor.STRING
All Implemented Interfaces:
Serializable, Cloneable
Enclosing class:
DocFlavor
public static class DocFlavor.STRING
extends DocFlavor

Class DocFlavor.STRING provides predefined static constant DocFlavor objects for example doc flavors using a string (java.lang.String) as the print data representation class. As such, the character set is Unicode.

See Also:
Serialized Form

Nested Class Summary
Nested classes/interfaces inherited from class javax.print.DocFlavor
DocFlavor.BYTE_ARRAY, DocFlavor.CHAR_ARRAY, DocFlavor.INPUT_STREAM, DocFlavor.READER, DocFlavor.SERVICE_FORMATTED, DocFlavor.STRING, DocFlavor.URL
Field Summary
static DocFlavor.STRING | TEXT_HTML Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "java.lang.String".
static DocFlavor.STRING | TEXT_PLAIN Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = "java.lang.String".
Fields inherited from class javax.print.DocFlavor
hostEncoding
Constructor Summary
DocFlavor.STRING(String mimeType)
Constructs a new doc flavor with the given MIME type and a print data representation class name of "java.lang.String".
Method Summary
Methods inherited from class javax.print.DocFlavor
equals, getMediaSubtype, getMediaType, getMimeType, getParameter, getRepresentationClassName, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

TEXT_PLAIN

public static final DocFlavor.STRING TEXT_PLAIN
Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = "java.lang.String".

TEXT_HTML

public static final DocFlavor.STRING TEXT_HTML
Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "java.lang.String".

Constructor Detail

DocFlavor.STRING

public DocFlavor.STRING(String mimeType)
Constructs a new doc flavor with the given MIME type and a print data representation class name of "java.lang.String".

Parameters:
mimeType - MIME media type string. If it is a text media type, it is assumed to contain a "charset=utf-16" parameter.
Throws:
NullPointerException - (unchecked exception) Thrown if mimeType is null.
IllegalArgumentException - (unchecked exception) Thrown if mimeType does not obey the syntax for a MIME media type string.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocFlavor.URL

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Class DocFlavor.URL

java.lang.Object
    extended by  javax.print.DocFlavor
        extended by  javax.print.DocFlavor.URL
All Implemented Interfaces:
Serializable, Cloneable
Enclosing class:
DocFlavor
public static class DocFlavor.URL
extends DocFlavor

Class DocFlavor.URL provides predefined static constant DocFlavor objects. For example doc flavors using a Uniform Resource Locator (java.net.URL) as the print data representation class.

See Also:
Serialized Form

Nested Class Summary
Nested classes/interfaces inherited from class javax.print.DocFlavor
DocFlavor.BYTE_ARRAY, DocFlavor.CHAR_ARRAY, DocFlavor.INPUT_STREAM, DocFlavor.READER, DocFlavor.SERVICE_FORMATTED, DocFlavor.STRING, DocFlavor.URL
Field Summary
static DocFlavor.URL | AUTOSENSE Doc flavor with MIME type = "application/octet-stream", print data representation class name = "java.net.URL".
static DocFlavor.URL | GIF Doc flavor with MIME type = "image/gif", print data representation class name = "java.net.URL".
static DocFlavor.URL | JPEG Doc flavor with MIME type = "image/jpeg", print data representation class name = "java.net.URL".
static DocFlavor.URL | PCL Doc flavor with MIME type = "application/vnd.hp-PCL", print data representation class name = "java.net.URL".
static DocFlavor.URL | PDF Doc flavor with MIME type = "application/pdf", print data representation class name = "java.net.URL".
static DocFlavor.URL | PNG Doc flavor with MIME type = "image/png", print data representation class name = "java.net.URL".
static DocFlavor.URL | POSTSCRIPT Doc flavor with MIME type = "application/postscript", print data representation class name = "java.net.URL".
static DocFlavor.URL | TEXT_HTML_HOST Doc flavor with MIME type = "text/html", encoded in the host platform encoding.
static DocFlavor.URL | TEXT_HTML_US_ASCII Doc flavor with MIME type = "text/html; charset=us-ascii", print data representation class name = "java.net.URL" (byte stream).
static DocFlavor.URL | TEXT_HTML_UTF_16 Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "java.net.URL" (byte stream).
static DocFlavor.URL | TEXT_HTML_UTF_16BE Doc flavor with MIME type = "text/html; charset=utf-16be" (big-endian byte ordering), print data representation class name = "java.net.URL" (byte stream).
static DocFlavor.URL | TEXT_HTML_UTF_16LE Doc flavor with MIME type = "text/html; charset=utf-16le" (little-endian byte ordering), print data representation class name = "java.net.URL" (byte stream).
static DocFlavor.URL | TEXT_HTML_UTF_8 Doc flavor with MIME type = "text/html; charset=utf-8", print data representation class name = "java.net.URL" (byte stream).
static DocFlavor.URL | TEXT_PLAIN_HOST Doc flavor with MIME type = "text/plain", encoded in the host platform encoding.
static DocFlavor.URL | TEXT_PLAIN_US_ASCII Doc flavor with MIME type = "text/plain; charset=us-ascii", print data representation class name = "java.net.URL" (byte stream).
static DocFlavor.URL | TEXT_PLAIN_UTF_16 Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = java.net.URL"" (byte stream).
static DocFlavor.URL | TEXT_PLAIN_UTF_16BE Doc flavor with MIME type = "text/plain; charset=utf-16be" (big-endian byte ordering), print data representation class name = "java.net.URL" (byte stream).
static DocFlavor.URL | TEXT_PLAIN_UTF_16LE Doc flavor with MIME type = "text/plain; charset=utf-16le" (little-endian byte ordering), print data representation class name = "java.net.URL" (byte stream).
static DocFlavor.URL | TEXT_PLAIN_UTF_8 Doc flavor with MIME type = "text/plain; charset=utf-8", print data representation class name = "java.net.URL" (byte stream).
Fields inherited from class javax.print.DocFlavor
hostEncoding
Constructor Summary
DocFlavor.URL(String mimeType)
Constructs a new doc flavor with the given MIME type and a print data representation class name of "java.net.URL".
Method Summary
Methods inherited from class javax.print.DocFlavor
equals, getMediaSubtype, getMediaType, getMimeType, getParameter, getRepresentationClassName, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

TEXT_PLAIN_HOST

public static final DocFlavor.URL TEXT_PLAIN_HOST
Doc flavor with MIME type = "text/plain", encoded in the host platform encoding. See hostEncoding Print data representation class name = "java.net.URL" (byte stream).

TEXT_PLAIN_UTF_8

public static final DocFlavor.URL TEXT_PLAIN_UTF_8
Doc flavor with MIME type = "text/plain; charset=utf-8", print data representation class name = "java.net.URL" (byte stream).

TEXT_PLAIN_UTF_16

public static final DocFlavor.URL TEXT_PLAIN_UTF_16
Doc flavor with MIME type = "text/plain; charset=utf-16", print data representation class name = java.net.URL"" (byte stream).

TEXT_PLAIN_UTF_16BE

public static final DocFlavor.URL TEXT_PLAIN_UTF_16BE
Doc flavor with MIME type = "text/plain; charset=utf-16be" (big-endian byte ordering), print data representation class name = "java.net.URL" (byte stream).

TEXT_PLAIN_UTF_16LE

public static final DocFlavor.URL TEXT_PLAIN_UTF_16LE
Doc flavor with MIME type = "text/plain; charset=utf-16le" (little-endian byte ordering), print data representation class name = "java.net.URL" (byte stream).

TEXT_PLAIN_US_ASCII

public static final DocFlavor.URL TEXT_PLAIN_US_ASCII
Doc flavor with MIME type = "text/plain; charset=us-ascii", print data representation class name = "java.net.URL" (byte stream).

TEXT_HTML_HOST

public static final DocFlavor.URL TEXT_HTML_HOST
Doc flavor with MIME type = "text/html", encoded in the host platform encoding. See hostEncoding Print data representation class name = "java.net.URL" (byte stream).

TEXT_HTML_UTF_8

public static final DocFlavor.URL TEXT_HTML_UTF_8
Doc flavor with MIME type = "text/html; charset=utf-8", print data representation class name = "java.net.URL" (byte stream).

TEXT_HTML_UTF_16

public static final DocFlavor.URL TEXT_HTML_UTF_16
Doc flavor with MIME type = "text/html; charset=utf-16", print data representation class name = "java.net.URL" (byte stream).

TEXT_HTML_UTF_16BE

public static final DocFlavor.URL TEXT_HTML_UTF_16BE
Doc flavor with MIME type = "text/html; charset=utf-16be" (big-endian byte ordering), print data representation class name = "java.net.URL" (byte stream).

TEXT_HTML_UTF_16LE

public static final DocFlavor.URL TEXT_HTML_UTF_16LE
Doc flavor with MIME type = "text/html; charset=utf-16le" (little-endian byte ordering), print data representation class name = "java.net.URL" (byte stream).

TEXT_HTML_US_ASCII

public static final DocFlavor.URL TEXT_HTML_US_ASCII
Doc flavor with MIME type = "text/html; charset=us-ascii", print data representation class name = "java.net.URL" (byte stream).

PDF

public static final DocFlavor.URL PDF
Doc flavor with MIME type = "application/pdf", print data representation class name = "java.net.URL".

POSTSCRIPT

public static final DocFlavor.URL POSTSCRIPT
Doc flavor with MIME type = "application/postscript", print data representation class name = "java.net.URL".

PCL

public static final DocFlavor.URL PCL
Doc flavor with MIME type = "application/vnd.hp-PCL", print data representation class name = "java.net.URL".

GIF

public static final DocFlavor.URL GIF
Doc flavor with MIME type = "image/gif", print data representation class name = "java.net.URL".

JPEG

public static final DocFlavor.URL JPEG
Doc flavor with MIME type = "image/jpeg", print data representation class name = "java.net.URL".

PNG

public static final DocFlavor.URL PNG
Doc flavor with MIME type = "image/png", print data representation class name = "java.net.URL".

AUTOSENSE

public static final DocFlavor.URL AUTOSENSE
Doc flavor with MIME type = "application/octet-stream", print data representation class name = "java.net.URL". The client must determine that data described using this DocFlavor is valid for the printer.

Constructor Detail

DocFlavor.URL

public DocFlavor.URL(String mimeType)
Constructs a new doc flavor with the given MIME type and a print data representation class name of "java.net.URL".

Parameters:
mimeType - MIME media type string.
Throws:
NullPointerException - (unchecked exception) Thrown if mimeType is null.
IllegalArgumentException - (unchecked exception) Thrown if mimeType does not obey the syntax for a MIME media type string.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocPrintJob

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Interface DocPrintJob

All Known Subinterfaces:
CancelablePrintJob, MultiDocPrintJob
public interface DocPrintJob

This interface represents a print job that can print a specified document with a set of job attributes. An object implementing this interface is obtained from a print service.

Method Summary
void | addPrintJobAttributeListener(PrintJobAttributeListener listener, PrintJobAttributeSet attributes) Registers a listener for changes in the specified attributes.
void | addPrintJobListener(PrintJobListener listener) Registers a listener for event occurring during this print job.
PrintJobAttributeSet | getAttributes() Obtains this Print Job's set of printing attributes.
PrintService | getPrintService() Determines the PrintService object to which this print job object is bound.
void | print(Doc doc, PrintRequestAttributeSet attributes) Prints a document with the specified job attributes.
void | removePrintJobAttributeListener(PrintJobAttributeListener listener) Removes an attribute listener from this print job.
void | removePrintJobListener(PrintJobListener listener) Removes a listener from this print job.

Method Detail

getPrintService

PrintService getPrintService()
Determines the PrintService object to which this print job object is bound.

Returns:
PrintService object.

getAttributes

PrintJobAttributeSet getAttributes()
Obtains this Print Job's set of printing attributes. The returned attribute set object is unmodifiable. The returned attribute set object is a "snapshot" of this Print Job's attribute set at the time of the getAttributes() method call; that is, the returned attribute set's object's contents will not be updated if this Print Job's attribute set's contents change in the future. To detect changes in attribute values, call getAttributes() again and compare the new attribute set to the previous attribute set; alternatively, register a listener for print job events. The returned value may be an empty set but should not be null.

Returns:
the print job attributes

addPrintJobListener

void addPrintJobListener(PrintJobListener listener)
Registers a listener for event occurring during this print job. If listener is null, no exception is thrown and no action is performed. If listener is already registered, it will be registered again.

Parameters:
listener - The object implementing the listener interface
See Also:
removePrintJobListener(javax.print.event.PrintJobListener)

removePrintJobListener

void removePrintJobListener(PrintJobListener listener)
Removes a listener from this print job. This method performs no function, nor does it throw an exception, if the listener specified by the argument was not previously added to this component. If listener is null, no exception is thrown and no action is performed. If a listener was registered more than once only one of the registrations will be removed.

Parameters:
listener - The object implementing the listener interface
See Also:
addPrintJobListener(javax.print.event.PrintJobListener)

addPrintJobAttributeListener

void addPrintJobAttributeListener(PrintJobAttributeListener listener,
                                  PrintJobAttributeSet attributes)
Registers a listener for changes in the specified attributes. If listener is null, no exception is thrown and no action is performed. To determine the attribute updates that may be reported by this job, a client can call getAttributes() and identify the subset that are interesting and likely to be reported to the listener. Clients expecting to be updated about changes in a specific job attribute should verify it is in that set, but updates about an attribute will be made only if it changes and this is detected by the job. Also updates may be subject to batching by the job. To minimise overhead in print job processing it is recommended to listen on only that subset of attributes which are likely to change. If the specified set is empty no attribute updates will be reported to the listener. If the attribute set is null, then this means to listen on all dynamic attributes that the job supports. This may result in no update notifications if a job can not report any attribute updates. If listener is already registered, it will be registered again.

Parameters:
listener - The object implementing the listener interface
attributes - The attributes to listen on, or null to mean all attributes that can change, as determined by the job.
See Also:
removePrintJobAttributeListener(javax.print.event.PrintJobAttributeListener)

removePrintJobAttributeListener

void removePrintJobAttributeListener(PrintJobAttributeListener listener)
Removes an attribute listener from this print job. This method performs no function, nor does it throw an exception, if the listener specified by the argument was not previously added to this component. If the listener is null, no exception is thrown and no action is performed. If a listener is registered more than once, even for a different set of attributes, no guarantee is made which listener is removed.

Parameters:
listener - The object implementing the listener interface
See Also:
addPrintJobAttributeListener(javax.print.event.PrintJobAttributeListener, javax.print.attribute.PrintJobAttributeSet)

print

void print(Doc doc,
           PrintRequestAttributeSet attributes)
           throws PrintException
Prints a document with the specified job attributes. This method should only be called once for a given print job. Calling it again will not result in a new job being spooled to the printer. The service implementation will define policy for service interruption and recovery. When the print method returns, printing may not yet have completed as printing may happen asynchronously, perhaps in a different thread. Application clients which want to monitor the success or failure should register a PrintJobListener.

Print service implementors should close any print data streams (ie Reader or InputStream implementations) that they obtain from the client doc. Robust clients may still wish to verify this. An exception is always generated if a DocFlavor cannot be printed.

Parameters:
doc - The document to be printed. If must be a flavor supported by this PrintJob.
attributes - The job attributes to be applied to this print job. If this parameter is null then the default attributes are used.
Throws:
PrintException - The exception additionally may implement an interface that more precisely describes the cause of the exception
  • FlavorException. If the document has a flavor not supported by this print job.
  • AttributeException. If one or more of the attributes are not valid for this print job.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


event

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.print.event

Package javax.print.event contains event classes and listener interfaces.

See:
Description

Interface Summary
PrintJobAttributeListener | Implementations of this interface are attached to a DocPrintJob to monitor the status of attribute changes associated with the print job.
PrintJobListener | Implementations of this listener interface should be attached to a DocPrintJob to monitor the status of the printer job.
PrintServiceAttributeListener | Implementations of this listener interface are attached to a PrintService to monitor the status of the print service.

Class Summary
PrintEvent | Class PrintEvent is the super class of all Print Service API events.
PrintJobAdapter | An abstract adapter class for receiving print job events.
PrintJobAttributeEvent | Class PrintJobAttributeEvent encapsulates an event a PrintService reports to let the client know that one or more printing attributes for a PrintJob have changed.
PrintJobEvent | Class PrintJobEvent encapsulates common events a print job reports to let a listener know of progress in the processing of the DocPrintJob.
PrintServiceAttributeEvent | Class PrintServiceAttributeEvent encapsulates an event a Print Service instance reports to let the client know of changes in the print service state.

Package javax.print.event Description

Package javax.print.event contains event classes and listener interfaces.

They may be used to monitor both print services (such as printers going on-line & off-line), and the progress of a specific print job.

Please note: In the javax.print APIs, a null reference parameter to methods is incorrect unless explicitly documented on the method as having a meaningful interpretation. Usage to the contrary is incorrect coding and may result in a run time exception either immediately or at some later time. IllegalArgumentException and NullPointerException are examples of typical and acceptable run time exceptions for such cases.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.print.event Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.print.event

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.util.EventObject (implements java.io.Serializable)
      • javax.print.event.PrintEvent
        • javax.print.event.PrintJobAttributeEvent
        • javax.print.event.PrintJobEvent
        • javax.print.event.PrintServiceAttributeEvent
    • javax.print.event.PrintJobAdapter (implements javax.print.event.PrintJobListener)

Interface Hierarchy

  • javax.print.event.PrintJobAttributeListener
  • javax.print.event.PrintJobListener
  • javax.print.event.PrintServiceAttributeListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.print.event

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.print.event

Packages that use javax.print.event
javax.print | Provides the principal classes and interfaces for the JavaTM Print Service API.
javax.print.event | Package javax.print.event contains event classes and listener interfaces.

Classes in javax.print.event used by javax.print
PrintJobAttributeListener
Implementations of this interface are attached to a DocPrintJob to monitor the status of attribute changes associated with the print job.
PrintJobListener
Implementations of this listener interface should be attached to a DocPrintJob to monitor the status of the printer job.
PrintServiceAttributeListener
Implementations of this listener interface are attached to a PrintService to monitor the status of the print service.

Classes in javax.print.event used by javax.print.event
PrintEvent
Class PrintEvent is the super class of all Print Service API events.
PrintJobAttributeEvent
Class PrintJobAttributeEvent encapsulates an event a PrintService reports to let the client know that one or more printing attributes for a PrintJob have changed.
PrintJobEvent
Class PrintJobEvent encapsulates common events a print job reports to let a listener know of progress in the processing of the DocPrintJob.
PrintJobListener
Implementations of this listener interface should be attached to a DocPrintJob to monitor the status of the printer job.
PrintServiceAttributeEvent
Class PrintServiceAttributeEvent encapsulates an event a Print Service instance reports to let the client know of changes in the print service state.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.event.PrintEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.event.PrintEvent

Packages that use PrintEvent
javax.print.event Package javax.print.event contains event classes and listener interfaces.

Uses of PrintEvent in javax.print.event

Subclasses of PrintEvent in javax.print.event
class | PrintJobAttributeEvent Class PrintJobAttributeEvent encapsulates an event a PrintService reports to let the client know that one or more printing attributes for a PrintJob have changed.
class | PrintJobEvent Class PrintJobEvent encapsulates common events a print job reports to let a listener know of progress in the processing of the DocPrintJob.
class | PrintServiceAttributeEvent Class PrintServiceAttributeEvent encapsulates an event a Print Service instance reports to let the client know of changes in the print service state.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.event.PrintJobAdapter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.event.PrintJobAdapter

No usage of javax.print.event.PrintJobAdapter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.event.PrintJobAttributeEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.event.PrintJobAttributeEvent

Packages that use PrintJobAttributeEvent
javax.print.event Package javax.print.event contains event classes and listener interfaces.

Uses of PrintJobAttributeEvent in javax.print.event

Methods in javax.print.event with parameters of type PrintJobAttributeEvent
 void PrintJobAttributeListener.attributeUpdate(PrintJobAttributeEvent pjae)
Notifies the listener of a change in some print job attributes.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.event.PrintJobEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.event.PrintJobEvent

Packages that use PrintJobEvent
javax.print.event Package javax.print.event contains event classes and listener interfaces.

Uses of PrintJobEvent in javax.print.event

Methods in javax.print.event with parameters of type PrintJobEvent
void | PrintJobAdapter.printDataTransferCompleted(PrintJobEvent pje) Called to notify the client that data has been successfully transferred to the print service, and the client may free local resources allocated for that data.
void | PrintJobListener.printDataTransferCompleted(PrintJobEvent pje) Called to notify the client that data has been successfully transferred to the print service, and the client may free local resources allocated for that data.
void | PrintJobAdapter.printJobCanceled(PrintJobEvent pje) Called to notify the client that the job was canceled by user or program.
void | PrintJobListener.printJobCanceled(PrintJobEvent pje) Called to notify the client that the job was canceled by a user or a program.
void | PrintJobAdapter.printJobCompleted(PrintJobEvent pje) Called to notify the client that the job completed successfully.
void | PrintJobListener.printJobCompleted(PrintJobEvent pje) Called to notify the client that the job completed successfully.
void | PrintJobAdapter.printJobFailed(PrintJobEvent pje) Called to notify the client that the job failed to complete successfully and will have to be resubmitted.
void | PrintJobListener.printJobFailed(PrintJobEvent pje) Called to notify the client that the job failed to complete successfully and will have to be resubmitted.
void | PrintJobAdapter.printJobNoMoreEvents(PrintJobEvent pje) Called to notify the client that no more events will be delivered.
void | PrintJobListener.printJobNoMoreEvents(PrintJobEvent pje) Called to notify the client that no more events will be delivered.
void | PrintJobAdapter.printJobRequiresAttention(PrintJobEvent pje) Called to notify the client that some possibly user rectifiable problem occurs (eg printer out of paper).
void | PrintJobListener.printJobRequiresAttention(PrintJobEvent pje) Called to notify the client that an error has occurred that the user might be able to fix.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.print.event.PrintServiceAttributeEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.print.event.PrintServiceAttributeEvent

Packages that use PrintServiceAttributeEvent
javax.print.event Package javax.print.event contains event classes and listener interfaces.

Uses of PrintServiceAttributeEvent in javax.print.event

Methods in javax.print.event with parameters of type PrintServiceAttributeEvent
 void PrintServiceAttributeListener.attributeUpdate(PrintServiceAttributeEvent psae)
Called to notify a listener of an event in the print service.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.event.PrintJobAttributeListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.event.PrintJobAttributeListener

Packages that use PrintJobAttributeListener
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of PrintJobAttributeListener in javax.print

Methods in javax.print with parameters of type PrintJobAttributeListener
void | DocPrintJob.addPrintJobAttributeListener(PrintJobAttributeListener listener, PrintJobAttributeSet attributes) Registers a listener for changes in the specified attributes.
void | DocPrintJob.removePrintJobAttributeListener(PrintJobAttributeListener listener) Removes an attribute listener from this print job.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.event.PrintJobListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.event.PrintJobListener

Packages that use PrintJobListener
javax.print | Provides the principal classes and interfaces for the JavaTM Print Service API.
javax.print.event | Package javax.print.event contains event classes and listener interfaces.

Uses of PrintJobListener in javax.print

Methods in javax.print with parameters of type PrintJobListener
void | DocPrintJob.addPrintJobListener(PrintJobListener listener) Registers a listener for event occurring during this print job.
void | DocPrintJob.removePrintJobListener(PrintJobListener listener) Removes a listener from this print job.

Uses of PrintJobListener in javax.print.event

Classes in javax.print.event that implement PrintJobListener
 class PrintJobAdapter
An abstract adapter class for receiving print job events.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.print.event.PrintServiceAttributeListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.print.event.PrintServiceAttributeListener

Packages that use PrintServiceAttributeListener
javax.print Provides the principal classes and interfaces for the JavaTM Print Service API.

Uses of PrintServiceAttributeListener in javax.print

Methods in javax.print with parameters of type PrintServiceAttributeListener
void | PrintService.addPrintServiceAttributeListener(PrintServiceAttributeListener listener) Registers a listener for events on this PrintService.
void | PrintService.removePrintServiceAttributeListener(PrintServiceAttributeListener listener) Removes the print-service listener from this print service.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


PrintEvent

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.print.event
Class PrintEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.print.event.PrintEvent
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
PrintJobAttributeEvent, PrintJobEvent, PrintServiceAttributeEvent
public class PrintEvent
extends EventObject

Class PrintEvent is the super class of all Print Service API events.

See Also:
Serialized Form

Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
PrintEvent(Object source)
Constructs a PrintEvent object.
Method Summary
 String toString()
Returns a String representation of this EventObject.
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PrintEvent

public PrintEvent(Object source)
Constructs a PrintEvent object.

Parameters:
source - is the source of the event
Throws:
IllegalArgumentException - if source is null.
Method Detail

toString

public String toString()
Description copied from class: EventObject
Returns a String representation of this EventObject.

Overrides:
toString in class EventObject
Returns:
a message describing the event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


PrintJobAdapter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.event
Class PrintJobAdapter

java.lang.Object
    extended by  javax.print.event.PrintJobAdapter
All Implemented Interfaces:
PrintJobListener
public abstract class PrintJobAdapter
extends Object
implements PrintJobListener

An abstract adapter class for receiving print job events. The methods in this class are empty. This class exists as a convenience for creating listener objects. Extend this class to create a PrintJobEvent listener and override the methods for the events of interest. Unlike the ComponentListener interface, this abstract interface provides null methods so that you only need to define the methods you need, rather than all of the methods.

Constructor Summary
PrintJobAdapter()
Method Summary
void | printDataTransferCompleted(PrintJobEvent pje) Called to notify the client that data has been successfully transferred to the print service, and the client may free local resources allocated for that data.
void | printJobCanceled(PrintJobEvent pje) Called to notify the client that the job was canceled by user or program.
void | printJobCompleted(PrintJobEvent pje) Called to notify the client that the job completed successfully.
void | printJobFailed(PrintJobEvent pje) Called to notify the client that the job failed to complete successfully and will have to be resubmitted.
void | printJobNoMoreEvents(PrintJobEvent pje) Called to notify the client that no more events will be delivered.
void | printJobRequiresAttention(PrintJobEvent pje) Called to notify the client that some possibly user rectifiable problem occurs (eg printer out of paper).
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PrintJobAdapter

public PrintJobAdapter()
Method Detail

printDataTransferCompleted

public void printDataTransferCompleted(PrintJobEvent pje)
Called to notify the client that data has been successfully transferred to the print service, and the client may free local resources allocated for that data. The client should not assume that the data has been completely printed after receiving this event.

Specified by:
printDataTransferCompleted in interface PrintJobListener
Parameters:
pje - the event being notified

printJobCompleted

public void printJobCompleted(PrintJobEvent pje)
Called to notify the client that the job completed successfully.

Specified by:
printJobCompleted in interface PrintJobListener
Parameters:
pje - the event being notified

printJobFailed

public void printJobFailed(PrintJobEvent pje)
Called to notify the client that the job failed to complete successfully and will have to be resubmitted.

Specified by:
printJobFailed in interface PrintJobListener
Parameters:
pje - the event being notified

printJobCanceled

public void printJobCanceled(PrintJobEvent pje)
Called to notify the client that the job was canceled by user or program.

Specified by:
printJobCanceled in interface PrintJobListener
Parameters:
pje - the event being notified

printJobNoMoreEvents

public void printJobNoMoreEvents(PrintJobEvent pje)
Called to notify the client that no more events will be delivered. One cause of this event being generated is if the job has successfully completed, but the printing system is limited in capability and cannot verify this. This event is required to be delivered if none of the other terminal events (completed/failed/canceled) are delivered.

Specified by:
printJobNoMoreEvents in interface PrintJobListener
Parameters:
pje - the event being notified

printJobRequiresAttention

public void printJobRequiresAttention(PrintJobEvent pje)
Called to notify the client that some possibly user rectifiable problem occurs (eg printer out of paper).

Specified by:
printJobRequiresAttention in interface PrintJobListener
Parameters:
pje - the event being notified
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrintJobAttributeEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.event
Class PrintJobAttributeEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.print.event.PrintEvent
            extended by  javax.print.event.PrintJobAttributeEvent
All Implemented Interfaces:
Serializable
public class PrintJobAttributeEvent
extends PrintEvent

Class PrintJobAttributeEvent encapsulates an event a PrintService reports to let the client know that one or more printing attributes for a PrintJob have changed.

See Also:
Serialized Form

Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
PrintJobAttributeEvent(DocPrintJob source, PrintJobAttributeSet attributes)
Constructs a PrintJobAttributeEvent object.
Method Summary
PrintJobAttributeSet | getAttributes() Determine the printing attributes that changed and their new values.
DocPrintJob | getPrintJob() Determine the Print Job to which this print job event pertains.
Methods inherited from class javax.print.event.PrintEvent
toString
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PrintJobAttributeEvent

public PrintJobAttributeEvent(DocPrintJob source,
                              PrintJobAttributeSet attributes)
Constructs a PrintJobAttributeEvent object.

Parameters:
source - the print job generating this event
attributes - the attribute changes being reported
Throws:
IllegalArgumentException - if source is null.
Method Detail

getPrintJob

public DocPrintJob getPrintJob()
Determine the Print Job to which this print job event pertains.

Returns:
Print Job object.

getAttributes

public PrintJobAttributeSet getAttributes()
Determine the printing attributes that changed and their new values.

Returns:
Attributes containing the new values for the print job attributes that changed. The returned set may not be modifiable.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrintJobAttributeListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.event
Interface PrintJobAttributeListener

public interface PrintJobAttributeListener

Implementations of this interface are attached to a DocPrintJob to monitor the status of attribute changes associated with the print job.

Method Summary
 void attributeUpdate(PrintJobAttributeEvent pjae)
Notifies the listener of a change in some print job attributes.

Method Detail

attributeUpdate

void attributeUpdate(PrintJobAttributeEvent pjae)
Notifies the listener of a change in some print job attributes. One example of an occurrence triggering this event is if the JobState attribute changed from PROCESSING to PROCESSING_STOPPED.

Parameters:
pjae - the event.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrintJobEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.event
Class PrintJobEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.print.event.PrintEvent
            extended by  javax.print.event.PrintJobEvent
All Implemented Interfaces:
Serializable
public class PrintJobEvent
extends PrintEvent

Class PrintJobEvent encapsulates common events a print job reports to let a listener know of progress in the processing of the DocPrintJob.

See Also:
Serialized Form

Field Summary
static int | DATA_TRANSFER_COMPLETE The job is not necessarily printed yet, but the data has been transferred successfully from the client to the print service.
static int | JOB_CANCELED The job was canceled by the PrintService.
static int | JOB_COMPLETE The document cis completely printed.
static int | JOB_FAILED The print service reports that the job cannot be completed.
static int | NO_MORE_EVENTS Not all print services may be capable of delivering interesting events, or even telling when a job is complete.
static int | REQUIRES_ATTENTION The print service indicates that a - possibly transient - problem may require external intervention before the print service can continue.
Fields inherited from class java.util.EventObject
source
Constructor Summary
PrintJobEvent(DocPrintJob source, int reason)
Constructs a PrintJobEvent object.
Method Summary
int | getPrintEventType() Gets the reason for this event.
DocPrintJob | getPrintJob() Determines the DocPrintJob to which this print job event pertains.
Methods inherited from class javax.print.event.PrintEvent
toString
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

JOB_CANCELED

public static final int JOB_CANCELED
The job was canceled by the PrintService.

See Also:
Constant Field Values

JOB_COMPLETE

public static final int JOB_COMPLETE
The document cis completely printed.

See Also:
Constant Field Values

JOB_FAILED

public static final int JOB_FAILED
The print service reports that the job cannot be completed. The application must resubmit the job.

See Also:
Constant Field Values

REQUIRES_ATTENTION

public static final int REQUIRES_ATTENTION
The print service indicates that a - possibly transient - problem may require external intervention before the print service can continue. One example of an event that can generate this message is when the printer runs out of paper.

See Also:
Constant Field Values

NO_MORE_EVENTS

public static final int NO_MORE_EVENTS
Not all print services may be capable of delivering interesting events, or even telling when a job is complete. This message indicates the print job has no further information or communication with the print service. This message should always be delivered if a terminal event (completed/failed/canceled) is not delivered. For example, if messages such as JOB_COMPLETE have NOT been received before receiving this message, the only inference that should be drawn is that the print service does not support delivering such an event.

See Also:
Constant Field Values

DATA_TRANSFER_COMPLETE

public static final int DATA_TRANSFER_COMPLETE
The job is not necessarily printed yet, but the data has been transferred successfully from the client to the print service. The client may free data resources.

See Also:
Constant Field Values
Constructor Detail

PrintJobEvent

public PrintJobEvent(DocPrintJob source,
                     int reason)
Constructs a PrintJobEvent object.

Parameters:
source - a DocPrintJob object
reason - an int specifying the reason.
Throws:
IllegalArgumentException - if source is null.
Method Detail

getPrintEventType

public int getPrintEventType()
Gets the reason for this event.

Returns:
reason int.

getPrintJob

public DocPrintJob getPrintJob()
Determines the DocPrintJob to which this print job event pertains.

Returns:
the DocPrintJob object that represents the print job that reports the events encapsulated by this PrintJobEvent.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrintJobListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.event
Interface PrintJobListener

All Known Implementing Classes:
PrintJobAdapter
public interface PrintJobListener

Implementations of this listener interface should be attached to a DocPrintJob to monitor the status of the printer job. These callback methods may be invoked on the thread processing the print job, or a service created notification thread. In either case the client should not perform lengthy processing in these callbacks.

Method Summary
void | printDataTransferCompleted(PrintJobEvent pje) Called to notify the client that data has been successfully transferred to the print service, and the client may free local resources allocated for that data.
void | printJobCanceled(PrintJobEvent pje) Called to notify the client that the job was canceled by a user or a program.
void | printJobCompleted(PrintJobEvent pje) Called to notify the client that the job completed successfully.
void | printJobFailed(PrintJobEvent pje) Called to notify the client that the job failed to complete successfully and will have to be resubmitted.
void | printJobNoMoreEvents(PrintJobEvent pje) Called to notify the client that no more events will be delivered.
void | printJobRequiresAttention(PrintJobEvent pje) Called to notify the client that an error has occurred that the user might be able to fix.

Method Detail

printDataTransferCompleted

void printDataTransferCompleted(PrintJobEvent pje)
Called to notify the client that data has been successfully transferred to the print service, and the client may free local resources allocated for that data. The client should not assume that the data has been completely printed after receiving this event. If this event is not received the client should wait for a terminal event (completed/canceled/failed) before freeing the resources.

Parameters:
pje - the job generating this event

printJobCompleted

void printJobCompleted(PrintJobEvent pje)
Called to notify the client that the job completed successfully.

Parameters:
pje - the job generating this event

printJobFailed

void printJobFailed(PrintJobEvent pje)
Called to notify the client that the job failed to complete successfully and will have to be resubmitted.

Parameters:
pje - the job generating this event

printJobCanceled

void printJobCanceled(PrintJobEvent pje)
Called to notify the client that the job was canceled by a user or a program.

Parameters:
pje - the job generating this event

printJobNoMoreEvents

void printJobNoMoreEvents(PrintJobEvent pje)
Called to notify the client that no more events will be delivered. One cause of this event being generated is if the job has successfully completed, but the printing system is limited in capability and cannot verify this. This event is required to be delivered if none of the other terminal events (completed/failed/canceled) are delivered.

Parameters:
pje - the job generating this event

printJobRequiresAttention

void printJobRequiresAttention(PrintJobEvent pje)
Called to notify the client that an error has occurred that the user might be able to fix. One example of an error that can generate this event is when the printer runs out of paper.

Parameters:
pje - the job generating this event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrintServiceAttributeEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print.event
Class PrintServiceAttributeEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.print.event.PrintEvent
            extended by  javax.print.event.PrintServiceAttributeEvent
All Implemented Interfaces:
Serializable
public class PrintServiceAttributeEvent
extends PrintEvent

Class PrintServiceAttributeEvent encapsulates an event a Print Service instance reports to let the client know of changes in the print service state.

See Also:
Serialized Form

Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
PrintServiceAttributeEvent(PrintService source, PrintServiceAttributeSet attributes)
Constructs a PrintServiceAttributeEvent object.
Method Summary
PrintServiceAttributeSet | getAttributes() Determine the printing service attributes that changed and their new values.
PrintService | getPrintService() Returns the print service.
Methods inherited from class javax.print.event.PrintEvent
toString
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PrintServiceAttributeEvent

public PrintServiceAttributeEvent(PrintService source,
                                  PrintServiceAttributeSet attributes)
Constructs a PrintServiceAttributeEvent object.

Parameters:
source - the print job generating this event
attributes - the attribute changes being reported
Throws:
IllegalArgumentException - if source is null.
Method Detail

getPrintService

public PrintService getPrintService()
Returns the print service.

Returns:
Print Service object.

getAttributes

public PrintServiceAttributeSet getAttributes()
Determine the printing service attributes that changed and their new values.

Returns:
Attributes containing the new values for the service attributes that changed. The returned set may be unmodifiable.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrintServiceAttributeListener

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.print.event
Interface PrintServiceAttributeListener

public interface PrintServiceAttributeListener

Implementations of this listener interface are attached to a PrintService to monitor the status of the print service.

To monitor a particular job see PrintJobListener and PrintJobAttributeListener.

Method Summary
 void attributeUpdate(PrintServiceAttributeEvent psae)
Called to notify a listener of an event in the print service.

Method Detail

attributeUpdate

void attributeUpdate(PrintServiceAttributeEvent psae)
Called to notify a listener of an event in the print service. The service will call this method on an event notification thread. The client should not perform lengthy processing in this callback or subsequent event notifications may be blocked.

Parameters:
psae - the event being notified
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


FlavorException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Interface FlavorException

public interface FlavorException

Interface FlavorException is a mixin interface which a subclass of PrintException can implement to report an error condition involving a doc flavor or flavors (class DocFlavor). The Print Service API does not define any print exception classes that implement interface FlavorException, that being left to the Print Service implementor's discretion.

Method Summary
 DocFlavor[] getUnsupportedFlavors()
Returns the unsupported flavors.

Method Detail

getUnsupportedFlavors

DocFlavor[] getUnsupportedFlavors()
Returns the unsupported flavors.

Returns:
the unsupported doc flavors.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiDoc

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Interface MultiDoc

public interface MultiDoc

Interface MultiDoc specifies the interface for an object that supplies more than one piece of print data for a Print Job. "Doc" is a short, easy-to-pronounce term that means "a piece of print data," and a "multidoc" is a group of several docs. The client passes to the Print Job an object that implements interface MultiDoc, and the Print Job calls methods on that object to obtain the print data.

Interface MultiDoc provides an abstraction similar to a "linked list" of docs. A multidoc object is like a node in the linked list, containing the current doc in the list and a pointer to the next node (multidoc) in the list. The Print Job can call the multidoc's getDoc() method to get the current doc. When it's ready to go on to the next doc, the Print Job can call the multidoc's next() method to get the next multidoc, which contains the next doc. So Print Job code for accessing a multidoc might look like this:

      void processMultiDoc(MultiDoc theMultiDoc) {

          MultiDoc current = theMultiDoc;

          while (current != null) {
              processDoc (current.getDoc());
              current = current.next();
          }
      }

Of course, interface MultiDoc can be implemented in any way that fulfills the contract; it doesn't have to use a linked list in the implementation.

To get all the print data for a multidoc print job, a Print Service proxy could use either of two patterns:

  1. The interleaved pattern: Get the doc from the current multidoc. Get the print data representation object from the current doc. Get all the print data from the print data representation object. Get the next multidoc from the current multidoc, and repeat until there are no more. (The code example above uses the interleaved pattern.)

  2. The all-at-once pattern: Get the doc from the current multidoc, and save the doc in a list. Get the next multidoc from the current multidoc, and repeat until there are no more. Then iterate over the list of saved docs. Get the print data representation object from the current doc. Get all the print data from the print data representation object. Go to the next doc in the list, and repeat until there are no more.
Now, consider a printing client that is generating print data on the fly and does not have the resources to store more than one piece of print data at a time. If the print service proxy used the all-at-once pattern to get the print data, it would pose a problem for such a client; the client would have to keep all the docs' print data around until the print service proxy comes back and asks for them, which the client is not able to do. To work with such a client, the print service proxy must use the interleaved pattern.

To address this problem, and to simplify the design of clients providing multiple docs to a Print Job, every Print Service proxy that supports multidoc print jobs is required to access a MultiDoc object using the interleaved pattern. That is, given a MultiDoc object, the print service proxy will call getDoc() one or more times until it successfully obtains the current Doc object. The print service proxy will then obtain the current doc's print data, not proceeding until all the print data is obtained or an unrecoverable error occurs. If it is able to continue, the print service proxy will then call next() one or more times until it successfully obtains either the next MultiDoc object or an indication that there are no more. An implementation of interface MultiDoc can assume the print service proxy will follow this interleaved pattern; for any other pattern of usage, the MultiDoc implementation's behavior is unspecified.

There is no restriction on the number of client threads that may be simultaneously accessing the same multidoc. Therefore, all implementations of interface MultiDoc must be designed to be multiple thread safe. In fact, a client thread could be adding docs to the end of the (conceptual) list while a Print Job thread is simultaneously obtaining docs from the beginning of the list; provided the multidoc object synchronizes the threads properly, the two threads will not interfere with each other

Method Summary
Doc | getDoc() Obtain the current doc object.
MultiDoc | next() Go to the multidoc object that contains the next doc object in the sequence of doc objects.

Method Detail

getDoc

Doc getDoc()
           throws IOException
Obtain the current doc object.

Returns:
Current doc object.
Throws:
IOException - Thrown if a error ocurred reading the document.

next

MultiDoc next()
              throws IOException
Go to the multidoc object that contains the next doc object in the sequence of doc objects.

Returns:
Multidoc object containing the next doc object, or null if there are no further doc objects.
Throws:
IOException - Thrown if an error occurred locating the next document
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiDocPrintJob

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Interface MultiDocPrintJob

All Superinterfaces:
DocPrintJob
public interface MultiDocPrintJob
extends DocPrintJob

Obtained from a MultiDocPrintService, a MultiDocPrintJob can print a specified collection of documents as a single print job with a set of job attributes.

Method Summary
 void print(MultiDoc multiDoc, PrintRequestAttributeSet attributes)
Print a MultiDoc with the specified job attributes.
Methods inherited from interface javax.print.DocPrintJob
addPrintJobAttributeListener, addPrintJobListener, getAttributes, getPrintService, print, removePrintJobAttributeListener, removePrintJobListener

Method Detail

print

void print(MultiDoc multiDoc,
           PrintRequestAttributeSet attributes)
           throws PrintException
Print a MultiDoc with the specified job attributes. This method should only be called once for a given print job. Calling it again will not result in a new job being spooled to the printer. The service implementation will define policy for service interruption and recovery. Application clients which want to monitor the success or failure should register a PrintJobListener.

Parameters:
multiDoc - The documents to be printed. ALL must be a flavor supported by the PrintJob & PrintService.
attributes - The job attributes to be applied to this print job. If this parameter is null then the default attributes are used.
Throws:
PrintException - The exception additionally may implement an interfaces which more precisely describes the cause of the exception
  • FlavorException. If the document has a flavor not supported by this print job.
  • AttributeException. If one or more of the attributes are not valid for this print job.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiDocPrintService

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Interface MultiDocPrintService

All Superinterfaces:
PrintService
public interface MultiDocPrintService
extends PrintService

Interface MultiPrintService is the factory for a MultiDocPrintJob. A MultiPrintService describes the capabilities of a Printer and can be queried regarding a printer's supported attributes.

Method Summary
 MultiDocPrintJob createMultiDocPrintJob()
Create a job which can print a multiDoc.
Methods inherited from interface javax.print.PrintService
addPrintServiceAttributeListener, createPrintJob, equals, getAttribute, getAttributes, getDefaultAttributeValue, getName, getServiceUIFactory, getSupportedAttributeCategories, getSupportedAttributeValues, getSupportedDocFlavors, getUnsupportedAttributes, hashCode, isAttributeCategorySupported, isAttributeValueSupported, isDocFlavorSupported, removePrintServiceAttributeListener

Method Detail

createMultiDocPrintJob

MultiDocPrintJob createMultiDocPrintJob()
Create a job which can print a multiDoc.

Returns:
a MultiDocPrintJob
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrintException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Class PrintException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.print.PrintException
All Implemented Interfaces:
Serializable
public class PrintException
extends Exception

Class PrintException encapsulates a printing-related error condition that occurred while using a Print Service instance. This base class furnishes only a string description of the error. Subclasses furnish more detailed information if applicable.

See Also:
Serialized Form

Constructor Summary
PrintException()
Construct a print exception with no detail message.
PrintException(Exception e)
Construct a print exception chaining the supplied exception.
PrintException(String s)
Construct a print exception with the given detail message.
PrintException(String s, Exception e)
Construct a print exception with the given detail message and chained exception.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PrintException

public PrintException()
Construct a print exception with no detail message.

PrintException

public PrintException(String s)
Construct a print exception with the given detail message.

Parameters:
s - Detail message, or null if no detail message.

PrintException

public PrintException(Exception e)
Construct a print exception chaining the supplied exception.

Parameters:
e - Chained exception.

PrintException

public PrintException(String s,
                      Exception e)
Construct a print exception with the given detail message and chained exception.

Parameters:
s - Detail message, or null if no detail message.
e - Chained exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrintService

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Interface PrintService

All Known Subinterfaces:
MultiDocPrintService
All Known Implementing Classes:
StreamPrintService
public interface PrintService

Interface PrintService is the factory for a DocPrintJob. A PrintService describes the capabilities of a Printer and can be queried regarding a printer's supported attributes.

Example:

   DocFlavor flavor = DocFlavor.INPUT_STREAM.POSTSCRIPT;
   PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
   aset.add(MediaSizeName.ISO_A4);
   PrintService[] pservices =
                 PrintServiceLookup.lookupPrintServices(flavor, aset);
   if (pservices.length > 0) {
       DocPrintJob pj = pservices[0].createPrintJob();
       try {
           FileInputStream fis = new FileInputStream("test.ps");
           Doc doc = new SimpleDoc(fis, flavor, null);
           pj.print(doc, aset);
        } catch (FileNotFoundException fe) {
        } catch (PrintException e) {
        }
   }

Method Summary
 void addPrintServiceAttributeListener(PrintServiceAttributeListener listener)
Registers a listener for events on this PrintService.
 DocPrintJob createPrintJob()
Creates and returns a PrintJob capable of handling data from any of the supported document flavors.
 boolean equals(Object obj)
Determines if two services are referring to the same underlying service.
<T extends PrintServiceAttribute>
T
getAttribute(Class<T> category)
Gets the value of the single specified service attribute.
 PrintServiceAttributeSet getAttributes()
Obtains this print service's set of printer description attributes giving this Print Service's status.
 Object getDefaultAttributeValue(Class<? extends Attribute> category)
Determines this print service's default printing attribute value in the given category.
 String getName()
Returns a String name for this print service which may be used by applications to request a particular print service.
 ServiceUIFactory getServiceUIFactory()
Returns a factory for UI components which allow users to interact with the service in various roles.
 Class<?>[] getSupportedAttributeCategories()
Determines the printing attribute categories a client can specify when setting up a job for this print service.
 Object getSupportedAttributeValues(Class<? extends Attribute> category, DocFlavor flavor, AttributeSet attributes)
Determines the printing attribute values a client can specify in the given category when setting up a job for this print service.
 DocFlavor[] getSupportedDocFlavors()
Determines the print data formats a client can specify when setting up a job for this PrintService.
 AttributeSet getUnsupportedAttributes(DocFlavor flavor, AttributeSet attributes)
Identifies the attributes that are unsupported for a print request in the context of a particular DocFlavor.
 int hashCode()
This method should be implemented consistently with equals(Object).
 boolean isAttributeCategorySupported(Class<? extends Attribute> category)
Determines whether a client can specify the given printing attribute category when setting up a job for this print service.
 boolean isAttributeValueSupported(Attribute attrval, DocFlavor flavor, AttributeSet attributes)
Determines whether a client can specify the given printing attribute value when setting up a job for this Print Service.
 boolean isDocFlavorSupported(DocFlavor flavor)
Determines if this print service supports a specific DocFlavor.
 void removePrintServiceAttributeListener(PrintServiceAttributeListener listener)
Removes the print-service listener from this print service.

Method Detail

getName

String getName()
Returns a String name for this print service which may be used by applications to request a particular print service. In a suitable context, such as a name service, this name must be unique. In some environments this unique name may be the same as the user friendly printer name defined as the PrinterName attribute.

Returns:
name of the service.

createPrintJob

DocPrintJob createPrintJob()
Creates and returns a PrintJob capable of handling data from any of the supported document flavors.

Returns:
a DocPrintJob object

addPrintServiceAttributeListener

void addPrintServiceAttributeListener(PrintServiceAttributeListener listener)
Registers a listener for events on this PrintService.

Parameters:
listener - a PrintServiceAttributeListener, which monitors the status of a print service
See Also:
removePrintServiceAttributeListener(javax.print.event.PrintServiceAttributeListener)

removePrintServiceAttributeListener

void removePrintServiceAttributeListener(PrintServiceAttributeListener listener)
Removes the print-service listener from this print service. This means the listener is no longer interested in PrintService events.

Parameters:
listener - a PrintServiceAttributeListener object
See Also:
addPrintServiceAttributeListener(javax.print.event.PrintServiceAttributeListener)

getAttributes

PrintServiceAttributeSet getAttributes()
Obtains this print service's set of printer description attributes giving this Print Service's status. The returned attribute set object is unmodifiable. The returned attribute set object is a "snapshot" of this Print Service's attribute set at the time of the getAttributes() method call: that is, the returned attribute set's contents will not be updated if this print service's attribute set's contents change in the future. To detect changes in attribute values, call getAttributes() again and compare the new attribute set to the previous attribute set; alternatively, register a listener for print service events.

Returns:
Unmodifiable snapshot of this Print Service's attribute set. May be empty, but not null.

getAttribute

<T extends PrintServiceAttribute> T getAttribute(Class<T> category)
Gets the value of the single specified service attribute. This may be useful to clients which only need the value of one attribute and want to minimise overhead.

Parameters:
category - the category of a PrintServiceAttribute supported by this service - may not be null.
Returns:
the value of the supported attribute or null if the attribute is not supported by this service.
Throws:
NullPointerException - if the category is null.
IllegalArgumentException - (unchecked exception) if category is not a Class that implements interface PrintServiceAttribute.

getSupportedDocFlavors

DocFlavor[] getSupportedDocFlavors()
Determines the print data formats a client can specify when setting up a job for this PrintService. A print data format is designated by a "doc flavor" (class DocFlavor) consisting of a MIME type plus a print data representation class.

Note that some doc flavors may not be supported in combination with all attributes. Use getUnsupportedAttributes(..) to validate specific combinations.

Returns:
Array of supported doc flavors, should have at least one element.

isDocFlavorSupported

boolean isDocFlavorSupported(DocFlavor flavor)
Determines if this print service supports a specific DocFlavor. This is a convenience method to determine if the DocFlavor would be a member of the result of getSupportedDocFlavors().

Note that some doc flavors may not be supported in combination with all attributes. Use getUnsupportedAttributes(..) to validate specific combinations.

Parameters:
flavor - the DocFlavorto query for support.
Returns:
true if this print service supports the specified DocFlavor; false otherwise.
Throws:
NullPointerException - (unchecked exception) Thrown if flavor is null.

getSupportedAttributeCategories

Class<?>[] getSupportedAttributeCategories()
Determines the printing attribute categories a client can specify when setting up a job for this print service. A printing attribute category is designated by a Class that implements interface Attribute. This method returns just the attribute categories that are supported; it does not return the particular attribute values that are supported.

This method returns all the printing attribute categories this print service supports for any possible job. Some categories may not be supported in a particular context (ie for a particular DocFlavor). Use one of the methods that include a DocFlavor to validate the request before submitting it, such as getSupportedAttributeValues(..).

Returns:
Array of printing attribute categories that the client can specify as a doc-level or job-level attribute in a Print Request. Each element in the array is a Class that implements interface Attribute. The array is empty if no categories are supported.

isAttributeCategorySupported

boolean isAttributeCategorySupported(Class<? extends Attribute> category)
Determines whether a client can specify the given printing attribute category when setting up a job for this print service. A printing attribute category is designated by a Class that implements interface Attribute. This method tells whether the attribute category is supported; it does not tell whether a particular attribute value is supported.

Some categories may not be supported in a particular context (ie for a particular DocFlavor). Use one of the methods which include a DocFlavor to validate the request before submitting it, such as getSupportedAttributeValues(..).

This is a convenience method to determine if the category would be a member of the result of getSupportedAttributeCategories().

Parameters:
category - Printing attribute category to test. It must be a Class that implements interface Attribute.
Returns:
true if this print service supports specifying a doc-level or job-level attribute in category in a Print Request; false if it doesn't.
Throws:
NullPointerException - (unchecked exception) Thrown if category is null.
IllegalArgumentException - (unchecked exception) Thrown if category is not a Class that implements interface Attribute.

getDefaultAttributeValue

Object getDefaultAttributeValue(Class<? extends Attribute> category)
Determines this print service's default printing attribute value in the given category. A printing attribute value is an instance of a class that implements interface Attribute. If a client sets up a print job and does not specify any attribute value in the given category, this Print Service will use the default attribute value instead.

Some attributes may not be supported in a particular context (ie for a particular DocFlavor). Use one of the methods that include a DocFlavor to validate the request before submitting it, such as getSupportedAttributeValues(..).

Not all attributes have a default value. For example the service will not have a defaultvalue for RequestingUser i.e. a null return for a supported category means there is no service default value for that category. Use the isAttributeCategorySupported(Class) method to distinguish these cases.

Parameters:
category - Printing attribute category for which the default attribute value is requested. It must be a Class that implements interface Attribute.
Returns:
Default attribute value for category, or null if this Print Service does not support specifying a doc-level or job-level attribute in category in a Print Request, or the service does not have a default value for this attribute.
Throws:
NullPointerException - (unchecked exception) Thrown if category is null.
IllegalArgumentException - (unchecked exception) Thrown if category is not a Class that implements interface Attribute.

getSupportedAttributeValues

Object getSupportedAttributeValues(Class<? extends Attribute> category,
                                   DocFlavor flavor,
                                   AttributeSet attributes)
Determines the printing attribute values a client can specify in the given category when setting up a job for this print service. A printing attribute value is an instance of a class that implements interface Attribute.

If flavor is null and attributes is null or is an empty set, this method returns all the printing attribute values this Print Service supports for any possible job. If flavor is not null or attributes is not an empty set, this method returns just the printing attribute values that are compatible with the given doc flavor and/or set of attributes. That is, a null return value may indicate that specifying this attribute is incompatible with the specified DocFlavor. Also if DocFlavor is not null it must be a flavor supported by this PrintService, else IllegalArgumentException will be thrown.

If the attributes parameter contains an Attribute whose category is the same as the category parameter, the service must ignore this attribute in the AttributeSet.

DocAttributes which are to be specified on the Doc must be included in this set to accurately represent the context.

This method returns an Object because different printing attribute categories indicate the supported attribute values in different ways. The documentation for each printing attribute in package javax.print.attribute.standard describes how each attribute indicates its supported values. Possible ways of indicating support include:

  • Return a single instance of the attribute category to indicate that any value is legal -- used, for example, by an attribute whose value is an arbitrary text string. (The value of the returned attribute object is irrelevant.)
  • Return an array of one or more instances of the attribute category, containing the legal values -- used, for example, by an attribute with a list of enumerated values. The type of the array is an array of the specified attribute category type as returned by its getCategory(Class).
  • Return a single object (of some class other than the attribute category) that indicates bounds on the legal values -- used, for example, by an integer-valued attribute that must lie within a certain range.

Parameters:
category - Printing attribute category to test. It must be a Class that implements interface Attribute.
flavor - Doc flavor for a supposed job, or null.
attributes - Set of printing attributes for a supposed job (both job-level attributes and document-level attributes), or null.
Returns:
Object indicating supported values for category, or null if this Print Service does not support specifying a doc-level or job-level attribute in category in a Print Request.
Throws:
NullPointerException - (unchecked exception) Thrown if category is null.
IllegalArgumentException - (unchecked exception) Thrown if category is not a Class that implements interface Attribute, or DocFlavor is not supported by this service.

isAttributeValueSupported

boolean isAttributeValueSupported(Attribute attrval,
                                  DocFlavor flavor,
                                  AttributeSet attributes)
Determines whether a client can specify the given printing attribute value when setting up a job for this Print Service. A printing attribute value is an instance of a class that implements interface Attribute.

If flavor is null and attributes is null or is an empty set, this method tells whether this Print Service supports the given printing attribute value for some possible combination of doc flavor and set of attributes. If flavor is not null or attributes is not an empty set, this method tells whether this Print Service supports the given printing attribute value in combination with the given doc flavor and/or set of attributes.

Also if DocFlavor is not null it must be a flavor supported by this PrintService, else IllegalArgumentException will be thrown.

DocAttributes which are to be specified on the Doc must be included in this set to accurately represent the context.

This is a convenience method to determine if the value would be a member of the result of getSupportedAttributeValues(...).

Parameters:
attrval - Printing attribute value to test.
flavor - Doc flavor for a supposed job, or null.
attributes - Set of printing attributes for a supposed job (both job-level attributes and document-level attributes), or null.
Returns:
True if this Print Service supports specifying attrval as a doc-level or job-level attribute in a Print Request, false if it doesn't.
Throws:
NullPointerException - (unchecked exception) if attrval is null.
IllegalArgumentException - if flavor is not supported by this PrintService.

getUnsupportedAttributes

AttributeSet getUnsupportedAttributes(DocFlavor flavor,
                                      AttributeSet attributes)
Identifies the attributes that are unsupported for a print request in the context of a particular DocFlavor. This method is useful for validating a potential print job and identifying the specific attributes which cannot be supported. It is important to supply only a supported DocFlavor or an IllegalArgumentException will be thrown. If the return value from this method is null, all attributes are supported.

DocAttributes which are to be specified on the Doc must be included in this set to accurately represent the context.

If the return value is non-null, all attributes in the returned set are unsupported with this DocFlavor. The returned set does not distinguish attribute categories that are unsupported from unsupported attribute values.

A supported print request can then be created by removing all unsupported attributes from the original attribute set, except in the case that the DocFlavor is unsupported.

If any attributes are unsupported only because they are in conflict with other attributes then it is at the discretion of the service to select the attribute(s) to be identified as the cause of the conflict.

Use isDocFlavorSupported() to verify that a DocFlavor is supported before calling this method.

Parameters:
flavor - Doc flavor to test, or null
attributes - Set of printing attributes for a supposed job (both job-level attributes and document-level attributes), or null.
Returns:
null if this Print Service supports the print request specification, else the unsupported attributes.
Throws:
IllegalArgumentException - ifflavor is not supported by this PrintService.

getServiceUIFactory

ServiceUIFactory getServiceUIFactory()
Returns a factory for UI components which allow users to interact with the service in various roles. Services which do not provide any UI should return null. Print Services which do provide UI but want to be supported in an environment with no UI support should ensure that the factory is not initialised unless the application calls this method to obtain the factory. See ServiceUIFactory for more information.

Returns:
null or a factory for UI components.

equals

boolean equals(Object obj)
Determines if two services are referring to the same underlying service. Objects encapsulating a print service may not exhibit equality of reference even though they refer to the same underlying service.

Clients should call this method to determine if two services are referring to the same underlying service.

Services must implement this method and return true only if the service objects being compared may be used interchangeably by the client. Services are free to return the same object reference to an underlying service if that, but clients must not depend on equality of reference.

Overrides:
equals in class Object
Parameters:
obj - the reference object with which to compare.
Returns:
true if this service is the same as the obj argument, false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

int hashCode()
This method should be implemented consistently with equals(Object).

Overrides:
hashCode in class Object
Returns:
hash code of this object.
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrintServiceLookup

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Class PrintServiceLookup

java.lang.Object
    extended by  javax.print.PrintServiceLookup

public abstract class PrintServiceLookup
extends Object

Implementations of this class provide lookup services for print services (typically equivalent to printers) of a particular type.

Multiple implementations may be installed concurrently. All implementations must be able to describe the located printers as instances of a PrintService. Typically implementations of this service class are located automatically in JAR files (see the SPI JAR file specification). These classes must be instantiable using a default constructor. Alternatively applications may explicitly register instances at runtime.

Applications use only the static methods of this abstract class. The instance methods are implemented by a service provider in a subclass and the unification of the results from all installed lookup classes are reported by the static methods of this class when called by the application.

A PrintServiceLookup implementor is recommended to check for the SecurityManager.checkPrintJobAccess() to deny access to untrusted code. Following this recommended policy means that untrusted code may not be able to locate any print services. Downloaded applets are the most common example of untrusted code.

This check is made on a per lookup service basis to allow flexibility in the policy to reflect the needs of different lookup services.

Services which are registered by registerService(PrintService) will not be included in lookup results if a security manager is installed and its checkPrintJobAccess() method denies access.

Constructor Summary
PrintServiceLookup()
Method Summary
abstract PrintService | getDefaultPrintService() Not called directly by applications.
abstract MultiDocPrintService[] | getMultiDocPrintServices(DocFlavor[] flavors, AttributeSet attributes) Not called directly by applications.
abstract PrintService[] | getPrintServices() Not called directly by applications.
abstract PrintService[] | getPrintServices(DocFlavor flavor, AttributeSet attributes) Locates services that can be positively confirmed to support the combination of attributes and DocFlavors specified.
static PrintService | lookupDefaultPrintService() Locates the default print service for this environment.
static MultiDocPrintService[] | lookupMultiDocPrintServices(DocFlavor[] flavors, AttributeSet attributes) Locates MultiDoc print Services capable of printing MultiDocs containing all the specified doc flavors.
static PrintService[] | lookupPrintServices(DocFlavor flavor, AttributeSet attributes) Locates print services capable of printing the specified DocFlavor.
static boolean | registerService(PrintService service) Allows an application to directly register an instance of a class which implements a print service.
static boolean | registerServiceProvider(PrintServiceLookup sp) Allows an application to explicitly register a class that implements lookup services.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PrintServiceLookup

public PrintServiceLookup()
Method Detail

lookupPrintServices

public static final PrintService[] lookupPrintServices(DocFlavor flavor,
                                                       AttributeSet attributes)
Locates print services capable of printing the specified DocFlavor.

Parameters:
flavor - the flavor to print. If null, this constraint is not used.
attributes - attributes that the print service must support. If null this constraint is not used.
Returns:
array of matching PrintService objects representing print services that support the specified flavor attributes. If no services match, the array is zero-length.

lookupMultiDocPrintServices

public static final MultiDocPrintService[] lookupMultiDocPrintServices(DocFlavor[] flavors,
                                                                       AttributeSet attributes)
Locates MultiDoc print Services capable of printing MultiDocs containing all the specified doc flavors.

This method is useful to help locate a service that can print a MultiDoc in which the elements may be different flavors. An application could perform this itself by multiple lookups on each DocFlavor in turn and collating the results, but the lookup service may be able to do this more efficiently.

Parameters:
flavors - the flavors to print. If null or empty this constraint is not used. Otherwise return only multidoc print services that can print all specified doc flavors.
attributes - attributes that the print service must support. If null this constraint is not used.
Returns:
array of matching MultiDocPrintService objects. If no services match, the array is zero-length.

lookupDefaultPrintService

public static final PrintService lookupDefaultPrintService()
Locates the default print service for this environment. This may return null. If multiple lookup services each specify a default, the chosen service is not precisely defined, but a platform native service, rather than an installed service, is usually returned as the default. If there is no clearly identifiable platform native default print service, the default is the first to be located in an implementation-dependent manner.

This may include making use of any preferences API that is available as part of the Java or native platform. This algorithm may be overridden by a user setting the property javax.print.defaultPrinter. A service specified must be discovered to be valid and currently available to be returned as the default.

Returns:
the default PrintService.

registerServiceProvider

public static boolean registerServiceProvider(PrintServiceLookup sp)
Allows an application to explicitly register a class that implements lookup services. The registration will not persist across VM invocations. This is useful if an application needs to make a new service available that is not part of the installation. If the lookup service is already registered, or cannot be registered, the method returns false.

Parameters:
sp - an implementation of a lookup service.
Returns:
true if the new lookup service is newly registered; false otherwise.

registerService

public static boolean registerService(PrintService service)
Allows an application to directly register an instance of a class which implements a print service. The lookup operations for this service will be performed by the PrintServiceLookup class using the attribute values and classes reported by the service. This may be less efficient than a lookup service tuned for that service. Therefore registering a PrintServiceLookup instance instead is recommended. The method returns true if this service is not previously registered and is now successfully registered. This method should not be called with StreamPrintService instances. They will always fail to register and the method will return false.

Parameters:
service - an implementation of a print service.
Returns:
true if the service is newly registered; false otherwise.

getPrintServices

public abstract PrintService[] getPrintServices(DocFlavor flavor,
                                                AttributeSet attributes)
Locates services that can be positively confirmed to support the combination of attributes and DocFlavors specified. This method is not called directly by applications.

Implemented by a service provider, used by the static methods of this class.

The results should be the same as obtaining all the PrintServices and querying each one individually on its support for the specified attributes and flavors, but the process can be more efficient by taking advantage of the capabilities of lookup services for the print services.

Parameters:
flavor - of document required. If null it is ignored.
attributes - required to be supported. If null this constraint is not used.
Returns:
array of matching PrintServices. If no services match, the array is zero-length.

getPrintServices

public abstract PrintService[] getPrintServices()
Not called directly by applications. Implemented by a service provider, used by the static methods of this class.

Returns:
array of all PrintServices known to this lookup service class. If none are found, the array is zero-length.

getMultiDocPrintServices

public abstract MultiDocPrintService[] getMultiDocPrintServices(DocFlavor[] flavors,
                                                                AttributeSet attributes)
Not called directly by applications.

Implemented by a service provider, used by the static methods of this class.

Locates MultiDoc print services which can be positively confirmed to support the combination of attributes and DocFlavors specified.

Parameters:
flavors - of documents required. If null or empty it is ignored.
attributes - required to be supported. If null this constraint is not used.
Returns:
array of matching PrintServices. If no services match, the array is zero-length.

getDefaultPrintService

public abstract PrintService getDefaultPrintService()
Not called directly by applications. Implemented by a service provider, and called by the print lookup service

Returns:
the default PrintService for this lookup service. If there is no default, returns null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServiceUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Class ServiceUI

java.lang.Object
    extended by  javax.print.ServiceUI

public class ServiceUI
extends Object

This class is a collection of UI convenience methods which provide a graphical user dialog for browsing print services looked up through the Java Print Service API.

The dialogs follow a standard pattern of acting as a continue/cancel option for a user as well as allowing the user to select the print service to use and specify choices such as paper size and number of copies.

The dialogs are designed to work with pluggable print services though the public APIs of those print services.

If a print service provides any vendor extensions these may be made accessible to the user through a vendor supplied tab panel Component. Such a vendor extension is encouraged to use Swing! and to support its accessibility APIs. The vendor extensions should return the settings as part of the AttributeSet. Applications which want to preserve the user settings should use those settings to specify the print job. Note that this class is not referenced by any other part of the Java Print Service and may not be included in profiles which cannot depend on the presence of the AWT packages.

Constructor Summary
ServiceUI()
Method Summary
static PrintService printDialog(GraphicsConfiguration gc, int x, int y, PrintService[] services, PrintService defaultService, DocFlavor flavor, PrintRequestAttributeSet attributes)
Presents a dialog to the user for selecting a print service (printer).
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServiceUI

public ServiceUI()
Method Detail

printDialog

public static PrintService printDialog(GraphicsConfiguration gc,
                                       int x,
                                       int y,
                                       PrintService[] services,
                                       PrintService defaultService,
                                       DocFlavor flavor,
                                       PrintRequestAttributeSet attributes)
                                throws HeadlessException
Presents a dialog to the user for selecting a print service (printer). It is displayed at the location specified by the application and is modal. If the specification is invalid or would make the dialog not visible it will be displayed at a location determined by the implementation. The dialog blocks its calling thread and is application modal.

The dialog may include a tab panel with custom UI lazily obtained from the PrintService's ServiceUIFactory when the PrintService is browsed. The dialog will attempt to locate a MAIN_UIROLE first as a JComponent, then as a Panel. If there is no ServiceUIFactory or no matching role the custom tab will be empty or not visible.

The dialog returns the print service selected by the user if the user OK's the dialog and null if the user cancels the dialog.

An application must pass in an array of print services to browse. The array must be non-null and non-empty. Typically an application will pass in only PrintServices capable of printing a particular document flavor.

An application may pass in a PrintService to be initially displayed. A non-null parameter must be included in the array of browsable services. If this parameter is null a service is chosen by the implementation.

An application may optionally pass in the flavor to be printed. If this is non-null choices presented to the user can be better validated against those supported by the services. An application must pass in a PrintRequestAttributeSet for returning user choices. On calling the PrintRequestAttributeSet may be empty, or may contain application-specified values.

These are used to set the initial settings for the initially displayed print service. Values which are not supported by the print service are ignored. As the user browses print services, attributes and values are copied to the new display. If a user browses a print service which does not support a particular attribute-value, the default for that service is used as the new value to be copied.

If the user cancels the dialog, the returned attributes will not reflect any changes made by the user. A typical basic usage of this method may be :

 PrintService[] services = PrintServiceLookup.lookupPrintServices(
                            DocFlavor.INPUT_STREAM.JPEG, null);
 PrintRequestAttributeSet attributes = new HashPrintRequestAttributeSet();
 if (services.length > 0) {
    PrintService service =  ServiceUI.printDialog(null, 50, 50,
                                               services, services[0],
                                               null,
                                               attributes);
    if (service != null) {
     ... print ...
    }
 }

Parameters:
gc - used to select screen. null means primary or default screen.
x - location of dialog including border in screen coordinates
y - location of dialog including border in screen coordinates
services - to be browsable, must be non-null.
defaultService - - initial PrintService to display.
flavor - - the flavor to be printed, or null.
attributes - on input is the initial application supplied preferences. This cannot be null but may be empty. On output the attributes reflect changes made by the user.
Returns:
print service selected by the user, or null if the user cancelled the dialog.
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
IllegalArgumentException - if services is null or empty, or attributes is null, or the initial PrintService is not in the list of browsable services.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServiceUIFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Class ServiceUIFactory

java.lang.Object
    extended by  javax.print.ServiceUIFactory

public abstract class ServiceUIFactory
extends Object

Services may optionally provide UIs which allow different styles of interaction in different roles. One role may be end-user browsing and setting of print options. Another role may be administering the print service.

Although the Print Service API does not presently provide standardised support for administering a print service, monitoring of the print service is possible and a UI may provide for private update mechanisms.

The basic design intent is to allow applications to lazily locate and initialize services only when needed without any API dependencies except in an environment in which they are used.

Swing UIs are preferred as they provide a more consistent L&F and can support accessibility APIs.

Example usage:

  ServiceUIFactory factory = printService.getServiceUIFactory();
  if (factory != null) {
      JComponent swingui = (JComponent)factory.getUI(
                                         ServiceUIFactory.MAIN_UIROLE,
                                         ServiceUIFactory.JCOMPONENT_UI);
      if (swingui != null) {
          tabbedpane.add("Custom UI", swingui);
      }
  }

Field Summary
static int | ABOUT_UIROLE Denotes a UI which performs an informative "About" role.
static int | ADMIN_UIROLE Denotes a UI which performs an administrative role.
static String | DIALOG_UI Denotes a UI implemented as an AWT dialog.
static String | JCOMPONENT_UI Denotes a UI implemented as a Swing component.
static String | JDIALOG_UI Denotes a UI implemented as a Swing dialog.
static int | MAIN_UIROLE Denotes a UI which performs the normal end user role.
static String | PANEL_UI Denotes a UI implemented as an AWT panel.
static int | RESERVED_UIROLE Not a valid role but role id's greater than this may be used for private roles supported by a service.
Constructor Summary
ServiceUIFactory()
Method Summary
abstract Object | getUI(int role, String ui) Get a UI object which may be cast to the requested UI type by the application and used in its user interface.
abstract String[] | getUIClassNamesForRole(int role) Given a UI role obtained from this factory obtain the UI types available from this factory which implement this role.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

JCOMPONENT_UI

public static final String JCOMPONENT_UI
Denotes a UI implemented as a Swing component. The value of the String is the fully qualified classname : "javax.swing.JComponent".

See Also:
Constant Field Values

PANEL_UI

public static final String PANEL_UI
Denotes a UI implemented as an AWT panel. The value of the String is the fully qualified classname : "java.awt.Panel"

See Also:
Constant Field Values

DIALOG_UI

public static final String DIALOG_UI
Denotes a UI implemented as an AWT dialog. The value of the String is the fully qualified classname : "java.awt.Dialog"

See Also:
Constant Field Values

JDIALOG_UI

public static final String JDIALOG_UI
Denotes a UI implemented as a Swing dialog. The value of the String is the fully qualified classname : "javax.swing.JDialog"

See Also:
Constant Field Values

ABOUT_UIROLE

public static final int ABOUT_UIROLE
Denotes a UI which performs an informative "About" role.

See Also:
Constant Field Values

ADMIN_UIROLE

public static final int ADMIN_UIROLE
Denotes a UI which performs an administrative role.

See Also:
Constant Field Values

MAIN_UIROLE

public static final int MAIN_UIROLE
Denotes a UI which performs the normal end user role.

See Also:
Constant Field Values

RESERVED_UIROLE

public static final int RESERVED_UIROLE
Not a valid role but role id's greater than this may be used for private roles supported by a service. Knowledge of the function performed by this role is required to make proper use of it.

See Also:
Constant Field Values
Constructor Detail

ServiceUIFactory

public ServiceUIFactory()
Method Detail

getUI

public abstract Object getUI(int role,
                             String ui)
Get a UI object which may be cast to the requested UI type by the application and used in its user interface.

Parameters:
role - requested. Must be one of the standard roles or a private role supported by this factory.
ui - type in which the role is requested.
Returns:
the UI role or null if the requested UI role is not available from this factory
Throws:
IllegalArgumentException - if the role or ui is neither one of the standard ones, nor a private one supported by the factory.

getUIClassNamesForRole

public abstract String[] getUIClassNamesForRole(int role)
Given a UI role obtained from this factory obtain the UI types available from this factory which implement this role. The returned Strings should refer to the static variables defined in this class so that applications can use equality of reference ("==").

Parameters:
role - to be looked up.
Returns:
the UI types supported by this class for the specified role, null if no UIs are available for the role.
Throws:
IllegalArgumentException - is the role is a non-standard role not supported by this factory.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SimpleDoc

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Class SimpleDoc

java.lang.Object
    extended by  javax.print.SimpleDoc
All Implemented Interfaces:
Doc
public final class SimpleDoc
extends Object
implements Doc

This class is an implementation of interface Doc that can be used in many common printing requests. It can handle all of the presently defined "pre-defined" doc flavors defined as static variables in the DocFlavor class.

In particular this class implements certain required semantics of the Doc specification as follows:

  • constructs a stream for the service if requested and appropriate.
  • ensures the same object is returned for each call on a method.
  • ensures multiple threads can access the Doc
  • performs some validation of that the data matches the doc flavor.
Clients who want to re-use the doc object in other jobs, or need a MultiDoc will not want to use this class.

If the print data is a stream, or a print job requests data as a stream, then SimpleDoc does not monitor if the service properly closes the stream after data transfer completion or job termination. Clients may prefer to use provide their own implementation of doc that adds a listener to monitor job completion and to validate that resources such as streams are freed (ie closed).

Constructor Summary
SimpleDoc(Object printData, DocFlavor flavor, DocAttributeSet attributes)
Constructs a SimpleDoc with the specified print data, doc flavor and doc attribute set.
Method Summary
DocAttributeSet | getAttributes() Obtains the set of printing attributes for this doc object.
DocFlavor | getDocFlavor() Determines the doc flavor in which this doc object will supply its piece of print data.
Object | getPrintData() Obtains the print data representation object that contains this doc object's piece of print data in the format corresponding to the supported doc flavor.
Reader | getReaderForText() Obtains a reader for extracting character print data from this doc.
InputStream | getStreamForBytes() Obtains an input stream for extracting byte print data from this doc.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SimpleDoc

public SimpleDoc(Object printData,
                 DocFlavor flavor,
                 DocAttributeSet attributes)
Constructs a SimpleDoc with the specified print data, doc flavor and doc attribute set.

Parameters:
printData - the print data object
flavor - the DocFlavor object
attributes - a DocAttributeSet, which can be null
Throws:
IllegalArgumentException - if flavor or printData is null, or the printData does not correspond to the specified doc flavor--for example, the data is not of the type specified as the representation in the DocFlavor.
Method Detail

getDocFlavor

public DocFlavor getDocFlavor()
Determines the doc flavor in which this doc object will supply its piece of print data.

Specified by:
getDocFlavor in interface Doc
Returns:
Doc flavor.

getAttributes

public DocAttributeSet getAttributes()
Obtains the set of printing attributes for this doc object. If the returned attribute set includes an instance of a particular attribute X, the printer must use that attribute value for this doc, overriding any value of attribute X in the job's attribute set. If the returned attribute set does not include an instance of a particular attribute X or if null is returned, the printer must consult the job's attribute set to obtain the value for attribute X, and if not found there, the printer must use an implementation-dependent default value. The returned attribute set is unmodifiable.

Specified by:
getAttributes in interface Doc
Returns:
Unmodifiable set of printing attributes for this doc, or null to obtain all attribute values from the job's attribute set.

getPrintData

public Object getPrintData()
                    throws IOException
Description copied from interface: Doc
Obtains the print data representation object that contains this doc object's piece of print data in the format corresponding to the supported doc flavor. The getPrintData() method returns an instance of the representation class whose name is given by getDocFlavor().getRepresentationClassName(), and the return value can be cast from class Object to that representation class.

Specified by:
getPrintData in interface Doc
Returns:
Print data representation object.
Throws:
IOException - Thrown if the representation class is a stream and there was an I/O error while constructing the stream.

getReaderForText

public Reader getReaderForText()
                        throws IOException
Obtains a reader for extracting character print data from this doc. The Doc implementation is required to support this method if the DocFlavor has one of the following print data representation classes, and return null otherwise:
  • char[]
  • java.lang.String
  • java.io.Reader
The doc's print data representation object is used to construct and return a Reader for reading the print data as a stream of characters from the print data representation object. However, if the print data representation object is itself a Reader then the print data representation object is simply returned.

Specified by:
getReaderForText in interface Doc
Returns:
a Reader for reading the print data characters from this doc. If a reader cannot be provided because this doc does not meet the criteria stated above, null is returned.
Throws:
IOException - if there was an I/O error while creating the reader.

getStreamForBytes

public InputStream getStreamForBytes()
                              throws IOException
Obtains an input stream for extracting byte print data from this doc. The Doc implementation is required to support this method if the DocFlavor has one of the following print data representation classes; otherwise this method returns null:
  • byte[]
  • java.io.InputStream
The doc's print data representation object is obtained. Then, an input stream for reading the print data from the print data representation object as a stream of bytes is created and returned. However, if the print data representation object is itself an input stream then the print data representation object is simply returned.

Specified by:
getStreamForBytes in interface Doc
Returns:
an InputStream for reading the print data bytes from this doc. If an input stream cannot be provided because this doc does not meet the criteria stated above, null is returned.
Throws:
IOException - if there was an I/O error while creating the input stream.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StreamPrintService

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Class StreamPrintService

java.lang.Object
    extended by  javax.print.StreamPrintService
All Implemented Interfaces:
PrintService
public abstract class StreamPrintService
extends Object
implements PrintService

This class extends PrintService and represents a print service that prints data in different formats to a client-provided output stream. This is principally intended for services where the output format is a document type suitable for viewing or archiving. The output format must be declared as a mime type. This is equivalent to an output document flavor where the representation class is always "java.io.OutputStream" An instance of the StreamPrintService class is obtained from a StreamPrintServiceFactory instance.

Note that a StreamPrintService is different from a PrintService, which supports a Destination attribute. A StreamPrintService always requires an output stream, whereas a PrintService optionally accepts a Destination. A StreamPrintService has no default destination for its formatted output. Additionally a StreamPrintService is expected to generate output in a format useful in other contexts. StreamPrintService's are not expected to support the Destination attribute.

Constructor Summary
protected StreamPrintService(OutputStream out)
Constructs a StreamPrintService object.
Method Summary
void | dispose() Disposes this StreamPrintService.
abstract String | getOutputFormat() Returns the document format emitted by this print service.
OutputStream | getOutputStream() Gets the output stream.
boolean | isDisposed() Returns a boolean indicating whether or not this StreamPrintService has been disposed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.print.PrintService
addPrintServiceAttributeListener, createPrintJob, equals, getAttribute, getAttributes, getDefaultAttributeValue, getName, getServiceUIFactory, getSupportedAttributeCategories, getSupportedAttributeValues, getSupportedDocFlavors, getUnsupportedAttributes, hashCode, isAttributeCategorySupported, isAttributeValueSupported, isDocFlavorSupported, removePrintServiceAttributeListener

Constructor Detail

StreamPrintService

protected StreamPrintService(OutputStream out)
Constructs a StreamPrintService object.

Parameters:
out - stream to which to send formatted print data.
Method Detail

getOutputStream

public OutputStream getOutputStream()
Gets the output stream.

Returns:
the stream to which this service will send formatted print data.

getOutputFormat

public abstract String getOutputFormat()
Returns the document format emitted by this print service. Must be in mimetype format, compatible with the mime type components of DocFlavors @see DocFlavor.

Returns:
mime type identifying the output format.

dispose

public void dispose()
Disposes this StreamPrintService. If a stream service cannot be re-used, it must be disposed to indicate this. Typically the client will call this method. Services which write data which cannot meaningfully be appended to may also dispose the stream. This does not close the stream. It just marks it as not for further use by this service.

isDisposed

public boolean isDisposed()
Returns a boolean indicating whether or not this StreamPrintService has been disposed. If this object has been disposed, will return true. Used by services and client applications to recognize streams to which no further data should be written.

Returns:
if this StreamPrintService has been disposed
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StreamPrintServiceFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.print
Class StreamPrintServiceFactory

java.lang.Object
    extended by  javax.print.StreamPrintServiceFactory

public abstract class StreamPrintServiceFactory
extends Object

A StreamPrintServiceFactory is the factory for StreamPrintService instances, which can print to an output stream in a particular document format described as a mime type. A typical output document format may be Postscript(TM).

This class is implemented by a service and located by the implementation using the SPI JAR File specification.

Applications locate instances of this class by calling the lookupStreamPrintServiceFactories(DocFlavor, String) method.

Applications can use a StreamPrintService obtained from a factory in place of a PrintService which represents a physical printer device.

Constructor Summary
StreamPrintServiceFactory()
Method Summary
abstract String | getOutputFormat() Queries the factory for the document format that is emitted by printers obtained from this factory.
abstract StreamPrintService | getPrintService(OutputStream out) Returns a StreamPrintService that can print to the specified output stream.
abstract DocFlavor[] | getSupportedDocFlavors() Queries the factory for the document flavors that can be accepted by printers obtained from this factory.
static StreamPrintServiceFactory[] | lookupStreamPrintServiceFactories(DocFlavor flavor, String outputMimeType) Locates factories for print services that can be used with a print job to output a stream of data in the format specified by flavor.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StreamPrintServiceFactory

public StreamPrintServiceFactory()
Method Detail

lookupStreamPrintServiceFactories

public static StreamPrintServiceFactory[] lookupStreamPrintServiceFactories(DocFlavor flavor,
                                                                            String outputMimeType)
Locates factories for print services that can be used with a print job to output a stream of data in the format specified by flavor. For example, the doc flavor is the document type that you want to create, not the flavor of the document before printing.

Although null is an acceptable value to use in the lookup of stream printing services, it's typical to search for a particular desired format, such as Postscript(TM).

Parameters:
flavor - of the input document type - null means match all types.
outputMimeType - representing the required output format, used to identify suitable stream printer factories. A value of null means match all formats.
Returns:
- matching factories for stream print service instance, empty if no suitable factories could be located.

getOutputFormat

public abstract String getOutputFormat()
Queries the factory for the document format that is emitted by printers obtained from this factory.

Returns:
the output format described as a mime type.

getSupportedDocFlavors

public abstract DocFlavor[] getSupportedDocFlavors()
Queries the factory for the document flavors that can be accepted by printers obtained from this factory.

Returns:
array of supported doc flavors.

getPrintService

public abstract StreamPrintService getPrintService(OutputStream out)
Returns a StreamPrintService that can print to the specified output stream. The output stream is created and managed by the application. It is the application's responsibility to close the stream and to ensure that this Printer is not reused. The application should not close this stream until any print job created from the printer is complete. Doing so earlier may generate a PrinterException and an event indicating that the job failed.

Whereas a PrintService connected to a physical printer can be reused, a StreamPrintService connected to a stream cannot. The underlying StreamPrintService may be disposed by the print system with the dispose method before returning from the print method of DocPrintJob so that the print system knows this printer is no longer usable. This is equivalent to a physical printer going offline - permanently. Applications may supply a null print stream to create a queryable service. It is not valid to create a PrintJob for such a stream. Implementations which allocate resources on construction should examine the stream and may wish to only allocate resources if the stream is non-null.

Parameters:
out - destination stream for generated output.
Returns:
a PrintService which will generate the format specified by the DocFlavor supported by this Factory.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


URIException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.print
Interface URIException

public interface URIException

Interface URIException is a mixin interface which a subclass of PrintException can implement to report an error condition involving a URI address. The Print Service API does not define any print exception classes that implement interface URIException, that being left to the Print Service implementor's discretion.

Field Summary
static int | URIInaccessible Indicates that the printer cannot access the URI address.
static int | URIOtherProblem Indicates any kind of problem not specifically identified by the other reasons.
static int | URISchemeNotSupported Indicates that the printer does not support the URI scheme ("http", "ftp", etc.) in the URI address.
Method Summary
int | getReason() Return the reason for the event.
URI | getUnsupportedURI() Return the URI.

Field Detail

URIInaccessible

static final int URIInaccessible
Indicates that the printer cannot access the URI address. For example, the printer might report this error if it goes to get the print data and cannot even establish a connection to the URI address.

See Also:
Constant Field Values

URISchemeNotSupported

static final int URISchemeNotSupported
Indicates that the printer does not support the URI scheme ("http", "ftp", etc.) in the URI address.

See Also:
Constant Field Values

URIOtherProblem

static final int URIOtherProblem
Indicates any kind of problem not specifically identified by the other reasons.

See Also:
Constant Field Values
Method Detail

getUnsupportedURI

URI getUnsupportedURI()
Return the URI.

Returns:
the URI that is the cause of this exception.

getReason

int getReason()
Return the reason for the event.

Returns:
one of the predefined reasons enumerated in this interface.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


rmi

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.rmi

Contains user APIs for RMI-IIOP.

See:
Description

Class Summary
PortableRemoteObject Server implementation objects may either inherit from javax.rmi.PortableRemoteObject or they may implement a remote interface and then use the exportObject method to register themselves as a server object.

Package javax.rmi Description

Contains user APIs for RMI-IIOP. These APIs are provided for use by RMI-IIOP applications, and provide equivalent semantics when running over either IIOP or JRMP. See also the javax.rmi.CORBA package.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.rmi Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.rmi

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.rmi.PortableRemoteObject
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.rmi

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.rmi

No usage of javax.rmi

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.rmi.PortableRemoteObject

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.rmi.PortableRemoteObject

No usage of javax.rmi.PortableRemoteObject

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


CORBA

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.rmi.CORBA

Contains portability APIs for RMI-IIOP.

See:
Description

Interface Summary
PortableRemoteObjectDelegate | Supports delegation for method implementations in PortableRemoteObject.
StubDelegate | Supports delegation for method implementations in Stub.
Tie | Defines methods which all RMI-IIOP server side ties must implement.
UtilDelegate | Supports delegation for method implementations in Util.
ValueHandler | Defines methods which allow serialization of Java objects to and from GIOP streams.
ValueHandlerMultiFormat | Java to IDL ptc 02-01-12 1.5.1.5

Class Summary
ClassDesc | This class is used to marshal java.lang.Class objects over IIOP.
Stub | Base class from which all RMI-IIOP stubs must inherit.
Util | Provides utility methods that can be used by stubs and ties to perform common operations.

Package javax.rmi.CORBA Description

Contains portability APIs for RMI-IIOP. These APIs provide a standard interface between the generated stubs and ties and the RMI-IIOP runtime. They also allow third party ORBs to be used for RMI over IIOP as an alternative to the ORB supplied by Sun. They are not intended to be called directly from RMI-IIOP applications. See also the javax.rmi package.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.rmi.CORBA Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.rmi.CORBA

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.rmi.CORBA.ClassDesc (implements java.io.Serializable)
    • org.omg.CORBA.portable.ObjectImpl (implements org.omg.CORBA.Object)
      • org.omg.CORBA_2_3.portable.ObjectImpl
        • javax.rmi.CORBA.Stub (implements java.io.Serializable)
    • javax.rmi.CORBA.Util

Interface Hierarchy

  • org.omg.CORBA.portable.InvokeHandler
    • javax.rmi.CORBA.Tie
  • javax.rmi.CORBA.PortableRemoteObjectDelegate
  • javax.rmi.CORBA.StubDelegate
  • javax.rmi.CORBA.UtilDelegate
  • javax.rmi.CORBA.ValueHandler
    • javax.rmi.CORBA.ValueHandlerMultiFormat
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.rmi.CORBA

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.rmi.CORBA

Packages that use javax.rmi.CORBA
javax.rmi.CORBA | Contains portability APIs for RMI-IIOP.
org.omg.stub.java.rmi | Contains RMI-IIOP Stubs for the Remote types that occur in the java.rmi package.

Classes in javax.rmi.CORBA used by javax.rmi.CORBA
Stub
Base class from which all RMI-IIOP stubs must inherit.
Tie
Defines methods which all RMI-IIOP server side ties must implement.
ValueHandler
Defines methods which allow serialization of Java objects to and from GIOP streams.

Classes in javax.rmi.CORBA used by org.omg.stub.java.rmi
Stub
Base class from which all RMI-IIOP stubs must inherit.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.rmi.CORBA.ClassDesc

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.rmi.CORBA.ClassDesc

No usage of javax.rmi.CORBA.ClassDesc

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.rmi.CORBA.Stub

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.rmi.CORBA.Stub

Packages that use Stub
javax.rmi.CORBA | Contains portability APIs for RMI-IIOP.
org.omg.stub.java.rmi | Contains RMI-IIOP Stubs for the Remote types that occur in the java.rmi package.

Uses of Stub in javax.rmi.CORBA

Methods in javax.rmi.CORBA with parameters of type Stub
 void StubDelegate.connect(Stub self, ORB orb)
Delegation call for connect(org.omg.CORBA.ORB).
 boolean StubDelegate.equals(Stub self, Object obj)
Delegation call for equals(java.lang.Object).
 int StubDelegate.hashCode(Stub self)
Delegation call for hashCode().
 boolean UtilDelegate.isLocal(Stub stub)
Delegation call for Util.isLocal(javax.rmi.CORBA.Stub).
static boolean Util.isLocal(Stub stub)
The isLocal method has the same semantics as the ObjectImpl._is_local method, except that it can throw a RemoteException.
 void StubDelegate.readObject(Stub self, ObjectInputStream s)
Delegation call for Stub.readObject(java.io.ObjectInputStream).
 String StubDelegate.toString(Stub self)
Delegation call for toString().
 void StubDelegate.writeObject(Stub self, ObjectOutputStream s)
Delegation call for Stub.writeObject(java.io.ObjectOutputStream).

Uses of Stub in org.omg.stub.java.rmi

Subclasses of Stub in org.omg.stub.java.rmi
 class _Remote_Stub
This class provides the Stub for the Remote Type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.rmi.CORBA.Util

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.rmi.CORBA.Util

No usage of javax.rmi.CORBA.Util

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.rmi.CORBA.PortableRemoteObjectDelegate

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.rmi.CORBA.PortableRemoteObjectDelegate

No usage of javax.rmi.CORBA.PortableRemoteObjectDelegate

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.rmi.CORBA.StubDelegate

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.rmi.CORBA.StubDelegate

No usage of javax.rmi.CORBA.StubDelegate

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.rmi.CORBA.Tie

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.rmi.CORBA.Tie

Packages that use Tie
javax.rmi.CORBA Contains portability APIs for RMI-IIOP.

Uses of Tie in javax.rmi.CORBA

Methods in javax.rmi.CORBA that return Tie
 Tie UtilDelegate.getTie(Remote target)
Delegation call for Util.getTie(java.rmi.Remote).
static Tie Util.getTie(Remote target)
Returns the tie (if any) for a given target object.

Methods in javax.rmi.CORBA with parameters of type Tie
 void UtilDelegate.registerTarget(Tie tie, Remote target)
Delegation call for Util.registerTarget(javax.rmi.CORBA.Tie, java.rmi.Remote).
static void Util.registerTarget(Tie tie, Remote target)
Registers a target for a tie.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.rmi.CORBA.UtilDelegate

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.rmi.CORBA.UtilDelegate

No usage of javax.rmi.CORBA.UtilDelegate

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.rmi.CORBA.ValueHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.rmi.CORBA.ValueHandler

Packages that use ValueHandler
javax.rmi.CORBA Contains portability APIs for RMI-IIOP.

Uses of ValueHandler in javax.rmi.CORBA

Subinterfaces of ValueHandler in javax.rmi.CORBA
 interface ValueHandlerMultiFormat
Java to IDL ptc 02-01-12 1.5.1.5

Methods in javax.rmi.CORBA that return ValueHandler
 ValueHandler UtilDelegate.createValueHandler()
Delegation call for Util.createValueHandler().
static ValueHandler Util.createValueHandler()
Returns a singleton instance of a class that implements the ValueHandler interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.rmi.CORBA.ValueHandlerMultiFormat

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.rmi.CORBA.ValueHandlerMultiFormat

No usage of javax.rmi.CORBA.ValueHandlerMultiFormat

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ClassDesc

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.rmi.CORBA
Class ClassDesc

java.lang.Object
    extended by  javax.rmi.CORBA.ClassDesc
All Implemented Interfaces:
Serializable
public class ClassDesc
extends Object
implements Serializable

This class is used to marshal java.lang.Class objects over IIOP.

See Also:
Serialized Form

Constructor Summary
ClassDesc()
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ClassDesc

public ClassDesc()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


PortableRemoteObjectDelegate

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.rmi.CORBA
Interface PortableRemoteObjectDelegate

public interface PortableRemoteObjectDelegate

Supports delegation for method implementations in PortableRemoteObject. The delegate is a singleton instance of a class that implements this interface and provides a replacement implementation for all the methods of javax.rmi.PortableRemoteObject. Delegates are enabled by providing the delegate's class name as the value of the javax.rmi.CORBA.PortableRemoteObjectClass system property.

See Also:
PortableRemoteObject

Method Summary
 void connect(Remote target, Remote source)
Delegation call for PortableRemoteObject.connect(java.rmi.Remote, java.rmi.Remote).
 void exportObject(Remote obj)
Delegation call for PortableRemoteObject.exportObject(java.rmi.Remote).
 Object narrow(Object narrowFrom, Class narrowTo)
Delegation call for PortableRemoteObject.narrow(java.lang.Object, java.lang.Class).
 Remote toStub(Remote obj)
Delegation call for PortableRemoteObject.toStub(java.rmi.Remote).
 void unexportObject(Remote obj)
Delegation call for PortableRemoteObject.unexportObject(java.rmi.Remote).

Method Detail

exportObject

void exportObject(Remote obj)
                  throws RemoteException
Delegation call for PortableRemoteObject.exportObject(java.rmi.Remote).

Throws:
RemoteException

toStub

Remote toStub(Remote obj)
              throws NoSuchObjectException
Delegation call for PortableRemoteObject.toStub(java.rmi.Remote).

Throws:
NoSuchObjectException

unexportObject

void unexportObject(Remote obj)
                    throws NoSuchObjectException
Delegation call for PortableRemoteObject.unexportObject(java.rmi.Remote).

Throws:
NoSuchObjectException

narrow

Object narrow(Object narrowFrom,
              Class narrowTo)
              throws ClassCastException
Delegation call for PortableRemoteObject.narrow(java.lang.Object, java.lang.Class).

Throws:
ClassCastException

connect

void connect(Remote target,
             Remote source)
             throws RemoteException
Delegation call for PortableRemoteObject.connect(java.rmi.Remote, java.rmi.Remote).

Throws:
RemoteException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Stub

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.rmi.CORBA
Class Stub

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.CORBA_2_3.portable.ObjectImpl
            extended by  javax.rmi.CORBA.Stub
All Implemented Interfaces:
Serializable, Object
Direct Known Subclasses:
_Remote_Stub
public abstract class Stub
extends ObjectImpl
implements Serializable

Base class from which all RMI-IIOP stubs must inherit.

See Also:
Serialized Form

Constructor Summary
Stub()
Method Summary
void | connect(ORB orb) Connects this stub to an ORB.
boolean | equals(Object obj) Compares two stubs for equality.
int | hashCode() Returns a hash code value for the object which is the same for all stubs that represent the same remote object.
String | toString() Returns a string representation of this stub.
Methods inherited from class org.omg.CORBA_2_3.portable.ObjectImpl
_get_codebase
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _ids, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Stub

public Stub()
Method Detail

hashCode

public int hashCode()
Returns a hash code value for the object which is the same for all stubs that represent the same remote object.

Overrides:
hashCode in class ObjectImpl
Returns:
the hash code value.
See Also:
Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object obj)
Compares two stubs for equality. Returns true when used to compare stubs that represent the same remote object, and false otherwise.

Overrides:
equals in class ObjectImpl
Parameters:
obj - the reference object with which to compare.
Returns:
true if this object is the same as the obj argument; false otherwise.
See Also:
Object.hashCode(), Hashtable

toString

public String toString()
Returns a string representation of this stub. Returns the same string for all stubs that represent the same remote object.

Overrides:
toString in class ObjectImpl
Returns:
a string representation of this stub.

connect

public void connect(ORB orb)
             throws RemoteException
Connects this stub to an ORB. Required after the stub is deserialized but not after it is demarshalled by an ORB stream. If an unconnected stub is passed to an ORB stream for marshalling, it is implicitly connected to that ORB. Application code should not call this method directly, but should call the portable wrapper method PortableRemoteObject.connect(java.rmi.Remote, java.rmi.Remote).

Parameters:
orb - the ORB to connect to.
Throws:
RemoteException - if the stub is already connected to a different ORB, or if the stub does not represent an exported remote or local object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StubDelegate

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.rmi.CORBA
Interface StubDelegate

public interface StubDelegate

Supports delegation for method implementations in Stub. A delegate is an instance of a class that implements this interface and provides a replacement implementation for all the methods of javax.rmi.CORBA.Stub. If delegation is enabled, each stub has an associated delegate. Delegates are enabled by providing the delegate's class name as the value of the javax.rmi.CORBA.StubClass system property.

See Also:
Stub

Method Summary
 void connect(Stub self, ORB orb)
Delegation call for Stub.connect(org.omg.CORBA.ORB).
 boolean equals(Stub self, Object obj)
Delegation call for Stub.equals(java.lang.Object).
 int hashCode(Stub self)
Delegation call for Stub.hashCode().
 void readObject(Stub self, ObjectInputStream s)
Delegation call for Stub.readObject(java.io.ObjectInputStream).
 String toString(Stub self)
Delegation call for Stub.toString().
 void writeObject(Stub self, ObjectOutputStream s)
Delegation call for Stub.writeObject(java.io.ObjectOutputStream).

Method Detail

hashCode

int hashCode(Stub self)
Delegation call for Stub.hashCode().

equals

boolean equals(Stub self,
               Object obj)
Delegation call for Stub.equals(java.lang.Object).

toString

String toString(Stub self)
Delegation call for Stub.toString().

connect

void connect(Stub self,
             ORB orb)
             throws RemoteException
Delegation call for Stub.connect(org.omg.CORBA.ORB).

Throws:
RemoteException

readObject

void readObject(Stub self,
                ObjectInputStream s)
                throws IOException,
                       ClassNotFoundException
Delegation call for Stub.readObject(java.io.ObjectInputStream).

Throws:
IOException
ClassNotFoundException

writeObject

void writeObject(Stub self,
                 ObjectOutputStream s)
                 throws IOException
Delegation call for Stub.writeObject(java.io.ObjectOutputStream).

Throws:
IOException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Tie

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.rmi.CORBA
Interface Tie

All Superinterfaces:
InvokeHandler
public interface Tie
extends InvokeHandler

Defines methods which all RMI-IIOP server side ties must implement.

Method Summary
void | deactivate() Deactivates the target object represented by this tie.
Remote | getTarget() Returns the target for this tie.
ORB | orb() Returns the ORB for this tie.
void | orb(ORB orb) Sets the ORB for this tie.
void | setTarget(Remote target) Called by Util.registerTarget(javax.rmi.CORBA.Tie, java.rmi.Remote) to set the target for this tie.
Object | thisObject() Returns an object reference for the target object represented by this tie.
Methods inherited from interface org.omg.CORBA.portable.InvokeHandler
_invoke

Method Detail

thisObject

Object thisObject()
Returns an object reference for the target object represented by this tie.

Returns:
an object reference for the target object.

deactivate

void deactivate()
                throws NoSuchObjectException
Deactivates the target object represented by this tie.

Throws:
NoSuchObjectException

orb

ORB orb()
Returns the ORB for this tie.

Returns:
the ORB.

orb

void orb(ORB orb)
Sets the ORB for this tie.

Parameters:
orb - the ORB.

setTarget

void setTarget(Remote target)
Called by Util.registerTarget(javax.rmi.CORBA.Tie, java.rmi.Remote) to set the target for this tie.

Parameters:
target - the object to use as the target for this tie.

getTarget

Remote getTarget()
Returns the target for this tie.

Returns:
the target.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Util

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.rmi.CORBA
Class Util

java.lang.Object
    extended by  javax.rmi.CORBA.Util

public class Util
extends Object

Provides utility methods that can be used by stubs and ties to perform common operations.

Method Summary
static Object | copyObject(Object obj, ORB orb) Copies or connects an object.
static Object[] | copyObjects(Object[] obj, ORB orb) Copies or connects an array of objects.
static ValueHandler | createValueHandler() Returns a singleton instance of a class that implements the ValueHandler interface.
static String | getCodebase(Class clz) Returns the codebase, if any, for the given class.
static Tie | getTie(Remote target) Returns the tie (if any) for a given target object.
static boolean | isLocal(Stub stub) The isLocal method has the same semantics as the ObjectImpl._is_local method, except that it can throw a RemoteException.
static Class | loadClass(String className, String remoteCodebase, ClassLoader loader) Returns a class instance for the specified class.
static RemoteException | mapSystemException(SystemException ex) Maps a SystemException to a RemoteException.
static Object | readAny(InputStream in) Reads a java.lang.Object as a CORBA any.
static void | registerTarget(Tie tie, Remote target) Registers a target for a tie.
static void | unexportObject(Remote target) Removes the associated tie from an internal table and calls Tie.deactivate() to deactivate the object.
static RemoteException | wrapException(Throwable orig) Wraps an exception thrown by an implementation method.
static void | writeAbstractObject(OutputStream out, Object obj) Writes a java.lang.Object as either a value or a CORBA Object.
static void | writeAny(OutputStream out, Object obj) Writes any java.lang.Object as a CORBA any.
static void | writeRemoteObject(OutputStream out, Object obj) Writes a java.lang.Object as a CORBA Object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

mapSystemException

public static RemoteException mapSystemException(SystemException ex)
Maps a SystemException to a RemoteException.

Parameters:
ex - the SystemException to map.
Returns:
the mapped exception.

writeAny

public static void writeAny(OutputStream out,
                            Object obj)
Writes any java.lang.Object as a CORBA any.

Parameters:
out - the stream in which to write the any.
obj - the object to write as an any.

readAny

public static Object readAny(InputStream in)
Reads a java.lang.Object as a CORBA any.

Parameters:
in - the stream from which to read the any.
Returns:
the object read from the stream.

writeRemoteObject

public static void writeRemoteObject(OutputStream out,
                                     Object obj)
Writes a java.lang.Object as a CORBA Object. If obj is an exported RMI-IIOP server object, the tie is found and wired to obj, then written to out.write_Object(org.omg.CORBA.Object). If obj is a CORBA Object, it is written to out.write_Object(org.omg.CORBA.Object).

Parameters:
out - the stream in which to write the object.
obj - the object to write.

writeAbstractObject

public static void writeAbstractObject(OutputStream out,
                                       Object obj)
Writes a java.lang.Object as either a value or a CORBA Object. If obj is a value object or a stub object, it is written to out.write_abstract_interface(java.lang.Object). If obj is an exported RMI-IIOP server object, the tie is found and wired to obj, then written to out.write_abstract_interface(java.lang.Object).

Parameters:
out - the stream in which to write the object.
obj - the object to write.

registerTarget

public static void registerTarget(Tie tie,
                                  Remote target)
Registers a target for a tie. Adds the tie to an internal table and calls Tie.setTarget(java.rmi.Remote) on the tie object.

Parameters:
tie - the tie to register.
target - the target for the tie.

unexportObject

public static void unexportObject(Remote target)
                           throws NoSuchObjectException
Removes the associated tie from an internal table and calls Tie.deactivate() to deactivate the object.

Parameters:
target - the object to unexport.
Throws:
NoSuchObjectException

getTie

public static Tie getTie(Remote target)
Returns the tie (if any) for a given target object.

Returns:
the tie or null if no tie is registered for the given target.

createValueHandler

public static ValueHandler createValueHandler()
Returns a singleton instance of a class that implements the ValueHandler interface.

Returns:
a class which implements the ValueHandler interface.

getCodebase

public static String getCodebase(Class clz)
Returns the codebase, if any, for the given class.

Parameters:
clz - the class to get a codebase for.
Returns:
a space-separated list of URLs, or null.

loadClass

public static Class loadClass(String className,
                              String remoteCodebase,
                              ClassLoader loader)
                       throws ClassNotFoundException
Returns a class instance for the specified class.

The spec for this method is the "Java to IDL language mapping", ptc/00-01-06.

In Java SE Platform, this method works as follows:

  • Find the first non-null ClassLoader on the call stack and attempt to load the class using this ClassLoader.
  • If the first step fails, and if remoteCodebase is non-null and useCodebaseOnly is false, then call java.rmi.server.RMIClassLoader.loadClass(remoteCodebase, className).
  • If remoteCodebase is null or useCodebaseOnly is true, then call java.rmi.server.RMIClassLoader.loadClass(className).
  • If a class was not successfully loaded by step 1, 2, or 3, and loader is non-null, then call loader.loadClass(className).
  • If a class was successfully loaded by step 1, 2, 3, or 4, then return the loaded class, else throw ClassNotFoundException.

    Parameters:
    className - the name of the class.
    remoteCodebase - a space-separated list of URLs at which the class might be found. May be null.
    loader - a ClassLoader that may be used to load the class if all other methods fail.
    Returns:
    the Class object representing the loaded class.
    Throws:
    ClassNotFoundException - if class cannot be loaded.

isLocal

public static boolean isLocal(Stub stub)
                       throws RemoteException
The isLocal method has the same semantics as the ObjectImpl._is_local method, except that it can throw a RemoteException. The _is_local() method is provided so that stubs may determine if a particular object is implemented by a local servant and hence local invocation APIs may be used.

Parameters:
stub - the stub to test.
Returns:
The _is_local() method returns true if the servant incarnating the object is located in the same process as the stub and they both share the same ORB instance. The _is_local() method returns false otherwise. The default behavior of _is_local() is to return false.
Throws:
RemoteException - The Java to IDL specification does not specify the conditions that cause a RemoteException to be thrown.

wrapException

public static RemoteException wrapException(Throwable orig)
Wraps an exception thrown by an implementation method. It returns the corresponding client-side exception.

Parameters:
orig - the exception to wrap.
Returns:
the wrapped exception.

copyObjects

public static Object[] copyObjects(Object[] obj,
                                   ORB orb)
                            throws RemoteException
Copies or connects an array of objects. Used by local stubs to copy any number of actual parameters, preserving sharing across parameters as necessary to support RMI semantics.

Parameters:
obj - the objects to copy or connect.
orb - the ORB.
Returns:
the copied or connected objects.
Throws:
RemoteException - if any object could not be copied or connected.

copyObject

public static Object copyObject(Object obj,
                                ORB orb)
                         throws RemoteException
Copies or connects an object. Used by local stubs to copy an actual parameter, result object, or exception.

Parameters:
obj - the object to copy.
orb - the ORB.
Returns:
the copy or connected object.
Throws:
RemoteException - if the object could not be copied or connected.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UtilDelegate

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.rmi.CORBA
Interface UtilDelegate

public interface UtilDelegate

Supports delegation for method implementations in Util. The delegate is a singleton instance of a class that implements this interface and provides a replacement implementation for all the methods of javax.rmi.CORBA.Util. Delegation is enabled by providing the delegate's class name as the value of the javax.rmi.CORBA.UtilClass system property.

See Also:
Util

Method Summary
 Object copyObject(Object obj, ORB orb)
Delegation call for Util.copyObject(java.lang.Object, org.omg.CORBA.ORB).
 Object[] copyObjects(Object[] obj, ORB orb)
Delegation call for Util.copyObjects(java.lang.Object[], org.omg.CORBA.ORB).
 ValueHandler createValueHandler()
Delegation call for Util.createValueHandler().
 String getCodebase(Class clz)
Delegation call for Util.getCodebase(java.lang.Class).
 Tie getTie(Remote target)
Delegation call for Util.getTie(java.rmi.Remote).
 boolean isLocal(Stub stub)
Delegation call for Util.isLocal(javax.rmi.CORBA.Stub).
 Class loadClass(String className, String remoteCodebase, ClassLoader loader)
Delegation call for Util.loadClass(java.lang.String, java.lang.String, java.lang.ClassLoader).
 RemoteException mapSystemException(SystemException ex)
Delegation call for Util.mapSystemException(org.omg.CORBA.SystemException).
 Object readAny(InputStream in)
Delegation call for Util.readAny(org.omg.CORBA.portable.InputStream).
 void registerTarget(Tie tie, Remote target)
Delegation call for Util.registerTarget(javax.rmi.CORBA.Tie, java.rmi.Remote).
 void unexportObject(Remote target)
Delegation call for Util.unexportObject(java.rmi.Remote).
 RemoteException wrapException(Throwable obj)
Delegation call for Util.wrapException(java.lang.Throwable).
 void writeAbstractObject(OutputStream out, Object obj)
Delegation call for Util.writeAbstractObject(org.omg.CORBA.portable.OutputStream, java.lang.Object).
 void writeAny(OutputStream out, Object obj)
Delegation call for Util.writeAny(org.omg.CORBA.portable.OutputStream, java.lang.Object).
 void writeRemoteObject(OutputStream out, Object obj)
Delegation call for Util.writeRemoteObject(org.omg.CORBA.portable.OutputStream, java.lang.Object).

Method Detail

mapSystemException

RemoteException mapSystemException(SystemException ex)
Delegation call for Util.mapSystemException(org.omg.CORBA.SystemException).

writeAny

void writeAny(OutputStream out,
              Object obj)
Delegation call for Util.writeAny(org.omg.CORBA.portable.OutputStream, java.lang.Object).

readAny

Object readAny(InputStream in)
Delegation call for Util.readAny(org.omg.CORBA.portable.InputStream).

writeRemoteObject

void writeRemoteObject(OutputStream out,
                       Object obj)
Delegation call for Util.writeRemoteObject(org.omg.CORBA.portable.OutputStream, java.lang.Object).

writeAbstractObject

void writeAbstractObject(OutputStream out,
                         Object obj)
Delegation call for Util.writeAbstractObject(org.omg.CORBA.portable.OutputStream, java.lang.Object).

registerTarget

void registerTarget(Tie tie,
                    Remote target)
Delegation call for Util.registerTarget(javax.rmi.CORBA.Tie, java.rmi.Remote).

unexportObject

void unexportObject(Remote target)
                    throws NoSuchObjectException
Delegation call for Util.unexportObject(java.rmi.Remote).

Throws:
NoSuchObjectException

getTie

Tie getTie(Remote target)
Delegation call for Util.getTie(java.rmi.Remote).

createValueHandler

ValueHandler createValueHandler()
Delegation call for Util.createValueHandler().

getCodebase

String getCodebase(Class clz)
Delegation call for Util.getCodebase(java.lang.Class).

loadClass

Class loadClass(String className,
                String remoteCodebase,
                ClassLoader loader)
                throws ClassNotFoundException
Delegation call for Util.loadClass(java.lang.String, java.lang.String, java.lang.ClassLoader).

Throws:
ClassNotFoundException

isLocal

boolean isLocal(Stub stub)
                throws RemoteException
Delegation call for Util.isLocal(javax.rmi.CORBA.Stub).

Throws:
RemoteException

wrapException

RemoteException wrapException(Throwable obj)
Delegation call for Util.wrapException(java.lang.Throwable).

copyObject

Object copyObject(Object obj,
                  ORB orb)
                  throws RemoteException
Delegation call for Util.copyObject(java.lang.Object, org.omg.CORBA.ORB).

Throws:
RemoteException

copyObjects

Object[] copyObjects(Object[] obj,
                     ORB orb)
                     throws RemoteException
Delegation call for Util.copyObjects(java.lang.Object[], org.omg.CORBA.ORB).

Throws:
RemoteException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ValueHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.rmi.CORBA
Interface ValueHandler

All Known Subinterfaces:
ValueHandlerMultiFormat
public interface ValueHandler

Defines methods which allow serialization of Java objects to and from GIOP streams.

Method Summary
String | getRMIRepositoryID(Class clz) Returns the CORBA RepositoryId for the given Java class.
RunTime | getRunTimeCodeBase() Returns the CodeBase for this ValueHandler.
boolean | isCustomMarshaled(Class clz) Indicates whether the given class performs custom or default marshaling.
Serializable | readValue(InputStream in, int offset, Class clz, String repositoryID, RunTime sender) Reads a value from the stream using Java semantics.
Serializable | writeReplace(Serializable value) If the value contains a writeReplace method then the result is returned.
void | writeValue(OutputStream out, Serializable value) Writes a value to the stream using Java semantics.

Method Detail

writeValue

void writeValue(OutputStream out,
                Serializable value)
Writes a value to the stream using Java semantics.

Parameters:
out - the stream to write the value to.
value - the value to be written to the stream.

readValue

Serializable readValue(InputStream in,
                       int offset,
                       Class clz,
                       String repositoryID,
                       RunTime sender)
Reads a value from the stream using Java semantics.

Parameters:
in - the stream to read the value from.
offset - the current position in the input stream.
clz - the type of the value to be read in.
repositoryID - the RepositoryId of the value to be read in.
sender - the sending context runtime codebase.
Returns:
the value read from the stream.

getRMIRepositoryID

String getRMIRepositoryID(Class clz)
Returns the CORBA RepositoryId for the given Java class.

Parameters:
clz - a Java class.
Returns:
the CORBA RepositoryId for the class.

isCustomMarshaled

boolean isCustomMarshaled(Class clz)
Indicates whether the given class performs custom or default marshaling.

Parameters:
clz - the class to test for custom marshaling.
Returns:
true if the class performs custom marshaling, false if it does not.

getRunTimeCodeBase

RunTime getRunTimeCodeBase()
Returns the CodeBase for this ValueHandler. This is used by the ORB runtime. The server sends the service context containing the IOR for this CodeBase on the first GIOP reply. The client does the same on the first GIOP request.

Returns:
the SendingContext.CodeBase of this ValueHandler.

writeReplace

Serializable writeReplace(Serializable value)
If the value contains a writeReplace method then the result is returned. Otherwise, the value itself is returned.

Parameters:
value - the value to be marshaled.
Returns:
the true value to marshal on the wire.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ValueHandlerMultiFormat

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.rmi.CORBA
Interface ValueHandlerMultiFormat

All Superinterfaces:
ValueHandler
public interface ValueHandlerMultiFormat
extends ValueHandler

Java to IDL ptc 02-01-12 1.5.1.5

Since:
1.5

Method Summary
byte | getMaximumStreamFormatVersion() Returns the maximum stream format version for RMI/IDL custom value types that is supported by this ValueHandler object.
void | writeValue(OutputStream out, Serializable value, byte streamFormatVersion) Allows the ORB to pass the stream format version for RMI/IDL custom value types.
Methods inherited from interface javax.rmi.CORBA.ValueHandler
getRMIRepositoryID, getRunTimeCodeBase, isCustomMarshaled, readValue, writeReplace, writeValue

Method Detail

getMaximumStreamFormatVersion

byte getMaximumStreamFormatVersion()
Returns the maximum stream format version for RMI/IDL custom value types that is supported by this ValueHandler object. The ValueHandler object must support the returned stream format version and all lower versions. An ORB may use this value to include in a standard IOR tagged component or service context to indicate to other ORBs the maximum RMI-IIOP stream format that it supports. If not included, the default for GIOP 1.2 is stream format version 1, and stream format version 2 for GIOP 1.3 and higher.

writeValue

void writeValue(OutputStream out,
                Serializable value,
                byte streamFormatVersion)
Allows the ORB to pass the stream format version for RMI/IDL custom value types. If the ORB calls this method, it must pass a stream format version between 1 and the value returned by the getMaximumStreamFormatVersion method inclusive, or else a BAD_PARAM exception with standard minor code will be thrown. If the ORB calls the older ValueHandler.writeValue(OutputStream, Serializable) method, stream format version 1 is implied. The ORB output stream passed to the ValueHandlerMultiFormat.writeValue method must implement the ValueOutputStream interface, and the ORB input stream passed to the ValueHandler.readValue method must implement the ValueInputStream interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


PortableRemoteObject

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.rmi
Class PortableRemoteObject

java.lang.Object
    extended by  javax.rmi.PortableRemoteObject

public class PortableRemoteObject
extends Object

Server implementation objects may either inherit from javax.rmi.PortableRemoteObject or they may implement a remote interface and then use the exportObject method to register themselves as a server object. The toStub method takes a server implementation and returns a stub that can be used to access that server object. The connect method makes a Remote object ready for remote communication. The unexportObject method is used to deregister a server object, allowing it to become available for garbage collection. The narrow method takes an object reference or abstract interface type and attempts to narrow it to conform to the given interface. If the operation is successful the result will be an object of the specified type, otherwise an exception will be thrown.

Constructor Summary
protected PortableRemoteObject()
Initializes the object by calling exportObject(this).
Method Summary
static void | connect(Remote target, Remote source) Makes a Remote object ready for remote communication.
static void | exportObject(Remote obj) Makes a server object ready to receive remote calls.
static Object | narrow(Object narrowFrom, Class narrowTo) Checks to ensure that an object of a remote or abstract interface type can be cast to a desired type.
static Remote | toStub(Remote obj) Returns a stub for the given server object.
static void | unexportObject(Remote obj) Deregisters a server object from the runtime, allowing the object to become available for garbage collection.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PortableRemoteObject

protected PortableRemoteObject()
                        throws RemoteException
Initializes the object by calling exportObject(this).

Throws:
RemoteException - if export fails.
Method Detail

exportObject

public static void exportObject(Remote obj)
                         throws RemoteException
Makes a server object ready to receive remote calls. Note that subclasses of PortableRemoteObject do not need to call this method, as it is called by the constructor.

Parameters:
obj - the server object to export.
Throws:
RemoteException - if export fails.

toStub

public static Remote toStub(Remote obj)
                     throws NoSuchObjectException
Returns a stub for the given server object.

Parameters:
obj - the server object for which a stub is required. Must either be a subclass of PortableRemoteObject or have been previously the target of a call to exportObject(java.rmi.Remote).
Returns:
the most derived stub for the object.
Throws:
NoSuchObjectException - if a stub cannot be located for the given server object.

unexportObject

public static void unexportObject(Remote obj)
                           throws NoSuchObjectException
Deregisters a server object from the runtime, allowing the object to become available for garbage collection.

Parameters:
obj - the object to unexport.
Throws:
NoSuchObjectException - if the remote object is not currently exported.

narrow

public static Object narrow(Object narrowFrom,
                            Class narrowTo)
                     throws ClassCastException
Checks to ensure that an object of a remote or abstract interface type can be cast to a desired type.

Parameters:
narrowFrom - the object to check.
narrowTo - the desired type.
Returns:
an object which can be cast to the desired type.
Throws:
ClassCastException - if narrowFrom cannot be cast to narrowTo.

connect

public static void connect(Remote target,
                           Remote source)
                    throws RemoteException
Makes a Remote object ready for remote communication. This normally happens implicitly when the object is sent or received as an argument on a remote method call, but in some circumstances it is useful to perform this action by making an explicit call. See the Stub#connect method for more information.

Parameters:
target - the object to connect.
source - a previously connected object.
Throws:
RemoteException - if source is not connected or if target is already connected to a different ORB than source.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


ssl

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.rmi.ssl

Provides implementations of RMIClientSocketFactory and RMIServerSocketFactory over the Secure Sockets Layer (SSL) or Transport Layer Security (TLS) protocols.

See:
Description

Class Summary
SslRMIClientSocketFactory | An SslRMIClientSocketFactory instance is used by the RMI runtime in order to obtain client sockets for RMI calls via SSL.
SslRMIServerSocketFactory | An SslRMIServerSocketFactory instance is used by the RMI runtime in order to obtain server sockets for RMI calls via SSL.

Package javax.rmi.ssl Description

Provides implementations of RMIClientSocketFactory and RMIServerSocketFactory over the Secure Sockets Layer (SSL) or Transport Layer Security (TLS) protocols.

Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.rmi.ssl Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.rmi.ssl

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.rmi.ssl.SslRMIClientSocketFactory (implements java.rmi.server.RMIClientSocketFactory, java.io.Serializable)
    • javax.rmi.ssl.SslRMIServerSocketFactory (implements java.rmi.server.RMIServerSocketFactory)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.rmi.ssl

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.rmi.ssl

No usage of javax.rmi.ssl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.rmi.ssl.SslRMIClientSocketFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.rmi.ssl.SslRMIClientSocketFactory

No usage of javax.rmi.ssl.SslRMIClientSocketFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.rmi.ssl.SslRMIServerSocketFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.rmi.ssl.SslRMIServerSocketFactory

No usage of javax.rmi.ssl.SslRMIServerSocketFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


SslRMIClientSocketFactory

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.rmi.ssl
Class SslRMIClientSocketFactory

java.lang.Object
    extended by  javax.rmi.ssl.SslRMIClientSocketFactory
All Implemented Interfaces:
Serializable, RMIClientSocketFactory
public class SslRMIClientSocketFactory
extends Object
implements RMIClientSocketFactory, Serializable

An SslRMIClientSocketFactory instance is used by the RMI runtime in order to obtain client sockets for RMI calls via SSL.

This class implements RMIClientSocketFactory over the Secure Sockets Layer (SSL) or Transport Layer Security (TLS) protocols.

This class creates SSL sockets using the default SSLSocketFactory (see SSLSocketFactory.getDefault()). All instances of this class are functionally equivalent. In particular, they all share the same truststore, and the same keystore when client authentication is required by the server. This behavior can be modified in subclasses by overriding the createSocket(String,int) method; in that case, equals and hashCode may also need to be overridden.

If the system property javax.rmi.ssl.client.enabledCipherSuites is specified, the createSocket(String,int) method will call SSLSocket.setEnabledCipherSuites(String[]) before returning the socket. The value of this system property is a string that is a comma-separated list of SSL/TLS cipher suites to enable.

If the system property javax.rmi.ssl.client.enabledProtocols is specified, the createSocket(String,int) method will call SSLSocket.setEnabledProtocols(String[]) before returning the socket. The value of this system property is a string that is a comma-separated list of SSL/TLS protocol versions to enable.

Since:
1.5
See Also:
SSLSocketFactory, SslRMIServerSocketFactory, Serialized Form

Constructor Summary
SslRMIClientSocketFactory()
Creates a new SslRMIClientSocketFactory.
Method Summary
Socket | createSocket(String host, int port) Creates an SSL socket.
boolean | equals(Object obj) Indicates whether some other object is "equal to" this one.
int | hashCode() Returns a hash code value for this SslRMIClientSocketFactory.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SslRMIClientSocketFactory

public SslRMIClientSocketFactory()

Creates a new SslRMIClientSocketFactory.

Method Detail

createSocket

public Socket createSocket(String host,
                           int port)
                    throws IOException

Creates an SSL socket.

If the system property javax.rmi.ssl.client.enabledCipherSuites is specified, this method will call SSLSocket.setEnabledCipherSuites(String[]) before returning the socket. The value of this system property is a string that is a comma-separated list of SSL/TLS cipher suites to enable.

If the system property javax.rmi.ssl.client.enabledProtocols is specified, this method will call SSLSocket.setEnabledProtocols(String[]) before returning the socket. The value of this system property is a string that is a comma-separated list of SSL/TLS protocol versions to enable.

Specified by:
createSocket in interface RMIClientSocketFactory
Parameters:
host - the host name
port - the port number
Returns:
a socket connected to the specified host and port.
Throws:
IOException - if an I/O error occurs during socket creation

equals

public boolean equals(Object obj)

Indicates whether some other object is "equal to" this one.

Because all instances of this class are functionally equivalent (they all use the default SSLSocketFactory), this method simply returns this.getClass().equals(obj.getClass()).

A subclass should override this method (as well as hashCode()) if its instances are not all functionally equivalent.

Overrides:
equals in class Object
Parameters:
obj - the reference object with which to compare.
Returns:
true if this object is the same as the obj argument; false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()

Returns a hash code value for this SslRMIClientSocketFactory.

Overrides:
hashCode in class Object
Returns:
a hash code value for this SslRMIClientSocketFactory.
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


SslRMIServerSocketFactory

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.rmi.ssl
Class SslRMIServerSocketFactory

java.lang.Object
    extended by  javax.rmi.ssl.SslRMIServerSocketFactory
All Implemented Interfaces:
RMIServerSocketFactory
public class SslRMIServerSocketFactory
extends Object
implements RMIServerSocketFactory

An SslRMIServerSocketFactory instance is used by the RMI runtime in order to obtain server sockets for RMI calls via SSL.

This class implements RMIServerSocketFactory over the Secure Sockets Layer (SSL) or Transport Layer Security (TLS) protocols.

This class creates SSL sockets using the default SSLSocketFactory (see SSLSocketFactory.getDefault()) or the default SSLServerSocketFactory (see SSLServerSocketFactory.getDefault()). Therefore, all instances of this class share the same keystore, and the same truststore, when client authentication is required by the server. This behavior can be modified in subclasses by overriding the createServerSocket(int) method; in that case, equals and hashCode may also need to be overridden.

Since:
1.5
See Also:
SSLSocketFactory, SSLServerSocketFactory, SslRMIClientSocketFactory

Constructor Summary
SslRMIServerSocketFactory()
Creates a new SslRMIServerSocketFactory with the default SSL socket configuration.
SslRMIServerSocketFactory(String[] enabledCipherSuites, String[] enabledProtocols, boolean needClientAuth)
Creates a new SslRMIServerSocketFactory with the specified SSL socket configuration.
Method Summary
ServerSocket | createServerSocket(int port) Creates a server socket that accepts SSL connections configured according to this factory's SSL socket configuration parameters.
boolean | equals(Object obj) Indicates whether some other object is "equal to" this one.
String[] | getEnabledCipherSuites() Returns the names of the cipher suites enabled on SSL connections accepted by server sockets created by this factory, or null if this factory uses the cipher suites that are enabled by default.
String[] | getEnabledProtocols() Returns the names of the protocol versions enabled on SSL connections accepted by server sockets created by this factory, or null if this factory uses the protocol versions that are enabled by default.
boolean | getNeedClientAuth() Returns true if client authentication is required on SSL connections accepted by server sockets created by this factory.
int | hashCode() Returns a hash code value for this SslRMIServerSocketFactory.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SslRMIServerSocketFactory

public SslRMIServerSocketFactory()

Creates a new SslRMIServerSocketFactory with the default SSL socket configuration.

SSL connections accepted by server sockets created by this factory have the default cipher suites and protocol versions enabled and do not require client authentication.

SslRMIServerSocketFactory

public SslRMIServerSocketFactory(String[] enabledCipherSuites,
                                 String[] enabledProtocols,
                                 boolean needClientAuth)
                          throws IllegalArgumentException

Creates a new SslRMIServerSocketFactory with the specified SSL socket configuration.

Parameters:
enabledCipherSuites - names of all the cipher suites to enable on SSL connections accepted by server sockets created by this factory, or null to use the cipher suites that are enabled by default
enabledProtocols - names of all the protocol versions to enable on SSL connections accepted by server sockets created by this factory, or null to use the protocol versions that are enabled by default
needClientAuth - true to require client authentication on SSL connections accepted by server sockets created by this factory; false to not require client authentication
Throws:
IllegalArgumentException - when one or more of the cipher suites named by the enabledCipherSuites parameter is not supported, when one or more of the protocols named by the enabledProtocols parameter is not supported or when a problem is encountered while trying to check if the supplied cipher suites and protocols to be enabled are supported.
See Also:
SSLSocket.setEnabledCipherSuites(java.lang.String[]),
SSLSocket.setEnabledProtocols(java.lang.String[]),
SSLSocket.setNeedClientAuth(boolean)
Method Detail

getEnabledCipherSuites

public final String[] getEnabledCipherSuites()

Returns the names of the cipher suites enabled on SSL connections accepted by server sockets created by this factory, or null if this factory uses the cipher suites that are enabled by default.

Returns:
an array of cipher suites enabled, or null
See Also:
SSLSocket.setEnabledCipherSuites(java.lang.String[])

getEnabledProtocols

public final String[] getEnabledProtocols()

Returns the names of the protocol versions enabled on SSL connections accepted by server sockets created by this factory, or null if this factory uses the protocol versions that are enabled by default.

Returns:
an array of protocol versions enabled, or null
See Also:
SSLSocket.setEnabledProtocols(java.lang.String[])

getNeedClientAuth

public final boolean getNeedClientAuth()

Returns true if client authentication is required on SSL connections accepted by server sockets created by this factory.

Returns:
true if client authentication is required
See Also:
SSLSocket.setNeedClientAuth(boolean)

createServerSocket

public ServerSocket createServerSocket(int port)
                                throws IOException

Creates a server socket that accepts SSL connections configured according to this factory's SSL socket configuration parameters.

Specified by:
createServerSocket in interface RMIServerSocketFactory
Parameters:
port - the port number
Returns:
the server socket on the specified port
Throws:
IOException - if an I/O error occurs during server socket creation

equals

public boolean equals(Object obj)

Indicates whether some other object is "equal to" this one.

Two SslRMIServerSocketFactory objects are equal if they have been constructed with the same SSL socket configuration parameters.

A subclass should override this method (as well as hashCode()) if it adds instance state that affects equality.

Overrides:
equals in class Object
Parameters:
obj - the reference object with which to compare.
Returns:
true if this object is the same as the obj argument; false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()

Returns a hash code value for this SslRMIServerSocketFactory.

Overrides:
hashCode in class Object
Returns:
a hash code value for this SslRMIServerSocketFactory.
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


script

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.script

The scripting API consists of interfaces and classes that define Java TM Scripting Engines and provides a framework for their use in Java applications.

See:
Description

Interface Summary
Bindings | A mapping of key/value pairs, all of whose keys are Strings.
Compilable | The optional interface implemented by ScriptEngines whose methods compile scripts to a form that can be executed repeatedly without recompilation.
Invocable | The optional interface implemented by ScriptEngines whose methods allow the invocation of procedures in scripts that have previously been executed.
ScriptContext | The interface whose implementing classes are used to connect Script Engines with objects, such as scoped Bindings, in hosting applications.
ScriptEngine | ScriptEngine is the fundamental interface whose methods must be fully functional in every implementation of this specification.
ScriptEngineFactory | ScriptEngineFactory is used to describe and instantiate ScriptEngines.

Class Summary
AbstractScriptEngine | Provides a standard implementation for several of the variants of the eval method.
CompiledScript | Extended by classes that store results of compilations.
ScriptEngineManager | The ScriptEngineManager implements a discovery and instantiation mechanism for ScriptEngine classes and also maintains a collection of key/value pairs storing state shared by all engines created by the Manager.
SimpleBindings | A simple implementation of Bindings backed by a HashMap or some other specified Map.
SimpleScriptContext | Simple implementation of ScriptContext.

Exception Summary
ScriptException The generic Exception class for the Scripting APIs.

Package javax.script Description

The scripting API consists of interfaces and classes that define Java TM Scripting Engines and provides a framework for their use in Java applications. This API is intended for use by application programmers who wish to execute programs written in scripting languages in their Java applications. The scripting language programs are usually provided by the end-users of the applications.

The main areas of functionality of javax.script package include

  1. Script execution: Scripts are streams of characters used as sources for programs executed by script engines. Script execution uses eval methods of ScriptEngine and methods of the Invocable interface.

  2. Binding: This facility allows Java objects to be exposed to script programs as named variables. Bindings and ScriptContext classes are used for this purpose.

  3. Compilation: This functionality allows the intermediate code generated by the front-end of a script engine to be stored and executed repeatedly. This benefits applications that execute the same script multiple times. These applications can gain efficiency since the engines' front-ends only need to execute once per script rather than once per script execution. Note that this functionality is optional and script engines may choose not to implement it. Callers need to check for availability of the Compilable interface using an instanceof check.

  4. Invocation: This functionality allows the reuse of intermediate code generated by a script engine's front-end. Whereas Compilation allows entire scripts represented by intermediate code to be re-executed, Invocation functionality allows individual procedures/methods in the scripts to be re-executed. As in the case with compilation, not all script engines are required to provide this facility. Caller has to check for Invocable availability.

  5. Script engine discovery and Metadata: Applications written to the Scripting API might have specific requirements on script engines. Some may require a specific scripting language and/or version while others may require a specific implementation engine and/or version. Script engines are packaged in a specified way so that engines can be discovered at runtime and queried for attributes. The Engine discovery mechanism is based on the Service discovery mechanism described in the Jar File Specification. Script engine implementing classes are packaged in jar files that include a text resource named META-INF/services/javax.script.ScriptEngineFactory. This resource must include a line for each ScriptEngineFactory that is packaged in the jar file. ScriptEngineManager includes getEngineFactories method to get all ScriptEngineFactory instances discovered using this mechanism. ScriptEngineFactory has methods to query attributes about script engine.

Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.script Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.script

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.script.AbstractScriptEngine (implements javax.script.ScriptEngine)
    • javax.script.CompiledScript
    • javax.script.ScriptEngineManager
    • javax.script.SimpleBindings (implements javax.script.Bindings)
    • javax.script.SimpleScriptContext (implements javax.script.ScriptContext)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.script.ScriptException

Interface Hierarchy

  • javax.script.Compilable
  • javax.script.Invocable
  • java.util.Map<K,V>
    • javax.script.Bindings
  • javax.script.ScriptContext
  • javax.script.ScriptEngine
  • javax.script.ScriptEngineFactory
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.script

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.script

Packages that use javax.script
javax.script The scripting API consists of interfaces and classes that define Java TM Scripting Engines and provides a framework for their use in Java applications.

Classes in javax.script used by javax.script
Bindings
A mapping of key/value pairs, all of whose keys are Strings.
CompiledScript
Extended by classes that store results of compilations.
ScriptContext
The interface whose implementing classes are used to connect Script Engines with objects, such as scoped Bindings, in hosting applications.
ScriptEngine
ScriptEngine is the fundamental interface whose methods must be fully functional in every implementation of this specification.
ScriptEngineFactory
ScriptEngineFactory is used to describe and instantiate ScriptEngines.
ScriptException
The generic Exception class for the Scripting APIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AbstractScriptEngine

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.script
Class AbstractScriptEngine

java.lang.Object
    extended by  javax.script.AbstractScriptEngine
All Implemented Interfaces:
ScriptEngine
public abstract class AbstractScriptEngine
extends Object
implements ScriptEngine

Provides a standard implementation for several of the variants of the eval method.

eval(Reader)

eval(String)

eval(String, Bindings)

eval(Reader, Bindings)

are implemented using the abstract methods

eval(Reader,ScriptContext) or eval(String, ScriptContext)

with a SimpleScriptContext.

A SimpleScriptContext is used as the default ScriptContext of the AbstractScriptEngine..

Since:
1.6

Field Summary
protected  ScriptContext context
The default ScriptContext of this AbstractScriptEngine.
Fields inherited from interface javax.script.ScriptEngine
ARGV, ENGINE, ENGINE_VERSION, FILENAME, LANGUAGE, LANGUAGE_VERSION, NAME
Constructor Summary
AbstractScriptEngine()
Creates a new instance of AbstractScriptEngine using a SimpleScriptContext as its default ScriptContext.
AbstractScriptEngine(Bindings n)
Creates a new instance using the specified Bindings as the ENGINE_SCOPE Bindings in the protected context field.
Method Summary
 Object eval(Reader reader)
eval(Reader) calls the abstract eval(Reader, ScriptContext) passing the value of the context field.
 Object eval(Reader reader, Bindings bindings)
eval(Reader, Bindings) calls the abstract eval(Reader, ScriptContext) method, passing it a ScriptContext whose Reader, Writers and Bindings for scopes other that ENGINE_SCOPE are identical to those members of the protected context field.
 Object eval(String script)
Same as eval(Reader) except that the abstract eval(String, ScriptContext) is used.
 Object eval(String script, Bindings bindings)
Same as eval(Reader, Bindings) except that the abstract eval(String, ScriptContext) is used.
 Object get(String key)
Gets the value for the specified key in the ENGINE_SCOPE of the protected context field.
 Bindings getBindings(int scope)
Returns the Bindings with the specified scope value in the protected context field.
 ScriptContext getContext()
Returns the value of the protected context field.
protected  ScriptContext getScriptContext(Bindings nn)
Returns a SimpleScriptContext.
 void put(String key, Object value)
Sets the specified value with the specified key in the ENGINE_SCOPE Bindings of the protected context field.
 void setBindings(Bindings bindings, int scope)
Sets the Bindings with the corresponding scope value in the context field.
 void setContext(ScriptContext ctxt)
Sets the value of the protected context field to the specified ScriptContext.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.script.ScriptEngine
createBindings, eval, eval, getFactory

Field Detail

context

protected ScriptContext context
The default ScriptContext of this AbstractScriptEngine.

Constructor Detail

AbstractScriptEngine

public AbstractScriptEngine()
Creates a new instance of AbstractScriptEngine using a SimpleScriptContext as its default ScriptContext.

AbstractScriptEngine

public AbstractScriptEngine(Bindings n)
Creates a new instance using the specified Bindings as the ENGINE_SCOPE Bindings in the protected context field.

Parameters:
n - The specified Bindings.
Throws:
NullPointerException - if n is null.
Method Detail

setContext

public void setContext(ScriptContext ctxt)
Sets the value of the protected context field to the specified ScriptContext.

Specified by:
setContext in interface ScriptEngine
Parameters:
ctxt - The specified ScriptContext.
Throws:
NullPointerException - if ctxt is null.

getContext

public ScriptContext getContext()
Returns the value of the protected context field.

Specified by:
getContext in interface ScriptEngine
Returns:
The value of the protected context field.

getBindings

public Bindings getBindings(int scope)
Returns the Bindings with the specified scope value in the protected context field.

Specified by:
getBindings in interface ScriptEngine
Parameters:
scope - The specified scope
Returns:
The corresponding Bindings.
Throws:
IllegalArgumentException - if the value of scope is invalid for the type the protected context field.

setBindings

public void setBindings(Bindings bindings,
                        int scope)
Sets the Bindings with the corresponding scope value in the context field.

Specified by:
setBindings in interface ScriptEngine
Parameters:
bindings - The specified Bindings.
scope - The specified scope.
Throws:
IllegalArgumentException - if the value of scope is invalid for the type the context field.
NullPointerException - if the bindings is null and the scope is ScriptContext.ENGINE_SCOPE

put

public void put(String key,
                Object value)
Sets the specified value with the specified key in the ENGINE_SCOPE Bindings of the protected context field.

Specified by:
put in interface ScriptEngine
Parameters:
key - The specified key.
value - The specified value.
Throws:
NullPointerException - if key is null.
IllegalArgumentException - if key is empty.

get

public Object get(String key)
Gets the value for the specified key in the ENGINE_SCOPE of the protected context field.

Specified by:
get in interface ScriptEngine
Parameters:
key - The key whose value is to be returned
Returns:
The value for the specified key.
Throws:
NullPointerException - if key is null.
IllegalArgumentException - if key is empty.

eval

public Object eval(Reader reader,
                   Bindings bindings)
            throws ScriptException
eval(Reader, Bindings) calls the abstract eval(Reader, ScriptContext) method, passing it a ScriptContext whose Reader, Writers and Bindings for scopes other that ENGINE_SCOPE are identical to those members of the protected context field. The specified Bindings is used instead of the ENGINE_SCOPE Bindings of the context field.

Specified by:
eval in interface ScriptEngine
Parameters:
reader - A Reader containing the source of the script.
bindings - A Bindings to use for the ENGINE_SCOPE while the script executes.
Returns:
The return value from eval(Reader, ScriptContext)
Throws:
ScriptException - if an error occurs in script.
NullPointerException - if any of the parameters is null.

eval

public Object eval(String script,
                   Bindings bindings)
            throws ScriptException
Same as eval(Reader, Bindings) except that the abstract eval(String, ScriptContext) is used.

Specified by:
eval in interface ScriptEngine
Parameters:
script - A String containing the source of the script.
bindings - A Bindings to use as the ENGINE_SCOPE while the script executes.
Returns:
The return value from eval(String, ScriptContext)
Throws:
ScriptException - if an error occurs in script.
NullPointerException - if any of the parameters is null.

eval

public Object eval(Reader reader)
            throws ScriptException
eval(Reader) calls the abstract eval(Reader, ScriptContext) passing the value of the context field.

Specified by:
eval in interface ScriptEngine
Parameters:
reader - A Reader containing the source of the script.
Returns:
The return value from eval(Reader, ScriptContext)
Throws:
ScriptException - if an error occurs in script.
NullPointerException - if any of the parameters is null.

eval

public Object eval(String script)
            throws ScriptException
Same as eval(Reader) except that the abstract eval(String, ScriptContext) is used.

Specified by:
eval in interface ScriptEngine
Parameters:
script - A String containing the source of the script.
Returns:
The return value from eval(String, ScriptContext)
Throws:
ScriptException - if an error occurrs in script.
NullPointerException - if any of the parameters is null.

getScriptContext

protected ScriptContext getScriptContext(Bindings nn)
Returns a SimpleScriptContext. The SimpleScriptContext:

  • Uses the specified Bindings for its ENGINE_SCOPE
  • Uses the Bindings returned by the abstract getGlobalScope method as its GLOBAL_SCOPE
  • Uses the Reader and Writer in the default ScriptContext of this ScriptEngine

A SimpleScriptContext returned by this method is used to implement eval methods using the abstract eval(Reader,Bindings) and eval(String,Bindings) versions.

Parameters:
nn - Bindings to use for the ENGINE_SCOPE
Returns:
The SimpleScriptContext
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Bindings

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.script
Interface Bindings

All Superinterfaces:
Map<String,Object>
All Known Implementing Classes:
SimpleBindings
public interface Bindings
extends Map<String,Object>

A mapping of key/value pairs, all of whose keys are Strings.

Since:
1.6

Nested Class Summary
Nested classes/interfaces inherited from interface java.util.Map
Map.Entry<K,V>
Method Summary
boolean | containsKey(Object key) Returns true if this map contains a mapping for the specified key.
Object | get(Object key) Returns the value to which this map maps the specified key.
Object | put(String name, Object value) Set a named value.
void | putAll(Map<? extends String,? extends Object> toMerge) Adds all the mappings in a given Map to this Bindings.
Object | remove(Object key) Removes the mapping for this key from this map if it is present (optional operation).
Methods inherited from interface java.util.Map
clear, containsValue, entrySet, equals, hashCode, isEmpty, keySet, size, values

Method Detail

put

Object put(String name,
           Object value)
Set a named value.

Specified by:
put in interface Map<String,Object>
Parameters:
name - The name associated with the value.
value - The value associated with the name.
Returns:
The value previously associated with the given name. Returns null if no value was previously associated with the name.
Throws:
NullPointerException - if the name is null.
IllegalArgumentException - if the name is empty String.

putAll

void putAll(Map<? extends String,? extends Object> toMerge)
Adds all the mappings in a given Map to this Bindings.

Specified by:
putAll in interface Map<String,Object>
Parameters:
toMerge - The Map to merge with this one.
Throws:
NullPointerException - if toMerge map is null or if some key in the map is null.
IllegalArgumentException - if some key in the map is an empty String.

containsKey

boolean containsKey(Object key)
Returns true if this map contains a mapping for the specified key. More formally, returns true if and only if this map contains a mapping for a key k such that (key==null ? k==null : key.equals(k)). (There can be at most one such mapping.)

Specified by:
containsKey in interface Map<String,Object>
Parameters:
key - key whose presence in this map is to be tested.
Returns:
true if this map contains a mapping for the specified key.
Throws:
NullPointerException - if key is null
ClassCastException - if key is not String
IllegalArgumentException - if key is empty String

get

Object get(Object key)
Returns the value to which this map maps the specified key. Returns null if the map contains no mapping for this key. A return value of null does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to null. The containsKey operation may be used to distinguish these two cases.

More formally, if this map contains a mapping from a key k to a value v such that (key==null ? k==null : key.equals(k)), then this method returns v; otherwise it returns null. (There can be at most one such mapping.)

Specified by:
get in interface Map<String,Object>
Parameters:
key - key whose associated value is to be returned.
Returns:
the value to which this map maps the specified key, or null if the map contains no mapping for this key.
Throws:
NullPointerException - if key is null
ClassCastException - if key is not String
IllegalArgumentException - if key is empty String

remove

Object remove(Object key)
Removes the mapping for this key from this map if it is present (optional operation). More formally, if this map contains a mapping from key k to value v such that (key==null ? k==null : key.equals(k)), that mapping is removed. (The map can contain at most one such mapping.)

Returns the value to which the map previously associated the key, or null if the map contained no mapping for this key. (A null return can also indicate that the map previously associated null with the specified key if the implementation supports null values.) The map will not contain a mapping for the specified key once the call returns.

Specified by:
remove in interface Map<String,Object>
Parameters:
key - key whose mapping is to be removed from the map.
Returns:
previous value associated with specified key, or null if there was no mapping for key.
Throws:
NullPointerException - if key is null
ClassCastException - if key is not String
IllegalArgumentException - if key is empty String
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.script.AbstractScriptEngine

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.script.AbstractScriptEngine

No usage of javax.script.AbstractScriptEngine

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.script.CompiledScript

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.script.CompiledScript

Packages that use CompiledScript
javax.script The scripting API consists of interfaces and classes that define Java TM Scripting Engines and provides a framework for their use in Java applications.

Uses of CompiledScript in javax.script

Methods in javax.script that return CompiledScript
CompiledScript | Compilable.compile(Reader script) Compiles the script (source read from Reader) for later execution.
CompiledScript | Compilable.compile(String script) Compiles the script (source represented as a String) for later execution.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.script.ScriptEngineManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.script.ScriptEngineManager

No usage of javax.script.ScriptEngineManager

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.script.ScriptException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.script.ScriptException

Packages that use ScriptException
javax.script The scripting API consists of interfaces and classes that define Java TM Scripting Engines and provides a framework for their use in Java applications.

Uses of ScriptException in javax.script

Methods in javax.script that throw ScriptException
 CompiledScript Compilable.compile(Reader script)
Compiles the script (source read from Reader) for later execution.
 CompiledScript Compilable.compile(String script)
Compiles the script (source represented as a String) for later execution.
 Object CompiledScript.eval()
Executes the program stored in the CompiledScript object.
 Object CompiledScript.eval(Bindings bindings)
Executes the program stored in the CompiledScript object using the supplied Bindings of attributes as the ENGINE_SCOPE of the associated ScriptEngine during script execution.
 Object ScriptEngine.eval(Reader reader)
Same as eval(String) except that the source of the script is provided as a Reader
 Object AbstractScriptEngine.eval(Reader reader)
eval(Reader) calls the abstract eval(Reader, ScriptContext) passing the value of the context field.
 Object ScriptEngine.eval(Reader reader, Bindings n)
Same as eval(String, Bindings) except that the source of the script is provided as a Reader.
 Object AbstractScriptEngine.eval(Reader reader, Bindings bindings)
eval(Reader, Bindings) calls the abstract eval(Reader, ScriptContext) method, passing it a ScriptContext whose Reader, Writers and Bindings for scopes other that ENGINE_SCOPE are identical to those members of the protected context field.
 Object ScriptEngine.eval(Reader reader, ScriptContext context)
Same as eval(String, ScriptContext) where the source of the script is read from a Reader.
abstract  Object CompiledScript.eval(ScriptContext context)
Executes the program stored in this CompiledScript object.
 Object ScriptEngine.eval(String script)
Executes the specified script.
 Object AbstractScriptEngine.eval(String script)
Same as eval(Reader) except that the abstract eval(String, ScriptContext) is used.
 Object ScriptEngine.eval(String script, Bindings n)
Executes the script using the Bindings argument as the ENGINE_SCOPE Bindings of the ScriptEngine during the script execution.
 Object AbstractScriptEngine.eval(String script, Bindings bindings)
Same as eval(Reader, Bindings) except that the abstract eval(String, ScriptContext) is used.
 Object ScriptEngine.eval(String script, ScriptContext context)
Causes the immediate execution of the script whose source is the String passed as the first argument.
 Object Invocable.invokeFunction(String name, Object... args)
Used to call top-level procedures and functions defined in scripts.
 Object Invocable.invokeMethod(Object thiz, String name, Object... args)
Calls a method on a script object compiled during a previous script execution, which is retained in the state of the ScriptEngine.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.script.SimpleBindings

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.script.SimpleBindings

No usage of javax.script.SimpleBindings

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.script.SimpleScriptContext

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.script.SimpleScriptContext

No usage of javax.script.SimpleScriptContext

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.script.Bindings

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.script.Bindings

Packages that use Bindings
javax.script The scripting API consists of interfaces and classes that define Java TM Scripting Engines and provides a framework for their use in Java applications.

Uses of Bindings in javax.script

Classes in javax.script that implement Bindings
 class SimpleBindings
A simple implementation of Bindings backed by a HashMap or some other specified Map.

Fields in javax.script declared as Bindings
protected Bindings | SimpleScriptContext.engineScope This is the engine scope bindings.
protected Bindings | SimpleScriptContext.globalScope This is the global scope bindings.

Methods in javax.script that return Bindings
Bindings | ScriptEngine.createBindings() Returns an uninitialized Bindings.
Bindings | ScriptEngineManager.getBindings() getBindings returns the value of the globalScope field.
Bindings | SimpleScriptContext.getBindings(int scope) Returns the value of the engineScope field if specified scope is ENGINE_SCOPE.
Bindings | ScriptContext.getBindings(int scope) Gets the Bindings associated with the given scope in this ScriptContext.
Bindings | ScriptEngine.getBindings(int scope) Returns a scope of named values.
Bindings | AbstractScriptEngine.getBindings(int scope) Returns the Bindings with the specified scope value in the protected context field.

Methods in javax.script with parameters of type Bindings
 Object CompiledScript.eval(Bindings bindings)
Executes the program stored in the CompiledScript object using the supplied Bindings of attributes as the ENGINE_SCOPE of the associated ScriptEngine during script execution.
 Object ScriptEngine.eval(Reader reader, Bindings n)
Same as eval(String, Bindings) except that the source of the script is provided as a Reader.
 Object AbstractScriptEngine.eval(Reader reader, Bindings bindings)
eval(Reader, Bindings) calls the abstract eval(Reader, ScriptContext) method, passing it a ScriptContext whose Reader, Writers and Bindings for scopes other that ENGINE_SCOPE are identical to those members of the protected context field.
 Object ScriptEngine.eval(String script, Bindings n)
Executes the script using the Bindings argument as the ENGINE_SCOPE Bindings of the ScriptEngine during the script execution.
 Object AbstractScriptEngine.eval(String script, Bindings bindings)
Same as eval(Reader, Bindings) except that the abstract eval(String, ScriptContext) is used.
protected  ScriptContext AbstractScriptEngine.getScriptContext(Bindings nn)
Returns a SimpleScriptContext.
 void ScriptEngineManager.setBindings(Bindings bindings)
setBindings stores the specified Bindings in the globalScope field.
 void SimpleScriptContext.setBindings(Bindings bindings, int scope)
Sets a Bindings of attributes for the given scope.
 void ScriptContext.setBindings(Bindings bindings, int scope)
Associates a Bindings instance with a particular scope in this ScriptContext.
 void ScriptEngine.setBindings(Bindings bindings, int scope)
Sets a scope of named values to be used by scripts.
 void AbstractScriptEngine.setBindings(Bindings bindings, int scope)
Sets the Bindings with the corresponding scope value in the context field.

Constructors in javax.script with parameters of type Bindings
AbstractScriptEngine(Bindings n)
Creates a new instance using the specified Bindings as the ENGINE_SCOPE Bindings in the protected context field.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.script.Compilable

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.script.Compilable

No usage of javax.script.Compilable

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.script.Invocable

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.script.Invocable

No usage of javax.script.Invocable

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.script.ScriptContext

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.script.ScriptContext

Packages that use ScriptContext
javax.script The scripting API consists of interfaces and classes that define Java TM Scripting Engines and provides a framework for their use in Java applications.

Uses of ScriptContext in javax.script

Classes in javax.script that implement ScriptContext
 class SimpleScriptContext
Simple implementation of ScriptContext.

Fields in javax.script declared as ScriptContext
protected  ScriptContext AbstractScriptEngine.context
The default ScriptContext of this AbstractScriptEngine.

Methods in javax.script that return ScriptContext
ScriptContext | ScriptEngine.getContext() Returns the default ScriptContext of the ScriptEngine whose Bindings, Reader and Writers are used for script executions when no ScriptContext is specified.
ScriptContext | AbstractScriptEngine.getContext() Returns the value of the protected context field.
protected ScriptContext | AbstractScriptEngine.getScriptContext(Bindings nn) Returns a SimpleScriptContext.

Methods in javax.script with parameters of type ScriptContext
 Object ScriptEngine.eval(Reader reader, ScriptContext context)
Same as eval(String, ScriptContext) where the source of the script is read from a Reader.
abstract  Object CompiledScript.eval(ScriptContext context)
Executes the program stored in this CompiledScript object.
 Object ScriptEngine.eval(String script, ScriptContext context)
Causes the immediate execution of the script whose source is the String passed as the first argument.
 void ScriptEngine.setContext(ScriptContext context)
Sets the default ScriptContext of the ScriptEngine whose Bindings, Reader and Writers are used for script executions when no ScriptContext is specified.
 void AbstractScriptEngine.setContext(ScriptContext ctxt)
Sets the value of the protected context field to the specified ScriptContext.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.script.ScriptEngine

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.script.ScriptEngine

Packages that use ScriptEngine
javax.script The scripting API consists of interfaces and classes that define Java TM Scripting Engines and provides a framework for their use in Java applications.

Uses of ScriptEngine in javax.script

Classes in javax.script that implement ScriptEngine
 class AbstractScriptEngine
Provides a standard implementation for several of the variants of the eval method.

Methods in javax.script that return ScriptEngine
abstract ScriptEngine | CompiledScript.getEngine() Returns the ScriptEngine wbose compile method created this CompiledScript.
ScriptEngine | ScriptEngineManager.getEngineByExtension(String extension) Look up and create a ScriptEngine for a given extension.
ScriptEngine | ScriptEngineManager.getEngineByMimeType(String mimeType) Look up and create a ScriptEngine for a given mime type.
ScriptEngine | ScriptEngineManager.getEngineByName(String shortName) Looks up and creates a ScriptEngine for a given name.
ScriptEngine | ScriptEngineFactory.getScriptEngine() Returns an instance of the ScriptEngine associated with this ScriptEngineFactory.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.script.ScriptEngineFactory

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.script.ScriptEngineFactory

Packages that use ScriptEngineFactory
javax.script The scripting API consists of interfaces and classes that define Java TM Scripting Engines and provides a framework for their use in Java applications.

Uses of ScriptEngineFactory in javax.script

Methods in javax.script that return ScriptEngineFactory
 ScriptEngineFactory ScriptEngine.getFactory()
Returns a ScriptEngineFactory for the class to which this ScriptEngine belongs.

Methods in javax.script that return types with arguments of type ScriptEngineFactory
 List<ScriptEngineFactory> ScriptEngineManager.getEngineFactories()
Returns an array whose elements are instances of all the ScriptEngineFactory classes found by the discovery mechanism.

Methods in javax.script with parameters of type ScriptEngineFactory
void | ScriptEngineManager.registerEngineExtension(String extension, ScriptEngineFactory factory) Registers a ScriptEngineFactory to handle an extension.
void | ScriptEngineManager.registerEngineMimeType(String type, ScriptEngineFactory factory) Registers a ScriptEngineFactory to handle a mime type.
void | ScriptEngineManager.registerEngineName(String name, ScriptEngineFactory factory) Registers a ScriptEngineFactory to handle a language name.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Compilable

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.script
Interface Compilable

public interface Compilable

The optional interface implemented by ScriptEngines whose methods compile scripts to a form that can be executed repeatedly without recompilation.

Since:
1.6

Method Summary
CompiledScript | compile(Reader script) Compiles the script (source read from Reader) for later execution.
CompiledScript | compile(String script) Compiles the script (source represented as a String) for later execution.

Method Detail

compile

CompiledScript compile(String script)
                       throws ScriptException
Compiles the script (source represented as a String) for later execution.

Parameters:
script - The source of the script, represented as a String.
Returns:
An subclass of CompiledScript to be executed later using one of the eval methods of CompiledScript.
Throws:
ScriptException - if compilation fails.
NullPointerException - if the argument is null.

compile

CompiledScript compile(Reader script)
                       throws ScriptException
Compiles the script (source read from Reader) for later execution. Functionality is identical to compile(String) other than the way in which the source is passed.

Parameters:
script - The reader from which the script source is obtained.
Returns:
An implementation of CompiledScript to be executed later using one of its eval methods of CompiledScript.
Throws:
ScriptException - if compilation fails.
NullPointerException - if argument is null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CompiledScript

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.script
Class CompiledScript

java.lang.Object
    extended by  javax.script.CompiledScript

public abstract class CompiledScript
extends Object

Extended by classes that store results of compilations. State might be stored in the form of Java classes, Java class files or scripting language opcodes. The script may be executed repeatedly without reparsing.

Each CompiledScript is associated with a ScriptEngine -- A call to an eval method of the CompiledScript causes the execution of the script by the ScriptEngine. Changes in the state of the ScriptEngine caused by execution of tne CompiledScript may visible during subsequent executions of scripts by the engine.

Since:
1.6

Constructor Summary
CompiledScript()
Method Summary
Object | eval() Executes the program stored in the CompiledScript object.
Object | eval(Bindings bindings) Executes the program stored in the CompiledScript object using the supplied Bindings of attributes as the ENGINE_SCOPE of the associated ScriptEngine during script execution.
abstract Object | eval(ScriptContext context) Executes the program stored in this CompiledScript object.
abstract ScriptEngine | getEngine() Returns the ScriptEngine wbose compile method created this CompiledScript.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CompiledScript

public CompiledScript()
Method Detail

eval

public abstract Object eval(ScriptContext context)
                     throws ScriptException
Executes the program stored in this CompiledScript object.

Parameters:
context - A ScriptContext that is used in the same way as the ScriptContext passed to the eval methods of ScriptEngine.
Returns:
The value returned by the script execution, if any. Should return null if no value is returned by the script execution.
Throws:
ScriptException - if an error occurs.
NullPointerException - if context is null.

eval

public Object eval(Bindings bindings)
            throws ScriptException
Executes the program stored in the CompiledScript object using the supplied Bindings of attributes as the ENGINE_SCOPE of the associated ScriptEngine during script execution. If bindings is null, then the effect of calling this method is same as that of eval(getEngine().getContext()).

. The GLOBAL_SCOPE Bindings, Reader and Writer associated with the default ScriptContext of the associated ScriptEngine are used.

Parameters:
bindings - The bindings of attributes used for the ENGINE_SCOPE.
Returns:
The return value from the script execution
Throws:
ScriptException - if an error occurs.

eval

public Object eval()
            throws ScriptException
Executes the program stored in the CompiledScript object. The default ScriptContext of the associated ScriptEngine is used. The effect of calling this method is same as that of eval(getEngine().getContext()).

Returns:
The return value from the script execution
Throws:
ScriptException - if an error occurs.

getEngine

public abstract ScriptEngine getEngine()
Returns the ScriptEngine wbose compile method created this CompiledScript. The CompiledScript will execute in this engine.

Returns:
The ScriptEngine that created this CompiledScript
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Invocable

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.script
Interface Invocable

public interface Invocable

The optional interface implemented by ScriptEngines whose methods allow the invocation of procedures in scripts that have previously been executed.

Since:
1.6

Method Summary
<T> T
getInterface(Class<T> clasz)
Returns an implementation of an interface using functions compiled in the interpreter.
<T> T
getInterface(Object thiz, Class<T> clasz)
Returns an implementation of an interface using member functions of a scripting object compiled in the interpreter.
 Object invokeFunction(String name, Object... args)
Used to call top-level procedures and functions defined in scripts.
 Object invokeMethod(Object thiz, String name, Object... args)
Calls a method on a script object compiled during a previous script execution, which is retained in the state of the ScriptEngine.

Method Detail

invokeMethod

Object invokeMethod(Object thiz,
                    String name,
                    Object... args)
                    throws ScriptException,
                           NoSuchMethodException
Calls a method on a script object compiled during a previous script execution, which is retained in the state of the ScriptEngine.

Parameters:
name - The name of the procedure to be called.
thiz - If the procedure is a member of a class defined in the script and thiz is an instance of that class returned by a previous execution or invocation, the named method is called through that instance.
args - Arguments to pass to the procedure. The rules for converting the arguments to scripting variables are implementation-specific.
Returns:
The value returned by the procedure. The rules for converting the scripting variable returned by the script method to a Java Object are implementation-specific.
Throws:
ScriptException - if an error occurrs during invocation of the method.
NoSuchMethodException - if method with given name or matching argument types cannot be found.
NullPointerException - if the method name is null.
IllegalArgumentException - if the specified thiz is null or the specified Object is does not represent a scripting object.

invokeFunction

Object invokeFunction(String name,
                      Object... args)
                      throws ScriptException,
                             NoSuchMethodException
Used to call top-level procedures and functions defined in scripts.

Parameters:
args - Arguments to pass to the procedure or function
Returns:
The value returned by the procedure or function
Throws:
ScriptException - if an error occurrs during invocation of the method.
NoSuchMethodException - if method with given name or matching argument types cannot be found.
NullPointerException - if method name is null.

getInterface

<T> T getInterface(Class<T> clasz)
Returns an implementation of an interface using functions compiled in the interpreter. The methods of the interface may be implemented using the invokeFunction method.

Parameters:
clasz - The Class object of the interface to return.
Returns:
An instance of requested interface - null if the requested interface is unavailable, i. e. if compiled functions in the ScriptEngine cannot be found matching the ones in the requested interface.
Throws:
IllegalArgumentException - if the specified Class object is null or is not an interface.

getInterface

<T> T getInterface(Object thiz,
                   Class<T> clasz)
Returns an implementation of an interface using member functions of a scripting object compiled in the interpreter. The methods of the interface may be implemented using the invokeMethod method.

Parameters:
thiz - The scripting object whose member functions are used to implement the methods of the interface.
clasz - The Class object of the interface to return.
Returns:
An instance of requested interface - null if the requested interface is unavailable, i. e. if compiled methods in the ScriptEngine cannot be found matching the ones in the requested interface.
Throws:
IllegalArgumentException - if the specified Class object is null or is not an interface, or if the specified Object is null or does not represent a scripting object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ScriptContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.script
Interface ScriptContext

All Known Implementing Classes:
SimpleScriptContext
public interface ScriptContext

The interface whose implementing classes are used to connect Script Engines with objects, such as scoped Bindings, in hosting applications. Each scope is a set of named attributes whose values can be set and retrieved using the ScriptContext methods. ScriptContexts also expose Readers and Writers that can be used by the ScriptEngines for input and output.

Since:
1.6

Field Summary
static int | ENGINE_SCOPE EngineScope attributes are visible during the lifetime of a single ScriptEngine and a set of attributes is maintained for each engine.
static int | GLOBAL_SCOPE GlobalScope attributes are visible to all engines created by same ScriptEngineFactory.
Method Summary
Object | getAttribute(String name) Retrieves the value of the attribute with the given name in the scope occurring earliest in the search order.
Object | getAttribute(String name, int scope) Gets the value of an attribute in a given scope.
int | getAttributesScope(String name) Get the lowest scope in which an attribute is defined.
Bindings | getBindings(int scope) Gets the Bindings associated with the given scope in this ScriptContext.
Writer | getErrorWriter() Returns the Writer used to display error output.
Reader | getReader() Returns a Reader to be used by the script to read input.
List<Integer> | getScopes() Returns immutable List of all the valid values for scope in the ScriptContext.
Writer | getWriter() Returns the Writer for scripts to use when displaying output.
Object | removeAttribute(String name, int scope) Remove an attribute in a given scope.
void | setAttribute(String name, Object value, int scope) Sets the value of an attribute in a given scope.
void | setBindings(Bindings bindings, int scope) Associates a Bindings instance with a particular scope in this ScriptContext.
void | setErrorWriter(Writer writer) Sets the Writer used to display error output.
void | setReader(Reader reader) Sets the Reader for scripts to read input .
void | setWriter(Writer writer) Sets the Writer for scripts to use when displaying output.

Field Detail

ENGINE_SCOPE

static final int ENGINE_SCOPE
EngineScope attributes are visible during the lifetime of a single ScriptEngine and a set of attributes is maintained for each engine.

See Also:
Constant Field Values

GLOBAL_SCOPE

static final int GLOBAL_SCOPE
GlobalScope attributes are visible to all engines created by same ScriptEngineFactory.

See Also:
Constant Field Values
Method Detail

setBindings

void setBindings(Bindings bindings,
                 int scope)
Associates a Bindings instance with a particular scope in this ScriptContext. Calls to the getAttribute and setAttribute methods must map to the get and put methods of the Bindings for the specified scope.

Parameters:
bindings - The Bindings to associate with the given scope
scope - The scope
Throws:
IllegalArgumentException - If no Bindings is defined for the specified scope value in ScriptContexts of this type.
NullPointerException - if value of scope is ENGINE_SCOPE and the specified Bindings is null.

getBindings

Bindings getBindings(int scope)
Gets the Bindings associated with the given scope in this ScriptContext.

Returns:
The associated Bindings. Returns null if it has not been set.
Throws:
IllegalArgumentException - If no Bindings is defined for the specified scope value in ScriptContext of this type.

setAttribute

void setAttribute(String name,
                  Object value,
                  int scope)
Sets the value of an attribute in a given scope.

Parameters:
name - The name of the attribute to set
value - The value of the attribute
scope - The scope in which to set the attribute
Throws:
IllegalArgumentException - if the name is empty or if the scope is invalid.
NullPointerException - if the name is null.

getAttribute

Object getAttribute(String name,
                    int scope)
Gets the value of an attribute in a given scope.

Parameters:
name - The name of the attribute to retrieve.
scope - The scope in which to retrieve the attribute.
Returns:
The value of the attribute. Returns null is the name does not exist in the given scope.
Throws:
IllegalArgumentException - if the name is empty or if the value of scope is invalid.
NullPointerException - if the name is null.

removeAttribute

Object removeAttribute(String name,
                       int scope)
Remove an attribute in a given scope.

Parameters:
name - The name of the attribute to remove
scope - The scope in which to remove the attribute
Returns:
The removed value.
Throws:
IllegalArgumentException - if the name is empty or if the scope is invalid.
NullPointerException - if the name is null.

getAttribute

Object getAttribute(String name)
Retrieves the value of the attribute with the given name in the scope occurring earliest in the search order. The order is determined by the numeric value of the scope parameter (lowest scope values first.)

Parameters:
name - The name of the the attribute to retrieve.
Returns:
The value of the attribute in the lowest scope for which an attribute with the given name is defined. Returns null if no attribute with the name exists in any scope.
Throws:
NullPointerException - if the name is null.
IllegalArgumentException - if the name is empty.

getAttributesScope

int getAttributesScope(String name)
Get the lowest scope in which an attribute is defined.

Parameters:
name - Name of the attribute .
Returns:
The lowest scope. Returns -1 if no attribute with the given name is defined in any scope.
Throws:
NullPointerException - if name is null.
IllegalArgumentException - if name is empty.

getWriter

Writer getWriter()
Returns the Writer for scripts to use when displaying output.

Returns:
The Writer.

getErrorWriter

Writer getErrorWriter()
Returns the Writer used to display error output.

Returns:
The Writer

setWriter

void setWriter(Writer writer)
Sets the Writer for scripts to use when displaying output.

Parameters:
writer - The new Writer.

setErrorWriter

void setErrorWriter(Writer writer)
Sets the Writer used to display error output.

Parameters:
writer - The Writer.

getReader

Reader getReader()
Returns a Reader to be used by the script to read input.

Returns:
The Reader.

setReader

void setReader(Reader reader)
Sets the Reader for scripts to read input .

Parameters:
reader - The new Reader.

getScopes

List<Integer> getScopes()
Returns immutable List of all the valid values for scope in the ScriptContext.

Returns:
list of scope values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ScriptEngine

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.script
Interface ScriptEngine

All Known Implementing Classes:
AbstractScriptEngine
public interface ScriptEngine

ScriptEngine is the fundamental interface whose methods must be fully functional in every implementation of this specification.

These methods provide basic scripting functionality. Applications written to this simple interface are expected to work with minimal modifications in every implementation. It includes methods that execute scripts, and ones that set and get values.

The values are key/value pairs of two types. The first type of pairs consists of those whose keys are reserved and defined in this specification or by individual implementations. The values in the pairs with reserved keys have specified meanings.

The other type of pairs consists of those that create Java language Bindings, the values are usually represented in scripts by the corresponding keys or by decorated forms of them.

Since:
1.6

Field Summary
static String | ARGV Reserved key for a named value that passes an array of positional arguments to a script.
static String | ENGINE Reserved key for a named value that is the name of the ScriptEngine implementation.
static String | ENGINE_VERSION Reserved key for a named value that identifies the version of the ScriptEngine implementation.
static String | FILENAME Reserved key for a named value that is the name of the file being executed.
static String | LANGUAGE Reserved key for a named value that is the full name of Scripting Language supported by the implementation.
static String | LANGUAGE_VERSION Reserved key for the named value that identifies the version of the scripting language supported by the implementation.
static String | NAME Reserved key for a named value that identifies the short name of the scripting language.
Method Summary
 Bindings createBindings()
Returns an uninitialized Bindings.
 Object eval(Reader reader)
Same as eval(String) except that the source of the script is provided as a Reader
 Object eval(Reader reader, Bindings n)
Same as eval(String, Bindings) except that the source of the script is provided as a Reader.
 Object eval(Reader reader, ScriptContext context)
Same as eval(String, ScriptContext) where the source of the script is read from a Reader.
 Object eval(String script)
Executes the specified script.
 Object eval(String script, Bindings n)
Executes the script using the Bindings argument as the ENGINE_SCOPE Bindings of the ScriptEngine during the script execution.
 Object eval(String script, ScriptContext context)
Causes the immediate execution of the script whose source is the String passed as the first argument.
 Object get(String key)
Retrieves a value set in the state of this engine.
 Bindings getBindings(int scope)
Returns a scope of named values.
 ScriptContext getContext()
Returns the default ScriptContext of the ScriptEngine whose Bindings, Reader and Writers are used for script executions when no ScriptContext is specified.
 ScriptEngineFactory getFactory()
Returns a ScriptEngineFactory for the class to which this ScriptEngine belongs.
 void put(String key, Object value)
Sets a key/value pair in the state of the ScriptEngine that may either create a Java Language Binding to be used in the execution of scripts or be used in some other way, depending on whether the key is reserved.
 void setBindings(Bindings bindings, int scope)
Sets a scope of named values to be used by scripts.
 void setContext(ScriptContext context)
Sets the default ScriptContext of the ScriptEngine whose Bindings, Reader and Writers are used for script executions when no ScriptContext is specified.

Field Detail

ARGV

static final String ARGV
Reserved key for a named value that passes an array of positional arguments to a script.

See Also:
Constant Field Values

FILENAME

static final String FILENAME
Reserved key for a named value that is the name of the file being executed.

See Also:
Constant Field Values

ENGINE

static final String ENGINE
Reserved key for a named value that is the name of the ScriptEngine implementation.

See Also:
Constant Field Values

ENGINE_VERSION

static final String ENGINE_VERSION
Reserved key for a named value that identifies the version of the ScriptEngine implementation.

See Also:
Constant Field Values

NAME

static final String NAME
Reserved key for a named value that identifies the short name of the scripting language. The name is used by the ScriptEngineManager to locate a ScriptEngine with a given name in the getEngineByName method.

See Also:
Constant Field Values

LANGUAGE

static final String LANGUAGE
Reserved key for a named value that is the full name of Scripting Language supported by the implementation.

See Also:
Constant Field Values

LANGUAGE_VERSION

static final String LANGUAGE_VERSION
Reserved key for the named value that identifies the version of the scripting language supported by the implementation.

See Also:
Constant Field Values
Method Detail

eval

Object eval(String script,
            ScriptContext context)
            throws ScriptException
Causes the immediate execution of the script whose source is the String passed as the first argument. The script may be reparsed or recompiled before execution. State left in the engine from previous executions, including variable values and compiled procedures may be visible during this execution.

Parameters:
script - The script to be executed by the script engine.
context - A ScriptContext exposing sets of attributes in different scopes. The meanings of the scopes ScriptContext.GLOBAL_SCOPE, and ScriptContext.ENGINE_SCOPE are defined in the specification.

The ENGINE_SCOPE Bindings of the ScriptContext contains the bindings of scripting variables to application objects to be used during this script execution.
Returns:
The value returned from the execution of the script.
Throws:
ScriptException - if an error occurrs in script. ScriptEngines should create and throw ScriptException wrappers for checked Exceptions thrown by underlying scripting implementations.
NullPointerException - if either argument is null.

eval

Object eval(Reader reader,
            ScriptContext context)
            throws ScriptException
Same as eval(String, ScriptContext) where the source of the script is read from a Reader.

Parameters:
reader - The source of the script to be executed by the script engine.
context - The ScriptContext passed to the script engine.
Returns:
The value returned from the execution of the script.
Throws:
ScriptException - if an error occurrs in script.
NullPointerException - if either argument is null.

eval

Object eval(String script)
            throws ScriptException
Executes the specified script. The default ScriptContext for the ScriptEngine is used.

Parameters:
script - The script language source to be executed.
Returns:
The value returned from the execution of the script.
Throws:
ScriptException - if error occurrs in script.
NullPointerException - if the argument is null.

eval

Object eval(Reader reader)
            throws ScriptException
Same as eval(String) except that the source of the script is provided as a Reader

Parameters:
reader - The source of the script.
Returns:
The value returned by the script.
Throws:
ScriptException - if an error occurrs in script.
NullPointerException - if the argument is null.

eval

Object eval(String script,
            Bindings n)
            throws ScriptException
Executes the script using the Bindings argument as the ENGINE_SCOPE Bindings of the ScriptEngine during the script execution. The Reader, Writer and non-ENGINE_SCOPE Bindings of the default ScriptContext are used. The ENGINE_SCOPE Bindings of the ScriptEngine is not changed, and its mappings are unaltered by the script execution.

Parameters:
script - The source for the script.
n - The Bindings of attributes to be used for script execution.
Returns:
The value returned by the script.
Throws:
ScriptException - if an error occurrs in script.
NullPointerException - if either argument is null.

eval

Object eval(Reader reader,
            Bindings n)
            throws ScriptException
Same as eval(String, Bindings) except that the source of the script is provided as a Reader.

Parameters:
reader - The source of the script.
n - The Bindings of attributes.
Returns:
The value returned by the script.
Throws:
ScriptException - if an error occurrs.
NullPointerException - if either argument is null.

put

void put(String key,
         Object value)
Sets a key/value pair in the state of the ScriptEngine that may either create a Java Language Binding to be used in the execution of scripts or be used in some other way, depending on whether the key is reserved. Must have the same effect as getBindings(ScriptContext.ENGINE_SCOPE).put.

Parameters:
key - The name of named value to add
value - The value of named value to add.
Throws:
NullPointerException - if key is null.
IllegalArgumentException - if key is empty.

get

Object get(String key)
Retrieves a value set in the state of this engine. The value might be one which was set using setValue or some other value in the state of the ScriptEngine, depending on the implementation. Must have the same effect as getBindings(ScriptContext.ENGINE_SCOPE).get

Parameters:
key - The key whose value is to be returned
Returns:
the value for the given key
Throws:
NullPointerException - if key is null.
IllegalArgumentException - if key is empty.

getBindings

Bindings getBindings(int scope)
Returns a scope of named values. The possible scopes are:

  • ScriptContext.GLOBAL_SCOPE - The set of named values representing global scope. If this ScriptEngine is created by a ScriptEngineManager, then the manager sets global scope bindings. This may be null if no global scope is associated with this ScriptEngine
  • ScriptContext.ENGINE_SCOPE - The set of named values representing the state of this ScriptEngine. The values are generally visible in scripts using the associated keys as variable names.
  • Any other value of scope defined in the default ScriptContext of the ScriptEngine.

The Bindings instances that are returned must be identical to those returned by the getBindings method of ScriptContext called with corresponding arguments on the default ScriptContext of the ScriptEngine.

Parameters:
scope - Either ScriptContext.ENGINE_SCOPE or ScriptContext.GLOBAL_SCOPE which specifies the Bindings to return. Implementations of ScriptContext may define additional scopes. If the default ScriptContext of the ScriptEngine defines additional scopes, any of them can be passed to get the corresponding Bindings.
Returns:
The Bindings with the specified scope.
Throws:
IllegalArgumentException - if specified scope is invalid

setBindings

void setBindings(Bindings bindings,
                 int scope)
Sets a scope of named values to be used by scripts. The possible scopes are:

  • ScriptContext.ENGINE_SCOPE - The specified Bindings replaces the engine scope of the ScriptEngine.
  • ScriptContext.GLOBAL_SCOPE - The specified Bindings must be visible as the GLOBAL_SCOPE.
  • Any other value of scope defined in the default ScriptContext of the ScriptEngine.

The method must have the same effect as calling the setBindings method of ScriptContext with the corresponding value of scope on the default ScriptContext of the ScriptEngine.

Parameters:
bindings - The Bindings for the specified scope.
scope - The specified scope. Either ScriptContext.ENGINE_SCOPE, ScriptContext.GLOBAL_SCOPE, or any other valid value of scope.
Throws:
IllegalArgumentException - if the scope is invalid
NullPointerException - if the bindings is null and the scope is ScriptContext.ENGINE_SCOPE

createBindings

Bindings createBindings()
Returns an uninitialized Bindings.

Returns:
A Bindings that can be used to replace the state of this ScriptEngine.

getContext

ScriptContext getContext()
Returns the default ScriptContext of the ScriptEngine whose Bindings, Reader and Writers are used for script executions when no ScriptContext is specified.

Returns:
The default ScriptContext of the ScriptEngine.

setContext

void setContext(ScriptContext context)
Sets the default ScriptContext of the ScriptEngine whose Bindings, Reader and Writers are used for script executions when no ScriptContext is specified.

Parameters:
context - A ScriptContext that will replace the default ScriptContext in the ScriptEngine.
Throws:
NullPointerException - if context is null.

getFactory

ScriptEngineFactory getFactory()
Returns a ScriptEngineFactory for the class to which this ScriptEngine belongs.

Returns:
The ScriptEngineFactory
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ScriptEngineFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.script
Interface ScriptEngineFactory

public interface ScriptEngineFactory

ScriptEngineFactory is used to describe and instantiate ScriptEngines.

Each class implementing ScriptEngine has a corresponding factory that exposes metadata describing the engine class.

The ScriptEngineManager uses the service provider mechanism described in the Jar File Specification to obtain instances of all ScriptEngineFactories available in the current ClassLoader.

Since:
1.6

Method Summary
String | getEngineName() Returns the full name of the ScriptEngine.
String | getEngineVersion() Returns the version of the ScriptEngine.
List<String> | getExtensions() Returns an immutable list of filename extensions, which generally identify scripts written in the language supported by this ScriptEngine.
String | getLanguageName() Returns the name of the scripting langauge supported by this ScriptEngine.
String | getLanguageVersion() Returns the version of the scripting language supported by this ScriptEngine.
String | getMethodCallSyntax(String obj, String m, String... args) Returns a String which can be used to invoke a method of a Java object using the syntax of the supported scripting language.
List<String> | getMimeTypes() Returns an immutable list of mimetypes, associated with scripts that can be executed by the engine.
List<String> | getNames() Returns an immutable list of short names for the ScriptEngine, which may be used to identify the ScriptEngine by the ScriptEngineManager.
String | getOutputStatement(String toDisplay) Returns a String that can be used as a statement to display the specified String using the syntax of the supported scripting language.
Object | getParameter(String key) Returns the value of an attribute whose meaning may be implementation-specific.
String | getProgram(String... statements) Returns A valid scripting language executable progam with given statements.
ScriptEngine | getScriptEngine() Returns an instance of the ScriptEngine associated with this ScriptEngineFactory.

Method Detail

getEngineName

String getEngineName()
Returns the full name of the ScriptEngine. For instance an implementation based on the Mozilla Rhino Javascript engine might return Rhino Mozilla Javascript Engine.

Returns:
The name of the engine implementation.

getEngineVersion

String getEngineVersion()
Returns the version of the ScriptEngine.

Returns:
The ScriptEngine implementation version.

getExtensions

List<String> getExtensions()
Returns an immutable list of filename extensions, which generally identify scripts written in the language supported by this ScriptEngine. The array is used by the ScriptEngineManager to implement its getEngineByExtension method.

Returns:
The list of extensions.

getMimeTypes

List<String> getMimeTypes()
Returns an immutable list of mimetypes, associated with scripts that can be executed by the engine. The list is used by the ScriptEngineManager class to implement its getEngineByMimetype method.

Returns:
The list of mime types.

getNames

List<String> getNames()
Returns an immutable list of short names for the ScriptEngine, which may be used to identify the ScriptEngine by the ScriptEngineManager. For instance, an implementation based on the Mozilla Rhino Javascript engine might return list containing {"javascript", "rhino"}.

getLanguageName

String getLanguageName()
Returns the name of the scripting langauge supported by this ScriptEngine.

Returns:
The name of the supported language.

getLanguageVersion

String getLanguageVersion()
Returns the version of the scripting language supported by this ScriptEngine.

Returns:
The version of the supported language.

getParameter

Object getParameter(String key)
Returns the value of an attribute whose meaning may be implementation-specific. Keys for which the value is defined in all implementations are:
  • ScriptEngine.ENGINE
  • ScriptEngine.ENGINE_VERSION
  • ScriptEngine.NAME
  • ScriptEngine.LANGUAGE
  • ScriptEngine.LANGUAGE_VERSION

The values for these keys are the Strings returned by getEngineName, getEngineVersion, getName, getLanguageName and getLanguageVersion respectively.

A reserved key, THREADING, whose value describes the behavior of the engine with respect to concurrent execution of scripts and maintenance of state is also defined. These values for the THREADING key are:

    null - The engine implementation is not thread safe, and cannot be used to execute scripts concurrently on multiple threads.

    "MULTITHREADED" - The engine implementation is internally thread-safe and scripts may execute concurrently although effects of script execution on one thread may be visible to scripts on other threads.

    "THREAD-ISOLATED" - The implementation satisfies the requirements of "MULTITHREADED", and also, the engine maintains independent values for symbols in scripts executing on different threads.

    "STATELESS" - The implementation satisfies the requirements of "THREAD-ISOLATED". In addition, script executions do not alter the mappings in the Bindings which is the engine scope of the ScriptEngine. In particular, the keys in the Bindings and their associated values are the same before and after the execution of the script.

Implementations may define implementation-specific keys.

Parameters:
key - The name of the parameter
Returns:
The value for the given parameter. Returns null if no value is assigned to the key.

getMethodCallSyntax

String getMethodCallSyntax(String obj,
                           String m,
                           String... args)
Returns a String which can be used to invoke a method of a Java object using the syntax of the supported scripting language. For instance, an implementaton for a Javascript engine might be;

 public String getMethodCallSyntax(String obj,
                                   String m, String... args) {
      String ret = obj;
      ret += "." + m + "(";
      for (int i = 0; i < args.length; i++) {
          ret += args[i];
          if (i == args.length - 1) {
              ret += ")";
          } else {
              ret += ",";
          }
      }
      return ret;
 }

Parameters:
obj - The name representing the object whose method is to be invoked. The name is the one used to create bindings using the put method of ScriptEngine, the put method of an ENGINE_SCOPE Bindings,or the setAttribute method of ScriptContext. The identifier used in scripts may be a decorated form of the specified one.
m - The name of the method to invoke.
args - names of the arguments in the method call.
Returns:
The String used to invoke the method in the syntax of the scripting language.

getOutputStatement

String getOutputStatement(String toDisplay)
Returns a String that can be used as a statement to display the specified String using the syntax of the supported scripting language. For instance, the implementaton for a Perl engine might be;

 public String getOutputStatement(String toDisplay) {
      return "print(" + toDisplay + ")";
 }

Parameters:
toDisplay - The String to be displayed by the returned statement.
Returns:
The string used to display the String in the syntax of the scripting language.

getProgram

String getProgram(String... statements)
Returns A valid scripting language executable progam with given statements. For instance an implementation for a PHP engine might be:

 public String getProgram(String... statements) {
      $retval = "<?\n";
      int len = statements.length;
      for (int i = 0; i < len; i++) {
          $retval += statements[i] + ";\n";
      }
      $retval += "?>";

 }

Parameters:
statements - The statements to be executed. May be return values of calls to the getMethodCallSyntax and getOutputStatement methods.
Returns:
The Program

getScriptEngine

ScriptEngine getScriptEngine()
Returns an instance of the ScriptEngine associated with this ScriptEngineFactory. A new ScriptEngine is generally returned, but implementations may pool, share or reuse engines.

Returns:
A new ScriptEngine instance.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ScriptEngineManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.script
Class ScriptEngineManager

java.lang.Object
    extended by  javax.script.ScriptEngineManager

public class ScriptEngineManager
extends Object

The ScriptEngineManager implements a discovery and instantiation mechanism for ScriptEngine classes and also maintains a collection of key/value pairs storing state shared by all engines created by the Manager. This class uses the service provider mechanism to enumerate all the implementations of ScriptEngineFactory.

The ScriptEngineManager provides a method to return an array of all these factories as well as utility methods which look up factories on the basis of language name, file extension and mime type.

The Bindings of key/value pairs, referred to as the "Global Scope" maintained by the manager is available to all instances of ScriptEngine created by the ScriptEngineManager. The values in the Bindings are generally exposed in all scripts.

Since:
1.6

Constructor Summary
ScriptEngineManager()
If the thread context ClassLoader can be accessed by the caller, then the effect of calling this constructor is the same as calling ScriptEngineManager(Thread.currentThread().getContextClassLoader()).
ScriptEngineManager(ClassLoader loader)
This constructor loads the implementations of ScriptEngineFactory visible to the given ClassLoader using the service provider mechanism.

If loader is null, the script engine factories that are bundled with the platform and that are in the usual extension directories (installed extensions) are loaded.
Method Summary
Object | get(String key) Gets the value for the specified key in the Global Scope
Bindings | getBindings() getBindings returns the value of the globalScope field.
ScriptEngine | getEngineByExtension(String extension) Look up and create a ScriptEngine for a given extension.
ScriptEngine | getEngineByMimeType(String mimeType) Look up and create a ScriptEngine for a given mime type.
ScriptEngine | getEngineByName(String shortName) Looks up and creates a ScriptEngine for a given name.
List<ScriptEngineFactory> | getEngineFactories() Returns an array whose elements are instances of all the ScriptEngineFactory classes found by the discovery mechanism.
void | put(String key, Object value) Sets the specified key/value pair in the Global Scope.
void | registerEngineExtension(String extension, ScriptEngineFactory factory) Registers a ScriptEngineFactory to handle an extension.
void | registerEngineMimeType(String type, ScriptEngineFactory factory) Registers a ScriptEngineFactory to handle a mime type.
void | registerEngineName(String name, ScriptEngineFactory factory) Registers a ScriptEngineFactory to handle a language name.
void | setBindings(Bindings bindings) setBindings stores the specified Bindings in the globalScope field.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ScriptEngineManager

public ScriptEngineManager()
If the thread context ClassLoader can be accessed by the caller, then the effect of calling this constructor is the same as calling ScriptEngineManager(Thread.currentThread().getContextClassLoader()). Otherwise, the effect is the same as calling ScriptEngineManager(null).

See Also:
Thread.getContextClassLoader()

ScriptEngineManager

public ScriptEngineManager(ClassLoader loader)
This constructor loads the implementations of ScriptEngineFactory visible to the given ClassLoader using the service provider mechanism.

If loader is null, the script engine factories that are bundled with the platform and that are in the usual extension directories (installed extensions) are loaded.

Parameters:
loader - ClassLoader used to discover script engine factories.
Method Detail

setBindings

public void setBindings(Bindings bindings)
setBindings stores the specified Bindings in the globalScope field. ScriptEngineManager sets this Bindings as global bindings for ScriptEngine objects created by it.

Parameters:
bindings - The specified Bindings
Throws:
IllegalArgumentException - if bindings is null.

getBindings

public Bindings getBindings()
getBindings returns the value of the globalScope field. ScriptEngineManager sets this Bindings as global bindings for ScriptEngine objects created by it.

Returns:
The globalScope field.

put

public void put(String key,
                Object value)
Sets the specified key/value pair in the Global Scope.

Parameters:
key - Key to set
value - Value to set.
Throws:
NullPointerException - if key is null.
IllegalArgumentException - if key is empty string.

get

public Object get(String key)
Gets the value for the specified key in the Global Scope

Parameters:
key - The key whose value is to be returned.
Returns:
The value for the specified key.

getEngineByName

public ScriptEngine getEngineByName(String shortName)
Looks up and creates a ScriptEngine for a given name. The algorithm first searches for a ScriptEngineFactory that has been registered as a handler for the specified name using the registerEngineName method.

If one is not found, it searches the array of ScriptEngineFactory instances stored by the constructor for one with the specified name. If a ScriptEngineFactory is found by either method, it is used to create instance of ScriptEngine.

Parameters:
shortName - The short name of the ScriptEngine implementation. returned by the getNames method of its ScriptEngineFactory.
Returns:
A ScriptEngine created by the factory located in the search. Returns null if no such factory was found. The ScriptEngineManager sets its own globalScope Bindings as the GLOBAL_SCOPE Bindings of the newly created ScriptEngine.
Throws:
NullPointerException - if shortName is null.

getEngineByExtension

public ScriptEngine getEngineByExtension(String extension)
Look up and create a ScriptEngine for a given extension. The algorithm used by getEngineByName is used except that the search starts by looking for a ScriptEngineFactory registered to handle the given extension using registerEngineExtension.

Parameters:
extension - The given extension
Returns:
The engine to handle scripts with this extension. Returns null if not found.
Throws:
NullPointerException - if extension is null.

getEngineByMimeType

public ScriptEngine getEngineByMimeType(String mimeType)
Look up and create a ScriptEngine for a given mime type. The algorithm used by getEngineByName is used except that the search starts by looking for a ScriptEngineFactory registered to handle the given mime type using registerEngineMimeType.

Parameters:
mimeType - The given mime type
Returns:
The engine to handle scripts with this mime type. Returns null if not found.
Throws:
NullPointerException - if mimeType is null.

getEngineFactories

public List<ScriptEngineFactory> getEngineFactories()
Returns an array whose elements are instances of all the ScriptEngineFactory classes found by the discovery mechanism.

Returns:
List of all discovered ScriptEngineFactorys.

registerEngineName

public void registerEngineName(String name,
                               ScriptEngineFactory factory)
Registers a ScriptEngineFactory to handle a language name. Overrides any such association found using the Discovery mechanism.

Parameters:
name - The name to be associated with the ScriptEngineFactory.
factory - The class to associate with the given name.
Throws:
NullPointerException - if any of the parameters is null.

registerEngineMimeType

public void registerEngineMimeType(String type,
                                   ScriptEngineFactory factory)
Registers a ScriptEngineFactory to handle a mime type. Overrides any such association found using the Discovery mechanism.

Parameters:
type - The mime type to be associated with the ScriptEngineFactory.
factory - The class to associate with the given mime type.
Throws:
NullPointerException - if any of the parameters is null.

registerEngineExtension

public void registerEngineExtension(String extension,
                                    ScriptEngineFactory factory)
Registers a ScriptEngineFactory to handle an extension. Overrides any such association found using the Discovery mechanism.

Parameters:
extension - The extension type to be associated with the ScriptEngineFactory.
factory - The class to associate with the given extension.
Throws:
NullPointerException - if any of the parameters is null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ScriptException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.script
Class ScriptException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.script.ScriptException
All Implemented Interfaces:
Serializable
public class ScriptException
extends Exception

The generic Exception class for the Scripting APIs. Checked exception types thrown by underlying scripting implementations must be wrapped in instances of ScriptException. The class has members to store line and column numbers and filenames if this information is available.

Since:
1.6
See Also:
Serialized Form

Constructor Summary
ScriptException(Exception e)
Creates a ScriptException wrapping an Exception thrown by an underlying interpreter.
ScriptException(String s)
Creates a ScriptException with a String to be used in its message.
ScriptException(String message, String fileName, int lineNumber)
Creates a ScriptException with message, filename and linenumber to be used in error messages.
ScriptException(String message, String fileName, int lineNumber, int columnNumber)
ScriptException constructor specifying message, filename, line number and column number.
Method Summary
int | getColumnNumber() Get the column number on which an error occurred.
String | getFileName() Get the source of the script causing the error.
int | getLineNumber() Get the line number on which an error occurred.
String | getMessage() Returns a message containing the String passed to a constructor as well as line and column numbers and filename if any of these are known.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ScriptException

public ScriptException(String s)
Creates a ScriptException with a String to be used in its message. Filename, and line and column numbers are unspecified.

Parameters:
s - The String to use in the message.

ScriptException

public ScriptException(Exception e)
Creates a ScriptException wrapping an Exception thrown by an underlying interpreter. Line and column numbers and filename are unspecified.

Parameters:
e - The wrapped Exception.

ScriptException

public ScriptException(String message,
                       String fileName,
                       int lineNumber)
Creates a ScriptException with message, filename and linenumber to be used in error messages.

Parameters:
message - The string to use in the message
fileName - The file or resource name describing the location of a script error causing the ScriptException to be thrown.
lineNumber - A line number describing the location of a script error causing the ScriptException to be thrown.

ScriptException

public ScriptException(String message,
                       String fileName,
                       int lineNumber,
                       int columnNumber)
ScriptException constructor specifying message, filename, line number and column number.

Parameters:
message - The message.
fileName - The filename
lineNumber - the line number.
columnNumber - the column number.
Method Detail

getMessage

public String getMessage()
Returns a message containing the String passed to a constructor as well as line and column numbers and filename if any of these are known.

Overrides:
getMessage in class Throwable
Returns:
The error message.

getLineNumber

public int getLineNumber()
Get the line number on which an error occurred.

Returns:
The line number. Returns -1 if a line number is unavailable.

getColumnNumber

public int getColumnNumber()
Get the column number on which an error occurred.

Returns:
The column number. Returns -1 if a column number is unavailable.

getFileName

public String getFileName()
Get the source of the script causing the error.

Returns:
The file name of the script or some other string describing the script source. May return some implementation-defined string such as <unknown> if a description of the source is unavailable.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SimpleBindings

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.script
Class SimpleBindings

java.lang.Object
    extended by  javax.script.SimpleBindings
All Implemented Interfaces:
Map<String,Object>, Bindings
public class SimpleBindings
extends Object
implements Bindings

A simple implementation of Bindings backed by a HashMap or some other specified Map.

Since:
1.6

Nested Class Summary
Nested classes/interfaces inherited from interface java.util.Map
Map.Entry<K,V>
Constructor Summary
SimpleBindings()
Default constructor uses a HashMap.
SimpleBindings(Map<String,Object> m)
Constructor uses an existing Map to store the values.
Method Summary
void | clear() Removes all of the mappings from this map (optional operation).
boolean | containsKey(Object key) Returns true if this map contains a mapping for the specified key.
boolean | containsValue(Object value) Returns true if this map maps one or more keys to the specified value.
Set<Map.Entry<String,Object>> | entrySet() Returns a Set view of the mappings contained in this map.
Object | get(Object key) Returns the value to which this map maps the specified key.
boolean | isEmpty() Returns true if this map contains no key-value mappings.
Set<String> | keySet() Returns a Set view of the keys contained in this map.
Object | put(String name, Object value) Sets the specified key/value in the underlying map field.
void | putAll(Map<? extends String,? extends Object> toMerge) putAll is implemented using Map.putAll.
Object | remove(Object key) Removes the mapping for this key from this map if it is present (optional operation).
int | size() Returns the number of key-value mappings in this map.
Collection<Object> | values() Returns a Collection view of the values contained in this map.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface java.util.Map
equals, hashCode

Constructor Detail

SimpleBindings

public SimpleBindings(Map<String,Object> m)
Constructor uses an existing Map to store the values.

Parameters:
m - The Map backing this SimpleBindings.
Throws:
NullPointerException - if m is null

SimpleBindings

public SimpleBindings()
Default constructor uses a HashMap.

Method Detail

put

public Object put(String name,
                  Object value)
Sets the specified key/value in the underlying map field.

Specified by:
put in interface Map<String,Object>
Specified by:
put in interface Bindings
Parameters:
name - Name of value
value - Value to set.
Returns:
Previous value for the specified key. Returns null if key was previously unset.
Throws:
NullPointerException - if the name is null.
IllegalArgumentException - if the name is empty.

putAll

public void putAll(Map<? extends String,? extends Object> toMerge)
putAll is implemented using Map.putAll.

Specified by:
putAll in interface Map<String,Object>
Specified by:
putAll in interface Bindings
Parameters:
toMerge - The Map of values to add.
Throws:
NullPointerException - if toMerge map is null or if some key in the map is null.
IllegalArgumentException - if some key in the map is an empty String.

clear

public void clear()
Removes all of the mappings from this map (optional operation). The map will be empty after this call returns.

Specified by:
clear in interface Map<String,Object>

containsKey

public boolean containsKey(Object key)
Returns true if this map contains a mapping for the specified key. More formally, returns true if and only if this map contains a mapping for a key k such that (key==null ? k==null : key.equals(k)). (There can be at most one such mapping.)

Specified by:
containsKey in interface Map<String,Object>
Specified by:
containsKey in interface Bindings
Parameters:
key - key whose presence in this map is to be tested.
Returns:
true if this map contains a mapping for the specified key.
Throws:
NullPointerException - if key is null
ClassCastException - if key is not String
IllegalArgumentException - if key is empty String

containsValue

public boolean containsValue(Object value)
Returns true if this map maps one or more keys to the specified value. More formally, returns true if and only if this map contains at least one mapping to a value v such that (value==null ? v==null : value.equals(v)). This operation will probably require time linear in the map size for most implementations of the Map interface.

Specified by:
containsValue in interface Map<String,Object>
Parameters:
value - value whose presence in this map is to be tested
Returns:
true if this map maps one or more keys to the specified value

entrySet

public Set<Map.Entry<String,Object>> entrySet()
Returns a Set view of the mappings contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation, or through the setValue operation on a map entry returned by the iterator) the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Specified by:
entrySet in interface Map<String,Object>
Returns:
a set view of the mappings contained in this map

get

public Object get(Object key)
Returns the value to which this map maps the specified key. Returns null if the map contains no mapping for this key. A return value of null does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to null. The containsKey operation may be used to distinguish these two cases.

More formally, if this map contains a mapping from a key k to a value v such that (key==null ? k==null : key.equals(k)), then this method returns v; otherwise it returns null. (There can be at most one such mapping.)

Specified by:
get in interface Map<String,Object>
Specified by:
get in interface Bindings
Parameters:
key - key whose associated value is to be returned.
Returns:
the value to which this map maps the specified key, or null if the map contains no mapping for this key.
Throws:
NullPointerException - if key is null
ClassCastException - if key is not String
IllegalArgumentException - if key is empty String

isEmpty

public boolean isEmpty()
Returns true if this map contains no key-value mappings.

Specified by:
isEmpty in interface Map<String,Object>
Returns:
true if this map contains no key-value mappings

keySet

public Set<String> keySet()
Returns a Set view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation), the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations. It does not support the add or addAll operations.

Specified by:
keySet in interface Map<String,Object>
Returns:
a set view of the keys contained in this map

remove

public Object remove(Object key)
Removes the mapping for this key from this map if it is present (optional operation). More formally, if this map contains a mapping from key k to value v such that (key==null ? k==null : key.equals(k)), that mapping is removed. (The map can contain at most one such mapping.)

Returns the value to which the map previously associated the key, or null if the map contained no mapping for this key. (A null return can also indicate that the map previously associated null with the specified key if the implementation supports null values.) The map will not contain a mapping for the specified key once the call returns.

Specified by:
remove in interface Map<String,Object>
Specified by:
remove in interface Bindings
Parameters:
key - key whose mapping is to be removed from the map.
Returns:
previous value associated with specified key, or null if there was no mapping for key.
Throws:
NullPointerException - if key is null
ClassCastException - if key is not String
IllegalArgumentException - if key is empty String

size

public int size()
Returns the number of key-value mappings in this map. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Specified by:
size in interface Map<String,Object>
Returns:
the number of key-value mappings in this map

values

public Collection<Object> values()
Returns a Collection view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. If the map is modified while an iteration over the collection is in progress (except through the iterator's own remove operation), the results of the iteration are undefined. The collection supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Collection.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Specified by:
values in interface Map<String,Object>
Returns:
a collection view of the values contained in this map
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SimpleScriptContext

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.script
Class SimpleScriptContext

java.lang.Object
    extended by  javax.script.SimpleScriptContext
All Implemented Interfaces:
ScriptContext
public class SimpleScriptContext
extends Object
implements ScriptContext

Simple implementation of ScriptContext.

Since:
1.6

Field Summary
protected Bindings | engineScope This is the engine scope bindings.
protected Writer | errorWriter This is the writer to be used to output errors from scripts.
protected Bindings | globalScope This is the global scope bindings.
protected Reader | reader This is the reader to be used for input from scripts.
protected Writer | writer This is the writer to be used to output from scripts.
Fields inherited from interface javax.script.ScriptContext
ENGINE_SCOPE, GLOBAL_SCOPE
Constructor Summary
SimpleScriptContext()
Method Summary
Object | getAttribute(String name) Retrieves the value of the attribute with the given name in the scope occurring earliest in the search order.
Object | getAttribute(String name, int scope) Gets the value of an attribute in a given scope.
int | getAttributesScope(String name) Get the lowest scope in which an attribute is defined.
Bindings | getBindings(int scope) Returns the value of the engineScope field if specified scope is ENGINE_SCOPE.
Writer | getErrorWriter() Returns the Writer used to display error output.
Reader | getReader() Returns a Reader to be used by the script to read input.
List<Integer> | getScopes() Returns immutable List of all the valid values for scope in the ScriptContext.
Writer | getWriter() Returns the Writer for scripts to use when displaying output.
Object | removeAttribute(String name, int scope) Remove an attribute in a given scope.
void | setAttribute(String name, Object value, int scope) Sets the value of an attribute in a given scope.
void | setBindings(Bindings bindings, int scope) Sets a Bindings of attributes for the given scope.
void | setErrorWriter(Writer writer) Sets the Writer used to display error output.
void | setReader(Reader reader) Sets the Reader for scripts to read input .
void | setWriter(Writer writer) Sets the Writer for scripts to use when displaying output.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

writer

protected Writer writer
This is the writer to be used to output from scripts. By default, a PrintWriter based on System.out is used. Accessor methods getWriter, setWriter are used to manage this field.

See Also:
System.out, PrintWriter

errorWriter

protected Writer errorWriter
This is the writer to be used to output errors from scripts. By default, a PrintWriter based on System.err is used. Accessor methods getErrorWriter, setErrorWriter are used to manage this field.

See Also:
System.err, PrintWriter

reader

protected Reader reader
This is the reader to be used for input from scripts. By default, a InputStreamReader based on System.in is used and default charset is used by this reader. Accessor methods getReader, setReader are used to manage this field.

See Also:
System.in, InputStreamReader

engineScope

protected Bindings engineScope
This is the engine scope bindings. By default, a SimpleBindings is used. Accessor methods setBindings, getBindings are used to manage this field.

See Also:
SimpleBindings

globalScope

protected Bindings globalScope
This is the global scope bindings. By default, a null value (which means no global scope) is used. Accessor methods setBindings, getBindings are used to manage this field.

Constructor Detail

SimpleScriptContext

public SimpleScriptContext()
Method Detail

setBindings

public void setBindings(Bindings bindings,
                        int scope)
Sets a Bindings of attributes for the given scope. If the value of scope is ENGINE_SCOPE the given Bindings replaces the engineScope field. If the value of scope is GLOBAL_SCOPE the given Bindings replaces the globalScope field.

Specified by:
setBindings in interface ScriptContext
Parameters:
bindings - The Bindings of attributes to set.
scope - The value of the scope in which the attributes are set.
Throws:
IllegalArgumentException - if scope is invalid.
NullPointerException - if the value of scope is ENGINE_SCOPE and the specified Bindings is null.

getAttribute

public Object getAttribute(String name)
Retrieves the value of the attribute with the given name in the scope occurring earliest in the search order. The order is determined by the numeric value of the scope parameter (lowest scope values first.)

Specified by:
getAttribute in interface ScriptContext
Parameters:
name - The name of the the attribute to retrieve.
Returns:
The value of the attribute in the lowest scope for which an attribute with the given name is defined. Returns null if no attribute with the name exists in any scope.
Throws:
NullPointerException - if the name is null.
IllegalArgumentException - if the name is empty.

getAttribute

public Object getAttribute(String name,
                           int scope)
Gets the value of an attribute in a given scope.

Specified by:
getAttribute in interface ScriptContext
Parameters:
name - The name of the attribute to retrieve.
scope - The scope in which to retrieve the attribute.
Returns:
The value of the attribute. Returns null is the name does not exist in the given scope.
Throws:
IllegalArgumentException - if the name is empty or if the value of scope is invalid.
NullPointerException - if the name is null.

removeAttribute

public Object removeAttribute(String name,
                              int scope)
Remove an attribute in a given scope.

Specified by:
removeAttribute in interface ScriptContext
Parameters:
name - The name of the attribute to remove
scope - The scope in which to remove the attribute
Returns:
The removed value.
Throws:
IllegalArgumentException - if the name is empty or if the scope is invalid.
NullPointerException - if the name is null.

setAttribute

public void setAttribute(String name,
                         Object value,
                         int scope)
Sets the value of an attribute in a given scope.

Specified by:
setAttribute in interface ScriptContext
Parameters:
name - The name of the attribute to set
value - The value of the attribute
scope - The scope in which to set the attribute
Throws:
IllegalArgumentException - if the name is empty or if the scope is invalid.
NullPointerException - if the name is null.

getWriter

public Writer getWriter()
Returns the Writer for scripts to use when displaying output.

Specified by:
getWriter in interface ScriptContext
Returns:
The Writer.

getReader

public Reader getReader()
Returns a Reader to be used by the script to read input.

Specified by:
getReader in interface ScriptContext
Returns:
The Reader.

setReader

public void setReader(Reader reader)
Sets the Reader for scripts to read input .

Specified by:
setReader in interface ScriptContext
Parameters:
reader - The new Reader.

setWriter

public void setWriter(Writer writer)
Sets the Writer for scripts to use when displaying output.

Specified by:
setWriter in interface ScriptContext
Parameters:
writer - The new Writer.

getErrorWriter

public Writer getErrorWriter()
Returns the Writer used to display error output.

Specified by:
getErrorWriter in interface ScriptContext
Returns:
The Writer

setErrorWriter

public void setErrorWriter(Writer writer)
Sets the Writer used to display error output.

Specified by:
setErrorWriter in interface ScriptContext
Parameters:
writer - The Writer.

getAttributesScope

public int getAttributesScope(String name)
Get the lowest scope in which an attribute is defined.

Specified by:
getAttributesScope in interface ScriptContext
Parameters:
name - Name of the attribute .
Returns:
The lowest scope. Returns -1 if no attribute with the given name is defined in any scope.
Throws:
NullPointerException - if name is null.
IllegalArgumentException - if name is empty.

getBindings

public Bindings getBindings(int scope)
Returns the value of the engineScope field if specified scope is ENGINE_SCOPE. Returns the value of the globalScope field if the specified scope is GLOBAL_SCOPE.

Specified by:
getBindings in interface ScriptContext
Parameters:
scope - The specified scope
Returns:
The value of either the engineScope or globalScope field.
Throws:
IllegalArgumentException - if the value of scope is invalid.

getScopes

public List<Integer> getScopes()
Returns immutable List of all the valid values for scope in the ScriptContext.

Specified by:
getScopes in interface ScriptContext
Returns:
list of scope values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


auth

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.security.auth

This package provides a framework for authentication and authorization.

See:
Description

Interface Summary
Destroyable | Objects such as credentials may optionally implement this interface to provide the capability to destroy its contents.
Refreshable | Objects such as credentials may optionally implement this interface to provide the capability to refresh itself.

Class Summary
AuthPermission | This class is for authentication permissions.
Policy | Deprecated. as of JDK version 1.4 -- Replaced by java.security.Policy.
PrivateCredentialPermission | This class is used to protect access to private Credentials belonging to a particular Subject.
Subject | A Subject represents a grouping of related information for a single entity, such as a person.
SubjectDomainCombiner | A SubjectDomainCombiner updates ProtectionDomains with Principals from the Subject associated with this SubjectDomainCombiner.

Exception Summary
DestroyFailedException | Signals that a destroy operation failed.
RefreshFailedException | Signals that a refresh operation failed.

Package javax.security.auth Description

This package provides a framework for authentication and authorization. The framework allows authentication to be performed in pluggable fashion. Different authentication modules can be plugged under an application without requiring modifications to the application itself. The authorization component allows specification of access controls based on code location, code signers and code executors (Subjects).

Since:
JDK1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.security.auth Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.security.auth

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.security.Permission (implements java.security.Guard, java.io.Serializable)
      • java.security.BasicPermission (implements java.io.Serializable)
        • javax.security.auth.AuthPermission
      • javax.security.auth.PrivateCredentialPermission
    • javax.security.auth.Policy
    • javax.security.auth.Subject (implements java.io.Serializable)
    • javax.security.auth.SubjectDomainCombiner (implements java.security.DomainCombiner)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.security.auth.DestroyFailedException
        • javax.security.auth.RefreshFailedException

Interface Hierarchy

  • javax.security.auth.Destroyable
  • javax.security.auth.Refreshable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.security.auth

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.security.auth

Packages that use javax.security.auth
java.security | Provides the classes and interfaces for the security framework.
javax.management.remote | Interfaces for remote access to JMX MBean servers.
javax.management.remote.rmi | The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server.
javax.security.auth | This package provides a framework for authentication and authorization.
javax.security.auth.kerberos | This package contains utility classes related to the Kerberos network authentication protocol.
javax.security.auth.login | This package provides a pluggable authentication framework.
javax.security.auth.spi | This package provides the interface to be used for implementing pluggable authentication modules.
javax.security.auth.x500 | This package contains the classes that should be used to store X500 Principal and X500 Private Crendentials in a Subject.

Classes in javax.security.auth used by java.security
Destroyable
Objects such as credentials may optionally implement this interface to provide the capability to destroy its contents.
DestroyFailedException
Signals that a destroy operation failed.
Subject
A Subject represents a grouping of related information for a single entity, such as a person.

Classes in javax.security.auth used by javax.management.remote
Subject
A Subject represents a grouping of related information for a single entity, such as a person.

Classes in javax.security.auth used by javax.management.remote.rmi
Subject
A Subject represents a grouping of related information for a single entity, such as a person.

Classes in javax.security.auth used by javax.security.auth
DestroyFailedException
Signals that a destroy operation failed.
Policy
Deprecated. as of JDK version 1.4 -- Replaced by java.security.Policy. java.security.Policy has a method:
        public PermissionCollection getPermissions
            (java.security.ProtectionDomain pd)
and ProtectionDomain has a constructor:
        public ProtectionDomain
            (CodeSource cs,
             PermissionCollection permissions,
             ClassLoader loader,
             Principal[] principals)
These two APIs provide callers the means to query the Policy for Principal-based Permission entries.
RefreshFailedException
Signals that a refresh operation failed.
Subject
A Subject represents a grouping of related information for a single entity, such as a person.

Classes in javax.security.auth used by javax.security.auth.kerberos
Destroyable
Objects such as credentials may optionally implement this interface to provide the capability to destroy its contents.
DestroyFailedException
Signals that a destroy operation failed.
Refreshable
Objects such as credentials may optionally implement this interface to provide the capability to refresh itself.
RefreshFailedException
Signals that a refresh operation failed.

Classes in javax.security.auth used by javax.security.auth.login
Subject
A Subject represents a grouping of related information for a single entity, such as a person.

Classes in javax.security.auth used by javax.security.auth.spi
Subject
A Subject represents a grouping of related information for a single entity, such as a person.

Classes in javax.security.auth used by javax.security.auth.x500
Destroyable
Objects such as credentials may optionally implement this interface to provide the capability to destroy its contents.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AuthPermission

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.security.auth
Class AuthPermission

java.lang.Object
    extended by  java.security.Permission
        extended by  java.security.BasicPermission
            extended by  javax.security.auth.AuthPermission
All Implemented Interfaces:
Serializable, Guard
public final class AuthPermission
extends BasicPermission

This class is for authentication permissions. An AuthPermission contains a name (also referred to as a "target name") but no actions list; you either have the named permission or you don't.

The target name is the name of a security configuration parameter (see below). Currently the AuthPermission object is used to guard access to the Policy, Subject, LoginContext, and Configuration objects.

The possible target names for an Authentication Permission are:

        doAs -                  allow the caller to invoke the
                                Subject.doAs methods.

        doAsPrivileged -        allow the caller to invoke the
                                Subject.doAsPrivileged methods.

        getSubject -            allow for the retrieval of the
                                Subject(s) associated with the
                                current Thread.

        getSubjectFromDomainCombiner -  allow for the retrieval of the
                                Subject associated with the
                                a SubjectDomainCombiner.

        setReadOnly -           allow the caller to set a Subject
                                to be read-only.

        modifyPrincipals -      allow the caller to modify the Set
                                of Principals associated with a
                                Subject

        modifyPublicCredentials - allow the caller to modify the
                                Set of public credentials
                                associated with a Subject

        modifyPrivateCredentials - allow the caller to modify the
                                Set of private credentials
                                associated with a Subject

        refreshCredential -     allow code to invoke the refresh
                                method on a credential which implements
                                the Refreshable interface.

        destroyCredential -     allow code to invoke the destroy
                                method on a credential object
                                which implements the Destroyable
                                interface.

        createLoginContext.{name} -  allow code to instantiate a
                                LoginContext with the
                                specified name.  name
                                is used as the index into the installed login
                                Configuration
                                (that returned by
                                Configuration.getConfiguration()).
                                name can be wildcarded (set to '*')
                                to allow for any name.

        getLoginConfiguration - allow for the retrieval of the system-wide
                                login Configuration.

        createLoginConfiguration.{type} - allow code to obtain a Configuration
                                object via
                                Configuration.getInstance.

        setLoginConfiguration - allow for the setting of the system-wide
                                login Configuration.

        refreshLoginConfiguration - allow for the refreshing of the system-wide
                                login Configuration.

The following target name has been deprecated in favor of createLoginContext.{name}.

        createLoginContext -    allow code to instantiate a
                                LoginContext.

javax.security.auth.Policy has been deprecated in favor of java.security.Policy. Therefore, the following target names have also been deprecated:

        getPolicy -             allow the caller to retrieve the system-wide
                                Subject-based access control policy.

        setPolicy -             allow the caller to set the system-wide
                                Subject-based access control policy.

        refreshPolicy -         allow the caller to refresh the system-wide
                                Subject-based access control policy.

See Also:
Serialized Form

Constructor Summary
AuthPermission(String name)
Creates a new AuthPermission with the specified name.
AuthPermission(String name, String actions)
Creates a new AuthPermission object with the specified name.
Method Summary
Methods inherited from class java.security.BasicPermission
equals, getActions, hashCode, implies, newPermissionCollection
Methods inherited from class java.security.Permission
checkGuard, getName, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

AuthPermission

public AuthPermission(String name)
Creates a new AuthPermission with the specified name. The name is the symbolic name of the AuthPermission.

Parameters:
name - the name of the AuthPermission
Throws:
NullPointerException - if name is null.
IllegalArgumentException - if name is empty.

AuthPermission

public AuthPermission(String name,
                      String actions)
Creates a new AuthPermission object with the specified name. The name is the symbolic name of the AuthPermission, and the actions String is currently unused and should be null.

Parameters:
name - the name of the AuthPermission

actions - should be null.
Throws:
NullPointerException - if name is null.
IllegalArgumentException - if name is empty.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


callback

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.security.auth.callback

This package provides the classes necessary for services to interact with applications in order to retrieve information (authentication data including usernames or passwords, for example) or to display information (error and warning messages, for example).

See:
Description

Interface Summary
Callback | Implementations of this interface are passed to a CallbackHandler, allowing underlying security services the ability to interact with a calling application to retrieve specific authentication data such as usernames and passwords, or to display certain information, such as error and warning messages.
CallbackHandler | An application implements a CallbackHandler and passes it to underlying security services so that they may interact with the application to retrieve specific authentication data, such as usernames and passwords, or to display certain information, such as error and warning messages.

Class Summary
ChoiceCallback | Underlying security services instantiate and pass a ChoiceCallback to the handle method of a CallbackHandler to display a list of choices and to retrieve the selected choice(s).
ConfirmationCallback | Underlying security services instantiate and pass a ConfirmationCallback to the handle method of a CallbackHandler to ask for YES/NO, OK/CANCEL, YES/NO/CANCEL or other similar confirmations.
LanguageCallback | Underlying security services instantiate and pass a LanguageCallback to the handle method of a CallbackHandler to retrieve the Locale used for localizing text.
NameCallback | Underlying security services instantiate and pass a NameCallback to the handle method of a CallbackHandler to retrieve name information.
PasswordCallback | Underlying security services instantiate and pass a PasswordCallback to the handle method of a CallbackHandler to retrieve password information.
TextInputCallback | Underlying security services instantiate and pass a TextInputCallback to the handle method of a CallbackHandler to retrieve generic text information.
TextOutputCallback | Underlying security services instantiate and pass a TextOutputCallback to the handle method of a CallbackHandler to display information messages, warning messages and error messages.

Exception Summary
UnsupportedCallbackException Signals that a CallbackHandler does not recognize a particular Callback.

Package javax.security.auth.callback Description

This package provides the classes necessary for services to interact with applications in order to retrieve information (authentication data including usernames or passwords, for example) or to display information (error and warning messages, for example).

Since:
JDK1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


Callback

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.callback
Interface Callback

All Known Implementing Classes:
AuthorizeCallback, ChoiceCallback, ConfirmationCallback, LanguageCallback, NameCallback, PasswordCallback, RealmCallback, RealmChoiceCallback, TextInputCallback, TextOutputCallback
public interface Callback

Implementations of this interface are passed to a CallbackHandler, allowing underlying security services the ability to interact with a calling application to retrieve specific authentication data such as usernames and passwords, or to display certain information, such as error and warning messages.

Callback implementations do not retrieve or display the information requested by underlying security services. Callback implementations simply provide the means to pass such requests to applications, and for applications, if appropriate, to return requested information back to the underlying security services.

See Also:
CallbackHandler, ChoiceCallback, ConfirmationCallback, LanguageCallback, NameCallback, PasswordCallback, TextInputCallback, TextOutputCallback

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


javax.security.auth.callback Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.security.auth.callback

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.security.auth.callback.ChoiceCallback (implements javax.security.auth.callback.Callback, java.io.Serializable)
    • javax.security.auth.callback.ConfirmationCallback (implements javax.security.auth.callback.Callback, java.io.Serializable)
    • javax.security.auth.callback.LanguageCallback (implements javax.security.auth.callback.Callback, java.io.Serializable)
    • javax.security.auth.callback.NameCallback (implements javax.security.auth.callback.Callback, java.io.Serializable)
    • javax.security.auth.callback.PasswordCallback (implements javax.security.auth.callback.Callback, java.io.Serializable)
    • javax.security.auth.callback.TextInputCallback (implements javax.security.auth.callback.Callback, java.io.Serializable)
    • javax.security.auth.callback.TextOutputCallback (implements javax.security.auth.callback.Callback, java.io.Serializable)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.security.auth.callback.UnsupportedCallbackException

Interface Hierarchy

  • javax.security.auth.callback.Callback
  • javax.security.auth.callback.CallbackHandler
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.security.auth.callback

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.security.auth.callback

Packages that use javax.security.auth.callback
java.security | Provides the classes and interfaces for the security framework.
javax.security.auth.callback | This package provides the classes necessary for services to interact with applications in order to retrieve information (authentication data including usernames or passwords, for example) or to display information (error and warning messages, for example).
javax.security.auth.login | This package provides a pluggable authentication framework.
javax.security.auth.spi | This package provides the interface to be used for implementing pluggable authentication modules.
javax.security.sasl | Contains class and interfaces for supporting SASL.

Classes in javax.security.auth.callback used by java.security
CallbackHandler
An application implements a CallbackHandler and passes it to underlying security services so that they may interact with the application to retrieve specific authentication data, such as usernames and passwords, or to display certain information, such as error and warning messages.

Classes in javax.security.auth.callback used by javax.security.auth.callback
Callback
Implementations of this interface are passed to a CallbackHandler, allowing underlying security services the ability to interact with a calling application to retrieve specific authentication data such as usernames and passwords, or to display certain information, such as error and warning messages.
UnsupportedCallbackException
Signals that a CallbackHandler does not recognize a particular Callback.

Classes in javax.security.auth.callback used by javax.security.auth.login
CallbackHandler
An application implements a CallbackHandler and passes it to underlying security services so that they may interact with the application to retrieve specific authentication data, such as usernames and passwords, or to display certain information, such as error and warning messages.

Classes in javax.security.auth.callback used by javax.security.auth.spi
CallbackHandler
An application implements a CallbackHandler and passes it to underlying security services so that they may interact with the application to retrieve specific authentication data, such as usernames and passwords, or to display certain information, such as error and warning messages.

Classes in javax.security.auth.callback used by javax.security.sasl
Callback
Implementations of this interface are passed to a CallbackHandler, allowing underlying security services the ability to interact with a calling application to retrieve specific authentication data such as usernames and passwords, or to display certain information, such as error and warning messages.
CallbackHandler
An application implements a CallbackHandler and passes it to underlying security services so that they may interact with the application to retrieve specific authentication data, such as usernames and passwords, or to display certain information, such as error and warning messages.
ChoiceCallback
Underlying security services instantiate and pass a ChoiceCallback to the handle method of a CallbackHandler to display a list of choices and to retrieve the selected choice(s).
TextInputCallback
Underlying security services instantiate and pass a TextInputCallback to the handle method of a CallbackHandler to retrieve generic text information.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


CallbackHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.callback
Interface CallbackHandler

public interface CallbackHandler

An application implements a CallbackHandler and passes it to underlying security services so that they may interact with the application to retrieve specific authentication data, such as usernames and passwords, or to display certain information, such as error and warning messages.

CallbackHandlers are implemented in an application-dependent fashion. For example, implementations for an application with a graphical user interface (GUI) may pop up windows to prompt for requested information or to display error messages. An implementation may also choose to obtain requested information from an alternate source without asking the end user.

Underlying security services make requests for different types of information by passing individual Callbacks to the CallbackHandler. The CallbackHandler implementation decides how to retrieve and display information depending on the Callbacks passed to it. For example, if the underlying service needs a username and password to authenticate a user, it uses a NameCallback and PasswordCallback. The CallbackHandler can then choose to prompt for a username and password serially, or to prompt for both in a single window.

A default CallbackHandler class implementation may be specified in the auth.login.defaultCallbackHandler security property. The security property can be set in the Java security properties file located in the file named <JAVA_HOME>/lib/security/java.security. <JAVA_HOME> refers to the value of the java.home system property, and specifies the directory where the JRE is installed.

If the security property is set to the fully qualified name of a CallbackHandler implementation class, then a LoginContext will load the specified CallbackHandler and pass it to the underlying LoginModules. The LoginContext only loads the default handler if it was not provided one.

All default handler implementations must provide a public zero-argument constructor.

Method Summary
 void handle(Callback[] callbacks)
Retrieve or display the information requested in the provided Callbacks.

Method Detail

handle

void handle(Callback[] callbacks)
            throws IOException,
                   UnsupportedCallbackException

Retrieve or display the information requested in the provided Callbacks.

The handle method implementation checks the instance(s) of the Callback object(s) passed in to retrieve or display the requested information. The following example is provided to help demonstrate what an handle method implementation might look like. This example code is for guidance only. Many details, including proper error handling, are left out for simplicity.

 public void handle(Callback[] callbacks)
 throws IOException, UnsupportedCallbackException {

         for (int i = 0; i < callbacks.length; i++) {
            if (callbacks[i] instanceof TextOutputCallback) {

                // display the message according to the specified type
                TextOutputCallback toc = (TextOutputCallback)callbacks[i];
                switch (toc.getMessageType()) {
                case TextOutputCallback.INFORMATION:
                    System.out.println(toc.getMessage());
                    break;
                case TextOutputCallback.ERROR:
                    System.out.println("ERROR: " + toc.getMessage());
                    break;
                case TextOutputCallback.WARNING:
                    System.out.println("WARNING: " + toc.getMessage());
                    break;
                default:
                    throw new IOException("Unsupported message type: " +
                                        toc.getMessageType());
                }

            } else if (callbacks[i] instanceof NameCallback) {

                // prompt the user for a username
                NameCallback nc = (NameCallback)callbacks[i];

                // ignore the provided defaultName
                System.err.print(nc.getPrompt());
                System.err.flush();
                nc.setName((new BufferedReader
                        (new InputStreamReader(System.in))).readLine());

            } else if (callbacks[i] instanceof PasswordCallback) {

                // prompt the user for sensitive information
                PasswordCallback pc = (PasswordCallback)callbacks[i];
                System.err.print(pc.getPrompt());
                System.err.flush();
                pc.setPassword(readPassword(System.in));

            } else {
                throw new UnsupportedCallbackException
                        (callbacks[i], "Unrecognized Callback");
            }
         }
 }

 // Reads user password from given input stream.
 private char[] readPassword(InputStream in) throws IOException {
    // insert code to read a user password from the input stream
 }

Parameters:
callbacks - an array of Callback objects provided by an underlying security service which contains the information requested to be retrieved or displayed.
Throws:
IOException - if an input or output error occurs.

UnsupportedCallbackException - if the implementation of this method does not support one or more of the Callbacks specified in the callbacks parameter.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ChoiceCallback

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.callback
Class ChoiceCallback

java.lang.Object
    extended by  javax.security.auth.callback.ChoiceCallback
All Implemented Interfaces:
Serializable, Callback
Direct Known Subclasses:
RealmChoiceCallback
public class ChoiceCallback
extends Object
implements Callback, Serializable

Underlying security services instantiate and pass a ChoiceCallback to the handle method of a CallbackHandler to display a list of choices and to retrieve the selected choice(s).

See Also:
CallbackHandler, Serialized Form

Constructor Summary
ChoiceCallback(String prompt, String[] choices, int defaultChoice, boolean multipleSelectionsAllowed)
Construct a ChoiceCallback with a prompt, a list of choices, a default choice, and a boolean specifying whether or not multiple selections from the list of choices are allowed.
Method Summary
boolean | allowMultipleSelections() Get the boolean determining whether multiple selections from the choices list are allowed.
String[] | getChoices() Get the list of choices.
int | getDefaultChoice() Get the defaultChoice.
String | getPrompt() Get the prompt.
int[] | getSelectedIndexes() Get the selected choices.
void | setSelectedIndex(int selection) Set the selected choice.
void | setSelectedIndexes(int[] selections) Set the selected choices.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ChoiceCallback

public ChoiceCallback(String prompt,
                      String[] choices,
                      int defaultChoice,
                      boolean multipleSelectionsAllowed)
Construct a ChoiceCallback with a prompt, a list of choices, a default choice, and a boolean specifying whether or not multiple selections from the list of choices are allowed.

Parameters:
prompt - the prompt used to describe the list of choices.

choices - the list of choices.

defaultChoice - the choice to be used as the default choice when the list of choices are displayed. This value is represented as an index into the choices array.

multipleSelectionsAllowed - boolean specifying whether or not multiple selections can be made from the list of choices.
Throws:
IllegalArgumentException - if prompt is null, if prompt has a length of 0, if choices is null, if choices has a length of 0, if any element from choices is null, if any element from choices has a length of 0 or if defaultChoice does not fall within the array boundaries of choices.
Method Detail

getPrompt

public String getPrompt()
Get the prompt.

Returns:
the prompt.

getChoices

public String[] getChoices()
Get the list of choices.

Returns:
the list of choices.

getDefaultChoice

public int getDefaultChoice()
Get the defaultChoice.

Returns:
the defaultChoice, represented as an index into the choices list.

allowMultipleSelections

public boolean allowMultipleSelections()
Get the boolean determining whether multiple selections from the choices list are allowed.

Returns:
whether multiple selections are allowed.

setSelectedIndex

public void setSelectedIndex(int selection)
Set the selected choice.

Parameters:
selection - the selection represented as an index into the choices list.
See Also:
getSelectedIndexes()

setSelectedIndexes

public void setSelectedIndexes(int[] selections)
Set the selected choices.

Parameters:
selections - the selections represented as indexes into the choices list.
Throws:
UnsupportedOperationException - if multiple selections are not allowed, as determined by allowMultipleSelections.
See Also:
getSelectedIndexes()

getSelectedIndexes

public int[] getSelectedIndexes()
Get the selected choices.

Returns:
the selected choices, represented as indexes into the choices list.
See Also:
setSelectedIndexes(int[])
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.security.auth.callback.ChoiceCallback

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.callback.ChoiceCallback

Packages that use ChoiceCallback
javax.security.sasl Contains class and interfaces for supporting SASL.

Uses of ChoiceCallback in javax.security.sasl

Subclasses of ChoiceCallback in javax.security.sasl
 class RealmChoiceCallback
This callback is used by SaslClient and SaslServer to obtain a realm given a list of realm choices.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.callback.ConfirmationCallback

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.callback.ConfirmationCallback

No usage of javax.security.auth.callback.ConfirmationCallback

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.callback.LanguageCallback

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.callback.LanguageCallback

No usage of javax.security.auth.callback.LanguageCallback

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.callback.NameCallback

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.callback.NameCallback

No usage of javax.security.auth.callback.NameCallback

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.callback.PasswordCallback

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.callback.PasswordCallback

No usage of javax.security.auth.callback.PasswordCallback

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.callback.TextInputCallback

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.callback.TextInputCallback

Packages that use TextInputCallback
javax.security.sasl Contains class and interfaces for supporting SASL.

Uses of TextInputCallback in javax.security.sasl

Subclasses of TextInputCallback in javax.security.sasl
 class RealmCallback
This callback is used by SaslClient and SaslServer to retrieve realm information.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.callback.TextOutputCallback

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.callback.TextOutputCallback

No usage of javax.security.auth.callback.TextOutputCallback

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.callback.UnsupportedCallbackException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.callback.UnsupportedCallbackException

Packages that use UnsupportedCallbackException
javax.security.auth.callback This package provides the classes necessary for services to interact with applications in order to retrieve information (authentication data including usernames or passwords, for example) or to display information (error and warning messages, for example).

Uses of UnsupportedCallbackException in javax.security.auth.callback

Methods in javax.security.auth.callback that throw UnsupportedCallbackException
 void CallbackHandler.handle(Callback[] callbacks)
Retrieve or display the information requested in the provided Callbacks.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.security.auth.callback.Callback

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.security.auth.callback.Callback

Packages that use Callback
javax.security.auth.callback | This package provides the classes necessary for services to interact with applications in order to retrieve information (authentication data including usernames or passwords, for example) or to display information (error and warning messages, for example).
javax.security.sasl | Contains class and interfaces for supporting SASL.

Uses of Callback in javax.security.auth.callback

Classes in javax.security.auth.callback that implement Callback
class | ChoiceCallback Underlying security services instantiate and pass a ChoiceCallback to the handle method of a CallbackHandler to display a list of choices and to retrieve the selected choice(s).
class | ConfirmationCallback Underlying security services instantiate and pass a ConfirmationCallback to the handle method of a CallbackHandler to ask for YES/NO, OK/CANCEL, YES/NO/CANCEL or other similar confirmations.
class | LanguageCallback Underlying security services instantiate and pass a LanguageCallback to the handle method of a CallbackHandler to retrieve the Locale used for localizing text.
class | NameCallback Underlying security services instantiate and pass a NameCallback to the handle method of a CallbackHandler to retrieve name information.
class | PasswordCallback Underlying security services instantiate and pass a PasswordCallback to the handle method of a CallbackHandler to retrieve password information.
class | TextInputCallback Underlying security services instantiate and pass a TextInputCallback to the handle method of a CallbackHandler to retrieve generic text information.
class | TextOutputCallback Underlying security services instantiate and pass a TextOutputCallback to the handle method of a CallbackHandler to display information messages, warning messages and error messages.

Methods in javax.security.auth.callback that return Callback
 Callback UnsupportedCallbackException.getCallback()
Get the unrecognized Callback.

Methods in javax.security.auth.callback with parameters of type Callback
 void CallbackHandler.handle(Callback[] callbacks)
Retrieve or display the information requested in the provided Callbacks.

Constructors in javax.security.auth.callback with parameters of type Callback
UnsupportedCallbackException(Callback callback)
Constructs a UnsupportedCallbackException with no detail message.
UnsupportedCallbackException(Callback callback, String msg)
Constructs a UnsupportedCallbackException with the specified detail message.

Uses of Callback in javax.security.sasl

Classes in javax.security.sasl that implement Callback
class | AuthorizeCallback This callback is used by SaslServer to determine whether one entity (identified by an authenticated authentication id) can act on behalf of another entity (identified by an authorization id).
class | RealmCallback This callback is used by SaslClient and SaslServer to retrieve realm information.
class | RealmChoiceCallback This callback is used by SaslClient and SaslServer to obtain a realm given a list of realm choices.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.security.auth.callback.CallbackHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.security.auth.callback.CallbackHandler

Packages that use CallbackHandler
java.security | Provides the classes and interfaces for the security framework.
javax.security.auth.login | This package provides a pluggable authentication framework.
javax.security.auth.spi | This package provides the interface to be used for implementing pluggable authentication modules.
javax.security.sasl | Contains class and interfaces for supporting SASL.

Uses of CallbackHandler in java.security

Methods in java.security that return CallbackHandler
 CallbackHandler KeyStore.CallbackHandlerProtection.getCallbackHandler()
Returns the CallbackHandler.

Methods in java.security with parameters of type CallbackHandler
abstract void | AuthProvider.login(Subject subject, CallbackHandler handler) Log in to this provider.
abstract void | AuthProvider.setCallbackHandler(CallbackHandler handler) Set a CallbackHandler.

Constructors in java.security with parameters of type CallbackHandler
KeyStore.CallbackHandlerProtection(CallbackHandler handler)
Constructs a new CallbackHandlerProtection from a CallbackHandler.

Uses of CallbackHandler in javax.security.auth.login

Constructors in javax.security.auth.login with parameters of type CallbackHandler
LoginContext(String name, CallbackHandler callbackHandler)
Instantiate a new LoginContext object with a name and a CallbackHandler object.
LoginContext(String name, Subject subject, CallbackHandler callbackHandler)
Instantiate a new LoginContext object with a name, a Subject to be authenticated, and a CallbackHandler object.
LoginContext(String name, Subject subject, CallbackHandler callbackHandler, Configuration config)
Instantiate a new LoginContext object with a name, a Subject to be authenticated, a CallbackHandler object, and a login Configuration.

Uses of CallbackHandler in javax.security.auth.spi

Methods in javax.security.auth.spi with parameters of type CallbackHandler
 void LoginModule.initialize(Subject subject, CallbackHandler callbackHandler, Map<String,?> sharedState, Map<String,?> options)
Initialize this LoginModule.

Uses of CallbackHandler in javax.security.sasl

Methods in javax.security.sasl with parameters of type CallbackHandler
SaslClient | SaslClientFactory.createSaslClient(String[] mechanisms, String authorizationId, String protocol, String serverName, Map<String,?> props, CallbackHandler cbh) Creates a SaslClient using the parameters supplied.
static SaslClient | Sasl.createSaslClient(String[] mechanisms, String authorizationId, String protocol, String serverName, Map<String,?> props, CallbackHandler cbh) Creates a SaslClient using the parameters supplied.
SaslServer | SaslServerFactory.createSaslServer(String mechanism, String protocol, String serverName, Map<String,?> props, CallbackHandler cbh) Creates a SaslServer using the parameters supplied.
static SaslServer | Sasl.createSaslServer(String mechanism, String protocol, String serverName, Map<String,?> props, CallbackHandler cbh) Creates a SaslServer for the specified mechanism.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ConfirmationCallback

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.callback
Class ConfirmationCallback

java.lang.Object
    extended by  javax.security.auth.callback.ConfirmationCallback
All Implemented Interfaces:
Serializable, Callback
public class ConfirmationCallback
extends Object
implements Callback, Serializable

Underlying security services instantiate and pass a ConfirmationCallback to the handle method of a CallbackHandler to ask for YES/NO, OK/CANCEL, YES/NO/CANCEL or other similar confirmations.

See Also:
CallbackHandler, Serialized Form

Field Summary
static int | CANCEL CANCEL option.
static int | ERROR ERROR message type.
static int | INFORMATION INFORMATION message type.
static int | NO NO option.
static int | OK OK option.
static int | OK_CANCEL_OPTION OK/CANCEL confirmation confirmation option.
static int | UNSPECIFIED_OPTION Unspecified option type.
static int | WARNING WARNING message type.
static int | YES YES option.
static int | YES_NO_CANCEL_OPTION YES/NO/CANCEL confirmation confirmation option.
static int | YES_NO_OPTION YES/NO confirmation option.
Constructor Summary
ConfirmationCallback(int messageType, int optionType, int defaultOption)
Construct a ConfirmationCallback with a message type, an option type and a default option.
ConfirmationCallback(int messageType, String[] options, int defaultOption)
Construct a ConfirmationCallback with a message type, a list of options and a default option.
ConfirmationCallback(String prompt, int messageType, int optionType, int defaultOption)
Construct a ConfirmationCallback with a prompt, message type, an option type and a default option.
ConfirmationCallback(String prompt, int messageType, String[] options, int defaultOption)
Construct a ConfirmationCallback with a prompt, message type, a list of options and a default option.
Method Summary
int | getDefaultOption() Get the default option.
int | getMessageType() Get the message type.
String[] | getOptions() Get the confirmation options.
int | getOptionType() Get the option type.
String | getPrompt() Get the prompt.
int | getSelectedIndex() Get the selected confirmation option.
void | setSelectedIndex(int selection) Set the selected confirmation option.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

UNSPECIFIED_OPTION

public static final int UNSPECIFIED_OPTION
Unspecified option type.

The getOptionType method returns this value if this ConfirmationCallback was instantiated with options instead of an optionType.

See Also:
Constant Field Values

YES_NO_OPTION

public static final int YES_NO_OPTION
YES/NO confirmation option.

An underlying security service specifies this as the optionType to a ConfirmationCallback constructor if it requires a confirmation which can be answered with either YES or NO.

See Also:
Constant Field Values

YES_NO_CANCEL_OPTION

public static final int YES_NO_CANCEL_OPTION
YES/NO/CANCEL confirmation confirmation option.

An underlying security service specifies this as the optionType to a ConfirmationCallback constructor if it requires a confirmation which can be answered with either YES, NO or CANCEL.

See Also:
Constant Field Values

OK_CANCEL_OPTION

public static final int OK_CANCEL_OPTION
OK/CANCEL confirmation confirmation option.

An underlying security service specifies this as the optionType to a ConfirmationCallback constructor if it requires a confirmation which can be answered with either OK or CANCEL.

See Also:
Constant Field Values

YES

public static final int YES
YES option.

If an optionType was specified to this ConfirmationCallback, this option may be specified as a defaultOption or returned as the selected index.

See Also:
Constant Field Values

NO

public static final int NO
NO option.

If an optionType was specified to this ConfirmationCallback, this option may be specified as a defaultOption or returned as the selected index.

See Also:
Constant Field Values

CANCEL

public static final int CANCEL
CANCEL option.

If an optionType was specified to this ConfirmationCallback, this option may be specified as a defaultOption or returned as the selected index.

See Also:
Constant Field Values

OK

public static final int OK
OK option.

If an optionType was specified to this ConfirmationCallback, this option may be specified as a defaultOption or returned as the selected index.

See Also:
Constant Field Values

INFORMATION

public static final int INFORMATION
INFORMATION message type.

See Also:
Constant Field Values

WARNING

public static final int WARNING
WARNING message type.

See Also:
Constant Field Values

ERROR

public static final int ERROR
ERROR message type.

See Also:
Constant Field Values
Constructor Detail

ConfirmationCallback

public ConfirmationCallback(int messageType,
                            int optionType,
                            int defaultOption)
Construct a ConfirmationCallback with a message type, an option type and a default option.

Underlying security services use this constructor if they require either a YES/NO, YES/NO/CANCEL or OK/CANCEL confirmation.

Parameters:
messageType - the message type (INFORMATION, WARNING or ERROR).

optionType - the option type (YES_NO_OPTION, YES_NO_CANCEL_OPTION or OK_CANCEL_OPTION).

defaultOption - the default option from the provided optionType (YES, NO, CANCEL or OK).
Throws:
IllegalArgumentException - if messageType is not either INFORMATION, WARNING, or ERROR, if optionType is not either YES_NO_OPTION, YES_NO_CANCEL_OPTION, or OK_CANCEL_OPTION, or if defaultOption does not correspond to one of the options in optionType.

ConfirmationCallback

public ConfirmationCallback(int messageType,
                            String[] options,
                            int defaultOption)
Construct a ConfirmationCallback with a message type, a list of options and a default option.

Underlying security services use this constructor if they require a confirmation different from the available preset confirmations provided (for example, CONTINUE/ABORT or STOP/GO). The confirmation options are listed in the options array, and are displayed by the CallbackHandler implementation in a manner consistent with the way preset options are displayed.

Parameters:
messageType - the message type (INFORMATION, WARNING or ERROR).

options - the list of confirmation options.

defaultOption - the default option, represented as an index into the options array.
Throws:
IllegalArgumentException - if messageType is not either INFORMATION, WARNING, or ERROR, if options is null, if options has a length of 0, if any element from options is null, if any element from options has a length of 0, or if defaultOption does not lie within the array boundaries of options.

ConfirmationCallback

public ConfirmationCallback(String prompt,
                            int messageType,
                            int optionType,
                            int defaultOption)
Construct a ConfirmationCallback with a prompt, message type, an option type and a default option.

Underlying security services use this constructor if they require either a YES/NO, YES/NO/CANCEL or OK/CANCEL confirmation.

Parameters:
prompt - the prompt used to describe the list of options.

messageType - the message type (INFORMATION, WARNING or ERROR).

optionType - the option type (YES_NO_OPTION, YES_NO_CANCEL_OPTION or OK_CANCEL_OPTION).

defaultOption - the default option from the provided optionType (YES, NO, CANCEL or OK).
Throws:
IllegalArgumentException - if prompt is null, if prompt has a length of 0, if messageType is not either INFORMATION, WARNING, or ERROR, if optionType is not either YES_NO_OPTION, YES_NO_CANCEL_OPTION, or OK_CANCEL_OPTION, or if defaultOption does not correspond to one of the options in optionType.

ConfirmationCallback

public ConfirmationCallback(String prompt,
                            int messageType,
                            String[] options,
                            int defaultOption)
Construct a ConfirmationCallback with a prompt, message type, a list of options and a default option.

Underlying security services use this constructor if they require a confirmation different from the available preset confirmations provided (for example, CONTINUE/ABORT or STOP/GO). The confirmation options are listed in the options array, and are displayed by the CallbackHandler implementation in a manner consistent with the way preset options are displayed.

Parameters:
prompt - the prompt used to describe the list of options.

messageType - the message type (INFORMATION, WARNING or ERROR).

options - the list of confirmation options.

defaultOption - the default option, represented as an index into the options array.
Throws:
IllegalArgumentException - if prompt is null, if prompt has a length of 0, if messageType is not either INFORMATION, WARNING, or ERROR, if options is null, if options has a length of 0, if any element from options is null, if any element from options has a length of 0, or if defaultOption does not lie within the array boundaries of options.
Method Detail

getPrompt

public String getPrompt()
Get the prompt.

Returns:
the prompt, or null if this ConfirmationCallback was instantiated without a prompt.

getMessageType

public int getMessageType()
Get the message type.

Returns:
the message type (INFORMATION, WARNING or ERROR).

getOptionType

public int getOptionType()
Get the option type.

If this method returns UNSPECIFIED_OPTION, then this ConfirmationCallback was instantiated with options instead of an optionType. In this case, invoke the getOptions method to determine which confirmation options to display.

Returns:
the option type (YES_NO_OPTION, YES_NO_CANCEL_OPTION or OK_CANCEL_OPTION), or UNSPECIFIED_OPTION if this ConfirmationCallback was instantiated with options instead of an optionType.

getOptions

public String[] getOptions()
Get the confirmation options.

Returns:
the list of confirmation options, or null if this ConfirmationCallback was instantiated with an optionType instead of options.

getDefaultOption

public int getDefaultOption()
Get the default option.

Returns:
the default option, represented as YES, NO, OK or CANCEL if an optionType was specified to the constructor of this ConfirmationCallback. Otherwise, this method returns the default option as an index into the options array specified to the constructor of this ConfirmationCallback.

setSelectedIndex

public void setSelectedIndex(int selection)
Set the selected confirmation option.

Parameters:
selection - the selection represented as YES, NO, OK or CANCEL if an optionType was specified to the constructor of this ConfirmationCallback. Otherwise, the selection represents the index into the options array specified to the constructor of this ConfirmationCallback.
See Also:
getSelectedIndex()

getSelectedIndex

public int getSelectedIndex()
Get the selected confirmation option.

Returns:
the selected confirmation option represented as YES, NO, OK or CANCEL if an optionType was specified to the constructor of this ConfirmationCallback. Otherwise, this method returns the selected confirmation option as an index into the options array specified to the constructor of this ConfirmationCallback.
See Also:
setSelectedIndex(int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LanguageCallback

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.callback
Class LanguageCallback

java.lang.Object
    extended by  javax.security.auth.callback.LanguageCallback
All Implemented Interfaces:
Serializable, Callback
public class LanguageCallback
extends Object
implements Callback, Serializable

Underlying security services instantiate and pass a LanguageCallback to the handle method of a CallbackHandler to retrieve the Locale used for localizing text.

See Also:
CallbackHandler, Serialized Form

Constructor Summary
LanguageCallback()
Construct a LanguageCallback.
Method Summary
Locale | getLocale() Get the retrieved Locale.
void | setLocale(Locale locale) Set the retrieved Locale.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LanguageCallback

public LanguageCallback()
Construct a LanguageCallback.

Method Detail

setLocale

public void setLocale(Locale locale)
Set the retrieved Locale.

Parameters:
locale - the retrieved Locale.
See Also:
getLocale()

getLocale

public Locale getLocale()
Get the retrieved Locale.

Returns:
the retrieved Locale, or null if no Locale could be retrieved.
See Also:
setLocale(java.util.Locale)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameCallback

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.callback
Class NameCallback

java.lang.Object
    extended by  javax.security.auth.callback.NameCallback
All Implemented Interfaces:
Serializable, Callback
public class NameCallback
extends Object
implements Callback, Serializable

Underlying security services instantiate and pass a NameCallback to the handle method of a CallbackHandler to retrieve name information.

See Also:
CallbackHandler, Serialized Form

Constructor Summary
NameCallback(String prompt)
Construct a NameCallback with a prompt.
NameCallback(String prompt, String defaultName)
Construct a NameCallback with a prompt and default name.
Method Summary
String | getDefaultName() Get the default name.
String | getName() Get the retrieved name.
String | getPrompt() Get the prompt.
void | setName(String name) Set the retrieved name.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NameCallback

public NameCallback(String prompt)
Construct a NameCallback with a prompt.

Parameters:
prompt - the prompt used to request the name.
Throws:
IllegalArgumentException - if prompt is null or if prompt has a length of 0.

NameCallback

public NameCallback(String prompt,
                    String defaultName)
Construct a NameCallback with a prompt and default name.

Parameters:
prompt - the prompt used to request the information.

defaultName - the name to be used as the default name displayed with the prompt.
Throws:
IllegalArgumentException - if prompt is null, if prompt has a length of 0, if defaultName is null, or if defaultName has a length of 0.
Method Detail

getPrompt

public String getPrompt()
Get the prompt.

Returns:
the prompt.

getDefaultName

public String getDefaultName()
Get the default name.

Returns:
the default name, or null if this NameCallback was not instantiated with a defaultName.

setName

public void setName(String name)
Set the retrieved name.

Parameters:
name - the retrieved name (which may be null).
See Also:
getName()

getName

public String getName()
Get the retrieved name.

Returns:
the retrieved name (which may be null)
See Also:
setName(java.lang.String)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PasswordCallback

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.callback
Class PasswordCallback

java.lang.Object
    extended by  javax.security.auth.callback.PasswordCallback
All Implemented Interfaces:
Serializable, Callback
public class PasswordCallback
extends Object
implements Callback, Serializable

Underlying security services instantiate and pass a PasswordCallback to the handle method of a CallbackHandler to retrieve password information.

See Also:
CallbackHandler, Serialized Form

Constructor Summary
PasswordCallback(String prompt, boolean echoOn)
Construct a PasswordCallback with a prompt and a boolean specifying whether the password should be displayed as it is being typed.
Method Summary
void | clearPassword() Clear the retrieved password.
char[] | getPassword() Get the retrieved password.
String | getPrompt() Get the prompt.
boolean | isEchoOn() Return whether the password should be displayed as it is being typed.
void | setPassword(char[] password) Set the retrieved password.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PasswordCallback

public PasswordCallback(String prompt,
                        boolean echoOn)
Construct a PasswordCallback with a prompt and a boolean specifying whether the password should be displayed as it is being typed.

Parameters:
prompt - the prompt used to request the password.

echoOn - true if the password should be displayed as it is being typed.
Throws:
IllegalArgumentException - if prompt is null or if prompt has a length of 0.
Method Detail

getPrompt

public String getPrompt()
Get the prompt.

Returns:
the prompt.

isEchoOn

public boolean isEchoOn()
Return whether the password should be displayed as it is being typed.

Returns:
the whether the password should be displayed as it is being typed.

setPassword

public void setPassword(char[] password)
Set the retrieved password.

This method makes a copy of the input password before storing it.

Parameters:
password - the retrieved password, which may be null.
See Also:
getPassword()

getPassword

public char[] getPassword()
Get the retrieved password.

This method returns a copy of the retrieved password.

Returns:
the retrieved password, which may be null.
See Also:
setPassword(char[])

clearPassword

public void clearPassword()
Clear the retrieved password.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TextInputCallback

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.callback
Class TextInputCallback

java.lang.Object
    extended by  javax.security.auth.callback.TextInputCallback
All Implemented Interfaces:
Serializable, Callback
Direct Known Subclasses:
RealmCallback
public class TextInputCallback
extends Object
implements Callback, Serializable

Underlying security services instantiate and pass a TextInputCallback to the handle method of a CallbackHandler to retrieve generic text information.

See Also:
CallbackHandler, Serialized Form

Constructor Summary
TextInputCallback(String prompt)
Construct a TextInputCallback with a prompt.
TextInputCallback(String prompt, String defaultText)
Construct a TextInputCallback with a prompt and default input value.
Method Summary
String | getDefaultText() Get the default text.
String | getPrompt() Get the prompt.
String | getText() Get the retrieved text.
void | setText(String text) Set the retrieved text.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TextInputCallback

public TextInputCallback(String prompt)
Construct a TextInputCallback with a prompt.

Parameters:
prompt - the prompt used to request the information.
Throws:
IllegalArgumentException - if prompt is null or if prompt has a length of 0.

TextInputCallback

public TextInputCallback(String prompt,
                         String defaultText)
Construct a TextInputCallback with a prompt and default input value.

Parameters:
prompt - the prompt used to request the information.

defaultText - the text to be used as the default text displayed with the prompt.
Throws:
IllegalArgumentException - if prompt is null, if prompt has a length of 0, if defaultText is null or if defaultText has a length of 0.
Method Detail

getPrompt

public String getPrompt()
Get the prompt.

Returns:
the prompt.

getDefaultText

public String getDefaultText()
Get the default text.

Returns:
the default text, or null if this TextInputCallback was not instantiated with defaultText.

setText

public void setText(String text)
Set the retrieved text.

Parameters:
text - the retrieved text, which may be null.
See Also:
getText()

getText

public String getText()
Get the retrieved text.

Returns:
the retrieved text, which may be null.
See Also:
setText(java.lang.String)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TextOutputCallback

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.callback
Class TextOutputCallback

java.lang.Object
    extended by  javax.security.auth.callback.TextOutputCallback
All Implemented Interfaces:
Serializable, Callback
public class TextOutputCallback
extends Object
implements Callback, Serializable

Underlying security services instantiate and pass a TextOutputCallback to the handle method of a CallbackHandler to display information messages, warning messages and error messages.

See Also:
CallbackHandler, Serialized Form

Field Summary
static int | ERROR Error message.
static int | INFORMATION Information message.
static int | WARNING Warning message.
Constructor Summary
TextOutputCallback(int messageType, String message)
Construct a TextOutputCallback with a message type and message to be displayed.
Method Summary
String | getMessage() Get the message to be displayed.
int | getMessageType() Get the message type.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INFORMATION

public static final int INFORMATION
Information message.

See Also:
Constant Field Values

WARNING

public static final int WARNING
Warning message.

See Also:
Constant Field Values

ERROR

public static final int ERROR
Error message.

See Also:
Constant Field Values
Constructor Detail

TextOutputCallback

public TextOutputCallback(int messageType,
                          String message)
Construct a TextOutputCallback with a message type and message to be displayed.

Parameters:
messageType - the message type (INFORMATION, WARNING or ERROR).

message - the message to be displayed.

Throws:
IllegalArgumentException - if messageType is not either INFORMATION, WARNING or ERROR, if message is null, or if message has a length of 0.
Method Detail

getMessageType

public int getMessageType()
Get the message type.

Returns:
the message type (INFORMATION, WARNING or ERROR).

getMessage

public String getMessage()
Get the message to be displayed.

Returns:
the message to be displayed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UnsupportedCallbackException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.callback
Class UnsupportedCallbackException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.security.auth.callback.UnsupportedCallbackException
All Implemented Interfaces:
Serializable
public class UnsupportedCallbackException
extends Exception

Signals that a CallbackHandler does not recognize a particular Callback.

See Also:
Serialized Form

Constructor Summary
UnsupportedCallbackException(Callback callback)
Constructs a UnsupportedCallbackException with no detail message.
UnsupportedCallbackException(Callback callback, String msg)
Constructs a UnsupportedCallbackException with the specified detail message.
Method Summary
 Callback getCallback()
Get the unrecognized Callback.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UnsupportedCallbackException

public UnsupportedCallbackException(Callback callback)
Constructs a UnsupportedCallbackException with no detail message.

Parameters:
callback - the unrecognized Callback.

UnsupportedCallbackException

public UnsupportedCallbackException(Callback callback,
                                    String msg)
Constructs a UnsupportedCallbackException with the specified detail message. A detail message is a String that describes this particular exception.

Parameters:
callback - the unrecognized Callback.

msg - the detail message.
Method Detail

getCallback

public Callback getCallback()
Get the unrecognized Callback.

Returns:
the unrecognized Callback.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.security.auth.AuthPermission

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.AuthPermission

No usage of javax.security.auth.AuthPermission

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.DestroyFailedException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.DestroyFailedException

Packages that use DestroyFailedException
java.security | Provides the classes and interfaces for the security framework.
javax.security.auth | This package provides a framework for authentication and authorization.
javax.security.auth.kerberos | This package contains utility classes related to the Kerberos network authentication protocol.

Uses of DestroyFailedException in java.security

Methods in java.security that throw DestroyFailedException
 void KeyStore.PasswordProtection.destroy()
Clears the password.

Uses of DestroyFailedException in javax.security.auth

Methods in javax.security.auth that throw DestroyFailedException
 void Destroyable.destroy()
Destroy this Object.

Uses of DestroyFailedException in javax.security.auth.kerberos

Methods in javax.security.auth.kerberos that throw DestroyFailedException
void | KerberosTicket.destroy() Destroys the ticket and destroys any sensitive information stored in it.
void | KerberosKey.destroy() Destroys this key.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.Policy

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.Policy

Packages that use Policy
javax.security.auth This package provides a framework for authentication and authorization.

Uses of Policy in javax.security.auth

Methods in javax.security.auth that return Policy
static Policy Policy.getPolicy()
Deprecated. Returns the installed Policy object.

Methods in javax.security.auth with parameters of type Policy
static void Policy.setPolicy(Policy policy)
Deprecated. Sets the system-wide Policy object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.PrivateCredentialPermission

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.PrivateCredentialPermission

No usage of javax.security.auth.PrivateCredentialPermission

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.RefreshFailedException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.RefreshFailedException

Packages that use RefreshFailedException
javax.security.auth | This package provides a framework for authentication and authorization.
javax.security.auth.kerberos | This package contains utility classes related to the Kerberos network authentication protocol.

Uses of RefreshFailedException in javax.security.auth

Methods in javax.security.auth that throw RefreshFailedException
 void Refreshable.refresh()
Update or extend the validity period for this Object.

Uses of RefreshFailedException in javax.security.auth.kerberos

Methods in javax.security.auth.kerberos that throw RefreshFailedException
 void KerberosTicket.refresh()
Extends the validity period of this ticket.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.Subject

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.Subject

Packages that use Subject
java.security | Provides the classes and interfaces for the security framework.
javax.management.remote | Interfaces for remote access to JMX MBean servers.
javax.management.remote.rmi | The RMI connector is a connector for the JMX Remote API that uses RMI to transmit client requests to a remote MBean server.
javax.security.auth | This package provides a framework for authentication and authorization.
javax.security.auth.login | This package provides a pluggable authentication framework.
javax.security.auth.spi | This package provides the interface to be used for implementing pluggable authentication modules.

Uses of Subject in java.security

Methods in java.security with parameters of type Subject
abstract  void AuthProvider.login(Subject subject, CallbackHandler handler)
Log in to this provider.

Uses of Subject in javax.management.remote

Methods in javax.management.remote that return Subject
 Subject JMXAuthenticator.authenticate(Object credentials)
Authenticates the MBeanServerConnection client with the given client credentials.

Methods in javax.management.remote with parameters of type Subject
 MBeanServerConnection JMXConnector.getMBeanServerConnection(Subject delegationSubject)
Returns an MBeanServerConnection object representing a remote MBean server on which operations are performed on behalf of the supplied delegation subject.

Uses of Subject in javax.management.remote.rmi

Methods in javax.management.remote.rmi with parameters of type Subject
 void RMIConnectionImpl_Stub.addNotificationListener(ObjectName $param_ObjectName_1, ObjectName $param_ObjectName_2, MarshalledObject $param_MarshalledObject_3, MarshalledObject $param_MarshalledObject_4, Subject $param_Subject_5)
 void RMIConnectionImpl.addNotificationListener(ObjectName name, ObjectName listener, MarshalledObject filter, MarshalledObject handback, Subject delegationSubject)
 void RMIConnection.addNotificationListener(ObjectName name, ObjectName listener, MarshalledObject filter, MarshalledObject handback, Subject delegationSubject)
Handles the method MBeanServerConnection.addNotificationListener(ObjectName, ObjectName, NotificationFilter, Object).
 Integer[] RMIConnectionImpl_Stub.addNotificationListeners(ObjectName[] $param_arrayOf_ObjectName_1, MarshalledObject[] $param_arrayOf_MarshalledObject_2, Subject[] $param_arrayOf_Subject_3)
 Integer[] RMIConnectionImpl.addNotificationListeners(ObjectName[] names, MarshalledObject[] filters, Subject[] delegationSubjects)
 Integer[] RMIConnection.addNotificationListeners(ObjectName[] names, MarshalledObject[] filters, Subject[] delegationSubjects)
Handles the method MBeanServerConnection.addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object).
 ObjectInstance RMIConnectionImpl_Stub.createMBean(String $param_String_1, ObjectName $param_ObjectName_2, MarshalledObject $param_MarshalledObject_3, String[] $param_arrayOf_String_4, Subject $param_Subject_5)
 ObjectInstance RMIConnectionImpl.createMBean(String className, ObjectName name, MarshalledObject params, String[] signature, Subject delegationSubject)
 ObjectInstance RMIConnection.createMBean(String className, ObjectName name, MarshalledObject params, String[] signature, Subject delegationSubject)
Handles the method MBeanServerConnection.createMBean(String, ObjectName, Object[], String[]).
 ObjectInstance RMIConnectionImpl_Stub.createMBean(String $param_String_1, ObjectName $param_ObjectName_2, ObjectName $param_ObjectName_3, MarshalledObject $param_MarshalledObject_4, String[] $param_arrayOf_String_5, Subject $param_Subject_6)
 ObjectInstance RMIConnectionImpl.createMBean(String className, ObjectName name, ObjectName loaderName, MarshalledObject params, String[] signature, Subject delegationSubject)
 ObjectInstance RMIConnection.createMBean(String className, ObjectName name, ObjectName loaderName, MarshalledObject params, String[] signature, Subject delegationSubject)
Handles the method MBeanServerConnection.createMBean(String, ObjectName, ObjectName, Object[], String[]).
 ObjectInstance RMIConnectionImpl_Stub.createMBean(String $param_String_1, ObjectName $param_ObjectName_2, ObjectName $param_ObjectName_3, Subject $param_Subject_4)
 ObjectInstance RMIConnectionImpl.createMBean(String className, ObjectName name, ObjectName loaderName, Subject delegationSubject)
 ObjectInstance RMIConnection.createMBean(String className, ObjectName name, ObjectName loaderName, Subject delegationSubject)
Handles the method MBeanServerConnection.createMBean(String, ObjectName, ObjectName).
 ObjectInstance RMIConnectionImpl_Stub.createMBean(String $param_String_1, ObjectName $param_ObjectName_2, Subject $param_Subject_3)
 ObjectInstance RMIConnectionImpl.createMBean(String className, ObjectName name, Subject delegationSubject)
 ObjectInstance RMIConnection.createMBean(String className, ObjectName name, Subject delegationSubject)
Handles the method MBeanServerConnection.createMBean(String, ObjectName).
 Object RMIConnectionImpl_Stub.getAttribute(ObjectName $param_ObjectName_1, String $param_String_2, Subject $param_Subject_3)
 Object RMIConnectionImpl.getAttribute(ObjectName name, String attribute, Subject delegationSubject)
 Object RMIConnection.getAttribute(ObjectName name, String attribute, Subject delegationSubject)
Handles the method MBeanServerConnection.getAttribute(ObjectName, String).
 AttributeList RMIConnectionImpl_Stub.getAttributes(ObjectName $param_ObjectName_1, String[] $param_arrayOf_String_2, Subject $param_Subject_3)
 AttributeList RMIConnectionImpl.getAttributes(ObjectName name, String[] attributes, Subject delegationSubject)
 AttributeList RMIConnection.getAttributes(ObjectName name, String[] attributes, Subject delegationSubject)
Handles the method MBeanServerConnection.getAttributes(ObjectName, String[]).
 String RMIConnectionImpl_Stub.getDefaultDomain(Subject $param_Subject_1)
 String RMIConnectionImpl.getDefaultDomain(Subject delegationSubject)
 String RMIConnection.getDefaultDomain(Subject delegationSubject)
Handles the method MBeanServerConnection.getDefaultDomain().
 String[] RMIConnectionImpl_Stub.getDomains(Subject $param_Subject_1)
 String[] RMIConnectionImpl.getDomains(Subject delegationSubject)
 String[] RMIConnection.getDomains(Subject delegationSubject)
Handles the method MBeanServerConnection.getDomains().
 Integer RMIConnectionImpl_Stub.getMBeanCount(Subject $param_Subject_1)
 Integer RMIConnectionImpl.getMBeanCount(Subject delegationSubject)
 Integer RMIConnection.getMBeanCount(Subject delegationSubject)
Handles the method MBeanServerConnection.getMBeanCount().
 MBeanInfo RMIConnectionImpl_Stub.getMBeanInfo(ObjectName $param_ObjectName_1, Subject $param_Subject_2)
 MBeanInfo RMIConnectionImpl.getMBeanInfo(ObjectName name, Subject delegationSubject)
 MBeanInfo RMIConnection.getMBeanInfo(ObjectName name, Subject delegationSubject)
Handles the method MBeanServerConnection.getMBeanInfo(ObjectName).
 MBeanServerConnection RMIConnector.getMBeanServerConnection(Subject delegationSubject)
 ObjectInstance RMIConnectionImpl_Stub.getObjectInstance(ObjectName $param_ObjectName_1, Subject $param_Subject_2)
 ObjectInstance RMIConnectionImpl.getObjectInstance(ObjectName name, Subject delegationSubject)
 ObjectInstance RMIConnection.getObjectInstance(ObjectName name, Subject delegationSubject)
Handles the method MBeanServerConnection.getObjectInstance(ObjectName).
 Object RMIConnectionImpl_Stub.invoke(ObjectName $param_ObjectName_1, String $param_String_2, MarshalledObject $param_MarshalledObject_3, String[] $param_arrayOf_String_4, Subject $param_Subject_5)
 Object RMIConnectionImpl.invoke(ObjectName name, String operationName, MarshalledObject params, String[] signature, Subject delegationSubject)
 Object RMIConnection.invoke(ObjectName name, String operationName, MarshalledObject params, String[] signature, Subject delegationSubject)
Handles the method MBeanServerConnection.invoke(ObjectName, String, Object[], String[]).
 boolean RMIConnectionImpl_Stub.isInstanceOf(ObjectName $param_ObjectName_1, String $param_String_2, Subject $param_Subject_3)
 boolean RMIConnectionImpl.isInstanceOf(ObjectName name, String className, Subject delegationSubject)
 boolean RMIConnection.isInstanceOf(ObjectName name, String className, Subject delegationSubject)
Handles the method MBeanServerConnection.isInstanceOf(ObjectName, String).
 boolean RMIConnectionImpl_Stub.isRegistered(ObjectName $param_ObjectName_1, Subject $param_Subject_2)
 boolean RMIConnectionImpl.isRegistered(ObjectName name, Subject delegationSubject)
 boolean RMIConnection.isRegistered(ObjectName name, Subject delegationSubject)
Handles the method MBeanServerConnection.isRegistered(ObjectName).
protected  RMIConnection RMIIIOPServerImpl.makeClient(String connectionId, Subject subject)
Creates a new client connection as an RMI object exported through IIOP.
protected  RMIConnection RMIJRMPServerImpl.makeClient(String connectionId, Subject subject)
Creates a new client connection as an RMI object exported through JRMP.
protected abstract  RMIConnection RMIServerImpl.makeClient(String connectionId, Subject subject)
Creates a new client connection.
 Set RMIConnectionImpl_Stub.queryMBeans(ObjectName $param_ObjectName_1, MarshalledObject $param_MarshalledObject_2, Subject $param_Subject_3)
 Set<ObjectInstance> RMIConnectionImpl.queryMBeans(ObjectName name, MarshalledObject query, Subject delegationSubject)
 Set<ObjectInstance> RMIConnection.queryMBeans(ObjectName name, MarshalledObject query, Subject delegationSubject)
Handles the method MBeanServerConnection.queryMBeans(ObjectName, QueryExp).
 Set RMIConnectionImpl_Stub.queryNames(ObjectName $param_ObjectName_1, MarshalledObject $param_MarshalledObject_2, Subject $param_Subject_3)
 Set<ObjectName> RMIConnectionImpl.queryNames(ObjectName name, MarshalledObject query, Subject delegationSubject)
 Set<ObjectName> RMIConnection.queryNames(ObjectName name, MarshalledObject query, Subject delegationSubject)
Handles the method MBeanServerConnection.queryNames(ObjectName, QueryExp).
 void RMIConnectionImpl_Stub.removeNotificationListener(ObjectName $param_ObjectName_1, ObjectName $param_ObjectName_2, MarshalledObject $param_MarshalledObject_3, MarshalledObject $param_MarshalledObject_4, Subject $param_Subject_5)
 void RMIConnectionImpl.removeNotificationListener(ObjectName name, ObjectName listener, MarshalledObject filter, MarshalledObject handback, Subject delegationSubject)
 void RMIConnection.removeNotificationListener(ObjectName name, ObjectName listener, MarshalledObject filter, MarshalledObject handback, Subject delegationSubject)
Handles the method MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName, NotificationFilter, Object).
 void RMIConnectionImpl_Stub.removeNotificationListener(ObjectName $param_ObjectName_1, ObjectName $param_ObjectName_2, Subject $param_Subject_3)
 void RMIConnectionImpl.removeNotificationListener(ObjectName name, ObjectName listener, Subject delegationSubject)
 void RMIConnection.removeNotificationListener(ObjectName name, ObjectName listener, Subject delegationSubject)
Handles the method MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName).
 void RMIConnectionImpl_Stub.removeNotificationListeners(ObjectName $param_ObjectName_1, Integer[] $param_arrayOf_Integer_2, Subject $param_Subject_3)
 void RMIConnectionImpl.removeNotificationListeners(ObjectName name, Integer[] listenerIDs, Subject delegationSubject)
 void RMIConnection.removeNotificationListeners(ObjectName name, Integer[] listenerIDs, Subject delegationSubject)
Handles the removeNotificationListener(ObjectName, NotificationListener) and removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object) methods.
 void RMIConnectionImpl_Stub.setAttribute(ObjectName $param_ObjectName_1, MarshalledObject $param_MarshalledObject_2, Subject $param_Subject_3)
 void RMIConnectionImpl.setAttribute(ObjectName name, MarshalledObject attribute, Subject delegationSubject)
 void RMIConnection.setAttribute(ObjectName name, MarshalledObject attribute, Subject delegationSubject)
Handles the method MBeanServerConnection.setAttribute(ObjectName, Attribute).
 AttributeList RMIConnectionImpl_Stub.setAttributes(ObjectName $param_ObjectName_1, MarshalledObject $param_MarshalledObject_2, Subject $param_Subject_3)
 AttributeList RMIConnectionImpl.setAttributes(ObjectName name, MarshalledObject attributes, Subject delegationSubject)
 AttributeList RMIConnection.setAttributes(ObjectName name, MarshalledObject attributes, Subject delegationSubject)
Handles the method MBeanServerConnection.setAttributes(ObjectName, AttributeList).
 void RMIConnectionImpl_Stub.unregisterMBean(ObjectName $param_ObjectName_1, Subject $param_Subject_2)
 void RMIConnectionImpl.unregisterMBean(ObjectName name, Subject delegationSubject)
 void RMIConnection.unregisterMBean(ObjectName name, Subject delegationSubject)
Handles the method MBeanServerConnection.unregisterMBean(ObjectName).

Constructors in javax.management.remote.rmi with parameters of type Subject
RMIConnectionImpl(RMIServerImpl rmiServer, String connectionId, ClassLoader defaultClassLoader, Subject subject, Map<String,?> env)
Constructs a new RMIConnection.

Uses of Subject in javax.security.auth

Methods in javax.security.auth that return Subject
Subject | SubjectDomainCombiner.getSubject() Get the Subject associated with this SubjectDomainCombiner.
static Subject | Subject.getSubject(AccessControlContext acc) Get the Subject associated with the provided AccessControlContext.

Methods in javax.security.auth with parameters of type Subject
static
<T> T
Subject.doAs(Subject subject, PrivilegedAction<T> action)
Perform work as a particular Subject.
static
<T> T
Subject.doAs(Subject subject, PrivilegedExceptionAction<T> action)
Perform work as a particular Subject.
static
<T> T
Subject.doAsPrivileged(Subject subject, PrivilegedAction<T> action, AccessControlContext acc)
Perform privileged work as a particular Subject.
static
<T> T
Subject.doAsPrivileged(Subject subject, PrivilegedExceptionAction<T> action, AccessControlContext acc)
Perform privileged work as a particular Subject.
abstract  PermissionCollection Policy.getPermissions(Subject subject, CodeSource cs)
Deprecated. Retrieve the Permissions granted to the Principals associated with the specified CodeSource.

Constructors in javax.security.auth with parameters of type Subject
SubjectDomainCombiner(Subject subject)
Associate the provided Subject with this SubjectDomainCombiner.

Uses of Subject in javax.security.auth.login

Methods in javax.security.auth.login that return Subject
 Subject LoginContext.getSubject()
Return the authenticated Subject.

Constructors in javax.security.auth.login with parameters of type Subject
LoginContext(String name, Subject subject)
Instantiate a new LoginContext object with a name and a Subject object.
LoginContext(String name, Subject subject, CallbackHandler callbackHandler)
Instantiate a new LoginContext object with a name, a Subject to be authenticated, and a CallbackHandler object.
LoginContext(String name, Subject subject, CallbackHandler callbackHandler, Configuration config)
Instantiate a new LoginContext object with a name, a Subject to be authenticated, a CallbackHandler object, and a login Configuration.

Uses of Subject in javax.security.auth.spi

Methods in javax.security.auth.spi with parameters of type Subject
 void LoginModule.initialize(Subject subject, CallbackHandler callbackHandler, Map<String,?> sharedState, Map<String,?> options)
Initialize this LoginModule.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.SubjectDomainCombiner

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.SubjectDomainCombiner

No usage of javax.security.auth.SubjectDomainCombiner

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.security.auth.Destroyable

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.security.auth.Destroyable

Packages that use Destroyable
java.security | Provides the classes and interfaces for the security framework.
javax.security.auth.kerberos | This package contains utility classes related to the Kerberos network authentication protocol.
javax.security.auth.x500 | This package contains the classes that should be used to store X500 Principal and X500 Private Crendentials in a Subject.

Uses of Destroyable in java.security

Classes in java.security that implement Destroyable
static class KeyStore.PasswordProtection
A password-based implementation of ProtectionParameter.

Uses of Destroyable in javax.security.auth.kerberos

Classes in javax.security.auth.kerberos that implement Destroyable
class | KerberosKey This class encapsulates a long term secret key for a Kerberos principal.
class | KerberosTicket This class encapsulates a Kerberos ticket and associated information as viewed from the client's point of view.

Uses of Destroyable in javax.security.auth.x500

Classes in javax.security.auth.x500 that implement Destroyable
 class X500PrivateCredential
This class represents an X500PrivateCredential.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.security.auth.Refreshable

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.security.auth.Refreshable

Packages that use Refreshable
javax.security.auth.kerberos This package contains utility classes related to the Kerberos network authentication protocol.

Uses of Refreshable in javax.security.auth.kerberos

Classes in javax.security.auth.kerberos that implement Refreshable
 class KerberosTicket
This class encapsulates a Kerberos ticket and associated information as viewed from the client's point of view.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Destroyable

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth
Interface Destroyable

All Known Implementing Classes:
KerberosKey, KerberosTicket, KeyStore.PasswordProtection, X500PrivateCredential
public interface Destroyable

Objects such as credentials may optionally implement this interface to provide the capability to destroy its contents.

See Also:
Subject

Method Summary
void | destroy() Destroy this Object.
boolean | isDestroyed() Determine if this Object has been destroyed.

Method Detail

destroy

void destroy()
             throws DestroyFailedException
Destroy this Object.

Sensitive information associated with this Object is destroyed or cleared. Subsequent calls to certain methods on this Object will result in an IllegalStateException being thrown.

Throws:
DestroyFailedException - if the destroy operation fails.

SecurityException - if the caller does not have permission to destroy this Object.

isDestroyed

boolean isDestroyed()
Determine if this Object has been destroyed.

Returns:
true if this Object has been destroyed, false otherwise.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DestroyFailedException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth
Class DestroyFailedException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.security.auth.DestroyFailedException
All Implemented Interfaces:
Serializable
public class DestroyFailedException
extends Exception

Signals that a destroy operation failed.

This exception is thrown by credentials implementing the Destroyable interface when the destroy method fails.

See Also:
Serialized Form

Constructor Summary
DestroyFailedException()
Constructs a DestroyFailedException with no detail message.
DestroyFailedException(String msg)
Constructs a DestroyFailedException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DestroyFailedException

public DestroyFailedException()
Constructs a DestroyFailedException with no detail message. A detail message is a String that describes this particular exception.

DestroyFailedException

public DestroyFailedException(String msg)
Constructs a DestroyFailedException with the specified detail message. A detail message is a String that describes this particular exception.

Parameters:
msg - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


kerberos

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.security.auth.kerberos

This package contains utility classes related to the Kerberos network authentication protocol.

See:
Description

Class Summary
DelegationPermission | This class is used to restrict the usage of the Kerberos delegation model, ie: forwardable and proxiable tickets.
KerberosKey | This class encapsulates a long term secret key for a Kerberos principal.
KerberosPrincipal | This class encapsulates a Kerberos principal.
KerberosTicket | This class encapsulates a Kerberos ticket and associated information as viewed from the client's point of view.
ServicePermission | This class is used to protect Kerberos services and the credentials necessary to access those services.

Package javax.security.auth.kerberos Description

This package contains utility classes related to the Kerberos network authentication protocol. They do not provide much Kerberos support themselves.

The Kerberos network authentication protocol is defined in RFC 1510. The Java platform contains support for the client side of Kerberos via the org.ietf.jgss package. There might also be a login module that implements LoginModule to authenticate Kerberos principals.

You can provide the name of your default realm and Key Distribution Center (KDC) host for that realm using the system properties java.security.krb5.realm and java.security.krb5.kdc. Alternatively, you can provide an MIT style configuration file called krb5.conf in <java-home>/lib/security. If you place this file elsewhere, you can indicate that location via the system property java.security.krb5.conf.

Since:
JDK1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.security.auth.kerberos Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.security.auth.kerberos

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.security.auth.kerberos.KerberosKey (implements javax.security.auth.Destroyable, javax.crypto.SecretKey)
    • javax.security.auth.kerberos.KerberosPrincipal (implements java.security.Principal, java.io.Serializable)
    • javax.security.auth.kerberos.KerberosTicket (implements javax.security.auth.Destroyable, javax.security.auth.Refreshable, java.io.Serializable)
    • java.security.Permission (implements java.security.Guard, java.io.Serializable)
      • java.security.BasicPermission (implements java.io.Serializable)
        • javax.security.auth.kerberos.DelegationPermission (implements java.io.Serializable)
      • javax.security.auth.kerberos.ServicePermission (implements java.io.Serializable)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.security.auth.kerberos

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.security.auth.kerberos

Packages that use javax.security.auth.kerberos
javax.security.auth.kerberos This package contains utility classes related to the Kerberos network authentication protocol.

Classes in javax.security.auth.kerberos used by javax.security.auth.kerberos
KerberosPrincipal
This class encapsulates a Kerberos principal.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.kerberos.DelegationPermission

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.kerberos.DelegationPermission

No usage of javax.security.auth.kerberos.DelegationPermission

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.kerberos.KerberosKey

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.kerberos.KerberosKey

No usage of javax.security.auth.kerberos.KerberosKey

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.kerberos.KerberosPrincipal

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.kerberos.KerberosPrincipal

Packages that use KerberosPrincipal
javax.security.auth.kerberos This package contains utility classes related to the Kerberos network authentication protocol.

Uses of KerberosPrincipal in javax.security.auth.kerberos

Methods in javax.security.auth.kerberos that return KerberosPrincipal
KerberosPrincipal | KerberosTicket.getClient() Returns the client principal associated with this ticket.
KerberosPrincipal | KerberosKey.getPrincipal() Returns the principal that this key belongs to.
KerberosPrincipal | KerberosTicket.getServer() Returns the service principal associated with this ticket.

Constructors in javax.security.auth.kerberos with parameters of type KerberosPrincipal
KerberosKey(KerberosPrincipal principal, byte[] keyBytes, int keyType, int versionNum)
Constructs a KerberosKey from the given bytes when the key type and key version number are known.
KerberosKey(KerberosPrincipal principal, char[] password, String algorithm)
Constructs a KerberosKey from a principal's password.
KerberosTicket(byte[] asn1Encoding, KerberosPrincipal client, KerberosPrincipal server, byte[] sessionKey, int keyType, boolean[] flags, Date authTime, Date startTime, Date endTime, Date renewTill, InetAddress[] clientAddresses)
Constructs a KerberosTicket using credentials information that a client either receives from a KDC or reads from a cache.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.kerberos.KerberosTicket

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.kerberos.KerberosTicket

No usage of javax.security.auth.kerberos.KerberosTicket

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.kerberos.ServicePermission

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.kerberos.ServicePermission

No usage of javax.security.auth.kerberos.ServicePermission

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DelegationPermission

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.kerberos
Class DelegationPermission

java.lang.Object
    extended by  java.security.Permission
        extended by  java.security.BasicPermission
            extended by  javax.security.auth.kerberos.DelegationPermission
All Implemented Interfaces:
Serializable, Guard
public final class DelegationPermission
extends BasicPermission
implements Serializable

This class is used to restrict the usage of the Kerberos delegation model, ie: forwardable and proxiable tickets.

The target name of this Permission specifies a pair of kerberos service principals. The first is the subordinate service principal being entrusted to use the TGT. The second service principal designates the target service the subordinate service principal is to interact with on behalf of the initiating KerberosPrincipal. This latter service principal is specified to restrict the use of a proxiable ticket.

For example, to specify the "host" service use of a forwardable TGT the target permission is specified as follows:

  DelegationPermission("\"host/foo.example.com@EXAMPLE.COM\" \"krbtgt/EXAMPLE.COM@EXAMPLE.COM\"");

To give the "backup" service a proxiable nfs service ticket the target permission might be specified:

  DelegationPermission("\"backup/bar.example.com@EXAMPLE.COM\" \"nfs/home.EXAMPLE.COM@EXAMPLE.COM\"");

Since:
1.4
See Also:
Serialized Form

Constructor Summary
DelegationPermission(String principals)
Create a new DelegationPermission with the specified subordinate and target principals.
DelegationPermission(String principals, String actions)
Create a new DelegationPermission with the specified subordinate and target principals.
Method Summary
boolean | equals(Object obj) Checks two DelegationPermission objects for equality.
int | hashCode() Returns the hash code value for this object.
boolean | implies(Permission p) Checks if this Kerberos delegation permission object "implies" the specified permission.
PermissionCollection | newPermissionCollection() Returns a PermissionCollection object for storing DelegationPermission objects.
Methods inherited from class java.security.BasicPermission
getActions
Methods inherited from class java.security.Permission
checkGuard, getName, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DelegationPermission

public DelegationPermission(String principals)
Create a new DelegationPermission with the specified subordinate and target principals.

Parameters:
principals - the name of the subordinate and target principals
Throws:
NullPointerException - if principals is null.
IllegalArgumentException - if principals is empty.

DelegationPermission

public DelegationPermission(String principals,
                            String actions)
Create a new DelegationPermission with the specified subordinate and target principals.

Parameters:
principals - the name of the subordinate and target principals

actions - should be null.
Throws:
NullPointerException - if principals is null.
IllegalArgumentException - if principals is empty.
Method Detail

implies

public boolean implies(Permission p)
Checks if this Kerberos delegation permission object "implies" the specified permission.

If none of the above are true, implies returns false.

Overrides:
implies in class BasicPermission
Parameters:
p - the permission to check against.
Returns:
true if the specified permission is implied by this object, false if not.

equals

public boolean equals(Object obj)
Checks two DelegationPermission objects for equality.

Overrides:
equals in class BasicPermission
Parameters:
obj - the object to test for equality with this object.
Returns:
true if obj is a DelegationPermission, and has the same subordinate and service principal as this. DelegationPermission object.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns the hash code value for this object.

Overrides:
hashCode in class BasicPermission
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

newPermissionCollection

public PermissionCollection newPermissionCollection()
Returns a PermissionCollection object for storing DelegationPermission objects.
DelegationPermission objects must be stored in a manner that allows them to be inserted into the collection in any order, but that also enables the PermissionCollection implies method to be implemented in an efficient (and consistent) manner.

Overrides:
newPermissionCollection in class BasicPermission
Returns:
a new PermissionCollection object suitable for storing DelegationPermissions.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


KerberosKey

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.kerberos
Class KerberosKey

java.lang.Object
    extended by  javax.security.auth.kerberos.KerberosKey
All Implemented Interfaces:
Serializable, Key, SecretKey, Destroyable
public class KerberosKey
extends Object
implements SecretKey, Destroyable

This class encapsulates a long term secret key for a Kerberos principal.

All Kerberos JAAS login modules that obtain a principal's password and generate the secret key from it should use this class. Where available, the login module might even read this secret key directly from a Kerberos "keytab". Sometimes, such as when authenticating a server in the absence of user-to-user authentication, the login module will store an instance of this class in the private credential set of a Subject during the commit phase of the authentication process.

It might be necessary for the application to be granted a PrivateCredentialPermission if it needs to access the KerberosKey instance from a Subject. This permission is not needed when the application depends on the default JGSS Kerberos mechanism to access the KerberosKey. In that case, however, the application will need an appropriate ServicePermission.

Since:
1.4
See Also:
Serialized Form

Constructor Summary
KerberosKey(KerberosPrincipal principal, byte[] keyBytes, int keyType, int versionNum)
Constructs a KerberosKey from the given bytes when the key type and key version number are known.
KerberosKey(KerberosPrincipal principal, char[] password, String algorithm)
Constructs a KerberosKey from a principal's password.
Method Summary
void | destroy() Destroys this key.
boolean | equals(Object other) Compares the specified Object with this KerberosKey for equality.
String | getAlgorithm() Returns the standard algorithm name for this key.
byte[] | getEncoded() Returns the key material of this secret key.
String | getFormat() Returns the name of the encoding format for this secret key.
int | getKeyType() Returns the key type for this long-term key.
KerberosPrincipal | getPrincipal() Returns the principal that this key belongs to.
int | getVersionNumber() Returns the key version number.
int | hashCode() Returns a hashcode for this KerberosKey.
boolean | isDestroyed() Determines if this key has been destroyed.
String | toString() Returns a string representation of the object.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

KerberosKey

public KerberosKey(KerberosPrincipal principal,
                   byte[] keyBytes,
                   int keyType,
                   int versionNum)
Constructs a KerberosKey from the given bytes when the key type and key version number are known. This can be used when reading the secret key information from a Kerberos "keytab".

Parameters:
principal - the principal that this secret key belongs to
keyBytes - the raw bytes for the secret key
keyType - the key type for the secret key as defined by the Kerberos protocol specification.
versionNum - the version number of this secret key

KerberosKey

public KerberosKey(KerberosPrincipal principal,
                   char[] password,
                   String algorithm)
Constructs a KerberosKey from a principal's password.

Parameters:
principal - the principal that this password belongs to
password - the password that should be used to compute the key
algorithm - the name for the algorithm that this key will be used for. This parameter may be null in which case the default algorithm "DES" will be assumed.
Throws:
IllegalArgumentException - if the name of the algorithm passed is unsupported.
Method Detail

getPrincipal

public final KerberosPrincipal getPrincipal()
Returns the principal that this key belongs to.

Returns:
the principal this key belongs to.

getVersionNumber

public final int getVersionNumber()
Returns the key version number.

Returns:
the key version number.

getKeyType

public final int getKeyType()
Returns the key type for this long-term key.

Returns:
the key type.

getAlgorithm

public final String getAlgorithm()
Returns the standard algorithm name for this key. For example, "DES" would indicate that this key is a DES key. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.

Specified by:
getAlgorithm in interface Key
Returns:
the name of the algorithm associated with this key.

getFormat

public final String getFormat()
Returns the name of the encoding format for this secret key.

Specified by:
getFormat in interface Key
Returns:
the String "RAW"

getEncoded

public final byte[] getEncoded()
Returns the key material of this secret key.

Specified by:
getEncoded in interface Key
Returns:
the key material

destroy

public void destroy()
             throws DestroyFailedException
Destroys this key. A call to any of its other methods after this will cause an IllegalStateException to be thrown.

Specified by:
destroy in interface Destroyable
Throws:
DestroyFailedException - if some error occurs while destorying this key.

isDestroyed

public boolean isDestroyed()
Determines if this key has been destroyed.

Specified by:
isDestroyed in interface Destroyable
Returns:
true if this Object has been destroyed, false otherwise.

toString

public String toString()
Description copied from class: Object
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())

Overrides:
toString in class Object
Returns:
a string representation of the object.

hashCode

public int hashCode()
Returns a hashcode for this KerberosKey.

Overrides:
hashCode in class Object
Returns:
a hashCode() for the KerberosKey
Since:
1.6
See Also:
Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object other)
Compares the specified Object with this KerberosKey for equality. Returns true if the given object is also a KerberosKey and the two KerberosKey instances are equivalent.

Overrides:
equals in class Object
Parameters:
other - the Object to compare to
Returns:
true if the specified object is equal to this KerberosKey, false otherwise. NOTE: Returns false if either of the KerberosKey objects has been destroyed.
Since:
1.6
See Also:
Object.hashCode(), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


KerberosPrincipal

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.kerberos
Class KerberosPrincipal

java.lang.Object
    extended by  javax.security.auth.kerberos.KerberosPrincipal
All Implemented Interfaces:
Serializable, Principal
public final class KerberosPrincipal
extends Object
implements Principal, Serializable

This class encapsulates a Kerberos principal.

Since:
1.4
See Also:
Serialized Form

Field Summary
static int | KRB_NT_PRINCIPAL user principal name type.
static int | KRB_NT_SRV_HST service with host name as instance (telnet, rcommands) name type.
static int | KRB_NT_SRV_INST service and other unique instance (krbtgt) name type.
static int | KRB_NT_SRV_XHST service with host as remaining components name type.
static int | KRB_NT_UID unique ID name type.
static int | KRB_NT_UNKNOWN unknown name type.
Constructor Summary
KerberosPrincipal(String name)
Constructs a KerberosPrincipal from the provided string input.
KerberosPrincipal(String name, int nameType)
Constructs a KerberosPrincipal from the provided string and name type input.
Method Summary
boolean | equals(Object other) Compares the specified Object with this Principal for equality.
String | getName() The returned string corresponds to the single-string representation of a Kerberos Principal name as specified in Section 2.1 of RFC 1964.
int | getNameType() Returns the name type of the KerberosPrincipal.
String | getRealm() Returns the realm component of this Kerberos principal.
int | hashCode() Returns a hashcode for this principal.
String | toString() Returns a string representation of the object.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

KRB_NT_UNKNOWN

public static final int KRB_NT_UNKNOWN
unknown name type.

See Also:
Constant Field Values

KRB_NT_PRINCIPAL

public static final int KRB_NT_PRINCIPAL
user principal name type.

See Also:
Constant Field Values

KRB_NT_SRV_INST

public static final int KRB_NT_SRV_INST
service and other unique instance (krbtgt) name type.

See Also:
Constant Field Values

KRB_NT_SRV_HST

public static final int KRB_NT_SRV_HST
service with host name as instance (telnet, rcommands) name type.

See Also:
Constant Field Values

KRB_NT_SRV_XHST

public static final int KRB_NT_SRV_XHST
service with host as remaining components name type.

See Also:
Constant Field Values

KRB_NT_UID

public static final int KRB_NT_UID
unique ID name type.

See Also:
Constant Field Values
Constructor Detail

KerberosPrincipal

public KerberosPrincipal(String name)
Constructs a KerberosPrincipal from the provided string input. The name type for this principal defaults to KRB_NT_PRINCIPAL This string is assumed to contain a name in the format that is specified in Section 2.1.1. (Kerberos Principal Name Form) of RFC 1964 (for example, duke@FOO.COM, where duke represents a principal, and FOO.COM represents a realm).

If the input name does not contain a realm, the default realm is used. The default realm can be specified either in a Kerberos configuration file or via the java.security.krb5.realm system property. For more information, Kerberos Requirements

Parameters:
name - the principal name
Throws:
IllegalArgumentException - if name is improperly formatted, if name is null, or if name does not contain the realm to use and the default realm is not specified in either a Kerberos configuration file or via the java.security.krb5.realm system property.

KerberosPrincipal

public KerberosPrincipal(String name,
                         int nameType)
Constructs a KerberosPrincipal from the provided string and name type input. The string is assumed to contain a name in the format that is specified in Section 2.1 (Mandatory Name Forms) of RFC 1964. Valid name types are specified in Section 7.2 (Principal Names) of RFC 1510. The input name must be consistent with the provided name type. (for example, duke@FOO.COM, is a valid input string for the name type, KRB_NT_PRINCIPAL where duke represents a principal, and FOO.COM represents a realm).

If the input name does not contain a realm, the default realm is used. The default realm can be specified either in a Kerberos configuration file or via the java.security.krb5.realm system property. For more information, see Kerberos Requirements.

Parameters:
name - the principal name
nameType - the name type of the principal
Throws:
IllegalArgumentException - if name is improperly formatted, if name is null, if the nameType is not supported, or if name does not contain the realm to use and the default realm is not specified in either a Kerberos configuration file or via the java.security.krb5.realm system property.
Method Detail

getRealm

public String getRealm()
Returns the realm component of this Kerberos principal.

Returns:
the realm component of this Kerberos principal.

hashCode

public int hashCode()
Returns a hashcode for this principal. The hash code is defined to be the result of the following calculation:

  hashCode = getName().hashCode();

Specified by:
hashCode in interface Principal
Overrides:
hashCode in class Object
Returns:
a hashCode() for the KerberosPrincipal
See Also:
Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object other)
Compares the specified Object with this Principal for equality. Returns true if the given object is also a KerberosPrincipal and the two KerberosPrincipal instances are equivalent. More formally two KerberosPrincipal instances are equal if the values returned by getName() are equal and the values returned by getNameType() are equal.

Specified by:
equals in interface Principal
Overrides:
equals in class Object
Parameters:
other - the Object to compare to
Returns:
true if the Object passed in represents the same principal as this one, false otherwise.
See Also:
Object.hashCode(), Hashtable

getName

public String getName()
The returned string corresponds to the single-string representation of a Kerberos Principal name as specified in Section 2.1 of RFC 1964.

Specified by:
getName in interface Principal
Returns:
the principal name.

getNameType

public int getNameType()
Returns the name type of the KerberosPrincipal. Valid name types are specified in Section 7.2 of RFC1510.

Returns:
the name type.

toString

public String toString()
Description copied from class: Object
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())

Specified by:
toString in interface Principal
Overrides:
toString in class Object
Returns:
a string representation of the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


KerberosTicket

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.kerberos
Class KerberosTicket

java.lang.Object
    extended by  javax.security.auth.kerberos.KerberosTicket
All Implemented Interfaces:
Serializable, Destroyable, Refreshable
public class KerberosTicket
extends Object
implements Destroyable, Refreshable, Serializable

This class encapsulates a Kerberos ticket and associated information as viewed from the client's point of view. It captures all information that the Key Distribution Center (KDC) sends to the client in the reply message KDC-REP defined in the Kerberos Protocol Specification (RFC 1510).

All Kerberos JAAS login modules that authenticate a user to a KDC should use this class. Where available, the login module might even read this information from a ticket cache in the operating system instead of directly communicating with the KDC. During the commit phase of the JAAS authentication process, the JAAS login module should instantiate this class and store the instance in the private credential set of a Subject.

It might be necessary for the application to be granted a PrivateCredentialPermission if it needs to access a KerberosTicket instance from a Subject. This permission is not needed when the application depends on the default JGSS Kerberos mechanism to access the KerberosTicket. In that case, however, the application will need an appropriate ServicePermission.

Note that this class is applicable to both ticket granting tickets and other regular service tickets. A ticket granting ticket is just a special case of a more generalized service ticket.

Since:
1.4
See Also:
Subject, PrivateCredentialPermission, LoginContext, GSSCredential, GSSManager, Serialized Form

Constructor Summary
KerberosTicket(byte[] asn1Encoding, KerberosPrincipal client, KerberosPrincipal server, byte[] sessionKey, int keyType, boolean[] flags, Date authTime, Date startTime, Date endTime, Date renewTill, InetAddress[] clientAddresses)
Constructs a KerberosTicket using credentials information that a client either receives from a KDC or reads from a cache.
Method Summary
void | destroy() Destroys the ticket and destroys any sensitive information stored in it.
boolean | equals(Object other) Compares the specified Object with this KerberosTicket for equality.
Date | getAuthTime() Returns the time that the client was authenticated.
KerberosPrincipal | getClient() Returns the client principal associated with this ticket.
InetAddress[] | getClientAddresses() Returns a list of addresses from where the ticket can be used.
byte[] | getEncoded() Returns an ASN.1 encoding of the entire ticket.
Date | getEndTime() Returns the expiration time for this ticket's validity period.
boolean[] | getFlags() Returns the flags associated with this ticket.
Date | getRenewTill() Returns the latest expiration time for this ticket, including all renewals.
KerberosPrincipal | getServer() Returns the service principal associated with this ticket.
SecretKey | getSessionKey() Returns the session key associated with this ticket.
int | getSessionKeyType() Returns the key type of the session key associated with this ticket as defined by the Kerberos Protocol Specification.
Date | getStartTime() Returns the start time for this ticket's validity period.
int | hashCode() Returns a hashcode for this KerberosTicket.
boolean | isCurrent() Determines if this ticket is still current.
boolean | isDestroyed() Determines if this ticket has been destroyed.
boolean | isForwardable() Determines if this ticket is forwardable.
boolean | isForwarded() Determines if this ticket had been forwarded or was issued based on authentication involving a forwarded ticket-granting ticket.
boolean | isInitial() Determines if this ticket was issued using the Kerberos AS-Exchange protocol, and not issued based on some ticket-granting ticket.
boolean | isPostdated() Determines is this ticket is post-dated.
boolean | isProxiable() Determines if this ticket is proxiable.
boolean | isProxy() Determines is this ticket is a proxy-ticket.
boolean | isRenewable() Determines is this ticket is renewable.
void | refresh() Extends the validity period of this ticket.
String | toString() Returns a string representation of the object.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

KerberosTicket

public KerberosTicket(byte[] asn1Encoding,
                      KerberosPrincipal client,
                      KerberosPrincipal server,
                      byte[] sessionKey,
                      int keyType,
                      boolean[] flags,
                      Date authTime,
                      Date startTime,
                      Date endTime,
                      Date renewTill,
                      InetAddress[] clientAddresses)
Constructs a KerberosTicket using credentials information that a client either receives from a KDC or reads from a cache.

Parameters:
asn1Encoding - the ASN.1 encoding of the ticket as defined by the Kerberos protocol specification.
client - the client that owns this service ticket
server - the service that this ticket is for
sessionKey - the raw bytes for the session key that must be used to encrypt the authenticator that will be sent to the server
keyType - the key type for the session key as defined by the Kerberos protocol specification.
flags - the ticket flags. Each element in this array indicates the value for the corresponding bit in the ASN.1 BitString that represents the ticket flags. If the number of elements in this array is less than the number of flags used by the Kerberos protocol, then the missing flags will be filled in with false.
authTime - the time of initial authentication for the client
startTime - the time after which the ticket will be valid. This may be null in which case the value of authTime is treated as the startTime.
endTime - the time after which the ticket will no longer be valid
renewTill - an absolute expiration time for the ticket, including all renewal that might be possible. This field may be null for tickets that are not renewable.
clientAddresses - the addresses from where the ticket may be used by the client. This field may be null when the ticket is usable from any address.
Method Detail

getClient

public final KerberosPrincipal getClient()
Returns the client principal associated with this ticket.

Returns:
the client principal.

getServer

public final KerberosPrincipal getServer()
Returns the service principal associated with this ticket.

Returns:
the service principal.

getSessionKey

public final SecretKey getSessionKey()
Returns the session key associated with this ticket.

Returns:
the session key.

getSessionKeyType

public final int getSessionKeyType()
Returns the key type of the session key associated with this ticket as defined by the Kerberos Protocol Specification.

Returns:
the key type of the session key associated with this ticket.
See Also:
getSessionKey()

isForwardable

public final boolean isForwardable()
Determines if this ticket is forwardable.

Returns:
true if this ticket is forwardable, false if not.

isForwarded

public final boolean isForwarded()
Determines if this ticket had been forwarded or was issued based on authentication involving a forwarded ticket-granting ticket.

Returns:
true if this ticket had been forwarded or was issued based on authentication involving a forwarded ticket-granting ticket, false otherwise.

isProxiable

public final boolean isProxiable()
Determines if this ticket is proxiable.

Returns:
true if this ticket is proxiable, false if not.

isProxy

public final boolean isProxy()
Determines is this ticket is a proxy-ticket.

Returns:
true if this ticket is a proxy-ticket, false if not.

isPostdated

public final boolean isPostdated()
Determines is this ticket is post-dated.

Returns:
true if this ticket is post-dated, false if not.

isRenewable

public final boolean isRenewable()
Determines is this ticket is renewable. If so, the refresh method can be called, assuming the validity period for renewing is not already over.

Returns:
true if this ticket is renewable, false if not.

isInitial

public final boolean isInitial()
Determines if this ticket was issued using the Kerberos AS-Exchange protocol, and not issued based on some ticket-granting ticket.

Returns:
true if this ticket was issued using the Kerberos AS-Exchange protocol, false if not.

getFlags

public final boolean[] getFlags()
Returns the flags associated with this ticket. Each element in the returned array indicates the value for the corresponding bit in the ASN.1 BitString that represents the ticket flags.

Returns:
the flags associated with this ticket.

getAuthTime

public final Date getAuthTime()
Returns the time that the client was authenticated.

Returns:
the time that the client was authenticated or null if not set.

getStartTime

public final Date getStartTime()
Returns the start time for this ticket's validity period.

Returns:
the start time for this ticket's validity period or null if not set.

getEndTime

public final Date getEndTime()
Returns the expiration time for this ticket's validity period.

Returns:
the expiration time for this ticket's validity period.

getRenewTill

public final Date getRenewTill()
Returns the latest expiration time for this ticket, including all renewals. This will return a null value for non-renewable tickets.

Returns:
the latest expiration time for this ticket.

getClientAddresses

public final InetAddress[] getClientAddresses()
Returns a list of addresses from where the ticket can be used.

Returns:
ths list of addresses or null, if the field was not provided.

getEncoded

public final byte[] getEncoded()
Returns an ASN.1 encoding of the entire ticket.

Returns:
an ASN.1 encoding of the entire ticket.

isCurrent

public boolean isCurrent()
Determines if this ticket is still current.

Specified by:
isCurrent in interface Refreshable
Returns:
true if this Object is currently current, false otherwise.

refresh

public void refresh()
             throws RefreshFailedException
Extends the validity period of this ticket. The ticket will contain a new session key if the refresh operation succeeds. The refresh operation will fail if the ticket is not renewable or the latest allowable renew time has passed. Any other error returned by the KDC will also cause this method to fail. Note: This method is not synchronized with the the accessor methods of this object. Hence callers need to be aware of multiple threads that might access this and try to renew it at the same time.

Specified by:
refresh in interface Refreshable
Throws:
RefreshFailedException - if the ticket is not renewable, or the latest allowable renew time has passed, or the KDC returns some error.
See Also:
isRenewable(), getRenewTill()

destroy

public void destroy()
             throws DestroyFailedException
Destroys the ticket and destroys any sensitive information stored in it.

Specified by:
destroy in interface Destroyable
Throws:
DestroyFailedException - if the destroy operation fails.

isDestroyed

public boolean isDestroyed()
Determines if this ticket has been destroyed.

Specified by:
isDestroyed in interface Destroyable
Returns:
true if this Object has been destroyed, false otherwise.

toString

public String toString()
Description copied from class: Object
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())

Overrides:
toString in class Object
Returns:
a string representation of the object.

hashCode

public int hashCode()
Returns a hashcode for this KerberosTicket.

Overrides:
hashCode in class Object
Returns:
a hashCode() for the KerberosTicket
Since:
1.6
See Also:
Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object other)
Compares the specified Object with this KerberosTicket for equality. Returns true if the given object is also a KerberosTicket and the two KerberosTicket instances are equivalent.

Overrides:
equals in class Object
Parameters:
other - the Object to compare to
Returns:
true if the specified object is equal to this KerberosTicket, false otherwise. NOTE: Returns false if either of the KerberosTicket objects has been destroyed.
Since:
1.6
See Also:
Object.hashCode(), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServicePermission

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.kerberos
Class ServicePermission

java.lang.Object
    extended by  java.security.Permission
        extended by  javax.security.auth.kerberos.ServicePermission
All Implemented Interfaces:
Serializable, Guard
public final class ServicePermission
extends Permission
implements Serializable

This class is used to protect Kerberos services and the credentials necessary to access those services. There is a one to one mapping of a service principal and the credentials necessary to access the service. Therefore granting access to a service principal implicitly grants access to the credential necessary to establish a security context with the service principal. This applies regardless of whether the credentials are in a cache or acquired via an exchange with the KDC. The credential can be either a ticket granting ticket, a service ticket or a secret key from a key table.

A ServicePermission contains a service principal name and a list of actions which specify the context the credential can be used within.

The service principal name is the canonical name of the KereberosPrincipal supplying the service, that is the KerberosPrincipal represents a Kerberos service principal. This name is treated in a case sensitive manner. An asterisk may appear by itself, to signify any service principal.

Granting this permission implies that the caller can use a cached credential (TGT, service ticket or secret key) within the context designated by the action. In the case of the TGT, granting this permission also implies that the TGT can be obtained by an Authentication Service exchange.

The possible actions are:

    initiate -              allow the caller to use the credential to
                            initiate a security context with a service
                            principal.

    accept -                allow the caller to use the credential to
                            accept security context as a particular
                            principal.
For example, to specify the permission to access to the TGT to initiate a security context the permission is constructed as follows:

     ServicePermission("krbtgt/EXAMPLE.COM@EXAMPLE.COM", "initiate");

To obtain a service ticket to initiate a context with the "host" service the permission is constructed as follows:

     ServicePermission("host/foo.example.com@EXAMPLE.COM", "initiate");

For a Kerberized server the action is "accept". For example, the permission necessary to access and use the secret key of the Kerberized "host" service (telnet and the likes) would be constructed as follows:

     ServicePermission("host/foo.example.com@EXAMPLE.COM", "accept");

Since:
1.4
See Also:
Serialized Form

Constructor Summary
ServicePermission(String servicePrincipal, String action)
Create a new ServicePermission with the specified servicePrincipal and action.
Method Summary
boolean | equals(Object obj) Checks two ServicePermission objects for equality.
String | getActions() Returns the canonical string representation of the actions.
int | hashCode() Returns the hash code value for this object.
boolean | implies(Permission p) Checks if this Kerberos service permission object "implies" the specified permission.
PermissionCollection | newPermissionCollection() Returns a PermissionCollection object for storing ServicePermission objects.
Methods inherited from class java.security.Permission
checkGuard, getName, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ServicePermission

public ServicePermission(String servicePrincipal,
                         String action)
Create a new ServicePermission with the specified servicePrincipal and action.

Parameters:
servicePrincipal - the name of the service principal. An asterisk may appear by itself, to signify any service principal.

action - the action string
Method Detail

implies

public boolean implies(Permission p)
Checks if this Kerberos service permission object "implies" the specified permission.

If none of the above are true, implies returns false.

Specified by:
implies in class Permission
Parameters:
p - the permission to check against.
Returns:
true if the specified permission is implied by this object, false if not.

equals

public boolean equals(Object obj)
Checks two ServicePermission objects for equality.

Specified by:
equals in class Permission
Parameters:
obj - the object to test for equality with this object.
Returns:
true if obj is a ServicePermission, and has the same service principal, and actions as this ServicePermission object.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns the hash code value for this object.

Specified by:
hashCode in class Permission
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

getActions

public String getActions()
Returns the canonical string representation of the actions. Always returns present actions in the following order: initiate, accept.

Specified by:
getActions in class Permission
Returns:
the actions of this Permission.

newPermissionCollection

public PermissionCollection newPermissionCollection()
Returns a PermissionCollection object for storing ServicePermission objects.
ServicePermission objects must be stored in a manner that allows them to be inserted into the collection in any order, but that also enables the PermissionCollection implies method to be implemented in an efficient (and consistent) manner.

Overrides:
newPermissionCollection in class Permission
Returns:
a new PermissionCollection object suitable for storing ServicePermissions.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


login

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.security.auth.login

This package provides a pluggable authentication framework.

See:
Description

Interface Summary
Configuration.Parameters This represents a marker interface for Configuration parameters.

Class Summary
AppConfigurationEntry | This class represents a single LoginModule entry configured for the application specified in the getAppConfigurationEntry(String appName) method in the Configuration class.
AppConfigurationEntry.LoginModuleControlFlag | This class represents whether or not a LoginModule is REQUIRED, REQUISITE, SUFFICIENT or OPTIONAL.
Configuration | A Configuration object is responsible for specifying which LoginModules should be used for a particular application, and in what order the LoginModules should be invoked.
ConfigurationSpi | This class defines the Service Provider Interface (SPI) for the Configuration class.
LoginContext | The LoginContext class describes the basic methods used to authenticate Subjects and provides a way to develop an application independent of the underlying authentication technology.

Exception Summary
AccountException | A generic account exception.
AccountExpiredException | Signals that a user account has expired.
AccountLockedException | Signals that an account was locked.
AccountNotFoundException | Signals that an account was not found.
CredentialException | A generic credential exception.
CredentialExpiredException | Signals that a Credential has expired.
CredentialNotFoundException | Signals that a credential was not found.
FailedLoginException | Signals that user authentication failed.
LoginException | This is the basic login exception.

Package javax.security.auth.login Description

This package provides a pluggable authentication framework.

Since:
JDK1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


Configuration.Parameters

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.login
Interface Configuration.Parameters

All Known Implementing Classes:
URIParameter
Enclosing class:
Configuration
public static interface Configuration.Parameters

This represents a marker interface for Configuration parameters.

Since:
1.6

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


javax.security.auth.login Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.security.auth.login

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.security.auth.login.AppConfigurationEntry
    • javax.security.auth.login.AppConfigurationEntry.LoginModuleControlFlag
    • javax.security.auth.login.Configuration
    • javax.security.auth.login.ConfigurationSpi
    • javax.security.auth.login.LoginContext
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.security.GeneralSecurityException
          • javax.security.auth.login.LoginException
            • javax.security.auth.login.AccountException
              • javax.security.auth.login.AccountExpiredException
              • javax.security.auth.login.AccountLockedException
              • javax.security.auth.login.AccountNotFoundException
            • javax.security.auth.login.CredentialException
              • javax.security.auth.login.CredentialExpiredException
              • javax.security.auth.login.CredentialNotFoundException
            • javax.security.auth.login.FailedLoginException

Interface Hierarchy

  • javax.security.auth.login.Configuration.Parameters
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.security.auth.login

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.security.auth.login

Packages that use javax.security.auth.login
java.security | Provides the classes and interfaces for the security framework.
javax.security.auth.login | This package provides a pluggable authentication framework.
javax.security.auth.spi | This package provides the interface to be used for implementing pluggable authentication modules.

Classes in javax.security.auth.login used by java.security
Configuration.Parameters
This represents a marker interface for Configuration parameters.
LoginException
This is the basic login exception.

Classes in javax.security.auth.login used by javax.security.auth.login
AccountException
A generic account exception.
AppConfigurationEntry
This class represents a single LoginModule entry configured for the application specified in the getAppConfigurationEntry(String appName) method in the Configuration class.
AppConfigurationEntry.LoginModuleControlFlag
This class represents whether or not a LoginModule is REQUIRED, REQUISITE, SUFFICIENT or OPTIONAL.
Configuration
A Configuration object is responsible for specifying which LoginModules should be used for a particular application, and in what order the LoginModules should be invoked.
Configuration.Parameters
This represents a marker interface for Configuration parameters.
CredentialException
A generic credential exception.
LoginException
This is the basic login exception.

Classes in javax.security.auth.login used by javax.security.auth.spi
LoginException
This is the basic login exception.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AccountException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.login
Class AccountException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.security.GeneralSecurityException
                extended by  javax.security.auth.login.LoginException
                    extended by  javax.security.auth.login.AccountException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
AccountExpiredException, AccountLockedException, AccountNotFoundException
public class AccountException
extends LoginException

A generic account exception.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
AccountException()
Constructs a AccountException with no detail message.
AccountException(String msg)
Constructs a AccountException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AccountException

public AccountException()
Constructs a AccountException with no detail message. A detail message is a String that describes this particular exception.

AccountException

public AccountException(String msg)
Constructs a AccountException with the specified detail message. A detail message is a String that describes this particular exception.

Parameters:
msg - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AccountExpiredException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.login
Class AccountExpiredException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.security.GeneralSecurityException
                extended by  javax.security.auth.login.LoginException
                    extended by  javax.security.auth.login.AccountException
                        extended by  javax.security.auth.login.AccountExpiredException
All Implemented Interfaces:
Serializable
public class AccountExpiredException
extends AccountException

Signals that a user account has expired.

This exception is thrown by LoginModules when they determine that an account has expired. For example, a LoginModule, after successfully authenticating a user, may determine that the user's account has expired. In this case the LoginModule throws this exception to notify the application. The application can then take the appropriate steps to notify the user.

See Also:
Serialized Form

Constructor Summary
AccountExpiredException()
Constructs a AccountExpiredException with no detail message.
AccountExpiredException(String msg)
Constructs a AccountExpiredException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AccountExpiredException

public AccountExpiredException()
Constructs a AccountExpiredException with no detail message. A detail message is a String that describes this particular exception.

AccountExpiredException

public AccountExpiredException(String msg)
Constructs a AccountExpiredException with the specified detail message. A detail message is a String that describes this particular exception.

Parameters:
msg - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AccountLockedException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.login
Class AccountLockedException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.security.GeneralSecurityException
                extended by  javax.security.auth.login.LoginException
                    extended by  javax.security.auth.login.AccountException
                        extended by  javax.security.auth.login.AccountLockedException
All Implemented Interfaces:
Serializable
public class AccountLockedException
extends AccountException

Signals that an account was locked.

This exception may be thrown by a LoginModule if it determines that authentication is being attempted on a locked account.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
AccountLockedException()
Constructs a AccountLockedException with no detail message.
AccountLockedException(String msg)
Constructs a AccountLockedException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AccountLockedException

public AccountLockedException()
Constructs a AccountLockedException with no detail message. A detail message is a String that describes this particular exception.

AccountLockedException

public AccountLockedException(String msg)
Constructs a AccountLockedException with the specified detail message. A detail message is a String that describes this particular exception.

Parameters:
msg - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AccountNotFoundException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.login
Class AccountNotFoundException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.security.GeneralSecurityException
                extended by  javax.security.auth.login.LoginException
                    extended by  javax.security.auth.login.AccountException
                        extended by  javax.security.auth.login.AccountNotFoundException
All Implemented Interfaces:
Serializable
public class AccountNotFoundException
extends AccountException

Signals that an account was not found.

This exception may be thrown by a LoginModule if it is unable to locate an account necessary to perform authentication.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
AccountNotFoundException()
Constructs a AccountNotFoundException with no detail message.
AccountNotFoundException(String msg)
Constructs a AccountNotFoundException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AccountNotFoundException

public AccountNotFoundException()
Constructs a AccountNotFoundException with no detail message. A detail message is a String that describes this particular exception.

AccountNotFoundException

public AccountNotFoundException(String msg)
Constructs a AccountNotFoundException with the specified detail message. A detail message is a String that describes this particular exception.

Parameters:
msg - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AppConfigurationEntry

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.login
Class AppConfigurationEntry

java.lang.Object
    extended by  javax.security.auth.login.AppConfigurationEntry

public class AppConfigurationEntry
extends Object

This class represents a single LoginModule entry configured for the application specified in the getAppConfigurationEntry(String appName) method in the Configuration class. Each respective AppConfigurationEntry contains a LoginModule name, a control flag (specifying whether this LoginModule is REQUIRED, REQUISITE, SUFFICIENT, or OPTIONAL), and LoginModule-specific options. Please refer to the Configuration class for more information on the different control flags and their semantics.

See Also:
Configuration

Nested Class Summary
static class AppConfigurationEntry.LoginModuleControlFlag
This class represents whether or not a LoginModule is REQUIRED, REQUISITE, SUFFICIENT or OPTIONAL.
Constructor Summary
AppConfigurationEntry(String loginModuleName, AppConfigurationEntry.LoginModuleControlFlag controlFlag, Map<String,?> options)
Default constructor for this class.
Method Summary
AppConfigurationEntry.LoginModuleControlFlag | getControlFlag() Return the controlFlag (either REQUIRED, REQUISITE, SUFFICIENT, or OPTIONAL) for this LoginModule.
String | getLoginModuleName() Get the class name of the configured LoginModule.
Map<String,?> | getOptions() Get the options configured for this LoginModule.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AppConfigurationEntry

public AppConfigurationEntry(String loginModuleName,
                             AppConfigurationEntry.LoginModuleControlFlag controlFlag,
                             Map<String,?> options)
Default constructor for this class.

This entry represents a single LoginModule entry configured for the application specified in the getAppConfigurationEntry(String appName) method from the Configuration class.

Parameters:
loginModuleName - String representing the class name of the LoginModule configured for the specified application.

controlFlag - either REQUIRED, REQUISITE, SUFFICIENT, or OPTIONAL.

options - the options configured for this LoginModule.
Throws:
IllegalArgumentException - if loginModuleName is null, if LoginModuleName has a length of 0, if controlFlag is not either REQUIRED, REQUISITE, SUFFICIENT or OPTIONAL, or if options is null.
Method Detail

getLoginModuleName

public String getLoginModuleName()
Get the class name of the configured LoginModule.

Returns:
the class name of the configured LoginModule as a String.

getControlFlag

public AppConfigurationEntry.LoginModuleControlFlag getControlFlag()
Return the controlFlag (either REQUIRED, REQUISITE, SUFFICIENT, or OPTIONAL) for this LoginModule.

Returns:
the controlFlag (either REQUIRED, REQUISITE, SUFFICIENT, or OPTIONAL) for this LoginModule.

getOptions

public Map<String,?> getOptions()
Get the options configured for this LoginModule.

Returns:
the options configured for this LoginModule as an unmodifiable Map.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AppConfigurationEntry.LoginModuleControlFlag

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.login
Class AppConfigurationEntry.LoginModuleControlFlag

java.lang.Object
    extended by  javax.security.auth.login.AppConfigurationEntry.LoginModuleControlFlag
Enclosing class:
AppConfigurationEntry
public static class AppConfigurationEntry.LoginModuleControlFlag
extends Object

This class represents whether or not a LoginModule is REQUIRED, REQUISITE, SUFFICIENT or OPTIONAL.

Field Summary
static AppConfigurationEntry.LoginModuleControlFlag | OPTIONAL Optional LoginModule.
static AppConfigurationEntry.LoginModuleControlFlag | REQUIRED Required LoginModule.
static AppConfigurationEntry.LoginModuleControlFlag | REQUISITE Requisite LoginModule.
static AppConfigurationEntry.LoginModuleControlFlag | SUFFICIENT Sufficient LoginModule.
Method Summary
 String toString()
Return a String representation of this controlFlag.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

REQUIRED

public static final AppConfigurationEntry.LoginModuleControlFlag REQUIRED
Required LoginModule.

REQUISITE

public static final AppConfigurationEntry.LoginModuleControlFlag REQUISITE
Requisite LoginModule.

SUFFICIENT

public static final AppConfigurationEntry.LoginModuleControlFlag SUFFICIENT
Sufficient LoginModule.

OPTIONAL

public static final AppConfigurationEntry.LoginModuleControlFlag OPTIONAL
Optional LoginModule.

Method Detail

toString

public String toString()
Return a String representation of this controlFlag.

The String has the format, "LoginModuleControlFlag: flag", where flag is either required, requisite, sufficient, or optional.

Overrides:
toString in class Object
Returns:
a String representation of this controlFlag.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.security.auth.login.AccountException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.login.AccountException

Packages that use AccountException
javax.security.auth.login This package provides a pluggable authentication framework.

Uses of AccountException in javax.security.auth.login

Subclasses of AccountException in javax.security.auth.login
class | AccountExpiredException Signals that a user account has expired.
class | AccountLockedException Signals that an account was locked.
class | AccountNotFoundException Signals that an account was not found.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.login.AccountExpiredException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.login.AccountExpiredException

No usage of javax.security.auth.login.AccountExpiredException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.login.AccountLockedException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.login.AccountLockedException

No usage of javax.security.auth.login.AccountLockedException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.login.AccountNotFoundException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.login.AccountNotFoundException

No usage of javax.security.auth.login.AccountNotFoundException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.login.AppConfigurationEntry

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.login.AppConfigurationEntry

Packages that use AppConfigurationEntry
javax.security.auth.login This package provides a pluggable authentication framework.

Uses of AppConfigurationEntry in javax.security.auth.login

Methods in javax.security.auth.login that return AppConfigurationEntry
protected abstract AppConfigurationEntry[] | ConfigurationSpi.engineGetAppConfigurationEntry(String name) Retrieve the AppConfigurationEntries for the specified name.
abstract AppConfigurationEntry[] | Configuration.getAppConfigurationEntry(String name) Retrieve the AppConfigurationEntries for the specified name from this Configuration.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.login.AppConfigurationEntry.LoginModuleControlFlag

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.login.AppConfigurationEntry.LoginModuleControlFlag

Packages that use AppConfigurationEntry.LoginModuleControlFlag
javax.security.auth.login This package provides a pluggable authentication framework.

Uses of AppConfigurationEntry.LoginModuleControlFlag in javax.security.auth.login

Fields in javax.security.auth.login declared as AppConfigurationEntry.LoginModuleControlFlag
static AppConfigurationEntry.LoginModuleControlFlag | AppConfigurationEntry.LoginModuleControlFlag.OPTIONAL Optional LoginModule.
static AppConfigurationEntry.LoginModuleControlFlag | AppConfigurationEntry.LoginModuleControlFlag.REQUIRED Required LoginModule.
static AppConfigurationEntry.LoginModuleControlFlag | AppConfigurationEntry.LoginModuleControlFlag.REQUISITE Requisite LoginModule.
static AppConfigurationEntry.LoginModuleControlFlag | AppConfigurationEntry.LoginModuleControlFlag.SUFFICIENT Sufficient LoginModule.

Methods in javax.security.auth.login that return AppConfigurationEntry.LoginModuleControlFlag
 AppConfigurationEntry.LoginModuleControlFlag AppConfigurationEntry.getControlFlag()
Return the controlFlag (either REQUIRED, REQUISITE, SUFFICIENT, or OPTIONAL) for this LoginModule.

Constructors in javax.security.auth.login with parameters of type AppConfigurationEntry.LoginModuleControlFlag
AppConfigurationEntry(String loginModuleName, AppConfigurationEntry.LoginModuleControlFlag controlFlag, Map<String,?> options)
Default constructor for this class.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.login.Configuration

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.login.Configuration

Packages that use Configuration
javax.security.auth.login This package provides a pluggable authentication framework.

Uses of Configuration in javax.security.auth.login

Methods in javax.security.auth.login that return Configuration
static Configuration | Configuration.getConfiguration() Get the installed login Configuration.
static Configuration | Configuration.getInstance(String type, Configuration.Parameters params) Returns a Configuration object of the specified type.
static Configuration | Configuration.getInstance(String type, Configuration.Parameters params, Provider provider) Returns a Configuration object of the specified type.
static Configuration | Configuration.getInstance(String type, Configuration.Parameters params, String provider) Returns a Configuration object of the specified type.

Methods in javax.security.auth.login with parameters of type Configuration
static void Configuration.setConfiguration(Configuration configuration)
Set the login Configuration.

Constructors in javax.security.auth.login with parameters of type Configuration
LoginContext(String name, Subject subject, CallbackHandler callbackHandler, Configuration config)
Instantiate a new LoginContext object with a name, a Subject to be authenticated, a CallbackHandler object, and a login Configuration.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.login.ConfigurationSpi

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.login.ConfigurationSpi

No usage of javax.security.auth.login.ConfigurationSpi

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.login.CredentialException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.login.CredentialException

Packages that use CredentialException
javax.security.auth.login This package provides a pluggable authentication framework.

Uses of CredentialException in javax.security.auth.login

Subclasses of CredentialException in javax.security.auth.login
class | CredentialExpiredException Signals that a Credential has expired.
class | CredentialNotFoundException Signals that a credential was not found.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.login.CredentialExpiredException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.login.CredentialExpiredException

No usage of javax.security.auth.login.CredentialExpiredException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.login.CredentialNotFoundException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.login.CredentialNotFoundException

No usage of javax.security.auth.login.CredentialNotFoundException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.login.FailedLoginException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.login.FailedLoginException

No usage of javax.security.auth.login.FailedLoginException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.login.LoginContext

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.login.LoginContext

No usage of javax.security.auth.login.LoginContext

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.login.LoginException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.login.LoginException

Packages that use LoginException
java.security | Provides the classes and interfaces for the security framework.
javax.security.auth.login | This package provides a pluggable authentication framework.
javax.security.auth.spi | This package provides the interface to be used for implementing pluggable authentication modules.

Uses of LoginException in java.security

Methods in java.security that throw LoginException
abstract void | AuthProvider.login(Subject subject, CallbackHandler handler) Log in to this provider.
abstract void | AuthProvider.logout() Log out from this provider.

Uses of LoginException in javax.security.auth.login

Subclasses of LoginException in javax.security.auth.login
class | AccountException A generic account exception.
class | AccountExpiredException Signals that a user account has expired.
class | AccountLockedException Signals that an account was locked.
class | AccountNotFoundException Signals that an account was not found.
class | CredentialException A generic credential exception.
class | CredentialExpiredException Signals that a Credential has expired.
class | CredentialNotFoundException Signals that a credential was not found.
class | FailedLoginException Signals that user authentication failed.

Methods in javax.security.auth.login that throw LoginException
void | LoginContext.login() Perform the authentication.
void | LoginContext.logout() Logout the Subject.

Constructors in javax.security.auth.login that throw LoginException
LoginContext(String name)
Instantiate a new LoginContext object with a name.
LoginContext(String name, CallbackHandler callbackHandler)
Instantiate a new LoginContext object with a name and a CallbackHandler object.
LoginContext(String name, Subject subject)
Instantiate a new LoginContext object with a name and a Subject object.
LoginContext(String name, Subject subject, CallbackHandler callbackHandler)
Instantiate a new LoginContext object with a name, a Subject to be authenticated, and a CallbackHandler object.
LoginContext(String name, Subject subject, CallbackHandler callbackHandler, Configuration config)
Instantiate a new LoginContext object with a name, a Subject to be authenticated, a CallbackHandler object, and a login Configuration.

Uses of LoginException in javax.security.auth.spi

Methods in javax.security.auth.spi that throw LoginException
boolean | LoginModule.abort() Method to abort the authentication process (phase 2).
boolean | LoginModule.commit() Method to commit the authentication process (phase 2).
boolean | LoginModule.login() Method to authenticate a Subject (phase 1).
boolean | LoginModule.logout() Method which logs out a Subject.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.security.auth.login.Configuration.Parameters

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.security.auth.login.Configuration.Parameters

Packages that use Configuration.Parameters
java.security | Provides the classes and interfaces for the security framework.
javax.security.auth.login | This package provides a pluggable authentication framework.

Uses of Configuration.Parameters in java.security

Classes in java.security that implement Configuration.Parameters
 class URIParameter
A parameter that contains a URI pointing to data intended for a PolicySpi or ConfigurationSpi implementation.

Uses of Configuration.Parameters in javax.security.auth.login

Methods in javax.security.auth.login that return Configuration.Parameters
 Configuration.Parameters Configuration.getParameters()
Return Configuration parameters.

Methods in javax.security.auth.login with parameters of type Configuration.Parameters
static Configuration | Configuration.getInstance(String type, Configuration.Parameters params) Returns a Configuration object of the specified type.
static Configuration | Configuration.getInstance(String type, Configuration.Parameters params, Provider provider) Returns a Configuration object of the specified type.
static Configuration | Configuration.getInstance(String type, Configuration.Parameters params, String provider) Returns a Configuration object of the specified type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Configuration

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.login
Class Configuration

java.lang.Object
    extended by  javax.security.auth.login.Configuration

public abstract class Configuration
extends Object

A Configuration object is responsible for specifying which LoginModules should be used for a particular application, and in what order the LoginModules should be invoked.

A login configuration contains the following information. Note that this example only represents the default syntax for the Configuration. Subclass implementations of this class may implement alternative syntaxes and may retrieve the Configuration from any source such as files, databases, or servers.

      Name {
              ModuleClass  Flag    ModuleOptions;
              ModuleClass  Flag    ModuleOptions;
              ModuleClass  Flag    ModuleOptions;
      };
      Name {
              ModuleClass  Flag    ModuleOptions;
              ModuleClass  Flag    ModuleOptions;
      };
      other {
              ModuleClass  Flag    ModuleOptions;
              ModuleClass  Flag    ModuleOptions;
      };

Each entry in the Configuration is indexed via an application name, Name, and contains a list of LoginModules configured for that application. Each LoginModule is specified via its fully qualified class name. Authentication proceeds down the module list in the exact order specified. If an application does not have specific entry, it defaults to the specific entry for "other".

The Flag value controls the overall behavior as authentication proceeds down the stack. The following represents a description of the valid values for Flag and their respective semantics:

      1) Required     - The LoginModule is required to succeed.
                        If it succeeds or fails, authentication still continues
                        to proceed down the LoginModule list.

      2) Requisite    - The LoginModule is required to succeed.
                        If it succeeds, authentication continues down the
                        LoginModule list.  If it fails,
                        control immediately returns to the application
                        (authentication does not proceed down the
                        LoginModule list).

      3) Sufficient   - The LoginModule is not required to
                        succeed.  If it does succeed, control immediately
                        returns to the application (authentication does not
                        proceed down the LoginModule list).
                        If it fails, authentication continues down the
                        LoginModule list.

      4) Optional     - The LoginModule is not required to
                        succeed.  If it succeeds or fails,
                        authentication still continues to proceed down the
                        LoginModule list.

The overall authentication succeeds only if all Required and Requisite LoginModules succeed. If a Sufficient LoginModule is configured and succeeds, then only the Required and Requisite LoginModules prior to that Sufficient LoginModule need to have succeeded for the overall authentication to succeed. If no Required or Requisite LoginModules are configured for an application, then at least one Sufficient or Optional LoginModule must succeed.

ModuleOptions is a space separated list of LoginModule-specific values which are passed directly to the underlying LoginModules. Options are defined by the LoginModule itself, and control the behavior within it. For example, a LoginModule may define options to support debugging/testing capabilities. The correct way to specify options in the Configuration is by using the following key-value pairing: debug="true". The key and value should be separated by an 'equals' symbol, and the value should be surrounded by double quotes. If a String in the form, ${system.property}, occurs in the value, it will be expanded to the value of the system property. Note that there is no limit to the number of options a LoginModule may define.

The following represents an example Configuration entry based on the syntax above:

 Login {
   com.sun.security.auth.module.UnixLoginModule required;
   com.sun.security.auth.module.Krb5LoginModule optional
                   useTicketCache="true"
                   ticketCache="${user.home}${/}tickets";
 };

This Configuration specifies that an application named, "Login", requires users to first authenticate to the com.sun.security.auth.module.UnixLoginModule, which is required to succeed. Even if the UnixLoginModule authentication fails, the com.sun.security.auth.module.Krb5LoginModule still gets invoked. This helps hide the source of failure. Since the Krb5LoginModule is Optional, the overall authentication succeeds only if the UnixLoginModule (Required) succeeds.

Also note that the LoginModule-specific options, useTicketCache="true" and ticketCache=${user.home}${/}tickets", are passed to the Krb5LoginModule. These options instruct the Krb5LoginModule to use the ticket cache at the specified location. The system properties, user.home and / (file.separator), are expanded to their respective values.

There is only one Configuration object installed in the runtime at any given time. A Configuration object can be installed by calling the setConfiguration method. The installed Configuration object can be obtained by calling the getConfiguration method.

If no Configuration object has been installed in the runtime, a call to getConfiguration installs an instance of the default Configuration implementation (a default subclass implementation of this abstract class). The default Configuration implementation can be changed by setting the value of the "login.configuration.provider" security property (in the Java security properties file) to the fully qualified name of the desired Configuration subclass implementation. The Java security properties file is located in the file named <JAVA_HOME>/lib/security/java.security. <JAVA_HOME> refers to the value of the java.home system property, and specifies the directory where the JRE is installed.

Application code can directly subclass Configuration to provide a custom implementation. In addition, an instance of a Configuration object can be constructed by invoking one of the getInstance factory methods with a standard type. The default policy type is "JavaLoginConfig". See Appendix A in the Java Cryptography Architecture API Specification & Reference for a list of standard Configuration types.

See Also:
LoginContext

Nested Class Summary
static interface Configuration.Parameters
This represents a marker interface for Configuration parameters.
Constructor Summary
protected Configuration()
Sole constructor.
Method Summary
abstract AppConfigurationEntry[] | getAppConfigurationEntry(String name) Retrieve the AppConfigurationEntries for the specified name from this Configuration.
static Configuration | getConfiguration() Get the installed login Configuration.
static Configuration | getInstance(String type, Configuration.Parameters params) Returns a Configuration object of the specified type.
static Configuration | getInstance(String type, Configuration.Parameters params, Provider provider) Returns a Configuration object of the specified type.
static Configuration | getInstance(String type, Configuration.Parameters params, String provider) Returns a Configuration object of the specified type.
Configuration.Parameters | getParameters() Return Configuration parameters.
Provider | getProvider() Return the Provider of this Configuration.
String | getType() Return the type of this Configuration.
void | refresh() Refresh and reload the Configuration.
static void | setConfiguration(Configuration configuration) Set the login Configuration.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Configuration

protected Configuration()
Sole constructor. (For invocation by subclass constructors, typically implicit.)

Method Detail

getConfiguration

public static Configuration getConfiguration()
Get the installed login Configuration.

Returns:
the login Configuration. If a Configuration object was set via the Configuration.setConfiguration method, then that object is returned. Otherwise, a default Configuration object is returned.
Throws:
SecurityException - if the caller does not have permission to retrieve the Configuration.
See Also:
setConfiguration(javax.security.auth.login.Configuration)

setConfiguration

public static void setConfiguration(Configuration configuration)
Set the login Configuration.

Parameters:
configuration - the new Configuration
Throws:
SecurityException - if the current thread does not have Permission to set the Configuration.
See Also:
getConfiguration()

getInstance

public static Configuration getInstance(String type,
                                        Configuration.Parameters params)
                                 throws NoSuchAlgorithmException
Returns a Configuration object of the specified type.

This method traverses the list of registered security providers, starting with the most preferred Provider. A new Configuration object encapsulating the ConfigurationSpi implementation from the first Provider that supports the specified type is returned.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters:
type - the specified Configuration type. See Appendix A in the Java Cryptography Architecture API Specification & Reference for a list of standard Configuration types.
params - parameters for the Configuration, which may be null.
Returns:
the new Configuration object.
Throws:
SecurityException - if the caller does not have permission to get a Configuration instance for the specified type.
NullPointerException - if the specified type is null.
IllegalArgumentException - if the specified parameters are not understood by the ConfigurationSpi implementation from the selected Provider.
NoSuchAlgorithmException - if no Provider supports a ConfigurationSpi implementation for the specified type.
Since:
1.6
See Also:
Provider

getInstance

public static Configuration getInstance(String type,
                                        Configuration.Parameters params,
                                        String provider)
                                 throws NoSuchProviderException,
                                        NoSuchAlgorithmException
Returns a Configuration object of the specified type.

A new Configuration object encapsulating the ConfigurationSpi implementation from the specified provider is returned. The specified provider must be registered in the provider list.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters:
type - the specified Configuration type. See Appendix A in the Java Cryptography Architecture API Specification & Reference for a list of standard Configuration types.
params - parameters for the Configuration, which may be null.
provider - the provider.
Returns:
the new Configuration object.
Throws:
SecurityException - if the caller does not have permission to get a Configuration instance for the specified type.
NullPointerException - if the specified type is null.
IllegalArgumentException - if the specified provider is null or empty, or if the specified parameters are not understood by the ConfigurationSpi implementation from the specified provider.
NoSuchProviderException - if the specified provider is not registered in the security provider list.
NoSuchAlgorithmException - if the specified provider does not support a ConfigurationSpi implementation for the specified type.
Since:
1.6
See Also:
Provider

getInstance

public static Configuration getInstance(String type,
                                        Configuration.Parameters params,
                                        Provider provider)
                                 throws NoSuchAlgorithmException
Returns a Configuration object of the specified type.

A new Configuration object encapsulating the ConfigurationSpi implementation from the specified Provider object is returned. Note that the specified Provider object does not have to be registered in the provider list.

Parameters:
type - the specified Configuration type. See Appendix A in the Java Cryptography Architecture API Specification & Reference for a list of standard Configuration types.
params - parameters for the Configuration, which may be null.
provider - the Provider.
Returns:
the new Configuration object.
Throws:
SecurityException - if the caller does not have permission to get a Configuration instance for the specified type.
NullPointerException - if the specified type is null.
IllegalArgumentException - if the specified Provider is null, or if the specified parameters are not understood by the ConfigurationSpi implementation from the specified Provider.
NoSuchAlgorithmException - if the specified Provider does not support a ConfigurationSpi implementation for the specified type.
Since:
1.6
See Also:
Provider

getProvider

public Provider getProvider()
Return the Provider of this Configuration.

This Configuration instance will only have a Provider if it was obtained via a call to Configuration.getInstance. Otherwise this method returns null.

Returns:
the Provider of this Configuration, or null.
Since:
1.6

getType

public String getType()
Return the type of this Configuration.

This Configuration instance will only have a type if it was obtained via a call to Configuration.getInstance. Otherwise this method returns null.

Returns:
the type of this Configuration, or null.
Since:
1.6

getParameters

public Configuration.Parameters getParameters()
Return Configuration parameters.

This Configuration instance will only have parameters if it was obtained via a call to Configuration.getInstance. Otherwise this method returns null.

Returns:
Configuration parameters, or null.
Since:
1.6

getAppConfigurationEntry

public abstract AppConfigurationEntry[] getAppConfigurationEntry(String name)
Retrieve the AppConfigurationEntries for the specified name from this Configuration.

Parameters:
name - the name used to index the Configuration.
Returns:
an array of AppConfigurationEntries for the specified name from this Configuration, or null if there are no entries for the specified name

refresh

public void refresh()
Refresh and reload the Configuration.

This method causes this Configuration object to refresh/reload its contents in an implementation-dependent manner. For example, if this Configuration object stores its entries in a file, calling refresh may cause the file to be re-read.

The default implementation of this method does nothing. This method should be overridden if a refresh operation is supported by the implementation.

Throws:
SecurityException - if the caller does not have permission to refresh its Configuration.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ConfigurationSpi

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.login
Class ConfigurationSpi

java.lang.Object
    extended by  javax.security.auth.login.ConfigurationSpi

public abstract class ConfigurationSpi
extends Object

This class defines the Service Provider Interface (SPI) for the Configuration class. All the abstract methods in this class must be implemented by each service provider who wishes to supply a Configuration implementation.

Subclass implementations of this abstract class must provide a public constructor that takes a Configuration.Parameters object as an input parameter. This constructor also must throw an IllegalArgumentException if it does not understand the Configuration.Parameters input.

Since:
1.6

Constructor Summary
ConfigurationSpi()
Method Summary
protected abstract AppConfigurationEntry[] | engineGetAppConfigurationEntry(String name) Retrieve the AppConfigurationEntries for the specified name.
protected void | engineRefresh() Refresh and reload the Configuration.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ConfigurationSpi

public ConfigurationSpi()
Method Detail

engineGetAppConfigurationEntry

protected abstract AppConfigurationEntry[] engineGetAppConfigurationEntry(String name)
Retrieve the AppConfigurationEntries for the specified name.

Parameters:
name - the name used to index the Configuration.
Returns:
an array of AppConfigurationEntries for the specified name, or null if there are no entries.

engineRefresh

protected void engineRefresh()
Refresh and reload the Configuration.

This method causes this Configuration object to refresh/reload its contents in an implementation-dependent manner. For example, if this Configuration object stores its entries in a file, calling refresh may cause the file to be re-read.

The default implementation of this method does nothing. This method should be overridden if a refresh operation is supported by the implementation.

Throws:
SecurityException - if the caller does not have permission to refresh its Configuration.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CredentialException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.login
Class CredentialException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.security.GeneralSecurityException
                extended by  javax.security.auth.login.LoginException
                    extended by  javax.security.auth.login.CredentialException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
CredentialExpiredException, CredentialNotFoundException
public class CredentialException
extends LoginException

A generic credential exception.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
CredentialException()
Constructs a CredentialException with no detail message.
CredentialException(String msg)
Constructs a CredentialException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CredentialException

public CredentialException()
Constructs a CredentialException with no detail message. A detail message is a String that describes this particular exception.

CredentialException

public CredentialException(String msg)
Constructs a CredentialException with the specified detail message. A detail message is a String that describes this particular exception.

Parameters:
msg - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CredentialExpiredException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.login
Class CredentialExpiredException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.security.GeneralSecurityException
                extended by  javax.security.auth.login.LoginException
                    extended by  javax.security.auth.login.CredentialException
                        extended by  javax.security.auth.login.CredentialExpiredException
All Implemented Interfaces:
Serializable
public class CredentialExpiredException
extends CredentialException

Signals that a Credential has expired.

This exception is thrown by LoginModules when they determine that a Credential has expired. For example, a LoginModule authenticating a user in its login method may determine that the user's password, although entered correctly, has expired. In this case the LoginModule throws this exception to notify the application. The application can then take the appropriate steps to assist the user in updating the password.

See Also:
Serialized Form

Constructor Summary
CredentialExpiredException()
Constructs a CredentialExpiredException with no detail message.
CredentialExpiredException(String msg)
Constructs a CredentialExpiredException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CredentialExpiredException

public CredentialExpiredException()
Constructs a CredentialExpiredException with no detail message. A detail message is a String that describes this particular exception.

CredentialExpiredException

public CredentialExpiredException(String msg)
Constructs a CredentialExpiredException with the specified detail message. A detail message is a String that describes this particular exception.

Parameters:
msg - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CredentialNotFoundException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.login
Class CredentialNotFoundException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.security.GeneralSecurityException
                extended by  javax.security.auth.login.LoginException
                    extended by  javax.security.auth.login.CredentialException
                        extended by  javax.security.auth.login.CredentialNotFoundException
All Implemented Interfaces:
Serializable
public class CredentialNotFoundException
extends CredentialException

Signals that a credential was not found.

This exception may be thrown by a LoginModule if it is unable to locate a credential necessary to perform authentication.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
CredentialNotFoundException()
Constructs a CredentialNotFoundException with no detail message.
CredentialNotFoundException(String msg)
Constructs a CredentialNotFoundException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CredentialNotFoundException

public CredentialNotFoundException()
Constructs a CredentialNotFoundException with no detail message. A detail message is a String that describes this particular exception.

CredentialNotFoundException

public CredentialNotFoundException(String msg)
Constructs a CredentialNotFoundException with the specified detail message. A detail message is a String that describes this particular exception.

Parameters:
msg - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FailedLoginException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.login
Class FailedLoginException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.security.GeneralSecurityException
                extended by  javax.security.auth.login.LoginException
                    extended by  javax.security.auth.login.FailedLoginException
All Implemented Interfaces:
Serializable
public class FailedLoginException
extends LoginException

Signals that user authentication failed.

This exception is thrown by LoginModules if authentication failed. For example, a LoginModule throws this exception if the user entered an incorrect password.

See Also:
Serialized Form

Constructor Summary
FailedLoginException()
Constructs a FailedLoginException with no detail message.
FailedLoginException(String msg)
Constructs a FailedLoginException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

FailedLoginException

public FailedLoginException()
Constructs a FailedLoginException with no detail message. A detail message is a String that describes this particular exception.

FailedLoginException

public FailedLoginException(String msg)
Constructs a FailedLoginException with the specified detail message. A detail message is a String that describes this particular exception.

Parameters:
msg - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LoginContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.login
Class LoginContext

java.lang.Object
    extended by  javax.security.auth.login.LoginContext

public class LoginContext
extends Object

The LoginContext class describes the basic methods used to authenticate Subjects and provides a way to develop an application independent of the underlying authentication technology. A Configuration specifies the authentication technology, or LoginModule, to be used with a particular application. Different LoginModules can be plugged in under an application without requiring any modifications to the application itself.

In addition to supporting pluggable authentication, this class also supports the notion of stacked authentication. Applications may be configured to use more than one LoginModule. For example, one could configure both a Kerberos LoginModule and a smart card LoginModule under an application.

A typical caller instantiates a LoginContext with a name and a CallbackHandler. LoginContext uses the name as the index into a Configuration to determine which LoginModules should be used, and which ones must succeed in order for the overall authentication to succeed. The CallbackHandler is passed to the underlying LoginModules so they may communicate and interact with users (prompting for a username and password via a graphical user interface, for example).

Once the caller has instantiated a LoginContext, it invokes the login method to authenticate a Subject. The login method invokes the configured modules to perform their respective types of authentication (username/password, smart card pin verification, etc.). Note that the LoginModules will not attempt authentication retries nor introduce delays if the authentication fails. Such tasks belong to the LoginContext caller.

If the login method returns without throwing an exception, then the overall authentication succeeded. The caller can then retrieve the newly authenticated Subject by invoking the getSubject method. Principals and Credentials associated with the Subject may be retrieved by invoking the Subject's respective getPrincipals, getPublicCredentials, and getPrivateCredentials methods.

To logout the Subject, the caller calls the logout method. As with the login method, this logout method invokes the logout method for the configured modules.

A LoginContext should not be used to authenticate more than one Subject. A separate LoginContext should be used to authenticate each different Subject.

The following documentation applies to all LoginContext constructors:

  1. Subject
    • If the constructor has a Subject input parameter, the LoginContext uses the caller-specified Subject object.

    • If the caller specifies a null Subject and a null value is permitted, the LoginContext instantiates a new Subject.

    • If the constructor does not have a Subject input parameter, the LoginContext instantiates a new Subject.

  2. Configuration
    • If the constructor has a Configuration input parameter and the caller specifies a non-null Configuration, the LoginContext uses the caller-specified Configuration.

      If the constructor does not have a Configuration input parameter, or if the caller specifies a null Configuration object, the constructor uses the following call to get the installed Configuration:

            config = Configuration.getConfiguration();
      For both cases, the name argument given to the constructor is passed to the Configuration.getAppConfigurationEntry method. If the Configuration has no entries for the specified name, then the LoginContext calls getAppConfigurationEntry with the name, "other" (the default entry name). If there is no entry for "other", then a LoginException is thrown.

    • When LoginContext uses the installed Configuration, the caller requires the createLoginContext.name and possibly createLoginContext.other AuthPermissions. Furthermore, the LoginContext will invoke configured modules from within an AccessController.doPrivileged call so that modules that perform security-sensitive tasks (such as connecting to remote hosts, and updating the Subject) will require the respective permissions, but the callers of the LoginContext will not require those permissions.

    • When LoginContext uses a caller-specified Configuration, the caller does not require any createLoginContext AuthPermission. The LoginContext saves the AccessControlContext for the caller, and invokes the configured modules from within an AccessController.doPrivileged call constrained by that context. This means the caller context (stored when the LoginContext was created) must have sufficient permissions to perform any security-sensitive tasks that the modules may perform.

  3. CallbackHandler
    • If the constructor has a CallbackHandler input parameter, the LoginContext uses the caller-specified CallbackHandler object.

    • If the constructor does not have a CallbackHandler input parameter, or if the caller specifies a null CallbackHandler object (and a null value is permitted), the LoginContext queries the auth.login.defaultCallbackHandler security property for the fully qualified class name of a default handler implementation. If the security property is not set, then the underlying modules will not have a CallbackHandler for use in communicating with users. The caller thus assumes that the configured modules have alternative means for authenticating the user.

    • When the LoginContext uses the installed Configuration (instead of a caller-specified Configuration, see above), then this LoginContext must wrap any caller-specified or default CallbackHandler implementation in a new CallbackHandler implementation whose handle method implementation invokes the specified CallbackHandler's handle method in a java.security.AccessController.doPrivileged call constrained by the caller's current AccessControlContext.

Note that Security Properties (such as auth.login.defaultCallbackHandler) can be set programmatically via the java.security.Security class, or statically in the Java security properties file located in the file named <JAVA_HOME>/lib/security/java.security. <JAVA_HOME> refers to the value of the java.home system property, and specifies the directory where the JRE is installed.

See Also:
Security, AuthPermission, Subject, CallbackHandler, Configuration, LoginModule

Constructor Summary
LoginContext(String name)
Instantiate a new LoginContext object with a name.
LoginContext(String name, CallbackHandler callbackHandler)
Instantiate a new LoginContext object with a name and a CallbackHandler object.
LoginContext(String name, Subject subject)
Instantiate a new LoginContext object with a name and a Subject object.
LoginContext(String name, Subject subject, CallbackHandler callbackHandler)
Instantiate a new LoginContext object with a name, a Subject to be authenticated, and a CallbackHandler object.
LoginContext(String name, Subject subject, CallbackHandler callbackHandler, Configuration config)
Instantiate a new LoginContext object with a name, a Subject to be authenticated, a CallbackHandler object, and a login Configuration.
Method Summary
Subject | getSubject() Return the authenticated Subject.
void | login() Perform the authentication.
void | logout() Logout the Subject.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LoginContext

public LoginContext(String name)
             throws LoginException
Instantiate a new LoginContext object with a name.

Parameters:
name - the name used as the index into the Configuration.
Throws:
LoginException - if the caller-specified name does not appear in the Configuration and there is no Configuration entry for "other", or if the auth.login.defaultCallbackHandler security property was set, but the implementation class could not be loaded.

SecurityException - if a SecurityManager is set and the caller does not have AuthPermission("createLoginContext.name"), or if a configuration entry for name does not exist and the caller does not additionally have AuthPermission("createLoginContext.other")

LoginContext

public LoginContext(String name,
                    Subject subject)
             throws LoginException
Instantiate a new LoginContext object with a name and a Subject object.

Parameters:
name - the name used as the index into the Configuration.

subject - the Subject to authenticate.
Throws:
LoginException - if the caller-specified name does not appear in the Configuration and there is no Configuration entry for "other", if the caller-specified subject is null, or if the auth.login.defaultCallbackHandler security property was set, but the implementation class could not be loaded.

SecurityException - if a SecurityManager is set and the caller does not have AuthPermission("createLoginContext.name"), or if a configuration entry for name does not exist and the caller does not additionally have AuthPermission("createLoginContext.other")

LoginContext

public LoginContext(String name,
                    CallbackHandler callbackHandler)
             throws LoginException
Instantiate a new LoginContext object with a name and a CallbackHandler object.

Parameters:
name - the name used as the index into the Configuration.

callbackHandler - the CallbackHandler object used by LoginModules to communicate with the user.
Throws:
LoginException - if the caller-specified name does not appear in the Configuration and there is no Configuration entry for "other", or if the caller-specified callbackHandler is null.

SecurityException - if a SecurityManager is set and the caller does not have AuthPermission("createLoginContext.name"), or if a configuration entry for name does not exist and the caller does not additionally have AuthPermission("createLoginContext.other")

LoginContext

public LoginContext(String name,
                    Subject subject,
                    CallbackHandler callbackHandler)
             throws LoginException
Instantiate a new LoginContext object with a name, a Subject to be authenticated, and a CallbackHandler object.

Parameters:
name - the name used as the index into the Configuration.

subject - the Subject to authenticate.

callbackHandler - the CallbackHandler object used by LoginModules to communicate with the user.
Throws:
LoginException - if the caller-specified name does not appear in the Configuration and there is no Configuration entry for "other", or if the caller-specified subject is null, or if the caller-specified callbackHandler is null.

SecurityException - if a SecurityManager is set and the caller does not have AuthPermission("createLoginContext.name"), or if a configuration entry for name does not exist and the caller does not additionally have AuthPermission("createLoginContext.other")

LoginContext

public LoginContext(String name,
                    Subject subject,
                    CallbackHandler callbackHandler,
                    Configuration config)
             throws LoginException
Instantiate a new LoginContext object with a name, a Subject to be authenticated, a CallbackHandler object, and a login Configuration.

Parameters:
name - the name used as the index into the caller-specified Configuration.

subject - the Subject to authenticate, or null.

callbackHandler - the CallbackHandler object used by LoginModules to communicate with the user, or null.

config - the Configuration that lists the login modules to be called to perform the authentication, or null.
Throws:
LoginException - if the caller-specified name does not appear in the Configuration and there is no Configuration entry for "other".

SecurityException - if a SecurityManager is set, config is null, and either the caller does not have AuthPermission("createLoginContext.name"), or if a configuration entry for name does not exist and the caller does not additionally have AuthPermission("createLoginContext.other")
Since:
1.5
Method Detail

login

public void login()
           throws LoginException
Perform the authentication.

This method invokes the login method for each LoginModule configured for the name specified to the LoginContext constructor, as determined by the login Configuration. Each LoginModule then performs its respective type of authentication (username/password, smart card pin verification, etc.).

This method completes a 2-phase authentication process by calling each configured LoginModule's commit method if the overall authentication succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT, and OPTIONAL LoginModules succeeded), or by calling each configured LoginModule's abort method if the overall authentication failed. If authentication succeeded, each successful LoginModule's commit method associates the relevant Principals and Credentials with the Subject. If authentication failed, each LoginModule's abort method removes/destroys any previously stored state.

If the commit phase of the authentication process fails, then the overall authentication fails and this method invokes the abort method for each configured LoginModule.

If the abort phase fails for any reason, then this method propagates the original exception thrown either during the login phase or the commit phase. In either case, the overall authentication fails.

In the case where multiple LoginModules fail, this method propagates the exception raised by the first LoginModule which failed.

Note that if this method enters the abort phase (either the login or commit phase failed), this method invokes all LoginModules configured for the application regardless of their respective Configuration flag parameters. Essentially this means that Requisite and Sufficient semantics are ignored during the abort phase. This guarantees that proper cleanup and state restoration can take place.

Throws:
LoginException - if the authentication fails.

logout

public void logout()
            throws LoginException
Logout the Subject.

This method invokes the logout method for each LoginModule configured for this LoginContext. Each LoginModule performs its respective logout procedure which may include removing/destroying Principal and Credential information from the Subject and state cleanup.

Note that this method invokes all LoginModules configured for the application regardless of their respective Configuration flag parameters. Essentially this means that Requisite and Sufficient semantics are ignored for this method. This guarantees that proper cleanup and state restoration can take place.

Throws:
LoginException - if the logout fails.

getSubject

public Subject getSubject()
Return the authenticated Subject.

Returns:
the authenticated Subject. If the caller specified a Subject to this LoginContext's constructor, this method returns the caller-specified Subject. If a Subject was not specified and authentication succeeds, this method returns the Subject instantiated and used for authentication by this LoginContext. If a Subject was not specified, and authentication fails or has not been attempted, this method returns null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LoginException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.login
Class LoginException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.security.GeneralSecurityException
                extended by  javax.security.auth.login.LoginException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
AccountException, CredentialException, FailedLoginException
public class LoginException
extends GeneralSecurityException

This is the basic login exception.

See Also:
LoginContext, Serialized Form

Constructor Summary
LoginException()
Constructs a LoginException with no detail message.
LoginException(String msg)
Constructs a LoginException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

LoginException

public LoginException()
Constructs a LoginException with no detail message. A detail message is a String that describes this particular exception.

LoginException

public LoginException(String msg)
Constructs a LoginException with the specified detail message. A detail message is a String that describes this particular exception.

Parameters:
msg - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Policy

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth
Class Policy

java.lang.Object
    extended by  javax.security.auth.Policy
Deprecated. as of JDK version 1.4 -- Replaced by java.security.Policy. java.security.Policy has a method:
        public PermissionCollection getPermissions
            (java.security.ProtectionDomain pd)
and ProtectionDomain has a constructor:
        public ProtectionDomain
            (CodeSource cs,
             PermissionCollection permissions,
             ClassLoader loader,
             Principal[] principals)
These two APIs provide callers the means to query the Policy for Principal-based Permission entries.

@Deprecated
public abstract class Policy
extends Object

This is an abstract class for representing the system policy for Subject-based authorization. A subclass implementation of this class provides a means to specify a Subject-based access control Policy.

A Policy object can be queried for the set of Permissions granted to code running as a Principal in the following manner:

        policy = Policy.getPolicy();
        PermissionCollection perms = policy.getPermissions(subject,
                                                        codeSource);
The Policy object consults the local policy and returns and appropriate Permissions object with the Permissions granted to the Principals associated with the provided subject, and granted to the code specified by the provided codeSource.

A Policy contains the following information. Note that this example only represents the syntax for the default Policy implementation. Subclass implementations of this class may implement alternative syntaxes and may retrieve the Policy from any source such as files, databases, or servers.

Each entry in the Policy is represented as a grant entry. Each grant entry specifies a codebase, code signers, and Principals triplet, as well as the Permissions granted to that triplet.

        grant CodeBase ["URL"], Signedby ["signers"],
              Principal [Principal_Class] "Principal_Name" {
            Permission Permission_Class ["Target_Name"]
                                        [, "Permission_Actions"]
                                        [, signedBy "SignerName"];
        };
The CodeBase and Signedby components of the triplet name/value pairs are optional. If they are not present, then any any codebase will match, and any signer (including unsigned code) will match. For Example,
        grant CodeBase "foo.com", Signedby "foo",
              Principal com.sun.security.auth.SolarisPrincipal "duke" {
            permission java.io.FilePermission "/home/duke", "read, write";
        };
This grant entry specifies that code from "foo.com", signed by "foo', and running as a SolarisPrincipal with the name, duke, has one Permission. This Permission permits the executing code to read and write files in the directory, "/home/duke".

To "run" as a particular Principal, code invokes the Subject.doAs(subject, ...) method. After invoking that method, the code runs as all the Principals associated with the specified Subject. Note that this Policy (and the Permissions granted in this Policy) only become effective after the call to Subject.doAs has occurred.

Multiple Principals may be listed within one grant entry. All the Principals in the grant entry must be associated with the Subject provided to Subject.doAs for that Subject to be granted the specified Permissions.

        grant Principal com.sun.security.auth.SolarisPrincipal "duke",
              Principal com.sun.security.auth.SolarisNumericUserPrincipal "0" {
            permission java.io.FilePermission "/home/duke", "read, write";
            permission java.net.SocketPermission "duke.com", "connect";
        };
This entry grants any code running as both "duke" and "0" permission to read and write files in duke's home directory, as well as permission to make socket connections to "duke.com".

Note that non Principal-based grant entries are not permitted in this Policy. Therefore, grant entries such as:

        grant CodeBase "foo.com", Signedby "foo" {
            permission java.io.FilePermission "/tmp/scratch", "read, write";
        };
are rejected. Such permission must be listed in the java.security.Policy.

The default Policy implementation can be changed by setting the value of the "auth.policy.provider" security property (in the Java security properties file) to the fully qualified name of the desired Policy implementation class. The Java security properties file is located in the file named <JAVA_HOME>/lib/security/java.security. <JAVA_HOME> refers to the value of the java.home system property, and specifies the directory where the JRE is installed.

Constructor Summary
protected Policy()
Deprecated. Sole constructor.
Method Summary
abstract PermissionCollection | getPermissions(Subject subject, CodeSource cs) Deprecated. Retrieve the Permissions granted to the Principals associated with the specified CodeSource.
static Policy | getPolicy() Deprecated. Returns the installed Policy object.
abstract void | refresh() Deprecated. Refresh and reload the Policy.
static void | setPolicy(Policy policy) Deprecated. Sets the system-wide Policy object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Policy

protected Policy()
Deprecated.
Sole constructor. (For invocation by subclass constructors, typically implicit.)

Method Detail

getPolicy

public static Policy getPolicy()
Deprecated.
Returns the installed Policy object. This method first calls SecurityManager.checkPermission with the AuthPermission("getPolicy") permission to ensure the caller has permission to get the Policy object.

Returns:
the installed Policy. The return value cannot be null.
Throws:
SecurityException - if the current thread does not have permission to get the Policy object.
See Also:
setPolicy(javax.security.auth.Policy)

setPolicy

public static void setPolicy(Policy policy)
Deprecated.
Sets the system-wide Policy object. This method first calls SecurityManager.checkPermission with the AuthPermission("setPolicy") permission to ensure the caller has permission to set the Policy.

Parameters:
policy - the new system Policy object.
Throws:
SecurityException - if the current thread does not have permission to set the Policy.
See Also:
getPolicy()

getPermissions

public abstract PermissionCollection getPermissions(Subject subject,
                                                    CodeSource cs)
Deprecated.
Retrieve the Permissions granted to the Principals associated with the specified CodeSource.

Parameters:
subject - the Subject whose associated Principals, in conjunction with the provided CodeSource, determines the Permissions returned by this method. This parameter may be null.

cs - the code specified by its CodeSource that determines, in conjunction with the provided Subject, the Permissions returned by this method. This parameter may be null.
Returns:
the Collection of Permissions granted to all the Subject and code specified in the provided subject and cs parameters.

refresh

public abstract void refresh()
Deprecated.
Refresh and reload the Policy.

This method causes this object to refresh/reload its current Policy. This is implementation-dependent. For example, if the Policy object is stored in a file, calling refresh will cause the file to be re-read.

Throws:
SecurityException - if the caller does not have permission to refresh the Policy.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrivateCredentialPermission

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth
Class PrivateCredentialPermission

java.lang.Object
    extended by  java.security.Permission
        extended by  javax.security.auth.PrivateCredentialPermission
All Implemented Interfaces:
Serializable, Guard
public final class PrivateCredentialPermission
extends Permission

This class is used to protect access to private Credentials belonging to a particular Subject. The Subject is represented by a Set of Principals.

The target name of this Permission specifies a Credential class name, and a Set of Principals. The only valid value for this Permission's actions is, "read". The target name must abide by the following syntax:

        CredentialClass {PrincipalClass "PrincipalName"}*
For example, the following permission grants access to the com.sun.PrivateCredential owned by Subjects which have a com.sun.Principal with the name, "duke". Note that although this example, as well as all the examples below, do not contain Codebase, SignedBy, or Principal information in the grant statement (for simplicity reasons), actual policy configurations should specify that information when appropriate.

    grant {
        permission javax.security.auth.PrivateCredentialPermission
                "com.sun.PrivateCredential com.sun.Principal \"duke\"",
                "read";
    };
If CredentialClass is "*", then access is granted to all private Credentials belonging to the specified Subject. If "PrincipalName" is "*", then access is granted to the specified Credential owned by any Subject that has the specified Principal (the actual PrincipalName doesn't matter). For example, the following grants access to the a.b.Credential owned by any Subject that has an a.b.Principal.
    grant {
        permission javax.security.auth.PrivateCredentialPermission
                "a.b.Credential a.b.Principal "*"",
                "read";
    };
If both the PrincipalClass and "PrincipalName" are "*", then access is granted to the specified Credential owned by any Subject.

In addition, the PrincipalClass/PrincipalName pairing may be repeated:

    grant {
        permission javax.security.auth.PrivateCredentialPermission
                "a.b.Credential a.b.Principal "duke" c.d.Principal "dukette"",
                "read";
    };
The above grants access to the private Credential, "a.b.Credential", belonging to a Subject with at least two associated Principals: "a.b.Principal" with the name, "duke", and "c.d.Principal", with the name, "dukette".

See Also:
Serialized Form

Constructor Summary
PrivateCredentialPermission(String name, String actions)
Creates a new PrivateCredentialPermission with the specified name.
Method Summary
boolean | equals(Object obj) Checks two PrivateCredentialPermission objects for equality.
String | getActions() Returns the "canonical string representation" of the actions.
String | getCredentialClass() Returns the Class name of the Credential associated with this PrivateCredentialPermission.
String[][] | getPrincipals() Returns the Principal classes and names associated with this PrivateCredentialPermission.
int | hashCode() Returns the hash code value for this object.
boolean | implies(Permission p) Checks if this PrivateCredentialPermission implies the specified Permission.
PermissionCollection | newPermissionCollection() Return a homogeneous collection of PrivateCredentialPermissions in a PermissionCollection.
Methods inherited from class java.security.Permission
checkGuard, getName, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

PrivateCredentialPermission

public PrivateCredentialPermission(String name,
                                   String actions)
Creates a new PrivateCredentialPermission with the specified name. The name specifies both a Credential class and a Principal Set.

Parameters:
name - the name specifying the Credential class and Principal Set.

actions - the actions specifying that the Credential can be read.
Throws:
IllegalArgumentException - if name does not conform to the correct syntax or if actions is not "read".
Method Detail

getCredentialClass

public String getCredentialClass()
Returns the Class name of the Credential associated with this PrivateCredentialPermission.

Returns:
the Class name of the Credential associated with this PrivateCredentialPermission.

getPrincipals

public String[][] getPrincipals()
Returns the Principal classes and names associated with this PrivateCredentialPermission. The information is returned as a two-dimensional array (array[x][y]). The 'x' value corresponds to the number of Principal class and name pairs. When (y==0), it corresponds to the Principal class value, and when (y==1), it corresponds to the Principal name value. For example, array[0][0] corresponds to the class name of the first Principal in the array. array[0][1] corresponds to the Principal name of the first Principal in the array.

Returns:
the Principal class and names associated with this PrivateCredentialPermission.

implies

public boolean implies(Permission p)
Checks if this PrivateCredentialPermission implies the specified Permission.

This method returns true if:

  • p is an instanceof PrivateCredentialPermission and

  • the target name for p is implied by this object's target name. For example:
            [* P1 "duke"] implies [a.b.Credential P1 "duke"].
        [C1 P1 "duke"] implies [C1 P1 "duke" P2 "dukette"].
        [C1 P2 "dukette"] implies [C1 P1 "duke" P2 "dukette"].

Specified by:
implies in class Permission
Parameters:
p - the Permission to check against.
Returns:
true if this PrivateCredentialPermission implies the specified Permission, false if not.

equals

public boolean equals(Object obj)
Checks two PrivateCredentialPermission objects for equality. Checks that obj is a PrivateCredentialPermission, and has the same credential class as this object, as well as the same Principals as this object. The order of the Principals in the respective Permission's target names is not relevant.

Specified by:
equals in class Permission
Parameters:
obj - the object we are testing for equality with this object.
Returns:
true if obj is a PrivateCredentialPermission, has the same credential class as this object, and has the same Principals as this object.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns the hash code value for this object.

Specified by:
hashCode in class Permission
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

getActions

public String getActions()
Returns the "canonical string representation" of the actions. This method always returns the String, "read".

Specified by:
getActions in class Permission
Returns:
the actions (always returns "read").

newPermissionCollection

public PermissionCollection newPermissionCollection()
Return a homogeneous collection of PrivateCredentialPermissions in a PermissionCollection. No such PermissionCollection is defined, so this method always returns null.

Overrides:
newPermissionCollection in class Permission
Returns:
null in all cases.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Refreshable

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth
Interface Refreshable

All Known Implementing Classes:
KerberosTicket
public interface Refreshable

Objects such as credentials may optionally implement this interface to provide the capability to refresh itself. For example, a credential with a particular time-restricted lifespan may implement this interface to allow callers to refresh the time period for which it is valid.

See Also:
Subject

Method Summary
boolean | isCurrent() Determine if this Object is current.
void | refresh() Update or extend the validity period for this Object.

Method Detail

isCurrent

boolean isCurrent()
Determine if this Object is current.

Returns:
true if this Object is currently current, false otherwise.

refresh

void refresh()
             throws RefreshFailedException
Update or extend the validity period for this Object.

Throws:
SecurityException - if the caller does not have permission to update or extend the validity period for this Object.

RefreshFailedException - if the refresh attempt failed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RefreshFailedException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth
Class RefreshFailedException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.security.auth.RefreshFailedException
All Implemented Interfaces:
Serializable
public class RefreshFailedException
extends Exception

Signals that a refresh operation failed.

This exception is thrown by credentials implementing the Refreshable interface when the refresh method fails.

See Also:
Serialized Form

Constructor Summary
RefreshFailedException()
Constructs a RefreshFailedException with no detail message.
RefreshFailedException(String msg)
Constructs a RefreshFailedException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RefreshFailedException

public RefreshFailedException()
Constructs a RefreshFailedException with no detail message. A detail message is a String that describes this particular exception.

RefreshFailedException

public RefreshFailedException(String msg)
Constructs a RefreshFailedException with the specified detail message. A detail message is a String that describes this particular exception.

Parameters:
msg - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


spi

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.security.auth.spi

This package provides the interface to be used for implementing pluggable authentication modules.

See:
Description

Interface Summary
LoginModule LoginModule describes the interface implemented by authentication technology providers.

Package javax.security.auth.spi Description

This package provides the interface to be used for implementing pluggable authentication modules.

Since:
JDK1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.security.auth.spi Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.security.auth.spi

Package Hierarchies:
All Packages

Interface Hierarchy

  • javax.security.auth.spi.LoginModule
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.security.auth.spi

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.security.auth.spi

No usage of javax.security.auth.spi

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.security.auth.spi.LoginModule

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.security.auth.spi.LoginModule

No usage of javax.security.auth.spi.LoginModule

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


LoginModule

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.spi
Interface LoginModule

public interface LoginModule

LoginModule describes the interface implemented by authentication technology providers. LoginModules are plugged in under applications to provide a particular type of authentication.

While applications write to the LoginContext API, authentication technology providers implement the LoginModule interface. A Configuration specifies the LoginModule(s) to be used with a particular login application. Therefore different LoginModules can be plugged in under the application without requiring any modifications to the application itself.

The LoginContext is responsible for reading the Configuration and instantiating the appropriate LoginModules. Each LoginModule is initialized with a Subject, a CallbackHandler, shared LoginModule state, and LoginModule-specific options. The Subject represents the Subject currently being authenticated and is updated with relevant Credentials if authentication succeeds. LoginModules use the CallbackHandler to communicate with users. The CallbackHandler may be used to prompt for usernames and passwords, for example. Note that the CallbackHandler may be null. LoginModules which absolutely require a CallbackHandler to authenticate the Subject may throw a LoginException. LoginModules optionally use the shared state to share information or data among themselves.

The LoginModule-specific options represent the options configured for this LoginModule by an administrator or user in the login Configuration. The options are defined by the LoginModule itself and control the behavior within it. For example, a LoginModule may define options to support debugging/testing capabilities. Options are defined using a key-value syntax, such as debug=true. The LoginModule stores the options as a Map so that the values may be retrieved using the key. Note that there is no limit to the number of options a LoginModule chooses to define.

The calling application sees the authentication process as a single operation. However, the authentication process within the LoginModule proceeds in two distinct phases. In the first phase, the LoginModule's login method gets invoked by the LoginContext's login method. The login method for the LoginModule then performs the actual authentication (prompt for and verify a password for example) and saves its authentication status as private state information. Once finished, the LoginModule's login method either returns true (if it succeeded) or false (if it should be ignored), or throws a LoginException to specify a failure. In the failure case, the LoginModule must not retry the authentication or introduce delays. The responsibility of such tasks belongs to the application. If the application attempts to retry the authentication, the LoginModule's login method will be called again.

In the second phase, if the LoginContext's overall authentication succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules succeeded), then the commit method for the LoginModule gets invoked. The commit method for a LoginModule checks its privately saved state to see if its own authentication succeeded. If the overall LoginContext authentication succeeded and the LoginModule's own authentication succeeded, then the commit method associates the relevant Principals (authenticated identities) and Credentials (authentication data such as cryptographic keys) with the Subject located within the LoginModule.

If the LoginContext's overall authentication failed (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules did not succeed), then the abort method for each LoginModule gets invoked. In this case, the LoginModule removes/destroys any authentication state originally saved.

Logging out a Subject involves only one phase. The LoginContext invokes the LoginModule's logout method. The logout method for the LoginModule then performs the logout procedures, such as removing Principals or Credentials from the Subject or logging session information.

A LoginModule implementation must have a constructor with no arguments. This allows classes which load the LoginModule to instantiate it.

See Also:
LoginContext, Configuration

Method Summary
boolean | abort() Method to abort the authentication process (phase 2).
boolean | commit() Method to commit the authentication process (phase 2).
void | initialize(Subject subject, CallbackHandler callbackHandler, Map<String,?> sharedState, Map<String,?> options) Initialize this LoginModule.
boolean | login() Method to authenticate a Subject (phase 1).
boolean | logout() Method which logs out a Subject.

Method Detail

initialize

void initialize(Subject subject,
                CallbackHandler callbackHandler,
                Map<String,?> sharedState,
                Map<String,?> options)
Initialize this LoginModule.

This method is called by the LoginContext after this LoginModule has been instantiated. The purpose of this method is to initialize this LoginModule with the relevant information. If this LoginModule does not understand any of the data stored in sharedState or options parameters, they can be ignored.

Parameters:
subject - the Subject to be authenticated.

callbackHandler - a CallbackHandler for communicating with the end user (prompting for usernames and passwords, for example).

sharedState - state shared with other configured LoginModules.

options - options specified in the login Configuration for this particular LoginModule.

login

boolean login()
              throws LoginException
Method to authenticate a Subject (phase 1).

The implementation of this method authenticates a Subject. For example, it may prompt for Subject information such as a username and password and then attempt to verify the password. This method saves the result of the authentication attempt as private state within the LoginModule.

Returns:
true if the authentication succeeded, or false if this LoginModule should be ignored.
Throws:
LoginException - if the authentication fails

commit

boolean commit()
               throws LoginException
Method to commit the authentication process (phase 2).

This method is called if the LoginContext's overall authentication succeeded (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules succeeded).

If this LoginModule's own authentication attempt succeeded (checked by retrieving the private state saved by the login method), then this method associates relevant Principals and Credentials with the Subject located in the LoginModule. If this LoginModule's own authentication attempted failed, then this method removes/destroys any state that was originally saved.

Returns:
true if this method succeeded, or false if this LoginModule should be ignored.
Throws:
LoginException - if the commit fails

abort

boolean abort()
              throws LoginException
Method to abort the authentication process (phase 2).

This method is called if the LoginContext's overall authentication failed. (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules did not succeed).

If this LoginModule's own authentication attempt succeeded (checked by retrieving the private state saved by the login method), then this method cleans up any state that was originally saved.

Returns:
true if this method succeeded, or false if this LoginModule should be ignored.
Throws:
LoginException - if the abort fails

logout

boolean logout()
               throws LoginException
Method which logs out a Subject.

An implementation of this method might remove/destroy a Subject's Principals and Credentials.

Returns:
true if this method succeeded, or false if this LoginModule should be ignored.
Throws:
LoginException - if the logout fails
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Subject

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.auth
Class Subject

java.lang.Object
    extended by  javax.security.auth.Subject
All Implemented Interfaces:
Serializable
public final class Subject
extends Object
implements Serializable

A Subject represents a grouping of related information for a single entity, such as a person. Such information includes the Subject's identities as well as its security-related attributes (passwords and cryptographic keys, for example).

Subjects may potentially have multiple identities. Each identity is represented as a Principal within the Subject. Principals simply bind names to a Subject. For example, a Subject that happens to be a person, Alice, might have two Principals: one which binds "Alice Bar", the name on her driver license, to the Subject, and another which binds, "999-99-9999", the number on her student identification card, to the Subject. Both Principals refer to the same Subject even though each has a different name.

A Subject may also own security-related attributes, which are referred to as credentials. Sensitive credentials that require special protection, such as private cryptographic keys, are stored within a private credential Set. Credentials intended to be shared, such as public key certificates or Kerberos server tickets are stored within a public credential Set. Different permissions are required to access and modify the different credential Sets.

To retrieve all the Principals associated with a Subject, invoke the getPrincipals method. To retrieve all the public or private credentials belonging to a Subject, invoke the getPublicCredentials method or getPrivateCredentials method, respectively. To modify the returned Set of Principals and credentials, use the methods defined in the Set class. For example:

        Subject subject;
        Principal principal;
        Object credential;

        // add a Principal and credential to the Subject
        subject.getPrincipals().add(principal);
        subject.getPublicCredentials().add(credential);

This Subject class implements Serializable. While the Principals associated with the Subject are serialized, the credentials associated with the Subject are not. Note that the java.security.Principal class does not implement Serializable. Therefore all concrete Principal implementations associated with Subjects must implement Serializable.

See Also:
Principal, DomainCombiner, Serialized Form

Constructor Summary
Subject()
Create an instance of a Subject with an empty Set of Principals and empty Sets of public and private credentials.
Subject(boolean readOnly, Set<? extends Principal> principals, Set<?> pubCredentials, Set<?> privCredentials)
Create an instance of a Subject with Principals and credentials.
Method Summary
static
<T> T
doAs(Subject subject, PrivilegedAction<T> action)
Perform work as a particular Subject.
static
<T> T
doAs(Subject subject, PrivilegedExceptionAction<T> action)
Perform work as a particular Subject.
static
<T> T
doAsPrivileged(Subject subject, PrivilegedAction<T> action, AccessControlContext acc)
Perform privileged work as a particular Subject.
static
<T> T
doAsPrivileged(Subject subject, PrivilegedExceptionAction<T> action, AccessControlContext acc)
Perform privileged work as a particular Subject.
 boolean equals(Object o)
Compares the specified Object with this Subject for equality.
 Set<Principal> getPrincipals()
Return the Set of Principals associated with this Subject.
<T extends Principal>
Set<T>
getPrincipals(Class<T> c)
Return a Set of Principals associated with this Subject that are instances or subclasses of the specified Class.
 Set<Object> getPrivateCredentials()
Return the Set of private credentials held by this Subject.
<T> Set<T>
getPrivateCredentials(Class<T> c)
Return a Set of private credentials associated with this Subject that are instances or subclasses of the specified Class.
 Set<Object> getPublicCredentials()
Return the Set of public credentials held by this Subject.
<T> Set<T>
getPublicCredentials(Class<T> c)
Return a Set of public credentials associated with this Subject that are instances or subclasses of the specified Class.
static Subject getSubject(AccessControlContext acc)
Get the Subject associated with the provided AccessControlContext.
 int hashCode()
Returns a hashcode for this Subject.
 boolean isReadOnly()
Query whether this Subject is read-only.
 void setReadOnly()
Set this Subject to be read-only.
 String toString()
Return the String representation of this Subject.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Subject

public Subject()
Create an instance of a Subject with an empty Set of Principals and empty Sets of public and private credentials.

The newly constructed Sets check whether this Subject has been set read-only before permitting subsequent modifications. The newly created Sets also prevent illegal modifications by ensuring that callers have sufficient permissions.

To modify the Principals Set, the caller must have AuthPermission("modifyPrincipals"). To modify the public credential Set, the caller must have AuthPermission("modifyPublicCredentials"). To modify the private credential Set, the caller must have AuthPermission("modifyPrivateCredentials").

Subject

public Subject(boolean readOnly,
               Set<? extends Principal> principals,
               Set<?> pubCredentials,
               Set<?> privCredentials)
Create an instance of a Subject with Principals and credentials.

The Principals and credentials from the specified Sets are copied into newly constructed Sets. These newly created Sets check whether this Subject has been set read-only before permitting subsequent modifications. The newly created Sets also prevent illegal modifications by ensuring that callers have sufficient permissions.

To modify the Principals Set, the caller must have AuthPermission("modifyPrincipals"). To modify the public credential Set, the caller must have AuthPermission("modifyPublicCredentials"). To modify the private credential Set, the caller must have AuthPermission("modifyPrivateCredentials").

Parameters:
readOnly - true if the Subject is to be read-only, and false otherwise.

principals - the Set of Principals to be associated with this Subject.

pubCredentials - the Set of public credentials to be associated with this Subject.

privCredentials - the Set of private credentials to be associated with this Subject.
Throws:
NullPointerException - if the specified principals, pubCredentials, or privCredentials are null.
Method Detail

setReadOnly

public void setReadOnly()
Set this Subject to be read-only.

Modifications (additions and removals) to this Subject's Principal Set and credential Sets will be disallowed. The destroy operation on this Subject's credentials will still be permitted.

Subsequent attempts to modify the Subject's Principal and credential Sets will result in an IllegalStateException being thrown. Also, once a Subject is read-only, it can not be reset to being writable again.

Throws:
SecurityException - if the caller does not have permission to set this Subject to be read-only.

isReadOnly

public boolean isReadOnly()
Query whether this Subject is read-only.

Returns:
true if this Subject is read-only, false otherwise.

getSubject

public static Subject getSubject(AccessControlContext acc)
Get the Subject associated with the provided AccessControlContext.

The AccessControlContext may contain many Subjects (from nested doAs calls). In this situation, the most recent Subject associated with the AccessControlContext is returned.

Parameters:
acc - the AccessControlContext from which to retrieve the Subject.
Returns:
the Subject associated with the provided AccessControlContext, or null if no Subject is associated with the provided AccessControlContext.
Throws:
SecurityException - if the caller does not have permission to get the Subject.

NullPointerException - if the provided AccessControlContext is null.

doAs

public static <T> T doAs(Subject subject,
                         PrivilegedAction<T> action)
Perform work as a particular Subject.

This method first retrieves the current Thread's AccessControlContext via AccessController.getContext, and then instantiates a new AccessControlContext using the retrieved context along with a new SubjectDomainCombiner (constructed using the provided Subject). Finally, this method invokes AccessController.doPrivileged, passing it the provided PrivilegedAction, as well as the newly constructed AccessControlContext.

Parameters:
subject - the Subject that the specified action will run as. This parameter may be null.

action - the code to be run as the specified Subject.

Returns:
the value returned by the PrivilegedAction's run method.
Throws:
NullPointerException - if the PrivilegedAction is null.

SecurityException - if the caller does not have permission to invoke this method.

doAs

public static <T> T doAs(Subject subject,
                         PrivilegedExceptionAction<T> action)
              throws PrivilegedActionException
Perform work as a particular Subject.

This method first retrieves the current Thread's AccessControlContext via AccessController.getContext, and then instantiates a new AccessControlContext using the retrieved context along with a new SubjectDomainCombiner (constructed using the provided Subject). Finally, this method invokes AccessController.doPrivileged, passing it the provided PrivilegedExceptionAction, as well as the newly constructed AccessControlContext.

Parameters:
subject - the Subject that the specified action will run as. This parameter may be null.

action - the code to be run as the specified Subject.

Returns:
the value returned by the PrivilegedExceptionAction's run method.
Throws:
PrivilegedActionException - if the PrivilegedExceptionAction.run method throws a checked exception.

NullPointerException - if the specified PrivilegedExceptionAction is null.

SecurityException - if the caller does not have permission to invoke this method.

doAsPrivileged

public static <T> T doAsPrivileged(Subject subject,
                                   PrivilegedAction<T> action,
                                   AccessControlContext acc)
Perform privileged work as a particular Subject.

This method behaves exactly as Subject.doAs, except that instead of retrieving the current Thread's AccessControlContext, it uses the provided AccessControlContext. If the provided AccessControlContext is null, this method instantiates a new AccessControlContext with an empty collection of ProtectionDomains.

Parameters:
subject - the Subject that the specified action will run as. This parameter may be null.

action - the code to be run as the specified Subject.

acc - the AccessControlContext to be tied to the specified subject and action.

Returns:
the value returned by the PrivilegedAction's run method.
Throws:
NullPointerException - if the PrivilegedAction is null.

SecurityException - if the caller does not have permission to invoke this method.

doAsPrivileged

public static <T> T doAsPrivileged(Subject subject,
                                   PrivilegedExceptionAction<T> action,
                                   AccessControlContext acc)
                        throws PrivilegedActionException
Perform privileged work as a particular Subject.

This method behaves exactly as Subject.doAs, except that instead of retrieving the current Thread's AccessControlContext, it uses the provided AccessControlContext. If the provided AccessControlContext is null, this method instantiates a new AccessControlContext with an empty collection of ProtectionDomains.

Parameters:
subject - the Subject that the specified action will run as. This parameter may be null.

action - the code to be run as the specified Subject.

acc - the AccessControlContext to be tied to the specified subject and action.

Returns:
the value returned by the PrivilegedExceptionAction's run method.
Throws:
PrivilegedActionException - if the PrivilegedExceptionAction.run method throws a checked exception.

NullPointerException - if the specified PrivilegedExceptionAction is null.

SecurityException - if the caller does not have permission to invoke this method.

getPrincipals

public Set<Principal> getPrincipals()
Return the Set of Principals associated with this Subject. Each Principal represents an identity for this Subject.

The returned Set is backed by this Subject's internal Principal Set. Any modification to the returned Set affects the internal Principal Set as well.

Returns:
The Set of Principals associated with this Subject.

getPrincipals

public <T extends Principal> Set<T> getPrincipals(Class<T> c)
Return a Set of Principals associated with this Subject that are instances or subclasses of the specified Class.

The returned Set is not backed by this Subject's internal Principal Set. A new Set is created and returned for each method invocation. Modifications to the returned Set will not affect the internal Principal Set.

Parameters:
c - the returned Set of Principals will all be instances of this class.
Returns:
a Set of Principals that are instances of the specified Class.
Throws:
NullPointerException - if the specified Class is null.

getPublicCredentials

public Set<Object> getPublicCredentials()
Return the Set of public credentials held by this Subject.

The returned Set is backed by this Subject's internal public Credential Set. Any modification to the returned Set affects the internal public Credential Set as well.

Returns:
A Set of public credentials held by this Subject.

getPrivateCredentials

public Set<Object> getPrivateCredentials()
Return the Set of private credentials held by this Subject.

The returned Set is backed by this Subject's internal private Credential Set. Any modification to the returned Set affects the internal private Credential Set as well.

A caller requires permissions to access the Credentials in the returned Set, or to modify the Set itself. A SecurityException is thrown if the caller does not have the proper permissions.

While iterating through the Set, a SecurityException is thrown if the caller does not have permission to access a particular Credential. The Iterator is nevertheless advanced to next element in the Set.

Returns:
A Set of private credentials held by this Subject.

getPublicCredentials

public <T> Set<T> getPublicCredentials(Class<T> c)
Return a Set of public credentials associated with this Subject that are instances or subclasses of the specified Class.

The returned Set is not backed by this Subject's internal public Credential Set. A new Set is created and returned for each method invocation. Modifications to the returned Set will not affect the internal public Credential Set.

Parameters:
c - the returned Set of public credentials will all be instances of this class.
Returns:
a Set of public credentials that are instances of the specified Class.
Throws:
NullPointerException - if the specified Class is null.

getPrivateCredentials

public <T> Set<T> getPrivateCredentials(Class<T> c)
Return a Set of private credentials associated with this Subject that are instances or subclasses of the specified Class.

The caller must have permission to access all of the requested Credentials, or a SecurityException will be thrown.

The returned Set is not backed by this Subject's internal private Credential Set. A new Set is created and returned for each method invocation. Modifications to the returned Set will not affect the internal private Credential Set.

Parameters:
c - the returned Set of private credentials will all be instances of this class.
Returns:
a Set of private credentials that are instances of the specified Class.
Throws:
NullPointerException - if the specified Class is null.

equals

public boolean equals(Object o)
Compares the specified Object with this Subject for equality. Returns true if the given object is also a Subject and the two Subject instances are equivalent. More formally, two Subject instances are equal if their Principal and Credential Sets are equal.

Overrides:
equals in class Object
Parameters:
o - Object to be compared for equality with this Subject.
Returns:
true if the specified Object is equal to this Subject.
Throws:
SecurityException - if the caller does not have permission to access the private credentials for this Subject, or if the caller does not have permission to access the private credentials for the provided Subject.
See Also:
Object.hashCode(), Hashtable

toString

public String toString()
Return the String representation of this Subject.

Overrides:
toString in class Object
Returns:
the String representation of this Subject.

hashCode

public int hashCode()
Returns a hashcode for this Subject.

Overrides:
hashCode in class Object
Returns:
a hashcode for this Subject.
Throws:
SecurityException - if the caller does not have permission to access this Subject's private credentials.
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SubjectDomainCombiner

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.security.auth
Class SubjectDomainCombiner

java.lang.Object
    extended by  javax.security.auth.SubjectDomainCombiner
All Implemented Interfaces:
DomainCombiner
public class SubjectDomainCombiner
extends Object
implements DomainCombiner

A SubjectDomainCombiner updates ProtectionDomains with Principals from the Subject associated with this SubjectDomainCombiner.

Constructor Summary
SubjectDomainCombiner(Subject subject)
Associate the provided Subject with this SubjectDomainCombiner.
Method Summary
ProtectionDomain[] | combine(ProtectionDomain[] currentDomains, ProtectionDomain[] assignedDomains) Update the relevant ProtectionDomains with the Principals from the Subject associated with this SubjectDomainCombiner.
Subject | getSubject() Get the Subject associated with this SubjectDomainCombiner.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SubjectDomainCombiner

public SubjectDomainCombiner(Subject subject)
Associate the provided Subject with this SubjectDomainCombiner.

Parameters:
subject - the Subject to be associated with with this SubjectDomainCombiner.
Method Detail

getSubject

public Subject getSubject()
Get the Subject associated with this SubjectDomainCombiner.

Returns:
the Subject associated with this SubjectDomainCombiner, or null if no Subject is associated with this SubjectDomainCombiner.
Throws:
SecurityException - if the caller does not have permission to get the Subject associated with this SubjectDomainCombiner.

combine

public ProtectionDomain[] combine(ProtectionDomain[] currentDomains,
                                  ProtectionDomain[] assignedDomains)
Update the relevant ProtectionDomains with the Principals from the Subject associated with this SubjectDomainCombiner.

A new ProtectionDomain instance is created for each ProtectionDomain in the currentDomains array. Each new ProtectionDomain instance is created using the CodeSource, Permissions and ClassLoader from the corresponding ProtectionDomain in currentDomains, as well as with the Principals from the Subject associated with this SubjectDomainCombiner.

All of the newly instantiated ProtectionDomains are combined into a new array. The ProtectionDomains from the assignedDomains array are appended to this new array, and the result is returned.

Note that optimizations such as the removal of duplicate ProtectionDomains may have occurred. In addition, caching of ProtectionDomains may be permitted.

Specified by:
combine in interface DomainCombiner
Parameters:
currentDomains - the ProtectionDomains associated with the current execution Thread, up to the most recent privileged ProtectionDomain. The ProtectionDomains are are listed in order of execution, with the most recently executing ProtectionDomain residing at the beginning of the array. This parameter may be null if the current execution Thread has no associated ProtectionDomains.

assignedDomains - the ProtectionDomains inherited from the parent Thread, or the ProtectionDomains from the privileged context, if a call to AccessController.doPrivileged(..., context) had occurred This parameter may be null if there were no ProtectionDomains inherited from the parent Thread, or from the privileged context.
Returns:
a new array consisting of the updated ProtectionDomains, or null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


x500

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.security.auth.x500

This package contains the classes that should be used to store X500 Principal and X500 Private Crendentials in a Subject.

See:
Description

Class Summary
X500Principal | This class represents an X.500 Principal.
X500PrivateCredential | This class represents an X500PrivateCredential.

Package javax.security.auth.x500 Description

This package contains the classes that should be used to store X500 Principal and X500 Private Crendentials in a Subject.

Since:
JDK1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.security.auth.x500 Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.security.auth.x500

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.security.auth.x500.X500Principal (implements java.security.Principal, java.io.Serializable)
    • javax.security.auth.x500.X500PrivateCredential (implements javax.security.auth.Destroyable)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.security.auth.x500

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.security.auth.x500

Packages that use javax.security.auth.x500
java.security.cert Provides classes and interfaces for parsing and managing certificates, certificate revocation lists (CRLs), and certification paths.

Classes in javax.security.auth.x500 used by java.security.cert
X500Principal
This class represents an X.500 Principal.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.x500.X500Principal

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.x500.X500Principal

Packages that use X500Principal
java.security.cert Provides classes and interfaces for parsing and managing certificates, certificate revocation lists (CRLs), and certification paths.

Uses of X500Principal in java.security.cert

Methods in java.security.cert that return X500Principal
X500Principal | TrustAnchor.getCA() Returns the name of the most-trusted CA as an X500Principal.
X500Principal | X509CRLEntry.getCertificateIssuer() Get the issuer of the X509Certificate described by this entry.
X500Principal | X509CertSelector.getIssuer() Returns the issuer criterion as an X500Principal.
X500Principal | X509CRL.getIssuerX500Principal() Returns the issuer (issuer distinguished name) value from the CRL as an X500Principal.
X500Principal | X509Certificate.getIssuerX500Principal() Returns the issuer (issuer distinguished name) value from the certificate as an X500Principal.
X500Principal | X509CertSelector.getSubject() Returns the subject criterion as an X500Principal.
X500Principal | X509Certificate.getSubjectX500Principal() Returns the subject (subject distinguished name) value from the certificate as an X500Principal.

Methods in java.security.cert that return types with arguments of type X500Principal
 Collection<X500Principal> X509CRLSelector.getIssuers()
Returns the issuerNames criterion.

Methods in java.security.cert with parameters of type X500Principal
void | X509CRLSelector.addIssuer(X500Principal issuer) Adds a name to the issuerNames criterion.
void | X509CertSelector.setIssuer(X500Principal issuer) Sets the issuer criterion.
void | X509CertSelector.setSubject(X500Principal subject) Sets the subject criterion.

Method parameters in java.security.cert with type arguments of type X500Principal
 void X509CRLSelector.setIssuers(Collection<X500Principal> issuers)
Sets the issuerNames criterion.

Constructors in java.security.cert with parameters of type X500Principal
TrustAnchor(X500Principal caPrincipal, PublicKey pubKey, byte[] nameConstraints)
Creates an instance of TrustAnchor where the most-trusted CA is specified as an X500Principal and public key.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.auth.x500.X500PrivateCredential

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.auth.x500.X500PrivateCredential

No usage of javax.security.auth.x500.X500PrivateCredential

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


X500Principal

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.x500
Class X500Principal

java.lang.Object
    extended by  javax.security.auth.x500.X500Principal
All Implemented Interfaces:
Serializable, Principal
public final class X500Principal
extends Object
implements Principal, Serializable

This class represents an X.500 Principal. X500Principals are represented by distinguished names such as "CN=Duke, OU=JavaSoft, O=Sun Microsystems, C=US".

This class can be instantiated by using a string representation of the distinguished name, or by using the ASN.1 DER encoded byte representation of the distinguished name. The current specification for the string representation of a distinguished name is defined in RFC 2253. This class, however, accepts string formats from both RFC 2253 and RFC 1779, and also recognizes attribute type keywords whose OIDs (Object Identifiers) are defined in RFC 2459.

The string representation for this X500Principal can be obtained by calling the getName methods.

Note that the getSubjectX500Principal and getIssuerX500Principal methods of X509Certificate return X500Principals representing the issuer and subject fields of the certificate.

Since:
1.4
See Also:
X509Certificate, Serialized Form

Field Summary
static String | CANONICAL Canonical String format of Distinguished Names.
static String | RFC1779 RFC 1779 String format of Distinguished Names.
static String | RFC2253 RFC 2253 String format of Distinguished Names.
Constructor Summary
X500Principal(byte[] name)
Creates an X500Principal from a distinguished name in ASN.1 DER encoded form.
X500Principal(InputStream is)
Creates an X500Principal from an InputStream containing the distinguished name in ASN.1 DER encoded form.
X500Principal(String name)
Creates an X500Principal from a string representation of an X.500 distinguished name (ex: "CN=Duke, OU=JavaSoft, O=Sun Microsystems, C=US").
X500Principal(String name, Map<String,String> keywordMap)
Creates an X500Principal from a string representation of an X.500 distinguished name (ex: "CN=Duke, OU=JavaSoft, O=Sun Microsystems, C=US").
Method Summary
boolean | equals(Object o) Compares the specified Object with this X500Principal for equality.
byte[] | getEncoded() Returns the distinguished name in ASN.1 DER encoded form.
String | getName() Returns a string representation of the X.500 distinguished name using the format defined in RFC 2253.
String | getName(String format) Returns a string representation of the X.500 distinguished name using the specified format.
String | getName(String format, Map<String,String> oidMap) Returns a string representation of the X.500 distinguished name using the specified format.
int | hashCode() Return a hash code for this X500Principal.
String | toString() Return a user-friendly string representation of this X500Principal.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

RFC1779

public static final String RFC1779
RFC 1779 String format of Distinguished Names.

See Also:
Constant Field Values

RFC2253

public static final String RFC2253
RFC 2253 String format of Distinguished Names.

See Also:
Constant Field Values

CANONICAL

public static final String CANONICAL
Canonical String format of Distinguished Names.

See Also:
Constant Field Values
Constructor Detail

X500Principal

public X500Principal(String name)
Creates an X500Principal from a string representation of an X.500 distinguished name (ex: "CN=Duke, OU=JavaSoft, O=Sun Microsystems, C=US"). The distinguished name must be specified using the grammar defined in RFC 1779 or RFC 2253 (either format is acceptable).

This constructor recognizes the attribute type keywords defined in RFC 1779 and RFC 2253 (and listed in getName(String format)), as well as the T, DNQ or DNQUALIFIER, SURNAME, GIVENNAME, INITIALS, GENERATION, EMAILADDRESS, and SERIALNUMBER keywords whose OIDs are defined in RFC 2459 and its successor. Any other attribute type must be specified as an OID.

Parameters:
name - an X.500 distinguished name in RFC 1779 or RFC 2253 format
Throws:
NullPointerException - if the name is null
IllegalArgumentException - if the name is improperly specified

X500Principal

public X500Principal(String name,
                     Map<String,String> keywordMap)
Creates an X500Principal from a string representation of an X.500 distinguished name (ex: "CN=Duke, OU=JavaSoft, O=Sun Microsystems, C=US"). The distinguished name must be specified using the grammar defined in RFC 1779 or RFC 2253 (either format is acceptable).

This constructor recognizes the attribute type keywords specified in X500Principal(String) and also recognizes additional keywords that have entries in the keywordMap parameter. Keyword entries in the keywordMap take precedence over the default keywords recognized by X500Principal(String). Keywords MUST be specified in all upper-case, otherwise they will be ignored. Improperly specified keywords are ignored; however if a keyword in the name maps to an improperly specified OID, an IllegalArgumentException is thrown. It is permissible to have 2 different keywords that map to the same OID.

Parameters:
name - an X.500 distinguished name in RFC 1779 or RFC 2253 format
keywordMap - an attribute type keyword map, where each key is a keyword String that maps to a corresponding object identifier in String form (a sequence of nonnegative integers separated by periods). The map may be empty but never null.
Throws:
NullPointerException - if name or keywordMap is null
IllegalArgumentException - if the name is improperly specified or a keyword in the name maps to an OID that is not in the correct form
Since:
1.6

X500Principal

public X500Principal(byte[] name)
Creates an X500Principal from a distinguished name in ASN.1 DER encoded form. The ASN.1 notation for this structure is as follows.

 Name ::= CHOICE {
   RDNSequence }

 RDNSequence ::= SEQUENCE OF RelativeDistinguishedName

 RelativeDistinguishedName ::=
   SET SIZE (1 .. MAX) OF AttributeTypeAndValue

 AttributeTypeAndValue ::= SEQUENCE {
   type     AttributeType,
   value    AttributeValue }

 AttributeType ::= OBJECT IDENTIFIER

 AttributeValue ::= ANY DEFINED BY AttributeType
 ....
 DirectoryString ::= CHOICE {
       teletexString           TeletexString (SIZE (1..MAX)),
       printableString         PrintableString (SIZE (1..MAX)),
       universalString         UniversalString (SIZE (1..MAX)),
       utf8String              UTF8String (SIZE (1.. MAX)),
       bmpString               BMPString (SIZE (1..MAX)) }

Parameters:
name - a byte array containing the distinguished name in ASN.1 DER encoded form
Throws:
IllegalArgumentException - if an encoding error occurs (incorrect form for DN)

X500Principal

public X500Principal(InputStream is)
Creates an X500Principal from an InputStream containing the distinguished name in ASN.1 DER encoded form. The ASN.1 notation for this structure is supplied in the documentation for X500Principal(byte[] name).

The read position of the input stream is positioned to the next available byte after the encoded distinguished name.

Parameters:
is - an InputStream containing the distinguished name in ASN.1 DER encoded form
Throws:
NullPointerException - if the InputStream is null
IllegalArgumentException - if an encoding error occurs (incorrect form for DN)
Method Detail

getName

public String getName()
Returns a string representation of the X.500 distinguished name using the format defined in RFC 2253.

This method is equivalent to calling getName(X500Principal.RFC2253).

Specified by:
getName in interface Principal
Returns:
the distinguished name of this X500Principal

getName

public String getName(String format)
Returns a string representation of the X.500 distinguished name using the specified format. Valid values for the format are "RFC1779", "RFC2253", and "CANONICAL" (case insensitive).

If "RFC1779" is specified as the format, this method emits the attribute type keywords defined in RFC 1779 (CN, L, ST, O, OU, C, STREET). Any other attribute type is emitted as an OID.

If "RFC2253" is specified as the format, this method emits the attribute type keywords defined in RFC 2253 (CN, L, ST, O, OU, C, STREET, DC, UID). Any other attribute type is emitted as an OID. Under a strict reading, RFC 2253 only specifies a UTF-8 string representation. The String returned by this method is the Unicode string achieved by decoding this UTF-8 representation.

If "CANONICAL" is specified as the format, this method returns an RFC 2253 conformant string representation with the following additional canonicalizations:

  1. Leading zeros are removed from attribute types that are encoded as dotted decimal OIDs
  2. DirectoryString attribute values of type PrintableString and UTF8String are not output in hexadecimal format
  3. DirectoryString attribute values of types other than PrintableString and UTF8String are output in hexadecimal format
  4. Leading and trailing white space characters are removed from non-hexadecimal attribute values (unless the value consists entirely of white space characters)
  5. Internal substrings of one or more white space characters are converted to a single space in non-hexadecimal attribute values
  6. Relative Distinguished Names containing more than one Attribute Value Assertion (AVA) are output in the following order: an alphabetical ordering of AVAs containing standard keywords, followed by a numeric ordering of AVAs containing OID keywords.
  7. The only characters in attribute values that are escaped are those which section 2.4 of RFC 2253 states must be escaped (they are escaped using a preceding backslash character)
  8. The entire name is converted to upper case using String.toUpperCase(Locale.US)
  9. The entire name is converted to lower case using String.toLowerCase(Locale.US)
  10. The name is finally normalized using normalization form KD, as described in the Unicode Standard and UAX #15

Additional standard formats may be introduced in the future.

Parameters:
format - the format to use
Returns:
a string representation of this X500Principal using the specified format
Throws:
IllegalArgumentException - if the specified format is invalid or null

getName

public String getName(String format,
                      Map<String,String> oidMap)
Returns a string representation of the X.500 distinguished name using the specified format. Valid values for the format are "RFC1779" and "RFC2253" (case insensitive). "CANONICAL" is not permitted and an IllegalArgumentException will be thrown.

This method returns Strings in the format as specified in getName(String) and also emits additional attribute type keywords for OIDs that have entries in the oidMap parameter. OID entries in the oidMap take precedence over the default OIDs recognized by getName(String). Improperly specified OIDs are ignored; however if an OID in the name maps to an improperly specified keyword, an IllegalArgumentException is thrown.

Additional standard formats may be introduced in the future.

Warning: additional attribute type keywords may not be recognized by other implementations; therefore do not use this method if you are unsure if these keywords will be recognized by other implementations.

Parameters:
format - the format to use
oidMap - an OID map, where each key is an object identifier in String form (a sequence of nonnegative integers separated by periods) that maps to a corresponding attribute type keyword String. The map may be empty but never null.
Returns:
a string representation of this X500Principal using the specified format
Throws:
IllegalArgumentException - if the specified format is invalid, null, or an OID in the name maps to an improperly specified keyword
NullPointerException - if oidMap is null
Since:
1.6

getEncoded

public byte[] getEncoded()
Returns the distinguished name in ASN.1 DER encoded form. The ASN.1 notation for this structure is supplied in the documentation for X500Principal(byte[] name).

Note that the byte array returned is cloned to protect against subsequent modifications.

Returns:
a byte array containing the distinguished name in ASN.1 DER encoded form

toString

public String toString()
Return a user-friendly string representation of this X500Principal.

Specified by:
toString in interface Principal
Overrides:
toString in class Object
Returns:
a string representation of this X500Principal

equals

public boolean equals(Object o)
Compares the specified Object with this X500Principal for equality.

Specifically, this method returns true if the Object o is an X500Principal and if the respective canonical string representations (obtained via the getName(X500Principal.CANONICAL) method) of this object and o are equal.

This implementation is compliant with the requirements of RFC 2459.

Specified by:
equals in interface Principal
Overrides:
equals in class Object
Parameters:
o - Object to be compared for equality with this X500Principal
Returns:
true if the specified Object is equal to this X500Principal, false otherwise
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Return a hash code for this X500Principal.

The hash code is calculated via: getName(X500Principal.CANONICAL).hashCode()

Specified by:
hashCode in interface Principal
Overrides:
hashCode in class Object
Returns:
a hash code for this X500Principal
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


X500PrivateCredential

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.security.auth.x500
Class X500PrivateCredential

java.lang.Object
    extended by  javax.security.auth.x500.X500PrivateCredential
All Implemented Interfaces:
Destroyable
public final class X500PrivateCredential
extends Object
implements Destroyable

This class represents an X500PrivateCredential. It associates an X.509 certificate, corresponding private key and the KeyStore alias used to reference that exact key pair in the KeyStore. This enables looking up the private credentials for an X.500 principal in a subject.

Constructor Summary
X500PrivateCredential(X509Certificate cert, PrivateKey key)
Creates an X500PrivateCredential that associates an X.509 certificate, a private key and the KeyStore alias.
X500PrivateCredential(X509Certificate cert, PrivateKey key, String alias)
Creates an X500PrivateCredential that associates an X.509 certificate, a private key and the KeyStore alias.
Method Summary
void | destroy() Clears the references to the X.509 certificate, private key and the KeyStore alias in this object.
String | getAlias() Returns the KeyStore alias.
X509Certificate | getCertificate() Returns the X.509 certificate.
PrivateKey | getPrivateKey() Returns the PrivateKey.
boolean | isDestroyed() Determines if the references to the X.509 certificate and private key in this object have been cleared.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

X500PrivateCredential

public X500PrivateCredential(X509Certificate cert,
                             PrivateKey key)
Creates an X500PrivateCredential that associates an X.509 certificate, a private key and the KeyStore alias.

Parameters:
cert - X509Certificate
key - PrivateKey for the certificate
Throws:
IllegalArgumentException - if either cert or key is null

X500PrivateCredential

public X500PrivateCredential(X509Certificate cert,
                             PrivateKey key,
                             String alias)
Creates an X500PrivateCredential that associates an X.509 certificate, a private key and the KeyStore alias.

Parameters:
cert - X509Certificate
key - PrivateKey for the certificate
alias - KeyStore alias
Throws:
IllegalArgumentException - if either cert, key or alias is null
Method Detail

getCertificate

public X509Certificate getCertificate()
Returns the X.509 certificate.

Returns:
the X509Certificate

getPrivateKey

public PrivateKey getPrivateKey()
Returns the PrivateKey.

Returns:
the PrivateKey

getAlias

public String getAlias()
Returns the KeyStore alias.

Returns:
the KeyStore alias

destroy

public void destroy()
Clears the references to the X.509 certificate, private key and the KeyStore alias in this object.

Specified by:
destroy in interface Destroyable

isDestroyed

public boolean isDestroyed()
Determines if the references to the X.509 certificate and private key in this object have been cleared.

Specified by:
isDestroyed in interface Destroyable
Returns:
true if X509Certificate and the PrivateKey are null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


cert

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.security.cert

Provides classes for public key certificates.

See:
Description

Class Summary
Certificate | Abstract class for managing a variety of identity certificates.
X509Certificate | Abstract class for X.509 v1 certificates.

Exception Summary
CertificateEncodingException | Certificate Encoding Exception.
CertificateException | This exception indicates one of a variety of certificate problems.
CertificateExpiredException | Certificate Expired Exception.
CertificateNotYetValidException | Certificate is not yet valid exception.
CertificateParsingException | Certificate Parsing Exception.

Package javax.security.cert Description

Provides classes for public key certificates.

These classes include a simplified version of the java.security.cert package. These classes were developed as part of the Java Secure Socket Extension (JSSE). When JSSE was added to the J2SE version 1.4, this package was added for backward-compatibility reasons only.

New applications should not use this package, but rather java.security.cert.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.security.cert Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.security.cert

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.security.cert.Certificate
      • javax.security.cert.X509Certificate
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.security.cert.CertificateException
          • javax.security.cert.CertificateEncodingException
          • javax.security.cert.CertificateExpiredException
          • javax.security.cert.CertificateNotYetValidException
          • javax.security.cert.CertificateParsingException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.security.cert

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.security.cert

Packages that use javax.security.cert
javax.net.ssl | Provides classes for the secure socket package.
javax.security.cert | Provides classes for public key certificates.

Classes in javax.security.cert used by javax.net.ssl
X509Certificate
Abstract class for X.509 v1 certificates.

Classes in javax.security.cert used by javax.security.cert
Certificate
Abstract class for managing a variety of identity certificates.
CertificateEncodingException
Certificate Encoding Exception.
CertificateException
This exception indicates one of a variety of certificate problems.
CertificateExpiredException
Certificate Expired Exception.
CertificateNotYetValidException
Certificate is not yet valid exception.
X509Certificate
Abstract class for X.509 v1 certificates.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Certificate

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.security.cert
Class Certificate

java.lang.Object
    extended by  javax.security.cert.Certificate
Direct Known Subclasses:
X509Certificate
public abstract class Certificate
extends Object

Abstract class for managing a variety of identity certificates. An identity certificate is a guarantee by a principal that a public key is that of another principal. (A principal represents an entity such as an individual user, a group, or a corporation.)

This class is an abstraction for certificates that have different formats but important common uses. For example, different types of certificates, such as X.509 and PGP, share general certificate functionality (like encoding and verifying) and some types of information (like a public key).

X.509, PGP, and SDSI certificates can all be implemented by subclassing the Certificate class, even though they contain different sets of information, and they store and retrieve the information in different ways.

Note: The classes in the package javax.security.cert exist for compatibility with earlier versions of the Java Secure Sockets Extension (JSSE). New applications should instead use the standard Java SE certificate classes located in java.security.cert.

Since:
1.4
See Also:
X509Certificate

Constructor Summary
Certificate()
Method Summary
boolean | equals(Object other) Compares this certificate for equality with the specified object.
abstract byte[] | getEncoded() Returns the encoded form of this certificate.
abstract PublicKey | getPublicKey() Gets the public key from this certificate.
int | hashCode() Returns a hashcode value for this certificate from its encoded form.
abstract String | toString() Returns a string representation of this certificate.
abstract void | verify(PublicKey key) Verifies that this certificate was signed using the private key that corresponds to the specified public key.
abstract void | verify(PublicKey key, String sigProvider) Verifies that this certificate was signed using the private key that corresponds to the specified public key.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Certificate

public Certificate()
Method Detail

equals

public boolean equals(Object other)
Compares this certificate for equality with the specified object. If the other object is an instanceof Certificate, then its encoded form is retrieved and compared with the encoded form of this certificate.

Overrides:
equals in class Object
Parameters:
other - the object to test for equality with this certificate.
Returns:
true if the encoded forms of the two certificates match, false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns a hashcode value for this certificate from its encoded form.

Overrides:
hashCode in class Object
Returns:
the hashcode value.
See Also:
Object.equals(java.lang.Object), Hashtable

getEncoded

public abstract byte[] getEncoded()
                           throws CertificateEncodingException
Returns the encoded form of this certificate. It is assumed that each certificate type would have only a single form of encoding; for example, X.509 certificates would be encoded as ASN.1 DER.

Returns:
encoded form of this certificate
Throws:
CertificateEncodingException - on internal certificate encoding failure

verify

public abstract void verify(PublicKey key)
                     throws CertificateException,
                            NoSuchAlgorithmException,
                            InvalidKeyException,
                            NoSuchProviderException,
                            SignatureException
Verifies that this certificate was signed using the private key that corresponds to the specified public key.

Parameters:
key - the PublicKey used to carry out the verification.
Throws:
NoSuchAlgorithmException - on unsupported signature algorithms.
InvalidKeyException - on incorrect key.
NoSuchProviderException - if there's no default provider.
SignatureException - on signature errors.
CertificateException - on encoding errors.

verify

public abstract void verify(PublicKey key,
                            String sigProvider)
                     throws CertificateException,
                            NoSuchAlgorithmException,
                            InvalidKeyException,
                            NoSuchProviderException,
                            SignatureException
Verifies that this certificate was signed using the private key that corresponds to the specified public key. This method uses the signature verification engine supplied by the specified provider.

Parameters:
key - the PublicKey used to carry out the verification.
sigProvider - the name of the signature provider.
Throws:
NoSuchAlgorithmException - on unsupported signature algorithms.
InvalidKeyException - on incorrect key.
NoSuchProviderException - on incorrect provider.
SignatureException - on signature errors.
CertificateException - on encoding errors.

toString

public abstract String toString()
Returns a string representation of this certificate.

Overrides:
toString in class Object
Returns:
a string representation of this certificate.

getPublicKey

public abstract PublicKey getPublicKey()
Gets the public key from this certificate.

Returns:
the public key.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


CertificateEncodingException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.cert
Class CertificateEncodingException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.security.cert.CertificateException
                extended by  javax.security.cert.CertificateEncodingException
All Implemented Interfaces:
Serializable
public class CertificateEncodingException
extends CertificateException

Certificate Encoding Exception. This is thrown whenever an error occurs whilst attempting to encode a certificate.

Note: The classes in the package javax.security.cert exist for compatibility with earlier versions of the Java Secure Sockets Extension (JSSE). New applications should instead use the standard Java SE certificate classes located in java.security.cert.

Since:
1.4
See Also:
Serialized Form

Constructor Summary
CertificateEncodingException()
Constructs a CertificateEncodingException with no detail message.
CertificateEncodingException(String message)
Constructs a CertificateEncodingException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CertificateEncodingException

public CertificateEncodingException()
Constructs a CertificateEncodingException with no detail message. A detail message is a String that describes this particular exception.

CertificateEncodingException

public CertificateEncodingException(String message)
Constructs a CertificateEncodingException with the specified detail message. A detail message is a String that describes this particular exception.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CertificateException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.cert
Class CertificateException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.security.cert.CertificateException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
CertificateEncodingException, CertificateExpiredException, CertificateNotYetValidException, CertificateParsingException
public class CertificateException
extends Exception

This exception indicates one of a variety of certificate problems.

Note: The classes in the package javax.security.cert exist for compatibility with earlier versions of the Java Secure Sockets Extension (JSSE). New applications should instead use the standard Java SE certificate classes located in java.security.cert.

Since:
1.4
See Also:
Certificate, Serialized Form

Constructor Summary
CertificateException()
Constructs a certificate exception with no detail message.
CertificateException(String msg)
Constructs a certificate exception with the given detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CertificateException

public CertificateException()
Constructs a certificate exception with no detail message. A detail message is a String that describes this particular exception.

CertificateException

public CertificateException(String msg)
Constructs a certificate exception with the given detail message. A detail message is a String that describes this particular exception.

Parameters:
msg - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CertificateExpiredException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.cert
Class CertificateExpiredException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.security.cert.CertificateException
                extended by  javax.security.cert.CertificateExpiredException
All Implemented Interfaces:
Serializable
public class CertificateExpiredException
extends CertificateException

Certificate Expired Exception. This is thrown whenever the current Date or the specified Date is after the notAfter date/time specified in the validity period of the certificate.

Note: The classes in the package javax.security.cert exist for compatibility with earlier versions of the Java Secure Sockets Extension (JSSE). New applications should instead use the standard Java SE certificate classes located in java.security.cert.

Since:
1.4
See Also:
Serialized Form

Constructor Summary
CertificateExpiredException()
Constructs a CertificateExpiredException with no detail message.
CertificateExpiredException(String message)
Constructs a CertificateExpiredException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CertificateExpiredException

public CertificateExpiredException()
Constructs a CertificateExpiredException with no detail message. A detail message is a String that describes this particular exception.

CertificateExpiredException

public CertificateExpiredException(String message)
Constructs a CertificateExpiredException with the specified detail message. A detail message is a String that describes this particular exception.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CertificateNotYetValidException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.cert
Class CertificateNotYetValidException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.security.cert.CertificateException
                extended by  javax.security.cert.CertificateNotYetValidException
All Implemented Interfaces:
Serializable
public class CertificateNotYetValidException
extends CertificateException

Certificate is not yet valid exception. This is thrown whenever the current Date or the specified Date is before the notBefore date/time in the Certificate validity period.

Note: The classes in the package javax.security.cert exist for compatibility with earlier versions of the Java Secure Sockets Extension (JSSE). New applications should instead use the standard Java SE certificate classes located in java.security.cert.

Since:
1.4
See Also:
Serialized Form

Constructor Summary
CertificateNotYetValidException()
Constructs a CertificateNotYetValidException with no detail message.
CertificateNotYetValidException(String message)
Constructs a CertificateNotYetValidException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CertificateNotYetValidException

public CertificateNotYetValidException()
Constructs a CertificateNotYetValidException with no detail message. A detail message is a String that describes this particular exception.

CertificateNotYetValidException

public CertificateNotYetValidException(String message)
Constructs a CertificateNotYetValidException with the specified detail message. A detail message is a String that describes this particular exception.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CertificateParsingException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.cert
Class CertificateParsingException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.security.cert.CertificateException
                extended by  javax.security.cert.CertificateParsingException
All Implemented Interfaces:
Serializable
public class CertificateParsingException
extends CertificateException

Certificate Parsing Exception. This is thrown whenever invalid DER encoded certificate is parsed or unsupported DER features are found in the Certificate.

Note: The classes in the package javax.security.cert exist for compatibility with earlier versions of the Java Secure Sockets Extension (JSSE). New applications should instead use the standard Java SE certificate classes located in java.security.cert.

Since:
1.4
See Also:
Serialized Form

Constructor Summary
CertificateParsingException()
Constructs a CertificateParsingException with no detail message.
CertificateParsingException(String message)
Constructs a CertificateParsingException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CertificateParsingException

public CertificateParsingException()
Constructs a CertificateParsingException with no detail message. A detail message is a String that describes this particular exception.

CertificateParsingException

public CertificateParsingException(String message)
Constructs a CertificateParsingException with the specified detail message. A detail message is a String that describes this particular exception.

Parameters:
message - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.security.cert.Certificate

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.cert.Certificate

Packages that use Certificate
javax.security.cert Provides classes for public key certificates.

Uses of Certificate in javax.security.cert

Subclasses of Certificate in javax.security.cert
 class X509Certificate
Abstract class for X.509 v1 certificates.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.cert.CertificateEncodingException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.cert.CertificateEncodingException

Packages that use CertificateEncodingException
javax.security.cert Provides classes for public key certificates.

Uses of CertificateEncodingException in javax.security.cert

Methods in javax.security.cert that throw CertificateEncodingException
abstract  byte[] Certificate.getEncoded()
Returns the encoded form of this certificate.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.cert.CertificateException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.cert.CertificateException

Packages that use CertificateException
javax.security.cert Provides classes for public key certificates.

Uses of CertificateException in javax.security.cert

Subclasses of CertificateException in javax.security.cert
class | CertificateEncodingException Certificate Encoding Exception.
class | CertificateExpiredException Certificate Expired Exception.
class | CertificateNotYetValidException Certificate is not yet valid exception.
class | CertificateParsingException Certificate Parsing Exception.

Methods in javax.security.cert that throw CertificateException
static X509Certificate | X509Certificate.getInstance(byte[] certData) Instantiates an X509Certificate object, and initializes it with the specified byte array.
static X509Certificate | X509Certificate.getInstance(InputStream inStream) Instantiates an X509Certificate object, and initializes it with the data read from the input stream inStream.
abstract void | Certificate.verify(PublicKey key) Verifies that this certificate was signed using the private key that corresponds to the specified public key.
abstract void | Certificate.verify(PublicKey key, String sigProvider) Verifies that this certificate was signed using the private key that corresponds to the specified public key.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.cert.CertificateExpiredException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.cert.CertificateExpiredException

Packages that use CertificateExpiredException
javax.security.cert Provides classes for public key certificates.

Uses of CertificateExpiredException in javax.security.cert

Methods in javax.security.cert that throw CertificateExpiredException
abstract void | X509Certificate.checkValidity() Checks that the certificate is currently valid.
abstract void | X509Certificate.checkValidity(Date date) Checks that the specified date is within the certificate's validity period.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.cert.CertificateNotYetValidException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.cert.CertificateNotYetValidException

Packages that use CertificateNotYetValidException
javax.security.cert Provides classes for public key certificates.

Uses of CertificateNotYetValidException in javax.security.cert

Methods in javax.security.cert that throw CertificateNotYetValidException
abstract void | X509Certificate.checkValidity() Checks that the certificate is currently valid.
abstract void | X509Certificate.checkValidity(Date date) Checks that the specified date is within the certificate's validity period.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.cert.CertificateParsingException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.cert.CertificateParsingException

No usage of javax.security.cert.CertificateParsingException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.cert.X509Certificate

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.cert.X509Certificate

Packages that use X509Certificate
javax.net.ssl | Provides classes for the secure socket package.
javax.security.cert | Provides classes for public key certificates.

Uses of X509Certificate in javax.net.ssl

Methods in javax.net.ssl that return X509Certificate
X509Certificate[] | HandshakeCompletedEvent.getPeerCertificateChain() Returns the identity of the peer which was identified as part of defining the session.
X509Certificate[] | SSLSession.getPeerCertificateChain() Returns the identity of the peer which was identified as part of defining the session.

Uses of X509Certificate in javax.security.cert

Methods in javax.security.cert that return X509Certificate
static X509Certificate | X509Certificate.getInstance(byte[] certData) Instantiates an X509Certificate object, and initializes it with the specified byte array.
static X509Certificate | X509Certificate.getInstance(InputStream inStream) Instantiates an X509Certificate object, and initializes it with the data read from the input stream inStream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


X509Certificate

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.security.cert
Class X509Certificate

java.lang.Object
    extended by  javax.security.cert.Certificate
        extended by  javax.security.cert.X509Certificate

public abstract class X509Certificate
extends Certificate

Abstract class for X.509 v1 certificates. This provides a standard way to access all the version 1 attributes of an X.509 certificate. Attributes that are specific to X.509 v2 or v3 are not available through this interface. Future API evolution will provide full access to complete X.509 v3 attributes.

The basic X.509 format was defined by ISO/IEC and ANSI X9 and is described below in ASN.1:

 Certificate  ::=  SEQUENCE  {
     tbsCertificate       TBSCertificate,
     signatureAlgorithm   AlgorithmIdentifier,
     signature            BIT STRING  }

These certificates are widely used to support authentication and other functionality in Internet security systems. Common applications include Privacy Enhanced Mail (PEM), Transport Layer Security (SSL), code signing for trusted software distribution, and Secure Electronic Transactions (SET).

These certificates are managed and vouched for by Certificate Authorities (CAs). CAs are services which create certificates by placing data in the X.509 standard format and then digitally signing that data. CAs act as trusted third parties, making introductions between principals who have no direct knowledge of each other. CA certificates are either signed by themselves, or by some other CA such as a "root" CA.

The ASN.1 definition of tbsCertificate is:

 TBSCertificate  ::=  SEQUENCE  {
     version         [0]  EXPLICIT Version DEFAULT v1,
     serialNumber         CertificateSerialNumber,
     signature            AlgorithmIdentifier,
     issuer               Name,
     validity             Validity,
     subject              Name,
     subjectPublicKeyInfo SubjectPublicKeyInfo,
     }

Here is sample code to instantiate an X.509 certificate:

 InputStream inStream = new FileInputStream("fileName-of-cert");
 X509Certificate cert = X509Certificate.getInstance(inStream);
 inStream.close();
OR
 byte[] certData = <certificate read from a file, say>
 X509Certificate cert = X509Certificate.getInstance(certData);

In either case, the code that instantiates an X.509 certificate consults the Java security properties file to locate the actual implementation or instantiates a default implementation.

The Java security properties file is located in the file named <JAVA_HOME>/lib/security/java.security. <JAVA_HOME> refers to the value of the java.home system property, and specifies the directory where the JRE is installed. In the Security properties file, a default implementation for X.509 v1 may be given such as:

 cert.provider.x509v1=com.sun.security.cert.internal.x509.X509V1CertImpl

The value of this cert.provider.x509v1 property has to be changed to instatiate another implementation. If this security property is not set, a default implementation will be used. Currently, due to possible security restrictions on access to Security properties, this value is looked up and cached at class initialization time and will fallback on a default implementation if the Security property is not accessible.

Note: The classes in the package javax.security.cert exist for compatibility with earlier versions of the Java Secure Sockets Extension (JSSE). New applications should instead use the standard Java SE certificate classes located in java.security.cert.

Since:
1.4
See Also:
Certificate, X509Extension

Constructor Summary
X509Certificate()
Method Summary
abstract void | checkValidity() Checks that the certificate is currently valid.
abstract void | checkValidity(Date date) Checks that the specified date is within the certificate's validity period.
static X509Certificate | getInstance(byte[] certData) Instantiates an X509Certificate object, and initializes it with the specified byte array.
static X509Certificate | getInstance(InputStream inStream) Instantiates an X509Certificate object, and initializes it with the data read from the input stream inStream.
abstract Principal | getIssuerDN() Gets the issuer (issuer distinguished name) value from the certificate.
abstract Date | getNotAfter() Gets the notAfter date from the validity period of the certificate.
abstract Date | getNotBefore() Gets the notBefore date from the validity period of the certificate.
abstract BigInteger | getSerialNumber() Gets the serialNumber value from the certificate.
abstract String | getSigAlgName() Gets the signature algorithm name for the certificate signature algorithm.
abstract String | getSigAlgOID() Gets the signature algorithm OID string from the certificate.
abstract byte[] | getSigAlgParams() Gets the DER-encoded signature algorithm parameters from this certificate's signature algorithm.
abstract Principal | getSubjectDN() Gets the subject (subject distinguished name) value from the certificate.
abstract int | getVersion() Gets the version (version number) value from the certificate.
Methods inherited from class javax.security.cert.Certificate
equals, getEncoded, getPublicKey, hashCode, toString, verify, verify
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

X509Certificate

public X509Certificate()
Method Detail

getInstance

public static final X509Certificate getInstance(InputStream inStream)
                                         throws CertificateException
Instantiates an X509Certificate object, and initializes it with the data read from the input stream inStream. The implementation (X509Certificate is an abstract class) is provided by the class specified as the value of the cert.provider.x509v1 property in the security properties file.

Note: Only one DER-encoded certificate is expected to be in the input stream. Also, all X509Certificate subclasses must provide a constructor of the form:

 public <subClass>(InputStream inStream) ...

Parameters:
inStream - an input stream with the data to be read to initialize the certificate.
Returns:
an X509Certificate object initialized with the data from the input stream.
Throws:
CertificateException - if a class initialization or certificate parsing error occurs.

getInstance

public static final X509Certificate getInstance(byte[] certData)
                                         throws CertificateException
Instantiates an X509Certificate object, and initializes it with the specified byte array. The implementation (X509Certificate is an abstract class) is provided by the class specified as the value of the cert.provider.x509v1 property in the security properties file.

Note: All X509Certificate subclasses must provide a constructor of the form:

 public <subClass>(InputStream inStream) ...

Parameters:
certData - a byte array containing the DER-encoded certificate.
Returns:
an X509Certificate object initialized with the data from certData.
Throws:
CertificateException - if a class initialization or certificate parsing error occurs.

checkValidity

public abstract void checkValidity()
                            throws CertificateExpiredException,
                                   CertificateNotYetValidException
Checks that the certificate is currently valid. It is if the current date and time are within the validity period given in the certificate.

The validity period consists of two date/time values: the first and last dates (and times) on which the certificate is valid. It is defined in ASN.1 as:

 validity             Validity

 Validity ::= SEQUENCE {
     notBefore      CertificateValidityDate,
     notAfter       CertificateValidityDate }

 CertificateValidityDate ::= CHOICE {
     utcTime        UTCTime,
     generalTime    GeneralizedTime }

Throws:
CertificateExpiredException - if the certificate has expired.
CertificateNotYetValidException - if the certificate is not yet valid.

checkValidity

public abstract void checkValidity(Date date)
                            throws CertificateExpiredException,
                                   CertificateNotYetValidException
Checks that the specified date is within the certificate's validity period. In other words, this determines whether the certificate would be valid at the specified date/time.

Parameters:
date - the Date to check against to see if this certificate is valid at that date/time.
Throws:
CertificateExpiredException - if the certificate has expired with respect to the date supplied.
CertificateNotYetValidException - if the certificate is not yet valid with respect to the date supplied.
See Also:
checkValidity()

getVersion

public abstract int getVersion()
Gets the version (version number) value from the certificate. The ASN.1 definition for this is:
 version         [0]  EXPLICIT Version DEFAULT v1

 Version  ::=  INTEGER  {  v1(0), v2(1), v3(2)  }

Returns:
the version number from the ASN.1 encoding, i.e. 0, 1 or 2.

getSerialNumber

public abstract BigInteger getSerialNumber()
Gets the serialNumber value from the certificate. The serial number is an integer assigned by the certification authority to each certificate. It must be unique for each certificate issued by a given CA (i.e., the issuer name and serial number identify a unique certificate). The ASN.1 definition for this is:
 serialNumber     CertificateSerialNumber

 CertificateSerialNumber  ::=  INTEGER

Returns:
the serial number.

getIssuerDN

public abstract Principal getIssuerDN()
Gets the issuer (issuer distinguished name) value from the certificate. The issuer name identifies the entity that signed (and issued) the certificate.

The issuer name field contains an X.500 distinguished name (DN). The ASN.1 definition for this is:

 issuer    Name

 Name ::= CHOICE { RDNSequence }
 RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
 RelativeDistinguishedName ::=
     SET OF AttributeValueAssertion

 AttributeValueAssertion ::= SEQUENCE {
                               AttributeType,
                               AttributeValue }
 AttributeType ::= OBJECT IDENTIFIER
 AttributeValue ::= ANY
The Name describes a hierarchical name composed of attributes, such as country name, and corresponding values, such as US. The type of the AttributeValue component is determined by the AttributeType; in general it will be a directoryString. A directoryString is usually one of PrintableString, TeletexString or UniversalString.

Returns:
a Principal whose name is the issuer distinguished name.

getSubjectDN

public abstract Principal getSubjectDN()
Gets the subject (subject distinguished name) value from the certificate. The ASN.1 definition for this is:
 subject    Name

See getIssuerDN for Name and other relevant definitions.

Returns:
a Principal whose name is the subject name.
See Also:
getIssuerDN()

getNotBefore

public abstract Date getNotBefore()
Gets the notBefore date from the validity period of the certificate. The relevant ASN.1 definitions are:
 validity             Validity

 Validity ::= SEQUENCE {
     notBefore      CertificateValidityDate,
     notAfter       CertificateValidityDate }

 CertificateValidityDate ::= CHOICE {
     utcTime        UTCTime,
     generalTime    GeneralizedTime }

Returns:
the start date of the validity period.
See Also:
checkValidity()

getNotAfter

public abstract Date getNotAfter()
Gets the notAfter date from the validity period of the certificate. See getNotBefore for relevant ASN.1 definitions.

Returns:
the end date of the validity period.
See Also:
checkValidity()

getSigAlgName

public abstract String getSigAlgName()
Gets the signature algorithm name for the certificate signature algorithm. An example is the string "SHA-1/DSA". The ASN.1 definition for this is:
 signatureAlgorithm   AlgorithmIdentifier

 AlgorithmIdentifier  ::=  SEQUENCE  {
     algorithm               OBJECT IDENTIFIER,
     parameters              ANY DEFINED BY algorithm OPTIONAL  }
                             -- contains a value of the type
                             -- registered for use with the
                             -- algorithm object identifier value

The algorithm name is determined from the algorithm OID string.

Returns:
the signature algorithm name.

getSigAlgOID

public abstract String getSigAlgOID()
Gets the signature algorithm OID string from the certificate. An OID is represented by a set of positive whole numbers separated by periods. For example, the string "1.2.840.10040.4.3" identifies the SHA-1 with DSA signature algorithm, as per the PKIX part I.

See getSigAlgName for relevant ASN.1 definitions.

Returns:
the signature algorithm OID string.

getSigAlgParams

public abstract byte[] getSigAlgParams()
Gets the DER-encoded signature algorithm parameters from this certificate's signature algorithm. In most cases, the signature algorithm parameters are null; the parameters are usually supplied with the certificate's public key.

See getSigAlgName for relevant ASN.1 definitions.

Returns:
the DER-encoded signature algorithm parameters, or null if no parameters are present.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


sasl

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.security.sasl

Contains class and interfaces for supporting SASL.

See:
Description

Interface Summary
SaslClient | Performs SASL authentication as a client.
SaslClientFactory | An interface for creating instances of SaslClient.
SaslServer | Performs SASL authentication as a server.
SaslServerFactory | An interface for creating instances of SaslServer.

Class Summary
AuthorizeCallback | This callback is used by SaslServer to determine whether one entity (identified by an authenticated authentication id) can act on behalf of another entity (identified by an authorization id).
RealmCallback | This callback is used by SaslClient and SaslServer to retrieve realm information.
RealmChoiceCallback | This callback is used by SaslClient and SaslServer to obtain a realm given a list of realm choices.
Sasl | A static class for creating SASL clients and servers.

Exception Summary
AuthenticationException | This exception is thrown by a SASL mechanism implementation to indicate that the SASL exchange has failed due to reasons related to authentication, such as an invalid identity, passphrase, or key.
SaslException | This class represents an error that has occurred when using SASL.

Package javax.security.sasl Description

Contains class and interfaces for supporting SASL. This package defines classes and interfaces for SASL mechanisms. It is used by developers to add authentication support for connection-based protocols that use SASL.

SASL Overview

Simple Authentication and Security Layer (SASL) specifies a challenge-response protocol in which data is exchanged between the client and the server for the purposes of authentication and (optional) establishment of a security layer on which to carry on subsequent communications. It is used with connection-based protocols such as LDAPv3 or IMAPv4. SASL is described in RFC 2222.

There are various mechanisms defined for SASL. Each mechanism defines the data that must be exchanged between the client and server in order for the authentication to succeed. This data exchange required for a particular mechanism is referred to to as its protocol profile. The following are some examples of mechanims that have been defined by the Internet standards community.

  • DIGEST-MD5 (RFC 2831). This mechanism defines how HTTP Digest Authentication can be used as a SASL mechanism.
  • Anonymous (RFC 2245). This mechamism is anonymous authentication in which no credentials are necessary.
  • External (RFC 2222). This mechanism obtains authentication information from an external source (such as TLS or IPsec).
  • S/Key (RFC 2222). This mechanism uses the MD4 digest algorithm to exchange data based on a shared secret.
  • GSSAPI (RFC 2222). This mechanism uses the GSSAPI for obtaining authentication information.

Some of these mechanisms provide both authentication and establishment of a security layer, others only authentication. Anonymous and S/Key do not provide for any security layers. GSSAPI and DIGEST-MD5 allow negotiation of the security layer. For External, the security layer is determined by the external protocol.

Usage

Users of this API are typically developers who produce client library implementations for connection-based protocols, such as LDAPv3 and IMAPv4, and developers who write servers (such as LDAP servers and IMAP servers). Developers who write client libraries use the SaslClient and SaslClientFactory interfaces. Developers who write servers use the SaslServer and SaslServerFactory interfaces.

Among these two groups of users, each can be further divided into two groups: those who produce the SASL mechanisms and those who use the SASL mechanisms. The producers of SASL mechanisms need to provide implementations for these interfaces, while users of the SASL mechanisms use the APIs in this package to access those implementations.

Related Documentation

Please refer to the Java SASL Programming Guide for information on how to use this API.

Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.security.sasl Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.security.sasl

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.security.sasl.AuthorizeCallback (implements javax.security.auth.callback.Callback, java.io.Serializable)
    • javax.security.auth.callback.ChoiceCallback (implements javax.security.auth.callback.Callback, java.io.Serializable)
      • javax.security.sasl.RealmChoiceCallback
    • javax.security.sasl.Sasl
    • javax.security.auth.callback.TextInputCallback (implements javax.security.auth.callback.Callback, java.io.Serializable)
      • javax.security.sasl.RealmCallback
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.io.IOException
          • javax.security.sasl.SaslException
            • javax.security.sasl.AuthenticationException

Interface Hierarchy

  • javax.security.sasl.SaslClient
  • javax.security.sasl.SaslClientFactory
  • javax.security.sasl.SaslServer
  • javax.security.sasl.SaslServerFactory
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.security.sasl

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.security.sasl

Packages that use javax.security.sasl
javax.security.sasl Contains class and interfaces for supporting SASL.

Classes in javax.security.sasl used by javax.security.sasl
SaslClient
Performs SASL authentication as a client.
SaslClientFactory
An interface for creating instances of SaslClient.
SaslException
This class represents an error that has occurred when using SASL.
SaslServer
Performs SASL authentication as a server.
SaslServerFactory
An interface for creating instances of SaslServer.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AuthenticationException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.security.sasl
Class AuthenticationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.io.IOException
                extended by  javax.security.sasl.SaslException
                    extended by  javax.security.sasl.AuthenticationException
All Implemented Interfaces:
Serializable
public class AuthenticationException
extends SaslException

This exception is thrown by a SASL mechanism implementation to indicate that the SASL exchange has failed due to reasons related to authentication, such as an invalid identity, passphrase, or key.

Note that the lack of an AuthenticationException does not mean that the failure was not due to an authentication error. A SASL mechanism implementation might throw the more general SaslException instead of AuthenticationException if it is unable to determine the nature of the failure, or if does not want to disclose the nature of the failure, for example, due to security reasons.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
AuthenticationException()
Constructs a new instance of AuthenticationException.
AuthenticationException(String detail)
Constructs a new instance of AuthenticationException with a detailed message.
AuthenticationException(String detail, Throwable ex)
Constructs a new instance of AuthenticationException with a detailed message and a root exception.
Method Summary
Methods inherited from class javax.security.sasl.SaslException
getCause, initCause, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AuthenticationException

public AuthenticationException()
Constructs a new instance of AuthenticationException. The root exception and the detailed message are null.

AuthenticationException

public AuthenticationException(String detail)
Constructs a new instance of AuthenticationException with a detailed message. The root exception is null.

Parameters:
detail - A possibly null string containing details of the exception.
See Also:
Throwable.getMessage()

AuthenticationException

public AuthenticationException(String detail,
                               Throwable ex)
Constructs a new instance of AuthenticationException with a detailed message and a root exception.

Parameters:
detail - A possibly null string containing details of the exception.
ex - A possibly null root exception that caused this exception.
See Also:
Throwable.getMessage(), SaslException.getCause()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AuthorizeCallback

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.sasl
Class AuthorizeCallback

java.lang.Object
    extended by  javax.security.sasl.AuthorizeCallback
All Implemented Interfaces:
Serializable, Callback
public class AuthorizeCallback
extends Object
implements Callback, Serializable

This callback is used by SaslServer to determine whether one entity (identified by an authenticated authentication id) can act on behalf of another entity (identified by an authorization id).

Since:
1.5
See Also:
Serialized Form

Constructor Summary
AuthorizeCallback(String authnID, String authzID)
Constructs an instance of AuthorizeCallback.
Method Summary
String | getAuthenticationID() Returns the authentication id to check.
String | getAuthorizationID() Returns the authorization id to check.
String | getAuthorizedID() Returns the id of the authorized user.
boolean | isAuthorized() Determines whether the authentication id is allowed to act on behalf of the authorization id.
void | setAuthorized(boolean ok) Sets whether the authorization is allowed.
void | setAuthorizedID(String id) Sets the id of the authorized entity.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AuthorizeCallback

public AuthorizeCallback(String authnID,
                         String authzID)
Constructs an instance of AuthorizeCallback.

Parameters:
authnID - The (authenticated) authentication id.
authzID - The authorization id.
Method Detail

getAuthenticationID

public String getAuthenticationID()
Returns the authentication id to check.

Returns:
The authentication id to check.

getAuthorizationID

public String getAuthorizationID()
Returns the authorization id to check.

Returns:
The authentication id to check.

isAuthorized

public boolean isAuthorized()
Determines whether the authentication id is allowed to act on behalf of the authorization id.

Returns:
true if authorization is allowed; false otherwise
See Also:
setAuthorized(boolean), getAuthorizedID()

setAuthorized

public void setAuthorized(boolean ok)
Sets whether the authorization is allowed.

Parameters:
ok - true if authorization is allowed; false otherwise
See Also:
isAuthorized(), setAuthorizedID(java.lang.String)

getAuthorizedID

public String getAuthorizedID()
Returns the id of the authorized user.

Returns:
The id of the authorized user. null means the authorization failed.
See Also:
setAuthorized(boolean), setAuthorizedID(java.lang.String)

setAuthorizedID

public void setAuthorizedID(String id)
Sets the id of the authorized entity. Called by handler only when the id is different from getAuthorizationID(). For example, the id might need to be canonicalized for the environment in which it will be used.

Parameters:
id - The id of the authorized user.
See Also:
setAuthorized(boolean), getAuthorizedID()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.security.sasl.AuthenticationException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.sasl.AuthenticationException

No usage of javax.security.sasl.AuthenticationException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.sasl.AuthorizeCallback

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.sasl.AuthorizeCallback

No usage of javax.security.sasl.AuthorizeCallback

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.sasl.RealmCallback

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.sasl.RealmCallback

No usage of javax.security.sasl.RealmCallback

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.sasl.RealmChoiceCallback

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.sasl.RealmChoiceCallback

No usage of javax.security.sasl.RealmChoiceCallback

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.sasl.Sasl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.sasl.Sasl

No usage of javax.security.sasl.Sasl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.security.sasl.SaslException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.security.sasl.SaslException

Packages that use SaslException
javax.security.sasl Contains class and interfaces for supporting SASL.

Uses of SaslException in javax.security.sasl

Subclasses of SaslException in javax.security.sasl
 class AuthenticationException
This exception is thrown by a SASL mechanism implementation to indicate that the SASL exchange has failed due to reasons related to authentication, such as an invalid identity, passphrase, or key.

Methods in javax.security.sasl that throw SaslException
SaslClient | SaslClientFactory.createSaslClient(String[] mechanisms, String authorizationId, String protocol, String serverName, Map<String,?> props, CallbackHandler cbh) Creates a SaslClient using the parameters supplied.
static SaslClient | Sasl.createSaslClient(String[] mechanisms, String authorizationId, String protocol, String serverName, Map<String,?> props, CallbackHandler cbh) Creates a SaslClient using the parameters supplied.
SaslServer | SaslServerFactory.createSaslServer(String mechanism, String protocol, String serverName, Map<String,?> props, CallbackHandler cbh) Creates a SaslServer using the parameters supplied.
static SaslServer | Sasl.createSaslServer(String mechanism, String protocol, String serverName, Map<String,?> props, CallbackHandler cbh) Creates a SaslServer for the specified mechanism.
void | SaslServer.dispose() Disposes of any system resources or security-sensitive information the SaslServer might be using.
void | SaslClient.dispose() Disposes of any system resources or security-sensitive information the SaslClient might be using.
byte[] | SaslClient.evaluateChallenge(byte[] challenge) Evaluates the challenge data and generates a response.
byte[] | SaslServer.evaluateResponse(byte[] response) Evaluates the response data and generates a challenge.
byte[] | SaslServer.unwrap(byte[] incoming, int offset, int len) Unwraps a byte array received from the client.
byte[] | SaslClient.unwrap(byte[] incoming, int offset, int len) Unwraps a byte array received from the server.
byte[] | SaslServer.wrap(byte[] outgoing, int offset, int len) Wraps a byte array to be sent to the client.
byte[] | SaslClient.wrap(byte[] outgoing, int offset, int len) Wraps a byte array to be sent to the server.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.security.sasl.SaslClient

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.security.sasl.SaslClient

Packages that use SaslClient
javax.security.sasl Contains class and interfaces for supporting SASL.

Uses of SaslClient in javax.security.sasl

Methods in javax.security.sasl that return SaslClient
SaslClient | SaslClientFactory.createSaslClient(String[] mechanisms, String authorizationId, String protocol, String serverName, Map<String,?> props, CallbackHandler cbh) Creates a SaslClient using the parameters supplied.
static SaslClient | Sasl.createSaslClient(String[] mechanisms, String authorizationId, String protocol, String serverName, Map<String,?> props, CallbackHandler cbh) Creates a SaslClient using the parameters supplied.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.security.sasl.SaslClientFactory

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.security.sasl.SaslClientFactory

Packages that use SaslClientFactory
javax.security.sasl Contains class and interfaces for supporting SASL.

Uses of SaslClientFactory in javax.security.sasl

Methods in javax.security.sasl that return types with arguments of type SaslClientFactory
static Enumeration<SaslClientFactory> Sasl.getSaslClientFactories()
Gets an enumeration of known factories for producing SaslClient.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.security.sasl.SaslServer

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.security.sasl.SaslServer

Packages that use SaslServer
javax.security.sasl Contains class and interfaces for supporting SASL.

Uses of SaslServer in javax.security.sasl

Methods in javax.security.sasl that return SaslServer
SaslServer | SaslServerFactory.createSaslServer(String mechanism, String protocol, String serverName, Map<String,?> props, CallbackHandler cbh) Creates a SaslServer using the parameters supplied.
static SaslServer | Sasl.createSaslServer(String mechanism, String protocol, String serverName, Map<String,?> props, CallbackHandler cbh) Creates a SaslServer for the specified mechanism.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.security.sasl.SaslServerFactory

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.security.sasl.SaslServerFactory

Packages that use SaslServerFactory
javax.security.sasl Contains class and interfaces for supporting SASL.

Uses of SaslServerFactory in javax.security.sasl

Methods in javax.security.sasl that return types with arguments of type SaslServerFactory
static Enumeration<SaslServerFactory> Sasl.getSaslServerFactories()
Gets an enumeration of known factories for producing SaslServer.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


RealmCallback

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.sasl
Class RealmCallback

java.lang.Object
    extended by  javax.security.auth.callback.TextInputCallback
        extended by  javax.security.sasl.RealmCallback
All Implemented Interfaces:
Serializable, Callback
public class RealmCallback
extends TextInputCallback

This callback is used by SaslClient and SaslServer to retrieve realm information.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
RealmCallback(String prompt)
Constructs a RealmCallback with a prompt.
RealmCallback(String prompt, String defaultRealmInfo)
Constructs a RealmCallback with a prompt and default realm information.
Method Summary
Methods inherited from class javax.security.auth.callback.TextInputCallback
getDefaultText, getPrompt, getText, setText
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RealmCallback

public RealmCallback(String prompt)
Constructs a RealmCallback with a prompt.

Parameters:
prompt - The non-null prompt to use to request the realm information.
Throws:
IllegalArgumentException - If prompt is null or the empty string.

RealmCallback

public RealmCallback(String prompt,
                     String defaultRealmInfo)
Constructs a RealmCallback with a prompt and default realm information.

Parameters:
prompt - The non-null prompt to use to request the realm information.
defaultRealmInfo - The non-null default realm information to use.
Throws:
IllegalArgumentException - If prompt is null or the empty string, or if defaultRealm is empty or null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RealmChoiceCallback

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.sasl
Class RealmChoiceCallback

java.lang.Object
    extended by  javax.security.auth.callback.ChoiceCallback
        extended by  javax.security.sasl.RealmChoiceCallback
All Implemented Interfaces:
Serializable, Callback
public class RealmChoiceCallback
extends ChoiceCallback

This callback is used by SaslClient and SaslServer to obtain a realm given a list of realm choices.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
RealmChoiceCallback(String prompt, String[] choices, int defaultChoice, boolean multiple)
Constructs a RealmChoiceCallback with a prompt, a list of choices and a default choice.
Method Summary
Methods inherited from class javax.security.auth.callback.ChoiceCallback
allowMultipleSelections, getChoices, getDefaultChoice, getPrompt, getSelectedIndexes, setSelectedIndex, setSelectedIndexes
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RealmChoiceCallback

public RealmChoiceCallback(String prompt,
                           String[] choices,
                           int defaultChoice,
                           boolean multiple)
Constructs a RealmChoiceCallback with a prompt, a list of choices and a default choice.

Parameters:
prompt - the non-null prompt to use to request the realm.
choices - the non-null list of realms to choose from.
defaultChoice - the choice to be used as the default choice when the list of choices is displayed. It is an index into the choices arary.
multiple - true if multiple choices allowed; false otherwise
Throws:
IllegalArgumentException - If prompt is null or the empty string, if choices has a length of 0, if any element from choices is null or empty, or if defaultChoice does not fall within the array boundary of choices
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Sasl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.sasl
Class Sasl

java.lang.Object
    extended by  javax.security.sasl.Sasl

public class Sasl
extends Object

A static class for creating SASL clients and servers.

This class defines the policy of how to locate, load, and instantiate SASL clients and servers.

For example, an application or library gets a SASL client by doing something like:

 SaslClient sc = Sasl.createSaslClient(mechanisms,
     authorizationId, protocol, serverName, props, callbackHandler);
It can then proceed to use the instance to create an authentication connection.

Similarly, a server gets a SASL server by using code that looks as follows:

 SaslServer ss = Sasl.createSaslServer(mechanism,
     protocol, serverName, props, callbackHandler);

Since:
1.5

Field Summary
static String | CREDENTIALS The name of a property that specifies the credentials to use.
static String | MAX_BUFFER The name of a property that specifies the maximum size of the receive buffer in bytes of SaslClient/SaslServer.
static String | POLICY_FORWARD_SECRECY The name of a property that specifies whether mechanisms that implement forward secrecy between sessions are required.
static String | POLICY_NOACTIVE The name of a property that specifies whether mechanisms susceptible to active (non-dictionary) attacks are not permitted.
static String | POLICY_NOANONYMOUS The name of a property that specifies whether mechanisms that accept anonymous login are not permitted.
static String | POLICY_NODICTIONARY The name of a property that specifies whether mechanisms susceptible to passive dictionary attacks are not permitted.
static String | POLICY_NOPLAINTEXT The name of a property that specifies whether mechanisms susceptible to simple plain passive attacks (e.g., "PLAIN") are not permitted.
static String | POLICY_PASS_CREDENTIALS The name of a property that specifies whether mechanisms that pass client credentials are required.
static String | QOP The name of a property that specifies the quality-of-protection to use.
static String | RAW_SEND_SIZE The name of a property that specifies the maximum size of the raw send buffer in bytes of SaslClient/SaslServer.
static String | REUSE The name of a property that specifies whether to reuse previously authenticated session information.
static String | SERVER_AUTH The name of a property that specifies whether the server must authenticate to the client.
static String | STRENGTH The name of a property that specifies the cipher strength to use.
Method Summary
static SaslClient | createSaslClient(String[] mechanisms, String authorizationId, String protocol, String serverName, Map<String,?> props, CallbackHandler cbh) Creates a SaslClient using the parameters supplied.
static SaslServer | createSaslServer(String mechanism, String protocol, String serverName, Map<String,?> props, CallbackHandler cbh) Creates a SaslServer for the specified mechanism.
static Enumeration<SaslClientFactory> | getSaslClientFactories() Gets an enumeration of known factories for producing SaslClient.
static Enumeration<SaslServerFactory> | getSaslServerFactories() Gets an enumeration of known factories for producing SaslServer.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

QOP

public static final String QOP
The name of a property that specifies the quality-of-protection to use. The property contains a comma-separated, ordered list of quality-of-protection values that the client or server is willing to support. A qop value is one of
  • "auth" - authentication only
  • "auth-int" - authentication plus integrity protection
  • "auth-conf" - authentication plus integrity and confidentiality protection
The order of the list specifies the preference order of the client or server. If this property is absent, the default qop is "auth". The value of this constant is "javax.security.sasl.qop".

See Also:
Constant Field Values

STRENGTH

public static final String STRENGTH
The name of a property that specifies the cipher strength to use. The property contains a comma-separated, ordered list of cipher strength values that the client or server is willing to support. A strength value is one of
  • "low"
  • "medium"
  • "high"
The order of the list specifies the preference order of the client or server. An implementation should allow configuration of the meaning of these values. An application may use the Java Cryptography Extension (JCE) with JCE-aware mechanisms to control the selection of cipher suites that match the strength values.
If this property is absent, the default strength is "high,medium,low". The value of this constant is "javax.security.sasl.strength".

See Also:
Constant Field Values

SERVER_AUTH

public static final String SERVER_AUTH
The name of a property that specifies whether the server must authenticate to the client. The property contains "true" if the server must authenticate the to client; "false" otherwise. The default is "false".
The value of this constant is "javax.security.sasl.server.authentication".

See Also:
Constant Field Values

MAX_BUFFER

public static final String MAX_BUFFER
The name of a property that specifies the maximum size of the receive buffer in bytes of SaslClient/SaslServer. The property contains the string representation of an integer.
If this property is absent, the default size is defined by the mechanism.
The value of this constant is "javax.security.sasl.maxbuffer".

See Also:
Constant Field Values

RAW_SEND_SIZE

public static final String RAW_SEND_SIZE
The name of a property that specifies the maximum size of the raw send buffer in bytes of SaslClient/SaslServer. The property contains the string representation of an integer. The value of this property is negotiated between the client and server during the authentication exchange.
The value of this constant is "javax.security.sasl.rawsendsize".

See Also:
Constant Field Values

REUSE

public static final String REUSE
The name of a property that specifies whether to reuse previously authenticated session information. The property contains "true" if the mechanism implementation may attempt to reuse previously authenticated session information; it contains "false" if the implementation must not reuse previously authenticated session information. A setting of "true" serves only as a hint: it does not necessarily entail actual reuse because reuse might not be possible due to a number of reasons, including, but not limited to, lack of mechanism support for reuse, expiration of reusable information, and the peer's refusal to support reuse. The property's default value is "false". The value of this constant is "javax.security.sasl.reuse". Note that all other parameters and properties required to create a SASL client/server instance must be provided regardless of whether this property has been supplied. That is, you cannot supply any less information in anticipation of reuse. Mechanism implementations that support reuse might allow customization of its implementation, for factors such as cache size, timeouts, and criteria for reuseability. Such customizations are implementation-dependent.

See Also:
Constant Field Values

POLICY_NOPLAINTEXT

public static final String POLICY_NOPLAINTEXT
The name of a property that specifies whether mechanisms susceptible to simple plain passive attacks (e.g., "PLAIN") are not permitted. The property contains "true" if such mechanisms are not permitted; "false" if such mechanisms are permitted. The default is "false".
The value of this constant is "javax.security.sasl.policy.noplaintext".

See Also:
Constant Field Values

POLICY_NOACTIVE

public static final String POLICY_NOACTIVE
The name of a property that specifies whether mechanisms susceptible to active (non-dictionary) attacks are not permitted. The property contains "true" if mechanisms susceptible to active attacks are not permitted; "false" if such mechanisms are permitted. The default is "false".
The value of this constant is "javax.security.sasl.policy.noactive".

See Also:
Constant Field Values

POLICY_NODICTIONARY

public static final String POLICY_NODICTIONARY
The name of a property that specifies whether mechanisms susceptible to passive dictionary attacks are not permitted. The property contains "true" if mechanisms susceptible to dictionary attacks are not permitted; "false" if such mechanisms are permitted. The default is "false".
The value of this constant is "javax.security.sasl.policy.nodictionary".

See Also:
Constant Field Values

POLICY_NOANONYMOUS

public static final String POLICY_NOANONYMOUS
The name of a property that specifies whether mechanisms that accept anonymous login are not permitted. The property contains "true" if mechanisms that accept anonymous login are not permitted; "false" if such mechanisms are permitted. The default is "false".
The value of this constant is "javax.security.sasl.policy.noanonymous".

See Also:
Constant Field Values

POLICY_FORWARD_SECRECY

public static final String POLICY_FORWARD_SECRECY
The name of a property that specifies whether mechanisms that implement forward secrecy between sessions are required. Forward secrecy means that breaking into one session will not automatically provide information for breaking into future sessions. The property contains "true" if mechanisms that implement forward secrecy between sessions are required; "false" if such mechanisms are not required. The default is "false".
The value of this constant is "javax.security.sasl.policy.forward".

See Also:
Constant Field Values

POLICY_PASS_CREDENTIALS

public static final String POLICY_PASS_CREDENTIALS
The name of a property that specifies whether mechanisms that pass client credentials are required. The property contains "true" if mechanisms that pass client credentials are required; "false" if such mechanisms are not required. The default is "false".
The value of this constant is "javax.security.sasl.policy.credentials".

See Also:
Constant Field Values

CREDENTIALS

public static final String CREDENTIALS
The name of a property that specifies the credentials to use. The property contains a mechanism-specific Java credential object. Mechanism implementations may examine the value of this property to determine whether it is a class that they support. The property may be used to supply credentials to a mechanism that supports delegated authentication.
The value of this constant is "javax.security.sasl.credentials".

See Also:
Constant Field Values
Method Detail

createSaslClient

public static SaslClient createSaslClient(String[] mechanisms,
                                          String authorizationId,
                                          String protocol,
                                          String serverName,
                                          Map<String,?> props,
                                          CallbackHandler cbh)
                                   throws SaslException
Creates a SaslClient using the parameters supplied. This method uses the JCA Security Provider Framework, described in the "Java Cryptography Architecture API Specification & Reference", for locating and selecting a SaslClient implementation. First, it obtains an ordered list of SaslClientFactory instances from the registered security providers for the "SaslClientFactory" service and the specified SASL mechanism(s). It then invokes createSaslClient() on each factory instance on the list until one produces a non-null SaslClient instance. It returns the non-null SaslClient instance, or null if the search fails to produce a non-null SaslClient instance.

A security provider for SaslClientFactory registers with the JCA Security Provider Framework keys of the form
SaslClientFactory.mechanism_name
and values that are class names of implementations of javax.security.sasl.SaslClientFactory. For example, a provider that contains a factory class, com.wiz.sasl.digest.ClientFactory, that supports the "DIGEST-MD5" mechanism would register the following entry with the JCA: SaslClientFactory.DIGEST-MD5 com.wiz.sasl.digest.ClientFactory

See the "Java Cryptography Architecture API Specification & Reference" for information about how to install and configure security service providers.

Parameters:
mechanisms - The non-null list of mechanism names to try. Each is the IANA-registered name of a SASL mechanism. (e.g. "GSSAPI", "CRAM-MD5").
authorizationId - The possibly null protocol-dependent identification to be used for authorization. If null or empty, the server derives an authorization ID from the client's authentication credentials. When the SASL authentication completes successfully, the specified entity is granted access.
protocol - The non-null string name of the protocol for which the authentication is being performed (e.g., "ldap").
serverName - The non-null fully-qualified host name of the server to authenticate to.
props - The possibly null set of properties used to select the SASL mechanism and to configure the authentication exchange of the selected mechanism. For example, if props contains the Sasl.POLICY_NOPLAINTEXT property with the value "true", then the selected SASL mechanism must not be susceptible to simple plain passive attacks. In addition to the standard properties declared in this class, other, possibly mechanism-specific, properties can be included. Properties not relevant to the selected mechanism are ignored, including any map entries with non-String keys.
cbh - The possibly null callback handler to used by the SASL mechanisms to get further information from the application/library to complete the authentication. For example, a SASL mechanism might require the authentication ID, password and realm from the caller. The authentication ID is requested by using a NameCallback. The password is requested by using a PasswordCallback. The realm is requested by using a RealmChoiceCallback if there is a list of realms to choose from, and by using a RealmCallback if the realm must be entered.
Returns:
A possibly null SaslClient created using the parameters supplied. If null, cannot find a SaslClientFactory that will produce one.
Throws:
SaslException - If cannot create a SaslClient because of an error.

createSaslServer

public static SaslServer createSaslServer(String mechanism,
                                          String protocol,
                                          String serverName,
                                          Map<String,?> props,
                                          CallbackHandler cbh)
                                   throws SaslException
Creates a SaslServer for the specified mechanism. This method uses the JCA Security Provider Framework, described in the "Java Cryptography Architecture API Specification & Reference", for locating and selecting a SaslServer implementation. First, it obtains an ordered list of SaslServerFactory instances from the registered security providers for the "SaslServerFactory" service and the specified mechanism. It then invokes createSaslServer() on each factory instance on the list until one produces a non-null SaslServer instance. It returns the non-null SaslServer instance, or null if the search fails to produce a non-null SaslServer instance.

A security provider for SaslServerFactory registers with the JCA Security Provider Framework keys of the form
SaslServerFactory.mechanism_name
and values that are class names of implementations of javax.security.sasl.SaslServerFactory. For example, a provider that contains a factory class, com.wiz.sasl.digest.ServerFactory, that supports the "DIGEST-MD5" mechanism would register the following entry with the JCA: SaslServerFactory.DIGEST-MD5 com.wiz.sasl.digest.ServerFactory

See the "Java Cryptography Architecture API Specification & Reference" for information about how to install and configure security service providers.

Parameters:
mechanism - The non-null mechanism name. It must be an IANA-registered name of a SASL mechanism. (e.g. "GSSAPI", "CRAM-MD5").
protocol - The non-null string name of the protocol for which the authentication is being performed (e.g., "ldap").
serverName - The non-null fully qualified host name of the server.
props - The possibly null set of properties used to select the SASL mechanism and to configure the authentication exchange of the selected mechanism. For example, if props contains the Sasl.POLICY_NOPLAINTEXT property with the value "true", then the selected SASL mechanism must not be susceptible to simple plain passive attacks. In addition to the standard properties declared in this class, other, possibly mechanism-specific, properties can be included. Properties not relevant to the selected mechanism are ignored, including any map entries with non-String keys.
cbh - The possibly null callback handler to used by the SASL mechanisms to get further information from the application/library to complete the authentication. For example, a SASL mechanism might require the authentication ID, password and realm from the caller. The authentication ID is requested by using a NameCallback. The password is requested by using a PasswordCallback. The realm is requested by using a RealmChoiceCallback if there is a list of realms to choose from, and by using a RealmCallback if the realm must be entered.
Returns:
A possibly null SaslServer created using the parameters supplied. If null, cannot find a SaslServerFactory that will produce one.
Throws:
SaslException - If cannot create a SaslServer because of an error.

getSaslClientFactories

public static Enumeration<SaslClientFactory> getSaslClientFactories()
Gets an enumeration of known factories for producing SaslClient. This method uses the same algorithm for locating factories as createSaslClient().

Returns:
A non-null enumeration of known factories for producing SaslClient.
See Also:
createSaslClient(java.lang.String[], java.lang.String, java.lang.String, java.lang.String, java.util.Map, javax.security.auth.callback.CallbackHandler)

getSaslServerFactories

public static Enumeration<SaslServerFactory> getSaslServerFactories()
Gets an enumeration of known factories for producing SaslServer. This method uses the same algorithm for locating factories as createSaslServer().

Returns:
A non-null enumeration of known factories for producing SaslServer.
See Also:
createSaslServer(java.lang.String, java.lang.String, java.lang.String, java.util.Map, javax.security.auth.callback.CallbackHandler)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SaslClient

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.sasl
Interface SaslClient

public interface SaslClient

Performs SASL authentication as a client.

A protocol library such as one for LDAP gets an instance of this class in order to perform authentication defined by a specific SASL mechanism. Invoking methods on the SaslClient instance process challenges and create responses according to the SASL mechanism implemented by the SaslClient. As the authentication proceeds, the instance encapsulates the state of a SASL client's authentication exchange.

Here's an example of how an LDAP library might use a SaslClient. It first gets an instance of a SaslClient:

 SaslClient sc = Sasl.createSaslClient(mechanisms,
     authorizationId, protocol, serverName, props, callbackHandler);
It can then proceed to use the client for authentication. For example, an LDAP library might use the client as follows:
 // Get initial response and send to server
 byte[] response = (sc.hasInitialResponse() ? sc.evaluateChallenge(new byte[0]) :
     null);
 LdapResult res = ldap.sendBindRequest(dn, sc.getName(), response);
 while (!sc.isComplete() &&
     (res.status == SASL_BIND_IN_PROGRESS || res.status == SUCCESS)) {
     response = sc.evaluateChallenge(res.getBytes());
     if (res.status == SUCCESS) {
         // we're done; don't expect to send another BIND
         if (response != null) {
               throw new SaslException(
                   "Protocol error: attempting to send response after completion");
           }
         break;
     }
     res = ldap.sendBindRequest(dn, sc.getName(), response);
 }
 if (sc.isComplete() && res.status == SUCCESS) {
    String qop = (String) sc.getNegotiatedProperty(Sasl.QOP);
    if (qop != null
        && (qop.equalsIgnoreCase("auth-int")
            || qop.equalsIgnoreCase("auth-conf"))) {

      // Use SaslClient.wrap() and SaslClient.unwrap() for future
      // communication with server
        ldap.in = new SecureInputStream(sc, ldap.in);
        ldap.out = new SecureOutputStream(sc, ldap.out);
    }
 }
If the mechanism has an initial response, the library invokes evaluateChallenge() with an empty challenge and to get initial response. Protocols such as IMAP4, which do not include an initial response with their first authentication command to the server, initiates the authentication without first calling hasInitialResponse() or evaluateChallenge(). When the server responds to the command, it sends an initial challenge. For a SASL mechanism in which the client sends data first, the server should have issued a challenge with no data. This will then result in a call (on the client) to evaluateChallenge() with an empty challenge.

Since:
1.5
See Also:
Sasl, SaslClientFactory

Method Summary
void | dispose() Disposes of any system resources or security-sensitive information the SaslClient might be using.
byte[] | evaluateChallenge(byte[] challenge) Evaluates the challenge data and generates a response.
String | getMechanismName() Returns the IANA-registered mechanism name of this SASL client.
Object | getNegotiatedProperty(String propName) Retrieves the negotiated property.
boolean | hasInitialResponse() Determines whether this mechanism has an optional initial response.
boolean | isComplete() Determines whether the authentication exchange has completed.
byte[] | unwrap(byte[] incoming, int offset, int len) Unwraps a byte array received from the server.
byte[] | wrap(byte[] outgoing, int offset, int len) Wraps a byte array to be sent to the server.

Method Detail

getMechanismName

String getMechanismName()
Returns the IANA-registered mechanism name of this SASL client. (e.g. "CRAM-MD5", "GSSAPI").

Returns:
A non-null string representing the IANA-registered mechanism name.

hasInitialResponse

boolean hasInitialResponse()
Determines whether this mechanism has an optional initial response. If true, caller should call evaluateChallenge() with an empty array to get the initial response.

Returns:
true if this mechanism has an initial response.

evaluateChallenge

byte[] evaluateChallenge(byte[] challenge)
                         throws SaslException
Evaluates the challenge data and generates a response. If a challenge is received from the server during the authentication process, this method is called to prepare an appropriate next response to submit to the server.

Parameters:
challenge - The non-null challenge sent from the server. The challenge array may have zero length.
Returns:
The possibly null reponse to send to the server. It is null if the challenge accompanied a "SUCCESS" status and the challenge only contains data for the client to update its state and no response needs to be sent to the server. The response is a zero-length byte array if the client is to send a response with no data.
Throws:
SaslException - If an error occurred while processing the challenge or generating a response.

isComplete

boolean isComplete()
Determines whether the authentication exchange has completed. This method may be called at any time, but typically, it will not be called until the caller has received indication from the server (in a protocol-specific manner) that the exchange has completed.

Returns:
true if the authentication exchange has completed; false otherwise.

unwrap

byte[] unwrap(byte[] incoming,
              int offset,
              int len)
              throws SaslException
Unwraps a byte array received from the server. This method can be called only after the authentication exchange has completed (i.e., when isComplete() returns true) and only if the authentication exchange has negotiated integrity and/or privacy as the quality of protection; otherwise, an IllegalStateException is thrown.

incoming is the contents of the SASL buffer as defined in RFC 2222 without the leading four octet field that represents the length. offset and len specify the portion of incoming to use.

Parameters:
incoming - A non-null byte array containing the encoded bytes from the server.
offset - The starting position at incoming of the bytes to use.
len - The number of bytes from incoming to use.
Returns:
A non-null byte array containing the decoded bytes.
Throws:
SaslException - if incoming cannot be successfully unwrapped.
IllegalStateException - if the authentication exchange has not completed, or if the negotiated quality of protection has neither integrity nor privacy.

wrap

byte[] wrap(byte[] outgoing,
            int offset,
            int len)
            throws SaslException
Wraps a byte array to be sent to the server. This method can be called only after the authentication exchange has completed (i.e., when isComplete() returns true) and only if the authentication exchange has negotiated integrity and/or privacy as the quality of protection; otherwise, an IllegalStateException is thrown.

The result of this method will make up the contents of the SASL buffer as defined in RFC 2222 without the leading four octet field that represents the length. offset and len specify the portion of outgoing to use.

Parameters:
outgoing - A non-null byte array containing the bytes to encode.
offset - The starting position at outgoing of the bytes to use.
len - The number of bytes from outgoing to use.
Returns:
A non-null byte array containing the encoded bytes.
Throws:
SaslException - if outgoing cannot be successfully wrapped.
IllegalStateException - if the authentication exchange has not completed, or if the negotiated quality of protection has neither integrity nor privacy.

getNegotiatedProperty

Object getNegotiatedProperty(String propName)
Retrieves the negotiated property. This method can be called only after the authentication exchange has completed (i.e., when isComplete() returns true); otherwise, an IllegalStateException is thrown.

Parameters:
propName - The non-null property name.
Returns:
The value of the negotiated property. If null, the property was not negotiated or is not applicable to this mechanism.
Throws:
IllegalStateException - if this authentication exchange has not completed

dispose

void dispose()
             throws SaslException
Disposes of any system resources or security-sensitive information the SaslClient might be using. Invoking this method invalidates the SaslClient instance. This method is idempotent.

Throws:
SaslException - If a problem was encountered while disposing the resources.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SaslClientFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.sasl
Interface SaslClientFactory

public interface SaslClientFactory

An interface for creating instances of SaslClient. A class that implements this interface must be thread-safe and handle multiple simultaneous requests. It must also have a public constructor that accepts no argument.

This interface is not normally accessed directly by a client, which will use the Sasl static methods instead. However, a particular environment may provide and install a new or different SaslClientFactory.

Since:
1.5
See Also:
SaslClient, Sasl

Method Summary
SaslClient | createSaslClient(String[] mechanisms, String authorizationId, String protocol, String serverName, Map<String,?> props, CallbackHandler cbh) Creates a SaslClient using the parameters supplied.
String[] | getMechanismNames(Map<String,?> props) Returns an array of names of mechanisms that match the specified mechanism selection policies.

Method Detail

createSaslClient

SaslClient createSaslClient(String[] mechanisms,
                            String authorizationId,
                            String protocol,
                            String serverName,
                            Map<String,?> props,
                            CallbackHandler cbh)
                            throws SaslException
Creates a SaslClient using the parameters supplied.

Parameters:
mechanisms - The non-null list of mechanism names to try. Each is the IANA-registered name of a SASL mechanism. (e.g. "GSSAPI", "CRAM-MD5").
authorizationId - The possibly null protocol-dependent identification to be used for authorization. If null or empty, the server derives an authorization ID from the client's authentication credentials. When the SASL authentication completes successfully, the specified entity is granted access.
protocol - The non-null string name of the protocol for which the authentication is being performed (e.g., "ldap").
serverName - The non-null fully qualified host name of the server to authenticate to.
props - The possibly null set of properties used to select the SASL mechanism and to configure the authentication exchange of the selected mechanism. See the Sasl class for a list of standard properties. Other, possibly mechanism-specific, properties can be included. Properties not relevant to the selected mechanism are ignored, including any map entries with non-String keys.
cbh - The possibly null callback handler to used by the SASL mechanisms to get further information from the application/library to complete the authentication. For example, a SASL mechanism might require the authentication ID, password and realm from the caller. The authentication ID is requested by using a NameCallback. The password is requested by using a PasswordCallback. The realm is requested by using a RealmChoiceCallback if there is a list of realms to choose from, and by using a RealmCallback if the realm must be entered.
Returns:
A possibly null SaslClient created using the parameters supplied. If null, this factory cannot produce a SaslClient using the parameters supplied.
Throws:
SaslException - If cannot create a SaslClient because of an error.

getMechanismNames

String[] getMechanismNames(Map<String,?> props)
Returns an array of names of mechanisms that match the specified mechanism selection policies.

Parameters:
props - The possibly null set of properties used to specify the security policy of the SASL mechanisms. For example, if props contains the Sasl.POLICY_NOPLAINTEXT property with the value "true", then the factory must not return any SASL mechanisms that are susceptible to simple plain passive attacks. See the Sasl class for a complete list of policy properties. Non-policy related properties, if present in props, are ignored, including any map entries with non-String keys.
Returns:
A non-null array containing a IANA-registered SASL mechanism names.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SaslException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.sasl
Class SaslException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.io.IOException
                extended by  javax.security.sasl.SaslException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
AuthenticationException
public class SaslException
extends IOException

This class represents an error that has occurred when using SASL.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
SaslException()
Constructs a new instance of SaslException.
SaslException(String detail)
Constructs a new instance of SaslException with a detailed message.
SaslException(String detail, Throwable ex)
Constructs a new instance of SaslException with a detailed message and a root exception.
Method Summary
Throwable | getCause() Returns the cause of this throwable or null if the cause is nonexistent or unknown.
Throwable | initCause(Throwable cause) Initializes the cause of this throwable to the specified value.
String | toString() Returns the string representation of this exception.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SaslException

public SaslException()
Constructs a new instance of SaslException. The root exception and the detailed message are null.

SaslException

public SaslException(String detail)
Constructs a new instance of SaslException with a detailed message. The root exception is null.

Parameters:
detail - A possibly null string containing details of the exception.
See Also:
Throwable.getMessage()

SaslException

public SaslException(String detail,
                     Throwable ex)
Constructs a new instance of SaslException with a detailed message and a root exception. For example, a SaslException might result from a problem with the callback handler, which might throw a NoSuchCallbackException if it does not support the requested callback, or throw an IOException if it had problems obtaining data for the callback. The SaslException's root exception would be then be the exception thrown by the callback handler.

Parameters:
detail - A possibly null string containing details of the exception.
ex - A possibly null root exception that caused this exception.
See Also:
Throwable.getMessage(), getCause()
Method Detail

getCause

public Throwable getCause()
Description copied from class: Throwable
Returns the cause of this throwable or null if the cause is nonexistent or unknown. (The cause is the throwable that caused this throwable to get thrown.)

This implementation returns the cause that was supplied via one of the constructors requiring a Throwable, or that was set after creation with the Throwable.initCause(Throwable) method. While it is typically unnecessary to override this method, a subclass can override it to return a cause set by some other means. This is appropriate for a "legacy chained throwable" that predates the addition of chained exceptions to Throwable. Note that it is not necessary to override any of the PrintStackTrace methods, all of which invoke the getCause method to determine the cause of a throwable.

Overrides:
getCause in class Throwable
Returns:
the cause of this throwable or null if the cause is nonexistent or unknown.

initCause

public Throwable initCause(Throwable cause)
Description copied from class: Throwable
Initializes the cause of this throwable to the specified value. (The cause is the throwable that caused this throwable to get thrown.)

This method can be called at most once. It is generally called from within the constructor, or immediately after creating the throwable. If this throwable was created with Throwable.Throwable(Throwable) or Throwable.Throwable(String,Throwable), this method cannot be called even once.

Overrides:
initCause in class Throwable
Parameters:
cause - the cause (which is saved for later retrieval by the Throwable.getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
Returns:
a reference to this Throwable instance.

toString

public String toString()
Returns the string representation of this exception. The string representation contains this exception's class name, its detailed messsage, and if it has a root exception, the string representation of the root exception. This string representation is meant for debugging and not meant to be interpreted programmatically.

Overrides:
toString in class Throwable
Returns:
The non-null string representation of this exception.
See Also:
Throwable.getMessage()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SaslServer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.security.sasl
Interface SaslServer

public interface SaslServer

Performs SASL authentication as a server.

A server such an LDAP server gets an instance of this class in order to perform authentication defined by a specific SASL mechanism. Invoking methods on the SaslServer instance generates challenges according to the SASL mechanism implemented by the SaslServer. As the authentication proceeds, the instance encapsulates the state of a SASL server's authentication exchange.

Here's an example of how an LDAP server might use a SaslServer. It first gets an instance of a SaslServer for the SASL mechanism requested by the client:

 SaslServer ss = Sasl.createSaslServer(mechanism,
     "ldap", myFQDN, props, callbackHandler);
It can then proceed to use the server for authentication. For example, suppose the LDAP server received an LDAP BIND request containing the name of the SASL mechanism and an (optional) initial response. It then might use the server as follows:
 while (!ss.isComplete()) {
     try {
         byte[] challenge = ss.evaluateResponse(response);
         if (ss.isComplete()) {
             status = ldap.sendBindResponse(mechanism, challenge, SUCCESS);
         } else {
             status = ldap.sendBindResponse(mechanism, challenge,
                   SASL_BIND_IN_PROGRESS);
             response = ldap.readBindRequest();
         }
     } catch (SaslException e) {
            status = ldap.sendErrorResponse(e);
            break;
     }
 }
 if (ss.isComplete() && status == SUCCESS) {
    String qop = (String) sc.getNegotiatedProperty(Sasl.QOP);
    if (qop != null
        && (qop.equalsIgnoreCase("auth-int")
            || qop.equalsIgnoreCase("auth-conf"))) {

      // Use SaslServer.wrap() and SaslServer.unwrap() for future
      // communication with client
        ldap.in = new SecureInputStream(ss, ldap.in);
        ldap.out = new SecureOutputStream(ss, ldap.out);
    }
 }

Since:
1.5
See Also:
Sasl, SaslServerFactory

Method Summary
void | dispose() Disposes of any system resources or security-sensitive information the SaslServer might be using.
byte[] | evaluateResponse(byte[] response) Evaluates the response data and generates a challenge.
String | getAuthorizationID() Reports the authorization ID in effect for the client of this session.
String | getMechanismName() Returns the IANA-registered mechanism name of this SASL server.
Object | getNegotiatedProperty(String propName) Retrieves the negotiated property.
boolean | isComplete() Determines whether the authentication exchange has completed.
byte[] | unwrap(byte[] incoming, int offset, int len) Unwraps a byte array received from the client.
byte[] | wrap(byte[] outgoing, int offset, int len) Wraps a byte array to be sent to the client.

Method Detail

getMechanismName

String getMechanismName()
Returns the IANA-registered mechanism name of this SASL server. (e.g. "CRAM-MD5", "GSSAPI").

Returns:
A non-null string representing the IANA-registered mechanism name.

evaluateResponse

byte[] evaluateResponse(byte[] response)
                        throws SaslException
Evaluates the response data and generates a challenge. If a response is received from the client during the authentication process, this method is called to prepare an appropriate next challenge to submit to the client. The challenge is null if the authentication has succeeded and no more challenge data is to be sent to the client. It is non-null if the authentication must be continued by sending a challenge to the client, or if the authentication has succeeded but challenge data needs to be processed by the client. isComplete() should be called after each call to evaluateResponse(),to determine if any further response is needed from the client.

Parameters:
response - The non-null (but possibly empty) response sent by the client.
Returns:
The possibly null challenge to send to the client. It is null if the authentication has succeeded and there is no more challenge data to be sent to the client.
Throws:
SaslException - If an error occurred while processing the response or generating a challenge.

isComplete

boolean isComplete()
Determines whether the authentication exchange has completed. This method is typically called after each invocation of evaluateResponse() to determine whether the authentication has completed successfully or should be continued.

Returns:
true if the authentication exchange has completed; false otherwise.

getAuthorizationID

String getAuthorizationID()
Reports the authorization ID in effect for the client of this session. This method can only be called if isComplete() returns true.

Returns:
The authorization ID of the client.
Throws:
IllegalStateException - if this authentication session has not completed

unwrap

byte[] unwrap(byte[] incoming,
              int offset,
              int len)
              throws SaslException
Unwraps a byte array received from the client. This method can be called only after the authentication exchange has completed (i.e., when isComplete() returns true) and only if the authentication exchange has negotiated integrity and/or privacy as the quality of protection; otherwise, an IllegalStateException is thrown.

incoming is the contents of the SASL buffer as defined in RFC 2222 without the leading four octet field that represents the length. offset and len specify the portion of incoming to use.

Parameters:
incoming - A non-null byte array containing the encoded bytes from the client.
offset - The starting position at incoming of the bytes to use.
len - The number of bytes from incoming to use.
Returns:
A non-null byte array containing the decoded bytes.
Throws:
SaslException - if incoming cannot be successfully unwrapped.
IllegalStateException - if the authentication exchange has not completed, or if the negotiated quality of protection has neither integrity nor privacy

wrap

byte[] wrap(byte[] outgoing,
            int offset,
            int len)
            throws SaslException
Wraps a byte array to be sent to the client. This method can be called only after the authentication exchange has completed (i.e., when isComplete() returns true) and only if the authentication exchange has negotiated integrity and/or privacy as the quality of protection; otherwise, a SaslException is thrown.

The result of this method will make up the contents of the SASL buffer as defined in RFC 2222 without the leading four octet field that represents the length. offset and len specify the portion of outgoing to use.

Parameters:
outgoing - A non-null byte array containing the bytes to encode.
offset - The starting position at outgoing of the bytes to use.
len - The number of bytes from outgoing to use.
Returns:
A non-null byte array containing the encoded bytes.
Throws:
SaslException - if outgoing cannot be successfully wrapped.
IllegalStateException - if the authentication exchange has not completed, or if the negotiated quality of protection has neither integrity nor privacy.

getNegotiatedProperty

Object getNegotiatedProperty(String propName)
Retrieves the negotiated property. This method can be called only after the authentication exchange has completed (i.e., when isComplete() returns true); otherwise, an IllegalStateException is thrown.

Parameters:
propName - the property
Returns:
The value of the negotiated property. If null, the property was not negotiated or is not applicable to this mechanism.
Throws:
IllegalStateException - if this authentication exchange has not completed

dispose

void dispose()
             throws SaslException
Disposes of any system resources or security-sensitive information the SaslServer might be using. Invoking this method invalidates the SaslServer instance. This method is idempotent.

Throws:
SaslException - If a problem was encountered while disposing the resources.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SaslServerFactory

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.security.sasl
Interface SaslServerFactory

public interface SaslServerFactory

An interface for creating instances of SaslServer. A class that implements this interface must be thread-safe and handle multiple simultaneous requests. It must also have a public constructor that accepts no argument.

This interface is not normally accessed directly by a server, which will use the Sasl static methods instead. However, a particular environment may provide and install a new or different SaslServerFactory.

Since:
1.5
See Also:
SaslServer, Sasl

Method Summary
SaslServer | createSaslServer(String mechanism, String protocol, String serverName, Map<String,?> props, CallbackHandler cbh) Creates a SaslServer using the parameters supplied.
String[] | getMechanismNames(Map<String,?> props) Returns an array of names of mechanisms that match the specified mechanism selection policies.

Method Detail

createSaslServer

SaslServer createSaslServer(String mechanism,
                            String protocol,
                            String serverName,
                            Map<String,?> props,
                            CallbackHandler cbh)
                            throws SaslException
Creates a SaslServer using the parameters supplied. It returns null if no SaslServer can be created using the parameters supplied. Throws SaslException if it cannot create a SaslServer because of an error.

Parameters:
mechanism - The non-null IANA-registered name of a SASL mechanism. (e.g. "GSSAPI", "CRAM-MD5").
protocol - The non-null string name of the protocol for which the authentication is being performed (e.g., "ldap").
serverName - The non-null fully qualified host name of the server to authenticate to.
props - The possibly null set of properties used to select the SASL mechanism and to configure the authentication exchange of the selected mechanism. See the Sasl class for a list of standard properties. Other, possibly mechanism-specific, properties can be included. Properties not relevant to the selected mechanism are ignored, including any map entries with non-String keys.
cbh - The possibly null callback handler to used by the SASL mechanisms to get further information from the application/library to complete the authentication. For example, a SASL mechanism might require the authentication ID, password and realm from the caller. The authentication ID is requested by using a NameCallback. The password is requested by using a PasswordCallback. The realm is requested by using a RealmChoiceCallback if there is a list of realms to choose from, and by using a RealmCallback if the realm must be entered.
Returns:
A possibly null SaslServer created using the parameters supplied. If null, this factory cannot produce a SaslServer using the parameters supplied.
Throws:
SaslException - If cannot create a SaslServer because of an error.

getMechanismNames

String[] getMechanismNames(Map<String,?> props)
Returns an array of names of mechanisms that match the specified mechanism selection policies.

Parameters:
props - The possibly null set of properties used to specify the security policy of the SASL mechanisms. For example, if props contains the Sasl.POLICY_NOPLAINTEXT property with the value "true", then the factory must not return any SASL mechanisms that are susceptible to simple plain passive attacks. See the Sasl class for a complete list of policy properties. Non-policy related properties, if present in props, are ignored, including any map entries with non-String keys.
Returns:
A non-null array containing a IANA-registered SASL mechanism names.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


midi

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.sound.midi

Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

See:
Description

Interface Summary
ControllerEventListener | The ControllerEventListener interface should be implemented by classes whose instances need to be notified when a Sequencer has processed a requested type of MIDI control-change event.
MetaEventListener | The MetaEventListener interface should be implemented by classes whose instances need to be notified when a Sequencer has processed a MetaMessage.
MidiChannel | A MidiChannel object represents a single MIDI channel.
MidiDevice | MidiDevice is the base interface for all MIDI devices.
Receiver | A Receiver receives MidiEvent objects and typically does something useful in response, such as interpreting them to generate sound or raw MIDI output.
Sequencer | A hardware or software device that plays back a MIDI sequence is known as a sequencer.
Soundbank | A Soundbank contains a set of Instruments that can be loaded into a Synthesizer.
Synthesizer | A Synthesizer generates sound.
Transmitter | A Transmitter sends MidiEvent objects to one or more Receivers.

Class Summary
Instrument | An instrument is a sound-synthesis algorithm with certain parameter settings, usually designed to emulate a specific real-world musical instrument or to achieve a specific sort of sound effect.
MetaMessage | A MetaMessage is a MidiMessage that is not meaningful to synthesizers, but that can be stored in a MIDI file and interpreted by a sequencer program.
MidiDevice.Info | A MidiDevice.Info object contains assorted data about a MidiDevice, including its name, the company who created it, and descriptive text.
MidiEvent | MIDI events contain a MIDI message and a corresponding time-stamp expressed in ticks, and can represent the MIDI event information stored in a MIDI file or a Sequence object.
MidiFileFormat | A MidiFileFormat object encapsulates a MIDI file's type, as well as its length and timing information.
MidiMessage | MidiMessage is the base class for MIDI messages.
MidiSystem | The MidiSystem class provides access to the installed MIDI system resources, including devices such as synthesizers, sequencers, and MIDI input and output ports.
Patch | A Patch object represents a location, on a MIDI synthesizer, into which a single instrument is stored (loaded).
Sequence | A Sequence is a data structure containing musical information (often an entire song or composition) that can be played back by a Sequencer object.
Sequencer.SyncMode | A SyncMode object represents one of the ways in which a MIDI sequencer's notion of time can be synchronized with a master or slave device.
ShortMessage | A ShortMessage contains a MIDI message that has at most two data bytes following its status byte.
SoundbankResource | A SoundbankResource represents any audio resource stored in a Soundbank.
SysexMessage | A SysexMessage object represents a MIDI system exclusive message.
Track | A MIDI track is an independent stream of MIDI events (time-stamped MIDI data) that can be stored along with other tracks in a standard MIDI file.
VoiceStatus | A VoiceStatus object contains information about the current status of one of the voices produced by a Synthesizer.

Exception Summary
InvalidMidiDataException | An InvalidMidiDataException indicates that inappropriate MIDI data was encountered.
MidiUnavailableException | A MidiUnavailableException is thrown when a requested MIDI component cannot be opened or created because it is unavailable.

Package javax.sound.midi Description

Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Related Documentation

For overviews, tutorials, examples, and guides, please see:
  • Sound

Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.sound.midi Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.sound.midi

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.sound.midi.MidiDevice.Info
    • javax.sound.midi.MidiEvent
    • javax.sound.midi.MidiFileFormat
    • javax.sound.midi.MidiMessage (implements java.lang.Cloneable)
      • javax.sound.midi.MetaMessage
      • javax.sound.midi.ShortMessage
      • javax.sound.midi.SysexMessage
    • javax.sound.midi.MidiSystem
    • javax.sound.midi.Patch
    • javax.sound.midi.Sequence
    • javax.sound.midi.Sequencer.SyncMode
    • javax.sound.midi.SoundbankResource
      • javax.sound.midi.Instrument
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.sound.midi.InvalidMidiDataException
        • javax.sound.midi.MidiUnavailableException
    • javax.sound.midi.Track
    • javax.sound.midi.VoiceStatus

Interface Hierarchy

  • java.util.EventListener
    • javax.sound.midi.ControllerEventListener
    • javax.sound.midi.MetaEventListener
  • javax.sound.midi.MidiChannel
  • javax.sound.midi.MidiDevice
    • javax.sound.midi.Sequencer
    • javax.sound.midi.Synthesizer
  • javax.sound.midi.Receiver
  • javax.sound.midi.Soundbank
  • javax.sound.midi.Transmitter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.sound.midi

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.sound.midi

Packages that use javax.sound.midi
javax.sound.midi | Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.
javax.sound.midi.spi | Supplies interfaces for service providers to implement when offering new MIDI devices, MIDI file readers and writers, or sound bank readers.

Classes in javax.sound.midi used by javax.sound.midi
ControllerEventListener
The ControllerEventListener interface should be implemented by classes whose instances need to be notified when a Sequencer has processed a requested type of MIDI control-change event.
Instrument
An instrument is a sound-synthesis algorithm with certain parameter settings, usually designed to emulate a specific real-world musical instrument or to achieve a specific sort of sound effect.
InvalidMidiDataException
An InvalidMidiDataException indicates that inappropriate MIDI data was encountered.
MetaEventListener
The MetaEventListener interface should be implemented by classes whose instances need to be notified when a Sequencer has processed a MetaMessage.
MetaMessage
A MetaMessage is a MidiMessage that is not meaningful to synthesizers, but that can be stored in a MIDI file and interpreted by a sequencer program.
MidiChannel
A MidiChannel object represents a single MIDI channel.
MidiDevice
MidiDevice is the base interface for all MIDI devices.
MidiDevice.Info
A MidiDevice.Info object contains assorted data about a MidiDevice, including its name, the company who created it, and descriptive text.
MidiEvent
MIDI events contain a MIDI message and a corresponding time-stamp expressed in ticks, and can represent the MIDI event information stored in a MIDI file or a Sequence object.
MidiFileFormat
A MidiFileFormat object encapsulates a MIDI file's type, as well as its length and timing information.
MidiMessage
MidiMessage is the base class for MIDI messages.
MidiUnavailableException
A MidiUnavailableException is thrown when a requested MIDI component cannot be opened or created because it is unavailable.
Patch
A Patch object represents a location, on a MIDI synthesizer, into which a single instrument is stored (loaded).
Receiver
A Receiver receives MidiEvent objects and typically does something useful in response, such as interpreting them to generate sound or raw MIDI output.
Sequence
A Sequence is a data structure containing musical information (often an entire song or composition) that can be played back by a Sequencer object.
Sequencer
A hardware or software device that plays back a MIDI sequence is known as a sequencer.
Sequencer.SyncMode
A SyncMode object represents one of the ways in which a MIDI sequencer's notion of time can be synchronized with a master or slave device.
ShortMessage
A ShortMessage contains a MIDI message that has at most two data bytes following its status byte.
Soundbank
A Soundbank contains a set of Instruments that can be loaded into a Synthesizer.
SoundbankResource
A SoundbankResource represents any audio resource stored in a Soundbank.
Synthesizer
A Synthesizer generates sound.
Track
A MIDI track is an independent stream of MIDI events (time-stamped MIDI data) that can be stored along with other tracks in a standard MIDI file.
Transmitter
A Transmitter sends MidiEvent objects to one or more Receivers.
VoiceStatus
A VoiceStatus object contains information about the current status of one of the voices produced by a Synthesizer.

Classes in javax.sound.midi used by javax.sound.midi.spi
InvalidMidiDataException
An InvalidMidiDataException indicates that inappropriate MIDI data was encountered.
MidiDevice
MidiDevice is the base interface for all MIDI devices.
MidiDevice.Info
A MidiDevice.Info object contains assorted data about a MidiDevice, including its name, the company who created it, and descriptive text.
MidiFileFormat
A MidiFileFormat object encapsulates a MIDI file's type, as well as its length and timing information.
Sequence
A Sequence is a data structure containing musical information (often an entire song or composition) that can be played back by a Sequencer object.
Soundbank
A Soundbank contains a set of Instruments that can be loaded into a Synthesizer.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.Instrument

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.Instrument

Packages that use Instrument
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of Instrument in javax.sound.midi

Methods in javax.sound.midi that return Instrument
Instrument[] | Synthesizer.getAvailableInstruments() Obtains a list of instruments that come with the synthesizer.
Instrument | Soundbank.getInstrument(Patch patch) Obtains an Instrument from the given Patch.
Instrument[] | Soundbank.getInstruments() Obtains a list of instruments contained in this sound bank.
Instrument[] | Synthesizer.getLoadedInstruments() Obtains a list of the instruments that are currently loaded onto this Synthesizer.

Methods in javax.sound.midi with parameters of type Instrument
boolean | Synthesizer.loadInstrument(Instrument instrument) Makes a particular instrument available for synthesis.
boolean | Synthesizer.remapInstrument(Instrument from, Instrument to) Remaps an instrument.
void | Synthesizer.unloadInstrument(Instrument instrument) Unloads a particular instrument.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.InvalidMidiDataException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.InvalidMidiDataException

Packages that use InvalidMidiDataException
javax.sound.midi | Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.
javax.sound.midi.spi | Supplies interfaces for service providers to implement when offering new MIDI devices, MIDI file readers and writers, or sound bank readers.

Uses of InvalidMidiDataException in javax.sound.midi

Methods in javax.sound.midi that throw InvalidMidiDataException
protected int | ShortMessage.getDataLength(int status) Retrieves the number of data bytes associated with a particular status byte value.
static MidiFileFormat | MidiSystem.getMidiFileFormat(File file) Obtains the MIDI file format of the specified File.
static MidiFileFormat | MidiSystem.getMidiFileFormat(InputStream stream) Obtains the MIDI file format of the data in the specified input stream.
static MidiFileFormat | MidiSystem.getMidiFileFormat(URL url) Obtains the MIDI file format of the data in the specified URL.
static Sequence | MidiSystem.getSequence(File file) Obtains a MIDI sequence from the specified File.
static Sequence | MidiSystem.getSequence(InputStream stream) Obtains a MIDI sequence from the specified input stream.
static Sequence | MidiSystem.getSequence(URL url) Obtains a MIDI sequence from the specified URL.
static Soundbank | MidiSystem.getSoundbank(File file) Constructs a Soundbank by reading it from the specified File.
static Soundbank | MidiSystem.getSoundbank(InputStream stream) Constructs a MIDI sound bank by reading it from the specified stream.
static Soundbank | MidiSystem.getSoundbank(URL url) Constructs a Soundbank by reading it from the specified URL.
void | SysexMessage.setMessage(byte[] data, int length) Sets the data for the system exclusive message.
protected void | MidiMessage.setMessage(byte[] data, int length) Sets the data for the MIDI message.
void | ShortMessage.setMessage(int status) Sets the parameters for a MIDI message that takes no data bytes.
void | SysexMessage.setMessage(int status, byte[] data, int length) Sets the data for the system exclusive message.
void | MetaMessage.setMessage(int type, byte[] data, int length) Sets the message parameters for a MetaMessage.
void | ShortMessage.setMessage(int status, int data1, int data2) Sets the parameters for a MIDI message that takes one or two data bytes.
void | ShortMessage.setMessage(int command, int channel, int data1, int data2) Sets the short message parameters for a channel message which takes up to two data bytes.
void | Sequencer.setSequence(InputStream stream) Sets the current sequence on which the sequencer operates.
void | Sequencer.setSequence(Sequence sequence) Sets the current sequence on which the sequencer operates.

Constructors in javax.sound.midi that throw InvalidMidiDataException
Sequence(float divisionType, int resolution)
Constructs a new MIDI sequence with the specified timing division type and timing resolution.
Sequence(float divisionType, int resolution, int numTracks)
Constructs a new MIDI sequence with the specified timing division type, timing resolution, and number of tracks.

Uses of InvalidMidiDataException in javax.sound.midi.spi

Methods in javax.sound.midi.spi that throw InvalidMidiDataException
abstract MidiFileFormat | MidiFileReader.getMidiFileFormat(File file) Obtains the MIDI file format of the File provided.
abstract MidiFileFormat | MidiFileReader.getMidiFileFormat(InputStream stream) Obtains the MIDI file format of the input stream provided.
abstract MidiFileFormat | MidiFileReader.getMidiFileFormat(URL url) Obtains the MIDI file format of the URL provided.
abstract Sequence | MidiFileReader.getSequence(File file) Obtains a MIDI sequence from the File provided.
abstract Sequence | MidiFileReader.getSequence(InputStream stream) Obtains a MIDI sequence from the input stream provided.
abstract Sequence | MidiFileReader.getSequence(URL url) Obtains a MIDI sequence from the URL provided.
abstract Soundbank | SoundbankReader.getSoundbank(File file) Obtains a soundbank object from the File provided.
abstract Soundbank | SoundbankReader.getSoundbank(InputStream stream) Obtains a soundbank object from the InputStream provided.
abstract Soundbank | SoundbankReader.getSoundbank(URL url) Obtains a soundbank object from the URL provided.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.MetaMessage

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.MetaMessage

Packages that use MetaMessage
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of MetaMessage in javax.sound.midi

Methods in javax.sound.midi with parameters of type MetaMessage
 void MetaEventListener.meta(MetaMessage meta)
Invoked when a Sequencer has encountered and processed a MetaMessage in the Sequence it is processing.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.MidiDevice.Info

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.MidiDevice.Info

Packages that use MidiDevice.Info
javax.sound.midi | Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.
javax.sound.midi.spi | Supplies interfaces for service providers to implement when offering new MIDI devices, MIDI file readers and writers, or sound bank readers.

Uses of MidiDevice.Info in javax.sound.midi

Methods in javax.sound.midi that return MidiDevice.Info
MidiDevice.Info | MidiDevice.getDeviceInfo() Obtains information about the device, including its Java class and Strings containing its name, vendor, and description.
static MidiDevice.Info[] | MidiSystem.getMidiDeviceInfo() Obtains an array of information objects representing the set of all MIDI devices available on the system.

Methods in javax.sound.midi with parameters of type MidiDevice.Info
static MidiDevice MidiSystem.getMidiDevice(MidiDevice.Info info)
Obtains the requested MIDI device.

Uses of MidiDevice.Info in javax.sound.midi.spi

Methods in javax.sound.midi.spi that return MidiDevice.Info
abstract  MidiDevice.Info[] MidiDeviceProvider.getDeviceInfo()
Obtains the set of info objects representing the device or devices provided by this MidiDeviceProvider.

Methods in javax.sound.midi.spi with parameters of type MidiDevice.Info
abstract MidiDevice | MidiDeviceProvider.getDevice(MidiDevice.Info info) Obtains an instance of the device represented by the info object.
boolean | MidiDeviceProvider.isDeviceSupported(MidiDevice.Info info) Indicates whether the device provider supports the device represented by the specified device info object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.MidiEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.MidiEvent

Packages that use MidiEvent
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of MidiEvent in javax.sound.midi

Methods in javax.sound.midi that return MidiEvent
 MidiEvent Track.get(int index)
Obtains the event at the specified index.

Methods in javax.sound.midi with parameters of type MidiEvent
boolean | Track.add(MidiEvent event) Adds a new event to the track.
boolean | Track.remove(MidiEvent event) Removes the specified event from the track.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.MidiFileFormat

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.MidiFileFormat

Packages that use MidiFileFormat
javax.sound.midi | Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.
javax.sound.midi.spi | Supplies interfaces for service providers to implement when offering new MIDI devices, MIDI file readers and writers, or sound bank readers.

Uses of MidiFileFormat in javax.sound.midi

Methods in javax.sound.midi that return MidiFileFormat
static MidiFileFormat | MidiSystem.getMidiFileFormat(File file) Obtains the MIDI file format of the specified File.
static MidiFileFormat | MidiSystem.getMidiFileFormat(InputStream stream) Obtains the MIDI file format of the data in the specified input stream.
static MidiFileFormat | MidiSystem.getMidiFileFormat(URL url) Obtains the MIDI file format of the data in the specified URL.

Uses of MidiFileFormat in javax.sound.midi.spi

Methods in javax.sound.midi.spi that return MidiFileFormat
abstract MidiFileFormat | MidiFileReader.getMidiFileFormat(File file) Obtains the MIDI file format of the File provided.
abstract MidiFileFormat | MidiFileReader.getMidiFileFormat(InputStream stream) Obtains the MIDI file format of the input stream provided.
abstract MidiFileFormat | MidiFileReader.getMidiFileFormat(URL url) Obtains the MIDI file format of the URL provided.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.MidiMessage

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.MidiMessage

Packages that use MidiMessage
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of MidiMessage in javax.sound.midi

Subclasses of MidiMessage in javax.sound.midi
class | MetaMessage A MetaMessage is a MidiMessage that is not meaningful to synthesizers, but that can be stored in a MIDI file and interpreted by a sequencer program.
class | ShortMessage A ShortMessage contains a MIDI message that has at most two data bytes following its status byte.
class | SysexMessage A SysexMessage object represents a MIDI system exclusive message.

Methods in javax.sound.midi that return MidiMessage
 MidiMessage MidiEvent.getMessage()
Obtains the MIDI message contained in the event.

Methods in javax.sound.midi with parameters of type MidiMessage
 void Receiver.send(MidiMessage message, long timeStamp)
Sends a MIDI message and time-stamp to this receiver.

Constructors in javax.sound.midi with parameters of type MidiMessage
MidiEvent(MidiMessage message, long tick)
Constructs a new MidiEvent.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.MidiSystem

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.MidiSystem

No usage of javax.sound.midi.MidiSystem

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.MidiUnavailableException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.MidiUnavailableException

Packages that use MidiUnavailableException
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of MidiUnavailableException in javax.sound.midi

Methods in javax.sound.midi that throw MidiUnavailableException
static MidiDevice | MidiSystem.getMidiDevice(MidiDevice.Info info) Obtains the requested MIDI device.
static Receiver | MidiSystem.getReceiver() Obtains a MIDI receiver from an external MIDI port or other default device.
Receiver | MidiDevice.getReceiver() Obtains a MIDI IN receiver through which the MIDI device may receive MIDI data.
static Sequencer | MidiSystem.getSequencer() Obtains the default Sequencer, connected to a default device.
static Sequencer | MidiSystem.getSequencer(boolean connected) Obtains the default Sequencer, optionally connected to a default device.
static Synthesizer | MidiSystem.getSynthesizer() Obtains the default synthesizer.
static Transmitter | MidiSystem.getTransmitter() Obtains a MIDI transmitter from an external MIDI port or other default source.
Transmitter | MidiDevice.getTransmitter() Obtains a MIDI OUT connection from which the MIDI device will transmit MIDI data The returned transmitter must be closed when the application has finished using it.
void | MidiDevice.open() Opens the device, indicating that it should now acquire any system resources it requires and become operational.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.Patch

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.Patch

Packages that use Patch
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of Patch in javax.sound.midi

Methods in javax.sound.midi that return Patch
Patch | Instrument.getPatch() Obtains the Patch object that indicates the bank and program numbers where this instrument is to be stored in the synthesizer.
Patch[] | Sequence.getPatchList() Obtains a list of patches referenced in this sequence.

Methods in javax.sound.midi with parameters of type Patch
Instrument | Soundbank.getInstrument(Patch patch) Obtains an Instrument from the given Patch.
boolean | Synthesizer.loadInstruments(Soundbank soundbank, Patch[] patchList) Loads the instruments referenced by the specified patches, from the specified Soundbank.
void | Synthesizer.unloadInstruments(Soundbank soundbank, Patch[] patchList) Unloads the instruments referenced by the specified patches, from the MIDI sound bank specified.

Constructors in javax.sound.midi with parameters of type Patch
Instrument(Soundbank soundbank, Patch patch, String name, Class<?> dataClass)
Constructs a new MIDI instrument from the specified Patch.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.Sequence

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.Sequence

Packages that use Sequence
javax.sound.midi | Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.
javax.sound.midi.spi | Supplies interfaces for service providers to implement when offering new MIDI devices, MIDI file readers and writers, or sound bank readers.

Uses of Sequence in javax.sound.midi

Methods in javax.sound.midi that return Sequence
Sequence | Sequencer.getSequence() Obtains the sequence on which the Sequencer is currently operating.
static Sequence | MidiSystem.getSequence(File file) Obtains a MIDI sequence from the specified File.
static Sequence | MidiSystem.getSequence(InputStream stream) Obtains a MIDI sequence from the specified input stream.
static Sequence | MidiSystem.getSequence(URL url) Obtains a MIDI sequence from the specified URL.

Methods in javax.sound.midi with parameters of type Sequence
static int[] | MidiSystem.getMidiFileTypes(Sequence sequence) Obtains the set of MIDI file types that the system can write from the sequence specified.
static boolean | MidiSystem.isFileTypeSupported(int fileType, Sequence sequence) Indicates whether a MIDI file of the file type specified can be written from the sequence indicated.
void | Sequencer.setSequence(Sequence sequence) Sets the current sequence on which the sequencer operates.
static int | MidiSystem.write(Sequence in, int type, File out) Writes a stream of bytes representing a file of the MIDI file type indicated to the external file provided.
static int | MidiSystem.write(Sequence in, int fileType, OutputStream out) Writes a stream of bytes representing a file of the MIDI file type indicated to the output stream provided.

Uses of Sequence in javax.sound.midi.spi

Methods in javax.sound.midi.spi that return Sequence
abstract Sequence | MidiFileReader.getSequence(File file) Obtains a MIDI sequence from the File provided.
abstract Sequence | MidiFileReader.getSequence(InputStream stream) Obtains a MIDI sequence from the input stream provided.
abstract Sequence | MidiFileReader.getSequence(URL url) Obtains a MIDI sequence from the URL provided.

Methods in javax.sound.midi.spi with parameters of type Sequence
abstract int[] | MidiFileWriter.getMidiFileTypes(Sequence sequence) Obtains the file types that this file writer can write from the sequence specified.
boolean | MidiFileWriter.isFileTypeSupported(int fileType, Sequence sequence) Indicates whether a MIDI file of the file type specified can be written from the sequence indicated.
abstract int | MidiFileWriter.write(Sequence in, int fileType, File out) Writes a stream of bytes representing a MIDI file of the file type indicated to the external file provided.
abstract int | MidiFileWriter.write(Sequence in, int fileType, OutputStream out) Writes a stream of bytes representing a MIDI file of the file type indicated to the output stream provided.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.Sequencer.SyncMode

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.Sequencer.SyncMode

Packages that use Sequencer.SyncMode
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of Sequencer.SyncMode in javax.sound.midi

Fields in javax.sound.midi declared as Sequencer.SyncMode
static Sequencer.SyncMode | Sequencer.SyncMode.INTERNAL_CLOCK A master synchronization mode that makes the sequencer get its timing information from its internal clock.
static Sequencer.SyncMode | Sequencer.SyncMode.MIDI_SYNC A master or slave synchronization mode that specifies the use of MIDI clock messages.
static Sequencer.SyncMode | Sequencer.SyncMode.MIDI_TIME_CODE A master or slave synchronization mode that specifies the use of MIDI Time Code.
static Sequencer.SyncMode | Sequencer.SyncMode.NO_SYNC A slave synchronization mode indicating that no timing information should be sent to the receiver.

Methods in javax.sound.midi that return Sequencer.SyncMode
Sequencer.SyncMode | Sequencer.getMasterSyncMode() Obtains the current master synchronization mode for this sequencer.
Sequencer.SyncMode[] | Sequencer.getMasterSyncModes() Obtains the set of master synchronization modes supported by this sequencer.
Sequencer.SyncMode | Sequencer.getSlaveSyncMode() Obtains the current slave synchronization mode for this sequencer.
Sequencer.SyncMode[] | Sequencer.getSlaveSyncModes() Obtains the set of slave synchronization modes supported by the sequencer.

Methods in javax.sound.midi with parameters of type Sequencer.SyncMode
void | Sequencer.setMasterSyncMode(Sequencer.SyncMode sync) Sets the source of timing information used by this sequencer.
void | Sequencer.setSlaveSyncMode(Sequencer.SyncMode sync) Sets the slave synchronization mode for the sequencer.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.ShortMessage

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.ShortMessage

Packages that use ShortMessage
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of ShortMessage in javax.sound.midi

Methods in javax.sound.midi with parameters of type ShortMessage
 void ControllerEventListener.controlChange(ShortMessage event)
Invoked when a Sequencer has encountered and processed a control-change event of interest to this listener.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.SoundbankResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.SoundbankResource

Packages that use SoundbankResource
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of SoundbankResource in javax.sound.midi

Subclasses of SoundbankResource in javax.sound.midi
 class Instrument
An instrument is a sound-synthesis algorithm with certain parameter settings, usually designed to emulate a specific real-world musical instrument or to achieve a specific sort of sound effect.

Methods in javax.sound.midi that return SoundbankResource
 SoundbankResource[] Soundbank.getResources()
Extracts a list of non-Instrument resources contained in the sound bank.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.SysexMessage

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.SysexMessage

No usage of javax.sound.midi.SysexMessage

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.Track

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.Track

Packages that use Track
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of Track in javax.sound.midi

Fields in javax.sound.midi with type parameters of type Track
protected  Vector<Track> Sequence.tracks
The MIDI tracks in this sequence.

Methods in javax.sound.midi that return Track
Track | Sequence.createTrack() Creates a new, initially empty track as part of this sequence.
Track[] | Sequence.getTracks() Obtains an array containing all the tracks in this sequence.

Methods in javax.sound.midi with parameters of type Track
boolean | Sequence.deleteTrack(Track track) Removes the specified track from the sequence.
void | Sequencer.recordDisable(Track track) Disables recording to the specified track.
void | Sequencer.recordEnable(Track track, int channel) Prepares the specified track for recording events received on a particular channel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.VoiceStatus

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.VoiceStatus

Packages that use VoiceStatus
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of VoiceStatus in javax.sound.midi

Methods in javax.sound.midi that return VoiceStatus
 VoiceStatus[] Synthesizer.getVoiceStatus()
Obtains the current status of the voices produced by this synthesizer.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sound.midi.ControllerEventListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sound.midi.ControllerEventListener

Packages that use ControllerEventListener
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of ControllerEventListener in javax.sound.midi

Methods in javax.sound.midi with parameters of type ControllerEventListener
int[] | Sequencer.addControllerEventListener(ControllerEventListener listener, int[] controllers) Registers a controller event listener to receive notification whenever the sequencer processes a control-change event of the requested type or types.
int[] | Sequencer.removeControllerEventListener(ControllerEventListener listener, int[] controllers) Removes a controller event listener's interest in one or more types of controller event.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sound.midi.MetaEventListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sound.midi.MetaEventListener

Packages that use MetaEventListener
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of MetaEventListener in javax.sound.midi

Methods in javax.sound.midi with parameters of type MetaEventListener
boolean | Sequencer.addMetaEventListener(MetaEventListener listener) Registers a meta-event listener to receive notification whenever a meta-event is encountered in the sequence and processed by the sequencer.
void | Sequencer.removeMetaEventListener(MetaEventListener listener) Removes the specified meta-event listener from this sequencer's list of registered listeners, if in fact the listener is registered.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sound.midi.MidiChannel

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sound.midi.MidiChannel

Packages that use MidiChannel
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of MidiChannel in javax.sound.midi

Methods in javax.sound.midi that return MidiChannel
 MidiChannel[] Synthesizer.getChannels()
Obtains the set of MIDI channels controlled by this synthesizer.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sound.midi.MidiDevice

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sound.midi.MidiDevice

Packages that use MidiDevice
javax.sound.midi | Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.
javax.sound.midi.spi | Supplies interfaces for service providers to implement when offering new MIDI devices, MIDI file readers and writers, or sound bank readers.

Uses of MidiDevice in javax.sound.midi

Subinterfaces of MidiDevice in javax.sound.midi
interface | Sequencer A hardware or software device that plays back a MIDI sequence is known as a sequencer.
interface | Synthesizer A Synthesizer generates sound.

Methods in javax.sound.midi that return MidiDevice
static MidiDevice MidiSystem.getMidiDevice(MidiDevice.Info info)
Obtains the requested MIDI device.

Uses of MidiDevice in javax.sound.midi.spi

Methods in javax.sound.midi.spi that return MidiDevice
abstract  MidiDevice MidiDeviceProvider.getDevice(MidiDevice.Info info)
Obtains an instance of the device represented by the info object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sound.midi.Receiver

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sound.midi.Receiver

Packages that use Receiver
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of Receiver in javax.sound.midi

Methods in javax.sound.midi that return Receiver
static Receiver | MidiSystem.getReceiver() Obtains a MIDI receiver from an external MIDI port or other default device.
Receiver | Transmitter.getReceiver() Obtains the current receiver to which this transmitter will deliver MIDI messages.
Receiver | MidiDevice.getReceiver() Obtains a MIDI IN receiver through which the MIDI device may receive MIDI data.

Methods in javax.sound.midi that return types with arguments of type Receiver
 List<Receiver> MidiDevice.getReceivers()
Returns all currently active, non-closed receivers connected with this MidiDevice.

Methods in javax.sound.midi with parameters of type Receiver
 void Transmitter.setReceiver(Receiver receiver)
Sets the receiver to which this transmitter will deliver MIDI messages.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sound.midi.Sequencer

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sound.midi.Sequencer

Packages that use Sequencer
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of Sequencer in javax.sound.midi

Methods in javax.sound.midi that return Sequencer
static Sequencer | MidiSystem.getSequencer() Obtains the default Sequencer, connected to a default device.
static Sequencer | MidiSystem.getSequencer(boolean connected) Obtains the default Sequencer, optionally connected to a default device.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sound.midi.Soundbank

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sound.midi.Soundbank

Packages that use Soundbank
javax.sound.midi | Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.
javax.sound.midi.spi | Supplies interfaces for service providers to implement when offering new MIDI devices, MIDI file readers and writers, or sound bank readers.

Uses of Soundbank in javax.sound.midi

Methods in javax.sound.midi that return Soundbank
Soundbank | Synthesizer.getDefaultSoundbank() Obtains the default soundbank for the synthesizer, if one exists.
Soundbank | SoundbankResource.getSoundbank() Obtains the sound bank that contains this SoundbankResource.
static Soundbank | MidiSystem.getSoundbank(File file) Constructs a Soundbank by reading it from the specified File.
static Soundbank | MidiSystem.getSoundbank(InputStream stream) Constructs a MIDI sound bank by reading it from the specified stream.
static Soundbank | MidiSystem.getSoundbank(URL url) Constructs a Soundbank by reading it from the specified URL.

Methods in javax.sound.midi with parameters of type Soundbank
boolean | Synthesizer.isSoundbankSupported(Soundbank soundbank) Informs the caller whether this synthesizer is capable of loading instruments from the specified soundbank.
boolean | Synthesizer.loadAllInstruments(Soundbank soundbank) Loads onto the Synthesizer all instruments contained in the specified Soundbank.
boolean | Synthesizer.loadInstruments(Soundbank soundbank, Patch[] patchList) Loads the instruments referenced by the specified patches, from the specified Soundbank.
void | Synthesizer.unloadAllInstruments(Soundbank soundbank) Unloads all instruments contained in the specified Soundbank.
void | Synthesizer.unloadInstruments(Soundbank soundbank, Patch[] patchList) Unloads the instruments referenced by the specified patches, from the MIDI sound bank specified.

Constructors in javax.sound.midi with parameters of type Soundbank
Instrument(Soundbank soundbank, Patch patch, String name, Class<?> dataClass)
Constructs a new MIDI instrument from the specified Patch.
SoundbankResource(Soundbank soundBank, String name, Class<?> dataClass)
Constructs a new SoundbankResource from the given sound bank and wavetable index.

Uses of Soundbank in javax.sound.midi.spi

Methods in javax.sound.midi.spi that return Soundbank
abstract Soundbank | SoundbankReader.getSoundbank(File file) Obtains a soundbank object from the File provided.
abstract Soundbank | SoundbankReader.getSoundbank(InputStream stream) Obtains a soundbank object from the InputStream provided.
abstract Soundbank | SoundbankReader.getSoundbank(URL url) Obtains a soundbank object from the URL provided.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sound.midi.Synthesizer

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sound.midi.Synthesizer

Packages that use Synthesizer
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of Synthesizer in javax.sound.midi

Methods in javax.sound.midi that return Synthesizer
static Synthesizer MidiSystem.getSynthesizer()
Obtains the default synthesizer.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sound.midi.Transmitter

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sound.midi.Transmitter

Packages that use Transmitter
javax.sound.midi Provides interfaces and classes for I/O, sequencing, and synthesis of MIDI (Musical Instrument Digital Interface) data.

Uses of Transmitter in javax.sound.midi

Methods in javax.sound.midi that return Transmitter
static Transmitter | MidiSystem.getTransmitter() Obtains a MIDI transmitter from an external MIDI port or other default source.
Transmitter | MidiDevice.getTransmitter() Obtains a MIDI OUT connection from which the MIDI device will transmit MIDI data The returned transmitter must be closed when the application has finished using it.

Methods in javax.sound.midi that return types with arguments of type Transmitter
 List<Transmitter> MidiDevice.getTransmitters()
Returns all currently active, non-closed transmitters connected with this MidiDevice.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ControllerEventListener

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Interface ControllerEventListener

All Superinterfaces:
EventListener
public interface ControllerEventListener
extends EventListener

The ControllerEventListener interface should be implemented by classes whose instances need to be notified when a Sequencer has processed a requested type of MIDI control-change event. To register a ControllerEventListener object to receive such notifications, invoke the addControllerEventListener method of Sequencer, specifying the types of MIDI controllers about which you are interested in getting control-change notifications.

See Also:
MidiChannel.controlChange(int, int)

Method Summary
 void controlChange(ShortMessage event)
Invoked when a Sequencer has encountered and processed a control-change event of interest to this listener.

Method Detail

controlChange

void controlChange(ShortMessage event)
Invoked when a Sequencer has encountered and processed a control-change event of interest to this listener. The event passed in is a ShortMessage whose first data byte indicates the controller number and whose second data byte is the value to which the controller was set.

Parameters:
event - the control-change event that the sequencer encountered in the sequence it is processing
See Also:
Sequencer.addControllerEventListener(ControllerEventListener, int[]),
MidiChannel.controlChange(int, int),
ShortMessage.getData1(),
ShortMessage.getData2()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Instrument

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Class Instrument

java.lang.Object
    extended by  javax.sound.midi.SoundbankResource
        extended by  javax.sound.midi.Instrument

public abstract class Instrument
extends SoundbankResource

An instrument is a sound-synthesis algorithm with certain parameter settings, usually designed to emulate a specific real-world musical instrument or to achieve a specific sort of sound effect. Instruments are typically stored in collections called soundbanks. Before the instrument can be used to play notes, it must first be loaded onto a synthesizer, and then it must be selected for use on one or more channels, via a program-change command. MIDI notes that are subsequently received on those channels will be played using the sound of the selected instrument.

See Also:
Soundbank, Soundbank.getInstruments(), Patch, Synthesizer.loadInstrument(Instrument), MidiChannel.programChange(int, int)

Constructor Summary
protected Instrument(Soundbank soundbank, Patch patch, String name, Class<?> dataClass)
Constructs a new MIDI instrument from the specified Patch.
Method Summary
 Patch getPatch()
Obtains the Patch object that indicates the bank and program numbers where this instrument is to be stored in the synthesizer.
Methods inherited from class javax.sound.midi.SoundbankResource
getData, getDataClass, getName, getSoundbank
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Instrument

protected Instrument(Soundbank soundbank,
                     Patch patch,
                     String name,
                     Class<?> dataClass)
Constructs a new MIDI instrument from the specified Patch. When a subsequent request is made to load the instrument, the sound bank will search its contents for this instrument's Patch, and the instrument will be loaded into the synthesizer at the bank and program location indicated by the Patch object.

Parameters:
soundbank - sound bank containing the instrument
patch - the patch of this instrument
name - the name of this instrument
dataClass - the class used to represent the sample's data.
See Also:
Synthesizer.loadInstrument(Instrument)
Method Detail

getPatch

public Patch getPatch()
Obtains the Patch object that indicates the bank and program numbers where this instrument is to be stored in the synthesizer.

Returns:
this instrument's patch
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidMidiDataException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Class InvalidMidiDataException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.sound.midi.InvalidMidiDataException
All Implemented Interfaces:
Serializable
public class InvalidMidiDataException
extends Exception

An InvalidMidiDataException indicates that inappropriate MIDI data was encountered. This often means that the data is invalid in and of itself, from the perspective of the MIDI specification. An example would be an undefined status byte. However, the exception might simply mean that the data was invalid in the context it was used, or that the object to which the data was given was unable to parse or use it. For example, a file reader might not be able to parse a Type 2 MIDI file, even though that format is defined in the MIDI specification.

See Also:
Serialized Form

Constructor Summary
InvalidMidiDataException()
Constructs an InvalidMidiDataException with null for its error detail message.
InvalidMidiDataException(String message)
Constructs an InvalidMidiDataException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidMidiDataException

public InvalidMidiDataException()
Constructs an InvalidMidiDataException with null for its error detail message.

InvalidMidiDataException

public InvalidMidiDataException(String message)
Constructs an InvalidMidiDataException with the specified detail message.

Parameters:
message - the string to display as an error detail message
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetaEventListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Interface MetaEventListener

All Superinterfaces:
EventListener
public interface MetaEventListener
extends EventListener

The MetaEventListener interface should be implemented by classes whose instances need to be notified when a Sequencer has processed a MetaMessage. To register a MetaEventListener object to receive such notifications, pass it as the argument to the addMetaEventListener method of Sequencer.

Method Summary
 void meta(MetaMessage meta)
Invoked when a Sequencer has encountered and processed a MetaMessage in the Sequence it is processing.

Method Detail

meta

void meta(MetaMessage meta)
Invoked when a Sequencer has encountered and processed a MetaMessage in the Sequence it is processing.

Parameters:
meta - the meta-message that the sequencer encountered
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetaMessage

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Class MetaMessage

java.lang.Object
    extended by  javax.sound.midi.MidiMessage
        extended by  javax.sound.midi.MetaMessage
All Implemented Interfaces:
Cloneable
public class MetaMessage
extends MidiMessage

A MetaMessage is a MidiMessage that is not meaningful to synthesizers, but that can be stored in a MIDI file and interpreted by a sequencer program. (See the discussion in the MidiMessage class description.) The Standard MIDI Files specification defines various types of meta-events, such as sequence number, lyric, cue point, and set tempo. There are also meta-events for such information as lyrics, copyrights, tempo indications, time and key signatures, markers, etc. For more information, see the Standard MIDI Files 1.0 specification, which is part of the Complete MIDI 1.0 Detailed Specification published by the MIDI Manufacturer's Association (http://www.midi.org).

When data is being transported using MIDI wire protocol, a ShortMessage with the status value 0xFF represents a system reset message. In MIDI files, this same status value denotes a MetaMessage. The types of meta-message are distinguished from each other by the first byte that follows the status byte 0xFF. The subsequent bytes are data bytes. As with system exclusive messages, there are an arbitrary number of data bytes, depending on the type of MetaMessage.

See Also:
MetaEventListener

Field Summary
static int META
Status byte for MetaMessage (0xFF, or 255), which is used in MIDI files.
Fields inherited from class javax.sound.midi.MidiMessage
data, length
Constructor Summary
 | MetaMessage() Constructs a new MetaMessage.
protected | MetaMessage(byte[] data) Constructs a new MetaMessage.
Method Summary
Object | clone() Creates a new object of the same class and with the same contents as this object.
byte[] | getData() Obtains a copy of the data for the meta message.
int | getType() Obtains the type of the MetaMessage.
void | setMessage(int type, byte[] data, int length) Sets the message parameters for a MetaMessage.
Methods inherited from class javax.sound.midi.MidiMessage
getLength, getMessage, getStatus, setMessage
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

META

public static final int META
Status byte for MetaMessage (0xFF, or 255), which is used in MIDI files. It has the same value as SYSTEM_RESET, which is used in the real-time "MIDI wire" protocol.

See Also:
MidiMessage.getStatus(), Constant Field Values
Constructor Detail

MetaMessage

public MetaMessage()
Constructs a new MetaMessage. The contents of the message are not set here; use setMessage to set them subsequently.

MetaMessage

protected MetaMessage(byte[] data)
Constructs a new MetaMessage.

Parameters:
data - an array of bytes containing the complete message. The message data may be changed using the setMessage method.
See Also:
setMessage(int, byte[], int)
Method Detail

setMessage

public void setMessage(int type,
                       byte[] data,
                       int length)
                throws InvalidMidiDataException
Sets the message parameters for a MetaMessage. Since only one status byte value, 0xFF, is allowed for meta-messages, it does not need to be specified here. Calls to getStatus return 0xFF for all meta-messages.

The type argument should be a valid value for the byte that follows the status byte in the MetaMessage. The data argument should contain all the subsequent bytes of the MetaMessage. In other words, the byte that specifies the type of MetaMessage is not considered a data byte.

Parameters:
type - meta-message type (must be less than 128)
data - the data bytes in the MIDI message
length - the number of bytes in the data byte array
Throws:
InvalidMidiDataException - if the parameter values do not specify a valid MIDI meta message
InvalidMidiDataException

getType

public int getType()
Obtains the type of the MetaMessage.

Returns:
an integer representing the MetaMessage type

getData

public byte[] getData()
Obtains a copy of the data for the meta message. The returned array of bytes does not include the status byte or the message length data. The length of the data for the meta message is the length of the array. Note that the length of the entire message includes the status byte and the meta message type byte, and therefore may be longer than the returned array.

Returns:
array containing the meta message data.
See Also:
MidiMessage.getLength()

clone

public Object clone()
Creates a new object of the same class and with the same contents as this object.

Specified by:
clone in class MidiMessage
Returns:
a clone of this instance
See Also:
Cloneable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MidiChannel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Interface MidiChannel

public interface MidiChannel

A MidiChannel object represents a single MIDI channel. Generally, each MidiChannel method processes a like-named MIDI "channel voice" or "channel mode" message as defined by the MIDI specification. However, MidiChannel adds some "get" methods that retrieve the value most recently set by one of the standard MIDI channel messages. Similarly, methods for per-channel solo and mute have been added.

A Synthesizer object has a collection of MidiChannels, usually one for each of the 16 channels prescribed by the MIDI 1.0 specification. The Synthesizer generates sound when its MidiChannels receive noteOn messages.

See the MIDI 1.0 Specification for more information about the prescribed behavior of the MIDI channel messages, which are not exhaustively documented here. The specification is titled MIDI Reference: The Complete MIDI 1.0 Detailed Specification, and is published by the MIDI Manufacturer's Association ( http://www.midi.org).

MIDI was originally a protocol for reporting the gestures of a keyboard musician. This genesis is visible in the MidiChannel API, which preserves such MIDI concepts as key number, key velocity, and key pressure. It should be understood that the MIDI data does not necessarily originate with a keyboard player (the source could be a different kind of musician, or software). Some devices might generate constant values for velocity and pressure, regardless of how the note was performed. Also, the MIDI specification often leaves it up to the synthesizer to use the data in the way the implementor sees fit. For example, velocity data need not always be mapped to volume and/or brightness.

See Also:
Synthesizer.getChannels()

Method Summary
void | allNotesOff() Turns off all notes that are currently sounding on this channel.
void | allSoundOff() Immediately turns off all sounding notes on this channel, ignoring the state of the Hold Pedal and the internal decay rate of the current Instrument.
void | controlChange(int controller, int value) Reacts to a change in the specified controller's value.
int | getChannelPressure() Obtains the channel's keyboard pressure.
int | getController(int controller) Obtains the current value of the specified controller.
boolean | getMono() Obtains the current mono/poly mode.
boolean | getMute() Obtains the current mute state for this channel.
boolean | getOmni() Obtains the current omni mode.
int | getPitchBend() Obtains the upward or downward pitch offset for this channel.
int | getPolyPressure(int noteNumber) Obtains the pressure with which the specified key is being depressed.
int | getProgram() Obtains the current program number for this channel.
boolean | getSolo() Obtains the current solo state for this channel.
boolean | localControl(boolean on) Turns local control on or off.
void | noteOff(int noteNumber) Turns the specified note off.
void | noteOff(int noteNumber, int velocity) Turns the specified note off.
void | noteOn(int noteNumber, int velocity) Starts the specified note sounding.
void | programChange(int program) Changes a program (patch).
void | programChange(int bank, int program) Changes the program using bank and program (patch) numbers.
void | resetAllControllers() Resets all the implemented controllers to their default values.
void | setChannelPressure(int pressure) Reacts to a change in the keyboard pressure.
void | setMono(boolean on) Turns mono mode on or off.
void | setMute(boolean mute) Sets the mute state for this channel.
void | setOmni(boolean on) Turns omni mode on or off.
void | setPitchBend(int bend) Changes the pitch offset for all notes on this channel.
void | setPolyPressure(int noteNumber, int pressure) Reacts to a change in the specified note's key pressure.
void | setSolo(boolean soloState) Sets the solo state for this channel.

Method Detail

noteOn

void noteOn(int noteNumber,
            int velocity)
Starts the specified note sounding. The key-down velocity usually controls the note's volume and/or brightness. If velocity is zero, this method instead acts like noteOff(int), terminating the note.

Parameters:
noteNumber - the MIDI note number, from 0 to 127 (60 = Middle C)
velocity - the speed with which the key was depressed
See Also:
noteOff(int, int)

noteOff

void noteOff(int noteNumber,
             int velocity)
Turns the specified note off. The key-up velocity, if not ignored, can be used to affect how quickly the note decays. In any case, the note might not die away instantaneously; its decay rate is determined by the internals of the Instrument. If the Hold Pedal (a controller; see controlChange) is down, the effect of this method is deferred until the pedal is released.

Parameters:
noteNumber - the MIDI note number, from 0 to 127 (60 = Middle C)
velocity - the speed with which the key was released
See Also:
noteOff(int),
noteOn(int, int),
allNotesOff(),
allSoundOff()

noteOff

void noteOff(int noteNumber)
Turns the specified note off.

Parameters:
noteNumber - the MIDI note number, from 0 to 127 (60 = Middle C)
See Also:
noteOff(int, int)

setPolyPressure

void setPolyPressure(int noteNumber,
                     int pressure)
Reacts to a change in the specified note's key pressure. Polyphonic key pressure allows a keyboard player to press multiple keys simultaneously, each with a different amount of pressure. The pressure, if not ignored, is typically used to vary such features as the volume, brightness, or vibrato of the note. It is possible that the underlying synthesizer does not support this MIDI message. In order to verify that setPolyPressure was successful, use getPolyPressure.

Parameters:
noteNumber - the MIDI note number, from 0 to 127 (60 = Middle C)
pressure - value for the specified key, from 0 to 127 (127 = maximum pressure)
See Also:
getPolyPressure(int)

getPolyPressure

int getPolyPressure(int noteNumber)
Obtains the pressure with which the specified key is being depressed.

Parameters:
noteNumber - the MIDI note number, from 0 to 127 (60 = Middle C) If the device does not support setting poly pressure, this method always returns 0. Calling setPolyPressure will have no effect then.
Returns:
the amount of pressure for that note, from 0 to 127 (127 = maximum pressure)
See Also:
setPolyPressure(int, int)

setChannelPressure

void setChannelPressure(int pressure)
Reacts to a change in the keyboard pressure. Channel pressure indicates how hard the keyboard player is depressing the entire keyboard. This can be the maximum or average of the per-key pressure-sensor values, as set by setPolyPressure. More commonly, it is a measurement of a single sensor on a device that doesn't implement polyphonic key pressure. Pressure can be used to control various aspects of the sound, as described under setPolyPressure. It is possible that the underlying synthesizer does not support this MIDI message. In order to verify that setChannelPressure was successful, use getChannelPressure.

Parameters:
pressure - the pressure with which the keyboard is being depressed, from 0 to 127 (127 = maximum pressure)
See Also:
setPolyPressure(int, int), getChannelPressure()

getChannelPressure

int getChannelPressure()
Obtains the channel's keyboard pressure. If the device does not support setting channel pressure, this method always returns 0. Calling setChannelPressure will have no effect then.

Returns:
the amount of pressure for that note, from 0 to 127 (127 = maximum pressure)
See Also:
setChannelPressure(int)

controlChange

void controlChange(int controller,
                   int value)
Reacts to a change in the specified controller's value. A controller is some control other than a keyboard key, such as a switch, slider, pedal, wheel, or breath-pressure sensor. The MIDI 1.0 Specification provides standard numbers for typical controllers on MIDI devices, and describes the intended effect for some of the controllers. The way in which an Instrument reacts to a controller change may be specific to the Instrument.

The MIDI 1.0 Specification defines both 7-bit controllers and 14-bit controllers. Continuous controllers, such as wheels and sliders, typically have 14 bits (two MIDI bytes), while discrete controllers, such as switches, typically have 7 bits (one MIDI byte). Refer to the specification to see the expected resolution for each type of control.

Controllers 64 through 95 (0x40 - 0x5F) allow 7-bit precision. The value of a 7-bit controller is set completely by the value argument. An additional set of controllers provide 14-bit precision by using two controller numbers, one for the most significant 7 bits and another for the least significant 7 bits. Controller numbers 0 through 31 (0x00 - 0x1F) control the most significant 7 bits of 14-bit controllers; controller numbers 32 through 63 (0x20 - 0x3F) control the least significant 7 bits of these controllers. For example, controller number 7 (0x07) controls the upper 7 bits of the channel volume controller, and controller number 39 (0x27) controls the lower 7 bits. The value of a 14-bit controller is determined by the interaction of the two halves. When the most significant 7 bits of a controller are set (using controller numbers 0 through 31), the lower 7 bits are automatically set to 0. The corresponding controller number for the lower 7 bits may then be used to further modulate the controller value. It is possible that the underlying synthesizer does not support a specific controller message. In order to verify that a call to controlChange was successful, use getController.

Parameters:
controller - the controller number (0 to 127; see the MIDI 1.0 Specification for the interpretation)
value - the value to which the specified controller is changed (0 to 127)
See Also:
getController(int)

getController

int getController(int controller)
Obtains the current value of the specified controller. The return value is represented with 7 bits. For 14-bit controllers, the MSB and LSB controller value needs to be obtained separately. For example, the 14-bit value of the volume controller can be calculated by multiplying the value of controller 7 (0x07, channel volume MSB) with 128 and adding the value of controller 39 (0x27, channel volume LSB). If the device does not support setting a specific controller, this method returns 0 for that controller. Calling controlChange will have no effect then.

Parameters:
controller - the number of the controller whose value is desired. The allowed range is 0-127; see the MIDI 1.0 Specification for the interpretation.
Returns:
the current value of the specified controller (0 to 127)
See Also:
controlChange(int, int)

programChange

void programChange(int program)
Changes a program (patch). This selects a specific instrument from the currently selected bank of instruments.

The MIDI specification does not dictate whether notes that are already sounding should switch to the new instrument (timbre) or continue with their original timbre until terminated by a note-off.

The program number is zero-based (expressed from 0 to 127). Note that MIDI hardware displays and literature about MIDI typically use the range 1 to 128 instead. It is possible that the underlying synthesizer does not support a specific program. In order to verify that a call to programChange was successful, use getProgram.

Parameters:
program - the program number to switch to (0 to 127)
See Also:
programChange(int, int), getProgram()

programChange

void programChange(int bank,
                   int program)
Changes the program using bank and program (patch) numbers. It is possible that the underlying synthesizer does not support a specific bank, or program. In order to verify that a call to programChange was successful, use getProgram and getController. Since banks are changed by way of control changes, you can verify the current bank with the following statement:
   int bank = (getController(0) * 128)
              + getController(32);

Parameters:
bank - the bank number to switch to (0 to 16383)
program - the program (patch) to use in the specified bank (0 to 127)
See Also:
programChange(int), getProgram()

getProgram

int getProgram()
Obtains the current program number for this channel.

Returns:
the program number of the currently selected patch
See Also:
Patch.getProgram(),
Synthesizer.loadInstrument(javax.sound.midi.Instrument),
programChange(int)

setPitchBend

void setPitchBend(int bend)
Changes the pitch offset for all notes on this channel. This affects all currently sounding notes as well as subsequent ones. (For pitch bend to cease, the value needs to be reset to the center position.)

The MIDI specification stipulates that pitch bend be a 14-bit value, where zero is maximum downward bend, 16383 is maximum upward bend, and 8192 is the center (no pitch bend). The actual amount of pitch change is not specified; it can be changed by a pitch-bend sensitivity setting. However, the General MIDI specification says that the default range should be two semitones up and down from center. It is possible that the underlying synthesizer does not support this MIDI message. In order to verify that setPitchBend was successful, use getPitchBend.

Parameters:
bend - the amount of pitch change, as a nonnegative 14-bit value (8192 = no bend)
See Also:
getPitchBend()

getPitchBend

int getPitchBend()
Obtains the upward or downward pitch offset for this channel. If the device does not support setting pitch bend, this method always returns 8192. Calling setPitchBend will have no effect then.

Returns:
bend amount, as a nonnegative 14-bit value (8192 = no bend)
See Also:
setPitchBend(int)

resetAllControllers

void resetAllControllers()
Resets all the implemented controllers to their default values.

See Also:
controlChange(int, int)

allNotesOff

void allNotesOff()
Turns off all notes that are currently sounding on this channel. The notes might not die away instantaneously; their decay rate is determined by the internals of the Instrument. If the Hold Pedal controller (see controlChange) is down, the effect of this method is deferred until the pedal is released.

See Also:
allSoundOff(), noteOff(int)

allSoundOff

void allSoundOff()
Immediately turns off all sounding notes on this channel, ignoring the state of the Hold Pedal and the internal decay rate of the current Instrument.

See Also:
allNotesOff()

localControl

boolean localControl(boolean on)
Turns local control on or off. The default is for local control to be on. The "on" setting means that if a device is capable of both synthesizing sound and transmitting MIDI messages, it will synthesize sound in response to the note-on and note-off messages that it itself transmits. It will also respond to messages received from other transmitting devices. The "off" setting means that the synthesizer will ignore its own transmitted MIDI messages, but not those received from other devices. It is possible that the underlying synthesizer does not support local control. In order to verify that a call to localControl was successful, check the return value.

Parameters:
on - true to turn local control on, false to turn local control off
Returns:
the new local-control value, or false if local control is not supported

setMono

void setMono(boolean on)
Turns mono mode on or off. In mono mode, the channel synthesizes only one note at a time. In poly mode (identical to mono mode off), the channel can synthesize multiple notes simultaneously. The default is mono off (poly mode on).

"Mono" is short for the word "monophonic," which in this context is opposed to the word "polyphonic" and refers to a single synthesizer voice per MIDI channel. It has nothing to do with how many audio channels there might be (as in "monophonic" versus "stereophonic" recordings). It is possible that the underlying synthesizer does not support mono mode. In order to verify that a call to setMono was successful, use getMono.

Parameters:
on - true to turn mono mode on, false to turn it off (which means turning poly mode on).
See Also:
getMono(), VoiceStatus

getMono

boolean getMono()
Obtains the current mono/poly mode. Synthesizers that do not allow changing mono/poly mode will always return the same value, regardless of calls to setMono.

Returns:
true if mono mode is on, otherwise false (meaning poly mode is on).
See Also:
setMono(boolean)

setOmni

void setOmni(boolean on)
Turns omni mode on or off. In omni mode, the channel responds to messages sent on all channels. When omni is off, the channel responds only to messages sent on its channel number. The default is omni off. It is possible that the underlying synthesizer does not support omni mode. In order to verify that setOmni was successful, use getOmni.

Parameters:
on - true to turn omni mode on, false to turn it off.
See Also:
getOmni(), VoiceStatus

getOmni

boolean getOmni()
Obtains the current omni mode. Synthesizers that do not allow changing the omni mode will always return the same value, regardless of calls to setOmni.

Returns:
true if omni mode is on, otherwise false (meaning omni mode is off).
See Also:
setOmni(boolean)

setMute

void setMute(boolean mute)
Sets the mute state for this channel. A value of true means the channel is to be muted, false means the channel can sound (if other channels are not soloed).

Unlike allSoundOff(), this method applies to only a specific channel, not to all channels. Further, it silences not only currently sounding notes, but also subsequently received notes. It is possible that the underlying synthesizer does not support muting channels. In order to verify that a call to setMute was successful, use getMute.

Parameters:
mute - the new mute state
See Also:
getMute(), setSolo(boolean)

getMute

boolean getMute()
Obtains the current mute state for this channel. If the underlying synthesizer does not support muting this channel, this method always returns false.

Returns:
true the channel is muted, or false if not
See Also:
setMute(boolean)

setSolo

void setSolo(boolean soloState)
Sets the solo state for this channel. If solo is true only this channel and other soloed channels will sound. If solo is false then only other soloed channels will sound, unless no channels are soloed, in which case all unmuted channels will sound. It is possible that the underlying synthesizer does not support solo channels. In order to verify that a call to setSolo was successful, use getSolo.

Parameters:
soloState - new solo state for the channel
See Also:
getSolo()

getSolo

boolean getSolo()
Obtains the current solo state for this channel. If the underlying synthesizer does not support solo on this channel, this method always returns false.

Returns:
true the channel is solo, or false if not
See Also:
setSolo(boolean)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MidiDevice

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Interface MidiDevice

All Known Subinterfaces:
Sequencer, Synthesizer
public interface MidiDevice

MidiDevice is the base interface for all MIDI devices. Common devices include synthesizers, sequencers, MIDI input ports, and MIDI output ports.

A MidiDevice can be a transmitter or a receiver of MIDI events, or both. Therefore, it can provide Transmitter or Receiver instances (or both). Typically, MIDI IN ports provide transmitters, MIDI OUT ports and synthesizers provide receivers. A Sequencer typically provides transmitters for playback and receivers for recording.

A MidiDevice can be opened and closed explicitly as well as implicitly. Explicit opening is accomplished by calling open(), explicit closing is done by calling close() on the MidiDevice instance. If an application opens a MidiDevice explicitly, it has to close it explicitly to free system resources and enable the application to exit cleanly. Implicit opening is done by calling MidiSystem.getReceiver and MidiSystem.getTransmitter. The MidiDevice used by MidiSystem.getReceiver and MidiSystem.getTransmitter is implementation-dependant unless the properties javax.sound.midi.Receiver and javax.sound.midi.Transmitter are used (see the description of properties to select default providers in MidiSystem). A MidiDevice that was opened implicitly, is closed implicitly by closing the Receiver or Transmitter that resulted in opening it. If more than one implicitly opening Receiver or Transmitter were obtained by the application, the decive is closed after the last Receiver or Transmitter has been closed. On the other hand, calling getReceiver or getTransmitter on the device instance directly does not open the device implicitly. Closing these Transmitters and Receivers does not close the device implicitly. To use a device with Receivers or Transmitters obtained this way, the device has to be opened and closed explicitly.

If implicit and explicit opening and closing are mixed on the same MidiDevice instance, the following rules apply:

  • After an explicit open (either before or after implicit opens), the device will not be closed by implicit closing. The only way to close an explicitly opened device is an explicit close.
  • An explicit close always closes the device, even if it also has been opened implicitly. A subsequent implicit close has no further effect.
To detect if a MidiDevice represents a hardware MIDI port, the following programming technique can be used:
 MidiDevice device = ...;
 if ( ! (device instanceof Sequencer) && ! (device instanceof Synthesizer)) {
   // we're now sure that device represents a MIDI port
   // ...
 }

A MidiDevice includes a MidiDevice.Info object to provide manufacturer information and so on.

See Also:
Synthesizer, Sequencer, Receiver, Transmitter

Nested Class Summary
static class MidiDevice.Info
A MidiDevice.Info object contains assorted data about a MidiDevice, including its name, the company who created it, and descriptive text.
Method Summary
void | close() Closes the device, indicating that the device should now release any system resources it is using.
MidiDevice.Info | getDeviceInfo() Obtains information about the device, including its Java class and Strings containing its name, vendor, and description.
int | getMaxReceivers() Obtains the maximum number of MIDI IN connections available on this MIDI device for receiving MIDI data.
int | getMaxTransmitters() Obtains the maximum number of MIDI OUT connections available on this MIDI device for transmitting MIDI data.
long | getMicrosecondPosition() Obtains the current time-stamp of the device, in microseconds.
Receiver | getReceiver() Obtains a MIDI IN receiver through which the MIDI device may receive MIDI data.
List<Receiver> | getReceivers() Returns all currently active, non-closed receivers connected with this MidiDevice.
Transmitter | getTransmitter() Obtains a MIDI OUT connection from which the MIDI device will transmit MIDI data The returned transmitter must be closed when the application has finished using it.
List<Transmitter> | getTransmitters() Returns all currently active, non-closed transmitters connected with this MidiDevice.
boolean | isOpen() Reports whether the device is open.
void | open() Opens the device, indicating that it should now acquire any system resources it requires and become operational.

Method Detail

getDeviceInfo

MidiDevice.Info getDeviceInfo()
Obtains information about the device, including its Java class and Strings containing its name, vendor, and description.

Returns:
device info

open

void open()
          throws MidiUnavailableException
Opens the device, indicating that it should now acquire any system resources it requires and become operational.

An application opening a device explicitly with this call has to close the device by calling close(). This is necessary to release system resources and allow applications to exit cleanly.

Note that some devices, once closed, cannot be reopened. Attempts to reopen such a device will always result in a MidiUnavailableException.

Throws:
MidiUnavailableException - thrown if the device cannot be opened due to resource restrictions.
SecurityException - thrown if the device cannot be opened due to security restrictions.
See Also:
close(), isOpen()

close

void close()
Closes the device, indicating that the device should now release any system resources it is using.

All Receiver and Transmitter instances open from this device are closed. This includes instances retrieved via MidiSystem.

See Also:
open(), isOpen()

isOpen

boolean isOpen()
Reports whether the device is open.

Returns:
true if the device is open, otherwise false
See Also:
open(), close()

getMicrosecondPosition

long getMicrosecondPosition()
Obtains the current time-stamp of the device, in microseconds. If a device supports time-stamps, it should start counting at 0 when the device is opened and continue incrementing its time-stamp in microseconds until the device is closed. If it does not support time-stamps, it should always return -1.

Returns:
the current time-stamp of the device in microseconds, or -1 if time-stamping is not supported by the device.

getMaxReceivers

int getMaxReceivers()
Obtains the maximum number of MIDI IN connections available on this MIDI device for receiving MIDI data.

Returns:
maximum number of MIDI IN connections, or -1 if an unlimited number of connections is available.

getMaxTransmitters

int getMaxTransmitters()
Obtains the maximum number of MIDI OUT connections available on this MIDI device for transmitting MIDI data.

Returns:
maximum number of MIDI OUT connections, or -1 if an unlimited number of connections is available.

getReceiver

Receiver getReceiver()
                     throws MidiUnavailableException
Obtains a MIDI IN receiver through which the MIDI device may receive MIDI data. The returned receiver must be closed when the application has finished using it.

Obtaining a Receiver with this method does not open the device. To be able to use the device, it has to be opened explicitly by calling open(). Also, closing the Receiver does not close the device. It has to be closed explicitly by calling close().

Returns:
a receiver for the device.
Throws:
MidiUnavailableException - thrown if a receiver is not available due to resource restrictions
See Also:
Receiver.close()

getReceivers

List<Receiver> getReceivers()
Returns all currently active, non-closed receivers connected with this MidiDevice. A receiver can be removed from the device by closing it.

Returns:
an unmodifiable list of the open receivers
Since:
1.5

getTransmitter

Transmitter getTransmitter()
                           throws MidiUnavailableException
Obtains a MIDI OUT connection from which the MIDI device will transmit MIDI data The returned transmitter must be closed when the application has finished using it.

Obtaining a Transmitter with this method does not open the device. To be able to use the device, it has to be opened explicitly by calling open(). Also, closing the Transmitter does not close the device. It has to be closed explicitly by calling close().

Returns:
a MIDI OUT transmitter for the device.
Throws:
MidiUnavailableException - thrown if a transmitter is not available due to resource restrictions
See Also:
Transmitter.close()

getTransmitters

List<Transmitter> getTransmitters()
Returns all currently active, non-closed transmitters connected with this MidiDevice. A transmitter can be removed from the device by closing it.

Returns:
an unmodifiable list of the open transmitters
Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MidiDevice.Info

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Class MidiDevice.Info

java.lang.Object
    extended by  javax.sound.midi.MidiDevice.Info
Enclosing interface:
MidiDevice
public static class MidiDevice.Info
extends Object

A MidiDevice.Info object contains assorted data about a MidiDevice, including its name, the company who created it, and descriptive text.

See Also:
MidiDevice.getDeviceInfo()

Constructor Summary
protected MidiDevice.Info(String name, String vendor, String description, String version)
Constructs a device info object.
Method Summary
boolean | equals(Object obj) Reports whether two objects are equal.
String | getDescription() Obtains the description of the device.
String | getName() Obtains the name of the device.
String | getVendor() Obtains the name of the company who supplies the device.
String | getVersion() Obtains the version of the device.
int | hashCode() Finalizes the hashcode method.
String | toString() Provides a string representation of the device information.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

MidiDevice.Info

protected MidiDevice.Info(String name,
                          String vendor,
                          String description,
                          String version)
Constructs a device info object.

Parameters:
name - the name of the device
vendor - the name of the company who provides the device
description - a description of the device
version - version information for the device
Method Detail

equals

public final boolean equals(Object obj)
Reports whether two objects are equal. Returns true if the objects are identical.

Overrides:
equals in class Object
Parameters:
obj - the reference object with which to compare this object
Returns:
true if this object is the same as the obj argument; false otherwise
See Also:
Object.hashCode(), Hashtable

hashCode

public final int hashCode()
Finalizes the hashcode method.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

getName

public final String getName()
Obtains the name of the device.

Returns:
a string containing the device's name

getVendor

public final String getVendor()
Obtains the name of the company who supplies the device.

Returns:
device the vendor's name

getDescription

public final String getDescription()
Obtains the description of the device.

Returns:
a description of the device

getVersion

public final String getVersion()
Obtains the version of the device.

Returns:
textual version information for the device.

toString

public final String toString()
Provides a string representation of the device information.

Overrides:
toString in class Object
Returns:
a description of the info object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MidiEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Class MidiEvent

java.lang.Object
    extended by  javax.sound.midi.MidiEvent

public class MidiEvent
extends Object

MIDI events contain a MIDI message and a corresponding time-stamp expressed in ticks, and can represent the MIDI event information stored in a MIDI file or a Sequence object. The duration of a tick is specified by the timing information contained in the MIDI file or Sequence object.

In Java Sound, MidiEvent objects are typically contained in a Track, and Tracks are likewise contained in a Sequence.

Constructor Summary
MidiEvent(MidiMessage message, long tick)
Constructs a new MidiEvent.
Method Summary
MidiMessage | getMessage() Obtains the MIDI message contained in the event.
long | getTick() Obtains the time-stamp for the event, in MIDI ticks
void | setTick(long tick) Sets the time-stamp for the event, in MIDI ticks
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MidiEvent

public MidiEvent(MidiMessage message,
                 long tick)
Constructs a new MidiEvent.

Parameters:
message - the MIDI message contained in the event
tick - the time-stamp for the event, in MIDI ticks
Method Detail

getMessage

public MidiMessage getMessage()
Obtains the MIDI message contained in the event.

Returns:
the MIDI message

setTick

public void setTick(long tick)
Sets the time-stamp for the event, in MIDI ticks

Parameters:
tick - the new time-stamp, in MIDI ticks

getTick

public long getTick()
Obtains the time-stamp for the event, in MIDI ticks

Returns:
the time-stamp for the event, in MIDI ticks
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MidiFileFormat

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Class MidiFileFormat

java.lang.Object
    extended by  javax.sound.midi.MidiFileFormat

public class MidiFileFormat
extends Object

A MidiFileFormat object encapsulates a MIDI file's type, as well as its length and timing information.

A MidiFileFormat object can include a set of properties. A property is a pair of key and value: the key is of type String, the associated property value is an arbitrary object. Properties specify additional informational meta data (like a author, or copyright). Properties are optional information, and file reader and file writer implementations are not required to provide or recognize properties.

The following table lists some common properties that should be used in implementations:
Property key | Value type | Description
"author" | String | name of the author of this file
"title" | String | title of this file
"copyright" | String | copyright message
"date" | Date | date of the recording or release
"comment" | String | an arbitrary text

See Also:
MidiSystem.getMidiFileFormat(java.io.File), Sequencer.setSequence(java.io.InputStream stream)

Field Summary
protected int | byteLength The length of the MIDI file in bytes.
protected float | divisionType The division type of the MIDI file.
protected long | microsecondLength The duration of the MIDI file in microseconds.
protected int | resolution The timing resolution of the MIDI file.
protected int | type The type of MIDI file.
static int | UNKNOWN_LENGTH Represents unknown length.
Constructor Summary
MidiFileFormat(int type, float divisionType, int resolution, int bytes, long microseconds)
Constructs a MidiFileFormat.
MidiFileFormat(int type, float divisionType, int resolution, int bytes, long microseconds, Map<String,Object> properties)
Construct a MidiFileFormat with a set of properties.
Method Summary
int | getByteLength() Obtains the length of the MIDI file, expressed in 8-bit bytes.
float | getDivisionType() Obtains the timing division type for the MIDI file.
long | getMicrosecondLength() Obtains the length of the MIDI file, expressed in microseconds.
Object | getProperty(String key) Obtain the property value specified by the key.
int | getResolution() Obtains the timing resolution for the MIDI file.
int | getType() Obtains the MIDI file type.
Map<String,Object> | properties() Obtain an unmodifiable map of properties.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

UNKNOWN_LENGTH

public static final int UNKNOWN_LENGTH
Represents unknown length.

See Also:
getByteLength(), getMicrosecondLength(), Constant Field Values

type

protected int type
The type of MIDI file.

divisionType

protected float divisionType
The division type of the MIDI file.

See Also:
Sequence.PPQ, Sequence.SMPTE_24, Sequence.SMPTE_25, Sequence.SMPTE_30DROP, Sequence.SMPTE_30

resolution

protected int resolution
The timing resolution of the MIDI file.

byteLength

protected int byteLength
The length of the MIDI file in bytes.

microsecondLength

protected long microsecondLength
The duration of the MIDI file in microseconds.

Constructor Detail

MidiFileFormat

public MidiFileFormat(int type,
                      float divisionType,
                      int resolution,
                      int bytes,
                      long microseconds)
Constructs a MidiFileFormat.

Parameters:
type - the MIDI file type (0, 1, or 2)
divisionType - the timing division type (PPQ or one of the SMPTE types)
resolution - the timing resolution
bytes - the length of the MIDI file in bytes, or UNKNOWN_LENGTH if not known
microseconds - the duration of the file in microseconds, or UNKNOWN_LENGTH if not known
See Also:
UNKNOWN_LENGTH, Sequence.PPQ, Sequence.SMPTE_24, Sequence.SMPTE_25, Sequence.SMPTE_30DROP, Sequence.SMPTE_30

MidiFileFormat

public MidiFileFormat(int type,
                      float divisionType,
                      int resolution,
                      int bytes,
                      long microseconds,
                      Map<String,Object> properties)
Construct a MidiFileFormat with a set of properties.

Parameters:
type - the MIDI file type (0, 1, or 2)
divisionType - the timing division type (PPQ or one of the SMPTE types)
resolution - the timing resolution
bytes - the length of the MIDI file in bytes, or UNKNOWN_LENGTH if not known
microseconds - the duration of the file in microseconds, or UNKNOWN_LENGTH if not known
properties - a Map<String,Object> object with properties
Since:
1.5
See Also:
UNKNOWN_LENGTH, Sequence.PPQ, Sequence.SMPTE_24, Sequence.SMPTE_25, Sequence.SMPTE_30DROP, Sequence.SMPTE_30
Method Detail

getType

public int getType()
Obtains the MIDI file type.

Returns:
the file's type (0, 1, or 2)

getDivisionType

public float getDivisionType()
Obtains the timing division type for the MIDI file.

Returns:
the division type (PPQ or one of the SMPTE types)
See Also:
Sequence.Sequence(float, int), Sequence.PPQ, Sequence.SMPTE_24, Sequence.SMPTE_25, Sequence.SMPTE_30DROP, Sequence.SMPTE_30, Sequence.getDivisionType()

getResolution

public int getResolution()
Obtains the timing resolution for the MIDI file. If the division type is PPQ, the resolution is specified in ticks per beat. For SMTPE timing, the resolution is specified in ticks per frame.

Returns:
the number of ticks per beat (PPQ) or per frame (SMPTE)
See Also:
getDivisionType(), Sequence.getResolution()

getByteLength

public int getByteLength()
Obtains the length of the MIDI file, expressed in 8-bit bytes.

Returns:
the number of bytes in the file, or UNKNOWN_LENGTH if not known
See Also:
UNKNOWN_LENGTH

getMicrosecondLength

public long getMicrosecondLength()
Obtains the length of the MIDI file, expressed in microseconds.

Returns:
the file's duration in microseconds, or UNKNOWN_LENGTH if not known
See Also:
Sequence.getMicrosecondLength(), getByteLength(), UNKNOWN_LENGTH

properties

public Map<String,Object> properties()
Obtain an unmodifiable map of properties. The concept of properties is further explained in the class description.

Returns:
a Map<String,Object> object containing all properties. If no properties are recognized, an empty map is returned.
Since:
1.5
See Also:
getProperty(String)

getProperty

public Object getProperty(String key)
Obtain the property value specified by the key. The concept of properties is further explained in the class description.

If the specified property is not defined for a particular file format, this method returns null.

Parameters:
key - the key of the desired property
Returns:
the value of the property with the specified key, or null if the property does not exist.
Since:
1.5
See Also:
properties
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MidiMessage

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Class MidiMessage

java.lang.Object
    extended by  javax.sound.midi.MidiMessage
All Implemented Interfaces:
Cloneable
Direct Known Subclasses:
MetaMessage, ShortMessage, SysexMessage
public abstract class MidiMessage
extends Object
implements Cloneable

MidiMessage is the base class for MIDI messages. They include not only the standard MIDI messages that a synthesizer can respond to, but also "meta-events" that can be used by sequencer programs. There are meta-events for such information as lyrics, copyrights, tempo indications, time and key signatures, markers, etc. For more information, see the Standard MIDI Files 1.0 specification, which is part of the Complete MIDI 1.0 Detailed Specification published by the MIDI Manufacturer's Association (http://www.midi.org).

The base MidiMessage class provides access to three types of information about a MIDI message:

  • The messages's status byte
  • The total length of the message in bytes (the status byte plus any data bytes)
  • A byte array containing the complete message
MidiMessage includes methods to get, but not set, these values. Setting them is a subclass responsibility.

The MIDI standard expresses MIDI data in bytes. However, because JavaTM uses signed bytes, the Java Sound API uses integers instead of bytes when expressing MIDI data. For example, the getStatus() method of MidiMessage returns MIDI status bytes as integers. If you are processing MIDI data that originated outside Java Sound and now is encoded as signed bytes, the bytes can can be converted to integers using this conversion:

int i = (int)(byte & 0xFF)

If you simply need to pass a known MIDI byte value as a method parameter, it can be expressed directly as an integer, using (for example) decimal or hexidecimal notation. For instance, to pass the "active sensing" status byte as the first argument to ShortMessage's setMessage(int) method, you can express it as 254 or 0xFE.

See Also:
Track, Sequence, Receiver

Field Summary
protected byte[] | data The MIDI message data.
protected int | length The number of bytes in the MIDI message, including the status byte and any data bytes.
Constructor Summary
protected MidiMessage(byte[] data)
Constructs a new MidiMessage.
Method Summary
abstract Object | clone() Creates a new object of the same class and with the same contents as this object.
int | getLength() Obtains the total length of the MIDI message in bytes.
byte[] | getMessage() Obtains the MIDI message data.
int | getStatus() Obtains the status byte for the MIDI message.
protected void | setMessage(byte[] data, int length) Sets the data for the MIDI message.
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

data

protected byte[] data
The MIDI message data. The first byte is the status byte for the message; subsequent bytes up to the length of the message are data bytes for this message.

See Also:
getLength()

length

protected int length
The number of bytes in the MIDI message, including the status byte and any data bytes.

See Also:
getLength()
Constructor Detail

MidiMessage

protected MidiMessage(byte[] data)
Constructs a new MidiMessage. This protected constructor is called by concrete subclasses, which should ensure that the data array specifies a complete, valid MIDI message.

Parameters:
data - an array of bytes containing the complete message. The message data may be changed using the setMessage method.
See Also:
setMessage(byte[], int)
Method Detail

setMessage

protected void setMessage(byte[] data,
                          int length)
                   throws InvalidMidiDataException
Sets the data for the MIDI message. This protected method is called by concrete subclasses, which should ensure that the data array specifies a complete, valid MIDI message.

Throws:
InvalidMidiDataException

getMessage

public byte[] getMessage()
Obtains the MIDI message data. The first byte of the returned byte array is the status byte of the message. Any subsequent bytes up to the length of the message are data bytes. The byte array may have a length which is greater than that of the actual message; the total length of the message in bytes is reported by the getLength() method.

Returns:
the byte array containing the complete MidiMessage data

getStatus

public int getStatus()
Obtains the status byte for the MIDI message. The status "byte" is represented as an integer; see the discussion in the MidiMessage class description.

Returns:
the integer representation of this event's status byte

getLength

public int getLength()
Obtains the total length of the MIDI message in bytes. A MIDI message consists of one status byte and zero or more data bytes. The return value ranges from 1 for system real-time messages, to 2 or 3 for channel messages, to any value for meta and system exclusive messages.

Returns:
the length of the message in bytes

clone

public abstract Object clone()
Creates a new object of the same class and with the same contents as this object.

Overrides:
clone in class Object
Returns:
a clone of this instance.
See Also:
Cloneable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MidiSystem

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Class MidiSystem

java.lang.Object
    extended by  javax.sound.midi.MidiSystem

public class MidiSystem
extends Object

The MidiSystem class provides access to the installed MIDI system resources, including devices such as synthesizers, sequencers, and MIDI input and output ports. A typical simple MIDI application might begin by invoking one or more MidiSystem methods to learn what devices are installed and to obtain the ones needed in that application.

The class also has methods for reading files, streams, and URLs that contain standard MIDI file data or soundbanks. You can query the MidiSystem for the format of a specified MIDI file.

You cannot instantiate a MidiSystem; all the methods are static.

Properties can be used to specify default MIDI devices. Both system properties and a properties file are considered. The properties file is "lib/sound.properties" in the JRE directory. If a property exists both as a system property and in the properties file, the system property takes precedence. If none is specified, a suitable default is chosen among the available devices. The syntax of the properties file is specified in Properties.load. The following table lists the available property keys and which methods consider them:
Property Key | Interface | Affected Method
javax.sound.midi.Receiver | Receiver | getReceiver()
javax.sound.midi.Sequencer | Sequencer | getSequencer()
javax.sound.midi.Synthesizer | Synthesizer | getSynthesizer()
javax.sound.midi.Transmitter | Transmitter | getTransmitter()
The property value consists of the provider class name and the device name, separated by the hash mark ("#"). The provider class name is the fully-qualified name of a concrete MIDI device provider class. The device name is matched against the String returned by the getName method of MidiDevice.Info. Either the class name, or the device name may be omitted. If only the class name is specified, the trailing hash mark is optional.

If the provider class is specified, and it can be successully retrieved from the installed providers, the list of MidiDevice.Info objects is retrieved from the provider. Otherwise, or when these devices do not provide a subsequent match, the list is retrieved from getMidiDeviceInfo() to contain all available MidiDevice.Info objects.

If a device name is specified, the resulting list of MidiDevice.Info objects is searched: the first one with a matching name, and whose MidiDevice implements the respective interface, will be returned. If no matching MidiDevice.Info object is found, or the device name is not specified, the first suitable device from the resulting list will be returned. For Sequencer and Synthesizer, a device is suitable if it implements the respective interface; whereas for Receiver and Transmitter, a device is suitable if it implements neither Sequencer nor Synthesizer and provides at least one Receiver or Transmitter, respectively. For example, the property javax.sound.midi.Receiver with a value "com.sun.media.sound.MidiProvider#SunMIDI1" will have the following consequences when getReceiver is called: if the class com.sun.media.sound.MidiProvider exists in the list of installed MIDI device providers, the first Receiver device with name "SunMIDI1" will be returned. If it cannot be found, the first Receiver from that provider will be returned, regardless of name. If there is none, the first Receiver with name "SunMIDI1" in the list of all devices (as returned by getMidiDeviceInfo) will be returned, or, if not found, the first Receiver that can be found in the list of all devices is returned. If that fails, too, a MidiUnavailableException is thrown.

Method Summary
static MidiDevice | getMidiDevice(MidiDevice.Info info) Obtains the requested MIDI device.
static MidiDevice.Info[] | getMidiDeviceInfo() Obtains an array of information objects representing the set of all MIDI devices available on the system.
static MidiFileFormat | getMidiFileFormat(File file) Obtains the MIDI file format of the specified File.
static MidiFileFormat | getMidiFileFormat(InputStream stream) Obtains the MIDI file format of the data in the specified input stream.
static MidiFileFormat | getMidiFileFormat(URL url) Obtains the MIDI file format of the data in the specified URL.
static int[] | getMidiFileTypes() Obtains the set of MIDI file types for which file writing support is provided by the system.
static int[] | getMidiFileTypes(Sequence sequence) Obtains the set of MIDI file types that the system can write from the sequence specified.
static Receiver | getReceiver() Obtains a MIDI receiver from an external MIDI port or other default device.
static Sequence | getSequence(File file) Obtains a MIDI sequence from the specified File.
static Sequence | getSequence(InputStream stream) Obtains a MIDI sequence from the specified input stream.
static Sequence | getSequence(URL url) Obtains a MIDI sequence from the specified URL.
static Sequencer | getSequencer() Obtains the default Sequencer, connected to a default device.
static Sequencer | getSequencer(boolean connected) Obtains the default Sequencer, optionally connected to a default device.
static Soundbank | getSoundbank(File file) Constructs a Soundbank by reading it from the specified File.
static Soundbank | getSoundbank(InputStream stream) Constructs a MIDI sound bank by reading it from the specified stream.
static Soundbank | getSoundbank(URL url) Constructs a Soundbank by reading it from the specified URL.
static Synthesizer | getSynthesizer() Obtains the default synthesizer.
static Transmitter | getTransmitter() Obtains a MIDI transmitter from an external MIDI port or other default source.
static boolean | isFileTypeSupported(int fileType) Indicates whether file writing support for the specified MIDI file type is provided by the system.
static boolean | isFileTypeSupported(int fileType, Sequence sequence) Indicates whether a MIDI file of the file type specified can be written from the sequence indicated.
static int | write(Sequence in, int type, File out) Writes a stream of bytes representing a file of the MIDI file type indicated to the external file provided.
static int | write(Sequence in, int fileType, OutputStream out) Writes a stream of bytes representing a file of the MIDI file type indicated to the output stream provided.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getMidiDeviceInfo

public static MidiDevice.Info[] getMidiDeviceInfo()
Obtains an array of information objects representing the set of all MIDI devices available on the system. A returned information object can then be used to obtain the corresponding device object, by invoking getMidiDevice.

Returns:
an array of MidiDevice.Info objects, one for each installed MIDI device. If no such devices are installed, an array of length 0 is returned.

getMidiDevice

public static MidiDevice getMidiDevice(MidiDevice.Info info)
                                throws MidiUnavailableException
Obtains the requested MIDI device.

Parameters:
info - a device information object representing the desired device.
Returns:
the requested device
Throws:
MidiUnavailableException - if the requested device is not available due to resource restrictions
IllegalArgumentException - if the info object does not represent a MIDI device installed on the system
See Also:
getMidiDeviceInfo()

getReceiver

public static Receiver getReceiver()
                            throws MidiUnavailableException
Obtains a MIDI receiver from an external MIDI port or other default device.

If the system property javax.sound.midi.Receiver is defined or it is defined in the file "sound.properties", it is used to identify the device that provides the default receiver. For details, refer to the class description. If a suitable MIDI port is not available, the Receiver is retrieved from an installed synthesizer.

If this method returns successfully, the MidiDevice the Receiver belongs to is opened implicitly, if it is not already open. It is possible to close an implicitly opened device by calling close on the returned Receiver. All open Receiver instances have to be closed in order to release system resources hold by the MidiDevice. For a detailed description of open/close behaviour see the class description of MidiDevice.

Returns:
the default MIDI receiver
Throws:
MidiUnavailableException - if the default receiver is not available due to resource restrictions, or no device providing receivers is installed in the system

getTransmitter

public static Transmitter getTransmitter()
                                  throws MidiUnavailableException
Obtains a MIDI transmitter from an external MIDI port or other default source.

If the system property javax.sound.midi.Transmitter is defined or it is defined in the file "sound.properties", it is used to identify the device that provides the default transmitter. For details, refer to the class description. If this method returns successfully, the MidiDevice the Transmitter belongs to is opened implicitly, if it is not already open. It is possible to close an implicitly opened device by calling close on the returned Transmitter. All open Transmitter instances have to be closed in order to release system resources hold by the MidiDevice. For a detailed description of open/close behaviour see the class description of MidiDevice.

Returns:
the default MIDI transmitter
Throws:
MidiUnavailableException - if the default transmitter is not available due to resource restrictions, or no device providing transmitters is installed in the system

getSynthesizer

public static Synthesizer getSynthesizer()
                                  throws MidiUnavailableException
Obtains the default synthesizer.

If the system property javax.sound.midi.Synthesizer is defined or it is defined in the file "sound.properties", it is used to identify the default synthesizer. For details, refer to the class description.

Returns:
the default synthesizer
Throws:
MidiUnavailableException - if the synthesizer is not available due to resource restrictions, or no synthesizer is installed in the system

getSequencer

public static Sequencer getSequencer()
                              throws MidiUnavailableException
Obtains the default Sequencer, connected to a default device. The returned Sequencer instance is connected to the default Synthesizer, as returned by getSynthesizer(). If there is no Synthesizer available, or the default Synthesizer cannot be opened, the sequencer is connected to the default Receiver, as returned by getReceiver(). The connection is made by retrieving a Transmitter instance from the Sequencer and setting its Receiver. Closing and re-opening the sequencer will restore the connection to the default device.

This method is equivalent to calling getSequencer(true).

If the system property javax.sound.midi.Sequencer is defined or it is defined in the file "sound.properties", it is used to identify the default sequencer. For details, refer to the class description.

Returns:
the default sequencer, connected to a default Receiver
Throws:
MidiUnavailableException - if the sequencer is not available due to resource restrictions, or there is no Receiver available by any installed MidiDevice, or no sequencer is installed in the system.
See Also:
getSequencer(boolean), getSynthesizer(), getReceiver()

getSequencer

public static Sequencer getSequencer(boolean connected)
                              throws MidiUnavailableException
Obtains the default Sequencer, optionally connected to a default device.

If connected is true, the returned Sequencer instance is connected to the default Synthesizer, as returned by getSynthesizer(). If there is no Synthesizer available, or the default Synthesizer cannot be opened, the sequencer is connected to the default Receiver, as returned by getReceiver(). The connection is made by retrieving a Transmitter instance from the Sequencer and setting its Receiver. Closing and re-opening the sequencer will restore the connection to the default device.

If connected is false, the returned Sequencer instance is not connected, it has no open Transmitters. In order to play the sequencer on a MIDI device, or a Synthesizer, it is necessary to get a Transmitter and set its Receiver.

If the system property javax.sound.midi.Sequencer is defined or it is defined in the file "sound.properties", it is used to identify the default sequencer. For details, refer to the class description.

Returns:
the default sequencer
Throws:
MidiUnavailableException - if the sequencer is not available due to resource restrictions, or no sequencer is installed in the system, or if connected is true, and there is no Receiver available by any installed MidiDevice
Since:
1.5
See Also:
getSynthesizer(), getReceiver()

getSoundbank

public static Soundbank getSoundbank(InputStream stream)
                              throws InvalidMidiDataException,
                                     IOException
Constructs a MIDI sound bank by reading it from the specified stream. The stream must point to a valid MIDI soundbank file. In general, MIDI soundbank providers may need to read some data from the stream before determining whether they support it. These parsers must be able to mark the stream, read enough data to determine whether they support the stream, and, if not, reset the stream's read pointer to its original position. If the input stream does not support this, this method may fail with an IOException.

Parameters:
stream - the source of the sound bank data.
Returns:
the sound bank
Throws:
InvalidMidiDataException - if the stream does not point to valid MIDI soundbank data recognized by the system
IOException - if an I/O error occurred when loading the soundbank
See Also:
InputStream.markSupported(), InputStream.mark(int)

getSoundbank

public static Soundbank getSoundbank(URL url)
                              throws InvalidMidiDataException,
                                     IOException
Constructs a Soundbank by reading it from the specified URL. The URL must point to a valid MIDI soundbank file.

Parameters:
url - the source of the sound bank data
Returns:
the sound bank
Throws:
InvalidMidiDataException - if the URL does not point to valid MIDI soundbank data recognized by the system
IOException - if an I/O error occurred when loading the soundbank

getSoundbank

public static Soundbank getSoundbank(File file)
                              throws InvalidMidiDataException,
                                     IOException
Constructs a Soundbank by reading it from the specified File. The File must point to a valid MIDI soundbank file.

Parameters:
file - the source of the sound bank data
Returns:
the sound bank
Throws:
InvalidMidiDataException - if the File does not point to valid MIDI soundbank data recognized by the system
IOException - if an I/O error occurred when loading the soundbank

getMidiFileFormat

public static MidiFileFormat getMidiFileFormat(InputStream stream)
                                        throws InvalidMidiDataException,
                                               IOException
Obtains the MIDI file format of the data in the specified input stream. The stream must point to valid MIDI file data for a file type recognized by the system.

This method and/or the code it invokes may need to read some data from the stream to determine whether its data format is supported. The implementation may therefore need to mark the stream, read enough data to determine whether it is in a supported format, and reset the stream's read pointer to its original position. If the input stream does not permit this set of operations, this method may fail with an IOException.

This operation can only succeed for files of a type which can be parsed by an installed file reader. It may fail with an InvalidMidiDataException even for valid files if no compatible file reader is installed. It will also fail with an InvalidMidiDataException if a compatible file reader is installed, but encounters errors while determining the file format.

Parameters:
stream - the input stream from which file format information should be extracted
Returns:
an MidiFileFormat object describing the MIDI file format
Throws:
InvalidMidiDataException - if the stream does not point to valid MIDI file data recognized by the system
IOException - if an I/O exception occurs while accessing the stream
See Also:
getMidiFileFormat(URL), getMidiFileFormat(File), InputStream.markSupported(), InputStream.mark(int)

getMidiFileFormat

public static MidiFileFormat getMidiFileFormat(URL url)
                                        throws InvalidMidiDataException,
                                               IOException
Obtains the MIDI file format of the data in the specified URL. The URL must point to valid MIDI file data for a file type recognized by the system.

This operation can only succeed for files of a type which can be parsed by an installed file reader. It may fail with an InvalidMidiDataException even for valid files if no compatible file reader is installed. It will also fail with an InvalidMidiDataException if a compatible file reader is installed, but encounters errors while determining the file format.

Parameters:
url - the URL from which file format information should be extracted
Returns:
a MidiFileFormat object describing the MIDI file format
Throws:
InvalidMidiDataException - if the URL does not point to valid MIDI file data recognized by the system
IOException - if an I/O exception occurs while accessing the URL
See Also:
getMidiFileFormat(InputStream), getMidiFileFormat(File)

getMidiFileFormat

public static MidiFileFormat getMidiFileFormat(File file)
                                        throws InvalidMidiDataException,
                                               IOException
Obtains the MIDI file format of the specified File. The File must point to valid MIDI file data for a file type recognized by the system.

This operation can only succeed for files of a type which can be parsed by an installed file reader. It may fail with an InvalidMidiDataException even for valid files if no compatible file reader is installed. It will also fail with an InvalidMidiDataException if a compatible file reader is installed, but encounters errors while determining the file format.

Parameters:
file - the File from which file format information should be extracted
Returns:
a MidiFileFormat object describing the MIDI file format
Throws:
InvalidMidiDataException - if the File does not point to valid MIDI file data recognized by the system
IOException - if an I/O exception occurs while accessing the file
See Also:
getMidiFileFormat(InputStream), getMidiFileFormat(URL)

getSequence

public static Sequence getSequence(InputStream stream)
                            throws InvalidMidiDataException,
                                   IOException
Obtains a MIDI sequence from the specified input stream. The stream must point to valid MIDI file data for a file type recognized by the system.

This method and/or the code it invokes may need to read some data from the stream to determine whether its data format is supported. The implementation may therefore need to mark the stream, read enough data to determine whether it is in a supported format, and reset the stream's read pointer to its original position. If the input stream does not permit this set of operations, this method may fail with an IOException.

This operation can only succeed for files of a type which can be parsed by an installed file reader. It may fail with an InvalidMidiDataException even for valid files if no compatible file reader is installed. It will also fail with an InvalidMidiDataException if a compatible file reader is installed, but encounters errors while constructing the Sequence object from the file data.

Parameters:
stream - the input stream from which the Sequence should be constructed
Returns:
a Sequence object based on the MIDI file data contained in the input stream
Throws:
InvalidMidiDataException - if the stream does not point to valid MIDI file data recognized by the system
IOException - if an I/O exception occurs while accessing the stream
See Also:
InputStream.markSupported(), InputStream.mark(int)

getSequence

public static Sequence getSequence(URL url)
                            throws InvalidMidiDataException,
                                   IOException
Obtains a MIDI sequence from the specified URL. The URL must point to valid MIDI file data for a file type recognized by the system.

This operation can only succeed for files of a type which can be parsed by an installed file reader. It may fail with an InvalidMidiDataException even for valid files if no compatible file reader is installed. It will also fail with an InvalidMidiDataException if a compatible file reader is installed, but encounters errors while constructing the Sequence object from the file data.

Parameters:
url - the URL from which the Sequence should be constructed
Returns:
a Sequence object based on the MIDI file data pointed to by the URL
Throws:
InvalidMidiDataException - if the URL does not point to valid MIDI file data recognized by the system
IOException - if an I/O exception occurs while accessing the URL

getSequence

public static Sequence getSequence(File file)
                            throws InvalidMidiDataException,
                                   IOException
Obtains a MIDI sequence from the specified File. The File must point to valid MIDI file data for a file type recognized by the system.

This operation can only succeed for files of a type which can be parsed by an installed file reader. It may fail with an InvalidMidiDataException even for valid files if no compatible file reader is installed. It will also fail with an InvalidMidiDataException if a compatible file reader is installed, but encounters errors while constructing the Sequence object from the file data.

Parameters:
file - the File from which the Sequence should be constructed
Returns:
a Sequence object based on the MIDI file data pointed to by the File
Throws:
InvalidMidiDataException - if the File does not point to valid MIDI file data recognized by the system
IOException - if an I/O exception occurs

getMidiFileTypes

public static int[] getMidiFileTypes()
Obtains the set of MIDI file types for which file writing support is provided by the system.

Returns:
array of unique file types. If no file types are supported, an array of length 0 is returned.

isFileTypeSupported

public static boolean isFileTypeSupported(int fileType)
Indicates whether file writing support for the specified MIDI file type is provided by the system.

Parameters:
fileType - the file type for which write capabilities are queried
Returns:
true if the file type is supported, otherwise false

getMidiFileTypes

public static int[] getMidiFileTypes(Sequence sequence)
Obtains the set of MIDI file types that the system can write from the sequence specified.

Parameters:
sequence - the sequence for which MIDI file type support is queried
Returns:
the set of unique supported file types. If no file types are supported, returns an array of length 0.

isFileTypeSupported

public static boolean isFileTypeSupported(int fileType,
                                          Sequence sequence)
Indicates whether a MIDI file of the file type specified can be written from the sequence indicated.

Parameters:
fileType - the file type for which write capabilities are queried
sequence - the sequence for which file writing support is queried
Returns:
true if the file type is supported for this sequence, otherwise false

write

public static int write(Sequence in,
                        int fileType,
                        OutputStream out)
                 throws IOException
Writes a stream of bytes representing a file of the MIDI file type indicated to the output stream provided.

Parameters:
in - sequence containing MIDI data to be written to the file
fileType - the file type of the file to be written to the output stream
out - stream to which the file data should be written
Returns:
the number of bytes written to the output stream
Throws:
IOException - if an I/O exception occurs
IllegalArgumentException - if the file format is not supported by the system
See Also:
isFileTypeSupported(int, Sequence), getMidiFileTypes(Sequence)

write

public static int write(Sequence in,
                        int type,
                        File out)
                 throws IOException
Writes a stream of bytes representing a file of the MIDI file type indicated to the external file provided.

Parameters:
in - sequence containing MIDI data to be written to the file
type - the file type of the file to be written to the output stream
out - external file to which the file data should be written
Returns:
the number of bytes written to the file
Throws:
IOException - if an I/O exception occurs
IllegalArgumentException - if the file type is not supported by the system
See Also:
isFileTypeSupported(int, Sequence), getMidiFileTypes(Sequence)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MidiUnavailableException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Class MidiUnavailableException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.sound.midi.MidiUnavailableException
All Implemented Interfaces:
Serializable
public class MidiUnavailableException
extends Exception

A MidiUnavailableException is thrown when a requested MIDI component cannot be opened or created because it is unavailable. This often occurs when a device is in use by another application. More generally, it can occur when there is a finite number of a certain kind of resource that can be used for some purpose, and all of them are already in use (perhaps all by this application). For an example of the latter case, see the setReceiver method of Transmitter.

See Also:
Serialized Form

Constructor Summary
MidiUnavailableException()
Constructs a MidiUnavailableException that has null as its error detail message.
MidiUnavailableException(String message)
Constructs a MidiUnavailableException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MidiUnavailableException

public MidiUnavailableException()
Constructs a MidiUnavailableException that has null as its error detail message.

MidiUnavailableException

public MidiUnavailableException(String message)
Constructs a MidiUnavailableException with the specified detail message.

Parameters:
message - the string to display as an error detail message
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Patch

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Class Patch

java.lang.Object
    extended by  javax.sound.midi.Patch

public class Patch
extends Object

A Patch object represents a location, on a MIDI synthesizer, into which a single instrument is stored (loaded). Every Instrument object has its own Patch object that specifies the memory location into which that instrument should be loaded. The location is specified abstractly by a bank index and a program number (not by any scheme that directly refers to a specific address or offset in RAM). This is a hierarchical indexing scheme: MIDI provides for up to 16384 banks, each of which contains up to 128 program locations. For example, a minimal sort of synthesizer might have only one bank of instruments, and only 32 instruments (programs) in that bank.

To select what instrument should play the notes on a particular MIDI channel, two kinds of MIDI message are used that specify a patch location: a bank-select command, and a program-change channel command. The Java Sound equivalent is the programChange(int, int) method of MidiChannel.

See Also:
Instrument,
Instrument.getPatch(),
MidiChannel.programChange(int, int),
Synthesizer.loadInstruments(Soundbank, Patch[]),
Soundbank,
Sequence.getPatchList()

Constructor Summary
Patch(int bank, int program)
Constructs a new patch object from the specified bank and program numbers.
Method Summary
int | getBank() Returns the number of the bank that contains the instrument whose location this Patch specifies.
int | getProgram() Returns the index, within a bank, of the instrument whose location this Patch specifies.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Patch

public Patch(int bank,
             int program)
Constructs a new patch object from the specified bank and program numbers.

Parameters:
bank - the bank index (in the range from 0 to 16383)
program - the program index (in the range from 0 to 127)
Method Detail

getBank

public int getBank()
Returns the number of the bank that contains the instrument whose location this Patch specifies.

Returns:
the bank number, whose range is from 0 to 16383
See Also:
MidiChannel.programChange(int, int)

getProgram

public int getProgram()
Returns the index, within a bank, of the instrument whose location this Patch specifies.

Returns:
the instrument's program number, whose range is from 0 to 127
See Also:
MidiChannel.getProgram(),
MidiChannel.programChange(int),
MidiChannel.programChange(int, int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Receiver

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Interface Receiver

public interface Receiver

A Receiver receives MidiEvent objects and typically does something useful in response, such as interpreting them to generate sound or raw MIDI output. Common MIDI receivers include synthesizers and MIDI Out ports.

See Also:
MidiDevice, Synthesizer, Transmitter

Method Summary
void | close() Indicates that the application has finished using the receiver, and that limited resources it requires may be released or made available.
void | send(MidiMessage message, long timeStamp) Sends a MIDI message and time-stamp to this receiver.

Method Detail

send

void send(MidiMessage message,
          long timeStamp)
Sends a MIDI message and time-stamp to this receiver. If time-stamping is not supported by this receiver, the time-stamp value should be -1.

Parameters:
message - the MIDI message to send
timeStamp - the time-stamp for the message, in microseconds.
Throws:
IllegalStateException - if the receiver is closed

close

void close()
Indicates that the application has finished using the receiver, and that limited resources it requires may be released or made available.

If the creation of this Receiver resulted in implicitly opening the underlying device, the device is implicitly closed by this method. This is true unless the device is kept open by other Receiver or Transmitter instances that opened the device implicitly, and unless the device has been opened explicitly. If the device this Receiver is retrieved from is closed explicitly by calling MidiDevice.close, the Receiver is closed, too. For a detailed description of open/close behaviour see the class description of MidiDevice.

See Also:
MidiSystem.getReceiver()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Sequence

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Class Sequence

java.lang.Object
    extended by  javax.sound.midi.Sequence

public class Sequence
extends Object

A Sequence is a data structure containing musical information (often an entire song or composition) that can be played back by a Sequencer object. Specifically, the Sequence contains timing information and one or more tracks. Each track consists of a series of MIDI events (such as note-ons, note-offs, program changes, and meta-events). The sequence's timing information specifies the type of unit that is used to time-stamp the events in the sequence.

A Sequence can be created from a MIDI file by reading the file into an input stream and invoking one of the getSequence methods of MidiSystem. A sequence can also be built from scratch by adding new Tracks to an empty Sequence, and adding MidiEvent objects to these Tracks.

See Also:
Sequencer.setSequence(java.io.InputStream stream),
Sequencer.setSequence(Sequence sequence),
Track.add(MidiEvent),
MidiFileFormat

Field Summary
protected float | divisionType The timing division type of the sequence.
static float | PPQ The tempo-based timing type, for which the resolution is expressed in pulses (ticks) per quarter note.
protected int | resolution The timing resolution of the sequence.
static float | SMPTE_24 The SMPTE-based timing type with 24 frames per second (resolution is expressed in ticks per frame).
static float | SMPTE_25 The SMPTE-based timing type with 25 frames per second (resolution is expressed in ticks per frame).
static float | SMPTE_30 The SMPTE-based timing type with 30 frames per second (resolution is expressed in ticks per frame).
static float | SMPTE_30DROP The SMPTE-based timing type with 29.97 frames per second (resolution is expressed in ticks per frame).
protected Vector<Track> | tracks The MIDI tracks in this sequence.
Constructor Summary
Sequence(float divisionType, int resolution)
Constructs a new MIDI sequence with the specified timing division type and timing resolution.
Sequence(float divisionType, int resolution, int numTracks)
Constructs a new MIDI sequence with the specified timing division type, timing resolution, and number of tracks.
Method Summary
Track | createTrack() Creates a new, initially empty track as part of this sequence.
boolean | deleteTrack(Track track) Removes the specified track from the sequence.
float | getDivisionType() Obtains the timing division type for this sequence.
long | getMicrosecondLength() Obtains the duration of this sequence, expressed in microseconds.
Patch[] | getPatchList() Obtains a list of patches referenced in this sequence.
int | getResolution() Obtains the timing resolution for this sequence.
long | getTickLength() Obtains the duration of this sequence, expressed in MIDI ticks.
Track[] | getTracks() Obtains an array containing all the tracks in this sequence.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PPQ

public static final float PPQ
The tempo-based timing type, for which the resolution is expressed in pulses (ticks) per quarter note.

See Also:
Sequence(float, int), Constant Field Values

SMPTE_24

public static final float SMPTE_24
The SMPTE-based timing type with 24 frames per second (resolution is expressed in ticks per frame).

See Also:
Sequence(float, int), Constant Field Values

SMPTE_25

public static final float SMPTE_25
The SMPTE-based timing type with 25 frames per second (resolution is expressed in ticks per frame).

See Also:
Sequence(float, int), Constant Field Values

SMPTE_30DROP

public static final float SMPTE_30DROP
The SMPTE-based timing type with 29.97 frames per second (resolution is expressed in ticks per frame).

See Also:
Sequence(float, int), Constant Field Values

SMPTE_30

public static final float SMPTE_30
The SMPTE-based timing type with 30 frames per second (resolution is expressed in ticks per frame).

See Also:
Sequence(float, int), Constant Field Values

divisionType

protected float divisionType
The timing division type of the sequence.

See Also:
PPQ, SMPTE_24, SMPTE_25, SMPTE_30DROP, SMPTE_30, getDivisionType()

resolution

protected int resolution
The timing resolution of the sequence.

See Also:
getResolution()

tracks

protected Vector<Track> tracks
The MIDI tracks in this sequence.

See Also:
getTracks()
Constructor Detail

Sequence

public Sequence(float divisionType,
                int resolution)
         throws InvalidMidiDataException
Constructs a new MIDI sequence with the specified timing division type and timing resolution. The division type must be one of the recognized MIDI timing types. For tempo-based timing, divisionType is PPQ (pulses per quarter note) and the resolution is specified in ticks per beat. For SMTPE timing, divisionType specifies the number of frames per second and the resolution is specified in ticks per frame. The sequence will contain no initial tracks. Tracks may be added to or removed from the sequence using createTrack() and deleteTrack(javax.sound.midi.Track).

Parameters:
divisionType - the timing division type (PPQ or one of the SMPTE types)
resolution - the timing resolution
Throws:
InvalidMidiDataException - if divisionType is not valid
See Also:
PPQ, SMPTE_24, SMPTE_25, SMPTE_30DROP, SMPTE_30, getDivisionType(), getResolution(), getTracks()

Sequence

public Sequence(float divisionType,
                int resolution,
                int numTracks)
         throws InvalidMidiDataException
Constructs a new MIDI sequence with the specified timing division type, timing resolution, and number of tracks. The division type must be one of the recognized MIDI timing types. For tempo-based timing, divisionType is PPQ (pulses per quarter note) and the resolution is specified in ticks per beat. For SMTPE timing, divisionType specifies the number of frames per second and the resolution is specified in ticks per frame. The sequence will be initialized with the number of tracks specified by numTracks. These tracks are initially empty (i.e. they contain only the meta-event End of Track). The tracks may be retrieved for editing using the getTracks() method. Additional tracks may be added, or existing tracks removed, using createTrack() and deleteTrack(javax.sound.midi.Track).

Parameters:
divisionType - the timing division type (PPQ or one of the SMPTE types)
resolution - the timing resolution
numTracks - the initial number of tracks in the sequence.
Throws:
InvalidMidiDataException - if divisionType is not valid
See Also:
PPQ, SMPTE_24, SMPTE_25, SMPTE_30DROP, SMPTE_30, getDivisionType(), getResolution()
Method Detail

getDivisionType

public float getDivisionType()
Obtains the timing division type for this sequence.

Returns:
the division type (PPQ or one of the SMPTE types)
See Also:
PPQ, SMPTE_24, SMPTE_25, SMPTE_30DROP, SMPTE_30, Sequence(float, int), MidiFileFormat.getDivisionType()

getResolution

public int getResolution()
Obtains the timing resolution for this sequence. If the sequence's division type is PPQ, the resolution is specified in ticks per beat. For SMTPE timing, the resolution is specified in ticks per frame.

Returns:
the number of ticks per beat (PPQ) or per frame (SMPTE)
See Also:
getDivisionType(),
Sequence(float, int),
MidiFileFormat.getResolution()

createTrack

public Track createTrack()
Creates a new, initially empty track as part of this sequence. The track initially contains the meta-event End of Track. The newly created track is returned. All tracks in the sequence may be retrieved using getTracks(). Tracks may be removed from the sequence using deleteTrack(javax.sound.midi.Track).

Returns:
the newly created track

deleteTrack

public boolean deleteTrack(Track track)
Removes the specified track from the sequence.

Parameters:
track - the track to remove
Returns:
true if the track existed in the track and was removed, otherwise false.
See Also:
createTrack(), getTracks()

getTracks

public Track[] getTracks()
Obtains an array containing all the tracks in this sequence. If the sequence contains no tracks, an array of length 0 is returned.

Returns:
the array of tracks
See Also:
createTrack(), deleteTrack(javax.sound.midi.Track)

getMicrosecondLength

public long getMicrosecondLength()
Obtains the duration of this sequence, expressed in microseconds.

Returns:
this sequence's duration in microseconds.

getTickLength

public long getTickLength()
Obtains the duration of this sequence, expressed in MIDI ticks.

Returns:
this sequence's length in ticks
See Also:
getMicrosecondLength()

getPatchList

public Patch[] getPatchList()
Obtains a list of patches referenced in this sequence. This patch list may be used to load the required Instrument objects into a Synthesizer.

Returns:
an array of Patch objects used in this sequence
See Also:
Synthesizer.loadInstruments(Soundbank, Patch[])
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Sequencer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Interface Sequencer

All Superinterfaces:
MidiDevice
public interface Sequencer
extends MidiDevice

A hardware or software device that plays back a MIDI sequence is known as a sequencer. A MIDI sequence contains lists of time-stamped MIDI data, such as might be read from a standard MIDI file. Most sequencers also provide functions for creating and editing sequences.

The Sequencer interface includes methods for the following basic MIDI sequencer operations:

  • obtaining a sequence from MIDI file data
  • starting and stopping playback
  • moving to an arbitrary position in the sequence
  • changing the tempo (speed) of playback
  • synchronizing playback to an internal clock or to received MIDI messages
  • controlling the timing of another device
In addition, the following operations are supported, either directly, or indirectly through objects that the Sequencer has access to:
  • editing the data by adding or deleting individual MIDI events or entire tracks
  • muting or soloing individual tracks in the sequence
  • notifying listener objects about any meta-events or control-change events encountered while playing back the sequence.

See Also:
Sequencer.SyncMode, addMetaEventListener(javax.sound.midi.MetaEventListener), ControllerEventListener, Receiver, Transmitter, MidiDevice

Nested Class Summary
static class Sequencer.SyncMode
A SyncMode object represents one of the ways in which a MIDI sequencer's notion of time can be synchronized with a master or slave device.
Nested classes/interfaces inherited from interface javax.sound.midi.MidiDevice
MidiDevice.Info
Field Summary
static int LOOP_CONTINUOUSLY
A value indicating that looping should continue indefinitely rather than complete after a specific number of loops.
Method Summary
int[] | addControllerEventListener(ControllerEventListener listener, int[] controllers) Registers a controller event listener to receive notification whenever the sequencer processes a control-change event of the requested type or types.
boolean | addMetaEventListener(MetaEventListener listener) Registers a meta-event listener to receive notification whenever a meta-event is encountered in the sequence and processed by the sequencer.
int | getLoopCount() Obtains the number of repetitions for playback.
long | getLoopEndPoint() Obtains the end position of the loop, in MIDI ticks.
long | getLoopStartPoint() Obtains the start position of the loop, in MIDI ticks.
Sequencer.SyncMode | getMasterSyncMode() Obtains the current master synchronization mode for this sequencer.
Sequencer.SyncMode[] | getMasterSyncModes() Obtains the set of master synchronization modes supported by this sequencer.
long | getMicrosecondLength() Obtains the length of the current sequence, expressed in microseconds, or 0 if no sequence is set.
long | getMicrosecondPosition() Obtains the current position in the sequence, expressed in microseconds.
Sequence | getSequence() Obtains the sequence on which the Sequencer is currently operating.
Sequencer.SyncMode | getSlaveSyncMode() Obtains the current slave synchronization mode for this sequencer.
Sequencer.SyncMode[] | getSlaveSyncModes() Obtains the set of slave synchronization modes supported by the sequencer.
float | getTempoFactor() Returns the current tempo factor for the sequencer.
float | getTempoInBPM() Obtains the current tempo, expressed in beats per minute.
float | getTempoInMPQ() Obtains the current tempo, expressed in microseconds per quarter note.
long | getTickLength() Obtains the length of the current sequence, expressed in MIDI ticks, or 0 if no sequence is set.
long | getTickPosition() Obtains the current position in the sequence, expressed in MIDI ticks.
boolean | getTrackMute(int track) Obtains the current mute state for a track.
boolean | getTrackSolo(int track) Obtains the current solo state for a track.
boolean | isRecording() Indicates whether the Sequencer is currently recording.
boolean | isRunning() Indicates whether the Sequencer is currently running.
void | recordDisable(Track track) Disables recording to the specified track.
void | recordEnable(Track track, int channel) Prepares the specified track for recording events received on a particular channel.
int[] | removeControllerEventListener(ControllerEventListener listener, int[] controllers) Removes a controller event listener's interest in one or more types of controller event.
void | removeMetaEventListener(MetaEventListener listener) Removes the specified meta-event listener from this sequencer's list of registered listeners, if in fact the listener is registered.
void | setLoopCount(int count) Sets the number of repetitions of the loop for playback.
void | setLoopEndPoint(long tick) Sets the last MIDI tick that will be played in the loop.
void | setLoopStartPoint(long tick) Sets the first MIDI tick that will be played in the loop.
void | setMasterSyncMode(Sequencer.SyncMode sync) Sets the source of timing information used by this sequencer.
void | setMicrosecondPosition(long microseconds) Sets the current position in the sequence, expressed in microseconds
void | setSequence(InputStream stream) Sets the current sequence on which the sequencer operates.
void | setSequence(Sequence sequence) Sets the current sequence on which the sequencer operates.
void | setSlaveSyncMode(Sequencer.SyncMode sync) Sets the slave synchronization mode for the sequencer.
void | setTempoFactor(float factor) Scales the sequencer's actual playback tempo by the factor provided.
void | setTempoInBPM(float bpm) Sets the tempo in beats per minute.
void | setTempoInMPQ(float mpq) Sets the tempo in microseconds per quarter note.
void | setTickPosition(long tick) Sets the current sequencer position in MIDI ticks
void | setTrackMute(int track, boolean mute) Sets the mute state for a track.
void | setTrackSolo(int track, boolean solo) Sets the solo state for a track.
void | start() Starts playback of the MIDI data in the currently loaded sequence.
void | startRecording() Starts recording and playback of MIDI data.
void | stop() Stops recording, if active, and playback of the currently loaded sequence, if any.
void | stopRecording() Stops recording, if active.
Methods inherited from interface javax.sound.midi.MidiDevice
close, getDeviceInfo, getMaxReceivers, getMaxTransmitters, getReceiver, getReceivers, getTransmitter, getTransmitters, isOpen, open

Field Detail

LOOP_CONTINUOUSLY

static final int LOOP_CONTINUOUSLY
A value indicating that looping should continue indefinitely rather than complete after a specific number of loops.

Since:
1.5
See Also:
setLoopCount(int), Constant Field Values
Method Detail

setSequence

void setSequence(Sequence sequence)
                 throws InvalidMidiDataException
Sets the current sequence on which the sequencer operates.

This method can be called even if the Sequencer is closed.

Parameters:
sequence - the sequence to be loaded.
Throws:
InvalidMidiDataException - if the sequence contains invalid MIDI data, or is not supported.

setSequence

void setSequence(InputStream stream)
                 throws IOException,
                        InvalidMidiDataException
Sets the current sequence on which the sequencer operates. The stream must point to MIDI file data.

This method can be called even if the Sequencer is closed.

Parameters:
stream - stream containing MIDI file data.
Throws:
IOException - if an I/O exception occurs during reading of the stream.
InvalidMidiDataException - if invalid data is encountered in the stream, or the stream is not supported.

getSequence

Sequence getSequence()
Obtains the sequence on which the Sequencer is currently operating.

This method can be called even if the Sequencer is closed.

Returns:
the current sequence, or null if no sequence is currently set.

start

void start()
Starts playback of the MIDI data in the currently loaded sequence. Playback will begin from the current position. If the playback position reaches the loop end point, and the loop count is greater than 0, playback will resume at the loop start point for the number of repetitions set with setLoopCount. After that, or if the loop count is 0, playback will continue to play to the end of the sequence.

The implementation ensures that the synthesizer is brought to a consistent state when jumping to the loop start point by sending appropriate controllers, pitch bend, and program change events.

Throws:
IllegalStateException - if the Sequencer is closed.
See Also:
setLoopStartPoint(long), setLoopEndPoint(long), setLoopCount(int), stop()

stop

void stop()
Stops recording, if active, and playback of the currently loaded sequence, if any.

Throws:
IllegalStateException - if the Sequencer is closed.
See Also:
start(), isRunning()

isRunning

boolean isRunning()
Indicates whether the Sequencer is currently running. The default is false. The Sequencer starts running when either start() or startRecording() is called. isRunning then returns true until playback of the sequence completes or stop() is called.

Returns:
true if the Sequencer is running, otherwise false

startRecording

void startRecording()
Starts recording and playback of MIDI data. Data is recorded to all enabled tracks, on the channel(s) for which they were enabled. Recording begins at the current position of the sequencer. Any events already in the track are overwritten for the duration of the recording session. Events from the currently loaded sequence, if any, are delivered to the sequencer's transmitter(s) along with messages received during recording.

Note that tracks are not by default enabled for recording. In order to record MIDI data, at least one track must be specifically enabled for recording.

Throws:
IllegalStateException - if the Sequencer is closed.
See Also:
startRecording(),
recordEnable(javax.sound.midi.Track, int),
recordDisable(javax.sound.midi.Track)

stopRecording

void stopRecording()
Stops recording, if active. Playback of the current sequence continues.

Throws:
IllegalStateException - if the Sequencer is closed.
See Also:
startRecording(), isRecording()

isRecording

boolean isRecording()
Indicates whether the Sequencer is currently recording. The default is false. The Sequencer begins recording when startRecording() is called, and then returns true until stop() or stopRecording() is called.

Returns:
true if the Sequencer is recording, otherwise false

recordEnable

void recordEnable(Track track,
                  int channel)
Prepares the specified track for recording events received on a particular channel. Once enabled, a track will receive events when recording is active.

Parameters:
track - the track to which events will be recorded
channel - the channel on which events will be received. If -1 is specified for the channel value, the track will receive data from all channels.
Throws:
IllegalArgumentException - thrown if the track is not part of the current sequence.

recordDisable

void recordDisable(Track track)
Disables recording to the specified track. Events will no longer be recorded into this track.

Parameters:
track - the track to disable for recording, or null to disable recording for all tracks.

getTempoInBPM

float getTempoInBPM()
Obtains the current tempo, expressed in beats per minute. The actual tempo of playback is the product of the returned value and the tempo factor.

Returns:
the current tempo in beats per minute
See Also:
getTempoFactor(), setTempoInBPM(float), getTempoInMPQ()

setTempoInBPM

void setTempoInBPM(float bpm)
Sets the tempo in beats per minute. The actual tempo of playback is the product of the specified value and the tempo factor.

Parameters:
bpm - desired new tempo in beats per minute
See Also:
getTempoFactor(), setTempoInMPQ(float), getTempoInBPM()

getTempoInMPQ

float getTempoInMPQ()
Obtains the current tempo, expressed in microseconds per quarter note. The actual tempo of playback is the product of the returned value and the tempo factor.

Returns:
the current tempo in microseconds per quarter note
See Also:
getTempoFactor(), setTempoInMPQ(float), getTempoInBPM()

setTempoInMPQ

void setTempoInMPQ(float mpq)
Sets the tempo in microseconds per quarter note. The actual tempo of playback is the product of the specified value and the tempo factor.

Parameters:
mpq - desired new tempo in microseconds per quarter note.
See Also:
getTempoFactor(), setTempoInBPM(float), getTempoInMPQ()

setTempoFactor

void setTempoFactor(float factor)
Scales the sequencer's actual playback tempo by the factor provided. The default is 1.0. A value of 1.0 represents the natural rate (the tempo specified in the sequence), 2.0 means twice as fast, etc. The tempo factor does not affect the values returned by getTempoInMPQ() and getTempoInBPM(). Those values indicate the tempo prior to scaling.

Note that the tempo factor cannot be adjusted when external synchronization is used. In that situation, setTempoFactor always sets the tempo factor to 1.0.

Parameters:
factor - the requested tempo scalar
See Also:
getTempoFactor()

getTempoFactor

float getTempoFactor()
Returns the current tempo factor for the sequencer. The default is 1.0.

Returns:
tempo factor.
See Also:
setTempoFactor(float)

getTickLength

long getTickLength()
Obtains the length of the current sequence, expressed in MIDI ticks, or 0 if no sequence is set.

Returns:
length of the sequence in ticks

getTickPosition

long getTickPosition()
Obtains the current position in the sequence, expressed in MIDI ticks. (The duration of a tick in seconds is determined both by the tempo and by the timing resolution stored in the Sequence.)

Returns:
current tick
See Also:
setTickPosition(long)

setTickPosition

void setTickPosition(long tick)
Sets the current sequencer position in MIDI ticks

Parameters:
tick - the desired tick position
See Also:
getTickPosition()

getMicrosecondLength

long getMicrosecondLength()
Obtains the length of the current sequence, expressed in microseconds, or 0 if no sequence is set.

Returns:
length of the sequence in microseconds.

getMicrosecondPosition

long getMicrosecondPosition()
Obtains the current position in the sequence, expressed in microseconds.

Specified by:
getMicrosecondPosition in interface MidiDevice
Returns:
the current position in microseconds
See Also:
setMicrosecondPosition(long)

setMicrosecondPosition

void setMicrosecondPosition(long microseconds)
Sets the current position in the sequence, expressed in microseconds

Parameters:
microseconds - desired position in microseconds
See Also:
getMicrosecondPosition()

setMasterSyncMode

void setMasterSyncMode(Sequencer.SyncMode sync)
Sets the source of timing information used by this sequencer. The sequencer synchronizes to the master, which is the internal clock, MIDI clock, or MIDI time code, depending on the value of sync. The sync argument must be one of the supported modes, as returned by getMasterSyncModes().

Parameters:
sync - the desired master synchronization mode
See Also:
Sequencer.SyncMode.INTERNAL_CLOCK, Sequencer.SyncMode.MIDI_SYNC, Sequencer.SyncMode.MIDI_TIME_CODE, getMasterSyncMode()

getMasterSyncMode

Sequencer.SyncMode getMasterSyncMode()
Obtains the current master synchronization mode for this sequencer.

Returns:
the current master synchronization mode
See Also:
setMasterSyncMode(Sequencer.SyncMode), getMasterSyncModes()

getMasterSyncModes

Sequencer.SyncMode[] getMasterSyncModes()
Obtains the set of master synchronization modes supported by this sequencer.

Returns:
the available master synchronization modes
See Also:
Sequencer.SyncMode.INTERNAL_CLOCK, Sequencer.SyncMode.MIDI_SYNC, Sequencer.SyncMode.MIDI_TIME_CODE, getMasterSyncMode(), setMasterSyncMode(Sequencer.SyncMode)

setSlaveSyncMode

void setSlaveSyncMode(Sequencer.SyncMode sync)
Sets the slave synchronization mode for the sequencer. This indicates the type of timing information sent by the sequencer to its receiver. The sync argument must be one of the supported modes, as returned by getSlaveSyncModes().

Parameters:
sync - the desired slave synchronization mode
See Also:
Sequencer.SyncMode.MIDI_SYNC, Sequencer.SyncMode.MIDI_TIME_CODE, Sequencer.SyncMode.NO_SYNC, getSlaveSyncModes()

getSlaveSyncMode

Sequencer.SyncMode getSlaveSyncMode()
Obtains the current slave synchronization mode for this sequencer.

Returns:
the current slave synchronization mode
See Also:
setSlaveSyncMode(Sequencer.SyncMode), getSlaveSyncModes()

getSlaveSyncModes

Sequencer.SyncMode[] getSlaveSyncModes()
Obtains the set of slave synchronization modes supported by the sequencer.

Returns:
the available slave synchronization modes
See Also:
Sequencer.SyncMode.MIDI_SYNC, Sequencer.SyncMode.MIDI_TIME_CODE, Sequencer.SyncMode.NO_SYNC

setTrackMute

void setTrackMute(int track,
                  boolean mute)
Sets the mute state for a track. This method may fail for a number of reasons. For example, the track number specified may not be valid for the current sequence, or the sequencer may not support this functionality. An application which needs to verify whether this operation succeeded should follow this call with a call to getTrackMute(int).

Parameters:
track - the track number. Tracks in the current sequence are numbered from 0 to the number of tracks in the sequence minus 1.
mute - the new mute state for the track. true implies the track should be muted, false implies the track should be unmuted.
See Also:
getSequence()

getTrackMute

boolean getTrackMute(int track)
Obtains the current mute state for a track. The default mute state for all tracks which have not been muted is false. In any case where the specified track has not been muted, this method should return false. This applies if the sequencer does not support muting of tracks, and if the specified track index is not valid.

Parameters:
track - the track number. Tracks in the current sequence are numbered from 0 to the number of tracks in the sequence minus 1.
Returns:
true if muted, false if not.

setTrackSolo

void setTrackSolo(int track,
                  boolean solo)
Sets the solo state for a track. If solo is true only this track and other solo'd tracks will sound. If solo is false then only other solo'd tracks will sound, unless no tracks are solo'd in which case all un-muted tracks will sound.

This method may fail for a number of reasons. For example, the track number specified may not be valid for the current sequence, or the sequencer may not support this functionality. An application which needs to verify whether this operation succeeded should follow this call with a call to getTrackSolo(int).

Parameters:
track - the track number. Tracks in the current sequence are numbered from 0 to the number of tracks in the sequence minus 1.
solo - the new solo state for the track. true implies the track should be solo'd, false implies the track should not be solo'd.
See Also:
getSequence()

getTrackSolo

boolean getTrackSolo(int track)
Obtains the current solo state for a track. The default mute state for all tracks which have not been solo'd is false. In any case where the specified track has not been solo'd, this method should return false. This applies if the sequencer does not support soloing of tracks, and if the specified track index is not valid.

Parameters:
track - the track number. Tracks in the current sequence are numbered from 0 to the number of tracks in the sequence minus 1.
Returns:
true if solo'd, false if not.

addMetaEventListener

boolean addMetaEventListener(MetaEventListener listener)
Registers a meta-event listener to receive notification whenever a meta-event is encountered in the sequence and processed by the sequencer. This method can fail if, for instance,this class of sequencer does not support meta-event notification.

Parameters:
listener - listener to add
Returns:
true if the listener was successfully added, otherwise false
See Also:
removeMetaEventListener(javax.sound.midi.MetaEventListener), MetaEventListener, MetaMessage

removeMetaEventListener

void removeMetaEventListener(MetaEventListener listener)
Removes the specified meta-event listener from this sequencer's list of registered listeners, if in fact the listener is registered.

Parameters:
listener - the meta-event listener to remove
See Also:
addMetaEventListener(javax.sound.midi.MetaEventListener)

addControllerEventListener

int[] addControllerEventListener(ControllerEventListener listener,
                                 int[] controllers)
Registers a controller event listener to receive notification whenever the sequencer processes a control-change event of the requested type or types. The types are specified by the controllers argument, which should contain an array of MIDI controller numbers. (Each number should be between 0 and 127, inclusive. See the MIDI 1.0 Specification for the numbers that correspond to various types of controllers.)

The returned array contains the MIDI controller numbers for which the listener will now receive events. Some sequencers might not support controller event notification, in which case the array has a length of 0. Other sequencers might support notification for some controllers but not all. This method may be invoked repeatedly. Each time, the returned array indicates all the controllers that the listener will be notified about, not only the controllers requested in that particular invocation.

Parameters:
listener - the controller event listener to add to the list of registered listeners
controllers - the MIDI controller numbers for which change notification is requested
Returns:
the numbers of all the MIDI controllers whose changes will now be reported to the specified listener
See Also:
removeControllerEventListener(javax.sound.midi.ControllerEventListener, int[]), ControllerEventListener

removeControllerEventListener

int[] removeControllerEventListener(ControllerEventListener listener,
                                    int[] controllers)
Removes a controller event listener's interest in one or more types of controller event. The controllers argument is an array of MIDI numbers corresponding to the controllers for which the listener should no longer receive change notifications. To completely remove this listener from the list of registered listeners, pass in null for controllers. The returned array contains the MIDI controller numbers for which the listener will now receive events. The array has a length of 0 if the listener will not receive change notifications for any controllers.

Parameters:
listener - old listener
controllers - the MIDI controller numbers for which change notification should be cancelled, or null to cancel for all controllers
Returns:
the numbers of all the MIDI controllers whose changes will now be reported to the specified listener
See Also:
addControllerEventListener(javax.sound.midi.ControllerEventListener, int[])

setLoopStartPoint

void setLoopStartPoint(long tick)
Sets the first MIDI tick that will be played in the loop. If the loop count is greater than 0, playback will jump to this point when reaching the loop end point.

A value of 0 for the starting point means the beginning of the loaded sequence. The starting point must be lower than or equal to the ending point, and it must fall within the size of the loaded sequence.

A sequencer's loop start point defaults to start of the sequence.

Parameters:
tick - the loop's starting position, in MIDI ticks (zero-based)
Throws:
IllegalArgumentException - if the requested loop start point cannot be set, usually because it falls outside the sequence's duration or because the start point is after the end point
Since:
1.5
See Also:
setLoopEndPoint(long), setLoopCount(int), getLoopStartPoint(), start()

getLoopStartPoint

long getLoopStartPoint()
Obtains the start position of the loop, in MIDI ticks.

Returns:
the start position of the loop, in MIDI ticks (zero-based)
Since:
1.5
See Also:
setLoopStartPoint(long)

setLoopEndPoint

void setLoopEndPoint(long tick)
Sets the last MIDI tick that will be played in the loop. If the loop count is 0, the loop end point has no effect and playback continues to play when reaching the loop end point.

A value of -1 for the ending point indicates the last tick of the sequence. Otherwise, the ending point must be greater than or equal to the starting point, and it must fall within the size of the loaded sequence.

A sequencer's loop end point defaults to -1, meaning the end of the sequence.

Parameters:
tick - the loop's ending position, in MIDI ticks (zero-based), or -1 to indicate the final tick
Throws:
IllegalArgumentException - if the requested loop point cannot be set, usually because it falls outside the sequence's duration or because the ending point is before the starting point
Since:
1.5
See Also:
setLoopStartPoint(long), setLoopCount(int), getLoopEndPoint(), start()

getLoopEndPoint

long getLoopEndPoint()
Obtains the end position of the loop, in MIDI ticks.

Returns:
the end position of the loop, in MIDI ticks (zero-based), or -1 to indicate the end of the sequence
Since:
1.5
See Also:
setLoopEndPoint(long)

setLoopCount

void setLoopCount(int count)
Sets the number of repetitions of the loop for playback. When the playback position reaches the loop end point, it will loop back to the loop start point count times, after which playback will continue to play to the end of the sequence.

If the current position when this method is invoked is greater than the loop end point, playback continues to the end of the sequence without looping, unless the loop end point is changed subsequently.

A count value of 0 disables looping: playback will continue at the loop end point, and it will not loop back to the loop start point. This is a sequencer's default.

If playback is stopped during looping, the current loop status is cleared; subsequent start requests are not affected by an interrupted loop operation.

Parameters:
count - the number of times playback should loop back from the loop's end position to the loop's start position, or LOOP_CONTINUOUSLY to indicate that looping should continue until interrupted
Throws:
IllegalArgumentException - if count is negative and not equal to LOOP_CONTINUOUSLY
Since:
1.5
See Also:
setLoopStartPoint(long), setLoopEndPoint(long), getLoopCount(), start()

getLoopCount

int getLoopCount()
Obtains the number of repetitions for playback.

Returns:
the number of loops after which playback plays to the end of the sequence
Since:
1.5
See Also:
setLoopCount(int), start()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Sequencer.SyncMode

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Class Sequencer.SyncMode

java.lang.Object
    extended by  javax.sound.midi.Sequencer.SyncMode
Enclosing interface:
Sequencer
public static class Sequencer.SyncMode
extends Object

A SyncMode object represents one of the ways in which a MIDI sequencer's notion of time can be synchronized with a master or slave device. If the sequencer is being synchronized to a master, the sequencer revises its current time in response to messages from the master. If the sequencer has a slave, the sequencer similarly sends messages to control the slave's timing.

There are three predefined modes that specify possible masters for a sequencer: INTERNAL_CLOCK, MIDI_SYNC, and MIDI_TIME_CODE. The latter two work if the sequencer receives MIDI messages from another device. In these two modes, the sequencer's time gets reset based on system real-time timing clock messages or MIDI time code (MTC) messages, respectively. These two modes can also be used as slave modes, in which case the sequencer sends the corresponding types of MIDI messages to its receiver (whether or not the sequencer is also receiving them from a master). A fourth mode, NO_SYNC, is used to indicate that the sequencer should not control its receiver's timing.

See Also:
Sequencer.setMasterSyncMode(Sequencer.SyncMode), Sequencer.setSlaveSyncMode(Sequencer.SyncMode)

Field Summary
static Sequencer.SyncMode | INTERNAL_CLOCK A master synchronization mode that makes the sequencer get its timing information from its internal clock.
static Sequencer.SyncMode | MIDI_SYNC A master or slave synchronization mode that specifies the use of MIDI clock messages.
static Sequencer.SyncMode | MIDI_TIME_CODE A master or slave synchronization mode that specifies the use of MIDI Time Code.
static Sequencer.SyncMode | NO_SYNC A slave synchronization mode indicating that no timing information should be sent to the receiver.
Constructor Summary
protected Sequencer.SyncMode(String name)
Constructs a synchronization mode.
Method Summary
boolean | equals(Object obj) Determines whether two objects are equal.
int | hashCode() Finalizes the hashcode method.
String | toString() Provides this synchronization mode's name as the string representation of the mode.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

INTERNAL_CLOCK

public static final Sequencer.SyncMode INTERNAL_CLOCK
A master synchronization mode that makes the sequencer get its timing information from its internal clock. This is not a legal slave sync mode.

MIDI_SYNC

public static final Sequencer.SyncMode MIDI_SYNC
A master or slave synchronization mode that specifies the use of MIDI clock messages. If this mode is used as the master sync mode, the sequencer gets its timing information from system real-time MIDI clock messages. This mode only applies as the master sync mode for sequencers that are also MIDI receivers. If this is the slave sync mode, the sequencer sends system real-time MIDI clock messages to its receiver. MIDI clock messages are sent at a rate of 24 per quarter note.

MIDI_TIME_CODE

public static final Sequencer.SyncMode MIDI_TIME_CODE
A master or slave synchronization mode that specifies the use of MIDI Time Code. If this mode is used as the master sync mode, the sequencer gets its timing information from MIDI Time Code messages. This mode only applies as the master sync mode to sequencers that are also MIDI receivers. If this mode is used as the slave sync mode, the sequencer sends MIDI Time Code messages to its receiver. (See the MIDI 1.0 Detailed Specification for a description of MIDI Time Code.)

NO_SYNC

public static final Sequencer.SyncMode NO_SYNC
A slave synchronization mode indicating that no timing information should be sent to the receiver. This is not a legal master sync mode.

Constructor Detail

Sequencer.SyncMode

protected Sequencer.SyncMode(String name)
Constructs a synchronization mode.

Parameters:
name - name of the synchronization mode
Method Detail

equals

public final boolean equals(Object obj)
Determines whether two objects are equal. Returns true if the objects are identical

Overrides:
equals in class Object
Parameters:
obj - the reference object with which to compare
Returns:
true if this object is the same as the obj argument, false otherwise
See Also:
Object.hashCode(), Hashtable

hashCode

public final int hashCode()
Finalizes the hashcode method.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public final String toString()
Provides this synchronization mode's name as the string representation of the mode.

Overrides:
toString in class Object
Returns:
the name of this synchronization mode
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ShortMessage

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Class ShortMessage

java.lang.Object
    extended by  javax.sound.midi.MidiMessage
        extended by  javax.sound.midi.ShortMessage
All Implemented Interfaces:
Cloneable
public class ShortMessage
extends MidiMessage

A ShortMessage contains a MIDI message that has at most two data bytes following its status byte. The types of MIDI message that satisfy this criterion are channel voice, channel mode, system common, and system real-time--in other words, everything except system exclusive and meta-events. The ShortMessage class provides methods for getting and setting the contents of the MIDI message.

A number of ShortMessage methods have integer parameters by which you specify a MIDI status or data byte. If you know the numeric value, you can express it directly. For system common and system real-time messages, you can often use the corresponding fields of ShortMessage, such as SYSTEM_RESET. For channel messages, the upper four bits of the status byte are specified by a command value and the lower four bits are specified by a MIDI channel number. To convert incoming MIDI data bytes that are in the form of Java's signed bytes, you can use the conversion code given in the MidiMessage class description.

See Also:
SysexMessage, MetaMessage

Field Summary
static int | ACTIVE_SENSING Status byte for Active Sensing message (0xFE, or 254).
static int | CHANNEL_PRESSURE Command value for Channel Pressure (Aftertouch) message (0xD0, or 208)
static int | CONTINUE Status byte for Continue message (0xFB, or 251).
static int | CONTROL_CHANGE Command value for Control Change message (0xB0, or 176)
static int | END_OF_EXCLUSIVE Status byte for End of System Exclusive message (0xF7, or 247).
static int | MIDI_TIME_CODE Status byte for MIDI Time Code Quarter Frame message (0xF1, or 241).
static int | NOTE_OFF Command value for Note Off message (0x80, or 128)
static int | NOTE_ON Command value for Note On message (0x90, or 144)
static int | PITCH_BEND Command value for Pitch Bend message (0xE0, or 224)
static int | POLY_PRESSURE Command value for Polyphonic Key Pressure (Aftertouch) message (0xA0, or 160)
static int | PROGRAM_CHANGE Command value for Program Change message (0xC0, or 192)
static int | SONG_POSITION_POINTER Status byte for Song Position Pointer message (0xF2, or 242).
static int | SONG_SELECT Status byte for MIDI Song Select message (0xF3, or 243).
static int | START Status byte for Start message (0xFA, or 250).
static int | STOP Status byte for Stop message (0xFC, or 252).
static int | SYSTEM_RESET Status byte for System Reset message (0xFF, or 255).
static int | TIMING_CLOCK Status byte for Timing Clock messagem (0xF8, or 248).
static int | TUNE_REQUEST Status byte for Tune Request message (0xF6, or 246).
Fields inherited from class javax.sound.midi.MidiMessage
data, length
Constructor Summary
 | ShortMessage() Constructs a new ShortMessage.
protected | ShortMessage(byte[] data) Constructs a new ShortMessage.
Method Summary
Object | clone() Creates a new object of the same class and with the same contents as this object.
int | getChannel() Obtains the MIDI channel associated with this event.
int | getCommand() Obtains the MIDI command associated with this event.
int | getData1() Obtains the first data byte in the message.
int | getData2() Obtains the second data byte in the message.
protected int | getDataLength(int status) Retrieves the number of data bytes associated with a particular status byte value.
void | setMessage(int status) Sets the parameters for a MIDI message that takes no data bytes.
void | setMessage(int status, int data1, int data2) Sets the parameters for a MIDI message that takes one or two data bytes.
void | setMessage(int command, int channel, int data1, int data2) Sets the short message parameters for a channel message which takes up to two data bytes.
Methods inherited from class javax.sound.midi.MidiMessage
getLength, getMessage, getStatus, setMessage
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MIDI_TIME_CODE

public static final int MIDI_TIME_CODE
Status byte for MIDI Time Code Quarter Frame message (0xF1, or 241).

See Also:
MidiMessage.getStatus(), Constant Field Values

SONG_POSITION_POINTER

public static final int SONG_POSITION_POINTER
Status byte for Song Position Pointer message (0xF2, or 242).

See Also:
MidiMessage.getStatus(), Constant Field Values

SONG_SELECT

public static final int SONG_SELECT
Status byte for MIDI Song Select message (0xF3, or 243).

See Also:
MidiMessage.getStatus(), Constant Field Values

TUNE_REQUEST

public static final int TUNE_REQUEST
Status byte for Tune Request message (0xF6, or 246).

See Also:
MidiMessage.getStatus(), Constant Field Values

END_OF_EXCLUSIVE

public static final int END_OF_EXCLUSIVE
Status byte for End of System Exclusive message (0xF7, or 247).

See Also:
MidiMessage.getStatus(), Constant Field Values

TIMING_CLOCK

public static final int TIMING_CLOCK
Status byte for Timing Clock messagem (0xF8, or 248).

See Also:
MidiMessage.getStatus(), Constant Field Values

START

public static final int START
Status byte for Start message (0xFA, or 250).

See Also:
MidiMessage.getStatus(), Constant Field Values

CONTINUE

public static final int CONTINUE
Status byte for Continue message (0xFB, or 251).

See Also:
MidiMessage.getStatus(), Constant Field Values

STOP

public static final int STOP
Status byte for Stop message (0xFC, or 252).

See Also:
MidiMessage.getStatus(), Constant Field Values

ACTIVE_SENSING

public static final int ACTIVE_SENSING
Status byte for Active Sensing message (0xFE, or 254).

See Also:
MidiMessage.getStatus(), Constant Field Values

SYSTEM_RESET

public static final int SYSTEM_RESET
Status byte for System Reset message (0xFF, or 255).

See Also:
MidiMessage.getStatus(), Constant Field Values

NOTE_OFF

public static final int NOTE_OFF
Command value for Note Off message (0x80, or 128)

See Also:
Constant Field Values

NOTE_ON

public static final int NOTE_ON
Command value for Note On message (0x90, or 144)

See Also:
Constant Field Values

POLY_PRESSURE

public static final int POLY_PRESSURE
Command value for Polyphonic Key Pressure (Aftertouch) message (0xA0, or 160)

See Also:
Constant Field Values

CONTROL_CHANGE

public static final int CONTROL_CHANGE
Command value for Control Change message (0xB0, or 176)

See Also:
Constant Field Values

PROGRAM_CHANGE

public static final int PROGRAM_CHANGE
Command value for Program Change message (0xC0, or 192)

See Also:
Constant Field Values

CHANNEL_PRESSURE

public static final int CHANNEL_PRESSURE
Command value for Channel Pressure (Aftertouch) message (0xD0, or 208)

See Also:
Constant Field Values

PITCH_BEND

public static final int PITCH_BEND
Command value for Pitch Bend message (0xE0, or 224)

See Also:
Constant Field Values
Constructor Detail

ShortMessage

public ShortMessage()
Constructs a new ShortMessage. The contents of the new message are guaranteed to specify a valid MIDI message. Subsequently, you may set the contents of the message using one of the setMessage methods.

See Also:
setMessage(int)

ShortMessage

protected ShortMessage(byte[] data)
Constructs a new ShortMessage.

Parameters:
data - an array of bytes containing the complete message. The message data may be changed using the setMessage method.
See Also:
setMessage(int)
Method Detail

setMessage

public void setMessage(int status)
                throws InvalidMidiDataException
Sets the parameters for a MIDI message that takes no data bytes.

Parameters:
status - the MIDI status byte
Throws:
InvalidMidiDataException - if status does not specify a valid MIDI status byte for a message that requires no data bytes.
InvalidMidiDataException
See Also:
setMessage(int, int, int), setMessage(int, int, int, int)

setMessage

public void setMessage(int status,
                       int data1,
                       int data2)
                throws InvalidMidiDataException
Sets the parameters for a MIDI message that takes one or two data bytes. If the message takes only one data byte, the second data byte is ignored; if the message does not take any data bytes, both data bytes are ignored.

Parameters:
status - the MIDI status byte
data1 - the first data byte
data2 - the second data byte
Throws:
InvalidMidiDataException - if the the status byte, or all data bytes belonging to the message, do not specify a valid MIDI message.
InvalidMidiDataException
See Also:
setMessage(int, int, int, int), setMessage(int)

setMessage

public void setMessage(int command,
                       int channel,
                       int data1,
                       int data2)
                throws InvalidMidiDataException
Sets the short message parameters for a channel message which takes up to two data bytes. If the message only takes one data byte, the second data byte is ignored; if the message does not take any data bytes, both data bytes are ignored.

Parameters:
command - the MIDI command represented by this message
channel - the channel associated with the message
data1 - the first data byte
data2 - the second data byte
Throws:
InvalidMidiDataException - if the status byte or all data bytes belonging to the message, do not specify a valid MIDI message
InvalidMidiDataException
See Also:
setMessage(int, int, int),
setMessage(int),
getCommand(),
getChannel(),
getData1(),
getData2()

getChannel

public int getChannel()
Obtains the MIDI channel associated with this event. This method assumes that the event is a MIDI channel message; if not, the return value will not be meaningful.

Returns:
MIDI channel associated with the message.
See Also:
setMessage(int, int, int, int)

getCommand

public int getCommand()
Obtains the MIDI command associated with this event. This method assumes that the event is a MIDI channel message; if not, the return value will not be meaningful.

See Also:
setMessage(int, int, int, int)

getData1

public int getData1()
Obtains the first data byte in the message.

Returns:
the value of the data1 field
See Also:
setMessage(int, int, int)

getData2

public int getData2()
Obtains the second data byte in the message.

Returns:
the value of the data2 field
See Also:
setMessage(int, int, int)

clone

public Object clone()
Creates a new object of the same class and with the same contents as this object.

Specified by:
clone in class MidiMessage
Returns:
a clone of this instance.
See Also:
Cloneable

getDataLength

protected final int getDataLength(int status)
                           throws InvalidMidiDataException
Retrieves the number of data bytes associated with a particular status byte value.

Parameters:
status - status byte value, which must represent a short MIDI message
Returns:
data length in bytes (0, 1, or 2)
Throws:
InvalidMidiDataException - if the status argument does not represent the status byte for any short message
InvalidMidiDataException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Soundbank

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Interface Soundbank

public interface Soundbank

A Soundbank contains a set of Instruments that can be loaded into a Synthesizer. Note that a Java Sound Soundbank is different from a MIDI bank. MIDI permits up to 16383 banks, each containing up to 128 instruments (also sometimes called programs, patches, or timbres). However, a Soundbank can contain 16383 times 128 instruments, because the instruments within a Soundbank are indexed by both a MIDI program number and a MIDI bank number (via a Patch object). Thus, a Soundbank can be thought of as a collection of MIDI banks.

Soundbank includes methods that return String objects containing the sound bank's name, manufacturer, version number, and description. The precise content and format of these strings is left to the implementor.

Different synthesizers use a variety of synthesis techniques. A common one is wavetable synthesis, in which a segment of recorded sound is played back, often with looping and pitch change. The Downloadable Sound (DLS) format uses segments of recorded sound, as does the Headspace Engine. Soundbanks and Instruments that are based on wavetable synthesis (or other uses of stored sound recordings) should typically implement the getResources() method to provide access to these recorded segments. This is optional, however; the method can return an zero-length array if the synthesis technique doesn't use sampled sound (FM synthesis and physical modeling are examples of such techniques), or if it does but the implementor chooses not to make the samples accessible.

See Also:
Synthesizer.getDefaultSoundbank(), Synthesizer.isSoundbankSupported(javax.sound.midi.Soundbank), Synthesizer.loadInstruments(Soundbank, Patch[]), Patch, Instrument, SoundbankResource

Method Summary
String | getDescription() Obtains a textual description of the sound bank, suitable for display.
Instrument | getInstrument(Patch patch) Obtains an Instrument from the given Patch.
Instrument[] | getInstruments() Obtains a list of instruments contained in this sound bank.
String | getName() Obtains the name of the sound bank.
SoundbankResource[] | getResources() Extracts a list of non-Instrument resources contained in the sound bank.
String | getVendor() Obtains a string naming the company that provides the sound bank
String | getVersion() Obtains the version string for the sound bank.

Method Detail

getName

String getName()
Obtains the name of the sound bank.

Returns:
a String naming the sound bank

getVersion

String getVersion()
Obtains the version string for the sound bank.

Returns:
a String that indicates the sound bank's version

getVendor

String getVendor()
Obtains a string naming the company that provides the sound bank

Returns:
the vendor string

getDescription

String getDescription()
Obtains a textual description of the sound bank, suitable for display.

Returns:
a String that describes the sound bank

getResources

SoundbankResource[] getResources()
Extracts a list of non-Instrument resources contained in the sound bank.

Returns:
an array of resources, exclusing instruments. If the sound bank contains no resources (other than instruments), returns an array of length 0.

getInstruments

Instrument[] getInstruments()
Obtains a list of instruments contained in this sound bank.

Returns:
an array of the Instruments in this SoundBank If the sound bank contains no instruments, returns an array of length 0.
See Also:
Synthesizer.getLoadedInstruments(), getInstrument(Patch)

getInstrument

Instrument getInstrument(Patch patch)
Obtains an Instrument from the given Patch.

Parameters:
patch - a Patch object specifying the bank index and program change number
Returns:
the requested instrument, or null if the sound bank doesn't contain that instrument
See Also:
getInstruments(), Synthesizer.loadInstruments(Soundbank, Patch[])
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SoundbankResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Class SoundbankResource

java.lang.Object
    extended by  javax.sound.midi.SoundbankResource
Direct Known Subclasses:
Instrument
public abstract class SoundbankResource
extends Object

A SoundbankResource represents any audio resource stored in a Soundbank. Common soundbank resources include:

  • Instruments. An instrument may be specified in a variety of ways. However, all soundbanks have some mechanism for defining instruments. In doing so, they may reference other resources stored in the soundbank. Each instrument has a Patch which specifies the MIDI program and bank by which it may be referenced in MIDI messages. Instrument information may be stored in Instrument objects.
  • Audio samples. A sample typically is a sampled audio waveform which contains a short sound recording whose duration is a fraction of a second, or at most a few seconds. These audio samples may be used by a Synthesizer to synthesize sound in response to MIDI commands, or extracted for use by an application. (The terminology reflects musicians' use of the word "sample" to refer collectively to a series of contiguous audio samples or frames, rather than to a single, instantaneous sample.) The data class for an audio sample will be an object that encapsulates the audio sample data itself and information about how to interpret it (the format of the audio data), such as an AudioInputStream.
  • Embedded sequences. A sound bank may contain built-in song data stored in a data object such as a Sequence.

Synthesizers that use wavetable synthesis or related techniques play back the audio in a sample when synthesizing notes, often when emulating the real-world instrument that was originally recorded. However, there is not necessarily a one-to-one correspondence between the Instruments and samples in a Soundbank. A single Instrument can use multiple SoundbankResources (typically for notes of dissimilar pitch or brightness). Also, more than one Instrument can use the same sample.

Constructor Summary
protected SoundbankResource(Soundbank soundBank, String name, Class<?> dataClass)
Constructs a new SoundbankResource from the given sound bank and wavetable index.
Method Summary
abstract Object | getData() Obtains the sampled audio that is stored in this SoundbankResource.
Class<?> | getDataClass() Obtains the class used by this sample to represent its data.
String | getName() Obtains the name of the resource.
Soundbank | getSoundbank() Obtains the sound bank that contains this SoundbankResource.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SoundbankResource

protected SoundbankResource(Soundbank soundBank,
                            String name,
                            Class<?> dataClass)
Constructs a new SoundbankResource from the given sound bank and wavetable index. (Setting the SoundbankResource's name, sampled audio data, and instruments is a subclass responsibility.)

Parameters:
soundBank - the sound bank containing this SoundbankResource
name - the name of the sample
dataClass - the class used to represent the sample's data
See Also:
getSoundbank(),
getName(),
getDataClass(),
getData()
Method Detail

getSoundbank

public Soundbank getSoundbank()
Obtains the sound bank that contains this SoundbankResource.

Returns:
the sound bank in which this SoundbankResource is stored

getName

public String getName()
Obtains the name of the resource. This should generally be a string descriptive of the resource.

Returns:
the instrument's name

getDataClass

public Class<?> getDataClass()
Obtains the class used by this sample to represent its data. The object returned by getData will be of this class. If this SoundbankResource object does not support direct access to its data, returns null.

Returns:
the class used to represent the sample's data, or null if the data is not accessible

getData

public abstract Object getData()
Obtains the sampled audio that is stored in this SoundbankResource. The type of object returned depends on the implementation of the concrete class, and may be queried using getDataClass.

Returns:
an object containing the sampled audio data
See Also:
getDataClass()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


spi

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.sound.midi.spi

Supplies interfaces for service providers to implement when offering new MIDI devices, MIDI file readers and writers, or sound bank readers.

See:
Description

Class Summary
MidiDeviceProvider | A MidiDeviceProvider is a factory or provider for a particular type of MIDI device.
MidiFileReader | A MidiFileReader supplies MIDI file-reading services.
MidiFileWriter | A MidiFileWriter supplies MIDI file-writing services.
SoundbankReader | A SoundbankReader supplies soundbank file-reading services.

Package javax.sound.midi.spi Description

Supplies interfaces for service providers to implement when offering new MIDI devices, MIDI file readers and writers, or sound bank readers.

Related Documentation

For overviews, tutorials, examples, and guides, please see:
  • Sound

Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.sound.midi.spi Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.sound.midi.spi

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.sound.midi.spi.MidiDeviceProvider
    • javax.sound.midi.spi.MidiFileReader
    • javax.sound.midi.spi.MidiFileWriter
    • javax.sound.midi.spi.SoundbankReader
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.sound.midi.spi

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.sound.midi.spi

No usage of javax.sound.midi.spi

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.spi.MidiDeviceProvider

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.spi.MidiDeviceProvider

No usage of javax.sound.midi.spi.MidiDeviceProvider

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.spi.MidiFileReader

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.spi.MidiFileReader

No usage of javax.sound.midi.spi.MidiFileReader

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.spi.MidiFileWriter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.spi.MidiFileWriter

No usage of javax.sound.midi.spi.MidiFileWriter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.midi.spi.SoundbankReader

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.midi.spi.SoundbankReader

No usage of javax.sound.midi.spi.SoundbankReader

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


MidiDeviceProvider

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi.spi
Class MidiDeviceProvider

java.lang.Object
    extended by  javax.sound.midi.spi.MidiDeviceProvider

public abstract class MidiDeviceProvider
extends Object

A MidiDeviceProvider is a factory or provider for a particular type of MIDI device. This mechanism allows the implementation to determine how resources are managed in the creation and management of a device.

Constructor Summary
MidiDeviceProvider()
Method Summary
abstract MidiDevice | getDevice(MidiDevice.Info info) Obtains an instance of the device represented by the info object.
abstract MidiDevice.Info[] | getDeviceInfo() Obtains the set of info objects representing the device or devices provided by this MidiDeviceProvider.
boolean | isDeviceSupported(MidiDevice.Info info) Indicates whether the device provider supports the device represented by the specified device info object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MidiDeviceProvider

public MidiDeviceProvider()
Method Detail

isDeviceSupported

public boolean isDeviceSupported(MidiDevice.Info info)
Indicates whether the device provider supports the device represented by the specified device info object.

Parameters:
info - an info object that describes the device for which support is queried
Returns:
true if the specified device is supported, otherwise false

getDeviceInfo

public abstract MidiDevice.Info[] getDeviceInfo()
Obtains the set of info objects representing the device or devices provided by this MidiDeviceProvider.

Returns:
set of device info objects

getDevice

public abstract MidiDevice getDevice(MidiDevice.Info info)
Obtains an instance of the device represented by the info object.

Parameters:
info - an info object that describes the desired device
Returns:
device instance
Throws:
IllegalArgumentException - if the info object specified does not match the info object for a device supported by this MidiDeviceProvider.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


MidiFileReader

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi.spi
Class MidiFileReader

java.lang.Object
    extended by  javax.sound.midi.spi.MidiFileReader

public abstract class MidiFileReader
extends Object

A MidiFileReader supplies MIDI file-reading services. Classes implementing this interface can parse the format information from one or more types of MIDI file, and can produce a Sequence object from files of these types.

Since:
1.3

Constructor Summary
MidiFileReader()
Method Summary
abstract MidiFileFormat | getMidiFileFormat(File file) Obtains the MIDI file format of the File provided.
abstract MidiFileFormat | getMidiFileFormat(InputStream stream) Obtains the MIDI file format of the input stream provided.
abstract MidiFileFormat | getMidiFileFormat(URL url) Obtains the MIDI file format of the URL provided.
abstract Sequence | getSequence(File file) Obtains a MIDI sequence from the File provided.
abstract Sequence | getSequence(InputStream stream) Obtains a MIDI sequence from the input stream provided.
abstract Sequence | getSequence(URL url) Obtains a MIDI sequence from the URL provided.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MidiFileReader

public MidiFileReader()
Method Detail

getMidiFileFormat

public abstract MidiFileFormat getMidiFileFormat(InputStream stream)
                                          throws InvalidMidiDataException,
                                                 IOException
Obtains the MIDI file format of the input stream provided. The stream must point to valid MIDI file data. In general, MIDI file readers may need to read some data from the stream before determining whether they support it. These parsers must be able to mark the stream, read enough data to determine whether they support the stream, and, if not, reset the stream's read pointer to its original position. If the input stream does not support this, this method may fail with an IOException.

Parameters:
stream - the input stream from which file format information should be extracted
Returns:
a MidiFileFormat object describing the MIDI file format
Throws:
InvalidMidiDataException - if the stream does not point to valid MIDI file data recognized by the system
IOException - if an I/O exception occurs
See Also:
InputStream.markSupported(), InputStream.mark(int)

getMidiFileFormat

public abstract MidiFileFormat getMidiFileFormat(URL url)
                                          throws InvalidMidiDataException,
                                                 IOException
Obtains the MIDI file format of the URL provided. The URL must point to valid MIDI file data.

Parameters:
url - the URL from which file format information should be extracted
Returns:
a MidiFileFormat object describing the MIDI file format
Throws:
InvalidMidiDataException - if the URL does not point to valid MIDI file data recognized by the system
IOException - if an I/O exception occurs

getMidiFileFormat

public abstract MidiFileFormat getMidiFileFormat(File file)
                                          throws InvalidMidiDataException,
                                                 IOException
Obtains the MIDI file format of the File provided. The File must point to valid MIDI file data.

Parameters:
file - the File from which file format information should be extracted
Returns:
a MidiFileFormat object describing the MIDI file format
Throws:
InvalidMidiDataException - if the File does not point to valid MIDI file data recognized by the system
IOException - if an I/O exception occurs

getSequence

public abstract Sequence getSequence(InputStream stream)
                              throws InvalidMidiDataException,
                                     IOException
Obtains a MIDI sequence from the input stream provided. The stream must point to valid MIDI file data. In general, MIDI file readers may need to read some data from the stream before determining whether they support it. These parsers must be able to mark the stream, read enough data to determine whether they support the stream, and, if not, reset the stream's read pointer to its original position. If the input stream does not support this, this method may fail with an IOException.

Parameters:
stream - the input stream from which the Sequence should be constructed
Returns:
a Sequence object based on the MIDI file data contained in the input stream.
Throws:
InvalidMidiDataException - if the stream does not point to valid MIDI file data recognized by the system
IOException - if an I/O exception occurs
See Also:
InputStream.markSupported(), InputStream.mark(int)

getSequence

public abstract Sequence getSequence(URL url)
                              throws InvalidMidiDataException,
                                     IOException
Obtains a MIDI sequence from the URL provided. The URL must point to valid MIDI file data.

Parameters:
url - the URL for which the Sequence should be constructed
Returns:
a Sequence object based on the MIDI file data pointed to by the URL
Throws:
InvalidMidiDataException - if the URL does not point to valid MIDI file data recognized by the system
IOException - if an I/O exception occurs

getSequence

public abstract Sequence getSequence(File file)
                              throws InvalidMidiDataException,
                                     IOException
Obtains a MIDI sequence from the File provided. The File must point to valid MIDI file data.

Parameters:
file - the File from which the Sequence should be constructed
Returns:
a Sequence object based on the MIDI file data pointed to by the File
Throws:
InvalidMidiDataException - if the File does not point to valid MIDI file data recognized by the system
IOException - if an I/O exception occurs
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MidiFileWriter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi.spi
Class MidiFileWriter

java.lang.Object
    extended by  javax.sound.midi.spi.MidiFileWriter

public abstract class MidiFileWriter
extends Object

A MidiFileWriter supplies MIDI file-writing services. Classes that implement this interface can write one or more types of MIDI file from a Sequence object.

Since:
1.3

Constructor Summary
MidiFileWriter()
Method Summary
abstract int[] | getMidiFileTypes() Obtains the set of MIDI file types for which file writing support is provided by this file writer.
abstract int[] | getMidiFileTypes(Sequence sequence) Obtains the file types that this file writer can write from the sequence specified.
boolean | isFileTypeSupported(int fileType) Indicates whether file writing support for the specified MIDI file type is provided by this file writer.
boolean | isFileTypeSupported(int fileType, Sequence sequence) Indicates whether a MIDI file of the file type specified can be written from the sequence indicated.
abstract int | write(Sequence in, int fileType, File out) Writes a stream of bytes representing a MIDI file of the file type indicated to the external file provided.
abstract int | write(Sequence in, int fileType, OutputStream out) Writes a stream of bytes representing a MIDI file of the file type indicated to the output stream provided.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MidiFileWriter

public MidiFileWriter()
Method Detail

getMidiFileTypes

public abstract int[] getMidiFileTypes()
Obtains the set of MIDI file types for which file writing support is provided by this file writer.

Returns:
array of file types. If no file types are supported, an array of length 0 is returned.

getMidiFileTypes

public abstract int[] getMidiFileTypes(Sequence sequence)
Obtains the file types that this file writer can write from the sequence specified.

Parameters:
sequence - the sequence for which MIDI file type support is queried
Returns:
array of file types. If no file types are supported, returns an array of length 0.

isFileTypeSupported

public boolean isFileTypeSupported(int fileType)
Indicates whether file writing support for the specified MIDI file type is provided by this file writer.

Parameters:
fileType - the file type for which write capabilities are queried
Returns:
true if the file type is supported, otherwise false

isFileTypeSupported

public boolean isFileTypeSupported(int fileType,
                                   Sequence sequence)
Indicates whether a MIDI file of the file type specified can be written from the sequence indicated.

Parameters:
fileType - the file type for which write capabilities are queried
sequence - the sequence for which file writing support is queried
Returns:
true if the file type is supported for this sequence, otherwise false

write

public abstract int write(Sequence in,
                          int fileType,
                          OutputStream out)
                   throws IOException
Writes a stream of bytes representing a MIDI file of the file type indicated to the output stream provided.

Parameters:
in - sequence containing MIDI data to be written to the file
fileType - type of the file to be written to the output stream
out - stream to which the file data should be written
Returns:
the number of bytes written to the output stream
Throws:
IOException - if an I/O exception occurs
IllegalArgumentException - if the file type is not supported by this file writer
See Also:
isFileTypeSupported(int, Sequence), getMidiFileTypes(Sequence)

write

public abstract int write(Sequence in,
                          int fileType,
                          File out)
                   throws IOException
Writes a stream of bytes representing a MIDI file of the file type indicated to the external file provided.

Parameters:
in - sequence containing MIDI data to be written to the external file
fileType - type of the file to be written to the external file
out - external file to which the file data should be written
Returns:
the number of bytes written to the file
Throws:
IOException - if an I/O exception occurs
IllegalArgumentException - if the file type is not supported by this file writer
See Also:
isFileTypeSupported(int, Sequence), getMidiFileTypes(Sequence)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SoundbankReader

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi.spi
Class SoundbankReader

java.lang.Object
    extended by  javax.sound.midi.spi.SoundbankReader

public abstract class SoundbankReader
extends Object

A SoundbankReader supplies soundbank file-reading services. Concrete subclasses of SoundbankReader parse a given soundbank file, producing a Soundbank object that can be loaded into a Synthesizer.

Since:
1.3

Constructor Summary
SoundbankReader()
Method Summary
abstract Soundbank | getSoundbank(File file) Obtains a soundbank object from the File provided.
abstract Soundbank | getSoundbank(InputStream stream) Obtains a soundbank object from the InputStream provided.
abstract Soundbank | getSoundbank(URL url) Obtains a soundbank object from the URL provided.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SoundbankReader

public SoundbankReader()
Method Detail

getSoundbank

public abstract Soundbank getSoundbank(URL url)
                                throws InvalidMidiDataException,
                                       IOException
Obtains a soundbank object from the URL provided.

Parameters:
url - URL representing the soundbank.
Returns:
soundbank object
Throws:
InvalidMidiDataException - if the URL does not point to valid MIDI soundbank data recognized by this soundbank reader
IOException - if an I/O error occurs

getSoundbank

public abstract Soundbank getSoundbank(InputStream stream)
                                throws InvalidMidiDataException,
                                       IOException
Obtains a soundbank object from the InputStream provided.

Parameters:
stream - InputStream representing the soundbank
Returns:
soundbank object
Throws:
InvalidMidiDataException - if the stream does not point to valid MIDI soundbank data recognized by this soundbank reader
IOException - if an I/O error occurs

getSoundbank

public abstract Soundbank getSoundbank(File file)
                                throws InvalidMidiDataException,
                                       IOException
Obtains a soundbank object from the File provided.

Parameters:
file - the File representing the soundbank
Returns:
soundbank object
Throws:
InvalidMidiDataException - if the file does not point to valid MIDI soundbank data recognized by this soundbank reader
IOException - if an I/O error occurs
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Synthesizer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Interface Synthesizer

All Superinterfaces:
MidiDevice
public interface Synthesizer
extends MidiDevice

A Synthesizer generates sound. This usually happens when one of the Synthesizer's MidiChannel objects receives a noteOn message, either directly or via the Synthesizer object. Many Synthesizers support Receivers, through which MIDI events can be delivered to the Synthesizer. In such cases, the Synthesizer typically responds by sending a corresponding message to the appropriate MidiChannel, or by processing the event itself if the event isn't one of the MIDI channel messages.

The Synthesizer interface includes methods for loading and unloading instruments from soundbanks. An instrument is a specification for synthesizing a certain type of sound, whether that sound emulates a traditional instrument or is some kind of sound effect or other imaginary sound. A soundbank is a collection of instruments, organized by bank and program number (via the instrument's Patch object). Different Synthesizer classes might implement different sound-synthesis techniques, meaning that some instruments and not others might be compatible with a given synthesizer. Also, synthesizers may have a limited amount of memory for instruments, meaning that not every soundbank and instrument can be used by every synthesizer, even if the synthesis technique is compatible. To see whether the instruments from a certain soundbank can be played by a given synthesizer, invoke the isSoundbankSupported method of Synthesizer.

"Loading" an instrument means that that instrument becomes available for synthesizing notes. The instrument is loaded into the bank and program location specified by its Patch object. Loading does not necessarily mean that subsequently played notes will immediately have the sound of this newly loaded instrument. For the instrument to play notes, one of the synthesizer's MidiChannel objects must receive (or have received) a program-change message that causes that particular instrument's bank and program number to be selected.

See Also:
MidiSystem.getSynthesizer(), Soundbank, Instrument, MidiChannel.programChange(int, int), Receiver, Transmitter, MidiDevice

Nested Class Summary
Nested classes/interfaces inherited from interface javax.sound.midi.MidiDevice
MidiDevice.Info
Method Summary
Instrument[] | getAvailableInstruments() Obtains a list of instruments that come with the synthesizer.
MidiChannel[] | getChannels() Obtains the set of MIDI channels controlled by this synthesizer.
Soundbank | getDefaultSoundbank() Obtains the default soundbank for the synthesizer, if one exists.
long | getLatency() Obtains the processing latency incurred by this synthesizer, expressed in microseconds.
Instrument[] | getLoadedInstruments() Obtains a list of the instruments that are currently loaded onto this Synthesizer.
int | getMaxPolyphony() Obtains the maximum number of notes that this synthesizer can sound simultaneously.
VoiceStatus[] | getVoiceStatus() Obtains the current status of the voices produced by this synthesizer.
boolean | isSoundbankSupported(Soundbank soundbank) Informs the caller whether this synthesizer is capable of loading instruments from the specified soundbank.
boolean | loadAllInstruments(Soundbank soundbank) Loads onto the Synthesizer all instruments contained in the specified Soundbank.
boolean | loadInstrument(Instrument instrument) Makes a particular instrument available for synthesis.
boolean | loadInstruments(Soundbank soundbank, Patch[] patchList) Loads the instruments referenced by the specified patches, from the specified Soundbank.
boolean | remapInstrument(Instrument from, Instrument to) Remaps an instrument.
void | unloadAllInstruments(Soundbank soundbank) Unloads all instruments contained in the specified Soundbank.
void | unloadInstrument(Instrument instrument) Unloads a particular instrument.
void | unloadInstruments(Soundbank soundbank, Patch[] patchList) Unloads the instruments referenced by the specified patches, from the MIDI sound bank specified.
Methods inherited from interface javax.sound.midi.MidiDevice
close, getDeviceInfo, getMaxReceivers, getMaxTransmitters, getMicrosecondPosition, getReceiver, getReceivers, getTransmitter, getTransmitters, isOpen, open

Method Detail

getMaxPolyphony

int getMaxPolyphony()
Obtains the maximum number of notes that this synthesizer can sound simultaneously.

Returns:
the maximum number of simultaneous notes
See Also:
getVoiceStatus()

getLatency

long getLatency()
Obtains the processing latency incurred by this synthesizer, expressed in microseconds. This latency measures the worst-case delay between the time a MIDI message is delivered to the synthesizer and the time that the synthesizer actually produces the corresponding result.

Although the latency is expressed in microseconds, a synthesizer's actual measured delay may vary over a wider range than this resolution suggests. For example, a synthesizer might have a worst-case delay of a few milliseconds or more.

Returns:
the worst-case delay, in microseconds

getChannels

MidiChannel[] getChannels()
Obtains the set of MIDI channels controlled by this synthesizer. Each non-null element in the returned array is a MidiChannel that receives the MIDI messages sent on that channel number.

The MIDI 1.0 specification provides for 16 channels, so this method returns an array of at least 16 elements. However, if this synthesizer doesn't make use of all 16 channels, some of the elements of the array might be null, so you should check each element before using it.

Returns:
an array of the MidiChannel objects managed by this Synthesizer. Some of the array elements may be null.

getVoiceStatus

VoiceStatus[] getVoiceStatus()
Obtains the current status of the voices produced by this synthesizer. If this class of Synthesizer does not provide voice information, the returned array will always be of length 0. Otherwise, its length is always equal to the total number of voices, as returned by getMaxPolyphony(). (See the VoiceStatus class description for an explanation of synthesizer voices.)

Returns:
an array of VoiceStatus objects that supply information about the corresponding synthesizer voices
See Also:
getMaxPolyphony(), VoiceStatus

isSoundbankSupported

boolean isSoundbankSupported(Soundbank soundbank)
Informs the caller whether this synthesizer is capable of loading instruments from the specified soundbank. If the soundbank is unsupported, any attempts to load instruments from it will result in an IllegalArgumentException.

Parameters:
soundbank - soundbank for which support is queried
Returns:
true if the soundbank is supported, otherwise false
See Also:
loadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[]),
loadAllInstruments(javax.sound.midi.Soundbank),
unloadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[]),
unloadAllInstruments(javax.sound.midi.Soundbank),
getDefaultSoundbank()

loadInstrument

boolean loadInstrument(Instrument instrument)
Makes a particular instrument available for synthesis. This instrument is loaded into the patch location specified by its Patch object, so that if a program-change message is received (or has been received) that causes that patch to be selected, subsequent notes will be played using the sound of instrument. If the specified instrument is already loaded, this method does nothing and returns true.

The instrument must be part of a soundbank that this Synthesizer supports. (To make sure, you can use the getSoundbank method of Instrument and the isSoundbankSupported method of Synthesizer.)

Parameters:
instrument - instrument to load
Returns:
true if the instrument is successfully loaded (or already had been), false if the instrument could not be loaded (for example, if the synthesizer has insufficient memory to load it)
Throws:
IllegalArgumentException - if this Synthesizer doesn't support the specified instrument's soundbank
See Also:
unloadInstrument(javax.sound.midi.Instrument),
loadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[]),
loadAllInstruments(javax.sound.midi.Soundbank),
remapInstrument(javax.sound.midi.Instrument, javax.sound.midi.Instrument),
SoundbankResource.getSoundbank(),
MidiChannel.programChange(int, int)

unloadInstrument

void unloadInstrument(Instrument instrument)
Unloads a particular instrument.

Parameters:
instrument - instrument to unload
Throws:
IllegalArgumentException - if this Synthesizer doesn't support the specified instrument's soundbank
See Also:
loadInstrument(javax.sound.midi.Instrument),
unloadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[]),
unloadAllInstruments(javax.sound.midi.Soundbank),
getLoadedInstruments(),
remapInstrument(javax.sound.midi.Instrument, javax.sound.midi.Instrument)

remapInstrument

boolean remapInstrument(Instrument from,
                        Instrument to)
Remaps an instrument. Instrument to takes the place of instrument from.
For example, if from was located at bank number 2, program number 11, remapping causes that bank and program location to be occupied instead by to.
If the function succeeds, instrument from is unloaded.

To cancel the remapping reload instrument from by invoking one of loadInstrument(javax.sound.midi.Instrument), loadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[]) or loadAllInstruments(javax.sound.midi.Soundbank).

Parameters:
from - the Instrument object to be replaced
to - the Instrument object to be used in place of the old instrument, it should be loaded into the synthesizer
Returns:
true if the instrument succeessfully remapped, false if feature is not implemented by synthesizer
Throws:
IllegalArgumentException - if instrument from or instrument to aren't supported by synthesizer or if instrument to is not loaded
NullPointerException - if from or to parameters have null value
See Also:
loadInstrument(javax.sound.midi.Instrument),
loadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[]),
loadAllInstruments(javax.sound.midi.Soundbank)

getDefaultSoundbank

Soundbank getDefaultSoundbank()
Obtains the default soundbank for the synthesizer, if one exists. (Some synthesizers provide a default or built-in soundbank.) If a synthesizer doesn't have a default soundbank, instruments must be loaded explicitly from an external soundbank.

Returns:
default soundbank, or null if one does not exist.
See Also:
isSoundbankSupported(javax.sound.midi.Soundbank)

getAvailableInstruments

Instrument[] getAvailableInstruments()
Obtains a list of instruments that come with the synthesizer. These instruments might be built into the synthesizer, or they might be part of a default soundbank provided with the synthesizer, etc.

Note that you don't use this method to find out which instruments are currently loaded onto the synthesizer; for that purpose, you use getLoadedInstruments(). Nor does the method indicate all the instruments that can be loaded onto the synthesizer; it only indicates the subset that come with the synthesizer. To learn whether another instrument can be loaded, you can invoke isSoundbankSupported(), and if the instrument's Soundbank is supported, you can try loading the instrument.

Returns:
list of available instruments.
See Also:
getLoadedInstruments(), isSoundbankSupported(Soundbank), loadInstrument(javax.sound.midi.Instrument)

getLoadedInstruments

Instrument[] getLoadedInstruments()
Obtains a list of the instruments that are currently loaded onto this Synthesizer.

Returns:
a list of currently loaded instruments
See Also:
loadInstrument(javax.sound.midi.Instrument),
getAvailableInstruments(),
Soundbank.getInstruments()

loadAllInstruments

boolean loadAllInstruments(Soundbank soundbank)
Loads onto the Synthesizer all instruments contained in the specified Soundbank.

Parameters:
soundbank - the Soundbank whose are instruments are to be loaded
Returns:
true if the instruments are all successfully loaded (or already had been), false if any instrument could not be loaded (for example, if the Synthesizer had insufficient memory)
Throws:
IllegalArgumentException - if the requested soundbank is incompatible with this synthesizer.
See Also:
isSoundbankSupported(javax.sound.midi.Soundbank),
loadInstrument(javax.sound.midi.Instrument),
loadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[])

unloadAllInstruments

void unloadAllInstruments(Soundbank soundbank)
Unloads all instruments contained in the specified Soundbank.

Parameters:
soundbank - soundbank containing instruments to unload
Throws:
IllegalArgumentException - thrown if the soundbank is not supported.
See Also:
isSoundbankSupported(javax.sound.midi.Soundbank),
unloadInstrument(javax.sound.midi.Instrument),
unloadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[])

loadInstruments

boolean loadInstruments(Soundbank soundbank,
                        Patch[] patchList)
Loads the instruments referenced by the specified patches, from the specified Soundbank. Each of the Patch objects indicates a bank and program number; the Instrument that has the matching Patch is loaded into that bank and program location.

Parameters:
soundbank - the Soundbank containing the instruments to load
patchList - list of patches for which instruments should be loaded
Returns:
true if the instruments are all successfully loaded (or already had been), false if any instrument could not be loaded (for example, if the Synthesizer had insufficient memory)
Throws:
IllegalArgumentException - thrown if the soundbank is not supported.
See Also:
isSoundbankSupported(javax.sound.midi.Soundbank),
Instrument.getPatch(),
loadAllInstruments(javax.sound.midi.Soundbank),
loadInstrument(javax.sound.midi.Instrument),
Soundbank.getInstrument(Patch),
Sequence.getPatchList()

unloadInstruments

void unloadInstruments(Soundbank soundbank,
                       Patch[] patchList)
Unloads the instruments referenced by the specified patches, from the MIDI sound bank specified.

Parameters:
soundbank - soundbank containing instruments to unload
patchList - list of patches for which instruments should be unloaded
Throws:
IllegalArgumentException - thrown if the soundbank is not supported.
See Also:
unloadInstrument(javax.sound.midi.Instrument),
unloadAllInstruments(javax.sound.midi.Soundbank),
isSoundbankSupported(javax.sound.midi.Soundbank),
Instrument.getPatch(),
loadInstruments(javax.sound.midi.Soundbank, javax.sound.midi.Patch[])
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SysexMessage

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Class SysexMessage

java.lang.Object
    extended by  javax.sound.midi.MidiMessage
        extended by  javax.sound.midi.SysexMessage
All Implemented Interfaces:
Cloneable
public class SysexMessage
extends MidiMessage

A SysexMessage object represents a MIDI system exclusive message.

When a system exclusive message is read from a MIDI file, it always has a defined length. Data from a system exclusive message from a MIDI file should be stored in the data array of a SysexMessage as follows: the system exclusive message status byte (0xF0 or 0xF7), all message data bytes, and finally the end-of-exclusive flag (0xF7). The length reported by the SysexMessage object is therefore the length of the system exclusive data plus two: one byte for the status byte and one for the end-of-exclusive flag.

As dictated by the Standard MIDI Files specification, two status byte values are legal for a SysexMessage read from a MIDI file:

  • 0xF0: System Exclusive message (same as in MIDI wire protocol)
  • 0xF7: Special System Exclusive message

When Java Sound is used to handle system exclusive data that is being received using MIDI wire protocol, it should place the data in one or more SysexMessages. In this case, the length of the system exclusive data is not known in advance; the end of the system exclusive data is marked by an end-of-exclusive flag (0xF7) in the MIDI wire byte stream.

  • 0xF0: System Exclusive message (same as in MIDI wire protocol)
  • 0xF7: End of Exclusive (EOX)
The first SysexMessage object containing data for a particular system exclusive message should have the status value 0xF0. If this message contains all the system exclusive data for the message, it should end with the status byte 0xF7 (EOX). Otherwise, additional system exclusive data should be sent in one or more SysexMessages with a status value of 0xF7. The SysexMessage containing the last of the data for the system exclusive message should end with the value 0xF7 (EOX) to mark the end of the system exclusive message.

If system exclusive data from SysexMessages objects is being transmitted using MIDI wire protocol, only the initial 0xF0 status byte, the system exclusive data itself, and the final 0xF7 (EOX) byte should be propagated; any 0xF7 status bytes used to indicate that a SysexMessage contains continuing system exclusive data should not be propagated via MIDI wire protocol.

Field Summary
static int | SPECIAL_SYSTEM_EXCLUSIVE Status byte for Special System Exclusive message (0xF7, or 247), which is used in MIDI files.
static int | SYSTEM_EXCLUSIVE Status byte for System Exclusive message (0xF0, or 240).
Fields inherited from class javax.sound.midi.MidiMessage
data, length
Constructor Summary
 | SysexMessage() Constructs a new SysexMessage.
protected | SysexMessage(byte[] data) Constructs a new SysexMessage.
Method Summary
Object | clone() Creates a new object of the same class and with the same contents as this object.
byte[] | getData() Obtains a copy of the data for the system exclusive message.
void | setMessage(byte[] data, int length) Sets the data for the system exclusive message.
void | setMessage(int status, byte[] data, int length) Sets the data for the system exclusive message.
Methods inherited from class javax.sound.midi.MidiMessage
getLength, getMessage, getStatus
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SYSTEM_EXCLUSIVE

public static final int SYSTEM_EXCLUSIVE
Status byte for System Exclusive message (0xF0, or 240).

See Also:
MidiMessage.getStatus(), Constant Field Values

SPECIAL_SYSTEM_EXCLUSIVE

public static final int SPECIAL_SYSTEM_EXCLUSIVE
Status byte for Special System Exclusive message (0xF7, or 247), which is used in MIDI files. It has the same value as END_OF_EXCLUSIVE, which is used in the real-time "MIDI wire" protocol.

See Also:
MidiMessage.getStatus(), Constant Field Values
Constructor Detail

SysexMessage

public SysexMessage()
Constructs a new SysexMessage. The contents of the new message are guaranteed to specify a valid MIDI message. Subsequently, you may set the contents of the message using one of the setMessage methods.

See Also:
setMessage(byte[], int)

SysexMessage

protected SysexMessage(byte[] data)
Constructs a new SysexMessage.

Parameters:
data - an array of bytes containing the complete message. The message data may be changed using the setMessage method.
See Also:
setMessage(byte[], int)
Method Detail

setMessage

public void setMessage(byte[] data,
                       int length)
                throws InvalidMidiDataException
Sets the data for the system exclusive message. The first byte of the data array must be a valid system exclusive status byte (0xF0 or 0xF7).

Overrides:
setMessage in class MidiMessage
Parameters:
data - the system exclusive message data
length - the length of the valid message data in the array, including the status byte.
Throws:
InvalidMidiDataException

setMessage

public void setMessage(int status,
                       byte[] data,
                       int length)
                throws InvalidMidiDataException
Sets the data for the system exclusive message.

Parameters:
status - the status byte for the message (0xF0 or 0xF7)
data - the system exclusive message data
length - the length of the valid message data in the array
Throws:
InvalidMidiDataException

getData

public byte[] getData()
Obtains a copy of the data for the system exclusive message. The returned array of bytes does not include the status byte.

Returns:
array containing the system exclusive message data.

clone

public Object clone()
Creates a new object of the same class and with the same contents as this object.

Specified by:
clone in class MidiMessage
Returns:
a clone of this instance
See Also:
Cloneable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Track

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Class Track

java.lang.Object
    extended by  javax.sound.midi.Track

public class Track
extends Object

A MIDI track is an independent stream of MIDI events (time-stamped MIDI data) that can be stored along with other tracks in a standard MIDI file. The MIDI specification allows only 16 channels of MIDI data, but tracks are a way to get around this limitation. A MIDI file can contain any number of tracks, each containing its own stream of up to 16 channels of MIDI data.

A Track occupies a middle level in the hierarchy of data played by a Sequencer: sequencers play sequences, which contain tracks, which contain MIDI events. A sequencer may provide controls that mute or solo individual tracks.

The timing information and resolution for a track is controlled by and stored in the sequence containing the track. A given Track is considered to belong to the particular Sequence that maintains its timing. For this reason, a new (empty) track is created by calling the Sequence.createTrack() method, rather than by directly invoking a Track constructor.

The Track class provides methods to edit the track by adding or removing MidiEvent objects from it. These operations keep the event list in the correct time order. Methods are also included to obtain the track's size, in terms of either the number of events it contains or its duration in ticks.

See Also:
Sequencer.setTrackMute(int, boolean), Sequencer.setTrackSolo(int, boolean)

Method Summary
boolean | add(MidiEvent event) Adds a new event to the track.
MidiEvent | get(int index) Obtains the event at the specified index.
boolean | remove(MidiEvent event) Removes the specified event from the track.
int | size() Obtains the number of events in this track.
long | ticks() Obtains the length of the track, expressed in MIDI ticks.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

add

public boolean add(MidiEvent event)
Adds a new event to the track. However, if the event is already contained in the track, it is not added again. The list of events is kept in time order, meaning that this event inserted at the appropriate place in the list, not necessarily at the end.

Parameters:
event - the event to add
Returns:
true if the event did not already exist in the track and was added, otherwise false

remove

public boolean remove(MidiEvent event)
Removes the specified event from the track.

Parameters:
event - the event to remove
Returns:
true if the event existed in the track and was removed, otherwise false

get

public MidiEvent get(int index)
              throws ArrayIndexOutOfBoundsException
Obtains the event at the specified index.

Parameters:
index - the location of the desired event in the event vector
Throws:
ArrayIndexOutOfBoundsException - if the specified index is negative or not less than the current size of this track.
ArrayIndexOutOfBoundsException
See Also:
size()

size

public int size()
Obtains the number of events in this track.

Returns:
the size of the track's event vector

ticks

public long ticks()
Obtains the length of the track, expressed in MIDI ticks. (The duration of a tick in seconds is determined by the timing resolution of the Sequence containing this track, and also by the tempo of the music as set by the sequencer.)

Returns:
the duration, in ticks
See Also:
Sequence.Sequence(float, int),
Sequencer.setTempoInBPM(float),
Sequencer.getTickPosition()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Transmitter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Interface Transmitter

public interface Transmitter

A Transmitter sends MidiEvent objects to one or more Receivers. Common MIDI transmitters include sequencers and MIDI input ports.

See Also:
Receiver

Method Summary
void | close() Indicates that the application has finished using the transmitter, and that limited resources it requires may be released or made available.
Receiver | getReceiver() Obtains the current receiver to which this transmitter will deliver MIDI messages.
void | setReceiver(Receiver receiver) Sets the receiver to which this transmitter will deliver MIDI messages.

Method Detail

setReceiver

void setReceiver(Receiver receiver)
Sets the receiver to which this transmitter will deliver MIDI messages. If a receiver is currently set, it is replaced with this one.

Parameters:
receiver - the desired receiver.

getReceiver

Receiver getReceiver()
Obtains the current receiver to which this transmitter will deliver MIDI messages.

Returns:
the current receiver. If no receiver is currently set, returns null

close

void close()
Indicates that the application has finished using the transmitter, and that limited resources it requires may be released or made available.

If the creation of this Transmitter resulted in implicitly opening the underlying device, the device is implicitly closed by this method. This is true unless the device is kept open by other Receiver or Transmitter instances that opened the device implicitly, and unless the device has been opened explicitly. If the device this Transmitter is retrieved from is closed explicitly by calling MidiDevice.close, the Transmitter is closed, too. For a detailed description of open/close behaviour see the class description of MidiDevice.

See Also:
MidiSystem.getTransmitter()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VoiceStatus

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.sound.midi
Class VoiceStatus

java.lang.Object
    extended by  javax.sound.midi.VoiceStatus

public class VoiceStatus
extends Object

A VoiceStatus object contains information about the current status of one of the voices produced by a Synthesizer.

MIDI synthesizers are generally capable of producing some maximum number of simultaneous notes, also referred to as voices. A voice is a stream of successive single notes, and the process of assigning incoming MIDI notes to specific voices is known as voice allocation. However, the voice-allocation algorithm and the contents of each voice are normally internal to a MIDI synthesizer and hidden from outside view. One can, of course, learn from MIDI messages which notes the synthesizer is playing, and one might be able deduce something about the assignment of notes to voices. But MIDI itself does not provide a means to report which notes a synthesizer has assigned to which voice, nor even to report how many voices the synthesizer is capable of synthesizing.

In Java Sound, however, a Synthesizer class can expose the contents of its voices through its getVoiceStatus() method. This behavior is recommended but optional; synthesizers that don't expose their voice allocation simply return a zero-length array. A Synthesizer that does report its voice status should maintain this information at all times for all of its voices, whether they are currently sounding or not. In other words, a given type of Synthesizer always has a fixed number of voices, equal to the maximum number of simultaneous notes it is capable of sounding.

If the voice is not currently processing a MIDI note, it is considered inactive. A voice is inactive when it has been given no note-on commands, or when every note-on command received has been terminated by a corresponding note-off (or by an "all notes off" message). For example, this happens when a synthesizer capable of playing 16 simultaneous notes is told to play a four-note chord; only four voices are active in this case (assuming no earlier notes are still playing). Usually, a voice whose status is reported as active is producing audible sound, but this is not always true; it depends on the details of the instrument (that is, the synthesis algorithm) and how long the note has been going on. For example, a voice may be synthesizing the sound of a single hand-clap. Because this sound dies away so quickly, it may become inaudible before a note-off message is received. In such a situation, the voice is still considered active even though no sound is currently being produced.

Besides its active or inactive status, the VoiceStatus class provides fields that reveal the voice's current MIDI channel, bank and program number, MIDI note number, and MIDI volume. All of these can change during the course of a voice. While the voice is inactive, each of these fields has an unspecified value, so you should check the active field first.

See Also:
Synthesizer.getMaxPolyphony(), Synthesizer.getVoiceStatus()

Field Summary
boolean | active Indicates whether the voice is currently processing a MIDI note.
int | bank The bank number of the instrument that this voice is currently using.
int | channel The MIDI channel on which this voice is playing.
int | note The MIDI note that this voice is playing.
int | program The program number of the instrument that this voice is currently using.
int | volume The current MIDI volume level for the voice.
Constructor Summary
VoiceStatus()
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

active

public boolean active
Indicates whether the voice is currently processing a MIDI note. See the explanation of active and inactive voices.

channel

public int channel
The MIDI channel on which this voice is playing. The value is a zero-based channel number if the voice is active, or unspecified if the voice is inactive.

See Also:
MidiChannel, active

bank

public int bank
The bank number of the instrument that this voice is currently using. This is a number dictated by the MIDI bank-select message; it does not refer to a SoundBank object. The value ranges from 0 to 16383 if the voice is active, and is unspecified if the voice is inactive.

See Also:
Patch, Soundbank, active, MidiChannel.programChange(int, int)

program

public int program
The program number of the instrument that this voice is currently using. The value ranges from 0 to 127 if the voice is active, and is unspecified if the voice is inactive.

See Also:
MidiChannel.getProgram(), Patch, active

note

public int note
The MIDI note that this voice is playing. The range for an active voice is from 0 to 127 in semitones, with 60 referring to Middle C. The value is unspecified if the voice is inactive.

See Also:
MidiChannel.noteOn(int, int), active

volume

public int volume
The current MIDI volume level for the voice. The value ranges from 0 to 127 if the voice is active, and is unspecified if the voice is inactive.

Note that this value does not necessarily reflect the instantaneous level of the sound produced by this voice; that level is the result of many contributing factors, including the current instrument and the shape of the amplitude envelope it produces.

See Also:
active
Constructor Detail

VoiceStatus

public VoiceStatus()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


sampled

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.sound.sampled

Provides interfaces and classes for capture, processing, and playback of sampled audio data.

See:
Description

Interface Summary
Clip | The Clip interface represents a special kind of data line whose audio data can be loaded prior to playback, instead of being streamed in real time.
DataLine | DataLine adds media-related functionality to its superinterface, Line.
Line | The Line interface represents a mono or multi-channel audio feed.
LineListener | Instances of classes that implement the LineListener interface can register to receive events when a line's status changes.
Mixer | A mixer is an audio device with one or more lines.
Port | Ports are simple lines for input or output of audio to or from audio devices.
SourceDataLine | A source data line is a data line to which data may be written.
TargetDataLine | A target data line is a type of DataLine from which audio data can be read.

Class Summary
AudioFileFormat | An instance of the AudioFileFormat class describes an audio file, including the file type, the file's length in bytes, the length in sample frames of the audio data contained in the file, and the format of the audio data.
AudioFileFormat.Type | An instance of the Type class represents one of the standard types of audio file.
AudioFormat | AudioFormat is the class that specifies a particular arrangement of data in a sound stream.
AudioFormat.Encoding | The Encoding class names the specific type of data representation used for an audio stream.
AudioInputStream | An audio input stream is an input stream with a specified audio format and length.
AudioPermission | The AudioPermission class represents access rights to the audio system resources.
AudioSystem | The AudioSystem class acts as the entry point to the sampled-audio system resources.
BooleanControl | A BooleanControl provides the ability to switch between two possible settings that affect a line's audio.
BooleanControl.Type | An instance of the BooleanControl.Type class identifies one kind of boolean control.
CompoundControl | A CompoundControl, such as a graphic equalizer, provides control over two or more related properties, each of which is itself represented as a Control.
CompoundControl.Type | An instance of the CompoundControl.Type inner class identifies one kind of compound control.
Control | Lines often have a set of controls, such as gain and pan, that affect the audio signal passing through the line.
Control.Type | An instance of the Type class represents the type of the control.
DataLine.Info | Besides the class information inherited from its superclass, DataLine.Info provides additional information specific to data lines.
EnumControl | A EnumControl provides control over a set of discrete possible values, each represented by an object.
EnumControl.Type | An instance of the EnumControl.Type inner class identifies one kind of enumerated control.
FloatControl | A FloatControl object provides control over a range of floating-point values.
FloatControl.Type | An instance of the FloatControl.Type inner class identifies one kind of float control.
Line.Info | A Line.Info object contains information about a line.
LineEvent | The LineEvent class encapsulates information that a line sends its listeners whenever the line opens, closes, starts, or stops.
LineEvent.Type | The LineEvent.Type inner class identifies what kind of event occurred on a line.
Mixer.Info | The Mixer.Info class represents information about an audio mixer, including the product's name, version, and vendor, along with a textual description.
Port.Info | The Port.Info class extends Line.Info with additional information specific to ports, including the port's name and whether it is a source or a target for its mixer.
ReverbType | The ReverbType class provides methods for accessing various reverberation settings to be applied to an audio signal.

Exception Summary
LineUnavailableException | A LineUnavailableException is an exception indicating that a line cannot be opened because it is unavailable.
UnsupportedAudioFileException | An UnsupportedAudioFileException is an exception indicating that an operation failed because a file did not contain valid data of a recognized file type and format.

Package javax.sound.sampled Description

Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Related Documentation

For overviews, tutorials, examples, and guides, please see:
  • Sound

Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.sound.sampled Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.sound.sampled

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.sound.sampled.AudioFileFormat
    • javax.sound.sampled.AudioFileFormat.Type
    • javax.sound.sampled.AudioFormat
    • javax.sound.sampled.AudioFormat.Encoding
    • javax.sound.sampled.AudioSystem
    • javax.sound.sampled.Control
      • javax.sound.sampled.BooleanControl
      • javax.sound.sampled.CompoundControl
      • javax.sound.sampled.EnumControl
      • javax.sound.sampled.FloatControl
    • javax.sound.sampled.Control.Type
      • javax.sound.sampled.BooleanControl.Type
      • javax.sound.sampled.CompoundControl.Type
      • javax.sound.sampled.EnumControl.Type
      • javax.sound.sampled.FloatControl.Type
    • java.util.EventObject (implements java.io.Serializable)
      • javax.sound.sampled.LineEvent
    • java.io.InputStream (implements java.io.Closeable)
      • javax.sound.sampled.AudioInputStream
    • javax.sound.sampled.Line.Info
      • javax.sound.sampled.DataLine.Info
      • javax.sound.sampled.Port.Info
    • javax.sound.sampled.LineEvent.Type
    • javax.sound.sampled.Mixer.Info
    • java.security.Permission (implements java.security.Guard, java.io.Serializable)
      • java.security.BasicPermission (implements java.io.Serializable)
        • javax.sound.sampled.AudioPermission
    • javax.sound.sampled.ReverbType
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.sound.sampled.LineUnavailableException
        • javax.sound.sampled.UnsupportedAudioFileException

Interface Hierarchy

  • java.util.EventListener
    • javax.sound.sampled.LineListener
  • javax.sound.sampled.Line
    • javax.sound.sampled.DataLine
      • javax.sound.sampled.Clip
      • javax.sound.sampled.SourceDataLine
      • javax.sound.sampled.TargetDataLine
    • javax.sound.sampled.Mixer
    • javax.sound.sampled.Port
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.sound.sampled

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.sound.sampled

Packages that use javax.sound.sampled
javax.sound.sampled | Provides interfaces and classes for capture, processing, and playback of sampled audio data.
javax.sound.sampled.spi | Supplies abstract classes for service providers to subclass when offering new audio devices, sound file readers and writers, or audio format converters.

Classes in javax.sound.sampled used by javax.sound.sampled
AudioFileFormat
An instance of the AudioFileFormat class describes an audio file, including the file type, the file's length in bytes, the length in sample frames of the audio data contained in the file, and the format of the audio data.
AudioFileFormat.Type
An instance of the Type class represents one of the standard types of audio file.
AudioFormat
AudioFormat is the class that specifies a particular arrangement of data in a sound stream.
AudioFormat.Encoding
The Encoding class names the specific type of data representation used for an audio stream.
AudioInputStream
An audio input stream is an input stream with a specified audio format and length.
BooleanControl.Type
An instance of the BooleanControl.Type class identifies one kind of boolean control.
Clip
The Clip interface represents a special kind of data line whose audio data can be loaded prior to playback, instead of being streamed in real time.
CompoundControl.Type
An instance of the CompoundControl.Type inner class identifies one kind of compound control.
Control
Lines often have a set of controls, such as gain and pan, that affect the audio signal passing through the line.
Control.Type
An instance of the Type class represents the type of the control.
DataLine
DataLine adds media-related functionality to its superinterface, Line.
EnumControl.Type
An instance of the EnumControl.Type inner class identifies one kind of enumerated control.
FloatControl.Type
An instance of the FloatControl.Type inner class identifies one kind of float control.
Line
The Line interface represents a mono or multi-channel audio feed.
Line.Info
A Line.Info object contains information about a line.
LineEvent
The LineEvent class encapsulates information that a line sends its listeners whenever the line opens, closes, starts, or stops.
LineEvent.Type
The LineEvent.Type inner class identifies what kind of event occurred on a line.
LineListener
Instances of classes that implement the LineListener interface can register to receive events when a line's status changes.
LineUnavailableException
A LineUnavailableException is an exception indicating that a line cannot be opened because it is unavailable.
Mixer
A mixer is an audio device with one or more lines.
Mixer.Info
The Mixer.Info class represents information about an audio mixer, including the product's name, version, and vendor, along with a textual description.
Port.Info
The Port.Info class extends Line.Info with additional information specific to ports, including the port's name and whether it is a source or a target for its mixer.
SourceDataLine
A source data line is a data line to which data may be written.
TargetDataLine
A target data line is a type of DataLine from which audio data can be read.
UnsupportedAudioFileException
An UnsupportedAudioFileException is an exception indicating that an operation failed because a file did not contain valid data of a recognized file type and format.

Classes in javax.sound.sampled used by javax.sound.sampled.spi
AudioFileFormat
An instance of the AudioFileFormat class describes an audio file, including the file type, the file's length in bytes, the length in sample frames of the audio data contained in the file, and the format of the audio data.
AudioFileFormat.Type
An instance of the Type class represents one of the standard types of audio file.
AudioFormat
AudioFormat is the class that specifies a particular arrangement of data in a sound stream.
AudioFormat.Encoding
The Encoding class names the specific type of data representation used for an audio stream.
AudioInputStream
An audio input stream is an input stream with a specified audio format and length.
Mixer
A mixer is an audio device with one or more lines.
Mixer.Info
The Mixer.Info class represents information about an audio mixer, including the product's name, version, and vendor, along with a textual description.
UnsupportedAudioFileException
An UnsupportedAudioFileException is an exception indicating that an operation failed because a file did not contain valid data of a recognized file type and format.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AudioFileFormat

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class AudioFileFormat

java.lang.Object
    extended by  javax.sound.sampled.AudioFileFormat

public class AudioFileFormat
extends Object

An instance of the AudioFileFormat class describes an audio file, including the file type, the file's length in bytes, the length in sample frames of the audio data contained in the file, and the format of the audio data.

The AudioSystem class includes methods for determining the format of an audio file, obtaining an audio input stream from an audio file, and writing an audio file from an audio input stream.

An AudioFileFormat object can include a set of properties. A property is a pair of key and value: the key is of type String, the associated property value is an arbitrary object. Properties specify additional informational meta data (like a author, copyright, or file duration). Properties are optional information, and file reader and file writer implementations are not required to provide or recognize properties.

The following table lists some common properties that should be used in implementations:
Property key | Value type | Description
"duration" | Long | playback duration of the file in microseconds
"author" | String | name of the author of this file
"title" | String | title of this file
"copyright" | String | copyright message
"date" | Date | date of the recording or release
"comment" | String | an arbitrary text

Since:
1.3
See Also:
AudioInputStream

Nested Class Summary
static class AudioFileFormat.Type
An instance of the Type class represents one of the standard types of audio file.
Constructor Summary
 | AudioFileFormat(AudioFileFormat.Type type, AudioFormat format, int frameLength) Constructs an audio file format object.
 | AudioFileFormat(AudioFileFormat.Type type, AudioFormat format, int frameLength, Map<String,Object> properties) Construct an audio file format object with a set of defined properties.
protected | AudioFileFormat(AudioFileFormat.Type type, int byteLength, AudioFormat format, int frameLength) Constructs an audio file format object.
Method Summary
int | getByteLength() Obtains the size in bytes of the entire audio file (not just its audio data).
AudioFormat | getFormat() Obtains the format of the audio data contained in the audio file.
int | getFrameLength() Obtains the length of the audio data contained in the file, expressed in sample frames.
Object | getProperty(String key) Obtain the property value specified by the key.
AudioFileFormat.Type | getType() Obtains the audio file type, such as WAVE or AU.
Map<String,Object> | properties() Obtain an unmodifiable map of properties.
String | toString() Provides a string representation of the file format.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AudioFileFormat

protected AudioFileFormat(AudioFileFormat.Type type,
                          int byteLength,
                          AudioFormat format,
                          int frameLength)
Constructs an audio file format object. This protected constructor is intended for use by providers of file-reading services when returning information about an audio file or about supported audio file formats.

Parameters:
type - the type of the audio file
byteLength - the length of the file in bytes, or AudioSystem.NOT_SPECIFIED
format - the format of the audio data contained in the file
frameLength - the audio data length in sample frames, or AudioSystem.NOT_SPECIFIED
See Also:
getType()

AudioFileFormat

public AudioFileFormat(AudioFileFormat.Type type,
                       AudioFormat format,
                       int frameLength)
Constructs an audio file format object. This public constructor may be used by applications to describe the properties of a requested audio file.

Parameters:
type - the type of the audio file
format - the format of the audio data contained in the file
frameLength - the audio data length in sample frames, or AudioSystem.NOT_SPECIFIED

AudioFileFormat

public AudioFileFormat(AudioFileFormat.Type type,
                       AudioFormat format,
                       int frameLength,
                       Map<String,Object> properties)
Construct an audio file format object with a set of defined properties. This public constructor may be used by applications to describe the properties of a requested audio file. The properties map will be copied to prevent any changes to it.

Parameters:
type - the type of the audio file
format - the format of the audio data contained in the file
frameLength - the audio data length in sample frames, or AudioSystem.NOT_SPECIFIED
properties - a Map<String,Object> object with properties
Since:
1.5
Method Detail

getType

public AudioFileFormat.Type getType()
Obtains the audio file type, such as WAVE or AU.

Returns:
the audio file type
See Also:
AudioFileFormat.Type.WAVE, AudioFileFormat.Type.AU, AudioFileFormat.Type.AIFF, AudioFileFormat.Type.AIFC, AudioFileFormat.Type.SND

getByteLength

public int getByteLength()
Obtains the size in bytes of the entire audio file (not just its audio data).

Returns:
the audio file length in bytes
See Also:
AudioSystem.NOT_SPECIFIED

getFormat

public AudioFormat getFormat()
Obtains the format of the audio data contained in the audio file.

Returns:
the audio data format

getFrameLength

public int getFrameLength()
Obtains the length of the audio data contained in the file, expressed in sample frames.

Returns:
the number of sample frames of audio data in the file
See Also:
AudioSystem.NOT_SPECIFIED

properties

public Map<String,Object> properties()
Obtain an unmodifiable map of properties. The concept of properties is further explained in the class description.

Returns:
a Map<String,Object> object containing all properties. If no properties are recognized, an empty map is returned.
Since:
1.5
See Also:
getProperty(String)

getProperty

public Object getProperty(String key)
Obtain the property value specified by the key. The concept of properties is further explained in the class description.

If the specified property is not defined for a particular file format, this method returns null.

Parameters:
key - the key of the desired property
Returns:
the value of the property with the specified key, or null if the property does not exist.
Since:
1.5
See Also:
properties

toString

public String toString()
Provides a string representation of the file format.

Overrides:
toString in class Object
Returns:
the file format as a string
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AudioFileFormat.Type

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class AudioFileFormat.Type

java.lang.Object
    extended by  javax.sound.sampled.AudioFileFormat.Type
Enclosing class:
AudioFileFormat
public static class AudioFileFormat.Type
extends Object

An instance of the Type class represents one of the standard types of audio file. Static instances are provided for the common types.

Field Summary
static AudioFileFormat.Type | AIFC Specifies an AIFF-C file.
static AudioFileFormat.Type | AIFF Specifies an AIFF file.
static AudioFileFormat.Type | AU Specifies an AU file.
static AudioFileFormat.Type | SND Specifies a SND file.
static AudioFileFormat.Type | WAVE Specifies a WAVE file.
Constructor Summary
AudioFileFormat.Type(String name, String extension)
Constructs a file type.
Method Summary
boolean | equals(Object obj) Finalizes the equals method
String | getExtension() Obtains the common file name extension for this file type.
int | hashCode() Finalizes the hashCode method
String | toString() Provides the file type's name as the String representation of the file type.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

WAVE

public static final AudioFileFormat.Type WAVE
Specifies a WAVE file.

AU

public static final AudioFileFormat.Type AU
Specifies an AU file.

AIFF

public static final AudioFileFormat.Type AIFF
Specifies an AIFF file.

AIFC

public static final AudioFileFormat.Type AIFC
Specifies an AIFF-C file.

SND

public static final AudioFileFormat.Type SND
Specifies a SND file.

Constructor Detail

AudioFileFormat.Type

public AudioFileFormat.Type(String name,
                            String extension)
Constructs a file type.

Parameters:
name - the string that names the file type
extension - the string that commonly marks the file type without leading dot.
Method Detail

equals

public final boolean equals(Object obj)
Finalizes the equals method

Overrides:
equals in class Object
Parameters:
obj - the reference object with which to compare.
Returns:
true if this object is the same as the obj argument; false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

public final int hashCode()
Finalizes the hashCode method

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public final String toString()
Provides the file type's name as the String representation of the file type.

Overrides:
toString in class Object
Returns:
the file type's name

getExtension

public String getExtension()
Obtains the common file name extension for this file type.

Returns:
file type extension
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AudioFormat

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class AudioFormat

java.lang.Object
    extended by  javax.sound.sampled.AudioFormat

public class AudioFormat
extends Object

AudioFormat is the class that specifies a particular arrangement of data in a sound stream. By examing the information stored in the audio format, you can discover how to interpret the bits in the binary sound data.

Every data line has an audio format associated with its data stream. The audio format of a source (playback) data line indicates what kind of data the data line expects to receive for output. For a target (capture) data line, the audio format specifies the kind of the data that can be read from the line. Sound files also have audio formats, of course. The AudioFileFormat class encapsulates an AudioFormat in addition to other, file-specific information. Similarly, an AudioInputStream has an AudioFormat.

The AudioFormat class accommodates a number of common sound-file encoding techniques, including pulse-code modulation (PCM), mu-law encoding, and a-law encoding. These encoding techniques are predefined, but service providers can create new encoding types. The encoding that a specific format uses is named by its encoding field.

In addition to the encoding, the audio format includes other properties that further specify the exact arrangement of the data. These include the number of channels, sample rate, sample size, byte order, frame rate, and frame size. Sounds may have different numbers of audio channels: one for mono, two for stereo. The sample rate measures how many "snapshots" (samples) of the sound pressure are taken per second, per channel. (If the sound is stereo rather than mono, two samples are actually measured at each instant of time: one for the left channel, and another for the right channel; however, the sample rate still measures the number per channel, so the rate is the same regardless of the number of channels. This is the standard use of the term.) The sample size indicates how many bits are used to store each snapshot; 8 and 16 are typical values. For 16-bit samples (or any other sample size larger than a byte), byte order is important; the bytes in each sample are arranged in either the "little-endian" or "big-endian" style. For encodings like PCM, a frame consists of the set of samples for all channels at a given point in time, and so the size of a frame (in bytes) is always equal to the size of a sample (in bytes) times the number of channels. However, with some other sorts of encodings a frame can contain a bundle of compressed data for a whole series of samples, as well as additional, non-sample data. For such encodings, the sample rate and sample size refer to the data after it is decoded into PCM, and so they are completely different from the frame rate and frame size.

An AudioFormat object can include a set of properties. A property is a pair of key and value: the key is of type String, the associated property value is an arbitrary object. Properties specify additional format specifications, like the bit rate for compressed formats. Properties are mainly used as a means to transport additional information of the audio format to and from the service providers. Therefore, properties are ignored in the matches(AudioFormat) method. However, methods which rely on the installed service providers, like (AudioFormat, AudioFormat) isConversionSupported may consider properties, depending on the respective service provider implementation.

The following table lists some common properties which service providers should use, if applicable:
Property key | Value type | Description
"bitrate" | Integer | average bit rate in bits per second
"vbr" | Boolean | true, if the file is encoded in variable bit rate (VBR)
"quality" | Integer | encoding/conversion quality, 1..100

Vendors of service providers (plugins) are encouraged to seek information about other already established properties in third party plugins, and follow the same conventions.

Since:
1.3
See Also:
DataLine.getFormat(), AudioInputStream.getFormat(), AudioFileFormat, FormatConversionProvider

Nested Class Summary
static class AudioFormat.Encoding
The Encoding class names the specific type of data representation used for an audio stream.
Field Summary
protected boolean | bigEndian Indicates whether the audio data is stored in big-endian or little-endian order.
protected int | channels The number of audio channels in this format (1 for mono, 2 for stereo).
protected AudioFormat.Encoding | encoding The audio encoding technique used by this format.
protected float | frameRate The number of frames played or recorded per second, for sounds that have this format.
protected int | frameSize The number of bytes in each frame of a sound that has this format.
protected float | sampleRate The number of samples played or recorded per second, for sounds that have this format.
protected int | sampleSizeInBits The number of bits in each sample of a sound that has this format.
Constructor Summary
AudioFormat(AudioFormat.Encoding encoding, float sampleRate, int sampleSizeInBits, int channels, int frameSize, float frameRate, boolean bigEndian)
Constructs an AudioFormat with the given parameters.
AudioFormat(AudioFormat.Encoding encoding, float sampleRate, int sampleSizeInBits, int channels, int frameSize, float frameRate, boolean bigEndian, Map<String,Object> properties)
Constructs an AudioFormat with the given parameters.
AudioFormat(float sampleRate, int sampleSizeInBits, int channels, boolean signed, boolean bigEndian)
Constructs an AudioFormat with a linear PCM encoding and the given parameters.
Method Summary
int | getChannels() Obtains the number of channels.
AudioFormat.Encoding | getEncoding() Obtains the type of encoding for sounds in this format.
float | getFrameRate() Obtains the frame rate in frames per second.
int | getFrameSize() Obtains the frame size in bytes.
Object | getProperty(String key) Obtain the property value specified by the key.
float | getSampleRate() Obtains the sample rate.
int | getSampleSizeInBits() Obtains the size of a sample.
boolean | isBigEndian() Indicates whether the audio data is stored in big-endian or little-endian byte order.
boolean | matches(AudioFormat format) Indicates whether this format matches the one specified.
Map<String,Object> | properties() Obtain an unmodifiable map of properties.
String | toString() Returns a string that describes the format, such as: "PCM SIGNED 22050 Hz 16 bit mono big-endian".
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

encoding

protected AudioFormat.Encoding encoding
The audio encoding technique used by this format.

sampleRate

protected float sampleRate
The number of samples played or recorded per second, for sounds that have this format.

sampleSizeInBits

protected int sampleSizeInBits
The number of bits in each sample of a sound that has this format.

channels

protected int channels
The number of audio channels in this format (1 for mono, 2 for stereo).

frameSize

protected int frameSize
The number of bytes in each frame of a sound that has this format.

frameRate

protected float frameRate
The number of frames played or recorded per second, for sounds that have this format.

bigEndian

protected boolean bigEndian
Indicates whether the audio data is stored in big-endian or little-endian order.

Constructor Detail

AudioFormat

public AudioFormat(AudioFormat.Encoding encoding,
                   float sampleRate,
                   int sampleSizeInBits,
                   int channels,
                   int frameSize,
                   float frameRate,
                   boolean bigEndian)
Constructs an AudioFormat with the given parameters. The encoding specifies the convention used to represent the data. The other parameters are further explained in the class description.

Parameters:
encoding - the audio encoding technique
sampleRate - the number of samples per second
sampleSizeInBits - the number of bits in each sample
channels - the number of channels (1 for mono, 2 for stereo, and so on)
frameSize - the number of bytes in each frame
frameRate - the number of frames per second
bigEndian - indicates whether the data for a single sample is stored in big-endian byte order (false means little-endian)

AudioFormat

public AudioFormat(AudioFormat.Encoding encoding,
                   float sampleRate,
                   int sampleSizeInBits,
                   int channels,
                   int frameSize,
                   float frameRate,
                   boolean bigEndian,
                   Map<String,Object> properties)
Constructs an AudioFormat with the given parameters. The encoding specifies the convention used to represent the data. The other parameters are further explained in the class description.

Parameters:
encoding - the audio encoding technique
sampleRate - the number of samples per second
sampleSizeInBits - the number of bits in each sample
channels - the number of channels (1 for mono, 2 for stereo, and so on)
frameSize - the number of bytes in each frame
frameRate - the number of frames per second
bigEndian - indicates whether the data for a single sample is stored in big-endian byte order (false means little-endian)
properties - a Map<String,Object> object containing format properties
Since:
1.5

AudioFormat

public AudioFormat(float sampleRate,
                   int sampleSizeInBits,
                   int channels,
                   boolean signed,
                   boolean bigEndian)
Constructs an AudioFormat with a linear PCM encoding and the given parameters. The frame size is set to the number of bytes required to contain one sample from each channel, and the frame rate is set to the sample rate.

Parameters:
sampleRate - the number of samples per second
sampleSizeInBits - the number of bits in each sample
channels - the number of channels (1 for mono, 2 for stereo, and so on)
signed - indicates whether the data is signed or unsigned
bigEndian - indicates whether the data for a single sample is stored in big-endian byte order (false means little-endian)
Method Detail

getEncoding

public AudioFormat.Encoding getEncoding()
Obtains the type of encoding for sounds in this format.

Returns:
the encoding type
See Also:
AudioFormat.Encoding.PCM_SIGNED, AudioFormat.Encoding.PCM_UNSIGNED, AudioFormat.Encoding.ULAW, AudioFormat.Encoding.ALAW

getSampleRate

public float getSampleRate()
Obtains the sample rate. For compressed formats, the return value is the sample rate of the uncompressed audio data. When this AudioFormat is used for queries (e.g. AudioSystem.isConversionSupported) or capabilities (e.g. DataLine.Info.getFormats), a sample rate of AudioSystem.NOT_SPECIFIED means that any sample rate is acceptable. AudioSystem.NOT_SPECIFIED is also returned when the sample rate is not defined for this audio format.

Returns:
the number of samples per second, or AudioSystem.NOT_SPECIFIED
See Also:
getFrameRate(), AudioSystem.NOT_SPECIFIED

getSampleSizeInBits

public int getSampleSizeInBits()
Obtains the size of a sample. For compressed formats, the return value is the sample size of the uncompressed audio data. When this AudioFormat is used for queries (e.g. AudioSystem.isConversionSupported) or capabilities (e.g. DataLine.Info.getFormats), a sample size of AudioSystem.NOT_SPECIFIED means that any sample size is acceptable. AudioSystem.NOT_SPECIFIED is also returned when the sample size is not defined for this audio format.

Returns:
the number of bits in each sample, or AudioSystem.NOT_SPECIFIED
See Also:
getFrameSize(), AudioSystem.NOT_SPECIFIED

getChannels

public int getChannels()
Obtains the number of channels. When this AudioFormat is used for queries (e.g. AudioSystem.isConversionSupported) or capabilities (e.g. DataLine.Info.getFormats), a return value of AudioSystem.NOT_SPECIFIED means that any (positive) number of channels is acceptable.

Returns:
The number of channels (1 for mono, 2 for stereo, etc.), or AudioSystem.NOT_SPECIFIED
See Also:
AudioSystem.NOT_SPECIFIED

getFrameSize

public int getFrameSize()
Obtains the frame size in bytes. When this AudioFormat is used for queries (e.g. AudioSystem.isConversionSupported) or capabilities (e.g. DataLine.Info.getFormats), a frame size of AudioSystem.NOT_SPECIFIED means that any frame size is acceptable. AudioSystem.NOT_SPECIFIED is also returned when the frame size is not defined for this audio format.

Returns:
the number of bytes per frame, or AudioSystem.NOT_SPECIFIED
See Also:
getSampleSizeInBits(), AudioSystem.NOT_SPECIFIED

getFrameRate

public float getFrameRate()
Obtains the frame rate in frames per second. When this AudioFormat is used for queries (e.g. AudioSystem.isConversionSupported) or capabilities (e.g. DataLine.Info.getFormats), a frame rate of AudioSystem.NOT_SPECIFIED means that any frame rate is acceptable. AudioSystem.NOT_SPECIFIED is also returned when the frame rate is not defined for this audio format.

Returns:
the number of frames per second, or AudioSystem.NOT_SPECIFIED
See Also:
getSampleRate(), AudioSystem.NOT_SPECIFIED

isBigEndian

public boolean isBigEndian()
Indicates whether the audio data is stored in big-endian or little-endian byte order. If the sample size is not more than one byte, the return value is irrelevant.

Returns:
true if the data is stored in big-endian byte order, false if little-endian

properties

public Map<String,Object> properties()
Obtain an unmodifiable map of properties. The concept of properties is further explained in the class description.

Returns:
a Map<String,Object> object containing all properties. If no properties are recognized, an empty map is returned.
Since:
1.5
See Also:
getProperty(String)

getProperty

public Object getProperty(String key)
Obtain the property value specified by the key. The concept of properties is further explained in the class description.

If the specified property is not defined for a particular file format, this method returns null.

Parameters:
key - the key of the desired property
Returns:
the value of the property with the specified key, or null if the property does not exist.
Since:
1.5
See Also:
properties

matches

public boolean matches(AudioFormat format)
Indicates whether this format matches the one specified. To match, two formats must have the same encoding, the same number of channels, and the same number of bits per sample and bytes per frame. The two formats must also have the same sample rate, unless the specified format has the sample rate value AudioSystem.NOT_SPECIFIED, which any sample rate will match. The frame rates must similarly be equal, unless the specified format has the frame rate value AudioSystem.NOT_SPECIFIED. The byte order (big-endian or little-endian) must match if the sample size is greater than one byte.

Parameters:
format - format to test for match
Returns:
true if this format matches the one specified, false otherwise.

toString

public String toString()
Returns a string that describes the format, such as: "PCM SIGNED 22050 Hz 16 bit mono big-endian". The contents of the string may vary between implementations of Java Sound.

Overrides:
toString in class Object
Returns:
a string that describes the format parameters
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AudioFormat.Encoding

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class AudioFormat.Encoding

java.lang.Object
    extended by  javax.sound.sampled.AudioFormat.Encoding
Enclosing class:
AudioFormat
public static class AudioFormat.Encoding
extends Object

The Encoding class names the specific type of data representation used for an audio stream. The encoding includes aspects of the sound format other than the number of channels, sample rate, sample size, frame rate, frame size, and byte order.

One ubiquitous type of audio encoding is pulse-code modulation (PCM), which is simply a linear (proportional) representation of the sound waveform. With PCM, the number stored in each sample is proportional to the instantaneous amplitude of the sound pressure at that point in time. The numbers are frequently signed or unsigned integers. Besides PCM, other encodings include mu-law and a-law, which are nonlinear mappings of the sound amplitude that are often used for recording speech.

You can use a predefined encoding by referring to one of the static objects created by this class, such as PCM_SIGNED or PCM_UNSIGNED. Service providers can create new encodings, such as compressed audio formats or floating-point PCM samples, and make these available through the AudioSystem class.

The Encoding class is static, so that all AudioFormat objects that have the same encoding will refer to the same object (rather than different instances of the same class). This allows matches to be made by checking that two format's encodings are equal.

Since:
1.3
See Also:
AudioFormat, FormatConversionProvider

Field Summary
static AudioFormat.Encoding | ALAW Specifies a-law encoded data.
static AudioFormat.Encoding | PCM_SIGNED Specifies signed, linear PCM data.
static AudioFormat.Encoding | PCM_UNSIGNED Specifies unsigned, linear PCM data.
static AudioFormat.Encoding | ULAW Specifies u-law encoded data.
Constructor Summary
AudioFormat.Encoding(String name)
Constructs a new encoding.
Method Summary
boolean | equals(Object obj) Finalizes the equals method
int | hashCode() Finalizes the hashCode method
String | toString() Provides the String representation of the encoding.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

PCM_SIGNED

public static final AudioFormat.Encoding PCM_SIGNED
Specifies signed, linear PCM data.

PCM_UNSIGNED

public static final AudioFormat.Encoding PCM_UNSIGNED
Specifies unsigned, linear PCM data.

ULAW

public static final AudioFormat.Encoding ULAW
Specifies u-law encoded data.

ALAW

public static final AudioFormat.Encoding ALAW
Specifies a-law encoded data.

Constructor Detail

AudioFormat.Encoding

public AudioFormat.Encoding(String name)
Constructs a new encoding.

Parameters:
name - the name of the new type of encoding
Method Detail

equals

public final boolean equals(Object obj)
Finalizes the equals method

Overrides:
equals in class Object
Parameters:
obj - the reference object with which to compare.
Returns:
true if this object is the same as the obj argument; false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

public final int hashCode()
Finalizes the hashCode method

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public final String toString()
Provides the String representation of the encoding. This String is the same name that was passed to the constructor. For the predefined encodings, the name is similar to the encoding's variable (field) name. For example, PCM_SIGNED.toString() returns the name "pcm_signed".

Overrides:
toString in class Object
Returns:
the encoding name
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AudioInputStream

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class AudioInputStream

java.lang.Object
    extended by  java.io.InputStream
        extended by  javax.sound.sampled.AudioInputStream
All Implemented Interfaces:
Closeable
public class AudioInputStream
extends InputStream

An audio input stream is an input stream with a specified audio format and length. The length is expressed in sample frames, not bytes. Several methods are provided for reading a certain number of bytes from the stream, or an unspecified number of bytes. The audio input stream keeps track of the last byte that was read. You can skip over an arbitrary number of bytes to get to a later position for reading. An audio input stream may support marks. When you set a mark, the current position is remembered so that you can return to it later.

The AudioSystem class includes many methods that manipulate AudioInputStream objects. For example, the methods let you:

  • obtain an audio input stream from an external audio file, stream, or URL
  • write an external file from an audio input stream
  • convert an audio input stream to a different audio format

Since:
1.3
See Also:
AudioSystem, Clip.open(AudioInputStream)

Field Summary
protected AudioFormat | format The format of the audio data contained in the stream.
protected long | frameLength This stream's length, in sample frames.
protected long | framePos The current position in this stream, in sample frames (zero-based).
protected int | frameSize The size of each frame, in bytes.
Constructor Summary
AudioInputStream(InputStream stream, AudioFormat format, long length)
Constructs an audio input stream that has the requested format and length in sample frames, using audio data from the specified input stream.
AudioInputStream(TargetDataLine line)
Constructs an audio input stream that reads its data from the target data line indicated.
Method Summary
int | available() Returns the maximum number of bytes that can be read (or skipped over) from this audio input stream without blocking.
void | close() Closes this audio input stream and releases any system resources associated with the stream.
AudioFormat | getFormat() Obtains the audio format of the sound data in this audio input stream.
long | getFrameLength() Obtains the length of the stream, expressed in sample frames rather than bytes.
void | mark(int readlimit) Marks the current position in this audio input stream.
boolean | markSupported() Tests whether this audio input stream supports the mark and reset methods.
int | read() Reads the next byte of data from the audio input stream.
int | read(byte[] b) Reads some number of bytes from the audio input stream and stores them into the buffer array b.
int | read(byte[] b, int off, int len) Reads up to a specified maximum number of bytes of data from the audio stream, putting them into the given byte array.
void | reset() Repositions this audio input stream to the position it had at the time its mark method was last invoked.
long | skip(long n) Skips over and discards a specified number of bytes from this audio input stream.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

format

protected AudioFormat format
The format of the audio data contained in the stream.

frameLength

protected long frameLength
This stream's length, in sample frames.

frameSize

protected int frameSize
The size of each frame, in bytes.

framePos

protected long framePos
The current position in this stream, in sample frames (zero-based).

Constructor Detail

AudioInputStream

public AudioInputStream(InputStream stream,
                        AudioFormat format,
                        long length)
Constructs an audio input stream that has the requested format and length in sample frames, using audio data from the specified input stream.

Parameters:
stream - the stream on which this AudioInputStream object is based
format - the format of this stream's audio data
length - the length in sample frames of the data in this stream

AudioInputStream

public AudioInputStream(TargetDataLine line)
Constructs an audio input stream that reads its data from the target data line indicated. The format of the stream is the same as that of the target data line, and the length is AudioSystem#NOT_SPECIFIED.

Parameters:
line - the target data line from which this stream obtains its data.
See Also:
AudioSystem.NOT_SPECIFIED
Method Detail

getFormat

public AudioFormat getFormat()
Obtains the audio format of the sound data in this audio input stream.

Returns:
an audio format object describing this stream's format

getFrameLength

public long getFrameLength()
Obtains the length of the stream, expressed in sample frames rather than bytes.

Returns:
the length in sample frames

read

public int read()
         throws IOException
Reads the next byte of data from the audio input stream. The audio input stream's frame size must be one byte, or an IOException will be thrown.

Specified by:
read in class InputStream
Returns:
the next byte of data, or -1 if the end of the stream is reached
Throws:
IOException - if an input or output error occurs
See Also:
read(byte[], int, int), read(byte[]),

read

public int read(byte[] b)
         throws IOException
Reads some number of bytes from the audio input stream and stores them into the buffer array b. The number of bytes actually read is returned as an integer. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.

This method will always read an integral number of frames. If the length of the array is not an integral number of frames, a maximum of b.length - (b.length % frameSize) bytes will be read.

Overrides:
read in class InputStream
Parameters:
b - the buffer into which the data is read
Returns:
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached
Throws:
IOException - if an input or output error occurs
See Also:
read(byte[], int, int),
read(),
available()

read

public int read(byte[] b,
                int off,
                int len)
         throws IOException
Reads up to a specified maximum number of bytes of data from the audio stream, putting them into the given byte array.

This method will always read an integral number of frames. If len does not specify an integral number of frames, a maximum of len - (len % frameSize) bytes will be read.

Overrides:
read in class InputStream
Parameters:
b - the buffer into which the data is read
off - the offset, from the beginning of array b, at which the data will be written
len - the maximum number of bytes to read
Returns:
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached
Throws:
IOException - if an input or output error occurs
See Also:
read(byte[]), read(), skip(long), available()

skip

public long skip(long n)
          throws IOException
Skips over and discards a specified number of bytes from this audio input stream.

Overrides:
skip in class InputStream
Parameters:
n - the requested number of bytes to be skipped
Returns:
the actual number of bytes skipped
Throws:
IOException - if an input or output error occurs
See Also:
read(), available()

available

public int available()
              throws IOException
Returns the maximum number of bytes that can be read (or skipped over) from this audio input stream without blocking. This limit applies only to the next invocation of a read or skip method for this audio input stream; the limit can vary each time these methods are invoked. Depending on the underlying stream,an IOException may be thrown if this stream is closed.

Overrides:
available in class InputStream
Returns:
the number of bytes that can be read from this audio input stream without blocking
Throws:
IOException - if an input or output error occurs
See Also:
read(byte[], int, int), read(byte[]), read(), skip(long)

close

public void close()
           throws IOException
Closes this audio input stream and releases any system resources associated with the stream.

Specified by:
close in interface Closeable
Overrides:
close in class InputStream
Throws:
IOException - if an input or output error occurs

mark

public void mark(int readlimit)
Marks the current position in this audio input stream.

Overrides:
mark in class InputStream
Parameters:
readlimit - the maximum number of bytes that can be read before the mark position becomes invalid.
See Also:
reset(), markSupported()

reset

public void reset()
           throws IOException
Repositions this audio input stream to the position it had at the time its mark method was last invoked.

Overrides:
reset in class InputStream
Throws:
IOException - if an input or output error occurs.
See Also:
mark(int), markSupported()

markSupported

public boolean markSupported()
Tests whether this audio input stream supports the mark and reset methods.

Overrides:
markSupported in class InputStream
Returns:
true if this stream supports the mark and reset methods; false otherwise
See Also:
mark(int), reset()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AudioPermission

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class AudioPermission

java.lang.Object
    extended by  java.security.Permission
        extended by  java.security.BasicPermission
            extended by  javax.sound.sampled.AudioPermission
All Implemented Interfaces:
Serializable, Guard
public class AudioPermission
extends BasicPermission

The AudioPermission class represents access rights to the audio system resources. An AudioPermission contains a target name but no actions list; you either have the named permission or you don't.

The target name is the name of the audio permission (see the table below). The names follow the hierarchical property-naming convention. Also, an asterisk can be used to represent all the audio permissions.

The following table lists the possible AudioPermission target names. For each name, the table provides a description of exactly what that permission allows, as well as a discussion of the risks of granting code the permission.

Permission Target Name | What the Permission Allows | Risks of Allowing this Permission
play | Audio playback through the audio device or devices on the system. Allows the application to obtain and manipulate lines and mixers for audio playback (rendering). | In some cases use of this permission may affect other applications because the audio from one line may be mixed with other audio being played on the system, or because manipulation of a mixer affects the audio for all lines using that mixer.
record | Audio recording through the audio device or devices on the system. Allows the application to obtain and manipulate lines and mixers for audio recording (capture). | In some cases use of this permission may affect other applications because manipulation of a mixer affects the audio for all lines using that mixer. This permission can enable an applet or application to eavesdrop on a user.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
AudioPermission(String name)
Creates a new AudioPermission object that has the specified symbolic name, such as "play" or "record".
AudioPermission(String name, String actions)
Creates a new AudioPermission object that has the specified symbolic name, such as "play" or "record".
Method Summary
Methods inherited from class java.security.BasicPermission
equals, getActions, hashCode, implies, newPermissionCollection
Methods inherited from class java.security.Permission
checkGuard, getName, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

AudioPermission

public AudioPermission(String name)
Creates a new AudioPermission object that has the specified symbolic name, such as "play" or "record". An asterisk can be used to indicate all audio permissions.

Parameters:
name - the name of the new AudioPermission
Throws:
NullPointerException - if name is null.
IllegalArgumentException - if name is empty.

AudioPermission

public AudioPermission(String name,
                       String actions)
Creates a new AudioPermission object that has the specified symbolic name, such as "play" or "record". The actions parameter is currently unused and should be null.

Parameters:
name - the name of the new AudioPermission
actions - (unused; should be null)
Throws:
NullPointerException - if name is null.
IllegalArgumentException - if name is empty.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AudioSystem

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class AudioSystem

java.lang.Object
    extended by  javax.sound.sampled.AudioSystem

public class AudioSystem
extends Object

The AudioSystem class acts as the entry point to the sampled-audio system resources. This class lets you query and access the mixers that are installed on the system. AudioSystem includes a number of methods for converting audio data between different formats, and for translating between audio files and streams. It also provides a method for obtaining a Line directly from the AudioSystem without dealing explicitly with mixers.

Properties can be used to specify the default mixer for specific line types. Both system properties and a properties file are considered. In the Sun reference implementation, the properties file is "lib/sound.properties" in the JRE directory. If a property exists both as a system property and in the properties file, the system property takes precedence. If none is specified, a suitable default is chosen among the available devices. The syntax of the properties file is specified in Properties.load. The following table lists the available property keys and which methods consider them:
Property Key | Interface | Affected Method(s)
javax.sound.sampled.Clip | Clip | getLine(javax.sound.sampled.Line.Info), getClip()
javax.sound.sampled.Port | Port | getLine(javax.sound.sampled.Line.Info)
javax.sound.sampled.SourceDataLine | SourceDataLine | getLine(javax.sound.sampled.Line.Info), getSourceDataLine(javax.sound.sampled.AudioFormat)
javax.sound.sampled.TargetDataLine | TargetDataLine | getLine(javax.sound.sampled.Line.Info), getTargetDataLine(javax.sound.sampled.AudioFormat)
The property value consists of the provider class name and the mixer name, separated by the hash mark ("#"). The provider class name is the fully-qualified name of a concrete mixer provider class. The mixer name is matched against the String returned by the getName method of Mixer.Info. Either the class name, or the mixer name may be omitted. If only the class name is specified, the trailing hash mark is optional.

If the provider class is specified, and it can be successully retrieved from the installed providers, the list of Mixer.Info objects is retrieved from the provider. Otherwise, or when these mixers do not provide a subsequent match, the list is retrieved from getMixerInfo() to contain all available Mixer.Info objects.

If a mixer name is specified, the resulting list of Mixer.Info objects is searched: the first one with a matching name, and whose Mixer provides the respective line interface, will be returned. If no matching Mixer.Info object is found, or the mixer name is not specified, the first mixer from the resulting list, which provides the respective line interface, will be returned. For example, the property javax.sound.sampled.Clip with a value "com.sun.media.sound.MixerProvider#SunClip" will have the following consequences when getLine is called requesting a Clip instance: if the class com.sun.media.sound.MixerProvider exists in the list of installed mixer providers, the first Clip from the first mixer with name "SunClip" will be returned. If it cannot be found, the first Clip from the first mixer of the specified provider will be returned, regardless of name. If there is none, the first Clip from the first Mixer with name "SunClip" in the list of all mixers (as returned by getMixerInfo) will be returned, or, if not found, the first Clip of the first Mixerthat can be found in the list of all mixers is returned. If that fails, too, an IllegalArgumentException is thrown.

Since:
1.3
See Also:
AudioFormat, AudioInputStream, Mixer, Line, Line.Info

Field Summary
static int NOT_SPECIFIED
An integer that stands for an unknown numeric value.
Method Summary
static AudioFileFormat | getAudioFileFormat(File file) Obtains the audio file format of the specified File.
static AudioFileFormat | getAudioFileFormat(InputStream stream) Obtains the audio file format of the provided input stream.
static AudioFileFormat | getAudioFileFormat(URL url) Obtains the audio file format of the specified URL.
static AudioFileFormat.Type[] | getAudioFileTypes() Obtains the file types for which file writing support is provided by the system.
static AudioFileFormat.Type[] | getAudioFileTypes(AudioInputStream stream) Obtains the file types that the system can write from the audio input stream specified.
static AudioInputStream | getAudioInputStream(AudioFormat.Encoding targetEncoding, AudioInputStream sourceStream) Obtains an audio input stream of the indicated encoding, by converting the provided audio input stream.
static AudioInputStream | getAudioInputStream(AudioFormat targetFormat, AudioInputStream sourceStream) Obtains an audio input stream of the indicated format, by converting the provided audio input stream.
static AudioInputStream | getAudioInputStream(File file) Obtains an audio input stream from the provided File.
static AudioInputStream | getAudioInputStream(InputStream stream) Obtains an audio input stream from the provided input stream.
static AudioInputStream | getAudioInputStream(URL url) Obtains an audio input stream from the URL provided.
static Clip | getClip() Obtains a clip that can be used for playing back an audio file or an audio stream.
static Clip | getClip(Mixer.Info mixerInfo) Obtains a clip from the specified mixer that can be used for playing back an audio file or an audio stream.
static Line | getLine(Line.Info info) Obtains a line that matches the description in the specified Line.Info object.
static Mixer | getMixer(Mixer.Info info) Obtains the requested audio mixer.
static Mixer.Info[] | getMixerInfo() Obtains an array of mixer info objects that represents the set of audio mixers that are currently installed on the system.
static SourceDataLine | getSourceDataLine(AudioFormat format) Obtains a source data line that can be used for playing back audio data in the format specified by the AudioFormat object.
static SourceDataLine | getSourceDataLine(AudioFormat format, Mixer.Info mixerinfo) Obtains a source data line that can be used for playing back audio data in the format specified by the AudioFormat object, provided by the mixer specified by the Mixer.Info object.
static Line.Info[] | getSourceLineInfo(Line.Info info) Obtains information about all source lines of a particular type that are supported by the installed mixers.
static TargetDataLine | getTargetDataLine(AudioFormat format) Obtains a target data line that can be used for recording audio data in the format specified by the AudioFormat object.
static TargetDataLine | getTargetDataLine(AudioFormat format, Mixer.Info mixerinfo) Obtains a target data line that can be used for recording audio data in the format specified by the AudioFormat object, provided by the mixer specified by the Mixer.Info object.
static AudioFormat.Encoding[] | getTargetEncodings(AudioFormat.Encoding sourceEncoding) Obtains the encodings that the system can obtain from an audio input stream with the specified encoding using the set of installed format converters.
static AudioFormat.Encoding[] | getTargetEncodings(AudioFormat sourceFormat) Obtains the encodings that the system can obtain from an audio input stream with the specified format using the set of installed format converters.
static AudioFormat[] | getTargetFormats(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) Obtains the formats that have a particular encoding and that the system can obtain from a stream of the specified format using the set of installed format converters.
static Line.Info[] | getTargetLineInfo(Line.Info info) Obtains information about all target lines of a particular type that are supported by the installed mixers.
static boolean | isConversionSupported(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) Indicates whether an audio input stream of the specified encoding can be obtained from an audio input stream that has the specified format.
static boolean | isConversionSupported(AudioFormat targetFormat, AudioFormat sourceFormat) Indicates whether an audio input stream of a specified format can be obtained from an audio input stream of another specified format.
static boolean | isFileTypeSupported(AudioFileFormat.Type fileType) Indicates whether file writing support for the specified file type is provided by the system.
static boolean | isFileTypeSupported(AudioFileFormat.Type fileType, AudioInputStream stream) Indicates whether an audio file of the specified file type can be written from the indicated audio input stream.
static boolean | isLineSupported(Line.Info info) Indicates whether the system supports any lines that match the specified Line.Info object.
static int | write(AudioInputStream stream, AudioFileFormat.Type fileType, File out) Writes a stream of bytes representing an audio file of the specified file type to the external file provided.
static int | write(AudioInputStream stream, AudioFileFormat.Type fileType, OutputStream out) Writes a stream of bytes representing an audio file of the specified file type to the output stream provided.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NOT_SPECIFIED

public static final int NOT_SPECIFIED
An integer that stands for an unknown numeric value. This value is appropriate only for signed quantities that do not normally take negative values. Examples include file sizes, frame sizes, buffer sizes, and sample rates. A number of Java Sound constructors accept a value of NOT_SPECIFIED for such parameters. Other methods may also accept or return this value, as documented.

See Also:
Constant Field Values
Method Detail

getMixerInfo

public static Mixer.Info[] getMixerInfo()
Obtains an array of mixer info objects that represents the set of audio mixers that are currently installed on the system.

Returns:
an array of info objects for the currently installed mixers. If no mixers are available on the system, an array of length 0 is returned.
See Also:
getMixer(javax.sound.sampled.Mixer.Info)

getMixer

public static Mixer getMixer(Mixer.Info info)
Obtains the requested audio mixer.

Parameters:
info - a Mixer.Info object representing the desired mixer, or null for the system default mixer
Returns:
the requested mixer
Throws:
SecurityException - if the requested mixer is unavailable because of security restrictions
IllegalArgumentException - if the info object does not represent a mixer installed on the system
See Also:
getMixerInfo()

getSourceLineInfo

public static Line.Info[] getSourceLineInfo(Line.Info info)
Obtains information about all source lines of a particular type that are supported by the installed mixers.

Parameters:
info - a Line.Info object that specifies the kind of lines about which information is requested
Returns:
an array of Line.Info objects describing source lines matching the type requested. If no matching source lines are supported, an array of length 0 is returned.
See Also:
Mixer.getSourceLineInfo(Line.Info)

getTargetLineInfo

public static Line.Info[] getTargetLineInfo(Line.Info info)
Obtains information about all target lines of a particular type that are supported by the installed mixers.

Parameters:
info - a Line.Info object that specifies the kind of lines about which information is requested
Returns:
an array of Line.Info objects describing target lines matching the type requested. If no matching target lines are supported, an array of length 0 is returned.
See Also:
Mixer.getTargetLineInfo(Line.Info)

isLineSupported

public static boolean isLineSupported(Line.Info info)
Indicates whether the system supports any lines that match the specified Line.Info object. A line is supported if any installed mixer supports it.

Parameters:
info - a Line.Info object describing the line for which support is queried
Returns:
true if at least one matching line is supported, otherwise false
See Also:
Mixer.isLineSupported(Line.Info)

getLine

public static Line getLine(Line.Info info)
                    throws LineUnavailableException
Obtains a line that matches the description in the specified Line.Info object.

If a DataLine is requested, and info is an instance of DataLine.Info specifying at least one fully qualified audio format, the last one will be used as the default format of the returned DataLine.

If system properties javax.sound.sampled.Clip, javax.sound.sampled.Port, javax.sound.sampled.SourceDataLine and javax.sound.sampled.TargetDataLine are defined or they are defined in the file "sound.properties", they are used to retrieve default lines. For details, refer to the class description. If the respective property is not set, or the mixer requested in the property is not installed or does not provide the requested line, all installed mixers are queried for the requested line type. A Line will be returned from the first mixer providing the requested line type.

Parameters:
info - a Line.Info object describing the desired kind of line
Returns:
a line of the requested kind
Throws:
LineUnavailableException - if a matching line is not available due to resource restrictions
SecurityException - if a matching line is not available due to security restrictions
IllegalArgumentException - if the system does not support at least one line matching the specified Line.Info object through any installed mixer

getClip

public static Clip getClip()
                    throws LineUnavailableException
Obtains a clip that can be used for playing back an audio file or an audio stream. The returned clip will be provided by the default system mixer, or, if not possible, by any other mixer installed in the system that supports a Clip object.

The returned clip must be opened with the open(AudioFormat) or open(AudioInputStream) method.

This is a high-level method that uses getMixer and getLine internally.

If the system property javax.sound.sampled.Clip is defined or it is defined in the file "sound.properties", it is used to retrieve the default clip. For details, refer to the class description.

Returns:
the desired clip object
Throws:
LineUnavailableException - if a clip object is not available due to resource restrictions
SecurityException - if a clip object is not available due to security restrictions
IllegalArgumentException - if the system does not support at least one clip instance through any installed mixer
Since:
1.5
See Also:
getClip(Mixer.Info)

getClip

public static Clip getClip(Mixer.Info mixerInfo)
                    throws LineUnavailableException
Obtains a clip from the specified mixer that can be used for playing back an audio file or an audio stream.

The returned clip must be opened with the open(AudioFormat) or open(AudioInputStream) method.

This is a high-level method that uses getMixer and getLine internally.

Parameters:
mixerInfo - a Mixer.Info object representing the desired mixer, or null for the system default mixer
Returns:
a clip object from the specified mixer
Throws:
LineUnavailableException - if a clip is not available from this mixer due to resource restrictions
SecurityException - if a clip is not available from this mixer due to security restrictions
IllegalArgumentException - if the system does not support at least one clip through the specified mixer
Since:
1.5
See Also:
getClip()

getSourceDataLine

public static SourceDataLine getSourceDataLine(AudioFormat format)
                                        throws LineUnavailableException
Obtains a source data line that can be used for playing back audio data in the format specified by the AudioFormat object. The returned line will be provided by the default system mixer, or, if not possible, by any other mixer installed in the system that supports a matching SourceDataLine object.

The returned line should be opened with the open(AudioFormat) or open(AudioFormat, int) method.

This is a high-level method that uses getMixer and getLine internally.

The returned SourceDataLine's default audio format will be initialized with format.

If the system property javax.sound.sampled.SourceDataLine is defined or it is defined in the file "sound.properties", it is used to retrieve the default source data line. For details, refer to the class description.

Parameters:
format - an AudioFormat object specifying the supported audio format of the returned line, or null for any audio format
Returns:
the desired SourceDataLine object
Throws:
LineUnavailableException - if a matching source data line is not available due to resource restrictions
SecurityException - if a matching source data line is not available due to security restrictions
IllegalArgumentException - if the system does not support at least one source data line supporting the specified audio format through any installed mixer
Since:
1.5
See Also:
getSourceDataLine(AudioFormat, Mixer.Info)

getSourceDataLine

public static SourceDataLine getSourceDataLine(AudioFormat format,
                                               Mixer.Info mixerinfo)
                                        throws LineUnavailableException
Obtains a source data line that can be used for playing back audio data in the format specified by the AudioFormat object, provided by the mixer specified by the Mixer.Info object.

The returned line should be opened with the open(AudioFormat) or open(AudioFormat, int) method.

This is a high-level method that uses getMixer and getLine internally.

The returned SourceDataLine's default audio format will be initialized with format.

Parameters:
format - an AudioFormat object specifying the supported audio format of the returned line, or null for any audio format
mixerinfo - a Mixer.Info object representing the desired mixer, or null for the system default mixer
Returns:
the desired SourceDataLine object
Throws:
LineUnavailableException - if a matching source data line is not available from the specified mixer due to resource restrictions
SecurityException - if a matching source data line is not available from the specified mixer due to security restrictions
IllegalArgumentException - if the specified mixer does not support at least one source data line supporting the specified audio format
Since:
1.5
See Also:
getSourceDataLine(AudioFormat)

getTargetDataLine

public static TargetDataLine getTargetDataLine(AudioFormat format)
                                        throws LineUnavailableException
Obtains a target data line that can be used for recording audio data in the format specified by the AudioFormat object. The returned line will be provided by the default system mixer, or, if not possible, by any other mixer installed in the system that supports a matching TargetDataLine object.

The returned line should be opened with the open(AudioFormat) or open(AudioFormat, int) method.

This is a high-level method that uses getMixer and getLine internally.

The returned TargetDataLine's default audio format will be initialized with format.

Parameters:
format - an AudioFormat object specifying the supported audio format of the returned line, or null for any audio format
Returns:
the desired TargetDataLine object
Throws:
LineUnavailableException - if a matching target data line is not available due to resource restrictions
SecurityException - if a matching target data line is not available due to security restrictions
IllegalArgumentException - if the system does not support at least one target data line supporting the specified audio format through any installed mixer
Since:
1.5
See Also:
getTargetDataLine(AudioFormat, Mixer.Info), AudioPermission

getTargetDataLine

public static TargetDataLine getTargetDataLine(AudioFormat format,
                                               Mixer.Info mixerinfo)
                                        throws LineUnavailableException
Obtains a target data line that can be used for recording audio data in the format specified by the AudioFormat object, provided by the mixer specified by the Mixer.Info object.

The returned line should be opened with the open(AudioFormat) or open(AudioFormat, int) method.

This is a high-level method that uses getMixer and getLine internally.

The returned TargetDataLine's default audio format will be initialized with format.

If the system property javax.sound.sampled.TargetDataLine is defined or it is defined in the file "sound.properties", it is used to retrieve the default target data line. For details, refer to the class description.

Parameters:
format - an AudioFormat object specifying the supported audio format of the returned line, or null for any audio format
mixerinfo - a Mixer.Info object representing the desired mixer, or null for the system default mixer
Returns:
the desired TargetDataLine object
Throws:
LineUnavailableException - if a matching target data line is not available from the specified mixer due to resource restrictions
SecurityException - if a matching target data line is not available from the specified mixer due to security restrictions
IllegalArgumentException - if the specified mixer does not support at least one target data line supporting the specified audio format
Since:
1.5
See Also:
getTargetDataLine(AudioFormat), AudioPermission

getTargetEncodings

public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat.Encoding sourceEncoding)
Obtains the encodings that the system can obtain from an audio input stream with the specified encoding using the set of installed format converters.

Parameters:
sourceEncoding - the encoding for which conversion support is queried
Returns:
array of encodings. If sourceEncodingis not supported, an array of length 0 is returned. Otherwise, the array will have a length of at least 1, representing sourceEncoding (no conversion).

getTargetEncodings

public static AudioFormat.Encoding[] getTargetEncodings(AudioFormat sourceFormat)
Obtains the encodings that the system can obtain from an audio input stream with the specified format using the set of installed format converters.

Parameters:
sourceFormat - the audio format for which conversion is queried
Returns:
array of encodings. If sourceFormatis not supported, an array of length 0 is returned. Otherwise, the array will have a length of at least 1, representing the encoding of sourceFormat (no conversion).

isConversionSupported

public static boolean isConversionSupported(AudioFormat.Encoding targetEncoding,
                                            AudioFormat sourceFormat)
Indicates whether an audio input stream of the specified encoding can be obtained from an audio input stream that has the specified format.

Parameters:
targetEncoding - the desired encoding after conversion
sourceFormat - the audio format before conversion
Returns:
true if the conversion is supported, otherwise false

getAudioInputStream

public static AudioInputStream getAudioInputStream(AudioFormat.Encoding targetEncoding,
                                                   AudioInputStream sourceStream)
Obtains an audio input stream of the indicated encoding, by converting the provided audio input stream.

Parameters:
targetEncoding - the desired encoding after conversion
sourceStream - the stream to be converted
Returns:
an audio input stream of the indicated encoding
Throws:
IllegalArgumentException - if the conversion is not supported
See Also:
getTargetEncodings(AudioFormat.Encoding), getTargetEncodings(AudioFormat), isConversionSupported(AudioFormat.Encoding, AudioFormat), getAudioInputStream(AudioFormat, AudioInputStream)

getTargetFormats

public static AudioFormat[] getTargetFormats(AudioFormat.Encoding targetEncoding,
                                             AudioFormat sourceFormat)
Obtains the formats that have a particular encoding and that the system can obtain from a stream of the specified format using the set of installed format converters.

Parameters:
targetEncoding - the desired encoding after conversion
sourceFormat - the audio format before conversion
Returns:
array of formats. If no formats of the specified encoding are supported, an array of length 0 is returned.

isConversionSupported

public static boolean isConversionSupported(AudioFormat targetFormat,
                                            AudioFormat sourceFormat)
Indicates whether an audio input stream of a specified format can be obtained from an audio input stream of another specified format.

Parameters:
targetFormat - the desired audio format after conversion
sourceFormat - the audio format before conversion
Returns:
true if the conversion is supported, otherwise false

getAudioInputStream

public static AudioInputStream getAudioInputStream(AudioFormat targetFormat,
                                                   AudioInputStream sourceStream)
Obtains an audio input stream of the indicated format, by converting the provided audio input stream.

Parameters:
targetFormat - the desired audio format after conversion
sourceStream - the stream to be converted
Returns:
an audio input stream of the indicated format
Throws:
IllegalArgumentException - if the conversion is not supported #see #getTargetEncodings(AudioFormat)
See Also:
getTargetFormats(AudioFormat.Encoding, AudioFormat),
isConversionSupported(AudioFormat, AudioFormat),
getAudioInputStream(AudioFormat.Encoding, AudioInputStream)

getAudioFileFormat

public static AudioFileFormat getAudioFileFormat(InputStream stream)
                                          throws UnsupportedAudioFileException,
                                                 IOException
Obtains the audio file format of the provided input stream. The stream must point to valid audio file data. The implementation of this method may require multiple parsers to examine the stream to determine whether they support it. These parsers must be able to mark the stream, read enough data to determine whether they support the stream, and, if not, reset the stream's read pointer to its original position. If the input stream does not support these operations, this method may fail with an IOException.

Parameters:
stream - the input stream from which file format information should be extracted
Returns:
an AudioFileFormat object describing the stream's audio file format
Throws:
UnsupportedAudioFileException - if the stream does not point to valid audio file data recognized by the system
IOException - if an input/output exception occurs
See Also:
InputStream.markSupported(), InputStream.mark(int)

getAudioFileFormat

public static AudioFileFormat getAudioFileFormat(URL url)
                                          throws UnsupportedAudioFileException,
                                                 IOException
Obtains the audio file format of the specified URL. The URL must point to valid audio file data.

Parameters:
url - the URL from which file format information should be extracted
Returns:
an AudioFileFormat object describing the audio file format
Throws:
UnsupportedAudioFileException - if the URL does not point to valid audio file data recognized by the system
IOException - if an input/output exception occurs

getAudioFileFormat

public static AudioFileFormat getAudioFileFormat(File file)
                                          throws UnsupportedAudioFileException,
                                                 IOException
Obtains the audio file format of the specified File. The File must point to valid audio file data.

Parameters:
file - the File from which file format information should be extracted
Returns:
an AudioFileFormat object describing the audio file format
Throws:
UnsupportedAudioFileException - if the File does not point to valid audio file data recognized by the system
IOException - if an I/O exception occurs

getAudioInputStream

public static AudioInputStream getAudioInputStream(InputStream stream)
                                            throws UnsupportedAudioFileException,
                                                   IOException
Obtains an audio input stream from the provided input stream. The stream must point to valid audio file data. The implementation of this method may require multiple parsers to examine the stream to determine whether they support it. These parsers must be able to mark the stream, read enough data to determine whether they support the stream, and, if not, reset the stream's read pointer to its original position. If the input stream does not support these operation, this method may fail with an IOException.

Parameters:
stream - the input stream from which the AudioInputStream should be constructed
Returns:
an AudioInputStream object based on the audio file data contained in the input stream.
Throws:
UnsupportedAudioFileException - if the stream does not point to valid audio file data recognized by the system
IOException - if an I/O exception occurs
See Also:
InputStream.markSupported(), InputStream.mark(int)

getAudioInputStream

public static AudioInputStream getAudioInputStream(URL url)
                                            throws UnsupportedAudioFileException,
                                                   IOException
Obtains an audio input stream from the URL provided. The URL must point to valid audio file data.

Parameters:
url - the URL for which the AudioInputStream should be constructed
Returns:
an AudioInputStream object based on the audio file data pointed to by the URL
Throws:
UnsupportedAudioFileException - if the URL does not point to valid audio file data recognized by the system
IOException - if an I/O exception occurs

getAudioInputStream

public static AudioInputStream getAudioInputStream(File file)
                                            throws UnsupportedAudioFileException,
                                                   IOException
Obtains an audio input stream from the provided File. The File must point to valid audio file data.

Parameters:
file - the File for which the AudioInputStream should be constructed
Returns:
an AudioInputStream object based on the audio file data pointed to by the File
Throws:
UnsupportedAudioFileException - if the File does not point to valid audio file data recognized by the system
IOException - if an I/O exception occurs

getAudioFileTypes

public static AudioFileFormat.Type[] getAudioFileTypes()
Obtains the file types for which file writing support is provided by the system.

Returns:
array of unique file types. If no file types are supported, an array of length 0 is returned.

isFileTypeSupported

public static boolean isFileTypeSupported(AudioFileFormat.Type fileType)
Indicates whether file writing support for the specified file type is provided by the system.

Parameters:
fileType - the file type for which write capabilities are queried
Returns:
true if the file type is supported, otherwise false

getAudioFileTypes

public static AudioFileFormat.Type[] getAudioFileTypes(AudioInputStream stream)
Obtains the file types that the system can write from the audio input stream specified.

Parameters:
stream - the audio input stream for which audio file type support is queried
Returns:
array of file types. If no file types are supported, an array of length 0 is returned.

isFileTypeSupported

public static boolean isFileTypeSupported(AudioFileFormat.Type fileType,
                                          AudioInputStream stream)
Indicates whether an audio file of the specified file type can be written from the indicated audio input stream.

Parameters:
fileType - the file type for which write capabilities are queried
stream - the stream for which file-writing support is queried
Returns:
true if the file type is supported for this audio input stream, otherwise false

write

public static int write(AudioInputStream stream,
                        AudioFileFormat.Type fileType,
                        OutputStream out)
                 throws IOException
Writes a stream of bytes representing an audio file of the specified file type to the output stream provided. Some file types require that the length be written into the file header; such files cannot be written from start to finish unless the length is known in advance. An attempt to write a file of such a type will fail with an IOException if the length in the audio file type is AudioSystem.NOT_SPECIFIED.

Parameters:
stream - the audio input stream containing audio data to be written to the file
fileType - the kind of audio file to write
out - the stream to which the file data should be written
Returns:
the number of bytes written to the output stream
Throws:
IOException - if an input/output exception occurs
IllegalArgumentException - if the file type is not supported by the system
See Also:
isFileTypeSupported(javax.sound.sampled.AudioFileFormat.Type), getAudioFileTypes()

write

public static int write(AudioInputStream stream,
                        AudioFileFormat.Type fileType,
                        File out)
                 throws IOException
Writes a stream of bytes representing an audio file of the specified file type to the external file provided.

Parameters:
stream - the audio input stream containing audio data to be written to the file
fileType - the kind of audio file to write
out - the external file to which the file data should be written
Returns:
the number of bytes written to the file
Throws:
IOException - if an I/O exception occurs
IllegalArgumentException - if the file type is not supported by the system
See Also:
isFileTypeSupported(javax.sound.sampled.AudioFileFormat.Type), getAudioFileTypes()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BooleanControl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class BooleanControl

java.lang.Object
    extended by  javax.sound.sampled.Control
        extended by  javax.sound.sampled.BooleanControl

public abstract class BooleanControl
extends Control

A BooleanControl provides the ability to switch between two possible settings that affect a line's audio. The settings are boolean values (true and false). A graphical user interface might represent the control by a two-state button, an on/off switch, two mutually exclusive buttons, or a checkbox (among other possibilities). For example, depressing a button might activate a MUTE control to silence the line's audio.

As with other Control subclasses, a method is provided that returns string labels for the values, suitable for display in the user interface.

Since:
1.3

Nested Class Summary
static class BooleanControl.Type
An instance of the BooleanControl.Type class identifies one kind of boolean control.
Constructor Summary
protected | BooleanControl(BooleanControl.Type type, boolean initialValue) Constructs a new boolean control object with the given parameters.
protected | BooleanControl(BooleanControl.Type type, boolean initialValue, String trueStateLabel, String falseStateLabel) Constructs a new boolean control object with the given parameters.
Method Summary
String | getStateLabel(boolean state) Obtains the label for the specified state.
boolean | getValue() Obtains this control's current value.
void | setValue(boolean value) Sets the current value for the control.
String | toString() Provides a string representation of the control
Methods inherited from class javax.sound.sampled.Control
getType
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

BooleanControl

protected BooleanControl(BooleanControl.Type type,
                         boolean initialValue,
                         String trueStateLabel,
                         String falseStateLabel)
Constructs a new boolean control object with the given parameters.

Parameters:
type - the type of control represented this float control object
initialValue - the initial control value
trueStateLabel - the label for the state represented by true, such as "true" or "on."
falseStateLabel - the label for the state represented by false, such as "false" or "off."

BooleanControl

protected BooleanControl(BooleanControl.Type type,
                         boolean initialValue)
Constructs a new boolean control object with the given parameters. The labels for the true and false states default to "true" and "false."

Parameters:
type - the type of control represented by this float control object
initialValue - the initial control value
Method Detail

setValue

public void setValue(boolean value)
Sets the current value for the control. The default implementation simply sets the value as indicated. Some controls require that their line be open before they can be affected by setting a value.

Parameters:
value - desired new value.

getValue

public boolean getValue()
Obtains this control's current value.

Returns:
current value.

getStateLabel

public String getStateLabel(boolean state)
Obtains the label for the specified state.

Returns:
the label for the specified state, such as "true" or "on" for true, or "false" or "off" for false.

toString

public String toString()
Provides a string representation of the control

Overrides:
toString in class Control
Returns:
a string description
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BooleanControl.Type

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class BooleanControl.Type

java.lang.Object
    extended by  javax.sound.sampled.Control.Type
        extended by  javax.sound.sampled.BooleanControl.Type
Enclosing class:
BooleanControl
public static class BooleanControl.Type
extends Control.Type

An instance of the BooleanControl.Type class identifies one kind of boolean control. Static instances are provided for the common types.

Since:
1.3

Field Summary
static BooleanControl.Type | APPLY_REVERB Represents a control for whether reverberation is applied to a line.
static BooleanControl.Type | MUTE Represents a control for the mute status of a line.
Constructor Summary
protected BooleanControl.Type(String name)
Constructs a new boolean control type.
Method Summary
Methods inherited from class javax.sound.sampled.Control.Type
equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

MUTE

public static final BooleanControl.Type MUTE
Represents a control for the mute status of a line. Note that mute status does not affect gain.

APPLY_REVERB

public static final BooleanControl.Type APPLY_REVERB
Represents a control for whether reverberation is applied to a line. Note that the status of this control not affect the reverberation settings for a line, but does affect whether these settings are used.

Constructor Detail

BooleanControl.Type

protected BooleanControl.Type(String name)
Constructs a new boolean control type.

Parameters:
name - the name of the new boolean control type
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.sound.sampled.AudioFileFormat

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.AudioFileFormat

Packages that use AudioFileFormat
javax.sound.sampled | Provides interfaces and classes for capture, processing, and playback of sampled audio data.
javax.sound.sampled.spi | Supplies abstract classes for service providers to subclass when offering new audio devices, sound file readers and writers, or audio format converters.

Uses of AudioFileFormat in javax.sound.sampled

Methods in javax.sound.sampled that return AudioFileFormat
static AudioFileFormat | AudioSystem.getAudioFileFormat(File file) Obtains the audio file format of the specified File.
static AudioFileFormat | AudioSystem.getAudioFileFormat(InputStream stream) Obtains the audio file format of the provided input stream.
static AudioFileFormat | AudioSystem.getAudioFileFormat(URL url) Obtains the audio file format of the specified URL.

Uses of AudioFileFormat in javax.sound.sampled.spi

Methods in javax.sound.sampled.spi that return AudioFileFormat
abstract AudioFileFormat | AudioFileReader.getAudioFileFormat(File file) Obtains the audio file format of the File provided.
abstract AudioFileFormat | AudioFileReader.getAudioFileFormat(InputStream stream) Obtains the audio file format of the input stream provided.
abstract AudioFileFormat | AudioFileReader.getAudioFileFormat(URL url) Obtains the audio file format of the URL provided.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.AudioFileFormat.Type

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.AudioFileFormat.Type

Packages that use AudioFileFormat.Type
javax.sound.sampled | Provides interfaces and classes for capture, processing, and playback of sampled audio data.
javax.sound.sampled.spi | Supplies abstract classes for service providers to subclass when offering new audio devices, sound file readers and writers, or audio format converters.

Uses of AudioFileFormat.Type in javax.sound.sampled

Fields in javax.sound.sampled declared as AudioFileFormat.Type
static AudioFileFormat.Type | AudioFileFormat.Type.AIFC Specifies an AIFF-C file.
static AudioFileFormat.Type | AudioFileFormat.Type.AIFF Specifies an AIFF file.
static AudioFileFormat.Type | AudioFileFormat.Type.AU Specifies an AU file.
static AudioFileFormat.Type | AudioFileFormat.Type.SND Specifies a SND file.
static AudioFileFormat.Type | AudioFileFormat.Type.WAVE Specifies a WAVE file.

Methods in javax.sound.sampled that return AudioFileFormat.Type
static AudioFileFormat.Type[] | AudioSystem.getAudioFileTypes() Obtains the file types for which file writing support is provided by the system.
static AudioFileFormat.Type[] | AudioSystem.getAudioFileTypes(AudioInputStream stream) Obtains the file types that the system can write from the audio input stream specified.
AudioFileFormat.Type | AudioFileFormat.getType() Obtains the audio file type, such as WAVE or AU.

Methods in javax.sound.sampled with parameters of type AudioFileFormat.Type
static boolean | AudioSystem.isFileTypeSupported(AudioFileFormat.Type fileType) Indicates whether file writing support for the specified file type is provided by the system.
static boolean | AudioSystem.isFileTypeSupported(AudioFileFormat.Type fileType, AudioInputStream stream) Indicates whether an audio file of the specified file type can be written from the indicated audio input stream.
static int | AudioSystem.write(AudioInputStream stream, AudioFileFormat.Type fileType, File out) Writes a stream of bytes representing an audio file of the specified file type to the external file provided.
static int | AudioSystem.write(AudioInputStream stream, AudioFileFormat.Type fileType, OutputStream out) Writes a stream of bytes representing an audio file of the specified file type to the output stream provided.

Constructors in javax.sound.sampled with parameters of type AudioFileFormat.Type
AudioFileFormat(AudioFileFormat.Type type, AudioFormat format, int frameLength)
Constructs an audio file format object.
AudioFileFormat(AudioFileFormat.Type type, AudioFormat format, int frameLength, Map<String,Object> properties)
Construct an audio file format object with a set of defined properties.
AudioFileFormat(AudioFileFormat.Type type, int byteLength, AudioFormat format, int frameLength)
Constructs an audio file format object.

Uses of AudioFileFormat.Type in javax.sound.sampled.spi

Methods in javax.sound.sampled.spi that return AudioFileFormat.Type
abstract AudioFileFormat.Type[] | AudioFileWriter.getAudioFileTypes() Obtains the file types for which file writing support is provided by this audio file writer.
abstract AudioFileFormat.Type[] | AudioFileWriter.getAudioFileTypes(AudioInputStream stream) Obtains the file types that this audio file writer can write from the audio input stream specified.

Methods in javax.sound.sampled.spi with parameters of type AudioFileFormat.Type
boolean | AudioFileWriter.isFileTypeSupported(AudioFileFormat.Type fileType) Indicates whether file writing support for the specified file type is provided by this audio file writer.
boolean | AudioFileWriter.isFileTypeSupported(AudioFileFormat.Type fileType, AudioInputStream stream) Indicates whether an audio file of the type specified can be written from the audio input stream indicated.
abstract int | AudioFileWriter.write(AudioInputStream stream, AudioFileFormat.Type fileType, File out) Writes a stream of bytes representing an audio file of the file format indicated to the external file provided.
abstract int | AudioFileWriter.write(AudioInputStream stream, AudioFileFormat.Type fileType, OutputStream out) Writes a stream of bytes representing an audio file of the file type indicated to the output stream provided.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.AudioFormat

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.AudioFormat

Packages that use AudioFormat
javax.sound.sampled | Provides interfaces and classes for capture, processing, and playback of sampled audio data.
javax.sound.sampled.spi | Supplies abstract classes for service providers to subclass when offering new audio devices, sound file readers and writers, or audio format converters.

Uses of AudioFormat in javax.sound.sampled

Fields in javax.sound.sampled declared as AudioFormat
protected  AudioFormat AudioInputStream.format
The format of the audio data contained in the stream.

Methods in javax.sound.sampled that return AudioFormat
AudioFormat | DataLine.getFormat() Obtains the current format (encoding, sample rate, number of channels, etc.) of the data line's audio data.
AudioFormat | AudioFileFormat.getFormat() Obtains the format of the audio data contained in the audio file.
AudioFormat | AudioInputStream.getFormat() Obtains the audio format of the sound data in this audio input stream.
AudioFormat[] | DataLine.Info.getFormats() Obtains a set of audio formats supported by the data line.
static AudioFormat[] | AudioSystem.getTargetFormats(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) Obtains the formats that have a particular encoding and that the system can obtain from a stream of the specified format using the set of installed format converters.

Methods in javax.sound.sampled with parameters of type AudioFormat
static AudioInputStream | AudioSystem.getAudioInputStream(AudioFormat targetFormat, AudioInputStream sourceStream) Obtains an audio input stream of the indicated format, by converting the provided audio input stream.
static SourceDataLine | AudioSystem.getSourceDataLine(AudioFormat format) Obtains a source data line that can be used for playing back audio data in the format specified by the AudioFormat object.
static SourceDataLine | AudioSystem.getSourceDataLine(AudioFormat format, Mixer.Info mixerinfo) Obtains a source data line that can be used for playing back audio data in the format specified by the AudioFormat object, provided by the mixer specified by the Mixer.Info object.
static TargetDataLine | AudioSystem.getTargetDataLine(AudioFormat format) Obtains a target data line that can be used for recording audio data in the format specified by the AudioFormat object.
static TargetDataLine | AudioSystem.getTargetDataLine(AudioFormat format, Mixer.Info mixerinfo) Obtains a target data line that can be used for recording audio data in the format specified by the AudioFormat object, provided by the mixer specified by the Mixer.Info object.
static AudioFormat.Encoding[] | AudioSystem.getTargetEncodings(AudioFormat sourceFormat) Obtains the encodings that the system can obtain from an audio input stream with the specified format using the set of installed format converters.
static AudioFormat[] | AudioSystem.getTargetFormats(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) Obtains the formats that have a particular encoding and that the system can obtain from a stream of the specified format using the set of installed format converters.
static boolean | AudioSystem.isConversionSupported(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) Indicates whether an audio input stream of the specified encoding can be obtained from an audio input stream that has the specified format.
static boolean | AudioSystem.isConversionSupported(AudioFormat targetFormat, AudioFormat sourceFormat) Indicates whether an audio input stream of a specified format can be obtained from an audio input stream of another specified format.
boolean | DataLine.Info.isFormatSupported(AudioFormat format) Indicates whether this data line supports a particular audio format.
boolean | AudioFormat.matches(AudioFormat format) Indicates whether this format matches the one specified.
void | TargetDataLine.open(AudioFormat format) Opens the line with the specified format, causing the line to acquire any required system resources and become operational.
void | SourceDataLine.open(AudioFormat format) Opens the line with the specified format, causing the line to acquire any required system resources and become operational.
void | Clip.open(AudioFormat format, byte[] data, int offset, int bufferSize) Opens the clip, meaning that it should acquire any required system resources and become operational.
void | TargetDataLine.open(AudioFormat format, int bufferSize) Opens the line with the specified format and requested buffer size, causing the line to acquire any required system resources and become operational.
void | SourceDataLine.open(AudioFormat format, int bufferSize) Opens the line with the specified format and suggested buffer size, causing the line to acquire any required system resources and become operational.

Constructors in javax.sound.sampled with parameters of type AudioFormat
AudioFileFormat(AudioFileFormat.Type type, AudioFormat format, int frameLength)
Constructs an audio file format object.
AudioFileFormat(AudioFileFormat.Type type, AudioFormat format, int frameLength, Map<String,Object> properties)
Construct an audio file format object with a set of defined properties.
AudioFileFormat(AudioFileFormat.Type type, int byteLength, AudioFormat format, int frameLength)
Constructs an audio file format object.
AudioInputStream(InputStream stream, AudioFormat format, long length)
Constructs an audio input stream that has the requested format and length in sample frames, using audio data from the specified input stream.
DataLine.Info(Class<?> lineClass, AudioFormat format)
Constructs a data line's info object from the specified information, which includes a single audio format.
DataLine.Info(Class<?> lineClass, AudioFormat[] formats, int minBufferSize, int maxBufferSize)
Constructs a data line's info object from the specified information, which includes a set of supported audio formats and a range for the buffer size.
DataLine.Info(Class<?> lineClass, AudioFormat format, int bufferSize)
Constructs a data line's info object from the specified information, which includes a single audio format and a desired buffer size.

Uses of AudioFormat in javax.sound.sampled.spi

Methods in javax.sound.sampled.spi that return AudioFormat
abstract  AudioFormat[] FormatConversionProvider.getTargetFormats(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat)
Obtains the set of target formats with the encoding specified supported by the format converter If no target formats with the specified encoding are supported for this source format, an array of length 0 is returned.

Methods in javax.sound.sampled.spi with parameters of type AudioFormat
abstract AudioInputStream | FormatConversionProvider.getAudioInputStream(AudioFormat targetFormat, AudioInputStream sourceStream) Obtains an audio input stream with the specified format from the given audio input stream.
abstract AudioFormat.Encoding[] | FormatConversionProvider.getTargetEncodings(AudioFormat sourceFormat) Obtains the set of target format encodings supported by the format converter given a particular source format.
abstract AudioFormat[] | FormatConversionProvider.getTargetFormats(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) Obtains the set of target formats with the encoding specified supported by the format converter If no target formats with the specified encoding are supported for this source format, an array of length 0 is returned.
boolean | FormatConversionProvider.isConversionSupported(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) Indicates whether the format converter supports conversion to a particular encoding from a particular format.
boolean | FormatConversionProvider.isConversionSupported(AudioFormat targetFormat, AudioFormat sourceFormat) Indicates whether the format converter supports conversion to one particular format from another.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.AudioFormat.Encoding

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.AudioFormat.Encoding

Packages that use AudioFormat.Encoding
javax.sound.sampled | Provides interfaces and classes for capture, processing, and playback of sampled audio data.
javax.sound.sampled.spi | Supplies abstract classes for service providers to subclass when offering new audio devices, sound file readers and writers, or audio format converters.

Uses of AudioFormat.Encoding in javax.sound.sampled

Fields in javax.sound.sampled declared as AudioFormat.Encoding
static AudioFormat.Encoding | AudioFormat.Encoding.ALAW Specifies a-law encoded data.
protected AudioFormat.Encoding | AudioFormat.encoding The audio encoding technique used by this format.
static AudioFormat.Encoding | AudioFormat.Encoding.PCM_SIGNED Specifies signed, linear PCM data.
static AudioFormat.Encoding | AudioFormat.Encoding.PCM_UNSIGNED Specifies unsigned, linear PCM data.
static AudioFormat.Encoding | AudioFormat.Encoding.ULAW Specifies u-law encoded data.

Methods in javax.sound.sampled that return AudioFormat.Encoding
AudioFormat.Encoding | AudioFormat.getEncoding() Obtains the type of encoding for sounds in this format.
static AudioFormat.Encoding[] | AudioSystem.getTargetEncodings(AudioFormat.Encoding sourceEncoding) Obtains the encodings that the system can obtain from an audio input stream with the specified encoding using the set of installed format converters.
static AudioFormat.Encoding[] | AudioSystem.getTargetEncodings(AudioFormat sourceFormat) Obtains the encodings that the system can obtain from an audio input stream with the specified format using the set of installed format converters.

Methods in javax.sound.sampled with parameters of type AudioFormat.Encoding
static AudioInputStream | AudioSystem.getAudioInputStream(AudioFormat.Encoding targetEncoding, AudioInputStream sourceStream) Obtains an audio input stream of the indicated encoding, by converting the provided audio input stream.
static AudioFormat.Encoding[] | AudioSystem.getTargetEncodings(AudioFormat.Encoding sourceEncoding) Obtains the encodings that the system can obtain from an audio input stream with the specified encoding using the set of installed format converters.
static AudioFormat[] | AudioSystem.getTargetFormats(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) Obtains the formats that have a particular encoding and that the system can obtain from a stream of the specified format using the set of installed format converters.
static boolean | AudioSystem.isConversionSupported(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) Indicates whether an audio input stream of the specified encoding can be obtained from an audio input stream that has the specified format.

Constructors in javax.sound.sampled with parameters of type AudioFormat.Encoding
AudioFormat(AudioFormat.Encoding encoding, float sampleRate, int sampleSizeInBits, int channels, int frameSize, float frameRate, boolean bigEndian)
Constructs an AudioFormat with the given parameters.
AudioFormat(AudioFormat.Encoding encoding, float sampleRate, int sampleSizeInBits, int channels, int frameSize, float frameRate, boolean bigEndian, Map<String,Object> properties)
Constructs an AudioFormat with the given parameters.

Uses of AudioFormat.Encoding in javax.sound.sampled.spi

Methods in javax.sound.sampled.spi that return AudioFormat.Encoding
abstract AudioFormat.Encoding[] | FormatConversionProvider.getSourceEncodings() Obtains the set of source format encodings from which format conversion services are provided by this provider.
abstract AudioFormat.Encoding[] | FormatConversionProvider.getTargetEncodings() Obtains the set of target format encodings to which format conversion services are provided by this provider.
abstract AudioFormat.Encoding[] | FormatConversionProvider.getTargetEncodings(AudioFormat sourceFormat) Obtains the set of target format encodings supported by the format converter given a particular source format.

Methods in javax.sound.sampled.spi with parameters of type AudioFormat.Encoding
abstract AudioInputStream | FormatConversionProvider.getAudioInputStream(AudioFormat.Encoding targetEncoding, AudioInputStream sourceStream) Obtains an audio input stream with the specified encoding from the given audio input stream.
abstract AudioFormat[] | FormatConversionProvider.getTargetFormats(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) Obtains the set of target formats with the encoding specified supported by the format converter If no target formats with the specified encoding are supported for this source format, an array of length 0 is returned.
boolean | FormatConversionProvider.isConversionSupported(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) Indicates whether the format converter supports conversion to a particular encoding from a particular format.
boolean | FormatConversionProvider.isSourceEncodingSupported(AudioFormat.Encoding sourceEncoding) Indicates whether the format converter supports conversion from the specified source format encoding.
boolean | FormatConversionProvider.isTargetEncodingSupported(AudioFormat.Encoding targetEncoding) Indicates whether the format converter supports conversion to the specified target format encoding.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.AudioInputStream

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.AudioInputStream

Packages that use AudioInputStream
javax.sound.sampled | Provides interfaces and classes for capture, processing, and playback of sampled audio data.
javax.sound.sampled.spi | Supplies abstract classes for service providers to subclass when offering new audio devices, sound file readers and writers, or audio format converters.

Uses of AudioInputStream in javax.sound.sampled

Methods in javax.sound.sampled that return AudioInputStream
static AudioInputStream | AudioSystem.getAudioInputStream(AudioFormat.Encoding targetEncoding, AudioInputStream sourceStream) Obtains an audio input stream of the indicated encoding, by converting the provided audio input stream.
static AudioInputStream | AudioSystem.getAudioInputStream(AudioFormat targetFormat, AudioInputStream sourceStream) Obtains an audio input stream of the indicated format, by converting the provided audio input stream.
static AudioInputStream | AudioSystem.getAudioInputStream(File file) Obtains an audio input stream from the provided File.
static AudioInputStream | AudioSystem.getAudioInputStream(InputStream stream) Obtains an audio input stream from the provided input stream.
static AudioInputStream | AudioSystem.getAudioInputStream(URL url) Obtains an audio input stream from the URL provided.

Methods in javax.sound.sampled with parameters of type AudioInputStream
static AudioFileFormat.Type[] | AudioSystem.getAudioFileTypes(AudioInputStream stream) Obtains the file types that the system can write from the audio input stream specified.
static AudioInputStream | AudioSystem.getAudioInputStream(AudioFormat.Encoding targetEncoding, AudioInputStream sourceStream) Obtains an audio input stream of the indicated encoding, by converting the provided audio input stream.
static AudioInputStream | AudioSystem.getAudioInputStream(AudioFormat targetFormat, AudioInputStream sourceStream) Obtains an audio input stream of the indicated format, by converting the provided audio input stream.
static boolean | AudioSystem.isFileTypeSupported(AudioFileFormat.Type fileType, AudioInputStream stream) Indicates whether an audio file of the specified file type can be written from the indicated audio input stream.
void | Clip.open(AudioInputStream stream) Opens the clip with the format and audio data present in the provided audio input stream.
static int | AudioSystem.write(AudioInputStream stream, AudioFileFormat.Type fileType, File out) Writes a stream of bytes representing an audio file of the specified file type to the external file provided.
static int | AudioSystem.write(AudioInputStream stream, AudioFileFormat.Type fileType, OutputStream out) Writes a stream of bytes representing an audio file of the specified file type to the output stream provided.

Uses of AudioInputStream in javax.sound.sampled.spi

Methods in javax.sound.sampled.spi that return AudioInputStream
abstract AudioInputStream | FormatConversionProvider.getAudioInputStream(AudioFormat.Encoding targetEncoding, AudioInputStream sourceStream) Obtains an audio input stream with the specified encoding from the given audio input stream.
abstract AudioInputStream | FormatConversionProvider.getAudioInputStream(AudioFormat targetFormat, AudioInputStream sourceStream) Obtains an audio input stream with the specified format from the given audio input stream.
abstract AudioInputStream | AudioFileReader.getAudioInputStream(File file) Obtains an audio input stream from the File provided.
abstract AudioInputStream | AudioFileReader.getAudioInputStream(InputStream stream) Obtains an audio input stream from the input stream provided.
abstract AudioInputStream | AudioFileReader.getAudioInputStream(URL url) Obtains an audio input stream from the URL provided.

Methods in javax.sound.sampled.spi with parameters of type AudioInputStream
abstract AudioFileFormat.Type[] | AudioFileWriter.getAudioFileTypes(AudioInputStream stream) Obtains the file types that this audio file writer can write from the audio input stream specified.
abstract AudioInputStream | FormatConversionProvider.getAudioInputStream(AudioFormat.Encoding targetEncoding, AudioInputStream sourceStream) Obtains an audio input stream with the specified encoding from the given audio input stream.
abstract AudioInputStream | FormatConversionProvider.getAudioInputStream(AudioFormat targetFormat, AudioInputStream sourceStream) Obtains an audio input stream with the specified format from the given audio input stream.
boolean | AudioFileWriter.isFileTypeSupported(AudioFileFormat.Type fileType, AudioInputStream stream) Indicates whether an audio file of the type specified can be written from the audio input stream indicated.
abstract int | AudioFileWriter.write(AudioInputStream stream, AudioFileFormat.Type fileType, File out) Writes a stream of bytes representing an audio file of the file format indicated to the external file provided.
abstract int | AudioFileWriter.write(AudioInputStream stream, AudioFileFormat.Type fileType, OutputStream out) Writes a stream of bytes representing an audio file of the file type indicated to the output stream provided.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.AudioPermission

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.AudioPermission

No usage of javax.sound.sampled.AudioPermission

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.AudioSystem

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.AudioSystem

No usage of javax.sound.sampled.AudioSystem

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.BooleanControl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.BooleanControl

No usage of javax.sound.sampled.BooleanControl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.BooleanControl.Type

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.BooleanControl.Type

Packages that use BooleanControl.Type
javax.sound.sampled Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Uses of BooleanControl.Type in javax.sound.sampled

Fields in javax.sound.sampled declared as BooleanControl.Type
static BooleanControl.Type | BooleanControl.Type.APPLY_REVERB Represents a control for whether reverberation is applied to a line.
static BooleanControl.Type | BooleanControl.Type.MUTE Represents a control for the mute status of a line.

Constructors in javax.sound.sampled with parameters of type BooleanControl.Type
BooleanControl(BooleanControl.Type type, boolean initialValue)
Constructs a new boolean control object with the given parameters.
BooleanControl(BooleanControl.Type type, boolean initialValue, String trueStateLabel, String falseStateLabel)
Constructs a new boolean control object with the given parameters.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.CompoundControl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.CompoundControl

No usage of javax.sound.sampled.CompoundControl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.CompoundControl.Type

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.CompoundControl.Type

Packages that use CompoundControl.Type
javax.sound.sampled Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Uses of CompoundControl.Type in javax.sound.sampled

Constructors in javax.sound.sampled with parameters of type CompoundControl.Type
CompoundControl(CompoundControl.Type type, Control[] memberControls)
Constructs a new compound control object with the given parameters.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.Control

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.Control

Packages that use Control
javax.sound.sampled Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Uses of Control in javax.sound.sampled

Subclasses of Control in javax.sound.sampled
class | BooleanControl A BooleanControl provides the ability to switch between two possible settings that affect a line's audio.
class | CompoundControl A CompoundControl, such as a graphic equalizer, provides control over two or more related properties, each of which is itself represented as a Control.
class | EnumControl A EnumControl provides control over a set of discrete possible values, each represented by an object.
class | FloatControl A FloatControl object provides control over a range of floating-point values.

Methods in javax.sound.sampled that return Control
Control | Line.getControl(Control.Type control) Obtains a control of the specified type, if there is any.
Control[] | Line.getControls() Obtains the set of controls associated with this line.
Control[] | CompoundControl.getMemberControls() Returns the set of member controls that comprise the compound control.

Constructors in javax.sound.sampled with parameters of type Control
CompoundControl(CompoundControl.Type type, Control[] memberControls)
Constructs a new compound control object with the given parameters.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.Control.Type

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.Control.Type

Packages that use Control.Type
javax.sound.sampled Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Uses of Control.Type in javax.sound.sampled

Subclasses of Control.Type in javax.sound.sampled
static class | BooleanControl.Type An instance of the BooleanControl.Type class identifies one kind of boolean control.
static class | CompoundControl.Type An instance of the CompoundControl.Type inner class identifies one kind of compound control.
static class | EnumControl.Type An instance of the EnumControl.Type inner class identifies one kind of enumerated control.
static class | FloatControl.Type An instance of the FloatControl.Type inner class identifies one kind of float control.

Methods in javax.sound.sampled that return Control.Type
 Control.Type Control.getType()
Obtains the control's type.

Methods in javax.sound.sampled with parameters of type Control.Type
Control | Line.getControl(Control.Type control) Obtains a control of the specified type, if there is any.
boolean | Line.isControlSupported(Control.Type control) Indicates whether the line supports a control of the specified type.

Constructors in javax.sound.sampled with parameters of type Control.Type
Control(Control.Type type)
Constructs a Control with the specified type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.DataLine.Info

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.DataLine.Info

No usage of javax.sound.sampled.DataLine.Info

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.EnumControl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.EnumControl

No usage of javax.sound.sampled.EnumControl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.EnumControl.Type

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.EnumControl.Type

Packages that use EnumControl.Type
javax.sound.sampled Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Uses of EnumControl.Type in javax.sound.sampled

Fields in javax.sound.sampled declared as EnumControl.Type
static EnumControl.Type EnumControl.Type.REVERB
Represents a control over a set of possible reverberation settings.

Constructors in javax.sound.sampled with parameters of type EnumControl.Type
EnumControl(EnumControl.Type type, Object[] values, Object value)
Constructs a new enumerated control object with the given parameters.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.FloatControl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.FloatControl

No usage of javax.sound.sampled.FloatControl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.FloatControl.Type

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.FloatControl.Type

Packages that use FloatControl.Type
javax.sound.sampled Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Uses of FloatControl.Type in javax.sound.sampled

Fields in javax.sound.sampled declared as FloatControl.Type
static FloatControl.Type | FloatControl.Type.AUX_RETURN Represents a control for the auxiliary return gain on a line.
static FloatControl.Type | FloatControl.Type.AUX_SEND Represents a control for the auxiliary send gain on a line.
static FloatControl.Type | FloatControl.Type.BALANCE Represents a control for the relative balance of a stereo signal between two stereo speakers.
static FloatControl.Type | FloatControl.Type.MASTER_GAIN Represents a control for the overall gain on a line.
static FloatControl.Type | FloatControl.Type.PAN Represents a control for the relative pan (left-right positioning) of the signal.
static FloatControl.Type | FloatControl.Type.REVERB_RETURN Represents a control for the post-reverb gain on a line.
static FloatControl.Type | FloatControl.Type.REVERB_SEND Represents a control for the pre-reverb gain on a line.
static FloatControl.Type | FloatControl.Type.SAMPLE_RATE Represents a control that changes the sample rate of audio playback.
static FloatControl.Type | FloatControl.Type.VOLUME Represents a control for the volume on a line.

Constructors in javax.sound.sampled with parameters of type FloatControl.Type
FloatControl(FloatControl.Type type, float minimum, float maximum, float precision, int updatePeriod, float initialValue, String units)
Constructs a new float control object with the given parameters.
FloatControl(FloatControl.Type type, float minimum, float maximum, float precision, int updatePeriod, float initialValue, String units, String minLabel, String midLabel, String maxLabel)
Constructs a new float control object with the given parameters

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.Line.Info

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.Line.Info

Packages that use Line.Info
javax.sound.sampled Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Uses of Line.Info in javax.sound.sampled

Subclasses of Line.Info in javax.sound.sampled
static class | DataLine.Info Besides the class information inherited from its superclass, DataLine.Info provides additional information specific to data lines.
static class | Port.Info The Port.Info class extends Line.Info with additional information specific to ports, including the port's name and whether it is a source or a target for its mixer.

Methods in javax.sound.sampled that return Line.Info
Line.Info | Line.getLineInfo() Obtains the Line.Info object describing this line.
Line.Info[] | Mixer.getSourceLineInfo() Obtains information about the set of source lines supported by this mixer.
Line.Info[] | Mixer.getSourceLineInfo(Line.Info info) Obtains information about source lines of a particular type supported by the mixer.
static Line.Info[] | AudioSystem.getSourceLineInfo(Line.Info info) Obtains information about all source lines of a particular type that are supported by the installed mixers.
Line.Info[] | Mixer.getTargetLineInfo() Obtains information about the set of target lines supported by this mixer.
Line.Info[] | Mixer.getTargetLineInfo(Line.Info info) Obtains information about target lines of a particular type supported by the mixer.
static Line.Info[] | AudioSystem.getTargetLineInfo(Line.Info info) Obtains information about all target lines of a particular type that are supported by the installed mixers.

Methods in javax.sound.sampled with parameters of type Line.Info
Line | Mixer.getLine(Line.Info info) Obtains a line that is available for use and that matches the description in the specified Line.Info object.
static Line | AudioSystem.getLine(Line.Info info) Obtains a line that matches the description in the specified Line.Info object.
int | Mixer.getMaxLines(Line.Info info) Obtains the approximate maximum number of lines of the requested type that can be open simultaneously on the mixer.
Line.Info[] | Mixer.getSourceLineInfo(Line.Info info) Obtains information about source lines of a particular type supported by the mixer.
static Line.Info[] | AudioSystem.getSourceLineInfo(Line.Info info) Obtains information about all source lines of a particular type that are supported by the installed mixers.
Line.Info[] | Mixer.getTargetLineInfo(Line.Info info) Obtains information about target lines of a particular type supported by the mixer.
static Line.Info[] | AudioSystem.getTargetLineInfo(Line.Info info) Obtains information about all target lines of a particular type that are supported by the installed mixers.
boolean | Mixer.isLineSupported(Line.Info info) Indicates whether the mixer supports a line (or lines) that match the specified Line.Info object.
static boolean | AudioSystem.isLineSupported(Line.Info info) Indicates whether the system supports any lines that match the specified Line.Info object.
boolean | Port.Info.matches(Line.Info info) Indicates whether this info object specified matches this one.
boolean | DataLine.Info.matches(Line.Info info) Determines whether the specified info object matches this one.
boolean | Line.Info.matches(Line.Info info) Indicates whether the specified info object matches this one.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.LineEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.LineEvent

Packages that use LineEvent
javax.sound.sampled Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Uses of LineEvent in javax.sound.sampled

Methods in javax.sound.sampled with parameters of type LineEvent
 void LineListener.update(LineEvent event)
Informs the listener that a line's state has changed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.LineEvent.Type

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.LineEvent.Type

Packages that use LineEvent.Type
javax.sound.sampled Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Uses of LineEvent.Type in javax.sound.sampled

Fields in javax.sound.sampled declared as LineEvent.Type
static LineEvent.Type | LineEvent.Type.CLOSE A type of event that is sent when a line closes, freeing the system resources it had obtained when it was opened.
static LineEvent.Type | LineEvent.Type.OPEN A type of event that is sent when a line opens, reserving system resources for itself.
static LineEvent.Type | LineEvent.Type.START A type of event that is sent when a line begins to engage in active input or output of audio data in response to a start request.
static LineEvent.Type | LineEvent.Type.STOP A type of event that is sent when a line ceases active input or output of audio data in response to a stop request, or because the end of media has been reached.

Methods in javax.sound.sampled that return LineEvent.Type
 LineEvent.Type LineEvent.getType()
Obtains the event's type.

Constructors in javax.sound.sampled with parameters of type LineEvent.Type
LineEvent(Line line, LineEvent.Type type, long position)
Constructs a new event of the specified type, originating from the specified line.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.LineUnavailableException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.LineUnavailableException

Packages that use LineUnavailableException
javax.sound.sampled Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Uses of LineUnavailableException in javax.sound.sampled

Methods in javax.sound.sampled that throw LineUnavailableException
static Clip | AudioSystem.getClip() Obtains a clip that can be used for playing back an audio file or an audio stream.
static Clip | AudioSystem.getClip(Mixer.Info mixerInfo) Obtains a clip from the specified mixer that can be used for playing back an audio file or an audio stream.
Line | Mixer.getLine(Line.Info info) Obtains a line that is available for use and that matches the description in the specified Line.Info object.
static Line | AudioSystem.getLine(Line.Info info) Obtains a line that matches the description in the specified Line.Info object.
static SourceDataLine | AudioSystem.getSourceDataLine(AudioFormat format) Obtains a source data line that can be used for playing back audio data in the format specified by the AudioFormat object.
static SourceDataLine | AudioSystem.getSourceDataLine(AudioFormat format, Mixer.Info mixerinfo) Obtains a source data line that can be used for playing back audio data in the format specified by the AudioFormat object, provided by the mixer specified by the Mixer.Info object.
static TargetDataLine | AudioSystem.getTargetDataLine(AudioFormat format) Obtains a target data line that can be used for recording audio data in the format specified by the AudioFormat object.
static TargetDataLine | AudioSystem.getTargetDataLine(AudioFormat format, Mixer.Info mixerinfo) Obtains a target data line that can be used for recording audio data in the format specified by the AudioFormat object, provided by the mixer specified by the Mixer.Info object.
void | Line.open() Opens the line, indicating that it should acquire any required system resources and become operational.
void | TargetDataLine.open(AudioFormat format) Opens the line with the specified format, causing the line to acquire any required system resources and become operational.
void | SourceDataLine.open(AudioFormat format) Opens the line with the specified format, causing the line to acquire any required system resources and become operational.
void | Clip.open(AudioFormat format, byte[] data, int offset, int bufferSize) Opens the clip, meaning that it should acquire any required system resources and become operational.
void | TargetDataLine.open(AudioFormat format, int bufferSize) Opens the line with the specified format and requested buffer size, causing the line to acquire any required system resources and become operational.
void | SourceDataLine.open(AudioFormat format, int bufferSize) Opens the line with the specified format and suggested buffer size, causing the line to acquire any required system resources and become operational.
void | Clip.open(AudioInputStream stream) Opens the clip with the format and audio data present in the provided audio input stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.Mixer.Info

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.Mixer.Info

Packages that use Mixer.Info
javax.sound.sampled | Provides interfaces and classes for capture, processing, and playback of sampled audio data.
javax.sound.sampled.spi | Supplies abstract classes for service providers to subclass when offering new audio devices, sound file readers and writers, or audio format converters.

Uses of Mixer.Info in javax.sound.sampled

Methods in javax.sound.sampled that return Mixer.Info
Mixer.Info | Mixer.getMixerInfo() Obtains information about this mixer, including the product's name, version, vendor, etc.
static Mixer.Info[] | AudioSystem.getMixerInfo() Obtains an array of mixer info objects that represents the set of audio mixers that are currently installed on the system.

Methods in javax.sound.sampled with parameters of type Mixer.Info
static Clip | AudioSystem.getClip(Mixer.Info mixerInfo) Obtains a clip from the specified mixer that can be used for playing back an audio file or an audio stream.
static Mixer | AudioSystem.getMixer(Mixer.Info info) Obtains the requested audio mixer.
static SourceDataLine | AudioSystem.getSourceDataLine(AudioFormat format, Mixer.Info mixerinfo) Obtains a source data line that can be used for playing back audio data in the format specified by the AudioFormat object, provided by the mixer specified by the Mixer.Info object.
static TargetDataLine | AudioSystem.getTargetDataLine(AudioFormat format, Mixer.Info mixerinfo) Obtains a target data line that can be used for recording audio data in the format specified by the AudioFormat object, provided by the mixer specified by the Mixer.Info object.

Uses of Mixer.Info in javax.sound.sampled.spi

Methods in javax.sound.sampled.spi that return Mixer.Info
abstract  Mixer.Info[] MixerProvider.getMixerInfo()
Obtains the set of info objects representing the mixer or mixers provided by this MixerProvider.

Methods in javax.sound.sampled.spi with parameters of type Mixer.Info
abstract Mixer | MixerProvider.getMixer(Mixer.Info info) Obtains an instance of the mixer represented by the info object.
boolean | MixerProvider.isMixerSupported(Mixer.Info info) Indicates whether the mixer provider supports the mixer represented by the specified mixer info object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.Port.Info

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.Port.Info

Packages that use Port.Info
javax.sound.sampled Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Uses of Port.Info in javax.sound.sampled

Fields in javax.sound.sampled declared as Port.Info
static Port.Info | Port.Info.COMPACT_DISC A type of port that gets audio from a CD-ROM drive.
static Port.Info | Port.Info.HEADPHONE A type of port that sends audio to a headphone jack.
static Port.Info | Port.Info.LINE_IN A type of port that gets audio from a line-level audio input jack.
static Port.Info | Port.Info.LINE_OUT A type of port that sends audio to a line-level audio output jack.
static Port.Info | Port.Info.MICROPHONE A type of port that gets audio from a built-in microphone or a microphone jack.
static Port.Info | Port.Info.SPEAKER A type of port that sends audio to a built-in speaker or a speaker jack.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.ReverbType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.ReverbType

No usage of javax.sound.sampled.ReverbType

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.UnsupportedAudioFileException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.UnsupportedAudioFileException

Packages that use UnsupportedAudioFileException
javax.sound.sampled | Provides interfaces and classes for capture, processing, and playback of sampled audio data.
javax.sound.sampled.spi | Supplies abstract classes for service providers to subclass when offering new audio devices, sound file readers and writers, or audio format converters.

Uses of UnsupportedAudioFileException in javax.sound.sampled

Methods in javax.sound.sampled that throw UnsupportedAudioFileException
static AudioFileFormat | AudioSystem.getAudioFileFormat(File file) Obtains the audio file format of the specified File.
static AudioFileFormat | AudioSystem.getAudioFileFormat(InputStream stream) Obtains the audio file format of the provided input stream.
static AudioFileFormat | AudioSystem.getAudioFileFormat(URL url) Obtains the audio file format of the specified URL.
static AudioInputStream | AudioSystem.getAudioInputStream(File file) Obtains an audio input stream from the provided File.
static AudioInputStream | AudioSystem.getAudioInputStream(InputStream stream) Obtains an audio input stream from the provided input stream.
static AudioInputStream | AudioSystem.getAudioInputStream(URL url) Obtains an audio input stream from the URL provided.

Uses of UnsupportedAudioFileException in javax.sound.sampled.spi

Methods in javax.sound.sampled.spi that throw UnsupportedAudioFileException
abstract AudioFileFormat | AudioFileReader.getAudioFileFormat(File file) Obtains the audio file format of the File provided.
abstract AudioFileFormat | AudioFileReader.getAudioFileFormat(InputStream stream) Obtains the audio file format of the input stream provided.
abstract AudioFileFormat | AudioFileReader.getAudioFileFormat(URL url) Obtains the audio file format of the URL provided.
abstract AudioInputStream | AudioFileReader.getAudioInputStream(File file) Obtains an audio input stream from the File provided.
abstract AudioInputStream | AudioFileReader.getAudioInputStream(InputStream stream) Obtains an audio input stream from the input stream provided.
abstract AudioInputStream | AudioFileReader.getAudioInputStream(URL url) Obtains an audio input stream from the URL provided.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sound.sampled.Clip

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sound.sampled.Clip

Packages that use Clip
javax.sound.sampled Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Uses of Clip in javax.sound.sampled

Methods in javax.sound.sampled that return Clip
static Clip | AudioSystem.getClip() Obtains a clip that can be used for playing back an audio file or an audio stream.
static Clip | AudioSystem.getClip(Mixer.Info mixerInfo) Obtains a clip from the specified mixer that can be used for playing back an audio file or an audio stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sound.sampled.DataLine

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sound.sampled.DataLine

Packages that use DataLine
javax.sound.sampled Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Uses of DataLine in javax.sound.sampled

Subinterfaces of DataLine in javax.sound.sampled
interface | Clip The Clip interface represents a special kind of data line whose audio data can be loaded prior to playback, instead of being streamed in real time.
interface | SourceDataLine A source data line is a data line to which data may be written.
interface | TargetDataLine A target data line is a type of DataLine from which audio data can be read.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sound.sampled.Line

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sound.sampled.Line

Packages that use Line
javax.sound.sampled Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Uses of Line in javax.sound.sampled

Subinterfaces of Line in javax.sound.sampled
interface | Clip The Clip interface represents a special kind of data line whose audio data can be loaded prior to playback, instead of being streamed in real time.
interface | DataLine DataLine adds media-related functionality to its superinterface, Line.
interface | Mixer A mixer is an audio device with one or more lines.
interface | Port Ports are simple lines for input or output of audio to or from audio devices.
interface | SourceDataLine A source data line is a data line to which data may be written.
interface | TargetDataLine A target data line is a type of DataLine from which audio data can be read.

Methods in javax.sound.sampled that return Line
Line | LineEvent.getLine() Obtains the audio line that is the source of this event.
Line | Mixer.getLine(Line.Info info) Obtains a line that is available for use and that matches the description in the specified Line.Info object.
static Line | AudioSystem.getLine(Line.Info info) Obtains a line that matches the description in the specified Line.Info object.
Line[] | Mixer.getSourceLines() Obtains the set of all source lines currently open to this mixer.
Line[] | Mixer.getTargetLines() Obtains the set of all target lines currently open from this mixer.

Methods in javax.sound.sampled with parameters of type Line
boolean | Mixer.isSynchronizationSupported(Line[] lines, boolean maintainSync) Reports whether this mixer supports synchronization of the specified set of lines.
void | Mixer.synchronize(Line[] lines, boolean maintainSync) Synchronizes two or more lines.
void | Mixer.unsynchronize(Line[] lines) Releases synchronization for the specified lines.

Constructors in javax.sound.sampled with parameters of type Line
LineEvent(Line line, LineEvent.Type type, long position)
Constructs a new event of the specified type, originating from the specified line.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sound.sampled.LineListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sound.sampled.LineListener

Packages that use LineListener
javax.sound.sampled Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Uses of LineListener in javax.sound.sampled

Methods in javax.sound.sampled with parameters of type LineListener
void | Line.addLineListener(LineListener listener) Adds a listener to this line.
void | Line.removeLineListener(LineListener listener) Removes the specified listener from this line's list of listeners.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sound.sampled.Mixer

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sound.sampled.Mixer

Packages that use Mixer
javax.sound.sampled | Provides interfaces and classes for capture, processing, and playback of sampled audio data.
javax.sound.sampled.spi | Supplies abstract classes for service providers to subclass when offering new audio devices, sound file readers and writers, or audio format converters.

Uses of Mixer in javax.sound.sampled

Methods in javax.sound.sampled that return Mixer
static Mixer AudioSystem.getMixer(Mixer.Info info)
Obtains the requested audio mixer.

Uses of Mixer in javax.sound.sampled.spi

Methods in javax.sound.sampled.spi that return Mixer
abstract  Mixer MixerProvider.getMixer(Mixer.Info info)
Obtains an instance of the mixer represented by the info object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sound.sampled.Port

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sound.sampled.Port

No usage of javax.sound.sampled.Port

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sound.sampled.SourceDataLine

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sound.sampled.SourceDataLine

Packages that use SourceDataLine
javax.sound.sampled Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Uses of SourceDataLine in javax.sound.sampled

Methods in javax.sound.sampled that return SourceDataLine
static SourceDataLine | AudioSystem.getSourceDataLine(AudioFormat format) Obtains a source data line that can be used for playing back audio data in the format specified by the AudioFormat object.
static SourceDataLine | AudioSystem.getSourceDataLine(AudioFormat format, Mixer.Info mixerinfo) Obtains a source data line that can be used for playing back audio data in the format specified by the AudioFormat object, provided by the mixer specified by the Mixer.Info object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sound.sampled.TargetDataLine

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sound.sampled.TargetDataLine

Packages that use TargetDataLine
javax.sound.sampled Provides interfaces and classes for capture, processing, and playback of sampled audio data.

Uses of TargetDataLine in javax.sound.sampled

Methods in javax.sound.sampled that return TargetDataLine
static TargetDataLine | AudioSystem.getTargetDataLine(AudioFormat format) Obtains a target data line that can be used for recording audio data in the format specified by the AudioFormat object.
static TargetDataLine | AudioSystem.getTargetDataLine(AudioFormat format, Mixer.Info mixerinfo) Obtains a target data line that can be used for recording audio data in the format specified by the AudioFormat object, provided by the mixer specified by the Mixer.Info object.

Constructors in javax.sound.sampled with parameters of type TargetDataLine
AudioInputStream(TargetDataLine line)
Constructs an audio input stream that reads its data from the target data line indicated.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Clip

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Interface Clip

All Superinterfaces:
DataLine, Line
public interface Clip
extends DataLine

The Clip interface represents a special kind of data line whose audio data can be loaded prior to playback, instead of being streamed in real time.

Because the data is pre-loaded and has a known length, you can set a clip to start playing at any position in its audio data. You can also create a loop, so that when the clip is played it will cycle repeatedly. Loops are specified with a starting and ending sample frame, along with the number of times that the loop should be played.

Clips may be obtained from a Mixer that supports lines of this type. Data is loaded into a clip when it is opened.

Playback of an audio clip may be started and stopped using the start and stop methods. These methods do not reset the media position; start causes playback to continue from the position where playback was last stopped. To restart playback from the beginning of the clip's audio data, simply follow the invocation of stop with setFramePosition(0), which rewinds the media to the beginning of the clip.

Since:
1.3

Nested Class Summary
Nested classes/interfaces inherited from interface javax.sound.sampled.DataLine
DataLine.Info
Field Summary
static int LOOP_CONTINUOUSLY
A value indicating that looping should continue indefinitely rather than complete after a specific number of loops.
Method Summary
int | getFrameLength() Obtains the media length in sample frames.
long | getMicrosecondLength() Obtains the media duration in microseconds
void | loop(int count) Starts looping playback from the current position.
void | open(AudioFormat format, byte[] data, int offset, int bufferSize) Opens the clip, meaning that it should acquire any required system resources and become operational.
void | open(AudioInputStream stream) Opens the clip with the format and audio data present in the provided audio input stream.
void | setFramePosition(int frames) Sets the media position in sample frames.
void | setLoopPoints(int start, int end) Sets the first and last sample frames that will be played in the loop.
void | setMicrosecondPosition(long microseconds) Sets the media position in microseconds.
Methods inherited from interface javax.sound.sampled.DataLine
available, drain, flush, getBufferSize, getFormat, getFramePosition, getLevel, getLongFramePosition, getMicrosecondPosition, isActive, isRunning, start, stop
Methods inherited from interface javax.sound.sampled.Line
addLineListener, close, getControl, getControls, getLineInfo, isControlSupported, isOpen, open, removeLineListener

Field Detail

LOOP_CONTINUOUSLY

static final int LOOP_CONTINUOUSLY
A value indicating that looping should continue indefinitely rather than complete after a specific number of loops.

See Also:
loop(int), Constant Field Values
Method Detail

open

void open(AudioFormat format,
          byte[] data,
          int offset,
          int bufferSize)
          throws LineUnavailableException
Opens the clip, meaning that it should acquire any required system resources and become operational. The clip is opened with the format and audio data indicated. If this operation succeeds, the line is marked as open and an OPEN event is dispatched to the line's listeners.

Invoking this method on a line which is already open is illegal and may result in an IllegalStateException.

Note that some lines, once closed, cannot be reopened. Attempts to reopen such a line will always result in a LineUnavailableException.

Parameters:
format - the format of the supplied audio data
data - a byte array containing audio data to load into the clip
offset - the point at which to start copying, expressed in bytes from the beginning of the array
bufferSize - the number of bytes of data to load into the clip from the array.
Throws:
LineUnavailableException - if the line cannot be opened due to resource restrictions
IllegalArgumentException - if the buffer size does not represent an integral number of sample frames, or if format is not fully specified or invalid
IllegalStateException - if the line is already open
SecurityException - if the line cannot be opened due to security restrictions
See Also:
Line.close(), Line.isOpen(), LineListener

open

void open(AudioInputStream stream)
          throws LineUnavailableException,
                 IOException
Opens the clip with the format and audio data present in the provided audio input stream. Opening a clip means that it should acquire any required system resources and become operational. If this operation input stream. If this operation succeeds, the line is marked open and an OPEN event is dispatched to the line's listeners.

Invoking this method on a line which is already open is illegal and may result in an IllegalStateException.

Note that some lines, once closed, cannot be reopened. Attempts to reopen such a line will always result in a LineUnavailableException.

Parameters:
stream - an audio input stream from which audio data will be read into the clip
Throws:
LineUnavailableException - if the line cannot be opened due to resource restrictions
IOException - if an I/O exception occurs during reading of the stream
IllegalArgumentException - if the stream's audio format is not fully specified or invalid
IllegalStateException - if the line is already open
SecurityException - if the line cannot be opened due to security restrictions
See Also:
Line.close(), Line.isOpen(), LineListener

getFrameLength

int getFrameLength()
Obtains the media length in sample frames.

Returns:
the media length, expressed in sample frames, or AudioSystem.NOT_SPECIFIED if the line is not open.
See Also:
AudioSystem.NOT_SPECIFIED

getMicrosecondLength

long getMicrosecondLength()
Obtains the media duration in microseconds

Returns:
the media duration, expressed in microseconds, or AudioSystem.NOT_SPECIFIED if the line is not open.
See Also:
AudioSystem.NOT_SPECIFIED

setFramePosition

void setFramePosition(int frames)
Sets the media position in sample frames. The position is zero-based; the first frame is frame number zero. When the clip begins playing the next time, it will start by playing the frame at this position.

To obtain the current position in sample frames, use the getFramePosition method of DataLine.

Parameters:
frames - the desired new media position, expressed in sample frames

setMicrosecondPosition

void setMicrosecondPosition(long microseconds)
Sets the media position in microseconds. When the clip begins playing the next time, it will start at this position. The level of precision is not guaranteed. For example, an implementation might calculate the microsecond position from the current frame position and the audio sample frame rate. The precision in microseconds would then be limited to the number of microseconds per sample frame.

To obtain the current position in microseconds, use the getMicrosecondPosition method of DataLine.

Parameters:
microseconds - the desired new media position, expressed in microseconds

setLoopPoints

void setLoopPoints(int start,
                   int end)
Sets the first and last sample frames that will be played in the loop. The ending point must be greater than or equal to the starting point, and both must fall within the the size of the loaded media. A value of 0 for the starting point means the beginning of the loaded media. Similarly, a value of -1 for the ending point indicates the last frame of the media.

Parameters:
start - the loop's starting position, in sample frames (zero-based)
end - the loop's ending position, in sample frames (zero-based), or -1 to indicate the final frame
Throws:
IllegalArgumentException - if the requested loop points cannot be set, usually because one or both falls outside the media's duration or because the ending point is before the starting point

loop

void loop(int count)
Starts looping playback from the current position. Playback will continue to the loop's end point, then loop back to the loop start point count times, and finally continue playback to the end of the clip.

If the current position when this method is invoked is greater than the loop end point, playback simply continues to the end of the clip without looping.

A count value of 0 indicates that any current looping should cease and playback should continue to the end of the clip. The behavior is undefined when this method is invoked with any other value during a loop operation.

If playback is stopped during looping, the current loop status is cleared; the behavior of subsequent loop and start requests is not affected by an interrupted loop operation.

Parameters:
count - the number of times playback should loop back from the loop's end position to the loop's start position, or LOOP_CONTINUOUSLY to indicate that looping should continue until interrupted
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CompoundControl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class CompoundControl

java.lang.Object
    extended by  javax.sound.sampled.Control
        extended by  javax.sound.sampled.CompoundControl

public abstract class CompoundControl
extends Control

A CompoundControl, such as a graphic equalizer, provides control over two or more related properties, each of which is itself represented as a Control.

Since:
1.3

Nested Class Summary
static class CompoundControl.Type
An instance of the CompoundControl.Type inner class identifies one kind of compound control.
Constructor Summary
protected CompoundControl(CompoundControl.Type type, Control[] memberControls)
Constructs a new compound control object with the given parameters.
Method Summary
Control[] | getMemberControls() Returns the set of member controls that comprise the compound control.
String | toString() Provides a string representation of the control
Methods inherited from class javax.sound.sampled.Control
getType
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CompoundControl

protected CompoundControl(CompoundControl.Type type,
                          Control[] memberControls)
Constructs a new compound control object with the given parameters.

Parameters:
type - the type of control represented this compound control object
memberControls - the set of member controls
Method Detail

getMemberControls

public Control[] getMemberControls()
Returns the set of member controls that comprise the compound control.

Returns:
the set of member controls.

toString

public String toString()
Provides a string representation of the control

Overrides:
toString in class Control
Returns:
a string description
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CompoundControl.Type

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class CompoundControl.Type

java.lang.Object
    extended by  javax.sound.sampled.Control.Type
        extended by  javax.sound.sampled.CompoundControl.Type
Enclosing class:
CompoundControl
public static class CompoundControl.Type
extends Control.Type

An instance of the CompoundControl.Type inner class identifies one kind of compound control. Static instances are provided for the common types.

Since:
1.3

Constructor Summary
protected CompoundControl.Type(String name)
Constructs a new compound control type.
Method Summary
Methods inherited from class javax.sound.sampled.Control.Type
equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

CompoundControl.Type

protected CompoundControl.Type(String name)
Constructs a new compound control type.

Parameters:
name - the name of the new compound control type
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Control

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class Control

java.lang.Object
    extended by  javax.sound.sampled.Control
Direct Known Subclasses:
BooleanControl, CompoundControl, EnumControl, FloatControl
public abstract class Control
extends Object

Lines often have a set of controls, such as gain and pan, that affect the audio signal passing through the line. Java Sound's Line objects let you obtain a particular control object by passing its class as the argument to a getControl method.

Because the various types of controls have different purposes and features, all of their functionality is accessed from the subclasses that define each kind of control.

Since:
1.3
See Also:
Line.getControls(), Line.isControlSupported(javax.sound.sampled.Control.Type)

Nested Class Summary
static class Control.Type
An instance of the Type class represents the type of the control.
Constructor Summary
protected Control(Control.Type type)
Constructs a Control with the specified type.
Method Summary
Control.Type | getType() Obtains the control's type.
String | toString() Obtains a String describing the control type and its current state.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Control

protected Control(Control.Type type)
Constructs a Control with the specified type.

Parameters:
type - the kind of control desired
Method Detail

getType

public Control.Type getType()
Obtains the control's type.

Returns:
the control's type.

toString

public String toString()
Obtains a String describing the control type and its current state.

Overrides:
toString in class Object
Returns:
a String representation of the Control.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Control.Type

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class Control.Type

java.lang.Object
    extended by  javax.sound.sampled.Control.Type
Direct Known Subclasses:
BooleanControl.Type, CompoundControl.Type, EnumControl.Type, FloatControl.Type
Enclosing class:
Control
public static class Control.Type
extends Object

An instance of the Type class represents the type of the control. Static instances are provided for the common types.

Constructor Summary
protected Control.Type(String name)
Constructs a new control type with the name specified.
Method Summary
boolean | equals(Object obj) Finalizes the equals method
int | hashCode() Finalizes the hashCode method
String | toString() Provides the String representation of the control type.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Control.Type

protected Control.Type(String name)
Constructs a new control type with the name specified. The name should be a descriptive string appropriate for labelling the control in an application, such as "Gain" or "Balance."

Parameters:
name - the name of the new control type.
Method Detail

equals

public final boolean equals(Object obj)
Finalizes the equals method

Overrides:
equals in class Object
Parameters:
obj - the reference object with which to compare.
Returns:
true if this object is the same as the obj argument; false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

public final int hashCode()
Finalizes the hashCode method

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public final String toString()
Provides the String representation of the control type. This String is the same name that was passed to the constructor.

Overrides:
toString in class Object
Returns:
the control type name
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DataLine

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Interface DataLine

All Superinterfaces:
Line
All Known Subinterfaces:
Clip, SourceDataLine, TargetDataLine
public interface DataLine
extends Line

DataLine adds media-related functionality to its superinterface, Line. This functionality includes transport-control methods that start, stop, drain, and flush the audio data that passes through the line. A data line can also report the current position, volume, and audio format of the media. Data lines are used for output of audio by means of the subinterfaces SourceDataLine or Clip, which allow an application program to write data. Similarly, audio input is handled by the subinterface TargetDataLine, which allows data to be read.

A data line has an internal buffer in which the incoming or outgoing audio data is queued. The drain() method blocks until this internal buffer becomes empty, usually because all queued data has been processed. The flush() method discards any available queued data from the internal buffer.

A data line produces START and STOP events whenever it begins or ceases active presentation or capture of data. These events can be generated in response to specific requests, or as a result of less direct state changes. For example, if start() is called on an inactive data line, and data is available for capture or playback, a START event will be generated shortly, when data playback or capture actually begins. Or, if the flow of data to an active data line is constricted so that a gap occurs in the presentation of data, a STOP event is generated.

Mixers often support synchronized control of multiple data lines. Synchronization can be established through the Mixer interface's synchronize method. See the description of the Mixer interface for a more complete description.

Since:
1.3
See Also:
LineEvent

Nested Class Summary
static class DataLine.Info
Besides the class information inherited from its superclass, DataLine.Info provides additional information specific to data lines.
Method Summary
int | available() Obtains the number of bytes of data currently available to the application for processing in the data line's internal buffer.
void | drain() Drains queued data from the line by continuing data I/O until the data line's internal buffer has been emptied.
void | flush() Flushes queued data from the line.
int | getBufferSize() Obtains the maximum number of bytes of data that will fit in the data line's internal buffer.
AudioFormat | getFormat() Obtains the current format (encoding, sample rate, number of channels, etc.) of the data line's audio data.
int | getFramePosition() Obtains the current position in the audio data, in sample frames.
float | getLevel() Obtains the current volume level for the line.
long | getLongFramePosition() Obtains the current position in the audio data, in sample frames.
long | getMicrosecondPosition() Obtains the current position in the audio data, in microseconds.
boolean | isActive() Indicates whether the line is engaging in active I/O (such as playback or capture).
boolean | isRunning() Indicates whether the line is running.
void | start() Allows a line to engage in data I/O.
void | stop() Stops the line.
Methods inherited from interface javax.sound.sampled.Line
addLineListener, close, getControl, getControls, getLineInfo, isControlSupported, isOpen, open, removeLineListener

Method Detail

drain

void drain()
Drains queued data from the line by continuing data I/O until the data line's internal buffer has been emptied. This method blocks until the draining is complete. Because this is a blocking method, it should be used with care. If drain() is invoked on a stopped line that has data in its queue, the method will block until the line is running and the data queue becomes empty. If drain() is invoked by one thread, and another continues to fill the data queue, the operation will not complete. This method always returns when the data line is closed.

See Also:
flush()

flush

void flush()
Flushes queued data from the line. The flushed data is discarded. In some cases, not all queued data can be discarded. For example, a mixer can flush data from the buffer for a specific input line, but any unplayed data already in the output buffer (the result of the mix) will still be played. You can invoke this method after pausing a line (the normal case) if you want to skip the "stale" data when you restart playback or capture. (It is legal to flush a line that is not stopped, but doing so on an active line is likely to cause a discontinuity in the data, resulting in a perceptible click.)

See Also:
stop(), drain()

start

void start()
Allows a line to engage in data I/O. If invoked on a line that is already running, this method does nothing. Unless the data in the buffer has been flushed, the line resumes I/O starting with the first frame that was unprocessed at the time the line was stopped. When audio capture or playback starts, a START event is generated.

See Also:
stop(), isRunning(), LineEvent

stop

void stop()
Stops the line. A stopped line should cease I/O activity. If the line is open and running, however, it should retain the resources required to resume activity. A stopped line should retain any audio data in its buffer instead of discarding it, so that upon resumption the I/O can continue where it left off, if possible. (This doesn't guarantee that there will never be discontinuities beyond the current buffer, of course; if the stopped condition continues for too long, input or output samples might be dropped.) If desired, the retained data can be discarded by invoking the flush method. When audio capture or playback stops, a STOP event is generated.

See Also:
start(),
isRunning(),
flush(),
LineEvent

isRunning

boolean isRunning()
Indicates whether the line is running. The default is false. An open line begins running when the first data is presented in response to an invocation of the start method, and continues until presentation ceases in response to a call to stop or because playback completes.

Returns:
true if the line is running, otherwise false
See Also:
start(), stop()

isActive

boolean isActive()
Indicates whether the line is engaging in active I/O (such as playback or capture). When an inactive line becomes active, it sends a START event to its listeners. Similarly, when an active line becomes inactive, it sends a STOP event.

Returns:
true if the line is actively capturing or rendering sound, otherwise false
See Also:
Line.isOpen(),
Line.addLineListener(javax.sound.sampled.LineListener),
Line.removeLineListener(javax.sound.sampled.LineListener),
LineEvent,
LineListener

getFormat

AudioFormat getFormat()
Obtains the current format (encoding, sample rate, number of channels, etc.) of the data line's audio data.

If the line is not open and has never been opened, it returns the default format. The default format is an implementation specific audio format, or, if the DataLine.Info object, which was used to retrieve this DataLine, specifies at least one fully qualified audio format, the last one will be used as the default format. Opening the line with a specific audio format (e.g. SourceDataLine.open(AudioFormat)) will override the default format.

Returns:
current audio data format
See Also:
AudioFormat

getBufferSize

int getBufferSize()
Obtains the maximum number of bytes of data that will fit in the data line's internal buffer. For a source data line, this is the size of the buffer to which data can be written. For a target data line, it is the size of the buffer from which data can be read. Note that the units used are bytes, but will always correspond to an integral number of sample frames of audio data.

Returns:
the size of the buffer in bytes

available

int available()
Obtains the number of bytes of data currently available to the application for processing in the data line's internal buffer. For a source data line, this is the amount of data that can be written to the buffer without blocking. For a target data line, this is the amount of data available to be read by the application. For a clip, this value is always 0 because the audio data is loaded into the buffer when the clip is opened, and persists without modification until the clip is closed.

Note that the units used are bytes, but will always correspond to an integral number of sample frames of audio data.

An application is guaranteed that a read or write operation of up to the number of bytes returned from available() will not block; however, there is no guarantee that attempts to read or write more data will block.

Returns:
the amount of data available, in bytes

getFramePosition

int getFramePosition()
Obtains the current position in the audio data, in sample frames. The frame position measures the number of sample frames captured by, or rendered from, the line since it was opened. This return value will wrap around after 2^31 frames. It is recommended to use getLongFramePosition instead.

Returns:
the number of frames already processed since the line was opened
See Also:
getLongFramePosition()

getLongFramePosition

long getLongFramePosition()
Obtains the current position in the audio data, in sample frames. The frame position measures the number of sample frames captured by, or rendered from, the line since it was opened.

Returns:
the number of frames already processed since the line was opened
Since:
1.5

getMicrosecondPosition

long getMicrosecondPosition()
Obtains the current position in the audio data, in microseconds. The microsecond position measures the time corresponding to the number of sample frames captured by, or rendered from, the line since it was opened. The level of precision is not guaranteed. For example, an implementation might calculate the microsecond position from the current frame position and the audio sample frame rate. The precision in microseconds would then be limited to the number of microseconds per sample frame.

Returns:
the number of microseconds of data processed since the line was opened

getLevel

float getLevel()
Obtains the current volume level for the line. This level is a measure of the signal's current amplitude, and should not be confused with the current setting of a gain control. The range is from 0.0 (silence) to 1.0 (maximum possible amplitude for the sound waveform). The units measure linear amplitude, not decibels.

Returns:
the current amplitude of the signal in this line, or AudioSystem.NOT_SPECIFIED
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DataLine.Info

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class DataLine.Info

java.lang.Object
    extended by  javax.sound.sampled.Line.Info
        extended by  javax.sound.sampled.DataLine.Info
Enclosing interface:
DataLine
public static class DataLine.Info
extends Line.Info

Besides the class information inherited from its superclass, DataLine.Info provides additional information specific to data lines. This information includes:

  • the audio formats supported by the data line
  • the minimum and maximum sizes of its internal buffer
Because a Line.Info knows the class of the line its describes, a DataLine.Info object can describe DataLine subinterfaces such as SourceDataLine, TargetDataLine, and Clip. You can query a mixer for lines of any of these types, passing an appropriate instance of DataLine.Info as the argument to a method such as Mixer.getLine(Line.Info).

Since:
1.3
See Also:
Line.Info

Constructor Summary
DataLine.Info(Class<?> lineClass, AudioFormat format)
Constructs a data line's info object from the specified information, which includes a single audio format.
DataLine.Info(Class<?> lineClass, AudioFormat[] formats, int minBufferSize, int maxBufferSize)
Constructs a data line's info object from the specified information, which includes a set of supported audio formats and a range for the buffer size.
DataLine.Info(Class<?> lineClass, AudioFormat format, int bufferSize)
Constructs a data line's info object from the specified information, which includes a single audio format and a desired buffer size.
Method Summary
AudioFormat[] | getFormats() Obtains a set of audio formats supported by the data line.
int | getMaxBufferSize() Obtains the maximum buffer size supported by the data line.
int | getMinBufferSize() Obtains the minimum buffer size supported by the data line.
boolean | isFormatSupported(AudioFormat format) Indicates whether this data line supports a particular audio format.
boolean | matches(Line.Info info) Determines whether the specified info object matches this one.
String | toString() Obtains a textual description of the data line info.
Methods inherited from class javax.sound.sampled.Line.Info
getLineClass
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DataLine.Info

public DataLine.Info(Class<?> lineClass,
                     AudioFormat[] formats,
                     int minBufferSize,
                     int maxBufferSize)
Constructs a data line's info object from the specified information, which includes a set of supported audio formats and a range for the buffer size. This constructor is typically used by mixer implementations when returning information about a supported line.

Parameters:
lineClass - the class of the data line described by the info object
formats - set of formats supported
minBufferSize - minimum buffer size supported by the data line, in bytes
maxBufferSize - maximum buffer size supported by the data line, in bytes

DataLine.Info

public DataLine.Info(Class<?> lineClass,
                     AudioFormat format,
                     int bufferSize)
Constructs a data line's info object from the specified information, which includes a single audio format and a desired buffer size. This constructor is typically used by an application to describe a desired line.

Parameters:
lineClass - the class of the data line described by the info object
format - desired format
bufferSize - desired buffer size in bytes

DataLine.Info

public DataLine.Info(Class<?> lineClass,
                     AudioFormat format)
Constructs a data line's info object from the specified information, which includes a single audio format. This constructor is typically used by an application to describe a desired line.

Parameters:
lineClass - the class of the data line described by the info object
format - desired format
Method Detail

getFormats

public AudioFormat[] getFormats()
Obtains a set of audio formats supported by the data line. Note that isFormatSupported(AudioFormat) might return true for certain additional formats that are missing from the set returned by getFormats(). The reverse is not the case: isFormatSupported(AudioFormat) is guaranteed to return true for all formats returned by getFormats(). Some fields in the AudioFormat instances can be set to NOT_SPECIFIED if that field does not apply to the format, or if the format supports a wide range of values for that field. For example, a multi-channel device supporting up to 64 channels, could set the channel field in the AudioFormat instances returned by this method to NOT_SPECIFIED.

Returns:
a set of supported audio formats.
See Also:
isFormatSupported(AudioFormat)

isFormatSupported

public boolean isFormatSupported(AudioFormat format)
Indicates whether this data line supports a particular audio format. The default implementation of this method simply returns true if the specified format matches any of the supported formats.

Parameters:
format - the audio format for which support is queried.
Returns:
true if the format is supported, otherwise false
See Also:
getFormats(), AudioFormat.matches(javax.sound.sampled.AudioFormat)

getMinBufferSize

public int getMinBufferSize()
Obtains the minimum buffer size supported by the data line.

Returns:
minimum buffer size in bytes, or AudioSystem.NOT_SPECIFIED

getMaxBufferSize

public int getMaxBufferSize()
Obtains the maximum buffer size supported by the data line.

Returns:
maximum buffer size in bytes, or AudioSystem.NOT_SPECIFIED

matches

public boolean matches(Line.Info info)
Determines whether the specified info object matches this one. To match, the superclass match requirements must be met. In addition, this object's minimum buffer size must be at least as large as that of the object specified, its maximum buffer size must be at most as large as that of the object specified, and all of its formats must match formats supported by the object specified.

Overrides:
matches in class Line.Info
Parameters:
info - the info object which is being compared to this one
Returns:
true if this object matches the one specified, otherwise false.

toString

public String toString()
Obtains a textual description of the data line info.

Overrides:
toString in class Line.Info
Returns:
a string description
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EnumControl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class EnumControl

java.lang.Object
    extended by  javax.sound.sampled.Control
        extended by  javax.sound.sampled.EnumControl

public abstract class EnumControl
extends Control

A EnumControl provides control over a set of discrete possible values, each represented by an object. In a graphical user interface, such a control might be represented by a set of buttons, each of which chooses one value or setting. For example, a reverb control might provide several preset reverberation settings, instead of providing continuously adjustable parameters of the sort that would be represented by FloatControl objects.

Controls that provide a choice between only two settings can often be implemented instead as a BooleanControl, and controls that provide a set of values along some quantifiable dimension might be implemented instead as a FloatControl with a coarse resolution. However, a key feature of EnumControl is that the returned values are arbitrary objects, rather than numerical or boolean values. This means that each returned object can provide further information. As an example, the settings of a REVERB control are instances of ReverbType that can be queried for the parameter values used for each setting.

Since:
1.3

Nested Class Summary
static class EnumControl.Type
An instance of the EnumControl.Type inner class identifies one kind of enumerated control.
Constructor Summary
protected EnumControl(EnumControl.Type type, Object[] values, Object value)
Constructs a new enumerated control object with the given parameters.
Method Summary
Object | getValue() Obtains this control's current value.
Object[] | getValues() Returns the set of possible values for this control.
void | setValue(Object value) Sets the current value for the control.
String | toString() Provides a string representation of the control.
Methods inherited from class javax.sound.sampled.Control
getType
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

EnumControl

protected EnumControl(EnumControl.Type type,
                      Object[] values,
                      Object value)
Constructs a new enumerated control object with the given parameters.

Parameters:
type - the type of control represented this enumerated control object
values - the set of possible values for the control
value - the initial control value
Method Detail

setValue

public void setValue(Object value)
Sets the current value for the control. The default implementation simply sets the value as indicated. If the value indicated is not supported, an IllegalArgumentException is thrown. Some controls require that their line be open before they can be affected by setting a value.

Parameters:
value - the desired new value
Throws:
IllegalArgumentException - if the value indicated does not fall within the allowable range

getValue

public Object getValue()
Obtains this control's current value.

Returns:
the current value

getValues

public Object[] getValues()
Returns the set of possible values for this control.

Returns:
the set of possible values

toString

public String toString()
Provides a string representation of the control.

Overrides:
toString in class Control
Returns:
a string description
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EnumControl.Type

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class EnumControl.Type

java.lang.Object
    extended by  javax.sound.sampled.Control.Type
        extended by  javax.sound.sampled.EnumControl.Type
Enclosing class:
EnumControl
public static class EnumControl.Type
extends Control.Type

An instance of the EnumControl.Type inner class identifies one kind of enumerated control. Static instances are provided for the common types.

Since:
1.3
See Also:
EnumControl

Field Summary
static EnumControl.Type REVERB
Represents a control over a set of possible reverberation settings.
Constructor Summary
protected EnumControl.Type(String name)
Constructs a new enumerated control type.
Method Summary
Methods inherited from class javax.sound.sampled.Control.Type
equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

REVERB

public static final EnumControl.Type REVERB
Represents a control over a set of possible reverberation settings. Each reverberation setting is described by an instance of the ReverbType class. (To access these settings, invoke EnumControl.getValues() on an enumerated control of type REVERB.)

Constructor Detail

EnumControl.Type

protected EnumControl.Type(String name)
Constructs a new enumerated control type.

Parameters:
name - the name of the new enumerated control type
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FloatControl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class FloatControl

java.lang.Object
    extended by  javax.sound.sampled.Control
        extended by  javax.sound.sampled.FloatControl

public abstract class FloatControl
extends Control

A FloatControl object provides control over a range of floating-point values. Float controls are often represented in graphical user interfaces by continuously adjustable objects such as sliders or rotary knobs. Concrete subclasses of FloatControl implement controls, such as gain and pan, that affect a line's audio signal in some way that an application can manipulate. The FloatControl.Type inner class provides static instances of types that are used to identify some common kinds of float control.

The FloatControl abstract class provides methods to set and get the control's current floating-point value. Other methods obtain the possible range of values and the control's resolution (the smallest increment between returned values). Some float controls allow ramping to a new value over a specified period of time. FloatControl also includes methods that return string labels for the minimum, maximum, and midpoint positions of the control.

Since:
1.3
See Also:
Line.getControls(), Line.isControlSupported(javax.sound.sampled.Control.Type)

Nested Class Summary
static class FloatControl.Type
An instance of the FloatControl.Type inner class identifies one kind of float control.
Constructor Summary
protected | FloatControl(FloatControl.Type type, float minimum, float maximum, float precision, int updatePeriod, float initialValue, String units) Constructs a new float control object with the given parameters.
protected | FloatControl(FloatControl.Type type, float minimum, float maximum, float precision, int updatePeriod, float initialValue, String units, String minLabel, String midLabel, String maxLabel) Constructs a new float control object with the given parameters
Method Summary
float | getMaximum() Obtains the maximum value permitted.
String | getMaxLabel() Obtains the label for the maximum value, such as "Right" or "Full."
String | getMidLabel() Obtains the label for the mid-point value, such as "Center" or "Default."
float | getMinimum() Obtains the minimum value permitted.
String | getMinLabel() Obtains the label for the minimum value, such as "Left" or "Off."
float | getPrecision() Obtains the resolution or granularity of the control, in the units that the control measures.
String | getUnits() Obtains the label for the units in which the control's values are expressed, such as "dB" or "frames per second."
int | getUpdatePeriod() Obtains the smallest time interval, in microseconds, over which the control's value can change during a shift.
float | getValue() Obtains this control's current value.
void | setValue(float newValue) Sets the current value for the control.
void | shift(float from, float to, int microseconds) Changes the control value from the initial value to the final value linearly over the specified time period, specified in microseconds.
String | toString() Provides a string representation of the control
Methods inherited from class javax.sound.sampled.Control
getType
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

FloatControl

protected FloatControl(FloatControl.Type type,
                       float minimum,
                       float maximum,
                       float precision,
                       int updatePeriod,
                       float initialValue,
                       String units,
                       String minLabel,
                       String midLabel,
                       String maxLabel)
Constructs a new float control object with the given parameters

Parameters:
type - the kind of control represented by this float control object
minimum - the smallest value permitted for the control
maximum - the largest value permitted for the control
precision - the resolution or granularity of the control. This is the size of the increment between discrete valid values.
updatePeriod - the smallest time interval, in microseconds, over which the control can change from one discrete value to the next during a shift
initialValue - the value that the control starts with when constructed
units - the label for the units in which the control's values are expressed, such as "dB" or "frames per second"
minLabel - the label for the minimum value, such as "Left" or "Off"
midLabel - the label for the midpoint value, such as "Center" or "Default"
maxLabel - the label for the maximum value, such as "Right" or "Full"

FloatControl

protected FloatControl(FloatControl.Type type,
                       float minimum,
                       float maximum,
                       float precision,
                       int updatePeriod,
                       float initialValue,
                       String units)
Constructs a new float control object with the given parameters. The labels for the minimum, maximum, and mid-point values are set to zero-length strings.

Parameters:
type - the kind of control represented by this float control object
minimum - the smallest value permitted for the control
maximum - the largest value permitted for the control
precision - the resolution or granularity of the control. This is the size of the increment between discrete valid values.
updatePeriod - the smallest time interval, in microseconds, over which the control can change from one discrete value to the next during a shift
initialValue - the value that the control starts with when constructed
units - the label for the units in which the control's values are expressed, such as "dB" or "frames per second"
Method Detail

setValue

public void setValue(float newValue)
Sets the current value for the control. The default implementation simply sets the value as indicated. If the value indicated is greater than the maximum value, or smaller than the minimum value, an IllegalArgumentException is thrown. Some controls require that their line be open before they can be affected by setting a value.

Parameters:
newValue - desired new value
Throws:
IllegalArgumentException - if the value indicated does not fall within the allowable range

getValue

public float getValue()
Obtains this control's current value.

Returns:
the current value

getMaximum

public float getMaximum()
Obtains the maximum value permitted.

Returns:
the maximum allowable value

getMinimum

public float getMinimum()
Obtains the minimum value permitted.

Returns:
the minimum allowable value

getUnits

public String getUnits()
Obtains the label for the units in which the control's values are expressed, such as "dB" or "frames per second."

Returns:
the units label, or a zero-length string if no label

getMinLabel

public String getMinLabel()
Obtains the label for the minimum value, such as "Left" or "Off."

Returns:
the minimum value label, or a zero-length string if no label * has been set

getMidLabel

public String getMidLabel()
Obtains the label for the mid-point value, such as "Center" or "Default."

Returns:
the mid-point value label, or a zero-length string if no label * has been set

getMaxLabel

public String getMaxLabel()
Obtains the label for the maximum value, such as "Right" or "Full."

Returns:
the maximum value label, or a zero-length string if no label * has been set

getPrecision

public float getPrecision()
Obtains the resolution or granularity of the control, in the units that the control measures. The precision is the size of the increment between discrete valid values for this control, over the set of supported floating-point values.

Returns:
the control's precision

getUpdatePeriod

public int getUpdatePeriod()
Obtains the smallest time interval, in microseconds, over which the control's value can change during a shift. The update period is the inverse of the frequency with which the control updates its value during a shift. If the implementation does not support value shifting over time, it should set the control's value to the final value immediately and return -1 from this method.

Returns:
update period in microseconds, or -1 if shifting over time is unsupported
See Also:
shift(float, float, int)

shift

public void shift(float from,
                  float to,
                  int microseconds)
Changes the control value from the initial value to the final value linearly over the specified time period, specified in microseconds. This method returns without blocking; it does not wait for the shift to complete. An implementation should complete the operation within the time specified. The default implementation simply changes the value to the final value immediately.

Parameters:
from - initial value at the beginning of the shift
to - final value after the shift
microseconds - maximum duration of the shift in microseconds
See Also:
getUpdatePeriod()

toString

public String toString()
Provides a string representation of the control

Overrides:
toString in class Control
Returns:
a string description
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FloatControl.Type

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class FloatControl.Type

java.lang.Object
    extended by  javax.sound.sampled.Control.Type
        extended by  javax.sound.sampled.FloatControl.Type
Enclosing class:
FloatControl
public static class FloatControl.Type
extends Control.Type

An instance of the FloatControl.Type inner class identifies one kind of float control. Static instances are provided for the common types.

Since:
1.3

Field Summary
static FloatControl.Type | AUX_RETURN Represents a control for the auxiliary return gain on a line.
static FloatControl.Type | AUX_SEND Represents a control for the auxiliary send gain on a line.
static FloatControl.Type | BALANCE Represents a control for the relative balance of a stereo signal between two stereo speakers.
static FloatControl.Type | MASTER_GAIN Represents a control for the overall gain on a line.
static FloatControl.Type | PAN Represents a control for the relative pan (left-right positioning) of the signal.
static FloatControl.Type | REVERB_RETURN Represents a control for the post-reverb gain on a line.
static FloatControl.Type | REVERB_SEND Represents a control for the pre-reverb gain on a line.
static FloatControl.Type | SAMPLE_RATE Represents a control that changes the sample rate of audio playback.
static FloatControl.Type | VOLUME Represents a control for the volume on a line.
Constructor Summary
protected FloatControl.Type(String name)
Constructs a new float control type.
Method Summary
Methods inherited from class javax.sound.sampled.Control.Type
equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

MASTER_GAIN

public static final FloatControl.Type MASTER_GAIN
Represents a control for the overall gain on a line.

Gain is a quantity in decibels (dB) that is added to the intrinsic decibel level of the audio signal--that is, the level of the signal before it is altered by the gain control. A positive gain amplifies (boosts) the signal's volume, and a negative gain attenuates (cuts) it. The gain setting defaults to a value of 0.0 dB, meaning the signal's loudness is unaffected. Note that gain measures dB, not amplitude. The relationship between a gain in decibels and the corresponding linear amplitude multiplier is:

linearScalar = pow(10.0, gainDB/20.0)

The FloatControl class has methods to impose a maximum and minimum allowable value for gain. However, because an audio signal might already be at a high amplitude, the maximum setting does not guarantee that the signal will be undistorted when the gain is applied to it (unless the maximum is zero or negative). To avoid numeric overflow from excessively large gain settings, a gain control can implement clipping, meaning that the signal's amplitude will be limited to the maximum value representable by its audio format, instead of wrapping around.

These comments apply to gain controls in general, not just master gain controls. A line can have more than one gain control. For example, a mixer (which is itself a line) might have a master gain control, an auxiliary return control, a reverb return control, and, on each of its source lines, an individual aux send and reverb send.

See Also:
AUX_SEND, AUX_RETURN, REVERB_SEND, REVERB_RETURN, VOLUME

AUX_SEND

public static final FloatControl.Type AUX_SEND
Represents a control for the auxiliary send gain on a line.

See Also:
MASTER_GAIN, AUX_RETURN

AUX_RETURN

public static final FloatControl.Type AUX_RETURN
Represents a control for the auxiliary return gain on a line.

See Also:
MASTER_GAIN, AUX_SEND

REVERB_SEND

public static final FloatControl.Type REVERB_SEND
Represents a control for the pre-reverb gain on a line. This control may be used to affect how much of a line's signal is directed to a mixer's internal reverberation unit.

See Also:
MASTER_GAIN, REVERB_RETURN, EnumControl.Type.REVERB

REVERB_RETURN

public static final FloatControl.Type REVERB_RETURN
Represents a control for the post-reverb gain on a line. This control may be used to control the relative amplitude of the signal returned from an internal reverberation unit.

See Also:
MASTER_GAIN, REVERB_SEND

VOLUME

public static final FloatControl.Type VOLUME
Represents a control for the volume on a line.

PAN

public static final FloatControl.Type PAN
Represents a control for the relative pan (left-right positioning) of the signal. The signal may be mono; the pan setting affects how it is distributed by the mixer in a stereo mix. The valid range of values is -1.0 (left channel only) to 1.0 (right channel only). The default is 0.0 (centered).

See Also:
BALANCE

BALANCE

public static final FloatControl.Type BALANCE
Represents a control for the relative balance of a stereo signal between two stereo speakers. The valid range of values is -1.0 (left channel only) to 1.0 (right channel only). The default is 0.0 (centered).

See Also:
PAN

SAMPLE_RATE

public static final FloatControl.Type SAMPLE_RATE
Represents a control that changes the sample rate of audio playback. The net effect of changing the sample rate depends on the relationship between the media's natural rate and the rate that is set via this control. The natural rate is the sample rate that is specified in the data line's AudioFormat object. For example, if the natural rate of the media is 11025 samples per second and the sample rate is set to 22050 samples per second, the media will play back at twice the normal speed.

Changing the sample rate with this control does not affect the data line's audio format. Also note that whenever you change a sound's sample rate, a change in the sound's pitch results. For example, doubling the sample rate has the effect of doubling the frequencies in the sound's spectrum, which raises the pitch by an octave.

Constructor Detail

FloatControl.Type

protected FloatControl.Type(String name)
Constructs a new float control type.

Parameters:
name - the name of the new float control type
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Line

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Interface Line

All Known Subinterfaces:
Clip, DataLine, Mixer, Port, SourceDataLine, TargetDataLine
public interface Line

The Line interface represents a mono or multi-channel audio feed. A line is an element of the digital audio "pipeline," such as a mixer, an input or output port, or a data path into or out of a mixer.

A line can have controls, such as gain, pan, and reverb. The controls themselves are instances of classes that extend the base Control class. The Line interface provides two accessor methods for obtaining the line's controls: getControls returns the entire set, and getControl returns a single control of specified type.

Lines exist in various states at different times. When a line opens, it reserves system resources for itself, and when it closes, these resources are freed for other objects or applications. The isOpen() method lets you discover whether a line is open or closed. An open line need not be processing data, however. Such processing is typically initiated by subinterface methods such as SourceDataLine.write and TargetDataLine.read.

You can register an object to receive notifications whenever the line's state changes. The object must implement the LineListener interface, which consists of the single method update. This method will be invoked when a line opens and closes (and, if it's a DataLine, when it starts and stops).

An object can be registered to listen to multiple lines. The event it receives in its update method will specify which line created the event, what type of event it was (OPEN, CLOSE, START, or STOP), and how many sample frames the line had processed at the time the event occurred.

Certain line operations, such as open and close, can generate security exceptions if invoked by unprivileged code when the line is a shared audio resource.

Since:
1.3
See Also:
LineEvent

Nested Class Summary
static class Line.Info
A Line.Info object contains information about a line.
Method Summary
void | addLineListener(LineListener listener) Adds a listener to this line.
void | close() Closes the line, indicating that any system resources in use by the line can be released.
Control | getControl(Control.Type control) Obtains a control of the specified type, if there is any.
Control[] | getControls() Obtains the set of controls associated with this line.
Line.Info | getLineInfo() Obtains the Line.Info object describing this line.
boolean | isControlSupported(Control.Type control) Indicates whether the line supports a control of the specified type.
boolean | isOpen() Indicates whether the line is open, meaning that it has reserved system resources and is operational, although it might not currently be playing or capturing sound.
void | open() Opens the line, indicating that it should acquire any required system resources and become operational.
void | removeLineListener(LineListener listener) Removes the specified listener from this line's list of listeners.

Method Detail

getLineInfo

Line.Info getLineInfo()
Obtains the Line.Info object describing this line.

Returns:
description of the line

open

void open()
          throws LineUnavailableException
Opens the line, indicating that it should acquire any required system resources and become operational. If this operation succeeds, the line is marked as open, and an OPEN event is dispatched to the line's listeners.

Note that some lines, once closed, cannot be reopened. Attempts to reopen such a line will always result in an LineUnavailableException.

Some types of lines have configurable properties that may affect resource allocation. For example, a DataLine must be opened with a particular format and buffer size. Such lines should provide a mechanism for configuring these properties, such as an additional open method or methods which allow an application to specify the desired settings.

This method takes no arguments, and opens the line with the current settings. For SourceDataLine and TargetDataLine objects, this means that the line is opened with default settings. For a Clip, however, the buffer size is determined when data is loaded. Since this method does not allow the application to specify any data to load, an IllegalArgumentException is thrown. Therefore, you should instead use one of the open methods provided in the Clip interface to load data into the Clip.

For DataLine's, if the DataLine.Info object which was used to retrieve the line, specifies at least one fully qualified audio format, the last one will be used as the default format.

Throws:
IllegalArgumentException - if this method is called on a Clip instance.
LineUnavailableException - if the line cannot be opened due to resource restrictions.
SecurityException - if the line cannot be opened due to security restrictions.
See Also:
close(), isOpen(), LineEvent, DataLine, Clip.open(AudioFormat, byte[], int, int), Clip.open(AudioInputStream)

close

void close()
Closes the line, indicating that any system resources in use by the line can be released. If this operation succeeds, the line is marked closed and a CLOSE event is dispatched to the line's listeners.

Throws:
SecurityException - if the line cannot be closed due to security restrictions.
See Also:
open(), isOpen(), LineEvent

isOpen

boolean isOpen()
Indicates whether the line is open, meaning that it has reserved system resources and is operational, although it might not currently be playing or capturing sound.

Returns:
true if the line is open, otherwise false
See Also:
open(), close()

getControls

Control[] getControls()
Obtains the set of controls associated with this line. Some controls may only be available when the line is open. If there are no controls, this method returns an array of length 0.

Returns:
the array of controls
See Also:
getControl(javax.sound.sampled.Control.Type)

isControlSupported

boolean isControlSupported(Control.Type control)
Indicates whether the line supports a control of the specified type. Some controls may only be available when the line is open.

Parameters:
control - the type of the control for which support is queried
Returns:
true if at least one control of the specified type is supported, otherwise false.

getControl

Control getControl(Control.Type control)
Obtains a control of the specified type, if there is any. Some controls may only be available when the line is open.

Parameters:
control - the type of the requested control
Returns:
a control of the specified type
Throws:
IllegalArgumentException - if a control of the specified type is not supported
See Also:
getControls(), isControlSupported(Control.Type control)

addLineListener

void addLineListener(LineListener listener)
Adds a listener to this line. Whenever the line's status changes, the listener's update() method is called with a LineEvent object that describes the change.

Parameters:
listener - the object to add as a listener to this line
See Also:
removeLineListener(javax.sound.sampled.LineListener), LineListener.update(javax.sound.sampled.LineEvent), LineEvent

removeLineListener

void removeLineListener(LineListener listener)
Removes the specified listener from this line's list of listeners.

Parameters:
listener - listener to remove
See Also:
addLineListener(javax.sound.sampled.LineListener)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Line.Info

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class Line.Info

java.lang.Object
    extended by  javax.sound.sampled.Line.Info
Direct Known Subclasses:
DataLine.Info, Port.Info
Enclosing interface:
Line
public static class Line.Info
extends Object

A Line.Info object contains information about a line. The only information provided by Line.Info itself is the Java class of the line. A subclass of Line.Info adds other kinds of information about the line. This additional information depends on which Line subinterface is implemented by the kind of line that the Line.Info subclass describes.

A Line.Info can be retrieved using various methods of the Line, Mixer, and AudioSystem interfaces. Other such methods let you pass a Line.Info as an argument, to learn whether lines matching the specified configuration are available and to obtain them.

Since:
1.3
See Also:
Line.getLineInfo(),
Mixer.getSourceLineInfo(),
Mixer.getTargetLineInfo(),
Mixer.getLine(Line.Info),
Mixer.getSourceLineInfo(Line.Info),
Mixer.getTargetLineInfo(Line.Info),
Mixer.isLineSupported(Line.Info),
AudioSystem.getLine(Line.Info),
AudioSystem.getSourceLineInfo(Line.Info),
AudioSystem.getTargetLineInfo(Line.Info),
AudioSystem.isLineSupported(Line.Info)

Constructor Summary
Line.Info(Class<?> lineClass)
Constructs an info object that describes a line of the specified class.
Method Summary
Class<?> | getLineClass() Obtains the class of the line that this Line.Info object describes.
boolean | matches(Line.Info info) Indicates whether the specified info object matches this one.
String | toString() Obtains a textual description of the line info.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Line.Info

public Line.Info(Class<?> lineClass)
Constructs an info object that describes a line of the specified class. This constructor is typically used by an application to describe a desired line.

Parameters:
lineClass - the class of the line that the new Line.Info object describes
Method Detail

getLineClass

public Class<?> getLineClass()
Obtains the class of the line that this Line.Info object describes.

Returns:
the described line's class

matches

public boolean matches(Line.Info info)
Indicates whether the specified info object matches this one. To match, the specified object must be identical to or a special case of this one. The specified info object must be either an instance of the same class as this one, or an instance of a sub-type of this one. In addition, the attributes of the specified object must be compatible with the capabilities of this one. Specifically, the routing configuration for the specified info object must be compatible with that of this one. Subclasses may add other criteria to determine whether the two objects match.

Parameters:
info - the info object which is being compared to this one
Returns:
true if the specified object matches this one, false otherwise

toString

public String toString()
Obtains a textual description of the line info.

Overrides:
toString in class Object
Returns:
a string description
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LineEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class LineEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.sound.sampled.LineEvent
All Implemented Interfaces:
Serializable
public class LineEvent
extends EventObject

The LineEvent class encapsulates information that a line sends its listeners whenever the line opens, closes, starts, or stops. Each of these four state changes is represented by a corresponding type of event. A listener receives the event as a parameter to its update method. By querying the event, the listener can learn the type of event, the line responsible for the event, and how much data the line had processed when the event occurred.

Although this class implements Serializable, attempts to serialize a LineEvent object will fail.

Since:
1.3
See Also:
Line, LineListener.update(javax.sound.sampled.LineEvent)

Nested Class Summary
static class LineEvent.Type
The LineEvent.Type inner class identifies what kind of event occurred on a line.
Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
LineEvent(Line line, LineEvent.Type type, long position)
Constructs a new event of the specified type, originating from the specified line.
Method Summary
long | getFramePosition() Obtains the position in the line's audio data when the event occurred, expressed in sample frames.
Line | getLine() Obtains the audio line that is the source of this event.
LineEvent.Type | getType() Obtains the event's type.
String | toString() Obtains a string representation of the event.
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

LineEvent

public LineEvent(Line line,
                 LineEvent.Type type,
                 long position)
Constructs a new event of the specified type, originating from the specified line.

Parameters:
line - the source of this event
type - the event type (OPEN, CLOSE, START, or STOP)
position - the number of sample frames that the line had already processed when the event occurred, or AudioSystem.NOT_SPECIFIED
Throws:
IllegalArgumentException - if line is null.
Method Detail

getLine

public final Line getLine()
Obtains the audio line that is the source of this event.

Returns:
the line responsible for this event

getType

public final LineEvent.Type getType()
Obtains the event's type.

Returns:
this event's type (LineEvent.Type.OPEN, LineEvent.Type.CLOSE, LineEvent.Type.START, or LineEvent.Type.STOP)

getFramePosition

public final long getFramePosition()
Obtains the position in the line's audio data when the event occurred, expressed in sample frames. For example, if a source line had already played back 14 sample frames at the time it was paused, the pause event would report the line's position as 14. The next frame to be processed would be frame number 14 using zero-based numbering, or 15 using one-based numbering.

Note that this field is relevant only to certain events generated by data lines, such as START and STOP. For events generated by lines that do not count sample frames, and for any other events for which this value is not known, the position value should be AudioSystem.NOT_SPECIFIED.

Returns:
the line's position as a sample frame number

toString

public String toString()
Obtains a string representation of the event. The contents of the string may vary between implementations of Java Sound.

Overrides:
toString in class EventObject
Returns:
a string describing the event.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LineEvent.Type

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class LineEvent.Type

java.lang.Object
    extended by  javax.sound.sampled.LineEvent.Type
Enclosing class:
LineEvent
public static class LineEvent.Type
extends Object

The LineEvent.Type inner class identifies what kind of event occurred on a line. Static instances are provided for the common types (OPEN, CLOSE, START, and STOP).

See Also:
LineEvent.getType()

Field Summary
static LineEvent.Type | CLOSE A type of event that is sent when a line closes, freeing the system resources it had obtained when it was opened.
static LineEvent.Type | OPEN A type of event that is sent when a line opens, reserving system resources for itself.
static LineEvent.Type | START A type of event that is sent when a line begins to engage in active input or output of audio data in response to a start request.
static LineEvent.Type | STOP A type of event that is sent when a line ceases active input or output of audio data in response to a stop request, or because the end of media has been reached.
Constructor Summary
protected LineEvent.Type(String name)
Constructs a new event type.
Method Summary
boolean | equals(Object obj) Indicates whether the specified object is equal to this event type, returning true if the objects are identical.
int | hashCode() Finalizes the hashcode method.
String | toString() Returns the type name as the string representation.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

OPEN

public static final LineEvent.Type OPEN
A type of event that is sent when a line opens, reserving system resources for itself.

See Also:
CLOSE, Line.open()

CLOSE

public static final LineEvent.Type CLOSE
A type of event that is sent when a line closes, freeing the system resources it had obtained when it was opened.

See Also:
OPEN, Line.close()

START

public static final LineEvent.Type START
A type of event that is sent when a line begins to engage in active input or output of audio data in response to a start request.

See Also:
STOP, DataLine.start()

STOP

public static final LineEvent.Type STOP
A type of event that is sent when a line ceases active input or output of audio data in response to a stop request, or because the end of media has been reached.

See Also:
START, DataLine.stop()
Constructor Detail

LineEvent.Type

protected LineEvent.Type(String name)
Constructs a new event type.

Parameters:
name - name of the type
Method Detail

equals

public final boolean equals(Object obj)
Indicates whether the specified object is equal to this event type, returning true if the objects are identical.

Overrides:
equals in class Object
Parameters:
obj - the reference object with which to compare
Returns:
true if this event type is the same as obj; false otherwise
See Also:
Object.hashCode(), Hashtable

hashCode

public final int hashCode()
Finalizes the hashcode method.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Returns the type name as the string representation.

Overrides:
toString in class Object
Returns:
a string representation of the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LineListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Interface LineListener

All Superinterfaces:
EventListener
public interface LineListener
extends EventListener

Instances of classes that implement the LineListener interface can register to receive events when a line's status changes.

Since:
1.3
See Also:
Line, Line.addLineListener(javax.sound.sampled.LineListener), Line.removeLineListener(javax.sound.sampled.LineListener), LineEvent

Method Summary
 void update(LineEvent event)
Informs the listener that a line's state has changed.

Method Detail

update

void update(LineEvent event)
Informs the listener that a line's state has changed. The listener can then invoke LineEvent methods to obtain information about the event.

Parameters:
event - a line event that describes the change
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LineUnavailableException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class LineUnavailableException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.sound.sampled.LineUnavailableException
All Implemented Interfaces:
Serializable
public class LineUnavailableException
extends Exception

A LineUnavailableException is an exception indicating that a line cannot be opened because it is unavailable. This situation arises most commonly when a requested line is already in use by another application.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
LineUnavailableException()
Constructs a LineUnavailableException that has null as its error detail message.
LineUnavailableException(String message)
Constructs a LineUnavailableException that has the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

LineUnavailableException

public LineUnavailableException()
Constructs a LineUnavailableException that has null as its error detail message.

LineUnavailableException

public LineUnavailableException(String message)
Constructs a LineUnavailableException that has the specified detail message.

Parameters:
message - a string containing the error detail message
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Mixer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Interface Mixer

All Superinterfaces:
Line
public interface Mixer
extends Line

A mixer is an audio device with one or more lines. It need not be designed for mixing audio signals. A mixer that actually mixes audio has multiple input (source) lines and at least one output (target) line. The former are often instances of classes that implement SourceDataLine, and the latter, TargetDataLine. Port objects, too, are either source lines or target lines. A mixer can accept prerecorded, loopable sound as input, by having some of its source lines be instances of objects that implement the Clip interface.

Through methods of the Line interface, which Mixer extends, a mixer might provide a set of controls that are global to the mixer. For example, the mixer can have a master gain control. These global controls are distinct from the controls belonging to each of the mixer's individual lines.

Some mixers, especially those with internal digital mixing capabilities, may provide additional capabilities by implementing the DataLine interface.

A mixer can support synchronization of its lines. When one line in a synchronized group is started or stopped, the other lines in the group automatically start or stop simultaneously with the explicitly affected one.

Since:
1.3

Nested Class Summary
static class Mixer.Info
The Mixer.Info class represents information about an audio mixer, including the product's name, version, and vendor, along with a textual description.
Method Summary
Line | getLine(Line.Info info) Obtains a line that is available for use and that matches the description in the specified Line.Info object.
int | getMaxLines(Line.Info info) Obtains the approximate maximum number of lines of the requested type that can be open simultaneously on the mixer.
Mixer.Info | getMixerInfo() Obtains information about this mixer, including the product's name, version, vendor, etc.
Line.Info[] | getSourceLineInfo() Obtains information about the set of source lines supported by this mixer.
Line.Info[] | getSourceLineInfo(Line.Info info) Obtains information about source lines of a particular type supported by the mixer.
Line[] | getSourceLines() Obtains the set of all source lines currently open to this mixer.
Line.Info[] | getTargetLineInfo() Obtains information about the set of target lines supported by this mixer.
Line.Info[] | getTargetLineInfo(Line.Info info) Obtains information about target lines of a particular type supported by the mixer.
Line[] | getTargetLines() Obtains the set of all target lines currently open from this mixer.
boolean | isLineSupported(Line.Info info) Indicates whether the mixer supports a line (or lines) that match the specified Line.Info object.
boolean | isSynchronizationSupported(Line[] lines, boolean maintainSync) Reports whether this mixer supports synchronization of the specified set of lines.
void | synchronize(Line[] lines, boolean maintainSync) Synchronizes two or more lines.
void | unsynchronize(Line[] lines) Releases synchronization for the specified lines.
Methods inherited from interface javax.sound.sampled.Line
addLineListener, close, getControl, getControls, getLineInfo, isControlSupported, isOpen, open, removeLineListener

Method Detail

getMixerInfo

Mixer.Info getMixerInfo()
Obtains information about this mixer, including the product's name, version, vendor, etc.

Returns:
a mixer info object that describes this mixer
See Also:
Mixer.Info

getSourceLineInfo

Line.Info[] getSourceLineInfo()
Obtains information about the set of source lines supported by this mixer. Some source lines may only be available when this mixer is open.

Returns:
array of Line.Info objects representing source lines for this mixer. If no source lines are supported, an array of length 0 is returned.

getTargetLineInfo

Line.Info[] getTargetLineInfo()
Obtains information about the set of target lines supported by this mixer. Some target lines may only be available when this mixer is open.

Returns:
array of Line.Info objects representing target lines for this mixer. If no target lines are supported, an array of length 0 is returned.

getSourceLineInfo

Line.Info[] getSourceLineInfo(Line.Info info)
Obtains information about source lines of a particular type supported by the mixer. Some source lines may only be available when this mixer is open.

Parameters:
info - a Line.Info object describing lines about which information is queried
Returns:
an array of Line.Info objects describing source lines matching the type requested. If no matching source lines are supported, an array of length 0 is returned.

getTargetLineInfo

Line.Info[] getTargetLineInfo(Line.Info info)
Obtains information about target lines of a particular type supported by the mixer. Some target lines may only be available when this mixer is open.

Parameters:
info - a Line.Info object describing lines about which information is queried
Returns:
an array of Line.Info objects describing target lines matching the type requested. If no matching target lines are supported, an array of length 0 is returned.

isLineSupported

boolean isLineSupported(Line.Info info)
Indicates whether the mixer supports a line (or lines) that match the specified Line.Info object. Some lines may only be supported when this mixer is open.

Parameters:
info - describes the line for which support is queried
Returns:
true if at least one matching line is supported, false otherwise

getLine

Line getLine(Line.Info info)
             throws LineUnavailableException
Obtains a line that is available for use and that matches the description in the specified Line.Info object.

If a DataLine is requested, and info is an instance of DataLine.Info specifying at least one fully qualified audio format, the last one will be used as the default format of the returned DataLine.

Parameters:
info - describes the desired line
Throws:
LineUnavailableException - if a matching line is not available due to resource restrictions
IllegalArgumentException - if this mixer does not support any lines matching the description
SecurityException - if a matching line is not available due to security restrictions

getMaxLines

int getMaxLines(Line.Info info)
Obtains the approximate maximum number of lines of the requested type that can be open simultaneously on the mixer. Certain types of mixers do not have a hard bound and may allow opening more lines. Since certain lines are a shared resource, a mixer may not be able to open the maximum number of lines if another process has opened lines of this mixer. The requested type is any line that matches the description in the provided Line.Info object. For example, if the info object represents a speaker port, and the mixer supports exactly one speaker port, this method should return 1. If the info object represents a source data line and the mixer supports the use of 32 source data lines simultaneously, the return value should be 32. If there is no limit, this function returns AudioSystem.NOT_SPECIFIED.

Parameters:
info - a Line.Info that describes the line for which the number of supported instances is queried
Returns:
the maximum number of matching lines supported, or AudioSystem.NOT_SPECIFIED

getSourceLines

Line[] getSourceLines()
Obtains the set of all source lines currently open to this mixer.

Returns:
the source lines currently open to the mixer. If no source lines are currently open to this mixer, an array of length 0 is returned.
Throws:
SecurityException - if the matching lines are not available due to security restrictions

getTargetLines

Line[] getTargetLines()
Obtains the set of all target lines currently open from this mixer.

Returns:
target lines currently open from the mixer. If no target lines are currently open from this mixer, an array of length 0 is returned.
Throws:
SecurityException - if the matching lines are not available due to security restrictions

synchronize

void synchronize(Line[] lines,
                 boolean maintainSync)
Synchronizes two or more lines. Any subsequent command that starts or stops audio playback or capture for one of these lines will exert the same effect on the other lines in the group, so that they start or stop playing or capturing data simultaneously.

Parameters:
lines - the lines that should be synchronized
maintainSync - true if the synchronization must be precisely maintained (i.e., the synchronization must be sample-accurate) at all times during operation of the lines , or false if precise synchronization is required only during start and stop operations
Throws:
IllegalArgumentException - if the lines cannot be synchronized. This may occur if the lines are of different types or have different formats for which this mixer does not support synchronization, or if all lines specified do not belong to this mixer.

unsynchronize

void unsynchronize(Line[] lines)
Releases synchronization for the specified lines. The array must be identical to one for which synchronization has already been established; otherwise an exception may be thrown. However, null may be specified, in which case all currently synchronized lines that belong to this mixer are unsynchronized.

Parameters:
lines - the synchronized lines for which synchronization should be released, or null for all this mixer's synchronized lines
Throws:
IllegalArgumentException - if the lines cannot be unsynchronized. This may occur if the argument specified does not exactly match a set of lines for which synchronization has already been established.

isSynchronizationSupported

boolean isSynchronizationSupported(Line[] lines,
                                   boolean maintainSync)
Reports whether this mixer supports synchronization of the specified set of lines.

Parameters:
lines - the set of lines for which synchronization support is queried
maintainSync - true if the synchronization must be precisely maintained (i.e., the synchronization must be sample-accurate) at all times during operation of the lines , or false if precise synchronization is required only during start and stop operations
Returns:
true if the lines can be synchronized, false otherwise
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Mixer.Info

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class Mixer.Info

java.lang.Object
    extended by  javax.sound.sampled.Mixer.Info
Enclosing interface:
Mixer
public static class Mixer.Info
extends Object

The Mixer.Info class represents information about an audio mixer, including the product's name, version, and vendor, along with a textual description. This information may be retrieved through the getMixerInfo method of the Mixer interface.

Since:
1.3

Constructor Summary
protected Mixer.Info(String name, String vendor, String description, String version)
Constructs a mixer's info object, passing it the given textual information.
Method Summary
boolean | equals(Object obj) Indicates whether two info objects are equal, returning true if they are identical.
String | getDescription() Obtains the description of the mixer.
String | getName() Obtains the name of the mixer.
String | getVendor() Obtains the vendor of the mixer.
String | getVersion() Obtains the version of the mixer.
int | hashCode() Finalizes the hashcode method.
String | toString() Provides a string representation of the mixer info.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Mixer.Info

protected Mixer.Info(String name,
                     String vendor,
                     String description,
                     String version)
Constructs a mixer's info object, passing it the given textual information.

Parameters:
name - the name of the mixer
vendor - the company who manufactures or creates the hardware or software mixer
description - descriptive text about the mixer
version - version information for the mixer
Method Detail

equals

public final boolean equals(Object obj)
Indicates whether two info objects are equal, returning true if they are identical.

Overrides:
equals in class Object
Parameters:
obj - the reference object with which to compare this info object
Returns:
true if this info object is the same as the obj argument; false otherwise
See Also:
Object.hashCode(), Hashtable

hashCode

public final int hashCode()
Finalizes the hashcode method.

Overrides:
hashCode in class Object
Returns:
the hashcode for this object
See Also:
Object.equals(java.lang.Object), Hashtable

getName

public final String getName()
Obtains the name of the mixer.

Returns:
a string that names the mixer

getVendor

public final String getVendor()
Obtains the vendor of the mixer.

Returns:
a string that names the mixer's vendor

getDescription

public final String getDescription()
Obtains the description of the mixer.

Returns:
a textual description of the mixer

getVersion

public final String getVersion()
Obtains the version of the mixer.

Returns:
textual version information for the mixer

toString

public final String toString()
Provides a string representation of the mixer info.

Overrides:
toString in class Object
Returns:
a string describing the info object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Port

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Interface Port

All Superinterfaces:
Line
public interface Port
extends Line

Ports are simple lines for input or output of audio to or from audio devices. Common examples of ports that act as source lines (mixer inputs) include the microphone, line input, and CD-ROM drive. Ports that act as target lines (mixer outputs) include the speaker, headphone, and line output. You can access port using a Port.Info object.

Since:
1.3

Nested Class Summary
static class Port.Info
The Port.Info class extends Line.Info with additional information specific to ports, including the port's name and whether it is a source or a target for its mixer.
Method Summary
Methods inherited from interface javax.sound.sampled.Line
addLineListener, close, getControl, getControls, getLineInfo, isControlSupported, isOpen, open, removeLineListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Port.Info

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class Port.Info

java.lang.Object
    extended by  javax.sound.sampled.Line.Info
        extended by  javax.sound.sampled.Port.Info
Enclosing interface:
Port
public static class Port.Info
extends Line.Info

The Port.Info class extends Line.Info with additional information specific to ports, including the port's name and whether it is a source or a target for its mixer. By definition, a port acts as either a source or a target to its mixer, but not both. (Audio input ports are sources; audio output ports are targets.)

To learn what ports are available, you can retrieve port info objects through the getSourceLineInfo and getTargetLineInfo methods of the Mixer interface. Instances of the Port.Info class may also be constructed and used to obtain lines matching the parameters specified in the Port.Info object.

Since:
1.3

Field Summary
static Port.Info | COMPACT_DISC A type of port that gets audio from a CD-ROM drive.
static Port.Info | HEADPHONE A type of port that sends audio to a headphone jack.
static Port.Info | LINE_IN A type of port that gets audio from a line-level audio input jack.
static Port.Info | LINE_OUT A type of port that sends audio to a line-level audio output jack.
static Port.Info | MICROPHONE A type of port that gets audio from a built-in microphone or a microphone jack.
static Port.Info | SPEAKER A type of port that sends audio to a built-in speaker or a speaker jack.
Constructor Summary
Port.Info(Class<?> lineClass, String name, boolean isSource)
Constructs a port's info object from the information given.
Method Summary
boolean | equals(Object obj) Finalizes the equals method
String | getName() Obtains the name of the port.
int | hashCode() Finalizes the hashCode method
boolean | isSource() Indicates whether the port is a source or a target for its mixer.
boolean | matches(Line.Info info) Indicates whether this info object specified matches this one.
String | toString() Provides a String representation of the port.
Methods inherited from class javax.sound.sampled.Line.Info
getLineClass
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

MICROPHONE

public static final Port.Info MICROPHONE
A type of port that gets audio from a built-in microphone or a microphone jack.

LINE_IN

public static final Port.Info LINE_IN
A type of port that gets audio from a line-level audio input jack.

COMPACT_DISC

public static final Port.Info COMPACT_DISC
A type of port that gets audio from a CD-ROM drive.

SPEAKER

public static final Port.Info SPEAKER
A type of port that sends audio to a built-in speaker or a speaker jack.

HEADPHONE

public static final Port.Info HEADPHONE
A type of port that sends audio to a headphone jack.

LINE_OUT

public static final Port.Info LINE_OUT
A type of port that sends audio to a line-level audio output jack.

Constructor Detail

Port.Info

public Port.Info(Class<?> lineClass,
                 String name,
                 boolean isSource)
Constructs a port's info object from the information given. This constructor is typically used by an implementation of Java Sound to describe a supported line.

Parameters:
lineClass - the class of the port described by the info object.
name - the string that names the port
isSource - true if the port is a source port (such as a microphone), false if the port is a target port (such as a speaker).
Method Detail

getName

public String getName()
Obtains the name of the port.

Returns:
the string that names the port

isSource

public boolean isSource()
Indicates whether the port is a source or a target for its mixer.

Returns:
true if the port is a source port (such as a microphone), false if the port is a target port (such as a speaker).

matches

public boolean matches(Line.Info info)
Indicates whether this info object specified matches this one. To match, the match requirements of the superclass must be met and the types must be equal.

Overrides:
matches in class Line.Info
Parameters:
info - the info object for which the match is queried
Returns:
true if the specified object matches this one, false otherwise

equals

public final boolean equals(Object obj)
Finalizes the equals method

Overrides:
equals in class Object
Parameters:
obj - the reference object with which to compare.
Returns:
true if this object is the same as the obj argument; false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

public final int hashCode()
Finalizes the hashCode method

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public final String toString()
Provides a String representation of the port.

Overrides:
toString in class Line.Info
Returns:
a string that describes the port
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ReverbType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class ReverbType

java.lang.Object
    extended by  javax.sound.sampled.ReverbType

public class ReverbType
extends Object

The ReverbType class provides methods for accessing various reverberation settings to be applied to an audio signal.

Reverberation simulates the reflection of sound off of the walls, ceiling, and floor of a room. Depending on the size of the room, and how absorbent or reflective the materials in the room's surfaces are, the sound might bounce around for a long time before dying away.

The reverberation parameters provided by ReverbType consist of the delay time and intensity of early reflections, the delay time and intensity of late reflections, and an overall decay time. Early reflections are the initial individual low-order reflections of the direct signal off the surfaces in the room. The late Relections are the dense, high-order reflections that characterize the room's reverberation. The delay times for the start of these two reflection types give the listener a sense of the overall size and complexity of the room's shape and contents. The larger the room, the longer the reflection delay times. The early and late reflections' intensities define the gain (in decibels) of the reflected signals as compared to the direct signal. These intensities give the listener an impression of the absorptive nature of the surfaces and objects in the room. The decay time defines how long the reverberation takes to exponentially decay until it is no longer perceptible ("effective zero"). The larger and less absorbent the surfaces, the longer the decay time.

The set of parameters defined here may not include all aspects of reverberation as specified by some systems. For example, the Midi Manufacturer's Association (MMA) has an Interactive Audio Special Interest Group (IASIG), which has a 3-D Working Group that has defined a Level 2 Spec (I3DL2). I3DL2 supports filtering of reverberation and control of reverb density. These properties are not included in the JavaSound 1.0 definition of a reverb control. In such a case, the implementing system should either extend the defined reverb control to include additional parameters, or else interpret the system's additional capabilities in a way that fits the model described here.

If implementing JavaSound on a I3DL2-compliant device:

  • Filtering is disabled (high-frequency attenuations are set to 0.0 dB)
  • Density parameters are set to midway between minimum and maximum

The following table shows what parameter values an implementation might use for a representative set of reverberation settings.

Reverberation Types and Parameters

Type | Decay Time (ms) | Late Intensity (dB) | Late Delay (ms) | Early Intensity (dB) | Early Delay(ms)
Cavern | 2250 | -2.0 | 41.3 | -1.4 | 10.3
Dungeon | 1600 | -1.0 | 10.3 | -0.7 | 2.6
Garage | 900 | -6.0 | 14.7 | -4.0 | 3.9
Acoustic Lab | 280 | -3.0 | 8.0 | -2.0 | 2.0
Closet | 150 | -10.0 | 2.5 | -7.0 | 0.6

Since:
1.3

Constructor Summary
protected ReverbType(String name, int earlyReflectionDelay, float earlyReflectionIntensity, int lateReflectionDelay, float lateReflectionIntensity, int decayTime)
Constructs a new reverb type that has the specified reverberation parameter values.
Method Summary
boolean | equals(Object obj) Indicates whether the specified object is equal to this reverb type, returning true if the objects are identical.
int | getDecayTime() Obtains the decay time, which is the amount of time over which the late reflections attenuate to effective zero.
int | getEarlyReflectionDelay() Returns the early reflection delay time in microseconds.
float | getEarlyReflectionIntensity() Returns the early reflection intensity in decibels.
int | getLateReflectionDelay() Returns the late reflection delay time in microseconds.
float | getLateReflectionIntensity() Returns the late reflection intensity in decibels.
String | getName() Obtains the name of this reverb type.
int | hashCode() Finalizes the hashcode method.
String | toString() Provides a String representation of the reverb type, including its name and its parameter settings.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ReverbType

protected ReverbType(String name,
                     int earlyReflectionDelay,
                     float earlyReflectionIntensity,
                     int lateReflectionDelay,
                     float lateReflectionIntensity,
                     int decayTime)
Constructs a new reverb type that has the specified reverberation parameter values.

Parameters:
name - the name of the new reverb type, or a zero-length String
earlyReflectionDelay - the new type's early reflection delay time in microseconds
earlyReflectionIntensity - the new type's early reflection intensity in dB
lateReflectionDelay - the new type's late reflection delay time in microseconds
lateReflectionIntensity - the new type's late reflection intensity in dB
decayTime - the new type's decay time in microseconds
Method Detail

getName

public String getName()
Obtains the name of this reverb type.

Returns:
the name of this reverb type
Since:
1.5

getEarlyReflectionDelay

public final int getEarlyReflectionDelay()
Returns the early reflection delay time in microseconds. This is the amount of time between when the direct signal is heard and when the first early reflections are heard.

Returns:
early reflection delay time for this reverb type, in microseconds

getEarlyReflectionIntensity

public final float getEarlyReflectionIntensity()
Returns the early reflection intensity in decibels. This is the amplitude attenuation of the first early reflections relative to the direct signal.

Returns:
early reflection intensity for this reverb type, in dB

getLateReflectionDelay

public final int getLateReflectionDelay()
Returns the late reflection delay time in microseconds. This is the amount of time between when the first early reflections are heard and when the first late reflections are heard.

Returns:
late reflection delay time for this reverb type, in microseconds

getLateReflectionIntensity

public final float getLateReflectionIntensity()
Returns the late reflection intensity in decibels. This is the amplitude attenuation of the first late reflections relative to the direct signal.

Returns:
late reflection intensity for this reverb type, in dB

getDecayTime

public final int getDecayTime()
Obtains the decay time, which is the amount of time over which the late reflections attenuate to effective zero. The effective zero value is implementation-dependent.

Returns:
the decay time of the late reflections, in microseconds

equals

public final boolean equals(Object obj)
Indicates whether the specified object is equal to this reverb type, returning true if the objects are identical.

Overrides:
equals in class Object
Parameters:
obj - the reference object with which to compare
Returns:
true if this reverb type is the same as obj; false otherwise
See Also:
Object.hashCode(), Hashtable

hashCode

public final int hashCode()
Finalizes the hashcode method.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public final String toString()
Provides a String representation of the reverb type, including its name and its parameter settings. The exact contents of the string may vary between implementations of Java Sound.

Overrides:
toString in class Object
Returns:
reverberation type name and description
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SourceDataLine

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Interface SourceDataLine

All Superinterfaces:
DataLine, Line
public interface SourceDataLine
extends DataLine

A source data line is a data line to which data may be written. It acts as a source to its mixer. An application writes audio bytes to a source data line, which handles the buffering of the bytes and delivers them to the mixer. The mixer may mix the samples with those from other sources and then deliver the mix to a target such as an output port (which may represent an audio output device on a sound card).

Note that the naming convention for this interface reflects the relationship between the line and its mixer. From the perspective of an application, a source data line may act as a target for audio data.

A source data line can be obtained from a mixer by invoking the getLine method of Mixer with an appropriate DataLine.Info object.

The SourceDataLine interface provides a method for writing audio data to the data line's buffer. Applications that play or mix audio should write data to the source data line quickly enough to keep the buffer from underflowing (emptying), which could cause discontinuities in the audio that are perceived as clicks. Applications can use the available method defined in the DataLine interface to determine the amount of data currently queued in the data line's buffer. The amount of data which can be written to the buffer without blocking is the difference between the buffer size and the amount of queued data. If the delivery of audio output stops due to underflow, a STOP event is generated. A START event is generated when the audio output resumes.

Since:
1.3
See Also:
Mixer, DataLine, TargetDataLine

Nested Class Summary
Nested classes/interfaces inherited from interface javax.sound.sampled.DataLine
DataLine.Info
Method Summary
void | open(AudioFormat format) Opens the line with the specified format, causing the line to acquire any required system resources and become operational.
void | open(AudioFormat format, int bufferSize) Opens the line with the specified format and suggested buffer size, causing the line to acquire any required system resources and become operational.
int | write(byte[] b, int off, int len) Writes audio data to the mixer via this source data line.
Methods inherited from interface javax.sound.sampled.DataLine
available, drain, flush, getBufferSize, getFormat, getFramePosition, getLevel, getLongFramePosition, getMicrosecondPosition, isActive, isRunning, start, stop
Methods inherited from interface javax.sound.sampled.Line
addLineListener, close, getControl, getControls, getLineInfo, isControlSupported, isOpen, open, removeLineListener

Method Detail

open

void open(AudioFormat format,
          int bufferSize)
          throws LineUnavailableException
Opens the line with the specified format and suggested buffer size, causing the line to acquire any required system resources and become operational.

The buffer size is specified in bytes, but must represent an integral number of sample frames. Invoking this method with a requested buffer size that does not meet this requirement may result in an IllegalArgumentException. The actual buffer size for the open line may differ from the requested buffer size. The value actually set may be queried by subsequently calling DataLine.getBufferSize().

If this operation succeeds, the line is marked as open, and an OPEN event is dispatched to the line's listeners.

Invoking this method on a line which is already open is illegal and may result in an IllegalStateException.

Note that some lines, once closed, cannot be reopened. Attempts to reopen such a line will always result in a LineUnavailableException.

Parameters:
format - the desired audio format
bufferSize - the desired buffer size
Throws:
LineUnavailableException - if the line cannot be opened due to resource restrictions
IllegalArgumentException - if the buffer size does not represent an integral number of sample frames, or if format is not fully specified or invalid
IllegalStateException - if the line is already open
SecurityException - if the line cannot be opened due to security restrictions
See Also:
open(AudioFormat),
Line.open(),
Line.close(),
Line.isOpen(),
LineEvent

open

void open(AudioFormat format)
          throws LineUnavailableException
Opens the line with the specified format, causing the line to acquire any required system resources and become operational.

The implementation chooses a buffer size, which is measured in bytes but which encompasses an integral number of sample frames. The buffer size that the system has chosen may be queried by subsequently calling DataLine.getBufferSize().

If this operation succeeds, the line is marked as open, and an OPEN event is dispatched to the line's listeners.

Invoking this method on a line which is already open is illegal and may result in an IllegalStateException.

Note that some lines, once closed, cannot be reopened. Attempts to reopen such a line will always result in a LineUnavailableException.

Parameters:
format - the desired audio format
Throws:
LineUnavailableException - if the line cannot be opened due to resource restrictions
IllegalArgumentException - if format is not fully specified or invalid
IllegalStateException - if the line is already open
SecurityException - if the line cannot be opened due to security restrictions
See Also:
open(AudioFormat, int),
Line.open(),
Line.close(),
Line.isOpen(),
LineEvent

write

int write(byte[] b,
          int off,
          int len)
Writes audio data to the mixer via this source data line. The requested number of bytes of data are read from the specified array, starting at the given offset into the array, and written to the data line's buffer. If the caller attempts to write more data than can currently be written (see available), this method blocks until the requested amount of data has been written. This applies even if the requested amount of data to write is greater than the data line's buffer size. However, if the data line is closed, stopped, or flushed before the requested amount has been written, the method no longer blocks, but returns the number of bytes written thus far.

The number of bytes that can be written without blocking can be ascertained using the available method of the DataLine interface. (While it is guaranteed that this number of bytes can be written without blocking, there is no guarantee that attempts to write additional data will block.)

The number of bytes to write must represent an integral number of sample frames, such that:

[ bytes written ] % [frame size in bytes ] == 0

The return value will always meet this requirement. A request to write a number of bytes representing a non-integral number of sample frames cannot be fulfilled and may result in an IllegalArgumentException.

Parameters:
b - a byte array containing data to be written to the data line
len - the length, in bytes, of the valid data in the array (in other words, the requested amount of data to write, in bytes)
off - the offset from the beginning of the array, in bytes
Returns:
the number of bytes actually written
Throws:
IllegalArgumentException - if the requested number of bytes does not represent an integral number of sample frames, or if len is negative
ArrayIndexOutOfBoundsException - if off is negative, or off+len is greater than the length of the array b.
See Also:
TargetDataLine.read(byte[], int, int), DataLine.available()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


spi

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.sound.sampled.spi

Supplies abstract classes for service providers to subclass when offering new audio devices, sound file readers and writers, or audio format converters.

See:
Description

Class Summary
AudioFileReader | Provider for audio file reading services.
AudioFileWriter | Provider for audio file writing services.
FormatConversionProvider | A format conversion provider provides format conversion services from one or more input formats to one or more output formats.
MixerProvider | A provider or factory for a particular mixer type.

Package javax.sound.sampled.spi Description

Supplies abstract classes for service providers to subclass when offering new audio devices, sound file readers and writers, or audio format converters.

Related Documentation

For overviews, tutorials, examples, and guides, please see:
  • Sound

Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.sound.sampled.spi Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.sound.sampled.spi

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.sound.sampled.spi.AudioFileReader
    • javax.sound.sampled.spi.AudioFileWriter
    • javax.sound.sampled.spi.FormatConversionProvider
    • javax.sound.sampled.spi.MixerProvider
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.sound.sampled.spi

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.sound.sampled.spi

No usage of javax.sound.sampled.spi

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AudioFileReader

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled.spi
Class AudioFileReader

java.lang.Object
    extended by  javax.sound.sampled.spi.AudioFileReader

public abstract class AudioFileReader
extends Object

Provider for audio file reading services. Classes providing concrete implementations can parse the format information from one or more types of audio file, and can produce audio input streams from files of these types.

Since:
1.3

Constructor Summary
AudioFileReader()
Method Summary
abstract AudioFileFormat | getAudioFileFormat(File file) Obtains the audio file format of the File provided.
abstract AudioFileFormat | getAudioFileFormat(InputStream stream) Obtains the audio file format of the input stream provided.
abstract AudioFileFormat | getAudioFileFormat(URL url) Obtains the audio file format of the URL provided.
abstract AudioInputStream | getAudioInputStream(File file) Obtains an audio input stream from the File provided.
abstract AudioInputStream | getAudioInputStream(InputStream stream) Obtains an audio input stream from the input stream provided.
abstract AudioInputStream | getAudioInputStream(URL url) Obtains an audio input stream from the URL provided.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AudioFileReader

public AudioFileReader()
Method Detail

getAudioFileFormat

public abstract AudioFileFormat getAudioFileFormat(InputStream stream)
                                            throws UnsupportedAudioFileException,
                                                   IOException
Obtains the audio file format of the input stream provided. The stream must point to valid audio file data. In general, audio file readers may need to read some data from the stream before determining whether they support it. These parsers must be able to mark the stream, read enough data to determine whether they support the stream, and, if not, reset the stream's read pointer to its original position. If the input stream does not support this, this method may fail with an IOException.

Parameters:
stream - the input stream from which file format information should be extracted
Returns:
an AudioFileFormat object describing the audio file format
Throws:
UnsupportedAudioFileException - if the stream does not point to valid audio file data recognized by the system
IOException - if an I/O exception occurs
See Also:
InputStream.markSupported(), InputStream.mark(int)

getAudioFileFormat

public abstract AudioFileFormat getAudioFileFormat(URL url)
                                            throws UnsupportedAudioFileException,
                                                   IOException
Obtains the audio file format of the URL provided. The URL must point to valid audio file data.

Parameters:
url - the URL from which file format information should be extracted
Returns:
an AudioFileFormat object describing the audio file format
Throws:
UnsupportedAudioFileException - if the URL does not point to valid audio file data recognized by the system
IOException - if an I/O exception occurs

getAudioFileFormat

public abstract AudioFileFormat getAudioFileFormat(File file)
                                            throws UnsupportedAudioFileException,
                                                   IOException
Obtains the audio file format of the File provided. The File must point to valid audio file data.

Parameters:
file - the File from which file format information should be extracted
Returns:
an AudioFileFormat object describing the audio file format
Throws:
UnsupportedAudioFileException - if the File does not point to valid audio file data recognized by the system
IOException - if an I/O exception occurs

getAudioInputStream

public abstract AudioInputStream getAudioInputStream(InputStream stream)
                                              throws UnsupportedAudioFileException,
                                                     IOException
Obtains an audio input stream from the input stream provided. The stream must point to valid audio file data. In general, audio file readers may need to read some data from the stream before determining whether they support it. These parsers must be able to mark the stream, read enough data to determine whether they support the stream, and, if not, reset the stream's read pointer to its original position. If the input stream does not support this, this method may fail with an IOException.

Parameters:
stream - the input stream from which the AudioInputStream should be constructed
Returns:
an AudioInputStream object based on the audio file data contained in the input stream.
Throws:
UnsupportedAudioFileException - if the stream does not point to valid audio file data recognized by the system
IOException - if an I/O exception occurs
See Also:
InputStream.markSupported(), InputStream.mark(int)

getAudioInputStream

public abstract AudioInputStream getAudioInputStream(URL url)
                                              throws UnsupportedAudioFileException,
                                                     IOException
Obtains an audio input stream from the URL provided. The URL must point to valid audio file data.

Parameters:
url - the URL for which the AudioInputStream should be constructed
Returns:
an AudioInputStream object based on the audio file data pointed to by the URL
Throws:
UnsupportedAudioFileException - if the URL does not point to valid audio file data recognized by the system
IOException - if an I/O exception occurs

getAudioInputStream

public abstract AudioInputStream getAudioInputStream(File file)
                                              throws UnsupportedAudioFileException,
                                                     IOException
Obtains an audio input stream from the File provided. The File must point to valid audio file data.

Parameters:
file - the File for which the AudioInputStream should be constructed
Returns:
an AudioInputStream object based on the audio file data pointed to by the File
Throws:
UnsupportedAudioFileException - if the File does not point to valid audio file data recognized by the system
IOException - if an I/O exception occurs
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AudioFileWriter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled.spi
Class AudioFileWriter

java.lang.Object
    extended by  javax.sound.sampled.spi.AudioFileWriter

public abstract class AudioFileWriter
extends Object

Provider for audio file writing services. Classes providing concrete implementations can write one or more types of audio file from an audio stream.

Since:
1.3

Constructor Summary
AudioFileWriter()
Method Summary
abstract AudioFileFormat.Type[] | getAudioFileTypes() Obtains the file types for which file writing support is provided by this audio file writer.
abstract AudioFileFormat.Type[] | getAudioFileTypes(AudioInputStream stream) Obtains the file types that this audio file writer can write from the audio input stream specified.
boolean | isFileTypeSupported(AudioFileFormat.Type fileType) Indicates whether file writing support for the specified file type is provided by this audio file writer.
boolean | isFileTypeSupported(AudioFileFormat.Type fileType, AudioInputStream stream) Indicates whether an audio file of the type specified can be written from the audio input stream indicated.
abstract int | write(AudioInputStream stream, AudioFileFormat.Type fileType, File out) Writes a stream of bytes representing an audio file of the file format indicated to the external file provided.
abstract int | write(AudioInputStream stream, AudioFileFormat.Type fileType, OutputStream out) Writes a stream of bytes representing an audio file of the file type indicated to the output stream provided.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AudioFileWriter

public AudioFileWriter()
Method Detail

getAudioFileTypes

public abstract AudioFileFormat.Type[] getAudioFileTypes()
Obtains the file types for which file writing support is provided by this audio file writer.

Returns:
array of file types. If no file types are supported, an array of length 0 is returned.

isFileTypeSupported

public boolean isFileTypeSupported(AudioFileFormat.Type fileType)
Indicates whether file writing support for the specified file type is provided by this audio file writer.

Parameters:
fileType - the file type for which write capabilities are queried
Returns:
true if the file type is supported, otherwise false

getAudioFileTypes

public abstract AudioFileFormat.Type[] getAudioFileTypes(AudioInputStream stream)
Obtains the file types that this audio file writer can write from the audio input stream specified.

Parameters:
stream - the audio input stream for which audio file type support is queried
Returns:
array of file types. If no file types are supported, an array of length 0 is returned.

isFileTypeSupported

public boolean isFileTypeSupported(AudioFileFormat.Type fileType,
                                   AudioInputStream stream)
Indicates whether an audio file of the type specified can be written from the audio input stream indicated.

Parameters:
fileType - file type for which write capabilities are queried
stream - for which file writing support is queried
Returns:
true if the file type is supported for this audio input stream, otherwise false

write

public abstract int write(AudioInputStream stream,
                          AudioFileFormat.Type fileType,
                          OutputStream out)
                   throws IOException
Writes a stream of bytes representing an audio file of the file type indicated to the output stream provided. Some file types require that the length be written into the file header, and cannot be written from start to finish unless the length is known in advance. An attempt to write such a file type will fail with an IOException if the length in the audio file format is AudioSystem.NOT_SPECIFIED.

Parameters:
stream - the audio input stream containing audio data to be written to the output stream
fileType - file type to be written to the output stream
out - stream to which the file data should be written
Returns:
the number of bytes written to the output stream
Throws:
IOException - if an I/O exception occurs
IllegalArgumentException - if the file type is not supported by the system
See Also:
isFileTypeSupported(AudioFileFormat.Type, AudioInputStream), getAudioFileTypes()

write

public abstract int write(AudioInputStream stream,
                          AudioFileFormat.Type fileType,
                          File out)
                   throws IOException
Writes a stream of bytes representing an audio file of the file format indicated to the external file provided.

Parameters:
stream - the audio input stream containing audio data to be written to the file
fileType - file type to be written to the file
out - external file to which the file data should be written
Returns:
the number of bytes written to the file
Throws:
IOException - if an I/O exception occurs
IllegalArgumentException - if the file format is not supported by the system
See Also:
isFileTypeSupported(javax.sound.sampled.AudioFileFormat.Type), getAudioFileTypes()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.sound.sampled.spi.AudioFileReader

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.spi.AudioFileReader

No usage of javax.sound.sampled.spi.AudioFileReader

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.spi.AudioFileWriter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.spi.AudioFileWriter

No usage of javax.sound.sampled.spi.AudioFileWriter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.spi.FormatConversionProvider

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.spi.FormatConversionProvider

No usage of javax.sound.sampled.spi.FormatConversionProvider

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sound.sampled.spi.MixerProvider

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sound.sampled.spi.MixerProvider

No usage of javax.sound.sampled.spi.MixerProvider

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


FormatConversionProvider

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled.spi
Class FormatConversionProvider

java.lang.Object
    extended by  javax.sound.sampled.spi.FormatConversionProvider

public abstract class FormatConversionProvider
extends Object

A format conversion provider provides format conversion services from one or more input formats to one or more output formats. Converters include codecs, which encode and/or decode audio data, as well as transcoders, etc. Format converters provide methods for determining what conversions are supported and for obtaining an audio stream from which converted data can be read.

The source format represents the format of the incoming audio data, which will be converted.

The target format represents the format of the processed, converted audio data. This is the format of the data that can be read from the stream returned by one of the getAudioInputStream methods.

Since:
1.3

Constructor Summary
FormatConversionProvider()
Method Summary
abstract AudioInputStream | getAudioInputStream(AudioFormat.Encoding targetEncoding, AudioInputStream sourceStream) Obtains an audio input stream with the specified encoding from the given audio input stream.
abstract AudioInputStream | getAudioInputStream(AudioFormat targetFormat, AudioInputStream sourceStream) Obtains an audio input stream with the specified format from the given audio input stream.
abstract AudioFormat.Encoding[] | getSourceEncodings() Obtains the set of source format encodings from which format conversion services are provided by this provider.
abstract AudioFormat.Encoding[] | getTargetEncodings() Obtains the set of target format encodings to which format conversion services are provided by this provider.
abstract AudioFormat.Encoding[] | getTargetEncodings(AudioFormat sourceFormat) Obtains the set of target format encodings supported by the format converter given a particular source format.
abstract AudioFormat[] | getTargetFormats(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) Obtains the set of target formats with the encoding specified supported by the format converter If no target formats with the specified encoding are supported for this source format, an array of length 0 is returned.
boolean | isConversionSupported(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat) Indicates whether the format converter supports conversion to a particular encoding from a particular format.
boolean | isConversionSupported(AudioFormat targetFormat, AudioFormat sourceFormat) Indicates whether the format converter supports conversion to one particular format from another.
boolean | isSourceEncodingSupported(AudioFormat.Encoding sourceEncoding) Indicates whether the format converter supports conversion from the specified source format encoding.
boolean | isTargetEncodingSupported(AudioFormat.Encoding targetEncoding) Indicates whether the format converter supports conversion to the specified target format encoding.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FormatConversionProvider

public FormatConversionProvider()
Method Detail

getSourceEncodings

public abstract AudioFormat.Encoding[] getSourceEncodings()
Obtains the set of source format encodings from which format conversion services are provided by this provider.

Returns:
array of source format encodings. The array will always have a length of at least 1.

getTargetEncodings

public abstract AudioFormat.Encoding[] getTargetEncodings()
Obtains the set of target format encodings to which format conversion services are provided by this provider.

Returns:
array of target format encodings. The array will always have a length of at least 1.

isSourceEncodingSupported

public boolean isSourceEncodingSupported(AudioFormat.Encoding sourceEncoding)
Indicates whether the format converter supports conversion from the specified source format encoding.

Parameters:
sourceEncoding - the source format encoding for which support is queried
Returns:
true if the encoding is supported, otherwise false

isTargetEncodingSupported

public boolean isTargetEncodingSupported(AudioFormat.Encoding targetEncoding)
Indicates whether the format converter supports conversion to the specified target format encoding.

Parameters:
targetEncoding - the target format encoding for which support is queried
Returns:
true if the encoding is supported, otherwise false

getTargetEncodings

public abstract AudioFormat.Encoding[] getTargetEncodings(AudioFormat sourceFormat)
Obtains the set of target format encodings supported by the format converter given a particular source format. If no target format encodings are supported for this source format, an array of length 0 is returned.

Returns:
array of supported target format encodings.

isConversionSupported

public boolean isConversionSupported(AudioFormat.Encoding targetEncoding,
                                     AudioFormat sourceFormat)
Indicates whether the format converter supports conversion to a particular encoding from a particular format.

Parameters:
targetEncoding - desired encoding of the outgoing data
sourceFormat - format of the incoming data
Returns:
true if the conversion is supported, otherwise false

getTargetFormats

public abstract AudioFormat[] getTargetFormats(AudioFormat.Encoding targetEncoding,
                                               AudioFormat sourceFormat)
Obtains the set of target formats with the encoding specified supported by the format converter If no target formats with the specified encoding are supported for this source format, an array of length 0 is returned.

Returns:
array of supported target formats.

isConversionSupported

public boolean isConversionSupported(AudioFormat targetFormat,
                                     AudioFormat sourceFormat)
Indicates whether the format converter supports conversion to one particular format from another.

Parameters:
targetFormat - desired format of outgoing data
sourceFormat - format of the incoming data
Returns:
true if the conversion is supported, otherwise false

getAudioInputStream

public abstract AudioInputStream getAudioInputStream(AudioFormat.Encoding targetEncoding,
                                                     AudioInputStream sourceStream)
Obtains an audio input stream with the specified encoding from the given audio input stream.

Parameters:
targetEncoding - desired encoding of the stream after processing
sourceStream - stream from which data to be processed should be read
Returns:
stream from which processed data with the specified target encoding may be read
Throws:
IllegalArgumentException - if the format combination supplied is not supported.

getAudioInputStream

public abstract AudioInputStream getAudioInputStream(AudioFormat targetFormat,
                                                     AudioInputStream sourceStream)
Obtains an audio input stream with the specified format from the given audio input stream.

Parameters:
targetFormat - desired data format of the stream after processing
sourceStream - stream from which data to be processed should be read
Returns:
stream from which processed data with the specified format may be read
Throws:
IllegalArgumentException - if the format combination supplied is not supported.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MixerProvider

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled.spi
Class MixerProvider

java.lang.Object
    extended by  javax.sound.sampled.spi.MixerProvider

public abstract class MixerProvider
extends Object

A provider or factory for a particular mixer type. This mechanism allows the implementation to determine how resources are managed in creation / management of a mixer.

Since:
1.3

Constructor Summary
MixerProvider()
Method Summary
abstract Mixer | getMixer(Mixer.Info info) Obtains an instance of the mixer represented by the info object.
abstract Mixer.Info[] | getMixerInfo() Obtains the set of info objects representing the mixer or mixers provided by this MixerProvider.
boolean | isMixerSupported(Mixer.Info info) Indicates whether the mixer provider supports the mixer represented by the specified mixer info object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MixerProvider

public MixerProvider()
Method Detail

isMixerSupported

public boolean isMixerSupported(Mixer.Info info)
Indicates whether the mixer provider supports the mixer represented by the specified mixer info object.

Parameters:
info - an info object that describes the mixer for which support is queried
Returns:
true if the specified mixer is supported, otherwise false

getMixerInfo

public abstract Mixer.Info[] getMixerInfo()
Obtains the set of info objects representing the mixer or mixers provided by this MixerProvider.

Returns:
set of mixer info objects

getMixer

public abstract Mixer getMixer(Mixer.Info info)
Obtains an instance of the mixer represented by the info object.

Parameters:
info - an info object that describes the desired mixer
Returns:
mixer instance
Throws:
IllegalArgumentException - if the info object specified does not match the info object for a mixer supported by this MixerProvider.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


TargetDataLine

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Interface TargetDataLine

All Superinterfaces:
DataLine, Line
public interface TargetDataLine
extends DataLine

A target data line is a type of DataLine from which audio data can be read. The most common example is a data line that gets its data from an audio capture device. (The device is implemented as a mixer that writes to the target data line.)

Note that the naming convention for this interface reflects the relationship between the line and its mixer. From the perspective of an application, a target data line may act as a source for audio data.

The target data line can be obtained from a mixer by invoking the getLine method of Mixer with an appropriate DataLine.Info object.

The TargetDataLine interface provides a method for reading the captured data from the target data line's buffer.Applications that record audio should read data from the target data line quickly enough to keep the buffer from overflowing, which could cause discontinuities in the captured data that are perceived as clicks. Applications can use the available method defined in the DataLine interface to determine the amount of data currently queued in the data line's buffer. If the buffer does overflow, the oldest queued data is discarded and replaced by new data.

Since:
1.3
See Also:
Mixer, DataLine, SourceDataLine

Nested Class Summary
Nested classes/interfaces inherited from interface javax.sound.sampled.DataLine
DataLine.Info
Method Summary
void | open(AudioFormat format) Opens the line with the specified format, causing the line to acquire any required system resources and become operational.
void | open(AudioFormat format, int bufferSize) Opens the line with the specified format and requested buffer size, causing the line to acquire any required system resources and become operational.
int | read(byte[] b, int off, int len) Reads audio data from the data line's input buffer.
Methods inherited from interface javax.sound.sampled.DataLine
available, drain, flush, getBufferSize, getFormat, getFramePosition, getLevel, getLongFramePosition, getMicrosecondPosition, isActive, isRunning, start, stop
Methods inherited from interface javax.sound.sampled.Line
addLineListener, close, getControl, getControls, getLineInfo, isControlSupported, isOpen, open, removeLineListener

Method Detail

open

void open(AudioFormat format,
          int bufferSize)
          throws LineUnavailableException
Opens the line with the specified format and requested buffer size, causing the line to acquire any required system resources and become operational.

The buffer size is specified in bytes, but must represent an integral number of sample frames. Invoking this method with a requested buffer size that does not meet this requirement may result in an IllegalArgumentException. The actual buffer size for the open line may differ from the requested buffer size. The value actually set may be queried by subsequently calling DataLine.getBufferSize()

If this operation succeeds, the line is marked as open, and an OPEN event is dispatched to the line's listeners.

Invoking this method on a line that is already open is illegal and may result in an IllegalStateException.

Some lines, once closed, cannot be reopened. Attempts to reopen such a line will always result in a LineUnavailableException.

Parameters:
format - the desired audio format
bufferSize - the desired buffer size, in bytes.
Throws:
LineUnavailableException - if the line cannot be opened due to resource restrictions
IllegalArgumentException - if the buffer size does not represent an integral number of sample frames, or if format is not fully specified or invalid
IllegalStateException - if the line is already open
SecurityException - if the line cannot be opened due to security restrictions
See Also:
open(AudioFormat),
Line.open(),
Line.close(),
Line.isOpen(),
LineEvent

open

void open(AudioFormat format)
          throws LineUnavailableException
Opens the line with the specified format, causing the line to acquire any required system resources and become operational.

The implementation chooses a buffer size, which is measured in bytes but which encompasses an integral number of sample frames. The buffer size that the system has chosen may be queried by subsequently calling DataLine.getBufferSize()

If this operation succeeds, the line is marked as open, and an OPEN event is dispatched to the line's listeners.

Invoking this method on a line that is already open is illegal and may result in an IllegalStateException.

Some lines, once closed, cannot be reopened. Attempts to reopen such a line will always result in a LineUnavailableException.

Parameters:
format - the desired audio format
Throws:
LineUnavailableException - if the line cannot be opened due to resource restrictions
IllegalArgumentException - if format is not fully specified or invalid
IllegalStateException - if the line is already open
SecurityException - if the line cannot be opened due to security restrictions
See Also:
open(AudioFormat, int),
Line.open(),
Line.close(),
Line.isOpen(),
LineEvent

read

int read(byte[] b,
         int off,
         int len)
Reads audio data from the data line's input buffer. The requested number of bytes is read into the specified array, starting at the specified offset into the array in bytes. This method blocks until the requested amount of data has been read. However, if the data line is closed, stopped, drained, or flushed before the requested amount has been read, the method no longer blocks, but returns the number of bytes read thus far.

The number of bytes that can be read without blocking can be ascertained using the available method of the DataLine interface. (While it is guaranteed that this number of bytes can be read without blocking, there is no guarantee that attempts to read additional data will block.)

The number of bytes to be read must represent an integral number of sample frames, such that:

[ bytes read ] % [frame size in bytes ] == 0

The return value will always meet this requirement. A request to read a number of bytes representing a non-integral number of sample frames cannot be fulfilled and may result in an IllegalArgumentException.

Parameters:
b - a byte array that will contain the requested input data when this method returns
off - the offset from the beginning of the array, in bytes
len - the requested number of bytes to read
Returns:
the number of bytes actually read
Throws:
IllegalArgumentException - if the requested number of bytes does not represent an integral number of sample frames. or if len is negative.
ArrayIndexOutOfBoundsException - if off is negative, or off+len is greater than the length of the array b.
See Also:
SourceDataLine.write(byte[], int, int), DataLine.available()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UnsupportedAudioFileException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.sound.sampled
Class UnsupportedAudioFileException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.sound.sampled.UnsupportedAudioFileException
All Implemented Interfaces:
Serializable
public class UnsupportedAudioFileException
extends Exception

An UnsupportedAudioFileException is an exception indicating that an operation failed because a file did not contain valid data of a recognized file type and format.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
UnsupportedAudioFileException()
Constructs a UnsupportedAudioFileException that has null as its error detail message.
UnsupportedAudioFileException(String message)
Constructs a UnsupportedAudioFileException that has the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UnsupportedAudioFileException

public UnsupportedAudioFileException()
Constructs a UnsupportedAudioFileException that has null as its error detail message.

UnsupportedAudioFileException

public UnsupportedAudioFileException(String message)
Constructs a UnsupportedAudioFileException that has the specified detail message.

Parameters:
message - a string containing the error detail message
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


sql

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.sql

Provides the API for server side data source access and processing from the JavaTM programming language.

See:
Description

Interface Summary
CommonDataSource | Interface that defines the methods which are common between DataSource, XADataSource and ConnectionPoolDataSource.
ConnectionEventListener | An object that registers to be notified of events generated by a PooledConnection object.
ConnectionPoolDataSource | A factory for PooledConnection objects.
DataSource | A factory for connections to the physical data source that this DataSource object represents.
PooledConnection | An object that provides hooks for connection pool management.
RowSet | The interface that adds support to the JDBC API for the JavaBeansTM component model.
RowSetInternal | The interface that a RowSet object implements in order to present itself to a RowSetReader or RowSetWriter object.
RowSetListener | An interface that must be implemented by a component that wants to be notified when a significant event happens in the life of a RowSet object.
RowSetMetaData | An object that contains information about the columns in a RowSet object.
RowSetReader | The facility that a disconnected RowSet object calls on to populate itself with rows of data.
RowSetWriter | An object that implements the RowSetWriter interface, called a writer.
StatementEventListener | An object that registers to be notified of events that occur on PreparedStatements that are in the Statement pool.
XAConnection | An object that provides support for distributed transactions.
XADataSource | A factory for XAConnection objects that is used internally.

Class Summary
ConnectionEvent | An Event object that provides information about the source of a connection-related event.
RowSetEvent | An Event object generated when an event occurs to a RowSet object.
StatementEvent | A StatementEvent is sent to all StatementEventListeners which were registered with a PooledConnection.

Package javax.sql Description

Provides the API for server side data source access and processing from the JavaTM programming language. This package supplements the java.sql package and, as of the version 1.4 release, is included in the Java Platform, Standard Edition (Java SETM). It remains an essential part of the Java Platform, Enterprise Edition (Java EETM).

The javax.sql package provides for the following:

  1. The DataSource interface as an alternative to the DriverManager for establishing a connection with a data source
  2. Connection pooling and Statement pooling
  3. Distributed transactions
  4. Rowsets

Applications use the DataSource and RowSet APIs directly, but the connection pooling and distributed transaction APIs are used internally by the middle-tier infrastructure.

Using a DataSource Object to Make a Connection

The javax.sql package provides the preferred way to make a connection with a data source. The DriverManager class, the original mechanism, is still valid, and code using it will continue to run. However, the newer DataSource mechanism is preferred because it offers many advantages over the DriverManager mechanism.

These are the main advantages of using a DataSource object to make a connection:

  • Changes can be made to a data source's properties, which means that it is not necessary to make changes in application code when something about the data source or driver changes.
  • Connection and Statement pooling and distributed transactions are available through a DataSource object that is implemented to work with the middle-tier infrastructure. Connections made through the DriverManager do not have connection and statement pooling or distributed transaction capabilities.

Driver vendors provide DataSource implementations. A particular DataSource object represents a particular physical data source, and each connection the DataSource object creates is a connection to that physical data source.

A logical name for the data source is registered with a naming service that uses the Java Naming and Directory InterfaceTM (JNDI) API, usually by a system administrator or someone performing the duties of a system administrator. An application can retrieve the DataSource object it wants by doing a lookup on the logical name that has been registered for it. The application can then use the DataSource object to create a connection to the physical data source it represents.

A DataSource object can be implemented to work with the middle tier infrastructure so that the connections it produces will be pooled for reuse. An application that uses such a DataSource implementation will automatically get a connection that participates in connection pooling. A DataSource object can also be implemented to work with the middle tier infrastructure so that the connections it produces can be used for distributed transactions without any special coding.

Connection Pooling and Statement Pooling

Connections made via a DataSource object that is implemented to work with a middle tier connection pool manager will participate in connection pooling. This can improve performance dramatically because creating new connections is very expensive. Connection pooling allows a connection to be used and reused, thus cutting down substantially on the number of new connections that need to be created.

Connection pooling is totally transparent. It is done automatically in the middle tier of a Java EE configuration, so from an application's viewpoint, no change in code is required. An application simply uses the DataSource.getConnection method to get the pooled connection and uses it the same way it uses any Connection object.

The classes and interfaces used for connection pooling are:

  • ConnectionPoolDataSource
  • PooledConnection
  • ConnectionEvent
  • ConnectionEventListener
  • StatementEvent
  • StatementEventListener
The connection pool manager, a facility in the middle tier of a three-tier architecture, uses these classes and interfaces behind the scenes. When a ConnectionPoolDataSource object is called on to create a PooledConnection object, the connection pool manager will register as a ConnectionEventListener object with the new PooledConnection object. When the connection is closed or there is an error, the connection pool manager (being a listener) gets a notification that includes a ConnectionEvent object.

If the connection pool manager supports Statement pooling, for PreparedStatements, which can be determined by invoking the method DatabaseMetaData.supportsStatementPooling, the connection pool manager will register as a StatementEventListener object with the new PooledConnection object. When the PreparedStatement is closed or there is an error, the connection pool manager (being a listener) gets a notification that includes a StatementEvent object.

Distributed Transactions

As with pooled connections, connections made via a DataSource object that is implemented to work with the middle tier infrastructure may participate in distributed transactions. This gives an application the ability to involve data sources on multiple servers in a single transaction.

The classes and interfaces used for distributed transactions are:

  • XADataSource
  • XAConnection
These interfaces are used by the transaction manager; an application does not use them directly.

The XAConnection interface is derived from the PooledConnection interface, so what applies to a pooled connection also applies to a connection that is part of a distributed transaction. A transaction manager in the middle tier handles everything transparently. The only change in application code is that an application cannot do anything that would interfere with the transaction manager's handling of the transaction. Specifically, an application cannot call the methods Connection.commit or Connection.rollback, and it cannot set the connection to be in auto-commit mode (that is, it cannot call Connection.setAutoCommit(true)).

An application does not need to do anything special to participate in a distributed transaction. It simply creates connections to the data sources it wants to use via the DataSource.getConnection method, just as it normally does. The transaction manager manages the transaction behind the scenes. The XADataSource interface creates XAConnection objects, and each XAConnection object creates an XAResource object that the transaction manager uses to manage the connection.

Rowsets

The RowSet interface works with various other classes and interfaces behind the scenes. These can be grouped into three categories.
  1. Event Notification
    • RowSetListener
      A RowSet object is a JavaBeansTM component because it has properties and participates in the JavaBeans event notification mechanism. The RowSetListener interface is implemented by a component that wants to be notified about events that occur to a particular RowSet object. Such a component registers itself as a listener with a rowset via the RowSet.addRowSetListener method.

      When the RowSet object changes one of its rows, changes all of it rows, or moves its cursor, it also notifies each listener that is registered with it. The listener reacts by carrying out its implementation of the notification method called on it.

    • RowSetEvent
      As part of its internal notification process, a RowSet object creates an instance of RowSetEvent and passes it to the listener. The listener can use this RowSetEvent object to find out which rowset had the event.

  2. Metadata
    • RowSetMetaData
      This interface, derived from the ResultSetMetaData interface, provides information about the columns in a RowSet object. An application can use RowSetMetaData methods to find out how many columns the rowset contains and what kind of data each column can contain.

      The RowSetMetaData interface provides methods for setting the information about columns, but an application would not normally use these methods. When an application calls the RowSet method execute, the RowSet object will contain a new set of rows, and its RowSetMetaData object will have been internally updated to contain information about the new columns.

  3. The Reader/Writer Facility
    A RowSet object that implements the RowSetInternal interface can call on the RowSetReader object associated with it to populate itself with data. It can also call on the RowSetWriter object associated with it to write any changes to its rows back to the data source from which it originally got the rows. A rowset that remains connected to its data source does not need to use a reader and writer because it can simply operate on the data source directly.
    • RowSetInternal
      By implementing the RowSetInternal interface, a RowSet object gets access to its internal state and is able to call on its reader and writer. A rowset keeps track of the values in its current rows and of the values that immediately preceded the current ones, referred to as the original values. A rowset also keeps track of (1) the parameters that have been set for its command and (2) the connection that was passed to it, if any. A rowset uses the RowSetInternal methods behind the scenes to get access to this information. An application does not normally invoke these methods directly.

    • RowSetReader
      A disconnected RowSet object that has implemented the RowSetInternal interface can call on its reader (the RowSetReader object associated with it) to populate it with data. When an application calls the RowSet.execute method, that method calls on the rowset's reader to do much of the work. Implementations can vary widely, but generally a reader makes a connection to the data source, reads data from the data source and populates the rowset with it, and closes the connection. A reader may also update the RowSetMetaData object for its rowset. The rowset's internal state is also updated, either by the reader or directly by the method RowSet.execute.
    • RowSetWriter
      A disconnected RowSet object that has implemented the RowSetInternal interface can call on its writer (the RowSetWriter object associated with it) to write changes back to the underlying data source. Implementations may vary widely, but generally, a writer will do the following:

      • Make a connection to the data source
      • Check to see whether there is a conflict, that is, whether a value that has been changed in the rowset has also been changed in the data source
      • Write the new values to the data source if there is no conflict
      • Close the connection

The RowSet interface may be implemented in any number of ways, and anyone may write an implementation. Developers are encouraged to use their imaginations in coming up with new ways to use rowsets.

IMPORTANT NOTE: Code that uses API marked "Since 1.6" must be run using a JDBC technology driver that implements the JDBC 4.0 API. You must check your driver documentation to be sure that it implements the particular features you want to use.

Package Specification

  • Specification of the JDBC 4.0 API

Related Documentation

The Java Series book published by Addison-Wesley Longman provides detailed information about the classes and interfaces in the javax.sql package:
  • JDBCTM API Tutorial and Reference, Third Edition:

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.sql Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.sql

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.util.EventObject (implements java.io.Serializable)
      • javax.sql.ConnectionEvent
      • javax.sql.RowSetEvent
      • javax.sql.StatementEvent

Interface Hierarchy

  • javax.sql.CommonDataSource
    • javax.sql.ConnectionPoolDataSource
    • javax.sql.DataSource (also extends java.sql.Wrapper)
    • javax.sql.XADataSource
  • java.util.EventListener
    • javax.sql.ConnectionEventListener
    • javax.sql.RowSetListener
    • javax.sql.StatementEventListener
  • javax.sql.PooledConnection
    • javax.sql.XAConnection
  • javax.sql.RowSetInternal
  • javax.sql.RowSetReader
  • javax.sql.RowSetWriter
  • java.sql.Wrapper
    • javax.sql.DataSource (also extends javax.sql.CommonDataSource)
    • java.sql.ResultSet
      • javax.sql.RowSet
    • java.sql.ResultSetMetaData
      • javax.sql.RowSetMetaData
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.sql

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.sql

Packages that use javax.sql
javax.sql | Provides the API for server side data source access and processing from the JavaTM programming language.
javax.sql.rowset | Standard interfaces and base classes for JDBC RowSet implementations.
javax.sql.rowset.spi | The standard classes and interfaces that a third party vendor has to use in its implementation of a synchronization provider.

Classes in javax.sql used by javax.sql
CommonDataSource
Interface that defines the methods which are common between DataSource, XADataSource and ConnectionPoolDataSource.
ConnectionEvent
An Event object that provides information about the source of a connection-related event.
ConnectionEventListener
An object that registers to be notified of events generated by a PooledConnection object.
PooledConnection
An object that provides hooks for connection pool management.
RowSet
The interface that adds support to the JDBC API for the JavaBeansTM component model.
RowSetEvent
An Event object generated when an event occurs to a RowSet object.
RowSetInternal
The interface that a RowSet object implements in order to present itself to a RowSetReader or RowSetWriter object.
RowSetListener
An interface that must be implemented by a component that wants to be notified when a significant event happens in the life of a RowSet object.
RowSetMetaData
An object that contains information about the columns in a RowSet object.
StatementEvent
A StatementEvent is sent to all StatementEventListeners which were registered with a PooledConnection.
StatementEventListener
An object that registers to be notified of events that occur on PreparedStatements that are in the Statement pool.
XAConnection
An object that provides support for distributed transactions.

Classes in javax.sql used by javax.sql.rowset
RowSet
The interface that adds support to the JDBC API for the JavaBeansTM component model.
RowSetEvent
An Event object generated when an event occurs to a RowSet object.
RowSetListener
An interface that must be implemented by a component that wants to be notified when a significant event happens in the life of a RowSet object.
RowSetMetaData
An object that contains information about the columns in a RowSet object.

Classes in javax.sql used by javax.sql.rowset.spi
RowSet
The interface that adds support to the JDBC API for the JavaBeansTM component model.
RowSetReader
The facility that a disconnected RowSet object calls on to populate itself with rows of data.
RowSetWriter
An object that implements the RowSetWriter interface, called a writer.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.ConnectionEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.ConnectionEvent

Packages that use ConnectionEvent
javax.sql Provides the API for server side data source access and processing from the JavaTM programming language.

Uses of ConnectionEvent in javax.sql

Methods in javax.sql with parameters of type ConnectionEvent
void | ConnectionEventListener.connectionClosed(ConnectionEvent event) Notifies this ConnectionEventListener that the application has called the method close on its representation of a pooled connection.
void | ConnectionEventListener.connectionErrorOccurred(ConnectionEvent event) Notifies this ConnectionEventListener that a fatal error has occurred and the pooled connection can no longer be used.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.RowSetEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.RowSetEvent

Packages that use RowSetEvent
javax.sql | Provides the API for server side data source access and processing from the JavaTM programming language.
javax.sql.rowset | Standard interfaces and base classes for JDBC RowSet implementations.

Uses of RowSetEvent in javax.sql

Methods in javax.sql with parameters of type RowSetEvent
void | RowSetListener.cursorMoved(RowSetEvent event) Notifies registered listeners that a RowSet object's cursor has moved.
void | RowSetListener.rowChanged(RowSetEvent event) Notifies registered listeners that a RowSet object has had a change in one of its rows.
void | RowSetListener.rowSetChanged(RowSetEvent event) Notifies registered listeners that a RowSet object in the given RowSetEvent object has changed its entire contents.

Uses of RowSetEvent in javax.sql.rowset

Methods in javax.sql.rowset with parameters of type RowSetEvent
 void CachedRowSet.rowSetPopulated(RowSetEvent event, int numRows)
Notifies registered listeners that a RowSet object in the given RowSetEvent object has populated a number of additional rows.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.StatementEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.StatementEvent

Packages that use StatementEvent
javax.sql Provides the API for server side data source access and processing from the JavaTM programming language.

Uses of StatementEvent in javax.sql

Methods in javax.sql with parameters of type StatementEvent
void | StatementEventListener.statementClosed(StatementEvent event) The driver calls this method on all StatementEventListeners registered on the connection when it detects that a PreparedStatement is closed.
void | StatementEventListener.statementErrorOccurred(StatementEvent event) The driver calls this method on all StatementEventListeners registered on the connection when it detects that a PreparedStatement is invalid.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.CommonDataSource

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.CommonDataSource

Packages that use CommonDataSource
javax.sql Provides the API for server side data source access and processing from the JavaTM programming language.

Uses of CommonDataSource in javax.sql

Subinterfaces of CommonDataSource in javax.sql
interface | ConnectionPoolDataSource A factory for PooledConnection objects.
interface | DataSource A factory for connections to the physical data source that this DataSource object represents.
interface | XADataSource A factory for XAConnection objects that is used internally.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.ConnectionEventListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.ConnectionEventListener

Packages that use ConnectionEventListener
javax.sql Provides the API for server side data source access and processing from the JavaTM programming language.

Uses of ConnectionEventListener in javax.sql

Methods in javax.sql with parameters of type ConnectionEventListener
void | PooledConnection.addConnectionEventListener(ConnectionEventListener listener) Registers the given event listener so that it will be notified when an event occurs on this PooledConnection object.
void | PooledConnection.removeConnectionEventListener(ConnectionEventListener listener) Removes the given event listener from the list of components that will be notified when an event occurs on this PooledConnection object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.ConnectionPoolDataSource

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.ConnectionPoolDataSource

No usage of javax.sql.ConnectionPoolDataSource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.DataSource

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.DataSource

No usage of javax.sql.DataSource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.PooledConnection

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.PooledConnection

Packages that use PooledConnection
javax.sql Provides the API for server side data source access and processing from the JavaTM programming language.

Uses of PooledConnection in javax.sql

Subinterfaces of PooledConnection in javax.sql
 interface XAConnection
An object that provides support for distributed transactions.

Methods in javax.sql that return PooledConnection
PooledConnection | ConnectionPoolDataSource.getPooledConnection() Attempts to establish a physical database connection that can be used as a pooled connection.
PooledConnection | ConnectionPoolDataSource.getPooledConnection(String user, String password) Attempts to establish a physical database connection that can be used as a pooled connection.

Constructors in javax.sql with parameters of type PooledConnection
ConnectionEvent(PooledConnection con)
Constructs a ConnectionEvent object initialized with the given PooledConnection object.
ConnectionEvent(PooledConnection con, SQLException ex)
Constructs a ConnectionEvent object initialized with the given PooledConnection object and SQLException object.
StatementEvent(PooledConnection con, PreparedStatement statement)
Constructs a StatementEvent with the specified PooledConnection and PreparedStatement.
StatementEvent(PooledConnection con, PreparedStatement statement, SQLException exception)
Constructs a StatementEvent with the specified PooledConnection, PreparedStatement and SQLException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.RowSet

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.RowSet

Packages that use RowSet
javax.sql | Provides the API for server side data source access and processing from the JavaTM programming language.
javax.sql.rowset | Standard interfaces and base classes for JDBC RowSet implementations.
javax.sql.rowset.spi | The standard classes and interfaces that a third party vendor has to use in its implementation of a synchronization provider.

Uses of RowSet in javax.sql

Constructors in javax.sql with parameters of type RowSet
RowSetEvent(RowSet source)
Constructs a RowSetEvent object initialized with the given RowSet object.

Uses of RowSet in javax.sql.rowset

Subinterfaces of RowSet in javax.sql.rowset
interface | CachedRowSet The interface that all standard implementations of CachedRowSet must implement.
interface | FilteredRowSet The standard interface that all standard implementations of FilteredRowSet must implement.
interface | JdbcRowSet The standard interface that all standard implementations of JdbcRowSet must implement.
interface | JoinRowSet The JoinRowSet interface provides a mechanism for combining related data from different RowSet objects into one JoinRowSet object, which represents an SQL JOIN.
interface | WebRowSet The standard interface that all implementations of a WebRowSet must implement.

Methods in javax.sql.rowset that return RowSet
 RowSet CachedRowSet.createShared()
Returns a new RowSet object backed by the same data as that of this CachedRowSet object.

Methods in javax.sql.rowset with parameters of type RowSet
void | JoinRowSet.addRowSet(RowSet[] rowset, int[] columnIdx) Adds one or more RowSet objects contained in the given array of RowSet objects to this JoinRowSet object and sets the match column for each of the RowSet objects to the match columns in the given array of column indexes.
void | JoinRowSet.addRowSet(RowSet[] rowset, String[] columnName) Adds one or more RowSet objects contained in the given array of RowSet objects to this JoinRowSet object and sets the match column for each of the RowSet objects to the match columns in the given array of column names.
void | JoinRowSet.addRowSet(RowSet rowset, int columnIdx) Adds the given RowSet object to this JoinRowSet object and sets the designated column as the match column for the RowSet object.
void | JoinRowSet.addRowSet(RowSet rowset, String columnName) Adds rowset to this JoinRowSet object and sets the designated column as the match column.
boolean | Predicate.evaluate(RowSet rs) This method is typically called a FilteredRowSet object internal methods (not public) that control the RowSet object's cursor moving from row to the next.

Uses of RowSet in javax.sql.rowset.spi

Subinterfaces of RowSet in javax.sql.rowset.spi
 interface SyncResolver
Defines a framework that allows applications to use a manual decision tree to decide what should be done when a synchronization conflict occurs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.RowSetInternal

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.RowSetInternal

Packages that use RowSetInternal
javax.sql Provides the API for server side data source access and processing from the JavaTM programming language.

Uses of RowSetInternal in javax.sql

Methods in javax.sql with parameters of type RowSetInternal
void | RowSetReader.readData(RowSetInternal caller) Reads the new contents of the calling RowSet object.
boolean | RowSetWriter.writeData(RowSetInternal caller) Writes the changes in this RowSetWriter object's rowset back to the data source from which it got its data.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.RowSetListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.RowSetListener

Packages that use RowSetListener
javax.sql | Provides the API for server side data source access and processing from the JavaTM programming language.
javax.sql.rowset | Standard interfaces and base classes for JDBC RowSet implementations.

Uses of RowSetListener in javax.sql

Methods in javax.sql with parameters of type RowSetListener
void | RowSet.addRowSetListener(RowSetListener listener) Registers the given listener so that it will be notified of events that occur on this RowSet object.
void | RowSet.removeRowSetListener(RowSetListener listener) Removes the specified listener from the list of components that will be notified when an event occurs on this RowSet object.

Uses of RowSetListener in javax.sql.rowset

Methods in javax.sql.rowset with parameters of type RowSetListener
void | BaseRowSet.addRowSetListener(RowSetListener listener) The listener will be notified whenever an event occurs on this RowSet object.
void | BaseRowSet.removeRowSetListener(RowSetListener listener) Removes the designated object from this RowSet object's list of listeners.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.RowSetMetaData

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.RowSetMetaData

Packages that use RowSetMetaData
javax.sql | Provides the API for server side data source access and processing from the JavaTM programming language.
javax.sql.rowset | Standard interfaces and base classes for JDBC RowSet implementations.

Uses of RowSetMetaData in javax.sql

Methods in javax.sql with parameters of type RowSetMetaData
 void RowSetInternal.setMetaData(RowSetMetaData md)
Sets the given RowSetMetaData object as the RowSetMetaData object for this RowSet object.

Uses of RowSetMetaData in javax.sql.rowset

Classes in javax.sql.rowset that implement RowSetMetaData
 class RowSetMetaDataImpl
Provides implementations for the methods that set and get metadata information about a RowSet object's columns.

Methods in javax.sql.rowset with parameters of type RowSetMetaData
 void CachedRowSet.setMetaData(RowSetMetaData md)
Sets the metadata for this CachedRowSet object with the given RowSetMetaData object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.RowSetReader

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.RowSetReader

Packages that use RowSetReader
javax.sql.rowset.spi The standard classes and interfaces that a third party vendor has to use in its implementation of a synchronization provider.

Uses of RowSetReader in javax.sql.rowset.spi

Subinterfaces of RowSetReader in javax.sql.rowset.spi
 interface XmlReader
A specialized interface that facilitates an extension of the SyncProvider abstract class for XML orientated synchronization providers.

Methods in javax.sql.rowset.spi that return RowSetReader
abstract  RowSetReader SyncProvider.getRowSetReader()
Returns a javax.sql.RowSetReader object, which can be used to populate a RowSet object with data.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.RowSetWriter

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.RowSetWriter

Packages that use RowSetWriter
javax.sql.rowset.spi The standard classes and interfaces that a third party vendor has to use in its implementation of a synchronization provider.

Uses of RowSetWriter in javax.sql.rowset.spi

Subinterfaces of RowSetWriter in javax.sql.rowset.spi
interface | TransactionalWriter A specialized interface that facilitates an extension of the standard SyncProvider abstract class so that it has finer grained transaction control.
interface | XmlWriter A specialized interface that facilitates an extension of the SyncProvider abstract class for XML orientated synchronization providers.

Methods in javax.sql.rowset.spi that return RowSetWriter
abstract  RowSetWriter SyncProvider.getRowSetWriter()
Returns a javax.sql.RowSetWriter object, which can be used to write a RowSet object's data back to the underlying data source.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.StatementEventListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.StatementEventListener

Packages that use StatementEventListener
javax.sql Provides the API for server side data source access and processing from the JavaTM programming language.

Uses of StatementEventListener in javax.sql

Methods in javax.sql with parameters of type StatementEventListener
void | PooledConnection.addStatementEventListener(StatementEventListener listener) Registers a StatementEventListener with this PooledConnection object.
void | PooledConnection.removeStatementEventListener(StatementEventListener listener) Removes the specified StatementEventListener from the list of components that will be notified when the driver detects that a PreparedStatement has been closed or is invalid.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.XAConnection

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.XAConnection

Packages that use XAConnection
javax.sql Provides the API for server side data source access and processing from the JavaTM programming language.

Uses of XAConnection in javax.sql

Methods in javax.sql that return XAConnection
XAConnection | XADataSource.getXAConnection() Attempts to establish a physical database connection that can be used in a distributed transaction.
XAConnection | XADataSource.getXAConnection(String user, String password) Attempts to establish a physical database connection, using the given user name and password.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.XADataSource

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.XADataSource

No usage of javax.sql.XADataSource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


CommonDataSource

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.sql
Interface CommonDataSource

All Known Subinterfaces:
ConnectionPoolDataSource, DataSource, XADataSource
public interface CommonDataSource

Interface that defines the methods which are common between DataSource, XADataSource and ConnectionPoolDataSource.

Method Summary
int | getLoginTimeout() Gets the maximum time in seconds that this data source can wait while attempting to connect to a database.
PrintWriter | getLogWriter() Retrieves the log writer for this DataSource object.
void | setLoginTimeout(int seconds) Sets the maximum time in seconds that this data source will wait while attempting to connect to a database.
void | setLogWriter(PrintWriter out) Sets the log writer for this DataSource object to the given java.io.PrintWriter object.

Method Detail

getLogWriter

PrintWriter getLogWriter()
                         throws SQLException

Retrieves the log writer for this DataSource object.

The log writer is a character output stream to which all logging and tracing messages for this data source will be printed. This includes messages printed by the methods of this object, messages printed by methods of other objects manufactured by this object, and so on. Messages printed to a data source specific log writer are not printed to the log writer associated with the java.sql.DriverManager class. When a DataSource object is created, the log writer is initially null; in other words, the default is for logging to be disabled.

Returns:
the log writer for this data source or null if logging is disabled
Throws:
SQLException - if a database access error occurs
Since:
1.4
See Also:
setLogWriter(java.io.PrintWriter)

setLogWriter

void setLogWriter(PrintWriter out)
                  throws SQLException

Sets the log writer for this DataSource object to the given java.io.PrintWriter object.

The log writer is a character output stream to which all logging and tracing messages for this data source will be printed. This includes messages printed by the methods of this object, messages printed by methods of other objects manufactured by this object, and so on. Messages printed to a data source- specific log writer are not printed to the log writer associated with the java.sql.DriverManager class. When a DataSource object is created the log writer is initially null; in other words, the default is for logging to be disabled.

Parameters:
out - the new log writer; to disable logging, set to null
Throws:
SQLException - if a database access error occurs
Since:
1.4
See Also:
getLogWriter()

setLoginTimeout

void setLoginTimeout(int seconds)
                     throws SQLException

Sets the maximum time in seconds that this data source will wait while attempting to connect to a database. A value of zero specifies that the timeout is the default system timeout if there is one; otherwise, it specifies that there is no timeout. When a DataSource object is created, the login timeout is initially zero.

Parameters:
seconds - the data source login time limit
Throws:
SQLException - if a database access error occurs.
Since:
1.4
See Also:
getLoginTimeout()

getLoginTimeout

int getLoginTimeout()
                    throws SQLException
Gets the maximum time in seconds that this data source can wait while attempting to connect to a database. A value of zero means that the timeout is the default system timeout if there is one; otherwise, it means that there is no timeout. When a DataSource object is created, the login timeout is initially zero.

Returns:
the data source login time limit
Throws:
SQLException - if a database access error occurs.
Since:
1.4
See Also:
setLoginTimeout(int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


ConnectionEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql
Class ConnectionEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.sql.ConnectionEvent
All Implemented Interfaces:
Serializable
public class ConnectionEvent
extends EventObject

An Event object that provides information about the source of a connection-related event. ConnectionEvent objects are generated when an application closes a pooled connection and when an error occurs. The ConnectionEvent object contains two kinds of information:

  • The pooled connection closed by the application
  • In the case of an error event, the SQLException about to be thrown to the application

Since:
1.4
See Also:
Serialized Form

Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
ConnectionEvent(PooledConnection con)
Constructs a ConnectionEvent object initialized with the given PooledConnection object.
ConnectionEvent(PooledConnection con, SQLException ex)
Constructs a ConnectionEvent object initialized with the given PooledConnection object and SQLException object.
Method Summary
 SQLException getSQLException()
Retrieves the SQLException for this ConnectionEvent object.
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ConnectionEvent

public ConnectionEvent(PooledConnection con)

Constructs a ConnectionEvent object initialized with the given PooledConnection object. SQLException defaults to null.

Parameters:
con - the pooled connection that is the source of the event
Throws:
IllegalArgumentException - if con is null.

ConnectionEvent

public ConnectionEvent(PooledConnection con,
                       SQLException ex)

Constructs a ConnectionEvent object initialized with the given PooledConnection object and SQLException object.

Parameters:
con - the pooled connection that is the source of the event
ex - the SQLException about to be thrown to the application
Throws:
IllegalArgumentException - if con is null.
Method Detail

getSQLException

public SQLException getSQLException()

Retrieves the SQLException for this ConnectionEvent object. May be null.

Returns:
the SQLException about to be thrown or null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ConnectionEventListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql
Interface ConnectionEventListener

All Superinterfaces:
EventListener
public interface ConnectionEventListener
extends EventListener

An object that registers to be notified of events generated by a PooledConnection object.

The ConnectionEventListener interface is implemented by a connection pooling component. A connection pooling component will usually be provided by a JDBC driver vendor or another system software vendor. A JDBC driver notifies a ConnectionEventListener object when an application is finished using a pooled connection with which the listener has registered. The notification occurs after the application calls the method close on its representation of a PooledConnection object. A ConnectionEventListener is also notified when a connection error occurs due to the fact that the PooledConnection is unfit for future use---the server has crashed, for example. The listener is notified by the JDBC driver just before the driver throws an SQLException to the application using the PooledConnection object.

Since:
1.4

Method Summary
void | connectionClosed(ConnectionEvent event) Notifies this ConnectionEventListener that the application has called the method close on its representation of a pooled connection.
void | connectionErrorOccurred(ConnectionEvent event) Notifies this ConnectionEventListener that a fatal error has occurred and the pooled connection can no longer be used.

Method Detail

connectionClosed

void connectionClosed(ConnectionEvent event)
Notifies this ConnectionEventListener that the application has called the method close on its representation of a pooled connection.

Parameters:
event - an event object describing the source of the event

connectionErrorOccurred

void connectionErrorOccurred(ConnectionEvent event)
Notifies this ConnectionEventListener that a fatal error has occurred and the pooled connection can no longer be used. The driver makes this notification just before it throws the application the SQLException contained in the given ConnectionEvent object.

Parameters:
event - an event object describing the source of the event and containing the SQLException that the driver is about to throw
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ConnectionPoolDataSource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql
Interface ConnectionPoolDataSource

All Superinterfaces:
CommonDataSource
public interface ConnectionPoolDataSource
extends CommonDataSource

A factory for PooledConnection objects. An object that implements this interface will typically be registered with a naming service that is based on the JavaTM Naming and Directory Interface (JNDI).

Since:
1.4

Method Summary
PooledConnection | getPooledConnection() Attempts to establish a physical database connection that can be used as a pooled connection.
PooledConnection | getPooledConnection(String user, String password) Attempts to establish a physical database connection that can be used as a pooled connection.
Methods inherited from interface javax.sql.CommonDataSource
getLoginTimeout, getLogWriter, setLoginTimeout, setLogWriter

Method Detail

getPooledConnection

PooledConnection getPooledConnection()
                                     throws SQLException
Attempts to establish a physical database connection that can be used as a pooled connection.

Returns:
a PooledConnection object that is a physical connection to the database that this ConnectionPoolDataSource object represents
Throws:
SQLException - if a database access error occurs
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4

getPooledConnection

PooledConnection getPooledConnection(String user,
                                     String password)
                                     throws SQLException
Attempts to establish a physical database connection that can be used as a pooled connection.

Parameters:
user - the database user on whose behalf the connection is being made
password - the user's password
Returns:
a PooledConnection object that is a physical connection to the database that this ConnectionPoolDataSource object represents
Throws:
SQLException - if a database access error occurs
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DataSource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql
Interface DataSource

All Superinterfaces:
CommonDataSource, Wrapper
public interface DataSource
extends CommonDataSource, Wrapper

A factory for connections to the physical data source that this DataSource object represents. An alternative to the DriverManager facility, a DataSource object is the preferred means of getting a connection. An object that implements the DataSource interface will typically be registered with a naming service based on the JavaTM Naming and Directory (JNDI) API.

The DataSource interface is implemented by a driver vendor. There are three types of implementations:

  1. Basic implementation -- produces a standard Connection object
  2. Connection pooling implementation -- produces a Connection object that will automatically participate in connection pooling. This implementation works with a middle-tier connection pooling manager.
  3. Distributed transaction implementation -- produces a Connection object that may be used for distributed transactions and almost always participates in connection pooling. This implementation works with a middle-tier transaction manager and almost always with a connection pooling manager.

A DataSource object has properties that can be modified when necessary. For example, if the data source is moved to a different server, the property for the server can be changed. The benefit is that because the data source's properties can be changed, any code accessing that data source does not need to be changed.

A driver that is accessed via a DataSource object does not register itself with the DriverManager. Rather, a DataSource object is retrieved though a lookup operation and then used to create a Connection object. With a basic implementation, the connection obtained through a DataSource object is identical to a connection obtained through the DriverManager facility.

Since:
1.4

Method Summary
Connection | getConnection() Attempts to establish a connection with the data source that this DataSource object represents.
Connection | getConnection(String username, String password) Attempts to establish a connection with the data source that this DataSource object represents.
Methods inherited from interface javax.sql.CommonDataSource
getLoginTimeout, getLogWriter, setLoginTimeout, setLogWriter
Methods inherited from interface java.sql.Wrapper
isWrapperFor, unwrap

Method Detail

getConnection

Connection getConnection()
                         throws SQLException

Attempts to establish a connection with the data source that this DataSource object represents.

Returns:
a connection to the data source
Throws:
SQLException - if a database access error occurs

getConnection

Connection getConnection(String username,
                         String password)
                         throws SQLException

Attempts to establish a connection with the data source that this DataSource object represents.

Parameters:
username - the database user on whose behalf the connection is being made
password - the user's password
Returns:
a connection to the data source
Throws:
SQLException - if a database access error occurs
Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PooledConnection

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql
Interface PooledConnection

All Known Subinterfaces:
XAConnection
public interface PooledConnection

An object that provides hooks for connection pool management. A PooledConnection object represents a physical connection to a data source. The connection can be recycled rather than being closed when an application is finished with it, thus reducing the number of connections that need to be made.

An application programmer does not use the PooledConnection interface directly; rather, it is used by a middle tier infrastructure that manages the pooling of connections.

When an application calls the method DataSource.getConnection, it gets back a Connection object. If connection pooling is being done, that Connection object is actually a handle to a PooledConnection object, which is a physical connection.

The connection pool manager, typically the application server, maintains a pool of PooledConnection objects. If there is a PooledConnection object available in the pool, the connection pool manager returns a Connection object that is a handle to that physical connection. If no PooledConnection object is available, the connection pool manager calls the ConnectionPoolDataSource method getPoolConnection to create a new physical connection. The JDBC driver implementing ConnectionPoolDataSource creates a new PooledConnection object and returns a handle to it.

When an application closes a connection, it calls the Connection method close. When connection pooling is being done, the connection pool manager is notified because it has registered itself as a ConnectionEventListener object using the ConnectionPool method addConnectionEventListener. The connection pool manager deactivates the handle to the PooledConnection object and returns the PooledConnection object to the pool of connections so that it can be used again. Thus, when an application closes its connection, the underlying physical connection is recycled rather than being closed.

The physical connection is not closed until the connection pool manager calls the PooledConnection method close. This method is generally called to have an orderly shutdown of the server or if a fatal error has made the connection unusable.

A connection pool manager is often also a statement pool manager, maintining a pool of PreparedStatement objects. When an application closes a prepared statement, it calls the PreparedStatement method close. When Statement pooling is being done, the pool manager is notified because it has registered itself as a StatementEventListener object using the ConnectionPool method addStatementEventListener. Thus, when an application closes its PreparedStatement, the underlying prepared statement is recycled rather than being closed.

Since:
1.4

Method Summary
void | addConnectionEventListener(ConnectionEventListener listener) Registers the given event listener so that it will be notified when an event occurs on this PooledConnection object.
void | addStatementEventListener(StatementEventListener listener) Registers a StatementEventListener with this PooledConnection object.
void | close() Closes the physical connection that this PooledConnection object represents.
Connection | getConnection() Creates and returns a Connection object that is a handle for the physical connection that this PooledConnection object represents.
void | removeConnectionEventListener(ConnectionEventListener listener) Removes the given event listener from the list of components that will be notified when an event occurs on this PooledConnection object.
void | removeStatementEventListener(StatementEventListener listener) Removes the specified StatementEventListener from the list of components that will be notified when the driver detects that a PreparedStatement has been closed or is invalid.

Method Detail

getConnection

Connection getConnection()
                         throws SQLException
Creates and returns a Connection object that is a handle for the physical connection that this PooledConnection object represents. The connection pool manager calls this method when an application has called the method DataSource.getConnection and there are no PooledConnection objects available. See the interface description for more information.

Returns:
a Connection object that is a handle to this PooledConnection object
Throws:
SQLException - if a database access error occurs
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4

close

void close()
           throws SQLException
Closes the physical connection that this PooledConnection object represents. An application never calls this method directly; it is called by the connection pool module, or manager.

See the interface description for more information.

Throws:
SQLException - if a database access error occurs
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4

addConnectionEventListener

void addConnectionEventListener(ConnectionEventListener listener)
Registers the given event listener so that it will be notified when an event occurs on this PooledConnection object.

Parameters:
listener - a component, usually the connection pool manager, that has implemented the ConnectionEventListener interface and wants to be notified when the connection is closed or has an error
See Also:
removeConnectionEventListener(javax.sql.ConnectionEventListener)

removeConnectionEventListener

void removeConnectionEventListener(ConnectionEventListener listener)
Removes the given event listener from the list of components that will be notified when an event occurs on this PooledConnection object.

Parameters:
listener - a component, usually the connection pool manager, that has implemented the ConnectionEventListener interface and been registered with this PooledConnection object as a listener
See Also:
addConnectionEventListener(javax.sql.ConnectionEventListener)

addStatementEventListener

void addStatementEventListener(StatementEventListener listener)
Registers a StatementEventListener with this PooledConnection object. Components that wish to be notified when PreparedStatements created by the connection are closed or are detected to be invalid may use this method to register a StatementEventListener with this PooledConnection object.

Parameters:
listener - an component which implements the StatementEventListener interface that is to be registered with this PooledConnection object

Since:
1.6

removeStatementEventListener

void removeStatementEventListener(StatementEventListener listener)
Removes the specified StatementEventListener from the list of components that will be notified when the driver detects that a PreparedStatement has been closed or is invalid.

Parameters:
listener - the component which implements the StatementEventListener interface that was previously registered with this PooledConnection object

Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RowSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql
Interface RowSet

All Superinterfaces:
ResultSet, Wrapper
All Known Subinterfaces:
CachedRowSet, FilteredRowSet, JdbcRowSet, JoinRowSet, SyncResolver, WebRowSet
public interface RowSet
extends ResultSet

The interface that adds support to the JDBC API for the JavaBeansTM component model. A rowset, which can be used as a JavaBeans component in a visual Bean development environment, can be created and configured at design time and executed at run time.

The RowSet interface provides a set of JavaBeans properties that allow a RowSet instance to be configured to connect to a JDBC data source and read some data from the data source. A group of setter methods (setInt, setBytes, setString, and so on) provide a way to pass input parameters to a rowset's command property. This command is the SQL query the rowset uses when it gets its data from a relational database, which is generally the case.

The RowSet interface supports JavaBeans events, allowing other components in an application to be notified when an event occurs on a rowset, such as a change in its value.

The RowSet interface is unique in that it is intended to be implemented using the rest of the JDBC API. In other words, a RowSet implementation is a layer of software that executes "on top" of a JDBC driver. Implementations of the RowSet interface can be provided by anyone, including JDBC driver vendors who want to provide a RowSet implementation as part of their JDBC products.

A RowSet object may make a connection with a data source and maintain that connection throughout its life cycle, in which case it is called a connected rowset. A rowset may also make a connection with a data source, get data from it, and then close the connection. Such a rowset is called a disconnected rowset. A disconnected rowset may make changes to its data while it is disconnected and then send the changes back to the original source of the data, but it must reestablish a connection to do so.

A disconnected rowset may have a reader (a RowSetReader object) and a writer (a RowSetWriter object) associated with it. The reader may be implemented in many different ways to populate a rowset with data, including getting data from a non-relational data source. The writer can also be implemented in many different ways to propagate changes made to the rowset's data back to the underlying data source.

Rowsets are easy to use. The RowSet interface extends the standard java.sql.ResultSet interface. The RowSetMetaData interface extends the java.sql.ResultSetMetaData interface. Thus, developers familiar with the JDBC API will have to learn a minimal number of new APIs to use rowsets. In addition, third-party software tools that work with JDBC ResultSet objects will also easily be made to work with rowsets.

Since:
1.4

Field Summary
Fields inherited from interface java.sql.ResultSet
CLOSE_CURSORS_AT_COMMIT, CONCUR_READ_ONLY, CONCUR_UPDATABLE, FETCH_FORWARD, FETCH_REVERSE, FETCH_UNKNOWN, HOLD_CURSORS_OVER_COMMIT, TYPE_FORWARD_ONLY, TYPE_SCROLL_INSENSITIVE, TYPE_SCROLL_SENSITIVE
Method Summary
void | addRowSetListener(RowSetListener listener) Registers the given listener so that it will be notified of events that occur on this RowSet object.
void | clearParameters() Clears the parameters set for this RowSet object's command.
void | execute() Fills this RowSet object with data.
String | getCommand() Retrieves this RowSet object's command property.
String | getDataSourceName() Retrieves the logical name that identifies the data source for this RowSet object.
boolean | getEscapeProcessing() Retrieves whether escape processing is enabled for this RowSet object.
int | getMaxFieldSize() Retrieves the maximum number of bytes that may be returned for certain column values.
int | getMaxRows() Retrieves the maximum number of rows that this RowSet object can contain.
String | getPassword() Retrieves the password used to create a database connection.
int | getQueryTimeout() Retrieves the maximum number of seconds the driver will wait for a statement to execute.
int | getTransactionIsolation() Retrieves the transaction isolation level set for this RowSet object.
Map<String,Class<?>> | getTypeMap() Retrieves the Map object associated with this RowSet object, which specifies the custom mapping of SQL user-defined types, if any.
String | getUrl() Retrieves the url property this RowSet object will use to create a connection if it uses the DriverManager instead of a DataSource object to establish the connection.
String | getUsername() Retrieves the username used to create a database connection for this RowSet object.
boolean | isReadOnly() Retrieves whether this RowSet object is read-only.
void | removeRowSetListener(RowSetListener listener) Removes the specified listener from the list of components that will be notified when an event occurs on this RowSet object.
void | setArray(int i, Array x) Sets the designated parameter in this RowSet object's command with the given Array value.
void | setAsciiStream(int parameterIndex, InputStream x) Sets the designated parameter in this RowSet object's command to the given input stream.
void | setAsciiStream(int parameterIndex, InputStream x, int length) Sets the designated parameter in this RowSet object's command to the given java.io.InputStream value.
void | setAsciiStream(String parameterName, InputStream x) Sets the designated parameter to the given input stream.
void | setAsciiStream(String parameterName, InputStream x, int length) Sets the designated parameter to the given input stream, which will have the specified number of bytes.
void | setBigDecimal(int parameterIndex, BigDecimal x) Sets the designated parameter in this RowSet object's command to the given java.math.BigDeciaml value.
void | setBigDecimal(String parameterName, BigDecimal x) Sets the designated parameter to the given java.math.BigDecimal value.
void | setBinaryStream(int parameterIndex, InputStream x) Sets the designated parameter in this RowSet object's command to the given input stream.
void | setBinaryStream(int parameterIndex, InputStream x, int length) Sets the designated parameter in this RowSet object's command to the given java.io.InputStream value.
void | setBinaryStream(String parameterName, InputStream x) Sets the designated parameter to the given input stream.
void | setBinaryStream(String parameterName, InputStream x, int length) Sets the designated parameter to the given input stream, which will have the specified number of bytes.
void | setBlob(int i, Blob x) Sets the designated parameter in this RowSet object's command with the given Blob value.
void | setBlob(int parameterIndex, InputStream inputStream) Sets the designated parameter to a InputStream object.
void | setBlob(int parameterIndex, InputStream inputStream, long length) Sets the designated parameter to a InputStream object.
void | setBlob(String parameterName, Blob x) Sets the designated parameter to the given java.sql.Blob object.
void | setBlob(String parameterName, InputStream inputStream) Sets the designated parameter to a InputStream object.
void | setBlob(String parameterName, InputStream inputStream, long length) Sets the designated parameter to a InputStream object.
void | setBoolean(int parameterIndex, boolean x) Sets the designated parameter in this RowSet object's command to the given Java boolean value.
void | setBoolean(String parameterName, boolean x) Sets the designated parameter to the given Java boolean value.
void | setByte(int parameterIndex, byte x) Sets the designated parameter in this RowSet object's command to the given Java byte value.
void | setByte(String parameterName, byte x) Sets the designated parameter to the given Java byte value.
void | setBytes(int parameterIndex, byte[] x) Sets the designated parameter in this RowSet object's command to the given Java array of byte values.
void | setBytes(String parameterName, byte[] x) Sets the designated parameter to the given Java array of bytes.
void | setCharacterStream(int parameterIndex, Reader reader) Sets the designated parameter in this RowSet object's command to the given Reader object.
void | setCharacterStream(int parameterIndex, Reader reader, int length) Sets the designated parameter in this RowSet object's command to the given java.io.Reader value.
void | setCharacterStream(String parameterName, Reader reader) Sets the designated parameter to the given Reader object.
void | setCharacterStream(String parameterName, Reader reader, int length) Sets the designated parameter to the given Reader object, which is the given number of characters long.
void | setClob(int i, Clob x) Sets the designated parameter in this RowSet object's command with the given Clob value.
void | setClob(int parameterIndex, Reader reader) Sets the designated parameter to a Reader object.
void | setClob(int parameterIndex, Reader reader, long length) Sets the designated parameter to a Reader object.
void | setClob(String parameterName, Clob x) Sets the designated parameter to the given java.sql.Clob object.
void | setClob(String parameterName, Reader reader) Sets the designated parameter to a Reader object.
void | setClob(String parameterName, Reader reader, long length) Sets the designated parameter to a Reader object.
void | setCommand(String cmd) Sets this RowSet object's command property to the given SQL query.
void | setConcurrency(int concurrency) Sets the concurrency of this RowSet object to the given concurrency level.
void | setDataSourceName(String name) Sets the data source name property for this RowSet object to the given String.
void | setDate(int parameterIndex, Date x) Sets the designated parameter in this RowSet object's command to the given java.sql.Date value.
void | setDate(int parameterIndex, Date x, Calendar cal) Sets the designated parameter in this RowSet object's command with the given java.sql.Date value.
void | setDate(String parameterName, Date x) Sets the designated parameter to the given java.sql.Date value using the default time zone of the virtual machine that is running the application.
void | setDate(String parameterName, Date x, Calendar cal) Sets the designated parameter to the given java.sql.Date value, using the given Calendar object.
void | setDouble(int parameterIndex, double x) Sets the designated parameter in this RowSet object's command to the given Java double value.
void | setDouble(String parameterName, double x) Sets the designated parameter to the given Java double value.
void | setEscapeProcessing(boolean enable) Sets escape processing for this RowSet object on or off.
void | setFloat(int parameterIndex, float x) Sets the designated parameter in this RowSet object's command to the given Java float value.
void | setFloat(String parameterName, float x) Sets the designated parameter to the given Java float value.
void | setInt(int parameterIndex, int x) Sets the designated parameter in this RowSet object's command to the given Java int value.
void | setInt(String parameterName, int x) Sets the designated parameter to the given Java int value.
void | setLong(int parameterIndex, long x) Sets the designated parameter in this RowSet object's command to the given Java long value.
void | setLong(String parameterName, long x) Sets the designated parameter to the given Java long value.
void | setMaxFieldSize(int max) Sets the maximum number of bytes that can be returned for a column value to the given number of bytes.
void | setMaxRows(int max) Sets the maximum number of rows that this RowSet object can contain to the specified number.
void | setNCharacterStream(int parameterIndex, Reader value) Sets the designated parameter in this RowSet object's command to a Reader object.
void | setNCharacterStream(int parameterIndex, Reader value, long length) Sets the designated parameter to a Reader object.
void | setNCharacterStream(String parameterName, Reader value) Sets the designated parameter to a Reader object.
void | setNCharacterStream(String parameterName, Reader value, long length) Sets the designated parameter to a Reader object.
void | setNClob(int parameterIndex, NClob value) Sets the designated parameter to a java.sql.NClob object.
void | setNClob(int parameterIndex, Reader reader) Sets the designated parameter to a Reader object.
void | setNClob(int parameterIndex, Reader reader, long length) Sets the designated parameter to a Reader object.
void | setNClob(String parameterName, NClob value) Sets the designated parameter to a java.sql.NClob object.
void | setNClob(String parameterName, Reader reader) Sets the designated parameter to a Reader object.
void | setNClob(String parameterName, Reader reader, long length) Sets the designated parameter to a Reader object.
void | setNString(int parameterIndex, String value) Sets the designated paramter to the given String object.
void | setNString(String parameterName, String value) Sets the designated paramter to the given String object.
void | setNull(int parameterIndex, int sqlType) Sets the designated parameter in this RowSet object's SQL command to SQL NULL.
void | setNull(int paramIndex, int sqlType, String typeName) Sets the designated parameter in this RowSet object's SQL command to SQL NULL.
void | setNull(String parameterName, int sqlType) Sets the designated parameter to SQL NULL.
void | setNull(String parameterName, int sqlType, String typeName) Sets the designated parameter to SQL NULL.
void | setObject(int parameterIndex, Object x) Sets the designated parameter in this RowSet object's command with a Java Object.
void | setObject(int parameterIndex, Object x, int targetSqlType) Sets the designated parameter in this RowSet object's command with a Java Object.
void | setObject(int parameterIndex, Object x, int targetSqlType, int scaleOrLength) Sets the designated parameter in this RowSet object's command with the given Java Object.
void | setObject(String parameterName, Object x) Sets the value of the designated parameter with the given object.
void | setObject(String parameterName, Object x, int targetSqlType) Sets the value of the designated parameter with the given object.
void | setObject(String parameterName, Object x, int targetSqlType, int scale) Sets the value of the designated parameter with the given object.
void | setPassword(String password) Sets the database password for this RowSet object to the given String.
void | setQueryTimeout(int seconds) Sets the maximum time the driver will wait for a statement to execute to the given number of seconds.
void | setReadOnly(boolean value) Sets whether this RowSet object is read-only to the given boolean.
void | setRef(int i, Ref x) Sets the designated parameter in this RowSet object's command with the given Ref value.
void | setRowId(int parameterIndex, RowId x) Sets the designated parameter to the given java.sql.RowId object.
void | setRowId(String parameterName, RowId x) Sets the designated parameter to the given java.sql.RowId object.
void | setShort(int parameterIndex, short x) Sets the designated parameter in this RowSet object's command to the given Java short value.
void | setShort(String parameterName, short x) Sets the designated parameter to the given Java short value.
void | setSQLXML(int parameterIndex, SQLXML xmlObject) Sets the designated parameter to the given java.sql.SQLXML object.
void | setSQLXML(String parameterName, SQLXML xmlObject) Sets the designated parameter to the given java.sql.SQLXML object.
void | setString(int parameterIndex, String x) Sets the designated parameter in this RowSet object's command to the given Java String value.
void | setString(String parameterName, String x) Sets the designated parameter to the given Java String value.
void | setTime(int parameterIndex, Time x) Sets the designated parameter in this RowSet object's command to the given java.sql.Time value.
void | setTime(int parameterIndex, Time x, Calendar cal) Sets the designated parameter in this RowSet object's command with the given java.sql.Time value.
void | setTime(String parameterName, Time x) Sets the designated parameter to the given java.sql.Time value.
void | setTime(String parameterName, Time x, Calendar cal) Sets the designated parameter to the given java.sql.Time value, using the given Calendar object.
void | setTimestamp(int parameterIndex, Timestamp x) Sets the designated parameter in this RowSet object's command to the given java.sql.Timestamp value.
void | setTimestamp(int parameterIndex, Timestamp x, Calendar cal) Sets the designated parameter in this RowSet object's command with the given java.sql.Timestamp value.
void | setTimestamp(String parameterName, Timestamp x) Sets the designated parameter to the given java.sql.Timestamp value.
void | setTimestamp(String parameterName, Timestamp x, Calendar cal) Sets the designated parameter to the given java.sql.Timestamp value, using the given Calendar object.
void | setTransactionIsolation(int level) Sets the transaction isolation level for this RowSet obejct.
void | setType(int type) Sets the type of this RowSet object to the given type.
void | setTypeMap(Map<String,Class<?>> map) Installs the given java.util.Map object as the default type map for this RowSet object.
void | setURL(int parameterIndex, URL x) Sets the designated parameter to the given java.net.URL value.
void | setUrl(String url) Sets the URL this RowSet object will use when it uses the DriverManager to create a connection.
void | setUsername(String name) Sets the username property for this RowSet object to the given String.
Methods inherited from interface java.sql.ResultSet
absolute, afterLast, beforeFirst, cancelRowUpdates, clearWarnings, close, deleteRow, findColumn, first, getArray, getArray, getAsciiStream, getAsciiStream, getBigDecimal, getBigDecimal, getBigDecimal, getBigDecimal, getBinaryStream, getBinaryStream, getBlob, getBlob, getBoolean, getBoolean, getByte, getByte, getBytes, getBytes, getCharacterStream, getCharacterStream, getClob, getClob, getConcurrency, getCursorName, getDate, getDate, getDate, getDate, getDouble, getDouble, getFetchDirection, getFetchSize, getFloat, getFloat, getHoldability, getInt, getInt, getLong, getLong, getMetaData, getNCharacterStream, getNCharacterStream, getNClob, getNClob, getNString, getNString, getObject, getObject, getObject, getObject, getRef, getRef, getRow, getRowId, getRowId, getShort, getShort, getSQLXML, getSQLXML, getStatement, getString, getString, getTime, getTime, getTime, getTime, getTimestamp, getTimestamp, getTimestamp, getTimestamp, getType, getUnicodeStream, getUnicodeStream, getURL, getURL, getWarnings, insertRow, isAfterLast, isBeforeFirst, isClosed, isFirst, isLast, last, moveToCurrentRow, moveToInsertRow, next, previous, refreshRow, relative, rowDeleted, rowInserted, rowUpdated, setFetchDirection, setFetchSize, updateArray, updateArray, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateBigDecimal, updateBigDecimal, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBoolean, updateBoolean, updateByte, updateByte, updateBytes, updateBytes, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateClob, updateClob, updateClob, updateClob, updateClob, updateClob, updateDate, updateDate, updateDouble, updateDouble, updateFloat, updateFloat, updateInt, updateInt, updateLong, updateLong, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNString, updateNString, updateNull, updateNull, updateObject, updateObject, updateObject, updateObject, updateRef, updateRef, updateRow, updateRowId, updateRowId, updateShort, updateShort, updateSQLXML, updateSQLXML, updateString, updateString, updateTime, updateTime, updateTimestamp, updateTimestamp, wasNull
Methods inherited from interface java.sql.Wrapper
isWrapperFor, unwrap

Method Detail

getUrl

String getUrl()
              throws SQLException
Retrieves the url property this RowSet object will use to create a connection if it uses the DriverManager instead of a DataSource object to establish the connection. The default value is null.

Returns:
a string url
Throws:
SQLException - if a database access error occurs
See Also:
setUrl(java.lang.String)

setUrl

void setUrl(String url)
            throws SQLException
Sets the URL this RowSet object will use when it uses the DriverManager to create a connection. Setting this property is optional. If a URL is used, a JDBC driver that accepts the URL must be loaded before the rowset is used to connect to a database. The rowset will use the URL internally to create a database connection when reading or writing data. Either a URL or a data source name is used to create a connection, whichever was set to non null value most recently.

Parameters:
url - a string value; may be null
Throws:
SQLException - if a database access error occurs
See Also:
getUrl()

getDataSourceName

String getDataSourceName()
Retrieves the logical name that identifies the data source for this RowSet object.

Returns:
a data source name
See Also:
setDataSourceName(java.lang.String), setUrl(java.lang.String)

setDataSourceName

void setDataSourceName(String name)
                       throws SQLException
Sets the data source name property for this RowSet object to the given String.

The value of the data source name property can be used to do a lookup of a DataSource object that has been registered with a naming service. After being retrieved, the DataSource object can be used to create a connection to the data source that it represents.

Parameters:
name - the logical name of the data source for this RowSet object; may be null
Throws:
SQLException - if a database access error occurs
See Also:
getDataSourceName()

getUsername

String getUsername()
Retrieves the username used to create a database connection for this RowSet object. The username property is set at run time before calling the method execute. It is not usually part of the serialized state of a RowSet object.

Returns:
the username property
See Also:
setUsername(java.lang.String)

setUsername

void setUsername(String name)
                 throws SQLException
Sets the username property for this RowSet object to the given String.

Parameters:
name - a user name
Throws:
SQLException - if a database access error occurs
See Also:
getUsername()

getPassword

String getPassword()
Retrieves the password used to create a database connection. The password property is set at run time before calling the method execute. It is not usually part of the serialized state of a RowSet object.

Returns:
the password for making a database connection
See Also:
setPassword(java.lang.String)

setPassword

void setPassword(String password)
                 throws SQLException
Sets the database password for this RowSet object to the given String.

Parameters:
password - the password string
Throws:
SQLException - if a database access error occurs
See Also:
getPassword()

getTransactionIsolation

int getTransactionIsolation()
Retrieves the transaction isolation level set for this RowSet object.

Returns:
the transaction isolation level; one of Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_REPEATABLE_READ, or Connection.TRANSACTION_SERIALIZABLE
See Also:
setTransactionIsolation(int)

setTransactionIsolation

void setTransactionIsolation(int level)
                             throws SQLException
Sets the transaction isolation level for this RowSet obejct.

Parameters:
level - the transaction isolation level; one of Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_REPEATABLE_READ, or Connection.TRANSACTION_SERIALIZABLE
Throws:
SQLException - if a database access error occurs
See Also:
getTransactionIsolation()

getTypeMap

Map<String,Class<?>> getTypeMap()
                                throws SQLException
Retrieves the Map object associated with this RowSet object, which specifies the custom mapping of SQL user-defined types, if any. The default is for the type map to be empty.

Returns:
a java.util.Map object containing the names of SQL user-defined types and the Java classes to which they are to be mapped
Throws:
SQLException - if a database access error occurs
See Also:
setTypeMap(java.util.Map>)

setTypeMap

void setTypeMap(Map<String,Class<?>> map)
                throws SQLException
Installs the given java.util.Map object as the default type map for this RowSet object. This type map will be used unless another type map is supplied as a method parameter.

Parameters:
map - a java.util.Map object containing the names of SQL user-defined types and the Java classes to which they are to be mapped
Throws:
SQLException - if a database access error occurs
See Also:
getTypeMap()

getCommand

String getCommand()
Retrieves this RowSet object's command property. The command property contains a command string, which must be an SQL query, that can be executed to fill the rowset with data. The default value is null.

Returns:
the command string; may be null
See Also:
setCommand(java.lang.String)

setCommand

void setCommand(String cmd)
                throws SQLException
Sets this RowSet object's command property to the given SQL query. This property is optional when a rowset gets its data from a data source that does not support commands, such as a spreadsheet.

Parameters:
cmd - the SQL query that will be used to get the data for this RowSet object; may be null
Throws:
SQLException - if a database access error occurs
See Also:
getCommand()

isReadOnly

boolean isReadOnly()
Retrieves whether this RowSet object is read-only. If updates are possible, the default is for a rowset to be updatable.

Attempts to update a read-only rowset will result in an SQLException being thrown.

Returns:
true if this RowSet object is read-only; false if it is updatable
See Also:
setReadOnly(boolean)

setReadOnly

void setReadOnly(boolean value)
                 throws SQLException
Sets whether this RowSet object is read-only to the given boolean.

Parameters:
value - true if read-only; false if updatable
Throws:
SQLException - if a database access error occurs
See Also:
isReadOnly()

getMaxFieldSize

int getMaxFieldSize()
                    throws SQLException
Retrieves the maximum number of bytes that may be returned for certain column values. This limit applies only to BINARY, VARBINARY, LONGVARBINARYBINARY, CHAR, VARCHAR, LONGVARCHAR, NCHAR and NVARCHAR columns. If the limit is exceeded, the excess data is silently discarded.

Returns:
the current maximum column size limit; zero means that there is no limit
Throws:
SQLException - if a database access error occurs
See Also:
setMaxFieldSize(int)

setMaxFieldSize

void setMaxFieldSize(int max)
                     throws SQLException
Sets the maximum number of bytes that can be returned for a column value to the given number of bytes. This limit applies only to BINARY, VARBINARY, LONGVARBINARYBINARY, CHAR, VARCHAR, LONGVARCHAR, NCHAR and NVARCHAR columns. If the limit is exceeded, the excess data is silently discarded. For maximum portability, use values greater than 256.

Parameters:
max - the new max column size limit in bytes; zero means unlimited
Throws:
SQLException - if a database access error occurs
See Also:
getMaxFieldSize()

getMaxRows

int getMaxRows()
               throws SQLException
Retrieves the maximum number of rows that this RowSet object can contain. If the limit is exceeded, the excess rows are silently dropped.

Returns:
the current maximum number of rows that this RowSet object can contain; zero means unlimited
Throws:
SQLException - if a database access error occurs
See Also:
setMaxRows(int)

setMaxRows

void setMaxRows(int max)
                throws SQLException
Sets the maximum number of rows that this RowSet object can contain to the specified number. If the limit is exceeded, the excess rows are silently dropped.

Parameters:
max - the new maximum number of rows; zero means unlimited
Throws:
SQLException - if a database access error occurs
See Also:
getMaxRows()

getEscapeProcessing

boolean getEscapeProcessing()
                            throws SQLException
Retrieves whether escape processing is enabled for this RowSet object. If escape scanning is enabled, which is the default, the driver will do escape substitution before sending an SQL statement to the database.

Returns:
true if escape processing is enabled; false if it is disabled
Throws:
SQLException - if a database access error occurs
See Also:
setEscapeProcessing(boolean)

setEscapeProcessing

void setEscapeProcessing(boolean enable)
                         throws SQLException
Sets escape processing for this RowSet object on or off. If escape scanning is on (the default), the driver will do escape substitution before sending an SQL statement to the database.

Parameters:
enable - true to enable escape processing; false to disable it
Throws:
SQLException - if a database access error occurs
See Also:
getEscapeProcessing()

getQueryTimeout

int getQueryTimeout()
                    throws SQLException
Retrieves the maximum number of seconds the driver will wait for a statement to execute. If this limit is exceeded, an SQLException is thrown.

Returns:
the current query timeout limit in seconds; zero means unlimited
Throws:
SQLException - if a database access error occurs
See Also:
setQueryTimeout(int)

setQueryTimeout

void setQueryTimeout(int seconds)
                     throws SQLException
Sets the maximum time the driver will wait for a statement to execute to the given number of seconds. If this limit is exceeded, an SQLException is thrown.

Parameters:
seconds - the new query timeout limit in seconds; zero means that there is no limit
Throws:
SQLException - if a database access error occurs
See Also:
getQueryTimeout()

setType

void setType(int type)
             throws SQLException
Sets the type of this RowSet object to the given type. This method is used to change the type of a rowset, which is by default read-only and non-scrollable.

Parameters:
type - one of the ResultSet constants specifying a type: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE
Throws:
SQLException - if a database access error occurs
See Also:
ResultSet.getType()

setConcurrency

void setConcurrency(int concurrency)
                    throws SQLException
Sets the concurrency of this RowSet object to the given concurrency level. This method is used to change the concurrency level of a rowset, which is by default ResultSet.CONCUR_READ_ONLY

Parameters:
concurrency - one of the ResultSet constants specifying a concurrency level: ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE
Throws:
SQLException - if a database access error occurs
See Also:
ResultSet.getConcurrency()

setNull

void setNull(int parameterIndex,
             int sqlType)
             throws SQLException
Sets the designated parameter in this RowSet object's SQL command to SQL NULL.

Note: You must specify the parameter's SQL type.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
sqlType - a SQL type code defined by java.sql.Types
Throws:
SQLException - if a database access error occurs

setNull

void setNull(String parameterName,
             int sqlType)
             throws SQLException
Sets the designated parameter to SQL NULL.

Note: You must specify the parameter's SQL type.

Parameters:
parameterName - the name of the parameter
sqlType - the SQL type code defined in java.sql.Types
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4

setNull

void setNull(int paramIndex,
             int sqlType,
             String typeName)
             throws SQLException
Sets the designated parameter in this RowSet object's SQL command to SQL NULL. This version of the method setNull should be used for SQL user-defined types (UDTs) and REF type parameters. Examples of UDTs include: STRUCT, DISTINCT, JAVA_OBJECT, and named array types.

Note: To be portable, applications must give the SQL type code and the fully qualified SQL type name when specifying a NULL UDT or REF parameter. In the case of a UDT, the name is the type name of the parameter itself. For a REF parameter, the name is the type name of the referenced type. If a JDBC driver does not need the type code or type name information, it may ignore it. Although it is intended for UDT and REF parameters, this method may be used to set a null parameter of any JDBC type. If the parameter does not have a user-defined or REF type, the typeName parameter is ignored.

Parameters:
paramIndex - the first parameter is 1, the second is 2, ...
sqlType - a value from java.sql.Types
typeName - the fully qualified name of an SQL UDT or the type name of the SQL structured type being referenced by a REF type; ignored if the parameter is not a UDT or REF type
Throws:
SQLException - if a database access error occurs

setNull

void setNull(String parameterName,
             int sqlType,
             String typeName)
             throws SQLException
Sets the designated parameter to SQL NULL. This version of the method setNull should be used for user-defined types and REF type parameters. Examples of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and named array types.

Note: To be portable, applications must give the SQL type code and the fully-qualified SQL type name when specifying a NULL user-defined or REF parameter. In the case of a user-defined type the name is the type name of the parameter itself. For a REF parameter, the name is the type name of the referenced type. If a JDBC driver does not need the type code or type name information, it may ignore it. Although it is intended for user-defined and Ref parameters, this method may be used to set a null parameter of any JDBC type. If the parameter does not have a user-defined or REF type, the given typeName is ignored.

Parameters:
parameterName - the name of the parameter
sqlType - a value from java.sql.Types
typeName - the fully-qualified name of an SQL user-defined type; ignored if the parameter is not a user-defined type or SQL REF value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4

setBoolean

void setBoolean(int parameterIndex,
                boolean x)
                throws SQLException
Sets the designated parameter in this RowSet object's command to the given Java boolean value. The driver converts this to an SQL BIT value before sending it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setBoolean

void setBoolean(String parameterName,
                boolean x)
                throws SQLException
Sets the designated parameter to the given Java boolean value. The driver converts this to an SQL BIT or BOOLEAN value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
ResultSet.getBoolean(int)

setByte

void setByte(int parameterIndex,
             byte x)
             throws SQLException
Sets the designated parameter in this RowSet object's command to the given Java byte value. The driver converts this to an SQL TINYINT value before sending it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setByte

void setByte(String parameterName,
             byte x)
             throws SQLException
Sets the designated parameter to the given Java byte value. The driver converts this to an SQL TINYINT value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
ResultSet.getByte(int)

setShort

void setShort(int parameterIndex,
              short x)
              throws SQLException
Sets the designated parameter in this RowSet object's command to the given Java short value. The driver converts this to an SQL SMALLINT value before sending it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setShort

void setShort(String parameterName,
              short x)
              throws SQLException
Sets the designated parameter to the given Java short value. The driver converts this to an SQL SMALLINT value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
ResultSet.getShort(int)

setInt

void setInt(int parameterIndex,
            int x)
            throws SQLException
Sets the designated parameter in this RowSet object's command to the given Java int value. The driver converts this to an SQL INTEGER value before sending it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setInt

void setInt(String parameterName,
            int x)
            throws SQLException
Sets the designated parameter to the given Java int value. The driver converts this to an SQL INTEGER value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
ResultSet.getInt(int)

setLong

void setLong(int parameterIndex,
             long x)
             throws SQLException
Sets the designated parameter in this RowSet object's command to the given Java long value. The driver converts this to an SQL BIGINT value before sending it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setLong

void setLong(String parameterName,
             long x)
             throws SQLException
Sets the designated parameter to the given Java long value. The driver converts this to an SQL BIGINT value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
ResultSet.getLong(int)

setFloat

void setFloat(int parameterIndex,
              float x)
              throws SQLException
Sets the designated parameter in this RowSet object's command to the given Java float value. The driver converts this to an SQL REAL value before sending it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setFloat

void setFloat(String parameterName,
              float x)
              throws SQLException
Sets the designated parameter to the given Java float value. The driver converts this to an SQL FLOAT value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
ResultSet.getFloat(int)

setDouble

void setDouble(int parameterIndex,
               double x)
               throws SQLException
Sets the designated parameter in this RowSet object's command to the given Java double value. The driver converts this to an SQL DOUBLE value before sending it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setDouble

void setDouble(String parameterName,
               double x)
               throws SQLException
Sets the designated parameter to the given Java double value. The driver converts this to an SQL DOUBLE value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
ResultSet.getDouble(int)

setBigDecimal

void setBigDecimal(int parameterIndex,
                   BigDecimal x)
                   throws SQLException
Sets the designated parameter in this RowSet object's command to the given java.math.BigDeciaml value. The driver converts this to an SQL NUMERIC value before sending it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setBigDecimal

void setBigDecimal(String parameterName,
                   BigDecimal x)
                   throws SQLException
Sets the designated parameter to the given java.math.BigDecimal value. The driver converts this to an SQL NUMERIC value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
ResultSet.getBigDecimal(int, int)

setString

void setString(int parameterIndex,
               String x)
               throws SQLException
Sets the designated parameter in this RowSet object's command to the given Java String value. Before sending it to the database, the driver converts this to an SQL VARCHAR or LONGVARCHAR value, depending on the argument's size relative to the driver's limits on VARCHAR values.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setString

void setString(String parameterName,
               String x)
               throws SQLException
Sets the designated parameter to the given Java String value. The driver converts this to an SQL VARCHAR or LONGVARCHAR value (depending on the argument's size relative to the driver's limits on VARCHAR values) when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
ResultSet.getString(int)

setBytes

void setBytes(int parameterIndex,
              byte[] x)
              throws SQLException
Sets the designated parameter in this RowSet object's command to the given Java array of byte values. Before sending it to the database, the driver converts this to an SQL VARBINARY or LONGVARBINARY value, depending on the argument's size relative to the driver's limits on VARBINARY values.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setBytes

void setBytes(String parameterName,
              byte[] x)
              throws SQLException
Sets the designated parameter to the given Java array of bytes. The driver converts this to an SQL VARBINARY or LONGVARBINARY (depending on the argument's size relative to the driver's limits on VARBINARY values) when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
ResultSet.getBytes(int)

setDate

void setDate(int parameterIndex,
             Date x)
             throws SQLException
Sets the designated parameter in this RowSet object's command to the given java.sql.Date value. The driver converts this to an SQL DATE value before sending it to the database, using the default java.util.Calendar to calculate the date.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setTime

void setTime(int parameterIndex,
             Time x)
             throws SQLException
Sets the designated parameter in this RowSet object's command to the given java.sql.Time value. The driver converts this to an SQL TIME value before sending it to the database, using the default java.util.Calendar to calculate it.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setTimestamp

void setTimestamp(int parameterIndex,
                  Timestamp x)
                  throws SQLException
Sets the designated parameter in this RowSet object's command to the given java.sql.Timestamp value. The driver converts this to an SQL TIMESTAMP value before sending it to the database, using the default java.util.Calendar to calculate it.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs

setTimestamp

void setTimestamp(String parameterName,
                  Timestamp x)
                  throws SQLException
Sets the designated parameter to the given java.sql.Timestamp value. The driver converts this to an SQL TIMESTAMP value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
ResultSet.getTimestamp(int)

setAsciiStream

void setAsciiStream(int parameterIndex,
                    InputStream x,
                    int length)
                    throws SQLException
Sets the designated parameter in this RowSet object's command to the given java.io.InputStream value. It may be more practical to send a very large ASCII value via a java.io.InputStream rather than as a LONGVARCHAR parameter. The driver will read the data from the stream as needed until it reaches end-of-file.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the Java input stream that contains the ASCII parameter value
length - the number of bytes in the stream
Throws:
SQLException - if a database access error occurs

setAsciiStream

void setAsciiStream(String parameterName,
                    InputStream x,
                    int length)
                    throws SQLException
Sets the designated parameter to the given input stream, which will have the specified number of bytes. When a very large ASCII value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream. Data will be read from the stream as needed until end-of-file is reached. The JDBC driver will do any necessary conversion from ASCII to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Parameters:
parameterName - the name of the parameter
x - the Java input stream that contains the ASCII parameter value
length - the number of bytes in the stream
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4

setBinaryStream

void setBinaryStream(int parameterIndex,
                     InputStream x,
                     int length)
                     throws SQLException
Sets the designated parameter in this RowSet object's command to the given java.io.InputStream value. It may be more practical to send a very large binary value via a java.io.InputStream rather than as a LONGVARBINARY parameter. The driver will read the data from the stream as needed until it reaches end-of-file.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the java input stream which contains the binary parameter value
length - the number of bytes in the stream
Throws:
SQLException - if a database access error occurs

setBinaryStream

void setBinaryStream(String parameterName,
                     InputStream x,
                     int length)
                     throws SQLException
Sets the designated parameter to the given input stream, which will have the specified number of bytes. When a very large binary value is input to a LONGVARBINARY parameter, it may be more practical to send it via a java.io.InputStream object. The data will be read from the stream as needed until end-of-file is reached.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Parameters:
parameterName - the name of the parameter
x - the java input stream which contains the binary parameter value
length - the number of bytes in the stream
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4

setCharacterStream

void setCharacterStream(int parameterIndex,
                        Reader reader,
                        int length)
                        throws SQLException
Sets the designated parameter in this RowSet object's command to the given java.io.Reader value. It may be more practical to send a very large UNICODE value via a java.io.Reader rather than as a LONGVARCHAR parameter. The driver will read the data from the stream as needed until it reaches end-of-file.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
reader - the Reader object that contains the UNICODE data to be set
length - the number of characters in the stream
Throws:
SQLException - if a database access error occurs

setCharacterStream

void setCharacterStream(String parameterName,
                        Reader reader,
                        int length)
                        throws SQLException
Sets the designated parameter to the given Reader object, which is the given number of characters long. When a very large UNICODE value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.Reader object. The data will be read from the stream as needed until end-of-file is reached. The JDBC driver will do any necessary conversion from UNICODE to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Parameters:
parameterName - the name of the parameter
reader - the java.io.Reader object that contains the UNICODE data used as the designated parameter
length - the number of characters in the stream
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4

setAsciiStream

void setAsciiStream(int parameterIndex,
                    InputStream x)
                    throws SQLException
Sets the designated parameter in this RowSet object's command to the given input stream. When a very large ASCII value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream. Data will be read from the stream as needed until end-of-file is reached. The JDBC driver will do any necessary conversion from ASCII to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setAsciiStream which takes a length parameter.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the Java input stream that contains the ASCII parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed PreparedStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setAsciiStream

void setAsciiStream(String parameterName,
                    InputStream x)
                    throws SQLException
Sets the designated parameter to the given input stream. When a very large ASCII value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream. Data will be read from the stream as needed until end-of-file is reached. The JDBC driver will do any necessary conversion from ASCII to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setAsciiStream which takes a length parameter.

Parameters:
parameterName - the name of the parameter
x - the Java input stream that contains the ASCII parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setBinaryStream

void setBinaryStream(int parameterIndex,
                     InputStream x)
                     throws SQLException
Sets the designated parameter in this RowSet object's command to the given input stream. When a very large binary value is input to a LONGVARBINARY parameter, it may be more practical to send it via a java.io.InputStream object. The data will be read from the stream as needed until end-of-file is reached.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setBinaryStream which takes a length parameter.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the java input stream which contains the binary parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed PreparedStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setBinaryStream

void setBinaryStream(String parameterName,
                     InputStream x)
                     throws SQLException
Sets the designated parameter to the given input stream. When a very large binary value is input to a LONGVARBINARY parameter, it may be more practical to send it via a java.io.InputStream object. The data will be read from the stream as needed until end-of-file is reached.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setBinaryStream which takes a length parameter.

Parameters:
parameterName - the name of the parameter
x - the java input stream which contains the binary parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setCharacterStream

void setCharacterStream(int parameterIndex,
                        Reader reader)
                        throws SQLException
Sets the designated parameter in this RowSet object's command to the given Reader object. When a very large UNICODE value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.Reader object. The data will be read from the stream as needed until end-of-file is reached. The JDBC driver will do any necessary conversion from UNICODE to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setCharacterStream which takes a length parameter.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
reader - the java.io.Reader object that contains the Unicode data
Throws:
SQLException - if a database access error occurs or this method is called on a closed PreparedStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setCharacterStream

void setCharacterStream(String parameterName,
                        Reader reader)
                        throws SQLException
Sets the designated parameter to the given Reader object. When a very large UNICODE value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.Reader object. The data will be read from the stream as needed until end-of-file is reached. The JDBC driver will do any necessary conversion from UNICODE to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setCharacterStream which takes a length parameter.

Parameters:
parameterName - the name of the parameter
reader - the java.io.Reader object that contains the Unicode data
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setNCharacterStream

void setNCharacterStream(int parameterIndex,
                         Reader value)
                         throws SQLException
Sets the designated parameter in this RowSet object's command to a Reader object. The Reader reads the data till end-of-file is reached. The driver does the necessary conversion from Java character format to the national character set in the database.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setNCharacterStream which takes a length parameter.

Parameters:
parameterIndex - of the first parameter is 1, the second is 2, ...
value - the parameter value
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur ; if a database access error occurs; or this method is called on a closed PreparedStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setObject

void setObject(int parameterIndex,
               Object x,
               int targetSqlType,
               int scaleOrLength)
               throws SQLException
Sets the designated parameter in this RowSet object's command with the given Java Object. For integral values, the java.lang equivalent objects should be used (for example, an instance of the class Integer for an int). If the second argument is an InputStream then the stream must contain the number of bytes specified by scaleOrLength. If the second argument is a Reader then the reader must contain the number of characters specified * by scaleOrLength. If these conditions are not true the driver will generate a SQLException when the prepared statement is executed.

The given Java object will be converted to the targetSqlType before being sent to the database.

If the object is of a class implementing SQLData, the rowset should call the method SQLData.writeSQL to write the object to an SQLOutput data stream. If, on the other hand, the object is of a class implementing Ref, Blob, Clob, NClob, Struct, java.net.URL, or Array, the driver should pass it to the database as a value of the corresponding SQL type.

Note that this method may be used to pass datatabase-specific abstract data types.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the object containing the input parameter value
targetSqlType - the SQL type (as defined in java.sql.Types) to be sent to the database. The scale argument may further qualify this type.
scaleOrLength - for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types, this is the number of digits after the decimal point. For Java Object types InputStream and Reader, this is the length of the data in the stream or reader. For all other types, this value will be ignored.
Throws:
SQLException - if a database access error occurs
See Also:
Types

setObject

void setObject(String parameterName,
               Object x,
               int targetSqlType,
               int scale)
               throws SQLException
Sets the value of the designated parameter with the given object. The second argument must be an object type; for integral values, the java.lang equivalent objects should be used.

The given Java object will be converted to the given targetSqlType before being sent to the database. If the object has a custom mapping (is of a class implementing the interface SQLData), the JDBC driver should call the method SQLData.writeSQL to write it to the SQL data stream. If, on the other hand, the object is of a class implementing Ref, Blob, Clob, NClob, Struct, java.net.URL, or Array, the driver should pass it to the database as a value of the corresponding SQL type.

Note that this method may be used to pass datatabase- specific abstract data types.

Parameters:
parameterName - the name of the parameter
x - the object containing the input parameter value
targetSqlType - the SQL type (as defined in java.sql.Types) to be sent to the database. The scale argument may further qualify this type.
scale - for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types, this is the number of digits after the decimal point. For all other types, this value will be ignored.
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if targetSqlType is a ARRAY, BLOB, CLOB, DATALINK, JAVA_OBJECT, NCHAR, NCLOB, NVARCHAR, LONGNVARCHAR, REF, ROWID, SQLXML or STRUCT data type and the JDBC driver does not support this data type
Since:
1.4
See Also:
Types, ResultSet.getObject(int)

setObject

void setObject(int parameterIndex,
               Object x,
               int targetSqlType)
               throws SQLException
Sets the designated parameter in this RowSet object's command with a Java Object. For integral values, the java.lang equivalent objects should be used. This method is like setObject above, but the scale used is the scale of the second parameter. Scalar values have a scale of zero. Literal values have the scale present in the literal.

Even though it is supported, it is not recommended that this method be called with floating point input values.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the object containing the input parameter value
targetSqlType - the SQL type (as defined in java.sql.Types) to be sent to the database
Throws:
SQLException - if a database access error occurs

setObject

void setObject(String parameterName,
               Object x,
               int targetSqlType)
               throws SQLException
Sets the value of the designated parameter with the given object. This method is like the method setObject above, except that it assumes a scale of zero.

Parameters:
parameterName - the name of the parameter
x - the object containing the input parameter value
targetSqlType - the SQL type (as defined in java.sql.Types) to be sent to the database
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if targetSqlType is a ARRAY, BLOB, CLOB, DATALINK, JAVA_OBJECT, NCHAR, NCLOB, NVARCHAR, LONGNVARCHAR, REF, ROWID, SQLXML or STRUCT data type and the JDBC driver does not support this data type
Since:
1.4
See Also:
ResultSet.getObject(int)

setObject

void setObject(String parameterName,
               Object x)
               throws SQLException
Sets the value of the designated parameter with the given object. The second parameter must be of type Object; therefore, the java.lang equivalent objects should be used for built-in types.

The JDBC specification specifies a standard mapping from Java Object types to SQL types. The given argument will be converted to the corresponding SQL type before being sent to the database.

Note that this method may be used to pass datatabase- specific abstract data types, by using a driver-specific Java type. If the object is of a class implementing the interface SQLData, the JDBC driver should call the method SQLData.writeSQL to write it to the SQL data stream. If, on the other hand, the object is of a class implementing Ref, Blob, Clob, NClob, Struct, java.net.URL, or Array, the driver should pass it to the database as a value of the corresponding SQL type.

This method throws an exception if there is an ambiguity, for example, if the object is of a class implementing more than one of the interfaces named above.

Parameters:
parameterName - the name of the parameter
x - the object containing the input parameter value
Throws:
SQLException - if a database access error occurs, this method is called on a closed CallableStatement or if the given Object parameter is ambiguous
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
ResultSet.getObject(int)

setObject

void setObject(int parameterIndex,
               Object x)
               throws SQLException
Sets the designated parameter in this RowSet object's command with a Java Object. For integral values, the java.lang equivalent objects should be used.

The JDBC specification provides a standard mapping from Java Object types to SQL types. The driver will convert the given Java object to its standard SQL mapping before sending it to the database.

Note that this method may be used to pass datatabase-specific abstract data types by using a driver-specific Java type. If the object is of a class implementing SQLData, the rowset should call the method SQLData.writeSQL to write the object to an SQLOutput data stream. If, on the other hand, the object is of a class implementing Ref, Blob, Clob, NClob, Struct, java.net.URL, or Array, the driver should pass it to the database as a value of the corresponding SQL type.

An exception is thrown if there is an ambiguity, for example, if the object is of a class implementing more than one of these interfaces.

Parameters:
parameterIndex - The first parameter is 1, the second is 2, ...
x - The object containing the input parameter value
Throws:
SQLException - if a database access error occurs

setRef

void setRef(int i,
            Ref x)
            throws SQLException
Sets the designated parameter in this RowSet object's command with the given Ref value. The driver will convert this to the appropriate REF(<structured-type>) value.

Parameters:
i - the first parameter is 1, the second is 2, ...
x - an object representing data of an SQL REF type
Throws:
SQLException - if a database access error occurs

setBlob

void setBlob(int i,
             Blob x)
             throws SQLException
Sets the designated parameter in this RowSet object's command with the given Blob value. The driver will convert this to the BLOB value that the Blob object represents before sending it to the database.

Parameters:
i - the first parameter is 1, the second is 2, ...
x - an object representing a BLOB
Throws:
SQLException - if a database access error occurs

setBlob

void setBlob(int parameterIndex,
             InputStream inputStream,
             long length)
             throws SQLException
Sets the designated parameter to a InputStream object. The inputstream must contain the number of characters specified by length otherwise a SQLException will be generated when the PreparedStatement is executed. This method differs from the setBinaryStream (int, InputStream, int) method because it informs the driver that the parameter value should be sent to the server as a BLOB. When the setBinaryStream method is used, the driver may have to do extra work to determine whether the parameter data should be sent to the server as a LONGVARBINARY or a BLOB

Parameters:
parameterIndex - index of the first parameter is 1, the second is 2, ...
inputStream - An object that contains the data to set the parameter value to.
length - the number of bytes in the parameter data.
Throws:
SQLException - if a database access error occurs, this method is called on a closed PreparedStatement, if parameterIndex does not correspond to a parameter marker in the SQL statement, if the length specified is less than zero or if the number of bytes in the inputstream does not match the specfied length.
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setBlob

void setBlob(int parameterIndex,
             InputStream inputStream)
             throws SQLException
Sets the designated parameter to a InputStream object. This method differs from the setBinaryStream (int, InputStream) method because it informs the driver that the parameter value should be sent to the server as a BLOB. When the setBinaryStream method is used, the driver may have to do extra work to determine whether the parameter data should be sent to the server as a LONGVARBINARY or a BLOB

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setBlob which takes a length parameter.

Parameters:
parameterIndex - index of the first parameter is 1, the second is 2, ...
inputStream - An object that contains the data to set the parameter value to.
Throws:
SQLException - if a database access error occurs, this method is called on a closed PreparedStatement or if parameterIndex does not correspond to a parameter marker in the SQL statement,
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setBlob

void setBlob(String parameterName,
             InputStream inputStream,
             long length)
             throws SQLException
Sets the designated parameter to a InputStream object. The inputstream must contain the number of characters specified by length, otherwise a SQLException will be generated when the CallableStatement is executed. This method differs from the setBinaryStream (int, InputStream, int) method because it informs the driver that the parameter value should be sent to the server as a BLOB. When the setBinaryStream method is used, the driver may have to do extra work to determine whether the parameter data should be sent to the server as a LONGVARBINARY or a BLOB

Parameters:
parameterName - the name of the parameter to be set the second is 2, ...
inputStream - An object that contains the data to set the parameter value to.
length - the number of bytes in the parameter data.
Throws:
SQLException - if parameterIndex does not correspond to a parameter marker in the SQL statement, or if the length specified is less than zero; if the number of bytes in the inputstream does not match the specfied length; if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setBlob

void setBlob(String parameterName,
             Blob x)
             throws SQLException
Sets the designated parameter to the given java.sql.Blob object. The driver converts this to an SQL BLOB value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - a Blob object that maps an SQL BLOB value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setBlob

void setBlob(String parameterName,
             InputStream inputStream)
             throws SQLException
Sets the designated parameter to a InputStream object. This method differs from the setBinaryStream (int, InputStream) method because it informs the driver that the parameter value should be sent to the server as a BLOB. When the setBinaryStream method is used, the driver may have to do extra work to determine whether the parameter data should be send to the server as a LONGVARBINARY or a BLOB

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setBlob which takes a length parameter.

Parameters:
parameterName - the name of the parameter
inputStream - An object that contains the data to set the parameter value to.
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setClob

void setClob(int i,
             Clob x)
             throws SQLException
Sets the designated parameter in this RowSet object's command with the given Clob value. The driver will convert this to the CLOB value that the Clob object represents before sending it to the database.

Parameters:
i - the first parameter is 1, the second is 2, ...
x - an object representing a CLOB
Throws:
SQLException - if a database access error occurs

setClob

void setClob(int parameterIndex,
             Reader reader,
             long length)
             throws SQLException
Sets the designated parameter to a Reader object. The reader must contain the number of characters specified by length otherwise a SQLException will be generated when the PreparedStatement is executed. This method differs from the setCharacterStream (int, Reader, int) method because it informs the driver that the parameter value should be sent to the server as a CLOB. When the setCharacterStream method is used, the driver may have to do extra work to determine whether the parameter data should be sent to the server as a LONGVARCHAR or a CLOB

Parameters:
parameterIndex - index of the first parameter is 1, the second is 2, ...
reader - An object that contains the data to set the parameter value to.
length - the number of characters in the parameter data.
Throws:
SQLException - if a database access error occurs, this method is called on a closed PreparedStatement, if parameterIndex does not correspond to a parameter marker in the SQL statement, or if the length specified is less than zero.
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setClob

void setClob(int parameterIndex,
             Reader reader)
             throws SQLException
Sets the designated parameter to a Reader object. This method differs from the setCharacterStream (int, Reader) method because it informs the driver that the parameter value should be sent to the server as a CLOB. When the setCharacterStream method is used, the driver may have to do extra work to determine whether the parameter data should be sent to the server as a LONGVARCHAR or a CLOB

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setClob which takes a length parameter.

Parameters:
parameterIndex - index of the first parameter is 1, the second is 2, ...
reader - An object that contains the data to set the parameter value to.
Throws:
SQLException - if a database access error occurs, this method is called on a closed PreparedStatementor if parameterIndex does not correspond to a parameter marker in the SQL statement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setClob

void setClob(String parameterName,
             Reader reader,
             long length)
             throws SQLException
Sets the designated parameter to a Reader object. The reader must contain the number of characters specified by length otherwise a SQLException will be generated when the CallableStatement is executed. This method differs from the setCharacterStream (int, Reader, int) method because it informs the driver that the parameter value should be sent to the server as a CLOB. When the setCharacterStream method is used, the driver may have to do extra work to determine whether the parameter data should be send to the server as a LONGVARCHAR or a CLOB

Parameters:
parameterName - the name of the parameter to be set
reader - An object that contains the data to set the parameter value to.
length - the number of characters in the parameter data.
Throws:
SQLException - if parameterIndex does not correspond to a parameter marker in the SQL statement; if the length specified is less than zero; a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setClob

void setClob(String parameterName,
             Clob x)
             throws SQLException
Sets the designated parameter to the given java.sql.Clob object. The driver converts this to an SQL CLOB value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - a Clob object that maps an SQL CLOB value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setClob

void setClob(String parameterName,
             Reader reader)
             throws SQLException
Sets the designated parameter to a Reader object. This method differs from the setCharacterStream (int, Reader) method because it informs the driver that the parameter value should be sent to the server as a CLOB. When the setCharacterStream method is used, the driver may have to do extra work to determine whether the parameter data should be send to the server as a LONGVARCHAR or a CLOB

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setClob which takes a length parameter.

Parameters:
parameterName - the name of the parameter
reader - An object that contains the data to set the parameter value to.
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setArray

void setArray(int i,
              Array x)
              throws SQLException
Sets the designated parameter in this RowSet object's command with the given Array value. The driver will convert this to the ARRAY value that the Array object represents before sending it to the database.

Parameters:
i - the first parameter is 1, the second is 2, ...
x - an object representing an SQL array
Throws:
SQLException - if a database access error occurs

setDate

void setDate(int parameterIndex,
             Date x,
             Calendar cal)
             throws SQLException
Sets the designated parameter in this RowSet object's command with the given java.sql.Date value. The driver will convert this to an SQL DATE value, using the given java.util.Calendar object to calculate the date.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
cal - the java.util.Calendar object to use for calculating the date
Throws:
SQLException - if a database access error occurs

setDate

void setDate(String parameterName,
             Date x)
             throws SQLException
Sets the designated parameter to the given java.sql.Date value using the default time zone of the virtual machine that is running the application. The driver converts this to an SQL DATE value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
ResultSet.getDate(int)

setDate

void setDate(String parameterName,
             Date x,
             Calendar cal)
             throws SQLException
Sets the designated parameter to the given java.sql.Date value, using the given Calendar object. The driver uses the Calendar object to construct an SQL DATE value, which the driver then sends to the database. With a a Calendar object, the driver can calculate the date taking into account a custom timezone. If no Calendar object is specified, the driver uses the default timezone, which is that of the virtual machine running the application.

Parameters:
parameterName - the name of the parameter
x - the parameter value
cal - the Calendar object the driver will use to construct the date
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
ResultSet.getDate(int)

setTime

void setTime(int parameterIndex,
             Time x,
             Calendar cal)
             throws SQLException
Sets the designated parameter in this RowSet object's command with the given java.sql.Time value. The driver will convert this to an SQL TIME value, using the given java.util.Calendar object to calculate it, before sending it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
cal - the java.util.Calendar object to use for calculating the time
Throws:
SQLException - if a database access error occurs

setTime

void setTime(String parameterName,
             Time x)
             throws SQLException
Sets the designated parameter to the given java.sql.Time value. The driver converts this to an SQL TIME value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
ResultSet.getTime(int)

setTime

void setTime(String parameterName,
             Time x,
             Calendar cal)
             throws SQLException
Sets the designated parameter to the given java.sql.Time value, using the given Calendar object. The driver uses the Calendar object to construct an SQL TIME value, which the driver then sends to the database. With a a Calendar object, the driver can calculate the time taking into account a custom timezone. If no Calendar object is specified, the driver uses the default timezone, which is that of the virtual machine running the application.

Parameters:
parameterName - the name of the parameter
x - the parameter value
cal - the Calendar object the driver will use to construct the time
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
ResultSet.getTime(int)

setTimestamp

void setTimestamp(int parameterIndex,
                  Timestamp x,
                  Calendar cal)
                  throws SQLException
Sets the designated parameter in this RowSet object's command with the given java.sql.Timestamp value. The driver will convert this to an SQL TIMESTAMP value, using the given java.util.Calendar object to calculate it, before sending it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
cal - the java.util.Calendar object to use for calculating the timestamp
Throws:
SQLException - if a database access error occurs

setTimestamp

void setTimestamp(String parameterName,
                  Timestamp x,
                  Calendar cal)
                  throws SQLException
Sets the designated parameter to the given java.sql.Timestamp value, using the given Calendar object. The driver uses the Calendar object to construct an SQL TIMESTAMP value, which the driver then sends to the database. With a a Calendar object, the driver can calculate the timestamp taking into account a custom timezone. If no Calendar object is specified, the driver uses the default timezone, which is that of the virtual machine running the application.

Parameters:
parameterName - the name of the parameter
x - the parameter value
cal - the Calendar object the driver will use to construct the timestamp
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
ResultSet.getTimestamp(int)

clearParameters

void clearParameters()
                     throws SQLException
Clears the parameters set for this RowSet object's command.

In general, parameter values remain in force for repeated use of a RowSet object. Setting a parameter value automatically clears its previous value. However, in some cases it is useful to immediately release the resources used by the current parameter values, which can be done by calling the method clearParameters.

Throws:
SQLException - if a database access error occurs

execute

void execute()
             throws SQLException
Fills this RowSet object with data.

The execute method may use the following properties to create a connection for reading data: url, data source name, user name, password, transaction isolation, and type map. The execute method may use the following properties to create a statement to execute a command: command, read only, maximum field size, maximum rows, escape processing, and query timeout.

If the required properties have not been set, an exception is thrown. If this method is successful, the current contents of the rowset are discarded and the rowset's metadata is also (re)set. If there are outstanding updates, they are ignored.

If this RowSet object does not maintain a continuous connection with its source of data, it may use a reader (a RowSetReader object) to fill itself with data. In this case, a reader will have been registered with this RowSet object, and the method execute will call on the reader's readData method as part of its implementation.

Throws:
SQLException - if a database access error occurs or any of the properties necessary for making a connection and creating a statement have not been set

addRowSetListener

void addRowSetListener(RowSetListener listener)
Registers the given listener so that it will be notified of events that occur on this RowSet object.

Parameters:
listener - a component that has implemented the RowSetListener interface and wants to be notified when events occur on this RowSet object
See Also:
removeRowSetListener(javax.sql.RowSetListener)

removeRowSetListener

void removeRowSetListener(RowSetListener listener)
Removes the specified listener from the list of components that will be notified when an event occurs on this RowSet object.

Parameters:
listener - a component that has been registered as a listener for this RowSet object
See Also:
addRowSetListener(javax.sql.RowSetListener)

setSQLXML

void setSQLXML(int parameterIndex,
               SQLXML xmlObject)
               throws SQLException
Sets the designated parameter to the given java.sql.SQLXML object. The driver converts this to an SQL XML value when it sends it to the database.

Parameters:
parameterIndex - index of the first parameter is 1, the second is 2, ...
xmlObject - a SQLXML object that maps an SQL XML value
Throws:
SQLException - if a database access error occurs, this method is called on a closed result set, the java.xml.transform.Result, Writer or OutputStream has not been closed for the SQLXML object or if there is an error processing the XML value. The getCause method of the exception may provide a more detailed exception, for example, if the stream does not contain valid XML.
Since:
1.6

setSQLXML

void setSQLXML(String parameterName,
               SQLXML xmlObject)
               throws SQLException
Sets the designated parameter to the given java.sql.SQLXML object. The driver converts this to an SQL XML value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
xmlObject - a SQLXML object that maps an SQL XML value
Throws:
SQLException - if a database access error occurs, this method is called on a closed result set, the java.xml.transform.Result, Writer or OutputStream has not been closed for the SQLXML object or if there is an error processing the XML value. The getCause method of the exception may provide a more detailed exception, for example, if the stream does not contain valid XML.
Since:
1.6

setRowId

void setRowId(int parameterIndex,
              RowId x)
              throws SQLException
Sets the designated parameter to the given java.sql.RowId object. The driver converts this to a SQL ROWID value when it sends it to the database

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs
Since:
1.6

setRowId

void setRowId(String parameterName,
              RowId x)
              throws SQLException
Sets the designated parameter to the given java.sql.RowId object. The driver converts this to a SQL ROWID when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs
Since:
1.6

setNString

void setNString(int parameterIndex,
                String value)
                throws SQLException
Sets the designated paramter to the given String object. The driver converts this to a SQL NCHAR or NVARCHAR or LONGNVARCHAR value (depending on the argument's size relative to the driver's limits on NVARCHAR values) when it sends it to the database.

Parameters:
parameterIndex - of the first parameter is 1, the second is 2, ...
value - the parameter value
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur ; or if a database access error occurs
Since:
1.6

setNString

void setNString(String parameterName,
                String value)
                throws SQLException
Sets the designated paramter to the given String object. The driver converts this to a SQL NCHAR or NVARCHAR or LONGNVARCHAR

Parameters:
parameterName - the name of the column to be set
value - the parameter value
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur; or if a database access error occurs
Since:
1.6

setNCharacterStream

void setNCharacterStream(int parameterIndex,
                         Reader value,
                         long length)
                         throws SQLException
Sets the designated parameter to a Reader object. The Reader reads the data till end-of-file is reached. The driver does the necessary conversion from Java character format to the national character set in the database.

Parameters:
parameterIndex - of the first parameter is 1, the second is 2, ...
value - the parameter value
length - the number of characters in the parameter data.
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur ; or if a database access error occurs
Since:
1.6

setNCharacterStream

void setNCharacterStream(String parameterName,
                         Reader value,
                         long length)
                         throws SQLException
Sets the designated parameter to a Reader object. The Reader reads the data till end-of-file is reached. The driver does the necessary conversion from Java character format to the national character set in the database.

Parameters:
parameterName - the name of the column to be set
value - the parameter value
length - the number of characters in the parameter data.
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur; or if a database access error occurs
Since:
1.6

setNCharacterStream

void setNCharacterStream(String parameterName,
                         Reader value)
                         throws SQLException
Sets the designated parameter to a Reader object. The Reader reads the data till end-of-file is reached. The driver does the necessary conversion from Java character format to the national character set in the database.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setNCharacterStream which takes a length parameter.

Parameters:
parameterName - the name of the parameter
value - the parameter value
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur ; if a database access error occurs; or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setNClob

void setNClob(String parameterName,
              NClob value)
              throws SQLException
Sets the designated parameter to a java.sql.NClob object. The object implements the java.sql.NClob interface. This NClob object maps to a SQL NCLOB.

Parameters:
parameterName - the name of the column to be set
value - the parameter value
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur; or if a database access error occurs
Since:
1.6

setNClob

void setNClob(String parameterName,
              Reader reader,
              long length)
              throws SQLException
Sets the designated parameter to a Reader object. The reader must contain the number of characters specified by length otherwise a SQLException will be generated when the CallableStatement is executed. This method differs from the setCharacterStream (int, Reader, int) method because it informs the driver that the parameter value should be sent to the server as a NCLOB. When the setCharacterStream method is used, the driver may have to do extra work to determine whether the parameter data should be send to the server as a LONGNVARCHAR or a NCLOB

Parameters:
parameterName - the name of the parameter to be set
reader - An object that contains the data to set the parameter value to.
length - the number of characters in the parameter data.
Throws:
SQLException - if parameterIndex does not correspond to a parameter marker in the SQL statement; if the length specified is less than zero; if the driver does not support national character sets; if the driver can detect that a data conversion error could occur; if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setNClob

void setNClob(String parameterName,
              Reader reader)
              throws SQLException
Sets the designated parameter to a Reader object. This method differs from the setCharacterStream (int, Reader) method because it informs the driver that the parameter value should be sent to the server as a NCLOB. When the setCharacterStream method is used, the driver may have to do extra work to determine whether the parameter data should be send to the server as a LONGNVARCHAR or a NCLOB

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setNClob which takes a length parameter.

Parameters:
parameterName - the name of the parameter
reader - An object that contains the data to set the parameter value to.
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur; if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setNClob

void setNClob(int parameterIndex,
              Reader reader,
              long length)
              throws SQLException
Sets the designated parameter to a Reader object. The reader must contain the number of characters specified by length otherwise a SQLException will be generated when the PreparedStatement is executed. This method differs from the setCharacterStream (int, Reader, int) method because it informs the driver that the parameter value should be sent to the server as a NCLOB. When the setCharacterStream method is used, the driver may have to do extra work to determine whether the parameter data should be sent to the server as a LONGNVARCHAR or a NCLOB

Parameters:
parameterIndex - index of the first parameter is 1, the second is 2, ...
reader - An object that contains the data to set the parameter value to.
length - the number of characters in the parameter data.
Throws:
SQLException - if parameterIndex does not correspond to a parameter marker in the SQL statement; if the length specified is less than zero; if the driver does not support national character sets; if the driver can detect that a data conversion error could occur; if a database access error occurs or this method is called on a closed PreparedStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setNClob

void setNClob(int parameterIndex,
              NClob value)
              throws SQLException
Sets the designated parameter to a java.sql.NClob object. The driver converts this to a SQL NCLOB value when it sends it to the database.

Parameters:
parameterIndex - of the first parameter is 1, the second is 2, ...
value - the parameter value
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur ; or if a database access error occurs
Since:
1.6

setNClob

void setNClob(int parameterIndex,
              Reader reader)
              throws SQLException
Sets the designated parameter to a Reader object. This method differs from the setCharacterStream (int, Reader) method because it informs the driver that the parameter value should be sent to the server as a NCLOB. When the setCharacterStream method is used, the driver may have to do extra work to determine whether the parameter data should be sent to the server as a LONGNVARCHAR or a NCLOB

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setNClob which takes a length parameter.

Parameters:
parameterIndex - index of the first parameter is 1, the second is 2, ...
reader - An object that contains the data to set the parameter value to.
Throws:
SQLException - if parameterIndex does not correspond to a parameter marker in the SQL statement; if the driver does not support national character sets; if the driver can detect that a data conversion error could occur; if a database access error occurs or this method is called on a closed PreparedStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setURL

void setURL(int parameterIndex,
            URL x)
            throws SQLException
Sets the designated parameter to the given java.net.URL value. The driver converts this to an SQL DATALINK value when it sends it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the java.net.URL object to be set
Throws:
SQLException - if a database access error occurs or this method is called on a closed PreparedStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


rowset

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.sql.rowset

Standard interfaces and base classes for JDBC RowSet implementations.

See:
Description

Interface Summary
CachedRowSet | The interface that all standard implementations of CachedRowSet must implement.
FilteredRowSet | The standard interface that all standard implementations of FilteredRowSet must implement.
JdbcRowSet | The standard interface that all standard implementations of JdbcRowSet must implement.
Joinable | 1.0 Background
JoinRowSet | The JoinRowSet interface provides a mechanism for combining related data from different RowSet objects into one JoinRowSet object, which represents an SQL JOIN.
Predicate | The standard interface that provides the framework for all FilteredRowSet objects to describe their filters.
WebRowSet | The standard interface that all implementations of a WebRowSet must implement.

Class Summary
BaseRowSet | An abstract class providing a RowSet object with its basic functionality.
RowSetMetaDataImpl | Provides implementations for the methods that set and get metadata information about a RowSet object's columns.

Exception Summary
RowSetWarning An extension of SQLException that provides information about database warnings set on RowSet objects.

Package javax.sql.rowset Description

Standard interfaces and base classes for JDBC RowSet implementations. This package contains interfaces and classes that a standard RowSet implementation either implements or extends.

Table of Contents

  • 1.0 Package Specification
  • 2.0 Standard RowSet Definitions
  • 3.0 Implementater's Guide
  • 4.0 Related Specifications
  • 5.0 Related Documentation

1.0 Package Specification

This package specifies five standard JDBC RowSet interfaces. All five extend the RowSet interface described in the JDBC 3.0 specification. It is anticipated that additional definitions of more specialized JDBC RowSet types will emerge as this technology matures. Future definitions should be specified as subinterfaces using inheritance similar to the way it is used in this specification.

Note: The interface definitions provided in this package form the basis for all compliant JDBC RowSet implementations. Vendors and more advanced developers who intend to provide their own compliant RowSet implementations should pay particular attention to the assertions detailed in specification interfaces.

2.0 Standard RowSet Definitions

  • JdbcRowSet - A wrapper around a ResultSet object that makes it possible to use the result set as a JavaBeansTM component. Thus, a JdbcRowSet object can be a Bean that any tool makes available for assembling an application as part of a component based architecture . A JdbcRowSet object is a connected RowSet object, that is, it must continually maintain its connection to its data source using a JDBC technology-enabled driver ("JDBC driver"). In addition, a JdbcRowSet object provides a fully updatable and scrollable tabular data structure as defined in the JDBC 3.0 specification.

  • CachedRowSetTM> - A CachedRowSet object is a JavaBeansTM component that is scrollable, updatable, serializable, and generally disconnected from the source of its data. A CachedRowSet object typically contains rows from a result set, but it can also contain rows from any file with a tabular format, such as a spreadsheet. CachedRowSet implementations must use the SyncFactory to manage and obtain pluggable SyncProvider objects to provide synchronization between the disconnected RowSet object and the originating data source. Typically a SyncProvider implementation relies upon a JDBC driver to obtain connectivity to a particular data source. Further details on this mechanism are discussed in the javax.sql.rowset.spi package specification.

  • WebRowSet - A WebRowSet object is an extension of CachedRowSet that can read and write a RowSet object in a well formed XML format. This class calls an XmlReader object (an extension of the RowSetReader interface) to read a rowset in XML format. It calls an XmlWriter object (an extension of the RowSetWriter interface) to write a rowset in XML format. The reader and writer required by WebRowSet objects are provided by the SyncFactory in the form of SyncProvider implementations. In order to ensure well formed XML usage, a standard generic XML Schema is defined and published at http://java.sun.com/xml/ns/jdbc/webrowset.xsd.

  • FilteredRowSet - A FilteredRowSet object provides filtering functionality in a programmatic and extensible way. There are many instances when a RowSet object has a need to provide filtering in its contents without sacrificing the disconnected environment, thus saving the expense of having to create a connection to the data source. Solutions to this need vary from providing heavyweight full scale SQL query abilities, to portable components, to more lightweight approaches. A FilteredRowSet object consumes an implementation of the Predicate interface, which may define a filter at run time. In turn, a FilteredRowSet object is tasked with enforcing the set filter for both inbound and outbound read and write operations. That is, all filters can be considered as bi-directional. No standard filters are defined; however, sufficient mechanics are specified to permit any required filter to be implemented.

  • JoinRowSet - The JoinRowSet interface describes a mechanism by which relationships can be established between two or more standard RowSet implementations. Any number of RowSet objects can be added to a JoinRowSet object provided the RowSetobjects can be related in a SQL JOIN like fashion. By definition, the SQL JOIN statement is used to combine the data contained in two (or more) relational database tables based upon a common attribute. By establishing and then enforcing column matches, a JoinRowSet object establishes relationships between RowSet instances without the need to touch the originating data source.

3.0 Implementer's Guide

Compliant implementations of JDBC RowSet Implementations must follow the assertions described in this specification. In accordance with the terms of the Java Community Process, a Test Compatibility Kit (TCK) can be licensed to ensure compatibility with the specification. The following paragraphs outline a number of starting points for implementers of the standard JDBC RowSet definitions. Implementers should also consult the Implementer's Guide in the javax.sql.rowset.spi package for guidelines on SyncProvider implementations.

  • 3.1 Role of the BaseRowSet Class

    A compliant JDBC RowSet implementation must implement one or more standard interfaces specified in this package and and may extend the BaseRowSet abstract class. For example, a CachedRowSet implementation must implement the CachedRowSet interface and extend the BaseRowSet abstract class. The BaseRowSet class provides the standard architecture on which all RowSet implementations should be built, regardless of whether the RowSet objects exist in a connected or disconnected environment. The BaseRowSet abstract class provides any RowSet implementation with its base functionality, including property manipulation and event notification that is fully compliant with JavaBeans component requirements. As an example, all implementations provided in the reference implementations (contained in the com.sun.rowset package) use the BaseRowSet class as a basis for their implementations.

    The following table illustrates the features that the BaseRowSet abstract class provides.

    Feature
             Details
    Properties
             Provides standard JavaBeans property manipulation mechanisms to allow applications to get and set RowSet command and property values. Refer to the documentation of the javax.sql.RowSet interface (available in the JDBC 3.0 specification) for more details on the standard RowSet properties.
    Event notification
             Provides standard JavaBeans event notifications to registered event listeners. Refer to the documentation of javax.sql.RowSetEvent interface (available in the JDBC 3.0 specification) for more details on how to register and handle standard RowSet events generated by compliant implementations.
    Setters for a RowSet object's command
             Provides a complete set of setter methods for setting RowSet command parameters.
    Streams
             Provides fields for storing of stream instances in addition to providing a set of constants for stream type designation.

  • 3.2 Connected RowSet Requirements

    The JdbcRowSet describes a RowSet object that must always be connected to the originating data source. Implementations of the JdbcRowSet should ensure that this connection is provided solely by a JDBC driver. Furthermore, RowSet objects that are implementations of the JdbcRowSet interface and are therefore operating in a connected environment do not use the SyncFactory to obtain a RowSetReader object or a RowSetWriter object. They can safely rely on the JDBC driver to supply their needs by virtue of the presence of an underlying updatable and scrollable ResultSet implementation.

  • 3.3 Disconnected RowSet Requirements

    A disconnected RowSet object, such as a CachedRowSet object, should delegate connection management to a SyncProvider object provided by the SyncFactory. To ensure fully disconnected semantics, all disconnected RowSet objects must ensure that the original connection made to the data source to populate the RowSet object is closed to permit the garbage collector to recover and release resources. The SyncProvider object ensures that the critical JDBC properties are maintained in order to re-establish a connection to the data source when a synchronization is required. A disconnected RowSet object should therefore ensure that no extraneous references remain on the Connection object.

  • 3.4 Role of RowSetMetaDataImpl

    The RowsetMetaDataImpl class is a utility class that provides an implementation of the RowSetMetaData interface, supplying standard setter method implementations for metadata for both connected and disconnected RowSet objects. All implementations are free to use this standard implementation but are not required to do so.

  • 3.5 RowSetWarning Class

    The RowSetWarning class provides warnings that can be set on RowSet implementations. Similar to SQLWarning objects, RowSetWarning objects are silently chained to the object whose method caused the warning to be thrown. All RowSet implementations should ensure that this chaining occurs if a warning is generated and also ensure that the warnings are available via the getRowSetWarnings method defined in either the JdbcRowSet interface or the CachedRowSet interface. After a warning has been retrieved with one of the getRowSetWarnings methods, the RowSetWarning method getNextWarning can be called on it to retrieve any warnings that might be chained on it. If a warning is returned, getNextWarning can be called on it, and so on until there are no more warnings.

  • 3.6 The Joinable Interface

    The Joinable interface provides both connected and disconnected RowSet objects with the capability to be added to a JoinRowSet object in an SQL JOIN operation. A RowSet object that has implemented the Joinable interface can set a match column, retrieve a match column, or unset a match column. A JoinRowSet object can then use the RowSet object's match column as a basis for adding the RowSet object.

4.0 Related Specifications

  • JDBC 3.0 Specification
  • XML Schema
  • SyncML

5.0 Related Documentation

  • JDBC RowSet Tutorial

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.sql.rowset Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.sql.rowset

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.sql.rowset.BaseRowSet (implements java.lang.Cloneable, java.io.Serializable)
    • javax.sql.rowset.RowSetMetaDataImpl (implements javax.sql.RowSetMetaData, java.io.Serializable)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.sql.SQLException (implements java.lang.Iterable<T>)
          • javax.sql.rowset.RowSetWarning

Interface Hierarchy

  • javax.sql.rowset.Joinable
    • javax.sql.rowset.CachedRowSet (also extends javax.sql.RowSet)
      • javax.sql.rowset.WebRowSet
        • javax.sql.rowset.FilteredRowSet
        • javax.sql.rowset.JoinRowSet
    • javax.sql.rowset.JdbcRowSet (also extends javax.sql.RowSet)
  • javax.sql.rowset.Predicate
  • java.sql.Wrapper
    • java.sql.ResultSet
      • javax.sql.RowSet
        • javax.sql.rowset.CachedRowSet (also extends javax.sql.rowset.Joinable)
          • javax.sql.rowset.WebRowSet
            • javax.sql.rowset.FilteredRowSet
            • javax.sql.rowset.JoinRowSet
        • javax.sql.rowset.JdbcRowSet (also extends javax.sql.rowset.Joinable)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.sql.rowset

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.sql.rowset

Packages that use javax.sql.rowset
javax.sql.rowset | Standard interfaces and base classes for JDBC RowSet implementations.
javax.sql.rowset.spi | The standard classes and interfaces that a third party vendor has to use in its implementation of a synchronization provider.

Classes in javax.sql.rowset used by javax.sql.rowset
CachedRowSet
The interface that all standard implementations of CachedRowSet must implement.
Joinable
1.0 Background
Predicate
The standard interface that provides the framework for all FilteredRowSet objects to describe their filters.
RowSetWarning
An extension of SQLException that provides information about database warnings set on RowSet objects.
WebRowSet
The standard interface that all implementations of a WebRowSet must implement.

Classes in javax.sql.rowset used by javax.sql.rowset.spi
WebRowSet
The standard interface that all implementations of a WebRowSet must implement.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


BaseRowSet

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset
Class BaseRowSet

java.lang.Object
    extended by  javax.sql.rowset.BaseRowSet
All Implemented Interfaces:
Serializable, Cloneable
public abstract class BaseRowSet
extends Object
implements Serializable, Cloneable

An abstract class providing a RowSet object with its basic functionality. The basic functions include having properties and sending event notifications, which all JavaBeansTM components must implement.

1.0 Overview

The BaseRowSet class provides the core functionality for all RowSet implementations, and all standard implementations may use this class in combination with one or more RowSet interfaces in order to provide a standard vendor-specific implementation. To clarify, all implementations must implement at least one of the RowSet interfaces (JdbcRowSet, CachedRowSet, JoinRowSet, FilteredRowSet, or WebRowSet). This means that any implementation that extends the BaseRowSet class must also implement one of the RowSet interfaces.

The BaseRowSet class provides the following:

  • Properties
    • Fields for storing current properties
    • Methods for getting and setting properties

  • Event notification

  • A complete set of setter methods for setting the parameters in a RowSet object's command

  • Streams
    • Fields for storing stream instances
    • Constants for indicating the type of a stream

2.0 Setting Properties

All rowsets maintain a set of properties, which will usually be set using a tool. The number and kinds of properties a rowset has will vary, depending on what the RowSet implementation does and how it gets its data. For example, rowsets that get their data from a ResultSet object need to set the properties that are required for making a database connection. If a RowSet object uses the DriverManager facility to make a connection, it needs to set a property for the JDBC URL that identifies the appropriate driver, and it needs to set the properties that give the user name and password. If, on the other hand, the rowset uses a DataSource object to make the connection, which is the preferred method, it does not need to set the property for the JDBC URL. Instead, it needs to set the property for the logical name of the data source along with the properties for the user name and password.

NOTE: In order to use a DataSource object for making a connection, the DataSource object must have been registered with a naming service that uses the Java Naming and Directory InterfaceTM (JNDI) API. This registration is usually done by a person acting in the capacity of a system administrator.

3.0 Setting the Command and Its Parameters

When a rowset gets its data from a relational database, it executes a command (a query) that produces a ResultSet object. This query is the command that is set for the RowSet object's command property. The rowset populates itself with data by reading the data from the ResultSet object into itself. If the query contains placeholders for values to be set, the BaseRowSet setter methods are used to set these values. All setter methods allow these values to be set to null if required.

The following code fragment illustrates how the CachedRowSetTM object crs might have its command property set. Note that if a tool is used to set properties, this is the code that the tool would use.

    crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
                   "WHERE CREDIT_LIMIT > ? AND REGION = ?");

In this example, the values for CREDIT_LIMIT and REGION are placeholder parameters, which are indicated with a question mark (?). The first question mark is placeholder parameter number 1, the second question mark is placeholder parameter number 2, and so on. Any placeholder parameters must be set with values before the query can be executed. To set these placeholder parameters, the BaseRowSet class provides a set of setter methods, similar to those provided by the PreparedStatement interface, for setting values of each data type. A RowSet object stores the parameter values internally, and its execute method uses them internally to set values for the placeholder parameters before it sends the command to the DBMS to be executed.

The following code fragment demonstrates setting the two parameters in the query from the previous example.

    crs.setInt(1, 5000);
    crs.setString(2, "West");
If the execute method is called at this point, the query sent to the DBMS will be:
    "SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
                   "WHERE CREDIT_LIMIT > 5000 AND REGION = 'West'"
NOTE: Setting Array, Clob, Blob and Ref objects as a command parameter, stores these values as SerialArray, SerialClob, SerialBlob and SerialRef objects respectively.

4.0 Handling of Parameters Behind the Scenes

NOTE: The BaseRowSet class provides two kinds of setter methods, those that set properties and those that set placeholder parameters. The setter methods discussed in this section are those that set placeholder parameters.

The placeholder parameters set with the BaseRowSet setter methods are stored as objects in an internal Hashtable object. Primitives are stored as their Object type. For example, byte is stored as Byte object, and int is stored as an Integer object. When the method execute is called, the values in the Hashtable object are substituted for the appropriate placeholder parameters in the command. A call to the method getParams returns the values stored in the Hashtable object as an array of Object instances. An element in this array may be a simple Object instance or an array (which is a type of Object). The particular setter method used determines whether an element in this array is an Object or an array.

The majority of methods for setting placeholder parameters take two parameters, with the first parameter indicating which placeholder parameter is to be set, and the second parameter giving the value to be set. Methods such as getInt, getString, getBoolean, and getLong fall into this category. After these methods have been called, a call to the method getParams will return an array with the values that have been set. Each element in the array is an Object instance representing the values that have been set. The order of these values in the array is determined by the int (the first parameter) passed to the setter method. The values in the array are the values (the second parameter) passed to the setter method. In other words, the first element in the array is the value to be set for the first placeholder parameter in the RowSet object's command. The second element is the value to be set for the second placeholder parameter, and so on.

Several setter methods send the driver and DBMS information beyond the value to be set. When the method getParams is called after one of these setter methods has been used, the elements in the array will themselves be arrays to accommodate the additional information. In this category, the method setNull is a special case because one version takes only two parameters (setNull(int parameterIndex, int SqlType)). Nevertheless, it requires an array to contain the information that will be passed to the driver and DBMS. The first element in this array is the value to be set, which is null, and the second element is the int supplied for sqlType, which indicates the type of SQL value that is being set to null. This information is needed by some DBMSs and is therefore required in order to ensure that applications are portable. The other version is intended to be used when the value to be set to null is a user-defined type. It takes three parameters (setNull(int parameterIndex, int sqlType, String typeName)) and also requires an array to contain the information to be passed to the driver and DBMS. The first two elements in this array are the same as for the first version of setNull. The third element, typeName, gives the SQL name of the user-defined type. As is true with the other setter methods, the number of the placeholder parameter to be set is indicated by an element's position in the array returned by getParams. So, for example, if the parameter supplied to setNull is 2, the second element in the array returned by getParams will be an array of two or three elements.

Some methods, such as setObject and setDate have versions that take more than two parameters, with the extra parameters giving information to the driver or the DBMS. For example, the methods setDate, setTime, and setTimestamp can take a Calendar object as their third parameter. If the DBMS does not store time zone information, the drivern uses the Calendar object to construct the Date, Time, or Timestamp object being set. As is true with other methods that provide additional information, the element in the array returned by getParams is an array instead of a simple Object instance.

The methods setAsciiStream, setBinaryStream, setCharacterStream, and setUnicodeStream (which is deprecated, so applications should use getCharacterStream instead) take three parameters, so for them, the element in the array returned by getParams is also an array. What is different about these setter methods is that in addition to the information provided by parameters, the array contains one of the BaseRowSet constants indicating the type of stream being set.

NOTE: The method getParams is called internally by RowSet implementations extending this class; it is not normally called by an application programmer directly.

5.0 Event Notification

The BaseRowSet class provides the event notification mechanism for rowsets. It contains the field listeners, methods for adding and removing listeners, and methods for notifying listeners of changes.

A listener is an object that has implemented the RowSetListener interface. If it has been added to a RowSet object's list of listeners, it will be notified when an event occurs on that RowSet object. Each listener's implementation of the RowSetListener methods defines what that object will do when it is notified that an event has occurred.

There are three possible events for a RowSet object:

  1. the cursor moves
  2. an individual row is changed (updated, deleted, or inserted)
  3. the contents of the entire RowSet object are changed

The BaseRowSet method used for the notification indicates the type of event that has occurred. For example, the method notifyRowChanged indicates that a row has been updated, deleted, or inserted. Each of the notification methods creates a RowSetEvent object, which is supplied to the listener in order to identify the RowSet object on which the event occurred. What the listener does with this information, which may be nothing, depends on how it was implemented.

6.0 Default Behavior

A default BaseRowSet object is initialized with many starting values. The following is true of a default RowSet instance that extends the BaseRowSet class:
  • Has a scrollable cursor and does not show changes made by others.
  • Is updatable.
  • Does not show rows that have been deleted.
  • Has no time limit for how long a driver may take to execute the RowSet object's command.
  • Has no limit for the number of rows it may contain.
  • Has no limit for the number of bytes a column may contain. NOTE: This limit applies only to columns that hold values of the following types: BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR.
  • Will not see uncommitted data (make "dirty" reads).
  • Has escape processing turned on.
  • Has its connection's type map set to null.
  • Has an empty Vector object for storing the values set for the placeholder parameters in the RowSet object's command.

If other values are desired, an application must set the property values explicitly. For example, the following line of code sets the maximum number of rows for the CachedRowSet object crs to 500.

    crs.setMaxRows(500);
Methods implemented in extensions of this BaseRowSet class must throw an SQLException object for any violation of the defined assertions. Also, if the extending class overrides and reimplements any BaseRowSet method and encounters connectivity or underlying data source issues, that method may in addition throw an SQLException object for that reason.

See Also:
Serialized Form

Field Summary
static int | ASCII_STREAM_PARAM A constant indicating to a RowSetReaderImpl object that a given parameter is an ASCII stream.
protected InputStream | asciiStream The InputStream object that will be returned by the method getAsciiStream, which is specified in the ResultSet interface.
static int | BINARY_STREAM_PARAM A constant indicating to a RowSetReaderImpl object that a given parameter is a binary stream.
protected InputStream | binaryStream The InputStream object that will be returned by the method getBinaryStream, which is specified in the ResultSet interface.
protected Reader | charStream The Reader object that will be returned by the method getCharacterStream, which is specified in the ResultSet interface.
static int | UNICODE_STREAM_PARAM A constant indicating to a RowSetReaderImpl object that a given parameter is a Unicode stream.
protected InputStream | unicodeStream The InputStream object that will be returned by the method getUnicodeStream, which is specified in the ResultSet interface.
Constructor Summary
BaseRowSet()
Constructs a new BaseRowSet object initialized with a default Vector object for its listeners field.
Method Summary
void | addRowSetListener(RowSetListener listener) The listener will be notified whenever an event occurs on this RowSet object.
void | clearParameters() Clears all of the current parameter values in this RowSet object's internal representation of the parameters to be set in this RowSet object's command when it is executed.
String | getCommand() Retrieves the SQL query that is the command for this RowSet object.
int | getConcurrency() Returns the concurrency for this RowSet object.
String | getDataSourceName() Returns the logical name that when supplied to a naming service that uses the Java Naming and Directory Interface (JNDI) API, will retrieve a javax.sql.DataSource object.
boolean | getEscapeProcessing() Ascertains whether escape processing is enabled for this RowSet object.
int | getFetchDirection() Retrieves this RowSet object's current setting for the fetch direction.
int | getFetchSize() Returns the fetch size for this RowSet object.
int | getMaxFieldSize() Retrieves the maximum number of bytes that can be used for a column value in this RowSet object.
int | getMaxRows() Retrieves the maximum number of rows that this RowSet object may contain.
Object[] | getParams() Retrieves an array containing the parameter values (both Objects and primitives) that have been set for this RowSet object's command and throws an SQLException object if all parameters have not been set.
String | getPassword() Returns the password used to create a database connection for this RowSet object.
int | getQueryTimeout() Retrieves the maximum number of seconds the driver will wait for a query to execute.
boolean | getShowDeleted() Retrieves a boolean indicating whether rows marked for deletion appear in the set of current rows.
int | getTransactionIsolation() Returns the transaction isolation property for this RowSet object's connection.
int | getType() Returns the type of this RowSet object.
Map<String,Class<?>> | getTypeMap() Retrieves the type map associated with the Connection object for this RowSet object.
String | getUrl() Retrieves the JDBC URL that this RowSet object's javax.sql.Reader object uses to make a connection with a relational database using a JDBC technology-enabled driver.
String | getUsername() Returns the user name used to create a database connection.
protected void | initParams() Performs the necessary internal configurations and initializations to allow any JDBC RowSet implementation to start using the standard facilities provided by a BaseRowSet instance.
boolean | isReadOnly() Returns a boolean indicating whether this RowSet object is read-only.
protected void | notifyCursorMoved() Notifies all of the listeners registered with this RowSet object that its cursor has moved.
protected void | notifyRowChanged() Notifies all of the listeners registered with this RowSet object that one of its rows has changed.
protected void | notifyRowSetChanged() Notifies all of the listeners registered with this RowSet object that its entire contents have changed.
void | removeRowSetListener(RowSetListener listener) Removes the designated object from this RowSet object's list of listeners.
void | setArray(int parameterIndex, Array array) Sets the designated parameter to an Array object in the Java programming language.
void | setAsciiStream(int parameterIndex, InputStream x) Sets the designated parameter in this RowSet object's command to the given input stream.
void | setAsciiStream(int parameterIndex, InputStream x, int length) Sets the designated parameter to the given java.io.InputStream object, which will have the specified number of bytes.
void | setAsciiStream(String parameterName, InputStream x) Sets the designated parameter to the given input stream.
void | setAsciiStream(String parameterName, InputStream x, int length) Sets the designated parameter to the given input stream, which will have the specified number of bytes.
void | setBigDecimal(int parameterIndex, BigDecimal x) Sets the designated parameter to the given java.lang.BigDecimal value.
void | setBigDecimal(String parameterName, BigDecimal x) Sets the designated parameter to the given java.math.BigDecimal value.
void | setBinaryStream(int parameterIndex, InputStream x) Sets the designated parameter in this RowSet object's command to the given input stream.
void | setBinaryStream(int parameterIndex, InputStream x, int length) Sets the designated parameter to the given java.io.InputStream object, which will have the specified number of bytes.
void | setBinaryStream(String parameterName, InputStream x) Sets the designated parameter to the given input stream.
void | setBinaryStream(String parameterName, InputStream x, int length) Sets the designated parameter to the given input stream, which will have the specified number of bytes.
void | setBlob(int parameterIndex, Blob x) Sets the designated parameter to the given Blob object in the Java programming language.
void | setBlob(int parameterIndex, InputStream inputStream) Sets the designated parameter to a InputStream object.
void | setBlob(int parameterIndex, InputStream inputStream, long length) Sets the designated parameter to a InputStream object.
void | setBlob(String parameterName, Blob x) Sets the designated parameter to the given java.sql.Blob object.
void | setBlob(String parameterName, InputStream inputStream) Sets the designated parameter to a InputStream object.
void | setBlob(String parameterName, InputStream inputStream, long length) Sets the designated parameter to a InputStream object.
void | setBoolean(int parameterIndex, boolean x) Sets the designated parameter to the given boolean in the Java programming language.
void | setBoolean(String parameterName, boolean x) Sets the designated parameter to the given Java boolean value.
void | setByte(int parameterIndex, byte x) Sets the designated parameter to the given byte in the Java programming language.
void | setByte(String parameterName, byte x) Sets the designated parameter to the given Java byte value.
void | setBytes(int parameterIndex, byte[] x) Sets the designated parameter to the given array of bytes.
void | setBytes(String parameterName, byte[] x) Sets the designated parameter to the given Java array of bytes.
void | setCharacterStream(int parameterIndex, Reader reader) Sets the designated parameter in this RowSet object's command to the given Reader object.
void | setCharacterStream(int parameterIndex, Reader reader, int length) Sets the designated parameter to the given java.io.Reader object, which will have the specified number of characters.
void | setCharacterStream(String parameterName, Reader reader) Sets the designated parameter to the given Reader object.
void | setCharacterStream(String parameterName, Reader reader, int length) Sets the designated parameter to the given Reader object, which is the given number of characters long.
void | setClob(int parameterIndex, Clob x) Sets the designated parameter to the given Clob object in the Java programming language.
void | setClob(int parameterIndex, Reader reader) Sets the designated parameter to a Reader object.
void | setClob(int parameterIndex, Reader reader, long length) Sets the designated parameter to a Reader object.
void | setClob(String parameterName, Clob x) Sets the designated parameter to the given java.sql.Clob object.
void | setClob(String parameterName, Reader reader) Sets the designated parameter to a Reader object.
void | setClob(String parameterName, Reader reader, long length) Sets the designated parameter to a Reader object.
void | setCommand(String cmd) Sets this RowSet object's command property to the given String object and clears the parameters, if any, that were set for the previous command.
void | setConcurrency(int concurrency) Sets the concurrency for this RowSet object to the specified concurrency.
void | setDataSourceName(String name) Sets the DataSource name property for this RowSet object to the given logical name and sets this RowSet object's Url property to null.
void | setDate(int parameterIndex, Date x) Sets the designated parameter to the given java.sql.Date value.
void | setDate(int parameterIndex, Date x, Calendar cal) Sets the designated parameter to the given java.sql.Date object.
void | setDate(String parameterName, Date x) Sets the designated parameter to the given java.sql.Date value using the default time zone of the virtual machine that is running the application.
void | setDate(String parameterName, Date x, Calendar cal) Sets the designated parameter to the given java.sql.Date value, using the given Calendar object.
void | setDouble(int parameterIndex, double x) Sets the designated parameter to the given double in the Java programming language.
void | setDouble(String parameterName, double x) Sets the designated parameter to the given Java double value.
void | setEscapeProcessing(boolean enable) Sets to the given boolean whether or not the driver will scan for escape syntax and do escape substitution before sending SQL statements to the database.
void | setFetchDirection(int direction) Gives the driver a performance hint as to the direction in which the rows in this RowSet object will be processed.
void | setFetchSize(int rows) Sets the fetch size for this RowSet object to the given number of rows.
void | setFloat(int parameterIndex, float x) Sets the designated parameter to the given float in the Java programming language.
void | setFloat(String parameterName, float x) Sets the designated parameter to the given Java float value.
void | setInt(int parameterIndex, int x) Sets the designated parameter to an int in the Java programming language.
void | setInt(String parameterName, int x) Sets the designated parameter to the given Java int value.
void | setLong(int parameterIndex, long x) Sets the designated parameter to the given long in the Java programming language.
void | setLong(String parameterName, long x) Sets the designated parameter to the given Java long value.
void | setMaxFieldSize(int max) Sets the maximum number of bytes that can be used for a column value in this RowSet object to the given number.
void | setMaxRows(int max) Sets the maximum number of rows that this RowSet object may contain to the given number.
void | setNCharacterStream(int parameterIndex, Reader value) Sets the designated parameter in this RowSet object's command to a Reader object.
void | setNCharacterStream(int parameterIndex, Reader value, long length) Sets the designated parameter to a Reader object.
void | setNCharacterStream(String parameterName, Reader value) Sets the designated parameter to a Reader object.
void | setNCharacterStream(String parameterName, Reader value, long length) Sets the designated parameter to a Reader object.
void | setNClob(int parameterIndex, NClob value) Sets the designated parameter to a java.sql.NClob object.
void | setNClob(int parameterIndex, Reader reader) Sets the designated parameter to a Reader object.
void | setNClob(int parameterIndex, Reader reader, long length) Sets the designated parameter to a Reader object.
void | setNClob(String parameterName, NClob value) Sets the designated parameter to a java.sql.NClob object.
void | setNClob(String parameterName, Reader reader) Sets the designated parameter to a Reader object.
void | setNClob(String parameterName, Reader reader, long length) Sets the designated parameter to a Reader object.
void | setNString(int parameterIndex, String value) Sets the designated paramter to the given String object.
void | setNString(String parameterName, String value) Sets the designated paramter to the given String object.
void | setNull(int parameterIndex, int sqlType) Sets the designated parameter to SQL NULL.
void | setNull(int parameterIndex, int sqlType, String typeName) Sets the designated parameter to SQL NULL.
void | setNull(String parameterName, int sqlType) Sets the designated parameter to SQL NULL.
void | setNull(String parameterName, int sqlType, String typeName) Sets the designated parameter to SQL NULL.
void | setObject(int parameterIndex, Object x) Sets the designated parameter to an Object in the Java programming language.
void | setObject(int parameterIndex, Object x, int targetSqlType) Sets the value of the designated parameter with the given Object value.
void | setObject(int parameterIndex, Object x, int targetSqlType, int scale) Sets the designated parameter to an Object in the Java programming language.
void | setObject(String parameterName, Object x) Sets the value of the designated parameter with the given object.
void | setObject(String parameterName, Object x, int targetSqlType) Sets the value of the designated parameter with the given object.
void | setObject(String parameterName, Object x, int targetSqlType, int scale) Sets the value of the designated parameter with the given object.
void | setPassword(String pass) Sets the password used to create a database connection for this RowSet object to the given String object.
void | setQueryTimeout(int seconds) Sets to the given number the maximum number of seconds the driver will wait for a query to execute.
void | setReadOnly(boolean value) Sets this RowSet object's readOnly property to the given boolean.
void | setRef(int parameterIndex, Ref ref) Sets the designated parameter to the given Ref object in the Java programming language.
void | setRowId(int parameterIndex, RowId x) Sets the designated parameter to the given java.sql.RowId object.
void | setRowId(String parameterName, RowId x) Sets the designated parameter to the given java.sql.RowId object.
void | setShort(int parameterIndex, short x) Sets the designated parameter to the given short in the Java programming language.
void | setShort(String parameterName, short x) Sets the designated parameter to the given Java short value.
void | setShowDeleted(boolean value) Sets the property showDeleted to the given boolean value, which determines whether rows marked for deletion appear in the set of current rows.
void | setSQLXML(int parameterIndex, SQLXML xmlObject) Sets the designated parameter to the given java.sql.SQLXML object.
void | setSQLXML(String parameterName, SQLXML xmlObject) Sets the designated parameter to the given java.sql.SQLXML object.
void | setString(int parameterIndex, String x) Sets the designated parameter to the given String value.
void | setString(String parameterName, String x) Sets the designated parameter to the given Java String value.
void | setTime(int parameterIndex, Time x) Sets the designated parameter to the given java.sql.Time value.
void | setTime(int parameterIndex, Time x, Calendar cal) Sets the designated parameter to the given java.sql.Time object.
void | setTime(String parameterName, Time x) Sets the designated parameter to the given java.sql.Time value.
void | setTime(String parameterName, Time x, Calendar cal) Sets the designated parameter to the given java.sql.Time value, using the given Calendar object.
void | setTimestamp(int parameterIndex, Timestamp x) Sets the designated parameter to the given java.sql.Timestamp value.
void | setTimestamp(int parameterIndex, Timestamp x, Calendar cal) Sets the designated parameter to the given java.sql.Timestamp object.
void | setTimestamp(String parameterName, Timestamp x) Sets the designated parameter to the given java.sql.Timestamp value.
void | setTimestamp(String parameterName, Timestamp x, Calendar cal) Sets the designated parameter to the given java.sql.Timestamp value, using the given Calendar object.
void | setTransactionIsolation(int level) Sets the transaction isolation property for this JDBC RowSet object to the given constant.
void | setType(int type) Sets the type for this RowSet object to the specified type.
void | setTypeMap(Map<String,Class<?>> map) Installs the given java.util.Map object as the type map associated with the Connection object for this RowSet object.
void | setUnicodeStream(int parameterIndex, InputStream x, int length) Deprecated. getCharacterStream should be used in its place
void | setURL(int parameterIndex, URL x) Sets the designated parameter to the given java.net.URL value.
void | setUrl(String url) Sets the Url property for this RowSet object to the given String object and sets the dataSource name property to null.
void | setUsername(String name) Sets the username property for this RowSet object to the given user name.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

UNICODE_STREAM_PARAM

public static final int UNICODE_STREAM_PARAM
A constant indicating to a RowSetReaderImpl object that a given parameter is a Unicode stream. This RowSetReaderImpl object is provided as an extension of the SyncProvider abstract class defined in the SyncFactory static factory SPI mechanism.

See Also:
Constant Field Values

BINARY_STREAM_PARAM

public static final int BINARY_STREAM_PARAM
A constant indicating to a RowSetReaderImpl object that a given parameter is a binary stream. A RowSetReaderImpl object is provided as an extension of the SyncProvider abstract class defined in the SyncFactory static factory SPI mechanism.

See Also:
Constant Field Values

ASCII_STREAM_PARAM

public static final int ASCII_STREAM_PARAM
A constant indicating to a RowSetReaderImpl object that a given parameter is an ASCII stream. A RowSetReaderImpl object is provided as an extension of the SyncProvider abstract class defined in the SyncFactory static factory SPI mechanism.

See Also:
Constant Field Values

binaryStream

protected InputStream binaryStream
The InputStream object that will be returned by the method getBinaryStream, which is specified in the ResultSet interface.

unicodeStream

protected InputStream unicodeStream
The InputStream object that will be returned by the method getUnicodeStream, which is specified in the ResultSet interface.

asciiStream

protected InputStream asciiStream
The InputStream object that will be returned by the method getAsciiStream, which is specified in the ResultSet interface.

charStream

protected Reader charStream
The Reader object that will be returned by the method getCharacterStream, which is specified in the ResultSet interface.

Constructor Detail

BaseRowSet

public BaseRowSet()
Constructs a new BaseRowSet object initialized with a default Vector object for its listeners field. The other default values with which it is initialized are listed in Section 6.0 of the class comment for this class.

Method Detail

initParams

protected void initParams()
Performs the necessary internal configurations and initializations to allow any JDBC RowSet implementation to start using the standard facilities provided by a BaseRowSet instance. This method should be called after the RowSet object has been instantiated to correctly initialize all parameters. This method should never be called by an application, but is called from with a RowSet implementation extending this class.

addRowSetListener

public void addRowSetListener(RowSetListener listener)
The listener will be notified whenever an event occurs on this RowSet object.

A listener might, for example, be a table or graph that needs to be updated in order to accurately reflect the current state of the RowSet object.

Note: if the RowSetListener object is null, this method silently discards the null value and does not add a null reference to the set of listeners.

Note: if the listener is already set, and the new RowSetListerner instance is added to the set of listeners already registered to receive event notifications from this RowSet.

Parameters:
listener - an object that has implemented the javax.sql.RowSetListener interface and wants to be notified of any events that occur on this RowSet object; May be null.
See Also:
removeRowSetListener(javax.sql.RowSetListener)

removeRowSetListener

public void removeRowSetListener(RowSetListener listener)
Removes the designated object from this RowSet object's list of listeners. If the given argument is not a registered listener, this method does nothing. Note: if the RowSetListener object is null, this method silently discards the null value.

Parameters:
listener - a RowSetListener object that is on the list of listeners for this RowSet object
See Also:
addRowSetListener(javax.sql.RowSetListener)

notifyCursorMoved

protected void notifyCursorMoved()
                          throws SQLException
Notifies all of the listeners registered with this RowSet object that its cursor has moved.

When an application calls a method to move the cursor, that method moves the cursor and then calls this method internally. An application should never invoke this method directly.

Throws:
SQLException - if the class extending the BaseRowSet abstract class does not implement the RowSet interface or one of it's sub-interfaces.

notifyRowChanged

protected void notifyRowChanged()
                         throws SQLException
Notifies all of the listeners registered with this RowSet object that one of its rows has changed.

When an application calls a method that changes a row, such as the CachedRowSet methods insertRow, updateRow, or deleteRow, that method calls notifyRowChanged internally. An application should never invoke this method directly.

Throws:
SQLException - if the class extending the BaseRowSet abstract class does not implement the RowSet interface or one of it's sub-interfaces.

notifyRowSetChanged

protected void notifyRowSetChanged()
                            throws SQLException
Notifies all of the listeners registered with this RowSet object that its entire contents have changed.

When an application calls methods that change the entire contents of the RowSet object, such as the CachedRowSet methods execute, populate, restoreOriginal, or release, that method calls notifyRowSetChanged internally (either directly or indirectly). An application should never invoke this method directly.

Throws:
SQLException - if the class extending the BaseRowSet abstract class does not implement the RowSet interface or one of it's sub-interfaces.

getCommand

public String getCommand()
Retrieves the SQL query that is the command for this RowSet object. The command property contains the query that will be executed to populate this RowSet object.

The SQL query returned by this method is used by RowSet methods such as execute and populate, which may be implemented by any class that extends the BaseRowSet abstract class and implements one or more of the standard JSR-114 RowSet interfaces.

The command is used by the RowSet object's reader to obtain a ResultSet object. The reader then reads the data from the ResultSet object and uses it to to populate this RowSet object.

The default value for the command property is null.

Returns:
the String that is the value for this RowSet object's command property; may be null
See Also:
setCommand(java.lang.String)

setCommand

public void setCommand(String cmd)
                throws SQLException
Sets this RowSet object's command property to the given String object and clears the parameters, if any, that were set for the previous command.

The command property may not be needed if the RowSet object gets its data from a source that does not support commands, such as a spreadsheet or other tabular file. Thus, this property is optional and may be null.

Parameters:
cmd - a String object containing an SQL query that will be set as this RowSet object's command property; may be null but may not be an empty string
Throws:
SQLException - if an empty string is provided as the command value
See Also:
getCommand()

getUrl

public String getUrl()
              throws SQLException
Retrieves the JDBC URL that this RowSet object's javax.sql.Reader object uses to make a connection with a relational database using a JDBC technology-enabled driver.

The Url property will be null if the underlying data source is a non-SQL data source, such as a spreadsheet or an XML data source.

Returns:
a String object that contains the JDBC URL used to establish the connection for this RowSet object; may be null (default value) if not set
Throws:
SQLException - if an error occurs retrieving the URL value
See Also:
setUrl(java.lang.String)

setUrl

public void setUrl(String url)
            throws SQLException
Sets the Url property for this RowSet object to the given String object and sets the dataSource name property to null. The Url property is a JDBC URL that is used when the connection is created using a JDBC technology-enabled driver ("JDBC driver") and the DriverManager. The correct JDBC URL for the specific driver to be used can be found in the driver documentation. Although there are guidelines for for how a JDBC URL is formed, a driver vendor can specify any String object except one with a length of 0 (an empty string).

Setting the Url property is optional if connections are established using a DataSource object instead of the DriverManager. The driver will use either the URL property or the dataSourceName property to create a connection, whichever was specified most recently. If an application uses a JDBC URL, it must load a JDBC driver that accepts the JDBC URL before it uses the RowSet object to connect to a database. The RowSet object will use the URL internally to create a database connection in order to read or write data.

Parameters:
url - a String object that contains the JDBC URL that will be used to establish the connection to a database for this RowSet object; may be null but must not be an empty string
Throws:
SQLException - if an error occurs setting the Url property or the parameter supplied is a string with a length of 0 (an empty string)
See Also:
getUrl()

getDataSourceName

public String getDataSourceName()
Returns the logical name that when supplied to a naming service that uses the Java Naming and Directory Interface (JNDI) API, will retrieve a javax.sql.DataSource object. This DataSource object can be used to establish a connection to the data source that it represents.

Users should set either the url or the data source name property. The driver will use the property set most recently to establish a connection.

Returns:
a String object that identifies the DataSource object to be used for making a connection; if no logical name has been set, null is returned.
See Also:
setDataSourceName(java.lang.String)

setDataSourceName

public void setDataSourceName(String name)
                       throws SQLException
Sets the DataSource name property for this RowSet object to the given logical name and sets this RowSet object's Url property to null. The name must have been bound to a DataSource object in a JNDI naming service so that an application can do a lookup using that name to retrieve the DataSource object bound to it. The DataSource object can then be used to establish a connection to the data source it represents.

Users should set either the Url property or the dataSourceName property. If both properties are set, the driver will use the property set most recently.

Parameters:
name - a String object with the name that can be supplied to a naming service based on JNDI technology to retrieve the DataSource object that can be used to get a connection; may be null but must not be an empty string
Throws:
SQLException - if an empty string is provided as the DataSource name
See Also:
getDataSourceName()

getUsername

public String getUsername()
Returns the user name used to create a database connection. Because it is not serialized, the username property is set at runtime before calling the method execute.

Returns:
the String object containing the user name that is supplied to the data source to create a connection; may be null (default value) if not set
See Also:
setUsername(java.lang.String)

setUsername

public void setUsername(String name)
Sets the username property for this RowSet object to the given user name. Because it is not serialized, the username property is set at run time before calling the method execute.

Parameters:
name - the String object containing the user name that is supplied to the data source to create a connection. It may be null.
See Also:
getUsername()

getPassword

public String getPassword()
Returns the password used to create a database connection for this RowSet object. Because the password property is not serialized, it is set at run time before calling the method execute. The default value is null

Returns:
the String object that represents the password that must be supplied to the database to create a connection
See Also:
setPassword(java.lang.String)

setPassword

public void setPassword(String pass)
Sets the password used to create a database connection for this RowSet object to the given String object. Because the password property is not serialized, it is set at run time before calling the method execute.

Parameters:
pass - the String object that represents the password that is supplied to the database to create a connection. It may be null.
See Also:
getPassword()

setType

public void setType(int type)
             throws SQLException
Sets the type for this RowSet object to the specified type. The default type is ResultSet.TYPE_SCROLL_INSENSITIVE.

Parameters:
type - one of the following constants: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE
Throws:
SQLException - if the parameter supplied is not one of the following constants: ResultSet.TYPE_FORWARD_ONLY or ResultSet.TYPE_SCROLL_INSENSITIVE ResultSet.TYPE_SCROLL_SENSITIVE
See Also:
getConcurrency(), getType()

getType

public int getType()
            throws SQLException
Returns the type of this RowSet object. The type is initially determined by the statement that created the RowSet object. The RowSet object can call the method setType at any time to change its type. The default is TYPE_SCROLL_INSENSITIVE.

Returns:
the type of this JDBC RowSet object, which must be one of the following: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE
Throws:
SQLException - if an error occurs getting the type of of this RowSet object
See Also:
setType(int)

setConcurrency

public void setConcurrency(int concurrency)
                    throws SQLException
Sets the concurrency for this RowSet object to the specified concurrency. The default concurrency for any RowSet object (connected or disconnected) is ResultSet.CONCUR_UPDATABLE, but this method may be called at any time to change the concurrency.

Parameters:
concurrency - one of the following constants: ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE
Throws:
SQLException - if the parameter supplied is not one of the following constants: ResultSet.CONCUR_UPDATABLE or ResultSet.CONCUR_READ_ONLY
See Also:
getConcurrency(), isReadOnly()

isReadOnly

public boolean isReadOnly()
Returns a boolean indicating whether this RowSet object is read-only. Any attempts to update a read-only RowSet object will result in an SQLException being thrown. By default, rowsets are updatable if updates are possible.

Returns:
true if this RowSet object cannot be updated; false otherwise
See Also:
setConcurrency(int), setReadOnly(boolean)

setReadOnly

public void setReadOnly(boolean value)
Sets this RowSet object's readOnly property to the given boolean.

Parameters:
value - true to indicate that this RowSet object is read-only; false to indicate that it is updatable

getTransactionIsolation

public int getTransactionIsolation()
Returns the transaction isolation property for this RowSet object's connection. This property represents the transaction isolation level requested for use in transactions.

For RowSet implementations such as the CachedRowSet that operate in a disconnected environment, the SyncProvider object offers complementary locking and data integrity options. The options described below are pertinent only to connected RowSet objects (JdbcRowSet objects).

Returns:
one of the following constants: Connection.TRANSACTION_NONE, Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_REPEATABLE_READ, or Connection.TRANSACTION_SERIALIZABLE
See Also:
SyncFactory, SyncProvider, setTransactionIsolation(int)

setTransactionIsolation

public void setTransactionIsolation(int level)
                             throws SQLException
Sets the transaction isolation property for this JDBC RowSet object to the given constant. The DBMS will use this transaction isolation level for transactions if it can.

For RowSet implementations such as the CachedRowSet that operate in a disconnected environment, the SyncProvider object being used offers complementary locking and data integrity options. The options described below are pertinent only to connected RowSet objects (JdbcRowSet objects).

Parameters:
level - one of the following constants, listed in ascending order: Connection.TRANSACTION_NONE, Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_REPEATABLE_READ, or Connection.TRANSACTION_SERIALIZABLE
Throws:
SQLException - if the given parameter is not one of the Connection constants
See Also:
SyncFactory, SyncProvider, getTransactionIsolation()

getTypeMap

public Map<String,Class<?>> getTypeMap()
Retrieves the type map associated with the Connection object for this RowSet object.

Drivers that support the JDBC 3.0 API will create Connection objects with an associated type map. This type map, which is initially empty, can contain one or more fully-qualified SQL names and Class objects indicating the class to which the named SQL value will be mapped. The type mapping specified in the connection's type map is used for custom type mapping when no other type map supersedes it.

If a type map is explicitly supplied to a method that can perform custom mapping, that type map supersedes the connection's type map.

Returns:
the java.util.Map object that is the type map for this RowSet object's connection

setTypeMap

public void setTypeMap(Map<String,Class<?>> map)
Installs the given java.util.Map object as the type map associated with the Connection object for this RowSet object. The custom mapping indicated in this type map will be used unless a different type map is explicitly supplied to a method, in which case the type map supplied will be used.

Parameters:
map - a java.util.Map object that contains the mapping from SQL type names for user defined types (UDT) to classes in the Java programming language. Each entry in the Map object consists of the fully qualified SQL name of a UDT and the Class object for the SQLData implementation of that UDT. May be null.

getMaxFieldSize

public int getMaxFieldSize()
                    throws SQLException
Retrieves the maximum number of bytes that can be used for a column value in this RowSet object. This limit applies only to columns that hold values of the following types: BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR. If the limit is exceeded, the excess data is silently discarded.

Returns:
an int indicating the current maximum column size limit; zero means that there is no limit
Throws:
SQLException - if an error occurs internally determining the maximum limit of the column size

setMaxFieldSize

public void setMaxFieldSize(int max)
                     throws SQLException
Sets the maximum number of bytes that can be used for a column value in this RowSet object to the given number. This limit applies only to columns that hold values of the following types: BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR. If the limit is exceeded, the excess data is silently discarded. For maximum portability, it is advisable to use values greater than 256.

Parameters:
max - an int indicating the new maximum column size limit; zero means that there is no limit
Throws:
SQLException - if (1) an error occurs internally setting the maximum limit of the column size or (2) a size of less than 0 is set

getMaxRows

public int getMaxRows()
               throws SQLException
Retrieves the maximum number of rows that this RowSet object may contain. If this limit is exceeded, the excess rows are silently dropped.

Returns:
an int indicating the current maximum number of rows; zero means that there is no limit
Throws:
SQLException - if an error occurs internally determining the maximum limit of rows that a Rowset object can contain

setMaxRows

public void setMaxRows(int max)
                throws SQLException
Sets the maximum number of rows that this RowSet object may contain to the given number. If this limit is exceeded, the excess rows are silently dropped.

Parameters:
max - an int indicating the current maximum number of rows; zero means that there is no limit
Throws:
SQLException - if an error occurs internally setting the maximum limit on the number of rows that a JDBC RowSet object can contain; or if max is less than 0; or if max is less than the fetchSize of the RowSet

setEscapeProcessing

public void setEscapeProcessing(boolean enable)
                         throws SQLException
Sets to the given boolean whether or not the driver will scan for escape syntax and do escape substitution before sending SQL statements to the database. The default is for the driver to do escape processing.

Note: Since PreparedStatement objects have usually been parsed prior to making this call, disabling escape processing for prepared statements will likely have no effect.

Parameters:
enable - true to enable escape processing; false to disable it
Throws:
SQLException - if an error occurs setting the underlying JDBC technology-enabled driver to process the escape syntax

getQueryTimeout

public int getQueryTimeout()
                    throws SQLException
Retrieves the maximum number of seconds the driver will wait for a query to execute. If the limit is exceeded, an SQLException is thrown.

Returns:
the current query timeout limit in seconds; zero means that there is no limit
Throws:
SQLException - if an error occurs in determining the query time-out value

setQueryTimeout

public void setQueryTimeout(int seconds)
                     throws SQLException
Sets to the given number the maximum number of seconds the driver will wait for a query to execute. If the limit is exceeded, an SQLException is thrown.

Parameters:
seconds - the new query time-out limit in seconds; zero means that there is no limit; must not be less than zero
Throws:
SQLException - if an error occurs setting the query time-out or if the query time-out value is less than 0

getShowDeleted

public boolean getShowDeleted()
                       throws SQLException
Retrieves a boolean indicating whether rows marked for deletion appear in the set of current rows. The default value is false.

Note: Allowing deleted rows to remain visible complicates the behavior of some of the methods. However, most RowSet object users can simply ignore this extra detail because only sophisticated applications will likely want to take advantage of this feature.

Returns:
true if deleted rows are visible; false otherwise
Throws:
SQLException - if an error occurs determining if deleted rows are visible or not
See Also:
setShowDeleted(boolean)

setShowDeleted

public void setShowDeleted(boolean value)
                    throws SQLException
Sets the property showDeleted to the given boolean value, which determines whether rows marked for deletion appear in the set of current rows.

Parameters:
value - true if deleted rows should be shown; false otherwise
Throws:
SQLException - if an error occurs setting whether deleted rows are visible or not
See Also:
getShowDeleted()

getEscapeProcessing

public boolean getEscapeProcessing()
                            throws SQLException
Ascertains whether escape processing is enabled for this RowSet object.

Returns:
true if escape processing is turned on; false otherwise
Throws:
SQLException - if an error occurs determining if escape processing is enabled or not or if the internal escape processing trigger has not been enabled

setFetchDirection

public void setFetchDirection(int direction)
                       throws SQLException
Gives the driver a performance hint as to the direction in which the rows in this RowSet object will be processed. The driver may ignore this hint.

A RowSet object inherits the default properties of the ResultSet object from which it got its data. That ResultSet object's default fetch direction is set by the Statement object that created it.

This method applies to a RowSet object only while it is connected to a database using a JDBC driver.

A RowSet object may use this method at any time to change its setting for the fetch direction.

Parameters:
direction - one of ResultSet.FETCH_FORWARD, ResultSet.FETCH_REVERSE, or ResultSet.FETCH_UNKNOWN
Throws:
SQLException - if (1) the RowSet type is TYPE_FORWARD_ONLY and the given fetch direction is not FETCH_FORWARD or (2) the given fetch direction is not one of the following: ResultSet.FETCH_FORWARD, ResultSet.FETCH_REVERSE, or ResultSet.FETCH_UNKNOWN
See Also:
getFetchDirection()

getFetchDirection

public int getFetchDirection()
                      throws SQLException
Retrieves this RowSet object's current setting for the fetch direction. The default type is ResultSet.FETCH_FORWARD

Returns:
one of ResultSet.FETCH_FORWARD, ResultSet.FETCH_REVERSE, or ResultSet.FETCH_UNKNOWN
Throws:
SQLException - if an error occurs in determining the current fetch direction for fetching rows
See Also:
setFetchDirection(int)

setFetchSize

public void setFetchSize(int rows)
                  throws SQLException
Sets the fetch size for this RowSet object to the given number of rows. The fetch size gives a JDBC technology-enabled driver ("JDBC driver") a hint as to the number of rows that should be fetched from the database when more rows are needed for this RowSet object. If the fetch size specified is zero, the driver ignores the value and is free to make its own best guess as to what the fetch size should be.

A RowSet object inherits the default properties of the ResultSet object from which it got its data. That ResultSet object's default fetch size is set by the Statement object that created it.

This method applies to a RowSet object only while it is connected to a database using a JDBC driver. For connected RowSet implementations such as JdbcRowSet, this method has a direct and immediate effect on the underlying JDBC driver.

A RowSet object may use this method at any time to change its setting for the fetch size.

For RowSet implementations such as CachedRowSet, which operate in a disconnected environment, the SyncProvider object being used may leverage the fetch size to poll the data source and retrieve a number of rows that do not exceed the fetch size and that may form a subset of the actual rows returned by the original query. This is an implementation variance determined by the specific SyncProvider object employed by the disconnected RowSet object.

Parameters:
rows - the number of rows to fetch; 0 to let the driver decide what the best fetch size is; must not be less than 0 or more than the maximum number of rows allowed for this RowSet object (the number returned by a call to the method getMaxRows())
Throws:
SQLException - if the specified fetch size is less than 0 or more than the limit for the maximum number of rows
See Also:
getFetchSize()

getFetchSize

public int getFetchSize()
                 throws SQLException
Returns the fetch size for this RowSet object. The default value is zero.

Returns:
the number of rows suggested as the fetch size when this RowSet object needs more rows from the database
Throws:
SQLException - if an error occurs determining the number of rows in the current fetch size
See Also:
setFetchSize(int)

getConcurrency

public int getConcurrency()
                   throws SQLException
Returns the concurrency for this RowSet object. The default is CONCUR_UPDATABLE for both connected and disconnected RowSet objects.

An application can call the method setConcurrency at any time to change a RowSet object's concurrency.

Returns:
the concurrency type for this RowSet object, which must be one of the following: ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE
Throws:
SQLException - if an error occurs getting the concurrency of this RowSet object
See Also:
setConcurrency(int), isReadOnly()

setNull

public void setNull(int parameterIndex,
                    int sqlType)
             throws SQLException
Sets the designated parameter to SQL NULL. Note that the parameter's SQL type must be specified using one of the type codes defined in java.sql.Types. This SQL type is specified in the second parameter.

Note that the second parameter tells the DBMS the data type of the value being set to NULL. Some DBMSs require this information, so it is required in order to make code more portable.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Calls made to the method getParams after this version of setNull has been called will return an Object array containing the parameter values that have been set. In that array, the element that represents the values set with this method will itself be an array. The first element of that array is null. The second element is the value set for sqlType. The parameter number is indicated by an element's position in the array returned by the method getParams, with the first element being the value for the first placeholder parameter, the second element being the value for the second placeholder parameter, and so on. In other words, if the second placeholder parameter is being set to null, the array containing it will be the second element in the array returned by getParams.

Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
sqlType - an int that is one of the SQL type codes defined in the class Types. If a non-standard sqlType is supplied, this method will not throw a SQLException. This allows implicit support for non-standard SQL types.
Throws:
SQLException - if a database access error occurs or the given parameter index is out of bounds
See Also:
getParams()

setNull

public void setNull(int parameterIndex,
                    int sqlType,
                    String typeName)
             throws SQLException
Sets the designated parameter to SQL NULL. Although this version of the method setNull is intended for user-defined and REF parameters, this method may be used to set a null parameter for any JDBC type. The following are user-defined types: STRUCT, DISTINCT, and JAVA_OBJECT, and named array types.

Note: To be portable, applications must give the SQL type code and the fully qualified SQL type name when specifying a NULL user-defined or REF parameter. In the case of a user-defined type, the name is the type name of the parameter itself. For a REF parameter, the name is the type name of the referenced type. If a JDBC technology-enabled driver does not need the type code or type name information, it may ignore it.

If the parameter does not have a user-defined or REF type, the given typeName parameter is ignored.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Calls made to the method getParams after this version of setNull has been called will return an Object array containing the parameter values that have been set. In that array, the element that represents the values set with this method will itself be an array. The first element of that array is null. The second element is the value set for sqlType, and the third element is the value set for typeName. The parameter number is indicated by an element's position in the array returned by the method getParams, with the first element being the value for the first placeholder parameter, the second element being the value for the second placeholder parameter, and so on. In other words, if the second placeholder parameter is being set to null, the array containing it will be the second element in the array returned by getParams.

Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
sqlType - a value from java.sql.Types
typeName - the fully qualified name of an SQL user-defined type, which is ignored if the parameter is not a user-defined type or REF value
Throws:
SQLException - if an error occurs or the given parameter index is out of bounds
See Also:
getParams()

setBoolean

public void setBoolean(int parameterIndex,
                       boolean x)
                throws SQLException
Sets the designated parameter to the given boolean in the Java programming language. The driver converts this to an SQL BIT value when it sends it to the database.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute, populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - the parameter value
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

setByte

public void setByte(int parameterIndex,
                    byte x)
             throws SQLException
Sets the designated parameter to the given byte in the Java programming language. The driver converts this to an SQL TINYINT value when it sends it to the database.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - the parameter value
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

setShort

public void setShort(int parameterIndex,
                     short x)
              throws SQLException
Sets the designated parameter to the given short in the Java programming language. The driver converts this to an SQL SMALLINT value when it sends it to the database.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - the parameter value
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

setInt

public void setInt(int parameterIndex,
                   int x)
            throws SQLException
Sets the designated parameter to an int in the Java programming language. The driver converts this to an SQL INTEGER value when it sends it to the database.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - the parameter value
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

setLong

public void setLong(int parameterIndex,
                    long x)
             throws SQLException
Sets the designated parameter to the given long in the Java programming language. The driver converts this to an SQL BIGINT value when it sends it to the database.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - the parameter value
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

setFloat

public void setFloat(int parameterIndex,
                     float x)
              throws SQLException
Sets the designated parameter to the given float in the Java programming language. The driver converts this to an SQL FLOAT value when it sends it to the database.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - the parameter value
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

setDouble

public void setDouble(int parameterIndex,
                      double x)
               throws SQLException
Sets the designated parameter to the given double in the Java programming language. The driver converts this to an SQL DOUBLE value when it sends it to the database.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class. S

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - the parameter value
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

setBigDecimal

public void setBigDecimal(int parameterIndex,
                          BigDecimal x)
                   throws SQLException
Sets the designated parameter to the given java.lang.BigDecimal value. The driver converts this to an SQL NUMERIC value when it sends it to the database.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

Note: JdbcRowSet does not require the populate method as it is undefined in this class.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - the parameter value
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

setString

public void setString(int parameterIndex,
                      String x)
               throws SQLException
Sets the designated parameter to the given String value. The driver converts this to an SQL VARCHAR or LONGVARCHAR value (depending on the argument's size relative to the driver's limits on VARCHAR values) when it sends it to the database.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - the parameter value
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

setBytes

public void setBytes(int parameterIndex,
                     byte[] x)
              throws SQLException
Sets the designated parameter to the given array of bytes. The driver converts this to an SQL VARBINARY or LONGVARBINARY value (depending on the argument's size relative to the driver's limits on VARBINARY values) when it sends it to the database.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - the parameter value
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

setDate

public void setDate(int parameterIndex,
                    Date x)
             throws SQLException
Sets the designated parameter to the given java.sql.Date value. The driver converts this to an SQL DATE value when it sends it to the database.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Calls made to the method getParams after this version of setDate has been called will return an array with the value to be set for placeholder parameter number parameterIndex being the Date object supplied as the second parameter. Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - the parameter value
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

setTime

public void setTime(int parameterIndex,
                    Time x)
             throws SQLException
Sets the designated parameter to the given java.sql.Time value. The driver converts this to an SQL TIME value when it sends it to the database.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Calls made to the method getParams after this version of the method setTime has been called will return an array of the parameters that have been set. The parameter to be set for parameter placeholder number parameterIndex will be the Time object that was set as the second parameter to this method.

Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - a java.sql.Time object, which is to be set as the value for placeholder parameter parameterIndex
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

setTimestamp

public void setTimestamp(int parameterIndex,
                         Timestamp x)
                  throws SQLException
Sets the designated parameter to the given java.sql.Timestamp value. The driver converts this to an SQL TIMESTAMP value when it sends it to the database.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Calls made to the method getParams after this version of setTimestamp has been called will return an array with the value for parameter placeholder number parameterIndex being the Timestamp object that was supplied as the second parameter to this method. Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - a java.sql.Timestamp object
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

setAsciiStream

public void setAsciiStream(int parameterIndex,
                           InputStream x,
                           int length)
                    throws SQLException
Sets the designated parameter to the given java.io.InputStream object, which will have the specified number of bytes. The contents of the stream will be read and sent to the database. This method throws an SQLException object if the number of bytes read and sent to the database is not equal to length.

When a very large ASCII value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream object. A JDBC technology-enabled driver will read the data from the stream as needed until it reaches end-of-file. The driver will do any necessary conversion from ASCII to the database CHAR format.

Note: This stream object can be either a standard Java stream object or your own subclass that implements the standard interface.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

Note: JdbcRowSet does not require the populate method as it is undefined in this class.

Calls made to the method getParams after setAsciiStream has been called will return an array containing the parameter values that have been set. The element in the array that represents the values set with this method will itself be an array. The first element of that array is the given java.io.InputStream object. The second element is the value set for length. The third element is an internal BaseRowSet constant specifying that the stream passed to this method is an ASCII stream. The parameter number is indicated by an element's position in the array returned by the method getParams, with the first element being the value for the first placeholder parameter, the second element being the value for the second placeholder parameter, and so on. In other words, if the input stream being set is the value for the second placeholder parameter, the array containing it will be the second element in the array returned by getParams.

Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is element number parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - the Java input stream that contains the ASCII parameter value
length - the number of bytes in the stream. This is the number of bytes the driver will send to the DBMS; lengths of 0 or less are are undefined but will cause an invalid length exception to be thrown in the underlying JDBC driver.
Throws:
SQLException - if an error occurs, the parameter index is out of bounds, or when connected to a data source, the number of bytes the driver reads and sends to the database is not equal to the number of bytes specified in length
See Also:
getParams()

setAsciiStream

public void setAsciiStream(int parameterIndex,
                           InputStream x)
                    throws SQLException
Sets the designated parameter in this RowSet object's command to the given input stream. When a very large ASCII value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream. Data will be read from the stream as needed until end-of-file is reached. The JDBC driver will do any necessary conversion from ASCII to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setAsciiStream which takes a length parameter.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the Java input stream that contains the ASCII parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed PreparedStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setBinaryStream

public void setBinaryStream(int parameterIndex,
                            InputStream x,
                            int length)
                     throws SQLException
Sets the designated parameter to the given java.io.InputStream object, which will have the specified number of bytes. The contents of the stream will be read and sent to the database. This method throws an SQLException object if the number of bytes read and sent to the database is not equal to length.

When a very large binary value is input to a LONGVARBINARY parameter, it may be more practical to send it via a java.io.InputStream object. A JDBC technology-enabled driver will read the data from the stream as needed until it reaches end-of-file.

Note: This stream object can be either a standard Java stream object or your own subclass that implements the standard interface.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Calls made to the method getParams after setBinaryStream has been called will return an array containing the parameter values that have been set. In that array, the element that represents the values set with this method will itself be an array. The first element of that array is the given java.io.InputStream object. The second element is the value set for length. The third element is an internal BaseRowSet constant specifying that the stream passed to this method is a binary stream. The parameter number is indicated by an element's position in the array returned by the method getParams, with the first element being the value for the first placeholder parameter, the second element being the value for the second placeholder parameter, and so on. In other words, if the input stream being set is the value for the second placeholder parameter, the array containing it will be the second element in the array returned by getParams.

Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is element number parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - the input stream that contains the binary value to be set
length - the number of bytes in the stream; lengths of 0 or less are are undefined but will cause an invalid length exception to be thrown in the underlying JDBC driver.
Throws:
SQLException - if an error occurs, the parameter index is out of bounds, or when connected to a data source, the number of bytes the driver reads and sends to the database is not equal to the number of bytes specified in length
See Also:
getParams()

setBinaryStream

public void setBinaryStream(int parameterIndex,
                            InputStream x)
                     throws SQLException
Sets the designated parameter in this RowSet object's command to the given input stream. When a very large binary value is input to a LONGVARBINARY parameter, it may be more practical to send it via a java.io.InputStream object. The data will be read from the stream as needed until end-of-file is reached.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setBinaryStream which takes a length parameter.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the java input stream which contains the binary parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed PreparedStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setUnicodeStream

public void setUnicodeStream(int parameterIndex,
                             InputStream x,
                             int length)
                      throws SQLException
Deprecated. getCharacterStream should be used in its place

Sets the designated parameter to the given java.io.InputStream object, which will have the specified number of bytes. The contents of the stream will be read and sent to the database. This method throws an SQLException if the number of bytes read and sent to the database is not equal to length.

When a very large Unicode value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream object. A JDBC technology-enabled driver will read the data from the stream as needed, until it reaches end-of-file. The driver will do any necessary conversion from Unicode to the database CHAR format. The byte format of the Unicode stream must be Java UTF-8, as defined in the Java Virtual Machine Specification.

Note: This stream object can be either a standard Java stream object or your own subclass that implements the standard interface.

This method is deprecated; the method getCharacterStream should be used in its place.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Calls made to the method getParams after setUnicodeStream has been called will return an array containing the parameter values that have been set. In that array, the element that represents the values set with this method will itself be an array. The first element of that array is the given java.io.InputStream object. The second element is the value set for length. The third element is an internal BaseRowSet constant specifying that the stream passed to this method is a Unicode stream. The parameter number is indicated by an element's position in the array returned by the method getParams, with the first element being the value for the first placeholder parameter, the second element being the value for the second placeholder parameter, and so on. In other words, if the input stream being set is the value for the second placeholder parameter, the array containing it will be the second element in the array returned by getParams.

Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is element number parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - the java.io.InputStream object that contains the UNICODE parameter value
length - the number of bytes in the input stream
Throws:
SQLException - if an error occurs, the parameter index is out of bounds, or the number of bytes the driver reads and sends to the database is not equal to the number of bytes specified in length
See Also:
getParams()

setCharacterStream

public void setCharacterStream(int parameterIndex,
                               Reader reader,
                               int length)
                        throws SQLException
Sets the designated parameter to the given java.io.Reader object, which will have the specified number of characters. The contents of the reader will be read and sent to the database. This method throws an SQLException if the number of bytes read and sent to the database is not equal to length.

When a very large Unicode value is input to a LONGVARCHAR parameter, it may be more practical to send it via a Reader object. A JDBC technology-enabled driver will read the data from the stream as needed until it reaches end-of-file. The driver will do any necessary conversion from Unicode to the database CHAR format. The byte format of the Unicode stream must be Java UTF-8, as defined in the Java Virtual Machine Specification.

Note: This stream object can be either a standard Java stream object or your own subclass that implements the standard interface.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Calls made to the method getParams after setCharacterStream has been called will return an array containing the parameter values that have been set. In that array, the element that represents the values set with this method will itself be an array. The first element of that array is the given java.io.Reader object. The second element is the value set for length. The parameter number is indicated by an element's position in the array returned by the method getParams, with the first element being the value for the first placeholder parameter, the second element being the value for the second placeholder parameter, and so on. In other words, if the reader being set is the value for the second placeholder parameter, the array containing it will be the second element in the array returned by getParams.

Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is element number parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
reader - the Reader object that contains the Unicode data
length - the number of characters in the stream; lengths of 0 or less are undefined but will cause an invalid length exception to be thrown in the underlying JDBC driver.
Throws:
SQLException - if an error occurs, the parameter index is out of bounds, or when connected to a data source, the number of bytes the driver reads and sends to the database is not equal to the number of bytes specified in length
See Also:
getParams()

setCharacterStream

public void setCharacterStream(int parameterIndex,
                               Reader reader)
                        throws SQLException
Sets the designated parameter in this RowSet object's command to the given Reader object. When a very large UNICODE value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.Reader object. The data will be read from the stream as needed until end-of-file is reached. The JDBC driver will do any necessary conversion from UNICODE to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setCharacterStream which takes a length parameter.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
reader - the java.io.Reader object that contains the Unicode data
Throws:
SQLException - if a database access error occurs or this method is called on a closed PreparedStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setObject

public void setObject(int parameterIndex,
                      Object x,
                      int targetSqlType,
                      int scale)
               throws SQLException
Sets the designated parameter to an Object in the Java programming language. The second parameter must be an Object type. For integral values, the java.lang equivalent objects should be used. For example, use the class Integer for an int.

The driver converts this object to the specified target SQL type before sending it to the database. If the object has a custom mapping (is of a class implementing SQLData), the driver should call the method SQLData.writeSQL to write the object to the SQL data stream. If, on the other hand, the object is of a class implementing Ref, Blob, Clob, Struct, or Array, the driver should pass it to the database as a value of the corresponding SQL type.

Note that this method may be used to pass database- specific abstract data types.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSetexecute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Calls made to the method getParams after this version of setObject has been called will return an array containing the parameter values that have been set. In that array, the element that represents the values set with this method will itself be an array. The first element of that array is the given Object instance, and the second element is the value set for targetSqlType. The third element is the value set for scale, which the driver will ignore if the type of the object being set is not java.sql.Types.NUMERIC or java.sql.Types.DECIMAL. The parameter number is indicated by an element's position in the array returned by the method getParams, with the first element being the value for the first placeholder parameter, the second element being the value for the second placeholder parameter, and so on. In other words, if the object being set is the value for the second placeholder parameter, the array containing it will be the second element in the array returned by getParams.

Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is element number parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - the Object containing the input parameter value; must be an Object type
targetSqlType - the SQL type (as defined in java.sql.Types) to be sent to the database. The scale argument may further qualify this type. If a non-standard targetSqlType is supplied, this method will not throw a SQLException. This allows implicit support for non-standard SQL types.
scale - for the types java.sql.Types.DECIMAL and java.sql.Types.NUMERIC, this is the number of digits after the decimal point. For all other types, this value will be ignored.
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

setObject

public void setObject(int parameterIndex,
                      Object x,
                      int targetSqlType)
               throws SQLException
Sets the value of the designated parameter with the given Object value. This method is like setObject(int parameterIndex, Object x, int targetSqlType, int scale) except that it assumes a scale of zero.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Calls made to the method getParams after this version of setObject has been called will return an array containing the parameter values that have been set. In that array, the element that represents the values set with this method will itself be an array. The first element of that array is the given Object instance. The second element is the value set for targetSqlType. The parameter number is indicated by an element's position in the array returned by the method getParams, with the first element being the value for the first placeholder parameter, the second element being the value for the second placeholder parameter, and so on. In other words, if the object being set is the value for the second placeholder parameter, the array containing it will be the second element in the array returned by getParams.

Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is element number parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - the Object containing the input parameter value; must be an Object type
targetSqlType - the SQL type (as defined in java.sql.Types) to be sent to the database. If a non-standard targetSqlType is supplied, this method will not throw a SQLException. This allows implicit support for non-standard SQL types.
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

setObject

public void setObject(int parameterIndex,
                      Object x)
               throws SQLException
Sets the designated parameter to an Object in the Java programming language. The second parameter must be an Object type. For integral values, the java.lang equivalent objects should be used. For example, use the class Integer for an int.

The JDBC specification defines a standard mapping from Java Object types to SQL types. The driver will use this standard mapping to convert the given object to its corresponding SQL type before sending it to the database. If the object has a custom mapping (is of a class implementing SQLData), the driver should call the method SQLData.writeSQL to write the object to the SQL data stream.

If, on the other hand, the object is of a class implementing Ref, Blob, Clob, Struct, or Array, the driver should pass it to the database as a value of the corresponding SQL type.

This method throws an exception if there is an ambiguity, for example, if the object is of a class implementing more than one interface.

Note that this method may be used to pass database-specific abstract data types.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

After this method has been called, a call to the method getParams will return an object array of the current command parameters, which will include the Object set for placeholder parameter number parameterIndex. Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is element number parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - the object containing the input parameter value
Throws:
SQLException - if an error occurs the parameter index is out of bounds, or there is ambiguity in the implementation of the object being set
See Also:
getParams()

setRef

public void setRef(int parameterIndex,
                   Ref ref)
            throws SQLException
Sets the designated parameter to the given Ref object in the Java programming language. The driver converts this to an SQL REF value when it sends it to the database. Internally, the Ref is represented as a SerialRef to ensure serializability.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

After this method has been called, a call to the method getParams will return an object array of the current command parameters, which will include the Ref object set for placeholder parameter number parameterIndex. Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is element number parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
ref - a Ref object representing an SQL REF value; cannot be null
Throws:
SQLException - if an error occurs; the parameter index is out of bounds or the Ref object is null; or the Ref object returns a null base type name.
See Also:
getParams(), SerialRef

setBlob

public void setBlob(int parameterIndex,
                    Blob x)
             throws SQLException
Sets the designated parameter to the given Blob object in the Java programming language. The driver converts this to an SQL BLOB value when it sends it to the database. Internally, the Blob is represented as a SerialBlob to ensure serializability.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces. NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

After this method has been called, a call to the method getParams will return an object array of the current command parameters, which will include the Blob object set for placeholder parameter number parameterIndex. Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is element number parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - a Blob object representing an SQL BLOB value
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams(), SerialBlob

setClob

public void setClob(int parameterIndex,
                    Clob x)
             throws SQLException
Sets the designated parameter to the given Clob object in the Java programming language. The driver converts this to an SQL CLOB value when it sends it to the database. Internally, the Clob is represented as a SerialClob to ensure serializability.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

After this method has been called, a call to the method getParams will return an object array of the current command parameters, which will include the Clob object set for placeholder parameter number parameterIndex. Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is element number parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - a Clob object representing an SQL CLOB value; cannot be null
Throws:
SQLException - if an error occurs; the parameter index is out of bounds or the Clob is null
See Also:
getParams(), SerialBlob

setArray

public void setArray(int parameterIndex,
                     Array array)
              throws SQLException
Sets the designated parameter to an Array object in the Java programming language. The driver converts this to an SQL ARRAY value when it sends it to the database. Internally, the Array is represented as a SerialArray to ensure serializability.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

Note: JdbcRowSet does not require the populate method as it is undefined in this class.

After this method has been called, a call to the method getParams will return an object array of the current command parameters, which will include the Array object set for placeholder parameter number parameterIndex. Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is element number parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
array - an Array object representing an SQL ARRAY value; cannot be null. The Array object passed to this method must return a non-null Object for all getArray() method calls. A null value will cause a SQLException to be thrown.
Throws:
SQLException - if an error occurs; the parameter index is out of bounds or the ARRAY is null
See Also:
getParams(), SerialArray

setDate

public void setDate(int parameterIndex,
                    Date x,
                    Calendar cal)
             throws SQLException
Sets the designated parameter to the given java.sql.Date object. When the DBMS does not store time zone information, the driver will use the given Calendar object to construct the SQL DATE value to send to the database. With a Calendar object, the driver can calculate the date taking into account a custom time zone. If no Calendar object is specified, the driver uses the time zone of the Virtual Machine that is running the application.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Calls made to the method getParams after this version of setDate has been called will return an array containing the parameter values that have been set. In that array, the element that represents the values set with this method will itself be an array. The first element of that array is the given java.sql.Date object. The second element is the value set for cal. The parameter number is indicated by an element's position in the array returned by the method getParams, with the first element being the value for the first placeholder parameter, the second element being the value for the second placeholder parameter, and so on. In other words, if the date being set is the value for the second placeholder parameter, the array containing it will be the second element in the array returned by getParams.

Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - a java.sql.Date object representing an SQL DATE value
cal - a java.util.Calendar object to use when when constructing the date
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

setTime

public void setTime(int parameterIndex,
                    Time x,
                    Calendar cal)
             throws SQLException
Sets the designated parameter to the given java.sql.Time object. The driver converts this to an SQL TIME value when it sends it to the database.

When the DBMS does not store time zone information, the driver will use the given Calendar object to construct the SQL TIME value to send to the database. With a Calendar object, the driver can calculate the date taking into account a custom time zone. If no Calendar object is specified, the driver uses the time zone of the Virtual Machine that is running the application.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Calls made to the method getParams after this version of setTime has been called will return an array containing the parameter values that have been set. In that array, the element that represents the values set with this method will itself be an array. The first element of that array is the given java.sql.Time object. The second element is the value set for cal. The parameter number is indicated by an element's position in the array returned by the method getParams, with the first element being the value for the first placeholder parameter, the second element being the value for the second placeholder parameter, and so on. In other words, if the time being set is the value for the second placeholder parameter, the array containing it will be the second element in the array returned by getParams.

Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - a java.sql.Time object
cal - the java.util.Calendar object the driver can use to construct the time
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

setTimestamp

public void setTimestamp(int parameterIndex,
                         Timestamp x,
                         Calendar cal)
                  throws SQLException
Sets the designated parameter to the given java.sql.Timestamp object. The driver converts this to an SQL TIMESTAMP value when it sends it to the database.

When the DBMS does not store time zone information, the driver will use the given Calendar object to construct the SQL TIMESTAMP value to send to the database. With a Calendar object, the driver can calculate the timestamp taking into account a custom time zone. If no Calendar object is specified, the driver uses the time zone of the Virtual Machine that is running the application.

The parameter value set by this method is stored internally and will be supplied as the appropriate parameter in this RowSet object's command when the method execute is called. Methods such as execute and populate must be provided in any class that extends this class and implements one or more of the standard JSR-114 RowSet interfaces.

NOTE: JdbcRowSet does not require the populate method as it is undefined in this class.

Calls made to the method getParams after this version of setTimestamp has been called will return an array containing the parameter values that have been set. In that array, the element that represents the values set with this method will itself be an array. The first element of that array is the given java.sql.Timestamp object. The second element is the value set for cal. The parameter number is indicated by an element's position in the array returned by the method getParams, with the first element being the value for the first placeholder parameter, the second element being the value for the second placeholder parameter, and so on. In other words, if the timestamp being set is the value for the second placeholder parameter, the array containing it will be the second element in the array returned by getParams.

Note that because the numbering of elements in an array starts at zero, the array element that corresponds to placeholder parameter number parameterIndex is parameterIndex -1.

Parameters:
parameterIndex - the ordinal number of the placeholder parameter in this RowSet object's command that is to be set. The first parameter is 1, the second is 2, and so on; must be 1 or greater
x - a java.sql.Timestamp object
cal - the java.util.Calendar object the driver can use to construct the timestamp
Throws:
SQLException - if an error occurs or the parameter index is out of bounds
See Also:
getParams()

clearParameters

public void clearParameters()
                     throws SQLException
Clears all of the current parameter values in this RowSet object's internal representation of the parameters to be set in this RowSet object's command when it is executed.

In general, parameter values remain in force for repeated use in this RowSet object's command. Setting a parameter value with the setter methods automatically clears the value of the designated parameter and replaces it with the new specified value.

This method is called internally by the setCommand method to clear all of the parameters set for the previous command.

Furthermore, this method differs from the initParams method in that it maintains the schema of the RowSet object.

Throws:
SQLException - if an error occurs clearing the parameters

getParams

public Object[] getParams()
                   throws SQLException
Retrieves an array containing the parameter values (both Objects and primitives) that have been set for this RowSet object's command and throws an SQLException object if all parameters have not been set. Before the command is sent to the DBMS to be executed, these parameters will be substituted for placeholder parameters in the PreparedStatement object that is the command for a RowSet implementation extending the BaseRowSet class.

Each element in the array that is returned is an Object instance that contains the values of the parameters supplied to a setter method. The order of the elements is determined by the value supplied for parameterIndex. If the setter method takes only the parameter index and the value to be set (possibly null), the array element will contain the value to be set (which will be expressed as an Object). If there are additional parameters, the array element will itself be an array containing the value to be set plus any additional parameter values supplied to the setter method. If the method sets a stream, the array element includes the type of stream being supplied to the method. These additional parameters are for the use of the driver or the DBMS and may or may not be used.

NOTE: Stored parameter values of types Array, Blob, Clob and Ref are returned as SerialArray, SerialBlob, SerialClob and SerialRef respectively.

Returns:
an array of Object instances that includes the parameter values that may be set in this RowSet object's command; an empty array if no parameters have been set
Throws:
SQLException - if an error occurs retrieveing the object array of parameters of this RowSet object or if not all parameters have been set

setNull

public void setNull(String parameterName,
                    int sqlType)
             throws SQLException
Sets the designated parameter to SQL NULL.

Note: You must specify the parameter's SQL type.

Parameters:
parameterName - the name of the parameter
sqlType - the SQL type code defined in java.sql.Types
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4

setNull

public void setNull(String parameterName,
                    int sqlType,
                    String typeName)
             throws SQLException
Sets the designated parameter to SQL NULL. This version of the method setNull should be used for user-defined types and REF type parameters. Examples of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and named array types.

Note: To be portable, applications must give the SQL type code and the fully-qualified SQL type name when specifying a NULL user-defined or REF parameter. In the case of a user-defined type the name is the type name of the parameter itself. For a REF parameter, the name is the type name of the referenced type. If a JDBC driver does not need the type code or type name information, it may ignore it. Although it is intended for user-defined and Ref parameters, this method may be used to set a null parameter of any JDBC type. If the parameter does not have a user-defined or REF type, the given typeName is ignored.

Parameters:
parameterName - the name of the parameter
sqlType - a value from java.sql.Types
typeName - the fully-qualified name of an SQL user-defined type; ignored if the parameter is not a user-defined type or SQL REF value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4

setBoolean

public void setBoolean(String parameterName,
                       boolean x)
                throws SQLException
Sets the designated parameter to the given Java boolean value. The driver converts this to an SQL BIT or BOOLEAN value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
#getBoolean

setByte

public void setByte(String parameterName,
                    byte x)
             throws SQLException
Sets the designated parameter to the given Java byte value. The driver converts this to an SQL TINYINT value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
#getByte

setShort

public void setShort(String parameterName,
                     short x)
              throws SQLException
Sets the designated parameter to the given Java short value. The driver converts this to an SQL SMALLINT value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
#getShort

setInt

public void setInt(String parameterName,
                   int x)
            throws SQLException
Sets the designated parameter to the given Java int value. The driver converts this to an SQL INTEGER value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
#getInt

setLong

public void setLong(String parameterName,
                    long x)
             throws SQLException
Sets the designated parameter to the given Java long value. The driver converts this to an SQL BIGINT value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
#getLong

setFloat

public void setFloat(String parameterName,
                     float x)
              throws SQLException
Sets the designated parameter to the given Java float value. The driver converts this to an SQL FLOAT value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
#getFloat

setDouble

public void setDouble(String parameterName,
                      double x)
               throws SQLException
Sets the designated parameter to the given Java double value. The driver converts this to an SQL DOUBLE value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
#getDouble

setBigDecimal

public void setBigDecimal(String parameterName,
                          BigDecimal x)
                   throws SQLException
Sets the designated parameter to the given java.math.BigDecimal value. The driver converts this to an SQL NUMERIC value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
#getBigDecimal

setString

public void setString(String parameterName,
                      String x)
               throws SQLException
Sets the designated parameter to the given Java String value. The driver converts this to an SQL VARCHAR or LONGVARCHAR value (depending on the argument's size relative to the driver's limits on VARCHAR values) when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
#getString

setBytes

public void setBytes(String parameterName,
                     byte[] x)
              throws SQLException
Sets the designated parameter to the given Java array of bytes. The driver converts this to an SQL VARBINARY or LONGVARBINARY (depending on the argument's size relative to the driver's limits on VARBINARY values) when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
#getBytes

setTimestamp

public void setTimestamp(String parameterName,
                         Timestamp x)
                  throws SQLException
Sets the designated parameter to the given java.sql.Timestamp value. The driver converts this to an SQL TIMESTAMP value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
#getTimestamp

setAsciiStream

public void setAsciiStream(String parameterName,
                           InputStream x,
                           int length)
                    throws SQLException
Sets the designated parameter to the given input stream, which will have the specified number of bytes. When a very large ASCII value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream. Data will be read from the stream as needed until end-of-file is reached. The JDBC driver will do any necessary conversion from ASCII to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Parameters:
parameterName - the name of the parameter
x - the Java input stream that contains the ASCII parameter value
length - the number of bytes in the stream
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4

setBinaryStream

public void setBinaryStream(String parameterName,
                            InputStream x,
                            int length)
                     throws SQLException
Sets the designated parameter to the given input stream, which will have the specified number of bytes. When a very large binary value is input to a LONGVARBINARY parameter, it may be more practical to send it via a java.io.InputStream object. The data will be read from the stream as needed until end-of-file is reached.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Parameters:
parameterName - the name of the parameter
x - the java input stream which contains the binary parameter value
length - the number of bytes in the stream
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4

setCharacterStream

public void setCharacterStream(String parameterName,
                               Reader reader,
                               int length)
                        throws SQLException
Sets the designated parameter to the given Reader object, which is the given number of characters long. When a very large UNICODE value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.Reader object. The data will be read from the stream as needed until end-of-file is reached. The JDBC driver will do any necessary conversion from UNICODE to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Parameters:
parameterName - the name of the parameter
reader - the java.io.Reader object that contains the UNICODE data used as the designated parameter
length - the number of characters in the stream
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4

setAsciiStream

public void setAsciiStream(String parameterName,
                           InputStream x)
                    throws SQLException
Sets the designated parameter to the given input stream. When a very large ASCII value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream. Data will be read from the stream as needed until end-of-file is reached. The JDBC driver will do any necessary conversion from ASCII to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setAsciiStream which takes a length parameter.

Parameters:
parameterName - the name of the parameter
x - the Java input stream that contains the ASCII parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setBinaryStream

public void setBinaryStream(String parameterName,
                            InputStream x)
                     throws SQLException
Sets the designated parameter to the given input stream. When a very large binary value is input to a LONGVARBINARY parameter, it may be more practical to send it via a java.io.InputStream object. The data will be read from the stream as needed until end-of-file is reached.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setBinaryStream which takes a length parameter.

Parameters:
parameterName - the name of the parameter
x - the java input stream which contains the binary parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setCharacterStream

public void setCharacterStream(String parameterName,
                               Reader reader)
                        throws SQLException
Sets the designated parameter to the given Reader object. When a very large UNICODE value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.Reader object. The data will be read from the stream as needed until end-of-file is reached. The JDBC driver will do any necessary conversion from UNICODE to the database char format.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setCharacterStream which takes a length parameter.

Parameters:
parameterName - the name of the parameter
reader - the java.io.Reader object that contains the Unicode data
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setNCharacterStream

public void setNCharacterStream(int parameterIndex,
                                Reader value)
                         throws SQLException
Sets the designated parameter in this RowSet object's command to a Reader object. The Reader reads the data till end-of-file is reached. The driver does the necessary conversion from Java character format to the national character set in the database.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setNCharacterStream which takes a length parameter.

Parameters:
parameterIndex - of the first parameter is 1, the second is 2, ...
value - the parameter value
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur ; if a database access error occurs; or this method is called on a closed PreparedStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setObject

public void setObject(String parameterName,
                      Object x,
                      int targetSqlType,
                      int scale)
               throws SQLException
Sets the value of the designated parameter with the given object. The second argument must be an object type; for integral values, the java.lang equivalent objects should be used.

The given Java object will be converted to the given targetSqlType before being sent to the database. If the object has a custom mapping (is of a class implementing the interface SQLData), the JDBC driver should call the method SQLData.writeSQL to write it to the SQL data stream. If, on the other hand, the object is of a class implementing Ref, Blob, Clob, NClob, Struct, java.net.URL, or Array, the driver should pass it to the database as a value of the corresponding SQL type.

Note that this method may be used to pass datatabase- specific abstract data types.

Parameters:
parameterName - the name of the parameter
x - the object containing the input parameter value
targetSqlType - the SQL type (as defined in java.sql.Types) to be sent to the database. The scale argument may further qualify this type.
scale - for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types, this is the number of digits after the decimal point. For all other types, this value will be ignored.
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if targetSqlType is a ARRAY, BLOB, CLOB, DATALINK, JAVA_OBJECT, NCHAR, NCLOB, NVARCHAR, LONGNVARCHAR, REF, ROWID, SQLXML or STRUCT data type and the JDBC driver does not support this data type
Since:
1.4
See Also:
Types, #getObject

setObject

public void setObject(String parameterName,
                      Object x,
                      int targetSqlType)
               throws SQLException
Sets the value of the designated parameter with the given object. This method is like the method setObject above, except that it assumes a scale of zero.

Parameters:
parameterName - the name of the parameter
x - the object containing the input parameter value
targetSqlType - the SQL type (as defined in java.sql.Types) to be sent to the database
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if targetSqlType is a ARRAY, BLOB, CLOB, DATALINK, JAVA_OBJECT, NCHAR, NCLOB, NVARCHAR, LONGNVARCHAR, REF, ROWID, SQLXML or STRUCT data type and the JDBC driver does not support this data type
Since:
1.4
See Also:
#getObject

setObject

public void setObject(String parameterName,
                      Object x)
               throws SQLException
Sets the value of the designated parameter with the given object. The second parameter must be of type Object; therefore, the java.lang equivalent objects should be used for built-in types.

The JDBC specification specifies a standard mapping from Java Object types to SQL types. The given argument will be converted to the corresponding SQL type before being sent to the database.

Note that this method may be used to pass datatabase- specific abstract data types, by using a driver-specific Java type. If the object is of a class implementing the interface SQLData, the JDBC driver should call the method SQLData.writeSQL to write it to the SQL data stream. If, on the other hand, the object is of a class implementing Ref, Blob, Clob, NClob, Struct, java.net.URL, or Array, the driver should pass it to the database as a value of the corresponding SQL type.

This method throws an exception if there is an ambiguity, for example, if the object is of a class implementing more than one of the interfaces named above.

Parameters:
parameterName - the name of the parameter
x - the object containing the input parameter value
Throws:
SQLException - if a database access error occurs, this method is called on a closed CallableStatement or if the given Object parameter is ambiguous
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
#getObject

setBlob

public void setBlob(int parameterIndex,
                    InputStream inputStream,
                    long length)
             throws SQLException
Sets the designated parameter to a InputStream object. The inputstream must contain the number of characters specified by length otherwise a SQLException will be generated when the PreparedStatement is executed. This method differs from the setBinaryStream (int, InputStream, int) method because it informs the driver that the parameter value should be sent to the server as a BLOB. When the setBinaryStream method is used, the driver may have to do extra work to determine whether the parameter data should be sent to the server as a LONGVARBINARY or a BLOB

Parameters:
parameterIndex - index of the first parameter is 1, the second is 2, ...
inputStream - An object that contains the data to set the parameter value to.
length - the number of bytes in the parameter data.
Throws:
SQLException - if a database access error occurs, this method is called on a closed PreparedStatement, if parameterIndex does not correspond to a parameter marker in the SQL statement, if the length specified is less than zero or if the number of bytes in the inputstream does not match the specfied length.
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setBlob

public void setBlob(int parameterIndex,
                    InputStream inputStream)
             throws SQLException
Sets the designated parameter to a InputStream object. This method differs from the setBinaryStream (int, InputStream) method because it informs the driver that the parameter value should be sent to the server as a BLOB. When the setBinaryStream method is used, the driver may have to do extra work to determine whether the parameter data should be sent to the server as a LONGVARBINARY or a BLOB

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setBlob which takes a length parameter.

Parameters:
parameterIndex - index of the first parameter is 1, the second is 2, ...
inputStream - An object that contains the data to set the parameter value to.
Throws:
SQLException - if a database access error occurs, this method is called on a closed PreparedStatement or if parameterIndex does not correspond to a parameter marker in the SQL statement,
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setBlob

public void setBlob(String parameterName,
                    InputStream inputStream,
                    long length)
             throws SQLException
Sets the designated parameter to a InputStream object. The inputstream must contain the number of characters specified by length, otherwise a SQLException will be generated when the CallableStatement is executed. This method differs from the setBinaryStream (int, InputStream, int) method because it informs the driver that the parameter value should be sent to the server as a BLOB. When the setBinaryStream method is used, the driver may have to do extra work to determine whether the parameter data should be sent to the server as a LONGVARBINARY or a BLOB

Parameters:
parameterName - the name of the parameter to be set the second is 2, ...
inputStream - An object that contains the data to set the parameter value to.
length - the number of bytes in the parameter data.
Throws:
SQLException - if parameterIndex does not correspond to a parameter marker in the SQL statement, or if the length specified is less than zero; if the number of bytes in the inputstream does not match the specfied length; if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setBlob

public void setBlob(String parameterName,
                    Blob x)
             throws SQLException
Sets the designated parameter to the given java.sql.Blob object. The driver converts this to an SQL BLOB value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - a Blob object that maps an SQL BLOB value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setBlob

public void setBlob(String parameterName,
                    InputStream inputStream)
             throws SQLException
Sets the designated parameter to a InputStream object. This method differs from the setBinaryStream (int, InputStream) method because it informs the driver that the parameter value should be sent to the server as a BLOB. When the setBinaryStream method is used, the driver may have to do extra work to determine whether the parameter data should be send to the server as a LONGVARBINARY or a BLOB

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setBlob which takes a length parameter.

Parameters:
parameterName - the name of the parameter
inputStream - An object that contains the data to set the parameter value to.
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setClob

public void setClob(int parameterIndex,
                    Reader reader,
                    long length)
             throws SQLException
Sets the designated parameter to a Reader object. The reader must contain the number of characters specified by length otherwise a SQLException will be generated when the PreparedStatement is executed. This method differs from the setCharacterStream (int, Reader, int) method because it informs the driver that the parameter value should be sent to the server as a CLOB. When the setCharacterStream method is used, the driver may have to do extra work to determine whether the parameter data should be sent to the server as a LONGVARCHAR or a CLOB

Parameters:
parameterIndex - index of the first parameter is 1, the second is 2, ...
reader - An object that contains the data to set the parameter value to.
length - the number of characters in the parameter data.
Throws:
SQLException - if a database access error occurs, this method is called on a closed PreparedStatement, if parameterIndex does not correspond to a parameter marker in the SQL statement, or if the length specified is less than zero.
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setClob

public void setClob(int parameterIndex,
                    Reader reader)
             throws SQLException
Sets the designated parameter to a Reader object. This method differs from the setCharacterStream (int, Reader) method because it informs the driver that the parameter value should be sent to the server as a CLOB. When the setCharacterStream method is used, the driver may have to do extra work to determine whether the parameter data should be sent to the server as a LONGVARCHAR or a CLOB

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setClob which takes a length parameter.

Parameters:
parameterIndex - index of the first parameter is 1, the second is 2, ...
reader - An object that contains the data to set the parameter value to.
Throws:
SQLException - if a database access error occurs, this method is called on a closed PreparedStatementor if parameterIndex does not correspond to a parameter marker in the SQL statement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setClob

public void setClob(String parameterName,
                    Reader reader,
                    long length)
             throws SQLException
Sets the designated parameter to a Reader object. The reader must contain the number of characters specified by length otherwise a SQLException will be generated when the CallableStatement is executed. This method differs from the setCharacterStream (int, Reader, int) method because it informs the driver that the parameter value should be sent to the server as a CLOB. When the setCharacterStream method is used, the driver may have to do extra work to determine whether the parameter data should be send to the server as a LONGVARCHAR or a CLOB

Parameters:
parameterName - the name of the parameter to be set
reader - An object that contains the data to set the parameter value to.
length - the number of characters in the parameter data.
Throws:
SQLException - if parameterIndex does not correspond to a parameter marker in the SQL statement; if the length specified is less than zero; a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setClob

public void setClob(String parameterName,
                    Clob x)
             throws SQLException
Sets the designated parameter to the given java.sql.Clob object. The driver converts this to an SQL CLOB value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - a Clob object that maps an SQL CLOB value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setClob

public void setClob(String parameterName,
                    Reader reader)
             throws SQLException
Sets the designated parameter to a Reader object. This method differs from the setCharacterStream (int, Reader) method because it informs the driver that the parameter value should be sent to the server as a CLOB. When the setCharacterStream method is used, the driver may have to do extra work to determine whether the parameter data should be send to the server as a LONGVARCHAR or a CLOB

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setClob which takes a length parameter.

Parameters:
parameterName - the name of the parameter
reader - An object that contains the data to set the parameter value to.
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setDate

public void setDate(String parameterName,
                    Date x)
             throws SQLException
Sets the designated parameter to the given java.sql.Date value using the default time zone of the virtual machine that is running the application. The driver converts this to an SQL DATE value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
#getDate

setDate

public void setDate(String parameterName,
                    Date x,
                    Calendar cal)
             throws SQLException
Sets the designated parameter to the given java.sql.Date value, using the given Calendar object. The driver uses the Calendar object to construct an SQL DATE value, which the driver then sends to the database. With a a Calendar object, the driver can calculate the date taking into account a custom timezone. If no Calendar object is specified, the driver uses the default timezone, which is that of the virtual machine running the application.

Parameters:
parameterName - the name of the parameter
x - the parameter value
cal - the Calendar object the driver will use to construct the date
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
#getDate

setTime

public void setTime(String parameterName,
                    Time x)
             throws SQLException
Sets the designated parameter to the given java.sql.Time value. The driver converts this to an SQL TIME value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
#getTime

setTime

public void setTime(String parameterName,
                    Time x,
                    Calendar cal)
             throws SQLException
Sets the designated parameter to the given java.sql.Time value, using the given Calendar object. The driver uses the Calendar object to construct an SQL TIME value, which the driver then sends to the database. With a a Calendar object, the driver can calculate the time taking into account a custom timezone. If no Calendar object is specified, the driver uses the default timezone, which is that of the virtual machine running the application.

Parameters:
parameterName - the name of the parameter
x - the parameter value
cal - the Calendar object the driver will use to construct the time
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
#getTime

setTimestamp

public void setTimestamp(String parameterName,
                         Timestamp x,
                         Calendar cal)
                  throws SQLException
Sets the designated parameter to the given java.sql.Timestamp value, using the given Calendar object. The driver uses the Calendar object to construct an SQL TIMESTAMP value, which the driver then sends to the database. With a a Calendar object, the driver can calculate the timestamp taking into account a custom timezone. If no Calendar object is specified, the driver uses the default timezone, which is that of the virtual machine running the application.

Parameters:
parameterName - the name of the parameter
x - the parameter value
cal - the Calendar object the driver will use to construct the timestamp
Throws:
SQLException - if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
See Also:
#getTimestamp

setSQLXML

public void setSQLXML(int parameterIndex,
                      SQLXML xmlObject)
               throws SQLException
Sets the designated parameter to the given java.sql.SQLXML object. The driver converts this to an SQL XML value when it sends it to the database.

Parameters:
parameterIndex - index of the first parameter is 1, the second is 2, ...
xmlObject - a SQLXML object that maps an SQL XML value
Throws:
SQLException - if a database access error occurs, this method is called on a closed result set, the java.xml.transform.Result, Writer or OutputStream has not been closed for the SQLXML object or if there is an error processing the XML value. The getCause method of the exception may provide a more detailed exception, for example, if the stream does not contain valid XML.
Since:
1.6

setSQLXML

public void setSQLXML(String parameterName,
                      SQLXML xmlObject)
               throws SQLException
Sets the designated parameter to the given java.sql.SQLXML object. The driver converts this to an SQL XML value when it sends it to the database.

Parameters:
parameterName - the name of the parameter
xmlObject - a SQLXML object that maps an SQL XML value
Throws:
SQLException - if a database access error occurs, this method is called on a closed result set, the java.xml.transform.Result, Writer or OutputStream has not been closed for the SQLXML object or if there is an error processing the XML value. The getCause method of the exception may provide a more detailed exception, for example, if the stream does not contain valid XML.
Since:
1.6

setRowId

public void setRowId(int parameterIndex,
                     RowId x)
              throws SQLException
Sets the designated parameter to the given java.sql.RowId object. The driver converts this to a SQL ROWID value when it sends it to the database

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the parameter value
Throws:
SQLException - if a database access error occurs
Since:
1.6

setRowId

public void setRowId(String parameterName,
                     RowId x)
              throws SQLException
Sets the designated parameter to the given java.sql.RowId object. The driver converts this to a SQL ROWID when it sends it to the database.

Parameters:
parameterName - the name of the parameter
x - the parameter value
Throws:
SQLException - if a database access error occurs
Since:
1.6

setNString

public void setNString(int parameterIndex,
                       String value)
                throws SQLException
Sets the designated paramter to the given String object. The driver converts this to a SQL NCHAR or NVARCHAR or LONGNVARCHAR value (depending on the argument's size relative to the driver's limits on NVARCHAR values) when it sends it to the database.

Parameters:
parameterIndex - of the first parameter is 1, the second is 2, ...
value - the parameter value
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur ; or if a database access error occurs
Since:
1.6

setNString

public void setNString(String parameterName,
                       String value)
                throws SQLException
Sets the designated paramter to the given String object. The driver converts this to a SQL NCHAR or NVARCHAR or LONGNVARCHAR

Parameters:
parameterName - the name of the column to be set
value - the parameter value
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur; or if a database access error occurs
Since:
1.6

setNCharacterStream

public void setNCharacterStream(int parameterIndex,
                                Reader value,
                                long length)
                         throws SQLException
Sets the designated parameter to a Reader object. The Reader reads the data till end-of-file is reached. The driver does the necessary conversion from Java character format to the national character set in the database.

Parameters:
parameterIndex - of the first parameter is 1, the second is 2, ...
value - the parameter value
length - the number of characters in the parameter data.
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur ; or if a database access error occurs
Since:
1.6

setNCharacterStream

public void setNCharacterStream(String parameterName,
                                Reader value,
                                long length)
                         throws SQLException
Sets the designated parameter to a Reader object. The Reader reads the data till end-of-file is reached. The driver does the necessary conversion from Java character format to the national character set in the database.

Parameters:
parameterName - the name of the column to be set
value - the parameter value
length - the number of characters in the parameter data.
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur; or if a database access error occurs
Since:
1.6

setNCharacterStream

public void setNCharacterStream(String parameterName,
                                Reader value)
                         throws SQLException
Sets the designated parameter to a Reader object. The Reader reads the data till end-of-file is reached. The driver does the necessary conversion from Java character format to the national character set in the database.

Note: This stream object can either be a standard Java stream object or your own subclass that implements the standard interface.

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setNCharacterStream which takes a length parameter.

Parameters:
parameterName - the name of the parameter
value - the parameter value
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur ; if a database access error occurs; or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setNClob

public void setNClob(String parameterName,
                     NClob value)
              throws SQLException
Sets the designated parameter to a java.sql.NClob object. The object implements the java.sql.NClob interface. This NClob object maps to a SQL NCLOB.

Parameters:
parameterName - the name of the column to be set
value - the parameter value
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur; or if a database access error occurs
Since:
1.6

setNClob

public void setNClob(String parameterName,
                     Reader reader,
                     long length)
              throws SQLException
Sets the designated parameter to a Reader object. The reader must contain * the number of characters specified by length otherwise a SQLException will be generated when the CallableStatement is executed. This method differs from the setCharacterStream (int, Reader, int) method because it informs the driver that the parameter value should be sent to the server as a NCLOB. When the setCharacterStream method is used, the driver may have to do extra work to determine whether the parameter data should be send to the server as a LONGNVARCHAR or a NCLOB

Parameters:
parameterName - the name of the parameter to be set
reader - An object that contains the data to set the parameter value to.
length - the number of characters in the parameter data.
Throws:
SQLException - if parameterIndex does not correspond to a parameter marker in the SQL statement; if the length specified is less than zero; if the driver does not support national character sets; if the driver can detect that a data conversion error could occur; if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setNClob

public void setNClob(String parameterName,
                     Reader reader)
              throws SQLException
Sets the designated parameter to a Reader object. This method differs from the setCharacterStream (int, Reader) method because it informs the driver that the parameter value should be sent to the server as a NCLOB. When the setCharacterStream method is used, the driver may have to do extra work to determine whether the parameter data should be send to the server as a LONGNVARCHAR or a NCLOB

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setNClob which takes a length parameter.

Parameters:
parameterName - the name of the parameter
reader - An object that contains the data to set the parameter value to.
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur; if a database access error occurs or this method is called on a closed CallableStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setNClob

public void setNClob(int parameterIndex,
                     Reader reader,
                     long length)
              throws SQLException
Sets the designated parameter to a Reader object. The reader must contain the number of characters specified by length otherwise a SQLException will be generated when the PreparedStatement is executed. This method differs from the setCharacterStream (int, Reader, int) method because it informs the driver that the parameter value should be sent to the server as a NCLOB. When the setCharacterStream method is used, the driver may have to do extra work to determine whether the parameter data should be sent to the server as a LONGNVARCHAR or a NCLOB

Parameters:
parameterIndex - index of the first parameter is 1, the second is 2, ...
reader - An object that contains the data to set the parameter value to.
length - the number of characters in the parameter data.
Throws:
SQLException - if parameterIndex does not correspond to a parameter marker in the SQL statement; if the length specified is less than zero; if the driver does not support national character sets; if the driver can detect that a data conversion error could occur; if a database access error occurs or this method is called on a closed PreparedStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setNClob

public void setNClob(int parameterIndex,
                     NClob value)
              throws SQLException
Sets the designated parameter to a java.sql.NClob object. The driver converts this oa SQL NCLOB value when it sends it to the database.

Parameters:
parameterIndex - of the first parameter is 1, the second is 2, ...
value - the parameter value
Throws:
SQLException - if the driver does not support national character sets; if the driver can detect that a data conversion error could occur ; or if a database access error occurs
Since:
1.6

setNClob

public void setNClob(int parameterIndex,
                     Reader reader)
              throws SQLException
Sets the designated parameter to a Reader object. This method differs from the setCharacterStream (int, Reader) method because it informs the driver that the parameter value should be sent to the server as a NCLOB. When the setCharacterStream method is used, the driver may have to do extra work to determine whether the parameter data should be sent to the server as a LONGNVARCHAR or a NCLOB

Note: Consult your JDBC driver documentation to determine if it might be more efficient to use a version of setNClob which takes a length parameter.

Parameters:
parameterIndex - index of the first parameter is 1, the second is 2, ...
reader - An object that contains the data to set the parameter value to.
Throws:
SQLException - if parameterIndex does not correspond to a parameter marker in the SQL statement; if the driver does not support national character sets; if the driver can detect that a data conversion error could occur; if a database access error occurs or this method is called on a closed PreparedStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

setURL

public void setURL(int parameterIndex,
                   URL x)
            throws SQLException
Sets the designated parameter to the given java.net.URL value. The driver converts this to an SQL DATALINK value when it sends it to the database.

Parameters:
parameterIndex - the first parameter is 1, the second is 2, ...
x - the java.net.URL object to be set
Throws:
SQLException - if a database access error occurs or this method is called on a closed PreparedStatement
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


CachedRowSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset
Interface CachedRowSet

All Superinterfaces:
Joinable, ResultSet, RowSet, Wrapper
All Known Subinterfaces:
FilteredRowSet, JoinRowSet, WebRowSet
public interface CachedRowSet
extends RowSet, Joinable

The interface that all standard implementations of CachedRowSet must implement.

The reference implementation of the CachedRowSet interface provided by Sun Microsystems is a standard implementation. Developers may use this implementation just as it is, they may extend it, or they may choose to write their own implementations of this interface.

A CachedRowSet object is a container for rows of data that caches its rows in memory, which makes it possible to operate without always being connected to its data source. Further, it is a JavaBeansTM component and is scrollable, updatable, and serializable. A CachedRowSet object typically contains rows from a result set, but it can also contain rows from any file with a tabular format, such as a spread sheet. The reference implementation supports getting data only from a ResultSet object, but developers can extend the SyncProvider implementations to provide access to other tabular data sources.

An application can modify the data in a CachedRowSet object, and those modifications can then be propagated back to the source of the data.

A CachedRowSet object is a disconnected rowset, which means that it makes use of a connection to its data source only briefly. It connects to its data source while it is reading data to populate itself with rows and again while it is propagating changes back to its underlying data source. The rest of the time, a CachedRowSet object is disconnected, including while its data is being modified. Being disconnected makes a RowSet object much leaner and therefore much easier to pass to another component. For example, a disconnected RowSet object can be serialized and passed over the wire to a thin client such as a personal digital assistant (PDA).

1.0 Creating a CachedRowSet Object

The following line of code uses the default constructor for CachedRowSet supplied in the reference implementation (RI) to create a default CachedRowSet object.
     CachedRowSetImpl crs = new CachedRowSetImpl();
This new CachedRowSet object will have its properties set to the default properties of a BaseRowSet object, and, in addition, it will have an RIOptimisticProvider object as its synchronization provider. RIOptimisticProvider, one of two SyncProvider implementations included in the RI, is the default provider that the SyncFactory singleton will supply when no synchronization provider is specified.

A SyncProvider object provides a CachedRowSet object with a reader (a RowSetReader object) for reading data from a data source to populate itself with data. A reader can be implemented to read data from a ResultSet object or from a file with a tabular format. A SyncProvider object also provides a writer (a RowSetWriter object) for synchronizing any modifications to the CachedRowSet object's data made while it was disconnected with the data in the underlying data source.

A writer can be implemented to exercise various degrees of care in checking for conflicts and in avoiding them. (A conflict occurs when a value in the data source has been changed after the rowset populated itself with that value.) The RIOptimisticProvider implementation assumes there will be few or no conflicts and therefore sets no locks. It updates the data source with values from the CachedRowSet object only if there are no conflicts. Other writers can be implemented so that they always write modified data to the data source, which can be accomplished either by not checking for conflicts or, on the other end of the spectrum, by setting locks sufficient to prevent data in the data source from being changed. Still other writer implementations can be somewhere in between.

A CachedRowSet object may use any SyncProvider implementation that has been registered with the SyncFactory singleton. An application can find out which SyncProvider implementations have been registered by calling the following line of code.

      java.util.Enumeration providers = SyncFactory.getRegisteredProviders();

There are two ways for a CachedRowSet object to specify which SyncProvider object it will use. Supplying the name of the implementation to the constructor
The following line of code creates the CachedRowSet object crs2 that is initialized with default values except that its SyncProvider object is the one specified.

          CachedRowSetImpl crs2 = new CachedRowSetImpl(
                                 "com.fred.providers.HighAvailabilityProvider");
  • Setting the SyncProvider using the CachedRowSet method setSyncProvider
    The following line of code resets the SyncProvider object for crs, the CachedRowSet object created with the default constructor.
               crs.setSyncProvider("com.fred.providers.HighAvailabilityProvider");
    SyncFactory and SyncProvider for more details.

    2.0 Retrieving Data from a CachedRowSet Object

    Data is retrieved from a CachedRowSet object by using the getter methods inherited from the ResultSet interface. The following examples, in which crs is a CachedRowSet object, demonstrate how to iterate through the rows, retrieving the column values in each row. The first example uses the version of the getter methods that take a column number; the second example uses the version that takes a column name. Column numbers are generally used when the RowSet object's command is of the form SELECT * FROM TABLENAME; column names are most commonly used when the command specifies columns by name.
        while (crs.next()) {
        String name = crs.getString(1);
        int id = crs.getInt(2);
        Clob comment = crs.getClob(3);
        short dept = crs.getShort(4);
        System.out.println(name + "  " + id + "  " + comment + "  " + dept);
    }

        while (crs.next()) {
        String name = crs.getString("NAME");
        int id = crs.getInt("ID");
        Clob comment = crs.getClob("COM");
        short dept = crs.getShort("DEPT");
        System.out.println(name + "  " + id + "  " + comment + "  " + dept);
    }

    2.1 Retrieving RowSetMetaData

    An application can get information about the columns in a CachedRowSet object by calling ResultSetMetaData and RowSetMetaData methods on a RowSetMetaData object. The following code fragment, in which crs is a CachedRowSet object, illustrates the process. The first line creates a RowSetMetaData object with information about the columns in crs. The method getMetaData, inherited from the ResultSet interface, returns a ResultSetMetaData object, which is cast to a RowSetMetaData object before being assigned to the variable rsmd. The second line finds out how many columns jrs has, and the third line gets the JDBC type of values stored in the second column of jrs.
         RowSetMetaData rsmd = (RowSetMetaData)crs.getMetaData();
     int count = rsmd.getColumnCount();
     int type = rsmd.getColumnType(2);
    The RowSetMetaData interface differs from the ResultSetMetaData interface in two ways.
    • It includes setter methods: A RowSet object uses these methods internally when it is populated with data from a different ResultSet object.

    • It contains fewer getter methods: Some ResultSetMetaData methods to not apply to a RowSet object. For example, methods retrieving whether a column value is writable or read only do not apply because all of a RowSet object's columns will be writable or read only, depending on whether the rowset is updatable or not.
    NOTE: In order to return a RowSetMetaData object, implementations must override the getMetaData() method defined in java.sql.ResultSet and return a RowSetMetaData object.

    3.0 Updating a CachedRowSet Object

    Updating a CachedRowSet object is similar to updating a ResultSet object, but because the rowset is not connected to its data source while it is being updated, it must take an additional step to effect changes in its underlying data source. After calling the method updateRow or insertRow, a CachedRowSet object must also call the method acceptChanges to have updates written to the data source. The following example, in which the cursor is on a row in the CachedRowSet object crs, shows the code required to update two column values in the current row and also update the RowSet object's underlying data source.
         crs.updateShort(3, 58);
     crs.updateInt(4, 150000);
     crs.updateRow();
     crs.acceptChanges();

    The next example demonstrates moving to the insert row, building a new row on the insert row, inserting it into the rowset, and then calling the method acceptChanges to add the new row to the underlying data source. Note that as with the getter methods, the updater methods may take either a column index or a column name to designate the column being acted upon.

         crs.moveToInsertRow();
     crs.updateString("Name", "Shakespeare");
     crs.updateInt("ID", 10098347);
     crs.updateShort("Age", 58);
     crs.updateInt("Sal", 150000);
     crs.insertRow();
     crs.moveToCurrentRow();
     crs.acceptChanges();

    NOTE: Where the insertRow() method inserts the contents of a CachedRowSet object's insert row is implementation-defined. The reference implementation for the CachedRowSet interface inserts a new row immediately following the current row, but it could be implemented to insert new rows in any number of other places.

    Another thing to note about these examples is how they use the method acceptChanges. It is this method that propagates changes in a CachedRowSet object back to the underlying data source, calling on the RowSet object's writer internally to write changes to the data source. To do this, the writer has to incur the expense of establishing a connection with that data source. The preceding two code fragments call the method acceptChanges immediately after calling updateRow or insertRow. However, when there are multiple rows being changed, it is more efficient to call acceptChanges after all calls to updateRow and insertRow have been made. If acceptChanges is called only once, only one connection needs to be established.

    4.0 Updating the Underlying Data Source

    When the method acceptChanges is executed, the CachedRowSet object's writer, a RowSetWriterImpl object, is called behind the scenes to write the changes made to the rowset to the underlying data source. The writer is implemented to make a connection to the data source and write updates to it.

    A writer is made available through an implementation of the SyncProvider interface, as discussed in section 1, "Creating a CachedRowSet Object." The default reference implementation provider, RIOptimisticProvider, has its writer implemented to use an optimistic concurrency control mechanism. That is, it maintains no locks in the underlying database while the rowset is disconnected from the database and simply checks to see if there are any conflicts before writing data to the data source. If there are any conflicts, it does not write anything to the data source.

    The reader/writer facility provided by the SyncProvider class is pluggable, allowing for the customization of data retrieval and updating. If a different concurrency control mechanism is desired, a different implementation of SyncProvider can be plugged in using the method setSyncProvider.

    In order to use the optimistic concurrency control routine, the RIOptismisticProvider maintains both its current value and its original value (the value it had immediately preceding the current value). Note that if no changes have been made to the data in a RowSet object, its current values and its original values are the same, both being the values with which the RowSet object was initially populated. However, once any values in the RowSet object have been changed, the current values and the original values will be different, though at this stage, the original values are still the initial values. With any subsequent changes to data in a RowSet object, its original values and current values will still differ, but its original values will be the values that were previously the current values.

    Keeping track of original values allows the writer to compare the RowSet object's original value with the value in the database. If the values in the database differ from the RowSet object's original values, which means that the values in the database have been changed, there is a conflict. Whether a writer checks for conflicts, what degree of checking it does, and how it handles conflicts all depend on how it is implemented.

    5.0 Registering and Notifying Listeners

    Being JavaBeans components, all rowsets participate in the JavaBeans event model, inheriting methods for registering listeners and notifying them of changes from the BaseRowSet class. A listener for a CachedRowSet object is a component that wants to be notified whenever there is a change in the rowset. For example, if a CachedRowSet object contains the results of a query and those results are being displayed in, say, a table and a bar graph, the table and bar graph could be registered as listeners with the rowset so that they can update themselves to reflect changes. To become listeners, the table and bar graph classes must implement the RowSetListener interface. Then they can be added to the CachedRowSet object's list of listeners, as is illustrated in the following lines of code.

    crs.addRowSetListener(table);
    crs.addRowSetListener(barGraph);
    Each CachedRowSet method that moves the cursor or changes data also notifies registered listeners of the changes, so table and barGraph will be notified when there is a change in crs.

    6.0 Passing Data to Thin Clients

    One of the main reasons to use a CachedRowSet object is to pass data between different components of an application. Because it is serializable, a CachedRowSet object can be used, for example, to send the result of a query executed by an enterprise JavaBeans component running in a server environment over a network to a client running in a web browser.

    While a CachedRowSet object is disconnected, it can be much leaner than a ResultSet object with the same data. As a result, it can be especially suitable for sending data to a thin client such as a PDA, where it would be inappropriate to use a JDBC driver due to resource limitations or security considerations. Thus, a CachedRowSet object provides a means to "get rows in" without the need to implement the full JDBC API.

    7.0 Scrolling and Updating

    A second major use for CachedRowSet objects is to provide scrolling and updating for ResultSet objects that do not provide these capabilities themselves. In other words, a CachedRowSet object can be used to augment the capabilities of a JDBC technology-enabled driver (hereafter called a "JDBC driver") when the DBMS does not provide full support for scrolling and updating. To achieve the effect of making a non-scrollble and read-only ResultSet object scrollable and updatable, a programmer simply needs to create a CachedRowSet object populated with that ResultSet object's data. This is demonstrated in the following code fragment, where stmt is a Statement object.
        ResultSet rs = stmt.executeQuery("SELECT * FROM EMPLOYEES");
    CachedRowSetImpl crs = new CachedRowSetImpl();
    crs.populate(rs);

    The object crs now contains the data from the table EMPLOYEES, just as the object rs does. The difference is that the cursor for crs can be moved forward, backward, or to a particular row even if the cursor for rs can move only forward. In addition, crs is updatable even if rs is not because by default, a CachedRowSet object is both scrollable and updatable.

    In summary, a CachedRowSet object can be thought of as simply a disconnected set of rows that are being cached outside of a data source. Being thin and serializable, it can easily be sent across a wire, and it is well suited to sending data to a thin client. However, a CachedRowSet object does have a limitation: It is limited in size by the amount of data it can store in memory at one time.

    8.0 Getting Universal Data Access

    Another advantage of the CachedRowSet class is that it makes it possible to retrieve and store data from sources other than a relational database. The reader for a rowset can be implemented to read and populate its rowset with data from any tabular data source, including a spreadsheet or flat file. Because both a CachedRowSet object and its metadata can be created from scratch, a component that acts as a factory for rowsets can use this capability to create a rowset containing data from non-SQL data sources. Nevertheless, it is expected that most of the time, CachedRowSet objects will contain data that was fetched from an SQL database using the JDBC API.

    9.0 Setting Properties

    All rowsets maintain a set of properties, which will usually be set using a tool. The number and kinds of properties a rowset has will vary, depending on what the rowset does and how it gets its data. For example, rowsets that get their data from a ResultSet object need to set the properties that are required for making a database connection. If a rowset uses the DriverManager facility to make a connection, it needs to set a property for the JDBC URL that identifies the appropriate driver, and it needs to set the properties that give the user name and password. If, on the other hand, the rowset uses a DataSource object to make the connection, which is the preferred method, it does not need to set the property for the JDBC URL. Instead, it needs to set properties for the logical name of the data source, for the user name, and for the password.

    NOTE: In order to use a DataSource object for making a connection, the DataSource object must have been registered with a naming service that uses the Java Naming and Directory InterfaceTM (JNDI) API. This registration is usually done by a person acting in the capacity of a system administrator.

    In order to be able to populate itself with data from a database, a rowset needs to set a command property. This property is a query that is a PreparedStatement object, which allows the query to have parameter placeholders that are set at run time, as opposed to design time. To set these placeholder parameters with values, a rowset provides setter methods for setting values of each data type, similar to the setter methods provided by the PreparedStatement interface.

    The following code fragment illustrates how the CachedRowSet object crs might have its command property set. Note that if a tool is used to set properties, this is the code that the tool would use.

        crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS " +
                   "WHERE CREDIT_LIMIT > ? AND REGION = ?");

    The values that will be used to set the command's placeholder parameters are contained in the RowSet object's params field, which is a Vector object. The CachedRowSet class provides a set of setter methods for setting the elements in its params field. The following code fragment demonstrates setting the two parameters in the query from the previous example.

        crs.setInt(1, 5000);
    crs.setString(2, "West");

    The params field now contains two elements, each of which is an array two elements long. The first element is the parameter number; the second is the value to be set. In this case, the first element of params is 1, 5000, and the second element is 2, "West". When an application calls the method execute, it will in turn call on this RowSet object's reader, which will in turn invoke its readData method. As part of its implementation, readData will get the values in params and use them to set the command's placeholder parameters. The following code fragment gives an idea of how the reader does this, after obtaining the Connection object con.

        PreparedStatement pstmt = con.prepareStatement(crs.getCommand());
    reader.decodeParams();
    // decodeParams figures out which setter methods to use and does something
    // like the following:
    //    for (i = 0; i < params.length; i++) {
    //        pstmt.setObject(i + 1, params[i]);
    //    }

    At this point, the command for crs is the query "SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS WHERE CREDIT_LIMIT > 5000 AND REGION = "West". After the readData method executes this command with the following line of code, it will have the data from rs with which to populate crs.

         ResultSet rs = pstmt.executeQuery();

    The preceding code fragments give an idea of what goes on behind the scenes; they would not appear in an application, which would not invoke methods like readData and decodeParams. In contrast, the following code fragment shows what an application might do. It sets the rowset's command, sets the command's parameters, and executes the command. Simply by calling the execute method, crs populates itself with the requested data from the table CUSTOMERS.

        crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
                   "WHERE CREDIT_LIMIT > ? AND REGION = ?");
    crs.setInt(1, 5000);
    crs.setString(2, "West");
    crs.execute();

    10.0 Paging Data

    Because a CachedRowSet object stores data in memory, the amount of data that it can contain at any one time is determined by the amount of memory available. To get around this limitation, a CachedRowSet object can retrieve data from a ResultSet object in chunks of data, called pages. To take advantage of this mechanism, an application sets the number of rows to be included in a page using the method setPageSize. In other words, if the page size is set to five, a chunk of five rows of data will be fetched from the data source at one time. An application can also optionally set the maximum number of rows that may be fetched at one time. If the maximum number of rows is set to zero, or no maximum number of rows is set, there is no limit to the number of rows that may be fetched at a time.

    After properties have been set, the CachedRowSet object must be populated with data using either the method populate or the method execute. The following lines of code demonstrate using the method populate. Note that this version of the method takes two parameters, a ResultSet handle and the row in the ResultSet object from which to start retrieving rows.

         CachedRowSet crs = new CachedRowSetImpl();
     crs.setMaxRows(20);
     crs.setPageSize(4);
     crs.populate(rsHandle, 10);
    When this code runs, crs will be populated with four rows from rsHandle starting with the tenth row.

    The next code fragment shows populating a CachedRowSet object using the method execute, which may or may not take a Connection object as a parameter. This code passes execute the Connection object conHandle.

    Note that there are two differences between the following code fragment and the previous one. First, the method setMaxRows is not called, so there is no limit set for the number of rows that crs may contain. (Remember that crs always has the overriding limit of how much data it can store in memory.) The second difference is that the you cannot pass the method execute the number of the row in the ResultSet object from which to start retrieving rows. This method always starts with the first row.

         CachedRowSet crs = new CachedRowSetImpl();
     crs.setPageSize(5);
     crs.execute(conHandle);
    After this code has run, crs will contain five rows of data from the ResultSet object produced by the command for crs. The writer for crs will use conHandle to connect to the data source and execute the command for crs. An application is then able to operate on the data in crs in the same way that it would operate on data in any other CachedRowSet object.

    To access the next page (chunk of data), an application calls the method nextPage. This method creates a new CachedRowSet object and fills it with the next page of data. For example, assume that the CachedRowSet object's command returns a ResultSet object rs with 1000 rows of data. If the page size has been set to 100, the first call to the method nextPage will create a CachedRowSet object containing the first 100 rows of rs. After doing what it needs to do with the data in these first 100 rows, the application can again call the method nextPage to create another CachedRowSet object with the second 100 rows from rs. The data from the first CachedRowSet object will no longer be in memory because it is replaced with the data from the second CachedRowSet object. After the tenth call to the method nextPage, the tenth CachedRowSet object will contain the last 100 rows of data from rs, which are stored in memory. At any given time, the data from only one CachedRowSet object is stored in memory.

    The method nextPage returns true as long as the current page is not the last page of rows and false when there are no more pages. It can therefore be used in a while loop to retrieve all of the pages, as is demonstrated in the following lines of code.

         CachedRowSet crs = CachedRowSetImpl();
     crs.setPageSize(100);
     crs.execute(conHandle);

     while(crs.nextPage()) {
         while(crs.next()) {
             . . . // operate on chunks (of 100 rows each) in crs,
                   // row by row
         }
     }
    After this code fragment has been run, the application will have traversed all 1000 rows, but it will have had no more than 100 rows in memory at a time.

    The CachedRowSet interface also defines the method previousPage. Just as the method nextPage is analogous to the ResultSet method next, the method previousPage is analogous to the ResultSet method previous. Similar to the method nextPage, previousPage creates a CachedRowSet object containing the number of rows set as the page size. So, for instance, the method previousPage could be used in a while loop at the end of the preceding code fragment to navigate back through the pages from the last page to the first page. The method previousPage is also similar to nextPage in that it can be used in a while loop, except that it returns true as long as there is another page preceding it and false when there are no more pages ahead of it.

    By positioning the cursor after the last row for each page, as is done in the following code fragment, the method previous navigates from the last row to the first row in each page. The code could also have left the cursor before the first row on each page and then used the method next in a while loop to navigate each page from the first row to the last row.

    The following code fragment assumes a continuation from the previous code fragment, meaning that the cursor for the tenth CachedRowSet object is on the last row. The code moves the cursor to after the last row so that the first call to the method previous will put the cursor back on the last row. After going through all of the rows in the last page (the CachedRowSet object crs), the code then enters the while loop to get to the ninth page, go through the rows backwards, go to the eighth page, go through the rows backwards, and so on to the first row of the first page.

         crs.afterLast();
     while(crs.previous())  {
         . . . // navigate through the rows, last to first
     {
     while(crs.previousPage())  {
         crs.afterLast();
         while(crs.previous())  {
             . . . // go from the last row to the first row of each page
         }
     }

    Field Summary
    static boolean COMMIT_ON_ACCEPT_CHANGES
    Causes the CachedRowSet object's SyncProvider to commit the changes when acceptChanges() is called.
    Fields inherited from interface java.sql.ResultSet
    CLOSE_CURSORS_AT_COMMIT, CONCUR_READ_ONLY, CONCUR_UPDATABLE, FETCH_FORWARD, FETCH_REVERSE, FETCH_UNKNOWN, HOLD_CURSORS_OVER_COMMIT, TYPE_FORWARD_ONLY, TYPE_SCROLL_INSENSITIVE, TYPE_SCROLL_SENSITIVE
    Method Summary
     void acceptChanges()
    Propagates row update, insert and delete changes made to this CachedRowSet object to the underlying data source.
     void acceptChanges(Connection con)
    Propagates all row update, insert and delete changes to the data source backing this CachedRowSet object using the specified Connection object to establish a connection to the data source.
     boolean columnUpdated(int idx)
    Indicates whether the designated column in the current row of this CachedRowSet object has been updated.
     boolean columnUpdated(String columnName)
    Indicates whether the designated column in the current row of this CachedRowSet object has been updated.
     void commit()
    Each CachedRowSet object's SyncProvider contains a Connection object from the ResultSet or JDBC properties passed to it's constructors.
     CachedRowSet createCopy()
    Creates a RowSet object that is a deep copy of the data in this CachedRowSet object.
     CachedRowSet createCopyNoConstraints()
    Creates a CachedRowSet object that is a deep copy of this CachedRowSet object's data but is independent of it.
     CachedRowSet createCopySchema()
    Creates a CachedRowSet object that is an empty copy of this CachedRowSet object.
     RowSet createShared()
    Returns a new RowSet object backed by the same data as that of this CachedRowSet object.
     void execute(Connection conn)
    Populates this CachedRowSet object with data, using the given connection to produce the result set from which the data will be read.
     int[] getKeyColumns()
    Returns an array containing one or more column numbers indicating the columns that form a key that uniquely identifies a row in this CachedRowSet object.
     ResultSet getOriginal()
    Returns a ResultSet object containing the original value of this CachedRowSet object.
     ResultSet getOriginalRow()
    Returns a ResultSet object containing the original value for the current row only of this CachedRowSet object.
     int getPageSize()
    Returns the page-size for the CachedRowSet object
     RowSetWarning getRowSetWarnings()
    Retrieves the first warning reported by calls on this RowSet object.
     boolean getShowDeleted()
    Retrieves a boolean indicating whether rows marked for deletion appear in the set of current rows.
     SyncProvider getSyncProvider()
    Retrieves the SyncProvider implementation for this CachedRowSet object.
     String getTableName()
    Returns an identifier for the object (table) that was used to create this CachedRowSet object.
     boolean nextPage()
    Increments the current page of the CachedRowSet.
     void populate(ResultSet data)
    Populates this CachedRowSet object with data from the given ResultSet object.
     void populate(ResultSet rs, int startRow)
    Populates this CachedRowSet object with data from the given ResultSet object.
     boolean previousPage()
    Decrements the current page of the CachedRowSet.
     void release()
    Releases the current contents of this CachedRowSet object and sends a rowSetChanged event to all registered listeners.
     void restoreOriginal()
    Restores this CachedRowSet object to its original value, that is, its value before the last set of changes.
     void rollback()
    Each CachedRowSet object's SyncProvider contains a Connection object from the original ResultSet or JDBC properties passed to it.
     void rollback(Savepoint s)
    Each CachedRowSet object's SyncProvider contains a Connection object from the original ResultSet or JDBC properties passed to it.
     void rowSetPopulated(RowSetEvent event, int numRows)
    Notifies registered listeners that a RowSet object in the given RowSetEvent object has populated a number of additional rows.
     void setKeyColumns(int[] keys)
    Sets this CachedRowSet object's keyCols field with the given array of column numbers, which forms a key for uniquely identifying a row in this CachedRowSet object.
     void setMetaData(RowSetMetaData md)
    Sets the metadata for this CachedRowSet object with the given RowSetMetaData object.
     void setOriginalRow()
    Sets the current row in this CachedRowSet object as the original row.
     void setPageSize(int size)
    Sets the CachedRowSet object's page-size.
     void setShowDeleted(boolean b)
    Sets the property showDeleted to the given boolean value, which determines whether rows marked for deletion appear in the set of current rows.
     void setSyncProvider(String provider)
    Sets the SyncProvider objec for this CachedRowSet object to the one specified.
     void setTableName(String tabName)
    Sets the identifier for the table from which this CachedRowSet object was derived to the given table name.
     int size()
    Returns the number of rows in this CachedRowSet object.
     Collection<?> toCollection()
    Converts this CachedRowSet object to a Collection object that contains all of this CachedRowSet object's data.
     Collection<?> toCollection(int column)
    Converts the designated column in this CachedRowSet object to a Collection object.
     Collection<?> toCollection(String column)
    Converts the designated column in this CachedRowSet object to a Collection object.
     void undoDelete()
    Cancels the deletion of the current row and notifies listeners that a row has changed.
     void undoInsert()
    Immediately removes the current row from this CachedRowSet object if the row has been inserted, and also notifies listeners that a row has changed.
     void undoUpdate()
    Immediately reverses the last update operation if the row has been modified.
    Methods inherited from interface javax.sql.RowSet
    addRowSetListener, clearParameters, execute, getCommand, getDataSourceName, getEscapeProcessing, getMaxFieldSize, getMaxRows, getPassword, getQueryTimeout, getTransactionIsolation, getTypeMap, getUrl, getUsername, isReadOnly, removeRowSetListener, setArray, setAsciiStream, setAsciiStream, setAsciiStream, setAsciiStream, setBigDecimal, setBigDecimal, setBinaryStream, setBinaryStream, setBinaryStream, setBinaryStream, setBlob, setBlob, setBlob, setBlob, setBlob, setBlob, setBoolean, setBoolean, setByte, setByte, setBytes, setBytes, setCharacterStream, setCharacterStream, setCharacterStream, setCharacterStream, setClob, setClob, setClob, setClob, setClob, setClob, setCommand, setConcurrency, setDataSourceName, setDate, setDate, setDate, setDate, setDouble, setDouble, setEscapeProcessing, setFloat, setFloat, setInt, setInt, setLong, setLong, setMaxFieldSize, setMaxRows, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNClob, setNClob, setNClob, setNClob, setNClob, setNClob, setNString, setNString, setNull, setNull, setNull, setNull, setObject, setObject, setObject, setObject, setObject, setObject, setPassword, setQueryTimeout, setReadOnly, setRef, setRowId, setRowId, setShort, setShort, setSQLXML, setSQLXML, setString, setString, setTime, setTime, setTime, setTime, setTimestamp, setTimestamp, setTimestamp, setTimestamp, setTransactionIsolation, setType, setTypeMap, setURL, setUrl, setUsername
    Methods inherited from interface java.sql.ResultSet
    absolute, afterLast, beforeFirst, cancelRowUpdates, clearWarnings, close, deleteRow, findColumn, first, getArray, getArray, getAsciiStream, getAsciiStream, getBigDecimal, getBigDecimal, getBigDecimal, getBigDecimal, getBinaryStream, getBinaryStream, getBlob, getBlob, getBoolean, getBoolean, getByte, getByte, getBytes, getBytes, getCharacterStream, getCharacterStream, getClob, getClob, getConcurrency, getCursorName, getDate, getDate, getDate, getDate, getDouble, getDouble, getFetchDirection, getFetchSize, getFloat, getFloat, getHoldability, getInt, getInt, getLong, getLong, getMetaData, getNCharacterStream, getNCharacterStream, getNClob, getNClob, getNString, getNString, getObject, getObject, getObject, getObject, getRef, getRef, getRow, getRowId, getRowId, getShort, getShort, getSQLXML, getSQLXML, getStatement, getString, getString, getTime, getTime, getTime, getTime, getTimestamp, getTimestamp, getTimestamp, getTimestamp, getType, getUnicodeStream, getUnicodeStream, getURL, getURL, getWarnings, insertRow, isAfterLast, isBeforeFirst, isClosed, isFirst, isLast, last, moveToCurrentRow, moveToInsertRow, next, previous, refreshRow, relative, rowDeleted, rowInserted, rowUpdated, setFetchDirection, setFetchSize, updateArray, updateArray, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateBigDecimal, updateBigDecimal, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBoolean, updateBoolean, updateByte, updateByte, updateBytes, updateBytes, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateClob, updateClob, updateClob, updateClob, updateClob, updateClob, updateDate, updateDate, updateDouble, updateDouble, updateFloat, updateFloat, updateInt, updateInt, updateLong, updateLong, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNString, updateNString, updateNull, updateNull, updateObject, updateObject, updateObject, updateObject, updateRef, updateRef, updateRow, updateRowId, updateRowId, updateShort, updateShort, updateSQLXML, updateSQLXML, updateString, updateString, updateTime, updateTime, updateTimestamp, updateTimestamp, wasNull
    Methods inherited from interface java.sql.Wrapper
    isWrapperFor, unwrap
    Methods inherited from interface javax.sql.rowset.Joinable
    getMatchColumnIndexes, getMatchColumnNames, setMatchColumn, setMatchColumn, setMatchColumn, setMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn

    Field Detail

    COMMIT_ON_ACCEPT_CHANGES

    static final boolean COMMIT_ON_ACCEPT_CHANGES
    Causes the CachedRowSet object's SyncProvider to commit the changes when acceptChanges() is called. If set to false, the changes will not be committed until one of the CachedRowSet interface transaction methods is called.

    See Also:
    commit(), rollback(), Constant Field Values
    Method Detail

    populate

    void populate(ResultSet data)
              throws SQLException
    Populates this CachedRowSet object with data from the given ResultSet object.

    This method can be used as an alternative to the execute method when an application has a connection to an open ResultSet object. Using the method populate can be more efficient than using the version of the execute method that takes no parameters because it does not open a new connection and re-execute this CachedRowSet object's command. Using the populate method is more a matter of convenience when compared to using the version of execute that takes a ResultSet object.

    Parameters:
    data - the ResultSet object containing the data to be read into this CachedRowSet object
    Throws:
    SQLException - if a null ResultSet object is supplied or this CachedRowSet object cannot retrieve the associated ResultSetMetaData object
    See Also:
    execute(java.sql.Connection), ResultSet, ResultSetMetaData

    execute

    void execute(Connection conn)
             throws SQLException
    Populates this CachedRowSet object with data, using the given connection to produce the result set from which the data will be read. This method should close any database connections that it creates to ensure that this CachedRowSet object is disconnected except when it is reading data from its data source or writing data to its data source.

    The reader for this CachedRowSet object will use conn to establish a connection to the data source so that it can execute the rowset's command and read data from the the resulting ResultSet object into this CachedRowSet object. This method also closes conn after it has populated this CachedRowSet object.

    If this method is called when an implementation has already been populated, the contents and the metadata are (re)set. Also, if this method is called before the method acceptChanges has been called to commit outstanding updates, those updates are lost.

    Parameters:
    conn - a standard JDBC Connection object with valid properties
    Throws:
    SQLException - if an invalid Connection object is supplied or an error occurs in establishing the connection to the data source
    See Also:
    populate(java.sql.ResultSet), Connection

    acceptChanges

    void acceptChanges()
                   throws SyncProviderException
    Propagates row update, insert and delete changes made to this CachedRowSet object to the underlying data source.

    This method calls on this CachedRowSet object's writer to do the work behind the scenes. Standard CachedRowSet implementations should use the SyncFactory singleton to obtain a SyncProvider instance providing a RowSetWriter object (writer). The writer will attempt to propagate changes made in this CachedRowSet object back to the data source.

    When the method acceptChanges executes successfully, in addition to writing changes to the data source, it makes the values in the current row be the values in the original row.

    Depending on the synchronization level of the SyncProvider implementation being used, the writer will compare the original values with those in the data source to check for conflicts. When there is a conflict, the RIOptimisticProvider implementation, for example, throws a SyncProviderException and does not write anything to the data source.

    An application may choose to catch the SyncProviderException object and retrieve the SyncResolver object it contains. The SyncResolver object lists the conflicts row by row and sets a lock on the data source to avoid further conflicts while the current conflicts are being resolved. Further, for each conflict, it provides methods for examining the conflict and setting the value that should be persisted in the data source. After all conflicts have been resolved, an application must call the acceptChanges method again to write resolved values to the data source. If all of the values in the data source are already the values to be persisted, the method acceptChanges does nothing.

    Some provider implementations may use locks to ensure that there are no conflicts. In such cases, it is guaranteed that the writer will succeed in writing changes to the data source when the method acceptChanges is called. This method may be called immediately after the methods updateRow, insertRow, or deleteRow have been called, but it is more efficient to call it only once after all changes have been made so that only one connection needs to be established.

    Note: The acceptChanges() method will determine if the COMMIT_ON_ACCEPT_CHANGES is set to true or not. If it is set to true, all updates in the synchronization are committed to the data source. Otherwise, the application must explicity call the commit() or rollback() methods as appropriate.

    Throws:
    SQLException - if the cursor is on the insert row
    SyncProviderException - if the underlying synchronization provider's writer fails to write the updates back to the data source
    See Also:
    acceptChanges(java.sql.Connection), RowSetWriter, SyncFactory, SyncProvider, SyncProviderException, SyncResolver

    acceptChanges

    void acceptChanges(Connection con)
                   throws SyncProviderException
    Propagates all row update, insert and delete changes to the data source backing this CachedRowSet object using the specified Connection object to establish a connection to the data source.

    The other version of the acceptChanges method is not passed a connection because it uses the Connection object already defined within the RowSet object, which is the connection used for populating it initially.

    This form of the method acceptChanges is similar to the form that takes no arguments; however, unlike the other form, this form can be used only when the underlying data source is a JDBC data source. The updated Connection properties must be used by the SyncProvider to reset the RowSetWriter configuration to ensure that the contents of the CachedRowSet object are synchronized correctly.

    When the method acceptChanges executes successfully, in addition to writing changes to the data source, it makes the values in the current row be the values in the original row.

    Depending on the synchronization level of the SyncProvider implementation being used, the writer will compare the original values with those in the data source to check for conflicts. When there is a conflict, the RIOptimisticProvider implementation, for example, throws a SyncProviderException and does not write anything to the data source.

    An application may choose to catch the SyncProviderException object and retrieve the SyncResolver object it contains. The SyncResolver object lists the conflicts row by row and sets a lock on the data source to avoid further conflicts while the current conflicts are being resolved. Further, for each conflict, it provides methods for examining the conflict and setting the value that should be persisted in the data source. After all conflicts have been resolved, an application must call the acceptChanges method again to write resolved values to the data source. If all of the values in the data source are already the values to be persisted, the method acceptChanges does nothing.

    Some provider implementations may use locks to ensure that there are no conflicts. In such cases, it is guaranteed that the writer will succeed in writing changes to the data source when the method acceptChanges is called. This method may be called immediately after the methods updateRow, insertRow, or deleteRow have been called, but it is more efficient to call it only once after all changes have been made so that only one connection needs to be established.

    Note: The acceptChanges() method will determine if the COMMIT_ON_ACCEPT_CHANGES is set to true or not. If it is set to true, all updates in the synchronization are committed to the data source. Otherwise, the application must explicity call the commit or rollback methods as appropriate.

    Parameters:
    con - a standard JDBC Connection object
    Throws:
    SQLException - if the cursor is on the insert row
    SyncProviderException - if the underlying synchronization provider's writer fails to write the updates back to the data source
    See Also:
    acceptChanges(), RowSetWriter, SyncFactory, SyncProvider, SyncProviderException, SyncResolver

    restoreOriginal

    void restoreOriginal()
                     throws SQLException
    Restores this CachedRowSet object to its original value, that is, its value before the last set of changes. If there have been no changes to the rowset or only one set of changes, the original value is the value with which this CachedRowSet object was populated; otherwise, the original value is the value it had immediately before its current value.

    When this method is called, a CachedRowSet implementation must ensure that all updates, inserts, and deletes to the current rowset instance are replaced by the previous values. In addition, the cursor should be reset to the first row and a rowSetChanged event should be fired to notify all registered listeners.

    Throws:
    SQLException - if an error occurs rolling back the current value of this CachedRowSet object to its previous value
    See Also:
    RowSetListener.rowSetChanged(javax.sql.RowSetEvent)

    release

    void release()
             throws SQLException
    Releases the current contents of this CachedRowSet object and sends a rowSetChanged event to all registered listeners. Any outstanding updates are discarded and the rowset contains no rows after this method is called. There are no interactions with the underlying data source, and any rowset content, metadata, and content updates should be non-recoverable.

    This CachedRowSet object should lock until its contents and associated updates are fully cleared, thus preventing 'dirty' reads by other components that hold a reference to this RowSet object. In addition, the contents cannot be released until all all components reading this CachedRowSet object have completed their reads. This CachedRowSet object should be returned to normal behavior after firing the rowSetChanged event.

    The metadata, including JDBC properties and Synchronization SPI properties, are maintained for future use. It is important that properties such as the command property be relevant to the originating data source from which this CachedRowSet object was originally established.

    This method empties a rowset, as opposed to the close method, which marks the entire rowset as recoverable to allow the garbage collector the rowset's Java VM resources.

    Throws:
    SQLException - if an error occurs flushing the contents of this CachedRowSet object
    See Also:
    RowSetListener.rowSetChanged(javax.sql.RowSetEvent), ResultSet.close()

    undoDelete

    void undoDelete()
                throws SQLException
    Cancels the deletion of the current row and notifies listeners that a row has changed. After this method is called, the current row is no longer marked for deletion. This method can be called at any time during the lifetime of the rowset.

    In addition, multiple cancellations of row deletions can be made by adjusting the position of the cursor using any of the cursor position control methods such as:

    • CachedRowSet.absolute
    • CachedRowSet.first
    • CachedRowSet.last

    Throws:
    SQLException - if (1) the current row has not been deleted or (2) the cursor is on the insert row, before the first row, or after the last row
    See Also:
    undoInsert(), ResultSet.cancelRowUpdates()

    undoInsert

    void undoInsert()
                throws SQLException
    Immediately removes the current row from this CachedRowSet object if the row has been inserted, and also notifies listeners that a row has changed. This method can be called at any time during the lifetime of a rowset and assuming the current row is within the exception limitations (see below), it cancels the row insertion of the current row.

    In addition, multiple cancellations of row insertions can be made by adjusting the position of the cursor using any of the cursor position control methods such as:

    • CachedRowSet.absolute
    • CachedRowSet.first
    • CachedRowSet.last

    Throws:
    SQLException - if (1) the current row has not been inserted or (2) the cursor is before the first row, after the last row, or on the insert row
    See Also:
    undoDelete(), ResultSet.cancelRowUpdates()

    undoUpdate

    void undoUpdate()
                throws SQLException
    Immediately reverses the last update operation if the row has been modified. This method can be called to reverse updates on all columns until all updates in a row have been rolled back to their state just prior to the last synchronization (acceptChanges) or population. This method may also be called while performing updates to the insert row.

    undoUpdate may be called at any time during the lifetime of a rowset; however, after a synchronization has occurred, this method has no effect until further modification to the rowset data has occurred.

    Throws:
    SQLException - if the cursor is before the first row or after the last row in in this CachedRowSet object
    See Also:
    undoDelete(),
undoInsert(),
ResultSet.cancelRowUpdates()

    columnUpdated

    boolean columnUpdated(int idx)
                      throws SQLException
    Indicates whether the designated column in the current row of this CachedRowSet object has been updated.

    Parameters:
    idx - an int identifying the column to be checked for updates
    Returns:
    true if the designated column has been visibly updated; false otherwise
    Throws:
    SQLException - if the cursor is on the insert row, before the first row, or after the last row
    See Also:
    DatabaseMetaData.updatesAreDetected(int)

    columnUpdated

    boolean columnUpdated(String columnName)
                      throws SQLException
    Indicates whether the designated column in the current row of this CachedRowSet object has been updated.

    Parameters:
    columnName - a String object giving the name of the column to be checked for updates
    Returns:
    true if the column has been visibly updated; false otherwise
    Throws:
    SQLException - if the cursor is on the insert row, before the first row, or after the last row
    See Also:
    DatabaseMetaData.updatesAreDetected(int)

    toCollection

    Collection<?> toCollection()
                           throws SQLException
    Converts this CachedRowSet object to a Collection object that contains all of this CachedRowSet object's data. Implementations have some latitude in how they can represent this Collection object because of the abstract nature of the Collection framework. Each row must be fully represented in either a general purpose Collection implementation or a specialized Collection implementation, such as a TreeMap object or a Vector object. An SQL NULL column value must be represented as a null in the Java programming language.

    The standard reference implementation for the CachedRowSet interface uses a TreeMap object for the rowset, with the values in each row being contained in Vector objects. It is expected that most implementations will do the same.

    The TreeMap type of collection guarantees that the map will be in ascending key order, sorted according to the natural order for the key's class. Each key references a Vector object that corresponds to one row of a RowSet object. Therefore, the size of each Vector object must be exactly equal to the number of columns in the RowSet object. The key used by the TreeMap collection is determined by the implementation, which may choose to leverage a set key that is available within the internal RowSet tabular structure by virtue of a key already set either on the RowSet object itself or on the underlying SQL data.

    Returns:
    a Collection object that contains the values in each row in this CachedRowSet object
    Throws:
    SQLException - if an error occurs generating the collection
    See Also:
    toCollection(int), toCollection(String)

    toCollection

    Collection<?> toCollection(int column)
                           throws SQLException
    Converts the designated column in this CachedRowSet object to a Collection object. Implementations have some latitude in how they can represent this Collection object because of the abstract nature of the Collection framework. Each column value should be fully represented in either a general purpose Collection implementation or a specialized Collection implementation, such as a Vector object. An SQL NULL column value must be represented as a null in the Java programming language.

    The standard reference implementation uses a Vector object to contain the column values, and it is expected that most implementations will do the same. If a Vector object is used, it size must be exactly equal to the number of rows in this CachedRowSet object.

    Parameters:
    column - an int indicating the column whose values are to be represented in a Collection object
    Returns:
    a Collection object that contains the values stored in the specified column of this CachedRowSet object
    Throws:
    SQLException - if an error occurs generating the collection or an invalid column id is provided
    See Also:
    toCollection(), toCollection(String)

    toCollection

    Collection<?> toCollection(String column)
                           throws SQLException
    Converts the designated column in this CachedRowSet object to a Collection object. Implementations have some latitude in how they can represent this Collection object because of the abstract nature of the Collection framework. Each column value should be fully represented in either a general purpose Collection implementation or a specialized Collection implementation, such as a Vector object. An SQL NULL column value must be represented as a null in the Java programming language.

    The standard reference implementation uses a Vector object to contain the column values, and it is expected that most implementations will do the same. If a Vector object is used, it size must be exactly equal to the number of rows in this CachedRowSet object.

    Parameters:
    column - a String object giving the name of the column whose values are to be represented in a collection
    Returns:
    a Collection object that contains the values stored in the specified column of this CachedRowSet object
    Throws:
    SQLException - if an error occurs generating the collection or an invalid column id is provided
    See Also:
    toCollection(), toCollection(int)

    getSyncProvider

    SyncProvider getSyncProvider()
                             throws SQLException
    Retrieves the SyncProvider implementation for this CachedRowSet object. Internally, this method is used by a rowset to trigger read or write actions between the rowset and the data source. For example, a rowset may need to get a handle on the the rowset reader (RowSetReader object) from the SyncProvider to allow the rowset to be populated.
         RowSetReader rowsetReader = null;
     SyncProvider provider =
         SyncFactory.getInstance("javax.sql.rowset.provider.RIOptimisticProvider");
         if (provider instanceof RIOptimisticProvider) {
             rowsetReader = provider.getRowSetReader();
         }
    Assuming rowsetReader is a private, accessible field within the rowset implementation, when an application calls the execute method, it in turn calls on the reader's readData method to populate the RowSet object.

     rowsetReader.readData((RowSetInternal)this);

    In addition, an application can use the SyncProvider object returned by this method to call methods that return information about the SyncProvider object, including information about the vendor, version, provider identification, synchronization grade, and locks it currently has set.

    Returns:
    the SyncProvider object that was set when the rowset was instantiated, or if none was was set, the default provider
    Throws:
    SQLException - if an error occurs while returning the SyncProvider object
    See Also:
    setSyncProvider(java.lang.String)

    setSyncProvider

    void setSyncProvider(String provider)
                     throws SQLException
    Sets the SyncProvider objec for this CachedRowSet object to the one specified. This method allows the SyncProvider object to be reset.

    A CachedRowSet implementation should always be instantiated with an available SyncProvider mechanism, but there are cases where resetting the SyncProvider object is desirable or necessary. For example, an application might want to use the default SyncProvider object for a time and then choose to use a provider that has more recently become available and better fits its needs.

    Resetting the SyncProvider object causes the RowSet object to request a new SyncProvider implementation from the SyncFactory. This has the effect of resetting all previous connections and relationships with the originating data source and can potentially drastically change the synchronization behavior of a disconnected rowset.

    Parameters:
    provider - a String object giving the fully qualified class name of a SyncProvider implementation
    Throws:
    SQLException - if an error occurs while attempting to reset the SyncProvider implementation
    See Also:
    getSyncProvider()

    size

    int size()
    Returns the number of rows in this CachedRowSet object.

    Returns:
    number of rows in the rowset

    setMetaData

    void setMetaData(RowSetMetaData md)
                 throws SQLException
    Sets the metadata for this CachedRowSet object with the given RowSetMetaData object. When a RowSetReader object is reading the contents of a rowset, it creates a RowSetMetaData object and initializes it using the methods in the RowSetMetaData implementation. The reference implementation uses the RowSetMetaDataImpl class. When the reader has completed reading the rowset contents, this method is called internally to pass the RowSetMetaData object to the rowset.

    Parameters:
    md - a RowSetMetaData object containing metadata about the columns in this CachedRowSet object
    Throws:
    SQLException - if invalid metadata is supplied to the rowset

    getOriginal

    ResultSet getOriginal()
                      throws SQLException
    Returns a ResultSet object containing the original value of this CachedRowSet object.

    The cursor for the ResultSet object should be positioned before the first row. In addition, the returned ResultSet object should have the following properties:

    • ResultSet.TYPE_SCROLL_INSENSITIVE
    • ResultSet.CONCUR_UPDATABLE

    The original value for a RowSet object is the value it had before the last synchronization with the underlying data source. If there have been no synchronizations, the original value will be the value with which the RowSet object was populated. This method is called internally when an aplication calls the method acceptChanges and the SyncProvider object has been implemented to check for conflicts. If this is the case, the writer compares the original value with the value currently in the data source to check for conflicts.

    Returns:
    a ResultSet object that contains the original value for this CachedRowSet object
    Throws:
    SQLException - if an error occurs producing the ResultSet object

    getOriginalRow

    ResultSet getOriginalRow()
                         throws SQLException
    Returns a ResultSet object containing the original value for the current row only of this CachedRowSet object.

    The cursor for the ResultSet object should be positioned before the first row. In addition, the returned ResultSet object should have the following properties:

    • ResultSet.TYPE_SCROLL_INSENSITIVE
    • ResultSet.CONCUR_UPDATABLE

    Returns:
    the original result set of the row
    Throws:
    SQLException - if there is no current row
    See Also:
    setOriginalRow()

    setOriginalRow

    void setOriginalRow()
                    throws SQLException
    Sets the current row in this CachedRowSet object as the original row.

    This method is called internally after the any modified values in the current row have been synchronized with the data source. The current row must be tagged as no longer inserted, deleted or updated.

    A call to setOriginalRow is irreversible.

    Throws:
    SQLException - if there is no current row or an error is encountered resetting the contents of the original row
    See Also:
    getOriginalRow()

    getTableName

    String getTableName()
                    throws SQLException
    Returns an identifier for the object (table) that was used to create this CachedRowSet object. This name may be set on multiple occasions, and the specification imposes no limits on how many times this may occur or whether standard implementations should keep track of previous table names.

    Returns:
    a String object giving the name of the table that is the source of data for this CachedRowSet object or null if no name has been set for the table
    Throws:
    SQLException - if an error is encountered returning the table name
    See Also:
    ResultSetMetaData.getTableName(int)

    setTableName

    void setTableName(String tabName)
                  throws SQLException
    Sets the identifier for the table from which this CachedRowSet object was derived to the given table name. The writer uses this name to determine which table to use when comparing the values in the data source with the CachedRowSet object's values during a synchronization attempt. The table identifier also indicates where modified values from this CachedRowSet object should be written.

    The implementation of this CachedRowSet object may obtain the the name internally from the RowSetMetaDataImpl object.

    Parameters:
    tabName - a String object identifying the table from which this CachedRowSet object was derived; cannot be null but may be an empty string
    Throws:
    SQLException - if an error is encountered naming the table or tabName is null
    See Also:
    RowSetMetaData.setTableName(int, java.lang.String), RowSetWriter, SyncProvider

    getKeyColumns

    int[] getKeyColumns()
                    throws SQLException
    Returns an array containing one or more column numbers indicating the columns that form a key that uniquely identifies a row in this CachedRowSet object.

    Returns:
    an array containing the column number or numbers that indicate which columns constitute a primary key for a row in this CachedRowSet object. This array should be empty if no columns are representative of a primary key.
    Throws:
    SQLException - if this CachedRowSet object is empty
    See Also:
    setKeyColumns(int[]), Joinable.getMatchColumnIndexes(), Joinable.getMatchColumnNames()

    setKeyColumns

    void setKeyColumns(int[] keys)
                   throws SQLException
    Sets this CachedRowSet object's keyCols field with the given array of column numbers, which forms a key for uniquely identifying a row in this CachedRowSet object.

    If a CachedRowSet object becomes part of a JoinRowSet object, the keys defined by this method and the resulting constraints are maintained if the columns designated as key columns also become match columns.

    Parameters:
    keys - an array of int indicating the columns that form a primary key for this CachedRowSet object; every element in the array must be greater than 0 and less than or equal to the number of columns in this rowset
    Throws:
    SQLException - if any of the numbers in the given array are not valid for this rowset
    See Also:
    getKeyColumns(),
Joinable.setMatchColumn(String),
Joinable.setMatchColumn(int)

    createShared

    RowSet createShared()
                    throws SQLException
    Returns a new RowSet object backed by the same data as that of this CachedRowSet object. In effect, both CachedRowSet objects have a cursor over the same data. As a result, any changes made by a duplicate are visible to the original and to any other duplicates, just as a change made by the original is visible to all of its duplicates. If a duplicate calls a method that changes the underlying data, the method it calls notifies all registered listeners just as it would when it is called by the original CachedRowSet object.

    In addition, any RowSet object created by this method will have the same properties as this CachedRowSet object. For example, if this CachedRowSet object is read-only, all of its duplicates will also be read-only. If it is changed to be updatable, the duplicates also become updatable.

    NOTE: If multiple threads access RowSet objects created from the createShared() method, the following behavior is specified to preserve shared data integrity: reads and writes of all shared RowSet objects should be made serially between each object and the single underlying tabular structure.

    Returns:
    a new shared RowSet object that has the same properties as this CachedRowSet object and that has a cursor over the same data
    Throws:
    SQLException - if an error occurs or cloning is not supported in the underlying platform
    See Also:
    RowSetEvent, RowSetListener

    createCopy

    CachedRowSet createCopy()
                        throws SQLException
    Creates a RowSet object that is a deep copy of the data in this CachedRowSet object. In contrast to the RowSet object generated from a createShared call, updates made to the copy of the original RowSet object must not be visible to the original RowSet object. Also, any event listeners that are registered with the original RowSet must not have scope over the new RowSet copies. In addition, any constraint restrictions established must be maintained.

    Returns:
    a new RowSet object that is a deep copy of this CachedRowSet object and is completely independent of this CachedRowSet object
    Throws:
    SQLException - if an error occurs in generating the copy of the of this CachedRowSet object
    See Also:
    createShared(),
createCopySchema(),
createCopyNoConstraints(),
RowSetEvent,
RowSetListener

    createCopySchema

    CachedRowSet createCopySchema()
                              throws SQLException
    Creates a CachedRowSet object that is an empty copy of this CachedRowSet object. The copy must not contain any contents but only represent the table structure of the original CachedRowSet object. In addition, primary or foreign key constraints set in the originating CachedRowSet object must be equally enforced in the new empty CachedRowSet object. In contrast to the RowSet object generated from a createShared method call, updates made to a copy of this CachedRowSet object with the createCopySchema method must not be visible to it.

    Applications can form a WebRowSet object from the CachedRowSet object returned by this method in order to export the RowSet schema definition to XML for future use.

    Throws:
    SQLException - if an error occurs in cloning the structure of this CachedRowSet object
    See Also:
    createShared(),
createCopySchema(),
createCopyNoConstraints(),
RowSetEvent,
RowSetListener

    createCopyNoConstraints

    CachedRowSet createCopyNoConstraints()
                                     throws SQLException
    Creates a CachedRowSet object that is a deep copy of this CachedRowSet object's data but is independent of it. In contrast to the RowSet object generated from a createShared method call, updates made to a copy of this CachedRowSet object must not be visible to it. Also, any event listeners that are registered with this CachedRowSet object must not have scope over the new RowSet object. In addition, any constraint restrictions established for this CachedRowSet object must not be maintained in the copy.

    Returns:
    a new CachedRowSet object that is a deep copy of this CachedRowSet object and is completely independent of this CachedRowSet object
    Throws:
    SQLException - if an error occurs in generating the copy of the of this CachedRowSet object
    See Also:
    createCopy(),
createShared(),
createCopySchema(),
RowSetEvent,
RowSetListener

    getRowSetWarnings

    RowSetWarning getRowSetWarnings()
                                throws SQLException
    Retrieves the first warning reported by calls on this RowSet object. Subsequent warnings on this RowSet object will be chained to the RowSetWarning object that this method returns. The warning chain is automatically cleared each time a new row is read. This method may not be called on a RowSet object that has been closed; doing so will cause a SQLException to be thrown.

    Returns:
    RowSetWarning the first RowSetWarning object reported or null if there are none
    Throws:
    SQLException - if this method is called on a closed RowSet
    See Also:
    RowSetWarning

    getShowDeleted

    boolean getShowDeleted()
                       throws SQLException
    Retrieves a boolean indicating whether rows marked for deletion appear in the set of current rows. If true is returned, deleted rows are visible with the current rows. If false is returned, rows are not visible with the set of current rows. The default value is false.

    Standard rowset implementations may choose to restrict this behavior due to security considerations or to better fit certain deployment scenarios. This is left as implementation defined and does not represent standard behavior.

    Note: Allowing deleted rows to remain visible complicates the behavior of some standard JDBC RowSet Implementations methods. However, most rowset users can simply ignore this extra detail because only very specialized applications will likely want to take advantage of this feature.

    Returns:
    true if deleted rows are visible; false otherwise
    Throws:
    SQLException - if a rowset implementation is unable to to determine whether rows marked for deletion are visible
    See Also:
    setShowDeleted(boolean)

    setShowDeleted

    void setShowDeleted(boolean b)
                    throws SQLException
    Sets the property showDeleted to the given boolean value, which determines whether rows marked for deletion appear in the set of current rows. If the value is set to true, deleted rows are immediately visible with the set of current rows. If the value is set to false, the deleted rows are set as invisible with the current set of rows.

    Standard rowset implementations may choose to restrict this behavior due to security considerations or to better fit certain deployment scenarios. This is left as implementations defined and does not represent standard behavior.

    Parameters:
    b - true if deleted rows should be shown; false otherwise
    Throws:
    SQLException - if a rowset implementation is unable to to reset whether deleted rows should be visible
    See Also:
    getShowDeleted()

    commit

    void commit()
            throws SQLException
    Each CachedRowSet object's SyncProvider contains a Connection object from the ResultSet or JDBC properties passed to it's constructors. This method wraps the Connection commit method to allow flexible auto commit or non auto commit transactional control support.

    Makes all changes that are performed by the acceptChanges() method since the previous commit/rollback permanent. This method should be used only when auto-commit mode has been disabled.

    Throws:
    SQLException - if a database access error occurs or this Connection object within this CachedRowSet is in auto-commit mode
    See Also:
    Connection.setAutoCommit(boolean)

    rollback

    void rollback()
              throws SQLException
    Each CachedRowSet object's SyncProvider contains a Connection object from the original ResultSet or JDBC properties passed to it.

    Undoes all changes made in the current transaction. This method should be used only when auto-commit mode has been disabled.

    Throws:
    SQLException - if a database access error occurs or this Connection object within this CachedRowSet is in auto-commit mode.

    rollback

    void rollback(Savepoint s)
              throws SQLException
    Each CachedRowSet object's SyncProvider contains a Connection object from the original ResultSet or JDBC properties passed to it.

    Undoes all changes made in the current transaction back to the last Savepoint transaction marker. This method should be used only when auto-commit mode has been disabled.

    Parameters:
    s - A Savepoint transaction marker
    Throws:
    SQLException - if a database access error occurs or this Connection object within this CachedRowSet is in auto-commit mode.

    rowSetPopulated

    void rowSetPopulated(RowSetEvent event,
                     int numRows)
                     throws SQLException
    Notifies registered listeners that a RowSet object in the given RowSetEvent object has populated a number of additional rows. The numRows parameter ensures that this event will only be fired every numRow.

    The source of the event can be retrieved with the method event.getSource.

    Parameters:
    event - a RowSetEvent object that contains the RowSet object that is the source of the events
    numRows - when populating, the number of rows interval on which the CachedRowSet populated should fire; the default value is zero; cannot be less than fetchSize or zero
    Throws:
    SQLException

    populate

    void populate(ResultSet rs,
              int startRow)
              throws SQLException
    Populates this CachedRowSet object with data from the given ResultSet object. While related to the populate(ResultSet) method, an additional parameter is provided to allow starting position within the ResultSet from where to populate the CachedRowSet instance.

    This method can be used as an alternative to the execute method when an application has a connection to an open ResultSet object. Using the method populate can be more efficient than using the version of the execute method that takes no parameters because it does not open a new connection and re-execute this CachedRowSet object's command. Using the populate method is more a matter of convenience when compared to using the version of execute that takes a ResultSet object.

    Parameters:
    startRow - the position in the ResultSet from where to start populating the records in this CachedRowSet
    rs - the ResultSet object containing the data to be read into this CachedRowSet object
    Throws:
    SQLException - if a null ResultSet object is supplied or this CachedRowSet object cannot retrieve the associated ResultSetMetaData object
    See Also:
    execute(java.sql.Connection), populate(ResultSet), ResultSet, ResultSetMetaData

    setPageSize

    void setPageSize(int size)
                 throws SQLException
    Sets the CachedRowSet object's page-size. A CachedRowSet may be configured to populate itself in page-size sized batches of rows. When either populate() or execute() are called, the CachedRowSet fetches an additional page according to the original SQL query used to populate the RowSet.

    Parameters:
    size - the page-size of the CachedRowSet
    Throws:
    SQLException - if an error occurs setting the CachedRowSet page size or if the page size is less than 0.

    getPageSize

    int getPageSize()
    Returns the page-size for the CachedRowSet object

    Returns:
    an int page size

    nextPage

    boolean nextPage()
                 throws SQLException
    Increments the current page of the CachedRowSet. This causes the CachedRowSet implementation to fetch the next page-size rows and populate the RowSet, if remaining rows remain within scope of the original SQL query used to populated the RowSet.

    Returns:
    true if more pages exist; false if this is the last page
    Throws:
    SQLException - if an error occurs fetching the next page, or if this method is called prematurely before populate or execute.

    previousPage

    boolean previousPage()
                     throws SQLException
    Decrements the current page of the CachedRowSet. This causes the CachedRowSet implementation to fetch the previous page-size rows and populate the RowSet. The amount of rows returned in the previous page must always remain within scope of the original SQL query used to populate the RowSet.

    Returns:
    true if the previous page is successfully retrieved; false if this is the first page.
    Throws:
    SQLException - if an error occurs fetching the previous page, or if this method is called prematurely before populate or execute.
    Overview Package Class Use Tree Deprecated Index Help
            Java™ Platform
    Standard Ed. 6
    PREV CLASS NEXT CLASS FRAMES NO FRAMES
    SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.sql.rowset.BaseRowSet

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.rowset.BaseRowSet

No usage of javax.sql.rowset.BaseRowSet

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.rowset.RowSetMetaDataImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.rowset.RowSetMetaDataImpl

No usage of javax.sql.rowset.RowSetMetaDataImpl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.rowset.RowSetWarning

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.rowset.RowSetWarning

Packages that use RowSetWarning
javax.sql.rowset Standard interfaces and base classes for JDBC RowSet implementations.

Uses of RowSetWarning in javax.sql.rowset

Methods in javax.sql.rowset that return RowSetWarning
RowSetWarning | RowSetWarning.getNextWarning() Retrieves the warning chained to this RowSetWarning object.
RowSetWarning | JdbcRowSet.getRowSetWarnings() Retrieves the first warning reported by calls on this JdbcRowSet object.
RowSetWarning | CachedRowSet.getRowSetWarnings() Retrieves the first warning reported by calls on this RowSet object.

Methods in javax.sql.rowset with parameters of type RowSetWarning
 void RowSetWarning.setNextWarning(RowSetWarning warning)
Sets warning as the next warning, that is, the warning chained to this RowSetWarning object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.rowset.CachedRowSet

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.rowset.CachedRowSet

Packages that use CachedRowSet
javax.sql.rowset Standard interfaces and base classes for JDBC RowSet implementations.

Uses of CachedRowSet in javax.sql.rowset

Subinterfaces of CachedRowSet in javax.sql.rowset
interface | FilteredRowSet The standard interface that all standard implementations of FilteredRowSet must implement.
interface | JoinRowSet The JoinRowSet interface provides a mechanism for combining related data from different RowSet objects into one JoinRowSet object, which represents an SQL JOIN.
interface | WebRowSet The standard interface that all implementations of a WebRowSet must implement.

Methods in javax.sql.rowset that return CachedRowSet
CachedRowSet | CachedRowSet.createCopy() Creates a RowSet object that is a deep copy of the data in this CachedRowSet object.
CachedRowSet | CachedRowSet.createCopyNoConstraints() Creates a CachedRowSet object that is a deep copy of this CachedRowSet object's data but is independent of it.
CachedRowSet | CachedRowSet.createCopySchema() Creates a CachedRowSet object that is an empty copy of this CachedRowSet object.
CachedRowSet | JoinRowSet.toCachedRowSet() Creates a new CachedRowSet object containing the data in this JoinRowSet object, which can be saved to a data source using the SyncProvider object for the CachedRowSet object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.rowset.FilteredRowSet

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.rowset.FilteredRowSet

No usage of javax.sql.rowset.FilteredRowSet

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.rowset.JdbcRowSet

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.rowset.JdbcRowSet

No usage of javax.sql.rowset.JdbcRowSet

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.rowset.Joinable

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.rowset.Joinable

Packages that use Joinable
javax.sql.rowset Standard interfaces and base classes for JDBC RowSet implementations.

Uses of Joinable in javax.sql.rowset

Subinterfaces of Joinable in javax.sql.rowset
interface | CachedRowSet The interface that all standard implementations of CachedRowSet must implement.
interface | FilteredRowSet The standard interface that all standard implementations of FilteredRowSet must implement.
interface | JdbcRowSet The standard interface that all standard implementations of JdbcRowSet must implement.
interface | JoinRowSet The JoinRowSet interface provides a mechanism for combining related data from different RowSet objects into one JoinRowSet object, which represents an SQL JOIN.
interface | WebRowSet The standard interface that all implementations of a WebRowSet must implement.

Methods in javax.sql.rowset with parameters of type Joinable
 void JoinRowSet.addRowSet(Joinable rowset)
Adds the given RowSet object to this JoinRowSet object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.rowset.JoinRowSet

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.rowset.JoinRowSet

No usage of javax.sql.rowset.JoinRowSet

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.rowset.Predicate

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.rowset.Predicate

Packages that use Predicate
javax.sql.rowset Standard interfaces and base classes for JDBC RowSet implementations.

Uses of Predicate in javax.sql.rowset

Methods in javax.sql.rowset that return Predicate
 Predicate FilteredRowSet.getFilter()
Retrieves the active filter for this FilteredRowSet object.

Methods in javax.sql.rowset with parameters of type Predicate
 void FilteredRowSet.setFilter(Predicate p)
Applies the given Predicate object to this FilteredRowSet object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.rowset.WebRowSet

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.rowset.WebRowSet

Packages that use WebRowSet
javax.sql.rowset | Standard interfaces and base classes for JDBC RowSet implementations.
javax.sql.rowset.spi | The standard classes and interfaces that a third party vendor has to use in its implementation of a synchronization provider.

Uses of WebRowSet in javax.sql.rowset

Subinterfaces of WebRowSet in javax.sql.rowset
interface | FilteredRowSet The standard interface that all standard implementations of FilteredRowSet must implement.
interface | JoinRowSet The JoinRowSet interface provides a mechanism for combining related data from different RowSet objects into one JoinRowSet object, which represents an SQL JOIN.

Uses of WebRowSet in javax.sql.rowset.spi

Methods in javax.sql.rowset.spi with parameters of type WebRowSet
void | XmlReader.readXML(WebRowSet caller, Reader reader) Reads and parses the given WebRowSet object from the given input stream in XML format.
void | XmlWriter.writeXML(WebRowSet caller, Writer writer) Writes the given WebRowSet object to the specified java.io.Writer output stream as an XML document.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


FilteredRowSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset
Interface FilteredRowSet

All Superinterfaces:
CachedRowSet, Joinable, ResultSet, RowSet, WebRowSet, Wrapper
public interface FilteredRowSet
extends WebRowSet

The standard interface that all standard implementations of FilteredRowSet must implement. The FilteredRowSetImpl class provides the reference implementation which may be extended if required. Alternatively, a vendor is free to implement its own version by implementing this interface.

1.0 Background

There are occasions when a RowSet object has a need to provide a degree of filtering to its contents. One possible solution is to provide a query language for all standard RowSet implementations; however, this is an impractical approach for lightweight components such as disconnected RowSet objects. The FilteredRowSet interface seeks to address this need without supplying a heavyweight query language along with the processing that such a query language would require.

A JDBC FilteredRowSet standard implementation implements the RowSet interfaces and extends the CachedRowSetTM class. The CachedRowSet class provides a set of protected cursor manipulation methods, which a FilteredRowSet implementation can override to supply filtering support.

2.0 Predicate Sharing

If a FilteredRowSet implementation is shared using the inherited createShared method in parent interfaces, the Predicate should be shared without modification by all FilteredRowSet instance clones.

3.0 Usage

By implementing a Predicate (see example in Predicate class JavaDoc), a FilteredRowSet could then be used as described below.

     FilteredRowSet frs = new FilteredRowSetImpl();
     frs.populate(rs);

     Range name = new Range("Alpha", "Bravo", "columnName");
     frs.setFilter(name);

     frs.next() // only names from "Alpha" to "Bravo" will be returned
In the example above, we initialize a Range object which implements the Predicate interface. This object expresses the following constraints: All rows outputted or modified from this FilteredRowSet object must fall between the values 'Alpha' and 'Bravo' both values inclusive, in the column 'columnName'. If a filter is applied to a FilteredRowSet object that contains no data that falls within the range of the filter, no rows are returned.

This framework allows multiple classes implementing predicates to be used in combination to achieved the required filtering result with out the need for query language processing.

4.0 Updating a FilteredRowSet Object

The predicate set on a FilteredRowSet object applies a criterion on all rows in a RowSet object to manage a subset of rows in a RowSet object. This criterion governs the subset of rows that are visible and also defines which rows can be modified, deleted or inserted.

Therefore, the predicate set on a FilteredRowSet object must be considered as bi-directional and the set criterion as the gating mechanism for all views and updates to the FilteredRowSet object. Any attempt to update the FilteredRowSet that violates the criterion will result in a SQLException object being thrown.

The FilteredRowSet range criterion can be modified by applying a new Predicate object to the FilteredRowSet instance at any time. This is possible if no additional references to the FilteredRowSet object are detected. A new filter has has an immediate effect on criterion enforcement within the FilteredRowSet object, and all subsequent views and updates will be subject to similar enforcement.

5.0 Behavior of Rows Outside the Filter

Rows that fall outside of the filter set on a FilteredRowSet object cannot be modified until the filter is removed or a new filter is applied.

Furthermore, only rows that fall within the bounds of a filter will be synchronized with the data source.

Field Summary
Fields inherited from interface javax.sql.rowset.WebRowSet
PUBLIC_XML_SCHEMA, SCHEMA_SYSTEM_ID
Fields inherited from interface javax.sql.rowset.CachedRowSet
COMMIT_ON_ACCEPT_CHANGES
Fields inherited from interface java.sql.ResultSet
CLOSE_CURSORS_AT_COMMIT, CONCUR_READ_ONLY, CONCUR_UPDATABLE, FETCH_FORWARD, FETCH_REVERSE, FETCH_UNKNOWN, HOLD_CURSORS_OVER_COMMIT, TYPE_FORWARD_ONLY, TYPE_SCROLL_INSENSITIVE, TYPE_SCROLL_SENSITIVE
Method Summary
Predicate | getFilter() Retrieves the active filter for this FilteredRowSet object.
void | setFilter(Predicate p) Applies the given Predicate object to this FilteredRowSet object.
Methods inherited from interface javax.sql.rowset.WebRowSet
readXml, readXml, writeXml, writeXml, writeXml, writeXml
Methods inherited from interface javax.sql.rowset.CachedRowSet
acceptChanges, acceptChanges, columnUpdated, columnUpdated, commit, createCopy, createCopyNoConstraints, createCopySchema, createShared, execute, getKeyColumns, getOriginal, getOriginalRow, getPageSize, getRowSetWarnings, getShowDeleted, getSyncProvider, getTableName, nextPage, populate, populate, previousPage, release, restoreOriginal, rollback, rollback, rowSetPopulated, setKeyColumns, setMetaData, setOriginalRow, setPageSize, setShowDeleted, setSyncProvider, setTableName, size, toCollection, toCollection, toCollection, undoDelete, undoInsert, undoUpdate
Methods inherited from interface javax.sql.RowSet
addRowSetListener, clearParameters, execute, getCommand, getDataSourceName, getEscapeProcessing, getMaxFieldSize, getMaxRows, getPassword, getQueryTimeout, getTransactionIsolation, getTypeMap, getUrl, getUsername, isReadOnly, removeRowSetListener, setArray, setAsciiStream, setAsciiStream, setAsciiStream, setAsciiStream, setBigDecimal, setBigDecimal, setBinaryStream, setBinaryStream, setBinaryStream, setBinaryStream, setBlob, setBlob, setBlob, setBlob, setBlob, setBlob, setBoolean, setBoolean, setByte, setByte, setBytes, setBytes, setCharacterStream, setCharacterStream, setCharacterStream, setCharacterStream, setClob, setClob, setClob, setClob, setClob, setClob, setCommand, setConcurrency, setDataSourceName, setDate, setDate, setDate, setDate, setDouble, setDouble, setEscapeProcessing, setFloat, setFloat, setInt, setInt, setLong, setLong, setMaxFieldSize, setMaxRows, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNClob, setNClob, setNClob, setNClob, setNClob, setNClob, setNString, setNString, setNull, setNull, setNull, setNull, setObject, setObject, setObject, setObject, setObject, setObject, setPassword, setQueryTimeout, setReadOnly, setRef, setRowId, setRowId, setShort, setShort, setSQLXML, setSQLXML, setString, setString, setTime, setTime, setTime, setTime, setTimestamp, setTimestamp, setTimestamp, setTimestamp, setTransactionIsolation, setType, setTypeMap, setURL, setUrl, setUsername
Methods inherited from interface java.sql.ResultSet
absolute, afterLast, beforeFirst, cancelRowUpdates, clearWarnings, close, deleteRow, findColumn, first, getArray, getArray, getAsciiStream, getAsciiStream, getBigDecimal, getBigDecimal, getBigDecimal, getBigDecimal, getBinaryStream, getBinaryStream, getBlob, getBlob, getBoolean, getBoolean, getByte, getByte, getBytes, getBytes, getCharacterStream, getCharacterStream, getClob, getClob, getConcurrency, getCursorName, getDate, getDate, getDate, getDate, getDouble, getDouble, getFetchDirection, getFetchSize, getFloat, getFloat, getHoldability, getInt, getInt, getLong, getLong, getMetaData, getNCharacterStream, getNCharacterStream, getNClob, getNClob, getNString, getNString, getObject, getObject, getObject, getObject, getRef, getRef, getRow, getRowId, getRowId, getShort, getShort, getSQLXML, getSQLXML, getStatement, getString, getString, getTime, getTime, getTime, getTime, getTimestamp, getTimestamp, getTimestamp, getTimestamp, getType, getUnicodeStream, getUnicodeStream, getURL, getURL, getWarnings, insertRow, isAfterLast, isBeforeFirst, isClosed, isFirst, isLast, last, moveToCurrentRow, moveToInsertRow, next, previous, refreshRow, relative, rowDeleted, rowInserted, rowUpdated, setFetchDirection, setFetchSize, updateArray, updateArray, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateBigDecimal, updateBigDecimal, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBoolean, updateBoolean, updateByte, updateByte, updateBytes, updateBytes, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateClob, updateClob, updateClob, updateClob, updateClob, updateClob, updateDate, updateDate, updateDouble, updateDouble, updateFloat, updateFloat, updateInt, updateInt, updateLong, updateLong, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNString, updateNString, updateNull, updateNull, updateObject, updateObject, updateObject, updateObject, updateRef, updateRef, updateRow, updateRowId, updateRowId, updateShort, updateShort, updateSQLXML, updateSQLXML, updateString, updateString, updateTime, updateTime, updateTimestamp, updateTimestamp, wasNull
Methods inherited from interface java.sql.Wrapper
isWrapperFor, unwrap
Methods inherited from interface javax.sql.rowset.Joinable
getMatchColumnIndexes, getMatchColumnNames, setMatchColumn, setMatchColumn, setMatchColumn, setMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn

Method Detail

setFilter

void setFilter(Predicate p)
               throws SQLException
Applies the given Predicate object to this FilteredRowSet object. The filter applies controls both to inbound and outbound views, constraining which rows are visible and which rows can be manipulated.

A new Predicate object may be set at any time. This has the effect of changing constraints on the RowSet object's data. In addition, modifying the filter at runtime presents issues whereby multiple components may be operating on one FilteredRowSet object. Application developers must take responsibility for managing multiple handles to FilteredRowSet objects when their underling Predicate objects change.

Parameters:
p - a Predicate object defining the filter for this FilteredRowSet object. Setting a null value will clear the predicate, allowing all rows to become visible.
Throws:
SQLException - if an error occurs when setting the Predicate object

getFilter

Predicate getFilter()
Retrieves the active filter for this FilteredRowSet object.

Returns:
p the Predicate for this FilteredRowSet object; null if no filter has been set.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JdbcRowSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset
Interface JdbcRowSet

All Superinterfaces:
Joinable, ResultSet, RowSet, Wrapper
public interface JdbcRowSet
extends RowSet, Joinable

The standard interface that all standard implementations of JdbcRowSet must implement.

1.0 Overview

A wrapper around a ResultSet object that makes it possible to use the result set as a JavaBeansTM component. Thus, a JdbcRowSet object can be one of the Beans that a tool makes available for composing an application. Because a JdbcRowSet is a connected rowset, that is, it continually maintains its connection to a database using a JDBC technology-enabled driver, it also effectively makes the driver a JavaBeans component.

Because it is always connected to its database, an instance of JdbcRowSet can simply take calls invoked on it and in turn call them on its ResultSet object. As a consequence, a result set can, for example, be a component in a Swing application.

Another advantage of a JdbcRowSet object is that it can be used to make a ResultSet object scrollable and updatable. All RowSet objects are by default scrollable and updatable. If the driver and database being used do not support scrolling and/or updating of result sets, an application can populate a JdbcRowSet object with the data of a ResultSet object and then operate on the JdbcRowSet object as if it were the ResultSet object.

2.0 Creating a JdbcRowSet Object

The reference implementation of the JdbcRowSet interface, JdbcRowSetImpl, provides an implementation of the default constructor. A new instance is initialized with default values, which can be set with new values as needed. A new instance is not really functional until its execute method is called. In general, this method does the following:
  • establishes a connection with a database
  • creates a PreparedStatement object and sets any of its placeholder parameters
  • executes the statement to create a ResultSet object
If the execute method is successful, it will set the appropriate private JdbcRowSet fields with the following:
  • a Connection object -- the connection between the rowset and the database
  • a PreparedStatement object -- the query that produces the result set
  • a ResultSet object -- the result set that the rowset's command produced and that is being made, in effect, a JavaBeans component
If these fields have not been set, meaning that the execute method has not executed successfully, no methods other than execute and close may be called on the rowset. All other public methods will throw an exception.

Before calling the execute method, however, the command and properties needed for establishing a connection must be set. The following code fragment creates a JdbcRowSetImpl object, sets the command and connection properties, sets the placeholder parameter, and then invokes the method execute.

     JdbcRowSetImpl jrs = new JdbcRowSetImpl();
     jrs.setCommand("SELECT * FROM TITLES WHERE TYPE = ?");
     jrs.setURL("jdbc:myDriver:myAttribute");
     jrs.setUsername("cervantes");
     jrs.setPassword("sancho");
     jrs.setString(1, "BIOGRAPHY");
     jrs.execute();
The variable jrs now represents an instance of JdbcRowSetImpl that is a thin wrapper around the ResultSet object containing all the rows in the table TITLES where the type of book is biography. At this point, operations called on jrs will affect the rows in the result set, which is effectively a JavaBeans component.

The implementation of the RowSet method execute in the JdbcRowSet reference implementation differs from that in the CachedRowSetTM reference implementation to account for the different requirements of connected and disconnected RowSet objects.

Field Summary
Fields inherited from interface java.sql.ResultSet
CLOSE_CURSORS_AT_COMMIT, CONCUR_READ_ONLY, CONCUR_UPDATABLE, FETCH_FORWARD, FETCH_REVERSE, FETCH_UNKNOWN, HOLD_CURSORS_OVER_COMMIT, TYPE_FORWARD_ONLY, TYPE_SCROLL_INSENSITIVE, TYPE_SCROLL_SENSITIVE
Method Summary
void | commit() Each JdbcRowSet contains a Connection object from the ResultSet or JDBC properties passed to it's constructors.
boolean | getAutoCommit() Each JdbcRowSet contains a Connection object from the original ResultSet or JDBC properties passed to it.
RowSetWarning | getRowSetWarnings() Retrieves the first warning reported by calls on this JdbcRowSet object.
boolean | getShowDeleted() Retrieves a boolean indicating whether rows marked for deletion appear in the set of current rows.
void | rollback() Each JdbcRowSet contains a Connection object from the original ResultSet or JDBC properties passed to it.
void | rollback(Savepoint s) Each JdbcRowSet contains a Connection object from the original ResultSet or JDBC properties passed to it.
void | setAutoCommit(boolean autoCommit) Each JdbcRowSet contains a Connection object from the original ResultSet or JDBC properties passed to it.
void | setShowDeleted(boolean b) Sets the property showDeleted to the given boolean value.
Methods inherited from interface javax.sql.RowSet
addRowSetListener, clearParameters, execute, getCommand, getDataSourceName, getEscapeProcessing, getMaxFieldSize, getMaxRows, getPassword, getQueryTimeout, getTransactionIsolation, getTypeMap, getUrl, getUsername, isReadOnly, removeRowSetListener, setArray, setAsciiStream, setAsciiStream, setAsciiStream, setAsciiStream, setBigDecimal, setBigDecimal, setBinaryStream, setBinaryStream, setBinaryStream, setBinaryStream, setBlob, setBlob, setBlob, setBlob, setBlob, setBlob, setBoolean, setBoolean, setByte, setByte, setBytes, setBytes, setCharacterStream, setCharacterStream, setCharacterStream, setCharacterStream, setClob, setClob, setClob, setClob, setClob, setClob, setCommand, setConcurrency, setDataSourceName, setDate, setDate, setDate, setDate, setDouble, setDouble, setEscapeProcessing, setFloat, setFloat, setInt, setInt, setLong, setLong, setMaxFieldSize, setMaxRows, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNClob, setNClob, setNClob, setNClob, setNClob, setNClob, setNString, setNString, setNull, setNull, setNull, setNull, setObject, setObject, setObject, setObject, setObject, setObject, setPassword, setQueryTimeout, setReadOnly, setRef, setRowId, setRowId, setShort, setShort, setSQLXML, setSQLXML, setString, setString, setTime, setTime, setTime, setTime, setTimestamp, setTimestamp, setTimestamp, setTimestamp, setTransactionIsolation, setType, setTypeMap, setURL, setUrl, setUsername
Methods inherited from interface java.sql.ResultSet
absolute, afterLast, beforeFirst, cancelRowUpdates, clearWarnings, close, deleteRow, findColumn, first, getArray, getArray, getAsciiStream, getAsciiStream, getBigDecimal, getBigDecimal, getBigDecimal, getBigDecimal, getBinaryStream, getBinaryStream, getBlob, getBlob, getBoolean, getBoolean, getByte, getByte, getBytes, getBytes, getCharacterStream, getCharacterStream, getClob, getClob, getConcurrency, getCursorName, getDate, getDate, getDate, getDate, getDouble, getDouble, getFetchDirection, getFetchSize, getFloat, getFloat, getHoldability, getInt, getInt, getLong, getLong, getMetaData, getNCharacterStream, getNCharacterStream, getNClob, getNClob, getNString, getNString, getObject, getObject, getObject, getObject, getRef, getRef, getRow, getRowId, getRowId, getShort, getShort, getSQLXML, getSQLXML, getStatement, getString, getString, getTime, getTime, getTime, getTime, getTimestamp, getTimestamp, getTimestamp, getTimestamp, getType, getUnicodeStream, getUnicodeStream, getURL, getURL, getWarnings, insertRow, isAfterLast, isBeforeFirst, isClosed, isFirst, isLast, last, moveToCurrentRow, moveToInsertRow, next, previous, refreshRow, relative, rowDeleted, rowInserted, rowUpdated, setFetchDirection, setFetchSize, updateArray, updateArray, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateBigDecimal, updateBigDecimal, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBoolean, updateBoolean, updateByte, updateByte, updateBytes, updateBytes, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateClob, updateClob, updateClob, updateClob, updateClob, updateClob, updateDate, updateDate, updateDouble, updateDouble, updateFloat, updateFloat, updateInt, updateInt, updateLong, updateLong, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNString, updateNString, updateNull, updateNull, updateObject, updateObject, updateObject, updateObject, updateRef, updateRef, updateRow, updateRowId, updateRowId, updateShort, updateShort, updateSQLXML, updateSQLXML, updateString, updateString, updateTime, updateTime, updateTimestamp, updateTimestamp, wasNull
Methods inherited from interface java.sql.Wrapper
isWrapperFor, unwrap
Methods inherited from interface javax.sql.rowset.Joinable
getMatchColumnIndexes, getMatchColumnNames, setMatchColumn, setMatchColumn, setMatchColumn, setMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn

Method Detail

getShowDeleted

boolean getShowDeleted()
                       throws SQLException
Retrieves a boolean indicating whether rows marked for deletion appear in the set of current rows. If true is returned, deleted rows are visible with the current rows. If false is returned, rows are not visible with the set of current rows. The default value is false.

Standard rowset implementations may choose to restrict this behavior for security considerations or for certain deployment scenarios. The visibility of deleted rows is implementation-defined and does not represent standard behavior.

Note: Allowing deleted rows to remain visible complicates the behavior of some standard JDBC RowSet implementations methods. However, most rowset users can simply ignore this extra detail because only very specialized applications will likely want to take advantage of this feature.

Returns:
true if deleted rows are visible; false otherwise
Throws:
SQLException - if a rowset implementation is unable to to determine whether rows marked for deletion remain visible
See Also:
setShowDeleted(boolean)

setShowDeleted

void setShowDeleted(boolean b)
                    throws SQLException
Sets the property showDeleted to the given boolean value. This property determines whether rows marked for deletion continue to appear in the set of current rows. If the value is set to true, deleted rows are immediately visible with the set of current rows. If the value is set to false, the deleted rows are set as invisible with the current set of rows.

Standard rowset implementations may choose to restrict this behavior for security considerations or for certain deployment scenarios. This is left as implementation-defined and does not represent standard behavior.

Parameters:
b - true if deleted rows should be shown; false otherwise
Throws:
SQLException - if a rowset implementation is unable to to reset whether deleted rows should be visible
See Also:
getShowDeleted()

getRowSetWarnings

RowSetWarning getRowSetWarnings()
                                throws SQLException
Retrieves the first warning reported by calls on this JdbcRowSet object. If a second warning was reported on this JdbcRowSet object, it will be chained to the first warning and can be retrieved by calling the method RowSetWarning.getNextWarning on the first warning. Subsequent warnings on this JdbcRowSet object will be chained to the RowSetWarning objects returned by the method RowSetWarning.getNextWarning. The warning chain is automatically cleared each time a new row is read. This method may not be called on a RowSet object that has been closed; doing so will cause an SQLException to be thrown.

Because it is always connected to its data source, a JdbcRowSet object can rely on the presence of active Statement, Connection, and ResultSet instances. This means that applications can obtain additional SQLWarning notifications by calling the getNextWarning methods that they provide. Disconnected Rowset objects, such as a CachedRowSet object, do not have access to these getNextWarning methods.

Returns:
the first RowSetWarning object reported on this JdbcRowSet object or null if there are none
Throws:
SQLException - if this method is called on a closed JdbcRowSet object
See Also:
RowSetWarning

commit

void commit()
            throws SQLException
Each JdbcRowSet contains a Connection object from the ResultSet or JDBC properties passed to it's constructors. This method wraps the Connection commit method to allow flexible auto commit or non auto commit transactional control support.

Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by this Connection object. This method should be used only when auto-commit mode has been disabled.

Throws:
SQLException - if a database access error occurs or this Connection object within this JdbcRowSet is in auto-commit mode
See Also:
Connection.setAutoCommit(boolean)

getAutoCommit

boolean getAutoCommit()
                      throws SQLException
Each JdbcRowSet contains a Connection object from the original ResultSet or JDBC properties passed to it. This method wraps the Connection's getAutoCommit method to allow an application to determine the JdbcRowSet transaction behavior.

Sets this connection's auto-commit mode to the given state. If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either the method commit or the method rollback. By default, new connections are in auto-commit mode.

Throws:
SQLException - if a database access error occurs
See Also:
Connection.getAutoCommit()

setAutoCommit

void setAutoCommit(boolean autoCommit)
                   throws SQLException
Each JdbcRowSet contains a Connection object from the original ResultSet or JDBC properties passed to it. This method wraps the Connection's getAutoCommit method to allow an application to set the JdbcRowSet transaction behavior.

Sets the current auto-commit mode for this Connection object.

Throws:
SQLException - if a database access error occurs
See Also:
Connection.setAutoCommit(boolean)

rollback

void rollback()
              throws SQLException
Each JdbcRowSet contains a Connection object from the original ResultSet or JDBC properties passed to it. Undoes all changes made in the current transaction and releases any database locks currently held by this Connection object. This method should be used only when auto-commit mode has been disabled.

Throws:
SQLException - if a database access error occurs or this Connection object within this JdbcRowSet is in auto-commit mode.
See Also:
rollback(Savepoint)

rollback

void rollback(Savepoint s)
              throws SQLException
Each JdbcRowSet contains a Connection object from the original ResultSet or JDBC properties passed to it. Undoes all changes made in the current transaction to the last set savepoint and releases any database locks currently held by this Connection object. This method should be used only when auto-commit mode has been disabled.

Throws:
SQLException - if a database access error occurs or this Connection object within this JdbcRowSet is in auto-commit mode.
See Also:
rollback()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Joinable

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset
Interface Joinable

All Known Subinterfaces:
CachedRowSet, FilteredRowSet, JdbcRowSet, JoinRowSet, WebRowSet
public interface Joinable

1.0 Background

The Joinable interface provides the methods for getting and setting a match column, which is the basis for forming the SQL JOIN formed by adding RowSet objects to a JoinRowSet object.

Any standard RowSet implementation may implement the Joinable interface in order to be added to a JoinRowSet object. Implementing this interface gives a RowSet object the ability to use Joinable methods, which set, retrieve, and get information about match columns. An application may add a RowSet object that has not implemented the Joinable interface to a JoinRowSet object, but to do so it must use one of the JoinRowSet.addRowSet methods that takes both a RowSet object and a match column or an array of RowSet objects and an array of match columns.

To get access to the methods in the Joinable interface, a RowSet object implements at least one of the five standard RowSet interfaces and also implements the Joinable interface. In addition, most RowSet objects extend the BaseRowSet class. For example:

     class MyRowSetImpl extends BaseRowSet implements CachedRowSet, Joinable {
         :
         :
     }

2.0 Usage Guidelines

The methods in the Joinable interface allow a RowSet object to set a match column, retrieve a match column, or unset a match column, which is the column upon which an SQL JOIN can be based. An instance of a class that implements these methods can be added to a JoinRowSet object to allow an SQL JOIN relationship to be established.

     CachedRowSet crs = new MyRowSetImpl();
     crs.populate((ResultSet)rs);
     (Joinable)crs.setMatchColumnIndex(1);

     JoinRowSet jrs = new JoinRowSetImpl();
     jrs.addRowSet(crs);
In the previous example, crs is a CachedRowSet object that has emplemented the Joinable interface. In the following example, crs2 has not, so it must supply the match column as an argument to the addRowSet method. This example assumes that column 1 is the match column.
     CachedRowSet crs2 = new MyRowSetImpl();
     crs2.populate((ResultSet)rs);

     JoinRowSet jrs2 = new JoinRowSetImpl();
     jrs2.addRowSet(crs2, 1);

The JoinRowSet interface makes it possible to get data from one or more RowSet objects consolidated into one table without having to incur the expense of creating a connection to a database. It is therefore ideally suited for use by disconnected RowSet objects. Nevertheless, any RowSet object may implement this interface regardless of whether it is connected or disconnected. Note that a JdbcRowSet object, being always connected to its data source, can become part of an SQL JOIN directly without having to become part of a JoinRowSet object.

3.0 Managing Multiple Match Columns

The index array passed into the setMatchColumn methods indicates how many match columns are being set (the length of the array) in addition to which columns will be used for the match. For example:
     int[] i = {1, 2, 4, 7}; // indicates four match columns, with column
                             // indexes 1, 2, 4, 7 participating in the JOIN.
     Joinable.setMatchColumn(i);
Subsequent match columns may be added as follows to a different Joinable object (a RowSet object that has implemented the Joinable interface).
     int[] w = {3, 2, 5, 3};
     Joinable2.setMatchColumn(w);
When an application adds two or more RowSet objects to a JoinRowSet object, the order of the indexes in the array is particularly important. Each index of the array maps directly to the corresponding index of the previously added RowSet object. If overlap or underlap occurs, the match column data is maintained in the event an additional Joinable RowSet is added and needs to relate to the match column data. Therefore, applications can set multiple match columns in any order, but this order has a direct effect on the outcome of the SQL JOIN.

This assertion applies in exactly the same manner when column names are used rather than column indexes to indicate match columns.

See Also:
JoinRowSet

Method Summary
int[] | getMatchColumnIndexes() Retrieves the indexes of the match columns that were set for this RowSet object with the method setMatchColumn(int[] columnIdxes).
String[] | getMatchColumnNames() Retrieves the names of the match columns that were set for this RowSet object with the method setMatchColumn(String [] columnNames).
void | setMatchColumn(int columnIdx) Sets the designated column as the match column for this RowSet object.
void | setMatchColumn(int[] columnIdxes) Sets the designated columns as the match column for this RowSet object.
void | setMatchColumn(String columnName) Sets the designated column as the match column for this RowSet object.
void | setMatchColumn(String[] columnNames) Sets the designated columns as the match column for this RowSet object.
void | unsetMatchColumn(int columnIdx) Unsets the designated column as the match column for this RowSet object.
void | unsetMatchColumn(int[] columnIdxes) Unsets the designated columns as the match column for this RowSet object.
void | unsetMatchColumn(String columnName) Unsets the designated column as the match column for this RowSet object.
void | unsetMatchColumn(String[] columnName) Unsets the designated columns as the match columns for this RowSet object.

Method Detail

setMatchColumn

void setMatchColumn(int columnIdx)
                    throws SQLException
Sets the designated column as the match column for this RowSet object. A JoinRowSet object can now add this RowSet object based on the match column.

Sub-interfaces such as the CachedRowSetTM interface define the method CachedRowSet.setKeyColumns, which allows primary key semantics to be enforced on specific columns. Implementations of the setMatchColumn(int columnIdx) method should ensure that the constraints on the key columns are maintained when a CachedRowSet object sets a primary key column as a match column.

Parameters:
columnIdx - an int identifying the index of the column to be set as the match column
Throws:
SQLException - if an invalid column index is set
See Also:
setMatchColumn(int[]), unsetMatchColumn(int)

setMatchColumn

void setMatchColumn(int[] columnIdxes)
                    throws SQLException
Sets the designated columns as the match column for this RowSet object. A JoinRowSet object can now add this RowSet object based on the match column.

Parameters:
columnIdxes - an array of int identifying the indexes of the columns to be set as the match columns
Throws:
SQLException - if an invalid column index is set
See Also:
setMatchColumn(int[]), unsetMatchColumn(int[])

setMatchColumn

void setMatchColumn(String columnName)
                    throws SQLException
Sets the designated column as the match column for this RowSet object. A JoinRowSet object can now add this RowSet object based on the match column.

Subinterfaces such as the CachedRowSet interface define the method CachedRowSet.setKeyColumns, which allows primary key semantics to be enforced on specific columns. Implementations of the setMatchColumn(String columnIdx) method should ensure that the constraints on the key columns are maintained when a CachedRowSet object sets a primary key column as a match column.

Parameters:
columnName - a String object giving the name of the column to be set as the match column
Throws:
SQLException - if an invalid column name is set, the column name is a null, or the column name is an empty string
See Also:
unsetMatchColumn(int), setMatchColumn(int[])

setMatchColumn

void setMatchColumn(String[] columnNames)
                    throws SQLException
Sets the designated columns as the match column for this RowSet object. A JoinRowSet object can now add this RowSet object based on the match column.

Parameters:
columnNames - an array of String objects giving the names of the column to be set as the match columns
Throws:
SQLException - if an invalid column name is set, the column name is a null, or the column name is an empty string
See Also:
unsetMatchColumn(int), setMatchColumn(int[])

getMatchColumnIndexes

int[] getMatchColumnIndexes()
                            throws SQLException
Retrieves the indexes of the match columns that were set for this RowSet object with the method setMatchColumn(int[] columnIdxes).

Returns:
an int array identifying the indexes of the columns that were set as the match columns for this RowSet object
Throws:
SQLException - if no match column has been set
See Also:
setMatchColumn(int), unsetMatchColumn(int)

getMatchColumnNames

String[] getMatchColumnNames()
                             throws SQLException
Retrieves the names of the match columns that were set for this RowSet object with the method setMatchColumn(String [] columnNames).

Returns:
an array of String objects giving the names of the columns set as the match columns for this RowSet object
Throws:
SQLException - if no match column has been set
See Also:
setMatchColumn(int), unsetMatchColumn(int)

unsetMatchColumn

void unsetMatchColumn(int columnIdx)
                      throws SQLException
Unsets the designated column as the match column for this RowSet object.

RowSet objects that implement the Joinable interface must ensure that a key-like constraint continues to be enforced until the method CachedRowSet.unsetKeyColumns has been called on the designated column.

Parameters:
columnIdx - an int that identifies the index of the column that is to be unset as a match column
Throws:
SQLException - if an invalid column index is designated or if the designated column was not previously set as a match column
See Also:
setMatchColumn(int)

unsetMatchColumn

void unsetMatchColumn(int[] columnIdxes)
                      throws SQLException
Unsets the designated columns as the match column for this RowSet object.

Parameters:
columnIdxes - an arrary of int that identifies the indexes of the columns that are to be unset as match columns
Throws:
SQLException - if an invalid column index is designated or if the designated column was not previously set as a match column
See Also:
setMatchColumn(int)

unsetMatchColumn

void unsetMatchColumn(String columnName)
                      throws SQLException
Unsets the designated column as the match column for this RowSet object.

RowSet objects that implement the Joinable interface must ensure that a key-like constraint continues to be enforced until the method CachedRowSet.unsetKeyColumns has been called on the designated column.

Parameters:
columnName - a String object giving the name of the column that is to be unset as a match column
Throws:
SQLException - if an invalid column name is designated or the designated column was not previously set as a match column
See Also:
setMatchColumn(int)

unsetMatchColumn

void unsetMatchColumn(String[] columnName)
                      throws SQLException
Unsets the designated columns as the match columns for this RowSet object.

Parameters:
columnName - an array of String objects giving the names of the columns that are to be unset as the match columns
Throws:
SQLException - if an invalid column name is designated or the designated column was not previously set as a match column
See Also:
setMatchColumn(int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JoinRowSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset
Interface JoinRowSet

All Superinterfaces:
CachedRowSet, Joinable, ResultSet, RowSet, WebRowSet, Wrapper
public interface JoinRowSet
extends WebRowSet

The JoinRowSet interface provides a mechanism for combining related data from different RowSet objects into one JoinRowSet object, which represents an SQL JOIN. In other words, a JoinRowSet object acts as a container for the data from RowSet objects that form an SQL JOIN relationship.

The Joinable interface provides the methods for setting, retrieving, and unsetting a match column, the basis for establishing an SQL JOIN relationship. The match column may alternatively be set by supplying it to the appropriate version of the JointRowSet method addRowSet.

1.0 Overview

Disconnected RowSet objects (CachedRowSet objects and implementations extending the CachedRowSet interface) do not have a standard way to establish an SQL JOIN between RowSet objects without the expensive operation of reconnecting to the data source. The JoinRowSet interface is specifically designed to address this need.

Any RowSet object can be added to a JoinRowSet object to become part of an SQL JOIN relationship. This means that both connected and disconnected RowSet objects can be part of a JOIN. RowSet objects operating in a connected environment (JdbcRowSet objects) are encouraged to use the database to which they are already connected to establish SQL JOIN relationships between tables directly. However, it is possible for a JdbcRowSet object to be added to a JoinRowSet object if necessary.

Any number of RowSet objects can be added to an instance of JoinRowSet provided that they can be related in an SQL JOIN. By definition, the SQL JOIN statement is used to combine the data contained in two or more relational database tables based upon a common attribute. The Joinable interface provides the methods for establishing a common attribute, which is done by setting a match column. The match column commonly coincides with the primary key, but there is no requirement that the match column be the same as the primary key. By establishing and then enforcing column matches, a JoinRowSet object establishes JOIN relationships between RowSet objects without the assistance of an available relational database.

The type of JOIN to be established is determined by setting one of the JoinRowSet constants using the method setJoinType. The following SQL JOIN types can be set:

  • CROSS_JOIN
  • FULL_JOIN
  • INNER_JOIN - the default if no JOIN type has been set
  • LEFT_OUTER_JOIN
  • RIGHT_OUTER_JOIN
Note that if no type is set, the JOIN will automatically be an inner join. The comments for the fields in the JoinRowSet interface explain these JOIN types, which are standard SQL JOIN types.

2.0 Using a JoinRowSet Object for Creating a JOIN

When a JoinRowSet object is created, it is empty. The first RowSet object to be added becomes the basis for the JOIN relationship. Applications must determine which column in each of the RowSet objects to be added to the JoinRowSet object should be the match column. All of the RowSet objects must contain a match column, and the values in each match column must be ones that can be compared to values in the other match columns. The columns do not have to have the same name, though they often do, and they do not have to store the exact same data type as long as the data types can be compared.

A match column can be be set in two ways:

  • By calling the Joinable method setMatchColumn
    This is the only method that can set the match column before a RowSet object is added to a JoinRowSet object. The RowSet object must have implemented the Joinable interface in order to use the method setMatchColumn. Once the match column value has been set, this method can be used to reset the match column at any time.
  • By calling one of the versions of the JoinRowSet method addRowSet that takes a column name or number (or an array of column names or numbers)
    Four of the five addRowSet methods take a match column as a parameter. These four methods set or reset the match column at the time a RowSet object is being added to a JoinRowSet object.

3.0 Sample Usage

The following code fragment adds two CachedRowSet objects to a JoinRowSet object. Note that in this example, no SQL JOIN type is set, so the default JOIN type, which is INNER_JOIN, is established.

In the following code fragment, the table EMPLOYEES, whose match column is set to the first column (EMP_ID), is added to the JoinRowSet object jrs. Then the table ESSP_BONUS_PLAN, whose match column is likewise the EMP_ID column, is added. When this second table is added to jrs, only the rows in ESSP_BONUS_PLAN whose EMP_ID value matches an EMP_ID value in the EMPLOYEES table are added. In this case, everyone in the bonus plan is an employee, so all of the rows in the table ESSP_BONUS_PLAN are added to the JoinRowSet object. In this example, both CachedRowSet objects being added have implemented the Joinable interface and can therefore call the Joinable method setMatchColumn.

     JoinRowSet jrs = new JoinRowSetImpl();

     ResultSet rs1 = stmt.executeQuery("SELECT * FROM EMPLOYEES");
     CachedRowSet empl = new CachedRowSetImpl();
     empl.populate(rs1);
     empl.setMatchColumn(1);
     jrs.addRowSet(empl);

     ResultSet rs2 = stmt.executeQuery("SELECT * FROM ESSP_BONUS_PLAN");
     CachedRowSet bonus = new CachedRowSetImpl();
     bonus.populate(rs2);
     bonus.setMatchColumn(1); // EMP_ID is the first column
     jrs.addRowSet(bonus);

At this point, jrs is an inside JOIN of the two RowSet objects based on their EMP_ID columns. The application can now browse the combined data as if it were browsing one single RowSet object. Because jrs is itself a RowSet object, an application can navigate or modify it using RowSet methods.

     jrs.first();
     int employeeID = jrs.getInt(1);
     String employeeName = jrs.getString(2);

Note that because the SQL JOIN must be enforced when an application adds a second or subsequent RowSet object, there may be an initial degradation in performance while the JOIN is being performed.

The following code fragment adds an additional CachedRowSet object. In this case, the match column (EMP_ID) is set when the CachedRowSet object is added to the JoinRowSet object.

     ResultSet rs3 = stmt.executeQuery("SELECT * FROM 401K_CONTRIB");
     CachedRowSet fourO1k = new CachedRowSetImpl();
     four01k.populate(rs3);
     jrs.addRowSet(four01k, 1);

The JoinRowSet object jrs now contains values from all three tables. The data in each row in four01k in which the value for the EMP_ID column matches a value for the EMP_ID column in jrs has been added to jrs.

4.0 JoinRowSet Methods

The JoinRowSet interface supplies several methods for adding RowSet objects and for getting information about the JoinRowSet object.
  • Methods for adding one or more RowSet objects
    These methods allow an application to add one RowSet object at a time or to add multiple RowSet objects at one time. In either case, the methods may specify the match column for each RowSet object being added.
  • Methods for getting information
    One method retrieves the RowSet objects in the JoinRowSet object, and another method retrieves the RowSet names. A third method retrieves either the SQL WHERE clause used behind the scenes to form the JOIN or a text description of what the WHERE clause does.
  • Methods related to the type of JOIN
    One method sets the JOIN type, and five methods find out whether the JoinRowSet object supports a given type.
  • A method to make a separate copy of the JoinRowSet object
    This method creates a copy that can be persisted to the data source.

Field Summary
static int | CROSS_JOIN An ANSI-style JOIN providing a cross product of two tables
static int | FULL_JOIN An ANSI-style JOIN providing a a full JOIN.
static int | INNER_JOIN An ANSI-style JOIN providing a inner join between two tables.
static int | LEFT_OUTER_JOIN An ANSI-style JOIN providing a left outer join between two tables.
static int | RIGHT_OUTER_JOIN An ANSI-style JOIN providing a right outer join between two tables.
Fields inherited from interface javax.sql.rowset.WebRowSet
PUBLIC_XML_SCHEMA, SCHEMA_SYSTEM_ID
Fields inherited from interface javax.sql.rowset.CachedRowSet
COMMIT_ON_ACCEPT_CHANGES
Fields inherited from interface java.sql.ResultSet
CLOSE_CURSORS_AT_COMMIT, CONCUR_READ_ONLY, CONCUR_UPDATABLE, FETCH_FORWARD, FETCH_REVERSE, FETCH_UNKNOWN, HOLD_CURSORS_OVER_COMMIT, TYPE_FORWARD_ONLY, TYPE_SCROLL_INSENSITIVE, TYPE_SCROLL_SENSITIVE
Method Summary
void | addRowSet(Joinable rowset) Adds the given RowSet object to this JoinRowSet object.
void | addRowSet(RowSet[] rowset, int[] columnIdx) Adds one or more RowSet objects contained in the given array of RowSet objects to this JoinRowSet object and sets the match column for each of the RowSet objects to the match columns in the given array of column indexes.
void | addRowSet(RowSet[] rowset, String[] columnName) Adds one or more RowSet objects contained in the given array of RowSet objects to this JoinRowSet object and sets the match column for each of the RowSet objects to the match columns in the given array of column names.
void | addRowSet(RowSet rowset, int columnIdx) Adds the given RowSet object to this JoinRowSet object and sets the designated column as the match column for the RowSet object.
void | addRowSet(RowSet rowset, String columnName) Adds rowset to this JoinRowSet object and sets the designated column as the match column.
int | getJoinType() Returns a int describing the set SQL JOIN type governing this JoinRowSet instance.
String[] | getRowSetNames() Returns a String array containing the names of the RowSet objects added to this JoinRowSet object.
Collection<?> | getRowSets() Returns a Collection object containing the RowSet objects that have been added to this JoinRowSet object.
String | getWhereClause() Return a SQL-like description of the WHERE clause being used in a JoinRowSet object.
void | setJoinType(int joinType) Allow the application to adjust the type of JOIN imposed on tables contained within the JoinRowSet object instance.
boolean | supportsCrossJoin() Indicates if CROSS_JOIN is supported by a JoinRowSet implementation
boolean | supportsFullJoin() Indicates if FULL_JOIN is supported by a JoinRowSet implementation
boolean | supportsInnerJoin() Indicates if INNER_JOIN is supported by a JoinRowSet implementation
boolean | supportsLeftOuterJoin() Indicates if LEFT_OUTER_JOIN is supported by a JoinRowSet implementation
boolean | supportsRightOuterJoin() Indicates if RIGHT_OUTER_JOIN is supported by a JoinRowSet implementation
CachedRowSet | toCachedRowSet() Creates a new CachedRowSet object containing the data in this JoinRowSet object, which can be saved to a data source using the SyncProvider object for the CachedRowSet object.
Methods inherited from interface javax.sql.rowset.WebRowSet
readXml, readXml, writeXml, writeXml, writeXml, writeXml
Methods inherited from interface javax.sql.rowset.CachedRowSet
acceptChanges, acceptChanges, columnUpdated, columnUpdated, commit, createCopy, createCopyNoConstraints, createCopySchema, createShared, execute, getKeyColumns, getOriginal, getOriginalRow, getPageSize, getRowSetWarnings, getShowDeleted, getSyncProvider, getTableName, nextPage, populate, populate, previousPage, release, restoreOriginal, rollback, rollback, rowSetPopulated, setKeyColumns, setMetaData, setOriginalRow, setPageSize, setShowDeleted, setSyncProvider, setTableName, size, toCollection, toCollection, toCollection, undoDelete, undoInsert, undoUpdate
Methods inherited from interface javax.sql.RowSet
addRowSetListener, clearParameters, execute, getCommand, getDataSourceName, getEscapeProcessing, getMaxFieldSize, getMaxRows, getPassword, getQueryTimeout, getTransactionIsolation, getTypeMap, getUrl, getUsername, isReadOnly, removeRowSetListener, setArray, setAsciiStream, setAsciiStream, setAsciiStream, setAsciiStream, setBigDecimal, setBigDecimal, setBinaryStream, setBinaryStream, setBinaryStream, setBinaryStream, setBlob, setBlob, setBlob, setBlob, setBlob, setBlob, setBoolean, setBoolean, setByte, setByte, setBytes, setBytes, setCharacterStream, setCharacterStream, setCharacterStream, setCharacterStream, setClob, setClob, setClob, setClob, setClob, setClob, setCommand, setConcurrency, setDataSourceName, setDate, setDate, setDate, setDate, setDouble, setDouble, setEscapeProcessing, setFloat, setFloat, setInt, setInt, setLong, setLong, setMaxFieldSize, setMaxRows, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNClob, setNClob, setNClob, setNClob, setNClob, setNClob, setNString, setNString, setNull, setNull, setNull, setNull, setObject, setObject, setObject, setObject, setObject, setObject, setPassword, setQueryTimeout, setReadOnly, setRef, setRowId, setRowId, setShort, setShort, setSQLXML, setSQLXML, setString, setString, setTime, setTime, setTime, setTime, setTimestamp, setTimestamp, setTimestamp, setTimestamp, setTransactionIsolation, setType, setTypeMap, setURL, setUrl, setUsername
Methods inherited from interface java.sql.ResultSet
absolute, afterLast, beforeFirst, cancelRowUpdates, clearWarnings, close, deleteRow, findColumn, first, getArray, getArray, getAsciiStream, getAsciiStream, getBigDecimal, getBigDecimal, getBigDecimal, getBigDecimal, getBinaryStream, getBinaryStream, getBlob, getBlob, getBoolean, getBoolean, getByte, getByte, getBytes, getBytes, getCharacterStream, getCharacterStream, getClob, getClob, getConcurrency, getCursorName, getDate, getDate, getDate, getDate, getDouble, getDouble, getFetchDirection, getFetchSize, getFloat, getFloat, getHoldability, getInt, getInt, getLong, getLong, getMetaData, getNCharacterStream, getNCharacterStream, getNClob, getNClob, getNString, getNString, getObject, getObject, getObject, getObject, getRef, getRef, getRow, getRowId, getRowId, getShort, getShort, getSQLXML, getSQLXML, getStatement, getString, getString, getTime, getTime, getTime, getTime, getTimestamp, getTimestamp, getTimestamp, getTimestamp, getType, getUnicodeStream, getUnicodeStream, getURL, getURL, getWarnings, insertRow, isAfterLast, isBeforeFirst, isClosed, isFirst, isLast, last, moveToCurrentRow, moveToInsertRow, next, previous, refreshRow, relative, rowDeleted, rowInserted, rowUpdated, setFetchDirection, setFetchSize, updateArray, updateArray, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateBigDecimal, updateBigDecimal, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBoolean, updateBoolean, updateByte, updateByte, updateBytes, updateBytes, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateClob, updateClob, updateClob, updateClob, updateClob, updateClob, updateDate, updateDate, updateDouble, updateDouble, updateFloat, updateFloat, updateInt, updateInt, updateLong, updateLong, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNString, updateNString, updateNull, updateNull, updateObject, updateObject, updateObject, updateObject, updateRef, updateRef, updateRow, updateRowId, updateRowId, updateShort, updateShort, updateSQLXML, updateSQLXML, updateString, updateString, updateTime, updateTime, updateTimestamp, updateTimestamp, wasNull
Methods inherited from interface java.sql.Wrapper
isWrapperFor, unwrap
Methods inherited from interface javax.sql.rowset.Joinable
getMatchColumnIndexes, getMatchColumnNames, setMatchColumn, setMatchColumn, setMatchColumn, setMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn

Field Detail

CROSS_JOIN

static final int CROSS_JOIN
An ANSI-style JOIN providing a cross product of two tables

See Also:
Constant Field Values

INNER_JOIN

static final int INNER_JOIN
An ANSI-style JOIN providing a inner join between two tables. Any unmatched rows in either table of the join should be discarded.

See Also:
Constant Field Values

LEFT_OUTER_JOIN

static final int LEFT_OUTER_JOIN
An ANSI-style JOIN providing a left outer join between two tables. In SQL, this is described where all records should be returned from the left side of the JOIN statement.

See Also:
Constant Field Values

RIGHT_OUTER_JOIN

static final int RIGHT_OUTER_JOIN
An ANSI-style JOIN providing a right outer join between two tables. In SQL, this is described where all records from the table on the right side of the JOIN statement even if the table on the left has no matching record.

See Also:
Constant Field Values

FULL_JOIN

static final int FULL_JOIN
An ANSI-style JOIN providing a a full JOIN. Specifies that all rows from either table be returned regardless of matching records on the other table.

See Also:
Constant Field Values
Method Detail

addRowSet

void addRowSet(Joinable rowset)
               throws SQLException
Adds the given RowSet object to this JoinRowSet object. If the RowSet object is the first to be added to this JoinRowSet object, it forms the basis of the JOIN relationship to be established.

This method should be used only when the given RowSet object already has a match column that was set with the Joinable method setMatchColumn.

Note: A Joinable object is any RowSet object that has implemented the Joinable interface.

Parameters:
rowset - the RowSet object that is to be added to this JoinRowSet object; it must implement the Joinable interface and have a match column set
Throws:
SQLException - if (1) an empty rowset is added to the to this JoinRowSet object, (2) a match column has not been set for rowset, or (3) rowset violates the active JOIN
See Also:
Joinable.setMatchColumn(int)

addRowSet

void addRowSet(RowSet rowset,
               int columnIdx)
               throws SQLException
Adds the given RowSet object to this JoinRowSet object and sets the designated column as the match column for the RowSet object. If the RowSet object is the first to be added to this JoinRowSet object, it forms the basis of the JOIN relationship to be established.

This method should be used when RowSet does not already have a match column set.

Parameters:
rowset - the RowSet object that is to be added to this JoinRowSet object; it may implement the Joinable interface
columnIdx - an int that identifies the column to become the match column
Throws:
SQLException - if (1) rowset is an empty rowset or (2) rowset violates the active JOIN
See Also:
Joinable.unsetMatchColumn(int)

addRowSet

void addRowSet(RowSet rowset,
               String columnName)
               throws SQLException
Adds rowset to this JoinRowSet object and sets the designated column as the match column. If rowset is the first to be added to this JoinRowSet object, it forms the basis for the JOIN relationship to be established.

This method should be used when the given RowSet object does not already have a match column.

Parameters:
rowset - the RowSet object that is to be added to this JoinRowSet object; it may implement the Joinable interface
columnName - the String object giving the name of the column to be set as the match column
Throws:
SQLException - if (1) rowset is an empty rowset or (2) the match column for rowset does not satisfy the conditions of the JOIN

addRowSet

void addRowSet(RowSet[] rowset,
               int[] columnIdx)
               throws SQLException
Adds one or more RowSet objects contained in the given array of RowSet objects to this JoinRowSet object and sets the match column for each of the RowSet objects to the match columns in the given array of column indexes. The first element in columnIdx is set as the match column for the first RowSet object in rowset, the second element of columnIdx is set as the match column for the second element in rowset, and so on.

The first RowSet object added to this JoinRowSet object forms the basis for the JOIN relationship.

This method should be used when the given RowSet object does not already have a match column.

Parameters:
rowset - an array of one or more RowSet objects to be added to the JOIN; it may implement the Joinable interface
columnIdx - an array of int values indicating the index(es) of the columns to be set as the match columns for the RowSet objects in rowset
Throws:
SQLException - if (1) an empty rowset is added to this JoinRowSet object, (2) a match column is not set for a RowSet object in rowset, or (3) a RowSet object being added violates the active JOIN

addRowSet

void addRowSet(RowSet[] rowset,
               String[] columnName)
               throws SQLException
Adds one or more RowSet objects contained in the given array of RowSet objects to this JoinRowSet object and sets the match column for each of the RowSet objects to the match columns in the given array of column names. The first element in columnName is set as the match column for the first RowSet object in rowset, the second element of columnName is set as the match column for the second element in rowset, and so on.

The first RowSet object added to this JoinRowSet object forms the basis for the JOIN relationship.

This method should be used when the given RowSet object(s) does not already have a match column.

Parameters:
rowset - an array of one or more RowSet objects to be added to the JOIN; it may implement the Joinable interface
columnName - an array of String values indicating the names of the columns to be set as the match columns for the RowSet objects in rowset
Throws:
SQLException - if (1) an empty rowset is added to this JoinRowSet object, (2) a match column is not set for a RowSet object in rowset, or (3) a RowSet object being added violates the active JOIN

getRowSets

Collection<?> getRowSets()
                         throws SQLException
Returns a Collection object containing the RowSet objects that have been added to this JoinRowSet object. This should return the 'n' number of RowSet contained within the JOIN and maintain any updates that have occured while in this union.

Returns:
a Collection object consisting of the RowSet objects added to this JoinRowSet object
Throws:
SQLException - if an error occurs generating the Collection object to be returned

getRowSetNames

String[] getRowSetNames()
                        throws SQLException
Returns a String array containing the names of the RowSet objects added to this JoinRowSet object.

Returns:
a String array of the names of the RowSet objects in this JoinRowSet object
Throws:
SQLException - if an error occurs retrieving the names of the RowSet objects
See Also:
CachedRowSet.setTableName(java.lang.String)

toCachedRowSet

CachedRowSet toCachedRowSet()
                            throws SQLException
Creates a new CachedRowSet object containing the data in this JoinRowSet object, which can be saved to a data source using the SyncProvider object for the CachedRowSet object.

If any updates or modifications have been applied to the JoinRowSet the CachedRowSet returned by the method will not be able to persist it's changes back to the originating rows and tables in the in the datasource. The CachedRowSet instance returned should not contain modification data and it should clear all properties of it's originating SQL statement. An application should reset the SQL statement using the RowSet.setCommand method.

In order to allow changes to be persisted back to the datasource to the originating tables, the acceptChanges method should be used and called on a JoinRowSet object instance. Implementations can leverage the internal data and update tracking in their implementations to interact with the SyncProvider to persist any changes.

Returns:
a CachedRowSet containing the contents of the JoinRowSet
Throws:
SQLException - if an error occurs assembling the CachedRowSet object
See Also:
RowSet, CachedRowSet, SyncProvider

supportsCrossJoin

boolean supportsCrossJoin()
Indicates if CROSS_JOIN is supported by a JoinRowSet implementation

Returns:
true if the CROSS_JOIN is supported; false otherwise

supportsInnerJoin

boolean supportsInnerJoin()
Indicates if INNER_JOIN is supported by a JoinRowSet implementation

Returns:
true is the INNER_JOIN is supported; false otherwise

supportsLeftOuterJoin

boolean supportsLeftOuterJoin()
Indicates if LEFT_OUTER_JOIN is supported by a JoinRowSet implementation

Returns:
true is the LEFT_OUTER_JOIN is supported; false otherwise

supportsRightOuterJoin

boolean supportsRightOuterJoin()
Indicates if RIGHT_OUTER_JOIN is supported by a JoinRowSet implementation

Returns:
true is the RIGHT_OUTER_JOIN is supported; false otherwise

supportsFullJoin

boolean supportsFullJoin()
Indicates if FULL_JOIN is supported by a JoinRowSet implementation

Returns:
true is the FULL_JOIN is supported; false otherwise

setJoinType

void setJoinType(int joinType)
                 throws SQLException
Allow the application to adjust the type of JOIN imposed on tables contained within the JoinRowSet object instance. Implementations should throw a SQLException if they do not support a given JOIN type.

Parameters:
joinType - the standard JoinRowSet.XXX static field definition of a SQL JOIN to re-configure a JoinRowSet instance on the fly.
Throws:
SQLException - if an unsupported JOIN type is set
See Also:
getJoinType()

getWhereClause

String getWhereClause()
                      throws SQLException
Return a SQL-like description of the WHERE clause being used in a JoinRowSet object. An implementation can describe the WHERE clause of the SQL JOIN by supplying a SQL strings description of JOIN or provide a textual description to assist applications using a JoinRowSet

Returns:
whereClause a textual or SQL description of the logical WHERE clause used in the JoinRowSet instance
Throws:
SQLException - if an error occurs in generating a representation of the WHERE clause.

getJoinType

int getJoinType()
                throws SQLException
Returns a int describing the set SQL JOIN type governing this JoinRowSet instance. The returned type will be one of standard JoinRowSet types: CROSS_JOIN, INNER_JOIN, LEFT_OUTER_JOIN, RIGHT_OUTER_JOIN or FULL_JOIN.

Returns:
joinType one of the standard JoinRowSet static field definitions of a SQL JOIN. JoinRowSet.INNER_JOIN is returned as the default JOIN type is no type has been explicitly set.
Throws:
SQLException - if an error occurs determining the SQL JOIN type supported by the JoinRowSet instance.
See Also:
setJoinType(int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Predicate

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset
Interface Predicate

public interface Predicate

The standard interface that provides the framework for all FilteredRowSet objects to describe their filters.

1.0 Background

The Predicate interface is a standard interface that applications can implement to define the filter they wish to apply to a a FilteredRowSet object. A FilteredRowSet object consumes implementations of this interface and enforces the constraints defined in the implementation of the method evaluate. A FilteredRowSet object enforces the filter constraints in a bi-directional manner: It outputs only rows that are within the constraints of the filter; and conversely, it inserts, modifies, or updates only rows that are within the constraints of the filter.

2.0 Implementation Guidelines

In order to supply a predicate for the FilteredRowSet. this interface must be implemented. At this time, the JDBC RowSet Implementations (JSR-114) does not specify any standard filters definitions. By specifying a standard means and mechanism for a range of filters to be defined and deployed with both the reference and vendor implementations of the FilteredRowSet interface, this allows for a flexible and application motivated implementations of Predicate to emerge.

A sample implementation would look something like this:

    public class Range implements Predicate {

       private Object lo[];
       private Object hi[];
       private int idx[];

       public Range(Object[] lo, Object[] hi, int[] idx) {
          this.lo = lo;
          this.hi = hi;
          this.idx = idx;
       }

      public boolean evaluate(RowSet rs) {
          CachedRowSet crs = (CachedRowSet)rs;
          boolean bool1,bool2;

          // Check the present row determine if it lies
          // within the filtering criteria.

          for (int i = 0; i < idx.length; i++) {

                if ((rs.getObject(idx[i]) >= lo[i]) &&
                  (rs.getObject(idx[i]) >= hi[i]) {
                    bool1 = true; // within filter constraints
          } else {
            bool2 = true; // outside of filter constraints
          }
      }

      if (bool2) {
         return false;
      } else {
         return true;
      }
  }

The example above implements a simple range predicate. Note, that implementations should but are not required to provider String and integer index based constructors to provide for JDBC RowSet Implementation applications that use both column identification conventions.

Method Summary
 boolean evaluate(Object value, int column)
This method is called by a FilteredRowSet object to check whether the value lies between the filtering criterion (or criteria if multiple constraints exist) set using the setFilter() method.
 boolean evaluate(Object value, String columnName)
This method is called by the FilteredRowSet object to check whether the value lies between the filtering criteria set using the setFilter method.
 boolean evaluate(RowSet rs)
This method is typically called a FilteredRowSet object internal methods (not public) that control the RowSet object's cursor moving from row to the next.

Method Detail

evaluate

boolean evaluate(RowSet rs)
This method is typically called a FilteredRowSet object internal methods (not public) that control the RowSet object's cursor moving from row to the next. In addition, if this internal method moves the cursor onto a row that has been deleted, the internal method will continue to ove the cursor until a valid row is found.

Returns:
true if there are more rows in the filter; false otherwise

evaluate

boolean evaluate(Object value,
                 int column)
                 throws SQLException
This method is called by a FilteredRowSet object to check whether the value lies between the filtering criterion (or criteria if multiple constraints exist) set using the setFilter() method.

The FilteredRowSet object will use this method internally while inserting new rows to a FilteredRowSet instance.

Parameters:
value - An Object value which needs to be checked, whether it can be part of this FilterRowSet object.
column - a int object that must match the SQL index of a column in this RowSet object. This must have been passed to Predicate as one of the columns for filtering while initializing a Predicate
Returns:
true ifrow value lies within the filter; false otherwise
Throws:
SQLException - if the column is not part of filtering criteria

evaluate

boolean evaluate(Object value,
                 String columnName)
                 throws SQLException
This method is called by the FilteredRowSet object to check whether the value lies between the filtering criteria set using the setFilter method.

The FilteredRowSet object will use this method internally while inserting new rows to a FilteredRowSet instance.

Parameters:
value - An Object value which needs to be checked, whether it can be part of this FilterRowSet.
columnName - a String object that must match the SQL name of a column in this RowSet, ignoring case. This must have been passed to Predicate as one of the columns for filtering while initializing a Predicate
Returns:
true if value lies within the filter; false otherwise
Throws:
SQLException - if the column is not part of filtering criteria
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RowSetMetaDataImpl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset
Class RowSetMetaDataImpl

java.lang.Object
    extended by  javax.sql.rowset.RowSetMetaDataImpl
All Implemented Interfaces:
Serializable, ResultSetMetaData, Wrapper, RowSetMetaData
public class RowSetMetaDataImpl
extends Object
implements RowSetMetaData, Serializable

Provides implementations for the methods that set and get metadata information about a RowSet object's columns. A RowSetMetaDataImpl object keeps track of the number of columns in the rowset and maintains an internal array of column attributes for each column.

A RowSet object creates a RowSetMetaDataImpl object internally in order to set and retrieve information about its columns.

NOTE: All metadata in a RowSetMetaDataImpl object should be considered as unavailable until the RowSet object that it describes is populated. Therefore, any RowSetMetaDataImpl method that retrieves information is defined as having unspecified behavior when it is called before the RowSet object contains data.

See Also:
Serialized Form

Field Summary
Fields inherited from interface java.sql.ResultSetMetaData
columnNoNulls, columnNullable, columnNullableUnknown
Constructor Summary
RowSetMetaDataImpl()
Method Summary
 String getCatalogName(int columnIndex)
Retrieves the catalog name of the table from which the value in the designated column was derived.
 String getColumnClassName(int columnIndex)
Retrieves the fully-qualified name of the class in the Java programming language to which a value in the designated column will be mapped.
 int getColumnCount()
Retrieves the number of columns in the RowSet object for which this RowSetMetaDataImpl object was created.
 int getColumnDisplaySize(int columnIndex)
Retrieves the normal maximum width in chars of the designated column.
 String getColumnLabel(int columnIndex)
Retrieves the the suggested column title for the designated column for use in printouts and displays.
 String getColumnName(int columnIndex)
Retrieves the name of the designated column.
 int getColumnType(int columnIndex)
Retrieves the type code (one of the java.sql.Types constants) for the SQL type of the value stored in the designated column.
 String getColumnTypeName(int columnIndex)
Retrieves the DBMS-specific type name for values stored in the designated column.
 int getPrecision(int columnIndex)
Retrieves the total number of digits for values stored in the designated column.
 int getScale(int columnIndex)
Retrieves the number of digits to the right of the decimal point for values stored in the designated column.
 String getSchemaName(int columnIndex)
Retrieves the schema name of the table from which the value in the designated column was derived.
 String getTableName(int columnIndex)
Retrieves the name of the table from which the value in the designated column was derived.
 boolean isAutoIncrement(int columnIndex)
Retrieves whether a value stored in the designated column is automatically numbered, and thus readonly.
 boolean isCaseSensitive(int columnIndex)
Indicates whether the case of the designated column's name matters.
 boolean isCurrency(int columnIndex)
Indicates whether a value stored in the designated column is a cash value.
 boolean isDefinitelyWritable(int columnIndex)
Indicates whether a write operation on the designated column will definitely succeed.
 int isNullable(int columnIndex)
Retrieves a constant indicating whether it is possible to store a NULL value in the designated column.
 boolean isReadOnly(int columnIndex)
Indicates whether the designated column is definitely not writable, thus readonly.
 boolean isSearchable(int columnIndex)
Indicates whether a value stored in the designated column can be used in a WHERE clause.
 boolean isSigned(int columnIndex)
Indicates whether a value stored in the designated column is a signed number.
 boolean isWrapperFor(Class<?> interfaces)
Returns true if this either implements the interface argument or is directly or indirectly a wrapper for an object that does.
 boolean isWritable(int columnIndex)
Indicates whether it is possible for a write operation on the designated column to succeed.
 void setAutoIncrement(int columnIndex, boolean property)
Sets whether the designated column is automatically numbered, thus read-only, to the given boolean value.
 void setCaseSensitive(int columnIndex, boolean property)
Sets whether the name of the designated column is case sensitive to the given boolean.
 void setCatalogName(int columnIndex, String catalogName)
Sets the catalog name of the table from which the designated column was derived to catalogName.
 void setColumnCount(int columnCount)
Sets to the given number the number of columns in the RowSet object for which this RowSetMetaDataImpl object was created.
 void setColumnDisplaySize(int columnIndex, int size)
Sets the normal maximum number of chars in the designated column to the given number.
 void setColumnLabel(int columnIndex, String label)
Sets the suggested column label for use in printouts and displays, if any, to label.
 void setColumnName(int columnIndex, String columnName)
Sets the column name of the designated column to the given name.
 void setColumnType(int columnIndex, int SQLType)
Sets the SQL type code for values stored in the designated column to the given type code from the class java.sql.Types.
 void setColumnTypeName(int columnIndex, String typeName)
Sets the type name used by the data source for values stored in the designated column to the given type name.
 void setCurrency(int columnIndex, boolean property)
Sets whether a value stored in the designated column is a cash value to the given boolean.
 void setNullable(int columnIndex, int property)
Sets whether a value stored in the designated column can be set to NULL to the given constant from the interface ResultSetMetaData.
 void setPrecision(int columnIndex, int precision)
Sets the total number of decimal digits in a value stored in the designated column to the given number.
 void setScale(int columnIndex, int scale)
Sets the number of digits to the right of the decimal point in a value stored in the designated column to the given number.
 void setSchemaName(int columnIndex, String schemaName)
Sets the designated column's table's schema name, if any, to schemaName.
 void setSearchable(int columnIndex, boolean property)
Sets whether a value stored in the designated column can be used in a WHERE clause to the given boolean value.
 void setSigned(int columnIndex, boolean property)
Sets whether a value stored in the designated column is a signed number to the given boolean.
 void setTableName(int columnIndex, String tableName)
Sets the name of the table from which the designated column was derived to the given table name.
<T> T
unwrap(Class<T> iface)
Returns an object that implements the given interface to allow access to non-standard methods, or standard methods not exposed by the proxy.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RowSetMetaDataImpl

public RowSetMetaDataImpl()
Method Detail

setColumnCount

public void setColumnCount(int columnCount)
                    throws SQLException
Sets to the given number the number of columns in the RowSet object for which this RowSetMetaDataImpl object was created.

Specified by:
setColumnCount in interface RowSetMetaData
Parameters:
columnCount - an int giving the number of columns in the RowSet object
Throws:
SQLException - if the given number is equal to or less than zero

setAutoIncrement

public void setAutoIncrement(int columnIndex,
                             boolean property)
                      throws SQLException
Sets whether the designated column is automatically numbered, thus read-only, to the given boolean value.

Specified by:
setAutoIncrement in interface RowSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns in the rowset, inclusive
property - true if the given column is automatically incremented; false otherwise
Throws:
SQLException - if a database access error occurs or the given index is out of bounds
SQLException - if a database access error occurs

setCaseSensitive

public void setCaseSensitive(int columnIndex,
                             boolean property)
                      throws SQLException
Sets whether the name of the designated column is case sensitive to the given boolean.

Specified by:
setCaseSensitive in interface RowSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns in the rowset, inclusive
property - true to indicate that the column name is case sensitive; false otherwise
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

setSearchable

public void setSearchable(int columnIndex,
                          boolean property)
                   throws SQLException
Sets whether a value stored in the designated column can be used in a WHERE clause to the given boolean value.

Specified by:
setSearchable in interface RowSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns in the rowset, inclusive
property - true to indicate that a column value can be used in a WHERE clause; false otherwise
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds
SQLException - if a database access error occurs

setCurrency

public void setCurrency(int columnIndex,
                        boolean property)
                 throws SQLException
Sets whether a value stored in the designated column is a cash value to the given boolean.

Specified by:
setCurrency in interface RowSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive between 1 and the number of columns, inclusive
property - true if the value is a cash value; false otherwise.
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds
SQLException - if a database access error occurs

setNullable

public void setNullable(int columnIndex,
                        int property)
                 throws SQLException
Sets whether a value stored in the designated column can be set to NULL to the given constant from the interface ResultSetMetaData.

Specified by:
setNullable in interface RowSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
property - one of the following ResultSetMetaData constants: columnNoNulls, columnNullable, or columnNullableUnknown
Throws:
SQLException - if a database access error occurs, the given column number is out of bounds, or the value supplied for the property parameter is not one of the following constants: ResultSetMetaData.columnNoNulls, ResultSetMetaData.columnNullable, or ResultSetMetaData.columnNullableUnknown
SQLException - if a database access error occurs

setSigned

public void setSigned(int columnIndex,
                      boolean property)
               throws SQLException
Sets whether a value stored in the designated column is a signed number to the given boolean.

Specified by:
setSigned in interface RowSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
property - true to indicate that a column value is a signed number; false to indicate that it is not
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

setColumnDisplaySize

public void setColumnDisplaySize(int columnIndex,
                                 int size)
                          throws SQLException
Sets the normal maximum number of chars in the designated column to the given number.

Specified by:
setColumnDisplaySize in interface RowSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
size - the maximum size of the column in chars; must be 0 or more
Throws:
SQLException - if a database access error occurs, the given column number is out of bounds, or size is less than 0

setColumnLabel

public void setColumnLabel(int columnIndex,
                           String label)
                    throws SQLException
Sets the suggested column label for use in printouts and displays, if any, to label. If label is null, the column label is set to an empty string ("").

Specified by:
setColumnLabel in interface RowSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
label - the column label to be used in printouts and displays; if the column label is null, an empty String is set
Throws:
SQLException - if a database access error occurs or the given column index is out of bounds

setColumnName

public void setColumnName(int columnIndex,
                          String columnName)
                   throws SQLException
Sets the column name of the designated column to the given name.

Specified by:
setColumnName in interface RowSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
columnName - a String object indicating the column name; if the given name is null, an empty String is set
Throws:
SQLException - if a database access error occurs or the given column index is out of bounds

setSchemaName

public void setSchemaName(int columnIndex,
                          String schemaName)
                   throws SQLException
Sets the designated column's table's schema name, if any, to schemaName. If schemaName is null, the schema name is set to an empty string ("").

Specified by:
setSchemaName in interface RowSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
schemaName - the schema name for the table from which a value in the designated column was derived; may be an empty String or null
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

setPrecision

public void setPrecision(int columnIndex,
                         int precision)
                  throws SQLException
Sets the total number of decimal digits in a value stored in the designated column to the given number.

Specified by:
setPrecision in interface RowSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
precision - the total number of decimal digits; must be 0 or more
Throws:
SQLException - if a database access error occurs, columnIndex is out of bounds, or precision is less than 0

setScale

public void setScale(int columnIndex,
                     int scale)
              throws SQLException
Sets the number of digits to the right of the decimal point in a value stored in the designated column to the given number.

Specified by:
setScale in interface RowSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
scale - the number of digits to the right of the decimal point; must be zero or greater
Throws:
SQLException - if a database access error occurs, columnIndex is out of bounds, or scale is less than 0

setTableName

public void setTableName(int columnIndex,
                         String tableName)
                  throws SQLException
Sets the name of the table from which the designated column was derived to the given table name.

Specified by:
setTableName in interface RowSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
tableName - the column's table name; may be null or an empty string
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

setCatalogName

public void setCatalogName(int columnIndex,
                           String catalogName)
                    throws SQLException
Sets the catalog name of the table from which the designated column was derived to catalogName. If catalogName is null, the catalog name is set to an empty string.

Specified by:
setCatalogName in interface RowSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
catalogName - the column's table's catalog name; if the catalogName is null, an empty String is set
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

setColumnType

public void setColumnType(int columnIndex,
                          int SQLType)
                   throws SQLException
Sets the SQL type code for values stored in the designated column to the given type code from the class java.sql.Types.

Specified by:
setColumnType in interface RowSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
SQLType - the designated column's SQL type, which must be one of the constants in the class java.sql.Types
Throws:
SQLException - if a database access error occurs, the given column number is out of bounds, or the column type specified is not one of the constants in java.sql.Types
See Also:
Types

setColumnTypeName

public void setColumnTypeName(int columnIndex,
                              String typeName)
                       throws SQLException
Sets the type name used by the data source for values stored in the designated column to the given type name.

Specified by:
setColumnTypeName in interface RowSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
typeName - the data source-specific type name; if typeName is null, an empty String is set
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

getColumnCount

public int getColumnCount()
                   throws SQLException
Retrieves the number of columns in the RowSet object for which this RowSetMetaDataImpl object was created.

Specified by:
getColumnCount in interface ResultSetMetaData
Returns:
the number of columns
Throws:
SQLException - if an error occurs determining the column count

isAutoIncrement

public boolean isAutoIncrement(int columnIndex)
                        throws SQLException
Retrieves whether a value stored in the designated column is automatically numbered, and thus readonly.

Specified by:
isAutoIncrement in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
true if the column is automatically numbered; false otherwise
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

isCaseSensitive

public boolean isCaseSensitive(int columnIndex)
                        throws SQLException
Indicates whether the case of the designated column's name matters.

Specified by:
isCaseSensitive in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
true if the column name is case sensitive; false otherwise
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

isSearchable

public boolean isSearchable(int columnIndex)
                     throws SQLException
Indicates whether a value stored in the designated column can be used in a WHERE clause.

Specified by:
isSearchable in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
true if a value in the designated column can be used in a WHERE clause; false otherwise
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

isCurrency

public boolean isCurrency(int columnIndex)
                   throws SQLException
Indicates whether a value stored in the designated column is a cash value.

Specified by:
isCurrency in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
true if a value in the designated column is a cash value; false otherwise
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

isNullable

public int isNullable(int columnIndex)
               throws SQLException
Retrieves a constant indicating whether it is possible to store a NULL value in the designated column.

Specified by:
isNullable in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
a constant from the ResultSetMetaData interface; either columnNoNulls, columnNullable, or columnNullableUnknown
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

isSigned

public boolean isSigned(int columnIndex)
                 throws SQLException
Indicates whether a value stored in the designated column is a signed number.

Specified by:
isSigned in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
true if if a value in the designated column is a signed number; false otherwise
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

getColumnDisplaySize

public int getColumnDisplaySize(int columnIndex)
                         throws SQLException
Retrieves the normal maximum width in chars of the designated column.

Specified by:
getColumnDisplaySize in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
the maximum number of chars that can be displayed in the designated column
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

getColumnLabel

public String getColumnLabel(int columnIndex)
                      throws SQLException
Retrieves the the suggested column title for the designated column for use in printouts and displays.

Specified by:
getColumnLabel in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
the suggested column name to use in printouts and displays
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

getColumnName

public String getColumnName(int columnIndex)
                     throws SQLException
Retrieves the name of the designated column.

Specified by:
getColumnName in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
the column name of the designated column
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

getSchemaName

public String getSchemaName(int columnIndex)
                     throws SQLException
Retrieves the schema name of the table from which the value in the designated column was derived.

Specified by:
getSchemaName in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
the schema name or an empty String if no schema name is available
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

getPrecision

public int getPrecision(int columnIndex)
                 throws SQLException
Retrieves the total number of digits for values stored in the designated column.

Specified by:
getPrecision in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
the precision for values stored in the designated column
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

getScale

public int getScale(int columnIndex)
             throws SQLException
Retrieves the number of digits to the right of the decimal point for values stored in the designated column.

Specified by:
getScale in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
the scale for values stored in the designated column
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

getTableName

public String getTableName(int columnIndex)
                    throws SQLException
Retrieves the name of the table from which the value in the designated column was derived.

Specified by:
getTableName in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
the table name or an empty String if no table name is available
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

getCatalogName

public String getCatalogName(int columnIndex)
                      throws SQLException
Retrieves the catalog name of the table from which the value in the designated column was derived.

Specified by:
getCatalogName in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
the catalog name of the column's table or an empty String if no catalog name is available
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

getColumnType

public int getColumnType(int columnIndex)
                  throws SQLException
Retrieves the type code (one of the java.sql.Types constants) for the SQL type of the value stored in the designated column.

Specified by:
getColumnType in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
an int representing the SQL type of values stored in the designated column
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds
See Also:
Types

getColumnTypeName

public String getColumnTypeName(int columnIndex)
                         throws SQLException
Retrieves the DBMS-specific type name for values stored in the designated column.

Specified by:
getColumnTypeName in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
the type name used by the data source
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

isReadOnly

public boolean isReadOnly(int columnIndex)
                   throws SQLException
Indicates whether the designated column is definitely not writable, thus readonly.

Specified by:
isReadOnly in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
true if this RowSet object is read-Only and thus not updatable; false otherwise
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

isWritable

public boolean isWritable(int columnIndex)
                   throws SQLException
Indicates whether it is possible for a write operation on the designated column to succeed. A return value of true means that a write operation may or may not succeed.

Specified by:
isWritable in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
true if a write operation on the designated column may will succeed; false otherwise
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

isDefinitelyWritable

public boolean isDefinitelyWritable(int columnIndex)
                             throws SQLException
Indicates whether a write operation on the designated column will definitely succeed.

Specified by:
isDefinitelyWritable in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
true if a write operation on the designated column will definitely succeed; false otherwise
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

getColumnClassName

public String getColumnClassName(int columnIndex)
                          throws SQLException
Retrieves the fully-qualified name of the class in the Java programming language to which a value in the designated column will be mapped. For example, if the value is an int, the class name returned by this method will be java.lang.Integer.

If the value in the designated column has a custom mapping, this method returns the name of the class that implements SQLData. When the method ResultSet.getObject is called to retrieve a value from the designated column, it will create an instance of this class or one of its subclasses.

Specified by:
getColumnClassName in interface ResultSetMetaData
Parameters:
columnIndex - the first column is 1, the second is 2, and so on; must be between 1 and the number of columns, inclusive
Returns:
the fully-qualified name of the class in the Java programming language that would be used by the method RowSet.getObject to retrieve the value in the specified column. This is the class name used for custom mapping when there is a custom mapping.
Throws:
SQLException - if a database access error occurs or the given column number is out of bounds

unwrap

public <T> T unwrap(Class<T> iface)
         throws SQLException
Returns an object that implements the given interface to allow access to non-standard methods, or standard methods not exposed by the proxy. The result may be either the object found to implement the interface or a proxy for that object. If the receiver implements the interface then that is the object. If the receiver is a wrapper and the wrapped object implements the interface then that is the object. Otherwise the object is the result of calling unwrap recursively on the wrapped object. If the receiver is not a wrapper and does not implement the interface, then an SQLException is thrown.

Specified by:
unwrap in interface Wrapper
Parameters:
iface - A Class defining an interface that the result must implement.
Returns:
an object that implements the interface. May be a proxy for the actual implementing object.
Throws:
SQLException - If no object found that implements the interface
Since:
1.6

isWrapperFor

public boolean isWrapperFor(Class<?> interfaces)
                     throws SQLException
Returns true if this either implements the interface argument or is directly or indirectly a wrapper for an object that does. Returns false otherwise. If this implements the interface then return true, else if this is a wrapper then return the result of recursively calling isWrapperFor on the wrapped object. If this does not implement the interface and is not a wrapper, return false. This method should be implemented as a low-cost operation compared to unwrap so that callers can use this method to avoid expensive unwrap calls that may fail. If this method returns true then calling unwrap with the same argument should succeed.

Specified by:
isWrapperFor in interface Wrapper
Parameters:
interfaces - a Class defining an interface.
Returns:
true if this implements the interface or directly or indirectly wraps an object that does.
Throws:
SQLException - if an error occurs while determining whether this is a wrapper for an object with the given interface.
Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RowSetWarning

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset
Class RowSetWarning

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.sql.SQLException
                extended by  javax.sql.rowset.RowSetWarning
All Implemented Interfaces:
Serializable, Iterable<Throwable>
public class RowSetWarning
extends SQLException

An extension of SQLException that provides information about database warnings set on RowSet objects. Warnings are silently chained to the object whose method call caused it to be reported. This class complements the SQLWarning class.

Rowset warnings may be retrieved from JdbcRowSet, CachedRowSetTM, WebRowSet, FilteredRowSet, or JoinRowSet implementations. To retrieve the first warning reported on any RowSet implementation, use the method getRowSetWarnings defined in the JdbcRowSet interface or the CachedRowSet interface. To retrieve a warning chained to the first warning, use the RowSetWarning method getNextWarning. To retrieve subsequent warnings, call getNextWarning on each RowSetWarning object that is returned.

The inherited methods getMessage, getSQLState, and getErrorCode retrieve information contained in a RowSetWarning object.

See Also:
Serialized Form

Constructor Summary
RowSetWarning()
Constructs a default RowSetWarning object.
RowSetWarning(String reason)
Constructs a RowSetWarning object with the given value for the reason; SQLState defaults to null, and vendorCode defaults to 0.
RowSetWarning(String reason, String SQLState)
Constructs a RowSetWarning object initialized with the given values for the reason and SQLState.
RowSetWarning(String reason, String SQLState, int vendorCode)
Constructs a fully specified RowSetWarning object initialized with the given values for the reason, SQLState and vendorCode.
Method Summary
RowSetWarning | getNextWarning() Retrieves the warning chained to this RowSetWarning object.
void | setNextWarning(RowSetWarning warning) Sets warning as the next warning, that is, the warning chained to this RowSetWarning object.
Methods inherited from class java.sql.SQLException
getErrorCode, getNextException, getSQLState, iterator, setNextException
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RowSetWarning

public RowSetWarning(String reason)
Constructs a RowSetWarning object with the given value for the reason; SQLState defaults to null, and vendorCode defaults to 0.

Parameters:
reason - a String object giving a description of the warning; if the String is null, this constructor behaves like the default (zero parameter) RowSetWarning constructor

RowSetWarning

public RowSetWarning()
Constructs a default RowSetWarning object. The reason defaults to null, SQLState defaults to null and vendorCode defaults to 0.

RowSetWarning

public RowSetWarning(String reason,
                     String SQLState)
Constructs a RowSetWarning object initialized with the given values for the reason and SQLState. The vendor code defaults to 0. If the reason or SQLState parameters are null, this constructor behaves like the default (zero parameter) RowSetWarning constructor.

Parameters:
reason - a String giving a description of the warning;
SQLState - an XOPEN code identifying the warning; if a non standard XOPEN SQLState is supplied, no exception is thrown.

RowSetWarning

public RowSetWarning(String reason,
                     String SQLState,
                     int vendorCode)
Constructs a fully specified RowSetWarning object initialized with the given values for the reason, SQLState and vendorCode. If the reason, or the SQLState parameters are null, this constructor behaves like the default (zero parameter) RowSetWarning constructor.

Parameters:
reason - a String giving a description of the warning;
SQLState - an XOPEN code identifying the warning; if a non standard XPOEN SQLState is supplied, no exception is thrown.
vendorCode - a database vendor-specific warning code
Method Detail

getNextWarning

public RowSetWarning getNextWarning()
Retrieves the warning chained to this RowSetWarning object.

Returns:
the RowSetWarning object chained to this one; if no RowSetWarning object is chained to this one, null is returned (default value)
See Also:
setNextWarning(javax.sql.rowset.RowSetWarning)

setNextWarning

public void setNextWarning(RowSetWarning warning)
Sets warning as the next warning, that is, the warning chained to this RowSetWarning object.

Parameters:
warning - the RowSetWarning object to be set as the next warning; if the RowSetWarning is null, this represents the finish point in the warning chain
See Also:
getNextWarning()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


serial

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.sql.rowset.serial

Provides utility classes to allow serializable mappings between SQL types and data types in the Java programming language.

See:
Description

Class Summary
SerialArray | A serialized version of an Array object, which is the mapping in the Java programming language of an SQL ARRAY value.
SerialBlob | A serialized mapping in the Java programming language of an SQL BLOB value.
SerialClob | A serialized mapping in the Java programming language of an SQL CLOB value.
SerialDatalink | A serialized mapping in the Java programming language of an SQL DATALINK value.
SerialJavaObject | A serializable mapping in the Java programming language of an SQL JAVA_OBJECT value.
SerialRef | A serialized mapping of a Ref object, which is the mapping in the Java programming language of an SQL REF value.
SerialStruct | A serialized mapping in the Java programming language of an SQL structured type.
SQLInputImpl | An input stream used for custom mapping user-defined types (UDTs).
SQLOutputImpl | The output stream for writing the attributes of a custom-mapped user-defined type (UDT) back to the database.

Exception Summary
SerialException Indicates and an error with the serialization or de-serialization of SQL types such as BLOB, CLOB, STRUCT or ARRAY in addition to SQL types such as DATALINK and JAVAOBJECT

Package javax.sql.rowset.serial Description

Provides utility classes to allow serializable mappings between SQL types and data types in the Java programming language.

Standard JDBC RowSet implementations may use these utility classes to assist in the serialization of disconnected RowSet objects. This is useful when transmitting a disconnected RowSet object over the wire to a different VM or across layers within an application.

1.0 SerialArray

A serializable mapping in the Java programming language of an SQL ARRAY value.

The SerialArray class provides a constructor for creating a SerialArray instance from an Array object, methods for getting the base type and the SQL name for the base type, and methods for copying all or part of a SerialArray object.

2.0 SerialBlob

A serializable mapping in the Java programming language of an SQL BLOB value.

The SerialBlob class provides a constructor for creating an instance from a Blob object. Note that the Blob object should have brought the SQL BLOB value's data over to the client before a SerialBlob object is constructed from it. The data of an SQL BLOB value can be materialized on the client as an array of bytes (using the method Blob.getBytes) or as a stream of uninterpreted bytes (using the method Blob.getBinaryStream).

SerialBlob methods make it possible to make a copy of a SerialBlob object as an array of bytes or as a stream. They also make it possible to locate a given pattern of bytes or a Blob object within a SerialBlob object.

3.0 SerialClob

A serializable mapping in the Java programming language of an SQL CLOB value.

The SerialClob class provides a constructor for creating an instance from a Clob object. Note that the Clob object should have brought the SQL CLOB value's data over to the client before a SerialClob object is constructed from it. The data of an SQL CLOB value can be materialized on the client as a stream of Unicode characters.

SerialClob methods make it possible to get a substring from a SerialClob object or to locate the start of a pattern of characters.

5.0 SerialDatalink

A serializable mapping in the Java programming language of an SQL DATALINK value. A DATALINK value references a file outside of the underlying data source that the the originating data source manages.

RowSet implementations can use the method RowSet.getURL() to retrieve a java.net.URL object, which can be used to manipulate the external data.

    java.net.URL url = rowset.getURL(1);

6.0 SerialJavaObject

A serializable mapping in the Java programming language of an SQL JAVA_OBJECT value. Assuming the Java object instance implements the Serializable interface, this simply wraps the serialization process.

If however, the serialization is not possible in the case where the Java object is not immediately serializable, this class will attempt to serialize all non static members to permit the object instance state to be serialized. Static or transient fields cannot be serialized and attempting to do so will result in a SerialException being thrown.

7.0 SerialRef

A serializable mapping between the SQL REF type and the Java programming language.

The SerialRef class provides a constructor for creating a SerialRef instance from a Ref type and provides methods for getting and setting the Ref object type.

8.0 SerialStruct

A serializable mapping in the Java programming language of an SQL structured type. Each attribute that is not already serializable is mapped to a serializable form, and if an attribute is itself a structured type, each of its attributes that is not already serializable is mapped to a serializable form.

In addition, if a Map object is passed to one of the constructors or to the method getAttributes, the structured type is custom mapped according to the mapping specified in the Map object.
The SerialStruct class provides a constructor for creating an instance from a Struct object, a method for retrieving the SQL type name of the SQL structured type in the database, and methods for retrieving its attribute values.

9.0 SQLInputImpl

An input stream used for custom mapping user-defined types (UDTs). An SQLInputImpl object is an input stream that contains a stream of values that are the attributes of a UDT. This class is used by the driver behind the scenes when the method getObject is called on an SQL structured or distinct type that has a custom mapping; a programmer never invokes SQLInputImpl methods directly.

The SQLInputImpl class provides a set of reader methods analogous to the ResultSet getter methods. These methods make it possible to read the values in an SQLInputImpl object. The method wasNull is used to determine whether the the last value read was SQL NULL.

When a constructor or getter method that takes a Map object is called, the JDBC driver calls the method SQLData.getSQLType to determine the SQL type of the UDT being custom mapped. The driver creates an instance of SQLInputImpl, populating it with the attributes of the UDT. The driver then passes the input stream to the method SQLData.readSQL, which in turn calls the SQLInputImpl methods to read the attributes from the input stream.

10.0 SQLOutputImpl

The output stream for writing the attributes of a custom mapped user-defined type (UDT) back to the database. The driver uses this interface internally, and its methods are never directly invoked by an application programmer.

When an application calls the method PreparedStatement.setObject, the driver checks to see whether the value to be written is a UDT with a custom mapping. If it is, there will be an entry in a type map containing the Class object for the class that implements SQLData for this UDT. If the value to be written is an instance of SQLData, the driver will create an instance of SQLOutputImpl and pass it to the method SQLData.writeSQL. The method writeSQL in turn calls the appropriate SQLOutputImpl writer methods to write data from the SQLData object to the SQLOutputImpl output stream as the representation of an SQL user-defined type.

Custom Mapping

The JDBC API provides mechanisms for mapping an SQL structured type or DISTINCT type to the Java programming language. Typically, a structured type is mapped to a class, and its attributes are mapped to fields in the class. (A DISTINCT type can thought of as having one attribute.) However, there are many other possibilities, and there may be any number of different mappings.

A programmer defines the mapping by implementing the interface SQLData. For example, if an SQL structured type named AUTHORS has the attributes NAME, TITLE, and PUBLISHER, it could be mapped to a Java class named Authors. The Authors class could have the fields name, title, and publisher, to which the attributes of AUTHORS are mapped. In such a case, the implementation of SQLData could look like the following:

   public class Authors implements SQLData {
       public String name;
       public String title;
       public String publisher;

       private String sql_type;
       public String getSQLTypeName() {
           return sql_type;
       }

       public void readSQL(SQLInput stream, String type)
                                  throws SQLException  {
           sql_type = type;
           name = stream.readString();
           title = stream.readString();
           publisher = stream.readString();
       }

       public void writeSQL(SQLOutput stream) throws SQLException {
           stream.writeString(name);
           stream.writeString(title);
           stream.writeString(publisher);
       }
   }
A java.util.Map object is used to associate the SQL structured type with its mapping to the class Authors. The following code fragment shows how a Map object might be created and given an entry associating AUTHORS and Authors.
    java.util.Map map = new java.util.HashMap();
    map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors");
The Map object map now contains an entry with the fully qualified name of the SQL structured type and the Class object for the class Authors. It can be passed to a method to tell the driver how to map AUTHORS to Authors.

For a disconnected RowSet object, custom mapping can be done only when a Map object is passed to the method or constructor that will be doing the custom mapping. The situation is different for connected RowSet objects because they maintain a connection with the data source. A method that does custom mapping and is called by a disconnected RowSet object may use the Map object that is associated with the Connection object being used. So, in other words, if no map is specified, the connection's type map can be used by default.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.sql.rowset.serial Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.sql.rowset.serial

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.sql.rowset.serial.SerialArray (implements java.sql.Array, java.lang.Cloneable, java.io.Serializable)
    • javax.sql.rowset.serial.SerialBlob (implements java.sql.Blob, java.lang.Cloneable, java.io.Serializable)
    • javax.sql.rowset.serial.SerialClob (implements java.sql.Clob, java.lang.Cloneable, java.io.Serializable)
    • javax.sql.rowset.serial.SerialDatalink (implements java.lang.Cloneable, java.io.Serializable)
    • javax.sql.rowset.serial.SerialJavaObject (implements java.lang.Cloneable, java.io.Serializable)
    • javax.sql.rowset.serial.SerialRef (implements java.lang.Cloneable, java.sql.Ref, java.io.Serializable)
    • javax.sql.rowset.serial.SerialStruct (implements java.lang.Cloneable, java.io.Serializable, java.sql.Struct)
    • javax.sql.rowset.serial.SQLInputImpl (implements java.sql.SQLInput)
    • javax.sql.rowset.serial.SQLOutputImpl (implements java.sql.SQLOutput)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.sql.SQLException (implements java.lang.Iterable<T>)
          • javax.sql.rowset.serial.SerialException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.sql.rowset.serial

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.sql.rowset.serial

Packages that use javax.sql.rowset.serial
javax.sql.rowset.serial Provides utility classes to allow serializable mappings between SQL types and data types in the Java programming language.

Classes in javax.sql.rowset.serial used by javax.sql.rowset.serial
SerialException
Indicates and an error with the serialization or de-serialization of SQL types such as BLOB, CLOB, STRUCT or ARRAY in addition to SQL types such as DATALINK and JAVAOBJECT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.rowset.serial.SerialArray

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.rowset.serial.SerialArray

No usage of javax.sql.rowset.serial.SerialArray

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.rowset.serial.SerialBlob

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.rowset.serial.SerialBlob

No usage of javax.sql.rowset.serial.SerialBlob

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.rowset.serial.SerialClob

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.rowset.serial.SerialClob

No usage of javax.sql.rowset.serial.SerialClob

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.rowset.serial.SerialDatalink

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.rowset.serial.SerialDatalink

No usage of javax.sql.rowset.serial.SerialDatalink

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.rowset.serial.SerialException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.rowset.serial.SerialException

Packages that use SerialException
javax.sql.rowset.serial Provides utility classes to allow serializable mappings between SQL types and data types in the Java programming language.

Uses of SerialException in javax.sql.rowset.serial

Methods in javax.sql.rowset.serial that throw SerialException
Object | SerialArray.getArray() Returns a new array that is a copy of this SerialArray object.
Object | SerialArray.getArray(long index, int count) Returns a new array that is a copy of a slice of this SerialArray object, starting with the element at the given index and containing the given number of consecutive elements.
Object | SerialArray.getArray(long index, int count, Map<String,Class<?>> map) Returns a new array that is a copy of a slice of this SerialArray object, starting with the element at the given index and containing the given number of consecutive elements.
Object | SerialArray.getArray(Map<String,Class<?>> map) Returns a new array that is a copy of this SerialArray object, using the given type map for the custom mapping of each element when the elements are SQL UDTs.
InputStream | SerialClob.getAsciiStream() Retrieves the CLOB value designated by this SerialClob object as an ascii stream.
Object[] | SerialStruct.getAttributes() Retrieves an array of Object values containing the attributes of the SQL structured type that this SerialStruct object represents.
Object[] | SerialStruct.getAttributes(Map<String,Class<?>> map) Retrieves the attributes for the SQL structured type that this SerialStruct represents as an array of Object values, using the given type map for custom mapping if appropriate.
int | SerialArray.getBaseType() Retrieves the SQL type of the elements in this SerialArray object.
String | SerialRef.getBaseTypeName() Returns a string describing the base type name of the Ref.
String | SerialArray.getBaseTypeName() Retrieves the DBMS-specific type name for the elements in this SerialArray object.
InputStream | SerialBlob.getBinaryStream() Returns this SerialBlob object as an input stream.
byte[] | SerialBlob.getBytes(long pos, int length) Copies the specified number of bytes, starting at the given position, from this SerialBlob object to another array of bytes.
Reader | SerialClob.getCharacterStream() Returns this SerialClob object's data as a stream of Unicode characters.
URL | SerialDatalink.getDatalink() Returns a new URL that is a copy of this SerialDatalink object.
Field[] | SerialJavaObject.getFields() Returns an array of Field objects that contains each field of the object that this helper class is serializing.
Object | SerialRef.getObject() Returns an Object representing the SQL structured type to which this SerialRef object refers.
Object | SerialJavaObject.getObject() Returns an Object that is a copy of this SerialJavaObject object.
Object | SerialRef.getObject(Map<String,Class<?>> map) Returns an Object representing the SQL structured type to which this SerialRef object refers.
ResultSet | SerialArray.getResultSet() Retrieves a ResultSet object that contains all of the elements in the ARRAY value that this SerialArray object represents.
ResultSet | SerialArray.getResultSet(long index, int count) Retrieves a ResultSet object holding the elements of the subarray that starts at index index and contains up to count successive elements.
ResultSet | SerialArray.getResultSet(long index, int count, Map<String,Class<?>> map) Retrieves a result set holding the elements of the subarray that starts at Retrieves a ResultSet object that contains a subarray of the elements in this SerialArray object, starting at index index and containing up to count successive elements.
ResultSet | SerialArray.getResultSet(Map<String,Class<?>> map) Retrieves a ResultSet object that contains all of the elements of the SQL ARRAY value represented by this SerialArray object.
String | SerialStruct.getSQLTypeName() Retrieves the SQL type name for this SerialStruct object.
String | SerialClob.getSubString(long pos, int length) Returns a copy of the substring contained in this SerialClob object, starting at the given position and continuing for the specified number or characters.
long | SerialClob.length() Retrieves the number of characters in this SerialClob object's array of characters.
long | SerialBlob.length() Retrieves the number of bytes in this SerialBlob object's array of bytes.
long | SerialBlob.position(Blob pattern, long start) Returns the position in this SerialBlob object where the given Blob object begins, starting the search at the specified position.
long | SerialBlob.position(byte[] pattern, long start) Returns the position in this SerialBlob object where the given pattern of bytes begins, starting the search at the specified position.
long | SerialClob.position(Clob searchStr, long start) Returns the position in this SerialClob object where the given Clob signature begins, starting the search at the specified position.
long | SerialClob.position(String searchStr, long start) Returns the position in this SerialClob object where the given String object begins, starting the search at the specified position.
OutputStream | SerialClob.setAsciiStream(long pos) Retrieves a stream to be used to write Ascii characters to the CLOB value that this SerialClob object represents, starting at position pos.
OutputStream | SerialBlob.setBinaryStream(long pos) Retrieves a stream that can be used to write to the BLOB value that this Blob object represents.
int | SerialBlob.setBytes(long pos, byte[] bytes) Writes the given array of bytes to the BLOB value that this Blob object represents, starting at position pos, and returns the number of bytes written.
int | SerialBlob.setBytes(long pos, byte[] bytes, int offset, int length) Writes all or part of the given byte array to the BLOB value that this Blob object represents and returns the number of bytes written.
Writer | SerialClob.setCharacterStream(long pos) Retrieves a stream to be used to write a stream of Unicode characters to the CLOB value that this SerialClob object represents, at position pos.
void | SerialRef.setObject(Object obj) Sets the SQL structured type that this SerialRef object references to the given Object object.
int | SerialClob.setString(long pos, String str) Writes the given Java String to the CLOB value that this SerialClob object represents, at the position pos.
int | SerialClob.setString(long pos, String str, int offset, int length) Writes len characters of str, starting at character offset, to the CLOB value that this Clob represents.
void | SerialClob.truncate(long length) Truncates the CLOB value that this SerialClob object represents so that it has a length of len characters.
void | SerialBlob.truncate(long length) Truncates the BLOB value that this Blob object represents to be len bytes in length.

Constructors in javax.sql.rowset.serial that throw SerialException
SerialArray(Array array)
Constructs a new SerialArray object from the given Array object.
SerialArray(Array array, Map<String,Class<?>> map)
Constructs a new SerialArray object from the given Array object, using the given type map for the custom mapping of each element when the elements are SQL UDTs.
SerialBlob(Blob blob)
Constructs a SerialBlob object that is a serialized version of the given Blob object.
SerialBlob(byte[] b)
Constructs a SerialBlob object that is a serialized version of the given byte array.
SerialClob(char[] ch)
Constructs a SerialClob object that is a serialized version of the given char array.
SerialClob(Clob clob)
Constructs a SerialClob object that is a serialized version of the given Clob object.
SerialDatalink(URL url)
Constructs a new SerialDatalink object from the given java.net.URL object.
SerialJavaObject(Object obj)
Constructor for SerialJavaObject helper class.
SerialRef(Ref ref)
Constructs a SerialRef object from the given Ref object.
SerialStruct(SQLData in, Map<String,Class<?>> map)
Constructs a SerialStruct object from the given SQLData object, using the given type map to custom map it to a class in the Java programming language.
SerialStruct(Struct in, Map<String,Class<?>> map)
Constructs a SerialStruct object from the given Struct object, using the given java.util.Map object for custom mapping the SQL structured type or any of its attributes that are SQL structured types.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.rowset.serial.SerialJavaObject

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.rowset.serial.SerialJavaObject

No usage of javax.sql.rowset.serial.SerialJavaObject

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.rowset.serial.SerialRef

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.rowset.serial.SerialRef

No usage of javax.sql.rowset.serial.SerialRef

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.rowset.serial.SerialStruct

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.rowset.serial.SerialStruct

No usage of javax.sql.rowset.serial.SerialStruct

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.rowset.serial.SQLInputImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.rowset.serial.SQLInputImpl

No usage of javax.sql.rowset.serial.SQLInputImpl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.rowset.serial.SQLOutputImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.rowset.serial.SQLOutputImpl

No usage of javax.sql.rowset.serial.SQLOutputImpl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


SerialArray

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.serial
Class SerialArray

java.lang.Object
    extended by  javax.sql.rowset.serial.SerialArray
All Implemented Interfaces:
Serializable, Cloneable, Array
public class SerialArray
extends Object
implements Array, Serializable, Cloneable

A serialized version of an Array object, which is the mapping in the Java programming language of an SQL ARRAY value.

The SerialArray class provides a constructor for creating a SerialArray instance from an Array object, methods for getting the base type and the SQL name for the base type, and methods for copying all or part of a SerialArray object.

Note: In order for this class to function correctly, a connection to the data source must be available in order for the SQL Array object to be materialized (have all of its elements brought to the client server) if necessary. At this time, logical pointers to the data in the data source, such as locators, are not currently supported.

See Also:
Serialized Form

Constructor Summary
SerialArray(Array array)
Constructs a new SerialArray object from the given Array object.
SerialArray(Array array, Map<String,Class<?>> map)
Constructs a new SerialArray object from the given Array object, using the given type map for the custom mapping of each element when the elements are SQL UDTs.
Method Summary
void | free() This method frees the Array object and releases the resources that it holds.
Object | getArray() Returns a new array that is a copy of this SerialArray object.
Object | getArray(long index, int count) Returns a new array that is a copy of a slice of this SerialArray object, starting with the element at the given index and containing the given number of consecutive elements.
Object | getArray(long index, int count, Map<String,Class<?>> map) Returns a new array that is a copy of a slice of this SerialArray object, starting with the element at the given index and containing the given number of consecutive elements.
Object | getArray(Map<String,Class<?>> map) Returns a new array that is a copy of this SerialArray object, using the given type map for the custom mapping of each element when the elements are SQL UDTs.
int | getBaseType() Retrieves the SQL type of the elements in this SerialArray object.
String | getBaseTypeName() Retrieves the DBMS-specific type name for the elements in this SerialArray object.
ResultSet | getResultSet() Retrieves a ResultSet object that contains all of the elements in the ARRAY value that this SerialArray object represents.
ResultSet | getResultSet(long index, int count) Retrieves a ResultSet object holding the elements of the subarray that starts at index index and contains up to count successive elements.
ResultSet | getResultSet(long index, int count, Map<String,Class<?>> map) Retrieves a result set holding the elements of the subarray that starts at Retrieves a ResultSet object that contains a subarray of the elements in this SerialArray object, starting at index index and containing up to count successive elements.
ResultSet | getResultSet(Map<String,Class<?>> map) Retrieves a ResultSet object that contains all of the elements of the SQL ARRAY value represented by this SerialArray object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SerialArray

public SerialArray(Array array,
                   Map<String,Class<?>> map)
            throws SerialException,
                   SQLException
Constructs a new SerialArray object from the given Array object, using the given type map for the custom mapping of each element when the elements are SQL UDTs.

This method does custom mapping if the array elements are a UDT and the given type map has an entry for that UDT. Custom mapping is recursive, meaning that if, for instance, an element of an SQL structured type is an SQL structured type that itself has an element that is an SQL structured type, each structured type that has a custom mapping will be mapped according to the given type map.

The new SerialArray object contains the same elements as the Array object from which it is built, except when the base type is the SQL type STRUCT, ARRAY, BLOB, CLOB, DATALINK or JAVA_OBJECT. In this case, each element in the new SerialArray object is the appropriate serialized form, that is, a SerialStruct, SerialArray, SerialBlob, SerialClob, SerialDatalink, or SerialJavaObject object.

Note: (1) The Array object from which a SerialArray object is created must have materialized the SQL ARRAY value's data on the client before it is passed to the constructor. Otherwise, the new SerialArray object will contain no data.

Note: (2) If the Array contains java.sql.Types.JAVA_OBJECT types, the SerialJavaObject constructor is called where checks are made to ensure this object is serializable.

Note: (3) The Array object supplied to this constructor cannot return null for any Array.getArray() methods. SerialArray cannot serialize null array values.

Parameters:
array - the Array object to be serialized
map - a java.util.Map object in which each entry consists of 1) a String object giving the fully qualified name of a UDT (an SQL structured type or distinct type) and 2) the Class object for the SQLData implementation that defines how the UDT is to be mapped. The map parameter does not have any effect for Blob, Clob, DATALINK, or JAVA_OBJECT types.
Throws:
SerialException - if an error occurs serializing the Array object
SQLException - if a database access error occurs or if the array or the map values are null

SerialArray

public SerialArray(Array array)
            throws SerialException,
                   SQLException
Constructs a new SerialArray object from the given Array object.

This constructor does not do custom mapping. If the base type of the array is an SQL structured type and custom mapping is desired, the constructor SerialArray(Array array, Map map) should be used.

The new SerialArray object contains the same elements as the Array object from which it is built, except when the base type is the SQL type BLOB, CLOB, DATALINK or JAVA_OBJECT. In this case, each element in the new SerialArray object is the appropriate serialized form, that is, a SerialBlob, SerialClob, SerialDatalink, or SerialJavaObject object.

Note: (1) The Array object from which a SerialArray object is created must have materialized the SQL ARRAY value's data on the client before it is passed to the constructor. Otherwise, the new SerialArray object will contain no data.

Note: (2) The Array object supplied to this constructor cannot return null for any Array.getArray() methods. SerialArray cannot serialize null array values.

Parameters:
array - the Array object to be serialized
Throws:
SerialException - if an error occurs serializing the Array object
SQLException - if a database access error occurs or the array parameter is null.
Method Detail

free

public void free()
          throws SQLException
This method frees the Array object and releases the resources that it holds. The object is invalid once the free method is called.

After free has been called, any attempt to invoke a method other than free will result in a SQLException being thrown. If free is called multiple times, the subsequent calls to free are treated as a no-op.

Specified by:
free in interface Array
Throws:
SQLException - if an error occurs releasing the Array's resources
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.6

getArray

public Object getArray()
                throws SerialException
Returns a new array that is a copy of this SerialArray object.

Specified by:
getArray in interface Array
Returns:
a copy of this SerialArray object as an Object in the Java programming language
Throws:
SerialException - if an error occurs retrieving a copy of this SerialArray object

getArray

public Object getArray(Map<String,Class<?>> map)
                throws SerialException
Returns a new array that is a copy of this SerialArray object, using the given type map for the custom mapping of each element when the elements are SQL UDTs.

This method does custom mapping if the array elements are a UDT and the given type map has an entry for that UDT. Custom mapping is recursive, meaning that if, for instance, an element of an SQL structured type is an SQL structured type that itself has an element that is an SQL structured type, each structured type that has a custom mapping will be mapped according to the given type map.

Specified by:
getArray in interface Array
Parameters:
map - a java.util.Map object in which each entry consists of 1) a String object giving the fully qualified name of a UDT and 2) the Class object for the SQLData implementation that defines how the UDT is to be mapped
Returns:
a copy of this SerialArray object as an Object in the Java programming language
Throws:
SerialException - if an error occurs

getArray

public Object getArray(long index,
                       int count)
                throws SerialException
Returns a new array that is a copy of a slice of this SerialArray object, starting with the element at the given index and containing the given number of consecutive elements.

Specified by:
getArray in interface Array
Parameters:
index - the index into this SerialArray object of the first element to be copied; the index of the first element is 0
count - the number of consecutive elements to be copied, starting at the given index
Returns:
a copy of the designated elements in this SerialArray object as an Object in the Java programming language
Throws:
SerialException - if an error occurs

getArray

public Object getArray(long index,
                       int count,
                       Map<String,Class<?>> map)
                throws SerialException
Returns a new array that is a copy of a slice of this SerialArray object, starting with the element at the given index and containing the given number of consecutive elements.

This method does custom mapping if the array elements are a UDT and the given type map has an entry for that UDT. Custom mapping is recursive, meaning that if, for instance, an element of an SQL structured type is an SQL structured type that itself has an element that is an SQL structured type, each structured type that has a custom mapping will be mapped according to the given type map.

Specified by:
getArray in interface Array
Parameters:
index - the index into this SerialArray object of the first element to be copied; the index of the first element in the array is 0
count - the number of consecutive elements to be copied, starting at the given index
map - a java.util.Map object in which each entry consists of 1) a String object giving the fully qualified name of a UDT and 2) the Class object for the SQLData implementation that defines how the UDT is to be mapped
Returns:
a copy of the designated elements in this SerialArray object as an Object in the Java programming language
Throws:
SerialException - if an error occurs

getBaseType

public int getBaseType()
                throws SerialException
Retrieves the SQL type of the elements in this SerialArray object. The int returned is one of the constants in the class java.sql.Types.

Specified by:
getBaseType in interface Array
Returns:
one of the constants in java.sql.Types, indicating the SQL type of the elements in this SerialArray object
Throws:
SerialException - if an error occurs

getBaseTypeName

public String getBaseTypeName()
                       throws SerialException
Retrieves the DBMS-specific type name for the elements in this SerialArray object.

Specified by:
getBaseTypeName in interface Array
Returns:
the SQL type name used by the DBMS for the base type of this SerialArray object
Throws:
SerialException - if an error occurs

getResultSet

public ResultSet getResultSet(long index,
                              int count)
                       throws SerialException
Retrieves a ResultSet object holding the elements of the subarray that starts at index index and contains up to count successive elements. This method uses the connection's type map to map the elements of the array if the map contains an entry for the base type. Otherwise, the standard mapping is used.

Specified by:
getResultSet in interface Array
Parameters:
index - the index into this SerialArray object of the first element to be copied; the index of the first element in the array is 0
count - the number of consecutive elements to be copied, starting at the given index
Returns:
a ResultSet object containing the designated elements in this SerialArray object, with a separate row for each element
Throws:
SerialException, - which in turn throws an UnsupportedOperationException, if this method is called
SerialException

getResultSet

public ResultSet getResultSet(Map<String,Class<?>> map)
                       throws SerialException
Retrieves a ResultSet object that contains all of the elements of the SQL ARRAY value represented by this SerialArray object. This method uses the specified map for type map customizations unless the base type of the array does not match a user-defined type (UDT) in map, in which case it uses the standard mapping. This version of the method getResultSet uses either the given type map or the standard mapping; it never uses the type map associated with the connection.

Specified by:
getResultSet in interface Array
Parameters:
map - a java.util.Map object in which each entry consists of 1) a String object giving the fully qualified name of a UDT and 2) the Class object for the SQLData implementation that defines how the UDT is to be mapped
Returns:
a ResultSet object containing all of the elements in this SerialArray object, with a separate row for each element
Throws:
SerialException, - which in turn throws an UnsupportedOperationException, if this method is called
SerialException

getResultSet

public ResultSet getResultSet()
                       throws SerialException
Retrieves a ResultSet object that contains all of the elements in the ARRAY value that this SerialArray object represents. If appropriate, the elements of the array are mapped using the connection's type map; otherwise, the standard mapping is used.

Specified by:
getResultSet in interface Array
Returns:
a ResultSet object containing all of the elements in this SerialArray object, with a separate row for each element
Throws:
SerialException - if called, which in turn throws an UnsupportedOperationException, if this method is called

getResultSet

public ResultSet getResultSet(long index,
                              int count,
                              Map<String,Class<?>> map)
                       throws SerialException
Retrieves a result set holding the elements of the subarray that starts at Retrieves a ResultSet object that contains a subarray of the elements in this SerialArray object, starting at index index and containing up to count successive elements. This method uses the specified map for type map customizations unless the base type of the array does not match a user-defined type (UDT) in map, in which case it uses the standard mapping. This version of the method getResultSet uses either the given type map or the standard mapping; it never uses the type map associated with the connection.

Specified by:
getResultSet in interface Array
Parameters:
index - the index into this SerialArray object of the first element to be copied; the index of the first element in the array is 0
count - the number of consecutive elements to be copied, starting at the given index
map - a java.util.Map object in which each entry consists of 1) a String object giving the fully qualified name of a UDT and 2) the Class object for the SQLData implementation that defines how the UDT is to be mapped
Returns:
a ResultSet object containing the designated elements in this SerialArray object, with a separate row for each element
Throws:
SerialException - if called, which in turn throws an UnsupportedOperationException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


SerialBlob

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.serial
Class SerialBlob

java.lang.Object
    extended by  javax.sql.rowset.serial.SerialBlob
All Implemented Interfaces:
Serializable, Cloneable, Blob
public class SerialBlob
extends Object
implements Blob, Serializable, Cloneable

A serialized mapping in the Java programming language of an SQL BLOB value.

The SerialBlob class provides a constructor for creating an instance from a Blob object. Note that the Blob object should have brought the SQL BLOB value's data over to the client before a SerialBlob object is constructed from it. The data of an SQL BLOB value can be materialized on the client as an array of bytes (using the method Blob.getBytes) or as a stream of uninterpreted bytes (using the method Blob.getBinaryStream).

SerialBlob methods make it possible to make a copy of a SerialBlob object as an array of bytes or as a stream. They also make it possible to locate a given pattern of bytes or a Blob object within a SerialBlob object and to update or truncate a Blob object.

See Also:
Serialized Form

Constructor Summary
SerialBlob(Blob blob)
Constructs a SerialBlob object that is a serialized version of the given Blob object.
SerialBlob(byte[] b)
Constructs a SerialBlob object that is a serialized version of the given byte array.
Method Summary
void | free() This method frees the Blob object and releases the resources that it holds.
InputStream | getBinaryStream() Returns this SerialBlob object as an input stream.
InputStream | getBinaryStream(long pos, long length) Returns an InputStream object that contains a partial Blob value, starting with the byte specified by pos, which is length bytes in length.
byte[] | getBytes(long pos, int length) Copies the specified number of bytes, starting at the given position, from this SerialBlob object to another array of bytes.
long | length() Retrieves the number of bytes in this SerialBlob object's array of bytes.
long | position(Blob pattern, long start) Returns the position in this SerialBlob object where the given Blob object begins, starting the search at the specified position.
long | position(byte[] pattern, long start) Returns the position in this SerialBlob object where the given pattern of bytes begins, starting the search at the specified position.
OutputStream | setBinaryStream(long pos) Retrieves a stream that can be used to write to the BLOB value that this Blob object represents.
int | setBytes(long pos, byte[] bytes) Writes the given array of bytes to the BLOB value that this Blob object represents, starting at position pos, and returns the number of bytes written.
int | setBytes(long pos, byte[] bytes, int offset, int length) Writes all or part of the given byte array to the BLOB value that this Blob object represents and returns the number of bytes written.
void | truncate(long length) Truncates the BLOB value that this Blob object represents to be len bytes in length.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SerialBlob

public SerialBlob(byte[] b)
           throws SerialException,
                  SQLException
Constructs a SerialBlob object that is a serialized version of the given byte array.

The new SerialBlob object is initialized with the data from the byte array, thus allowing disconnected RowSet objects to establish serialized Blob objects without touching the data source.

Parameters:
b - the byte array containing the data for the Blob object to be serialized
Throws:
SerialException - if an error occurs during serialization
SQLException - if a SQL errors occurs

SerialBlob

public SerialBlob(Blob blob)
           throws SerialException,
                  SQLException
Constructs a SerialBlob object that is a serialized version of the given Blob object.

The new SerialBlob object is initialized with the data from the Blob object; therefore, the Blob object should have previously brought the SQL BLOB value's data over to the client from the database. Otherwise, the new SerialBlob object will contain no data.

Parameters:
blob - the Blob object from which this SerialBlob object is to be constructed; cannot be null.
Throws:
SerialException - if an error occurs during serialization
SQLException - if the Blob passed to this to this constructor is a null.
See Also:
Blob
Method Detail

getBytes

public byte[] getBytes(long pos,
                       int length)
                throws SerialException
Copies the specified number of bytes, starting at the given position, from this SerialBlob object to another array of bytes.

Note that if the given number of bytes to be copied is larger than the length of this SerialBlob object's array of bytes, the given number will be shortened to the array's length.

Specified by:
getBytes in interface Blob
Parameters:
pos - the ordinal position of the first byte in this SerialBlob object to be copied; numbering starts at 1; must not be less than 1 and must be less than or equal to the length of this SerialBlob object
length - the number of bytes to be copied
Returns:
an array of bytes that is a copy of a region of this SerialBlob object, starting at the given position and containing the given number of consecutive bytes
Throws:
SerialException - if the given starting position is out of bounds
See Also:
Blob.setBytes(long, byte[])

length

public long length()
            throws SerialException
Retrieves the number of bytes in this SerialBlob object's array of bytes.

Specified by:
length in interface Blob
Returns:
a long indicating the length in bytes of this SerialBlob object's array of bytes
Throws:
SerialException - if an error occurs

getBinaryStream

public InputStream getBinaryStream()
                            throws SerialException
Returns this SerialBlob object as an input stream. Unlike the related method, setBinaryStream, a stream is produced regardless of whether the SerialBlob was created with a Blob object or a byte array.

Specified by:
getBinaryStream in interface Blob
Returns:
a java.io.InputStream object that contains this SerialBlob object's array of bytes
Throws:
SerialException - if an error occurs
See Also:
setBinaryStream(long)

position

public long position(byte[] pattern,
                     long start)
              throws SerialException,
                     SQLException
Returns the position in this SerialBlob object where the given pattern of bytes begins, starting the search at the specified position.

Specified by:
position in interface Blob
Parameters:
pattern - the pattern of bytes for which to search
start - the position of the byte in this SerialBlob object from which to begin the search; the first position is 1; must not be less than 1 nor greater than the length of this SerialBlob object
Returns:
the position in this SerialBlob object where the given pattern begins, starting at the specified position; -1 if the pattern is not found or the given starting position is out of bounds; position numbering for the return value starts at 1
Throws:
SerialException - if an error occurs when serializing the blob
SQLException - if there is an error accessing the BLOB value from the database

position

public long position(Blob pattern,
                     long start)
              throws SerialException,
                     SQLException
Returns the position in this SerialBlob object where the given Blob object begins, starting the search at the specified position.

Specified by:
position in interface Blob
Parameters:
pattern - the Blob object for which to search;
start - the position of the byte in this SerialBlob object from which to begin the search; the first position is 1; must not be less than 1 nor greater than the length of this SerialBlob object
Returns:
the position in this SerialBlob object where the given Blob object begins, starting at the specified position; -1 if the pattern is not found or the given starting position is out of bounds; position numbering for the return value starts at 1
Throws:
SerialException - if an error occurs when serializing the blob
SQLException - if there is an error accessing the BLOB value from the database

setBytes

public int setBytes(long pos,
                    byte[] bytes)
             throws SerialException,
                    SQLException
Writes the given array of bytes to the BLOB value that this Blob object represents, starting at position pos, and returns the number of bytes written.

Specified by:
setBytes in interface Blob
Parameters:
pos - the position in the SQL BLOB value at which to start writing. The first position is 1; must not be less than 1 nor greater than the length of this SerialBlob object.
bytes - the array of bytes to be written to the BLOB value that this Blob object represents
Returns:
the number of bytes written
Throws:
SerialException - if there is an error accessing the BLOB value; or if an invalid position is set; if an invalid offset value is set
SQLException - if there is an error accessing the BLOB value from the database
See Also:
getBytes(long, int)

setBytes

public int setBytes(long pos,
                    byte[] bytes,
                    int offset,
                    int length)
             throws SerialException,
                    SQLException
Writes all or part of the given byte array to the BLOB value that this Blob object represents and returns the number of bytes written. Writing starts at position pos in the BLOB value; len bytes from the given byte array are written.

Specified by:
setBytes in interface Blob
Parameters:
pos - the position in the BLOB object at which to start writing. The first position is 1; must not be less than 1 nor greater than the length of this SerialBlob object.
bytes - the array of bytes to be written to the BLOB value
offset - the offset in the byte array at which to start reading the bytes. The first offset position is 0; must not be less than 0 nor greater than the length of the byte array
length - the number of bytes to be written to the BLOB value from the array of bytes bytes.
Returns:
the number of bytes written
Throws:
SerialException - if there is an error accessing the BLOB value; if an invalid position is set; if an invalid offset value is set; if number of bytes to be written is greater than the SerialBlob length; or the combined values of the length and offset is greater than the Blob buffer
SQLException - if there is an error accessing the BLOB value from the database.
See Also:
getBytes(long, int)

setBinaryStream

public OutputStream setBinaryStream(long pos)
                             throws SerialException,
                                    SQLException
Retrieves a stream that can be used to write to the BLOB value that this Blob object represents. The stream begins at position pos. This method forwards the setBinaryStream() call to the underlying Blob in the event that this SerialBlob object is instantiated with a Blob. If this SerialBlob is instantiated with a byte array, a SerialException is thrown.

Specified by:
setBinaryStream in interface Blob
Parameters:
pos - the position in the BLOB value at which to start writing
Returns:
a java.io.OutputStream object to which data can be written
Throws:
SQLException - if there is an error accessing the BLOB value
SerialException - if the SerialBlob in not instantiated with a Blob object that supports setBinaryStream()
See Also:
getBinaryStream()

truncate

public void truncate(long length)
              throws SerialException
Truncates the BLOB value that this Blob object represents to be len bytes in length.

Specified by:
truncate in interface Blob
Parameters:
length - the length, in bytes, to which the BLOB value that this Blob object represents should be truncated
Throws:
SerialException - if there is an error accessing the Blob value; or the length to truncate is greater that the SerialBlob length

getBinaryStream

public InputStream getBinaryStream(long pos,
                                   long length)
                            throws SQLException
Returns an InputStream object that contains a partial Blob value, starting with the byte specified by pos, which is length bytes in length.

Specified by:
getBinaryStream in interface Blob
Parameters:
pos - the offset to the first byte of the partial value to be retrieved. The first byte in the Blob is at position 1
length - the length in bytes of the partial value to be retrieved
Returns:
InputStream through which the partial Blob value can be read.
Throws:
SQLException - if pos is less than 1 or if pos is greater than the number of bytes in the Blob or if pos + length is greater than the number of bytes in the Blob
Since:
1.6

free

public void free()
          throws SQLException
This method frees the Blob object and releases the resources that it holds. Blob object. The object is invalid once the free method is called. If free is called multiple times, the subsequent calls to free are treated as a no-op.

Specified by:
free in interface Blob
Throws:
SQLException - if an error occurs releasing the Blob's resources
Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SerialClob

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.serial
Class SerialClob

java.lang.Object
    extended by  javax.sql.rowset.serial.SerialClob
All Implemented Interfaces:
Serializable, Cloneable, Clob
public class SerialClob
extends Object
implements Clob, Serializable, Cloneable

A serialized mapping in the Java programming language of an SQL CLOB value.

The SerialClob class provides a constructor for creating an instance from a Clob object. Note that the Clob object should have brought the SQL CLOB value's data over to the client before a SerialClob object is constructed from it. The data of an SQL CLOB value can be materialized on the client as a stream of Unicode characters.

SerialClob methods make it possible to get a substring from a SerialClob object or to locate the start of a pattern of characters.

See Also:
Serialized Form

Constructor Summary
SerialClob(char[] ch)
Constructs a SerialClob object that is a serialized version of the given char array.
SerialClob(Clob clob)
Constructs a SerialClob object that is a serialized version of the given Clob object.
Method Summary
void | free() This method frees the Clob object and releases the resources the resources that it holds.
InputStream | getAsciiStream() Retrieves the CLOB value designated by this SerialClob object as an ascii stream.
Reader | getCharacterStream() Returns this SerialClob object's data as a stream of Unicode characters.
Reader | getCharacterStream(long pos, long length) Returns a Reader object that contains a partial Clob value, starting with the character specified by pos, which is length characters in length.
String | getSubString(long pos, int length) Returns a copy of the substring contained in this SerialClob object, starting at the given position and continuing for the specified number or characters.
long | length() Retrieves the number of characters in this SerialClob object's array of characters.
long | position(Clob searchStr, long start) Returns the position in this SerialClob object where the given Clob signature begins, starting the search at the specified position.
long | position(String searchStr, long start) Returns the position in this SerialClob object where the given String object begins, starting the search at the specified position.
OutputStream | setAsciiStream(long pos) Retrieves a stream to be used to write Ascii characters to the CLOB value that this SerialClob object represents, starting at position pos.
Writer | setCharacterStream(long pos) Retrieves a stream to be used to write a stream of Unicode characters to the CLOB value that this SerialClob object represents, at position pos.
int | setString(long pos, String str) Writes the given Java String to the CLOB value that this SerialClob object represents, at the position pos.
int | setString(long pos, String str, int offset, int length) Writes len characters of str, starting at character offset, to the CLOB value that this Clob represents.
void | truncate(long length) Truncates the CLOB value that this SerialClob object represents so that it has a length of len characters.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SerialClob

public SerialClob(char[] ch)
           throws SerialException,
                  SQLException
Constructs a SerialClob object that is a serialized version of the given char array.

The new SerialClob object is initialized with the data from the char array, thus allowing disconnected RowSet objects to establish a serialized Clob object without touching the data source.

Parameters:
ch - the char array representing the Clob object to be serialized
Throws:
SerialException - if an error occurs during serialization
SQLException - if a SQL error occurs

SerialClob

public SerialClob(Clob clob)
           throws SerialException,
                  SQLException
Constructs a SerialClob object that is a serialized version of the given Clob object.

The new SerialClob object is initialized with the data from the Clob object; therefore, the Clob object should have previously brought the SQL CLOB value's data over to the client from the database. Otherwise, the new SerialClob object object will contain no data.

Note: The Clob object supplied to this constructor cannot return null for the Clob.getCharacterStream() and Clob.getAsciiStream methods. This SerialClob constructor cannot serialize a Clob object in this instance and will throw an SQLException object.

Parameters:
clob - the Clob object from which this SerialClob object is to be constructed; cannot be null
Throws:
SerialException - if an error occurs during serialization
SQLException - if a SQL error occurs in capturing the CLOB; if the Clob object is a null; or if both the Clob.getCharacterStream() and Clob.getAsciiStream() methods on the Clob return a null
See Also:
Clob
Method Detail

length

public long length()
            throws SerialException
Retrieves the number of characters in this SerialClob object's array of characters.

Specified by:
length in interface Clob
Returns:
a long indicating the length in characters of this SerialClob object's array of character
Throws:
SerialException - if an error occurs

getCharacterStream

public Reader getCharacterStream()
                          throws SerialException
Returns this SerialClob object's data as a stream of Unicode characters. Unlike the related method, getAsciiStream, a stream is produced regardless of whether the SerialClob object was created with a Clob object or a char array.

Specified by:
getCharacterStream in interface Clob
Returns:
a java.io.Reader object containing this SerialClob object's data
Throws:
SerialException - if an error occurs
See Also:
Clob.setCharacterStream(long)

getAsciiStream

public InputStream getAsciiStream()
                           throws SerialException,
                                  SQLException
Retrieves the CLOB value designated by this SerialClob object as an ascii stream. This method forwards the getAsciiStream call to the underlying Clob object in the event that this SerialClob object is instantiated with a Clob object. If this SerialClob object is instantiated with a char array, a SerialException object is thrown.

Specified by:
getAsciiStream in interface Clob
Returns:
a java.io.InputStream object containing this SerialClob object's data
Throws:
SerialException - if this SerialClob object was not instantiated with a Clob object
SQLException - if there is an error accessing the CLOB value represented by the Clob object that was used to create this SerialClob object
See Also:
Clob.setAsciiStream(long)

getSubString

public String getSubString(long pos,
                           int length)
                    throws SerialException
Returns a copy of the substring contained in this SerialClob object, starting at the given position and continuing for the specified number or characters.

Specified by:
getSubString in interface Clob
Parameters:
pos - the position of the first character in the substring to be copied; the first character of the SerialClob object is at position 1; must not be less than 1, and the sum of the starting position and the length of the substring must be less than the length of this SerialClob object
length - the number of characters in the substring to be returned; must not be greater than the length of this SerialClob object, and the sum of the starting position and the length of the substring must be less than the length of this SerialClob object
Returns:
a String object containing a substring of this SerialClob object beginning at the given position and containing the specified number of consecutive characters
Throws:
SerialException - if either of the arguments is out of bounds

position

public long position(String searchStr,
                     long start)
              throws SerialException,
                     SQLException
Returns the position in this SerialClob object where the given String object begins, starting the search at the specified position. This method returns -1 if the pattern is not found.

Specified by:
position in interface Clob
Parameters:
searchStr - the String object for which to search
start - the position in this SerialClob object at which to start the search; the first position is 1; must not be less than 1 nor greater than the length of this SerialClob object
Returns:
the position at which the given String object begins, starting the search at the specified position; -1 if the given String object is not found or the starting position is out of bounds; position numbering for the return value starts at 1
Throws:
SerialException - if an error occurs locating the String signature
SQLException - if there is an error accessing the Blob value from the database.

position

public long position(Clob searchStr,
                     long start)
              throws SerialException,
                     SQLException
Returns the position in this SerialClob object where the given Clob signature begins, starting the search at the specified position. This method returns -1 if the pattern is not found.

Specified by:
position in interface Clob
Parameters:
searchStr - the Clob object for which to search
start - the position in this SerialClob object at which to begin the search; the first position is 1; must not be less than 1 nor greater than the length of this SerialClob object
Returns:
the position at which the given Clob object begins in this SerialClob object, at or after the specified starting position
Throws:
SerialException - if an error occurs locating the Clob signature
SQLException - if there is an error accessing the Blob value from the database

setString

public int setString(long pos,
                     String str)
              throws SerialException
Writes the given Java String to the CLOB value that this SerialClob object represents, at the position pos.

Specified by:
setString in interface Clob
Parameters:
pos - the position at which to start writing to the CLOB value that this SerialClob object represents; the first position is 1; must not be less than 1 nor greater than the length of this SerialClob object
str - the string to be written to the CLOB value that this SerialClob object represents
Returns:
the number of characters written
Throws:
SerialException - if there is an error accessing the CLOB value; if an invalid position is set; if an invalid offset value is set; if number of bytes to be written is greater than the SerialClob length; or the combined values of the length and offset is greater than the Clob buffer

setString

public int setString(long pos,
                     String str,
                     int offset,
                     int length)
              throws SerialException
Writes len characters of str, starting at character offset, to the CLOB value that this Clob represents.

Specified by:
setString in interface Clob
Parameters:
pos - the position at which to start writing to the CLOB value that this SerialClob object represents; the first position is 1; must not be less than 1 nor greater than the length of this SerialClob object
str - the string to be written to the CLOB value that this Clob object represents
offset - the offset into str to start reading the characters to be written
length - the number of characters to be written
Returns:
the number of characters written
Throws:
SerialException - if there is an error accessing the CLOB value; if an invalid position is set; if an invalid offset value is set; if number of bytes to be written is greater than the SerialClob length; or the combined values of the length and offset is greater than the Clob buffer

setAsciiStream

public OutputStream setAsciiStream(long pos)
                            throws SerialException,
                                   SQLException
Retrieves a stream to be used to write Ascii characters to the CLOB value that this SerialClob object represents, starting at position pos. This method forwards the setAsciiStream() call to the underlying Clob object in the event that this SerialClob object is instantiated with a Clob object. If this SerialClob object is instantiated with a char array, a SerialException object is thrown.

Specified by:
setAsciiStream in interface Clob
Parameters:
pos - the position at which to start writing to the CLOB object
Returns:
the stream to which ASCII encoded characters can be written
Throws:
SerialException - if SerialClob is not instantiated with a Clob object that supports setAsciiStream
SQLException - if there is an error accessing the CLOB value
See Also:
getAsciiStream()

setCharacterStream

public Writer setCharacterStream(long pos)
                          throws SerialException,
                                 SQLException
Retrieves a stream to be used to write a stream of Unicode characters to the CLOB value that this SerialClob object represents, at position pos. This method forwards the setCharacterStream() call to the underlying Clob object in the event that this SerialClob object is instantiated with a Clob object. If this SerialClob object is instantiated with a char array, a SerialException is thrown.

Specified by:
setCharacterStream in interface Clob
Parameters:
pos - the position at which to start writing to the CLOB value
Returns:
a stream to which Unicode encoded characters can be written
Throws:
SerialException - if the SerialClob is not instantiated with a Clob object that supports setCharacterStream
SQLException - if there is an error accessing the CLOB value
See Also:
getCharacterStream()

truncate

public void truncate(long length)
              throws SerialException
Truncates the CLOB value that this SerialClob object represents so that it has a length of len characters.

Truncating a SerialClob object to length 0 has the effect of clearing its contents.

Specified by:
truncate in interface Clob
Parameters:
length - the length, in bytes, to which the CLOB value should be truncated
Throws:
SQLException - if there is an error accessing the CLOB value
SerialException

getCharacterStream

public Reader getCharacterStream(long pos,
                                 long length)
                          throws SQLException
Description copied from interface: Clob
Returns a Reader object that contains a partial Clob value, starting with the character specified by pos, which is length characters in length.

Specified by:
getCharacterStream in interface Clob
Parameters:
pos - the offset to the first character of the partial value to be retrieved. The first character in the Clob is at position 1.
length - the length in characters of the partial value to be retrieved.
Returns:
Reader through which the partial Clob value can be read.
Throws:
SQLException - if pos is less than 1 or if pos is greater than the number of characters in the Clob or if pos + length is greater than the number of characters in the Clob
SQLFeatureNotSupportedException - if the JDBC driver does not support this method

free

public void free()
          throws SQLException
Description copied from interface: Clob
This method frees the Clob object and releases the resources the resources that it holds. The object is invalid once the free method is called.

After free has been called, any attempt to invoke a method other than free will result in a SQLException being thrown. If free is called multiple times, the subsequent calls to free are treated as a no-op.

Specified by:
free in interface Clob
Throws:
SQLException - if an error occurs releasing the Clob's resources
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SerialDatalink

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.serial
Class SerialDatalink

java.lang.Object
    extended by  javax.sql.rowset.serial.SerialDatalink
All Implemented Interfaces:
Serializable, Cloneable
public class SerialDatalink
extends Object
implements Serializable, Cloneable

A serialized mapping in the Java programming language of an SQL DATALINK value. A DATALINK value references a file outside of the underlying data source that the data source manages.

RowSet implementations can use the method RowSet.getURL to retrieve a java.net.URL object, which can be used to manipulate the external data.

      java.net.URL url = rowset.getURL(1);

See Also:
Serialized Form

Constructor Summary
SerialDatalink(URL url)
Constructs a new SerialDatalink object from the given java.net.URL object.
Method Summary
 URL getDatalink()
Returns a new URL that is a copy of this SerialDatalink object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SerialDatalink

public SerialDatalink(URL url)
               throws SerialException
Constructs a new SerialDatalink object from the given java.net.URL object.

Throws:
SerialException - if url parameter is a null
Method Detail

getDatalink

public URL getDatalink()
                throws SerialException
Returns a new URL that is a copy of this SerialDatalink object.

Returns:
a copy of this SerialDatalink object as a URL object in the Java programming language.
Throws:
SerialException - if the URL object cannot be de-serialized
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SerialException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.serial
Class SerialException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.sql.SQLException
                extended by  javax.sql.rowset.serial.SerialException
All Implemented Interfaces:
Serializable, Iterable<Throwable>
public class SerialException
extends SQLException

Indicates and an error with the serialization or de-serialization of SQL types such as BLOB, CLOB, STRUCT or ARRAY in addition to SQL types such as DATALINK and JAVAOBJECT

See Also:
Serialized Form

Constructor Summary
SerialException()
Creates a new SerialException without a message.
SerialException(String msg)
Creates a new SerialException with the specified message.
Method Summary
Methods inherited from class java.sql.SQLException
getErrorCode, getNextException, getSQLState, iterator, setNextException
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SerialException

public SerialException()
Creates a new SerialException without a message.

SerialException

public SerialException(String msg)
Creates a new SerialException with the specified message.

Parameters:
msg - the detail message
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SerialJavaObject

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.serial
Class SerialJavaObject

java.lang.Object
    extended by  javax.sql.rowset.serial.SerialJavaObject
All Implemented Interfaces:
Serializable, Cloneable
public class SerialJavaObject
extends Object
implements Serializable, Cloneable

A serializable mapping in the Java programming language of an SQL JAVA_OBJECT value. Assuming the Java object implements the Serializable interface, this class simply wraps the serialization process.

If however, the serialization is not possible because the Java object is not immediately serializable, this class will attempt to serialize all non-static members to permit the object state to be serialized. Static or transient fields cannot be serialized; an attempt to serialize them will result in a SerialException object being thrown.

See Also:
Serialized Form

Constructor Summary
SerialJavaObject(Object obj)
Constructor for SerialJavaObject helper class.
Method Summary
Field[] | getFields() Returns an array of Field objects that contains each field of the object that this helper class is serializing.
Object | getObject() Returns an Object that is a copy of this SerialJavaObject object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SerialJavaObject

public SerialJavaObject(Object obj)
                 throws SerialException
Constructor for SerialJavaObject helper class.

Parameters:
obj - the Java Object to be serialized
Throws:
SerialException - if the object is found to be unserializable
Method Detail

getObject

public Object getObject()
                 throws SerialException
Returns an Object that is a copy of this SerialJavaObject object.

Returns:
a copy of this SerialJavaObject object as an Object in the Java programming language
Throws:
SerialException - if the instance is corrupt

getFields

public Field[] getFields()
                  throws SerialException
Returns an array of Field objects that contains each field of the object that this helper class is serializing.

Returns:
an array of Field objects
Throws:
SerialException - if an error is encountered accessing the serialized object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SerialRef

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.serial
Class SerialRef

java.lang.Object
    extended by  javax.sql.rowset.serial.SerialRef
All Implemented Interfaces:
Serializable, Cloneable, Ref
public class SerialRef
extends Object
implements Ref, Serializable, Cloneable

A serialized mapping of a Ref object, which is the mapping in the Java programming language of an SQL REF value.

The SerialRef class provides a constructor for creating a SerialRef instance from a Ref object and provides methods for getting and setting the Ref object.

See Also:
Serialized Form

Constructor Summary
SerialRef(Ref ref)
Constructs a SerialRef object from the given Ref object.
Method Summary
String | getBaseTypeName() Returns a string describing the base type name of the Ref.
Object | getObject() Returns an Object representing the SQL structured type to which this SerialRef object refers.
Object | getObject(Map<String,Class<?>> map) Returns an Object representing the SQL structured type to which this SerialRef object refers.
void | setObject(Object obj) Sets the SQL structured type that this SerialRef object references to the given Object object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SerialRef

public SerialRef(Ref ref)
          throws SerialException,
                 SQLException
Constructs a SerialRef object from the given Ref object.

Parameters:
ref - a Ref object; cannot be null
Throws:
SQLException - if a database access occurs; if ref is null; or if the Ref object returns a null value base type name.
SerialException - if an error occurs serializing the Ref object
Method Detail

getBaseTypeName

public String getBaseTypeName()
                       throws SerialException
Returns a string describing the base type name of the Ref.

Specified by:
getBaseTypeName in interface Ref
Returns:
a string of the base type name of the Ref
Throws:
SerialException - in no Ref object has been set

getObject

public Object getObject(Map<String,Class<?>> map)
                 throws SerialException
Returns an Object representing the SQL structured type to which this SerialRef object refers. The attributes of the structured type are mapped according to the given type map.

Specified by:
getObject in interface Ref
Parameters:
map - a java.util.Map object containing zero or more entries, with each entry consisting of 1) a String giving the fully qualified name of a UDT and 2) the Class object for the SQLData implementation that defines how the UDT is to be mapped
Returns:
an object instance resolved from the Ref reference and mapped according to the supplied type map
Throws:
SerialException - if an error is encountered in the reference resolution
See Also:
Ref.setObject(java.lang.Object)

getObject

public Object getObject()
                 throws SerialException
Returns an Object representing the SQL structured type to which this SerialRef object refers.

Specified by:
getObject in interface Ref
Returns:
an object instance resolved from the Ref reference
Throws:
SerialException - if an error is encountered in the reference resolution
See Also:
Ref.setObject(java.lang.Object)

setObject

public void setObject(Object obj)
               throws SerialException
Sets the SQL structured type that this SerialRef object references to the given Object object.

Specified by:
setObject in interface Ref
Parameters:
obj - an Object representing the SQL structured type to be referenced
Throws:
SerialException - if an error is encountered generating the the structured type referenced by this SerialRef object
See Also:
Ref.getObject(),
Ref.getObject(Map),
PreparedStatement.setObject(int, Object),
CallableStatement.setObject(String, Object)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SerialStruct

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.serial
Class SerialStruct

java.lang.Object
    extended by  javax.sql.rowset.serial.SerialStruct
All Implemented Interfaces:
Serializable, Cloneable, Struct
public class SerialStruct
extends Object
implements Struct, Serializable, Cloneable

A serialized mapping in the Java programming language of an SQL structured type. Each attribute that is not already serialized is mapped to a serialized form, and if an attribute is itself a structured type, each of its attributes that is not already serialized is mapped to a serialized form.

In addition, the structured type is custom mapped to a class in the Java programming language if there is such a mapping, as are its attributes, if appropriate.

The SerialStruct class provides a constructor for creating an instance from a Struct object, a method for retrieving the SQL type name of the SQL structured type in the database, and methods for retrieving its attribute values.

See Also:
Serialized Form

Constructor Summary
SerialStruct(SQLData in, Map<String,Class<?>> map)
Constructs a SerialStruct object from the given SQLData object, using the given type map to custom map it to a class in the Java programming language.
SerialStruct(Struct in, Map<String,Class<?>> map)
Constructs a SerialStruct object from the given Struct object, using the given java.util.Map object for custom mapping the SQL structured type or any of its attributes that are SQL structured types.
Method Summary
Object[] | getAttributes() Retrieves an array of Object values containing the attributes of the SQL structured type that this SerialStruct object represents.
Object[] | getAttributes(Map<String,Class<?>> map) Retrieves the attributes for the SQL structured type that this SerialStruct represents as an array of Object values, using the given type map for custom mapping if appropriate.
String | getSQLTypeName() Retrieves the SQL type name for this SerialStruct object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SerialStruct

public SerialStruct(Struct in,
                    Map<String,Class<?>> map)
             throws SerialException
Constructs a SerialStruct object from the given Struct object, using the given java.util.Map object for custom mapping the SQL structured type or any of its attributes that are SQL structured types.

Parameters:
map - a java.util.Map object in which each entry consists of 1) a String object giving the fully qualified name of a UDT and 2) the Class object for the SQLData implementation that defines how the UDT is to be mapped
Throws:
SerialException - if an error occurs
See Also:
Struct

SerialStruct

public SerialStruct(SQLData in,
                    Map<String,Class<?>> map)
             throws SerialException
Constructs a SerialStruct object from the given SQLData object, using the given type map to custom map it to a class in the Java programming language. The type map gives the SQL type and the class to which it is mapped. The SQLData object defines the class to which the SQL type will be mapped.

Parameters:
in - an instance of the SQLData class that defines the mapping of the SQL structured type to one or more objects in the Java programming language
map - a java.util.Map object in which each entry consists of 1) a String object giving the fully qualified name of a UDT and 2) the Class object for the SQLData implementation that defines how the UDT is to be mapped
Throws:
SerialException - if an error occurs
Method Detail

getSQLTypeName

public String getSQLTypeName()
                      throws SerialException
Retrieves the SQL type name for this SerialStruct object. This is the name used in the SQL definition of the structured type

Specified by:
getSQLTypeName in interface Struct
Returns:
a String object representing the SQL type name for the SQL structured type that this SerialStruct object represents
Throws:
SerialException - if an error occurs

getAttributes

public Object[] getAttributes()
                       throws SerialException
Retrieves an array of Object values containing the attributes of the SQL structured type that this SerialStruct object represents.

Specified by:
getAttributes in interface Struct
Returns:
an array of Object values, with each element being an attribute of the SQL structured type that this SerialStruct object represents
Throws:
SerialException - if an error occurs

getAttributes

public Object[] getAttributes(Map<String,Class<?>> map)
                       throws SerialException
Retrieves the attributes for the SQL structured type that this SerialStruct represents as an array of Object values, using the given type map for custom mapping if appropriate.

Specified by:
getAttributes in interface Struct
Parameters:
map - a java.util.Map object in which each entry consists of 1) a String object giving the fully qualified name of a UDT and 2) the Class object for the SQLData implementation that defines how the UDT is to be mapped
Returns:
an array of Object values, with each element being an attribute of the SQL structured type that this SerialStruct object represents
Throws:
SerialException - if an error occurs
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SQLInputImpl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.serial
Class SQLInputImpl

java.lang.Object
    extended by  javax.sql.rowset.serial.SQLInputImpl
All Implemented Interfaces:
SQLInput
public class SQLInputImpl
extends Object
implements SQLInput

An input stream used for custom mapping user-defined types (UDTs). An SQLInputImpl object is an input stream that contains a stream of values that are the attributes of a UDT.

This class is used by the driver behind the scenes when the method getObject is called on an SQL structured or distinct type that has a custom mapping; a programmer never invokes SQLInputImpl methods directly. They are provided here as a convenience for those who write RowSet implementations.

The SQLInputImpl class provides a set of reader methods analogous to the ResultSet getter methods. These methods make it possible to read the values in an SQLInputImpl object.

The method wasNull is used to determine whether the the last value read was SQL NULL.

When the method getObject is called with an object of a class implementing the interface SQLData, the JDBC driver calls the method SQLData.getSQLType to determine the SQL type of the UDT being custom mapped. The driver creates an instance of SQLInputImpl, populating it with the attributes of the UDT. The driver then passes the input stream to the method SQLData.readSQL, which in turn calls the SQLInputImpl reader methods to read the attributes from the input stream.

See Also:
SQLData

Constructor Summary
SQLInputImpl(Object[] attributes, Map<String,Class<?>> map)
Creates an SQLInputImpl object initialized with the given array of attributes and the given type map.
Method Summary
Array | readArray() Reads an SQL ARRAY value from the stream and returns it as an Array object in the Java programming language.
InputStream | readAsciiStream() Returns the next attribute in this SQLInputImpl object as a stream of ASCII characters.
BigDecimal | readBigDecimal() Retrieves the next attribute in this SQLInputImpl object as a java.math.BigDecimal.
InputStream | readBinaryStream() Returns the next attribute in this SQLInputImpl object as a stream of uninterpreted bytes.
Blob | readBlob() Retrieves the BLOB value at the head of this SQLInputImpl object as a Blob object in the Java programming language.
boolean | readBoolean() Retrieves the next attribute in this SQLInputImpl object as a boolean in the Java programming language.
byte | readByte() Retrieves the next attribute in this SQLInputImpl object as a byte in the Java programming language.
byte[] | readBytes() Retrieves the next attribute in this SQLInputImpl object as an array of bytes.
Reader | readCharacterStream() Retrieves the next attribute in this SQLInputImpl object as a stream of Unicode characters.
Clob | readClob() Retrieves the CLOB value at the head of this SQLInputImpl object as a Clob object in the Java programming language.
Date | readDate() Retrieves the next attribute in this SQLInputImpl as a java.sql.Date object.
double | readDouble() Retrieves the next attribute in this SQLInputImpl object as a double in the Java programming language.
float | readFloat() Retrieves the next attribute in this SQLInputImpl object as a float in the Java programming language.
int | readInt() Retrieves the next attribute in this SQLInputImpl object as an int in the Java programming language.
long | readLong() Retrieves the next attribute in this SQLInputImpl object as a long in the Java programming language.
NClob | readNClob() Reads an SQL NCLOB value from the stream and returns it as a Clob object in the Java programming language.
String | readNString() Reads the next attribute in the stream and returns it as a String in the Java programming language.
Object | readObject() Retrieves the value at the head of this SQLInputImpl object as an Object in the Java programming language.
Ref | readRef() Retrieves the value at the head of this SQLInputImpl object as a Ref object in the Java programming language.
RowId | readRowId() Reads an SQL ROWID value from the stream and returns it as a RowId object in the Java programming language.
short | readShort() Retrieves the next attribute in this SQLInputImpl object as a short in the Java programming language.
SQLXML | readSQLXML() Reads an SQL XML value from the stream and returns it as a SQLXML object in the Java programming language.
String | readString() Retrieves the next attribute in this SQLInputImpl object as a String in the Java programming language.
Time | readTime() Retrieves the next attribute in this SQLInputImpl object as a java.sql.Time object.
Timestamp | readTimestamp() Retrieves the next attribute in this SQLInputImpl object as a java.sql.Timestamp object.
URL | readURL() Reads an SQL DATALINK value from the stream and returns it as an URL object in the Java programming language.
boolean | wasNull() Ascertains whether the last value read from this SQLInputImpl object was null.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SQLInputImpl

public SQLInputImpl(Object[] attributes,
                    Map<String,Class<?>> map)
             throws SQLException
Creates an SQLInputImpl object initialized with the given array of attributes and the given type map. If any of the attributes is a UDT whose name is in an entry in the type map, the attribute will be mapped according to the corresponding SQLData implementation.

Parameters:
attributes - an array of Object instances in which each element is an attribute of a UDT. The order of the attributes in the array is the same order in which the attributes were defined in the UDT definition.
map - a java.util.Map object containing zero or more entries, with each entry consisting of 1) a String giving the fully qualified name of the UDT and 2) the Class object for the SQLData implementation that defines how the UDT is to be mapped
Throws:
SQLException - if the attributes or the map is a null value
Method Detail

readString

public String readString()
                  throws SQLException
Retrieves the next attribute in this SQLInputImpl object as a String in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a SQLData implementation.

Specified by:
readString in interface SQLInput
Returns:
the next attribute in this SQLInputImpl object; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position or if there are no further values in the stream.

readBoolean

public boolean readBoolean()
                    throws SQLException
Retrieves the next attribute in this SQLInputImpl object as a boolean in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a SQLData implementation.

Specified by:
readBoolean in interface SQLInput
Returns:
the next attribute in this SQLInputImpl object; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position or if there are no further values in the stream.

readByte

public byte readByte()
              throws SQLException
Retrieves the next attribute in this SQLInputImpl object as a byte in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a SQLData implementation.

Specified by:
readByte in interface SQLInput
Returns:
the next attribute in this SQLInputImpl object; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position or if there are no further values in the stream

readShort

public short readShort()
                throws SQLException
Retrieves the next attribute in this SQLInputImpl object as a short in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a SQLData implementation.

Specified by:
readShort in interface SQLInput
Returns:
the next attribute in this SQLInputImpl object; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position or if there are no more values in the stream

readInt

public int readInt()
            throws SQLException
Retrieves the next attribute in this SQLInputImpl object as an int in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a SQLData implementation.

Specified by:
readInt in interface SQLInput
Returns:
the next attribute in this SQLInputImpl object; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position or if there are no more values in the stream

readLong

public long readLong()
              throws SQLException
Retrieves the next attribute in this SQLInputImpl object as a long in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a SQLData implementation.

Specified by:
readLong in interface SQLInput
Returns:
the next attribute in this SQLInputImpl object; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position or if there are no more values in the stream

readFloat

public float readFloat()
                throws SQLException
Retrieves the next attribute in this SQLInputImpl object as a float in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a SQLData implementation.

Specified by:
readFloat in interface SQLInput
Returns:
the next attribute in this SQLInputImpl object; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position or if there are no more values in the stream

readDouble

public double readDouble()
                  throws SQLException
Retrieves the next attribute in this SQLInputImpl object as a double in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a SQLData implementation.

Specified by:
readDouble in interface SQLInput
Returns:
the next attribute in this SQLInputImpl object; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position or if there are no more values in the stream

readBigDecimal

public BigDecimal readBigDecimal()
                          throws SQLException
Retrieves the next attribute in this SQLInputImpl object as a java.math.BigDecimal.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a SQLData implementation.

Specified by:
readBigDecimal in interface SQLInput
Returns:
the next attribute in this SQLInputImpl object; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position or if there are no more values in the stream

readBytes

public byte[] readBytes()
                 throws SQLException
Retrieves the next attribute in this SQLInputImpl object as an array of bytes.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a SQLData implementation.

Specified by:
readBytes in interface SQLInput
Returns:
the next attribute in this SQLInputImpl object; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position or if there are no more values in the stream

readDate

public Date readDate()
              throws SQLException
Retrieves the next attribute in this SQLInputImpl as a java.sql.Date object.

This method does not perform type-safe checking to determine if the returned type is the expected type; this responsibility is delegated to the UDT mapping as defined by a SQLData implementation.

Specified by:
readDate in interface SQLInput
Returns:
the next attribute in this SQLInputImpl object; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position or if there are no more values in the stream

readTime

public Time readTime()
              throws SQLException
Retrieves the next attribute in this SQLInputImpl object as a java.sql.Time object.

This method does not perform type-safe checking to determine if the returned type is the expected type as this responsibility is delegated to the UDT mapping as implemented by a SQLData implementation.

Specified by:
readTime in interface SQLInput
Returns:
the attribute; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position; or if there are no further values in the stream.

readTimestamp

public Timestamp readTimestamp()
                        throws SQLException
Retrieves the next attribute in this SQLInputImpl object as a java.sql.Timestamp object.

Specified by:
readTimestamp in interface SQLInput
Returns:
the attribute; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position; or if there are no further values in the stream.

readCharacterStream

public Reader readCharacterStream()
                           throws SQLException
Retrieves the next attribute in this SQLInputImpl object as a stream of Unicode characters.

This method does not perform type-safe checking to determine if the returned type is the expected type as this responsibility is delegated to the UDT mapping as implemented by a SQLData implementation.

Specified by:
readCharacterStream in interface SQLInput
Returns:
the attribute; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position; or if there are no further values in the stream.

readAsciiStream

public InputStream readAsciiStream()
                            throws SQLException
Returns the next attribute in this SQLInputImpl object as a stream of ASCII characters.

This method does not perform type-safe checking to determine if the returned type is the expected type as this responsibility is delegated to the UDT mapping as implemented by a SQLData implementation.

Specified by:
readAsciiStream in interface SQLInput
Returns:
the attribute; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position; or if there are no further values in the stream.

readBinaryStream

public InputStream readBinaryStream()
                             throws SQLException
Returns the next attribute in this SQLInputImpl object as a stream of uninterpreted bytes.

This method does not perform type-safe checking to determine if the returned type is the expected type as this responsibility is delegated to the UDT mapping as implemented by a SQLData implementation.

Specified by:
readBinaryStream in interface SQLInput
Returns:
the attribute; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position; or if there are no further values in the stream.

readObject

public Object readObject()
                  throws SQLException
Retrieves the value at the head of this SQLInputImpl object as an Object in the Java programming language. The actual type of the object returned is determined by the default mapping of SQL types to types in the Java programming language unless there is a custom mapping, in which case the type of the object returned is determined by this stream's type map.

The JDBC technology-enabled driver registers a type map with the stream before passing the stream to the application.

When the datum at the head of the stream is an SQL NULL, this method returns null. If the datum is an SQL structured or distinct type with a custom mapping, this method determines the SQL type of the datum at the head of the stream, constructs an object of the appropriate class, and calls the method SQLData.readSQL on that object. The readSQL method then calls the appropriate SQLInputImpl.readXXX methods to retrieve the attribute values from the stream.

Specified by:
readObject in interface SQLInput
Returns:
the value at the head of the stream as an Object in the Java programming language; null if the value is SQL NULL
Throws:
SQLException - if the read position is located at an invalid position; or if there are no further values in the stream.

readRef

public Ref readRef()
            throws SQLException
Retrieves the value at the head of this SQLInputImpl object as a Ref object in the Java programming language.

Specified by:
readRef in interface SQLInput
Returns:
a Ref object representing the SQL REF value at the head of the stream; if the value is SQL NULL return null
Throws:
SQLException - if the read position is located at an invalid position; or if there are no further values in the stream.

readBlob

public Blob readBlob()
              throws SQLException
Retrieves the BLOB value at the head of this SQLInputImpl object as a Blob object in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type as this responsibility is delegated to the UDT mapping as implemented by a SQLData implementation.

Specified by:
readBlob in interface SQLInput
Returns:
a Blob object representing the SQL BLOB value at the head of this stream; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position; or if there are no further values in the stream.

readClob

public Clob readClob()
              throws SQLException
Retrieves the CLOB value at the head of this SQLInputImpl object as a Clob object in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type as this responsibility is delegated to the UDT mapping as implemented by a SQLData implementation.

Specified by:
readClob in interface SQLInput
Returns:
a Clob object representing the SQL CLOB value at the head of the stream; if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position; or if there are no further values in the stream.

readArray

public Array readArray()
                throws SQLException
Reads an SQL ARRAY value from the stream and returns it as an Array object in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type as this responsibility is delegated to the UDT mapping as implemented by a SQLData implementation.

Specified by:
readArray in interface SQLInput
Returns:
an Array object representing the SQL ARRAY value at the head of the stream; * if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position; or if there are no further values in the stream.

wasNull

public boolean wasNull()
                throws SQLException
Ascertains whether the last value read from this SQLInputImpl object was null.

Specified by:
wasNull in interface SQLInput
Returns:
true if the SQL value read most recently was null; otherwise, false; by default it will return false
Throws:
SQLException - if an error occurs determining the last value read was a null value or not;

readURL

public URL readURL()
            throws SQLException
Reads an SQL DATALINK value from the stream and returns it as an URL object in the Java programming language.

This method does not perform type-safe checking to determine if the returned type is the expected type as this responsibility is delegated to the UDT mapping as implemented by a SQLData implementation.

Specified by:
readURL in interface SQLInput
Returns:
an URL object representing the SQL DATALINK value at the head of the stream; * if the value is SQL NULL, return null
Throws:
SQLException - if the read position is located at an invalid position; or if there are no further values in the stream.

readNClob

public NClob readNClob()
                throws SQLException
Reads an SQL NCLOB value from the stream and returns it as a Clob object in the Java programming language.

Specified by:
readNClob in interface SQLInput
Returns:
a NClob object representing data of the SQL NCLOB value at the head of the stream; null if the value read is SQL NULL
Throws:
SQLException - if a database access error occurs

readNString

public String readNString()
                   throws SQLException
Reads the next attribute in the stream and returns it as a String in the Java programming language. It is intended for use when accessing NCHAR,NVARCHAR and LONGNVARCHAR columns.

Specified by:
readNString in interface SQLInput
Returns:
the attribute; if the value is SQL NULL, returns null
Throws:
SQLException - if a database access error occurs

readSQLXML

public SQLXML readSQLXML()
                  throws SQLException
Reads an SQL XML value from the stream and returns it as a SQLXML object in the Java programming language.

Specified by:
readSQLXML in interface SQLInput
Returns:
a SQLXML object representing data of the SQL XML value at the head of the stream; null if the value read is SQL NULL
Throws:
SQLException - if a database access error occurs

readRowId

public RowId readRowId()
                throws SQLException
Reads an SQL ROWID value from the stream and returns it as a RowId object in the Java programming language.

Specified by:
readRowId in interface SQLInput
Returns:
a RowId object representing data of the SQL ROWID value at the head of the stream; null if the value read is SQL NULL
Throws:
SQLException - if a database access error occurs
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SQLOutputImpl

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.serial
Class SQLOutputImpl

java.lang.Object
    extended by  javax.sql.rowset.serial.SQLOutputImpl
All Implemented Interfaces:
SQLOutput
public class SQLOutputImpl
extends Object
implements SQLOutput

The output stream for writing the attributes of a custom-mapped user-defined type (UDT) back to the database. The driver uses this interface internally, and its methods are never directly invoked by an application programmer.

When an application calls the method PreparedStatement.setObject, the driver checks to see whether the value to be written is a UDT with a custom mapping. If it is, there will be an entry in a type map containing the Class object for the class that implements SQLData for this UDT. If the value to be written is an instance of SQLData, the driver will create an instance of SQLOutputImpl and pass it to the method SQLData.writeSQL. The method writeSQL in turn calls the appropriate SQLOutputImpl.writeXXX methods to write data from the SQLData object to the SQLOutputImpl output stream as the representation of an SQL user-defined type.

Constructor Summary
SQLOutputImpl(Vector<?> attributes, Map<String,?> map)
Creates a new SQLOutputImpl object initialized with the given vector of attributes and type map.
Method Summary
void | writeArray(Array x) Writes an Array object in the Java programming language to this SQLOutputImpl object.
void | writeAsciiStream(InputStream x) Writes a stream of ASCII characters to this SQLOutputImpl object.
void | writeBigDecimal(BigDecimal x) Writes a java.math.BigDecimal object in the Java programming language to this SQLOutputImpl object.
void | writeBinaryStream(InputStream x) Writes a stream of uninterpreted bytes to this SQLOutputImpl object.
void | writeBlob(Blob x) Writes a Blob object in the Java programming language to this SQLOutputImpl object.
void | writeBoolean(boolean x) Writes a boolean in the Java programming language to this SQLOutputImpl object.
void | writeByte(byte x) Writes a byte in the Java programming language to this SQLOutputImpl object.
void | writeBytes(byte[] x) Writes an array of bytes in the Java programming language to this SQLOutputImpl object.
void | writeCharacterStream(Reader x) Writes a stream of Unicode characters to this SQLOutputImpl object.
void | writeClob(Clob x) Writes a Clob object in the Java programming language to this SQLOutputImpl object.
void | writeDate(Date x) Writes a java.sql.Date object in the Java programming language to this SQLOutputImpl object.
void | writeDouble(double x) Writes a double in the Java programming language to this SQLOutputImpl object.
void | writeFloat(float x) Writes a float in the Java programming language to this SQLOutputImpl object.
void | writeInt(int x) Writes an int in the Java programming language to this SQLOutputImpl object.
void | writeLong(long x) Writes a long in the Java programming language to this SQLOutputImpl object.
void | writeNClob(NClob x) Writes an SQL NCLOB value to the stream.
void | writeNString(String x) Writes the next attribute to the stream as a String in the Java programming language.
void | writeObject(SQLData x) Writes to the stream the data contained in the given SQLData object.
void | writeRef(Ref x) Writes a Ref object in the Java programming language to this SQLOutputImpl object.
void | writeRowId(RowId x) Writes an SQL ROWID value to the stream.
void | writeShort(short x) Writes a short in the Java programming language to this SQLOutputImpl object.
void | writeSQLXML(SQLXML x) Writes an SQL XML value to the stream.
void | writeString(String x) Writes a String in the Java programming language to this SQLOutputImpl object.
void | writeStruct(Struct x) Writes a Struct object in the Java programming language to this SQLOutputImpl object.
void | writeTime(Time x) Writes a java.sql.Time object in the Java programming language to this SQLOutputImpl object.
void | writeTimestamp(Timestamp x) Writes a java.sql.Timestamp object in the Java programming language to this SQLOutputImpl object.
void | writeURL(URL url) Writes an java.sql.Type.DATALINK object in the Java programming language to this SQLOutputImpl object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SQLOutputImpl

public SQLOutputImpl(Vector<?> attributes,
                     Map<String,?> map)
              throws SQLException
Creates a new SQLOutputImpl object initialized with the given vector of attributes and type map. The driver will use the type map to determine which SQLData.writeSQL method to invoke. This method will then call the appropriate SQLOutputImpl writer methods in order and thereby write the attributes to the new output stream.

Parameters:
attributes - a Vector object containing the attributes of the UDT to be mapped to one or more objects in the Java programming language
map - a java.util.Map object containing zero or more entries, with each entry consisting of 1) a String giving the fully qualified name of a UDT and 2) the Class object for the SQLData implementation that defines how the UDT is to be mapped
Throws:
SQLException - if the attributes or the map is a null value
Method Detail

writeString

public void writeString(String x)
                 throws SQLException
Writes a String in the Java programming language to this SQLOutputImpl object. The driver converts it to an SQL CHAR, VARCHAR, or LONGVARCHAR before returning it to the database.

Specified by:
writeString in interface SQLOutput
Parameters:
x - the value to pass to the database
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeBoolean

public void writeBoolean(boolean x)
                  throws SQLException
Writes a boolean in the Java programming language to this SQLOutputImpl object. The driver converts it to an SQL BIT before returning it to the database.

Specified by:
writeBoolean in interface SQLOutput
Parameters:
x - the value to pass to the database
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeByte

public void writeByte(byte x)
               throws SQLException
Writes a byte in the Java programming language to this SQLOutputImpl object. The driver converts it to an SQL BIT before returning it to the database.

Specified by:
writeByte in interface SQLOutput
Parameters:
x - the value to pass to the database
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeShort

public void writeShort(short x)
                throws SQLException
Writes a short in the Java programming language to this SQLOutputImpl object. The driver converts it to an SQL SMALLINT before returning it to the database.

Specified by:
writeShort in interface SQLOutput
Parameters:
x - the value to pass to the database
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeInt

public void writeInt(int x)
              throws SQLException
Writes an int in the Java programming language to this SQLOutputImpl object. The driver converts it to an SQL INTEGER before returning it to the database.

Specified by:
writeInt in interface SQLOutput
Parameters:
x - the value to pass to the database
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeLong

public void writeLong(long x)
               throws SQLException
Writes a long in the Java programming language to this SQLOutputImpl object. The driver converts it to an SQL BIGINT before returning it to the database.

Specified by:
writeLong in interface SQLOutput
Parameters:
x - the value to pass to the database
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeFloat

public void writeFloat(float x)
                throws SQLException
Writes a float in the Java programming language to this SQLOutputImpl object. The driver converts it to an SQL REAL before returning it to the database.

Specified by:
writeFloat in interface SQLOutput
Parameters:
x - the value to pass to the database
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeDouble

public void writeDouble(double x)
                 throws SQLException
Writes a double in the Java programming language to this SQLOutputImpl object. The driver converts it to an SQL DOUBLE before returning it to the database.

Specified by:
writeDouble in interface SQLOutput
Parameters:
x - the value to pass to the database
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeBigDecimal

public void writeBigDecimal(BigDecimal x)
                     throws SQLException
Writes a java.math.BigDecimal object in the Java programming language to this SQLOutputImpl object. The driver converts it to an SQL NUMERIC before returning it to the database.

Specified by:
writeBigDecimal in interface SQLOutput
Parameters:
x - the value to pass to the database
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeBytes

public void writeBytes(byte[] x)
                throws SQLException
Writes an array of bytes in the Java programming language to this SQLOutputImpl object. The driver converts it to an SQL VARBINARY or LONGVARBINARY before returning it to the database.

Specified by:
writeBytes in interface SQLOutput
Parameters:
x - the value to pass to the database
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeDate

public void writeDate(Date x)
               throws SQLException
Writes a java.sql.Date object in the Java programming language to this SQLOutputImpl object. The driver converts it to an SQL DATE before returning it to the database.

Specified by:
writeDate in interface SQLOutput
Parameters:
x - the value to pass to the database
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeTime

public void writeTime(Time x)
               throws SQLException
Writes a java.sql.Time object in the Java programming language to this SQLOutputImpl object. The driver converts it to an SQL TIME before returning it to the database.

Specified by:
writeTime in interface SQLOutput
Parameters:
x - the value to pass to the database
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeTimestamp

public void writeTimestamp(Timestamp x)
                    throws SQLException
Writes a java.sql.Timestamp object in the Java programming language to this SQLOutputImpl object. The driver converts it to an SQL TIMESTAMP before returning it to the database.

Specified by:
writeTimestamp in interface SQLOutput
Parameters:
x - the value to pass to the database
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeCharacterStream

public void writeCharacterStream(Reader x)
                          throws SQLException
Writes a stream of Unicode characters to this SQLOutputImpl object. The driver will do any necessary conversion from Unicode to the database CHAR format.

Specified by:
writeCharacterStream in interface SQLOutput
Parameters:
x - the value to pass to the database
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeAsciiStream

public void writeAsciiStream(InputStream x)
                      throws SQLException
Writes a stream of ASCII characters to this SQLOutputImpl object. The driver will do any necessary conversion from ASCII to the database CHAR format.

Specified by:
writeAsciiStream in interface SQLOutput
Parameters:
x - the value to pass to the database
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeBinaryStream

public void writeBinaryStream(InputStream x)
                       throws SQLException
Writes a stream of uninterpreted bytes to this SQLOutputImpl object.

Specified by:
writeBinaryStream in interface SQLOutput
Parameters:
x - the value to pass to the database
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeObject

public void writeObject(SQLData x)
                 throws SQLException
Writes to the stream the data contained in the given SQLData object. When the SQLData object is null, this method writes an SQL NULL to the stream. Otherwise, it calls the SQLData.writeSQL method of the given object, which writes the object's attributes to the stream.

The implementation of the method SQLData.writeSQ calls the appropriate SQLOutputImpl.writeXXX method(s) for writing each of the object's attributes in order. The attributes must be read from an SQLInput input stream and written to an SQLOutputImpl output stream in the same order in which they were listed in the SQL definition of the user-defined type.

Specified by:
writeObject in interface SQLOutput
Parameters:
x - the object representing data of an SQL structured or distinct type
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeRef

public void writeRef(Ref x)
              throws SQLException
Writes a Ref object in the Java programming language to this SQLOutputImpl object. The driver converts it to a serializable SerialRef SQL REF value before returning it to the database.

Specified by:
writeRef in interface SQLOutput
Parameters:
x - an object representing an SQL REF value
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeBlob

public void writeBlob(Blob x)
               throws SQLException
Writes a Blob object in the Java programming language to this SQLOutputImpl object. The driver converts it to a serializable SerialBlob SQL BLOB value before returning it to the database.

Specified by:
writeBlob in interface SQLOutput
Parameters:
x - an object representing an SQL BLOB value
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeClob

public void writeClob(Clob x)
               throws SQLException
Writes a Clob object in the Java programming language to this SQLOutputImpl object. The driver converts it to a serializable SerialClob SQL CLOB value before returning it to the database.

Specified by:
writeClob in interface SQLOutput
Parameters:
x - an object representing an SQL CLOB value
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeStruct

public void writeStruct(Struct x)
                 throws SQLException
Writes a Struct object in the Java programming language to this SQLOutputImpl object. The driver converts this value to an SQL structured type before returning it to the database.

This method should be used when an SQL structured type has been mapped to a Struct object in the Java programming language (the standard mapping). The method writeObject should be used if an SQL structured type has been custom mapped to a class in the Java programming language.

Specified by:
writeStruct in interface SQLOutput
Parameters:
x - an object representing the attributes of an SQL structured type
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeArray

public void writeArray(Array x)
                throws SQLException
Writes an Array object in the Java programming language to this SQLOutputImpl object. The driver converts this value to a serializable SerialArray SQL ARRAY value before returning it to the database.

Specified by:
writeArray in interface SQLOutput
Parameters:
x - an object representing an SQL ARRAY value
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeURL

public void writeURL(URL url)
              throws SQLException
Writes an java.sql.Type.DATALINK object in the Java programming language to this SQLOutputImpl object. The driver converts this value to a serializable SerialDatalink SQL DATALINK value before return it to the database.

Specified by:
writeURL in interface SQLOutput
Parameters:
url - an object representing a SQL DATALINK value
Throws:
SQLException - if the SQLOutputImpl object is in use by a SQLData object attempting to write the attribute values of a UDT to the database.

writeNString

public void writeNString(String x)
                  throws SQLException
Writes the next attribute to the stream as a String in the Java programming language. The driver converts this to a SQL NCHAR or NVARCHAR or LONGNVARCHAR value (depending on the argument's size relative to the driver's limits on NVARCHAR values) when it sends it to the stream.

Specified by:
writeNString in interface SQLOutput
Parameters:
x - the value to pass to the database
Throws:
SQLException - if a database access error occurs
Since:
1.6

writeNClob

public void writeNClob(NClob x)
                throws SQLException
Writes an SQL NCLOB value to the stream.

Specified by:
writeNClob in interface SQLOutput
Parameters:
x - a NClob object representing data of an SQL NCLOB value
Throws:
SQLException - if a database access error occurs
Since:
1.6

writeRowId

public void writeRowId(RowId x)
                throws SQLException
Writes an SQL ROWID value to the stream.

Specified by:
writeRowId in interface SQLOutput
Parameters:
x - a RowId object representing data of an SQL ROWID value
Throws:
SQLException - if a database access error occurs
Since:
1.6

writeSQLXML

public void writeSQLXML(SQLXML x)
                 throws SQLException
Writes an SQL XML value to the stream.

Specified by:
writeSQLXML in interface SQLOutput
Parameters:
x - a SQLXML object representing data of an SQL XML value
Throws:
SQLException - if a database access error occurs
Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


spi

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.sql.rowset.spi

The standard classes and interfaces that a third party vendor has to use in its implementation of a synchronization provider.

See:
Description

Interface Summary
SyncResolver | Defines a framework that allows applications to use a manual decision tree to decide what should be done when a synchronization conflict occurs.
TransactionalWriter | A specialized interface that facilitates an extension of the standard SyncProvider abstract class so that it has finer grained transaction control.
XmlReader | A specialized interface that facilitates an extension of the SyncProvider abstract class for XML orientated synchronization providers.
XmlWriter | A specialized interface that facilitates an extension of the SyncProvider abstract class for XML orientated synchronization providers.

Class Summary
SyncFactory | The Service Provider Interface (SPI) mechanism that generates SyncProvider instances to be used by disconnected RowSet objects.
SyncProvider | The synchronization mechanism that provides reader/writer capabilities for disconnected RowSet objects.

Exception Summary
SyncFactoryException | Indicates an error with SyncFactory mechanism.
SyncProviderException | Indicates an error with the SyncProvider mechanism.

Package javax.sql.rowset.spi Description

The standard classes and interfaces that a third party vendor has to use in its implementation of a synchronization provider. These classes and interfaces are referred to as the Service Provider Interface (SPI). A vendor may have its implementation included on the JDBC web page that lists available SyncProvider implementations by sending email to jdbc@sun.com. Doing this helps make developers aware of the implementation. To make it possible for a RowSet object to use an implementation, the vendor must register it with the SyncFactory singleton. (See the class comment for SyncProvider for a full explanation of the registration process and the naming convention to be used.)

Table of Contents

  • 1.0 Package Specification
  • 2.0 Service Provider Architecture
  • 3.0 Implementer's Guide
  • 4.0 Resolving Synchronization Conflicts
  • 5.0 Related Specifications
  • 6.0 Related Documentation

1.0 Package Specification

The following classes and interfaces make up the javax.sql.rowset.spi package:

  • SyncFactory
  • SyncProvider
  • SyncFactoryException
  • SyncProviderException
  • SyncResolver
  • XmlReader
  • XmlWriter
  • TransactionalWriter
The following interfaces, in the javax.sql package, are also part of the SPI:
  • RowSetReader
  • RowSetWriter

A SyncProvider implementation provides a disconnected RowSet object with the mechanisms for reading data into it and for writing data that has been modified in it back to the underlying data source. A reader, a RowSetReader or XMLReader object, reads data into a RowSet object when the CachedRowSet methods execute or populate are called. A writer, a RowSetWriter or XMLWriter object, writes changes back to the underlying data source when the CachedRowSet method acceptChanges is called.

The process of writing changes in a RowSet object to its data source is known as synchronization. The SyncProvider implementation that a RowSet object is using determines the level of synchronization that the RowSet object's writer uses. The various levels of synchronization are referred to as grades.

The lower grades of synchronization are known as optimistic concurrency levels because they optimistically assume that there will be no conflicts or very few conflicts. A conflict exists when the same data modified in the RowSet object has also been modified in the data source. Using the optimistic concurrency model means that if there is a conflict, modifications to either the data source or the RowSet object will be lost.

Higher grades of synchronization are called pessimistic because they assume that others will be accessing the data source and making modifications. These grades set varying levels of locks to increase the chances that no conflicts occur.

The lowest level of synchronization is simply writing any changes made to the RowSet object to its underlying data source. The writer does nothing to check for conflicts. If there is a conflict and the data source values are overwritten, the changes other parties have made by to the data source are lost.

The RIXMLProvider implementation uses the lowest level of synchronization and just writes RowSet changes to the data source. This is true because typically XML data sources do not enable transaction techniques for maintaining the integrity of data. However, specific standards groups have considered offering XML-based synchronization. For details, see

     http://www.syncml.org

For the the next level up, the writer checks to see if there are any conflicts, and if there are, it does not write anything to the data source. The problem with this concurrency level is that if another party has modified the corresponding data in the data source since the RowSet object got its data, the changes made to the RowSet object are lost. The RIOptimisticProvider implementation uses this level of synchronization.

At higher levels of synchronization, referred to as pessimistic concurrency, the writer take steps to avoid conflicts by setting locks. Setting locks can vary from setting a lock on a single row to setting a lock on a table or the entire data source. The level of synchronization is therefore a tradeoff between the ability of users to access the data source concurrently and the ability of the writer to keep the data in the RowSet object and its data source synchronized.

It is a requirement that all disconnected RowSet objects (CachedRowSet, FilteredRowSet, JoinRowSet, and WebRowSet objects) obtain their SyncProvider objects from the SyncFactory mechanism.

The reference implementation (RI) provides two synchronization providers.

  • RIOptimisticProvider
    The default provider that the SyncFactory instance will supply to a disconnected RowSet object when no provider implementation is specified.
    This synchronization provider uses an optimistic concurrency model, assuming that there will be few conflicts among users who are accessing the same data in a database. It avoids using locks; rather, it checks to see if there is a conflict before trying to synchronize the RowSet object and the data source. If there is a conflict, it does nothing, meaning that changes to the RowSet object are not persisted to the data source.
  • RIXMLProvider
    A synchronization provider that can be used with a WebRowSet object, which is a rowset that can be written in XML format or read from XML format. The RIXMLProvider implementation does no checking at all for conflicts and simply writes any updated data in the WebRowSet object to the underlying data source. WebRowSet objects use this provider when they are dealing with XML data.
These SyncProvider implementations are bundled with the reference implementation, which makes them always available to RowSet implementations. SyncProvider implementations make themselves available by being registered with the SyncFactory singleton. When a RowSet object requests a provider, by specifying it in the constructor or as an argument to the CachedRowSet method setSyncProvider, the SyncFactory singleton checks to see if the requested provider has been registered with it. If it has, the SyncFactory creates an instance of it and passes it to the requesting RowSet object. If the SyncProvider implementation that is specified has not been registered, the SyncFactory singleton causes a SyncFactoryException object to be thrown. If no provider is specified, the SyncFactory singleton will create an instance of the default provider implementation, RIOptimisticProvider, and pass it to the requesting RowSet object.

If a WebRowSet object does not specify a provider in its constructor, the SyncFactory will give it an instance of RIOptimisticProvider. However, the constructor for WebRowSet is implemented to set the provider to the RIXMLProvider, which reads and writes a RowSet object in XML format.

See the SyncProvider class specification for further details.

Vendors may develop a SyncProvider implementation with any one of the possible levels of synchronization, thus giving RowSet objects a choice of synchronization mechanisms. A vendor can make its implementation available by registering the fully qualified class name with Sun Microsystems at jdbc@sun.com. This process is discussed in further detail below.

2.0 Service Provider Interface Architecture

    2.1 Overview

    The Service Provider Interface provides a pluggable mechanism by which SyncProvider implementations can be registered and then generated when required. The lazy reference mechanism employed by the SyncFactory limits unnecessary resource consumption by not creating an instance until it is required by a disconnected RowSet object. The SyncFactory class also provides a standard API to configure logging options and streams that may be provided by a particular SyncProvider implementation.

    2.2 Registering with the SyncFactory

    A third party SyncProvider implementation must be registered with the SyncFactory in order for a disconnected RowSet object to obtain it and thereby use its javax.sql.RowSetReader and javax.sql.RowSetWriter implementations. The following registration mechanisms are available to all SyncProvider implementations:

    • System properties - Properties set at the command line. These properties are set at run time and apply system-wide per invocation of the Java application. See the section "Related Documentation" further related information.

    • Property Files - Properties specified in a standard property file. This can be specified using a System Property or by modifying a standard property file located in the platform run-time. The reference implementation of this technology includes a standard property file than can be edited to add additional SyncProvider objects.

    • JNDI Context - Available providers can be registered on a JNDI context. The SyncFactory will attempt to load SyncProvider objects bound to the context and register them with the factory. This context must be supplied to the SyncFactory for the mechanism to function correctly.

    Details on how to specify the system properties or properties in a property file and how to configure the JNDI Context are explained in detail in the SyncFactory class description.

    2.3 SyncFactory Provider Instance Generation Policies

    The SyncFactory generates a requested SyncProvider object if the provider has been correctly registered. The following policies are adhered to when either a disconnected RowSet object is instantiated with a specified SyncProvider implementation or is reconfigured at runtime with an alternative SyncProvider object.

    • If a SyncProvider object is specified and the SyncFactory contains no reference to the provider, a SyncFactoryException is thrown.

    • If a SyncProvider object is specified and the SyncFactory contains a reference to the provider, the requested provider is supplied.

    • If no SyncProvider object is specified, the reference implementation provider RIOptimisticProvider is supplied.

    These policies are explored in more detail in the SyncFactory class.

  • 3.0 SyncProvider Implementer's Guide

      3.1 Requirements

      A compliant SyncProvider implementation that is fully pluggable into the SyncFactory must extend and implement all abstract methods in the SyncProvider class. In addition, an implementation must determine the grade, locking and updatable view capabilities defined in the SyncProvider class definition. One or more of the SyncProvider description criteria must be supported. It is expected that vendor implementations will offer a range of grade, locking, and updatable view capabilities.

      Furthermore, the SyncProvider naming convention must be followed as detailed in the SyncProvider class description.

      3.2 Grades

      JSR 114 defines a set of grades to describe the quality of synchronization a SyncProvider object can offer a disconnected RowSet object. These grades are listed from the lowest quality of service to the highest.

      • GRADE_NONE - No synchronization with the originating data source is provided. A SyncProvider implementation returning this grade will simply attempt to write any data that has changed in the RowSet object to the underlying data source, overwriting whatever is there. No attempt is made to compare original values with current values to see if there is a conflict. The RIXMLProvider is implemented with this grade.

      • GRADE_CHECK_MODIFIED_AT_COMMIT - A low grade of optimistic synchronization. A SyncProvider implementation returning this grade will check for conflicts in rows that have changed between the last synchronization and the current synchronization under way. Any changes in the originating data source that have been modified will not be reflected in the disconnected RowSet object. If there are no conflicts, changes in the RowSet object will be written to the data source. If there are conflicts, no changes are written. The RIOptimisticProvider implementation uses this grade.

      • GRADE_CHECK_ALL_AT_COMMIT - A high grade of optimistic synchronization. A SyncProvider implementation returning this grade will check all rows, including rows that have not changed in the disconnected RowSet object. In this way, any changes to rows in the underlying data source will be reflected in the disconnected RowSet object when the synchronization finishes successfully.

      • GRADE_LOCK_WHEN_MODIFIED - A pessimistic grade of synchronization. SyncProvider implementations returning this grade will lock the row in the originating data source that corresponds to the row being changed in the RowSet object to reduce the possibility of other processes modifying the same data in the data source.

      • GRADE_LOCK_WHEN_LOADED - A higher pessimistic synchronization grade. A SyncProvider implementation returning this grade will lock the entire view and/or table affected by the original query used to populate a RowSet object.

      3.3 Locks

      JSR 114 defines a set of constants that specify whether any locks have been placed on a RowSet object's underlying data source and, if so, on which constructs the locks are placed. These locks will remain on the data source while the RowSet object is disconnected from the data source.

      These constants should be considered complementary to the grade constants. The default setting for the majority of grade settings requires that no data source locks remain when a RowSet object is disconnected from its data source. The grades GRADE_LOCK_WHEN_MODIFIED and GRADE_LOCK_WHEN_LOADED allow a disconnected RowSet object to have a fine-grained control over the degree of locking.

      • DATASOURCE_NO_LOCK - No locks remain on the originating data source. This is the default lock setting for all SyncProvider implementations unless otherwise directed by a RowSet object.

      • DATASOURCE_ROW_LOCK - A lock is placed on the rows that are touched by the original SQL query used to populate the RowSet object.

      • DATASOURCE_TABLE_LOCK - A lock is placed on all tables that are touched by the query that was used to populate the RowSet object.

      • DATASOURCE_DB_LOCK A lock is placed on the entire data source that is used by the RowSet object.

      3.4 Updatable Views

      A RowSet object may be populated with data from an SQL VIEW. The following constants indicate whether a SyncProvider object can update data in the table or tables from which the VIEW was derived.

      • UPDATABLE_VIEW_SYNC Indicates that a SyncProvider implementation supports synchronization to the table or tables from which the SQL VIEW used to populate a a RowSet object is derived.

      • NONUPDATABLE_VIEW_SYNC Indicates that a SyncProvider implementation does not support synchronization to the table or tables from which the SQL VIEW used to populate a RowSet object is derived.

      3.5 Usage of SyncProvider Grading and Locking

      In the example below, the reference CachedRowSetImpl implementation reconfigures its current SyncProvider object by calling the setSyncProvider method.

          CachedRowSetImpl crs = new CachedRowSetImpl();
    crs.setSyncProvider("com.foo.bar.HASyncProvider");
      An application can retrieve the SyncProvider object currently in use by a disconnected RowSet object. It can also retrieve the grade of synchronization with which the provider was implemented and the degree of locking currently in use. In addition, an application has the flexibility to set the degree of locking to be used, which can increase the possibilities for successful synchronization. These operation are shown in the following code fragment.
          SyncProvider sync = crs.getSyncProvider();

    switch (sync.getProviderGrade()) {
    case: SyncProvider.GRADE_CHECK_ALL_AT_COMMIT
         //A high grade of optimistic synchronization
    break;
    case: SyncProvider.GRADE_CHECK_MODIFIED_AT_COMMIT
         //A low grade of optimistic synchronization
    break;
    case: SyncProvider.GRADE_LOCK_WHEN_LOADED
         // A pessimistic synchronization grade
    break;
    case: SyncProvider.GRADE_LOCK_WHEN_MODIFIED
         // A pessimistic synchronization grade
    break;
    case: SyncProvider.GRADE_NONE
      // No synchronization with the originating data source provided
    break;
    }

    switch (sync.getDataSourcLock() {
      case: SyncProvider.DATASOURCE_DB_LOCK
       // A lock is placed on the entire datasource that is used by the
       // RowSet object
       break;

      case: SyncProvider.DATASOURCE_NO_LOCK
       // No locks remain on the  originating data source.
      break;

      case: SyncProvider.DATASOURCE_ROW_LOCK
       // A lock is placed on the rows that are  touched by the original
       // SQL statement used to populate
       // the RowSet object that is using the SyncProvider
       break;

      case: DATASOURCE_TABLE_LOCK
       // A lock is placed on  all tables that are touched by the original
       // SQL statement used to populated
       // the RowSet object that is using the SyncProvider
       break;
      It is also possible using the static utility method in the SyncFactory class to determine the list of SyncProvider implementations currently registered with the SyncFactory.
              Enumeration e = SyncFactory.getRegisteredProviders();

    4.0 Resolving Synchronization Conflicts

    The interface SyncResolver provides a way for an application to decide manually what to do when a conflict occurs. When the CachedRowSet method acceptChanges finishes and has detected one or more conflicts, it throws a SyncProviderException object. An application can catch the exception and have it retrieve a SyncResolver object by calling the method SyncProviderException.getSyncResolver().

    A SyncResolver object, which is a special kind of CachedRowSet object or a JdbcRowSet object that has implemented the SyncResolver interface, examines the conflicts row by row. It is a duplicate of the RowSet object being synchronized except that it contains only the data from the data source this is causing a conflict. All of the other column values are set to null. To navigate from one conflict value to another, a SyncResolver object provides the methods nextConflict and previousConflict.

    The SyncResolver interface also provides methods for doing the following:

    • finding out whether the conflict involved an update, a delete, or an insert
    • getting the value in the data source that caused the conflict
    • setting the value that should be in the data source if it needs to be changed or setting the value that should be in the RowSet object if it needs to be changed

    When the CachedRowSet method acceptChanges is called, it delegates to the RowSet object's SyncProvider object. How the writer provided by that SyncProvider object is implemented determines what level (grade) of checking for conflicts will be done. After all checking for conflicts is completed and one or more conflicts has been found, the method acceptChanges throws a SyncProviderException object. The application can catch the exception and use it to obtain a SyncResolver object.

    The application can then use SyncResolver methods to get information about each conflict and decide what to do. If the application logic or the user decides that a value in the RowSet object should be the one to persist, the application or user can overwrite the data source value with it.

    The comment for the SyncResolver interface has more detail.

    5.0 Related Specifications

    • JNDI 1.3
    • Java Logging APIs

    6.0 Related Documentation

    • System properties
    • Resource Files
    • DataSource for JDBC Connections

    Overview Package Class Use Tree Deprecated Index Help
            Java™ Platform
    Standard Ed. 6
    PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.sql.rowset.spi Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.sql.rowset.spi

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.sql.rowset.spi.SyncFactory
    • javax.sql.rowset.spi.SyncProvider
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.sql.SQLException (implements java.lang.Iterable<T>)
          • javax.sql.rowset.spi.SyncFactoryException
          • javax.sql.rowset.spi.SyncProviderException

Interface Hierarchy

  • javax.sql.RowSetReader
    • javax.sql.rowset.spi.XmlReader
  • javax.sql.RowSetWriter
    • javax.sql.rowset.spi.TransactionalWriter
    • javax.sql.rowset.spi.XmlWriter
  • java.sql.Wrapper
    • java.sql.ResultSet
      • javax.sql.RowSet
        • javax.sql.rowset.spi.SyncResolver
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.sql.rowset.spi

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.sql.rowset.spi

Packages that use javax.sql.rowset.spi
javax.sql.rowset | Standard interfaces and base classes for JDBC RowSet implementations.
javax.sql.rowset.spi | The standard classes and interfaces that a third party vendor has to use in its implementation of a synchronization provider.

Classes in javax.sql.rowset.spi used by javax.sql.rowset
SyncProvider
The synchronization mechanism that provides reader/writer capabilities for disconnected RowSet objects.
SyncProviderException
Indicates an error with the SyncProvider mechanism.

Classes in javax.sql.rowset.spi used by javax.sql.rowset.spi
SyncFactory
The Service Provider Interface (SPI) mechanism that generates SyncProvider instances to be used by disconnected RowSet objects.
SyncFactoryException
Indicates an error with SyncFactory mechanism.
SyncProvider
The synchronization mechanism that provides reader/writer capabilities for disconnected RowSet objects.
SyncProviderException
Indicates an error with the SyncProvider mechanism.
SyncResolver
Defines a framework that allows applications to use a manual decision tree to decide what should be done when a synchronization conflict occurs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.rowset.spi.SyncFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.rowset.spi.SyncFactory

Packages that use SyncFactory
javax.sql.rowset.spi The standard classes and interfaces that a third party vendor has to use in its implementation of a synchronization provider.

Uses of SyncFactory in javax.sql.rowset.spi

Methods in javax.sql.rowset.spi that return SyncFactory
static SyncFactory SyncFactory.getSyncFactory()
Returns the SyncFactory singleton.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.rowset.spi.SyncFactoryException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.rowset.spi.SyncFactoryException

Packages that use SyncFactoryException
javax.sql.rowset.spi The standard classes and interfaces that a third party vendor has to use in its implementation of a synchronization provider.

Uses of SyncFactoryException in javax.sql.rowset.spi

Methods in javax.sql.rowset.spi that throw SyncFactoryException
static SyncProvider | SyncFactory.getInstance(String providerID) Returns the SyncProvider instance identified by providerID.
static Logger | SyncFactory.getLogger() Returns the logging object for applications to retrieve synchronization events posted by SyncProvider implementations.
static Enumeration<SyncProvider> | SyncFactory.getRegisteredProviders() Returns an Enumeration of currently registered synchronization providers.
static void | SyncFactory.registerProvider(String providerID) Adds the the given synchronization provider to the factory register.
static void | SyncFactory.setJNDIContext(Context ctx) Sets the initial JNDI context from which SyncProvider implementations can be retrieved from a JNDI namespace
static void | SyncFactory.unregisterProvider(String providerID) Removes the designated currently registered synchronization provider from the Factory SPI register.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.rowset.spi.SyncProvider

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.rowset.spi.SyncProvider

Packages that use SyncProvider
javax.sql.rowset | Standard interfaces and base classes for JDBC RowSet implementations.
javax.sql.rowset.spi | The standard classes and interfaces that a third party vendor has to use in its implementation of a synchronization provider.

Uses of SyncProvider in javax.sql.rowset

Methods in javax.sql.rowset that return SyncProvider
 SyncProvider CachedRowSet.getSyncProvider()
Retrieves the SyncProvider implementation for this CachedRowSet object.

Uses of SyncProvider in javax.sql.rowset.spi

Methods in javax.sql.rowset.spi that return SyncProvider
static SyncProvider SyncFactory.getInstance(String providerID)
Returns the SyncProvider instance identified by providerID.

Methods in javax.sql.rowset.spi that return types with arguments of type SyncProvider
static Enumeration<SyncProvider> SyncFactory.getRegisteredProviders()
Returns an Enumeration of currently registered synchronization providers.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.sql.rowset.spi.SyncProviderException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.sql.rowset.spi.SyncProviderException

Packages that use SyncProviderException
javax.sql.rowset | Standard interfaces and base classes for JDBC RowSet implementations.
javax.sql.rowset.spi | The standard classes and interfaces that a third party vendor has to use in its implementation of a synchronization provider.

Uses of SyncProviderException in javax.sql.rowset

Methods in javax.sql.rowset that throw SyncProviderException
void | CachedRowSet.acceptChanges() Propagates row update, insert and delete changes made to this CachedRowSet object to the underlying data source.
void | CachedRowSet.acceptChanges(Connection con) Propagates all row update, insert and delete changes to the data source backing this CachedRowSet object using the specified Connection object to establish a connection to the data source.

Uses of SyncProviderException in javax.sql.rowset.spi

Methods in javax.sql.rowset.spi that throw SyncProviderException
abstract int | SyncProvider.getDataSourceLock() Returns the current data source lock severity level active in this SyncProvider implementation.
abstract void | SyncProvider.setDataSourceLock(int datasource_lock) Sets a lock on the underlying data source at the level indicated by datasource_lock.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.rowset.spi.SyncResolver

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.rowset.spi.SyncResolver

Packages that use SyncResolver
javax.sql.rowset.spi The standard classes and interfaces that a third party vendor has to use in its implementation of a synchronization provider.

Uses of SyncResolver in javax.sql.rowset.spi

Methods in javax.sql.rowset.spi that return SyncResolver
 SyncResolver SyncProviderException.getSyncResolver()
Retrieves the SyncResolver object that has been set for this SyncProviderException object, or if none has been set, an instance of the default SyncResolver implementation included in the reference implementation.

Methods in javax.sql.rowset.spi with parameters of type SyncResolver
 void SyncProviderException.setSyncResolver(SyncResolver syncResolver)
Sets the SyncResolver object for this SyncProviderException object to the one supplied.

Constructors in javax.sql.rowset.spi with parameters of type SyncResolver
SyncProviderException(SyncResolver syncResolver)
Constructs a SyncProviderException object with the specified SyncResolver instance.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.rowset.spi.TransactionalWriter

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.rowset.spi.TransactionalWriter

No usage of javax.sql.rowset.spi.TransactionalWriter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.rowset.spi.XmlReader

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.rowset.spi.XmlReader

No usage of javax.sql.rowset.spi.XmlReader

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.sql.rowset.spi.XmlWriter

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.sql.rowset.spi.XmlWriter

No usage of javax.sql.rowset.spi.XmlWriter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


SyncFactory

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.spi
Class SyncFactory

java.lang.Object
    extended by  javax.sql.rowset.spi.SyncFactory

public class SyncFactory
extends Object

The Service Provider Interface (SPI) mechanism that generates SyncProvider instances to be used by disconnected RowSet objects. The SyncProvider instances in turn provide the javax.sql.RowSetReader object the RowSet object needs to populate itself with data and the javax.sql.RowSetWriter object it needs to propagate changes to its data back to the underlying data source.

Because the methods in the SyncFactory class are all static, there is only one SyncFactory object per Java VM at any one time. This ensures that there is a single source from which a RowSet implementation can obtain its SyncProvider implementation.

1.0 Overview

The SyncFactory class provides an internal registry of available synchronization provider implementations (SyncProvider objects). This registry may be queried to determine which synchronization providers are available. The following line of code gets an enumeration of the providers currently registered.
     java.util.Enumeration e = SyncFactory.getRegisteredProviders();
All standard RowSet implementations must provide at least two providers:
  • an optimistic provider for use with a CachedRowSet implementation or an implementation derived from it
  • an XML provider, which is used for reading and writing XML, such as with WebRowSet objects
Note that the JDBC RowSet Implementations include the SyncProvider implemtations RIOptimisticProvider and RIXmlProvider, which satisfy this requirement.

The SyncFactory class provides accessor methods to assist applications in determining which synchronization providers are currently registered with the SyncFactory.

Other methods let RowSet persistence providers be registered or de-registered with the factory mechanism. This allows additional synchronization provider implementations to be made available to RowSet objects at run time.

Applications can apply a degree of filtering to determine the level of synchronization that a SyncProvider implementation offers. The following criteria determine whether a provider is made available to a RowSet object:

  1. If a particular provider is specified by a RowSet object, and the SyncFactory does not contain a reference to this provider, a SyncFactoryException is thrown stating that the synchronization provider could not be found.

  2. If a RowSet implementation is instantiated with a specified provider and the specified provider has been properly registered, the requested provider is supplied. Otherwise a SyncFactoryException is thrown.

  3. If a RowSet object does not specify a SyncProvider implementation and no additional SyncProvider implementations are available, the reference implementation providers are supplied.

2.0 Registering SyncProvider Implementations

Both vendors and developers can register SyncProvider implementations using one of the following mechanisms.

  • Using the command line
    The name of the provider is supplied on the command line, which will add the provider to the system properties. For example:

    -Drowset.provider.classname=com.fred.providers.HighAvailabilityProvider
  • Using the Standard Properties File
    The reference implementation is targeted to ship with J2SE 1.5, which will include an additional resource file that may be edited by hand. Here is an example of the properties file included in the reference implementation:
       #Default JDBC RowSet sync providers listing
   #

   # Optimistic synchronization provider
   rowset.provider.classname.0=com.sun.rowset.providers.RIOptimisticProvider
   rowset.provider.vendor.0=Sun Microsystems Inc
   rowset.provider.version.0=1.0

   # XML Provider using standard XML schema
   rowset.provider.classname.1=com.sun.rowset.providers.RIXMLProvider
   rowset.provider.vendor.1=Sun Microsystems Inc.
   rowset.provider.version.1=1.0
    The SyncFactory checks this file and registers the SyncProvider implementations that it contains. A developer or vendor can add other implementations to this file. For example, here is a possible addition:
         rowset.provider.classname.2=com.fred.providers.HighAvailabilityProvider
     rowset.provider.vendor.2=Fred, Inc.
     rowset.provider.version.2=1.0

  • Using a JNDI Context
    Available providers can be registered on a JNDI context, and the SyncFactory will attempt to load SyncProvider implementations from that JNDI context. For example, the following code fragment registers a provider implementation on a JNDI context. This is something a deployer would normally do. In this example, MyProvider is being registered on a CosNaming namespace, which is the namespace used by J2EE resources.
        import javax.naming.*;

    Hashtable svrEnv = new  Hashtable();
    srvEnv.put(Context.INITIAL_CONTEXT_FACTORY, "CosNaming");

    Context ctx = new InitialContext(svrEnv);
    com.fred.providers.MyProvider = new MyProvider();
    ctx.rebind("providers/MyProvider", syncProvider);
Next, an application will register the JNDI context with the SyncFactory instance. This allows the SyncFactory to browse within the JNDI context looking for SyncProvider implementations.
    Hashtable appEnv = new Hashtable();
    appEnv.put(Context.INITIAL_CONTEXT_FACTORY, "CosNaming");
    appEnv.put(Context.PROVIDER_URL, "iiop://hostname/providers");
    Context ctx = new InitialContext(appEnv);

    SyncFactory.registerJNDIContext(ctx);
If a RowSet object attempts to obtain a MyProvider object, the SyncFactory will try to locate it. First it searches for it in the system properties, then it looks in the resource files, and finally it checks the JNDI context that has been set. The SyncFactory instance verifies that the requested provider is a valid extension of the SyncProvider abstract class and then gives it to the RowSet object. In the following code fragment, a new CachedRowSet object is created and initialized with env, which contains the binding to MyProvider.
    Hashtable env = new Hashtable();
    env.put(SyncFactory.ROWSET_SYNC_PROVIDER, "com.fred.providers.MyProvider");
    CachedRowSet crs = new com.sun.rowset.CachedRowSetImpl(env);
Further details on these mechanisms are available in the javax.sql.rowset.spi package specification.

See Also:
SyncProvider, SyncFactoryException

Field Summary
static String | ROWSET_SYNC_PROVIDER The standard property-id for a synchronization provider implementation name.
static String | ROWSET_SYNC_PROVIDER_VERSION The standard property-id for a synchronization provider implementation version tag.
static String | ROWSET_SYNC_VENDOR The standard property-id for a synchronization provider implementation vendor name.
Method Summary
static SyncProvider | getInstance(String providerID) Returns the SyncProvider instance identified by providerID.
static Logger | getLogger() Returns the logging object for applications to retrieve synchronization events posted by SyncProvider implementations.
static Enumeration<SyncProvider> | getRegisteredProviders() Returns an Enumeration of currently registered synchronization providers.
static SyncFactory | getSyncFactory() Returns the SyncFactory singleton.
static void | registerProvider(String providerID) Adds the the given synchronization provider to the factory register.
static void | setJNDIContext(Context ctx) Sets the initial JNDI context from which SyncProvider implementations can be retrieved from a JNDI namespace
static void | setLogger(Logger logger) Sets the logging object to be used by the SyncProvider implementation provided by the SyncFactory.
static void | setLogger(Logger logger, Level level) Sets the logging object that is used by SyncProvider implementations provided by the SyncFactory SPI.
static void | unregisterProvider(String providerID) Removes the designated currently registered synchronization provider from the Factory SPI register.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ROWSET_SYNC_PROVIDER

public static String ROWSET_SYNC_PROVIDER
The standard property-id for a synchronization provider implementation name.

ROWSET_SYNC_VENDOR

public static String ROWSET_SYNC_VENDOR
The standard property-id for a synchronization provider implementation vendor name.

ROWSET_SYNC_PROVIDER_VERSION

public static String ROWSET_SYNC_PROVIDER_VERSION
The standard property-id for a synchronization provider implementation version tag.

Method Detail

registerProvider

public static void registerProvider(String providerID)
                             throws SyncFactoryException
Adds the the given synchronization provider to the factory register. Guidelines are provided in the SyncProvider specification for the required naming conventions for SyncProvider implementations.

Synchronization providers bound to a JNDI context can be registered by binding a SyncProvider instance to a JNDI namespace.

     SyncProvider p = new MySyncProvider();
 InitialContext ic = new InitialContext();
 ic.bind ("jdbc/rowset/MySyncProvider", p);
Furthermore, an initial JNDI context should be set with the SyncFactory using the setJNDIContext method. The SyncFactory leverages this context to search for available SyncProvider objects bound to the JNDI context and its child nodes.

Parameters:
providerID - A String object with the unique ID of the synchronization provider being registered
Throws:
SyncFactoryException - if an attempt is made to supply an empty or null provider name
See Also:
setJNDIContext(javax.naming.Context)

getSyncFactory

public static SyncFactory getSyncFactory()
Returns the SyncFactory singleton.

Returns:
the SyncFactory instance

unregisterProvider

public static void unregisterProvider(String providerID)
                               throws SyncFactoryException
Removes the designated currently registered synchronization provider from the Factory SPI register.

Parameters:
providerID - The unique-id of the synchronization provider
Throws:
SyncFactoryException - If an attempt is made to unregister a SyncProvider implementation that was not registered.

getInstance

public static SyncProvider getInstance(String providerID)
                                throws SyncFactoryException
Returns the SyncProvider instance identified by providerID.

Parameters:
providerID - the unique identifier of the provider
Returns:
a SyncProvider implementation
Throws:
SyncFactoryException - If the SyncProvider cannot be found or some error was encountered when trying to invoke this provider.

getRegisteredProviders

public static Enumeration<SyncProvider> getRegisteredProviders()
                                                        throws SyncFactoryException
Returns an Enumeration of currently registered synchronization providers. A RowSet implementation may use any provider in the enumeration as its SyncProvider object.

At a minimum, the reference synchronization provider allowing RowSet content data to be stored using a JDBC driver should be possible.

Returns:
Enumeration A enumeration of available synchronization providers that are registered with this Factory
Throws:
SyncFactoryException

setLogger

public static void setLogger(Logger logger)
Sets the logging object to be used by the SyncProvider implementation provided by the SyncFactory. All SyncProvider implementations can log their events to this object and the application can retrieve a handle to this object using the getLogger method.

Parameters:
logger - A Logger object instance

setLogger

public static void setLogger(Logger logger,
                             Level level)
Sets the logging object that is used by SyncProvider implementations provided by the SyncFactory SPI. All SyncProvider implementations can log their events to this object and the application can retrieve a handle to this object using the getLogger method.

Parameters:
logger - a Logger object instance
level - a Level object instance indicating the degree of logging required

getLogger

public static Logger getLogger()
                        throws SyncFactoryException
Returns the logging object for applications to retrieve synchronization events posted by SyncProvider implementations.

Throws:
SyncFactoryException - if no logging object has been set.

setJNDIContext

public static void setJNDIContext(Context ctx)
                           throws SyncFactoryException
Sets the initial JNDI context from which SyncProvider implementations can be retrieved from a JNDI namespace

Parameters:
ctx - a valid JNDI context
Throws:
SyncFactoryException - if the supplied JNDI context is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


SyncFactoryException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.spi
Class SyncFactoryException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.sql.SQLException
                extended by  javax.sql.rowset.spi.SyncFactoryException
All Implemented Interfaces:
Serializable, Iterable<Throwable>
public class SyncFactoryException
extends SQLException

Indicates an error with SyncFactory mechanism. A disconnected RowSet implementation cannot be used without a SyncProvider being successfully instantiated

See Also:
SyncFactory, SyncFactoryException, Serialized Form

Constructor Summary
SyncFactoryException()
Creates new SyncFactoryException without detail message.
SyncFactoryException(String msg)
Constructs an SyncFactoryException with the specified detail message.
Method Summary
Methods inherited from class java.sql.SQLException
getErrorCode, getNextException, getSQLState, iterator, setNextException
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SyncFactoryException

public SyncFactoryException()
Creates new SyncFactoryException without detail message.

SyncFactoryException

public SyncFactoryException(String msg)
Constructs an SyncFactoryException with the specified detail message.

Parameters:
msg - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SyncProvider

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.spi
Class SyncProvider

java.lang.Object
    extended by  javax.sql.rowset.spi.SyncProvider

public abstract class SyncProvider
extends Object

The synchronization mechanism that provides reader/writer capabilities for disconnected RowSet objects. A SyncProvider implementation is a class that extends the SyncProvider abstract class.

A SyncProvider implementation is identified by a unique ID, which is its fully qualified class name. This name must be registered with the SyncFactory SPI, thus making the implementation available to all RowSet implementations. The factory mechanism in the reference implementation uses this name to instantiate the implementation, which can then provide a RowSet object with its reader (a javax.sql.RowSetReader object) and its writer (a javax.sql.RowSetWriter object).

The Jdbc RowSet Implementations specification provides two reference implementations of the SyncProvider abstract class: RIOptimisticProvider and RIXMLProvider. The RIOptimisticProvider can set any RowSet implementation with a RowSetReader object and a RowSetWriter object. However, only the RIXMLProvider implementation can set an XmlReader object and an XmlWriter object. A WebRowSet object uses the XmlReader object to read data in XML format to populate itself with that data. It uses the XmlWriter object to write itself to a stream or java.io.Writer object in XML format.

1.0 Naming Convention for Implementations

As a guide to naming SyncProvider implementations, the following should be noted:
  • The name for a SyncProvider implementation is its fully qualified class name.
  • It is recommended that vendors supply a SyncProvider implementation in a package named providers.

For instance, if a vendor named Fred, Inc. offered a SyncProvider implementation, you could have the following:

     Vendor name:  Fred, Inc.
     Domain name of vendor:  com.fred
     Package name:  com.fred.providers
     SyncProvider implementation class name:  HighAvailabilityProvider

     Fully qualified class name of SyncProvider implementation:
                        com.fred.providers.HighAvailabilityProvider

The following line of code uses the fully qualified name to register this implementation with the SyncFactory static instance.

     SyncFactory.registerProvider(
                          "com.fred.providers.HighAvailabilityProvider");

The default SyncProvider object provided with the reference implementation uses the following name:

     com.sun.rowset.providers.RIOptimisticProvider

A vendor can register a SyncProvider implementation class name with Sun Microsystems, Inc. by sending email to jdbc@sun.com. Sun will maintain a database listing the available SyncProvider implementations for use with compliant RowSet implementations. This database will be similar to the one already maintained to list available JDBC drivers.

Vendors should refer to the reference implementation synchronization providers for additional guidance on how to implement a new SyncProvider implementation.

2.0 How a RowSet Object Gets Its Provider

A disconnected Rowset object may get access to a SyncProvider object in one of the following two ways:
  • Using a constructor
           CachedRowSet crs = new CachedRowSet(
                  "com.fred.providers.HighAvailabilitySyncProvider");
  • Using the setSyncProvider method
           CachedRowSet crs = new CachedRowSet();
       crs.setSyncProvider("com.fred.providers.HighAvailabilitySyncProvider");

By default, the reference implementations of the RowSet synchronization providers are always available to the Java platform. If no other pluggable synchronization providers have been correctly registered, the SyncFactory will automatically generate an instance of the default SyncProvider reference implementation. Thus, in the preceding code fragment, if no implementation named com.fred.providers.HighAvailabilitySyncProvider has been registered with the SyncFactory instance, crs will be assigned the default provider in the reference implementation, which is com.sun.rowset.providers.RIOptimisticProvider.

3.0 Violations and Synchronization Issues

If an update between a disconnected RowSet object and a data source violates the original query or the underlying data source constraints, this will result in undefined behavior for all disconnected RowSet implementations and their designated SyncProvider implementations. Not defining the behavior when such violations occur offers greater flexibility for a SyncProvider implementation to determine its own best course of action.

A SyncProvider implementation may choose to implement a specific handler to handle a subset of query violations. However if an original query violation or a more general data source constraint violation is not handled by the SyncProvider implementation, all SyncProvider objects must throw a SyncProviderException.

4.0 Updatable SQL VIEWs

It is possible for any disconnected or connected RowSet object to be populated from an SQL query that is formulated originally from an SQL VIEW. While in many cases it is possible for an update to be performed to an underlying view, such an update requires additional metadata, which may vary. The SyncProvider class provides two constants to indicate whether an implementation supports updating an SQL VIEW.
  • NONUPDATABLE_VIEW_SYNC - Indicates that a SyncProvider implementation does not support synchronization with an SQL VIEW as the underlying source of data for the RowSet object.
  • UPDATABLE_VIEW_SYNC - Indicates that a SyncProvider implementation supports synchronization with an SQL VIEW as the underlying source of data.

The default is for a RowSet object not to be updatable if it was populated with data from an SQL VIEW.

5.0 SyncProvider Constants

The SyncProvider class provides three sets of constants that are used as return values or parameters for SyncProvider methods. SyncProvider objects may be implemented to perform synchronization between a RowSet object and its underlying data source with varying degrees of of care. The first group of constants indicate how synchronization is handled. For example, GRADE_NONE indicates that a SyncProvider object will not take any care to see what data is valid and will simply write the RowSet data to the data source. GRADE_MODIFIED_AT_COMMIT indicates that the provider will check only modified data for validity. Other grades check all data for validity or set locks when data is modified or loaded.
  1. Constants to indicate the synchronization grade of a SyncProvider object
    • SyncProvider.GRADE_NONE
    • SyncProvider.GRADE_MODIFIED_AT_COMMIT
    • SyncProvider.GRADE_CHECK_ALL_AT_COMMIT
    • SyncProvider.GRADE_LOCK_WHEN_MODIFIED
    • SyncProvider.GRADE_LOCK_WHEN_LOADED
  2. Constants to indicate what locks are set on the data source
    • SyncProvider.DATASOURCE_NO_LOCK
    • SyncProvider.DATASOURCE_ROW_LOCK
    • SyncProvider.DATASOURCE_TABLE_LOCK
    • SyncProvider.DATASOURCE_DB_LOCK
  3. Constants to indicate whether a SyncProvider object can perform updates to an SQL VIEW
    These constants are explained in the preceding section (4.0).
    • SyncProvider.UPDATABLE_VIEW_SYNC
    • SyncProvider.NONUPDATABLE_VIEW_SYNC

See Also:
SyncFactory, SyncFactoryException

Field Summary
static int | DATASOURCE_DB_LOCK Indicates that a lock is placed on the entire data source that is the source of data for the RowSet object that is using this SyncProvider object.
static int | DATASOURCE_NO_LOCK Indicates that no locks remain on the originating data source.
static int | DATASOURCE_ROW_LOCK Indicates that a lock is placed on the rows that are touched by the original SQL statement used to populate the RowSet object that is using this SyncProvider object.
static int | DATASOURCE_TABLE_LOCK Indicates that a lock is placed on all tables that are touched by the original SQL statement used to populate the RowSet object that is using this SyncProvider object.
static int | GRADE_CHECK_ALL_AT_COMMIT Indicates a high level optimistic synchronization grade with respect to the originating data source.
static int | GRADE_CHECK_MODIFIED_AT_COMMIT Indicates a low level optimistic synchronization grade with respect to the originating data source.
static int | GRADE_LOCK_WHEN_LOADED Indicates the most pessimistic synchronization grade with respect to the originating data source.
static int | GRADE_LOCK_WHEN_MODIFIED Indicates a pessimistic synchronization grade with respect to the originating data source.
static int | GRADE_NONE Indicates that no synchronization with the originating data source is provided.
static int | NONUPDATABLE_VIEW_SYNC Indicates that a SyncProvider implementation does not support synchronization between a RowSet object and the SQL VIEW used to populate it.
static int | UPDATABLE_VIEW_SYNC Indicates that a SyncProvider implementation supports synchronization between a RowSet object and the SQL VIEW used to populate it.
Constructor Summary
SyncProvider()
Creates a default SyncProvider object.
Method Summary
abstract int | getDataSourceLock() Returns the current data source lock severity level active in this SyncProvider implementation.
abstract int | getProviderGrade() Returns a constant indicating the grade of synchronization a RowSet object can expect from this SyncProvider object.
abstract String | getProviderID() Returns the unique identifier for this SyncProvider object.
abstract RowSetReader | getRowSetReader() Returns a javax.sql.RowSetReader object, which can be used to populate a RowSet object with data.
abstract RowSetWriter | getRowSetWriter() Returns a javax.sql.RowSetWriter object, which can be used to write a RowSet object's data back to the underlying data source.
abstract String | getVendor() Returns the vendor name of this SyncProvider instance
abstract String | getVersion() Returns the release version of this SyncProvider instance.
abstract void | setDataSourceLock(int datasource_lock) Sets a lock on the underlying data source at the level indicated by datasource_lock.
abstract int | supportsUpdatableView() Returns whether this SyncProvider implementation can perform synchronization between a RowSet object and the SQL VIEW in the data source from which the RowSet object got its data.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

GRADE_NONE

public static int GRADE_NONE
Indicates that no synchronization with the originating data source is provided. A SyncProvider implementation returning this grade will simply attempt to write updates in the RowSet object to the underlying data source without checking the validity of any data.

GRADE_CHECK_MODIFIED_AT_COMMIT

public static int GRADE_CHECK_MODIFIED_AT_COMMIT
Indicates a low level optimistic synchronization grade with respect to the originating data source. A SyncProvider implementation returning this grade will check only rows that have changed.

GRADE_CHECK_ALL_AT_COMMIT

public static int GRADE_CHECK_ALL_AT_COMMIT
Indicates a high level optimistic synchronization grade with respect to the originating data source. A SyncProvider implementation returning this grade will check all rows, including rows that have not changed.

GRADE_LOCK_WHEN_MODIFIED

public static int GRADE_LOCK_WHEN_MODIFIED
Indicates a pessimistic synchronization grade with respect to the originating data source. A SyncProvider implementation returning this grade will lock the row in the originating data source.

GRADE_LOCK_WHEN_LOADED

public static int GRADE_LOCK_WHEN_LOADED
Indicates the most pessimistic synchronization grade with respect to the originating data source. A SyncProvider implementation returning this grade will lock the entire view and/or table affected by the original statement used to populate a RowSet object.

DATASOURCE_NO_LOCK

public static int DATASOURCE_NO_LOCK
Indicates that no locks remain on the originating data source. This is the default lock setting for all SyncProvider implementations unless otherwise directed by a RowSet object.

DATASOURCE_ROW_LOCK

public static int DATASOURCE_ROW_LOCK
Indicates that a lock is placed on the rows that are touched by the original SQL statement used to populate the RowSet object that is using this SyncProvider object.

DATASOURCE_TABLE_LOCK

public static int DATASOURCE_TABLE_LOCK
Indicates that a lock is placed on all tables that are touched by the original SQL statement used to populate the RowSet object that is using this SyncProvider object.

DATASOURCE_DB_LOCK

public static int DATASOURCE_DB_LOCK
Indicates that a lock is placed on the entire data source that is the source of data for the RowSet object that is using this SyncProvider object.

UPDATABLE_VIEW_SYNC

public static int UPDATABLE_VIEW_SYNC
Indicates that a SyncProvider implementation supports synchronization between a RowSet object and the SQL VIEW used to populate it.

NONUPDATABLE_VIEW_SYNC

public static int NONUPDATABLE_VIEW_SYNC
Indicates that a SyncProvider implementation does not support synchronization between a RowSet object and the SQL VIEW used to populate it.

Constructor Detail

SyncProvider

public SyncProvider()
Creates a default SyncProvider object.

Method Detail

getProviderID

public abstract String getProviderID()
Returns the unique identifier for this SyncProvider object.

Returns:
a String object with the fully qualified class name of this SyncProvider object

getRowSetReader

public abstract RowSetReader getRowSetReader()
Returns a javax.sql.RowSetReader object, which can be used to populate a RowSet object with data.

Returns:
a javax.sql.RowSetReader object

getRowSetWriter

public abstract RowSetWriter getRowSetWriter()
Returns a javax.sql.RowSetWriter object, which can be used to write a RowSet object's data back to the underlying data source.

Returns:
a javax.sql.RowSetWriter object

getProviderGrade

public abstract int getProviderGrade()
Returns a constant indicating the grade of synchronization a RowSet object can expect from this SyncProvider object.

Returns:
an int that is one of the following constants: SyncProvider.GRADE_NONE, SyncProvider.GRADE_CHECK_MODIFIED_AT_COMMIT, SyncProvider.GRADE_CHECK_ALL_AT_COMMIT, SyncProvider.GRADE_LOCK_WHEN_MODIFIED, SyncProvider.GRADE_LOCK_WHEN_LOADED

setDataSourceLock

public abstract void setDataSourceLock(int datasource_lock)
                                throws SyncProviderException
Sets a lock on the underlying data source at the level indicated by datasource_lock. This should cause the SyncProvider to adjust its behavior by increasing or decreasing the level of optimism it provides for a successful synchronization.

Parameters:
datasource_lock - one of the following constants indicating the severity level of data source lock required:
           SyncProvider.DATASOURCE_NO_LOCK,
           SyncProvider.DATASOURCE_ROW_LOCK,
           SyncProvider.DATASOURCE_TABLE_LOCK,
           SyncProvider.DATASOURCE_DB_LOCK,
Throws:
SyncProviderException - if an unsupported data source locking level is set.
See Also:
getDataSourceLock()

getDataSourceLock

public abstract int getDataSourceLock()
                               throws SyncProviderException
Returns the current data source lock severity level active in this SyncProvider implementation.

Returns:
a constant indicating the current level of data source lock active in this SyncProvider object; one of the following:
           SyncProvider.DATASOURCE_NO_LOCK,
           SyncProvider.DATASOURCE_ROW_LOCK,
           SyncProvider.DATASOURCE_TABLE_LOCK,
           SyncProvider.DATASOURCE_DB_LOCK
Throws:
SyncProviderExceptiom - if an error occurs determining the data source locking level.
SyncProviderException
See Also:
setDataSourceLock(int)

supportsUpdatableView

public abstract int supportsUpdatableView()
Returns whether this SyncProvider implementation can perform synchronization between a RowSet object and the SQL VIEW in the data source from which the RowSet object got its data.

Returns:
an int saying whether this SyncProvider object supports updating an SQL VIEW; one of the following: SyncProvider.UPDATABLE_VIEW_SYNC, SyncProvider.NONUPDATABLE_VIEW_SYNC

getVersion

public abstract String getVersion()
Returns the release version of this SyncProvider instance.

Returns:
a String detailing the release version of the SyncProvider implementation

getVendor

public abstract String getVendor()
Returns the vendor name of this SyncProvider instance

Returns:
a String detailing the vendor name of this SyncProvider implementation
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SyncProviderException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.spi
Class SyncProviderException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.sql.SQLException
                extended by  javax.sql.rowset.spi.SyncProviderException
All Implemented Interfaces:
Serializable, Iterable<Throwable>
public class SyncProviderException
extends SQLException

Indicates an error with the SyncProvider mechanism. This exception is created by a SyncProvider abstract class extension if it encounters violations in reading from or writing to the originating data source.

If it is implemented to do so, the SyncProvider object may also create a SyncResolver object and either initialize the SyncProviderException object with it at construction time or set it with the SyncProvider object at a later time.

The method acceptChanges will throw this exception after the writer has finished checking for conflicts and has found one or more conflicts. An application may catch a SyncProviderException object and call its getSyncResolver method to get its SyncResolver object. See the code fragment in the interface comment for SyncResolver for an example. This SyncResolver object will mirror the RowSet object that generated the exception, except that it will contain only the values from the data source that are in conflict. All other values in the SyncResolver object will be null.

The SyncResolver object may be used to examine and resolve each conflict in a row and then go to the next row with a conflict to repeat the procedure.

A SyncProviderException object may or may not contain a description of the condition causing the exception. The inherited method getMessage may be called to retrieve the description if there is one.

See Also:
SyncFactory, SyncResolver, SyncFactoryException, Serialized Form

Constructor Summary
SyncProviderException()
Creates a new SyncProviderException object without a detail message.
SyncProviderException(String msg)
Constructs a SyncProviderException object with the specified detail message.
SyncProviderException(SyncResolver syncResolver)
Constructs a SyncProviderException object with the specified SyncResolver instance.
Method Summary
SyncResolver | getSyncResolver() Retrieves the SyncResolver object that has been set for this SyncProviderException object, or if none has been set, an instance of the default SyncResolver implementation included in the reference implementation.
void | setSyncResolver(SyncResolver syncResolver) Sets the SyncResolver object for this SyncProviderException object to the one supplied.
Methods inherited from class java.sql.SQLException
getErrorCode, getNextException, getSQLState, iterator, setNextException
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SyncProviderException

public SyncProviderException()
Creates a new SyncProviderException object without a detail message.

SyncProviderException

public SyncProviderException(String msg)
Constructs a SyncProviderException object with the specified detail message.

Parameters:
msg - the detail message

SyncProviderException

public SyncProviderException(SyncResolver syncResolver)
Constructs a SyncProviderException object with the specified SyncResolver instance.

Parameters:
syncResolver - the SyncResolver instance used to to process the synchronization conflicts
Throws:
IllegalArgumentException - if the SyncResolver object is null.
Method Detail

getSyncResolver

public SyncResolver getSyncResolver()
Retrieves the SyncResolver object that has been set for this SyncProviderException object, or if none has been set, an instance of the default SyncResolver implementation included in the reference implementation.

If a SyncProviderException object is thrown, an application may use this method to generate a SyncResolver object with which to resolve the conflict or conflicts that caused the exception to be thrown.

Returns:
the SyncResolver object set for this SyncProviderException object or, if none has been set, an instance of the default SyncResolver implementation. In addition, the default SyncResolver implementation is also returned if the SyncResolver() or SyncResolver(String) constructors are used to instantiate the SyncResolver instance.

setSyncResolver

public void setSyncResolver(SyncResolver syncResolver)
Sets the SyncResolver object for this SyncProviderException object to the one supplied. If the argument supplied is null, a call to the method getSyncResolver will return the default reference implementation of the SyncResolver interface.

Parameters:
syncResolver - the SyncResolver object to be set; cannot be null
Throws:
IllegalArgumentException - if the SyncResolver object is null.
See Also:
getSyncResolver()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SyncResolver

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.spi
Interface SyncResolver

All Superinterfaces:
ResultSet, RowSet, Wrapper
public interface SyncResolver
extends RowSet

Defines a framework that allows applications to use a manual decision tree to decide what should be done when a synchronization conflict occurs. Although it is not mandatory for applications to resolve synchronization conflicts manually, this framework provides the means to delegate to the application when conflicts arise.

Note that a conflict is a situation where the RowSet object's original values for a row do not match the values in the data source, which indicates that the data source row has been modified since the last synchronization. Note also that a RowSet object's original values are the values it had just prior to the the last synchronization, which are not necessarily its initial values.

Description of a SyncResolver Object

A SyncResolver object is a specialized RowSet object that implements the SyncResolver interface. It may operate as either a connected RowSet object (an implementation of the JdbcRowSet interface) or a connected RowSet object (an implementation of the CachedRowSet interface or one of its subinterfaces). For information on the subinterfaces, see the javax.sql.rowset package description. The reference implementation for SyncResolver implements the CachedRowSet interface, but other implementations may choose to implement the JdbcRowSet interface to satisfy particular needs.

After an application has attempted to synchronize a RowSet object with the data source (by calling the CachedRowSet method acceptChanges), and one or more conflicts have been found, a rowset's SyncProvider object creates an instance of SyncResolver. This new SyncResolver object has the same number of rows and columns as the RowSet object that was attempting the synchronization. The SyncResolver object contains the values from the data source that caused the conflict(s) and null for all other values. In addition, it contains information about each conflict.

Getting and Using a SyncResolver Object

When the method acceptChanges encounters conflicts, the SyncProvider object creates a SyncProviderException object and sets it with the new SyncResolver object. The method acceptChanges will throw this exception, which the application can then catch and use to retrieve the SyncResolver object it contains. The following code snippet uses the SyncProviderException method getSyncResolver to get the SyncResolver object resolver.
     } catch (SyncProviderException spe) {
         SyncResolver resolver = spe.getSyncResolver();
     ...
     }

With resolver in hand, an application can use it to get the information it contains about the conflict or conflicts. A SyncResolver object such as resolver keeps track of the conflicts for each row in which there is a conflict. It also places a lock on the table or tables affected by the rowset's command so that no more conflicts can occur while the current conflicts are being resolved.

The following kinds of information can be obtained from a SyncResolver object:

  • What operation was being attempted when a conflict occurred
    The SyncProvider interface defines four constants describing states that may occur. Three constants describe the type of operation (update, delete, or insert) that a RowSet object was attempting to perform when a conflict was discovered, and the fourth indicates that there is no conflict. These constants are the possible return values when a SyncResolver object calls the method getStatus.
         int operation = resolver.getStatus();

  • The value in the data source that caused a conflict
    A conflict exists when a value that a RowSet object has changed and is attempting to write to the data source has also been changed in the data source since the last synchronization. An application can call the SyncResolver method getConflictValue to retrieve the value in the data source that is the cause of the conflict because the values in a SyncResolver object are the conflict values from the data source.
         java.lang.Object conflictValue = resolver.getConflictValue(2);
    Note that the column in resolver can be designated by the column number, as is done in the preceding line of code, or by the column name.

    With the information retrieved from the methods getStatus and getConflictValue, the application may make a determination as to which value should be persisted in the data source. The application then calls the SyncResolver method setResolvedValue, which sets the value to be persisted in the RowSet object and also in the data source.

         resolver.setResolvedValue("DEPT", 8390426);
    In the preceding line of code, the column name designates the column in the RowSet object that is to be set with the given value. The column number can also be used to designate the column.

    An application calls the method setResolvedValue after it has resolved all of the conflicts in the current conflict row and repeats this process for each conflict row in the SyncResolver object.

    Navigating a SyncResolver Object

    Because a SyncResolver object is a RowSet object, an application can use all of the RowSet methods for moving the cursor to navigate a SyncResolver object. For example, an application can use the RowSet method next to get to each row and then call the SyncResolver method getStatus to see if the row contains a conflict. In a row with one or more conflicts, the application can iterate through the columns to find any non-null values, which will be the values from the data source that are in conflict.

    To make it easier to navigate a SyncResolver object, especially when there are large numbers of rows with no conflicts, the SyncResolver interface defines the methods nextConflict and previousConflict, which move only to rows that contain at least one conflict value. Then an application can call the SyncResolver method getConflictValue, supplying it with the column number, to get the conflict value itself. The code fragment in the next section gives an example.

    Code Example

    The following code fragment demonstrates how a disconnected RowSet object crs might attempt to synchronize itself with the underlying data source and then resolve the conflicts. In the try block, crs calls the method acceptChanges, passing it the Connection object con. If there are no conflicts, the changes in crs are simply written to the data source. However, if there is a conflict, the method acceptChanges throws a SyncProviderException object, and the catch block takes effect. In this example, which illustrates one of the many ways a SyncResolver object can be used, the SyncResolver method nextConflict is used in a while loop. The loop will end when nextConflict returns false, which will occur when there are no more conflict rows in the SyncResolver object resolver. In This particular code fragment, resolver looks for rows that have update conflicts (rows with the status SyncResolver.UPDATE_ROW_CONFLICT), and the rest of this code fragment executes only for rows where conflicts occurred because crs was attempting an update.

    After the cursor for resolver has moved to the next conflict row that has an update conflict, the method getRow indicates the number of the current row, and the cursor for the CachedRowSet object crs is moved to the comparable row in crs. By iterating through the columns of that row in both resolver and crs, the conflicting values can be retrieved and compared to decide which one should be persisted. In this code fragment, the value in crs is the one set as the resolved value, which means that it will be used to overwrite the conflict value in the data source.

         try {

         crs.acceptChanges(con);

     } catch (SyncProviderException spe) {

         SyncResolver resolver = spe.getSyncResolver();

         Object crsValue;  // value in the RowSet object
         Object resolverValue:  // value in the SyncResolver object
         Object resolvedValue:  // value to be persisted

         while(resolver.nextConflict())  {
             if(resolver.getStatus() == SyncResolver.UPDATE_ROW_CONFLICT)  {
                 int row = resolver.getRow();
                 crs.absolute(row);

                 int colCount = crs.getMetaData().getColumnCount();
                 for(int j = 1; j <= colCount;="colCount;" j++)="j++)" {="{" if="if" (resolver.getConflictValue(j)="(resolver.getConflictValue(j)" !="null)" {="{" crsValue="crs.getObject(j);" resolverValue="resolver.getConflictValue(j);" .="." .="." .="." //="//" compare="compare" crsValue="crsValue" and="and" resolverValue="resolverValue" to="to" determine="determine" //="//" which="which" should="should" be="be" the="the" resolved="resolved" value="value" (the="(the" value="value" to="to" persist)="persist)" resolvedValue="crsValue;" resolver.setResolvedValue(j,="resolver.setResolvedValue(j," resolvedValue);="resolvedValue);" }="}" }="}" }="}" }="}" }="}"

Field Summary

static int
DELETE_ROW_CONFLICT

          Indicates that a conflict occurred while the RowSet object was
 attempting to delete a row in the data source.

static int
INSERT_ROW_CONFLICT

          Indicates that a conflict occurred while the RowSet object was
 attempting to insert a row into the data source.

static int
NO_ROW_CONFLICT

          Indicates that no conflict occured while the RowSet object
 was attempting to update, delete or insert a row in the data source.

static int
UPDATE_ROW_CONFLICT

          Indicates that a conflict occurred while the RowSet object was
 attempting to update a row in the data source.

Fields inherited from interface java.sql.ResultSet

CLOSE_CURSORS_AT_COMMIT, CONCUR_READ_ONLY, CONCUR_UPDATABLE, FETCH_FORWARD, FETCH_REVERSE, FETCH_UNKNOWN, HOLD_CURSORS_OVER_COMMIT, TYPE_FORWARD_ONLY, TYPE_SCROLL_INSENSITIVE, TYPE_SCROLL_SENSITIVE

Method Summary

 Object
getConflictValue(int index)

          Retrieves the value in the designated column in the current row of this
 SyncResolver object, which is the value in the data source
 that caused a conflict.

 Object
getConflictValue(String columnName)

          Retrieves the value in the designated column in the current row of this
 SyncResolver object, which is the value in the data source
 that caused a conflict.

 int
getStatus()

          Retrieves the conflict status of the current row of this SyncResolver,
 which indicates the operation
 the RowSet object was attempting when the conflict occurred.

 boolean
nextConflict()

          Moves the cursor down from its current position to the next row that contains
 a conflict value.

 boolean
previousConflict()

          Moves the cursor up from its current position to the previous conflict
 row in this SyncResolver object.

 void
setResolvedValue(int index,
                 Object obj)

          Sets obj as the value in column index in the current row of the
 RowSet object that is being synchronized.

 void
setResolvedValue(String columnName,
                 Object obj)

          Sets obj as the value in column columnName in the current row of the
 RowSet object that is being synchronized.

Methods inherited from interface javax.sql.RowSet

addRowSetListener, clearParameters, execute, getCommand, getDataSourceName, getEscapeProcessing, getMaxFieldSize, getMaxRows, getPassword, getQueryTimeout, getTransactionIsolation, getTypeMap, getUrl, getUsername, isReadOnly, removeRowSetListener, setArray, setAsciiStream, setAsciiStream, setAsciiStream, setAsciiStream, setBigDecimal, setBigDecimal, setBinaryStream, setBinaryStream, setBinaryStream, setBinaryStream, setBlob, setBlob, setBlob, setBlob, setBlob, setBlob, setBoolean, setBoolean, setByte, setByte, setBytes, setBytes, setCharacterStream, setCharacterStream, setCharacterStream, setCharacterStream, setClob, setClob, setClob, setClob, setClob, setClob, setCommand, setConcurrency, setDataSourceName, setDate, setDate, setDate, setDate, setDouble, setDouble, setEscapeProcessing, setFloat, setFloat, setInt, setInt, setLong, setLong, setMaxFieldSize, setMaxRows, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNClob, setNClob, setNClob, setNClob, setNClob, setNClob, setNString, setNString, setNull, setNull, setNull, setNull, setObject, setObject, setObject, setObject, setObject, setObject, setPassword, setQueryTimeout, setReadOnly, setRef, setRowId, setRowId, setShort, setShort, setSQLXML, setSQLXML, setString, setString, setTime, setTime, setTime, setTime, setTimestamp, setTimestamp, setTimestamp, setTimestamp, setTransactionIsolation, setType, setTypeMap, setURL, setUrl, setUsername

Methods inherited from interface java.sql.ResultSet

absolute, afterLast, beforeFirst, cancelRowUpdates, clearWarnings, close, deleteRow, findColumn, first, getArray, getArray, getAsciiStream, getAsciiStream, getBigDecimal, getBigDecimal, getBigDecimal, getBigDecimal, getBinaryStream, getBinaryStream, getBlob, getBlob, getBoolean, getBoolean, getByte, getByte, getBytes, getBytes, getCharacterStream, getCharacterStream, getClob, getClob, getConcurrency, getCursorName, getDate, getDate, getDate, getDate, getDouble, getDouble, getFetchDirection, getFetchSize, getFloat, getFloat, getHoldability, getInt, getInt, getLong, getLong, getMetaData, getNCharacterStream, getNCharacterStream, getNClob, getNClob, getNString, getNString, getObject, getObject, getObject, getObject, getRef, getRef, getRow, getRowId, getRowId, getShort, getShort, getSQLXML, getSQLXML, getStatement, getString, getString, getTime, getTime, getTime, getTime, getTimestamp, getTimestamp, getTimestamp, getTimestamp, getType, getUnicodeStream, getUnicodeStream, getURL, getURL, getWarnings, insertRow, isAfterLast, isBeforeFirst, isClosed, isFirst, isLast, last, moveToCurrentRow, moveToInsertRow, next, previous, refreshRow, relative, rowDeleted, rowInserted, rowUpdated, setFetchDirection, setFetchSize, updateArray, updateArray, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateBigDecimal, updateBigDecimal, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBoolean, updateBoolean, updateByte, updateByte, updateBytes, updateBytes, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateClob, updateClob, updateClob, updateClob, updateClob, updateClob, updateDate, updateDate, updateDouble, updateDouble, updateFloat, updateFloat, updateInt, updateInt, updateLong, updateLong, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNString, updateNString, updateNull, updateNull, updateObject, updateObject, updateObject, updateObject, updateRef, updateRef, updateRow, updateRowId, updateRowId, updateShort, updateShort, updateSQLXML, updateSQLXML, updateString, updateString, updateTime, updateTime, updateTimestamp, updateTimestamp, wasNull

Methods inherited from interface java.sql.Wrapper

isWrapperFor, unwrap

Field Detail

UPDATE_ROW_CONFLICT

    static final int UPDATE_ROW_CONFLICT

    Indicates that a conflict occurred while the RowSet object was
 attempting to update a row in the data source.
 The values in the data source row to be updated differ from the
 RowSet object's original values for that row, which means that
 the row in the data source has been updated or deleted since the last
 synchronization.

    See Also:
    Constant Field Values

DELETE_ROW_CONFLICT

    static final int DELETE_ROW_CONFLICT

    Indicates that a conflict occurred while the RowSet object was
 attempting to delete a row in the data source.
 The values in the data source row to be updated differ from the
 RowSet object's original values for that row, which means that
 the row in the data source has been updated or deleted since the last
 synchronization.

    See Also:
    Constant Field Values

INSERT_ROW_CONFLICT

    static final int INSERT_ROW_CONFLICT

    Indicates that a conflict occurred while the RowSet object was
 attempting to insert a row into the data source.  This means that a
 row with the same primary key as the row to be inserted has been inserted
 into the data source since the last synchronization.

    See Also:
    Constant Field Values

NO_ROW_CONFLICT

    static final int NO_ROW_CONFLICT

    Indicates that no conflict occured while the RowSet object
 was attempting to update, delete or insert a row in the data source. The values in
 the SyncResolver will contain null values only as an indication
 that no information in pertitent to the conflict resolution in this row.

    See Also:
    Constant Field Values

Method Detail

getStatus

    int getStatus()

    Retrieves the conflict status of the current row of this SyncResolver,
 which indicates the operation
 the RowSet object was attempting when the conflict occurred.

    Returns:
    one of the following constants:
         SyncResolver.UPDATE_ROW_CONFLICT,
         SyncResolver.DELETE_ROW_CONFLICT,
         SyncResolver.INSERT_ROW_CONFLICT, or
         SyncResolver.NO_ROW_CONFLICT

getConflictValue

    Object getConflictValue(int index)
                        throws SQLException

    Retrieves the value in the designated column in the current row of this
 SyncResolver object, which is the value in the data source
 that caused a conflict.

    Parameters:
    index - an int designating the column in this row of this
        SyncResolver object from which to retrieve the value
        causing a conflict

    Returns:
    the value of the designated column in the current row of this
         SyncResolver object

    Throws:

    SQLException - if a database access error occurs

getConflictValue

    Object getConflictValue(String columnName)
                        throws SQLException

    Retrieves the value in the designated column in the current row of this
 SyncResolver object, which is the value in the data source
 that caused a conflict.

    Parameters:
    columnName - a String object designating the column in this row of this
        SyncResolver object from which to retrieve the value
        causing a conflict

    Returns:
    the value of the designated column in the current row of this
         SyncResolver object

    Throws:

    SQLException - if a database access error occurs

setResolvedValue

    void setResolvedValue(int index,
                      Object obj)
                      throws SQLException

    Sets obj as the value in column index in the current row of the
 RowSet object that is being synchronized. obj
 is set as the value in the data source internally.

    Parameters:
    index - an int giving the number of the column into which to
        set the value to be persisted
    obj - an Object that is the value to be set in the
        RowSet object and persisted in the data source

    Throws:

    SQLException - if a database access error occurs

setResolvedValue

    void setResolvedValue(String columnName,
                      Object obj)
                      throws SQLException

    Sets obj as the value in column columnName in the current row of the
 RowSet object that is being synchronized. obj
 is set as the value in the data source internally.

    Parameters:
    columnName - a String object giving the name of the column
        into which to set the value to be persisted
    obj - an Object that is the value to be set in the
        RowSet object and persisted in the data source

    Throws:

    SQLException - if a database access error occurs

nextConflict

    boolean nextConflict()
                     throws SQLException

    Moves the cursor down from its current position to the next row that contains
 a conflict value. A SyncResolver object's
 cursor is initially positioned before the first conflict row; the first call to the
 method nextConflict makes the first conflict row the current row;
 the second call makes the second conflict row the current row, and so on.

 A call to the method nextConflict will implicitly close
 an input stream if one is open and will clear the SyncResolver
 object's warning chain.

    Returns:
    true if the new current row is valid; false
         if there are no more rows

    Throws:

    SQLException - if a database access error occurs or the result set type
     is TYPE_FORWARD_ONLY

previousConflict

    boolean previousConflict()
                         throws SQLException

    Moves the cursor up from its current position to the previous conflict
 row in this SyncResolver object.

 A call to the method previousConflict will implicitly close
 an input stream if one is open and will clear the SyncResolver
 object's warning chain.

    Returns:
    true if the cursor is on a valid row; false
     if it is off the result set

    Throws:

    SQLException - if a database access error occurs or the result set type
     is TYPE_FORWARD_ONLY

      Overview
      Package
    Class
      Use
      Tree
      Deprecated
      Index
      Help

Java™ Platform
    Standard Ed. 6

 PREV CLASS
 NEXT CLASS

  FRAMES
 NO FRAMES

  SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD


TransactionalWriter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.spi
Interface TransactionalWriter

All Superinterfaces:
RowSetWriter
public interface TransactionalWriter
extends RowSetWriter

A specialized interface that facilitates an extension of the standard SyncProvider abstract class so that it has finer grained transaction control.

If one or more disconnected RowSet objects are particating in a global transaction, they may wish to coordinate their synchronization commits to preserve data integrity and reduce the number of sychronization exceptions. If this is the case, an application should set the CachedRowSet constant COMMIT_ON_ACCEPT_CHANGES to false and use the commit and rollback methods defined in this interface to manage transaction boundaries.

Method Summary
void | commit() Makes permanent all changes that have been performed by the acceptChanges method since the last call to either the commit or rollback methods.
void | rollback() Undoes all changes made in the current transaction.
void | rollback(Savepoint s) Undoes all changes made in the current transaction made prior to the given Savepoint object.
Methods inherited from interface javax.sql.RowSetWriter
writeData

Method Detail

commit

void commit()
            throws SQLException
Makes permanent all changes that have been performed by the acceptChanges method since the last call to either the commit or rollback methods. This method should be used only when auto-commit mode has been disabled.

Throws:
SQLException - if a database access error occurs or the Connection object within this CachedRowSet object is in auto-commit mode

rollback

void rollback()
              throws SQLException
Undoes all changes made in the current transaction. This method should be used only when auto-commit mode has been disabled.

Throws:
SQLException - if a database access error occurs or the Connection object within this CachedRowSet object is in auto-commit mode

rollback

void rollback(Savepoint s)
              throws SQLException
Undoes all changes made in the current transaction made prior to the given Savepoint object. This method should be used only when auto-commit mode has been disabled.

Parameters:
s - a Savepoint object marking a savepoint in the current transaction. All changes made before s was set will be undone. All changes made after s was set will be made permanent.
Throws:
SQLException - if a database access error occurs or the Connection object within this CachedRowSet object is in auto-commit mode
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XmlReader

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.spi
Interface XmlReader

All Superinterfaces:
RowSetReader
public interface XmlReader
extends RowSetReader

A specialized interface that facilitates an extension of the SyncProvider abstract class for XML orientated synchronization providers.

SyncProvider implementations that supply XML data reader capabilities such as output XML stream capabilities can implement this interface to provider standard XmlReader objects to WebRowSet implementations.

An XmlReader object is registered as the XML reader for a WebRowSet by being assigned to the rowset's xmlReader field. When the WebRowSet object's readXml method is invoked, it in turn invokes its XML reader's readXML method.

Method Summary
 void readXML(WebRowSet caller, Reader reader)
Reads and parses the given WebRowSet object from the given input stream in XML format.
Methods inherited from interface javax.sql.RowSetReader
readData

Method Detail

readXML

void readXML(WebRowSet caller,
             Reader reader)
             throws SQLException
Reads and parses the given WebRowSet object from the given input stream in XML format. The xmlReader field of the given WebRowSet object must contain this XmlReader object.

If a parsing error occurs, the exception that is thrown will include information about the location of the error in the original XML document.

Parameters:
caller - the WebRowSet object to be parsed, whose xmlReader field must contain a reference to this XmlReader object
reader - the java.io.Reader object from which caller will be read
Throws:
SQLException - if a database access error occurs or this XmlReader object is not the reader for the given rowset
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XmlWriter

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset.spi
Interface XmlWriter

All Superinterfaces:
RowSetWriter
public interface XmlWriter
extends RowSetWriter

A specialized interface that facilitates an extension of the SyncProvider abstract class for XML orientated synchronization providers.

SyncProvider implementations that supply XML data writer capabilities such as output XML stream capabilities can implement this interface to provider standard XmlWriter objects to WebRowSet implementations.

Writing a WebRowSet object includes printing the rowset's data, metadata, and properties, all with the appropriate XML tags.

Method Summary
 void writeXML(WebRowSet caller, Writer writer)
Writes the given WebRowSet object to the specified java.io.Writer output stream as an XML document.
Methods inherited from interface javax.sql.RowSetWriter
writeData

Method Detail

writeXML

void writeXML(WebRowSet caller,
              Writer writer)
              throws SQLException
Writes the given WebRowSet object to the specified java.io.Writer output stream as an XML document. This document includes the rowset's data, metadata, and properties plus the appropriate XML tags.

The caller parameter must be a WebRowSet object whose XmlWriter field contains a reference to this XmlWriter object.

Parameters:
caller - the WebRowSet instance to be written, for which this XmlWriter object is the writer
writer - the java.io.Writer object that serves as the output stream for writing caller as an XML document
Throws:
SQLException - if a database access error occurs or this XmlWriter object is not the writer for the given WebRowSet object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


WebRowSet

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.sql.rowset
Interface WebRowSet

All Superinterfaces:
CachedRowSet, Joinable, ResultSet, RowSet, Wrapper
All Known Subinterfaces:
FilteredRowSet, JoinRowSet
public interface WebRowSet
extends CachedRowSet

The standard interface that all implementations of a WebRowSet must implement.

1.0 Overview

The WebRowSetImpl provides the standard reference implementation, which may be extended if required.

The standard WebRowSet XML Schema definition is available at the following URI:

     http://java.sun.com/xml/ns/jdbc/webrowset.xsd
It describes the standard XML document format required when describing a RowSet object in XML and must be used be all standard implementations of the WebRowSet interface to ensure interoperability. In addition, the WebRowSet schema uses specific SQL/XML Schema annotations, thus ensuring greater cross platform inter-operability. This is an effort currently under way at the ISO organization. The SQL/XML definition is available at the following URI:
     http://standards.iso.org/iso/9075/2002/12/sqlxml
The schema definition describes the internal data of a RowSet object in three distinct areas:
  • properties
    • These properties describe the standard synchronization provider properties in addition to the more general RowSet properties.

  • metadata
    • This describes the metadata associated with the tabular structure governed by a WebRowSet object. The metadata described is closely aligned with the metadata accessible in the underlying java.sql.ResultSet interface.

  • data
    • This describes the original data (the state of data since the last population or last synchronization of the WebRowSet object) and the current data. By keeping track of the delta between the original data and the current data, a WebRowSet maintains the ability to synchronize changes in its data back to the originating data source.

2.0 WebRowSet States

The following sections demonstrates how a WebRowSet implementation should use the XML Schema to describe update, insert, and delete operations and to describe the state of a WebRowSet object in XML.

2.1 State 1 - Outputting a WebRowSet Object to XML

In this example, a WebRowSet object is created and populated with a simple 2 column, 5 row table from a data source. Having the 5 rows in a WebRowSet object makes it possible to describe them in XML. The metadata describing the various standard JavaBeans properties as defined in the RowSet interface plus the standard properties defined in the CachedRowSetTM interface provide key details that describe WebRowSet properties. Outputting the WebRowSet object to XML using the standard writeXml methods describes the internal properties as follows:
 <properties>
       <command>select co1, col2 from test_table</command>
        <concurrency>1</concurrency>
        <datasource/>
        <escape-processing>true</escape-processing>
        <fetch-direction>0</fetch-direction>
        <fetch-size>0</fetch-size>
        <isolation-level>1</isolation-level>
        <key-columns/>
        <map/>
        <max-field-size>0</max-field-size>
        <max-rows>0</max-rows>
        <query-timeout>0</query-timeout>
        <read-only>false</read-only>
        <rowset-type>TRANSACTION_READ_UNCOMMITED</rowset-type>
        <show-deleted>false</show-deleted>
        <table-name/>
        <url>jdbc:thin:oracle</url>
        <sync-provider>
                <sync-provider-name>.com.rowset.provider.RIOptimisticProvider</sync-provider-name>
                <sync-provider-vendor>Sun Microsystems</sync-provider-vendor>
                <sync-provider-version>1.0</sync-provider-name>
                <sync-provider-grade>LOW</sync-provider-grade>
              <data-source-lock>NONE</data-source-lock>
        </sync-provider>
 </properties>
The meta-data describing the make up of the WebRowSet is described in XML as detailed below. Note both columns are described between the column-definition tags.
 <metadata>
        <column-count>2</column-count>
        <column-definition>
                <column-index>1</column-index>
                <auto-increment>false</auto-increment>
                <case-sensitive>true</case-sensitive>
                <currency>false</currency>
                <nullable>1</nullable>
                <signed>false</signed>
                <searchable>true</searchable>
                <column-display-size>10</column-display-size>
                <column-label>COL1</column-label>
                <column-name>COL1</column-name>
                <schema-name/>
                <column-precision>10</column-precision>
                <column-scale>0</column-scale>
                <table-name/>
                <catalog-name/>
                <column-type>1</column-type>
                <column-type-name>CHAR</column-type-name>
        </column-definition>
        <column-definition>
                <column-index>2</column-index>
                <auto-increment>false</auto-increment>
                <case-sensitive>false</case-sensitive>
                <currency>false</currency>
                <nullable>1</nullable>
                <signed>true</signed>
                <searchable>true</searchable>
                <column-display-size>39</column-display-size>
                <column-label>COL2</column-label>
                <column-name>COL2</column-name>
                <schema-name/>
                <column-precision>38</column-precision>
                <column-scale>0</column-scale>
                <table-name/>
                <catalog-name/>
                <column-type>3</column-type>
                <column-type-name>NUMBER</column-type-name>
        </column-definition>
 </metadata>
Having detailed how the properties and metadata are described, the following details how the contents of a WebRowSet object is described in XML. Note, that this describes a WebRowSet object that has not undergone any modifications since its instantiation. A currentRow tag is mapped to each row of the table structure that the WebRowSet object provides. A columnValue tag may contain either the stringData or binaryData tag, according to the SQL type that the XML value is mapping back to. The binaryData tag contains data in the Base64 encoding and is typically used for BLOB and CLOB type data.
 <data>
        <currentRow>
                <columnValue>
                        firstrow
                </columnValue>
                <columnValue>
                        1
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        secondrow
                </columnValue>
                <columnValue>
                        2
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        thirdrow
                </columnValue>
                <columnValue>
                        3
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        fourthrow
                </columnValue>
                <columnValue>
                        4
                </columnValue>
        </currentRow>
 </data>

2.2 State 2 - Deleting a Row

Deleting a row in a WebRowSet object involves simply moving to the row to be deleted and then calling the method deleteRow, as in any other RowSet object. The following two lines of code, in which wrs is a WebRowSet object, delete the third row.
     wrs.absolute(3);
     wrs.deleteRow();
The XML description shows the third row is marked as a deleteRow, which eliminates the third row in the WebRowSet object.
 <data>
        <currentRow>
                <columnValue>
                        firstrow
                </columnValue>
                <columnValue>
                        1
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        secondrow
                </columnValue>
                <columnValue>
                        2
                </columnValue>
        </currentRow>
        <deleteRow>
                <columnValue>
                        thirdrow
                </columnValue>
                <columnValue>
                        3
                </columnValue>
        </deleteRow>
        <currentRow>
                <columnValue>
                        fourthrow
                </columnValue>
                <columnValue>
                        4
                </columnValue>
        </currentRow>
 </data>

2.3 State 3 - Inserting a Row

A WebRowSet object can insert a new row by moving to the insert row, calling the appropriate updater methods for each column in the row, and then calling the method insertRow.
 wrs.moveToInsertRow();
 wrs.updateString(1, "fifththrow");
 wrs.updateString(2, "5");
 wrs.insertRow();
The following code fragment changes the second column value in the row just inserted. Note that this code applies when new rows are inserted right after the current row, which is why the method next moves the cursor to the correct row. Calling the method acceptChanges writes the change to the data source.
 wrs.moveToCurrentRow();
 wrs.next();
 wrs.updateString(2, "V");
 wrs.acceptChanges();
 :
Describing this in XML demonstrates where the Java code inserts a new row and then performs an update on the newly inserted row on an individual field.

 <data>
        <currentRow>
                <columnValue>
                        firstrow
                </columnValue>
                <columnValue>
                        1
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        secondrow
                </columnValue>
                <columnValue>
                        2
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        newthirdrow
                </columnValue>
                <columnValue>
                        III
                </columnValue>
        </currentRow>
        <insertRow>
                <columnValue>
                        fifthrow
                </columnValue>
                <columnValue>
                        5
                </columnValue>
                <updateValue>
                        V
                </updateValue>
        </insertRow>
        <currentRow>
                <columnValue>
                        fourthrow
                </columnValue>
                <columnValue>
                        4
                </columnValue>
        </currentRow>
 </date>

2.4 State 4 - Modifying a Row

Modifying a row produces specific XML that records both the new value and the value that was replaced. The value that was replaced becomes the original value, and the new value becomes the current value. The following code moves the cursor to a specific row, performs some modifications, and updates the row when complete.
 wrs.absolute(5);
 wrs.updateString(1, "new4thRow");
 wrs.updateString(2, "IV");
 wrs.updateRow();
In XML, this is described by the modifyRow tag. Both the original and new values are contained within the tag for original row tracking purposes.
 <data>
        <currentRow>
                <columnValue>
                        firstrow
                </columnValue>
                <columnValue>
                        1
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        secondrow
                </columnValue>
                <columnValue>
                        2
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        newthirdrow
                </columnValue>
                <columnValue>
                        III
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        fifthrow
                </columnValue>
                <columnValue>
                        5
                </columnValue>
        </currentRow>
        <modifyRow>
                <columnValue>
                        fourthrow
                </columnValue>
                <updateValue>
                        new4thRow
                </updateValue>
                <columnValue>
                        4
                </columnValue>
                <updateValue>
                        IV
                </updateValue>
        </modifyRow>
 </data>

See Also:
JdbcRowSet, CachedRowSet, FilteredRowSet, JoinRowSet

Field Summary
static String | PUBLIC_XML_SCHEMA The public identifier for the XML Schema definition that defines the XML tags and their valid values for a WebRowSet implementation.
static String | SCHEMA_SYSTEM_ID The URL for the XML Schema definition file that defines the XML tags and their valid values for a WebRowSet implementation.
Fields inherited from interface javax.sql.rowset.CachedRowSet
COMMIT_ON_ACCEPT_CHANGES
Fields inherited from interface java.sql.ResultSet
CLOSE_CURSORS_AT_COMMIT, CONCUR_READ_ONLY, CONCUR_UPDATABLE, FETCH_FORWARD, FETCH_REVERSE, FETCH_UNKNOWN, HOLD_CURSORS_OVER_COMMIT, TYPE_FORWARD_ONLY, TYPE_SCROLL_INSENSITIVE, TYPE_SCROLL_SENSITIVE
Method Summary
void | readXml(InputStream iStream) Reads a stream based XML input to populate this WebRowSet object.
void | readXml(Reader reader) Reads a WebRowSet object in its XML format from the given Reader object.
void | writeXml(OutputStream oStream) Writes the data, properties, and metadata for this WebRowSet object to the given OutputStream object in XML format.
void | writeXml(ResultSet rs, OutputStream oStream) Populates this WebRowSet object with the contents of the given ResultSet object and writes its data, properties, and metadata to the given OutputStream object in XML format.
void | writeXml(ResultSet rs, Writer writer) Populates this WebRowSet object with the contents of the given ResultSet object and writes its data, properties, and metadata to the given Writer object in XML format.
void | writeXml(Writer writer) Writes the data, properties, and metadata for this WebRowSet object to the given Writer object in XML format.
Methods inherited from interface javax.sql.rowset.CachedRowSet
acceptChanges, acceptChanges, columnUpdated, columnUpdated, commit, createCopy, createCopyNoConstraints, createCopySchema, createShared, execute, getKeyColumns, getOriginal, getOriginalRow, getPageSize, getRowSetWarnings, getShowDeleted, getSyncProvider, getTableName, nextPage, populate, populate, previousPage, release, restoreOriginal, rollback, rollback, rowSetPopulated, setKeyColumns, setMetaData, setOriginalRow, setPageSize, setShowDeleted, setSyncProvider, setTableName, size, toCollection, toCollection, toCollection, undoDelete, undoInsert, undoUpdate
Methods inherited from interface javax.sql.RowSet
addRowSetListener, clearParameters, execute, getCommand, getDataSourceName, getEscapeProcessing, getMaxFieldSize, getMaxRows, getPassword, getQueryTimeout, getTransactionIsolation, getTypeMap, getUrl, getUsername, isReadOnly, removeRowSetListener, setArray, setAsciiStream, setAsciiStream, setAsciiStream, setAsciiStream, setBigDecimal, setBigDecimal, setBinaryStream, setBinaryStream, setBinaryStream, setBinaryStream, setBlob, setBlob, setBlob, setBlob, setBlob, setBlob, setBoolean, setBoolean, setByte, setByte, setBytes, setBytes, setCharacterStream, setCharacterStream, setCharacterStream, setCharacterStream, setClob, setClob, setClob, setClob, setClob, setClob, setCommand, setConcurrency, setDataSourceName, setDate, setDate, setDate, setDate, setDouble, setDouble, setEscapeProcessing, setFloat, setFloat, setInt, setInt, setLong, setLong, setMaxFieldSize, setMaxRows, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNClob, setNClob, setNClob, setNClob, setNClob, setNClob, setNString, setNString, setNull, setNull, setNull, setNull, setObject, setObject, setObject, setObject, setObject, setObject, setPassword, setQueryTimeout, setReadOnly, setRef, setRowId, setRowId, setShort, setShort, setSQLXML, setSQLXML, setString, setString, setTime, setTime, setTime, setTime, setTimestamp, setTimestamp, setTimestamp, setTimestamp, setTransactionIsolation, setType, setTypeMap, setURL, setUrl, setUsername
Methods inherited from interface java.sql.ResultSet
absolute, afterLast, beforeFirst, cancelRowUpdates, clearWarnings, close, deleteRow, findColumn, first, getArray, getArray, getAsciiStream, getAsciiStream, getBigDecimal, getBigDecimal, getBigDecimal, getBigDecimal, getBinaryStream, getBinaryStream, getBlob, getBlob, getBoolean, getBoolean, getByte, getByte, getBytes, getBytes, getCharacterStream, getCharacterStream, getClob, getClob, getConcurrency, getCursorName, getDate, getDate, getDate, getDate, getDouble, getDouble, getFetchDirection, getFetchSize, getFloat, getFloat, getHoldability, getInt, getInt, getLong, getLong, getMetaData, getNCharacterStream, getNCharacterStream, getNClob, getNClob, getNString, getNString, getObject, getObject, getObject, getObject, getRef, getRef, getRow, getRowId, getRowId, getShort, getShort, getSQLXML, getSQLXML, getStatement, getString, getString, getTime, getTime, getTime, getTime, getTimestamp, getTimestamp, getTimestamp, getTimestamp, getType, getUnicodeStream, getUnicodeStream, getURL, getURL, getWarnings, insertRow, isAfterLast, isBeforeFirst, isClosed, isFirst, isLast, last, moveToCurrentRow, moveToInsertRow, next, previous, refreshRow, relative, rowDeleted, rowInserted, rowUpdated, setFetchDirection, setFetchSize, updateArray, updateArray, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateBigDecimal, updateBigDecimal, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBoolean, updateBoolean, updateByte, updateByte, updateBytes, updateBytes, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateClob, updateClob, updateClob, updateClob, updateClob, updateClob, updateDate, updateDate, updateDouble, updateDouble, updateFloat, updateFloat, updateInt, updateInt, updateLong, updateLong, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNString, updateNString, updateNull, updateNull, updateObject, updateObject, updateObject, updateObject, updateRef, updateRef, updateRow, updateRowId, updateRowId, updateShort, updateShort, updateSQLXML, updateSQLXML, updateString, updateString, updateTime, updateTime, updateTimestamp, updateTimestamp, wasNull
Methods inherited from interface java.sql.Wrapper
isWrapperFor, unwrap
Methods inherited from interface javax.sql.rowset.Joinable
getMatchColumnIndexes, getMatchColumnNames, setMatchColumn, setMatchColumn, setMatchColumn, setMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn

Field Detail

PUBLIC_XML_SCHEMA

static final String PUBLIC_XML_SCHEMA
The public identifier for the XML Schema definition that defines the XML tags and their valid values for a WebRowSet implementation.

See Also:
Constant Field Values

SCHEMA_SYSTEM_ID

static final String SCHEMA_SYSTEM_ID
The URL for the XML Schema definition file that defines the XML tags and their valid values for a WebRowSet implementation.

See Also:
Constant Field Values
Method Detail

readXml

void readXml(Reader reader)
             throws SQLException
Reads a WebRowSet object in its XML format from the given Reader object.

Parameters:
reader - the java.io.Reader stream from which this WebRowSet object will be populated
Throws:
SQLException - if a database access error occurs

readXml

void readXml(InputStream iStream)
             throws SQLException,
                    IOException
Reads a stream based XML input to populate this WebRowSet object.

Parameters:
iStream - the java.io.InputStream from which this WebRowSet object will be populated
Throws:
SQLException - if a data source access error occurs
IOException - if an IO exception occurs

writeXml

void writeXml(ResultSet rs,
              Writer writer)
              throws SQLException
Populates this WebRowSet object with the contents of the given ResultSet object and writes its data, properties, and metadata to the given Writer object in XML format.

NOTE: The WebRowSet cursor may be moved to write out the contents to the XML data source. If implemented in this way, the cursor must be returned to its position just prior to the writeXml() call.

Parameters:
rs - the ResultSet object with which to populate this WebRowSet object
writer - the java.io.Writer object to write to.
Throws:
SQLException - if an error occurs writing out the rowset contents in XML format

writeXml

void writeXml(ResultSet rs,
              OutputStream oStream)
              throws SQLException,
                     IOException
Populates this WebRowSet object with the contents of the given ResultSet object and writes its data, properties, and metadata to the given OutputStream object in XML format.

NOTE: The WebRowSet cursor may be moved to write out the contents to the XML data source. If implemented in this way, the cursor must be returned to its position just prior to the writeXml() call.

Parameters:
rs - the ResultSet object with which to populate this WebRowSet object
oStream - the java.io.OutputStream to write to
Throws:
SQLException - if a data source access error occurs
IOException - if a IO exception occurs

writeXml

void writeXml(Writer writer)
              throws SQLException
Writes the data, properties, and metadata for this WebRowSet object to the given Writer object in XML format.

Parameters:
writer - the java.io.Writer stream to write to
Throws:
SQLException - if an error occurs writing out the rowset contents to XML

writeXml

void writeXml(OutputStream oStream)
              throws SQLException,
                     IOException
Writes the data, properties, and metadata for this WebRowSet object to the given OutputStream object in XML format.

Parameters:
oStream - the java.io.OutputStream stream to write to
Throws:
SQLException - if a data source access error occurs
IOException - if a IO exception occurs
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


RowSetEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql
Class RowSetEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.sql.RowSetEvent
All Implemented Interfaces:
Serializable
public class RowSetEvent
extends EventObject

An Event object generated when an event occurs to a RowSet object. A RowSetEvent object is generated when a single row in a rowset is changed, the whole rowset is changed, or the rowset cursor moves.

When an event occurs on a RowSet object, one of the RowSetListener methods will be sent to all registered listeners to notify them of the event. An Event object is supplied to the RowSetListener method so that the listener can use it to find out which RowSet object is the source of the event.

Since:
1.4
See Also:
Serialized Form

Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
RowSetEvent(RowSet source)
Constructs a RowSetEvent object initialized with the given RowSet object.
Method Summary
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RowSetEvent

public RowSetEvent(RowSet source)
Constructs a RowSetEvent object initialized with the given RowSet object.

Parameters:
source - the RowSet object whose data has changed or whose cursor has moved
Throws:
IllegalArgumentException - if source is null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RowSetInternal

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql
Interface RowSetInternal

public interface RowSetInternal

The interface that a RowSet object implements in order to present itself to a RowSetReader or RowSetWriter object. The RowSetInternal interface contains methods that let the reader or writer access and modify the internal state of the rowset.

Since:
1.4

Method Summary
Connection | getConnection() Retrieves the Connection object that was passed to this RowSet object.
ResultSet | getOriginal() Retrieves a ResultSet object containing the original value of this RowSet object.
ResultSet | getOriginalRow() Retrieves a ResultSet object containing the original value of the current row only.
Object[] | getParams() Retrieves the parameters that have been set for this RowSet object's command.
void | setMetaData(RowSetMetaData md) Sets the given RowSetMetaData object as the RowSetMetaData object for this RowSet object.

Method Detail

getParams

Object[] getParams()
                   throws SQLException
Retrieves the parameters that have been set for this RowSet object's command.

Returns:
an array of the current parameter values for this RowSet object's command
Throws:
SQLException - if a database access error occurs

getConnection

Connection getConnection()
                         throws SQLException
Retrieves the Connection object that was passed to this RowSet object.

Returns:
the Connection object passed to the rowset or null if none was passed
Throws:
SQLException - if a database access error occurs

setMetaData

void setMetaData(RowSetMetaData md)
                 throws SQLException
Sets the given RowSetMetaData object as the RowSetMetaData object for this RowSet object. The RowSetReader object associated with the rowset will use RowSetMetaData methods to set the values giving information about the rowset's columns.

Parameters:
md - the RowSetMetaData object that will be set with information about the rowset's columns
Throws:
SQLException - if a database access error occurs

getOriginal

ResultSet getOriginal()
                      throws SQLException
Retrieves a ResultSet object containing the original value of this RowSet object.

The cursor is positioned before the first row in the result set. Only rows contained in the result set returned by the method getOriginal are said to have an original value.

Returns:
the original value of the rowset
Throws:
SQLException - if a database access error occurs

getOriginalRow

ResultSet getOriginalRow()
                         throws SQLException
Retrieves a ResultSet object containing the original value of the current row only. If the current row has no original value, an empty result set is returned. If there is no current row, an exception is thrown.

Returns:
the original value of the current row as a ResultSet object
Throws:
SQLException - if a database access error occurs or this method is called while the cursor is on the insert row, before the first row, or after the last row
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RowSetListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql
Interface RowSetListener

All Superinterfaces:
EventListener
public interface RowSetListener
extends EventListener

An interface that must be implemented by a component that wants to be notified when a significant event happens in the life of a RowSet object. A component becomes a listener by being registered with a RowSet object via the method RowSet.addRowSetListener. How a registered component implements this interface determines what it does when it is notified of an event.

Since:
1.4

Method Summary
void | cursorMoved(RowSetEvent event) Notifies registered listeners that a RowSet object's cursor has moved.
void | rowChanged(RowSetEvent event) Notifies registered listeners that a RowSet object has had a change in one of its rows.
void | rowSetChanged(RowSetEvent event) Notifies registered listeners that a RowSet object in the given RowSetEvent object has changed its entire contents.

Method Detail

rowSetChanged

void rowSetChanged(RowSetEvent event)
Notifies registered listeners that a RowSet object in the given RowSetEvent object has changed its entire contents.

The source of the event can be retrieved with the method event.getSource.

Parameters:
event - a RowSetEvent object that contains the RowSet object that is the source of the event

rowChanged

void rowChanged(RowSetEvent event)
Notifies registered listeners that a RowSet object has had a change in one of its rows.

The source of the event can be retrieved with the method event.getSource.

Parameters:
event - a RowSetEvent object that contains the RowSet object that is the source of the event

cursorMoved

void cursorMoved(RowSetEvent event)
Notifies registered listeners that a RowSet object's cursor has moved.

The source of the event can be retrieved with the method event.getSource.

Parameters:
event - a RowSetEvent object that contains the RowSet object that is the source of the event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RowSetMetaData

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql
Interface RowSetMetaData

All Superinterfaces:
ResultSetMetaData, Wrapper
All Known Implementing Classes:
RowSetMetaDataImpl
public interface RowSetMetaData
extends ResultSetMetaData

An object that contains information about the columns in a RowSet object. This interface is an extension of the ResultSetMetaData interface with methods for setting the values in a RowSetMetaData object. When a RowSetReader object reads data into a RowSet object, it creates a RowSetMetaData object and initializes it using the methods in the RowSetMetaData interface. Then the reader passes the RowSetMetaData object to the rowset.

The methods in this interface are invoked internally when an application calls the method RowSet.execute; an application programmer would not use them directly.

Since:
1.4

Field Summary
Fields inherited from interface java.sql.ResultSetMetaData
columnNoNulls, columnNullable, columnNullableUnknown
Method Summary
void | setAutoIncrement(int columnIndex, boolean property) Sets whether the designated column is automatically numbered, The default is for a RowSet object's columns not to be automatically numbered.
void | setCaseSensitive(int columnIndex, boolean property) Sets whether the designated column is case sensitive.
void | setCatalogName(int columnIndex, String catalogName) Sets the designated column's table's catalog name, if any, to the given String.
void | setColumnCount(int columnCount) Sets the number of columns in the RowSet object to the given number.
void | setColumnDisplaySize(int columnIndex, int size) Sets the designated column's normal maximum width in chars to the given int.
void | setColumnLabel(int columnIndex, String label) Sets the suggested column title for use in printouts and displays, if any, to the given String.
void | setColumnName(int columnIndex, String columnName) Sets the name of the designated column to the given String.
void | setColumnType(int columnIndex, int SQLType) Sets the designated column's SQL type to the one given.
void | setColumnTypeName(int columnIndex, String typeName) Sets the designated column's type name that is specific to the data source, if any, to the given String.
void | setCurrency(int columnIndex, boolean property) Sets whether the designated column is a cash value.
void | setNullable(int columnIndex, int property) Sets whether the designated column's value can be set to NULL.
void | setPrecision(int columnIndex, int precision) Sets the designated column's number of decimal digits to the given int.
void | setScale(int columnIndex, int scale) Sets the designated column's number of digits to the right of the decimal point to the given int.
void | setSchemaName(int columnIndex, String schemaName) Sets the name of the designated column's table's schema, if any, to the given String.
void | setSearchable(int columnIndex, boolean property) Sets whether the designated column can be used in a where clause.
void | setSigned(int columnIndex, boolean property) Sets whether the designated column is a signed number.
void | setTableName(int columnIndex, String tableName) Sets the designated column's table name, if any, to the given String.
Methods inherited from interface java.sql.ResultSetMetaData
getCatalogName, getColumnClassName, getColumnCount, getColumnDisplaySize, getColumnLabel, getColumnName, getColumnType, getColumnTypeName, getPrecision, getScale, getSchemaName, getTableName, isAutoIncrement, isCaseSensitive, isCurrency, isDefinitelyWritable, isNullable, isReadOnly, isSearchable, isSigned, isWritable
Methods inherited from interface java.sql.Wrapper
isWrapperFor, unwrap

Method Detail

setColumnCount

void setColumnCount(int columnCount)
                    throws SQLException
Sets the number of columns in the RowSet object to the given number.

Parameters:
columnCount - the number of columns in the RowSet object
Throws:
SQLException - if a database access error occurs

setAutoIncrement

void setAutoIncrement(int columnIndex,
                      boolean property)
                      throws SQLException
Sets whether the designated column is automatically numbered, The default is for a RowSet object's columns not to be automatically numbered.

Parameters:
columnIndex - the first column is 1, the second is 2, ...
property - true if the column is automatically numbered; false if it is not
Throws:
SQLException - if a database access error occurs

setCaseSensitive

void setCaseSensitive(int columnIndex,
                      boolean property)
                      throws SQLException
Sets whether the designated column is case sensitive. The default is false.

Parameters:
columnIndex - the first column is 1, the second is 2, ...
property - true if the column is case sensitive; false if it is not
Throws:
SQLException - if a database access error occurs

setSearchable

void setSearchable(int columnIndex,
                   boolean property)
                   throws SQLException
Sets whether the designated column can be used in a where clause. The default is false.

Parameters:
columnIndex - the first column is 1, the second is 2, ...
property - true if the column can be used in a WHERE clause; false if it cannot
Throws:
SQLException - if a database access error occurs

setCurrency

void setCurrency(int columnIndex,
                 boolean property)
                 throws SQLException
Sets whether the designated column is a cash value. The default is false.

Parameters:
columnIndex - the first column is 1, the second is 2, ...
property - true if the column is a cash value; false if it is not
Throws:
SQLException - if a database access error occurs

setNullable

void setNullable(int columnIndex,
                 int property)
                 throws SQLException
Sets whether the designated column's value can be set to NULL. The default is ResultSetMetaData.columnNullableUnknown

Parameters:
columnIndex - the first column is 1, the second is 2, ...
property - one of the following constants: ResultSetMetaData.columnNoNulls, ResultSetMetaData.columnNullable, or ResultSetMetaData.columnNullableUnknown
Throws:
SQLException - if a database access error occurs

setSigned

void setSigned(int columnIndex,
               boolean property)
               throws SQLException
Sets whether the designated column is a signed number. The default is false.

Parameters:
columnIndex - the first column is 1, the second is 2, ...
property - true if the column is a signed number; false if it is not
Throws:
SQLException - if a database access error occurs

setColumnDisplaySize

void setColumnDisplaySize(int columnIndex,
                          int size)
                          throws SQLException
Sets the designated column's normal maximum width in chars to the given int.

Parameters:
columnIndex - the first column is 1, the second is 2, ...
size - the normal maximum number of characters for the designated column
Throws:
SQLException - if a database access error occurs

setColumnLabel

void setColumnLabel(int columnIndex,
                    String label)
                    throws SQLException
Sets the suggested column title for use in printouts and displays, if any, to the given String.

Parameters:
columnIndex - the first column is 1, the second is 2, ...
label - the column title
Throws:
SQLException - if a database access error occurs

setColumnName

void setColumnName(int columnIndex,
                   String columnName)
                   throws SQLException
Sets the name of the designated column to the given String.

Parameters:
columnIndex - the first column is 1, the second is 2, ...
columnName - the designated column's name
Throws:
SQLException - if a database access error occurs

setSchemaName

void setSchemaName(int columnIndex,
                   String schemaName)
                   throws SQLException
Sets the name of the designated column's table's schema, if any, to the given String.

Parameters:
columnIndex - the first column is 1, the second is 2, ...
schemaName - the schema name
Throws:
SQLException - if a database access error occurs

setPrecision

void setPrecision(int columnIndex,
                  int precision)
                  throws SQLException
Sets the designated column's number of decimal digits to the given int.

Parameters:
columnIndex - the first column is 1, the second is 2, ...
precision - the total number of decimal digits
Throws:
SQLException - if a database access error occurs

setScale

void setScale(int columnIndex,
              int scale)
              throws SQLException
Sets the designated column's number of digits to the right of the decimal point to the given int.

Parameters:
columnIndex - the first column is 1, the second is 2, ...
scale - the number of digits to right of decimal point
Throws:
SQLException - if a database access error occurs

setTableName

void setTableName(int columnIndex,
                  String tableName)
                  throws SQLException
Sets the designated column's table name, if any, to the given String.

Parameters:
columnIndex - the first column is 1, the second is 2, ...
tableName - the column's table name
Throws:
SQLException - if a database access error occurs

setCatalogName

void setCatalogName(int columnIndex,
                    String catalogName)
                    throws SQLException
Sets the designated column's table's catalog name, if any, to the given String.

Parameters:
columnIndex - the first column is 1, the second is 2, ...
catalogName - the column's catalog name
Throws:
SQLException - if a database access error occurs

setColumnType

void setColumnType(int columnIndex,
                   int SQLType)
                   throws SQLException
Sets the designated column's SQL type to the one given.

Parameters:
columnIndex - the first column is 1, the second is 2, ...
SQLType - the column's SQL type
Throws:
SQLException - if a database access error occurs
See Also:
Types

setColumnTypeName

void setColumnTypeName(int columnIndex,
                       String typeName)
                       throws SQLException
Sets the designated column's type name that is specific to the data source, if any, to the given String.

Parameters:
columnIndex - the first column is 1, the second is 2, ...
typeName - data source specific type name.
Throws:
SQLException - if a database access error occurs
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RowSetReader

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql
Interface RowSetReader

All Known Subinterfaces:
XmlReader
public interface RowSetReader

The facility that a disconnected RowSet object calls on to populate itself with rows of data. A reader (an object implementing the RowSetReader interface) may be registered with a RowSet object that supports the reader/writer paradigm. When the RowSet object's execute method is called, it in turn calls the reader's readData method.

Since:
1.4

Method Summary
 void readData(RowSetInternal caller)
Reads the new contents of the calling RowSet object.

Method Detail

readData

void readData(RowSetInternal caller)
              throws SQLException
Reads the new contents of the calling RowSet object. In order to call this method, a RowSet object must have implemented the RowSetInternal interface and registered this RowSetReader object as its reader. The readData method is invoked internally by the RowSet.execute method for rowsets that support the reader/writer paradigm.

The readData method adds rows to the caller. It can be implemented in a wide variety of ways and can even populate the caller with rows from a nonrelational data source. In general, a reader may invoke any of the rowset's methods, with one exception. Calling the method execute will cause an SQLException to be thrown because execute may not be called recursively. Also, when a reader invokes RowSet methods, no listeners are notified; that is, no RowSetEvent objects are generated and no RowSetListener methods are invoked. This is true because listeners are already being notified by the method execute.

Parameters:
caller - the RowSet object (1) that has implemented the RowSetInternal interface, (2) with which this reader is registered, and (3) whose execute method called this reader
Throws:
SQLException - if a database access error occurs or this method invokes the RowSet.execute method
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RowSetWriter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql
Interface RowSetWriter

All Known Subinterfaces:
TransactionalWriter, XmlWriter
public interface RowSetWriter

An object that implements the RowSetWriter interface, called a writer. A writer may be registered with a RowSet object that supports the reader/writer paradigm.

If a disconnected RowSet object modifies some of its data, and it has a writer associated with it, it may be implemented so that it calls on the writer's writeData method internally to write the updates back to the data source. In order to do this, the writer must first establish a connection with the rowset's data source.

If the data to be updated has already been changed in the data source, there is a conflict, in which case the writer will not write the changes to the data source. The algorithm the writer uses for preventing or limiting conflicts depends entirely on its implementation.

Since:
1.4

Method Summary
 boolean writeData(RowSetInternal caller)
Writes the changes in this RowSetWriter object's rowset back to the data source from which it got its data.

Method Detail

writeData

boolean writeData(RowSetInternal caller)
                  throws SQLException
Writes the changes in this RowSetWriter object's rowset back to the data source from which it got its data.

Parameters:
caller - the RowSet object (1) that has implemented the RowSetInternal interface, (2) with which this writer is registered, and (3) that called this method internally
Returns:
true if the modified data was written; false if not, which will be the case if there is a conflict
Throws:
SQLException - if a database access error occurs
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StatementEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql
Class StatementEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.sql.StatementEvent
All Implemented Interfaces:
Serializable
public class StatementEvent
extends EventObject

A StatementEvent is sent to all StatementEventListeners which were registered with a PooledConnection. This occurs when the driver determines that a PreparedStatement that is associated with the PooledConnection has been closed or the driver determines is invalid.

Since:
1.6
See Also:
Serialized Form

Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
StatementEvent(PooledConnection con, PreparedStatement statement)
Constructs a StatementEvent with the specified PooledConnection and PreparedStatement.
StatementEvent(PooledConnection con, PreparedStatement statement, SQLException exception)
Constructs a StatementEvent with the specified PooledConnection, PreparedStatement and SQLException
Method Summary
SQLException | getSQLException() Returns the SQLException the driver is about to throw
PreparedStatement | getStatement() Returns the PreparedStatement that is being closed or is invalid
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

StatementEvent

public StatementEvent(PooledConnection con,
                      PreparedStatement statement)
Constructs a StatementEvent with the specified PooledConnection and PreparedStatement. The SQLException contained in the event defaults to null.

Parameters:
con - The PooledConnection that the closed or invalid PreparedStatementis associated with.
statement - The PreparedStatement that is bieng closed or is invalid

Throws:
IllegalArgumentException - if con is null.
Since:
1.6

StatementEvent

public StatementEvent(PooledConnection con,
                      PreparedStatement statement,
                      SQLException exception)
Constructs a StatementEvent with the specified PooledConnection, PreparedStatement and SQLException

Parameters:
con - The PooledConnection that the closed or invalid PreparedStatement is associated with.
statement - The PreparedStatement that is being closed or is invalid
exception - The SQLException the driver is about to throw to the application
Throws:
IllegalArgumentException - if con is null.

Since:
1.6
Method Detail

getStatement

public PreparedStatement getStatement()
Returns the PreparedStatement that is being closed or is invalid

Returns:
The PreparedStatement that is being closed or is invalid

Since:
1.6

getSQLException

public SQLException getSQLException()
Returns the SQLException the driver is about to throw

Returns:
The SQLException the driver is about to throw

Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StatementEventListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql
Interface StatementEventListener

All Superinterfaces:
EventListener
public interface StatementEventListener
extends EventListener

An object that registers to be notified of events that occur on PreparedStatements that are in the Statement pool.

The JDBC 3.0 specification added the maxStatements ConnectionPooledDataSource property to provide a standard mechanism for enabling the pooling of PreparedStatements and to specify the size of the statement pool. However, there was no way for a driver to notify an external statement pool when a PreparedStatement becomes invalid. For some databases, a statement becomes invalid if a DDL operation is performed that affects the table. For example an application may create a temporary table to do some work on the table and then destroy it. It may later recreate the same table when it is needed again. Some databases will invalidate any prepared statements that reference the temporary table when the table is dropped.

Similar to the methods defined in the ConnectionEventListener interface, the driver will call the StatementEventListener.statementErrorOccurred method prior to throwing any exceptions when it detects a statement is invalid. The driver will also call the StatementEventListener.statementClosed method when a PreparedStatement is closed.

Methods which allow a component to register a StatementEventListener with a PooledConnection have been added to the PooledConnection interface.

Since:
1.6

Method Summary
void | statementClosed(StatementEvent event) The driver calls this method on all StatementEventListeners registered on the connection when it detects that a PreparedStatement is closed.
void | statementErrorOccurred(StatementEvent event) The driver calls this method on all StatementEventListeners registered on the connection when it detects that a PreparedStatement is invalid.

Method Detail

statementClosed

void statementClosed(StatementEvent event)
The driver calls this method on all StatementEventListeners registered on the connection when it detects that a PreparedStatement is closed.

Parameters:
event - an event object describing the source of the event and that the PreparedStatement was closed.
Since:
1.6

statementErrorOccurred

void statementErrorOccurred(StatementEvent event)
The driver calls this method on all StatementEventListeners registered on the connection when it detects that a PreparedStatement is invalid. The driver calls this method just before it throws the SQLException, contained in the given event, to the application.

Parameters:
event - an event object describing the source of the event, the statement that is invalid and the exception the driver is about to throw. The source of the event is the PooledConnection which the invalid PreparedStatement is associated with.

Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XAConnection

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.sql
Interface XAConnection

All Superinterfaces:
PooledConnection
public interface XAConnection
extends PooledConnection

An object that provides support for distributed transactions. An XAConnection object may be enlisted in a distributed transaction by means of an XAResource object. A transaction manager, usually part of a middle tier server, manages an XAConnection object through the XAResource object.

An application programmer does not use this interface directly; rather, it is used by a transaction manager working in the middle tier server.

Since:
1.4

Method Summary
 XAResource getXAResource()
Retrieves an XAResource object that the transaction manager will use to manage this XAConnection object's participation in a distributed transaction.
Methods inherited from interface javax.sql.PooledConnection
addConnectionEventListener, addStatementEventListener, close, getConnection, removeConnectionEventListener, removeStatementEventListener

Method Detail

getXAResource

XAResource getXAResource()
                         throws SQLException
Retrieves an XAResource object that the transaction manager will use to manage this XAConnection object's participation in a distributed transaction.

Returns:
the XAResource object
Throws:
SQLException - if a database access error occurs
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XADataSource

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.sql
Interface XADataSource

All Superinterfaces:
CommonDataSource
public interface XADataSource
extends CommonDataSource

A factory for XAConnection objects that is used internally. An object that implements the XADataSource interface is typically registered with a naming service that uses the Java Naming and Directory InterfaceTM (JNDI).

Since:
1.4

Method Summary
XAConnection | getXAConnection() Attempts to establish a physical database connection that can be used in a distributed transaction.
XAConnection | getXAConnection(String user, String password) Attempts to establish a physical database connection, using the given user name and password.
Methods inherited from interface javax.sql.CommonDataSource
getLoginTimeout, getLogWriter, setLoginTimeout, setLogWriter

Method Detail

getXAConnection

XAConnection getXAConnection()
                             throws SQLException
Attempts to establish a physical database connection that can be used in a distributed transaction.

Returns:
an XAConnection object, which represents a physical connection to a data source, that can be used in a distributed transaction
Throws:
SQLException - if a database access error occurs
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4

getXAConnection

XAConnection getXAConnection(String user,
                             String password)
                             throws SQLException
Attempts to establish a physical database connection, using the given user name and password. The connection that is returned is one that can be used in a distributed transaction.

Parameters:
user - the database user on whose behalf the connection is being made
password - the user's password
Returns:
an XAConnection object, which represents a physical connection to a data source, that can be used in a distributed transaction
Throws:
SQLException - if a database access error occurs
SQLFeatureNotSupportedException - if the JDBC driver does not support this method
Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


swing

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.swing

Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

See:
Description

Interface Summary
Action | The Action interface provides a useful extension to the ActionListener interface in cases where the same functionality may be accessed by several controls.
BoundedRangeModel | Defines the data model used by components like Sliders and ProgressBars.
ButtonModel | State model for buttons.
CellEditor | This interface defines the methods any general editor should be able to implement.
ComboBoxEditor | The editor component used for JComboBox components.
ComboBoxModel | A data model for a combo box.
DesktopManager | DesktopManager objects are owned by a JDesktopPane object.
Icon | A small fixed size picture, typically used to decorate components.
JComboBox.KeySelectionManager | The interface that defines a KeySelectionManager.
ListCellRenderer | Identifies components that can be used as "rubber stamps" to paint the cells in a JList.
ListModel | This interface defines the methods components like JList use to get the value of each cell in a list and the length of the list.
ListSelectionModel | This interface represents the current state of the selection for any of the components that display a list of values with stable indices.
MenuElement | Any component that can be placed into a menu should implement this interface.
MutableComboBoxModel | A mutable version of ComboBoxModel.
Renderer | Defines the requirements for an object responsible for "rendering" (displaying) a value.
RootPaneContainer | This interface is implemented by components that have a single JRootPane child: JDialog, JFrame, JWindow, JApplet, JInternalFrame.
Scrollable | An interface that provides information to a scrolling container like JScrollPane.
ScrollPaneConstants | Constants used with the JScrollPane component.
SingleSelectionModel | A model that supports at most one indexed selection.
SpinnerModel | A model for a potentially unbounded sequence of object values.
SwingConstants | A collection of constants generally used for positioning and orienting components on the screen.
UIDefaults.ActiveValue | This class enables one to store an entry in the defaults table that's constructed each time it's looked up with one of the getXXX(key) methods.
UIDefaults.LazyValue | This class enables one to store an entry in the defaults table that isn't constructed until the first time it's looked up with one of the getXXX(key) methods.
WindowConstants | Constants used to control the window-closing operation.

Class Summary
AbstractAction | This class provides default implementations for the JFC Action interface.
AbstractButton | Defines common behaviors for buttons and menu items.
AbstractCellEditor |
AbstractListModel | The abstract definition for the data model that provides a List with its contents.
AbstractSpinnerModel | This class provides the ChangeListener part of the SpinnerModel interface that should be suitable for most concrete SpinnerModel implementations.
ActionMap | ActionMap provides mappings from Objects (called keys or Action names) to Actions.
BorderFactory | Factory class for vending standard Border objects.
Box | A lightweight container that uses a BoxLayout object as its layout manager.
Box.Filler | An implementation of a lightweight component that participates in layout but has no view.
BoxLayout | A layout manager that allows multiple components to be laid out either vertically or horizontally.
ButtonGroup | This class is used to create a multiple-exclusion scope for a set of buttons.
CellRendererPane | This class is inserted in between cell renderers and the components that use them.
ComponentInputMap | A ComponentInputMap is an InputMap associated with a particular JComponent.
DebugGraphics | Graphics subclass supporting graphics debugging.
DefaultBoundedRangeModel | A generic implementation of BoundedRangeModel.
DefaultButtonModel | The default implementation of a Button component's data model.
DefaultCellEditor | The default editor for table and tree cells.
DefaultComboBoxModel | The default model for combo boxes.
DefaultDesktopManager | This is an implementation of the DesktopManager.
DefaultFocusManager | This class has been obsoleted by the 1.4 focus APIs.
DefaultListCellRenderer | Renders an item in a list.
DefaultListCellRenderer.UIResource | A subclass of DefaultListCellRenderer that implements UIResource.
DefaultListModel | This class loosely implements the java.util.Vector API, in that it implements the 1.1.x version of java.util.Vector, has no collection class support, and notifies the ListDataListeners when changes occur.
DefaultListSelectionModel | Default data model for list selections.
DefaultRowSorter<M,I> | An implementation of RowSorter that provides sorting and filtering around a grid-based data model.
DefaultRowSorter.ModelWrapper<M,I> | DefaultRowSorter.ModelWrapper is responsible for providing the data that gets sorted by DefaultRowSorter.
DefaultSingleSelectionModel | A generic implementation of SingleSelectionModel.
FocusManager | This class has been obsoleted by the 1.4 focus APIs.
GrayFilter | An image filter that "disables" an image by turning it into a grayscale image, and brightening the pixels in the image.
GroupLayout | GroupLayout is a LayoutManager that hierarchically groups components in order to position them in a Container.
ImageIcon | An implementation of the Icon interface that paints Icons from Images.
InputMap | InputMap provides a binding between an input event (currently only KeyStrokes are used) and an Object.
InputVerifier | The purpose of this class is to help clients support smooth focus navigation through GUIs with text fields.
InternalFrameFocusTraversalPolicy | A FocusTraversalPolicy which can optionally provide an algorithm for determining a JInternalFrame's initial Component.
JApplet | An extended version of java.applet.Applet that adds support for the JFC/Swing component architecture.
JButton | An implementation of a "push" button.
JCheckBox | An implementation of a check box -- an item that can be selected or deselected, and which displays its state to the user.
JCheckBoxMenuItem | A menu item that can be selected or deselected.
JColorChooser | JColorChooser provides a pane of controls designed to allow a user to manipulate and select a color.
JComboBox | A component that combines a button or editable field and a drop-down list.
JComponent | The base class for all Swing components except top-level containers.
JDesktopPane | A container used to create a multiple-document interface or a virtual desktop.
JDialog | The main class for creating a dialog window.
JEditorPane | A text component to edit various kinds of content.
JFileChooser | JFileChooser provides a simple mechanism for the user to choose a file.
JFormattedTextField | JFormattedTextField extends JTextField adding support for formatting arbitrary values, as well as retrieving a particular object once the user has edited the text.
JFormattedTextField.AbstractFormatter | Instances of AbstractFormatter are used by JFormattedTextField to handle the conversion both from an Object to a String, and back from a String to an Object.
JFormattedTextField.AbstractFormatterFactory | Instances of AbstractFormatterFactory are used by JFormattedTextField to obtain instances of AbstractFormatter which in turn are used to format values.
JFrame | An extended version of java.awt.Frame that adds support for the JFC/Swing component architecture.
JInternalFrame | A lightweight object that provides many of the features of a native frame, including dragging, closing, becoming an icon, resizing, title display, and support for a menu bar.
JInternalFrame.JDesktopIcon | This component represents an iconified version of a JInternalFrame.
JLabel | A display area for a short text string or an image, or both.
JLayeredPane | JLayeredPane adds depth to a JFC/Swing container, allowing components to overlap each other when needed.
JList | A component that displays a list of objects and allows the user to select one or more items.
JList.DropLocation | A subclass of TransferHandler.DropLocation representing a drop location for a JList.
JMenu | An implementation of a menu -- a popup window containing JMenuItems that is displayed when the user selects an item on the JMenuBar.
JMenuBar | An implementation of a menu bar.
JMenuItem | An implementation of an item in a menu.
JOptionPane | JOptionPane makes it easy to pop up a standard dialog box that prompts users for a value or informs them of something.
JPanel | JPanel is a generic lightweight container.
JPasswordField | JPasswordField is a lightweight component that allows the editing of a single line of text where the view indicates something was typed, but does not show the original characters.
JPopupMenu | An implementation of a popup menu -- a small window that pops up and displays a series of choices.
JPopupMenu.Separator | A popup menu-specific separator.
JProgressBar | A component that visually displays the progress of some task.
JRadioButton | An implementation of a radio button -- an item that can be selected or deselected, and which displays its state to the user.
JRadioButtonMenuItem | An implementation of a radio button menu item.
JRootPane | A lightweight container used behind the scenes by JFrame, JDialog, JWindow, JApplet, and JInternalFrame.
JScrollBar | An implementation of a scrollbar.
JScrollPane | Provides a scrollable view of a lightweight component.
JSeparator | JSeparator provides a general purpose component for implementing divider lines - most commonly used as a divider between menu items that breaks them up into logical groupings.
JSlider | A component that lets the user graphically select a value by sliding a knob within a bounded interval.
JSpinner | A single line input field that lets the user select a number or an object value from an ordered sequence.
JSpinner.DateEditor | An editor for a JSpinner whose model is a SpinnerDateModel.
JSpinner.DefaultEditor | A simple base class for more specialized editors that displays a read-only view of the model's current value with a JFormattedTextField.
JSpinner.ListEditor | An editor for a JSpinner whose model is a SpinnerListModel.
JSpinner.NumberEditor | An editor for a JSpinner whose model is a SpinnerNumberModel.
JSplitPane | JSplitPane is used to divide two (and only two) Components.
JTabbedPane | A component that lets the user switch between a group of components by clicking on a tab with a given title and/or icon.
JTable | The JTable is used to display and edit regular two-dimensional tables of cells.
JTable.DropLocation | A subclass of TransferHandler.DropLocation representing a drop location for a JTable.
JTextArea | A JTextArea is a multi-line area that displays plain text.
JTextField | JTextField is a lightweight component that allows the editing of a single line of text.
JTextPane | A text component that can be marked up with attributes that are represented graphically.
JToggleButton | An implementation of a two-state button.
JToggleButton.ToggleButtonModel | The ToggleButton model
JToolBar | JToolBar provides a component that is useful for displaying commonly used Actions or controls.
JToolBar.Separator | A toolbar-specific separator.
JToolTip | Used to display a "Tip" for a Component.
JTree | A control that displays a set of hierarchical data as an outline.
JTree.DropLocation | A subclass of TransferHandler.DropLocation representing a drop location for a JTree.
JTree.DynamicUtilTreeNode | DynamicUtilTreeNode can wrap vectors/hashtables/arrays/strings and create the appropriate children tree nodes as necessary.
JTree.EmptySelectionModel | EmptySelectionModel is a TreeSelectionModel that does not allow anything to be selected.
JViewport | The "viewport" or "porthole" through which you see the underlying information.
JWindow | A JWindow is a container that can be displayed anywhere on the user's desktop.
KeyStroke | A KeyStroke represents a key action on the keyboard, or equivalent input device.
LayoutFocusTraversalPolicy | A SortingFocusTraversalPolicy which sorts Components based on their size, position, and orientation.
LayoutStyle | LayoutStyle provides information about how to position components.
LookAndFeel | LookAndFeel, as the name implies, encapsulates a look and feel.
MenuSelectionManager | A MenuSelectionManager owns the selection in menu hierarchy.
OverlayLayout | A layout manager to arrange components over the top of each other.
Popup | Popups are used to display a Component to the user, typically on top of all the other Components in a particular containment hierarchy.
PopupFactory | PopupFactory, as the name implies, is used to obtain instances of Popups.
ProgressMonitor | A class to monitor the progress of some operation.
ProgressMonitorInputStream | Monitors the progress of reading from some InputStream.
RepaintManager | This class manages repaint requests, allowing the number of repaints to be minimized, for example by collapsing multiple requests into a single repaint for members of a component tree.
RowFilter<M,I> | RowFilter is used to filter out entries from the model so that they are not shown in the view.
RowFilter.Entry<M,I> | An Entry object is passed to instances of RowFilter, allowing the filter to get the value of the entry's data, and thus to determine whether the entry should be shown.
RowSorter<M> | RowSorter provides the basis for sorting and filtering.
RowSorter.SortKey | SortKey describes the sort order for a particular column.
ScrollPaneLayout | The layout manager used by JScrollPane.
ScrollPaneLayout.UIResource | The UI resource version of ScrollPaneLayout.
SizeRequirements | For the convenience of layout managers, calculates information about the size and position of components.
SizeSequence | A SizeSequence object efficiently maintains an ordered list of sizes and corresponding positions.
SortingFocusTraversalPolicy | A FocusTraversalPolicy that determines traversal order by sorting the Components of a focus traversal cycle based on a given Comparator.
SpinnerDateModel | A SpinnerModel for sequences of Dates.
SpinnerListModel | A simple implementation of SpinnerModel whose values are defined by an array or a List.
SpinnerNumberModel | A SpinnerModel for sequences of numbers.
Spring | An instance of the Spring class holds three properties that characterize its behavior: the minimum, preferred, and maximum values.
SpringLayout | A SpringLayout lays out the children of its associated container according to a set of constraints.
SpringLayout.Constraints | A Constraints object holds the constraints that govern the way a component's size and position change in a container controlled by a SpringLayout.
SwingUtilities | A collection of utility methods for Swing.
SwingWorker<T,V> | An abstract class to perform lengthy GUI-interacting tasks in a dedicated thread.
Timer | Fires one or more ActionEvents at specified intervals.
ToolTipManager | Manages all the ToolTips in the system.
TransferHandler | This class is used to handle the transfer of a Transferable to and from Swing components.
TransferHandler.DropLocation | Represents a location where dropped data should be inserted.
TransferHandler.TransferSupport | This class encapsulates all relevant details of a clipboard or drag and drop transfer, and also allows for customizing aspects of the drag and drop experience.
UIDefaults | A table of defaults for Swing components.
UIDefaults.LazyInputMap | LazyInputMap will create a InputMap in its createValue method.
UIDefaults.ProxyLazyValue | This class provides an implementation of LazyValue which can be used to delay loading of the Class for the instance to be created.
UIManager | UIManager manages the current look and feel, the set of available look and feels, PropertyChangeListeners that are notified when the look and feel changes, look and feel defaults, and convenience methods for obtaining various default values.
UIManager.LookAndFeelInfo | Provides a little information about an installed LookAndFeel for the sake of configuring a menu or for initial application set up.
ViewportLayout | The default layout manager for JViewport.

Enum Summary
DropMode | Drop modes, used to determine the method by which a component tracks and indicates a drop location during drag and drop.
GroupLayout.Alignment | Enumeration of the possible ways ParallelGroup can align its children.
JTable.PrintMode | Printing modes, used in printing JTables.
LayoutStyle.ComponentPlacement | ComponentPlacement is an enumeration of the possible ways two components can be placed relative to each other.
RowFilter.ComparisonType | Enumeration of the possible comparison values supported by some of the default RowFilters.
SortOrder | SortOrder is an enumeration of the possible sort orderings.
SwingWorker.StateValue | Values for the state bound property.

Exception Summary
UnsupportedLookAndFeelException An exception that indicates the requested look & feel management classes are not present on the user's system.

Package javax.swing Description

Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms. For a programmer's guide to using these components, see Creating a GUI with JFC/Swing, a trail in The Java Tutorial. For other resources, see Related Documentation.

Swing's Threading Policy

In general Swing is not thread safe. All Swing components and related classes, unless otherwise documented, must be accessed on the event dispatching thread.

Typical Swing applications do processing in response to an event generated from a user gesture. For example, clicking on a JButton notifies all ActionListeners added to the JButton. As all events generated from a user gesture are dispatched on the event dispatching thread, most developers are not impacted by the restriction.

Where the impact lies, however, is in constructing and showing a Swing application. Calls to an application's main method, or methods in Applet, are not invoked on the event dispatching thread. As such, care must be taken to transfer control to the event dispatching thread when constructing and showing an application or applet. The preferred way to transfer control and begin working with Swing is to use invokeLater. The invokeLater method schedules a Runnable to be processed on the event dispatching thread. The following two examples work equally well for transferring control and starting up a Swing application:

public class MyApp implements Runnable {
    public void run() {
        // Invoked on the event dispatching thread.
        // Construct and show GUI.
    }

    public static void main(String[] args) {
        SwingUtilities.invokeLater(new MyApp(args));
    }
}
Or:
public class MyApp {
    MyApp(String[] args) {
        // Invoked on the event dispatching thread. Do any initialization
        // here.
    }

    public void show() {
        // Show the UI.
    }

    public static void main(final String[] args) {
        // Schedule a job for the event-dispatching thread:
        // creating and showing this application's GUI.
        SwingUtilities.invokeLater(new Runnable() {
            public void run() {
                new MyApp(args).show();
            }
        });
    }
}
This restriction also applies to models attached to Swing components. For example, if a TableModel is attached to a JTable, the TableModel should only be modified on the event dispatching thread. If you modify the model on a separate thread you run the risk of exceptions and possible display corruption.

As all events are delivered on the event dispatching thread, care must be taken in event processing. In particular, a long running task, such as network io or computational intensive processing, executed on the event dispatching thread blocks the event dispatching thread from dispatching any other events. While the event dispatching thread is blocked the application is completely unresponsive to user input. Refer to SwingWorker for the preferred way to do such processing when working with Swing.

More information on this topic can be found in the Swing tutorial, in particular the section on How to Use Threads.

Related Documentation

For overviews, tutorials, examples, guides, and other documentation, please see:

  • The Swing Connection
  • The Java Tutorial
  • Online Training at the Java Developer ConnectionSM
  • Java Foundation Classes (JFC) home page

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.swing Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.swing

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.swing.AbstractAction (implements javax.swing.Action, java.lang.Cloneable, java.io.Serializable)
    • javax.swing.AbstractButton.ButtonChangeListener (implements javax.swing.event.ChangeListener, java.io.Serializable)
    • javax.swing.AbstractCellEditor (implements javax.swing.CellEditor, java.io.Serializable)
      • javax.swing.DefaultCellEditor (implements javax.swing.table.TableCellEditor, javax.swing.tree.TreeCellEditor)
    • javax.swing.AbstractListModel (implements javax.swing.ListModel, java.io.Serializable)
      • javax.swing.DefaultComboBoxModel (implements javax.swing.MutableComboBoxModel, java.io.Serializable)
      • javax.swing.DefaultListModel
    • javax.swing.AbstractSpinnerModel (implements javax.swing.SpinnerModel)
      • javax.swing.SpinnerDateModel (implements java.io.Serializable)
      • javax.swing.SpinnerListModel (implements java.io.Serializable)
      • javax.swing.SpinnerNumberModel (implements java.io.Serializable)
    • javax.accessibility.AccessibleContext
      • java.awt.Component.AccessibleAWTComponent (implements javax.accessibility.AccessibleComponent, java.io.Serializable)
        • javax.swing.Box.Filler.AccessibleBoxFiller
        • java.awt.Container.AccessibleAWTContainer
          • javax.swing.Box.AccessibleBox
          • javax.swing.CellRendererPane.AccessibleCellRendererPane
          • javax.swing.JComponent.AccessibleJComponent (implements javax.accessibility.AccessibleExtendedComponent)
            • javax.swing.AbstractButton.AccessibleAbstractButton (implements javax.accessibility.AccessibleAction, javax.accessibility.AccessibleExtendedComponent, javax.accessibility.AccessibleText, javax.accessibility.AccessibleValue)
              • javax.swing.JButton.AccessibleJButton
              • javax.swing.JMenuItem.AccessibleJMenuItem (implements javax.swing.event.ChangeListener)
                • javax.swing.JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem
                • javax.swing.JMenu.AccessibleJMenu (implements javax.accessibility.AccessibleSelection)
                • javax.swing.JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem
              • javax.swing.JToggleButton.AccessibleJToggleButton (implements java.awt.event.ItemListener)
                • javax.swing.JCheckBox.AccessibleJCheckBox
                • javax.swing.JRadioButton.AccessibleJRadioButton
            • javax.swing.JColorChooser.AccessibleJColorChooser
            • javax.swing.JComboBox.AccessibleJComboBox (implements javax.accessibility.AccessibleAction, javax.accessibility.AccessibleSelection)
            • javax.swing.JDesktopPane.AccessibleJDesktopPane
            • javax.swing.JFileChooser.AccessibleJFileChooser
            • javax.swing.JInternalFrame.AccessibleJInternalFrame (implements javax.accessibility.AccessibleValue)
            • javax.swing.JInternalFrame.JDesktopIcon.AccessibleJDesktopIcon (implements javax.accessibility.AccessibleValue)
            • javax.swing.JLabel.AccessibleJLabel (implements javax.accessibility.AccessibleExtendedComponent, javax.accessibility.AccessibleText)
            • javax.swing.JLayeredPane.AccessibleJLayeredPane
            • javax.swing.JList.AccessibleJList (implements javax.accessibility.AccessibleSelection, javax.swing.event.ListDataListener, javax.swing.event.ListSelectionListener, java.beans.PropertyChangeListener)
            • javax.swing.JMenuBar.AccessibleJMenuBar (implements javax.accessibility.AccessibleSelection)
            • javax.swing.JOptionPane.AccessibleJOptionPane
            • javax.swing.JPanel.AccessibleJPanel
            • javax.swing.JPopupMenu.AccessibleJPopupMenu (implements java.beans.PropertyChangeListener)
            • javax.swing.JProgressBar.AccessibleJProgressBar (implements javax.accessibility.AccessibleValue)
            • javax.swing.JRootPane.AccessibleJRootPane
            • javax.swing.JScrollBar.AccessibleJScrollBar (implements javax.accessibility.AccessibleValue)
            • javax.swing.JScrollPane.AccessibleJScrollPane (implements javax.swing.event.ChangeListener, java.beans.PropertyChangeListener)
            • javax.swing.JSeparator.AccessibleJSeparator
            • javax.swing.JSlider.AccessibleJSlider (implements javax.accessibility.AccessibleValue)
            • javax.swing.JSpinner.AccessibleJSpinner (implements javax.accessibility.AccessibleAction, javax.accessibility.AccessibleEditableText, javax.accessibility.AccessibleText, javax.accessibility.AccessibleValue, javax.swing.event.ChangeListener)
            • javax.swing.JSplitPane.AccessibleJSplitPane (implements javax.accessibility.AccessibleValue)
            • javax.swing.JTabbedPane.AccessibleJTabbedPane (implements javax.accessibility.AccessibleSelection, javax.swing.event.ChangeListener)
            • javax.swing.JTable.AccessibleJTable (implements javax.accessibility.AccessibleExtendedTable, javax.accessibility.AccessibleSelection, javax.swing.event.CellEditorListener, javax.swing.event.ListSelectionListener, java.beans.PropertyChangeListener, javax.swing.event.TableColumnModelListener, javax.swing.event.TableModelListener)
            • javax.swing.text.JTextComponent.AccessibleJTextComponent (implements javax.accessibility.AccessibleAction, javax.accessibility.AccessibleEditableText, javax.accessibility.AccessibleExtendedText, javax.accessibility.AccessibleText, javax.swing.event.CaretListener, javax.swing.event.DocumentListener)
              • javax.swing.JEditorPane.AccessibleJEditorPane
                • javax.swing.JEditorPane.AccessibleJEditorPaneHTML
                • javax.swing.JEditorPane.JEditorPaneAccessibleHypertextSupport (implements javax.accessibility.AccessibleHypertext)
              • javax.swing.JTextArea.AccessibleJTextArea
              • javax.swing.JTextField.AccessibleJTextField
                • javax.swing.JPasswordField.AccessibleJPasswordField
            • javax.swing.JToolBar.AccessibleJToolBar
            • javax.swing.JToolTip.AccessibleJToolTip
            • javax.swing.JTree.AccessibleJTree (implements javax.accessibility.AccessibleSelection, javax.swing.event.TreeExpansionListener, javax.swing.event.TreeModelListener, javax.swing.event.TreeSelectionListener)
            • javax.swing.JViewport.AccessibleJViewport
          • java.awt.Panel.AccessibleAWTPanel
            • java.applet.Applet.AccessibleApplet
              • javax.swing.JApplet.AccessibleJApplet
          • java.awt.Window.AccessibleAWTWindow
            • java.awt.Dialog.AccessibleAWTDialog
              • javax.swing.JDialog.AccessibleJDialog
            • java.awt.Frame.AccessibleAWTFrame
              • javax.swing.JFrame.AccessibleJFrame
            • javax.swing.JWindow.AccessibleJWindow
      • javax.swing.ImageIcon.AccessibleImageIcon (implements javax.accessibility.AccessibleIcon, java.io.Serializable)
      • javax.swing.JList.AccessibleJList.AccessibleJListChild (implements javax.accessibility.Accessible, javax.accessibility.AccessibleComponent)
      • javax.swing.JTable.AccessibleJTable.AccessibleJTableCell (implements javax.accessibility.Accessible, javax.accessibility.AccessibleComponent)
      • javax.swing.JTree.AccessibleJTree.AccessibleJTreeNode (implements javax.accessibility.Accessible, javax.accessibility.AccessibleAction, javax.accessibility.AccessibleComponent, javax.accessibility.AccessibleSelection)
      • javax.swing.ProgressMonitor.AccessibleProgressMonitor (implements javax.accessibility.AccessibleText, javax.swing.event.ChangeListener, java.beans.PropertyChangeListener)
    • javax.accessibility.AccessibleHyperlink (implements javax.accessibility.AccessibleAction)
      • javax.swing.JEditorPane.JEditorPaneAccessibleHypertextSupport.HTMLLink
    • javax.swing.ActionMap (implements java.io.Serializable)
    • java.awt.AWTKeyStroke (implements java.io.Serializable)
      • javax.swing.KeyStroke
    • javax.swing.BorderFactory
    • javax.swing.BoxLayout (implements java.awt.LayoutManager2, java.io.Serializable)
    • javax.swing.ButtonGroup (implements java.io.Serializable)
    • java.awt.Component (implements java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable)
      • java.awt.Container
        • javax.swing.CellRendererPane (implements javax.accessibility.Accessible)
        • javax.swing.JComponent (implements java.io.Serializable)
          • javax.swing.AbstractButton (implements java.awt.ItemSelectable, javax.swing.SwingConstants)
            • javax.swing.JButton (implements javax.accessibility.Accessible)
            • javax.swing.JMenuItem (implements javax.accessibility.Accessible, javax.swing.MenuElement)
              • javax.swing.JCheckBoxMenuItem (implements javax.accessibility.Accessible, javax.swing.SwingConstants)
              • javax.swing.JMenu (implements javax.accessibility.Accessible, javax.swing.MenuElement)
              • javax.swing.JRadioButtonMenuItem (implements javax.accessibility.Accessible)
            • javax.swing.JToggleButton (implements javax.accessibility.Accessible)
              • javax.swing.JCheckBox (implements javax.accessibility.Accessible)
              • javax.swing.JRadioButton (implements javax.accessibility.Accessible)
          • javax.swing.Box (implements javax.accessibility.Accessible)
          • javax.swing.Box.Filler (implements javax.accessibility.Accessible)
          • javax.swing.JColorChooser (implements javax.accessibility.Accessible)
          • javax.swing.JComboBox (implements javax.accessibility.Accessible, java.awt.event.ActionListener, java.awt.ItemSelectable, javax.swing.event.ListDataListener)
          • javax.swing.JFileChooser (implements javax.accessibility.Accessible)
          • javax.swing.JInternalFrame (implements javax.accessibility.Accessible, javax.swing.RootPaneContainer, javax.swing.WindowConstants)
          • javax.swing.JInternalFrame.JDesktopIcon (implements javax.accessibility.Accessible)
          • javax.swing.JLabel (implements javax.accessibility.Accessible, javax.swing.SwingConstants)
            • javax.swing.DefaultListCellRenderer (implements javax.swing.ListCellRenderer, java.io.Serializable)
              • javax.swing.DefaultListCellRenderer.UIResource (implements javax.swing.plaf.UIResource)
          • javax.swing.JLayeredPane (implements javax.accessibility.Accessible)
            • javax.swing.JDesktopPane (implements javax.accessibility.Accessible)
          • javax.swing.JList (implements javax.accessibility.Accessible, javax.swing.Scrollable)
          • javax.swing.JMenuBar (implements javax.accessibility.Accessible, javax.swing.MenuElement)
          • javax.swing.JOptionPane (implements javax.accessibility.Accessible)
          • javax.swing.JPanel (implements javax.accessibility.Accessible)
            • javax.swing.JSpinner.DefaultEditor (implements javax.swing.event.ChangeListener, java.awt.LayoutManager, java.beans.PropertyChangeListener)
              • javax.swing.JSpinner.DateEditor
              • javax.swing.JSpinner.ListEditor
              • javax.swing.JSpinner.NumberEditor
          • javax.swing.JPopupMenu (implements javax.accessibility.Accessible, javax.swing.MenuElement)
          • javax.swing.JProgressBar (implements javax.accessibility.Accessible, javax.swing.SwingConstants)
          • javax.swing.JRootPane (implements javax.accessibility.Accessible)
          • javax.swing.JScrollBar (implements javax.accessibility.Accessible, java.awt.Adjustable)
            • javax.swing.JScrollPane.ScrollBar (implements javax.swing.plaf.UIResource)
          • javax.swing.JScrollPane (implements javax.accessibility.Accessible, javax.swing.ScrollPaneConstants)
          • javax.swing.JSeparator (implements javax.accessibility.Accessible, javax.swing.SwingConstants)
            • javax.swing.JPopupMenu.Separator
            • javax.swing.JToolBar.Separator
          • javax.swing.JSlider (implements javax.accessibility.Accessible, javax.swing.SwingConstants)
          • javax.swing.JSpinner (implements javax.accessibility.Accessible)
          • javax.swing.JSplitPane (implements javax.accessibility.Accessible)
          • javax.swing.JTabbedPane (implements javax.accessibility.Accessible, java.io.Serializable, javax.swing.SwingConstants)
          • javax.swing.JTable (implements javax.accessibility.Accessible, javax.swing.event.CellEditorListener, javax.swing.event.ListSelectionListener, javax.swing.event.RowSorterListener, javax.swing.Scrollable, javax.swing.event.TableColumnModelListener, javax.swing.event.TableModelListener)
          • javax.swing.text.JTextComponent (implements javax.accessibility.Accessible, javax.swing.Scrollable)
            • javax.swing.JEditorPane
              • javax.swing.JTextPane
            • javax.swing.JTextArea
            • javax.swing.JTextField (implements javax.swing.SwingConstants)
              • javax.swing.JFormattedTextField
              • javax.swing.JPasswordField
          • javax.swing.JToolBar (implements javax.accessibility.Accessible, javax.swing.SwingConstants)
          • javax.swing.JToolTip (implements javax.accessibility.Accessible)
          • javax.swing.JTree (implements javax.accessibility.Accessible, javax.swing.Scrollable)
          • javax.swing.JViewport (implements javax.accessibility.Accessible)
        • java.awt.Panel (implements javax.accessibility.Accessible)
          • java.applet.Applet
            • javax.swing.JApplet (implements javax.accessibility.Accessible, javax.swing.RootPaneContainer)
        • java.awt.Window (implements javax.accessibility.Accessible)
          • java.awt.Dialog
            • javax.swing.JDialog (implements javax.accessibility.Accessible, javax.swing.RootPaneContainer, javax.swing.WindowConstants)
          • java.awt.Frame (implements java.awt.MenuContainer)
            • javax.swing.JFrame (implements javax.accessibility.Accessible, javax.swing.RootPaneContainer, javax.swing.WindowConstants)
          • javax.swing.JWindow (implements javax.accessibility.Accessible, javax.swing.RootPaneContainer)
    • java.awt.event.ComponentAdapter (implements java.awt.event.ComponentListener)
      • javax.swing.JViewport.ViewListener (implements java.io.Serializable)
    • javax.swing.DefaultBoundedRangeModel (implements javax.swing.BoundedRangeModel, java.io.Serializable)
    • javax.swing.DefaultButtonModel (implements javax.swing.ButtonModel, java.io.Serializable)
      • javax.swing.JToggleButton.ToggleButtonModel
    • javax.swing.DefaultCellEditor.EditorDelegate (implements java.awt.event.ActionListener, java.awt.event.ItemListener, java.io.Serializable)
    • javax.swing.DefaultDesktopManager (implements javax.swing.DesktopManager, java.io.Serializable)
    • javax.swing.DefaultListSelectionModel (implements java.lang.Cloneable, javax.swing.ListSelectionModel, java.io.Serializable)
    • javax.swing.tree.DefaultMutableTreeNode (implements java.lang.Cloneable, javax.swing.tree.MutableTreeNode, java.io.Serializable)
      • javax.swing.JTree.DynamicUtilTreeNode
    • javax.swing.DefaultRowSorter.ModelWrapper<M,I>
    • javax.swing.DefaultSingleSelectionModel (implements java.io.Serializable, javax.swing.SingleSelectionModel)
    • javax.swing.tree.DefaultTreeSelectionModel (implements java.lang.Cloneable, java.io.Serializable, javax.swing.tree.TreeSelectionModel)
      • javax.swing.JTree.EmptySelectionModel
    • java.util.Dictionary<K,V>
      • java.util.Hashtable<K,V> (implements java.lang.Cloneable, java.util.Map<K,V>, java.io.Serializable)
        • javax.swing.UIDefaults
    • java.awt.FocusTraversalPolicy
      • javax.swing.InternalFrameFocusTraversalPolicy
        • javax.swing.SortingFocusTraversalPolicy
          • javax.swing.LayoutFocusTraversalPolicy (implements java.io.Serializable)
    • java.awt.Graphics
      • javax.swing.DebugGraphics
    • javax.swing.GroupLayout (implements java.awt.LayoutManager2)
    • javax.swing.GroupLayout.Group
      • javax.swing.GroupLayout.ParallelGroup
      • javax.swing.GroupLayout.SequentialGroup
    • java.awt.image.ImageFilter (implements java.lang.Cloneable, java.awt.image.ImageConsumer)
      • java.awt.image.RGBImageFilter
        • javax.swing.GrayFilter
    • javax.swing.ImageIcon (implements javax.accessibility.Accessible, javax.swing.Icon, java.io.Serializable)
    • javax.swing.InputMap (implements java.io.Serializable)
      • javax.swing.ComponentInputMap
    • java.io.InputStream (implements java.io.Closeable)
      • java.io.FilterInputStream
        • javax.swing.ProgressMonitorInputStream
    • javax.swing.InputVerifier
    • javax.swing.JComponent.AccessibleJComponent.AccessibleContainerHandler (implements java.awt.event.ContainerListener)
    • javax.swing.JComponent.AccessibleJComponent.AccessibleFocusHandler (implements java.awt.event.FocusListener)
    • javax.swing.JFormattedTextField.AbstractFormatter (implements java.io.Serializable)
    • javax.swing.JFormattedTextField.AbstractFormatterFactory
    • javax.swing.JRootPane.RootLayout (implements java.awt.LayoutManager2, java.io.Serializable)
    • javax.swing.JTabbedPane.ModelListener (implements javax.swing.event.ChangeListener, java.io.Serializable)
    • javax.swing.JTable.AccessibleJTable.AccessibleJTableModelChange (implements javax.accessibility.AccessibleTableModelChange)
    • javax.swing.JTree.TreeModelHandler (implements javax.swing.event.TreeModelListener)
    • javax.swing.JTree.TreeSelectionRedirector (implements java.io.Serializable, javax.swing.event.TreeSelectionListener)
    • java.awt.KeyboardFocusManager (implements java.awt.KeyEventDispatcher, java.awt.KeyEventPostProcessor)
      • java.awt.DefaultKeyboardFocusManager
        • javax.swing.FocusManager
          • javax.swing.DefaultFocusManager
    • javax.swing.LayoutStyle
    • javax.swing.LookAndFeel
    • javax.swing.MenuSelectionManager
    • java.awt.event.MouseAdapter (implements java.awt.event.MouseListener, java.awt.event.MouseMotionListener, java.awt.event.MouseWheelListener)
      • javax.swing.ToolTipManager (implements java.awt.event.MouseMotionListener)
    • javax.swing.OverlayLayout (implements java.awt.LayoutManager2, java.io.Serializable)
    • javax.swing.Popup
    • javax.swing.PopupFactory
    • javax.swing.ProgressMonitor (implements javax.accessibility.Accessible)
    • javax.swing.RepaintManager
    • javax.swing.RowFilter<M,I>
    • javax.swing.RowFilter.Entry<M,I>
    • javax.swing.RowSorter<M>
      • javax.swing.DefaultRowSorter<M,I>
    • javax.swing.RowSorter.SortKey
    • javax.swing.ScrollPaneLayout (implements java.awt.LayoutManager, javax.swing.ScrollPaneConstants, java.io.Serializable)
      • javax.swing.ScrollPaneLayout.UIResource (implements javax.swing.plaf.UIResource)
    • javax.swing.SizeRequirements (implements java.io.Serializable)
    • javax.swing.SizeSequence
    • javax.swing.Spring
    • javax.swing.SpringLayout (implements java.awt.LayoutManager2)
    • javax.swing.SpringLayout.Constraints
    • javax.swing.SwingUtilities (implements javax.swing.SwingConstants)
    • javax.swing.SwingWorker<T,V> (implements java.util.concurrent.RunnableFuture<V>)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.swing.UnsupportedLookAndFeelException
    • javax.swing.Timer (implements java.io.Serializable)
    • javax.swing.ToolTipManager.insideTimerAction (implements java.awt.event.ActionListener)
    • javax.swing.ToolTipManager.outsideTimerAction (implements java.awt.event.ActionListener)
    • javax.swing.ToolTipManager.stillInsideTimerAction (implements java.awt.event.ActionListener)
    • javax.swing.TransferHandler (implements java.io.Serializable)
    • javax.swing.TransferHandler.DropLocation
      • javax.swing.JList.DropLocation
      • javax.swing.JTable.DropLocation
      • javax.swing.JTree.DropLocation
    • javax.swing.TransferHandler.TransferSupport
    • javax.swing.UIDefaults.LazyInputMap (implements javax.swing.UIDefaults.LazyValue)
    • javax.swing.UIDefaults.ProxyLazyValue (implements javax.swing.UIDefaults.LazyValue)
    • javax.swing.UIManager (implements java.io.Serializable)
    • javax.swing.UIManager.LookAndFeelInfo
    • javax.swing.ViewportLayout (implements java.awt.LayoutManager, java.io.Serializable)
    • java.awt.event.WindowAdapter (implements java.awt.event.WindowFocusListener, java.awt.event.WindowListener, java.awt.event.WindowStateListener)
      • javax.swing.JMenu.WinListener (implements java.io.Serializable)

Interface Hierarchy

  • javax.swing.BoundedRangeModel
  • javax.swing.CellEditor
  • javax.swing.ComboBoxEditor
  • javax.swing.DesktopManager
  • java.util.EventListener
    • java.awt.event.ActionListener
      • javax.swing.Action
  • javax.swing.Icon
  • java.awt.ItemSelectable
    • javax.swing.ButtonModel
  • javax.swing.JComboBox.KeySelectionManager
  • javax.swing.ListCellRenderer
  • javax.swing.ListModel
    • javax.swing.ComboBoxModel
      • javax.swing.MutableComboBoxModel
  • javax.swing.ListSelectionModel
  • javax.swing.MenuElement
  • javax.swing.Renderer
  • javax.swing.RootPaneContainer
  • javax.swing.Scrollable
  • javax.swing.ScrollPaneConstants
  • javax.swing.SingleSelectionModel
  • javax.swing.SpinnerModel
  • javax.swing.SwingConstants
  • javax.swing.UIDefaults.ActiveValue
  • javax.swing.UIDefaults.LazyValue
  • javax.swing.WindowConstants

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • javax.swing.SwingWorker.StateValue
      • javax.swing.GroupLayout.Alignment
      • javax.swing.JTable.PrintMode
      • javax.swing.RowFilter.ComparisonType
      • javax.swing.LayoutStyle.ComponentPlacement
      • javax.swing.SortOrder
      • javax.swing.DropMode
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.swing

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.swing

Packages that use javax.swing
java.awt.im.spi | Provides interfaces that enable the development of input methods that can be used with any Java runtime environment.
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.border | Provides classes and interface for drawing specialized borders around a Swing component.
javax.swing.colorchooser | Contains classes and interfaces used by the JColorChooser component.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.filechooser | Contains classes and interfaces used by the JFileChooser component.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.
javax.swing.plaf.synth | Synth is a skinnable look and feel in which all painting is delegated.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Classes in javax.swing used by java.awt.im.spi
JFrame
An extended version of java.awt.Frame that adds support for the JFC/Swing component architecture.

Classes in javax.swing used by javax.swing
AbstractButton
Defines common behaviors for buttons and menu items.
AbstractButton.AccessibleAbstractButton
This class implements accessibility support for the AbstractButton class.
AbstractCellEditor
AbstractListModel
The abstract definition for the data model that provides a List with its contents.
AbstractSpinnerModel
This class provides the ChangeListener part of the SpinnerModel interface that should be suitable for most concrete SpinnerModel implementations.
Action
The Action interface provides a useful extension to the ActionListener interface in cases where the same functionality may be accessed by several controls.
ActionMap
ActionMap provides mappings from Objects (called keys or Action names) to Actions.
BoundedRangeModel
Defines the data model used by components like Sliders and ProgressBars.
Box
A lightweight container that uses a BoxLayout object as its layout manager.
ButtonGroup
This class is used to create a multiple-exclusion scope for a set of buttons.
ButtonModel
State model for buttons.
CellEditor
This interface defines the methods any general editor should be able to implement.
ComboBoxEditor
The editor component used for JComboBox components.
ComboBoxModel
A data model for a combo box.
ComponentInputMap
A ComponentInputMap is an InputMap associated with a particular JComponent.
DefaultButtonModel
The default implementation of a Button component's data model.
DefaultCellEditor.EditorDelegate
The protected EditorDelegate class.
DefaultListCellRenderer
Renders an item in a list.
DefaultRowSorter.ModelWrapper
DefaultRowSorter.ModelWrapper is responsible for providing the data that gets sorted by DefaultRowSorter.
DesktopManager
DesktopManager objects are owned by a JDesktopPane object.
DropMode
Drop modes, used to determine the method by which a component tracks and indicates a drop location during drag and drop.
FocusManager
This class has been obsoleted by the 1.4 focus APIs.
GroupLayout.Alignment
Enumeration of the possible ways ParallelGroup can align its children.
GroupLayout.Group
Group provides the basis for the two types of operations supported by GroupLayout: laying out components one after another (SequentialGroup) or aligned (ParallelGroup).
GroupLayout.ParallelGroup
A Group that aligns and sizes it's children.
GroupLayout.SequentialGroup
A Group that positions and sizes its elements sequentially, one after another.
Icon
A small fixed size picture, typically used to decorate components.
InputMap
InputMap provides a binding between an input event (currently only KeyStrokes are used) and an Object.
InputVerifier
The purpose of this class is to help clients support smooth focus navigation through GUIs with text fields.
InternalFrameFocusTraversalPolicy
A FocusTraversalPolicy which can optionally provide an algorithm for determining a JInternalFrame's initial Component.
JButton
An implementation of a "push" button.
JCheckBox
An implementation of a check box -- an item that can be selected or deselected, and which displays its state to the user.
JColorChooser
JColorChooser provides a pane of controls designed to allow a user to manipulate and select a color.
JComboBox
A component that combines a button or editable field and a drop-down list.
JComboBox.KeySelectionManager
The interface that defines a KeySelectionManager.
JComponent
The base class for all Swing components except top-level containers.
JComponent.AccessibleJComponent
Inner class of JComponent used to provide default support for accessibility.
JDesktopPane
A container used to create a multiple-document interface or a virtual desktop.
JDialog
The main class for creating a dialog window.
JEditorPane
A text component to edit various kinds of content.
JEditorPane.AccessibleJEditorPane
This class implements accessibility support for the JEditorPane class.
JFormattedTextField
JFormattedTextField extends JTextField adding support for formatting arbitrary values, as well as retrieving a particular object once the user has edited the text.
JFormattedTextField.AbstractFormatter
Instances of AbstractFormatter are used by JFormattedTextField to handle the conversion both from an Object to a String, and back from a String to an Object.
JFormattedTextField.AbstractFormatterFactory
Instances of AbstractFormatterFactory are used by JFormattedTextField to obtain instances of AbstractFormatter which in turn are used to format values.
JInternalFrame
A lightweight object that provides many of the features of a native frame, including dragging, closing, becoming an icon, resizing, title display, and support for a menu bar.
JInternalFrame.JDesktopIcon
This component represents an iconified version of a JInternalFrame.
JLabel
A display area for a short text string or an image, or both.
JLayeredPane
JLayeredPane adds depth to a JFC/Swing container, allowing components to overlap each other when needed.
JList
A component that displays a list of objects and allows the user to select one or more items.
JList.DropLocation
A subclass of TransferHandler.DropLocation representing a drop location for a JList.
JMenu
An implementation of a menu -- a popup window containing JMenuItems that is displayed when the user selects an item on the JMenuBar.
JMenu.WinListener
A listener class that watches for a popup window closing.
JMenuBar
An implementation of a menu bar.
JMenuItem
An implementation of an item in a menu.
JMenuItem.AccessibleJMenuItem
This class implements accessibility support for the JMenuItem class.
JPanel
JPanel is a generic lightweight container.
JPopupMenu
An implementation of a popup menu -- a small window that pops up and displays a series of choices.
JRootPane
A lightweight container used behind the scenes by JFrame, JDialog, JWindow, JApplet, and JInternalFrame.
JScrollBar
An implementation of a scrollbar.
JScrollPane
Provides a scrollable view of a lightweight component.
JSeparator
JSeparator provides a general purpose component for implementing divider lines - most commonly used as a divider between menu items that breaks them up into logical groupings.
JSpinner
A single line input field that lets the user select a number or an object value from an ordered sequence.
JSpinner.DefaultEditor
A simple base class for more specialized editors that displays a read-only view of the model's current value with a JFormattedTextField.
JTable
The JTable is used to display and edit regular two-dimensional tables of cells.
JTable.DropLocation
A subclass of TransferHandler.DropLocation representing a drop location for a JTable.
JTable.PrintMode
Printing modes, used in printing JTables.
JTextField
JTextField is a lightweight component that allows the editing of a single line of text.
JTextField.AccessibleJTextField
This class implements accessibility support for the JTextField class.
JToggleButton
An implementation of a two-state button.
JToggleButton.AccessibleJToggleButton
This class implements accessibility support for the JToggleButton class.
JToolTip
Used to display a "Tip" for a Component.
JTree
A control that displays a set of hierarchical data as an outline.
JTree.DropLocation
A subclass of TransferHandler.DropLocation representing a drop location for a JTree.
JTree.EmptySelectionModel
EmptySelectionModel is a TreeSelectionModel that does not allow anything to be selected.
JTree.TreeSelectionRedirector
Handles creating a new TreeSelectionEvent with the JTree as the source and passing it off to all the listeners.
JViewport
The "viewport" or "porthole" through which you see the underlying information.
JViewport.ViewListener
A listener for the view.
KeyStroke
A KeyStroke represents a key action on the keyboard, or equivalent input device.
LayoutStyle
LayoutStyle provides information about how to position components.
LayoutStyle.ComponentPlacement
ComponentPlacement is an enumeration of the possible ways two components can be placed relative to each other.
ListCellRenderer
Identifies components that can be used as "rubber stamps" to paint the cells in a JList.
ListModel
This interface defines the methods components like JList use to get the value of each cell in a list and the length of the list.
ListSelectionModel
This interface represents the current state of the selection for any of the components that display a list of values with stable indices.
LookAndFeel
LookAndFeel, as the name implies, encapsulates a look and feel.
MenuElement
Any component that can be placed into a menu should implement this interface.
MenuSelectionManager
A MenuSelectionManager owns the selection in menu hierarchy.
MutableComboBoxModel
A mutable version of ComboBoxModel.
Popup
Popups are used to display a Component to the user, typically on top of all the other Components in a particular containment hierarchy.
PopupFactory
PopupFactory, as the name implies, is used to obtain instances of Popups.
ProgressMonitor
A class to monitor the progress of some operation.
RepaintManager
This class manages repaint requests, allowing the number of repaints to be minimized, for example by collapsing multiple requests into a single repaint for members of a component tree.
RootPaneContainer
This interface is implemented by components that have a single JRootPane child: JDialog, JFrame, JWindow, JApplet, JInternalFrame.
RowFilter
RowFilter is used to filter out entries from the model so that they are not shown in the view.
RowFilter.ComparisonType
Enumeration of the possible comparison values supported by some of the default RowFilters.
RowFilter.Entry
An Entry object is passed to instances of RowFilter, allowing the filter to get the value of the entry's data, and thus to determine whether the entry should be shown.
RowSorter
RowSorter provides the basis for sorting and filtering.
RowSorter.SortKey
SortKey describes the sort order for a particular column.
Scrollable
An interface that provides information to a scrolling container like JScrollPane.
ScrollPaneConstants
Constants used with the JScrollPane component.
ScrollPaneLayout
The layout manager used by JScrollPane.
SingleSelectionModel
A model that supports at most one indexed selection.
SizeRequirements
For the convenience of layout managers, calculates information about the size and position of components.
SortingFocusTraversalPolicy
A FocusTraversalPolicy that determines traversal order by sorting the Components of a focus traversal cycle based on a given Comparator.
SortOrder
SortOrder is an enumeration of the possible sort orderings.
SpinnerDateModel
A SpinnerModel for sequences of Dates.
SpinnerListModel
A simple implementation of SpinnerModel whose values are defined by an array or a List.
SpinnerModel
A model for a potentially unbounded sequence of object values.
SpinnerNumberModel
A SpinnerModel for sequences of numbers.
Spring
An instance of the Spring class holds three properties that characterize its behavior: the minimum, preferred, and maximum values.
SpringLayout.Constraints
A Constraints object holds the constraints that govern the way a component's size and position change in a container controlled by a SpringLayout.
SwingConstants
A collection of constants generally used for positioning and orienting components on the screen.
SwingWorker.StateValue
Values for the state bound property.
ToolTipManager
Manages all the ToolTips in the system.
TransferHandler
This class is used to handle the transfer of a Transferable to and from Swing components.
TransferHandler.DropLocation
Represents a location where dropped data should be inserted.
TransferHandler.TransferSupport
This class encapsulates all relevant details of a clipboard or drag and drop transfer, and also allows for customizing aspects of the drag and drop experience.
UIDefaults
A table of defaults for Swing components.
UIDefaults.LazyValue
This class enables one to store an entry in the defaults table that isn't constructed until the first time it's looked up with one of the getXXX(key) methods.
UIManager.LookAndFeelInfo
Provides a little information about an installed LookAndFeel for the sake of configuring a menu or for initial application set up.
UnsupportedLookAndFeelException
An exception that indicates the requested look & feel management classes are not present on the user's system.
WindowConstants
Constants used to control the window-closing operation.

Classes in javax.swing used by javax.swing.border
Icon
A small fixed size picture, typically used to decorate components.

Classes in javax.swing used by javax.swing.colorchooser
Icon
A small fixed size picture, typically used to decorate components.
JColorChooser
JColorChooser provides a pane of controls designed to allow a user to manipulate and select a color.
JComponent
The base class for all Swing components except top-level containers.
JPanel
JPanel is a generic lightweight container.

Classes in javax.swing used by javax.swing.event
JComponent
The base class for all Swing components except top-level containers.
JInternalFrame
A lightweight object that provides many of the features of a native frame, including dragging, closing, becoming an icon, resizing, title display, and support for a menu bar.
MenuElement
Any component that can be placed into a menu should implement this interface.
MenuSelectionManager
A MenuSelectionManager owns the selection in menu hierarchy.
RowSorter
RowSorter provides the basis for sorting and filtering.

Classes in javax.swing used by javax.swing.filechooser
Icon
A small fixed size picture, typically used to decorate components.

Classes in javax.swing used by javax.swing.plaf
ActionMap
ActionMap provides mappings from Objects (called keys or Action names) to Actions.
ComponentInputMap
A ComponentInputMap is an InputMap associated with a particular JComponent.
Icon
A small fixed size picture, typically used to decorate components.
InputMap
InputMap provides a binding between an input event (currently only KeyStrokes are used) and an Object.
JComboBox
A component that combines a button or editable field and a drop-down list.
JComponent
The base class for all Swing components except top-level containers.
JFileChooser
JFileChooser provides a simple mechanism for the user to choose a file.
JList
A component that displays a list of objects and allows the user to select one or more items.
JOptionPane
JOptionPane makes it easy to pop up a standard dialog box that prompts users for a value or informs them of something.
JPopupMenu
An implementation of a popup menu -- a small window that pops up and displays a series of choices.
JSplitPane
JSplitPane is used to divide two (and only two) Components.
JTabbedPane
A component that lets the user switch between a group of components by clicking on a tab with a given title and/or icon.
JTree
A control that displays a set of hierarchical data as an outline.
Popup
Popups are used to display a Component to the user, typically on top of all the other Components in a particular containment hierarchy.

Classes in javax.swing used by javax.swing.plaf.basic
AbstractAction
This class provides default implementations for the JFC Action interface.
AbstractButton
Defines common behaviors for buttons and menu items.
AbstractListModel
The abstract definition for the data model that provides a List with its contents.
Action
The Action interface provides a useful extension to the ActionListener interface in cases where the same functionality may be accessed by several controls.
ActionMap
ActionMap provides mappings from Objects (called keys or Action names) to Actions.
BoxLayout
A layout manager that allows multiple components to be laid out either vertically or horizontally.
CellRendererPane
This class is inserted in between cell renderers and the components that use them.
ComboBoxEditor
The editor component used for JComboBox components.
ComboBoxModel
A data model for a combo box.
DesktopManager
DesktopManager objects are owned by a JDesktopPane object.
Icon
A small fixed size picture, typically used to decorate components.
JButton
An implementation of a "push" button.
JColorChooser
JColorChooser provides a pane of controls designed to allow a user to manipulate and select a color.
JComboBox
A component that combines a button or editable field and a drop-down list.
JComponent
The base class for all Swing components except top-level containers.
JDesktopPane
A container used to create a multiple-document interface or a virtual desktop.
JFileChooser
JFileChooser provides a simple mechanism for the user to choose a file.
JFrame
An extended version of java.awt.Frame that adds support for the JFC/Swing component architecture.
JInternalFrame
A lightweight object that provides many of the features of a native frame, including dragging, closing, becoming an icon, resizing, title display, and support for a menu bar.
JInternalFrame.JDesktopIcon
This component represents an iconified version of a JInternalFrame.
JLabel
A display area for a short text string or an image, or both.
JList
A component that displays a list of objects and allows the user to select one or more items.
JMenu
An implementation of a menu -- a popup window containing JMenuItems that is displayed when the user selects an item on the JMenuBar.
JMenuBar
An implementation of a menu bar.
JMenuItem
An implementation of an item in a menu.
JOptionPane
JOptionPane makes it easy to pop up a standard dialog box that prompts users for a value or informs them of something.
JPanel
JPanel is a generic lightweight container.
JPopupMenu
An implementation of a popup menu -- a small window that pops up and displays a series of choices.
JProgressBar
A component that visually displays the progress of some task.
JRootPane
A lightweight container used behind the scenes by JFrame, JDialog, JWindow, JApplet, and JInternalFrame.
JScrollBar
An implementation of a scrollbar.
JScrollPane
Provides a scrollable view of a lightweight component.
JSeparator
JSeparator provides a general purpose component for implementing divider lines - most commonly used as a divider between menu items that breaks them up into logical groupings.
JSlider
A component that lets the user graphically select a value by sliding a knob within a bounded interval.
JSpinner
A single line input field that lets the user select a number or an object value from an ordered sequence.
JSplitPane
JSplitPane is used to divide two (and only two) Components.
JTabbedPane
A component that lets the user switch between a group of components by clicking on a tab with a given title and/or icon.
JTable
The JTable is used to display and edit regular two-dimensional tables of cells.
JTextField
JTextField is a lightweight component that allows the editing of a single line of text.
JToolBar
JToolBar provides a component that is useful for displaying commonly used Actions or controls.
JTree
A control that displays a set of hierarchical data as an outline.
KeyStroke
A KeyStroke represents a key action on the keyboard, or equivalent input device.
ListCellRenderer
Identifies components that can be used as "rubber stamps" to paint the cells in a JList.
ListModel
This interface defines the methods components like JList use to get the value of each cell in a list and the length of the list.
ListSelectionModel
This interface represents the current state of the selection for any of the components that display a list of values with stable indices.
LookAndFeel
LookAndFeel, as the name implies, encapsulates a look and feel.
MenuElement
Any component that can be placed into a menu should implement this interface.
MenuSelectionManager
A MenuSelectionManager owns the selection in menu hierarchy.
RootPaneContainer
This interface is implemented by components that have a single JRootPane child: JDialog, JFrame, JWindow, JApplet, JInternalFrame.
ScrollPaneConstants
Constants used with the JScrollPane component.
SwingConstants
A collection of constants generally used for positioning and orienting components on the screen.
Timer
Fires one or more ActionEvents at specified intervals.
UIDefaults
A table of defaults for Swing components.

Classes in javax.swing used by javax.swing.plaf.metal
AbstractAction
This class provides default implementations for the JFC Action interface.
AbstractButton
Defines common behaviors for buttons and menu items.
AbstractListModel
The abstract definition for the data model that provides a List with its contents.
Action
The Action interface provides a useful extension to the ActionListener interface in cases where the same functionality may be accessed by several controls.
ActionMap
ActionMap provides mappings from Objects (called keys or Action names) to Actions.
CellRendererPane
This class is inserted in between cell renderers and the components that use them.
ComboBoxEditor
The editor component used for JComboBox components.
ComboBoxModel
A data model for a combo box.
DefaultListCellRenderer
Renders an item in a list.
Icon
A small fixed size picture, typically used to decorate components.
JButton
An implementation of a "push" button.
JComboBox
A component that combines a button or editable field and a drop-down list.
JComponent
The base class for all Swing components except top-level containers.
JFileChooser
JFileChooser provides a simple mechanism for the user to choose a file.
JInternalFrame
A lightweight object that provides many of the features of a native frame, including dragging, closing, becoming an icon, resizing, title display, and support for a menu bar.
JLabel
A display area for a short text string or an image, or both.
JList
A component that displays a list of objects and allows the user to select one or more items.
JMenu
An implementation of a menu -- a popup window containing JMenuItems that is displayed when the user selects an item on the JMenuBar.
JPanel
JPanel is a generic lightweight container.
JPopupMenu
An implementation of a popup menu -- a small window that pops up and displays a series of choices.
JScrollPane
Provides a scrollable view of a lightweight component.
JSeparator
JSeparator provides a general purpose component for implementing divider lines - most commonly used as a divider between menu items that breaks them up into logical groupings.
JSlider
A component that lets the user graphically select a value by sliding a knob within a bounded interval.
JToolBar
JToolBar provides a component that is useful for displaying commonly used Actions or controls.
LayoutStyle
LayoutStyle provides information about how to position components.
ListCellRenderer
Identifies components that can be used as "rubber stamps" to paint the cells in a JList.
ListModel
This interface defines the methods components like JList use to get the value of each cell in a list and the length of the list.
LookAndFeel
LookAndFeel, as the name implies, encapsulates a look and feel.
MenuElement
Any component that can be placed into a menu should implement this interface.
ScrollPaneConstants
Constants used with the JScrollPane component.
SwingConstants
A collection of constants generally used for positioning and orienting components on the screen.
UIDefaults
A table of defaults for Swing components.

Classes in javax.swing used by javax.swing.plaf.multi
JComboBox
A component that combines a button or editable field and a drop-down list.
JComponent
The base class for all Swing components except top-level containers.
JFileChooser
JFileChooser provides a simple mechanism for the user to choose a file.
JList
A component that displays a list of objects and allows the user to select one or more items.
JOptionPane
JOptionPane makes it easy to pop up a standard dialog box that prompts users for a value or informs them of something.
JPopupMenu
An implementation of a popup menu -- a small window that pops up and displays a series of choices.
JSplitPane
JSplitPane is used to divide two (and only two) Components.
JTabbedPane
A component that lets the user switch between a group of components by clicking on a tab with a given title and/or icon.
JTree
A control that displays a set of hierarchical data as an outline.
LookAndFeel
LookAndFeel, as the name implies, encapsulates a look and feel.
Popup
Popups are used to display a Component to the user, typically on top of all the other Components in a particular containment hierarchy.
UIDefaults
A table of defaults for Swing components.

Classes in javax.swing used by javax.swing.plaf.synth
Icon
A small fixed size picture, typically used to decorate components.
JComponent
The base class for all Swing components except top-level containers.
LookAndFeel
LookAndFeel, as the name implies, encapsulates a look and feel.
UIDefaults
A table of defaults for Swing components.

Classes in javax.swing used by javax.swing.table
CellEditor
This interface defines the methods any general editor should be able to implement.
DefaultRowSorter
An implementation of RowSorter that provides sorting and filtering around a grid-based data model.
JComponent
The base class for all Swing components except top-level containers.
JComponent.AccessibleJComponent
Inner class of JComponent used to provide default support for accessibility.
JLabel
A display area for a short text string or an image, or both.
JTable
The JTable is used to display and edit regular two-dimensional tables of cells.
ListSelectionModel
This interface represents the current state of the selection for any of the components that display a list of values with stable indices.
RowSorter
RowSorter provides the basis for sorting and filtering.
SwingConstants
A collection of constants generally used for positioning and orienting components on the screen.

Classes in javax.swing used by javax.swing.text
AbstractAction
This class provides default implementations for the JFC Action interface.
Action
The Action interface provides a useful extension to the ActionListener interface in cases where the same functionality may be accessed by several controls.
DropMode
Drop modes, used to determine the method by which a component tracks and indicates a drop location during drag and drop.
Icon
A small fixed size picture, typically used to decorate components.
JComponent
The base class for all Swing components except top-level containers.
JComponent.AccessibleJComponent
Inner class of JComponent used to provide default support for accessibility.
JEditorPane
A text component to edit various kinds of content.
JFormattedTextField
JFormattedTextField extends JTextField adding support for formatting arbitrary values, as well as retrieving a particular object once the user has edited the text.
JFormattedTextField.AbstractFormatter
Instances of AbstractFormatter are used by JFormattedTextField to handle the conversion both from an Object to a String, and back from a String to an Object.
JFormattedTextField.AbstractFormatterFactory
Instances of AbstractFormatterFactory are used by JFormattedTextField to obtain instances of AbstractFormatter which in turn are used to format values.
KeyStroke
A KeyStroke represents a key action on the keyboard, or equivalent input device.
Scrollable
An interface that provides information to a scrolling container like JScrollPane.
SizeRequirements
For the convenience of layout managers, calculates information about the size and position of components.
SwingConstants
A collection of constants generally used for positioning and orienting components on the screen.
TransferHandler.DropLocation
Represents a location where dropped data should be inserted.

Classes in javax.swing used by javax.swing.text.html
AbstractAction
This class provides default implementations for the JFC Action interface.
Action
The Action interface provides a useful extension to the ActionListener interface in cases where the same functionality may be accessed by several controls.
Icon
A small fixed size picture, typically used to decorate components.
JEditorPane
A text component to edit various kinds of content.
SizeRequirements
For the convenience of layout managers, calculates information about the size and position of components.
SwingConstants
A collection of constants generally used for positioning and orienting components on the screen.

Classes in javax.swing used by javax.swing.tree
CellEditor
This interface defines the methods any general editor should be able to implement.
DefaultListSelectionModel
Default data model for list selections.
Icon
A small fixed size picture, typically used to decorate components.
JComponent
The base class for all Swing components except top-level containers.
JLabel
A display area for a short text string or an image, or both.
JTextField
JTextField is a lightweight component that allows the editing of a single line of text.
JTree
A control that displays a set of hierarchical data as an outline.
Scrollable
An interface that provides information to a scrolling container like JScrollPane.
SwingConstants
A collection of constants generally used for positioning and orienting components on the screen.
Timer
Fires one or more ActionEvents at specified intervals.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AbstractAction

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class AbstractAction

java.lang.Object
    extended by  javax.swing.AbstractAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Direct Known Subclasses:
BasicDesktopPaneUI.CloseAction, BasicDesktopPaneUI.MaximizeAction, BasicDesktopPaneUI.MinimizeAction, BasicDesktopPaneUI.NavigateAction, BasicDesktopPaneUI.OpenAction, BasicFileChooserUI.ApproveSelectionAction, BasicFileChooserUI.CancelSelectionAction, BasicFileChooserUI.ChangeToParentDirectoryAction, BasicFileChooserUI.GoHomeAction, BasicFileChooserUI.NewFolderAction, BasicFileChooserUI.UpdateAction, BasicInternalFrameTitlePane.CloseAction, BasicInternalFrameTitlePane.IconifyAction, BasicInternalFrameTitlePane.MaximizeAction, BasicInternalFrameTitlePane.MoveAction, BasicInternalFrameTitlePane.RestoreAction, BasicInternalFrameTitlePane.SizeAction, BasicSliderUI.ActionScroller, BasicTreeUI.TreeCancelEditingAction, BasicTreeUI.TreeHomeAction, BasicTreeUI.TreeIncrementAction, BasicTreeUI.TreePageAction, BasicTreeUI.TreeToggleAction, BasicTreeUI.TreeTraverseAction, MetalFileChooserUI.DirectoryComboBoxAction, TextAction
public abstract class AbstractAction
extends Object
implements Action, Cloneable, Serializable

This class provides default implementations for the JFC Action interface. Standard behaviors like the get and set methods for Action object properties (icon, text, and enabled) are defined here. The developer need only subclass this abstract class and define the actionPerformed method.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
Action

Field Summary
protected SwingPropertyChangeSupport | changeSupport If any PropertyChangeListeners have been registered, the changeSupport field describes them.
protected boolean | enabled Specifies whether action is enabled; the default is true.
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
AbstractAction()
Defines an Action object with a default description string and default icon.
AbstractAction(String name)
Defines an Action object with the specified description string and a default icon.
AbstractAction(String name, Icon icon)
Defines an Action object with the specified description string and a the specified icon.
Method Summary
 void addPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list.
protected  Object clone()
Clones the abstract action.
protected  void firePropertyChange(String propertyName, Object oldValue, Object newValue)
Supports reporting bound property changes.
 Object[] getKeys()
Returns an array of Objects which are keys for which values have been set for this AbstractAction, or null if no keys have values set.
 PropertyChangeListener[] getPropertyChangeListeners()
Returns an array of all the PropertyChangeListeners added to this AbstractAction with addPropertyChangeListener().
 Object getValue(String key)
Gets the Object associated with the specified key.
 boolean isEnabled()
Returns true if the action is enabled.
 void putValue(String key, Object newValue)
Sets the Value associated with the specified key.
 void removePropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list.
 void setEnabled(boolean newValue)
Enables or disables the action.
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface java.awt.event.ActionListener
actionPerformed

Field Detail

enabled

protected boolean enabled
Specifies whether action is enabled; the default is true.

changeSupport

protected SwingPropertyChangeSupport changeSupport
If any PropertyChangeListeners have been registered, the changeSupport field describes them.

Constructor Detail

AbstractAction

public AbstractAction()
Defines an Action object with a default description string and default icon.

AbstractAction

public AbstractAction(String name)
Defines an Action object with the specified description string and a default icon.

AbstractAction

public AbstractAction(String name,
                      Icon icon)
Defines an Action object with the specified description string and a the specified icon.

Method Detail

getValue

public Object getValue(String key)
Gets the Object associated with the specified key.

Specified by:
getValue in interface Action
Parameters:
key - a string containing the specified key
Returns:
the binding Object stored with this key; if there are no keys, it will return null
See Also:
Action.getValue(java.lang.String)

putValue

public void putValue(String key,
                     Object newValue)
Sets the Value associated with the specified key.

Specified by:
putValue in interface Action
Parameters:
key - the String that identifies the stored object
newValue - the Object to store using this key
See Also:
Action.putValue(java.lang.String, java.lang.Object)

isEnabled

public boolean isEnabled()
Returns true if the action is enabled.

Specified by:
isEnabled in interface Action
Returns:
true if the action is enabled, false otherwise
See Also:
Action.isEnabled()

setEnabled

public void setEnabled(boolean newValue)
Enables or disables the action.

Specified by:
setEnabled in interface Action
Parameters:
newValue - true to enable the action, false to disable it
See Also:
Action.setEnabled(boolean)

getKeys

public Object[] getKeys()
Returns an array of Objects which are keys for which values have been set for this AbstractAction, or null if no keys have values set.

Returns:
an array of key objects, or null if no keys have values set
Since:
1.3

firePropertyChange

protected void firePropertyChange(String propertyName,
                                  Object oldValue,
                                  Object newValue)
Supports reporting bound property changes. This method can be called when a bound property has changed and it will send the appropriate PropertyChangeEvent to any registered PropertyChangeListeners.

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list. The listener is registered for all properties.

A PropertyChangeEvent will get fired in response to setting a bound property, e.g. setFont, setBackground, or setForeground. Note that if the current component is inheriting its foreground, background, or font from its container, then no event will be fired in response to a change in the inherited property.

Specified by:
addPropertyChangeListener in interface Action
Parameters:
listener - The PropertyChangeListener to be added
See Also:
Action.addPropertyChangeListener(java.beans.PropertyChangeListener)

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties.

Specified by:
removePropertyChangeListener in interface Action
Parameters:
listener - the PropertyChangeListener to be removed
See Also:
Action.removePropertyChangeListener(java.beans.PropertyChangeListener)

getPropertyChangeListeners

public PropertyChangeListener[] getPropertyChangeListeners()
Returns an array of all the PropertyChangeListeners added to this AbstractAction with addPropertyChangeListener().

Returns:
all of the PropertyChangeListeners added or an empty array if no listeners have been added
Since:
1.4

clone

protected Object clone()
                throws CloneNotSupportedException
Clones the abstract action. This gives the clone its own copy of the key/value list, which is not handled for you by Object.clone().

Overrides:
clone in class Object
Returns:
a clone of this instance.
Throws:
CloneNotSupportedException - if the object's class does not support the Cloneable interface. Subclasses that override the clone method can also throw this exception to indicate that an instance cannot be cloned.
See Also:
Cloneable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AbstractButton

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class AbstractButton

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.AbstractButton
All Implemented Interfaces:
ImageObserver, ItemSelectable, MenuContainer, Serializable, SwingConstants
Direct Known Subclasses:
JButton, JMenuItem, JToggleButton
public abstract class AbstractButton
extends JComponent
implements ItemSelectable, SwingConstants

Defines common behaviors for buttons and menu items.

Buttons can be configured, and to some degree controlled, by Actions. Using an Action with a button has many benefits beyond directly configuring a button. Refer to Swing Components Supporting Action for more details, and you can find more information in How to Use Actions, a section in The Java Tutorial.

For further information see How to Use Buttons, Check Boxes, and Radio Buttons, a section in The Java Tutorial.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected class | AbstractButton.AccessibleAbstractButton This class implements accessibility support for the AbstractButton class.
protected class | AbstractButton.ButtonChangeListener Extends ChangeListener to be serializable.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected ActionListener | actionListener The button model's ActionListener.
static String | BORDER_PAINTED_CHANGED_PROPERTY Identifies a change to having the border drawn, or having it not drawn.
protected ChangeEvent | changeEvent Only one ChangeEvent is needed per button instance since the event's only state is the source property.
protected ChangeListener | changeListener The button model's changeListener.
static String | CONTENT_AREA_FILLED_CHANGED_PROPERTY Identifies a change to having the button paint the content area.
static String | DISABLED_ICON_CHANGED_PROPERTY Identifies a change to the icon used when the button has been disabled.
static String | DISABLED_SELECTED_ICON_CHANGED_PROPERTY Identifies a change to the icon used when the button has been disabled and selected.
static String | FOCUS_PAINTED_CHANGED_PROPERTY Identifies a change to having the border highlighted when focused, or not.
static String | HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY Identifies a change in the button's horizontal alignment.
static String | HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY Identifies a change in the button's horizontal text position.
static String | ICON_CHANGED_PROPERTY Identifies a change to the icon that represents the button.
protected ItemListener | itemListener The button model's ItemListener.
static String | MARGIN_CHANGED_PROPERTY Identifies a change in the button's margins.
static String | MNEMONIC_CHANGED_PROPERTY Identifies a change to the button's mnemonic.
protected ButtonModel | model The data model that determines the button's state.
static String | MODEL_CHANGED_PROPERTY Identifies a change in the button model.
static String | PRESSED_ICON_CHANGED_PROPERTY Identifies a change to the icon used when the button has been pressed.
static String | ROLLOVER_ENABLED_CHANGED_PROPERTY Identifies a change from rollover enabled to disabled or back to enabled.
static String | ROLLOVER_ICON_CHANGED_PROPERTY Identifies a change to the icon used when the cursor is over the button.
static String | ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY Identifies a change to the icon used when the cursor is over the button and it has been selected.
static String | SELECTED_ICON_CHANGED_PROPERTY Identifies a change to the icon used when the button has been selected.
static String | TEXT_CHANGED_PROPERTY Identifies a change in the button's text.
static String | VERTICAL_ALIGNMENT_CHANGED_PROPERTY Identifies a change in the button's vertical alignment.
static String | VERTICAL_TEXT_POSITION_CHANGED_PROPERTY Identifies a change in the button's vertical text position.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
AbstractButton()
Method Summary
protected  void actionPropertyChanged(Action action, String propertyName)
Updates the button's state in response to property changes in the associated action.
 void addActionListener(ActionListener l)
Adds an ActionListener to the button.
 void addChangeListener(ChangeListener l)
Adds a ChangeListener to the button.
protected  void addImpl(Component comp, Object constraints, int index)
Adds the specified component to this container at the specified index, refer to Container.addImpl(Component, Object, int) for a complete description of this method.
 void addItemListener(ItemListener l)
Adds an ItemListener to the checkbox.
protected  int checkHorizontalKey(int key, String exception)
Verify that the key argument is a legal value for the horizontalAlignment and horizontalTextPosition properties.
protected  int checkVerticalKey(int key, String exception)
Verify that the key argument is a legal value for the vertical properties.
protected  void configurePropertiesFromAction(Action a)
Sets the properties on this button to match those in the specified Action.
protected  ActionListener createActionListener()
protected  PropertyChangeListener createActionPropertyChangeListener(Action a)
Creates and returns a PropertyChangeListener that is responsible for listening for changes from the specified Action and updating the appropriate properties.
protected  ChangeListener createChangeListener()
Subclasses that want to handle ChangeEvents differently can override this to return another ChangeListener implementation.
protected  ItemListener createItemListener()
 void doClick()
Programmatically perform a "click".
 void doClick(int pressTime)
Programmatically perform a "click".
protected  void fireActionPerformed(ActionEvent event)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireItemStateChanged(ItemEvent event)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireStateChanged()
Notifies all listeners that have registered interest for notification on this event type.
 Action getAction()
Returns the currently set Action for this ActionEvent source, or null if no Action is set.
 String getActionCommand()
Returns the action command for this button.
 ActionListener[] getActionListeners()
Returns an array of all the ActionListeners added to this AbstractButton with addActionListener().
 ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this AbstractButton with addChangeListener().
 Icon getDisabledIcon()
Returns the icon used by the button when it's disabled.
 Icon getDisabledSelectedIcon()
Returns the icon used by the button when it's disabled and selected.
 int getDisplayedMnemonicIndex()
Returns the character, as an index, that the look and feel should provide decoration for as representing the mnemonic character.
 boolean getHideActionText()
Returns the value of the hideActionText property, which determines whether the button displays text from the Action.
 int getHorizontalAlignment()
Returns the horizontal alignment of the icon and text.
 int getHorizontalTextPosition()
Returns the horizontal position of the text relative to the icon.
 Icon getIcon()
Returns the default icon.
 int getIconTextGap()
Returns the amount of space between the text and the icon displayed in this button.
 ItemListener[] getItemListeners()
Returns an array of all the ItemListeners added to this AbstractButton with addItemListener().
 String getLabel()
Deprecated. - Replaced by getText
 Insets getMargin()
Returns the margin between the button's border and the label.
 int getMnemonic()
Returns the keyboard mnemonic from the the current model.
 ButtonModel getModel()
Returns the model that this button represents.
 long getMultiClickThreshhold()
Gets the amount of time (in milliseconds) required between mouse press events for the button to generate the corresponding action events.
 Icon getPressedIcon()
Returns the pressed icon for the button.
 Icon getRolloverIcon()
Returns the rollover icon for the button.
 Icon getRolloverSelectedIcon()
Returns the rollover selection icon for the button.
 Icon getSelectedIcon()
Returns the selected icon for the button.
 Object[] getSelectedObjects()
Returns an array (length 1) containing the label or null if the button is not selected.
 String getText()
Returns the button's text.
 ButtonUI getUI()
Returns the L&F object that renders this component.
 int getVerticalAlignment()
Returns the vertical alignment of the text and icon.
 int getVerticalTextPosition()
Returns the vertical position of the text relative to the icon.
 boolean imageUpdate(Image img, int infoflags, int x, int y, int w, int h)
This is overridden to return false if the current Icon's Image is not equal to the passed in Image img.
protected  void init(String text, Icon icon)
 boolean isBorderPainted()
Gets the borderPainted property.
 boolean isContentAreaFilled()
Gets the contentAreaFilled property.
 boolean isFocusPainted()
Gets the paintFocus property.
 boolean isRolloverEnabled()
Gets the rolloverEnabled property.
 boolean isSelected()
Returns the state of the button.
protected  void paintBorder(Graphics g)
Paint the button's border if BorderPainted property is true and the button has a border.
protected  String paramString()
Returns a string representation of this AbstractButton.
 void removeActionListener(ActionListener l)
Removes an ActionListener from the button.
 void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the button.
 void removeItemListener(ItemListener l)
Removes an ItemListener from the button.
 void removeNotify()
Notifies this component that it no longer has a parent component.
 void setAction(Action a)
Sets the Action.
 void setActionCommand(String actionCommand)
Sets the action command for this button.
 void setBorderPainted(boolean b)
Sets the borderPainted property.
 void setContentAreaFilled(boolean b)
Sets the contentAreaFilled property.
 void setDisabledIcon(Icon disabledIcon)
Sets the disabled icon for the button.
 void setDisabledSelectedIcon(Icon disabledSelectedIcon)
Sets the disabled selection icon for the button.
 void setDisplayedMnemonicIndex(int index)
Provides a hint to the look and feel as to which character in the text should be decorated to represent the mnemonic.
 void setEnabled(boolean b)
Enables (or disables) the button.
 void setFocusPainted(boolean b)
Sets the paintFocus property, which must be true for the focus state to be painted.
 void setHideActionText(boolean hideActionText)
Sets the hideActionText property, which determines whether the button displays text from the Action.
 void setHorizontalAlignment(int alignment)
Sets the horizontal alignment of the icon and text.
 void setHorizontalTextPosition(int textPosition)
Sets the horizontal position of the text relative to the icon.
 void setIcon(Icon defaultIcon)
Sets the button's default icon.
 void setIconTextGap(int iconTextGap)
If both the icon and text properties are set, this property defines the space between them.
 void setLabel(String label)
Deprecated. - Replaced by setText(text)
 void setLayout(LayoutManager mgr)
Sets the layout manager for this container, refer to Container.setLayout(LayoutManager) for a complete description of this method.
 void setMargin(Insets m)
Sets space for margin between the button's border and the label.
 void setMnemonic(char mnemonic)
This method is now obsolete, please use setMnemonic(int) to set the mnemonic for a button.
 void setMnemonic(int mnemonic)
Sets the keyboard mnemonic on the current model.
 void setModel(ButtonModel newModel)
Sets the model that this button represents.
 void setMultiClickThreshhold(long threshhold)
Sets the amount of time (in milliseconds) required between mouse press events for the button to generate the corresponding action events.
 void setPressedIcon(Icon pressedIcon)
Sets the pressed icon for the button.
 void setRolloverEnabled(boolean b)
Sets the rolloverEnabled property, which must be true for rollover effects to occur.
 void setRolloverIcon(Icon rolloverIcon)
Sets the rollover icon for the button.
 void setRolloverSelectedIcon(Icon rolloverSelectedIcon)
Sets the rollover selected icon for the button.
 void setSelected(boolean b)
Sets the state of the button.
 void setSelectedIcon(Icon selectedIcon)
Sets the selected icon for the button.
 void setText(String text)
Sets the button's text.
 void setUI(ButtonUI ui)
Sets the L&F object that renders this component.
 void setVerticalAlignment(int alignment)
Sets the vertical alignment of the icon and text.
 void setVerticalTextPosition(int textPosition)
Sets the vertical position of the text relative to the icon.
 void updateUI()
Resets the UI property to a value from the current look and feel.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

MODEL_CHANGED_PROPERTY

public static final String MODEL_CHANGED_PROPERTY
Identifies a change in the button model.

See Also:
Constant Field Values

TEXT_CHANGED_PROPERTY

public static final String TEXT_CHANGED_PROPERTY
Identifies a change in the button's text.

See Also:
Constant Field Values

MNEMONIC_CHANGED_PROPERTY

public static final String MNEMONIC_CHANGED_PROPERTY
Identifies a change to the button's mnemonic.

See Also:
Constant Field Values

MARGIN_CHANGED_PROPERTY

public static final String MARGIN_CHANGED_PROPERTY
Identifies a change in the button's margins.

See Also:
Constant Field Values

VERTICAL_ALIGNMENT_CHANGED_PROPERTY

public static final String VERTICAL_ALIGNMENT_CHANGED_PROPERTY
Identifies a change in the button's vertical alignment.

See Also:
Constant Field Values

HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY

public static final String HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY
Identifies a change in the button's horizontal alignment.

See Also:
Constant Field Values

VERTICAL_TEXT_POSITION_CHANGED_PROPERTY

public static final String VERTICAL_TEXT_POSITION_CHANGED_PROPERTY
Identifies a change in the button's vertical text position.

See Also:
Constant Field Values

HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY

public static final String HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY
Identifies a change in the button's horizontal text position.

See Also:
Constant Field Values

BORDER_PAINTED_CHANGED_PROPERTY

public static final String BORDER_PAINTED_CHANGED_PROPERTY
Identifies a change to having the border drawn, or having it not drawn.

See Also:
Constant Field Values

FOCUS_PAINTED_CHANGED_PROPERTY

public static final String FOCUS_PAINTED_CHANGED_PROPERTY
Identifies a change to having the border highlighted when focused, or not.

See Also:
Constant Field Values

ROLLOVER_ENABLED_CHANGED_PROPERTY

public static final String ROLLOVER_ENABLED_CHANGED_PROPERTY
Identifies a change from rollover enabled to disabled or back to enabled.

See Also:
Constant Field Values

CONTENT_AREA_FILLED_CHANGED_PROPERTY

public static final String CONTENT_AREA_FILLED_CHANGED_PROPERTY
Identifies a change to having the button paint the content area.

See Also:
Constant Field Values

ICON_CHANGED_PROPERTY

public static final String ICON_CHANGED_PROPERTY
Identifies a change to the icon that represents the button.

See Also:
Constant Field Values

PRESSED_ICON_CHANGED_PROPERTY

public static final String PRESSED_ICON_CHANGED_PROPERTY
Identifies a change to the icon used when the button has been pressed.

See Also:
Constant Field Values

SELECTED_ICON_CHANGED_PROPERTY

public static final String SELECTED_ICON_CHANGED_PROPERTY
Identifies a change to the icon used when the button has been selected.

See Also:
Constant Field Values

ROLLOVER_ICON_CHANGED_PROPERTY

public static final String ROLLOVER_ICON_CHANGED_PROPERTY
Identifies a change to the icon used when the cursor is over the button.

See Also:
Constant Field Values

ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY

public static final String ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY
Identifies a change to the icon used when the cursor is over the button and it has been selected.

See Also:
Constant Field Values

DISABLED_ICON_CHANGED_PROPERTY

public static final String DISABLED_ICON_CHANGED_PROPERTY
Identifies a change to the icon used when the button has been disabled.

See Also:
Constant Field Values

DISABLED_SELECTED_ICON_CHANGED_PROPERTY

public static final String DISABLED_SELECTED_ICON_CHANGED_PROPERTY
Identifies a change to the icon used when the button has been disabled and selected.

See Also:
Constant Field Values

model

protected ButtonModel model
The data model that determines the button's state.

changeListener

protected ChangeListener changeListener
The button model's changeListener.

actionListener

protected ActionListener actionListener
The button model's ActionListener.

itemListener

protected ItemListener itemListener
The button model's ItemListener.

changeEvent

protected transient ChangeEvent changeEvent
Only one ChangeEvent is needed per button instance since the event's only state is the source property. The source of events generated is always "this".

Constructor Detail

AbstractButton

public AbstractButton()
Method Detail

setHideActionText

public void setHideActionText(boolean hideActionText)
Sets the hideActionText property, which determines whether the button displays text from the Action. This is useful only if an Action has been installed on the button.

Parameters:
hideActionText - true if the button's text property should not reflect that of the Action; the default is false
Since:
1.6
See Also:
Swing Components Supporting Action

getHideActionText

public boolean getHideActionText()
Returns the value of the hideActionText property, which determines whether the button displays text from the Action. This is useful only if an Action has been installed on the button.

Returns:
true if the button's text property should not reflect that of the Action; the default is false
Since:
1.6

getText

public String getText()
Returns the button's text.

Returns:
the buttons text
See Also:
setText(java.lang.String)

setText

public void setText(String text)
Sets the button's text.

Parameters:
text - the string used to set the text
See Also:
getText()

isSelected

public boolean isSelected()
Returns the state of the button. True if the toggle button is selected, false if it's not.

Returns:
true if the toggle button is selected, otherwise false

setSelected

public void setSelected(boolean b)
Sets the state of the button. Note that this method does not trigger an actionEvent. Call doClick to perform a programatic action change.

Parameters:
b - true if the button is selected, otherwise false

doClick

public void doClick()
Programmatically perform a "click". This does the same thing as if the user had pressed and released the button.

doClick

public void doClick(int pressTime)
Programmatically perform a "click". This does the same thing as if the user had pressed and released the button. The button stays visually "pressed" for pressTime milliseconds.

Parameters:
pressTime - the time to "hold down" the button, in milliseconds

setMargin

public void setMargin(Insets m)
Sets space for margin between the button's border and the label. Setting to null will cause the button to use the default margin. The button's default Border object will use this value to create the proper margin. However, if a non-default border is set on the button, it is that Border object's responsibility to create the appropriate margin space (else this property will effectively be ignored).

Parameters:
m - the space between the border and the label

getMargin

public Insets getMargin()
Returns the margin between the button's border and the label.

Returns:
an Insets object specifying the margin between the botton's border and the label
See Also:
setMargin(java.awt.Insets)

getIcon

public Icon getIcon()
Returns the default icon.

Returns:
the default Icon
See Also:
setIcon(javax.swing.Icon)

setIcon

public void setIcon(Icon defaultIcon)
Sets the button's default icon. This icon is also used as the "pressed" and "disabled" icon if there is no explicitly set pressed icon.

Parameters:
defaultIcon - the icon used as the default image
See Also:
getIcon(), setPressedIcon(javax.swing.Icon)

getPressedIcon

public Icon getPressedIcon()
Returns the pressed icon for the button.

Returns:
the pressedIcon property
See Also:
setPressedIcon(javax.swing.Icon)

setPressedIcon

public void setPressedIcon(Icon pressedIcon)
Sets the pressed icon for the button.

Parameters:
pressedIcon - the icon used as the "pressed" image
See Also:
getPressedIcon()

getSelectedIcon

public Icon getSelectedIcon()
Returns the selected icon for the button.

Returns:
the selectedIcon property
See Also:
setSelectedIcon(javax.swing.Icon)

setSelectedIcon

public void setSelectedIcon(Icon selectedIcon)
Sets the selected icon for the button.

Parameters:
selectedIcon - the icon used as the "selected" image
See Also:
getSelectedIcon()

getRolloverIcon

public Icon getRolloverIcon()
Returns the rollover icon for the button.

Returns:
the rolloverIcon property
See Also:
setRolloverIcon(javax.swing.Icon)

setRolloverIcon

public void setRolloverIcon(Icon rolloverIcon)
Sets the rollover icon for the button.

Parameters:
rolloverIcon - the icon used as the "rollover" image
See Also:
getRolloverIcon()

getRolloverSelectedIcon

public Icon getRolloverSelectedIcon()
Returns the rollover selection icon for the button.

Returns:
the rolloverSelectedIcon property
See Also:
setRolloverSelectedIcon(javax.swing.Icon)

setRolloverSelectedIcon

public void setRolloverSelectedIcon(Icon rolloverSelectedIcon)
Sets the rollover selected icon for the button.

Parameters:
rolloverSelectedIcon - the icon used as the "selected rollover" image
See Also:
getRolloverSelectedIcon()

getDisabledIcon

public Icon getDisabledIcon()
Returns the icon used by the button when it's disabled. If no disabled icon has been set this will forward the call to the look and feel to construct an appropriate disabled Icon.

Some look and feels might not render the disabled Icon, in which case they will ignore this.

Returns:
the disabledIcon property
See Also:
getPressedIcon(),
setDisabledIcon(javax.swing.Icon),
LookAndFeel.getDisabledIcon(javax.swing.JComponent, javax.swing.Icon)

setDisabledIcon

public void setDisabledIcon(Icon disabledIcon)
Sets the disabled icon for the button.

Parameters:
disabledIcon - the icon used as the disabled image
See Also:
getDisabledIcon()

getDisabledSelectedIcon

public Icon getDisabledSelectedIcon()
Returns the icon used by the button when it's disabled and selected. If no disabled selection icon has been set, this will forward the call to the LookAndFeel to construct an appropriate disabled Icon from the selection icon if it has been set and to getDisabledIcon() otherwise.

Some look and feels might not render the disabled selected Icon, in which case they will ignore this.

Returns:
the disabledSelectedIcon property
See Also:
getDisabledIcon(),
setDisabledSelectedIcon(javax.swing.Icon),
LookAndFeel.getDisabledSelectedIcon(javax.swing.JComponent, javax.swing.Icon)

setDisabledSelectedIcon

public void setDisabledSelectedIcon(Icon disabledSelectedIcon)
Sets the disabled selection icon for the button.

Parameters:
disabledSelectedIcon - the icon used as the disabled selection image
See Also:
getDisabledSelectedIcon()

getVerticalAlignment

public int getVerticalAlignment()
Returns the vertical alignment of the text and icon.

Returns:
the verticalAlignment property, one of the following values:
  • SwingConstants.CENTER (the default)
  • SwingConstants.TOP
  • SwingConstants.BOTTOM

setVerticalAlignment

public void setVerticalAlignment(int alignment)
Sets the vertical alignment of the icon and text.

Parameters:
alignment - one of the following values:
  • SwingConstants.CENTER (the default)
  • SwingConstants.TOP
  • SwingConstants.BOTTOM
Throws:
IllegalArgumentException - if the alignment is not one of the legal values listed above

getHorizontalAlignment

public int getHorizontalAlignment()
Returns the horizontal alignment of the icon and text. AbstractButton's default is SwingConstants.CENTER, but subclasses such as JCheckBox may use a different default.

Returns:
the horizontalAlignment property, one of the following values:
  • SwingConstants.RIGHT
  • SwingConstants.LEFT
  • SwingConstants.CENTER
  • SwingConstants.LEADING
  • SwingConstants.TRAILING

setHorizontalAlignment

public void setHorizontalAlignment(int alignment)
Sets the horizontal alignment of the icon and text. AbstractButton's default is SwingConstants.CENTER, but subclasses such as JCheckBox may use a different default.

Parameters:
alignment - the alignment value, one of the following values:
  • SwingConstants.RIGHT
  • SwingConstants.LEFT
  • SwingConstants.CENTER
  • SwingConstants.LEADING
  • SwingConstants.TRAILING
Throws:
IllegalArgumentException - if the alignment is not one of the valid values

getVerticalTextPosition

public int getVerticalTextPosition()
Returns the vertical position of the text relative to the icon.

Returns:
the verticalTextPosition property, one of the following values:
  • SwingConstants.CENTER (the default)
  • SwingConstants.TOP
  • SwingConstants.BOTTOM

setVerticalTextPosition

public void setVerticalTextPosition(int textPosition)
Sets the vertical position of the text relative to the icon.

Parameters:
textPosition - one of the following values:
  • SwingConstants.CENTER (the default)
  • SwingConstants.TOP
  • SwingConstants.BOTTOM

getHorizontalTextPosition

public int getHorizontalTextPosition()
Returns the horizontal position of the text relative to the icon.

Returns:
the horizontalTextPosition property, one of the following values:
  • SwingConstants.RIGHT
  • SwingConstants.LEFT
  • SwingConstants.CENTER
  • SwingConstants.LEADING
  • SwingConstants.TRAILING (the default)

setHorizontalTextPosition

public void setHorizontalTextPosition(int textPosition)
Sets the horizontal position of the text relative to the icon.

Parameters:
textPosition - one of the following values:
  • SwingConstants.RIGHT
  • SwingConstants.LEFT
  • SwingConstants.CENTER
  • SwingConstants.LEADING
  • SwingConstants.TRAILING (the default)
Throws:
IllegalArgumentException - if textPosition is not one of the legal values listed above

getIconTextGap

public int getIconTextGap()
Returns the amount of space between the text and the icon displayed in this button.

Returns:
an int equal to the number of pixels between the text and the icon.
Since:
1.4
See Also:
setIconTextGap(int)

setIconTextGap

public void setIconTextGap(int iconTextGap)
If both the icon and text properties are set, this property defines the space between them.

The default value of this property is 4 pixels.

This is a JavaBeans bound property.

Since:
1.4
See Also:
getIconTextGap()

checkHorizontalKey

protected int checkHorizontalKey(int key,
                                 String exception)
Verify that the key argument is a legal value for the horizontalAlignment and horizontalTextPosition properties. Valid values are:
  • SwingConstants.RIGHT
  • SwingConstants.LEFT
  • SwingConstants.CENTER
  • SwingConstants.LEADING
  • SwingConstants.TRAILING

Parameters:
key - the property value to check
exception - the message to use in the IllegalArgumentException that is thrown for an invalid value
Throws:
IllegalArgumentException - if key is not one of the legal values listed above
See Also:
setHorizontalTextPosition(int), setHorizontalAlignment(int)

checkVerticalKey

protected int checkVerticalKey(int key,
                               String exception)
Verify that the key argument is a legal value for the vertical properties. Valid values are:
  • SwingConstants.CENTER
  • SwingConstants.TOP
  • SwingConstants.BOTTOM

Parameters:
key - the property value to check
exception - the message to use in the IllegalArgumentException that is thrown for an invalid value
Throws:
IllegalArgumentException - if key is not one of the legal values listed above

removeNotify

public void removeNotify()
Notifies this component that it no longer has a parent component. When this method is invoked, any KeyboardActions set up in the the chain of parent components are removed.

Overrides:
removeNotify in class JComponent
Since:
1.6
See Also:
JComponent.registerKeyboardAction(java.awt.event.ActionListener, java.lang.String, javax.swing.KeyStroke, int)

setActionCommand

public void setActionCommand(String actionCommand)
Sets the action command for this button.

Parameters:
actionCommand - the action command for this button

getActionCommand

public String getActionCommand()
Returns the action command for this button.

Returns:
the action command for this button

setAction

public void setAction(Action a)
Sets the Action. The new Action replaces any previously set Action but does not affect ActionListeners independently added with addActionListener. If the Action is already a registered ActionListener for the button, it is not re-registered.

Setting the Action results in immediately changing all the properties described in Swing Components Supporting Action. Subsequently, the button's properties are automatically updated as the Action's properties change.

This method uses three other methods to set and help track the Action's property values. It uses the configurePropertiesFromAction method to immediately change the button's properties. To track changes in the Action's property values, this method registers the PropertyChangeListener returned by createActionPropertyChangeListener. The default PropertyChangeListener invokes the actionPropertyChanged method when a property in the Action changes.

Parameters:
a - the Action for the AbstractButton, or null
Since:
1.3
See Also:
Action,
getAction(),
configurePropertiesFromAction(javax.swing.Action),
createActionPropertyChangeListener(javax.swing.Action),
actionPropertyChanged(javax.swing.Action, java.lang.String)

getAction

public Action getAction()
Returns the currently set Action for this ActionEvent source, or null if no Action is set.

Returns:
the Action for this ActionEvent source, or null
Since:
1.3
See Also:
Action, setAction(javax.swing.Action)

configurePropertiesFromAction

protected void configurePropertiesFromAction(Action a)
Sets the properties on this button to match those in the specified Action. Refer to Swing Components Supporting Action for more details as to which properties this sets.

Parameters:
a - the Action from which to get the properties, or null
Since:
1.3
See Also:
Action, setAction(javax.swing.Action)

actionPropertyChanged

protected void actionPropertyChanged(Action action,
                                     String propertyName)
Updates the button's state in response to property changes in the associated action. This method is invoked from the PropertyChangeListener returned from createActionPropertyChangeListener. Subclasses do not normally need to invoke this. Subclasses that support additional Action properties should override this and configurePropertiesFromAction.

Refer to the table at Swing Components Supporting Action for a list of the properties this method sets.

Parameters:
action - the Action associated with this button
propertyName - the name of the property that changed
Since:
1.6
See Also:
Action, configurePropertiesFromAction(javax.swing.Action)

createActionPropertyChangeListener

protected PropertyChangeListener createActionPropertyChangeListener(Action a)
Creates and returns a PropertyChangeListener that is responsible for listening for changes from the specified Action and updating the appropriate properties.

Warning: If you subclass this do not create an anonymous inner class. If you do the lifetime of the button will be tied to that of the Action.

Parameters:
a - the button's action
Since:
1.3
See Also:
Actions, Action, setAction(javax.swing.Action)

isBorderPainted

public boolean isBorderPainted()
Gets the borderPainted property.

Returns:
the value of the borderPainted property
See Also:
setBorderPainted(boolean)

setBorderPainted

public void setBorderPainted(boolean b)
Sets the borderPainted property. If true and the button has a border, the border is painted. The default value for the borderPainted property is true.

Parameters:
b - if true and border property is not null, the border is painted
See Also:
isBorderPainted()

paintBorder

protected void paintBorder(Graphics g)
Paint the button's border if BorderPainted property is true and the button has a border.

Overrides:
paintBorder in class JComponent
Parameters:
g - the Graphics context in which to paint
See Also:
JComponent.paint(java.awt.Graphics), JComponent.setBorder(javax.swing.border.Border)

isFocusPainted

public boolean isFocusPainted()
Gets the paintFocus property.

Returns:
the paintFocus property
See Also:
setFocusPainted(boolean)

setFocusPainted

public void setFocusPainted(boolean b)
Sets the paintFocus property, which must be true for the focus state to be painted. The default value for the paintFocus property is true. Some look and feels might not paint focus state; they will ignore this property.

Parameters:
b - if true, the focus state should be painted
See Also:
isFocusPainted()

isContentAreaFilled

public boolean isContentAreaFilled()
Gets the contentAreaFilled property.

Returns:
the contentAreaFilled property
See Also:
setContentAreaFilled(boolean)

setContentAreaFilled

public void setContentAreaFilled(boolean b)
Sets the contentAreaFilled property. If true the button will paint the content area. If you wish to have a transparent button, such as an icon only button, for example, then you should set this to false. Do not call setOpaque(false). The default value for the the contentAreaFilled property is true.

This function may cause the component's opaque property to change.

The exact behavior of calling this function varies on a component-by-component and L&F-by-L&F basis.

Parameters:
b - if true, the content should be filled; if false the content area is not filled
See Also:
isContentAreaFilled(), JComponent.setOpaque(boolean)

isRolloverEnabled

public boolean isRolloverEnabled()
Gets the rolloverEnabled property.

Returns:
the value of the rolloverEnabled property
See Also:
setRolloverEnabled(boolean)

setRolloverEnabled

public void setRolloverEnabled(boolean b)
Sets the rolloverEnabled property, which must be true for rollover effects to occur. The default value for the rolloverEnabled property is false. Some look and feels might not implement rollover effects; they will ignore this property.

Parameters:
b - if true, rollover effects should be painted
See Also:
isRolloverEnabled()

getMnemonic

public int getMnemonic()
Returns the keyboard mnemonic from the the current model.

Returns:
the keyboard mnemonic from the model

setMnemonic

public void setMnemonic(int mnemonic)
Sets the keyboard mnemonic on the current model. The mnemonic is the key which when combined with the look and feel's mouseless modifier (usually Alt) will activate this button if focus is contained somewhere within this button's ancestor window.

A mnemonic must correspond to a single key on the keyboard and should be specified using one of the VK_XXX keycodes defined in java.awt.event.KeyEvent. Mnemonics are case-insensitive, therefore a key event with the corresponding keycode would cause the button to be activated whether or not the Shift modifier was pressed.

If the character defined by the mnemonic is found within the button's label string, the first occurrence of it will be underlined to indicate the mnemonic to the user.

Parameters:
mnemonic - the key code which represents the mnemonic
See Also:
KeyEvent, setDisplayedMnemonicIndex(int)

setMnemonic

public void setMnemonic(char mnemonic)
This method is now obsolete, please use setMnemonic(int) to set the mnemonic for a button. This method is only designed to handle character values which fall between 'a' and 'z' or 'A' and 'Z'.

Parameters:
mnemonic - a char specifying the mnemonic value
See Also:
setMnemonic(int)

setDisplayedMnemonicIndex

public void setDisplayedMnemonicIndex(int index)
                               throws IllegalArgumentException
Provides a hint to the look and feel as to which character in the text should be decorated to represent the mnemonic. Not all look and feels may support this. A value of -1 indicates either there is no mnemonic, the mnemonic character is not contained in the string, or the developer does not wish the mnemonic to be displayed.

The value of this is updated as the properties relating to the mnemonic change (such as the mnemonic itself, the text...). You should only ever have to call this if you do not wish the default character to be underlined. For example, if the text was 'Save As', with a mnemonic of 'a', and you wanted the 'A' to be decorated, as 'Save As', you would have to invoke setDisplayedMnemonicIndex(5) after invoking setMnemonic(KeyEvent.VK_A).

Parameters:
index - Index into the String to underline
Throws:
IllegalArgumentException - will be thrown if index is >= length of the text, or < -1
Since:
1.4
See Also:
getDisplayedMnemonicIndex()

getDisplayedMnemonicIndex

public int getDisplayedMnemonicIndex()
Returns the character, as an index, that the look and feel should provide decoration for as representing the mnemonic character.

Returns:
index representing mnemonic character
Since:
1.4
See Also:
setDisplayedMnemonicIndex(int)

setMultiClickThreshhold

public void setMultiClickThreshhold(long threshhold)
Sets the amount of time (in milliseconds) required between mouse press events for the button to generate the corresponding action events. After the initial mouse press occurs (and action event generated) any subsequent mouse press events which occur on intervals less than the threshhold will be ignored and no corresponding action event generated. By default the threshhold is 0, which means that for each mouse press, an action event will be fired, no matter how quickly the mouse clicks occur. In buttons where this behavior is not desirable (for example, the "OK" button in a dialog), this threshhold should be set to an appropriate positive value.

Parameters:
threshhold - the amount of time required between mouse press events to generate corresponding action events
Throws:
IllegalArgumentException - if threshhold < 0
Since:
1.4
See Also:
getMultiClickThreshhold()

getMultiClickThreshhold

public long getMultiClickThreshhold()
Gets the amount of time (in milliseconds) required between mouse press events for the button to generate the corresponding action events.

Returns:
the amount of time required between mouse press events to generate corresponding action events
Since:
1.4
See Also:
setMultiClickThreshhold(long)

getModel

public ButtonModel getModel()
Returns the model that this button represents.

Returns:
the model property
See Also:
setModel(javax.swing.ButtonModel)

setModel

public void setModel(ButtonModel newModel)
Sets the model that this button represents.

Parameters:
newModel - the new ButtonModel
See Also:
getModel()

getUI

public ButtonUI getUI()
Returns the L&F object that renders this component.

Returns:
the ButtonUI object
See Also:
setUI(javax.swing.plaf.ButtonUI)

setUI

public void setUI(ButtonUI ui)
Sets the L&F object that renders this component.

Parameters:
ui - the ButtonUI L&F object
See Also:
getUI()

updateUI

public void updateUI()
Resets the UI property to a value from the current look and feel. Subtypes of AbstractButton should override this to update the UI. For example, JButton might do the following:
      setUI((ButtonUI)UIManager.getUI(
          "ButtonUI", "javax.swing.plaf.basic.BasicButtonUI", this));

Overrides:
updateUI in class JComponent
See Also:
JComponent.setUI(javax.swing.plaf.ComponentUI),
UIManager.getLookAndFeel(),
UIManager.getUI(javax.swing.JComponent)

addImpl

protected void addImpl(Component comp,
                       Object constraints,
                       int index)
Adds the specified component to this container at the specified index, refer to Container.addImpl(Component, Object, int) for a complete description of this method.

Overrides:
addImpl in class Container
Parameters:
comp - the component to be added
constraints - an object expressing layout constraints for this component
index - the position in the container's list at which to insert the component, where -1 means append to the end
Throws:
IllegalArgumentException - if index is invalid
IllegalArgumentException - if adding the container's parent to itself
IllegalArgumentException - if adding a window to a container
Since:
1.5
See Also:
Container.add(Component),
Container.add(Component, int),
Container.add(Component, java.lang.Object),
LayoutManager,
LayoutManager2

setLayout

public void setLayout(LayoutManager mgr)
Sets the layout manager for this container, refer to Container.setLayout(LayoutManager) for a complete description of this method.

Overrides:
setLayout in class Container
Parameters:
mgr - the specified layout manager
Since:
1.5
See Also:
Container.doLayout(), Container.getLayout()

addChangeListener

public void addChangeListener(ChangeListener l)
Adds a ChangeListener to the button.

Parameters:
l - the listener to be added

removeChangeListener

public void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the button.

Parameters:
l - the listener to be removed

getChangeListeners

public ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this AbstractButton with addChangeListener().

Returns:
all of the ChangeListeners added or an empty array if no listeners have been added
Since:
1.4

fireStateChanged

protected void fireStateChanged()
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created.

See Also:
EventListenerList

addActionListener

public void addActionListener(ActionListener l)
Adds an ActionListener to the button.

Parameters:
l - the ActionListener to be added

removeActionListener

public void removeActionListener(ActionListener l)
Removes an ActionListener from the button. If the listener is the currently set Action for the button, then the Action is set to null.

Parameters:
l - the listener to be removed

getActionListeners

public ActionListener[] getActionListeners()
Returns an array of all the ActionListeners added to this AbstractButton with addActionListener().

Returns:
all of the ActionListeners added or an empty array if no listeners have been added
Since:
1.4

createChangeListener

protected ChangeListener createChangeListener()
Subclasses that want to handle ChangeEvents differently can override this to return another ChangeListener implementation.

Returns:
the new ChangeListener

fireActionPerformed

protected void fireActionPerformed(ActionEvent event)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the event parameter.

Parameters:
event - the ActionEvent object
See Also:
EventListenerList

fireItemStateChanged

protected void fireItemStateChanged(ItemEvent event)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the event parameter.

Parameters:
event - the ItemEvent object
See Also:
EventListenerList

createActionListener

protected ActionListener createActionListener()

createItemListener

protected ItemListener createItemListener()

setEnabled

public void setEnabled(boolean b)
Enables (or disables) the button.

Overrides:
setEnabled in class JComponent
Parameters:
b - true to enable the button, otherwise false
See Also:
Component.isEnabled(), Component.isLightweight()

getLabel

@Deprecated
public String getLabel()
Deprecated. - Replaced by getText

Returns the label text.

Returns:
a String containing the label

setLabel

@Deprecated
public void setLabel(String label)
Deprecated. - Replaced by setText(text)

Sets the label text.

Parameters:
label - a String containing the text

addItemListener

public void addItemListener(ItemListener l)
Adds an ItemListener to the checkbox.

Specified by:
addItemListener in interface ItemSelectable
Parameters:
l - the ItemListener to be added
See Also:
ItemEvent

removeItemListener

public void removeItemListener(ItemListener l)
Removes an ItemListener from the button.

Specified by:
removeItemListener in interface ItemSelectable
Parameters:
l - the ItemListener to be removed
See Also:
ItemEvent

getItemListeners

public ItemListener[] getItemListeners()
Returns an array of all the ItemListeners added to this AbstractButton with addItemListener().

Returns:
all of the ItemListeners added or an empty array if no listeners have been added
Since:
1.4

getSelectedObjects

public Object[] getSelectedObjects()
Returns an array (length 1) containing the label or null if the button is not selected.

Specified by:
getSelectedObjects in interface ItemSelectable
Returns:
an array containing 1 Object: the text of the button, if the item is selected; otherwise null

init

protected void init(String text,
                    Icon icon)

imageUpdate

public boolean imageUpdate(Image img,
                           int infoflags,
                           int x,
                           int y,
                           int w,
                           int h)
This is overridden to return false if the current Icon's Image is not equal to the passed in Image img.

Specified by:
imageUpdate in interface ImageObserver
Overrides:
imageUpdate in class Component
Parameters:
img - the Image to be compared
infoflags - flags used to repaint the button when the image is updated and which determine how much is to be painted
x - the x coordinate
y - the y coordinate
w - the width
h - the height
Returns:
false if the infoflags indicate that the image is completely loaded; true otherwise.
See Also:
ImageObserver, Component.imageUpdate(java.awt.Image, int, int, int, int, int)

paramString

protected String paramString()
Returns a string representation of this AbstractButton. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overriding paramString to provide information about the specific new aspects of the JFC components.

Overrides:
paramString in class JComponent
Returns:
a string representation of this AbstractButton
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AbstractButton.AccessibleAbstractButton

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class AbstractButton.AccessibleAbstractButton

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.AbstractButton.AccessibleAbstractButton
All Implemented Interfaces:
Serializable, AccessibleAction, AccessibleComponent, AccessibleExtendedComponent, AccessibleText, AccessibleValue
Direct Known Subclasses:
JButton.AccessibleJButton, JMenuItem.AccessibleJMenuItem, JToggleButton.AccessibleJToggleButton
Enclosing class:
AbstractButton
protected abstract class AbstractButton.AccessibleAbstractButton
extends JComponent.AccessibleJComponent
implements AccessibleAction, AccessibleValue, AccessibleText, AccessibleExtendedComponent

This class implements accessibility support for the AbstractButton class. It provides an implementation of the Java Accessibility API appropriate to button and menu item user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Since:
1.4

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Constructor Summary
protected AbstractButton.AccessibleAbstractButton()
Method Summary
boolean | doAccessibleAction(int i) Perform the specified Action on the object
AccessibleAction | getAccessibleAction() Get the AccessibleAction associated with this object.
int | getAccessibleActionCount() Returns the number of Actions available in this object.
String | getAccessibleActionDescription(int i) Return a description of the specified action of the object.
AccessibleIcon[] | getAccessibleIcon() Get the AccessibleIcons associated with this object if one or more exist.
AccessibleKeyBinding | getAccessibleKeyBinding() Returns key bindings associated with this object
String | getAccessibleName() Returns the accessible name of this object.
AccessibleRelationSet | getAccessibleRelationSet() Get the AccessibleRelationSet associated with this object if one exists.
AccessibleStateSet | getAccessibleStateSet() Get the state set of this object.
AccessibleText | getAccessibleText() Gets the AccessibleText associated with this object presenting text on the display.
AccessibleValue | getAccessibleValue() Get the AccessibleValue associated with this object.
String | getAfterIndex(int part, int index) Returns the String after a given index.
String | getAtIndex(int part, int index) Returns the String at a given index.
String | getBeforeIndex(int part, int index) Returns the String before a given index.
int | getCaretPosition() Return the zero-based offset of the caret.
AttributeSet | getCharacterAttribute(int i) Return the AttributeSet for a given character at a given index
Rectangle | getCharacterBounds(int i) Determine the bounding box of the character at the given index into the string.
int | getCharCount() Return the number of characters (valid indicies)
Number | getCurrentAccessibleValue() Get the value of this object as a Number.
int | getIndexAtPoint(Point p) Given a point in local coordinates, return the zero-based index of the character under that Point.
Number | getMaximumAccessibleValue() Get the maximum value of this object as a Number.
Number | getMinimumAccessibleValue() Get the minimum value of this object as a Number.
String | getSelectedText() Returns the portion of the text that is selected.
int | getSelectionEnd() Returns the end offset within the selected text.
int | getSelectionStart() Returns the start offset within the selected text.
String | getTitledBorderText() Returns the titled border text
String | getToolTipText() Returns the tool tip text
boolean | setCurrentAccessibleValue(Number n) Set the value of this object as a Number.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleRole, getBorderTitle, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleEditableText, getAccessibleSelection, getAccessibleTable, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

AbstractButton.AccessibleAbstractButton

protected AbstractButton.AccessibleAbstractButton()
Method Detail

getAccessibleName

public String getAccessibleName()
Returns the accessible name of this object.

Overrides:
getAccessibleName in class JComponent.AccessibleJComponent
Returns:
the localized name of the object -- can be null if this object does not have a name
See Also:
AccessibleContext.setAccessibleName(java.lang.String)

getAccessibleIcon

public AccessibleIcon[] getAccessibleIcon()
Get the AccessibleIcons associated with this object if one or more exist. Otherwise return null.

Overrides:
getAccessibleIcon in class AccessibleContext
Returns:
an array of AccessibleIcon if supported by object; otherwise return null
Since:
1.3
See Also:
AccessibleIcon

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Get the state set of this object.

Overrides:
getAccessibleStateSet in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleState containing the current state of the object
See Also:
AccessibleState

getAccessibleRelationSet

public AccessibleRelationSet getAccessibleRelationSet()
Get the AccessibleRelationSet associated with this object if one exists. Otherwise return null.

Overrides:
getAccessibleRelationSet in class AccessibleContext
Returns:
an AccessibleRelationSet if supported by object; otherwise return null
Since:
1.3
See Also:
AccessibleRelation

getAccessibleAction

public AccessibleAction getAccessibleAction()
Get the AccessibleAction associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleAction interface on behalf of itself.

Overrides:
getAccessibleAction in class AccessibleContext
Returns:
this object
See Also:
AccessibleAction

getAccessibleValue

public AccessibleValue getAccessibleValue()
Get the AccessibleValue associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleValue interface on behalf of itself.

Overrides:
getAccessibleValue in class AccessibleContext
Returns:
this object
See Also:
AccessibleValue

getAccessibleActionCount

public int getAccessibleActionCount()
Returns the number of Actions available in this object. The default behavior of a button is to have one action - toggle the button.

Specified by:
getAccessibleActionCount in interface AccessibleAction
Returns:
1, the number of Actions in this object

getAccessibleActionDescription

public String getAccessibleActionDescription(int i)
Return a description of the specified action of the object.

Specified by:
getAccessibleActionDescription in interface AccessibleAction
Parameters:
i - zero-based index of the actions
Returns:
a String description of the action
See Also:
AccessibleAction.getAccessibleActionCount()

doAccessibleAction

public boolean doAccessibleAction(int i)
Perform the specified Action on the object

Specified by:
doAccessibleAction in interface AccessibleAction
Parameters:
i - zero-based index of actions
Returns:
true if the the action was performed; else false.
See Also:
AccessibleAction.getAccessibleActionCount()

getCurrentAccessibleValue

public Number getCurrentAccessibleValue()
Get the value of this object as a Number.

Specified by:
getCurrentAccessibleValue in interface AccessibleValue
Returns:
An Integer of 0 if this isn't selected or an Integer of 1 if this is selected.
See Also:
AbstractButton.isSelected()

setCurrentAccessibleValue

public boolean setCurrentAccessibleValue(Number n)
Set the value of this object as a Number.

Specified by:
setCurrentAccessibleValue in interface AccessibleValue
Returns:
True if the value was set.
See Also:
AccessibleValue.getCurrentAccessibleValue()

getMinimumAccessibleValue

public Number getMinimumAccessibleValue()
Get the minimum value of this object as a Number.

Specified by:
getMinimumAccessibleValue in interface AccessibleValue
Returns:
an Integer of 0.
See Also:
AccessibleValue.getMaximumAccessibleValue()

getMaximumAccessibleValue

public Number getMaximumAccessibleValue()
Get the maximum value of this object as a Number.

Specified by:
getMaximumAccessibleValue in interface AccessibleValue
Returns:
An Integer of 1.
See Also:
AccessibleValue.getMinimumAccessibleValue()

getAccessibleText

public AccessibleText getAccessibleText()
Description copied from class: AccessibleContext
Gets the AccessibleText associated with this object presenting text on the display.

Overrides:
getAccessibleText in class AccessibleContext
Returns:
AccessibleText if supported by object; else return null
See Also:
AccessibleText

getIndexAtPoint

public int getIndexAtPoint(Point p)
Given a point in local coordinates, return the zero-based index of the character under that Point. If the point is invalid, this method returns -1. Note: the AbstractButton must have a valid size (e.g. have been added to a parent container whose ancestor container is a valid top-level window) for this method to be able to return a meaningful value.

Specified by:
getIndexAtPoint in interface AccessibleText
Parameters:
p - the Point in local coordinates
Returns:
the zero-based index of the character under Point p; if Point is invalid returns -1.
Since:
1.3

getCharacterBounds

public Rectangle getCharacterBounds(int i)
Determine the bounding box of the character at the given index into the string. The bounds are returned in local coordinates. If the index is invalid an empty rectangle is returned. Note: the AbstractButton must have a valid size (e.g. have been added to a parent container whose ancestor container is a valid top-level window) for this method to be able to return a meaningful value.

Specified by:
getCharacterBounds in interface AccessibleText
Parameters:
i - the index into the String
Returns:
the screen coordinates of the character's the bounding box, if index is invalid returns an empty rectangle.
Since:
1.3

getCharCount

public int getCharCount()
Return the number of characters (valid indicies)

Specified by:
getCharCount in interface AccessibleText
Returns:
the number of characters
Since:
1.3

getCaretPosition

public int getCaretPosition()
Return the zero-based offset of the caret. Note: That to the right of the caret will have the same index value as the offset (the caret is between two characters).

Specified by:
getCaretPosition in interface AccessibleText
Returns:
the zero-based offset of the caret.
Since:
1.3

getAtIndex

public String getAtIndex(int part,
                         int index)
Returns the String at a given index.

Specified by:
getAtIndex in interface AccessibleText
Parameters:
part - the AccessibleText.CHARACTER, AccessibleText.WORD, or AccessibleText.SENTENCE to retrieve
index - an index within the text >= 0
Returns:
the letter, word, or sentence, null for an invalid index or part
Since:
1.3

getAfterIndex

public String getAfterIndex(int part,
                            int index)
Returns the String after a given index.

Specified by:
getAfterIndex in interface AccessibleText
Parameters:
part - the AccessibleText.CHARACTER, AccessibleText.WORD, or AccessibleText.SENTENCE to retrieve
index - an index within the text >= 0
Returns:
the letter, word, or sentence, null for an invalid index or part
Since:
1.3

getBeforeIndex

public String getBeforeIndex(int part,
                             int index)
Returns the String before a given index.

Specified by:
getBeforeIndex in interface AccessibleText
Parameters:
part - the AccessibleText.CHARACTER, AccessibleText.WORD, or AccessibleText.SENTENCE to retrieve
index - an index within the text >= 0
Returns:
the letter, word, or sentence, null for an invalid index or part
Since:
1.3

getCharacterAttribute

public AttributeSet getCharacterAttribute(int i)
Return the AttributeSet for a given character at a given index

Specified by:
getCharacterAttribute in interface AccessibleText
Parameters:
i - the zero-based index into the text
Returns:
the AttributeSet of the character
Since:
1.3

getSelectionStart

public int getSelectionStart()
Returns the start offset within the selected text. If there is no selection, but there is a caret, the start and end offsets will be the same.

Specified by:
getSelectionStart in interface AccessibleText
Returns:
the index into the text of the start of the selection
Since:
1.3

getSelectionEnd

public int getSelectionEnd()
Returns the end offset within the selected text. If there is no selection, but there is a caret, the start and end offsets will be the same.

Specified by:
getSelectionEnd in interface AccessibleText
Returns:
the index into teh text of the end of the selection
Since:
1.3

getSelectedText

public String getSelectedText()
Returns the portion of the text that is selected.

Specified by:
getSelectedText in interface AccessibleText
Returns:
the String portion of the text that is selected
Since:
1.3

getToolTipText

public String getToolTipText()
Returns the tool tip text

Specified by:
getToolTipText in interface AccessibleExtendedComponent
Overrides:
getToolTipText in class JComponent.AccessibleJComponent
Returns:
the tool tip text, if supported, of the object; otherwise, null
Since:
1.4

getTitledBorderText

public String getTitledBorderText()
Returns the titled border text

Specified by:
getTitledBorderText in interface AccessibleExtendedComponent
Overrides:
getTitledBorderText in class JComponent.AccessibleJComponent
Returns:
the titled border text, if supported, of the object; otherwise, null
Since:
1.4

getAccessibleKeyBinding

public AccessibleKeyBinding getAccessibleKeyBinding()
Returns key bindings associated with this object

Specified by:
getAccessibleKeyBinding in interface AccessibleExtendedComponent
Overrides:
getAccessibleKeyBinding in class JComponent.AccessibleJComponent
Returns:
the key bindings, if supported, of the object; otherwise, null
Since:
1.4
See Also:
AccessibleKeyBinding
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AbstractButton.ButtonChangeListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class AbstractButton.ButtonChangeListener

java.lang.Object
    extended by  javax.swing.AbstractButton.ButtonChangeListener
All Implemented Interfaces:
Serializable, EventListener, ChangeListener
Enclosing class:
AbstractButton
protected class AbstractButton.ButtonChangeListener
extends Object
implements ChangeListener, Serializable

Extends ChangeListener to be serializable.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Method Summary
 void stateChanged(ChangeEvent e)
Invoked when the target of the listener has changed its state.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

stateChanged

public void stateChanged(ChangeEvent e)
Description copied from interface: ChangeListener
Invoked when the target of the listener has changed its state.

Specified by:
stateChanged in interface ChangeListener
Parameters:
e - a ChangeEvent object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AbstractCellEditor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class AbstractCellEditor

java.lang.Object
    extended by  javax.swing.AbstractCellEditor
All Implemented Interfaces:
Serializable, CellEditor
Direct Known Subclasses:
DefaultCellEditor
public abstract class AbstractCellEditor
extends Object
implements CellEditor, Serializable

Since:
1.3

Field Summary
protected ChangeEvent | changeEvent
protected EventListenerList | listenerList
Constructor Summary
AbstractCellEditor()
Method Summary
 void addCellEditorListener(CellEditorListener l)
Adds a CellEditorListener to the listener list.
 void cancelCellEditing()
Calls fireEditingCanceled.
protected  void fireEditingCanceled()
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireEditingStopped()
Notifies all listeners that have registered interest for notification on this event type.
 CellEditorListener[] getCellEditorListeners()
Returns an array of all the CellEditorListeners added to this AbstractCellEditor with addCellEditorListener().
 boolean isCellEditable(EventObject e)
Returns true.
 void removeCellEditorListener(CellEditorListener l)
Removes a CellEditorListener from the listener list.
 boolean shouldSelectCell(EventObject anEvent)
Returns true.
 boolean stopCellEditing()
Calls fireEditingStopped and returns true.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.swing.CellEditor
getCellEditorValue

Field Detail

listenerList

protected EventListenerList listenerList

changeEvent

protected transient ChangeEvent changeEvent
Constructor Detail

AbstractCellEditor

public AbstractCellEditor()
Method Detail

isCellEditable

public boolean isCellEditable(EventObject e)
Returns true.

Specified by:
isCellEditable in interface CellEditor
Parameters:
e - an event object
Returns:
true
See Also:
CellEditor.shouldSelectCell(java.util.EventObject)

shouldSelectCell

public boolean shouldSelectCell(EventObject anEvent)
Returns true.

Specified by:
shouldSelectCell in interface CellEditor
Parameters:
anEvent - an event object
Returns:
true
See Also:
CellEditor.isCellEditable(java.util.EventObject)

stopCellEditing

public boolean stopCellEditing()
Calls fireEditingStopped and returns true.

Specified by:
stopCellEditing in interface CellEditor
Returns:
true

cancelCellEditing

public void cancelCellEditing()
Calls fireEditingCanceled.

Specified by:
cancelCellEditing in interface CellEditor

addCellEditorListener

public void addCellEditorListener(CellEditorListener l)
Adds a CellEditorListener to the listener list.

Specified by:
addCellEditorListener in interface CellEditor
Parameters:
l - the new listener to be added

removeCellEditorListener

public void removeCellEditorListener(CellEditorListener l)
Removes a CellEditorListener from the listener list.

Specified by:
removeCellEditorListener in interface CellEditor
Parameters:
l - the listener to be removed

getCellEditorListeners

public CellEditorListener[] getCellEditorListeners()
Returns an array of all the CellEditorListeners added to this AbstractCellEditor with addCellEditorListener().

Returns:
all of the CellEditorListeners added or an empty array if no listeners have been added
Since:
1.4

fireEditingStopped

protected void fireEditingStopped()
Notifies all listeners that have registered interest for notification on this event type. The event instance is created lazily.

See Also:
EventListenerList

fireEditingCanceled

protected void fireEditingCanceled()
Notifies all listeners that have registered interest for notification on this event type. The event instance is created lazily.

See Also:
EventListenerList
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AbstractListModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class AbstractListModel

java.lang.Object
    extended by  javax.swing.AbstractListModel
All Implemented Interfaces:
Serializable, ListModel
Direct Known Subclasses:
BasicDirectoryModel, DefaultComboBoxModel, DefaultListModel, MetalFileChooserUI.DirectoryComboBoxModel, MetalFileChooserUI.FilterComboBoxModel
public abstract class AbstractListModel
extends Object
implements ListModel, Serializable

The abstract definition for the data model that provides a List with its contents.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected  EventListenerList listenerList
Constructor Summary
AbstractListModel()
Method Summary
 void addListDataListener(ListDataListener l)
Adds a listener to the list that's notified each time a change to the data model occurs.
protected  void fireContentsChanged(Object source, int index0, int index1)
AbstractListModel subclasses must call this method after one or more elements of the list change.
protected  void fireIntervalAdded(Object source, int index0, int index1)
AbstractListModel subclasses must call this method after one or more elements are added to the model.
protected  void fireIntervalRemoved(Object source, int index0, int index1)
AbstractListModel subclasses must call this method after one or more elements are removed from the model.
 ListDataListener[] getListDataListeners()
Returns an array of all the list data listeners registered on this AbstractListModel.
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this model.
 void removeListDataListener(ListDataListener l)
Removes a listener from the list that's notified each time a change to the data model occurs.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.swing.ListModel
getElementAt, getSize

Field Detail

listenerList

protected EventListenerList listenerList
Constructor Detail

AbstractListModel

public AbstractListModel()
Method Detail

addListDataListener

public void addListDataListener(ListDataListener l)
Adds a listener to the list that's notified each time a change to the data model occurs.

Specified by:
addListDataListener in interface ListModel
Parameters:
l - the ListDataListener to be added

removeListDataListener

public void removeListDataListener(ListDataListener l)
Removes a listener from the list that's notified each time a change to the data model occurs.

Specified by:
removeListDataListener in interface ListModel
Parameters:
l - the ListDataListener to be removed

getListDataListeners

public ListDataListener[] getListDataListeners()
Returns an array of all the list data listeners registered on this AbstractListModel.

Returns:
all of this model's ListDataListeners, or an empty array if no list data listeners are currently registered
Since:
1.4
See Also:
addListDataListener(javax.swing.event.ListDataListener), removeListDataListener(javax.swing.event.ListDataListener)

fireContentsChanged

protected void fireContentsChanged(Object source,
                                   int index0,
                                   int index1)
AbstractListModel subclasses must call this method after one or more elements of the list change. The changed elements are specified by the closed interval index0, index1 -- the endpoints are included. Note that index0 need not be less than or equal to index1.

Parameters:
source - the ListModel that changed, typically "this"
index0 - one end of the new interval
index1 - the other end of the new interval
See Also:
EventListenerList, DefaultListModel

fireIntervalAdded

protected void fireIntervalAdded(Object source,
                                 int index0,
                                 int index1)
AbstractListModel subclasses must call this method after one or more elements are added to the model. The new elements are specified by a closed interval index0, index1 -- the enpoints are included. Note that index0 need not be less than or equal to index1.

Parameters:
source - the ListModel that changed, typically "this"
index0 - one end of the new interval
index1 - the other end of the new interval
See Also:
EventListenerList, DefaultListModel

fireIntervalRemoved

protected void fireIntervalRemoved(Object source,
                                   int index0,
                                   int index1)
AbstractListModel subclasses must call this method after one or more elements are removed from the model. index0 and index1 are the end points of the interval that's been removed. Note that index0 need not be less than or equal to index1.

Parameters:
source - the ListModel that changed, typically "this"
index0 - one end of the removed interval, including index0
index1 - the other end of the removed interval, including index1
See Also:
EventListenerList, DefaultListModel

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this model. FooListeners are registered using the addFooListener method.

You can specify the listenerType argument with a class literal, such as FooListener.class. For example, you can query a list model m for its list data listeners with the following code:

ListDataListener[] ldls = (ListDataListener[])(m.getListeners(ListDataListener.class));
If no such listeners exist, this method returns an empty array.

Parameters:
listenerType - the type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener
Returns:
an array of all objects registered as FooListeners on this model, or an empty array if no such listeners have been added
Throws:
ClassCastException - if listenerType doesn't specify a class or interface that implements java.util.EventListener
Since:
1.3
See Also:
getListDataListeners()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AbstractSpinnerModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class AbstractSpinnerModel

java.lang.Object
    extended by  javax.swing.AbstractSpinnerModel
All Implemented Interfaces:
SpinnerModel
Direct Known Subclasses:
SpinnerDateModel, SpinnerListModel, SpinnerNumberModel
public abstract class AbstractSpinnerModel
extends Object
implements SpinnerModel

This class provides the ChangeListener part of the SpinnerModel interface that should be suitable for most concrete SpinnerModel implementations. Subclasses must provide an implementation of the setValue, getValue, getNextValue and getPreviousValue methods.

Since:
1.4
See Also:
JSpinner, SpinnerModel, SpinnerListModel, SpinnerNumberModel, SpinnerDateModel

Field Summary
protected  EventListenerList listenerList
The list of ChangeListeners for this model.
Constructor Summary
AbstractSpinnerModel()
Method Summary
 void addChangeListener(ChangeListener l)
Adds a ChangeListener to the model's listener list.
protected  void fireStateChanged()
Run each ChangeListeners stateChanged() method.
 ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this AbstractSpinnerModel with addChangeListener().
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
Return an array of all the listeners of the given type that were added to this model.
 void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the model's listener list.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.swing.SpinnerModel
getNextValue, getPreviousValue, getValue, setValue

Field Detail

listenerList

protected EventListenerList listenerList
The list of ChangeListeners for this model. Subclasses may store their own listeners here.

Constructor Detail

AbstractSpinnerModel

public AbstractSpinnerModel()
Method Detail

addChangeListener

public void addChangeListener(ChangeListener l)
Adds a ChangeListener to the model's listener list. The ChangeListeners must be notified when the models value changes.

Specified by:
addChangeListener in interface SpinnerModel
Parameters:
l - the ChangeListener to add
See Also:
removeChangeListener(javax.swing.event.ChangeListener), SpinnerModel.addChangeListener(javax.swing.event.ChangeListener)

removeChangeListener

public void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the model's listener list.

Specified by:
removeChangeListener in interface SpinnerModel
Parameters:
l - the ChangeListener to remove
See Also:
addChangeListener(javax.swing.event.ChangeListener), SpinnerModel.removeChangeListener(javax.swing.event.ChangeListener)

getChangeListeners

public ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this AbstractSpinnerModel with addChangeListener().

Returns:
all of the ChangeListeners added or an empty array if no listeners have been added
Since:
1.4

fireStateChanged

protected void fireStateChanged()
Run each ChangeListeners stateChanged() method.

See Also:
SpinnerModel.setValue(java.lang.Object), EventListenerList

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Return an array of all the listeners of the given type that were added to this model. For example to find all of the ChangeListeners added to this model:
 myAbstractSpinnerModel.getListeners(ChangeListener.class);

Parameters:
listenerType - the type of listeners to return, e.g. ChangeListener.class
Returns:
all of the objects receiving listenerType notifications from this model
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Action

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface Action

All Superinterfaces:
ActionListener, EventListener
All Known Implementing Classes:
AbstractAction, BasicDesktopPaneUI.CloseAction, BasicDesktopPaneUI.MaximizeAction, BasicDesktopPaneUI.MinimizeAction, BasicDesktopPaneUI.NavigateAction, BasicDesktopPaneUI.OpenAction, BasicFileChooserUI.ApproveSelectionAction, BasicFileChooserUI.CancelSelectionAction, BasicFileChooserUI.ChangeToParentDirectoryAction, BasicFileChooserUI.GoHomeAction, BasicFileChooserUI.NewFolderAction, BasicFileChooserUI.UpdateAction, BasicInternalFrameTitlePane.CloseAction, BasicInternalFrameTitlePane.IconifyAction, BasicInternalFrameTitlePane.MaximizeAction, BasicInternalFrameTitlePane.MoveAction, BasicInternalFrameTitlePane.RestoreAction, BasicInternalFrameTitlePane.SizeAction, BasicSliderUI.ActionScroller, BasicTreeUI.TreeCancelEditingAction, BasicTreeUI.TreeHomeAction, BasicTreeUI.TreeIncrementAction, BasicTreeUI.TreePageAction, BasicTreeUI.TreeToggleAction, BasicTreeUI.TreeTraverseAction, DefaultEditorKit.BeepAction, DefaultEditorKit.CopyAction, DefaultEditorKit.CutAction, DefaultEditorKit.DefaultKeyTypedAction, DefaultEditorKit.InsertBreakAction, DefaultEditorKit.InsertContentAction, DefaultEditorKit.InsertTabAction, DefaultEditorKit.PasteAction, HTMLEditorKit.HTMLTextAction, HTMLEditorKit.InsertHTMLTextAction, MetalFileChooserUI.DirectoryComboBoxAction, StyledEditorKit.AlignmentAction, StyledEditorKit.BoldAction, StyledEditorKit.FontFamilyAction, StyledEditorKit.FontSizeAction, StyledEditorKit.ForegroundAction, StyledEditorKit.ItalicAction, StyledEditorKit.StyledTextAction, StyledEditorKit.UnderlineAction, TextAction
public interface Action
extends ActionListener

The Action interface provides a useful extension to the ActionListener interface in cases where the same functionality may be accessed by several controls.

In addition to the actionPerformed method defined by the ActionListener interface, this interface allows the application to define, in a single place:

  • One or more text strings that describe the function. These strings can be used, for example, to display the flyover text for a button or to set the text in a menu item.
  • One or more icons that depict the function. These icons can be used for the images in a menu control, or for composite entries in a more sophisticated user interface.
  • The enabled/disabled state of the functionality. Instead of having to separately disable the menu item and the toolbar button, the application can disable the function that implements this interface. All components which are registered as listeners for the state change then know to disable event generation for that item and to modify the display accordingly.

This interface can be added to an existing class or used to create an adapter (typically, by subclassing AbstractAction). The Action object can then be added to multiple Action-aware containers and connected to Action-capable components. The GUI controls can then be activated or deactivated all at once by invoking the Action object's setEnabled method.

Note that Action implementations tend to be more expensive in terms of storage than a typical ActionListener, which does not offer the benefits of centralized control of functionality and broadcast of property changes. For this reason, you should take care to only use Actions where their benefits are desired, and use simple ActionListeners elsewhere.

Swing Components Supporting Action

Many of Swing's components have an Action property. When an Action is set on a component, the following things happen:

  • The Action is added as an ActionListener to the component.
  • The component configures some of its properties to match the Action.
  • The component installs a PropertyChangeListener on the Action so that the component can change its properties to reflect changes in the Action's properties.

The following table describes the properties used by Swing components that support Actions. In the table, button refers to any AbstractButton subclass, which includes not only JButton but also classes such as JMenuItem. Unless otherwise stated, a null property value in an Action (or a Action that is null) results in the button's corresponding property being set to null.

Component Property | Components | Action Key | Notes
enabled | All | The isEnabled method |
toolTipText | All | SHORT_DESCRIPTION |
actionCommand | All | ACTION_COMMAND_KEY |
mnemonic | All buttons | MNEMONIC_KEY | A null value or Action results in the button's mnemonic property being set to '\0'.
text | All buttons | NAME | If you do not want the text of the button to mirror that of the Action, set the property hideActionText to true. If hideActionText is true, setting the Action changes the text of the button to null and any changes to NAME are ignored. hideActionText is useful for tool bar buttons that typically only show an Icon. JToolBar.add(Action) sets the property to true if the Action has a non-null value for LARGE_ICON_KEY or SMALL_ICON.
displayedMnemonicIndex | All buttons | DISPLAYED_MNEMONIC_INDEX_KEY | If the value of DISPLAYED_MNEMONIC_INDEX_KEY is beyond the bounds of the text, it is ignored. When setAction is called, if the value from the Action is null, the displayed mnemonic index is not updated. In any subsequent changes to DISPLAYED_MNEMONIC_INDEX_KEY, null is treated as -1.
icon | All buttons except of JCheckBox, JToggleButton and JRadioButton. | either LARGE_ICON_KEY or SMALL_ICON | The JMenuItem subclasses only use SMALL_ICON. All other buttons will use LARGE_ICON_KEY; if the value is null they use SMALL_ICON.
accelerator | All JMenuItem subclasses, with the exception of JMenu. | ACCELERATOR_KEY |
selected | JToggleButton, JCheckBox, JRadioButton, JCheckBoxMenuItem and JRadioButtonMenuItem | SELECTED_KEY | Components that honor this property only use the value if it is non-null. For example, if you set an Action that has a null value for SELECTED_KEY on a JToggleButton, the JToggleButton will not update it's selected state in any way. Similarly, any time the JToggleButton's selected state changes it will only set the value back on the Action if the Action has a non-null value for SELECTED_KEY. Components that honor this property keep their selected state in sync with this property. When the same Action is used with multiple components, all the components keep their selected state in sync with this property. Mutually exclusive buttons, such as JToggleButtons in a ButtonGroup, force only one of the buttons to be selected. As such, do not use the same Action that defines a value for the SELECTED_KEY property with multiple mutually exclusive buttons.

JPopupMenu, JToolBar and JMenu all provide convenience methods for creating a component and setting the Action on the corresponding component. Refer to each of these classes for more information.

Action uses PropertyChangeListener to inform listeners the Action has changed. The beans specification indicates that a null property name can be used to indicate multiple values have changed. By default Swing components that take an Action do not handle such a change. To indicate that Swing should treat null according to the beans specification set the system property swing.actions.reconfigureOnNull to the String value true.

See Also:
AbstractAction

Field Summary
static String | ACCELERATOR_KEY The key used for storing a KeyStroke to be used as the accelerator for the action.
static String | ACTION_COMMAND_KEY The key used to determine the command String for the ActionEvent that will be created when an Action is going to be notified as the result of residing in a Keymap associated with a JComponent.
static String | DEFAULT Not currently used.
static String | DISPLAYED_MNEMONIC_INDEX_KEY The key used for storing an Integer that corresponds to the index in the text (identified by the NAME property) that the decoration for a mnemonic should be rendered at.
static String | LARGE_ICON_KEY The key used for storing an Icon.
static String | LONG_DESCRIPTION The key used for storing a longer String description for the action, could be used for context-sensitive help.
static String | MNEMONIC_KEY The key used for storing an Integer that corresponds to one of the KeyEvent key codes.
static String | NAME The key used for storing the String name for the action, used for a menu or button.
static String | SELECTED_KEY The key used for storing a Boolean that corresponds to the selected state.
static String | SHORT_DESCRIPTION The key used for storing a short String description for the action, used for tooltip text.
static String | SMALL_ICON The key used for storing a small Icon, such as ImageIcon.
Method Summary
void | addPropertyChangeListener(PropertyChangeListener listener) Adds a PropertyChange listener.
Object | getValue(String key) Gets one of this object's properties using the associated key.
boolean | isEnabled() Returns the enabled state of the Action.
void | putValue(String key, Object value) Sets one of this object's properties using the associated key.
void | removePropertyChangeListener(PropertyChangeListener listener) Removes a PropertyChange listener.
void | setEnabled(boolean b) Sets the enabled state of the Action.
Methods inherited from interface java.awt.event.ActionListener
actionPerformed

Field Detail

DEFAULT

static final String DEFAULT
Not currently used.

See Also:
Constant Field Values

NAME

static final String NAME
The key used for storing the String name for the action, used for a menu or button.

See Also:
Constant Field Values

SHORT_DESCRIPTION

static final String SHORT_DESCRIPTION
The key used for storing a short String description for the action, used for tooltip text.

See Also:
Constant Field Values

LONG_DESCRIPTION

static final String LONG_DESCRIPTION
The key used for storing a longer String description for the action, could be used for context-sensitive help.

See Also:
Constant Field Values

SMALL_ICON

static final String SMALL_ICON
The key used for storing a small Icon, such as ImageIcon. This is typically used with menus such as JMenuItem.

If the same Action is used with menus and buttons you'll typically specify both a SMALL_ICON and a LARGE_ICON_KEY. The menu will use the SMALL_ICON and the button will use the LARGE_ICON_KEY.

See Also:
Constant Field Values

ACTION_COMMAND_KEY

static final String ACTION_COMMAND_KEY
The key used to determine the command String for the ActionEvent that will be created when an Action is going to be notified as the result of residing in a Keymap associated with a JComponent.

See Also:
Constant Field Values

ACCELERATOR_KEY

static final String ACCELERATOR_KEY
The key used for storing a KeyStroke to be used as the accelerator for the action.

Since:
1.3
See Also:
Constant Field Values

MNEMONIC_KEY

static final String MNEMONIC_KEY
The key used for storing an Integer that corresponds to one of the KeyEvent key codes. The value is commonly used to specify a mnemonic. For example: myAction.putValue(Action.MNEMONIC_KEY, KeyEvent.VK_A) sets the mnemonic of myAction to 'a'.

Since:
1.3
See Also:
Constant Field Values

SELECTED_KEY

static final String SELECTED_KEY
The key used for storing a Boolean that corresponds to the selected state. This is typically used only for components that have a meaningful selection state. For example, JRadioButton and JCheckBox make use of this but instances of JMenu don't.

This property differs from the others in that it is both read by the component and set by the component. For example, if an Action is attached to a JCheckBox the selected state of the JCheckBox will be set from that of the Action. If the user clicks on the JCheckBox the selected state of the JCheckBox and the Action will both be updated.

Note: the value of this field is prefixed with 'Swing' to avoid possible collisions with existing Actions.

Since:
1.6
See Also:
Constant Field Values

DISPLAYED_MNEMONIC_INDEX_KEY

static final String DISPLAYED_MNEMONIC_INDEX_KEY
The key used for storing an Integer that corresponds to the index in the text (identified by the NAME property) that the decoration for a mnemonic should be rendered at. If the value of this property is greater than or equal to the length of the text, it will treated as -1.

Note: the value of this field is prefixed with 'Swing' to avoid possible collisions with existing Actions.

Since:
1.6
See Also:
AbstractButton.setDisplayedMnemonicIndex(int), Constant Field Values

LARGE_ICON_KEY

static final String LARGE_ICON_KEY
The key used for storing an Icon. This is typically used by buttons, such as JButton and JToggleButton.

If the same Action is used with menus and buttons you'll typically specify both a SMALL_ICON and a LARGE_ICON_KEY. The menu will use the SMALL_ICON and the button the LARGE_ICON_KEY.

Note: the value of this field is prefixed with 'Swing' to avoid possible collisions with existing Actions.

Since:
1.6
See Also:
Constant Field Values
Method Detail

getValue

Object getValue(String key)
Gets one of this object's properties using the associated key.

See Also:
putValue(java.lang.String, java.lang.Object)

putValue

void putValue(String key,
              Object value)
Sets one of this object's properties using the associated key. If the value has changed, a PropertyChangeEvent is sent to listeners.

Parameters:
key - a String containing the key
value - an Object value

setEnabled

void setEnabled(boolean b)
Sets the enabled state of the Action. When enabled, any component associated with this object is active and able to fire this object's actionPerformed method. If the value has changed, a PropertyChangeEvent is sent to listeners.

Parameters:
b - true to enable this Action, false to disable it

isEnabled

boolean isEnabled()
Returns the enabled state of the Action. When enabled, any component associated with this object is active and able to fire this object's actionPerformed method.

Returns:
true if this Action is enabled

addPropertyChangeListener

void addPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChange listener. Containers and attached components use these methods to register interest in this Action object. When its enabled state or other property changes, the registered listeners are informed of the change.

Parameters:
listener - a PropertyChangeListener object

removePropertyChangeListener

void removePropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChange listener.

Parameters:
listener - a PropertyChangeListener object
See Also:
addPropertyChangeListener(java.beans.PropertyChangeListener)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ActionMap

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class ActionMap

java.lang.Object
    extended by  javax.swing.ActionMap
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
ActionMapUIResource
public class ActionMap
extends Object
implements Serializable

ActionMap provides mappings from Objects (called keys or Action names) to Actions. An ActionMap is usually used with an InputMap to locate a particular action when a key is pressed. As with InputMap, an ActionMap can have a parent that is searched for keys not defined in the ActionMap.

As with InputMap if you create a cycle, eg:

   ActionMap am = new ActionMap();
   ActionMap bm = new ActionMap():
   am.setParent(bm);
   bm.setParent(am);
some of the methods will cause a StackOverflowError to be thrown.

Since:
1.3
See Also:
InputMap

Constructor Summary
ActionMap()
Creates an ActionMap with no parent and no mappings.
Method Summary
Object[] | allKeys() Returns an array of the keys defined in this ActionMap and its parent.
void | clear() Removes all the mappings from this ActionMap.
Action | get(Object key) Returns the binding for key, messaging the parent ActionMap if the binding is not locally defined.
ActionMap | getParent() Returns this ActionMap's parent.
Object[] | keys() Returns the Action names that are bound in this ActionMap.
void | put(Object key, Action action) Adds a binding for key to action.
void | remove(Object key) Removes the binding for key from this ActionMap.
void | setParent(ActionMap map) Sets this ActionMap's parent.
int | size() Returns the number of KeyStroke bindings.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ActionMap

public ActionMap()
Creates an ActionMap with no parent and no mappings.

Method Detail

setParent

public void setParent(ActionMap map)
Sets this ActionMap's parent.

Parameters:
map - the ActionMap that is the parent of this one

getParent

public ActionMap getParent()
Returns this ActionMap's parent.

Returns:
the ActionMap that is the parent of this one, or null if this ActionMap has no parent

put

public void put(Object key,
                Action action)
Adds a binding for key to action. If action is null, this removes the current binding for key.

In most instances, key will be action.getValue(NAME).

get

public Action get(Object key)
Returns the binding for key, messaging the parent ActionMap if the binding is not locally defined.

remove

public void remove(Object key)
Removes the binding for key from this ActionMap.

clear

public void clear()
Removes all the mappings from this ActionMap.

keys

public Object[] keys()
Returns the Action names that are bound in this ActionMap.

size

public int size()
Returns the number of KeyStroke bindings.

allKeys

public Object[] allKeys()
Returns an array of the keys defined in this ActionMap and its parent. This method differs from keys() in that this method includes the keys defined in the parent.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


border

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.swing.border

Provides classes and interface for drawing specialized borders around a Swing component.

See:
Description

Interface Summary
Border Interface describing an object capable of rendering a border around the edges of a swing component.

Class Summary
AbstractBorder | A class that implements an empty border with no size.
BevelBorder | A class which implements a simple two-line bevel border.
CompoundBorder | A composite Border class used to compose two Border objects into a single border by nesting an inside Border object within the insets of an outside Border object.
EmptyBorder | A class which provides an empty, transparent border which takes up space but does no drawing.
EtchedBorder | A class which implements a simple etched border which can either be etched-in or etched-out.
LineBorder | A class which implements a line border of arbitrary thickness and of a single color.
MatteBorder | A class which provides a matte-like border of either a solid color or a tiled icon.
SoftBevelBorder | A class which implements a raised or lowered bevel with softened corners.
TitledBorder | A class which implements an arbitrary border with the addition of a String title in a specified position and justification.

Package javax.swing.border Description

Provides classes and interface for drawing specialized borders around a Swing component. You can subclass these classes to create customized borders for your components instead of using the default borders provided by the look-and-feel being used.

Note: Most of the Swing API is not thread safe. For details, see Threads and Swing, a section in The Java Tutorial.

Related Documentation

For overviews, tutorials, examples, guides, and tool documentation, please see:
  • How to Use Borders, a section in The Java Tutorial

Since:
1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.swing.border Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.swing.border

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.swing.border.AbstractBorder (implements javax.swing.border.Border, java.io.Serializable)
      • javax.swing.border.BevelBorder
        • javax.swing.border.SoftBevelBorder
      • javax.swing.border.CompoundBorder
      • javax.swing.border.EmptyBorder (implements java.io.Serializable)
        • javax.swing.border.MatteBorder
      • javax.swing.border.EtchedBorder
      • javax.swing.border.LineBorder
      • javax.swing.border.TitledBorder

Interface Hierarchy

  • javax.swing.border.Border
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.swing.border

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.swing.border

Packages that use javax.swing.border
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.border | Provides classes and interface for drawing specialized borders around a Swing component.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Classes in javax.swing.border used by javax.swing
Border
Interface describing an object capable of rendering a border around the edges of a swing component.
CompoundBorder
A composite Border class used to compose two Border objects into a single border by nesting an inside Border object within the insets of an outside Border object.
MatteBorder
A class which provides a matte-like border of either a solid color or a tiled icon.
TitledBorder
A class which implements an arbitrary border with the addition of a String title in a specified position and justification.

Classes in javax.swing.border used by javax.swing.border
AbstractBorder
A class that implements an empty border with no size.
BevelBorder
A class which implements a simple two-line bevel border.
Border
Interface describing an object capable of rendering a border around the edges of a swing component.
EmptyBorder
A class which provides an empty, transparent border which takes up space but does no drawing.

Classes in javax.swing.border used by javax.swing.plaf
AbstractBorder
A class that implements an empty border with no size.
BevelBorder
A class which implements a simple two-line bevel border.
Border
Interface describing an object capable of rendering a border around the edges of a swing component.
CompoundBorder
A composite Border class used to compose two Border objects into a single border by nesting an inside Border object within the insets of an outside Border object.
EmptyBorder
A class which provides an empty, transparent border which takes up space but does no drawing.
EtchedBorder
A class which implements a simple etched border which can either be etched-in or etched-out.
LineBorder
A class which implements a line border of arbitrary thickness and of a single color.
MatteBorder
A class which provides a matte-like border of either a solid color or a tiled icon.
TitledBorder
A class which implements an arbitrary border with the addition of a String title in a specified position and justification.

Classes in javax.swing.border used by javax.swing.plaf.basic
AbstractBorder
A class that implements an empty border with no size.
Border
Interface describing an object capable of rendering a border around the edges of a swing component.

Classes in javax.swing.border used by javax.swing.plaf.metal
AbstractBorder
A class that implements an empty border with no size.
Border
Interface describing an object capable of rendering a border around the edges of a swing component.

Classes in javax.swing.border used by javax.swing.table
Border
Interface describing an object capable of rendering a border around the edges of a swing component.

Classes in javax.swing.border used by javax.swing.tree
Border
Interface describing an object capable of rendering a border around the edges of a swing component.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AbstractBorder

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.border
Class AbstractBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
All Implemented Interfaces:
Serializable, Border
Direct Known Subclasses:
BasicBorders.ButtonBorder, BasicBorders.FieldBorder, BasicBorders.MarginBorder, BasicBorders.MenuBarBorder, BevelBorder, CompoundBorder, EmptyBorder, EtchedBorder, LineBorder, MetalBorders.ButtonBorder, MetalBorders.Flush3DBorder, MetalBorders.InternalFrameBorder, MetalBorders.MenuBarBorder, MetalBorders.MenuItemBorder, MetalBorders.OptionDialogBorder, MetalBorders.PaletteBorder, MetalBorders.PopupMenuBorder, MetalBorders.ScrollPaneBorder, MetalBorders.TableHeaderBorder, MetalBorders.ToolBarBorder, TitledBorder
public abstract class AbstractBorder
extends Object
implements Border, Serializable

A class that implements an empty border with no size. This provides a convenient base class from which other border classes can be easily derived.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
AbstractBorder()
Method Summary
int | getBaseline(Component c, int width, int height) Returns the baseline.
Component.BaselineResizeBehavior | getBaselineResizeBehavior(Component c) Returns an enum indicating how the baseline of a component changes as the size changes.
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
Insets | getBorderInsets(Component c, Insets insets) Reinitializes the insets parameter with this Border's current Insets.
static Rectangle | getInteriorRectangle(Component c, Border b, int x, int y, int width, int height) Returns a rectangle using the arguments minus the insets of the border.
Rectangle | getInteriorRectangle(Component c, int x, int y, int width, int height) This convenience method calls the static method.
boolean | isBorderOpaque() This default implementation returns false.
void | paintBorder(Component c, Graphics g, int x, int y, int width, int height) This default implementation does no painting.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractBorder

public AbstractBorder()
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int width,
                        int height)
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
width - the width of the painted border
height - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets insets)
Reinitializes the insets parameter with this Border's current Insets.

Parameters:
c - the component for which this border insets value applies
insets - the object to be reinitialized
Returns:
the insets object

isBorderOpaque

public boolean isBorderOpaque()
This default implementation returns false.

Specified by:
isBorderOpaque in interface Border
Returns:
false

getInteriorRectangle

public Rectangle getInteriorRectangle(Component c,
                                      int x,
                                      int y,
                                      int width,
                                      int height)
This convenience method calls the static method.

Parameters:
c - the component for which this border is being computed
x - the x position of the border
y - the y position of the border
width - the width of the border
height - the height of the border
Returns:
a Rectangle containing the interior coordinates

getInteriorRectangle

public static Rectangle getInteriorRectangle(Component c,
                                             Border b,
                                             int x,
                                             int y,
                                             int width,
                                             int height)
Returns a rectangle using the arguments minus the insets of the border. This is useful for determining the area that components should draw in that will not intersect the border.

Parameters:
c - the component for which this border is being computed
b - the Border object
x - the x position of the border
y - the y position of the border
width - the width of the border
height - the height of the border
Returns:
a Rectangle containing the interior coordinates

getBaseline

public int getBaseline(Component c,
                       int width,
                       int height)
Returns the baseline. A return value less than 0 indicates the border does not have a reasonable baseline.

The default implementation returns -1. Subclasses that support baseline should override appropriately. If a value >= 0 is returned, then the component has a valid baseline for any size >= the minimum size and getBaselineResizeBehavior can be used to determine how the baseline changes with size.

Parameters:
c - Component baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
the baseline or < 0 indicating there is no reasonable baseline
Throws:
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
Component.getBaseline(int,int), Component.getBaselineResizeBehavior()

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior(Component c)
Returns an enum indicating how the baseline of a component changes as the size changes. This method is primarily meant for layout managers and GUI builders.

The default implementation returns BaselineResizeBehavior.OTHER, subclasses that support baseline should override appropriately. Subclasses should never return null; if the baseline can not be calculated return BaselineResizeBehavior.OTHER. Callers should first ask for the baseline using getBaseline and if a value >= 0 is returned use this method. It is acceptable for this method to return a value other than BaselineResizeBehavior.OTHER even if getBaseline returns a value less than 0.

Parameters:
c - Component to return baseline resize behavior for
Returns:
an enum indicating how the baseline changes as the border is resized
Since:
1.6
See Also:
Component.getBaseline(int,int), Component.getBaselineResizeBehavior()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


BevelBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.border
Class BevelBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.border.BevelBorder
All Implemented Interfaces:
Serializable, Border
Direct Known Subclasses:
BorderUIResource.BevelBorderUIResource, SoftBevelBorder
public class BevelBorder
extends AbstractBorder

A class which implements a simple two-line bevel border.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected int | bevelType
protected Color | highlightInner
protected Color | highlightOuter
static int | LOWERED Lowered bevel type.
static int | RAISED Raised bevel type.
protected Color | shadowInner
protected Color | shadowOuter
Constructor Summary
BevelBorder(int bevelType)
Creates a bevel border with the specified type and whose colors will be derived from the background color of the component passed into the paintBorder method.
BevelBorder(int bevelType, Color highlight, Color shadow)
Creates a bevel border with the specified type, highlight and shadow colors.
BevelBorder(int bevelType, Color highlightOuterColor, Color highlightInnerColor, Color shadowOuterColor, Color shadowInnerColor)
Creates a bevel border with the specified type, highlight and shadow colors.
Method Summary
int | getBevelType() Returns the type of the bevel border.
Insets | getBorderInsets(Component c) Returns the insets of the border.
Insets | getBorderInsets(Component c, Insets insets) Reinitialize the insets parameter with this Border's current Insets.
Color | getHighlightInnerColor() Returns the inner highlight color of the bevel border.
Color | getHighlightInnerColor(Component c) Returns the inner highlight color of the bevel border when rendered on the specified component.
Color | getHighlightOuterColor() Returns the outer highlight color of the bevel border.
Color | getHighlightOuterColor(Component c) Returns the outer highlight color of the bevel border when rendered on the specified component.
Color | getShadowInnerColor() Returns the inner shadow color of the bevel border.
Color | getShadowInnerColor(Component c) Returns the inner shadow color of the bevel border when rendered on the specified component.
Color | getShadowOuterColor() Returns the outer shadow color of the bevel border.
Color | getShadowOuterColor(Component c) Returns the outer shadow color of the bevel border when rendered on the specified component.
boolean | isBorderOpaque() Returns whether or not the border is opaque.
void | paintBorder(Component c, Graphics g, int x, int y, int width, int height) Paints the border for the specified component with the specified position and size.
protected void | paintLoweredBevel(Component c, Graphics g, int x, int y, int width, int height)
protected void | paintRaisedBevel(Component c, Graphics g, int x, int y, int width, int height)
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

RAISED

public static final int RAISED
Raised bevel type.

See Also:
Constant Field Values

LOWERED

public static final int LOWERED
Lowered bevel type.

See Also:
Constant Field Values

bevelType

protected int bevelType

highlightOuter

protected Color highlightOuter

highlightInner

protected Color highlightInner

shadowInner

protected Color shadowInner

shadowOuter

protected Color shadowOuter
Constructor Detail

BevelBorder

public BevelBorder(int bevelType)
Creates a bevel border with the specified type and whose colors will be derived from the background color of the component passed into the paintBorder method.

Parameters:
bevelType - the type of bevel for the border

BevelBorder

public BevelBorder(int bevelType,
                   Color highlight,
                   Color shadow)
Creates a bevel border with the specified type, highlight and shadow colors.

Parameters:
bevelType - the type of bevel for the border
highlight - the color to use for the bevel highlight
shadow - the color to use for the bevel shadow

BevelBorder

public BevelBorder(int bevelType,
                   Color highlightOuterColor,
                   Color highlightInnerColor,
                   Color shadowOuterColor,
                   Color shadowInnerColor)
Creates a bevel border with the specified type, highlight and shadow colors.

Note: The shadow inner and outer colors are switched for a lowered bevel border.

Parameters:
bevelType - the type of bevel for the border
highlightOuterColor - the color to use for the bevel outer highlight
highlightInnerColor - the color to use for the bevel inner highlight
shadowOuterColor - the color to use for the bevel outer shadow
shadowInnerColor - the color to use for the bevel inner shadow
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int width,
                        int height)
Paints the border for the specified component with the specified position and size.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
width - the width of the painted border
height - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Returns the insets of the border.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets insets)
Reinitialize the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
insets - the object to be reinitialized
Returns:
the insets object

getHighlightOuterColor

public Color getHighlightOuterColor(Component c)
Returns the outer highlight color of the bevel border when rendered on the specified component. If no highlight color was specified at instantiation, the highlight color is derived from the specified component's background color.

Parameters:
c - the component for which the highlight may be derived
Since:
1.3

getHighlightInnerColor

public Color getHighlightInnerColor(Component c)
Returns the inner highlight color of the bevel border when rendered on the specified component. If no highlight color was specified at instantiation, the highlight color is derived from the specified component's background color.

Parameters:
c - the component for which the highlight may be derived
Since:
1.3

getShadowInnerColor

public Color getShadowInnerColor(Component c)
Returns the inner shadow color of the bevel border when rendered on the specified component. If no shadow color was specified at instantiation, the shadow color is derived from the specified component's background color.

Parameters:
c - the component for which the shadow may be derived
Since:
1.3

getShadowOuterColor

public Color getShadowOuterColor(Component c)
Returns the outer shadow color of the bevel border when rendered on the specified component. If no shadow color was specified at instantiation, the shadow color is derived from the specified component's background color.

Parameters:
c - the component for which the shadow may be derived
Since:
1.3

getHighlightOuterColor

public Color getHighlightOuterColor()
Returns the outer highlight color of the bevel border. Will return null if no highlight color was specified at instantiation.

Since:
1.3

getHighlightInnerColor

public Color getHighlightInnerColor()
Returns the inner highlight color of the bevel border. Will return null if no highlight color was specified at instantiation.

Since:
1.3

getShadowInnerColor

public Color getShadowInnerColor()
Returns the inner shadow color of the bevel border. Will return null if no shadow color was specified at instantiation.

Since:
1.3

getShadowOuterColor

public Color getShadowOuterColor()
Returns the outer shadow color of the bevel border. Will return null if no shadow color was specified at instantiation.

Since:
1.3

getBevelType

public int getBevelType()
Returns the type of the bevel border.

isBorderOpaque

public boolean isBorderOpaque()
Returns whether or not the border is opaque.

Specified by:
isBorderOpaque in interface Border
Overrides:
isBorderOpaque in class AbstractBorder
Returns:
false

paintRaisedBevel

protected void paintRaisedBevel(Component c,
                                Graphics g,
                                int x,
                                int y,
                                int width,
                                int height)

paintLoweredBevel

protected void paintLoweredBevel(Component c,
                                 Graphics g,
                                 int x,
                                 int y,
                                 int width,
                                 int height)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Border

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.border
Interface Border

All Known Implementing Classes:
AbstractBorder, BasicBorders.ButtonBorder, BasicBorders.FieldBorder, BasicBorders.MarginBorder, BasicBorders.MenuBarBorder, BasicBorders.RadioButtonBorder, BasicBorders.RolloverButtonBorder, BasicBorders.SplitPaneBorder, BasicBorders.ToggleButtonBorder, BevelBorder, BorderUIResource, BorderUIResource.BevelBorderUIResource, BorderUIResource.CompoundBorderUIResource, BorderUIResource.EmptyBorderUIResource, BorderUIResource.EtchedBorderUIResource, BorderUIResource.LineBorderUIResource, BorderUIResource.MatteBorderUIResource, BorderUIResource.TitledBorderUIResource, CompoundBorder, EmptyBorder, EtchedBorder, LineBorder, MatteBorder, MetalBorders.ButtonBorder, MetalBorders.Flush3DBorder, MetalBorders.InternalFrameBorder, MetalBorders.MenuBarBorder, MetalBorders.MenuItemBorder, MetalBorders.OptionDialogBorder, MetalBorders.PaletteBorder, MetalBorders.PopupMenuBorder, MetalBorders.RolloverButtonBorder, MetalBorders.ScrollPaneBorder, MetalBorders.TableHeaderBorder, MetalBorders.TextFieldBorder, MetalBorders.ToggleButtonBorder, MetalBorders.ToolBarBorder, SoftBevelBorder, TitledBorder
public interface Border

Interface describing an object capable of rendering a border around the edges of a swing component. For examples of using borders see How to Use Borders, a section in The Java Tutorial.

In the Swing component set, borders supercede Insets as the mechanism for creating a (decorated or plain) area around the edge of a component.

Usage Notes:

  • Use EmptyBorder to create a plain border (this mechanism replaces its predecessor, setInsets).
  • Use CompoundBorder to nest multiple border objects, creating a single, combined border.
  • Border instances are designed to be shared. Rather than creating a new border object using one of border classes, use the BorderFactory methods, which produces a shared instance of the common border types.
  • Additional border styles include BevelBorder, SoftBevelBorder, EtchedBorder, LineBorder, TitledBorder, and MatteBorder.
  • To create a new border class, subclass AbstractBorder.

See Also:
BorderFactory, EmptyBorder, CompoundBorder

Method Summary
Insets | getBorderInsets(Component c) Returns the insets of the border.
boolean | isBorderOpaque() Returns whether or not the border is opaque.
void | paintBorder(Component c, Graphics g, int x, int y, int width, int height) Paints the border for the specified component with the specified position and size.

Method Detail

paintBorder

void paintBorder(Component c,
                 Graphics g,
                 int x,
                 int y,
                 int width,
                 int height)
Paints the border for the specified component with the specified position and size.

Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
width - the width of the painted border
height - the height of the painted border

getBorderInsets

Insets getBorderInsets(Component c)
Returns the insets of the border.

Parameters:
c - the component for which this border insets value applies

isBorderOpaque

boolean isBorderOpaque()
Returns whether or not the border is opaque. If the border is opaque, it is responsible for filling in it's own background when painting.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.swing.border.AbstractBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.border.AbstractBorder

Packages that use AbstractBorder
javax.swing.border | Provides classes and interface for drawing specialized borders around a Swing component.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of AbstractBorder in javax.swing.border

Subclasses of AbstractBorder in javax.swing.border
class | BevelBorder A class which implements a simple two-line bevel border.
class | CompoundBorder A composite Border class used to compose two Border objects into a single border by nesting an inside Border object within the insets of an outside Border object.
class | EmptyBorder A class which provides an empty, transparent border which takes up space but does no drawing.
class | EtchedBorder A class which implements a simple etched border which can either be etched-in or etched-out.
class | LineBorder A class which implements a line border of arbitrary thickness and of a single color.
class | MatteBorder A class which provides a matte-like border of either a solid color or a tiled icon.
class | SoftBevelBorder A class which implements a raised or lowered bevel with softened corners.
class | TitledBorder A class which implements an arbitrary border with the addition of a String title in a specified position and justification.

Uses of AbstractBorder in javax.swing.plaf

Subclasses of AbstractBorder in javax.swing.plaf
static class | BorderUIResource.BevelBorderUIResource
static class | BorderUIResource.CompoundBorderUIResource
static class | BorderUIResource.EmptyBorderUIResource
static class | BorderUIResource.EtchedBorderUIResource
static class | BorderUIResource.LineBorderUIResource
static class | BorderUIResource.MatteBorderUIResource
static class | BorderUIResource.TitledBorderUIResource

Uses of AbstractBorder in javax.swing.plaf.basic

Subclasses of AbstractBorder in javax.swing.plaf.basic
static class | BasicBorders.ButtonBorder
static class | BasicBorders.FieldBorder
static class | BasicBorders.MarginBorder
static class | BasicBorders.MenuBarBorder
static class | BasicBorders.RadioButtonBorder
static class | BasicBorders.RolloverButtonBorder Special thin border for rollover toolbar buttons.
static class | BasicBorders.ToggleButtonBorder

Uses of AbstractBorder in javax.swing.plaf.metal

Subclasses of AbstractBorder in javax.swing.plaf.metal
static class | MetalBorders.ButtonBorder
static class | MetalBorders.Flush3DBorder
static class | MetalBorders.InternalFrameBorder
static class | MetalBorders.MenuBarBorder
static class | MetalBorders.MenuItemBorder
static class | MetalBorders.OptionDialogBorder
static class | MetalBorders.PaletteBorder Border for a Palette.
static class | MetalBorders.PopupMenuBorder
static class | MetalBorders.RolloverButtonBorder
static class | MetalBorders.ScrollPaneBorder
static class | MetalBorders.TableHeaderBorder Border for a Table Header
static class | MetalBorders.TextFieldBorder
static class | MetalBorders.ToggleButtonBorder
static class | MetalBorders.ToolBarBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.border.BevelBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.border.BevelBorder

Packages that use BevelBorder
javax.swing.border | Provides classes and interface for drawing specialized borders around a Swing component.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.

Uses of BevelBorder in javax.swing.border

Subclasses of BevelBorder in javax.swing.border
 class SoftBevelBorder
A class which implements a raised or lowered bevel with softened corners.

Uses of BevelBorder in javax.swing.plaf

Subclasses of BevelBorder in javax.swing.plaf
static class BorderUIResource.BevelBorderUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.border.CompoundBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.border.CompoundBorder

Packages that use CompoundBorder
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.

Uses of CompoundBorder in javax.swing

Methods in javax.swing that return CompoundBorder
static CompoundBorder | BorderFactory.createCompoundBorder() Creates a compound border with a null inside edge and a null outside edge.
static CompoundBorder | BorderFactory.createCompoundBorder(Border outsideBorder, Border insideBorder) Creates a compound border specifying the border objects to use for the outside and inside edges.

Uses of CompoundBorder in javax.swing.plaf

Subclasses of CompoundBorder in javax.swing.plaf
static class BorderUIResource.CompoundBorderUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.border.EmptyBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.border.EmptyBorder

Packages that use EmptyBorder
javax.swing.border | Provides classes and interface for drawing specialized borders around a Swing component.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.

Uses of EmptyBorder in javax.swing.border

Subclasses of EmptyBorder in javax.swing.border
 class MatteBorder
A class which provides a matte-like border of either a solid color or a tiled icon.

Uses of EmptyBorder in javax.swing.plaf

Subclasses of EmptyBorder in javax.swing.plaf
static class | BorderUIResource.EmptyBorderUIResource
static class | BorderUIResource.MatteBorderUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.border.EtchedBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.border.EtchedBorder

Packages that use EtchedBorder
javax.swing.plaf Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.

Uses of EtchedBorder in javax.swing.plaf

Subclasses of EtchedBorder in javax.swing.plaf
static class BorderUIResource.EtchedBorderUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.border.LineBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.border.LineBorder

Packages that use LineBorder
javax.swing.plaf Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.

Uses of LineBorder in javax.swing.plaf

Subclasses of LineBorder in javax.swing.plaf
static class BorderUIResource.LineBorderUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.border.MatteBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.border.MatteBorder

Packages that use MatteBorder
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.

Uses of MatteBorder in javax.swing

Methods in javax.swing that return MatteBorder
static MatteBorder | BorderFactory.createMatteBorder(int top, int left, int bottom, int right, Color color) Creates a matte-look border using a solid color.
static MatteBorder | BorderFactory.createMatteBorder(int top, int left, int bottom, int right, Icon tileIcon) Creates a matte-look border that consists of multiple tiles of a specified icon.

Uses of MatteBorder in javax.swing.plaf

Subclasses of MatteBorder in javax.swing.plaf
static class BorderUIResource.MatteBorderUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.border.SoftBevelBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.border.SoftBevelBorder

No usage of javax.swing.border.SoftBevelBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.border.TitledBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.border.TitledBorder

Packages that use TitledBorder
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.

Uses of TitledBorder in javax.swing

Methods in javax.swing that return TitledBorder
static TitledBorder | BorderFactory.createTitledBorder(Border border) Creates a new titled border with an empty title, the specified border object, the default text position (sitting on the top line), the default justification (leading), and the default font and text color (determined by the current look and feel).
static TitledBorder | BorderFactory.createTitledBorder(Border border, String title) Adds a title to an existing border, with default positioning (sitting on the top line), default justification (leading) and the default font and text color (determined by the current look and feel).
static TitledBorder | BorderFactory.createTitledBorder(Border border, String title, int titleJustification, int titlePosition) Adds a title to an existing border, with the specified positioning and using the default font and text color (determined by the current look and feel).
static TitledBorder | BorderFactory.createTitledBorder(Border border, String title, int titleJustification, int titlePosition, Font titleFont) Adds a title to an existing border, with the specified positioning and font, and using the default text color (determined by the current look and feel).
static TitledBorder | BorderFactory.createTitledBorder(Border border, String title, int titleJustification, int titlePosition, Font titleFont, Color titleColor) Adds a title to an existing border, with the specified positioning, font and color.
static TitledBorder | BorderFactory.createTitledBorder(String title) Creates a new titled border with the specified title, the default border type (determined by the current look and feel), the default text position (sitting on the top line), the default justification (leading), and the default font and text color (determined by the current look and feel).

Uses of TitledBorder in javax.swing.plaf

Subclasses of TitledBorder in javax.swing.plaf
static class BorderUIResource.TitledBorderUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.border.Border

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.border.Border

Packages that use Border
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.border | Provides classes and interface for drawing specialized borders around a Swing component.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of Border in javax.swing

Fields in javax.swing declared as Border
protected static Border DefaultListCellRenderer.noFocusBorder
An empty Border.

Methods in javax.swing that return Border
static Border | BorderFactory.createBevelBorder(int type) Creates a beveled border of the specified type, using brighter shades of the component's current background color for highlighting, and darker shading for shadows.
static Border | BorderFactory.createBevelBorder(int type, Color highlight, Color shadow) Creates a beveled border of the specified type, using the specified highlighting and shadowing.
static Border | BorderFactory.createBevelBorder(int type, Color highlightOuter, Color highlightInner, Color shadowOuter, Color shadowInner) Creates a beveled border of the specified type, using the specified colors for the inner and outer highlight and shadow areas.
static Border | BorderFactory.createEmptyBorder() Creates an empty border that takes up no space.
static Border | BorderFactory.createEmptyBorder(int top, int left, int bottom, int right) Creates an empty border that takes up space but which does no drawing, specifying the width of the top, left, bottom, and right sides.
static Border | BorderFactory.createEtchedBorder() Creates a border with an "etched" look using the component's current background color for highlighting and shading.
static Border | BorderFactory.createEtchedBorder(Color highlight, Color shadow) Creates a border with an "etched" look using the specified highlighting and shading colors.
static Border | BorderFactory.createEtchedBorder(int type) Creates a border with an "etched" look using the component's current background color for highlighting and shading.
static Border | BorderFactory.createEtchedBorder(int type, Color highlight, Color shadow) Creates a border with an "etched" look using the specified highlighting and shading colors.
static Border | BorderFactory.createLineBorder(Color color) Creates a line border withe the specified color.
static Border | BorderFactory.createLineBorder(Color color, int thickness) Creates a line border with the specified color and width.
static Border | BorderFactory.createLoweredBevelBorder() Creates a border with a lowered beveled edge, using brighter shades of the component's current background color for highlighting, and darker shading for shadows.
static Border | BorderFactory.createRaisedBevelBorder() Creates a border with a raised beveled edge, using brighter shades of the component's current background color for highlighting, and darker shading for shadows.
Border | JComponent.getBorder() Returns the border of this component or null if no border is currently set.
Border | UIDefaults.getBorder(Object key) If the value of key is a Border return it, otherwise return null.
static Border | UIManager.getBorder(Object key) Returns a border from the defaults.
Border | UIDefaults.getBorder(Object key, Locale l) If the value of key for the given Locale is a Border return it, otherwise return null.
static Border | UIManager.getBorder(Object key, Locale l) Returns a border from the defaults that is appropriate for the given locale.
Border | JScrollPane.getViewportBorder() Returns the Border object that surrounds the viewport.

Methods in javax.swing with parameters of type Border
static CompoundBorder | BorderFactory.createCompoundBorder(Border outsideBorder, Border insideBorder) Creates a compound border specifying the border objects to use for the outside and inside edges.
static TitledBorder | BorderFactory.createTitledBorder(Border border) Creates a new titled border with an empty title, the specified border object, the default text position (sitting on the top line), the default justification (leading), and the default font and text color (determined by the current look and feel).
static TitledBorder | BorderFactory.createTitledBorder(Border border, String title) Adds a title to an existing border, with default positioning (sitting on the top line), default justification (leading) and the default font and text color (determined by the current look and feel).
static TitledBorder | BorderFactory.createTitledBorder(Border border, String title, int titleJustification, int titlePosition) Adds a title to an existing border, with the specified positioning and using the default font and text color (determined by the current look and feel).
static TitledBorder | BorderFactory.createTitledBorder(Border border, String title, int titleJustification, int titlePosition, Font titleFont) Adds a title to an existing border, with the specified positioning and font, and using the default text color (determined by the current look and feel).
static TitledBorder | BorderFactory.createTitledBorder(Border border, String title, int titleJustification, int titlePosition, Font titleFont, Color titleColor) Adds a title to an existing border, with the specified positioning, font and color.
protected String | JComponent.AccessibleJComponent.getBorderTitle(Border b) Recursively search through the border hierarchy (if it exists) for a TitledBorder with a non-null title.
void | JViewport.setBorder(Border border) The viewport "scrolls" its child (called the "view") by the normal parent/child clipping (typically the view is moved in the opposite direction of the scroll).
void | JComponent.setBorder(Border border) Sets the border of this component.
void | JScrollPane.setViewportBorder(Border viewportBorder) Adds a border around the viewport.

Uses of Border in javax.swing.border

Classes in javax.swing.border that implement Border
class | AbstractBorder A class that implements an empty border with no size.
class | BevelBorder A class which implements a simple two-line bevel border.
class | CompoundBorder A composite Border class used to compose two Border objects into a single border by nesting an inside Border object within the insets of an outside Border object.
class | EmptyBorder A class which provides an empty, transparent border which takes up space but does no drawing.
class | EtchedBorder A class which implements a simple etched border which can either be etched-in or etched-out.
class | LineBorder A class which implements a line border of arbitrary thickness and of a single color.
class | MatteBorder A class which provides a matte-like border of either a solid color or a tiled icon.
class | SoftBevelBorder A class which implements a raised or lowered bevel with softened corners.
class | TitledBorder A class which implements an arbitrary border with the addition of a String title in a specified position and justification.

Fields in javax.swing.border declared as Border
protected Border | TitledBorder.border
protected Border | CompoundBorder.insideBorder
protected Border | CompoundBorder.outsideBorder

Methods in javax.swing.border that return Border
static Border | LineBorder.createBlackLineBorder() Convenience method for getting the Color.black LineBorder of thickness 1.
static Border | LineBorder.createGrayLineBorder() Convenience method for getting the Color.gray LineBorder of thickness 1.
Border | TitledBorder.getBorder() Returns the border of the titled border.
Border | CompoundBorder.getInsideBorder() Returns the inside border object.
Border | CompoundBorder.getOutsideBorder() Returns the outside border object.

Methods in javax.swing.border with parameters of type Border
static Rectangle | AbstractBorder.getInteriorRectangle(Component c, Border b, int x, int y, int width, int height) Returns a rectangle using the arguments minus the insets of the border.
void | TitledBorder.setBorder(Border border) Sets the border of the titled border.

Constructors in javax.swing.border with parameters of type Border
CompoundBorder(Border outsideBorder, Border insideBorder)
Creates a compound border with the specified outside and inside borders.
TitledBorder(Border border)
Creates a TitledBorder instance with the specified border and an empty title.
TitledBorder(Border border, String title)
Creates a TitledBorder instance with the specified border and title.
TitledBorder(Border border, String title, int titleJustification, int titlePosition)
Creates a TitledBorder instance with the specified border, title, title-justification, and title-position.
TitledBorder(Border border, String title, int titleJustification, int titlePosition, Font titleFont)
Creates a TitledBorder instance with the specified border, title, title-justification, title-position, and title-font.
TitledBorder(Border border, String title, int titleJustification, int titlePosition, Font titleFont, Color titleColor)
Creates a TitledBorder instance with the specified border, title, title-justification, title-position, title-font, and title-color.

Uses of Border in javax.swing.plaf

Classes in javax.swing.plaf that implement Border
class | BorderUIResource
static class | BorderUIResource.BevelBorderUIResource
static class | BorderUIResource.CompoundBorderUIResource
static class | BorderUIResource.EmptyBorderUIResource
static class | BorderUIResource.EtchedBorderUIResource
static class | BorderUIResource.LineBorderUIResource
static class | BorderUIResource.MatteBorderUIResource
static class | BorderUIResource.TitledBorderUIResource

Methods in javax.swing.plaf that return Border
static Border | BorderUIResource.getBlackLineBorderUIResource()
static Border | BorderUIResource.getEtchedBorderUIResource()
static Border | BorderUIResource.getLoweredBevelBorderUIResource()
static Border | BorderUIResource.getRaisedBevelBorderUIResource()

Constructors in javax.swing.plaf with parameters of type Border
BorderUIResource.CompoundBorderUIResource(Border outsideBorder, Border insideBorder)
BorderUIResource.TitledBorderUIResource(Border border)
BorderUIResource.TitledBorderUIResource(Border border, String title)
BorderUIResource.TitledBorderUIResource(Border border, String title, int titleJustification, int titlePosition)
BorderUIResource.TitledBorderUIResource(Border border, String title, int titleJustification, int titlePosition, Font titleFont)
BorderUIResource.TitledBorderUIResource(Border border, String title, int titleJustification, int titlePosition, Font titleFont, Color titleColor)
BorderUIResource(Border delegate)
Creates a UIResource border object which wraps an existing Border instance.

Uses of Border in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement Border
static class | BasicBorders.ButtonBorder
static class | BasicBorders.FieldBorder
static class | BasicBorders.MarginBorder
static class | BasicBorders.MenuBarBorder
static class | BasicBorders.RadioButtonBorder
static class | BasicBorders.RolloverButtonBorder Special thin border for rollover toolbar buttons.
static class | BasicBorders.SplitPaneBorder Draws the border around the splitpane.
static class | BasicBorders.ToggleButtonBorder

Fields in javax.swing.plaf.basic declared as Border
protected static Border BasicComboBoxRenderer.noFocusBorder
An empty Border.

Methods in javax.swing.plaf.basic that return Border
protected Border | BasicToolBarUI.createNonRolloverBorder() Creates the non rollover border for toolbar components.
protected Border | BasicToolBarUI.createRolloverBorder() Creates a rollover border for toolbar components.
Border | BasicSplitPaneDivider.getBorder() Returns the border of this component or null if no border is currently set.
static Border | BasicBorders.getButtonBorder()
static Border | BasicBorders.getInternalFrameBorder()
static Border | BasicBorders.getMenuBarBorder()
protected Border | BasicToolBarUI.getNonRolloverBorder(AbstractButton b) Returns a non-rollover border for the button.
static Border | BasicBorders.getProgressBarBorder()
static Border | BasicBorders.getRadioButtonBorder()
protected Border | BasicToolBarUI.getRolloverBorder(AbstractButton b) Returns a rollover border for the button.
static Border | BasicBorders.getSplitPaneBorder()
static Border | BasicBorders.getSplitPaneDividerBorder() Returns a border instance for a JSplitPane divider
static Border | BasicBorders.getTextFieldBorder()
static Border | BasicBorders.getToggleButtonBorder()

Methods in javax.swing.plaf.basic with parameters of type Border
 void BasicSplitPaneDivider.setBorder(Border border)
Sets the border of this component.

Uses of Border in javax.swing.plaf.metal

Classes in javax.swing.plaf.metal that implement Border
static class | MetalBorders.ButtonBorder
static class | MetalBorders.Flush3DBorder
static class | MetalBorders.InternalFrameBorder
static class | MetalBorders.MenuBarBorder
static class | MetalBorders.MenuItemBorder
static class | MetalBorders.OptionDialogBorder
static class | MetalBorders.PaletteBorder Border for a Palette.
static class | MetalBorders.PopupMenuBorder
static class | MetalBorders.RolloverButtonBorder
static class | MetalBorders.ScrollPaneBorder
static class | MetalBorders.TableHeaderBorder Border for a Table Header
static class | MetalBorders.TextFieldBorder
static class | MetalBorders.ToggleButtonBorder
static class | MetalBorders.ToolBarBorder

Methods in javax.swing.plaf.metal that return Border
protected Border | MetalToolBarUI.createNonRolloverBorder()
protected Border | MetalToolBarUI.createRolloverBorder()
static Border | MetalBorders.getButtonBorder() Returns a border instance for a JButton
static Border | MetalBorders.getDesktopIconBorder() Returns a border instance for a Desktop Icon
static Border | MetalBorders.getTextBorder() Returns a border instance for a text component
static Border | MetalBorders.getTextFieldBorder() Returns a border instance for a JTextField
static Border | MetalBorders.getToggleButtonBorder() Returns a border instance for a JToggleButton

Uses of Border in javax.swing.table

Fields in javax.swing.table declared as Border
protected static Border DefaultTableCellRenderer.noFocusBorder
An empty Border.

Uses of Border in javax.swing.tree

Fields in javax.swing.tree declared as Border
protected  Border DefaultTreeCellEditor.DefaultTextField.border
Border to use.

Methods in javax.swing.tree that return Border
 Border DefaultTreeCellEditor.DefaultTextField.getBorder()
Overrides JComponent.getBorder to returns the current border.

Methods in javax.swing.tree with parameters of type Border
 void DefaultTreeCellEditor.DefaultTextField.setBorder(Border border)
Sets the border of this component.

Constructors in javax.swing.tree with parameters of type Border
DefaultTreeCellEditor.DefaultTextField(Border border)
Constructs a DefaultTreeCellEditor.DefaultTextField object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


CompoundBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.border
Class CompoundBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.border.CompoundBorder
All Implemented Interfaces:
Serializable, Border
Direct Known Subclasses:
BorderUIResource.CompoundBorderUIResource
public class CompoundBorder
extends AbstractBorder

A composite Border class used to compose two Border objects into a single border by nesting an inside Border object within the insets of an outside Border object. For example, this class may be used to add blank margin space to a component with an existing decorative border:

    Border border = comp.getBorder();
    Border margin = new EmptyBorder(10,10,10,10);
    comp.setBorder(new CompoundBorder(border, margin));

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected Border | insideBorder
protected Border | outsideBorder
Constructor Summary
CompoundBorder()
Creates a compound border with null outside and inside borders.
CompoundBorder(Border outsideBorder, Border insideBorder)
Creates a compound border with the specified outside and inside borders.
Method Summary
Insets | getBorderInsets(Component c) Returns the insets of the composite border by adding the insets of the outside border to the insets of the inside border.
Insets | getBorderInsets(Component c, Insets insets) Reinitialize the insets parameter with this Border's current Insets.
Border | getInsideBorder() Returns the inside border object.
Border | getOutsideBorder() Returns the outside border object.
boolean | isBorderOpaque() Returns whether or not this compound border is opaque.
void | paintBorder(Component c, Graphics g, int x, int y, int width, int height) Paints the compound border by painting the outside border with the specified position and size and then painting the inside border at the specified position and size offset by the insets of the outside border.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

outsideBorder

protected Border outsideBorder

insideBorder

protected Border insideBorder
Constructor Detail

CompoundBorder

public CompoundBorder()
Creates a compound border with null outside and inside borders.

CompoundBorder

public CompoundBorder(Border outsideBorder,
                      Border insideBorder)
Creates a compound border with the specified outside and inside borders. Either border may be null.

Parameters:
outsideBorder - the outside border
insideBorder - the inside border to be nested
Method Detail

isBorderOpaque

public boolean isBorderOpaque()
Returns whether or not this compound border is opaque. Returns true if both the inside and outside borders are non-null and opaque; returns false otherwise.

Specified by:
isBorderOpaque in interface Border
Overrides:
isBorderOpaque in class AbstractBorder
Returns:
false

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int width,
                        int height)
Paints the compound border by painting the outside border with the specified position and size and then painting the inside border at the specified position and size offset by the insets of the outside border.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
width - the width of the painted border
height - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets insets)
Reinitialize the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
insets - the object to be reinitialized
Returns:
the insets object

getBorderInsets

public Insets getBorderInsets(Component c)
Returns the insets of the composite border by adding the insets of the outside border to the insets of the inside border.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getOutsideBorder

public Border getOutsideBorder()
Returns the outside border object.

getInsideBorder

public Border getInsideBorder()
Returns the inside border object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EmptyBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.border
Class EmptyBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.border.EmptyBorder
All Implemented Interfaces:
Serializable, Border
Direct Known Subclasses:
BorderUIResource.EmptyBorderUIResource, MatteBorder
public class EmptyBorder
extends AbstractBorder
implements Serializable

A class which provides an empty, transparent border which takes up space but does no drawing.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected int | bottom
protected int | left
protected int | right
protected int | top
Constructor Summary
EmptyBorder(Insets borderInsets)
Creates an empty border with the specified insets.
EmptyBorder(int top, int left, int bottom, int right)
Creates an empty border with the specified insets.
Method Summary
Insets | getBorderInsets() Returns the insets of the border.
Insets | getBorderInsets(Component c) Returns the insets of the border.
Insets | getBorderInsets(Component c, Insets insets) Reinitialize the insets parameter with this Border's current Insets.
boolean | isBorderOpaque() Returns whether or not the border is opaque.
void | paintBorder(Component c, Graphics g, int x, int y, int width, int height) Does no drawing by default.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

left

protected int left

right

protected int right

top

protected int top

bottom

protected int bottom
Constructor Detail

EmptyBorder

public EmptyBorder(int top,
                   int left,
                   int bottom,
                   int right)
Creates an empty border with the specified insets.

Parameters:
top - the top inset of the border
left - the left inset of the border
bottom - the bottom inset of the border
right - the right inset of the border

EmptyBorder

public EmptyBorder(Insets borderInsets)
Creates an empty border with the specified insets.

Parameters:
borderInsets - the insets of the border
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int width,
                        int height)
Does no drawing by default.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
width - the width of the painted border
height - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Returns the insets of the border.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0
Since:
1.3

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets insets)
Reinitialize the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
insets - the object to be reinitialized
Returns:
the insets object

getBorderInsets

public Insets getBorderInsets()
Returns the insets of the border.

Since:
1.3

isBorderOpaque

public boolean isBorderOpaque()
Returns whether or not the border is opaque. Returns false by default.

Specified by:
isBorderOpaque in interface Border
Overrides:
isBorderOpaque in class AbstractBorder
Returns:
false
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EtchedBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.border
Class EtchedBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.border.EtchedBorder
All Implemented Interfaces:
Serializable, Border
Direct Known Subclasses:
BorderUIResource.EtchedBorderUIResource
public class EtchedBorder
extends AbstractBorder

A class which implements a simple etched border which can either be etched-in or etched-out. If no highlight/shadow colors are initialized when the border is created, then these colors will be dynamically derived from the background color of the component argument passed into the paintBorder() method.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected int | etchType
protected Color | highlight
static int | LOWERED Lowered etched type.
static int | RAISED Raised etched type.
protected Color | shadow
Constructor Summary
EtchedBorder()
Creates a lowered etched border whose colors will be derived from the background color of the component passed into the paintBorder method.
EtchedBorder(Color highlight, Color shadow)
Creates a lowered etched border with the specified highlight and shadow colors.
EtchedBorder(int etchType)
Creates an etched border with the specified etch-type whose colors will be derived from the background color of the component passed into the paintBorder method.
EtchedBorder(int etchType, Color highlight, Color shadow)
Creates an etched border with the specified etch-type, highlight and shadow colors.
Method Summary
Insets | getBorderInsets(Component c) Returns the insets of the border.
Insets | getBorderInsets(Component c, Insets insets) Reinitialize the insets parameter with this Border's current Insets.
int | getEtchType() Returns which etch-type is set on the etched border.
Color | getHighlightColor() Returns the highlight color of the etched border.
Color | getHighlightColor(Component c) Returns the highlight color of the etched border when rendered on the specified component.
Color | getShadowColor() Returns the shadow color of the etched border.
Color | getShadowColor(Component c) Returns the shadow color of the etched border when rendered on the specified component.
boolean | isBorderOpaque() Returns whether or not the border is opaque.
void | paintBorder(Component c, Graphics g, int x, int y, int width, int height) Paints the border for the specified component with the specified position and size.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

RAISED

public static final int RAISED
Raised etched type.

See Also:
Constant Field Values

LOWERED

public static final int LOWERED
Lowered etched type.

See Also:
Constant Field Values

etchType

protected int etchType

highlight

protected Color highlight

shadow

protected Color shadow
Constructor Detail

EtchedBorder

public EtchedBorder()
Creates a lowered etched border whose colors will be derived from the background color of the component passed into the paintBorder method.

EtchedBorder

public EtchedBorder(int etchType)
Creates an etched border with the specified etch-type whose colors will be derived from the background color of the component passed into the paintBorder method.

Parameters:
etchType - the type of etch to be drawn by the border

EtchedBorder

public EtchedBorder(Color highlight,
                    Color shadow)
Creates a lowered etched border with the specified highlight and shadow colors.

Parameters:
highlight - the color to use for the etched highlight
shadow - the color to use for the etched shadow

EtchedBorder

public EtchedBorder(int etchType,
                    Color highlight,
                    Color shadow)
Creates an etched border with the specified etch-type, highlight and shadow colors.

Parameters:
etchType - the type of etch to be drawn by the border
highlight - the color to use for the etched highlight
shadow - the color to use for the etched shadow
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int width,
                        int height)
Paints the border for the specified component with the specified position and size.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
width - the width of the painted border
height - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Returns the insets of the border.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets insets)
Reinitialize the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
insets - the object to be reinitialized
Returns:
the insets object

isBorderOpaque

public boolean isBorderOpaque()
Returns whether or not the border is opaque.

Specified by:
isBorderOpaque in interface Border
Overrides:
isBorderOpaque in class AbstractBorder
Returns:
false

getEtchType

public int getEtchType()
Returns which etch-type is set on the etched border.

getHighlightColor

public Color getHighlightColor(Component c)
Returns the highlight color of the etched border when rendered on the specified component. If no highlight color was specified at instantiation, the highlight color is derived from the specified component's background color.

Parameters:
c - the component for which the highlight may be derived
Since:
1.3

getHighlightColor

public Color getHighlightColor()
Returns the highlight color of the etched border. Will return null if no highlight color was specified at instantiation.

Since:
1.3

getShadowColor

public Color getShadowColor(Component c)
Returns the shadow color of the etched border when rendered on the specified component. If no shadow color was specified at instantiation, the shadow color is derived from the specified component's background color.

Parameters:
c - the component for which the shadow may be derived
Since:
1.3

getShadowColor

public Color getShadowColor()
Returns the shadow color of the etched border. Will return null if no shadow color was specified at instantiation.

Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LineBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.border
Class LineBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.border.LineBorder
All Implemented Interfaces:
Serializable, Border
Direct Known Subclasses:
BorderUIResource.LineBorderUIResource
public class LineBorder
extends AbstractBorder

A class which implements a line border of arbitrary thickness and of a single color.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected Color | lineColor
protected boolean | roundedCorners
protected int | thickness
Constructor Summary
LineBorder(Color color)
Creates a line border with the specified color and a thickness = 1.
LineBorder(Color color, int thickness)
Creates a line border with the specified color and thickness.
LineBorder(Color color, int thickness, boolean roundedCorners)
Creates a line border with the specified color, thickness, and corner shape.
Method Summary
static Border | createBlackLineBorder() Convenience method for getting the Color.black LineBorder of thickness 1.
static Border | createGrayLineBorder() Convenience method for getting the Color.gray LineBorder of thickness 1.
Insets | getBorderInsets(Component c) Returns the insets of the border.
Insets | getBorderInsets(Component c, Insets insets) Reinitialize the insets parameter with this Border's current Insets.
Color | getLineColor() Returns the color of the border.
boolean | getRoundedCorners() Returns whether this border will be drawn with rounded corners.
int | getThickness() Returns the thickness of the border.
boolean | isBorderOpaque() Returns whether or not the border is opaque.
void | paintBorder(Component c, Graphics g, int x, int y, int width, int height) Paints the border for the specified component with the specified position and size.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

thickness

protected int thickness

lineColor

protected Color lineColor

roundedCorners

protected boolean roundedCorners
Constructor Detail

LineBorder

public LineBorder(Color color)
Creates a line border with the specified color and a thickness = 1.

Parameters:
color - the color for the border

LineBorder

public LineBorder(Color color,
                  int thickness)
Creates a line border with the specified color and thickness.

Parameters:
color - the color of the border
thickness - the thickness of the border

LineBorder

public LineBorder(Color color,
                  int thickness,
                  boolean roundedCorners)
Creates a line border with the specified color, thickness, and corner shape.

Parameters:
color - the color of the border
thickness - the thickness of the border
roundedCorners - whether or not border corners should be round
Since:
1.3
Method Detail

createBlackLineBorder

public static Border createBlackLineBorder()
Convenience method for getting the Color.black LineBorder of thickness 1.

createGrayLineBorder

public static Border createGrayLineBorder()
Convenience method for getting the Color.gray LineBorder of thickness 1.

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int width,
                        int height)
Paints the border for the specified component with the specified position and size.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
width - the width of the painted border
height - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Returns the insets of the border.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets insets)
Reinitialize the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
insets - the object to be reinitialized
Returns:
the insets object

getLineColor

public Color getLineColor()
Returns the color of the border.

getThickness

public int getThickness()
Returns the thickness of the border.

getRoundedCorners

public boolean getRoundedCorners()
Returns whether this border will be drawn with rounded corners.

Since:
1.3

isBorderOpaque

public boolean isBorderOpaque()
Returns whether or not the border is opaque.

Specified by:
isBorderOpaque in interface Border
Overrides:
isBorderOpaque in class AbstractBorder
Returns:
false
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MatteBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.border
Class MatteBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.border.EmptyBorder
            extended by  javax.swing.border.MatteBorder
All Implemented Interfaces:
Serializable, Border
Direct Known Subclasses:
BorderUIResource.MatteBorderUIResource
public class MatteBorder
extends EmptyBorder

A class which provides a matte-like border of either a solid color or a tiled icon.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected Color | color
protected Icon | tileIcon
Fields inherited from class javax.swing.border.EmptyBorder
bottom, left, right, top
Constructor Summary
MatteBorder(Icon tileIcon)
Creates a matte border with the specified tile icon.
MatteBorder(Insets borderInsets, Color matteColor)
Creates a matte border with the specified insets and color.
MatteBorder(Insets borderInsets, Icon tileIcon)
Creates a matte border with the specified insets and tile icon.
MatteBorder(int top, int left, int bottom, int right, Color matteColor)
Creates a matte border with the specified insets and color.
MatteBorder(int top, int left, int bottom, int right, Icon tileIcon)
Creates a matte border with the specified insets and tile icon.
Method Summary
Insets | getBorderInsets() Returns the insets of the border.
Insets | getBorderInsets(Component c) Returns the insets of the border.
Insets | getBorderInsets(Component c, Insets insets) Reinitialize the insets parameter with this Border's current Insets.
Color | getMatteColor() Returns the color used for tiling the border or null if a tile icon is being used.
Icon | getTileIcon() Returns the icon used for tiling the border or null if a solid color is being used.
boolean | isBorderOpaque() Returns whether or not the border is opaque.
void | paintBorder(Component c, Graphics g, int x, int y, int width, int height) Paints the matte border.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

color

protected Color color

tileIcon

protected Icon tileIcon
Constructor Detail

MatteBorder

public MatteBorder(int top,
                   int left,
                   int bottom,
                   int right,
                   Color matteColor)
Creates a matte border with the specified insets and color.

Parameters:
top - the top inset of the border
left - the left inset of the border
bottom - the bottom inset of the border
right - the right inset of the border
matteColor - the color rendered for the border

MatteBorder

public MatteBorder(Insets borderInsets,
                   Color matteColor)
Creates a matte border with the specified insets and color.

Parameters:
borderInsets - the insets of the border
matteColor - the color rendered for the border
Since:
1.3

MatteBorder

public MatteBorder(int top,
                   int left,
                   int bottom,
                   int right,
                   Icon tileIcon)
Creates a matte border with the specified insets and tile icon.

Parameters:
top - the top inset of the border
left - the left inset of the border
bottom - the bottom inset of the border
right - the right inset of the border
tileIcon - the icon to be used for tiling the border

MatteBorder

public MatteBorder(Insets borderInsets,
                   Icon tileIcon)
Creates a matte border with the specified insets and tile icon.

Parameters:
borderInsets - the insets of the border
tileIcon - the icon to be used for tiling the border
Since:
1.3

MatteBorder

public MatteBorder(Icon tileIcon)
Creates a matte border with the specified tile icon. The insets will be calculated dynamically based on the size of the tile icon, where the top and bottom will be equal to the tile icon's height, and the left and right will be equal to the tile icon's width.

Parameters:
tileIcon - the icon to be used for tiling the border
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int width,
                        int height)
Paints the matte border.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class EmptyBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
width - the width of the painted border
height - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Returns the insets of the border.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class EmptyBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0
Since:
1.3

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets insets)
Reinitialize the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class EmptyBorder
Parameters:
c - the component for which this border insets value applies
insets - the object to be reinitialized
Returns:
the insets object
Since:
1.3

getBorderInsets

public Insets getBorderInsets()
Returns the insets of the border.

Overrides:
getBorderInsets in class EmptyBorder
Since:
1.3

getMatteColor

public Color getMatteColor()
Returns the color used for tiling the border or null if a tile icon is being used.

Since:
1.3

getTileIcon

public Icon getTileIcon()
Returns the icon used for tiling the border or null if a solid color is being used.

Since:
1.3

isBorderOpaque

public boolean isBorderOpaque()
Returns whether or not the border is opaque.

Specified by:
isBorderOpaque in interface Border
Overrides:
isBorderOpaque in class EmptyBorder
Returns:
false
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SoftBevelBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.border
Class SoftBevelBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.border.BevelBorder
            extended by  javax.swing.border.SoftBevelBorder
All Implemented Interfaces:
Serializable, Border
public class SoftBevelBorder
extends BevelBorder

A class which implements a raised or lowered bevel with softened corners.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class javax.swing.border.BevelBorder
bevelType, highlightInner, highlightOuter, LOWERED, RAISED, shadowInner, shadowOuter
Constructor Summary
SoftBevelBorder(int bevelType)
Creates a bevel border with the specified type and whose colors will be derived from the background color of the component passed into the paintBorder method.
SoftBevelBorder(int bevelType, Color highlight, Color shadow)
Creates a bevel border with the specified type, highlight and shadow colors.
SoftBevelBorder(int bevelType, Color highlightOuterColor, Color highlightInnerColor, Color shadowOuterColor, Color shadowInnerColor)
Creates a bevel border with the specified type, highlight shadow colors.
Method Summary
Insets | getBorderInsets(Component c) Returns the insets of the border.
Insets | getBorderInsets(Component c, Insets insets) Reinitialize the insets parameter with this Border's current Insets.
boolean | isBorderOpaque() Returns whether or not the border is opaque.
void | paintBorder(Component c, Graphics g, int x, int y, int width, int height) Paints the border for the specified component with the specified position and size.
Methods inherited from class javax.swing.border.BevelBorder
getBevelType, getHighlightInnerColor, getHighlightInnerColor, getHighlightOuterColor, getHighlightOuterColor, getShadowInnerColor, getShadowInnerColor, getShadowOuterColor, getShadowOuterColor, paintLoweredBevel, paintRaisedBevel
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SoftBevelBorder

public SoftBevelBorder(int bevelType)
Creates a bevel border with the specified type and whose colors will be derived from the background color of the component passed into the paintBorder method.

Parameters:
bevelType - the type of bevel for the border

SoftBevelBorder

public SoftBevelBorder(int bevelType,
                       Color highlight,
                       Color shadow)
Creates a bevel border with the specified type, highlight and shadow colors.

Parameters:
bevelType - the type of bevel for the border
highlight - the color to use for the bevel highlight
shadow - the color to use for the bevel shadow

SoftBevelBorder

public SoftBevelBorder(int bevelType,
                       Color highlightOuterColor,
                       Color highlightInnerColor,
                       Color shadowOuterColor,
                       Color shadowInnerColor)
Creates a bevel border with the specified type, highlight shadow colors.

Parameters:
bevelType - the type of bevel for the border
highlightOuterColor - the color to use for the bevel outer highlight
highlightInnerColor - the color to use for the bevel inner highlight
shadowOuterColor - the color to use for the bevel outer shadow
shadowInnerColor - the color to use for the bevel inner shadow
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int width,
                        int height)
Paints the border for the specified component with the specified position and size.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class BevelBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
width - the width of the painted border
height - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Returns the insets of the border.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class BevelBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets insets)
Reinitialize the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class BevelBorder
Parameters:
c - the component for which this border insets value applies
insets - the object to be reinitialized
Returns:
the insets object

isBorderOpaque

public boolean isBorderOpaque()
Returns whether or not the border is opaque.

Specified by:
isBorderOpaque in interface Border
Overrides:
isBorderOpaque in class BevelBorder
Returns:
false
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TitledBorder

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.border
Class TitledBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.border.TitledBorder
All Implemented Interfaces:
Serializable, Border
Direct Known Subclasses:
BorderUIResource.TitledBorderUIResource
public class TitledBorder
extends AbstractBorder

A class which implements an arbitrary border with the addition of a String title in a specified position and justification.

If the border, font, or color property values are not specified in the constuctor or by invoking the appropriate set methods, the property values will be defined by the current look and feel, using the following property names in the Defaults Table:

  • "TitledBorder.border"
  • "TitledBorder.font"
  • "TitledBorder.titleColor"

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
static int | ABOVE_BOTTOM Position the title above the border's bottom line.
static int | ABOVE_TOP Position the title above the border's top line.
static int | BELOW_BOTTOM Position the title below the border's bottom line.
static int | BELOW_TOP Position the title below the border's top line.
protected Border | border
static int | BOTTOM Position the title in the middle of the border's bottom line.
static int | CENTER Position title text in the center of the border line.
static int | DEFAULT_JUSTIFICATION Use the default justification for the title text.
static int | DEFAULT_POSITION Use the default vertical orientation for the title text.
protected static int | EDGE_SPACING
static int | LEADING Position title text at the left side of the border line for left to right orientation, at the right side of the border line for right to left orientation.
static int | LEFT Position title text at the left side of the border line.
static int | RIGHT Position title text at the right side of the border line.
protected static int | TEXT_INSET_H
protected static int | TEXT_SPACING
protected String | title
protected Color | titleColor
protected Font | titleFont
protected int | titleJustification
protected int | titlePosition
static int | TOP Position the title in the middle of the border's top line.
static int | TRAILING Position title text at the right side of the border line for left to right orientation, at the left side of the border line for right to left orientation.
Constructor Summary
TitledBorder(Border border)
Creates a TitledBorder instance with the specified border and an empty title.
TitledBorder(Border border, String title)
Creates a TitledBorder instance with the specified border and title.
TitledBorder(Border border, String title, int titleJustification, int titlePosition)
Creates a TitledBorder instance with the specified border, title, title-justification, and title-position.
TitledBorder(Border border, String title, int titleJustification, int titlePosition, Font titleFont)
Creates a TitledBorder instance with the specified border, title, title-justification, title-position, and title-font.
TitledBorder(Border border, String title, int titleJustification, int titlePosition, Font titleFont, Color titleColor)
Creates a TitledBorder instance with the specified border, title, title-justification, title-position, title-font, and title-color.
TitledBorder(String title)
Creates a TitledBorder instance.
Method Summary
int | getBaseline(Component c, int width, int height) Returns the baseline.
Component.BaselineResizeBehavior | getBaselineResizeBehavior(Component c) Returns an enum indicating how the baseline of the border changes as the size changes.
Border | getBorder() Returns the border of the titled border.
Insets | getBorderInsets(Component c) Returns the insets of the border.
Insets | getBorderInsets(Component c, Insets insets) Reinitialize the insets parameter with this Border's current Insets.
protected Font | getFont(Component c)
Dimension | getMinimumSize(Component c) Returns the minimum dimensions this border requires in order to fully display the border and title.
String | getTitle() Returns the title of the titled border.
Color | getTitleColor() Returns the title-color of the titled border.
Font | getTitleFont() Returns the title-font of the titled border.
int | getTitleJustification() Returns the title-justification of the titled border.
int | getTitlePosition() Returns the title-position of the titled border.
boolean | isBorderOpaque() Returns whether or not the border is opaque.
void | paintBorder(Component c, Graphics g, int x, int y, int width, int height) Paints the border for the specified component with the specified position and size.
void | setBorder(Border border) Sets the border of the titled border.
void | setTitle(String title) Sets the title of the titled border.
void | setTitleColor(Color titleColor) Sets the title-color of the titled border.
void | setTitleFont(Font titleFont) Sets the title-font of the titled border.
void | setTitleJustification(int titleJustification) Sets the title-justification of the titled border.
void | setTitlePosition(int titlePosition) Sets the title-position of the titled border.
Methods inherited from class javax.swing.border.AbstractBorder
getInteriorRectangle, getInteriorRectangle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

title

protected String title

border

protected Border border

titlePosition

protected int titlePosition

titleJustification

protected int titleJustification

titleFont

protected Font titleFont

titleColor

protected Color titleColor

DEFAULT_POSITION

public static final int DEFAULT_POSITION
Use the default vertical orientation for the title text.

See Also:
Constant Field Values

ABOVE_TOP

public static final int ABOVE_TOP
Position the title above the border's top line.

See Also:
Constant Field Values

TOP

public static final int TOP
Position the title in the middle of the border's top line.

See Also:
Constant Field Values

BELOW_TOP

public static final int BELOW_TOP
Position the title below the border's top line.

See Also:
Constant Field Values

ABOVE_BOTTOM

public static final int ABOVE_BOTTOM
Position the title above the border's bottom line.

See Also:
Constant Field Values

BOTTOM

public static final int BOTTOM
Position the title in the middle of the border's bottom line.

See Also:
Constant Field Values

BELOW_BOTTOM

public static final int BELOW_BOTTOM
Position the title below the border's bottom line.

See Also:
Constant Field Values

DEFAULT_JUSTIFICATION

public static final int DEFAULT_JUSTIFICATION
Use the default justification for the title text.

See Also:
Constant Field Values

LEFT

public static final int LEFT
Position title text at the left side of the border line.

See Also:
Constant Field Values

CENTER

public static final int CENTER
Position title text in the center of the border line.

See Also:
Constant Field Values

RIGHT

public static final int RIGHT
Position title text at the right side of the border line.

See Also:
Constant Field Values

LEADING

public static final int LEADING
Position title text at the left side of the border line for left to right orientation, at the right side of the border line for right to left orientation.

See Also:
Constant Field Values

TRAILING

public static final int TRAILING
Position title text at the right side of the border line for left to right orientation, at the left side of the border line for right to left orientation.

See Also:
Constant Field Values

EDGE_SPACING

protected static final int EDGE_SPACING
See Also:
Constant Field Values

TEXT_SPACING

protected static final int TEXT_SPACING
See Also:
Constant Field Values

TEXT_INSET_H

protected static final int TEXT_INSET_H
See Also:
Constant Field Values
Constructor Detail

TitledBorder

public TitledBorder(String title)
Creates a TitledBorder instance.

Parameters:
title - the title the border should display

TitledBorder

public TitledBorder(Border border)
Creates a TitledBorder instance with the specified border and an empty title.

Parameters:
border - the border

TitledBorder

public TitledBorder(Border border,
                    String title)
Creates a TitledBorder instance with the specified border and title.

Parameters:
border - the border
title - the title the border should display

TitledBorder

public TitledBorder(Border border,
                    String title,
                    int titleJustification,
                    int titlePosition)
Creates a TitledBorder instance with the specified border, title, title-justification, and title-position.

Parameters:
border - the border
title - the title the border should display
titleJustification - the justification for the title
titlePosition - the position for the title

TitledBorder

public TitledBorder(Border border,
                    String title,
                    int titleJustification,
                    int titlePosition,
                    Font titleFont)
Creates a TitledBorder instance with the specified border, title, title-justification, title-position, and title-font.

Parameters:
border - the border
title - the title the border should display
titleJustification - the justification for the title
titlePosition - the position for the title
titleFont - the font for rendering the title

TitledBorder

public TitledBorder(Border border,
                    String title,
                    int titleJustification,
                    int titlePosition,
                    Font titleFont,
                    Color titleColor)
Creates a TitledBorder instance with the specified border, title, title-justification, title-position, title-font, and title-color.

Parameters:
border - the border
title - the title the border should display
titleJustification - the justification for the title
titlePosition - the position for the title
titleFont - the font of the title
titleColor - the color of the title
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int width,
                        int height)
Paints the border for the specified component with the specified position and size.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
width - the width of the painted border
height - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Returns the insets of the border.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets insets)
Reinitialize the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
insets - the object to be reinitialized
Returns:
the insets object

isBorderOpaque

public boolean isBorderOpaque()
Returns whether or not the border is opaque.

Specified by:
isBorderOpaque in interface Border
Overrides:
isBorderOpaque in class AbstractBorder
Returns:
false

getTitle

public String getTitle()
Returns the title of the titled border.

getBorder

public Border getBorder()
Returns the border of the titled border.

getTitlePosition

public int getTitlePosition()
Returns the title-position of the titled border.

getTitleJustification

public int getTitleJustification()
Returns the title-justification of the titled border.

getTitleFont

public Font getTitleFont()
Returns the title-font of the titled border.

getTitleColor

public Color getTitleColor()
Returns the title-color of the titled border.

setTitle

public void setTitle(String title)
Sets the title of the titled border. param title the title for the border

setBorder

public void setBorder(Border border)
Sets the border of the titled border.

Parameters:
border - the border

setTitlePosition

public void setTitlePosition(int titlePosition)
Sets the title-position of the titled border.

Parameters:
titlePosition - the position for the border

setTitleJustification

public void setTitleJustification(int titleJustification)
Sets the title-justification of the titled border.

Parameters:
titleJustification - the justification for the border

setTitleFont

public void setTitleFont(Font titleFont)
Sets the title-font of the titled border.

Parameters:
titleFont - the font for the border title

setTitleColor

public void setTitleColor(Color titleColor)
Sets the title-color of the titled border.

Parameters:
titleColor - the color for the border title

getMinimumSize

public Dimension getMinimumSize(Component c)
Returns the minimum dimensions this border requires in order to fully display the border and title.

Parameters:
c - the component where this border will be drawn

getBaseline

public int getBaseline(Component c,
                       int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class AbstractBorder
Parameters:
c - Component baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
the baseline or < 0 indicating there is no reasonable baseline
Throws:
NullPointerException
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior(Component c)
Returns an enum indicating how the baseline of the border changes as the size changes.

Overrides:
getBaselineResizeBehavior in class AbstractBorder
Parameters:
c - Component to return baseline resize behavior for
Returns:
an enum indicating how the baseline changes as the border is resized
Throws:
NullPointerException
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getFont

protected Font getFont(Component c)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


BorderFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class BorderFactory

java.lang.Object
    extended by  javax.swing.BorderFactory

public class BorderFactory
extends Object

Factory class for vending standard Border objects. Wherever possible, this factory will hand out references to shared Border instances. For further information and examples see How to Use Borders, a section in The Java Tutorial.

Method Summary
static Border | createBevelBorder(int type) Creates a beveled border of the specified type, using brighter shades of the component's current background color for highlighting, and darker shading for shadows.
static Border | createBevelBorder(int type, Color highlight, Color shadow) Creates a beveled border of the specified type, using the specified highlighting and shadowing.
static Border | createBevelBorder(int type, Color highlightOuter, Color highlightInner, Color shadowOuter, Color shadowInner) Creates a beveled border of the specified type, using the specified colors for the inner and outer highlight and shadow areas.
static CompoundBorder | createCompoundBorder() Creates a compound border with a null inside edge and a null outside edge.
static CompoundBorder | createCompoundBorder(Border outsideBorder, Border insideBorder) Creates a compound border specifying the border objects to use for the outside and inside edges.
static Border | createEmptyBorder() Creates an empty border that takes up no space.
static Border | createEmptyBorder(int top, int left, int bottom, int right) Creates an empty border that takes up space but which does no drawing, specifying the width of the top, left, bottom, and right sides.
static Border | createEtchedBorder() Creates a border with an "etched" look using the component's current background color for highlighting and shading.
static Border | createEtchedBorder(Color highlight, Color shadow) Creates a border with an "etched" look using the specified highlighting and shading colors.
static Border | createEtchedBorder(int type) Creates a border with an "etched" look using the component's current background color for highlighting and shading.
static Border | createEtchedBorder(int type, Color highlight, Color shadow) Creates a border with an "etched" look using the specified highlighting and shading colors.
static Border | createLineBorder(Color color) Creates a line border withe the specified color.
static Border | createLineBorder(Color color, int thickness) Creates a line border with the specified color and width.
static Border | createLoweredBevelBorder() Creates a border with a lowered beveled edge, using brighter shades of the component's current background color for highlighting, and darker shading for shadows.
static MatteBorder | createMatteBorder(int top, int left, int bottom, int right, Color color) Creates a matte-look border using a solid color.
static MatteBorder | createMatteBorder(int top, int left, int bottom, int right, Icon tileIcon) Creates a matte-look border that consists of multiple tiles of a specified icon.
static Border | createRaisedBevelBorder() Creates a border with a raised beveled edge, using brighter shades of the component's current background color for highlighting, and darker shading for shadows.
static TitledBorder | createTitledBorder(Border border) Creates a new titled border with an empty title, the specified border object, the default text position (sitting on the top line), the default justification (leading), and the default font and text color (determined by the current look and feel).
static TitledBorder | createTitledBorder(Border border, String title) Adds a title to an existing border, with default positioning (sitting on the top line), default justification (leading) and the default font and text color (determined by the current look and feel).
static TitledBorder | createTitledBorder(Border border, String title, int titleJustification, int titlePosition) Adds a title to an existing border, with the specified positioning and using the default font and text color (determined by the current look and feel).
static TitledBorder | createTitledBorder(Border border, String title, int titleJustification, int titlePosition, Font titleFont) Adds a title to an existing border, with the specified positioning and font, and using the default text color (determined by the current look and feel).
static TitledBorder | createTitledBorder(Border border, String title, int titleJustification, int titlePosition, Font titleFont, Color titleColor) Adds a title to an existing border, with the specified positioning, font and color.
static TitledBorder | createTitledBorder(String title) Creates a new titled border with the specified title, the default border type (determined by the current look and feel), the default text position (sitting on the top line), the default justification (leading), and the default font and text color (determined by the current look and feel).
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createLineBorder

public static Border createLineBorder(Color color)
Creates a line border withe the specified color.

Parameters:
color - a Color to use for the line
Returns:
the Border object

createLineBorder

public static Border createLineBorder(Color color,
                                      int thickness)
Creates a line border with the specified color and width. The width applies to all four sides of the border. To specify widths individually for the top, bottom, left, and right, use createMatteBorder(int,int,int,int,Color).

Parameters:
color - a Color to use for the line
thickness - an integer specifying the width in pixels
Returns:
the Border object

createRaisedBevelBorder

public static Border createRaisedBevelBorder()
Creates a border with a raised beveled edge, using brighter shades of the component's current background color for highlighting, and darker shading for shadows. (In a raised border, highlights are on top and shadows are underneath.)

Returns:
the Border object

createLoweredBevelBorder

public static Border createLoweredBevelBorder()
Creates a border with a lowered beveled edge, using brighter shades of the component's current background color for highlighting, and darker shading for shadows. (In a lowered border, shadows are on top and highlights are underneath.)

Returns:
the Border object

createBevelBorder

public static Border createBevelBorder(int type)
Creates a beveled border of the specified type, using brighter shades of the component's current background color for highlighting, and darker shading for shadows. (In a lowered border, shadows are on top and highlights are underneath.)

Parameters:
type - an integer specifying either BevelBorder.LOWERED or BevelBorder.RAISED
Returns:
the Border object

createBevelBorder

public static Border createBevelBorder(int type,
                                       Color highlight,
                                       Color shadow)
Creates a beveled border of the specified type, using the specified highlighting and shadowing. The outer edge of the highlighted area uses a brighter shade of the highlight color. The inner edge of the shadow area uses a brighter shade of the shadow color.

Parameters:
type - an integer specifying either BevelBorder.LOWERED or BevelBorder.RAISED
highlight - a Color object for highlights
shadow - a Color object for shadows
Returns:
the Border object

createBevelBorder

public static Border createBevelBorder(int type,
                                       Color highlightOuter,
                                       Color highlightInner,
                                       Color shadowOuter,
                                       Color shadowInner)
Creates a beveled border of the specified type, using the specified colors for the inner and outer highlight and shadow areas.

Note: The shadow inner and outer colors are switched for a lowered bevel border.

Parameters:
type - an integer specifying either BevelBorder.LOWERED or BevelBorder.RAISED
highlightOuter - a Color object for the outer edge of the highlight area
highlightInner - a Color object for the inner edge of the highlight area
shadowOuter - a Color object for the outer edge of the shadow area
shadowInner - a Color object for the inner edge of the shadow area
Returns:
the Border object

createEtchedBorder

public static Border createEtchedBorder()
Creates a border with an "etched" look using the component's current background color for highlighting and shading.

Returns:
the Border object

createEtchedBorder

public static Border createEtchedBorder(Color highlight,
                                        Color shadow)
Creates a border with an "etched" look using the specified highlighting and shading colors.

Parameters:
highlight - a Color object for the border highlights
shadow - a Color object for the border shadows
Returns:
the Border object

createEtchedBorder

public static Border createEtchedBorder(int type)
Creates a border with an "etched" look using the component's current background color for highlighting and shading.

Parameters:
type - one of EtchedBorder.RAISED, or EtchedBorder.LOWERED
Returns:
the Border object
Throws:
IllegalArgumentException - if type is not either EtchedBorder.RAISED or EtchedBorder.LOWERED
Since:
1.3

createEtchedBorder

public static Border createEtchedBorder(int type,
                                        Color highlight,
                                        Color shadow)
Creates a border with an "etched" look using the specified highlighting and shading colors.

Parameters:
type - one of EtchedBorder.RAISED, or EtchedBorder.LOWERED
highlight - a Color object for the border highlights
shadow - a Color object for the border shadows
Returns:
the Border object
Since:
1.3

createTitledBorder

public static TitledBorder createTitledBorder(String title)
Creates a new titled border with the specified title, the default border type (determined by the current look and feel), the default text position (sitting on the top line), the default justification (leading), and the default font and text color (determined by the current look and feel).

Parameters:
title - a String containing the text of the title
Returns:
the TitledBorder object

createTitledBorder

public static TitledBorder createTitledBorder(Border border)
Creates a new titled border with an empty title, the specified border object, the default text position (sitting on the top line), the default justification (leading), and the default font and text color (determined by the current look and feel).

Parameters:
border - the Border object to add the title to; if null the Border is determined by the current look and feel.
Returns:
the TitledBorder object

createTitledBorder

public static TitledBorder createTitledBorder(Border border,
                                              String title)
Adds a title to an existing border, with default positioning (sitting on the top line), default justification (leading) and the default font and text color (determined by the current look and feel).

Parameters:
border - the Border object to add the title to
title - a String containing the text of the title
Returns:
the TitledBorder object

createTitledBorder

public static TitledBorder createTitledBorder(Border border,
                                              String title,
                                              int titleJustification,
                                              int titlePosition)
Adds a title to an existing border, with the specified positioning and using the default font and text color (determined by the current look and feel).

Parameters:
border - the Border object to add the title to
title - a String containing the text of the title
titleJustification - an integer specifying the justification of the title -- one of the following:
  • TitledBorder.LEFT
  • TitledBorder.CENTER
  • TitledBorder.RIGHT
  • TitledBorder.LEADING
  • TitledBorder.TRAILING
  • TitledBorder.DEFAULT_JUSTIFICATION (leading)
titlePosition - an integer specifying the vertical position of the text in relation to the border -- one of the following:
  • TitledBorder.ABOVE_TOP
  • TitledBorder.TOP (sitting on the top line)
  • TitledBorder.BELOW_TOP
  • TitledBorder.ABOVE_BOTTOM
  • TitledBorder.BOTTOM (sitting on the bottom line)
  • TitledBorder.BELOW_BOTTOM
  • TitledBorder.DEFAULT_POSITION (top)
Returns:
the TitledBorder object

createTitledBorder

public static TitledBorder createTitledBorder(Border border,
                                              String title,
                                              int titleJustification,
                                              int titlePosition,
                                              Font titleFont)
Adds a title to an existing border, with the specified positioning and font, and using the default text color (determined by the current look and feel).

Parameters:
border - the Border object to add the title to
title - a String containing the text of the title
titleJustification - an integer specifying the justification of the title -- one of the following:
  • TitledBorder.LEFT
  • TitledBorder.CENTER
  • TitledBorder.RIGHT
  • TitledBorder.LEADING
  • TitledBorder.TRAILING
  • TitledBorder.DEFAULT_JUSTIFICATION (leading)
titlePosition - an integer specifying the vertical position of the text in relation to the border -- one of the following:
  • TitledBorder.ABOVE_TOP
  • TitledBorder.TOP (sitting on the top line)
  • TitledBorder.BELOW_TOP
  • TitledBorder.ABOVE_BOTTOM
  • TitledBorder.BOTTOM (sitting on the bottom line)
  • TitledBorder.BELOW_BOTTOM
  • TitledBorder.DEFAULT_POSITION (top)
titleFont - a Font object specifying the title font
Returns:
the TitledBorder object

createTitledBorder

public static TitledBorder createTitledBorder(Border border,
                                              String title,
                                              int titleJustification,
                                              int titlePosition,
                                              Font titleFont,
                                              Color titleColor)
Adds a title to an existing border, with the specified positioning, font and color.

Parameters:
border - the Border object to add the title to
title - a String containing the text of the title
titleJustification - an integer specifying the justification of the title -- one of the following:
  • TitledBorder.LEFT
  • TitledBorder.CENTER
  • TitledBorder.RIGHT
  • TitledBorder.LEADING
  • TitledBorder.TRAILING
  • TitledBorder.DEFAULT_JUSTIFICATION (leading)
titlePosition - an integer specifying the vertical position of the text in relation to the border -- one of the following:
  • TitledBorder.ABOVE_TOP
  • TitledBorder.TOP (sitting on the top line)
  • TitledBorder.BELOW_TOP
  • TitledBorder.ABOVE_BOTTOM
  • TitledBorder.BOTTOM (sitting on the bottom line)
  • TitledBorder.BELOW_BOTTOM
  • TitledBorder.DEFAULT_POSITION (top)
titleFont - a Font object specifying the title font
titleColor - a Color object specifying the title color
Returns:
the TitledBorder object

createEmptyBorder

public static Border createEmptyBorder()
Creates an empty border that takes up no space. (The width of the top, bottom, left, and right sides are all zero.)

Returns:
the Border object

createEmptyBorder

public static Border createEmptyBorder(int top,
                                       int left,
                                       int bottom,
                                       int right)
Creates an empty border that takes up space but which does no drawing, specifying the width of the top, left, bottom, and right sides.

Parameters:
top - an integer specifying the width of the top, in pixels
left - an integer specifying the width of the left side, in pixels
bottom - an integer specifying the width of the bottom, in pixels
right - an integer specifying the width of the right side, in pixels
Returns:
the Border object

createCompoundBorder

public static CompoundBorder createCompoundBorder()
Creates a compound border with a null inside edge and a null outside edge.

Returns:
the CompoundBorder object

createCompoundBorder

public static CompoundBorder createCompoundBorder(Border outsideBorder,
                                                  Border insideBorder)
Creates a compound border specifying the border objects to use for the outside and inside edges.

Parameters:
outsideBorder - a Border object for the outer edge of the compound border
insideBorder - a Border object for the inner edge of the compound border
Returns:
the CompoundBorder object

createMatteBorder

public static MatteBorder createMatteBorder(int top,
                                            int left,
                                            int bottom,
                                            int right,
                                            Color color)
Creates a matte-look border using a solid color. (The difference between this border and a line border is that you can specify the individual border dimensions.)

Parameters:
top - an integer specifying the width of the top, in pixels
left - an integer specifying the width of the left side, in pixels
bottom - an integer specifying the width of the right side, in pixels
right - an integer specifying the width of the bottom, in pixels
color - a Color to use for the border
Returns:
the MatteBorder object

createMatteBorder

public static MatteBorder createMatteBorder(int top,
                                            int left,
                                            int bottom,
                                            int right,
                                            Icon tileIcon)
Creates a matte-look border that consists of multiple tiles of a specified icon. Multiple copies of the icon are placed side-by-side to fill up the border area.

Note:
If the icon doesn't load, the border area is painted gray.

Parameters:
top - an integer specifying the width of the top, in pixels
left - an integer specifying the width of the left side, in pixels
bottom - an integer specifying the width of the right side, in pixels
right - an integer specifying the width of the bottom, in pixels
tileIcon - the Icon object used for the border tiles
Returns:
the MatteBorder object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BoundedRangeModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface BoundedRangeModel

All Known Implementing Classes:
DefaultBoundedRangeModel
public interface BoundedRangeModel

Defines the data model used by components like Sliders and ProgressBars. Defines four interrelated integer properties: minimum, maximum, extent and value. These four integers define two nested ranges like this:

 minimum <= value <= value+extent <= maximum
The outer range is minimum,maximum and the inner range is value,value+extent. The inner range must lie within the outer one, i.e. value must be less than or equal to maximum and value+extent must greater than or equal to minimum, and maximum must be greater than or equal to minimum. There are a few features of this model that one might find a little surprising. These quirks exist for the convenience of the Swing BoundedRangeModel clients, such as Slider and ScrollBar.
  • The minimum and maximum set methods "correct" the other three properties to accommodate their new value argument. For example setting the model's minimum may change its maximum, value, and extent properties (in that order), to maintain the constraints specified above.
  • The value and extent set methods "correct" their argument to fit within the limits defined by the other three properties. For example if value == maximum, setExtent(10) would change the extent (back) to zero.
  • The four BoundedRangeModel values are defined as Java Beans properties however Swing ChangeEvents are used to notify clients of changes rather than PropertyChangeEvents. This was done to keep the overhead of monitoring a BoundedRangeModel low. Changes are often reported at MouseDragged rates.

For an example of specifying custom bounded range models used by sliders, see The Anatomy of a Swing-Based Program in The Java Tutorial.

See Also:
DefaultBoundedRangeModel

Method Summary
void | addChangeListener(ChangeListener x) Adds a ChangeListener to the model's listener list.
int | getExtent() Returns the model's extent, the length of the inner range that begins at the model's value.
int | getMaximum() Returns the model's maximum.
int | getMinimum() Returns the minimum acceptable value.
int | getValue() Returns the model's current value.
boolean | getValueIsAdjusting() Returns true if the current changes to the value property are part of a series of changes.
void | removeChangeListener(ChangeListener x) Removes a ChangeListener from the model's listener list.
void | setExtent(int newExtent) Sets the model's extent.
void | setMaximum(int newMaximum) Sets the model's maximum to newMaximum.
void | setMinimum(int newMinimum) Sets the model's minimum to newMinimum.
void | setRangeProperties(int value, int extent, int min, int max, boolean adjusting) This method sets all of the model's data with a single method call.
void | setValue(int newValue) Sets the model's current value to newValue if newValue satisfies the model's constraints.
void | setValueIsAdjusting(boolean b) This attribute indicates that any upcoming changes to the value of the model should be considered a single event.

Method Detail

getMinimum

int getMinimum()
Returns the minimum acceptable value.

Returns:
the value of the minimum property
See Also:
setMinimum(int)

setMinimum

void setMinimum(int newMinimum)
Sets the model's minimum to newMinimum. The other three properties may be changed as well, to ensure that:
 minimum <= value <= value+extent <= maximum

Notifies any listeners if the model changes.

Parameters:
newMinimum - the model's new minimum
See Also:
getMinimum(), addChangeListener(javax.swing.event.ChangeListener)

getMaximum

int getMaximum()
Returns the model's maximum. Note that the upper limit on the model's value is (maximum - extent).

Returns:
the value of the maximum property.
See Also:
setMaximum(int), setExtent(int)

setMaximum

void setMaximum(int newMaximum)
Sets the model's maximum to newMaximum. The other three properties may be changed as well, to ensure that
 minimum <= value <= value+extent <= maximum

Notifies any listeners if the model changes.

Parameters:
newMaximum - the model's new maximum
See Also:
getMaximum(), addChangeListener(javax.swing.event.ChangeListener)

getValue

int getValue()
Returns the model's current value. Note that the upper limit on the model's value is maximum - extent and the lower limit is minimum.

Returns:
the model's value
See Also:
setValue(int)

setValue

void setValue(int newValue)
Sets the model's current value to newValue if newValue satisfies the model's constraints. Those constraints are:
 minimum <= value <= value+extent <= maximum
Otherwise, if newValue is less than minimum it's set to minimum, if its greater than maximum then it's set to maximum, and if it's greater than value+extent then it's set to value+extent.

When a BoundedRange model is used with a scrollbar the value specifies the origin of the scrollbar knob (aka the "thumb" or "elevator"). The value usually represents the origin of the visible part of the object being scrolled.

Notifies any listeners if the model changes.

Parameters:
newValue - the model's new value
See Also:
getValue()

setValueIsAdjusting

void setValueIsAdjusting(boolean b)
This attribute indicates that any upcoming changes to the value of the model should be considered a single event. This attribute will be set to true at the start of a series of changes to the value, and will be set to false when the value has finished changing. Normally this allows a listener to only take action when the final value change in committed, instead of having to do updates for all intermediate values.

Sliders and scrollbars use this property when a drag is underway.

Parameters:
b - true if the upcoming changes to the value property are part of a series

getValueIsAdjusting

boolean getValueIsAdjusting()
Returns true if the current changes to the value property are part of a series of changes.

Returns:
the valueIsAdjustingProperty.
See Also:
setValueIsAdjusting(boolean)

getExtent

int getExtent()
Returns the model's extent, the length of the inner range that begins at the model's value.

Returns:
the value of the model's extent property
See Also:
setExtent(int), setValue(int)

setExtent

void setExtent(int newExtent)
Sets the model's extent. The newExtent is forced to be greater than or equal to zero and less than or equal to maximum - value.

When a BoundedRange model is used with a scrollbar the extent defines the length of the scrollbar knob (aka the "thumb" or "elevator"). The extent usually represents how much of the object being scrolled is visible. When used with a slider, the extent determines how much the value can "jump", for example when the user presses PgUp or PgDn.

Notifies any listeners if the model changes.

Parameters:
newExtent - the model's new extent
See Also:
getExtent(), setValue(int)

setRangeProperties

void setRangeProperties(int value,
                        int extent,
                        int min,
                        int max,
                        boolean adjusting)
This method sets all of the model's data with a single method call. The method results in a single change event being generated. This is convenient when you need to adjust all the model data simultaneously and do not want individual change events to occur.

Parameters:
value - an int giving the current value
extent - an int giving the amount by which the value can "jump"
min - an int giving the minimum value
max - an int giving the maximum value
adjusting - a boolean, true if a series of changes are in progress
See Also:
setValue(int), setExtent(int), setMinimum(int), setMaximum(int), setValueIsAdjusting(boolean)

addChangeListener

void addChangeListener(ChangeListener x)
Adds a ChangeListener to the model's listener list.

Parameters:
x - the ChangeListener to add
See Also:
removeChangeListener(javax.swing.event.ChangeListener)

removeChangeListener

void removeChangeListener(ChangeListener x)
Removes a ChangeListener from the model's listener list.

Parameters:
x - the ChangeListener to remove
See Also:
addChangeListener(javax.swing.event.ChangeListener)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Box

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class Box

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.Box
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public class Box
extends JComponent
implements Accessible

A lightweight container that uses a BoxLayout object as its layout manager. Box provides several class methods that are useful for containers using BoxLayout -- even non-Box containers.

The Box class can create several kinds of invisible components that affect layout: glue, struts, and rigid areas. If all the components your Box contains have a fixed size, you might want to use a glue component (returned by createGlue) to control the components' positions. If you need a fixed amount of space between two components, try using a strut (createHorizontalStrut or createVerticalStrut). If you need an invisible component that always takes up the same amount of space, get it by invoking createRigidArea.

If you are implementing a BoxLayout you can find further information and examples in How to Use BoxLayout, a section in The Java Tutorial.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
BoxLayout

Nested Class Summary
protected class | Box.AccessibleBox This class implements accessibility support for the Box class.
static class | Box.Filler An implementation of a lightweight component that participates in layout but has no view.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
Box(int axis)
Creates a Box that displays its components along the the specified axis.
Method Summary
static Component | createGlue() Creates an invisible "glue" component that can be useful in a Box whose visible components have a maximum width (for a horizontal box) or height (for a vertical box).
static Box | createHorizontalBox() Creates a Box that displays its components from left to right.
static Component | createHorizontalGlue() Creates a horizontal glue component.
static Component | createHorizontalStrut(int width) Creates an invisible, fixed-width component.
static Component | createRigidArea(Dimension d) Creates an invisible component that's always the specified size.
static Box | createVerticalBox() Creates a Box that displays its components from top to bottom.
static Component | createVerticalGlue() Creates a vertical glue component.
static Component | createVerticalStrut(int height) Creates an invisible, fixed-height component.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this Box.
protected void | paintComponent(Graphics g) Paints this Box.
void | setLayout(LayoutManager l) Throws an AWTError, since a Box can use only a BoxLayout.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update, updateUI
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Box

public Box(int axis)
Creates a Box that displays its components along the the specified axis.

Parameters:
axis - can be BoxLayout.X_AXIS, BoxLayout.Y_AXIS, BoxLayout.LINE_AXIS or BoxLayout.PAGE_AXIS.
Throws:
AWTError - if the axis is invalid
See Also:
createHorizontalBox(), createVerticalBox()
Method Detail

createHorizontalBox

public static Box createHorizontalBox()
Creates a Box that displays its components from left to right. If you want a Box that respects the component orientation you should create the Box using the constructor and pass in BoxLayout.LINE_AXIS, eg:
   Box lineBox = new Box(BoxLayout.LINE_AXIS);

Returns:
the box

createVerticalBox

public static Box createVerticalBox()
Creates a Box that displays its components from top to bottom. If you want a Box that respects the component orientation you should create the Box using the constructor and pass in BoxLayout.PAGE_AXIS, eg:
   Box lineBox = new Box(BoxLayout.PAGE_AXIS);

Returns:
the box

createRigidArea

public static Component createRigidArea(Dimension d)
Creates an invisible component that's always the specified size.

Parameters:
d - the dimensions of the invisible component
Returns:
the component
See Also:
createGlue(), createHorizontalStrut(int), createVerticalStrut(int)

createHorizontalStrut

public static Component createHorizontalStrut(int width)
Creates an invisible, fixed-width component. In a horizontal box, you typically use this method to force a certain amount of space between two components. In a vertical box, you might use this method to force the box to be at least the specified width. The invisible component has no height unless excess space is available, in which case it takes its share of available space, just like any other component that has no maximum height.

Parameters:
width - the width of the invisible component, in pixels >= 0
Returns:
the component
See Also:
createVerticalStrut(int), createGlue(), createRigidArea(java.awt.Dimension)

createVerticalStrut

public static Component createVerticalStrut(int height)
Creates an invisible, fixed-height component. In a vertical box, you typically use this method to force a certain amount of space between two components. In a horizontal box, you might use this method to force the box to be at least the specified height. The invisible component has no width unless excess space is available, in which case it takes its share of available space, just like any other component that has no maximum width.

Parameters:
height - the height of the invisible component, in pixels >= 0
Returns:
the component
See Also:
createHorizontalStrut(int), createGlue(), createRigidArea(java.awt.Dimension)

createGlue

public static Component createGlue()
Creates an invisible "glue" component that can be useful in a Box whose visible components have a maximum width (for a horizontal box) or height (for a vertical box). You can think of the glue component as being a gooey substance that expands as much as necessary to fill the space between its neighboring components.

For example, suppose you have a horizontal box that contains two fixed-size components. If the box gets extra space, the fixed-size components won't become larger, so where does the extra space go? Without glue, the extra space goes to the right of the second component. If you put glue between the fixed-size components, then the extra space goes there. If you put glue before the first fixed-size component, the extra space goes there, and the fixed-size components are shoved against the right edge of the box. If you put glue before the first fixed-size component and after the second fixed-size component, the fixed-size components are centered in the box.

To use glue, call Box.createGlue and add the returned component to a container. The glue component has no minimum or preferred size, so it takes no space unless excess space is available. If excess space is available, then the glue component takes its share of available horizontal or vertical space, just like any other component that has no maximum width or height.

Returns:
the component

createHorizontalGlue

public static Component createHorizontalGlue()
Creates a horizontal glue component.

Returns:
the component

createVerticalGlue

public static Component createVerticalGlue()
Creates a vertical glue component.

Returns:
the component

setLayout

public void setLayout(LayoutManager l)
Throws an AWTError, since a Box can use only a BoxLayout.

Overrides:
setLayout in class Container
Parameters:
l - the layout manager to use
See Also:
Container.doLayout(), Container.getLayout()

paintComponent

protected void paintComponent(Graphics g)
Paints this Box. If this Box has a UI this method invokes super's implementation, otherwise if this Box is opaque the Graphics is filled using the background.

Overrides:
paintComponent in class JComponent
Parameters:
g - the Graphics to paint to
Throws:
NullPointerException - if g is null
Since:
1.6
See Also:
JComponent.paint(java.awt.Graphics), ComponentUI

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this Box. For boxes, the AccessibleContext takes the form of an AccessibleBox. A new AccessibleAWTBox instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleBox that serves as the AccessibleContext of this Box
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Box.AccessibleBox

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class Box.AccessibleBox

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.Box.AccessibleBox
All Implemented Interfaces:
Serializable, AccessibleComponent
Enclosing class:
Box
protected class Box.AccessibleBox
extends Container.AccessibleAWTContainer

This class implements accessibility support for the Box class.

Nested Class Summary
Nested classes/interfaces inherited from class java.awt.Container.AccessibleAWTContainer
Container.AccessibleAWTContainer.AccessibleContainerHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class java.awt.Container.AccessibleAWTContainer
accessibleContainerHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected Box.AccessibleBox()
Method Summary
 AccessibleRole getAccessibleRole()
Gets the role of this object.
Methods inherited from class java.awt.Container.AccessibleAWTContainer
addPropertyChangeListener, getAccessibleAt, getAccessibleChild, getAccessibleChildrenCount
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleDescription, getAccessibleIndexInParent, getAccessibleName, getAccessibleParent, getAccessibleStateSet, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, removePropertyChangeListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Box.AccessibleBox

protected Box.AccessibleBox()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Gets the role of this object.

Overrides:
getAccessibleRole in class Component.AccessibleAWTComponent
Returns:
an instance of AccessibleRole describing the role of the object (AccessibleRole.FILLER)
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Box.Filler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class Box.Filler

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.Box.Filler
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
Enclosing class:
Box
public static class Box.Filler
extends JComponent
implements Accessible

An implementation of a lightweight component that participates in layout but has no view.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class Box.Filler.AccessibleBoxFiller
This class implements accessibility support for the Box.Filler class.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
Box.Filler(Dimension min, Dimension pref, Dimension max)
Constructor to create shape with the given size ranges.
Method Summary
void | changeShape(Dimension min, Dimension pref, Dimension max) Change the size requests for this shape.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this Box.Filler.
protected void | paintComponent(Graphics g) Paints this Filler.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update, updateUI
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Box.Filler

public Box.Filler(Dimension min,
                  Dimension pref,
                  Dimension max)
Constructor to create shape with the given size ranges.

Parameters:
min - Minimum size
pref - Preferred size
max - Maximum size
Method Detail

changeShape

public void changeShape(Dimension min,
                        Dimension pref,
                        Dimension max)
Change the size requests for this shape. An invalidate() is propagated upward as a result so that layout will eventually happen with using the new sizes.

Parameters:
min - Value to return for getMinimumSize
pref - Value to return for getPreferredSize
max - Value to return for getMaximumSize

paintComponent

protected void paintComponent(Graphics g)
Paints this Filler. If this Filler has a UI this method invokes super's implementation, otherwise if this Filler is opaque the Graphics is filled using the background.

Overrides:
paintComponent in class JComponent
Parameters:
g - the Graphics to paint to
Throws:
NullPointerException - if g is null
Since:
1.6
See Also:
JComponent.paint(java.awt.Graphics), ComponentUI

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this Box.Filler. For box fillers, the AccessibleContext takes the form of an AccessibleBoxFiller. A new AccessibleAWTBoxFiller instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleBoxFiller that serves as the AccessibleContext of this Box.Filler.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Box.Filler.AccessibleBoxFiller

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class Box.Filler.AccessibleBoxFiller

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  javax.swing.Box.Filler.AccessibleBoxFiller
All Implemented Interfaces:
Serializable, AccessibleComponent
Enclosing class:
Box.Filler
protected class Box.Filler.AccessibleBoxFiller
extends Component.AccessibleAWTComponent

This class implements accessibility support for the Box.Filler class.

Nested Class Summary
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected Box.Filler.AccessibleBoxFiller()
Method Summary
 AccessibleRole getAccessibleRole()
Gets the role of this object.
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, addPropertyChangeListener, contains, getAccessibleAt, getAccessibleChild, getAccessibleChildrenCount, getAccessibleComponent, getAccessibleDescription, getAccessibleIndexInParent, getAccessibleName, getAccessibleParent, getAccessibleStateSet, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, removePropertyChangeListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Box.Filler.AccessibleBoxFiller

protected Box.Filler.AccessibleBoxFiller()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Gets the role of this object.

Overrides:
getAccessibleRole in class Component.AccessibleAWTComponent
Returns:
an instance of AccessibleRole describing the role of the object (AccessibleRole.FILLER)
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BoxLayout

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class BoxLayout

java.lang.Object
    extended by  javax.swing.BoxLayout
All Implemented Interfaces:
LayoutManager, LayoutManager2, Serializable
Direct Known Subclasses:
DefaultMenuLayout
public class BoxLayout
extends Object
implements LayoutManager2, Serializable

A layout manager that allows multiple components to be laid out either vertically or horizontally. The components will not wrap so, for example, a vertical arrangement of components will stay vertically arranged when the frame is resized.

The following text describes this graphic.

Nesting multiple panels with different combinations of horizontal and vertical gives an effect similar to GridBagLayout, without the complexity. The diagram shows two panels arranged horizontally, each of which contains 3 components arranged vertically.

The BoxLayout manager is constructed with an axis parameter that specifies the type of layout that will be done. There are four choices:

X_AXIS - Components are laid out horizontally from left to right.
Y_AXIS - Components are laid out vertically from top to bottom.
LINE_AXIS - Components are laid out the way words are laid out in a line, based on the container's ComponentOrientation property. If the container's ComponentOrientation is horizontal then components are laid out horizontally, otherwise they are laid out vertically. For horizontal orientations, if the container's ComponentOrientation is left to right then components are laid out left to right, otherwise they are laid out right to left. For vertical orientations components are always laid out from top to bottom.
PAGE_AXIS - Components are laid out the way text lines are laid out on a page, based on the container's ComponentOrientation property. If the container's ComponentOrientation is horizontal then components are laid out vertically, otherwise they are laid out horizontally. For horizontal orientations, if the container's ComponentOrientation is left to right then components are laid out left to right, otherwise they are laid out right to left. For vertical orientations components are always laid out from top to bottom.

For all directions, components are arranged in the same order as they were added to the container.

BoxLayout attempts to arrange components at their preferred widths (for horizontal layout) or heights (for vertical layout). For a horizontal layout, if not all the components are the same height, BoxLayout attempts to make all the components as high as the highest component. If that's not possible for a particular component, then BoxLayout aligns that component vertically, according to the component's Y alignment. By default, a component has a Y alignment of 0.5, which means that the vertical center of the component should have the same Y coordinate as the vertical centers of other components with 0.5 Y alignment.

Similarly, for a vertical layout, BoxLayout attempts to make all components in the column as wide as the widest component. If that fails, it aligns them horizontally according to their X alignments. For PAGE_AXIS layout, horizontal alignment is done based on the leading edge of the component. In other words, an X alignment value of 0.0 means the left edge of a component if the container's ComponentOrientation is left to right and it means the right edge of the component otherwise.

Instead of using BoxLayout directly, many programs use the Box class. The Box class is a lightweight container that uses a BoxLayout. It also provides handy methods to help you use BoxLayout well. Adding components to multiple nested boxes is a powerful way to get the arrangement you want.

For further information and examples see How to Use BoxLayout, a section in The Java Tutorial.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
Box, ComponentOrientation, JComponent.getAlignmentX(), JComponent.getAlignmentY()

Field Summary
static int | LINE_AXIS Specifies that components should be laid out in the direction of a line of text as determined by the target container's ComponentOrientation property.
static int | PAGE_AXIS Specifies that components should be laid out in the direction that lines flow across a page as determined by the target container's ComponentOrientation property.
static int | X_AXIS Specifies that components should be laid out left to right.
static int | Y_AXIS Specifies that components should be laid out top to bottom.
Constructor Summary
BoxLayout(Container target, int axis)
Creates a layout manager that will lay out components along the given axis.
Method Summary
void | addLayoutComponent(Component comp, Object constraints) Not used by this class.
void | addLayoutComponent(String name, Component comp) Not used by this class.
int | getAxis() Returns the axis that was used to lay out components.
float | getLayoutAlignmentX(Container target) Returns the alignment along the X axis for the container.
float | getLayoutAlignmentY(Container target) Returns the alignment along the Y axis for the container.
Container | getTarget() Returns the container that uses this layout manager.
void | invalidateLayout(Container target) Indicates that a child has changed its layout related information, and thus any cached calculations should be flushed.
void | layoutContainer(Container target) Called by the AWT when the specified container needs to be laid out.
Dimension | maximumLayoutSize(Container target) Returns the maximum dimensions the target container can use to lay out the components it contains.
Dimension | minimumLayoutSize(Container target) Returns the minimum dimensions needed to lay out the components contained in the specified target container.
Dimension | preferredLayoutSize(Container target) Returns the preferred dimensions for this layout, given the components in the specified target container.
void | removeLayoutComponent(Component comp) Not used by this class.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

X_AXIS

public static final int X_AXIS
Specifies that components should be laid out left to right.

See Also:
Constant Field Values

Y_AXIS

public static final int Y_AXIS
Specifies that components should be laid out top to bottom.

See Also:
Constant Field Values

LINE_AXIS

public static final int LINE_AXIS
Specifies that components should be laid out in the direction of a line of text as determined by the target container's ComponentOrientation property.

See Also:
Constant Field Values

PAGE_AXIS

public static final int PAGE_AXIS
Specifies that components should be laid out in the direction that lines flow across a page as determined by the target container's ComponentOrientation property.

See Also:
Constant Field Values
Constructor Detail

BoxLayout

public BoxLayout(Container target,
                 int axis)
Creates a layout manager that will lay out components along the given axis.

Parameters:
target - the container that needs to be laid out
axis - the axis to lay out components along. Can be one of: BoxLayout.X_AXIS, BoxLayout.Y_AXIS, BoxLayout.LINE_AXIS or BoxLayout.PAGE_AXIS
Throws:
AWTError - if the value of axis is invalid
Method Detail

getTarget

public final Container getTarget()
Returns the container that uses this layout manager.

Returns:
the container that uses this layout manager
Since:
1.6

getAxis

public final int getAxis()
Returns the axis that was used to lay out components. Returns one of: BoxLayout.X_AXIS, BoxLayout.Y_AXIS, BoxLayout.LINE_AXIS or BoxLayout.PAGE_AXIS

Returns:
the axis that was used to lay out components
Since:
1.6

invalidateLayout

public void invalidateLayout(Container target)
Indicates that a child has changed its layout related information, and thus any cached calculations should be flushed.

This method is called by AWT when the invalidate method is called on the Container. Since the invalidate method may be called asynchronously to the event thread, this method may be called asynchronously.

Specified by:
invalidateLayout in interface LayoutManager2
Parameters:
target - the affected container
Throws:
AWTError - if the target isn't the container specified to the BoxLayout constructor

addLayoutComponent

public void addLayoutComponent(String name,
                               Component comp)
Not used by this class.

Specified by:
addLayoutComponent in interface LayoutManager
Parameters:
name - the name of the component
comp - the component

removeLayoutComponent

public void removeLayoutComponent(Component comp)
Not used by this class.

Specified by:
removeLayoutComponent in interface LayoutManager
Parameters:
comp - the component

addLayoutComponent

public void addLayoutComponent(Component comp,
                               Object constraints)
Not used by this class.

Specified by:
addLayoutComponent in interface LayoutManager2
Parameters:
comp - the component
constraints - constraints

preferredLayoutSize

public Dimension preferredLayoutSize(Container target)
Returns the preferred dimensions for this layout, given the components in the specified target container.

Specified by:
preferredLayoutSize in interface LayoutManager
Parameters:
target - the container that needs to be laid out
Returns:
the dimensions >= 0 && <= Integer.MAX_VALUE="Integer.MAX_VALUE" Throws:
AWTError - if the target isn't the container specified to the BoxLayout constructor
See Also:
Container, minimumLayoutSize(java.awt.Container), maximumLayoutSize(java.awt.Container)

minimumLayoutSize

public Dimension minimumLayoutSize(Container target)
Returns the minimum dimensions needed to lay out the components contained in the specified target container.

Specified by:
minimumLayoutSize in interface LayoutManager
Parameters:
target - the container that needs to be laid out
Returns:
the dimensions >= 0 && <= Integer.MAX_VALUE="Integer.MAX_VALUE" Throws:
AWTError - if the target isn't the container specified to the BoxLayout constructor
See Also:
preferredLayoutSize(java.awt.Container), maximumLayoutSize(java.awt.Container)

maximumLayoutSize

public Dimension maximumLayoutSize(Container target)
Returns the maximum dimensions the target container can use to lay out the components it contains.

Specified by:
maximumLayoutSize in interface LayoutManager2
Parameters:
target - the container that needs to be laid out
Returns:
the dimenions >= 0 && <= Integer.MAX_VALUE="Integer.MAX_VALUE" Throws:
AWTError - if the target isn't the container specified to the BoxLayout constructor
See Also:
preferredLayoutSize(java.awt.Container), minimumLayoutSize(java.awt.Container)

getLayoutAlignmentX

public float getLayoutAlignmentX(Container target)
Returns the alignment along the X axis for the container. If the box is horizontal, the default alignment will be returned. Otherwise, the alignment needed to place the children along the X axis will be returned.

Specified by:
getLayoutAlignmentX in interface LayoutManager2
Parameters:
target - the container
Returns:
the alignment >= 0.0f && <= 1.0f="1.0f" Throws:
AWTError - if the target isn't the container specified to the BoxLayout constructor

getLayoutAlignmentY

public float getLayoutAlignmentY(Container target)
Returns the alignment along the Y axis for the container. If the box is vertical, the default alignment will be returned. Otherwise, the alignment needed to place the children along the Y axis will be returned.

Specified by:
getLayoutAlignmentY in interface LayoutManager2
Parameters:
target - the container
Returns:
the alignment >= 0.0f && <= 1.0f="1.0f" Throws:
AWTError - if the target isn't the container specified to the BoxLayout constructor

layoutContainer

public void layoutContainer(Container target)
Called by the AWT when the specified container needs to be laid out.

Specified by:
layoutContainer in interface LayoutManager
Parameters:
target - the container to lay out
Throws:
AWTError - if the target isn't the container specified to the BoxLayout constructor
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ButtonGroup

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class ButtonGroup

java.lang.Object
    extended by  javax.swing.ButtonGroup
All Implemented Interfaces:
Serializable
public class ButtonGroup
extends Object
implements Serializable

This class is used to create a multiple-exclusion scope for a set of buttons. Creating a set of buttons with the same ButtonGroup object means that turning "on" one of those buttons turns off all other buttons in the group.

A ButtonGroup can be used with any set of objects that inherit from AbstractButton. Typically a button group contains instances of JRadioButton, JRadioButtonMenuItem, or JToggleButton. It wouldn't make sense to put an instance of JButton or JMenuItem in a button group because JButton and JMenuItem don't implement the selected state.

Initially, all buttons in the group are unselected.

For examples and further information on using button groups see How to Use Radio Buttons, a section in The Java Tutorial.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected  Vector<AbstractButton> buttons
Constructor Summary
ButtonGroup()
Creates a new ButtonGroup.
Method Summary
void | add(AbstractButton b) Adds the button to the group.
void | clearSelection() Clears the selection such that none of the buttons in the ButtonGroup are selected.
int | getButtonCount() Returns the number of buttons in the group.
Enumeration<AbstractButton> | getElements() Returns all the buttons that are participating in this group.
ButtonModel | getSelection() Returns the model of the selected button.
boolean | isSelected(ButtonModel m) Returns whether a ButtonModel is selected.
void | remove(AbstractButton b) Removes the button from the group.
void | setSelected(ButtonModel m, boolean b) Sets the selected value for the ButtonModel.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

buttons

protected Vector<AbstractButton> buttons
Constructor Detail

ButtonGroup

public ButtonGroup()
Creates a new ButtonGroup.

Method Detail

add

public void add(AbstractButton b)
Adds the button to the group.

Parameters:
b - the button to be added

remove

public void remove(AbstractButton b)
Removes the button from the group.

Parameters:
b - the button to be removed

clearSelection

public void clearSelection()
Clears the selection such that none of the buttons in the ButtonGroup are selected.

Since:
1.6

getElements

public Enumeration<AbstractButton> getElements()
Returns all the buttons that are participating in this group.

Returns:
an Enumeration of the buttons in this group

getSelection

public ButtonModel getSelection()
Returns the model of the selected button.

Returns:
the selected button model

setSelected

public void setSelected(ButtonModel m,
                        boolean b)
Sets the selected value for the ButtonModel. Only one button in the group may be selected at a time.

Parameters:
m - the ButtonModel
b - true if this button is to be selected, otherwise false

isSelected

public boolean isSelected(ButtonModel m)
Returns whether a ButtonModel is selected.

Returns:
true if the button is selected, otherwise returns false

getButtonCount

public int getButtonCount()
Returns the number of buttons in the group.

Returns:
the button count
Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ButtonModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface ButtonModel

All Superinterfaces:
ItemSelectable
All Known Implementing Classes:
DefaultButtonModel, JToggleButton.ToggleButtonModel
public interface ButtonModel
extends ItemSelectable

State model for buttons.

This model is used for regular buttons, as well as check boxes and radio buttons, which are special kinds of buttons. In practice, a button's UI takes the responsibility of calling methods on its model to manage the state, as detailed below:

In simple terms, pressing and releasing the mouse over a regular button triggers the button and causes and ActionEvent to be fired. The same behavior can be produced via a keyboard key defined by the look and feel of the button (typically the SPACE BAR). Pressing and releasing this key while the button has focus will give the same results. For check boxes and radio buttons, the mouse or keyboard equivalent sequence just described causes the button to become selected.

In details, the state model for buttons works as follows when used with the mouse:
Pressing the mouse on top of a button makes the model both armed and pressed. As long as the mouse remains down, the model remains pressed, even if the mouse moves outside the button. On the contrary, the model is only armed while the mouse remains pressed within the bounds of the button (it can move in or out of the button, but the model is only armed during the portion of time spent within the button). A button is triggered, and an ActionEvent is fired, when the mouse is released while the model is armed - meaning when it is released over top of the button after the mouse has previously been pressed on that button (and not already released). Upon mouse release, the model becomes unarmed and unpressed.

In details, the state model for buttons works as follows when used with the keyboard:
Pressing the look and feel defined keyboard key while the button has focus makes the model both armed and pressed. As long as this key remains down, the model remains in this state. Releasing the key sets the model to unarmed and unpressed, triggers the button, and causes an ActionEvent to be fired.

Method Summary
void | addActionListener(ActionListener l) Adds an ActionListener to the model.
void | addChangeListener(ChangeListener l) Adds a ChangeListener to the model.
void | addItemListener(ItemListener l) Adds an ItemListener to the model.
String | getActionCommand() Returns the action command string for the button.
int | getMnemonic() Gets the keyboard mnemonic for the button.
boolean | isArmed() Indicates partial commitment towards triggering the button.
boolean | isEnabled() Indicates if the button can be selected or triggered by an input device, such as a mouse pointer.
boolean | isPressed() Indicates if the button is pressed.
boolean | isRollover() Indicates that the mouse is over the button.
boolean | isSelected() Indicates if the button has been selected.
void | removeActionListener(ActionListener l) Removes an ActionListener from the model.
void | removeChangeListener(ChangeListener l) Removes a ChangeListener from the model.
void | removeItemListener(ItemListener l) Removes an ItemListener from the model.
void | setActionCommand(String s) Sets the action command string that gets sent as part of the ActionEvent when the button is triggered.
void | setArmed(boolean b) Marks the button as armed or unarmed.
void | setEnabled(boolean b) Enables or disables the button.
void | setGroup(ButtonGroup group) Identifies the group the button belongs to -- needed for radio buttons, which are mutually exclusive within their group.
void | setMnemonic(int key) Sets the keyboard mnemonic (shortcut key or accelerator key) for the button.
void | setPressed(boolean b) Sets the button to pressed or unpressed.
void | setRollover(boolean b) Sets or clears the button's rollover state
void | setSelected(boolean b) Selects or deselects the button.
Methods inherited from interface java.awt.ItemSelectable
getSelectedObjects

Method Detail

isArmed

boolean isArmed()
Indicates partial commitment towards triggering the button.

Returns:
true if the button is armed, and ready to be triggered
See Also:
setArmed(boolean)

isSelected

boolean isSelected()
Indicates if the button has been selected. Only needed for certain types of buttons - such as radio buttons and check boxes.

Returns:
true if the button is selected

isEnabled

boolean isEnabled()
Indicates if the button can be selected or triggered by an input device, such as a mouse pointer.

Returns:
true if the button is enabled

isPressed

boolean isPressed()
Indicates if the button is pressed.

Returns:
true if the button is pressed

isRollover

boolean isRollover()
Indicates that the mouse is over the button.

Returns:
true if the mouse is over the button

setArmed

void setArmed(boolean b)
Marks the button as armed or unarmed.

Parameters:
b - whether or not the button should be armed

setSelected

void setSelected(boolean b)
Selects or deselects the button.

Parameters:
b - true selects the button, false deselects the button

setEnabled

void setEnabled(boolean b)
Enables or disables the button.

Parameters:
b - whether or not the button should be enabled
See Also:
isEnabled()

setPressed

void setPressed(boolean b)
Sets the button to pressed or unpressed.

Parameters:
b - whether or not the button should be pressed
See Also:
isPressed()

setRollover

void setRollover(boolean b)
Sets or clears the button's rollover state

Parameters:
b - whether or not the button is in the rollover state
See Also:
isRollover()

setMnemonic

void setMnemonic(int key)
Sets the keyboard mnemonic (shortcut key or accelerator key) for the button.

Parameters:
key - an int specifying the accelerator key

getMnemonic

int getMnemonic()
Gets the keyboard mnemonic for the button.

Returns:
an int specifying the accelerator key
See Also:
setMnemonic(int)

setActionCommand

void setActionCommand(String s)
Sets the action command string that gets sent as part of the ActionEvent when the button is triggered.

Parameters:
s - the String that identifies the generated event
See Also:
getActionCommand(), ActionEvent.getActionCommand()

getActionCommand

String getActionCommand()
Returns the action command string for the button.

Returns:
the String that identifies the generated event
See Also:
setActionCommand(java.lang.String)

setGroup

void setGroup(ButtonGroup group)
Identifies the group the button belongs to -- needed for radio buttons, which are mutually exclusive within their group.

Parameters:
group - the ButtonGroup the button belongs to

addActionListener

void addActionListener(ActionListener l)
Adds an ActionListener to the model.

Parameters:
l - the listener to add

removeActionListener

void removeActionListener(ActionListener l)
Removes an ActionListener from the model.

Parameters:
l - the listener to remove

addItemListener

void addItemListener(ItemListener l)
Adds an ItemListener to the model.

Specified by:
addItemListener in interface ItemSelectable
Parameters:
l - the listener to add
See Also:
ItemEvent

removeItemListener

void removeItemListener(ItemListener l)
Removes an ItemListener from the model.

Specified by:
removeItemListener in interface ItemSelectable
Parameters:
l - the listener to remove
See Also:
ItemEvent

addChangeListener

void addChangeListener(ChangeListener l)
Adds a ChangeListener to the model.

Parameters:
l - the listener to add

removeChangeListener

void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the model.

Parameters:
l - the listener to remove
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CellEditor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface CellEditor

All Known Subinterfaces:
TableCellEditor, TreeCellEditor
All Known Implementing Classes:
AbstractCellEditor, DefaultCellEditor, DefaultTreeCellEditor
public interface CellEditor

This interface defines the methods any general editor should be able to implement.

Having this interface enables complex components (the client of the editor) such as JTree and JTable to allow any generic editor to edit values in a table cell, or tree cell, etc. Without this generic editor interface, JTable would have to know about specific editors, such as JTextField, JCheckBox, JComboBox, etc. In addition, without this interface, clients of editors such as JTable would not be able to work with any editors developed in the future by the user or a 3rd party ISV.

To use this interface, a developer creating a new editor can have the new component implement the interface. Or the developer can choose a wrapper based approach and provide a companion object which implements the CellEditor interface (See JCellEditor for example). The wrapper approach is particularly useful if the user want to use a 3rd party ISV editor with JTable, but the ISV didn't implement the CellEditor interface. The user can simply create an object that contains an instance of the 3rd party editor object and "translate" the CellEditor API into the 3rd party editor's API.

See Also:
CellEditorListener

Method Summary
void | addCellEditorListener(CellEditorListener l) Adds a listener to the list that's notified when the editor stops, or cancels editing.
void | cancelCellEditing() Tells the editor to cancel editing and not accept any partially edited value.
Object | getCellEditorValue() Returns the value contained in the editor.
boolean | isCellEditable(EventObject anEvent) Asks the editor if it can start editing using anEvent.
void | removeCellEditorListener(CellEditorListener l) Removes a listener from the list that's notified
boolean | shouldSelectCell(EventObject anEvent) Returns true if the editing cell should be selected, false otherwise.
boolean | stopCellEditing() Tells the editor to stop editing and accept any partially edited value as the value of the editor.

Method Detail

getCellEditorValue

Object getCellEditorValue()
Returns the value contained in the editor.

Returns:
the value contained in the editor

isCellEditable

boolean isCellEditable(EventObject anEvent)
Asks the editor if it can start editing using anEvent. anEvent is in the invoking component coordinate system. The editor can not assume the Component returned by getCellEditorComponent is installed. This method is intended for the use of client to avoid the cost of setting up and installing the editor component if editing is not possible. If editing can be started this method returns true.

Parameters:
anEvent - the event the editor should use to consider whether to begin editing or not
Returns:
true if editing can be started
See Also:
shouldSelectCell(java.util.EventObject)

shouldSelectCell

boolean shouldSelectCell(EventObject anEvent)
Returns true if the editing cell should be selected, false otherwise. Typically, the return value is true, because is most cases the editing cell should be selected. However, it is useful to return false to keep the selection from changing for some types of edits. eg. A table that contains a column of check boxes, the user might want to be able to change those checkboxes without altering the selection. (See Netscape Communicator for just such an example) Of course, it is up to the client of the editor to use the return value, but it doesn't need to if it doesn't want to.

Parameters:
anEvent - the event the editor should use to start editing
Returns:
true if the editor would like the editing cell to be selected; otherwise returns false
See Also:
isCellEditable(java.util.EventObject)

stopCellEditing

boolean stopCellEditing()
Tells the editor to stop editing and accept any partially edited value as the value of the editor. The editor returns false if editing was not stopped; this is useful for editors that validate and can not accept invalid entries.

Returns:
true if editing was stopped; false otherwise

cancelCellEditing

void cancelCellEditing()
Tells the editor to cancel editing and not accept any partially edited value.

addCellEditorListener

void addCellEditorListener(CellEditorListener l)
Adds a listener to the list that's notified when the editor stops, or cancels editing.

Parameters:
l - the CellEditorListener

removeCellEditorListener

void removeCellEditorListener(CellEditorListener l)
Removes a listener from the list that's notified

Parameters:
l - the CellEditorListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CellRendererPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class CellRendererPane

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.CellRendererPane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public class CellRendererPane
extends Container
implements Accessible

This class is inserted in between cell renderers and the components that use them. It just exists to thwart the repaint() and invalidate() methods which would otherwise propagate up the tree when the renderer was configured. It's used by the implementations of JTable, JTree, and JList. For example, here's how CellRendererPane is used in the code the paints each row in a JList:

   cellRendererPane = new CellRendererPane();
   ...
   Component rendererComponent = renderer.getListCellRendererComponent();
   renderer.configureListCellRenderer(dataModel.getElementAt(row), row);
   cellRendererPane.paintComponent(g, rendererComponent, this, x, y, w, h);

A renderer component must override isShowing() and unconditionally return true to work correctly because the Swing paint does nothing for components with isShowing false.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class CellRendererPane.AccessibleCellRendererPane
This class implements accessibility support for the CellRendererPane class.
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected  AccessibleContext accessibleContext
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
CellRendererPane()
Construct a CellRendererPane object.
Method Summary
protected  void addImpl(Component x, Object constraints, int index)
If the specified component is already a child of this then we don't bother doing anything - stacking order doesn't matter for cell renderer components (CellRendererPane doesn't paint anyway).<</TD>
 AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this CellRendererPane.
 void invalidate()
Overridden to avoid propagating a invalidate up the tree when the cell renderer child is configured.
 void paint(Graphics g)
Shouldn't be called.
 void paintComponent(Graphics g, Component c, Container p, int x, int y, int w, int h)
Calls this.paintComponent(g, c, p, x, y, w, h, false).
 void paintComponent(Graphics g, Component c, Container p, int x, int y, int w, int h, boolean shouldValidate)
Paint a cell renderer component c on graphics object g.
 void paintComponent(Graphics g, Component c, Container p, Rectangle r)
Calls this.paintComponent() with the rectangles x,y,width,height fields.
 void update(Graphics g)
Shouldn't be called.
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getInsets, getLayout, getListeners, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, insets, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, paramString, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, removeNotify, setComponentZOrder, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

accessibleContext

protected AccessibleContext accessibleContext
Constructor Detail

CellRendererPane

public CellRendererPane()
Construct a CellRendererPane object.

Method Detail

invalidate

public void invalidate()
Overridden to avoid propagating a invalidate up the tree when the cell renderer child is configured.

Overrides:
invalidate in class Container
See Also:
Container.validate(), Container.layout(), LayoutManager, LayoutManager2.invalidateLayout(Container)

paint

public void paint(Graphics g)
Shouldn't be called.

Overrides:
paint in class Container
Parameters:
g - the specified Graphics window
See Also:
Component.update(Graphics)

update

public void update(Graphics g)
Shouldn't be called.

Overrides:
update in class Container
Parameters:
g - the specified Graphics window
See Also:
Component.update(Graphics)

addImpl

protected void addImpl(Component x,
                       Object constraints,
                       int index)
If the specified component is already a child of this then we don't bother doing anything - stacking order doesn't matter for cell renderer components (CellRendererPane doesn't paint anyway).<

Overrides:
addImpl in class Container
Parameters:
x - the component to be added
constraints - an object expressing layout constraints for this component
index - the position in the container's list at which to insert the component, where -1 means append to the end
See Also:
Container.add(Component),
Container.add(Component, int),
Container.add(Component, java.lang.Object),
LayoutManager,
LayoutManager2

paintComponent

public void paintComponent(Graphics g,
                           Component c,
                           Container p,
                           int x,
                           int y,
                           int w,
                           int h,
                           boolean shouldValidate)
Paint a cell renderer component c on graphics object g. Before the component is drawn it's reparented to this (if that's necessary), it's bounds are set to w,h and the graphics object is (effectively) translated to x,y. If it's a JComponent, double buffering is temporarily turned off. After the component is painted it's bounds are reset to -w, -h, 0, 0 so that, if it's the last renderer component painted, it will not start consuming input. The Container p is the component we're actually drawing on, typically it's equal to this.getParent(). If shouldValidate is true the component c will be validated before painted.

paintComponent

public void paintComponent(Graphics g,
                           Component c,
                           Container p,
                           int x,
                           int y,
                           int w,
                           int h)
Calls this.paintComponent(g, c, p, x, y, w, h, false).

paintComponent

public void paintComponent(Graphics g,
                           Component c,
                           Container p,
                           Rectangle r)
Calls this.paintComponent() with the rectangles x,y,width,height fields.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this CellRendererPane. For CellRendererPanes, the AccessibleContext takes the form of an AccessibleCellRendererPane. A new AccessibleCellRendererPane instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class Component
Returns:
an AccessibleCellRendererPane that serves as the AccessibleContext of this CellRendererPane
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CellRendererPane.AccessibleCellRendererPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class CellRendererPane.AccessibleCellRendererPane

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.CellRendererPane.AccessibleCellRendererPane
All Implemented Interfaces:
Serializable, AccessibleComponent
Enclosing class:
CellRendererPane
protected class CellRendererPane.AccessibleCellRendererPane
extends Container.AccessibleAWTContainer

This class implements accessibility support for the CellRendererPane class.

Nested Class Summary
Nested classes/interfaces inherited from class java.awt.Container.AccessibleAWTContainer
Container.AccessibleAWTContainer.AccessibleContainerHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class java.awt.Container.AccessibleAWTContainer
accessibleContainerHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected CellRendererPane.AccessibleCellRendererPane()
Method Summary
 AccessibleRole getAccessibleRole()
Get the role of this object.
Methods inherited from class java.awt.Container.AccessibleAWTContainer
addPropertyChangeListener, getAccessibleAt, getAccessibleChild, getAccessibleChildrenCount
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleDescription, getAccessibleIndexInParent, getAccessibleName, getAccessibleParent, getAccessibleStateSet, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, removePropertyChangeListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CellRendererPane.AccessibleCellRendererPane

protected CellRendererPane.AccessibleCellRendererPane()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class Component.AccessibleAWTComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.swing.AbstractAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.AbstractAction

Packages that use AbstractAction
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of AbstractAction in javax.swing.plaf.basic

Subclasses of AbstractAction in javax.swing.plaf.basic
protected class | BasicDesktopPaneUI.CloseAction Handles closing an internal frame.
protected class | BasicDesktopPaneUI.MaximizeAction Handles maximizing an internal frame.
protected class | BasicDesktopPaneUI.MinimizeAction Handles minimizing an internal frame.
protected class | BasicDesktopPaneUI.NavigateAction Handles navigating to the next internal frame.
protected class | BasicDesktopPaneUI.OpenAction Handles restoring a minimized or maximized internal frame.
protected class | BasicFileChooserUI.ApproveSelectionAction Responds to an Open or Save request
protected class | BasicFileChooserUI.CancelSelectionAction Responds to a cancel request.
protected class | BasicFileChooserUI.ChangeToParentDirectoryAction
protected class | BasicFileChooserUI.GoHomeAction Acts on the "home" key event or equivalent event.
protected class | BasicFileChooserUI.NewFolderAction Creates a new folder.
protected class | BasicFileChooserUI.UpdateAction Rescans the files in the current directory
class | BasicInternalFrameTitlePane.CloseAction This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.IconifyAction This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.MaximizeAction This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.MoveAction This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.RestoreAction This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.SizeAction This class should be treated as a "protected" inner class.
class | BasicSliderUI.ActionScroller As of Java 2 platform v1.3 this undocumented class is no longer used.
class | BasicTreeUI.TreeCancelEditingAction ActionListener that invokes cancelEditing when action performed.
class | BasicTreeUI.TreeHomeAction TreeHomeAction is used to handle end/home actions.
class | BasicTreeUI.TreeIncrementAction TreeIncrementAction is used to handle up/down actions.
class | BasicTreeUI.TreePageAction TreePageAction handles page up and page down events.
class | BasicTreeUI.TreeToggleAction For the first selected row expandedness will be toggled.
class | BasicTreeUI.TreeTraverseAction TreeTraverseAction is the action used for left/right keys.

Uses of AbstractAction in javax.swing.plaf.metal

Subclasses of AbstractAction in javax.swing.plaf.metal
protected  class MetalFileChooserUI.DirectoryComboBoxAction
Acts when DirectoryComboBox has changed the selected item.

Uses of AbstractAction in javax.swing.text

Subclasses of AbstractAction in javax.swing.text
static class | DefaultEditorKit.BeepAction Creates a beep.
static class | DefaultEditorKit.CopyAction Copies the selected region and place its contents into the system clipboard.
static class | DefaultEditorKit.CutAction Cuts the selected region and place its contents into the system clipboard.
static class | DefaultEditorKit.DefaultKeyTypedAction The action that is executed by default if a key typed event is received and there is no keymap entry.
static class | DefaultEditorKit.InsertBreakAction Places a line/paragraph break into the document.
static class | DefaultEditorKit.InsertContentAction Places content into the associated document.
static class | DefaultEditorKit.InsertTabAction Places a tab character into the document.
static class | DefaultEditorKit.PasteAction Pastes the contents of the system clipboard into the selected region, or before the caret if nothing is selected.
static class | StyledEditorKit.AlignmentAction An action to set paragraph alignment.
static class | StyledEditorKit.BoldAction An action to toggle the bold attribute.
static class | StyledEditorKit.FontFamilyAction An action to set the font family in the associated JEditorPane.
static class | StyledEditorKit.FontSizeAction An action to set the font size in the associated JEditorPane.
static class | StyledEditorKit.ForegroundAction An action to set foreground color.
static class | StyledEditorKit.ItalicAction An action to toggle the italic attribute.
static class | StyledEditorKit.StyledTextAction An action that assumes it's being fired on a JEditorPane with a StyledEditorKit (or subclass) installed.
static class | StyledEditorKit.UnderlineAction An action to toggle the underline attribute.
class | TextAction An Action implementation useful for key bindings that are shared across a number of different text components.

Uses of AbstractAction in javax.swing.text.html

Subclasses of AbstractAction in javax.swing.text.html
static class | HTMLEditorKit.HTMLTextAction An abstract Action providing some convenience methods that may be useful in inserting HTML into an existing document.
static class | HTMLEditorKit.InsertHTMLTextAction InsertHTMLTextAction can be used to insert an arbitrary string of HTML into an existing HTML document.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.AbstractButton

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.AbstractButton

Packages that use AbstractButton
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of AbstractButton in javax.swing

Subclasses of AbstractButton in javax.swing
class | JButton An implementation of a "push" button.
class | JCheckBox An implementation of a check box -- an item that can be selected or deselected, and which displays its state to the user.
class | JCheckBoxMenuItem A menu item that can be selected or deselected.
class | JMenu An implementation of a menu -- a popup window containing JMenuItems that is displayed when the user selects an item on the JMenuBar.
class | JMenuItem An implementation of an item in a menu.
class | JRadioButton An implementation of a radio button -- an item that can be selected or deselected, and which displays its state to the user.
class | JRadioButtonMenuItem An implementation of a radio button menu item.
class | JToggleButton An implementation of a two-state button.

Fields in javax.swing with type parameters of type AbstractButton
protected  Vector<AbstractButton> ButtonGroup.buttons

Methods in javax.swing that return types with arguments of type AbstractButton
 Enumeration<AbstractButton> ButtonGroup.getElements()
Returns all the buttons that are participating in this group.

Methods in javax.swing with parameters of type AbstractButton
void | ButtonGroup.add(AbstractButton b) Adds the button to the group.
void | ButtonGroup.remove(AbstractButton b) Removes the button from the group.

Uses of AbstractButton in javax.swing.plaf.basic

Subclasses of AbstractButton in javax.swing.plaf.basic
 class BasicArrowButton
JButton object that draws a scaled Arrow in one of the cardinal directions.

Methods in javax.swing.plaf.basic with parameters of type AbstractButton
protected void | BasicButtonListener.checkOpacity(AbstractButton b)
protected BasicButtonListener | BasicButtonUI.createButtonListener(AbstractButton b)
int | BasicButtonUI.getDefaultTextIconGap(AbstractButton b)
protected Border | BasicToolBarUI.getNonRolloverBorder(AbstractButton b) Returns a non-rollover border for the button.
static Dimension | BasicGraphicsUtils.getPreferredButtonSize(AbstractButton b, int textIconGap)
protected Border | BasicToolBarUI.getRolloverBorder(AbstractButton b) Returns a rollover border for the button.
protected void | BasicRadioButtonUI.installDefaults(AbstractButton b)
protected void | BasicButtonUI.installDefaults(AbstractButton b)
protected void | BasicButtonUI.installKeyboardActions(AbstractButton b)
protected void | BasicButtonUI.installListeners(AbstractButton b)
protected void | BasicButtonUI.paintButtonPressed(Graphics g, AbstractButton b)
protected void | BasicButtonUI.paintFocus(Graphics g, AbstractButton b, Rectangle viewRect, Rectangle textRect, Rectangle iconRect)
protected void | BasicToggleButtonUI.paintIcon(Graphics g, AbstractButton b, Rectangle iconRect)
protected void | BasicButtonUI.paintText(Graphics g, AbstractButton b, Rectangle textRect, String text) Method which renders the text of the current button.
protected void | BasicRadioButtonUI.uninstallDefaults(AbstractButton b)
protected void | BasicButtonUI.uninstallDefaults(AbstractButton b)
protected void | BasicButtonUI.uninstallKeyboardActions(AbstractButton b)
protected void | BasicButtonUI.uninstallListeners(AbstractButton b)

Constructors in javax.swing.plaf.basic with parameters of type AbstractButton
BasicButtonListener(AbstractButton b)

Uses of AbstractButton in javax.swing.plaf.metal

Subclasses of AbstractButton in javax.swing.plaf.metal
class | MetalComboBoxButton JButton subclass to help out MetalComboBoxUI
class | MetalScrollButton JButton object for Metal scrollbar arrows.

Methods in javax.swing.plaf.metal with parameters of type AbstractButton
protected BasicButtonListener | MetalButtonUI.createButtonListener(AbstractButton b)
void | MetalRadioButtonUI.installDefaults(AbstractButton b)
void | MetalCheckBoxUI.installDefaults(AbstractButton b)
void | MetalToggleButtonUI.installDefaults(AbstractButton b)
void | MetalButtonUI.installDefaults(AbstractButton b)
protected void | MetalToggleButtonUI.paintButtonPressed(Graphics g, AbstractButton b)
protected void | MetalButtonUI.paintButtonPressed(Graphics g, AbstractButton b)
protected void | MetalToggleButtonUI.paintFocus(Graphics g, AbstractButton b, Rectangle viewRect, Rectangle textRect, Rectangle iconRect)
protected void | MetalButtonUI.paintFocus(Graphics g, AbstractButton b, Rectangle viewRect, Rectangle textRect, Rectangle iconRect)
protected void | MetalToggleButtonUI.paintIcon(Graphics g, AbstractButton b, Rectangle iconRect) Paints the appropriate icon of the button b in the space iconRect.
protected void | MetalRadioButtonUI.uninstallDefaults(AbstractButton b)
protected void | MetalCheckBoxUI.uninstallDefaults(AbstractButton b)
protected void | MetalToggleButtonUI.uninstallDefaults(AbstractButton b)
void | MetalButtonUI.uninstallDefaults(AbstractButton b)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.AbstractButton.AccessibleAbstractButton

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.AbstractButton.AccessibleAbstractButton

Packages that use AbstractButton.AccessibleAbstractButton
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of AbstractButton.AccessibleAbstractButton in javax.swing

Subclasses of AbstractButton.AccessibleAbstractButton in javax.swing
protected class | JButton.AccessibleJButton This class implements accessibility support for the JButton class.
protected class | JCheckBox.AccessibleJCheckBox This class implements accessibility support for the JCheckBox class.
protected class | JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem This class implements accessibility support for the JCheckBoxMenuItem class.
protected class | JMenu.AccessibleJMenu This class implements accessibility support for the JMenu class.
protected class | JMenuItem.AccessibleJMenuItem This class implements accessibility support for the JMenuItem class.
protected class | JRadioButton.AccessibleJRadioButton This class implements accessibility support for the JRadioButton class.
protected class | JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem This class implements accessibility support for the JRadioButtonMenuItem class.
protected class | JToggleButton.AccessibleJToggleButton This class implements accessibility support for the JToggleButton class.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.AbstractButton.ButtonChangeListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.AbstractButton.ButtonChangeListener

No usage of javax.swing.AbstractButton.ButtonChangeListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.AbstractCellEditor

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.AbstractCellEditor

Packages that use AbstractCellEditor
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of AbstractCellEditor in javax.swing

Subclasses of AbstractCellEditor in javax.swing
 class DefaultCellEditor
The default editor for table and tree cells.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.AbstractListModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.AbstractListModel

Packages that use AbstractListModel
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of AbstractListModel in javax.swing

Subclasses of AbstractListModel in javax.swing
class | DefaultComboBoxModel The default model for combo boxes.
class | DefaultListModel This class loosely implements the java.util.Vector API, in that it implements the 1.1.x version of java.util.Vector, has no collection class support, and notifies the ListDataListeners when changes occur.

Uses of AbstractListModel in javax.swing.plaf.basic

Subclasses of AbstractListModel in javax.swing.plaf.basic
 class BasicDirectoryModel
Basic implementation of a file list.

Uses of AbstractListModel in javax.swing.plaf.metal

Subclasses of AbstractListModel in javax.swing.plaf.metal
protected class | MetalFileChooserUI.DirectoryComboBoxModel Data model for a type-face selection combo-box.
protected class | MetalFileChooserUI.FilterComboBoxModel Data model for a type-face selection combo-box.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.AbstractSpinnerModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.AbstractSpinnerModel

Packages that use AbstractSpinnerModel
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of AbstractSpinnerModel in javax.swing

Subclasses of AbstractSpinnerModel in javax.swing
class | SpinnerDateModel A SpinnerModel for sequences of Dates.
class | SpinnerListModel A simple implementation of SpinnerModel whose values are defined by an array or a List.
class | SpinnerNumberModel A SpinnerModel for sequences of numbers.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.ActionMap

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.ActionMap

Packages that use ActionMap
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of ActionMap in javax.swing

Methods in javax.swing that return ActionMap
ActionMap | JComponent.getActionMap() Returns the ActionMap used to determine what Action to fire for particular KeyStroke binding.
ActionMap | ActionMap.getParent() Returns this ActionMap's parent.
static ActionMap | SwingUtilities.getUIActionMap(JComponent component) Returns the ActionMap provided by the UI in component component.

Methods in javax.swing with parameters of type ActionMap
static void | SwingUtilities.replaceUIActionMap(JComponent component, ActionMap uiActionMap) Convenience method to change the UI ActionMap for component to uiActionMap.
void | JComponent.setActionMap(ActionMap am) Sets the ActionMap to am.
void | ActionMap.setParent(ActionMap map) Sets this ActionMap's parent.

Uses of ActionMap in javax.swing.plaf

Subclasses of ActionMap in javax.swing.plaf
 class ActionMapUIResource
A subclass of javax.swing.ActionMap that implements UIResource.

Uses of ActionMap in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic that return ActionMap
protected  ActionMap BasicLookAndFeel.getAudioActionMap()
Returns an ActionMap containing the audio actions for this look and feel.

Uses of ActionMap in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal that return ActionMap
protected ActionMap | MetalFileChooserUI.createActionMap()
protected ActionMap | MetalFileChooserUI.getActionMap()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.BorderFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.BorderFactory

No usage of javax.swing.BorderFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.Box

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.Box

Packages that use Box
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of Box in javax.swing

Methods in javax.swing that return Box
static Box | Box.createHorizontalBox() Creates a Box that displays its components from left to right.
static Box | Box.createVerticalBox() Creates a Box that displays its components from top to bottom.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.Box.AccessibleBox

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.Box.AccessibleBox

No usage of javax.swing.Box.AccessibleBox

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.Box.Filler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.Box.Filler

No usage of javax.swing.Box.Filler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.Box.Filler.AccessibleBoxFiller

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.Box.Filler.AccessibleBoxFiller

No usage of javax.swing.Box.Filler.AccessibleBoxFiller

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.BoxLayout

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.BoxLayout

Packages that use BoxLayout
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of BoxLayout in javax.swing.plaf.basic

Subclasses of BoxLayout in javax.swing.plaf.basic
 class DefaultMenuLayout
The default layout manager for Popup menus and menubars.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.ButtonGroup

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.ButtonGroup

Packages that use ButtonGroup
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of ButtonGroup in javax.swing

Fields in javax.swing declared as ButtonGroup
protected  ButtonGroup DefaultButtonModel.group
The button group that the button belongs to.

Methods in javax.swing that return ButtonGroup
 ButtonGroup DefaultButtonModel.getGroup()
Returns the group that the button belongs to.

Methods in javax.swing with parameters of type ButtonGroup
void | DefaultButtonModel.setGroup(ButtonGroup group) Identifies the group the button belongs to -- needed for radio buttons, which are mutually exclusive within their group.
void | ButtonModel.setGroup(ButtonGroup group) Identifies the group the button belongs to -- needed for radio buttons, which are mutually exclusive within their group.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.CellRendererPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.CellRendererPane

Packages that use CellRendererPane
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of CellRendererPane in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as CellRendererPane
protected CellRendererPane | BasicComboBoxUI.currentValuePane
protected CellRendererPane | BasicTableHeaderUI.rendererPane
protected CellRendererPane | BasicTableUI.rendererPane
protected CellRendererPane | BasicListUI.rendererPane
protected CellRendererPane | BasicTreeUI.rendererPane Used to paint the TreeCellRenderer.

Methods in javax.swing.plaf.basic that return CellRendererPane
protected  CellRendererPane BasicTreeUI.createCellRendererPane()
Returns the renderer pane that renderer components are placed in.

Uses of CellRendererPane in javax.swing.plaf.metal

Fields in javax.swing.plaf.metal declared as CellRendererPane
protected  CellRendererPane MetalComboBoxButton.rendererPane

Constructors in javax.swing.plaf.metal with parameters of type CellRendererPane
MetalComboBoxButton(JComboBox cb, Icon i, boolean onlyIcon, CellRendererPane pane, JList list)
MetalComboBoxButton(JComboBox cb, Icon i, CellRendererPane pane, JList list)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.CellRendererPane.AccessibleCellRendererPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.CellRendererPane.AccessibleCellRendererPane

No usage of javax.swing.CellRendererPane.AccessibleCellRendererPane

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.ComponentInputMap

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.ComponentInputMap

Packages that use ComponentInputMap
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.

Uses of ComponentInputMap in javax.swing

Methods in javax.swing that return ComponentInputMap
static ComponentInputMap LookAndFeel.makeComponentInputMap(JComponent c, Object[] keys)
Creates a ComponentInputMapUIResource from keys.

Uses of ComponentInputMap in javax.swing.plaf

Subclasses of ComponentInputMap in javax.swing.plaf
 class ComponentInputMapUIResource
A subclass of javax.swing.ComponentInputMap that implements UIResource.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.DebugGraphics

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.DebugGraphics

No usage of javax.swing.DebugGraphics

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.DefaultBoundedRangeModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.DefaultBoundedRangeModel

No usage of javax.swing.DefaultBoundedRangeModel

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.DefaultButtonModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.DefaultButtonModel

Packages that use DefaultButtonModel
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of DefaultButtonModel in javax.swing

Subclasses of DefaultButtonModel in javax.swing
static class JToggleButton.ToggleButtonModel
The ToggleButton model

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.DefaultCellEditor

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.DefaultCellEditor

No usage of javax.swing.DefaultCellEditor

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.DefaultCellEditor.EditorDelegate

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.DefaultCellEditor.EditorDelegate

Packages that use DefaultCellEditor.EditorDelegate
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of DefaultCellEditor.EditorDelegate in javax.swing

Fields in javax.swing declared as DefaultCellEditor.EditorDelegate
protected  DefaultCellEditor.EditorDelegate DefaultCellEditor.delegate
The delegate class which handles all methods sent from the CellEditor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.DefaultComboBoxModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.DefaultComboBoxModel

No usage of javax.swing.DefaultComboBoxModel

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.DefaultDesktopManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.DefaultDesktopManager

No usage of javax.swing.DefaultDesktopManager

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.DefaultFocusManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.DefaultFocusManager

No usage of javax.swing.DefaultFocusManager

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.DefaultListCellRenderer

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.DefaultListCellRenderer

Packages that use DefaultListCellRenderer
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of DefaultListCellRenderer in javax.swing

Subclasses of DefaultListCellRenderer in javax.swing
static class DefaultListCellRenderer.UIResource
A subclass of DefaultListCellRenderer that implements UIResource.

Uses of DefaultListCellRenderer in javax.swing.plaf.metal

Subclasses of DefaultListCellRenderer in javax.swing.plaf.metal
protected class | MetalFileChooserUI.FileRenderer
class | MetalFileChooserUI.FilterComboBoxRenderer Render different type sizes and styles.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.DefaultListCellRenderer.UIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.DefaultListCellRenderer.UIResource

No usage of javax.swing.DefaultListCellRenderer.UIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.DefaultListModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.DefaultListModel

No usage of javax.swing.DefaultListModel

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.DefaultListSelectionModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.DefaultListSelectionModel

Packages that use DefaultListSelectionModel
javax.swing.tree Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of DefaultListSelectionModel in javax.swing.tree

Fields in javax.swing.tree declared as DefaultListSelectionModel
protected  DefaultListSelectionModel DefaultTreeSelectionModel.listSelectionModel
Handles maintaining the list selection model.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.DefaultRowSorter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.DefaultRowSorter

Packages that use DefaultRowSorter
javax.swing.table Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of DefaultRowSorter in javax.swing.table

Subclasses of DefaultRowSorter in javax.swing.table
 class TableRowSorter<M extends TableModel>
An implementation of RowSorter that provides sorting and filtering using a TableModel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.DefaultRowSorter.ModelWrapper

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.DefaultRowSorter.ModelWrapper

Packages that use DefaultRowSorter.ModelWrapper
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of DefaultRowSorter.ModelWrapper in javax.swing

Methods in javax.swing that return DefaultRowSorter.ModelWrapper
protected  DefaultRowSorter.ModelWrapper<M,I> DefaultRowSorter.getModelWrapper()
Returns the model wrapper providing the data that is being sorted and filtered.

Methods in javax.swing with parameters of type DefaultRowSorter.ModelWrapper
protected  void DefaultRowSorter.setModelWrapper(DefaultRowSorter.ModelWrapper<M,I> modelWrapper)
Sets the model wrapper providing the data that is being sorted and filtered.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.DefaultSingleSelectionModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.DefaultSingleSelectionModel

No usage of javax.swing.DefaultSingleSelectionModel

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.DropMode

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.DropMode

Packages that use DropMode
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of DropMode in javax.swing

Methods in javax.swing that return DropMode
DropMode | JTree.getDropMode() Returns the drop mode for this component.
DropMode | JTable.getDropMode() Returns the drop mode for this component.
DropMode | JList.getDropMode() Returns the drop mode for this component.
static DropMode | DropMode.valueOf(String name) Returns the enum constant of this type with the specified name.
static DropMode[] | DropMode.values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods in javax.swing with parameters of type DropMode
void | JTree.setDropMode(DropMode dropMode) Sets the drop mode for this component.
void | JTable.setDropMode(DropMode dropMode) Sets the drop mode for this component.
void | JList.setDropMode(DropMode dropMode) Sets the drop mode for this component.

Uses of DropMode in javax.swing.text

Methods in javax.swing.text that return DropMode
 DropMode JTextComponent.getDropMode()
Returns the drop mode for this component.

Methods in javax.swing.text with parameters of type DropMode
 void JTextComponent.setDropMode(DropMode dropMode)
Sets the drop mode for this component.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.FocusManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.FocusManager

Packages that use FocusManager
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of FocusManager in javax.swing

Subclasses of FocusManager in javax.swing
 class DefaultFocusManager
This class has been obsoleted by the 1.4 focus APIs.

Methods in javax.swing that return FocusManager
static FocusManager FocusManager.getCurrentManager()
Returns the current KeyboardFocusManager instance for the calling thread's context.

Methods in javax.swing with parameters of type FocusManager
static void FocusManager.setCurrentManager(FocusManager aFocusManager)
Sets the current KeyboardFocusManager instance for the calling thread's context.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.GrayFilter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.GrayFilter

No usage of javax.swing.GrayFilter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.GroupLayout

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.GroupLayout

No usage of javax.swing.GroupLayout

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.GroupLayout.Alignment

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.GroupLayout.Alignment

Packages that use GroupLayout.Alignment
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of GroupLayout.Alignment in javax.swing

Methods in javax.swing that return GroupLayout.Alignment
static GroupLayout.Alignment | GroupLayout.Alignment.valueOf(String name) Returns the enum constant of this type with the specified name.
static GroupLayout.Alignment[] | GroupLayout.Alignment.values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods in javax.swing with parameters of type GroupLayout.Alignment
GroupLayout.ParallelGroup | GroupLayout.ParallelGroup.addComponent(Component component, GroupLayout.Alignment alignment) Adds a Component to this ParallelGroup with the specified alignment.
GroupLayout.ParallelGroup | GroupLayout.ParallelGroup.addComponent(Component component, GroupLayout.Alignment alignment, int min, int pref, int max) Adds a Component to this ParallelGroup with the specified alignment and size.
GroupLayout.ParallelGroup | GroupLayout.ParallelGroup.addGroup(GroupLayout.Alignment alignment, GroupLayout.Group group) Adds a Group to this ParallelGroup with the specified alignment.
GroupLayout.ParallelGroup | GroupLayout.createParallelGroup(GroupLayout.Alignment alignment) Creates and returns a ParallelGroup with the specified alignment.
GroupLayout.ParallelGroup | GroupLayout.createParallelGroup(GroupLayout.Alignment alignment, boolean resizable) Creates and returns a ParallelGroup with the specified alignment and resize behavior.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.GroupLayout.Group

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.GroupLayout.Group

Packages that use GroupLayout.Group
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of GroupLayout.Group in javax.swing

Subclasses of GroupLayout.Group in javax.swing
class | GroupLayout.ParallelGroup A Group that aligns and sizes it's children.
class | GroupLayout.SequentialGroup A Group that positions and sizes its elements sequentially, one after another.

Methods in javax.swing that return GroupLayout.Group
GroupLayout.Group | GroupLayout.Group.addComponent(Component component) Adds a Component to this Group.
GroupLayout.Group | GroupLayout.Group.addComponent(Component component, int min, int pref, int max) Adds a Component to this Group with the specified size.
GroupLayout.Group | GroupLayout.Group.addGap(int size) Adds a rigid gap to this Group.
GroupLayout.Group | GroupLayout.Group.addGap(int min, int pref, int max) Adds a gap to this Group with the specified size.
GroupLayout.Group | GroupLayout.Group.addGroup(GroupLayout.Group group) Adds a Group to this Group.

Methods in javax.swing with parameters of type GroupLayout.Group
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addGroup(boolean useAsBaseline, GroupLayout.Group group) Adds a Group to this Group.
GroupLayout.ParallelGroup | GroupLayout.ParallelGroup.addGroup(GroupLayout.Alignment alignment, GroupLayout.Group group) Adds a Group to this ParallelGroup with the specified alignment.
GroupLayout.Group | GroupLayout.Group.addGroup(GroupLayout.Group group) Adds a Group to this Group.
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addGroup(GroupLayout.Group group) Adds a Group to this Group.
GroupLayout.ParallelGroup | GroupLayout.ParallelGroup.addGroup(GroupLayout.Group group) Adds a Group to this Group.
void | GroupLayout.setHorizontalGroup(GroupLayout.Group group) Sets the Group that positions and sizes components along the horizontal axis.
void | GroupLayout.setVerticalGroup(GroupLayout.Group group) Sets the Group that positions and sizes components along the vertical axis.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.GroupLayout.ParallelGroup

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.GroupLayout.ParallelGroup

Packages that use GroupLayout.ParallelGroup
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of GroupLayout.ParallelGroup in javax.swing

Methods in javax.swing that return GroupLayout.ParallelGroup
GroupLayout.ParallelGroup | GroupLayout.ParallelGroup.addComponent(Component component) Adds a Component to this Group.
GroupLayout.ParallelGroup | GroupLayout.ParallelGroup.addComponent(Component component, GroupLayout.Alignment alignment) Adds a Component to this ParallelGroup with the specified alignment.
GroupLayout.ParallelGroup | GroupLayout.ParallelGroup.addComponent(Component component, GroupLayout.Alignment alignment, int min, int pref, int max) Adds a Component to this ParallelGroup with the specified alignment and size.
GroupLayout.ParallelGroup | GroupLayout.ParallelGroup.addComponent(Component component, int min, int pref, int max) Adds a Component to this Group with the specified size.
GroupLayout.ParallelGroup | GroupLayout.ParallelGroup.addGap(int pref) Adds a rigid gap to this Group.
GroupLayout.ParallelGroup | GroupLayout.ParallelGroup.addGap(int min, int pref, int max) Adds a gap to this Group with the specified size.
GroupLayout.ParallelGroup | GroupLayout.ParallelGroup.addGroup(GroupLayout.Alignment alignment, GroupLayout.Group group) Adds a Group to this ParallelGroup with the specified alignment.
GroupLayout.ParallelGroup | GroupLayout.ParallelGroup.addGroup(GroupLayout.Group group) Adds a Group to this Group.
GroupLayout.ParallelGroup | GroupLayout.createBaselineGroup(boolean resizable, boolean anchorBaselineToTop) Creates and returns a ParallelGroup that aligns it's elements along the baseline.
GroupLayout.ParallelGroup | GroupLayout.createParallelGroup() Creates and returns a ParallelGroup with an alignment of Alignment.LEADING.
GroupLayout.ParallelGroup | GroupLayout.createParallelGroup(GroupLayout.Alignment alignment) Creates and returns a ParallelGroup with the specified alignment.
GroupLayout.ParallelGroup | GroupLayout.createParallelGroup(GroupLayout.Alignment alignment, boolean resizable) Creates and returns a ParallelGroup with the specified alignment and resize behavior.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.GroupLayout.SequentialGroup

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.GroupLayout.SequentialGroup

Packages that use GroupLayout.SequentialGroup
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of GroupLayout.SequentialGroup in javax.swing

Methods in javax.swing that return GroupLayout.SequentialGroup
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addComponent(boolean useAsBaseline, Component component) Adds a Component to this Group.
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addComponent(boolean useAsBaseline, Component component, int min, int pref, int max) Adds a Component to this Group with the specified size.
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addComponent(Component component) Adds a Component to this Group.
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addComponent(Component component, int min, int pref, int max) Adds a Component to this Group with the specified size.
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addContainerGap() Adds an element representing the preferred gap between an edge the container and components that touch the border of the container.
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addContainerGap(int pref, int max) Adds an element representing the preferred gap between one edge of the container and the next or previous Component with the specified size.
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addGap(int size) Adds a rigid gap to this Group.
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addGap(int min, int pref, int max) Adds a gap to this Group with the specified size.
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addGroup(boolean useAsBaseline, GroupLayout.Group group) Adds a Group to this Group.
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addGroup(GroupLayout.Group group) Adds a Group to this Group.
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addPreferredGap(JComponent comp1, JComponent comp2, LayoutStyle.ComponentPlacement type) Adds an element representing the preferred gap between two components.
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addPreferredGap(JComponent comp1, JComponent comp2, LayoutStyle.ComponentPlacement type, int pref, int max) Adds an element representing the preferred gap between two components.
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addPreferredGap(LayoutStyle.ComponentPlacement type) Adds an element representing the preferred gap between the nearest components.
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addPreferredGap(LayoutStyle.ComponentPlacement type, int pref, int max) Adds an element representing the preferred gap between the nearest components.
GroupLayout.SequentialGroup | GroupLayout.createSequentialGroup() Creates and returns a SequentialGroup.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.ImageIcon

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.ImageIcon

No usage of javax.swing.ImageIcon

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.ImageIcon.AccessibleImageIcon

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.ImageIcon.AccessibleImageIcon

No usage of javax.swing.ImageIcon.AccessibleImageIcon

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.InputMap

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.InputMap

Packages that use InputMap
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.

Uses of InputMap in javax.swing

Subclasses of InputMap in javax.swing
 class ComponentInputMap
A ComponentInputMap is an InputMap associated with a particular JComponent.

Methods in javax.swing that return InputMap
InputMap | JComponent.getInputMap() Returns the InputMap that is used when the component has focus.
InputMap | JComponent.getInputMap(int condition) Returns the InputMap that is used during condition.
InputMap | InputMap.getParent() Gets this InputMap's parent.
static InputMap | SwingUtilities.getUIInputMap(JComponent component, int condition) Returns the InputMap provided by the UI for condition condition in component component.
static InputMap | LookAndFeel.makeInputMap(Object[] keys) Creates a InputMapUIResource from keys.

Methods in javax.swing with parameters of type InputMap
static void | LookAndFeel.loadKeyBindings(InputMap retMap, Object[] keys) Populates an InputMap with the specified bindings.
static void | SwingUtilities.replaceUIInputMap(JComponent component, int type, InputMap uiInputMap) Convenience method to change the UI InputMap for component to uiInputMap.
void | JComponent.setInputMap(int condition, InputMap map) Sets the InputMap to use under the condition condition to map.
void | ComponentInputMap.setParent(InputMap map) Sets the parent, which must be a ComponentInputMap associated with the same component as this ComponentInputMap.
void | InputMap.setParent(InputMap map) Sets this InputMap's parent.

Uses of InputMap in javax.swing.plaf

Subclasses of InputMap in javax.swing.plaf
class | ComponentInputMapUIResource A subclass of javax.swing.ComponentInputMap that implements UIResource.
class | InputMapUIResource A subclass of javax.swing.InputMap that implements UIResource.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.InputVerifier

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.InputVerifier

Packages that use InputVerifier
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of InputVerifier in javax.swing

Methods in javax.swing that return InputVerifier
 InputVerifier JComponent.getInputVerifier()
Returns the input verifier for this component.

Methods in javax.swing with parameters of type InputVerifier
 void JComponent.setInputVerifier(InputVerifier inputVerifier)
Sets the input verifier for this component.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.InternalFrameFocusTraversalPolicy

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.InternalFrameFocusTraversalPolicy

Packages that use InternalFrameFocusTraversalPolicy
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of InternalFrameFocusTraversalPolicy in javax.swing

Subclasses of InternalFrameFocusTraversalPolicy in javax.swing
class | LayoutFocusTraversalPolicy A SortingFocusTraversalPolicy which sorts Components based on their size, position, and orientation.
class | SortingFocusTraversalPolicy A FocusTraversalPolicy that determines traversal order by sorting the Components of a focus traversal cycle based on a given Comparator.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JApplet

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JApplet

No usage of javax.swing.JApplet

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JApplet.AccessibleJApplet

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JApplet.AccessibleJApplet

No usage of javax.swing.JApplet.AccessibleJApplet

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JButton

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JButton

Packages that use JButton
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of JButton in javax.swing

Fields in javax.swing declared as JButton
protected  JButton JRootPane.defaultButton
The button that gets activated when the pane has the focus and a UI-specific action like pressing the Enter key occurs.

Methods in javax.swing that return JButton
JButton | JToolBar.add(Action a) Adds a new JButton which dispatches the action.
protected JButton | JToolBar.createActionComponent(Action a) Factory method which creates the JButton for Actions added to the JToolBar.
JButton | JRootPane.getDefaultButton() Returns the value of the defaultButton property.

Methods in javax.swing with parameters of type JButton
protected PropertyChangeListener | JToolBar.createActionChangeListener(JButton b) Returns a properly configured PropertyChangeListener which updates the control as changes to the Action occur, or null if the default property change listener for the control is desired.
void | JRootPane.setDefaultButton(JButton defaultButton) Sets the defaultButton property, which determines the current default button for this JRootPane.

Uses of JButton in javax.swing.plaf.basic

Subclasses of JButton in javax.swing.plaf.basic
 class BasicArrowButton
JButton object that draws a scaled Arrow in one of the cardinal directions.

Fields in javax.swing.plaf.basic declared as JButton
protected JButton | BasicComboBoxUI.arrowButton
protected JButton | BasicInternalFrameTitlePane.closeButton
protected JButton | BasicScrollBarUI.decrButton
protected JButton | BasicInternalFrameTitlePane.iconButton
protected JButton | BasicScrollBarUI.incrButton
protected JButton | BasicSplitPaneDivider.leftButton Button for quickly toggling the left component.
protected JButton | BasicInternalFrameTitlePane.maxButton
protected JButton | BasicSplitPaneDivider.rightButton Button for quickly toggling the right component.

Methods in javax.swing.plaf.basic that return JButton
protected JButton | BasicComboBoxUI.createArrowButton() Creates an button which will be used as the control to show or hide the popup portion of the combo box.
protected JButton | BasicScrollBarUI.createDecreaseButton(int orientation)
protected JButton | BasicScrollBarUI.createIncreaseButton(int orientation)
protected JButton | BasicSplitPaneDivider.createLeftOneTouchButton() Creates and return an instance of JButton that can be used to collapse the left component in the split pane.
protected JButton | BasicSplitPaneDivider.createRightOneTouchButton() Creates and return an instance of JButton that can be used to collapse the right component in the split pane.
protected JButton | BasicTabbedPaneUI.createScrollButton(int direction) Creates and returns a JButton that will provide the user with a way to scroll the tabs in a particular direction.
protected JButton | BasicFileChooserUI.getApproveButton(JFileChooser fc)

Uses of JButton in javax.swing.plaf.metal

Subclasses of JButton in javax.swing.plaf.metal
class | MetalComboBoxButton JButton subclass to help out MetalComboBoxUI
class | MetalScrollButton JButton object for Metal scrollbar arrows.

Methods in javax.swing.plaf.metal that return JButton
protected JButton | MetalComboBoxUI.createArrowButton()
protected JButton | MetalScrollBarUI.createDecreaseButton(int orientation) Returns the view that represents the decrease view.
protected JButton | MetalScrollBarUI.createIncreaseButton(int orientation) Returns the view that represents the increase view.
protected JButton | MetalFileChooserUI.getApproveButton(JFileChooser fc)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JButton.AccessibleJButton

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JButton.AccessibleJButton

No usage of javax.swing.JButton.AccessibleJButton

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JCheckBox

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JCheckBox

Packages that use JCheckBox
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JCheckBox in javax.swing

Constructors in javax.swing with parameters of type JCheckBox
DefaultCellEditor(JCheckBox checkBox)
Constructs a DefaultCellEditor object that uses a check box.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JCheckBox.AccessibleJCheckBox

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JCheckBox.AccessibleJCheckBox

No usage of javax.swing.JCheckBox.AccessibleJCheckBox

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JCheckBoxMenuItem

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JCheckBoxMenuItem

No usage of javax.swing.JCheckBoxMenuItem

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem

No usage of javax.swing.JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JColorChooser

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JColorChooser

Packages that use JColorChooser
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.colorchooser | Contains classes and interfaces used by the JColorChooser component.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of JColorChooser in javax.swing

Methods in javax.swing with parameters of type JColorChooser
static JDialog JColorChooser.createDialog(Component c, String title, boolean modal, JColorChooser chooserPane, ActionListener okListener, ActionListener cancelListener)
Creates and returns a new dialog containing the specified ColorChooser pane along with "OK", "Cancel", and "Reset" buttons.

Uses of JColorChooser in javax.swing.colorchooser

Methods in javax.swing.colorchooser with parameters of type JColorChooser
void | AbstractColorChooserPanel.installChooserPanel(JColorChooser enclosingChooser) Invoked when the panel is added to the chooser.
void | AbstractColorChooserPanel.uninstallChooserPanel(JColorChooser enclosingChooser) Invoked when the panel is removed from the chooser.

Uses of JColorChooser in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JColorChooser
protected  JColorChooser BasicColorChooserUI.chooser
JColorChooser this BasicColorChooserUI is installed on.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JColorChooser.AccessibleJColorChooser

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JColorChooser.AccessibleJColorChooser

No usage of javax.swing.JColorChooser.AccessibleJColorChooser

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JComboBox

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JComboBox

Packages that use JComboBox
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of JComboBox in javax.swing

Constructors in javax.swing with parameters of type JComboBox
DefaultCellEditor(JComboBox comboBox)
Constructs a DefaultCellEditor object that uses a combo box.

Uses of JComboBox in javax.swing.plaf

Methods in javax.swing.plaf with parameters of type JComboBox
abstract boolean | ComboBoxUI.isFocusTraversable(JComboBox c) Determine whether or not the combo box itself is traversable
abstract boolean | ComboBoxUI.isPopupVisible(JComboBox c) Determine the visibility of the popup
abstract void | ComboBoxUI.setPopupVisible(JComboBox c, boolean v) Set the visiblity of the popup

Uses of JComboBox in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JComboBox
protected JComboBox | BasicComboBoxUI.comboBox
protected JComboBox | BasicComboPopup.comboBox

Methods in javax.swing.plaf.basic with parameters of type JComboBox
boolean | BasicComboBoxUI.isFocusTraversable(JComboBox c) Determines if the JComboBox is focus traversable.
boolean | BasicComboBoxUI.isPopupVisible(JComboBox c) Tells if the popup is visible or not.
void | BasicComboBoxUI.setPopupVisible(JComboBox c, boolean v) Hides the popup.

Constructors in javax.swing.plaf.basic with parameters of type JComboBox
BasicComboPopup(JComboBox combo)

Uses of JComboBox in javax.swing.plaf.metal

Fields in javax.swing.plaf.metal declared as JComboBox
protected  JComboBox MetalComboBoxButton.comboBox

Methods in javax.swing.plaf.metal that return JComboBox
 JComboBox MetalComboBoxButton.getComboBox()

Methods in javax.swing.plaf.metal with parameters of type JComboBox
 void MetalComboBoxButton.setComboBox(JComboBox cb)

Constructors in javax.swing.plaf.metal with parameters of type JComboBox
MetalComboBoxButton(JComboBox cb, Icon i, boolean onlyIcon, CellRendererPane pane, JList list)
MetalComboBoxButton(JComboBox cb, Icon i, CellRendererPane pane, JList list)
MetalComboBoxUI.MetalComboPopup(JComboBox cBox)
Deprecated.

Uses of JComboBox in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi with parameters of type JComboBox
boolean | MultiComboBoxUI.isFocusTraversable(JComboBox a) Invokes the isFocusTraversable method on each UI handled by this object.
boolean | MultiComboBoxUI.isPopupVisible(JComboBox a) Invokes the isPopupVisible method on each UI handled by this object.
void | MultiComboBoxUI.setPopupVisible(JComboBox a, boolean b) Invokes the setPopupVisible method on each UI handled by this object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JComboBox.AccessibleJComboBox

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JComboBox.AccessibleJComboBox

No usage of javax.swing.JComboBox.AccessibleJComboBox

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JComponent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JComponent

Packages that use JComponent
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.colorchooser | Contains classes and interfaces used by the JColorChooser component.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.
javax.swing.plaf.synth | Synth is a skinnable look and feel in which all painting is delegated.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of JComponent in javax.swing

Subclasses of JComponent in javax.swing
class | AbstractButton Defines common behaviors for buttons and menu items.
class | Box A lightweight container that uses a BoxLayout object as its layout manager.
static class | Box.Filler An implementation of a lightweight component that participates in layout but has no view.
class | DefaultListCellRenderer Renders an item in a list.
static class | DefaultListCellRenderer.UIResource A subclass of DefaultListCellRenderer that implements UIResource.
class | JButton An implementation of a "push" button.
class | JCheckBox An implementation of a check box -- an item that can be selected or deselected, and which displays its state to the user.
class | JCheckBoxMenuItem A menu item that can be selected or deselected.
class | JColorChooser JColorChooser provides a pane of controls designed to allow a user to manipulate and select a color.
class | JComboBox A component that combines a button or editable field and a drop-down list.
class | JDesktopPane A container used to create a multiple-document interface or a virtual desktop.
class | JEditorPane A text component to edit various kinds of content.
class | JFileChooser JFileChooser provides a simple mechanism for the user to choose a file.
class | JFormattedTextField JFormattedTextField extends JTextField adding support for formatting arbitrary values, as well as retrieving a particular object once the user has edited the text.
class | JInternalFrame A lightweight object that provides many of the features of a native frame, including dragging, closing, becoming an icon, resizing, title display, and support for a menu bar.
static class | JInternalFrame.JDesktopIcon This component represents an iconified version of a JInternalFrame.
class | JLabel A display area for a short text string or an image, or both.
class | JLayeredPane JLayeredPane adds depth to a JFC/Swing container, allowing components to overlap each other when needed.
class | JList A component that displays a list of objects and allows the user to select one or more items.
class | JMenu An implementation of a menu -- a popup window containing JMenuItems that is displayed when the user selects an item on the JMenuBar.
class | JMenuBar An implementation of a menu bar.
class | JMenuItem An implementation of an item in a menu.
class | JOptionPane JOptionPane makes it easy to pop up a standard dialog box that prompts users for a value or informs them of something.
class | JPanel JPanel is a generic lightweight container.
class | JPasswordField JPasswordField is a lightweight component that allows the editing of a single line of text where the view indicates something was typed, but does not show the original characters.
class | JPopupMenu An implementation of a popup menu -- a small window that pops up and displays a series of choices.
static class | JPopupMenu.Separator A popup menu-specific separator.
class | JProgressBar A component that visually displays the progress of some task.
class | JRadioButton An implementation of a radio button -- an item that can be selected or deselected, and which displays its state to the user.
class | JRadioButtonMenuItem An implementation of a radio button menu item.
class | JRootPane A lightweight container used behind the scenes by JFrame, JDialog, JWindow, JApplet, and JInternalFrame.
class | JScrollBar An implementation of a scrollbar.
class | JScrollPane Provides a scrollable view of a lightweight component.
protected class | JScrollPane.ScrollBar By default JScrollPane creates scrollbars that are instances of this class.
class | JSeparator JSeparator provides a general purpose component for implementing divider lines - most commonly used as a divider between menu items that breaks them up into logical groupings.
class | JSlider A component that lets the user graphically select a value by sliding a knob within a bounded interval.
class | JSpinner A single line input field that lets the user select a number or an object value from an ordered sequence.
static class | JSpinner.DateEditor An editor for a JSpinner whose model is a SpinnerDateModel.
static class | JSpinner.DefaultEditor A simple base class for more specialized editors that displays a read-only view of the model's current value with a JFormattedTextField.
static class | JSpinner.ListEditor An editor for a JSpinner whose model is a SpinnerListModel.
static class | JSpinner.NumberEditor An editor for a JSpinner whose model is a SpinnerNumberModel.
class | JSplitPane JSplitPane is used to divide two (and only two) Components.
class | JTabbedPane A component that lets the user switch between a group of components by clicking on a tab with a given title and/or icon.
class | JTable The JTable is used to display and edit regular two-dimensional tables of cells.
class | JTextArea A JTextArea is a multi-line area that displays plain text.
class | JTextField JTextField is a lightweight component that allows the editing of a single line of text.
class | JTextPane A text component that can be marked up with attributes that are represented graphically.
class | JToggleButton An implementation of a two-state button.
class | JToolBar JToolBar provides a component that is useful for displaying commonly used Actions or controls.
static class | JToolBar.Separator A toolbar-specific separator.
class | JToolTip Used to display a "Tip" for a Component.
class | JTree A control that displays a set of hierarchical data as an outline.
class | JViewport The "viewport" or "porthole" through which you see the underlying information.

Fields in javax.swing declared as JComponent
protected  JComponent DefaultCellEditor.editorComponent
The Swing component being edited.

Methods in javax.swing that return JComponent
protected JComponent | JSpinner.createEditor(SpinnerModel model) This method is called by the constructors to create the JComponent that displays the current value of the sequence.
JComponent | JFileChooser.getAccessory() Returns the accessory component.
JComponent | JToolTip.getComponent() Returns the component the tooltip applies to.
JComponent | ComponentInputMap.getComponent() Returns the component the InputMap was created for.
JComponent | JSpinner.getEditor() Returns the component that displays and potentially changes the model's value.
JComponent | JColorChooser.getPreviewPanel() Returns the preview panel that shows a chosen color.

Methods in javax.swing with parameters of type JComponent
 void RepaintManager.addDirtyRegion(JComponent c, int x, int y, int w, int h)
Add a component in the list of components that should be refreshed.
 void RepaintManager.addInvalidComponent(JComponent invalidComponent)
Mark the component as in need of layout and queue a runnable for the event dispatching thread that will validate the components first isValidateRoot() ancestor.
 GroupLayout.SequentialGroup GroupLayout.SequentialGroup.addPreferredGap(JComponent comp1, JComponent comp2, LayoutStyle.ComponentPlacement type)
Adds an element representing the preferred gap between two components.
 GroupLayout.SequentialGroup GroupLayout.SequentialGroup.addPreferredGap(JComponent comp1, JComponent comp2, LayoutStyle.ComponentPlacement type, int pref, int max)
Adds an element representing the preferred gap between two components.
 void DefaultDesktopManager.beginDraggingFrame(JComponent f)
 void DesktopManager.beginDraggingFrame(JComponent f)
This method is normally called when the user has indicated that they will begin dragging a component around.
 void DefaultDesktopManager.beginResizingFrame(JComponent f, int direction)
 void DesktopManager.beginResizingFrame(JComponent f, int direction)
This methods is normally called when the user has indicated that they will begin resizing the frame.
static Rectangle SwingUtilities.calculateInnerArea(JComponent c, Rectangle r)
Stores the position and size of the inner painting area of the specified component in r and returns r.
 boolean TransferHandler.canImport(JComponent comp, DataFlavor[] transferFlavors)
Indicates whether a component will accept an import of the given set of data flavors prior to actually attempting to import it.
protected  Transferable TransferHandler.createTransferable(JComponent c)
Creates a Transferable to use as the source for a data transfer.
static RepaintManager RepaintManager.currentManager(JComponent c)
Return the RepaintManager for the calling thread given a JComponent.
 void DefaultDesktopManager.dragFrame(JComponent f, int newX, int newY)
Moves the visible location of the frame being dragged to the location specified.
 void DesktopManager.dragFrame(JComponent f, int newX, int newY)
The user has moved the frame.
 void DefaultDesktopManager.endDraggingFrame(JComponent f)
 void DesktopManager.endDraggingFrame(JComponent f)
This method signals the end of the dragging session.
 void DefaultDesktopManager.endResizingFrame(JComponent f)
 void DesktopManager.endResizingFrame(JComponent f)
This method signals the end of the resize session.
 void TransferHandler.exportAsDrag(JComponent comp, InputEvent e, int action)
Causes the Swing drag support to be initiated.
protected  void TransferHandler.exportDone(JComponent source, Transferable data, int action)
Invoked after data has been exported.
 void TransferHandler.exportToClipboard(JComponent comp, Clipboard clip, int action)
Causes a transfer from the given component to the given clipboard.
abstract  int LayoutStyle.getContainerGap(JComponent component, int position, Container parent)
Returns the amount of space to place between the component and specified edge of its parent.
 Rectangle RepaintManager.getDirtyRegion(JComponent aComponent)
Return the current dirty region for a component.
 Icon LookAndFeel.getDisabledIcon(JComponent component, Icon icon)
Returns an Icon with a disabled appearance.
 Icon LookAndFeel.getDisabledSelectedIcon(JComponent component, Icon icon)
Returns an Icon for use by disabled components that are also selected.
static int JLayeredPane.getLayer(JComponent c)
Gets the layer property for a JComponent, it does not cause any side effects like setLayer().
abstract  int LayoutStyle.getPreferredGap(JComponent component1, JComponent component2, LayoutStyle.ComponentPlacement type, int position, Container parent)
Returns the amount of space to use between two components.
 int TransferHandler.getSourceActions(JComponent c)
Returns the type of transfer actions supported by the source; any bitwise-OR combination of COPY, MOVE and LINK.
 ComponentUI UIDefaults.getUI(JComponent target)
Creates an ComponentUI implementation for the specified component.
static ComponentUI UIManager.getUI(JComponent target)
Returns the appropriate ComponentUI implementation for target.
static ActionMap SwingUtilities.getUIActionMap(JComponent component)
Returns the ActionMap provided by the UI in component component.
static InputMap SwingUtilities.getUIInputMap(JComponent component, int condition)
Returns the InputMap provided by the UI for condition condition in component component.
 boolean TransferHandler.importData(JComponent comp, Transferable t)
Causes a transfer to a component from a clipboard or a DND drop operation.
static void LookAndFeel.installBorder(JComponent c, String defaultBorderName)
Convenience method for setting a component's border property with a value from the defaults.
static void LookAndFeel.installColors(JComponent c, String defaultBgName, String defaultFgName)
Convenience method for setting a component's foreground and background color properties with values from the defaults.
static void LookAndFeel.installColorsAndFont(JComponent c, String defaultBgName, String defaultFgName, String defaultFontName)
Convenience method for setting a component's foreground, background and font properties with values from the defaults.
static void LookAndFeel.installProperty(JComponent c, String propertyName, Object propertyValue)
Convenience method for installing a property with the specified name and value on a component if that property has not already been set by the developer.
 boolean RepaintManager.isCompletelyDirty(JComponent aComponent)
Convenience method that returns true if aComponent will be completely painted during the next paintDirtyRegions().
static String SwingUtilities.layoutCompoundLabel(JComponent c, FontMetrics fm, String text, Icon icon, int verticalAlignment, int horizontalAlignment, int verticalTextPosition, int horizontalTextPosition, Rectangle viewR, Rectangle iconR, Rectangle textR, int textIconGap)
Compute and return the location of the icons origin, the location of origin of the text baseline, and a possibly clipped version of the compound labels string.
static ComponentInputMap LookAndFeel.makeComponentInputMap(JComponent c, Object[] keys)
Creates a ComponentInputMapUIResource from keys.
 void RepaintManager.markCompletelyClean(JComponent aComponent)
Mark a component completely clean.
 void RepaintManager.markCompletelyDirty(JComponent aComponent)
Mark a component completely dirty.
static void JLayeredPane.putLayer(JComponent c, int layer)
Sets the layer property on a JComponent.
 void ToolTipManager.registerComponent(JComponent component)
Registers a component for tooltip management.
 void RepaintManager.removeInvalidComponent(JComponent component)
Remove a component from the list of invalid components.
static void SwingUtilities.replaceUIActionMap(JComponent component, ActionMap uiActionMap)
Convenience method to change the UI ActionMap for component to uiActionMap.
static void SwingUtilities.replaceUIInputMap(JComponent component, int type, InputMap uiInputMap)
Convenience method to change the UI InputMap for component to uiInputMap.
 void DefaultDesktopManager.resizeFrame(JComponent f, int newX, int newY, int newWidth, int newHeight)
Calls setBoundsForFrame with the new values.
 void DesktopManager.resizeFrame(JComponent f, int newX, int newY, int newWidth, int newHeight)
The user has resized the component.
 void JFileChooser.setAccessory(JComponent newAccessory)
Sets the accessory component.
 void DefaultDesktopManager.setBoundsForFrame(JComponent f, int newX, int newY, int newWidth, int newHeight)
This moves the JComponent and repaints the damaged areas.
 void DesktopManager.setBoundsForFrame(JComponent f, int newX, int newY, int newWidth, int newHeight)
This is a primitive reshape method.
 void JToolTip.setComponent(JComponent c)
Specifies the component that the tooltip describes.
 void JSpinner.setEditor(JComponent editor)
Changes the JComponent that displays the current value of the SpinnerModel.
 void JColorChooser.setPreviewPanel(JComponent preview)
Sets the current preview panel.
 boolean InputVerifier.shouldYieldFocus(JComponent input)
Calls verify(input) to ensure that the input is valid.
static void LookAndFeel.uninstallBorder(JComponent c)
Convenience method for uninstalling a border.
 void ToolTipManager.unregisterComponent(JComponent component)
Removes a component from tooltip control.
abstract  boolean InputVerifier.verify(JComponent input)
Checks whether the JComponent's input is valid.

Constructors in javax.swing with parameters of type JComponent
ComponentInputMap(JComponent component)
Creates a ComponentInputMap associated with the specified component.
DebugGraphics(Graphics graphics, JComponent component)
Constructs a debug graphics context from an existing graphics context that slows down drawing for the specified component.

Uses of JComponent in javax.swing.colorchooser

Subclasses of JComponent in javax.swing.colorchooser
 class AbstractColorChooserPanel
This is the abstract superclass for color choosers.

Methods in javax.swing.colorchooser that return JComponent
static JComponent ColorChooserComponentFactory.getPreviewPanel()

Uses of JComponent in javax.swing.event

Methods in javax.swing.event that return JComponent
 JComponent AncestorEvent.getComponent()
Returns the component that the listener was added to.

Constructors in javax.swing.event with parameters of type JComponent
AncestorEvent(JComponent source, int id, Container ancestor, Container ancestorParent)
Constructs an AncestorEvent object to identify a change in an ancestor-component's display-status.

Uses of JComponent in javax.swing.plaf

Methods in javax.swing.plaf with parameters of type JComponent
boolean | ComponentUI.contains(JComponent c, int x, int y) Returns true if the specified x,y location is contained within the look and feel's defined shape of the specified component.
static ComponentUI | ComponentUI.createUI(JComponent c) Returns an instance of the UI delegate for the specified component.
Accessible | ComponentUI.getAccessibleChild(JComponent c, int i) Returns the ith Accessible child of the object.
int | ComponentUI.getAccessibleChildrenCount(JComponent c) Returns the number of accessible children in the object.
int | ComponentUI.getBaseline(JComponent c, int width, int height) Returns the baseline.
Component.BaselineResizeBehavior | ComponentUI.getBaselineResizeBehavior(JComponent c) Returns an enum indicating how the baseline of he component changes as the size changes.
Dimension | ComponentUI.getMaximumSize(JComponent c) Returns the specified component's maximum size appropriate for the look and feel.
Dimension | ComponentUI.getMinimumSize(JComponent c) Returns the specified component's minimum size appropriate for the look and feel.
Dimension | ComponentUI.getPreferredSize(JComponent c) Returns the specified component's preferred size appropriate for the look and feel.
void | ComponentUI.installUI(JComponent c) Configures the specified component appropriate for the look and feel.
void | ComponentUI.paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
void | ComponentUI.uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
void | ComponentUI.update(Graphics g, JComponent c) Notifies this UI delegate that it's time to paint the specified component.

Constructors in javax.swing.plaf with parameters of type JComponent
ComponentInputMapUIResource(JComponent component)

Uses of JComponent in javax.swing.plaf.basic

Subclasses of JComponent in javax.swing.plaf.basic
class | BasicArrowButton JButton object that draws a scaled Arrow in one of the cardinal directions.
class | BasicComboBoxRenderer ComboBox renderer
static class | BasicComboBoxRenderer.UIResource A subclass of BasicComboBoxRenderer that implements UIResource.
class | BasicComboPopup This is a basic implementation of the ComboPopup interface.
class | BasicInternalFrameTitlePane The class that manages a basic title bar
class | BasicInternalFrameTitlePane.SystemMenuBar This class should be treated as a "protected" inner class.

Fields in javax.swing.plaf.basic declared as JComponent
protected JComponent | BasicInternalFrameUI.eastPane
protected JComponent | BasicDesktopIconUI.iconPane The title pane component used in the desktop icon.
protected JComponent | BasicOptionPaneUI.inputComponent JComponent provide for input if optionPane.getWantsInput() returns true.
protected JComponent | BasicInternalFrameUI.northPane
protected JComponent | BasicInternalFrameUI.southPane
protected JComponent | BasicInternalFrameUI.westPane

Methods in javax.swing.plaf.basic that return JComponent
protected JComponent | BasicInternalFrameUI.createEastPane(JInternalFrame w)
protected JComponent | BasicSpinnerUI.createEditor() This method is called by installUI to get the editor component of the JSpinner.
protected JComponent | BasicInternalFrameUI.createNorthPane(JInternalFrame w)
protected JComponent | BasicInternalFrameUI.createSouthPane(JInternalFrame w)
protected JComponent | BasicInternalFrameUI.createWestPane(JInternalFrame w)
JComponent | BasicInternalFrameUI.getEastPane()
JComponent | BasicInternalFrameUI.getNorthPane()
JComponent | BasicInternalFrameUI.getSouthPane()
JComponent | BasicInternalFrameUI.getWestPane()

Methods in javax.swing.plaf.basic with parameters of type JComponent
protected  ChangeListener BasicMenuUI.createChangeListener(JComponent c)
static View BasicHTML.createHTMLView(JComponent c, String html)
Create an html renderer for the given component and string of html.
protected  MenuDragMouseListener BasicMenuUI.createMenuDragMouseListener(JComponent c)
protected  MenuDragMouseListener BasicMenuItemUI.createMenuDragMouseListener(JComponent c)
protected  MenuKeyListener BasicMenuUI.createMenuKeyListener(JComponent c)
protected  MenuKeyListener BasicMenuItemUI.createMenuKeyListener(JComponent c)
protected  MenuListener BasicMenuUI.createMenuListener(JComponent c)
protected  MouseInputListener BasicMenuUI.createMouseInputListener(JComponent c)
protected  MouseInputListener BasicMenuItemUI.createMouseInputListener(JComponent c)
protected  PropertyChangeListener BasicMenuUI.createPropertyChangeListener(JComponent c)
protected  PropertyChangeListener BasicMenuItemUI.createPropertyChangeListener(JComponent c)
Creates a PropertyChangeListener which will be added to the menu item.
static ComponentUI BasicPopupMenuSeparatorUI.createUI(JComponent c)
static ComponentUI BasicRadioButtonUI.createUI(JComponent b)
static ComponentUI BasicCheckBoxUI.createUI(JComponent b)
static ComponentUI BasicViewportUI.createUI(JComponent c)
static ComponentUI BasicToolBarSeparatorUI.createUI(JComponent c)
static ComponentUI BasicRadioButtonMenuItemUI.createUI(JComponent b)
static ComponentUI BasicSeparatorUI.createUI(JComponent c)
static ComponentUI BasicPasswordFieldUI.createUI(JComponent c)
Creates a UI for a JPasswordField.
static ComponentUI BasicFormattedTextFieldUI.createUI(JComponent c)
Creates a UI for a JFormattedTextField.
static ComponentUI BasicToggleButtonUI.createUI(JComponent b)
static ComponentUI BasicCheckBoxMenuItemUI.createUI(JComponent c)
static ComponentUI BasicTextPaneUI.createUI(JComponent c)
Creates a UI for the JTextPane.
static ComponentUI BasicToolTipUI.createUI(JComponent c)
static ComponentUI BasicToolBarUI.createUI(JComponent c)
static ComponentUI BasicTextAreaUI.createUI(JComponent ta)
Creates a UI for a JTextArea.
static ComponentUI BasicTableHeaderUI.createUI(JComponent h)
static ComponentUI BasicTableUI.createUI(JComponent c)
static ComponentUI BasicTabbedPaneUI.createUI(JComponent c)
static ComponentUI BasicSpinnerUI.createUI(JComponent c)
Returns a new instance of BasicSpinnerUI.
static ComponentUI BasicSliderUI.createUI(JComponent b)
static ComponentUI BasicScrollPaneUI.createUI(JComponent x)
static ComponentUI BasicScrollBarUI.createUI(JComponent c)
static ComponentUI BasicProgressBarUI.createUI(JComponent x)
static ComponentUI BasicPanelUI.createUI(JComponent c)
static ComponentUI BasicOptionPaneUI.createUI(JComponent x)
Creates a new BasicOptionPaneUI instance.
static ComponentUI BasicMenuUI.createUI(JComponent x)
static ComponentUI BasicMenuBarUI.createUI(JComponent x)
static ComponentUI BasicListUI.createUI(JComponent list)
Returns a new instance of BasicListUI.
static ComponentUI BasicLabelUI.createUI(JComponent c)
static ComponentUI BasicInternalFrameUI.createUI(JComponent b)
static ComponentUI BasicTextFieldUI.createUI(JComponent c)
Creates a UI for a JTextField.
static ComponentUI BasicEditorPaneUI.createUI(JComponent c)
Creates a UI for the JTextPane.
static ComponentUI BasicDesktopIconUI.createUI(JComponent c)
static ComponentUI BasicDesktopPaneUI.createUI(JComponent c)
static ComponentUI BasicColorChooserUI.createUI(JComponent c)
static ComponentUI BasicButtonUI.createUI(JComponent c)
static ComponentUI BasicTreeUI.createUI(JComponent x)
static ComponentUI BasicRootPaneUI.createUI(JComponent c)
static ComponentUI BasicSplitPaneUI.createUI(JComponent x)
Creates a new BasicSplitPaneUI instance
static ComponentUI BasicComboBoxUI.createUI(JComponent c)
static ComponentUI BasicMenuItemUI.createUI(JComponent c)
static ComponentUI BasicPopupMenuUI.createUI(JComponent x)
protected  void BasicInternalFrameUI.deinstallMouseHandlers(JComponent c)
 Accessible BasicComboBoxUI.getAccessibleChild(JComponent c, int i)
 int BasicComboBoxUI.getAccessibleChildrenCount(JComponent c)
 int BasicTextAreaUI.getBaseline(JComponent c, int width, int height)
Returns the baseline.
 int BasicTableHeaderUI.getBaseline(JComponent c, int width, int height)
Returns the baseline.
 int BasicTableUI.getBaseline(JComponent c, int width, int height)
Returns the baseline.
 int BasicTabbedPaneUI.getBaseline(JComponent c, int width, int height)
Returns the baseline.
 int BasicSpinnerUI.getBaseline(JComponent c, int width, int height)
Returns the baseline.
 int BasicSliderUI.getBaseline(JComponent c, int width, int height)
Returns the baseline.
 int BasicScrollPaneUI.getBaseline(JComponent c, int width, int height)
Returns the baseline.
 int BasicProgressBarUI.getBaseline(JComponent c, int width, int height)
Returns the baseline.
 int BasicPanelUI.getBaseline(JComponent c, int width, int height)
Returns the baseline.
 int BasicListUI.getBaseline(JComponent c, int width, int height)
Returns the baseline.
 int BasicLabelUI.getBaseline(JComponent c, int width, int height)
Returns the baseline.
 int BasicTextFieldUI.getBaseline(JComponent c, int width, int height)
Returns the baseline.
 int BasicButtonUI.getBaseline(JComponent c, int width, int height)
Returns the baseline.
 int BasicTreeUI.getBaseline(JComponent c, int width, int height)
Returns the baseline.
 int BasicComboBoxUI.getBaseline(JComponent c, int width, int height)
Returns the baseline.
 Component.BaselineResizeBehavior BasicTextAreaUI.getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Component.BaselineResizeBehavior BasicTableUI.getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Component.BaselineResizeBehavior BasicTabbedPaneUI.getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Component.BaselineResizeBehavior BasicSpinnerUI.getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Component.BaselineResizeBehavior BasicSliderUI.getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Component.BaselineResizeBehavior BasicScrollPaneUI.getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Component.BaselineResizeBehavior BasicProgressBarUI.getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Component.BaselineResizeBehavior BasicPanelUI.getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Component.BaselineResizeBehavior BasicListUI.getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Component.BaselineResizeBehavior BasicLabelUI.getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Component.BaselineResizeBehavior BasicTextFieldUI.getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Component.BaselineResizeBehavior BasicButtonUI.getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Component.BaselineResizeBehavior BasicTreeUI.getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Component.BaselineResizeBehavior BasicComboBoxUI.getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Insets BasicDesktopIconUI.getInsets(JComponent c)
 Insets BasicSplitPaneUI.getInsets(JComponent jc)
Returns the insets.
 Dimension BasicSeparatorUI.getMaximumSize(JComponent c)
 Dimension BasicToolTipUI.getMaximumSize(JComponent c)
 Dimension BasicTableHeaderUI.getMaximumSize(JComponent c)
Return the maximum size of the header.
 Dimension BasicTableUI.getMaximumSize(JComponent c)
Return the maximum size of the table.
 Dimension BasicTabbedPaneUI.getMaximumSize(JComponent c)
 Dimension BasicSliderUI.getMaximumSize(JComponent c)
 Dimension BasicScrollPaneUI.getMaximumSize(JComponent c)
 Dimension BasicScrollBarUI.getMaximumSize(JComponent c)
 Dimension BasicProgressBarUI.getMaximumSize(JComponent c)
 Dimension BasicMenuUI.getMaximumSize(JComponent c)
 Dimension BasicMenuBarUI.getMaximumSize(JComponent c)
 Dimension BasicLabelUI.getMaximumSize(JComponent c)
 Dimension BasicInternalFrameUI.getMaximumSize(JComponent x)
 Dimension BasicDesktopIconUI.getMaximumSize(JComponent c)
Desktop icons can not be resized.
 Dimension BasicDesktopPaneUI.getMaximumSize(JComponent c)
 Dimension BasicTextUI.getMaximumSize(JComponent c)
Gets the maximum size for the editor component.
 Dimension BasicButtonUI.getMaximumSize(JComponent c)
 Dimension BasicTreeUI.getMaximumSize(JComponent c)
Returns the maximum size for this component, which will be the preferred size if the instance is currently in a JTree, or 0, 0.
 Dimension BasicSplitPaneUI.getMaximumSize(JComponent jc)
Returns the maximum size for the passed in component, This is passed off to the current layoutmanager.
 Dimension BasicComboBoxUI.getMaximumSize(JComponent c)
 Dimension BasicMenuItemUI.getMaximumSize(JComponent c)
 Dimension BasicSeparatorUI.getMinimumSize(JComponent c)
 Dimension BasicToolTipUI.getMinimumSize(JComponent c)
 Dimension BasicTextAreaUI.getMinimumSize(JComponent c)
The method is overridden to take into account caret width.
 Dimension BasicTableHeaderUI.getMinimumSize(JComponent c)
Return the minimum size of the header.
 Dimension BasicTableUI.getMinimumSize(JComponent c)
Return the minimum size of the table.
 Dimension BasicTabbedPaneUI.getMinimumSize(JComponent c)
 Dimension BasicSliderUI.getMinimumSize(JComponent c)
 Dimension BasicProgressBarUI.getMinimumSize(JComponent c)
The Minimum size for this component is 10.
 Dimension BasicMenuBarUI.getMinimumSize(JComponent c)
 Dimension BasicLabelUI.getMinimumSize(JComponent c)
 Dimension BasicInternalFrameUI.getMinimumSize(JComponent x)
 Dimension BasicDesktopIconUI.getMinimumSize(JComponent c)
 Dimension BasicDesktopPaneUI.getMinimumSize(JComponent c)
 Dimension BasicTextUI.getMinimumSize(JComponent c)
Gets the minimum size for the editor component.
 Dimension BasicButtonUI.getMinimumSize(JComponent c)
 Dimension BasicTreeUI.getMinimumSize(JComponent c)
Returns the minimum size for this component.
 Dimension BasicSplitPaneUI.getMinimumSize(JComponent jc)
Returns the minimum size for the passed in component, This is passed off to the current layoutmanager.
 Dimension BasicComboBoxUI.getMinimumSize(JComponent c)
The minumum size is the size of the display area plus insets plus the button.
 Dimension BasicMenuItemUI.getMinimumSize(JComponent c)
protected  Dimension BasicMenuItemUI.getPreferredMenuItemSize(JComponent c, Icon checkIcon, Icon arrowIcon, int defaultTextIconGap)
 Dimension BasicPopupMenuSeparatorUI.getPreferredSize(JComponent c)
 Dimension BasicRadioButtonUI.getPreferredSize(JComponent c)
The preferred size of the radio button
 Dimension BasicToolBarSeparatorUI.getPreferredSize(JComponent c)
 Dimension BasicSeparatorUI.getPreferredSize(JComponent c)
 Dimension BasicToolTipUI.getPreferredSize(JComponent c)
 Dimension BasicTextAreaUI.getPreferredSize(JComponent c)
The method is overridden to take into account caret width.
 Dimension BasicTableHeaderUI.getPreferredSize(JComponent c)
Return the preferred size of the header.
 Dimension BasicTableUI.getPreferredSize(JComponent c)
Return the preferred size of the table.
 Dimension BasicSliderUI.getPreferredSize(JComponent c)
 Dimension BasicScrollBarUI.getPreferredSize(JComponent c)
A vertical scrollbar's preferred width is the maximum of preferred widths of the (non null) increment/decrement buttons, and the minimum width of the thumb.
 Dimension BasicProgressBarUI.getPreferredSize(JComponent c)
 Dimension BasicOptionPaneUI.getPreferredSize(JComponent c)
If c is the JOptionPane the receiver is contained in, the preferred size that is returned is the maximum of the preferred size of the LayoutManager for the JOptionPane, and getMinimumOptionPaneSize.
 Dimension BasicListUI.getPreferredSize(JComponent c)
The preferredSize of the list depends upon the layout orientation.
 Dimension BasicLabelUI.getPreferredSize(JComponent c)
 Dimension BasicInternalFrameUI.getPreferredSize(JComponent x)
 Dimension BasicDesktopIconUI.getPreferredSize(JComponent c)
 Dimension BasicDesktopPaneUI.getPreferredSize(JComponent c)
 Dimension BasicTextUI.getPreferredSize(JComponent c)
Gets the preferred size for the editor component.
 Dimension BasicButtonUI.getPreferredSize(JComponent c)
 Dimension BasicTreeUI.getPreferredSize(JComponent c)
Returns the preferred size to properly display the tree, this is a cover method for getPreferredSize(c, false).
 Dimension BasicSplitPaneUI.getPreferredSize(JComponent jc)
Returns the preferred size for the passed in component, This is passed off to the current layoutmanager.
 Dimension BasicComboBoxUI.getPreferredSize(JComponent c)
 Dimension BasicMenuItemUI.getPreferredSize(JComponent c)
 Dimension BasicTreeUI.getPreferredSize(JComponent c, boolean checkConsistancy)
Returns the preferred size to represent the tree in c.
protected  void BasicViewportUI.installDefaults(JComponent c)
protected  void BasicToolTipUI.installDefaults(JComponent c)
 void BasicButtonListener.installKeyboardActions(JComponent c)
Register default key actions: pressing space to "click" a button and registring the keyboard mnemonic (if any).
protected  void BasicToolTipUI.installListeners(JComponent c)
protected  void BasicInternalFrameUI.installMouseHandlers(JComponent c)
protected  void BasicToolBarUI.installNonRolloverBorders(JComponent c)
Installs non-rollover borders on all the child components of the JComponent.
protected  void BasicToolBarUI.installNormalBorders(JComponent c)
Installs normal borders on all the child components of the JComponent.
protected  void BasicToolBarUI.installRolloverBorders(JComponent c)
Installs rollover borders on all the child components of the JComponent.
 void BasicViewportUI.installUI(JComponent c)
 void BasicSeparatorUI.installUI(JComponent c)
 void BasicTextPaneUI.installUI(JComponent c)
 void BasicToolTipUI.installUI(JComponent c)
 void BasicToolBarUI.installUI(JComponent c)
 void BasicTableHeaderUI.installUI(JComponent c)
 void BasicTableUI.installUI(JComponent c)
 void BasicTabbedPaneUI.installUI(JComponent c)
 void BasicSpinnerUI.installUI(JComponent c)
Calls installDefaults, installListeners, and then adds the components returned by createNextButton, createPreviousButton, and createEditor.
 void BasicSliderUI.installUI(JComponent c)
 void BasicScrollPaneUI.installUI(JComponent x)
 void BasicScrollBarUI.installUI(JComponent c)
 void BasicProgressBarUI.installUI(JComponent c)
 void BasicPanelUI.installUI(JComponent c)
 void BasicOptionPaneUI.installUI(JComponent c)
Installs the receiver as the L&F for the passed in JOptionPane.
 void BasicMenuBarUI.installUI(JComponent c)
 void BasicListUI.installUI(JComponent c)
Initializes this.list by calling installDefaults(), installListeners(), and installKeyboardActions() in order.
 void BasicLabelUI.installUI(JComponent c)
 void BasicInternalFrameUI.installUI(JComponent c)
 void BasicEditorPaneUI.installUI(JComponent c)
Installs the UI for a component.
 void BasicDesktopIconUI.installUI(JComponent c)
 void BasicDesktopPaneUI.installUI(JComponent c)
 void BasicColorChooserUI.installUI(JComponent c)
 void BasicFileChooserUI.installUI(JComponent c)
 void BasicTextUI.installUI(JComponent c)
Installs the UI for a component.
 void BasicButtonUI.installUI(JComponent c)
 void BasicTreeUI.installUI(JComponent c)
 void BasicRootPaneUI.installUI(JComponent c)
 void BasicSplitPaneUI.installUI(JComponent c)
Installs the UI.
 void BasicComboBoxUI.installUI(JComponent c)
 void BasicMenuItemUI.installUI(JComponent c)
 void BasicPopupMenuUI.installUI(JComponent c)
 void BasicDesktopIconUI.MouseInputHandler.moveAndRepaint(JComponent f, int newX, int newY, int newWidth, int newHeight)
 void BasicPopupMenuSeparatorUI.paint(Graphics g, JComponent c)
 void BasicRadioButtonUI.paint(Graphics g, JComponent c)
paint the radio button
 void BasicToolBarSeparatorUI.paint(Graphics g, JComponent c)
 void BasicSeparatorUI.paint(Graphics g, JComponent c)
 void BasicToggleButtonUI.paint(Graphics g, JComponent c)
 void BasicToolTipUI.paint(Graphics g, JComponent c)
 void BasicTableHeaderUI.paint(Graphics g, JComponent c)
 void BasicTableUI.paint(Graphics g, JComponent c)
Paint a representation of the table instance that was set in installUI().
 void BasicTabbedPaneUI.paint(Graphics g, JComponent c)
 void BasicSliderUI.paint(Graphics g, JComponent c)
 void BasicScrollPaneUI.paint(Graphics g, JComponent c)
 void BasicScrollBarUI.paint(Graphics g, JComponent c)
 void BasicProgressBarUI.paint(Graphics g, JComponent c)
Delegates painting to one of two methods: paintDeterminate or paintIndeterminate.
 void BasicListUI.paint(Graphics g, JComponent c)
Paint the rows that intersect the Graphics objects clipRect.
 void BasicLabelUI.paint(Graphics g, JComponent c)
Paint the label text in the foreground color, if the label is opaque then paint the entire background with the background color.
 void BasicDesktopPaneUI.paint(Graphics g, JComponent c)
 void BasicTextUI.paint(Graphics g, JComponent c)
Paints the interface.
 void BasicButtonUI.paint(Graphics g, JComponent c)
 void BasicTreeUI.paint(Graphics g, JComponent c)
 void BasicSplitPaneUI.paint(Graphics g, JComponent jc)
Messaged to paint the look and feel.
 void BasicComboBoxUI.paint(Graphics g, JComponent c)
 void BasicMenuItemUI.paint(Graphics g, JComponent c)
protected  void BasicProgressBarUI.paintDeterminate(Graphics g, JComponent c)
All purpose paint method that should do the right thing for almost all linear, determinate progress bars.
protected  void BasicTreeUI.paintHorizontalLine(Graphics g, JComponent c, int y, int left, int right)
Paints a horizontal line.
protected  void BasicButtonUI.paintIcon(Graphics g, JComponent c, Rectangle iconRect)
protected  void BasicProgressBarUI.paintIndeterminate(Graphics g, JComponent c)
All purpose paint method that should do the right thing for all linear bouncing-box progress bars.
protected  void BasicMenuItemUI.paintMenuItem(Graphics g, JComponent c, Icon checkIcon, Icon arrowIcon, Color background, Color foreground, int defaultTextIconGap)
protected  void BasicButtonUI.paintText(Graphics g, JComponent c, Rectangle textRect, String text)
As of Java 2 platform v 1.4 this method should not be used or overriden.
protected  void BasicScrollBarUI.paintThumb(Graphics g, JComponent c, Rectangle thumbBounds)
protected  void BasicScrollBarUI.paintTrack(Graphics g, JComponent c, Rectangle trackBounds)
protected  void BasicTreeUI.paintVerticalLine(Graphics g, JComponent c, int x, int top, int bottom)
Paints a vertical line.
protected  void BasicSpinnerUI.replaceEditor(JComponent oldEditor, JComponent newEditor)
Called by the PropertyChangeListener when the JSpinner editor property changes.
protected  void BasicInternalFrameUI.replacePane(JComponent currentPane, JComponent newPane)
Installs necessary mouse handlers on newPane and adds it to the frame.
 void BasicInternalFrameUI.setEastPane(JComponent c)
 void BasicInternalFrameUI.setNorthPane(JComponent c)
 void BasicInternalFrameUI.setSouthPane(JComponent c)
 void BasicInternalFrameUI.setWestPane(JComponent c)
protected  void BasicViewportUI.uninstallDefaults(JComponent c)
protected  void BasicToolTipUI.uninstallDefaults(JComponent c)
 void BasicButtonListener.uninstallKeyboardActions(JComponent c)
Unregister's default key actions
protected  void BasicToolTipUI.uninstallListeners(JComponent c)
protected  void BasicScrollPaneUI.uninstallListeners(JComponent c)
 void BasicViewportUI.uninstallUI(JComponent c)
 void BasicSeparatorUI.uninstallUI(JComponent c)
 void BasicToolTipUI.uninstallUI(JComponent c)
 void BasicToolBarUI.uninstallUI(JComponent c)
 void BasicTableHeaderUI.uninstallUI(JComponent c)
 void BasicTableUI.uninstallUI(JComponent c)
 void BasicTabbedPaneUI.uninstallUI(JComponent c)
 void BasicSpinnerUI.uninstallUI(JComponent c)
Calls uninstallDefaults, uninstallListeners, and then removes all of the spinners children.
 void BasicSliderUI.uninstallUI(JComponent c)
 void BasicScrollPaneUI.uninstallUI(JComponent c)
 void BasicScrollBarUI.uninstallUI(JComponent c)
 void BasicProgressBarUI.uninstallUI(JComponent c)
 void BasicPanelUI.uninstallUI(JComponent c)
 void BasicOptionPaneUI.uninstallUI(JComponent c)
Removes the receiver from the L&F controller of the passed in split pane.
 void BasicMenuBarUI.uninstallUI(JComponent c)
 void BasicListUI.uninstallUI(JComponent c)
Uninitializes this.list by calling uninstallListeners(), uninstallKeyboardActions(), and uninstallDefaults() in order.
 void BasicLabelUI.uninstallUI(JComponent c)
 void BasicInternalFrameUI.uninstallUI(JComponent c)
 void BasicEditorPaneUI.uninstallUI(JComponent c)
Deinstalls the UI for a component.
 void BasicDesktopIconUI.uninstallUI(JComponent c)
 void BasicDesktopPaneUI.uninstallUI(JComponent c)
 void BasicColorChooserUI.uninstallUI(JComponent c)
 void BasicFileChooserUI.uninstallUI(JComponent c)
 void BasicTextUI.uninstallUI(JComponent c)
Deinstalls the UI for a component.
 void BasicButtonUI.uninstallUI(JComponent c)
 void BasicTreeUI.uninstallUI(JComponent c)
 void BasicRootPaneUI.uninstallUI(JComponent c)
 void BasicSplitPaneUI.uninstallUI(JComponent c)
Uninstalls the UI.
 void BasicComboBoxUI.uninstallUI(JComponent c)
 void BasicMenuItemUI.uninstallUI(JComponent c)
 void BasicPopupMenuUI.uninstallUI(JComponent c)
 void BasicTextUI.update(Graphics g, JComponent c)
Superclass paints background in an uncontrollable way (i.e.
 void BasicMenuItemUI.update(Graphics g, JComponent c)
We draw the background in paintMenuItem() so override update (which fills the background of opaque components by default) to just call paint().
static void BasicHTML.updateRenderer(JComponent c, String text)
Stash the HTML render for the given text into the client properties of the given JComponent.

Uses of JComponent in javax.swing.plaf.metal

Subclasses of JComponent in javax.swing.plaf.metal
class | MetalComboBoxButton JButton subclass to help out MetalComboBoxUI
class | MetalComboBoxUI.MetalComboPopup Deprecated. As of Java 2 platform v1.4.
protected class | MetalFileChooserUI.FileRenderer
class | MetalFileChooserUI.FilterComboBoxRenderer Render different type sizes and styles.
class | MetalInternalFrameTitlePane Class that manages a JLF title bar
class | MetalScrollButton JButton object for Metal scrollbar arrows.

Methods in javax.swing.plaf.metal that return JComponent
protected  JComponent MetalInternalFrameUI.createNorthPane(JInternalFrame w)

Methods in javax.swing.plaf.metal with parameters of type JComponent
static ComponentUI | MetalPopupMenuSeparatorUI.createUI(JComponent c)
static ComponentUI | MetalRadioButtonUI.createUI(JComponent c)
static ComponentUI | MetalCheckBoxUI.createUI(JComponent b)
static ComponentUI | MetalTreeUI.createUI(JComponent x)
static ComponentUI | MetalToolTipUI.createUI(JComponent c)
static ComponentUI | MetalToolBarUI.createUI(JComponent c)
static ComponentUI | MetalToggleButtonUI.createUI(JComponent b)
static ComponentUI | MetalTextFieldUI.createUI(JComponent c)
static ComponentUI | MetalTabbedPaneUI.createUI(JComponent x)
static ComponentUI | MetalSplitPaneUI.createUI(JComponent x) Creates a new MetalSplitPaneUI instance
static ComponentUI | MetalSliderUI.createUI(JComponent c)
static ComponentUI | MetalScrollPaneUI.createUI(JComponent x)
static ComponentUI | MetalScrollBarUI.createUI(JComponent c)
static ComponentUI | MetalRootPaneUI.createUI(JComponent c) Creates a UI for a JRootPane.
static ComponentUI | MetalProgressBarUI.createUI(JComponent c)
static ComponentUI | MetalSeparatorUI.createUI(JComponent c)
static ComponentUI | MetalMenuBarUI.createUI(JComponent x) Creates the ComponentUI implementation for the passed in component.
static ComponentUI | MetalLabelUI.createUI(JComponent c)
static ComponentUI | MetalInternalFrameUI.createUI(JComponent c)
static ComponentUI | MetalFileChooserUI.createUI(JComponent c)
static ComponentUI | MetalDesktopIconUI.createUI(JComponent c)
static ComponentUI | MetalComboBoxUI.createUI(JComponent c)
static ComponentUI | MetalButtonUI.createUI(JComponent c)
int | MetalComboBoxUI.getBaseline(JComponent c, int width, int height) Returns the baseline.
Icon | MetalLookAndFeel.getDisabledIcon(JComponent component, Icon icon) Returns an Icon with a disabled appearance.
Icon | MetalLookAndFeel.getDisabledSelectedIcon(JComponent component, Icon icon) Returns an Icon for use by disabled components that are also selected.
Dimension | MetalFileChooserUI.getMaximumSize(JComponent c) Returns the maximum size of the JFileChooser.
Dimension | MetalDesktopIconUI.getMaximumSize(JComponent c)
Dimension | MetalFileChooserUI.getMinimumSize(JComponent c) Returns the minimum size of the JFileChooser.
Dimension | MetalDesktopIconUI.getMinimumSize(JComponent c)
Dimension | MetalComboBoxUI.getMinimumSize(JComponent c)
Dimension | MetalPopupMenuSeparatorUI.getPreferredSize(JComponent c)
Dimension | MetalToolTipUI.getPreferredSize(JComponent c)
Dimension | MetalScrollBarUI.getPreferredSize(JComponent c)
Dimension | MetalSeparatorUI.getPreferredSize(JComponent c)
Dimension | MetalFileChooserUI.getPreferredSize(JComponent c) Returns the preferred size of the specified JFileChooser.
Dimension | MetalDesktopIconUI.getPreferredSize(JComponent c)
void | MetalTreeUI.installUI(JComponent c)
void | MetalToolTipUI.installUI(JComponent c)
void | MetalToolBarUI.installUI(JComponent c)
void | MetalSliderUI.installUI(JComponent c)
void | MetalScrollPaneUI.installUI(JComponent c)
void | MetalRootPaneUI.installUI(JComponent c) Invokes supers implementation of installUI to install the necessary state onto the passed in JRootPane to render the metal look and feel implementation of RootPaneUI.
void | MetalMenuBarUI.installUI(JComponent c) Configures the specified component appropriate for the metal look and feel.
void | MetalInternalFrameUI.installUI(JComponent c)
void | MetalFileChooserUI.installUI(JComponent c)
void | MetalPopupMenuSeparatorUI.paint(Graphics g, JComponent c)
void | MetalRadioButtonUI.paint(Graphics g, JComponent c)
void | MetalTreeUI.paint(Graphics g, JComponent c)
void | MetalToolTipUI.paint(Graphics g, JComponent c)
void | MetalTabbedPaneUI.paint(Graphics g, JComponent c)
void | MetalSeparatorUI.paint(Graphics g, JComponent c)
void | MetalComboBoxUI.paint(Graphics g, JComponent c)
void | MetalProgressBarUI.paintDeterminate(Graphics g, JComponent c) Draws a bit of special highlighting on the progress bar.
protected void | MetalTreeUI.paintHorizontalSeparators(Graphics g, JComponent c)
void | MetalProgressBarUI.paintIndeterminate(Graphics g, JComponent c) Draws a bit of special highlighting on the progress bar and bouncing box.
protected void | MetalToggleButtonUI.paintText(Graphics g, JComponent c, Rectangle textRect, String text)
protected void | MetalButtonUI.paintText(Graphics g, JComponent c, Rectangle textRect, String text)
protected void | MetalScrollBarUI.paintThumb(Graphics g, JComponent c, Rectangle thumbBounds)
protected void | MetalScrollBarUI.paintTrack(Graphics g, JComponent c, Rectangle trackBounds)
void | MetalTreeUI.uninstallUI(JComponent c)
void | MetalToolTipUI.uninstallUI(JComponent c)
void | MetalToolBarUI.uninstallUI(JComponent c)
void | MetalScrollPaneUI.uninstallUI(JComponent c)
void | MetalRootPaneUI.uninstallUI(JComponent c) Invokes supers implementation to uninstall any of its state.
void | MetalMenuBarUI.uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
void | MetalInternalFrameUI.uninstallUI(JComponent c)
void | MetalFileChooserUI.uninstallUI(JComponent c)
void | MetalToolBarUI.update(Graphics g, JComponent c) If necessary paints the background of the component, then invokes paint.
void | MetalToggleButtonUI.update(Graphics g, JComponent c) If necessary paints the background of the component, then invokes paint.
void | MetalTabbedPaneUI.update(Graphics g, JComponent c)
void | MetalMenuBarUI.update(Graphics g, JComponent c) If necessary paints the background of the component, then invokes paint.
void | MetalButtonUI.update(Graphics g, JComponent c) If necessary paints the background of the component, then invokes paint.

Uses of JComponent in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi with parameters of type JComponent
boolean | MultiViewportUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiTreeUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiToolTipUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiToolBarUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiTextUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiTableUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiTableHeaderUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiTabbedPaneUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiSplitPaneUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiSpinnerUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiSliderUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiSeparatorUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiScrollPaneUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiScrollBarUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiRootPaneUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiProgressBarUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiPopupMenuUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiPanelUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiOptionPaneUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiMenuItemUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiMenuBarUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiListUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiLabelUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiInternalFrameUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiFileChooserUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiDesktopPaneUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiDesktopIconUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiComboBoxUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiColorChooserUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | MultiButtonUI.contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | MultiViewportUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiTreeUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiToolTipUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiToolBarUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiTextUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiTableUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiTableHeaderUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiTabbedPaneUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiSplitPaneUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiSpinnerUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiSliderUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiSeparatorUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiScrollPaneUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiScrollBarUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiRootPaneUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiProgressBarUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiPopupMenuUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiPanelUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiOptionPaneUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiMenuItemUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiMenuBarUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiListUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiLabelUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiInternalFrameUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiFileChooserUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiDesktopPaneUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiDesktopIconUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiComboBoxUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiColorChooserUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiButtonUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiLookAndFeel.createUIs(ComponentUI mui, Vector uis, JComponent target) Creates the ComponentUI objects required to present the target component, placing the objects in the uis vector and returning the ComponentUI object that best represents the component's UI.
Accessible | MultiViewportUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiTreeUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiToolTipUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiToolBarUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiTextUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiTableUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiTableHeaderUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiTabbedPaneUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiSplitPaneUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiSpinnerUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiSliderUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiSeparatorUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiScrollPaneUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiScrollBarUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiRootPaneUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiProgressBarUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiPopupMenuUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiPanelUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiOptionPaneUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiMenuItemUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiMenuBarUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiListUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiLabelUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiInternalFrameUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiFileChooserUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiDesktopPaneUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiDesktopIconUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiComboBoxUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiColorChooserUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
Accessible | MultiButtonUI.getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | MultiViewportUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiTreeUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiToolTipUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiToolBarUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiTextUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiTableUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiTableHeaderUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiTabbedPaneUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiSplitPaneUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiSpinnerUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiSliderUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiSeparatorUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiScrollPaneUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiScrollBarUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiRootPaneUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiProgressBarUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiPopupMenuUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiPanelUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiOptionPaneUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiMenuItemUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiMenuBarUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiListUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiLabelUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiInternalFrameUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiFileChooserUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiDesktopPaneUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiDesktopIconUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiComboBoxUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiColorChooserUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | MultiButtonUI.getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | MultiViewportUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiTreeUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiToolTipUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiToolBarUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiTextUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiTableUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiTableHeaderUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiTabbedPaneUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiSplitPaneUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiSpinnerUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiSliderUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiSeparatorUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiScrollPaneUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiScrollBarUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiRootPaneUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiProgressBarUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiPopupMenuUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiPanelUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiOptionPaneUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiMenuItemUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiMenuBarUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiListUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiLabelUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiInternalFrameUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiFileChooserUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiDesktopPaneUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiDesktopIconUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiComboBoxUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiColorChooserUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiButtonUI.getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | MultiViewportUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiTreeUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiToolTipUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiToolBarUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiTextUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiTableUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiTableHeaderUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiTabbedPaneUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiSplitPaneUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiSpinnerUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiSliderUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiSeparatorUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiScrollPaneUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiScrollBarUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiRootPaneUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiProgressBarUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiPopupMenuUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiPanelUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiOptionPaneUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiMenuItemUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiMenuBarUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiListUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiLabelUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiInternalFrameUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiFileChooserUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiDesktopPaneUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiDesktopIconUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiComboBoxUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiColorChooserUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiButtonUI.getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | MultiViewportUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiTreeUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiToolTipUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiToolBarUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiTextUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiTableUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiTableHeaderUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiTabbedPaneUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiSplitPaneUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiSpinnerUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiSliderUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiSeparatorUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiScrollPaneUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiScrollBarUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiRootPaneUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiProgressBarUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiPopupMenuUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiPanelUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiOptionPaneUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiMenuItemUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiMenuBarUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiListUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiLabelUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiInternalFrameUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiFileChooserUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiDesktopPaneUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiDesktopIconUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiComboBoxUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiColorChooserUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Dimension | MultiButtonUI.getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
void | MultiViewportUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiTreeUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiToolTipUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiToolBarUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiTextUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiTableUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiTableHeaderUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiTabbedPaneUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiSplitPaneUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiSpinnerUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiSliderUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiSeparatorUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiScrollPaneUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiScrollBarUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiRootPaneUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiProgressBarUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiPopupMenuUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiPanelUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiOptionPaneUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiMenuItemUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiMenuBarUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiListUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiLabelUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiInternalFrameUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiFileChooserUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiDesktopPaneUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiDesktopIconUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiComboBoxUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiColorChooserUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiButtonUI.installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | MultiViewportUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiTreeUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiToolTipUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiToolBarUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiTextUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiTableUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiTableHeaderUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiTabbedPaneUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiSplitPaneUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiSpinnerUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiSliderUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiSeparatorUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiScrollPaneUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiScrollBarUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiRootPaneUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiProgressBarUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiPopupMenuUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiPanelUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiOptionPaneUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiMenuItemUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiMenuBarUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiListUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiLabelUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiInternalFrameUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiFileChooserUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiDesktopPaneUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiDesktopIconUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiComboBoxUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiColorChooserUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiButtonUI.paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | MultiViewportUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiTreeUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiToolTipUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiToolBarUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiTextUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiTableUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiTableHeaderUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiTabbedPaneUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiSplitPaneUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiSpinnerUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiSliderUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiSeparatorUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiScrollPaneUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiScrollBarUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiRootPaneUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiProgressBarUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiPopupMenuUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiPanelUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiOptionPaneUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiMenuItemUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiMenuBarUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiListUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiLabelUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiInternalFrameUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiFileChooserUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiDesktopPaneUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiDesktopIconUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiComboBoxUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiColorChooserUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiButtonUI.uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | MultiViewportUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiTreeUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiToolTipUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiToolBarUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiTextUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiTableUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiTableHeaderUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiTabbedPaneUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiSplitPaneUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiSpinnerUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiSliderUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiSeparatorUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiScrollPaneUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiScrollBarUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiRootPaneUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiProgressBarUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiPopupMenuUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiPanelUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiOptionPaneUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiMenuItemUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiMenuBarUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiListUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiLabelUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiInternalFrameUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiFileChooserUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiDesktopPaneUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiDesktopIconUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiComboBoxUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiColorChooserUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
void | MultiButtonUI.update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.

Uses of JComponent in javax.swing.plaf.synth

Methods in javax.swing.plaf.synth that return JComponent
 JComponent SynthContext.getComponent()
Returns the hosting component containing the region.

Methods in javax.swing.plaf.synth with parameters of type JComponent
static ComponentUI | SynthLookAndFeel.createUI(JComponent c) Creates the Synth look and feel ComponentUI for the passed in JComponent.
static Region | SynthLookAndFeel.getRegion(JComponent c) Returns the Region for the JComponent c.
abstract SynthStyle | SynthStyleFactory.getStyle(JComponent c, Region id) Returns the style for the specified Component.
static SynthStyle | SynthLookAndFeel.getStyle(JComponent c, Region region) Gets a SynthStyle for the specified region of the specified component.

Constructors in javax.swing.plaf.synth with parameters of type JComponent
SynthContext(JComponent component, Region region, SynthStyle style, int state)
Creates a SynthContext with the specified values.

Uses of JComponent in javax.swing.table

Subclasses of JComponent in javax.swing.table
class | DefaultTableCellRenderer The standard class for rendering (displaying) individual cells in a JTable.
static class | DefaultTableCellRenderer.UIResource A subclass of DefaultTableCellRenderer that implements UIResource.
class | JTableHeader This is the object which manages the header of the JTable.

Uses of JComponent in javax.swing.text

Subclasses of JComponent in javax.swing.text
 class JTextComponent
JTextComponent is the base class for swing text components.

Uses of JComponent in javax.swing.tree

Subclasses of JComponent in javax.swing.tree
class | DefaultTreeCellEditor.DefaultTextField TextField used when no editor is supplied.
class | DefaultTreeCellRenderer Displays an entry in a tree.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JComponent.AccessibleJComponent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JComponent.AccessibleJComponent

Packages that use JComponent.AccessibleJComponent
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of JComponent.AccessibleJComponent in javax.swing

Subclasses of JComponent.AccessibleJComponent in javax.swing
protected class | AbstractButton.AccessibleAbstractButton This class implements accessibility support for the AbstractButton class.
protected class | JButton.AccessibleJButton This class implements accessibility support for the JButton class.
protected class | JCheckBox.AccessibleJCheckBox This class implements accessibility support for the JCheckBox class.
protected class | JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem This class implements accessibility support for the JCheckBoxMenuItem class.
protected class | JColorChooser.AccessibleJColorChooser This class implements accessibility support for the JColorChooser class.
protected class | JComboBox.AccessibleJComboBox This class implements accessibility support for the JComboBox class.
protected class | JDesktopPane.AccessibleJDesktopPane This class implements accessibility support for the JDesktopPane class.
protected class | JEditorPane.AccessibleJEditorPane This class implements accessibility support for the JEditorPane class.
protected class | JEditorPane.AccessibleJEditorPaneHTML This class provides support for AccessibleHypertext, and is used in instances where the EditorKit installed in this JEditorPane is an instance of HTMLEditorKit.
protected class | JEditorPane.JEditorPaneAccessibleHypertextSupport What's returned by AccessibleJEditorPaneHTML.getAccessibleText.
protected class | JFileChooser.AccessibleJFileChooser This class implements accessibility support for the JFileChooser class.
protected class | JInternalFrame.AccessibleJInternalFrame This class implements accessibility support for the JInternalFrame class.
protected class | JInternalFrame.JDesktopIcon.AccessibleJDesktopIcon This class implements accessibility support for the JInternalFrame.JDesktopIcon class.
protected class | JLabel.AccessibleJLabel The class used to obtain the accessible role for this object.
protected class | JLayeredPane.AccessibleJLayeredPane This class implements accessibility support for the JLayeredPane class.
protected class | JList.AccessibleJList This class implements accessibility support for the JList class.
protected class | JMenu.AccessibleJMenu This class implements accessibility support for the JMenu class.
protected class | JMenuBar.AccessibleJMenuBar This class implements accessibility support for the JMenuBar class.
protected class | JMenuItem.AccessibleJMenuItem This class implements accessibility support for the JMenuItem class.
protected class | JOptionPane.AccessibleJOptionPane This class implements accessibility support for the JOptionPane class.
protected class | JPanel.AccessibleJPanel This class implements accessibility support for the JPanel class.
protected class | JPasswordField.AccessibleJPasswordField This class implements accessibility support for the JPasswordField class.
protected class | JPopupMenu.AccessibleJPopupMenu This class implements accessibility support for the JPopupMenu class.
protected class | JProgressBar.AccessibleJProgressBar This class implements accessibility support for the JProgressBar class.
protected class | JRadioButton.AccessibleJRadioButton This class implements accessibility support for the JRadioButton class.
protected class | JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem This class implements accessibility support for the JRadioButtonMenuItem class.
protected class | JRootPane.AccessibleJRootPane This class implements accessibility support for the JRootPane class.
protected class | JScrollBar.AccessibleJScrollBar This class implements accessibility support for the JScrollBar class.
protected class | JScrollPane.AccessibleJScrollPane This class implements accessibility support for the JScrollPane class.
protected class | JSeparator.AccessibleJSeparator This class implements accessibility support for the JSeparator class.
protected class | JSlider.AccessibleJSlider This class implements accessibility support for the JSlider class.
protected class | JSpinner.AccessibleJSpinner AccessibleJSpinner implements accessibility support for the JSpinner class.
protected class | JSplitPane.AccessibleJSplitPane This class implements accessibility support for the JSplitPane class.
protected class | JTabbedPane.AccessibleJTabbedPane This class implements accessibility support for the JTabbedPane class.
protected class | JTable.AccessibleJTable This class implements accessibility support for the JTable class.
protected class | JTextArea.AccessibleJTextArea This class implements accessibility support for the JTextArea class.
protected class | JTextField.AccessibleJTextField This class implements accessibility support for the JTextField class.
protected class | JToggleButton.AccessibleJToggleButton This class implements accessibility support for the JToggleButton class.
protected class | JToolBar.AccessibleJToolBar This class implements accessibility support for the JToolBar class.
protected class | JToolTip.AccessibleJToolTip This class implements accessibility support for the JToolTip class.
protected class | JTree.AccessibleJTree This class implements accessibility support for the JTree class.
protected class | JViewport.AccessibleJViewport This class implements accessibility support for the JViewport class.

Uses of JComponent.AccessibleJComponent in javax.swing.table

Subclasses of JComponent.AccessibleJComponent in javax.swing.table
protected  class JTableHeader.AccessibleJTableHeader
This class implements accessibility support for the JTableHeader class.

Uses of JComponent.AccessibleJComponent in javax.swing.text

Subclasses of JComponent.AccessibleJComponent in javax.swing.text
 class JTextComponent.AccessibleJTextComponent
This class implements accessibility support for the JTextComponent class.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JComponent.AccessibleJComponent.AccessibleContainerHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JComponent.AccessibleJComponent.AccessibleContainerHandler

No usage of javax.swing.JComponent.AccessibleJComponent.AccessibleContainerHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JComponent.AccessibleJComponent.AccessibleFocusHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JComponent.AccessibleJComponent.AccessibleFocusHandler

No usage of javax.swing.JComponent.AccessibleJComponent.AccessibleFocusHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JDesktopPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JDesktopPane

Packages that use JDesktopPane
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of JDesktopPane in javax.swing

Methods in javax.swing that return JDesktopPane
JDesktopPane | JInternalFrame.getDesktopPane() Convenience method that searches the ancestor hierarchy for a JDesktop instance.
JDesktopPane | JInternalFrame.JDesktopIcon.getDesktopPane() Convenience method to ask the icon for the Desktop object it belongs to.
static JDesktopPane | JOptionPane.getDesktopPaneForComponent(Component parentComponent) Returns the specified component's desktop pane.

Uses of JDesktopPane in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JDesktopPane
protected  JDesktopPane BasicDesktopPaneUI.desktop

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JDesktopPane.AccessibleJDesktopPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JDesktopPane.AccessibleJDesktopPane

No usage of javax.swing.JDesktopPane.AccessibleJDesktopPane

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JDialog

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JDialog

Packages that use JDialog
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JDialog in javax.swing

Methods in javax.swing that return JDialog
protected JDialog | JFileChooser.createDialog(Component parent) Creates and returns a new JDialog wrapping this centered on the parent in the parent's frame.
JDialog | JOptionPane.createDialog(Component parentComponent, String title) Creates and returns a new JDialog wrapping this centered on the parentComponent in the parentComponent's frame.
static JDialog | JColorChooser.createDialog(Component c, String title, boolean modal, JColorChooser chooserPane, ActionListener okListener, ActionListener cancelListener) Creates and returns a new dialog containing the specified ColorChooser pane along with "OK", "Cancel", and "Reset" buttons.
JDialog | JOptionPane.createDialog(String title) Creates and returns a new parentless JDialog with the specified title.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JDialog.AccessibleJDialog

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JDialog.AccessibleJDialog

No usage of javax.swing.JDialog.AccessibleJDialog

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JEditorPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JEditorPane

Packages that use JEditorPane
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of JEditorPane in javax.swing

Subclasses of JEditorPane in javax.swing
 class JTextPane
A text component that can be marked up with attributes that are represented graphically.

Uses of JEditorPane in javax.swing.text

Methods in javax.swing.text that return JEditorPane
protected  JEditorPane StyledEditorKit.StyledTextAction.getEditor(ActionEvent e)
Gets the target editor for an action.

Methods in javax.swing.text with parameters of type JEditorPane
void | StyledEditorKit.deinstall(JEditorPane c) Called when the kit is being removed from the JEditorPane.
void | EditorKit.deinstall(JEditorPane c) Called when the kit is being removed from the JEditorPane.
protected StyledDocument | StyledEditorKit.StyledTextAction.getStyledDocument(JEditorPane e) Gets the document associated with an editor pane.
protected StyledEditorKit | StyledEditorKit.StyledTextAction.getStyledEditorKit(JEditorPane e) Gets the editor kit associated with an editor pane.
void | StyledEditorKit.install(JEditorPane c) Called when the kit is being installed into a JEditorPane.
void | EditorKit.install(JEditorPane c) Called when the kit is being installed into the a JEditorPane.
protected void | StyledEditorKit.StyledTextAction.setCharacterAttributes(JEditorPane editor, AttributeSet attr, boolean replace) Applies the given attributes to character content.
protected void | StyledEditorKit.StyledTextAction.setParagraphAttributes(JEditorPane editor, AttributeSet attr, boolean replace) Applies the given attributes to paragraphs.

Uses of JEditorPane in javax.swing.text.html

Methods in javax.swing.text.html with parameters of type JEditorPane
protected void | HTMLEditorKit.LinkController.activateLink(int pos, JEditorPane editor) Calls linkActivated on the associated JEditorPane if the given position represents a link.
void | HTMLEditorKit.deinstall(JEditorPane c) Called when the kit is being removed from the JEditorPane.
protected HTMLDocument | HTMLEditorKit.HTMLTextAction.getHTMLDocument(JEditorPane e)
protected HTMLEditorKit | HTMLEditorKit.HTMLTextAction.getHTMLEditorKit(JEditorPane e)
protected void | HTMLEditorKit.InsertHTMLTextAction.insertAtBoundary(JEditorPane editor, HTMLDocument doc, int offset, Element insertElement, String html, HTML.Tag parentTag, HTML.Tag addTag) This is invoked when inserting at a boundary.
protected void | HTMLEditorKit.InsertHTMLTextAction.insertAtBoundry(JEditorPane editor, HTMLDocument doc, int offset, Element insertElement, String html, HTML.Tag parentTag, HTML.Tag addTag) Deprecated. As of Java 2 platform v1.3, use insertAtBoundary
protected void | HTMLEditorKit.InsertHTMLTextAction.insertHTML(JEditorPane editor, HTMLDocument doc, int offset, String html, int popDepth, int pushDepth, HTML.Tag addTag) A cover for HTMLEditorKit.insertHTML.
void | HTMLEditorKit.install(JEditorPane c) Called when the kit is being installed into the a JEditorPane.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JEditorPane.AccessibleJEditorPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JEditorPane.AccessibleJEditorPane

Packages that use JEditorPane.AccessibleJEditorPane
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JEditorPane.AccessibleJEditorPane in javax.swing

Subclasses of JEditorPane.AccessibleJEditorPane in javax.swing
protected class | JEditorPane.AccessibleJEditorPaneHTML This class provides support for AccessibleHypertext, and is used in instances where the EditorKit installed in this JEditorPane is an instance of HTMLEditorKit.
protected class | JEditorPane.JEditorPaneAccessibleHypertextSupport What's returned by AccessibleJEditorPaneHTML.getAccessibleText.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JEditorPane.AccessibleJEditorPaneHTML

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JEditorPane.AccessibleJEditorPaneHTML

No usage of javax.swing.JEditorPane.AccessibleJEditorPaneHTML

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JEditorPane.JEditorPaneAccessibleHypertextSupport

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JEditorPane.JEditorPaneAccessibleHypertextSupport

No usage of javax.swing.JEditorPane.JEditorPaneAccessibleHypertextSupport

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JEditorPane.JEditorPaneAccessibleHypertextSupport.HTMLLink

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JEditorPane.JEditorPaneAccessibleHypertextSupport.HTMLLink

No usage of javax.swing.JEditorPane.JEditorPaneAccessibleHypertextSupport.HTMLLink

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JFileChooser

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JFileChooser

Packages that use JFileChooser
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of JFileChooser in javax.swing.plaf

Methods in javax.swing.plaf with parameters of type JFileChooser
abstract void | FileChooserUI.ensureFileIsVisible(JFileChooser fc, File f)
abstract FileFilter | FileChooserUI.getAcceptAllFileFilter(JFileChooser fc)
abstract String | FileChooserUI.getApproveButtonText(JFileChooser fc)
abstract String | FileChooserUI.getDialogTitle(JFileChooser fc)
abstract FileView | FileChooserUI.getFileView(JFileChooser fc)
abstract void | FileChooserUI.rescanCurrentDirectory(JFileChooser fc)

Uses of JFileChooser in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic that return JFileChooser
 JFileChooser BasicFileChooserUI.getFileChooser()

Methods in javax.swing.plaf.basic with parameters of type JFileChooser
protected MouseListener | BasicFileChooserUI.createDoubleClickListener(JFileChooser fc, JList list)
ListSelectionListener | BasicFileChooserUI.createListSelectionListener(JFileChooser fc)
PropertyChangeListener | BasicFileChooserUI.createPropertyChangeListener(JFileChooser fc)
void | BasicFileChooserUI.ensureFileIsVisible(JFileChooser fc, File f)
FileFilter | BasicFileChooserUI.getAcceptAllFileFilter(JFileChooser fc) Returns the default accept all file filter
protected JButton | BasicFileChooserUI.getApproveButton(JFileChooser fc)
int | BasicFileChooserUI.getApproveButtonMnemonic(JFileChooser fc)
String | BasicFileChooserUI.getApproveButtonText(JFileChooser fc)
String | BasicFileChooserUI.getApproveButtonToolTipText(JFileChooser fc)
String | BasicFileChooserUI.getDialogTitle(JFileChooser fc) Returns the title of this dialog
FileView | BasicFileChooserUI.getFileView(JFileChooser fc)
void | BasicFileChooserUI.installComponents(JFileChooser fc)
protected void | BasicFileChooserUI.installDefaults(JFileChooser fc)
protected void | BasicFileChooserUI.installIcons(JFileChooser fc)
protected void | BasicFileChooserUI.installListeners(JFileChooser fc)
protected void | BasicFileChooserUI.installStrings(JFileChooser fc)
void | BasicFileChooserUI.rescanCurrentDirectory(JFileChooser fc)
void | BasicFileChooserUI.uninstallComponents(JFileChooser fc)
protected void | BasicFileChooserUI.uninstallDefaults(JFileChooser fc)
protected void | BasicFileChooserUI.uninstallIcons(JFileChooser fc)
protected void | BasicFileChooserUI.uninstallListeners(JFileChooser fc)
protected void | BasicFileChooserUI.uninstallStrings(JFileChooser fc)

Constructors in javax.swing.plaf.basic with parameters of type JFileChooser
BasicDirectoryModel(JFileChooser filechooser)
BasicFileChooserUI(JFileChooser b)

Uses of JFileChooser in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal with parameters of type JFileChooser
protected JPanel | MetalFileChooserUI.createDetailsView(JFileChooser fc)
protected MetalFileChooserUI.DirectoryComboBoxModel | MetalFileChooserUI.createDirectoryComboBoxModel(JFileChooser fc)
protected javax.swing.plaf.metal.MetalFileChooserUI.DirectoryComboBoxRenderer | MetalFileChooserUI.createDirectoryComboBoxRenderer(JFileChooser fc)
protected JPanel | MetalFileChooserUI.createList(JFileChooser fc)
ListSelectionListener | MetalFileChooserUI.createListSelectionListener(JFileChooser fc) Creates a selection listener for the list of files and directories.
PropertyChangeListener | MetalFileChooserUI.createPropertyChangeListener(JFileChooser fc)
void | MetalFileChooserUI.ensureFileIsVisible(JFileChooser fc, File f)
protected JButton | MetalFileChooserUI.getApproveButton(JFileChooser fc)
void | MetalFileChooserUI.installComponents(JFileChooser fc)
protected void | MetalFileChooserUI.installListeners(JFileChooser fc)
protected void | MetalFileChooserUI.installStrings(JFileChooser fc)
void | MetalFileChooserUI.rescanCurrentDirectory(JFileChooser fc)
void | MetalFileChooserUI.uninstallComponents(JFileChooser fc)

Constructors in javax.swing.plaf.metal with parameters of type JFileChooser
MetalFileChooserUI(JFileChooser filechooser)

Uses of JFileChooser in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi with parameters of type JFileChooser
void | MultiFileChooserUI.ensureFileIsVisible(JFileChooser a, File b) Invokes the ensureFileIsVisible method on each UI handled by this object.
FileFilter | MultiFileChooserUI.getAcceptAllFileFilter(JFileChooser a) Invokes the getAcceptAllFileFilter method on each UI handled by this object.
String | MultiFileChooserUI.getApproveButtonText(JFileChooser a) Invokes the getApproveButtonText method on each UI handled by this object.
String | MultiFileChooserUI.getDialogTitle(JFileChooser a) Invokes the getDialogTitle method on each UI handled by this object.
FileView | MultiFileChooserUI.getFileView(JFileChooser a) Invokes the getFileView method on each UI handled by this object.
void | MultiFileChooserUI.rescanCurrentDirectory(JFileChooser a) Invokes the rescanCurrentDirectory method on each UI handled by this object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JFileChooser.AccessibleJFileChooser

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JFileChooser.AccessibleJFileChooser

No usage of javax.swing.JFileChooser.AccessibleJFileChooser

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JFormattedTextField

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JFormattedTextField

Packages that use JFormattedTextField
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of JFormattedTextField in javax.swing

Methods in javax.swing that return JFormattedTextField
protected JFormattedTextField | JFormattedTextField.AbstractFormatter.getFormattedTextField() Returns the current JFormattedTextField the AbstractFormatter is installed on.
JFormattedTextField | JSpinner.DefaultEditor.getTextField() Returns the JFormattedTextField child of this editor.

Methods in javax.swing with parameters of type JFormattedTextField
abstract JFormattedTextField.AbstractFormatter | JFormattedTextField.AbstractFormatterFactory.getFormatter(JFormattedTextField tf) Returns an AbstractFormatter that can handle formatting of the passed in JFormattedTextField.
void | JFormattedTextField.AbstractFormatter.install(JFormattedTextField ftf) Installs the AbstractFormatter onto a particular JFormattedTextField.

Uses of JFormattedTextField in javax.swing.text

Methods in javax.swing.text with parameters of type JFormattedTextField
JFormattedTextField.AbstractFormatter | DefaultFormatterFactory.getFormatter(JFormattedTextField source) Returns either the default formatter, display formatter, editor formatter or null formatter based on the state of the JFormattedTextField.
void | MaskFormatter.install(JFormattedTextField ftf) Installs the DefaultFormatter onto a particular JFormattedTextField.
void | DefaultFormatter.install(JFormattedTextField ftf) Installs the DefaultFormatter onto a particular JFormattedTextField.
void | InternationalFormatter.install(JFormattedTextField ftf) Installs the DefaultFormatter onto a particular JFormattedTextField.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JFormattedTextField.AbstractFormatter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JFormattedTextField.AbstractFormatter

Packages that use JFormattedTextField.AbstractFormatter
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of JFormattedTextField.AbstractFormatter in javax.swing

Methods in javax.swing that return JFormattedTextField.AbstractFormatter
JFormattedTextField.AbstractFormatter | JFormattedTextField.getFormatter() Returns the AbstractFormatter that is used to format and parse the current value.
abstract JFormattedTextField.AbstractFormatter | JFormattedTextField.AbstractFormatterFactory.getFormatter(JFormattedTextField tf) Returns an AbstractFormatter that can handle formatting of the passed in JFormattedTextField.

Methods in javax.swing with parameters of type JFormattedTextField.AbstractFormatter
protected  void JFormattedTextField.setFormatter(JFormattedTextField.AbstractFormatter format)
Sets the current AbstractFormatter.

Constructors in javax.swing with parameters of type JFormattedTextField.AbstractFormatter
JFormattedTextField(JFormattedTextField.AbstractFormatter formatter)
Creates a JFormattedTextField with the specified AbstractFormatter.

Uses of JFormattedTextField.AbstractFormatter in javax.swing.text

Subclasses of JFormattedTextField.AbstractFormatter in javax.swing.text
class | DateFormatter DateFormatter is an InternationalFormatter that does its formatting by way of an instance of java.text.DateFormat.
class | DefaultFormatter DefaultFormatter formats aribtrary objects.
class | InternationalFormatter InternationalFormatter extends DefaultFormatter, using an instance of java.text.Format to handle the conversion to a String, and the conversion from a String.
class | MaskFormatter MaskFormatter is used to format and edit strings.
class | NumberFormatter NumberFormatter subclasses InternationalFormatter adding special behavior for numbers.

Methods in javax.swing.text that return JFormattedTextField.AbstractFormatter
JFormattedTextField.AbstractFormatter | DefaultFormatterFactory.getDefaultFormatter() Returns the JFormattedTextField.AbstractFormatter to use as a last resort, eg in case a display, edit or null JFormattedTextField.AbstractFormatter has not been specified.
JFormattedTextField.AbstractFormatter | DefaultFormatterFactory.getDisplayFormatter() Returns the JFormattedTextField.AbstractFormatter to use if the JFormattedTextField is not being edited and either the value is not-null, or the value is null and a null formatter has has not been specified.
JFormattedTextField.AbstractFormatter | DefaultFormatterFactory.getEditFormatter() Returns the JFormattedTextField.AbstractFormatter to use if the JFormattedTextField is being edited and either the value is not-null, or the value is null and a null formatter has has not been specified.
JFormattedTextField.AbstractFormatter | DefaultFormatterFactory.getFormatter(JFormattedTextField source) Returns either the default formatter, display formatter, editor formatter or null formatter based on the state of the JFormattedTextField.
JFormattedTextField.AbstractFormatter | DefaultFormatterFactory.getNullFormatter() Returns the formatter to use if the value is null.

Methods in javax.swing.text with parameters of type JFormattedTextField.AbstractFormatter
void | DefaultFormatterFactory.setDefaultFormatter(JFormattedTextField.AbstractFormatter atf) Sets the JFormattedTextField.AbstractFormatter to use as a last resort, eg in case a display, edit or null JFormattedTextField.AbstractFormatter has not been specified.
void | DefaultFormatterFactory.setDisplayFormatter(JFormattedTextField.AbstractFormatter atf) Sets the JFormattedTextField.AbstractFormatter to use if the JFormattedTextField is not being edited and either the value is not-null, or the value is null and a null formatter has has not been specified.
void | DefaultFormatterFactory.setEditFormatter(JFormattedTextField.AbstractFormatter atf) Sets the JFormattedTextField.AbstractFormatter to use if the JFormattedTextField is being edited and either the value is not-null, or the value is null and a null formatter has has not been specified.
void | DefaultFormatterFactory.setNullFormatter(JFormattedTextField.AbstractFormatter atf) Sets the formatter to use if the value of the JFormattedTextField is null.

Constructors in javax.swing.text with parameters of type JFormattedTextField.AbstractFormatter
DefaultFormatterFactory(JFormattedTextField.AbstractFormatter defaultFormat)
Creates a DefaultFormatterFactory with the specified JFormattedTextField.AbstractFormatter.
DefaultFormatterFactory(JFormattedTextField.AbstractFormatter defaultFormat, JFormattedTextField.AbstractFormatter displayFormat)
Creates a DefaultFormatterFactory with the specified JFormattedTextField.AbstractFormatters.
DefaultFormatterFactory(JFormattedTextField.AbstractFormatter defaultFormat, JFormattedTextField.AbstractFormatter displayFormat, JFormattedTextField.AbstractFormatter editFormat)
Creates a DefaultFormatterFactory with the specified JFormattedTextField.AbstractFormatters.
DefaultFormatterFactory(JFormattedTextField.AbstractFormatter defaultFormat, JFormattedTextField.AbstractFormatter displayFormat, JFormattedTextField.AbstractFormatter editFormat, JFormattedTextField.AbstractFormatter nullFormat)
Creates a DefaultFormatterFactory with the specified JFormattedTextField.AbstractFormatters.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JFormattedTextField.AbstractFormatterFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JFormattedTextField.AbstractFormatterFactory

Packages that use JFormattedTextField.AbstractFormatterFactory
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of JFormattedTextField.AbstractFormatterFactory in javax.swing

Methods in javax.swing that return JFormattedTextField.AbstractFormatterFactory
 JFormattedTextField.AbstractFormatterFactory JFormattedTextField.getFormatterFactory()
Returns the current AbstractFormatterFactory.

Methods in javax.swing with parameters of type JFormattedTextField.AbstractFormatterFactory
 void JFormattedTextField.setFormatterFactory(JFormattedTextField.AbstractFormatterFactory tf)
Sets the AbstractFormatterFactory.

Constructors in javax.swing with parameters of type JFormattedTextField.AbstractFormatterFactory
JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory)
Creates a JFormattedTextField with the specified AbstractFormatterFactory.
JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory, Object currentValue)
Creates a JFormattedTextField with the specified AbstractFormatterFactory and initial value.

Uses of JFormattedTextField.AbstractFormatterFactory in javax.swing.text

Subclasses of JFormattedTextField.AbstractFormatterFactory in javax.swing.text
 class DefaultFormatterFactory
An implementation of JFormattedTextField.AbstractFormatterFactory.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JFrame

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JFrame

Packages that use JFrame
java.awt.im.spi | Provides interfaces that enable the development of input methods that can be used with any Java runtime environment.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of JFrame in java.awt.im.spi

Methods in java.awt.im.spi that return JFrame
 JFrame InputMethodContext.createInputMethodJFrame(String title, boolean attachToInputContext)
Creates a top-level Swing JFrame for use by the input method.

Uses of JFrame in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic that return JFrame
protected  JFrame BasicToolBarUI.createFloatingFrame(JToolBar toolbar)
No longer used, use BasicToolBarUI.createFloatingWindow(JToolBar)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JFrame.AccessibleJFrame

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JFrame.AccessibleJFrame

No usage of javax.swing.JFrame.AccessibleJFrame

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JInternalFrame

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JInternalFrame

Packages that use JInternalFrame
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of JInternalFrame in javax.swing

Methods in javax.swing that return JInternalFrame
JInternalFrame | JOptionPane.createInternalFrame(Component parentComponent, String title) Creates and returns an instance of JInternalFrame.
JInternalFrame[] | JDesktopPane.getAllFrames() Returns all JInternalFrames currently displayed in the desktop.
JInternalFrame[] | JDesktopPane.getAllFramesInLayer(int layer) Returns all JInternalFrames currently displayed in the specified layer of the desktop.
JInternalFrame | JInternalFrame.JDesktopIcon.getInternalFrame() Returns the JInternalFrame that this DesktopIcon is associated with.
JInternalFrame | JDesktopPane.getSelectedFrame() Returns the currently active JInternalFrame in this JDesktopPane, or null if no JInternalFrame is currently active.
JInternalFrame | JDesktopPane.selectFrame(boolean forward) Selects the next JInternalFrame in this desktop pane.

Methods in javax.swing with parameters of type JInternalFrame
 void DefaultDesktopManager.activateFrame(JInternalFrame f)
This will activate f moving it to the front.
 void DesktopManager.activateFrame(JInternalFrame f)
Generally, indicate that this frame has focus.
 void DefaultDesktopManager.closeFrame(JInternalFrame f)
Removes the frame, and, if necessary, the desktopIcon, from its parent.
 void DesktopManager.closeFrame(JInternalFrame f)
Generally, this call should remove the frame from it's parent.
 void DefaultDesktopManager.deactivateFrame(JInternalFrame f)
 void DesktopManager.deactivateFrame(JInternalFrame f)
Generally, indicate that this frame has lost focus.
 void DefaultDesktopManager.deiconifyFrame(JInternalFrame f)
Removes the desktopIcon from its parent and adds its frame to the parent.
 void DesktopManager.deiconifyFrame(JInternalFrame f)
Generally, remove any iconic representation that is present and restore the frame to it's original size and location.
protected  Rectangle DefaultDesktopManager.getBoundsForIconOf(JInternalFrame f)
The iconifyFrame() code calls this to determine the proper bounds for the desktopIcon.
 Component InternalFrameFocusTraversalPolicy.getInitialComponent(JInternalFrame frame)
Returns the Component that should receive the focus when a JInternalFrame is selected for the first time.
protected  Rectangle DefaultDesktopManager.getPreviousBounds(JInternalFrame f)
Gets the normal bounds of the component prior to the component being maximized.
 void DefaultDesktopManager.iconifyFrame(JInternalFrame f)
Removes the frame from its parent and adds its desktopIcon to the parent.
 void DesktopManager.iconifyFrame(JInternalFrame f)
Generally, remove this frame from it's parent and add an iconic representation.
 void DefaultDesktopManager.maximizeFrame(JInternalFrame f)
Resizes the frame to fill its parents bounds.
 void DesktopManager.maximizeFrame(JInternalFrame f)
Generally, the frame should be resized to match it's parents bounds.
 void DefaultDesktopManager.minimizeFrame(JInternalFrame f)
Restores the frame back to its size and position prior to a maximizeFrame call.
 void DesktopManager.minimizeFrame(JInternalFrame f)
Generally, this indicates that the frame should be restored to it's size and position prior to a maximizeFrame() call.
 void DefaultDesktopManager.openFrame(JInternalFrame f)
Normally this method will not be called.
 void DesktopManager.openFrame(JInternalFrame f)
If possible, display this frame in an appropriate location.
protected  void DefaultDesktopManager.removeIconFor(JInternalFrame f)
Convenience method to remove the desktopIcon of f is necessary.
 void JInternalFrame.JDesktopIcon.setInternalFrame(JInternalFrame f)
Sets the JInternalFrame with which this DesktopIcon is associated.
protected  void DefaultDesktopManager.setPreviousBounds(JInternalFrame f, Rectangle r)
Stores the bounds of the component just before a maximize call.
 void JDesktopPane.setSelectedFrame(JInternalFrame f)
Sets the currently active JInternalFrame in this JDesktopPane.
protected  void DefaultDesktopManager.setWasIcon(JInternalFrame f, Boolean value)
Sets that the component has been iconized and the bounds of the desktopIcon are valid.
protected  boolean DefaultDesktopManager.wasIcon(JInternalFrame f)
Returns true if the component has been iconized and the bounds of the desktopIcon are valid, otherwise returns false.

Constructors in javax.swing with parameters of type JInternalFrame
JInternalFrame.JDesktopIcon(JInternalFrame f)
Creates an icon for an internal frame.

Uses of JInternalFrame in javax.swing.event

Methods in javax.swing.event that return JInternalFrame
 JInternalFrame InternalFrameEvent.getInternalFrame()
Returns the originator of the event.

Constructors in javax.swing.event with parameters of type JInternalFrame
InternalFrameEvent(JInternalFrame source, int id)
Constructs an InternalFrameEvent object.

Uses of JInternalFrame in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JInternalFrame
protected JInternalFrame | BasicInternalFrameTitlePane.frame
protected JInternalFrame | BasicInternalFrameUI.frame
protected JInternalFrame | BasicDesktopIconUI.frame

Methods in javax.swing.plaf.basic with parameters of type JInternalFrame
protected void | BasicInternalFrameUI.activateFrame(JInternalFrame f) This method is called when the frame becomes selected.
protected void | BasicInternalFrameUI.closeFrame(JInternalFrame f) This method is called when the user wants to close the frame.
protected MouseInputAdapter | BasicInternalFrameUI.createBorderListener(JInternalFrame w)
protected JComponent | BasicInternalFrameUI.createEastPane(JInternalFrame w)
protected JComponent | BasicInternalFrameUI.createNorthPane(JInternalFrame w)
protected JComponent | BasicInternalFrameUI.createSouthPane(JInternalFrame w)
protected JComponent | BasicInternalFrameUI.createWestPane(JInternalFrame w)
protected void | BasicInternalFrameUI.deactivateFrame(JInternalFrame f) This method is called when the frame is no longer selected.
protected void | BasicInternalFrameUI.deiconifyFrame(JInternalFrame f) This method is called when the user wants to deiconify the frame.
protected void | BasicInternalFrameUI.iconifyFrame(JInternalFrame f) This method is called when the user wants to iconify the frame.
protected void | BasicInternalFrameUI.maximizeFrame(JInternalFrame f) This method is called when the user wants to maximize the frame.
protected void | BasicInternalFrameUI.minimizeFrame(JInternalFrame f) This method is called when the user wants to minimize the frame.
protected void | BasicInternalFrameTitlePane.postClosingEvent(JInternalFrame frame) Post a WINDOW_CLOSING-like event to the frame, so that it can be treated like a regular Frame.

Constructors in javax.swing.plaf.basic with parameters of type JInternalFrame
BasicInternalFrameTitlePane(JInternalFrame f)
BasicInternalFrameUI(JInternalFrame b)

Uses of JInternalFrame in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal with parameters of type JInternalFrame
protected MouseInputAdapter | MetalInternalFrameUI.createBorderListener(JInternalFrame w) Returns the MouseInputAdapter that will be installed on the TitlePane.
protected JComponent | MetalInternalFrameUI.createNorthPane(JInternalFrame w)

Constructors in javax.swing.plaf.metal with parameters of type JInternalFrame
MetalInternalFrameTitlePane(JInternalFrame f)
MetalInternalFrameUI(JInternalFrame b)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JInternalFrame.AccessibleJInternalFrame

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JInternalFrame.AccessibleJInternalFrame

No usage of javax.swing.JInternalFrame.AccessibleJInternalFrame

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JInternalFrame.JDesktopIcon

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JInternalFrame.JDesktopIcon

Packages that use JInternalFrame.JDesktopIcon
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of JInternalFrame.JDesktopIcon in javax.swing

Fields in javax.swing declared as JInternalFrame.JDesktopIcon
protected  JInternalFrame.JDesktopIcon JInternalFrame.desktopIcon
The icon that is displayed when this internal frame is iconified.

Methods in javax.swing that return JInternalFrame.JDesktopIcon
 JInternalFrame.JDesktopIcon JInternalFrame.getDesktopIcon()
Returns the JDesktopIcon used when this JInternalFrame is iconified.

Methods in javax.swing with parameters of type JInternalFrame.JDesktopIcon
 void JInternalFrame.setDesktopIcon(JInternalFrame.JDesktopIcon d)
Sets the JDesktopIcon associated with this JInternalFrame.

Uses of JInternalFrame.JDesktopIcon in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JInternalFrame.JDesktopIcon
protected  JInternalFrame.JDesktopIcon BasicDesktopIconUI.desktopIcon

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JInternalFrame.JDesktopIcon.AccessibleJDesktopIcon

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JInternalFrame.JDesktopIcon.AccessibleJDesktopIcon

No usage of javax.swing.JInternalFrame.JDesktopIcon.AccessibleJDesktopIcon

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JLabel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JLabel

Packages that use JLabel
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of JLabel in javax.swing

Subclasses of JLabel in javax.swing
class | DefaultListCellRenderer Renders an item in a list.
static class | DefaultListCellRenderer.UIResource A subclass of DefaultListCellRenderer that implements UIResource.

Uses of JLabel in javax.swing.plaf.basic

Subclasses of JLabel in javax.swing.plaf.basic
class | BasicComboBoxRenderer ComboBox renderer
static class | BasicComboBoxRenderer.UIResource A subclass of BasicComboBoxRenderer that implements UIResource.

Methods in javax.swing.plaf.basic with parameters of type JLabel
protected  void BasicLabelUI.installComponents(JLabel c)
protected  void BasicLabelUI.installDefaults(JLabel c)
protected  void BasicLabelUI.installKeyboardActions(JLabel l)
protected  void BasicLabelUI.installListeners(JLabel c)
protected  String BasicLabelUI.layoutCL(JLabel label, FontMetrics fontMetrics, String text, Icon icon, Rectangle viewR, Rectangle iconR, Rectangle textR)
Forwards the call to SwingUtilities.layoutCompoundLabel().
protected  void BasicLabelUI.paintDisabledText(JLabel l, Graphics g, String s, int textX, int textY)
Paint clippedText at textX, textY with background.lighter() and then shifted down and to the right by one pixel with background.darker().
protected  void BasicLabelUI.paintEnabledText(JLabel l, Graphics g, String s, int textX, int textY)
Paint clippedText at textX, textY with the labels foreground color.
protected  void BasicLabelUI.uninstallComponents(JLabel c)
protected  void BasicLabelUI.uninstallDefaults(JLabel c)
protected  void BasicLabelUI.uninstallKeyboardActions(JLabel c)
protected  void BasicLabelUI.uninstallListeners(JLabel c)

Uses of JLabel in javax.swing.plaf.metal

Subclasses of JLabel in javax.swing.plaf.metal
protected class | MetalFileChooserUI.FileRenderer
class | MetalFileChooserUI.FilterComboBoxRenderer Render different type sizes and styles.

Methods in javax.swing.plaf.metal with parameters of type JLabel
protected  void MetalLabelUI.paintDisabledText(JLabel l, Graphics g, String s, int textX, int textY)
Just paint the text gray (Label.disabledForeground) rather than in the labels foreground color.

Uses of JLabel in javax.swing.table

Subclasses of JLabel in javax.swing.table
class | DefaultTableCellRenderer The standard class for rendering (displaying) individual cells in a JTable.
static class | DefaultTableCellRenderer.UIResource A subclass of DefaultTableCellRenderer that implements UIResource.

Uses of JLabel in javax.swing.tree

Subclasses of JLabel in javax.swing.tree
 class DefaultTreeCellRenderer
Displays an entry in a tree.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JLabel.AccessibleJLabel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JLabel.AccessibleJLabel

No usage of javax.swing.JLabel.AccessibleJLabel

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JLayeredPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JLayeredPane

Packages that use JLayeredPane
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JLayeredPane in javax.swing

Subclasses of JLayeredPane in javax.swing
 class JDesktopPane
A container used to create a multiple-document interface or a virtual desktop.

Fields in javax.swing declared as JLayeredPane
protected  JLayeredPane JRootPane.layeredPane
The layered pane that manages the menu bar and content pane.

Methods in javax.swing that return JLayeredPane
protected JLayeredPane | JRootPane.createLayeredPane() Called by the constructor methods to create the default layeredPane.
JLayeredPane | JInternalFrame.getLayeredPane() Returns the layered pane for this internal frame.
JLayeredPane | JDialog.getLayeredPane() Returns the layeredPane object for this dialog.
JLayeredPane | JApplet.getLayeredPane() Returns the layeredPane object for this applet.
JLayeredPane | JWindow.getLayeredPane() Returns the layeredPane object for this window.
JLayeredPane | JRootPane.getLayeredPane() Gets the layered pane used by the root pane.
JLayeredPane | JFrame.getLayeredPane() Returns the layeredPane object for this frame.
JLayeredPane | RootPaneContainer.getLayeredPane() Returns the layeredPane.
static JLayeredPane | JLayeredPane.getLayeredPaneAbove(Component c) Convenience method that returns the first JLayeredPane which contains the specified component.

Methods in javax.swing with parameters of type JLayeredPane
void | JInternalFrame.setLayeredPane(JLayeredPane layered) Sets this JInternalFrame's layeredPane property.
void | JDialog.setLayeredPane(JLayeredPane layeredPane) Sets the layeredPane property.
void | JApplet.setLayeredPane(JLayeredPane layeredPane) Sets the layeredPane property.
void | JWindow.setLayeredPane(JLayeredPane layeredPane) Sets the layeredPane property.
void | JRootPane.setLayeredPane(JLayeredPane layered) Sets the layered pane for the root pane.
void | JFrame.setLayeredPane(JLayeredPane layeredPane) Sets the layeredPane property.
void | RootPaneContainer.setLayeredPane(JLayeredPane layeredPane) A Container that manages the contentPane and in some cases a menu bar.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JLayeredPane.AccessibleJLayeredPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JLayeredPane.AccessibleJLayeredPane

No usage of javax.swing.JLayeredPane.AccessibleJLayeredPane

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JList

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JList

Packages that use JList
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of JList in javax.swing

Methods in javax.swing with parameters of type JList
Component | DefaultListCellRenderer.getListCellRendererComponent(JList list, Object value, int index, boolean isSelected, boolean cellHasFocus)
Component | ListCellRenderer.getListCellRendererComponent(JList list, Object value, int index, boolean isSelected, boolean cellHasFocus) Return a component that has been configured to display the specified value.

Constructors in javax.swing with parameters of type JList
JList.AccessibleJList.AccessibleJListChild(JList parent, int indexInParent)

Uses of JList in javax.swing.plaf

Methods in javax.swing.plaf with parameters of type JList
abstract Rectangle | ListUI.getCellBounds(JList list, int index1, int index2) Returns the bounding rectangle, in the given list's coordinate system, for the range of cells specified by the two indices.
abstract Point | ListUI.indexToLocation(JList list, int index) Returns the origin in the given JList, of the specified item, in the list's coordinate system.
abstract int | ListUI.locationToIndex(JList list, Point location) Returns the cell index in the specified JList closest to the given location in the list's coordinate system.

Uses of JList in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JList
protected JList | BasicListUI.list
protected JList | BasicComboPopup.list This protected field is implementation specific.
protected JList | BasicComboBoxUI.listBox

Methods in javax.swing.plaf.basic that return JList
protected  JList BasicComboPopup.createList()
Creates the JList used in the popup to display the items in the combo box model.
 JList BasicComboPopup.getList()
Implementation of ComboPopup.getList().
 JList ComboPopup.getList()
Returns the list that is being used to draw the items in the combo box.

Methods in javax.swing.plaf.basic with parameters of type JList
protected MouseListener | BasicFileChooserUI.createDoubleClickListener(JFileChooser fc, JList list)
Rectangle | BasicListUI.getCellBounds(JList list, int index1, int index2) Returns the bounding rectangle, in the given list's coordinate system, for the range of cells specified by the two indices.
Component | BasicComboBoxRenderer.getListCellRendererComponent(JList list, Object value, int index, boolean isSelected, boolean cellHasFocus)
Point | BasicListUI.indexToLocation(JList list, int index) Returns the origin in the given JList, of the specified item, in the list's coordinate system.
int | BasicListUI.locationToIndex(JList list, Point location) Returns the cell index in the specified JList closest to the given location in the list's coordinate system.

Constructors in javax.swing.plaf.basic with parameters of type JList
BasicFileChooserUI.DoubleClickListener(JList list)

Uses of JList in javax.swing.plaf.metal

Fields in javax.swing.plaf.metal declared as JList
protected  JList MetalComboBoxButton.listBox

Methods in javax.swing.plaf.metal with parameters of type JList
 Component MetalFileChooserUI.FilterComboBoxRenderer.getListCellRendererComponent(JList list, Object value, int index, boolean isSelected, boolean cellHasFocus)

Constructors in javax.swing.plaf.metal with parameters of type JList
MetalComboBoxButton(JComboBox cb, Icon i, boolean onlyIcon, CellRendererPane pane, JList list)
MetalComboBoxButton(JComboBox cb, Icon i, CellRendererPane pane, JList list)
MetalFileChooserUI.SingleClickListener(JList list)

Uses of JList in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi with parameters of type JList
Rectangle | MultiListUI.getCellBounds(JList a, int b, int c) Invokes the getCellBounds method on each UI handled by this object.
Point | MultiListUI.indexToLocation(JList a, int b) Invokes the indexToLocation method on each UI handled by this object.
int | MultiListUI.locationToIndex(JList a, Point b) Invokes the locationToIndex method on each UI handled by this object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JList.AccessibleJList

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JList.AccessibleJList

No usage of javax.swing.JList.AccessibleJList

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JList.AccessibleJList.AccessibleJListChild

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JList.AccessibleJList.AccessibleJListChild

No usage of javax.swing.JList.AccessibleJList.AccessibleJListChild

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JList.DropLocation

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JList.DropLocation

Packages that use JList.DropLocation
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JList.DropLocation in javax.swing

Methods in javax.swing that return JList.DropLocation
 JList.DropLocation JList.getDropLocation()
Returns the location that this component should visually indicate as the drop location during a DnD operation over the component, or null if no location is to currently be shown.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JMenu

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JMenu

Packages that use JMenu
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of JMenu in javax.swing

Methods in javax.swing that return JMenu
JMenu | JMenuBar.add(JMenu c) Appends the specified menu to the end of the menu bar.
JMenu | JMenuBar.getHelpMenu() Gets the help menu for the menu bar.
JMenu | JMenuBar.getMenu(int index) Returns the menu at the specified position in the menu bar.

Methods in javax.swing with parameters of type JMenu
JMenu | JMenuBar.add(JMenu c) Appends the specified menu to the end of the menu bar.
void | JMenuBar.setHelpMenu(JMenu menu) Sets the help menu that appears when the user selects the "help" option in the menu bar.

Uses of JMenu in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JMenu
JMenu | BasicMenuUI.ChangeHandler.menu
protected JMenu | BasicInternalFrameTitlePane.windowMenu

Methods in javax.swing.plaf.basic that return JMenu
protected  JMenu BasicInternalFrameTitlePane.createSystemMenu()

Methods in javax.swing.plaf.basic with parameters of type JMenu
protected void | BasicInternalFrameTitlePane.addSystemMenuItems(JMenu systemMenu)
protected void | BasicMenuUI.setupPostTimer(JMenu menu)

Constructors in javax.swing.plaf.basic with parameters of type JMenu
BasicMenuUI.ChangeHandler(JMenu m, BasicMenuUI ui)

Uses of JMenu in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal with parameters of type JMenu
protected  void MetalInternalFrameTitlePane.addSystemMenuItems(JMenu systemMenu)
Override the parent's method to do nothing.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JMenu.AccessibleJMenu

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JMenu.AccessibleJMenu

No usage of javax.swing.JMenu.AccessibleJMenu

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JMenu.WinListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JMenu.WinListener

Packages that use JMenu.WinListener
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JMenu.WinListener in javax.swing

Fields in javax.swing declared as JMenu.WinListener
protected  JMenu.WinListener JMenu.popupListener
The window-closing listener for the popup.

Methods in javax.swing that return JMenu.WinListener
protected  JMenu.WinListener JMenu.createWinListener(JPopupMenu p)
Creates a window-closing listener for the popup.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JMenuBar

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JMenuBar

Packages that use JMenuBar
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of JMenuBar in javax.swing

Fields in javax.swing declared as JMenuBar
protected  JMenuBar JRootPane.menuBar
The menu bar.

Methods in javax.swing that return JMenuBar
 JMenuBar JInternalFrame.getJMenuBar()
Returns the current JMenuBar for this JInternalFrame, or null if no menu bar has been set.
 JMenuBar JDialog.getJMenuBar()
Returns the menubar set on this dialog.
 JMenuBar JApplet.getJMenuBar()
Returns the menubar set on this applet.
 JMenuBar JRootPane.getJMenuBar()
Returns the menu bar from the layered pane.
 JMenuBar JFrame.getJMenuBar()
Returns the menubar set on this frame.
 JMenuBar JInternalFrame.getMenuBar()
Deprecated. As of Swing version 1.0.3, replaced by getJMenuBar().
 JMenuBar JRootPane.getMenuBar()
Deprecated. As of Swing version 1.0.3 replaced by getJMenuBar().

Methods in javax.swing with parameters of type JMenuBar
void | JInternalFrame.setJMenuBar(JMenuBar m) Sets the menuBar property for this JInternalFrame.
void | JDialog.setJMenuBar(JMenuBar menu) Sets the menubar for this dialog.
void | JApplet.setJMenuBar(JMenuBar menuBar) Sets the menubar for this applet.
void | JRootPane.setJMenuBar(JMenuBar menu) Adds or changes the menu bar used in the layered pane.
void | JFrame.setJMenuBar(JMenuBar menubar) Sets the menubar for this frame.
void | JInternalFrame.setMenuBar(JMenuBar m) Deprecated. As of Swing version 1.0.3 replaced by setJMenuBar(JMenuBar m).
void | JRootPane.setMenuBar(JMenuBar menu) Deprecated. As of Swing version 1.0.3 replaced by setJMenuBar(JMenuBar menu).

Uses of JMenuBar in javax.swing.plaf.basic

Subclasses of JMenuBar in javax.swing.plaf.basic
 class BasicInternalFrameTitlePane.SystemMenuBar
This class should be treated as a "protected" inner class.

Fields in javax.swing.plaf.basic declared as JMenuBar
protected JMenuBar | BasicMenuBarUI.menuBar
protected JMenuBar | BasicInternalFrameTitlePane.menuBar

Methods in javax.swing.plaf.basic that return JMenuBar
protected  JMenuBar BasicInternalFrameTitlePane.createSystemMenuBar()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JMenuBar.AccessibleJMenuBar

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JMenuBar.AccessibleJMenuBar

No usage of javax.swing.JMenuBar.AccessibleJMenuBar

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JMenuItem

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JMenuItem

Packages that use JMenuItem
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of JMenuItem in javax.swing

Subclasses of JMenuItem in javax.swing
class | JCheckBoxMenuItem A menu item that can be selected or deselected.
class | JMenu An implementation of a menu -- a popup window containing JMenuItems that is displayed when the user selects an item on the JMenuBar.
class | JRadioButtonMenuItem An implementation of a radio button menu item.

Methods in javax.swing that return JMenuItem
JMenuItem | JPopupMenu.add(Action a) Appends a new menu item to the end of the menu which dispatches the specified Action object.
JMenuItem | JMenu.add(Action a) Creates a new menu item attached to the specified Action object and appends it to the end of this menu.
JMenuItem | JPopupMenu.add(JMenuItem menuItem) Appends the specified menu item to the end of this menu.
JMenuItem | JMenu.add(JMenuItem menuItem) Appends a menu item to the end of this menu.
JMenuItem | JPopupMenu.add(String s) Creates a new menu item with the specified text and appends it to the end of this menu.
JMenuItem | JMenu.add(String s) Creates a new menu item with the specified text and appends it to the end of this menu.
protected JMenuItem | JPopupMenu.createActionComponent(Action a) Factory method which creates the JMenuItem for Actions added to the JPopupMenu.
protected JMenuItem | JMenu.createActionComponent(Action a) Factory method which creates the JMenuItem for Actions added to the JMenu.
JMenuItem | JMenu.getItem(int pos) Returns the JMenuItem at the specified position.
JMenuItem | JMenu.insert(Action a, int pos) Inserts a new menu item attached to the specified Action object at a given position.
JMenuItem | JMenu.insert(JMenuItem mi, int pos) Inserts the specified JMenuitem at a given position.

Methods in javax.swing with parameters of type JMenuItem
JMenuItem | JPopupMenu.add(JMenuItem menuItem) Appends the specified menu item to the end of this menu.
JMenuItem | JMenu.add(JMenuItem menuItem) Appends a menu item to the end of this menu.
protected PropertyChangeListener | JPopupMenu.createActionChangeListener(JMenuItem b) Returns a properly configured PropertyChangeListener which updates the control as changes to the Action occur.
protected PropertyChangeListener | JMenu.createActionChangeListener(JMenuItem b) Returns a properly configured PropertyChangeListener which updates the control as changes to the Action occur.
JMenuItem | JMenu.insert(JMenuItem mi, int pos) Inserts the specified JMenuitem at a given position.
void | JMenu.remove(JMenuItem item) Removes the specified menu item from this menu.

Uses of JMenuItem in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JMenuItem
protected  JMenuItem BasicMenuItemUI.menuItem

Methods in javax.swing.plaf.basic with parameters of type JMenuItem
protected void | BasicMenuItemUI.installComponents(JMenuItem menuItem)
protected void | BasicMenuItemUI.paintBackground(Graphics g, JMenuItem menuItem, Color bgColor) Draws the background of the menu item.
protected void | BasicMenuItemUI.paintText(Graphics g, JMenuItem menuItem, Rectangle textRect, String text) Renders the text of the current menu item.
void | BasicRadioButtonMenuItemUI.processMouseEvent(JMenuItem item, MouseEvent e, MenuElement[] path, MenuSelectionManager manager)
void | BasicCheckBoxMenuItemUI.processMouseEvent(JMenuItem item, MouseEvent e, MenuElement[] path, MenuSelectionManager manager)
protected void | BasicMenuItemUI.uninstallComponents(JMenuItem menuItem)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JMenuItem.AccessibleJMenuItem

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JMenuItem.AccessibleJMenuItem

Packages that use JMenuItem.AccessibleJMenuItem
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JMenuItem.AccessibleJMenuItem in javax.swing

Subclasses of JMenuItem.AccessibleJMenuItem in javax.swing
protected class | JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem This class implements accessibility support for the JCheckBoxMenuItem class.
protected class | JMenu.AccessibleJMenu This class implements accessibility support for the JMenu class.
protected class | JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem This class implements accessibility support for the JRadioButtonMenuItem class.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JOptionPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JOptionPane

Packages that use JOptionPane
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of JOptionPane in javax.swing.plaf

Methods in javax.swing.plaf with parameters of type JOptionPane
abstract boolean | OptionPaneUI.containsCustomComponents(JOptionPane op) Returns true if the user has supplied instances of Component for either the options or message.
abstract void | OptionPaneUI.selectInitialValue(JOptionPane op) Requests the component representing the default value to have focus.

Uses of JOptionPane in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JOptionPane
protected  JOptionPane BasicOptionPaneUI.optionPane
JOptionPane that the receiver is providing the look and feel for.

Methods in javax.swing.plaf.basic with parameters of type JOptionPane
boolean | BasicOptionPaneUI.containsCustomComponents(JOptionPane op) Returns true if in the last call to validateComponent the message or buttons contained a subclass of Component.
void | BasicOptionPaneUI.selectInitialValue(JOptionPane op) If inputComponent is non-null, the focus is requested on that, otherwise request focus on the default value

Uses of JOptionPane in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi with parameters of type JOptionPane
boolean | MultiOptionPaneUI.containsCustomComponents(JOptionPane a) Invokes the containsCustomComponents method on each UI handled by this object.
void | MultiOptionPaneUI.selectInitialValue(JOptionPane a) Invokes the selectInitialValue method on each UI handled by this object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JOptionPane.AccessibleJOptionPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JOptionPane.AccessibleJOptionPane

No usage of javax.swing.JOptionPane.AccessibleJOptionPane

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JPanel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JPanel

Packages that use JPanel
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.colorchooser | Contains classes and interfaces used by the JColorChooser component.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of JPanel in javax.swing

Subclasses of JPanel in javax.swing
static class | JSpinner.DateEditor An editor for a JSpinner whose model is a SpinnerDateModel.
static class | JSpinner.DefaultEditor A simple base class for more specialized editors that displays a read-only view of the model's current value with a JFormattedTextField.
static class | JSpinner.ListEditor An editor for a JSpinner whose model is a SpinnerListModel.
static class | JSpinner.NumberEditor An editor for a JSpinner whose model is a SpinnerNumberModel.

Uses of JPanel in javax.swing.colorchooser

Subclasses of JPanel in javax.swing.colorchooser
 class AbstractColorChooserPanel
This is the abstract superclass for color choosers.

Uses of JPanel in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic that return JPanel
 JPanel BasicFileChooserUI.getAccessoryPanel()

Methods in javax.swing.plaf.basic with parameters of type JPanel
protected void | BasicPanelUI.installDefaults(JPanel p)
protected void | BasicPanelUI.uninstallDefaults(JPanel p)

Uses of JPanel in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal that return JPanel
protected JPanel | MetalFileChooserUI.createDetailsView(JFileChooser fc)
protected JPanel | MetalFileChooserUI.createList(JFileChooser fc)
protected JPanel | MetalFileChooserUI.getBottomPanel()
protected JPanel | MetalFileChooserUI.getButtonPanel()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JPanel.AccessibleJPanel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JPanel.AccessibleJPanel

No usage of javax.swing.JPanel.AccessibleJPanel

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JPasswordField

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JPasswordField

No usage of javax.swing.JPasswordField

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JPasswordField.AccessibleJPasswordField

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JPasswordField.AccessibleJPasswordField

No usage of javax.swing.JPasswordField.AccessibleJPasswordField

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JPopupMenu

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JPopupMenu

Packages that use JPopupMenu
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of JPopupMenu in javax.swing

Methods in javax.swing that return JPopupMenu
JPopupMenu | JComponent.getComponentPopupMenu() Returns JPopupMenu that assigned for this component.
JPopupMenu | JMenu.getPopupMenu() Returns the popupmenu associated with this menu.

Methods in javax.swing with parameters of type JPopupMenu
protected JMenu.WinListener | JMenu.createWinListener(JPopupMenu p) Creates a window-closing listener for the popup.
void | JComponent.setComponentPopupMenu(JPopupMenu popup) Sets the JPopupMenu for this JComponent.

Constructors in javax.swing with parameters of type JPopupMenu
JMenu.WinListener(JPopupMenu p)
Create the window listener for the specified popup.

Uses of JPopupMenu in javax.swing.plaf

Methods in javax.swing.plaf with parameters of type JPopupMenu
 Popup PopupMenuUI.getPopup(JPopupMenu popup, int x, int y)
Returns the Popup that will be responsible for displaying the JPopupMenu.

Uses of JPopupMenu in javax.swing.plaf.basic

Subclasses of JPopupMenu in javax.swing.plaf.basic
 class BasicComboPopup
This is a basic implementation of the ComboPopup interface.

Fields in javax.swing.plaf.basic declared as JPopupMenu
protected  JPopupMenu BasicPopupMenuUI.popupMenu

Uses of JPopupMenu in javax.swing.plaf.metal

Subclasses of JPopupMenu in javax.swing.plaf.metal
 class MetalComboBoxUI.MetalComboPopup
Deprecated. As of Java 2 platform v1.4.

Uses of JPopupMenu in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi with parameters of type JPopupMenu
 Popup MultiPopupMenuUI.getPopup(JPopupMenu a, int b, int c)
Invokes the getPopup method on each UI handled by this object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JPopupMenu.AccessibleJPopupMenu

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JPopupMenu.AccessibleJPopupMenu

No usage of javax.swing.JPopupMenu.AccessibleJPopupMenu

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JPopupMenu.Separator

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JPopupMenu.Separator

No usage of javax.swing.JPopupMenu.Separator

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JProgressBar

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JProgressBar

Packages that use JProgressBar
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of JProgressBar in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JProgressBar
protected  JProgressBar BasicProgressBarUI.progressBar

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JProgressBar.AccessibleJProgressBar

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JProgressBar.AccessibleJProgressBar

No usage of javax.swing.JProgressBar.AccessibleJProgressBar

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JRadioButton

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JRadioButton

No usage of javax.swing.JRadioButton

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JRadioButton.AccessibleJRadioButton

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JRadioButton.AccessibleJRadioButton

No usage of javax.swing.JRadioButton.AccessibleJRadioButton

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JRadioButtonMenuItem

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JRadioButtonMenuItem

No usage of javax.swing.JRadioButtonMenuItem

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem

No usage of javax.swing.JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JRootPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JRootPane

Packages that use JRootPane
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of JRootPane in javax.swing

Fields in javax.swing declared as JRootPane
protected JRootPane | JInternalFrame.rootPane The JRootPane instance that manages the content pane and optional menu bar for this internal frame, as well as the glass pane.
protected JRootPane | JDialog.rootPane
protected JRootPane | JApplet.rootPane
protected JRootPane | JWindow.rootPane The JRootPane instance that manages the contentPane and optional menuBar for this frame, as well as the glassPane.
protected JRootPane | JFrame.rootPane The JRootPane instance that manages the contentPane and optional menuBar for this frame, as well as the glassPane.

Methods in javax.swing that return JRootPane
protected JRootPane | JInternalFrame.createRootPane() Called by the constructor to set up the JRootPane.
protected JRootPane | JDialog.createRootPane() Called by the constructor methods to create the default rootPane.
protected JRootPane | JApplet.createRootPane() Called by the constructor methods to create the default rootPane.
protected JRootPane | JWindow.createRootPane() Called by the constructor methods to create the default rootPane.
protected JRootPane | JFrame.createRootPane() Called by the constructor methods to create the default rootPane.
JRootPane | JInternalFrame.getRootPane() Returns the rootPane object for this internal frame.
JRootPane | JDialog.getRootPane() Returns the rootPane object for this dialog.
JRootPane | JApplet.getRootPane() Returns the rootPane object for this applet.
JRootPane | JWindow.getRootPane() Returns the rootPane object for this window.
JRootPane | JComponent.getRootPane() Returns the JRootPane ancestor for this component.
JRootPane | JFrame.getRootPane() Returns the rootPane object for this frame.
JRootPane | RootPaneContainer.getRootPane() Return this component's single JRootPane child.
static JRootPane | SwingUtilities.getRootPane(Component c) If c is a JRootPane descendant return its JRootPane ancestor.

Methods in javax.swing with parameters of type JRootPane
protected void | JInternalFrame.setRootPane(JRootPane root) Sets the rootPane property for this JInternalFrame.
protected void | JDialog.setRootPane(JRootPane root) Sets the rootPane property.
protected void | JApplet.setRootPane(JRootPane root) Sets the rootPane property.
protected void | JWindow.setRootPane(JRootPane root) Sets the new rootPane object for this window.
protected void | JFrame.setRootPane(JRootPane root) Sets the rootPane property.

Uses of JRootPane in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic with parameters of type JRootPane
protected void | BasicRootPaneUI.installComponents(JRootPane root)
protected void | BasicRootPaneUI.installDefaults(JRootPane c)
protected void | BasicRootPaneUI.installKeyboardActions(JRootPane root)
protected void | BasicRootPaneUI.installListeners(JRootPane root)
protected void | BasicRootPaneUI.uninstallComponents(JRootPane root)
protected void | BasicRootPaneUI.uninstallDefaults(JRootPane root)
protected void | BasicRootPaneUI.uninstallKeyboardActions(JRootPane root)
protected void | BasicRootPaneUI.uninstallListeners(JRootPane root)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JRootPane.AccessibleJRootPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JRootPane.AccessibleJRootPane

No usage of javax.swing.JRootPane.AccessibleJRootPane

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JRootPane.RootLayout

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JRootPane.RootLayout

No usage of javax.swing.JRootPane.RootLayout

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JScrollBar

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JScrollBar

Packages that use JScrollBar
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of JScrollBar in javax.swing

Subclasses of JScrollBar in javax.swing
protected  class JScrollPane.ScrollBar
By default JScrollPane creates scrollbars that are instances of this class.

Fields in javax.swing declared as JScrollBar
protected JScrollBar | JScrollPane.horizontalScrollBar The scrollpane's horizontal scrollbar child.
protected JScrollBar | ScrollPaneLayout.hsb The scrollpane's horizontal scrollbar child.
protected JScrollBar | JScrollPane.verticalScrollBar The scrollpane's vertical scrollbar child.
protected JScrollBar | ScrollPaneLayout.vsb The scrollpane's vertical scrollbar child.

Methods in javax.swing that return JScrollBar
JScrollBar | JScrollPane.createHorizontalScrollBar() Returns a JScrollPane.ScrollBar by default.
JScrollBar | JScrollPane.createVerticalScrollBar() Returns a JScrollPane.ScrollBar by default.
JScrollBar | JScrollPane.getHorizontalScrollBar() Returns the horizontal scroll bar that controls the viewport's horizontal view position.
JScrollBar | ScrollPaneLayout.getHorizontalScrollBar() Returns the JScrollBar object that handles horizontal scrolling.
JScrollBar | JScrollPane.getVerticalScrollBar() Returns the vertical scroll bar that controls the viewports vertical view position.
JScrollBar | ScrollPaneLayout.getVerticalScrollBar() Returns the JScrollBar object that handles vertical scrolling.

Methods in javax.swing with parameters of type JScrollBar
void | JScrollPane.setHorizontalScrollBar(JScrollBar horizontalScrollBar) Adds the scrollbar that controls the viewport's horizontal view position to the scrollpane.
void | JScrollPane.setVerticalScrollBar(JScrollBar verticalScrollBar) Adds the scrollbar that controls the viewports vertical view position to the scrollpane.

Uses of JScrollBar in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JScrollBar
protected JScrollBar | BasicScrollBarUI.scrollbar
protected JScrollBar | BasicTreeUI.ComponentHandler.scrollBar ScrollBar that is being adjusted.

Methods in javax.swing.plaf.basic with parameters of type JScrollBar
protected void | BasicScrollBarUI.layoutHScrollbar(JScrollBar sb)
protected void | BasicScrollBarUI.layoutVScrollbar(JScrollBar sb)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JScrollBar.AccessibleJScrollBar

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JScrollBar.AccessibleJScrollBar

No usage of javax.swing.JScrollBar.AccessibleJScrollBar

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JScrollPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JScrollPane

Packages that use JScrollPane
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of JScrollPane in javax.swing

Methods in javax.swing that return JScrollPane
static JScrollPane JTable.createScrollPaneForTable(JTable aTable)
Deprecated. As of Swing version 1.0.2, replaced by new JScrollPane(aTable).

Methods in javax.swing with parameters of type JScrollPane
 Rectangle ScrollPaneLayout.getViewportBorderBounds(JScrollPane scrollpane)
Deprecated. As of JDK version Swing1.1 replaced by JScrollPane.getViewportBorderBounds().
 void ScrollPaneLayout.syncWithScrollPane(JScrollPane sp)
This method is invoked after the ScrollPaneLayout is set as the LayoutManager of a JScrollPane.

Uses of JScrollPane in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JScrollPane
protected JScrollPane | BasicComboPopup.scroller This protected field is implementation specific.
protected JScrollPane | BasicScrollPaneUI.scrollpane

Methods in javax.swing.plaf.basic that return JScrollPane
protected JScrollPane | BasicComboPopup.createScroller() Creates the scroll pane which houses the scrollable list.
protected JScrollPane | BasicTreeUI.ComponentHandler.getScrollPane() Returns the JScrollPane housing the JTree, or null if one isn't found.

Methods in javax.swing.plaf.basic with parameters of type JScrollPane
protected void | BasicScrollPaneUI.installDefaults(JScrollPane scrollpane)
protected void | BasicScrollPaneUI.installKeyboardActions(JScrollPane c)
protected void | BasicScrollPaneUI.installListeners(JScrollPane c)
protected void | BasicScrollPaneUI.uninstallDefaults(JScrollPane c)
protected void | BasicScrollPaneUI.uninstallKeyboardActions(JScrollPane c)

Uses of JScrollPane in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal with parameters of type JScrollPane
void | MetalScrollPaneUI.installListeners(JScrollPane scrollPane)
void | MetalScrollPaneUI.uninstallListeners(JScrollPane scrollPane)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JScrollPane.AccessibleJScrollPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JScrollPane.AccessibleJScrollPane

No usage of javax.swing.JScrollPane.AccessibleJScrollPane

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JScrollPane.ScrollBar

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JScrollPane.ScrollBar

No usage of javax.swing.JScrollPane.ScrollBar

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JSeparator

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JSeparator

Packages that use JSeparator
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of JSeparator in javax.swing

Subclasses of JSeparator in javax.swing
static class | JPopupMenu.Separator A popup menu-specific separator.
static class | JToolBar.Separator A toolbar-specific separator.

Uses of JSeparator in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic with parameters of type JSeparator
protected void | BasicToolBarSeparatorUI.installDefaults(JSeparator s)
protected void | BasicSeparatorUI.installDefaults(JSeparator s)
protected void | BasicSeparatorUI.installListeners(JSeparator s)
protected void | BasicSeparatorUI.uninstallDefaults(JSeparator s)
protected void | BasicSeparatorUI.uninstallListeners(JSeparator s)

Uses of JSeparator in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal with parameters of type JSeparator
protected  void MetalSeparatorUI.installDefaults(JSeparator s)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JSeparator.AccessibleJSeparator

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JSeparator.AccessibleJSeparator

No usage of javax.swing.JSeparator.AccessibleJSeparator

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JSlider

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JSlider

Packages that use JSlider
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of JSlider in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JSlider
protected  JSlider BasicSliderUI.slider

Methods in javax.swing.plaf.basic with parameters of type JSlider
protected ChangeListener | BasicSliderUI.createChangeListener(JSlider slider)
protected ComponentListener | BasicSliderUI.createComponentListener(JSlider slider)
protected FocusListener | BasicSliderUI.createFocusListener(JSlider slider)
protected PropertyChangeListener | BasicSliderUI.createPropertyChangeListener(JSlider slider)
protected BasicSliderUI.ScrollListener | BasicSliderUI.createScrollListener(JSlider slider)
protected BasicSliderUI.TrackListener | BasicSliderUI.createTrackListener(JSlider slider)
protected void | BasicSliderUI.installDefaults(JSlider slider)
protected void | BasicSliderUI.installKeyboardActions(JSlider slider)
protected void | BasicSliderUI.installListeners(JSlider slider)
protected void | BasicSliderUI.uninstallKeyboardActions(JSlider slider)
protected void | BasicSliderUI.uninstallListeners(JSlider slider)

Constructors in javax.swing.plaf.basic with parameters of type JSlider
BasicSliderUI.ActionScroller(JSlider slider, int dir, boolean block)
BasicSliderUI(JSlider b)

Uses of JSlider in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal with parameters of type JSlider
protected  PropertyChangeListener MetalSliderUI.createPropertyChangeListener(JSlider slider)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JSlider.AccessibleJSlider

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JSlider.AccessibleJSlider

No usage of javax.swing.JSlider.AccessibleJSlider

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JSpinner

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JSpinner

Packages that use JSpinner
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of JSpinner in javax.swing

Methods in javax.swing that return JSpinner
 JSpinner JSpinner.DefaultEditor.getSpinner()
Returns the JSpinner ancestor of this editor or null if none of the ancestors are a JSpinner.

Methods in javax.swing with parameters of type JSpinner
 void JSpinner.DefaultEditor.dismiss(JSpinner spinner)
Disconnect this editor from the specified JSpinner.

Constructors in javax.swing with parameters of type JSpinner
JSpinner.DateEditor(JSpinner spinner)
Construct a JSpinner editor that supports displaying and editing the value of a SpinnerDateModel with a JFormattedTextField.
JSpinner.DateEditor(JSpinner spinner, String dateFormatPattern)
Construct a JSpinner editor that supports displaying and editing the value of a SpinnerDateModel with a JFormattedTextField.
JSpinner.DefaultEditor(JSpinner spinner)
Constructs an editor component for the specified JSpinner.
JSpinner.ListEditor(JSpinner spinner)
Construct a JSpinner editor that supports displaying and editing the value of a SpinnerListModel with a JFormattedTextField.
JSpinner.NumberEditor(JSpinner spinner)
Construct a JSpinner editor that supports displaying and editing the value of a SpinnerNumberModel with a JFormattedTextField.
JSpinner.NumberEditor(JSpinner spinner, String decimalFormatPattern)
Construct a JSpinner editor that supports displaying and editing the value of a SpinnerNumberModel with a JFormattedTextField.

Uses of JSpinner in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JSpinner
protected  JSpinner BasicSpinnerUI.spinner
The spinner that we're a UI delegate for.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JSpinner.AccessibleJSpinner

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JSpinner.AccessibleJSpinner

No usage of javax.swing.JSpinner.AccessibleJSpinner

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JSpinner.DateEditor

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JSpinner.DateEditor

No usage of javax.swing.JSpinner.DateEditor

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JSpinner.DefaultEditor

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JSpinner.DefaultEditor

Packages that use JSpinner.DefaultEditor
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JSpinner.DefaultEditor in javax.swing

Subclasses of JSpinner.DefaultEditor in javax.swing
static class | JSpinner.DateEditor An editor for a JSpinner whose model is a SpinnerDateModel.
static class | JSpinner.ListEditor An editor for a JSpinner whose model is a SpinnerListModel.
static class | JSpinner.NumberEditor An editor for a JSpinner whose model is a SpinnerNumberModel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JSpinner.ListEditor

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JSpinner.ListEditor

No usage of javax.swing.JSpinner.ListEditor

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JSpinner.NumberEditor

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JSpinner.NumberEditor

No usage of javax.swing.JSpinner.NumberEditor

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JSplitPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JSplitPane

Packages that use JSplitPane
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of JSplitPane in javax.swing.plaf

Methods in javax.swing.plaf with parameters of type JSplitPane
abstract void | SplitPaneUI.finishedPaintingChildren(JSplitPane jc, Graphics g) Messaged after the JSplitPane the receiver is providing the look and feel for paints its children.
abstract int | SplitPaneUI.getDividerLocation(JSplitPane jc) Returns the location of the divider.
abstract int | SplitPaneUI.getMaximumDividerLocation(JSplitPane jc) Returns the maximum possible location of the divider.
abstract int | SplitPaneUI.getMinimumDividerLocation(JSplitPane jc) Returns the minimum possible location of the divider.
abstract void | SplitPaneUI.resetToPreferredSizes(JSplitPane jc) Messaged to relayout the JSplitPane based on the preferred size of the children components.
abstract void | SplitPaneUI.setDividerLocation(JSplitPane jc, int location) Sets the location of the divider to location.

Uses of JSplitPane in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JSplitPane
protected JSplitPane | BasicSplitPaneUI.splitPane JSplitPane instance this instance is providing the look and feel for.
protected JSplitPane | BasicSplitPaneDivider.splitPane JSplitPane the receiver is contained in.

Methods in javax.swing.plaf.basic that return JSplitPane
 JSplitPane BasicSplitPaneUI.getSplitPane()
Returns the splitpane this instance is currently contained in.

Methods in javax.swing.plaf.basic with parameters of type JSplitPane
void | BasicSplitPaneUI.finishedPaintingChildren(JSplitPane jc, Graphics g) Messaged after the JSplitPane the receiver is providing the look and feel for paints its children.
int | BasicSplitPaneUI.getDividerLocation(JSplitPane jc) Returns the location of the divider, which may differ from what the splitpane thinks the location of the divider is.
int | BasicSplitPaneUI.getMaximumDividerLocation(JSplitPane jc) Gets the maximum location of the divider.
int | BasicSplitPaneUI.getMinimumDividerLocation(JSplitPane jc) Gets the minimum location of the divider.
void | BasicSplitPaneUI.resetToPreferredSizes(JSplitPane jc) Messaged to reset the preferred sizes.
void | BasicSplitPaneUI.setDividerLocation(JSplitPane jc, int location) Sets the location of the divider to location.

Uses of JSplitPane in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi with parameters of type JSplitPane
void | MultiSplitPaneUI.finishedPaintingChildren(JSplitPane a, Graphics b) Invokes the finishedPaintingChildren method on each UI handled by this object.
int | MultiSplitPaneUI.getDividerLocation(JSplitPane a) Invokes the getDividerLocation method on each UI handled by this object.
int | MultiSplitPaneUI.getMaximumDividerLocation(JSplitPane a) Invokes the getMaximumDividerLocation method on each UI handled by this object.
int | MultiSplitPaneUI.getMinimumDividerLocation(JSplitPane a) Invokes the getMinimumDividerLocation method on each UI handled by this object.
void | MultiSplitPaneUI.resetToPreferredSizes(JSplitPane a) Invokes the resetToPreferredSizes method on each UI handled by this object.
void | MultiSplitPaneUI.setDividerLocation(JSplitPane a, int b) Invokes the setDividerLocation method on each UI handled by this object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JSplitPane.AccessibleJSplitPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JSplitPane.AccessibleJSplitPane

No usage of javax.swing.JSplitPane.AccessibleJSplitPane

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTabbedPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTabbedPane

Packages that use JTabbedPane
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of JTabbedPane in javax.swing.plaf

Methods in javax.swing.plaf with parameters of type JTabbedPane
abstract Rectangle | TabbedPaneUI.getTabBounds(JTabbedPane pane, int index)
abstract int | TabbedPaneUI.getTabRunCount(JTabbedPane pane)
abstract int | TabbedPaneUI.tabForCoordinate(JTabbedPane pane, int x, int y)

Uses of JTabbedPane in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JTabbedPane
protected  JTabbedPane BasicTabbedPaneUI.tabPane

Methods in javax.swing.plaf.basic with parameters of type JTabbedPane
Rectangle | BasicTabbedPaneUI.getTabBounds(JTabbedPane pane, int i) Returns the bounds of the specified tab index.
int | BasicTabbedPaneUI.getTabRunCount(JTabbedPane pane)
int | BasicTabbedPaneUI.tabForCoordinate(JTabbedPane pane, int x, int y) Returns the tab index which intersects the specified point in the JTabbedPane's coordinate space.

Uses of JTabbedPane in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi with parameters of type JTabbedPane
Rectangle | MultiTabbedPaneUI.getTabBounds(JTabbedPane a, int b) Invokes the getTabBounds method on each UI handled by this object.
int | MultiTabbedPaneUI.getTabRunCount(JTabbedPane a) Invokes the getTabRunCount method on each UI handled by this object.
int | MultiTabbedPaneUI.tabForCoordinate(JTabbedPane a, int b, int c) Invokes the tabForCoordinate method on each UI handled by this object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTabbedPane.AccessibleJTabbedPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTabbedPane.AccessibleJTabbedPane

No usage of javax.swing.JTabbedPane.AccessibleJTabbedPane

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTabbedPane.ModelListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTabbedPane.ModelListener

No usage of javax.swing.JTabbedPane.ModelListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTable

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTable

Packages that use JTable
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of JTable in javax.swing

Methods in javax.swing with parameters of type JTable
static JScrollPane | JTable.createScrollPaneForTable(JTable aTable) Deprecated. As of Swing version 1.0.2, replaced by new JScrollPane(aTable).
Component | DefaultCellEditor.getTableCellEditorComponent(JTable table, Object value, boolean isSelected, int row, int column) Implements the TableCellEditor interface.

Constructors in javax.swing with parameters of type JTable
JTable.AccessibleJTable.AccessibleJTableCell(JTable t, int r, int c, int i)
Constructs an AccessibleJTableHeaderEntry.

Uses of JTable in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JTable
protected  JTable BasicTableUI.table

Uses of JTable in javax.swing.table

Fields in javax.swing.table declared as JTable
protected  JTable JTableHeader.table
The table for which this object is the header; the default is null.

Methods in javax.swing.table that return JTable
 JTable JTableHeader.getTable()
Returns the table associated with this header.

Methods in javax.swing.table with parameters of type JTable
Component | TableCellEditor.getTableCellEditorComponent(JTable table, Object value, boolean isSelected, int row, int column) Sets an initial value for the editor.
Component | DefaultTableCellRenderer.getTableCellRendererComponent(JTable table, Object value, boolean isSelected, boolean hasFocus, int row, int column) Returns the default table cell renderer.
Component | TableCellRenderer.getTableCellRendererComponent(JTable table, Object value, boolean isSelected, boolean hasFocus, int row, int column) Returns the component used for drawing the cell.
void | JTableHeader.setTable(JTable table) Sets the table associated with this header.

Constructors in javax.swing.table with parameters of type JTable
JTableHeader.AccessibleJTableHeader.AccessibleJTableHeaderEntry(int c, JTableHeader p, JTable t)
Constructs an AccessiblJTableHeaaderEntry

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTable.AccessibleJTable

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTable.AccessibleJTable

No usage of javax.swing.JTable.AccessibleJTable

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTable.AccessibleJTable.AccessibleJTableCell

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTable.AccessibleJTable.AccessibleJTableCell

No usage of javax.swing.JTable.AccessibleJTable.AccessibleJTableCell

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTable.AccessibleJTable.AccessibleJTableModelChange

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTable.AccessibleJTable.AccessibleJTableModelChange

No usage of javax.swing.JTable.AccessibleJTable.AccessibleJTableModelChange

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTable.DropLocation

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTable.DropLocation

Packages that use JTable.DropLocation
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JTable.DropLocation in javax.swing

Methods in javax.swing that return JTable.DropLocation
 JTable.DropLocation JTable.getDropLocation()
Returns the location that this component should visually indicate as the drop location during a DnD operation over the component, or null if no location is to currently be shown.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTable.PrintMode

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTable.PrintMode

Packages that use JTable.PrintMode
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JTable.PrintMode in javax.swing

Methods in javax.swing that return JTable.PrintMode
static JTable.PrintMode | JTable.PrintMode.valueOf(String name) Returns the enum constant of this type with the specified name.
static JTable.PrintMode[] | JTable.PrintMode.values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods in javax.swing with parameters of type JTable.PrintMode
Printable | JTable.getPrintable(JTable.PrintMode printMode, MessageFormat headerFormat, MessageFormat footerFormat) Return a Printable for use in printing this JTable.
boolean | JTable.print(JTable.PrintMode printMode) A convenience method that displays a printing dialog, and then prints this JTable in the given printing mode, with no header or footer text.
boolean | JTable.print(JTable.PrintMode printMode, MessageFormat headerFormat, MessageFormat footerFormat) A convenience method that displays a printing dialog, and then prints this JTable in the given printing mode, with the specified header and footer text.
boolean | JTable.print(JTable.PrintMode printMode, MessageFormat headerFormat, MessageFormat footerFormat, boolean showPrintDialog, PrintRequestAttributeSet attr, boolean interactive) Prints this table, as specified by the fully featured print method, with the default printer specified as the print service.
boolean | JTable.print(JTable.PrintMode printMode, MessageFormat headerFormat, MessageFormat footerFormat, boolean showPrintDialog, PrintRequestAttributeSet attr, boolean interactive, PrintService service) Prints this JTable.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTextArea

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTextArea

No usage of javax.swing.JTextArea

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTextArea.AccessibleJTextArea

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTextArea.AccessibleJTextArea

No usage of javax.swing.JTextArea.AccessibleJTextArea

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTextField

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTextField

Packages that use JTextField
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of JTextField in javax.swing

Subclasses of JTextField in javax.swing
class | JFormattedTextField JFormattedTextField extends JTextField adding support for formatting arbitrary values, as well as retrieving a particular object once the user has edited the text.
class | JPasswordField JPasswordField is a lightweight component that allows the editing of a single line of text where the view indicates something was typed, but does not show the original characters.

Constructors in javax.swing with parameters of type JTextField
DefaultCellEditor(JTextField textField)
Constructs a DefaultCellEditor that uses a text field.

Uses of JTextField in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JTextField
protected  JTextField BasicComboBoxEditor.editor

Methods in javax.swing.plaf.basic that return JTextField
protected  JTextField BasicComboBoxEditor.createEditorComponent()
Creates the internal editor component.

Uses of JTextField in javax.swing.tree

Subclasses of JTextField in javax.swing.tree
 class DefaultTreeCellEditor.DefaultTextField
TextField used when no editor is supplied.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTextField.AccessibleJTextField

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTextField.AccessibleJTextField

Packages that use JTextField.AccessibleJTextField
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JTextField.AccessibleJTextField in javax.swing

Subclasses of JTextField.AccessibleJTextField in javax.swing
protected  class JPasswordField.AccessibleJPasswordField
This class implements accessibility support for the JPasswordField class.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTextPane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTextPane

No usage of javax.swing.JTextPane

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JToggleButton

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JToggleButton

Packages that use JToggleButton
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JToggleButton in javax.swing

Subclasses of JToggleButton in javax.swing
class | JCheckBox An implementation of a check box -- an item that can be selected or deselected, and which displays its state to the user.
class | JRadioButton An implementation of a radio button -- an item that can be selected or deselected, and which displays its state to the user.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JToggleButton.AccessibleJToggleButton

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JToggleButton.AccessibleJToggleButton

Packages that use JToggleButton.AccessibleJToggleButton
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JToggleButton.AccessibleJToggleButton in javax.swing

Subclasses of JToggleButton.AccessibleJToggleButton in javax.swing
protected class | JCheckBox.AccessibleJCheckBox This class implements accessibility support for the JCheckBox class.
protected class | JRadioButton.AccessibleJRadioButton This class implements accessibility support for the JRadioButton class.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JToggleButton.ToggleButtonModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JToggleButton.ToggleButtonModel

No usage of javax.swing.JToggleButton.ToggleButtonModel

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JToolBar

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JToolBar

Packages that use JToolBar
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of JToolBar in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JToolBar
protected JToolBar | BasicToolBarUI.toolBar
protected JToolBar | BasicToolBarUI.DockingListener.toolBar

Methods in javax.swing.plaf.basic with parameters of type JToolBar
protected  BasicToolBarUI.DragWindow BasicToolBarUI.createDragWindow(JToolBar toolbar)
protected  JFrame BasicToolBarUI.createFloatingFrame(JToolBar toolbar)
No longer used, use BasicToolBarUI.createFloatingWindow(JToolBar)
protected  RootPaneContainer BasicToolBarUI.createFloatingWindow(JToolBar toolbar)
Creates a window which contains the toolbar after it has been dragged out from its container

Constructors in javax.swing.plaf.basic with parameters of type JToolBar
BasicToolBarUI.DockingListener(JToolBar t)

Uses of JToolBar in javax.swing.plaf.metal

Constructors in javax.swing.plaf.metal with parameters of type JToolBar
MetalToolBarUI.MetalDockingListener(JToolBar t)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JToolBar.AccessibleJToolBar

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JToolBar.AccessibleJToolBar

No usage of javax.swing.JToolBar.AccessibleJToolBar

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JToolBar.Separator

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JToolBar.Separator

No usage of javax.swing.JToolBar.Separator

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JToolTip

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JToolTip

Packages that use JToolTip
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JToolTip in javax.swing

Methods in javax.swing that return JToolTip
 JToolTip JComponent.createToolTip()
Returns the instance of JToolTip that should be used to display the tooltip.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JToolTip.AccessibleJToolTip

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JToolTip.AccessibleJToolTip

No usage of javax.swing.JToolTip.AccessibleJToolTip

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTree

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTree

Packages that use JTree
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of JTree in javax.swing

Methods in javax.swing with parameters of type JTree
 Component DefaultCellEditor.getTreeCellEditorComponent(JTree tree, Object value, boolean isSelected, boolean expanded, boolean leaf, int row)
Implements the TreeCellEditor interface.

Constructors in javax.swing with parameters of type JTree
JTree.AccessibleJTree.AccessibleJTreeNode(JTree t, TreePath p, Accessible ap)
Constructs an AccessibleJTreeNode

Uses of JTree in javax.swing.plaf

Methods in javax.swing.plaf with parameters of type JTree
abstract void | TreeUI.cancelEditing(JTree tree) Cancels the current editing session.
abstract TreePath | TreeUI.getClosestPathForLocation(JTree tree, int x, int y) Returns the path to the node that is closest to x,y.
abstract TreePath | TreeUI.getEditingPath(JTree tree) Returns the path to the element that is being edited.
abstract Rectangle | TreeUI.getPathBounds(JTree tree, TreePath path) Returns the Rectangle enclosing the label portion that the last item in path will be drawn into.
abstract TreePath | TreeUI.getPathForRow(JTree tree, int row) Returns the path for passed in row.
abstract int | TreeUI.getRowCount(JTree tree) Returns the number of rows that are being displayed.
abstract int | TreeUI.getRowForPath(JTree tree, TreePath path) Returns the row that the last item identified in path is visible at.
abstract boolean | TreeUI.isEditing(JTree tree) Returns true if the tree is being edited.
abstract void | TreeUI.startEditingAtPath(JTree tree, TreePath path) Selects the last item in path and tries to edit it.
abstract boolean | TreeUI.stopEditing(JTree tree) Stops the current editing session.

Uses of JTree in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JTree
protected  JTree BasicTreeUI.tree
Component that we're going to be drawing into.

Methods in javax.swing.plaf.basic with parameters of type JTree
void | BasicTreeUI.cancelEditing(JTree tree) Cancels the current editing session.
TreePath | BasicTreeUI.getClosestPathForLocation(JTree tree, int x, int y) Returns the path to the node that is closest to x,y.
TreePath | BasicTreeUI.getEditingPath(JTree tree) Returns the path to the element that is being edited.
Rectangle | BasicTreeUI.getPathBounds(JTree tree, TreePath path) Returns the Rectangle enclosing the label portion that the last item in path will be drawn into.
TreePath | BasicTreeUI.getPathForRow(JTree tree, int row) Returns the path for passed in row.
int | BasicTreeUI.getRowCount(JTree tree) Returns the number of rows that are being displayed.
int | BasicTreeUI.getRowForPath(JTree tree, TreePath path) Returns the row that the last item identified in path is visible at.
boolean | BasicTreeUI.isEditing(JTree tree) Returns true if the tree is being edited.
void | BasicTreeUI.startEditingAtPath(JTree tree, TreePath path) Selects the last item in path and tries to edit it.
boolean | BasicTreeUI.stopEditing(JTree tree) Stops the current editing session.

Uses of JTree in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi with parameters of type JTree
void | MultiTreeUI.cancelEditing(JTree a) Invokes the cancelEditing method on each UI handled by this object.
TreePath | MultiTreeUI.getClosestPathForLocation(JTree a, int b, int c) Invokes the getClosestPathForLocation method on each UI handled by this object.
TreePath | MultiTreeUI.getEditingPath(JTree a) Invokes the getEditingPath method on each UI handled by this object.
Rectangle | MultiTreeUI.getPathBounds(JTree a, TreePath b) Invokes the getPathBounds method on each UI handled by this object.
TreePath | MultiTreeUI.getPathForRow(JTree a, int b) Invokes the getPathForRow method on each UI handled by this object.
int | MultiTreeUI.getRowCount(JTree a) Invokes the getRowCount method on each UI handled by this object.
int | MultiTreeUI.getRowForPath(JTree a, TreePath b) Invokes the getRowForPath method on each UI handled by this object.
boolean | MultiTreeUI.isEditing(JTree a) Invokes the isEditing method on each UI handled by this object.
void | MultiTreeUI.startEditingAtPath(JTree a, TreePath b) Invokes the startEditingAtPath method on each UI handled by this object.
boolean | MultiTreeUI.stopEditing(JTree a) Invokes the stopEditing method on each UI handled by this object.

Uses of JTree in javax.swing.tree

Fields in javax.swing.tree declared as JTree
protected  JTree DefaultTreeCellEditor.tree
JTree instance listening too.

Methods in javax.swing.tree with parameters of type JTree
protected void | DefaultTreeCellEditor.determineOffset(JTree tree, Object value, boolean isSelected, boolean expanded, boolean leaf, int row)
Component | DefaultTreeCellEditor.getTreeCellEditorComponent(JTree tree, Object value, boolean isSelected, boolean expanded, boolean leaf, int row) Configures the editor.
Component | TreeCellEditor.getTreeCellEditorComponent(JTree tree, Object value, boolean isSelected, boolean expanded, boolean leaf, int row) Sets an initial value for the editor.
Component | DefaultTreeCellRenderer.getTreeCellRendererComponent(JTree tree, Object value, boolean sel, boolean expanded, boolean leaf, int row, boolean hasFocus) Configures the renderer based on the passed in components.
Component | TreeCellRenderer.getTreeCellRendererComponent(JTree tree, Object value, boolean selected, boolean expanded, boolean leaf, int row, boolean hasFocus) Sets the value of the current tree cell to value.
protected void | DefaultTreeCellEditor.setTree(JTree newTree) Sets the tree currently editing for.

Constructors in javax.swing.tree with parameters of type JTree
DefaultTreeCellEditor(JTree tree, DefaultTreeCellRenderer renderer)
Constructs a DefaultTreeCellEditor object for a JTree using the specified renderer and a default editor.
DefaultTreeCellEditor(JTree tree, DefaultTreeCellRenderer renderer, TreeCellEditor editor)
Constructs a DefaultTreeCellEditor object for a JTree using the specified renderer and the specified editor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTree.AccessibleJTree

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTree.AccessibleJTree

No usage of javax.swing.JTree.AccessibleJTree

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTree.AccessibleJTree.AccessibleJTreeNode

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTree.AccessibleJTree.AccessibleJTreeNode

No usage of javax.swing.JTree.AccessibleJTree.AccessibleJTreeNode

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTree.DropLocation

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTree.DropLocation

Packages that use JTree.DropLocation
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JTree.DropLocation in javax.swing

Methods in javax.swing that return JTree.DropLocation
 JTree.DropLocation JTree.getDropLocation()
Returns the location that this component should visually indicate as the drop location during a DnD operation over the component, or null if no location is to currently be shown.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTree.DynamicUtilTreeNode

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTree.DynamicUtilTreeNode

No usage of javax.swing.JTree.DynamicUtilTreeNode

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTree.EmptySelectionModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTree.EmptySelectionModel

Packages that use JTree.EmptySelectionModel
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JTree.EmptySelectionModel in javax.swing

Fields in javax.swing declared as JTree.EmptySelectionModel
protected static JTree.EmptySelectionModel JTree.EmptySelectionModel.sharedInstance
Unique shared instance.

Methods in javax.swing that return JTree.EmptySelectionModel
static JTree.EmptySelectionModel JTree.EmptySelectionModel.sharedInstance()
Returns a shared instance of an empty selection model.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTree.TreeModelHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTree.TreeModelHandler

No usage of javax.swing.JTree.TreeModelHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JTree.TreeSelectionRedirector

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JTree.TreeSelectionRedirector

Packages that use JTree.TreeSelectionRedirector
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JTree.TreeSelectionRedirector in javax.swing

Fields in javax.swing declared as JTree.TreeSelectionRedirector
protected  JTree.TreeSelectionRedirector JTree.selectionRedirector
Creates a new event and passed it off the selectionListeners.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JViewport

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JViewport

Packages that use JViewport
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JViewport in javax.swing

Fields in javax.swing declared as JViewport
protected JViewport | ScrollPaneLayout.colHead The column header child.
protected JViewport | JScrollPane.columnHeader The column header child.
protected JViewport | ScrollPaneLayout.rowHead The row header child.
protected JViewport | JScrollPane.rowHeader The row header child.
protected JViewport | JScrollPane.viewport The scrollpane's viewport child.
protected JViewport | ScrollPaneLayout.viewport The scrollpane's viewport child.
protected JViewport | JScrollPane.AccessibleJScrollPane.viewPort

Methods in javax.swing that return JViewport
protected JViewport | JScrollPane.createViewport() Returns a new JViewport by default.
JViewport | JScrollPane.getColumnHeader() Returns the column header.
JViewport | ScrollPaneLayout.getColumnHeader() Returns the JViewport object that is the column header.
JViewport | JScrollPane.getRowHeader() Returns the row header.
JViewport | ScrollPaneLayout.getRowHeader() Returns the JViewport object that is the row header.
JViewport | JScrollPane.getViewport() Returns the current JViewport.
JViewport | ScrollPaneLayout.getViewport() Returns the JViewport object that displays the scrollable contents.

Methods in javax.swing with parameters of type JViewport
void | JScrollPane.setColumnHeader(JViewport columnHeader) Removes the old columnHeader, if it exists; if the new columnHeader isn't null, syncs the x coordinate of its viewPosition with the viewport (if there is one) and then adds it to the scroll pane.
void | JScrollPane.setRowHeader(JViewport rowHeader) Removes the old rowHeader, if it exists; if the new rowHeader isn't null, syncs the y coordinate of its viewPosition with the viewport (if there is one) and then adds it to the scroll pane.
void | JScrollPane.setViewport(JViewport viewport) Removes the old viewport (if there is one); forces the viewPosition of the new viewport to be in the +x,+y quadrant; syncs up the row and column headers (if there are any) with the new viewport; and finally syncs the scrollbars and headers with the new viewport.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JViewport.AccessibleJViewport

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JViewport.AccessibleJViewport

No usage of javax.swing.JViewport.AccessibleJViewport

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JViewport.ViewListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JViewport.ViewListener

Packages that use JViewport.ViewListener
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JViewport.ViewListener in javax.swing

Methods in javax.swing that return JViewport.ViewListener
protected  JViewport.ViewListener JViewport.createViewListener()
Creates a listener for the view.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JWindow

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JWindow

No usage of javax.swing.JWindow

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.JWindow.AccessibleJWindow

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.JWindow.AccessibleJWindow

No usage of javax.swing.JWindow.AccessibleJWindow

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.KeyStroke

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.KeyStroke

Packages that use KeyStroke
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of KeyStroke in javax.swing

Methods in javax.swing that return KeyStroke
KeyStroke[] | InputMap.allKeys() Returns an array of the KeyStrokes defined in this InputMap and its parent.
KeyStroke | JMenuItem.getAccelerator() Returns the KeyStroke which serves as an accelerator for the menu item.
static KeyStroke | KeyStroke.getKeyStroke(char keyChar) Returns a shared instance of a KeyStroke that represents a KEY_TYPED event for the specified character.
static KeyStroke | KeyStroke.getKeyStroke(Character keyChar, int modifiers) Returns a shared instance of a KeyStroke that represents a KEY_TYPED event for the specified Character object and a set of modifiers.
static KeyStroke | KeyStroke.getKeyStroke(char keyChar, boolean onKeyRelease) Deprecated. use getKeyStroke(char)
static KeyStroke | KeyStroke.getKeyStroke(int keyCode, int modifiers) Returns a shared instance of a KeyStroke, given a numeric key code and a set of modifiers.
static KeyStroke | KeyStroke.getKeyStroke(int keyCode, int modifiers, boolean onKeyRelease) Returns a shared instance of a KeyStroke, given a numeric key code and a set of modifiers, specifying whether the key is activated when it is pressed or released.
static KeyStroke | KeyStroke.getKeyStroke(String s) Parses a string and returns a KeyStroke.
static KeyStroke | KeyStroke.getKeyStrokeForEvent(KeyEvent anEvent) Returns a KeyStroke which represents the stroke which generated a given KeyEvent.
KeyStroke[] | JComponent.getRegisteredKeyStrokes() Returns the KeyStrokes that will initiate registered actions.
KeyStroke[] | InputMap.keys() Returns the KeyStrokes that are bound in this InputMap.

Methods in javax.swing with parameters of type KeyStroke
 Object InputMap.get(KeyStroke keyStroke)
Returns the binding for keyStroke, messaging the parent InputMap if the binding is not locally defined.
 ActionListener JComponent.getActionForKeyStroke(KeyStroke aKeyStroke)
Returns the object that will perform the action registered for a given keystroke.
 int JComponent.getConditionForKeyStroke(KeyStroke aKeyStroke)
Returns the condition that determines whether a registered action occurs in response to the specified keystroke.
static boolean SwingUtilities.notifyAction(Action action, KeyStroke ks, KeyEvent event, Object sender, int modifiers)
Invokes actionPerformed on action if action is enabled (and non-null).
protected  boolean JTable.processKeyBinding(KeyStroke ks, KeyEvent e, int condition, boolean pressed)
protected  boolean JMenuBar.processKeyBinding(KeyStroke ks, KeyEvent e, int condition, boolean pressed)
Subclassed to check all the child menus.
protected  boolean JComponent.processKeyBinding(KeyStroke ks, KeyEvent e, int condition, boolean pressed)
Invoked to process the key bindings for ks as the result of the KeyEvent e.
 void ComponentInputMap.put(KeyStroke keyStroke, Object actionMapKey)
Adds a binding for keyStroke to actionMapKey.
 void InputMap.put(KeyStroke keyStroke, Object actionMapKey)
Adds a binding for keyStroke to actionMapKey.
 void JComponent.registerKeyboardAction(ActionListener anAction, KeyStroke aKeyStroke, int aCondition)
This method is now obsolete, please use a combination of getActionMap() and getInputMap() for similiar behavior.
 void JComponent.registerKeyboardAction(ActionListener anAction, String aCommand, KeyStroke aKeyStroke, int aCondition)
This method is now obsolete, please use a combination of getActionMap() and getInputMap() for similiar behavior.
 void ComponentInputMap.remove(KeyStroke key)
Removes the binding for key from this object.
 void InputMap.remove(KeyStroke key)
Removes the binding for key from this InputMap.
 void JMenuItem.setAccelerator(KeyStroke keyStroke)
Sets the key combination which invokes the menu item's action listeners without navigating the menu hierarchy.
 void JMenu.setAccelerator(KeyStroke keyStroke)
setAccelerator is not defined for JMenu.
 void JComponent.unregisterKeyboardAction(KeyStroke aKeyStroke)
This method is now obsolete.

Uses of KeyStroke in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as KeyStroke
protected KeyStroke | BasicDesktopPaneUI.closeKey Deprecated. As of 1.3.
protected KeyStroke | BasicSplitPaneUI.dividerResizeToggleKey Deprecated. As of Java 2 platform v1.3.
protected KeyStroke | BasicToolBarUI.downKey Deprecated. As of Java 2 platform v1.3.
protected KeyStroke | BasicTabbedPaneUI.downKey Deprecated. As of Java 2 platform v1.3.
protected KeyStroke | BasicSplitPaneUI.downKey Deprecated. As of Java 2 platform v1.3.
protected KeyStroke | BasicSplitPaneUI.endKey Deprecated. As of Java 2 platform v1.3.
protected KeyStroke | BasicSplitPaneUI.homeKey Deprecated. As of Java 2 platform v1.3.
protected KeyStroke | BasicToolBarUI.leftKey Deprecated. As of Java 2 platform v1.3.
protected KeyStroke | BasicTabbedPaneUI.leftKey Deprecated. As of Java 2 platform v1.3.
protected KeyStroke | BasicSplitPaneUI.leftKey Deprecated. As of Java 2 platform v1.3.
protected KeyStroke | BasicDesktopPaneUI.maximizeKey Deprecated. As of 1.3.
protected KeyStroke | BasicDesktopPaneUI.minimizeKey Deprecated. As of 1.3.
protected KeyStroke | BasicDesktopPaneUI.navigateKey Deprecated. As of 1.3.
protected KeyStroke | BasicDesktopPaneUI.navigateKey2 Deprecated. As of 1.3.
protected KeyStroke | BasicInternalFrameUI.openMenuKey Deprecated. As of Java 2 platform v1.3.
protected KeyStroke | BasicToolBarUI.rightKey Deprecated. As of Java 2 platform v1.3.
protected KeyStroke | BasicTabbedPaneUI.rightKey Deprecated. As of Java 2 platform v1.3.
protected KeyStroke | BasicSplitPaneUI.rightKey Deprecated. As of Java 2 platform v1.3.
protected KeyStroke | BasicToolBarUI.upKey Deprecated. As of Java 2 platform v1.3.
protected KeyStroke | BasicTabbedPaneUI.upKey Deprecated. As of Java 2 platform v1.3.
protected KeyStroke | BasicSplitPaneUI.upKey Deprecated. As of Java 2 platform v1.3.

Uses of KeyStroke in javax.swing.text

Fields in javax.swing.text declared as KeyStroke
 KeyStroke JTextComponent.KeyBinding.key
The key.

Methods in javax.swing.text that return KeyStroke
KeyStroke[] | Keymap.getBoundKeyStrokes() Fetches all of the keystrokes in this map that are bound to some action.
KeyStroke[] | Keymap.getKeyStrokesForAction(Action a) Fetches the keystrokes that will result in the given action.

Methods in javax.swing.text with parameters of type KeyStroke
void | Keymap.addActionForKeyStroke(KeyStroke key, Action a) Adds a binding to the keymap.
Action | Keymap.getAction(KeyStroke key) Fetches the action appropriate for the given symbolic event sequence.
boolean | Keymap.isLocallyDefined(KeyStroke key) Determines if the given key sequence is locally defined.
void | Keymap.removeKeyStrokeBinding(KeyStroke keys) Removes a binding from the keymap.

Constructors in javax.swing.text with parameters of type KeyStroke
JTextComponent.KeyBinding(KeyStroke key, String actionName)
Creates a new key binding.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.LayoutFocusTraversalPolicy

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.LayoutFocusTraversalPolicy

No usage of javax.swing.LayoutFocusTraversalPolicy

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.LayoutStyle

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.LayoutStyle

Packages that use LayoutStyle
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of LayoutStyle in javax.swing

Methods in javax.swing that return LayoutStyle
static LayoutStyle | LayoutStyle.getInstance() Returns the shared instance of LayoutStyle.
LayoutStyle | GroupLayout.getLayoutStyle() Returns the LayoutStyle used for calculating the preferred gap between components.
LayoutStyle | LookAndFeel.getLayoutStyle() Returns the LayoutStyle for this look and feel.

Methods in javax.swing with parameters of type LayoutStyle
static void | LayoutStyle.setInstance(LayoutStyle style) Sets the shared instance of LayoutStyle.
void | GroupLayout.setLayoutStyle(LayoutStyle layoutStyle) Sets the LayoutStyle used to calculate the preferred gaps between components.

Uses of LayoutStyle in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal that return LayoutStyle
 LayoutStyle MetalLookAndFeel.getLayoutStyle()
Returns a LayoutStyle implementing the Java look and feel design guidelines as specified at http://java.sun.com/products/jlf/ed2/book/HIG.Visual2.html.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.LayoutStyle.ComponentPlacement

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.LayoutStyle.ComponentPlacement

Packages that use LayoutStyle.ComponentPlacement
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of LayoutStyle.ComponentPlacement in javax.swing

Methods in javax.swing that return LayoutStyle.ComponentPlacement
static LayoutStyle.ComponentPlacement | LayoutStyle.ComponentPlacement.valueOf(String name) Returns the enum constant of this type with the specified name.
static LayoutStyle.ComponentPlacement[] | LayoutStyle.ComponentPlacement.values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods in javax.swing with parameters of type LayoutStyle.ComponentPlacement
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addPreferredGap(JComponent comp1, JComponent comp2, LayoutStyle.ComponentPlacement type) Adds an element representing the preferred gap between two components.
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addPreferredGap(JComponent comp1, JComponent comp2, LayoutStyle.ComponentPlacement type, int pref, int max) Adds an element representing the preferred gap between two components.
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addPreferredGap(LayoutStyle.ComponentPlacement type) Adds an element representing the preferred gap between the nearest components.
GroupLayout.SequentialGroup | GroupLayout.SequentialGroup.addPreferredGap(LayoutStyle.ComponentPlacement type, int pref, int max) Adds an element representing the preferred gap between the nearest components.
abstract int | LayoutStyle.getPreferredGap(JComponent component1, JComponent component2, LayoutStyle.ComponentPlacement type, int position, Container parent) Returns the amount of space to use between two components.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.LookAndFeel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.LookAndFeel

Packages that use LookAndFeel
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.
javax.swing.plaf.synth | Synth is a skinnable look and feel in which all painting is delegated.

Uses of LookAndFeel in javax.swing

Methods in javax.swing that return LookAndFeel
static LookAndFeel[] | UIManager.getAuxiliaryLookAndFeels() Returns the list of auxiliary look and feels (can be null).
static LookAndFeel | UIManager.getLookAndFeel() Returns the current look and feel or null.

Methods in javax.swing with parameters of type LookAndFeel
static void | UIManager.addAuxiliaryLookAndFeel(LookAndFeel laf) Adds a LookAndFeel to the list of auxiliary look and feels.
static boolean | UIManager.removeAuxiliaryLookAndFeel(LookAndFeel laf) Removes a LookAndFeel from the list of auxiliary look and feels.
static void | UIManager.setLookAndFeel(LookAndFeel newLookAndFeel) Sets the current look and feel to newLookAndFeel.

Uses of LookAndFeel in javax.swing.plaf.basic

Subclasses of LookAndFeel in javax.swing.plaf.basic
 class BasicLookAndFeel
A base class to use in creating a look and feel for Swing.

Uses of LookAndFeel in javax.swing.plaf.metal

Subclasses of LookAndFeel in javax.swing.plaf.metal
 class MetalLookAndFeel
The Java Look and Feel, otherwise known as Metal.

Uses of LookAndFeel in javax.swing.plaf.multi

Subclasses of LookAndFeel in javax.swing.plaf.multi
 class MultiLookAndFeel
A multiplexing look and feel that allows more than one UI to be associated with a component at the same time.

Uses of LookAndFeel in javax.swing.plaf.synth

Subclasses of LookAndFeel in javax.swing.plaf.synth
 class SynthLookAndFeel
SynthLookAndFeel provides the basis for creating a customized look and feel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.MenuSelectionManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.MenuSelectionManager

Packages that use MenuSelectionManager
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of MenuSelectionManager in javax.swing

Methods in javax.swing that return MenuSelectionManager
static MenuSelectionManager MenuSelectionManager.defaultManager()
Returns the default menu selection manager.

Methods in javax.swing with parameters of type MenuSelectionManager
void | JMenuItem.processKeyEvent(KeyEvent e, MenuElement[] path, MenuSelectionManager manager) Processes a key event forwarded from the MenuSelectionManager and changes the menu selection, if necessary, by using MenuSelectionManager's API.
void | JPopupMenu.processKeyEvent(KeyEvent e, MenuElement[] path, MenuSelectionManager manager) Processes a key event forwarded from the MenuSelectionManager and changes the menu selection, if necessary, by using MenuSelectionManager's API.
void | JMenuBar.processKeyEvent(KeyEvent e, MenuElement[] path, MenuSelectionManager manager) Implemented to be a MenuElement -- does nothing.
void | MenuElement.processKeyEvent(KeyEvent event, MenuElement[] path, MenuSelectionManager manager) Process a key event.
void | JMenuItem.processMouseEvent(MouseEvent e, MenuElement[] path, MenuSelectionManager manager) Processes a mouse event forwarded from the MenuSelectionManager and changes the menu selection, if necessary, by using the MenuSelectionManager's API.
void | JPopupMenu.processMouseEvent(MouseEvent event, MenuElement[] path, MenuSelectionManager manager) This method is required to conform to the MenuElement interface, but it not implemented.
void | JMenuBar.processMouseEvent(MouseEvent event, MenuElement[] path, MenuSelectionManager manager) Implemented to be a MenuElement -- does nothing.
void | MenuElement.processMouseEvent(MouseEvent event, MenuElement[] path, MenuSelectionManager manager) Processes a mouse event.

Uses of MenuSelectionManager in javax.swing.event

Methods in javax.swing.event that return MenuSelectionManager
MenuSelectionManager | MenuDragMouseEvent.getMenuSelectionManager() Returns the current menu selection manager.
MenuSelectionManager | MenuKeyEvent.getMenuSelectionManager() Returns the current menu selection manager.

Constructors in javax.swing.event with parameters of type MenuSelectionManager
MenuDragMouseEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger, MenuElement[] p, MenuSelectionManager m)
Constructs a MenuDragMouseEvent object.
MenuDragMouseEvent(Component source, int id, long when, int modifiers, int x, int y, int xAbs, int yAbs, int clickCount, boolean popupTrigger, MenuElement[] p, MenuSelectionManager m)
Constructs a MenuDragMouseEvent object.
MenuKeyEvent(Component source, int id, long when, int modifiers, int keyCode, char keyChar, MenuElement[] p, MenuSelectionManager m)
Constructs a MenuKeyEvent object.

Uses of MenuSelectionManager in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic with parameters of type MenuSelectionManager
protected void | BasicMenuItemUI.doClick(MenuSelectionManager msm) Call this method when a menu item is to be activated.
void | BasicRadioButtonMenuItemUI.processMouseEvent(JMenuItem item, MouseEvent e, MenuElement[] path, MenuSelectionManager manager)
void | BasicCheckBoxMenuItemUI.processMouseEvent(JMenuItem item, MouseEvent e, MenuElement[] path, MenuSelectionManager manager)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.OverlayLayout

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.OverlayLayout

No usage of javax.swing.OverlayLayout

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.Popup

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.Popup

Packages that use Popup
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of Popup in javax.swing

Methods in javax.swing that return Popup
 Popup PopupFactory.getPopup(Component owner, Component contents, int x, int y)
Creates a Popup for the Component owner containing the Component contents.

Uses of Popup in javax.swing.plaf

Methods in javax.swing.plaf that return Popup
 Popup PopupMenuUI.getPopup(JPopupMenu popup, int x, int y)
Returns the Popup that will be responsible for displaying the JPopupMenu.

Uses of Popup in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi that return Popup
 Popup MultiPopupMenuUI.getPopup(JPopupMenu a, int b, int c)
Invokes the getPopup method on each UI handled by this object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.PopupFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.PopupFactory

Packages that use PopupFactory
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of PopupFactory in javax.swing

Methods in javax.swing that return PopupFactory
static PopupFactory PopupFactory.getSharedInstance()
Returns the shared PopupFactory which can be used to obtain Popups.

Methods in javax.swing with parameters of type PopupFactory
static void PopupFactory.setSharedInstance(PopupFactory factory)
Sets the PopupFactory that will be used to obtain Popups.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.ProgressMonitor

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.ProgressMonitor

Packages that use ProgressMonitor
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of ProgressMonitor in javax.swing

Methods in javax.swing that return ProgressMonitor
 ProgressMonitor ProgressMonitorInputStream.getProgressMonitor()
Get the ProgressMonitor object being used by this stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.ProgressMonitor.AccessibleProgressMonitor

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.ProgressMonitor.AccessibleProgressMonitor

No usage of javax.swing.ProgressMonitor.AccessibleProgressMonitor

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.ProgressMonitorInputStream

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.ProgressMonitorInputStream

No usage of javax.swing.ProgressMonitorInputStream

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.RepaintManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.RepaintManager

Packages that use RepaintManager
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of RepaintManager in javax.swing

Methods in javax.swing that return RepaintManager
static RepaintManager | RepaintManager.currentManager(Component c) Return the RepaintManager for the calling thread given a Component.
static RepaintManager | RepaintManager.currentManager(JComponent c) Return the RepaintManager for the calling thread given a JComponent.

Methods in javax.swing with parameters of type RepaintManager
static void RepaintManager.setCurrentManager(RepaintManager aRepaintManager)
Set the RepaintManager that should be used for the calling thread.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.RowFilter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.RowFilter

Packages that use RowFilter
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of RowFilter in javax.swing

Methods in javax.swing that return RowFilter
static
<M,I> RowFilter<M,I>
RowFilter.andFilter(Iterable<? extends RowFilter<? super M,? super I>> filters)
Returns a RowFilter that includes entries if all of the supplied filters include the entry.
static
<M,I> RowFilter<M,I>
RowFilter.dateFilter(RowFilter.ComparisonType type, Date date, int... indices)
Returns a RowFilter that includes entries that have at least one Date value meeting the specified criteria.
 RowFilter<? super M,? super I> DefaultRowSorter.getRowFilter()
Returns the filter that determines which rows, if any, should be hidden from view.
static
<M,I> RowFilter<M,I>
RowFilter.notFilter(RowFilter<M,I> filter)
Returns a RowFilter that includes entries if the supplied filter does not include the entry.
static
<M,I> RowFilter<M,I>
RowFilter.numberFilter(RowFilter.ComparisonType type, Number number, int... indices)
Returns a RowFilter that includes entries that have at least one Number value meeting the specified criteria.
static
<M,I> RowFilter<M,I>
RowFilter.orFilter(Iterable<? extends RowFilter<? super M,? super I>> filters)
Returns a RowFilter that includes entries if any of the supplied filters includes the entry.
static
<M,I> RowFilter<M,I>
RowFilter.regexFilter(String regex, int... indices)
Returns a RowFilter that uses a regular expression to determine which entries to include.

Methods in javax.swing with parameters of type RowFilter
static
<M,I> RowFilter<M,I>
RowFilter.notFilter(RowFilter<M,I> filter)
Returns a RowFilter that includes entries if the supplied filter does not include the entry.
 void DefaultRowSorter.setRowFilter(RowFilter<? super M,? super I> filter)
Sets the filter that determines which rows, if any, should be hidden from the view.

Method parameters in javax.swing with type arguments of type RowFilter
static
<M,I> RowFilter<M,I>
RowFilter.andFilter(Iterable<? extends RowFilter<? super M,? super I>> filters)
Returns a RowFilter that includes entries if all of the supplied filters include the entry.
static
<M,I> RowFilter<M,I>
RowFilter.orFilter(Iterable<? extends RowFilter<? super M,? super I>> filters)
Returns a RowFilter that includes entries if any of the supplied filters includes the entry.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.RowFilter.ComparisonType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.RowFilter.ComparisonType

Packages that use RowFilter.ComparisonType
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of RowFilter.ComparisonType in javax.swing

Methods in javax.swing that return RowFilter.ComparisonType
static RowFilter.ComparisonType | RowFilter.ComparisonType.valueOf(String name) Returns the enum constant of this type with the specified name.
static RowFilter.ComparisonType[] | RowFilter.ComparisonType.values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods in javax.swing with parameters of type RowFilter.ComparisonType
static
<M,I> RowFilter<M,I>
RowFilter.dateFilter(RowFilter.ComparisonType type, Date date, int... indices)
Returns a RowFilter that includes entries that have at least one Date value meeting the specified criteria.
static
<M,I> RowFilter<M,I>
RowFilter.numberFilter(RowFilter.ComparisonType type, Number number, int... indices)
Returns a RowFilter that includes entries that have at least one Number value meeting the specified criteria.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.RowFilter.Entry

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.RowFilter.Entry

Packages that use RowFilter.Entry
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of RowFilter.Entry in javax.swing

Methods in javax.swing with parameters of type RowFilter.Entry
abstract  boolean RowFilter.include(RowFilter.Entry<? extends M,? extends I> entry)
Returns true if the specified entry should be shown; returns false if the entry should be hidden.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.RowSorter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.RowSorter

Packages that use RowSorter
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of RowSorter in javax.swing

Subclasses of RowSorter in javax.swing
 class DefaultRowSorter<M,I>
An implementation of RowSorter that provides sorting and filtering around a grid-based data model.

Methods in javax.swing that return RowSorter
 RowSorter<? extends TableModel> JTable.getRowSorter()
Returns the object responsible for sorting.

Methods in javax.swing with parameters of type RowSorter
 void JTable.setRowSorter(RowSorter<? extends TableModel> sorter)
Sets the RowSorter.

Uses of RowSorter in javax.swing.event

Methods in javax.swing.event that return RowSorter
 RowSorter RowSorterEvent.getSource()
Returns the source of the event as a RowSorter.

Constructors in javax.swing.event with parameters of type RowSorter
RowSorterEvent(RowSorter source)
Creates a RowSorterEvent of type SORT_ORDER_CHANGED.
RowSorterEvent(RowSorter source, RowSorterEvent.Type type, int[] previousRowIndexToModel)
Creates a RowSorterEvent.

Uses of RowSorter in javax.swing.table

Subclasses of RowSorter in javax.swing.table
 class TableRowSorter<M extends TableModel>
An implementation of RowSorter that provides sorting and filtering using a TableModel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.RowSorter.SortKey

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.RowSorter.SortKey

Packages that use RowSorter.SortKey
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of RowSorter.SortKey in javax.swing

Methods in javax.swing that return types with arguments of type RowSorter.SortKey
List<? extends RowSorter.SortKey> | DefaultRowSorter.getSortKeys() Returns the current sort keys.
abstract List<? extends RowSorter.SortKey> | RowSorter.getSortKeys() Returns the current sort keys.

Method parameters in javax.swing with type arguments of type RowSorter.SortKey
void | DefaultRowSorter.setSortKeys(List<? extends RowSorter.SortKey> sortKeys) Sets the sort keys.
abstract void | RowSorter.setSortKeys(List<? extends RowSorter.SortKey> keys) Sets the current sort keys.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.ScrollPaneLayout

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.ScrollPaneLayout

Packages that use ScrollPaneLayout
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of ScrollPaneLayout in javax.swing

Subclasses of ScrollPaneLayout in javax.swing
static class ScrollPaneLayout.UIResource
The UI resource version of ScrollPaneLayout.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.ScrollPaneLayout.UIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.ScrollPaneLayout.UIResource

No usage of javax.swing.ScrollPaneLayout.UIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.SizeRequirements

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.SizeRequirements

Packages that use SizeRequirements
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of SizeRequirements in javax.swing

Methods in javax.swing that return SizeRequirements
static SizeRequirements | SizeRequirements.getAlignedSizeRequirements(SizeRequirements[] children) Determines the total space necessary to align a set of components.
static SizeRequirements | SizeRequirements.getTiledSizeRequirements(SizeRequirements[] children) Determines the total space necessary to place a set of components end-to-end.

Methods in javax.swing with parameters of type SizeRequirements
static int[] | SizeRequirements.adjustSizes(int delta, SizeRequirements[] children) Adjust a specified array of sizes by a given amount.
static void | SizeRequirements.calculateAlignedPositions(int allocated, SizeRequirements total, SizeRequirements[] children, int[] offsets, int[] spans) Creates a bunch of offset/span pairs specifying how to lay out a set of components with the specified alignments.
static void | SizeRequirements.calculateAlignedPositions(int allocated, SizeRequirements total, SizeRequirements[] children, int[] offsets, int[] spans) Creates a bunch of offset/span pairs specifying how to lay out a set of components with the specified alignments.
static void | SizeRequirements.calculateAlignedPositions(int allocated, SizeRequirements total, SizeRequirements[] children, int[] offsets, int[] spans, boolean normal) Creates a set of offset/span pairs specifying how to lay out a set of components with the specified alignments.
static void | SizeRequirements.calculateAlignedPositions(int allocated, SizeRequirements total, SizeRequirements[] children, int[] offsets, int[] spans, boolean normal) Creates a set of offset/span pairs specifying how to lay out a set of components with the specified alignments.
static void | SizeRequirements.calculateTiledPositions(int allocated, SizeRequirements total, SizeRequirements[] children, int[] offsets, int[] spans) Creates a set of offset/span pairs representing how to lay out a set of components end-to-end.
static void | SizeRequirements.calculateTiledPositions(int allocated, SizeRequirements total, SizeRequirements[] children, int[] offsets, int[] spans) Creates a set of offset/span pairs representing how to lay out a set of components end-to-end.
static void | SizeRequirements.calculateTiledPositions(int allocated, SizeRequirements total, SizeRequirements[] children, int[] offsets, int[] spans, boolean forward) Creates a set of offset/span pairs representing how to lay out a set of components end-to-end.
static void | SizeRequirements.calculateTiledPositions(int allocated, SizeRequirements total, SizeRequirements[] children, int[] offsets, int[] spans, boolean forward) Creates a set of offset/span pairs representing how to lay out a set of components end-to-end.
static SizeRequirements | SizeRequirements.getAlignedSizeRequirements(SizeRequirements[] children) Determines the total space necessary to align a set of components.
static SizeRequirements | SizeRequirements.getTiledSizeRequirements(SizeRequirements[] children) Determines the total space necessary to place a set of components end-to-end.

Uses of SizeRequirements in javax.swing.text

Methods in javax.swing.text that return SizeRequirements
protected SizeRequirements | BoxView.baselineRequirements(int axis, SizeRequirements r) Calculates the size requirements for this BoxView by examining the size of each child view.
protected SizeRequirements | BoxView.calculateMajorAxisRequirements(int axis, SizeRequirements r) Calculates the size requirements for the major axis axis.
protected SizeRequirements | TableView.calculateMinorAxisRequirements(int axis, SizeRequirements r) Calculate the requirements for the minor axis.
protected SizeRequirements | BoxView.calculateMinorAxisRequirements(int axis, SizeRequirements r) Calculates the size requirements for the minor axis axis.
protected SizeRequirements | FlowView.calculateMinorAxisRequirements(int axis, SizeRequirements r) Calculate equirements along the minor axis.

Methods in javax.swing.text with parameters of type SizeRequirements
protected SizeRequirements | BoxView.baselineRequirements(int axis, SizeRequirements r) Calculates the size requirements for this BoxView by examining the size of each child view.
protected SizeRequirements | BoxView.calculateMajorAxisRequirements(int axis, SizeRequirements r) Calculates the size requirements for the major axis axis.
protected SizeRequirements | TableView.calculateMinorAxisRequirements(int axis, SizeRequirements r) Calculate the requirements for the minor axis.
protected SizeRequirements | BoxView.calculateMinorAxisRequirements(int axis, SizeRequirements r) Calculates the size requirements for the minor axis axis.
protected SizeRequirements | FlowView.calculateMinorAxisRequirements(int axis, SizeRequirements r) Calculate equirements along the minor axis.
protected void | TableView.layoutColumns(int targetSpan, int[] offsets, int[] spans, SizeRequirements[] reqs) Lays out the columns to fit within the given target span.

Uses of SizeRequirements in javax.swing.text.html

Methods in javax.swing.text.html that return SizeRequirements
protected SizeRequirements | BlockView.calculateMajorAxisRequirements(int axis, SizeRequirements r) Calculate the requirements of the block along the major axis (i.e.
protected SizeRequirements | BlockView.calculateMinorAxisRequirements(int axis, SizeRequirements r) Calculate the requirements of the block along the minor axis (i.e.
protected SizeRequirements | ParagraphView.calculateMinorAxisRequirements(int axis, SizeRequirements r) Calculate the needs for the paragraph along the minor axis.

Methods in javax.swing.text.html with parameters of type SizeRequirements
protected SizeRequirements | BlockView.calculateMajorAxisRequirements(int axis, SizeRequirements r) Calculate the requirements of the block along the major axis (i.e.
protected SizeRequirements | BlockView.calculateMinorAxisRequirements(int axis, SizeRequirements r) Calculate the requirements of the block along the minor axis (i.e.
protected SizeRequirements | ParagraphView.calculateMinorAxisRequirements(int axis, SizeRequirements r) Calculate the needs for the paragraph along the minor axis.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.SizeSequence

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.SizeSequence

No usage of javax.swing.SizeSequence

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.SortingFocusTraversalPolicy

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.SortingFocusTraversalPolicy

Packages that use SortingFocusTraversalPolicy
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of SortingFocusTraversalPolicy in javax.swing

Subclasses of SortingFocusTraversalPolicy in javax.swing
 class LayoutFocusTraversalPolicy
A SortingFocusTraversalPolicy which sorts Components based on their size, position, and orientation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.SortOrder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.SortOrder

Packages that use SortOrder
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of SortOrder in javax.swing

Methods in javax.swing that return SortOrder
SortOrder | RowSorter.SortKey.getSortOrder() Returns the sort order of the column.
static SortOrder | SortOrder.valueOf(String name) Returns the enum constant of this type with the specified name.
static SortOrder[] | SortOrder.values() Returns an array containing the constants of this enum type, in the order they are declared.

Constructors in javax.swing with parameters of type SortOrder
RowSorter.SortKey(int column, SortOrder sortOrder)
Creates a SortKey for the specified column with the specified sort order.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.SpinnerDateModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.SpinnerDateModel

Packages that use SpinnerDateModel
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of SpinnerDateModel in javax.swing

Methods in javax.swing that return SpinnerDateModel
 SpinnerDateModel JSpinner.DateEditor.getModel()
Return our spinner ancestor's SpinnerDateModel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.SpinnerListModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.SpinnerListModel

Packages that use SpinnerListModel
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of SpinnerListModel in javax.swing

Methods in javax.swing that return SpinnerListModel
 SpinnerListModel JSpinner.ListEditor.getModel()
Return our spinner ancestor's SpinnerNumberModel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.SpinnerNumberModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.SpinnerNumberModel

Packages that use SpinnerNumberModel
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of SpinnerNumberModel in javax.swing

Methods in javax.swing that return SpinnerNumberModel
 SpinnerNumberModel JSpinner.NumberEditor.getModel()
Return our spinner ancestor's SpinnerNumberModel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.Spring

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.Spring

Packages that use Spring
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of Spring in javax.swing

Methods in javax.swing that return Spring
static Spring Spring.constant(int pref)
Returns a strut -- a spring whose minimum, preferred, and maximum values each have the value pref.
static Spring Spring.constant(int min, int pref, int max)
Returns a spring whose minimum, preferred, and maximum values have the values: min, pref, and max respectively.
 Spring SpringLayout.Constraints.getConstraint(String edgeName)
Returns the value of the specified edge, which may be a derived value, or even null.
 Spring SpringLayout.getConstraint(String edgeName, Component c)
Returns the spring controlling the distance between the specified edge of the component and the top or left edge of its parent.
 Spring SpringLayout.Constraints.getHeight()
Returns the value of the height property.
 Spring SpringLayout.Constraints.getWidth()
Returns the value of the width property.
 Spring SpringLayout.Constraints.getX()
Returns the value of the x property.
 Spring SpringLayout.Constraints.getY()
Returns the value of the y property.
static Spring Spring.height(Component c)
Returns a spring whose minimum, preferred, maximum and value properties are defined by the heights of the minimumSize, preferredSize, maximumSize and size properties of the supplied component.
static Spring Spring.max(Spring s1, Spring s2)
Returns max(s1, s2): a spring whose value is always greater than (or equal to) the values of both s1 and s2.
static Spring Spring.minus(Spring s)
Returns -s: a spring running in the opposite direction to s.
static Spring Spring.scale(Spring s, float factor)
Returns a spring whose minimum, preferred, maximum and value properties are each multiples of the properties of the argument spring, s.
static Spring Spring.sum(Spring s1, Spring s2)
Returns s1+s2: a spring representing s1 and s2 in series.
static Spring Spring.width(Component c)
Returns a spring whose minimum, preferred, maximum and value properties are defined by the widths of the minimumSize, preferredSize, maximumSize and size properties of the supplied component.

Methods in javax.swing with parameters of type Spring
static Spring Spring.max(Spring s1, Spring s2)
Returns max(s1, s2): a spring whose value is always greater than (or equal to) the values of both s1 and s2.
static Spring Spring.minus(Spring s)
Returns -s: a spring running in the opposite direction to s.
 void SpringLayout.putConstraint(String e1, Component c1, Spring s, String e2, Component c2)
Links edge e1 of component c1 to edge e2 of component c2.
static Spring Spring.scale(Spring s, float factor)
Returns a spring whose minimum, preferred, maximum and value properties are each multiples of the properties of the argument spring, s.
 void SpringLayout.Constraints.setConstraint(String edgeName, Spring s)
Sets the spring controlling the specified edge.
 void SpringLayout.Constraints.setHeight(Spring height)
Sets the height property, which controls the height of a component.
 void SpringLayout.Constraints.setWidth(Spring width)
Sets the width property, which controls the width of a component.
 void SpringLayout.Constraints.setX(Spring x)
Sets the x property, which controls the x value of a component's location.
 void SpringLayout.Constraints.setY(Spring y)
Sets the y property, which controls the y value of a component's location.
static Spring Spring.sum(Spring s1, Spring s2)
Returns s1+s2: a spring representing s1 and s2 in series.

Constructors in javax.swing with parameters of type Spring
SpringLayout.Constraints(Spring x, Spring y)
Creates a Constraints object with the specified values for its x and y properties.
SpringLayout.Constraints(Spring x, Spring y, Spring width, Spring height)
Creates a Constraints object with the specified values for its x, y, width, and height properties.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.SpringLayout

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.SpringLayout

No usage of javax.swing.SpringLayout

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.SpringLayout.Constraints

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.SpringLayout.Constraints

Packages that use SpringLayout.Constraints
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of SpringLayout.Constraints in javax.swing

Methods in javax.swing that return SpringLayout.Constraints
 SpringLayout.Constraints SpringLayout.getConstraints(Component c)
Returns the constraints for the specified component.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.SwingUtilities

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.SwingUtilities

No usage of javax.swing.SwingUtilities

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.SwingWorker

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.SwingWorker

No usage of javax.swing.SwingWorker

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.SwingWorker.StateValue

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.SwingWorker.StateValue

Packages that use SwingWorker.StateValue
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of SwingWorker.StateValue in javax.swing

Methods in javax.swing that return SwingWorker.StateValue
SwingWorker.StateValue | SwingWorker.getState() Returns the SwingWorker state bound property.
static SwingWorker.StateValue | SwingWorker.StateValue.valueOf(String name) Returns the enum constant of this type with the specified name.
static SwingWorker.StateValue[] | SwingWorker.StateValue.values() Returns an array containing the constants of this enum type, in the order they are declared.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.Timer

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.Timer

Packages that use Timer
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of Timer in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as Timer
protected Timer | BasicComboPopup.autoscrollTimer This protected field is implementation specific.
protected Timer | BasicSliderUI.scrollTimer
protected Timer | BasicScrollBarUI.scrollTimer
protected Timer | BasicTreeUI.ComponentHandler.timer Timer used when inside a scrollpane and the scrollbar is adjusting.

Uses of Timer in javax.swing.tree

Fields in javax.swing.tree declared as Timer
protected  Timer DefaultTreeCellEditor.timer
Used before starting the editing session.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.ToolTipManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.ToolTipManager

Packages that use ToolTipManager
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of ToolTipManager in javax.swing

Methods in javax.swing that return ToolTipManager
static ToolTipManager ToolTipManager.sharedInstance()
Returns a shared ToolTipManager instance.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.ToolTipManager.insideTimerAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.ToolTipManager.insideTimerAction

No usage of javax.swing.ToolTipManager.insideTimerAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.ToolTipManager.outsideTimerAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.ToolTipManager.outsideTimerAction

No usage of javax.swing.ToolTipManager.outsideTimerAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.ToolTipManager.stillInsideTimerAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.ToolTipManager.stillInsideTimerAction

No usage of javax.swing.ToolTipManager.stillInsideTimerAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.TransferHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.TransferHandler

Packages that use TransferHandler
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of TransferHandler in javax.swing

Methods in javax.swing that return TransferHandler
TransferHandler | JDialog.getTransferHandler() Gets the transferHandler property.
TransferHandler | JApplet.getTransferHandler() Gets the transferHandler property.
TransferHandler | JWindow.getTransferHandler() Gets the transferHandler property.
TransferHandler | JComponent.getTransferHandler() Gets the transferHandler property.
TransferHandler | JFrame.getTransferHandler() Gets the transferHandler property.

Methods in javax.swing with parameters of type TransferHandler
void | JDialog.setTransferHandler(TransferHandler newHandler) Sets the transferHandler property, which is a mechanism to support transfer of data into this component.
void | JApplet.setTransferHandler(TransferHandler newHandler) Sets the transferHandler property, which is a mechanism to support transfer of data into this component.
void | JWindow.setTransferHandler(TransferHandler newHandler) Sets the transferHandler property, which is a mechanism to support transfer of data into this component.
void | JComponent.setTransferHandler(TransferHandler newHandler) Sets the transferHandler property, which is null if the component does not support data transfer operations.
void | JFrame.setTransferHandler(TransferHandler newHandler) Sets the transferHandler property, which is a mechanism to support transfer of data into this component.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.TransferHandler.DropLocation

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.TransferHandler.DropLocation

Packages that use TransferHandler.DropLocation
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of TransferHandler.DropLocation in javax.swing

Subclasses of TransferHandler.DropLocation in javax.swing
static class | JList.DropLocation A subclass of TransferHandler.DropLocation representing a drop location for a JList.
static class | JTable.DropLocation A subclass of TransferHandler.DropLocation representing a drop location for a JTable.
static class | JTree.DropLocation A subclass of TransferHandler.DropLocation representing a drop location for a JTree.

Methods in javax.swing that return TransferHandler.DropLocation
 TransferHandler.DropLocation TransferHandler.TransferSupport.getDropLocation()
Returns the current (non-null) drop location for the component, when this TransferSupport represents a drop.

Uses of TransferHandler.DropLocation in javax.swing.text

Subclasses of TransferHandler.DropLocation in javax.swing.text
static class JTextComponent.DropLocation
Represents a drop location for JTextComponents.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.TransferHandler.TransferSupport

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.TransferHandler.TransferSupport

Packages that use TransferHandler.TransferSupport
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of TransferHandler.TransferSupport in javax.swing

Methods in javax.swing with parameters of type TransferHandler.TransferSupport
boolean | TransferHandler.canImport(TransferHandler.TransferSupport support) This method is called repeatedly during a drag and drop operation to allow the developer to configure properties of, and to return the acceptability of transfers; with a return value of true indicating that the transfer represented by the given TransferSupport (which contains all of the details of the transfer) is acceptable at the current time, and a value of false rejecting the transfer.
boolean | TransferHandler.importData(TransferHandler.TransferSupport support) Causes a transfer to occur from a clipboard or a drag and drop operation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.UIDefaults

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.UIDefaults

Packages that use UIDefaults
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.
javax.swing.plaf.synth | Synth is a skinnable look and feel in which all painting is delegated.

Uses of UIDefaults in javax.swing

Methods in javax.swing that return UIDefaults
UIDefaults | LookAndFeel.getDefaults() Returns the look and feel defaults.
static UIDefaults | UIManager.getDefaults() Returns the defaults.
static UIDefaults | UIManager.getLookAndFeelDefaults() Returns the UIDefaults from the current look and feel, that were obtained at the time the look and feel was installed.

Methods in javax.swing with parameters of type UIDefaults
Object | UIDefaults.LazyValue.createValue(UIDefaults table) Creates the actual value retrieved from the UIDefaults table.
Object | UIDefaults.ActiveValue.createValue(UIDefaults table) Creates the value retrieved from the UIDefaults table.
Object | UIDefaults.ProxyLazyValue.createValue(UIDefaults table) Creates the value retrieved from the UIDefaults table.
Object | UIDefaults.LazyInputMap.createValue(UIDefaults table) Creates an InputMap with the bindings that are passed in.

Uses of UIDefaults in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic that return UIDefaults
 UIDefaults BasicLookAndFeel.getDefaults()
Returns the look and feel defaults.

Methods in javax.swing.plaf.basic with parameters of type UIDefaults
protected void | BasicLookAndFeel.initClassDefaults(UIDefaults table) Populates table with mappings from uiClassID to the fully qualified name of the ui class.
protected void | BasicLookAndFeel.initComponentDefaults(UIDefaults table) Populates table with the defaults for the basic look and feel.
protected void | BasicLookAndFeel.initSystemColorDefaults(UIDefaults table) Populates table with system colors.
protected void | BasicLookAndFeel.loadSystemColors(UIDefaults table, String[] systemColors, boolean useNative) Populates table with the name-color pairs in systemColors.

Uses of UIDefaults in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal that return UIDefaults
 UIDefaults MetalLookAndFeel.getDefaults()
Returns the look and feel defaults.

Methods in javax.swing.plaf.metal with parameters of type UIDefaults
void | OceanTheme.addCustomEntriesToTable(UIDefaults table) Add this theme's custom entries to the defaults table.
void | MetalTheme.addCustomEntriesToTable(UIDefaults table) Adds values specific to this theme to the defaults table.
protected void | MetalLookAndFeel.initClassDefaults(UIDefaults table) Populates table with mappings from uiClassID to the fully qualified name of the ui class.
protected void | MetalLookAndFeel.initComponentDefaults(UIDefaults table) Populates table with the defaults for metal.
protected void | MetalLookAndFeel.initSystemColorDefaults(UIDefaults table) Populates table with system colors.

Uses of UIDefaults in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi that return UIDefaults
 UIDefaults MultiLookAndFeel.getDefaults()
Creates, initializes, and returns the look and feel specific defaults.

Uses of UIDefaults in javax.swing.plaf.synth

Methods in javax.swing.plaf.synth that return UIDefaults
 UIDefaults SynthLookAndFeel.getDefaults()
Returns the defaults for this SynthLookAndFeel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.UIDefaults.LazyInputMap

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.UIDefaults.LazyInputMap

No usage of javax.swing.UIDefaults.LazyInputMap

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.UIDefaults.ProxyLazyValue

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.UIDefaults.ProxyLazyValue

No usage of javax.swing.UIDefaults.ProxyLazyValue

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.UIManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.UIManager

No usage of javax.swing.UIManager

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.UIManager.LookAndFeelInfo

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.UIManager.LookAndFeelInfo

Packages that use UIManager.LookAndFeelInfo
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of UIManager.LookAndFeelInfo in javax.swing

Methods in javax.swing that return UIManager.LookAndFeelInfo
static UIManager.LookAndFeelInfo[] UIManager.getInstalledLookAndFeels()
Returns an array of LookAndFeelInfos representing the LookAndFeel implementations currently available.

Methods in javax.swing with parameters of type UIManager.LookAndFeelInfo
static void | UIManager.installLookAndFeel(UIManager.LookAndFeelInfo info) Adds the specified look and feel to the set of available look and feels.
static void | UIManager.setInstalledLookAndFeels(UIManager.LookAndFeelInfo[] infos) Sets the set of available look and feels.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.UnsupportedLookAndFeelException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.UnsupportedLookAndFeelException

Packages that use UnsupportedLookAndFeelException
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of UnsupportedLookAndFeelException in javax.swing

Methods in javax.swing that throw UnsupportedLookAndFeelException
static void | UIManager.setLookAndFeel(LookAndFeel newLookAndFeel) Sets the current look and feel to newLookAndFeel.
static void | UIManager.setLookAndFeel(String className) Loads the LookAndFeel specified by the given class name, using the current thread's context class loader, and passes it to setLookAndFeel(LookAndFeel).

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.ViewportLayout

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.ViewportLayout

No usage of javax.swing.ViewportLayout

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.Action

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.Action

Packages that use Action
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of Action in javax.swing

Classes in javax.swing that implement Action
 class AbstractAction
This class provides default implementations for the JFC Action interface.

Methods in javax.swing that return Action
Action | ActionMap.get(Object key) Returns the binding for key, messaging the parent ActionMap if the binding is not locally defined.
Action | JTextField.getAction() Returns the currently set Action for this ActionEvent source, or null if no Action is set.
Action | JComboBox.getAction() Returns the currently set Action for this ActionEvent source, or null if no Action is set.
Action | AbstractButton.getAction() Returns the currently set Action for this ActionEvent source, or null if no Action is set.
Action[] | JFormattedTextField.getActions() Fetches the command list for the editor.
protected Action[] | JFormattedTextField.AbstractFormatter.getActions() Subclass and override if you wish to provide a custom set of Actions.
Action[] | JTextField.getActions() Fetches the command list for the editor.
static Action | TransferHandler.getCopyAction() Returns an Action that performs copy operations to the clipboard.
static Action | TransferHandler.getCutAction() Returns an Action that performs cut operations to the clipboard.
static Action | TransferHandler.getPasteAction() Returns an Action that performs paste operations from the clipboard.

Methods in javax.swing with parameters of type Action
protected void | JTextField.actionPropertyChanged(Action action, String propertyName) Updates the textfield's state in response to property changes in associated action.
protected void | JComboBox.actionPropertyChanged(Action action, String propertyName) Updates the combobox's state in response to property changes in associated action.
protected void | JMenuItem.actionPropertyChanged(Action action, String propertyName) Updates the button's state in response to property changes in the associated action.
protected void | AbstractButton.actionPropertyChanged(Action action, String propertyName) Updates the button's state in response to property changes in the associated action.
JButton | JToolBar.add(Action a) Adds a new JButton which dispatches the action.
JMenuItem | JPopupMenu.add(Action a) Appends a new menu item to the end of the menu which dispatches the specified Action object.
JMenuItem | JMenu.add(Action a) Creates a new menu item attached to the specified Action object and appends it to the end of this menu.
protected void | JTextField.configurePropertiesFromAction(Action a) Sets the properties on this textfield to match those in the specified Action.
protected void | JComboBox.configurePropertiesFromAction(Action a) Sets the properties on this combobox to match those in the specified Action.
protected void | JMenuItem.configurePropertiesFromAction(Action a) Sets the properties on this button to match those in the specified Action.
protected void | AbstractButton.configurePropertiesFromAction(Action a) Sets the properties on this button to match those in the specified Action.
protected JButton | JToolBar.createActionComponent(Action a) Factory method which creates the JButton for Actions added to the JToolBar.
protected JMenuItem | JPopupMenu.createActionComponent(Action a) Factory method which creates the JMenuItem for Actions added to the JPopupMenu.
protected JMenuItem | JMenu.createActionComponent(Action a) Factory method which creates the JMenuItem for Actions added to the JMenu.
protected PropertyChangeListener | JTextField.createActionPropertyChangeListener(Action a) Creates and returns a PropertyChangeListener that is responsible for listening for changes from the specified Action and updating the appropriate properties.
protected PropertyChangeListener | JComboBox.createActionPropertyChangeListener(Action a) Creates and returns a PropertyChangeListener that is responsible for listening for changes from the specified Action and updating the appropriate properties.
protected PropertyChangeListener | AbstractButton.createActionPropertyChangeListener(Action a) Creates and returns a PropertyChangeListener that is responsible for listening for changes from the specified Action and updating the appropriate properties.
void | JPopupMenu.insert(Action a, int index) Inserts a menu item for the specified Action object at a given position.
JMenuItem | JMenu.insert(Action a, int pos) Inserts a new menu item attached to the specified Action object at a given position.
static boolean | SwingUtilities.notifyAction(Action action, KeyStroke ks, KeyEvent event, Object sender, int modifiers) Invokes actionPerformed on action if action is enabled (and non-null).
void | ActionMap.put(Object key, Action action) Adds a binding for key to action.
void | JTextField.setAction(Action a) Sets the Action for the ActionEvent source.
void | JComboBox.setAction(Action a) Sets the Action for the ActionEvent source.
void | AbstractButton.setAction(Action a) Sets the Action.

Constructors in javax.swing with parameters of type Action
JButton(Action a)
Creates a button where properties are taken from the Action supplied.
JCheckBox(Action a)
Creates a check box where properties are taken from the Action supplied.
JCheckBoxMenuItem(Action a)
Creates a menu item whose properties are taken from the Action supplied.
JMenu(Action a)
Constructs a menu whose properties are taken from the Action supplied.
JMenuItem(Action a)
Creates a menu item whose properties are taken from the specified Action.
JRadioButton(Action a)
Creates a radiobutton where properties are taken from the Action supplied.
JRadioButtonMenuItem(Action a)
Creates a radio button menu item whose properties are taken from the Action supplied.
JToggleButton(Action a)
Creates a toggle button where properties are taken from the Action supplied.

Uses of Action in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement Action
protected class | BasicDesktopPaneUI.CloseAction Handles closing an internal frame.
protected class | BasicDesktopPaneUI.MaximizeAction Handles maximizing an internal frame.
protected class | BasicDesktopPaneUI.MinimizeAction Handles minimizing an internal frame.
protected class | BasicDesktopPaneUI.NavigateAction Handles navigating to the next internal frame.
protected class | BasicDesktopPaneUI.OpenAction Handles restoring a minimized or maximized internal frame.
protected class | BasicFileChooserUI.ApproveSelectionAction Responds to an Open or Save request
protected class | BasicFileChooserUI.CancelSelectionAction Responds to a cancel request.
protected class | BasicFileChooserUI.ChangeToParentDirectoryAction
protected class | BasicFileChooserUI.GoHomeAction Acts on the "home" key event or equivalent event.
protected class | BasicFileChooserUI.NewFolderAction Creates a new folder.
protected class | BasicFileChooserUI.UpdateAction Rescans the files in the current directory
class | BasicInternalFrameTitlePane.CloseAction This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.IconifyAction This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.MaximizeAction This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.MoveAction This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.RestoreAction This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.SizeAction This class should be treated as a "protected" inner class.
class | BasicSliderUI.ActionScroller As of Java 2 platform v1.3 this undocumented class is no longer used.
class | BasicTreeUI.TreeCancelEditingAction ActionListener that invokes cancelEditing when action performed.
class | BasicTreeUI.TreeHomeAction TreeHomeAction is used to handle end/home actions.
class | BasicTreeUI.TreeIncrementAction TreeIncrementAction is used to handle up/down actions.
class | BasicTreeUI.TreePageAction TreePageAction handles page up and page down events.
class | BasicTreeUI.TreeToggleAction For the first selected row expandedness will be toggled.
class | BasicTreeUI.TreeTraverseAction TreeTraverseAction is the action used for left/right keys.

Fields in javax.swing.plaf.basic declared as Action
protected Action | BasicInternalFrameTitlePane.closeAction
protected Action | BasicInternalFrameTitlePane.iconifyAction
protected Action | BasicInternalFrameTitlePane.maximizeAction
protected Action | BasicInternalFrameTitlePane.moveAction
protected Action | BasicTreeUI.KeyHandler.repeatKeyAction Key code that is being generated for.
protected Action | BasicInternalFrameTitlePane.restoreAction
protected Action | BasicInternalFrameTitlePane.sizeAction

Methods in javax.swing.plaf.basic that return Action
protected Action | BasicLookAndFeel.createAudioAction(Object key) Creates and returns an Action used to play a sound.
Action | BasicFileChooserUI.getApproveSelectionAction()
Action | BasicFileChooserUI.getCancelSelectionAction()
Action | BasicFileChooserUI.getChangeToParentDirectoryAction()
Action | BasicFileChooserUI.getGoHomeAction()
Action | BasicFileChooserUI.getNewFolderAction()
Action | BasicFileChooserUI.getUpdateAction()

Methods in javax.swing.plaf.basic with parameters of type Action
protected  void BasicLookAndFeel.playSound(Action audioAction)
If necessary, invokes actionPerformed on audioAction to play a sound.

Uses of Action in javax.swing.plaf.metal

Classes in javax.swing.plaf.metal that implement Action
protected  class MetalFileChooserUI.DirectoryComboBoxAction
Acts when DirectoryComboBox has changed the selected item.

Uses of Action in javax.swing.text

Classes in javax.swing.text that implement Action
static class | DefaultEditorKit.BeepAction Creates a beep.
static class | DefaultEditorKit.CopyAction Copies the selected region and place its contents into the system clipboard.
static class | DefaultEditorKit.CutAction Cuts the selected region and place its contents into the system clipboard.
static class | DefaultEditorKit.DefaultKeyTypedAction The action that is executed by default if a key typed event is received and there is no keymap entry.
static class | DefaultEditorKit.InsertBreakAction Places a line/paragraph break into the document.
static class | DefaultEditorKit.InsertContentAction Places content into the associated document.
static class | DefaultEditorKit.InsertTabAction Places a tab character into the document.
static class | DefaultEditorKit.PasteAction Pastes the contents of the system clipboard into the selected region, or before the caret if nothing is selected.
static class | StyledEditorKit.AlignmentAction An action to set paragraph alignment.
static class | StyledEditorKit.BoldAction An action to toggle the bold attribute.
static class | StyledEditorKit.FontFamilyAction An action to set the font family in the associated JEditorPane.
static class | StyledEditorKit.FontSizeAction An action to set the font size in the associated JEditorPane.
static class | StyledEditorKit.ForegroundAction An action to set foreground color.
static class | StyledEditorKit.ItalicAction An action to toggle the italic attribute.
static class | StyledEditorKit.StyledTextAction An action that assumes it's being fired on a JEditorPane with a StyledEditorKit (or subclass) installed.
static class | StyledEditorKit.UnderlineAction An action to toggle the underline attribute.
class | TextAction An Action implementation useful for key bindings that are shared across a number of different text components.

Methods in javax.swing.text that return Action
static Action[] | TextAction.augmentList(Action[] list1, Action[] list2) Takes one list of commands and augments it with another list of commands.
Action | Keymap.getAction(KeyStroke key) Fetches the action appropriate for the given symbolic event sequence.
protected Action[] | InternationalFormatter.getActions() If getSupportsIncrement returns true, this returns two Actions suitable for incrementing/decrementing the value.
Action[] | StyledEditorKit.getActions() Fetches the command list for the editor.
Action[] | DefaultEditorKit.getActions() Fetches the set of commands that can be used on a text component that is using a model and view produced by this kit.
Action[] | JTextComponent.getActions() Fetches the command list for the editor.
abstract Action[] | EditorKit.getActions() Fetches the set of commands that can be used on a text component that is using a model and view produced by this kit.
Action[] | Keymap.getBoundActions() Fetches all of the actions defined in this keymap.
Action | Keymap.getDefaultAction() Fetches the default action to fire if a key is typed (i.e.

Methods in javax.swing.text with parameters of type Action
void | Keymap.addActionForKeyStroke(KeyStroke key, Action a) Adds a binding to the keymap.
static Action[] | TextAction.augmentList(Action[] list1, Action[] list2) Takes one list of commands and augments it with another list of commands.
static Action[] | TextAction.augmentList(Action[] list1, Action[] list2) Takes one list of commands and augments it with another list of commands.
KeyStroke[] | Keymap.getKeyStrokesForAction(Action a) Fetches the keystrokes that will result in the given action.
static void | JTextComponent.loadKeymap(Keymap map, JTextComponent.KeyBinding[] bindings, Action[] actions) Loads a keymap with a bunch of bindings.
void | Keymap.setDefaultAction(Action a) Set the default action to fire if a key is typed.

Uses of Action in javax.swing.text.html

Classes in javax.swing.text.html that implement Action
static class | HTMLEditorKit.HTMLTextAction An abstract Action providing some convenience methods that may be useful in inserting HTML into an existing document.
static class | HTMLEditorKit.InsertHTMLTextAction InsertHTMLTextAction can be used to insert an arbitrary string of HTML into an existing HTML document.

Methods in javax.swing.text.html that return Action
 Action[] HTMLEditorKit.getActions()
Fetches the command list for the editor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.BoundedRangeModel

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.BoundedRangeModel

Packages that use BoundedRangeModel
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of BoundedRangeModel in javax.swing

Classes in javax.swing that implement BoundedRangeModel
 class DefaultBoundedRangeModel
A generic implementation of BoundedRangeModel.

Fields in javax.swing declared as BoundedRangeModel
protected BoundedRangeModel | JProgressBar.model The object that holds the data for the progress bar.
protected BoundedRangeModel | JScrollBar.model The model that represents the scrollbar's minimum, maximum, extent (aka "visibleAmount") and current value.
protected BoundedRangeModel | JSlider.sliderModel The data model that handles the numeric maximum value, minimum value, and current-position value for the slider.

Methods in javax.swing that return BoundedRangeModel
BoundedRangeModel | JTextField.getHorizontalVisibility() Gets the visibility of the text field.
BoundedRangeModel | JProgressBar.getModel() Returns the data model used by this progress bar.
BoundedRangeModel | JSlider.getModel() Returns the BoundedRangeModel that handles the slider's three fundamental properties: minimum, maximum, value.
BoundedRangeModel | JScrollBar.getModel() Returns data model that handles the scrollbar's four fundamental properties: minimum, maximum, value, extent.

Methods in javax.swing with parameters of type BoundedRangeModel
void | JProgressBar.setModel(BoundedRangeModel newModel) Sets the data model used by the JProgressBar.
void | JSlider.setModel(BoundedRangeModel newModel) Sets the BoundedRangeModel that handles the slider's three fundamental properties: minimum, maximum, value.
void | JScrollBar.setModel(BoundedRangeModel newModel) Sets the model that handles the scrollbar's four fundamental properties: minimum, maximum, value, extent.

Constructors in javax.swing with parameters of type BoundedRangeModel
JProgressBar(BoundedRangeModel newModel)
Creates a horizontal progress bar that uses the specified model to hold the progress bar's data.
JSlider(BoundedRangeModel brm)
Creates a horizontal slider using the specified BoundedRangeModel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.ButtonModel

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.ButtonModel

Packages that use ButtonModel
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of ButtonModel in javax.swing

Classes in javax.swing that implement ButtonModel
class | DefaultButtonModel The default implementation of a Button component's data model.
static class | JToggleButton.ToggleButtonModel The ToggleButton model

Fields in javax.swing declared as ButtonModel
protected  ButtonModel AbstractButton.model
The data model that determines the button's state.

Methods in javax.swing that return ButtonModel
ButtonModel | AbstractButton.getModel() Returns the model that this button represents.
ButtonModel | ButtonGroup.getSelection() Returns the model of the selected button.

Methods in javax.swing with parameters of type ButtonModel
boolean | ButtonGroup.isSelected(ButtonModel m) Returns whether a ButtonModel is selected.
void | JMenuItem.setModel(ButtonModel newModel) Sets the model that this button represents.
void | AbstractButton.setModel(ButtonModel newModel) Sets the model that this button represents.
void | JMenu.setModel(ButtonModel newModel) Sets the data model for the "menu button" -- the label that the user clicks to open or close the menu.
void | ButtonGroup.setSelected(ButtonModel m, boolean b) Sets the selected value for the ButtonModel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.CellEditor

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.CellEditor

Packages that use CellEditor
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of CellEditor in javax.swing

Classes in javax.swing that implement CellEditor
class | AbstractCellEditor
class | DefaultCellEditor The default editor for table and tree cells.

Uses of CellEditor in javax.swing.table

Subinterfaces of CellEditor in javax.swing.table
 interface TableCellEditor
This interface defines the method any object that would like to be an editor of values for components such as JListBox, JComboBox, JTree, or JTable needs to implement.

Uses of CellEditor in javax.swing.tree

Subinterfaces of CellEditor in javax.swing.tree
 interface TreeCellEditor
Adds to CellEditor the extensions necessary to configure an editor in a tree.

Classes in javax.swing.tree that implement CellEditor
 class DefaultTreeCellEditor
A TreeCellEditor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.ComboBoxEditor

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.ComboBoxEditor

Packages that use ComboBoxEditor
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of ComboBoxEditor in javax.swing

Fields in javax.swing declared as ComboBoxEditor
protected  ComboBoxEditor JComboBox.editor
This protected field is implementation specific.

Methods in javax.swing that return ComboBoxEditor
 ComboBoxEditor JComboBox.getEditor()
Returns the editor used to paint and edit the selected item in the JComboBox field.

Methods in javax.swing with parameters of type ComboBoxEditor
void | JComboBox.configureEditor(ComboBoxEditor anEditor, Object anItem) Initializes the editor with the specified item.
void | JComboBox.setEditor(ComboBoxEditor anEditor) Sets the editor used to paint and edit the selected item in the JComboBox field.

Uses of ComboBoxEditor in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement ComboBoxEditor
class | BasicComboBoxEditor The default editor for editable combo boxes.
static class | BasicComboBoxEditor.UIResource A subclass of BasicComboBoxEditor that implements UIResource.

Methods in javax.swing.plaf.basic that return ComboBoxEditor
protected  ComboBoxEditor BasicComboBoxUI.createEditor()
Creates the default editor that will be used in editable combo boxes.

Uses of ComboBoxEditor in javax.swing.plaf.metal

Classes in javax.swing.plaf.metal that implement ComboBoxEditor
class | MetalComboBoxEditor The default editor for Metal editable combo boxes
static class | MetalComboBoxEditor.UIResource A subclass of BasicComboBoxEditor that implements UIResource.

Methods in javax.swing.plaf.metal that return ComboBoxEditor
protected  ComboBoxEditor MetalComboBoxUI.createEditor()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.ComboBoxModel

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.ComboBoxModel

Packages that use ComboBoxModel
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of ComboBoxModel in javax.swing

Subinterfaces of ComboBoxModel in javax.swing
 interface MutableComboBoxModel
A mutable version of ComboBoxModel.

Classes in javax.swing that implement ComboBoxModel
 class DefaultComboBoxModel
The default model for combo boxes.

Fields in javax.swing declared as ComboBoxModel
protected  ComboBoxModel JComboBox.dataModel
This protected field is implementation specific.

Methods in javax.swing that return ComboBoxModel
 ComboBoxModel JComboBox.getModel()
Returns the data model currently used by the JComboBox.

Methods in javax.swing with parameters of type ComboBoxModel
int | JComboBox.KeySelectionManager.selectionForKey(char aKey, ComboBoxModel aModel) Given aKey and the model, returns the row that should become selected.
void | JComboBox.setModel(ComboBoxModel aModel) Sets the data model that the JComboBox uses to obtain the list of items.

Constructors in javax.swing with parameters of type ComboBoxModel
JComboBox(ComboBoxModel aModel)
Creates a JComboBox that takes its items from an existing ComboBoxModel.

Uses of ComboBoxModel in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic with parameters of type ComboBoxModel
protected void | BasicComboPopup.installComboBoxModelListeners(ComboBoxModel model) Installs the listeners on the combo box model.
protected void | BasicComboPopup.uninstallComboBoxModelListeners(ComboBoxModel model) Removes the listeners from the combo box model

Uses of ComboBoxModel in javax.swing.plaf.metal

Classes in javax.swing.plaf.metal that implement ComboBoxModel
protected class | MetalFileChooserUI.DirectoryComboBoxModel Data model for a type-face selection combo-box.
protected class | MetalFileChooserUI.FilterComboBoxModel Data model for a type-face selection combo-box.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.DesktopManager

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.DesktopManager

Packages that use DesktopManager
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of DesktopManager in javax.swing

Classes in javax.swing that implement DesktopManager
 class DefaultDesktopManager
This is an implementation of the DesktopManager.

Methods in javax.swing that return DesktopManager
 DesktopManager JDesktopPane.getDesktopManager()
Returns the DesktopManger that handles desktop-specific UI actions.

Methods in javax.swing with parameters of type DesktopManager
 void JDesktopPane.setDesktopManager(DesktopManager d)
Sets the DesktopManger that will handle desktop-specific UI actions.

Uses of DesktopManager in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as DesktopManager
protected  DesktopManager BasicDesktopPaneUI.desktopManager

Methods in javax.swing.plaf.basic that return DesktopManager
protected DesktopManager | BasicInternalFrameUI.createDesktopManager()
protected DesktopManager | BasicInternalFrameUI.getDesktopManager() Returns the proper DesktopManager.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.Icon

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.Icon

Packages that use Icon
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.border | Provides classes and interface for drawing specialized borders around a Swing component.
javax.swing.colorchooser | Contains classes and interfaces used by the JColorChooser component.
javax.swing.filechooser | Contains classes and interfaces used by the JFileChooser component.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.synth | Synth is a skinnable look and feel in which all painting is delegated.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of Icon in javax.swing

Classes in javax.swing that implement Icon
 class ImageIcon
An implementation of the Icon interface that paints Icons from Images.

Fields in javax.swing declared as Icon
protected Icon | JInternalFrame.frameIcon The icon shown in the top-left corner of this internal frame.
protected Icon | JOptionPane.icon Icon used in pane.

Methods in javax.swing that return Icon
Icon | JLabel.getDisabledIcon() Returns the icon used by the label when it's disabled.
Icon | AbstractButton.getDisabledIcon() Returns the icon used by the button when it's disabled.
Icon | LookAndFeel.getDisabledIcon(JComponent component, Icon icon) Returns an Icon with a disabled appearance.
Icon | JTabbedPane.getDisabledIconAt(int index) Returns the tab disabled icon at index.
Icon | AbstractButton.getDisabledSelectedIcon() Returns the icon used by the button when it's disabled and selected.
Icon | LookAndFeel.getDisabledSelectedIcon(JComponent component, Icon icon) Returns an Icon for use by disabled components that are also selected.
Icon | JInternalFrame.getFrameIcon() Returns the image displayed in the title bar of this internal frame (usually in the top-left corner).
Icon | JOptionPane.getIcon() Returns the icon this pane displays.
Icon | JLabel.getIcon() Returns the graphic image (glyph, icon) that the label displays.
Icon | AbstractButton.getIcon() Returns the default icon.
Icon | JFileChooser.getIcon(File f) Returns the icon for this file or type of file, depending on the system.
Icon | UIDefaults.getIcon(Object key) If the value of key is an Icon return it, otherwise return null.
static Icon | UIManager.getIcon(Object key) Returns an Icon from the defaults.
Icon | UIDefaults.getIcon(Object key, Locale l) If the value of key for the given Locale is an Icon return it, otherwise return null.
static Icon | UIManager.getIcon(Object key, Locale l) Returns an Icon from the defaults that is appropriate for the given locale.
Icon | JTabbedPane.getIconAt(int index) Returns the tab icon at index.
Icon | AbstractButton.getPressedIcon() Returns the pressed icon for the button.
Icon | AbstractButton.getRolloverIcon() Returns the rollover icon for the button.
Icon | AbstractButton.getRolloverSelectedIcon() Returns the rollover selection icon for the button.
Icon | AbstractButton.getSelectedIcon() Returns the selected icon for the button.
Icon | TransferHandler.getVisualRepresentation(Transferable t) Returns an object that establishes the look of a transfer.

Methods in javax.swing with parameters of type Icon
 void JTabbedPane.addTab(String title, Icon icon, Component component)
Adds a component represented by a title and/or icon, either of which can be null.
 void JTabbedPane.addTab(String title, Icon icon, Component component, String tip)
Adds a component and tip represented by a title and/or icon, either of which can be null.
static MatteBorder BorderFactory.createMatteBorder(int top, int left, int bottom, int right, Icon tileIcon)
Creates a matte-look border that consists of multiple tiles of a specified icon.
 Icon LookAndFeel.getDisabledIcon(JComponent component, Icon icon)
Returns an Icon with a disabled appearance.
 Icon LookAndFeel.getDisabledSelectedIcon(JComponent component, Icon icon)
Returns an Icon for use by disabled components that are also selected.
 int JTabbedPane.indexOfTab(Icon icon)
Returns the first tab index with a given icon, or -1 if no tab has this icon.
protected  void JMenuItem.init(String text, Icon icon)
Initializes the menu item with the specified text and icon.
protected  void AbstractButton.init(String text, Icon icon)
 void JTextPane.insertIcon(Icon g)
Inserts an icon into the document as a replacement for the currently selected content.
 void JTabbedPane.insertTab(String title, Icon icon, Component component, String tip, int index)
Inserts a component, at index, represented by a title and/or icon, either of which may be null.
static String SwingUtilities.layoutCompoundLabel(FontMetrics fm, String text, Icon icon, int verticalAlignment, int horizontalAlignment, int verticalTextPosition, int horizontalTextPosition, Rectangle viewR, Rectangle iconR, Rectangle textR, int textIconGap)
Compute and return the location of the icons origin, the location of origin of the text baseline, and a possibly clipped version of the compound labels string.
static String SwingUtilities.layoutCompoundLabel(JComponent c, FontMetrics fm, String text, Icon icon, int verticalAlignment, int horizontalAlignment, int verticalTextPosition, int horizontalTextPosition, Rectangle viewR, Rectangle iconR, Rectangle textR, int textIconGap)
Compute and return the location of the icons origin, the location of origin of the text baseline, and a possibly clipped version of the compound labels string.
 void JLabel.setDisabledIcon(Icon disabledIcon)
Set the icon to be displayed if this JLabel is "disabled" (JLabel.setEnabled(false)).
 void AbstractButton.setDisabledIcon(Icon disabledIcon)
Sets the disabled icon for the button.
 void JTabbedPane.setDisabledIconAt(int index, Icon disabledIcon)
Sets the disabled icon at index to icon which can be null.
 void AbstractButton.setDisabledSelectedIcon(Icon disabledSelectedIcon)
Sets the disabled selection icon for the button.
 void JInternalFrame.setFrameIcon(Icon icon)
Sets an image to be displayed in the titlebar of this internal frame (usually in the top-left corner).
 void JOptionPane.setIcon(Icon newIcon)
Sets the icon to display.
 void JLabel.setIcon(Icon icon)
Defines the icon this component will display.
 void AbstractButton.setIcon(Icon defaultIcon)
Sets the button's default icon.
 void JTabbedPane.setIconAt(int index, Icon icon)
Sets the icon at index to icon which can be null.
 void AbstractButton.setPressedIcon(Icon pressedIcon)
Sets the pressed icon for the button.
 void AbstractButton.setRolloverIcon(Icon rolloverIcon)
Sets the rollover icon for the button.
 void AbstractButton.setRolloverSelectedIcon(Icon rolloverSelectedIcon)
Sets the rollover selected icon for the button.
 void AbstractButton.setSelectedIcon(Icon selectedIcon)
Sets the selected icon for the button.
static int JOptionPane.showConfirmDialog(Component parentComponent, Object message, String title, int optionType, int messageType, Icon icon)
Brings up a dialog with a specified icon, where the number of choices is determined by the optionType parameter.
static Object JOptionPane.showInputDialog(Component parentComponent, Object message, String title, int messageType, Icon icon, Object[] selectionValues, Object initialSelectionValue)
Prompts the user for input in a blocking dialog where the initial selection, possible selections, and all other options can be specified.
static int JOptionPane.showInternalConfirmDialog(Component parentComponent, Object message, String title, int optionType, int messageType, Icon icon)
Brings up an internal dialog panel with a specified icon, where the number of choices is determined by the optionType parameter.
static Object JOptionPane.showInternalInputDialog(Component parentComponent, Object message, String title, int messageType, Icon icon, Object[] selectionValues, Object initialSelectionValue)
Prompts the user for input in a blocking internal dialog where the initial selection, possible selections, and all other options can be specified.
static void JOptionPane.showInternalMessageDialog(Component parentComponent, Object message, String title, int messageType, Icon icon)
Brings up an internal dialog panel displaying a message, specifying all parameters.
static int JOptionPane.showInternalOptionDialog(Component parentComponent, Object message, String title, int optionType, int messageType, Icon icon, Object[] options, Object initialValue)
Brings up an internal dialog panel with a specified icon, where the initial choice is determined by the initialValue parameter and the number of choices is determined by the optionType parameter.
static void JOptionPane.showMessageDialog(Component parentComponent, Object message, String title, int messageType, Icon icon)
Brings up a dialog displaying a message, specifying all parameters.
static int JOptionPane.showOptionDialog(Component parentComponent, Object message, String title, int optionType, int messageType, Icon icon, Object[] options, Object initialValue)
Brings up a dialog with a specified icon, where the initial choice is determined by the initialValue parameter and the number of choices is determined by the optionType parameter.

Constructors in javax.swing with parameters of type Icon
AbstractAction(String name, Icon icon)
Defines an Action object with the specified description string and a the specified icon.
JButton(Icon icon)
Creates a button with an icon.
JButton(String text, Icon icon)
Creates a button with initial text and an icon.
JCheckBox(Icon icon)
Creates an initially unselected check box with an icon.
JCheckBox(Icon icon, boolean selected)
Creates a check box with an icon and specifies whether or not it is initially selected.
JCheckBox(String text, Icon icon)
Creates an initially unselected check box with the specified text and icon.
JCheckBox(String text, Icon icon, boolean selected)
Creates a check box with text and icon, and specifies whether or not it is initially selected.
JCheckBoxMenuItem(Icon icon)
Creates an initially unselected check box menu item with an icon.
JCheckBoxMenuItem(String text, Icon icon)
Creates an initially unselected check box menu item with the specified text and icon.
JCheckBoxMenuItem(String text, Icon icon, boolean b)
Creates a check box menu item with the specified text, icon, and selection state.
JLabel(Icon image)
Creates a JLabel instance with the specified image.
JLabel(Icon image, int horizontalAlignment)
Creates a JLabel instance with the specified image and horizontal alignment.
JLabel(String text, Icon icon, int horizontalAlignment)
Creates a JLabel instance with the specified text, image, and horizontal alignment.
JMenuItem(Icon icon)
Creates a JMenuItem with the specified icon.
JMenuItem(String text, Icon icon)
Creates a JMenuItem with the specified text and icon.
JOptionPane(Object message, int messageType, int optionType, Icon icon)
Creates an instance of JOptionPane to display a message with the specified message type, options, and icon.
JOptionPane(Object message, int messageType, int optionType, Icon icon, Object[] options)
Creates an instance of JOptionPane to display a message with the specified message type, icon, and options.
JOptionPane(Object message, int messageType, int optionType, Icon icon, Object[] options, Object initialValue)
Creates an instance of JOptionPane to display a message with the specified message type, icon, and options, with the initially-selected option specified.
JRadioButton(Icon icon)
Creates an initially unselected radio button with the specified image but no text.
JRadioButton(Icon icon, boolean selected)
Creates a radio button with the specified image and selection state, but no text.
JRadioButton(String text, Icon icon)
Creates a radio button that has the specified text and image, and that is initially unselected.
JRadioButton(String text, Icon icon, boolean selected)
Creates a radio button that has the specified text, image, and selection state.
JRadioButtonMenuItem(Icon icon)
Creates a JRadioButtonMenuItem with an icon.
JRadioButtonMenuItem(Icon icon, boolean selected)
Creates a radio button menu item with the specified image and selection state, but no text.
JRadioButtonMenuItem(String text, Icon icon)
Creates a radio button menu item with the specified text and Icon.
JRadioButtonMenuItem(String text, Icon icon, boolean selected)
Creates a radio button menu item that has the specified text, image, and selection state.
JToggleButton(Icon icon)
Creates an initially unselected toggle button with the specified image but no text.
JToggleButton(Icon icon, boolean selected)
Creates a toggle button with the specified image and selection state, but no text.
JToggleButton(String text, Icon icon)
Creates a toggle button that has the specified text and image, and that is initially unselected.
JToggleButton(String text, Icon icon, boolean selected)
Creates a toggle button with the specified text, image, and selection state.

Uses of Icon in javax.swing.border

Fields in javax.swing.border declared as Icon
protected  Icon MatteBorder.tileIcon

Methods in javax.swing.border that return Icon
 Icon MatteBorder.getTileIcon()
Returns the icon used for tiling the border or null if a solid color is being used.

Constructors in javax.swing.border with parameters of type Icon
MatteBorder(Icon tileIcon)
Creates a matte border with the specified tile icon.
MatteBorder(Insets borderInsets, Icon tileIcon)
Creates a matte border with the specified insets and tile icon.
MatteBorder(int top, int left, int bottom, int right, Icon tileIcon)
Creates a matte border with the specified insets and tile icon.

Uses of Icon in javax.swing.colorchooser

Methods in javax.swing.colorchooser that return Icon
abstract Icon | AbstractColorChooserPanel.getLargeDisplayIcon() Returns the large display icon for the panel.
abstract Icon | AbstractColorChooserPanel.getSmallDisplayIcon() Returns the small display icon for the panel.

Uses of Icon in javax.swing.filechooser

Methods in javax.swing.filechooser that return Icon
Icon | FileView.getIcon(File f) The icon that represents this file in the JFileChooser.
Icon | FileSystemView.getSystemIcon(File f) Icon for a file, directory, or folder as it would be displayed in a system file browser.

Uses of Icon in javax.swing.plaf

Classes in javax.swing.plaf that implement Icon
 class IconUIResource
An Icon wrapper class which implements UIResource.

Constructors in javax.swing.plaf with parameters of type Icon
BorderUIResource.MatteBorderUIResource(Icon tileIcon)
BorderUIResource.MatteBorderUIResource(int top, int left, int bottom, int right, Icon tileIcon)
IconUIResource(Icon delegate)
Creates a UIResource icon object which wraps an existing Icon instance.

Uses of Icon in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as Icon
protected Icon | BasicMenuItemUI.arrowIcon
protected Icon | BasicMenuItemUI.checkIcon
protected Icon | BasicInternalFrameTitlePane.closeIcon
protected Icon | BasicTreeUI.collapsedIcon
protected Icon | BasicFileChooserUI.computerIcon
protected Icon | BasicFileChooserUI.detailsViewIcon
protected Icon | BasicFileChooserUI.directoryIcon
protected Icon | BasicTreeUI.expandedIcon
protected Icon | BasicFileChooserUI.fileIcon
protected Icon | BasicFileChooserUI.floppyDriveIcon
protected Icon | BasicFileChooserUI.hardDriveIcon
protected Icon | BasicFileChooserUI.homeFolderIcon
protected Icon | BasicRadioButtonUI.icon
protected Icon | BasicInternalFrameTitlePane.iconIcon
protected Icon | BasicFileChooserUI.listViewIcon
protected Icon | BasicInternalFrameTitlePane.maxIcon
protected Icon | BasicInternalFrameTitlePane.minIcon
protected Icon | BasicFileChooserUI.newFolderIcon
protected Icon | BasicFileChooserUI.upFolderIcon

Fields in javax.swing.plaf.basic with type parameters of type Icon
protected  Hashtable<File,Icon> BasicFileChooserUI.BasicFileView.iconCache

Methods in javax.swing.plaf.basic that return Icon
static Icon | BasicIconFactory.createEmptyFrameIcon()
Icon | BasicFileChooserUI.BasicFileView.getCachedIcon(File f)
static Icon | BasicIconFactory.getCheckBoxIcon()
static Icon | BasicIconFactory.getCheckBoxMenuItemIcon()
Icon | BasicTreeUI.getCollapsedIcon()
Icon | BasicRadioButtonUI.getDefaultIcon()
Icon | BasicTreeUI.getExpandedIcon()
protected Icon | BasicOptionPaneUI.getIcon() Returns the icon from the JOptionPane the receiver is providing the look and feel for, or the default icon as returned from getDefaultIcon.
Icon | BasicFileChooserUI.BasicFileView.getIcon(File f)
protected Icon | BasicTabbedPaneUI.getIconForTab(int tabIndex)
protected Icon | BasicOptionPaneUI.getIconForType(int messageType) Returns the icon to use for the passed in type.
static Icon | BasicIconFactory.getMenuArrowIcon()
static Icon | BasicIconFactory.getMenuItemArrowIcon()
static Icon | BasicIconFactory.getMenuItemCheckIcon()
static Icon | BasicIconFactory.getRadioButtonIcon()
static Icon | BasicIconFactory.getRadioButtonMenuItemIcon()

Methods in javax.swing.plaf.basic with parameters of type Icon
 void BasicFileChooserUI.BasicFileView.cacheIcon(File f, Icon i)
protected  void BasicTreeUI.drawCentered(Component c, Graphics graphics, Icon icon, int x, int y)
protected  Dimension BasicMenuItemUI.getPreferredMenuItemSize(JComponent c, Icon checkIcon, Icon arrowIcon, int defaultTextIconGap)
protected  String BasicLabelUI.layoutCL(JLabel label, FontMetrics fontMetrics, String text, Icon icon, Rectangle viewR, Rectangle iconR, Rectangle textR)
Forwards the call to SwingUtilities.layoutCompoundLabel().
protected  void BasicTabbedPaneUI.layoutLabel(int tabPlacement, FontMetrics metrics, int tabIndex, String title, Icon icon, Rectangle tabRect, Rectangle iconRect, Rectangle textRect, boolean isSelected)
protected  void BasicTabbedPaneUI.paintIcon(Graphics g, int tabPlacement, int tabIndex, Icon icon, Rectangle iconRect, boolean isSelected)
protected  void BasicMenuItemUI.paintMenuItem(Graphics g, JComponent c, Icon checkIcon, Icon arrowIcon, Color background, Color foreground, int defaultTextIconGap)
 void BasicTreeUI.setCollapsedIcon(Icon newG)
 void BasicTreeUI.setExpandedIcon(Icon newG)

Uses of Icon in javax.swing.plaf.metal

Classes in javax.swing.plaf.metal that implement Icon
class | MetalCheckBoxIcon CheckboxIcon implementation for OrganicCheckBoxUI
class | MetalComboBoxIcon This utility class draws the horizontal bars which indicate a MetalComboBox
static class | MetalIconFactory.FileIcon16 Warning: Serialized objects of this class will not be compatible with future Swing releases.
static class | MetalIconFactory.FolderIcon16 Warning: Serialized objects of this class will not be compatible with future Swing releases.
static class | MetalIconFactory.PaletteCloseIcon Defines an icon for Palette close
static class | MetalIconFactory.TreeControlIcon Warning: Serialized objects of this class will not be compatible with future Swing releases.
static class | MetalIconFactory.TreeFolderIcon Warning: Serialized objects of this class will not be compatible with future Swing releases.
static class | MetalIconFactory.TreeLeafIcon

Fields in javax.swing.plaf.metal declared as Icon
protected Icon | MetalComboBoxButton.comboIcon
protected static Icon | MetalSliderUI.horizThumbIcon A default horizontal thumb Icon.
protected Icon | MetalInternalFrameTitlePane.paletteCloseIcon
protected static Icon | MetalSliderUI.vertThumbIcon A default vertical thumb Icon.

Methods in javax.swing.plaf.metal that return Icon
static Icon | MetalIconFactory.getCheckBoxIcon() Returns a checkbox icon.
static Icon | MetalIconFactory.getCheckBoxMenuItemIcon()
Icon | MetalComboBoxButton.getComboIcon()
Icon | MetalLookAndFeel.getDisabledIcon(JComponent component, Icon icon) Returns an Icon with a disabled appearance.
Icon | MetalLookAndFeel.getDisabledSelectedIcon(JComponent component, Icon icon) Returns an Icon for use by disabled components that are also selected.
static Icon | MetalIconFactory.getFileChooserDetailViewIcon()
static Icon | MetalIconFactory.getFileChooserHomeFolderIcon()
static Icon | MetalIconFactory.getFileChooserListViewIcon()
static Icon | MetalIconFactory.getFileChooserNewFolderIcon()
static Icon | MetalIconFactory.getFileChooserUpFolderIcon()
static Icon | MetalIconFactory.getHorizontalSliderThumbIcon()
static Icon | MetalIconFactory.getInternalFrameAltMaximizeIcon(int size)
static Icon | MetalIconFactory.getInternalFrameCloseIcon(int size)
static Icon | MetalIconFactory.getInternalFrameDefaultMenuIcon()
static Icon | MetalIconFactory.getInternalFrameMaximizeIcon(int size)
static Icon | MetalIconFactory.getInternalFrameMinimizeIcon(int size)
static Icon | MetalIconFactory.getMenuArrowIcon()
static Icon | MetalIconFactory.getMenuItemArrowIcon()
static Icon | MetalIconFactory.getMenuItemCheckIcon() Returns an icon to be used by JCheckBoxMenuItem.
static Icon | MetalIconFactory.getRadioButtonIcon()
static Icon | MetalIconFactory.getRadioButtonMenuItemIcon()
static Icon | MetalIconFactory.getTreeComputerIcon()
static Icon | MetalIconFactory.getTreeControlIcon(boolean isCollapsed)
static Icon | MetalIconFactory.getTreeFloppyDriveIcon()
static Icon | MetalIconFactory.getTreeFolderIcon()
static Icon | MetalIconFactory.getTreeHardDriveIcon()
static Icon | MetalIconFactory.getTreeLeafIcon()
static Icon | MetalIconFactory.getVerticalSliderThumbIcon()

Methods in javax.swing.plaf.metal with parameters of type Icon
Icon | MetalLookAndFeel.getDisabledIcon(JComponent component, Icon icon) Returns an Icon with a disabled appearance.
Icon | MetalLookAndFeel.getDisabledSelectedIcon(JComponent component, Icon icon) Returns an Icon for use by disabled components that are also selected.
void | MetalComboBoxButton.setComboIcon(Icon i)

Constructors in javax.swing.plaf.metal with parameters of type Icon
MetalComboBoxButton(JComboBox cb, Icon i, boolean onlyIcon, CellRendererPane pane, JList list)
MetalComboBoxButton(JComboBox cb, Icon i, CellRendererPane pane, JList list)

Uses of Icon in javax.swing.plaf.synth

Methods in javax.swing.plaf.synth that return Icon
 Icon SynthStyle.getIcon(SynthContext context, Object key)
Convenience method to get a specific style property whose value is an Icon.

Methods in javax.swing.plaf.synth with parameters of type Icon
Dimension | SynthGraphicsUtils.getMaximumSize(SynthContext ss, Font font, String text, Icon icon, int hAlign, int vAlign, int hTextPosition, int vTextPosition, int iconTextGap, int mnemonicIndex) Returns the maximum size needed to properly render an icon and text.
Dimension | SynthGraphicsUtils.getMinimumSize(SynthContext ss, Font font, String text, Icon icon, int hAlign, int vAlign, int hTextPosition, int vTextPosition, int iconTextGap, int mnemonicIndex) Returns the minimum size needed to properly render an icon and text.
Dimension | SynthGraphicsUtils.getPreferredSize(SynthContext ss, Font font, String text, Icon icon, int hAlign, int vAlign, int hTextPosition, int vTextPosition, int iconTextGap, int mnemonicIndex) Returns the preferred size needed to properly render an icon and text.
String | SynthGraphicsUtils.layoutText(SynthContext ss, FontMetrics fm, String text, Icon icon, int hAlign, int vAlign, int hTextPosition, int vTextPosition, Rectangle viewR, Rectangle iconR, Rectangle textR, int iconTextGap) Lays out text and an icon returning, by reference, the location to place the icon and text.
void | SynthGraphicsUtils.paintText(SynthContext ss, Graphics g, String text, Icon icon, int hAlign, int vAlign, int hTextPosition, int vTextPosition, int iconTextGap, int mnemonicIndex, int textOffset) Paints an icon and text.

Uses of Icon in javax.swing.text

Methods in javax.swing.text that return Icon
static Icon StyleConstants.getIcon(AttributeSet a)
Gets the icon setting from the attribute list.

Methods in javax.swing.text with parameters of type Icon
static void StyleConstants.setIcon(MutableAttributeSet a, Icon c)
Sets the icon attribute.

Uses of Icon in javax.swing.text.html

Methods in javax.swing.text.html that return Icon
Icon | ImageView.getLoadingImageIcon() Returns the icon to use while in the process of loading the image.
Icon | ImageView.getNoImageIcon() Returns the icon to use if the image couldn't be found.

Uses of Icon in javax.swing.tree

Fields in javax.swing.tree declared as Icon
protected Icon | DefaultTreeCellRenderer.closedIcon Icon used to show non-leaf nodes that aren't expanded.
protected Icon | DefaultTreeCellEditor.editingIcon Icon to use when editing.
protected Icon | DefaultTreeCellRenderer.leafIcon Icon used to show leaf nodes.
protected Icon | DefaultTreeCellRenderer.openIcon Icon used to show non-leaf nodes that are expanded.

Methods in javax.swing.tree that return Icon
Icon | DefaultTreeCellRenderer.getClosedIcon() Returns the icon used to represent non-leaf nodes that are not expanded.
Icon | DefaultTreeCellRenderer.getDefaultClosedIcon() Returns the default icon, for the current laf, that is used to represent non-leaf nodes that are not expanded.
Icon | DefaultTreeCellRenderer.getDefaultLeafIcon() Returns the default icon, for the current laf, that is used to represent leaf nodes.
Icon | DefaultTreeCellRenderer.getDefaultOpenIcon() Returns the default icon, for the current laf, that is used to represent non-leaf nodes that are expanded.
Icon | DefaultTreeCellRenderer.getLeafIcon() Returns the icon used to represent leaf nodes.
Icon | DefaultTreeCellRenderer.getOpenIcon() Returns the icon used to represent non-leaf nodes that are expanded.

Methods in javax.swing.tree with parameters of type Icon
void | DefaultTreeCellRenderer.setClosedIcon(Icon newIcon) Sets the icon used to represent non-leaf nodes that are not expanded.
void | DefaultTreeCellRenderer.setLeafIcon(Icon newIcon) Sets the icon used to represent leaf nodes.
void | DefaultTreeCellRenderer.setOpenIcon(Icon newIcon) Sets the icon used to represent non-leaf nodes that are expanded.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.JComboBox.KeySelectionManager

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.JComboBox.KeySelectionManager

Packages that use JComboBox.KeySelectionManager
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JComboBox.KeySelectionManager in javax.swing

Fields in javax.swing declared as JComboBox.KeySelectionManager
protected  JComboBox.KeySelectionManager JComboBox.keySelectionManager
This protected field is implementation specific.

Methods in javax.swing that return JComboBox.KeySelectionManager
protected JComboBox.KeySelectionManager | JComboBox.createDefaultKeySelectionManager() Returns an instance of the default key-selection manager.
JComboBox.KeySelectionManager | JComboBox.getKeySelectionManager() Returns the list's key-selection manager.

Methods in javax.swing with parameters of type JComboBox.KeySelectionManager
 void JComboBox.setKeySelectionManager(JComboBox.KeySelectionManager aManager)
Sets the object that translates a keyboard character into a list selection.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.ListCellRenderer

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.ListCellRenderer

Packages that use ListCellRenderer
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of ListCellRenderer in javax.swing

Classes in javax.swing that implement ListCellRenderer
class | DefaultListCellRenderer Renders an item in a list.
static class | DefaultListCellRenderer.UIResource A subclass of DefaultListCellRenderer that implements UIResource.

Fields in javax.swing declared as ListCellRenderer
protected  ListCellRenderer JComboBox.renderer
This protected field is implementation specific.

Methods in javax.swing that return ListCellRenderer
ListCellRenderer | JList.getCellRenderer() Returns the object responsible for painting list items.
ListCellRenderer | JComboBox.getRenderer() Returns the renderer used to display the selected item in the JComboBox field.

Methods in javax.swing with parameters of type ListCellRenderer
void | JList.setCellRenderer(ListCellRenderer cellRenderer) Sets the delegate that is used to paint each cell in the list.
void | JComboBox.setRenderer(ListCellRenderer aRenderer) Sets the renderer that paints the list items and the item selected from the list in the JComboBox field.

Uses of ListCellRenderer in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement ListCellRenderer
class | BasicComboBoxRenderer ComboBox renderer
static class | BasicComboBoxRenderer.UIResource A subclass of BasicComboBoxRenderer that implements UIResource.

Methods in javax.swing.plaf.basic that return ListCellRenderer
protected  ListCellRenderer BasicComboBoxUI.createRenderer()
Creates the default renderer that will be used in a non-editiable combo box.

Methods in javax.swing.plaf.basic with parameters of type ListCellRenderer
protected  void BasicListUI.paintCell(Graphics g, int row, Rectangle rowBounds, ListCellRenderer cellRenderer, ListModel dataModel, ListSelectionModel selModel, int leadIndex)
Paint one List cell: compute the relevant state, get the "rubber stamp" cell renderer component, and then use the CellRendererPane to paint it.

Uses of ListCellRenderer in javax.swing.plaf.metal

Classes in javax.swing.plaf.metal that implement ListCellRenderer
protected class | MetalFileChooserUI.FileRenderer
class | MetalFileChooserUI.FilterComboBoxRenderer Render different type sizes and styles.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.ListModel

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.ListModel

Packages that use ListModel
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of ListModel in javax.swing

Subinterfaces of ListModel in javax.swing
interface | ComboBoxModel A data model for a combo box.
interface | MutableComboBoxModel A mutable version of ComboBoxModel.

Classes in javax.swing that implement ListModel
class | AbstractListModel The abstract definition for the data model that provides a List with its contents.
class | DefaultComboBoxModel The default model for combo boxes.
class | DefaultListModel This class loosely implements the java.util.Vector API, in that it implements the 1.1.x version of java.util.Vector, has no collection class support, and notifies the ListDataListeners when changes occur.

Methods in javax.swing that return ListModel
 ListModel JList.getModel()
Returns the data model that holds the list of items displayed by the JList component.

Methods in javax.swing with parameters of type ListModel
 void JList.setModel(ListModel model)
Sets the model that represents the contents or "value" of the list, notifies property change listeners, and then clears the list's selection.

Constructors in javax.swing with parameters of type ListModel
JList(ListModel dataModel)
Constructs a JList that displays elements from the specified, non-null, model.

Uses of ListModel in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement ListModel
 class BasicDirectoryModel
Basic implementation of a file list.

Methods in javax.swing.plaf.basic with parameters of type ListModel
protected  void BasicListUI.paintCell(Graphics g, int row, Rectangle rowBounds, ListCellRenderer cellRenderer, ListModel dataModel, ListSelectionModel selModel, int leadIndex)
Paint one List cell: compute the relevant state, get the "rubber stamp" cell renderer component, and then use the CellRendererPane to paint it.

Uses of ListModel in javax.swing.plaf.metal

Classes in javax.swing.plaf.metal that implement ListModel
protected class | MetalFileChooserUI.DirectoryComboBoxModel Data model for a type-face selection combo-box.
protected class | MetalFileChooserUI.FilterComboBoxModel Data model for a type-face selection combo-box.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.ListSelectionModel

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.ListSelectionModel

Packages that use ListSelectionModel
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of ListSelectionModel in javax.swing

Classes in javax.swing that implement ListSelectionModel
 class DefaultListSelectionModel
Default data model for list selections.

Fields in javax.swing declared as ListSelectionModel
protected  ListSelectionModel JTable.selectionModel
The ListSelectionModel of the table, used to keep track of row selections.

Methods in javax.swing that return ListSelectionModel
protected ListSelectionModel | JTable.createDefaultSelectionModel() Returns the default selection model object, which is a DefaultListSelectionModel.
protected ListSelectionModel | JList.createSelectionModel() Returns an instance of DefaultListSelectionModel; called during construction to initialize the list's selection model property.
ListSelectionModel | JTable.getSelectionModel() Returns the ListSelectionModel that is used to maintain row selection state.
ListSelectionModel | JList.getSelectionModel() Returns the current selection model.

Methods in javax.swing with parameters of type ListSelectionModel
void | JTable.setSelectionModel(ListSelectionModel newModel) Sets the row selection model for this table to newModel and registers for listener notifications from the new selection model.
void | JList.setSelectionModel(ListSelectionModel selectionModel) Sets the selectionModel for the list to a non-null ListSelectionModel implementation.

Constructors in javax.swing with parameters of type ListSelectionModel
JTable(TableModel dm, TableColumnModel cm, ListSelectionModel sm)
Constructs a JTable that is initialized with dm as the data model, cm as the column model, and sm as the selection model.

Uses of ListSelectionModel in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic with parameters of type ListSelectionModel
protected  void BasicListUI.paintCell(Graphics g, int row, Rectangle rowBounds, ListCellRenderer cellRenderer, ListModel dataModel, ListSelectionModel selModel, int leadIndex)
Paint one List cell: compute the relevant state, get the "rubber stamp" cell renderer component, and then use the CellRendererPane to paint it.

Uses of ListSelectionModel in javax.swing.table

Fields in javax.swing.table declared as ListSelectionModel
protected  ListSelectionModel DefaultTableColumnModel.selectionModel
Model for keeping track of column selections

Methods in javax.swing.table that return ListSelectionModel
protected ListSelectionModel | DefaultTableColumnModel.createSelectionModel() Creates a new default list selection model.
ListSelectionModel | DefaultTableColumnModel.getSelectionModel() Returns the ListSelectionModel that is used to maintain column selection state.
ListSelectionModel | TableColumnModel.getSelectionModel() Returns the current selection model.

Methods in javax.swing.table with parameters of type ListSelectionModel
void | DefaultTableColumnModel.setSelectionModel(ListSelectionModel newModel) Sets the selection model for this TableColumnModel to newModel and registers for listener notifications from the new selection model.
void | TableColumnModel.setSelectionModel(ListSelectionModel newModel) Sets the selection model.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.MenuElement

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.MenuElement

Packages that use MenuElement
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of MenuElement in javax.swing

Classes in javax.swing that implement MenuElement
class | JCheckBoxMenuItem A menu item that can be selected or deselected.
class | JMenu An implementation of a menu -- a popup window containing JMenuItems that is displayed when the user selects an item on the JMenuBar.
class | JMenuBar An implementation of a menu bar.
class | JMenuItem An implementation of an item in a menu.
class | JPopupMenu An implementation of a popup menu -- a small window that pops up and displays a series of choices.
class | JRadioButtonMenuItem An implementation of a radio button menu item.

Methods in javax.swing that return MenuElement
MenuElement[] | MenuSelectionManager.getSelectedPath() Returns the path to the currently selected menu item
MenuElement[] | JMenuItem.getSubElements() This method returns an array containing the sub-menu components for this menu component.
MenuElement[] | JPopupMenu.getSubElements() Returns an array of MenuElements containing the submenu for this menu component.
MenuElement[] | JMenuBar.getSubElements() Implemented to be a MenuElement -- returns the menus in this menu bar.
MenuElement[] | JMenu.getSubElements() Returns an array of MenuElements containing the submenu for this menu component.
MenuElement[] | MenuElement.getSubElements() This method should return an array containing the sub-elements for the receiving menu element

Methods in javax.swing with parameters of type MenuElement
void | JMenuItem.processKeyEvent(KeyEvent e, MenuElement[] path, MenuSelectionManager manager) Processes a key event forwarded from the MenuSelectionManager and changes the menu selection, if necessary, by using MenuSelectionManager's API.
void | JPopupMenu.processKeyEvent(KeyEvent e, MenuElement[] path, MenuSelectionManager manager) Processes a key event forwarded from the MenuSelectionManager and changes the menu selection, if necessary, by using MenuSelectionManager's API.
void | JMenuBar.processKeyEvent(KeyEvent e, MenuElement[] path, MenuSelectionManager manager) Implemented to be a MenuElement -- does nothing.
void | MenuElement.processKeyEvent(KeyEvent event, MenuElement[] path, MenuSelectionManager manager) Process a key event.
void | JMenuItem.processMouseEvent(MouseEvent e, MenuElement[] path, MenuSelectionManager manager) Processes a mouse event forwarded from the MenuSelectionManager and changes the menu selection, if necessary, by using the MenuSelectionManager's API.
void | JPopupMenu.processMouseEvent(MouseEvent event, MenuElement[] path, MenuSelectionManager manager) This method is required to conform to the MenuElement interface, but it not implemented.
void | JMenuBar.processMouseEvent(MouseEvent event, MenuElement[] path, MenuSelectionManager manager) Implemented to be a MenuElement -- does nothing.
void | MenuElement.processMouseEvent(MouseEvent event, MenuElement[] path, MenuSelectionManager manager) Processes a mouse event.
void | MenuSelectionManager.setSelectedPath(MenuElement[] path) Changes the selection in the menu hierarchy.

Uses of MenuElement in javax.swing.event

Methods in javax.swing.event that return MenuElement
MenuElement[] | MenuDragMouseEvent.getPath() Returns the path to the selected menu item.
MenuElement[] | MenuKeyEvent.getPath() Returns the path to the menu item referenced by this event.

Constructors in javax.swing.event with parameters of type MenuElement
MenuDragMouseEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger, MenuElement[] p, MenuSelectionManager m)
Constructs a MenuDragMouseEvent object.
MenuDragMouseEvent(Component source, int id, long when, int modifiers, int x, int y, int xAbs, int yAbs, int clickCount, boolean popupTrigger, MenuElement[] p, MenuSelectionManager m)
Constructs a MenuDragMouseEvent object.
MenuKeyEvent(Component source, int id, long when, int modifiers, int keyCode, char keyChar, MenuElement[] p, MenuSelectionManager m)
Constructs a MenuKeyEvent object.

Uses of MenuElement in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement MenuElement
class | BasicComboPopup This is a basic implementation of the ComboPopup interface.
class | BasicInternalFrameTitlePane.SystemMenuBar This class should be treated as a "protected" inner class.

Methods in javax.swing.plaf.basic that return MenuElement
 MenuElement[] BasicMenuItemUI.getPath()

Methods in javax.swing.plaf.basic with parameters of type MenuElement
void | BasicRadioButtonMenuItemUI.processMouseEvent(JMenuItem item, MouseEvent e, MenuElement[] path, MenuSelectionManager manager)
void | BasicCheckBoxMenuItemUI.processMouseEvent(JMenuItem item, MouseEvent e, MenuElement[] path, MenuSelectionManager manager)

Uses of MenuElement in javax.swing.plaf.metal

Classes in javax.swing.plaf.metal that implement MenuElement
 class MetalComboBoxUI.MetalComboPopup
Deprecated. As of Java 2 platform v1.4.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.MutableComboBoxModel

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.MutableComboBoxModel

Packages that use MutableComboBoxModel
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of MutableComboBoxModel in javax.swing

Classes in javax.swing that implement MutableComboBoxModel
 class DefaultComboBoxModel
The default model for combo boxes.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.Renderer

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.Renderer

No usage of javax.swing.Renderer

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.RootPaneContainer

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.RootPaneContainer

Packages that use RootPaneContainer
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of RootPaneContainer in javax.swing

Classes in javax.swing that implement RootPaneContainer
class | JApplet An extended version of java.applet.Applet that adds support for the JFC/Swing component architecture.
class | JDialog The main class for creating a dialog window.
class | JFrame An extended version of java.awt.Frame that adds support for the JFC/Swing component architecture.
class | JInternalFrame A lightweight object that provides many of the features of a native frame, including dragging, closing, becoming an icon, resizing, title display, and support for a menu bar.
class | JWindow A JWindow is a container that can be displayed anywhere on the user's desktop.

Uses of RootPaneContainer in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic that return RootPaneContainer
protected  RootPaneContainer BasicToolBarUI.createFloatingWindow(JToolBar toolbar)
Creates a window which contains the toolbar after it has been dragged out from its container

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.Scrollable

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.Scrollable

Packages that use Scrollable
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of Scrollable in javax.swing

Classes in javax.swing that implement Scrollable
class | JEditorPane A text component to edit various kinds of content.
class | JFormattedTextField JFormattedTextField extends JTextField adding support for formatting arbitrary values, as well as retrieving a particular object once the user has edited the text.
class | JList A component that displays a list of objects and allows the user to select one or more items.
class | JPasswordField JPasswordField is a lightweight component that allows the editing of a single line of text where the view indicates something was typed, but does not show the original characters.
class | JTable The JTable is used to display and edit regular two-dimensional tables of cells.
class | JTextArea A JTextArea is a multi-line area that displays plain text.
class | JTextField JTextField is a lightweight component that allows the editing of a single line of text.
class | JTextPane A text component that can be marked up with attributes that are represented graphically.
class | JTree A control that displays a set of hierarchical data as an outline.

Uses of Scrollable in javax.swing.text

Classes in javax.swing.text that implement Scrollable
 class JTextComponent
JTextComponent is the base class for swing text components.

Uses of Scrollable in javax.swing.tree

Classes in javax.swing.tree that implement Scrollable
 class DefaultTreeCellEditor.DefaultTextField
TextField used when no editor is supplied.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.ScrollPaneConstants

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.ScrollPaneConstants

Packages that use ScrollPaneConstants
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of ScrollPaneConstants in javax.swing

Classes in javax.swing that implement ScrollPaneConstants
class | JScrollPane Provides a scrollable view of a lightweight component.
class | ScrollPaneLayout The layout manager used by JScrollPane.
static class | ScrollPaneLayout.UIResource The UI resource version of ScrollPaneLayout.

Uses of ScrollPaneConstants in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement ScrollPaneConstants
 class BasicScrollPaneUI
A default L&F implementation of ScrollPaneUI.

Uses of ScrollPaneConstants in javax.swing.plaf.metal

Classes in javax.swing.plaf.metal that implement ScrollPaneConstants
 class MetalScrollPaneUI
A Metal L&F implementation of ScrollPaneUI.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.SingleSelectionModel

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.SingleSelectionModel

Packages that use SingleSelectionModel
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of SingleSelectionModel in javax.swing

Classes in javax.swing that implement SingleSelectionModel
 class DefaultSingleSelectionModel
A generic implementation of SingleSelectionModel.

Fields in javax.swing declared as SingleSelectionModel
protected  SingleSelectionModel JTabbedPane.model
The default selection model

Methods in javax.swing that return SingleSelectionModel
SingleSelectionModel | JTabbedPane.getModel() Returns the model associated with this tabbedpane.
SingleSelectionModel | JPopupMenu.getSelectionModel() Returns the model object that handles single selections.
SingleSelectionModel | JMenuBar.getSelectionModel() Returns the model object that handles single selections.

Methods in javax.swing with parameters of type SingleSelectionModel
void | JTabbedPane.setModel(SingleSelectionModel model) Sets the model to be used with this tabbedpane.
void | JPopupMenu.setSelectionModel(SingleSelectionModel model) Sets the model object to handle single selections.
void | JMenuBar.setSelectionModel(SingleSelectionModel model) Sets the model object to handle single selections.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.SpinnerModel

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.SpinnerModel

Packages that use SpinnerModel
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of SpinnerModel in javax.swing

Classes in javax.swing that implement SpinnerModel
class | AbstractSpinnerModel This class provides the ChangeListener part of the SpinnerModel interface that should be suitable for most concrete SpinnerModel implementations.
class | SpinnerDateModel A SpinnerModel for sequences of Dates.
class | SpinnerListModel A simple implementation of SpinnerModel whose values are defined by an array or a List.
class | SpinnerNumberModel A SpinnerModel for sequences of numbers.

Methods in javax.swing that return SpinnerModel
 SpinnerModel JSpinner.getModel()
Returns the SpinnerModel that defines this spinners sequence of values.

Methods in javax.swing with parameters of type SpinnerModel
protected JComponent | JSpinner.createEditor(SpinnerModel model) This method is called by the constructors to create the JComponent that displays the current value of the sequence.
void | JSpinner.setModel(SpinnerModel model) Changes the model that represents the value of this spinner.

Constructors in javax.swing with parameters of type SpinnerModel
JSpinner(SpinnerModel model)
Constructs a complete spinner with pair of next/previous buttons and an editor for the SpinnerModel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.SwingConstants

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.SwingConstants

Packages that use SwingConstants
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of SwingConstants in javax.swing

Classes in javax.swing that implement SwingConstants
class | AbstractButton Defines common behaviors for buttons and menu items.
class | DefaultListCellRenderer Renders an item in a list.
static class | DefaultListCellRenderer.UIResource A subclass of DefaultListCellRenderer that implements UIResource.
class | JButton An implementation of a "push" button.
class | JCheckBox An implementation of a check box -- an item that can be selected or deselected, and which displays its state to the user.
class | JCheckBoxMenuItem A menu item that can be selected or deselected.
class | JFormattedTextField JFormattedTextField extends JTextField adding support for formatting arbitrary values, as well as retrieving a particular object once the user has edited the text.
class | JLabel A display area for a short text string or an image, or both.
class | JMenu An implementation of a menu -- a popup window containing JMenuItems that is displayed when the user selects an item on the JMenuBar.
class | JMenuItem An implementation of an item in a menu.
class | JPasswordField JPasswordField is a lightweight component that allows the editing of a single line of text where the view indicates something was typed, but does not show the original characters.
static class | JPopupMenu.Separator A popup menu-specific separator.
class | JProgressBar A component that visually displays the progress of some task.
class | JRadioButton An implementation of a radio button -- an item that can be selected or deselected, and which displays its state to the user.
class | JRadioButtonMenuItem An implementation of a radio button menu item.
class | JSeparator JSeparator provides a general purpose component for implementing divider lines - most commonly used as a divider between menu items that breaks them up into logical groupings.
class | JSlider A component that lets the user graphically select a value by sliding a knob within a bounded interval.
class | JTabbedPane A component that lets the user switch between a group of components by clicking on a tab with a given title and/or icon.
class | JTextField JTextField is a lightweight component that allows the editing of a single line of text.
class | JToggleButton An implementation of a two-state button.
class | JToolBar JToolBar provides a component that is useful for displaying commonly used Actions or controls.
static class | JToolBar.Separator A toolbar-specific separator.
class | SwingUtilities A collection of utility methods for Swing.

Uses of SwingConstants in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement SwingConstants
class | BasicArrowButton JButton object that draws a scaled Arrow in one of the cardinal directions.
class | BasicComboBoxRenderer ComboBox renderer
static class | BasicComboBoxRenderer.UIResource A subclass of BasicComboBoxRenderer that implements UIResource.
protected class | BasicInternalFrameUI.BorderListener Listens for border adjustments.
class | BasicScrollBarUI Implementation of ScrollBarUI for the Basic Look and Feel
class | BasicTabbedPaneUI A Basic L&F implementation of TabbedPaneUI.
class | BasicToolBarUI A Basic L&F implementation of ToolBarUI.

Uses of SwingConstants in javax.swing.plaf.metal

Classes in javax.swing.plaf.metal that implement SwingConstants
static class | MetalBorders.ToolBarBorder
class | MetalComboBoxButton JButton subclass to help out MetalComboBoxUI
protected class | MetalFileChooserUI.FileRenderer
class | MetalFileChooserUI.FilterComboBoxRenderer Render different type sizes and styles.
class | MetalScrollBarUI Implementation of ScrollBarUI for the Metal Look and Feel
class | MetalScrollButton JButton object for Metal scrollbar arrows.
class | MetalTabbedPaneUI The Metal subclass of BasicTabbedPaneUI.
class | MetalToolBarUI A Metal Look and Feel implementation of ToolBarUI.

Uses of SwingConstants in javax.swing.table

Classes in javax.swing.table that implement SwingConstants
class | DefaultTableCellRenderer The standard class for rendering (displaying) individual cells in a JTable.
static class | DefaultTableCellRenderer.UIResource A subclass of DefaultTableCellRenderer that implements UIResource.

Uses of SwingConstants in javax.swing.text

Classes in javax.swing.text that implement SwingConstants
class | AsyncBoxView A box that does layout asynchronously.
class | BoxView A view that arranges its children into a box shape by tiling its children along an axis.
class | ComponentView Component decorator that implements the view interface.
class | CompositeView CompositeView is an abstract View implementation which manages one or more child views.
class | FieldView Extends the multi-line plain text view to be suitable for a single-line editor view.
class | FlowView A View that tries to flow it's children into some partially constrained space.
class | GlyphView A GlyphView is a styled chunk of text that represents a view mapped over an element in the text model.
class | IconView Icon decorator that implements the view interface.
class | LabelView A LabelView is a styled chunk of text that represents a view mapped over an element in the text model.
class | ParagraphView View of a simple line-wrapping paragraph that supports multiple fonts, colors, components, icons, etc.
class | PasswordView Implements a View suitable for use in JPasswordField UI implementations.
class | PlainView Implements View interface for a simple multi-line text view that has text in one font and color.
class | TableView Implements View interface for a table, that is composed of an element structure where the child elements of the element this view is responsible for represent rows and the child elements of the row elements are cells.
class | TableView.TableCell Deprecated. A table cell can now be any View implementation.
class | TableView.TableRow View of a row in a row-centric table.
class | View A very important part of the text package is the View class.
class | WrappedPlainView View of plain text (text with only one font and color) that does line-wrapping.
class | ZoneView ZoneView is a View implementation that creates zones for which the child views are not created or stored until they are needed for display or model/view translations.

Uses of SwingConstants in javax.swing.text.html

Classes in javax.swing.text.html that implement SwingConstants
class | BlockView A view implementation to display a block (as a box) with CSS specifications.
class | FormView Component decorator that implements the view interface for form elements, <input>, <textarea>, and <select>.
class | ImageView View of an Image, intended to support the HTML <IMG> tag.
class | InlineView Displays the inline element styles based upon css attributes.
class | ListView A view implementation to display an html list
class | ObjectView Component decorator that implements the view interface for <object> elements.

Uses of SwingConstants in javax.swing.tree

Classes in javax.swing.tree that implement SwingConstants
class | DefaultTreeCellEditor.DefaultTextField TextField used when no editor is supplied.
class | DefaultTreeCellRenderer Displays an entry in a tree.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.UIDefaults.ActiveValue

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.UIDefaults.ActiveValue

No usage of javax.swing.UIDefaults.ActiveValue

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.UIDefaults.LazyValue

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.UIDefaults.LazyValue

Packages that use UIDefaults.LazyValue
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of UIDefaults.LazyValue in javax.swing

Classes in javax.swing that implement UIDefaults.LazyValue
static class | UIDefaults.LazyInputMap LazyInputMap will create a InputMap in its createValue method.
static class | UIDefaults.ProxyLazyValue This class provides an implementation of LazyValue which can be used to delay loading of the Class for the instance to be created.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.WindowConstants

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.WindowConstants

Packages that use WindowConstants
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of WindowConstants in javax.swing

Classes in javax.swing that implement WindowConstants
class | JDialog The main class for creating a dialog window.
class | JFrame An extended version of java.awt.Frame that adds support for the JFC/Swing component architecture.
class | JInternalFrame A lightweight object that provides many of the features of a native frame, including dragging, closing, becoming an icon, resizing, title display, and support for a menu bar.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


colorchooser

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.swing.colorchooser

Contains classes and interfaces used by the JColorChooser component.

See:
Description

Interface Summary
ColorSelectionModel A model that supports selecting a Color.

Class Summary
AbstractColorChooserPanel | This is the abstract superclass for color choosers.
ColorChooserComponentFactory | A class designed to produce preconfigured "accessory" objects to insert into color choosers.
DefaultColorSelectionModel | A generic implementation of ColorSelectionModel.

Package javax.swing.colorchooser Description

Contains classes and interfaces used by the JColorChooser component.

Note: Most of the Swing API is not thread safe. For details, see Threads and Swing, a section in The Java Tutorial.

Related Documentation

This document forms the complete API specification. For overviews, tutorials, examples, guides, and tool documentation, please see:
  • How to Use Color Choosers, a section in The Java Tutorial
  • Internationalization Documentation
  • Input Method Framework Documentation

Since:
1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.swing.colorchooser Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.swing.colorchooser

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.swing.colorchooser.ColorChooserComponentFactory
    • java.awt.Component (implements java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable)
      • java.awt.Container
        • javax.swing.JComponent (implements java.io.Serializable)
          • javax.swing.JPanel (implements javax.accessibility.Accessible)
            • javax.swing.colorchooser.AbstractColorChooserPanel
    • javax.swing.colorchooser.DefaultColorSelectionModel (implements javax.swing.colorchooser.ColorSelectionModel, java.io.Serializable)

Interface Hierarchy

  • javax.swing.colorchooser.ColorSelectionModel
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.swing.colorchooser

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.swing.colorchooser

Packages that use javax.swing.colorchooser
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.colorchooser | Contains classes and interfaces used by the JColorChooser component.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Classes in javax.swing.colorchooser used by javax.swing
AbstractColorChooserPanel
This is the abstract superclass for color choosers.
ColorSelectionModel
A model that supports selecting a Color.

Classes in javax.swing.colorchooser used by javax.swing.colorchooser
AbstractColorChooserPanel
This is the abstract superclass for color choosers.
ColorSelectionModel
A model that supports selecting a Color.

Classes in javax.swing.colorchooser used by javax.swing.plaf.basic
AbstractColorChooserPanel
This is the abstract superclass for color choosers.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AbstractColorChooserPanel

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.colorchooser
Class AbstractColorChooserPanel

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JPanel
                    extended by  javax.swing.colorchooser.AbstractColorChooserPanel
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public abstract class AbstractColorChooserPanel
extends JPanel

This is the abstract superclass for color choosers. If you want to add a new color chooser panel into a JColorChooser, subclass this class.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JPanel
JPanel.AccessibleJPanel
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
AbstractColorChooserPanel()
Method Summary
protected abstract void | buildChooser() Builds a new chooser panel.
protected Color | getColorFromModel() Returns the color that is currently selected.
ColorSelectionModel | getColorSelectionModel() Returns the model that the chooser panel is editing.
int | getDisplayedMnemonicIndex() Provides a hint to the look and feel as to the index of the character in getDisplayName that should be visually identified as the mnemonic.
abstract String | getDisplayName() Returns a string containing the display name of the panel.
abstract Icon | getLargeDisplayIcon() Returns the large display icon for the panel.
int | getMnemonic() Provides a hint to the look and feel as to the KeyEvent.VK constant that can be used as a mnemonic to access the panel.
abstract Icon | getSmallDisplayIcon() Returns the small display icon for the panel.
void | installChooserPanel(JColorChooser enclosingChooser) Invoked when the panel is added to the chooser.
void | paint(Graphics g) Draws the panel.
void | uninstallChooserPanel(JColorChooser enclosingChooser) Invoked when the panel is removed from the chooser.
abstract void | updateChooser() Invoked automatically when the model's state changes.
Methods inherited from class javax.swing.JPanel
getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractColorChooserPanel

public AbstractColorChooserPanel()
Method Detail

updateChooser

public abstract void updateChooser()
Invoked automatically when the model's state changes. It is also called by installChooserPanel to allow you to set up the initial state of your chooser. Override this method to update your ChooserPanel.

buildChooser

protected abstract void buildChooser()
Builds a new chooser panel.

getDisplayName

public abstract String getDisplayName()
Returns a string containing the display name of the panel.

Returns:
the name of the display panel

getMnemonic

public int getMnemonic()
Provides a hint to the look and feel as to the KeyEvent.VK constant that can be used as a mnemonic to access the panel. A return value <= 0="0" indicates="indicates" there="there" is="is" no="no" mnemonic.="mnemonic." The return value here is a hint, it is ultimately up to the look and feel to honor the return value in some meaningful way.

This implementation returns 0, indicating the AbstractColorChooserPanel does not support a mnemonic, subclasses wishing a mnemonic will need to override this.

Returns:
KeyEvent.VK constant identifying the mnemonic; <= 0="0" for="for" no="no" mnemonicSince:
1.4
See Also:
getDisplayedMnemonicIndex()

getDisplayedMnemonicIndex

public int getDisplayedMnemonicIndex()
Provides a hint to the look and feel as to the index of the character in getDisplayName that should be visually identified as the mnemonic. The look and feel should only use this if getMnemonic returns a value > 0.

The return value here is a hint, it is ultimately up to the look and feel to honor the return value in some meaningful way. For example, a look and feel may wish to render each AbstractColorChooserPanel in a JTabbedPane, and further use this return value to underline a character in the getDisplayName.

This implementation returns -1, indicating the AbstractColorChooserPanel does not support a mnemonic, subclasses wishing a mnemonic will need to override this.

Returns:
Character index to render mnemonic for; -1 to provide no visual identifier for this panel.
Since:
1.4
See Also:
getMnemonic()

getSmallDisplayIcon

public abstract Icon getSmallDisplayIcon()
Returns the small display icon for the panel.

Returns:
the small display icon

getLargeDisplayIcon

public abstract Icon getLargeDisplayIcon()
Returns the large display icon for the panel.

Returns:
the large display icon

installChooserPanel

public void installChooserPanel(JColorChooser enclosingChooser)
Invoked when the panel is added to the chooser. If you override this, be sure to call super.

Parameters:
enclosingChooser - the panel to be added
Throws:
RuntimeException - if the chooser panel has already been installed

uninstallChooserPanel

public void uninstallChooserPanel(JColorChooser enclosingChooser)
Invoked when the panel is removed from the chooser. If override this, be sure to call super.

getColorSelectionModel

public ColorSelectionModel getColorSelectionModel()
Returns the model that the chooser panel is editing.

Returns:
the ColorSelectionModel model this panel is editing

getColorFromModel

protected Color getColorFromModel()
Returns the color that is currently selected.

Returns:
the Color that is selected

paint

public void paint(Graphics g)
Draws the panel.

Overrides:
paint in class JComponent
Parameters:
g - the Graphics object
See Also:
JComponent.paintComponent(java.awt.Graphics),
JComponent.paintBorder(java.awt.Graphics),
JComponent.paintChildren(java.awt.Graphics),
JComponent.getComponentGraphics(java.awt.Graphics),
JComponent.repaint(long, int, int, int, int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.swing.colorchooser.AbstractColorChooserPanel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.colorchooser.AbstractColorChooserPanel

Packages that use AbstractColorChooserPanel
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.colorchooser | Contains classes and interfaces used by the JColorChooser component.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of AbstractColorChooserPanel in javax.swing

Methods in javax.swing that return AbstractColorChooserPanel
AbstractColorChooserPanel[] | JColorChooser.getChooserPanels() Returns the specified color panels.
AbstractColorChooserPanel | JColorChooser.removeChooserPanel(AbstractColorChooserPanel panel) Removes the Color Panel specified.

Methods in javax.swing with parameters of type AbstractColorChooserPanel
void | JColorChooser.addChooserPanel(AbstractColorChooserPanel panel) Adds a color chooser panel to the color chooser.
AbstractColorChooserPanel | JColorChooser.removeChooserPanel(AbstractColorChooserPanel panel) Removes the Color Panel specified.
void | JColorChooser.setChooserPanels(AbstractColorChooserPanel[] panels) Specifies the Color Panels used to choose a color value.

Uses of AbstractColorChooserPanel in javax.swing.colorchooser

Methods in javax.swing.colorchooser that return AbstractColorChooserPanel
static AbstractColorChooserPanel[] ColorChooserComponentFactory.getDefaultChooserPanels()

Uses of AbstractColorChooserPanel in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as AbstractColorChooserPanel
protected  AbstractColorChooserPanel[] BasicColorChooserUI.defaultChoosers

Methods in javax.swing.plaf.basic that return AbstractColorChooserPanel
protected  AbstractColorChooserPanel[] BasicColorChooserUI.createDefaultChoosers()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.colorchooser.ColorChooserComponentFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.colorchooser.ColorChooserComponentFactory

No usage of javax.swing.colorchooser.ColorChooserComponentFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.colorchooser.DefaultColorSelectionModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.colorchooser.DefaultColorSelectionModel

No usage of javax.swing.colorchooser.DefaultColorSelectionModel

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.colorchooser.ColorSelectionModel

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.colorchooser.ColorSelectionModel

Packages that use ColorSelectionModel
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.colorchooser | Contains classes and interfaces used by the JColorChooser component.

Uses of ColorSelectionModel in javax.swing

Methods in javax.swing that return ColorSelectionModel
 ColorSelectionModel JColorChooser.getSelectionModel()
Returns the data model that handles color selections.

Methods in javax.swing with parameters of type ColorSelectionModel
 void JColorChooser.setSelectionModel(ColorSelectionModel newModel)
Sets the model containing the selected color.

Constructors in javax.swing with parameters of type ColorSelectionModel
JColorChooser(ColorSelectionModel model)
Creates a color chooser pane with the specified ColorSelectionModel.

Uses of ColorSelectionModel in javax.swing.colorchooser

Classes in javax.swing.colorchooser that implement ColorSelectionModel
 class DefaultColorSelectionModel
A generic implementation of ColorSelectionModel.

Methods in javax.swing.colorchooser that return ColorSelectionModel
 ColorSelectionModel AbstractColorChooserPanel.getColorSelectionModel()
Returns the model that the chooser panel is editing.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ColorChooserComponentFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.colorchooser
Class ColorChooserComponentFactory

java.lang.Object
    extended by  javax.swing.colorchooser.ColorChooserComponentFactory

public class ColorChooserComponentFactory
extends Object

A class designed to produce preconfigured "accessory" objects to insert into color choosers.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Method Summary
static AbstractColorChooserPanel[] | getDefaultChooserPanels()
static JComponent | getPreviewPanel()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getDefaultChooserPanels

public static AbstractColorChooserPanel[] getDefaultChooserPanels()

getPreviewPanel

public static JComponent getPreviewPanel()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ColorSelectionModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.colorchooser
Interface ColorSelectionModel

All Known Implementing Classes:
DefaultColorSelectionModel
public interface ColorSelectionModel

A model that supports selecting a Color.

See Also:
Color

Method Summary
void | addChangeListener(ChangeListener listener) Adds listener as a listener to changes in the model.
Color | getSelectedColor() Returns the selected Color which should be non-null.
void | removeChangeListener(ChangeListener listener) Removes listener as a listener to changes in the model.
void | setSelectedColor(Color color) Sets the selected color to color.

Method Detail

getSelectedColor

Color getSelectedColor()
Returns the selected Color which should be non-null.

Returns:
the selected Color
See Also:
setSelectedColor(java.awt.Color)

setSelectedColor

void setSelectedColor(Color color)
Sets the selected color to color. Note that setting the color to null is undefined and may have unpredictable results. This method fires a state changed event if it sets the current color to a new non-null color.

Parameters:
color - the new Color
See Also:
getSelectedColor(), addChangeListener(javax.swing.event.ChangeListener)

addChangeListener

void addChangeListener(ChangeListener listener)
Adds listener as a listener to changes in the model.

Parameters:
listener - the ChangeListener to be added

removeChangeListener

void removeChangeListener(ChangeListener listener)
Removes listener as a listener to changes in the model.

Parameters:
listener - the ChangeListener to be removed
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultColorSelectionModel

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.colorchooser
Class DefaultColorSelectionModel

java.lang.Object
    extended by  javax.swing.colorchooser.DefaultColorSelectionModel
All Implemented Interfaces:
Serializable, ColorSelectionModel
public class DefaultColorSelectionModel
extends Object
implements ColorSelectionModel, Serializable

A generic implementation of ColorSelectionModel.

See Also:
Color

Field Summary
protected ChangeEvent | changeEvent Only one ChangeEvent is needed per model instance since the event's only (read-only) state is the source property.
protected EventListenerList | listenerList
Constructor Summary
DefaultColorSelectionModel()
Creates a DefaultColorSelectionModel with the current color set to Color.white.
DefaultColorSelectionModel(Color color)
Creates a DefaultColorSelectionModel with the current color set to color, which should be non-null.
Method Summary
void | addChangeListener(ChangeListener l) Adds a ChangeListener to the model.
protected void | fireStateChanged() Runs each ChangeListener's stateChanged method.
ChangeListener[] | getChangeListeners() Returns an array of all the ChangeListeners added to this DefaultColorSelectionModel with addChangeListener.
Color | getSelectedColor() Returns the selected Color which should be non-null.
void | removeChangeListener(ChangeListener l) Removes a ChangeListener from the model.
void | setSelectedColor(Color color) Sets the selected color to color.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

changeEvent

protected transient ChangeEvent changeEvent
Only one ChangeEvent is needed per model instance since the event's only (read-only) state is the source property. The source of events generated here is always "this".

listenerList

protected EventListenerList listenerList
Constructor Detail

DefaultColorSelectionModel

public DefaultColorSelectionModel()
Creates a DefaultColorSelectionModel with the current color set to Color.white. This is the default constructor.

DefaultColorSelectionModel

public DefaultColorSelectionModel(Color color)
Creates a DefaultColorSelectionModel with the current color set to color, which should be non-null. Note that setting the color to null is undefined and may have unpredictable results.

Parameters:
color - the new Color
Method Detail

getSelectedColor

public Color getSelectedColor()
Returns the selected Color which should be non-null.

Specified by:
getSelectedColor in interface ColorSelectionModel
Returns:
the selected Color
See Also:
ColorSelectionModel.setSelectedColor(java.awt.Color)

setSelectedColor

public void setSelectedColor(Color color)
Sets the selected color to color. Note that setting the color to null is undefined and may have unpredictable results. This method fires a state changed event if it sets the current color to a new non-null color; if the new color is the same as the current color, no event is fired.

Specified by:
setSelectedColor in interface ColorSelectionModel
Parameters:
color - the new Color
See Also:
ColorSelectionModel.getSelectedColor(), ColorSelectionModel.addChangeListener(javax.swing.event.ChangeListener)

addChangeListener

public void addChangeListener(ChangeListener l)
Adds a ChangeListener to the model.

Specified by:
addChangeListener in interface ColorSelectionModel
Parameters:
l - the ChangeListener to be added

removeChangeListener

public void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the model.

Specified by:
removeChangeListener in interface ColorSelectionModel
Parameters:
l - the ChangeListener to be removed

getChangeListeners

public ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this DefaultColorSelectionModel with addChangeListener.

Returns:
all of the ChangeListeners added, or an empty array if no listeners have been added
Since:
1.4

fireStateChanged

protected void fireStateChanged()
Runs each ChangeListener's stateChanged method.

See Also:
EventListenerList
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


ComboBoxEditor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface ComboBoxEditor

All Known Implementing Classes:
BasicComboBoxEditor, BasicComboBoxEditor.UIResource, MetalComboBoxEditor, MetalComboBoxEditor.UIResource
public interface ComboBoxEditor

The editor component used for JComboBox components.

Method Summary
void | addActionListener(ActionListener l) Add an ActionListener.
Component | getEditorComponent() Return the component that should be added to the tree hierarchy for this editor
Object | getItem() Return the edited item
void | removeActionListener(ActionListener l) Remove an ActionListener
void | selectAll() Ask the editor to start editing and to select everything
void | setItem(Object anObject) Set the item that should be edited.

Method Detail

getEditorComponent

Component getEditorComponent()
Return the component that should be added to the tree hierarchy for this editor

setItem

void setItem(Object anObject)
Set the item that should be edited. Cancel any editing if necessary

getItem

Object getItem()
Return the edited item

selectAll

void selectAll()
Ask the editor to start editing and to select everything

addActionListener

void addActionListener(ActionListener l)
Add an ActionListener. An action event is generated when the edited item changes

removeActionListener

void removeActionListener(ActionListener l)
Remove an ActionListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ComboBoxModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface ComboBoxModel

All Superinterfaces:
ListModel
All Known Subinterfaces:
MutableComboBoxModel
All Known Implementing Classes:
DefaultComboBoxModel, MetalFileChooserUI.DirectoryComboBoxModel, MetalFileChooserUI.FilterComboBoxModel
public interface ComboBoxModel
extends ListModel

A data model for a combo box. This interface extends ListDataModel and adds the concept of a selected item. The selected item is generally the item which is visible in the combo box display area.

The selected item may not necessarily be managed by the underlying ListModel. This disjoint behavior allows for the temporary storage and retrieval of a selected item in the model.

Method Summary
Object | getSelectedItem() Returns the selected item
void | setSelectedItem(Object anItem) Set the selected item.
Methods inherited from interface javax.swing.ListModel
addListDataListener, getElementAt, getSize, removeListDataListener

Method Detail

setSelectedItem

void setSelectedItem(Object anItem)
Set the selected item. The implementation of this method should notify all registered ListDataListeners that the contents have changed.

Parameters:
anItem - the list object to select or null to clear the selection

getSelectedItem

Object getSelectedItem()
Returns the selected item

Returns:
The selected item or null if there is no selection
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ComponentInputMap

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class ComponentInputMap

java.lang.Object
    extended by  javax.swing.InputMap
        extended by  javax.swing.ComponentInputMap
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
ComponentInputMapUIResource
public class ComponentInputMap
extends InputMap

A ComponentInputMap is an InputMap associated with a particular JComponent. The component is automatically notified whenever the ComponentInputMap changes. ComponentInputMaps are used for WHEN_IN_FOCUSED_WINDOW bindings.

Since:
1.3

Constructor Summary
ComponentInputMap(JComponent component)
Creates a ComponentInputMap associated with the specified component.
Method Summary
void | clear() Removes all the mappings from this object.
JComponent | getComponent() Returns the component the InputMap was created for.
void | put(KeyStroke keyStroke, Object actionMapKey) Adds a binding for keyStroke to actionMapKey.
void | remove(KeyStroke key) Removes the binding for key from this object.
void | setParent(InputMap map) Sets the parent, which must be a ComponentInputMap associated with the same component as this ComponentInputMap.
Methods inherited from class javax.swing.InputMap
allKeys, get, getParent, keys, size
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ComponentInputMap

public ComponentInputMap(JComponent component)
Creates a ComponentInputMap associated with the specified component.

Parameters:
component - a non-null JComponent
Throws:
IllegalArgumentException - if component is null
Method Detail

setParent

public void setParent(InputMap map)
Sets the parent, which must be a ComponentInputMap associated with the same component as this ComponentInputMap.

Overrides:
setParent in class InputMap
Parameters:
map - a ComponentInputMap
Throws:
IllegalArgumentException - if map is not a ComponentInputMap or is not associated with the same component

getComponent

public JComponent getComponent()
Returns the component the InputMap was created for.

put

public void put(KeyStroke keyStroke,
                Object actionMapKey)
Adds a binding for keyStroke to actionMapKey. If actionMapKey is null, this removes the current binding for keyStroke.

Overrides:
put in class InputMap

remove

public void remove(KeyStroke key)
Removes the binding for key from this object.

Overrides:
remove in class InputMap

clear

public void clear()
Removes all the mappings from this object.

Overrides:
clear in class InputMap
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DebugGraphics

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class DebugGraphics

java.lang.Object
    extended by  java.awt.Graphics
        extended by  javax.swing.DebugGraphics

public class DebugGraphics
extends Graphics

Graphics subclass supporting graphics debugging. Overrides most methods from Graphics. DebugGraphics objects are rarely created by hand. They are most frequently created automatically when a JComponent's debugGraphicsOptions are changed using the setDebugGraphicsOptions() method.

NOTE: You must turn off double buffering to use DebugGraphics: RepaintManager repaintManager = RepaintManager.currentManager(component); repaintManager.setDoubleBufferingEnabled(false);

See Also:
JComponent.setDebugGraphicsOptions(int),
RepaintManager.currentManager(java.awt.Component),
RepaintManager.setDoubleBufferingEnabled(boolean)

Field Summary
static int | BUFFERED_OPTION Show buffered operations in a separate Frame.
static int | FLASH_OPTION Flash graphics operations.
static int | LOG_OPTION Log graphics operations.
static int | NONE_OPTION Don't debug graphics operations.
Constructor Summary
DebugGraphics()
Constructs a new debug graphics context that supports slowed down drawing.
DebugGraphics(Graphics graphics)
Constructs a debug graphics context from an existing graphics context that supports slowed down drawing.
DebugGraphics(Graphics graphics, JComponent component)
Constructs a debug graphics context from an existing graphics context that slows down drawing for the specified component.
Method Summary
void | clearRect(int x, int y, int width, int height) Overrides Graphics.clearRect.
void | clipRect(int x, int y, int width, int height) Overrides Graphics.clipRect.
void | copyArea(int x, int y, int width, int height, int destX, int destY) Overrides Graphics.copyArea.
Graphics | create() Overrides Graphics.create to return a DebugGraphics object.
Graphics | create(int x, int y, int width, int height) Overrides Graphics.create to return a DebugGraphics object.
void | dispose() Overrides Graphics.dispose.
void | draw3DRect(int x, int y, int width, int height, boolean raised) Overrides Graphics.draw3DRect.
void | drawArc(int x, int y, int width, int height, int startAngle, int arcAngle) Overrides Graphics.drawArc.
void | drawBytes(byte[] data, int offset, int length, int x, int y) Overrides Graphics.drawBytes.
void | drawChars(char[] data, int offset, int length, int x, int y) Overrides Graphics.drawChars.
boolean | drawImage(Image img, int x, int y, Color bgcolor, ImageObserver observer) Overrides Graphics.drawImage.
boolean | drawImage(Image img, int x, int y, ImageObserver observer) Overrides Graphics.drawImage.
boolean | drawImage(Image img, int x, int y, int width, int height, Color bgcolor, ImageObserver observer) Overrides Graphics.drawImage.
boolean | drawImage(Image img, int x, int y, int width, int height, ImageObserver observer) Overrides Graphics.drawImage.
boolean | drawImage(Image img, int dx1, int dy1, int dx2, int dy2, int sx1, int sy1, int sx2, int sy2, Color bgcolor, ImageObserver observer) Overrides Graphics.drawImage.
boolean | drawImage(Image img, int dx1, int dy1, int dx2, int dy2, int sx1, int sy1, int sx2, int sy2, ImageObserver observer) Overrides Graphics.drawImage.
void | drawLine(int x1, int y1, int x2, int y2) Overrides Graphics.drawLine.
void | drawOval(int x, int y, int width, int height) Overrides Graphics.drawOval.
void | drawPolygon(int[] xPoints, int[] yPoints, int nPoints) Overrides Graphics.drawPolygon.
void | drawPolyline(int[] xPoints, int[] yPoints, int nPoints) Overrides Graphics.drawPolyline.
void | drawRect(int x, int y, int width, int height) Overrides Graphics.drawRect.
void | drawRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight) Overrides Graphics.drawRoundRect.
void | drawString(AttributedCharacterIterator iterator, int x, int y) Overrides Graphics.drawString.
void | drawString(String aString, int x, int y) Overrides Graphics.drawString.
void | fill3DRect(int x, int y, int width, int height, boolean raised) Overrides Graphics.fill3DRect.
void | fillArc(int x, int y, int width, int height, int startAngle, int arcAngle) Overrides Graphics.fillArc.
void | fillOval(int x, int y, int width, int height) Overrides Graphics.fillOval.
void | fillPolygon(int[] xPoints, int[] yPoints, int nPoints) Overrides Graphics.fillPolygon.
void | fillRect(int x, int y, int width, int height) Overrides Graphics.fillRect.
void | fillRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight) Overrides Graphics.fillRoundRect.
static Color | flashColor() Returns the Color used to flash drawing operations.
static int | flashCount() Returns the number of times that drawing operations will flash.
static int | flashTime() Returns the time delay of drawing operation flashing.
Shape | getClip() Overrides Graphics.getClip.
Rectangle | getClipBounds() Overrides Graphics.getClipBounds.
Color | getColor() Returns the Color used for text drawing operations.
int | getDebugOptions() Returns the current debugging options for this DebugGraphics.
Font | getFont() Returns the Font used for text drawing operations.
FontMetrics | getFontMetrics() Overrides Graphics.getFontMetrics.
FontMetrics | getFontMetrics(Font f) Overrides Graphics.getFontMetrics.
boolean | isDrawingBuffer() Returns the drawingBuffer value.
static PrintStream | logStream() Returns the stream to which the DebugGraphics logs drawing operations.
void | setClip(int x, int y, int width, int height) Overrides Graphics.setClip.
void | setClip(Shape clip) Overrides Graphics.setClip.
void | setColor(Color aColor) Sets the color to be used for drawing and filling lines and shapes.
void | setDebugOptions(int options) Enables/disables diagnostic information about every graphics operation.
static void | setFlashColor(Color flashColor) Sets the Color used to flash drawing operations.
static void | setFlashCount(int flashCount) Sets the number of times that drawing operations will flash.
static void | setFlashTime(int flashTime) Sets the time delay of drawing operation flashing.
void | setFont(Font aFont) Sets the Font used for text drawing operations.
static void | setLogStream(PrintStream stream) Sets the stream to which the DebugGraphics logs drawing operations.
void | setPaintMode() Overrides Graphics.setPaintMode.
void | setXORMode(Color aColor) Overrides Graphics.setXORMode.
void | translate(int x, int y) Overrides Graphics.translate.
Methods inherited from class java.awt.Graphics
drawPolygon, fillPolygon, finalize, getClipBounds, getClipRect, hitClip, toString
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

LOG_OPTION

public static final int LOG_OPTION
Log graphics operations.

See Also:
Constant Field Values

FLASH_OPTION

public static final int FLASH_OPTION
Flash graphics operations.

See Also:
Constant Field Values

BUFFERED_OPTION

public static final int BUFFERED_OPTION
Show buffered operations in a separate Frame.

See Also:
Constant Field Values

NONE_OPTION

public static final int NONE_OPTION
Don't debug graphics operations.

See Also:
Constant Field Values
Constructor Detail

DebugGraphics

public DebugGraphics()
Constructs a new debug graphics context that supports slowed down drawing.

DebugGraphics

public DebugGraphics(Graphics graphics,
                     JComponent component)
Constructs a debug graphics context from an existing graphics context that slows down drawing for the specified component.

Parameters:
graphics - the Graphics context to slow down
component - the JComponent to draw slowly

DebugGraphics

public DebugGraphics(Graphics graphics)
Constructs a debug graphics context from an existing graphics context that supports slowed down drawing.

Parameters:
graphics - the Graphics context to slow down
Method Detail

create

public Graphics create()
Overrides Graphics.create to return a DebugGraphics object.

Specified by:
create in class Graphics
Returns:
a new graphics context that is a copy of this graphics context.

create

public Graphics create(int x,
                       int y,
                       int width,
                       int height)
Overrides Graphics.create to return a DebugGraphics object.

Overrides:
create in class Graphics
Parameters:
x - the x coordinate.
y - the y coordinate.
width - the width of the clipping rectangle.
height - the height of the clipping rectangle.
Returns:
a new graphics context.
See Also:
Graphics.translate(int, int), Graphics.clipRect(int, int, int, int)

setFlashColor

public static void setFlashColor(Color flashColor)
Sets the Color used to flash drawing operations.

flashColor

public static Color flashColor()
Returns the Color used to flash drawing operations.

See Also:
setFlashColor(java.awt.Color)

setFlashTime

public static void setFlashTime(int flashTime)
Sets the time delay of drawing operation flashing.

flashTime

public static int flashTime()
Returns the time delay of drawing operation flashing.

See Also:
setFlashTime(int)

setFlashCount

public static void setFlashCount(int flashCount)
Sets the number of times that drawing operations will flash.

flashCount

public static int flashCount()
Returns the number of times that drawing operations will flash.

See Also:
setFlashCount(int)

setLogStream

public static void setLogStream(PrintStream stream)
Sets the stream to which the DebugGraphics logs drawing operations.

logStream

public static PrintStream logStream()
Returns the stream to which the DebugGraphics logs drawing operations.

See Also:
setLogStream(java.io.PrintStream)

setFont

public void setFont(Font aFont)
Sets the Font used for text drawing operations.

Specified by:
setFont in class Graphics
Parameters:
aFont - the font.
See Also:
Graphics.getFont(),
Graphics.drawString(java.lang.String, int, int),
Graphics.drawBytes(byte[], int, int, int, int),
Graphics.drawChars(char[], int, int, int, int)

getFont

public Font getFont()
Returns the Font used for text drawing operations.

Specified by:
getFont in class Graphics
Returns:
this graphics context's current font.
See Also:
setFont(java.awt.Font)

setColor

public void setColor(Color aColor)
Sets the color to be used for drawing and filling lines and shapes.

Specified by:
setColor in class Graphics
Parameters:
aColor - the new rendering color.
See Also:
Color, Graphics.getColor()

getColor

public Color getColor()
Returns the Color used for text drawing operations.

Specified by:
getColor in class Graphics
Returns:
this graphics context's current color.
See Also:
setColor(java.awt.Color)

getFontMetrics

public FontMetrics getFontMetrics()
Overrides Graphics.getFontMetrics.

Overrides:
getFontMetrics in class Graphics
Returns:
the font metrics of this graphics context's current font.
See Also:
Graphics.getFont(), FontMetrics, Graphics.getFontMetrics(Font)

getFontMetrics

public FontMetrics getFontMetrics(Font f)
Overrides Graphics.getFontMetrics.

Specified by:
getFontMetrics in class Graphics
Parameters:
f - the specified font
Returns:
the font metrics for the specified font.
See Also:
Graphics.getFont(), FontMetrics, Graphics.getFontMetrics()

translate

public void translate(int x,
                      int y)
Overrides Graphics.translate.

Specified by:
translate in class Graphics
Parameters:
x - the x coordinate.
y - the y coordinate.

setPaintMode

public void setPaintMode()
Overrides Graphics.setPaintMode.

Specified by:
setPaintMode in class Graphics

setXORMode

public void setXORMode(Color aColor)
Overrides Graphics.setXORMode.

Specified by:
setXORMode in class Graphics
Parameters:
aColor - the XOR alternation color

getClipBounds

public Rectangle getClipBounds()
Overrides Graphics.getClipBounds.

Specified by:
getClipBounds in class Graphics
Returns:
the bounding rectangle of the current clipping area, or null if no clip is set.
See Also:
Graphics.getClip(),
Graphics.clipRect(int, int, int, int),
Graphics.setClip(int, int, int, int),
Graphics.setClip(Shape)

clipRect

public void clipRect(int x,
                     int y,
                     int width,
                     int height)
Overrides Graphics.clipRect.

Specified by:
clipRect in class Graphics
Parameters:
x - the x coordinate of the rectangle to intersect the clip with
y - the y coordinate of the rectangle to intersect the clip with
width - the width of the rectangle to intersect the clip with
height - the height of the rectangle to intersect the clip with
See Also:
Graphics.setClip(int, int, int, int), Graphics.setClip(Shape)

setClip

public void setClip(int x,
                    int y,
                    int width,
                    int height)
Overrides Graphics.setClip.

Specified by:
setClip in class Graphics
Parameters:
x - the x coordinate of the new clip rectangle.
y - the y coordinate of the new clip rectangle.
width - the width of the new clip rectangle.
height - the height of the new clip rectangle.
See Also:
Graphics.clipRect(int, int, int, int),
Graphics.setClip(Shape),
Graphics.getClip()

getClip

public Shape getClip()
Overrides Graphics.getClip.

Specified by:
getClip in class Graphics
Returns:
a Shape object representing the current clipping area, or null if no clip is set.
See Also:
Graphics.getClipBounds(),
Graphics.clipRect(int, int, int, int),
Graphics.setClip(int, int, int, int),
Graphics.setClip(Shape)

setClip

public void setClip(Shape clip)
Overrides Graphics.setClip.

Specified by:
setClip in class Graphics
Parameters:
clip - the Shape to use to set the clip
See Also:
Graphics.getClip(),
Graphics.clipRect(int, int, int, int),
Graphics.setClip(int, int, int, int)

drawRect

public void drawRect(int x,
                     int y,
                     int width,
                     int height)
Overrides Graphics.drawRect.

Overrides:
drawRect in class Graphics
Parameters:
x - the x coordinate of the rectangle to be drawn.
y - the y coordinate of the rectangle to be drawn.
width - the width of the rectangle to be drawn.
height - the height of the rectangle to be drawn.
See Also:
Graphics.fillRect(int, int, int, int), Graphics.clearRect(int, int, int, int)

fillRect

public void fillRect(int x,
                     int y,
                     int width,
                     int height)
Overrides Graphics.fillRect.

Specified by:
fillRect in class Graphics
Parameters:
x - the x coordinate of the rectangle to be filled.
y - the y coordinate of the rectangle to be filled.
width - the width of the rectangle to be filled.
height - the height of the rectangle to be filled.
See Also:
Graphics.clearRect(int, int, int, int), Graphics.drawRect(int, int, int, int)

clearRect

public void clearRect(int x,
                      int y,
                      int width,
                      int height)
Overrides Graphics.clearRect.

Specified by:
clearRect in class Graphics
Parameters:
x - the x coordinate of the rectangle to clear.
y - the y coordinate of the rectangle to clear.
width - the width of the rectangle to clear.
height - the height of the rectangle to clear.
See Also:
Graphics.fillRect(int, int, int, int),
Graphics.drawRect(int, int, int, int),
Graphics.setColor(java.awt.Color),
Graphics.setPaintMode(),
Graphics.setXORMode(java.awt.Color)

drawRoundRect

public void drawRoundRect(int x,
                          int y,
                          int width,
                          int height,
                          int arcWidth,
                          int arcHeight)
Overrides Graphics.drawRoundRect.

Specified by:
drawRoundRect in class Graphics
Parameters:
x - the x coordinate of the rectangle to be drawn.
y - the y coordinate of the rectangle to be drawn.
width - the width of the rectangle to be drawn.
height - the height of the rectangle to be drawn.
arcWidth - the horizontal diameter of the arc at the four corners.
arcHeight - the vertical diameter of the arc at the four corners.
See Also:
Graphics.fillRoundRect(int, int, int, int, int, int)

fillRoundRect

public void fillRoundRect(int x,
                          int y,
                          int width,
                          int height,
                          int arcWidth,
                          int arcHeight)
Overrides Graphics.fillRoundRect.

Specified by:
fillRoundRect in class Graphics
Parameters:
x - the x coordinate of the rectangle to be filled.
y - the y coordinate of the rectangle to be filled.
width - the width of the rectangle to be filled.
height - the height of the rectangle to be filled.
arcWidth - the horizontal diameter of the arc at the four corners.
arcHeight - the vertical diameter of the arc at the four corners.
See Also:
Graphics.drawRoundRect(int, int, int, int, int, int)

drawLine

public void drawLine(int x1,
                     int y1,
                     int x2,
                     int y2)
Overrides Graphics.drawLine.

Specified by:
drawLine in class Graphics
Parameters:
x1 - the first point's x coordinate.
y1 - the first point's y coordinate.
x2 - the second point's x coordinate.
y2 - the second point's y coordinate.

draw3DRect

public void draw3DRect(int x,
                       int y,
                       int width,
                       int height,
                       boolean raised)
Overrides Graphics.draw3DRect.

Overrides:
draw3DRect in class Graphics
Parameters:
x - the x coordinate of the rectangle to be drawn.
y - the y coordinate of the rectangle to be drawn.
width - the width of the rectangle to be drawn.
height - the height of the rectangle to be drawn.
raised - a boolean that determines whether the rectangle appears to be raised above the surface or sunk into the surface.
See Also:
Graphics.fill3DRect(int, int, int, int, boolean)

fill3DRect

public void fill3DRect(int x,
                       int y,
                       int width,
                       int height,
                       boolean raised)
Overrides Graphics.fill3DRect.

Overrides:
fill3DRect in class Graphics
Parameters:
x - the x coordinate of the rectangle to be filled.
y - the y coordinate of the rectangle to be filled.
width - the width of the rectangle to be filled.
height - the height of the rectangle to be filled.
raised - a boolean value that determines whether the rectangle appears to be raised above the surface or etched into the surface.
See Also:
Graphics.draw3DRect(int, int, int, int, boolean)

drawOval

public void drawOval(int x,
                     int y,
                     int width,
                     int height)
Overrides Graphics.drawOval.

Specified by:
drawOval in class Graphics
Parameters:
x - the x coordinate of the upper left corner of the oval to be drawn.
y - the y coordinate of the upper left corner of the oval to be drawn.
width - the width of the oval to be drawn.
height - the height of the oval to be drawn.
See Also:
Graphics.fillOval(int, int, int, int)

fillOval

public void fillOval(int x,
                     int y,
                     int width,
                     int height)
Overrides Graphics.fillOval.

Specified by:
fillOval in class Graphics
Parameters:
x - the x coordinate of the upper left corner of the oval to be filled.
y - the y coordinate of the upper left corner of the oval to be filled.
width - the width of the oval to be filled.
height - the height of the oval to be filled.
See Also:
Graphics.drawOval(int, int, int, int)

drawArc

public void drawArc(int x,
                    int y,
                    int width,
                    int height,
                    int startAngle,
                    int arcAngle)
Overrides Graphics.drawArc.

Specified by:
drawArc in class Graphics
Parameters:
x - the x coordinate of the upper-left corner of the arc to be drawn.
y - the y coordinate of the upper-left corner of the arc to be drawn.
width - the width of the arc to be drawn.
height - the height of the arc to be drawn.
startAngle - the beginning angle.
arcAngle - the angular extent of the arc, relative to the start angle.
See Also:
Graphics.fillArc(int, int, int, int, int, int)

fillArc

public void fillArc(int x,
                    int y,
                    int width,
                    int height,
                    int startAngle,
                    int arcAngle)
Overrides Graphics.fillArc.

Specified by:
fillArc in class Graphics
Parameters:
x - the x coordinate of the upper-left corner of the arc to be filled.
y - the y coordinate of the upper-left corner of the arc to be filled.
width - the width of the arc to be filled.
height - the height of the arc to be filled.
startAngle - the beginning angle.
arcAngle - the angular extent of the arc, relative to the start angle.
See Also:
Graphics.drawArc(int, int, int, int, int, int)

drawPolyline

public void drawPolyline(int[] xPoints,
                         int[] yPoints,
                         int nPoints)
Overrides Graphics.drawPolyline.

Specified by:
drawPolyline in class Graphics
Parameters:
xPoints - an array of x points
yPoints - an array of y points
nPoints - the total number of points
See Also:
Graphics.drawPolygon(int[], int[], int)

drawPolygon

public void drawPolygon(int[] xPoints,
                        int[] yPoints,
                        int nPoints)
Overrides Graphics.drawPolygon.

Specified by:
drawPolygon in class Graphics
Parameters:
xPoints - a an array of x coordinates.
yPoints - a an array of y coordinates.
nPoints - a the total number of points.
See Also:
Graphics.fillPolygon(int[], int[], int), Graphics.drawPolyline(int[], int[], int)

fillPolygon

public void fillPolygon(int[] xPoints,
                        int[] yPoints,
                        int nPoints)
Overrides Graphics.fillPolygon.

Specified by:
fillPolygon in class Graphics
Parameters:
xPoints - a an array of x coordinates.
yPoints - a an array of y coordinates.
nPoints - a the total number of points.
See Also:
Graphics.drawPolygon(int[], int[], int)

drawString

public void drawString(String aString,
                       int x,
                       int y)
Overrides Graphics.drawString.

Specified by:
drawString in class Graphics
Parameters:
aString - the string to be drawn.
x - the x coordinate.
y - the y coordinate.
See Also:
Graphics.drawBytes(byte[], int, int, int, int), Graphics.drawChars(char[], int, int, int, int)

drawString

public void drawString(AttributedCharacterIterator iterator,
                       int x,
                       int y)
Overrides Graphics.drawString.

Specified by:
drawString in class Graphics
Parameters:
iterator - the iterator whose text is to be drawn
x - the x coordinate.
y - the y coordinate.
See Also:
Graphics.drawBytes(byte[], int, int, int, int), Graphics.drawChars(char[], int, int, int, int)

drawBytes

public void drawBytes(byte[] data,
                      int offset,
                      int length,
                      int x,
                      int y)
Overrides Graphics.drawBytes.

Overrides:
drawBytes in class Graphics
Parameters:
data - the data to be drawn
offset - the start offset in the data
length - the number of bytes that are drawn
x - the x coordinate of the baseline of the text
y - the y coordinate of the baseline of the text
See Also:
Graphics.drawChars(char[], int, int, int, int), Graphics.drawString(java.lang.String, int, int)

drawChars

public void drawChars(char[] data,
                      int offset,
                      int length,
                      int x,
                      int y)
Overrides Graphics.drawChars.

Overrides:
drawChars in class Graphics
Parameters:
data - the array of characters to be drawn
offset - the start offset in the data
length - the number of characters to be drawn
x - the x coordinate of the baseline of the text
y - the y coordinate of the baseline of the text
See Also:
Graphics.drawBytes(byte[], int, int, int, int), Graphics.drawString(java.lang.String, int, int)

drawImage

public boolean drawImage(Image img,
                         int x,
                         int y,
                         ImageObserver observer)
Overrides Graphics.drawImage.

Specified by:
drawImage in class Graphics
Parameters:
img - the specified image to be drawn. This method does nothing if img is null.
x - the x coordinate.
y - the y coordinate.
observer - object to be notified as more of the image is converted.
Returns:
false if the image pixels are still changing; true otherwise.
See Also:
Image, ImageObserver, ImageObserver.imageUpdate(java.awt.Image, int, int, int, int, int)

drawImage

public boolean drawImage(Image img,
                         int x,
                         int y,
                         int width,
                         int height,
                         ImageObserver observer)
Overrides Graphics.drawImage.

Specified by:
drawImage in class Graphics
Parameters:
img - the specified image to be drawn. This method does nothing if img is null.
x - the x coordinate.
y - the y coordinate.
width - the width of the rectangle.
height - the height of the rectangle.
observer - object to be notified as more of the image is converted.
Returns:
false if the image pixels are still changing; true otherwise.
See Also:
Image, ImageObserver, ImageObserver.imageUpdate(java.awt.Image, int, int, int, int, int)

drawImage

public boolean drawImage(Image img,
                         int x,
                         int y,
                         Color bgcolor,
                         ImageObserver observer)
Overrides Graphics.drawImage.

Specified by:
drawImage in class Graphics
Parameters:
img - the specified image to be drawn. This method does nothing if img is null.
x - the x coordinate.
y - the y coordinate.
bgcolor - the background color to paint under the non-opaque portions of the image.
observer - object to be notified as more of the image is converted.
Returns:
false if the image pixels are still changing; true otherwise.
See Also:
Image, ImageObserver, ImageObserver.imageUpdate(java.awt.Image, int, int, int, int, int)

drawImage

public boolean drawImage(Image img,
                         int x,
                         int y,
                         int width,
                         int height,
                         Color bgcolor,
                         ImageObserver observer)
Overrides Graphics.drawImage.

Specified by:
drawImage in class Graphics
Parameters:
img - the specified image to be drawn. This method does nothing if img is null.
x - the x coordinate.
y - the y coordinate.
width - the width of the rectangle.
height - the height of the rectangle.
bgcolor - the background color to paint under the non-opaque portions of the image.
observer - object to be notified as more of the image is converted.
Returns:
false if the image pixels are still changing; true otherwise.
See Also:
Image, ImageObserver, ImageObserver.imageUpdate(java.awt.Image, int, int, int, int, int)

drawImage

public boolean drawImage(Image img,
                         int dx1,
                         int dy1,
                         int dx2,
                         int dy2,
                         int sx1,
                         int sy1,
                         int sx2,
                         int sy2,
                         ImageObserver observer)
Overrides Graphics.drawImage.

Specified by:
drawImage in class Graphics
Parameters:
img - the specified image to be drawn. This method does nothing if img is null.
dx1 - the x coordinate of the first corner of the destination rectangle.
dy1 - the y coordinate of the first corner of the destination rectangle.
dx2 - the x coordinate of the second corner of the destination rectangle.
dy2 - the y coordinate of the second corner of the destination rectangle.
sx1 - the x coordinate of the first corner of the source rectangle.
sy1 - the y coordinate of the first corner of the source rectangle.
sx2 - the x coordinate of the second corner of the source rectangle.
sy2 - the y coordinate of the second corner of the source rectangle.
observer - object to be notified as more of the image is scaled and converted.
Returns:
false if the image pixels are still changing; true otherwise.
See Also:
Image, ImageObserver, ImageObserver.imageUpdate(java.awt.Image, int, int, int, int, int)

drawImage

public boolean drawImage(Image img,
                         int dx1,
                         int dy1,
                         int dx2,
                         int dy2,
                         int sx1,
                         int sy1,
                         int sx2,
                         int sy2,
                         Color bgcolor,
                         ImageObserver observer)
Overrides Graphics.drawImage.

Specified by:
drawImage in class Graphics
Parameters:
img - the specified image to be drawn. This method does nothing if img is null.
dx1 - the x coordinate of the first corner of the destination rectangle.
dy1 - the y coordinate of the first corner of the destination rectangle.
dx2 - the x coordinate of the second corner of the destination rectangle.
dy2 - the y coordinate of the second corner of the destination rectangle.
sx1 - the x coordinate of the first corner of the source rectangle.
sy1 - the y coordinate of the first corner of the source rectangle.
sx2 - the x coordinate of the second corner of the source rectangle.
sy2 - the y coordinate of the second corner of the source rectangle.
bgcolor - the background color to paint under the non-opaque portions of the image.
observer - object to be notified as more of the image is scaled and converted.
Returns:
false if the image pixels are still changing; true otherwise.
See Also:
Image, ImageObserver, ImageObserver.imageUpdate(java.awt.Image, int, int, int, int, int)

copyArea

public void copyArea(int x,
                     int y,
                     int width,
                     int height,
                     int destX,
                     int destY)
Overrides Graphics.copyArea.

Specified by:
copyArea in class Graphics
Parameters:
x - the x coordinate of the source rectangle.
y - the y coordinate of the source rectangle.
width - the width of the source rectangle.
height - the height of the source rectangle.
destX - the horizontal distance to copy the pixels.
destY - the vertical distance to copy the pixels.

dispose

public void dispose()
Overrides Graphics.dispose.

Specified by:
dispose in class Graphics
See Also:
Graphics.finalize(),
Component.paint(java.awt.Graphics),
Component.update(java.awt.Graphics),
Component.getGraphics(),
Graphics.create()

isDrawingBuffer

public boolean isDrawingBuffer()
Returns the drawingBuffer value.

Returns:
true if this object is drawing from a Buffer

setDebugOptions

public void setDebugOptions(int options)
Enables/disables diagnostic information about every graphics operation. The value of options indicates how this information should be displayed. LOG_OPTION causes a text message to be printed. FLASH_OPTION causes the drawing to flash several times. BUFFERED_OPTION creates a new Frame that shows each operation on an offscreen buffer. The value of options is bitwise OR'd into the current value. To disable debugging use NONE_OPTION.

getDebugOptions

public int getDebugOptions()
Returns the current debugging options for this DebugGraphics.

See Also:
setDebugOptions(int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultBoundedRangeModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class DefaultBoundedRangeModel

java.lang.Object
    extended by  javax.swing.DefaultBoundedRangeModel
All Implemented Interfaces:
Serializable, BoundedRangeModel
public class DefaultBoundedRangeModel
extends Object
implements BoundedRangeModel, Serializable

A generic implementation of BoundedRangeModel.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
BoundedRangeModel

Field Summary
protected ChangeEvent | changeEvent Only one ChangeEvent is needed per model instance since the event's only (read-only) state is the source property.
protected EventListenerList | listenerList The listeners waiting for model changes.
Constructor Summary
DefaultBoundedRangeModel()
Initializes all of the properties with default values.
DefaultBoundedRangeModel(int value, int extent, int min, int max)
Initializes value, extent, minimum and maximum.
Method Summary
 void addChangeListener(ChangeListener l)
Adds a ChangeListener.
protected  void fireStateChanged()
Runs each ChangeListener's stateChanged method.
 ChangeListener[] getChangeListeners()
Returns an array of all the change listeners registered on this DefaultBoundedRangeModel.
 int getExtent()
Returns the model's extent.
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this model.
 int getMaximum()
Returns the model's maximum.
 int getMinimum()
Returns the model's minimum.
 int getValue()
Returns the model's current value.
 boolean getValueIsAdjusting()
Returns true if the value is in the process of changing as a result of actions being taken by the user.
 void removeChangeListener(ChangeListener l)
Removes a ChangeListener.
 void setExtent(int n)
Sets the extent to n after ensuring that n is greater than or equal to zero and falls within the model's constraints:
 void setMaximum(int n)
Sets the maximum to n after ensuring that n that the other three properties obey the model's constraints:
 void setMinimum(int n)
Sets the minimum to n after ensuring that n that the other three properties obey the model's constraints:
 void setRangeProperties(int newValue, int newExtent, int newMin, int newMax, boolean adjusting)
Sets all of the BoundedRangeModel properties after forcing the arguments to obey the usual constraints:
 void setValue(int n)
Sets the current value of the model.
 void setValueIsAdjusting(boolean b)
Sets the valueIsAdjusting property.
 String toString()
Returns a string that displays all of the BoundedRangeModel properties.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

changeEvent

protected transient ChangeEvent changeEvent
Only one ChangeEvent is needed per model instance since the event's only (read-only) state is the source property. The source of events generated here is always "this".

listenerList

protected EventListenerList listenerList
The listeners waiting for model changes.

Constructor Detail

DefaultBoundedRangeModel

public DefaultBoundedRangeModel()
Initializes all of the properties with default values. Those values are:
  • value = 0
  • extent = 0
  • minimum = 0
  • maximum = 100
  • adjusting = false

DefaultBoundedRangeModel

public DefaultBoundedRangeModel(int value,
                                int extent,
                                int min,
                                int max)
Initializes value, extent, minimum and maximum. Adjusting is false. Throws an IllegalArgumentException if the following constraints aren't satisfied:
 min <= value <= value+extent <= max

Method Detail

getValue

public int getValue()
Returns the model's current value.

Specified by:
getValue in interface BoundedRangeModel
Returns:
the model's current value
See Also:
setValue(int), BoundedRangeModel.getValue()

getExtent

public int getExtent()
Returns the model's extent.

Specified by:
getExtent in interface BoundedRangeModel
Returns:
the model's extent
See Also:
setExtent(int), BoundedRangeModel.getExtent()

getMinimum

public int getMinimum()
Returns the model's minimum.

Specified by:
getMinimum in interface BoundedRangeModel
Returns:
the model's minimum
See Also:
setMinimum(int), BoundedRangeModel.getMinimum()

getMaximum

public int getMaximum()
Returns the model's maximum.

Specified by:
getMaximum in interface BoundedRangeModel
Returns:
the model's maximum
See Also:
setMaximum(int), BoundedRangeModel.getMaximum()

setValue

public void setValue(int n)
Sets the current value of the model. For a slider, that determines where the knob appears. Ensures that the new value, n falls within the model's constraints:
     minimum <= value <= value+extent <= maximum

Specified by:
setValue in interface BoundedRangeModel
Parameters:
n - the model's new value
See Also:
BoundedRangeModel.setValue(int)

setExtent

public void setExtent(int n)
Sets the extent to n after ensuring that n is greater than or equal to zero and falls within the model's constraints:
     minimum <= value <= value+extent <= maximum

Specified by:
setExtent in interface BoundedRangeModel
Parameters:
n - the model's new extent
See Also:
BoundedRangeModel.setExtent(int)

setMinimum

public void setMinimum(int n)
Sets the minimum to n after ensuring that n that the other three properties obey the model's constraints:
     minimum <= value <= value+extent <= maximum

Specified by:
setMinimum in interface BoundedRangeModel
Parameters:
n - the model's new minimum
See Also:
getMinimum(), BoundedRangeModel.setMinimum(int)

setMaximum

public void setMaximum(int n)
Sets the maximum to n after ensuring that n that the other three properties obey the model's constraints:
     minimum <= value <= value+extent <= maximum

Specified by:
setMaximum in interface BoundedRangeModel
Parameters:
n - the model's new maximum
See Also:
BoundedRangeModel.setMaximum(int)

setValueIsAdjusting

public void setValueIsAdjusting(boolean b)
Sets the valueIsAdjusting property.

Specified by:
setValueIsAdjusting in interface BoundedRangeModel
Parameters:
b - true if the upcoming changes to the value property are part of a series
See Also:
getValueIsAdjusting(), setValue(int), BoundedRangeModel.setValueIsAdjusting(boolean)

getValueIsAdjusting

public boolean getValueIsAdjusting()
Returns true if the value is in the process of changing as a result of actions being taken by the user.

Specified by:
getValueIsAdjusting in interface BoundedRangeModel
Returns:
the value of the valueIsAdjusting property
See Also:
setValue(int), BoundedRangeModel.getValueIsAdjusting()

setRangeProperties

public void setRangeProperties(int newValue,
                               int newExtent,
                               int newMin,
                               int newMax,
                               boolean adjusting)
Sets all of the BoundedRangeModel properties after forcing the arguments to obey the usual constraints:
     minimum <= value <= value+extent <= maximum

At most, one ChangeEvent is generated.

Specified by:
setRangeProperties in interface BoundedRangeModel
Parameters:
newValue - an int giving the current value
newExtent - an int giving the amount by which the value can "jump"
newMin - an int giving the minimum value
newMax - an int giving the maximum value
adjusting - a boolean, true if a series of changes are in progress
See Also:
BoundedRangeModel.setRangeProperties(int, int, int, int, boolean), setValue(int), setExtent(int), setMinimum(int), setMaximum(int), setValueIsAdjusting(boolean)

addChangeListener

public void addChangeListener(ChangeListener l)
Adds a ChangeListener. The change listeners are run each time any one of the Bounded Range model properties changes.

Specified by:
addChangeListener in interface BoundedRangeModel
Parameters:
l - the ChangeListener to add
See Also:
removeChangeListener(javax.swing.event.ChangeListener), BoundedRangeModel.addChangeListener(javax.swing.event.ChangeListener)

removeChangeListener

public void removeChangeListener(ChangeListener l)
Removes a ChangeListener.

Specified by:
removeChangeListener in interface BoundedRangeModel
Parameters:
l - the ChangeListener to remove
See Also:
addChangeListener(javax.swing.event.ChangeListener), BoundedRangeModel.removeChangeListener(javax.swing.event.ChangeListener)

getChangeListeners

public ChangeListener[] getChangeListeners()
Returns an array of all the change listeners registered on this DefaultBoundedRangeModel.

Returns:
all of this model's ChangeListeners or an empty array if no change listeners are currently registered
Since:
1.4
See Also:
addChangeListener(javax.swing.event.ChangeListener), removeChangeListener(javax.swing.event.ChangeListener)

fireStateChanged

protected void fireStateChanged()
Runs each ChangeListener's stateChanged method.

See Also:
setRangeProperties(int, int, int, int, boolean), EventListenerList

toString

public String toString()
Returns a string that displays all of the BoundedRangeModel properties.

Overrides:
toString in class Object
Returns:
a string representation of the object.

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this model. FooListeners are registered using the addFooListener method.

You can specify the listenerType argument with a class literal, such as FooListener.class. For example, you can query a DefaultBoundedRangeModel instance m for its change listeners with the following code:

ChangeListener[] cls = (ChangeListener[])(m.getListeners(ChangeListener.class));
If no such listeners exist, this method returns an empty array.

Parameters:
listenerType - the type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener
Returns:
an array of all objects registered as FooListeners on this model, or an empty array if no such listeners have been added
Throws:
ClassCastException - if listenerType doesn't specify a class or interface that implements java.util.EventListener
Since:
1.3
See Also:
getChangeListeners()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultButtonModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class DefaultButtonModel

java.lang.Object
    extended by  javax.swing.DefaultButtonModel
All Implemented Interfaces:
ItemSelectable, Serializable, ButtonModel
Direct Known Subclasses:
JToggleButton.ToggleButtonModel
public class DefaultButtonModel
extends Object
implements ButtonModel, Serializable

The default implementation of a Button component's data model.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected String | actionCommand The action command string fired by the button.
static int | ARMED Identifies the "armed" bit in the bitmask, which indicates partial commitment towards choosing/triggering the button.
protected ChangeEvent | changeEvent Only one ChangeEvent is needed per button model instance since the event's only state is the source property.
static int | ENABLED Identifies the "enabled" bit in the bitmask, which indicates that the button can be selected by an input device (such as a mouse pointer).
protected ButtonGroup | group The button group that the button belongs to.
protected EventListenerList | listenerList Stores the listeners on this model.
protected int | mnemonic The button's mnemonic.
static int | PRESSED Identifies the "pressed" bit in the bitmask, which indicates that the button is pressed.
static int | ROLLOVER Identifies the "rollover" bit in the bitmask, which indicates that the mouse is over the button.
static int | SELECTED Identifies the "selected" bit in the bitmask, which indicates that the button has been selected.
protected int | stateMask The bitmask used to store the state of the button.
Constructor Summary
DefaultButtonModel()
Constructs a DefaultButtonModel.
Method Summary
 void addActionListener(ActionListener l)
Adds an ActionListener to the model.
 void addChangeListener(ChangeListener l)
Adds a ChangeListener to the model.
 void addItemListener(ItemListener l)
Adds an ItemListener to the model.
protected  void fireActionPerformed(ActionEvent e)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireItemStateChanged(ItemEvent e)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireStateChanged()
Notifies all listeners that have registered interest for notification on this event type.
 String getActionCommand()
Returns the action command string for the button.
 ActionListener[] getActionListeners()
Returns an array of all the action listeners registered on this DefaultButtonModel.
 ChangeListener[] getChangeListeners()
Returns an array of all the change listeners registered on this DefaultButtonModel.
 ButtonGroup getGroup()
Returns the group that the button belongs to.
 ItemListener[] getItemListeners()
Returns an array of all the item listeners registered on this DefaultButtonModel.
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this model.
 int getMnemonic()
Gets the keyboard mnemonic for the button.
 Object[] getSelectedObjects()
Overridden to return null.
 boolean isArmed()
Indicates partial commitment towards triggering the button.
 boolean isEnabled()
Indicates if the button can be selected or triggered by an input device, such as a mouse pointer.
 boolean isPressed()
Indicates if the button is pressed.
 boolean isRollover()
Indicates that the mouse is over the button.
 boolean isSelected()
Indicates if the button has been selected.
 void removeActionListener(ActionListener l)
Removes an ActionListener from the model.
 void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the model.
 void removeItemListener(ItemListener l)
Removes an ItemListener from the model.
 void setActionCommand(String actionCommand)
Sets the action command string that gets sent as part of the ActionEvent when the button is triggered.
 void setArmed(boolean b)
Marks the button as armed or unarmed.
 void setEnabled(boolean b)
Enables or disables the button.
 void setGroup(ButtonGroup group)
Identifies the group the button belongs to -- needed for radio buttons, which are mutually exclusive within their group.
 void setMnemonic(int key)
Sets the keyboard mnemonic (shortcut key or accelerator key) for the button.
 void setPressed(boolean b)
Sets the button to pressed or unpressed.
 void setRollover(boolean b)
Sets or clears the button's rollover state
 void setSelected(boolean b)
Selects or deselects the button.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

stateMask

protected int stateMask
The bitmask used to store the state of the button.

actionCommand

protected String actionCommand
The action command string fired by the button.

group

protected ButtonGroup group
The button group that the button belongs to.

mnemonic

protected int mnemonic
The button's mnemonic.

changeEvent

protected transient ChangeEvent changeEvent
Only one ChangeEvent is needed per button model instance since the event's only state is the source property. The source of events generated is always "this".

listenerList

protected EventListenerList listenerList
Stores the listeners on this model.

ARMED

public static final int ARMED
Identifies the "armed" bit in the bitmask, which indicates partial commitment towards choosing/triggering the button.

See Also:
Constant Field Values

SELECTED

public static final int SELECTED
Identifies the "selected" bit in the bitmask, which indicates that the button has been selected. Only needed for certain types of buttons - such as radio button or check box.

See Also:
Constant Field Values

PRESSED

public static final int PRESSED
Identifies the "pressed" bit in the bitmask, which indicates that the button is pressed.

See Also:
Constant Field Values

ENABLED

public static final int ENABLED
Identifies the "enabled" bit in the bitmask, which indicates that the button can be selected by an input device (such as a mouse pointer).

See Also:
Constant Field Values

ROLLOVER

public static final int ROLLOVER
Identifies the "rollover" bit in the bitmask, which indicates that the mouse is over the button.

See Also:
Constant Field Values
Constructor Detail

DefaultButtonModel

public DefaultButtonModel()
Constructs a DefaultButtonModel.

Method Detail

setActionCommand

public void setActionCommand(String actionCommand)
Sets the action command string that gets sent as part of the ActionEvent when the button is triggered.

Specified by:
setActionCommand in interface ButtonModel
Parameters:
actionCommand - the String that identifies the generated event
See Also:
ButtonModel.getActionCommand(), ActionEvent.getActionCommand()

getActionCommand

public String getActionCommand()
Returns the action command string for the button.

Specified by:
getActionCommand in interface ButtonModel
Returns:
the String that identifies the generated event
See Also:
ButtonModel.setActionCommand(java.lang.String)

isArmed

public boolean isArmed()
Indicates partial commitment towards triggering the button.

Specified by:
isArmed in interface ButtonModel
Returns:
true if the button is armed, and ready to be triggered
See Also:
ButtonModel.setArmed(boolean)

isSelected

public boolean isSelected()
Indicates if the button has been selected. Only needed for certain types of buttons - such as radio buttons and check boxes.

Specified by:
isSelected in interface ButtonModel
Returns:
true if the button is selected

isEnabled

public boolean isEnabled()
Indicates if the button can be selected or triggered by an input device, such as a mouse pointer.

Specified by:
isEnabled in interface ButtonModel
Returns:
true if the button is enabled

isPressed

public boolean isPressed()
Indicates if the button is pressed.

Specified by:
isPressed in interface ButtonModel
Returns:
true if the button is pressed

isRollover

public boolean isRollover()
Indicates that the mouse is over the button.

Specified by:
isRollover in interface ButtonModel
Returns:
true if the mouse is over the button

setArmed

public void setArmed(boolean b)
Marks the button as armed or unarmed.

Specified by:
setArmed in interface ButtonModel
Parameters:
b - whether or not the button should be armed

setEnabled

public void setEnabled(boolean b)
Enables or disables the button.

Specified by:
setEnabled in interface ButtonModel
Parameters:
b - whether or not the button should be enabled
See Also:
ButtonModel.isEnabled()

setSelected

public void setSelected(boolean b)
Selects or deselects the button.

Specified by:
setSelected in interface ButtonModel
Parameters:
b - true selects the button, false deselects the button

setPressed

public void setPressed(boolean b)
Sets the button to pressed or unpressed.

Specified by:
setPressed in interface ButtonModel
Parameters:
b - whether or not the button should be pressed
See Also:
ButtonModel.isPressed()

setRollover

public void setRollover(boolean b)
Sets or clears the button's rollover state

Specified by:
setRollover in interface ButtonModel
Parameters:
b - whether or not the button is in the rollover state
See Also:
ButtonModel.isRollover()

setMnemonic

public void setMnemonic(int key)
Sets the keyboard mnemonic (shortcut key or accelerator key) for the button.

Specified by:
setMnemonic in interface ButtonModel
Parameters:
key - an int specifying the accelerator key

getMnemonic

public int getMnemonic()
Gets the keyboard mnemonic for the button.

Specified by:
getMnemonic in interface ButtonModel
Returns:
an int specifying the accelerator key
See Also:
ButtonModel.setMnemonic(int)

addChangeListener

public void addChangeListener(ChangeListener l)
Adds a ChangeListener to the model.

Specified by:
addChangeListener in interface ButtonModel
Parameters:
l - the listener to add

removeChangeListener

public void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the model.

Specified by:
removeChangeListener in interface ButtonModel
Parameters:
l - the listener to remove

getChangeListeners

public ChangeListener[] getChangeListeners()
Returns an array of all the change listeners registered on this DefaultButtonModel.

Returns:
all of this model's ChangeListeners or an empty array if no change listeners are currently registered
Since:
1.4
See Also:
addChangeListener(javax.swing.event.ChangeListener), removeChangeListener(javax.swing.event.ChangeListener)

fireStateChanged

protected void fireStateChanged()
Notifies all listeners that have registered interest for notification on this event type. The event instance is created lazily.

See Also:
EventListenerList

addActionListener

public void addActionListener(ActionListener l)
Adds an ActionListener to the model.

Specified by:
addActionListener in interface ButtonModel
Parameters:
l - the listener to add

removeActionListener

public void removeActionListener(ActionListener l)
Removes an ActionListener from the model.

Specified by:
removeActionListener in interface ButtonModel
Parameters:
l - the listener to remove

getActionListeners

public ActionListener[] getActionListeners()
Returns an array of all the action listeners registered on this DefaultButtonModel.

Returns:
all of this model's ActionListeners or an empty array if no action listeners are currently registered
Since:
1.4
See Also:
addActionListener(java.awt.event.ActionListener), removeActionListener(java.awt.event.ActionListener)

fireActionPerformed

protected void fireActionPerformed(ActionEvent e)
Notifies all listeners that have registered interest for notification on this event type.

Parameters:
e - the ActionEvent to deliver to listeners
See Also:
EventListenerList

addItemListener

public void addItemListener(ItemListener l)
Adds an ItemListener to the model.

Specified by:
addItemListener in interface ItemSelectable
Specified by:
addItemListener in interface ButtonModel
Parameters:
l - the listener to add
See Also:
ItemEvent

removeItemListener

public void removeItemListener(ItemListener l)
Removes an ItemListener from the model.

Specified by:
removeItemListener in interface ItemSelectable
Specified by:
removeItemListener in interface ButtonModel
Parameters:
l - the listener to remove
See Also:
ItemEvent

getItemListeners

public ItemListener[] getItemListeners()
Returns an array of all the item listeners registered on this DefaultButtonModel.

Returns:
all of this model's ItemListeners or an empty array if no item listeners are currently registered
Since:
1.4
See Also:
addItemListener(java.awt.event.ItemListener), removeItemListener(java.awt.event.ItemListener)

fireItemStateChanged

protected void fireItemStateChanged(ItemEvent e)
Notifies all listeners that have registered interest for notification on this event type.

Parameters:
e - the ItemEvent to deliver to listeners
See Also:
EventListenerList

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this model. FooListeners are registered using the addFooListener method.

You can specify the listenerType argument with a class literal, such as FooListener.class. For example, you can query a DefaultButtonModel instance m for its action listeners with the following code:

ActionListener[] als = (ActionListener[])(m.getListeners(ActionListener.class));
If no such listeners exist, this method returns an empty array.

Parameters:
listenerType - the type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener
Returns:
an array of all objects registered as FooListeners on this model, or an empty array if no such listeners have been added
Throws:
ClassCastException - if listenerType doesn't specify a class or interface that implements java.util.EventListener
Since:
1.3
See Also:
getActionListeners(),
getChangeListeners(),
getItemListeners()

getSelectedObjects

public Object[] getSelectedObjects()
Overridden to return null.

Specified by:
getSelectedObjects in interface ItemSelectable

setGroup

public void setGroup(ButtonGroup group)
Identifies the group the button belongs to -- needed for radio buttons, which are mutually exclusive within their group.

Specified by:
setGroup in interface ButtonModel
Parameters:
group - the ButtonGroup the button belongs to

getGroup

public ButtonGroup getGroup()
Returns the group that the button belongs to. Normally used with radio buttons, which are mutually exclusive within their group.

Returns:
the ButtonGroup that the button belongs to
Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultCellEditor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class DefaultCellEditor

java.lang.Object
    extended by  javax.swing.AbstractCellEditor
        extended by  javax.swing.DefaultCellEditor
All Implemented Interfaces:
Serializable, CellEditor, TableCellEditor, TreeCellEditor
public class DefaultCellEditor
extends AbstractCellEditor
implements TableCellEditor, TreeCellEditor

The default editor for table and tree cells.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class DefaultCellEditor.EditorDelegate
The protected EditorDelegate class.
Field Summary
protected int | clickCountToStart An integer specifying the number of clicks needed to start editing.
protected DefaultCellEditor.EditorDelegate | delegate The delegate class which handles all methods sent from the CellEditor.
protected JComponent | editorComponent The Swing component being edited.
Fields inherited from class javax.swing.AbstractCellEditor
changeEvent, listenerList
Constructor Summary
DefaultCellEditor(JCheckBox checkBox)
Constructs a DefaultCellEditor object that uses a check box.
DefaultCellEditor(JComboBox comboBox)
Constructs a DefaultCellEditor object that uses a combo box.
DefaultCellEditor(JTextField textField)
Constructs a DefaultCellEditor that uses a text field.
Method Summary
void | cancelCellEditing() Forwards the message from the CellEditor to the delegate.
Object | getCellEditorValue() Forwards the message from the CellEditor to the delegate.
int | getClickCountToStart() Returns the number of clicks needed to start editing.
Component | getComponent() Returns a reference to the editor component.
Component | getTableCellEditorComponent(JTable table, Object value, boolean isSelected, int row, int column) Implements the TableCellEditor interface.
Component | getTreeCellEditorComponent(JTree tree, Object value, boolean isSelected, boolean expanded, boolean leaf, int row) Implements the TreeCellEditor interface.
boolean | isCellEditable(EventObject anEvent) Forwards the message from the CellEditor to the delegate.
void | setClickCountToStart(int count) Specifies the number of clicks needed to start editing.
boolean | shouldSelectCell(EventObject anEvent) Forwards the message from the CellEditor to the delegate.
boolean | stopCellEditing() Forwards the message from the CellEditor to the delegate.
Methods inherited from class javax.swing.AbstractCellEditor
addCellEditorListener, fireEditingCanceled, fireEditingStopped, getCellEditorListeners, removeCellEditorListener
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.swing.CellEditor
addCellEditorListener, removeCellEditorListener

Field Detail

editorComponent

protected JComponent editorComponent
The Swing component being edited.

delegate

protected DefaultCellEditor.EditorDelegate delegate
The delegate class which handles all methods sent from the CellEditor.

clickCountToStart

protected int clickCountToStart
An integer specifying the number of clicks needed to start editing. Even if clickCountToStart is defined as zero, it will not initiate until a click occurs.

Constructor Detail

DefaultCellEditor

public DefaultCellEditor(JTextField textField)
Constructs a DefaultCellEditor that uses a text field.

Parameters:
textField - a JTextField object

DefaultCellEditor

public DefaultCellEditor(JCheckBox checkBox)
Constructs a DefaultCellEditor object that uses a check box.

Parameters:
checkBox - a JCheckBox object

DefaultCellEditor

public DefaultCellEditor(JComboBox comboBox)
Constructs a DefaultCellEditor object that uses a combo box.

Parameters:
comboBox - a JComboBox object
Method Detail

getComponent

public Component getComponent()
Returns a reference to the editor component.

Returns:
the editor Component

setClickCountToStart

public void setClickCountToStart(int count)
Specifies the number of clicks needed to start editing.

Parameters:
count - an int specifying the number of clicks needed to start editing
See Also:
getClickCountToStart()

getClickCountToStart

public int getClickCountToStart()
Returns the number of clicks needed to start editing.

Returns:
the number of clicks needed to start editing

getCellEditorValue

public Object getCellEditorValue()
Forwards the message from the CellEditor to the delegate.

Specified by:
getCellEditorValue in interface CellEditor
Returns:
the value contained in the editor
See Also:
DefaultCellEditor.EditorDelegate.getCellEditorValue()

isCellEditable

public boolean isCellEditable(EventObject anEvent)
Forwards the message from the CellEditor to the delegate.

Specified by:
isCellEditable in interface CellEditor
Overrides:
isCellEditable in class AbstractCellEditor
Parameters:
anEvent - an event object
Returns:
true
See Also:
DefaultCellEditor.EditorDelegate.isCellEditable(EventObject)

shouldSelectCell

public boolean shouldSelectCell(EventObject anEvent)
Forwards the message from the CellEditor to the delegate.

Specified by:
shouldSelectCell in interface CellEditor
Overrides:
shouldSelectCell in class AbstractCellEditor
Parameters:
anEvent - an event object
Returns:
true
See Also:
DefaultCellEditor.EditorDelegate.shouldSelectCell(EventObject)

stopCellEditing

public boolean stopCellEditing()
Forwards the message from the CellEditor to the delegate.

Specified by:
stopCellEditing in interface CellEditor
Overrides:
stopCellEditing in class AbstractCellEditor
Returns:
true
See Also:
DefaultCellEditor.EditorDelegate.stopCellEditing()

cancelCellEditing

public void cancelCellEditing()
Forwards the message from the CellEditor to the delegate.

Specified by:
cancelCellEditing in interface CellEditor
Overrides:
cancelCellEditing in class AbstractCellEditor
See Also:
DefaultCellEditor.EditorDelegate.cancelCellEditing()

getTreeCellEditorComponent

public Component getTreeCellEditorComponent(JTree tree,
                                            Object value,
                                            boolean isSelected,
                                            boolean expanded,
                                            boolean leaf,
                                            int row)
Implements the TreeCellEditor interface.

Specified by:
getTreeCellEditorComponent in interface TreeCellEditor
Parameters:
tree - the JTree that is asking the editor to edit; this parameter can be null
value - the value of the cell to be edited
isSelected - true if the cell is to be rendered with selection highlighting
expanded - true if the node is expanded
leaf - true if the node is a leaf node
row - the row index of the node being edited
Returns:
the component for editing

getTableCellEditorComponent

public Component getTableCellEditorComponent(JTable table,
                                             Object value,
                                             boolean isSelected,
                                             int row,
                                             int column)
Implements the TableCellEditor interface.

Specified by:
getTableCellEditorComponent in interface TableCellEditor
Parameters:
table - the JTable that is asking the editor to edit; can be null
value - the value of the cell to be edited; it is up to the specific editor to interpret and draw the value. For example, if value is the string "true", it could be rendered as a string or it could be rendered as a check box that is checked. null is a valid value
isSelected - true if the cell is to be rendered with highlighting
row - the row of the cell being edited
column - the column of the cell being edited
Returns:
the component for editing
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultCellEditor.EditorDelegate

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class DefaultCellEditor.EditorDelegate

java.lang.Object
    extended by  javax.swing.DefaultCellEditor.EditorDelegate
All Implemented Interfaces:
ActionListener, ItemListener, Serializable, EventListener
Enclosing class:
DefaultCellEditor
protected class DefaultCellEditor.EditorDelegate
extends Object
implements ActionListener, ItemListener, Serializable

The protected EditorDelegate class.

Field Summary
protected  Object value
The value of this cell.
Constructor Summary
protected DefaultCellEditor.EditorDelegate()
Method Summary
void | actionPerformed(ActionEvent e) When an action is performed, editing is ended.
void | cancelCellEditing() Cancels editing.
Object | getCellEditorValue() Returns the value of this cell.
boolean | isCellEditable(EventObject anEvent) Returns true if anEvent is not a MouseEvent.
void | itemStateChanged(ItemEvent e) When an item's state changes, editing is ended.
void | setValue(Object value) Sets the value of this cell.
boolean | shouldSelectCell(EventObject anEvent) Returns true to indicate that the editing cell may be selected.
boolean | startCellEditing(EventObject anEvent) Returns true to indicate that editing has begun.
boolean | stopCellEditing() Stops editing and returns true to indicate that editing has stopped.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

protected Object value
The value of this cell.

Constructor Detail

DefaultCellEditor.EditorDelegate

protected DefaultCellEditor.EditorDelegate()
Method Detail

getCellEditorValue

public Object getCellEditorValue()
Returns the value of this cell.

Returns:
the value of this cell

setValue

public void setValue(Object value)
Sets the value of this cell.

Parameters:
value - the new value of this cell

isCellEditable

public boolean isCellEditable(EventObject anEvent)
Returns true if anEvent is not a MouseEvent. Otherwise, it returns true if the necessary number of clicks have occurred, and returns false otherwise.

Parameters:
anEvent - the event
Returns:
true if cell is ready for editing, false otherwise
See Also:
DefaultCellEditor.setClickCountToStart(int), shouldSelectCell(java.util.EventObject)

shouldSelectCell

public boolean shouldSelectCell(EventObject anEvent)
Returns true to indicate that the editing cell may be selected.

Parameters:
anEvent - the event
Returns:
true
See Also:
isCellEditable(java.util.EventObject)

startCellEditing

public boolean startCellEditing(EventObject anEvent)
Returns true to indicate that editing has begun.

Parameters:
anEvent - the event

stopCellEditing

public boolean stopCellEditing()
Stops editing and returns true to indicate that editing has stopped. This method calls fireEditingStopped.

Returns:
true

cancelCellEditing

public void cancelCellEditing()
Cancels editing. This method calls fireEditingCanceled.

actionPerformed

public void actionPerformed(ActionEvent e)
When an action is performed, editing is ended.

Specified by:
actionPerformed in interface ActionListener
Parameters:
e - the action event
See Also:
stopCellEditing()

itemStateChanged

public void itemStateChanged(ItemEvent e)
When an item's state changes, editing is ended.

Specified by:
itemStateChanged in interface ItemListener
Parameters:
e - the action event
See Also:
stopCellEditing()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultComboBoxModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class DefaultComboBoxModel

java.lang.Object
    extended by  javax.swing.AbstractListModel
        extended by  javax.swing.DefaultComboBoxModel
All Implemented Interfaces:
Serializable, ComboBoxModel, ListModel, MutableComboBoxModel
public class DefaultComboBoxModel
extends AbstractListModel
implements MutableComboBoxModel, Serializable

The default model for combo boxes.

Field Summary
Fields inherited from class javax.swing.AbstractListModel
listenerList
Constructor Summary
DefaultComboBoxModel()
Constructs an empty DefaultComboBoxModel object.
DefaultComboBoxModel(Object[] items)
Constructs a DefaultComboBoxModel object initialized with an array of objects.
DefaultComboBoxModel(Vector<?> v)
Constructs a DefaultComboBoxModel object initialized with a vector.
Method Summary
void | addElement(Object anObject) Adds an item at the end of the model.
Object | getElementAt(int index) Returns the value at the specified index.
int | getIndexOf(Object anObject) Returns the index-position of the specified object in the list.
Object | getSelectedItem() Returns the selected item
int | getSize() Returns the length of the list.
void | insertElementAt(Object anObject, int index) Adds an item at a specific index.
void | removeAllElements() Empties the list.
void | removeElement(Object anObject) Removes an item from the model.
void | removeElementAt(int index) Removes an item at a specific index.
void | setSelectedItem(Object anObject) Set the value of the selected item.
Methods inherited from class javax.swing.AbstractListModel
addListDataListener, fireContentsChanged, fireIntervalAdded, fireIntervalRemoved, getListDataListeners, getListeners, removeListDataListener
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.swing.ListModel
addListDataListener, removeListDataListener

Constructor Detail

DefaultComboBoxModel

public DefaultComboBoxModel()
Constructs an empty DefaultComboBoxModel object.

DefaultComboBoxModel

public DefaultComboBoxModel(Object[] items)
Constructs a DefaultComboBoxModel object initialized with an array of objects.

Parameters:
items - an array of Object objects

DefaultComboBoxModel

public DefaultComboBoxModel(Vector<?> v)
Constructs a DefaultComboBoxModel object initialized with a vector.

Parameters:
v - a Vector object ...
Method Detail

setSelectedItem

public void setSelectedItem(Object anObject)
Set the value of the selected item. The selected item may be null.

Specified by:
setSelectedItem in interface ComboBoxModel
Parameters:
anObject - The combo box value or null for no selection.

getSelectedItem

public Object getSelectedItem()
Description copied from interface: ComboBoxModel
Returns the selected item

Specified by:
getSelectedItem in interface ComboBoxModel
Returns:
The selected item or null if there is no selection

getSize

public int getSize()
Description copied from interface: ListModel
Returns the length of the list.

Specified by:
getSize in interface ListModel
Returns:
the length of the list

getElementAt

public Object getElementAt(int index)
Description copied from interface: ListModel
Returns the value at the specified index.

Specified by:
getElementAt in interface ListModel
Parameters:
index - the requested index
Returns:
the value at index

getIndexOf

public int getIndexOf(Object anObject)
Returns the index-position of the specified object in the list.

Parameters:
anObject -
Returns:
an int representing the index position, where 0 is the first position

addElement

public void addElement(Object anObject)
Description copied from interface: MutableComboBoxModel
Adds an item at the end of the model. The implementation of this method should notify all registered ListDataListeners that the item has been added.

Specified by:
addElement in interface MutableComboBoxModel
Parameters:
anObject - the Object to be added

insertElementAt

public void insertElementAt(Object anObject,
                            int index)
Description copied from interface: MutableComboBoxModel
Adds an item at a specific index. The implementation of this method should notify all registered ListDataListeners that the item has been added.

Specified by:
insertElementAt in interface MutableComboBoxModel
Parameters:
anObject - the Object to be added
index - location to add the object

removeElementAt

public void removeElementAt(int index)
Description copied from interface: MutableComboBoxModel
Removes an item at a specific index. The implementation of this method should notify all registered ListDataListeners that the item has been removed.

Specified by:
removeElementAt in interface MutableComboBoxModel
Parameters:
index - location of object to be removed

removeElement

public void removeElement(Object anObject)
Description copied from interface: MutableComboBoxModel
Removes an item from the model. The implementation of this method should should notify all registered ListDataListeners that the item has been removed.

Specified by:
removeElement in interface MutableComboBoxModel
Parameters:
anObject - the Object to be removed

removeAllElements

public void removeAllElements()
Empties the list.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultDesktopManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class DefaultDesktopManager

java.lang.Object
    extended by  javax.swing.DefaultDesktopManager
All Implemented Interfaces:
Serializable, DesktopManager
public class DefaultDesktopManager
extends Object
implements DesktopManager, Serializable

This is an implementation of the DesktopManager. It currently implements the basic behaviors for managing JInternalFrames in an arbitrary parent. JInternalFrames that are not children of a JDesktop will use this component to handle their desktop-like actions.

This class provides a policy for the various JInternalFrame methods, it is not meant to be called directly rather the various JInternalFrame methods will call into the DesktopManager.

See Also:
JDesktopPane, JInternalFrame

Constructor Summary
DefaultDesktopManager()
Method Summary
void | activateFrame(JInternalFrame f) This will activate f moving it to the front.
void | beginDraggingFrame(JComponent f) This method is normally called when the user has indicated that they will begin dragging a component around.
void | beginResizingFrame(JComponent f, int direction) This methods is normally called when the user has indicated that they will begin resizing the frame.
void | closeFrame(JInternalFrame f) Removes the frame, and, if necessary, the desktopIcon, from its parent.
void | deactivateFrame(JInternalFrame f) Generally, indicate that this frame has lost focus.
void | deiconifyFrame(JInternalFrame f) Removes the desktopIcon from its parent and adds its frame to the parent.
void | dragFrame(JComponent f, int newX, int newY) Moves the visible location of the frame being dragged to the location specified.
void | endDraggingFrame(JComponent f) This method signals the end of the dragging session.
void | endResizingFrame(JComponent f) This method signals the end of the resize session.
protected Rectangle | getBoundsForIconOf(JInternalFrame f) The iconifyFrame() code calls this to determine the proper bounds for the desktopIcon.
protected Rectangle | getPreviousBounds(JInternalFrame f) Gets the normal bounds of the component prior to the component being maximized.
void | iconifyFrame(JInternalFrame f) Removes the frame from its parent and adds its desktopIcon to the parent.
void | maximizeFrame(JInternalFrame f) Resizes the frame to fill its parents bounds.
void | minimizeFrame(JInternalFrame f) Restores the frame back to its size and position prior to a maximizeFrame call.
void | openFrame(JInternalFrame f) Normally this method will not be called.
protected void | removeIconFor(JInternalFrame f) Convenience method to remove the desktopIcon of f is necessary.
void | resizeFrame(JComponent f, int newX, int newY, int newWidth, int newHeight) Calls setBoundsForFrame with the new values.
void | setBoundsForFrame(JComponent f, int newX, int newY, int newWidth, int newHeight) This moves the JComponent and repaints the damaged areas.
protected void | setPreviousBounds(JInternalFrame f, Rectangle r) Stores the bounds of the component just before a maximize call.
protected void | setWasIcon(JInternalFrame f, Boolean value) Sets that the component has been iconized and the bounds of the desktopIcon are valid.
protected boolean | wasIcon(JInternalFrame f) Returns true if the component has been iconized and the bounds of the desktopIcon are valid, otherwise returns false.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultDesktopManager

public DefaultDesktopManager()
Method Detail

openFrame

public void openFrame(JInternalFrame f)
Normally this method will not be called. If it is, it try to determine the appropriate parent from the desktopIcon of the frame. Will remove the desktopIcon from its parent if it successfully adds the frame.

Specified by:
openFrame in interface DesktopManager

closeFrame

public void closeFrame(JInternalFrame f)
Removes the frame, and, if necessary, the desktopIcon, from its parent.

Specified by:
closeFrame in interface DesktopManager
Parameters:
f - the JInternalFrame to be removed

maximizeFrame

public void maximizeFrame(JInternalFrame f)
Resizes the frame to fill its parents bounds.

Specified by:
maximizeFrame in interface DesktopManager
Parameters:
f - the frame to be resized

minimizeFrame

public void minimizeFrame(JInternalFrame f)
Restores the frame back to its size and position prior to a maximizeFrame call.

Specified by:
minimizeFrame in interface DesktopManager
Parameters:
f - the JInternalFrame to be restored

iconifyFrame

public void iconifyFrame(JInternalFrame f)
Removes the frame from its parent and adds its desktopIcon to the parent.

Specified by:
iconifyFrame in interface DesktopManager
Parameters:
f - the JInternalFrame to be iconified

deiconifyFrame

public void deiconifyFrame(JInternalFrame f)
Removes the desktopIcon from its parent and adds its frame to the parent.

Specified by:
deiconifyFrame in interface DesktopManager
Parameters:
f - the JInternalFrame to be de-iconified

activateFrame

public void activateFrame(JInternalFrame f)
This will activate f moving it to the front. It will set the current active frame's (if any) IS_SELECTED_PROPERTY to false. There can be only one active frame across all Layers.

Specified by:
activateFrame in interface DesktopManager
Parameters:
f - the JInternalFrame to be activated

deactivateFrame

public void deactivateFrame(JInternalFrame f)
Description copied from interface: DesktopManager
Generally, indicate that this frame has lost focus. This is usually called after the JInternalFrame's IS_SELECTED_PROPERTY has been set to false.

Specified by:
deactivateFrame in interface DesktopManager

beginDraggingFrame

public void beginDraggingFrame(JComponent f)
Description copied from interface: DesktopManager
This method is normally called when the user has indicated that they will begin dragging a component around. This method should be called prior to any dragFrame() calls to allow the DesktopManager to prepare any necessary state. Normally f will be a JInternalFrame.

Specified by:
beginDraggingFrame in interface DesktopManager

dragFrame

public void dragFrame(JComponent f,
                      int newX,
                      int newY)
Moves the visible location of the frame being dragged to the location specified. The means by which this occurs can vary depending on the dragging algorithm being used. The actual logical location of the frame might not change until endDraggingFrame is called.

Specified by:
dragFrame in interface DesktopManager

endDraggingFrame

public void endDraggingFrame(JComponent f)
Description copied from interface: DesktopManager
This method signals the end of the dragging session. Any state maintained by the DesktopManager can be removed here. Normally f will be a JInternalFrame.

Specified by:
endDraggingFrame in interface DesktopManager

beginResizingFrame

public void beginResizingFrame(JComponent f,
                               int direction)
Description copied from interface: DesktopManager
This methods is normally called when the user has indicated that they will begin resizing the frame. This method should be called prior to any resizeFrame() calls to allow the DesktopManager to prepare any necessary state. Normally f will be a JInternalFrame.

Specified by:
beginResizingFrame in interface DesktopManager

resizeFrame

public void resizeFrame(JComponent f,
                        int newX,
                        int newY,
                        int newWidth,
                        int newHeight)
Calls setBoundsForFrame with the new values.

Specified by:
resizeFrame in interface DesktopManager
Parameters:
f - the component to be resized
newX - the new x-coordinate
newY - the new y-coordinate
newWidth - the new width
newHeight - the new height

endResizingFrame

public void endResizingFrame(JComponent f)
Description copied from interface: DesktopManager
This method signals the end of the resize session. Any state maintained by the DesktopManager can be removed here. Normally f will be a JInternalFrame.

Specified by:
endResizingFrame in interface DesktopManager

setBoundsForFrame

public void setBoundsForFrame(JComponent f,
                              int newX,
                              int newY,
                              int newWidth,
                              int newHeight)
This moves the JComponent and repaints the damaged areas.

Specified by:
setBoundsForFrame in interface DesktopManager

removeIconFor

protected void removeIconFor(JInternalFrame f)
Convenience method to remove the desktopIcon of f is necessary.

getBoundsForIconOf

protected Rectangle getBoundsForIconOf(JInternalFrame f)
The iconifyFrame() code calls this to determine the proper bounds for the desktopIcon.

setPreviousBounds

protected void setPreviousBounds(JInternalFrame f,
                                 Rectangle r)
Stores the bounds of the component just before a maximize call.

Parameters:
f - the component about to be resized
r - the normal bounds to be saved away

getPreviousBounds

protected Rectangle getPreviousBounds(JInternalFrame f)
Gets the normal bounds of the component prior to the component being maximized.

Parameters:
f - the JInternalFrame of interest
Returns:
the normal bounds of the component

setWasIcon

protected void setWasIcon(JInternalFrame f,
                          Boolean value)
Sets that the component has been iconized and the bounds of the desktopIcon are valid.

wasIcon

protected boolean wasIcon(JInternalFrame f)
Returns true if the component has been iconized and the bounds of the desktopIcon are valid, otherwise returns false.

Parameters:
f - the JInternalFrame of interest
Returns:
true if the component has been iconized; otherwise returns false
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultFocusManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class DefaultFocusManager

java.lang.Object
    extended by  java.awt.KeyboardFocusManager
        extended by  java.awt.DefaultKeyboardFocusManager
            extended by  javax.swing.FocusManager
                extended by  javax.swing.DefaultFocusManager
All Implemented Interfaces:
KeyEventDispatcher, KeyEventPostProcessor
public class DefaultFocusManager
extends FocusManager

This class has been obsoleted by the 1.4 focus APIs. While client code may still use this class, developers are strongly encouraged to use java.awt.KeyboardFocusManager and java.awt.DefaultKeyboardFocusManager instead.

Please see How to Use the Focus Subsystem, a section in The Java Tutorial, and the Focus Specification for more information.

Field Summary
Fields inherited from class javax.swing.FocusManager
FOCUS_MANAGER_CLASS_PROPERTY
Fields inherited from class java.awt.KeyboardFocusManager
BACKWARD_TRAVERSAL_KEYS, DOWN_CYCLE_TRAVERSAL_KEYS, FORWARD_TRAVERSAL_KEYS, UP_CYCLE_TRAVERSAL_KEYS
Constructor Summary
DefaultFocusManager()
Method Summary
boolean | compareTabOrder(Component a, Component b)
Component | getComponentAfter(Container aContainer, Component aComponent)
Component | getComponentBefore(Container aContainer, Component aComponent)
Component | getFirstComponent(Container aContainer)
Component | getLastComponent(Container aContainer)
Methods inherited from class javax.swing.FocusManager
disableSwingFocusManager, getCurrentManager, isFocusManagerEnabled, setCurrentManager
Methods inherited from class java.awt.DefaultKeyboardFocusManager
dequeueKeyEvents, discardKeyEvents, dispatchEvent, dispatchKeyEvent, downFocusCycle, enqueueKeyEvents, focusNextComponent, focusPreviousComponent, postProcessKeyEvent, processKeyEvent, upFocusCycle
Methods inherited from class java.awt.KeyboardFocusManager
addKeyEventDispatcher, addKeyEventPostProcessor, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, clearGlobalFocusOwner, downFocusCycle, firePropertyChange, fireVetoableChange, focusNextComponent, focusPreviousComponent, getActiveWindow, getCurrentFocusCycleRoot, getCurrentKeyboardFocusManager, getDefaultFocusTraversalKeys, getDefaultFocusTraversalPolicy, getFocusedWindow, getFocusOwner, getGlobalActiveWindow, getGlobalCurrentFocusCycleRoot, getGlobalFocusedWindow, getGlobalFocusOwner, getGlobalPermanentFocusOwner, getKeyEventDispatchers, getKeyEventPostProcessors, getPermanentFocusOwner, getPropertyChangeListeners, getPropertyChangeListeners, getVetoableChangeListeners, getVetoableChangeListeners, redispatchEvent, removeKeyEventDispatcher, removeKeyEventPostProcessor, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, removeVetoableChangeListener, setCurrentKeyboardFocusManager, setDefaultFocusTraversalKeys, setDefaultFocusTraversalPolicy, setGlobalActiveWindow, setGlobalCurrentFocusCycleRoot, setGlobalFocusedWindow, setGlobalFocusOwner, setGlobalPermanentFocusOwner, upFocusCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultFocusManager

public DefaultFocusManager()
Method Detail

getComponentAfter

public Component getComponentAfter(Container aContainer,
                                   Component aComponent)

getComponentBefore

public Component getComponentBefore(Container aContainer,
                                    Component aComponent)

getFirstComponent

public Component getFirstComponent(Container aContainer)

getLastComponent

public Component getLastComponent(Container aContainer)

compareTabOrder

public boolean compareTabOrder(Component a,
                               Component b)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultListCellRenderer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class DefaultListCellRenderer

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JLabel
                    extended by  javax.swing.DefaultListCellRenderer
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, ListCellRenderer, SwingConstants
Direct Known Subclasses:
DefaultListCellRenderer.UIResource, MetalFileChooserUI.FileRenderer, MetalFileChooserUI.FilterComboBoxRenderer
public class DefaultListCellRenderer
extends JLabel
implements ListCellRenderer, Serializable

Renders an item in a list.

Implementation Note: This class overrides invalidate, validate, revalidate, repaint, isOpaque, and firePropertyChange solely to improve performance. If not overridden, these frequently called methods would execute code paths that are unnecessary for the default list cell renderer. If you write your own renderer, take care to weigh the benefits and drawbacks of overriding these methods.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
static class DefaultListCellRenderer.UIResource
A subclass of DefaultListCellRenderer that implements UIResource.
Nested classes/interfaces inherited from class javax.swing.JLabel
JLabel.AccessibleJLabel
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected static Border noFocusBorder
An empty Border.
Fields inherited from class javax.swing.JLabel
labelFor
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
DefaultListCellRenderer()
Constructs a default renderer object for an item in a list.
Method Summary
void | firePropertyChange(String propertyName, boolean oldValue, boolean newValue) Overridden for performance reasons.
void | firePropertyChange(String propertyName, byte oldValue, byte newValue) Overridden for performance reasons.
void | firePropertyChange(String propertyName, char oldValue, char newValue) Overridden for performance reasons.
void | firePropertyChange(String propertyName, double oldValue, double newValue) Overridden for performance reasons.
void | firePropertyChange(String propertyName, float oldValue, float newValue) Overridden for performance reasons.
void | firePropertyChange(String propertyName, int oldValue, int newValue) Overridden for performance reasons.
void | firePropertyChange(String propertyName, long oldValue, long newValue) Overridden for performance reasons.
protected void | firePropertyChange(String propertyName, Object oldValue, Object newValue) Overridden for performance reasons.
void | firePropertyChange(String propertyName, short oldValue, short newValue) Overridden for performance reasons.
Component | getListCellRendererComponent(JList list, Object value, int index, boolean isSelected, boolean cellHasFocus) Return a component that has been configured to display the specified value.
void | invalidate() Overridden for performance reasons.
boolean | isOpaque() Overridden for performance reasons.
void | repaint() Overridden for performance reasons.
void | repaint(long tm, int x, int y, int width, int height) Overridden for performance reasons.
void | repaint(Rectangle r) Overridden for performance reasons.
void | revalidate() Overridden for performance reasons.
void | validate() Overridden for performance reasons.
Methods inherited from class javax.swing.JLabel
checkHorizontalKey, checkVerticalKey, getAccessibleContext, getDisabledIcon, getDisplayedMnemonic, getDisplayedMnemonicIndex, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getLabelFor, getText, getUI, getUIClassID, getVerticalAlignment, getVerticalTextPosition, imageUpdate, paramString, setDisabledIcon, setDisplayedMnemonic, setDisplayedMnemonic, setDisplayedMnemonicIndex, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabelFor, setText, setUI, setVerticalAlignment, setVerticalTextPosition, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

noFocusBorder

protected static Border noFocusBorder
An empty Border. This field might not be used. To change the Border used by this renderer override the getListCellRendererComponent method and set the border of the returned component directly.

Constructor Detail

DefaultListCellRenderer

public DefaultListCellRenderer()
Constructs a default renderer object for an item in a list.

Method Detail

getListCellRendererComponent

public Component getListCellRendererComponent(JList list,
                                              Object value,
                                              int index,
                                              boolean isSelected,
                                              boolean cellHasFocus)
Description copied from interface: ListCellRenderer
Return a component that has been configured to display the specified value. That component's paint method is then called to "render" the cell. If it is necessary to compute the dimensions of a list because the list cells do not have a fixed size, this method is called to generate a component on which getPreferredSize can be invoked.

Specified by:
getListCellRendererComponent in interface ListCellRenderer
Parameters:
list - The JList we're painting.
value - The value returned by list.getModel().getElementAt(index).
index - The cells index.
isSelected - True if the specified cell was selected.
cellHasFocus - True if the specified cell has the focus.
Returns:
A component whose paint() method will render the specified value.
See Also:
JList, ListSelectionModel, ListModel

isOpaque

public boolean isOpaque()
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
isOpaque in class JComponent
Returns:
true if the background is completely opaque and differs from the JList's background; false otherwise
Since:
1.5
See Also:
JComponent.setOpaque(boolean)

validate

public void validate()
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
validate in class Container
See Also:
Container.add(java.awt.Component),
Component.invalidate(),
JComponent.revalidate(),
Container.validateTree()

invalidate

public void invalidate()
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
invalidate in class Container
Since:
1.5
See Also:
Container.validate(), Container.layout(), LayoutManager, LayoutManager2.invalidateLayout(Container)

repaint

public void repaint()
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
repaint in class Component
Since:
1.5
See Also:
Component.update(Graphics)

revalidate

public void revalidate()
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
revalidate in class JComponent
See Also:
Component.invalidate(),
Container.validate(),
JComponent.isValidateRoot(),
RepaintManager.addInvalidComponent(javax.swing.JComponent)

repaint

public void repaint(long tm,
                    int x,
                    int y,
                    int width,
                    int height)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
repaint in class JComponent
Parameters:
tm - this parameter is not used
x - the x value of the dirty region
y - the y value of the dirty region
width - the width of the dirty region
height - the height of the dirty region
See Also:
Component.isShowing(), RepaintManager.addDirtyRegion(javax.swing.JComponent, int, int, int, int)

repaint

public void repaint(Rectangle r)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
repaint in class JComponent
Parameters:
r - a Rectangle containing the dirty region
See Also:
Component.isShowing(), RepaintManager.addDirtyRegion(javax.swing.JComponent, int, int, int, int)

firePropertyChange

protected void firePropertyChange(String propertyName,
                                  Object oldValue,
                                  Object newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class Component
Parameters:
propertyName - the property whose value has changed
oldValue - the property's previous value
newValue - the property's new value

firePropertyChange

public void firePropertyChange(String propertyName,
                               byte oldValue,
                               byte newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class Component
Parameters:
propertyName - the programmatic name of the property that was changed
oldValue - the old value of the property (as a byte)
newValue - the new value of the property (as a byte)
See Also:
Component.firePropertyChange(java.lang.String, java.lang.Object, java.lang.Object)

firePropertyChange

public void firePropertyChange(String propertyName,
                               char oldValue,
                               char newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class JComponent
Parameters:
propertyName - the programmatic name of the property that was changed
oldValue - the old value of the property (as a char)
newValue - the new value of the property (as a char)
See Also:
Component.firePropertyChange(java.lang.String, java.lang.Object, java.lang.Object)

firePropertyChange

public void firePropertyChange(String propertyName,
                               short oldValue,
                               short newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class Component
Parameters:
propertyName - the programmatic name of the property that was changed
oldValue - the old value of the property (as a short)
newValue - the old value of the property (as a short)
See Also:
Component.firePropertyChange(java.lang.String, java.lang.Object, java.lang.Object)

firePropertyChange

public void firePropertyChange(String propertyName,
                               int oldValue,
                               int newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class JComponent
Parameters:
propertyName - the property whose value has changed
oldValue - the property's previous value
newValue - the property's new value

firePropertyChange

public void firePropertyChange(String propertyName,
                               long oldValue,
                               long newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class Component
Parameters:
propertyName - the programmatic name of the property that was changed
oldValue - the old value of the property (as a long)
newValue - the new value of the property (as a long)
See Also:
Component.firePropertyChange(java.lang.String, java.lang.Object, java.lang.Object)

firePropertyChange

public void firePropertyChange(String propertyName,
                               float oldValue,
                               float newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class Component
Parameters:
propertyName - the programmatic name of the property that was changed
oldValue - the old value of the property (as a float)
newValue - the new value of the property (as a float)
See Also:
Component.firePropertyChange(java.lang.String, java.lang.Object, java.lang.Object)

firePropertyChange

public void firePropertyChange(String propertyName,
                               double oldValue,
                               double newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class Component
Parameters:
propertyName - the programmatic name of the property that was changed
oldValue - the old value of the property (as a double)
newValue - the new value of the property (as a double)
See Also:
Component.firePropertyChange(java.lang.String, java.lang.Object, java.lang.Object)

firePropertyChange

public void firePropertyChange(String propertyName,
                               boolean oldValue,
                               boolean newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class JComponent
Parameters:
propertyName - the property whose value has changed
oldValue - the property's previous value
newValue - the property's new value
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultListCellRenderer.UIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class DefaultListCellRenderer.UIResource

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JLabel
                    extended by  javax.swing.DefaultListCellRenderer
                        extended by  javax.swing.DefaultListCellRenderer.UIResource
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, ListCellRenderer, UIResource, SwingConstants
Enclosing class:
DefaultListCellRenderer
public static class DefaultListCellRenderer.UIResource
extends DefaultListCellRenderer
implements UIResource

A subclass of DefaultListCellRenderer that implements UIResource. DefaultListCellRenderer doesn't implement UIResource directly so that applications can safely override the cellRenderer property with DefaultListCellRenderer subclasses.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.DefaultListCellRenderer
DefaultListCellRenderer.UIResource
Nested classes/interfaces inherited from class javax.swing.JLabel
JLabel.AccessibleJLabel
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.DefaultListCellRenderer
noFocusBorder
Fields inherited from class javax.swing.JLabel
labelFor
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
DefaultListCellRenderer.UIResource()
Method Summary
Methods inherited from class javax.swing.DefaultListCellRenderer
firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getListCellRendererComponent, invalidate, isOpaque, repaint, repaint, repaint, revalidate, validate
Methods inherited from class javax.swing.JLabel
checkHorizontalKey, checkVerticalKey, getAccessibleContext, getDisabledIcon, getDisplayedMnemonic, getDisplayedMnemonicIndex, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getLabelFor, getText, getUI, getUIClassID, getVerticalAlignment, getVerticalTextPosition, imageUpdate, paramString, setDisabledIcon, setDisplayedMnemonic, setDisplayedMnemonic, setDisplayedMnemonicIndex, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabelFor, setText, setUI, setVerticalAlignment, setVerticalTextPosition, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DefaultListCellRenderer.UIResource

public DefaultListCellRenderer.UIResource()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultListModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class DefaultListModel

java.lang.Object
    extended by  javax.swing.AbstractListModel
        extended by  javax.swing.DefaultListModel
All Implemented Interfaces:
Serializable, ListModel
public class DefaultListModel
extends AbstractListModel

This class loosely implements the java.util.Vector API, in that it implements the 1.1.x version of java.util.Vector, has no collection class support, and notifies the ListDataListeners when changes occur. Presently it delegates to a Vector, in a future release it will be a real Collection implementation.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class javax.swing.AbstractListModel
listenerList
Constructor Summary
DefaultListModel()
Method Summary
void | add(int index, Object element) Inserts the specified element at the specified position in this list.
void | addElement(Object obj) Adds the specified component to the end of this list.
int | capacity() Returns the current capacity of this list.
void | clear() Removes all of the elements from this list.
boolean | contains(Object elem) Tests whether the specified object is a component in this list.
void | copyInto(Object[] anArray) Copies the components of this list into the specified array.
Object | elementAt(int index) Returns the component at the specified index.
Enumeration<?> | elements() Returns an enumeration of the components of this list.
void | ensureCapacity(int minCapacity) Increases the capacity of this list, if necessary, to ensure that it can hold at least the number of components specified by the minimum capacity argument.
Object | firstElement() Returns the first component of this list.
Object | get(int index) Returns the element at the specified position in this list.
Object | getElementAt(int index) Returns the component at the specified index.
int | getSize() Returns the number of components in this list.
int | indexOf(Object elem) Searches for the first occurrence of elem.
int | indexOf(Object elem, int index) Searches for the first occurrence of elem, beginning the search at index.
void | insertElementAt(Object obj, int index) Inserts the specified object as a component in this list at the specified index.
boolean | isEmpty() Tests whether this list has any components.
Object | lastElement() Returns the last component of the list.
int | lastIndexOf(Object elem) Returns the index of the last occurrence of elem.
int | lastIndexOf(Object elem, int index) Searches backwards for elem, starting from the specified index, and returns an index to it.
Object | remove(int index) Removes the element at the specified position in this list.
void | removeAllElements() Removes all components from this list and sets its size to zero.
boolean | removeElement(Object obj) Removes the first (lowest-indexed) occurrence of the argument from this list.
void | removeElementAt(int index) Deletes the component at the specified index.
void | removeRange(int fromIndex, int toIndex) Deletes the components at the specified range of indexes.
Object | set(int index, Object element) Replaces the element at the specified position in this list with the specified element.
void | setElementAt(Object obj, int index) Sets the component at the specified index of this list to be the specified object.
void | setSize(int newSize) Sets the size of this list.
int | size() Returns the number of components in this list.
Object[] | toArray() Returns an array containing all of the elements in this list in the correct order.
String | toString() Returns a string that displays and identifies this object's properties.
void | trimToSize() Trims the capacity of this list to be the list's current size.
Methods inherited from class javax.swing.AbstractListModel
addListDataListener, fireContentsChanged, fireIntervalAdded, fireIntervalRemoved, getListDataListeners, getListeners, removeListDataListener
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DefaultListModel

public DefaultListModel()
Method Detail

getSize

public int getSize()
Returns the number of components in this list.

This method is identical to size, which implements the List interface defined in the 1.2 Collections framework. This method exists in conjunction with setSize so that size is identifiable as a JavaBean property.

Returns:
the number of components in this list
See Also:
size()

getElementAt

public Object getElementAt(int index)
Returns the component at the specified index.
Note: Although this method is not deprecated, the preferred method to use is get(int), which implements the List interface defined in the 1.2 Collections framework.

Parameters:
index - an index into this list
Returns:
the component at the specified index
Throws:
ArrayIndexOutOfBoundsException - if the index is negative or greater than the current size of this list
See Also:
get(int)

copyInto

public void copyInto(Object[] anArray)
Copies the components of this list into the specified array. The array must be big enough to hold all the objects in this list, else an IndexOutOfBoundsException is thrown.

Parameters:
anArray - the array into which the components get copied
See Also:
Vector.copyInto(Object[])

trimToSize

public void trimToSize()
Trims the capacity of this list to be the list's current size.

See Also:
Vector.trimToSize()

ensureCapacity

public void ensureCapacity(int minCapacity)
Increases the capacity of this list, if necessary, to ensure that it can hold at least the number of components specified by the minimum capacity argument.

Parameters:
minCapacity - the desired minimum capacity
See Also:
Vector.ensureCapacity(int)

setSize

public void setSize(int newSize)
Sets the size of this list.

Parameters:
newSize - the new size of this list
See Also:
Vector.setSize(int)

capacity

public int capacity()
Returns the current capacity of this list.

Returns:
the current capacity
See Also:
Vector.capacity()

size

public int size()
Returns the number of components in this list.

Returns:
the number of components in this list
See Also:
Vector.size()

isEmpty

public boolean isEmpty()
Tests whether this list has any components.

Returns:
true if and only if this list has no components, that is, its size is zero; false otherwise
See Also:
Vector.isEmpty()

elements

public Enumeration<?> elements()
Returns an enumeration of the components of this list.

Returns:
an enumeration of the components of this list
See Also:
Vector.elements()

contains

public boolean contains(Object elem)
Tests whether the specified object is a component in this list.

Parameters:
elem - an object
Returns:
true if the specified object is the same as a component in this list
See Also:
Vector.contains(Object)

indexOf

public int indexOf(Object elem)
Searches for the first occurrence of elem.

Parameters:
elem - an object
Returns:
the index of the first occurrence of the argument in this list; returns -1 if the object is not found
See Also:
Vector.indexOf(Object)

indexOf

public int indexOf(Object elem,
                   int index)
Searches for the first occurrence of elem, beginning the search at index.

Parameters:
elem - an desired component
index - the index from which to begin searching
Returns:
the index where the first occurrence of elem is found after index; returns -1 if the elem is not found in the list
See Also:
Vector.indexOf(Object,int)

lastIndexOf

public int lastIndexOf(Object elem)
Returns the index of the last occurrence of elem.

Parameters:
elem - the desired component
Returns:
the index of the last occurrence of elem in the list; returns -1 if the object is not found
See Also:
Vector.lastIndexOf(Object)

lastIndexOf

public int lastIndexOf(Object elem,
                       int index)
Searches backwards for elem, starting from the specified index, and returns an index to it.

Parameters:
elem - the desired component
index - the index to start searching from
Returns:
the index of the last occurrence of the elem in this list at position less than index; returns -1 if the object is not found
See Also:
Vector.lastIndexOf(Object,int)

elementAt

public Object elementAt(int index)
Returns the component at the specified index. Throws an ArrayIndexOutOfBoundsException if the index is negative or not less than the size of the list.
Note: Although this method is not deprecated, the preferred method to use is get(int), which implements the List interface defined in the 1.2 Collections framework.

Parameters:
index - an index into this list
Returns:
the component at the specified index
See Also:
get(int), Vector.elementAt(int)

firstElement

public Object firstElement()
Returns the first component of this list. Throws a NoSuchElementException if this vector has no components.

Returns:
the first component of this list
See Also:
Vector.firstElement()

lastElement

public Object lastElement()
Returns the last component of the list. Throws a NoSuchElementException if this vector has no components.

Returns:
the last component of the list
See Also:
Vector.lastElement()

setElementAt

public void setElementAt(Object obj,
                         int index)
Sets the component at the specified index of this list to be the specified object. The previous component at that position is discarded.

Throws an ArrayIndexOutOfBoundsException if the index is invalid.

Note: Although this method is not deprecated, the preferred method to use is set(int,Object), which implements the List interface defined in the 1.2 Collections framework.

Parameters:
obj - what the component is to be set to
index - the specified index
See Also:
set(int,Object), Vector.setElementAt(Object,int)

removeElementAt

public void removeElementAt(int index)
Deletes the component at the specified index.

Throws an ArrayIndexOutOfBoundsException if the index is invalid.

Note: Although this method is not deprecated, the preferred method to use is remove(int), which implements the List interface defined in the 1.2 Collections framework.

Parameters:
index - the index of the object to remove
See Also:
remove(int), Vector.removeElementAt(int)

insertElementAt

public void insertElementAt(Object obj,
                            int index)
Inserts the specified object as a component in this list at the specified index.

Throws an ArrayIndexOutOfBoundsException if the index is invalid.

Note: Although this method is not deprecated, the preferred method to use is add(int,Object), which implements the List interface defined in the 1.2 Collections framework.

Parameters:
obj - the component to insert
index - where to insert the new component
Throws:
ArrayIndexOutOfBoundsException - if the index was invalid
See Also:
add(int,Object), Vector.insertElementAt(Object,int)

addElement

public void addElement(Object obj)
Adds the specified component to the end of this list.

Parameters:
obj - the component to be added
See Also:
Vector.addElement(Object)

removeElement

public boolean removeElement(Object obj)
Removes the first (lowest-indexed) occurrence of the argument from this list.

Parameters:
obj - the component to be removed
Returns:
true if the argument was a component of this list; false otherwise
See Also:
Vector.removeElement(Object)

removeAllElements

public void removeAllElements()
Removes all components from this list and sets its size to zero.
Note: Although this method is not deprecated, the preferred method to use is clear, which implements the List interface defined in the 1.2 Collections framework.

See Also:
clear(), Vector.removeAllElements()

toString

public String toString()
Returns a string that displays and identifies this object's properties.

Overrides:
toString in class Object
Returns:
a String representation of this object

toArray

public Object[] toArray()
Returns an array containing all of the elements in this list in the correct order.

Returns:
an array containing the elements of the list
See Also:
Vector.toArray()

get

public Object get(int index)
Returns the element at the specified position in this list.

Throws an ArrayIndexOutOfBoundsException if the index is out of range (index < 0 || index >= size()).

Parameters:
index - index of element to return

set

public Object set(int index,
                  Object element)
Replaces the element at the specified position in this list with the specified element.

Throws an ArrayIndexOutOfBoundsException if the index is out of range (index < 0 || index >= size()).

Parameters:
index - index of element to replace
element - element to be stored at the specified position
Returns:
the element previously at the specified position

add

public void add(int index,
                Object element)
Inserts the specified element at the specified position in this list.

Throws an ArrayIndexOutOfBoundsException if the index is out of range (index < 0 || index > size()).

Parameters:
index - index at which the specified element is to be inserted
element - element to be inserted

remove

public Object remove(int index)
Removes the element at the specified position in this list. Returns the element that was removed from the list.

Throws an ArrayIndexOutOfBoundsException if the index is out of range (index < 0 || index >= size()).

Parameters:
index - the index of the element to removed

clear

public void clear()
Removes all of the elements from this list. The list will be empty after this call returns (unless it throws an exception).

removeRange

public void removeRange(int fromIndex,
                        int toIndex)
Deletes the components at the specified range of indexes. The removal is inclusive, so specifying a range of (1,5) removes the component at index 1 and the component at index 5, as well as all components in between.

Throws an ArrayIndexOutOfBoundsException if the index was invalid. Throws an IllegalArgumentException if fromIndex > toIndex.

Parameters:
fromIndex - the index of the lower end of the range
toIndex - the index of the upper end of the range
See Also:
remove(int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultListSelectionModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class DefaultListSelectionModel

java.lang.Object
    extended by  javax.swing.DefaultListSelectionModel
All Implemented Interfaces:
Serializable, Cloneable, ListSelectionModel
public class DefaultListSelectionModel
extends Object
implements ListSelectionModel, Cloneable, Serializable

Default data model for list selections.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
ListSelectionModel

Field Summary
protected boolean | leadAnchorNotificationEnabled
protected EventListenerList | listenerList
Fields inherited from interface javax.swing.ListSelectionModel
MULTIPLE_INTERVAL_SELECTION, SINGLE_INTERVAL_SELECTION, SINGLE_SELECTION
Constructor Summary
DefaultListSelectionModel()
Method Summary
 void addListSelectionListener(ListSelectionListener l)
Add a listener to the list that's notified each time a change to the selection occurs.
 void addSelectionInterval(int index0, int index1)
Changes the selection to be the set union of the current selection and the indices between index0 and index1 inclusive.
 void clearSelection()
Change the selection to the empty set.
 Object clone()
Returns a clone of this selection model with the same selection.
protected  void fireValueChanged(boolean isAdjusting)
Notifies listeners that we have ended a series of adjustments.
protected  void fireValueChanged(int firstIndex, int lastIndex)
Notifies ListSelectionListeners that the value of the selection, in the closed interval firstIndex, lastIndex, has changed.
protected  void fireValueChanged(int firstIndex, int lastIndex, boolean isAdjusting)
 int getAnchorSelectionIndex()
Return the first index argument from the most recent call to setSelectionInterval(), addSelectionInterval() or removeSelectionInterval().
 int getLeadSelectionIndex()
Return the second index argument from the most recent call to setSelectionInterval(), addSelectionInterval() or removeSelectionInterval().
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this model.
 ListSelectionListener[] getListSelectionListeners()
Returns an array of all the list selection listeners registered on this DefaultListSelectionModel.
 int getMaxSelectionIndex()
Returns the last selected index or -1 if the selection is empty.
 int getMinSelectionIndex()
Returns the first selected index or -1 if the selection is empty.
 int getSelectionMode()
Returns the current selection mode.
 boolean getValueIsAdjusting()
Returns true if the selection is undergoing a series of changes.
 void insertIndexInterval(int index, int length, boolean before)
Insert length indices beginning before/after index.
 boolean isLeadAnchorNotificationEnabled()
Returns the value of the leadAnchorNotificationEnabled flag.
 boolean isSelectedIndex(int index)
Returns true if the specified index is selected.
 boolean isSelectionEmpty()
Returns true if no indices are selected.
 void moveLeadSelectionIndex(int leadIndex)
Set the lead selection index, leaving all selection values unchanged.
 void removeIndexInterval(int index0, int index1)
Remove the indices in the interval index0,index1 (inclusive) from the selection model.
 void removeListSelectionListener(ListSelectionListener l)
Remove a listener from the list that's notified each time a change to the selection occurs.
 void removeSelectionInterval(int index0, int index1)
Changes the selection to be the set difference of the current selection and the indices between index0 and index1 inclusive.
 void setAnchorSelectionIndex(int anchorIndex)
Set the anchor selection index, leaving all selection values unchanged.
 void setLeadAnchorNotificationEnabled(boolean flag)
Sets the value of the leadAnchorNotificationEnabled flag.
 void setLeadSelectionIndex(int leadIndex)
Sets the lead selection index, ensuring that values between the anchor and the new lead are either all selected or all deselected.
 void setSelectionInterval(int index0, int index1)
Changes the selection to be between index0 and index1 inclusive.
 void setSelectionMode(int selectionMode)
Sets the selection mode.
 void setValueIsAdjusting(boolean isAdjusting)
Sets the valueIsAdjusting property, which indicates whether or not upcoming selection changes should be considered part of a single change.
 String toString()
Returns a string that displays and identifies this object's properties.
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

listenerList

protected EventListenerList listenerList

leadAnchorNotificationEnabled

protected boolean leadAnchorNotificationEnabled
Constructor Detail

DefaultListSelectionModel

public DefaultListSelectionModel()
Method Detail

getMinSelectionIndex

public int getMinSelectionIndex()
Returns the first selected index or -1 if the selection is empty.

Specified by:
getMinSelectionIndex in interface ListSelectionModel

getMaxSelectionIndex

public int getMaxSelectionIndex()
Returns the last selected index or -1 if the selection is empty.

Specified by:
getMaxSelectionIndex in interface ListSelectionModel

getValueIsAdjusting

public boolean getValueIsAdjusting()
Returns true if the selection is undergoing a series of changes.

Specified by:
getValueIsAdjusting in interface ListSelectionModel
Returns:
true if the selection is undergoing a series of changes
See Also:
ListSelectionModel.setValueIsAdjusting(boolean)

getSelectionMode

public int getSelectionMode()
Returns the current selection mode.

Specified by:
getSelectionMode in interface ListSelectionModel
Returns:
the current selection mode
See Also:
ListSelectionModel.setSelectionMode(int)

setSelectionMode

public void setSelectionMode(int selectionMode)
Sets the selection mode. The following list describes the accepted selection modes:
  • ListSelectionModel.SINGLE_SELECTION - Only one list index can be selected at a time. In this mode, setSelectionInterval and addSelectionInterval are equivalent, both replacing the current selection with the index represented by the second argument (the "lead").
  • ListSelectionModel.SINGLE_INTERVAL_SELECTION - Only one contiguous interval can be selected at a time. In this mode, addSelectionInterval behaves like setSelectionInterval (replacing the current selection), unless the given interval is immediately adjacent to or overlaps the existing selection, and can therefore be used to grow it.
  • ListSelectionModel.MULTIPLE_INTERVAL_SELECTION - In this mode, there's no restriction on what can be selected.

Specified by:
setSelectionMode in interface ListSelectionModel
Throws:
IllegalArgumentException - if the selection mode isn't one of those allowed
See Also:
ListSelectionModel.getSelectionMode()

isSelectedIndex

public boolean isSelectedIndex(int index)
Returns true if the specified index is selected.

Specified by:
isSelectedIndex in interface ListSelectionModel

isSelectionEmpty

public boolean isSelectionEmpty()
Returns true if no indices are selected.

Specified by:
isSelectionEmpty in interface ListSelectionModel

addListSelectionListener

public void addListSelectionListener(ListSelectionListener l)
Add a listener to the list that's notified each time a change to the selection occurs.

Specified by:
addListSelectionListener in interface ListSelectionModel
Parameters:
l - the ListSelectionListener
See Also:
ListSelectionModel.removeListSelectionListener(javax.swing.event.ListSelectionListener),
ListSelectionModel.setSelectionInterval(int, int),
ListSelectionModel.addSelectionInterval(int, int),
ListSelectionModel.removeSelectionInterval(int, int),
ListSelectionModel.clearSelection(),
ListSelectionModel.insertIndexInterval(int, int, boolean),
ListSelectionModel.removeIndexInterval(int, int)

removeListSelectionListener

public void removeListSelectionListener(ListSelectionListener l)
Remove a listener from the list that's notified each time a change to the selection occurs.

Specified by:
removeListSelectionListener in interface ListSelectionModel
Parameters:
l - the ListSelectionListener
See Also:
ListSelectionModel.addListSelectionListener(javax.swing.event.ListSelectionListener)

getListSelectionListeners

public ListSelectionListener[] getListSelectionListeners()
Returns an array of all the list selection listeners registered on this DefaultListSelectionModel.

Returns:
all of this model's ListSelectionListeners or an empty array if no list selection listeners are currently registered
Since:
1.4
See Also:
addListSelectionListener(javax.swing.event.ListSelectionListener), removeListSelectionListener(javax.swing.event.ListSelectionListener)

fireValueChanged

protected void fireValueChanged(boolean isAdjusting)
Notifies listeners that we have ended a series of adjustments.

fireValueChanged

protected void fireValueChanged(int firstIndex,
                                int lastIndex)
Notifies ListSelectionListeners that the value of the selection, in the closed interval firstIndex, lastIndex, has changed.

fireValueChanged

protected void fireValueChanged(int firstIndex,
                                int lastIndex,
                                boolean isAdjusting)
Parameters:
firstIndex - the first index in the interval
lastIndex - the last index in the interval
isAdjusting - true if this is the final change in a series of adjustments
See Also:
EventListenerList

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this model. FooListeners are registered using the addFooListener method.

You can specify the listenerType argument with a class literal, such as FooListener.class. For example, you can query a DefaultListSelectionModel instance m for its list selection listeners with the following code:

ListSelectionListener[] lsls = (ListSelectionListener[])(m.getListeners(ListSelectionListener.class));
If no such listeners exist, this method returns an empty array.

Parameters:
listenerType - the type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener
Returns:
an array of all objects registered as FooListeners on this model, or an empty array if no such listeners have been added
Throws:
ClassCastException - if listenerType doesn't specify a class or interface that implements java.util.EventListener
Since:
1.3
See Also:
getListSelectionListeners()

setLeadAnchorNotificationEnabled

public void setLeadAnchorNotificationEnabled(boolean flag)
Sets the value of the leadAnchorNotificationEnabled flag.

See Also:
isLeadAnchorNotificationEnabled()

isLeadAnchorNotificationEnabled

public boolean isLeadAnchorNotificationEnabled()
Returns the value of the leadAnchorNotificationEnabled flag. When leadAnchorNotificationEnabled is true the model generates notification events with bounds that cover all the changes to the selection plus the changes to the lead and anchor indices. Setting the flag to false causes a narrowing of the event's bounds to include only the elements that have been selected or deselected since the last change. Either way, the model continues to maintain the lead and anchor variables internally. The default is true.

Note: It is possible for the lead or anchor to be changed without a change to the selection. Notification of these changes is often important, such as when the new lead or anchor needs to be updated in the view. Therefore, caution is urged when changing the default value.

Returns:
the value of the leadAnchorNotificationEnabled flag
See Also:
setLeadAnchorNotificationEnabled(boolean)

clearSelection

public void clearSelection()
Change the selection to the empty set. If this represents a change to the current selection then notify each ListSelectionListener.

Specified by:
clearSelection in interface ListSelectionModel
See Also:
ListSelectionModel.addListSelectionListener(javax.swing.event.ListSelectionListener)

setSelectionInterval

public void setSelectionInterval(int index0,
                                 int index1)
Changes the selection to be between index0 and index1 inclusive. index0 doesn't have to be less than or equal to index1.

In SINGLE_SELECTION selection mode, only the second index is used.

If this represents a change to the current selection, then each ListSelectionListener is notified of the change.

If either index is -1, this method does nothing and returns without exception. Otherwise, if either index is less than -1, an IndexOutOfBoundsException is thrown.

Specified by:
setSelectionInterval in interface ListSelectionModel
Parameters:
index0 - one end of the interval.
index1 - other end of the interval
Throws:
IndexOutOfBoundsException - if either index is less than -1 (and neither index is -1)
See Also:
addListSelectionListener(javax.swing.event.ListSelectionListener)

addSelectionInterval

public void addSelectionInterval(int index0,
                                 int index1)
Changes the selection to be the set union of the current selection and the indices between index0 and index1 inclusive.

In SINGLE_SELECTION selection mode, this is equivalent to calling setSelectionInterval, and only the second index is used. In SINGLE_INTERVAL_SELECTION selection mode, this method behaves like setSelectionInterval, unless the given interval is immediately adjacent to or overlaps the existing selection, and can therefore be used to grow it.

If this represents a change to the current selection, then each ListSelectionListener is notified of the change. Note that index0 doesn't have to be less than or equal to index1.

If either index is -1, this method does nothing and returns without exception. Otherwise, if either index is less than -1, an IndexOutOfBoundsException is thrown.

Specified by:
addSelectionInterval in interface ListSelectionModel
Parameters:
index0 - one end of the interval.
index1 - other end of the interval
Throws:
IndexOutOfBoundsException - if either index is less than -1 (and neither index is -1)
See Also:
addListSelectionListener(javax.swing.event.ListSelectionListener), setSelectionInterval(int, int)

removeSelectionInterval

public void removeSelectionInterval(int index0,
                                    int index1)
Changes the selection to be the set difference of the current selection and the indices between index0 and index1 inclusive. index0 doesn't have to be less than or equal to index1.

In SINGLE_INTERVAL_SELECTION selection mode, if the removal would produce two disjoint selections, the removal is extended through the greater end of the selection. For example, if the selection is 0-10 and you supply indices 5,6 (in any order) the resulting selection is 0-4.

If this represents a change to the current selection, then each ListSelectionListener is notified of the change.

If either index is -1, this method does nothing and returns without exception. Otherwise, if either index is less than -1, an IndexOutOfBoundsException is thrown.

Specified by:
removeSelectionInterval in interface ListSelectionModel
Parameters:
index0 - one end of the interval
index1 - other end of the interval
Throws:
IndexOutOfBoundsException - if either index is less than -1 (and neither index is -1)
See Also:
addListSelectionListener(javax.swing.event.ListSelectionListener)

insertIndexInterval

public void insertIndexInterval(int index,
                                int length,
                                boolean before)
Insert length indices beginning before/after index. If the value at index is itself selected and the selection mode is not SINGLE_SELECTION, set all of the newly inserted items as selected. Otherwise leave them unselected. This method is typically called to sync the selection model with a corresponding change in the data model.

Specified by:
insertIndexInterval in interface ListSelectionModel

removeIndexInterval

public void removeIndexInterval(int index0,
                                int index1)
Remove the indices in the interval index0,index1 (inclusive) from the selection model. This is typically called to sync the selection model width a corresponding change in the data model. Note that (as always) index0 need not be <= index1.="index1."
Specified by:
removeIndexInterval in interface ListSelectionModel

setValueIsAdjusting

public void setValueIsAdjusting(boolean isAdjusting)
Sets the valueIsAdjusting property, which indicates whether or not upcoming selection changes should be considered part of a single change. The value of this property is used to initialize the valueIsAdjusting property of the ListSelectionEvents that are generated.

For example, if the selection is being updated in response to a user drag, this property can be set to true when the drag is initiated and set to false when the drag is finished. During the drag, listeners receive events with a valueIsAdjusting property set to true. At the end of the drag, when the change is finalized, listeners receive an event with the value set to false. Listeners can use this pattern if they wish to update only when a change has been finalized.

Setting this property to true begins a series of changes that is to be considered part of a single change. When the property is changed back to false, an event is sent out characterizing the entire selection change (if there was one), with the event's valueIsAdjusting property set to false.

Specified by:
setValueIsAdjusting in interface ListSelectionModel
Parameters:
isAdjusting - the new value of the property
See Also:
ListSelectionModel.getValueIsAdjusting(), ListSelectionEvent.getValueIsAdjusting()

toString

public String toString()
Returns a string that displays and identifies this object's properties.

Overrides:
toString in class Object
Returns:
a String representation of this object

clone

public Object clone()
             throws CloneNotSupportedException
Returns a clone of this selection model with the same selection. listenerLists are not duplicated.

Overrides:
clone in class Object
Returns:
a clone of this instance.
Throws:
CloneNotSupportedException - if the selection model does not both (a) implement the Cloneable interface and (b) define a clone method.
See Also:
Cloneable

getAnchorSelectionIndex

public int getAnchorSelectionIndex()
Return the first index argument from the most recent call to setSelectionInterval(), addSelectionInterval() or removeSelectionInterval(). The most recent index0 is considered the "anchor" and the most recent index1 is considered the "lead". Some interfaces display these indices specially, e.g. Windows95 displays the lead index with a dotted yellow outline.

Specified by:
getAnchorSelectionIndex in interface ListSelectionModel
See Also:
ListSelectionModel.getLeadSelectionIndex(),
ListSelectionModel.setSelectionInterval(int, int),
ListSelectionModel.addSelectionInterval(int, int)

getLeadSelectionIndex

public int getLeadSelectionIndex()
Return the second index argument from the most recent call to setSelectionInterval(), addSelectionInterval() or removeSelectionInterval().

Specified by:
getLeadSelectionIndex in interface ListSelectionModel
See Also:
ListSelectionModel.getAnchorSelectionIndex(),
ListSelectionModel.setSelectionInterval(int, int),
ListSelectionModel.addSelectionInterval(int, int)

setAnchorSelectionIndex

public void setAnchorSelectionIndex(int anchorIndex)
Set the anchor selection index, leaving all selection values unchanged. If leadAnchorNotificationEnabled is true, send a notification covering the old and new anchor cells.

Specified by:
setAnchorSelectionIndex in interface ListSelectionModel
See Also:
getAnchorSelectionIndex(), setLeadSelectionIndex(int)

moveLeadSelectionIndex

public void moveLeadSelectionIndex(int leadIndex)
Set the lead selection index, leaving all selection values unchanged. If leadAnchorNotificationEnabled is true, send a notification covering the old and new lead cells.

Parameters:
leadIndex - the new lead selection index
Since:
1.5
See Also:
setAnchorSelectionIndex(int), setLeadSelectionIndex(int), getLeadSelectionIndex()

setLeadSelectionIndex

public void setLeadSelectionIndex(int leadIndex)
Sets the lead selection index, ensuring that values between the anchor and the new lead are either all selected or all deselected. If the value at the anchor index is selected, first clear all the values in the range [anchor, oldLeadIndex], then select all the values values in the range [anchor, newLeadIndex], where oldLeadIndex is the old leadIndex and newLeadIndex is the new one.

If the value at the anchor index is not selected, do the same thing in reverse selecting values in the old range and deslecting values in the new one.

Generate a single event for this change and notify all listeners. For the purposes of generating minimal bounds in this event, do the operation in a single pass; that way the first and last index inside the ListSelectionEvent that is broadcast will refer to cells that actually changed value because of this method. If, instead, this operation were done in two steps the effect on the selection state would be the same but two events would be generated and the bounds around the changed values would be wider, including cells that had been first cleared only to later be set.

This method can be used in the mouseDragged method of a UI class to extend a selection.

Specified by:
setLeadSelectionIndex in interface ListSelectionModel
See Also:
getLeadSelectionIndex(), setAnchorSelectionIndex(int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultRowSorter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class DefaultRowSorter<M,I>

java.lang.Object
    extended by  javax.swing.RowSorter<M>
        extended by  javax.swing.DefaultRowSorter<M,I>
Type Parameters:
M - the type of the model
I - the type of the identifier passed to the RowFilter
Direct Known Subclasses:
TableRowSorter
public abstract class DefaultRowSorter<M,I>
extends RowSorter<M>

An implementation of RowSorter that provides sorting and filtering around a grid-based data model. Beyond creating and installing a RowSorter, you very rarely need to interact with one directly. Refer to TableRowSorter for a concrete implementation of RowSorter for JTable.

Sorting is done based on the current SortKeys, in order. If two objects are equal (the Comparator for the column returns 0) the next SortKey is used. If no SortKeys remain or the order is UNSORTED, then the order of the rows in the model is used.

Sorting of each column is done by way of a Comparator that you can specify using the setComparator method. If a Comparator has not been specified, the Comparator returned by Collator.getInstance() is used on the results of calling toString on the underlying objects. The Comparator is never passed null. A null value is treated as occuring before a non-null value, and two null values are considered equal.

If you specify a Comparator that casts its argument to a type other than that provided by the model, a ClassCastException will be thrown when the data is sorted.

In addition to sorting, DefaultRowSorter provides the ability to filter rows. Filtering is done by way of a RowFilter that is specified using the setRowFilter method. If no filter has been specified all rows are included.

By default, rows are in unsorted order (the same as the model) and every column is sortable. The default Comparators are documented in the subclasses (for example, TableRowSorter).

If the underlying model structure changes (the modelStructureChanged method is invoked) the following are reset to their default values: Comparators by column, current sort order, and whether each column is sortable. To find the default Comparators, see the concrete implementation (for example, TableRowSorter). The default sort order is unsorted (the same as the model), and columns are sortable by default.

If the underlying model structure changes (the modelStructureChanged method is invoked) the following are reset to their default values: Comparators by column, current sort order and whether a column is sortable.

DefaultRowSorter is an abstract class. Concrete subclasses must provide access to the underlying data by invoking setModelWrapper. The setModelWrapper method must be invoked soon after the constructor is called, ideally from within the subclass's constructor. Undefined behavior will result if you use a DefaultRowSorter without specifying a ModelWrapper.

DefaultRowSorter has two formal type parameters. The first type parameter corresponds to the class of the model, for example DefaultTableModel. The second type parameter corresponds to the class of the identifier passed to the RowFilter. Refer to TableRowSorter and RowFilter for more details on the type parameters.

Since:
1.6
See Also:
TableRowSorter, DefaultTableModel, Collator

Nested Class Summary
protected static class DefaultRowSorter.ModelWrapper<M,I>
DefaultRowSorter.ModelWrapper is responsible for providing the data that gets sorted by DefaultRowSorter.
Nested classes/interfaces inherited from class javax.swing.RowSorter
RowSorter.SortKey
Constructor Summary
DefaultRowSorter()
Creates an empty DefaultRowSorter.
Method Summary
void | allRowsChanged() Invoked when the contents of the underlying model have completely changed.
int | convertRowIndexToModel(int index) Returns the location of index in terms of the underlying model.
int | convertRowIndexToView(int index) Returns the location of index in terms of the view.
Comparator<?> | getComparator(int column) Returns the Comparator for the specified column.
int | getMaxSortKeys() Returns the maximum number of sort keys.
M | getModel() Returns the underlying model.
int | getModelRowCount() Returns the number of rows in the underlying model.
protected DefaultRowSorter.ModelWrapper<M,I> | getModelWrapper() Returns the model wrapper providing the data that is being sorted and filtered.
RowFilter<? super M,? super I> | getRowFilter() Returns the filter that determines which rows, if any, should be hidden from view.
List<? extends RowSorter.SortKey> | getSortKeys() Returns the current sort keys.
boolean | getSortsOnUpdates() Returns true if a sort should happen when the underlying model is updated; otherwise, returns false.
int | getViewRowCount() Returns the number of rows in the view.
boolean | isSortable(int column) Returns true if the specified column is sortable; otherwise, false.
void | modelStructureChanged() Invoked when the underlying model structure has completely changed.
void | rowsDeleted(int firstRow, int endRow) Invoked when rows have been deleted from the underlying model in the specified range (inclusive).
void | rowsInserted(int firstRow, int endRow) Invoked when rows have been inserted into the underlying model in the specified range (inclusive).
void | rowsUpdated(int firstRow, int endRow) Invoked when rows have been changed in the underlying model between the specified range (inclusive).
void | rowsUpdated(int firstRow, int endRow, int column) Invoked when the column in the rows have been updated in the underlying model between the specified range.
void | setComparator(int column, Comparator<?> comparator) Sets the Comparator to use when sorting the specified column.
void | setMaxSortKeys(int max) Sets the maximum number of sort keys.
protected void | setModelWrapper(DefaultRowSorter.ModelWrapper<M,I> modelWrapper) Sets the model wrapper providing the data that is being sorted and filtered.
void | setRowFilter(RowFilter<? super M,? super I> filter) Sets the filter that determines which rows, if any, should be hidden from the view.
void | setSortable(int column, boolean sortable) Sets whether or not the specified column is sortable.
void | setSortKeys(List<? extends RowSorter.SortKey> sortKeys) Sets the sort keys.
void | setSortsOnUpdates(boolean sortsOnUpdates) If true, specifies that a sort should happen when the underlying model is updated (rowsUpdated is invoked).
void | sort() Sorts and filters the rows in the view based on the sort keys of the columns currently being sorted and the filter, if any, associated with this sorter.
void | toggleSortOrder(int column) Reverses the sort order from ascending to descending (or descending to ascending) if the specified column is already the primary sorted column; otherwise, makes the specified column the primary sorted column, with an ascending sort order.
protected boolean | useToString(int column) Returns whether or not to convert the value to a string before doing comparisons when sorting.
Methods inherited from class javax.swing.RowSorter
addRowSorterListener, fireRowSorterChanged, fireSortOrderChanged, removeRowSorterListener
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultRowSorter

public DefaultRowSorter()
Creates an empty DefaultRowSorter.

Method Detail

setModelWrapper

protected final void setModelWrapper(DefaultRowSorter.ModelWrapper<M,I> modelWrapper)
Sets the model wrapper providing the data that is being sorted and filtered.

Parameters:
modelWrapper - the model wrapper responsible for providing the data that gets sorted and filtered
Throws:
IllegalArgumentException - if modelWrapper is null

getModelWrapper

protected final DefaultRowSorter.ModelWrapper<M,I> getModelWrapper()
Returns the model wrapper providing the data that is being sorted and filtered.

Returns:
the model wrapper responsible for providing the data that gets sorted and filtered

getModel

public final M getModel()
Returns the underlying model.

Specified by:
getModel in class RowSorter<M>
Returns:
the underlying model

setSortable

public void setSortable(int column,
                        boolean sortable)
Sets whether or not the specified column is sortable. The specified value is only checked when toggleSortOrder is invoked. It is still possible to sort on a column that has been marked as unsortable by directly setting the sort keys. The default is true.

Parameters:
column - the column to enable or disable sorting on, in terms of the underlying model
sortable - whether or not the specified column is sortable
Throws:
IndexOutOfBoundsException - if column is outside the range of the model
See Also:
toggleSortOrder(int), setSortKeys(java.util.List)

isSortable

public boolean isSortable(int column)
Returns true if the specified column is sortable; otherwise, false.

Parameters:
column - the column to check sorting for, in terms of the underlying model
Returns:
true if the column is sortable
Throws:
IndexOutOfBoundsException - if column is outside the range of the underlying model

setSortKeys

public void setSortKeys(List<? extends RowSorter.SortKey> sortKeys)
Sets the sort keys. This creates a copy of the supplied List; subsequent changes to the supplied List do not effect this DefaultRowSorter. If the sort keys have changed this triggers a sort.

Specified by:
setSortKeys in class RowSorter<M>
Parameters:
sortKeys - the new SortKeys; null is a shorthand for specifying an empty list, indicating that the view should be unsorted
Throws:
IllegalArgumentException - if any of the values in sortKeys are null or have a column index outside the range of the model

getSortKeys

public List<? extends RowSorter.SortKey> getSortKeys()
Returns the current sort keys. This returns an unmodifiable non-null List. If you need to change the sort keys, make a copy of the returned List, mutate the copy and invoke setSortKeys with the new list.

Specified by:
getSortKeys in class RowSorter<M>
Returns:
the current sort order

setMaxSortKeys

public void setMaxSortKeys(int max)
Sets the maximum number of sort keys. The number of sort keys determines how equal values are resolved when sorting. For example, assume a table row sorter is created and setMaxSortKeys(2) is invoked on it. The user clicks the header for column 1, causing the table rows to be sorted based on the items in column 1. Next, the user clicks the header for column 2, causing the table to be sorted based on the items in column 2; if any items in column 2 are equal, then those particular rows are ordered based on the items in column 1. In this case, we say that the rows are primarily sorted on column 2, and secondarily on column 1. If the user then clicks the header for column 3, then the items are primarily sorted on column 3 and secondarily sorted on column 2. Because the maximum number of sort keys has been set to 2 with setMaxSortKeys, column 1 no longer has an effect on the order.

The maximum number of sort keys is enforced by toggleSortOrder. You can specify more sort keys by invoking setSortKeys directly and they will all be honored. However if toggleSortOrder is subsequently invoked the maximum number of sort keys will be enforced. The default value is 3.

Parameters:
max - the maximum number of sort keys
Throws:
IllegalArgumentException - if max < 1

getMaxSortKeys

public int getMaxSortKeys()
Returns the maximum number of sort keys.

Returns:
the maximum number of sort keys

setSortsOnUpdates

public void setSortsOnUpdates(boolean sortsOnUpdates)
If true, specifies that a sort should happen when the underlying model is updated (rowsUpdated is invoked). For example, if this is true and the user edits an entry the location of that item in the view may change. The default is false.

Parameters:
sortsOnUpdates - whether or not to sort on update events

getSortsOnUpdates

public boolean getSortsOnUpdates()
Returns true if a sort should happen when the underlying model is updated; otherwise, returns false.

Returns:
whether or not to sort when the model is updated

setRowFilter

public void setRowFilter(RowFilter<? super M,? super I> filter)
Sets the filter that determines which rows, if any, should be hidden from the view. The filter is applied before sorting. A value of null indicates all values from the model should be included.

RowFilter's include method is passed an Entry that wraps the underlying model. The number of columns in the Entry corresponds to the number of columns in the ModelWrapper. The identifier comes from the ModelWrapper as well.

This method triggers a sort.

Parameters:
filter - the filter used to determine what entries should be included

getRowFilter

public RowFilter<? super M,? super I> getRowFilter()
Returns the filter that determines which rows, if any, should be hidden from view.

Returns:
the filter

toggleSortOrder

public void toggleSortOrder(int column)
Reverses the sort order from ascending to descending (or descending to ascending) if the specified column is already the primary sorted column; otherwise, makes the specified column the primary sorted column, with an ascending sort order. If the specified column is not sortable, this method has no effect.

Specified by:
toggleSortOrder in class RowSorter<M>
Parameters:
column - index of the column to make the primary sorted column, in terms of the underlying model
Throws:
IndexOutOfBoundsException - if column is outside the range of the underlying model
See Also:
setSortable(int,boolean), setMaxSortKeys(int)

convertRowIndexToView

public int convertRowIndexToView(int index)
Returns the location of index in terms of the view. That is, for the row index in the coordinates of the underlying model this returns the row index in terms of the view.

Specified by:
convertRowIndexToView in class RowSorter<M>
Parameters:
index - the row index in terms of the underlying model
Returns:
row index in terms of the view, or -1 if index has been filtered out of the view
Throws:
IndexOutOfBoundsException - if index is outside the range of the model

convertRowIndexToModel

public int convertRowIndexToModel(int index)
Returns the location of index in terms of the underlying model. That is, for the row index in the coordinates of the view this returns the row index in terms of the underlying model.

Specified by:
convertRowIndexToModel in class RowSorter<M>
Parameters:
index - the row index in terms of the underlying view
Returns:
row index in terms of the view
Throws:
IndexOutOfBoundsException - if index is outside the range of the view

sort

public void sort()
Sorts and filters the rows in the view based on the sort keys of the columns currently being sorted and the filter, if any, associated with this sorter. An empty sortKeys list indicates that the view should unsorted, the same as the model.

See Also:
setRowFilter(javax.swing.RowFilter), setSortKeys(java.util.List)

useToString

protected boolean useToString(int column)
Returns whether or not to convert the value to a string before doing comparisons when sorting. If true ModelWrapper.getStringValueAt will be used, otherwise ModelWrapper.getValueAt will be used. It is up to subclasses, such as TableRowSorter, to honor this value in their ModelWrapper implementation.

Parameters:
column - the index of the column to test, in terms of the underlying model
Throws:
IndexOutOfBoundsException - if column is not valid

setComparator

public void setComparator(int column,
                          Comparator<?> comparator)
Sets the Comparator to use when sorting the specified column. This does not trigger a sort. If you want to sort after setting the comparator you need to explicitly invoke sort.

Parameters:
column - the index of the column the Comparator is to be used for, in terms of the underlying model
comparator - the Comparator to use
Throws:
IndexOutOfBoundsException - if column is outside the range of the underlying model

getComparator

public Comparator<?> getComparator(int column)
Returns the Comparator for the specified column. This will return null if a Comparator has not been specified for the column.

Parameters:
column - the column to fetch the Comparator for, in terms of the underlying model
Returns:
the Comparator for the specified column
Throws:
IndexOutOfBoundsException - if column is outside the range of the underlying model

getViewRowCount

public int getViewRowCount()
Returns the number of rows in the view. If the contents have been filtered this might differ from the row count of the underlying model.

Specified by:
getViewRowCount in class RowSorter<M>
Returns:
number of rows in the view
See Also:
RowSorter.getModelRowCount()

getModelRowCount

public int getModelRowCount()
Returns the number of rows in the underlying model.

Specified by:
getModelRowCount in class RowSorter<M>
Returns:
number of rows in the underlying model
See Also:
RowSorter.getViewRowCount()

modelStructureChanged

public void modelStructureChanged()
Invoked when the underlying model structure has completely changed. For example, if the number of columns in a TableModel changed, this method would be invoked.

You normally do not call this method. This method is public to allow view classes to call it.

Specified by:
modelStructureChanged in class RowSorter<M>

allRowsChanged

public void allRowsChanged()
Invoked when the contents of the underlying model have completely changed. The structure of the table is the same, only the contents have changed. This is typically sent when it is too expensive to characterize the change in terms of the other methods.

You normally do not call this method. This method is public to allow view classes to call it.

Specified by:
allRowsChanged in class RowSorter<M>

rowsInserted

public void rowsInserted(int firstRow,
                         int endRow)
Invoked when rows have been inserted into the underlying model in the specified range (inclusive).

The arguments give the indices of the effected range. The first argument is in terms of the model before the change, and must be less than or equal to the size of the model before the change. The second argument is in terms of the model after the change and must be less than the size of the model after the change. For example, if you have a 5-row model and add 3 items to the end of the model the indices are 5, 7.

You normally do not call this method. This method is public to allow view classes to call it.

Specified by:
rowsInserted in class RowSorter<M>
Parameters:
firstRow - the first row
endRow - the last row
Throws:
IndexOutOfBoundsException - if either argument is invalid, or firstRow > endRow

rowsDeleted

public void rowsDeleted(int firstRow,
                        int endRow)
Invoked when rows have been deleted from the underlying model in the specified range (inclusive).

The arguments give the indices of the effected range and are in terms of the model before the change. For example, if you have a 5-row model and delete 3 items from the end of the model the indices are 2, 4.

You normally do not call this method. This method is public to allow view classes to call it.

Specified by:
rowsDeleted in class RowSorter<M>
Parameters:
firstRow - the first row
endRow - the last row
Throws:
IndexOutOfBoundsException - if either argument is outside the range of the model before the change, or firstRow > endRow

rowsUpdated

public void rowsUpdated(int firstRow,
                        int endRow)
Invoked when rows have been changed in the underlying model between the specified range (inclusive).

You normally do not call this method. This method is public to allow view classes to call it.

Specified by:
rowsUpdated in class RowSorter<M>
Parameters:
firstRow - the first row, in terms of the underlying model
endRow - the last row, in terms of the underlying model
Throws:
IndexOutOfBoundsException - if either argument is outside the range of the underlying model, or firstRow > endRow

rowsUpdated

public void rowsUpdated(int firstRow,
                        int endRow,
                        int column)
Invoked when the column in the rows have been updated in the underlying model between the specified range.

You normally do not call this method. This method is public to allow view classes to call it.

Specified by:
rowsUpdated in class RowSorter<M>
Parameters:
firstRow - the first row, in terms of the underlying model
endRow - the last row, in terms of the underlying model
column - the column that has changed, in terms of the underlying model
Throws:
IndexOutOfBoundsException - if either argument is outside the range of the underlying model after the change, firstRow > endRow, or column is outside the range of the underlying model
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultRowSorter.ModelWrapper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class DefaultRowSorter.ModelWrapper<M,I>

java.lang.Object
    extended by  javax.swing.DefaultRowSorter.ModelWrapper<M,I>
Type Parameters:
M - the type of the underlying model
I - the identifier supplied to the filter
Enclosing class:
DefaultRowSorter<M,I>
protected abstract static class DefaultRowSorter.ModelWrapper<M,I>
extends Object

DefaultRowSorter.ModelWrapper is responsible for providing the data that gets sorted by DefaultRowSorter. You normally do not interact directly with ModelWrapper. Subclasses of DefaultRowSorter provide an implementation of ModelWrapper wrapping another model. For example, TableRowSorter provides a ModelWrapper that wraps a TableModel.

ModelWrapper makes a distinction between values as Objects and Strings. This allows implementations to provide a custom string converter to be used instead of invoking toString on the object.

Since:
1.6
See Also:
RowFilter, RowFilter.Entry

Constructor Summary
protected DefaultRowSorter.ModelWrapper()
Creates a new ModelWrapper.
Method Summary
abstract int | getColumnCount() Returns the number of columns in the model.
abstract I | getIdentifier(int row) Returns the identifier for the specified row.
abstract M | getModel() Returns the underlying model that this Model is wrapping.
abstract int | getRowCount() Returns the number of rows in the model.
String | getStringValueAt(int row, int column) Returns the value as a String at the specified index.
abstract Object | getValueAt(int row, int column) Returns the value at the specified index.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultRowSorter.ModelWrapper

protected DefaultRowSorter.ModelWrapper()
Creates a new ModelWrapper.

Method Detail

getModel

public abstract M getModel()
Returns the underlying model that this Model is wrapping.

Returns:
the underlying model

getColumnCount

public abstract int getColumnCount()
Returns the number of columns in the model.

Returns:
the number of columns in the model

getRowCount

public abstract int getRowCount()
Returns the number of rows in the model.

Returns:
the number of rows in the model

getValueAt

public abstract Object getValueAt(int row,
                                  int column)
Returns the value at the specified index.

Parameters:
row - the row index
column - the column index
Returns:
the value at the specified index
Throws:
IndexOutOfBoundsException - if the indices are outside the range of the model

getStringValueAt

public String getStringValueAt(int row,
                               int column)
Returns the value as a String at the specified index. This implementation uses toString on the result from getValueAt (making sure to return an empty string for null values). Subclasses that override this method should never return null.

Parameters:
row - the row index
column - the column index
Returns:
the value at the specified index as a String
Throws:
IndexOutOfBoundsException - if the indices are outside the range of the model

getIdentifier

public abstract I getIdentifier(int row)
Returns the identifier for the specified row. The return value of this is used as the identifier for the RowFilter.Entry that is passed to the RowFilter.

Parameters:
row - the row to return the identifier for, in terms of the underlying model
Returns:
the identifier
See Also:
RowFilter.Entry.getIdentifier()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultSingleSelectionModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class DefaultSingleSelectionModel

java.lang.Object
    extended by  javax.swing.DefaultSingleSelectionModel
All Implemented Interfaces:
Serializable, SingleSelectionModel
public class DefaultSingleSelectionModel
extends Object
implements SingleSelectionModel, Serializable

A generic implementation of SingleSelectionModel.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected ChangeEvent | changeEvent
protected EventListenerList | listenerList The collection of registered listeners
Constructor Summary
DefaultSingleSelectionModel()
Method Summary
 void addChangeListener(ChangeListener l)
Adds a ChangeListener to the button.
 void clearSelection()
Clears the selection (to -1).
protected  void fireStateChanged()
Notifies all listeners that have registered interest for notification on this event type.
 ChangeListener[] getChangeListeners()
Returns an array of all the change listeners registered on this DefaultSingleSelectionModel.
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this model.
 int getSelectedIndex()
Returns the model's selection.
 boolean isSelected()
Returns true if the selection model currently has a selected value.
 void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the button.
 void setSelectedIndex(int index)
Sets the model's selected index to index.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

changeEvent

protected transient ChangeEvent changeEvent

listenerList

protected EventListenerList listenerList
The collection of registered listeners

Constructor Detail

DefaultSingleSelectionModel

public DefaultSingleSelectionModel()
Method Detail

getSelectedIndex

public int getSelectedIndex()
Description copied from interface: SingleSelectionModel
Returns the model's selection.

Specified by:
getSelectedIndex in interface SingleSelectionModel
Returns:
the model's selection, or -1 if there is no selection
See Also:
SingleSelectionModel.setSelectedIndex(int)

setSelectedIndex

public void setSelectedIndex(int index)
Description copied from interface: SingleSelectionModel
Sets the model's selected index to index. Notifies any listeners if the model changes

Specified by:
setSelectedIndex in interface SingleSelectionModel
Parameters:
index - an int specifying the model selection
See Also:
SingleSelectionModel.getSelectedIndex(), SingleSelectionModel.addChangeListener(javax.swing.event.ChangeListener)

clearSelection

public void clearSelection()
Description copied from interface: SingleSelectionModel
Clears the selection (to -1).

Specified by:
clearSelection in interface SingleSelectionModel

isSelected

public boolean isSelected()
Description copied from interface: SingleSelectionModel
Returns true if the selection model currently has a selected value.

Specified by:
isSelected in interface SingleSelectionModel
Returns:
true if a value is currently selected

addChangeListener

public void addChangeListener(ChangeListener l)
Adds a ChangeListener to the button.

Specified by:
addChangeListener in interface SingleSelectionModel
Parameters:
l - the ChangeListener to add

removeChangeListener

public void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the button.

Specified by:
removeChangeListener in interface SingleSelectionModel
Parameters:
l - the ChangeListener to remove

getChangeListeners

public ChangeListener[] getChangeListeners()
Returns an array of all the change listeners registered on this DefaultSingleSelectionModel.

Returns:
all of this model's ChangeListeners or an empty array if no change listeners are currently registered
Since:
1.4
See Also:
addChangeListener(javax.swing.event.ChangeListener), removeChangeListener(javax.swing.event.ChangeListener)

fireStateChanged

protected void fireStateChanged()
Notifies all listeners that have registered interest for notification on this event type. The event instance is created lazily.

See Also:
EventListenerList

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this model. FooListeners are registered using the addFooListener method.

You can specify the listenerType argument with a class literal, such as FooListener.class. For example, you can query a DefaultSingleSelectionModel instance m for its change listeners with the following code:

ChangeListener[] cls = (ChangeListener[])(m.getListeners(ChangeListener.class));
If no such listeners exist, this method returns an empty array.

Parameters:
listenerType - the type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener
Returns:
an array of all objects registered as FooListeners on this model, or an empty array if no such listeners have been added
Throws:
ClassCastException - if listenerType doesn't specify a class or interface that implements java.util.EventListener
Since:
1.3
See Also:
getChangeListeners()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DesktopManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface DesktopManager

All Known Implementing Classes:
DefaultDesktopManager
public interface DesktopManager

DesktopManager objects are owned by a JDesktopPane object. They are responsible for implementing L&F specific behaviors for the JDesktopPane. JInternalFrame implementations should delegate specific behaviors to the DesktopManager. For instance, if a JInternalFrame was asked to iconify, it should try:

    getDesktopPane().getDesktopManager().iconifyFrame(frame);
This delegation allows each L&F to provide custom behaviors for desktop-specific actions. (For example, how and where the internal frame's icon would appear.)

This class provides a policy for the various JInternalFrame methods, it is not meant to be called directly rather the various JInternalFrame methods will call into the DesktopManager.

See Also:
JDesktopPane, JInternalFrame, JInternalFrame.JDesktopIcon

Method Summary
void | activateFrame(JInternalFrame f) Generally, indicate that this frame has focus.
void | beginDraggingFrame(JComponent f) This method is normally called when the user has indicated that they will begin dragging a component around.
void | beginResizingFrame(JComponent f, int direction) This methods is normally called when the user has indicated that they will begin resizing the frame.
void | closeFrame(JInternalFrame f) Generally, this call should remove the frame from it's parent.
void | deactivateFrame(JInternalFrame f) Generally, indicate that this frame has lost focus.
void | deiconifyFrame(JInternalFrame f) Generally, remove any iconic representation that is present and restore the frame to it's original size and location.
void | dragFrame(JComponent f, int newX, int newY) The user has moved the frame.
void | endDraggingFrame(JComponent f) This method signals the end of the dragging session.
void | endResizingFrame(JComponent f) This method signals the end of the resize session.
void | iconifyFrame(JInternalFrame f) Generally, remove this frame from it's parent and add an iconic representation.
void | maximizeFrame(JInternalFrame f) Generally, the frame should be resized to match it's parents bounds.
void | minimizeFrame(JInternalFrame f) Generally, this indicates that the frame should be restored to it's size and position prior to a maximizeFrame() call.
void | openFrame(JInternalFrame f) If possible, display this frame in an appropriate location.
void | resizeFrame(JComponent f, int newX, int newY, int newWidth, int newHeight) The user has resized the component.
void | setBoundsForFrame(JComponent f, int newX, int newY, int newWidth, int newHeight) This is a primitive reshape method.

Method Detail

openFrame

void openFrame(JInternalFrame f)
If possible, display this frame in an appropriate location. Normally, this is not called, as the creator of the JInternalFrame will add the frame to the appropriate parent.

closeFrame

void closeFrame(JInternalFrame f)
Generally, this call should remove the frame from it's parent.

maximizeFrame

void maximizeFrame(JInternalFrame f)
Generally, the frame should be resized to match it's parents bounds.

minimizeFrame

void minimizeFrame(JInternalFrame f)
Generally, this indicates that the frame should be restored to it's size and position prior to a maximizeFrame() call.

iconifyFrame

void iconifyFrame(JInternalFrame f)
Generally, remove this frame from it's parent and add an iconic representation.

deiconifyFrame

void deiconifyFrame(JInternalFrame f)
Generally, remove any iconic representation that is present and restore the frame to it's original size and location.

activateFrame

void activateFrame(JInternalFrame f)
Generally, indicate that this frame has focus. This is usually called after the JInternalFrame's IS_SELECTED_PROPERTY has been set to true.

deactivateFrame

void deactivateFrame(JInternalFrame f)
Generally, indicate that this frame has lost focus. This is usually called after the JInternalFrame's IS_SELECTED_PROPERTY has been set to false.

beginDraggingFrame

void beginDraggingFrame(JComponent f)
This method is normally called when the user has indicated that they will begin dragging a component around. This method should be called prior to any dragFrame() calls to allow the DesktopManager to prepare any necessary state. Normally f will be a JInternalFrame.

dragFrame

void dragFrame(JComponent f,
               int newX,
               int newY)
The user has moved the frame. Calls to this method will be preceded by calls to beginDraggingFrame(). Normally f will be a JInternalFrame.

endDraggingFrame

void endDraggingFrame(JComponent f)
This method signals the end of the dragging session. Any state maintained by the DesktopManager can be removed here. Normally f will be a JInternalFrame.

beginResizingFrame

void beginResizingFrame(JComponent f,
                        int direction)
This methods is normally called when the user has indicated that they will begin resizing the frame. This method should be called prior to any resizeFrame() calls to allow the DesktopManager to prepare any necessary state. Normally f will be a JInternalFrame.

resizeFrame

void resizeFrame(JComponent f,
                 int newX,
                 int newY,
                 int newWidth,
                 int newHeight)
The user has resized the component. Calls to this method will be preceded by calls to beginResizingFrame(). Normally f will be a JInternalFrame.

endResizingFrame

void endResizingFrame(JComponent f)
This method signals the end of the resize session. Any state maintained by the DesktopManager can be removed here. Normally f will be a JInternalFrame.

setBoundsForFrame

void setBoundsForFrame(JComponent f,
                       int newX,
                       int newY,
                       int newWidth,
                       int newHeight)
This is a primitive reshape method.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DropMode

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.swing
Enum DropMode

java.lang.Object
    extended by  java.lang.Enum<DropMode>
        extended by  javax.swing.DropMode
All Implemented Interfaces:
Serializable, Comparable<DropMode>
public enum DropMode
extends Enum<DropMode>

Drop modes, used to determine the method by which a component tracks and indicates a drop location during drag and drop.

Since:
1.6
See Also:
JTable.setDropMode(javax.swing.DropMode),
JList.setDropMode(javax.swing.DropMode),
JTree.setDropMode(javax.swing.DropMode),
JTextComponent.setDropMode(javax.swing.DropMode)

Enum Constant Summary
INSERT
The drop location should be tracked in terms of the position where new data should be inserted.
INSERT_COLS
The drop location should be tracked in terms of the column index where new columns should be inserted to accommodate the dropped data.
INSERT_ROWS
The drop location should be tracked in terms of the row index where new rows should be inserted to accommodate the dropped data.
ON
The drop location should be tracked in terms of the index of existing items.
ON_OR_INSERT
This mode is a combination of ON and INSERT, specifying that data can be dropped on existing items, or in insert locations as specified by INSERT.
ON_OR_INSERT_COLS
This mode is a combination of ON and INSERT_COLS, specifying that data can be dropped on existing items, or as insert columns as specified by INSERT_COLS.
ON_OR_INSERT_ROWS
This mode is a combination of ON and INSERT_ROWS, specifying that data can be dropped on existing items, or as insert rows as specified by INSERT_ROWS.
USE_SELECTION
A component's own internal selection mechanism (or caret for text components) should be used to track the drop location.
Method Summary
static DropMode | valueOf(String name) Returns the enum constant of this type with the specified name.
static DropMode[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

USE_SELECTION

public static final DropMode USE_SELECTION
A component's own internal selection mechanism (or caret for text components) should be used to track the drop location.

ON

public static final DropMode ON
The drop location should be tracked in terms of the index of existing items. Useful for dropping on items in tables, lists, and trees.

INSERT

public static final DropMode INSERT
The drop location should be tracked in terms of the position where new data should be inserted. For components that manage a list of items (list and tree for example), the drop location should indicate the index where new data should be inserted. For text components the location should represent a position between characters. For components that manage tabular data (table for example), the drop location should indicate where to insert new rows, columns, or both, to accommodate the dropped data.

INSERT_ROWS

public static final DropMode INSERT_ROWS
The drop location should be tracked in terms of the row index where new rows should be inserted to accommodate the dropped data. This is useful for components that manage tabular data.

INSERT_COLS

public static final DropMode INSERT_COLS
The drop location should be tracked in terms of the column index where new columns should be inserted to accommodate the dropped data. This is useful for components that manage tabular data.

ON_OR_INSERT

public static final DropMode ON_OR_INSERT
This mode is a combination of ON and INSERT, specifying that data can be dropped on existing items, or in insert locations as specified by INSERT.

ON_OR_INSERT_ROWS

public static final DropMode ON_OR_INSERT_ROWS
This mode is a combination of ON and INSERT_ROWS, specifying that data can be dropped on existing items, or as insert rows as specified by INSERT_ROWS.

ON_OR_INSERT_COLS

public static final DropMode ON_OR_INSERT_COLS
This mode is a combination of ON and INSERT_COLS, specifying that data can be dropped on existing items, or as insert columns as specified by INSERT_COLS.

Method Detail

values

public static DropMode[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (DropMode c : DropMode.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static DropMode valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


event

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.swing.event

Provides for events fired by Swing components.

See:
Description

Interface Summary
AncestorListener | AncestorListener Interface to support notification when changes occur to a JComponent or one of its ancestors.
CaretListener | Listener for changes in the caret position of a text component.
CellEditorListener | CellEditorListener defines the interface for an object that listens to changes in a CellEditor
ChangeListener | Defines an object which listens for ChangeEvents.
DocumentEvent | Interface for document change notifications.
DocumentEvent.ElementChange | Describes changes made to a specific element.
DocumentListener | Interface for an observer to register to receive notifications of changes to a text document.
HyperlinkListener | HyperlinkListener
InternalFrameListener | The listener interface for receiving internal frame events.
ListDataListener | ListDataListener
ListSelectionListener | The listener that's notified when a lists selection value changes.
MenuDragMouseListener | Defines a menu mouse-drag listener.
MenuKeyListener | MenuKeyListener
MenuListener | Defines a listener for menu events.
MouseInputListener | A listener implementing all the methods in both the MouseListener and MouseMotionListener interfaces.
PopupMenuListener | A popup menu listener
RowSorterListener | RowSorterListeners are notified of changes to a RowSorter.
TableColumnModelListener | TableColumnModelListener defines the interface for an object that listens to changes in a TableColumnModel.
TableModelListener | TableModelListener defines the interface for an object that listens to changes in a TableModel.
TreeExpansionListener | The listener that's notified when a tree expands or collapses a node.
TreeModelListener | Defines the interface for an object that listens to changes in a TreeModel.
TreeSelectionListener | The listener that's notified when the selection in a TreeSelectionModel changes.
TreeWillExpandListener | The listener that's notified when a tree expands or collapses a node.
UndoableEditListener | Interface implemented by a class interested in hearing about undoable operations.

Class Summary
AncestorEvent | An event reported to a child component that originated from an ancestor in the component hierarchy.
CaretEvent | CaretEvent is used to notify interested parties that the text caret has changed in the event source.
ChangeEvent | ChangeEvent is used to notify interested parties that state has changed in the event source.
DocumentEvent.EventType | Enumeration for document event types
EventListenerList | A class that holds a list of EventListeners.
HyperlinkEvent | HyperlinkEvent is used to notify interested parties that something has happened with respect to a hypertext link.
HyperlinkEvent.EventType | Defines the ENTERED, EXITED, and ACTIVATED event types, along with their string representations, returned by toString().
InternalFrameAdapter | An abstract adapter class for receiving internal frame events.
InternalFrameEvent | An AWTEvent that adds support for JInternalFrame objects as the event source.
ListDataEvent | Defines an event that encapsulates changes to a list.
ListSelectionEvent | An event that characterizes a change in selection.
MenuDragMouseEvent | MenuDragMouseEvent is used to notify interested parties that the menu element has received a MouseEvent forwarded to it under drag conditions.
MenuEvent | MenuEvent is used to notify interested parties that the menu which is the event source has been posted, selected, or canceled.
MenuKeyEvent | MenuKeyEvent is used to notify interested parties that the menu element has received a KeyEvent forwarded to it in a menu tree.
MouseInputAdapter | An empty implementation of the MouseInputListener interface, provided as a convenience to simplify the task of creating listeners, by extending and implementing only the methods of interest.
PopupMenuEvent | PopupMenuEvent only contains the source of the event which is the JPoupMenu sending the event
RowSorterEvent | RowSorterEvent provides notification of changes to a RowSorter.
SwingPropertyChangeSupport | This subclass of java.beans.PropertyChangeSupport is almost identical in functionality.
TableColumnModelEvent | TableColumnModelEvent is used to notify listeners that a table column model has changed, such as a column was added, removed, or moved.
TableModelEvent | TableModelEvent is used to notify listeners that a table model has changed.
TreeExpansionEvent | An event used to identify a single path in a tree.
TreeModelEvent | Encapsulates information describing changes to a tree model, and used to notify tree model listeners of the change.
TreeSelectionEvent | An event that characterizes a change in the current selection.
UndoableEditEvent | An event indicating that an operation which can be undone has occurred.

Enum Summary
RowSorterEvent.Type Enumeration of the types of RowSorterEvents.

Package javax.swing.event Description

Provides for events fired by Swing components. It contains event classes and corresponding event listener interfaces for events fired by Swing components in addition to those events in the java.awt.event package.

Note: Most of the Swing API is not thread safe. For details, see Threads and Swing, a section in The Java Tutorial.

Related Documentation

For overviews, tutorials, examples, guides, and tool documentation, please see:
  • Writing Event Listeners, a section in The Java Tutorial

Since:
1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.swing.event Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.swing.event

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.swing.event.DocumentEvent.EventType
    • javax.swing.event.EventListenerList (implements java.io.Serializable)
    • java.util.EventObject (implements java.io.Serializable)
      • java.awt.AWTEvent
        • javax.swing.event.AncestorEvent
        • java.awt.event.ComponentEvent
          • java.awt.event.InputEvent
            • java.awt.event.KeyEvent
              • javax.swing.event.MenuKeyEvent
            • java.awt.event.MouseEvent
              • javax.swing.event.MenuDragMouseEvent
        • javax.swing.event.InternalFrameEvent
      • javax.swing.event.CaretEvent
      • javax.swing.event.ChangeEvent
      • javax.swing.event.HyperlinkEvent
      • javax.swing.event.ListDataEvent
      • javax.swing.event.ListSelectionEvent
      • javax.swing.event.MenuEvent
      • javax.swing.event.PopupMenuEvent
      • javax.swing.event.RowSorterEvent
      • javax.swing.event.TableColumnModelEvent
      • javax.swing.event.TableModelEvent
      • javax.swing.event.TreeExpansionEvent
      • javax.swing.event.TreeModelEvent
      • javax.swing.event.TreeSelectionEvent
      • javax.swing.event.UndoableEditEvent
    • javax.swing.event.HyperlinkEvent.EventType
    • javax.swing.event.InternalFrameAdapter (implements javax.swing.event.InternalFrameListener)
    • java.awt.event.MouseAdapter (implements java.awt.event.MouseListener, java.awt.event.MouseMotionListener, java.awt.event.MouseWheelListener)
      • javax.swing.event.MouseInputAdapter (implements javax.swing.event.MouseInputListener)
    • java.beans.PropertyChangeSupport (implements java.io.Serializable)
      • javax.swing.event.SwingPropertyChangeSupport

Interface Hierarchy

  • javax.swing.event.DocumentEvent
  • javax.swing.event.DocumentEvent.ElementChange
  • java.util.EventListener
    • javax.swing.event.AncestorListener
    • javax.swing.event.CaretListener
    • javax.swing.event.CellEditorListener
    • javax.swing.event.ChangeListener
    • javax.swing.event.DocumentListener
    • javax.swing.event.HyperlinkListener
    • javax.swing.event.InternalFrameListener
    • javax.swing.event.ListDataListener
    • javax.swing.event.ListSelectionListener
    • javax.swing.event.MenuDragMouseListener
    • javax.swing.event.MenuKeyListener
    • javax.swing.event.MenuListener
    • java.awt.event.MouseListener
      • javax.swing.event.MouseInputListener (also extends java.awt.event.MouseMotionListener)
    • java.awt.event.MouseMotionListener
      • javax.swing.event.MouseInputListener (also extends java.awt.event.MouseListener)
    • javax.swing.event.PopupMenuListener
    • javax.swing.event.RowSorterListener
    • javax.swing.event.TableColumnModelListener
    • javax.swing.event.TableModelListener
    • javax.swing.event.TreeExpansionListener
    • javax.swing.event.TreeModelListener
    • javax.swing.event.TreeSelectionListener
    • javax.swing.event.TreeWillExpandListener
    • javax.swing.event.UndoableEditListener

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • javax.swing.event.RowSorterEvent.Type
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


MouseInputListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface MouseInputListener

All Superinterfaces:
EventListener, MouseListener, MouseMotionListener
All Known Implementing Classes:
BasicDesktopIconUI.MouseInputHandler, BasicInternalFrameUI.BorderListener, BasicInternalFrameUI.GlassPaneDispatcher, BasicListUI.MouseInputHandler, BasicMenuItemUI.MouseInputHandler, BasicMenuUI.MouseInputHandler, BasicSliderUI.TrackListener, BasicTableHeaderUI.MouseInputHandler, BasicTableUI.MouseInputHandler, BasicToolBarUI.DockingListener, BasicTreeUI.MouseInputHandler, MetalToolBarUI.MetalDockingListener, MouseInputAdapter
public interface MouseInputListener
extends MouseListener, MouseMotionListener

A listener implementing all the methods in both the MouseListener and MouseMotionListener interfaces.

See Also:
MouseInputAdapter

Method Summary
Methods inherited from interface java.awt.event.MouseListener
mouseClicked, mouseEntered, mouseExited, mousePressed, mouseReleased
Methods inherited from interface java.awt.event.MouseMotionListener
mouseDragged, mouseMoved

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Package javax.swing.event

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.swing.event

Packages that use javax.swing.event
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.colorchooser | Contains classes and interfaces used by the JColorChooser component.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.
javax.swing.undo | Allows developers to provide support for undo/redo in applications such as text editors.

Classes in javax.swing.event used by javax.swing
AncestorListener
AncestorListener Interface to support notification when changes occur to a JComponent or one of its ancestors.
CaretListener
Listener for changes in the caret position of a text component.
CellEditorListener
CellEditorListener defines the interface for an object that listens to changes in a CellEditor
ChangeEvent
ChangeEvent is used to notify interested parties that state has changed in the event source.
ChangeListener
Defines an object which listens for ChangeEvents.
DocumentListener
Interface for an observer to register to receive notifications of changes to a text document.
EventListenerList
A class that holds a list of EventListeners.
HyperlinkEvent
HyperlinkEvent is used to notify interested parties that something has happened with respect to a hypertext link.
HyperlinkListener
HyperlinkListener
InternalFrameListener
The listener interface for receiving internal frame events.
ListDataEvent
Defines an event that encapsulates changes to a list.
ListDataListener
ListDataListener
ListSelectionEvent
An event that characterizes a change in selection.
ListSelectionListener
The listener that's notified when a lists selection value changes.
MenuDragMouseEvent
MenuDragMouseEvent is used to notify interested parties that the menu element has received a MouseEvent forwarded to it under drag conditions.
MenuDragMouseListener
Defines a menu mouse-drag listener.
MenuKeyEvent
MenuKeyEvent is used to notify interested parties that the menu element has received a KeyEvent forwarded to it in a menu tree.
MenuKeyListener
MenuKeyListener
MenuListener
Defines a listener for menu events.
PopupMenuListener
A popup menu listener
RowSorterEvent
RowSorterEvent provides notification of changes to a RowSorter.
RowSorterListener
RowSorterListeners are notified of changes to a RowSorter.
SwingPropertyChangeSupport
This subclass of java.beans.PropertyChangeSupport is almost identical in functionality.
TableColumnModelEvent
TableColumnModelEvent is used to notify listeners that a table column model has changed, such as a column was added, removed, or moved.
TableColumnModelListener
TableColumnModelListener defines the interface for an object that listens to changes in a TableColumnModel.
TableModelEvent
TableModelEvent is used to notify listeners that a table model has changed.
TableModelListener
TableModelListener defines the interface for an object that listens to changes in a TableModel.
TreeExpansionEvent
An event used to identify a single path in a tree.
TreeExpansionListener
The listener that's notified when a tree expands or collapses a node.
TreeModelEvent
Encapsulates information describing changes to a tree model, and used to notify tree model listeners of the change.
TreeModelListener
Defines the interface for an object that listens to changes in a TreeModel.
TreeSelectionEvent
An event that characterizes a change in the current selection.
TreeSelectionListener
The listener that's notified when the selection in a TreeSelectionModel changes.
TreeWillExpandListener
The listener that's notified when a tree expands or collapses a node.

Classes in javax.swing.event used by javax.swing.colorchooser
ChangeEvent
ChangeEvent is used to notify interested parties that state has changed in the event source.
ChangeListener
Defines an object which listens for ChangeEvents.
EventListenerList
A class that holds a list of EventListeners.

Classes in javax.swing.event used by javax.swing.event
AncestorEvent
An event reported to a child component that originated from an ancestor in the component hierarchy.
CaretEvent
CaretEvent is used to notify interested parties that the text caret has changed in the event source.
ChangeEvent
ChangeEvent is used to notify interested parties that state has changed in the event source.
DocumentEvent
Interface for document change notifications.
DocumentEvent.ElementChange
Describes changes made to a specific element.
DocumentEvent.EventType
Enumeration for document event types
HyperlinkEvent
HyperlinkEvent is used to notify interested parties that something has happened with respect to a hypertext link.
HyperlinkEvent.EventType
Defines the ENTERED, EXITED, and ACTIVATED event types, along with their string representations, returned by toString().
InternalFrameEvent
An AWTEvent that adds support for JInternalFrame objects as the event source.
InternalFrameListener
The listener interface for receiving internal frame events.
ListDataEvent
Defines an event that encapsulates changes to a list.
ListSelectionEvent
An event that characterizes a change in selection.
MenuDragMouseEvent
MenuDragMouseEvent is used to notify interested parties that the menu element has received a MouseEvent forwarded to it under drag conditions.
MenuEvent
MenuEvent is used to notify interested parties that the menu which is the event source has been posted, selected, or canceled.
MenuKeyEvent
MenuKeyEvent is used to notify interested parties that the menu element has received a KeyEvent forwarded to it in a menu tree.
MouseInputListener
A listener implementing all the methods in both the MouseListener and MouseMotionListener interfaces.
PopupMenuEvent
PopupMenuEvent only contains the source of the event which is the JPoupMenu sending the event
RowSorterEvent
RowSorterEvent provides notification of changes to a RowSorter.
RowSorterEvent.Type
Enumeration of the types of RowSorterEvents.
TableColumnModelEvent
TableColumnModelEvent is used to notify listeners that a table column model has changed, such as a column was added, removed, or moved.
TableModelEvent
TableModelEvent is used to notify listeners that a table model has changed.
TreeExpansionEvent
An event used to identify a single path in a tree.
TreeModelEvent
Encapsulates information describing changes to a tree model, and used to notify tree model listeners of the change.
TreeSelectionEvent
An event that characterizes a change in the current selection.
UndoableEditEvent
An event indicating that an operation which can be undone has occurred.

Classes in javax.swing.event used by javax.swing.plaf.basic
CellEditorListener
CellEditorListener defines the interface for an object that listens to changes in a CellEditor
ChangeEvent
ChangeEvent is used to notify interested parties that state has changed in the event source.
ChangeListener
Defines an object which listens for ChangeEvents.
InternalFrameEvent
An AWTEvent that adds support for JInternalFrame objects as the event source.
InternalFrameListener
The listener interface for receiving internal frame events.
ListDataEvent
Defines an event that encapsulates changes to a list.
ListDataListener
ListDataListener
ListSelectionEvent
An event that characterizes a change in selection.
ListSelectionListener
The listener that's notified when a lists selection value changes.
MenuDragMouseListener
Defines a menu mouse-drag listener.
MenuKeyListener
MenuKeyListener
MenuListener
Defines a listener for menu events.
MouseInputAdapter
An empty implementation of the MouseInputListener interface, provided as a convenience to simplify the task of creating listeners, by extending and implementing only the methods of interest.
MouseInputListener
A listener implementing all the methods in both the MouseListener and MouseMotionListener interfaces.
TreeExpansionEvent
An event used to identify a single path in a tree.
TreeExpansionListener
The listener that's notified when a tree expands or collapses a node.
TreeModelEvent
Encapsulates information describing changes to a tree model, and used to notify tree model listeners of the change.
TreeModelListener
Defines the interface for an object that listens to changes in a TreeModel.
TreeSelectionEvent
An event that characterizes a change in the current selection.
TreeSelectionListener
The listener that's notified when the selection in a TreeSelectionModel changes.

Classes in javax.swing.event used by javax.swing.plaf.metal
ListSelectionEvent
An event that characterizes a change in selection.
ListSelectionListener
The listener that's notified when a lists selection value changes.
MouseInputAdapter
An empty implementation of the MouseInputListener interface, provided as a convenience to simplify the task of creating listeners, by extending and implementing only the methods of interest.
MouseInputListener
A listener implementing all the methods in both the MouseListener and MouseMotionListener interfaces.

Classes in javax.swing.event used by javax.swing.table
ChangeEvent
ChangeEvent is used to notify interested parties that state has changed in the event source.
EventListenerList
A class that holds a list of EventListeners.
ListSelectionEvent
An event that characterizes a change in selection.
ListSelectionListener
The listener that's notified when a lists selection value changes.
TableColumnModelEvent
TableColumnModelEvent is used to notify listeners that a table column model has changed, such as a column was added, removed, or moved.
TableColumnModelListener
TableColumnModelListener defines the interface for an object that listens to changes in a TableColumnModel.
TableModelEvent
TableModelEvent is used to notify listeners that a table model has changed.
TableModelListener
TableModelListener defines the interface for an object that listens to changes in a TableModel.

Classes in javax.swing.event used by javax.swing.text
CaretEvent
CaretEvent is used to notify interested parties that the text caret has changed in the event source.
CaretListener
Listener for changes in the caret position of a text component.
ChangeEvent
ChangeEvent is used to notify interested parties that state has changed in the event source.
ChangeListener
Defines an object which listens for ChangeEvents.
DocumentEvent
Interface for document change notifications.
DocumentEvent.ElementChange
Describes changes made to a specific element.
DocumentEvent.EventType
Enumeration for document event types
DocumentListener
Interface for an observer to register to receive notifications of changes to a text document.
EventListenerList
A class that holds a list of EventListeners.
UndoableEditEvent
An event indicating that an operation which can be undone has occurred.
UndoableEditListener
Interface implemented by a class interested in hearing about undoable operations.

Classes in javax.swing.event used by javax.swing.text.html
DocumentEvent
Interface for document change notifications.
HyperlinkEvent
HyperlinkEvent is used to notify interested parties that something has happened with respect to a hypertext link.
HyperlinkEvent.EventType
Defines the ENTERED, EXITED, and ACTIVATED event types, along with their string representations, returned by toString().
UndoableEditEvent
An event indicating that an operation which can be undone has occurred.

Classes in javax.swing.event used by javax.swing.tree
CellEditorListener
CellEditorListener defines the interface for an object that listens to changes in a CellEditor
EventListenerList
A class that holds a list of EventListeners.
SwingPropertyChangeSupport
This subclass of java.beans.PropertyChangeSupport is almost identical in functionality.
TreeExpansionEvent
An event used to identify a single path in a tree.
TreeModelEvent
Encapsulates information describing changes to a tree model, and used to notify tree model listeners of the change.
TreeModelListener
Defines the interface for an object that listens to changes in a TreeModel.
TreeSelectionEvent
An event that characterizes a change in the current selection.
TreeSelectionListener
The listener that's notified when the selection in a TreeSelectionModel changes.

Classes in javax.swing.event used by javax.swing.undo
UndoableEditEvent
An event indicating that an operation which can be undone has occurred.
UndoableEditListener
Interface implemented by a class interested in hearing about undoable operations.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AncestorEvent

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class AncestorEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  java.awt.AWTEvent
            extended by  javax.swing.event.AncestorEvent
All Implemented Interfaces:
Serializable
public class AncestorEvent
extends AWTEvent

An event reported to a child component that originated from an ancestor in the component hierarchy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
static int | ANCESTOR_ADDED An ancestor-component was added to the hierarchy of visible objects (made visible), and is currently being displayed.
static int | ANCESTOR_MOVED An ancestor-component changed its position on the screen.
static int | ANCESTOR_REMOVED An ancestor-component was removed from the hierarchy of visible objects (hidden) and is no longer being displayed.
Fields inherited from class java.awt.AWTEvent
ACTION_EVENT_MASK, ADJUSTMENT_EVENT_MASK, COMPONENT_EVENT_MASK, consumed, CONTAINER_EVENT_MASK, FOCUS_EVENT_MASK, HIERARCHY_BOUNDS_EVENT_MASK, HIERARCHY_EVENT_MASK, id, INPUT_METHOD_EVENT_MASK, INVOCATION_EVENT_MASK, ITEM_EVENT_MASK, KEY_EVENT_MASK, MOUSE_EVENT_MASK, MOUSE_MOTION_EVENT_MASK, MOUSE_WHEEL_EVENT_MASK, PAINT_EVENT_MASK, RESERVED_ID_MAX, TEXT_EVENT_MASK, WINDOW_EVENT_MASK, WINDOW_FOCUS_EVENT_MASK, WINDOW_STATE_EVENT_MASK
Fields inherited from class java.util.EventObject
source
Constructor Summary
AncestorEvent(JComponent source, int id, Container ancestor, Container ancestorParent)
Constructs an AncestorEvent object to identify a change in an ancestor-component's display-status.
Method Summary
Container | getAncestor() Returns the ancestor that the event actually occurred on.
Container | getAncestorParent() Returns the parent of the ancestor the event actually occurred on.
JComponent | getComponent() Returns the component that the listener was added to.
Methods inherited from class java.awt.AWTEvent
consume, getID, isConsumed, paramString, setSource, toString
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ANCESTOR_ADDED

public static final int ANCESTOR_ADDED
An ancestor-component was added to the hierarchy of visible objects (made visible), and is currently being displayed.

See Also:
Constant Field Values

ANCESTOR_REMOVED

public static final int ANCESTOR_REMOVED
An ancestor-component was removed from the hierarchy of visible objects (hidden) and is no longer being displayed.

See Also:
Constant Field Values

ANCESTOR_MOVED

public static final int ANCESTOR_MOVED
An ancestor-component changed its position on the screen.

See Also:
Constant Field Values
Constructor Detail

AncestorEvent

public AncestorEvent(JComponent source,
                     int id,
                     Container ancestor,
                     Container ancestorParent)
Constructs an AncestorEvent object to identify a change in an ancestor-component's display-status.

Parameters:
source - the JComponent that originated the event (typically this)
id - an int specifying ANCESTOR_ADDED, ANCESTOR_REMOVED or ANCESTOR_MOVED
ancestor - a Container object specifying the ancestor-component whose display-status changed
ancestorParent - a Container object specifying the ancestor's parent
Method Detail

getAncestor

public Container getAncestor()
Returns the ancestor that the event actually occurred on.

getAncestorParent

public Container getAncestorParent()
Returns the parent of the ancestor the event actually occurred on. This is most interesting in an ANCESTOR_REMOVED event, as the ancestor may no longer be in the component hierarchy.

getComponent

public JComponent getComponent()
Returns the component that the listener was added to.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AncestorListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface AncestorListener

All Superinterfaces:
EventListener
public interface AncestorListener
extends EventListener

AncestorListener Interface to support notification when changes occur to a JComponent or one of its ancestors. These include movement and when the component becomes visible or invisible, either by the setVisible() method or by being added or removed from the component hierarchy.

Method Summary
void | ancestorAdded(AncestorEvent event) Called when the source or one of its ancestors is made visible either by setVisible(true) being called or by its being added to the component hierarchy.
void | ancestorMoved(AncestorEvent event) Called when either the source or one of its ancestors is moved.
void | ancestorRemoved(AncestorEvent event) Called when the source or one of its ancestors is made invisible either by setVisible(false) being called or by its being remove from the component hierarchy.

Method Detail

ancestorAdded

void ancestorAdded(AncestorEvent event)
Called when the source or one of its ancestors is made visible either by setVisible(true) being called or by its being added to the component hierarchy. The method is only called if the source has actually become visible. For this to be true all its parents must be visible and it must be in a hierarchy rooted at a Window

ancestorRemoved

void ancestorRemoved(AncestorEvent event)
Called when the source or one of its ancestors is made invisible either by setVisible(false) being called or by its being remove from the component hierarchy. The method is only called if the source has actually become invisible. For this to be true at least one of its parents must by invisible or it is not in a hierarchy rooted at a Window

ancestorMoved

void ancestorMoved(AncestorEvent event)
Called when either the source or one of its ancestors is moved.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CaretEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class CaretEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.swing.event.CaretEvent
All Implemented Interfaces:
Serializable
public abstract class CaretEvent
extends EventObject

CaretEvent is used to notify interested parties that the text caret has changed in the event source.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
CaretEvent(Object source)
Creates a new CaretEvent object.
Method Summary
abstract int | getDot() Fetches the location of the caret.
abstract int | getMark() Fetches the location of other end of a logical selection.
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CaretEvent

public CaretEvent(Object source)
Creates a new CaretEvent object.

Parameters:
source - the object responsible for the event
Method Detail

getDot

public abstract int getDot()
Fetches the location of the caret.

Returns:
the dot >= 0

getMark

public abstract int getMark()
Fetches the location of other end of a logical selection. If there is no selection, this will be the same as dot.

Returns:
the mark >= 0
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CaretListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface CaretListener

All Superinterfaces:
EventListener
All Known Implementing Classes:
JEditorPane.AccessibleJEditorPane, JEditorPane.AccessibleJEditorPaneHTML, JEditorPane.JEditorPaneAccessibleHypertextSupport, JPasswordField.AccessibleJPasswordField, JTextArea.AccessibleJTextArea, JTextComponent.AccessibleJTextComponent, JTextField.AccessibleJTextField
public interface CaretListener
extends EventListener

Listener for changes in the caret position of a text component.

Method Summary
 void caretUpdate(CaretEvent e)
Called when the caret position is updated.

Method Detail

caretUpdate

void caretUpdate(CaretEvent e)
Called when the caret position is updated.

Parameters:
e - the caret event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CellEditorListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface CellEditorListener

All Superinterfaces:
EventListener
All Known Implementing Classes:
BasicTreeUI.CellEditorHandler, JTable, JTable.AccessibleJTable
public interface CellEditorListener
extends EventListener

CellEditorListener defines the interface for an object that listens to changes in a CellEditor

Method Summary
void | editingCanceled(ChangeEvent e) This tells the listeners the editor has canceled editing
void | editingStopped(ChangeEvent e) This tells the listeners the editor has ended editing

Method Detail

editingStopped

void editingStopped(ChangeEvent e)
This tells the listeners the editor has ended editing

editingCanceled

void editingCanceled(ChangeEvent e)
This tells the listeners the editor has canceled editing

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ChangeEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class ChangeEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.swing.event.ChangeEvent
All Implemented Interfaces:
Serializable
public class ChangeEvent
extends EventObject

ChangeEvent is used to notify interested parties that state has changed in the event source.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
ChangeEvent(Object source)
Constructs a ChangeEvent object.
Method Summary
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ChangeEvent

public ChangeEvent(Object source)
Constructs a ChangeEvent object.

Parameters:
source - the Object that is the source of the event (typically this)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ChangeListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface ChangeListener

All Superinterfaces:
EventListener
All Known Implementing Classes:
AbstractButton.ButtonChangeListener, BasicButtonListener, BasicMenuUI.ChangeHandler, BasicProgressBarUI.ChangeHandler, BasicScrollBarUI.ModelListener, BasicScrollPaneUI.HSBChangeListener, BasicScrollPaneUI.ViewportChangeHandler, BasicScrollPaneUI.VSBChangeListener, BasicSliderUI.ChangeHandler, BasicTabbedPaneUI.TabSelectionHandler, JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem, JMenu.AccessibleJMenu, JMenuItem.AccessibleJMenuItem, JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem, JScrollPane.AccessibleJScrollPane, JSpinner.AccessibleJSpinner, JSpinner.DateEditor, JSpinner.DefaultEditor, JSpinner.ListEditor, JSpinner.NumberEditor, JTabbedPane.AccessibleJTabbedPane, JTabbedPane.ModelListener, ProgressMonitor.AccessibleProgressMonitor
public interface ChangeListener
extends EventListener

Defines an object which listens for ChangeEvents.

Method Summary
 void stateChanged(ChangeEvent e)
Invoked when the target of the listener has changed its state.

Method Detail

stateChanged

void stateChanged(ChangeEvent e)
Invoked when the target of the listener has changed its state.

Parameters:
e - a ChangeEvent object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.swing.event.AncestorEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.AncestorEvent

Packages that use AncestorEvent
javax.swing.event Provides for events fired by Swing components.

Uses of AncestorEvent in javax.swing.event

Methods in javax.swing.event with parameters of type AncestorEvent
void | AncestorListener.ancestorAdded(AncestorEvent event) Called when the source or one of its ancestors is made visible either by setVisible(true) being called or by its being added to the component hierarchy.
void | AncestorListener.ancestorMoved(AncestorEvent event) Called when either the source or one of its ancestors is moved.
void | AncestorListener.ancestorRemoved(AncestorEvent event) Called when the source or one of its ancestors is made invisible either by setVisible(false) being called or by its being remove from the component hierarchy.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.CaretEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.CaretEvent

Packages that use CaretEvent
javax.swing.event | Provides for events fired by Swing components.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of CaretEvent in javax.swing.event

Methods in javax.swing.event with parameters of type CaretEvent
 void CaretListener.caretUpdate(CaretEvent e)
Called when the caret position is updated.

Uses of CaretEvent in javax.swing.text

Methods in javax.swing.text with parameters of type CaretEvent
void | JTextComponent.AccessibleJTextComponent.caretUpdate(CaretEvent e) Handles caret updates (fire appropriate property change event, which are AccessibleContext.ACCESSIBLE_CARET_PROPERTY and AccessibleContext.ACCESSIBLE_SELECTION_PROPERTY).
protected void | JTextComponent.fireCaretUpdate(CaretEvent e) Notifies all listeners that have registered interest for notification on this event type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.ChangeEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.ChangeEvent

Packages that use ChangeEvent
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.colorchooser | Contains classes and interfaces used by the JColorChooser component.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of ChangeEvent in javax.swing

Fields in javax.swing declared as ChangeEvent
protected ChangeEvent | JProgressBar.changeEvent Only one ChangeEvent is needed per instance since the event's only interesting property is the immutable source, which is the progress bar.
protected ChangeEvent | JSlider.changeEvent Only one ChangeEvent is needed per slider instance since the event's only (read-only) state is the source property.
protected ChangeEvent | JTabbedPane.changeEvent Only one ChangeEvent is needed per TabPane instance since the event's only (read-only) state is the source property.
protected ChangeEvent | DefaultBoundedRangeModel.changeEvent Only one ChangeEvent is needed per model instance since the event's only (read-only) state is the source property.
protected ChangeEvent | AbstractButton.changeEvent Only one ChangeEvent is needed per button instance since the event's only state is the source property.
protected ChangeEvent | DefaultSingleSelectionModel.changeEvent
protected ChangeEvent | DefaultButtonModel.changeEvent Only one ChangeEvent is needed per button model instance since the event's only state is the source property.
protected ChangeEvent | AbstractCellEditor.changeEvent
protected ChangeEvent | MenuSelectionManager.changeEvent Only one ChangeEvent is needed per button model instance since the event's only state is the source property.

Methods in javax.swing with parameters of type ChangeEvent
void | JTable.columnMarginChanged(ChangeEvent e) Invoked when a column is moved due to a margin change.
void | JTable.AccessibleJTable.columnMarginChanged(ChangeEvent e) Track changes of a column moving due to margin changes.
void | JTable.editingCanceled(ChangeEvent e) Invoked when editing is canceled.
void | JTable.AccessibleJTable.editingCanceled(ChangeEvent e) Invoked when editing is canceled.
void | JTable.editingStopped(ChangeEvent e) Invoked when editing is finished.
void | JTable.AccessibleJTable.editingStopped(ChangeEvent e) Track changes to a cell's contents.
void | ProgressMonitor.AccessibleProgressMonitor.stateChanged(ChangeEvent e) Invoked when the target of the listener has changed its state.
void | JSpinner.DefaultEditor.stateChanged(ChangeEvent e) This method is called when the spinner's model's state changes.
void | JSpinner.AccessibleJSpinner.stateChanged(ChangeEvent e) Invoked when the target of the listener has changed its state.
void | JTabbedPane.ModelListener.stateChanged(ChangeEvent e)
void | JTabbedPane.AccessibleJTabbedPane.stateChanged(ChangeEvent e)
void | JScrollPane.AccessibleJScrollPane.stateChanged(ChangeEvent e) Invoked when the target of the listener has changed its state.
void | JMenuItem.AccessibleJMenuItem.stateChanged(ChangeEvent e) Supports the change listener interface and fires property changes.
void | AbstractButton.ButtonChangeListener.stateChanged(ChangeEvent e)

Uses of ChangeEvent in javax.swing.colorchooser

Fields in javax.swing.colorchooser declared as ChangeEvent
protected  ChangeEvent DefaultColorSelectionModel.changeEvent
Only one ChangeEvent is needed per model instance since the event's only (read-only) state is the source property.

Uses of ChangeEvent in javax.swing.event

Methods in javax.swing.event with parameters of type ChangeEvent
void | TableColumnModelListener.columnMarginChanged(ChangeEvent e) Tells listeners that a column was moved due to a margin change.
void | CellEditorListener.editingCanceled(ChangeEvent e) This tells the listeners the editor has canceled editing
void | CellEditorListener.editingStopped(ChangeEvent e) This tells the listeners the editor has ended editing
void | ChangeListener.stateChanged(ChangeEvent e) Invoked when the target of the listener has changed its state.

Uses of ChangeEvent in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic with parameters of type ChangeEvent
void | BasicTreeUI.CellEditorHandler.editingCanceled(ChangeEvent e) Messaged when editing has been canceled in the tree.
void | BasicTreeUI.CellEditorHandler.editingStopped(ChangeEvent e) Messaged when editing has stopped in the tree.
void | BasicTabbedPaneUI.TabSelectionHandler.stateChanged(ChangeEvent e)
void | BasicSliderUI.ChangeHandler.stateChanged(ChangeEvent e)
void | BasicScrollPaneUI.ViewportChangeHandler.stateChanged(ChangeEvent e)
void | BasicScrollPaneUI.HSBChangeListener.stateChanged(ChangeEvent e)
void | BasicScrollPaneUI.VSBChangeListener.stateChanged(ChangeEvent e)
void | BasicScrollBarUI.ModelListener.stateChanged(ChangeEvent e)
void | BasicProgressBarUI.ChangeHandler.stateChanged(ChangeEvent e)
void | BasicMenuUI.ChangeHandler.stateChanged(ChangeEvent e)
void | BasicButtonListener.stateChanged(ChangeEvent e)

Uses of ChangeEvent in javax.swing.table

Fields in javax.swing.table declared as ChangeEvent
protected  ChangeEvent DefaultTableColumnModel.changeEvent
Change event (only one needed)

Methods in javax.swing.table with parameters of type ChangeEvent
 void JTableHeader.columnMarginChanged(ChangeEvent e)
Invoked when a column is moved due to a margin change.

Uses of ChangeEvent in javax.swing.text

Fields in javax.swing.text declared as ChangeEvent
protected ChangeEvent | DefaultCaret.changeEvent The change event for the model.
protected ChangeEvent | StyleContext.NamedStyle.changeEvent Only one ChangeEvent is needed per model instance since the event's only (read-only) state is the source property.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.DocumentEvent.EventType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.DocumentEvent.EventType

Packages that use DocumentEvent.EventType
javax.swing.event | Provides for events fired by Swing components.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of DocumentEvent.EventType in javax.swing.event

Fields in javax.swing.event declared as DocumentEvent.EventType
static DocumentEvent.EventType | DocumentEvent.EventType.CHANGE Change type.
static DocumentEvent.EventType | DocumentEvent.EventType.INSERT Insert type.
static DocumentEvent.EventType | DocumentEvent.EventType.REMOVE Remove type.

Methods in javax.swing.event that return DocumentEvent.EventType
 DocumentEvent.EventType DocumentEvent.getType()
Gets the type of event.

Uses of DocumentEvent.EventType in javax.swing.text

Methods in javax.swing.text that return DocumentEvent.EventType
 DocumentEvent.EventType AbstractDocument.DefaultDocumentEvent.getType()
Returns the type of event.

Constructors in javax.swing.text with parameters of type DocumentEvent.EventType
AbstractDocument.DefaultDocumentEvent(int offs, int len, DocumentEvent.EventType type)
Constructs a change record.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.EventListenerList

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.EventListenerList

Packages that use EventListenerList
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.colorchooser | Contains classes and interfaces used by the JColorChooser component.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of EventListenerList in javax.swing

Fields in javax.swing declared as EventListenerList
protected EventListenerList | DefaultBoundedRangeModel.listenerList The listeners waiting for model changes.
protected EventListenerList | AbstractListModel.listenerList
protected EventListenerList | DefaultSingleSelectionModel.listenerList The collection of registered listeners
protected EventListenerList | JComponent.listenerList A list of event listeners for this component.
protected EventListenerList | AbstractSpinnerModel.listenerList The list of ChangeListeners for this model.
protected EventListenerList | DefaultListSelectionModel.listenerList
protected EventListenerList | DefaultButtonModel.listenerList Stores the listeners on this model.
protected EventListenerList | AbstractCellEditor.listenerList
protected EventListenerList | MenuSelectionManager.listenerList
protected EventListenerList | Timer.listenerList

Uses of EventListenerList in javax.swing.colorchooser

Fields in javax.swing.colorchooser declared as EventListenerList
protected  EventListenerList DefaultColorSelectionModel.listenerList

Uses of EventListenerList in javax.swing.table

Fields in javax.swing.table declared as EventListenerList
protected EventListenerList | DefaultTableColumnModel.listenerList List of TableColumnModelListener
protected EventListenerList | AbstractTableModel.listenerList List of listeners

Uses of EventListenerList in javax.swing.text

Fields in javax.swing.text declared as EventListenerList
protected EventListenerList | AbstractDocument.listenerList The event listener list for the document.
protected EventListenerList | DefaultCaret.listenerList The event listener list.
protected EventListenerList | StyleContext.NamedStyle.listenerList The change listeners for the model.

Uses of EventListenerList in javax.swing.tree

Fields in javax.swing.tree declared as EventListenerList
protected EventListenerList | DefaultTreeModel.listenerList Listeners.
protected EventListenerList | DefaultTreeSelectionModel.listenerList Event listener list.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.HyperlinkEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.HyperlinkEvent

Packages that use HyperlinkEvent
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of HyperlinkEvent in javax.swing

Methods in javax.swing with parameters of type HyperlinkEvent
 void JEditorPane.fireHyperlinkUpdate(HyperlinkEvent e)
Notifies all listeners that have registered interest for notification on this event type.

Uses of HyperlinkEvent in javax.swing.event

Methods in javax.swing.event with parameters of type HyperlinkEvent
 void HyperlinkListener.hyperlinkUpdate(HyperlinkEvent e)
Called when a hypertext link is updated.

Uses of HyperlinkEvent in javax.swing.text.html

Subclasses of HyperlinkEvent in javax.swing.text.html
class | FormSubmitEvent FormSubmitEvent is used to notify interested parties that a form was submited.
class | HTMLFrameHyperlinkEvent HTMLFrameHyperlinkEvent is used to notify interested parties that link was activated in a frame.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.HyperlinkEvent.EventType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.HyperlinkEvent.EventType

Packages that use HyperlinkEvent.EventType
javax.swing.event | Provides for events fired by Swing components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of HyperlinkEvent.EventType in javax.swing.event

Fields in javax.swing.event declared as HyperlinkEvent.EventType
static HyperlinkEvent.EventType | HyperlinkEvent.EventType.ACTIVATED Activated type.
static HyperlinkEvent.EventType | HyperlinkEvent.EventType.ENTERED Entered type.
static HyperlinkEvent.EventType | HyperlinkEvent.EventType.EXITED Exited type.

Methods in javax.swing.event that return HyperlinkEvent.EventType
 HyperlinkEvent.EventType HyperlinkEvent.getEventType()
Gets the type of event.

Constructors in javax.swing.event with parameters of type HyperlinkEvent.EventType
HyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL u)
Creates a new object representing a hypertext link event.
HyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL u, String desc)
Creates a new object representing a hypertext link event.
HyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL u, String desc, Element sourceElement)
Creates a new object representing a hypertext link event.

Uses of HyperlinkEvent.EventType in javax.swing.text.html

Constructors in javax.swing.text.html with parameters of type HyperlinkEvent.EventType
HTMLFrameHyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL targetURL, Element sourceElement, String targetFrame)
Creates a new object representing a hypertext link event.
HTMLFrameHyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL targetURL, String targetFrame)
Creates a new object representing a html frame hypertext link event.
HTMLFrameHyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL targetURL, String desc, Element sourceElement, String targetFrame)
Creates a new object representing a hypertext link event.
HTMLFrameHyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL targetURL, String desc, String targetFrame)
Creates a new object representing a hypertext link event.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.InternalFrameAdapter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.InternalFrameAdapter

No usage of javax.swing.event.InternalFrameAdapter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.InternalFrameEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.InternalFrameEvent

Packages that use InternalFrameEvent
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of InternalFrameEvent in javax.swing.event

Methods in javax.swing.event with parameters of type InternalFrameEvent
void | InternalFrameAdapter.internalFrameActivated(InternalFrameEvent e) Invoked when an internal frame is activated.
void | InternalFrameListener.internalFrameActivated(InternalFrameEvent e) Invoked when an internal frame is activated.
void | InternalFrameAdapter.internalFrameClosed(InternalFrameEvent e) Invoked when an internal frame has been closed.
void | InternalFrameListener.internalFrameClosed(InternalFrameEvent e) Invoked when an internal frame has been closed.
void | InternalFrameAdapter.internalFrameClosing(InternalFrameEvent e) Invoked when an internal frame is in the process of being closed.
void | InternalFrameListener.internalFrameClosing(InternalFrameEvent e) Invoked when an internal frame is in the process of being closed.
void | InternalFrameAdapter.internalFrameDeactivated(InternalFrameEvent e) Invoked when an internal frame is de-activated.
void | InternalFrameListener.internalFrameDeactivated(InternalFrameEvent e) Invoked when an internal frame is de-activated.
void | InternalFrameAdapter.internalFrameDeiconified(InternalFrameEvent e) Invoked when an internal frame is de-iconified.
void | InternalFrameListener.internalFrameDeiconified(InternalFrameEvent e) Invoked when an internal frame is de-iconified.
void | InternalFrameAdapter.internalFrameIconified(InternalFrameEvent e) Invoked when an internal frame is iconified.
void | InternalFrameListener.internalFrameIconified(InternalFrameEvent e) Invoked when an internal frame is iconified.
void | InternalFrameAdapter.internalFrameOpened(InternalFrameEvent e) Invoked when an internal frame has been opened.
void | InternalFrameListener.internalFrameOpened(InternalFrameEvent e) Invoked when a internal frame has been opened.

Uses of InternalFrameEvent in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic with parameters of type InternalFrameEvent
void | BasicInternalFrameUI.BasicInternalFrameListener.internalFrameActivated(InternalFrameEvent e)
void | BasicInternalFrameUI.BasicInternalFrameListener.internalFrameClosed(InternalFrameEvent e)
void | BasicInternalFrameUI.BasicInternalFrameListener.internalFrameClosing(InternalFrameEvent e)
void | BasicInternalFrameUI.BasicInternalFrameListener.internalFrameDeactivated(InternalFrameEvent e)
void | BasicInternalFrameUI.BasicInternalFrameListener.internalFrameDeiconified(InternalFrameEvent e)
void | BasicInternalFrameUI.BasicInternalFrameListener.internalFrameIconified(InternalFrameEvent e)
void | BasicInternalFrameUI.BasicInternalFrameListener.internalFrameOpened(InternalFrameEvent e)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.ListDataEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.ListDataEvent

Packages that use ListDataEvent
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of ListDataEvent in javax.swing

Methods in javax.swing with parameters of type ListDataEvent
void | JComboBox.contentsChanged(ListDataEvent e) This method is public as an implementation side effect.
void | JList.AccessibleJList.contentsChanged(ListDataEvent e) List Data Listener contents changed method.
void | JComboBox.intervalAdded(ListDataEvent e) This method is public as an implementation side effect.
void | JList.AccessibleJList.intervalAdded(ListDataEvent e) List Data Listener interval added method.
void | JComboBox.intervalRemoved(ListDataEvent e) This method is public as an implementation side effect.
void | JList.AccessibleJList.intervalRemoved(ListDataEvent e) List Data Listener interval removed method.

Uses of ListDataEvent in javax.swing.event

Methods in javax.swing.event with parameters of type ListDataEvent
void | ListDataListener.contentsChanged(ListDataEvent e) Sent when the contents of the list has changed in a way that's too complex to characterize with the previous methods.
void | ListDataListener.intervalAdded(ListDataEvent e) Sent after the indices in the index0,index1 interval have been inserted in the data model.
void | ListDataListener.intervalRemoved(ListDataEvent e) Sent after the indices in the index0,index1 interval have been removed from the data model.

Uses of ListDataEvent in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic with parameters of type ListDataEvent
void | BasicListUI.ListDataHandler.contentsChanged(ListDataEvent e)
void | BasicComboBoxUI.ListDataHandler.contentsChanged(ListDataEvent e)
void | BasicComboPopup.ListDataHandler.contentsChanged(ListDataEvent e)
void | BasicListUI.ListDataHandler.intervalAdded(ListDataEvent e)
void | BasicDirectoryModel.intervalAdded(ListDataEvent e) Obsolete - not used.
void | BasicComboBoxUI.ListDataHandler.intervalAdded(ListDataEvent e)
void | BasicComboPopup.ListDataHandler.intervalAdded(ListDataEvent e)
void | BasicListUI.ListDataHandler.intervalRemoved(ListDataEvent e)
void | BasicDirectoryModel.intervalRemoved(ListDataEvent e) Obsolete - not used.
void | BasicComboBoxUI.ListDataHandler.intervalRemoved(ListDataEvent e)
void | BasicComboPopup.ListDataHandler.intervalRemoved(ListDataEvent e)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.ListSelectionEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.ListSelectionEvent

Packages that use ListSelectionEvent
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of ListSelectionEvent in javax.swing

Methods in javax.swing with parameters of type ListSelectionEvent
void | JTable.columnSelectionChanged(ListSelectionEvent e) Invoked when the selection model of the TableColumnModel is changed.
void | JTable.AccessibleJTable.columnSelectionChanged(ListSelectionEvent e) Track that the selection model of the TableColumnModel changed.
void | JTable.valueChanged(ListSelectionEvent e) Invoked when the row selection changes -- repaints to show the new selection.
void | JTable.AccessibleJTable.valueChanged(ListSelectionEvent e) Track changes to table cell selections
void | JList.AccessibleJList.valueChanged(ListSelectionEvent e) List Selection Listener value change method.

Uses of ListSelectionEvent in javax.swing.event

Methods in javax.swing.event with parameters of type ListSelectionEvent
void | TableColumnModelListener.columnSelectionChanged(ListSelectionEvent e) Tells listeners that the selection model of the TableColumnModel changed.
void | ListSelectionListener.valueChanged(ListSelectionEvent e) Called whenever the value of the selection changes.

Uses of ListSelectionEvent in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic with parameters of type ListSelectionEvent
void | BasicListUI.ListSelectionHandler.valueChanged(ListSelectionEvent e)
void | BasicFileChooserUI.SelectionListener.valueChanged(ListSelectionEvent e)
void | BasicComboPopup.ListSelectionHandler.valueChanged(ListSelectionEvent e)

Uses of ListSelectionEvent in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal with parameters of type ListSelectionEvent
 void MetalFileChooserUI.valueChanged(ListSelectionEvent e)

Uses of ListSelectionEvent in javax.swing.table

Methods in javax.swing.table with parameters of type ListSelectionEvent
void | JTableHeader.columnSelectionChanged(ListSelectionEvent e) Invoked when the selection model of the TableColumnModel is changed.
protected void | DefaultTableColumnModel.fireColumnSelectionChanged(ListSelectionEvent e) Notifies all listeners that have registered interest for notification on this event type.
void | DefaultTableColumnModel.valueChanged(ListSelectionEvent e) A ListSelectionListener that forwards ListSelectionEvents when there is a column selection change.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.MenuDragMouseEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.MenuDragMouseEvent

Packages that use MenuDragMouseEvent
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.

Uses of MenuDragMouseEvent in javax.swing

Methods in javax.swing with parameters of type MenuDragMouseEvent
protected void | JMenuItem.fireMenuDragMouseDragged(MenuDragMouseEvent event) Notifies all listeners that have registered interest for notification on this event type.
protected void | JMenuItem.fireMenuDragMouseEntered(MenuDragMouseEvent event) Notifies all listeners that have registered interest for notification on this event type.
protected void | JMenuItem.fireMenuDragMouseExited(MenuDragMouseEvent event) Notifies all listeners that have registered interest for notification on this event type.
protected void | JMenuItem.fireMenuDragMouseReleased(MenuDragMouseEvent event) Notifies all listeners that have registered interest for notification on this event type.
void | JMenuItem.processMenuDragMouseEvent(MenuDragMouseEvent e) Handles mouse drag in a menu.

Uses of MenuDragMouseEvent in javax.swing.event

Methods in javax.swing.event with parameters of type MenuDragMouseEvent
void | MenuDragMouseListener.menuDragMouseDragged(MenuDragMouseEvent e) Invoked when the mouse is being dragged in a menu component's display area.
void | MenuDragMouseListener.menuDragMouseEntered(MenuDragMouseEvent e) Invoked when the dragged mouse has entered a menu component's display area.
void | MenuDragMouseListener.menuDragMouseExited(MenuDragMouseEvent e) Invoked when the dragged mouse has left a menu component's display area.
void | MenuDragMouseListener.menuDragMouseReleased(MenuDragMouseEvent e) Invoked when a dragged mouse is release in a menu component's display area.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.MenuEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.MenuEvent

Packages that use MenuEvent
javax.swing.event Provides for events fired by Swing components.

Uses of MenuEvent in javax.swing.event

Methods in javax.swing.event with parameters of type MenuEvent
void | MenuListener.menuCanceled(MenuEvent e) Invoked when the menu is canceled.
void | MenuListener.menuDeselected(MenuEvent e) Invoked when the menu is deselected.
void | MenuListener.menuSelected(MenuEvent e) Invoked when a menu is selected.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.MenuKeyEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.MenuKeyEvent

Packages that use MenuKeyEvent
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.

Uses of MenuKeyEvent in javax.swing

Methods in javax.swing with parameters of type MenuKeyEvent
protected void | JMenuItem.fireMenuKeyPressed(MenuKeyEvent event) Notifies all listeners that have registered interest for notification on this event type.
protected void | JMenuItem.fireMenuKeyReleased(MenuKeyEvent event) Notifies all listeners that have registered interest for notification on this event type.
protected void | JMenuItem.fireMenuKeyTyped(MenuKeyEvent event) Notifies all listeners that have registered interest for notification on this event type.
void | JMenuItem.processMenuKeyEvent(MenuKeyEvent e) Handles a keystroke in a menu.

Uses of MenuKeyEvent in javax.swing.event

Methods in javax.swing.event with parameters of type MenuKeyEvent
void | MenuKeyListener.menuKeyPressed(MenuKeyEvent e) Invoked when a key has been pressed.
void | MenuKeyListener.menuKeyReleased(MenuKeyEvent e) Invoked when a key has been released.
void | MenuKeyListener.menuKeyTyped(MenuKeyEvent e) Invoked when a key has been typed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.MouseInputAdapter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.MouseInputAdapter

Packages that use MouseInputAdapter
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of MouseInputAdapter in javax.swing.plaf.basic

Subclasses of MouseInputAdapter in javax.swing.plaf.basic
class | BasicDesktopIconUI.MouseInputHandler Listens for mouse movements and acts on them.
protected class | BasicInternalFrameUI.BorderListener Listens for border adjustments.
class | BasicSliderUI.TrackListener Track mouse movements.

Fields in javax.swing.plaf.basic declared as MouseInputAdapter
protected  MouseInputAdapter BasicInternalFrameUI.borderListener

Methods in javax.swing.plaf.basic that return MouseInputAdapter
protected  MouseInputAdapter BasicInternalFrameUI.createBorderListener(JInternalFrame w)

Uses of MouseInputAdapter in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal that return MouseInputAdapter
protected  MouseInputAdapter MetalInternalFrameUI.createBorderListener(JInternalFrame w)
Returns the MouseInputAdapter that will be installed on the TitlePane.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.PopupMenuEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.PopupMenuEvent

Packages that use PopupMenuEvent
javax.swing.event Provides for events fired by Swing components.

Uses of PopupMenuEvent in javax.swing.event

Methods in javax.swing.event with parameters of type PopupMenuEvent
void | PopupMenuListener.popupMenuCanceled(PopupMenuEvent e) This method is called when the popup menu is canceled
void | PopupMenuListener.popupMenuWillBecomeInvisible(PopupMenuEvent e) This method is called before the popup menu becomes invisible Note that a JPopupMenu can become invisible any time
void | PopupMenuListener.popupMenuWillBecomeVisible(PopupMenuEvent e) This method is called before the popup menu becomes visible

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.RowSorterEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.RowSorterEvent

Packages that use RowSorterEvent
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.

Uses of RowSorterEvent in javax.swing

Methods in javax.swing with parameters of type RowSorterEvent
 void JTable.sorterChanged(RowSorterEvent e)
RowSorterListener notification that the RowSorter has changed in some way.

Uses of RowSorterEvent in javax.swing.event

Methods in javax.swing.event with parameters of type RowSorterEvent
 void RowSorterListener.sorterChanged(RowSorterEvent e)
Notification that the RowSorter has changed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.RowSorterEvent.Type

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.RowSorterEvent.Type

Packages that use RowSorterEvent.Type
javax.swing.event Provides for events fired by Swing components.

Uses of RowSorterEvent.Type in javax.swing.event

Methods in javax.swing.event that return RowSorterEvent.Type
RowSorterEvent.Type | RowSorterEvent.getType() Returns the type of event.
static RowSorterEvent.Type | RowSorterEvent.Type.valueOf(String name) Returns the enum constant of this type with the specified name.
static RowSorterEvent.Type[] | RowSorterEvent.Type.values() Returns an array containing the constants of this enum type, in the order they are declared.

Constructors in javax.swing.event with parameters of type RowSorterEvent.Type
RowSorterEvent(RowSorter source, RowSorterEvent.Type type, int[] previousRowIndexToModel)
Creates a RowSorterEvent.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.SwingPropertyChangeSupport

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.SwingPropertyChangeSupport

Packages that use SwingPropertyChangeSupport
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of SwingPropertyChangeSupport in javax.swing

Fields in javax.swing declared as SwingPropertyChangeSupport
protected  SwingPropertyChangeSupport AbstractAction.changeSupport
If any PropertyChangeListeners have been registered, the changeSupport field describes them.

Uses of SwingPropertyChangeSupport in javax.swing.tree

Fields in javax.swing.tree declared as SwingPropertyChangeSupport
protected  SwingPropertyChangeSupport DefaultTreeSelectionModel.changeSupport
Used to messaged registered listeners.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.TableColumnModelEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.TableColumnModelEvent

Packages that use TableColumnModelEvent
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of TableColumnModelEvent in javax.swing

Methods in javax.swing with parameters of type TableColumnModelEvent
void | JTable.columnAdded(TableColumnModelEvent e) Invoked when a column is added to the table column model.
void | JTable.AccessibleJTable.columnAdded(TableColumnModelEvent e) Track changes to the table contents (column insertions)
void | JTable.columnMoved(TableColumnModelEvent e) Invoked when a column is repositioned.
void | JTable.AccessibleJTable.columnMoved(TableColumnModelEvent e) Track changes of a column repositioning.
void | JTable.columnRemoved(TableColumnModelEvent e) Invoked when a column is removed from the table column model.
void | JTable.AccessibleJTable.columnRemoved(TableColumnModelEvent e) Track changes to the table contents (column deletions)

Uses of TableColumnModelEvent in javax.swing.event

Methods in javax.swing.event with parameters of type TableColumnModelEvent
void | TableColumnModelListener.columnAdded(TableColumnModelEvent e) Tells listeners that a column was added to the model.
void | TableColumnModelListener.columnMoved(TableColumnModelEvent e) Tells listeners that a column was repositioned.
void | TableColumnModelListener.columnRemoved(TableColumnModelEvent e) Tells listeners that a column was removed from the model.

Uses of TableColumnModelEvent in javax.swing.table

Methods in javax.swing.table with parameters of type TableColumnModelEvent
void | JTableHeader.columnAdded(TableColumnModelEvent e) Invoked when a column is added to the table column model.
void | JTableHeader.columnMoved(TableColumnModelEvent e) Invoked when a column is repositioned.
void | JTableHeader.columnRemoved(TableColumnModelEvent e) Invoked when a column is removed from the table column model.
protected void | DefaultTableColumnModel.fireColumnAdded(TableColumnModelEvent e) Notifies all listeners that have registered interest for notification on this event type.
protected void | DefaultTableColumnModel.fireColumnMoved(TableColumnModelEvent e) Notifies all listeners that have registered interest for notification on this event type.
protected void | DefaultTableColumnModel.fireColumnRemoved(TableColumnModelEvent e) Notifies all listeners that have registered interest for notification on this event type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.TableModelEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.TableModelEvent

Packages that use TableModelEvent
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of TableModelEvent in javax.swing

Methods in javax.swing with parameters of type TableModelEvent
void | JTable.tableChanged(TableModelEvent e) Invoked when this table's TableModel generates a TableModelEvent.
void | JTable.AccessibleJTable.tableChanged(TableModelEvent e) Track changes to the table contents
void | JTable.AccessibleJTable.tableRowsDeleted(TableModelEvent e) Track changes to the table contents (row deletions)
void | JTable.AccessibleJTable.tableRowsInserted(TableModelEvent e) Track changes to the table contents (row insertions)

Uses of TableModelEvent in javax.swing.event

Methods in javax.swing.event with parameters of type TableModelEvent
 void TableModelListener.tableChanged(TableModelEvent e)
This fine grain notification tells listeners the exact range of cells, rows, or columns that changed.

Uses of TableModelEvent in javax.swing.table

Methods in javax.swing.table with parameters of type TableModelEvent
void | AbstractTableModel.fireTableChanged(TableModelEvent e) Forwards the given notification event to all TableModelListeners that registered themselves as listeners for this table model.
void | DefaultTableModel.newDataAvailable(TableModelEvent event) Equivalent to fireTableChanged.
void | DefaultTableModel.newRowsAdded(TableModelEvent e) Ensures that the new rows have the correct number of columns.
void | DefaultTableModel.rowsRemoved(TableModelEvent event) Equivalent to fireTableChanged.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.TreeExpansionEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.TreeExpansionEvent

Packages that use TreeExpansionEvent
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of TreeExpansionEvent in javax.swing

Methods in javax.swing with parameters of type TreeExpansionEvent
void | JTree.AccessibleJTree.treeCollapsed(TreeExpansionEvent e) Tree Collapsed notification.
void | JTree.AccessibleJTree.treeExpanded(TreeExpansionEvent e) Tree Model Expansion notification.

Uses of TreeExpansionEvent in javax.swing.event

Methods in javax.swing.event with parameters of type TreeExpansionEvent
void | TreeExpansionListener.treeCollapsed(TreeExpansionEvent event) Called whenever an item in the tree has been collapsed.
void | TreeExpansionListener.treeExpanded(TreeExpansionEvent event) Called whenever an item in the tree has been expanded.
void | TreeWillExpandListener.treeWillCollapse(TreeExpansionEvent event) Invoked whenever a node in the tree is about to be collapsed.
void | TreeWillExpandListener.treeWillExpand(TreeExpansionEvent event) Invoked whenever a node in the tree is about to be expanded.

Uses of TreeExpansionEvent in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic with parameters of type TreeExpansionEvent
void | BasicTreeUI.TreeExpansionHandler.treeCollapsed(TreeExpansionEvent event) Called whenever an item in the tree has been collapsed.
void | BasicTreeUI.TreeExpansionHandler.treeExpanded(TreeExpansionEvent event) Called whenever an item in the tree has been expanded.

Uses of TreeExpansionEvent in javax.swing.tree

Fields in javax.swing.tree declared as TreeExpansionEvent
protected  TreeExpansionEvent ExpandVetoException.event
The event that the exception was created for.

Constructors in javax.swing.tree with parameters of type TreeExpansionEvent
ExpandVetoException(TreeExpansionEvent event)
Constructs an ExpandVetoException object with no message.
ExpandVetoException(TreeExpansionEvent event, String message)
Constructs an ExpandVetoException object with the specified message.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.TreeModelEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.TreeModelEvent

Packages that use TreeModelEvent
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of TreeModelEvent in javax.swing

Methods in javax.swing with parameters of type TreeModelEvent
void | JTree.TreeModelHandler.treeNodesChanged(TreeModelEvent e)
void | JTree.AccessibleJTree.treeNodesChanged(TreeModelEvent e) Tree Model Node change notification.
void | JTree.TreeModelHandler.treeNodesInserted(TreeModelEvent e)
void | JTree.AccessibleJTree.treeNodesInserted(TreeModelEvent e) Tree Model Node change notification.
void | JTree.TreeModelHandler.treeNodesRemoved(TreeModelEvent e)
void | JTree.AccessibleJTree.treeNodesRemoved(TreeModelEvent e) Tree Model Node change notification.
void | JTree.TreeModelHandler.treeStructureChanged(TreeModelEvent e)
void | JTree.AccessibleJTree.treeStructureChanged(TreeModelEvent e) Tree Model structure change change notification.

Uses of TreeModelEvent in javax.swing.event

Methods in javax.swing.event with parameters of type TreeModelEvent
void | TreeModelListener.treeNodesChanged(TreeModelEvent e) Invoked after a node (or a set of siblings) has changed in some way.
void | TreeModelListener.treeNodesInserted(TreeModelEvent e) Invoked after nodes have been inserted into the tree.
void | TreeModelListener.treeNodesRemoved(TreeModelEvent e) Invoked after nodes have been removed from the tree.
void | TreeModelListener.treeStructureChanged(TreeModelEvent e) Invoked after the tree has drastically changed structure from a given node down.

Uses of TreeModelEvent in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic with parameters of type TreeModelEvent
void | BasicTreeUI.TreeModelHandler.treeNodesChanged(TreeModelEvent e)
void | BasicTreeUI.TreeModelHandler.treeNodesInserted(TreeModelEvent e)
void | BasicTreeUI.TreeModelHandler.treeNodesRemoved(TreeModelEvent e)
void | BasicTreeUI.TreeModelHandler.treeStructureChanged(TreeModelEvent e)

Uses of TreeModelEvent in javax.swing.tree

Methods in javax.swing.tree with parameters of type TreeModelEvent
void | VariableHeightLayoutCache.treeNodesChanged(TreeModelEvent e) Invoked after a node (or a set of siblings) has changed in some way.
void | FixedHeightLayoutCache.treeNodesChanged(TreeModelEvent e) Invoked after a node (or a set of siblings) has changed in some way.
abstract void | AbstractLayoutCache.treeNodesChanged(TreeModelEvent e) Invoked after a node (or a set of siblings) has changed in some way.
void | VariableHeightLayoutCache.treeNodesInserted(TreeModelEvent e) Invoked after nodes have been inserted into the tree.
void | FixedHeightLayoutCache.treeNodesInserted(TreeModelEvent e) Invoked after nodes have been inserted into the tree.
abstract void | AbstractLayoutCache.treeNodesInserted(TreeModelEvent e) Invoked after nodes have been inserted into the tree.
void | VariableHeightLayoutCache.treeNodesRemoved(TreeModelEvent e) Invoked after nodes have been removed from the tree.
void | FixedHeightLayoutCache.treeNodesRemoved(TreeModelEvent e) Invoked after nodes have been removed from the tree.
abstract void | AbstractLayoutCache.treeNodesRemoved(TreeModelEvent e) Invoked after nodes have been removed from the tree.
void | VariableHeightLayoutCache.treeStructureChanged(TreeModelEvent e) Invoked after the tree has drastically changed structure from a given node down.
void | FixedHeightLayoutCache.treeStructureChanged(TreeModelEvent e) Invoked after the tree has drastically changed structure from a given node down.
abstract void | AbstractLayoutCache.treeStructureChanged(TreeModelEvent e) Invoked after the tree has drastically changed structure from a given node down.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.TreeSelectionEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.TreeSelectionEvent

Packages that use TreeSelectionEvent
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of TreeSelectionEvent in javax.swing

Methods in javax.swing with parameters of type TreeSelectionEvent
protected void | JTree.fireValueChanged(TreeSelectionEvent e) Notifies all listeners that have registered interest for notification on this event type.
void | JTree.TreeSelectionRedirector.valueChanged(TreeSelectionEvent e) Invoked by the TreeSelectionModel when the selection changes.
void | JTree.AccessibleJTree.valueChanged(TreeSelectionEvent e) Tree Selection Listener value change method.

Uses of TreeSelectionEvent in javax.swing.event

Methods in javax.swing.event with parameters of type TreeSelectionEvent
 void TreeSelectionListener.valueChanged(TreeSelectionEvent e)
Called whenever the value of the selection changes.

Uses of TreeSelectionEvent in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic with parameters of type TreeSelectionEvent
 void BasicTreeUI.TreeSelectionHandler.valueChanged(TreeSelectionEvent event)
Messaged when the selection changes in the tree we're displaying for.

Uses of TreeSelectionEvent in javax.swing.tree

Methods in javax.swing.tree with parameters of type TreeSelectionEvent
protected void | DefaultTreeSelectionModel.fireValueChanged(TreeSelectionEvent e) Notifies all listeners that are registered for tree selection events on this object.
void | DefaultTreeCellEditor.valueChanged(TreeSelectionEvent e) Resets lastPath.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.event.UndoableEditEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.event.UndoableEditEvent

Packages that use UndoableEditEvent
javax.swing.event | Provides for events fired by Swing components.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.
javax.swing.undo | Allows developers to provide support for undo/redo in applications such as text editors.

Uses of UndoableEditEvent in javax.swing.event

Methods in javax.swing.event with parameters of type UndoableEditEvent
 void UndoableEditListener.undoableEditHappened(UndoableEditEvent e)
An undoable edit happened

Uses of UndoableEditEvent in javax.swing.text

Methods in javax.swing.text with parameters of type UndoableEditEvent
protected  void AbstractDocument.fireUndoableEditUpdate(UndoableEditEvent e)
Notifies all listeners that have registered interest for notification on this event type.

Uses of UndoableEditEvent in javax.swing.text.html

Methods in javax.swing.text.html with parameters of type UndoableEditEvent
protected  void HTMLDocument.fireUndoableEditUpdate(UndoableEditEvent e)
Notifies all listeners that have registered interest for notification on this event type.

Uses of UndoableEditEvent in javax.swing.undo

Methods in javax.swing.undo with parameters of type UndoableEditEvent
 void UndoManager.undoableEditHappened(UndoableEditEvent e)
An UndoableEditListener method.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.AncestorListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.AncestorListener

Packages that use AncestorListener
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of AncestorListener in javax.swing

Methods in javax.swing that return AncestorListener
 AncestorListener[] JComponent.getAncestorListeners()
Returns an array of all the ancestor listeners registered on this component.

Methods in javax.swing with parameters of type AncestorListener
void | JComponent.addAncestorListener(AncestorListener listener) Registers listener so that it will receive AncestorEvents when it or any of its ancestors move or are made visible or invisible.
void | JComponent.removeAncestorListener(AncestorListener listener) Unregisters listener so that it will no longer receive AncestorEvents.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.CaretListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.CaretListener

Packages that use CaretListener
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of CaretListener in javax.swing

Classes in javax.swing that implement CaretListener
protected class | JEditorPane.AccessibleJEditorPane This class implements accessibility support for the JEditorPane class.
protected class | JEditorPane.AccessibleJEditorPaneHTML This class provides support for AccessibleHypertext, and is used in instances where the EditorKit installed in this JEditorPane is an instance of HTMLEditorKit.
protected class | JEditorPane.JEditorPaneAccessibleHypertextSupport What's returned by AccessibleJEditorPaneHTML.getAccessibleText.
protected class | JPasswordField.AccessibleJPasswordField This class implements accessibility support for the JPasswordField class.
protected class | JTextArea.AccessibleJTextArea This class implements accessibility support for the JTextArea class.
protected class | JTextField.AccessibleJTextField This class implements accessibility support for the JTextField class.

Uses of CaretListener in javax.swing.text

Classes in javax.swing.text that implement CaretListener
 class JTextComponent.AccessibleJTextComponent
This class implements accessibility support for the JTextComponent class.

Methods in javax.swing.text that return CaretListener
 CaretListener[] JTextComponent.getCaretListeners()
Returns an array of all the caret listeners registered on this text component.

Methods in javax.swing.text with parameters of type CaretListener
void | JTextComponent.addCaretListener(CaretListener listener) Adds a caret listener for notification of any changes to the caret.
void | JTextComponent.removeCaretListener(CaretListener listener) Removes a caret listener.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.CellEditorListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.CellEditorListener

Packages that use CellEditorListener
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of CellEditorListener in javax.swing

Classes in javax.swing that implement CellEditorListener
class | JTable The JTable is used to display and edit regular two-dimensional tables of cells.
protected class | JTable.AccessibleJTable This class implements accessibility support for the JTable class.

Methods in javax.swing that return CellEditorListener
 CellEditorListener[] AbstractCellEditor.getCellEditorListeners()
Returns an array of all the CellEditorListeners added to this AbstractCellEditor with addCellEditorListener().

Methods in javax.swing with parameters of type CellEditorListener
void | AbstractCellEditor.addCellEditorListener(CellEditorListener l) Adds a CellEditorListener to the listener list.
void | CellEditor.addCellEditorListener(CellEditorListener l) Adds a listener to the list that's notified when the editor stops, or cancels editing.
void | AbstractCellEditor.removeCellEditorListener(CellEditorListener l) Removes a CellEditorListener from the listener list.
void | CellEditor.removeCellEditorListener(CellEditorListener l) Removes a listener from the list that's notified

Uses of CellEditorListener in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement CellEditorListener
 class BasicTreeUI.CellEditorHandler
Listener responsible for getting cell editing events and updating the tree accordingly.

Methods in javax.swing.plaf.basic that return CellEditorListener
protected  CellEditorListener BasicTreeUI.createCellEditorListener()
Creates a listener to handle events from the current editor.

Uses of CellEditorListener in javax.swing.tree

Methods in javax.swing.tree that return CellEditorListener
 CellEditorListener[] DefaultTreeCellEditor.getCellEditorListeners()
Returns an array of all the CellEditorListeners added to this DefaultTreeCellEditor with addCellEditorListener().

Methods in javax.swing.tree with parameters of type CellEditorListener
void | DefaultTreeCellEditor.addCellEditorListener(CellEditorListener l) Adds the CellEditorListener.
void | DefaultTreeCellEditor.removeCellEditorListener(CellEditorListener l) Removes the previously added CellEditorListener.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.ChangeListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.ChangeListener

Packages that use ChangeListener
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.colorchooser | Contains classes and interfaces used by the JColorChooser component.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of ChangeListener in javax.swing

Classes in javax.swing that implement ChangeListener
protected class | AbstractButton.ButtonChangeListener Extends ChangeListener to be serializable.
protected class | JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem This class implements accessibility support for the JCheckBoxMenuItem class.
protected class | JMenu.AccessibleJMenu This class implements accessibility support for the JMenu class.
protected class | JMenuItem.AccessibleJMenuItem This class implements accessibility support for the JMenuItem class.
protected class | JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem This class implements accessibility support for the JRadioButtonMenuItem class.
protected class | JScrollPane.AccessibleJScrollPane This class implements accessibility support for the JScrollPane class.
protected class | JSpinner.AccessibleJSpinner AccessibleJSpinner implements accessibility support for the JSpinner class.
static class | JSpinner.DateEditor An editor for a JSpinner whose model is a SpinnerDateModel.
static class | JSpinner.DefaultEditor A simple base class for more specialized editors that displays a read-only view of the model's current value with a JFormattedTextField.
static class | JSpinner.ListEditor An editor for a JSpinner whose model is a SpinnerListModel.
static class | JSpinner.NumberEditor An editor for a JSpinner whose model is a SpinnerNumberModel.
protected class | JTabbedPane.AccessibleJTabbedPane This class implements accessibility support for the JTabbedPane class.
protected class | JTabbedPane.ModelListener We pass ModelChanged events along to the listeners with the tabbedpane (instead of the model itself) as the event source.
protected class | ProgressMonitor.AccessibleProgressMonitor AccessibleProgressMonitor implements accessibility support for the ProgressMonitor class.

Fields in javax.swing declared as ChangeListener
protected ChangeListener | JProgressBar.changeListener Listens for change events sent by the progress bar's model, redispatching them to change-event listeners registered upon this progress bar.
protected ChangeListener | JSlider.changeListener The changeListener (no suffix) is the listener we add to the slider's model.
protected ChangeListener | JTabbedPane.changeListener The changeListener is the listener we add to the model.
protected ChangeListener | AbstractButton.changeListener The button model's changeListener.

Methods in javax.swing that return ChangeListener
protected  ChangeListener JProgressBar.createChangeListener()
Subclasses that want to handle change events from the model differently can override this to return an instance of a custom ChangeListener implementation.
protected  ChangeListener JSlider.createChangeListener()
Subclasses that want to handle ChangeEvents from the model differently can override this to return an instance of a custom ChangeListener implementation.
protected  ChangeListener JTabbedPane.createChangeListener()
Subclasses that want to handle ChangeEvents differently can override this to return a subclass of ModelListener or another ChangeListener implementation.
protected  ChangeListener AbstractButton.createChangeListener()
Subclasses that want to handle ChangeEvents differently can override this to return another ChangeListener implementation.
 ChangeListener[] JProgressBar.getChangeListeners()
Returns an array of all the ChangeListeners added to this progress bar with addChangeListener.
 ChangeListener[] JSlider.getChangeListeners()
Returns an array of all the ChangeListeners added to this JSlider with addChangeListener().
 ChangeListener[] JSpinner.getChangeListeners()
Returns an array of all the ChangeListeners added to this JSpinner with addChangeListener().
 ChangeListener[] JTabbedPane.getChangeListeners()
Returns an array of all the ChangeListeners added to this JTabbedPane with addChangeListener.
 ChangeListener[] JViewport.getChangeListeners()
Returns an array of all the ChangeListeners added to this JViewport with addChangeListener().
 ChangeListener[] DefaultBoundedRangeModel.getChangeListeners()
Returns an array of all the change listeners registered on this DefaultBoundedRangeModel.
 ChangeListener[] AbstractButton.getChangeListeners()
Returns an array of all the ChangeListeners added to this AbstractButton with addChangeListener().
 ChangeListener[] DefaultSingleSelectionModel.getChangeListeners()
Returns an array of all the change listeners registered on this DefaultSingleSelectionModel.
 ChangeListener[] AbstractSpinnerModel.getChangeListeners()
Returns an array of all the ChangeListeners added to this AbstractSpinnerModel with addChangeListener().
 ChangeListener[] DefaultButtonModel.getChangeListeners()
Returns an array of all the change listeners registered on this DefaultButtonModel.
 ChangeListener[] MenuSelectionManager.getChangeListeners()
Returns an array of all the ChangeListeners added to this MenuSelectionManager with addChangeListener().

Methods in javax.swing with parameters of type ChangeListener
void | JProgressBar.addChangeListener(ChangeListener l) Adds the specified ChangeListener to the progress bar.
void | JSlider.addChangeListener(ChangeListener l) Adds a ChangeListener to the slider.
void | JSpinner.addChangeListener(ChangeListener listener) Adds a listener to the list that is notified each time a change to the model occurs.
void | JTabbedPane.addChangeListener(ChangeListener l) Adds a ChangeListener to this tabbedpane.
void | JViewport.addChangeListener(ChangeListener l) Adds a ChangeListener to the list that is notified each time the view's size, position, or the viewport's extent size has changed.
void | DefaultBoundedRangeModel.addChangeListener(ChangeListener l) Adds a ChangeListener.
void | AbstractButton.addChangeListener(ChangeListener l) Adds a ChangeListener to the button.
void | DefaultSingleSelectionModel.addChangeListener(ChangeListener l) Adds a ChangeListener to the button.
void | SpinnerModel.addChangeListener(ChangeListener l) Adds a ChangeListener to the model's listener list.
void | AbstractSpinnerModel.addChangeListener(ChangeListener l) Adds a ChangeListener to the model's listener list.
void | DefaultButtonModel.addChangeListener(ChangeListener l) Adds a ChangeListener to the model.
void | BoundedRangeModel.addChangeListener(ChangeListener x) Adds a ChangeListener to the model's listener list.
void | ButtonModel.addChangeListener(ChangeListener l) Adds a ChangeListener to the model.
void | MenuSelectionManager.addChangeListener(ChangeListener l) Adds a ChangeListener to the button.
void | SingleSelectionModel.addChangeListener(ChangeListener listener) Adds listener as a listener to changes in the model.
void | JProgressBar.removeChangeListener(ChangeListener l) Removes a ChangeListener from the progress bar.
void | JSlider.removeChangeListener(ChangeListener l) Removes a ChangeListener from the slider.
void | JSpinner.removeChangeListener(ChangeListener listener) Removes a ChangeListener from this spinner.
void | JTabbedPane.removeChangeListener(ChangeListener l) Removes a ChangeListener from this tabbedpane.
void | JViewport.removeChangeListener(ChangeListener l) Removes a ChangeListener from the list that's notified each time the views size, position, or the viewports extent size has changed.
void | DefaultBoundedRangeModel.removeChangeListener(ChangeListener l) Removes a ChangeListener.
void | AbstractButton.removeChangeListener(ChangeListener l) Removes a ChangeListener from the button.
void | DefaultSingleSelectionModel.removeChangeListener(ChangeListener l) Removes a ChangeListener from the button.
void | SpinnerModel.removeChangeListener(ChangeListener l) Removes a ChangeListener from the model's listener list.
void | AbstractSpinnerModel.removeChangeListener(ChangeListener l) Removes a ChangeListener from the model's listener list.
void | DefaultButtonModel.removeChangeListener(ChangeListener l) Removes a ChangeListener from the model.
void | BoundedRangeModel.removeChangeListener(ChangeListener x) Removes a ChangeListener from the model's listener list.
void | ButtonModel.removeChangeListener(ChangeListener l) Removes a ChangeListener from the model.
void | MenuSelectionManager.removeChangeListener(ChangeListener l) Removes a ChangeListener from the button.
void | SingleSelectionModel.removeChangeListener(ChangeListener listener) Removes listener as a listener to changes in the model.

Uses of ChangeListener in javax.swing.colorchooser

Methods in javax.swing.colorchooser that return ChangeListener
 ChangeListener[] DefaultColorSelectionModel.getChangeListeners()
Returns an array of all the ChangeListeners added to this DefaultColorSelectionModel with addChangeListener.

Methods in javax.swing.colorchooser with parameters of type ChangeListener
void | DefaultColorSelectionModel.addChangeListener(ChangeListener l) Adds a ChangeListener to the model.
void | ColorSelectionModel.addChangeListener(ChangeListener listener) Adds listener as a listener to changes in the model.
void | DefaultColorSelectionModel.removeChangeListener(ChangeListener l) Removes a ChangeListener from the model.
void | ColorSelectionModel.removeChangeListener(ChangeListener listener) Removes listener as a listener to changes in the model.

Uses of ChangeListener in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement ChangeListener
class | BasicButtonListener Button Listener
class | BasicMenuUI.ChangeHandler As of Java 2 platform 1.4, this previously undocumented class is now obsolete.
class | BasicProgressBarUI.ChangeHandler This inner class is marked "public" due to a compiler bug.
protected class | BasicScrollBarUI.ModelListener A listener to listen for model changes.
class | BasicScrollPaneUI.HSBChangeListener Horizontal scrollbar listener.
class | BasicScrollPaneUI.ViewportChangeHandler Listener for viewport events.
class | BasicScrollPaneUI.VSBChangeListener Vertical scrollbar listener.
class | BasicSliderUI.ChangeHandler Data model listener.
class | BasicTabbedPaneUI.TabSelectionHandler This class should be treated as a "protected" inner class.

Fields in javax.swing.plaf.basic declared as ChangeListener
protected ChangeListener | BasicSliderUI.changeListener
protected ChangeListener | BasicProgressBarUI.changeListener
protected ChangeListener | BasicMenuUI.changeListener
protected ChangeListener | BasicMenuBarUI.changeListener
protected ChangeListener | BasicScrollPaneUI.hsbChangeListener
protected ChangeListener | BasicColorChooserUI.previewListener
protected ChangeListener | BasicTabbedPaneUI.tabChangeListener
protected ChangeListener | BasicScrollPaneUI.viewportChangeListener
protected ChangeListener | BasicScrollPaneUI.vsbChangeListener

Methods in javax.swing.plaf.basic that return ChangeListener
protected ChangeListener | BasicTabbedPaneUI.createChangeListener()
protected ChangeListener | BasicMenuBarUI.createChangeListener()
protected ChangeListener | BasicMenuUI.createChangeListener(JComponent c)
protected ChangeListener | BasicSliderUI.createChangeListener(JSlider slider)
protected ChangeListener | BasicScrollPaneUI.createHSBChangeListener()
protected ChangeListener | BasicScrollPaneUI.createViewportChangeListener()
protected ChangeListener | BasicScrollPaneUI.createVSBChangeListener()

Uses of ChangeListener in javax.swing.text

Methods in javax.swing.text that return ChangeListener
 ChangeListener[] DefaultCaret.getChangeListeners()
Returns an array of all the change listeners registered on this caret.
 ChangeListener[] StyleContext.getChangeListeners()
Returns an array of all the ChangeListeners added to this StyleContext with addChangeListener().
 ChangeListener[] StyleContext.NamedStyle.getChangeListeners()
Returns an array of all the ChangeListeners added to this NamedStyle with addChangeListener().

Methods in javax.swing.text with parameters of type ChangeListener
void | DefaultCaret.addChangeListener(ChangeListener l) Adds a listener to track whenever the caret position has been changed.
void | StyleContext.addChangeListener(ChangeListener l) Adds a listener to track when styles are added or removed.
void | StyleContext.NamedStyle.addChangeListener(ChangeListener l) Adds a change listener.
void | Style.addChangeListener(ChangeListener l) Adds a listener to track whenever an attribute has been changed.
void | Caret.addChangeListener(ChangeListener l) Adds a listener to track whenever the caret position has been changed.
void | DefaultCaret.removeChangeListener(ChangeListener l) Removes a listener that was tracking caret position changes.
void | StyleContext.removeChangeListener(ChangeListener l) Removes a listener that was tracking styles being added or removed.
void | StyleContext.NamedStyle.removeChangeListener(ChangeListener l) Removes a change listener.
void | Style.removeChangeListener(ChangeListener l) Removes a listener that was tracking attribute changes.
void | Caret.removeChangeListener(ChangeListener l) Removes a listener that was tracking caret position changes.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.DocumentEvent

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.DocumentEvent

Packages that use DocumentEvent
javax.swing.event | Provides for events fired by Swing components.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of DocumentEvent in javax.swing.event

Methods in javax.swing.event with parameters of type DocumentEvent
void | DocumentListener.changedUpdate(DocumentEvent e) Gives notification that an attribute or set of attributes changed.
void | DocumentListener.insertUpdate(DocumentEvent e) Gives notification that there was an insert into the document.
void | DocumentListener.removeUpdate(DocumentEvent e) Gives notification that a portion of the document has been removed.

Uses of DocumentEvent in javax.swing.text

Classes in javax.swing.text that implement DocumentEvent
 class AbstractDocument.DefaultDocumentEvent
Stores document changes as the document is being modified.

Methods in javax.swing.text with parameters of type DocumentEvent
void | JTextComponent.AccessibleJTextComponent.changedUpdate(DocumentEvent e) Handles document remove (fire appropriate property change event, which is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY).
void | WrappedPlainView.changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
void | PlainView.changedUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
void | FlowView.changedUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
void | ParagraphView.changedUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
void | LabelView.changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
void | GlyphView.changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
void | View.changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
void | FlowView.FlowStrategy.changedUpdate(FlowView fv, DocumentEvent e, Rectangle alloc) Gives notification from the document that attributes were changed in a location that this view is responsible for.
protected void | AbstractDocument.fireChangedUpdate(DocumentEvent e) Notifies all listeners that have registered interest for notification on this event type.
protected void | AbstractDocument.fireInsertUpdate(DocumentEvent e) Notifies all listeners that have registered interest for notification on this event type.
protected void | AbstractDocument.fireRemoveUpdate(DocumentEvent e) Notifies all listeners that have registered interest for notification on this event type.
protected void | TableView.forwardUpdate(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a, ViewFactory f)
protected void | BoxView.forwardUpdate(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a, ViewFactory f) Forwards the given DocumentEvent to the child views that need to be notified of the change to the model.
protected void | View.forwardUpdate(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a, ViewFactory f) Forwards the given DocumentEvent to the child views that need to be notified of the change to the model.
protected void | View.forwardUpdateToView(View v, DocumentEvent e, Shape a, ViewFactory f) Forwards the DocumentEvent to the give child view.
void | JTextComponent.AccessibleJTextComponent.insertUpdate(DocumentEvent e) Handles document insert (fire appropriate property change event which is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY).
void | FieldView.insertUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
void | ZoneView.insertUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
void | WrappedPlainView.insertUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
void | PlainView.insertUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
void | FlowView.insertUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
void | GlyphView.insertUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
void | View.insertUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
void | FlowView.FlowStrategy.insertUpdate(FlowView fv, DocumentEvent e, Rectangle alloc) Gives notification that something was inserted into the document in a location that the given flow view is responsible for.
void | JTextComponent.AccessibleJTextComponent.removeUpdate(DocumentEvent e) Handles document remove (fire appropriate property change event, which is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY).
void | FieldView.removeUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | ZoneView.removeUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | WrappedPlainView.removeUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | PlainView.removeUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | FlowView.removeUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | GlyphView.removeUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | View.removeUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | FlowView.FlowStrategy.removeUpdate(FlowView fv, DocumentEvent e, Rectangle alloc) Gives notification that something was removed from the document in a location that the given flow view is responsible for.
protected boolean | ZoneView.updateChildren(DocumentEvent.ElementChange ec, DocumentEvent e, ViewFactory f) The superclass behavior will try to update the child views which is not desired in this case, since the children are zones and not directly effected by the changes to the associated element.
protected boolean | View.updateChildren(DocumentEvent.ElementChange ec, DocumentEvent e, ViewFactory f) Updates the child views in response to receiving notification that the model changed, and there is change record for the element this view is responsible for.
protected void | PlainView.updateDamage(DocumentEvent changes, Shape a, ViewFactory f) Repaint the region of change covered by the given document event.
protected void | AsyncBoxView.updateLayout(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a) Update the layout in response to receiving notification of change from the model.
protected void | View.updateLayout(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a) Updates the layout in response to receiving notification of change from the model.

Uses of DocumentEvent in javax.swing.text.html

Methods in javax.swing.text.html with parameters of type DocumentEvent
void | BlockView.changedUpdate(DocumentEvent changes, Shape a, ViewFactory f)
void | ImageView.changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Invoked when the Elements attributes have changed.
void | InlineView.changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
protected void | HTMLDocument.fireChangedUpdate(DocumentEvent e) Notifies all listeners that have registered interest for notification on this event type.
void | InlineView.insertUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
void | InlineView.removeUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.DocumentEvent.ElementChange

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.DocumentEvent.ElementChange

Packages that use DocumentEvent.ElementChange
javax.swing.event | Provides for events fired by Swing components.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of DocumentEvent.ElementChange in javax.swing.event

Methods in javax.swing.event that return DocumentEvent.ElementChange
 DocumentEvent.ElementChange DocumentEvent.getChange(Element elem)
Gets the change information for the given element.

Uses of DocumentEvent.ElementChange in javax.swing.text

Classes in javax.swing.text that implement DocumentEvent.ElementChange
static class AbstractDocument.ElementEdit
An implementation of ElementChange that can be added to the document event.

Methods in javax.swing.text that return DocumentEvent.ElementChange
 DocumentEvent.ElementChange AbstractDocument.DefaultDocumentEvent.getChange(Element elem)
Gets the changes for an element.

Methods in javax.swing.text with parameters of type DocumentEvent.ElementChange
protected void | TableView.forwardUpdate(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a, ViewFactory f)
protected void | BoxView.forwardUpdate(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a, ViewFactory f) Forwards the given DocumentEvent to the child views that need to be notified of the change to the model.
protected void | View.forwardUpdate(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a, ViewFactory f) Forwards the given DocumentEvent to the child views that need to be notified of the change to the model.
protected boolean | ZoneView.updateChildren(DocumentEvent.ElementChange ec, DocumentEvent e, ViewFactory f) The superclass behavior will try to update the child views which is not desired in this case, since the children are zones and not directly effected by the changes to the associated element.
protected boolean | View.updateChildren(DocumentEvent.ElementChange ec, DocumentEvent e, ViewFactory f) Updates the child views in response to receiving notification that the model changed, and there is change record for the element this view is responsible for.
protected void | AsyncBoxView.updateLayout(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a) Update the layout in response to receiving notification of change from the model.
protected void | View.updateLayout(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a) Updates the layout in response to receiving notification of change from the model.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.DocumentListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.DocumentListener

Packages that use DocumentListener
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of DocumentListener in javax.swing

Classes in javax.swing that implement DocumentListener
protected class | JEditorPane.AccessibleJEditorPane This class implements accessibility support for the JEditorPane class.
protected class | JEditorPane.AccessibleJEditorPaneHTML This class provides support for AccessibleHypertext, and is used in instances where the EditorKit installed in this JEditorPane is an instance of HTMLEditorKit.
protected class | JEditorPane.JEditorPaneAccessibleHypertextSupport What's returned by AccessibleJEditorPaneHTML.getAccessibleText.
protected class | JPasswordField.AccessibleJPasswordField This class implements accessibility support for the JPasswordField class.
protected class | JTextArea.AccessibleJTextArea This class implements accessibility support for the JTextArea class.
protected class | JTextField.AccessibleJTextField This class implements accessibility support for the JTextField class.

Uses of DocumentListener in javax.swing.text

Classes in javax.swing.text that implement DocumentListener
 class JTextComponent.AccessibleJTextComponent
This class implements accessibility support for the JTextComponent class.

Methods in javax.swing.text that return DocumentListener
 DocumentListener[] AbstractDocument.getDocumentListeners()
Returns an array of all the document listeners registered on this document.

Methods in javax.swing.text with parameters of type DocumentListener
void | DefaultStyledDocument.addDocumentListener(DocumentListener listener) Adds a document listener for notification of any changes.
void | AbstractDocument.addDocumentListener(DocumentListener listener) Adds a document listener for notification of any changes.
void | Document.addDocumentListener(DocumentListener listener) Registers the given observer to begin receiving notifications when changes are made to the document.
void | DefaultStyledDocument.removeDocumentListener(DocumentListener listener) Removes a document listener.
void | AbstractDocument.removeDocumentListener(DocumentListener listener) Removes a document listener.
void | Document.removeDocumentListener(DocumentListener listener) Unregisters the given observer from the notification list so it will no longer receive change updates.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.HyperlinkListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.HyperlinkListener

Packages that use HyperlinkListener
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of HyperlinkListener in javax.swing

Methods in javax.swing that return HyperlinkListener
 HyperlinkListener[] JEditorPane.getHyperlinkListeners()
Returns an array of all the HyperLinkListeners added to this JEditorPane with addHyperlinkListener().

Methods in javax.swing with parameters of type HyperlinkListener
void | JEditorPane.addHyperlinkListener(HyperlinkListener listener) Adds a hyperlink listener for notification of any changes, for example when a link is selected and entered.
void | JEditorPane.removeHyperlinkListener(HyperlinkListener listener) Removes a hyperlink listener.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.InternalFrameListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.InternalFrameListener

Packages that use InternalFrameListener
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of InternalFrameListener in javax.swing

Methods in javax.swing that return InternalFrameListener
 InternalFrameListener[] JInternalFrame.getInternalFrameListeners()
Returns an array of all the InternalFrameListeners added to this JInternalFrame with addInternalFrameListener.

Methods in javax.swing with parameters of type InternalFrameListener
void | JInternalFrame.addInternalFrameListener(InternalFrameListener l) Adds the specified listener to receive internal frame events from this internal frame.
void | JInternalFrame.removeInternalFrameListener(InternalFrameListener l) Removes the specified internal frame listener so that it no longer receives internal frame events from this internal frame.

Uses of InternalFrameListener in javax.swing.event

Classes in javax.swing.event that implement InternalFrameListener
 class InternalFrameAdapter
An abstract adapter class for receiving internal frame events.

Uses of InternalFrameListener in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement InternalFrameListener
protected  class BasicInternalFrameUI.BasicInternalFrameListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.ListDataListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.ListDataListener

Packages that use ListDataListener
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of ListDataListener in javax.swing

Classes in javax.swing that implement ListDataListener
class | JComboBox A component that combines a button or editable field and a drop-down list.
protected class | JList.AccessibleJList This class implements accessibility support for the JList class.

Methods in javax.swing that return ListDataListener
 ListDataListener[] AbstractListModel.getListDataListeners()
Returns an array of all the list data listeners registered on this AbstractListModel.

Methods in javax.swing with parameters of type ListDataListener
void | AbstractListModel.addListDataListener(ListDataListener l) Adds a listener to the list that's notified each time a change to the data model occurs.
void | ListModel.addListDataListener(ListDataListener l) Adds a listener to the list that's notified each time a change to the data model occurs.
void | AbstractListModel.removeListDataListener(ListDataListener l) Removes a listener from the list that's notified each time a change to the data model occurs.
void | ListModel.removeListDataListener(ListDataListener l) Removes a listener from the list that's notified each time a change to the data model occurs.

Uses of ListDataListener in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement ListDataListener
class | BasicComboBoxUI.ListDataHandler This listener watches for changes in the ComboBoxModel.
class | BasicComboPopup.ListDataHandler As of 1.4, this class is now obsolete, doesn't do anything, and is only included for backwards API compatibility.
class | BasicListUI.ListDataHandler The ListDataListener that's added to the JLists model at installUI time, and whenever the JList.model property changes.

Fields in javax.swing.plaf.basic declared as ListDataListener
protected ListDataListener | BasicListUI.listDataListener
protected ListDataListener | BasicComboBoxUI.listDataListener This protected field is implementation specific.
protected ListDataListener | BasicComboPopup.listDataListener This protected field is implementation specific.

Methods in javax.swing.plaf.basic that return ListDataListener
protected ListDataListener | BasicListUI.createListDataListener() Creates an instance of ListDataListener that's added to the JLists by model as needed.
protected ListDataListener | BasicComboBoxUI.createListDataListener() Creates a list data listener which will be added to the ComboBoxModel.
protected ListDataListener | BasicComboPopup.createListDataListener() Creates a list data listener which will be added to the ComboBoxModel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.ListSelectionListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.ListSelectionListener

Packages that use ListSelectionListener
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of ListSelectionListener in javax.swing

Classes in javax.swing that implement ListSelectionListener
protected class | JList.AccessibleJList This class implements accessibility support for the JList class.
class | JTable The JTable is used to display and edit regular two-dimensional tables of cells.
protected class | JTable.AccessibleJTable This class implements accessibility support for the JTable class.

Methods in javax.swing that return ListSelectionListener
ListSelectionListener[] | JList.getListSelectionListeners() Returns an array of all the ListSelectionListeners added to this JList by way of addListSelectionListener.
ListSelectionListener[] | DefaultListSelectionModel.getListSelectionListeners() Returns an array of all the list selection listeners registered on this DefaultListSelectionModel.

Methods in javax.swing with parameters of type ListSelectionListener
void | JList.addListSelectionListener(ListSelectionListener listener) Adds a listener to the list, to be notified each time a change to the selection occurs; the preferred way of listening for selection state changes.
void | DefaultListSelectionModel.addListSelectionListener(ListSelectionListener l) Add a listener to the list that's notified each time a change to the selection occurs.
void | ListSelectionModel.addListSelectionListener(ListSelectionListener x) Add a listener to the list that's notified each time a change to the selection occurs.
void | JList.removeListSelectionListener(ListSelectionListener listener) Removes a selection listener from the list.
void | DefaultListSelectionModel.removeListSelectionListener(ListSelectionListener l) Remove a listener from the list that's notified each time a change to the selection occurs.
void | ListSelectionModel.removeListSelectionListener(ListSelectionListener x) Remove a listener from the list that's notified each time a change to the selection occurs.

Uses of ListSelectionListener in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement ListSelectionListener
protected class | BasicComboPopup.ListSelectionHandler As of Java 2 platform v 1.4, this class is now obsolete, doesn't do anything, and is only included for backwards API compatibility.
protected class | BasicFileChooserUI.SelectionListener
class | BasicListUI.ListSelectionHandler The ListSelectionListener that's added to the JLists selection model at installUI time, and whenever the JList.selectionModel property changes.

Fields in javax.swing.plaf.basic declared as ListSelectionListener
protected ListSelectionListener | BasicListUI.listSelectionListener
protected ListSelectionListener | BasicComboPopup.listSelectionListener This protected field is implementation specific.

Methods in javax.swing.plaf.basic that return ListSelectionListener
protected ListSelectionListener | BasicListUI.createListSelectionListener() Creates an instance of ListSelectionHandler that's added to the JLists by selectionModel as needed.
protected ListSelectionListener | BasicComboPopup.createListSelectionListener() Creates a list selection listener that watches for selection changes in the popup's list.
ListSelectionListener | BasicFileChooserUI.createListSelectionListener(JFileChooser fc)

Uses of ListSelectionListener in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal that return ListSelectionListener
 ListSelectionListener MetalFileChooserUI.createListSelectionListener(JFileChooser fc)
Creates a selection listener for the list of files and directories.

Uses of ListSelectionListener in javax.swing.table

Classes in javax.swing.table that implement ListSelectionListener
 class DefaultTableColumnModel
The standard column-handler for a JTable.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.MenuDragMouseListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.MenuDragMouseListener

Packages that use MenuDragMouseListener
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of MenuDragMouseListener in javax.swing

Methods in javax.swing that return MenuDragMouseListener
 MenuDragMouseListener[] JMenuItem.getMenuDragMouseListeners()
Returns an array of all the MenuDragMouseListeners added to this JMenuItem with addMenuDragMouseListener().

Methods in javax.swing with parameters of type MenuDragMouseListener
void | JMenuItem.addMenuDragMouseListener(MenuDragMouseListener l) Adds a MenuDragMouseListener to the menu item.
void | JMenuItem.removeMenuDragMouseListener(MenuDragMouseListener l) Removes a MenuDragMouseListener from the menu item.

Uses of MenuDragMouseListener in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as MenuDragMouseListener
protected  MenuDragMouseListener BasicMenuItemUI.menuDragMouseListener

Methods in javax.swing.plaf.basic that return MenuDragMouseListener
protected MenuDragMouseListener | BasicMenuUI.createMenuDragMouseListener(JComponent c)
protected MenuDragMouseListener | BasicMenuItemUI.createMenuDragMouseListener(JComponent c)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.MenuKeyListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.MenuKeyListener

Packages that use MenuKeyListener
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of MenuKeyListener in javax.swing

Methods in javax.swing that return MenuKeyListener
 MenuKeyListener[] JMenuItem.getMenuKeyListeners()
Returns an array of all the MenuKeyListeners added to this JMenuItem with addMenuKeyListener().
 MenuKeyListener[] JPopupMenu.getMenuKeyListeners()
Returns an array of all the MenuKeyListeners added to this JPopupMenu with addMenuKeyListener().

Methods in javax.swing with parameters of type MenuKeyListener
void | JMenuItem.addMenuKeyListener(MenuKeyListener l) Adds a MenuKeyListener to the menu item.
void | JPopupMenu.addMenuKeyListener(MenuKeyListener l) Adds a MenuKeyListener to the popup menu.
void | JMenuItem.removeMenuKeyListener(MenuKeyListener l) Removes a MenuKeyListener from the menu item.
void | JPopupMenu.removeMenuKeyListener(MenuKeyListener l) Removes a MenuKeyListener from the popup menu.

Uses of MenuKeyListener in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as MenuKeyListener
protected  MenuKeyListener BasicMenuItemUI.menuKeyListener

Methods in javax.swing.plaf.basic that return MenuKeyListener
protected MenuKeyListener | BasicMenuUI.createMenuKeyListener(JComponent c)
protected MenuKeyListener | BasicMenuItemUI.createMenuKeyListener(JComponent c)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.MenuListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.MenuListener

Packages that use MenuListener
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of MenuListener in javax.swing

Methods in javax.swing that return MenuListener
 MenuListener[] JMenu.getMenuListeners()
Returns an array of all the MenuListeners added to this JMenu with addMenuListener().

Methods in javax.swing with parameters of type MenuListener
void | JMenu.addMenuListener(MenuListener l) Adds a listener for menu events.
void | JMenu.removeMenuListener(MenuListener l) Removes a listener for menu events.

Uses of MenuListener in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as MenuListener
protected  MenuListener BasicMenuUI.menuListener

Methods in javax.swing.plaf.basic that return MenuListener
protected  MenuListener BasicMenuUI.createMenuListener(JComponent c)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.MouseInputListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.MouseInputListener

Packages that use MouseInputListener
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of MouseInputListener in javax.swing.event

Classes in javax.swing.event that implement MouseInputListener
 class MouseInputAdapter
An empty implementation of the MouseInputListener interface, provided as a convenience to simplify the task of creating listeners, by extending and implementing only the methods of interest.

Uses of MouseInputListener in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement MouseInputListener
class | BasicDesktopIconUI.MouseInputHandler Listens for mouse movements and acts on them.
protected class | BasicInternalFrameUI.BorderListener Listens for border adjustments.
protected class | BasicInternalFrameUI.GlassPaneDispatcher
class | BasicListUI.MouseInputHandler Mouse input, and focus handling for JList.
protected class | BasicMenuItemUI.MouseInputHandler
protected class | BasicMenuUI.MouseInputHandler Instantiated and used by a menu item to handle the current menu selection from mouse events.
class | BasicSliderUI.TrackListener Track mouse movements.
class | BasicTableHeaderUI.MouseInputHandler This inner class is marked "public" due to a compiler bug.
class | BasicTableUI.MouseInputHandler This inner class is marked "public" due to a compiler bug.
class | BasicToolBarUI.DockingListener This class should be treated as a "protected" inner class.
class | BasicTreeUI.MouseInputHandler MouseInputHandler handles passing all mouse events, including mouse motion events, until the mouse is released to the destination it is constructed with.

Fields in javax.swing.plaf.basic declared as MouseInputListener
protected MouseInputListener | BasicToolBarUI.dockingListener
protected MouseInputListener | BasicInternalFrameUI.glassPaneDispatcher
protected MouseInputListener | BasicTableHeaderUI.mouseInputListener
protected MouseInputListener | BasicTableUI.mouseInputListener
protected MouseInputListener | BasicListUI.mouseInputListener
protected MouseInputListener | BasicMenuItemUI.mouseInputListener

Methods in javax.swing.plaf.basic that return MouseInputListener
protected MouseInputListener | BasicToolBarUI.createDockingListener()
protected MouseInputListener | BasicInternalFrameUI.createGlassPaneDispatcher()
protected MouseInputListener | BasicTableHeaderUI.createMouseInputListener() Creates the mouse listener for the JTableHeader.
protected MouseInputListener | BasicTableUI.createMouseInputListener() Creates the mouse listener for the JTable.
protected MouseInputListener | BasicListUI.createMouseInputListener() Creates a delegate that implements MouseInputListener.
protected MouseInputListener | BasicDesktopIconUI.createMouseInputListener()
protected MouseInputListener | BasicMenuUI.createMouseInputListener(JComponent c)
protected MouseInputListener | BasicMenuItemUI.createMouseInputListener(JComponent c)

Uses of MouseInputListener in javax.swing.plaf.metal

Classes in javax.swing.plaf.metal that implement MouseInputListener
protected  class MetalToolBarUI.MetalDockingListener

Methods in javax.swing.plaf.metal that return MouseInputListener
protected  MouseInputListener MetalToolBarUI.createDockingListener()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.PopupMenuListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.PopupMenuListener

Packages that use PopupMenuListener
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of PopupMenuListener in javax.swing

Methods in javax.swing that return PopupMenuListener
 PopupMenuListener[] JComboBox.getPopupMenuListeners()
Returns an array of all the PopupMenuListeners added to this JComboBox with addPopupMenuListener().
 PopupMenuListener[] JPopupMenu.getPopupMenuListeners()
Returns an array of all the PopupMenuListeners added to this JMenuItem with addPopupMenuListener().

Methods in javax.swing with parameters of type PopupMenuListener
void | JComboBox.addPopupMenuListener(PopupMenuListener l) Adds a PopupMenu listener which will listen to notification messages from the popup portion of the combo box.
void | JPopupMenu.addPopupMenuListener(PopupMenuListener l) Adds a PopupMenu listener.
void | JComboBox.removePopupMenuListener(PopupMenuListener l) Removes a PopupMenuListener.
void | JPopupMenu.removePopupMenuListener(PopupMenuListener l) Removes a PopupMenu listener.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.RowSorterListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.RowSorterListener

Packages that use RowSorterListener
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of RowSorterListener in javax.swing

Classes in javax.swing that implement RowSorterListener
 class JTable
The JTable is used to display and edit regular two-dimensional tables of cells.

Methods in javax.swing with parameters of type RowSorterListener
void | RowSorter.addRowSorterListener(RowSorterListener l) Adds a RowSorterListener to receive notification about this RowSorter.
void | RowSorter.removeRowSorterListener(RowSorterListener l) Removes a RowSorterListener.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.TableColumnModelListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.TableColumnModelListener

Packages that use TableColumnModelListener
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of TableColumnModelListener in javax.swing

Classes in javax.swing that implement TableColumnModelListener
class | JTable The JTable is used to display and edit regular two-dimensional tables of cells.
protected class | JTable.AccessibleJTable This class implements accessibility support for the JTable class.

Uses of TableColumnModelListener in javax.swing.table

Classes in javax.swing.table that implement TableColumnModelListener
 class JTableHeader
This is the object which manages the header of the JTable.

Methods in javax.swing.table that return TableColumnModelListener
 TableColumnModelListener[] DefaultTableColumnModel.getColumnModelListeners()
Returns an array of all the column model listeners registered on this model.

Methods in javax.swing.table with parameters of type TableColumnModelListener
void | DefaultTableColumnModel.addColumnModelListener(TableColumnModelListener x) Adds a listener for table column model events.
void | TableColumnModel.addColumnModelListener(TableColumnModelListener x) Adds a listener for table column model events.
void | DefaultTableColumnModel.removeColumnModelListener(TableColumnModelListener x) Removes a listener for table column model events.
void | TableColumnModel.removeColumnModelListener(TableColumnModelListener x) Removes a listener for table column model events.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.TableModelListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.TableModelListener

Packages that use TableModelListener
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of TableModelListener in javax.swing

Classes in javax.swing that implement TableModelListener
class | JTable The JTable is used to display and edit regular two-dimensional tables of cells.
protected class | JTable.AccessibleJTable This class implements accessibility support for the JTable class.

Uses of TableModelListener in javax.swing.table

Methods in javax.swing.table that return TableModelListener
 TableModelListener[] AbstractTableModel.getTableModelListeners()
Returns an array of all the table model listeners registered on this model.

Methods in javax.swing.table with parameters of type TableModelListener
void | AbstractTableModel.addTableModelListener(TableModelListener l) Adds a listener to the list that's notified each time a change to the data model occurs.
void | TableModel.addTableModelListener(TableModelListener l) Adds a listener to the list that is notified each time a change to the data model occurs.
void | AbstractTableModel.removeTableModelListener(TableModelListener l) Removes a listener from the list that's notified each time a change to the data model occurs.
void | TableModel.removeTableModelListener(TableModelListener l) Removes a listener from the list that is notified each time a change to the data model occurs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.TreeExpansionListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.TreeExpansionListener

Packages that use TreeExpansionListener
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.

Uses of TreeExpansionListener in javax.swing

Classes in javax.swing that implement TreeExpansionListener
protected  class JTree.AccessibleJTree
This class implements accessibility support for the JTree class.

Methods in javax.swing that return TreeExpansionListener
 TreeExpansionListener[] JTree.getTreeExpansionListeners()
Returns an array of all the TreeExpansionListeners added to this JTree with addTreeExpansionListener().

Methods in javax.swing with parameters of type TreeExpansionListener
void | JTree.addTreeExpansionListener(TreeExpansionListener tel) Adds a listener for TreeExpansion events.
void | JTree.removeTreeExpansionListener(TreeExpansionListener tel) Removes a listener for TreeExpansion events.

Uses of TreeExpansionListener in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement TreeExpansionListener
 class BasicTreeUI.TreeExpansionHandler
Updates the TreeState in response to nodes expanding/collapsing.

Methods in javax.swing.plaf.basic that return TreeExpansionListener
protected  TreeExpansionListener BasicTreeUI.createTreeExpansionListener()
Creates and returns the object responsible for updating the treestate when nodes expanded state changes.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.TreeModelListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.TreeModelListener

Packages that use TreeModelListener
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of TreeModelListener in javax.swing

Classes in javax.swing that implement TreeModelListener
protected class | JTree.AccessibleJTree This class implements accessibility support for the JTree class.
protected class | JTree.TreeModelHandler Listens to the model and updates the expandedState accordingly when nodes are removed, or changed.

Fields in javax.swing declared as TreeModelListener
protected  TreeModelListener JTree.treeModelListener
Updates the expandedState.

Methods in javax.swing that return TreeModelListener
protected  TreeModelListener JTree.createTreeModelListener()
Creates and returns an instance of TreeModelHandler.

Uses of TreeModelListener in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement TreeModelListener
 class BasicTreeUI.TreeModelHandler
Forwards all TreeModel events to the TreeState.

Methods in javax.swing.plaf.basic that return TreeModelListener
protected  TreeModelListener BasicTreeUI.createTreeModelListener()
Returns a listener that can update the tree when the model changes.

Uses of TreeModelListener in javax.swing.tree

Methods in javax.swing.tree that return TreeModelListener
 TreeModelListener[] DefaultTreeModel.getTreeModelListeners()
Returns an array of all the tree model listeners registered on this model.

Methods in javax.swing.tree with parameters of type TreeModelListener
 void DefaultTreeModel.addTreeModelListener(TreeModelListener l)
Adds a listener for the TreeModelEvent posted after the tree changes.
 void TreeModel.addTreeModelListener(TreeModelListener l)
Adds a listener for the TreeModelEvent posted after the tree changes.
 void DefaultTreeModel.removeTreeModelListener(TreeModelListener l)
Removes a listener previously added with addTreeModelListener().
 void TreeModel.removeTreeModelListener(TreeModelListener l)
Removes a listener previously added with addTreeModelListener.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.TreeSelectionListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.TreeSelectionListener

Packages that use TreeSelectionListener
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of TreeSelectionListener in javax.swing

Classes in javax.swing that implement TreeSelectionListener
protected class | JTree.AccessibleJTree This class implements accessibility support for the JTree class.
protected class | JTree.TreeSelectionRedirector Handles creating a new TreeSelectionEvent with the JTree as the source and passing it off to all the listeners.

Methods in javax.swing that return TreeSelectionListener
 TreeSelectionListener[] JTree.getTreeSelectionListeners()
Returns an array of all the TreeSelectionListeners added to this JTree with addTreeSelectionListener().

Methods in javax.swing with parameters of type TreeSelectionListener
void | JTree.addTreeSelectionListener(TreeSelectionListener tsl) Adds a listener for TreeSelection events.
void | JTree.removeTreeSelectionListener(TreeSelectionListener tsl) Removes a TreeSelection listener.

Uses of TreeSelectionListener in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement TreeSelectionListener
 class BasicTreeUI.TreeSelectionHandler
Listens for changes in the selection model and updates the display accordingly.

Methods in javax.swing.plaf.basic that return TreeSelectionListener
protected  TreeSelectionListener BasicTreeUI.createTreeSelectionListener()
Creates the listener that updates the display based on selection change methods.

Uses of TreeSelectionListener in javax.swing.tree

Classes in javax.swing.tree that implement TreeSelectionListener
 class DefaultTreeCellEditor
A TreeCellEditor.

Methods in javax.swing.tree that return TreeSelectionListener
 TreeSelectionListener[] DefaultTreeSelectionModel.getTreeSelectionListeners()
Returns an array of all the tree selection listeners registered on this model.

Methods in javax.swing.tree with parameters of type TreeSelectionListener
void | DefaultTreeSelectionModel.addTreeSelectionListener(TreeSelectionListener x) Adds x to the list of listeners that are notified each time the set of selected TreePaths changes.
void | TreeSelectionModel.addTreeSelectionListener(TreeSelectionListener x) Adds x to the list of listeners that are notified each time the set of selected TreePaths changes.
void | DefaultTreeSelectionModel.removeTreeSelectionListener(TreeSelectionListener x) Removes x from the list of listeners that are notified each time the set of selected TreePaths changes.
void | TreeSelectionModel.removeTreeSelectionListener(TreeSelectionListener x) Removes x from the list of listeners that are notified each time the set of selected TreePaths changes.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.TreeWillExpandListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.TreeWillExpandListener

Packages that use TreeWillExpandListener
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of TreeWillExpandListener in javax.swing

Methods in javax.swing that return TreeWillExpandListener
 TreeWillExpandListener[] JTree.getTreeWillExpandListeners()
Returns an array of all the TreeWillExpandListeners added to this JTree with addTreeWillExpandListener().

Methods in javax.swing with parameters of type TreeWillExpandListener
void | JTree.addTreeWillExpandListener(TreeWillExpandListener tel) Adds a listener for TreeWillExpand events.
void | JTree.removeTreeWillExpandListener(TreeWillExpandListener tel) Removes a listener for TreeWillExpand events.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.event.UndoableEditListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.event.UndoableEditListener

Packages that use UndoableEditListener
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.undo | Allows developers to provide support for undo/redo in applications such as text editors.

Uses of UndoableEditListener in javax.swing.text

Methods in javax.swing.text that return UndoableEditListener
 UndoableEditListener[] AbstractDocument.getUndoableEditListeners()
Returns an array of all the undoable edit listeners registered on this document.

Methods in javax.swing.text with parameters of type UndoableEditListener
void | AbstractDocument.addUndoableEditListener(UndoableEditListener listener) Adds an undo listener for notification of any changes.
void | Document.addUndoableEditListener(UndoableEditListener listener) Registers the given observer to begin receiving notifications when undoable edits are made to the document.
void | AbstractDocument.removeUndoableEditListener(UndoableEditListener listener) Removes an undo listener.
void | Document.removeUndoableEditListener(UndoableEditListener listener) Unregisters the given observer from the notification list so it will no longer receive updates.

Uses of UndoableEditListener in javax.swing.undo

Classes in javax.swing.undo that implement UndoableEditListener
 class UndoManager
UndoManager manages a list of UndoableEdits, providing a way to undo or redo the appropriate edits.

Fields in javax.swing.undo with type parameters of type UndoableEditListener
protected  Vector<UndoableEditListener> UndoableEditSupport.listeners

Methods in javax.swing.undo that return UndoableEditListener
 UndoableEditListener[] UndoableEditSupport.getUndoableEditListeners()
Returns an array of all the UndoableEditListeners added to this UndoableEditSupport with addUndoableEditListener().

Methods in javax.swing.undo with parameters of type UndoableEditListener
void | UndoableEditSupport.addUndoableEditListener(UndoableEditListener l) Registers an UndoableEditListener.
void | UndoableEditSupport.removeUndoableEditListener(UndoableEditListener l) Removes an UndoableEditListener.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DocumentEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface DocumentEvent

All Known Implementing Classes:
AbstractDocument.DefaultDocumentEvent
public interface DocumentEvent

Interface for document change notifications. This provides detailed information to Document observers about how the Document changed. It provides high level information such as type of change and where it occurred, as well as the more detailed structural changes (What Elements were inserted and removed).

See Also:
Document, DocumentListener

Nested Class Summary
static interface | DocumentEvent.ElementChange Describes changes made to a specific element.
static class | DocumentEvent.EventType Enumeration for document event types
Method Summary
DocumentEvent.ElementChange | getChange(Element elem) Gets the change information for the given element.
Document | getDocument() Gets the document that sourced the change event.
int | getLength() Returns the length of the change.
int | getOffset() Returns the offset within the document of the start of the change.
DocumentEvent.EventType | getType() Gets the type of event.

Method Detail

getOffset

int getOffset()
Returns the offset within the document of the start of the change.

Returns:
the offset >= 0

getLength

int getLength()
Returns the length of the change.

Returns:
the length >= 0

getDocument

Document getDocument()
Gets the document that sourced the change event.

Returns:
the document

getType

DocumentEvent.EventType getType()
Gets the type of event.

Returns:
the type

getChange

DocumentEvent.ElementChange getChange(Element elem)
Gets the change information for the given element. The change information describes what elements were added and removed and the location. If there were no changes, null is returned.

This method is for observers to discover the structural changes that were made. This means that only elements that existed prior to the mutation (and still exist after the mutatino) need to have ElementChange records. The changes made available need not be recursive.

For example, if the an element is removed from it's parent, this method should report that the parent changed and provide an ElementChange implementation that describes the change to the parent. If the child element removed had children, these elements do not need to be reported as removed.

If an child element is insert into a parent element, the parent element should report a change. If the child element also had elements inserted into it (grandchildren to the parent) these elements need not report change.

Parameters:
elem - the element
Returns:
the change information, or null if the element was not modified
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocumentEvent.ElementChange

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface DocumentEvent.ElementChange

All Known Implementing Classes:
AbstractDocument.ElementEdit
Enclosing interface:
DocumentEvent
public static interface DocumentEvent.ElementChange

Describes changes made to a specific element.

Method Summary
Element[] | getChildrenAdded() Gets the child elements that were added to the given parent element.
Element[] | getChildrenRemoved() Gets the child elements that were removed from the given parent element.
Element | getElement() Returns the element represented.
int | getIndex() Fetches the index within the element represented.

Method Detail

getElement

Element getElement()
Returns the element represented. This is the element that was changed.

Returns:
the element

getIndex

int getIndex()
Fetches the index within the element represented. This is the location that children were added and/or removed.

Returns:
the index >= 0

getChildrenRemoved

Element[] getChildrenRemoved()
Gets the child elements that were removed from the given parent element. The element array returned is sorted in the order that the elements used to lie in the document, and must be contiguous.

Returns:
the child elements

getChildrenAdded

Element[] getChildrenAdded()
Gets the child elements that were added to the given parent element. The element array returned is in the order that the elements lie in the document, and must be contiguous.

Returns:
the child elements
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocumentEvent.EventType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class DocumentEvent.EventType

java.lang.Object
    extended by  javax.swing.event.DocumentEvent.EventType
Enclosing interface:
DocumentEvent
public static final class DocumentEvent.EventType
extends Object

Enumeration for document event types

Field Summary
static DocumentEvent.EventType | CHANGE Change type.
static DocumentEvent.EventType | INSERT Insert type.
static DocumentEvent.EventType | REMOVE Remove type.
Method Summary
 String toString()
Converts the type to a string.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

INSERT

public static final DocumentEvent.EventType INSERT
Insert type.

REMOVE

public static final DocumentEvent.EventType REMOVE
Remove type.

CHANGE

public static final DocumentEvent.EventType CHANGE
Change type.

Method Detail

toString

public String toString()
Converts the type to a string.

Overrides:
toString in class Object
Returns:
the string
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocumentListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface DocumentListener

All Superinterfaces:
EventListener
All Known Implementing Classes:
JEditorPane.AccessibleJEditorPane, JEditorPane.AccessibleJEditorPaneHTML, JEditorPane.JEditorPaneAccessibleHypertextSupport, JPasswordField.AccessibleJPasswordField, JTextArea.AccessibleJTextArea, JTextComponent.AccessibleJTextComponent, JTextField.AccessibleJTextField
public interface DocumentListener
extends EventListener

Interface for an observer to register to receive notifications of changes to a text document.

The default implementation of the Document interface (AbstractDocument) supports asynchronous mutations. If this feature is used (i.e. mutations are made from a thread other than the Swing event thread), the listeners will be notified via the mutating thread. This means that if asynchronous updates are made, the implementation of this interface must be threadsafe!

The DocumentEvent notification is based upon the JavaBeans event model. There is no guarantee about the order of delivery to listeners, and all listeners must be notified prior to making further mutations to the Document. This means implementations of the DocumentListener may not mutate the source of the event (i.e. the associated Document).

See Also:
Document, StyledDocument, DocumentEvent

Method Summary
void | changedUpdate(DocumentEvent e) Gives notification that an attribute or set of attributes changed.
void | insertUpdate(DocumentEvent e) Gives notification that there was an insert into the document.
void | removeUpdate(DocumentEvent e) Gives notification that a portion of the document has been removed.

Method Detail

insertUpdate

void insertUpdate(DocumentEvent e)
Gives notification that there was an insert into the document. The range given by the DocumentEvent bounds the freshly inserted region.

Parameters:
e - the document event

removeUpdate

void removeUpdate(DocumentEvent e)
Gives notification that a portion of the document has been removed. The range is given in terms of what the view last saw (that is, before updating sticky positions).

Parameters:
e - the document event

changedUpdate

void changedUpdate(DocumentEvent e)
Gives notification that an attribute or set of attributes changed.

Parameters:
e - the document event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EventListenerList

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class EventListenerList

java.lang.Object
    extended by  javax.swing.event.EventListenerList
All Implemented Interfaces:
Serializable
public class EventListenerList
extends Object
implements Serializable

A class that holds a list of EventListeners. A single instance can be used to hold all listeners (of all types) for the instance using the list. It is the responsiblity of the class using the EventListenerList to provide type-safe API (preferably conforming to the JavaBeans spec) and methods which dispatch event notification methods to appropriate Event Listeners on the list. The main benefits that this class provides are that it is relatively cheap in the case of no listeners, and it provides serialization for event-listener lists in a single place, as well as a degree of MT safety (when used correctly). Usage example: Say one is defining a class that sends out FooEvents, and one wants to allow users of the class to register FooListeners and receive notification when FooEvents occur. The following should be added to the class definition:

 EventListenerList listenerList = new EventListenerList();
 FooEvent fooEvent = null;

 public void addFooListener(FooListener l) {
     listenerList.add(FooListener.class, l);
 }

 public void removeFooListener(FooListener l) {
     listenerList.remove(FooListener.class, l);
 }

 // Notify all listeners that have registered interest for
 // notification on this event type.  The event instance
 // is lazily created using the parameters passed into
 // the fire method.

 protected void fireFooXXX() {
     // Guaranteed to return a non-null array
     Object[] listeners = listenerList.getListenerList();
     // Process the listeners last to first, notifying
     // those that are interested in this event
     for (int i = listeners.length-2; i>=0; i-=2) {
         if (listeners[i]==FooListener.class) {
             // Lazily create the event:
             if (fooEvent == null)
                 fooEvent = new FooEvent(this);
             ((FooListener)listeners[i+1]).fooXXX(fooEvent);
         }
     }
 }
foo should be changed to the appropriate name, and fireFooXxx to the appropriate method name. One fire method should exist for each notification method in the FooListener interface.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected  Object[] listenerList
Constructor Summary
EventListenerList()
Method Summary
<T extends EventListener>
void
add(Class<T> t, T l)
Adds the listener as a listener of the specified type.
 int getListenerCount()
Returns the total number of listeners for this listener list.
 int getListenerCount(Class<?> t)
Returns the total number of listeners of the supplied type for this listener list.
 Object[] getListenerList()
Passes back the event listener list as an array of ListenerType-listener pairs.
<T extends EventListener>
T[]
getListeners(Class<T> t)
Return an array of all the listeners of the given type.
<T extends EventListener>
void
remove(Class<T> t, T l)
Removes the listener as a listener of the specified type.
 String toString()
Returns a string representation of the EventListenerList.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

listenerList

protected transient Object[] listenerList
Constructor Detail

EventListenerList

public EventListenerList()
Method Detail

getListenerList

public Object[] getListenerList()
Passes back the event listener list as an array of ListenerType-listener pairs. Note that for performance reasons, this implementation passes back the actual data structure in which the listener data is stored internally! This method is guaranteed to pass back a non-null array, so that no null-checking is required in fire methods. A zero-length array of Object should be returned if there are currently no listeners. WARNING!!! Absolutely NO modification of the data contained in this array should be made -- if any such manipulation is necessary, it should be done on a copy of the array returned rather than the array itself.

getListeners

public <T extends EventListener> T[] getListeners(Class<T> t)
Return an array of all the listeners of the given type.

Returns:
all of the listeners of the specified type.
Throws:
ClassCastException - if the supplied class is not assignable to EventListener
Since:
1.3

getListenerCount

public int getListenerCount()
Returns the total number of listeners for this listener list.

getListenerCount

public int getListenerCount(Class<?> t)
Returns the total number of listeners of the supplied type for this listener list.

add

public <T extends EventListener> void add(Class<T> t,
                                          T l)
Adds the listener as a listener of the specified type.

Parameters:
t - the type of the listener to be added
l - the listener to be added

remove

public <T extends EventListener> void remove(Class<T> t,
                                             T l)
Removes the listener as a listener of the specified type.

Parameters:
t - the type of the listener to be removed
l - the listener to be removed

toString

public String toString()
Returns a string representation of the EventListenerList.

Overrides:
toString in class Object
Returns:
a string representation of the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HyperlinkEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class HyperlinkEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.swing.event.HyperlinkEvent
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
HTMLFrameHyperlinkEvent
public class HyperlinkEvent
extends EventObject

HyperlinkEvent is used to notify interested parties that something has happened with respect to a hypertext link.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
static class HyperlinkEvent.EventType
Defines the ENTERED, EXITED, and ACTIVATED event types, along with their string representations, returned by toString().
Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
HyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL u)
Creates a new object representing a hypertext link event.
HyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL u, String desc)
Creates a new object representing a hypertext link event.
HyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL u, String desc, Element sourceElement)
Creates a new object representing a hypertext link event.
Method Summary
String | getDescription() Get the description of the link as a string.
HyperlinkEvent.EventType | getEventType() Gets the type of event.
Element | getSourceElement() Returns the Element that corresponds to the source of the event.
URL | getURL() Gets the URL that the link refers to.
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

HyperlinkEvent

public HyperlinkEvent(Object source,
                      HyperlinkEvent.EventType type,
                      URL u)
Creates a new object representing a hypertext link event. The other constructor is preferred, as it provides more information if a URL could not be formed. This constructor is primarily for backward compatibility.

Parameters:
source - the object responsible for the event
type - the event type
u - the affected URL

HyperlinkEvent

public HyperlinkEvent(Object source,
                      HyperlinkEvent.EventType type,
                      URL u,
                      String desc)
Creates a new object representing a hypertext link event.

Parameters:
source - the object responsible for the event
type - the event type
u - the affected URL. This may be null if a valid URL could not be created.
desc - the description of the link. This may be useful when attempting to form a URL resulted in a MalformedURLException. The description provides the text used when attempting to form the URL.

HyperlinkEvent

public HyperlinkEvent(Object source,
                      HyperlinkEvent.EventType type,
                      URL u,
                      String desc,
                      Element sourceElement)
Creates a new object representing a hypertext link event.

Parameters:
source - the object responsible for the event
type - the event type
u - the affected URL. This may be null if a valid URL could not be created.
desc - the description of the link. This may be useful when attempting to form a URL resulted in a MalformedURLException. The description provides the text used when attempting to form the URL.
sourceElement - Element in the Document representing the anchor
Since:
1.4
Method Detail

getEventType

public HyperlinkEvent.EventType getEventType()
Gets the type of event.

Returns:
the type

getDescription

public String getDescription()
Get the description of the link as a string. This may be useful if a URL can't be formed from the description, in which case the associated URL would be null.

getURL

public URL getURL()
Gets the URL that the link refers to.

Returns:
the URL

getSourceElement

public Element getSourceElement()
Returns the Element that corresponds to the source of the event. This will typically be an Element representing an anchor. If a constructur that is used that does not specify a source Element, or null was specified as the source Element, this will return null.

Returns:
Element indicating source of event, or null
Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HyperlinkEvent.EventType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class HyperlinkEvent.EventType

java.lang.Object
    extended by  javax.swing.event.HyperlinkEvent.EventType
Enclosing class:
HyperlinkEvent
public static final class HyperlinkEvent.EventType
extends Object

Defines the ENTERED, EXITED, and ACTIVATED event types, along with their string representations, returned by toString().

Field Summary
static HyperlinkEvent.EventType | ACTIVATED Activated type.
static HyperlinkEvent.EventType | ENTERED Entered type.
static HyperlinkEvent.EventType | EXITED Exited type.
Method Summary
 String toString()
Converts the type to a string.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ENTERED

public static final HyperlinkEvent.EventType ENTERED
Entered type.

EXITED

public static final HyperlinkEvent.EventType EXITED
Exited type.

ACTIVATED

public static final HyperlinkEvent.EventType ACTIVATED
Activated type.

Method Detail

toString

public String toString()
Converts the type to a string.

Overrides:
toString in class Object
Returns:
the string
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HyperlinkListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface HyperlinkListener

All Superinterfaces:
EventListener
public interface HyperlinkListener
extends EventListener

HyperlinkListener

Method Summary
 void hyperlinkUpdate(HyperlinkEvent e)
Called when a hypertext link is updated.

Method Detail

hyperlinkUpdate

void hyperlinkUpdate(HyperlinkEvent e)
Called when a hypertext link is updated.

Parameters:
e - the event responsible for the update
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InternalFrameAdapter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class InternalFrameAdapter

java.lang.Object
    extended by  javax.swing.event.InternalFrameAdapter
All Implemented Interfaces:
EventListener, InternalFrameListener
public abstract class InternalFrameAdapter
extends Object
implements InternalFrameListener

An abstract adapter class for receiving internal frame events. The methods in this class are empty. This class exists as convenience for creating listener objects, and is functionally equivalent to the WindowAdapter class in the AWT.

See How to Write an Internal Frame Listener in The Java Tutorial and The Java Class Libraries (update)

See Also:
InternalFrameEvent, InternalFrameListener, WindowListener

Constructor Summary
InternalFrameAdapter()
Method Summary
void | internalFrameActivated(InternalFrameEvent e) Invoked when an internal frame is activated.
void | internalFrameClosed(InternalFrameEvent e) Invoked when an internal frame has been closed.
void | internalFrameClosing(InternalFrameEvent e) Invoked when an internal frame is in the process of being closed.
void | internalFrameDeactivated(InternalFrameEvent e) Invoked when an internal frame is de-activated.
void | internalFrameDeiconified(InternalFrameEvent e) Invoked when an internal frame is de-iconified.
void | internalFrameIconified(InternalFrameEvent e) Invoked when an internal frame is iconified.
void | internalFrameOpened(InternalFrameEvent e) Invoked when an internal frame has been opened.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InternalFrameAdapter

public InternalFrameAdapter()
Method Detail

internalFrameOpened

public void internalFrameOpened(InternalFrameEvent e)
Invoked when an internal frame has been opened.

Specified by:
internalFrameOpened in interface InternalFrameListener
See Also:
JInternalFrame.show()

internalFrameClosing

public void internalFrameClosing(InternalFrameEvent e)
Invoked when an internal frame is in the process of being closed. The close operation can be overridden at this point.

Specified by:
internalFrameClosing in interface InternalFrameListener
See Also:
JInternalFrame.setDefaultCloseOperation(int)

internalFrameClosed

public void internalFrameClosed(InternalFrameEvent e)
Invoked when an internal frame has been closed.

Specified by:
internalFrameClosed in interface InternalFrameListener
See Also:
JInternalFrame.setClosed(boolean)

internalFrameIconified

public void internalFrameIconified(InternalFrameEvent e)
Invoked when an internal frame is iconified.

Specified by:
internalFrameIconified in interface InternalFrameListener
See Also:
JInternalFrame.setIcon(boolean)

internalFrameDeiconified

public void internalFrameDeiconified(InternalFrameEvent e)
Invoked when an internal frame is de-iconified.

Specified by:
internalFrameDeiconified in interface InternalFrameListener
See Also:
JInternalFrame.setIcon(boolean)

internalFrameActivated

public void internalFrameActivated(InternalFrameEvent e)
Invoked when an internal frame is activated.

Specified by:
internalFrameActivated in interface InternalFrameListener
See Also:
JInternalFrame.setSelected(boolean)

internalFrameDeactivated

public void internalFrameDeactivated(InternalFrameEvent e)
Invoked when an internal frame is de-activated.

Specified by:
internalFrameDeactivated in interface InternalFrameListener
See Also:
JInternalFrame.setSelected(boolean)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InternalFrameEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class InternalFrameEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  java.awt.AWTEvent
            extended by  javax.swing.event.InternalFrameEvent
All Implemented Interfaces:
Serializable
public class InternalFrameEvent
extends AWTEvent

An AWTEvent that adds support for JInternalFrame objects as the event source. This class has the same event types as WindowEvent, although different IDs are used. Help on handling internal frame events is in How to Write an Internal Frame Listener, a section in The Java Tutorial.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
WindowEvent, WindowListener, JInternalFrame, InternalFrameListener

Field Summary
static int | INTERNAL_FRAME_ACTIVATED The "window activated" event type.
static int | INTERNAL_FRAME_CLOSED The "window closed" event.
static int | INTERNAL_FRAME_CLOSING The "window is closing" event.
static int | INTERNAL_FRAME_DEACTIVATED The "window deactivated" event type.
static int | INTERNAL_FRAME_DEICONIFIED The "window deiconified" event type.
static int | INTERNAL_FRAME_FIRST The first number in the range of IDs used for internal frame events.
static int | INTERNAL_FRAME_ICONIFIED The "window iconified" event.
static int | INTERNAL_FRAME_LAST The last number in the range of IDs used for internal frame events.
static int | INTERNAL_FRAME_OPENED The "window opened" event.
Fields inherited from class java.awt.AWTEvent
ACTION_EVENT_MASK, ADJUSTMENT_EVENT_MASK, COMPONENT_EVENT_MASK, consumed, CONTAINER_EVENT_MASK, FOCUS_EVENT_MASK, HIERARCHY_BOUNDS_EVENT_MASK, HIERARCHY_EVENT_MASK, id, INPUT_METHOD_EVENT_MASK, INVOCATION_EVENT_MASK, ITEM_EVENT_MASK, KEY_EVENT_MASK, MOUSE_EVENT_MASK, MOUSE_MOTION_EVENT_MASK, MOUSE_WHEEL_EVENT_MASK, PAINT_EVENT_MASK, RESERVED_ID_MAX, TEXT_EVENT_MASK, WINDOW_EVENT_MASK, WINDOW_FOCUS_EVENT_MASK, WINDOW_STATE_EVENT_MASK
Fields inherited from class java.util.EventObject
source
Constructor Summary
InternalFrameEvent(JInternalFrame source, int id)
Constructs an InternalFrameEvent object.
Method Summary
JInternalFrame | getInternalFrame() Returns the originator of the event.
String | paramString() Returns a parameter string identifying this event.
Methods inherited from class java.awt.AWTEvent
consume, getID, isConsumed, setSource, toString
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

INTERNAL_FRAME_FIRST

public static final int INTERNAL_FRAME_FIRST
The first number in the range of IDs used for internal frame events.

See Also:
Constant Field Values

INTERNAL_FRAME_LAST

public static final int INTERNAL_FRAME_LAST
The last number in the range of IDs used for internal frame events.

See Also:
Constant Field Values

INTERNAL_FRAME_OPENED

public static final int INTERNAL_FRAME_OPENED
The "window opened" event. This event is delivered only the first time the internal frame is made visible.

See Also:
JInternalFrame.show(), Constant Field Values

INTERNAL_FRAME_CLOSING

public static final int INTERNAL_FRAME_CLOSING
The "window is closing" event. This event is delivered when the user attempts to close the internal frame, such as by clicking the internal frame's close button, or when a program attempts to close the internal frame by invoking the setClosed method.

See Also:
JInternalFrame.setDefaultCloseOperation(int),
JInternalFrame.doDefaultCloseAction(),
JInternalFrame.setClosed(boolean),
Constant Field Values

INTERNAL_FRAME_CLOSED

public static final int INTERNAL_FRAME_CLOSED
The "window closed" event. This event is delivered after the internal frame has been closed as the result of a call to the setClosed or dispose method.

See Also:
JInternalFrame.setClosed(boolean), JInternalFrame.dispose(), Constant Field Values

INTERNAL_FRAME_ICONIFIED

public static final int INTERNAL_FRAME_ICONIFIED
The "window iconified" event. This event indicates that the internal frame was shrunk down to a small icon.

See Also:
JInternalFrame.setIcon(boolean), Constant Field Values

INTERNAL_FRAME_DEICONIFIED

public static final int INTERNAL_FRAME_DEICONIFIED
The "window deiconified" event type. This event indicates that the internal frame has been restored to its normal size.

See Also:
JInternalFrame.setIcon(boolean), Constant Field Values

INTERNAL_FRAME_ACTIVATED

public static final int INTERNAL_FRAME_ACTIVATED
The "window activated" event type. This event indicates that keystrokes and mouse clicks are directed towards this internal frame.

See Also:
JInternalFrame.show(), JInternalFrame.setSelected(boolean), Constant Field Values

INTERNAL_FRAME_DEACTIVATED

public static final int INTERNAL_FRAME_DEACTIVATED
The "window deactivated" event type. This event indicates that keystrokes and mouse clicks are no longer directed to the internal frame.

See Also:
JInternalFrame.setSelected(boolean), Constant Field Values
Constructor Detail

InternalFrameEvent

public InternalFrameEvent(JInternalFrame source,
                          int id)
Constructs an InternalFrameEvent object.

Parameters:
source - the JInternalFrame object that originated the event
id - an integer indicating the type of event
Method Detail

paramString

public String paramString()
Returns a parameter string identifying this event. This method is useful for event logging and for debugging.

Overrides:
paramString in class AWTEvent
Returns:
a string identifying the event and its attributes

getInternalFrame

public JInternalFrame getInternalFrame()
Returns the originator of the event.

Returns:
the JInternalFrame object that originated the event
Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InternalFrameListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface InternalFrameListener

All Superinterfaces:
EventListener
All Known Implementing Classes:
BasicInternalFrameUI.BasicInternalFrameListener, InternalFrameAdapter
public interface InternalFrameListener
extends EventListener

The listener interface for receiving internal frame events. This class is functionally equivalent to the WindowListener class in the AWT.

See How to Write an Internal Frame Listener in The Java Tutorial and The Java Class Libraries (update) for further documentation.

See Also:
WindowListener

Method Summary
void | internalFrameActivated(InternalFrameEvent e) Invoked when an internal frame is activated.
void | internalFrameClosed(InternalFrameEvent e) Invoked when an internal frame has been closed.
void | internalFrameClosing(InternalFrameEvent e) Invoked when an internal frame is in the process of being closed.
void | internalFrameDeactivated(InternalFrameEvent e) Invoked when an internal frame is de-activated.
void | internalFrameDeiconified(InternalFrameEvent e) Invoked when an internal frame is de-iconified.
void | internalFrameIconified(InternalFrameEvent e) Invoked when an internal frame is iconified.
void | internalFrameOpened(InternalFrameEvent e) Invoked when a internal frame has been opened.

Method Detail

internalFrameOpened

void internalFrameOpened(InternalFrameEvent e)
Invoked when a internal frame has been opened.

See Also:
JInternalFrame.show()

internalFrameClosing

void internalFrameClosing(InternalFrameEvent e)
Invoked when an internal frame is in the process of being closed. The close operation can be overridden at this point.

See Also:
JInternalFrame.setDefaultCloseOperation(int)

internalFrameClosed

void internalFrameClosed(InternalFrameEvent e)
Invoked when an internal frame has been closed.

See Also:
JInternalFrame.setClosed(boolean)

internalFrameIconified

void internalFrameIconified(InternalFrameEvent e)
Invoked when an internal frame is iconified.

See Also:
JInternalFrame.setIcon(boolean)

internalFrameDeiconified

void internalFrameDeiconified(InternalFrameEvent e)
Invoked when an internal frame is de-iconified.

See Also:
JInternalFrame.setIcon(boolean)

internalFrameActivated

void internalFrameActivated(InternalFrameEvent e)
Invoked when an internal frame is activated.

See Also:
JInternalFrame.setSelected(boolean)

internalFrameDeactivated

void internalFrameDeactivated(InternalFrameEvent e)
Invoked when an internal frame is de-activated.

See Also:
JInternalFrame.setSelected(boolean)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ListDataEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class ListDataEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.swing.event.ListDataEvent
All Implemented Interfaces:
Serializable
public class ListDataEvent
extends EventObject

Defines an event that encapsulates changes to a list.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
static int | CONTENTS_CHANGED Identifies one or more changes in the lists contents.
static int | INTERVAL_ADDED Identifies the addition of one or more contiguous items to the list
static int | INTERVAL_REMOVED Identifies the removal of one or more contiguous items from the list
Fields inherited from class java.util.EventObject
source
Constructor Summary
ListDataEvent(Object source, int type, int index0, int index1)
Constructs a ListDataEvent object.
Method Summary
int | getIndex0() Returns the lower index of the range.
int | getIndex1() Returns the upper index of the range.
int | getType() Returns the event type.
String | toString() Returns a string representation of this ListDataEvent.
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

CONTENTS_CHANGED

public static final int CONTENTS_CHANGED
Identifies one or more changes in the lists contents.

See Also:
Constant Field Values

INTERVAL_ADDED

public static final int INTERVAL_ADDED
Identifies the addition of one or more contiguous items to the list

See Also:
Constant Field Values

INTERVAL_REMOVED

public static final int INTERVAL_REMOVED
Identifies the removal of one or more contiguous items from the list

See Also:
Constant Field Values
Constructor Detail

ListDataEvent

public ListDataEvent(Object source,
                     int type,
                     int index0,
                     int index1)
Constructs a ListDataEvent object. If index0 is > index1, index0 and index1 will be swapped such that index0 will always be <= index1.="index1."
Parameters:
source - the source Object (typically this)
type - an int specifying CONTENTS_CHANGED, INTERVAL_ADDED, or INTERVAL_REMOVED
index0 - one end of the new interval
index1 - the other end of the new interval
Method Detail

getType

public int getType()
Returns the event type. The possible values are:
  • CONTENTS_CHANGED
  • INTERVAL_ADDED
  • INTERVAL_REMOVED

Returns:
an int representing the type value

getIndex0

public int getIndex0()
Returns the lower index of the range. For a single element, this value is the same as that returned by getIndex1().

Returns:
an int representing the lower index value

getIndex1

public int getIndex1()
Returns the upper index of the range. For a single element, this value is the same as that returned by getIndex0().

Returns:
an int representing the upper index value

toString

public String toString()
Returns a string representation of this ListDataEvent. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
toString in class EventObject
Returns:
a string representation of this ListDataEvent.
Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ListDataListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface ListDataListener

All Superinterfaces:
EventListener
All Known Implementing Classes:
BasicComboBoxUI.ListDataHandler, BasicComboPopup.ListDataHandler, BasicListUI.ListDataHandler, JComboBox, JList.AccessibleJList
public interface ListDataListener
extends EventListener

ListDataListener

Method Summary
void | contentsChanged(ListDataEvent e) Sent when the contents of the list has changed in a way that's too complex to characterize with the previous methods.
void | intervalAdded(ListDataEvent e) Sent after the indices in the index0,index1 interval have been inserted in the data model.
void | intervalRemoved(ListDataEvent e) Sent after the indices in the index0,index1 interval have been removed from the data model.

Method Detail

intervalAdded

void intervalAdded(ListDataEvent e)
Sent after the indices in the index0,index1 interval have been inserted in the data model. The new interval includes both index0 and index1.

Parameters:
e - a ListDataEvent encapsulating the event information

intervalRemoved

void intervalRemoved(ListDataEvent e)
Sent after the indices in the index0,index1 interval have been removed from the data model. The interval includes both index0 and index1.

Parameters:
e - a ListDataEvent encapsulating the event information

contentsChanged

void contentsChanged(ListDataEvent e)
Sent when the contents of the list has changed in a way that's too complex to characterize with the previous methods. For example, this is sent when an item has been replaced. Index0 and index1 bracket the change.

Parameters:
e - a ListDataEvent encapsulating the event information
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ListSelectionEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class ListSelectionEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.swing.event.ListSelectionEvent
All Implemented Interfaces:
Serializable
public class ListSelectionEvent
extends EventObject

An event that characterizes a change in selection. The change is limited to a a single inclusive interval. The selection of at least one index within the range will have changed. A decent ListSelectionModel implementation will keep the range as small as possible. ListSelectionListeners will generally query the source of the event for the new selected status of each potentially changed row.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
ListSelectionModel

Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
ListSelectionEvent(Object source, int firstIndex, int lastIndex, boolean isAdjusting)
Represents a change in selection status between firstIndex and lastIndex, inclusive.
Method Summary
int | getFirstIndex() Returns the index of the first row whose selection may have changed.
int | getLastIndex() Returns the index of the last row whose selection may have changed.
boolean | getValueIsAdjusting() Returns whether or not this is one in a series of multiple events, where changes are still being made.
String | toString() Returns a String that displays and identifies this object's properties.
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ListSelectionEvent

public ListSelectionEvent(Object source,
                          int firstIndex,
                          int lastIndex,
                          boolean isAdjusting)
Represents a change in selection status between firstIndex and lastIndex, inclusive. firstIndex is less than or equal to lastIndex. The selection of at least one index within the range will have changed.

Parameters:
firstIndex - the first index in the range, <= lastIndex
lastIndex - the last index in the range, >= firstIndex
isAdjusting - whether or not this is one in a series of multiple events, where changes are still being made
Method Detail

getFirstIndex

public int getFirstIndex()
Returns the index of the first row whose selection may have changed. getFirstIndex() &lt;= getLastIndex()

Returns:
the first row whose selection value may have changed, where zero is the first row

getLastIndex

public int getLastIndex()
Returns the index of the last row whose selection may have changed. getLastIndex() &gt;= getFirstIndex()

Returns:
the last row whose selection value may have changed, where zero is the first row

getValueIsAdjusting

public boolean getValueIsAdjusting()
Returns whether or not this is one in a series of multiple events, where changes are still being made. See the documentation for ListSelectionModel.setValueIsAdjusting(boolean) for more details on how this is used.

Returns:
true if this is one in a series of multiple events, where changes are still being made

toString

public String toString()
Returns a String that displays and identifies this object's properties.

Overrides:
toString in class EventObject
Returns:
a String representation of this object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ListSelectionListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface ListSelectionListener

All Superinterfaces:
EventListener
All Known Implementing Classes:
BasicComboPopup.ListSelectionHandler, BasicFileChooserUI.SelectionListener, BasicListUI.ListSelectionHandler, DefaultTableColumnModel, JList.AccessibleJList, JTable, JTable.AccessibleJTable
public interface ListSelectionListener
extends EventListener

The listener that's notified when a lists selection value changes.

See Also:
ListSelectionModel

Method Summary
 void valueChanged(ListSelectionEvent e)
Called whenever the value of the selection changes.

Method Detail

valueChanged

void valueChanged(ListSelectionEvent e)
Called whenever the value of the selection changes.

Parameters:
e - the event that characterizes the change.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MenuDragMouseEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class MenuDragMouseEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  java.awt.AWTEvent
            extended by  java.awt.event.ComponentEvent
                extended by  java.awt.event.InputEvent
                    extended by  java.awt.event.MouseEvent
                        extended by  javax.swing.event.MenuDragMouseEvent
All Implemented Interfaces:
Serializable
public class MenuDragMouseEvent
extends MouseEvent

MenuDragMouseEvent is used to notify interested parties that the menu element has received a MouseEvent forwarded to it under drag conditions.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class java.awt.event.MouseEvent
BUTTON1, BUTTON2, BUTTON3, MOUSE_CLICKED, MOUSE_DRAGGED, MOUSE_ENTERED, MOUSE_EXITED, MOUSE_FIRST, MOUSE_LAST, MOUSE_MOVED, MOUSE_PRESSED, MOUSE_RELEASED, MOUSE_WHEEL, NOBUTTON
Fields inherited from class java.awt.event.InputEvent
ALT_DOWN_MASK, ALT_GRAPH_DOWN_MASK, ALT_GRAPH_MASK, ALT_MASK, BUTTON1_DOWN_MASK, BUTTON1_MASK, BUTTON2_DOWN_MASK, BUTTON2_MASK, BUTTON3_DOWN_MASK, BUTTON3_MASK, CTRL_DOWN_MASK, CTRL_MASK, META_DOWN_MASK, META_MASK, SHIFT_DOWN_MASK, SHIFT_MASK
Fields inherited from class java.awt.event.ComponentEvent
COMPONENT_FIRST, COMPONENT_HIDDEN, COMPONENT_LAST, COMPONENT_MOVED, COMPONENT_RESIZED, COMPONENT_SHOWN
Fields inherited from class java.awt.AWTEvent
ACTION_EVENT_MASK, ADJUSTMENT_EVENT_MASK, COMPONENT_EVENT_MASK, consumed, CONTAINER_EVENT_MASK, FOCUS_EVENT_MASK, HIERARCHY_BOUNDS_EVENT_MASK, HIERARCHY_EVENT_MASK, id, INPUT_METHOD_EVENT_MASK, INVOCATION_EVENT_MASK, ITEM_EVENT_MASK, KEY_EVENT_MASK, MOUSE_EVENT_MASK, MOUSE_MOTION_EVENT_MASK, MOUSE_WHEEL_EVENT_MASK, PAINT_EVENT_MASK, RESERVED_ID_MAX, TEXT_EVENT_MASK, WINDOW_EVENT_MASK, WINDOW_FOCUS_EVENT_MASK, WINDOW_STATE_EVENT_MASK
Fields inherited from class java.util.EventObject
source
Constructor Summary
MenuDragMouseEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger, MenuElement[] p, MenuSelectionManager m)
Constructs a MenuDragMouseEvent object.
MenuDragMouseEvent(Component source, int id, long when, int modifiers, int x, int y, int xAbs, int yAbs, int clickCount, boolean popupTrigger, MenuElement[] p, MenuSelectionManager m)
Constructs a MenuDragMouseEvent object.
Method Summary
MenuSelectionManager | getMenuSelectionManager() Returns the current menu selection manager.
MenuElement[] | getPath() Returns the path to the selected menu item.
Methods inherited from class java.awt.event.MouseEvent
getButton, getClickCount, getLocationOnScreen, getMouseModifiersText, getPoint, getX, getXOnScreen, getY, getYOnScreen, isPopupTrigger, paramString, translatePoint
Methods inherited from class java.awt.event.InputEvent
consume, getModifiers, getModifiersEx, getModifiersExText, getWhen, isAltDown, isAltGraphDown, isConsumed, isControlDown, isMetaDown, isShiftDown
Methods inherited from class java.awt.event.ComponentEvent
getComponent
Methods inherited from class java.awt.AWTEvent
getID, setSource, toString
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MenuDragMouseEvent

public MenuDragMouseEvent(Component source,
                          int id,
                          long when,
                          int modifiers,
                          int x,
                          int y,
                          int clickCount,
                          boolean popupTrigger,
                          MenuElement[] p,
                          MenuSelectionManager m)
Constructs a MenuDragMouseEvent object.

Absolute coordinates xAbs and yAbs are set to source's location on screen plus relative coordinates x and y. xAbs and yAbs are set to zero if the source is not showing.

Parameters:
source - the Component that originated the event (typically this)
id - an int specifying the type of event, as defined in MouseEvent
when - a long identifying the time the event occurred
modifiers - an int specifying any modifier keys held down, as specified in InputEvent
x - an int specifying the horizontal position at which the event occurred, in pixels
y - an int specifying the vertical position at which the event occurred, in pixels
clickCount - an int specifying the number of mouse-clicks
popupTrigger - a boolean -- true if the event {should?/did?} trigger a popup
p - an array of MenuElement objects specifying a path to a menu item affected by the drag
m - a MenuSelectionManager object that handles selections
See Also:
MouseEvent.MouseEvent(java.awt.Component, int, long, int, int, int, int, int, int, boolean, int)

MenuDragMouseEvent

public MenuDragMouseEvent(Component source,
                          int id,
                          long when,
                          int modifiers,
                          int x,
                          int y,
                          int xAbs,
                          int yAbs,
                          int clickCount,
                          boolean popupTrigger,
                          MenuElement[] p,
                          MenuSelectionManager m)
Constructs a MenuDragMouseEvent object.

Even if inconsistent values for relative and absolute coordinates are passed to the constructor, the MenuDragMouseEvent instance is still created.

Parameters:
source - the Component that originated the event (typically this)
id - an int specifying the type of event, as defined in MouseEvent
when - a long identifying the time the event occurred
modifiers - an int specifying any modifier keys held down, as specified in InputEvent
x - an int specifying the horizontal position at which the event occurred, in pixels
y - an int specifying the vertical position at which the event occurred, in pixels
xAbs - an int specifying the horizontal absolute position at which the event occurred, in pixels
yAbs - an int specifying the vertical absolute position at which the event occurred, in pixels
clickCount - an int specifying the number of mouse-clicks
popupTrigger - a boolean -- true if the event {should?/did?} trigger a popup
p - an array of MenuElement objects specifying a path to a menu item affected by the drag
m - a MenuSelectionManager object that handles selections
Since:
1.6
See Also:
MouseEvent.MouseEvent(java.awt.Component, int, long, int, int, int, int, int, int, boolean, int)
Method Detail

getPath

public MenuElement[] getPath()
Returns the path to the selected menu item.

Returns:
an array of MenuElement objects representing the path value

getMenuSelectionManager

public MenuSelectionManager getMenuSelectionManager()
Returns the current menu selection manager.

Returns:
a MenuSelectionManager object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MenuDragMouseListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface MenuDragMouseListener

All Superinterfaces:
EventListener
public interface MenuDragMouseListener
extends EventListener

Defines a menu mouse-drag listener.

Method Summary
void | menuDragMouseDragged(MenuDragMouseEvent e) Invoked when the mouse is being dragged in a menu component's display area.
void | menuDragMouseEntered(MenuDragMouseEvent e) Invoked when the dragged mouse has entered a menu component's display area.
void | menuDragMouseExited(MenuDragMouseEvent e) Invoked when the dragged mouse has left a menu component's display area.
void | menuDragMouseReleased(MenuDragMouseEvent e) Invoked when a dragged mouse is release in a menu component's display area.

Method Detail

menuDragMouseEntered

void menuDragMouseEntered(MenuDragMouseEvent e)
Invoked when the dragged mouse has entered a menu component's display area.

Parameters:
e - a MenuDragMouseEvent object

menuDragMouseExited

void menuDragMouseExited(MenuDragMouseEvent e)
Invoked when the dragged mouse has left a menu component's display area.

Parameters:
e - a MenuDragMouseEvent object

menuDragMouseDragged

void menuDragMouseDragged(MenuDragMouseEvent e)
Invoked when the mouse is being dragged in a menu component's display area.

Parameters:
e - a MenuDragMouseEvent object

menuDragMouseReleased

void menuDragMouseReleased(MenuDragMouseEvent e)
Invoked when a dragged mouse is release in a menu component's display area.

Parameters:
e - a MenuDragMouseEvent object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MenuEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class MenuEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.swing.event.MenuEvent
All Implemented Interfaces:
Serializable
public class MenuEvent
extends EventObject

MenuEvent is used to notify interested parties that the menu which is the event source has been posted, selected, or canceled.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
MenuEvent(Object source)
Constructs a MenuEvent object.
Method Summary
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MenuEvent

public MenuEvent(Object source)
Constructs a MenuEvent object.

Parameters:
source - the Object that originated the event (typically this)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MenuKeyEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class MenuKeyEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  java.awt.AWTEvent
            extended by  java.awt.event.ComponentEvent
                extended by  java.awt.event.InputEvent
                    extended by  java.awt.event.KeyEvent
                        extended by  javax.swing.event.MenuKeyEvent
All Implemented Interfaces:
Serializable
public class MenuKeyEvent
extends KeyEvent

MenuKeyEvent is used to notify interested parties that the menu element has received a KeyEvent forwarded to it in a menu tree.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class java.awt.event.KeyEvent
CHAR_UNDEFINED, KEY_FIRST, KEY_LAST, KEY_LOCATION_LEFT, KEY_LOCATION_NUMPAD, KEY_LOCATION_RIGHT, KEY_LOCATION_STANDARD, KEY_LOCATION_UNKNOWN, KEY_PRESSED, KEY_RELEASED, KEY_TYPED, VK_0, VK_1, VK_2, VK_3, VK_4, VK_5, VK_6, VK_7, VK_8, VK_9, VK_A, VK_ACCEPT, VK_ADD, VK_AGAIN, VK_ALL_CANDIDATES, VK_ALPHANUMERIC, VK_ALT, VK_ALT_GRAPH, VK_AMPERSAND, VK_ASTERISK, VK_AT, VK_B, VK_BACK_QUOTE, VK_BACK_SLASH, VK_BACK_SPACE, VK_BEGIN, VK_BRACELEFT, VK_BRACERIGHT, VK_C, VK_CANCEL, VK_CAPS_LOCK, VK_CIRCUMFLEX, VK_CLEAR, VK_CLOSE_BRACKET, VK_CODE_INPUT, VK_COLON, VK_COMMA, VK_COMPOSE, VK_CONTEXT_MENU, VK_CONTROL, VK_CONVERT, VK_COPY, VK_CUT, VK_D, VK_DEAD_ABOVEDOT, VK_DEAD_ABOVERING, VK_DEAD_ACUTE, VK_DEAD_BREVE, VK_DEAD_CARON, VK_DEAD_CEDILLA, VK_DEAD_CIRCUMFLEX, VK_DEAD_DIAERESIS, VK_DEAD_DOUBLEACUTE, VK_DEAD_GRAVE, VK_DEAD_IOTA, VK_DEAD_MACRON, VK_DEAD_OGONEK, VK_DEAD_SEMIVOICED_SOUND, VK_DEAD_TILDE, VK_DEAD_VOICED_SOUND, VK_DECIMAL, VK_DELETE, VK_DIVIDE, VK_DOLLAR, VK_DOWN, VK_E, VK_END, VK_ENTER, VK_EQUALS, VK_ESCAPE, VK_EURO_SIGN, VK_EXCLAMATION_MARK, VK_F, VK_F1, VK_F10, VK_F11, VK_F12, VK_F13, VK_F14, VK_F15, VK_F16, VK_F17, VK_F18, VK_F19, VK_F2, VK_F20, VK_F21, VK_F22, VK_F23, VK_F24, VK_F3, VK_F4, VK_F5, VK_F6, VK_F7, VK_F8, VK_F9, VK_FINAL, VK_FIND, VK_FULL_WIDTH, VK_G, VK_GREATER, VK_H, VK_HALF_WIDTH, VK_HELP, VK_HIRAGANA, VK_HOME, VK_I, VK_INPUT_METHOD_ON_OFF, VK_INSERT, VK_INVERTED_EXCLAMATION_MARK, VK_J, VK_JAPANESE_HIRAGANA, VK_JAPANESE_KATAKANA, VK_JAPANESE_ROMAN, VK_K, VK_KANA, VK_KANA_LOCK, VK_KANJI, VK_KATAKANA, VK_KP_DOWN, VK_KP_LEFT, VK_KP_RIGHT, VK_KP_UP, VK_L, VK_LEFT, VK_LEFT_PARENTHESIS, VK_LESS, VK_M, VK_META, VK_MINUS, VK_MODECHANGE, VK_MULTIPLY, VK_N, VK_NONCONVERT, VK_NUM_LOCK, VK_NUMBER_SIGN, VK_NUMPAD0, VK_NUMPAD1, VK_NUMPAD2, VK_NUMPAD3, VK_NUMPAD4, VK_NUMPAD5, VK_NUMPAD6, VK_NUMPAD7, VK_NUMPAD8, VK_NUMPAD9, VK_O, VK_OPEN_BRACKET, VK_P, VK_PAGE_DOWN, VK_PAGE_UP, VK_PASTE, VK_PAUSE, VK_PERIOD, VK_PLUS, VK_PREVIOUS_CANDIDATE, VK_PRINTSCREEN, VK_PROPS, VK_Q, VK_QUOTE, VK_QUOTEDBL, VK_R, VK_RIGHT, VK_RIGHT_PARENTHESIS, VK_ROMAN_CHARACTERS, VK_S, VK_SCROLL_LOCK, VK_SEMICOLON, VK_SEPARATER, VK_SEPARATOR, VK_SHIFT, VK_SLASH, VK_SPACE, VK_STOP, VK_SUBTRACT, VK_T, VK_TAB, VK_U, VK_UNDEFINED, VK_UNDERSCORE, VK_UNDO, VK_UP, VK_V, VK_W, VK_WINDOWS, VK_X, VK_Y, VK_Z
Fields inherited from class java.awt.event.InputEvent
ALT_DOWN_MASK, ALT_GRAPH_DOWN_MASK, ALT_GRAPH_MASK, ALT_MASK, BUTTON1_DOWN_MASK, BUTTON1_MASK, BUTTON2_DOWN_MASK, BUTTON2_MASK, BUTTON3_DOWN_MASK, BUTTON3_MASK, CTRL_DOWN_MASK, CTRL_MASK, META_DOWN_MASK, META_MASK, SHIFT_DOWN_MASK, SHIFT_MASK
Fields inherited from class java.awt.event.ComponentEvent
COMPONENT_FIRST, COMPONENT_HIDDEN, COMPONENT_LAST, COMPONENT_MOVED, COMPONENT_RESIZED, COMPONENT_SHOWN
Fields inherited from class java.awt.AWTEvent
ACTION_EVENT_MASK, ADJUSTMENT_EVENT_MASK, COMPONENT_EVENT_MASK, consumed, CONTAINER_EVENT_MASK, FOCUS_EVENT_MASK, HIERARCHY_BOUNDS_EVENT_MASK, HIERARCHY_EVENT_MASK, id, INPUT_METHOD_EVENT_MASK, INVOCATION_EVENT_MASK, ITEM_EVENT_MASK, KEY_EVENT_MASK, MOUSE_EVENT_MASK, MOUSE_MOTION_EVENT_MASK, MOUSE_WHEEL_EVENT_MASK, PAINT_EVENT_MASK, RESERVED_ID_MAX, TEXT_EVENT_MASK, WINDOW_EVENT_MASK, WINDOW_FOCUS_EVENT_MASK, WINDOW_STATE_EVENT_MASK
Fields inherited from class java.util.EventObject
source
Constructor Summary
MenuKeyEvent(Component source, int id, long when, int modifiers, int keyCode, char keyChar, MenuElement[] p, MenuSelectionManager m)
Constructs a MenuKeyEvent object.
Method Summary
MenuSelectionManager | getMenuSelectionManager() Returns the current menu selection manager.
MenuElement[] | getPath() Returns the path to the menu item referenced by this event.
Methods inherited from class java.awt.event.KeyEvent
getKeyChar, getKeyCode, getKeyLocation, getKeyModifiersText, getKeyText, isActionKey, paramString, setKeyChar, setKeyCode, setModifiers
Methods inherited from class java.awt.event.InputEvent
consume, getModifiers, getModifiersEx, getModifiersExText, getWhen, isAltDown, isAltGraphDown, isConsumed, isControlDown, isMetaDown, isShiftDown
Methods inherited from class java.awt.event.ComponentEvent
getComponent
Methods inherited from class java.awt.AWTEvent
getID, setSource, toString
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MenuKeyEvent

public MenuKeyEvent(Component source,
                    int id,
                    long when,
                    int modifiers,
                    int keyCode,
                    char keyChar,
                    MenuElement[] p,
                    MenuSelectionManager m)
Constructs a MenuKeyEvent object.

Parameters:
source - the Component that originated the event (typically this)
id - an int specifying the type of event, as defined in KeyEvent
when - a long identifying the time the event occurred
modifiers - an int specifying any modifier keys held down, as specified in InputEvent
keyCode - an int specifying the specific key that was pressed
keyChar - a char specifying the key's character value, if any -- null if the key has no character value
p - an array of MenuElement objects specifying a path to a menu item affected by the drag
m - a MenuSelectionManager object that handles selections
Method Detail

getPath

public MenuElement[] getPath()
Returns the path to the menu item referenced by this event.

Returns:
an array of MenuElement objects representing the path value

getMenuSelectionManager

public MenuSelectionManager getMenuSelectionManager()
Returns the current menu selection manager.

Returns:
a MenuSelectionManager object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MenuKeyListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface MenuKeyListener

All Superinterfaces:
EventListener
public interface MenuKeyListener
extends EventListener

MenuKeyListener

Method Summary
void | menuKeyPressed(MenuKeyEvent e) Invoked when a key has been pressed.
void | menuKeyReleased(MenuKeyEvent e) Invoked when a key has been released.
void | menuKeyTyped(MenuKeyEvent e) Invoked when a key has been typed.

Method Detail

menuKeyTyped

void menuKeyTyped(MenuKeyEvent e)
Invoked when a key has been typed. This event occurs when a key press is followed by a key release.

menuKeyPressed

void menuKeyPressed(MenuKeyEvent e)
Invoked when a key has been pressed.

menuKeyReleased

void menuKeyReleased(MenuKeyEvent e)
Invoked when a key has been released.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MenuListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface MenuListener

All Superinterfaces:
EventListener
public interface MenuListener
extends EventListener

Defines a listener for menu events.

Method Summary
void | menuCanceled(MenuEvent e) Invoked when the menu is canceled.
void | menuDeselected(MenuEvent e) Invoked when the menu is deselected.
void | menuSelected(MenuEvent e) Invoked when a menu is selected.

Method Detail

menuSelected

void menuSelected(MenuEvent e)
Invoked when a menu is selected.

Parameters:
e - a MenuEvent object

menuDeselected

void menuDeselected(MenuEvent e)
Invoked when the menu is deselected.

Parameters:
e - a MenuEvent object

menuCanceled

void menuCanceled(MenuEvent e)
Invoked when the menu is canceled.

Parameters:
e - a MenuEvent object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MouseInputAdapter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class MouseInputAdapter

java.lang.Object
    extended by  java.awt.event.MouseAdapter
        extended by  javax.swing.event.MouseInputAdapter
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, EventListener, MouseInputListener
Direct Known Subclasses:
BasicDesktopIconUI.MouseInputHandler, BasicInternalFrameUI.BorderListener, BasicSliderUI.TrackListener
public abstract class MouseInputAdapter
extends MouseAdapter
implements MouseInputListener

An empty implementation of the MouseInputListener interface, provided as a convenience to simplify the task of creating listeners, by extending and implementing only the methods of interest. This class also provides an empty implementation of the MouseWheelListener interface, through its extension from AWT's MouseAdapter.

Constructor Summary
MouseInputAdapter()
Method Summary
Methods inherited from class java.awt.event.MouseAdapter
mouseClicked, mouseDragged, mouseEntered, mouseExited, mouseMoved, mousePressed, mouseReleased, mouseWheelMoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface java.awt.event.MouseListener
mouseClicked, mouseEntered, mouseExited, mousePressed, mouseReleased
Methods inherited from interface java.awt.event.MouseMotionListener
mouseDragged, mouseMoved

Constructor Detail

MouseInputAdapter

public MouseInputAdapter()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PopupMenuEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class PopupMenuEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.swing.event.PopupMenuEvent
All Implemented Interfaces:
Serializable
public class PopupMenuEvent
extends EventObject

PopupMenuEvent only contains the source of the event which is the JPoupMenu sending the event

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
PopupMenuEvent(Object source)
Constructs a PopupMenuEvent object.
Method Summary
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PopupMenuEvent

public PopupMenuEvent(Object source)
Constructs a PopupMenuEvent object.

Parameters:
source - the Object that originated the event (typically this)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PopupMenuListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface PopupMenuListener

All Superinterfaces:
EventListener
public interface PopupMenuListener
extends EventListener

A popup menu listener

Method Summary
void | popupMenuCanceled(PopupMenuEvent e) This method is called when the popup menu is canceled
void | popupMenuWillBecomeInvisible(PopupMenuEvent e) This method is called before the popup menu becomes invisible Note that a JPopupMenu can become invisible any time
void | popupMenuWillBecomeVisible(PopupMenuEvent e) This method is called before the popup menu becomes visible

Method Detail

popupMenuWillBecomeVisible

void popupMenuWillBecomeVisible(PopupMenuEvent e)
This method is called before the popup menu becomes visible

popupMenuWillBecomeInvisible

void popupMenuWillBecomeInvisible(PopupMenuEvent e)
This method is called before the popup menu becomes invisible Note that a JPopupMenu can become invisible any time

popupMenuCanceled

void popupMenuCanceled(PopupMenuEvent e)
This method is called when the popup menu is canceled

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RowSorterEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class RowSorterEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.swing.event.RowSorterEvent
All Implemented Interfaces:
Serializable
public class RowSorterEvent
extends EventObject

RowSorterEvent provides notification of changes to a RowSorter. Two types of notification are possible:

  • Type.SORT_ORDER_CHANGED: indicates the sort order has changed. This is typically followed by a notification of:
  • Type.SORTED: indicates the contents of the model have been transformed in some way. For example, the contents may have been sorted or filtered.

Since:
1.6
See Also:
RowSorter

Nested Class Summary
static class RowSorterEvent.Type
Enumeration of the types of RowSorterEvents.
Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
RowSorterEvent(RowSorter source)
Creates a RowSorterEvent of type SORT_ORDER_CHANGED.
RowSorterEvent(RowSorter source, RowSorterEvent.Type type, int[] previousRowIndexToModel)
Creates a RowSorterEvent.
Method Summary
int | convertPreviousRowIndexToModel(int index) Returns the location of index in terms of the model prior to the sort.
int | getPreviousRowCount() Returns the number of rows before the sort.
RowSorter | getSource() Returns the source of the event as a RowSorter.
RowSorterEvent.Type | getType() Returns the type of event.
Methods inherited from class java.util.EventObject
toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RowSorterEvent

public RowSorterEvent(RowSorter source)
Creates a RowSorterEvent of type SORT_ORDER_CHANGED.

Parameters:
source - the source of the change
Throws:
IllegalArgumentException - if source is null

RowSorterEvent

public RowSorterEvent(RowSorter source,
                      RowSorterEvent.Type type,
                      int[] previousRowIndexToModel)
Creates a RowSorterEvent.

Parameters:
source - the source of the change
type - the type of event
previousRowIndexToModel - the mapping from model indices to view indices prior to the sort, may be null
Throws:
IllegalArgumentException - if source or type is null
Method Detail

getSource

public RowSorter getSource()
Returns the source of the event as a RowSorter.

Overrides:
getSource in class EventObject
Returns:
the source of the event as a RowSorter

getType

public RowSorterEvent.Type getType()
Returns the type of event.

Returns:
the type of event

convertPreviousRowIndexToModel

public int convertPreviousRowIndexToModel(int index)
Returns the location of index in terms of the model prior to the sort. This method is only useful for events of type SORTED. This method will return -1 if the index is not valid, or the locations prior to the sort have not been provided.

Parameters:
index - the index in terms of the view
Returns:
the index in terms of the model prior to the sort, or -1 if the location is not valid or the mapping was not provided.

getPreviousRowCount

public int getPreviousRowCount()
Returns the number of rows before the sort. This method is only useful for events of type SORTED and if the last locations have not been provided will return 0.

Returns:
the number of rows in terms of the view prior to the sort
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RowSorterEvent.Type

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.swing.event
Enum RowSorterEvent.Type

java.lang.Object
    extended by  java.lang.Enum<RowSorterEvent.Type>
        extended by  javax.swing.event.RowSorterEvent.Type
All Implemented Interfaces:
Serializable, Comparable<RowSorterEvent.Type>
Enclosing class:
RowSorterEvent
public static enum RowSorterEvent.Type
extends Enum<RowSorterEvent.Type>

Enumeration of the types of RowSorterEvents.

Since:
1.6

Enum Constant Summary
SORT_ORDER_CHANGED
Indicates the sort order has changed.
SORTED
Indicates the contents have been newly sorted or transformed in some way.
Method Summary
static RowSorterEvent.Type | valueOf(String name) Returns the enum constant of this type with the specified name.
static RowSorterEvent.Type[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

SORT_ORDER_CHANGED

public static final RowSorterEvent.Type SORT_ORDER_CHANGED
Indicates the sort order has changed.

SORTED

public static final RowSorterEvent.Type SORTED
Indicates the contents have been newly sorted or transformed in some way.

Method Detail

values

public static RowSorterEvent.Type[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (RowSorterEvent.Type c : RowSorterEvent.Type.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static RowSorterEvent.Type valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


RowSorterListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface RowSorterListener

All Superinterfaces:
EventListener
All Known Implementing Classes:
JTable
public interface RowSorterListener
extends EventListener

RowSorterListeners are notified of changes to a RowSorter.

Since:
1.6
See Also:
RowSorter

Method Summary
 void sorterChanged(RowSorterEvent e)
Notification that the RowSorter has changed.

Method Detail

sorterChanged

void sorterChanged(RowSorterEvent e)
Notification that the RowSorter has changed. The event describes the scope of the change.

Parameters:
e - the event, will not be null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SwingPropertyChangeSupport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class SwingPropertyChangeSupport

java.lang.Object
    extended by  java.beans.PropertyChangeSupport
        extended by  javax.swing.event.SwingPropertyChangeSupport
All Implemented Interfaces:
Serializable
public final class SwingPropertyChangeSupport
extends PropertyChangeSupport

This subclass of java.beans.PropertyChangeSupport is almost identical in functionality. The only difference is if constructed with SwingPropertyChangeSupport(sourceBean, true) it ensures listeners are only ever notified on the Event Dispatch Thread.

Constructor Summary
SwingPropertyChangeSupport(Object sourceBean)
Constructs a SwingPropertyChangeSupport object.
SwingPropertyChangeSupport(Object sourceBean, boolean notifyOnEDT)
Constructs a SwingPropertyChangeSupport object.
Method Summary
void | firePropertyChange(PropertyChangeEvent evt) Fire an existing PropertyChangeEvent to any registered listeners.
boolean | isNotifyOnEDT() Returns notifyOnEDT property.
Methods inherited from class java.beans.PropertyChangeSupport
addPropertyChangeListener, addPropertyChangeListener, fireIndexedPropertyChange, fireIndexedPropertyChange, fireIndexedPropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getPropertyChangeListeners, getPropertyChangeListeners, hasListeners, removePropertyChangeListener, removePropertyChangeListener
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SwingPropertyChangeSupport

public SwingPropertyChangeSupport(Object sourceBean)
Constructs a SwingPropertyChangeSupport object.

Parameters:
sourceBean - The bean to be given as the source for any events.
Throws:
NullPointerException - if sourceBean is null

SwingPropertyChangeSupport

public SwingPropertyChangeSupport(Object sourceBean,
                                  boolean notifyOnEDT)
Constructs a SwingPropertyChangeSupport object.

Parameters:
sourceBean - the bean to be given as the source for any events
notifyOnEDT - whether to notify listeners on the Event Dispatch Thread only
Throws:
NullPointerException - if sourceBean is null
Since:
1.6
Method Detail

firePropertyChange

public void firePropertyChange(PropertyChangeEvent evt)
Fire an existing PropertyChangeEvent to any registered listeners. No event is fired if the given event's old and new values are equal and non-null.

If isNotifyOnEDT() is true and called off the Event Dispatch Thread this implementation uses SwingUtilities.invokeLater to send out the notification on the Event Dispatch Thread. This ensures listeners are only ever notified on the Event Dispatch Thread.

Overrides:
firePropertyChange in class PropertyChangeSupport
Parameters:
evt - The PropertyChangeEvent object.
Throws:
NullPointerException - if evt is null
Since:
1.6

isNotifyOnEDT

public final boolean isNotifyOnEDT()
Returns notifyOnEDT property.

Returns:
notifyOnEDT property
Since:
1.6
See Also:
SwingPropertyChangeSupport(Object sourceBean, boolean notifyOnEDT)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TableColumnModelEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class TableColumnModelEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.swing.event.TableColumnModelEvent
All Implemented Interfaces:
Serializable
public class TableColumnModelEvent
extends EventObject

TableColumnModelEvent is used to notify listeners that a table column model has changed, such as a column was added, removed, or moved.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
TableColumnModelListener

Field Summary
protected int | fromIndex The index of the column from where it was moved or removed
protected int | toIndex The index of the column to where it was moved or added
Fields inherited from class java.util.EventObject
source
Constructor Summary
TableColumnModelEvent(TableColumnModel source, int from, int to)
Constructs a TableColumnModelEvent object.
Method Summary
int | getFromIndex() Returns the fromIndex.
int | getToIndex() Returns the toIndex.
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

fromIndex

protected int fromIndex
The index of the column from where it was moved or removed

toIndex

protected int toIndex
The index of the column to where it was moved or added

Constructor Detail

TableColumnModelEvent

public TableColumnModelEvent(TableColumnModel source,
                             int from,
                             int to)
Constructs a TableColumnModelEvent object.

Parameters:
source - the TableColumnModel that originated the event
from - an int specifying the index from where the column was moved or removed
to - an int specifying the index to where the column was moved or added
See Also:
getFromIndex(), getToIndex()
Method Detail

getFromIndex

public int getFromIndex()
Returns the fromIndex. Valid for removed or moved events

getToIndex

public int getToIndex()
Returns the toIndex. Valid for add and moved events

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TableColumnModelListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface TableColumnModelListener

All Superinterfaces:
EventListener
All Known Implementing Classes:
JTable, JTable.AccessibleJTable, JTableHeader
public interface TableColumnModelListener
extends EventListener

TableColumnModelListener defines the interface for an object that listens to changes in a TableColumnModel.

See Also:
TableColumnModelEvent

Method Summary
void | columnAdded(TableColumnModelEvent e) Tells listeners that a column was added to the model.
void | columnMarginChanged(ChangeEvent e) Tells listeners that a column was moved due to a margin change.
void | columnMoved(TableColumnModelEvent e) Tells listeners that a column was repositioned.
void | columnRemoved(TableColumnModelEvent e) Tells listeners that a column was removed from the model.
void | columnSelectionChanged(ListSelectionEvent e) Tells listeners that the selection model of the TableColumnModel changed.

Method Detail

columnAdded

void columnAdded(TableColumnModelEvent e)
Tells listeners that a column was added to the model.

columnRemoved

void columnRemoved(TableColumnModelEvent e)
Tells listeners that a column was removed from the model.

columnMoved

void columnMoved(TableColumnModelEvent e)
Tells listeners that a column was repositioned.

columnMarginChanged

void columnMarginChanged(ChangeEvent e)
Tells listeners that a column was moved due to a margin change.

columnSelectionChanged

void columnSelectionChanged(ListSelectionEvent e)
Tells listeners that the selection model of the TableColumnModel changed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TableModelEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class TableModelEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.swing.event.TableModelEvent
All Implemented Interfaces:
Serializable
public class TableModelEvent
extends EventObject

TableModelEvent is used to notify listeners that a table model has changed. The model event describes changes to a TableModel and all references to rows and columns are in the co-ordinate system of the model. Depending on the parameters used in the constructors, the TableModelevent can be used to specify the following types of changes:

 TableModelEvent(source);              //  The data, ie. all rows changed
 TableModelEvent(source, HEADER_ROW);  //  Structure change, reallocate TableColumns
 TableModelEvent(source, 1);           //  Row 1 changed
 TableModelEvent(source, 3, 6);        //  Rows 3 to 6 inclusive changed
 TableModelEvent(source, 2, 2, 6);     //  Cell at (2, 6) changed
 TableModelEvent(source, 3, 6, ALL_COLUMNS, INSERT); // Rows (3, 6) were inserted
 TableModelEvent(source, 3, 6, ALL_COLUMNS, DELETE); // Rows (3, 6) were deleted
It is possible to use other combinations of the parameters, not all of them are meaningful. By subclassing, you can add other information, for example: whether the event WILL happen or DID happen. This makes the specification of rows in DELETE events more useful but has not been included in the swing package as the JTable only needs post-event notification.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
TableModel

Field Summary
static int | ALL_COLUMNS Specifies all columns in a row or rows.
protected int | column
static int | DELETE Identifies the removal of rows or columns.
protected int | firstRow
static int | HEADER_ROW Identifies the header row.
static int | INSERT Identifies the addtion of new rows or columns.
protected int | lastRow
protected int | type
static int | UPDATE Identifies a change to existing data.
Fields inherited from class java.util.EventObject
source
Constructor Summary
TableModelEvent(TableModel source)
All row data in the table has changed, listeners should discard any state that was based on the rows and requery the TableModel to get the new row count and all the appropriate values.
TableModelEvent(TableModel source, int row)
This row of data has been updated.
TableModelEvent(TableModel source, int firstRow, int lastRow)
The data in rows [firstRow, lastRow] have been updated.
TableModelEvent(TableModel source, int firstRow, int lastRow, int column)
The cells in column column in the range [firstRow, lastRow] have been updated.
TableModelEvent(TableModel source, int firstRow, int lastRow, int column, int type)
The cells from (firstRow, column) to (lastRow, column) have been changed.
Method Summary
int | getColumn() Returns the column for the event.
int | getFirstRow() Returns the first row that changed.
int | getLastRow() Returns the last row that changed.
int | getType() Returns the type of event - one of: INSERT, UPDATE and DELETE.
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

INSERT

public static final int INSERT
Identifies the addtion of new rows or columns.

See Also:
Constant Field Values

UPDATE

public static final int UPDATE
Identifies a change to existing data.

See Also:
Constant Field Values

DELETE

public static final int DELETE
Identifies the removal of rows or columns.

See Also:
Constant Field Values

HEADER_ROW

public static final int HEADER_ROW
Identifies the header row.

See Also:
Constant Field Values

ALL_COLUMNS

public static final int ALL_COLUMNS
Specifies all columns in a row or rows.

See Also:
Constant Field Values

type

protected int type

firstRow

protected int firstRow

lastRow

protected int lastRow

column

protected int column
Constructor Detail

TableModelEvent

public TableModelEvent(TableModel source)
All row data in the table has changed, listeners should discard any state that was based on the rows and requery the TableModel to get the new row count and all the appropriate values. The JTable will repaint the entire visible region on receiving this event, querying the model for the cell values that are visible. The structure of the table ie, the column names, types and order have not changed.

TableModelEvent

public TableModelEvent(TableModel source,
                       int row)
This row of data has been updated. To denote the arrival of a completely new table with a different structure use HEADER_ROW as the value for the row. When the JTable receives this event and its autoCreateColumnsFromModel flag is set it discards any TableColumns that it had and reallocates default ones in the order they appear in the model. This is the same as calling setModel(TableModel) on the JTable.

TableModelEvent

public TableModelEvent(TableModel source,
                       int firstRow,
                       int lastRow)
The data in rows [firstRow, lastRow] have been updated.

TableModelEvent

public TableModelEvent(TableModel source,
                       int firstRow,
                       int lastRow,
                       int column)
The cells in column column in the range [firstRow, lastRow] have been updated.

TableModelEvent

public TableModelEvent(TableModel source,
                       int firstRow,
                       int lastRow,
                       int column,
                       int type)
The cells from (firstRow, column) to (lastRow, column) have been changed. The column refers to the column index of the cell in the model's co-ordinate system. When column is ALL_COLUMNS, all cells in the specified range of rows are considered changed.

The type should be one of: INSERT, UPDATE and DELETE.

Method Detail

getFirstRow

public int getFirstRow()
Returns the first row that changed. HEADER_ROW means the meta data, ie. names, types and order of the columns.

getLastRow

public int getLastRow()
Returns the last row that changed.

getColumn

public int getColumn()
Returns the column for the event. If the return value is ALL_COLUMNS; it means every column in the specified rows changed.

getType

public int getType()
Returns the type of event - one of: INSERT, UPDATE and DELETE.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TableModelListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface TableModelListener

All Superinterfaces:
EventListener
All Known Implementing Classes:
JTable, JTable.AccessibleJTable
public interface TableModelListener
extends EventListener

TableModelListener defines the interface for an object that listens to changes in a TableModel.

See Also:
TableModel

Method Summary
 void tableChanged(TableModelEvent e)
This fine grain notification tells listeners the exact range of cells, rows, or columns that changed.

Method Detail

tableChanged

void tableChanged(TableModelEvent e)
This fine grain notification tells listeners the exact range of cells, rows, or columns that changed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TreeExpansionEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class TreeExpansionEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.swing.event.TreeExpansionEvent
All Implemented Interfaces:
Serializable
public class TreeExpansionEvent
extends EventObject

An event used to identify a single path in a tree. The source returned by getSource will be an instance of JTree.

For further documentation and examples see the following sections in The Java Tutorial: How to Write a Tree Expansion Listener and How to Write a Tree-Will-Expand Listener.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected  TreePath path
Path to the value this event represents.
Fields inherited from class java.util.EventObject
source
Constructor Summary
TreeExpansionEvent(Object source, TreePath path)
Constructs a TreeExpansionEvent object.
Method Summary
 TreePath getPath()
Returns the path to the value that has been expanded/collapsed.
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

path

protected TreePath path
Path to the value this event represents.

Constructor Detail

TreeExpansionEvent

public TreeExpansionEvent(Object source,
                          TreePath path)
Constructs a TreeExpansionEvent object.

Parameters:
source - the Object that originated the event (typically this)
path - a TreePath object identifying the newly expanded node
Method Detail

getPath

public TreePath getPath()
Returns the path to the value that has been expanded/collapsed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TreeExpansionListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface TreeExpansionListener

All Superinterfaces:
EventListener
All Known Implementing Classes:
BasicTreeUI.TreeExpansionHandler, JTree.AccessibleJTree
public interface TreeExpansionListener
extends EventListener

The listener that's notified when a tree expands or collapses a node. For further documentation and examples see How to Write a Tree Expansion Listener, a section in The Java Tutorial.

Method Summary
void | treeCollapsed(TreeExpansionEvent event) Called whenever an item in the tree has been collapsed.
void | treeExpanded(TreeExpansionEvent event) Called whenever an item in the tree has been expanded.

Method Detail

treeExpanded

void treeExpanded(TreeExpansionEvent event)
Called whenever an item in the tree has been expanded.

treeCollapsed

void treeCollapsed(TreeExpansionEvent event)
Called whenever an item in the tree has been collapsed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TreeModelEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class TreeModelEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.swing.event.TreeModelEvent
All Implemented Interfaces:
Serializable
public class TreeModelEvent
extends EventObject

Encapsulates information describing changes to a tree model, and used to notify tree model listeners of the change. For more information and examples see How to Write a Tree Model Listener, a section in The Java Tutorial.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected int[] | childIndices Indices identifying the position of where the children were.
protected Object[] | children Children that have been removed.
protected TreePath | path Path to the parent of the nodes that have changed.
Fields inherited from class java.util.EventObject
source
Constructor Summary
TreeModelEvent(Object source, Object[] path)
Used to create an event when the node structure has changed in some way, identifying the path to the root of a modified subtree as an array of Objects.
TreeModelEvent(Object source, Object[] path, int[] childIndices, Object[] children)
Used to create an event when nodes have been changed, inserted, or removed, identifying the path to the parent of the modified items as an array of Objects.
TreeModelEvent(Object source, TreePath path)
Used to create an event when the node structure has changed in some way, identifying the path to the root of the modified subtree as a TreePath object.
TreeModelEvent(Object source, TreePath path, int[] childIndices, Object[] children)
Used to create an event when nodes have been changed, inserted, or removed, identifying the path to the parent of the modified items as a TreePath object.
Method Summary
int[] | getChildIndices() Returns the values of the child indexes.
Object[] | getChildren() Returns the objects that are children of the node identified by getPath at the locations specified by getChildIndices.
Object[] | getPath() Convenience method to get the array of objects from the TreePath instance that this event wraps.
TreePath | getTreePath() For all events, except treeStructureChanged, returns the parent of the changed nodes.
String | toString() Returns a string that displays and identifies this object's properties.
Methods inherited from class java.util.EventObject
getSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

path

protected TreePath path
Path to the parent of the nodes that have changed.

childIndices

protected int[] childIndices
Indices identifying the position of where the children were.

children

protected Object[] children
Children that have been removed.

Constructor Detail

TreeModelEvent

public TreeModelEvent(Object source,
                      Object[] path,
                      int[] childIndices,
                      Object[] children)
Used to create an event when nodes have been changed, inserted, or removed, identifying the path to the parent of the modified items as an array of Objects. All of the modified objects are siblings which are direct descendents (not grandchildren) of the specified parent. The positions at which the inserts, deletes, or changes occurred are specified by an array of int. The indexes in that array must be in order, from lowest to highest.

For changes, the indexes in the model correspond exactly to the indexes of items currently displayed in the UI. As a result, it is not really critical if the indexes are not in their exact order. But after multiple inserts or deletes, the items currently in the UI no longer correspond to the items in the model. It is therefore critical to specify the indexes properly for inserts and deletes.

For inserts, the indexes represent the final state of the tree, after the inserts have occurred. Since the indexes must be specified in order, the most natural processing methodology is to do the inserts starting at the lowest index and working towards the highest. Accumulate a Vector of Integer objects that specify the insert-locations as you go, then convert the Vector to an array of int to create the event. When the postition-index equals zero, the node is inserted at the beginning of the list. When the position index equals the size of the list, the node is "inserted" at (appended to) the end of the list.

For deletes, the indexes represent the initial state of the tree, before the deletes have occurred. Since the indexes must be specified in order, the most natural processing methodology is to use a delete-counter. Start by initializing the counter to zero and start work through the list from lowest to higest. Every time you do a delete, add the current value of the delete-counter to the index-position where the delete occurred, and append the result to a Vector of delete-locations, using addElement(). Then increment the delete-counter. The index positions stored in the Vector therefore reflect the effects of all previous deletes, so they represent each object's position in the initial tree. (You could also start at the highest index and working back towards the lowest, accumulating a Vector of delete-locations as you go using the insertElementAt(Integer, 0).) However you produce the Vector of initial-positions, you then need to convert the Vector of Integer objects to an array of int to create the event.

Notes:

  • Like the insertNodeInto method in the DefaultTreeModel class, insertElementAt appends to the Vector when the index matches the size of the vector. So you can use insertElementAt(Integer, 0) even when the vector is empty.
      To create a node changed event for the root node, specify the parent and the child indices as null.

    Parameters:
    source - the Object responsible for generating the event (typically the creator of the event object passes this for its value)
    path - an array of Object identifying the path to the parent of the modified item(s), where the first element of the array is the Object stored at the root node and the last element is the Object stored at the parent node
    childIndices - an array of int that specifies the index values of the removed items. The indices must be in sorted order, from lowest to highest
    children - an array of Object containing the inserted, removed, or changed objects
    See Also:
    TreePath

TreeModelEvent

public TreeModelEvent(Object source,
                      TreePath path,
                      int[] childIndices,
                      Object[] children)
Used to create an event when nodes have been changed, inserted, or removed, identifying the path to the parent of the modified items as a TreePath object. For more information on how to specify the indexes and objects, see TreeModelEvent(Object,Object[],int[],Object[]).

Parameters:
source - the Object responsible for generating the event (typically the creator of the event object passes this for its value)
path - a TreePath object that identifies the path to the parent of the modified item(s)
childIndices - an array of int that specifies the index values of the modified items
children - an array of Object containing the inserted, removed, or changed objects
See Also:
TreeModelEvent(Object,Object[],int[],Object[])

TreeModelEvent

public TreeModelEvent(Object source,
                      Object[] path)
Used to create an event when the node structure has changed in some way, identifying the path to the root of a modified subtree as an array of Objects. A structure change event might involve nodes swapping position, for example, or it might encapsulate multiple inserts and deletes in the subtree stemming from the node, where the changes may have taken place at different levels of the subtree.
Note:
JTree collapses all nodes under the specified node, so that only its immediate children are visible.

Parameters:
source - the Object responsible for generating the event (typically the creator of the event object passes this for its value)
path - an array of Object identifying the path to the root of the modified subtree, where the first element of the array is the object stored at the root node and the last element is the object stored at the changed node
See Also:
TreePath

TreeModelEvent

public TreeModelEvent(Object source,
                      TreePath path)
Used to create an event when the node structure has changed in some way, identifying the path to the root of the modified subtree as a TreePath object. For more information on this event specification, see TreeModelEvent(Object,Object[]).

Parameters:
source - the Object responsible for generating the event (typically the creator of the event object passes this for its value)
path - a TreePath object that identifies the path to the change. In the DefaultTreeModel, this object contains an array of user-data objects, but a subclass of TreePath could use some totally different mechanism -- for example, a node ID number
See Also:
TreeModelEvent(Object,Object[])
Method Detail

getTreePath

public TreePath getTreePath()
For all events, except treeStructureChanged, returns the parent of the changed nodes. For treeStructureChanged events, returns the ancestor of the structure that has changed. This and getChildIndices are used to get a list of the effected nodes.

The one exception to this is a treeNodesChanged event that is to identify the root, in which case this will return the root and getChildIndices will return null.

Returns:
the TreePath used in identifying the changed nodes.
See Also:
TreePath.getLastPathComponent()

getPath

public Object[] getPath()
Convenience method to get the array of objects from the TreePath instance that this event wraps.

Returns:
an array of Objects, where the first Object is the one stored at the root and the last object is the one stored at the node identified by the path

getChildren

public Object[] getChildren()
Returns the objects that are children of the node identified by getPath at the locations specified by getChildIndices. If this is a removal event the returned objects are no longer children of the parent node.

Returns:
an array of Object containing the children specified by the event
See Also:
getPath(), getChildIndices()

getChildIndices

public int[] getChildIndices()
Returns the values of the child indexes. If this is a removal event the indexes point to locations in the initial list where items were removed. If it is an insert, the indices point to locations in the final list where the items were added. For node changes, the indices point to the locations of the modified nodes.

Returns:
an array of int containing index locations for the children specified by the event

toString

public String toString()
Returns a string that displays and identifies this object's properties.

Overrides:
toString in class EventObject
Returns:
a String representation of this object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TreeModelListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface TreeModelListener

All Superinterfaces:
EventListener
All Known Implementing Classes:
BasicTreeUI.TreeModelHandler, JTree.AccessibleJTree, JTree.TreeModelHandler
public interface TreeModelListener
extends EventListener

Defines the interface for an object that listens to changes in a TreeModel. For further information and examples see How to Write a Tree Model Listener, a section in The Java Tutorial.

Method Summary
void | treeNodesChanged(TreeModelEvent e) Invoked after a node (or a set of siblings) has changed in some way.
void | treeNodesInserted(TreeModelEvent e) Invoked after nodes have been inserted into the tree.
void | treeNodesRemoved(TreeModelEvent e) Invoked after nodes have been removed from the tree.
void | treeStructureChanged(TreeModelEvent e) Invoked after the tree has drastically changed structure from a given node down.

Method Detail

treeNodesChanged

void treeNodesChanged(TreeModelEvent e)

Invoked after a node (or a set of siblings) has changed in some way. The node(s) have not changed locations in the tree or altered their children arrays, but other attributes have changed and may affect presentation. Example: the name of a file has changed, but it is in the same location in the file system.

To indicate the root has changed, childIndices and children will be null.

Use e.getPath() to get the parent of the changed node(s). e.getChildIndices() returns the index(es) of the changed node(s).

treeNodesInserted

void treeNodesInserted(TreeModelEvent e)

Invoked after nodes have been inserted into the tree.

Use e.getPath() to get the parent of the new node(s). e.getChildIndices() returns the index(es) of the new node(s) in ascending order.

treeNodesRemoved

void treeNodesRemoved(TreeModelEvent e)

Invoked after nodes have been removed from the tree. Note that if a subtree is removed from the tree, this method may only be invoked once for the root of the removed subtree, not once for each individual set of siblings removed.

Use e.getPath() to get the former parent of the deleted node(s). e.getChildIndices() returns, in ascending order, the index(es) the node(s) had before being deleted.

treeStructureChanged

void treeStructureChanged(TreeModelEvent e)

Invoked after the tree has drastically changed structure from a given node down. If the path returned by e.getPath() is of length one and the first element does not identify the current root node the first element should become the new root of the tree.

Use e.getPath() to get the path to the node. e.getChildIndices() returns null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TreeSelectionEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class TreeSelectionEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.swing.event.TreeSelectionEvent
All Implemented Interfaces:
Serializable
public class TreeSelectionEvent
extends EventObject

An event that characterizes a change in the current selection. The change is based on any number of paths. TreeSelectionListeners will generally query the source of the event for the new selected status of each potentially changed row.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
TreeSelectionListener, TreeSelectionModel

Field Summary
protected boolean[] | areNew For each path identifies if that path is in fact new.
protected TreePath | newLeadSelectionPath leadSelectionPath after the paths changed, may be null.
protected TreePath | oldLeadSelectionPath leadSelectionPath before the paths changed, may be null.
protected TreePath[] | paths Paths this event represents.
Fields inherited from class java.util.EventObject
source
Constructor Summary
TreeSelectionEvent(Object source, TreePath[] paths, boolean[] areNew, TreePath oldLeadSelectionPath, TreePath newLeadSelectionPath)
Represents a change in the selection of a TreeSelectionModel.
TreeSelectionEvent(Object source, TreePath path, boolean isNew, TreePath oldLeadSelectionPath, TreePath newLeadSelectionPath)
Represents a change in the selection of a TreeSelectionModel.
Method Summary
Object | cloneWithSource(Object newSource) Returns a copy of the receiver, but with the source being newSource.
TreePath | getNewLeadSelectionPath() Returns the current lead path.
TreePath | getOldLeadSelectionPath() Returns the path that was previously the lead path.
TreePath | getPath() Returns the first path element.
TreePath[] | getPaths() Returns the paths that have been added or removed from the selection.
boolean | isAddedPath() Returns true if the first path element has been added to the selection, a return value of false means the first path has been removed from the selection.
boolean | isAddedPath(int index) Returns true if the path identified by index was added to the selection.
boolean | isAddedPath(TreePath path) Returns true if the path identified by path was added to the selection.
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

paths

protected TreePath[] paths
Paths this event represents.

areNew

protected boolean[] areNew
For each path identifies if that path is in fact new.

oldLeadSelectionPath

protected TreePath oldLeadSelectionPath
leadSelectionPath before the paths changed, may be null.

newLeadSelectionPath

protected TreePath newLeadSelectionPath
leadSelectionPath after the paths changed, may be null.

Constructor Detail

TreeSelectionEvent

public TreeSelectionEvent(Object source,
                          TreePath[] paths,
                          boolean[] areNew,
                          TreePath oldLeadSelectionPath,
                          TreePath newLeadSelectionPath)
Represents a change in the selection of a TreeSelectionModel. paths identifies the paths that have been either added or removed from the selection.

Parameters:
source - source of event
paths - the paths that have changed in the selection

TreeSelectionEvent

public TreeSelectionEvent(Object source,
                          TreePath path,
                          boolean isNew,
                          TreePath oldLeadSelectionPath,
                          TreePath newLeadSelectionPath)
Represents a change in the selection of a TreeSelectionModel. path identifies the path that have been either added or removed from the selection.

Parameters:
source - source of event
path - the path that has changed in the selection
isNew - whether or not the path is new to the selection, false means path was removed from the selection.
Method Detail

getPaths

public TreePath[] getPaths()
Returns the paths that have been added or removed from the selection.

getPath

public TreePath getPath()
Returns the first path element.

isAddedPath

public boolean isAddedPath()
Returns true if the first path element has been added to the selection, a return value of false means the first path has been removed from the selection.

isAddedPath

public boolean isAddedPath(TreePath path)
Returns true if the path identified by path was added to the selection. A return value of false means the path was in the selection but is no longer in the selection. This will raise if path is not one of the paths identified by this event.

isAddedPath

public boolean isAddedPath(int index)
Returns true if the path identified by index was added to the selection. A return value of false means the path was in the selection but is no longer in the selection. This will raise if index < 0 || >= getPaths.length.

Since:
1.3

getOldLeadSelectionPath

public TreePath getOldLeadSelectionPath()
Returns the path that was previously the lead path.

getNewLeadSelectionPath

public TreePath getNewLeadSelectionPath()
Returns the current lead path.

cloneWithSource

public Object cloneWithSource(Object newSource)
Returns a copy of the receiver, but with the source being newSource.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TreeSelectionListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface TreeSelectionListener

All Superinterfaces:
EventListener
All Known Implementing Classes:
BasicTreeUI.TreeSelectionHandler, DefaultTreeCellEditor, JTree.AccessibleJTree, JTree.TreeSelectionRedirector
public interface TreeSelectionListener
extends EventListener

The listener that's notified when the selection in a TreeSelectionModel changes. For more information and examples see How to Write a Tree Selection Listener, a section in The Java Tutorial.

See Also:
TreeSelectionModel, JTree

Method Summary
 void valueChanged(TreeSelectionEvent e)
Called whenever the value of the selection changes.

Method Detail

valueChanged

void valueChanged(TreeSelectionEvent e)
Called whenever the value of the selection changes.

Parameters:
e - the event that characterizes the change.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TreeWillExpandListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface TreeWillExpandListener

All Superinterfaces:
EventListener
public interface TreeWillExpandListener
extends EventListener

The listener that's notified when a tree expands or collapses a node. For further information and examples see How to Write a Tree-Will-Expand Listener, a section in The Java Tutorial.

Method Summary
void | treeWillCollapse(TreeExpansionEvent event) Invoked whenever a node in the tree is about to be collapsed.
void | treeWillExpand(TreeExpansionEvent event) Invoked whenever a node in the tree is about to be expanded.

Method Detail

treeWillExpand

void treeWillExpand(TreeExpansionEvent event)
                    throws ExpandVetoException
Invoked whenever a node in the tree is about to be expanded.

Throws:
ExpandVetoException

treeWillCollapse

void treeWillCollapse(TreeExpansionEvent event)
                      throws ExpandVetoException
Invoked whenever a node in the tree is about to be collapsed.

Throws:
ExpandVetoException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UndoableEditEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Class UndoableEditEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.swing.event.UndoableEditEvent
All Implemented Interfaces:
Serializable
public class UndoableEditEvent
extends EventObject

An event indicating that an operation which can be undone has occurred.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
UndoableEditEvent(Object source, UndoableEdit edit)
Constructs an UndoableEditEvent object.
Method Summary
 UndoableEdit getEdit()
Returns the edit value.
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UndoableEditEvent

public UndoableEditEvent(Object source,
                         UndoableEdit edit)
Constructs an UndoableEditEvent object.

Parameters:
source - the Object that originated the event (typically this)
edit - an UndoableEdit object
Method Detail

getEdit

public UndoableEdit getEdit()
Returns the edit value.

Returns:
the UndoableEdit object encapsulating the edit
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UndoableEditListener

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.event
Interface UndoableEditListener

All Superinterfaces:
EventListener
All Known Implementing Classes:
UndoManager
public interface UndoableEditListener
extends EventListener

Interface implemented by a class interested in hearing about undoable operations.

Method Summary
 void undoableEditHappened(UndoableEditEvent e)
An undoable edit happened

Method Detail

undoableEditHappened

void undoableEditHappened(UndoableEditEvent e)
An undoable edit happened

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


filechooser

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.swing.filechooser

Contains classes and interfaces used by the JFileChooser component.

See:
Description

Class Summary
FileFilter | FileFilter is an abstract class used by JFileChooser for filtering the set of files shown to the user.
FileNameExtensionFilter | An implementation of FileFilter that filters using a specified set of extensions.
FileSystemView | FileSystemView is JFileChooser's gateway to the file system.
FileView | FileView defines an abstract class that can be implemented to provide the filechooser with UI information for a File.

Package javax.swing.filechooser Description

Contains classes and interfaces used by the JFileChooser component.

Note: Most of the Swing API is not thread safe. For details, see Threads and Swing, a section in The Java Tutorial.

Related Documentation

This document forms the complete API specification. For overviews, tutorials, examples, guides, and tool documentation, please see:
  • How to Use File Choosers, a section in The Java Tutorial
  • Internationalization Documentation
  • Input Method Framework Documentation

Since:
1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.swing.filechooser Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.swing.filechooser

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.swing.filechooser.FileFilter
      • javax.swing.filechooser.FileNameExtensionFilter
    • javax.swing.filechooser.FileSystemView
    • javax.swing.filechooser.FileView
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.swing.filechooser

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.swing.filechooser

Packages that use javax.swing.filechooser
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.filechooser | Contains classes and interfaces used by the JFileChooser component.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Classes in javax.swing.filechooser used by javax.swing
FileFilter
FileFilter is an abstract class used by JFileChooser for filtering the set of files shown to the user.
FileSystemView
FileSystemView is JFileChooser's gateway to the file system.
FileView
FileView defines an abstract class that can be implemented to provide the filechooser with UI information for a File.

Classes in javax.swing.filechooser used by javax.swing.filechooser
FileFilter
FileFilter is an abstract class used by JFileChooser for filtering the set of files shown to the user.
FileSystemView
FileSystemView is JFileChooser's gateway to the file system.

Classes in javax.swing.filechooser used by javax.swing.plaf
FileFilter
FileFilter is an abstract class used by JFileChooser for filtering the set of files shown to the user.
FileView
FileView defines an abstract class that can be implemented to provide the filechooser with UI information for a File.

Classes in javax.swing.filechooser used by javax.swing.plaf.basic
FileFilter
FileFilter is an abstract class used by JFileChooser for filtering the set of files shown to the user.
FileView
FileView defines an abstract class that can be implemented to provide the filechooser with UI information for a File.

Classes in javax.swing.filechooser used by javax.swing.plaf.metal
FileFilter
FileFilter is an abstract class used by JFileChooser for filtering the set of files shown to the user.

Classes in javax.swing.filechooser used by javax.swing.plaf.multi
FileFilter
FileFilter is an abstract class used by JFileChooser for filtering the set of files shown to the user.
FileView
FileView defines an abstract class that can be implemented to provide the filechooser with UI information for a File.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.filechooser.FileFilter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.filechooser.FileFilter

Packages that use FileFilter
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.filechooser | Contains classes and interfaces used by the JFileChooser component.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of FileFilter in javax.swing

Methods in javax.swing that return FileFilter
FileFilter | JFileChooser.getAcceptAllFileFilter() Returns the AcceptAll file filter.
FileFilter[] | JFileChooser.getChoosableFileFilters() Gets the list of user choosable file filters.
FileFilter | JFileChooser.getFileFilter() Returns the currently selected file filter.

Methods in javax.swing with parameters of type FileFilter
void | JFileChooser.addChoosableFileFilter(FileFilter filter) Adds a filter to the list of user choosable file filters.
boolean | JFileChooser.removeChoosableFileFilter(FileFilter f) Removes a filter from the list of user choosable file filters.
void | JFileChooser.setFileFilter(FileFilter filter) Sets the current file filter.

Uses of FileFilter in javax.swing.filechooser

Subclasses of FileFilter in javax.swing.filechooser
 class FileNameExtensionFilter
An implementation of FileFilter that filters using a specified set of extensions.

Uses of FileFilter in javax.swing.plaf

Methods in javax.swing.plaf that return FileFilter
abstract  FileFilter FileChooserUI.getAcceptAllFileFilter(JFileChooser fc)

Uses of FileFilter in javax.swing.plaf.basic

Subclasses of FileFilter in javax.swing.plaf.basic
protected  class BasicFileChooserUI.AcceptAllFileFilter

Methods in javax.swing.plaf.basic that return FileFilter
 FileFilter BasicFileChooserUI.getAcceptAllFileFilter(JFileChooser fc)
Returns the default accept all file filter

Uses of FileFilter in javax.swing.plaf.metal

Fields in javax.swing.plaf.metal declared as FileFilter
protected  FileFilter[] MetalFileChooserUI.FilterComboBoxModel.filters

Uses of FileFilter in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi that return FileFilter
 FileFilter MultiFileChooserUI.getAcceptAllFileFilter(JFileChooser a)
Invokes the getAcceptAllFileFilter method on each UI handled by this object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.filechooser.FileNameExtensionFilter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.filechooser.FileNameExtensionFilter

No usage of javax.swing.filechooser.FileNameExtensionFilter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.filechooser.FileSystemView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.filechooser.FileSystemView

Packages that use FileSystemView
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.filechooser | Contains classes and interfaces used by the JFileChooser component.

Uses of FileSystemView in javax.swing

Methods in javax.swing that return FileSystemView
 FileSystemView JFileChooser.getFileSystemView()
Returns the file system view.

Methods in javax.swing with parameters of type FileSystemView
void | JFileChooser.setFileSystemView(FileSystemView fsv) Sets the file system view that the JFileChooser uses for accessing and creating file system resources, such as finding the floppy drive and getting a list of root drives.
protected void | JFileChooser.setup(FileSystemView view) Performs common constructor initialization and setup.

Constructors in javax.swing with parameters of type FileSystemView
JFileChooser(File currentDirectory, FileSystemView fsv)
Constructs a JFileChooser using the given current directory and FileSystemView.
JFileChooser(FileSystemView fsv)
Constructs a JFileChooser using the given FileSystemView.
JFileChooser(String currentDirectoryPath, FileSystemView fsv)
Constructs a JFileChooser using the given current directory path and FileSystemView.

Uses of FileSystemView in javax.swing.filechooser

Methods in javax.swing.filechooser that return FileSystemView
static FileSystemView FileSystemView.getFileSystemView()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.filechooser.FileView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.filechooser.FileView

Packages that use FileView
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of FileView in javax.swing

Methods in javax.swing that return FileView
 FileView JFileChooser.getFileView()
Returns the current file view.

Methods in javax.swing with parameters of type FileView
 void JFileChooser.setFileView(FileView fileView)
Sets the file view to used to retrieve UI information, such as the icon that represents a file or the type description of a file.

Uses of FileView in javax.swing.plaf

Methods in javax.swing.plaf that return FileView
abstract  FileView FileChooserUI.getFileView(JFileChooser fc)

Uses of FileView in javax.swing.plaf.basic

Subclasses of FileView in javax.swing.plaf.basic
protected  class BasicFileChooserUI.BasicFileView

Methods in javax.swing.plaf.basic that return FileView
 FileView BasicFileChooserUI.getFileView(JFileChooser fc)

Uses of FileView in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi that return FileView
 FileView MultiFileChooserUI.getFileView(JFileChooser a)
Invokes the getFileView method on each UI handled by this object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


FileFilter

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.filechooser
Class FileFilter

java.lang.Object
    extended by  javax.swing.filechooser.FileFilter
Direct Known Subclasses:
BasicFileChooserUI.AcceptAllFileFilter, FileNameExtensionFilter
public abstract class FileFilter
extends Object

FileFilter is an abstract class used by JFileChooser for filtering the set of files shown to the user. See FileNameExtensionFilter for an implementation that filters using the file name extension.

A FileFilter can be set on a JFileChooser to keep unwanted files from appearing in the directory listing. For an example implementation of a simple file filter, see yourJDK/demo/jfc/FileChooserDemo/ExampleFileFilter.java. For more information and examples see How to Use File Choosers, a section in The Java Tutorial.

See Also:
FileNameExtensionFilter, JFileChooser.setFileFilter(javax.swing.filechooser.FileFilter), JFileChooser.addChoosableFileFilter(javax.swing.filechooser.FileFilter)

Constructor Summary
FileFilter()
Method Summary
abstract boolean | accept(File f) Whether the given file is accepted by this filter.
abstract String | getDescription() The description of this filter.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FileFilter

public FileFilter()
Method Detail

accept

public abstract boolean accept(File f)
Whether the given file is accepted by this filter.

getDescription

public abstract String getDescription()
The description of this filter. For example: "JPG and GIF Images"

See Also:
FileView.getName(java.io.File)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


FileNameExtensionFilter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.filechooser
Class FileNameExtensionFilter

java.lang.Object
    extended by  javax.swing.filechooser.FileFilter
        extended by  javax.swing.filechooser.FileNameExtensionFilter

public final class FileNameExtensionFilter
extends FileFilter

An implementation of FileFilter that filters using a specified set of extensions. The extension for a file is the portion of the file name after the last ".". Files whose name does not contain a "." have no file name extension. File name extension comparisons are case insensitive.

The following example creates a FileNameExtensionFilter that will show jpg files:

 FileFilter filter = new FileNameExtensionFilter("JPEG file", "jpg", "jpeg");
 JFileChooser fileChooser = ...;
 fileChooser.addChoosableFileFilter(filter);

Since:
1.6
See Also:
FileFilter,
JFileChooser.setFileFilter(javax.swing.filechooser.FileFilter),
JFileChooser.addChoosableFileFilter(javax.swing.filechooser.FileFilter),
JFileChooser.getFileFilter()

Constructor Summary
FileNameExtensionFilter(String description, String... extensions)
Creates a FileNameExtensionFilter with the specified description and file name extensions.
Method Summary
boolean | accept(File f) Tests the specified file, returning true if the file is accepted, false otherwise.
String | getDescription() The description of this filter.
String[] | getExtensions() Returns the set of file name extensions files are tested against.
String | toString() Returns a string representation of the FileNameExtensionFilter.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

FileNameExtensionFilter

public FileNameExtensionFilter(String description,
                               String... extensions)
Creates a FileNameExtensionFilter with the specified description and file name extensions. The returned FileNameExtensionFilter will accept all directories and any file with a file name extension contained in extensions.

Parameters:
description - textual description for the filter, may be null
extensions - the accepted file name extensions
Throws:
IllegalArgumentException - if extensions is null, empty, contains null, or contains an empty string
See Also:
accept(java.io.File)
Method Detail

accept

public boolean accept(File f)
Tests the specified file, returning true if the file is accepted, false otherwise. True is returned if the extension matches one of the file name extensions of this FileFilter, or the file is a directory.

Specified by:
accept in class FileFilter
Parameters:
f - the File to test
Returns:
true if the file is to be accepted, false otherwise

getDescription

public String getDescription()
The description of this filter. For example: "JPG and GIF Images."

Specified by:
getDescription in class FileFilter
Returns:
the description of this filter
See Also:
FileView.getName(java.io.File)

getExtensions

public String[] getExtensions()
Returns the set of file name extensions files are tested against.

Returns:
the set of file name extensions files are tested against

toString

public String toString()
Returns a string representation of the FileNameExtensionFilter. This method is intended to be used for debugging purposes, and the content and format of the returned string may vary between implementations.

Overrides:
toString in class Object
Returns:
a string representation of this FileNameExtensionFilter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FileSystemView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.filechooser
Class FileSystemView

java.lang.Object
    extended by  javax.swing.filechooser.FileSystemView

public abstract class FileSystemView
extends Object

FileSystemView is JFileChooser's gateway to the file system. Since the JDK1.1 File API doesn't allow access to such information as root partitions, file type information, or hidden file bits, this class is designed to intuit as much OS-specific file system information as possible.

Java Licensees may want to provide a different implementation of FileSystemView to better handle a given operating system.

Constructor Summary
FileSystemView()
Method Summary
File | createFileObject(File dir, String filename) Returns a File object constructed in dir from the given filename.
File | createFileObject(String path) Returns a File object constructed from the given path string.
protected File | createFileSystemRoot(File f) Creates a new File object for f with correct behavior for a file system root directory.
abstract File | createNewFolder(File containingDir) Creates a new folder with a default folder name.
File | getChild(File parent, String fileName)
File | getDefaultDirectory() Return the user's default starting directory for the file chooser.
File[] | getFiles(File dir, boolean useFileHiding) Gets the list of shown (i.e.
static FileSystemView | getFileSystemView()
File | getHomeDirectory()
File | getParentDirectory(File dir) Returns the parent directory of dir.
File[] | getRoots() Returns all root partitions on this system.
String | getSystemDisplayName(File f) Name of a file, directory, or folder as it would be displayed in a system file browser.
Icon | getSystemIcon(File f) Icon for a file, directory, or folder as it would be displayed in a system file browser.
String | getSystemTypeDescription(File f) Type description for a file, directory, or folder as it would be displayed in a system file browser.
boolean | isComputerNode(File dir) Used by UI classes to decide whether to display a special icon for a computer node, e.g.
boolean | isDrive(File dir) Used by UI classes to decide whether to display a special icon for drives or partitions, e.g.
boolean | isFileSystem(File f) Checks if f represents a real directory or file as opposed to a special folder such as "Desktop".
boolean | isFileSystemRoot(File dir) Is dir the root of a tree in the file system, such as a drive or partition.
boolean | isFloppyDrive(File dir) Used by UI classes to decide whether to display a special icon for a floppy disk.
boolean | isHiddenFile(File f) Returns whether a file is hidden or not.
boolean | isParent(File folder, File file) On Windows, a file can appear in multiple folders, other than its parent directory in the filesystem.
boolean | isRoot(File f) Determines if the given file is a root in the navigatable tree(s).
Boolean | isTraversable(File f) Returns true if the file (directory) can be visited.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FileSystemView

public FileSystemView()
Method Detail

getFileSystemView

public static FileSystemView getFileSystemView()

isRoot

public boolean isRoot(File f)
Determines if the given file is a root in the navigatable tree(s). Examples: Windows 98 has one root, the Desktop folder. DOS has one root per drive letter, C:\, D:\, etc. Unix has one root, the "/" directory. The default implementation gets information from the ShellFolder class.

Parameters:
f - a File object representing a directory
Returns:
true if f is a root in the navigatable tree.
See Also:
isFileSystemRoot(java.io.File)

isTraversable

public Boolean isTraversable(File f)
Returns true if the file (directory) can be visited. Returns false if the directory cannot be traversed.

Parameters:
f - the File
Returns:
true if the file/directory can be traversed, otherwise false
Since:
1.4
See Also:
JFileChooser.isTraversable(java.io.File), FileView.isTraversable(java.io.File)

getSystemDisplayName

public String getSystemDisplayName(File f)
Name of a file, directory, or folder as it would be displayed in a system file browser. Example from Windows: the "M:\" directory displays as "CD-ROM (M:)" The default implementation gets information from the ShellFolder class.

Parameters:
f - a File object
Returns:
the file name as it would be displayed by a native file chooser
Since:
1.4
See Also:
JFileChooser.getName(java.io.File)

getSystemTypeDescription

public String getSystemTypeDescription(File f)
Type description for a file, directory, or folder as it would be displayed in a system file browser. Example from Windows: the "Desktop" folder is desribed as "Desktop". Override for platforms with native ShellFolder implementations.

Parameters:
f - a File object
Returns:
the file type description as it would be displayed by a native file chooser or null if no native information is available.
Since:
1.4
See Also:
JFileChooser.getTypeDescription(java.io.File)

getSystemIcon

public Icon getSystemIcon(File f)
Icon for a file, directory, or folder as it would be displayed in a system file browser. Example from Windows: the "M:\" directory displays a CD-ROM icon. The default implementation gets information from the ShellFolder class.

Parameters:
f - a File object
Returns:
an icon as it would be displayed by a native file chooser
Since:
1.4
See Also:
JFileChooser.getIcon(java.io.File)

isParent

public boolean isParent(File folder,
                        File file)
On Windows, a file can appear in multiple folders, other than its parent directory in the filesystem. Folder could for example be the "Desktop" folder which is not the same as file.getParentFile().

Parameters:
folder - a File object repesenting a directory or special folder
file - a File object
Returns:
true if folder is a directory or special folder and contains file.
Since:
1.4

getChild

public File getChild(File parent,
                     String fileName)
Parameters:
parent - a File object repesenting a directory or special folder
fileName - a name of a file or folder which exists in parent
Returns:
a File object. This is normally constructed with new File(parent, fileName) except when parent and child are both special folders, in which case the File is a wrapper containing a ShellFolder object.
Since:
1.4

isFileSystem

public boolean isFileSystem(File f)
Checks if f represents a real directory or file as opposed to a special folder such as "Desktop". Used by UI classes to decide if a folder is selectable when doing directory choosing.

Parameters:
f - a File object
Returns:
true if f is a real file or directory.
Since:
1.4

createNewFolder

public abstract File createNewFolder(File containingDir)
                              throws IOException
Creates a new folder with a default folder name.

Throws:
IOException

isHiddenFile

public boolean isHiddenFile(File f)
Returns whether a file is hidden or not.

isFileSystemRoot

public boolean isFileSystemRoot(File dir)
Is dir the root of a tree in the file system, such as a drive or partition. Example: Returns true for "C:\" on Windows 98.

Parameters:
dir - a File object representing a directory
Returns:
true if f is a root of a filesystem
Since:
1.4
See Also:
isRoot(java.io.File)

isDrive

public boolean isDrive(File dir)
Used by UI classes to decide whether to display a special icon for drives or partitions, e.g. a "hard disk" icon. The default implementation has no way of knowing, so always returns false.

Parameters:
dir - a directory
Returns:
false always
Since:
1.4

isFloppyDrive

public boolean isFloppyDrive(File dir)
Used by UI classes to decide whether to display a special icon for a floppy disk. Implies isDrive(dir). The default implementation has no way of knowing, so always returns false.

Parameters:
dir - a directory
Returns:
false always
Since:
1.4

isComputerNode

public boolean isComputerNode(File dir)
Used by UI classes to decide whether to display a special icon for a computer node, e.g. "My Computer" or a network server. The default implementation has no way of knowing, so always returns false.

Parameters:
dir - a directory
Returns:
false always
Since:
1.4

getRoots

public File[] getRoots()
Returns all root partitions on this system. For example, on Windows, this would be the "Desktop" folder, while on DOS this would be the A: through Z: drives.

getHomeDirectory

public File getHomeDirectory()

getDefaultDirectory

public File getDefaultDirectory()
Return the user's default starting directory for the file chooser.

Returns:
a File object representing the default starting folder
Since:
1.4

createFileObject

public File createFileObject(File dir,
                             String filename)
Returns a File object constructed in dir from the given filename.

createFileObject

public File createFileObject(String path)
Returns a File object constructed from the given path string.

getFiles

public File[] getFiles(File dir,
                       boolean useFileHiding)
Gets the list of shown (i.e. not hidden) files.

getParentDirectory

public File getParentDirectory(File dir)
Returns the parent directory of dir.

Parameters:
dir - the File being queried
Returns:
the parent directory of dir, or null if dir is null

createFileSystemRoot

protected File createFileSystemRoot(File f)
Creates a new File object for f with correct behavior for a file system root directory.

Parameters:
f - a File object representing a file system root directory, for example "/" on Unix or "C:\" on Windows.
Returns:
a new File object
Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FileView

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.filechooser
Class FileView

java.lang.Object
    extended by  javax.swing.filechooser.FileView
Direct Known Subclasses:
BasicFileChooserUI.BasicFileView
public abstract class FileView
extends Object

FileView defines an abstract class that can be implemented to provide the filechooser with UI information for a File. Each L&F JFileChooserUI object implements this class to pass back the correct icons and type descriptions specific to that L&F. For example, the Microsoft Windows L&F returns the generic Windows icons for directories and generic files. Additionally, you may want to provide your own FileView to JFileChooser to return different icons or additional information using JFileChooser.setFileView(javax.swing.filechooser.FileView).

JFileChooser first looks to see if there is a user defined FileView, if there is, it gets type information from there first. If FileView returns null for any method, JFileChooser then uses the L&F specific view to get the information. So, for example, if you provide a FileView class that returns an Icon for JPG files, and returns null icons for all other files, the UI's FileView will provide default icons for all other files.

For an example implementation of a simple file view, see yourJDK/demo/jfc/FileChooserDemo/ExampleFileView.java. For more information and examples see How to Use File Choosers, a section in The Java Tutorial.

See Also:
JFileChooser

Constructor Summary
FileView()
Method Summary
String | getDescription(File f) A human readable description of the file.
Icon | getIcon(File f) The icon that represents this file in the JFileChooser.
String | getName(File f) The name of the file.
String | getTypeDescription(File f) A human readable description of the type of the file.
Boolean | isTraversable(File f) Whether the directory is traversable or not.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FileView

public FileView()
Method Detail

getName

public String getName(File f)
The name of the file. Normally this would be simply f.getName().

getDescription

public String getDescription(File f)
A human readable description of the file. For example, a file named jag.jpg might have a description that read: "A JPEG image file of James Gosling's face".

getTypeDescription

public String getTypeDescription(File f)
A human readable description of the type of the file. For example, a jpg file might have a type description of: "A JPEG Compressed Image File"

getIcon

public Icon getIcon(File f)
The icon that represents this file in the JFileChooser.

isTraversable

public Boolean isTraversable(File f)
Whether the directory is traversable or not. This might be useful, for example, if you want a directory to represent a compound document and don't want the user to descend into it.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


FocusManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class FocusManager

java.lang.Object
    extended by  java.awt.KeyboardFocusManager
        extended by  java.awt.DefaultKeyboardFocusManager
            extended by  javax.swing.FocusManager
All Implemented Interfaces:
KeyEventDispatcher, KeyEventPostProcessor
Direct Known Subclasses:
DefaultFocusManager
public abstract class FocusManager
extends DefaultKeyboardFocusManager

This class has been obsoleted by the 1.4 focus APIs. While client code may still use this class, developers are strongly encouraged to use java.awt.KeyboardFocusManager and java.awt.DefaultKeyboardFocusManager instead.

Please see How to Use the Focus Subsystem, a section in The Java Tutorial, and the Focus Specification for more information.

See Also:
Focus Specification

Field Summary
static String FOCUS_MANAGER_CLASS_PROPERTY
This field is obsolete, and its use is discouraged since its specification is incompatible with the 1.4 focus APIs.
Fields inherited from class java.awt.KeyboardFocusManager
BACKWARD_TRAVERSAL_KEYS, DOWN_CYCLE_TRAVERSAL_KEYS, FORWARD_TRAVERSAL_KEYS, UP_CYCLE_TRAVERSAL_KEYS
Constructor Summary
FocusManager()
Method Summary
static void disableSwingFocusManager()
Deprecated. as of 1.4, replaced by KeyboardFocusManager.setDefaultFocusTraversalPolicy(FocusTraversalPolicy)
static FocusManager getCurrentManager()
Returns the current KeyboardFocusManager instance for the calling thread's context.
static boolean isFocusManagerEnabled()
Deprecated. As of 1.4, replaced by KeyboardFocusManager.getDefaultFocusTraversalPolicy()
static void setCurrentManager(FocusManager aFocusManager)
Sets the current KeyboardFocusManager instance for the calling thread's context.
Methods inherited from class java.awt.DefaultKeyboardFocusManager
dequeueKeyEvents, discardKeyEvents, dispatchEvent, dispatchKeyEvent, downFocusCycle, enqueueKeyEvents, focusNextComponent, focusPreviousComponent, postProcessKeyEvent, processKeyEvent, upFocusCycle
Methods inherited from class java.awt.KeyboardFocusManager
addKeyEventDispatcher, addKeyEventPostProcessor, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, clearGlobalFocusOwner, downFocusCycle, firePropertyChange, fireVetoableChange, focusNextComponent, focusPreviousComponent, getActiveWindow, getCurrentFocusCycleRoot, getCurrentKeyboardFocusManager, getDefaultFocusTraversalKeys, getDefaultFocusTraversalPolicy, getFocusedWindow, getFocusOwner, getGlobalActiveWindow, getGlobalCurrentFocusCycleRoot, getGlobalFocusedWindow, getGlobalFocusOwner, getGlobalPermanentFocusOwner, getKeyEventDispatchers, getKeyEventPostProcessors, getPermanentFocusOwner, getPropertyChangeListeners, getPropertyChangeListeners, getVetoableChangeListeners, getVetoableChangeListeners, redispatchEvent, removeKeyEventDispatcher, removeKeyEventPostProcessor, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, removeVetoableChangeListener, setCurrentKeyboardFocusManager, setDefaultFocusTraversalKeys, setDefaultFocusTraversalPolicy, setGlobalActiveWindow, setGlobalCurrentFocusCycleRoot, setGlobalFocusedWindow, setGlobalFocusOwner, setGlobalPermanentFocusOwner, upFocusCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FOCUS_MANAGER_CLASS_PROPERTY

public static final String FOCUS_MANAGER_CLASS_PROPERTY
This field is obsolete, and its use is discouraged since its specification is incompatible with the 1.4 focus APIs. The current FocusManager is no longer a property of the UI. Client code must query for the current FocusManager using KeyboardFocusManager.getCurrentKeyboardFocusManager(). See the Focus Specification for more information.

See Also:
KeyboardFocusManager.getCurrentKeyboardFocusManager(), Focus Specification, Constant Field Values
Constructor Detail

FocusManager

public FocusManager()
Method Detail

getCurrentManager

public static FocusManager getCurrentManager()
Returns the current KeyboardFocusManager instance for the calling thread's context.

Returns:
this thread's context's KeyboardFocusManager
See Also:
setCurrentManager(javax.swing.FocusManager)

setCurrentManager

public static void setCurrentManager(FocusManager aFocusManager)
                              throws SecurityException
Sets the current KeyboardFocusManager instance for the calling thread's context. If null is specified, then the current KeyboardFocusManager is replaced with a new instance of DefaultKeyboardFocusManager.

If a SecurityManager is installed, the calling thread must be granted the AWTPermission "replaceKeyboardFocusManager" in order to replace the the current KeyboardFocusManager. If this permission is not granted, this method will throw a SecurityException, and the current KeyboardFocusManager will be unchanged.

Parameters:
aFocusManager - the new KeyboardFocusManager for this thread's context
Throws:
SecurityException - if the calling thread does not have permission to replace the current KeyboardFocusManager
See Also:
getCurrentManager(), DefaultKeyboardFocusManager

disableSwingFocusManager

@Deprecated
public static void disableSwingFocusManager()
Deprecated. as of 1.4, replaced by KeyboardFocusManager.setDefaultFocusTraversalPolicy(FocusTraversalPolicy)

Changes the current KeyboardFocusManager's default FocusTraversalPolicy to DefaultFocusTraversalPolicy.

See Also:
DefaultFocusTraversalPolicy, KeyboardFocusManager.setDefaultFocusTraversalPolicy(java.awt.FocusTraversalPolicy)

isFocusManagerEnabled

@Deprecated
public static boolean isFocusManagerEnabled()
Deprecated. As of 1.4, replaced by KeyboardFocusManager.getDefaultFocusTraversalPolicy()

Returns whether the application has invoked disableSwingFocusManager().

See Also:
disableSwingFocusManager()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


GrayFilter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class GrayFilter

java.lang.Object
    extended by  java.awt.image.ImageFilter
        extended by  java.awt.image.RGBImageFilter
            extended by  javax.swing.GrayFilter
All Implemented Interfaces:
ImageConsumer, Cloneable
public class GrayFilter
extends RGBImageFilter

An image filter that "disables" an image by turning it into a grayscale image, and brightening the pixels in the image. Used by buttons to create an image for a disabled button.

Field Summary
Fields inherited from class java.awt.image.RGBImageFilter
canFilterIndexColorModel, newmodel, origmodel
Fields inherited from class java.awt.image.ImageFilter
consumer
Fields inherited from interface java.awt.image.ImageConsumer
COMPLETESCANLINES, IMAGEABORTED, IMAGEERROR, RANDOMPIXELORDER, SINGLEFRAME, SINGLEFRAMEDONE, SINGLEPASS, STATICIMAGEDONE, TOPDOWNLEFTRIGHT
Constructor Summary
GrayFilter(boolean b, int p)
Constructs a GrayFilter object that filters a color image to a grayscale image.
Method Summary
static Image | createDisabledImage(Image i) Creates a disabled image
int | filterRGB(int x, int y, int rgb) Overrides RGBImageFilter.filterRGB.
Methods inherited from class java.awt.image.RGBImageFilter
filterIndexColorModel, filterRGBPixels, setColorModel, setPixels, setPixels, substituteColorModel
Methods inherited from class java.awt.image.ImageFilter
clone, getFilterInstance, imageComplete, resendTopDownLeftRight, setDimensions, setHints, setProperties
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GrayFilter

public GrayFilter(boolean b,
                  int p)
Constructs a GrayFilter object that filters a color image to a grayscale image. Used by buttons to create disabled ("grayed out") button images.

Parameters:
b - a boolean -- true if the pixels should be brightened
p - an int in the range 0..100 that determines the percentage of gray, where 100 is the darkest gray, and 0 is the lightest
Method Detail

createDisabledImage

public static Image createDisabledImage(Image i)
Creates a disabled image

filterRGB

public int filterRGB(int x,
                     int y,
                     int rgb)
Overrides RGBImageFilter.filterRGB.

Specified by:
filterRGB in class RGBImageFilter
Parameters:
x - the X coordinate of the pixel
y - the Y coordinate of the pixel
rgb - the integer pixel representation in the default RGB color model
Returns:
a filtered pixel in the default RGB color model.
See Also:
ColorModel.getRGBdefault(), RGBImageFilter.filterRGBPixels(int, int, int, int, int[], int, int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


GroupLayout

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class GroupLayout

java.lang.Object
    extended by  javax.swing.GroupLayout
All Implemented Interfaces:
LayoutManager, LayoutManager2
public class GroupLayout
extends Object
implements LayoutManager2

GroupLayout is a LayoutManager that hierarchically groups components in order to position them in a Container. GroupLayout is intended for use by builders, but may be hand-coded as well. Grouping is done by instances of the Group class. GroupLayout supports two types of groups. A sequential group positions its child elements sequentially, one after another. A parallel group aligns its child elements in one of four ways.

Each group may contain any number of elements, where an element is a Group, Component, or gap. A gap can be thought of as an invisible component with a minimum, preferred and maximum size. In addition GroupLayout supports a preferred gap, whose value comes from LayoutStyle.

Elements are similar to a spring. Each element has a range as specified by a minimum, preferred and maximum. Gaps have either a developer-specified range, or a range determined by LayoutStyle. The range for Components is determined from the Component's getMinimumSize, getPreferredSize and getMaximumSize methods. In addition, when adding Components you may specify a particular range to use instead of that from the component. The range for a Group is determined by the type of group. A ParallelGroup's range is the maximum of the ranges of its elements. A SequentialGroup's range is the sum of the ranges of its elements.

GroupLayout treats each axis independently. That is, there is a group representing the horizontal axis, and a group representing the vertical axis. The horizontal group is responsible for determining the minimum, preferred and maximum size along the horizontal axis as well as setting the x and width of the components contained in it. The vertical group is responsible for determining the minimum, preferred and maximum size along the vertical axis as well as setting the y and height of the components contained in it. Each Component must exist in both a horizontal and vertical group, otherwise an IllegalStateException is thrown during layout, or when the minimum, preferred or maximum size is requested.

The following diagram shows a sequential group along the horizontal axis. The sequential group contains three components. A parallel group was used along the vertical axis.

To reinforce that each axis is treated independently the diagram shows the range of each group and element along each axis. The range of each component has been projected onto the axes, and the groups are rendered in blue (horizontal) and red (vertical). For readability there is a gap between each of the elements in the sequential group.

The sequential group along the horizontal axis is rendered as a solid blue line. Notice the sequential group is the sum of the children elements it contains.

Along the vertical axis the parallel group is the maximum of the height of each of the components. As all three components have the same height, the parallel group has the same height.

The following diagram shows the same three components, but with the parallel group along the horizontal axis and the sequential group along the vertical axis.

As c1 is the largest of the three components, the parallel group is sized to c1. As c2 and c3 are smaller than c1 they are aligned based on the alignment specified for the component (if specified) or the default alignment of the parallel group. In the diagram c2 and c3 were created with an alignment of LEADING. If the component orientation were right-to-left then c2 and c3 would be positioned on the opposite side.

The following diagram shows a sequential group along both the horizontal and vertical axis.

GroupLayout provides the ability to insert gaps between Components. The size of the gap is determined by an instance of LayoutStyle. This may be turned on using the setAutoCreateGaps method. Similarly, you may use the setAutoCreateContainerGaps method to insert gaps between components that touch the edge of the parent container and the container.

The following builds a panel consisting of two labels in one column, followed by two textfields in the next column:

   JComponent panel = ...;
   GroupLayout layout = new GroupLayout(panel);
   panel.setLayout(layout);

   // Turn on automatically adding gaps between components
   layout.setAutoCreateGaps(true);

   // Turn on automatically creating gaps between components that touch
   // the edge of the container and the container.
   layout.setAutoCreateContainerGaps(true);

   // Create a sequential group for the horizontal axis.

   GroupLayout.SequentialGroup hGroup = layout.createSequentialGroup();

   // The sequential group in turn contains two parallel groups.
   // One parallel group contains the labels, the other the text fields.
   // Putting the labels in a parallel group along the horizontal axis
   // positions them at the same x location.
   //
   // Variable indentation is used to reinforce the level of grouping.
   hGroup.addGroup(layout.createParallelGroup().
            addComponent(label1).addComponent(label2));
   hGroup.addGroup(layout.createParallelGroup().
            addComponent(tf1).addComponent(tf2));
   layout.setHorizontalGroup(hGroup);

   // Create a sequential group for the vertical axis.
   GroupLayout.SequentialGroup vGroup = layout.createSequentialGroup();

   // The sequential group contains two parallel groups that align
   // the contents along the baseline. The first parallel group contains
   // the first label and text field, and the second parallel group contains
   // the second label and text field. By using a sequential group
   // the labels and text fields are positioned vertically after one another.
   vGroup.addGroup(layout.createParallelGroup(Alignment.BASELINE).
            addComponent(label1).addComponent(tf1));
   vGroup.addGroup(layout.createParallelGroup(Alignment.BASELINE).
            addComponent(label2).addComponent(tf2));
   layout.setVerticalGroup(vGroup);

When run the following is produced.

This layout consists of the following.

  • The horizontal axis consists of a sequential group containing two parallel groups. The first parallel group contains the labels, and the second parallel group contains the text fields.
  • The vertical axis consists of a sequential group containing two parallel groups. The parallel groups are configured to align their components along the baseline. The first parallel group contains the first label and first text field, and the second group consists of the second label and second text field.
There are a couple of things to notice in this code:
  • You need not explicitly add the components to the container; this is indirectly done by using one of the add methods of Group.
  • The various add methods return the caller. This allows for easy chaining of invocations. For example, group.addComponent(label1).addComponent(label2); is equivalent to group.addComponent(label1); group.addComponent(label2);.
  • There are no public constructors for Groups; instead use the create methods of GroupLayout.

Since:
1.6

Nested Class Summary
static class | GroupLayout.Alignment Enumeration of the possible ways ParallelGroup can align its children.
class | GroupLayout.Group Group provides the basis for the two types of operations supported by GroupLayout: laying out components one after another (SequentialGroup) or aligned (ParallelGroup).
class | GroupLayout.ParallelGroup A Group that aligns and sizes it's children.
class | GroupLayout.SequentialGroup A Group that positions and sizes its elements sequentially, one after another.
Field Summary
static int | DEFAULT_SIZE Indicates the size from the component or gap should be used for a particular range value.
static int | PREFERRED_SIZE Indicates the preferred size from the component or gap should be used for a particular range value.
Constructor Summary
GroupLayout(Container host)
Creates a GroupLayout for the specified Container.
Method Summary
void | addLayoutComponent(Component component, Object constraints) Notification that a Component has been added to the parent container.
void | addLayoutComponent(String name, Component component) Notification that a Component has been added to the parent container.
GroupLayout.ParallelGroup | createBaselineGroup(boolean resizable, boolean anchorBaselineToTop) Creates and returns a ParallelGroup that aligns it's elements along the baseline.
GroupLayout.ParallelGroup | createParallelGroup() Creates and returns a ParallelGroup with an alignment of Alignment.LEADING.
GroupLayout.ParallelGroup | createParallelGroup(GroupLayout.Alignment alignment) Creates and returns a ParallelGroup with the specified alignment.
GroupLayout.ParallelGroup | createParallelGroup(GroupLayout.Alignment alignment, boolean resizable) Creates and returns a ParallelGroup with the specified alignment and resize behavior.
GroupLayout.SequentialGroup | createSequentialGroup() Creates and returns a SequentialGroup.
boolean | getAutoCreateContainerGaps() Returns true if gaps between the container and components that border the container are automatically created.
boolean | getAutoCreateGaps() Returns true if gaps between components are automatically created.
boolean | getHonorsVisibility() Returns whether component visiblity is considered when sizing and positioning components.
float | getLayoutAlignmentX(Container parent) Returns the alignment along the x axis.
float | getLayoutAlignmentY(Container parent) Returns the alignment along the y axis.
LayoutStyle | getLayoutStyle() Returns the LayoutStyle used for calculating the preferred gap between components.
void | invalidateLayout(Container parent) Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.
void | layoutContainer(Container parent) Lays out the specified container.
void | linkSize(Component... components) Forces the specified components to have the same size regardless of their preferred, minimum or maximum sizes.
void | linkSize(int axis, Component... components) Forces the specified components to have the same size along the specified axis regardless of their preferred, minimum or maximum sizes.
Dimension | maximumLayoutSize(Container parent) Returns the maximum size for the specified container.
Dimension | minimumLayoutSize(Container parent) Returns the minimum size for the specified container.
Dimension | preferredLayoutSize(Container parent) Returns the preferred size for the specified container.
void | removeLayoutComponent(Component component) Notification that a Component has been removed from the parent container.
void | replace(Component existingComponent, Component newComponent) Replaces an existing component with a new one.
void | setAutoCreateContainerGaps(boolean autoCreateContainerPadding) Sets whether a gap between the container and components that touch the border of the container should automatically be created.
void | setAutoCreateGaps(boolean autoCreatePadding) Sets whether a gap between components should automatically be created.
void | setHonorsVisibility(boolean honorsVisibility) Sets whether component visiblity is considered when sizing and positioning components.
void | setHonorsVisibility(Component component, Boolean honorsVisibility) Sets whether the component's visiblity is considered for sizing and positioning.
void | setHorizontalGroup(GroupLayout.Group group) Sets the Group that positions and sizes components along the horizontal axis.
void | setLayoutStyle(LayoutStyle layoutStyle) Sets the LayoutStyle used to calculate the preferred gaps between components.
void | setVerticalGroup(GroupLayout.Group group) Sets the Group that positions and sizes components along the vertical axis.
String | toString() Returns a string representation of this GroupLayout.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_SIZE

public static final int DEFAULT_SIZE
Indicates the size from the component or gap should be used for a particular range value.

See Also:
GroupLayout.Group, Constant Field Values

PREFERRED_SIZE

public static final int PREFERRED_SIZE
Indicates the preferred size from the component or gap should be used for a particular range value.

See Also:
GroupLayout.Group, Constant Field Values
Constructor Detail

GroupLayout

public GroupLayout(Container host)
Creates a GroupLayout for the specified Container.

Parameters:
host - the Container the GroupLayout is the LayoutManager for
Throws:
IllegalArgumentException - if host is null
Method Detail

setHonorsVisibility

public void setHonorsVisibility(boolean honorsVisibility)
Sets whether component visiblity is considered when sizing and positioning components. A value of true indicates that non-visible components should not be treated as part of the layout. A value of false indicates that components should be positioned and sized regardless of visibility.

A value of false is useful when the visibility of components is dynamically adjusted and you don't want surrounding components and the sizing to change.

The specified value is used for components that do not have an explicit visibility specified.

The default is true.

Parameters:
honorsVisibility - whether component visiblity is considered when sizing and positioning components
See Also:
setHonorsVisibility(Component,Boolean)

getHonorsVisibility

public boolean getHonorsVisibility()
Returns whether component visiblity is considered when sizing and positioning components.

Returns:
whether component visiblity is considered when sizing and positioning components

setHonorsVisibility

public void setHonorsVisibility(Component component,
                                Boolean honorsVisibility)
Sets whether the component's visiblity is considered for sizing and positioning. A value of Boolean.TRUE indicates that if component is not visible it should not be treated as part of the layout. A value of false indicates that component is positioned and sized regardless of it's visibility. A value of null indicates the value specified by the single argument method setHonorsVisibility should be used.

If component is not a child of the Container this GroupLayout is managine, it will be added to the Container.

Parameters:
component - the component
honorsVisibility - whether component's visiblity should be considered for sizing and positioning
Throws:
IllegalArgumentException - if component is null
See Also:
setHonorsVisibility(Component,Boolean)

setAutoCreateGaps

public void setAutoCreateGaps(boolean autoCreatePadding)
Sets whether a gap between components should automatically be created. For example, if this is true and you add two components to a SequentialGroup a gap between the two components is automatically be created. The default is false.

Parameters:
autoCreatePadding - whether a gap between components is automatically created

getAutoCreateGaps

public boolean getAutoCreateGaps()
Returns true if gaps between components are automatically created.

Returns:
true if gaps between components are automatically created

setAutoCreateContainerGaps

public void setAutoCreateContainerGaps(boolean autoCreateContainerPadding)
Sets whether a gap between the container and components that touch the border of the container should automatically be created. The default is false.

Parameters:
autoCreateContainerPadding - whether a gap between the container and components that touch the border of the container should automatically be created

getAutoCreateContainerGaps

public boolean getAutoCreateContainerGaps()
Returns true if gaps between the container and components that border the container are automatically created.

Returns:
true if gaps between the container and components that border the container are automatically created

setHorizontalGroup

public void setHorizontalGroup(GroupLayout.Group group)
Sets the Group that positions and sizes components along the horizontal axis.

Parameters:
group - the Group that positions and sizes components along the horizontal axis
Throws:
IllegalArgumentException - if group is null

setVerticalGroup

public void setVerticalGroup(GroupLayout.Group group)
Sets the Group that positions and sizes components along the vertical axis.

Parameters:
group - the Group that positions and sizes components along the vertical axis
Throws:
IllegalArgumentException - if group is null

createSequentialGroup

public GroupLayout.SequentialGroup createSequentialGroup()
Creates and returns a SequentialGroup.

Returns:
a new SequentialGroup

createParallelGroup

public GroupLayout.ParallelGroup createParallelGroup()
Creates and returns a ParallelGroup with an alignment of Alignment.LEADING. This is a cover method for the more general createParallelGroup(Alignment) method.

Returns:
a new ParallelGroup
See Also:
createParallelGroup(Alignment)

createParallelGroup

public GroupLayout.ParallelGroup createParallelGroup(GroupLayout.Alignment alignment)
Creates and returns a ParallelGroup with the specified alignment. This is a cover method for the more general createParallelGroup(Alignment,boolean) method with true supplied for the second argument.

Parameters:
alignment - the alignment for the elements of the group
Returns:
a new ParallelGroup
Throws:
IllegalArgumentException - if alignment is null
See Also:
createBaselineGroup(boolean, boolean), GroupLayout.ParallelGroup

createParallelGroup

public GroupLayout.ParallelGroup createParallelGroup(GroupLayout.Alignment alignment,
                                                     boolean resizable)
Creates and returns a ParallelGroup with the specified alignment and resize behavior. The alignment argument specifies how children elements are positioned that do not fill the group. For example, if a ParallelGroup with an alignment of TRAILING is given 100 and a child only needs 50, the child is positioned at the position 50 (with a component orientation of left-to-right).

Baseline alignment is only useful when used along the vertical axis. A ParallelGroup created with a baseline alignment along the horizontal axis is treated as LEADING.

Refer to ParallelGroup for details on the behavior of baseline groups.

Parameters:
alignment - the alignment for the elements of the group
resizable - true if the group is resizable; if the group is not resizable the preferred size is used for the minimum and maximum size of the group
Returns:
a new ParallelGroup
Throws:
IllegalArgumentException - if alignment is null
See Also:
createBaselineGroup(boolean, boolean), GroupLayout.ParallelGroup

createBaselineGroup

public GroupLayout.ParallelGroup createBaselineGroup(boolean resizable,
                                                     boolean anchorBaselineToTop)
Creates and returns a ParallelGroup that aligns it's elements along the baseline.

Parameters:
resizable - whether the group is resizable
anchorBaselineToTop - whether the baseline is anchored to the top or bottom of the group
See Also:
createBaselineGroup(boolean, boolean), GroupLayout.ParallelGroup

linkSize

public void linkSize(Component... components)
Forces the specified components to have the same size regardless of their preferred, minimum or maximum sizes. Components that are linked are given the maximum of the preferred size of each of the linked components. For example, if you link two components with a preferred width of 10 and 20, both components are given a width of 20.

This can be used multiple times to force any number of components to share the same size.

Linked Components are not be resizable.

Parameters:
components - the Components that are to have the same size
Throws:
IllegalArgumentException - if components is null, or contains null
See Also:
linkSize(int,Component[])

linkSize

public void linkSize(int axis,
                     Component... components)
Forces the specified components to have the same size along the specified axis regardless of their preferred, minimum or maximum sizes. Components that are linked are given the maximum of the preferred size of each of the linked components. For example, if you link two components along the horizontal axis and the preferred width is 10 and 20, both components are given a width of 20.

This can be used multiple times to force any number of components to share the same size.

Linked Components are not be resizable.

Parameters:
components - the Components that are to have the same size
axis - the axis to link the size along; one of SwingConstants.HORIZONTAL or SwingConstans.VERTICAL
Throws:
IllegalArgumentException - if components is null, or contains null; or axis is not SwingConstants.HORIZONTAL or SwingConstants.VERTICAL

replace

public void replace(Component existingComponent,
                    Component newComponent)
Replaces an existing component with a new one.

Parameters:
existingComponent - the component that should be removed and replaced with newComponent
newComponent - the component to put in existingComponent's place
Throws:
IllegalArgumentException - if either of the components are null or existingComponent is not being managed by this layout manager

setLayoutStyle

public void setLayoutStyle(LayoutStyle layoutStyle)
Sets the LayoutStyle used to calculate the preferred gaps between components. A value of null indicates the shared instance of LayoutStyle should be used.

Parameters:
layoutStyle - the LayoutStyle to use
See Also:
LayoutStyle

getLayoutStyle

public LayoutStyle getLayoutStyle()
Returns the LayoutStyle used for calculating the preferred gap between components. This returns the value specified to setLayoutStyle, which may be null.

Returns:
the LayoutStyle used for calculating the preferred gap between components

addLayoutComponent

public void addLayoutComponent(String name,
                               Component component)
Notification that a Component has been added to the parent container. You should not invoke this method directly, instead you should use one of the Group methods to add a Component.

Specified by:
addLayoutComponent in interface LayoutManager
Parameters:
name - the string to be associated with the component
component - the Component to be added

removeLayoutComponent

public void removeLayoutComponent(Component component)
Notification that a Component has been removed from the parent container. You should not invoke this method directly, instead invoke remove on the parent Container.

Specified by:
removeLayoutComponent in interface LayoutManager
Parameters:
component - the component to be removed
See Also:
Component.remove(java.awt.MenuComponent)

preferredLayoutSize

public Dimension preferredLayoutSize(Container parent)
Returns the preferred size for the specified container.

Specified by:
preferredLayoutSize in interface LayoutManager
Parameters:
parent - the container to return the preferred size for
Returns:
the preferred size for parent
Throws:
IllegalArgumentException - if parent is not the same Container this was created with
IllegalStateException - if any of the components added to this layout are not in both a horizontal and vertical group
See Also:
Container.getPreferredSize()

minimumLayoutSize

public Dimension minimumLayoutSize(Container parent)
Returns the minimum size for the specified container.

Specified by:
minimumLayoutSize in interface LayoutManager
Parameters:
parent - the container to return the size for
Returns:
the minimum size for parent
Throws:
IllegalArgumentException - if parent is not the same Container that this was created with
IllegalStateException - if any of the components added to this layout are not in both a horizontal and vertical group
See Also:
Container.getMinimumSize()

layoutContainer

public void layoutContainer(Container parent)
Lays out the specified container.

Specified by:
layoutContainer in interface LayoutManager
Parameters:
parent - the container to be laid out
Throws:
IllegalStateException - if any of the components added to this layout are not in both a horizontal and vertical group

addLayoutComponent

public void addLayoutComponent(Component component,
                               Object constraints)
Notification that a Component has been added to the parent container. You should not invoke this method directly, instead you should use one of the Group methods to add a Component.

Specified by:
addLayoutComponent in interface LayoutManager2
Parameters:
component - the component added
constraints - description of where to place the component

maximumLayoutSize

public Dimension maximumLayoutSize(Container parent)
Returns the maximum size for the specified container.

Specified by:
maximumLayoutSize in interface LayoutManager2
Parameters:
parent - the container to return the size for
Returns:
the maximum size for parent
Throws:
IllegalArgumentException - if parent is not the same Container that this was created with
IllegalStateException - if any of the components added to this layout are not in both a horizontal and vertical group
See Also:
Container.getMaximumSize()

getLayoutAlignmentX

public float getLayoutAlignmentX(Container parent)
Returns the alignment along the x axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.

Specified by:
getLayoutAlignmentX in interface LayoutManager2
Parameters:
parent - the Container hosting this LayoutManager
Returns:
the alignment; this implementation returns .5
Throws:
IllegalArgumentException - if parent is not the same Container that this was created with

getLayoutAlignmentY

public float getLayoutAlignmentY(Container parent)
Returns the alignment along the y axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.

Specified by:
getLayoutAlignmentY in interface LayoutManager2
Parameters:
parent - the Container hosting this LayoutManager
Returns:
alignment; this implementation returns .5
Throws:
IllegalArgumentException - if parent is not the same Container that this was created with

invalidateLayout

public void invalidateLayout(Container parent)
Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.

Specified by:
invalidateLayout in interface LayoutManager2
Parameters:
parent - the Container hosting this LayoutManager
Throws:
IllegalArgumentException - if parent is not the same Container that this was created with

toString

public String toString()
Returns a string representation of this GroupLayout. This method is intended to be used for debugging purposes, and the content and format of the returned string may vary between implementations.

Overrides:
toString in class Object
Returns:
a string representation of this GroupLayout
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


GroupLayout.Alignment

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.swing
Enum GroupLayout.Alignment

java.lang.Object
    extended by  java.lang.Enum<GroupLayout.Alignment>
        extended by  javax.swing.GroupLayout.Alignment
All Implemented Interfaces:
Serializable, Comparable<GroupLayout.Alignment>
Enclosing class:
GroupLayout
public static enum GroupLayout.Alignment
extends Enum<GroupLayout.Alignment>

Enumeration of the possible ways ParallelGroup can align its children.

Since:
1.6
See Also:
GroupLayout.createParallelGroup(Alignment)

Enum Constant Summary
BASELINE
Indicates the elements should be aligned along their baseline.
CENTER
Indicates the elements should be centered in the region.
LEADING
Indicates the elements should be aligned to the origin.
TRAILING
Indicates the elements should be aligned to the end of the region.
Method Summary
static GroupLayout.Alignment | valueOf(String name) Returns the enum constant of this type with the specified name.
static GroupLayout.Alignment[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

LEADING

public static final GroupLayout.Alignment LEADING
Indicates the elements should be aligned to the origin. For the horizontal axis with a left to right orientation this means aligned to the left edge. For the vertical axis leading means aligned to the top edge.

See Also:
GroupLayout.createParallelGroup(Alignment)

TRAILING

public static final GroupLayout.Alignment TRAILING
Indicates the elements should be aligned to the end of the region. For the horizontal axis with a left to right orientation this means aligned to the right edge. For the vertical axis trailing means aligned to the bottom edge.

See Also:
GroupLayout.createParallelGroup(Alignment)

CENTER

public static final GroupLayout.Alignment CENTER
Indicates the elements should be centered in the region.

See Also:
GroupLayout.createParallelGroup(Alignment)

BASELINE

public static final GroupLayout.Alignment BASELINE
Indicates the elements should be aligned along their baseline.

See Also:
GroupLayout.createParallelGroup(Alignment), GroupLayout.createBaselineGroup(boolean,boolean)
Method Detail

values

public static GroupLayout.Alignment[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (GroupLayout.Alignment c : GroupLayout.Alignment.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static GroupLayout.Alignment valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


GroupLayout.Group

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class GroupLayout.Group

java.lang.Object
    extended by  javax.swing.GroupLayout.Group
Direct Known Subclasses:
GroupLayout.ParallelGroup, GroupLayout.SequentialGroup
Enclosing class:
GroupLayout
public abstract class GroupLayout.Group
extends Object

Group provides the basis for the two types of operations supported by GroupLayout: laying out components one after another (SequentialGroup) or aligned (ParallelGroup). Group and its subclasses have no public constructor; to create one use one of createSequentialGroup or createParallelGroup. Additionally, taking a Group created from one GroupLayout and using it with another will produce undefined results.

Various methods in Group and its subclasses allow you to explicitly specify the range. The arguments to these methods can take two forms, either a value greater than or equal to 0, or one of DEFAULT_SIZE or PREFERRED_SIZE. A value greater than or equal to 0 indicates a specific size. DEFAULT_SIZE indicates the corresponding size from the component should be used. For example, if DEFAULT_SIZE is passed as the minimum size argument, the minimum size is obtained from invoking getMinimumSize on the component. Likewise, PREFERRED_SIZE indicates the value from getPreferredSize should be used. The following example adds myComponent to group with specific values for the range. That is, the minimum is explicitly specified as 100, preferred as 200, and maximum as 300.

   group.addComponent(myComponent, 100, 200, 300);
The following example adds myComponent to group using a combination of the forms. The minimum size is forced to be the same as the preferred size, the preferred size is determined by using myComponent.getPreferredSize and the maximum is determined by invoking getMaximumSize on the component.
   group.addComponent(myComponent, GroupLayout.PREFERRED_SIZE,
             GroupLayout.PREFERRED_SIZE, GroupLayout.DEFAULT_SIZE);

Unless otherwise specified all the methods of Group and its subclasses that allow you to specify a range throw an IllegalArgumentException if passed an invalid range. An invalid range is one in which any of the values are < 0 and not one of PREFERRED_SIZE or DEFAULT_SIZE, or the following is not met (for specific values): min <= pref <= max.

Similarly any methods that take a Component throw a NullPointerException if passed null and any methods that take a Group throw an IllegalArgumentException if passed null.

Since:
1.6
See Also:
GroupLayout.createSequentialGroup(), GroupLayout.createParallelGroup()

Method Summary
GroupLayout.Group | addComponent(Component component) Adds a Component to this Group.
GroupLayout.Group | addComponent(Component component, int min, int pref, int max) Adds a Component to this Group with the specified size.
GroupLayout.Group | addGap(int size) Adds a rigid gap to this Group.
GroupLayout.Group | addGap(int min, int pref, int max) Adds a gap to this Group with the specified size.
GroupLayout.Group | addGroup(GroupLayout.Group group) Adds a Group to this Group.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

addGroup

public GroupLayout.Group addGroup(GroupLayout.Group group)
Adds a Group to this Group.

Parameters:
group - the Group to add
Returns:
this Group

addComponent

public GroupLayout.Group addComponent(Component component)
Adds a Component to this Group.

Parameters:
component - the Component to add
Returns:
this Group

addComponent

public GroupLayout.Group addComponent(Component component,
                                      int min,
                                      int pref,
                                      int max)
Adds a Component to this Group with the specified size.

Parameters:
component - the Component to add
min - the minimum size or one of DEFAULT_SIZE or PREFERRED_SIZE
pref - the preferred size or one of DEFAULT_SIZE or PREFERRED_SIZE
max - the maximum size or one of DEFAULT_SIZE or PREFERRED_SIZE
Returns:
this Group

addGap

public GroupLayout.Group addGap(int size)
Adds a rigid gap to this Group.

Parameters:
size - the size of the gap
Returns:
this Group
Throws:
IllegalArgumentException - if size is less than 0

addGap

public GroupLayout.Group addGap(int min,
                                int pref,
                                int max)
Adds a gap to this Group with the specified size.

Parameters:
min - the minimum size of the gap
pref - the preferred size of the gap
max - the maximum size of the gap
Returns:
this Group
Throws:
IllegalArgumentException - if any of the values are less than 0
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


GroupLayout.ParallelGroup

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class GroupLayout.ParallelGroup

java.lang.Object
    extended by  javax.swing.GroupLayout.Group
        extended by  javax.swing.GroupLayout.ParallelGroup
Enclosing class:
GroupLayout
public class GroupLayout.ParallelGroup
extends GroupLayout.Group

A Group that aligns and sizes it's children. ParallelGroup aligns it's children in four possible ways: along the baseline, centered, anchored to the leading edge, or anchored to the trailing edge.

Baseline

A ParallelGroup that aligns it's children along the baseline must first decide where the baseline is anchored. The baseline can either be anchored to the top, or anchored to the bottom of the group. That is, the distance between the baseline and the beginning of the group can be a constant distance, or the distance between the end of the group and the baseline can be a constant distance. The possible choices correspond to the BaselineResizeBehavior constants CONSTANT_ASCENT and CONSTANT_DESCENT.

The baseline anchor may be explicitly specified by the createBaselineGroup method, or determined based on the elements. If not explicitly specified, the baseline will be anchored to the bottom if all the elements with a baseline, and that are aligned to the baseline, have a baseline resize behavior of CONSTANT_DESCENT; otherwise the baseline is anchored to the top of the group.

Elements aligned to the baseline are resizable if they have have a baseline resize behavior of CONSTANT_ASCENT or CONSTANT_DESCENT. Elements with a baseline resize behavior of OTHER or CENTER_OFFSET are not resizable.

The baseline is calculated based on the preferred height of each of the elements that have a baseline. The baseline is calculated using the following algorithm: max(maxNonBaselineHeight, maxAscent + maxDescent), where the maxNonBaselineHeight is the maximum height of all elements that do not have a baseline, or are not aligned along the baseline. maxAscent is the maximum ascent (baseline) of all elements that have a baseline and are aligned along the baseline. maxDescent is the maximum descent (preferred height - baseline) of all elements that have a baseline and are aligned along the baseline.

A ParallelGroup that aligns it's elements along the baseline is only useful along the vertical axis. If you create a baseline group and use it along the horizontal axis an IllegalStateException is thrown when you ask GroupLayout for the minimum, preferred or maximum size or attempt to layout the components.

Elements that are not aligned to the baseline and smaller than the size of the ParallelGroup are positioned in one of three ways: centered, anchored to the leading edge, or anchored to the trailing edge.

Non-baseline ParallelGroup

ParallelGroups created with an alignment other than BASELINE align elements that are smaller than the size of the group in one of three ways: centered, anchored to the leading edge, or anchored to the trailing edge.

The leading edge is based on the axis and ComponentOrientation. For the vertical axis the top edge is always the leading edge, and the bottom edge is always the trailing edge. When the ComponentOrientation is LEFT_TO_RIGHT, the leading edge is the left edge and the trailing edge the right edge. A ComponentOrientation of RIGHT_TO_LEFT flips the left and right edges. Child elements are aligned based on the specified alignment the element was added with. If you do not specify an alignment, the alignment specified for the ParallelGroup is used.

To align elements along the baseline you createBaselineGroup, or createParallelGroup with an alignment of BASELINE. If the group was not created with a baseline alignment, and you attempt to add an element specifying a baseline alignment, an IllegalArgumentException is thrown.

Since:
1.6
See Also:
GroupLayout.createParallelGroup(), GroupLayout.createBaselineGroup(boolean,boolean)

Method Summary
GroupLayout.ParallelGroup | addComponent(Component component) Adds a Component to this Group.
GroupLayout.ParallelGroup | addComponent(Component component, GroupLayout.Alignment alignment) Adds a Component to this ParallelGroup with the specified alignment.
GroupLayout.ParallelGroup | addComponent(Component component, GroupLayout.Alignment alignment, int min, int pref, int max) Adds a Component to this ParallelGroup with the specified alignment and size.
GroupLayout.ParallelGroup | addComponent(Component component, int min, int pref, int max) Adds a Component to this Group with the specified size.
GroupLayout.ParallelGroup | addGap(int pref) Adds a rigid gap to this Group.
GroupLayout.ParallelGroup | addGap(int min, int pref, int max) Adds a gap to this Group with the specified size.
GroupLayout.ParallelGroup | addGroup(GroupLayout.Alignment alignment, GroupLayout.Group group) Adds a Group to this ParallelGroup with the specified alignment.
GroupLayout.ParallelGroup | addGroup(GroupLayout.Group group) Adds a Group to this Group.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

addGroup

public GroupLayout.ParallelGroup addGroup(GroupLayout.Group group)
Adds a Group to this Group.

Overrides:
addGroup in class GroupLayout.Group
Parameters:
group - the Group to add
Returns:
this Group

addComponent

public GroupLayout.ParallelGroup addComponent(Component component)
Adds a Component to this Group.

Overrides:
addComponent in class GroupLayout.Group
Parameters:
component - the Component to add
Returns:
this Group

addComponent

public GroupLayout.ParallelGroup addComponent(Component component,
                                              int min,
                                              int pref,
                                              int max)
Adds a Component to this Group with the specified size.

Overrides:
addComponent in class GroupLayout.Group
Parameters:
component - the Component to add
min - the minimum size or one of DEFAULT_SIZE or PREFERRED_SIZE
pref - the preferred size or one of DEFAULT_SIZE or PREFERRED_SIZE
max - the maximum size or one of DEFAULT_SIZE or PREFERRED_SIZE
Returns:
this Group

addGap

public GroupLayout.ParallelGroup addGap(int pref)
Adds a rigid gap to this Group.

Overrides:
addGap in class GroupLayout.Group
Parameters:
pref - the size of the gap
Returns:
this Group

addGap

public GroupLayout.ParallelGroup addGap(int min,
                                        int pref,
                                        int max)
Adds a gap to this Group with the specified size.

Overrides:
addGap in class GroupLayout.Group
Parameters:
min - the minimum size of the gap
pref - the preferred size of the gap
max - the maximum size of the gap
Returns:
this Group

addGroup

public GroupLayout.ParallelGroup addGroup(GroupLayout.Alignment alignment,
                                          GroupLayout.Group group)
Adds a Group to this ParallelGroup with the specified alignment. If the child is smaller than the Group it is aligned based on the specified alignment.

Parameters:
alignment - the alignment
group - the Group to add
Returns:
this ParallelGroup
Throws:
IllegalArgumentException - if alignment is null

addComponent

public GroupLayout.ParallelGroup addComponent(Component component,
                                              GroupLayout.Alignment alignment)
Adds a Component to this ParallelGroup with the specified alignment.

Parameters:
alignment - the alignment
component - the Component to add
Returns:
this Group
Throws:
IllegalArgumentException - if alignment is null

addComponent

public GroupLayout.ParallelGroup addComponent(Component component,
                                              GroupLayout.Alignment alignment,
                                              int min,
                                              int pref,
                                              int max)
Adds a Component to this ParallelGroup with the specified alignment and size.

Parameters:
alignment - the alignment
component - the Component to add
min - the minimum size
pref - the preferred size
max - the maximum size
Returns:
this Group
Throws:
IllegalArgumentException - if alignment is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


GroupLayout.SequentialGroup

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class GroupLayout.SequentialGroup

java.lang.Object
    extended by  javax.swing.GroupLayout.Group
        extended by  javax.swing.GroupLayout.SequentialGroup
Enclosing class:
GroupLayout
public class GroupLayout.SequentialGroup
extends GroupLayout.Group

A Group that positions and sizes its elements sequentially, one after another. This class has no public constructor, use the createSequentialGroup method to create one.

In order to align a SequentialGroup along the baseline of a baseline aligned ParallelGroup you need to specify which of the elements of the SequentialGroup is used to determine the baseline. The element used to calculate the baseline is specified using one of the add methods that take a boolean. The last element added with a value of true for useAsBaseline is used to calculate the baseline.

Since:
1.6
See Also:
GroupLayout.createSequentialGroup()

Method Summary
GroupLayout.SequentialGroup | addComponent(boolean useAsBaseline, Component component) Adds a Component to this Group.
GroupLayout.SequentialGroup | addComponent(boolean useAsBaseline, Component component, int min, int pref, int max) Adds a Component to this Group with the specified size.
GroupLayout.SequentialGroup | addComponent(Component component) Adds a Component to this Group.
GroupLayout.SequentialGroup | addComponent(Component component, int min, int pref, int max) Adds a Component to this Group with the specified size.
GroupLayout.SequentialGroup | addContainerGap() Adds an element representing the preferred gap between an edge the container and components that touch the border of the container.
GroupLayout.SequentialGroup | addContainerGap(int pref, int max) Adds an element representing the preferred gap between one edge of the container and the next or previous Component with the specified size.
GroupLayout.SequentialGroup | addGap(int size) Adds a rigid gap to this Group.
GroupLayout.SequentialGroup | addGap(int min, int pref, int max) Adds a gap to this Group with the specified size.
GroupLayout.SequentialGroup | addGroup(boolean useAsBaseline, GroupLayout.Group group) Adds a Group to this Group.
GroupLayout.SequentialGroup | addGroup(GroupLayout.Group group) Adds a Group to this Group.
GroupLayout.SequentialGroup | addPreferredGap(JComponent comp1, JComponent comp2, LayoutStyle.ComponentPlacement type) Adds an element representing the preferred gap between two components.
GroupLayout.SequentialGroup | addPreferredGap(JComponent comp1, JComponent comp2, LayoutStyle.ComponentPlacement type, int pref, int max) Adds an element representing the preferred gap between two components.
GroupLayout.SequentialGroup | addPreferredGap(LayoutStyle.ComponentPlacement type) Adds an element representing the preferred gap between the nearest components.
GroupLayout.SequentialGroup | addPreferredGap(LayoutStyle.ComponentPlacement type, int pref, int max) Adds an element representing the preferred gap between the nearest components.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

addGroup

public GroupLayout.SequentialGroup addGroup(GroupLayout.Group group)
Adds a Group to this Group.

Overrides:
addGroup in class GroupLayout.Group
Parameters:
group - the Group to add
Returns:
this Group

addGroup

public GroupLayout.SequentialGroup addGroup(boolean useAsBaseline,
                                            GroupLayout.Group group)
Adds a Group to this Group.

Parameters:
group - the Group to add
useAsBaseline - whether the specified Group should be used to calculate the baseline for this Group
Returns:
this Group

addComponent

public GroupLayout.SequentialGroup addComponent(Component component)
Adds a Component to this Group.

Overrides:
addComponent in class GroupLayout.Group
Parameters:
component - the Component to add
Returns:
this Group

addComponent

public GroupLayout.SequentialGroup addComponent(boolean useAsBaseline,
                                                Component component)
Adds a Component to this Group.

Parameters:
useAsBaseline - whether the specified Component should be used to calculate the baseline for this Group
component - the Component to add
Returns:
this Group

addComponent

public GroupLayout.SequentialGroup addComponent(Component component,
                                                int min,
                                                int pref,
                                                int max)
Adds a Component to this Group with the specified size.

Overrides:
addComponent in class GroupLayout.Group
Parameters:
component - the Component to add
min - the minimum size or one of DEFAULT_SIZE or PREFERRED_SIZE
pref - the preferred size or one of DEFAULT_SIZE or PREFERRED_SIZE
max - the maximum size or one of DEFAULT_SIZE or PREFERRED_SIZE
Returns:
this Group

addComponent

public GroupLayout.SequentialGroup addComponent(boolean useAsBaseline,
                                                Component component,
                                                int min,
                                                int pref,
                                                int max)
Adds a Component to this Group with the specified size.

Parameters:
useAsBaseline - whether the specified Component should be used to calculate the baseline for this Group
component - the Component to add
min - the minimum size or one of DEFAULT_SIZE or PREFERRED_SIZE
pref - the preferred size or one of DEFAULT_SIZE or PREFERRED_SIZE
max - the maximum size or one of DEFAULT_SIZE or PREFERRED_SIZE
Returns:
this Group

addGap

public GroupLayout.SequentialGroup addGap(int size)
Adds a rigid gap to this Group.

Overrides:
addGap in class GroupLayout.Group
Parameters:
size - the size of the gap
Returns:
this Group

addGap

public GroupLayout.SequentialGroup addGap(int min,
                                          int pref,
                                          int max)
Adds a gap to this Group with the specified size.

Overrides:
addGap in class GroupLayout.Group
Parameters:
min - the minimum size of the gap
pref - the preferred size of the gap
max - the maximum size of the gap
Returns:
this Group

addPreferredGap

public GroupLayout.SequentialGroup addPreferredGap(JComponent comp1,
                                                   JComponent comp2,
                                                   LayoutStyle.ComponentPlacement type)
Adds an element representing the preferred gap between two components. The element created to represent the gap is not resizable.

Parameters:
comp1 - the first component
comp2 - the second component
type - the type of gap; one of the constants defined by LayoutStyle
Returns:
this SequentialGroup
Throws:
IllegalArgumentException - if type, comp1 or comp2 is null
See Also:
LayoutStyle

addPreferredGap

public GroupLayout.SequentialGroup addPreferredGap(JComponent comp1,
                                                   JComponent comp2,
                                                   LayoutStyle.ComponentPlacement type,
                                                   int pref,
                                                   int max)
Adds an element representing the preferred gap between two components.

Parameters:
comp1 - the first component
comp2 - the second component
type - the type of gap
pref - the preferred size of the grap; one of DEFAULT_SIZE or a value >= 0
max - the maximum size of the gap; one of DEFAULT_SIZE, PREFERRED_SIZE or a value >= 0
Returns:
this SequentialGroup
Throws:
IllegalArgumentException - if type, comp1 or comp2 is null
See Also:
LayoutStyle

addPreferredGap

public GroupLayout.SequentialGroup addPreferredGap(LayoutStyle.ComponentPlacement type)
Adds an element representing the preferred gap between the nearest components. During layout, neighboring components are found, and the size of the added gap is set based on the preferred gap between the components. If no neighboring components are found the gap has a size of 0.

The element created to represent the gap is not resizable.

Parameters:
type - the type of gap; one of LayoutStyle.ComponentPlacement.RELATED or LayoutStyle.ComponentPlacement.UNRELATED
Returns:
this SequentialGroup
Throws:
IllegalArgumentException - if type is not one of LayoutStyle.ComponentPlacement.RELATED or LayoutStyle.ComponentPlacement.UNRELATED
See Also:
LayoutStyle

addPreferredGap

public GroupLayout.SequentialGroup addPreferredGap(LayoutStyle.ComponentPlacement type,
                                                   int pref,
                                                   int max)
Adds an element representing the preferred gap between the nearest components. During layout, neighboring components are found, and the minimum of this gap is set based on the size of the preferred gap between the neighboring components. If no neighboring components are found the minimum size is set to 0.

Parameters:
type - the type of gap; one of LayoutStyle.ComponentPlacement.RELATED or LayoutStyle.ComponentPlacement.UNRELATED
pref - the preferred size of the grap; one of DEFAULT_SIZE or a value >= 0
max - the maximum size of the gap; one of DEFAULT_SIZE, PREFERRED_SIZE or a value >= 0
Returns:
this SequentialGroup
Throws:
IllegalArgumentException - if type is not one of LayoutStyle.ComponentPlacement.RELATED or LayoutStyle.ComponentPlacement.UNRELATED
See Also:
LayoutStyle

addContainerGap

public GroupLayout.SequentialGroup addContainerGap()
Adds an element representing the preferred gap between an edge the container and components that touch the border of the container. This has no effect if the added gap does not touch an edge of the parent container.

The element created to represent the gap is not resizable.

Returns:
this SequentialGroup

addContainerGap

public GroupLayout.SequentialGroup addContainerGap(int pref,
                                                   int max)
Adds an element representing the preferred gap between one edge of the container and the next or previous Component with the specified size. This has no effect if the next or previous element is not a Component and does not touch one edge of the parent container.

Parameters:
pref - the preferred size; one of DEFAULT_SIZE or a value >= 0
max - the maximum size; one of DEFAULT_SIZE, PREFERRED_SIZE or a value >= 0
Returns:
this SequentialGroup
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Icon

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface Icon

All Known Implementing Classes:
IconUIResource, ImageIcon, MetalCheckBoxIcon, MetalComboBoxIcon, MetalIconFactory.FileIcon16, MetalIconFactory.FolderIcon16, MetalIconFactory.PaletteCloseIcon, MetalIconFactory.TreeControlIcon, MetalIconFactory.TreeFolderIcon, MetalIconFactory.TreeLeafIcon
public interface Icon

A small fixed size picture, typically used to decorate components.

See Also:
ImageIcon

Method Summary
int | getIconHeight() Returns the icon's height.
int | getIconWidth() Returns the icon's width.
void | paintIcon(Component c, Graphics g, int x, int y) Draw the icon at the specified location.

Method Detail

paintIcon

void paintIcon(Component c,
               Graphics g,
               int x,
               int y)
Draw the icon at the specified location. Icon implementations may use the Component argument to get properties useful for painting, e.g. the foreground or background color.

getIconWidth

int getIconWidth()
Returns the icon's width.

Returns:
an int specifying the fixed width of the icon.

getIconHeight

int getIconHeight()
Returns the icon's height.

Returns:
an int specifying the fixed height of the icon.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ImageIcon

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class ImageIcon

java.lang.Object
    extended by  javax.swing.ImageIcon
All Implemented Interfaces:
Serializable, Accessible, Icon
public class ImageIcon
extends Object
implements Icon, Serializable, Accessible

An implementation of the Icon interface that paints Icons from Images. Images that are created from a URL, filename or byte array are preloaded using MediaTracker to monitor the loaded state of the image.

For further information and examples of using image icons, see How to Use Icons in The Java Tutorial.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class ImageIcon.AccessibleImageIcon
This class implements accessibility support for the ImageIcon class.
Field Summary
protected static Component | component
protected static MediaTracker | tracker
Constructor Summary
ImageIcon()
Creates an uninitialized image icon.
ImageIcon(byte[] imageData)
Creates an ImageIcon from an array of bytes which were read from an image file containing a supported image format, such as GIF, JPEG, or (as of 1.3) PNG.
ImageIcon(byte[] imageData, String description)
Creates an ImageIcon from an array of bytes which were read from an image file containing a supported image format, such as GIF, JPEG, or (as of 1.3) PNG.
ImageIcon(Image image)
Creates an ImageIcon from an image object.
ImageIcon(Image image, String description)
Creates an ImageIcon from the image.
ImageIcon(String filename)
Creates an ImageIcon from the specified file.
ImageIcon(String filename, String description)
Creates an ImageIcon from the specified file.
ImageIcon(URL location)
Creates an ImageIcon from the specified URL.
ImageIcon(URL location, String description)
Creates an ImageIcon from the specified URL.
Method Summary
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this ImageIcon.
String | getDescription() Gets the description of the image.
int | getIconHeight() Gets the height of the icon.
int | getIconWidth() Gets the width of the icon.
Image | getImage() Returns this icon's Image.
int | getImageLoadStatus() Returns the status of the image loading operation.
ImageObserver | getImageObserver() Returns the image observer for the image.
protected void | loadImage(Image image) Loads the image, returning only when the image is loaded.
void | paintIcon(Component c, Graphics g, int x, int y) Paints the icon.
void | setDescription(String description) Sets the description of the image.
void | setImage(Image image) Sets the image displayed by this icon.
void | setImageObserver(ImageObserver observer) Sets the image observer for the image.
String | toString() Returns a string representation of this image.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

component

protected static final Component component

tracker

protected static final MediaTracker tracker
Constructor Detail

ImageIcon

public ImageIcon(String filename,
                 String description)
Creates an ImageIcon from the specified file. The image will be preloaded by using MediaTracker to monitor the loading state of the image.

Parameters:
filename - the name of the file containing the image
description - a brief textual description of the image
See Also:
ImageIcon(String)

ImageIcon

public ImageIcon(String filename)
Creates an ImageIcon from the specified file. The image will be preloaded by using MediaTracker to monitor the loading state of the image. The specified String can be a file name or a file path. When specifying a path, use the Internet-standard forward-slash ("/") as a separator. (The string is converted to an URL, so the forward-slash works on all systems.) For example, specify:
    new ImageIcon("images/myImage.gif")
The description is initialized to the filename string.

Parameters:
filename - a String specifying a filename or path
See Also:
getDescription()

ImageIcon

public ImageIcon(URL location,
                 String description)
Creates an ImageIcon from the specified URL. The image will be preloaded by using MediaTracker to monitor the loaded state of the image.

Parameters:
location - the URL for the image
description - a brief textual description of the image
See Also:
ImageIcon(String)

ImageIcon

public ImageIcon(URL location)
Creates an ImageIcon from the specified URL. The image will be preloaded by using MediaTracker to monitor the loaded state of the image. The icon's description is initialized to be a string representation of the URL.

Parameters:
location - the URL for the image
See Also:
getDescription()

ImageIcon

public ImageIcon(Image image,
                 String description)
Creates an ImageIcon from the image.

Parameters:
image - the image
description - a brief textual description of the image

ImageIcon

public ImageIcon(Image image)
Creates an ImageIcon from an image object. If the image has a "comment" property that is a string, then the string is used as the description of this icon.

Parameters:
image - the image
See Also:
getDescription(), Image.getProperty(java.lang.String, java.awt.image.ImageObserver)

ImageIcon

public ImageIcon(byte[] imageData,
                 String description)
Creates an ImageIcon from an array of bytes which were read from an image file containing a supported image format, such as GIF, JPEG, or (as of 1.3) PNG. Normally this array is created by reading an image using Class.getResourceAsStream(), but the byte array may also be statically stored in a class.

Parameters:
imageData - an array of pixels in an image format supported by the AWT Toolkit, such as GIF, JPEG, or (as of 1.3) PNG
description - a brief textual description of the image
See Also:
Toolkit.createImage(java.lang.String)

ImageIcon

public ImageIcon(byte[] imageData)
Creates an ImageIcon from an array of bytes which were read from an image file containing a supported image format, such as GIF, JPEG, or (as of 1.3) PNG. Normally this array is created by reading an image using Class.getResourceAsStream(), but the byte array may also be statically stored in a class. If the resulting image has a "comment" property that is a string, then the string is used as the description of this icon.

Parameters:
imageData - an array of pixels in an image format supported by the AWT Toolkit, such as GIF, JPEG, or (as of 1.3) PNG
See Also:
Toolkit.createImage(java.lang.String),
getDescription(),
Image.getProperty(java.lang.String, java.awt.image.ImageObserver)

ImageIcon

public ImageIcon()
Creates an uninitialized image icon.

Method Detail

loadImage

protected void loadImage(Image image)
Loads the image, returning only when the image is loaded.

Parameters:
image - the image

getImageLoadStatus

public int getImageLoadStatus()
Returns the status of the image loading operation.

Returns:
the loading status as defined by java.awt.MediaTracker
See Also:
MediaTracker.ABORTED, MediaTracker.ERRORED, MediaTracker.COMPLETE

getImage

public Image getImage()
Returns this icon's Image.

Returns:
the Image object for this ImageIcon

setImage

public void setImage(Image image)
Sets the image displayed by this icon.

Parameters:
image - the image

getDescription

public String getDescription()
Gets the description of the image. This is meant to be a brief textual description of the object. For example, it might be presented to a blind user to give an indication of the purpose of the image. The description may be null.

Returns:
a brief textual description of the image

setDescription

public void setDescription(String description)
Sets the description of the image. This is meant to be a brief textual description of the object. For example, it might be presented to a blind user to give an indication of the purpose of the image.

Parameters:
description - a brief textual description of the image

paintIcon

public void paintIcon(Component c,
                      Graphics g,
                      int x,
                      int y)
Paints the icon. The top-left corner of the icon is drawn at the point (x, y) in the coordinate space of the graphics context g. If this icon has no image observer, this method uses the c component as the observer.

Specified by:
paintIcon in interface Icon
Parameters:
c - the component to be used as the observer if this icon has no image observer
g - the graphics context
x - the X coordinate of the icon's top-left corner
y - the Y coordinate of the icon's top-left corner

getIconWidth

public int getIconWidth()
Gets the width of the icon.

Specified by:
getIconWidth in interface Icon
Returns:
the width in pixels of this icon

getIconHeight

public int getIconHeight()
Gets the height of the icon.

Specified by:
getIconHeight in interface Icon
Returns:
the height in pixels of this icon

setImageObserver

public void setImageObserver(ImageObserver observer)
Sets the image observer for the image. Set this property if the ImageIcon contains an animated GIF, so the observer is notified to update its display. For example:
     icon = new ImageIcon(...)
     button.setIcon(icon);
     icon.setImageObserver(button);

Parameters:
observer - the image observer

getImageObserver

public ImageObserver getImageObserver()
Returns the image observer for the image.

Returns:
the image observer, which may be null

toString

public String toString()
Returns a string representation of this image.

Overrides:
toString in class Object
Returns:
a string representing this image

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this ImageIcon. For image icons, the AccessibleContext takes the form of an AccessibleImageIcon. A new AccessibleImageIcon instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Returns:
an AccessibleImageIcon that serves as the AccessibleContext of this ImageIcon
Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ImageIcon.AccessibleImageIcon

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class ImageIcon.AccessibleImageIcon

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  javax.swing.ImageIcon.AccessibleImageIcon
All Implemented Interfaces:
Serializable, AccessibleIcon
Enclosing class:
ImageIcon
protected class ImageIcon.AccessibleImageIcon
extends AccessibleContext
implements AccessibleIcon, Serializable

This class implements accessibility support for the ImageIcon class. It provides an implementation of the Java Accessibility API appropriate to image icon user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Since:
1.3

Field Summary
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected ImageIcon.AccessibleImageIcon()
Method Summary
Accessible | getAccessibleChild(int i) Returns the nth Accessible child of the object.
int | getAccessibleChildrenCount() Returns the number of accessible children in the object.
String | getAccessibleIconDescription() Gets the description of the icon.
int | getAccessibleIconHeight() Gets the height of the icon.
int | getAccessibleIconWidth() Gets the width of the icon.
int | getAccessibleIndexInParent() Gets the index of this object in its accessible parent.
Accessible | getAccessibleParent() Gets the Accessible parent of this object.
AccessibleRole | getAccessibleRole() Gets the role of this object.
AccessibleStateSet | getAccessibleStateSet() Gets the state of this object.
Locale | getLocale() Returns the locale of this object.
void | setAccessibleIconDescription(String description) Sets the description of the icon.
Methods inherited from class javax.accessibility.AccessibleContext
addPropertyChangeListener, firePropertyChange, getAccessibleAction, getAccessibleComponent, getAccessibleDescription, getAccessibleEditableText, getAccessibleIcon, getAccessibleName, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, removePropertyChangeListener, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ImageIcon.AccessibleImageIcon

protected ImageIcon.AccessibleImageIcon()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Gets the role of this object.

Specified by:
getAccessibleRole in class AccessibleContext
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Gets the state of this object.

Specified by:
getAccessibleStateSet in class AccessibleContext
Returns:
an instance of AccessibleStateSet containing the current state set of the object
See Also:
AccessibleState

getAccessibleParent

public Accessible getAccessibleParent()
Gets the Accessible parent of this object. If the parent of this object implements Accessible, this method should simply return getParent().

Overrides:
getAccessibleParent in class AccessibleContext
Returns:
the Accessible parent of this object -- can be null if this object does not have an Accessible parent

getAccessibleIndexInParent

public int getAccessibleIndexInParent()
Gets the index of this object in its accessible parent.

Specified by:
getAccessibleIndexInParent in class AccessibleContext
Returns:
the index of this object in its parent; -1 if this object does not have an accessible parent.
See Also:
getAccessibleParent()

getAccessibleChildrenCount

public int getAccessibleChildrenCount()
Returns the number of accessible children in the object. If all of the children of this object implement Accessible, than this method should return the number of children of this object.

Specified by:
getAccessibleChildrenCount in class AccessibleContext
Returns:
the number of accessible children in the object.

getAccessibleChild

public Accessible getAccessibleChild(int i)
Returns the nth Accessible child of the object.

Specified by:
getAccessibleChild in class AccessibleContext
Parameters:
i - zero-based index of child
Returns:
the nth Accessible child of the object
See Also:
AccessibleContext.getAccessibleChildrenCount()

getLocale

public Locale getLocale()
                 throws IllegalComponentStateException
Returns the locale of this object.

Specified by:
getLocale in class AccessibleContext
Returns:
the locale of this object
Throws:
IllegalComponentStateException - If the Component does not have its own locale and has not yet been added to a containment hierarchy such that the locale can be determined from the containing parent.

getAccessibleIconDescription

public String getAccessibleIconDescription()
Gets the description of the icon. This is meant to be a brief textual description of the object. For example, it might be presented to a blind user to give an indication of the purpose of the icon.

Specified by:
getAccessibleIconDescription in interface AccessibleIcon
Returns:
the description of the icon

setAccessibleIconDescription

public void setAccessibleIconDescription(String description)
Sets the description of the icon. This is meant to be a brief textual description of the object. For example, it might be presented to a blind user to give an indication of the purpose of the icon.

Specified by:
setAccessibleIconDescription in interface AccessibleIcon
Parameters:
description - the description of the icon

getAccessibleIconHeight

public int getAccessibleIconHeight()
Gets the height of the icon.

Specified by:
getAccessibleIconHeight in interface AccessibleIcon
Returns:
the height of the icon

getAccessibleIconWidth

public int getAccessibleIconWidth()
Gets the width of the icon.

Specified by:
getAccessibleIconWidth in interface AccessibleIcon
Returns:
the width of the icon
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InputMap

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class InputMap

java.lang.Object
    extended by  javax.swing.InputMap
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
ComponentInputMap, InputMapUIResource
public class InputMap
extends Object
implements Serializable

InputMap provides a binding between an input event (currently only KeyStrokes are used) and an Object. InputMaps are usually used with an ActionMap, to determine an Action to perform when a key is pressed. An InputMap can have a parent that is searched for bindings not defined in the InputMap.

As with ActionMap if you create a cycle, eg:

   InputMap am = new InputMap();
   InputMap bm = new InputMap():
   am.setParent(bm);
   bm.setParent(am);
some of the methods will cause a StackOverflowError to be thrown.

Since:
1.3

Constructor Summary
InputMap()
Creates an InputMap with no parent and no mappings.
Method Summary
KeyStroke[] | allKeys() Returns an array of the KeyStrokes defined in this InputMap and its parent.
void | clear() Removes all the mappings from this InputMap.
Object | get(KeyStroke keyStroke) Returns the binding for keyStroke, messaging the parent InputMap if the binding is not locally defined.
InputMap | getParent() Gets this InputMap's parent.
KeyStroke[] | keys() Returns the KeyStrokes that are bound in this InputMap.
void | put(KeyStroke keyStroke, Object actionMapKey) Adds a binding for keyStroke to actionMapKey.
void | remove(KeyStroke key) Removes the binding for key from this InputMap.
void | setParent(InputMap map) Sets this InputMap's parent.
int | size() Returns the number of KeyStroke bindings.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InputMap

public InputMap()
Creates an InputMap with no parent and no mappings.

Method Detail

setParent

public void setParent(InputMap map)
Sets this InputMap's parent.

Parameters:
map - the InputMap that is the parent of this one

getParent

public InputMap getParent()
Gets this InputMap's parent.

Returns:
map the InputMap that is the parent of this one, or null if this InputMap has no parent

put

public void put(KeyStroke keyStroke,
                Object actionMapKey)
Adds a binding for keyStroke to actionMapKey. If actionMapKey is null, this removes the current binding for keyStroke.

get

public Object get(KeyStroke keyStroke)
Returns the binding for keyStroke, messaging the parent InputMap if the binding is not locally defined.

remove

public void remove(KeyStroke key)
Removes the binding for key from this InputMap.

clear

public void clear()
Removes all the mappings from this InputMap.

keys

public KeyStroke[] keys()
Returns the KeyStrokes that are bound in this InputMap.

size

public int size()
Returns the number of KeyStroke bindings.

allKeys

public KeyStroke[] allKeys()
Returns an array of the KeyStrokes defined in this InputMap and its parent. This differs from keys() in that this method includes the keys defined in the parent.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InputVerifier

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class InputVerifier

java.lang.Object
    extended by  javax.swing.InputVerifier

public abstract class InputVerifier
extends Object

The purpose of this class is to help clients support smooth focus navigation through GUIs with text fields. Such GUIs often need to ensure that the text entered by the user is valid (for example, that it's in the proper format) before allowing the user to navigate out of the text field. To do this, clients create a subclass of InputVerifier and, using JComponent's setInputVerifier method, attach an instance of their subclass to the JComponent whose input they want to validate. Before focus is transfered to another Swing component that requests it, the input verifier's shouldYieldFocus method is called. Focus is transfered only if that method returns true.

The following example has two text fields, with the first one expecting the string "pass" to be entered by the user. If that string is entered in the first text field, then the user can advance to the second text field either by clicking in it or by pressing TAB. However, if another string is entered in the first text field, then the user will be unable to transfer focus to the second text field.

 import java.awt.*;
 import java.util.*;
 import java.awt.event.*;
 import javax.swing.*;

 // This program demonstrates the use of the Swing InputVerifier class.
 // It creates two text fields; the first of the text fields expects the
 // string "pass" as input, and will allow focus to advance out of it
 // only after that string is typed in by the user.

 public class VerifierTest extends JFrame {
     public VerifierTest() {
         JTextField tf1 = new JTextField ("Type \"pass\" here");
           getContentPane().add (tf1, BorderLayout.NORTH);
           tf1.setInputVerifier(new PassVerifier());

           JTextField tf2 = new JTextField ("TextField2");
           getContentPane().add (tf2, BorderLayout.SOUTH);

           WindowListener l = new WindowAdapter() {
               public void windowClosing(WindowEvent e) {
                   System.exit(0);
               }
           };
           addWindowListener(l);
     }

     class PassVerifier extends InputVerifier {
         public boolean verify(JComponent input) {
               JTextField tf = (JTextField) input;
               return "pass".equals(tf.getText());
         }
     }

     public static void main(String[] args) {
         Frame f = new VerifierTest();
           f.pack();
           f.setVisible(true);
     }
 }

Since:
1.3

Constructor Summary
InputVerifier()
Method Summary
boolean | shouldYieldFocus(JComponent input) Calls verify(input) to ensure that the input is valid.
abstract boolean | verify(JComponent input) Checks whether the JComponent's input is valid.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InputVerifier

public InputVerifier()
Method Detail

verify

public abstract boolean verify(JComponent input)
Checks whether the JComponent's input is valid. This method should have no side effects. It returns a boolean indicating the status of the argument's input.

Parameters:
input - the JComponent to verify
Returns:
true when valid, false when invalid
See Also:
JComponent.setInputVerifier(javax.swing.InputVerifier), JComponent.getInputVerifier()

shouldYieldFocus

public boolean shouldYieldFocus(JComponent input)
Calls verify(input) to ensure that the input is valid. This method can have side effects. In particular, this method is called when the user attempts to advance focus out of the argument component into another Swing component in this window. If this method returns true, then the focus is transfered normally; if it returns false, then the focus remains in the argument component.

Parameters:
input - the JComponent to verify
Returns:
true when valid, false when invalid
See Also:
JComponent.setInputVerifier(javax.swing.InputVerifier), JComponent.getInputVerifier()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InternalFrameFocusTraversalPolicy

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class InternalFrameFocusTraversalPolicy

java.lang.Object
    extended by  java.awt.FocusTraversalPolicy
        extended by  javax.swing.InternalFrameFocusTraversalPolicy
Direct Known Subclasses:
SortingFocusTraversalPolicy
public abstract class InternalFrameFocusTraversalPolicy
extends FocusTraversalPolicy

A FocusTraversalPolicy which can optionally provide an algorithm for determining a JInternalFrame's initial Component. The initial Component is the first to receive focus when the JInternalFrame is first selected. By default, this is the same as the JInternalFrame's default Component to focus.

Since:
1.4

Constructor Summary
InternalFrameFocusTraversalPolicy()
Method Summary
 Component getInitialComponent(JInternalFrame frame)
Returns the Component that should receive the focus when a JInternalFrame is selected for the first time.
Methods inherited from class java.awt.FocusTraversalPolicy
getComponentAfter, getComponentBefore, getDefaultComponent, getFirstComponent, getInitialComponent, getLastComponent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InternalFrameFocusTraversalPolicy

public InternalFrameFocusTraversalPolicy()
Method Detail

getInitialComponent

public Component getInitialComponent(JInternalFrame frame)
Returns the Component that should receive the focus when a JInternalFrame is selected for the first time. Once the JInternalFrame has been selected by a call to setSelected(true), the initial Component will not be used again. Instead, if the JInternalFrame loses and subsequently regains selection, or is made invisible or undisplayable and subsequently made visible and displayable, the JInternalFrame's most recently focused Component will become the focus owner. The default implementation of this method returns the JInternalFrame's default Component to focus.

Parameters:
frame - the JInternalFrame whose initial Component is to be returned
Returns:
the Component that should receive the focus when frame is selected for the first time, or null if no suitable Component can be found
Throws:
IllegalArgumentException - if window is null
See Also:
JInternalFrame.getMostRecentFocusOwner()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JApplet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JApplet

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  java.awt.Panel
                extended by  java.applet.Applet
                    extended by  javax.swing.JApplet
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, RootPaneContainer
public class JApplet
extends Applet
implements Accessible, RootPaneContainer

An extended version of java.applet.Applet that adds support for the JFC/Swing component architecture. You can find task-oriented documentation about using JApplet in The Java Tutorial, in the section How to Make Applets.

The JApplet class is slightly incompatible with java.applet.Applet. JApplet contains a JRootPane as its only child. The contentPane should be the parent of any children of the JApplet. As a convenience add and its variants, remove and setLayout have been overridden to forward to the contentPane as necessary. This means you can write:

       applet.add(child);
And the child will be added to the contentPane. The contentPane will always be non-null. Attempting to set it to null will cause the JApplet to throw an exception. The default contentPane will have a BorderLayout manager set on it. Refer to RootPaneContainer for details on adding, removing and setting the LayoutManager of a JApplet.

Please see the JRootPane documentation for a complete description of the contentPane, glassPane, and layeredPane properties.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
RootPaneContainer

Nested Class Summary
protected  class JApplet.AccessibleJApplet
This class implements accessibility support for the JApplet class.
Nested classes/interfaces inherited from class java.applet.Applet
Applet.AccessibleApplet
Nested classes/interfaces inherited from class java.awt.Panel
Panel.AccessibleAWTPanel
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected AccessibleContext | accessibleContext
protected JRootPane | rootPane
protected boolean | rootPaneCheckingEnabled If true then calls to add and setLayout will be forwarded to the contentPane.
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JApplet()
Creates a swing applet instance.
Method Summary
protected void | addImpl(Component comp, Object constraints, int index) Adds the specified child Component.
protected JRootPane | createRootPane() Called by the constructor methods to create the default rootPane.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JApplet.
Container | getContentPane() Returns the contentPane object for this applet.
Component | getGlassPane() Returns the glassPane object for this applet.
Graphics | getGraphics() Creates a graphics context for this component.
JMenuBar | getJMenuBar() Returns the menubar set on this applet.
JLayeredPane | getLayeredPane() Returns the layeredPane object for this applet.
JRootPane | getRootPane() Returns the rootPane object for this applet.
TransferHandler | getTransferHandler() Gets the transferHandler property.
protected boolean | isRootPaneCheckingEnabled() Returns whether calls to add and setLayout are forwarded to the contentPane.
protected String | paramString() Returns a string representation of this JApplet.
void | remove(Component comp) Removes the specified component from the container.
void | repaint(long time, int x, int y, int width, int height) Repaints the specified rectangle of this component within time milliseconds.
void | setContentPane(Container contentPane) Sets the contentPane property.
void | setGlassPane(Component glassPane) Sets the glassPane property.
void | setJMenuBar(JMenuBar menuBar) Sets the menubar for this applet.
void | setLayeredPane(JLayeredPane layeredPane) Sets the layeredPane property.
void | setLayout(LayoutManager manager) Sets the LayoutManager.
protected void | setRootPane(JRootPane root) Sets the rootPane property.
protected void | setRootPaneCheckingEnabled(boolean enabled) Sets whether calls to add and setLayout are forwarded to the contentPane.
void | setTransferHandler(TransferHandler newHandler) Sets the transferHandler property, which is a mechanism to support transfer of data into this component.
void | update(Graphics g) Just calls paint(g).
Methods inherited from class java.applet.Applet
destroy, getAppletContext, getAppletInfo, getAudioClip, getAudioClip, getCodeBase, getDocumentBase, getImage, getImage, getLocale, getParameter, getParameterInfo, init, isActive, newAudioClip, play, play, resize, resize, setStub, showStatus, start, stop
Methods inherited from class java.awt.Panel
addNotify
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getInsets, getLayout, getListeners, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paint, paintComponents, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, removeAll, removeContainerListener, removeNotify, setComponentZOrder, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

rootPane

protected JRootPane rootPane
See Also:
getRootPane(), setRootPane(javax.swing.JRootPane)

rootPaneCheckingEnabled

protected boolean rootPaneCheckingEnabled
If true then calls to add and setLayout will be forwarded to the contentPane. This is initially false, but is set to true when the JApplet is constructed.

See Also:
isRootPaneCheckingEnabled(), setRootPaneCheckingEnabled(boolean), RootPaneContainer

accessibleContext

protected AccessibleContext accessibleContext
Constructor Detail

JApplet

public JApplet()
        throws HeadlessException
Creates a swing applet instance.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
GraphicsEnvironment.isHeadless(), JComponent.getDefaultLocale()
Method Detail

createRootPane

protected JRootPane createRootPane()
Called by the constructor methods to create the default rootPane.

setTransferHandler

public void setTransferHandler(TransferHandler newHandler)
Sets the transferHandler property, which is a mechanism to support transfer of data into this component. Use null if the component does not support data transfer operations.

If the system property suppressSwingDropSupport is false (the default) and the current drop target on this component is either null or not a user-set drop target, this method will change the drop target as follows: If newHandler is null it will clear the drop target. If not null it will install a new DropTarget.

Note: When used with JApplet, TransferHandler only provides data import capability, as the data export related methods are currently typed to JComponent.

Please see How to Use Drag and Drop and Data Transfer, a section in The Java Tutorial, for more information.

Parameters:
newHandler - the new TransferHandler
Since:
1.6
See Also:
TransferHandler, getTransferHandler(), Component.setDropTarget(java.awt.dnd.DropTarget)

getTransferHandler

public TransferHandler getTransferHandler()
Gets the transferHandler property.

Returns:
the value of the transferHandler property
Since:
1.6
See Also:
TransferHandler, setTransferHandler(javax.swing.TransferHandler)

update

public void update(Graphics g)
Just calls paint(g). This method was overridden to prevent an unnecessary call to clear the background.

Overrides:
update in class Container
Parameters:
g - the specified Graphics window
See Also:
Component.update(Graphics)

setJMenuBar

public void setJMenuBar(JMenuBar menuBar)
Sets the menubar for this applet.

Parameters:
menuBar - the menubar being placed in the applet
See Also:
getJMenuBar()

getJMenuBar

public JMenuBar getJMenuBar()
Returns the menubar set on this applet.

See Also:
setJMenuBar(javax.swing.JMenuBar)

isRootPaneCheckingEnabled

protected boolean isRootPaneCheckingEnabled()
Returns whether calls to add and setLayout are forwarded to the contentPane.

Returns:
true if add and setLayout are fowarded; false otherwise
See Also:
addImpl(java.awt.Component, java.lang.Object, int), setLayout(java.awt.LayoutManager), setRootPaneCheckingEnabled(boolean), RootPaneContainer

setRootPaneCheckingEnabled

protected void setRootPaneCheckingEnabled(boolean enabled)
Sets whether calls to add and setLayout are forwarded to the contentPane.

Parameters:
enabled - true if add and setLayout are forwarded, false if they should operate directly on the JApplet.
See Also:
addImpl(java.awt.Component, java.lang.Object, int),
setLayout(java.awt.LayoutManager),
isRootPaneCheckingEnabled(),
RootPaneContainer

addImpl

protected void addImpl(Component comp,
                       Object constraints,
                       int index)
Adds the specified child Component. This method is overridden to conditionally forward calls to the contentPane. By default, children are added to the contentPane instead of the frame, refer to RootPaneContainer for details.

Overrides:
addImpl in class Container
Parameters:
comp - the component to be enhanced
constraints - the constraints to be respected
index - the index
Throws:
IllegalArgumentException - if index is invalid
IllegalArgumentException - if adding the container's parent to itself
IllegalArgumentException - if adding a window to a container
See Also:
setRootPaneCheckingEnabled(boolean), RootPaneContainer

remove

public void remove(Component comp)
Removes the specified component from the container. If comp is not the rootPane, this will forward the call to the contentPane. This will do nothing if comp is not a child of the JFrame or contentPane.

Overrides:
remove in class Container
Parameters:
comp - the component to be removed
Throws:
NullPointerException - if comp is null
See Also:
Container.add(java.awt.Component), RootPaneContainer

setLayout

public void setLayout(LayoutManager manager)
Sets the LayoutManager. Overridden to conditionally forward the call to the contentPane. Refer to RootPaneContainer for more information.

Overrides:
setLayout in class Container
Parameters:
manager - the LayoutManager
See Also:
setRootPaneCheckingEnabled(boolean), RootPaneContainer

getRootPane

public JRootPane getRootPane()
Returns the rootPane object for this applet.

Specified by:
getRootPane in interface RootPaneContainer
Returns:
this components single JRootPane child.
See Also:
setRootPane(javax.swing.JRootPane), RootPaneContainer.getRootPane()

setRootPane

protected void setRootPane(JRootPane root)
Sets the rootPane property. This method is called by the constructor.

Parameters:
root - the rootPane object for this applet
See Also:
getRootPane()

getContentPane

public Container getContentPane()
Returns the contentPane object for this applet.

Specified by:
getContentPane in interface RootPaneContainer
Returns:
the value of the contentPane property.
See Also:
setContentPane(java.awt.Container), RootPaneContainer.getContentPane()

setContentPane

public void setContentPane(Container contentPane)
Sets the contentPane property. This method is called by the constructor.

Specified by:
setContentPane in interface RootPaneContainer
Parameters:
contentPane - the contentPane object for this applet
Throws:
IllegalComponentStateException - (a runtime exception) if the content pane parameter is null
See Also:
getContentPane(), RootPaneContainer.setContentPane(java.awt.Container)

getLayeredPane

public JLayeredPane getLayeredPane()
Returns the layeredPane object for this applet.

Specified by:
getLayeredPane in interface RootPaneContainer
Returns:
the value of the layeredPane property.
Throws:
IllegalComponentStateException - (a runtime exception) if the layered pane parameter is null
See Also:
setLayeredPane(javax.swing.JLayeredPane), RootPaneContainer.getLayeredPane()

setLayeredPane

public void setLayeredPane(JLayeredPane layeredPane)
Sets the layeredPane property. This method is called by the constructor.

Specified by:
setLayeredPane in interface RootPaneContainer
Parameters:
layeredPane - the layeredPane object for this applet
See Also:
getLayeredPane(), RootPaneContainer.setLayeredPane(javax.swing.JLayeredPane)

getGlassPane

public Component getGlassPane()
Returns the glassPane object for this applet.

Specified by:
getGlassPane in interface RootPaneContainer
Returns:
the value of the glassPane property.
See Also:
setGlassPane(java.awt.Component), RootPaneContainer.getGlassPane()

setGlassPane

public void setGlassPane(Component glassPane)
Sets the glassPane property. This method is called by the constructor.

Specified by:
setGlassPane in interface RootPaneContainer
Parameters:
glassPane - the glassPane object for this applet
See Also:
getGlassPane(), RootPaneContainer.setGlassPane(java.awt.Component)

getGraphics

public Graphics getGraphics()
Creates a graphics context for this component. This method will return null if this component is currently not displayable.

Overrides:
getGraphics in class Component
Returns:
a graphics context for this component, or null if it has none
Since:
1.6
See Also:
Component.paint(java.awt.Graphics)

repaint

public void repaint(long time,
                    int x,
                    int y,
                    int width,
                    int height)
Repaints the specified rectangle of this component within time milliseconds. Refer to RepaintManager for details on how the repaint is handled.

Overrides:
repaint in class Component
Parameters:
time - maximum time in milliseconds before update
x - the x coordinate
y - the y coordinate
width - the width
height - the height
Since:
1.6
See Also:
RepaintManager

paramString

protected String paramString()
Returns a string representation of this JApplet. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class Container
Returns:
a string representation of this JApplet.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JApplet. For JApplets, the AccessibleContext takes the form of an AccessibleJApplet. A new AccessibleJApplet instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class Applet
Returns:
an AccessibleJApplet that serves as the AccessibleContext of this JApplet
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JApplet.AccessibleJApplet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JApplet.AccessibleJApplet

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  java.awt.Panel.AccessibleAWTPanel
                    extended by  java.applet.Applet.AccessibleApplet
                        extended by  javax.swing.JApplet.AccessibleJApplet
All Implemented Interfaces:
Serializable, AccessibleComponent
Enclosing class:
JApplet
protected class JApplet.AccessibleJApplet
extends Applet.AccessibleApplet

This class implements accessibility support for the JApplet class.

Nested Class Summary
Nested classes/interfaces inherited from class java.awt.Container.AccessibleAWTContainer
Container.AccessibleAWTContainer.AccessibleContainerHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class java.awt.Container.AccessibleAWTContainer
accessibleContainerHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JApplet.AccessibleJApplet()
Method Summary
Methods inherited from class java.applet.Applet.AccessibleApplet
getAccessibleRole, getAccessibleStateSet
Methods inherited from class java.awt.Container.AccessibleAWTContainer
addPropertyChangeListener, getAccessibleAt, getAccessibleChild, getAccessibleChildrenCount
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleDescription, getAccessibleIndexInParent, getAccessibleName, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, removePropertyChangeListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JApplet.AccessibleJApplet

protected JApplet.AccessibleJApplet()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JButton

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JButton

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.AbstractButton
                    extended by  javax.swing.JButton
All Implemented Interfaces:
ImageObserver, ItemSelectable, MenuContainer, Serializable, Accessible, SwingConstants
Direct Known Subclasses:
BasicArrowButton, MetalComboBoxButton
public class JButton
extends AbstractButton
implements Accessible

An implementation of a "push" button.

Buttons can be configured, and to some degree controlled, by Actions. Using an Action with a button has many benefits beyond directly configuring a button. Refer to Swing Components Supporting Action for more details, and you can find more information in How to Use Actions, a section in The Java Tutorial.

See How to Use Buttons, Check Boxes, and Radio Buttons in The Java Tutorial for information and examples of using buttons.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class JButton.AccessibleJButton
This class implements accessibility support for the JButton class.
Nested classes/interfaces inherited from class javax.swing.AbstractButton
AbstractButton.AccessibleAbstractButton, AbstractButton.ButtonChangeListener
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.AbstractButton
actionListener, BORDER_PAINTED_CHANGED_PROPERTY, changeEvent, changeListener, CONTENT_AREA_FILLED_CHANGED_PROPERTY, DISABLED_ICON_CHANGED_PROPERTY, DISABLED_SELECTED_ICON_CHANGED_PROPERTY, FOCUS_PAINTED_CHANGED_PROPERTY, HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY, HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY, ICON_CHANGED_PROPERTY, itemListener, MARGIN_CHANGED_PROPERTY, MNEMONIC_CHANGED_PROPERTY, model, MODEL_CHANGED_PROPERTY, PRESSED_ICON_CHANGED_PROPERTY, ROLLOVER_ENABLED_CHANGED_PROPERTY, ROLLOVER_ICON_CHANGED_PROPERTY, ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY, SELECTED_ICON_CHANGED_PROPERTY, TEXT_CHANGED_PROPERTY, VERTICAL_ALIGNMENT_CHANGED_PROPERTY, VERTICAL_TEXT_POSITION_CHANGED_PROPERTY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JButton()
Creates a button with no set text or icon.
JButton(Action a)
Creates a button where properties are taken from the Action supplied.
JButton(Icon icon)
Creates a button with an icon.
JButton(String text)
Creates a button with text.
JButton(String text, Icon icon)
Creates a button with initial text and an icon.
Method Summary
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JButton.
String | getUIClassID() Returns a string that specifies the name of the L&F class that renders this component.
boolean | isDefaultButton() Gets the value of the defaultButton property, which if true means that this button is the current default button for its JRootPane.
boolean | isDefaultCapable() Gets the value of the defaultCapable property.
protected String | paramString() Returns a string representation of this JButton.
void | removeNotify() Overrides JComponent.removeNotify to check if this button is currently set as the default button on the RootPane, and if so, sets the RootPane's default button to null to ensure the RootPane doesn't hold onto an invalid button reference.
void | setDefaultCapable(boolean defaultCapable) Sets the defaultCapable property, which determines whether this button can be made the default button for its root pane.
void | updateUI() Resets the UI property to a value from the current look and feel.
Methods inherited from class javax.swing.AbstractButton
actionPropertyChanged, addActionListener, addChangeListener, addImpl, addItemListener, checkHorizontalKey, checkVerticalKey, configurePropertiesFromAction, createActionListener, createActionPropertyChangeListener, createChangeListener, createItemListener, doClick, doClick, fireActionPerformed, fireItemStateChanged, fireStateChanged, getAction, getActionCommand, getActionListeners, getChangeListeners, getDisabledIcon, getDisabledSelectedIcon, getDisplayedMnemonicIndex, getHideActionText, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getItemListeners, getLabel, getMargin, getMnemonic, getModel, getMultiClickThreshhold, getPressedIcon, getRolloverIcon, getRolloverSelectedIcon, getSelectedIcon, getSelectedObjects, getText, getUI, getVerticalAlignment, getVerticalTextPosition, imageUpdate, init, isBorderPainted, isContentAreaFilled, isFocusPainted, isRolloverEnabled, isSelected, paintBorder, removeActionListener, removeChangeListener, removeItemListener, setAction, setActionCommand, setBorderPainted, setContentAreaFilled, setDisabledIcon, setDisabledSelectedIcon, setDisplayedMnemonicIndex, setEnabled, setFocusPainted, setHideActionText, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabel, setLayout, setMargin, setMnemonic, setMnemonic, setModel, setMultiClickThreshhold, setPressedIcon, setRolloverEnabled, setRolloverIcon, setRolloverSelectedIcon, setSelected, setSelectedIcon, setText, setUI, setVerticalAlignment, setVerticalTextPosition
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JButton

public JButton()
Creates a button with no set text or icon.

JButton

public JButton(Icon icon)
Creates a button with an icon.

Parameters:
icon - the Icon image to display on the button

JButton

public JButton(String text)
Creates a button with text.

Parameters:
text - the text of the button

JButton

public JButton(Action a)
Creates a button where properties are taken from the Action supplied.

Parameters:
a - the Action used to specify the new button
Since:
1.3

JButton

public JButton(String text,
               Icon icon)
Creates a button with initial text and an icon.

Parameters:
text - the text of the button
icon - the Icon image to display on the button
Method Detail

updateUI

public void updateUI()
Resets the UI property to a value from the current look and feel.

Overrides:
updateUI in class AbstractButton
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns a string that specifies the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "ButtonUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

isDefaultButton

public boolean isDefaultButton()
Gets the value of the defaultButton property, which if true means that this button is the current default button for its JRootPane. Most look and feels render the default button differently, and may potentially provide bindings to access the default button.

Returns:
the value of the defaultButton property
See Also:
JRootPane.setDefaultButton(javax.swing.JButton), isDefaultCapable()

isDefaultCapable

public boolean isDefaultCapable()
Gets the value of the defaultCapable property.

Returns:
the value of the defaultCapable property
See Also:
setDefaultCapable(boolean), isDefaultButton(), JRootPane.setDefaultButton(javax.swing.JButton)

setDefaultCapable

public void setDefaultCapable(boolean defaultCapable)
Sets the defaultCapable property, which determines whether this button can be made the default button for its root pane. The default value of the defaultCapable property is true unless otherwise specified by the look and feel.

Parameters:
defaultCapable - true if this button will be capable of being the default button on the RootPane; otherwise false
See Also:
isDefaultCapable()

removeNotify

public void removeNotify()
Overrides JComponent.removeNotify to check if this button is currently set as the default button on the RootPane, and if so, sets the RootPane's default button to null to ensure the RootPane doesn't hold onto an invalid button reference.

Overrides:
removeNotify in class AbstractButton
See Also:
JComponent.registerKeyboardAction(java.awt.event.ActionListener, java.lang.String, javax.swing.KeyStroke, int)

paramString

protected String paramString()
Returns a string representation of this JButton. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class AbstractButton
Returns:
a string representation of this JButton

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JButton. For JButtons, the AccessibleContext takes the form of an AccessibleJButton. A new AccessibleJButton instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJButton that serves as the AccessibleContext of this JButton
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JButton.AccessibleJButton

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JButton.AccessibleJButton

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.AbstractButton.AccessibleAbstractButton
                        extended by  javax.swing.JButton.AccessibleJButton
All Implemented Interfaces:
Serializable, AccessibleAction, AccessibleComponent, AccessibleExtendedComponent, AccessibleText, AccessibleValue
Enclosing class:
JButton
protected class JButton.AccessibleJButton
extends AbstractButton.AccessibleAbstractButton

This class implements accessibility support for the JButton class. It provides an implementation of the Java Accessibility API appropriate to button user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Constructor Summary
protected JButton.AccessibleJButton()
Method Summary
 AccessibleRole getAccessibleRole()
Get the role of this object.
Methods inherited from class javax.swing.AbstractButton.AccessibleAbstractButton
doAccessibleAction, getAccessibleAction, getAccessibleActionCount, getAccessibleActionDescription, getAccessibleIcon, getAccessibleKeyBinding, getAccessibleName, getAccessibleRelationSet, getAccessibleStateSet, getAccessibleText, getAccessibleValue, getAfterIndex, getAtIndex, getBeforeIndex, getCaretPosition, getCharacterAttribute, getCharacterBounds, getCharCount, getCurrentAccessibleValue, getIndexAtPoint, getMaximumAccessibleValue, getMinimumAccessibleValue, getSelectedText, getSelectionEnd, getSelectionStart, getTitledBorderText, getToolTipText, setCurrentAccessibleValue
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getBorderTitle, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleEditableText, getAccessibleSelection, getAccessibleTable, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JButton.AccessibleJButton

protected JButton.AccessibleJButton()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JCheckBox

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JCheckBox

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.AbstractButton
                    extended by  javax.swing.JToggleButton
                        extended by  javax.swing.JCheckBox
All Implemented Interfaces:
ImageObserver, ItemSelectable, MenuContainer, Serializable, Accessible, SwingConstants
public class JCheckBox
extends JToggleButton
implements Accessible

An implementation of a check box -- an item that can be selected or deselected, and which displays its state to the user. By convention, any number of check boxes in a group can be selected. See How to Use Buttons, Check Boxes, and Radio Buttons in The Java Tutorial for examples and information on using check boxes.

Buttons can be configured, and to some degree controlled, by Actions. Using an Action with a button has many benefits beyond directly configuring a button. Refer to Swing Components Supporting Action for more details, and you can find more information in How to Use Actions, a section in The Java Tutorial.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JRadioButton

Nested Class Summary
protected  class JCheckBox.AccessibleJCheckBox
This class implements accessibility support for the JCheckBox class.
Nested classes/interfaces inherited from class javax.swing.JToggleButton
JToggleButton.AccessibleJToggleButton, JToggleButton.ToggleButtonModel
Nested classes/interfaces inherited from class javax.swing.AbstractButton
AbstractButton.AccessibleAbstractButton, AbstractButton.ButtonChangeListener
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
static String BORDER_PAINTED_FLAT_CHANGED_PROPERTY
Identifies a change to the flat property.
Fields inherited from class javax.swing.AbstractButton
actionListener, BORDER_PAINTED_CHANGED_PROPERTY, changeEvent, changeListener, CONTENT_AREA_FILLED_CHANGED_PROPERTY, DISABLED_ICON_CHANGED_PROPERTY, DISABLED_SELECTED_ICON_CHANGED_PROPERTY, FOCUS_PAINTED_CHANGED_PROPERTY, HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY, HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY, ICON_CHANGED_PROPERTY, itemListener, MARGIN_CHANGED_PROPERTY, MNEMONIC_CHANGED_PROPERTY, model, MODEL_CHANGED_PROPERTY, PRESSED_ICON_CHANGED_PROPERTY, ROLLOVER_ENABLED_CHANGED_PROPERTY, ROLLOVER_ICON_CHANGED_PROPERTY, ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY, SELECTED_ICON_CHANGED_PROPERTY, TEXT_CHANGED_PROPERTY, VERTICAL_ALIGNMENT_CHANGED_PROPERTY, VERTICAL_TEXT_POSITION_CHANGED_PROPERTY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JCheckBox()
Creates an initially unselected check box button with no text, no icon.
JCheckBox(Action a)
Creates a check box where properties are taken from the Action supplied.
JCheckBox(Icon icon)
Creates an initially unselected check box with an icon.
JCheckBox(Icon icon, boolean selected)
Creates a check box with an icon and specifies whether or not it is initially selected.
JCheckBox(String text)
Creates an initially unselected check box with text.
JCheckBox(String text, boolean selected)
Creates a check box with text and specifies whether or not it is initially selected.
JCheckBox(String text, Icon icon)
Creates an initially unselected check box with the specified text and icon.
JCheckBox(String text, Icon icon, boolean selected)
Creates a check box with text and icon, and specifies whether or not it is initially selected.
Method Summary
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JCheckBox.
String | getUIClassID() Returns a string that specifies the name of the L&F class that renders this component.
boolean | isBorderPaintedFlat() Gets the value of the borderPaintedFlat property.
protected String | paramString() Returns a string representation of this JCheckBox.
void | setBorderPaintedFlat(boolean b) Sets the borderPaintedFlat property, which gives a hint to the look and feel as to the appearance of the check box border.
void | updateUI() Resets the UI property to a value from the current look and feel.
Methods inherited from class javax.swing.AbstractButton
actionPropertyChanged, addActionListener, addChangeListener, addImpl, addItemListener, checkHorizontalKey, checkVerticalKey, configurePropertiesFromAction, createActionListener, createActionPropertyChangeListener, createChangeListener, createItemListener, doClick, doClick, fireActionPerformed, fireItemStateChanged, fireStateChanged, getAction, getActionCommand, getActionListeners, getChangeListeners, getDisabledIcon, getDisabledSelectedIcon, getDisplayedMnemonicIndex, getHideActionText, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getItemListeners, getLabel, getMargin, getMnemonic, getModel, getMultiClickThreshhold, getPressedIcon, getRolloverIcon, getRolloverSelectedIcon, getSelectedIcon, getSelectedObjects, getText, getUI, getVerticalAlignment, getVerticalTextPosition, imageUpdate, init, isBorderPainted, isContentAreaFilled, isFocusPainted, isRolloverEnabled, isSelected, paintBorder, removeActionListener, removeChangeListener, removeItemListener, removeNotify, setAction, setActionCommand, setBorderPainted, setContentAreaFilled, setDisabledIcon, setDisabledSelectedIcon, setDisplayedMnemonicIndex, setEnabled, setFocusPainted, setHideActionText, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabel, setLayout, setMargin, setMnemonic, setMnemonic, setModel, setMultiClickThreshhold, setPressedIcon, setRolloverEnabled, setRolloverIcon, setRolloverSelectedIcon, setSelected, setSelectedIcon, setText, setUI, setVerticalAlignment, setVerticalTextPosition
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

BORDER_PAINTED_FLAT_CHANGED_PROPERTY

public static final String BORDER_PAINTED_FLAT_CHANGED_PROPERTY
Identifies a change to the flat property.

See Also:
Constant Field Values
Constructor Detail

JCheckBox

public JCheckBox()
Creates an initially unselected check box button with no text, no icon.

JCheckBox

public JCheckBox(Icon icon)
Creates an initially unselected check box with an icon.

Parameters:
icon - the Icon image to display

JCheckBox

public JCheckBox(Icon icon,
                 boolean selected)
Creates a check box with an icon and specifies whether or not it is initially selected.

Parameters:
icon - the Icon image to display
selected - a boolean value indicating the initial selection state. If true the check box is selected

JCheckBox

public JCheckBox(String text)
Creates an initially unselected check box with text.

Parameters:
text - the text of the check box.

JCheckBox

public JCheckBox(Action a)
Creates a check box where properties are taken from the Action supplied.

Since:
1.3

JCheckBox

public JCheckBox(String text,
                 boolean selected)
Creates a check box with text and specifies whether or not it is initially selected.

Parameters:
text - the text of the check box.
selected - a boolean value indicating the initial selection state. If true the check box is selected

JCheckBox

public JCheckBox(String text,
                 Icon icon)
Creates an initially unselected check box with the specified text and icon.

Parameters:
text - the text of the check box.
icon - the Icon image to display

JCheckBox

public JCheckBox(String text,
                 Icon icon,
                 boolean selected)
Creates a check box with text and icon, and specifies whether or not it is initially selected.

Parameters:
text - the text of the check box.
icon - the Icon image to display
selected - a boolean value indicating the initial selection state. If true the check box is selected
Method Detail

setBorderPaintedFlat

public void setBorderPaintedFlat(boolean b)
Sets the borderPaintedFlat property, which gives a hint to the look and feel as to the appearance of the check box border. This is usually set to true when a JCheckBox instance is used as a renderer in a component such as a JTable or JTree. The default value for the borderPaintedFlat property is false. This method fires a property changed event. Some look and feels might not implement flat borders; they will ignore this property.

Parameters:
b - true requests that the border be painted flat; false requests normal borders
Since:
1.3
See Also:
isBorderPaintedFlat()

isBorderPaintedFlat

public boolean isBorderPaintedFlat()
Gets the value of the borderPaintedFlat property.

Returns:
the value of the borderPaintedFlat property
Since:
1.3
See Also:
setBorderPaintedFlat(boolean)

updateUI

public void updateUI()
Resets the UI property to a value from the current look and feel.

Overrides:
updateUI in class JToggleButton
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns a string that specifies the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JToggleButton
Returns:
the string "CheckBoxUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

paramString

protected String paramString()
Returns a string representation of this JCheckBox. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null. specific new aspects of the JFC components.

Overrides:
paramString in class JToggleButton
Returns:
a string representation of this JCheckBox.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JCheckBox. For JCheckBoxes, the AccessibleContext takes the form of an AccessibleJCheckBox. A new AccessibleJCheckBox instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JToggleButton
Returns:
an AccessibleJCheckBox that serves as the AccessibleContext of this JCheckBox
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JCheckBox.AccessibleJCheckBox

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JCheckBox.AccessibleJCheckBox

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.AbstractButton.AccessibleAbstractButton
                        extended by  javax.swing.JToggleButton.AccessibleJToggleButton
                            extended by  javax.swing.JCheckBox.AccessibleJCheckBox
All Implemented Interfaces:
ItemListener, Serializable, EventListener, AccessibleAction, AccessibleComponent, AccessibleExtendedComponent, AccessibleText, AccessibleValue
Enclosing class:
JCheckBox
protected class JCheckBox.AccessibleJCheckBox
extends JToggleButton.AccessibleJToggleButton

This class implements accessibility support for the JCheckBox class. It provides an implementation of the Java Accessibility API appropriate to check box user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Constructor Summary
protected JCheckBox.AccessibleJCheckBox()
Method Summary
 AccessibleRole getAccessibleRole()
Get the role of this object.
Methods inherited from class javax.swing.JToggleButton.AccessibleJToggleButton
itemStateChanged
Methods inherited from class javax.swing.AbstractButton.AccessibleAbstractButton
doAccessibleAction, getAccessibleAction, getAccessibleActionCount, getAccessibleActionDescription, getAccessibleIcon, getAccessibleKeyBinding, getAccessibleName, getAccessibleRelationSet, getAccessibleStateSet, getAccessibleText, getAccessibleValue, getAfterIndex, getAtIndex, getBeforeIndex, getCaretPosition, getCharacterAttribute, getCharacterBounds, getCharCount, getCurrentAccessibleValue, getIndexAtPoint, getMaximumAccessibleValue, getMinimumAccessibleValue, getSelectedText, getSelectionEnd, getSelectionStart, getTitledBorderText, getToolTipText, setCurrentAccessibleValue
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getBorderTitle, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleEditableText, getAccessibleSelection, getAccessibleTable, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JCheckBox.AccessibleJCheckBox

protected JCheckBox.AccessibleJCheckBox()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JToggleButton.AccessibleJToggleButton
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JCheckBoxMenuItem

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JCheckBoxMenuItem

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.AbstractButton
                    extended by  javax.swing.JMenuItem
                        extended by  javax.swing.JCheckBoxMenuItem
All Implemented Interfaces:
ImageObserver, ItemSelectable, MenuContainer, Serializable, Accessible, MenuElement, SwingConstants
public class JCheckBoxMenuItem
extends JMenuItem
implements SwingConstants, Accessible

A menu item that can be selected or deselected. If selected, the menu item typically appears with a checkmark next to it. If unselected or deselected, the menu item appears without a checkmark. Like a regular menu item, a check box menu item can have either text or a graphic icon associated with it, or both.

Either isSelected/setSelected or getState/setState can be used to determine/specify the menu item's selection state. The preferred methods are isSelected and setSelected, which work for all menus and buttons. The getState and setState methods exist for compatibility with other component sets.

Menu items can be configured, and to some degree controlled, by Actions. Using an Action with a menu item has many benefits beyond directly configuring a menu item. Refer to Swing Components Supporting Action for more details, and you can find more information in How to Use Actions, a section in The Java Tutorial.

For further information and examples of using check box menu items, see How to Use Menus, a section in The Java Tutorial.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem
This class implements accessibility support for the JCheckBoxMenuItem class.
Nested classes/interfaces inherited from class javax.swing.JMenuItem
JMenuItem.AccessibleJMenuItem
Nested classes/interfaces inherited from class javax.swing.AbstractButton
AbstractButton.AccessibleAbstractButton, AbstractButton.ButtonChangeListener
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.AbstractButton
actionListener, BORDER_PAINTED_CHANGED_PROPERTY, changeEvent, changeListener, CONTENT_AREA_FILLED_CHANGED_PROPERTY, DISABLED_ICON_CHANGED_PROPERTY, DISABLED_SELECTED_ICON_CHANGED_PROPERTY, FOCUS_PAINTED_CHANGED_PROPERTY, HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY, HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY, ICON_CHANGED_PROPERTY, itemListener, MARGIN_CHANGED_PROPERTY, MNEMONIC_CHANGED_PROPERTY, model, MODEL_CHANGED_PROPERTY, PRESSED_ICON_CHANGED_PROPERTY, ROLLOVER_ENABLED_CHANGED_PROPERTY, ROLLOVER_ICON_CHANGED_PROPERTY, ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY, SELECTED_ICON_CHANGED_PROPERTY, TEXT_CHANGED_PROPERTY, VERTICAL_ALIGNMENT_CHANGED_PROPERTY, VERTICAL_TEXT_POSITION_CHANGED_PROPERTY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JCheckBoxMenuItem()
Creates an initially unselected check box menu item with no set text or icon.
JCheckBoxMenuItem(Action a)
Creates a menu item whose properties are taken from the Action supplied.
JCheckBoxMenuItem(Icon icon)
Creates an initially unselected check box menu item with an icon.
JCheckBoxMenuItem(String text)
Creates an initially unselected check box menu item with text.
JCheckBoxMenuItem(String text, boolean b)
Creates a check box menu item with the specified text and selection state.
JCheckBoxMenuItem(String text, Icon icon)
Creates an initially unselected check box menu item with the specified text and icon.
JCheckBoxMenuItem(String text, Icon icon, boolean b)
Creates a check box menu item with the specified text, icon, and selection state.
Method Summary
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JCheckBoxMenuItem.
Object[] | getSelectedObjects() Returns an array (length 1) containing the check box menu item label or null if the check box is not selected.
boolean | getState() Returns the selected-state of the item.
String | getUIClassID() Returns the name of the L&F class that renders this component.
protected String | paramString() Returns a string representation of this JCheckBoxMenuItem.
void | setState(boolean b) Sets the selected-state of the item.
Methods inherited from class javax.swing.JMenuItem
actionPropertyChanged, addMenuDragMouseListener, addMenuKeyListener, configurePropertiesFromAction, fireMenuDragMouseDragged, fireMenuDragMouseEntered, fireMenuDragMouseExited, fireMenuDragMouseReleased, fireMenuKeyPressed, fireMenuKeyReleased, fireMenuKeyTyped, getAccelerator, getComponent, getMenuDragMouseListeners, getMenuKeyListeners, getSubElements, init, isArmed, menuSelectionChanged, processKeyEvent, processMenuDragMouseEvent, processMenuKeyEvent, processMouseEvent, removeMenuDragMouseListener, removeMenuKeyListener, setAccelerator, setArmed, setEnabled, setModel, setUI, updateUI
Methods inherited from class javax.swing.AbstractButton
addActionListener, addChangeListener, addImpl, addItemListener, checkHorizontalKey, checkVerticalKey, createActionListener, createActionPropertyChangeListener, createChangeListener, createItemListener, doClick, doClick, fireActionPerformed, fireItemStateChanged, fireStateChanged, getAction, getActionCommand, getActionListeners, getChangeListeners, getDisabledIcon, getDisabledSelectedIcon, getDisplayedMnemonicIndex, getHideActionText, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getItemListeners, getLabel, getMargin, getMnemonic, getModel, getMultiClickThreshhold, getPressedIcon, getRolloverIcon, getRolloverSelectedIcon, getSelectedIcon, getText, getUI, getVerticalAlignment, getVerticalTextPosition, imageUpdate, isBorderPainted, isContentAreaFilled, isFocusPainted, isRolloverEnabled, isSelected, paintBorder, removeActionListener, removeChangeListener, removeItemListener, removeNotify, setAction, setActionCommand, setBorderPainted, setContentAreaFilled, setDisabledIcon, setDisabledSelectedIcon, setDisplayedMnemonicIndex, setFocusPainted, setHideActionText, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabel, setLayout, setMargin, setMnemonic, setMnemonic, setMultiClickThreshhold, setPressedIcon, setRolloverEnabled, setRolloverIcon, setRolloverSelectedIcon, setSelected, setSelectedIcon, setText, setUI, setVerticalAlignment, setVerticalTextPosition
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JCheckBoxMenuItem

public JCheckBoxMenuItem()
Creates an initially unselected check box menu item with no set text or icon.

JCheckBoxMenuItem

public JCheckBoxMenuItem(Icon icon)
Creates an initially unselected check box menu item with an icon.

Parameters:
icon - the icon of the CheckBoxMenuItem.

JCheckBoxMenuItem

public JCheckBoxMenuItem(String text)
Creates an initially unselected check box menu item with text.

Parameters:
text - the text of the CheckBoxMenuItem

JCheckBoxMenuItem

public JCheckBoxMenuItem(Action a)
Creates a menu item whose properties are taken from the Action supplied.

Since:
1.3

JCheckBoxMenuItem

public JCheckBoxMenuItem(String text,
                         Icon icon)
Creates an initially unselected check box menu item with the specified text and icon.

Parameters:
text - the text of the CheckBoxMenuItem
icon - the icon of the CheckBoxMenuItem

JCheckBoxMenuItem

public JCheckBoxMenuItem(String text,
                         boolean b)
Creates a check box menu item with the specified text and selection state.

Parameters:
text - the text of the check box menu item.
b - the selected state of the check box menu item

JCheckBoxMenuItem

public JCheckBoxMenuItem(String text,
                         Icon icon,
                         boolean b)
Creates a check box menu item with the specified text, icon, and selection state.

Parameters:
text - the text of the check box menu item
icon - the icon of the check box menu item
b - the selected state of the check box menu item
Method Detail

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JMenuItem
Returns:
"CheckBoxMenuItemUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

getState

public boolean getState()
Returns the selected-state of the item. This method exists for AWT compatibility only. New code should use isSelected() instead.

Returns:
true if the item is selected

setState

public void setState(boolean b)
Sets the selected-state of the item. This method exists for AWT compatibility only. New code should use setSelected() instead.

Parameters:
b - a boolean value indicating the item's selected-state, where true=selected

getSelectedObjects

public Object[] getSelectedObjects()
Returns an array (length 1) containing the check box menu item label or null if the check box is not selected.

Specified by:
getSelectedObjects in interface ItemSelectable
Overrides:
getSelectedObjects in class AbstractButton
Returns:
an array containing one Object -- the text of the menu item -- if the item is selected; otherwise null

paramString

protected String paramString()
Returns a string representation of this JCheckBoxMenuItem. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JMenuItem
Returns:
a string representation of this JCheckBoxMenuItem.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JCheckBoxMenuItem. For JCheckBoxMenuItems, the AccessibleContext takes the form of an AccessibleJCheckBoxMenuItem. A new AccessibleJCheckBoxMenuItem instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JMenuItem
Returns:
an AccessibleJCheckBoxMenuItem that serves as the AccessibleContext of this AccessibleJCheckBoxMenuItem
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.AbstractButton.AccessibleAbstractButton
                        extended by  javax.swing.JMenuItem.AccessibleJMenuItem
                            extended by  javax.swing.JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem
All Implemented Interfaces:
Serializable, EventListener, AccessibleAction, AccessibleComponent, AccessibleExtendedComponent, AccessibleText, AccessibleValue, ChangeListener
Enclosing class:
JCheckBoxMenuItem
protected class JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem
extends JMenuItem.AccessibleJMenuItem

This class implements accessibility support for the JCheckBoxMenuItem class. It provides an implementation of the Java Accessibility API appropriate to checkbox menu item user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Constructor Summary
protected JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem()
Method Summary
 AccessibleRole getAccessibleRole()
Get the role of this object.
Methods inherited from class javax.swing.JMenuItem.AccessibleJMenuItem
stateChanged
Methods inherited from class javax.swing.AbstractButton.AccessibleAbstractButton
doAccessibleAction, getAccessibleAction, getAccessibleActionCount, getAccessibleActionDescription, getAccessibleIcon, getAccessibleKeyBinding, getAccessibleName, getAccessibleRelationSet, getAccessibleStateSet, getAccessibleText, getAccessibleValue, getAfterIndex, getAtIndex, getBeforeIndex, getCaretPosition, getCharacterAttribute, getCharacterBounds, getCharCount, getCurrentAccessibleValue, getIndexAtPoint, getMaximumAccessibleValue, getMinimumAccessibleValue, getSelectedText, getSelectionEnd, getSelectionStart, getTitledBorderText, getToolTipText, setCurrentAccessibleValue
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getBorderTitle, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleEditableText, getAccessibleSelection, getAccessibleTable, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem

protected JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JMenuItem.AccessibleJMenuItem
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JColorChooser

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JColorChooser

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JColorChooser
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public class JColorChooser
extends JComponent
implements Accessible

JColorChooser provides a pane of controls designed to allow a user to manipulate and select a color. For information about using color choosers, see How to Use Color Choosers, a section in The Java Tutorial.

This class provides three levels of API:

  1. A static convenience method which shows a modal color-chooser dialog and returns the color selected by the user.
  2. A static convenience method for creating a color-chooser dialog where ActionListeners can be specified to be invoked when the user presses one of the dialog buttons.
  3. The ability to create instances of JColorChooser panes directly (within any container). PropertyChange listeners can be added to detect when the current "color" property changes.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class JColorChooser.AccessibleJColorChooser
This class implements accessibility support for the JColorChooser class.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected AccessibleContext | accessibleContext
static String | CHOOSER_PANELS_PROPERTY The chooserPanel array property name.
static String | PREVIEW_PANEL_PROPERTY The preview panel property name.
static String | SELECTION_MODEL_PROPERTY The selection model property name.
Fields inherited from class javax.swing.JComponent
listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JColorChooser()
Creates a color chooser pane with an initial color of white.
JColorChooser(Color initialColor)
Creates a color chooser pane with the specified initial color.
JColorChooser(ColorSelectionModel model)
Creates a color chooser pane with the specified ColorSelectionModel.
Method Summary
void | addChooserPanel(AbstractColorChooserPanel panel) Adds a color chooser panel to the color chooser.
static JDialog | createDialog(Component c, String title, boolean modal, JColorChooser chooserPane, ActionListener okListener, ActionListener cancelListener) Creates and returns a new dialog containing the specified ColorChooser pane along with "OK", "Cancel", and "Reset" buttons.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JColorChooser.
AbstractColorChooserPanel[] | getChooserPanels() Returns the specified color panels.
Color | getColor() Gets the current color value from the color chooser.
boolean | getDragEnabled() Gets the value of the dragEnabled property.
JComponent | getPreviewPanel() Returns the preview panel that shows a chosen color.
ColorSelectionModel | getSelectionModel() Returns the data model that handles color selections.
ColorChooserUI | getUI() Returns the L&F object that renders this component.
String | getUIClassID() Returns the name of the L&F class that renders this component.
protected String | paramString() Returns a string representation of this JColorChooser.
AbstractColorChooserPanel | removeChooserPanel(AbstractColorChooserPanel panel) Removes the Color Panel specified.
void | setChooserPanels(AbstractColorChooserPanel[] panels) Specifies the Color Panels used to choose a color value.
void | setColor(Color color) Sets the current color of the color chooser to the specified color.
void | setColor(int c) Sets the current color of the color chooser to the specified color.
void | setColor(int r, int g, int b) Sets the current color of the color chooser to the specified RGB color.
void | setDragEnabled(boolean b) Sets the dragEnabled property, which must be true to enable automatic drag handling (the first part of drag and drop) on this component.
void | setPreviewPanel(JComponent preview) Sets the current preview panel.
void | setSelectionModel(ColorSelectionModel newModel) Sets the model containing the selected color.
void | setUI(ColorChooserUI ui) Sets the L&F object that renders this component.
static Color | showDialog(Component component, String title, Color initialColor) Shows a modal color-chooser dialog and blocks until the dialog is hidden.
void | updateUI() Notification from the UIManager that the L&F has changed.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

SELECTION_MODEL_PROPERTY

public static final String SELECTION_MODEL_PROPERTY
The selection model property name.

See Also:
Constant Field Values

PREVIEW_PANEL_PROPERTY

public static final String PREVIEW_PANEL_PROPERTY
The preview panel property name.

See Also:
Constant Field Values

CHOOSER_PANELS_PROPERTY

public static final String CHOOSER_PANELS_PROPERTY
The chooserPanel array property name.

See Also:
Constant Field Values

accessibleContext

protected AccessibleContext accessibleContext
Constructor Detail

JColorChooser

public JColorChooser()
Creates a color chooser pane with an initial color of white.

JColorChooser

public JColorChooser(Color initialColor)
Creates a color chooser pane with the specified initial color.

Parameters:
initialColor - the initial color set in the chooser

JColorChooser

public JColorChooser(ColorSelectionModel model)
Creates a color chooser pane with the specified ColorSelectionModel.

Parameters:
model - the ColorSelectionModel to be used
Method Detail

showDialog

public static Color showDialog(Component component,
                               String title,
                               Color initialColor)
                        throws HeadlessException
Shows a modal color-chooser dialog and blocks until the dialog is hidden. If the user presses the "OK" button, then this method hides/disposes the dialog and returns the selected color. If the user presses the "Cancel" button or closes the dialog without pressing "OK", then this method hides/disposes the dialog and returns null.

Parameters:
component - the parent Component for the dialog
title - the String containing the dialog's title
initialColor - the initial Color set when the color-chooser is shown
Returns:
the selected color or null if the user opted out
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
GraphicsEnvironment.isHeadless()

createDialog

public static JDialog createDialog(Component c,
                                   String title,
                                   boolean modal,
                                   JColorChooser chooserPane,
                                   ActionListener okListener,
                                   ActionListener cancelListener)
                            throws HeadlessException
Creates and returns a new dialog containing the specified ColorChooser pane along with "OK", "Cancel", and "Reset" buttons. If the "OK" or "Cancel" buttons are pressed, the dialog is automatically hidden (but not disposed). If the "Reset" button is pressed, the color-chooser's color will be reset to the color which was set the last time show was invoked on the dialog and the dialog will remain showing.

Parameters:
c - the parent component for the dialog
title - the title for the dialog
modal - a boolean. When true, the remainder of the program is inactive until the dialog is closed.
chooserPane - the color-chooser to be placed inside the dialog
okListener - the ActionListener invoked when "OK" is pressed
cancelListener - the ActionListener invoked when "Cancel" is pressed
Returns:
a new dialog containing the color-chooser pane
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
GraphicsEnvironment.isHeadless()

getUI

public ColorChooserUI getUI()
Returns the L&F object that renders this component.

Returns:
the ColorChooserUI object that renders this component

setUI

public void setUI(ColorChooserUI ui)
Sets the L&F object that renders this component.

Parameters:
ui - the ColorChooserUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Notification from the UIManager that the L&F has changed. Replaces the current UI object with the latest version from the UIManager.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "ColorChooserUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

getColor

public Color getColor()
Gets the current color value from the color chooser. By default, this delegates to the model.

Returns:
the current color value of the color chooser

setColor

public void setColor(Color color)
Sets the current color of the color chooser to the specified color. The ColorSelectionModel will fire a ChangeEvent

Parameters:
color - the color to be set in the color chooser
See Also:
Container.addPropertyChangeListener(java.beans.PropertyChangeListener)

setColor

public void setColor(int r,
                     int g,
                     int b)
Sets the current color of the color chooser to the specified RGB color. Note that the values of red, green, and blue should be between the numbers 0 and 255, inclusive.

Parameters:
r - an int specifying the amount of Red
g - an int specifying the amount of Green
b - an int specifying the amount of Blue
Throws:
IllegalArgumentException - if r,g,b values are out of range
See Also:
Color

setColor

public void setColor(int c)
Sets the current color of the color chooser to the specified color.

Parameters:
c - an integer value that sets the current color in the chooser where the low-order 8 bits specify the Blue value, the next 8 bits specify the Green value, and the 8 bits above that specify the Red value.

setDragEnabled

public void setDragEnabled(boolean b)
Sets the dragEnabled property, which must be true to enable automatic drag handling (the first part of drag and drop) on this component. The transferHandler property needs to be set to a non-null value for the drag to do anything. The default value of the dragEnabled property is false.

When automatic drag handling is enabled, most look and feels begin a drag-and-drop operation when the user presses the mouse button over the preview panel. Some look and feels might not support automatic drag and drop; they will ignore this property. You can work around such look and feels by modifying the component to directly call the exportAsDrag method of a TransferHandler.

Parameters:
b - the value to set the dragEnabled property to
Throws:
HeadlessException - if b is true and GraphicsEnvironment.isHeadless() returns true
Since:
1.4
See Also:
GraphicsEnvironment.isHeadless(),
getDragEnabled(),
JComponent.setTransferHandler(javax.swing.TransferHandler),
TransferHandler

getDragEnabled

public boolean getDragEnabled()
Gets the value of the dragEnabled property.

Returns:
the value of the dragEnabled property
Since:
1.4
See Also:
setDragEnabled(boolean)

setPreviewPanel

public void setPreviewPanel(JComponent preview)
Sets the current preview panel. This will fire a PropertyChangeEvent for the property named "previewPanel".

Parameters:
preview - the JComponent which displays the current color
See Also:
Container.addPropertyChangeListener(java.beans.PropertyChangeListener)

getPreviewPanel

public JComponent getPreviewPanel()
Returns the preview panel that shows a chosen color.

Returns:
a JComponent object -- the preview panel

addChooserPanel

public void addChooserPanel(AbstractColorChooserPanel panel)
Adds a color chooser panel to the color chooser.

Parameters:
panel - the AbstractColorChooserPanel to be added

removeChooserPanel

public AbstractColorChooserPanel removeChooserPanel(AbstractColorChooserPanel panel)
Removes the Color Panel specified.

Parameters:
panel - a string that specifies the panel to be removed
Returns:
the color panel
Throws:
IllegalArgumentException - if panel is not in list of known chooser panels

setChooserPanels

public void setChooserPanels(AbstractColorChooserPanel[] panels)
Specifies the Color Panels used to choose a color value.

Parameters:
panels - an array of AbstractColorChooserPanel objects

getChooserPanels

public AbstractColorChooserPanel[] getChooserPanels()
Returns the specified color panels.

Returns:
an array of AbstractColorChooserPanel objects

getSelectionModel

public ColorSelectionModel getSelectionModel()
Returns the data model that handles color selections.

Returns:
a ColorSelectionModel object

setSelectionModel

public void setSelectionModel(ColorSelectionModel newModel)
Sets the model containing the selected color.

Parameters:
newModel - the new ColorSelectionModel object

paramString

protected String paramString()
Returns a string representation of this JColorChooser. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JColorChooser

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JColorChooser. For color choosers, the AccessibleContext takes the form of an AccessibleJColorChooser. A new AccessibleJColorChooser instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJColorChooser that serves as the AccessibleContext of this JColorChooser
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JColorChooser.AccessibleJColorChooser

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JColorChooser.AccessibleJColorChooser

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JColorChooser.AccessibleJColorChooser
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent
Enclosing class:
JColorChooser
protected class JColorChooser.AccessibleJColorChooser
extends JComponent.AccessibleJComponent

This class implements accessibility support for the JColorChooser class. It provides an implementation of the Java Accessibility API appropriate to color chooser user-interface elements.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JColorChooser.AccessibleJColorChooser()
Method Summary
 AccessibleRole getAccessibleRole()
Get the role of this object.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JColorChooser.AccessibleJColorChooser

protected JColorChooser.AccessibleJColorChooser()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JComboBox

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JComboBox

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JComboBox
All Implemented Interfaces:
ActionListener, ImageObserver, ItemSelectable, MenuContainer, Serializable, EventListener, Accessible, ListDataListener
public class JComboBox
extends JComponent
implements ItemSelectable, ListDataListener, ActionListener, Accessible

A component that combines a button or editable field and a drop-down list. The user can select a value from the drop-down list, which appears at the user's request. If you make the combo box editable, then the combo box includes an editable field into which the user can type a value.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See How to Use Combo Boxes in The Java Tutorial for further information.

See Also:
ComboBoxModel, DefaultComboBoxModel

Nested Class Summary
protected class | JComboBox.AccessibleJComboBox This class implements accessibility support for the JComboBox class.
static interface | JComboBox.KeySelectionManager The interface that defines a KeySelectionManager.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected String | actionCommand This protected field is implementation specific.
protected ComboBoxModel | dataModel This protected field is implementation specific.
protected ComboBoxEditor | editor This protected field is implementation specific.
protected boolean | isEditable This protected field is implementation specific.
protected JComboBox.KeySelectionManager | keySelectionManager This protected field is implementation specific.
protected boolean | lightWeightPopupEnabled This protected field is implementation specific.
protected int | maximumRowCount This protected field is implementation specific.
protected ListCellRenderer | renderer This protected field is implementation specific.
protected Object | selectedItemReminder This protected field is implementation specific.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JComboBox()
Creates a JComboBox with a default data model.
JComboBox(ComboBoxModel aModel)
Creates a JComboBox that takes its items from an existing ComboBoxModel.
JComboBox(Object[] items)
Creates a JComboBox that contains the elements in the specified array.
JComboBox(Vector<?> items)
Creates a JComboBox that contains the elements in the specified Vector.
Method Summary
 void actionPerformed(ActionEvent e)
This method is public as an implementation side effect.
protected  void actionPropertyChanged(Action action, String propertyName)
Updates the combobox's state in response to property changes in associated action.
 void addActionListener(ActionListener l)
Adds an ActionListener.
 void addItem(Object anObject)
Adds an item to the item list.
 void addItemListener(ItemListener aListener)
Adds an ItemListener.
 void addPopupMenuListener(PopupMenuListener l)
Adds a PopupMenu listener which will listen to notification messages from the popup portion of the combo box.
 void configureEditor(ComboBoxEditor anEditor, Object anItem)
Initializes the editor with the specified item.
protected  void configurePropertiesFromAction(Action a)
Sets the properties on this combobox to match those in the specified Action.
 void contentsChanged(ListDataEvent e)
This method is public as an implementation side effect.
protected  PropertyChangeListener createActionPropertyChangeListener(Action a)
Creates and returns a PropertyChangeListener that is responsible for listening for changes from the specified Action and updating the appropriate properties.
protected  JComboBox.KeySelectionManager createDefaultKeySelectionManager()
Returns an instance of the default key-selection manager.
protected  void fireActionEvent()
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireItemStateChanged(ItemEvent e)
Notifies all listeners that have registered interest for notification on this event type.
 void firePopupMenuCanceled()
Notifies PopupMenuListeners that the popup portion of the combo box has been canceled.
 void firePopupMenuWillBecomeInvisible()
Notifies PopupMenuListeners that the popup portion of the combo box has become invisible.
 void firePopupMenuWillBecomeVisible()
Notifies PopupMenuListeners that the popup portion of the combo box will become visible.
 AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JComboBox.
 Action getAction()
Returns the currently set Action for this ActionEvent source, or null if no Action is set.
 String getActionCommand()
Returns the action command that is included in the event sent to action listeners.
 ActionListener[] getActionListeners()
Returns an array of all the ActionListeners added to this JComboBox with addActionListener().
 ComboBoxEditor getEditor()
Returns the editor used to paint and edit the selected item in the JComboBox field.
 Object getItemAt(int index)
Returns the list item at the specified index.
 int getItemCount()
Returns the number of items in the list.
 ItemListener[] getItemListeners()
Returns an array of all the ItemListeners added to this JComboBox with addItemListener().
 JComboBox.KeySelectionManager getKeySelectionManager()
Returns the list's key-selection manager.
 int getMaximumRowCount()
Returns the maximum number of items the combo box can display without a scrollbar
 ComboBoxModel getModel()
Returns the data model currently used by the JComboBox.
 PopupMenuListener[] getPopupMenuListeners()
Returns an array of all the PopupMenuListeners added to this JComboBox with addPopupMenuListener().
 Object getPrototypeDisplayValue()
Returns the "prototypical display" value - an Object used for the calculation of the display height and width.
 ListCellRenderer getRenderer()
Returns the renderer used to display the selected item in the JComboBox field.
 int getSelectedIndex()
Returns the first item in the list that matches the given item.
 Object getSelectedItem()
Returns the current selected item.
 Object[] getSelectedObjects()
Returns an array containing the selected item.
 ComboBoxUI getUI()
Returns the L&F object that renders this component.
 String getUIClassID()
Returns the name of the L&F class that renders this component.
 void hidePopup()
Causes the combo box to close its popup window.
 void insertItemAt(Object anObject, int index)
Inserts an item into the item list at a given index.
protected  void installAncestorListener()
 void intervalAdded(ListDataEvent e)
This method is public as an implementation side effect.
 void intervalRemoved(ListDataEvent e)
This method is public as an implementation side effect.
 boolean isEditable()
Returns true if the JComboBox is editable.
 boolean isLightWeightPopupEnabled()
Gets the value of the lightWeightPopupEnabled property.
 boolean isPopupVisible()
Determines the visibility of the popup.
protected  String paramString()
Returns a string representation of this JComboBox.
 void processKeyEvent(KeyEvent e)
Handles KeyEvents, looking for the Tab key.
 void removeActionListener(ActionListener l)
Removes an ActionListener.
 void removeAllItems()
Removes all items from the item list.
 void removeItem(Object anObject)
Removes an item from the item list.
 void removeItemAt(int anIndex)
Removes the item at anIndex This method works only if the JComboBox uses a mutable data model.
 void removeItemListener(ItemListener aListener)
Removes an ItemListener.
 void removePopupMenuListener(PopupMenuListener l)
Removes a PopupMenuListener.
protected  void selectedItemChanged()
This protected method is implementation specific.
 boolean selectWithKeyChar(char keyChar)
Selects the list item that corresponds to the specified keyboard character and returns true, if there is an item corresponding to that character.
 void setAction(Action a)
Sets the Action for the ActionEvent source.
 void setActionCommand(String aCommand)
Sets the action command that should be included in the event sent to action listeners.
 void setEditable(boolean aFlag)
Determines whether the JComboBox field is editable.
 void setEditor(ComboBoxEditor anEditor)
Sets the editor used to paint and edit the selected item in the JComboBox field.
 void setEnabled(boolean b)
Enables the combo box so that items can be selected.
 void setKeySelectionManager(JComboBox.KeySelectionManager aManager)
Sets the object that translates a keyboard character into a list selection.
 void setLightWeightPopupEnabled(boolean aFlag)
Sets the lightWeightPopupEnabled property, which provides a hint as to whether or not a lightweight Component should be used to contain the JComboBox, versus a heavyweight Component such as a Panel or a Window.
 void setMaximumRowCount(int count)
Sets the maximum number of rows the JComboBox displays.
 void setModel(ComboBoxModel aModel)
Sets the data model that the JComboBox uses to obtain the list of items.
 void setPopupVisible(boolean v)
Sets the visibility of the popup.
 void setPrototypeDisplayValue(Object prototypeDisplayValue)
Sets the prototype display value used to calculate the size of the display for the UI portion.
 void setRenderer(ListCellRenderer aRenderer)
Sets the renderer that paints the list items and the item selected from the list in the JComboBox field.
 void setSelectedIndex(int anIndex)
Selects the item at index anIndex.
 void setSelectedItem(Object anObject)
Sets the selected item in the combo box display area to the object in the argument.
 void setUI(ComboBoxUI ui)
Sets the L&F object that renders this component.
 void showPopup()
Causes the combo box to display its popup window.
 void updateUI()
Resets the UI property to a value from the current look and feel.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

dataModel

protected ComboBoxModel dataModel
This protected field is implementation specific. Do not access directly or override. Use the accessor methods instead.

See Also:
getModel(), setModel(javax.swing.ComboBoxModel)

renderer

protected ListCellRenderer renderer
This protected field is implementation specific. Do not access directly or override. Use the accessor methods instead.

See Also:
getRenderer(), setRenderer(javax.swing.ListCellRenderer)

editor

protected ComboBoxEditor editor
This protected field is implementation specific. Do not access directly or override. Use the accessor methods instead.

See Also:
getEditor(), setEditor(javax.swing.ComboBoxEditor)

maximumRowCount

protected int maximumRowCount
This protected field is implementation specific. Do not access directly or override. Use the accessor methods instead.

See Also:
getMaximumRowCount(), setMaximumRowCount(int)

isEditable

protected boolean isEditable
This protected field is implementation specific. Do not access directly or override. Use the accessor methods instead.

See Also:
isEditable, setEditable(boolean)

keySelectionManager

protected JComboBox.KeySelectionManager keySelectionManager
This protected field is implementation specific. Do not access directly or override. Use the accessor methods instead.

See Also:
setKeySelectionManager(javax.swing.JComboBox.KeySelectionManager), getKeySelectionManager()

actionCommand

protected String actionCommand
This protected field is implementation specific. Do not access directly or override. Use the accessor methods instead.

See Also:
setActionCommand(java.lang.String), getActionCommand()

lightWeightPopupEnabled

protected boolean lightWeightPopupEnabled
This protected field is implementation specific. Do not access directly or override. Use the accessor methods instead.

See Also:
setLightWeightPopupEnabled(boolean), isLightWeightPopupEnabled()

selectedItemReminder

protected Object selectedItemReminder
This protected field is implementation specific. Do not access directly or override.

Constructor Detail

JComboBox

public JComboBox(ComboBoxModel aModel)
Creates a JComboBox that takes its items from an existing ComboBoxModel. Since the ComboBoxModel is provided, a combo box created using this constructor does not create a default combo box model and may impact how the insert, remove and add methods behave.

Parameters:
aModel - the ComboBoxModel that provides the displayed list of items
See Also:
DefaultComboBoxModel

JComboBox

public JComboBox(Object[] items)
Creates a JComboBox that contains the elements in the specified array. By default the first item in the array (and therefore the data model) becomes selected.

Parameters:
items - an array of objects to insert into the combo box
See Also:
DefaultComboBoxModel

JComboBox

public JComboBox(Vector<?> items)
Creates a JComboBox that contains the elements in the specified Vector. By default the first item in the vector (and therefore the data model) becomes selected.

Parameters:
items - an array of vectors to insert into the combo box
See Also:
DefaultComboBoxModel

JComboBox

public JComboBox()
Creates a JComboBox with a default data model. The default data model is an empty list of objects. Use addItem to add items. By default the first item in the data model becomes selected.

See Also:
DefaultComboBoxModel
Method Detail

installAncestorListener

protected void installAncestorListener()

setUI

public void setUI(ComboBoxUI ui)
Sets the L&F object that renders this component.

Parameters:
ui - the ComboBoxUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Resets the UI property to a value from the current look and feel.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "ComboBoxUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

getUI

public ComboBoxUI getUI()
Returns the L&F object that renders this component.

Returns:
the ComboBoxUI object that renders this component

setModel

public void setModel(ComboBoxModel aModel)
Sets the data model that the JComboBox uses to obtain the list of items.

Parameters:
aModel - the ComboBoxModel that provides the displayed list of items

getModel

public ComboBoxModel getModel()
Returns the data model currently used by the JComboBox.

Returns:
the ComboBoxModel that provides the displayed list of items

setLightWeightPopupEnabled

public void setLightWeightPopupEnabled(boolean aFlag)
Sets the lightWeightPopupEnabled property, which provides a hint as to whether or not a lightweight Component should be used to contain the JComboBox, versus a heavyweight Component such as a Panel or a Window. The decision of lightweight versus heavyweight is ultimately up to the JComboBox. Lightweight windows are more efficient than heavyweight windows, but lightweight and heavyweight components do not mix well in a GUI. If your application mixes lightweight and heavyweight components, you should disable lightweight popups. The default value for the lightWeightPopupEnabled property is true, unless otherwise specified by the look and feel. Some look and feels always use heavyweight popups, no matter what the value of this property.

See the article Mixing Heavy and Light Components on The Swing Connection This method fires a property changed event.

Parameters:
aFlag - if true, lightweight popups are desired

isLightWeightPopupEnabled

public boolean isLightWeightPopupEnabled()
Gets the value of the lightWeightPopupEnabled property.

Returns:
the value of the lightWeightPopupEnabled property
See Also:
setLightWeightPopupEnabled(boolean)

setEditable

public void setEditable(boolean aFlag)
Determines whether the JComboBox field is editable. An editable JComboBox allows the user to type into the field or selected an item from the list to initialize the field, after which it can be edited. (The editing affects only the field, the list item remains intact.) A non editable JComboBox displays the selected item in the field, but the selection cannot be modified.

Parameters:
aFlag - a boolean value, where true indicates that the field is editable

isEditable

public boolean isEditable()
Returns true if the JComboBox is editable. By default, a combo box is not editable.

Returns:
true if the JComboBox is editable, else false

setMaximumRowCount

public void setMaximumRowCount(int count)
Sets the maximum number of rows the JComboBox displays. If the number of objects in the model is greater than count, the combo box uses a scrollbar.

Parameters:
count - an integer specifying the maximum number of items to display in the list before using a scrollbar

getMaximumRowCount

public int getMaximumRowCount()
Returns the maximum number of items the combo box can display without a scrollbar

Returns:
an integer specifying the maximum number of items that are displayed in the list before using a scrollbar

setRenderer

public void setRenderer(ListCellRenderer aRenderer)
Sets the renderer that paints the list items and the item selected from the list in the JComboBox field. The renderer is used if the JComboBox is not editable. If it is editable, the editor is used to render and edit the selected item.

The default renderer displays a string or an icon. Other renderers can handle graphic images and composite items.

To display the selected item, aRenderer.getListCellRendererComponent is called, passing the list object and an index of -1.

Parameters:
aRenderer - the ListCellRenderer that displays the selected item
See Also:
setEditor(javax.swing.ComboBoxEditor)

getRenderer

public ListCellRenderer getRenderer()
Returns the renderer used to display the selected item in the JComboBox field.

Returns:
the ListCellRenderer that displays the selected item.

setEditor

public void setEditor(ComboBoxEditor anEditor)
Sets the editor used to paint and edit the selected item in the JComboBox field. The editor is used only if the receiving JComboBox is editable. If not editable, the combo box uses the renderer to paint the selected item.

Parameters:
anEditor - the ComboBoxEditor that displays the selected item
See Also:
setRenderer(javax.swing.ListCellRenderer)

getEditor

public ComboBoxEditor getEditor()
Returns the editor used to paint and edit the selected item in the JComboBox field.

Returns:
the ComboBoxEditor that displays the selected item

setSelectedItem

public void setSelectedItem(Object anObject)
Sets the selected item in the combo box display area to the object in the argument. If anObject is in the list, the display area shows anObject selected.

If anObject is not in the list and the combo box is uneditable, it will not change the current selection. For editable combo boxes, the selection will change to anObject.

If this constitutes a change in the selected item, ItemListeners added to the combo box will be notified with one or two ItemEvents. If there is a current selected item, an ItemEvent will be fired and the state change will be ItemEvent.DESELECTED. If anObject is in the list and is not currently selected then an ItemEvent will be fired and the state change will be ItemEvent.SELECTED.

ActionListeners added to the combo box will be notified with an ActionEvent when this method is called.

Parameters:
anObject - the list object to select; use null to clear the selection

getSelectedItem

public Object getSelectedItem()
Returns the current selected item.

If the combo box is editable, then this value may not have been added to the combo box with addItem, insertItemAt or the data constructors.

Returns:
the current selected Object
See Also:
setSelectedItem(java.lang.Object)

setSelectedIndex

public void setSelectedIndex(int anIndex)
Selects the item at index anIndex.

Parameters:
anIndex - an integer specifying the list item to select, where 0 specifies the first item in the list and -1 indicates no selection
Throws:
IllegalArgumentException - if anIndex < -1 or anIndex is greater than or equal to size

getSelectedIndex

public int getSelectedIndex()
Returns the first item in the list that matches the given item. The result is not always defined if the JComboBox allows selected items that are not in the list. Returns -1 if there is no selected item or if the user specified an item which is not in the list.

Returns:
an integer specifying the currently selected list item, where 0 specifies the first item in the list; or -1 if no item is selected or if the currently selected item is not in the list

getPrototypeDisplayValue

public Object getPrototypeDisplayValue()
Returns the "prototypical display" value - an Object used for the calculation of the display height and width.

Returns:
the value of the prototypeDisplayValue property
Since:
1.4
See Also:
setPrototypeDisplayValue(java.lang.Object)

setPrototypeDisplayValue

public void setPrototypeDisplayValue(Object prototypeDisplayValue)
Sets the prototype display value used to calculate the size of the display for the UI portion.

If a prototype display value is specified, the preferred size of the combo box is calculated by configuring the renderer with the prototype display value and obtaining its preferred size. Specifying the preferred display value is often useful when the combo box will be displaying large amounts of data. If no prototype display value has been specified, the renderer must be configured for each value from the model and its preferred size obtained, which can be relatively expensive.

Parameters:
prototypeDisplayValue -
Since:
1.4
See Also:
getPrototypeDisplayValue()

addItem

public void addItem(Object anObject)
Adds an item to the item list. This method works only if the JComboBox uses a mutable data model.

Warning: Focus and keyboard navigation problems may arise if you add duplicate String objects. A workaround is to add new objects instead of String objects and make sure that the toString() method is defined. For example:

   comboBox.addItem(makeObj("Item 1"));
   comboBox.addItem(makeObj("Item 1"));
   ...
   private Object makeObj(final String item)  {
     return new Object() { public String toString() { return item; } };
   }

Parameters:
anObject - the Object to add to the list
See Also:
MutableComboBoxModel

insertItemAt

public void insertItemAt(Object anObject,
                         int index)
Inserts an item into the item list at a given index. This method works only if the JComboBox uses a mutable data model.

Parameters:
anObject - the Object to add to the list
index - an integer specifying the position at which to add the item
See Also:
MutableComboBoxModel

removeItem

public void removeItem(Object anObject)
Removes an item from the item list. This method works only if the JComboBox uses a mutable data model.

Parameters:
anObject - the object to remove from the item list
See Also:
MutableComboBoxModel

removeItemAt

public void removeItemAt(int anIndex)
Removes the item at anIndex This method works only if the JComboBox uses a mutable data model.

Parameters:
anIndex - an int specifying the index of the item to remove, where 0 indicates the first item in the list
See Also:
MutableComboBoxModel

removeAllItems

public void removeAllItems()
Removes all items from the item list.

showPopup

public void showPopup()
Causes the combo box to display its popup window.

See Also:
setPopupVisible(boolean)

hidePopup

public void hidePopup()
Causes the combo box to close its popup window.

See Also:
setPopupVisible(boolean)

setPopupVisible

public void setPopupVisible(boolean v)
Sets the visibility of the popup.

isPopupVisible

public boolean isPopupVisible()
Determines the visibility of the popup.

Returns:
true if the popup is visible, otherwise returns false

addItemListener

public void addItemListener(ItemListener aListener)
Adds an ItemListener.

aListener will receive one or two ItemEvents when the selected item changes.

Specified by:
addItemListener in interface ItemSelectable
Parameters:
aListener - the ItemListener that is to be notified
See Also:
setSelectedItem(java.lang.Object)

removeItemListener

public void removeItemListener(ItemListener aListener)
Removes an ItemListener.

Specified by:
removeItemListener in interface ItemSelectable
Parameters:
aListener - the ItemListener to remove
See Also:
ItemEvent

getItemListeners

public ItemListener[] getItemListeners()
Returns an array of all the ItemListeners added to this JComboBox with addItemListener().

Returns:
all of the ItemListeners added or an empty array if no listeners have been added
Since:
1.4

addActionListener

public void addActionListener(ActionListener l)
Adds an ActionListener.

The ActionListener will receive an ActionEvent when a selection has been made. If the combo box is editable, then an ActionEvent will be fired when editing has stopped.

Parameters:
l - the ActionListener that is to be notified
See Also:
setSelectedItem(java.lang.Object)

removeActionListener

public void removeActionListener(ActionListener l)
Removes an ActionListener.

Parameters:
l - the ActionListener to remove

getActionListeners

public ActionListener[] getActionListeners()
Returns an array of all the ActionListeners added to this JComboBox with addActionListener().

Returns:
all of the ActionListeners added or an empty array if no listeners have been added
Since:
1.4

addPopupMenuListener

public void addPopupMenuListener(PopupMenuListener l)
Adds a PopupMenu listener which will listen to notification messages from the popup portion of the combo box.

For all standard look and feels shipped with Java, the popup list portion of combo box is implemented as a JPopupMenu. A custom look and feel may not implement it this way and will therefore not receive the notification.

Parameters:
l - the PopupMenuListener to add
Since:
1.4

removePopupMenuListener

public void removePopupMenuListener(PopupMenuListener l)
Removes a PopupMenuListener.

Parameters:
l - the PopupMenuListener to remove
Since:
1.4
See Also:
addPopupMenuListener(javax.swing.event.PopupMenuListener)

getPopupMenuListeners

public PopupMenuListener[] getPopupMenuListeners()
Returns an array of all the PopupMenuListeners added to this JComboBox with addPopupMenuListener().

Returns:
all of the PopupMenuListeners added or an empty array if no listeners have been added
Since:
1.4

firePopupMenuWillBecomeVisible

public void firePopupMenuWillBecomeVisible()
Notifies PopupMenuListeners that the popup portion of the combo box will become visible.

This method is public but should not be called by anything other than the UI delegate.

Since:
1.4
See Also:
addPopupMenuListener(javax.swing.event.PopupMenuListener)

firePopupMenuWillBecomeInvisible

public void firePopupMenuWillBecomeInvisible()
Notifies PopupMenuListeners that the popup portion of the combo box has become invisible.

This method is public but should not be called by anything other than the UI delegate.

Since:
1.4
See Also:
addPopupMenuListener(javax.swing.event.PopupMenuListener)

firePopupMenuCanceled

public void firePopupMenuCanceled()
Notifies PopupMenuListeners that the popup portion of the combo box has been canceled.

This method is public but should not be called by anything other than the UI delegate.

Since:
1.4
See Also:
addPopupMenuListener(javax.swing.event.PopupMenuListener)

setActionCommand

public void setActionCommand(String aCommand)
Sets the action command that should be included in the event sent to action listeners.

Parameters:
aCommand - a string containing the "command" that is sent to action listeners; the same listener can then do different things depending on the command it receives

getActionCommand

public String getActionCommand()
Returns the action command that is included in the event sent to action listeners.

Returns:
the string containing the "command" that is sent to action listeners.

setAction

public void setAction(Action a)
Sets the Action for the ActionEvent source. The new Action replaces any previously set Action but does not affect ActionListeners independently added with addActionListener. If the Action is already a registered ActionListener for the ActionEvent source, it is not re-registered.

Setting the Action results in immediately changing all the properties described in Swing Components Supporting Action. Subsequently, the combobox's properties are automatically updated as the Action's properties change.

This method uses three other methods to set and help track the Action's property values. It uses the configurePropertiesFromAction method to immediately change the combobox's properties. To track changes in the Action's property values, this method registers the PropertyChangeListener returned by createActionPropertyChangeListener. The default PropertyChangeListener invokes the actionPropertyChanged method when a property in the Action changes.

Parameters:
a - the Action for the JComboBox, or null.
Since:
1.3
See Also:
Action,
getAction(),
configurePropertiesFromAction(javax.swing.Action),
createActionPropertyChangeListener(javax.swing.Action),
actionPropertyChanged(javax.swing.Action, java.lang.String)

getAction

public Action getAction()
Returns the currently set Action for this ActionEvent source, or null if no Action is set.

Returns:
the Action for this ActionEvent source; or null
Since:
1.3
See Also:
Action, setAction(javax.swing.Action)

configurePropertiesFromAction

protected void configurePropertiesFromAction(Action a)
Sets the properties on this combobox to match those in the specified Action. Refer to Swing Components Supporting Action for more details as to which properties this sets.

Parameters:
a - the Action from which to get the properties, or null
Since:
1.3
See Also:
Action, setAction(javax.swing.Action)

createActionPropertyChangeListener

protected PropertyChangeListener createActionPropertyChangeListener(Action a)
Creates and returns a PropertyChangeListener that is responsible for listening for changes from the specified Action and updating the appropriate properties.

Warning: If you subclass this do not create an anonymous inner class. If you do the lifetime of the combobox will be tied to that of the Action.

Parameters:
a - the combobox's action
Since:
1.3
See Also:
Action, setAction(javax.swing.Action)

actionPropertyChanged

protected void actionPropertyChanged(Action action,
                                     String propertyName)
Updates the combobox's state in response to property changes in associated action. This method is invoked from the PropertyChangeListener returned from createActionPropertyChangeListener. Subclasses do not normally need to invoke this. Subclasses that support additional Action properties should override this and configurePropertiesFromAction.

Refer to the table at Swing Components Supporting Action for a list of the properties this method sets.

Parameters:
action - the Action associated with this combobox
propertyName - the name of the property that changed
Since:
1.6
See Also:
Action, configurePropertiesFromAction(javax.swing.Action)

fireItemStateChanged

protected void fireItemStateChanged(ItemEvent e)
Notifies all listeners that have registered interest for notification on this event type.

Parameters:
e - the event of interest
See Also:
EventListenerList

fireActionEvent

protected void fireActionEvent()
Notifies all listeners that have registered interest for notification on this event type.

See Also:
EventListenerList

selectedItemChanged

protected void selectedItemChanged()
This protected method is implementation specific. Do not access directly or override.

getSelectedObjects

public Object[] getSelectedObjects()
Returns an array containing the selected item. This method is implemented for compatibility with ItemSelectable.

Specified by:
getSelectedObjects in interface ItemSelectable
Returns:
an array of Objects containing one element -- the selected item

actionPerformed

public void actionPerformed(ActionEvent e)
This method is public as an implementation side effect. do not call or override.

Specified by:
actionPerformed in interface ActionListener

contentsChanged

public void contentsChanged(ListDataEvent e)
This method is public as an implementation side effect. do not call or override.

Specified by:
contentsChanged in interface ListDataListener
Parameters:
e - a ListDataEvent encapsulating the event information

intervalAdded

public void intervalAdded(ListDataEvent e)
This method is public as an implementation side effect. do not call or override.

Specified by:
intervalAdded in interface ListDataListener
Parameters:
e - a ListDataEvent encapsulating the event information

intervalRemoved

public void intervalRemoved(ListDataEvent e)
This method is public as an implementation side effect. do not call or override.

Specified by:
intervalRemoved in interface ListDataListener
Parameters:
e - a ListDataEvent encapsulating the event information

selectWithKeyChar

public boolean selectWithKeyChar(char keyChar)
Selects the list item that corresponds to the specified keyboard character and returns true, if there is an item corresponding to that character. Otherwise, returns false.

Parameters:
keyChar - a char, typically this is a keyboard key typed by the user

setEnabled

public void setEnabled(boolean b)
Enables the combo box so that items can be selected. When the combo box is disabled, items cannot be selected and values cannot be typed into its field (if it is editable).

Overrides:
setEnabled in class JComponent
Parameters:
b - a boolean value, where true enables the component and false disables it
See Also:
Component.isEnabled(), Component.isLightweight()

configureEditor

public void configureEditor(ComboBoxEditor anEditor,
                            Object anItem)
Initializes the editor with the specified item.

Parameters:
anEditor - the ComboBoxEditor that displays the list item in the combo box field and allows it to be edited
anItem - the object to display and edit in the field

processKeyEvent

public void processKeyEvent(KeyEvent e)
Handles KeyEvents, looking for the Tab key. If the Tab key is found, the popup window is closed.

Overrides:
processKeyEvent in class JComponent
Parameters:
e - the KeyEvent containing the keyboard key that was pressed
See Also:
KeyEvent, KeyListener, KeyboardFocusManager, DefaultKeyboardFocusManager, Component.processEvent(java.awt.AWTEvent), Component.dispatchEvent(java.awt.AWTEvent), Component.addKeyListener(java.awt.event.KeyListener), Component.enableEvents(long), Component.isShowing()

setKeySelectionManager

public void setKeySelectionManager(JComboBox.KeySelectionManager aManager)
Sets the object that translates a keyboard character into a list selection. Typically, the first selection with a matching first character becomes the selected item.

getKeySelectionManager

public JComboBox.KeySelectionManager getKeySelectionManager()
Returns the list's key-selection manager.

Returns:
the KeySelectionManager currently in use

getItemCount

public int getItemCount()
Returns the number of items in the list.

Returns:
an integer equal to the number of items in the list

getItemAt

public Object getItemAt(int index)
Returns the list item at the specified index. If index is out of range (less than zero or greater than or equal to size) it will return null.

Parameters:
index - an integer indicating the list position, where the first item starts at zero
Returns:
the Object at that list position; or null if out of range

createDefaultKeySelectionManager

protected JComboBox.KeySelectionManager createDefaultKeySelectionManager()
Returns an instance of the default key-selection manager.

Returns:
the KeySelectionManager currently used by the list
See Also:
setKeySelectionManager(javax.swing.JComboBox.KeySelectionManager)

paramString

protected String paramString()
Returns a string representation of this JComboBox. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JComboBox

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JComboBox. For combo boxes, the AccessibleContext takes the form of an AccessibleJComboBox. A new AccessibleJComboBox instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJComboBox that serves as the AccessibleContext of this JComboBox
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JComboBox.AccessibleJComboBox

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JComboBox.AccessibleJComboBox

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JComboBox.AccessibleJComboBox
All Implemented Interfaces:
Serializable, AccessibleAction, AccessibleComponent, AccessibleExtendedComponent, AccessibleSelection
Enclosing class:
JComboBox
protected class JComboBox.AccessibleJComboBox
extends JComponent.AccessibleJComponent
implements AccessibleAction, AccessibleSelection

This class implements accessibility support for the JComboBox class. It provides an implementation of the Java Accessibility API appropriate to Combo Box user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Constructor Summary
JComboBox.AccessibleJComboBox()
Returns an AccessibleJComboBox instance
Method Summary
void | addAccessibleSelection(int i) Adds the specified Accessible child of the object to the object's selection.
void | clearAccessibleSelection() Clears the selection in the object, so that no children in the object are selected.
boolean | doAccessibleAction(int i) Perform the specified Action on the object
AccessibleAction | getAccessibleAction() Get the AccessibleAction associated with this object.
int | getAccessibleActionCount() Returns the number of Actions available in this object.
String | getAccessibleActionDescription(int i) Return a description of the specified action of the object.
Accessible | getAccessibleChild(int i) Returns the nth Accessible child of the object.
int | getAccessibleChildrenCount() Returns the number of accessible children in the object.
AccessibleRole | getAccessibleRole() Get the role of this object.
AccessibleSelection | getAccessibleSelection() Get the AccessibleSelection associated with this object.
Accessible | getAccessibleSelection(int i) Returns an Accessible representing the specified selected child in the popup.
int | getAccessibleSelectionCount() Returns the number of Accessible children currently selected.
AccessibleStateSet | getAccessibleStateSet() Gets the state set of this object.
boolean | isAccessibleChildSelected(int i) Determines if the current child of this object is selected.
void | removeAccessibleSelection(int i) Removes the specified child of the object from the object's selection.
void | selectAllAccessibleSelection() Causes every child of the object to be selected if the object supports multiple selections.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JComboBox.AccessibleJComboBox

public JComboBox.AccessibleJComboBox()
Returns an AccessibleJComboBox instance

Since:
1.4
Method Detail

getAccessibleChildrenCount

public int getAccessibleChildrenCount()
Returns the number of accessible children in the object. If all of the children of this object implement Accessible, than this method should return the number of children of this object.

Overrides:
getAccessibleChildrenCount in class JComponent.AccessibleJComponent
Returns:
the number of accessible children in the object.

getAccessibleChild

public Accessible getAccessibleChild(int i)
Returns the nth Accessible child of the object. The child at index zero represents the popup. If the combo box is editable, the child at index one represents the editor.

Overrides:
getAccessibleChild in class JComponent.AccessibleJComponent
Parameters:
i - zero-based index of child
Returns:
the nth Accessible child of the object
See Also:
AccessibleContext.getAccessibleChildrenCount()

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Gets the state set of this object. The AccessibleStateSet of an object is composed of a set of unique AccessibleStates. A change in the AccessibleStateSet of an object will cause a PropertyChangeEvent to be fired for the ACCESSIBLE_STATE_PROPERTY property.

Overrides:
getAccessibleStateSet in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleStateSet containing the current state set of the object
See Also:
AccessibleStateSet, AccessibleState, JComponent.AccessibleJComponent.addPropertyChangeListener(java.beans.PropertyChangeListener)

getAccessibleAction

public AccessibleAction getAccessibleAction()
Get the AccessibleAction associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleAction interface on behalf of itself.

Overrides:
getAccessibleAction in class AccessibleContext
Returns:
this object
See Also:
AccessibleAction

getAccessibleActionDescription

public String getAccessibleActionDescription(int i)
Return a description of the specified action of the object.

Specified by:
getAccessibleActionDescription in interface AccessibleAction
Parameters:
i - zero-based index of the actions
Returns:
a String description of the action
See Also:
AccessibleAction.getAccessibleActionCount()

getAccessibleActionCount

public int getAccessibleActionCount()
Returns the number of Actions available in this object. The default behavior of a combo box is to have one action.

Specified by:
getAccessibleActionCount in interface AccessibleAction
Returns:
1, the number of Actions in this object

doAccessibleAction

public boolean doAccessibleAction(int i)
Perform the specified Action on the object

Specified by:
doAccessibleAction in interface AccessibleAction
Parameters:
i - zero-based index of actions
Returns:
true if the the action was performed; else false.
See Also:
AccessibleAction.getAccessibleActionCount()

getAccessibleSelection

public AccessibleSelection getAccessibleSelection()
Get the AccessibleSelection associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleSelection interface on behalf of itself.

Overrides:
getAccessibleSelection in class AccessibleContext
Returns:
this object
See Also:
AccessibleSelection

getAccessibleSelectionCount

public int getAccessibleSelectionCount()
Returns the number of Accessible children currently selected. If no children are selected, the return value will be 0.

Specified by:
getAccessibleSelectionCount in interface AccessibleSelection
Returns:
the number of items currently selected.
Since:
1.3

getAccessibleSelection

public Accessible getAccessibleSelection(int i)
Returns an Accessible representing the specified selected child in the popup. If there isn't a selection, or there are fewer children selected than the integer passed in, the return value will be null.

Note that the index represents the i-th selected child, which is different from the i-th child.

Specified by:
getAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of selected children
Returns:
the i-th selected child
Since:
1.3
See Also:
getAccessibleSelectionCount()

isAccessibleChildSelected

public boolean isAccessibleChildSelected(int i)
Determines if the current child of this object is selected.

Specified by:
isAccessibleChildSelected in interface AccessibleSelection
Parameters:
i - the zero-based index of the child in this Accessible object.
Returns:
true if the current child of this object is selected; else false
Since:
1.3
See Also:
AccessibleContext.getAccessibleChild(int)

addAccessibleSelection

public void addAccessibleSelection(int i)
Adds the specified Accessible child of the object to the object's selection. If the object supports multiple selections, the specified child is added to any existing selection, otherwise it replaces any existing selection in the object. If the specified child is already selected, this method has no effect.

Specified by:
addAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of the child
Since:
1.3
See Also:
AccessibleContext.getAccessibleChild(int)

removeAccessibleSelection

public void removeAccessibleSelection(int i)
Removes the specified child of the object from the object's selection. If the specified item isn't currently selected, this method has no effect.

Specified by:
removeAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of the child
Since:
1.3
See Also:
AccessibleContext.getAccessibleChild(int)

clearAccessibleSelection

public void clearAccessibleSelection()
Clears the selection in the object, so that no children in the object are selected.

Specified by:
clearAccessibleSelection in interface AccessibleSelection
Since:
1.3

selectAllAccessibleSelection

public void selectAllAccessibleSelection()
Causes every child of the object to be selected if the object supports multiple selections.

Specified by:
selectAllAccessibleSelection in interface AccessibleSelection
Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JComboBox.KeySelectionManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface JComboBox.KeySelectionManager

Enclosing class:
JComboBox
public static interface JComboBox.KeySelectionManager

The interface that defines a KeySelectionManager. To qualify as a KeySelectionManager, the class needs to implement the method that identifies the list index given a character and the combo box data model.

Method Summary
 int selectionForKey(char aKey, ComboBoxModel aModel)
Given aKey and the model, returns the row that should become selected.

Method Detail

selectionForKey

int selectionForKey(char aKey,
                    ComboBoxModel aModel)
Given aKey and the model, returns the row that should become selected. Return -1 if no match was found.

Parameters:
aKey - a char value, usually indicating a keyboard key that was pressed
aModel - a ComboBoxModel -- the component's data model, containing the list of selectable items
Returns:
an int equal to the selected row, where 0 is the first item and -1 is none.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JComponent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JComponent

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable
Direct Known Subclasses:
AbstractButton, BasicInternalFrameTitlePane, Box, Box.Filler, JColorChooser, JComboBox, JFileChooser, JInternalFrame, JInternalFrame.JDesktopIcon, JLabel, JLayeredPane, JList, JMenuBar, JOptionPane, JPanel, JPopupMenu, JProgressBar, JRootPane, JScrollBar, JScrollPane, JSeparator, JSlider, JSpinner, JSplitPane, JTabbedPane, JTable, JTableHeader, JTextComponent, JToolBar, JToolTip, JTree, JViewport
public abstract class JComponent
extends Container
implements Serializable

The base class for all Swing components except top-level containers. To use a component that inherits from JComponent, you must place the component in a containment hierarchy whose root is a top-level Swing container. Top-level Swing containers -- such as JFrame, JDialog, and JApplet -- are specialized components that provide a place for other Swing components to paint themselves. For an explanation of containment hierarchies, see Swing Components and the Containment Hierarchy, a section in The Java Tutorial.

The JComponent class provides:

  • The base class for both standard and custom components that use the Swing architecture.
  • A "pluggable look and feel" (L&F) that can be specified by the programmer or (optionally) selected by the user at runtime. The look and feel for each component is provided by a UI delegate -- an object that descends from ComponentUI. See How to Set the Look and Feel in The Java Tutorial for more information.
  • Comprehensive keystroke handling. See the document Keyboard Bindings in Swing, an article in The Swing Connection, for more information.
  • Support for tool tips -- short descriptions that pop up when the cursor lingers over a component. See How to Use Tool Tips in The Java Tutorial for more information.
  • Support for accessibility. JComponent contains all of the methods in the Accessible interface, but it doesn't actually implement the interface. That is the responsibility of the individual classes that extend JComponent.
  • Support for component-specific properties. With the putClientProperty(java.lang.Object, java.lang.Object) and getClientProperty(java.lang.Object) methods, you can associate name-object pairs with any object that descends from JComponent.
  • An infrastructure for painting that includes double buffering and support for borders. For more information see Painting and How to Use Borders, both of which are sections in The Java Tutorial.
For more information on these subjects, see the Swing package description and The Java Tutorial section The JComponent Class.

JComponent and its subclasses document default values for certain properties. For example, JTable documents the default row height as 16. Each JComponent subclass that has a ComponentUI will create the ComponentUI as part of its constructor. In order to provide a particular look and feel each ComponentUI may set properties back on the JComponent that created it. For example, a custom look and feel may require JTables to have a row height of 24. The documented defaults are the value of a property BEFORE the ComponentUI has been installed. If you need a specific value for a particular property you should explicitly set it.

In release 1.4, the focus subsystem was rearchitected. For more information, see How to Use the Focus Subsystem, a section in The Java Tutorial.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
KeyStroke, Action, setBorder(javax.swing.border.Border), registerKeyboardAction(java.awt.event.ActionListener, java.lang.String, javax.swing.KeyStroke, int), JOptionPane, setDebugGraphicsOptions(int), setToolTipText(java.lang.String), setAutoscrolls(boolean)

Nested Class Summary
 class JComponent.AccessibleJComponent
Inner class of JComponent used to provide default support for accessibility.
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected AccessibleContext | accessibleContext The AccessibleContext associated with this JComponent.
protected EventListenerList | listenerList A list of event listeners for this component.
static String | TOOL_TIP_TEXT_KEY The comment to display when the cursor is over the component, also known as a "value tip", "flyover help", or "flyover label".
protected ComponentUI | ui The look and feel delegate for this component.
static int | UNDEFINED_CONDITION Constant used by some of the APIs to mean that no condition is defined.
static int | WHEN_ANCESTOR_OF_FOCUSED_COMPONENT Constant used for registerKeyboardAction that means that the command should be invoked when the receiving component is an ancestor of the focused component or is itself the focused component.
static int | WHEN_FOCUSED Constant used for registerKeyboardAction that means that the command should be invoked when the component has the focus.
static int | WHEN_IN_FOCUSED_WINDOW Constant used for registerKeyboardAction that means that the command should be invoked when the receiving component is in the window that has the focus or is itself the focused component.
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JComponent()
Default JComponent constructor.
Method Summary
 void addAncestorListener(AncestorListener listener)
Registers listener so that it will receive AncestorEvents when it or any of its ancestors move or are made visible or invisible.
 void addNotify()
Notifies this component that it now has a parent component.
 void addVetoableChangeListener(VetoableChangeListener listener)
Adds a VetoableChangeListener to the listener list.
 void computeVisibleRect(Rectangle visibleRect)
Returns the Component's "visible rect rectangle" - the intersection of the visible rectangles for this component and all of its ancestors.
 boolean contains(int x, int y)
Gives the UI delegate an opportunity to define the precise shape of this component for the sake of mouse processing.
 JToolTip createToolTip()
Returns the instance of JToolTip that should be used to display the tooltip.
 void disable()
Deprecated. As of JDK version 1.1, replaced by java.awt.Component.setEnabled(boolean).
 void enable()
Deprecated. As of JDK version 1.1, replaced by java.awt.Component.setEnabled(boolean).
 void firePropertyChange(String propertyName, boolean oldValue, boolean newValue)
Support for reporting bound property changes for boolean properties.
 void firePropertyChange(String propertyName, char oldValue, char newValue)
Reports a bound property change.
 void firePropertyChange(String propertyName, int oldValue, int newValue)
Support for reporting bound property changes for integer properties.
protected  void fireVetoableChange(String propertyName, Object oldValue, Object newValue)
Supports reporting constrained property changes.
 AccessibleContext getAccessibleContext()
Returns the AccessibleContext associated with this JComponent.
 ActionListener getActionForKeyStroke(KeyStroke aKeyStroke)
Returns the object that will perform the action registered for a given keystroke.
 ActionMap getActionMap()
Returns the ActionMap used to determine what Action to fire for particular KeyStroke binding.
 float getAlignmentX()
Overrides Container.getAlignmentX to return the vertical alignment.
 float getAlignmentY()
Overrides Container.getAlignmentY to return the horizontal alignment.
 AncestorListener[] getAncestorListeners()
Returns an array of all the ancestor listeners registered on this component.
 boolean getAutoscrolls()
Gets the autoscrolls property.
 int getBaseline(int width, int height)
Returns the baseline.
 Component.BaselineResizeBehavior getBaselineResizeBehavior()
Returns an enum indicating how the baseline of the component changes as the size changes.
 Border getBorder()
Returns the border of this component or null if no border is currently set.
 Rectangle getBounds(Rectangle rv)
Stores the bounds of this component into "return value" rv and returns rv.
 Object getClientProperty(Object key)
Returns the value of the property with the specified key.
protected  Graphics getComponentGraphics(Graphics g)
Returns the graphics object used to paint this component.
 JPopupMenu getComponentPopupMenu()
Returns JPopupMenu that assigned for this component.
 int getConditionForKeyStroke(KeyStroke aKeyStroke)
Returns the condition that determines whether a registered action occurs in response to the specified keystroke.
 int getDebugGraphicsOptions()
Returns the state of graphics debugging.
static Locale getDefaultLocale()
Returns the default locale used to initialize each JComponent's locale property upon creation.
 FontMetrics getFontMetrics(Font font)
Gets the FontMetrics for the specified Font.
 Graphics getGraphics()
Returns this component's graphics context, which lets you draw on a component.
 int getHeight()
Returns the current height of this component.
 boolean getInheritsPopupMenu()
Returns true if the JPopupMenu should be inherited from the parent.
 InputMap getInputMap()
Returns the InputMap that is used when the component has focus.
 InputMap getInputMap(int condition)
Returns the InputMap that is used during condition.
 InputVerifier getInputVerifier()
Returns the input verifier for this component.
 Insets getInsets()
If a border has been set on this component, returns the border's insets; otherwise calls super.getInsets.
 Insets getInsets(Insets insets)
Returns an Insets object containing this component's inset values.
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this JComponent.
 Point getLocation(Point rv)
Stores the x,y origin of this component into "return value" rv and returns rv.
 Dimension getMaximumSize()
If the maximum size has been set to a non-null value just returns it.
 Dimension getMinimumSize()
If the minimum size has been set to a non-null value just returns it.
 Component getNextFocusableComponent()
Deprecated. As of 1.4, replaced by FocusTraversalPolicy.
 Point getPopupLocation(MouseEvent event)
Returns the preferred location to display the popup menu in this component's coordinate system.
 Dimension getPreferredSize()
If the preferredSize has been set to a non-null value just returns it.
 KeyStroke[] getRegisteredKeyStrokes()
Returns the KeyStrokes that will initiate registered actions.
 JRootPane getRootPane()
Returns the JRootPane ancestor for this component.
 Dimension getSize(Dimension rv)
Stores the width/height of this component into "return value" rv and returns rv.
 Point getToolTipLocation(MouseEvent event)
Returns the tooltip location in this component's coordinate system.
 String getToolTipText()
Returns the tooltip string that has been set with setToolTipText.
 String getToolTipText(MouseEvent event)
Returns the string to be used as the tooltip for event.
 Container getTopLevelAncestor()
Returns the top-level ancestor of this component (either the containing Window or Applet), or null if this component has not been added to any container.
 TransferHandler getTransferHandler()
Gets the transferHandler property.
 String getUIClassID()
Returns the UIDefaults key used to look up the name of the swing.plaf.ComponentUI class that defines the look and feel for this component.
 boolean getVerifyInputWhenFocusTarget()
Returns the value that indicates whether the input verifier for the current focus owner will be called before this component requests focus.
 VetoableChangeListener[] getVetoableChangeListeners()
Returns an array of all the vetoable change listeners registered on this component.
 Rectangle getVisibleRect()
Returns the Component's "visible rectangle" - the intersection of this component's visible rectangle, new Rectangle(0, 0, getWidth(), getHeight()), and all of its ancestors' visible rectangles.
 int getWidth()
Returns the current width of this component.
 int getX()
Returns the current x coordinate of the component's origin.
 int getY()
Returns the current y coordinate of the component's origin.
 void grabFocus()
Requests that this Component get the input focus, and that this Component's top-level ancestor become the focused Window.
 boolean isDoubleBuffered()
Returns whether this component should use a buffer to paint.
static boolean isLightweightComponent(Component c)
Returns true if this component is lightweight, that is, if it doesn't have a native window system peer.
 boolean isManagingFocus()
Deprecated. As of 1.4, replaced by Component.setFocusTraversalKeys(int, Set) and Container.setFocusCycleRoot(boolean).
 boolean isOpaque()
Returns true if this component is completely opaque.
 boolean isOptimizedDrawingEnabled()
Returns true if this component tiles its children -- that is, if it can guarantee that the children will not overlap.
 boolean isPaintingForPrint()
Returns true if the current painting operation on this component is part of a print operation.
 boolean isPaintingTile()
Returns true if the component is currently painting a tile.
 boolean isRequestFocusEnabled()
Returns true if this JComponent should get focus; otherwise returns false.
 boolean isValidateRoot()
If this method returns true, revalidate calls by descendants of this component will cause the entire tree beginning with this root to be validated.
 void paint(Graphics g)
Invoked by Swing to draw components.
protected  void paintBorder(Graphics g)
Paints the component's border.
protected  void paintChildren(Graphics g)
Paints this component's children.
protected  void paintComponent(Graphics g)
Calls the UI delegate's paint method, if the UI delegate is non-null.
 void paintImmediately(int x, int y, int w, int h)
Paints the specified region in this component and all of its descendants that overlap the region, immediately.
 void paintImmediately(Rectangle r)
Paints the specified region now.
protected  String paramString()
Returns a string representation of this JComponent.
 void print(Graphics g)
Invoke this method to print the component to the specified Graphics.
 void printAll(Graphics g)
Invoke this method to print the component.
protected  void printBorder(Graphics g)
Prints the component's border.
protected  void printChildren(Graphics g)
Prints this component's children.
protected  void printComponent(Graphics g)
This is invoked during a printing operation.
protected  void processComponentKeyEvent(KeyEvent e)
Processes any key events that the component itself recognizes.
protected  boolean processKeyBinding(KeyStroke ks, KeyEvent e, int condition, boolean pressed)
Invoked to process the key bindings for ks as the result of the KeyEvent e.
protected  void processKeyEvent(KeyEvent e)
Overrides processKeyEvent to process events.
protected  void processMouseEvent(MouseEvent e)
Processes mouse events occurring on this component by dispatching them to any registered MouseListener objects, refer to Component.processMouseEvent(MouseEvent) for a complete description of this method.
protected  void processMouseMotionEvent(MouseEvent e)
Processes mouse motion events, such as MouseEvent.MOUSE_DRAGGED.
 void putClientProperty(Object key, Object value)
Adds an arbitrary key/value "client property" to this component.
 void registerKeyboardAction(ActionListener anAction, KeyStroke aKeyStroke, int aCondition)
This method is now obsolete, please use a combination of getActionMap() and getInputMap() for similiar behavior.
 void registerKeyboardAction(ActionListener anAction, String aCommand, KeyStroke aKeyStroke, int aCondition)
This method is now obsolete, please use a combination of getActionMap() and getInputMap() for similiar behavior.
 void removeAncestorListener(AncestorListener listener)
Unregisters listener so that it will no longer receive AncestorEvents.
 void removeNotify()
Notifies this component that it no longer has a parent component.
 void removeVetoableChangeListener(VetoableChangeListener listener)
Removes a VetoableChangeListener from the listener list.
 void repaint(long tm, int x, int y, int width, int height)
Adds the specified region to the dirty region list if the component is showing.
 void repaint(Rectangle r)
Adds the specified region to the dirty region list if the component is showing.
 boolean requestDefaultFocus()
Deprecated. As of 1.4, replaced by FocusTraversalPolicy.getDefaultComponent(Container).requestFocus()
 void requestFocus()
Requests that this Component gets the input focus.
 boolean requestFocus(boolean temporary)
Requests that this Component gets the input focus.
 boolean requestFocusInWindow()
Requests that this Component gets the input focus.
protected  boolean requestFocusInWindow(boolean temporary)
Requests that this Component gets the input focus.
 void resetKeyboardActions()
Unregisters all the bindings in the first tier InputMaps and ActionMap.
 void reshape(int x, int y, int w, int h)
Deprecated. As of JDK 5, replaced by Component.setBounds(int, int, int, int).

Moves and resizes this component.

 void revalidate()
Supports deferred automatic layout.
 void scrollRectToVisible(Rectangle aRect)
Forwards the scrollRectToVisible() message to the JComponent's parent.
 void setActionMap(ActionMap am)
Sets the ActionMap to am.
 void setAlignmentX(float alignmentX)
Sets the the vertical alignment.
 void setAlignmentY(float alignmentY)
Sets the the horizontal alignment.
 void setAutoscrolls(boolean autoscrolls)
Sets the autoscrolls property.
 void setBackground(Color bg)
Sets the background color of this component.
 void setBorder(Border border)
Sets the border of this component.
 void setComponentPopupMenu(JPopupMenu popup)
Sets the JPopupMenu for this JComponent.
 void setDebugGraphicsOptions(int debugOptions)
Enables or disables diagnostic information about every graphics operation performed within the component or one of its children.
static void setDefaultLocale(Locale l)
Sets the default locale used to initialize each JComponent's locale property upon creation.
 void setDoubleBuffered(boolean aFlag)
Sets whether this component should use a buffer to paint.
 void setEnabled(boolean enabled)
Sets whether or not this component is enabled.
 void setFocusTraversalKeys(int id, Set<? extends AWTKeyStroke> keystrokes)
Sets the focus traversal keys for a given traversal operation for this Component.
 void setFont(Font font)
Sets the font for this component.
 void setForeground(Color fg)
Sets the foreground color of this component.
 void setInheritsPopupMenu(boolean value)
Sets whether or not getComponentPopupMenu should delegate to the parent if this component does not have a JPopupMenu assigned to it.
 void setInputMap(int condition, InputMap map)
Sets the InputMap to use under the condition condition to map.
 void setInputVerifier(InputVerifier inputVerifier)
Sets the input verifier for this component.
 void setMaximumSize(Dimension maximumSize)
Sets the maximum size of this component to a constant value.
 void setMinimumSize(Dimension minimumSize)
Sets the minimum size of this component to a constant value.
 void setNextFocusableComponent(Component aComponent)
Deprecated. As of 1.4, replaced by FocusTraversalPolicy
 void setOpaque(boolean isOpaque)
If true the component paints every pixel within its bounds.
 void setPreferredSize(Dimension preferredSize)
Sets the preferred size of this component.
 void setRequestFocusEnabled(boolean requestFocusEnabled)
Provides a hint as to whether or not this JComponent should get focus.
 void setToolTipText(String text)
Registers the text to display in a tool tip.
 void setTransferHandler(TransferHandler newHandler)
Sets the transferHandler property, which is null if the component does not support data transfer operations.
protected  void setUI(ComponentUI newUI)
Sets the look and feel delegate for this component.
 void setVerifyInputWhenFocusTarget(boolean verifyInputWhenFocusTarget)
Sets the value to indicate whether input verifier for the current focus owner will be called before this component requests focus.
 void setVisible(boolean aFlag)
Makes the component visible or invisible.
 void unregisterKeyboardAction(KeyStroke aKeyStroke)
This method is now obsolete.
 void update(Graphics g)
Calls paint.
 void updateUI()
Resets the UI property to a value from the current look and feel.
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ui

protected transient ComponentUI ui
The look and feel delegate for this component.

listenerList

protected EventListenerList listenerList
A list of event listeners for this component.

WHEN_FOCUSED

public static final int WHEN_FOCUSED
Constant used for registerKeyboardAction that means that the command should be invoked when the component has the focus.

See Also:
Constant Field Values

WHEN_ANCESTOR_OF_FOCUSED_COMPONENT

public static final int WHEN_ANCESTOR_OF_FOCUSED_COMPONENT
Constant used for registerKeyboardAction that means that the command should be invoked when the receiving component is an ancestor of the focused component or is itself the focused component.

See Also:
Constant Field Values

WHEN_IN_FOCUSED_WINDOW

public static final int WHEN_IN_FOCUSED_WINDOW
Constant used for registerKeyboardAction that means that the command should be invoked when the receiving component is in the window that has the focus or is itself the focused component.

See Also:
Constant Field Values

UNDEFINED_CONDITION

public static final int UNDEFINED_CONDITION
Constant used by some of the APIs to mean that no condition is defined.

See Also:
Constant Field Values

TOOL_TIP_TEXT_KEY

public static final String TOOL_TIP_TEXT_KEY
The comment to display when the cursor is over the component, also known as a "value tip", "flyover help", or "flyover label".

See Also:
Constant Field Values

accessibleContext

protected AccessibleContext accessibleContext
The AccessibleContext associated with this JComponent.

Constructor Detail

JComponent

public JComponent()
Default JComponent constructor. This constructor does very little initialization beyond calling the Container constructor. For example, the initial layout manager is null. It does, however, set the component's locale property to the value returned by JComponent.getDefaultLocale.

See Also:
getDefaultLocale()
Method Detail

setInheritsPopupMenu

public void setInheritsPopupMenu(boolean value)
Sets whether or not getComponentPopupMenu should delegate to the parent if this component does not have a JPopupMenu assigned to it.

The default value for this is false, but some JComponent subclasses that are implemented as a number of JComponents may set this to true.

This is a bound property.

Parameters:
value - whether or not the JPopupMenu is inherited
Since:
1.5
See Also:
setComponentPopupMenu(javax.swing.JPopupMenu)

getInheritsPopupMenu

public boolean getInheritsPopupMenu()
Returns true if the JPopupMenu should be inherited from the parent.

Since:
1.5
See Also:
setComponentPopupMenu(javax.swing.JPopupMenu)

setComponentPopupMenu

public void setComponentPopupMenu(JPopupMenu popup)
Sets the JPopupMenu for this JComponent. The UI is responsible for registering bindings and adding the necessary listeners such that the JPopupMenu will be shown at the appropriate time. When the JPopupMenu is shown depends upon the look and feel: some may show it on a mouse event, some may enable a key binding.

If popup is null, and getInheritsPopupMenu returns true, then getComponentPopupMenu will be delegated to the parent. This provides for a way to make all child components inherit the popupmenu of the parent.

This is a bound property.

Parameters:
popup - - the popup that will be assigned to this component may be null
Since:
1.5
See Also:
getComponentPopupMenu()

getComponentPopupMenu

public JPopupMenu getComponentPopupMenu()
Returns JPopupMenu that assigned for this component. If this component does not have a JPopupMenu assigned to it and getInheritsPopupMenu is true, this will return getParent().getComponentPopupMenu() (assuming the parent is valid.)

Returns:
JPopupMenu assigned for this component or null if no popup assigned
Since:
1.5
See Also:
setComponentPopupMenu(javax.swing.JPopupMenu)

updateUI

public void updateUI()
Resets the UI property to a value from the current look and feel. JComponent subclasses must override this method like this:
   public void updateUI() {
      setUI((SliderUI)UIManager.getUI(this);
   }

See Also:
setUI(javax.swing.plaf.ComponentUI),
UIManager.getLookAndFeel(),
UIManager.getUI(javax.swing.JComponent)

setUI

protected void setUI(ComponentUI newUI)
Sets the look and feel delegate for this component. JComponent subclasses generally override this method to narrow the argument type. For example, in JSlider:
 public void setUI(SliderUI newUI) {
     super.setUI(newUI);
 }

Additionally JComponent subclasses must provide a getUI method that returns the correct type. For example:

 public SliderUI getUI() {
     return (SliderUI)ui;
 }

Parameters:
newUI - the new UI delegate
See Also:
updateUI(),
UIManager.getLookAndFeel(),
UIManager.getUI(javax.swing.JComponent)

getUIClassID

public String getUIClassID()
Returns the UIDefaults key used to look up the name of the swing.plaf.ComponentUI class that defines the look and feel for this component. Most applications will never need to call this method. Subclasses of JComponent that support pluggable look and feel should override this method to return a UIDefaults key that maps to the ComponentUI subclass that defines their look and feel.

Returns:
the UIDefaults key for a ComponentUI subclass
See Also:
UIDefaults.getUI(javax.swing.JComponent)

getComponentGraphics

protected Graphics getComponentGraphics(Graphics g)
Returns the graphics object used to paint this component. If DebugGraphics is turned on we create a new DebugGraphics object if necessary. Otherwise we just configure the specified graphics object's foreground and font.

Parameters:
g - the original Graphics object
Returns:
a Graphics object configured for this component

paintComponent

protected void paintComponent(Graphics g)
Calls the UI delegate's paint method, if the UI delegate is non-null. We pass the delegate a copy of the Graphics object to protect the rest of the paint code from irrevocable changes (for example, Graphics.translate).

If you override this in a subclass you should not make permanent changes to the passed in Graphics. For example, you should not alter the clip Rectangle or modify the transform. If you need to do these operations you may find it easier to create a new Graphics from the passed in Graphics and manipulate it. Further, if you do not invoker super's implementation you must honor the opaque property, that is if this component is opaque, you must completely fill in the background in a non-opaque color. If you do not honor the opaque property you will likely see visual artifacts.

The passed in Graphics object might have a transform other than the identify transform installed on it. In this case, you might get unexpected results if you cumulatively apply another transform.

Parameters:
g - the Graphics object to protect
See Also:
paint(java.awt.Graphics), ComponentUI

paintChildren

protected void paintChildren(Graphics g)
Paints this component's children. If shouldUseBuffer is true, no component ancestor has a buffer and the component children can use a buffer if they have one. Otherwise, one ancestor has a buffer currently in use and children should not use a buffer to paint.

Parameters:
g - the Graphics context in which to paint
See Also:
paint(java.awt.Graphics), Container.paint(java.awt.Graphics)

paintBorder

protected void paintBorder(Graphics g)
Paints the component's border.

If you override this in a subclass you should not make permanent changes to the passed in Graphics. For example, you should not alter the clip Rectangle or modify the transform. If you need to do these operations you may find it easier to create a new Graphics from the passed in Graphics and manipulate it.

Parameters:
g - the Graphics context in which to paint
See Also:
paint(java.awt.Graphics), setBorder(javax.swing.border.Border)

update

public void update(Graphics g)
Calls paint. Doesn't clear the background but see ComponentUI.update, which is called by paintComponent.

Overrides:
update in class Container
Parameters:
g - the Graphics context in which to paint
See Also:
paint(java.awt.Graphics), paintComponent(java.awt.Graphics), ComponentUI

paint

public void paint(Graphics g)
Invoked by Swing to draw components. Applications should not invoke paint directly, but should instead use the repaint method to schedule the component for redrawing.

This method actually delegates the work of painting to three protected methods: paintComponent, paintBorder, and paintChildren. They're called in the order listed to ensure that children appear on top of component itself. Generally speaking, the component and its children should not paint in the insets area allocated to the border. Subclasses can just override this method, as always. A subclass that just wants to specialize the UI (look and feel) delegate's paint method should just override paintComponent.

Overrides:
paint in class Container
Parameters:
g - the Graphics context in which to paint
See Also:
paintComponent(java.awt.Graphics),
paintBorder(java.awt.Graphics),
paintChildren(java.awt.Graphics),
getComponentGraphics(java.awt.Graphics),
repaint(long, int, int, int, int)

printAll

public void printAll(Graphics g)
Invoke this method to print the component. This method invokes print on the component.

Overrides:
printAll in class Component
Parameters:
g - the Graphics context in which to paint
See Also:
print(java.awt.Graphics),
printComponent(java.awt.Graphics),
printBorder(java.awt.Graphics),
printChildren(java.awt.Graphics)

print

public void print(Graphics g)
Invoke this method to print the component to the specified Graphics. This method will result in invocations of printComponent, printBorder and printChildren. It is recommended that you override one of the previously mentioned methods rather than this one if your intention is to customize the way printing looks. However, it can be useful to override this method should you want to prepare state before invoking the superclass behavior. As an example, if you wanted to change the component's background color before printing, you could do the following:
     public void print(Graphics g) {
         Color orig = getBackground();
         setBackground(Color.WHITE);

         // wrap in try/finally so that we always restore the state
         try {
             super.print(g);
         } finally {
             setBackground(orig);
         }
     }

Alternatively, or for components that delegate painting to other objects, you can query during painting whether or not the component is in the midst of a print operation. The isPaintingForPrint method provides this ability and its return value will be changed by this method: to true immediately before rendering and to false immediately after. With each change a property change event is fired on this component with the name "paintingForPrint".

This method sets the component's state such that the double buffer will not be used: painting will be done directly on the passed in Graphics.

Overrides:
print in class Container
Parameters:
g - the Graphics context in which to paint
See Also:
printComponent(java.awt.Graphics),
printBorder(java.awt.Graphics),
printChildren(java.awt.Graphics),
isPaintingForPrint()

printComponent

protected void printComponent(Graphics g)
This is invoked during a printing operation. This is implemented to invoke paintComponent on the component. Override this if you wish to add special painting behavior when printing.

Parameters:
g - the Graphics context in which to paint
Since:
1.3
See Also:
print(java.awt.Graphics)

printChildren

protected void printChildren(Graphics g)
Prints this component's children. This is implemented to invoke paintChildren on the component. Override this if you wish to print the children differently than painting.

Parameters:
g - the Graphics context in which to paint
Since:
1.3
See Also:
print(java.awt.Graphics)

printBorder

protected void printBorder(Graphics g)
Prints the component's border. This is implemented to invoke paintBorder on the component. Override this if you wish to print the border differently that it is painted.

Parameters:
g - the Graphics context in which to paint
Since:
1.3
See Also:
print(java.awt.Graphics)

isPaintingTile

public boolean isPaintingTile()
Returns true if the component is currently painting a tile. If this method returns true, paint will be called again for another tile. This method returns false if you are not painting a tile or if the last tile is painted. Use this method to keep some state you might need between tiles.

Returns:
true if the component is currently painting a tile, false otherwise

isPaintingForPrint

public final boolean isPaintingForPrint()
Returns true if the current painting operation on this component is part of a print operation. This method is useful when you want to customize what you print versus what you show on the screen.

You can detect changes in the value of this property by listening for property change events on this component with name "paintingForPrint".

Note: This method provides complimentary functionality to that provided by other high level Swing printing APIs. However, it deals strictly with painting and should not be confused as providing information on higher level print processes. For example, a JTable.print() operation doesn't necessarily result in a continuous rendering of the full component, and the return value of this method can change multiple times during that operation. It is even possible for the component to be painted to the screen while the printing process is ongoing. In such a case, the return value of this method is true when, and only when, the table is being painted as part of the printing process.

Returns:
true if the current painting operation on this component is part of a print operation
Since:
1.6
See Also:
print(java.awt.Graphics)

isManagingFocus

@Deprecated
public boolean isManagingFocus()
Deprecated. As of 1.4, replaced by Component.setFocusTraversalKeys(int, Set) and Container.setFocusCycleRoot(boolean).

In release 1.4, the focus subsystem was rearchitected. For more information, see How to Use the Focus Subsystem, a section in The Java Tutorial.

Changes this JComponent's focus traversal keys to CTRL+TAB and CTRL+SHIFT+TAB. Also prevents SortingFocusTraversalPolicy from considering descendants of this JComponent when computing a focus traversal cycle.

See Also:
Component.setFocusTraversalKeys(int, java.util.Set), SortingFocusTraversalPolicy

setNextFocusableComponent

@Deprecated
public void setNextFocusableComponent(Component aComponent)
Deprecated. As of 1.4, replaced by FocusTraversalPolicy

In release 1.4, the focus subsystem was rearchitected. For more information, see How to Use the Focus Subsystem, a section in The Java Tutorial.

Overrides the default FocusTraversalPolicy for this JComponent's focus traversal cycle by unconditionally setting the specified Component as the next Component in the cycle, and this JComponent as the specified Component's previous Component in the cycle.

Parameters:
aComponent - the Component that should follow this JComponent in the focus traversal cycle
See Also:
getNextFocusableComponent(), FocusTraversalPolicy

getNextFocusableComponent

@Deprecated
public Component getNextFocusableComponent()
Deprecated. As of 1.4, replaced by FocusTraversalPolicy.

In release 1.4, the focus subsystem was rearchitected. For more information, see How to Use the Focus Subsystem, a section in The Java Tutorial.

Returns the Component set by a prior call to setNextFocusableComponent(Component) on this JComponent.

Returns:
the Component that will follow this JComponent in the focus traversal cycle, or null if none has been explicitly specified
See Also:
setNextFocusableComponent(java.awt.Component)

setRequestFocusEnabled

public void setRequestFocusEnabled(boolean requestFocusEnabled)
Provides a hint as to whether or not this JComponent should get focus. This is only a hint, and it is up to consumers that are requesting focus to honor this property. This is typically honored for mouse operations, but not keyboard operations. For example, look and feels could verify this property is true before requesting focus during a mouse operation. This would often times be used if you did not want a mouse press on a JComponent to steal focus, but did want the JComponent to be traversable via the keyboard. If you do not want this JComponent focusable at all, use the setFocusable method instead.

Please see How to Use the Focus Subsystem, a section in The Java Tutorial, for more information.

Parameters:
requestFocusEnabled - indicates whether you want this JComponent to be focusable or not
See Also:
Focus Specification, Component.setFocusable(boolean)

isRequestFocusEnabled

public boolean isRequestFocusEnabled()
Returns true if this JComponent should get focus; otherwise returns false.

Please see How to Use the Focus Subsystem, a section in The Java Tutorial, for more information.

Returns:
true if this component should get focus, otherwise returns false
See Also:
setRequestFocusEnabled(boolean), Focus Specification, Component.isFocusable()

requestFocus

public void requestFocus()
Requests that this Component gets the input focus. Refer to Component.requestFocus() for a complete description of this method.

Note that the use of this method is discouraged because its behavior is platform dependent. Instead we recommend the use of requestFocusInWindow(). If you would like more information on focus, see How to Use the Focus Subsystem, a section in The Java Tutorial.

Overrides:
requestFocus in class Component
Since:
1.4
See Also:
Component.requestFocusInWindow(), Component.requestFocusInWindow(boolean)

requestFocus

public boolean requestFocus(boolean temporary)
Requests that this Component gets the input focus. Refer to Component.requestFocus(boolean) for a complete description of this method.

Note that the use of this method is discouraged because its behavior is platform dependent. Instead we recommend the use of requestFocusInWindow(boolean). If you would like more information on focus, see How to Use the Focus Subsystem, a section in The Java Tutorial.

Overrides:
requestFocus in class Component
Parameters:
temporary - boolean indicating if the focus change is temporary
Returns:
false if the focus change request is guaranteed to fail; true if it is likely to succeed
Since:
1.4
See Also:
Component.requestFocusInWindow(), Component.requestFocusInWindow(boolean)

requestFocusInWindow

public boolean requestFocusInWindow()
Requests that this Component gets the input focus. Refer to Component.requestFocusInWindow() for a complete description of this method.

If you would like more information on focus, see How to Use the Focus Subsystem, a section in The Java Tutorial.

Overrides:
requestFocusInWindow in class Component
Returns:
false if the focus change request is guaranteed to fail; true if it is likely to succeed
Since:
1.4
See Also:
Component.requestFocusInWindow(), Component.requestFocusInWindow(boolean)

requestFocusInWindow

protected boolean requestFocusInWindow(boolean temporary)
Requests that this Component gets the input focus. Refer to Component.requestFocusInWindow(boolean) for a complete description of this method.

If you would like more information on focus, see How to Use the Focus Subsystem, a section in The Java Tutorial.

Overrides:
requestFocusInWindow in class Component
Parameters:
temporary - boolean indicating if the focus change is temporary
Returns:
false if the focus change request is guaranteed to fail; true if it is likely to succeed
Since:
1.4
See Also:
Component.requestFocusInWindow(), Component.requestFocusInWindow(boolean)

grabFocus

public void grabFocus()
Requests that this Component get the input focus, and that this Component's top-level ancestor become the focused Window. This component must be displayable, visible, and focusable for the request to be granted.

This method is intended for use by focus implementations. Client code should not use this method; instead, it should use requestFocusInWindow().

See Also:
requestFocusInWindow()

setVerifyInputWhenFocusTarget

public void setVerifyInputWhenFocusTarget(boolean verifyInputWhenFocusTarget)
Sets the value to indicate whether input verifier for the current focus owner will be called before this component requests focus. The default is true. Set to false on components such as a Cancel button or a scrollbar, which should activate even if the input in the current focus owner is not "passed" by the input verifier for that component.

Parameters:
verifyInputWhenFocusTarget - value for the verifyInputWhenFocusTarget property
Since:
1.3
See Also:
InputVerifier,
setInputVerifier(javax.swing.InputVerifier),
getInputVerifier(),
getVerifyInputWhenFocusTarget()

getVerifyInputWhenFocusTarget

public boolean getVerifyInputWhenFocusTarget()
Returns the value that indicates whether the input verifier for the current focus owner will be called before this component requests focus.

Returns:
value of the verifyInputWhenFocusTarget property
Since:
1.3
See Also:
InputVerifier,
setInputVerifier(javax.swing.InputVerifier),
getInputVerifier(),
setVerifyInputWhenFocusTarget(boolean)

getFontMetrics

public FontMetrics getFontMetrics(Font font)
Gets the FontMetrics for the specified Font.

Overrides:
getFontMetrics in class Component
Parameters:
font - the font for which font metrics is to be obtained
Returns:
the font metrics for font
Throws:
NullPointerException - if font is null
Since:
1.5
See Also:
Component.getFont(),
Component.getPeer(),
ComponentPeer.getFontMetrics(Font),
Toolkit.getFontMetrics(Font)

setPreferredSize

public void setPreferredSize(Dimension preferredSize)
Sets the preferred size of this component. If preferredSize is null, the UI will be asked for the preferred size.

Overrides:
setPreferredSize in class Component
Parameters:
preferredSize - The new preferred size, or null
See Also:
Component.getPreferredSize(), Component.isPreferredSizeSet()

getPreferredSize

public Dimension getPreferredSize()
If the preferredSize has been set to a non-null value just returns it. If the UI delegate's getPreferredSize method returns a non null value then return that; otherwise defer to the component's layout manager.

Overrides:
getPreferredSize in class Container
Returns:
the value of the preferredSize property
See Also:
setPreferredSize(java.awt.Dimension), ComponentUI

setMaximumSize

public void setMaximumSize(Dimension maximumSize)
Sets the maximum size of this component to a constant value. Subsequent calls to getMaximumSize will always return this value; the component's UI will not be asked to compute it. Setting the maximum size to null restores the default behavior.

Overrides:
setMaximumSize in class Component
Parameters:
maximumSize - a Dimension containing the desired maximum allowable size
See Also:
getMaximumSize()

getMaximumSize

public Dimension getMaximumSize()
If the maximum size has been set to a non-null value just returns it. If the UI delegate's getMaximumSize method returns a non-null value then return that; otherwise defer to the component's layout manager.

Overrides:
getMaximumSize in class Container
Returns:
the value of the maximumSize property
See Also:
setMaximumSize(java.awt.Dimension), ComponentUI

setMinimumSize

public void setMinimumSize(Dimension minimumSize)
Sets the minimum size of this component to a constant value. Subsequent calls to getMinimumSize will always return this value; the component's UI will not be asked to compute it. Setting the minimum size to null restores the default behavior.

Overrides:
setMinimumSize in class Component
Parameters:
minimumSize - the new minimum size of this component
See Also:
getMinimumSize()

getMinimumSize

public Dimension getMinimumSize()
If the minimum size has been set to a non-null value just returns it. If the UI delegate's getMinimumSize method returns a non-null value then return that; otherwise defer to the component's layout manager.

Overrides:
getMinimumSize in class Container
Returns:
the value of the minimumSize property
See Also:
setMinimumSize(java.awt.Dimension), ComponentUI

contains

public boolean contains(int x,
                        int y)
Gives the UI delegate an opportunity to define the precise shape of this component for the sake of mouse processing.

Overrides:
contains in class Component
Parameters:
x - the x coordinate of the point
y - the y coordinate of the point
Returns:
true if this component logically contains x,y
See Also:
Component.contains(int, int), ComponentUI

setBorder

public void setBorder(Border border)
Sets the border of this component. The Border object is responsible for defining the insets for the component (overriding any insets set directly on the component) and for optionally rendering any border decorations within the bounds of those insets. Borders should be used (rather than insets) for creating both decorative and non-decorative (such as margins and padding) regions for a swing component. Compound borders can be used to nest multiple borders within a single component.

Although technically you can set the border on any object that inherits from JComponent, the look and feel implementation of many standard Swing components doesn't work well with user-set borders. In general, when you want to set a border on a standard Swing component other than JPanel or JLabel, we recommend that you put the component in a JPanel and set the border on the JPanel.

This is a bound property.

Parameters:
border - the border to be rendered for this component
See Also:
Border, CompoundBorder

getBorder

public Border getBorder()
Returns the border of this component or null if no border is currently set.

Returns:
the border object for this component
See Also:
setBorder(javax.swing.border.Border)

getInsets

public Insets getInsets()
If a border has been set on this component, returns the border's insets; otherwise calls super.getInsets.

Overrides:
getInsets in class Container
Returns:
the value of the insets property
See Also:
setBorder(javax.swing.border.Border)

getInsets

public Insets getInsets(Insets insets)
Returns an Insets object containing this component's inset values. The passed-in Insets object will be reused if possible. Calling methods cannot assume that the same object will be returned, however. All existing values within this object are overwritten. If insets is null, this will allocate a new one.

Parameters:
insets - the Insets object, which can be reused
Returns:
the Insets object
See Also:
getInsets()

getAlignmentY

public float getAlignmentY()
Overrides Container.getAlignmentY to return the horizontal alignment.

Overrides:
getAlignmentY in class Container
Returns:
the value of the alignmentY property
See Also:
setAlignmentY(float), Component.getAlignmentY()

setAlignmentY

public void setAlignmentY(float alignmentY)
Sets the the horizontal alignment.

Parameters:
alignmentY - the new horizontal alignment
See Also:
getAlignmentY()

getAlignmentX

public float getAlignmentX()
Overrides Container.getAlignmentX to return the vertical alignment.

Overrides:
getAlignmentX in class Container
Returns:
the value of the alignmentX property
See Also:
setAlignmentX(float), Component.getAlignmentX()

setAlignmentX

public void setAlignmentX(float alignmentX)
Sets the the vertical alignment.

Parameters:
alignmentX - the new vertical alignment
See Also:
getAlignmentX()

setInputVerifier

public void setInputVerifier(InputVerifier inputVerifier)
Sets the input verifier for this component.

Parameters:
inputVerifier - the new input verifier
Since:
1.3
See Also:
InputVerifier

getInputVerifier

public InputVerifier getInputVerifier()
Returns the input verifier for this component.

Returns:
the inputVerifier property
Since:
1.3
See Also:
InputVerifier

getGraphics

public Graphics getGraphics()
Returns this component's graphics context, which lets you draw on a component. Use this method to get a Graphics object and then invoke operations on that object to draw on the component.

Overrides:
getGraphics in class Component
Returns:
this components graphics context
See Also:
Component.paint(java.awt.Graphics)

setDebugGraphicsOptions

public void setDebugGraphicsOptions(int debugOptions)
Enables or disables diagnostic information about every graphics operation performed within the component or one of its children.

Parameters:
debugOptions - determines how the component should display the information; one of the following options:
  • DebugGraphics.LOG_OPTION - causes a text message to be printed.
  • DebugGraphics.FLASH_OPTION - causes the drawing to flash several times.
  • DebugGraphics.BUFFERED_OPTION - creates an ExternalWindow that displays the operations performed on the View's offscreen buffer.
  • DebugGraphics.NONE_OPTION disables debugging.
  • A value of 0 causes no changes to the debugging options.
debugOptions is bitwise OR'd into the current value

getDebugGraphicsOptions

public int getDebugGraphicsOptions()
Returns the state of graphics debugging.

Returns:
a bitwise OR'd flag of zero or more of the following options:
  • DebugGraphics.LOG_OPTION - causes a text message to be printed.
  • DebugGraphics.FLASH_OPTION - causes the drawing to flash several times.
  • DebugGraphics.BUFFERED_OPTION - creates an ExternalWindow that displays the operations performed on the View's offscreen buffer.
  • DebugGraphics.NONE_OPTION disables debugging.
  • A value of 0 causes no changes to the debugging options.
See Also:
setDebugGraphicsOptions(int)

registerKeyboardAction

public void registerKeyboardAction(ActionListener anAction,
                                   String aCommand,
                                   KeyStroke aKeyStroke,
                                   int aCondition)
This method is now obsolete, please use a combination of getActionMap() and getInputMap() for similiar behavior. For example, to bind the KeyStroke aKeyStroke to the Action anAction now use:
   component.getInputMap().put(aKeyStroke, aCommand);
   component.getActionMap().put(aCommmand, anAction);
The above assumes you want the binding to be applicable for WHEN_FOCUSED. To register bindings for other focus states use the getInputMap method that takes an integer.

Register a new keyboard action. anAction will be invoked if a key event matching aKeyStroke occurs and aCondition is verified. The KeyStroke object defines a particular combination of a keyboard key and one or more modifiers (alt, shift, ctrl, meta).

The aCommand will be set in the delivered event if specified.

The aCondition can be one of:

WHEN_FOCUSED
The action will be invoked only when the keystroke occurs while the component has the focus.
WHEN_IN_FOCUSED_WINDOW
The action will be invoked when the keystroke occurs while the component has the focus or if the component is in the window that has the focus. Note that the component need not be an immediate descendent of the window -- it can be anywhere in the window's containment hierarchy. In other words, whenever any component in the window has the focus, the action registered with this component is invoked.
WHEN_ANCESTOR_OF_FOCUSED_COMPONENT
The action will be invoked when the keystroke occurs while the component has the focus or if the component is an ancestor of the component that has the focus.

The combination of keystrokes and conditions lets you define high level (semantic) action events for a specified keystroke+modifier combination (using the KeyStroke class) and direct to a parent or child of a component that has the focus, or to the component itself. In other words, in any hierarchical structure of components, an arbitrary key-combination can be immediately directed to the appropriate component in the hierarchy, and cause a specific method to be invoked (usually by way of adapter objects).

If an action has already been registered for the receiving container, with the same charCode and the same modifiers, anAction will replace the action.

Parameters:
anAction - the Action to be registered
aCommand - the command to be set in the delivered event
aKeyStroke - the KeyStroke to bind to the action
aCondition - the condition that needs to be met, see above
See Also:
KeyStroke

registerKeyboardAction

public void registerKeyboardAction(ActionListener anAction,
                                   KeyStroke aKeyStroke,
                                   int aCondition)
This method is now obsolete, please use a combination of getActionMap() and getInputMap() for similiar behavior.

unregisterKeyboardAction

public void unregisterKeyboardAction(KeyStroke aKeyStroke)
This method is now obsolete. To unregister an existing binding you can either remove the binding from the ActionMap/InputMap, or place a dummy binding the InputMap. Removing the binding from the InputMap allows bindings in parent InputMaps to be active, whereas putting a dummy binding in the InputMap effectively disables the binding from ever happening.

Unregisters a keyboard action. This will remove the binding from the ActionMap (if it exists) as well as the InputMaps.

getRegisteredKeyStrokes

public KeyStroke[] getRegisteredKeyStrokes()
Returns the KeyStrokes that will initiate registered actions.

Returns:
an array of KeyStroke objects
See Also:
registerKeyboardAction(java.awt.event.ActionListener, java.lang.String, javax.swing.KeyStroke, int)

getConditionForKeyStroke

public int getConditionForKeyStroke(KeyStroke aKeyStroke)
Returns the condition that determines whether a registered action occurs in response to the specified keystroke.

For Java 2 platform v1.3, a KeyStroke can be associated with more than one condition. For example, 'a' could be bound for the two conditions WHEN_FOCUSED and WHEN_IN_FOCUSED_WINDOW condition.

Returns:
the action-keystroke condition

getActionForKeyStroke

public ActionListener getActionForKeyStroke(KeyStroke aKeyStroke)
Returns the object that will perform the action registered for a given keystroke.

Returns:
the ActionListener object invoked when the keystroke occurs

resetKeyboardActions

public void resetKeyboardActions()
Unregisters all the bindings in the first tier InputMaps and ActionMap. This has the effect of removing any local bindings, and allowing the bindings defined in parent InputMap/ActionMaps (the UI is usually defined in the second tier) to persist.

setInputMap

public final void setInputMap(int condition,
                              InputMap map)
Sets the InputMap to use under the condition condition to map. A null value implies you do not want any bindings to be used, even from the UI. This will not reinstall the UI InputMap (if there was one). condition has one of the following values:
  • WHEN_IN_FOCUSED_WINDOW
  • WHEN_FOCUSED
  • WHEN_ANCESTOR_OF_FOCUSED_COMPONENT
If condition is WHEN_IN_FOCUSED_WINDOW and map is not a ComponentInputMap, an IllegalArgumentException will be thrown. Similarly, if condition is not one of the values listed, an IllegalArgumentException will be thrown.

Parameters:
condition - one of the values listed above
map - the InputMap to use for the given condition
Throws:
IllegalArgumentException - if condition is WHEN_IN_FOCUSED_WINDOW and map is not an instance of ComponentInputMap; or if condition is not one of the legal values specified above
Since:
1.3

getInputMap

public final InputMap getInputMap(int condition)
Returns the InputMap that is used during condition.

Parameters:
condition - one of WHEN_IN_FOCUSED_WINDOW, WHEN_FOCUSED, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT
Returns:
the InputMap for the specified condition
Since:
1.3

getInputMap

public final InputMap getInputMap()
Returns the InputMap that is used when the component has focus. This is convenience method for getInputMap(WHEN_FOCUSED).

Returns:
the InputMap used when the component has focus
Since:
1.3

setActionMap

public final void setActionMap(ActionMap am)
Sets the ActionMap to am. This does not set the parent of the am to be the ActionMap from the UI (if there was one), it is up to the caller to have done this.

Parameters:
am - the new ActionMap
Since:
1.3

getActionMap

public final ActionMap getActionMap()
Returns the ActionMap used to determine what Action to fire for particular KeyStroke binding. The returned ActionMap, unless otherwise set, will have the ActionMap from the UI set as the parent.

Returns:
the ActionMap containing the key/action bindings
Since:
1.3

getBaseline

public int getBaseline(int width,
                       int height)
Returns the baseline. The baseline is measured from the top of the component. This method is primarily meant for LayoutManagers to align components along their baseline. A return value less than 0 indicates this component does not have a reasonable baseline and that LayoutManagers should not align this component on its baseline.

This method calls into the ComponentUI method of the same name. If this component does not have a ComponentUI -1 will be returned. If a value >= 0 is returned, then the component has a valid baseline for any size >= the minimum size and getBaselineResizeBehavior can be used to determine how the baseline changes with size.

Overrides:
getBaseline in class Component
Parameters:
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
the baseline or < 0 indicating there is no reasonable baseline
Throws:
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
getBaselineResizeBehavior(), FontMetrics

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior()
Returns an enum indicating how the baseline of the component changes as the size changes. This method is primarily meant for layout managers and GUI builders.

This method calls into the ComponentUI method of the same name. If this component does not have a ComponentUI BaselineResizeBehavior.OTHER will be returned. Subclasses should never return null; if the baseline can not be calculated return BaselineResizeBehavior.OTHER. Callers should first ask for the baseline using getBaseline and if a value >= 0 is returned use this method. It is acceptable for this method to return a value other than BaselineResizeBehavior.OTHER even if getBaseline returns a value less than 0.

Overrides:
getBaselineResizeBehavior in class Component
Returns:
an enum indicating how the baseline changes as the component size changes
Since:
1.6
See Also:
getBaseline(int, int)

requestDefaultFocus

@Deprecated
public boolean requestDefaultFocus()
Deprecated. As of 1.4, replaced by FocusTraversalPolicy.getDefaultComponent(Container).requestFocus()

In release 1.4, the focus subsystem was rearchitected. For more information, see How to Use the Focus Subsystem, a section in The Java Tutorial.

Requests focus on this JComponent's FocusTraversalPolicy's default Component. If this JComponent is a focus cycle root, then its FocusTraversalPolicy is used. Otherwise, the FocusTraversalPolicy of this JComponent's focus-cycle-root ancestor is used.

See Also:
FocusTraversalPolicy.getDefaultComponent(java.awt.Container)

setVisible

public void setVisible(boolean aFlag)
Makes the component visible or invisible. Overrides Component.setVisible.

Overrides:
setVisible in class Component
Parameters:
aFlag - true to make the component visible; false to make it invisible
See Also:
Component.isVisible()

setEnabled

public void setEnabled(boolean enabled)
Sets whether or not this component is enabled. A component that is enabled may respond to user input, while a component that is not enabled cannot respond to user input. Some components may alter their visual representation when they are disabled in order to provide feedback to the user that they cannot take input.

Note: Disabling a component does not disable its children.

Note: Disabling a lightweight component does not prevent it from receiving MouseEvents.

Overrides:
setEnabled in class Component
Parameters:
enabled - true if this component should be enabled, false otherwise
See Also:
Component.isEnabled(), Component.isLightweight()

setForeground

public void setForeground(Color fg)
Sets the foreground color of this component. It is up to the look and feel to honor this property, some may choose to ignore it.

Overrides:
setForeground in class Component
Parameters:
fg - the desired foreground Color
See Also:
Component.getForeground()

setBackground

public void setBackground(Color bg)
Sets the background color of this component. The background color is used only if the component is opaque, and only by subclasses of JComponent or ComponentUI implementations. Direct subclasses of JComponent must override paintComponent to honor this property.

It is up to the look and feel to honor this property, some may choose to ignore it.

Overrides:
setBackground in class Component
Parameters:
bg - the desired background Color
See Also:
Component.getBackground(), setOpaque(boolean)

setFont

public void setFont(Font font)
Sets the font for this component.

Overrides:
setFont in class Container
Parameters:
font - the desired Font for this component
See Also:
Component.getFont()

getDefaultLocale

public static Locale getDefaultLocale()
Returns the default locale used to initialize each JComponent's locale property upon creation. The default locale has "AppContext" scope so that applets (and potentially multiple lightweight applications running in a single VM) can have their own setting. An applet can safely alter its default locale because it will have no affect on other applets (or the browser).

Returns:
the default Locale.
Since:
1.4
See Also:
setDefaultLocale(java.util.Locale),
Component.getLocale(),
Component.setLocale(java.util.Locale)

setDefaultLocale

public static void setDefaultLocale(Locale l)
Sets the default locale used to initialize each JComponent's locale property upon creation. The initial value is the VM's default locale. The default locale has "AppContext" scope so that applets (and potentially multiple lightweight applications running in a single VM) can have their own setting. An applet can safely alter its default locale because it will have no affect on other applets (or the browser).

Parameters:
l - the desired default Locale for new components.
Since:
1.4
See Also:
getDefaultLocale(),
Component.getLocale(),
Component.setLocale(java.util.Locale)

processComponentKeyEvent

protected void processComponentKeyEvent(KeyEvent e)
Processes any key events that the component itself recognizes. This is called after the focus manager and any interested listeners have been given a chance to steal away the event. This method is called only if the event has not yet been consumed. This method is called prior to the keyboard UI logic.

This method is implemented to do nothing. Subclasses would normally override this method if they process some key events themselves. If the event is processed, it should be consumed.

processKeyEvent

protected void processKeyEvent(KeyEvent e)
Overrides processKeyEvent to process events.

Overrides:
processKeyEvent in class Component
Parameters:
e - the key event
See Also:
KeyEvent, KeyListener, KeyboardFocusManager, DefaultKeyboardFocusManager, Component.processEvent(java.awt.AWTEvent), Component.dispatchEvent(java.awt.AWTEvent), Component.addKeyListener(java.awt.event.KeyListener), Component.enableEvents(long), Component.isShowing()

processKeyBinding

protected boolean processKeyBinding(KeyStroke ks,
                                    KeyEvent e,
                                    int condition,
                                    boolean pressed)
Invoked to process the key bindings for ks as the result of the KeyEvent e. This obtains the appropriate InputMap, gets the binding, gets the action from the ActionMap, and then (if the action is found and the component is enabled) invokes notifyAction to notify the action.

Parameters:
ks - the KeyStroke queried
e - the KeyEvent
condition - one of the following values:
  • JComponent.WHEN_FOCUSED
  • JComponent.WHEN_ANCESTOR_OF_FOCUSED_COMPONENT
  • JComponent.WHEN_IN_FOCUSED_WINDOW
pressed - true if the key is pressed
Returns:
true if there was a binding to an action, and the action was enabled
Since:
1.3

setToolTipText

public void setToolTipText(String text)
Registers the text to display in a tool tip. The text displays when the cursor lingers over the component.

See How to Use Tool Tips in The Java Tutorial for further documentation.

Parameters:
text - the string to display; if the text is null, the tool tip is turned off for this component
See Also:
TOOL_TIP_TEXT_KEY

getToolTipText

public String getToolTipText()
Returns the tooltip string that has been set with setToolTipText.

Returns:
the text of the tool tip
See Also:
TOOL_TIP_TEXT_KEY

getToolTipText

public String getToolTipText(MouseEvent event)
Returns the string to be used as the tooltip for event. By default this returns any string set using setToolTipText. If a component provides more extensive API to support differing tooltips at different locations, this method should be overridden.

getToolTipLocation

public Point getToolTipLocation(MouseEvent event)
Returns the tooltip location in this component's coordinate system. If null is returned, Swing will choose a location. The default implementation returns null.

Parameters:
event - the MouseEvent that caused the ToolTipManager to show the tooltip
Returns:
always returns null

getPopupLocation

public Point getPopupLocation(MouseEvent event)
Returns the preferred location to display the popup menu in this component's coordinate system. It is up to the look and feel to honor this property, some may choose to ignore it. If null, the look and feel will choose a suitable location.

Parameters:
event - the MouseEvent that triggered the popup to be shown, or null if the popup is not being shown as the result of a mouse event
Returns:
location to display the JPopupMenu, or null
Since:
1.5

createToolTip

public JToolTip createToolTip()
Returns the instance of JToolTip that should be used to display the tooltip. Components typically would not override this method, but it can be used to cause different tooltips to be displayed differently.

Returns:
the JToolTip used to display this toolTip

scrollRectToVisible

public void scrollRectToVisible(Rectangle aRect)
Forwards the scrollRectToVisible() message to the JComponent's parent. Components that can service the request, such as JViewport, override this method and perform the scrolling.

Parameters:
aRect - the visible Rectangle
See Also:
JViewport

setAutoscrolls

public void setAutoscrolls(boolean autoscrolls)
Sets the autoscrolls property. If true mouse dragged events will be synthetically generated when the mouse is dragged outside of the component's bounds and mouse motion has paused (while the button continues to be held down). The synthetic events make it appear that the drag gesture has resumed in the direction established when the component's boundary was crossed. Components that support autoscrolling must handle mouseDragged events by calling scrollRectToVisible with a rectangle that contains the mouse event's location. All of the Swing components that support item selection and are typically displayed in a JScrollPane (JTable, JList, JTree, JTextArea, and JEditorPane) already handle mouse dragged events in this way. To enable autoscrolling in any other component, add a mouse motion listener that calls scrollRectToVisible. For example, given a JPanel, myPanel:
 MouseMotionListener doScrollRectToVisible = new MouseMotionAdapter() {
     public void mouseDragged(MouseEvent e) {
        Rectangle r = new Rectangle(e.getX(), e.getY(), 1, 1);
        ((JPanel)e.getSource()).scrollRectToVisible(r);
    }
 };
 myPanel.addMouseMotionListener(doScrollRectToVisible);
The default value of the autoScrolls property is false.

Parameters:
autoscrolls - if true, synthetic mouse dragged events are generated when the mouse is dragged outside of a component's bounds and the mouse button continues to be held down; otherwise false
See Also:
getAutoscrolls(), JViewport, JScrollPane

getAutoscrolls

public boolean getAutoscrolls()
Gets the autoscrolls property.

Returns:
the value of the autoscrolls property
See Also:
JViewport, setAutoscrolls(boolean)

setTransferHandler

public void setTransferHandler(TransferHandler newHandler)
Sets the transferHandler property, which is null if the component does not support data transfer operations.

If newHandler is not null, and the system property suppressSwingDropSupport is not true, this will install a DropTarget on the JComponent. The default for the system property is false, so that a DropTarget will be added.

Please see How to Use Drag and Drop and Data Transfer, a section in The Java Tutorial, for more information.

Parameters:
newHandler - mechanism for transfer of data to and from the component
Since:
1.4
See Also:
TransferHandler, getTransferHandler()

getTransferHandler

public TransferHandler getTransferHandler()
Gets the transferHandler property.

Returns:
the value of the transferHandler property
Since:
1.4
See Also:
TransferHandler, setTransferHandler(javax.swing.TransferHandler)

processMouseEvent

protected void processMouseEvent(MouseEvent e)
Processes mouse events occurring on this component by dispatching them to any registered MouseListener objects, refer to Component.processMouseEvent(MouseEvent) for a complete description of this method.

Overrides:
processMouseEvent in class Component
Parameters:
e - the mouse event
Since:
1.5
See Also:
Component.processMouseEvent(java.awt.event.MouseEvent)

processMouseMotionEvent

protected void processMouseMotionEvent(MouseEvent e)
Processes mouse motion events, such as MouseEvent.MOUSE_DRAGGED.

Overrides:
processMouseMotionEvent in class Component
Parameters:
e - the MouseEvent
See Also:
MouseEvent

enable

@Deprecated
public void enable()
Deprecated. As of JDK version 1.1, replaced by java.awt.Component.setEnabled(boolean).

Overrides:
enable in class Component

disable

@Deprecated
public void disable()
Deprecated. As of JDK version 1.1, replaced by java.awt.Component.setEnabled(boolean).

Overrides:
disable in class Component

getAccessibleContext

public AccessibleContext getAccessibleContext()
Returns the AccessibleContext associated with this JComponent. The method implemented by this base class returns null. Classes that extend JComponent should implement this method to return the AccessibleContext associated with the subclass.

Overrides:
getAccessibleContext in class Component
Returns:
the AccessibleContext of this JComponent

getClientProperty

public final Object getClientProperty(Object key)
Returns the value of the property with the specified key. Only properties added with putClientProperty will return a non-null value.

Parameters:
key - the being queried
Returns:
the value of this property or null
See Also:
putClientProperty(java.lang.Object, java.lang.Object)

putClientProperty

public final void putClientProperty(Object key,
                                    Object value)
Adds an arbitrary key/value "client property" to this component.

The get/putClientProperty methods provide access to a small per-instance hashtable. Callers can use get/putClientProperty to annotate components that were created by another module. For example, a layout manager might store per child constraints this way. For example:

 componentA.putClientProperty("to the left of", componentB);
If value is null this method will remove the property. Changes to client properties are reported with PropertyChange events. The name of the property (for the sake of PropertyChange events) is key.toString().

The clientProperty dictionary is not intended to support large scale extensions to JComponent nor should be it considered an alternative to subclassing when designing a new component.

Parameters:
key - the new client property key
value - the new client property value; if null this method will remove the property
See Also:
getClientProperty(java.lang.Object), Container.addPropertyChangeListener(java.beans.PropertyChangeListener)

setFocusTraversalKeys

public void setFocusTraversalKeys(int id,
                                  Set<? extends AWTKeyStroke> keystrokes)
Sets the focus traversal keys for a given traversal operation for this Component. Refer to Component.setFocusTraversalKeys(int, java.util.Set) for a complete description of this method.

Overrides:
setFocusTraversalKeys in class Container
Parameters:
id - one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS, KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, or KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS
keystrokes - the Set of AWTKeyStroke for the specified operation
Throws:
IllegalArgumentException - if id is not one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS, KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, or KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or if keystrokes contains null, or if any Object in keystrokes is not an AWTKeyStroke, or if any keystroke represents a KEY_TYPED event, or if any keystroke already maps to another focus traversal operation for this Component
Since:
1.5
See Also:
KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS, KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS

isLightweightComponent

public static boolean isLightweightComponent(Component c)
Returns true if this component is lightweight, that is, if it doesn't have a native window system peer.

Returns:
true if this component is lightweight

reshape

@Deprecated
public void reshape(int x,
                               int y,
                               int w,
                               int h)
Deprecated. As of JDK 5, replaced by Component.setBounds(int, int, int, int).

Moves and resizes this component.

Overrides:
reshape in class Component
Parameters:
x - the new horizontal location
y - the new vertical location
w - the new width
h - the new height
See Also:
Component.setBounds(int, int, int, int)

getBounds

public Rectangle getBounds(Rectangle rv)
Stores the bounds of this component into "return value" rv and returns rv. If rv is null a new Rectangle is allocated. This version of getBounds is useful if the caller wants to avoid allocating a new Rectangle object on the heap.

Overrides:
getBounds in class Component
Parameters:
rv - the return value, modified to the component's bounds
Returns:
rv; if rv is null return a newly created Rectangle with this component's bounds

getSize

public Dimension getSize(Dimension rv)
Stores the width/height of this component into "return value" rv and returns rv. If rv is null a new Dimension object is allocated. This version of getSize is useful if the caller wants to avoid allocating a new Dimension object on the heap.

Overrides:
getSize in class Component
Parameters:
rv - the return value, modified to the component's size
Returns:
rv

getLocation

public Point getLocation(Point rv)
Stores the x,y origin of this component into "return value" rv and returns rv. If rv is null a new Point is allocated. This version of getLocation is useful if the caller wants to avoid allocating a new Point object on the heap.

Overrides:
getLocation in class Component
Parameters:
rv - the return value, modified to the component's location
Returns:
rv

getX

public int getX()
Returns the current x coordinate of the component's origin. This method is preferable to writing component.getBounds().x, or component.getLocation().x because it doesn't cause any heap allocations.

Overrides:
getX in class Component
Returns:
the current x coordinate of the component's origin

getY

public int getY()
Returns the current y coordinate of the component's origin. This method is preferable to writing component.getBounds().y, or component.getLocation().y because it doesn't cause any heap allocations.

Overrides:
getY in class Component
Returns:
the current y coordinate of the component's origin

getWidth

public int getWidth()
Returns the current width of this component. This method is preferable to writing component.getBounds().width, or component.getSize().width because it doesn't cause any heap allocations.

Overrides:
getWidth in class Component
Returns:
the current width of this component

getHeight

public int getHeight()
Returns the current height of this component. This method is preferable to writing component.getBounds().height, or component.getSize().height because it doesn't cause any heap allocations.

Overrides:
getHeight in class Component
Returns:
the current height of this component

isOpaque

public boolean isOpaque()
Returns true if this component is completely opaque.

An opaque component paints every pixel within its rectangular bounds. A non-opaque component paints only a subset of its pixels or none at all, allowing the pixels underneath it to "show through". Therefore, a component that does not fully paint its pixels provides a degree of transparency.

Subclasses that guarantee to always completely paint their contents should override this method and return true.

Overrides:
isOpaque in class Component
Returns:
true if this component is completely opaque
See Also:
setOpaque(boolean)

setOpaque

public void setOpaque(boolean isOpaque)
If true the component paints every pixel within its bounds. Otherwise, the component may not paint some or all of its pixels, allowing the underlying pixels to show through.

The default value of this property is false for JComponent. However, the default value for this property on most standard JComponent subclasses (such as JButton and JTree) is look-and-feel dependent.

Parameters:
isOpaque - true if this component should be opaque
See Also:
isOpaque()

computeVisibleRect

public void computeVisibleRect(Rectangle visibleRect)
Returns the Component's "visible rect rectangle" - the intersection of the visible rectangles for this component and all of its ancestors. The return value is stored in visibleRect.

Parameters:
visibleRect - a Rectangle computed as the intersection of all visible rectangles for this component and all of its ancestors -- this is the return value for this method
See Also:
getVisibleRect()

getVisibleRect

public Rectangle getVisibleRect()
Returns the Component's "visible rectangle" - the intersection of this component's visible rectangle, new Rectangle(0, 0, getWidth(), getHeight()), and all of its ancestors' visible rectangles.

Returns:
the visible rectangle

firePropertyChange

public void firePropertyChange(String propertyName,
                               boolean oldValue,
                               boolean newValue)
Support for reporting bound property changes for boolean properties. This method can be called when a bound property has changed and it will send the appropriate PropertyChangeEvent to any registered PropertyChangeListeners.

Overrides:
firePropertyChange in class Component
Parameters:
propertyName - the property whose value has changed
oldValue - the property's previous value
newValue - the property's new value

firePropertyChange

public void firePropertyChange(String propertyName,
                               int oldValue,
                               int newValue)
Support for reporting bound property changes for integer properties. This method can be called when a bound property has changed and it will send the appropriate PropertyChangeEvent to any registered PropertyChangeListeners.

Overrides:
firePropertyChange in class Component
Parameters:
propertyName - the property whose value has changed
oldValue - the property's previous value
newValue - the property's new value

firePropertyChange

public void firePropertyChange(String propertyName,
                               char oldValue,
                               char newValue)
Description copied from class: Component
Reports a bound property change.

Overrides:
firePropertyChange in class Component
Parameters:
propertyName - the programmatic name of the property that was changed
oldValue - the old value of the property (as a char)
newValue - the new value of the property (as a char)
See Also:
Component.firePropertyChange(java.lang.String, java.lang.Object, java.lang.Object)

fireVetoableChange

protected void fireVetoableChange(String propertyName,
                                  Object oldValue,
                                  Object newValue)
                           throws PropertyVetoException
Supports reporting constrained property changes. This method can be called when a constrained property has changed and it will send the appropriate PropertyChangeEvent to any registered VetoableChangeListeners.

Parameters:
propertyName - the name of the property that was listened on
oldValue - the old value of the property
newValue - the new value of the property
Throws:
PropertyVetoException - when the attempt to set the property is vetoed by the component

addVetoableChangeListener

public void addVetoableChangeListener(VetoableChangeListener listener)
Adds a VetoableChangeListener to the listener list. The listener is registered for all properties.

Parameters:
listener - the VetoableChangeListener to be added

removeVetoableChangeListener

public void removeVetoableChangeListener(VetoableChangeListener listener)
Removes a VetoableChangeListener from the listener list. This removes a VetoableChangeListener that was registered for all properties.

Parameters:
listener - the VetoableChangeListener to be removed

getVetoableChangeListeners

public VetoableChangeListener[] getVetoableChangeListeners()
Returns an array of all the vetoable change listeners registered on this component.

Returns:
all of the component's VetoableChangeListeners or an empty array if no vetoable change listeners are currently registered
Since:
1.4
See Also:
addVetoableChangeListener(java.beans.VetoableChangeListener), removeVetoableChangeListener(java.beans.VetoableChangeListener)

getTopLevelAncestor

public Container getTopLevelAncestor()
Returns the top-level ancestor of this component (either the containing Window or Applet), or null if this component has not been added to any container.

Returns:
the top-level Container that this component is in, or null if not in any container

addAncestorListener

public void addAncestorListener(AncestorListener listener)
Registers listener so that it will receive AncestorEvents when it or any of its ancestors move or are made visible or invisible. Events are also sent when the component or its ancestors are added or removed from the containment hierarchy.

Parameters:
listener - the AncestorListener to register
See Also:
AncestorEvent

removeAncestorListener

public void removeAncestorListener(AncestorListener listener)
Unregisters listener so that it will no longer receive AncestorEvents.

Parameters:
listener - the AncestorListener to be removed
See Also:
addAncestorListener(javax.swing.event.AncestorListener)

getAncestorListeners

public AncestorListener[] getAncestorListeners()
Returns an array of all the ancestor listeners registered on this component.

Returns:
all of the component's AncestorListeners or an empty array if no ancestor listeners are currently registered
Since:
1.4
See Also:
addAncestorListener(javax.swing.event.AncestorListener), removeAncestorListener(javax.swing.event.AncestorListener)

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this JComponent. FooListeners are registered using the addFooListener method.

You can specify the listenerType argument with a class literal, such as FooListener.class. For example, you can query a JComponent c for its mouse listeners with the following code:

MouseListener[] mls = (MouseListener[])(c.getListeners(MouseListener.class));
If no such listeners exist, this method returns an empty array.

Overrides:
getListeners in class Container
Parameters:
listenerType - the type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener
Returns:
an array of all objects registered as FooListeners on this component, or an empty array if no such listeners have been added
Throws:
ClassCastException - if listenerType doesn't specify a class or interface that implements java.util.EventListener
Since:
1.3
See Also:
getVetoableChangeListeners(), getAncestorListeners()

addNotify

public void addNotify()
Notifies this component that it now has a parent component. When this method is invoked, the chain of parent components is set up with KeyboardAction event listeners.

Overrides:
addNotify in class Container
See Also:
registerKeyboardAction(java.awt.event.ActionListener, java.lang.String, javax.swing.KeyStroke, int)

removeNotify

public void removeNotify()
Notifies this component that it no longer has a parent component. When this method is invoked, any KeyboardActions set up in the the chain of parent components are removed.

Overrides:
removeNotify in class Container
See Also:
registerKeyboardAction(java.awt.event.ActionListener, java.lang.String, javax.swing.KeyStroke, int)

repaint

public void repaint(long tm,
                    int x,
                    int y,
                    int width,
                    int height)
Adds the specified region to the dirty region list if the component is showing. The component will be repainted after all of the currently pending events have been dispatched.

Overrides:
repaint in class Component
Parameters:
tm - this parameter is not used
x - the x value of the dirty region
y - the y value of the dirty region
width - the width of the dirty region
height - the height of the dirty region
See Also:
Component.isShowing(), RepaintManager.addDirtyRegion(javax.swing.JComponent, int, int, int, int)

repaint

public void repaint(Rectangle r)
Adds the specified region to the dirty region list if the component is showing. The component will be repainted after all of the currently pending events have been dispatched.

Parameters:
r - a Rectangle containing the dirty region
See Also:
Component.isShowing(), RepaintManager.addDirtyRegion(javax.swing.JComponent, int, int, int, int)

revalidate

public void revalidate()
Supports deferred automatic layout.

Calls invalidate and then adds this component's validateRoot to a list of components that need to be validated. Validation will occur after all currently pending events have been dispatched. In other words after this method is called, the first validateRoot (if any) found when walking up the containment hierarchy of this component will be validated. By default, JRootPane, JScrollPane, and JTextField return true from isValidateRoot.

This method will automatically be called on this component when a property value changes such that size, location, or internal layout of this component has been affected. This automatic updating differs from the AWT because programs generally no longer need to invoke validate to get the contents of the GUI to update.

See Also:
Component.invalidate(),
Container.validate(),
isValidateRoot(),
RepaintManager.addInvalidComponent(javax.swing.JComponent)

isValidateRoot

public boolean isValidateRoot()
If this method returns true, revalidate calls by descendants of this component will cause the entire tree beginning with this root to be validated. Returns false by default. JScrollPane overrides this method and returns true.

Returns:
always returns false
See Also:
revalidate(),
Component.invalidate(),
Container.validate()

isOptimizedDrawingEnabled

public boolean isOptimizedDrawingEnabled()
Returns true if this component tiles its children -- that is, if it can guarantee that the children will not overlap. The repainting system is substantially more efficient in this common case. JComponent subclasses that can't make this guarantee, such as JLayeredPane, should override this method to return false.

Returns:
always returns true

paintImmediately

public void paintImmediately(int x,
                             int y,
                             int w,
                             int h)
Paints the specified region in this component and all of its descendants that overlap the region, immediately.

It's rarely necessary to call this method. In most cases it's more efficient to call repaint, which defers the actual painting and can collapse redundant requests into a single paint call. This method is useful if one needs to update the display while the current event is being dispatched.

Parameters:
x - the x value of the region to be painted
y - the y value of the region to be painted
w - the width of the region to be painted
h - the height of the region to be painted
See Also:
repaint(long, int, int, int, int)

paintImmediately

public void paintImmediately(Rectangle r)
Paints the specified region now.

Parameters:
r - a Rectangle containing the region to be painted

setDoubleBuffered

public void setDoubleBuffered(boolean aFlag)
Sets whether this component should use a buffer to paint. If set to true, all the drawing from this component will be done in an offscreen painting buffer. The offscreen painting buffer will the be copied onto the screen. If a Component is buffered and one of its ancestor is also buffered, the ancestor buffer will be used.

Parameters:
aFlag - if true, set this component to be double buffered

isDoubleBuffered

public boolean isDoubleBuffered()
Returns whether this component should use a buffer to paint.

Overrides:
isDoubleBuffered in class Component
Returns:
true if this component is double buffered, otherwise false

getRootPane

public JRootPane getRootPane()
Returns the JRootPane ancestor for this component.

Returns:
the JRootPane that contains this component, or null if no JRootPane is found

paramString

protected String paramString()
Returns a string representation of this JComponent. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class Container
Returns:
a string representation of this JComponent
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JComponent.AccessibleJComponent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JComponent.AccessibleJComponent

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent
Direct Known Subclasses:
AbstractButton.AccessibleAbstractButton, JColorChooser.AccessibleJColorChooser, JComboBox.AccessibleJComboBox, JDesktopPane.AccessibleJDesktopPane, JFileChooser.AccessibleJFileChooser, JInternalFrame.AccessibleJInternalFrame, JInternalFrame.JDesktopIcon.AccessibleJDesktopIcon, JLabel.AccessibleJLabel, JLayeredPane.AccessibleJLayeredPane, JList.AccessibleJList, JMenuBar.AccessibleJMenuBar, JOptionPane.AccessibleJOptionPane, JPanel.AccessibleJPanel, JPopupMenu.AccessibleJPopupMenu, JProgressBar.AccessibleJProgressBar, JRootPane.AccessibleJRootPane, JScrollBar.AccessibleJScrollBar, JScrollPane.AccessibleJScrollPane, JSeparator.AccessibleJSeparator, JSlider.AccessibleJSlider, JSpinner.AccessibleJSpinner, JSplitPane.AccessibleJSplitPane, JTabbedPane.AccessibleJTabbedPane, JTable.AccessibleJTable, JTableHeader.AccessibleJTableHeader, JTextComponent.AccessibleJTextComponent, JToolBar.AccessibleJToolBar, JToolTip.AccessibleJToolTip, JTree.AccessibleJTree, JViewport.AccessibleJViewport
Enclosing class:
JComponent
public abstract class JComponent.AccessibleJComponent
extends Container.AccessibleAWTContainer
implements AccessibleExtendedComponent

Inner class of JComponent used to provide default support for accessibility. This class is not meant to be used directly by application developers, but is instead meant only to be subclassed by component developers.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected class | JComponent.AccessibleJComponent.AccessibleContainerHandler Fire PropertyChange listener, if one is registered, when children added/removed.
protected class | JComponent.AccessibleJComponent.AccessibleFocusHandler Fire PropertyChange listener, if one is registered, when focus events happen
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
protected ContainerListener | accessibleContainerHandler
protected FocusListener | accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JComponent.AccessibleJComponent()
Though the class is abstract, this should be called by all sub-classes.
Method Summary
void | addPropertyChangeListener(PropertyChangeListener listener) Adds a PropertyChangeListener to the listener list.
Accessible | getAccessibleChild(int i) Returns the nth Accessible child of the object.
int | getAccessibleChildrenCount() Returns the number of accessible children in the object.
String | getAccessibleDescription() Gets the accessible description of this object.
AccessibleKeyBinding | getAccessibleKeyBinding() Returns key bindings associated with this object
String | getAccessibleName() Gets the accessible name of this object.
AccessibleRole | getAccessibleRole() Gets the role of this object.
AccessibleStateSet | getAccessibleStateSet() Gets the state of this object.
protected String | getBorderTitle(Border b) Recursively search through the border hierarchy (if it exists) for a TitledBorder with a non-null title.
String | getTitledBorderText() Returns the titled border text
String | getToolTipText() Returns the tool tip text
void | removePropertyChangeListener(PropertyChangeListener listener) Removes a PropertyChangeListener from the listener list.
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Field Detail

accessibleContainerHandler

protected ContainerListener accessibleContainerHandler

accessibleFocusHandler

protected FocusListener accessibleFocusHandler
Constructor Detail

JComponent.AccessibleJComponent

protected JComponent.AccessibleJComponent()
Though the class is abstract, this should be called by all sub-classes.

Method Detail

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list.

Overrides:
addPropertyChangeListener in class Container.AccessibleAWTContainer
Parameters:
listener - the PropertyChangeListener to be added
See Also:
AccessibleContext.ACCESSIBLE_NAME_PROPERTY, AccessibleContext.ACCESSIBLE_DESCRIPTION_PROPERTY, AccessibleContext.ACCESSIBLE_STATE_PROPERTY, AccessibleContext.ACCESSIBLE_VALUE_PROPERTY, AccessibleContext.ACCESSIBLE_SELECTION_PROPERTY, AccessibleContext.ACCESSIBLE_TEXT_PROPERTY, AccessibleContext.ACCESSIBLE_VISIBLE_DATA_PROPERTY

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties.

Overrides:
removePropertyChangeListener in class Component.AccessibleAWTComponent
Parameters:
listener - the PropertyChangeListener to be removed

getBorderTitle

protected String getBorderTitle(Border b)
Recursively search through the border hierarchy (if it exists) for a TitledBorder with a non-null title. This does a depth first search on first the inside borders then the outside borders. The assumption is that titles make really pretty inside borders but not very pretty outside borders in compound border situations. It's rather arbitrary, but hopefully decent UI programmers will not create multiple titled borders for the same component.

getAccessibleName

public String getAccessibleName()
Gets the accessible name of this object. This should almost never return java.awt.Component.getName(), as that generally isn't a localized name, and doesn't have meaning for the user. If the object is fundamentally a text object (such as a menu item), the accessible name should be the text of the object (for example, "save"). If the object has a tooltip, the tooltip text may also be an appropriate String to return.

Overrides:
getAccessibleName in class Component.AccessibleAWTComponent
Returns:
the localized name of the object -- can be null if this object does not have a name
See Also:
AccessibleContext.setAccessibleName(java.lang.String)

getAccessibleDescription

public String getAccessibleDescription()
Gets the accessible description of this object. This should be a concise, localized description of what this object is - what is its meaning to the user. If the object has a tooltip, the tooltip text may be an appropriate string to return, assuming it contains a concise description of the object (instead of just the name of the object - for example a "Save" icon on a toolbar that had "save" as the tooltip text shouldn't return the tooltip text as the description, but something like "Saves the current text document" instead).

Overrides:
getAccessibleDescription in class Component.AccessibleAWTComponent
Returns:
the localized description of the object -- can be null if this object does not have a description
See Also:
AccessibleContext.setAccessibleDescription(java.lang.String)

getAccessibleRole

public AccessibleRole getAccessibleRole()
Gets the role of this object.

Overrides:
getAccessibleRole in class Component.AccessibleAWTComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Gets the state of this object.

Overrides:
getAccessibleStateSet in class Component.AccessibleAWTComponent
Returns:
an instance of AccessibleStateSet containing the current state set of the object
See Also:
AccessibleState

getAccessibleChildrenCount

public int getAccessibleChildrenCount()
Returns the number of accessible children in the object. If all of the children of this object implement Accessible, than this method should return the number of children of this object.

Overrides:
getAccessibleChildrenCount in class Container.AccessibleAWTContainer
Returns:
the number of accessible children in the object.

getAccessibleChild

public Accessible getAccessibleChild(int i)
Returns the nth Accessible child of the object.

Overrides:
getAccessibleChild in class Container.AccessibleAWTContainer
Parameters:
i - zero-based index of child
Returns:
the nth Accessible child of the object
See Also:
AccessibleContext.getAccessibleChildrenCount()

getToolTipText

public String getToolTipText()
Returns the tool tip text

Specified by:
getToolTipText in interface AccessibleExtendedComponent
Returns:
the tool tip text, if supported, of the object; otherwise, null
Since:
1.4

getTitledBorderText

public String getTitledBorderText()
Returns the titled border text

Specified by:
getTitledBorderText in interface AccessibleExtendedComponent
Returns:
the titled border text, if supported, of the object; otherwise, null
Since:
1.4

getAccessibleKeyBinding

public AccessibleKeyBinding getAccessibleKeyBinding()
Returns key bindings associated with this object

Specified by:
getAccessibleKeyBinding in interface AccessibleExtendedComponent
Returns:
the key bindings, if supported, of the object; otherwise, null
Since:
1.4
See Also:
AccessibleKeyBinding
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JComponent.AccessibleJComponent.AccessibleContainerHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JComponent.AccessibleJComponent.AccessibleContainerHandler

java.lang.Object
    extended by  javax.swing.JComponent.AccessibleJComponent.AccessibleContainerHandler
All Implemented Interfaces:
ContainerListener, EventListener
Enclosing class:
JComponent.AccessibleJComponent
protected class JComponent.AccessibleJComponent.AccessibleContainerHandler
extends Object
implements ContainerListener

Fire PropertyChange listener, if one is registered, when children added/removed.

Constructor Summary
protected JComponent.AccessibleJComponent.AccessibleContainerHandler()
Method Summary
void | componentAdded(ContainerEvent e) Invoked when a component has been added to the container.
void | componentRemoved(ContainerEvent e) Invoked when a component has been removed from the container.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JComponent.AccessibleJComponent.AccessibleContainerHandler

protected JComponent.AccessibleJComponent.AccessibleContainerHandler()
Method Detail

componentAdded

public void componentAdded(ContainerEvent e)
Description copied from interface: ContainerListener
Invoked when a component has been added to the container.

Specified by:
componentAdded in interface ContainerListener

componentRemoved

public void componentRemoved(ContainerEvent e)
Description copied from interface: ContainerListener
Invoked when a component has been removed from the container.

Specified by:
componentRemoved in interface ContainerListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JComponent.AccessibleJComponent.AccessibleFocusHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JComponent.AccessibleJComponent.AccessibleFocusHandler

java.lang.Object
    extended by  javax.swing.JComponent.AccessibleJComponent.AccessibleFocusHandler
All Implemented Interfaces:
FocusListener, EventListener
Enclosing class:
JComponent.AccessibleJComponent
protected class JComponent.AccessibleJComponent.AccessibleFocusHandler
extends Object
implements FocusListener

Fire PropertyChange listener, if one is registered, when focus events happen

Since:
1.3

Constructor Summary
protected JComponent.AccessibleJComponent.AccessibleFocusHandler()
Method Summary
void | focusGained(FocusEvent event) Invoked when a component gains the keyboard focus.
void | focusLost(FocusEvent event) Invoked when a component loses the keyboard focus.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JComponent.AccessibleJComponent.AccessibleFocusHandler

protected JComponent.AccessibleJComponent.AccessibleFocusHandler()
Method Detail

focusGained

public void focusGained(FocusEvent event)
Description copied from interface: FocusListener
Invoked when a component gains the keyboard focus.

Specified by:
focusGained in interface FocusListener

focusLost

public void focusLost(FocusEvent event)
Description copied from interface: FocusListener
Invoked when a component loses the keyboard focus.

Specified by:
focusLost in interface FocusListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JDesktopPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JDesktopPane

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JLayeredPane
                    extended by  javax.swing.JDesktopPane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public class JDesktopPane
extends JLayeredPane
implements Accessible

A container used to create a multiple-document interface or a virtual desktop. You create JInternalFrame objects and add them to the JDesktopPane. JDesktopPane extends JLayeredPane to manage the potentially overlapping internal frames. It also maintains a reference to an instance of DesktopManager that is set by the UI class for the current look and feel (L&F). Note that JDesktopPane does not support borders.

This class is normally used as the parent of JInternalFrames to provide a pluggable DesktopManager object to the JInternalFrames. The installUI of the L&F specific implementation is responsible for setting the desktopManager variable appropriately. When the parent of a JInternalFrame is a JDesktopPane, it should delegate most of its behavior to the desktopManager (closing, resizing, etc).

For further documentation and examples see How to Use Internal Frames, a section in The Java Tutorial.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JInternalFrame, JInternalFrame.JDesktopIcon, DesktopManager

Nested Class Summary
protected  class JDesktopPane.AccessibleJDesktopPane
This class implements accessibility support for the JDesktopPane class.
Nested classes/interfaces inherited from class javax.swing.JLayeredPane
JLayeredPane.AccessibleJLayeredPane
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
static int | LIVE_DRAG_MODE Indicates that the entire contents of the item being dragged should appear inside the desktop pane.
static int | OUTLINE_DRAG_MODE Indicates that an outline only of the item being dragged should appear inside the desktop pane.
Fields inherited from class javax.swing.JLayeredPane
DEFAULT_LAYER, DRAG_LAYER, FRAME_CONTENT_LAYER, LAYER_PROPERTY, MODAL_LAYER, PALETTE_LAYER, POPUP_LAYER
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JDesktopPane()
Creates a new JDesktopPane.
Method Summary
protected void | addImpl(Component comp, Object constraints, int index) Adds the specified component to this container at the specified index.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JDesktopPane.
JInternalFrame[] | getAllFrames() Returns all JInternalFrames currently displayed in the desktop.
JInternalFrame[] | getAllFramesInLayer(int layer) Returns all JInternalFrames currently displayed in the specified layer of the desktop.
DesktopManager | getDesktopManager() Returns the DesktopManger that handles desktop-specific UI actions.
int | getDragMode() Gets the current "dragging style" used by the desktop pane.
JInternalFrame | getSelectedFrame() Returns the currently active JInternalFrame in this JDesktopPane, or null if no JInternalFrame is currently active.
DesktopPaneUI | getUI() Returns the L&F object that renders this component.
String | getUIClassID() Returns the name of the L&F class that renders this component.
protected String | paramString() Returns a string representation of this JDesktopPane.
void | remove(int index) Remove the indexed component from this pane.
void | removeAll() Removes all the components from this container.
JInternalFrame | selectFrame(boolean forward) Selects the next JInternalFrame in this desktop pane.
void | setComponentZOrder(Component comp, int index) Moves the specified component to the specified z-order index in the container.
void | setDesktopManager(DesktopManager d) Sets the DesktopManger that will handle desktop-specific UI actions.
void | setDragMode(int dragMode) Sets the "dragging style" used by the desktop pane.
void | setSelectedFrame(JInternalFrame f) Sets the currently active JInternalFrame in this JDesktopPane.
void | setUI(DesktopPaneUI ui) Sets the L&F object that renders this component.
void | updateUI() Notification from the UIManager that the L&F has changed.
Methods inherited from class javax.swing.JLayeredPane
getComponentCountInLayer, getComponentsInLayer, getComponentToLayer, getIndexOf, getLayer, getLayer, getLayeredPaneAbove, getObjectForLayer, getPosition, highestLayer, insertIndexForLayer, isOptimizedDrawingEnabled, lowestLayer, moveToBack, moveToFront, paint, putLayer, setLayer, setLayer, setPosition
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, removeContainerListener, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

LIVE_DRAG_MODE

public static final int LIVE_DRAG_MODE
Indicates that the entire contents of the item being dragged should appear inside the desktop pane.

See Also:
OUTLINE_DRAG_MODE, setDragMode(int), Constant Field Values

OUTLINE_DRAG_MODE

public static final int OUTLINE_DRAG_MODE
Indicates that an outline only of the item being dragged should appear inside the desktop pane.

See Also:
LIVE_DRAG_MODE, setDragMode(int), Constant Field Values
Constructor Detail

JDesktopPane

public JDesktopPane()
Creates a new JDesktopPane.

Method Detail

getUI

public DesktopPaneUI getUI()
Returns the L&F object that renders this component.

Returns:
the DesktopPaneUI object that renders this component

setUI

public void setUI(DesktopPaneUI ui)
Sets the L&F object that renders this component.

Parameters:
ui - the DesktopPaneUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

setDragMode

public void setDragMode(int dragMode)
Sets the "dragging style" used by the desktop pane. You may want to change to one mode or another for performance or aesthetic reasons.

Parameters:
dragMode - the style of drag to use for items in the Desktop
Since:
1.3
See Also:
LIVE_DRAG_MODE, OUTLINE_DRAG_MODE

getDragMode

public int getDragMode()
Gets the current "dragging style" used by the desktop pane.

Returns:
either Live_DRAG_MODE or OUTLINE_DRAG_MODE
Since:
1.3
See Also:
setDragMode(int)

getDesktopManager

public DesktopManager getDesktopManager()
Returns the DesktopManger that handles desktop-specific UI actions.

setDesktopManager

public void setDesktopManager(DesktopManager d)
Sets the DesktopManger that will handle desktop-specific UI actions.

Parameters:
d - the DesktopManager to use

updateUI

public void updateUI()
Notification from the UIManager that the L&F has changed. Replaces the current UI object with the latest version from the UIManager.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "DesktopPaneUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

getAllFrames

public JInternalFrame[] getAllFrames()
Returns all JInternalFrames currently displayed in the desktop. Returns iconified frames as well as expanded frames.

Returns:
an array of JInternalFrame objects

getSelectedFrame

public JInternalFrame getSelectedFrame()
Returns the currently active JInternalFrame in this JDesktopPane, or null if no JInternalFrame is currently active.

Returns:
the currently active JInternalFrame or null
Since:
1.3

setSelectedFrame

public void setSelectedFrame(JInternalFrame f)
Sets the currently active JInternalFrame in this JDesktopPane. This method is used to bridge the package gap between JDesktopPane and the platform implementation code and should not be called directly. To visually select the frame the client must call JInternalFrame.setSelected(true) to activate the frame.

Parameters:
f - the internal frame that's currently selected
Since:
1.3
See Also:
JInternalFrame.setSelected(boolean)

getAllFramesInLayer

public JInternalFrame[] getAllFramesInLayer(int layer)
Returns all JInternalFrames currently displayed in the specified layer of the desktop. Returns iconified frames as well expanded frames.

Parameters:
layer - an int specifying the desktop layer
Returns:
an array of JInternalFrame objects
See Also:
JLayeredPane

selectFrame

public JInternalFrame selectFrame(boolean forward)
Selects the next JInternalFrame in this desktop pane.

Parameters:
forward - a boolean indicating which direction to select in; true for forward, false for backward
Returns:
the JInternalFrame that was selected or null if nothing was selected
Since:
1.6

addImpl

protected void addImpl(Component comp,
                       Object constraints,
                       int index)
Adds the specified component to this container at the specified index. This method also notifies the layout manager to add the component to this container's layout using the specified constraints object via the addLayoutComponent method.

The constraints are defined by the particular layout manager being used. For example, the BorderLayout class defines five constraints: BorderLayout.NORTH, BorderLayout.SOUTH, BorderLayout.EAST, BorderLayout.WEST, and BorderLayout.CENTER.

The GridBagLayout class requires a GridBagConstraints object. Failure to pass the correct type of constraints object results in an IllegalArgumentException.

If the current layout manager implements LayoutManager2, then LayoutManager2.addLayoutComponent(Component,Object) is invoked on it. If the current layout manager does not implement LayoutManager2, and constraints is a String, then LayoutManager.addLayoutComponent(String,Component) is invoked on it.

If the component is not an ancestor of this container and has a non-null parent, it is removed from its current parent before it is added to this container.

This is the method to override if a program needs to track every add request to a container as all other add methods defer to this one. An overriding method should usually include a call to the superclass's version of the method:

super.addImpl(comp, constraints, index)

Overrides:
addImpl in class JLayeredPane
Parameters:
comp - the component to be added
constraints - an object expressing layout constraints for this component
index - the position in the container's list at which to insert the component, where -1 means append to the end
Since:
1.6
See Also:
Container.add(Component),
Container.add(Component, int),
Container.add(Component, java.lang.Object),
LayoutManager,
LayoutManager2

remove

public void remove(int index)
Remove the indexed component from this pane. This is the absolute index, ignoring layers.

Overrides:
remove in class JLayeredPane
Parameters:
index - an int specifying the component to remove
Since:
1.6
See Also:
JLayeredPane.getIndexOf(java.awt.Component)

removeAll

public void removeAll()
Removes all the components from this container.

Overrides:
removeAll in class JLayeredPane
Since:
1.6
See Also:
Container.add(java.awt.Component), Container.remove(int)

setComponentZOrder

public void setComponentZOrder(Component comp,
                               int index)
Moves the specified component to the specified z-order index in the container. The z-order determines the order that components are painted; the component with the highest z-order paints first and the component with the lowest z-order paints last. Where components overlap, the component with the lower z-order paints over the component with the higher z-order.

If the component is a child of some other container, it is removed from that container before being added to this container. The important difference between this method and java.awt.Container.add(Component, int) is that this method doesn't call removeNotify on the component while removing it from its previous container unless necessary and when allowed by the underlying native windowing system. This way, if the component has the keyboard focus, it maintains the focus when moved to the new position.

This property is guaranteed to apply only to lightweight non-Container components.

Note: Not all platforms support changing the z-order of heavyweight components from one container into another without the call to removeNotify. There is no way to detect whether a platform supports this, so developers shouldn't make any assumptions.

Overrides:
setComponentZOrder in class Container
Parameters:
comp - the component to be moved
index - the position in the container's list to insert the component, where getComponentCount() appends to the end
Since:
1.6
See Also:
Container.getComponentZOrder(java.awt.Component)

paramString

protected String paramString()
Returns a string representation of this JDesktopPane. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JLayeredPane
Returns:
a string representation of this JDesktopPane

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JDesktopPane. For desktop panes, the AccessibleContext takes the form of an AccessibleJDesktopPane. A new AccessibleJDesktopPane instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JLayeredPane
Returns:
an AccessibleJDesktopPane that serves as the AccessibleContext of this JDesktopPane
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JDesktopPane.AccessibleJDesktopPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JDesktopPane.AccessibleJDesktopPane

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JDesktopPane.AccessibleJDesktopPane
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent
Enclosing class:
JDesktopPane
protected class JDesktopPane.AccessibleJDesktopPane
extends JComponent.AccessibleJComponent

This class implements accessibility support for the JDesktopPane class. It provides an implementation of the Java Accessibility API appropriate to desktop pane user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JDesktopPane.AccessibleJDesktopPane()
Method Summary
 AccessibleRole getAccessibleRole()
Get the role of this object.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JDesktopPane.AccessibleJDesktopPane

protected JDesktopPane.AccessibleJDesktopPane()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JDialog

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JDialog

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  java.awt.Window
                extended by  java.awt.Dialog
                    extended by  javax.swing.JDialog
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, RootPaneContainer, WindowConstants
public class JDialog
extends Dialog
implements WindowConstants, Accessible, RootPaneContainer

The main class for creating a dialog window. You can use this class to create a custom dialog, or invoke the many class methods in JOptionPane to create a variety of standard dialogs. For information about creating dialogs, see The Java Tutorial section How to Make Dialogs.

The JDialog component contains a JRootPane as its only child. The contentPane should be the parent of any children of the JDialog. As a convenience add and its variants, remove and setLayout have been overridden to forward to the contentPane as necessary. This means you can write:

       dialog.add(child);
And the child will be added to the contentPane. The contentPane is always non-null. Attempting to set it to null generates an exception. The default contentPane has a BorderLayout manager set on it. Refer to RootPaneContainer for details on adding, removing and setting the LayoutManager of a JDialog.

Please see the JRootPane documentation for a complete description of the contentPane, glassPane, and layeredPane components.

In a multi-screen environment, you can create a JDialog on a different screen device than its owner. See Frame for more information.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JOptionPane, JRootPane, RootPaneContainer

Nested Class Summary
protected  class JDialog.AccessibleJDialog
This class implements accessibility support for the JDialog class.
Nested classes/interfaces inherited from class java.awt.Dialog
Dialog.AccessibleAWTDialog, Dialog.ModalExclusionType, Dialog.ModalityType
Nested classes/interfaces inherited from class java.awt.Window
Window.AccessibleAWTWindow
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected AccessibleContext | accessibleContext
protected JRootPane | rootPane
protected boolean | rootPaneCheckingEnabled If true then calls to add and setLayout will be forwarded to the contentPane.
Fields inherited from class java.awt.Dialog
DEFAULT_MODALITY_TYPE
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.WindowConstants
DISPOSE_ON_CLOSE, DO_NOTHING_ON_CLOSE, EXIT_ON_CLOSE, HIDE_ON_CLOSE
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JDialog()
Creates a modeless dialog without a title and without a specified Frame owner.
JDialog(Dialog owner)
Creates a modeless dialog without a title with the specified Dialog as its owner.
JDialog(Dialog owner, boolean modal)
Creates a dialog with the specified owner Dialog and modality.
JDialog(Dialog owner, String title)
Creates a modeless dialog with the specified title and with the specified owner dialog.
JDialog(Dialog owner, String title, boolean modal)
Creates a dialog with the specified title, modality and the specified owner Dialog.
JDialog(Dialog owner, String title, boolean modal, GraphicsConfiguration gc)
Creates a dialog with the specified title, owner Dialog, modality and GraphicsConfiguration.
JDialog(Frame owner)
Creates a modeless dialog without a title with the specified Frame as its owner.
JDialog(Frame owner, boolean modal)
Creates a dialog with the specified owner Frame, modality and an empty title.
JDialog(Frame owner, String title)
Creates a modeless dialog with the specified title and with the specified owner frame.
JDialog(Frame owner, String title, boolean modal)
Creates a dialog with the specified title, owner Frame and modality.
JDialog(Frame owner, String title, boolean modal, GraphicsConfiguration gc)
Creates a dialog with the specified title, owner Frame, modality and GraphicsConfiguration.
JDialog(Window owner)
Creates a modeless dialog with the specified owner Window and an empty title.
JDialog(Window owner, Dialog.ModalityType modalityType)
Creates a dialog with the specified owner Window, modality and an empty title.
JDialog(Window owner, String title)
Creates a modeless dialog with the specified title and owner Window.
JDialog(Window owner, String title, Dialog.ModalityType modalityType)
Creates a dialog with the specified title, owner Window and modality.
JDialog(Window owner, String title, Dialog.ModalityType modalityType, GraphicsConfiguration gc)
Creates a dialog with the specified title, owner Window, modality and GraphicsConfiguration.
Method Summary
protected void | addImpl(Component comp, Object constraints, int index) Adds the specified child Component.
protected JRootPane | createRootPane() Called by the constructor methods to create the default rootPane.
protected void | dialogInit() Called by the constructors to init the JDialog properly.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JDialog.
Container | getContentPane() Returns the contentPane object for this dialog.
int | getDefaultCloseOperation() Returns the operation which occurs when the user initiates a "close" on this dialog.
Component | getGlassPane() Returns the glassPane object for this dialog.
Graphics | getGraphics() Creates a graphics context for this component.
JMenuBar | getJMenuBar() Returns the menubar set on this dialog.
JLayeredPane | getLayeredPane() Returns the layeredPane object for this dialog.
JRootPane | getRootPane() Returns the rootPane object for this dialog.
TransferHandler | getTransferHandler() Gets the transferHandler property.
static boolean | isDefaultLookAndFeelDecorated() Returns true if newly created JDialogs should have their Window decorations provided by the current look and feel.
protected boolean | isRootPaneCheckingEnabled() Returns whether calls to add and setLayout are forwarded to the contentPane.
protected String | paramString() Returns a string representation of this JDialog.
protected void | processWindowEvent(WindowEvent e) Handles window events depending on the state of the defaultCloseOperation property.
void | remove(Component comp) Removes the specified component from the container.
void | repaint(long time, int x, int y, int width, int height) Repaints the specified rectangle of this component within time milliseconds.
void | setContentPane(Container contentPane) Sets the contentPane property.
void | setDefaultCloseOperation(int operation) Sets the operation that will happen by default when the user initiates a "close" on this dialog.
static void | setDefaultLookAndFeelDecorated(boolean defaultLookAndFeelDecorated) Provides a hint as to whether or not newly created JDialogs should have their Window decorations (such as borders, widgets to close the window, title...) provided by the current look and feel.
void | setGlassPane(Component glassPane) Sets the glassPane property.
void | setJMenuBar(JMenuBar menu) Sets the menubar for this dialog.
void | setLayeredPane(JLayeredPane layeredPane) Sets the layeredPane property.
void | setLayout(LayoutManager manager) Sets the LayoutManager.
protected void | setRootPane(JRootPane root) Sets the rootPane property.
protected void | setRootPaneCheckingEnabled(boolean enabled) Sets whether calls to add and setLayout are forwarded to the contentPane.
void | setTransferHandler(TransferHandler newHandler) Sets the transferHandler property, which is a mechanism to support transfer of data into this component.
void | update(Graphics g) Calls paint(g).
Methods inherited from class java.awt.Dialog
addNotify, getModalityType, getTitle, hide, isModal, isResizable, isUndecorated, setModal, setModalityType, setResizable, setTitle, setUndecorated, setVisible, show, toBack
Methods inherited from class java.awt.Window
addPropertyChangeListener, addPropertyChangeListener, addWindowFocusListener, addWindowListener, addWindowStateListener, applyResourceBundle, applyResourceBundle, createBufferStrategy, createBufferStrategy, dispose, getBufferStrategy, getFocusableWindowState, getFocusCycleRootAncestor, getFocusOwner, getFocusTraversalKeys, getGraphicsConfiguration, getIconImages, getInputContext, getListeners, getLocale, getModalExclusionType, getMostRecentFocusOwner, getOwnedWindows, getOwner, getOwnerlessWindows, getToolkit, getWarningString, getWindowFocusListeners, getWindowListeners, getWindows, getWindowStateListeners, isActive, isAlwaysOnTop, isAlwaysOnTopSupported, isFocusableWindow, isFocusCycleRoot, isFocused, isLocationByPlatform, isShowing, pack, postEvent, processEvent, processWindowFocusEvent, processWindowStateEvent, removeNotify, removeWindowFocusListener, removeWindowListener, removeWindowStateListener, reshape, setAlwaysOnTop, setBounds, setBounds, setCursor, setFocusableWindowState, setFocusCycleRoot, setIconImage, setIconImages, setLocationByPlatform, setLocationRelativeTo, setMinimumSize, setModalExclusionType, setSize, setSize, toFront
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalPolicy, getInsets, getLayout, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paint, paintComponents, preferredSize, print, printComponents, processContainerEvent, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resize, resize, setBackground, setComponentOrientation, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setName, setPreferredSize, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

rootPane

protected JRootPane rootPane
See Also:
getRootPane(), setRootPane(javax.swing.JRootPane)

rootPaneCheckingEnabled

protected boolean rootPaneCheckingEnabled
If true then calls to add and setLayout will be forwarded to the contentPane. This is initially false, but is set to true when the JDialog is constructed.

See Also:
isRootPaneCheckingEnabled(), setRootPaneCheckingEnabled(boolean), RootPaneContainer

accessibleContext

protected AccessibleContext accessibleContext
Constructor Detail

JDialog

public JDialog()
Creates a modeless dialog without a title and without a specified Frame owner. A shared, hidden frame will be set as the owner of the dialog.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

NOTE: This constructor does not allow you to create an unowned JDialog. To create an unowned JDialog you must use either the JDialog(Window) or JDialog(Dialog) constructor with an argument of null.

Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
GraphicsEnvironment.isHeadless(), JComponent.getDefaultLocale()

JDialog

public JDialog(Frame owner)
Creates a modeless dialog without a title with the specified Frame as its owner. If owner is null, a shared, hidden frame will be set as the owner of the dialog.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

NOTE: This constructor does not allow you to create an unowned JDialog. To create an unowned JDialog you must use either the JDialog(Window) or JDialog(Dialog) constructor with an argument of null.

Parameters:
owner - the Frame from which the dialog is displayed
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
GraphicsEnvironment.isHeadless(), JComponent.getDefaultLocale()

JDialog

public JDialog(Frame owner,
               boolean modal)
Creates a dialog with the specified owner Frame, modality and an empty title. If owner is null, a shared, hidden frame will be set as the owner of the dialog.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

NOTE: This constructor does not allow you to create an unowned JDialog. To create an unowned JDialog you must use either the JDialog(Window) or JDialog(Dialog) constructor with an argument of null.

Parameters:
owner - the Frame from which the dialog is displayed
modal - specifies whether dialog blocks user input to other top-level windows when shown. If true, the modality type property is set to DEFAULT_MODALITY_TYPE, otherwise the dialog is modeless.
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
GraphicsEnvironment.isHeadless(), JComponent.getDefaultLocale()

JDialog

public JDialog(Frame owner,
               String title)
Creates a modeless dialog with the specified title and with the specified owner frame. If owner is null, a shared, hidden frame will be set as the owner of the dialog.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

NOTE: This constructor does not allow you to create an unowned JDialog. To create an unowned JDialog you must use either the JDialog(Window) or JDialog(Dialog) constructor with an argument of null.

Parameters:
owner - the Frame from which the dialog is displayed
title - the String to display in the dialog's title bar
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
GraphicsEnvironment.isHeadless(), JComponent.getDefaultLocale()

JDialog

public JDialog(Frame owner,
               String title,
               boolean modal)
Creates a dialog with the specified title, owner Frame and modality. If owner is null, a shared, hidden frame will be set as the owner of this dialog.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

NOTE: Any popup components (JComboBox, JPopupMenu, JMenuBar) created within a modal dialog will be forced to be lightweight.

NOTE: This constructor does not allow you to create an unowned JDialog. To create an unowned JDialog you must use either the JDialog(Window) or JDialog(Dialog) constructor with an argument of null.

Parameters:
owner - the Frame from which the dialog is displayed
title - the String to display in the dialog's title bar
modal - specifies whether dialog blocks user input to other top-level windows when shown. If true, the modality type property is set to DEFAULT_MODALITY_TYPE otherwise the dialog is modeless
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
Dialog.ModalityType, Dialog.ModalityType.MODELESS, Dialog.DEFAULT_MODALITY_TYPE, Dialog.setModal(boolean), Dialog.setModalityType(java.awt.Dialog.ModalityType), GraphicsEnvironment.isHeadless(), JComponent.getDefaultLocale()

JDialog

public JDialog(Frame owner,
               String title,
               boolean modal,
               GraphicsConfiguration gc)
Creates a dialog with the specified title, owner Frame, modality and GraphicsConfiguration. If owner is null, a shared, hidden frame will be set as the owner of this dialog.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

NOTE: Any popup components (JComboBox, JPopupMenu, JMenuBar) created within a modal dialog will be forced to be lightweight.

NOTE: This constructor does not allow you to create an unowned JDialog. To create an unowned JDialog you must use either the JDialog(Window) or JDialog(Dialog) constructor with an argument of null.

Parameters:
owner - the Frame from which the dialog is displayed
title - the String to display in the dialog's title bar
modal - specifies whether dialog blocks user input to other top-level windows when shown. If true, the modality type property is set to DEFAULT_MODALITY_TYPE, otherwise the dialog is modeless.
gc - the GraphicsConfiguration of the target screen device. If gc is null, the same GraphicsConfiguration as the owning Frame is used.
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
Since:
1.4
See Also:
Dialog.ModalityType, Dialog.ModalityType.MODELESS, Dialog.DEFAULT_MODALITY_TYPE, Dialog.setModal(boolean), Dialog.setModalityType(java.awt.Dialog.ModalityType), GraphicsEnvironment.isHeadless(), JComponent.getDefaultLocale()

JDialog

public JDialog(Dialog owner)
Creates a modeless dialog without a title with the specified Dialog as its owner.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
owner - the owner Dialog from which the dialog is displayed or null if this dialog has no owner
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
GraphicsEnvironment.isHeadless(), JComponent.getDefaultLocale()

JDialog

public JDialog(Dialog owner,
               boolean modal)
Creates a dialog with the specified owner Dialog and modality.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
owner - the owner Dialog from which the dialog is displayed or null if this dialog has no owner
modal - specifies whether dialog blocks user input to other top-level windows when shown. If true, the modality type property is set to DEFAULT_MODALITY_TYPE, otherwise the dialog is modeless.
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
Dialog.ModalityType, Dialog.ModalityType.MODELESS, Dialog.DEFAULT_MODALITY_TYPE, Dialog.setModal(boolean), Dialog.setModalityType(java.awt.Dialog.ModalityType), GraphicsEnvironment.isHeadless(), JComponent.getDefaultLocale()

JDialog

public JDialog(Dialog owner,
               String title)
Creates a modeless dialog with the specified title and with the specified owner dialog.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
owner - the owner Dialog from which the dialog is displayed or null if this dialog has no owner
title - the String to display in the dialog's title bar
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
GraphicsEnvironment.isHeadless(), JComponent.getDefaultLocale()

JDialog

public JDialog(Dialog owner,
               String title,
               boolean modal)
Creates a dialog with the specified title, modality and the specified owner Dialog.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
owner - the owner Dialog from which the dialog is displayed or null if this dialog has no owner
title - the String to display in the dialog's title bar
modal - specifies whether dialog blocks user input to other top-level windows when shown. If true, the modality type property is set to DEFAULT_MODALITY_TYPE, otherwise the dialog is modeless
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
Dialog.ModalityType, Dialog.ModalityType.MODELESS, Dialog.DEFAULT_MODALITY_TYPE, Dialog.setModal(boolean), Dialog.setModalityType(java.awt.Dialog.ModalityType), GraphicsEnvironment.isHeadless(), JComponent.getDefaultLocale()

JDialog

public JDialog(Dialog owner,
               String title,
               boolean modal,
               GraphicsConfiguration gc)
Creates a dialog with the specified title, owner Dialog, modality and GraphicsConfiguration.

NOTE: Any popup components (JComboBox, JPopupMenu, JMenuBar) created within a modal dialog will be forced to be lightweight.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
owner - the owner Dialog from which the dialog is displayed or null if this dialog has no owner
title - the String to display in the dialog's title bar
modal - specifies whether dialog blocks user input to other top-level windows when shown. If true, the modality type property is set to DEFAULT_MODALITY_TYPE, otherwise the dialog is modeless
gc - the GraphicsConfiguration of the target screen device. If gc is null, the same GraphicsConfiguration as the owning Dialog is used.
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
Since:
1.4
See Also:
Dialog.ModalityType, Dialog.ModalityType.MODELESS, Dialog.DEFAULT_MODALITY_TYPE, Dialog.setModal(boolean), Dialog.setModalityType(java.awt.Dialog.ModalityType), GraphicsEnvironment.isHeadless(), JComponent.getDefaultLocale()

JDialog

public JDialog(Window owner)
Creates a modeless dialog with the specified owner Window and an empty title.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
owner - the Window from which the dialog is displayed or null if this dialog has no owner
Throws:
HeadlessException - when GraphicsEnvironment.isHeadless() returns true
Since:
1.6
See Also:
GraphicsEnvironment.isHeadless(), JComponent.getDefaultLocale()

JDialog

public JDialog(Window owner,
               Dialog.ModalityType modalityType)
Creates a dialog with the specified owner Window, modality and an empty title.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
owner - the Window from which the dialog is displayed or null if this dialog has no owner
modalityType - specifies whether dialog blocks input to other windows when shown. null value and unsupported modality types are equivalent to MODELESS
Throws:
HeadlessException - when GraphicsEnvironment.isHeadless() returns true
Since:
1.6
See Also:
Dialog.ModalityType,
Dialog.setModal(boolean),
Dialog.setModalityType(java.awt.Dialog.ModalityType),
GraphicsEnvironment.isHeadless(),
JComponent.getDefaultLocale()

JDialog

public JDialog(Window owner,
               String title)
Creates a modeless dialog with the specified title and owner Window.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
owner - the Window from which the dialog is displayed or null if this dialog has no owner
title - the String to display in the dialog's title bar or null if the dialog has no title
Throws:
HeadlessException - when GraphicsEnvironment.isHeadless() returns true
Since:
1.6
See Also:
GraphicsEnvironment.isHeadless(), JComponent.getDefaultLocale()

JDialog

public JDialog(Window owner,
               String title,
               Dialog.ModalityType modalityType)
Creates a dialog with the specified title, owner Window and modality.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
owner - the Window from which the dialog is displayed or null if this dialog has no owner
title - the String to display in the dialog's title bar or null if the dialog has no title
modalityType - specifies whether dialog blocks input to other windows when shown. null value and unsupported modality types are equivalent to MODELESS
Throws:
HeadlessException - when GraphicsEnvironment.isHeadless() returns true
Since:
1.6
See Also:
Dialog.ModalityType,
Dialog.setModal(boolean),
Dialog.setModalityType(java.awt.Dialog.ModalityType),
GraphicsEnvironment.isHeadless(),
JComponent.getDefaultLocale()

JDialog

public JDialog(Window owner,
               String title,
               Dialog.ModalityType modalityType,
               GraphicsConfiguration gc)
Creates a dialog with the specified title, owner Window, modality and GraphicsConfiguration.

NOTE: Any popup components (JComboBox, JPopupMenu, JMenuBar) created within a modal dialog will be forced to be lightweight.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
owner - the Window from which the dialog is displayed or null if this dialog has no owner
title - the String to display in the dialog's title bar or null if the dialog has no title
modalityType - specifies whether dialog blocks input to other windows when shown. null value and unsupported modality types are equivalent to MODELESS
gc - the GraphicsConfiguration of the target screen device; if null, the GraphicsConfiguration from the owning window is used; if owner is also null, the system default GraphicsConfiguration is assumed
Throws:
HeadlessException - when GraphicsEnvironment.isHeadless() returns true
Since:
1.6
See Also:
Dialog.ModalityType,
Dialog.setModal(boolean),
Dialog.setModalityType(java.awt.Dialog.ModalityType),
GraphicsEnvironment.isHeadless(),
JComponent.getDefaultLocale()
Method Detail

dialogInit

protected void dialogInit()
Called by the constructors to init the JDialog properly.

createRootPane

protected JRootPane createRootPane()
Called by the constructor methods to create the default rootPane.

processWindowEvent

protected void processWindowEvent(WindowEvent e)
Handles window events depending on the state of the defaultCloseOperation property.

Overrides:
processWindowEvent in class Window
Parameters:
e - the window event
See Also:
setDefaultCloseOperation(int)

setDefaultCloseOperation

public void setDefaultCloseOperation(int operation)
Sets the operation that will happen by default when the user initiates a "close" on this dialog. You must specify one of the following choices:

  • DO_NOTHING_ON_CLOSE (defined in WindowConstants): Don't do anything; require the program to handle the operation in the windowClosing method of a registered WindowListener object.
  • HIDE_ON_CLOSE (defined in WindowConstants): Automatically hide the dialog after invoking any registered WindowListener objects.
  • DISPOSE_ON_CLOSE (defined in WindowConstants): Automatically hide and dispose the dialog after invoking any registered WindowListener objects.

The value is set to HIDE_ON_CLOSE by default. Changes to the value of this property cause the firing of a property change event, with property name "defaultCloseOperation".

Note: When the last displayable window within the Java virtual machine (VM) is disposed of, the VM may terminate. See AWT Threading Issues for more information.

Parameters:
operation - the operation which should be performed when the user closes the dialog
Throws:
IllegalArgumentException - if defaultCloseOperation value isn't one of the above valid values
See Also:
Window.addWindowListener(java.awt.event.WindowListener), getDefaultCloseOperation(), WindowConstants

getDefaultCloseOperation

public int getDefaultCloseOperation()
Returns the operation which occurs when the user initiates a "close" on this dialog.

Returns:
an integer indicating the window-close operation
See Also:
setDefaultCloseOperation(int)

setTransferHandler

public void setTransferHandler(TransferHandler newHandler)
Sets the transferHandler property, which is a mechanism to support transfer of data into this component. Use null if the component does not support data transfer operations.

If the system property suppressSwingDropSupport is false (the default) and the current drop target on this component is either null or not a user-set drop target, this method will change the drop target as follows: If newHandler is null it will clear the drop target. If not null it will install a new DropTarget.

Note: When used with JDialog, TransferHandler only provides data import capability, as the data export related methods are currently typed to JComponent.

Please see How to Use Drag and Drop and Data Transfer, a section in The Java Tutorial, for more information.

Parameters:
newHandler - the new TransferHandler
Since:
1.6
See Also:
TransferHandler, getTransferHandler(), Component.setDropTarget(java.awt.dnd.DropTarget)

getTransferHandler

public TransferHandler getTransferHandler()
Gets the transferHandler property.

Returns:
the value of the transferHandler property
Since:
1.6
See Also:
TransferHandler, setTransferHandler(javax.swing.TransferHandler)

update

public void update(Graphics g)
Calls paint(g). This method was overridden to prevent an unnecessary call to clear the background.

Overrides:
update in class Container
Parameters:
g - the Graphics context in which to paint
See Also:
Component.update(Graphics)

setJMenuBar

public void setJMenuBar(JMenuBar menu)
Sets the menubar for this dialog.

Parameters:
menu - the menubar being placed in the dialog
See Also:
getJMenuBar()

getJMenuBar

public JMenuBar getJMenuBar()
Returns the menubar set on this dialog.

See Also:
setJMenuBar(javax.swing.JMenuBar)

isRootPaneCheckingEnabled

protected boolean isRootPaneCheckingEnabled()
Returns whether calls to add and setLayout are forwarded to the contentPane.

Returns:
true if add and setLayout are fowarded; false otherwise
See Also:
addImpl(java.awt.Component, java.lang.Object, int), setLayout(java.awt.LayoutManager), setRootPaneCheckingEnabled(boolean), RootPaneContainer

setRootPaneCheckingEnabled

protected void setRootPaneCheckingEnabled(boolean enabled)
Sets whether calls to add and setLayout are forwarded to the contentPane.

Parameters:
enabled - true if add and setLayout are forwarded, false if they should operate directly on the JDialog.
See Also:
addImpl(java.awt.Component, java.lang.Object, int),
setLayout(java.awt.LayoutManager),
isRootPaneCheckingEnabled(),
RootPaneContainer

addImpl

protected void addImpl(Component comp,
                       Object constraints,
                       int index)
Adds the specified child Component. This method is overridden to conditionally forward calls to the contentPane. By default, children are added to the contentPane instead of the frame, refer to RootPaneContainer for details.

Overrides:
addImpl in class Container
Parameters:
comp - the component to be enhanced
constraints - the constraints to be respected
index - the index
Throws:
IllegalArgumentException - if index is invalid
IllegalArgumentException - if adding the container's parent to itself
IllegalArgumentException - if adding a window to a container
See Also:
setRootPaneCheckingEnabled(boolean), RootPaneContainer

remove

public void remove(Component comp)
Removes the specified component from the container. If comp is not the rootPane, this will forward the call to the contentPane. This will do nothing if comp is not a child of the JDialog or contentPane.

Overrides:
remove in class Container
Parameters:
comp - the component to be removed
Throws:
NullPointerException - if comp is null
See Also:
Container.add(java.awt.Component), RootPaneContainer

setLayout

public void setLayout(LayoutManager manager)
Sets the LayoutManager. Overridden to conditionally forward the call to the contentPane. Refer to RootPaneContainer for more information.

Overrides:
setLayout in class Container
Parameters:
manager - the LayoutManager
See Also:
setRootPaneCheckingEnabled(boolean), RootPaneContainer

getRootPane

public JRootPane getRootPane()
Returns the rootPane object for this dialog.

Specified by:
getRootPane in interface RootPaneContainer
Returns:
this components single JRootPane child.
See Also:
setRootPane(javax.swing.JRootPane), RootPaneContainer.getRootPane()

setRootPane

protected void setRootPane(JRootPane root)
Sets the rootPane property. This method is called by the constructor.

Parameters:
root - the rootPane object for this dialog
See Also:
getRootPane()

getContentPane

public Container getContentPane()
Returns the contentPane object for this dialog.

Specified by:
getContentPane in interface RootPaneContainer
Returns:
the contentPane property
See Also:
setContentPane(java.awt.Container), RootPaneContainer.getContentPane()

setContentPane

public void setContentPane(Container contentPane)
Sets the contentPane property. This method is called by the constructor.

Swing's painting architecture requires an opaque JComponent in the containment hiearchy. This is typically provided by the content pane. If you replace the content pane it is recommended you replace it with an opaque JComponent.

Specified by:
setContentPane in interface RootPaneContainer
Parameters:
contentPane - the contentPane object for this dialog
Throws:
IllegalComponentStateException - (a runtime exception) if the content pane parameter is null
See Also:
JRootPane, getContentPane(), RootPaneContainer.setContentPane(java.awt.Container)

getLayeredPane

public JLayeredPane getLayeredPane()
Returns the layeredPane object for this dialog.

Specified by:
getLayeredPane in interface RootPaneContainer
Returns:
the layeredPane property
See Also:
setLayeredPane(javax.swing.JLayeredPane), RootPaneContainer.getLayeredPane()

setLayeredPane

public void setLayeredPane(JLayeredPane layeredPane)
Sets the layeredPane property. This method is called by the constructor.

Specified by:
setLayeredPane in interface RootPaneContainer
Parameters:
layeredPane - the new layeredPane property
Throws:
IllegalComponentStateException - (a runtime exception) if the layered pane parameter is null
See Also:
getLayeredPane(), RootPaneContainer.setLayeredPane(javax.swing.JLayeredPane)

getGlassPane

public Component getGlassPane()
Returns the glassPane object for this dialog.

Specified by:
getGlassPane in interface RootPaneContainer
Returns:
the glassPane property
See Also:
setGlassPane(java.awt.Component), RootPaneContainer.getGlassPane()

setGlassPane

public void setGlassPane(Component glassPane)
Sets the glassPane property. This method is called by the constructor.

Specified by:
setGlassPane in interface RootPaneContainer
Parameters:
glassPane - the glassPane object for this dialog
See Also:
getGlassPane(), RootPaneContainer.setGlassPane(java.awt.Component)

getGraphics

public Graphics getGraphics()
Creates a graphics context for this component. This method will return null if this component is currently not displayable.

Overrides:
getGraphics in class Component
Returns:
a graphics context for this component, or null if it has none
Since:
1.6
See Also:
Component.paint(java.awt.Graphics)

repaint

public void repaint(long time,
                    int x,
                    int y,
                    int width,
                    int height)
Repaints the specified rectangle of this component within time milliseconds. Refer to RepaintManager for details on how the repaint is handled.

Overrides:
repaint in class Component
Parameters:
time - maximum time in milliseconds before update
x - the x coordinate
y - the y coordinate
width - the width
height - the height
Since:
1.6
See Also:
RepaintManager

setDefaultLookAndFeelDecorated

public static void setDefaultLookAndFeelDecorated(boolean defaultLookAndFeelDecorated)
Provides a hint as to whether or not newly created JDialogs should have their Window decorations (such as borders, widgets to close the window, title...) provided by the current look and feel. If defaultLookAndFeelDecorated is true, the current LookAndFeel supports providing window decorations, and the current window manager supports undecorated windows, then newly created JDialogs will have their Window decorations provided by the current LookAndFeel. Otherwise, newly created JDialogs will have their Window decorations provided by the current window manager.

You can get the same effect on a single JDialog by doing the following:

    JDialog dialog = new JDialog();
    dialog.setUndecorated(true);
    dialog.getRootPane().setWindowDecorationStyle(JRootPane.PLAIN_DIALOG);

Parameters:
defaultLookAndFeelDecorated - A hint as to whether or not current look and feel should provide window decorations
Since:
1.4
See Also:
LookAndFeel.getSupportsWindowDecorations()

isDefaultLookAndFeelDecorated

public static boolean isDefaultLookAndFeelDecorated()
Returns true if newly created JDialogs should have their Window decorations provided by the current look and feel. This is only a hint, as certain look and feels may not support this feature.

Returns:
true if look and feel should provide Window decorations.
Since:
1.4

paramString

protected String paramString()
Returns a string representation of this JDialog. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class Dialog
Returns:
a string representation of this JDialog.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JDialog. For JDialogs, the AccessibleContext takes the form of an AccessibleJDialog. A new AccessibleJDialog instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class Dialog
Returns:
an AccessibleJDialog that serves as the AccessibleContext of this JDialog
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JDialog.AccessibleJDialog

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JDialog.AccessibleJDialog

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  java.awt.Window.AccessibleAWTWindow
                    extended by  java.awt.Dialog.AccessibleAWTDialog
                        extended by  javax.swing.JDialog.AccessibleJDialog
All Implemented Interfaces:
Serializable, AccessibleComponent
Enclosing class:
JDialog
protected class JDialog.AccessibleJDialog
extends Dialog.AccessibleAWTDialog

This class implements accessibility support for the JDialog class. It provides an implementation of the Java Accessibility API appropriate to dialog user-interface elements.

Nested Class Summary
Nested classes/interfaces inherited from class java.awt.Container.AccessibleAWTContainer
Container.AccessibleAWTContainer.AccessibleContainerHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class java.awt.Container.AccessibleAWTContainer
accessibleContainerHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JDialog.AccessibleJDialog()
Method Summary
String | getAccessibleName() Get the accessible name of this object.
AccessibleStateSet | getAccessibleStateSet() Get the state of this object.
Methods inherited from class java.awt.Dialog.AccessibleAWTDialog
getAccessibleRole
Methods inherited from class java.awt.Container.AccessibleAWTContainer
addPropertyChangeListener, getAccessibleAt, getAccessibleChild, getAccessibleChildrenCount
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleDescription, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, removePropertyChangeListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JDialog.AccessibleJDialog

protected JDialog.AccessibleJDialog()
Method Detail

getAccessibleName

public String getAccessibleName()
Get the accessible name of this object.

Overrides:
getAccessibleName in class Component.AccessibleAWTComponent
Returns:
the localized name of the object -- can be null if this object does not have a name
See Also:
AccessibleContext.setAccessibleName(java.lang.String)

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Get the state of this object.

Overrides:
getAccessibleStateSet in class Dialog.AccessibleAWTDialog
Returns:
an instance of AccessibleStateSet containing the current state set of the object
See Also:
AccessibleState
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JEditorPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JEditorPane

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.text.JTextComponent
                    extended by  javax.swing.JEditorPane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable
Direct Known Subclasses:
JTextPane
public class JEditorPane
extends JTextComponent

A text component to edit various kinds of content. You can find how-to information and examples of using editor panes in Using Text Components, a section in The Java Tutorial.

This component uses implementations of the EditorKit to accomplish its behavior. It effectively morphs into the proper kind of text editor for the kind of content it is given. The content type that editor is bound to at any given time is determined by the EditorKit currently installed. If the content is set to a new URL, its type is used to determine the EditorKit that should be used to load the content.

By default, the following types of content are known:

text/plain
Plain text, which is the default the type given isn't recognized. The kit used in this case is an extension of DefaultEditorKit that produces a wrapped plain text view.
text/html
HTML text. The kit used in this case is the class javax.swing.text.html.HTMLEditorKit which provides HTML 3.2 support.
text/rtf
RTF text. The kit used in this case is the class javax.swing.text.rtf.RTFEditorKit which provides a limited support of the Rich Text Format.

There are several ways to load content into this component.

  1. The setText method can be used to initialize the component from a string. In this case the current EditorKit will be used, and the content type will be expected to be of this type.
  2. The read method can be used to initialize the component from a Reader. Note that if the content type is HTML, relative references (e.g. for things like images) can't be resolved unless the <base> tag is used or the Base property on HTMLDocument is set. In this case the current EditorKit will be used, and the content type will be expected to be of this type.
  3. The setPage method can be used to initialize the component from a URL. In this case, the content type will be determined from the URL, and the registered EditorKit for that content type will be set.

Some kinds of content may provide hyperlink support by generating hyperlink events. The HTML EditorKit will generate hyperlink events if the JEditorPane is not editable (JEditorPane.setEditable(false); has been called). If HTML frames are embedded in the document, the typical response would be to change a portion of the current document. The following code fragment is a possible hyperlink listener implementation, that treats HTML frame events specially, and simply displays any other activated hyperlinks.

     class Hyperactive implements HyperlinkListener {

         public void hyperlinkUpdate(HyperlinkEvent e) {
             if (e.getEventType() == HyperlinkEvent.EventType.ACTIVATED) {
                 JEditorPane pane = (JEditorPane) e.getSource();
                 if (e instanceof HTMLFrameHyperlinkEvent) {
                     HTMLFrameHyperlinkEvent  evt = (HTMLFrameHyperlinkEvent)e;
                     HTMLDocument doc = (HTMLDocument)pane.getDocument();
                     doc.processHTMLFrameHyperlinkEvent(evt);
                 } else {
                     try {
                         pane.setPage(e.getURL());
                     } catch (Throwable t) {
                         t.printStackTrace();
                     }
                 }
             }
         }
     }

For information on customizing how text/html is rendered please see W3C_LENGTH_UNITS and HONOR_DISPLAY_PROPERTIES

Culturally dependent information in some documents is handled through a mechanism called character encoding. Character encoding is an unambiguous mapping of the members of a character set (letters, ideographs, digits, symbols, or control functions) to specific numeric code values. It represents the way the file is stored. Example character encodings are ISO-8859-1, ISO-8859-5, Shift-jis, Euc-jp, and UTF-8. When the file is passed to an user agent (JEditorPane) it is converted to the document character set (ISO-10646 aka Unicode).

There are multiple ways to get a character set mapping to happen with JEditorPane.

  1. One way is to specify the character set as a parameter of the MIME type. This will be established by a call to the setContentType method. If the content is loaded by the setPage method the content type will have been set according to the specification of the URL. It the file is loaded directly, the content type would be expected to have been set prior to loading.
  2. Another way the character set can be specified is in the document itself. This requires reading the document prior to determining the character set that is desired. To handle this, it is expected that the EditorKit.read operation throw a ChangedCharSetException which will be caught. The read is then restarted with a new Reader that uses the character set specified in the ChangedCharSetException (which is an IOException).

Newlines
For a discussion on how newlines are handled, see DefaultEditorKit.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected class | JEditorPane.AccessibleJEditorPane This class implements accessibility support for the JEditorPane class.
protected class | JEditorPane.AccessibleJEditorPaneHTML This class provides support for AccessibleHypertext, and is used in instances where the EditorKit installed in this JEditorPane is an instance of HTMLEditorKit.
protected class | JEditorPane.JEditorPaneAccessibleHypertextSupport What's returned by AccessibleJEditorPaneHTML.getAccessibleText.
Nested classes/interfaces inherited from class javax.swing.text.JTextComponent
JTextComponent.AccessibleJTextComponent, JTextComponent.DropLocation, JTextComponent.KeyBinding
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
static String | HONOR_DISPLAY_PROPERTIES Key for a client property used to indicate whether the default font and foreground color from the component are used if a font or foreground color is not specified in the styled text.
static String | W3C_LENGTH_UNITS Key for a client property used to indicate whether w3c compliant length units are used for html rendering.
Fields inherited from class javax.swing.text.JTextComponent
DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JEditorPane()
Creates a new JEditorPane.
JEditorPane(String url)
Creates a JEditorPane based on a string containing a URL specification.
JEditorPane(String type, String text)
Creates a JEditorPane that has been initialized to the given text.
JEditorPane(URL initialPage)
Creates a JEditorPane based on a specified URL for input.
Method Summary
 void addHyperlinkListener(HyperlinkListener listener)
Adds a hyperlink listener for notification of any changes, for example when a link is selected and entered.
protected  EditorKit createDefaultEditorKit()
Creates the default editor kit (PlainEditorKit) for when the component is first created.
static EditorKit createEditorKitForContentType(String type)
Creates a handler for the given type from the default registry of editor kits.
 void fireHyperlinkUpdate(HyperlinkEvent e)
Notifies all listeners that have registered interest for notification on this event type.
 AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JEditorPane.
 String getContentType()
Gets the type of content that this editor is currently set to deal with.
 EditorKit getEditorKit()
Fetches the currently installed kit for handling content.
static String getEditorKitClassNameForContentType(String type)
Returns the currently registered EditorKit class name for the type type.
 EditorKit getEditorKitForContentType(String type)
Fetches the editor kit to use for the given type of content.
 HyperlinkListener[] getHyperlinkListeners()
Returns an array of all the HyperLinkListeners added to this JEditorPane with addHyperlinkListener().
 URL getPage()
Gets the current URL being displayed.
 Dimension getPreferredSize()
Returns the preferred size for the JEditorPane.
 boolean getScrollableTracksViewportHeight()
Returns true if a viewport should always force the height of this Scrollable to match the height of the viewport.
 boolean getScrollableTracksViewportWidth()
Returns true if a viewport should always force the width of this Scrollable to match the width of the viewport.
protected  InputStream getStream(URL page)
Fetches a stream for the given URL, which is about to be loaded by the setPage method.
 String getText()
Returns the text contained in this TextComponent in terms of the content type of this editor.
 String getUIClassID()
Gets the class ID for the UI.
protected  String paramString()
Returns a string representation of this JEditorPane.
 void read(InputStream in, Object desc)
This method initializes from a stream.
static void registerEditorKitForContentType(String type, String classname)
Establishes the default bindings of type to classname.
static void registerEditorKitForContentType(String type, String classname, ClassLoader loader)
Establishes the default bindings of type to classname.
 void removeHyperlinkListener(HyperlinkListener listener)
Removes a hyperlink listener.
 void replaceSelection(String content)
Replaces the currently selected content with new content represented by the given string.
 void scrollToReference(String reference)
Scrolls the view to the given reference location (that is, the value returned by the UL.getRef method for the URL being displayed).
 void setContentType(String type)
Sets the type of content that this editor handles.
 void setEditorKit(EditorKit kit)
Sets the currently installed kit for handling content.
 void setEditorKitForContentType(String type, EditorKit k)
Directly sets the editor kit to use for the given type.
 void setPage(String url)
Sets the current URL being displayed.
 void setPage(URL page)
Sets the current URL being displayed.
 void setText(String t)
Sets the text of this TextComponent to the specified content, which is expected to be in the format of the content type of this editor.
Methods inherited from class javax.swing.text.JTextComponent
addCaretListener, addInputMethodListener, addKeymap, copy, cut, fireCaretUpdate, getActions, getCaret, getCaretColor, getCaretListeners, getCaretPosition, getDisabledTextColor, getDocument, getDragEnabled, getDropLocation, getDropMode, getFocusAccelerator, getHighlighter, getInputMethodRequests, getKeymap, getKeymap, getMargin, getNavigationFilter, getPreferredScrollableViewportSize, getPrintable, getScrollableBlockIncrement, getScrollableUnitIncrement, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getToolTipText, getUI, isEditable, loadKeymap, modelToView, moveCaretPosition, paste, print, print, print, processInputMethodEvent, read, removeCaretListener, removeKeymap, removeNotify, select, selectAll, setCaret, setCaretColor, setCaretPosition, setComponentOrientation, setDisabledTextColor, setDocument, setDragEnabled, setDropMode, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setUI, updateUI, viewToModel, write
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

W3C_LENGTH_UNITS

public static final String W3C_LENGTH_UNITS
Key for a client property used to indicate whether w3c compliant length units are used for html rendering.

By default this is not enabled; to enable it set the client property with this name to Boolean.TRUE.

Since:
1.5
See Also:
Constant Field Values

HONOR_DISPLAY_PROPERTIES

public static final String HONOR_DISPLAY_PROPERTIES
Key for a client property used to indicate whether the default font and foreground color from the component are used if a font or foreground color is not specified in the styled text.

The default varies based on the look and feel; to enable it set the client property with this name to Boolean.TRUE.

Since:
1.5
See Also:
Constant Field Values
Constructor Detail

JEditorPane

public JEditorPane()
Creates a new JEditorPane. The document model is set to null.

JEditorPane

public JEditorPane(URL initialPage)
            throws IOException
Creates a JEditorPane based on a specified URL for input.

Parameters:
initialPage - the URL
Throws:
IOException - if the URL is null or cannot be accessed

JEditorPane

public JEditorPane(String url)
            throws IOException
Creates a JEditorPane based on a string containing a URL specification.

Parameters:
url - the URL
Throws:
IOException - if the URL is null or cannot be accessed

JEditorPane

public JEditorPane(String type,
                   String text)
Creates a JEditorPane that has been initialized to the given text. This is a convenience constructor that calls the setContentType and setText methods.

Parameters:
type - mime type of the given text
text - the text to initialize with; may be null
Throws:
NullPointerException - if the type parameter is null
Method Detail

addHyperlinkListener

public void addHyperlinkListener(HyperlinkListener listener)
Adds a hyperlink listener for notification of any changes, for example when a link is selected and entered.

Parameters:
listener - the listener

removeHyperlinkListener

public void removeHyperlinkListener(HyperlinkListener listener)
Removes a hyperlink listener.

Parameters:
listener - the listener

getHyperlinkListeners

public HyperlinkListener[] getHyperlinkListeners()
Returns an array of all the HyperLinkListeners added to this JEditorPane with addHyperlinkListener().

Returns:
all of the HyperLinkListeners added or an empty array if no listeners have been added
Since:
1.4

fireHyperlinkUpdate

public void fireHyperlinkUpdate(HyperlinkEvent e)
Notifies all listeners that have registered interest for notification on this event type. This is normally called by the currently installed EditorKit if a content type that supports hyperlinks is currently active and there was activity with a link. The listener list is processed last to first.

Parameters:
e - the event
See Also:
EventListenerList

setPage

public void setPage(URL page)
             throws IOException
Sets the current URL being displayed. The content type of the pane is set, and if the editor kit for the pane is non-null, then a new default document is created and the URL is read into it. If the URL contains and reference location, the location will be scrolled to by calling the scrollToReference method. If the desired URL is the one currently being displayed, the document will not be reloaded. To force a document reload it is necessary to clear the stream description property of the document. The following code shows how this can be done:
   Document doc = jEditorPane.getDocument();
   doc.putProperty(Document.StreamDescriptionProperty, null);
If the desired URL is not the one currently being displayed, the getStream method is called to give subclasses control over the stream provided.

This may load either synchronously or asynchronously depending upon the document returned by the EditorKit. If the Document is of type AbstractDocument and has a value returned by AbstractDocument.getAsynchronousLoadPriority that is greater than or equal to zero, the page will be loaded on a separate thread using that priority.

If the document is loaded synchronously, it will be filled in with the stream prior to being installed into the editor with a call to setDocument, which is bound and will fire a property change event. If an IOException is thrown the partially loaded document will be discarded and neither the document or page property change events will be fired. If the document is successfully loaded and installed, a view will be built for it by the UI which will then be scrolled if necessary, and then the page property change event will be fired.

If the document is loaded asynchronously, the document will be installed into the editor immediately using a call to setDocument which will fire a document property change event, then a thread will be created which will begin doing the actual loading. In this case, the page property change event will not be fired by the call to this method directly, but rather will be fired when the thread doing the loading has finished. It will also be fired on the event-dispatch thread. Since the calling thread can not throw an IOException in the event of failure on the other thread, the page property change event will be fired when the other thread is done whether the load was successful or not.

Parameters:
page - the URL of the page
Throws:
IOException - for a null or invalid page specification, or exception from the stream being read
See Also:
getPage()

read

public void read(InputStream in,
                 Object desc)
          throws IOException
This method initializes from a stream. If the kit is set to be of type HTMLEditorKit, and the desc parameter is an HTMLDocument, then it invokes the HTMLEditorKit to initiate the read. Otherwise it calls the superclass method which loads the model as plain text.

Parameters:
in - the stream from which to read
desc - an object describing the stream
Throws:
IOException - as thrown by the stream being used to initialize
See Also:
JTextComponent.read(java.io.Reader, java.lang.Object), JTextComponent.setDocument(javax.swing.text.Document)

getStream

protected InputStream getStream(URL page)
                         throws IOException
Fetches a stream for the given URL, which is about to be loaded by the setPage method. By default, this simply opens the URL and returns the stream. This can be reimplemented to do useful things like fetch the stream from a cache, monitor the progress of the stream, etc.

This method is expected to have the the side effect of establishing the content type, and therefore setting the appropriate EditorKit to use for loading the stream.

If this the stream was an http connection, redirects will be followed and the resulting URL will be set as the Document.StreamDescriptionProperty so that relative URL's can be properly resolved.

Parameters:
page - the URL of the page
Throws:
IOException

scrollToReference

public void scrollToReference(String reference)
Scrolls the view to the given reference location (that is, the value returned by the UL.getRef method for the URL being displayed). By default, this method only knows how to locate a reference in an HTMLDocument. The implementation calls the scrollRectToVisible method to accomplish the actual scrolling. If scrolling to a reference location is needed for document types other than HTML, this method should be reimplemented. This method will have no effect if the component is not visible.

Parameters:
reference - the named location to scroll to

getPage

public URL getPage()
Gets the current URL being displayed. If a URL was not specified in the creation of the document, this will return null, and relative URL's will not be resolved.

Returns:
the URL, or null if none

setPage

public void setPage(String url)
             throws IOException
Sets the current URL being displayed.

Parameters:
url - the URL for display
Throws:
IOException - for a null or invalid URL specification

getUIClassID

public String getUIClassID()
Gets the class ID for the UI.

Overrides:
getUIClassID in class JComponent
Returns:
the string "EditorPaneUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

createDefaultEditorKit

protected EditorKit createDefaultEditorKit()
Creates the default editor kit (PlainEditorKit) for when the component is first created.

Returns:
the editor kit

getEditorKit

public EditorKit getEditorKit()
Fetches the currently installed kit for handling content. createDefaultEditorKit is called to set up a default if necessary.

Returns:
the editor kit

getContentType

public final String getContentType()
Gets the type of content that this editor is currently set to deal with. This is defined to be the type associated with the currently installed EditorKit.

Returns:
the content type, null if no editor kit set

setContentType

public final void setContentType(String type)
Sets the type of content that this editor handles. This calls getEditorKitForContentType, and then setEditorKit if an editor kit can be successfully located. This is mostly convenience method that can be used as an alternative to calling setEditorKit directly.

If there is a charset definition specified as a parameter of the content type specification, it will be used when loading input streams using the associated EditorKit. For example if the type is specified as text/html; charset=EUC-JP the content will be loaded using the EditorKit registered for text/html and the Reader provided to the EditorKit to load unicode into the document will use the EUC-JP charset for translating to unicode. If the type is not recognized, the content will be loaded using the EditorKit registered for plain text, text/plain.

Parameters:
type - the non-null mime type for the content editing support
Throws:
NullPointerException - if the type parameter is null
See Also:
getContentType()

setEditorKit

public void setEditorKit(EditorKit kit)
Sets the currently installed kit for handling content. This is the bound property that establishes the content type of the editor. Any old kit is first deinstalled, then if kit is non-null, the new kit is installed, and a default document created for it. A PropertyChange event ("editorKit") is always fired when setEditorKit is called.

NOTE: This has the side effect of changing the model, because the EditorKit is the source of how a particular type of content is modeled. This method will cause setDocument to be called on behalf of the caller to ensure integrity of the internal state.

Parameters:
kit - the desired editor behavior
See Also:
getEditorKit()

getEditorKitForContentType

public EditorKit getEditorKitForContentType(String type)
Fetches the editor kit to use for the given type of content. This is called when a type is requested that doesn't match the currently installed type. If the component doesn't have an EditorKit registered for the given type, it will try to create an EditorKit from the default EditorKit registry. If that fails, a PlainEditorKit is used on the assumption that all text documents can be represented as plain text.

This method can be reimplemented to use some other kind of type registry. This can be reimplemented to use the Java Activation Framework, for example.

Parameters:
type - the non-null content type
Returns:
the editor kit

setEditorKitForContentType

public void setEditorKitForContentType(String type,
                                       EditorKit k)
Directly sets the editor kit to use for the given type. A look-and-feel implementation might use this in conjunction with createEditorKitForContentType to install handlers for content types with a look-and-feel bias.

Parameters:
type - the non-null content type
k - the editor kit to be set

replaceSelection

public void replaceSelection(String content)
Replaces the currently selected content with new content represented by the given string. If there is no selection this amounts to an insert of the given text. If there is no replacement text (i.e. the content string is empty or null) this amounts to a removal of the current selection. The replacement text will have the attributes currently defined for input. If the component is not editable, beep and return.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Overrides:
replaceSelection in class JTextComponent
Parameters:
content - the content to replace the selection with. This value can be null

createEditorKitForContentType

public static EditorKit createEditorKitForContentType(String type)
Creates a handler for the given type from the default registry of editor kits. The registry is created if necessary. If the registered class has not yet been loaded, an attempt is made to dynamically load the prototype of the kit for the given type. If the type was registered with a ClassLoader, that ClassLoader will be used to load the prototype. If there was no registered ClassLoader, Class.forName will be used to load the prototype.

Once a prototype EditorKit instance is successfully located, it is cloned and the clone is returned.

Parameters:
type - the content type
Returns:
the editor kit, or null if there is nothing registered for the given type

registerEditorKitForContentType

public static void registerEditorKitForContentType(String type,
                                                   String classname)
Establishes the default bindings of type to classname. The class will be dynamically loaded later when actually needed, and can be safely changed before attempted uses to avoid loading unwanted classes. The prototype EditorKit will be loaded with Class.forName when registered with this method.

Parameters:
type - the non-null content type
classname - the class to load later

registerEditorKitForContentType

public static void registerEditorKitForContentType(String type,
                                                   String classname,
                                                   ClassLoader loader)
Establishes the default bindings of type to classname. The class will be dynamically loaded later when actually needed using the given ClassLoader, and can be safely changed before attempted uses to avoid loading unwanted classes.

Parameters:
type - the non-null content type
classname - the class to load later
loader - the ClassLoader to use to load the name

getEditorKitClassNameForContentType

public static String getEditorKitClassNameForContentType(String type)
Returns the currently registered EditorKit class name for the type type.

Parameters:
type - the non-null content type
Since:
1.3

getPreferredSize

public Dimension getPreferredSize()
Returns the preferred size for the JEditorPane. The preferred size for JEditorPane is slightly altered from the preferred size of the superclass. If the size of the viewport has become smaller than the minimum size of the component, the scrollable definition for tracking width or height will turn to false. The default viewport layout will give the preferred size, and that is not desired in the case where the scrollable is tracking. In that case the normal preferred size is adjusted to the minimum size. This allows things like HTML tables to shrink down to their minimum size and then be laid out at their minimum size, refusing to shrink any further.

Overrides:
getPreferredSize in class JComponent
Returns:
a Dimension containing the preferred size
See Also:
JComponent.setPreferredSize(java.awt.Dimension), ComponentUI

setText

public void setText(String t)
Sets the text of this TextComponent to the specified content, which is expected to be in the format of the content type of this editor. For example, if the type is set to text/html the string should be specified in terms of HTML.

This is implemented to remove the contents of the current document, and replace them by parsing the given string using the current EditorKit. This gives the semantics of the superclass by not changing out the model, while supporting the content type currently set on this component. The assumption is that the previous content is relatively small, and that the previous content doesn't have side effects. Both of those assumptions can be violated and cause undesirable results. To avoid this, create a new document, getEditorKit().createDefaultDocument(), and replace the existing Document with the new one. You are then assured the previous Document won't have any lingering state.

  1. Leaving the existing model in place means that the old view will be torn down, and a new view created, where replacing the document would avoid the tear down of the old view.
  2. Some formats (such as HTML) can install things into the document that can influence future contents. HTML can have style information embedded that would influence the next content installed unexpectedly.

An alternative way to load this component with a string would be to create a StringReader and call the read method. In this case the model would be replaced after it was initialized with the contents of the string.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Overrides:
setText in class JTextComponent
Parameters:
t - the new text to be set; if null the old text will be deleted
See Also:
getText()

getText

public String getText()
Returns the text contained in this TextComponent in terms of the content type of this editor. If an exception is thrown while attempting to retrieve the text, null will be returned. This is implemented to call JTextComponent.write with a StringWriter.

Overrides:
getText in class JTextComponent
Returns:
the text
See Also:
setText(java.lang.String)

getScrollableTracksViewportWidth

public boolean getScrollableTracksViewportWidth()
Returns true if a viewport should always force the width of this Scrollable to match the width of the viewport.

Specified by:
getScrollableTracksViewportWidth in interface Scrollable
Overrides:
getScrollableTracksViewportWidth in class JTextComponent
Returns:
true if a viewport should force the Scrollables width to match its own, false otherwise

getScrollableTracksViewportHeight

public boolean getScrollableTracksViewportHeight()
Returns true if a viewport should always force the height of this Scrollable to match the height of the viewport.

Specified by:
getScrollableTracksViewportHeight in interface Scrollable
Overrides:
getScrollableTracksViewportHeight in class JTextComponent
Returns:
true if a viewport should force the Scrollable's height to match its own, false otherwise

paramString

protected String paramString()
Returns a string representation of this JEditorPane. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JTextComponent
Returns:
a string representation of this JEditorPane

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JEditorPane. For editor panes, the AccessibleContext takes the form of an AccessibleJEditorPane. A new AccessibleJEditorPane instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JTextComponent
Returns:
an AccessibleJEditorPane that serves as the AccessibleContext of this JEditorPane
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JEditorPane.AccessibleJEditorPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JEditorPane.AccessibleJEditorPane

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.text.JTextComponent.AccessibleJTextComponent
                        extended by  javax.swing.JEditorPane.AccessibleJEditorPane
All Implemented Interfaces:
Serializable, EventListener, AccessibleAction, AccessibleComponent, AccessibleEditableText, AccessibleExtendedComponent, AccessibleExtendedText, AccessibleText, CaretListener, DocumentListener
Direct Known Subclasses:
JEditorPane.AccessibleJEditorPaneHTML, JEditorPane.JEditorPaneAccessibleHypertextSupport
Enclosing class:
JEditorPane
protected class JEditorPane.AccessibleJEditorPane
extends JTextComponent.AccessibleJTextComponent

This class implements accessibility support for the JEditorPane class. It provides an implementation of the Java Accessibility API appropriate to editor pane user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Fields inherited from interface javax.accessibility.AccessibleExtendedText
ATTRIBUTE_RUN, LINE
Constructor Summary
protected JEditorPane.AccessibleJEditorPane()
Method Summary
String | getAccessibleDescription() Gets the accessibleDescription property of this object.
AccessibleStateSet | getAccessibleStateSet() Gets the state set of this object.
Methods inherited from class javax.swing.text.JTextComponent.AccessibleJTextComponent
caretUpdate, changedUpdate, cut, delete, doAccessibleAction, getAccessibleAction, getAccessibleActionCount, getAccessibleActionDescription, getAccessibleEditableText, getAccessibleRole, getAccessibleText, getAfterIndex, getAtIndex, getBeforeIndex, getCaretPosition, getCharacterAttribute, getCharacterBounds, getCharCount, getIndexAtPoint, getSelectedText, getSelectionEnd, getSelectionStart, getTextBounds, getTextRange, getTextSequenceAfter, getTextSequenceAt, getTextSequenceBefore, insertTextAtIndex, insertUpdate, paste, removeUpdate, replaceText, selectText, setAttributes, setTextContents
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleKeyBinding, getAccessibleName, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JEditorPane.AccessibleJEditorPane

protected JEditorPane.AccessibleJEditorPane()
Method Detail

getAccessibleDescription

public String getAccessibleDescription()
Gets the accessibleDescription property of this object. If this property isn't set, returns the content type of this JEditorPane instead (e.g. "plain/text", "html/text").

Overrides:
getAccessibleDescription in class JComponent.AccessibleJComponent
Returns:
the localized description of the object; null if this object does not have a description
See Also:
AccessibleContext.setAccessibleName(java.lang.String)

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Gets the state set of this object.

Overrides:
getAccessibleStateSet in class JTextComponent.AccessibleJTextComponent
Returns:
an instance of AccessibleStateSet describing the states of the object
See Also:
AccessibleStateSet
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JEditorPane.AccessibleJEditorPaneHTML

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JEditorPane.AccessibleJEditorPaneHTML

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.text.JTextComponent.AccessibleJTextComponent
                        extended by  javax.swing.JEditorPane.AccessibleJEditorPane
                            extended by  javax.swing.JEditorPane.AccessibleJEditorPaneHTML
All Implemented Interfaces:
Serializable, EventListener, AccessibleAction, AccessibleComponent, AccessibleEditableText, AccessibleExtendedComponent, AccessibleExtendedText, AccessibleText, CaretListener, DocumentListener
Enclosing class:
JEditorPane
protected class JEditorPane.AccessibleJEditorPaneHTML
extends JEditorPane.AccessibleJEditorPane

This class provides support for AccessibleHypertext, and is used in instances where the EditorKit installed in this JEditorPane is an instance of HTMLEditorKit.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Fields inherited from interface javax.accessibility.AccessibleExtendedText
ATTRIBUTE_RUN, LINE
Constructor Summary
protected JEditorPane.AccessibleJEditorPaneHTML()
Method Summary
Accessible | getAccessibleAt(Point p) Returns the Accessible child, if one exists, contained at the local coordinate Point.
Accessible | getAccessibleChild(int i) Returns the specified Accessible child of the object.
int | getAccessibleChildrenCount() Returns the number of accessible children of the object.
AccessibleText | getAccessibleText() Get the AccessibleText associated with this object.
Methods inherited from class javax.swing.JEditorPane.AccessibleJEditorPane
getAccessibleDescription, getAccessibleStateSet
Methods inherited from class javax.swing.text.JTextComponent.AccessibleJTextComponent
caretUpdate, changedUpdate, cut, delete, doAccessibleAction, getAccessibleAction, getAccessibleActionCount, getAccessibleActionDescription, getAccessibleEditableText, getAccessibleRole, getAfterIndex, getAtIndex, getBeforeIndex, getCaretPosition, getCharacterAttribute, getCharacterBounds, getCharCount, getIndexAtPoint, getSelectedText, getSelectionEnd, getSelectionStart, getTextBounds, getTextRange, getTextSequenceAfter, getTextSequenceAt, getTextSequenceBefore, insertTextAtIndex, insertUpdate, paste, removeUpdate, replaceText, selectText, setAttributes, setTextContents
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleKeyBinding, getAccessibleName, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JEditorPane.AccessibleJEditorPaneHTML

protected JEditorPane.AccessibleJEditorPaneHTML()
Method Detail

getAccessibleText

public AccessibleText getAccessibleText()
Description copied from class: JTextComponent.AccessibleJTextComponent
Get the AccessibleText associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleText interface on behalf of itself.

Overrides:
getAccessibleText in class JTextComponent.AccessibleJTextComponent
Returns:
this object
See Also:
AccessibleText

getAccessibleChildrenCount

public int getAccessibleChildrenCount()
Returns the number of accessible children of the object.

Overrides:
getAccessibleChildrenCount in class JComponent.AccessibleJComponent
Returns:
the number of accessible children of the object.

getAccessibleChild

public Accessible getAccessibleChild(int i)
Returns the specified Accessible child of the object. The Accessible children of an Accessible object are zero-based, so the first child of an Accessible child is at index 0, the second child is at index 1, and so on.

Overrides:
getAccessibleChild in class JComponent.AccessibleJComponent
Parameters:
i - zero-based index of child
Returns:
the Accessible child of the object
See Also:
getAccessibleChildrenCount()

getAccessibleAt

public Accessible getAccessibleAt(Point p)
Returns the Accessible child, if one exists, contained at the local coordinate Point.

Specified by:
getAccessibleAt in interface AccessibleComponent
Overrides:
getAccessibleAt in class Container.AccessibleAWTContainer
Parameters:
p - The point relative to the coordinate system of this object.
Returns:
the Accessible, if it exists, at the specified location; otherwise null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JEditorPane.JEditorPaneAccessibleHypertextSupport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JEditorPane.JEditorPaneAccessibleHypertextSupport

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.text.JTextComponent.AccessibleJTextComponent
                        extended by  javax.swing.JEditorPane.AccessibleJEditorPane
                            extended by  javax.swing.JEditorPane.JEditorPaneAccessibleHypertextSupport
All Implemented Interfaces:
Serializable, EventListener, AccessibleAction, AccessibleComponent, AccessibleEditableText, AccessibleExtendedComponent, AccessibleExtendedText, AccessibleHypertext, AccessibleText, CaretListener, DocumentListener
Enclosing class:
JEditorPane
protected class JEditorPane.JEditorPaneAccessibleHypertextSupport
extends JEditorPane.AccessibleJEditorPane
implements AccessibleHypertext

What's returned by AccessibleJEditorPaneHTML.getAccessibleText. Provides support for AccessibleHypertext in case there is an HTML document being displayed in this JEditorPane.

Nested Class Summary
 class JEditorPane.JEditorPaneAccessibleHypertextSupport.HTMLLink
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Fields inherited from interface javax.accessibility.AccessibleExtendedText
ATTRIBUTE_RUN, LINE
Constructor Summary
JEditorPane.JEditorPaneAccessibleHypertextSupport()
Make one of these puppies
Method Summary
AccessibleHyperlink | getLink(int linkIndex) Returns the index into an array of hyperlinks that index.
int | getLinkCount() Returns the number of links within this hypertext doc.
int | getLinkIndex(int charIndex) Returns the index into an array of hyperlinks that is associated with this character index, or -1 if there is no hyperlink associated with this index.
String | getLinkText(int linkIndex) Returns the contiguous text within the document that is associated with this hyperlink.
Methods inherited from class javax.swing.JEditorPane.AccessibleJEditorPane
getAccessibleDescription, getAccessibleStateSet
Methods inherited from class javax.swing.text.JTextComponent.AccessibleJTextComponent
caretUpdate, changedUpdate, cut, delete, doAccessibleAction, getAccessibleAction, getAccessibleActionCount, getAccessibleActionDescription, getAccessibleEditableText, getAccessibleRole, getAccessibleText, getAfterIndex, getAtIndex, getBeforeIndex, getCaretPosition, getCharacterAttribute, getCharacterBounds, getCharCount, getIndexAtPoint, getSelectedText, getSelectionEnd, getSelectionStart, getTextBounds, getTextRange, getTextSequenceAfter, getTextSequenceAt, getTextSequenceBefore, insertTextAtIndex, insertUpdate, paste, removeUpdate, replaceText, selectText, setAttributes, setTextContents
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleKeyBinding, getAccessibleName, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleText
getAfterIndex, getAtIndex, getBeforeIndex, getCaretPosition, getCharacterAttribute, getCharacterBounds, getCharCount, getIndexAtPoint, getSelectedText, getSelectionEnd, getSelectionStart
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JEditorPane.JEditorPaneAccessibleHypertextSupport

public JEditorPane.JEditorPaneAccessibleHypertextSupport()
Make one of these puppies

Method Detail

getLinkCount

public int getLinkCount()
Returns the number of links within this hypertext doc.

Specified by:
getLinkCount in interface AccessibleHypertext
Returns:
number of links in this hypertext doc.

getLinkIndex

public int getLinkIndex(int charIndex)
Returns the index into an array of hyperlinks that is associated with this character index, or -1 if there is no hyperlink associated with this index.

Specified by:
getLinkIndex in interface AccessibleHypertext
Parameters:
charIndex - index within the text
Returns:
index into the set of hyperlinks for this hypertext doc.

getLink

public AccessibleHyperlink getLink(int linkIndex)
Returns the index into an array of hyperlinks that index. If there is no hyperlink at this index, it returns null.

Specified by:
getLink in interface AccessibleHypertext
Parameters:
linkIndex - into the set of hyperlinks for this hypertext doc.
Returns:
string representation of the hyperlink

getLinkText

public String getLinkText(int linkIndex)
Returns the contiguous text within the document that is associated with this hyperlink.

Parameters:
linkIndex - into the set of hyperlinks for this hypertext doc.
Returns:
the contiguous text sharing the link at this index
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JEditorPane.JEditorPaneAccessibleHypertextSupport.HTMLLink

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JEditorPane.JEditorPaneAccessibleHypertextSupport.HTMLLink

java.lang.Object
    extended by  javax.accessibility.AccessibleHyperlink
        extended by  javax.swing.JEditorPane.JEditorPaneAccessibleHypertextSupport.HTMLLink
All Implemented Interfaces:
AccessibleAction
Enclosing class:
JEditorPane.JEditorPaneAccessibleHypertextSupport
public class JEditorPane.JEditorPaneAccessibleHypertextSupport.HTMLLink
extends AccessibleHyperlink

Field Summary
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Constructor Summary
JEditorPane.JEditorPaneAccessibleHypertextSupport.HTMLLink(Element e)
Method Summary
boolean | doAccessibleAction(int i) Perform the specified Action on the object
Object | getAccessibleActionAnchor(int i) Return an object that represents the link anchor, as appropriate for that link.
int | getAccessibleActionCount() Returns the number of accessible actions available in this Link If there are more than one, the first one is NOT considered the "default" action of this LINK object (e.g.
String | getAccessibleActionDescription(int i) Return a String description of this particular link action.
Object | getAccessibleActionObject(int i) Returns a URL object that represents the link.
int | getEndIndex() Get the index with the hypertext document at which this link ends
int | getStartIndex() Get the index with the hypertext document at which this link begins
boolean | isValid() Since the document a link is associated with may have changed, this method returns whether this Link is valid anymore (with respect to the document it references).
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JEditorPane.JEditorPaneAccessibleHypertextSupport.HTMLLink

public JEditorPane.JEditorPaneAccessibleHypertextSupport.HTMLLink(Element e)
Method Detail

isValid

public boolean isValid()
Since the document a link is associated with may have changed, this method returns whether this Link is valid anymore (with respect to the document it references).

Specified by:
isValid in class AccessibleHyperlink
Returns:
a flag indicating whether this link is still valid with respect to the AccessibleHypertext it belongs to

getAccessibleActionCount

public int getAccessibleActionCount()
Returns the number of accessible actions available in this Link If there are more than one, the first one is NOT considered the "default" action of this LINK object (e.g. in an HTML imagemap). In general, links will have only one AccessibleAction in them.

Specified by:
getAccessibleActionCount in interface AccessibleAction
Specified by:
getAccessibleActionCount in class AccessibleHyperlink
Returns:
the zero-based number of Actions in this object

doAccessibleAction

public boolean doAccessibleAction(int i)
Perform the specified Action on the object

Specified by:
doAccessibleAction in interface AccessibleAction
Specified by:
doAccessibleAction in class AccessibleHyperlink
Parameters:
i - zero-based index of actions
Returns:
true if the the action was performed; else false.
See Also:
getAccessibleActionCount()

getAccessibleActionDescription

public String getAccessibleActionDescription(int i)
Return a String description of this particular link action. The string returned is the text within the document associated with the element which contains this link.

Specified by:
getAccessibleActionDescription in interface AccessibleAction
Specified by:
getAccessibleActionDescription in class AccessibleHyperlink
Parameters:
i - zero-based index of the actions
Returns:
a String description of the action
See Also:
getAccessibleActionCount()

getAccessibleActionObject

public Object getAccessibleActionObject(int i)
Returns a URL object that represents the link.

Specified by:
getAccessibleActionObject in class AccessibleHyperlink
Parameters:
i - zero-based index of the actions
Returns:
an URL representing the HTML link itself
See Also:
getAccessibleActionCount()

getAccessibleActionAnchor

public Object getAccessibleActionAnchor(int i)
Return an object that represents the link anchor, as appropriate for that link. E.g. from HTML: Accessibility this method would return a String containing the text: 'Accessibility'. Similarly, from this HTML: <a HREF="#top"><img src="top-hat.gif" alt="top hat"></a> this might return the object ImageIcon("top-hat.gif", "top hat");

Specified by:
getAccessibleActionAnchor in class AccessibleHyperlink
Parameters:
i - zero-based index of the actions
Returns:
an Object representing the hypertext anchor
See Also:
getAccessibleActionCount()

getStartIndex

public int getStartIndex()
Get the index with the hypertext document at which this link begins

Specified by:
getStartIndex in class AccessibleHyperlink
Returns:
index of start of link

getEndIndex

public int getEndIndex()
Get the index with the hypertext document at which this link ends

Specified by:
getEndIndex in class AccessibleHyperlink
Returns:
index of end of link
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JFileChooser

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JFileChooser

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JFileChooser
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public class JFileChooser
extends JComponent
implements Accessible

JFileChooser provides a simple mechanism for the user to choose a file. For information about using JFileChooser, see How to Use File Choosers, a section in The Java Tutorial.

The following code pops up a file chooser for the user's home directory that sees only .jpg and .gif images:

    JFileChooser chooser = new JFileChooser();
    FileNameExtensionFilter filter = new FileNameExtensionFilter(
        "JPG & GIF Images", "jpg", "gif");
    chooser.setFileFilter(filter);
    int returnVal = chooser.showOpenDialog(parent);
    if(returnVal == JFileChooser.APPROVE_OPTION) {
       System.out.println("You chose to open this file: " +
            chooser.getSelectedFile().getName());
    }

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Nested Class Summary
protected  class JFileChooser.AccessibleJFileChooser
This class implements accessibility support for the JFileChooser class.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
static String | ACCEPT_ALL_FILE_FILTER_USED_CHANGED_PROPERTY Identifies whether a the AcceptAllFileFilter is used or not.
protected AccessibleContext | accessibleContext
static String | ACCESSORY_CHANGED_PROPERTY Says that a different accessory component is in use (for example, to preview files).
static String | APPROVE_BUTTON_MNEMONIC_CHANGED_PROPERTY Identifies change in the mnemonic for the approve (yes, ok) button.
static String | APPROVE_BUTTON_TEXT_CHANGED_PROPERTY Identifies change in the text on the approve (yes, ok) button.
static String | APPROVE_BUTTON_TOOL_TIP_TEXT_CHANGED_PROPERTY Identifies change in the tooltip text for the approve (yes, ok) button.
static int | APPROVE_OPTION Return value if approve (yes, ok) is chosen.
static String | APPROVE_SELECTION Instruction to approve the current selection (same as pressing yes or ok).
static int | CANCEL_OPTION Return value if cancel is chosen.
static String | CANCEL_SELECTION Instruction to cancel the current selection.
static String | CHOOSABLE_FILE_FILTER_CHANGED_PROPERTY Identifies a change in the list of predefined file filters the user can choose from.
static String | CONTROL_BUTTONS_ARE_SHOWN_CHANGED_PROPERTY Instruction to display the control buttons.
static int | CUSTOM_DIALOG Type value indicating that the JFileChooser supports a developer-specified file operation.
static String | DIALOG_TITLE_CHANGED_PROPERTY Identifies a change in the dialog title.
static String | DIALOG_TYPE_CHANGED_PROPERTY Identifies a change in the type of files displayed (files only, directories only, or both files and directories).
static int | DIRECTORIES_ONLY Instruction to display only directories.
static String | DIRECTORY_CHANGED_PROPERTY Identifies user's directory change.
static int | ERROR_OPTION Return value if an error occured.
static String | FILE_FILTER_CHANGED_PROPERTY User changed the kind of files to display.
static String | FILE_HIDING_CHANGED_PROPERTY Identifies a change in the display-hidden-files property.
static String | FILE_SELECTION_MODE_CHANGED_PROPERTY Identifies a change in the kind of selection (single, multiple, etc.).
static String | FILE_SYSTEM_VIEW_CHANGED_PROPERTY Says that a different object is being used to find available drives on the system.
static String | FILE_VIEW_CHANGED_PROPERTY Says that a different object is being used to retrieve file information.
static int | FILES_AND_DIRECTORIES Instruction to display both files and directories.
static int | FILES_ONLY Instruction to display only files.
static String | MULTI_SELECTION_ENABLED_CHANGED_PROPERTY Enables multiple-file selections.
static int | OPEN_DIALOG Type value indicating that the JFileChooser supports an "Open" file operation.
static int | SAVE_DIALOG Type value indicating that the JFileChooser supports a "Save" file operation.
static String | SELECTED_FILE_CHANGED_PROPERTY Identifies change in user's single-file selection.
static String | SELECTED_FILES_CHANGED_PROPERTY Identifies change in user's multiple-file selection.
Fields inherited from class javax.swing.JComponent
listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JFileChooser()
Constructs a JFileChooser pointing to the user's default directory.
JFileChooser(File currentDirectory)
Constructs a JFileChooser using the given File as the path.
JFileChooser(File currentDirectory, FileSystemView fsv)
Constructs a JFileChooser using the given current directory and FileSystemView.
JFileChooser(FileSystemView fsv)
Constructs a JFileChooser using the given FileSystemView.
JFileChooser(String currentDirectoryPath)
Constructs a JFileChooser using the given path.
JFileChooser(String currentDirectoryPath, FileSystemView fsv)
Constructs a JFileChooser using the given current directory path and FileSystemView.
Method Summary
boolean | accept(File f) Returns true if the file should be displayed.
void | addActionListener(ActionListener l) Adds an ActionListener to the file chooser.
void | addChoosableFileFilter(FileFilter filter) Adds a filter to the list of user choosable file filters.
void | approveSelection() Called by the UI when the user hits the Approve button (labeled "Open" or "Save", by default).
void | cancelSelection() Called by the UI when the user chooses the Cancel button.
void | changeToParentDirectory() Changes the directory to be set to the parent of the current directory.
protected JDialog | createDialog(Component parent) Creates and returns a new JDialog wrapping this centered on the parent in the parent's frame.
void | ensureFileIsVisible(File f) Makes sure that the specified file is viewable, and not hidden.
protected void | fireActionPerformed(String command) Notifies all listeners that have registered interest for notification on this event type.
FileFilter | getAcceptAllFileFilter() Returns the AcceptAll file filter.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JFileChooser.
JComponent | getAccessory() Returns the accessory component.
ActionListener[] | getActionListeners() Returns an array of all the action listeners registered on this file chooser.
int | getApproveButtonMnemonic() Returns the approve button's mnemonic.
String | getApproveButtonText() Returns the text used in the ApproveButton in the FileChooserUI.
String | getApproveButtonToolTipText() Returns the tooltip text used in the ApproveButton.
FileFilter[] | getChoosableFileFilters() Gets the list of user choosable file filters.
boolean | getControlButtonsAreShown() Returns the value of the controlButtonsAreShown property.
File | getCurrentDirectory() Returns the current directory.
String | getDescription(File f) Returns the file description.
String | getDialogTitle() Gets the string that goes in the JFileChooser's titlebar.
int | getDialogType() Returns the type of this dialog.
boolean | getDragEnabled() Gets the value of the dragEnabled property.
FileFilter | getFileFilter() Returns the currently selected file filter.
int | getFileSelectionMode() Returns the current file-selection mode.
FileSystemView | getFileSystemView() Returns the file system view.
FileView | getFileView() Returns the current file view.
Icon | getIcon(File f) Returns the icon for this file or type of file, depending on the system.
String | getName(File f) Returns the filename.
File | getSelectedFile() Returns the selected file.
File[] | getSelectedFiles() Returns a list of selected files if the file chooser is set to allow multiple selection.
String | getTypeDescription(File f) Returns the file type.
FileChooserUI | getUI() Gets the UI object which implements the L&F for this component.
String | getUIClassID() Returns a string that specifies the name of the L&F class that renders this component.
boolean | isAcceptAllFileFilterUsed() Returns whether the AcceptAll FileFilter is used.
boolean | isDirectorySelectionEnabled() Convenience call that determines if directories are selectable based on the current file selection mode.
boolean | isFileHidingEnabled() Returns true if hidden files are not shown in the file chooser; otherwise, returns false.
boolean | isFileSelectionEnabled() Convenience call that determines if files are selectable based on the current file selection mode.
boolean | isMultiSelectionEnabled() Returns true if multiple files can be selected.
boolean | isTraversable(File f) Returns true if the file (directory) can be visited.
protected String | paramString() Returns a string representation of this JFileChooser.
void | removeActionListener(ActionListener l) Removes an ActionListener from the file chooser.
boolean | removeChoosableFileFilter(FileFilter f) Removes a filter from the list of user choosable file filters.
void | rescanCurrentDirectory() Tells the UI to rescan its files list from the current directory.
void | resetChoosableFileFilters() Resets the choosable file filter list to its starting state.
void | setAcceptAllFileFilterUsed(boolean b) Determines whether the AcceptAll FileFilter is used as an available choice in the choosable filter list.
void | setAccessory(JComponent newAccessory) Sets the accessory component.
void | setApproveButtonMnemonic(char mnemonic) Sets the approve button's mnemonic using a character.
void | setApproveButtonMnemonic(int mnemonic) Sets the approve button's mnemonic using a numeric keycode.
void | setApproveButtonText(String approveButtonText) Sets the text used in the ApproveButton in the FileChooserUI.
void | setApproveButtonToolTipText(String toolTipText) Sets the tooltip text used in the ApproveButton.
void | setControlButtonsAreShown(boolean b) Sets the property that indicates whether the approve and cancel buttons are shown in the file chooser.
void | setCurrentDirectory(File dir) Sets the current directory.
void | setDialogTitle(String dialogTitle) Sets the string that goes in the JFileChooser window's title bar.
void | setDialogType(int dialogType) Sets the type of this dialog.
void | setDragEnabled(boolean b) Sets the dragEnabled property, which must be true to enable automatic drag handling (the first part of drag and drop) on this component.
void | setFileFilter(FileFilter filter) Sets the current file filter.
void | setFileHidingEnabled(boolean b) Sets file hiding on or off.
void | setFileSelectionMode(int mode) Sets the JFileChooser to allow the user to just select files, just select directories, or select both files and directories.
void | setFileSystemView(FileSystemView fsv) Sets the file system view that the JFileChooser uses for accessing and creating file system resources, such as finding the floppy drive and getting a list of root drives.
void | setFileView(FileView fileView) Sets the file view to used to retrieve UI information, such as the icon that represents a file or the type description of a file.
void | setMultiSelectionEnabled(boolean b) Sets the file chooser to allow multiple file selections.
void | setSelectedFile(File file) Sets the selected file.
void | setSelectedFiles(File[] selectedFiles) Sets the list of selected files if the file chooser is set to allow multiple selection.
protected void | setup(FileSystemView view) Performs common constructor initialization and setup.
int | showDialog(Component parent, String approveButtonText) Pops a custom file chooser dialog with a custom approve button.
int | showOpenDialog(Component parent) Pops up an "Open File" file chooser dialog.
int | showSaveDialog(Component parent) Pops up a "Save File" file chooser dialog.
void | updateUI() Resets the UI property to a value from the current look and feel.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

OPEN_DIALOG

public static final int OPEN_DIALOG
Type value indicating that the JFileChooser supports an "Open" file operation.

See Also:
Constant Field Values

SAVE_DIALOG

public static final int SAVE_DIALOG
Type value indicating that the JFileChooser supports a "Save" file operation.

See Also:
Constant Field Values

CUSTOM_DIALOG

public static final int CUSTOM_DIALOG
Type value indicating that the JFileChooser supports a developer-specified file operation.

See Also:
Constant Field Values

CANCEL_OPTION

public static final int CANCEL_OPTION
Return value if cancel is chosen.

See Also:
Constant Field Values

APPROVE_OPTION

public static final int APPROVE_OPTION
Return value if approve (yes, ok) is chosen.

See Also:
Constant Field Values

ERROR_OPTION

public static final int ERROR_OPTION
Return value if an error occured.

See Also:
Constant Field Values

FILES_ONLY

public static final int FILES_ONLY
Instruction to display only files.

See Also:
Constant Field Values

DIRECTORIES_ONLY

public static final int DIRECTORIES_ONLY
Instruction to display only directories.

See Also:
Constant Field Values

FILES_AND_DIRECTORIES

public static final int FILES_AND_DIRECTORIES
Instruction to display both files and directories.

See Also:
Constant Field Values

CANCEL_SELECTION

public static final String CANCEL_SELECTION
Instruction to cancel the current selection.

See Also:
Constant Field Values

APPROVE_SELECTION

public static final String APPROVE_SELECTION
Instruction to approve the current selection (same as pressing yes or ok).

See Also:
Constant Field Values

APPROVE_BUTTON_TEXT_CHANGED_PROPERTY

public static final String APPROVE_BUTTON_TEXT_CHANGED_PROPERTY
Identifies change in the text on the approve (yes, ok) button.

See Also:
Constant Field Values

APPROVE_BUTTON_TOOL_TIP_TEXT_CHANGED_PROPERTY

public static final String APPROVE_BUTTON_TOOL_TIP_TEXT_CHANGED_PROPERTY
Identifies change in the tooltip text for the approve (yes, ok) button.

See Also:
Constant Field Values

APPROVE_BUTTON_MNEMONIC_CHANGED_PROPERTY

public static final String APPROVE_BUTTON_MNEMONIC_CHANGED_PROPERTY
Identifies change in the mnemonic for the approve (yes, ok) button.

See Also:
Constant Field Values

CONTROL_BUTTONS_ARE_SHOWN_CHANGED_PROPERTY

public static final String CONTROL_BUTTONS_ARE_SHOWN_CHANGED_PROPERTY
Instruction to display the control buttons.

See Also:
Constant Field Values

DIRECTORY_CHANGED_PROPERTY

public static final String DIRECTORY_CHANGED_PROPERTY
Identifies user's directory change.

See Also:
Constant Field Values

SELECTED_FILE_CHANGED_PROPERTY

public static final String SELECTED_FILE_CHANGED_PROPERTY
Identifies change in user's single-file selection.

See Also:
Constant Field Values

SELECTED_FILES_CHANGED_PROPERTY

public static final String SELECTED_FILES_CHANGED_PROPERTY
Identifies change in user's multiple-file selection.

See Also:
Constant Field Values

MULTI_SELECTION_ENABLED_CHANGED_PROPERTY

public static final String MULTI_SELECTION_ENABLED_CHANGED_PROPERTY
Enables multiple-file selections.

See Also:
Constant Field Values

FILE_SYSTEM_VIEW_CHANGED_PROPERTY

public static final String FILE_SYSTEM_VIEW_CHANGED_PROPERTY
Says that a different object is being used to find available drives on the system.

See Also:
Constant Field Values

FILE_VIEW_CHANGED_PROPERTY

public static final String FILE_VIEW_CHANGED_PROPERTY
Says that a different object is being used to retrieve file information.

See Also:
Constant Field Values

FILE_HIDING_CHANGED_PROPERTY

public static final String FILE_HIDING_CHANGED_PROPERTY
Identifies a change in the display-hidden-files property.

See Also:
Constant Field Values

FILE_FILTER_CHANGED_PROPERTY

public static final String FILE_FILTER_CHANGED_PROPERTY
User changed the kind of files to display.

See Also:
Constant Field Values

FILE_SELECTION_MODE_CHANGED_PROPERTY

public static final String FILE_SELECTION_MODE_CHANGED_PROPERTY
Identifies a change in the kind of selection (single, multiple, etc.).

See Also:
Constant Field Values

ACCESSORY_CHANGED_PROPERTY

public static final String ACCESSORY_CHANGED_PROPERTY
Says that a different accessory component is in use (for example, to preview files).

See Also:
Constant Field Values

ACCEPT_ALL_FILE_FILTER_USED_CHANGED_PROPERTY

public static final String ACCEPT_ALL_FILE_FILTER_USED_CHANGED_PROPERTY
Identifies whether a the AcceptAllFileFilter is used or not.

See Also:
Constant Field Values

DIALOG_TITLE_CHANGED_PROPERTY

public static final String DIALOG_TITLE_CHANGED_PROPERTY
Identifies a change in the dialog title.

See Also:
Constant Field Values

DIALOG_TYPE_CHANGED_PROPERTY

public static final String DIALOG_TYPE_CHANGED_PROPERTY
Identifies a change in the type of files displayed (files only, directories only, or both files and directories).

See Also:
Constant Field Values

CHOOSABLE_FILE_FILTER_CHANGED_PROPERTY

public static final String CHOOSABLE_FILE_FILTER_CHANGED_PROPERTY
Identifies a change in the list of predefined file filters the user can choose from.

See Also:
Constant Field Values

accessibleContext

protected AccessibleContext accessibleContext
Constructor Detail

JFileChooser

public JFileChooser()
Constructs a JFileChooser pointing to the user's default directory. This default depends on the operating system. It is typically the "My Documents" folder on Windows, and the user's home directory on Unix.

JFileChooser

public JFileChooser(String currentDirectoryPath)
Constructs a JFileChooser using the given path. Passing in a null string causes the file chooser to point to the user's default directory. This default depends on the operating system. It is typically the "My Documents" folder on Windows, and the user's home directory on Unix.

Parameters:
currentDirectoryPath - a String giving the path to a file or directory

JFileChooser

public JFileChooser(File currentDirectory)
Constructs a JFileChooser using the given File as the path. Passing in a null file causes the file chooser to point to the user's default directory. This default depends on the operating system. It is typically the "My Documents" folder on Windows, and the user's home directory on Unix.

Parameters:
currentDirectory - a File object specifying the path to a file or directory

JFileChooser

public JFileChooser(FileSystemView fsv)
Constructs a JFileChooser using the given FileSystemView.

JFileChooser

public JFileChooser(File currentDirectory,
                    FileSystemView fsv)
Constructs a JFileChooser using the given current directory and FileSystemView.

JFileChooser

public JFileChooser(String currentDirectoryPath,
                    FileSystemView fsv)
Constructs a JFileChooser using the given current directory path and FileSystemView.

Method Detail

setup

protected void setup(FileSystemView view)
Performs common constructor initialization and setup.

setDragEnabled

public void setDragEnabled(boolean b)
Sets the dragEnabled property, which must be true to enable automatic drag handling (the first part of drag and drop) on this component. The transferHandler property needs to be set to a non-null value for the drag to do anything. The default value of the dragEnabled property is false.

When automatic drag handling is enabled, most look and feels begin a drag-and-drop operation whenever the user presses the mouse button over an item and then moves the mouse a few pixels. Setting this property to true can therefore have a subtle effect on how selections behave.

Some look and feels might not support automatic drag and drop; they will ignore this property. You can work around such look and feels by modifying the component to directly call the exportAsDrag method of a TransferHandler.

Parameters:
b - the value to set the dragEnabled property to
Throws:
HeadlessException - if b is true and GraphicsEnvironment.isHeadless() returns true
Since:
1.4
See Also:
GraphicsEnvironment.isHeadless(),
getDragEnabled(),
JComponent.setTransferHandler(javax.swing.TransferHandler),
TransferHandler

getDragEnabled

public boolean getDragEnabled()
Gets the value of the dragEnabled property.

Returns:
the value of the dragEnabled property
Since:
1.4
See Also:
setDragEnabled(boolean)

getSelectedFile

public File getSelectedFile()
Returns the selected file. This can be set either by the programmer via setFile or by a user action, such as either typing the filename into the UI or selecting the file from a list in the UI.

Returns:
the selected file
See Also:
setSelectedFile(java.io.File)

setSelectedFile

public void setSelectedFile(File file)
Sets the selected file. If the file's parent directory is not the current directory, changes the current directory to be the file's parent directory.

Parameters:
file - the selected file
See Also:
getSelectedFile()

getSelectedFiles

public File[] getSelectedFiles()
Returns a list of selected files if the file chooser is set to allow multiple selection.

setSelectedFiles

public void setSelectedFiles(File[] selectedFiles)
Sets the list of selected files if the file chooser is set to allow multiple selection.

getCurrentDirectory

public File getCurrentDirectory()
Returns the current directory.

Returns:
the current directory
See Also:
setCurrentDirectory(java.io.File)

setCurrentDirectory

public void setCurrentDirectory(File dir)
Sets the current directory. Passing in null sets the file chooser to point to the user's default directory. This default depends on the operating system. It is typically the "My Documents" folder on Windows, and the user's home directory on Unix. If the file passed in as currentDirectory is not a directory, the parent of the file will be used as the currentDirectory. If the parent is not traversable, then it will walk up the parent tree until it finds a traversable directory, or hits the root of the file system.

Parameters:
dir - the current directory to point to
See Also:
getCurrentDirectory()

changeToParentDirectory

public void changeToParentDirectory()
Changes the directory to be set to the parent of the current directory.

See Also:
getCurrentDirectory()

rescanCurrentDirectory

public void rescanCurrentDirectory()
Tells the UI to rescan its files list from the current directory.

ensureFileIsVisible

public void ensureFileIsVisible(File f)
Makes sure that the specified file is viewable, and not hidden.

Parameters:
f - a File object

showOpenDialog

public int showOpenDialog(Component parent)
                   throws HeadlessException
Pops up an "Open File" file chooser dialog. Note that the text that appears in the approve button is determined by the L&F.

Parameters:
parent - the parent component of the dialog, can be null; see showDialog for details
Returns:
the return state of the file chooser on popdown:
  • JFileChooser.CANCEL_OPTION
  • JFileChooser.APPROVE_OPTION
  • JFileChooser.ERROR_OPTION if an error occurs or the dialog is dismissed
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
GraphicsEnvironment.isHeadless(), showDialog(java.awt.Component, java.lang.String)

showSaveDialog

public int showSaveDialog(Component parent)
                   throws HeadlessException
Pops up a "Save File" file chooser dialog. Note that the text that appears in the approve button is determined by the L&F.

Parameters:
parent - the parent component of the dialog, can be null; see showDialog for details
Returns:
the return state of the file chooser on popdown:
  • JFileChooser.CANCEL_OPTION
  • JFileChooser.APPROVE_OPTION
  • JFileChooser.ERROR_OPTION if an error occurs or the dialog is dismissed
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
GraphicsEnvironment.isHeadless(), showDialog(java.awt.Component, java.lang.String)

showDialog

public int showDialog(Component parent,
                      String approveButtonText)
               throws HeadlessException
Pops a custom file chooser dialog with a custom approve button. For example, the following code pops up a file chooser with a "Run Application" button (instead of the normal "Save" or "Open" button):
 filechooser.showDialog(parentFrame, "Run Application");
Alternatively, the following code does the same thing:
    JFileChooser chooser = new JFileChooser(null);
    chooser.setApproveButtonText("Run Application");
    chooser.showDialog(parentFrame, null);

The parent argument determines two things: the frame on which the open dialog depends and the component whose position the look and feel should consider when placing the dialog. If the parent is a Frame object (such as a JFrame) then the dialog depends on the frame and the look and feel positions the dialog relative to the frame (for example, centered over the frame). If the parent is a component, then the dialog depends on the frame containing the component, and is positioned relative to the component (for example, centered over the component). If the parent is null, then the dialog depends on no visible window, and it's placed in a look-and-feel-dependent position such as the center of the screen.

Parameters:
parent - the parent component of the dialog; can be null
approveButtonText - the text of the ApproveButton
Returns:
the return state of the file chooser on popdown:
  • JFileChooser.CANCEL_OPTION
  • JFileChooser.APPROVE_OPTION
  • JFileCHooser.ERROR_OPTION if an error occurs or the dialog is dismissed
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
GraphicsEnvironment.isHeadless()

createDialog

protected JDialog createDialog(Component parent)
                        throws HeadlessException
Creates and returns a new JDialog wrapping this centered on the parent in the parent's frame. This method can be overriden to further manipulate the dialog, to disable resizing, set the location, etc. Example:
     class MyFileChooser extends JFileChooser {
         protected JDialog createDialog(Component parent) throws HeadlessException {
             JDialog dialog = super.createDialog(parent);
             dialog.setLocation(300, 200);
             dialog.setResizable(false);
             return dialog;
         }
     }

Parameters:
parent - the parent component of the dialog; can be null
Returns:
a new JDialog containing this instance
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
Since:
1.4
See Also:
GraphicsEnvironment.isHeadless()

getControlButtonsAreShown

public boolean getControlButtonsAreShown()
Returns the value of the controlButtonsAreShown property.

Returns:
the value of the controlButtonsAreShown property
Since:
1.3
See Also:
setControlButtonsAreShown(boolean)

setControlButtonsAreShown

public void setControlButtonsAreShown(boolean b)
Sets the property that indicates whether the approve and cancel buttons are shown in the file chooser. This property is true by default. Look and feels that always show these buttons will ignore the value of this property. This method fires a property-changed event, using the string value of CONTROL_BUTTONS_ARE_SHOWN_CHANGED_PROPERTY as the name of the property.

Parameters:
b - false if control buttons should not be shown; otherwise, true
Since:
1.3
See Also:
getControlButtonsAreShown(), CONTROL_BUTTONS_ARE_SHOWN_CHANGED_PROPERTY

getDialogType

public int getDialogType()
Returns the type of this dialog. The default is JFileChooser.OPEN_DIALOG.

Returns:
the type of dialog to be displayed:
  • JFileChooser.OPEN_DIALOG
  • JFileChooser.SAVE_DIALOG
  • JFileChooser.CUSTOM_DIALOG
See Also:
setDialogType(int)

setDialogType

public void setDialogType(int dialogType)
Sets the type of this dialog. Use OPEN_DIALOG when you want to bring up a file chooser that the user can use to open a file. Likewise, use SAVE_DIALOG for letting the user choose a file for saving. Use CUSTOM_DIALOG when you want to use the file chooser in a context other than "Open" or "Save". For instance, you might want to bring up a file chooser that allows the user to choose a file to execute. Note that you normally would not need to set the JFileChooser to use CUSTOM_DIALOG since a call to setApproveButtonText does this for you. The default dialog type is JFileChooser.OPEN_DIALOG.

Parameters:
dialogType - the type of dialog to be displayed:
  • JFileChooser.OPEN_DIALOG
  • JFileChooser.SAVE_DIALOG
  • JFileChooser.CUSTOM_DIALOG
Throws:
IllegalArgumentException - if dialogType is not legal
See Also:
getDialogType(), setApproveButtonText(java.lang.String)

setDialogTitle

public void setDialogTitle(String dialogTitle)
Sets the string that goes in the JFileChooser window's title bar.

Parameters:
dialogTitle - the new String for the title bar
See Also:
getDialogTitle()

getDialogTitle

public String getDialogTitle()
Gets the string that goes in the JFileChooser's titlebar.

See Also:
setDialogTitle(java.lang.String)

setApproveButtonToolTipText

public void setApproveButtonToolTipText(String toolTipText)
Sets the tooltip text used in the ApproveButton. If null, the UI object will determine the button's text.

Parameters:
toolTipText - the tooltip text for the approve button
See Also:
setApproveButtonText(java.lang.String), setDialogType(int), showDialog(java.awt.Component, java.lang.String)

getApproveButtonToolTipText

public String getApproveButtonToolTipText()
Returns the tooltip text used in the ApproveButton. If null, the UI object will determine the button's text.

Returns:
the tooltip text used for the approve button
See Also:
setApproveButtonText(java.lang.String), setDialogType(int), showDialog(java.awt.Component, java.lang.String)

getApproveButtonMnemonic

public int getApproveButtonMnemonic()
Returns the approve button's mnemonic.

Returns:
an integer value for the mnemonic key
See Also:
setApproveButtonMnemonic(int)

setApproveButtonMnemonic

public void setApproveButtonMnemonic(int mnemonic)
Sets the approve button's mnemonic using a numeric keycode.

Parameters:
mnemonic - an integer value for the mnemonic key
See Also:
getApproveButtonMnemonic()

setApproveButtonMnemonic

public void setApproveButtonMnemonic(char mnemonic)
Sets the approve button's mnemonic using a character.

Parameters:
mnemonic - a character value for the mnemonic key
See Also:
getApproveButtonMnemonic()

setApproveButtonText

public void setApproveButtonText(String approveButtonText)
Sets the text used in the ApproveButton in the FileChooserUI.

Parameters:
approveButtonText - the text used in the ApproveButton
See Also:
getApproveButtonText(), setDialogType(int), showDialog(java.awt.Component, java.lang.String)

getApproveButtonText

public String getApproveButtonText()
Returns the text used in the ApproveButton in the FileChooserUI. If null, the UI object will determine the button's text. Typically, this would be "Open" or "Save".

Returns:
the text used in the ApproveButton
See Also:
setApproveButtonText(java.lang.String), setDialogType(int), showDialog(java.awt.Component, java.lang.String)

getChoosableFileFilters

public FileFilter[] getChoosableFileFilters()
Gets the list of user choosable file filters.

Returns:
a FileFilter array containing all the choosable file filters
See Also:
addChoosableFileFilter(javax.swing.filechooser.FileFilter),
removeChoosableFileFilter(javax.swing.filechooser.FileFilter),
resetChoosableFileFilters()

addChoosableFileFilter

public void addChoosableFileFilter(FileFilter filter)
Adds a filter to the list of user choosable file filters. For information on setting the file selection mode, see setFileSelectionMode.

Parameters:
filter - the FileFilter to add to the choosable file filter list
See Also:
getChoosableFileFilters(),
removeChoosableFileFilter(javax.swing.filechooser.FileFilter),
resetChoosableFileFilters(),
setFileSelectionMode(int)

removeChoosableFileFilter

public boolean removeChoosableFileFilter(FileFilter f)
Removes a filter from the list of user choosable file filters. Returns true if the file filter was removed.

See Also:
addChoosableFileFilter(javax.swing.filechooser.FileFilter),
getChoosableFileFilters(),
resetChoosableFileFilters()

resetChoosableFileFilters

public void resetChoosableFileFilters()
Resets the choosable file filter list to its starting state. Normally, this removes all added file filters while leaving the AcceptAll file filter.

See Also:
addChoosableFileFilter(javax.swing.filechooser.FileFilter),
getChoosableFileFilters(),
removeChoosableFileFilter(javax.swing.filechooser.FileFilter)

getAcceptAllFileFilter

public FileFilter getAcceptAllFileFilter()
Returns the AcceptAll file filter. For example, on Microsoft Windows this would be All Files (*.*).

isAcceptAllFileFilterUsed

public boolean isAcceptAllFileFilterUsed()
Returns whether the AcceptAll FileFilter is used.

Returns:
true if the AcceptAll FileFilter is used
Since:
1.3
See Also:
setAcceptAllFileFilterUsed(boolean)

setAcceptAllFileFilterUsed

public void setAcceptAllFileFilterUsed(boolean b)
Determines whether the AcceptAll FileFilter is used as an available choice in the choosable filter list. If false, the AcceptAll file filter is removed from the list of available file filters. If true, the AcceptAll file filter will become the the actively used file filter.

Since:
1.3
See Also:
isAcceptAllFileFilterUsed(),
getAcceptAllFileFilter(),
setFileFilter(javax.swing.filechooser.FileFilter)

getAccessory

public JComponent getAccessory()
Returns the accessory component.

Returns:
this JFileChooser's accessory component, or null
See Also:
setAccessory(javax.swing.JComponent)

setAccessory

public void setAccessory(JComponent newAccessory)
Sets the accessory component. An accessory is often used to show a preview image of the selected file; however, it can be used for anything that the programmer wishes, such as extra custom file chooser controls.

Note: if there was a previous accessory, you should unregister any listeners that the accessory might have registered with the file chooser.

setFileSelectionMode

public void setFileSelectionMode(int mode)
Sets the JFileChooser to allow the user to just select files, just select directories, or select both files and directories. The default is JFilesChooser.FILES_ONLY.

Parameters:
mode - the type of files to be displayed:
  • JFileChooser.FILES_ONLY
  • JFileChooser.DIRECTORIES_ONLY
  • JFileChooser.FILES_AND_DIRECTORIES
Throws:
IllegalArgumentException - if mode is an illegal file selection mode
See Also:
getFileSelectionMode()

getFileSelectionMode

public int getFileSelectionMode()
Returns the current file-selection mode. The default is JFilesChooser.FILES_ONLY.

Returns:
the type of files to be displayed, one of the following:
  • JFileChooser.FILES_ONLY
  • JFileChooser.DIRECTORIES_ONLY
  • JFileChooser.FILES_AND_DIRECTORIES
See Also:
setFileSelectionMode(int)

isFileSelectionEnabled

public boolean isFileSelectionEnabled()
Convenience call that determines if files are selectable based on the current file selection mode.

See Also:
setFileSelectionMode(int), getFileSelectionMode()

isDirectorySelectionEnabled

public boolean isDirectorySelectionEnabled()
Convenience call that determines if directories are selectable based on the current file selection mode.

See Also:
setFileSelectionMode(int), getFileSelectionMode()

setMultiSelectionEnabled

public void setMultiSelectionEnabled(boolean b)
Sets the file chooser to allow multiple file selections.

Parameters:
b - true if multiple files may be selected
See Also:
isMultiSelectionEnabled()

isMultiSelectionEnabled

public boolean isMultiSelectionEnabled()
Returns true if multiple files can be selected.

Returns:
true if multiple files can be selected
See Also:
setMultiSelectionEnabled(boolean)

isFileHidingEnabled

public boolean isFileHidingEnabled()
Returns true if hidden files are not shown in the file chooser; otherwise, returns false.

Returns:
the status of the file hiding property
See Also:
setFileHidingEnabled(boolean)

setFileHidingEnabled

public void setFileHidingEnabled(boolean b)
Sets file hiding on or off. If true, hidden files are not shown in the file chooser. The job of determining which files are shown is done by the FileView.

Parameters:
b - the boolean value that determines whether file hiding is turned on
See Also:
isFileHidingEnabled()

setFileFilter

public void setFileFilter(FileFilter filter)
Sets the current file filter. The file filter is used by the file chooser to filter out files from the user's view.

Parameters:
filter - the new current file filter to use
See Also:
getFileFilter()

getFileFilter

public FileFilter getFileFilter()
Returns the currently selected file filter.

Returns:
the current file filter
See Also:
setFileFilter(javax.swing.filechooser.FileFilter), addChoosableFileFilter(javax.swing.filechooser.FileFilter)

setFileView

public void setFileView(FileView fileView)
Sets the file view to used to retrieve UI information, such as the icon that represents a file or the type description of a file.

See Also:
getFileView()

getFileView

public FileView getFileView()
Returns the current file view.

See Also:
setFileView(javax.swing.filechooser.FileView)

getName

public String getName(File f)
Returns the filename.

Parameters:
f - the File
Returns:
the String containing the filename for f
See Also:
FileView.getName(java.io.File)

getDescription

public String getDescription(File f)
Returns the file description.

Parameters:
f - the File
Returns:
the String containing the file description for f
See Also:
FileView.getDescription(java.io.File)

getTypeDescription

public String getTypeDescription(File f)
Returns the file type.

Parameters:
f - the File
Returns:
the String containing the file type description for f
See Also:
FileView.getTypeDescription(java.io.File)

getIcon

public Icon getIcon(File f)
Returns the icon for this file or type of file, depending on the system.

Parameters:
f - the File
Returns:
the Icon for this file, or type of file
See Also:
FileView.getIcon(java.io.File)

isTraversable

public boolean isTraversable(File f)
Returns true if the file (directory) can be visited. Returns false if the directory cannot be traversed.

Parameters:
f - the File
Returns:
true if the file/directory can be traversed, otherwise false
See Also:
FileView.isTraversable(java.io.File)

accept

public boolean accept(File f)
Returns true if the file should be displayed.

Parameters:
f - the File
Returns:
true if the file should be displayed, otherwise false
See Also:
FileFilter.accept(java.io.File)

setFileSystemView

public void setFileSystemView(FileSystemView fsv)
Sets the file system view that the JFileChooser uses for accessing and creating file system resources, such as finding the floppy drive and getting a list of root drives.

Parameters:
fsv - the new FileSystemView
See Also:
FileSystemView

getFileSystemView

public FileSystemView getFileSystemView()
Returns the file system view.

Returns:
the FileSystemView object
See Also:
setFileSystemView(javax.swing.filechooser.FileSystemView)

approveSelection

public void approveSelection()
Called by the UI when the user hits the Approve button (labeled "Open" or "Save", by default). This can also be called by the programmer. This method causes an action event to fire with the command string equal to APPROVE_SELECTION.

See Also:
APPROVE_SELECTION

cancelSelection

public void cancelSelection()
Called by the UI when the user chooses the Cancel button. This can also be called by the programmer. This method causes an action event to fire with the command string equal to CANCEL_SELECTION.

See Also:
CANCEL_SELECTION

addActionListener

public void addActionListener(ActionListener l)
Adds an ActionListener to the file chooser.

Parameters:
l - the listener to be added
See Also:
approveSelection(), cancelSelection()

removeActionListener

public void removeActionListener(ActionListener l)
Removes an ActionListener from the file chooser.

Parameters:
l - the listener to be removed
See Also:
addActionListener(java.awt.event.ActionListener)

getActionListeners

public ActionListener[] getActionListeners()
Returns an array of all the action listeners registered on this file chooser.

Returns:
all of this file chooser's ActionListeners or an empty array if no action listeners are currently registered
Since:
1.4
See Also:
addActionListener(java.awt.event.ActionListener), removeActionListener(java.awt.event.ActionListener)

fireActionPerformed

protected void fireActionPerformed(String command)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the command parameter.

See Also:
EventListenerList

updateUI

public void updateUI()
Resets the UI property to a value from the current look and feel.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns a string that specifies the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "FileChooserUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

getUI

public FileChooserUI getUI()
Gets the UI object which implements the L&F for this component.

Returns:
the FileChooserUI object that implements the FileChooserUI L&F

paramString

protected String paramString()
Returns a string representation of this JFileChooser. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JFileChooser

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JFileChooser. For file choosers, the AccessibleContext takes the form of an AccessibleJFileChooser. A new AccessibleJFileChooser instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJFileChooser that serves as the AccessibleContext of this JFileChooser
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JFileChooser.AccessibleJFileChooser

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JFileChooser.AccessibleJFileChooser

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JFileChooser.AccessibleJFileChooser
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent
Enclosing class:
JFileChooser
protected class JFileChooser.AccessibleJFileChooser
extends JComponent.AccessibleJComponent

This class implements accessibility support for the JFileChooser class. It provides an implementation of the Java Accessibility API appropriate to file chooser user-interface elements.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JFileChooser.AccessibleJFileChooser()
Method Summary
 AccessibleRole getAccessibleRole()
Gets the role of this object.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JFileChooser.AccessibleJFileChooser

protected JFileChooser.AccessibleJFileChooser()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Gets the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JFormattedTextField

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JFormattedTextField

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.text.JTextComponent
                    extended by  javax.swing.JTextField
                        extended by  javax.swing.JFormattedTextField
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable, SwingConstants
public class JFormattedTextField
extends JTextField

JFormattedTextField extends JTextField adding support for formatting arbitrary values, as well as retrieving a particular object once the user has edited the text. The following illustrates configuring a JFormattedTextField to edit dates:

   JFormattedTextField ftf = new JFormattedTextField();
   ftf.setValue(new Date());

Once a JFormattedTextField has been created, you can listen for editing changes by way of adding a PropertyChangeListener and listening for PropertyChangeEvents with the property name value.

JFormattedTextField allows configuring what action should be taken when focus is lost. The possible configurations are:
Value | Description
JFormattedTextField.REVERT | Revert the display to match that of getValue, possibly losing the current edit.
JFormattedTextField.COMMIT | Commits the current value. If the value being edited isn't considered a legal value by the AbstractFormatter that is, a ParseException is thrown, then the value will not change, and then edited value will persist.
JFormattedTextField.COMMIT_OR_REVERT | Similar to COMMIT, but if the value isn't legal, behave like REVERT.
JFormattedTextField.PERSIST | Do nothing, don't obtain a new AbstractFormatter, and don't update the value.
The default is JFormattedTextField.COMMIT_OR_REVERT, refer to setFocusLostBehavior(int) for more information on this.

JFormattedTextField allows the focus to leave, even if the currently edited value is invalid. To lock the focus down while the JFormattedTextField is an invalid edit state you can attach an InputVerifier. The following code snippet shows a potential implementation of such an InputVerifier:

 public class FormattedTextFieldVerifier extends InputVerifier {
     public boolean verify(JComponent input) {
         if (input instanceof JFormattedTextField) {
             JFormattedTextField ftf = (JFormattedTextField)input;
             AbstractFormatter formatter = ftf.getFormatter();
             if (formatter != null) {
                 String text = ftf.getText();
                 try {
                      formatter.stringToValue(text);
                      return true;
                  } catch (ParseException pe) {
                      return false;
                  }
              }
          }
          return true;
      }
      public boolean shouldYieldFocus(JComponent input) {
          return verify(input);
      }
  }

Alternatively, you could invoke commitEdit, which would also commit the value.

JFormattedTextField does not do the formatting it self, rather formatting is done through an instance of JFormattedTextField.AbstractFormatter which is obtained from an instance of JFormattedTextField.AbstractFormatterFactory. Instances of JFormattedTextField.AbstractFormatter are notified when they become active by way of the install method, at which point the JFormattedTextField.AbstractFormatter can install whatever it needs to, typically a DocumentFilter. Similarly when JFormattedTextField no longer needs the AbstractFormatter, it will invoke uninstall.

JFormattedTextField typically queries the AbstractFormatterFactory for an AbstractFormat when it gains or loses focus. Although this can change based on the focus lost policy. If the focus lost policy is JFormattedTextField.PERSIST and the JFormattedTextField has been edited, the AbstractFormatterFactory will not be queried until the value has been commited. Similarly if the focus lost policy is JFormattedTextField.COMMIT and an exception is thrown from stringToValue, the AbstractFormatterFactory will not be querired when focus is lost or gained.

JFormattedTextField.AbstractFormatter is also responsible for determining when values are commited to the JFormattedTextField. Some JFormattedTextField.AbstractFormatters will make new values available on every edit, and others will never commit the value. You can force the current value to be obtained from the current JFormattedTextField.AbstractFormatter by way of invoking commitEdit. commitEdit will be invoked whenever return is pressed in the JFormattedTextField.

If an AbstractFormatterFactory has not been explicitly set, one will be set based on the Class of the value type after setValue has been invoked (assuming value is non-null). For example, in the following code an appropriate AbstractFormatterFactory and AbstractFormatter will be created to handle formatting of numbers:

   JFormattedTextField tf = new JFormattedTextField();
   tf.setValue(new Number(100));

Warning: As the AbstractFormatter will typically install a DocumentFilter on the Document, and a NavigationFilter on the JFormattedTextField you should not install your own. If you do, you are likely to see odd behavior in that the editing policy of the AbstractFormatter will not be enforced.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Since:
1.4

Nested Class Summary
static class | JFormattedTextField.AbstractFormatter Instances of AbstractFormatter are used by JFormattedTextField to handle the conversion both from an Object to a String, and back from a String to an Object.
static class | JFormattedTextField.AbstractFormatterFactory Instances of AbstractFormatterFactory are used by JFormattedTextField to obtain instances of AbstractFormatter which in turn are used to format values.
Nested classes/interfaces inherited from class javax.swing.JTextField
JTextField.AccessibleJTextField
Nested classes/interfaces inherited from class javax.swing.text.JTextComponent
JTextComponent.AccessibleJTextComponent, JTextComponent.DropLocation, JTextComponent.KeyBinding
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
static int | COMMIT Constant identifying that when focus is lost, commitEdit should be invoked.
static int | COMMIT_OR_REVERT Constant identifying that when focus is lost, commitEdit should be invoked.
static int | PERSIST Constant identifying that when focus is lost, the edited value should be left.
static int | REVERT Constant identifying that when focus is lost, editing value should be reverted to current value set on the JFormattedTextField.
Fields inherited from class javax.swing.JTextField
notifyAction
Fields inherited from class javax.swing.text.JTextComponent
DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JFormattedTextField()
Creates a JFormattedTextField with no AbstractFormatterFactory.
JFormattedTextField(Format format)
Creates a JFormattedTextField.
JFormattedTextField(JFormattedTextField.AbstractFormatter formatter)
Creates a JFormattedTextField with the specified AbstractFormatter.
JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory)
Creates a JFormattedTextField with the specified AbstractFormatterFactory.
JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory, Object currentValue)
Creates a JFormattedTextField with the specified AbstractFormatterFactory and initial value.
JFormattedTextField(Object value)
Creates a JFormattedTextField with the specified value.
Method Summary
void | commitEdit() Forces the current value to be taken from the AbstractFormatter and set as the current value.
Action[] | getActions() Fetches the command list for the editor.
int | getFocusLostBehavior() Returns the behavior when focus is lost.
JFormattedTextField.AbstractFormatter | getFormatter() Returns the AbstractFormatter that is used to format and parse the current value.
JFormattedTextField.AbstractFormatterFactory | getFormatterFactory() Returns the current AbstractFormatterFactory.
String | getUIClassID() Gets the class ID for a UI.
Object | getValue() Returns the last valid value.
protected void | invalidEdit() Invoked when the user inputs an invalid value.
boolean | isEditValid() Returns true if the current value being edited is valid.
protected void | processFocusEvent(FocusEvent e) Processes any focus events, such as FocusEvent.FOCUS_GAINED or FocusEvent.FOCUS_LOST.
protected void | processInputMethodEvent(InputMethodEvent e) Processes any input method events, such as InputMethodEvent.INPUT_METHOD_TEXT_CHANGED or InputMethodEvent.CARET_POSITION_CHANGED.
void | setDocument(Document doc) Associates the editor with a text document.
void | setFocusLostBehavior(int behavior) Sets the behavior when focus is lost.
protected void | setFormatter(JFormattedTextField.AbstractFormatter format) Sets the current AbstractFormatter.
void | setFormatterFactory(JFormattedTextField.AbstractFormatterFactory tf) Sets the AbstractFormatterFactory.
void | setValue(Object value) Sets the value that will be formatted by an AbstractFormatter obtained from the current AbstractFormatterFactory.
Methods inherited from class javax.swing.JTextField
actionPropertyChanged, addActionListener, configurePropertiesFromAction, createActionPropertyChangeListener, createDefaultModel, fireActionPerformed, getAccessibleContext, getAction, getActionListeners, getColumns, getColumnWidth, getHorizontalAlignment, getHorizontalVisibility, getPreferredSize, getScrollOffset, isValidateRoot, paramString, postActionEvent, removeActionListener, scrollRectToVisible, setAction, setActionCommand, setColumns, setFont, setHorizontalAlignment, setScrollOffset
Methods inherited from class javax.swing.text.JTextComponent
addCaretListener, addInputMethodListener, addKeymap, copy, cut, fireCaretUpdate, getCaret, getCaretColor, getCaretListeners, getCaretPosition, getDisabledTextColor, getDocument, getDragEnabled, getDropLocation, getDropMode, getFocusAccelerator, getHighlighter, getInputMethodRequests, getKeymap, getKeymap, getMargin, getNavigationFilter, getPreferredScrollableViewportSize, getPrintable, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getScrollableUnitIncrement, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getText, getToolTipText, getUI, isEditable, loadKeymap, modelToView, moveCaretPosition, paste, print, print, print, read, removeCaretListener, removeKeymap, removeNotify, replaceSelection, select, selectAll, setCaret, setCaretColor, setCaretPosition, setComponentOrientation, setDisabledTextColor, setDragEnabled, setDropMode, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, setUI, updateUI, viewToModel, write
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processHierarchyBoundsEvent, processHierarchyEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

COMMIT

public static final int COMMIT
Constant identifying that when focus is lost, commitEdit should be invoked. If in commiting the new value a ParseException is thrown, the invalid value will remain.

See Also:
setFocusLostBehavior(int), Constant Field Values

COMMIT_OR_REVERT

public static final int COMMIT_OR_REVERT
Constant identifying that when focus is lost, commitEdit should be invoked. If in commiting the new value a ParseException is thrown, the value will be reverted.

See Also:
setFocusLostBehavior(int), Constant Field Values

REVERT

public static final int REVERT
Constant identifying that when focus is lost, editing value should be reverted to current value set on the JFormattedTextField.

See Also:
setFocusLostBehavior(int), Constant Field Values

PERSIST

public static final int PERSIST
Constant identifying that when focus is lost, the edited value should be left.

See Also:
setFocusLostBehavior(int), Constant Field Values
Constructor Detail

JFormattedTextField

public JFormattedTextField()
Creates a JFormattedTextField with no AbstractFormatterFactory. Use setMask or setFormatterFactory to configure the JFormattedTextField to edit a particular type of value.

JFormattedTextField

public JFormattedTextField(Object value)
Creates a JFormattedTextField with the specified value. This will create an AbstractFormatterFactory based on the type of value.

Parameters:
value - Initial value for the JFormattedTextField

JFormattedTextField

public JFormattedTextField(Format format)
Creates a JFormattedTextField. format is wrapped in an appropriate AbstractFormatter which is then wrapped in an AbstractFormatterFactory.

Parameters:
format - Format used to look up an AbstractFormatter

JFormattedTextField

public JFormattedTextField(JFormattedTextField.AbstractFormatter formatter)
Creates a JFormattedTextField with the specified AbstractFormatter. The AbstractFormatter is placed in an AbstractFormatterFactory.

Parameters:
formatter - AbstractFormatter to use for formatting.

JFormattedTextField

public JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory)
Creates a JFormattedTextField with the specified AbstractFormatterFactory.

Parameters:
factory - AbstractFormatterFactory used for formatting.

JFormattedTextField

public JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory,
                           Object currentValue)
Creates a JFormattedTextField with the specified AbstractFormatterFactory and initial value.

Parameters:
factory - AbstractFormatterFactory used for formatting.
currentValue - Initial value to use
Method Detail

setFocusLostBehavior

public void setFocusLostBehavior(int behavior)
Sets the behavior when focus is lost. This will be one of JFormattedTextField.COMMIT_OR_REVERT, JFormattedTextField.REVERT, JFormattedTextField.COMMIT or JFormattedTextField.PERSIST Note that some AbstractFormatters may push changes as they occur, so that the value of this will have no effect.

This will throw an IllegalArgumentException if the object passed in is not one of the afore mentioned values.

The default value of this property is JFormattedTextField.COMMIT_OR_REVERT.

Parameters:
behavior - Identifies behavior when focus is lost
Throws:
IllegalArgumentException - if behavior is not one of the known values

getFocusLostBehavior

public int getFocusLostBehavior()
Returns the behavior when focus is lost. This will be one of COMMIT_OR_REVERT, COMMIT, REVERT or PERSIST Note that some AbstractFormatters may push changes as they occur, so that the value of this will have no effect.

Returns:
returns behavior when focus is lost

setFormatterFactory

public void setFormatterFactory(JFormattedTextField.AbstractFormatterFactory tf)
Sets the AbstractFormatterFactory. AbstractFormatterFactory is able to return an instance of AbstractFormatter that is used to format a value for display, as well an enforcing an editing policy.

If you have not explicitly set an AbstractFormatterFactory by way of this method (or a constructor) an AbstractFormatterFactory and consequently an AbstractFormatter will be used based on the Class of the value. NumberFormatter will be used for Numbers, DateFormatter will be used for Dates, otherwise DefaultFormatter will be used.

This is a JavaBeans bound property.

Parameters:
tf - AbstractFormatterFactory used to lookup instances of AbstractFormatter

getFormatterFactory

public JFormattedTextField.AbstractFormatterFactory getFormatterFactory()
Returns the current AbstractFormatterFactory.

Returns:
AbstractFormatterFactory used to determine AbstractFormatters
See Also:
setFormatterFactory(javax.swing.JFormattedTextField.AbstractFormatterFactory)

setFormatter

protected void setFormatter(JFormattedTextField.AbstractFormatter format)
Sets the current AbstractFormatter.

You should not normally invoke this, instead set the AbstractFormatterFactory or set the value. JFormattedTextField will invoke this as the state of the JFormattedTextField changes and requires the value to be reset. JFormattedTextField passes in the AbstractFormatter obtained from the AbstractFormatterFactory.

This is a JavaBeans bound property.

Parameters:
format - AbstractFormatter to use for formatting
See Also:
setFormatterFactory(javax.swing.JFormattedTextField.AbstractFormatterFactory)

getFormatter

public JFormattedTextField.AbstractFormatter getFormatter()
Returns the AbstractFormatter that is used to format and parse the current value.

Returns:
AbstractFormatter used for formatting

setValue

public void setValue(Object value)
Sets the value that will be formatted by an AbstractFormatter obtained from the current AbstractFormatterFactory. If no AbstractFormatterFactory has been specified, this will attempt to create one based on the type of value.

The default value of this property is null.

This is a JavaBeans bound property.

Parameters:
value - Current value to display

getValue

public Object getValue()
Returns the last valid value. Based on the editing policy of the AbstractFormatter this may not return the current value. The currently edited value can be obtained by invoking commitEdit followed by getValue.

Returns:
Last valid value

commitEdit

public void commitEdit()
                throws ParseException
Forces the current value to be taken from the AbstractFormatter and set as the current value. This has no effect if there is no current AbstractFormatter installed.

Throws:
ParseException - if the AbstractFormatter is not able to format the current value

isEditValid

public boolean isEditValid()
Returns true if the current value being edited is valid. The value of this is managed by the current AbstractFormatter, as such there is no public setter for it.

Returns:
true if the current value being edited is valid.

invalidEdit

protected void invalidEdit()
Invoked when the user inputs an invalid value. This gives the component a chance to provide feedback. The default implementation beeps.

processInputMethodEvent

protected void processInputMethodEvent(InputMethodEvent e)
Processes any input method events, such as InputMethodEvent.INPUT_METHOD_TEXT_CHANGED or InputMethodEvent.CARET_POSITION_CHANGED.

Overrides:
processInputMethodEvent in class JTextComponent
Parameters:
e - the InputMethodEvent
See Also:
InputMethodEvent

processFocusEvent

protected void processFocusEvent(FocusEvent e)
Processes any focus events, such as FocusEvent.FOCUS_GAINED or FocusEvent.FOCUS_LOST.

Overrides:
processFocusEvent in class Component
Parameters:
e - the FocusEvent
See Also:
FocusEvent

getActions

public Action[] getActions()
Fetches the command list for the editor. This is the list of commands supported by the plugged-in UI augmented by the collection of commands that the editor itself supports. These are useful for binding to events, such as in a keymap.

Overrides:
getActions in class JTextField
Returns:
the command list

getUIClassID

public String getUIClassID()
Gets the class ID for a UI.

Overrides:
getUIClassID in class JTextField
Returns:
the string "FormattedTextFieldUI"
See Also:
JComponent.getUIClassID()

setDocument

public void setDocument(Document doc)
Associates the editor with a text document. The currently registered factory is used to build a view for the document, which gets displayed by the editor after revalidation. A PropertyChange event ("document") is propagated to each listener.

Overrides:
setDocument in class JTextField
Parameters:
doc - the document to display/edit
See Also:
JTextComponent.getDocument()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JFormattedTextField.AbstractFormatter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JFormattedTextField.AbstractFormatter

java.lang.Object
    extended by  javax.swing.JFormattedTextField.AbstractFormatter
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
DefaultFormatter
Enclosing class:
JFormattedTextField
public abstract static class JFormattedTextField.AbstractFormatter
extends Object
implements Serializable

Instances of AbstractFormatter are used by JFormattedTextField to handle the conversion both from an Object to a String, and back from a String to an Object. AbstractFormatters can also enfore editing policies, or navigation policies, or manipulate the JFormattedTextField in any way it sees fit to enforce the desired policy.

An AbstractFormatter can only be active in one JFormattedTextField at a time. JFormattedTextField invokes install when it is ready to use it followed by uninstall when done. Subclasses that wish to install additional state should override install and message super appropriately.

Subclasses must override the conversion methods stringToValue and valueToString. Optionally they can override getActions, getNavigationFilter and getDocumentFilter to restrict the JFormattedTextField in a particular way.

Subclasses that allow the JFormattedTextField to be in a temporarily invalid state should invoke setEditValid at the appropriate times.

Since:
1.4

Constructor Summary
JFormattedTextField.AbstractFormatter()
Method Summary
protected Object | clone() Clones the AbstractFormatter.
protected Action[] | getActions() Subclass and override if you wish to provide a custom set of Actions.
protected DocumentFilter | getDocumentFilter() Subclass and override if you wish to provide a DocumentFilter to restrict what can be input.
protected JFormattedTextField | getFormattedTextField() Returns the current JFormattedTextField the AbstractFormatter is installed on.
protected NavigationFilter | getNavigationFilter() Subclass and override if you wish to provide a filter to restrict where the user can navigate to.
void | install(JFormattedTextField ftf) Installs the AbstractFormatter onto a particular JFormattedTextField.
protected void | invalidEdit() This should be invoked when the user types an invalid character.
protected void | setEditValid(boolean valid) Invoke this to update the editValid property of the JFormattedTextField.
abstract Object | stringToValue(String text) Parses text returning an arbitrary Object.
void | uninstall() Uninstalls any state the AbstractFormatter may have installed on the JFormattedTextField.
abstract String | valueToString(Object value) Returns the string value to display for value.
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JFormattedTextField.AbstractFormatter

public JFormattedTextField.AbstractFormatter()
Method Detail

install

public void install(JFormattedTextField ftf)
Installs the AbstractFormatter onto a particular JFormattedTextField. This will invoke valueToString to convert the current value from the JFormattedTextField to a String. This will then install the Actions from getActions, the DocumentFilter returned from getDocumentFilter and the NavigationFilter returned from getNavigationFilter onto the JFormattedTextField.

Subclasses will typically only need to override this if they wish to install additional listeners on the JFormattedTextField.

If there is a ParseException in converting the current value to a String, this will set the text to an empty String, and mark the JFormattedTextField as being in an invalid state.

While this is a public method, this is typically only useful for subclassers of JFormattedTextField. JFormattedTextField will invoke this method at the appropriate times when the value changes, or its internal state changes. You will only need to invoke this yourself if you are subclassing JFormattedTextField and installing/uninstalling AbstractFormatter at a different time than JFormattedTextField does.

Parameters:
ftf - JFormattedTextField to format for, may be null indicating uninstall from current JFormattedTextField.

uninstall

public void uninstall()
Uninstalls any state the AbstractFormatter may have installed on the JFormattedTextField. This resets the DocumentFilter, NavigationFilter and additional Actions installed on the JFormattedTextField.

stringToValue

public abstract Object stringToValue(String text)
                              throws ParseException
Parses text returning an arbitrary Object. Some formatters may return null.

Parameters:
text - String to convert
Returns:
Object representation of text
Throws:
ParseException - if there is an error in the conversion

valueToString

public abstract String valueToString(Object value)
                              throws ParseException
Returns the string value to display for value.

Parameters:
value - Value to convert
Returns:
String representation of value
Throws:
ParseException - if there is an error in the conversion

getFormattedTextField

protected JFormattedTextField getFormattedTextField()
Returns the current JFormattedTextField the AbstractFormatter is installed on.

Returns:
JFormattedTextField formatting for.

invalidEdit

protected void invalidEdit()
This should be invoked when the user types an invalid character. This forwards the call to the current JFormattedTextField.

setEditValid

protected void setEditValid(boolean valid)
Invoke this to update the editValid property of the JFormattedTextField. If you an enforce a policy such that the JFormattedTextField is always in a valid state, you will never need to invoke this.

Parameters:
valid - Valid state of the JFormattedTextField

getActions

protected Action[] getActions()
Subclass and override if you wish to provide a custom set of Actions. install will install these on the JFormattedTextField's ActionMap.

Returns:
Array of Actions to install on JFormattedTextField

getDocumentFilter

protected DocumentFilter getDocumentFilter()
Subclass and override if you wish to provide a DocumentFilter to restrict what can be input. install will install the returned value onto the JFormattedTextField.

Returns:
DocumentFilter to restrict edits

getNavigationFilter

protected NavigationFilter getNavigationFilter()
Subclass and override if you wish to provide a filter to restrict where the user can navigate to. install will install the returned value onto the JFormattedTextField.

Returns:
NavigationFilter to restrict navigation

clone

protected Object clone()
                throws CloneNotSupportedException
Clones the AbstractFormatter. The returned instance is not associated with a JFormattedTextField.

Overrides:
clone in class Object
Returns:
Copy of the AbstractFormatter
Throws:
CloneNotSupportedException - if the object's class does not support the Cloneable interface. Subclasses that override the clone method can also throw this exception to indicate that an instance cannot be cloned.
See Also:
Cloneable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JFormattedTextField.AbstractFormatterFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JFormattedTextField.AbstractFormatterFactory

java.lang.Object
    extended by  javax.swing.JFormattedTextField.AbstractFormatterFactory
Direct Known Subclasses:
DefaultFormatterFactory
Enclosing class:
JFormattedTextField
public abstract static class JFormattedTextField.AbstractFormatterFactory
extends Object

Instances of AbstractFormatterFactory are used by JFormattedTextField to obtain instances of AbstractFormatter which in turn are used to format values. AbstractFormatterFactory can return different AbstractFormatters based on the state of the JFormattedTextField, perhaps returning different AbstractFormatters when the JFormattedTextField has focus vs when it doesn't have focus.

Since:
1.4

Constructor Summary
JFormattedTextField.AbstractFormatterFactory()
Method Summary
abstract  JFormattedTextField.AbstractFormatter getFormatter(JFormattedTextField tf)
Returns an AbstractFormatter that can handle formatting of the passed in JFormattedTextField.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JFormattedTextField.AbstractFormatterFactory

public JFormattedTextField.AbstractFormatterFactory()
Method Detail

getFormatter

public abstract JFormattedTextField.AbstractFormatter getFormatter(JFormattedTextField tf)
Returns an AbstractFormatter that can handle formatting of the passed in JFormattedTextField.

Parameters:
tf - JFormattedTextField requesting AbstractFormatter
Returns:
AbstractFormatter to handle formatting duties, a null return value implies the JFormattedTextField should behave like a normal JTextField
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JFrame

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JFrame

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  java.awt.Window
                extended by  java.awt.Frame
                    extended by  javax.swing.JFrame
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, RootPaneContainer, WindowConstants
public class JFrame
extends Frame
implements WindowConstants, Accessible, RootPaneContainer

An extended version of java.awt.Frame that adds support for the JFC/Swing component architecture. You can find task-oriented documentation about using JFrame in The Java Tutorial, in the section How to Make Frames.

The JFrame class is slightly incompatible with Frame. Like all other JFC/Swing top-level containers, a JFrame contains a JRootPane as its only child. The content pane provided by the root pane should, as a rule, contain all the non-menu components displayed by the JFrame. This is different from the AWT Frame case. As a conveniance add and its variants, remove and setLayout have been overridden to forward to the contentPane as necessary. This means you can write:

       frame.add(child);
And the child will be added to the contentPane. The content pane will always be non-null. Attempting to set it to null will cause the JFrame to throw an exception. The default content pane will have a BorderLayout manager set on it. Refer to RootPaneContainer for details on adding, removing and setting the LayoutManager of a JFrame.

Unlike a Frame, a JFrame has some notion of how to respond when the user attempts to close the window. The default behavior is to simply hide the JFrame when the user closes the window. To change the default behavior, you invoke the method setDefaultCloseOperation(int). To make the JFrame behave the same as a Frame instance, use setDefaultCloseOperation(WindowConstants.DO_NOTHING_ON_CLOSE).

For more information on content panes and other features that root panes provide, see Using Top-Level Containers in The Java Tutorial.

In a multi-screen environment, you can create a JFrame on a different screen device. See Frame for more information.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JRootPane, setDefaultCloseOperation(int), WindowListener.windowClosing(java.awt.event.WindowEvent), RootPaneContainer

Nested Class Summary
protected  class JFrame.AccessibleJFrame
This class implements accessibility support for the JFrame class.
Nested classes/interfaces inherited from class java.awt.Frame
Frame.AccessibleAWTFrame
Nested classes/interfaces inherited from class java.awt.Window
Window.AccessibleAWTWindow
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected AccessibleContext | accessibleContext The accessible context property.
static int | EXIT_ON_CLOSE The exit application default window close operation.
protected JRootPane | rootPane The JRootPane instance that manages the contentPane and optional menuBar for this frame, as well as the glassPane.
protected boolean | rootPaneCheckingEnabled If true then calls to add and setLayout will be forwarded to the contentPane.
Fields inherited from class java.awt.Frame
CROSSHAIR_CURSOR, DEFAULT_CURSOR, E_RESIZE_CURSOR, HAND_CURSOR, ICONIFIED, MAXIMIZED_BOTH, MAXIMIZED_HORIZ, MAXIMIZED_VERT, MOVE_CURSOR, N_RESIZE_CURSOR, NE_RESIZE_CURSOR, NORMAL, NW_RESIZE_CURSOR, S_RESIZE_CURSOR, SE_RESIZE_CURSOR, SW_RESIZE_CURSOR, TEXT_CURSOR, W_RESIZE_CURSOR, WAIT_CURSOR
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.WindowConstants
DISPOSE_ON_CLOSE, DO_NOTHING_ON_CLOSE, HIDE_ON_CLOSE
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JFrame()
Constructs a new frame that is initially invisible.
JFrame(GraphicsConfiguration gc)
Creates a Frame in the specified GraphicsConfiguration of a screen device and a blank title.
JFrame(String title)
Creates a new, initially invisible Frame with the specified title.
JFrame(String title, GraphicsConfiguration gc)
Creates a JFrame with the specified title and the specified GraphicsConfiguration of a screen device.
Method Summary
protected void | addImpl(Component comp, Object constraints, int index) Adds the specified child Component.
protected JRootPane | createRootPane() Called by the constructor methods to create the default rootPane.
protected void | frameInit() Called by the constructors to init the JFrame properly.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JFrame.
Container | getContentPane() Returns the contentPane object for this frame.
int | getDefaultCloseOperation() Returns the operation that occurs when the user initiates a "close" on this frame.
Component | getGlassPane() Returns the glassPane object for this frame.
Graphics | getGraphics() Creates a graphics context for this component.
JMenuBar | getJMenuBar() Returns the menubar set on this frame.
JLayeredPane | getLayeredPane() Returns the layeredPane object for this frame.
JRootPane | getRootPane() Returns the rootPane object for this frame.
TransferHandler | getTransferHandler() Gets the transferHandler property.
static boolean | isDefaultLookAndFeelDecorated() Returns true if newly created JFrames should have their Window decorations provided by the current look and feel.
protected boolean | isRootPaneCheckingEnabled() Returns whether calls to add and setLayout are forwarded to the contentPane.
protected String | paramString() Returns a string representation of this JFrame.
protected void | processWindowEvent(WindowEvent e) Processes window events occurring on this component.
void | remove(Component comp) Removes the specified component from the container.
void | repaint(long time, int x, int y, int width, int height) Repaints the specified rectangle of this component within time milliseconds.
void | setContentPane(Container contentPane) Sets the contentPane property.
void | setDefaultCloseOperation(int operation) Sets the operation that will happen by default when the user initiates a "close" on this frame.
static void | setDefaultLookAndFeelDecorated(boolean defaultLookAndFeelDecorated) Provides a hint as to whether or not newly created JFrames should have their Window decorations (such as borders, widgets to close the window, title...) provided by the current look and feel.
void | setGlassPane(Component glassPane) Sets the glassPane property.
void | setIconImage(Image image) Sets the image to be displayed as the icon for this window.
void | setJMenuBar(JMenuBar menubar) Sets the menubar for this frame.
void | setLayeredPane(JLayeredPane layeredPane) Sets the layeredPane property.
void | setLayout(LayoutManager manager) Sets the LayoutManager.
protected void | setRootPane(JRootPane root) Sets the rootPane property.
protected void | setRootPaneCheckingEnabled(boolean enabled) Sets whether calls to add and setLayout are forwarded to the contentPane.
void | setTransferHandler(TransferHandler newHandler) Sets the transferHandler property, which is a mechanism to support transfer of data into this component.
void | update(Graphics g) Just calls paint(g).
Methods inherited from class java.awt.Frame
addNotify, getCursorType, getExtendedState, getFrames, getIconImage, getMaximizedBounds, getMenuBar, getState, getTitle, isResizable, isUndecorated, remove, removeNotify, setCursor, setExtendedState, setMaximizedBounds, setMenuBar, setResizable, setState, setTitle, setUndecorated
Methods inherited from class java.awt.Window
addPropertyChangeListener, addPropertyChangeListener, addWindowFocusListener, addWindowListener, addWindowStateListener, applyResourceBundle, applyResourceBundle, createBufferStrategy, createBufferStrategy, dispose, getBufferStrategy, getFocusableWindowState, getFocusCycleRootAncestor, getFocusOwner, getFocusTraversalKeys, getGraphicsConfiguration, getIconImages, getInputContext, getListeners, getLocale, getModalExclusionType, getMostRecentFocusOwner, getOwnedWindows, getOwner, getOwnerlessWindows, getToolkit, getWarningString, getWindowFocusListeners, getWindowListeners, getWindows, getWindowStateListeners, hide, isActive, isAlwaysOnTop, isAlwaysOnTopSupported, isFocusableWindow, isFocusCycleRoot, isFocused, isLocationByPlatform, isShowing, pack, postEvent, processEvent, processWindowFocusEvent, processWindowStateEvent, removeWindowFocusListener, removeWindowListener, removeWindowStateListener, reshape, setAlwaysOnTop, setBounds, setBounds, setCursor, setFocusableWindowState, setFocusCycleRoot, setIconImages, setLocationByPlatform, setLocationRelativeTo, setMinimumSize, setModalExclusionType, setSize, setSize, setVisible, show, toBack, toFront
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalPolicy, getInsets, getLayout, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paint, paintComponents, preferredSize, print, printComponents, processContainerEvent, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resize, resize, setBackground, setComponentOrientation, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setName, setPreferredSize, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.awt.MenuContainer
getFont, postEvent

Field Detail

EXIT_ON_CLOSE

public static final int EXIT_ON_CLOSE
The exit application default window close operation. If a window has this set as the close operation and is closed in an applet, a SecurityException may be thrown. It is recommended you only use this in an application.

Since:
1.3
See Also:
Constant Field Values

rootPane

protected JRootPane rootPane
The JRootPane instance that manages the contentPane and optional menuBar for this frame, as well as the glassPane.

See Also:
JRootPane, RootPaneContainer

rootPaneCheckingEnabled

protected boolean rootPaneCheckingEnabled
If true then calls to add and setLayout will be forwarded to the contentPane. This is initially false, but is set to true when the JFrame is constructed.

See Also:
isRootPaneCheckingEnabled(), setRootPaneCheckingEnabled(boolean), RootPaneContainer

accessibleContext

protected AccessibleContext accessibleContext
The accessible context property.

Constructor Detail

JFrame

public JFrame()
       throws HeadlessException
Constructs a new frame that is initially invisible.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
GraphicsEnvironment.isHeadless(),
Component.setSize(int, int),
Component.setVisible(boolean),
JComponent.getDefaultLocale()

JFrame

public JFrame(GraphicsConfiguration gc)
Creates a Frame in the specified GraphicsConfiguration of a screen device and a blank title.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
gc - the GraphicsConfiguration that is used to construct the new Frame; if gc is null, the system default GraphicsConfiguration is assumed
Throws:
IllegalArgumentException - if gc is not from a screen device. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true.
Since:
1.3
See Also:
GraphicsEnvironment.isHeadless(), JComponent.getDefaultLocale()

JFrame

public JFrame(String title)
       throws HeadlessException
Creates a new, initially invisible Frame with the specified title.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
title - the title for the frame
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
GraphicsEnvironment.isHeadless(),
Component.setSize(int, int),
Component.setVisible(boolean),
JComponent.getDefaultLocale()

JFrame

public JFrame(String title,
              GraphicsConfiguration gc)
Creates a JFrame with the specified title and the specified GraphicsConfiguration of a screen device.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
title - the title to be displayed in the frame's border. A null value is treated as an empty string, "".
gc - the GraphicsConfiguration that is used to construct the new JFrame with; if gc is null, the system default GraphicsConfiguration is assumed
Throws:
IllegalArgumentException - if gc is not from a screen device. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true.
Since:
1.3
See Also:
GraphicsEnvironment.isHeadless(), JComponent.getDefaultLocale()
Method Detail

frameInit

protected void frameInit()
Called by the constructors to init the JFrame properly.

createRootPane

protected JRootPane createRootPane()
Called by the constructor methods to create the default rootPane.

processWindowEvent

protected void processWindowEvent(WindowEvent e)
Processes window events occurring on this component. Hides the window or disposes of it, as specified by the setting of the defaultCloseOperation property.

Overrides:
processWindowEvent in class Window
Parameters:
e - the window event
See Also:
setDefaultCloseOperation(int), Window.processWindowEvent(java.awt.event.WindowEvent)

setDefaultCloseOperation

public void setDefaultCloseOperation(int operation)
Sets the operation that will happen by default when the user initiates a "close" on this frame. You must specify one of the following choices:

  • DO_NOTHING_ON_CLOSE (defined in WindowConstants): Don't do anything; require the program to handle the operation in the windowClosing method of a registered WindowListener object.
  • HIDE_ON_CLOSE (defined in WindowConstants): Automatically hide the frame after invoking any registered WindowListener objects.
  • DISPOSE_ON_CLOSE (defined in WindowConstants): Automatically hide and dispose the frame after invoking any registered WindowListener objects.
  • EXIT_ON_CLOSE (defined in JFrame): Exit the application using the System exit method. Use this only in applications.

The value is set to HIDE_ON_CLOSE by default. Changes to the value of this property cause the firing of a property change event, with property name "defaultCloseOperation".

Note: When the last displayable window within the Java virtual machine (VM) is disposed of, the VM may terminate. See AWT Threading Issues for more information.

Parameters:
operation - the operation which should be performed when the user closes the frame
Throws:
IllegalArgumentException - if defaultCloseOperation value isn't one of the above valid values
SecurityException - if EXIT_ON_CLOSE has been specified and the SecurityManager will not allow the caller to invoke System.exit
See Also:
Window.addWindowListener(java.awt.event.WindowListener), getDefaultCloseOperation(), WindowConstants, Runtime.exit(int)

getDefaultCloseOperation

public int getDefaultCloseOperation()
Returns the operation that occurs when the user initiates a "close" on this frame.

Returns:
an integer indicating the window-close operation
See Also:
setDefaultCloseOperation(int)

setTransferHandler

public void setTransferHandler(TransferHandler newHandler)
Sets the transferHandler property, which is a mechanism to support transfer of data into this component. Use null if the component does not support data transfer operations.

If the system property suppressSwingDropSupport is false (the default) and the current drop target on this component is either null or not a user-set drop target, this method will change the drop target as follows: If newHandler is null it will clear the drop target. If not null it will install a new DropTarget.

Note: When used with JFrame, TransferHandler only provides data import capability, as the data export related methods are currently typed to JComponent.

Please see How to Use Drag and Drop and Data Transfer, a section in The Java Tutorial, for more information.

Parameters:
newHandler - the new TransferHandler
Since:
1.6
See Also:
TransferHandler, getTransferHandler(), Component.setDropTarget(java.awt.dnd.DropTarget)

getTransferHandler

public TransferHandler getTransferHandler()
Gets the transferHandler property.

Returns:
the value of the transferHandler property
Since:
1.6
See Also:
TransferHandler, setTransferHandler(javax.swing.TransferHandler)

update

public void update(Graphics g)
Just calls paint(g). This method was overridden to prevent an unnecessary call to clear the background.

Overrides:
update in class Container
Parameters:
g - the Graphics context in which to paint
See Also:
Component.update(Graphics)

setJMenuBar

public void setJMenuBar(JMenuBar menubar)
Sets the menubar for this frame.

Parameters:
menubar - the menubar being placed in the frame
See Also:
getJMenuBar()

getJMenuBar

public JMenuBar getJMenuBar()
Returns the menubar set on this frame.

Returns:
the menubar for this frame
See Also:
setJMenuBar(javax.swing.JMenuBar)

isRootPaneCheckingEnabled

protected boolean isRootPaneCheckingEnabled()
Returns whether calls to add and setLayout are forwarded to the contentPane.

Returns:
true if add and setLayout are fowarded; false otherwise
See Also:
addImpl(java.awt.Component, java.lang.Object, int), setLayout(java.awt.LayoutManager), setRootPaneCheckingEnabled(boolean), RootPaneContainer

setRootPaneCheckingEnabled

protected void setRootPaneCheckingEnabled(boolean enabled)
Sets whether calls to add and setLayout are forwarded to the contentPane.

Parameters:
enabled - true if add and setLayout are forwarded, false if they should operate directly on the JFrame.
See Also:
addImpl(java.awt.Component, java.lang.Object, int),
setLayout(java.awt.LayoutManager),
isRootPaneCheckingEnabled(),
RootPaneContainer

addImpl

protected void addImpl(Component comp,
                       Object constraints,
                       int index)
Adds the specified child Component. This method is overridden to conditionally forward calls to the contentPane. By default, children are added to the contentPane instead of the frame, refer to RootPaneContainer for details.

Overrides:
addImpl in class Container
Parameters:
comp - the component to be enhanced
constraints - the constraints to be respected
index - the index
Throws:
IllegalArgumentException - if index is invalid
IllegalArgumentException - if adding the container's parent to itself
IllegalArgumentException - if adding a window to a container
See Also:
setRootPaneCheckingEnabled(boolean), RootPaneContainer

remove

public void remove(Component comp)
Removes the specified component from the container. If comp is not the rootPane, this will forward the call to the contentPane. This will do nothing if comp is not a child of the JFrame or contentPane.

Overrides:
remove in class Container
Parameters:
comp - the component to be removed
Throws:
NullPointerException - if comp is null
See Also:
Container.add(java.awt.Component), RootPaneContainer

setLayout

public void setLayout(LayoutManager manager)
Sets the LayoutManager. Overridden to conditionally forward the call to the contentPane. Refer to RootPaneContainer for more information.

Overrides:
setLayout in class Container
Parameters:
manager - the LayoutManager
See Also:
setRootPaneCheckingEnabled(boolean), RootPaneContainer

getRootPane

public JRootPane getRootPane()
Returns the rootPane object for this frame.

Specified by:
getRootPane in interface RootPaneContainer
Returns:
the rootPane property
See Also:
setRootPane(javax.swing.JRootPane), RootPaneContainer.getRootPane()

setRootPane

protected void setRootPane(JRootPane root)
Sets the rootPane property. This method is called by the constructor.

Parameters:
root - the rootPane object for this frame
See Also:
getRootPane()

setIconImage

public void setIconImage(Image image)
Sets the image to be displayed as the icon for this window.

This method can be used instead of setIconImages() to specify a single image as a window's icon.

The following statement:

     setIconImage(image);
is equivalent to:
     ArrayList   imageList = new ArrayList  ();
     imageList.add(image);
     setIconImages(imageList);

Note : Native windowing systems may use different images of differing dimensions to represent a window, depending on the context (e.g. window decoration, window list, taskbar, etc.). They could also use just a single image for all contexts or no image at all.

Overrides:
setIconImage in class Frame
Parameters:
image - the icon image to be displayed.
See Also:
Window.setIconImages(java.util.List), Window.getIconImages()

getContentPane

public Container getContentPane()
Returns the contentPane object for this frame.

Specified by:
getContentPane in interface RootPaneContainer
Returns:
the contentPane property
See Also:
setContentPane(java.awt.Container), RootPaneContainer.getContentPane()

setContentPane

public void setContentPane(Container contentPane)
Sets the contentPane property. This method is called by the constructor.

Swing's painting architecture requires an opaque JComponent in the containment hiearchy. This is typically provided by the content pane. If you replace the content pane it is recommended you replace it with an opaque JComponent.

Specified by:
setContentPane in interface RootPaneContainer
Parameters:
contentPane - the contentPane object for this frame
Throws:
IllegalComponentStateException - (a runtime exception) if the content pane parameter is null
See Also:
getContentPane(), RootPaneContainer.setContentPane(java.awt.Container), JRootPane

getLayeredPane

public JLayeredPane getLayeredPane()
Returns the layeredPane object for this frame.

Specified by:
getLayeredPane in interface RootPaneContainer
Returns:
the layeredPane property
See Also:
setLayeredPane(javax.swing.JLayeredPane), RootPaneContainer.getLayeredPane()

setLayeredPane

public void setLayeredPane(JLayeredPane layeredPane)
Sets the layeredPane property. This method is called by the constructor.

Specified by:
setLayeredPane in interface RootPaneContainer
Parameters:
layeredPane - the layeredPane object for this frame
Throws:
IllegalComponentStateException - (a runtime exception) if the layered pane parameter is null
See Also:
getLayeredPane(), RootPaneContainer.setLayeredPane(javax.swing.JLayeredPane)

getGlassPane

public Component getGlassPane()
Returns the glassPane object for this frame.

Specified by:
getGlassPane in interface RootPaneContainer
Returns:
the glassPane property
See Also:
setGlassPane(java.awt.Component), RootPaneContainer.getGlassPane()

setGlassPane

public void setGlassPane(Component glassPane)
Sets the glassPane property. This method is called by the constructor.

Specified by:
setGlassPane in interface RootPaneContainer
Parameters:
glassPane - the glassPane object for this frame
See Also:
getGlassPane(), RootPaneContainer.setGlassPane(java.awt.Component)

getGraphics

public Graphics getGraphics()
Creates a graphics context for this component. This method will return null if this component is currently not displayable.

Overrides:
getGraphics in class Component
Returns:
a graphics context for this component, or null if it has none
Since:
1.6
See Also:
Component.paint(java.awt.Graphics)

repaint

public void repaint(long time,
                    int x,
                    int y,
                    int width,
                    int height)
Repaints the specified rectangle of this component within time milliseconds. Refer to RepaintManager for details on how the repaint is handled.

Overrides:
repaint in class Component
Parameters:
time - maximum time in milliseconds before update
x - the x coordinate
y - the y coordinate
width - the width
height - the height
Since:
1.6
See Also:
RepaintManager

setDefaultLookAndFeelDecorated

public static void setDefaultLookAndFeelDecorated(boolean defaultLookAndFeelDecorated)
Provides a hint as to whether or not newly created JFrames should have their Window decorations (such as borders, widgets to close the window, title...) provided by the current look and feel. If defaultLookAndFeelDecorated is true, the current LookAndFeel supports providing window decorations, and the current window manager supports undecorated windows, then newly created JFrames will have their Window decorations provided by the current LookAndFeel. Otherwise, newly created JFrames will have their Window decorations provided by the current window manager.

You can get the same effect on a single JFrame by doing the following:

    JFrame frame = new JFrame();
    frame.setUndecorated(true);
    frame.getRootPane().setWindowDecorationStyle(JRootPane.FRAME);

Parameters:
defaultLookAndFeelDecorated - A hint as to whether or not current look and feel should provide window decorations
Since:
1.4
See Also:
LookAndFeel.getSupportsWindowDecorations()

isDefaultLookAndFeelDecorated

public static boolean isDefaultLookAndFeelDecorated()
Returns true if newly created JFrames should have their Window decorations provided by the current look and feel. This is only a hint, as certain look and feels may not support this feature.

Returns:
true if look and feel should provide Window decorations.
Since:
1.4

paramString

protected String paramString()
Returns a string representation of this JFrame. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class Frame
Returns:
a string representation of this JFrame

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JFrame. For JFrames, the AccessibleContext takes the form of an AccessibleJFrame. A new AccessibleJFrame instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class Frame
Returns:
an AccessibleJFrame that serves as the AccessibleContext of this JFrame
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JFrame.AccessibleJFrame

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JFrame.AccessibleJFrame

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  java.awt.Window.AccessibleAWTWindow
                    extended by  java.awt.Frame.AccessibleAWTFrame
                        extended by  javax.swing.JFrame.AccessibleJFrame
All Implemented Interfaces:
Serializable, AccessibleComponent
Enclosing class:
JFrame
protected class JFrame.AccessibleJFrame
extends Frame.AccessibleAWTFrame

This class implements accessibility support for the JFrame class. It provides an implementation of the Java Accessibility API appropriate to frame user-interface elements.

Nested Class Summary
Nested classes/interfaces inherited from class java.awt.Container.AccessibleAWTContainer
Container.AccessibleAWTContainer.AccessibleContainerHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class java.awt.Container.AccessibleAWTContainer
accessibleContainerHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JFrame.AccessibleJFrame()
Method Summary
String | getAccessibleName() Get the accessible name of this object.
AccessibleStateSet | getAccessibleStateSet() Get the state of this object.
Methods inherited from class java.awt.Frame.AccessibleAWTFrame
getAccessibleRole
Methods inherited from class java.awt.Container.AccessibleAWTContainer
addPropertyChangeListener, getAccessibleAt, getAccessibleChild, getAccessibleChildrenCount
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleDescription, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, removePropertyChangeListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JFrame.AccessibleJFrame

protected JFrame.AccessibleJFrame()
Method Detail

getAccessibleName

public String getAccessibleName()
Get the accessible name of this object.

Overrides:
getAccessibleName in class Component.AccessibleAWTComponent
Returns:
the localized name of the object -- can be null if this object does not have a name
See Also:
AccessibleContext.setAccessibleName(java.lang.String)

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Get the state of this object.

Overrides:
getAccessibleStateSet in class Frame.AccessibleAWTFrame
Returns:
an instance of AccessibleStateSet containing the current state set of the object
See Also:
AccessibleState
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JInternalFrame

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JInternalFrame

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JInternalFrame
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, RootPaneContainer, WindowConstants
public class JInternalFrame
extends JComponent
implements Accessible, WindowConstants, RootPaneContainer

A lightweight object that provides many of the features of a native frame, including dragging, closing, becoming an icon, resizing, title display, and support for a menu bar. For task-oriented documentation and examples of using internal frames, see How to Use Internal Frames, a section in The Java Tutorial.

Generally, you add JInternalFrames to a JDesktopPane. The UI delegates the look-and-feel-specific actions to the DesktopManager object maintained by the JDesktopPane.

The JInternalFrame content pane is where you add child components. As a conveniance add and its variants, remove and setLayout have been overridden to forward to the contentPane as necessary. This means you can write:

       internalFrame.add(child);
And the child will be added to the contentPane. The content pane is actually managed by an instance of JRootPane, which also manages a layout pane, glass pane, and optional menu bar for the internal frame. Please see the JRootPane documentation for a complete description of these components. Refer to RootPaneContainer for details on adding, removing and setting the LayoutManager of a JInternalFrame.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
InternalFrameEvent, JDesktopPane, DesktopManager, JInternalFrame.JDesktopIcon, JRootPane, RootPaneContainer

Nested Class Summary
protected class | JInternalFrame.AccessibleJInternalFrame This class implements accessibility support for the JInternalFrame class.
static class | JInternalFrame.JDesktopIcon This component represents an iconified version of a JInternalFrame.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected boolean | closable The frame can be closed.
static String | CONTENT_PANE_PROPERTY Bound property name.
protected JInternalFrame.JDesktopIcon | desktopIcon The icon that is displayed when this internal frame is iconified.
static String | FRAME_ICON_PROPERTY Bound property name.
protected Icon | frameIcon The icon shown in the top-left corner of this internal frame.
static String | GLASS_PANE_PROPERTY Bound property name.
protected boolean | iconable The frame can "iconified" (shrunk down and displayed as an icon-image).
static String | IS_CLOSED_PROPERTY Constrained property name indicating that the internal frame is closed.
static String | IS_ICON_PROPERTY Constrained property name indicating that the internal frame is iconified.
static String | IS_MAXIMUM_PROPERTY Constrained property name indicating that the internal frame is maximized.
static String | IS_SELECTED_PROPERTY Constrained property name indicated that this frame has selected status.
protected boolean | isClosed The frame has been closed.
protected boolean | isIcon The frame has been iconified.
protected boolean | isMaximum The frame has been expanded to its maximum size.
protected boolean | isSelected The frame is currently selected.
static String | LAYERED_PANE_PROPERTY Bound property name.
protected boolean | maximizable The frame can be expanded to the size of the desktop pane.
static String | MENU_BAR_PROPERTY Bound property name.
protected boolean | resizable The frame's size can be changed.
static String | ROOT_PANE_PROPERTY Bound property name.
protected JRootPane | rootPane The JRootPane instance that manages the content pane and optional menu bar for this internal frame, as well as the glass pane.
protected boolean | rootPaneCheckingEnabled If true then calls to add and setLayout will be forwarded to the contentPane.
protected String | title The title displayed in this internal frame's title bar.
static String | TITLE_PROPERTY Bound property name.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.WindowConstants
DISPOSE_ON_CLOSE, DO_NOTHING_ON_CLOSE, EXIT_ON_CLOSE, HIDE_ON_CLOSE
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JInternalFrame()
Creates a non-resizable, non-closable, non-maximizable, non-iconifiable JInternalFrame with no title.
JInternalFrame(String title)
Creates a non-resizable, non-closable, non-maximizable, non-iconifiable JInternalFrame with the specified title.
JInternalFrame(String title, boolean resizable)
Creates a non-closable, non-maximizable, non-iconifiable JInternalFrame with the specified title and resizability.
JInternalFrame(String title, boolean resizable, boolean closable)
Creates a non-maximizable, non-iconifiable JInternalFrame with the specified title, resizability, and closability.
JInternalFrame(String title, boolean resizable, boolean closable, boolean maximizable)
Creates a non-iconifiable JInternalFrame with the specified title, resizability, closability, and maximizability.
JInternalFrame(String title, boolean resizable, boolean closable, boolean maximizable, boolean iconifiable)
Creates a JInternalFrame with the specified title, resizability, closability, maximizability, and iconifiability.
Method Summary
protected  void addImpl(Component comp, Object constraints, int index)
Adds the specified child Component.
 void addInternalFrameListener(InternalFrameListener l)
Adds the specified listener to receive internal frame events from this internal frame.
protected  JRootPane createRootPane()
Called by the constructor to set up the JRootPane.
 void dispose()
Makes this internal frame invisible, unselected, and closed.
 void doDefaultCloseAction()
Fires an INTERNAL_FRAME_CLOSING event and then performs the action specified by the internal frame's default close operation.
protected  void fireInternalFrameEvent(int id)
Fires an internal frame event.
 AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JInternalFrame.
 Container getContentPane()
Returns the content pane for this internal frame.
 int getDefaultCloseOperation()
Returns the default operation that occurs when the user initiates a "close" on this internal frame.
 JInternalFrame.JDesktopIcon getDesktopIcon()
Returns the JDesktopIcon used when this JInternalFrame is iconified.
 JDesktopPane getDesktopPane()
Convenience method that searches the ancestor hierarchy for a JDesktop instance.
 Container getFocusCycleRootAncestor()
Always returns null because JInternalFrames must always be roots of a focus traversal cycle.
 Component getFocusOwner()
If this JInternalFrame is active, returns the child that has focus.
 Icon getFrameIcon()
Returns the image displayed in the title bar of this internal frame (usually in the top-left corner).
 Component getGlassPane()
Returns the glass pane for this internal frame.
 InternalFrameListener[] getInternalFrameListeners()
Returns an array of all the InternalFrameListeners added to this JInternalFrame with addInternalFrameListener.
 JMenuBar getJMenuBar()
Returns the current JMenuBar for this JInternalFrame, or null if no menu bar has been set.
 Cursor getLastCursor()
Returns the last Cursor that was set by the setCursor method that is not a resizable Cursor.
 int getLayer()
Convenience method for getting the layer attribute of this component.
 JLayeredPane getLayeredPane()
Returns the layered pane for this internal frame.
 JMenuBar getMenuBar()
Deprecated. As of Swing version 1.0.3, replaced by getJMenuBar().
 Component getMostRecentFocusOwner()
Returns the child component of this JInternalFrame that will receive the focus when this JInternalFrame is selected.
 Rectangle getNormalBounds()
If the JInternalFrame is not in maximized state, returns getBounds(); otherwise, returns the bounds that the JInternalFrame would be restored to.
 JRootPane getRootPane()
Returns the rootPane object for this internal frame.
 String getTitle()
Returns the title of the JInternalFrame.
 InternalFrameUI getUI()
Returns the look-and-feel object that renders this component.
 String getUIClassID()
Returns the name of the look-and-feel class that renders this component.
 String getWarningString()
Gets the warning string that is displayed with this internal frame.
 void hide()
 boolean isClosable()
Returns whether this JInternalFrame can be closed by some user action.
 boolean isClosed()
Returns whether this JInternalFrame is currently closed.
 boolean isFocusCycleRoot()
Always returns true because all JInternalFrames must be roots of a focus traversal cycle.
 boolean isIcon()
Returns whether the JInternalFrame is currently iconified.
 boolean isIconifiable()
Gets the iconable property, which by default is false.
 boolean isMaximizable()
Gets the value of the maximizable property.
 boolean isMaximum()
Returns whether the JInternalFrame is currently maximized.
 boolean isResizable()
Returns whether the JInternalFrame can be resized by some user action.
protected  boolean isRootPaneCheckingEnabled()
Returns whether calls to add and setLayout are forwarded to the contentPane.
 boolean isSelected()
Returns whether the JInternalFrame is the currently "selected" or active frame.
 void moveToBack()
Convenience method that moves this component to position -1 if its parent is a JLayeredPane.
 void moveToFront()
Convenience method that moves this component to position 0 if its parent is a JLayeredPane.
 void pack()
Causes subcomponents of this JInternalFrame to be laid out at their preferred size.
protected  void paintComponent(Graphics g)
Overridden to allow optimized painting when the internal frame is being dragged.
protected  String paramString()
Returns a string representation of this JInternalFrame.
 void remove(Component comp)
Removes the specified component from the container.
 void removeInternalFrameListener(InternalFrameListener l)
Removes the specified internal frame listener so that it no longer receives internal frame events from this internal frame.
 void reshape(int x, int y, int width, int height)
Moves and resizes this component.
 void restoreSubcomponentFocus()
Requests the internal frame to restore focus to the last subcomponent that had focus.
 void setClosable(boolean b)
Sets whether this JInternalFrame can be closed by some user action.
 void setClosed(boolean b)
Closes this internal frame if the argument is true.
 void setContentPane(Container c)
Sets this JInternalFrame's contentPane property.
 void setCursor(Cursor cursor)
Sets the cursor image to the specified cursor.
 void setDefaultCloseOperation(int operation)
Sets the operation that will happen by default when the user initiates a "close" on this internal frame.
 void setDesktopIcon(JInternalFrame.JDesktopIcon d)
Sets the JDesktopIcon associated with this JInternalFrame.
 void setFocusCycleRoot(boolean focusCycleRoot)
Does nothing because JInternalFrames must always be roots of a focus traversal cycle.
 void setFrameIcon(Icon icon)
Sets an image to be displayed in the titlebar of this internal frame (usually in the top-left corner).
 void setGlassPane(Component glass)
Sets this JInternalFrame's glassPane property.
 void setIcon(boolean b)
Iconifies or de-iconifies this internal frame, if the look and feel supports iconification.
 void setIconifiable(boolean b)
Sets the iconable property, which must be true for the user to be able to make the JInternalFrame an icon.
 void setJMenuBar(JMenuBar m)
Sets the menuBar property for this JInternalFrame.
 void setLayer(int layer)
Convenience method for setting the layer attribute of this component.
 void setLayer(Integer layer)
Convenience method for setting the layer attribute of this component.
 void setLayeredPane(JLayeredPane layered)
Sets this JInternalFrame's layeredPane property.
 void setLayout(LayoutManager manager)
Ensures that, by default, the layout of this component cannot be set.
 void setMaximizable(boolean b)
Sets the maximizable property, which determines whether the JInternalFrame can be maximized by some user action.
 void setMaximum(boolean b)
Maximizes and restores this internal frame.
 void setMenuBar(JMenuBar m)
Deprecated. As of Swing version 1.0.3 replaced by setJMenuBar(JMenuBar m).
 void setNormalBounds(Rectangle r)
Sets the normal bounds for this internal frame, the bounds that this internal frame would be restored to from its maximized state.
 void setResizable(boolean b)
Sets whether the JInternalFrame can be resized by some user action.
protected  void setRootPane(JRootPane root)
Sets the rootPane property for this JInternalFrame.
protected  void setRootPaneCheckingEnabled(boolean enabled)
Sets whether calls to add and setLayout are forwarded to the contentPane.
 void setSelected(boolean selected)
Selects or deselects the internal frame if it's showing.
 void setTitle(String title)
Sets the JInternalFrame title.
 void setUI(InternalFrameUI ui)
Sets the UI delegate for this JInternalFrame.
 void show()
If the internal frame is not visible, brings the internal frame to the front, makes it visible, and attempts to select it.
 void toBack()
Sends this internal frame to the back.
 void toFront()
Brings this internal frame to the front.
 void updateUI()
Notification from the UIManager that the look and feel has changed.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

rootPane

protected JRootPane rootPane
The JRootPane instance that manages the content pane and optional menu bar for this internal frame, as well as the glass pane.

See Also:
JRootPane, RootPaneContainer

rootPaneCheckingEnabled

protected boolean rootPaneCheckingEnabled
If true then calls to add and setLayout will be forwarded to the contentPane. This is initially false, but is set to true when the JInternalFrame is constructed.

See Also:
isRootPaneCheckingEnabled(), setRootPaneCheckingEnabled(boolean), RootPaneContainer

closable

protected boolean closable
The frame can be closed.

isClosed

protected boolean isClosed
The frame has been closed.

maximizable

protected boolean maximizable
The frame can be expanded to the size of the desktop pane.

isMaximum

protected boolean isMaximum
The frame has been expanded to its maximum size.

See Also:
maximizable

iconable

protected boolean iconable
The frame can "iconified" (shrunk down and displayed as an icon-image).

See Also:
JInternalFrame.JDesktopIcon, setIconifiable(boolean)

isIcon

protected boolean isIcon
The frame has been iconified.

See Also:
isIcon()

resizable

protected boolean resizable
The frame's size can be changed.

isSelected

protected boolean isSelected
The frame is currently selected.

frameIcon

protected Icon frameIcon
The icon shown in the top-left corner of this internal frame.

title

protected String title
The title displayed in this internal frame's title bar.

desktopIcon

protected JInternalFrame.JDesktopIcon desktopIcon
The icon that is displayed when this internal frame is iconified.

See Also:
iconable

CONTENT_PANE_PROPERTY

public static final String CONTENT_PANE_PROPERTY
Bound property name.

See Also:
Constant Field Values

MENU_BAR_PROPERTY

public static final String MENU_BAR_PROPERTY
Bound property name.

See Also:
Constant Field Values

TITLE_PROPERTY

public static final String TITLE_PROPERTY
Bound property name.

See Also:
Constant Field Values

LAYERED_PANE_PROPERTY

public static final String LAYERED_PANE_PROPERTY
Bound property name.

See Also:
Constant Field Values

ROOT_PANE_PROPERTY

public static final String ROOT_PANE_PROPERTY
Bound property name.

See Also:
Constant Field Values

GLASS_PANE_PROPERTY

public static final String GLASS_PANE_PROPERTY
Bound property name.

See Also:
Constant Field Values

FRAME_ICON_PROPERTY

public static final String FRAME_ICON_PROPERTY
Bound property name.

See Also:
Constant Field Values

IS_SELECTED_PROPERTY

public static final String IS_SELECTED_PROPERTY
Constrained property name indicated that this frame has selected status.

See Also:
Constant Field Values

IS_CLOSED_PROPERTY

public static final String IS_CLOSED_PROPERTY
Constrained property name indicating that the internal frame is closed.

See Also:
Constant Field Values

IS_MAXIMUM_PROPERTY

public static final String IS_MAXIMUM_PROPERTY
Constrained property name indicating that the internal frame is maximized.

See Also:
Constant Field Values

IS_ICON_PROPERTY

public static final String IS_ICON_PROPERTY
Constrained property name indicating that the internal frame is iconified.

See Also:
Constant Field Values
Constructor Detail

JInternalFrame

public JInternalFrame()
Creates a non-resizable, non-closable, non-maximizable, non-iconifiable JInternalFrame with no title.

JInternalFrame

public JInternalFrame(String title)
Creates a non-resizable, non-closable, non-maximizable, non-iconifiable JInternalFrame with the specified title. Note that passing in a null title results in unspecified behavior and possibly an exception.

Parameters:
title - the non-null String to display in the title bar

JInternalFrame

public JInternalFrame(String title,
                      boolean resizable)
Creates a non-closable, non-maximizable, non-iconifiable JInternalFrame with the specified title and resizability.

Parameters:
title - the String to display in the title bar
resizable - if true, the internal frame can be resized

JInternalFrame

public JInternalFrame(String title,
                      boolean resizable,
                      boolean closable)
Creates a non-maximizable, non-iconifiable JInternalFrame with the specified title, resizability, and closability.

Parameters:
title - the String to display in the title bar
resizable - if true, the internal frame can be resized
closable - if true, the internal frame can be closed

JInternalFrame

public JInternalFrame(String title,
                      boolean resizable,
                      boolean closable,
                      boolean maximizable)
Creates a non-iconifiable JInternalFrame with the specified title, resizability, closability, and maximizability.

Parameters:
title - the String to display in the title bar
resizable - if true, the internal frame can be resized
closable - if true, the internal frame can be closed
maximizable - if true, the internal frame can be maximized

JInternalFrame

public JInternalFrame(String title,
                      boolean resizable,
                      boolean closable,
                      boolean maximizable,
                      boolean iconifiable)
Creates a JInternalFrame with the specified title, resizability, closability, maximizability, and iconifiability. All JInternalFrame constructors use this one.

Parameters:
title - the String to display in the title bar
resizable - if true, the internal frame can be resized
closable - if true, the internal frame can be closed
maximizable - if true, the internal frame can be maximized
iconifiable - if true, the internal frame can be iconified
Method Detail

createRootPane

protected JRootPane createRootPane()
Called by the constructor to set up the JRootPane.

Returns:
a new JRootPane
See Also:
JRootPane

getUI

public InternalFrameUI getUI()
Returns the look-and-feel object that renders this component.

Returns:
the InternalFrameUI object that renders this component

setUI

public void setUI(InternalFrameUI ui)
Sets the UI delegate for this JInternalFrame.

Parameters:
ui - the UI delegate

updateUI

public void updateUI()
Notification from the UIManager that the look and feel has changed. Replaces the current UI object with the latest version from the UIManager.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the look-and-feel class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "InternalFrameUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

isRootPaneCheckingEnabled

protected boolean isRootPaneCheckingEnabled()
Returns whether calls to add and setLayout are forwarded to the contentPane.

Returns:
true if add and setLayout are fowarded; false otherwise
See Also:
addImpl(java.awt.Component, java.lang.Object, int), setLayout(java.awt.LayoutManager), setRootPaneCheckingEnabled(boolean), RootPaneContainer

setRootPaneCheckingEnabled

protected void setRootPaneCheckingEnabled(boolean enabled)
Sets whether calls to add and setLayout are forwarded to the contentPane.

Parameters:
enabled - true if add and setLayout are forwarded, false if they should operate directly on the JInternalFrame.
See Also:
addImpl(java.awt.Component, java.lang.Object, int),
setLayout(java.awt.LayoutManager),
isRootPaneCheckingEnabled(),
RootPaneContainer

addImpl

protected void addImpl(Component comp,
                       Object constraints,
                       int index)
Adds the specified child Component. This method is overridden to conditionally forward calls to the contentPane. By default, children are added to the contentPane instead of the frame, refer to RootPaneContainer for details.

Overrides:
addImpl in class Container
Parameters:
comp - the component to be enhanced
constraints - the constraints to be respected
index - the index
Throws:
IllegalArgumentException - if index is invalid
IllegalArgumentException - if adding the container's parent to itself
IllegalArgumentException - if adding a window to a container
See Also:
setRootPaneCheckingEnabled(boolean), RootPaneContainer

remove

public void remove(Component comp)
Removes the specified component from the container. If comp is not a child of the JInternalFrame this will forward the call to the contentPane.

Overrides:
remove in class Container
Parameters:
comp - the component to be removed
Throws:
NullPointerException - if comp is null
See Also:
Container.add(java.awt.Component), RootPaneContainer

setLayout

public void setLayout(LayoutManager manager)
Ensures that, by default, the layout of this component cannot be set. Overridden to conditionally forward the call to the contentPane. Refer to RootPaneContainer for more information.

Overrides:
setLayout in class Container
Parameters:
manager - the LayoutManager
See Also:
setRootPaneCheckingEnabled(boolean)

getMenuBar

@Deprecated
public JMenuBar getMenuBar()
Deprecated. As of Swing version 1.0.3, replaced by getJMenuBar().

Returns the current JMenuBar for this JInternalFrame, or null if no menu bar has been set.

Returns:
the current menu bar, or null if none has been set

getJMenuBar

public JMenuBar getJMenuBar()
Returns the current JMenuBar for this JInternalFrame, or null if no menu bar has been set.

Returns:
the JMenuBar used by this internal frame
See Also:
setJMenuBar(javax.swing.JMenuBar)

setMenuBar

@Deprecated
public void setMenuBar(JMenuBar m)
Deprecated. As of Swing version 1.0.3 replaced by setJMenuBar(JMenuBar m).

Sets the menuBar property for this JInternalFrame.

Parameters:
m - the JMenuBar to use in this internal frame
See Also:
getJMenuBar()

setJMenuBar

public void setJMenuBar(JMenuBar m)
Sets the menuBar property for this JInternalFrame.

Parameters:
m - the JMenuBar to use in this internal frame
See Also:
getJMenuBar()

getContentPane

public Container getContentPane()
Returns the content pane for this internal frame.

Specified by:
getContentPane in interface RootPaneContainer
Returns:
the content pane
See Also:
RootPaneContainer.setContentPane(java.awt.Container)

setContentPane

public void setContentPane(Container c)
Sets this JInternalFrame's contentPane property.

Specified by:
setContentPane in interface RootPaneContainer
Parameters:
c - the content pane for this internal frame
Throws:
IllegalComponentStateException - (a runtime exception) if the content pane parameter is null
See Also:
RootPaneContainer.getContentPane()

getLayeredPane

public JLayeredPane getLayeredPane()
Returns the layered pane for this internal frame.

Specified by:
getLayeredPane in interface RootPaneContainer
Returns:
a JLayeredPane object
See Also:
RootPaneContainer.setLayeredPane(javax.swing.JLayeredPane), RootPaneContainer.getLayeredPane()

setLayeredPane

public void setLayeredPane(JLayeredPane layered)
Sets this JInternalFrame's layeredPane property.

Specified by:
setLayeredPane in interface RootPaneContainer
Parameters:
layered - the JLayeredPane for this internal frame
Throws:
IllegalComponentStateException - (a runtime exception) if the layered pane parameter is null
See Also:
RootPaneContainer.setLayeredPane(javax.swing.JLayeredPane)

getGlassPane

public Component getGlassPane()
Returns the glass pane for this internal frame.

Specified by:
getGlassPane in interface RootPaneContainer
Returns:
the glass pane
See Also:
RootPaneContainer.setGlassPane(java.awt.Component)

setGlassPane

public void setGlassPane(Component glass)
Sets this JInternalFrame's glassPane property.

Specified by:
setGlassPane in interface RootPaneContainer
Parameters:
glass - the glass pane for this internal frame
See Also:
RootPaneContainer.getGlassPane()

getRootPane

public JRootPane getRootPane()
Returns the rootPane object for this internal frame.

Specified by:
getRootPane in interface RootPaneContainer
Overrides:
getRootPane in class JComponent
Returns:
the rootPane property
See Also:
RootPaneContainer.getRootPane()

setRootPane

protected void setRootPane(JRootPane root)
Sets the rootPane property for this JInternalFrame. This method is called by the constructor.

Parameters:
root - the new JRootPane object

setClosable

public void setClosable(boolean b)
Sets whether this JInternalFrame can be closed by some user action.

Parameters:
b - a boolean value, where true means this internal frame can be closed

isClosable

public boolean isClosable()
Returns whether this JInternalFrame can be closed by some user action.

Returns:
true if this internal frame can be closed

isClosed

public boolean isClosed()
Returns whether this JInternalFrame is currently closed.

Returns:
true if this internal frame is closed, false otherwise

setClosed

public void setClosed(boolean b)
               throws PropertyVetoException
Closes this internal frame if the argument is true. Do not invoke this method with a false argument; the result of invoking setClosed(false) is unspecified.

If the internal frame is already closed, this method does nothing and returns immediately. Otherwise, this method begins by firing an INTERNAL_FRAME_CLOSING event. Then this method sets the closed property to true unless a listener vetoes the property change. This method finishes by making the internal frame invisible and unselected, and then firing an INTERNAL_FRAME_CLOSED event.

Note: To reuse an internal frame that has been closed, you must add it to a container (even if you never removed it from its previous container). Typically, this container will be the JDesktopPane that previously contained the internal frame.

Parameters:
b - must be true
Throws:
PropertyVetoException - when the attempt to set the property is vetoed by the JInternalFrame
See Also:
isClosed(), setDefaultCloseOperation(int), dispose(), InternalFrameEvent.INTERNAL_FRAME_CLOSING

setResizable

public void setResizable(boolean b)
Sets whether the JInternalFrame can be resized by some user action.

Parameters:
b - a boolean, where true means this internal frame can be resized

isResizable

public boolean isResizable()
Returns whether the JInternalFrame can be resized by some user action.

Returns:
true if this internal frame can be resized, false otherwise

setIconifiable

public void setIconifiable(boolean b)
Sets the iconable property, which must be true for the user to be able to make the JInternalFrame an icon. Some look and feels might not implement iconification; they will ignore this property.

Parameters:
b - a boolean, where true means this internal frame can be iconified

isIconifiable

public boolean isIconifiable()
Gets the iconable property, which by default is false.

Returns:
the value of the iconable property.
See Also:
setIconifiable(boolean)

isIcon

public boolean isIcon()
Returns whether the JInternalFrame is currently iconified.

Returns:
true if this internal frame is iconified

setIcon

public void setIcon(boolean b)
             throws PropertyVetoException
Iconifies or de-iconifies this internal frame, if the look and feel supports iconification. If the internal frame's state changes to iconified, this method fires an INTERNAL_FRAME_ICONIFIED event. If the state changes to de-iconified, an INTERNAL_FRAME_DEICONIFIED event is fired.

Parameters:
b - a boolean, where true means to iconify this internal frame and false means to de-iconify it
Throws:
PropertyVetoException - when the attempt to set the property is vetoed by the JInternalFrame
See Also:
InternalFrameEvent.INTERNAL_FRAME_ICONIFIED, InternalFrameEvent.INTERNAL_FRAME_DEICONIFIED

setMaximizable

public void setMaximizable(boolean b)
Sets the maximizable property, which determines whether the JInternalFrame can be maximized by some user action. Some look and feels might not support maximizing internal frames; they will ignore this property.

Parameters:
b - true to specify that this internal frame should be maximizable; false to specify that it should not be

isMaximizable

public boolean isMaximizable()
Gets the value of the maximizable property.

Returns:
the value of the maximizable property
See Also:
setMaximizable(boolean)

isMaximum

public boolean isMaximum()
Returns whether the JInternalFrame is currently maximized.

Returns:
true if this internal frame is maximized, false otherwise

setMaximum

public void setMaximum(boolean b)
                throws PropertyVetoException
Maximizes and restores this internal frame. A maximized frame is resized to fully fit the JDesktopPane area associated with the JInternalFrame. A restored frame's size is set to the JInternalFrame's actual size.

Parameters:
b - a boolean, where true maximizes this internal frame and false restores it
Throws:
PropertyVetoException - when the attempt to set the property is vetoed by the JInternalFrame

getTitle

public String getTitle()
Returns the title of the JInternalFrame.

Returns:
a String containing this internal frame's title
See Also:
setTitle(java.lang.String)

setTitle

public void setTitle(String title)
Sets the JInternalFrame title. title may have a null value.

Parameters:
title - the String to display in the title bar
See Also:
getTitle()

setSelected

public void setSelected(boolean selected)
                 throws PropertyVetoException
Selects or deselects the internal frame if it's showing. A JInternalFrame normally draws its title bar differently if it is the selected frame, which indicates to the user that this internal frame has the focus. When this method changes the state of the internal frame from deselected to selected, it fires an InternalFrameEvent.INTERNAL_FRAME_ACTIVATED event. If the change is from selected to deselected, an InternalFrameEvent.INTERNAL_FRAME_DEACTIVATED event is fired.

Parameters:
selected - a boolean, where true means this internal frame should become selected (currently active) and false means it should become deselected
Throws:
PropertyVetoException - when the attempt to set the property is vetoed by the JInternalFrame
See Also:
Component.isShowing(), InternalFrameEvent.INTERNAL_FRAME_ACTIVATED, InternalFrameEvent.INTERNAL_FRAME_DEACTIVATED

isSelected

public boolean isSelected()
Returns whether the JInternalFrame is the currently "selected" or active frame.

Returns:
true if this internal frame is currently selected (active)
See Also:
setSelected(boolean)

setFrameIcon

public void setFrameIcon(Icon icon)
Sets an image to be displayed in the titlebar of this internal frame (usually in the top-left corner). This image is not the desktopIcon object, which is the image displayed in the JDesktop when this internal frame is iconified. Passing null to this function is valid, but the look and feel can choose the appropriate behavior for that situation, such as displaying no icon or a default icon for the look and feel.

Parameters:
icon - the Icon to display in the title bar
See Also:
getFrameIcon()

getFrameIcon

public Icon getFrameIcon()
Returns the image displayed in the title bar of this internal frame (usually in the top-left corner).

Returns:
the Icon displayed in the title bar
See Also:
setFrameIcon(javax.swing.Icon)

moveToFront

public void moveToFront()
Convenience method that moves this component to position 0 if its parent is a JLayeredPane.

moveToBack

public void moveToBack()
Convenience method that moves this component to position -1 if its parent is a JLayeredPane.

getLastCursor

public Cursor getLastCursor()
Returns the last Cursor that was set by the setCursor method that is not a resizable Cursor.

Returns:
the last non-resizable Cursor
Since:
1.6

setCursor

public void setCursor(Cursor cursor)
Sets the cursor image to the specified cursor. This cursor image is displayed when the contains method for this component returns true for the current cursor location, and this Component is visible, displayable, and enabled. Setting the cursor of a Container causes that cursor to be displayed within all of the container's subcomponents, except for those that have a non-null cursor.

The method may have no visual effect if the Java platform implementation and/or the native system do not support changing the mouse cursor shape.

Overrides:
setCursor in class Component
Parameters:
cursor - One of the constants defined by the Cursor class; if this parameter is null then this component will inherit the cursor of its parent
Since:
1.6
See Also:
Component.isEnabled(),
Component.isShowing(),
Component.getCursor(),
Component.contains(int, int),
Toolkit.createCustomCursor(java.awt.Image, java.awt.Point, java.lang.String),
Cursor

setLayer

public void setLayer(Integer layer)
Convenience method for setting the layer attribute of this component.

Parameters:
layer - an Integer object specifying this frame's desktop layer
See Also:
JLayeredPane

setLayer

public void setLayer(int layer)
Convenience method for setting the layer attribute of this component. The method setLayer(Integer) should be used for layer values predefined in JLayeredPane. When using setLayer(int), care must be taken not to accidentally clash with those values.

Parameters:
layer - an integer specifying this internal frame's desktop layer
Since:
1.3
See Also:
setLayer(Integer), JLayeredPane

getLayer

public int getLayer()
Convenience method for getting the layer attribute of this component.

Returns:
an Integer object specifying this frame's desktop layer
See Also:
JLayeredPane

getDesktopPane

public JDesktopPane getDesktopPane()
Convenience method that searches the ancestor hierarchy for a JDesktop instance. If JInternalFrame finds none, the desktopIcon tree is searched.

Returns:
the JDesktopPane this internal frame belongs to, or null if none is found

setDesktopIcon

public void setDesktopIcon(JInternalFrame.JDesktopIcon d)
Sets the JDesktopIcon associated with this JInternalFrame.

Parameters:
d - the JDesktopIcon to display on the desktop
See Also:
getDesktopIcon()

getDesktopIcon

public JInternalFrame.JDesktopIcon getDesktopIcon()
Returns the JDesktopIcon used when this JInternalFrame is iconified.

Returns:
the JDesktopIcon displayed on the desktop
See Also:
setDesktopIcon(javax.swing.JInternalFrame.JDesktopIcon)

getNormalBounds

public Rectangle getNormalBounds()
If the JInternalFrame is not in maximized state, returns getBounds(); otherwise, returns the bounds that the JInternalFrame would be restored to.

Returns:
a Rectangle containing the bounds of this frame when in the normal state
Since:
1.3

setNormalBounds

public void setNormalBounds(Rectangle r)
Sets the normal bounds for this internal frame, the bounds that this internal frame would be restored to from its maximized state. This method is intended for use only by desktop managers.

Parameters:
r - the bounds that this internal frame should be restored to
Since:
1.3

getFocusOwner

public Component getFocusOwner()
If this JInternalFrame is active, returns the child that has focus. Otherwise, returns null.

Returns:
the component with focus, or null if no children have focus
Since:
1.3

getMostRecentFocusOwner

public Component getMostRecentFocusOwner()
Returns the child component of this JInternalFrame that will receive the focus when this JInternalFrame is selected. If this JInternalFrame is currently selected, this method returns the same component as the getFocusOwner method. If this JInternalFrame is not selected, then the child component that most recently requested focus will be returned. If no child component has ever requested focus, then this JInternalFrame's initial focusable component is returned. If no such child exists, then this JInternalFrame's default component to focus is returned.

Returns:
the child component that will receive focus when this JInternalFrame is selected
Since:
1.4
See Also:
getFocusOwner(), isSelected

restoreSubcomponentFocus

public void restoreSubcomponentFocus()
Requests the internal frame to restore focus to the last subcomponent that had focus. This is used by the UI when the user selected this internal frame -- for example, by clicking on the title bar.

Since:
1.3

reshape

public void reshape(int x,
                    int y,
                    int width,
                    int height)
Moves and resizes this component. Unlike other components, this implementation also forces re-layout, so that frame decorations such as the title bar are always redisplayed.

Overrides:
reshape in class JComponent
Parameters:
x - an integer giving the component's new horizontal position measured in pixels from the left of its container
y - an integer giving the component's new vertical position, measured in pixels from the bottom of its container
width - an integer giving the component's new width in pixels
height - an integer giving the component's new height in pixels
See Also:
Component.setBounds(int, int, int, int)

addInternalFrameListener

public void addInternalFrameListener(InternalFrameListener l)
Adds the specified listener to receive internal frame events from this internal frame.

Parameters:
l - the internal frame listener

removeInternalFrameListener

public void removeInternalFrameListener(InternalFrameListener l)
Removes the specified internal frame listener so that it no longer receives internal frame events from this internal frame.

Parameters:
l - the internal frame listener

getInternalFrameListeners

public InternalFrameListener[] getInternalFrameListeners()
Returns an array of all the InternalFrameListeners added to this JInternalFrame with addInternalFrameListener.

Returns:
all of the InternalFrameListeners added or an empty array if no listeners have been added
Since:
1.4
See Also:
addInternalFrameListener(javax.swing.event.InternalFrameListener)

fireInternalFrameEvent

protected void fireInternalFrameEvent(int id)
Fires an internal frame event.

Parameters:
id - the type of the event being fired; one of the following:
  • InternalFrameEvent.INTERNAL_FRAME_OPENED
  • InternalFrameEvent.INTERNAL_FRAME_CLOSING
  • InternalFrameEvent.INTERNAL_FRAME_CLOSED
  • InternalFrameEvent.INTERNAL_FRAME_ICONIFIED
  • InternalFrameEvent.INTERNAL_FRAME_DEICONIFIED
  • InternalFrameEvent.INTERNAL_FRAME_ACTIVATED
  • InternalFrameEvent.INTERNAL_FRAME_DEACTIVATED
If the event type is not one of the above, nothing happens.

doDefaultCloseAction

public void doDefaultCloseAction()
Fires an INTERNAL_FRAME_CLOSING event and then performs the action specified by the internal frame's default close operation. This method is typically invoked by the look-and-feel-implemented action handler for the internal frame's close button.

Since:
1.3
See Also:
setDefaultCloseOperation(int), InternalFrameEvent.INTERNAL_FRAME_CLOSING

setDefaultCloseOperation

public void setDefaultCloseOperation(int operation)
Sets the operation that will happen by default when the user initiates a "close" on this internal frame. The possible choices are:

DO_NOTHING_ON_CLOSE
Do nothing. This requires the program to handle the operation in the windowClosing method of a registered InternalFrameListener object.
HIDE_ON_CLOSE
Automatically make the internal frame invisible.
DISPOSE_ON_CLOSE
Automatically dispose of the internal frame.

The default value is DISPOSE_ON_CLOSE. Before performing the specified close operation, the internal frame fires an INTERNAL_FRAME_CLOSING event.

Parameters:
operation - one of the following constants defined in javax.swing.WindowConstants (an interface implemented by JInternalFrame): DO_NOTHING_ON_CLOSE, HIDE_ON_CLOSE, or DISPOSE_ON_CLOSE
See Also:
addInternalFrameListener(javax.swing.event.InternalFrameListener),
getDefaultCloseOperation(),
JComponent.setVisible(boolean),
dispose(),
InternalFrameEvent.INTERNAL_FRAME_CLOSING

getDefaultCloseOperation

public int getDefaultCloseOperation()
Returns the default operation that occurs when the user initiates a "close" on this internal frame.

Returns:
the operation that will occur when the user closes the internal frame
See Also:
setDefaultCloseOperation(int)

pack

public void pack()
Causes subcomponents of this JInternalFrame to be laid out at their preferred size. Internal frames that are iconized or maximized are first restored and then packed. If the internal frame is unable to be restored its state is not changed and will not be packed.

See Also:
Window.pack()

show

public void show()
If the internal frame is not visible, brings the internal frame to the front, makes it visible, and attempts to select it. The first time the internal frame is made visible, this method also fires an INTERNAL_FRAME_OPENED event. This method does nothing if the internal frame is already visible. Invoking this method has the same result as invoking setVisible(true).

Overrides:
show in class Component
See Also:
moveToFront(), setSelected(boolean), InternalFrameEvent.INTERNAL_FRAME_OPENED, JComponent.setVisible(boolean)

hide

public void hide()
Overrides:
hide in class Component

dispose

public void dispose()
Makes this internal frame invisible, unselected, and closed. If the frame is not already closed, this method fires an INTERNAL_FRAME_CLOSED event. The results of invoking this method are similar to setClosed(true), but dispose always succeeds in closing the internal frame and does not fire an INTERNAL_FRAME_CLOSING event.

See Also:
InternalFrameEvent.INTERNAL_FRAME_CLOSED, JComponent.setVisible(boolean), setSelected(boolean), setClosed(boolean)

toFront

public void toFront()
Brings this internal frame to the front. Places this internal frame at the top of the stacking order and makes the corresponding adjustment to other visible internal frames.

See Also:
Window.toFront(), moveToFront()

toBack

public void toBack()
Sends this internal frame to the back. Places this internal frame at the bottom of the stacking order and makes the corresponding adjustment to other visible internal frames.

See Also:
Window.toBack(), moveToBack()

setFocusCycleRoot

public final void setFocusCycleRoot(boolean focusCycleRoot)
Does nothing because JInternalFrames must always be roots of a focus traversal cycle.

Overrides:
setFocusCycleRoot in class Container
Parameters:
focusCycleRoot - this value is ignored
Since:
1.4
See Also:
isFocusCycleRoot(),
Container.setFocusTraversalPolicy(java.awt.FocusTraversalPolicy),
Container.getFocusTraversalPolicy()

isFocusCycleRoot

public final boolean isFocusCycleRoot()
Always returns true because all JInternalFrames must be roots of a focus traversal cycle.

Overrides:
isFocusCycleRoot in class Container
Returns:
true
Since:
1.4
See Also:
setFocusCycleRoot(boolean), Container.setFocusTraversalPolicy(java.awt.FocusTraversalPolicy), Container.getFocusTraversalPolicy()

getFocusCycleRootAncestor

public final Container getFocusCycleRootAncestor()
Always returns null because JInternalFrames must always be roots of a focus traversal cycle.

Overrides:
getFocusCycleRootAncestor in class Component
Returns:
null
Since:
1.4
See Also:
Container.isFocusCycleRoot()

getWarningString

public final String getWarningString()
Gets the warning string that is displayed with this internal frame. Since an internal frame is always secure (since it's fully contained within a window that might need a warning string) this method always returns null.

Returns:
null
See Also:
Window.getWarningString()

paramString

protected String paramString()
Returns a string representation of this JInternalFrame. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JInternalFrame

paintComponent

protected void paintComponent(Graphics g)
Overridden to allow optimized painting when the internal frame is being dragged.

Overrides:
paintComponent in class JComponent
Parameters:
g - the Graphics object to protect
See Also:
JComponent.paint(java.awt.Graphics), ComponentUI

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JInternalFrame. For internal frames, the AccessibleContext takes the form of an AccessibleJInternalFrame object. A new AccessibleJInternalFrame instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJInternalFrame that serves as the AccessibleContext of this JInternalFrame
See Also:
JInternalFrame.AccessibleJInternalFrame
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JInternalFrame.AccessibleJInternalFrame

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JInternalFrame.AccessibleJInternalFrame

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JInternalFrame.AccessibleJInternalFrame
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent, AccessibleValue
Enclosing class:
JInternalFrame
protected class JInternalFrame.AccessibleJInternalFrame
extends JComponent.AccessibleJComponent
implements AccessibleValue

This class implements accessibility support for the JInternalFrame class. It provides an implementation of the Java Accessibility API appropriate to internal frame user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JInternalFrame.AccessibleJInternalFrame()
Method Summary
String | getAccessibleName() Get the accessible name of this object.
AccessibleRole | getAccessibleRole() Get the role of this object.
AccessibleValue | getAccessibleValue() Gets the AccessibleValue associated with this object.
Number | getCurrentAccessibleValue() Get the value of this object as a Number.
Number | getMaximumAccessibleValue() Get the maximum value of this object as a Number.
Number | getMinimumAccessibleValue() Get the minimum value of this object as a Number.
boolean | setCurrentAccessibleValue(Number n) Set the value of this object as a Number.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JInternalFrame.AccessibleJInternalFrame

protected JInternalFrame.AccessibleJInternalFrame()
Method Detail

getAccessibleName

public String getAccessibleName()
Get the accessible name of this object.

Overrides:
getAccessibleName in class JComponent.AccessibleJComponent
Returns:
the localized name of the object -- can be null if this object does not have a name
See Also:
AccessibleContext.setAccessibleName(java.lang.String)

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleValue

public AccessibleValue getAccessibleValue()
Gets the AccessibleValue associated with this object. In the implementation of the Java Accessibility API for this class, returns this object, which is responsible for implementing the AccessibleValue interface on behalf of itself.

Overrides:
getAccessibleValue in class AccessibleContext
Returns:
this object
See Also:
AccessibleValue

getCurrentAccessibleValue

public Number getCurrentAccessibleValue()
Get the value of this object as a Number.

Specified by:
getCurrentAccessibleValue in interface AccessibleValue
Returns:
value of the object -- can be null if this object does not have a value
See Also:
AccessibleValue.setCurrentAccessibleValue(java.lang.Number)

setCurrentAccessibleValue

public boolean setCurrentAccessibleValue(Number n)
Set the value of this object as a Number.

Specified by:
setCurrentAccessibleValue in interface AccessibleValue
Returns:
true if the value was set
See Also:
AccessibleValue.getCurrentAccessibleValue()

getMinimumAccessibleValue

public Number getMinimumAccessibleValue()
Get the minimum value of this object as a Number.

Specified by:
getMinimumAccessibleValue in interface AccessibleValue
Returns:
Minimum value of the object; null if this object does not have a minimum value
See Also:
AccessibleValue.getMaximumAccessibleValue()

getMaximumAccessibleValue

public Number getMaximumAccessibleValue()
Get the maximum value of this object as a Number.

Specified by:
getMaximumAccessibleValue in interface AccessibleValue
Returns:
Maximum value of the object; null if this object does not have a maximum value
See Also:
AccessibleValue.getMinimumAccessibleValue()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JInternalFrame.JDesktopIcon

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JInternalFrame.JDesktopIcon

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JInternalFrame.JDesktopIcon
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
Enclosing class:
JInternalFrame
public static class JInternalFrame.JDesktopIcon
extends JComponent
implements Accessible

This component represents an iconified version of a JInternalFrame. This API should NOT BE USED by Swing applications, as it will go away in future versions of Swing as its functionality is moved into JInternalFrame. This class is public only so that UI objects can display a desktop icon. If an application wants to display a desktop icon, it should create a JInternalFrame instance and iconify it.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class JInternalFrame.JDesktopIcon.AccessibleJDesktopIcon
This class implements accessibility support for the JInternalFrame.JDesktopIcon class.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JInternalFrame.JDesktopIcon(JInternalFrame f)
Creates an icon for an internal frame.
Method Summary
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JDesktopIcon.
JDesktopPane | getDesktopPane() Convenience method to ask the icon for the Desktop object it belongs to.
JInternalFrame | getInternalFrame() Returns the JInternalFrame that this DesktopIcon is associated with.
DesktopIconUI | getUI() Returns the look-and-feel object that renders this component.
String | getUIClassID() Returns the name of the look-and-feel class that renders this component.
void | setInternalFrame(JInternalFrame f) Sets the JInternalFrame with which this DesktopIcon is associated.
void | setUI(DesktopIconUI ui) Sets the look-and-feel object that renders this component.
void | updateUI() Notification from the UIManager that the look and feel has changed.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JInternalFrame.JDesktopIcon

public JInternalFrame.JDesktopIcon(JInternalFrame f)
Creates an icon for an internal frame.

Parameters:
f - the JInternalFrame for which the icon is created
Method Detail

getUI

public DesktopIconUI getUI()
Returns the look-and-feel object that renders this component.

Returns:
the DesktopIconUI object that renders this component

setUI

public void setUI(DesktopIconUI ui)
Sets the look-and-feel object that renders this component.

Parameters:
ui - the DesktopIconUI look-and-feel object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

getInternalFrame

public JInternalFrame getInternalFrame()
Returns the JInternalFrame that this DesktopIcon is associated with.

Returns:
the JInternalFrame with which this icon is associated

setInternalFrame

public void setInternalFrame(JInternalFrame f)
Sets the JInternalFrame with which this DesktopIcon is associated.

Parameters:
f - the JInternalFrame with which this icon is associated

getDesktopPane

public JDesktopPane getDesktopPane()
Convenience method to ask the icon for the Desktop object it belongs to.

Returns:
the JDesktopPane that contains this icon's internal frame, or null if none found

updateUI

public void updateUI()
Notification from the UIManager that the look and feel has changed. Replaces the current UI object with the latest version from the UIManager.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the look-and-feel class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "DesktopIconUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JDesktopIcon. For desktop icons, the AccessibleContext takes the form of an AccessibleJDesktopIcon. A new AccessibleJDesktopIcon instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJDesktopIcon that serves as the AccessibleContext of this JDesktopIcon
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JInternalFrame.JDesktopIcon.AccessibleJDesktopIcon

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JInternalFrame.JDesktopIcon.AccessibleJDesktopIcon

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JInternalFrame.JDesktopIcon.AccessibleJDesktopIcon
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent, AccessibleValue
Enclosing class:
JInternalFrame.JDesktopIcon
protected class JInternalFrame.JDesktopIcon.AccessibleJDesktopIcon
extends JComponent.AccessibleJComponent
implements AccessibleValue

This class implements accessibility support for the JInternalFrame.JDesktopIcon class. It provides an implementation of the Java Accessibility API appropriate to desktop icon user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JInternalFrame.JDesktopIcon.AccessibleJDesktopIcon()
Method Summary
AccessibleRole | getAccessibleRole() Gets the role of this object.
AccessibleValue | getAccessibleValue() Gets the AccessibleValue associated with this object.
Number | getCurrentAccessibleValue() Gets the value of this object as a Number.
Number | getMaximumAccessibleValue() Gets the maximum value of this object as a Number.
Number | getMinimumAccessibleValue() Gets the minimum value of this object as a Number.
boolean | setCurrentAccessibleValue(Number n) Sets the value of this object as a Number.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JInternalFrame.JDesktopIcon.AccessibleJDesktopIcon

protected JInternalFrame.JDesktopIcon.AccessibleJDesktopIcon()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Gets the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleValue

public AccessibleValue getAccessibleValue()
Gets the AccessibleValue associated with this object. In the implementation of the Java Accessibility API for this class, returns this object, which is responsible for implementing the AccessibleValue interface on behalf of itself.

Overrides:
getAccessibleValue in class AccessibleContext
Returns:
this object
See Also:
AccessibleValue

getCurrentAccessibleValue

public Number getCurrentAccessibleValue()
Gets the value of this object as a Number.

Specified by:
getCurrentAccessibleValue in interface AccessibleValue
Returns:
value of the object -- can be null if this object does not have a value
See Also:
AccessibleValue.setCurrentAccessibleValue(java.lang.Number)

setCurrentAccessibleValue

public boolean setCurrentAccessibleValue(Number n)
Sets the value of this object as a Number.

Specified by:
setCurrentAccessibleValue in interface AccessibleValue
Returns:
true if the value was set
See Also:
AccessibleValue.getCurrentAccessibleValue()

getMinimumAccessibleValue

public Number getMinimumAccessibleValue()
Gets the minimum value of this object as a Number.

Specified by:
getMinimumAccessibleValue in interface AccessibleValue
Returns:
minimum value of the object; null if this object does not have a minimum value
See Also:
AccessibleValue.getMaximumAccessibleValue()

getMaximumAccessibleValue

public Number getMaximumAccessibleValue()
Gets the maximum value of this object as a Number.

Specified by:
getMaximumAccessibleValue in interface AccessibleValue
Returns:
maximum value of the object; null if this object does not have a maximum value
See Also:
AccessibleValue.getMinimumAccessibleValue()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JLabel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JLabel

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JLabel
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, SwingConstants
Direct Known Subclasses:
BasicComboBoxRenderer, DefaultListCellRenderer, DefaultTableCellRenderer, DefaultTreeCellRenderer
public class JLabel
extends JComponent
implements SwingConstants, Accessible

A display area for a short text string or an image, or both. A label does not react to input events. As a result, it cannot get the keyboard focus. A label can, however, display a keyboard alternative as a convenience for a nearby component that has a keyboard alternative but can't display it.

A JLabel object can display either text, an image, or both. You can specify where in the label's display area the label's contents are aligned by setting the vertical and horizontal alignment. By default, labels are vertically centered in their display area. Text-only labels are leading edge aligned, by default; image-only labels are horizontally centered, by default.

You can also specify the position of the text relative to the image. By default, text is on the trailing edge of the image, with the text and image vertically aligned.

A label's leading and trailing edge are determined from the value of its ComponentOrientation property. At present, the default ComponentOrientation setting maps the leading edge to left and the trailing edge to right.

Finally, you can use the setIconTextGap method to specify how many pixels should appear between the text and the image. The default is 4 pixels.

See How to Use Labels in The Java Tutorial for further documentation.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class JLabel.AccessibleJLabel
The class used to obtain the accessible role for this object.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected  Component labelFor
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JLabel()
Creates a JLabel instance with no image and with an empty string for the title.
JLabel(Icon image)
Creates a JLabel instance with the specified image.
JLabel(Icon image, int horizontalAlignment)
Creates a JLabel instance with the specified image and horizontal alignment.
JLabel(String text)
Creates a JLabel instance with the specified text.
JLabel(String text, Icon icon, int horizontalAlignment)
Creates a JLabel instance with the specified text, image, and horizontal alignment.
JLabel(String text, int horizontalAlignment)
Creates a JLabel instance with the specified text and horizontal alignment.
Method Summary
protected int | checkHorizontalKey(int key, String message) Verify that key is a legal value for the horizontalAlignment properties.
protected int | checkVerticalKey(int key, String message) Verify that key is a legal value for the verticalAlignment or verticalTextPosition properties.
AccessibleContext | getAccessibleContext() Get the AccessibleContext of this object
Icon | getDisabledIcon() Returns the icon used by the label when it's disabled.
int | getDisplayedMnemonic() Return the keycode that indicates a mnemonic key.
int | getDisplayedMnemonicIndex() Returns the character, as an index, that the look and feel should provide decoration for as representing the mnemonic character.
int | getHorizontalAlignment() Returns the alignment of the label's contents along the X axis.
int | getHorizontalTextPosition() Returns the horizontal position of the label's text, relative to its image.
Icon | getIcon() Returns the graphic image (glyph, icon) that the label displays.
int | getIconTextGap() Returns the amount of space between the text and the icon displayed in this label.
Component | getLabelFor() Get the component this is labelling.
String | getText() Returns the text string that the label displays.
LabelUI | getUI() Returns the L&F object that renders this component.
String | getUIClassID() Returns a string that specifies the name of the l&f class that renders this component.
int | getVerticalAlignment() Returns the alignment of the label's contents along the Y axis.
int | getVerticalTextPosition() Returns the vertical position of the label's text, relative to its image.
boolean | imageUpdate(Image img, int infoflags, int x, int y, int w, int h) This is overridden to return false if the current Icon's Image is not equal to the passed in Image img.
protected String | paramString() Returns a string representation of this JLabel.
void | setDisabledIcon(Icon disabledIcon) Set the icon to be displayed if this JLabel is "disabled" (JLabel.setEnabled(false)).
void | setDisplayedMnemonic(char aChar) Specifies the displayedMnemonic as a char value.
void | setDisplayedMnemonic(int key) Specify a keycode that indicates a mnemonic key.
void | setDisplayedMnemonicIndex(int index) Provides a hint to the look and feel as to which character in the text should be decorated to represent the mnemonic.
void | setHorizontalAlignment(int alignment) Sets the alignment of the label's contents along the X axis.
void | setHorizontalTextPosition(int textPosition) Sets the horizontal position of the label's text, relative to its image.
void | setIcon(Icon icon) Defines the icon this component will display.
void | setIconTextGap(int iconTextGap) If both the icon and text properties are set, this property defines the space between them.
void | setLabelFor(Component c) Set the component this is labelling.
void | setText(String text) Defines the single line of text this component will display.
void | setUI(LabelUI ui) Sets the L&F object that renders this component.
void | setVerticalAlignment(int alignment) Sets the alignment of the label's contents along the Y axis.
void | setVerticalTextPosition(int textPosition) Sets the vertical position of the label's text, relative to its image.
void | updateUI() Resets the UI property to a value from the current look and feel.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

labelFor

protected Component labelFor
Constructor Detail

JLabel

public JLabel(String text,
              Icon icon,
              int horizontalAlignment)
Creates a JLabel instance with the specified text, image, and horizontal alignment. The label is centered vertically in its display area. The text is on the trailing edge of the image.

Parameters:
text - The text to be displayed by the label.
icon - The image to be displayed by the label.
horizontalAlignment - One of the following constants defined in SwingConstants: LEFT, CENTER, RIGHT, LEADING or TRAILING.

JLabel

public JLabel(String text,
              int horizontalAlignment)
Creates a JLabel instance with the specified text and horizontal alignment. The label is centered vertically in its display area.

Parameters:
text - The text to be displayed by the label.
horizontalAlignment - One of the following constants defined in SwingConstants: LEFT, CENTER, RIGHT, LEADING or TRAILING.

JLabel

public JLabel(String text)
Creates a JLabel instance with the specified text. The label is aligned against the leading edge of its display area, and centered vertically.

Parameters:
text - The text to be displayed by the label.

JLabel

public JLabel(Icon image,
              int horizontalAlignment)
Creates a JLabel instance with the specified image and horizontal alignment. The label is centered vertically in its display area.

Parameters:
image - The image to be displayed by the label.
horizontalAlignment - One of the following constants defined in SwingConstants: LEFT, CENTER, RIGHT, LEADING or TRAILING.

JLabel

public JLabel(Icon image)
Creates a JLabel instance with the specified image. The label is centered vertically and horizontally in its display area.

Parameters:
image - The image to be displayed by the label.

JLabel

public JLabel()
Creates a JLabel instance with no image and with an empty string for the title. The label is centered vertically in its display area. The label's contents, once set, will be displayed on the leading edge of the label's display area.

Method Detail

getUI

public LabelUI getUI()
Returns the L&F object that renders this component.

Returns:
LabelUI object

setUI

public void setUI(LabelUI ui)
Sets the L&F object that renders this component.

Parameters:
ui - the LabelUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Resets the UI property to a value from the current look and feel.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns a string that specifies the name of the l&f class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
String "LabelUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

getText

public String getText()
Returns the text string that the label displays.

Returns:
a String
See Also:
setText(java.lang.String)

setText

public void setText(String text)
Defines the single line of text this component will display. If the value of text is null or empty string, nothing is displayed.

The default value of this property is null.

This is a JavaBeans bound property.

See Also:
setVerticalTextPosition(int), setHorizontalTextPosition(int), setIcon(javax.swing.Icon)

getIcon

public Icon getIcon()
Returns the graphic image (glyph, icon) that the label displays.

Returns:
an Icon
See Also:
setIcon(javax.swing.Icon)

setIcon

public void setIcon(Icon icon)
Defines the icon this component will display. If the value of icon is null, nothing is displayed.

The default value of this property is null.

This is a JavaBeans bound property.

See Also:
setVerticalTextPosition(int), setHorizontalTextPosition(int), getIcon()

getDisabledIcon

public Icon getDisabledIcon()
Returns the icon used by the label when it's disabled. If no disabled icon has been set this will forward the call to the look and feel to construct an appropriate disabled Icon.

Some look and feels might not render the disabled Icon, in which case they will ignore this.

Returns:
the disabledIcon property
See Also:
setDisabledIcon(javax.swing.Icon), LookAndFeel.getDisabledIcon(javax.swing.JComponent, javax.swing.Icon), ImageIcon

setDisabledIcon

public void setDisabledIcon(Icon disabledIcon)
Set the icon to be displayed if this JLabel is "disabled" (JLabel.setEnabled(false)).

The default value of this property is null.

Parameters:
disabledIcon - the Icon to display when the component is disabled
See Also:
getDisabledIcon(), JComponent.setEnabled(boolean)

setDisplayedMnemonic

public void setDisplayedMnemonic(int key)
Specify a keycode that indicates a mnemonic key. This property is used when the label is part of a larger component. If the labelFor property of the label is not null, the label will call the requestFocus method of the component specified by the labelFor property when the mnemonic is activated.

See Also:
getLabelFor(), setLabelFor(java.awt.Component)

setDisplayedMnemonic

public void setDisplayedMnemonic(char aChar)
Specifies the displayedMnemonic as a char value.

Parameters:
aChar - a char specifying the mnemonic to display
See Also:
setDisplayedMnemonic(int)

getDisplayedMnemonic

public int getDisplayedMnemonic()
Return the keycode that indicates a mnemonic key. This property is used when the label is part of a larger component. If the labelFor property of the label is not null, the label will call the requestFocus method of the component specified by the labelFor property when the mnemonic is activated.

Returns:
int value for the mnemonic key
See Also:
getLabelFor(), setLabelFor(java.awt.Component)

setDisplayedMnemonicIndex

public void setDisplayedMnemonicIndex(int index)
                               throws IllegalArgumentException
Provides a hint to the look and feel as to which character in the text should be decorated to represent the mnemonic. Not all look and feels may support this. A value of -1 indicates either there is no mnemonic, the mnemonic character is not contained in the string, or the developer does not wish the mnemonic to be displayed.

The value of this is updated as the properties relating to the mnemonic change (such as the mnemonic itself, the text...). You should only ever have to call this if you do not wish the default character to be underlined. For example, if the text was 'Save As', with a mnemonic of 'a', and you wanted the 'A' to be decorated, as 'Save As', you would have to invoke setDisplayedMnemonicIndex(5) after invoking setDisplayedMnemonic(KeyEvent.VK_A).

Parameters:
index - Index into the String to underline
Throws:
IllegalArgumentException - will be thrown if index= length of the text, or < -1
Since:
1.4

getDisplayedMnemonicIndex

public int getDisplayedMnemonicIndex()
Returns the character, as an index, that the look and feel should provide decoration for as representing the mnemonic character.

Returns:
index representing mnemonic character
Since:
1.4
See Also:
setDisplayedMnemonicIndex(int)

checkHorizontalKey

protected int checkHorizontalKey(int key,
                                 String message)
Verify that key is a legal value for the horizontalAlignment properties.

Parameters:
key - the property value to check
message - the IllegalArgumentException detail message
Throws:
IllegalArgumentException - if key isn't LEFT, CENTER, RIGHT, LEADING or TRAILING.
See Also:
setHorizontalTextPosition(int), setHorizontalAlignment(int)

checkVerticalKey

protected int checkVerticalKey(int key,
                               String message)
Verify that key is a legal value for the verticalAlignment or verticalTextPosition properties.

Parameters:
key - the property value to check
message - the IllegalArgumentException detail message
Throws:
IllegalArgumentException - if key isn't TOP, CENTER, or BOTTOM.
See Also:
setVerticalAlignment(int), setVerticalTextPosition(int)

getIconTextGap

public int getIconTextGap()
Returns the amount of space between the text and the icon displayed in this label.

Returns:
an int equal to the number of pixels between the text and the icon.
See Also:
setIconTextGap(int)

setIconTextGap

public void setIconTextGap(int iconTextGap)
If both the icon and text properties are set, this property defines the space between them.

The default value of this property is 4 pixels.

This is a JavaBeans bound property.

See Also:
getIconTextGap()

getVerticalAlignment

public int getVerticalAlignment()
Returns the alignment of the label's contents along the Y axis.

Returns:
The value of the verticalAlignment property, one of the following constants defined in SwingConstants: TOP, CENTER, or BOTTOM.
See Also:
SwingConstants, setVerticalAlignment(int)

setVerticalAlignment

public void setVerticalAlignment(int alignment)
Sets the alignment of the label's contents along the Y axis.

The default value of this property is CENTER.

Parameters:
alignment - One of the following constants defined in SwingConstants: TOP, CENTER (the default), or BOTTOM.
See Also:
SwingConstants, getVerticalAlignment()

getHorizontalAlignment

public int getHorizontalAlignment()
Returns the alignment of the label's contents along the X axis.

Returns:
The value of the horizontalAlignment property, one of the following constants defined in SwingConstants: LEFT, CENTER, RIGHT, LEADING or TRAILING.
See Also:
setHorizontalAlignment(int), SwingConstants

setHorizontalAlignment

public void setHorizontalAlignment(int alignment)
Sets the alignment of the label's contents along the X axis.

This is a JavaBeans bound property.

Parameters:
alignment - One of the following constants defined in SwingConstants: LEFT, CENTER (the default for image-only labels), RIGHT, LEADING (the default for text-only labels) or TRAILING.
See Also:
SwingConstants, getHorizontalAlignment()

getVerticalTextPosition

public int getVerticalTextPosition()
Returns the vertical position of the label's text, relative to its image.

Returns:
One of the following constants defined in SwingConstants: TOP, CENTER, or BOTTOM.
See Also:
setVerticalTextPosition(int), SwingConstants

setVerticalTextPosition

public void setVerticalTextPosition(int textPosition)
Sets the vertical position of the label's text, relative to its image.

The default value of this property is CENTER.

This is a JavaBeans bound property.

Parameters:
textPosition - One of the following constants defined in SwingConstants: TOP, CENTER (the default), or BOTTOM.
See Also:
SwingConstants, getVerticalTextPosition()

getHorizontalTextPosition

public int getHorizontalTextPosition()
Returns the horizontal position of the label's text, relative to its image.

Returns:
One of the following constants defined in SwingConstants: LEFT, CENTER, RIGHT, LEADING or TRAILING.
See Also:
SwingConstants

setHorizontalTextPosition

public void setHorizontalTextPosition(int textPosition)
Sets the horizontal position of the label's text, relative to its image.

Parameters:
textPosition - One of the following constants defined in SwingConstants: LEFT, CENTER, RIGHT, LEADING, or TRAILING (the default).
Throws:
IllegalArgumentException
See Also:
SwingConstants

imageUpdate

public boolean imageUpdate(Image img,
                           int infoflags,
                           int x,
                           int y,
                           int w,
                           int h)
This is overridden to return false if the current Icon's Image is not equal to the passed in Image img.

Specified by:
imageUpdate in interface ImageObserver
Overrides:
imageUpdate in class Component
Parameters:
img - the image being observed
infoflags - see imageUpdate for more information
x - the x coordinate
y - the y coordinate
w - the width
h - the height
Returns:
false if the infoflags indicate that the image is completely loaded; true otherwise.
See Also:
ImageObserver, Component.imageUpdate(java.awt.Image, int, int, int, int, int)

paramString

protected String paramString()
Returns a string representation of this JLabel. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JLabel.

getLabelFor

public Component getLabelFor()
Get the component this is labelling.

Returns:
the Component this is labelling. Can be null if this does not label a Component. If the displayedMnemonic property is set and the labelFor property is also set, the label will call the requestFocus method of the component specified by the labelFor property when the mnemonic is activated.
See Also:
getDisplayedMnemonic(), setDisplayedMnemonic(int)

setLabelFor

public void setLabelFor(Component c)
Set the component this is labelling. Can be null if this does not label a Component. If the displayedMnemonic property is set and the labelFor property is also set, the label will call the requestFocus method of the component specified by the labelFor property when the mnemonic is activated.

Parameters:
c - the Component this label is for, or null if the label is not the label for a component
See Also:
getDisplayedMnemonic(), setDisplayedMnemonic(int)

getAccessibleContext

public AccessibleContext getAccessibleContext()
Get the AccessibleContext of this object

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
the AccessibleContext of this object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JLabel.AccessibleJLabel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JLabel.AccessibleJLabel

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JLabel.AccessibleJLabel
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent, AccessibleText
Enclosing class:
JLabel
protected class JLabel.AccessibleJLabel
extends JComponent.AccessibleJComponent
implements AccessibleText, AccessibleExtendedComponent

The class used to obtain the accessible role for this object.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Constructor Summary
protected JLabel.AccessibleJLabel()
Method Summary
AccessibleIcon[] | getAccessibleIcon() Get the AccessibleIcons associated with this object if one or more exist.
AccessibleKeyBinding | getAccessibleKeyBinding() Returns key bindings associated with this object
String | getAccessibleName() Get the accessible name of this object.
AccessibleRelationSet | getAccessibleRelationSet() Get the AccessibleRelationSet associated with this object if one exists.
AccessibleRole | getAccessibleRole() Get the role of this object.
AccessibleText | getAccessibleText() Gets the AccessibleText associated with this object presenting text on the display.
String | getAfterIndex(int part, int index) Returns the String after a given index.
String | getAtIndex(int part, int index) Returns the String at a given index.
String | getBeforeIndex(int part, int index) Returns the String before a given index.
int | getCaretPosition() Return the zero-based offset of the caret.
AttributeSet | getCharacterAttribute(int i) Return the AttributeSet for a given character at a given index
Rectangle | getCharacterBounds(int i) Determine the bounding box of the character at the given index into the string.
int | getCharCount() Return the number of characters (valid indicies)
int | getIndexAtPoint(Point p) Given a point in local coordinates, return the zero-based index of the character under that Point.
String | getSelectedText() Returns the portion of the text that is selected.
int | getSelectionEnd() Returns the end offset within the selected text.
int | getSelectionStart() Returns the start offset within the selected text.
String | getTitledBorderText() Returns the titled border text
String | getToolTipText() Returns the tool tip text
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleStateSet, getBorderTitle, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleSelection, getAccessibleTable, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JLabel.AccessibleJLabel

protected JLabel.AccessibleJLabel()
Method Detail

getAccessibleName

public String getAccessibleName()
Get the accessible name of this object.

Overrides:
getAccessibleName in class JComponent.AccessibleJComponent
Returns:
the localized name of the object -- can be null if this object does not have a name
See Also:
AccessibleContext.setAccessibleName(java.lang.String)

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleIcon

public AccessibleIcon[] getAccessibleIcon()
Get the AccessibleIcons associated with this object if one or more exist. Otherwise return null.

Overrides:
getAccessibleIcon in class AccessibleContext
Returns:
an array of AccessibleIcon if supported by object; otherwise return null
Since:
1.3
See Also:
AccessibleIcon

getAccessibleRelationSet

public AccessibleRelationSet getAccessibleRelationSet()
Get the AccessibleRelationSet associated with this object if one exists. Otherwise return null.

Overrides:
getAccessibleRelationSet in class AccessibleContext
Returns:
an AccessibleRelationSet if supported by object; otherwise return null
Since:
1.3
See Also:
AccessibleRelation

getAccessibleText

public AccessibleText getAccessibleText()
Description copied from class: AccessibleContext
Gets the AccessibleText associated with this object presenting text on the display.

Overrides:
getAccessibleText in class AccessibleContext
Returns:
AccessibleText if supported by object; else return null
See Also:
AccessibleText

getIndexAtPoint

public int getIndexAtPoint(Point p)
Given a point in local coordinates, return the zero-based index of the character under that Point. If the point is invalid, this method returns -1.

Specified by:
getIndexAtPoint in interface AccessibleText
Parameters:
p - the Point in local coordinates
Returns:
the zero-based index of the character under Point p; if Point is invalid returns -1.
Since:
1.3

getCharacterBounds

public Rectangle getCharacterBounds(int i)
Determine the bounding box of the character at the given index into the string. The bounds are returned in local coordinates. If the index is invalid an empty rectangle is returned.

Specified by:
getCharacterBounds in interface AccessibleText
Parameters:
i - the index into the String
Returns:
the screen coordinates of the character's the bounding box, if index is invalid returns an empty rectangle.
Since:
1.3

getCharCount

public int getCharCount()
Return the number of characters (valid indicies)

Specified by:
getCharCount in interface AccessibleText
Returns:
the number of characters
Since:
1.3

getCaretPosition

public int getCaretPosition()
Return the zero-based offset of the caret. Note: That to the right of the caret will have the same index value as the offset (the caret is between two characters).

Specified by:
getCaretPosition in interface AccessibleText
Returns:
the zero-based offset of the caret.
Since:
1.3

getAtIndex

public String getAtIndex(int part,
                         int index)
Returns the String at a given index.

Specified by:
getAtIndex in interface AccessibleText
Parameters:
part - the AccessibleText.CHARACTER, AccessibleText.WORD, or AccessibleText.SENTENCE to retrieve
index - an index within the text >= 0
Returns:
the letter, word, or sentence, null for an invalid index or part
Since:
1.3

getAfterIndex

public String getAfterIndex(int part,
                            int index)
Returns the String after a given index.

Specified by:
getAfterIndex in interface AccessibleText
Parameters:
part - the AccessibleText.CHARACTER, AccessibleText.WORD, or AccessibleText.SENTENCE to retrieve
index - an index within the text >= 0
Returns:
the letter, word, or sentence, null for an invalid index or part
Since:
1.3

getBeforeIndex

public String getBeforeIndex(int part,
                             int index)
Returns the String before a given index.

Specified by:
getBeforeIndex in interface AccessibleText
Parameters:
part - the AccessibleText.CHARACTER, AccessibleText.WORD, or AccessibleText.SENTENCE to retrieve
index - an index within the text >= 0
Returns:
the letter, word, or sentence, null for an invalid index or part
Since:
1.3

getCharacterAttribute

public AttributeSet getCharacterAttribute(int i)
Return the AttributeSet for a given character at a given index

Specified by:
getCharacterAttribute in interface AccessibleText
Parameters:
i - the zero-based index into the text
Returns:
the AttributeSet of the character
Since:
1.3

getSelectionStart

public int getSelectionStart()
Returns the start offset within the selected text. If there is no selection, but there is a caret, the start and end offsets will be the same.

Specified by:
getSelectionStart in interface AccessibleText
Returns:
the index into the text of the start of the selection
Since:
1.3

getSelectionEnd

public int getSelectionEnd()
Returns the end offset within the selected text. If there is no selection, but there is a caret, the start and end offsets will be the same.

Specified by:
getSelectionEnd in interface AccessibleText
Returns:
the index into teh text of the end of the selection
Since:
1.3

getSelectedText

public String getSelectedText()
Returns the portion of the text that is selected.

Specified by:
getSelectedText in interface AccessibleText
Returns:
the String portion of the text that is selected
Since:
1.3

getToolTipText

public String getToolTipText()
Returns the tool tip text

Specified by:
getToolTipText in interface AccessibleExtendedComponent
Overrides:
getToolTipText in class JComponent.AccessibleJComponent
Returns:
the tool tip text, if supported, of the object; otherwise, null
Since:
1.4

getTitledBorderText

public String getTitledBorderText()
Returns the titled border text

Specified by:
getTitledBorderText in interface AccessibleExtendedComponent
Overrides:
getTitledBorderText in class JComponent.AccessibleJComponent
Returns:
the titled border text, if supported, of the object; otherwise, null
Since:
1.4

getAccessibleKeyBinding

public AccessibleKeyBinding getAccessibleKeyBinding()
Returns key bindings associated with this object

Specified by:
getAccessibleKeyBinding in interface AccessibleExtendedComponent
Overrides:
getAccessibleKeyBinding in class JComponent.AccessibleJComponent
Returns:
the key bindings, if supported, of the object; otherwise, null
Since:
1.4
See Also:
AccessibleKeyBinding
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JLayeredPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JLayeredPane

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JLayeredPane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
Direct Known Subclasses:
JDesktopPane
public class JLayeredPane
extends JComponent
implements Accessible

JLayeredPane adds depth to a JFC/Swing container, allowing components to overlap each other when needed. An Integer object specifies each component's depth in the container, where higher-numbered components sit "on top" of other components. For task-oriented documentation and examples of using layered panes see How to Use a Layered Pane, a section in The Java Tutorial.

The following text describes this image.

For convenience, JLayeredPane divides the depth-range into several different layers. Putting a component into one of those layers makes it easy to ensure that components overlap properly, without having to worry about specifying numbers for specific depths:

DEFAULT_LAYER
The standard layer, where most components go. This the bottommost layer.
PALETTE_LAYER
The palette layer sits over the default layer. Useful for floating toolbars and palettes, so they can be positioned above other components.
MODAL_LAYER
The layer used for modal dialogs. They will appear on top of any toolbars, palettes, or standard components in the container.
POPUP_LAYER
The popup layer displays above dialogs. That way, the popup windows associated with combo boxes, tooltips, and other help text will appear above the component, palette, or dialog that generated them.
DRAG_LAYER
When dragging a component, reassigning it to the drag layer ensures that it is positioned over every other component in the container. When finished dragging, it can be reassigned to its normal layer.
The JLayeredPane methods moveToFront(Component), moveToBack(Component) and setPosition can be used to reposition a component within its layer. The setLayer method can also be used to change the component's current layer.

Details

JLayeredPane manages its list of children like Container, but allows for the definition of a several layers within itself. Children in the same layer are managed exactly like the normal Container object, with the added feature that when children components overlap, children in higher layers display above the children in lower layers.

Each layer is a distinct integer number. The layer attribute can be set on a Component by passing an Integer object during the add call.
For example:

     layeredPane.add(child, JLayeredPane.DEFAULT_LAYER);
 or
     layeredPane.add(child, new Integer(10));
The layer attribute can also be set on a Component by calling
     layeredPaneParent.setLayer(child, 10)
on the JLayeredPane that is the parent of component. The layer should be set before adding the child to the parent.

Higher number layers display above lower number layers. So, using numbers for the layers and letters for individual components, a representative list order would look like this:

       5a, 5b, 5c, 2a, 2b, 2c, 1a
where the leftmost components are closest to the top of the display.

A component can be moved to the top or bottom position within its layer by calling moveToFront or moveToBack.

The position of a component within a layer can also be specified directly. Valid positions range from 0 up to one less than the number of components in that layer. A value of -1 indicates the bottommost position. A value of 0 indicates the topmost position. Unlike layer numbers, higher position values are lower in the display.

Note: This sequence (defined by java.awt.Container) is the reverse of the layer numbering sequence. Usually though, you will use moveToFront, moveToBack, and setLayer.
Here are some examples using the method add(Component, layer, position): Calling add(5x, 5, -1) results in:
       5a, 5b, 5c, 5x, 2a, 2b, 2c, 1a
Calling add(5z, 5, 2) results in:
       5a, 5b, 5z, 5c, 5x, 2a, 2b, 2c, 1a
Calling add(3a, 3, 7) results in:
       5a, 5b, 5z, 5c, 5x, 3a, 2a, 2b, 2c, 1a
Using normal paint/event mechanics results in 1a appearing at the bottom and 5a being above all other components.

Note: that these layers are simply a logical construct and LayoutManagers will affect all child components of this container without regard for layer settings.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class JLayeredPane.AccessibleJLayeredPane
This class implements accessibility support for the JLayeredPane class.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
static Integer | DEFAULT_LAYER Convenience object defining the Default layer.
static Integer | DRAG_LAYER Convenience object defining the Drag layer.
static Integer | FRAME_CONTENT_LAYER Convenience object defining the Frame Content layer.
static String | LAYER_PROPERTY Bound property
static Integer | MODAL_LAYER Convenience object defining the Modal layer.
static Integer | PALETTE_LAYER Convenience object defining the Palette layer.
static Integer | POPUP_LAYER Convenience object defining the Popup layer.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JLayeredPane()
Create a new JLayeredPane
Method Summary
protected void | addImpl(Component comp, Object constraints, int index) Adds the specified component to this container at the specified index.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JLayeredPane.
int | getComponentCountInLayer(int layer) Returns the number of children currently in the specified layer.
Component[] | getComponentsInLayer(int layer) Returns an array of the components in the specified layer.
protected Hashtable<Component,Integer> | getComponentToLayer() Returns the hashtable that maps components to layers.
int | getIndexOf(Component c) Returns the index of the specified Component.
int | getLayer(Component c) Returns the layer attribute for the specified Component.
static int | getLayer(JComponent c) Gets the layer property for a JComponent, it does not cause any side effects like setLayer().
static JLayeredPane | getLayeredPaneAbove(Component c) Convenience method that returns the first JLayeredPane which contains the specified component.
protected Integer | getObjectForLayer(int layer) Returns the Integer object associated with a specified layer.
int | getPosition(Component c) Get the relative position of the component within its layer.
int | highestLayer() Returns the highest layer value from all current children.
protected int | insertIndexForLayer(int layer, int position) Primitive method that determines the proper location to insert a new child based on layer and position requests.
boolean | isOptimizedDrawingEnabled() Returns false if components in the pane can overlap, which makes optimized drawing impossible.
int | lowestLayer() Returns the lowest layer value from all current children.
void | moveToBack(Component c) Moves the component to the bottom of the components in its current layer (position -1).
void | moveToFront(Component c) Moves the component to the top of the components in its current layer (position 0).
void | paint(Graphics g) Paints this JLayeredPane within the specified graphics context.
protected String | paramString() Returns a string representation of this JLayeredPane.
static void | putLayer(JComponent c, int layer) Sets the layer property on a JComponent.
void | remove(int index) Remove the indexed component from this pane.
void | removeAll() Removes all the components from this container.
void | setLayer(Component c, int layer) Sets the layer attribute on the specified component, making it the bottommost component in that layer.
void | setLayer(Component c, int layer, int position) Sets the layer attribute for the specified component and also sets its position within that layer.
void | setPosition(Component c, int position) Moves the component to position within its current layer, where 0 is the topmost position within the layer and -1 is the bottommost position.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update, updateUI
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_LAYER

public static final Integer DEFAULT_LAYER
Convenience object defining the Default layer. Equivalent to new Integer(0).

PALETTE_LAYER

public static final Integer PALETTE_LAYER
Convenience object defining the Palette layer. Equivalent to new Integer(100).

MODAL_LAYER

public static final Integer MODAL_LAYER
Convenience object defining the Modal layer. Equivalent to new Integer(200).

POPUP_LAYER

public static final Integer POPUP_LAYER
Convenience object defining the Popup layer. Equivalent to new Integer(300).

DRAG_LAYER

public static final Integer DRAG_LAYER
Convenience object defining the Drag layer. Equivalent to new Integer(400).

FRAME_CONTENT_LAYER

public static final Integer FRAME_CONTENT_LAYER
Convenience object defining the Frame Content layer. This layer is normally only use to positon the contentPane and menuBar components of JFrame. Equivalent to new Integer(-30000).

See Also:
JFrame

LAYER_PROPERTY

public static final String LAYER_PROPERTY
Bound property

See Also:
Constant Field Values
Constructor Detail

JLayeredPane

public JLayeredPane()
Create a new JLayeredPane

Method Detail

addImpl

protected void addImpl(Component comp,
                       Object constraints,
                       int index)
Description copied from class: Container
Adds the specified component to this container at the specified index. This method also notifies the layout manager to add the component to this container's layout using the specified constraints object via the addLayoutComponent method.

The constraints are defined by the particular layout manager being used. For example, the BorderLayout class defines five constraints: BorderLayout.NORTH, BorderLayout.SOUTH, BorderLayout.EAST, BorderLayout.WEST, and BorderLayout.CENTER.

The GridBagLayout class requires a GridBagConstraints object. Failure to pass the correct type of constraints object results in an IllegalArgumentException.

If the current layout manager implements LayoutManager2, then LayoutManager2.addLayoutComponent(Component,Object) is invoked on it. If the current layout manager does not implement LayoutManager2, and constraints is a String, then LayoutManager.addLayoutComponent(String,Component) is invoked on it.

If the component is not an ancestor of this container and has a non-null parent, it is removed from its current parent before it is added to this container.

This is the method to override if a program needs to track every add request to a container as all other add methods defer to this one. An overriding method should usually include a call to the superclass's version of the method:

super.addImpl(comp, constraints, index)

Overrides:
addImpl in class Container
Parameters:
comp - the component to be added
constraints - an object expressing layout constraints for this component
index - the position in the container's list at which to insert the component, where -1 means append to the end
See Also:
Container.add(Component),
Container.add(Component, int),
Container.add(Component, java.lang.Object),
LayoutManager,
LayoutManager2

remove

public void remove(int index)
Remove the indexed component from this pane. This is the absolute index, ignoring layers.

Overrides:
remove in class Container
Parameters:
index - an int specifying the component to remove
See Also:
getIndexOf(java.awt.Component)

removeAll

public void removeAll()
Removes all the components from this container.

Overrides:
removeAll in class Container
Since:
1.5
See Also:
Container.add(java.awt.Component), Container.remove(int)

isOptimizedDrawingEnabled

public boolean isOptimizedDrawingEnabled()
Returns false if components in the pane can overlap, which makes optimized drawing impossible. Otherwise, returns true.

Overrides:
isOptimizedDrawingEnabled in class JComponent
Returns:
false if components can overlap, else true
See Also:
JComponent.isOptimizedDrawingEnabled()

putLayer

public static void putLayer(JComponent c,
                            int layer)
Sets the layer property on a JComponent. This method does not cause any side effects like setLayer() (painting, add/remove, etc). Normally you should use the instance method setLayer(), in order to get the desired side-effects (like repainting).

Parameters:
c - the JComponent to move
layer - an int specifying the layer to move it to
See Also:
setLayer(java.awt.Component, int)

getLayer

public static int getLayer(JComponent c)
Gets the layer property for a JComponent, it does not cause any side effects like setLayer(). (painting, add/remove, etc) Normally you should use the instance method getLayer().

Parameters:
c - the JComponent to check
Returns:
an int specifying the component's layer

getLayeredPaneAbove

public static JLayeredPane getLayeredPaneAbove(Component c)
Convenience method that returns the first JLayeredPane which contains the specified component. Note that all JFrames have a JLayeredPane at their root, so any component in a JFrame will have a JLayeredPane parent.

Parameters:
c - the Component to check
Returns:
the JLayeredPane that contains the component, or null if no JLayeredPane is found in the component hierarchy
See Also:
JFrame, JRootPane

setLayer

public void setLayer(Component c,
                     int layer)
Sets the layer attribute on the specified component, making it the bottommost component in that layer. Should be called before adding to parent.

Parameters:
c - the Component to set the layer for
layer - an int specifying the layer to set, where lower numbers are closer to the bottom

setLayer

public void setLayer(Component c,
                     int layer,
                     int position)
Sets the layer attribute for the specified component and also sets its position within that layer.

Parameters:
c - the Component to set the layer for
layer - an int specifying the layer to set, where lower numbers are closer to the bottom
position - an int specifying the position within the layer, where 0 is the topmost position and -1 is the bottommost position

getLayer

public int getLayer(Component c)
Returns the layer attribute for the specified Component.

Parameters:
c - the Component to check
Returns:
an int specifying the component's current layer

getIndexOf

public int getIndexOf(Component c)
Returns the index of the specified Component. This is the absolute index, ignoring layers. Index numbers, like position numbers, have the topmost component at index zero. Larger numbers are closer to the bottom.

Parameters:
c - the Component to check
Returns:
an int specifying the component's index

moveToFront

public void moveToFront(Component c)
Moves the component to the top of the components in its current layer (position 0).

Parameters:
c - the Component to move
See Also:
setPosition(Component, int)

moveToBack

public void moveToBack(Component c)
Moves the component to the bottom of the components in its current layer (position -1).

Parameters:
c - the Component to move
See Also:
setPosition(Component, int)

setPosition

public void setPosition(Component c,
                        int position)
Moves the component to position within its current layer, where 0 is the topmost position within the layer and -1 is the bottommost position.

Note: Position numbering is defined by java.awt.Container, and is the opposite of layer numbering. Lower position numbers are closer to the top (0 is topmost), and higher position numbers are closer to the bottom.

Parameters:
c - the Component to move
position - an int in the range -1..N-1, where N is the number of components in the component's current layer

getPosition

public int getPosition(Component c)
Get the relative position of the component within its layer.

Parameters:
c - the Component to check
Returns:
an int giving the component's position, where 0 is the topmost position and the highest index value = the count count of components at that layer, minus 1
See Also:
getComponentCountInLayer(int)

highestLayer

public int highestLayer()
Returns the highest layer value from all current children. Returns 0 if there are no children.

Returns:
an int indicating the layer of the topmost component in the pane, or zero if there are no children

lowestLayer

public int lowestLayer()
Returns the lowest layer value from all current children. Returns 0 if there are no children.

Returns:
an int indicating the layer of the bottommost component in the pane, or zero if there are no children

getComponentCountInLayer

public int getComponentCountInLayer(int layer)
Returns the number of children currently in the specified layer.

Parameters:
layer - an int specifying the layer to check
Returns:
an int specifying the number of components in that layer

getComponentsInLayer

public Component[] getComponentsInLayer(int layer)
Returns an array of the components in the specified layer.

Parameters:
layer - an int specifying the layer to check
Returns:
an array of Components contained in that layer

paint

public void paint(Graphics g)
Paints this JLayeredPane within the specified graphics context.

Overrides:
paint in class JComponent
Parameters:
g - the Graphics context within which to paint
See Also:
JComponent.paintComponent(java.awt.Graphics),
JComponent.paintBorder(java.awt.Graphics),
JComponent.paintChildren(java.awt.Graphics),
JComponent.getComponentGraphics(java.awt.Graphics),
JComponent.repaint(long, int, int, int, int)

getComponentToLayer

protected Hashtable<Component,Integer> getComponentToLayer()
Returns the hashtable that maps components to layers.

Returns:
the Hashtable used to map components to their layers

getObjectForLayer

protected Integer getObjectForLayer(int layer)
Returns the Integer object associated with a specified layer.

Parameters:
layer - an int specifying the layer
Returns:
an Integer object for that layer

insertIndexForLayer

protected int insertIndexForLayer(int layer,
                                  int position)
Primitive method that determines the proper location to insert a new child based on layer and position requests.

Parameters:
layer - an int specifying the layer
position - an int specifying the position within the layer
Returns:
an int giving the (absolute) insertion-index
See Also:
getIndexOf(java.awt.Component)

paramString

protected String paramString()
Returns a string representation of this JLayeredPane. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JLayeredPane.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JLayeredPane. For layered panes, the AccessibleContext takes the form of an AccessibleJLayeredPane. A new AccessibleJLayeredPane instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJLayeredPane that serves as the AccessibleContext of this JLayeredPane
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JLayeredPane.AccessibleJLayeredPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JLayeredPane.AccessibleJLayeredPane

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JLayeredPane.AccessibleJLayeredPane
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent
Enclosing class:
JLayeredPane
protected class JLayeredPane.AccessibleJLayeredPane
extends JComponent.AccessibleJComponent

This class implements accessibility support for the JLayeredPane class. It provides an implementation of the Java Accessibility API appropriate to layered pane user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JLayeredPane.AccessibleJLayeredPane()
Method Summary
 AccessibleRole getAccessibleRole()
Get the role of this object.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JLayeredPane.AccessibleJLayeredPane

protected JLayeredPane.AccessibleJLayeredPane()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JList

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JList

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JList
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable
public class JList
extends JComponent
implements Scrollable, Accessible

A component that displays a list of objects and allows the user to select one or more items. A separate model, ListModel, maintains the contents of the list.

It's easy to display an array or Vector of objects, using the JList constructor that automatically builds a read-only ListModel instance for you:

 // Create a JList that displays strings from an array

 String[] data = {"one", "two", "three", "four"};
 JList myList = new JList(data);

 // Create a JList that displays the superclasses of JList.class, by
 // creating it with a Vector populated with this data

 Vector superClasses = new Vector();
 Class rootClass = javax.swing.JList.class;
 for(Class cls = rootClass; cls != null; cls = cls.getSuperclass()) {
     superClasses.addElement(cls);
 }
 JList myList = new JList(superClasses);

 // The automatically created model is stored in JList's "model"
 // property, which you can retrieve

 ListModel model = myList.getModel();
 for(int i = 0; i < model.getSize(); i++) {
     System.out.println(model.getElementAt(i));
 }

A ListModel can be supplied directly to a JList by way of a constructor or the setModel method. The contents need not be static - the number of items, and the values of items can change over time. A correct ListModel implementation notifies the set of javax.swing.event.ListDataListeners that have been added to it, each time a change occurs. These changes are characterized by a javax.swing.event.ListDataEvent, which identifies the range of list indices that have been modified, added, or removed. JList's ListUI is responsible for keeping the visual representation up to date with changes, by listening to the model.

Simple, dynamic-content, JList applications can use the DefaultListModel class to maintain list elements. This class implements the ListModel interface and also provides a java.util.Vector-like API. Applications that need a more custom ListModel implementation may instead wish to subclass AbstractListModel, which provides basic support for managing and notifying listeners. For example, a read-only implementation of AbstractListModel:

 // This list model has about 2^16 elements.  Enjoy scrolling.

 ListModel bigData = new AbstractListModel() {
     public int getSize() { return Short.MAX_VALUE; }
     public Object getElementAt(int index) { return "Index " + index; }
 };

The selection state of a JList is managed by another separate model, an instance of ListSelectionModel. JList is initialized with a selection model on construction, and also contains methods to query or set this selection model. Additionally, JList provides convenient methods for easily managing the selection. These methods, such as setSelectedIndex and getSelectedValue, are cover methods that take care of the details of interacting with the selection model. By default, JList's selection model is configured to allow any combination of items to be selected at a time; selection mode MULTIPLE_INTERVAL_SELECTION. The selection mode can be changed on the selection model directly, or via JList's cover method. Responsibility for updating the selection model in response to user gestures lies with the list's ListUI.

A correct ListSelectionModel implementation notifies the set of javax.swing.event.ListSelectionListeners that have been added to it each time a change to the selection occurs. These changes are characterized by a javax.swing.event.ListSelectionEvent, which identifies the range of the selection change.

The preferred way to listen for changes in list selection is to add ListSelectionListeners directly to the JList. JList then takes care of listening to the the selection model and notifying your listeners of change.

Responsibility for listening to selection changes in order to keep the list's visual representation up to date lies with the list's ListUI.

Painting of cells in a JList is handled by a delegate called a cell renderer, installed on the list as the cellRenderer property. The renderer provides a java.awt.Component that is used like a "rubber stamp" to paint the cells. Each time a cell needs to be painted, the list's ListUI asks the cell renderer for the component, moves it into place, and has it paint the contents of the cell by way of its paint method. A default cell renderer, which uses a JLabel component to render, is installed by the lists's ListUI. You can substitute your own renderer using code like this:

  // Display an icon and a string for each object in the list.

 class MyCellRenderer extends JLabel implements ListCellRenderer {
     final static ImageIcon longIcon = new ImageIcon("long.gif");
     final static ImageIcon shortIcon = new ImageIcon("short.gif");

     // This is the only method defined by ListCellRenderer.
     // We just reconfigure the JLabel each time we're called.

     public Component getListCellRendererComponent(
       JList list,              // the list
       Object value,            // value to display
       int index,               // cell index
       boolean isSelected,      // is the cell selected
       boolean cellHasFocus)    // does the cell have focus
     {
         String s = value.toString();
         setText(s);
         setIcon((s.length() > 10) ? longIcon : shortIcon);
         if (isSelected) {
             setBackground(list.getSelectionBackground());
             setForeground(list.getSelectionForeground());
         } else {
             setBackground(list.getBackground());
             setForeground(list.getForeground());
         }
         setEnabled(list.isEnabled());
         setFont(list.getFont());
         setOpaque(true);
         return this;
     }
 }

 myList.setCellRenderer(new MyCellRenderer());

Another job for the cell renderer is in helping to determine sizing information for the list. By default, the list's ListUI determines the size of cells by asking the cell renderer for its preferred size for each list item. This can be expensive for large lists of items. To avoid these calculations, you can set a fixedCellWidth and fixedCellHeight on the list, or have these values calculated automatically based on a single prototype value:

 JList bigDataList = new JList(bigData);

 // We don't want the JList implementation to compute the width
 // or height of all of the list cells, so we give it a string
 // that's as big as we'll need for any cell.  It uses this to
 // compute values for the fixedCellWidth and fixedCellHeight
 // properties.

 bigDataList.setPrototypeCellValue("Index 1234567890");

JList doesn't implement scrolling directly. To create a list that scrolls, make it the viewport view of a JScrollPane. For example:

 JScrollPane scrollPane = new JScrollPane(myList);

 // Or in two steps:
 JScrollPane scrollPane = new JScrollPane();
 scrollPane.getViewport().setView(myList);

JList doesn't provide any special handling of double or triple (or N) mouse clicks, but it's easy to add a MouseListener if you wish to take action on these events. Use the locationToIndex method to determine what cell was clicked. For example:

 MouseListener mouseListener = new MouseAdapter() {
     public void mouseClicked(MouseEvent e) {
         if (e.getClickCount() == 2) {
             int index = list.locationToIndex(e.getPoint());
             System.out.println("Double clicked on Item " + index);
          }
     }
 };
 list.addMouseListener(mouseListener);

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See How to Use Lists in The Java Tutorial for further documentation. Also see the article Advanced JList Programming in The Swing Connection.

See Also:
ListModel, AbstractListModel, DefaultListModel, ListSelectionModel, DefaultListSelectionModel, ListCellRenderer, DefaultListCellRenderer

Nested Class Summary
protected class | JList.AccessibleJList This class implements accessibility support for the JList class.
static class | JList.DropLocation A subclass of TransferHandler.DropLocation representing a drop location for a JList.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
static int | HORIZONTAL_WRAP Indicates a "newspaper style" layout with cells flowing horizontally then vertically.
static int | VERTICAL Indicates a vertical layout of cells, in a single column; the default layout.
static int | VERTICAL_WRAP Indicates a "newspaper style" layout with cells flowing vertically then horizontally.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JList()
Constructs a JList with an empty, read-only, model.
JList(ListModel dataModel)
Constructs a JList that displays elements from the specified, non-null, model.
JList(Object[] listData)
Constructs a JList that displays the elements in the specified array.
JList(Vector<?> listData)
Constructs a JList that displays the elements in the specified Vector.
Method Summary
void | addListSelectionListener(ListSelectionListener listener) Adds a listener to the list, to be notified each time a change to the selection occurs; the preferred way of listening for selection state changes.
void | addSelectionInterval(int anchor, int lead) Sets the selection to be the union of the specified interval with current selection.
void | clearSelection() Clears the selection; after calling this method, isSelectionEmpty will return true.
protected ListSelectionModel | createSelectionModel() Returns an instance of DefaultListSelectionModel; called during construction to initialize the list's selection model property.
void | ensureIndexIsVisible(int index) Scrolls the list within an enclosing viewport to make the specified cell completely visible.
protected void | fireSelectionValueChanged(int firstIndex, int lastIndex, boolean isAdjusting) Notifies ListSelectionListeners added directly to the list of selection changes made to the selection model.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JList.
int | getAnchorSelectionIndex() Returns the anchor selection index.
Rectangle | getCellBounds(int index0, int index1) Returns the bounding rectangle, in the list's coordinate system, for the range of cells specified by the two indices.
ListCellRenderer | getCellRenderer() Returns the object responsible for painting list items.
boolean | getDragEnabled() Returns whether or not automatic drag handling is enabled.
JList.DropLocation | getDropLocation() Returns the location that this component should visually indicate as the drop location during a DnD operation over the component, or null if no location is to currently be shown.
DropMode | getDropMode() Returns the drop mode for this component.
int | getFirstVisibleIndex() Returns the smallest list index that is currently visible.
int | getFixedCellHeight() Returns the value of the fixedCellHeight property.
int | getFixedCellWidth() Returns the value of the fixedCellWidth property.
int | getLastVisibleIndex() Returns the largest list index that is currently visible.
int | getLayoutOrientation() Returns the layout orientation property for the list: VERTICAL if the layout is a single column of cells, VERTICAL_WRAP if the layout is "newspaper style" with the content flowing vertically then horizontally, or HORIZONTAL_WRAP if the layout is "newspaper style" with the content flowing horizontally then vertically.
int | getLeadSelectionIndex() Returns the lead selection index.
ListSelectionListener[] | getListSelectionListeners() Returns an array of all the ListSelectionListeners added to this JList by way of addListSelectionListener.
int | getMaxSelectionIndex() Returns the largest selected cell index, or -1 if the selection is empty.
int | getMinSelectionIndex() Returns the smallest selected cell index, or -1 if the selection is empty.
ListModel | getModel() Returns the data model that holds the list of items displayed by the JList component.
int | getNextMatch(String prefix, int startIndex, Position.Bias bias) Returns the next list element whose toString value starts with the given prefix.
Dimension | getPreferredScrollableViewportSize() Computes the size of viewport needed to display visibleRowCount rows.
Object | getPrototypeCellValue() Returns the "prototypical" cell value -- a value used to calculate a fixed width and height for cells.
int | getScrollableBlockIncrement(Rectangle visibleRect, int orientation, int direction) Returns the distance to scroll to expose the next or previous block.
boolean | getScrollableTracksViewportHeight() Returns true if this JList is displayed in a JViewport and the viewport is taller than the list's preferred height, or if the layout orientation is VERTICAL_WRAP and visibleRowCount <= 0; otherwise returns false.
boolean | getScrollableTracksViewportWidth() Returns true if this JList is displayed in a JViewport and the viewport is wider than the list's preferred width, or if the layout orientation is HORIZONTAL_WRAP and visibleRowCount <= 0; otherwise returns false.
int | getScrollableUnitIncrement(Rectangle visibleRect, int orientation, int direction) Returns the distance to scroll to expose the next or previous row (for vertical scrolling) or column (for horizontal scrolling).
int | getSelectedIndex() Returns the smallest selected cell index; the selection when only a single item is selected in the list.
int[] | getSelectedIndices() Returns an array of all of the selected indices, in increasing order.
Object | getSelectedValue() Returns the value for the smallest selected cell index; the selected value when only a single item is selected in the list.
Object[] | getSelectedValues() Returns an array of all the selected values, in increasing order based on their indices in the list.
Color | getSelectionBackground() Returns the color used to draw the background of selected items.
Color | getSelectionForeground() Returns the color used to draw the foreground of selected items.
int | getSelectionMode() Returns the current selection mode for the list.
ListSelectionModel | getSelectionModel() Returns the current selection model.
String | getToolTipText(MouseEvent event) Returns the tooltip text to be used for the given event.
ListUI | getUI() Returns the ListUI, the look and feel object that renders this component.
String | getUIClassID() Returns "ListUI", the UIDefaults key used to look up the name of the javax.swing.plaf.ListUI class that defines the look and feel for this component.
boolean | getValueIsAdjusting() Returns the value of the selection model's isAdjusting property.
int | getVisibleRowCount() Returns the value of the visibleRowCount property.
Point | indexToLocation(int index) Returns the origin of the specified item in the list's coordinate system.
boolean | isSelectedIndex(int index) Returns true if the specified index is selected, else false.
boolean | isSelectionEmpty() Returns true if nothing is selected, else false.
int | locationToIndex(Point location) Returns the cell index closest to the given location in the list's coordinate system.
protected String | paramString() Returns a String representation of this JList.
void | removeListSelectionListener(ListSelectionListener listener) Removes a selection listener from the list.
void | removeSelectionInterval(int index0, int index1) Sets the selection to be the set difference of the specified interval and the current selection.
void | setCellRenderer(ListCellRenderer cellRenderer) Sets the delegate that is used to paint each cell in the list.
void | setDragEnabled(boolean b) Turns on or off automatic drag handling.
void | setDropMode(DropMode dropMode) Sets the drop mode for this component.
void | setFixedCellHeight(int height) Sets a fixed value to be used for the height of every cell in the list.
void | setFixedCellWidth(int width) Sets a fixed value to be used for the width of every cell in the list.
void | setLayoutOrientation(int layoutOrientation) Defines the way list cells are layed out.
void | setListData(Object[] listData) Constructs a read-only ListModel from an array of objects, and calls setModel with this model.
void | setListData(Vector<?> listData) Constructs a read-only ListModel from a Vector and calls setModel with this model.
void | setModel(ListModel model) Sets the model that represents the contents or "value" of the list, notifies property change listeners, and then clears the list's selection.
void | setPrototypeCellValue(Object prototypeCellValue) Sets the prototypeCellValue property, and then (if the new value is non-null), computes the fixedCellWidth and fixedCellHeight properties by requesting the cell renderer component for the given value (and index 0) from the cell renderer, and using that component's preferred size.
void | setSelectedIndex(int index) Selects a single cell.
void | setSelectedIndices(int[] indices) Changes the selection to be the set of indices specified by the given array.
void | setSelectedValue(Object anObject, boolean shouldScroll) Selects the specified object from the list.
void | setSelectionBackground(Color selectionBackground) Sets the color used to draw the background of selected items, which cell renderers can use fill selected cells.
void | setSelectionForeground(Color selectionForeground) Sets the color used to draw the foreground of selected items, which cell renderers can use to render text and graphics.
void | setSelectionInterval(int anchor, int lead) Selects the specified interval.
void | setSelectionMode(int selectionMode) Sets the selection mode for the list.
void | setSelectionModel(ListSelectionModel selectionModel) Sets the selectionModel for the list to a non-null ListSelectionModel implementation.
void | setUI(ListUI ui) Sets the ListUI, the look and feel object that renders this component.
void | setValueIsAdjusting(boolean b) Sets the selection model's valueIsAdjusting property.
void | setVisibleRowCount(int visibleRowCount) Sets the visibleRowCount property, which has different meanings depending on the layout orientation: For a VERTICAL layout orientation, this sets the preferred number of rows to display without requiring scrolling; for other orientations, it affects the wrapping of cells.
void | updateUI() Resets the ListUI property by setting it to the value provided by the current look and feel.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

VERTICAL

public static final int VERTICAL
Indicates a vertical layout of cells, in a single column; the default layout.

Since:
1.4
See Also:
setLayoutOrientation(int), Constant Field Values

VERTICAL_WRAP

public static final int VERTICAL_WRAP
Indicates a "newspaper style" layout with cells flowing vertically then horizontally.

Since:
1.4
See Also:
setLayoutOrientation(int), Constant Field Values

HORIZONTAL_WRAP

public static final int HORIZONTAL_WRAP
Indicates a "newspaper style" layout with cells flowing horizontally then vertically.

Since:
1.4
See Also:
setLayoutOrientation(int), Constant Field Values
Constructor Detail

JList

public JList(ListModel dataModel)
Constructs a JList that displays elements from the specified, non-null, model. All JList constructors delegate to this one.

This constructor registers the list with the ToolTipManager, allowing for tooltips to be provided by the cell renderers.

Parameters:
dataModel - the model for the list
Throws:
IllegalArgumentException - if the model is null

JList

public JList(Object[] listData)
Constructs a JList that displays the elements in the specified array. This constructor creates a read-only model for the given array, and then delegates to the constructor that takes a ListModel.

Attempts to pass a null value to this method results in undefined behavior and, most likely, exceptions. The created model references the given array directly. Attempts to modify the array after constructing the list results in undefined behavior.

Parameters:
listData - the array of Objects to be loaded into the data model, non-null

JList

public JList(Vector<?> listData)
Constructs a JList that displays the elements in the specified Vector. This constructor creates a read-only model for the given Vector, and then delegates to the constructor that takes a ListModel.

Attempts to pass a null value to this method results in undefined behavior and, most likely, exceptions. The created model references the given Vector directly. Attempts to modify the Vector after constructing the list results in undefined behavior.

Parameters:
listData - the Vector to be loaded into the data model, non-null

JList

public JList()
Constructs a JList with an empty, read-only, model.

Method Detail

getUI

public ListUI getUI()
Returns the ListUI, the look and feel object that renders this component.

Returns:
the ListUI object that renders this component

setUI

public void setUI(ListUI ui)
Sets the ListUI, the look and feel object that renders this component.

Parameters:
ui - the ListUI object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Resets the ListUI property by setting it to the value provided by the current look and feel. If the current cell renderer was installed by the developer (rather than the look and feel itself), this also causes the cell renderer and its children to be updated, by calling SwingUtilities.updateComponentTreeUI on it.

Overrides:
updateUI in class JComponent
See Also:
UIManager.getUI(javax.swing.JComponent), SwingUtilities.updateComponentTreeUI(java.awt.Component)

getUIClassID

public String getUIClassID()
Returns "ListUI", the UIDefaults key used to look up the name of the javax.swing.plaf.ListUI class that defines the look and feel for this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "ListUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

getPrototypeCellValue

public Object getPrototypeCellValue()
Returns the "prototypical" cell value -- a value used to calculate a fixed width and height for cells. This can be null if there is no such value.

Returns:
the value of the prototypeCellValue property
See Also:
setPrototypeCellValue(java.lang.Object)

setPrototypeCellValue

public void setPrototypeCellValue(Object prototypeCellValue)
Sets the prototypeCellValue property, and then (if the new value is non-null), computes the fixedCellWidth and fixedCellHeight properties by requesting the cell renderer component for the given value (and index 0) from the cell renderer, and using that component's preferred size.

This method is useful when the list is too long to allow the ListUI to compute the width/height of each cell, and there is a single cell value that is known to occupy as much space as any of the others, a so-called prototype.

While all three of the prototypeCellValue, fixedCellHeight, and fixedCellWidth properties may be modified by this method, PropertyChangeEvent notifications are only sent when the prototypeCellValue property changes.

To see an example which sets this property, see the class description above.

The default value of this property is null.

This is a JavaBeans bound property.

Parameters:
prototypeCellValue - the value on which to base fixedCellWidth and fixedCellHeight
See Also:
getPrototypeCellValue(), setFixedCellWidth(int), setFixedCellHeight(int), Container.addPropertyChangeListener(java.beans.PropertyChangeListener)

getFixedCellWidth

public int getFixedCellWidth()
Returns the value of the fixedCellWidth property.

Returns:
the fixed cell width
See Also:
setFixedCellWidth(int)

setFixedCellWidth

public void setFixedCellWidth(int width)
Sets a fixed value to be used for the width of every cell in the list. If width is -1, cell widths are computed in the ListUI by applying getPreferredSize to the cell renderer component for each list element.

The default value of this property is -1.

This is a JavaBeans bound property.

Parameters:
width - the width to be used for all cells in the list
See Also:
setPrototypeCellValue(java.lang.Object), setFixedCellWidth(int), Container.addPropertyChangeListener(java.beans.PropertyChangeListener)

getFixedCellHeight

public int getFixedCellHeight()
Returns the value of the fixedCellHeight property.

Returns:
the fixed cell height
See Also:
setFixedCellHeight(int)

setFixedCellHeight

public void setFixedCellHeight(int height)
Sets a fixed value to be used for the height of every cell in the list. If height is -1, cell heights are computed in the ListUI by applying getPreferredSize to the cell renderer component for each list element.

The default value of this property is -1.

This is a JavaBeans bound property.

Parameters:
height - the height to be used for for all cells in the list
See Also:
setPrototypeCellValue(java.lang.Object), setFixedCellWidth(int), Container.addPropertyChangeListener(java.beans.PropertyChangeListener)

getCellRenderer

public ListCellRenderer getCellRenderer()
Returns the object responsible for painting list items.

Returns:
the value of the cellRenderer property
See Also:
setCellRenderer(javax.swing.ListCellRenderer)

setCellRenderer

public void setCellRenderer(ListCellRenderer cellRenderer)
Sets the delegate that is used to paint each cell in the list. The job of a cell renderer is discussed in detail in the class level documentation.

If the prototypeCellValue property is non-null, setting the cell renderer also causes the fixedCellWidth and fixedCellHeight properties to be re-calculated. Only one PropertyChangeEvent is generated however - for the cellRenderer property.

The default value of this property is provided by the ListUI delegate, i.e. by the look and feel implementation.

This is a JavaBeans bound property.

Parameters:
cellRenderer - the ListCellRenderer that paints list cells
See Also:
getCellRenderer()

getSelectionForeground

public Color getSelectionForeground()
Returns the color used to draw the foreground of selected items. DefaultListCellRenderer uses this color to draw the foreground of items in the selected state, as do the renderers installed by most ListUI implementations.

Returns:
the color to draw the foreground of selected items
See Also:
setSelectionForeground(java.awt.Color), DefaultListCellRenderer

setSelectionForeground

public void setSelectionForeground(Color selectionForeground)
Sets the color used to draw the foreground of selected items, which cell renderers can use to render text and graphics. DefaultListCellRenderer uses this color to draw the foreground of items in the selected state, as do the renderers installed by most ListUI implementations.

The default value of this property is defined by the look and feel implementation.

This is a JavaBeans bound property.

Parameters:
selectionForeground - the Color to use in the foreground for selected list items
See Also:
getSelectionForeground(),
setSelectionBackground(java.awt.Color),
JComponent.setForeground(java.awt.Color),
JComponent.setBackground(java.awt.Color),
JComponent.setFont(java.awt.Font),
DefaultListCellRenderer

getSelectionBackground

public Color getSelectionBackground()
Returns the color used to draw the background of selected items. DefaultListCellRenderer uses this color to draw the background of items in the selected state, as do the renderers installed by most ListUI implementations.

Returns:
the color to draw the background of selected items
See Also:
setSelectionBackground(java.awt.Color), DefaultListCellRenderer

setSelectionBackground

public void setSelectionBackground(Color selectionBackground)
Sets the color used to draw the background of selected items, which cell renderers can use fill selected cells. DefaultListCellRenderer uses this color to fill the background of items in the selected state, as do the renderers installed by most ListUI implementations.

The default value of this property is defined by the look and feel implementation.

This is a JavaBeans bound property.

Parameters:
selectionBackground - the Color to use for the background of selected cells
See Also:
getSelectionBackground(),
setSelectionForeground(java.awt.Color),
JComponent.setForeground(java.awt.Color),
JComponent.setBackground(java.awt.Color),
JComponent.setFont(java.awt.Font),
DefaultListCellRenderer

getVisibleRowCount

public int getVisibleRowCount()
Returns the value of the visibleRowCount property. See the documentation for setVisibleRowCount(int) for details on how to interpret this value.

Returns:
the value of the visibleRowCount property.
See Also:
setVisibleRowCount(int)

setVisibleRowCount

public void setVisibleRowCount(int visibleRowCount)
Sets the visibleRowCount property, which has different meanings depending on the layout orientation: For a VERTICAL layout orientation, this sets the preferred number of rows to display without requiring scrolling; for other orientations, it affects the wrapping of cells.

In VERTICAL orientation:
Setting this property affects the return value of the getPreferredScrollableViewportSize() method, which is used to calculate the preferred size of an enclosing viewport. See that method's documentation for more details.

In HORIZONTAL_WRAP and VERTICAL_WRAP orientations:
This affects how cells are wrapped. See the documentation of setLayoutOrientation(int) for more details.

The default value of this property is 8.

Calling this method with a negative value results in the property being set to 0.

This is a JavaBeans bound property.

Parameters:
visibleRowCount - an integer specifying the preferred number of rows to display without requiring scrolling
See Also:
getVisibleRowCount(), getPreferredScrollableViewportSize(), setLayoutOrientation(int), JComponent.getVisibleRect(), JViewport

getLayoutOrientation

public int getLayoutOrientation()
Returns the layout orientation property for the list: VERTICAL if the layout is a single column of cells, VERTICAL_WRAP if the layout is "newspaper style" with the content flowing vertically then horizontally, or HORIZONTAL_WRAP if the layout is "newspaper style" with the content flowing horizontally then vertically.

Returns:
the value of the layoutOrientation property
Since:
1.4
See Also:
setLayoutOrientation(int)

setLayoutOrientation

public void setLayoutOrientation(int layoutOrientation)
Defines the way list cells are layed out. Consider a JList with five cells. Cells can be layed out in one of the following ways:

 VERTICAL:          0
                    1
                    2
                    3
                    4

 HORIZONTAL_WRAP:   0  1  2
                    3  4

 VERTICAL_WRAP:     0  3
                    1  4
                    2

A description of these layouts follows:

Value

Description

VERTICAL | Cells are layed out vertically in a single column.
HORIZONTAL_WRAP | Cells are layed out horizontally, wrapping to a new row as necessary. If the visibleRowCount property is less than or equal to zero, wrapping is determined by the width of the list; otherwise wrapping is done in such a way as to ensure visibleRowCount rows in the list.
VERTICAL_WRAP | Cells are layed out vertically, wrapping to a new column as necessary. If the visibleRowCount property is less than or equal to zero, wrapping is determined by the height of the list; otherwise wrapping is done at visibleRowCount rows.

The default value of this property is VERTICAL.

Parameters:
layoutOrientation - the new layout orientation, one of: VERTICAL, HORIZONTAL_WRAP or VERTICAL_WRAP
Throws:
IllegalArgumentException - if layoutOrientation isn't one of the allowable values
Since:
1.4
See Also:
getLayoutOrientation(), setVisibleRowCount(int), getScrollableTracksViewportHeight(), getScrollableTracksViewportWidth()

getFirstVisibleIndex

public int getFirstVisibleIndex()
Returns the smallest list index that is currently visible. In a left-to-right componentOrientation, the first visible cell is found closest to the list's upper-left corner. In right-to-left orientation, it is found closest to the upper-right corner. If nothing is visible or the list is empty, -1 is returned. Note that the returned cell may only be partially visible.

Returns:
the index of the first visible cell
See Also:
getLastVisibleIndex(), JComponent.getVisibleRect()

getLastVisibleIndex

public int getLastVisibleIndex()
Returns the largest list index that is currently visible. If nothing is visible or the list is empty, -1 is returned. Note that the returned cell may only be partially visible.

Returns:
the index of the last visible cell
See Also:
getFirstVisibleIndex(), JComponent.getVisibleRect()

ensureIndexIsVisible

public void ensureIndexIsVisible(int index)
Scrolls the list within an enclosing viewport to make the specified cell completely visible. This calls scrollRectToVisible with the bounds of the specified cell. For this method to work, the JList must be within a JViewport.

If the given index is outside the list's range of cells, this method results in nothing.

Parameters:
index - the index of the cell to make visible
See Also:
JComponent.scrollRectToVisible(java.awt.Rectangle), JComponent.getVisibleRect()

setDragEnabled

public void setDragEnabled(boolean b)
Turns on or off automatic drag handling. In order to enable automatic drag handling, this property should be set to true, and the list's TransferHandler needs to be non-null. The default value of the dragEnabled property is false.

The job of honoring this property, and recognizing a user drag gesture, lies with the look and feel implementation, and in particular, the list's ListUI. When automatic drag handling is enabled, most look and feels (including those that subclass BasicLookAndFeel) begin a drag and drop operation whenever the user presses the mouse button over an item and then moves the mouse a few pixels. Setting this property to true can therefore have a subtle effect on how selections behave.

If a look and feel is used that ignores this property, you can still begin a drag and drop operation by calling exportAsDrag on the list's TransferHandler.

Parameters:
b - whether or not to enable automatic drag handling
Throws:
HeadlessException - if b is true and GraphicsEnvironment.isHeadless() returns true
Since:
1.4
See Also:
GraphicsEnvironment.isHeadless(),
getDragEnabled(),
JComponent.setTransferHandler(javax.swing.TransferHandler),
TransferHandler

getDragEnabled

public boolean getDragEnabled()
Returns whether or not automatic drag handling is enabled.

Returns:
the value of the dragEnabled property
Since:
1.4
See Also:
setDragEnabled(boolean)

setDropMode

public final void setDropMode(DropMode dropMode)
Sets the drop mode for this component. For backward compatibility, the default for this property is DropMode.USE_SELECTION. Usage of one of the other modes is recommended, however, for an improved user experience. DropMode.ON, for instance, offers similar behavior of showing items as selected, but does so without affecting the actual selection in the list.

JList supports the following drop modes:

  • DropMode.USE_SELECTION
  • DropMode.ON
  • DropMode.INSERT
  • DropMode.ON_OR_INSERT
The drop mode is only meaningful if this component has a TransferHandler that accepts drops.

Parameters:
dropMode - the drop mode to use
Throws:
IllegalArgumentException - if the drop mode is unsupported or null
Since:
1.6
See Also:
getDropMode(),
getDropLocation(),
JComponent.setTransferHandler(javax.swing.TransferHandler),
TransferHandler

getDropMode

public final DropMode getDropMode()
Returns the drop mode for this component.

Returns:
the drop mode for this component
Since:
1.6
See Also:
setDropMode(javax.swing.DropMode)

getDropLocation

public final JList.DropLocation getDropLocation()
Returns the location that this component should visually indicate as the drop location during a DnD operation over the component, or null if no location is to currently be shown.

This method is not meant for querying the drop location from a TransferHandler, as the drop location is only set after the TransferHandler's canImport has returned and has allowed for the location to be shown.

When this property changes, a property change event with name "dropLocation" is fired by the component.

By default, responsibility for listening for changes to this property and indicating the drop location visually lies with the list's ListUI, which may paint it directly and/or install a cell renderer to do so. Developers wishing to implement custom drop location painting and/or replace the default cell renderer, may need to honor this property.

Returns:
the drop location
Since:
1.6
See Also:
setDropMode(javax.swing.DropMode), TransferHandler.canImport(TransferHandler.TransferSupport)

getNextMatch

public int getNextMatch(String prefix,
                        int startIndex,
                        Position.Bias bias)
Returns the next list element whose toString value starts with the given prefix.

Parameters:
prefix - the string to test for a match
startIndex - the index for starting the search
bias - the search direction, either Position.Bias.Forward or Position.Bias.Backward.
Returns:
the index of the next list element that starts with the prefix; otherwise -1
Throws:
IllegalArgumentException - if prefix is null or startIndex is out of bounds
Since:
1.4

getToolTipText

public String getToolTipText(MouseEvent event)
Returns the tooltip text to be used for the given event. This overrides JComponent's getToolTipText to first check the cell renderer component for the cell over which the event occurred, returning its tooltip text, if any. This implementation allows you to specify tooltip text on the cell level, by using setToolTipText on your cell renderer component.

Note: For JList to properly display the tooltips of its renderers in this manner, JList must be a registered component with the ToolTipManager. This registration is done automatically in the constructor. However, if at a later point JList is unregistered, by way of a call to setToolTipText(null), tips from the renderers will no longer display.

Overrides:
getToolTipText in class JComponent
Parameters:
event - the MouseEvent to fetch the tooltip text for
See Also:
JComponent.setToolTipText(java.lang.String), JComponent.getToolTipText()

locationToIndex

public int locationToIndex(Point location)
Returns the cell index closest to the given location in the list's coordinate system. To determine if the cell actually contains the specified location, compare the point against the cell's bounds, as provided by getCellBounds. This method returns -1 if the model is empty

This is a cover method that delegates to the method of the same name in the list's ListUI. It returns -1 if the list has no ListUI.

Parameters:
location - the coordinates of the point
Returns:
the cell index closest to the given location, or -1

indexToLocation

public Point indexToLocation(int index)
Returns the origin of the specified item in the list's coordinate system. This method returns null if the index isn't valid.

This is a cover method that delegates to the method of the same name in the list's ListUI. It returns null if the list has no ListUI.

Parameters:
index - the cell index
Returns:
the origin of the cell, or null

getCellBounds

public Rectangle getCellBounds(int index0,
                               int index1)
Returns the bounding rectangle, in the list's coordinate system, for the range of cells specified by the two indices. These indices can be supplied in any order.

If the smaller index is outside the list's range of cells, this method returns null. If the smaller index is valid, but the larger index is outside the list's range, the bounds of just the first index is returned. Otherwise, the bounds of the valid range is returned.

This is a cover method that delegates to the method of the same name in the list's ListUI. It returns null if the list has no ListUI.

Parameters:
index0 - the first index in the range
index1 - the second index in the range
Returns:
the bounding rectangle for the range of cells, or null

getModel

public ListModel getModel()
Returns the data model that holds the list of items displayed by the JList component.

Returns:
the ListModel that provides the displayed list of items
See Also:
setModel(javax.swing.ListModel)

setModel

public void setModel(ListModel model)
Sets the model that represents the contents or "value" of the list, notifies property change listeners, and then clears the list's selection.

This is a JavaBeans bound property.

Parameters:
model - the ListModel that provides the list of items for display
Throws:
IllegalArgumentException - if model is null
See Also:
getModel(), clearSelection()

setListData

public void setListData(Object[] listData)
Constructs a read-only ListModel from an array of objects, and calls setModel with this model.

Attempts to pass a null value to this method results in undefined behavior and, most likely, exceptions. The created model references the given array directly. Attempts to modify the array after invoking this method results in undefined behavior.

Parameters:
listData - an array of Objects containing the items to display in the list
See Also:
setModel(javax.swing.ListModel)

setListData

public void setListData(Vector<?> listData)
Constructs a read-only ListModel from a Vector and calls setModel with this model.

Attempts to pass a null value to this method results in undefined behavior and, most likely, exceptions. The created model references the given Vector directly. Attempts to modify the Vector after invoking this method results in undefined behavior.

Parameters:
listData - a Vector containing the items to display in the list
See Also:
setModel(javax.swing.ListModel)

createSelectionModel

protected ListSelectionModel createSelectionModel()
Returns an instance of DefaultListSelectionModel; called during construction to initialize the list's selection model property.

Returns:
a DefaultListSelecitonModel, used to initialize the list's selection model property during construction
See Also:
setSelectionModel(javax.swing.ListSelectionModel), DefaultListSelectionModel

getSelectionModel

public ListSelectionModel getSelectionModel()
Returns the current selection model. The selection model maintains the selection state of the list. See the class level documentation for more details.

Returns:
the ListSelectionModel that maintains the list's selections
See Also:
setSelectionModel(javax.swing.ListSelectionModel), ListSelectionModel

fireSelectionValueChanged

protected void fireSelectionValueChanged(int firstIndex,
                                         int lastIndex,
                                         boolean isAdjusting)
Notifies ListSelectionListeners added directly to the list of selection changes made to the selection model. JList listens for changes made to the selection in the selection model, and forwards notification to listeners added to the list directly, by calling this method.

This method constructs a ListSelectionEvent with this list as the source, and the specified arguments, and sends it to the registered ListSelectionListeners.

Parameters:
firstIndex - the first index in the range, <= lastIndex
lastIndex - the last index in the range, >= firstIndex
isAdjusting - whether or not this is one in a series of multiple events, where changes are still being made
See Also:
addListSelectionListener(javax.swing.event.ListSelectionListener), removeListSelectionListener(javax.swing.event.ListSelectionListener), ListSelectionEvent, EventListenerList

addListSelectionListener

public void addListSelectionListener(ListSelectionListener listener)
Adds a listener to the list, to be notified each time a change to the selection occurs; the preferred way of listening for selection state changes. JList takes care of listening for selection state changes in the selection model, and notifies the given listener of each change. ListSelectionEvents sent to the listener have a source property set to this list.

Parameters:
listener - the ListSelectionListener to add
See Also:
getSelectionModel(), getListSelectionListeners()

removeListSelectionListener

public void removeListSelectionListener(ListSelectionListener listener)
Removes a selection listener from the list.

Parameters:
listener - the ListSelectionListener to remove
See Also:
addListSelectionListener(javax.swing.event.ListSelectionListener), getSelectionModel()

getListSelectionListeners

public ListSelectionListener[] getListSelectionListeners()
Returns an array of all the ListSelectionListeners added to this JList by way of addListSelectionListener.

Returns:
all of the ListSelectionListeners on this list, or an empty array if no listeners have been added
Since:
1.4
See Also:
addListSelectionListener(javax.swing.event.ListSelectionListener)

setSelectionModel

public void setSelectionModel(ListSelectionModel selectionModel)
Sets the selectionModel for the list to a non-null ListSelectionModel implementation. The selection model handles the task of making single selections, selections of contiguous ranges, and non-contiguous selections.

This is a JavaBeans bound property.

Parameters:
selectionModel - the ListSelectionModel that implements the selections
Throws:
IllegalArgumentException - if selectionModel is null
See Also:
getSelectionModel()

setSelectionMode

public void setSelectionMode(int selectionMode)
Sets the selection mode for the list. This is a cover method that sets the selection mode directly on the selection model.

The following list describes the accepted selection modes:

  • ListSelectionModel.SINGLE_SELECTION - Only one list index can be selected at a time. In this mode, setSelectionInterval and addSelectionInterval are equivalent, both replacing the current selection with the index represented by the second argument (the "lead").
  • ListSelectionModel.SINGLE_INTERVAL_SELECTION - Only one contiguous interval can be selected at a time. In this mode, addSelectionInterval behaves like setSelectionInterval (replacing the current selection}, unless the given interval is immediately adjacent to or overlaps the existing selection, and can be used to grow the selection.
  • ListSelectionModel.MULTIPLE_INTERVAL_SELECTION - In this mode, there's no restriction on what can be selected. This mode is the default.

Parameters:
selectionMode - the selection mode
Throws:
IllegalArgumentException - if the selection mode isn't one of those allowed
See Also:
getSelectionMode()

getSelectionMode

public int getSelectionMode()
Returns the current selection mode for the list. This is a cover method that delegates to the method of the same name on the list's selection model.

Returns:
the current selection mode
See Also:
setSelectionMode(int)

getAnchorSelectionIndex

public int getAnchorSelectionIndex()
Returns the anchor selection index. This is a cover method that delegates to the method of the same name on the list's selection model.

Returns:
the anchor selection index
See Also:
ListSelectionModel.getAnchorSelectionIndex()

getLeadSelectionIndex

public int getLeadSelectionIndex()
Returns the lead selection index. This is a cover method that delegates to the method of the same name on the list's selection model.

Returns:
the lead selection index
See Also:
ListSelectionModel.getLeadSelectionIndex()

getMinSelectionIndex

public int getMinSelectionIndex()
Returns the smallest selected cell index, or -1 if the selection is empty. This is a cover method that delegates to the method of the same name on the list's selection model.

Returns:
the smallest selected cell index, or -1
See Also:
ListSelectionModel.getMinSelectionIndex()

getMaxSelectionIndex

public int getMaxSelectionIndex()
Returns the largest selected cell index, or -1 if the selection is empty. This is a cover method that delegates to the method of the same name on the list's selection model.

Returns:
the largest selected cell index
See Also:
ListSelectionModel.getMaxSelectionIndex()

isSelectedIndex

public boolean isSelectedIndex(int index)
Returns true if the specified index is selected, else false. This is a cover method that delegates to the method of the same name on the list's selection model.

Parameters:
index - index to be queried for selection state
Returns:
true if the specified index is selected, else false
See Also:
ListSelectionModel.isSelectedIndex(int), setSelectedIndex(int)

isSelectionEmpty

public boolean isSelectionEmpty()
Returns true if nothing is selected, else false. This is a cover method that delegates to the method of the same name on the list's selection model.

Returns:
true if nothing is selected, else false
See Also:
ListSelectionModel.isSelectionEmpty(), clearSelection()

clearSelection

public void clearSelection()
Clears the selection; after calling this method, isSelectionEmpty will return true. This is a cover method that delegates to the method of the same name on the list's selection model.

See Also:
ListSelectionModel.clearSelection(), isSelectionEmpty()

setSelectionInterval

public void setSelectionInterval(int anchor,
                                 int lead)
Selects the specified interval. Both anchor and lead indices are included. anchor doesn't have to be less than or equal to lead. This is a cover method that delegates to the method of the same name on the list's selection model.

Refer to the documentation of the selection model class being used for details on how values less than 0 are handled.

Parameters:
anchor - the first index to select
lead - the last index to select
See Also:
ListSelectionModel.setSelectionInterval(int, int),
DefaultListSelectionModel.setSelectionInterval(int, int),
createSelectionModel(),
addSelectionInterval(int, int),
removeSelectionInterval(int, int)

addSelectionInterval

public void addSelectionInterval(int anchor,
                                 int lead)
Sets the selection to be the union of the specified interval with current selection. Both the anchor and lead indices are included. anchor doesn't have to be less than or equal to lead. This is a cover method that delegates to the method of the same name on the list's selection model.

Refer to the documentation of the selection model class being used for details on how values less than 0 are handled.

Parameters:
anchor - the first index to add to the selection
lead - the last index to add to the selection
See Also:
ListSelectionModel.addSelectionInterval(int, int),
DefaultListSelectionModel.addSelectionInterval(int, int),
createSelectionModel(),
setSelectionInterval(int, int),
removeSelectionInterval(int, int)

removeSelectionInterval

public void removeSelectionInterval(int index0,
                                    int index1)
Sets the selection to be the set difference of the specified interval and the current selection. Both the index0 and index1 indices are removed. index0 doesn't have to be less than or equal to index1. This is a cover method that delegates to the method of the same name on the list's selection model.

Refer to the documentation of the selection model class being used for details on how values less than 0 are handled.

Parameters:
index0 - the first index to remove from the selection
index1 - the last index to remove from the selection
See Also:
ListSelectionModel.removeSelectionInterval(int, int),
DefaultListSelectionModel.removeSelectionInterval(int, int),
createSelectionModel(),
setSelectionInterval(int, int),
addSelectionInterval(int, int)

setValueIsAdjusting

public void setValueIsAdjusting(boolean b)
Sets the selection model's valueIsAdjusting property. When true, upcoming changes to selection should be considered part of a single change. This property is used internally and developers typically need not call this method. For example, when the model is being updated in response to a user drag, the value of the property is set to true when the drag is initiated and set to false when the drag is finished. This allows listeners to update only when a change has been finalized, rather than handling all of the intermediate values.

You may want to use this directly if making a series of changes that should be considered part of a single change.

This is a cover method that delegates to the method of the same name on the list's selection model. See the documentation for ListSelectionModel.setValueIsAdjusting(boolean) for more details.

Parameters:
b - the new value for the property
See Also:
ListSelectionModel.setValueIsAdjusting(boolean),
ListSelectionEvent.getValueIsAdjusting(),
getValueIsAdjusting()

getValueIsAdjusting

public boolean getValueIsAdjusting()
Returns the value of the selection model's isAdjusting property.

This is a cover method that delegates to the method of the same name on the list's selection model.

Returns:
the value of the selection model's isAdjusting property.
See Also:
setValueIsAdjusting(boolean), ListSelectionModel.getValueIsAdjusting()

getSelectedIndices

public int[] getSelectedIndices()
Returns an array of all of the selected indices, in increasing order.

Returns:
all of the selected indices, in increasing order, or an empty array if nothing is selected
See Also:
removeSelectionInterval(int, int), addListSelectionListener(javax.swing.event.ListSelectionListener)

setSelectedIndex

public void setSelectedIndex(int index)
Selects a single cell. Does nothing if the given index is greater than or equal to the model size. This is a convenience method that uses setSelectionInterval on the selection model. Refer to the documentation for the selection model class being used for details on how values less than 0 are handled.

Parameters:
index - the index of the cell to select
See Also:
ListSelectionModel.setSelectionInterval(int, int), isSelectedIndex(int), addListSelectionListener(javax.swing.event.ListSelectionListener)

setSelectedIndices

public void setSelectedIndices(int[] indices)
Changes the selection to be the set of indices specified by the given array. Indices greater than or equal to the model size are ignored. This is a convenience method that clears the selection and then uses addSelectionInterval on the selection model to add the indices. Refer to the documentation of the selection model class being used for details on how values less than 0 are handled.

Parameters:
indices - an array of the indices of the cells to select, non-null
Throws:
NullPointerException - if the given array is null
See Also:
ListSelectionModel.addSelectionInterval(int, int), isSelectedIndex(int), addListSelectionListener(javax.swing.event.ListSelectionListener)

getSelectedValues

public Object[] getSelectedValues()
Returns an array of all the selected values, in increasing order based on their indices in the list.

Returns:
the selected values, or an empty array if nothing is selected
See Also:
isSelectedIndex(int), getModel(), addListSelectionListener(javax.swing.event.ListSelectionListener)

getSelectedIndex

public int getSelectedIndex()
Returns the smallest selected cell index; the selection when only a single item is selected in the list. When multiple items are selected, it is simply the smallest selected index. Returns -1 if there is no selection.

This method is a cover that delegates to getMinSelectionIndex.

Returns:
the smallest selected cell index
See Also:
getMinSelectionIndex(), addListSelectionListener(javax.swing.event.ListSelectionListener)

getSelectedValue

public Object getSelectedValue()
Returns the value for the smallest selected cell index; the selected value when only a single item is selected in the list. When multiple items are selected, it is simply the value for the smallest selected index. Returns null if there is no selection.

This is a convenience method that simply returns the model value for getMinSelectionIndex.

Returns:
the first selected value
See Also:
getMinSelectionIndex(),
getModel(),
addListSelectionListener(javax.swing.event.ListSelectionListener)

setSelectedValue

public void setSelectedValue(Object anObject,
                             boolean shouldScroll)
Selects the specified object from the list.

Parameters:
anObject - the object to select
shouldScroll - true if the list should scroll to display the selected object, if one exists; otherwise false

getPreferredScrollableViewportSize

public Dimension getPreferredScrollableViewportSize()
Computes the size of viewport needed to display visibleRowCount rows. The value returned by this method depends on the layout orientation:

VERTICAL:
This is trivial if both fixedCellWidth and fixedCellHeight have been set (either explicitly or by specifying a prototype cell value). The width is simply the fixedCellWidth plus the list's horizontal insets. The height is the fixedCellHeight multiplied by the visibleRowCount, plus the list's vertical insets.

If either fixedCellWidth or fixedCellHeight haven't been specified, heuristics are used. If the model is empty, the width is the fixedCellWidth, if greater than 0, or a hard-coded value of 256. The height is the fixedCellHeight multiplied by visibleRowCount, if fixedCellHeight is greater than 0, otherwise it is a hard-coded value of 16 multiplied by visibleRowCount.

If the model isn't empty, the width is the preferred size's width, typically the width of the widest list element. The height is the fixedCellHeight multiplied by the visibleRowCount, plus the list's vertical insets.

VERTICAL_WRAP or HORIZONTAL_WRAP:
This method simply returns the value from getPreferredSize. The list's ListUI is expected to override getPreferredSize to return an appropriate value.

Specified by:
getPreferredScrollableViewportSize in interface Scrollable
Returns:
a dimension containing the size of the viewport needed to display visibleRowCount rows
See Also:
getPreferredScrollableViewportSize(), setPrototypeCellValue(java.lang.Object)

getScrollableUnitIncrement

public int getScrollableUnitIncrement(Rectangle visibleRect,
                                      int orientation,
                                      int direction)
Returns the distance to scroll to expose the next or previous row (for vertical scrolling) or column (for horizontal scrolling).

For horizontal scrolling, if the layout orientation is VERTICAL, then the list's font size is returned (or 1 if the font is null).

Specified by:
getScrollableUnitIncrement in interface Scrollable
Parameters:
visibleRect - the view area visible within the viewport
orientation - SwingConstants.HORIZONTAL or SwingConstants.VERTICAL
direction - less or equal to zero to scroll up/back, greater than zero for down/forward
Returns:
the "unit" increment for scrolling in the specified direction; always positive
Throws:
IllegalArgumentException - if visibleRect is null, or orientation isn't one of SwingConstants.VERTICAL or SwingConstants.HORIZONTAL
See Also:
getScrollableBlockIncrement(java.awt.Rectangle, int, int), Scrollable.getScrollableUnitIncrement(java.awt.Rectangle, int, int)

getScrollableBlockIncrement

public int getScrollableBlockIncrement(Rectangle visibleRect,
                                       int orientation,
                                       int direction)
Returns the distance to scroll to expose the next or previous block.

For vertical scrolling, the following rules are used:

  • if scrolling down, returns the distance to scroll so that the last visible element becomes the first completely visible element
  • if scrolling up, returns the distance to scroll so that the first visible element becomes the last completely visible element
  • returns visibleRect.height if the list is empty

For horizontal scrolling, when the layout orientation is either VERTICAL_WRAP or HORIZONTAL_WRAP:

  • if scrolling right, returns the distance to scroll so that the last visible element becomes the first completely visible element
  • if scrolling left, returns the distance to scroll so that the first visible element becomes the last completely visible element
  • returns visibleRect.width if the list is empty

For horizontal scrolling and VERTICAL orientation, returns visibleRect.width.

Note that the value of visibleRect must be the equal to this.getVisibleRect().

Specified by:
getScrollableBlockIncrement in interface Scrollable
Parameters:
visibleRect - the view area visible within the viewport
orientation - SwingConstants.HORIZONTAL or SwingConstants.VERTICAL
direction - less or equal to zero to scroll up/back, greater than zero for down/forward
Returns:
the "block" increment for scrolling in the specified direction; always positive
Throws:
IllegalArgumentException - if visibleRect is null, or orientation isn't one of SwingConstants.VERTICAL or SwingConstants.HORIZONTAL
See Also:
getScrollableUnitIncrement(java.awt.Rectangle, int, int), Scrollable.getScrollableBlockIncrement(java.awt.Rectangle, int, int)

getScrollableTracksViewportWidth

public boolean getScrollableTracksViewportWidth()
Returns true if this JList is displayed in a JViewport and the viewport is wider than the list's preferred width, or if the layout orientation is HORIZONTAL_WRAP and visibleRowCount <= 0; otherwise returns false.

If false, then don't track the viewport's width. This allows horizontal scrolling if the JViewport is itself embedded in a JScrollPane.

Specified by:
getScrollableTracksViewportWidth in interface Scrollable
Returns:
whether or not an enclosing viewport should force the list's width to match its own
See Also:
Scrollable.getScrollableTracksViewportWidth()

getScrollableTracksViewportHeight

public boolean getScrollableTracksViewportHeight()
Returns true if this JList is displayed in a JViewport and the viewport is taller than the list's preferred height, or if the layout orientation is VERTICAL_WRAP and visibleRowCount <= 0; otherwise returns false.

If false, then don't track the viewport's height. This allows vertical scrolling if the JViewport is itself embedded in a JScrollPane.

Specified by:
getScrollableTracksViewportHeight in interface Scrollable
Returns:
whether or not an enclosing viewport should force the list's height to match its own
See Also:
Scrollable.getScrollableTracksViewportHeight()

paramString

protected String paramString()
Returns a String representation of this JList. This method is intended to be used only for debugging purposes, and the content and format of the returned String may vary between implementations. The returned String may be empty, but may not be null.

Overrides:
paramString in class JComponent
Returns:
a String representation of this JList.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JList. For JList, the AccessibleContext takes the form of an AccessibleJList.

A new AccessibleJList instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJList that serves as the AccessibleContext of this JList
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JList.AccessibleJList

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JList.AccessibleJList

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JList.AccessibleJList
All Implemented Interfaces:
PropertyChangeListener, Serializable, EventListener, AccessibleComponent, AccessibleExtendedComponent, AccessibleSelection, ListDataListener, ListSelectionListener
Enclosing class:
JList
protected class JList.AccessibleJList
extends JComponent.AccessibleJComponent
implements AccessibleSelection, PropertyChangeListener, ListSelectionListener, ListDataListener

This class implements accessibility support for the JList class. It provides an implementation of the Java Accessibility API appropriate to list user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class JList.AccessibleJList.AccessibleJListChild
This class implements accessibility support appropriate for list children.
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
JList.AccessibleJList()
Method Summary
void | addAccessibleSelection(int i) Adds the specified selected item in the object to the object's selection.
void | clearAccessibleSelection() Clears the selection in the object, so that nothing in the object is selected.
void | contentsChanged(ListDataEvent e) List Data Listener contents changed method.
Accessible | getAccessibleAt(Point p) Returns the Accessible child contained at the local coordinate Point, if one exists.
Accessible | getAccessibleChild(int i) Return the nth Accessible child of the object.
int | getAccessibleChildrenCount() Returns the number of accessible children in the object.
AccessibleRole | getAccessibleRole() Get the role of this object.
AccessibleSelection | getAccessibleSelection() Get the AccessibleSelection associated with this object.
Accessible | getAccessibleSelection(int i) Returns an Accessible representing the specified selected item in the object.
int | getAccessibleSelectionCount() Returns the number of items currently selected.
AccessibleStateSet | getAccessibleStateSet() Get the state set of this object.
void | intervalAdded(ListDataEvent e) List Data Listener interval added method.
void | intervalRemoved(ListDataEvent e) List Data Listener interval removed method.
boolean | isAccessibleChildSelected(int i) Returns true if the current child of this object is selected.
void | propertyChange(PropertyChangeEvent e) Property Change Listener change method.
void | removeAccessibleSelection(int i) Removes the specified selected item in the object from the object's selection.
void | selectAllAccessibleSelection() Causes every selected item in the object to be selected if the object supports multiple selections.
void | valueChanged(ListSelectionEvent e) List Selection Listener value change method.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JList.AccessibleJList

public JList.AccessibleJList()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
Property Change Listener change method. Used to track changes to the DataModel and ListSelectionModel, in order to re-set listeners to those for reporting changes there via the Accessibility PropertyChange mechanism.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - PropertyChangeEvent

valueChanged

public void valueChanged(ListSelectionEvent e)
List Selection Listener value change method. Used to fire the property change

Specified by:
valueChanged in interface ListSelectionListener
Parameters:
e - ListSelectionEvent

intervalAdded

public void intervalAdded(ListDataEvent e)
List Data Listener interval added method. Used to fire the visible data property change

Specified by:
intervalAdded in interface ListDataListener
Parameters:
e - ListDataEvent

intervalRemoved

public void intervalRemoved(ListDataEvent e)
List Data Listener interval removed method. Used to fire the visible data property change

Specified by:
intervalRemoved in interface ListDataListener
Parameters:
e - ListDataEvent

contentsChanged

public void contentsChanged(ListDataEvent e)
List Data Listener contents changed method. Used to fire the visible data property change

Specified by:
contentsChanged in interface ListDataListener
Parameters:
e - ListDataEvent

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Get the state set of this object.

Overrides:
getAccessibleStateSet in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleState containing the current state of the object
See Also:
AccessibleState

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleAt

public Accessible getAccessibleAt(Point p)
Returns the Accessible child contained at the local coordinate Point, if one exists. Otherwise returns null.

Specified by:
getAccessibleAt in interface AccessibleComponent
Overrides:
getAccessibleAt in class Container.AccessibleAWTContainer
Parameters:
p - the point defining the top-left corner of the Accessible, given in the coordinate space of the object's parent
Returns:
the Accessible at the specified location, if it exists

getAccessibleChildrenCount

public int getAccessibleChildrenCount()
Returns the number of accessible children in the object. If all of the children of this object implement Accessible, than this method should return the number of children of this object.

Overrides:
getAccessibleChildrenCount in class JComponent.AccessibleJComponent
Returns:
the number of accessible children in the object.

getAccessibleChild

public Accessible getAccessibleChild(int i)
Return the nth Accessible child of the object.

Overrides:
getAccessibleChild in class JComponent.AccessibleJComponent
Parameters:
i - zero-based index of child
Returns:
the nth Accessible child of the object
See Also:
AccessibleContext.getAccessibleChildrenCount()

getAccessibleSelection

public AccessibleSelection getAccessibleSelection()
Get the AccessibleSelection associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleSelection interface on behalf of itself.

Overrides:
getAccessibleSelection in class AccessibleContext
Returns:
this object
See Also:
AccessibleSelection

getAccessibleSelectionCount

public int getAccessibleSelectionCount()
Returns the number of items currently selected. If no items are selected, the return value will be 0.

Specified by:
getAccessibleSelectionCount in interface AccessibleSelection
Returns:
the number of items currently selected.

getAccessibleSelection

public Accessible getAccessibleSelection(int i)
Returns an Accessible representing the specified selected item in the object. If there isn't a selection, or there are fewer items selected than the integer passed in, the return value will be null.

Specified by:
getAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of selected items
Returns:
an Accessible containing the selected item
See Also:
AccessibleSelection.getAccessibleSelectionCount()

isAccessibleChildSelected

public boolean isAccessibleChildSelected(int i)
Returns true if the current child of this object is selected.

Specified by:
isAccessibleChildSelected in interface AccessibleSelection
Parameters:
i - the zero-based index of the child in this Accessible object.
Returns:
true if the current child of this object is selected; else false.
See Also:
AccessibleContext.getAccessibleChild(int)

addAccessibleSelection

public void addAccessibleSelection(int i)
Adds the specified selected item in the object to the object's selection. If the object supports multiple selections, the specified item is added to any existing selection, otherwise it replaces any existing selection in the object. If the specified item is already selected, this method has no effect.

Specified by:
addAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of selectable items
See Also:
AccessibleContext.getAccessibleChild(int)

removeAccessibleSelection

public void removeAccessibleSelection(int i)
Removes the specified selected item in the object from the object's selection. If the specified item isn't currently selected, this method has no effect.

Specified by:
removeAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of selectable items
See Also:
AccessibleContext.getAccessibleChild(int)

clearAccessibleSelection

public void clearAccessibleSelection()
Clears the selection in the object, so that nothing in the object is selected.

Specified by:
clearAccessibleSelection in interface AccessibleSelection

selectAllAccessibleSelection

public void selectAllAccessibleSelection()
Causes every selected item in the object to be selected if the object supports multiple selections.

Specified by:
selectAllAccessibleSelection in interface AccessibleSelection
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JList.AccessibleJList.AccessibleJListChild

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JList.AccessibleJList.AccessibleJListChild

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  javax.swing.JList.AccessibleJList.AccessibleJListChild
All Implemented Interfaces:
Accessible, AccessibleComponent
Enclosing class:
JList.AccessibleJList
protected class JList.AccessibleJList.AccessibleJListChild
extends AccessibleContext
implements Accessible, AccessibleComponent

This class implements accessibility support appropriate for list children.

Field Summary
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
JList.AccessibleJList.AccessibleJListChild(JList parent, int indexInParent)
Method Summary
void | addFocusListener(FocusListener l) Adds the specified focus listener to receive focus events from this component.
void | addPropertyChangeListener(PropertyChangeListener l) Adds a PropertyChangeListener to the listener list.
boolean | contains(Point p) Checks whether the specified point is within this object's bounds, where the point's x and y coordinates are defined to be relative to the coordinate system of the object.
AccessibleAction | getAccessibleAction() Gets the AccessibleAction associated with this object that supports one or more actions.
Accessible | getAccessibleAt(Point p) Returns the Accessible child, if one exists, contained at the local coordinate Point.
Accessible | getAccessibleChild(int i) Returns the specified Accessible child of the object.
int | getAccessibleChildrenCount() Returns the number of accessible children of the object.
AccessibleComponent | getAccessibleComponent() Get the AccessibleComponent associated with this object.
AccessibleContext | getAccessibleContext() Get the AccessibleContext for this object.
String | getAccessibleDescription() Gets the accessibleDescription property of this object.
AccessibleIcon[] | getAccessibleIcon() Returns the icon for the element renderer, as the only item of an array of AccessibleIcons or a null array if the renderer component contains no icons.
int | getAccessibleIndexInParent() Gets the 0-based index of this object in its accessible parent.
String | getAccessibleName() Gets the accessibleName property of this object.
AccessibleRole | getAccessibleRole() Gets the role of this object.
AccessibleSelection | getAccessibleSelection() Gets the AccessibleSelection associated with this object which allows its Accessible children to be selected.
AccessibleStateSet | getAccessibleStateSet() Gets the state set of this object.
AccessibleText | getAccessibleText() Gets the AccessibleText associated with this object presenting text on the display.
AccessibleValue | getAccessibleValue() Gets the AccessibleValue associated with this object that supports a Numerical value.
Color | getBackground() Gets the background color of this object.
Rectangle | getBounds() Gets the bounds of this object in the form of a Rectangle object.
Cursor | getCursor() Gets the Cursor of this object.
Font | getFont() Gets the Font of this object.
FontMetrics | getFontMetrics(Font f) Gets the FontMetrics of this object.
Color | getForeground() Gets the foreground color of this object.
Locale | getLocale() Gets the locale of the component.
Point | getLocation() Gets the location of the object relative to the parent in the form of a point specifying the object's top-left corner in the screen's coordinate space.
Point | getLocationOnScreen() Returns the location of the object on the screen.
Dimension | getSize() Returns the size of this object in the form of a Dimension object.
boolean | isEnabled() Determines if the object is enabled.
boolean | isFocusTraversable() Returns whether this object can accept focus or not.
boolean | isShowing() Determines if the object is showing.
boolean | isVisible() Determines if the object is visible.
void | removeFocusListener(FocusListener l) Removes the specified focus listener so it no longer receives focus events from this component.
void | removePropertyChangeListener(PropertyChangeListener l) Removes a PropertyChangeListener from the listener list.
void | requestFocus() Requests focus for this object.
void | setAccessibleDescription(String s) Sets the accessible description of this object.
void | setAccessibleName(String s) Sets the localized accessible name of this object.
void | setBackground(Color c) Sets the background color of this object.
void | setBounds(Rectangle r) Sets the bounds of this object in the form of a Rectangle object.
void | setCursor(Cursor c) Sets the Cursor of this object.
void | setEnabled(boolean b) Sets the enabled state of the object.
void | setFont(Font f) Sets the Font of this object.
void | setForeground(Color c) Sets the foreground color of this object.
void | setLocation(Point p) Sets the location of the object relative to the parent.
void | setSize(Dimension d) Resizes this object so that it has width and height.
void | setVisible(boolean b) Sets the visible state of the object.
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleEditableText, getAccessibleParent, getAccessibleRelationSet, getAccessibleTable, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JList.AccessibleJList.AccessibleJListChild

public JList.AccessibleJList.AccessibleJListChild(JList parent,
                                                  int indexInParent)
Method Detail

getAccessibleContext

public AccessibleContext getAccessibleContext()
Get the AccessibleContext for this object. In the implementation of the Java Accessibility API for this class, returns this object, which is its own AccessibleContext.

Specified by:
getAccessibleContext in interface Accessible
Returns:
this object

getAccessibleName

public String getAccessibleName()
Description copied from class: AccessibleContext
Gets the accessibleName property of this object. The accessibleName property of an object is a localized String that designates the purpose of the object. For example, the accessibleName property of a label or button might be the text of the label or button itself. In the case of an object that doesn't display its name, the accessibleName should still be set. For example, in the case of a text field used to enter the name of a city, the accessibleName for the en_US locale could be 'city.'

Overrides:
getAccessibleName in class AccessibleContext
Returns:
the localized name of the object; null if this object does not have a name
See Also:
AccessibleContext.setAccessibleName(java.lang.String)

setAccessibleName

public void setAccessibleName(String s)
Description copied from class: AccessibleContext
Sets the localized accessible name of this object. Changing the name will cause a PropertyChangeEvent to be fired for the ACCESSIBLE_NAME_PROPERTY property.

Overrides:
setAccessibleName in class AccessibleContext
Parameters:
s - the new localized name of the object.
See Also:
AccessibleContext.getAccessibleName(), AccessibleContext.addPropertyChangeListener(java.beans.PropertyChangeListener)

getAccessibleDescription

public String getAccessibleDescription()
Description copied from class: AccessibleContext
Gets the accessibleDescription property of this object. The accessibleDescription property of this object is a short localized phrase describing the purpose of the object. For example, in the case of a 'Cancel' button, the accessibleDescription could be 'Ignore changes and close dialog box.'

Overrides:
getAccessibleDescription in class AccessibleContext
Returns:
the localized description of the object; null if this object does not have a description
See Also:
AccessibleContext.setAccessibleDescription(java.lang.String)

setAccessibleDescription

public void setAccessibleDescription(String s)
Description copied from class: AccessibleContext
Sets the accessible description of this object. Changing the name will cause a PropertyChangeEvent to be fired for the ACCESSIBLE_DESCRIPTION_PROPERTY property.

Overrides:
setAccessibleDescription in class AccessibleContext
Parameters:
s - the new localized description of the object
See Also:
AccessibleContext.setAccessibleName(java.lang.String), AccessibleContext.addPropertyChangeListener(java.beans.PropertyChangeListener)

getAccessibleRole

public AccessibleRole getAccessibleRole()
Description copied from class: AccessibleContext
Gets the role of this object. The role of the object is the generic purpose or use of the class of this object. For example, the role of a push button is AccessibleRole.PUSH_BUTTON. The roles in AccessibleRole are provided so component developers can pick from a set of predefined roles. This enables assistive technologies to provide a consistent interface to various tweaked subclasses of components (e.g., use AccessibleRole.PUSH_BUTTON for all components that act like a push button) as well as distinguish between sublasses that behave differently (e.g., AccessibleRole.CHECK_BOX for check boxes and AccessibleRole.RADIO_BUTTON for radio buttons).

Note that the AccessibleRole class is also extensible, so custom component developers can define their own AccessibleRole's if the set of predefined roles is inadequate.

Specified by:
getAccessibleRole in class AccessibleContext
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Description copied from class: AccessibleContext
Gets the state set of this object. The AccessibleStateSet of an object is composed of a set of unique AccessibleStates. A change in the AccessibleStateSet of an object will cause a PropertyChangeEvent to be fired for the ACCESSIBLE_STATE_PROPERTY property.

Specified by:
getAccessibleStateSet in class AccessibleContext
Returns:
an instance of AccessibleStateSet containing the current state set of the object
See Also:
AccessibleStateSet, AccessibleState, AccessibleContext.addPropertyChangeListener(java.beans.PropertyChangeListener)

getAccessibleIndexInParent

public int getAccessibleIndexInParent()
Description copied from class: AccessibleContext
Gets the 0-based index of this object in its accessible parent.

Specified by:
getAccessibleIndexInParent in class AccessibleContext
Returns:
the 0-based index of this object in its parent; -1 if this object does not have an accessible parent.
See Also:
AccessibleContext.getAccessibleParent(),
AccessibleContext.getAccessibleChildrenCount(),
AccessibleContext.getAccessibleChild(int)

getAccessibleChildrenCount

public int getAccessibleChildrenCount()
Description copied from class: AccessibleContext
Returns the number of accessible children of the object.

Specified by:
getAccessibleChildrenCount in class AccessibleContext
Returns:
the number of accessible children of the object.

getAccessibleChild

public Accessible getAccessibleChild(int i)
Description copied from class: AccessibleContext
Returns the specified Accessible child of the object. The Accessible children of an Accessible object are zero-based, so the first child of an Accessible child is at index 0, the second child is at index 1, and so on.

Specified by:
getAccessibleChild in class AccessibleContext
Parameters:
i - zero-based index of child
Returns:
the Accessible child of the object
See Also:
AccessibleContext.getAccessibleChildrenCount()

getLocale

public Locale getLocale()
Description copied from class: AccessibleContext
Gets the locale of the component. If the component does not have a locale, then the locale of its parent is returned.

Specified by:
getLocale in class AccessibleContext
Returns:
this component's locale. If this component does not have a locale, the locale of its parent is returned.

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener l)
Description copied from class: AccessibleContext
Adds a PropertyChangeListener to the listener list. The listener is registered for all Accessible properties and will be called when those properties change.

Overrides:
addPropertyChangeListener in class AccessibleContext
Parameters:
l - The PropertyChangeListener to be added
See Also:
AccessibleContext.ACCESSIBLE_NAME_PROPERTY, AccessibleContext.ACCESSIBLE_DESCRIPTION_PROPERTY, AccessibleContext.ACCESSIBLE_STATE_PROPERTY, AccessibleContext.ACCESSIBLE_VALUE_PROPERTY, AccessibleContext.ACCESSIBLE_SELECTION_PROPERTY, AccessibleContext.ACCESSIBLE_TEXT_PROPERTY, AccessibleContext.ACCESSIBLE_VISIBLE_DATA_PROPERTY

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener l)
Description copied from class: AccessibleContext
Removes a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties.

Overrides:
removePropertyChangeListener in class AccessibleContext
Parameters:
l - The PropertyChangeListener to be removed

getAccessibleAction

public AccessibleAction getAccessibleAction()
Description copied from class: AccessibleContext
Gets the AccessibleAction associated with this object that supports one or more actions.

Overrides:
getAccessibleAction in class AccessibleContext
Returns:
AccessibleAction if supported by object; else return null
See Also:
AccessibleAction

getAccessibleComponent

public AccessibleComponent getAccessibleComponent()
Get the AccessibleComponent associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleComponent interface on behalf of itself.

Overrides:
getAccessibleComponent in class AccessibleContext
Returns:
this object
See Also:
AccessibleComponent

getAccessibleSelection

public AccessibleSelection getAccessibleSelection()
Description copied from class: AccessibleContext
Gets the AccessibleSelection associated with this object which allows its Accessible children to be selected.

Overrides:
getAccessibleSelection in class AccessibleContext
Returns:
AccessibleSelection if supported by object; else return null
See Also:
AccessibleSelection

getAccessibleText

public AccessibleText getAccessibleText()
Description copied from class: AccessibleContext
Gets the AccessibleText associated with this object presenting text on the display.

Overrides:
getAccessibleText in class AccessibleContext
Returns:
AccessibleText if supported by object; else return null
See Also:
AccessibleText

getAccessibleValue

public AccessibleValue getAccessibleValue()
Description copied from class: AccessibleContext
Gets the AccessibleValue associated with this object that supports a Numerical value.

Overrides:
getAccessibleValue in class AccessibleContext
Returns:
AccessibleValue if supported by object; else return null
See Also:
AccessibleValue

getBackground

public Color getBackground()
Description copied from interface: AccessibleComponent
Gets the background color of this object.

Specified by:
getBackground in interface AccessibleComponent
Returns:
the background color, if supported, of the object; otherwise, null
See Also:
AccessibleComponent.setBackground(java.awt.Color)

setBackground

public void setBackground(Color c)
Description copied from interface: AccessibleComponent
Sets the background color of this object.

Specified by:
setBackground in interface AccessibleComponent
Parameters:
c - the new Color for the background
See Also:
AccessibleComponent.setBackground(java.awt.Color)

getForeground

public Color getForeground()
Description copied from interface: AccessibleComponent
Gets the foreground color of this object.

Specified by:
getForeground in interface AccessibleComponent
Returns:
the foreground color, if supported, of the object; otherwise, null
See Also:
AccessibleComponent.setForeground(java.awt.Color)

setForeground

public void setForeground(Color c)
Description copied from interface: AccessibleComponent
Sets the foreground color of this object.

Specified by:
setForeground in interface AccessibleComponent
Parameters:
c - the new Color for the foreground
See Also:
AccessibleComponent.getForeground()

getCursor

public Cursor getCursor()
Description copied from interface: AccessibleComponent
Gets the Cursor of this object.

Specified by:
getCursor in interface AccessibleComponent
Returns:
the Cursor, if supported, of the object; otherwise, null
See Also:
AccessibleComponent.setCursor(java.awt.Cursor)

setCursor

public void setCursor(Cursor c)
Description copied from interface: AccessibleComponent
Sets the Cursor of this object.

Specified by:
setCursor in interface AccessibleComponent
Parameters:
c - the new Cursor for the object
See Also:
AccessibleComponent.getCursor()

getFont

public Font getFont()
Description copied from interface: AccessibleComponent
Gets the Font of this object.

Specified by:
getFont in interface AccessibleComponent
Returns:
the Font,if supported, for the object; otherwise, null
See Also:
AccessibleComponent.setFont(java.awt.Font)

setFont

public void setFont(Font f)
Description copied from interface: AccessibleComponent
Sets the Font of this object.

Specified by:
setFont in interface AccessibleComponent
Parameters:
f - the new Font for the object
See Also:
AccessibleComponent.getFont()

getFontMetrics

public FontMetrics getFontMetrics(Font f)
Description copied from interface: AccessibleComponent
Gets the FontMetrics of this object.

Specified by:
getFontMetrics in interface AccessibleComponent
Parameters:
f - the Font
Returns:
the FontMetrics, if supported, the object; otherwise, null
See Also:
AccessibleComponent.getFont()

isEnabled

public boolean isEnabled()
Description copied from interface: AccessibleComponent
Determines if the object is enabled. Objects that are enabled will also have the AccessibleState.ENABLED state set in their AccessibleStateSets.

Specified by:
isEnabled in interface AccessibleComponent
Returns:
true if object is enabled; otherwise, false
See Also:
AccessibleComponent.setEnabled(boolean), AccessibleContext.getAccessibleStateSet(), AccessibleState.ENABLED, AccessibleStateSet

setEnabled

public void setEnabled(boolean b)
Description copied from interface: AccessibleComponent
Sets the enabled state of the object.

Specified by:
setEnabled in interface AccessibleComponent
Parameters:
b - if true, enables this object; otherwise, disables it
See Also:
AccessibleComponent.isEnabled()

isVisible

public boolean isVisible()
Description copied from interface: AccessibleComponent
Determines if the object is visible. Note: this means that the object intends to be visible; however, it may not be showing on the screen because one of the objects that this object is contained by is currently not visible. To determine if an object is showing on the screen, use isShowing().

Objects that are visible will also have the AccessibleState.VISIBLE state set in their AccessibleStateSets.

Specified by:
isVisible in interface AccessibleComponent
Returns:
true if object is visible; otherwise, false
See Also:
AccessibleComponent.setVisible(boolean), AccessibleContext.getAccessibleStateSet(), AccessibleState.VISIBLE, AccessibleStateSet

setVisible

public void setVisible(boolean b)
Description copied from interface: AccessibleComponent
Sets the visible state of the object.

Specified by:
setVisible in interface AccessibleComponent
Parameters:
b - if true, shows this object; otherwise, hides it
See Also:
AccessibleComponent.isVisible()

isShowing

public boolean isShowing()
Description copied from interface: AccessibleComponent
Determines if the object is showing. This is determined by checking the visibility of the object and its ancestors. Note: this will return true even if the object is obscured by another (for example, it is underneath a menu that was pulled down).

Specified by:
isShowing in interface AccessibleComponent
Returns:
true if object is showing; otherwise, false

contains

public boolean contains(Point p)
Description copied from interface: AccessibleComponent
Checks whether the specified point is within this object's bounds, where the point's x and y coordinates are defined to be relative to the coordinate system of the object.

Specified by:
contains in interface AccessibleComponent
Parameters:
p - the Point relative to the coordinate system of the object
Returns:
true if object contains Point; otherwise false
See Also:
AccessibleComponent.getBounds()

getLocationOnScreen

public Point getLocationOnScreen()
Description copied from interface: AccessibleComponent
Returns the location of the object on the screen.

Specified by:
getLocationOnScreen in interface AccessibleComponent
Returns:
the location of the object on screen; null if this object is not on the screen
See Also:
AccessibleComponent.getBounds(), AccessibleComponent.getLocation()

getLocation

public Point getLocation()
Description copied from interface: AccessibleComponent
Gets the location of the object relative to the parent in the form of a point specifying the object's top-left corner in the screen's coordinate space.

Specified by:
getLocation in interface AccessibleComponent
Returns:
An instance of Point representing the top-left corner of the object's bounds in the coordinate space of the screen; null if this object or its parent are not on the screen
See Also:
AccessibleComponent.getBounds(), AccessibleComponent.getLocationOnScreen()

setLocation

public void setLocation(Point p)
Description copied from interface: AccessibleComponent
Sets the location of the object relative to the parent.

Specified by:
setLocation in interface AccessibleComponent
Parameters:
p - the new position for the top-left corner
See Also:
AccessibleComponent.getLocation()

getBounds

public Rectangle getBounds()
Description copied from interface: AccessibleComponent
Gets the bounds of this object in the form of a Rectangle object. The bounds specify this object's width, height, and location relative to its parent.

Specified by:
getBounds in interface AccessibleComponent
Returns:
A rectangle indicating this component's bounds; null if this object is not on the screen.
See Also:
AccessibleComponent.contains(java.awt.Point)

setBounds

public void setBounds(Rectangle r)
Description copied from interface: AccessibleComponent
Sets the bounds of this object in the form of a Rectangle object. The bounds specify this object's width, height, and location relative to its parent.

Specified by:
setBounds in interface AccessibleComponent
Parameters:
r - rectangle indicating this component's bounds
See Also:
AccessibleComponent.getBounds()

getSize

public Dimension getSize()
Description copied from interface: AccessibleComponent
Returns the size of this object in the form of a Dimension object. The height field of the Dimension object contains this object's height, and the width field of the Dimension object contains this object's width.

Specified by:
getSize in interface AccessibleComponent
Returns:
A Dimension object that indicates the size of this component; null if this object is not on the screen
See Also:
AccessibleComponent.setSize(java.awt.Dimension)

setSize

public void setSize(Dimension d)
Description copied from interface: AccessibleComponent
Resizes this object so that it has width and height.

Specified by:
setSize in interface AccessibleComponent
Parameters:
d - The dimension specifying the new size of the object.
See Also:
AccessibleComponent.getSize()

getAccessibleAt

public Accessible getAccessibleAt(Point p)
Description copied from interface: AccessibleComponent
Returns the Accessible child, if one exists, contained at the local coordinate Point.

Specified by:
getAccessibleAt in interface AccessibleComponent
Parameters:
p - The point relative to the coordinate system of this object.
Returns:
the Accessible, if it exists, at the specified location; otherwise null

isFocusTraversable

public boolean isFocusTraversable()
Description copied from interface: AccessibleComponent
Returns whether this object can accept focus or not. Objects that can accept focus will also have the AccessibleState.FOCUSABLE state set in their AccessibleStateSets.

Specified by:
isFocusTraversable in interface AccessibleComponent
Returns:
true if object can accept focus; otherwise false
See Also:
AccessibleContext.getAccessibleStateSet(), AccessibleState.FOCUSABLE, AccessibleState.FOCUSED, AccessibleStateSet

requestFocus

public void requestFocus()
Description copied from interface: AccessibleComponent
Requests focus for this object. If this object cannot accept focus, nothing will happen. Otherwise, the object will attempt to take focus.

Specified by:
requestFocus in interface AccessibleComponent
See Also:
AccessibleComponent.isFocusTraversable()

addFocusListener

public void addFocusListener(FocusListener l)
Description copied from interface: AccessibleComponent
Adds the specified focus listener to receive focus events from this component.

Specified by:
addFocusListener in interface AccessibleComponent
Parameters:
l - the focus listener
See Also:
AccessibleComponent.removeFocusListener(java.awt.event.FocusListener)

removeFocusListener

public void removeFocusListener(FocusListener l)
Description copied from interface: AccessibleComponent
Removes the specified focus listener so it no longer receives focus events from this component.

Specified by:
removeFocusListener in interface AccessibleComponent
Parameters:
l - the focus listener
See Also:
AccessibleComponent.addFocusListener(java.awt.event.FocusListener)

getAccessibleIcon

public AccessibleIcon[] getAccessibleIcon()
Returns the icon for the element renderer, as the only item of an array of AccessibleIcons or a null array if the renderer component contains no icons.

Overrides:
getAccessibleIcon in class AccessibleContext
Returns:
an array containing the accessible icon or a null array if none
Since:
1.3
See Also:
AccessibleIcon
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JList.DropLocation

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JList.DropLocation

java.lang.Object
    extended by  javax.swing.TransferHandler.DropLocation
        extended by  javax.swing.JList.DropLocation
Enclosing class:
JList
public static final class JList.DropLocation
extends TransferHandler.DropLocation

A subclass of TransferHandler.DropLocation representing a drop location for a JList.

Since:
1.6
See Also:
JList.getDropLocation()

Method Summary
int | getIndex() Returns the index where dropped data should be placed in the list.
boolean | isInsert() Returns whether or not this location represents an insert location.
String | toString() Returns a string representation of this drop location.
Methods inherited from class javax.swing.TransferHandler.DropLocation
getDropPoint
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getIndex

public int getIndex()
Returns the index where dropped data should be placed in the list. Interpretation of the value depends on the drop mode set on the associated component. If the drop mode is either DropMode.USE_SELECTION or DropMode.ON, the return value is an index of a row in the list. If the drop mode is DropMode.INSERT, the return value refers to the index where the data should be inserted. If the drop mode is DropMode.ON_OR_INSERT, the value of isInsert() indicates whether the index is an index of a row, or an insert index.

-1 indicates that the drop occurred over empty space, and no index could be calculated.

Returns:
the drop index

isInsert

public boolean isInsert()
Returns whether or not this location represents an insert location.

Returns:
whether or not this is an insert location

toString

public String toString()
Returns a string representation of this drop location. This method is intended to be used for debugging purposes, and the content and format of the returned string may vary between implementations.

Overrides:
toString in class TransferHandler.DropLocation
Returns:
a string representation of this drop location
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMenu

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JMenu

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.AbstractButton
                    extended by  javax.swing.JMenuItem
                        extended by  javax.swing.JMenu
All Implemented Interfaces:
ImageObserver, ItemSelectable, MenuContainer, Serializable, Accessible, MenuElement, SwingConstants
public class JMenu
extends JMenuItem
implements Accessible, MenuElement

An implementation of a menu -- a popup window containing JMenuItems that is displayed when the user selects an item on the JMenuBar. In addition to JMenuItems, a JMenu can also contain JSeparators.

In essence, a menu is a button with an associated JPopupMenu. When the "button" is pressed, the JPopupMenu appears. If the "button" is on the JMenuBar, the menu is a top-level window. If the "button" is another menu item, then the JPopupMenu is "pull-right" menu.

Menus can be configured, and to some degree controlled, by Actions. Using an Action with a menu has many benefits beyond directly configuring a menu. Refer to Swing Components Supporting Action for more details, and you can find more information in How to Use Actions, a section in The Java Tutorial.

For information and examples of using menus see How to Use Menus, a section in The Java Tutorial.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JMenuItem, JSeparator, JMenuBar, JPopupMenu

Nested Class Summary
protected class | JMenu.AccessibleJMenu This class implements accessibility support for the JMenu class.
protected class | JMenu.WinListener A listener class that watches for a popup window closing.
Nested classes/interfaces inherited from class javax.swing.JMenuItem
JMenuItem.AccessibleJMenuItem
Nested classes/interfaces inherited from class javax.swing.AbstractButton
AbstractButton.AccessibleAbstractButton, AbstractButton.ButtonChangeListener
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected  JMenu.WinListener popupListener
The window-closing listener for the popup.
Fields inherited from class javax.swing.AbstractButton
actionListener, BORDER_PAINTED_CHANGED_PROPERTY, changeEvent, changeListener, CONTENT_AREA_FILLED_CHANGED_PROPERTY, DISABLED_ICON_CHANGED_PROPERTY, DISABLED_SELECTED_ICON_CHANGED_PROPERTY, FOCUS_PAINTED_CHANGED_PROPERTY, HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY, HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY, ICON_CHANGED_PROPERTY, itemListener, MARGIN_CHANGED_PROPERTY, MNEMONIC_CHANGED_PROPERTY, model, MODEL_CHANGED_PROPERTY, PRESSED_ICON_CHANGED_PROPERTY, ROLLOVER_ENABLED_CHANGED_PROPERTY, ROLLOVER_ICON_CHANGED_PROPERTY, ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY, SELECTED_ICON_CHANGED_PROPERTY, TEXT_CHANGED_PROPERTY, VERTICAL_ALIGNMENT_CHANGED_PROPERTY, VERTICAL_TEXT_POSITION_CHANGED_PROPERTY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JMenu()
Constructs a new JMenu with no text.
JMenu(Action a)
Constructs a menu whose properties are taken from the Action supplied.
JMenu(String s)
Constructs a new JMenu with the supplied string as its text.
JMenu(String s, boolean b)
Constructs a new JMenu with the supplied string as its text and specified as a tear-off menu or not.
Method Summary
 JMenuItem add(Action a)
Creates a new menu item attached to the specified Action object and appends it to the end of this menu.
 Component add(Component c)
Appends a component to the end of this menu.
 Component add(Component c, int index)
Adds the specified component to this container at the given position.
 JMenuItem add(JMenuItem menuItem)
Appends a menu item to the end of this menu.
 JMenuItem add(String s)
Creates a new menu item with the specified text and appends it to the end of this menu.
 void addMenuListener(MenuListener l)
Adds a listener for menu events.
 void addSeparator()
Appends a new separator to the end of the menu.
 void applyComponentOrientation(ComponentOrientation o)
Sets the ComponentOrientation property of this menu and all components contained within it.
protected  PropertyChangeListener createActionChangeListener(JMenuItem b)
Returns a properly configured PropertyChangeListener which updates the control as changes to the Action occur.
protected  JMenuItem createActionComponent(Action a)
Factory method which creates the JMenuItem for Actions added to the JMenu.
protected  JMenu.WinListener createWinListener(JPopupMenu p)
Creates a window-closing listener for the popup.
 void doClick(int pressTime)
Programmatically performs a "click".
protected  void fireMenuCanceled()
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireMenuDeselected()
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireMenuSelected()
Notifies all listeners that have registered interest for notification on this event type.
 AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JMenu.
 Component getComponent()
Returns the java.awt.Component used to paint this MenuElement.
 int getDelay()
Returns the suggested delay, in milliseconds, before submenus are popped up or down.
 JMenuItem getItem(int pos)
Returns the JMenuItem at the specified position.
 int getItemCount()
Returns the number of items on the menu, including separators.
 Component getMenuComponent(int n)
Returns the component at position n.
 int getMenuComponentCount()
Returns the number of components on the menu.
 Component[] getMenuComponents()
Returns an array of Components of the menu's subcomponents.
 MenuListener[] getMenuListeners()
Returns an array of all the MenuListeners added to this JMenu with addMenuListener().
 JPopupMenu getPopupMenu()
Returns the popupmenu associated with this menu.
protected  Point getPopupMenuOrigin()
Computes the origin for the JMenu's popup menu.
 MenuElement[] getSubElements()
Returns an array of MenuElements containing the submenu for this menu component.
 String getUIClassID()
Returns the name of the L&F class that renders this component.
 JMenuItem insert(Action a, int pos)
Inserts a new menu item attached to the specified Action object at a given position.
 JMenuItem insert(JMenuItem mi, int pos)
Inserts the specified JMenuitem at a given position.
 void insert(String s, int pos)
Inserts a new menu item with the specified text at a given position.
 void insertSeparator(int index)
Inserts a separator at the specified position.
 boolean isMenuComponent(Component c)
Returns true if the specified component exists in the submenu hierarchy.
 boolean isPopupMenuVisible()
Returns true if the menu's popup window is visible.
 boolean isSelected()
Returns true if the menu is currently selected (highlighted).
 boolean isTearOff()
Returns true if the menu can be torn off.
 boolean isTopLevelMenu()
Returns true if the menu is a 'top-level menu', that is, if it is the direct child of a menubar.
 void menuSelectionChanged(boolean isIncluded)
Messaged when the menubar selection changes to activate or deactivate this menu.
protected  String paramString()
Returns a string representation of this JMenu.
protected  void processKeyEvent(KeyEvent evt)
Processes key stroke events such as mnemonics and accelerators.
 void remove(Component c)
Removes the component c from this menu.
 void remove(int pos)
Removes the menu item at the specified index from this menu.
 void remove(JMenuItem item)
Removes the specified menu item from this menu.
 void removeAll()
Removes all menu items from this menu.
 void removeMenuListener(MenuListener l)
Removes a listener for menu events.
 void setAccelerator(KeyStroke keyStroke)
setAccelerator is not defined for JMenu.
 void setComponentOrientation(ComponentOrientation o)
Sets the language-sensitive orientation that is to be used to order the elements or text within this component.
 void setDelay(int d)
Sets the suggested delay before the menu's PopupMenu is popped up or down.
 void setMenuLocation(int x, int y)
Sets the location of the popup component.
 void setModel(ButtonModel newModel)
Sets the data model for the "menu button" -- the label that the user clicks to open or close the menu.
 void setPopupMenuVisible(boolean b)
Sets the visibility of the menu's popup.
 void setSelected(boolean b)
Sets the selection status of the menu.
 void updateUI()
Resets the UI property with a value from the current look and feel.
Methods inherited from class javax.swing.JMenuItem
actionPropertyChanged, addMenuDragMouseListener, addMenuKeyListener, configurePropertiesFromAction, fireMenuDragMouseDragged, fireMenuDragMouseEntered, fireMenuDragMouseExited, fireMenuDragMouseReleased, fireMenuKeyPressed, fireMenuKeyReleased, fireMenuKeyTyped, getAccelerator, getMenuDragMouseListeners, getMenuKeyListeners, init, isArmed, processKeyEvent, processMenuDragMouseEvent, processMenuKeyEvent, processMouseEvent, removeMenuDragMouseListener, removeMenuKeyListener, setArmed, setEnabled, setUI
Methods inherited from class javax.swing.AbstractButton
addActionListener, addChangeListener, addImpl, addItemListener, checkHorizontalKey, checkVerticalKey, createActionListener, createActionPropertyChangeListener, createChangeListener, createItemListener, doClick, fireActionPerformed, fireItemStateChanged, fireStateChanged, getAction, getActionCommand, getActionListeners, getChangeListeners, getDisabledIcon, getDisabledSelectedIcon, getDisplayedMnemonicIndex, getHideActionText, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getItemListeners, getLabel, getMargin, getMnemonic, getModel, getMultiClickThreshhold, getPressedIcon, getRolloverIcon, getRolloverSelectedIcon, getSelectedIcon, getSelectedObjects, getText, getUI, getVerticalAlignment, getVerticalTextPosition, imageUpdate, isBorderPainted, isContentAreaFilled, isFocusPainted, isRolloverEnabled, paintBorder, removeActionListener, removeChangeListener, removeItemListener, removeNotify, setAction, setActionCommand, setBorderPainted, setContentAreaFilled, setDisabledIcon, setDisabledSelectedIcon, setDisplayedMnemonicIndex, setFocusPainted, setHideActionText, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabel, setLayout, setMargin, setMnemonic, setMnemonic, setMultiClickThreshhold, setPressedIcon, setRolloverEnabled, setRolloverIcon, setRolloverSelectedIcon, setSelectedIcon, setText, setUI, setVerticalAlignment, setVerticalTextPosition
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface javax.swing.MenuElement
processKeyEvent, processMouseEvent

Field Detail

popupListener

protected JMenu.WinListener popupListener
The window-closing listener for the popup.

See Also:
JMenu.WinListener
Constructor Detail

JMenu

public JMenu()
Constructs a new JMenu with no text.

JMenu

public JMenu(String s)
Constructs a new JMenu with the supplied string as its text.

Parameters:
s - the text for the menu label

JMenu

public JMenu(Action a)
Constructs a menu whose properties are taken from the Action supplied.

Parameters:
a - an Action
Since:
1.3

JMenu

public JMenu(String s,
             boolean b)
Constructs a new JMenu with the supplied string as its text and specified as a tear-off menu or not.

Parameters:
s - the text for the menu label
b - can the menu be torn off (not yet implemented)
Method Detail

updateUI

public void updateUI()
Resets the UI property with a value from the current look and feel.

Overrides:
updateUI in class JMenuItem
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JMenuItem
Returns:
the string "MenuUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

setModel

public void setModel(ButtonModel newModel)
Sets the data model for the "menu button" -- the label that the user clicks to open or close the menu.

Overrides:
setModel in class JMenuItem
Parameters:
newModel - the ButtonModel
See Also:
AbstractButton.getModel()

isSelected

public boolean isSelected()
Returns true if the menu is currently selected (highlighted).

Overrides:
isSelected in class AbstractButton
Returns:
true if the menu is selected, else false

setSelected

public void setSelected(boolean b)
Sets the selection status of the menu.

Overrides:
setSelected in class AbstractButton
Parameters:
b - true to select (highlight) the menu; false to de-select the menu

isPopupMenuVisible

public boolean isPopupMenuVisible()
Returns true if the menu's popup window is visible.

Returns:
true if the menu is visible, else false

setPopupMenuVisible

public void setPopupMenuVisible(boolean b)
Sets the visibility of the menu's popup. If the menu is not enabled, this method will have no effect.

Parameters:
b - a boolean value -- true to make the menu visible, false to hide it

getPopupMenuOrigin

protected Point getPopupMenuOrigin()
Computes the origin for the JMenu's popup menu. This method uses Look and Feel properties named Menu.menuPopupOffsetX, Menu.menuPopupOffsetY, Menu.submenuPopupOffsetX, and Menu.submenuPopupOffsetY to adjust the exact location of popup.

Returns:
a Point in the coordinate space of the menu which should be used as the origin of the JMenu's popup menu
Since:
1.3

getDelay

public int getDelay()
Returns the suggested delay, in milliseconds, before submenus are popped up or down. Each look and feel (L&F) may determine its own policy for observing the delay property. In most cases, the delay is not observed for top level menus or while dragging. The default for delay is 0. This method is a property of the look and feel code and is used to manage the idiosyncracies of the various UI implementations.

Returns:
the delay property

setDelay

public void setDelay(int d)
Sets the suggested delay before the menu's PopupMenu is popped up or down. Each look and feel (L&F) may determine it's own policy for observing the delay property. In most cases, the delay is not observed for top level menus or while dragging. This method is a property of the look and feel code and is used to manage the idiosyncracies of the various UI implementations.

Parameters:
d - the number of milliseconds to delay
Throws:
IllegalArgumentException - if d is less than 0

setMenuLocation

public void setMenuLocation(int x,
                            int y)
Sets the location of the popup component.

Parameters:
x - the x coordinate of the popup's new position
y - the y coordinate of the popup's new position

add

public JMenuItem add(JMenuItem menuItem)
Appends a menu item to the end of this menu. Returns the menu item added.

Parameters:
menuItem - the JMenuitem to be added
Returns:
the JMenuItem added

add

public Component add(Component c)
Appends a component to the end of this menu. Returns the component added.

Overrides:
add in class Container
Parameters:
c - the Component to add
Returns:
the Component added
See Also:
Container.addImpl(java.awt.Component, java.lang.Object, int),
Container.validate(),
JComponent.revalidate()

add

public Component add(Component c,
                     int index)
Adds the specified component to this container at the given position. If index equals -1, the component will be appended to the end.

Overrides:
add in class Container
Parameters:
c - the Component to add
index - the position at which to insert the component
Returns:
the Component added
See Also:
remove(javax.swing.JMenuItem), Container.add(Component, int)

add

public JMenuItem add(String s)
Creates a new menu item with the specified text and appends it to the end of this menu.

Parameters:
s - the string for the menu item to be added

add

public JMenuItem add(Action a)
Creates a new menu item attached to the specified Action object and appends it to the end of this menu.

Parameters:
a - the Action for the menu item to be added
See Also:
Action

createActionComponent

protected JMenuItem createActionComponent(Action a)
Factory method which creates the JMenuItem for Actions added to the JMenu.

Parameters:
a - the Action for the menu item to be added
Returns:
the new menu item
Since:
1.3
See Also:
Action

createActionChangeListener

protected PropertyChangeListener createActionChangeListener(JMenuItem b)
Returns a properly configured PropertyChangeListener which updates the control as changes to the Action occur.

addSeparator

public void addSeparator()
Appends a new separator to the end of the menu.

insert

public void insert(String s,
                   int pos)
Inserts a new menu item with the specified text at a given position.

Parameters:
s - the text for the menu item to add
pos - an integer specifying the position at which to add the new menu item
Throws:
IllegalArgumentException - when the value of pos < 0

insert

public JMenuItem insert(JMenuItem mi,
                        int pos)
Inserts the specified JMenuitem at a given position.

Parameters:
mi - the JMenuitem to add
pos - an integer specifying the position at which to add the new JMenuitem
Returns:
the new menu item
Throws:
IllegalArgumentException - if the value of pos < 0

insert

public JMenuItem insert(Action a,
                        int pos)
Inserts a new menu item attached to the specified Action object at a given position.

Parameters:
a - the Action object for the menu item to add
pos - an integer specifying the position at which to add the new menu item
Throws:
IllegalArgumentException - if the value of pos < 0

insertSeparator

public void insertSeparator(int index)
Inserts a separator at the specified position.

Parameters:
index - an integer specifying the position at which to insert the menu separator
Throws:
IllegalArgumentException - if the value of index < 0

getItem

public JMenuItem getItem(int pos)
Returns the JMenuItem at the specified position. If the component at pos is not a menu item, null is returned. This method is included for AWT compatibility.

Parameters:
pos - an integer specifying the position
Returns:
the menu item at the specified position; or null if the item as the specified position is not a menu item
Throws:
IllegalArgumentException - if the value of pos < 0

getItemCount

public int getItemCount()
Returns the number of items on the menu, including separators. This method is included for AWT compatibility.

Returns:
an integer equal to the number of items on the menu
See Also:
getMenuComponentCount()

isTearOff

public boolean isTearOff()
Returns true if the menu can be torn off. This method is not yet implemented.

Returns:
true if the menu can be torn off, else false
Throws:
Error - if invoked -- this method is not yet implemented

remove

public void remove(JMenuItem item)
Removes the specified menu item from this menu. If there is no popup menu, this method will have no effect.

Parameters:
item - the JMenuItem to be removed from the menu

remove

public void remove(int pos)
Removes the menu item at the specified index from this menu.

Overrides:
remove in class Container
Parameters:
pos - the position of the item to be removed
Throws:
IllegalArgumentException - if the value of pos < 0, or if pos is greater than the number of menu items
See Also:
Container.add(java.awt.Component),
Container.validate(),
Container.getComponentCount()

remove

public void remove(Component c)
Removes the component c from this menu.

Overrides:
remove in class Container
Parameters:
c - the component to be removed
See Also:
Container.add(java.awt.Component),
Container.validate(),
Container.remove(int)

removeAll

public void removeAll()
Removes all menu items from this menu.

Overrides:
removeAll in class Container
See Also:
Container.add(java.awt.Component), Container.remove(int)

getMenuComponentCount

public int getMenuComponentCount()
Returns the number of components on the menu.

Returns:
an integer containing the number of components on the menu

getMenuComponent

public Component getMenuComponent(int n)
Returns the component at position n.

Parameters:
n - the position of the component to be returned
Returns:
the component requested, or null if there is no popup menu

getMenuComponents

public Component[] getMenuComponents()
Returns an array of Components of the menu's subcomponents. Note that this returns all Components in the popup menu, including separators.

Returns:
an array of Components or an empty array if there is no popup menu

isTopLevelMenu

public boolean isTopLevelMenu()
Returns true if the menu is a 'top-level menu', that is, if it is the direct child of a menubar.

Returns:
true if the menu is activated from the menu bar; false if the menu is activated from a menu item on another menu

isMenuComponent

public boolean isMenuComponent(Component c)
Returns true if the specified component exists in the submenu hierarchy.

Parameters:
c - the Component to be tested
Returns:
true if the Component exists, false otherwise

getPopupMenu

public JPopupMenu getPopupMenu()
Returns the popupmenu associated with this menu. If there is no popupmenu, it will create one.

addMenuListener

public void addMenuListener(MenuListener l)
Adds a listener for menu events.

Parameters:
l - the listener to be added

removeMenuListener

public void removeMenuListener(MenuListener l)
Removes a listener for menu events.

Parameters:
l - the listener to be removed

getMenuListeners

public MenuListener[] getMenuListeners()
Returns an array of all the MenuListeners added to this JMenu with addMenuListener().

Returns:
all of the MenuListeners added or an empty array if no listeners have been added
Since:
1.4

fireMenuSelected

protected void fireMenuSelected()
Notifies all listeners that have registered interest for notification on this event type. The event instance is created lazily.

Throws:
Error - if there is a null listener
See Also:
EventListenerList

fireMenuDeselected

protected void fireMenuDeselected()
Notifies all listeners that have registered interest for notification on this event type. The event instance is created lazily.

Throws:
Error - if there is a null listener
See Also:
EventListenerList

fireMenuCanceled

protected void fireMenuCanceled()
Notifies all listeners that have registered interest for notification on this event type. The event instance is created lazily.

Throws:
Error - if there is a null listener
See Also:
EventListenerList

createWinListener

protected JMenu.WinListener createWinListener(JPopupMenu p)
Creates a window-closing listener for the popup.

Parameters:
p - the JPopupMenu
Returns:
the new window-closing listener
See Also:
JMenu.WinListener

menuSelectionChanged

public void menuSelectionChanged(boolean isIncluded)
Messaged when the menubar selection changes to activate or deactivate this menu. Overrides JMenuItem.menuSelectionChanged.

Specified by:
menuSelectionChanged in interface MenuElement
Overrides:
menuSelectionChanged in class JMenuItem
Parameters:
isIncluded - true if this menu is active, false if it is not
See Also:
MenuSelectionManager.setSelectedPath(MenuElement[])

getSubElements

public MenuElement[] getSubElements()
Returns an array of MenuElements containing the submenu for this menu component. If popup menu is null returns an empty array. This method is required to conform to the MenuElement interface. Note that since JSeparators do not conform to the MenuElement interface, this array will only contain JMenuItems.

Specified by:
getSubElements in interface MenuElement
Overrides:
getSubElements in class JMenuItem
Returns:
an array of MenuElement objects

getComponent

public Component getComponent()
Returns the java.awt.Component used to paint this MenuElement. The returned component is used to convert events and detect if an event is inside a menu component.

Specified by:
getComponent in interface MenuElement
Overrides:
getComponent in class JMenuItem
Returns:
the Component that paints this menu item

applyComponentOrientation

public void applyComponentOrientation(ComponentOrientation o)
Sets the ComponentOrientation property of this menu and all components contained within it. This includes all components returned by getMenuComponents.

Overrides:
applyComponentOrientation in class Container
Parameters:
o - the new component orientation of this menu and the components contained within it.
Throws:
NullPointerException - if orientation is null.
Since:
1.4
See Also:
Component.setComponentOrientation(java.awt.ComponentOrientation), Component.getComponentOrientation()

setComponentOrientation

public void setComponentOrientation(ComponentOrientation o)
Description copied from class: Component
Sets the language-sensitive orientation that is to be used to order the elements or text within this component. Language-sensitive LayoutManager and Component subclasses will use this property to determine how to lay out and draw components.

At construction time, a component's orientation is set to ComponentOrientation.UNKNOWN, indicating that it has not been specified explicitly. The UNKNOWN orientation behaves the same as ComponentOrientation.LEFT_TO_RIGHT.

To set the orientation of a single component, use this method. To set the orientation of an entire component hierarchy, use applyComponentOrientation.

Overrides:
setComponentOrientation in class Component
See Also:
ComponentOrientation

setAccelerator

public void setAccelerator(KeyStroke keyStroke)
setAccelerator is not defined for JMenu. Use setMnemonic instead.

Overrides:
setAccelerator in class JMenuItem
Parameters:
keyStroke - the keystroke combination which will invoke the JMenuItem's actionlisteners without navigating the menu hierarchy
Throws:
Error - if invoked -- this method is not defined for JMenu. Use setMnemonic instead

processKeyEvent

protected void processKeyEvent(KeyEvent evt)
Processes key stroke events such as mnemonics and accelerators.

Overrides:
processKeyEvent in class JComponent
Parameters:
evt - the key event to be processed
See Also:
KeyEvent, KeyListener, KeyboardFocusManager, DefaultKeyboardFocusManager, Component.processEvent(java.awt.AWTEvent), Component.dispatchEvent(java.awt.AWTEvent), Component.addKeyListener(java.awt.event.KeyListener), Component.enableEvents(long), Component.isShowing()

doClick

public void doClick(int pressTime)
Programmatically performs a "click". This overrides the method AbstractButton.doClick in order to make the menu pop up.

Overrides:
doClick in class AbstractButton
Parameters:
pressTime - indicates the number of milliseconds the button was pressed for

paramString

protected String paramString()
Returns a string representation of this JMenu. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JMenuItem
Returns:
a string representation of this JMenu.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JMenu. For JMenus, the AccessibleContext takes the form of an AccessibleJMenu. A new AccessibleJMenu instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JMenuItem
Returns:
an AccessibleJMenu that serves as the AccessibleContext of this JMenu
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMenu.AccessibleJMenu

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JMenu.AccessibleJMenu

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.AbstractButton.AccessibleAbstractButton
                        extended by  javax.swing.JMenuItem.AccessibleJMenuItem
                            extended by  javax.swing.JMenu.AccessibleJMenu
All Implemented Interfaces:
Serializable, EventListener, AccessibleAction, AccessibleComponent, AccessibleExtendedComponent, AccessibleSelection, AccessibleText, AccessibleValue, ChangeListener
Enclosing class:
JMenu
protected class JMenu.AccessibleJMenu
extends JMenuItem.AccessibleJMenuItem
implements AccessibleSelection

This class implements accessibility support for the JMenu class. It provides an implementation of the Java Accessibility API appropriate to menu user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Constructor Summary
protected JMenu.AccessibleJMenu()
Method Summary
void | addAccessibleSelection(int i) Selects the ith menu in the menu.
void | clearAccessibleSelection() Clears the selection in the object, so that nothing in the object is selected.
Accessible | getAccessibleChild(int i) Returns the nth Accessible child of the object.
int | getAccessibleChildrenCount() Returns the number of accessible children in the object.
AccessibleRole | getAccessibleRole() Get the role of this object.
AccessibleSelection | getAccessibleSelection() Get the AccessibleSelection associated with this object.
Accessible | getAccessibleSelection(int i) Returns the currently selected sub-menu if one is selected, otherwise null (there can only be one selection, and it can only be a sub-menu, as otherwise menu items don't remain selected).
int | getAccessibleSelectionCount() Returns 1 if a sub-menu is currently selected in this menu.
boolean | isAccessibleChildSelected(int i) Returns true if the current child of this object is selected (that is, if this child is a popped-up submenu).
void | removeAccessibleSelection(int i) Removes the nth item from the selection.
void | selectAllAccessibleSelection() Normally causes every selected item in the object to be selected if the object supports multiple selections.
Methods inherited from class javax.swing.JMenuItem.AccessibleJMenuItem
stateChanged
Methods inherited from class javax.swing.AbstractButton.AccessibleAbstractButton
doAccessibleAction, getAccessibleAction, getAccessibleActionCount, getAccessibleActionDescription, getAccessibleIcon, getAccessibleKeyBinding, getAccessibleName, getAccessibleRelationSet, getAccessibleStateSet, getAccessibleText, getAccessibleValue, getAfterIndex, getAtIndex, getBeforeIndex, getCaretPosition, getCharacterAttribute, getCharacterBounds, getCharCount, getCurrentAccessibleValue, getIndexAtPoint, getMaximumAccessibleValue, getMinimumAccessibleValue, getSelectedText, getSelectionEnd, getSelectionStart, getTitledBorderText, getToolTipText, setCurrentAccessibleValue
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleDescription, getBorderTitle, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleEditableText, getAccessibleTable, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JMenu.AccessibleJMenu

protected JMenu.AccessibleJMenu()
Method Detail

getAccessibleChildrenCount

public int getAccessibleChildrenCount()
Returns the number of accessible children in the object. If all of the children of this object implement Accessible, than this method should return the number of children of this object.

Overrides:
getAccessibleChildrenCount in class JComponent.AccessibleJComponent
Returns:
the number of accessible children in the object.

getAccessibleChild

public Accessible getAccessibleChild(int i)
Returns the nth Accessible child of the object.

Overrides:
getAccessibleChild in class JComponent.AccessibleJComponent
Parameters:
i - zero-based index of child
Returns:
the nth Accessible child of the object
See Also:
AccessibleContext.getAccessibleChildrenCount()

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JMenuItem.AccessibleJMenuItem
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleSelection

public AccessibleSelection getAccessibleSelection()
Get the AccessibleSelection associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleSelection interface on behalf of itself.

Overrides:
getAccessibleSelection in class AccessibleContext
Returns:
this object
See Also:
AccessibleSelection

getAccessibleSelectionCount

public int getAccessibleSelectionCount()
Returns 1 if a sub-menu is currently selected in this menu.

Specified by:
getAccessibleSelectionCount in interface AccessibleSelection
Returns:
1 if a menu is currently selected, else 0

getAccessibleSelection

public Accessible getAccessibleSelection(int i)
Returns the currently selected sub-menu if one is selected, otherwise null (there can only be one selection, and it can only be a sub-menu, as otherwise menu items don't remain selected).

Specified by:
getAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of selected children
Returns:
the i-th selected child
See Also:
AccessibleSelection.getAccessibleSelectionCount()

isAccessibleChildSelected

public boolean isAccessibleChildSelected(int i)
Returns true if the current child of this object is selected (that is, if this child is a popped-up submenu).

Specified by:
isAccessibleChildSelected in interface AccessibleSelection
Parameters:
i - the zero-based index of the child in this Accessible object.
Returns:
true if the current child of this object is selected; else false.
See Also:
AccessibleContext.getAccessibleChild(int)

addAccessibleSelection

public void addAccessibleSelection(int i)
Selects the ith menu in the menu. If that item is a submenu, it will pop up in response. If a different item is already popped up, this will force it to close. If this is a sub-menu that is already popped up (selected), this method has no effect.

Specified by:
addAccessibleSelection in interface AccessibleSelection
Parameters:
i - the index of the item to be selected
See Also:
AbstractButton.AccessibleAbstractButton.getAccessibleStateSet()

removeAccessibleSelection

public void removeAccessibleSelection(int i)
Removes the nth item from the selection. In general, menus can only have one item within them selected at a time (e.g. one sub-menu popped open).

Specified by:
removeAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of the selected item
See Also:
AccessibleContext.getAccessibleChild(int)

clearAccessibleSelection

public void clearAccessibleSelection()
Clears the selection in the object, so that nothing in the object is selected. This will close any open sub-menu.

Specified by:
clearAccessibleSelection in interface AccessibleSelection

selectAllAccessibleSelection

public void selectAllAccessibleSelection()
Normally causes every selected item in the object to be selected if the object supports multiple selections. This method makes no sense in a menu bar, and so does nothing.

Specified by:
selectAllAccessibleSelection in interface AccessibleSelection
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMenu.WinListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JMenu.WinListener

java.lang.Object
    extended by  java.awt.event.WindowAdapter
        extended by  javax.swing.JMenu.WinListener
All Implemented Interfaces:
WindowFocusListener, WindowListener, WindowStateListener, Serializable, EventListener
Enclosing class:
JMenu
protected class JMenu.WinListener
extends WindowAdapter
implements Serializable

A listener class that watches for a popup window closing. When the popup is closing, the listener deselects the menu.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
JMenu.WinListener(JPopupMenu p)
Create the window listener for the specified popup.
Method Summary
 void windowClosing(WindowEvent e)
Deselect the menu when the popup is closed from outside.
Methods inherited from class java.awt.event.WindowAdapter
windowActivated, windowClosed, windowDeactivated, windowDeiconified, windowGainedFocus, windowIconified, windowLostFocus, windowOpened, windowStateChanged
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JMenu.WinListener

public JMenu.WinListener(JPopupMenu p)
Create the window listener for the specified popup.

Since:
1.4
Method Detail

windowClosing

public void windowClosing(WindowEvent e)
Deselect the menu when the popup is closed from outside.

Specified by:
windowClosing in interface WindowListener
Overrides:
windowClosing in class WindowAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMenuBar

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JMenuBar

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JMenuBar
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, MenuElement
Direct Known Subclasses:
BasicInternalFrameTitlePane.SystemMenuBar
public class JMenuBar
extends JComponent
implements Accessible, MenuElement

An implementation of a menu bar. You add JMenu objects to the menu bar to construct a menu. When the user selects a JMenu object, its associated JPopupMenu is displayed, allowing the user to select one of the JMenuItems on it.

For information and examples of using menu bars see How to Use Menus, a section in The Java Tutorial.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JMenu, JPopupMenu, JMenuItem

Nested Class Summary
protected  class JMenuBar.AccessibleJMenuBar
This class implements accessibility support for the JMenuBar class.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JMenuBar()
Creates a new menu bar.
Method Summary
JMenu | add(JMenu c) Appends the specified menu to the end of the menu bar.
void | addNotify() Overrides JComponent.addNotify to register this menu bar with the current keyboard manager.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JMenuBar.
Component | getComponent() Implemented to be a MenuElement.
Component | getComponentAtIndex(int i) Deprecated. replaced by getComponent(int i)
int | getComponentIndex(Component c) Returns the index of the specified component.
JMenu | getHelpMenu() Gets the help menu for the menu bar.
Insets | getMargin() Returns the margin between the menubar's border and its menus.
JMenu | getMenu(int index) Returns the menu at the specified position in the menu bar.
int | getMenuCount() Returns the number of items in the menu bar.
SingleSelectionModel | getSelectionModel() Returns the model object that handles single selections.
MenuElement[] | getSubElements() Implemented to be a MenuElement -- returns the menus in this menu bar.
MenuBarUI | getUI() Returns the menubar's current UI.
String | getUIClassID() Returns the name of the L&F class that renders this component.
boolean | isBorderPainted() Returns true if the menu bars border should be painted.
boolean | isSelected() Returns true if the menu bar currently has a component selected.
void | menuSelectionChanged(boolean isIncluded) Implemented to be a MenuElement -- does nothing.
protected void | paintBorder(Graphics g) Paints the menubar's border if BorderPainted property is true.
protected String | paramString() Returns a string representation of this JMenuBar.
protected boolean | processKeyBinding(KeyStroke ks, KeyEvent e, int condition, boolean pressed) Subclassed to check all the child menus.
void | processKeyEvent(KeyEvent e, MenuElement[] path, MenuSelectionManager manager) Implemented to be a MenuElement -- does nothing.
void | processMouseEvent(MouseEvent event, MenuElement[] path, MenuSelectionManager manager) Implemented to be a MenuElement -- does nothing.
void | removeNotify() Overrides JComponent.removeNotify to unregister this menu bar with the current keyboard manager.
void | setBorderPainted(boolean b) Sets whether the border should be painted.
void | setHelpMenu(JMenu menu) Sets the help menu that appears when the user selects the "help" option in the menu bar.
void | setMargin(Insets m) Sets the margin between the menubar's border and its menus.
void | setSelected(Component sel) Sets the currently selected component, producing a a change to the selection model.
void | setSelectionModel(SingleSelectionModel model) Sets the model object to handle single selections.
void | setUI(MenuBarUI ui) Sets the L&F object that renders this component.
void | updateUI() Resets the UI property with a value from the current look and feel.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JMenuBar

public JMenuBar()
Creates a new menu bar.

Method Detail

getUI

public MenuBarUI getUI()
Returns the menubar's current UI.

See Also:
setUI(javax.swing.plaf.MenuBarUI)

setUI

public void setUI(MenuBarUI ui)
Sets the L&F object that renders this component.

Parameters:
ui - the new MenuBarUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Resets the UI property with a value from the current look and feel.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "MenuBarUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

getSelectionModel

public SingleSelectionModel getSelectionModel()
Returns the model object that handles single selections.

Returns:
the SingleSelectionModel property
See Also:
SingleSelectionModel

setSelectionModel

public void setSelectionModel(SingleSelectionModel model)
Sets the model object to handle single selections.

Parameters:
model - the SingleSelectionModel to use
See Also:
SingleSelectionModel

add

public JMenu add(JMenu c)
Appends the specified menu to the end of the menu bar.

Parameters:
c - the JMenu component to add
Returns:
the menu component

getMenu

public JMenu getMenu(int index)
Returns the menu at the specified position in the menu bar.

Parameters:
index - an integer giving the position in the menu bar, where 0 is the first position
Returns:
the JMenu at that position, or null if if there is no JMenu at that position (ie. if it is a JMenuItem)

getMenuCount

public int getMenuCount()
Returns the number of items in the menu bar.

Returns:
the number of items in the menu bar

setHelpMenu

public void setHelpMenu(JMenu menu)
Sets the help menu that appears when the user selects the "help" option in the menu bar. This method is not yet implemented and will throw an exception.

Parameters:
menu - the JMenu that delivers help to the user

getHelpMenu

public JMenu getHelpMenu()
Gets the help menu for the menu bar. This method is not yet implemented and will throw an exception.

Returns:
the JMenu that delivers help to the user

getComponentAtIndex

@Deprecated
public Component getComponentAtIndex(int i)
Deprecated. replaced by getComponent(int i)

Returns the component at the specified index.

Parameters:
i - an integer specifying the position, where 0 is first
Returns:
the Component at the position, or null for an invalid index

getComponentIndex

public int getComponentIndex(Component c)
Returns the index of the specified component.

Parameters:
c - the Component to find
Returns:
an integer giving the component's position, where 0 is first; or -1 if it can't be found

setSelected

public void setSelected(Component sel)
Sets the currently selected component, producing a a change to the selection model.

Parameters:
sel - the Component to select

isSelected

public boolean isSelected()
Returns true if the menu bar currently has a component selected.

Returns:
true if a selection has been made, else false

isBorderPainted

public boolean isBorderPainted()
Returns true if the menu bars border should be painted.

Returns:
true if the border should be painted, else false

setBorderPainted

public void setBorderPainted(boolean b)
Sets whether the border should be painted.

Parameters:
b - if true and border property is not null, the border is painted.
See Also:
isBorderPainted()

paintBorder

protected void paintBorder(Graphics g)
Paints the menubar's border if BorderPainted property is true.

Overrides:
paintBorder in class JComponent
Parameters:
g - the Graphics context to use for painting
See Also:
JComponent.paint(java.awt.Graphics), JComponent.setBorder(javax.swing.border.Border)

setMargin

public void setMargin(Insets m)
Sets the margin between the menubar's border and its menus. Setting to null will cause the menubar to use the default margins.

Parameters:
m - an Insets object containing the margin values
See Also:
Insets

getMargin

public Insets getMargin()
Returns the margin between the menubar's border and its menus. If there is no previous margin, it will create a default margin with zero size.

Returns:
an Insets object containing the margin values
See Also:
Insets

processMouseEvent

public void processMouseEvent(MouseEvent event,
                              MenuElement[] path,
                              MenuSelectionManager manager)
Implemented to be a MenuElement -- does nothing.

Specified by:
processMouseEvent in interface MenuElement
See Also:
getSubElements()

processKeyEvent

public void processKeyEvent(KeyEvent e,
                            MenuElement[] path,
                            MenuSelectionManager manager)
Implemented to be a MenuElement -- does nothing.

Specified by:
processKeyEvent in interface MenuElement
See Also:
getSubElements()

menuSelectionChanged

public void menuSelectionChanged(boolean isIncluded)
Implemented to be a MenuElement -- does nothing.

Specified by:
menuSelectionChanged in interface MenuElement
See Also:
getSubElements()

getSubElements

public MenuElement[] getSubElements()
Implemented to be a MenuElement -- returns the menus in this menu bar. This is the reason for implementing the MenuElement interface -- so that the menu bar can be treated the same as other menu elements.

Specified by:
getSubElements in interface MenuElement
Returns:
an array of menu items in the menu bar.

getComponent

public Component getComponent()
Implemented to be a MenuElement. Returns this object.

Specified by:
getComponent in interface MenuElement
Returns:
the current Component (this)
See Also:
getSubElements()

paramString

protected String paramString()
Returns a string representation of this JMenuBar. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JMenuBar

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JMenuBar. For JMenuBars, the AccessibleContext takes the form of an AccessibleJMenuBar. A new AccessibleJMenuBar instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJMenuBar that serves as the AccessibleContext of this JMenuBar

processKeyBinding

protected boolean processKeyBinding(KeyStroke ks,
                                    KeyEvent e,
                                    int condition,
                                    boolean pressed)
Subclassed to check all the child menus.

Overrides:
processKeyBinding in class JComponent
Parameters:
ks - the KeyStroke queried
e - the KeyEvent
condition - one of the following values:
  • JComponent.WHEN_FOCUSED
  • JComponent.WHEN_ANCESTOR_OF_FOCUSED_COMPONENT
  • JComponent.WHEN_IN_FOCUSED_WINDOW
pressed - true if the key is pressed
Returns:
true if there was a binding to an action, and the action was enabled
Since:
1.3

addNotify

public void addNotify()
Overrides JComponent.addNotify to register this menu bar with the current keyboard manager.

Overrides:
addNotify in class JComponent
See Also:
JComponent.registerKeyboardAction(java.awt.event.ActionListener, java.lang.String, javax.swing.KeyStroke, int)

removeNotify

public void removeNotify()
Overrides JComponent.removeNotify to unregister this menu bar with the current keyboard manager.

Overrides:
removeNotify in class JComponent
See Also:
JComponent.registerKeyboardAction(java.awt.event.ActionListener, java.lang.String, javax.swing.KeyStroke, int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMenuBar.AccessibleJMenuBar

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JMenuBar.AccessibleJMenuBar

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JMenuBar.AccessibleJMenuBar
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent, AccessibleSelection
Enclosing class:
JMenuBar
protected class JMenuBar.AccessibleJMenuBar
extends JComponent.AccessibleJComponent
implements AccessibleSelection

This class implements accessibility support for the JMenuBar class. It provides an implementation of the Java Accessibility API appropriate to menu bar user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JMenuBar.AccessibleJMenuBar()
Method Summary
void | addAccessibleSelection(int i) Selects the nth menu in the menu bar, forcing it to pop up.
void | clearAccessibleSelection() Clears the selection in the object, so that nothing in the object is selected.
AccessibleRole | getAccessibleRole() Get the role of this object.
AccessibleSelection | getAccessibleSelection() Get the AccessibleSelection associated with this object.
Accessible | getAccessibleSelection(int i) Returns the currently selected menu if one is selected, otherwise null.
int | getAccessibleSelectionCount() Returns 1 if a menu is currently selected in this menu bar.
AccessibleStateSet | getAccessibleStateSet() Get the accessible state set of this object.
boolean | isAccessibleChildSelected(int i) Returns true if the current child of this object is selected.
void | removeAccessibleSelection(int i) Removes the nth selected item in the object from the object's selection.
void | selectAllAccessibleSelection() Normally causes every selected item in the object to be selected if the object supports multiple selections.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JMenuBar.AccessibleJMenuBar

protected JMenuBar.AccessibleJMenuBar()
Method Detail

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Get the accessible state set of this object.

Overrides:
getAccessibleStateSet in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleState containing the current state of the object
See Also:
AccessibleState

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleSelection

public AccessibleSelection getAccessibleSelection()
Get the AccessibleSelection associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleSelection interface on behalf of itself.

Overrides:
getAccessibleSelection in class AccessibleContext
Returns:
this object
See Also:
AccessibleSelection

getAccessibleSelectionCount

public int getAccessibleSelectionCount()
Returns 1 if a menu is currently selected in this menu bar.

Specified by:
getAccessibleSelectionCount in interface AccessibleSelection
Returns:
1 if a menu is currently selected, else 0

getAccessibleSelection

public Accessible getAccessibleSelection(int i)
Returns the currently selected menu if one is selected, otherwise null.

Specified by:
getAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of selected children
Returns:
the i-th selected child
See Also:
AccessibleSelection.getAccessibleSelectionCount()

isAccessibleChildSelected

public boolean isAccessibleChildSelected(int i)
Returns true if the current child of this object is selected.

Specified by:
isAccessibleChildSelected in interface AccessibleSelection
Parameters:
i - the zero-based index of the child in this Accessible object.
Returns:
true if the current child of this object is selected; else false.
See Also:
AccessibleContext.getAccessibleChild(int)

addAccessibleSelection

public void addAccessibleSelection(int i)
Selects the nth menu in the menu bar, forcing it to pop up. If another menu is popped up, this will force it to close. If the nth menu is already selected, this method has no effect.

Specified by:
addAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of selectable items
See Also:
getAccessibleStateSet()

removeAccessibleSelection

public void removeAccessibleSelection(int i)
Removes the nth selected item in the object from the object's selection. If the nth item isn't currently selected, this method has no effect. Otherwise, it closes the popup menu.

Specified by:
removeAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of selectable items
See Also:
AccessibleContext.getAccessibleChild(int)

clearAccessibleSelection

public void clearAccessibleSelection()
Clears the selection in the object, so that nothing in the object is selected. This will close any open menu.

Specified by:
clearAccessibleSelection in interface AccessibleSelection

selectAllAccessibleSelection

public void selectAllAccessibleSelection()
Normally causes every selected item in the object to be selected if the object supports multiple selections. This method makes no sense in a menu bar, and so does nothing.

Specified by:
selectAllAccessibleSelection in interface AccessibleSelection
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMenuItem

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JMenuItem

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.AbstractButton
                    extended by  javax.swing.JMenuItem
All Implemented Interfaces:
ImageObserver, ItemSelectable, MenuContainer, Serializable, Accessible, MenuElement, SwingConstants
Direct Known Subclasses:
JCheckBoxMenuItem, JMenu, JRadioButtonMenuItem
public class JMenuItem
extends AbstractButton
implements Accessible, MenuElement

An implementation of an item in a menu. A menu item is essentially a button sitting in a list. When the user selects the "button", the action associated with the menu item is performed. A JMenuItem contained in a JPopupMenu performs exactly that function.

Menu items can be configured, and to some degree controlled, by Actions. Using an Action with a menu item has many benefits beyond directly configuring a menu item. Refer to Swing Components Supporting Action for more details, and you can find more information in How to Use Actions, a section in The Java Tutorial.

For further documentation and for examples, see How to Use Menus in The Java Tutorial.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JPopupMenu, JMenu, JCheckBoxMenuItem, JRadioButtonMenuItem

Nested Class Summary
protected  class JMenuItem.AccessibleJMenuItem
This class implements accessibility support for the JMenuItem class.
Nested classes/interfaces inherited from class javax.swing.AbstractButton
AbstractButton.AccessibleAbstractButton, AbstractButton.ButtonChangeListener
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.AbstractButton
actionListener, BORDER_PAINTED_CHANGED_PROPERTY, changeEvent, changeListener, CONTENT_AREA_FILLED_CHANGED_PROPERTY, DISABLED_ICON_CHANGED_PROPERTY, DISABLED_SELECTED_ICON_CHANGED_PROPERTY, FOCUS_PAINTED_CHANGED_PROPERTY, HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY, HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY, ICON_CHANGED_PROPERTY, itemListener, MARGIN_CHANGED_PROPERTY, MNEMONIC_CHANGED_PROPERTY, model, MODEL_CHANGED_PROPERTY, PRESSED_ICON_CHANGED_PROPERTY, ROLLOVER_ENABLED_CHANGED_PROPERTY, ROLLOVER_ICON_CHANGED_PROPERTY, ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY, SELECTED_ICON_CHANGED_PROPERTY, TEXT_CHANGED_PROPERTY, VERTICAL_ALIGNMENT_CHANGED_PROPERTY, VERTICAL_TEXT_POSITION_CHANGED_PROPERTY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JMenuItem()
Creates a JMenuItem with no set text or icon.
JMenuItem(Action a)
Creates a menu item whose properties are taken from the specified Action.
JMenuItem(Icon icon)
Creates a JMenuItem with the specified icon.
JMenuItem(String text)
Creates a JMenuItem with the specified text.
JMenuItem(String text, Icon icon)
Creates a JMenuItem with the specified text and icon.
JMenuItem(String text, int mnemonic)
Creates a JMenuItem with the specified text and keyboard mnemonic.
Method Summary
protected  void actionPropertyChanged(Action action, String propertyName)
Updates the button's state in response to property changes in the associated action.
 void addMenuDragMouseListener(MenuDragMouseListener l)
Adds a MenuDragMouseListener to the menu item.
 void addMenuKeyListener(MenuKeyListener l)
Adds a MenuKeyListener to the menu item.
protected  void configurePropertiesFromAction(Action a)
Sets the properties on this button to match those in the specified Action.
protected  void fireMenuDragMouseDragged(MenuDragMouseEvent event)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireMenuDragMouseEntered(MenuDragMouseEvent event)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireMenuDragMouseExited(MenuDragMouseEvent event)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireMenuDragMouseReleased(MenuDragMouseEvent event)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireMenuKeyPressed(MenuKeyEvent event)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireMenuKeyReleased(MenuKeyEvent event)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireMenuKeyTyped(MenuKeyEvent event)
Notifies all listeners that have registered interest for notification on this event type.
 KeyStroke getAccelerator()
Returns the KeyStroke which serves as an accelerator for the menu item.
 AccessibleContext getAccessibleContext()
Returns the AccessibleContext associated with this JMenuItem.
 Component getComponent()
Returns the java.awt.Component used to paint this object.
 MenuDragMouseListener[] getMenuDragMouseListeners()
Returns an array of all the MenuDragMouseListeners added to this JMenuItem with addMenuDragMouseListener().
 MenuKeyListener[] getMenuKeyListeners()
Returns an array of all the MenuKeyListeners added to this JMenuItem with addMenuKeyListener().
 MenuElement[] getSubElements()
This method returns an array containing the sub-menu components for this menu component.
 String getUIClassID()
Returns the suffix used to construct the name of the L&F class used to render this component.
protected  void init(String text, Icon icon)
Initializes the menu item with the specified text and icon.
 boolean isArmed()
Returns whether the menu item is "armed".
 void menuSelectionChanged(boolean isIncluded)
Called by the MenuSelectionManager when the MenuElement is selected or unselected.
protected  String paramString()
Returns a string representation of this JMenuItem.
 void processKeyEvent(KeyEvent e, MenuElement[] path, MenuSelectionManager manager)
Processes a key event forwarded from the MenuSelectionManager and changes the menu selection, if necessary, by using MenuSelectionManager's API.
 void processMenuDragMouseEvent(MenuDragMouseEvent e)
Handles mouse drag in a menu.
 void processMenuKeyEvent(MenuKeyEvent e)
Handles a keystroke in a menu.
 void processMouseEvent(MouseEvent e, MenuElement[] path, MenuSelectionManager manager)
Processes a mouse event forwarded from the MenuSelectionManager and changes the menu selection, if necessary, by using the MenuSelectionManager's API.
 void removeMenuDragMouseListener(MenuDragMouseListener l)
Removes a MenuDragMouseListener from the menu item.
 void removeMenuKeyListener(MenuKeyListener l)
Removes a MenuKeyListener from the menu item.
 void setAccelerator(KeyStroke keyStroke)
Sets the key combination which invokes the menu item's action listeners without navigating the menu hierarchy.
 void setArmed(boolean b)
Identifies the menu item as "armed".
 void setEnabled(boolean b)
Enables or disables the menu item.
 void setModel(ButtonModel newModel)
Sets the model that this button represents.
 void setUI(MenuItemUI ui)
Sets the look and feel object that renders this component.
 void updateUI()
Resets the UI property with a value from the current look and feel.
Methods inherited from class javax.swing.AbstractButton
addActionListener, addChangeListener, addImpl, addItemListener, checkHorizontalKey, checkVerticalKey, createActionListener, createActionPropertyChangeListener, createChangeListener, createItemListener, doClick, doClick, fireActionPerformed, fireItemStateChanged, fireStateChanged, getAction, getActionCommand, getActionListeners, getChangeListeners, getDisabledIcon, getDisabledSelectedIcon, getDisplayedMnemonicIndex, getHideActionText, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getItemListeners, getLabel, getMargin, getMnemonic, getModel, getMultiClickThreshhold, getPressedIcon, getRolloverIcon, getRolloverSelectedIcon, getSelectedIcon, getSelectedObjects, getText, getUI, getVerticalAlignment, getVerticalTextPosition, imageUpdate, isBorderPainted, isContentAreaFilled, isFocusPainted, isRolloverEnabled, isSelected, paintBorder, removeActionListener, removeChangeListener, removeItemListener, removeNotify, setAction, setActionCommand, setBorderPainted, setContentAreaFilled, setDisabledIcon, setDisabledSelectedIcon, setDisplayedMnemonicIndex, setFocusPainted, setHideActionText, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabel, setLayout, setMargin, setMnemonic, setMnemonic, setMultiClickThreshhold, setPressedIcon, setRolloverEnabled, setRolloverIcon, setRolloverSelectedIcon, setSelected, setSelectedIcon, setText, setUI, setVerticalAlignment, setVerticalTextPosition
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JMenuItem

public JMenuItem()
Creates a JMenuItem with no set text or icon.

JMenuItem

public JMenuItem(Icon icon)
Creates a JMenuItem with the specified icon.

Parameters:
icon - the icon of the JMenuItem

JMenuItem

public JMenuItem(String text)
Creates a JMenuItem with the specified text.

Parameters:
text - the text of the JMenuItem

JMenuItem

public JMenuItem(Action a)
Creates a menu item whose properties are taken from the specified Action.

Parameters:
a - the action of the JMenuItem
Since:
1.3

JMenuItem

public JMenuItem(String text,
                 Icon icon)
Creates a JMenuItem with the specified text and icon.

Parameters:
text - the text of the JMenuItem
icon - the icon of the JMenuItem

JMenuItem

public JMenuItem(String text,
                 int mnemonic)
Creates a JMenuItem with the specified text and keyboard mnemonic.

Parameters:
text - the text of the JMenuItem
mnemonic - the keyboard mnemonic for the JMenuItem
Method Detail

setModel

public void setModel(ButtonModel newModel)
Sets the model that this button represents.

Overrides:
setModel in class AbstractButton
Parameters:
newModel - the new ButtonModel
See Also:
AbstractButton.getModel()

init

protected void init(String text,
                    Icon icon)
Initializes the menu item with the specified text and icon.

Overrides:
init in class AbstractButton
Parameters:
text - the text of the JMenuItem
icon - the icon of the JMenuItem

setUI

public void setUI(MenuItemUI ui)
Sets the look and feel object that renders this component.

Parameters:
ui - the JMenuItemUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Resets the UI property with a value from the current look and feel.

Overrides:
updateUI in class AbstractButton
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the suffix used to construct the name of the L&F class used to render this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "MenuItemUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

setArmed

public void setArmed(boolean b)
Identifies the menu item as "armed". If the mouse button is released while it is over this item, the menu's action event will fire. If the mouse button is released elsewhere, the event will not fire and the menu item will be disarmed.

Parameters:
b - true to arm the menu item so it can be selected

isArmed

public boolean isArmed()
Returns whether the menu item is "armed".

Returns:
true if the menu item is armed, and it can be selected
See Also:
setArmed(boolean)

setEnabled

public void setEnabled(boolean b)
Enables or disables the menu item.

Overrides:
setEnabled in class AbstractButton
Parameters:
b - true to enable the item
See Also:
Component.isEnabled(), Component.isLightweight()

setAccelerator

public void setAccelerator(KeyStroke keyStroke)
Sets the key combination which invokes the menu item's action listeners without navigating the menu hierarchy. It is the UI's responsibility to install the correct action. Note that when the keyboard accelerator is typed, it will work whether or not the menu is currently displayed.

Parameters:
keyStroke - the KeyStroke which will serve as an accelerator

getAccelerator

public KeyStroke getAccelerator()
Returns the KeyStroke which serves as an accelerator for the menu item.

Returns:
a KeyStroke object identifying the accelerator key

configurePropertiesFromAction

protected void configurePropertiesFromAction(Action a)
Sets the properties on this button to match those in the specified Action. Refer to Swing Components Supporting Action for more details as to which properties this sets.

Overrides:
configurePropertiesFromAction in class AbstractButton
Parameters:
a - the Action from which to get the properties, or null
Since:
1.3
See Also:
Action, AbstractButton.setAction(javax.swing.Action)

actionPropertyChanged

protected void actionPropertyChanged(Action action,
                                     String propertyName)
Updates the button's state in response to property changes in the associated action. This method is invoked from the PropertyChangeListener returned from createActionPropertyChangeListener. Subclasses do not normally need to invoke this. Subclasses that support additional Action properties should override this and configurePropertiesFromAction.

Refer to the table at Swing Components Supporting Action for a list of the properties this method sets.

Overrides:
actionPropertyChanged in class AbstractButton
Parameters:
action - the Action associated with this button
propertyName - the name of the property that changed
Since:
1.6
See Also:
Action, AbstractButton.configurePropertiesFromAction(javax.swing.Action)

processMouseEvent

public void processMouseEvent(MouseEvent e,
                              MenuElement[] path,
                              MenuSelectionManager manager)
Processes a mouse event forwarded from the MenuSelectionManager and changes the menu selection, if necessary, by using the MenuSelectionManager's API.

Note: you do not have to forward the event to sub-components. This is done automatically by the MenuSelectionManager.

Specified by:
processMouseEvent in interface MenuElement
Parameters:
e - a MouseEvent
path - the MenuElement path array
manager - the MenuSelectionManager

processKeyEvent

public void processKeyEvent(KeyEvent e,
                            MenuElement[] path,
                            MenuSelectionManager manager)
Processes a key event forwarded from the MenuSelectionManager and changes the menu selection, if necessary, by using MenuSelectionManager's API.

Note: you do not have to forward the event to sub-components. This is done automatically by the MenuSelectionManager.

Specified by:
processKeyEvent in interface MenuElement
Parameters:
e - a KeyEvent
path - the MenuElement path array
manager - the MenuSelectionManager

processMenuDragMouseEvent

public void processMenuDragMouseEvent(MenuDragMouseEvent e)
Handles mouse drag in a menu.

Parameters:
e - a MenuDragMouseEvent object

processMenuKeyEvent

public void processMenuKeyEvent(MenuKeyEvent e)
Handles a keystroke in a menu.

Parameters:
e - a MenuKeyEvent object

fireMenuDragMouseEntered

protected void fireMenuDragMouseEntered(MenuDragMouseEvent event)
Notifies all listeners that have registered interest for notification on this event type.

Parameters:
event - a MenuMouseDragEvent
See Also:
EventListenerList

fireMenuDragMouseExited

protected void fireMenuDragMouseExited(MenuDragMouseEvent event)
Notifies all listeners that have registered interest for notification on this event type.

Parameters:
event - a MenuDragMouseEvent
See Also:
EventListenerList

fireMenuDragMouseDragged

protected void fireMenuDragMouseDragged(MenuDragMouseEvent event)
Notifies all listeners that have registered interest for notification on this event type.

Parameters:
event - a MenuDragMouseEvent
See Also:
EventListenerList

fireMenuDragMouseReleased

protected void fireMenuDragMouseReleased(MenuDragMouseEvent event)
Notifies all listeners that have registered interest for notification on this event type.

Parameters:
event - a MenuDragMouseEvent
See Also:
EventListenerList

fireMenuKeyPressed

protected void fireMenuKeyPressed(MenuKeyEvent event)
Notifies all listeners that have registered interest for notification on this event type.

Parameters:
event - a MenuKeyEvent
See Also:
EventListenerList

fireMenuKeyReleased

protected void fireMenuKeyReleased(MenuKeyEvent event)
Notifies all listeners that have registered interest for notification on this event type.

Parameters:
event - a MenuKeyEvent
See Also:
EventListenerList

fireMenuKeyTyped

protected void fireMenuKeyTyped(MenuKeyEvent event)
Notifies all listeners that have registered interest for notification on this event type.

Parameters:
event - a MenuKeyEvent
See Also:
EventListenerList

menuSelectionChanged

public void menuSelectionChanged(boolean isIncluded)
Called by the MenuSelectionManager when the MenuElement is selected or unselected.

Specified by:
menuSelectionChanged in interface MenuElement
Parameters:
isIncluded - true if this menu item is on the part of the menu path that changed, false if this menu is part of the a menu path that changed, but this particular part of that path is still the same
See Also:
MenuSelectionManager.setSelectedPath(MenuElement[])

getSubElements

public MenuElement[] getSubElements()
This method returns an array containing the sub-menu components for this menu component.

Specified by:
getSubElements in interface MenuElement
Returns:
an array of MenuElements

getComponent

public Component getComponent()
Returns the java.awt.Component used to paint this object. The returned component will be used to convert events and detect if an event is inside a menu component.

Specified by:
getComponent in interface MenuElement
Returns:
the Component that paints this menu item

addMenuDragMouseListener

public void addMenuDragMouseListener(MenuDragMouseListener l)
Adds a MenuDragMouseListener to the menu item.

Parameters:
l - the MenuDragMouseListener to be added

removeMenuDragMouseListener

public void removeMenuDragMouseListener(MenuDragMouseListener l)
Removes a MenuDragMouseListener from the menu item.

Parameters:
l - the MenuDragMouseListener to be removed

getMenuDragMouseListeners

public MenuDragMouseListener[] getMenuDragMouseListeners()
Returns an array of all the MenuDragMouseListeners added to this JMenuItem with addMenuDragMouseListener().

Returns:
all of the MenuDragMouseListeners added or an empty array if no listeners have been added
Since:
1.4

addMenuKeyListener

public void addMenuKeyListener(MenuKeyListener l)
Adds a MenuKeyListener to the menu item.

Parameters:
l - the MenuKeyListener to be added

removeMenuKeyListener

public void removeMenuKeyListener(MenuKeyListener l)
Removes a MenuKeyListener from the menu item.

Parameters:
l - the MenuKeyListener to be removed

getMenuKeyListeners

public MenuKeyListener[] getMenuKeyListeners()
Returns an array of all the MenuKeyListeners added to this JMenuItem with addMenuKeyListener().

Returns:
all of the MenuKeyListeners added or an empty array if no listeners have been added
Since:
1.4

paramString

protected String paramString()
Returns a string representation of this JMenuItem. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class AbstractButton
Returns:
a string representation of this JMenuItem

getAccessibleContext

public AccessibleContext getAccessibleContext()
Returns the AccessibleContext associated with this JMenuItem. For JMenuItems, the AccessibleContext takes the form of an AccessibleJMenuItem. A new AccessibleJMenuItme instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJMenuItem that serves as the AccessibleContext of this JMenuItem
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JMenuItem.AccessibleJMenuItem

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JMenuItem.AccessibleJMenuItem

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.AbstractButton.AccessibleAbstractButton
                        extended by  javax.swing.JMenuItem.AccessibleJMenuItem
All Implemented Interfaces:
Serializable, EventListener, AccessibleAction, AccessibleComponent, AccessibleExtendedComponent, AccessibleText, AccessibleValue, ChangeListener
Direct Known Subclasses:
JCheckBoxMenuItem.AccessibleJCheckBoxMenuItem, JMenu.AccessibleJMenu, JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem
Enclosing class:
JMenuItem
protected class JMenuItem.AccessibleJMenuItem
extends AbstractButton.AccessibleAbstractButton
implements ChangeListener

This class implements accessibility support for the JMenuItem class. It provides an implementation of the Java Accessibility API appropriate to menu item user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Method Summary
AccessibleRole | getAccessibleRole() Get the role of this object.
void | stateChanged(ChangeEvent e) Supports the change listener interface and fires property changes.
Methods inherited from class javax.swing.AbstractButton.AccessibleAbstractButton
doAccessibleAction, getAccessibleAction, getAccessibleActionCount, getAccessibleActionDescription, getAccessibleIcon, getAccessibleKeyBinding, getAccessibleName, getAccessibleRelationSet, getAccessibleStateSet, getAccessibleText, getAccessibleValue, getAfterIndex, getAtIndex, getBeforeIndex, getCaretPosition, getCharacterAttribute, getCharacterBounds, getCharCount, getCurrentAccessibleValue, getIndexAtPoint, getMaximumAccessibleValue, getMinimumAccessibleValue, getSelectedText, getSelectionEnd, getSelectionStart, getTitledBorderText, getToolTipText, setCurrentAccessibleValue
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getBorderTitle, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleEditableText, getAccessibleSelection, getAccessibleTable, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

stateChanged

public void stateChanged(ChangeEvent e)
Supports the change listener interface and fires property changes.

Specified by:
stateChanged in interface ChangeListener
Parameters:
e - a ChangeEvent object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JOptionPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JOptionPane

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JOptionPane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public class JOptionPane
extends JComponent
implements Accessible

JOptionPane makes it easy to pop up a standard dialog box that prompts users for a value or informs them of something. For information about using JOptionPane, see How to Make Dialogs, a section in The Java Tutorial.

While the JOptionPane class may appear complex because of the large number of methods, almost all uses of this class are one-line calls to one of the static showXxxDialog methods shown below:

Method Name | Description
showConfirmDialog | Asks a confirming question, like yes/no/cancel.
showInputDialog | Prompt for some input.
showMessageDialog | Tell the user about something that has happened.
showOptionDialog | The Grand Unification of the above three.
Each of these methods also comes in a showInternalXXX flavor, which uses an internal frame to hold the dialog box (see JInternalFrame). Multiple convenience methods have also been defined -- overloaded versions of the basic methods that use different parameter lists.

All dialogs are modal. Each showXxxDialog method blocks the caller until the user's interaction is complete.

icon message
input value
option buttons
The basic appearance of one of these dialog boxes is generally similar to the picture at the right, although the various look-and-feels are ultimately responsible for the final result. In particular, the look-and-feels will adjust the layout to accommodate the option pane's ComponentOrientation property.

Parameters:
The parameters to these methods follow consistent patterns:

parentComponent
Defines the Component that is to be the parent of this dialog box. It is used in two ways: the Frame that contains it is used as the Frame parent for the dialog box, and its screen coordinates are used in the placement of the dialog box. In general, the dialog box is placed just below the component. This parameter may be null, in which case a default Frame is used as the parent, and the dialog will be centered on the screen (depending on the L&F).
message
A descriptive message to be placed in the dialog box. In the most common usage, message is just a String or String constant. However, the type of this parameter is actually Object. Its interpretation depends on its type:
Object[]
An array of objects is interpreted as a series of messages (one per object) arranged in a vertical stack. The interpretation is recursive -- each object in the array is interpreted according to its type.
Component
The Component is displayed in the dialog.
Icon
The Icon is wrapped in a JLabel and displayed in the dialog.
others
The object is converted to a String by calling its toString method. The result is wrapped in a JLabel and displayed.
messageType
Defines the style of the message. The Look and Feel manager may lay out the dialog differently depending on this value, and will often provide a default icon. The possible values are:
  • ERROR_MESSAGE
  • INFORMATION_MESSAGE
  • WARNING_MESSAGE
  • QUESTION_MESSAGE
  • PLAIN_MESSAGE
optionType
Defines the set of option buttons that appear at the bottom of the dialog box:
  • DEFAULT_OPTION
  • YES_NO_OPTION
  • YES_NO_CANCEL_OPTION
  • OK_CANCEL_OPTION
You aren't limited to this set of option buttons. You can provide any buttons you want using the options parameter.
options
A more detailed description of the set of option buttons that will appear at the bottom of the dialog box. The usual value for the options parameter is an array of Strings. But the parameter type is an array of Objects. A button is created for each object depending on its type:
Component
The component is added to the button row directly.
Icon
A JButton is created with this as its label.
other
The Object is converted to a string using its toString method and the result is used to label a JButton.
icon
A decorative icon to be placed in the dialog box. A default value for this is determined by the messageType parameter.
title
The title for the dialog box.
initialValue
The default selection (input value).

When the selection is changed, setValue is invoked, which generates a PropertyChangeEvent.

If a JOptionPane has configured to all input setWantsInput the bound property JOptionPane.INPUT_VALUE_PROPERTY can also be listened to, to determine when the user has input or selected a value.

When one of the showXxxDialog methods returns an integer, the possible values are:

  • YES_OPTION
  • NO_OPTION
  • CANCEL_OPTION
  • OK_OPTION
  • CLOSED_OPTION
Examples:
Show an error dialog that displays the message, 'alert':
JOptionPane.showMessageDialog(null, "alert", "alert", JOptionPane.ERROR_MESSAGE);

Show an internal information dialog with the message, 'information':
JOptionPane.showInternalMessageDialog(frame, "information",
      "information", JOptionPane.INFORMATION_MESSAGE);

Show an information panel with the options yes/no and message 'choose one':
JOptionPane.showConfirmDialog(null,
      "choose one", "choose one", JOptionPane.YES_NO_OPTION);

Show an internal information dialog with the options yes/no/cancel and message 'please choose one' and title information:
JOptionPane.showInternalConfirmDialog(frame,
      "please choose one", "information",
      JOptionPane.YES_NO_CANCEL_OPTION, JOptionPane.INFORMATION_MESSAGE);

Show a warning dialog with the options OK, CANCEL, title 'Warning', and message 'Click OK to continue':
Object[] options = { "OK", "CANCEL" };
JOptionPane.showOptionDialog(null, "Click OK to continue", "Warning",
      JOptionPane.DEFAULT_OPTION, JOptionPane.WARNING_MESSAGE,
      null, options, options[0]);

Show a dialog asking the user to type in a String:
String inputValue = JOptionPane.showInputDialog("Please input a value");

Show a dialog asking the user to select a String:
Object[] possibleValues = { "First", "Second", "Third" };
Object selectedValue = JOptionPane.showInputDialog(null,
      "Choose one", "Input",
      JOptionPane.INFORMATION_MESSAGE, null,
      possibleValues, possibleValues[0]);

Direct Use:
To create and use an JOptionPane directly, the standard pattern is roughly as follows:
     JOptionPane pane = new JOptionPane(arguments);
     pane.set.Xxxx(...); // Configure
     JDialog dialog = pane.createDialog(parentComponent, title);
     dialog.show();
     Object selectedValue = pane.getValue();
     if(selectedValue == null)
       return CLOSED_OPTION;
     //If there is not an array of option buttons:
     if(options == null) {
       if(selectedValue instanceof Integer)
          return ((Integer)selectedValue).intValue();
       return CLOSED_OPTION;
     }
     //If there is an array of option buttons:
     for(int counter = 0, maxCounter = options.length;
        counter < maxCounter; counter++) {
        if(options[counter].equals(selectedValue))
        return counter;
     }
     return CLOSED_OPTION;

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JInternalFrame

Nested Class Summary
protected  class JOptionPane.AccessibleJOptionPane
This class implements accessibility support for the JOptionPane class.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
static int | CANCEL_OPTION Return value from class method if CANCEL is chosen.
static int | CLOSED_OPTION Return value from class method if user closes window without selecting anything, more than likely this should be treated as either a CANCEL_OPTION or NO_OPTION.
static int | DEFAULT_OPTION Type meaning Look and Feel should not supply any options -- only use the options from the JOptionPane.
static int | ERROR_MESSAGE Used for error messages.
protected Icon | icon Icon used in pane.
static String | ICON_PROPERTY Bound property name for icon.
static int | INFORMATION_MESSAGE Used for information messages.
static String | INITIAL_SELECTION_VALUE_PROPERTY Bound property name for initialSelectionValue.
static String | INITIAL_VALUE_PROPERTY Bound property name for initialValue.
protected Object | initialSelectionValue Initial value to select in selectionValues.
protected Object | initialValue Value that should be initially selected in options.
static String | INPUT_VALUE_PROPERTY Bound property name for inputValue.
protected Object | inputValue Value the user has input.
protected Object | message Message to display.
static String | MESSAGE_PROPERTY Bound property name for message.
static String | MESSAGE_TYPE_PROPERTY Bound property name for type.
protected int | messageType Message type.
static int | NO_OPTION Return value from class method if NO is chosen.
static int | OK_CANCEL_OPTION Type used for showConfirmDialog.
static int | OK_OPTION Return value form class method if OK is chosen.
static String | OPTION_TYPE_PROPERTY Bound property name for optionType.
protected Object[] | options Options to display to the user.
static String | OPTIONS_PROPERTY Bound property name for option.
protected int | optionType Option type, one of DEFAULT_OPTION, YES_NO_OPTION, YES_NO_CANCEL_OPTION or OK_CANCEL_OPTION.
static int | PLAIN_MESSAGE No icon is used.
static int | QUESTION_MESSAGE Used for questions.
static String | SELECTION_VALUES_PROPERTY Bound property name for selectionValues.
protected Object[] | selectionValues Array of values the user can choose from.
static Object | UNINITIALIZED_VALUE Indicates that the user has not yet selected a value.
protected Object | value Currently selected value, will be a valid option, or UNINITIALIZED_VALUE or null.
static String | VALUE_PROPERTY Bound property name for value.
static String | WANTS_INPUT_PROPERTY Bound property name for wantsInput.
protected boolean | wantsInput If true, a UI widget will be provided to the user to get input.
static int | WARNING_MESSAGE Used for warning messages.
static int | YES_NO_CANCEL_OPTION Type used for showConfirmDialog.
static int | YES_NO_OPTION Type used for showConfirmDialog.
static int | YES_OPTION Return value from class method if YES is chosen.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JOptionPane()
Creates a JOptionPane with a test message.
JOptionPane(Object message)
Creates a instance of JOptionPane to display a message using the plain-message message type and the default options delivered by the UI.
JOptionPane(Object message, int messageType)
Creates an instance of JOptionPane to display a message with the specified message type and the default options,
JOptionPane(Object message, int messageType, int optionType)
Creates an instance of JOptionPane to display a message with the specified message type and options.
JOptionPane(Object message, int messageType, int optionType, Icon icon)
Creates an instance of JOptionPane to display a message with the specified message type, options, and icon.
JOptionPane(Object message, int messageType, int optionType, Icon icon, Object[] options)
Creates an instance of JOptionPane to display a message with the specified message type, icon, and options.
JOptionPane(Object message, int messageType, int optionType, Icon icon, Object[] options, Object initialValue)
Creates an instance of JOptionPane to display a message with the specified message type, icon, and options, with the initially-selected option specified.
Method Summary
JDialog | createDialog(Component parentComponent, String title) Creates and returns a new JDialog wrapping this centered on the parentComponent in the parentComponent's frame.
JDialog | createDialog(String title) Creates and returns a new parentless JDialog with the specified title.
JInternalFrame | createInternalFrame(Component parentComponent, String title) Creates and returns an instance of JInternalFrame.
AccessibleContext | getAccessibleContext() Returns the AccessibleContext associated with this JOptionPane.
static JDesktopPane | getDesktopPaneForComponent(Component parentComponent) Returns the specified component's desktop pane.
static Frame | getFrameForComponent(Component parentComponent) Returns the specified component's Frame.
Icon | getIcon() Returns the icon this pane displays.
Object | getInitialSelectionValue() Returns the input value that is displayed as initially selected to the user.
Object | getInitialValue() Returns the initial value.
Object | getInputValue() Returns the value the user has input, if wantsInput is true.
int | getMaxCharactersPerLineCount() Returns the maximum number of characters to place on a line in a message.
Object | getMessage() Returns the message-object this pane displays.
int | getMessageType() Returns the message type.
Object[] | getOptions() Returns the choices the user can make.
int | getOptionType() Returns the type of options that are displayed.
static Frame | getRootFrame() Returns the Frame to use for the class methods in which a frame is not provided.
Object[] | getSelectionValues() Returns the input selection values.
OptionPaneUI | getUI() Returns the UI object which implements the L&F for this component.
String | getUIClassID() Returns the name of the UI class that implements the L&F for this component.
Object | getValue() Returns the value the user has selected.
boolean | getWantsInput() Returns the value of the wantsInput property.
protected String | paramString() Returns a string representation of this JOptionPane.
void | selectInitialValue() Requests that the initial value be selected, which will set focus to the initial value.
void | setIcon(Icon newIcon) Sets the icon to display.
void | setInitialSelectionValue(Object newValue) Sets the input value that is initially displayed as selected to the user.
void | setInitialValue(Object newInitialValue) Sets the initial value that is to be enabled -- the Component that has the focus when the pane is initially displayed.
void | setInputValue(Object newValue) Sets the input value that was selected or input by the user.
void | setMessage(Object newMessage) Sets the option pane's message-object.
void | setMessageType(int newType) Sets the option pane's message type.
void | setOptions(Object[] newOptions) Sets the options this pane displays.
void | setOptionType(int newType) Sets the options to display.
static void | setRootFrame(Frame newRootFrame) Sets the frame to use for class methods in which a frame is not provided.
void | setSelectionValues(Object[] newValues) Sets the input selection values for a pane that provides the user with a list of items to choose from.
void | setUI(OptionPaneUI ui) Sets the UI object which implements the L&F for this component.
void | setValue(Object newValue) Sets the value the user has chosen.
void | setWantsInput(boolean newValue) Sets the wantsInput property.
static int | showConfirmDialog(Component parentComponent, Object message) Brings up a dialog with the options Yes, No and Cancel; with the title, Select an Option.
static int | showConfirmDialog(Component parentComponent, Object message, String title, int optionType) Brings up a dialog where the number of choices is determined by the optionType parameter.
static int | showConfirmDialog(Component parentComponent, Object message, String title, int optionType, int messageType) Brings up a dialog where the number of choices is determined by the optionType parameter, where the messageType parameter determines the icon to display.
static int | showConfirmDialog(Component parentComponent, Object message, String title, int optionType, int messageType, Icon icon) Brings up a dialog with a specified icon, where the number of choices is determined by the optionType parameter.
static String | showInputDialog(Component parentComponent, Object message) Shows a question-message dialog requesting input from the user parented to parentComponent.
static String | showInputDialog(Component parentComponent, Object message, Object initialSelectionValue) Shows a question-message dialog requesting input from the user and parented to parentComponent.
static String | showInputDialog(Component parentComponent, Object message, String title, int messageType) Shows a dialog requesting input from the user parented to parentComponent with the dialog having the title title and message type messageType.
static Object | showInputDialog(Component parentComponent, Object message, String title, int messageType, Icon icon, Object[] selectionValues, Object initialSelectionValue) Prompts the user for input in a blocking dialog where the initial selection, possible selections, and all other options can be specified.
static String | showInputDialog(Object message) Shows a question-message dialog requesting input from the user.
static String | showInputDialog(Object message, Object initialSelectionValue) Shows a question-message dialog requesting input from the user, with the input value initialized to initialSelectionValue.
static int | showInternalConfirmDialog(Component parentComponent, Object message) Brings up an internal dialog panel with the options Yes, No and Cancel; with the title, Select an Option.
static int | showInternalConfirmDialog(Component parentComponent, Object message, String title, int optionType) Brings up a internal dialog panel where the number of choices is determined by the optionType parameter.
static int | showInternalConfirmDialog(Component parentComponent, Object message, String title, int optionType, int messageType) Brings up an internal dialog panel where the number of choices is determined by the optionType parameter, where the messageType parameter determines the icon to display.
static int | showInternalConfirmDialog(Component parentComponent, Object message, String title, int optionType, int messageType, Icon icon) Brings up an internal dialog panel with a specified icon, where the number of choices is determined by the optionType parameter.
static String | showInternalInputDialog(Component parentComponent, Object message) Shows an internal question-message dialog requesting input from the user parented to parentComponent.
static String | showInternalInputDialog(Component parentComponent, Object message, String title, int messageType) Shows an internal dialog requesting input from the user parented to parentComponent with the dialog having the title title and message type messageType.
static Object | showInternalInputDialog(Component parentComponent, Object message, String title, int messageType, Icon icon, Object[] selectionValues, Object initialSelectionValue) Prompts the user for input in a blocking internal dialog where the initial selection, possible selections, and all other options can be specified.
static void | showInternalMessageDialog(Component parentComponent, Object message) Brings up an internal confirmation dialog panel.
static void | showInternalMessageDialog(Component parentComponent, Object message, String title, int messageType) Brings up an internal dialog panel that displays a message using a default icon determined by the messageType parameter.
static void | showInternalMessageDialog(Component parentComponent, Object message, String title, int messageType, Icon icon) Brings up an internal dialog panel displaying a message, specifying all parameters.
static int | showInternalOptionDialog(Component parentComponent, Object message, String title, int optionType, int messageType, Icon icon, Object[] options, Object initialValue) Brings up an internal dialog panel with a specified icon, where the initial choice is determined by the initialValue parameter and the number of choices is determined by the optionType parameter.
static void | showMessageDialog(Component parentComponent, Object message) Brings up an information-message dialog titled "Message".
static void | showMessageDialog(Component parentComponent, Object message, String title, int messageType) Brings up a dialog that displays a message using a default icon determined by the messageType parameter.
static void | showMessageDialog(Component parentComponent, Object message, String title, int messageType, Icon icon) Brings up a dialog displaying a message, specifying all parameters.
static int | showOptionDialog(Component parentComponent, Object message, String title, int optionType, int messageType, Icon icon, Object[] options, Object initialValue) Brings up a dialog with a specified icon, where the initial choice is determined by the initialValue parameter and the number of choices is determined by the optionType parameter.
void | updateUI() Notification from the UIManager that the L&F has changed.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

UNINITIALIZED_VALUE

public static final Object UNINITIALIZED_VALUE
Indicates that the user has not yet selected a value.

DEFAULT_OPTION

public static final int DEFAULT_OPTION
Type meaning Look and Feel should not supply any options -- only use the options from the JOptionPane.

See Also:
Constant Field Values

YES_NO_OPTION

public static final int YES_NO_OPTION
Type used for showConfirmDialog.

See Also:
Constant Field Values

YES_NO_CANCEL_OPTION

public static final int YES_NO_CANCEL_OPTION
Type used for showConfirmDialog.

See Also:
Constant Field Values

OK_CANCEL_OPTION

public static final int OK_CANCEL_OPTION
Type used for showConfirmDialog.

See Also:
Constant Field Values

YES_OPTION

public static final int YES_OPTION
Return value from class method if YES is chosen.

See Also:
Constant Field Values

NO_OPTION

public static final int NO_OPTION
Return value from class method if NO is chosen.

See Also:
Constant Field Values

CANCEL_OPTION

public static final int CANCEL_OPTION
Return value from class method if CANCEL is chosen.

See Also:
Constant Field Values

OK_OPTION

public static final int OK_OPTION
Return value form class method if OK is chosen.

See Also:
Constant Field Values

CLOSED_OPTION

public static final int CLOSED_OPTION
Return value from class method if user closes window without selecting anything, more than likely this should be treated as either a CANCEL_OPTION or NO_OPTION.

See Also:
Constant Field Values

ERROR_MESSAGE

public static final int ERROR_MESSAGE
Used for error messages.

See Also:
Constant Field Values

INFORMATION_MESSAGE

public static final int INFORMATION_MESSAGE
Used for information messages.

See Also:
Constant Field Values

WARNING_MESSAGE

public static final int WARNING_MESSAGE
Used for warning messages.

See Also:
Constant Field Values

QUESTION_MESSAGE

public static final int QUESTION_MESSAGE
Used for questions.

See Also:
Constant Field Values

PLAIN_MESSAGE

public static final int PLAIN_MESSAGE
No icon is used.

See Also:
Constant Field Values

ICON_PROPERTY

public static final String ICON_PROPERTY
Bound property name for icon.

See Also:
Constant Field Values

MESSAGE_PROPERTY

public static final String MESSAGE_PROPERTY
Bound property name for message.

See Also:
Constant Field Values

VALUE_PROPERTY

public static final String VALUE_PROPERTY
Bound property name for value.

See Also:
Constant Field Values

OPTIONS_PROPERTY

public static final String OPTIONS_PROPERTY
Bound property name for option.

See Also:
Constant Field Values

INITIAL_VALUE_PROPERTY

public static final String INITIAL_VALUE_PROPERTY
Bound property name for initialValue.

See Also:
Constant Field Values

MESSAGE_TYPE_PROPERTY

public static final String MESSAGE_TYPE_PROPERTY
Bound property name for type.

See Also:
Constant Field Values

OPTION_TYPE_PROPERTY

public static final String OPTION_TYPE_PROPERTY
Bound property name for optionType.

See Also:
Constant Field Values

SELECTION_VALUES_PROPERTY

public static final String SELECTION_VALUES_PROPERTY
Bound property name for selectionValues.

See Also:
Constant Field Values

INITIAL_SELECTION_VALUE_PROPERTY

public static final String INITIAL_SELECTION_VALUE_PROPERTY
Bound property name for initialSelectionValue.

See Also:
Constant Field Values

INPUT_VALUE_PROPERTY

public static final String INPUT_VALUE_PROPERTY
Bound property name for inputValue.

See Also:
Constant Field Values

WANTS_INPUT_PROPERTY

public static final String WANTS_INPUT_PROPERTY
Bound property name for wantsInput.

See Also:
Constant Field Values

icon

protected transient Icon icon
Icon used in pane.

message

protected transient Object message
Message to display.

options

protected transient Object[] options
Options to display to the user.

initialValue

protected transient Object initialValue
Value that should be initially selected in options.

messageType

protected int messageType
Message type.

optionType

protected int optionType
Option type, one of DEFAULT_OPTION, YES_NO_OPTION, YES_NO_CANCEL_OPTION or OK_CANCEL_OPTION.

value

protected transient Object value
Currently selected value, will be a valid option, or UNINITIALIZED_VALUE or null.

selectionValues

protected transient Object[] selectionValues
Array of values the user can choose from. Look and feel will provide the UI component to choose this from.

inputValue

protected transient Object inputValue
Value the user has input.

initialSelectionValue

protected transient Object initialSelectionValue
Initial value to select in selectionValues.

wantsInput

protected boolean wantsInput
If true, a UI widget will be provided to the user to get input.

Constructor Detail

JOptionPane

public JOptionPane()
Creates a JOptionPane with a test message.

JOptionPane

public JOptionPane(Object message)
Creates a instance of JOptionPane to display a message using the plain-message message type and the default options delivered by the UI.

Parameters:
message - the Object to display

JOptionPane

public JOptionPane(Object message,
                   int messageType)
Creates an instance of JOptionPane to display a message with the specified message type and the default options,

Parameters:
message - the Object to display
messageType - the type of message to be displayed: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE

JOptionPane

public JOptionPane(Object message,
                   int messageType,
                   int optionType)
Creates an instance of JOptionPane to display a message with the specified message type and options.

Parameters:
message - the Object to display
messageType - the type of message to be displayed: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
optionType - the options to display in the pane: DEFAULT_OPTION, YES_NO_OPTION, YES_NO_CANCEL_OPTION, OK_CANCEL_OPTION

JOptionPane

public JOptionPane(Object message,
                   int messageType,
                   int optionType,
                   Icon icon)
Creates an instance of JOptionPane to display a message with the specified message type, options, and icon.

Parameters:
message - the Object to display
messageType - the type of message to be displayed: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
optionType - the options to display in the pane: DEFAULT_OPTION, YES_NO_OPTION, YES_NO_CANCEL_OPTION, OK_CANCEL_OPTION
icon - the Icon image to display

JOptionPane

public JOptionPane(Object message,
                   int messageType,
                   int optionType,
                   Icon icon,
                   Object[] options)
Creates an instance of JOptionPane to display a message with the specified message type, icon, and options. None of the options is initially selected.

The options objects should contain either instances of Components, (which are added directly) or Strings (which are wrapped in a JButton). If you provide Components, you must ensure that when the Component is clicked it messages setValue in the created JOptionPane.

Parameters:
message - the Object to display
messageType - the type of message to be displayed: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
optionType - the options to display in the pane: DEFAULT_OPTION, YES_NO_OPTION, YES_NO_CANCEL_OPTION, OK_CANCEL_OPTION
icon - the Icon image to display
options - the choices the user can select

JOptionPane

public JOptionPane(Object message,
                   int messageType,
                   int optionType,
                   Icon icon,
                   Object[] options,
                   Object initialValue)
Creates an instance of JOptionPane to display a message with the specified message type, icon, and options, with the initially-selected option specified.

Parameters:
message - the Object to display
messageType - the type of message to be displayed: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
optionType - the options to display in the pane: DEFAULT_OPTION, YES_NO_OPTION, YES_NO_CANCEL_OPTION, OK_CANCEL_OPTION
icon - the Icon image to display
options - the choices the user can select
initialValue - the choice that is initially selected; if null, then nothing will be initially selected; only meaningful if options is used
Method Detail

showInputDialog

public static String showInputDialog(Object message)
                              throws HeadlessException
Shows a question-message dialog requesting input from the user. The dialog uses the default frame, which usually means it is centered on the screen.

Parameters:
message - the Object to display
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless returns true
See Also:
GraphicsEnvironment.isHeadless()

showInputDialog

public static String showInputDialog(Object message,
                                     Object initialSelectionValue)
Shows a question-message dialog requesting input from the user, with the input value initialized to initialSelectionValue. The dialog uses the default frame, which usually means it is centered on the screen.

Parameters:
message - the Object to display
initialSelectionValue - the value used to initialize the input field
Since:
1.4

showInputDialog

public static String showInputDialog(Component parentComponent,
                                     Object message)
                              throws HeadlessException
Shows a question-message dialog requesting input from the user parented to parentComponent. The dialog is displayed on top of the Component's frame, and is usually positioned below the Component.

Parameters:
parentComponent - the parent Component for the dialog
message - the Object to display
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless returns true
See Also:
GraphicsEnvironment.isHeadless()

showInputDialog

public static String showInputDialog(Component parentComponent,
                                     Object message,
                                     Object initialSelectionValue)
Shows a question-message dialog requesting input from the user and parented to parentComponent. The input value will be initialized to initialSelectionValue. The dialog is displayed on top of the Component's frame, and is usually positioned below the Component.

Parameters:
parentComponent - the parent Component for the dialog
message - the Object to display
initialSelectionValue - the value used to initialize the input field
Since:
1.4

showInputDialog

public static String showInputDialog(Component parentComponent,
                                     Object message,
                                     String title,
                                     int messageType)
                              throws HeadlessException
Shows a dialog requesting input from the user parented to parentComponent with the dialog having the title title and message type messageType.

Parameters:
parentComponent - the parent Component for the dialog
message - the Object to display
title - the String to display in the dialog title bar
messageType - the type of message that is to be displayed: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless returns true
See Also:
GraphicsEnvironment.isHeadless()

showInputDialog

public static Object showInputDialog(Component parentComponent,
                                     Object message,
                                     String title,
                                     int messageType,
                                     Icon icon,
                                     Object[] selectionValues,
                                     Object initialSelectionValue)
                              throws HeadlessException
Prompts the user for input in a blocking dialog where the initial selection, possible selections, and all other options can be specified. The user will able to choose from selectionValues, where null implies the user can input whatever they wish, usually by means of a JTextField. initialSelectionValue is the initial value to prompt the user with. It is up to the UI to decide how best to represent the selectionValues, but usually a JComboBox, JList, or JTextField will be used.

Parameters:
parentComponent - the parent Component for the dialog
message - the Object to display
title - the String to display in the dialog title bar
messageType - the type of message to be displayed: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
icon - the Icon image to display
selectionValues - an array of Objects that gives the possible selections
initialSelectionValue - the value used to initialize the input field
Returns:
user's input, or null meaning the user canceled the input
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless returns true
See Also:
GraphicsEnvironment.isHeadless()

showMessageDialog

public static void showMessageDialog(Component parentComponent,
                                     Object message)
                              throws HeadlessException
Brings up an information-message dialog titled "Message".

Parameters:
parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used
message - the Object to display
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless returns true
See Also:
GraphicsEnvironment.isHeadless()

showMessageDialog

public static void showMessageDialog(Component parentComponent,
                                     Object message,
                                     String title,
                                     int messageType)
                              throws HeadlessException
Brings up a dialog that displays a message using a default icon determined by the messageType parameter.

Parameters:
parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used
message - the Object to display
title - the title string for the dialog
messageType - the type of message to be displayed: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless returns true
See Also:
GraphicsEnvironment.isHeadless()

showMessageDialog

public static void showMessageDialog(Component parentComponent,
                                     Object message,
                                     String title,
                                     int messageType,
                                     Icon icon)
                              throws HeadlessException
Brings up a dialog displaying a message, specifying all parameters.

Parameters:
parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used
message - the Object to display
title - the title string for the dialog
messageType - the type of message to be displayed: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
icon - an icon to display in the dialog that helps the user identify the kind of message that is being displayed
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless returns true
See Also:
GraphicsEnvironment.isHeadless()

showConfirmDialog

public static int showConfirmDialog(Component parentComponent,
                                    Object message)
                             throws HeadlessException
Brings up a dialog with the options Yes, No and Cancel; with the title, Select an Option.

Parameters:
parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used
message - the Object to display
Returns:
an integer indicating the option selected by the user
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless returns true
See Also:
GraphicsEnvironment.isHeadless()

showConfirmDialog

public static int showConfirmDialog(Component parentComponent,
                                    Object message,
                                    String title,
                                    int optionType)
                             throws HeadlessException
Brings up a dialog where the number of choices is determined by the optionType parameter.

Parameters:
parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used
message - the Object to display
title - the title string for the dialog
optionType - an int designating the options available on the dialog: YES_NO_OPTION, YES_NO_CANCEL_OPTION, or OK_CANCEL_OPTION
Returns:
an int indicating the option selected by the user
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless returns true
See Also:
GraphicsEnvironment.isHeadless()

showConfirmDialog

public static int showConfirmDialog(Component parentComponent,
                                    Object message,
                                    String title,
                                    int optionType,
                                    int messageType)
                             throws HeadlessException
Brings up a dialog where the number of choices is determined by the optionType parameter, where the messageType parameter determines the icon to display. The messageType parameter is primarily used to supply a default icon from the Look and Feel.

Parameters:
parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used.
message - the Object to display
title - the title string for the dialog
optionType - an integer designating the options available on the dialog: YES_NO_OPTION, YES_NO_CANCEL_OPTION, or OK_CANCEL_OPTION
messageType - an integer designating the kind of message this is; primarily used to determine the icon from the pluggable Look and Feel: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
Returns:
an integer indicating the option selected by the user
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless returns true
See Also:
GraphicsEnvironment.isHeadless()

showConfirmDialog

public static int showConfirmDialog(Component parentComponent,
                                    Object message,
                                    String title,
                                    int optionType,
                                    int messageType,
                                    Icon icon)
                             throws HeadlessException
Brings up a dialog with a specified icon, where the number of choices is determined by the optionType parameter. The messageType parameter is primarily used to supply a default icon from the look and feel.

Parameters:
parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used
message - the Object to display
title - the title string for the dialog
optionType - an int designating the options available on the dialog: YES_NO_OPTION, YES_NO_CANCEL_OPTION, or OK_CANCEL_OPTION
messageType - an int designating the kind of message this is, primarily used to determine the icon from the pluggable Look and Feel: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
icon - the icon to display in the dialog
Returns:
an int indicating the option selected by the user
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless returns true
See Also:
GraphicsEnvironment.isHeadless()

showOptionDialog

public static int showOptionDialog(Component parentComponent,
                                   Object message,
                                   String title,
                                   int optionType,
                                   int messageType,
                                   Icon icon,
                                   Object[] options,
                                   Object initialValue)
                            throws HeadlessException
Brings up a dialog with a specified icon, where the initial choice is determined by the initialValue parameter and the number of choices is determined by the optionType parameter.

If optionType is YES_NO_OPTION, or YES_NO_CANCEL_OPTION and the options parameter is null, then the options are supplied by the look and feel.

The messageType parameter is primarily used to supply a default icon from the look and feel.

Parameters:
parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used
message - the Object to display
title - the title string for the dialog
optionType - an integer designating the options available on the dialog: DEFAULT_OPTION, YES_NO_OPTION, YES_NO_CANCEL_OPTION, or OK_CANCEL_OPTION
messageType - an integer designating the kind of message this is, primarily used to determine the icon from the pluggable Look and Feel: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
icon - the icon to display in the dialog
options - an array of objects indicating the possible choices the user can make; if the objects are components, they are rendered properly; non-String objects are rendered using their toString methods; if this parameter is null, the options are determined by the Look and Feel
initialValue - the object that represents the default selection for the dialog; only meaningful if options is used; can be null
Returns:
an integer indicating the option chosen by the user, or CLOSED_OPTION if the user closed the dialog
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless returns true
See Also:
GraphicsEnvironment.isHeadless()

createDialog

public JDialog createDialog(Component parentComponent,
                            String title)
                     throws HeadlessException
Creates and returns a new JDialog wrapping this centered on the parentComponent in the parentComponent's frame. title is the title of the returned dialog. The returned JDialog will not be resizable by the user, however programs can invoke setResizable on the JDialog instance to change this property. The returned JDialog will be set up such that once it is closed, or the user clicks on one of the buttons, the optionpane's value property will be set accordingly and the dialog will be closed. Each time the dialog is made visible, it will reset the option pane's value property to JOptionPane.UNINITIALIZED_VALUE to ensure the user's subsequent action closes the dialog properly.

Parameters:
parentComponent - determines the frame in which the dialog is displayed; if the parentComponent has no Frame, a default Frame is used
title - the title string for the dialog
Returns:
a new JDialog containing this instance
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless returns true
See Also:
GraphicsEnvironment.isHeadless()

createDialog

public JDialog createDialog(String title)
                     throws HeadlessException
Creates and returns a new parentless JDialog with the specified title. The returned JDialog will not be resizable by the user, however programs can invoke setResizable on the JDialog instance to change this property. The returned JDialog will be set up such that once it is closed, or the user clicks on one of the buttons, the optionpane's value property will be set accordingly and the dialog will be closed. Each time the dialog is made visible, it will reset the option pane's value property to JOptionPane.UNINITIALIZED_VALUE to ensure the user's subsequent action closes the dialog properly.

Parameters:
title - the title string for the dialog
Returns:
a new JDialog containing this instance
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless returns true
Since:
1.6
See Also:
GraphicsEnvironment.isHeadless()

showInternalMessageDialog

public static void showInternalMessageDialog(Component parentComponent,
                                             Object message)
Brings up an internal confirmation dialog panel. The dialog is a information-message dialog titled "Message".

Parameters:
parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used
message - the object to display

showInternalMessageDialog

public static void showInternalMessageDialog(Component parentComponent,
                                             Object message,
                                             String title,
                                             int messageType)
Brings up an internal dialog panel that displays a message using a default icon determined by the messageType parameter.

Parameters:
parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used
message - the Object to display
title - the title string for the dialog
messageType - the type of message to be displayed: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE

showInternalMessageDialog

public static void showInternalMessageDialog(Component parentComponent,
                                             Object message,
                                             String title,
                                             int messageType,
                                             Icon icon)
Brings up an internal dialog panel displaying a message, specifying all parameters.

Parameters:
parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used
message - the Object to display
title - the title string for the dialog
messageType - the type of message to be displayed: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
icon - an icon to display in the dialog that helps the user identify the kind of message that is being displayed

showInternalConfirmDialog

public static int showInternalConfirmDialog(Component parentComponent,
                                            Object message)
Brings up an internal dialog panel with the options Yes, No and Cancel; with the title, Select an Option.

Parameters:
parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used
message - the Object to display
Returns:
an integer indicating the option selected by the user

showInternalConfirmDialog

public static int showInternalConfirmDialog(Component parentComponent,
                                            Object message,
                                            String title,
                                            int optionType)
Brings up a internal dialog panel where the number of choices is determined by the optionType parameter.

Parameters:
parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used
message - the object to display in the dialog; a Component object is rendered as a Component; a String object is rendered as a string; other objects are converted to a String using the toString method
title - the title string for the dialog
optionType - an integer designating the options available on the dialog: YES_NO_OPTION, or YES_NO_CANCEL_OPTION
Returns:
an integer indicating the option selected by the user

showInternalConfirmDialog

public static int showInternalConfirmDialog(Component parentComponent,
                                            Object message,
                                            String title,
                                            int optionType,
                                            int messageType)
Brings up an internal dialog panel where the number of choices is determined by the optionType parameter, where the messageType parameter determines the icon to display. The messageType parameter is primarily used to supply a default icon from the Look and Feel.

Parameters:
parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used
message - the object to display in the dialog; a Component object is rendered as a Component; a String object is rendered as a string; other objects are converted to a String using the toString method
title - the title string for the dialog
optionType - an integer designating the options available on the dialog: YES_NO_OPTION, or YES_NO_CANCEL_OPTION
messageType - an integer designating the kind of message this is, primarily used to determine the icon from the pluggable Look and Feel: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
Returns:
an integer indicating the option selected by the user

showInternalConfirmDialog

public static int showInternalConfirmDialog(Component parentComponent,
                                            Object message,
                                            String title,
                                            int optionType,
                                            int messageType,
                                            Icon icon)
Brings up an internal dialog panel with a specified icon, where the number of choices is determined by the optionType parameter. The messageType parameter is primarily used to supply a default icon from the look and feel.

Parameters:
parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used
message - the object to display in the dialog; a Component object is rendered as a Component; a String object is rendered as a string; other objects are converted to a String using the toString method
title - the title string for the dialog
optionType - an integer designating the options available on the dialog: YES_NO_OPTION, or YES_NO_CANCEL_OPTION.
messageType - an integer designating the kind of message this is, primarily used to determine the icon from the pluggable Look and Feel: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
icon - the icon to display in the dialog
Returns:
an integer indicating the option selected by the user

showInternalOptionDialog

public static int showInternalOptionDialog(Component parentComponent,
                                           Object message,
                                           String title,
                                           int optionType,
                                           int messageType,
                                           Icon icon,
                                           Object[] options,
                                           Object initialValue)
Brings up an internal dialog panel with a specified icon, where the initial choice is determined by the initialValue parameter and the number of choices is determined by the optionType parameter.

If optionType is YES_NO_OPTION, or YES_NO_CANCEL_OPTION and the options parameter is null, then the options are supplied by the Look and Feel.

The messageType parameter is primarily used to supply a default icon from the look and feel.

Parameters:
parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used
message - the object to display in the dialog; a Component object is rendered as a Component; a String object is rendered as a string. Other objects are converted to a String using the toString method
title - the title string for the dialog
optionType - an integer designating the options available on the dialog: YES_NO_OPTION, or YES_NO_CANCEL_OPTION
messageType - an integer designating the kind of message this is; primarily used to determine the icon from the pluggable Look and Feel: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
icon - the icon to display in the dialog
options - an array of objects indicating the possible choices the user can make; if the objects are components, they are rendered properly; non-String objects are rendered using their toString methods; if this parameter is null, the options are determined by the Look and Feel
initialValue - the object that represents the default selection for the dialog; only meaningful if options is used; can be null
Returns:
an integer indicating the option chosen by the user, or CLOSED_OPTION if the user closed the Dialog

showInternalInputDialog

public static String showInternalInputDialog(Component parentComponent,
                                             Object message)
Shows an internal question-message dialog requesting input from the user parented to parentComponent. The dialog is displayed in the Component's frame, and is usually positioned below the Component.

Parameters:
parentComponent - the parent Component for the dialog
message - the Object to display

showInternalInputDialog

public static String showInternalInputDialog(Component parentComponent,
                                             Object message,
                                             String title,
                                             int messageType)
Shows an internal dialog requesting input from the user parented to parentComponent with the dialog having the title title and message type messageType.

Parameters:
parentComponent - the parent Component for the dialog
message - the Object to display
title - the String to display in the dialog title bar
messageType - the type of message that is to be displayed: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE

showInternalInputDialog

public static Object showInternalInputDialog(Component parentComponent,
                                             Object message,
                                             String title,
                                             int messageType,
                                             Icon icon,
                                             Object[] selectionValues,
                                             Object initialSelectionValue)
Prompts the user for input in a blocking internal dialog where the initial selection, possible selections, and all other options can be specified. The user will able to choose from selectionValues, where null implies the user can input whatever they wish, usually by means of a JTextField. initialSelectionValue is the initial value to prompt the user with. It is up to the UI to decide how best to represent the selectionValues, but usually a JComboBox, JList, or JTextField will be used.

Parameters:
parentComponent - the parent Component for the dialog
message - the Object to display
title - the String to display in the dialog title bar
messageType - the type of message to be displayed: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
icon - the Icon image to display
selectionValues - an array of Objects that gives the possible selections
initialSelectionValue - the value used to initialize the input field
Returns:
user's input, or null meaning the user canceled the input

createInternalFrame

public JInternalFrame createInternalFrame(Component parentComponent,
                                          String title)
Creates and returns an instance of JInternalFrame. The internal frame is created with the specified title, and wrapping the JOptionPane. The returned JInternalFrame is added to the JDesktopPane ancestor of parentComponent, or components parent if one its ancestors isn't a JDesktopPane, or if parentComponent doesn't have a parent then a RuntimeException is thrown.

Parameters:
parentComponent - the parent Component for the internal frame
title - the String to display in the frame's title bar
Returns:
a JInternalFrame containing a JOptionPane
Throws:
RuntimeException - if parentComponent does not have a valid parent

getFrameForComponent

public static Frame getFrameForComponent(Component parentComponent)
                                  throws HeadlessException
Returns the specified component's Frame.

Parameters:
parentComponent - the Component to check for a Frame
Returns:
the Frame that contains the component, or getRootFrame if the component is null, or does not have a valid Frame parent
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless returns true
See Also:
getRootFrame(), GraphicsEnvironment.isHeadless()

getDesktopPaneForComponent

public static JDesktopPane getDesktopPaneForComponent(Component parentComponent)
Returns the specified component's desktop pane.

Parameters:
parentComponent - the Component to check for a desktop
Returns:
the JDesktopPane that contains the component, or null if the component is null or does not have an ancestor that is a JInternalFrame

setRootFrame

public static void setRootFrame(Frame newRootFrame)
Sets the frame to use for class methods in which a frame is not provided.

Note: It is recommended that rather than using this method you supply a valid parent.

Parameters:
newRootFrame - the default Frame to use

getRootFrame

public static Frame getRootFrame()
                          throws HeadlessException
Returns the Frame to use for the class methods in which a frame is not provided.

Returns:
the default Frame to use
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless returns true
See Also:
setRootFrame(java.awt.Frame), GraphicsEnvironment.isHeadless()

setUI

public void setUI(OptionPaneUI ui)
Sets the UI object which implements the L&F for this component.

Parameters:
ui - the OptionPaneUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

getUI

public OptionPaneUI getUI()
Returns the UI object which implements the L&F for this component.

Returns:
the OptionPaneUI object

updateUI

public void updateUI()
Notification from the UIManager that the L&F has changed. Replaces the current UI object with the latest version from the UIManager.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the UI class that implements the L&F for this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "OptionPaneUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

setMessage

public void setMessage(Object newMessage)
Sets the option pane's message-object.

Parameters:
newMessage - the Object to display
See Also:
getMessage()

getMessage

public Object getMessage()
Returns the message-object this pane displays.

Returns:
the Object that is displayed
See Also:
setMessage(java.lang.Object)

setIcon

public void setIcon(Icon newIcon)
Sets the icon to display. If non-null, the look and feel does not provide an icon.

Parameters:
newIcon - the Icon to display
See Also:
getIcon()

getIcon

public Icon getIcon()
Returns the icon this pane displays.

Returns:
the Icon that is displayed
See Also:
setIcon(javax.swing.Icon)

setValue

public void setValue(Object newValue)
Sets the value the user has chosen.

Parameters:
newValue - the chosen value
See Also:
getValue()

getValue

public Object getValue()
Returns the value the user has selected. UNINITIALIZED_VALUE implies the user has not yet made a choice, null means the user closed the window with out choosing anything. Otherwise the returned value will be one of the options defined in this object.

Returns:
the Object chosen by the user, UNINITIALIZED_VALUE if the user has not yet made a choice, or null if the user closed the window without making a choice
See Also:
setValue(java.lang.Object)

setOptions

public void setOptions(Object[] newOptions)
Sets the options this pane displays. If an element in newOptions is a Component it is added directly to the pane, otherwise a button is created for the element.

Parameters:
newOptions - an array of Objects that create the buttons the user can click on, or arbitrary Components to add to the pane
See Also:
getOptions()

getOptions

public Object[] getOptions()
Returns the choices the user can make.

Returns:
the array of Objects that give the user's choices
See Also:
setOptions(java.lang.Object[])

setInitialValue

public void setInitialValue(Object newInitialValue)
Sets the initial value that is to be enabled -- the Component that has the focus when the pane is initially displayed.

Parameters:
newInitialValue - the Object that gets the initial keyboard focus
See Also:
getInitialValue()

getInitialValue

public Object getInitialValue()
Returns the initial value.

Returns:
the Object that gets the initial keyboard focus
See Also:
setInitialValue(java.lang.Object)

setMessageType

public void setMessageType(int newType)
Sets the option pane's message type. The message type is used by the Look and Feel to determine the icon to display (if not supplied) as well as potentially how to lay out the parentComponent.

Parameters:
newType - an integer specifying the kind of message to display: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
Throws:
RuntimeException - if newType is not one of the legal values listed above
See Also:
getMessageType()

getMessageType

public int getMessageType()
Returns the message type.

Returns:
an integer specifying the message type
See Also:
setMessageType(int)

setOptionType

public void setOptionType(int newType)
Sets the options to display. The option type is used by the Look and Feel to determine what buttons to show (unless options are supplied).

Parameters:
newType - an integer specifying the options the L&F is to display: DEFAULT_OPTION, YES_NO_OPTION, YES_NO_CANCEL_OPTION, or OK_CANCEL_OPTION
Throws:
RuntimeException - if newType is not one of the legal values listed above
See Also:
getOptionType(), setOptions(java.lang.Object[])

getOptionType

public int getOptionType()
Returns the type of options that are displayed.

Returns:
an integer specifying the user-selectable options
See Also:
setOptionType(int)

setSelectionValues

public void setSelectionValues(Object[] newValues)
Sets the input selection values for a pane that provides the user with a list of items to choose from. (The UI provides a widget for choosing one of the values.) A null value implies the user can input whatever they wish, usually by means of a JTextField.

Sets wantsInput to true. Use setInitialSelectionValue to specify the initially-chosen value. After the pane as been enabled, inputValue is set to the value the user has selected.

Parameters:
newValues - an array of Objects the user to be displayed (usually in a list or combo-box) from which the user can make a selection
See Also:
setWantsInput(boolean), setInitialSelectionValue(java.lang.Object), getSelectionValues()

getSelectionValues

public Object[] getSelectionValues()
Returns the input selection values.

Returns:
the array of Objects the user can select
See Also:
setSelectionValues(java.lang.Object[])

setInitialSelectionValue

public void setInitialSelectionValue(Object newValue)
Sets the input value that is initially displayed as selected to the user. Only used if wantsInput is true.

Parameters:
newValue - the initially selected value
See Also:
setSelectionValues(java.lang.Object[]), getInitialSelectionValue()

getInitialSelectionValue

public Object getInitialSelectionValue()
Returns the input value that is displayed as initially selected to the user.

Returns:
the initially selected value
See Also:
setInitialSelectionValue(java.lang.Object), setSelectionValues(java.lang.Object[])

setInputValue

public void setInputValue(Object newValue)
Sets the input value that was selected or input by the user. Only used if wantsInput is true. Note that this method is invoked internally by the option pane (in response to user action) and should generally not be called by client programs. To set the input value initially displayed as selected to the user, use setInitialSelectionValue.

Parameters:
newValue - the Object used to set the value that the user specified (usually in a text field)
See Also:
setSelectionValues(java.lang.Object[]), setInitialSelectionValue(java.lang.Object), setWantsInput(boolean), getInputValue()

getInputValue

public Object getInputValue()
Returns the value the user has input, if wantsInput is true.

Returns:
the Object the user specified, if it was one of the objects, or a String if it was a value typed into a field
See Also:
setSelectionValues(java.lang.Object[]), setWantsInput(boolean), setInputValue(java.lang.Object)

getMaxCharactersPerLineCount

public int getMaxCharactersPerLineCount()
Returns the maximum number of characters to place on a line in a message. Default is to return Integer.MAX_VALUE. The value can be changed by overriding this method in a subclass.

Returns:
an integer giving the maximum number of characters on a line

setWantsInput

public void setWantsInput(boolean newValue)
Sets the wantsInput property. If newValue is true, an input component (such as a text field or combo box) whose parent is parentComponent is provided to allow the user to input a value. If getSelectionValues returns a non-null array, the input value is one of the objects in that array. Otherwise the input value is whatever the user inputs.

This is a bound property.

See Also:
setSelectionValues(java.lang.Object[]), setInputValue(java.lang.Object)

getWantsInput

public boolean getWantsInput()
Returns the value of the wantsInput property.

Returns:
true if an input component will be provided
See Also:
setWantsInput(boolean)

selectInitialValue

public void selectInitialValue()
Requests that the initial value be selected, which will set focus to the initial value. This method should be invoked after the window containing the option pane is made visible.

paramString

protected String paramString()
Returns a string representation of this JOptionPane. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JOptionPane

getAccessibleContext

public AccessibleContext getAccessibleContext()
Returns the AccessibleContext associated with this JOptionPane. For option panes, the AccessibleContext takes the form of an AccessibleJOptionPane. A new AccessibleJOptionPane instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJOptionPane that serves as the AccessibleContext of this AccessibleJOptionPane
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JOptionPane.AccessibleJOptionPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JOptionPane.AccessibleJOptionPane

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JOptionPane.AccessibleJOptionPane
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent
Enclosing class:
JOptionPane
protected class JOptionPane.AccessibleJOptionPane
extends JComponent.AccessibleJComponent

This class implements accessibility support for the JOptionPane class. It provides an implementation of the Java Accessibility API appropriate to option pane user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JOptionPane.AccessibleJOptionPane()
Method Summary
 AccessibleRole getAccessibleRole()
Get the role of this object.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JOptionPane.AccessibleJOptionPane

protected JOptionPane.AccessibleJOptionPane()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JPanel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JPanel

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JPanel
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
Direct Known Subclasses:
AbstractColorChooserPanel, JSpinner.DefaultEditor
public class JPanel
extends JComponent
implements Accessible

JPanel is a generic lightweight container. For examples and task-oriented documentation for JPanel, see How to Use Panels, a section in The Java Tutorial.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class JPanel.AccessibleJPanel
This class implements accessibility support for the JPanel class.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JPanel()
Creates a new JPanel with a double buffer and a flow layout.
JPanel(boolean isDoubleBuffered)
Creates a new JPanel with FlowLayout and the specified buffering strategy.
JPanel(LayoutManager layout)
Create a new buffered JPanel with the specified layout manager
JPanel(LayoutManager layout, boolean isDoubleBuffered)
Creates a new JPanel with the specified layout manager and buffering strategy.
Method Summary
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JPanel.
PanelUI | getUI() Returns the look and feel (L&F) object that renders this component.
String | getUIClassID() Returns a string that specifies the name of the L&F class that renders this component.
protected String | paramString() Returns a string representation of this JPanel.
void | setUI(PanelUI ui) Sets the look and feel (L&F) object that renders this component.
void | updateUI() Resets the UI property with a value from the current look and feel.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JPanel

public JPanel(LayoutManager layout,
              boolean isDoubleBuffered)
Creates a new JPanel with the specified layout manager and buffering strategy.

Parameters:
layout - the LayoutManager to use
isDoubleBuffered - a boolean, true for double-buffering, which uses additional memory space to achieve fast, flicker-free updates

JPanel

public JPanel(LayoutManager layout)
Create a new buffered JPanel with the specified layout manager

Parameters:
layout - the LayoutManager to use

JPanel

public JPanel(boolean isDoubleBuffered)
Creates a new JPanel with FlowLayout and the specified buffering strategy. If isDoubleBuffered is true, the JPanel will use a double buffer.

Parameters:
isDoubleBuffered - a boolean, true for double-buffering, which uses additional memory space to achieve fast, flicker-free updates

JPanel

public JPanel()
Creates a new JPanel with a double buffer and a flow layout.

Method Detail

updateUI

public void updateUI()
Resets the UI property with a value from the current look and feel.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUI

public PanelUI getUI()
Returns the look and feel (L&F) object that renders this component.

Returns:
the PanelUI object that renders this component
Since:
1.4

setUI

public void setUI(PanelUI ui)
Sets the look and feel (L&F) object that renders this component.

Parameters:
ui - the PanelUI L&F object
Since:
1.4
See Also:
UIDefaults.getUI(javax.swing.JComponent)

getUIClassID

public String getUIClassID()
Returns a string that specifies the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
"PanelUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

paramString

protected String paramString()
Returns a string representation of this JPanel. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JPanel.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JPanel. For JPanels, the AccessibleContext takes the form of an AccessibleJPanel. A new AccessibleJPanel instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJPanel that serves as the AccessibleContext of this JPanel
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JPanel.AccessibleJPanel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JPanel.AccessibleJPanel

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JPanel.AccessibleJPanel
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent
Enclosing class:
JPanel
protected class JPanel.AccessibleJPanel
extends JComponent.AccessibleJComponent

This class implements accessibility support for the JPanel class. It provides an implementation of the Java Accessibility API appropriate to panel user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JPanel.AccessibleJPanel()
Method Summary
 AccessibleRole getAccessibleRole()
Get the role of this object.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JPanel.AccessibleJPanel

protected JPanel.AccessibleJPanel()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JPasswordField

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JPasswordField

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.text.JTextComponent
                    extended by  javax.swing.JTextField
                        extended by  javax.swing.JPasswordField
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable, SwingConstants
public class JPasswordField
extends JTextField

JPasswordField is a lightweight component that allows the editing of a single line of text where the view indicates something was typed, but does not show the original characters. You can find further information and examples in How to Use Text Fields, a section in The Java Tutorial.

JPasswordField is intended to be source-compatible with java.awt.TextField used with echoChar set. It is provided separately to make it easier to safely change the UI for the JTextField without affecting password entries.

NOTE: By default, JPasswordField disables input methods; otherwise, input characters could be visible while they were composed using input methods. If an application needs the input methods support, please use the inherited method, enableInputMethods(true).

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class JPasswordField.AccessibleJPasswordField
This class implements accessibility support for the JPasswordField class.
Nested classes/interfaces inherited from class javax.swing.JTextField
JTextField.AccessibleJTextField
Nested classes/interfaces inherited from class javax.swing.text.JTextComponent
JTextComponent.AccessibleJTextComponent, JTextComponent.DropLocation, JTextComponent.KeyBinding
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JTextField
notifyAction
Fields inherited from class javax.swing.text.JTextComponent
DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JPasswordField()
Constructs a new JPasswordField, with a default document, null starting text string, and 0 column width.
JPasswordField(Document doc, String txt, int columns)
Constructs a new JPasswordField that uses the given text storage model and the given number of columns.
JPasswordField(int columns)
Constructs a new empty JPasswordField with the specified number of columns.
JPasswordField(String text)
Constructs a new JPasswordField initialized with the specified text.
JPasswordField(String text, int columns)
Constructs a new JPasswordField initialized with the specified text and columns.
Method Summary
void | copy() Invokes provideErrorFeedback on the current look and feel, which typically initiates an error beep.
void | cut() Invokes provideErrorFeedback on the current look and feel, which typically initiates an error beep.
boolean | echoCharIsSet() Returns true if this JPasswordField has a character set for echoing.
AccessibleContext | getAccessibleContext() Returns the AccessibleContext associated with this JPasswordField.
char | getEchoChar() Returns the character to be used for echoing.
char[] | getPassword() Returns the text contained in this TextComponent.
String | getText() Deprecated. As of Java 2 platform v1.2, replaced by getPassword.
String | getText(int offs, int len) Deprecated. As of Java 2 platform v1.2, replaced by getPassword.
String | getUIClassID() Returns the name of the L&F class that renders this component.
protected String | paramString() Returns a string representation of this JPasswordField.
void | setEchoChar(char c) Sets the echo character for this JPasswordField.
void | updateUI() Reloads the pluggable UI.
Methods inherited from class javax.swing.JTextField
actionPropertyChanged, addActionListener, configurePropertiesFromAction, createActionPropertyChangeListener, createDefaultModel, fireActionPerformed, getAction, getActionListeners, getActions, getColumns, getColumnWidth, getHorizontalAlignment, getHorizontalVisibility, getPreferredSize, getScrollOffset, isValidateRoot, postActionEvent, removeActionListener, scrollRectToVisible, setAction, setActionCommand, setColumns, setDocument, setFont, setHorizontalAlignment, setScrollOffset
Methods inherited from class javax.swing.text.JTextComponent
addCaretListener, addInputMethodListener, addKeymap, fireCaretUpdate, getCaret, getCaretColor, getCaretListeners, getCaretPosition, getDisabledTextColor, getDocument, getDragEnabled, getDropLocation, getDropMode, getFocusAccelerator, getHighlighter, getInputMethodRequests, getKeymap, getKeymap, getMargin, getNavigationFilter, getPreferredScrollableViewportSize, getPrintable, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getScrollableUnitIncrement, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getToolTipText, getUI, isEditable, loadKeymap, modelToView, moveCaretPosition, paste, print, print, print, processInputMethodEvent, read, removeCaretListener, removeKeymap, removeNotify, replaceSelection, select, selectAll, setCaret, setCaretColor, setCaretPosition, setComponentOrientation, setDisabledTextColor, setDragEnabled, setDropMode, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, setUI, viewToModel, write
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JPasswordField

public JPasswordField()
Constructs a new JPasswordField, with a default document, null starting text string, and 0 column width.

JPasswordField

public JPasswordField(String text)
Constructs a new JPasswordField initialized with the specified text. The document model is set to the default, and the number of columns to 0.

Parameters:
text - the text to be displayed, null if none

JPasswordField

public JPasswordField(int columns)
Constructs a new empty JPasswordField with the specified number of columns. A default model is created, and the initial string is set to null.

Parameters:
columns - the number of columns >= 0

JPasswordField

public JPasswordField(String text,
                      int columns)
Constructs a new JPasswordField initialized with the specified text and columns. The document model is set to the default.

Parameters:
text - the text to be displayed, null if none
columns - the number of columns >= 0

JPasswordField

public JPasswordField(Document doc,
                      String txt,
                      int columns)
Constructs a new JPasswordField that uses the given text storage model and the given number of columns. This is the constructor through which the other constructors feed. The echo character is set to '*', but may be changed by the current Look and Feel. If the document model is null, a default one will be created.

Parameters:
doc - the text storage to use
txt - the text to be displayed, null if none
columns - the number of columns to use to calculate the preferred width >= 0; if columns is set to zero, the preferred width will be whatever naturally results from the component implementation
Method Detail

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JTextField
Returns:
the string "PasswordFieldUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Reloads the pluggable UI. The key used to fetch the new interface is getUIClassID(). The type of the UI is TextUI. invalidate is called after setting the UI.

Overrides:
updateUI in class JTextComponent
Since:
1.6
See Also:
JComponent.setUI(javax.swing.plaf.ComponentUI),
UIManager.getLookAndFeel(),
UIManager.getUI(javax.swing.JComponent)

getEchoChar

public char getEchoChar()
Returns the character to be used for echoing. The default is '*'. The default may be different depending on the currently running Look and Feel. For example, Metal/Ocean's default is a bullet character.

Returns:
the echo character, 0 if unset
See Also:
setEchoChar(char), echoCharIsSet()

setEchoChar

public void setEchoChar(char c)
Sets the echo character for this JPasswordField. Note that this is largely a suggestion, since the view that gets installed can use whatever graphic techniques it desires to represent the field. Setting a value of 0 indicates that you wish to see the text as it is typed, similar to the behavior of a standard JTextField.

Parameters:
c - the echo character to display
See Also:
echoCharIsSet(), getEchoChar()

echoCharIsSet

public boolean echoCharIsSet()
Returns true if this JPasswordField has a character set for echoing. A character is considered to be set if the echo character is not 0.

Returns:
true if a character is set for echoing
See Also:
setEchoChar(char), getEchoChar()

cut

public void cut()
Invokes provideErrorFeedback on the current look and feel, which typically initiates an error beep. The normal behavior of transferring the currently selected range in the associated text model to the system clipboard, and removing the contents from the model, is not acceptable for a password field.

Overrides:
cut in class JTextComponent
See Also:
Toolkit.getSystemClipboard(), Clipboard

copy

public void copy()
Invokes provideErrorFeedback on the current look and feel, which typically initiates an error beep. The normal behavior of transferring the currently selected range in the associated text model to the system clipboard, and leaving the contents from the model, is not acceptable for a password field.

Overrides:
copy in class JTextComponent
See Also:
Toolkit.getSystemClipboard(), Clipboard

getText

@Deprecated
public String getText()
Deprecated. As of Java 2 platform v1.2, replaced by getPassword.

Returns the text contained in this TextComponent. If the underlying document is null, will give a NullPointerException.

For security reasons, this method is deprecated. Use the * getPassword method instead.

Overrides:
getText in class JTextComponent
Returns:
the text
See Also:
JTextComponent.setText(java.lang.String)

getText

@Deprecated
public String getText(int offs,
                                 int len)
               throws BadLocationException
Deprecated. As of Java 2 platform v1.2, replaced by getPassword.

Fetches a portion of the text represented by the component. Returns an empty string if length is 0.

For security reasons, this method is deprecated. Use the getPassword method instead.

Overrides:
getText in class JTextComponent
Parameters:
offs - the offset >= 0
len - the length >= 0
Returns:
the text
Throws:
BadLocationException - if the offset or length are invalid

getPassword

public char[] getPassword()
Returns the text contained in this TextComponent. If the underlying document is null, will give a NullPointerException. For stronger security, it is recommended that the returned character array be cleared after use by setting each character to zero.

Returns:
the text

paramString

protected String paramString()
Returns a string representation of this JPasswordField. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JTextField
Returns:
a string representation of this JPasswordField

getAccessibleContext

public AccessibleContext getAccessibleContext()
Returns the AccessibleContext associated with this JPasswordField. For password fields, the AccessibleContext takes the form of an AccessibleJPasswordField. A new AccessibleJPasswordField instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JTextField
Returns:
an AccessibleJPasswordField that serves as the AccessibleContext of this JPasswordField
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JPasswordField.AccessibleJPasswordField

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JPasswordField.AccessibleJPasswordField

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.text.JTextComponent.AccessibleJTextComponent
                        extended by  javax.swing.JTextField.AccessibleJTextField
                            extended by  javax.swing.JPasswordField.AccessibleJPasswordField
All Implemented Interfaces:
Serializable, EventListener, AccessibleAction, AccessibleComponent, AccessibleEditableText, AccessibleExtendedComponent, AccessibleExtendedText, AccessibleText, CaretListener, DocumentListener
Enclosing class:
JPasswordField
protected class JPasswordField.AccessibleJPasswordField
extends JTextField.AccessibleJTextField

This class implements accessibility support for the JPasswordField class. It provides an implementation of the Java Accessibility API appropriate to password field user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Fields inherited from interface javax.accessibility.AccessibleExtendedText
ATTRIBUTE_RUN, LINE
Constructor Summary
protected JPasswordField.AccessibleJPasswordField()
Method Summary
AccessibleRole | getAccessibleRole() Gets the role of this object.
AccessibleText | getAccessibleText() Gets the AccessibleText for the JPasswordField.
String | getAfterIndex(int part, int index) Returns the String after a given index.
String | getAtIndex(int part, int index) Returns the String at a given index.
String | getBeforeIndex(int part, int index) Returns the String before a given index.
String | getTextRange(int startIndex, int endIndex) Returns the text between two indices.
AccessibleTextSequence | getTextSequenceAfter(int part, int index) Returns the AccessibleTextSequence after a given index.
AccessibleTextSequence | getTextSequenceAt(int part, int index) Returns the AccessibleTextSequence at a given index.
AccessibleTextSequence | getTextSequenceBefore(int part, int index) Returns the AccessibleTextSequence before a given index.
Methods inherited from class javax.swing.JTextField.AccessibleJTextField
getAccessibleStateSet
Methods inherited from class javax.swing.text.JTextComponent.AccessibleJTextComponent
caretUpdate, changedUpdate, cut, delete, doAccessibleAction, getAccessibleAction, getAccessibleActionCount, getAccessibleActionDescription, getAccessibleEditableText, getCaretPosition, getCharacterAttribute, getCharacterBounds, getCharCount, getIndexAtPoint, getSelectedText, getSelectionEnd, getSelectionStart, getTextBounds, insertTextAtIndex, insertUpdate, paste, removeUpdate, replaceText, selectText, setAttributes, setTextContents
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JPasswordField.AccessibleJPasswordField

protected JPasswordField.AccessibleJPasswordField()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Gets the role of this object.

Overrides:
getAccessibleRole in class JTextComponent.AccessibleJTextComponent
Returns:
an instance of AccessibleRole describing the role of the object (AccessibleRole.PASSWORD_TEXT)
See Also:
AccessibleRole

getAccessibleText

public AccessibleText getAccessibleText()
Gets the AccessibleText for the JPasswordField. The returned object also implements the AccessibleExtendedText interface.

Overrides:
getAccessibleText in class JTextComponent.AccessibleJTextComponent
Returns:
AccessibleText for the JPasswordField
Since:
1.6
See Also:
AccessibleContext, AccessibleContext.getAccessibleText(), AccessibleText, AccessibleExtendedText

getAtIndex

public String getAtIndex(int part,
                         int index)
Returns the String at a given index.

Specified by:
getAtIndex in interface AccessibleText
Overrides:
getAtIndex in class JTextComponent.AccessibleJTextComponent
Parameters:
part - the CHARACTER, WORD or SENTENCE to retrieve
index - an index within the text
Returns:
a String if part and index are valid. Otherwise, null is returned
Since:
1.6
See Also:
AccessibleText.CHARACTER, AccessibleText.WORD, AccessibleText.SENTENCE

getAfterIndex

public String getAfterIndex(int part,
                            int index)
Returns the String after a given index.

Specified by:
getAfterIndex in interface AccessibleText
Overrides:
getAfterIndex in class JTextComponent.AccessibleJTextComponent
Parameters:
part - the CHARACTER, WORD or SENTENCE to retrieve
index - an index within the text
Returns:
a String if part and index are valid. Otherwise, null is returned
Since:
1.6
See Also:
AccessibleText.CHARACTER, AccessibleText.WORD, AccessibleText.SENTENCE

getBeforeIndex

public String getBeforeIndex(int part,
                             int index)
Returns the String before a given index.

Specified by:
getBeforeIndex in interface AccessibleText
Overrides:
getBeforeIndex in class JTextComponent.AccessibleJTextComponent
Parameters:
part - the CHARACTER, WORD or SENTENCE to retrieve
index - an index within the text
Returns:
a String if part and index are valid. Otherwise, null is returned
Since:
1.6
See Also:
AccessibleText.CHARACTER, AccessibleText.WORD, AccessibleText.SENTENCE

getTextRange

public String getTextRange(int startIndex,
                           int endIndex)
Returns the text between two indices.

Specified by:
getTextRange in interface AccessibleEditableText
Specified by:
getTextRange in interface AccessibleExtendedText
Overrides:
getTextRange in class JTextComponent.AccessibleJTextComponent
Parameters:
startIndex - the start index in the text
endIndex - the end index in the text
Returns:
the text string if the indices are valid. Otherwise, null is returned
Since:
1.6

getTextSequenceAt

public AccessibleTextSequence getTextSequenceAt(int part,
                                                int index)
Returns the AccessibleTextSequence at a given index.

Specified by:
getTextSequenceAt in interface AccessibleExtendedText
Overrides:
getTextSequenceAt in class JTextComponent.AccessibleJTextComponent
Parameters:
part - the CHARACTER, WORD, SENTENCE, LINE or ATTRIBUTE_RUN to retrieve
index - an index within the text
Returns:
an AccessibleTextSequence specifying the text if part and index are valid. Otherwise, null is returned
Since:
1.6
See Also:
AccessibleText.CHARACTER, AccessibleText.WORD, AccessibleText.SENTENCE, AccessibleExtendedText.LINE, AccessibleExtendedText.ATTRIBUTE_RUN

getTextSequenceAfter

public AccessibleTextSequence getTextSequenceAfter(int part,
                                                   int index)
Returns the AccessibleTextSequence after a given index.

Specified by:
getTextSequenceAfter in interface AccessibleExtendedText
Overrides:
getTextSequenceAfter in class JTextComponent.AccessibleJTextComponent
Parameters:
part - the CHARACTER, WORD, SENTENCE, LINE or ATTRIBUTE_RUN to retrieve
index - an index within the text
Returns:
an AccessibleTextSequence specifying the text if part and index are valid. Otherwise, null is returned
Since:
1.6
See Also:
AccessibleText.CHARACTER, AccessibleText.WORD, AccessibleText.SENTENCE, AccessibleExtendedText.LINE, AccessibleExtendedText.ATTRIBUTE_RUN

getTextSequenceBefore

public AccessibleTextSequence getTextSequenceBefore(int part,
                                                    int index)
Returns the AccessibleTextSequence before a given index.

Specified by:
getTextSequenceBefore in interface AccessibleExtendedText
Overrides:
getTextSequenceBefore in class JTextComponent.AccessibleJTextComponent
Parameters:
part - the CHARACTER, WORD, SENTENCE, LINE or ATTRIBUTE_RUN to retrieve
index - an index within the text
Returns:
an AccessibleTextSequence specifying the text if part and index are valid. Otherwise, null is returned
Since:
1.6
See Also:
AccessibleText.CHARACTER, AccessibleText.WORD, AccessibleText.SENTENCE, AccessibleExtendedText.LINE, AccessibleExtendedText.ATTRIBUTE_RUN
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JPopupMenu

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JPopupMenu

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JPopupMenu
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, MenuElement
Direct Known Subclasses:
BasicComboPopup
public class JPopupMenu
extends JComponent
implements Accessible, MenuElement

An implementation of a popup menu -- a small window that pops up and displays a series of choices. A JPopupMenu is used for the menu that appears when the user selects an item on the menu bar. It is also used for "pull-right" menu that appears when the selects a menu item that activates it. Finally, a JPopupMenu can also be used anywhere else you want a menu to appear. For example, when the user right-clicks in a specified area.

For information and examples of using popup menus, see How to Use Menus in The Java Tutorial.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected class | JPopupMenu.AccessibleJPopupMenu This class implements accessibility support for the JPopupMenu class.
static class | JPopupMenu.Separator A popup menu-specific separator.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JPopupMenu()
Constructs a JPopupMenu without an "invoker".
JPopupMenu(String label)
Constructs a JPopupMenu with the specified title.
Method Summary
 JMenuItem add(Action a)
Appends a new menu item to the end of the menu which dispatches the specified Action object.
 JMenuItem add(JMenuItem menuItem)
Appends the specified menu item to the end of this menu.
 JMenuItem add(String s)
Creates a new menu item with the specified text and appends it to the end of this menu.
 void addMenuKeyListener(MenuKeyListener l)
Adds a MenuKeyListener to the popup menu.
 void addPopupMenuListener(PopupMenuListener l)
Adds a PopupMenu listener.
 void addSeparator()
Appends a new separator at the end of the menu.
protected  PropertyChangeListener createActionChangeListener(JMenuItem b)
Returns a properly configured PropertyChangeListener which updates the control as changes to the Action occur.
protected  JMenuItem createActionComponent(Action a)
Factory method which creates the JMenuItem for Actions added to the JPopupMenu.
protected  void firePopupMenuCanceled()
Notifies PopupMenuListeners that this popup menu is cancelled.
protected  void firePopupMenuWillBecomeInvisible()
Notifies PopupMenuListeners that this popup menu will become invisible.
protected  void firePopupMenuWillBecomeVisible()
Notifies PopupMenuListeners that this popup menu will become visible.
 AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JPopupMenu.
 Component getComponent()
Returns this JPopupMenu component.
 Component getComponentAtIndex(int i)
Deprecated. replaced by Container.getComponent(int)
 int getComponentIndex(Component c)
Returns the index of the specified component.
static boolean getDefaultLightWeightPopupEnabled()
Gets the defaultLightWeightPopupEnabled property, which by default is true.
 Component getInvoker()
Returns the component which is the 'invoker' of this popup menu.
 String getLabel()
Returns the popup menu's label
 Insets getMargin()
Returns the margin, in pixels, between the popup menu's border and its containees.
 MenuKeyListener[] getMenuKeyListeners()
Returns an array of all the MenuKeyListeners added to this JPopupMenu with addMenuKeyListener().
 PopupMenuListener[] getPopupMenuListeners()
Returns an array of all the PopupMenuListeners added to this JMenuItem with addPopupMenuListener().
 SingleSelectionModel getSelectionModel()
Returns the model object that handles single selections.
 MenuElement[] getSubElements()
Returns an array of MenuElements containing the submenu for this menu component.
 PopupMenuUI getUI()
Returns the look and feel (L&F) object that renders this component.
 String getUIClassID()
Returns the name of the L&F class that renders this component.
 void insert(Action a, int index)
Inserts a menu item for the specified Action object at a given position.
 void insert(Component component, int index)
Inserts the specified component into the menu at a given position.
 boolean isBorderPainted()
Checks whether the border should be painted.
 boolean isLightWeightPopupEnabled()
Gets the lightWeightPopupEnabled property.
 boolean isPopupTrigger(MouseEvent e)
Returns true if the MouseEvent is considered a popup trigger by the JPopupMenu's currently installed UI.
 boolean isVisible()
Returns true if the popup menu is visible (currently being displayed).
 void menuSelectionChanged(boolean isIncluded)
Messaged when the menubar selection changes to activate or deactivate this menu.
 void pack()
Lays out the container so that it uses the minimum space needed to display its contents.
protected  void paintBorder(Graphics g)
Paints the popup menu's border if the borderPainted property is true.
protected  String paramString()
Returns a string representation of this JPopupMenu.
protected  void processFocusEvent(FocusEvent evt)
Processes focus events occurring on this component by dispatching them to any registered FocusListener objects.
protected  void processKeyEvent(KeyEvent evt)
Processes key stroke events such as mnemonics and accelerators.
 void processKeyEvent(KeyEvent e, MenuElement[] path, MenuSelectionManager manager)
Processes a key event forwarded from the MenuSelectionManager and changes the menu selection, if necessary, by using MenuSelectionManager's API.
 void processMouseEvent(MouseEvent event, MenuElement[] path, MenuSelectionManager manager)
This method is required to conform to the MenuElement interface, but it not implemented.
 void remove(int pos)
Removes the component at the specified index from this popup menu.
 void removeMenuKeyListener(MenuKeyListener l)
Removes a MenuKeyListener from the popup menu.
 void removePopupMenuListener(PopupMenuListener l)
Removes a PopupMenu listener.
 void setBorderPainted(boolean b)
Sets whether the border should be painted.
static void setDefaultLightWeightPopupEnabled(boolean aFlag)
Sets the default value of the lightWeightPopupEnabled property.
 void setInvoker(Component invoker)
Sets the invoker of this popup menu -- the component in which the popup menu menu is to be displayed.
 void setLabel(String label)
Sets the popup menu's label.
 void setLightWeightPopupEnabled(boolean aFlag)
Sets the value of the lightWeightPopupEnabled property, which by default is true.
 void setLocation(int x, int y)
Sets the location of the upper left corner of the popup menu using x, y coordinates.
 void setPopupSize(Dimension d)
Sets the size of the Popup window using a Dimension object.
 void setPopupSize(int width, int height)
Sets the size of the Popup window to the specified width and height.
 void setSelected(Component sel)
Sets the currently selected component, This will result in a change to the selection model.
 void setSelectionModel(SingleSelectionModel model)
Sets the model object to handle single selections.
 void setUI(PopupMenuUI ui)
Sets the L&F object that renders this component.
 void setVisible(boolean b)
Sets the visibility of the popup menu.
 void show(Component invoker, int x, int y)
Displays the popup menu at the position x,y in the coordinate space of the component invoker.
 void updateUI()
Resets the UI property to a value from the current look and feel.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JPopupMenu

public JPopupMenu()
Constructs a JPopupMenu without an "invoker".

JPopupMenu

public JPopupMenu(String label)
Constructs a JPopupMenu with the specified title.

Parameters:
label - the string that a UI may use to display as a title for the popup menu.
Method Detail

setDefaultLightWeightPopupEnabled

public static void setDefaultLightWeightPopupEnabled(boolean aFlag)
Sets the default value of the lightWeightPopupEnabled property.

Parameters:
aFlag - true if popups can be lightweight, otherwise false
See Also:
getDefaultLightWeightPopupEnabled(), setLightWeightPopupEnabled(boolean)

getDefaultLightWeightPopupEnabled

public static boolean getDefaultLightWeightPopupEnabled()
Gets the defaultLightWeightPopupEnabled property, which by default is true.

Returns:
the value of the defaultLightWeightPopupEnabled property
See Also:
setDefaultLightWeightPopupEnabled(boolean)

getUI

public PopupMenuUI getUI()
Returns the look and feel (L&F) object that renders this component.

Returns:
the PopupMenuUI object that renders this component

setUI

public void setUI(PopupMenuUI ui)
Sets the L&F object that renders this component.

Parameters:
ui - the new PopupMenuUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Resets the UI property to a value from the current look and feel.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "PopupMenuUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

processFocusEvent

protected void processFocusEvent(FocusEvent evt)
Description copied from class: Component
Processes focus events occurring on this component by dispatching them to any registered FocusListener objects.

This method is not called unless focus events are enabled for this component. Focus events are enabled when one of the following occurs:

  • A FocusListener object is registered via addFocusListener.
  • Focus events are enabled via enableEvents.

If focus events are enabled for a Component, the current KeyboardFocusManager determines whether or not a focus event should be dispatched to registered FocusListener objects. If the events are to be dispatched, the KeyboardFocusManager calls the Component's dispatchEvent method, which results in a call to the Component's processFocusEvent method.

If focus events are enabled for a Component, calling the Component's dispatchEvent method with a FocusEvent as the argument will result in a call to the Component's processFocusEvent method regardless of the current KeyboardFocusManager.

Note that if the event parameter is null the behavior is unspecified and may result in an exception.

Overrides:
processFocusEvent in class Component
Parameters:
evt - the focus event
See Also:
FocusEvent, FocusListener, KeyboardFocusManager, Component.addFocusListener(java.awt.event.FocusListener), Component.enableEvents(long), Component.dispatchEvent(java.awt.AWTEvent)

processKeyEvent

protected void processKeyEvent(KeyEvent evt)
Processes key stroke events such as mnemonics and accelerators.

Overrides:
processKeyEvent in class JComponent
Parameters:
evt - the key event to be processed
See Also:
KeyEvent, KeyListener, KeyboardFocusManager, DefaultKeyboardFocusManager, Component.processEvent(java.awt.AWTEvent), Component.dispatchEvent(java.awt.AWTEvent), Component.addKeyListener(java.awt.event.KeyListener), Component.enableEvents(long), Component.isShowing()

getSelectionModel

public SingleSelectionModel getSelectionModel()
Returns the model object that handles single selections.

Returns:
the selectionModel property
See Also:
SingleSelectionModel

setSelectionModel

public void setSelectionModel(SingleSelectionModel model)
Sets the model object to handle single selections.

Parameters:
model - the new SingleSelectionModel
See Also:
SingleSelectionModel

add

public JMenuItem add(JMenuItem menuItem)
Appends the specified menu item to the end of this menu.

Parameters:
menuItem - the JMenuItem to add
Returns:
the JMenuItem added

add

public JMenuItem add(String s)
Creates a new menu item with the specified text and appends it to the end of this menu.

Parameters:
s - the string for the menu item to be added

add

public JMenuItem add(Action a)
Appends a new menu item to the end of the menu which dispatches the specified Action object.

Parameters:
a - the Action to add to the menu
Returns:
the new menu item
See Also:
Action

createActionComponent

protected JMenuItem createActionComponent(Action a)
Factory method which creates the JMenuItem for Actions added to the JPopupMenu.

Parameters:
a - the Action for the menu item to be added
Returns:
the new menu item
Since:
1.3
See Also:
Action

createActionChangeListener

protected PropertyChangeListener createActionChangeListener(JMenuItem b)
Returns a properly configured PropertyChangeListener which updates the control as changes to the Action occur.

remove

public void remove(int pos)
Removes the component at the specified index from this popup menu.

Overrides:
remove in class Container
Parameters:
pos - the position of the item to be removed
Throws:
IllegalArgumentException - if the value of pos < 0, or if the value of pos is greater than the number of items
See Also:
Container.add(java.awt.Component),
Container.validate(),
Container.getComponentCount()

setLightWeightPopupEnabled

public void setLightWeightPopupEnabled(boolean aFlag)
Sets the value of the lightWeightPopupEnabled property, which by default is true. By default, when a look and feel displays a popup, it can choose to use a lightweight (all-Java) popup. Lightweight popup windows are more efficient than heavyweight (native peer) windows, but lightweight and heavyweight components do not mix well in a GUI. If your application mixes lightweight and heavyweight components, you should disable lightweight popups. Some look and feels might always use heavyweight popups, no matter what the value of this property.

Parameters:
aFlag - false to disable lightweight popups
See Also:
isLightWeightPopupEnabled()

isLightWeightPopupEnabled

public boolean isLightWeightPopupEnabled()
Gets the lightWeightPopupEnabled property.

Returns:
the value of the lightWeightPopupEnabled property
See Also:
setLightWeightPopupEnabled(boolean)

getLabel

public String getLabel()
Returns the popup menu's label

Returns:
a string containing the popup menu's label
See Also:
setLabel(java.lang.String)

setLabel

public void setLabel(String label)
Sets the popup menu's label. Different look and feels may choose to display or not display this.

Parameters:
label - a string specifying the label for the popup menu
See Also:
setLabel(java.lang.String)

addSeparator

public void addSeparator()
Appends a new separator at the end of the menu.

insert

public void insert(Action a,
                   int index)
Inserts a menu item for the specified Action object at a given position.

Parameters:
a - the Action object to insert
index - specifies the position at which to insert the Action, where 0 is the first
Throws:
IllegalArgumentException - if index < 0
See Also:
Action

insert

public void insert(Component component,
                   int index)
Inserts the specified component into the menu at a given position.

Parameters:
component - the Component to insert
index - specifies the position at which to insert the component, where 0 is the first
Throws:
IllegalArgumentException - if index < 0

addPopupMenuListener

public void addPopupMenuListener(PopupMenuListener l)
Adds a PopupMenu listener.

Parameters:
l - the PopupMenuListener to add

removePopupMenuListener

public void removePopupMenuListener(PopupMenuListener l)
Removes a PopupMenu listener.

Parameters:
l - the PopupMenuListener to remove

getPopupMenuListeners

public PopupMenuListener[] getPopupMenuListeners()
Returns an array of all the PopupMenuListeners added to this JMenuItem with addPopupMenuListener().

Returns:
all of the PopupMenuListeners added or an empty array if no listeners have been added
Since:
1.4

addMenuKeyListener

public void addMenuKeyListener(MenuKeyListener l)
Adds a MenuKeyListener to the popup menu.

Parameters:
l - the MenuKeyListener to be added
Since:
1.5

removeMenuKeyListener

public void removeMenuKeyListener(MenuKeyListener l)
Removes a MenuKeyListener from the popup menu.

Parameters:
l - the MenuKeyListener to be removed
Since:
1.5

getMenuKeyListeners

public MenuKeyListener[] getMenuKeyListeners()
Returns an array of all the MenuKeyListeners added to this JPopupMenu with addMenuKeyListener().

Returns:
all of the MenuKeyListeners added or an empty array if no listeners have been added
Since:
1.5

firePopupMenuWillBecomeVisible

protected void firePopupMenuWillBecomeVisible()
Notifies PopupMenuListeners that this popup menu will become visible.

firePopupMenuWillBecomeInvisible

protected void firePopupMenuWillBecomeInvisible()
Notifies PopupMenuListeners that this popup menu will become invisible.

firePopupMenuCanceled

protected void firePopupMenuCanceled()
Notifies PopupMenuListeners that this popup menu is cancelled.

pack

public void pack()
Lays out the container so that it uses the minimum space needed to display its contents.

setVisible

public void setVisible(boolean b)
Sets the visibility of the popup menu.

Overrides:
setVisible in class JComponent
Parameters:
b - true to make the popup visible, or false to hide it
See Also:
Component.isVisible()

isVisible

public boolean isVisible()
Returns true if the popup menu is visible (currently being displayed).

Overrides:
isVisible in class Component
Returns:
true if the component is visible, false otherwise
See Also:
Component.setVisible(boolean)

setLocation

public void setLocation(int x,
                        int y)
Sets the location of the upper left corner of the popup menu using x, y coordinates.

Overrides:
setLocation in class Component
Parameters:
x - the x coordinate of the popup's new position in the screen's coordinate space
y - the y coordinate of the popup's new position in the screen's coordinate space
See Also:
Component.getLocation(), Component.setBounds(int, int, int, int)

getInvoker

public Component getInvoker()
Returns the component which is the 'invoker' of this popup menu.

Returns:
the Component in which the popup menu is displayed

setInvoker

public void setInvoker(Component invoker)
Sets the invoker of this popup menu -- the component in which the popup menu menu is to be displayed.

Parameters:
invoker - the Component in which the popup menu is displayed

show

public void show(Component invoker,
                 int x,
                 int y)
Displays the popup menu at the position x,y in the coordinate space of the component invoker.

Parameters:
invoker - the component in whose space the popup menu is to appear
x - the x coordinate in invoker's coordinate space at which the popup menu is to be displayed
y - the y coordinate in invoker's coordinate space at which the popup menu is to be displayed

getComponentAtIndex

@Deprecated
public Component getComponentAtIndex(int i)
Deprecated. replaced by Container.getComponent(int)

Returns the component at the specified index.

Parameters:
i - the index of the component, where 0 is the first
Returns:
the Component at that index

getComponentIndex

public int getComponentIndex(Component c)
Returns the index of the specified component.

Parameters:
c - the Component to find
Returns:
the index of the component, where 0 is the first; or -1 if the component is not found

setPopupSize

public void setPopupSize(Dimension d)
Sets the size of the Popup window using a Dimension object. This is equivalent to setPreferredSize(d).

Parameters:
d - the Dimension specifying the new size of this component.

setPopupSize

public void setPopupSize(int width,
                         int height)
Sets the size of the Popup window to the specified width and height. This is equivalent to setPreferredSize(new Dimension(width, height)).

Parameters:
width - the new width of the Popup in pixels
height - the new height of the Popup in pixels

setSelected

public void setSelected(Component sel)
Sets the currently selected component, This will result in a change to the selection model.

Parameters:
sel - the Component to select

isBorderPainted

public boolean isBorderPainted()
Checks whether the border should be painted.

Returns:
true if the border is painted, false otherwise
See Also:
setBorderPainted(boolean)

setBorderPainted

public void setBorderPainted(boolean b)
Sets whether the border should be painted.

Parameters:
b - if true, the border is painted.
See Also:
isBorderPainted()

paintBorder

protected void paintBorder(Graphics g)
Paints the popup menu's border if the borderPainted property is true.

Overrides:
paintBorder in class JComponent
Parameters:
g - the Graphics object
See Also:
JComponent.paint(java.awt.Graphics), JComponent.setBorder(javax.swing.border.Border)

getMargin

public Insets getMargin()
Returns the margin, in pixels, between the popup menu's border and its containees.

Returns:
an Insets object containing the margin values.

paramString

protected String paramString()
Returns a string representation of this JPopupMenu. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JPopupMenu.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JPopupMenu. For JPopupMenus, the AccessibleContext takes the form of an AccessibleJPopupMenu. A new AccessibleJPopupMenu instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJPopupMenu that serves as the AccessibleContext of this JPopupMenu

processMouseEvent

public void processMouseEvent(MouseEvent event,
                              MenuElement[] path,
                              MenuSelectionManager manager)
This method is required to conform to the MenuElement interface, but it not implemented.

Specified by:
processMouseEvent in interface MenuElement
See Also:
MenuElement.processMouseEvent(MouseEvent, MenuElement[], MenuSelectionManager)

processKeyEvent

public void processKeyEvent(KeyEvent e,
                            MenuElement[] path,
                            MenuSelectionManager manager)
Processes a key event forwarded from the MenuSelectionManager and changes the menu selection, if necessary, by using MenuSelectionManager's API.

Note: you do not have to forward the event to sub-components. This is done automatically by the MenuSelectionManager.

Specified by:
processKeyEvent in interface MenuElement
Parameters:
e - a KeyEvent
path - the MenuElement path array
manager - the MenuSelectionManager

menuSelectionChanged

public void menuSelectionChanged(boolean isIncluded)
Messaged when the menubar selection changes to activate or deactivate this menu. This implements the javax.swing.MenuElement interface. Overrides MenuElement.menuSelectionChanged.

Specified by:
menuSelectionChanged in interface MenuElement
Parameters:
isIncluded - true if this menu is active, false if it is not
See Also:
MenuElement.menuSelectionChanged(boolean)

getSubElements

public MenuElement[] getSubElements()
Returns an array of MenuElements containing the submenu for this menu component. It will only return items conforming to the JMenuElement interface. If popup menu is null returns an empty array. This method is required to conform to the MenuElement interface.

Specified by:
getSubElements in interface MenuElement
Returns:
an array of MenuElement objects
See Also:
MenuElement.getSubElements()

getComponent

public Component getComponent()
Returns this JPopupMenu component.

Specified by:
getComponent in interface MenuElement
Returns:
this JPopupMenu object
See Also:
MenuElement.getComponent()

isPopupTrigger

public boolean isPopupTrigger(MouseEvent e)
Returns true if the MouseEvent is considered a popup trigger by the JPopupMenu's currently installed UI.

Returns:
true if the mouse event is a popup trigger
Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JPopupMenu.AccessibleJPopupMenu

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JPopupMenu.AccessibleJPopupMenu

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JPopupMenu.AccessibleJPopupMenu
All Implemented Interfaces:
PropertyChangeListener, Serializable, EventListener, AccessibleComponent, AccessibleExtendedComponent
Enclosing class:
JPopupMenu
protected class JPopupMenu.AccessibleJPopupMenu
extends JComponent.AccessibleJComponent
implements PropertyChangeListener

This class implements accessibility support for the JPopupMenu class. It provides an implementation of the Java Accessibility API appropriate to popup menu user-interface elements.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JPopupMenu.AccessibleJPopupMenu()
AccessibleJPopupMenu constructor
Method Summary
AccessibleRole | getAccessibleRole() Get the role of this object.
void | propertyChange(PropertyChangeEvent e) This method gets called when a bound property is changed.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JPopupMenu.AccessibleJPopupMenu

protected JPopupMenu.AccessibleJPopupMenu()
AccessibleJPopupMenu constructor

Since:
1.5
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

propertyChange

public void propertyChange(PropertyChangeEvent e)
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed. Must not be null.
Throws:
NullPointerException - if the parameter is null.
Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JPopupMenu.Separator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JPopupMenu.Separator

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JSeparator
                    extended by  javax.swing.JPopupMenu.Separator
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, SwingConstants
Enclosing class:
JPopupMenu
public static class JPopupMenu.Separator
extends JSeparator

A popup menu-specific separator.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JSeparator
JSeparator.AccessibleJSeparator
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JPopupMenu.Separator()
Method Summary
 String getUIClassID()
Returns the name of the L&F class that renders this component.
Methods inherited from class javax.swing.JSeparator
getAccessibleContext, getOrientation, getUI, paramString, setOrientation, setUI, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JPopupMenu.Separator

public JPopupMenu.Separator()
Method Detail

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JSeparator
Returns:
the string "PopupMenuSeparatorUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JProgressBar

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JProgressBar

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JProgressBar
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, SwingConstants
public class JProgressBar
extends JComponent
implements SwingConstants, Accessible

A component that visually displays the progress of some task. As the task progresses towards completion, the progress bar displays the task's percentage of completion. This percentage is typically represented visually by a rectangle which starts out empty and gradually becomes filled in as the task progresses. In addition, the progress bar can display a textual representation of this percentage.

JProgressBar uses a BoundedRangeModel as its data model, with the value property representing the "current" state of the task, and the minimum and maximum properties representing the beginning and end points, respectively.

To indicate that a task of unknown length is executing, you can put a progress bar into indeterminate mode. While the bar is in indeterminate mode, it animates constantly to show that work is occurring. As soon as you can determine the task's length and amount of progress, you should update the progress bar's value and switch it back to determinate mode.

Here is an example of creating a progress bar, where task is an object (representing some piece of work) which returns information about the progress of the task:

progressBar = new JProgressBar(0, task.getLengthOfTask());
progressBar.setValue(0);
progressBar.setStringPainted(true);
Here is an example of querying the current state of the task, and using the returned value to update the progress bar:
progressBar.setValue(task.getCurrent());
Here is an example of putting a progress bar into indeterminate mode, and then switching back to determinate mode once the length of the task is known:
progressBar = new JProgressBar();
...//when the task of (initially) unknown length begins:
progressBar.setIndeterminate(true);
...//do some work; get length of task...
progressBar.setMaximum(newLength);
progressBar.setValue(newValue);
progressBar.setIndeterminate(false);

For complete examples and further documentation see How to Monitor Progress, a section in The Java Tutorial.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
BasicProgressBarUI, BoundedRangeModel, SwingWorker

Nested Class Summary
protected  class JProgressBar.AccessibleJProgressBar
This class implements accessibility support for the JProgressBar class.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected ChangeEvent | changeEvent Only one ChangeEvent is needed per instance since the event's only interesting property is the immutable source, which is the progress bar.
protected ChangeListener | changeListener Listens for change events sent by the progress bar's model, redispatching them to change-event listeners registered upon this progress bar.
protected BoundedRangeModel | model The object that holds the data for the progress bar.
protected int | orientation Whether the progress bar is horizontal or vertical.
protected boolean | paintBorder Whether to display a border around the progress bar.
protected boolean | paintString Whether to display a string of text on the progress bar.
protected String | progressString An optional string that can be displayed on the progress bar.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JProgressBar()
Creates a horizontal progress bar that displays a border but no progress string.
JProgressBar(BoundedRangeModel newModel)
Creates a horizontal progress bar that uses the specified model to hold the progress bar's data.
JProgressBar(int orient)
Creates a progress bar with the specified orientation, which can be either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL.
JProgressBar(int min, int max)
Creates a horizontal progress bar with the specified minimum and maximum.
JProgressBar(int orient, int min, int max)
Creates a progress bar using the specified orientation, minimum, and maximum.
Method Summary
void | addChangeListener(ChangeListener l) Adds the specified ChangeListener to the progress bar.
protected ChangeListener | createChangeListener() Subclasses that want to handle change events from the model differently can override this to return an instance of a custom ChangeListener implementation.
protected void | fireStateChanged() Send a ChangeEvent, whose source is this JProgressBar, to all ChangeListeners that have registered interest in ChangeEvents.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JProgressBar.
ChangeListener[] | getChangeListeners() Returns an array of all the ChangeListeners added to this progress bar with addChangeListener.
int | getMaximum() Returns the progress bar's maximum value from the BoundedRangeModel.
int | getMinimum() Returns the progress bar's minimum value from the BoundedRangeModel.
BoundedRangeModel | getModel() Returns the data model used by this progress bar.
int | getOrientation() Returns SwingConstants.VERTICAL or SwingConstants.HORIZONTAL, depending on the orientation of the progress bar.
double | getPercentComplete() Returns the percent complete for the progress bar.
String | getString() Returns a String representation of the current progress.
ProgressBarUI | getUI() Returns the look-and-feel object that renders this component.
String | getUIClassID() Returns the name of the look-and-feel class that renders this component.
int | getValue() Returns the progress bar's current value from the BoundedRangeModel.
boolean | isBorderPainted() Returns the borderPainted property.
boolean | isIndeterminate() Returns the value of the indeterminate property.
boolean | isStringPainted() Returns the value of the stringPainted property.
protected void | paintBorder(Graphics g) Paints the progress bar's border if the borderPainted property is true.
protected String | paramString() Returns a string representation of this JProgressBar.
void | removeChangeListener(ChangeListener l) Removes a ChangeListener from the progress bar.
void | setBorderPainted(boolean b) Sets the borderPainted property, which is true if the progress bar should paint its border.
void | setIndeterminate(boolean newValue) Sets the indeterminate property of the progress bar, which determines whether the progress bar is in determinate or indeterminate mode.
void | setMaximum(int n) Sets the progress bar's maximum value (stored in the progress bar's data model) to n.
void | setMinimum(int n) Sets the progress bar's minimum value (stored in the progress bar's data model) to n.
void | setModel(BoundedRangeModel newModel) Sets the data model used by the JProgressBar.
void | setOrientation(int newOrientation) Sets the progress bar's orientation to newOrientation, which must be SwingConstants.VERTICAL or SwingConstants.HORIZONTAL.
void | setString(String s) Sets the value of the progress string.
void | setStringPainted(boolean b) Sets the value of the stringPainted property, which determines whether the progress bar should render a progress string.
void | setUI(ProgressBarUI ui) Sets the look-and-feel object that renders this component.
void | setValue(int n) Sets the progress bar's current value to n.
void | updateUI() Resets the UI property to a value from the current look and feel.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

orientation

protected int orientation
Whether the progress bar is horizontal or vertical. The default is HORIZONTAL.

See Also:
setOrientation(int)

paintBorder

protected boolean paintBorder
Whether to display a border around the progress bar. The default is true.

See Also:
setBorderPainted(boolean)

model

protected BoundedRangeModel model
The object that holds the data for the progress bar.

See Also:
setModel(javax.swing.BoundedRangeModel)

progressString

protected String progressString
An optional string that can be displayed on the progress bar. The default is null. Setting this to a non-null value does not imply that the string will be displayed. To display the string, paintString must be true.

See Also:
setString(java.lang.String), setStringPainted(boolean)

paintString

protected boolean paintString
Whether to display a string of text on the progress bar. The default is false. Setting this to true causes a textual display of the progress to be rendered on the progress bar. If the progressString is null, the percentage of completion is displayed on the progress bar. Otherwise, the progressString is rendered on the progress bar.

See Also:
setStringPainted(boolean), setString(java.lang.String)

changeEvent

protected transient ChangeEvent changeEvent
Only one ChangeEvent is needed per instance since the event's only interesting property is the immutable source, which is the progress bar. The event is lazily created the first time that an event notification is fired.

See Also:
fireStateChanged()

changeListener

protected ChangeListener changeListener
Listens for change events sent by the progress bar's model, redispatching them to change-event listeners registered upon this progress bar.

See Also:
createChangeListener()
Constructor Detail

JProgressBar

public JProgressBar()
Creates a horizontal progress bar that displays a border but no progress string. The initial and minimum values are 0, and the maximum is 100.

See Also:
setOrientation(int), setBorderPainted(boolean), setStringPainted(boolean), setString(java.lang.String), setIndeterminate(boolean)

JProgressBar

public JProgressBar(int orient)
Creates a progress bar with the specified orientation, which can be either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL. By default, a border is painted but a progress string is not. The initial and minimum values are 0, and the maximum is 100.

Parameters:
orient - the desired orientation of the progress bar
Throws:
IllegalArgumentException - if orient is an illegal value
See Also:
setOrientation(int), setBorderPainted(boolean), setStringPainted(boolean), setString(java.lang.String), setIndeterminate(boolean)

JProgressBar

public JProgressBar(int min,
                    int max)
Creates a horizontal progress bar with the specified minimum and maximum. Sets the initial value of the progress bar to the specified minimum. By default, a border is painted but a progress string is not.

The BoundedRangeModel that holds the progress bar's data handles any issues that may arise from improperly setting the minimum, initial, and maximum values on the progress bar. See the BoundedRangeModel documentation for details.

Parameters:
min - the minimum value of the progress bar
max - the maximum value of the progress bar
See Also:
BoundedRangeModel, setOrientation(int), setBorderPainted(boolean), setStringPainted(boolean), setString(java.lang.String), setIndeterminate(boolean)

JProgressBar

public JProgressBar(int orient,
                    int min,
                    int max)
Creates a progress bar using the specified orientation, minimum, and maximum. By default, a border is painted but a progress string is not. Sets the initial value of the progress bar to the specified minimum.

The BoundedRangeModel that holds the progress bar's data handles any issues that may arise from improperly setting the minimum, initial, and maximum values on the progress bar. See the BoundedRangeModel documentation for details.

Parameters:
orient - the desired orientation of the progress bar
min - the minimum value of the progress bar
max - the maximum value of the progress bar
Throws:
IllegalArgumentException - if orient is an illegal value
See Also:
BoundedRangeModel, setOrientation(int), setBorderPainted(boolean), setStringPainted(boolean), setString(java.lang.String), setIndeterminate(boolean)

JProgressBar

public JProgressBar(BoundedRangeModel newModel)
Creates a horizontal progress bar that uses the specified model to hold the progress bar's data. By default, a border is painted but a progress string is not.

Parameters:
newModel - the data model for the progress bar
See Also:
setOrientation(int), setBorderPainted(boolean), setStringPainted(boolean), setString(java.lang.String), setIndeterminate(boolean)
Method Detail

getOrientation

public int getOrientation()
Returns SwingConstants.VERTICAL or SwingConstants.HORIZONTAL, depending on the orientation of the progress bar. The default orientation is SwingConstants.HORIZONTAL.

Returns:
HORIZONTAL or VERTICAL
See Also:
setOrientation(int)

setOrientation

public void setOrientation(int newOrientation)
Sets the progress bar's orientation to newOrientation, which must be SwingConstants.VERTICAL or SwingConstants.HORIZONTAL. The default orientation is SwingConstants.HORIZONTAL.

Parameters:
newOrientation - HORIZONTAL or VERTICAL
Throws:
IllegalArgumentException - if newOrientation is an illegal value
See Also:
getOrientation()

isStringPainted

public boolean isStringPainted()
Returns the value of the stringPainted property.

Returns:
the value of the stringPainted property
See Also:
setStringPainted(boolean), setString(java.lang.String)

setStringPainted

public void setStringPainted(boolean b)
Sets the value of the stringPainted property, which determines whether the progress bar should render a progress string. The default is false, meaning no string is painted. Some look and feels might not support progress strings or might support them only when the progress bar is in determinate mode.

Parameters:
b - true if the progress bar should render a string
See Also:
isStringPainted(), setString(java.lang.String)

getString

public String getString()
Returns a String representation of the current progress. By default, this returns a simple percentage String based on the value returned from getPercentComplete. An example would be the "42%". You can change this by calling setString.

Returns:
the value of the progress string, or a simple percentage string if the progress string is null
See Also:
setString(java.lang.String)

setString

public void setString(String s)
Sets the value of the progress string. By default, this string is null, implying the built-in behavior of using a simple percent string. If you have provided a custom progress string and want to revert to the built-in behavior, set the string back to null.

The progress string is painted only if the isStringPainted method returns true.

Parameters:
s - the value of the progress string
See Also:
getString(), setStringPainted(boolean), isStringPainted()

getPercentComplete

public double getPercentComplete()
Returns the percent complete for the progress bar. Note that this number is between 0.0 and 1.0.

Returns:
the percent complete for this progress bar

isBorderPainted

public boolean isBorderPainted()
Returns the borderPainted property.

Returns:
the value of the borderPainted property
See Also:
setBorderPainted(boolean)

setBorderPainted

public void setBorderPainted(boolean b)
Sets the borderPainted property, which is true if the progress bar should paint its border. The default value for this property is true. Some look and feels might not implement painted borders; they will ignore this property.

Parameters:
b - true if the progress bar should paint its border; otherwise, false
See Also:
isBorderPainted()

paintBorder

protected void paintBorder(Graphics g)
Paints the progress bar's border if the borderPainted property is true.

Overrides:
paintBorder in class JComponent
Parameters:
g - the Graphics context within which to paint the border
See Also:
JComponent.paint(java.awt.Graphics),
JComponent.setBorder(javax.swing.border.Border),
isBorderPainted(),
setBorderPainted(boolean)

getUI

public ProgressBarUI getUI()
Returns the look-and-feel object that renders this component.

Returns:
the ProgressBarUI object that renders this component

setUI

public void setUI(ProgressBarUI ui)
Sets the look-and-feel object that renders this component.

Parameters:
ui - a ProgressBarUI object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Resets the UI property to a value from the current look and feel.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the look-and-feel class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "ProgressBarUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

createChangeListener

protected ChangeListener createChangeListener()
Subclasses that want to handle change events from the model differently can override this to return an instance of a custom ChangeListener implementation. The default ChangeListener simply calls the fireStateChanged method to forward ChangeEvents to the ChangeListeners that have been added directly to the progress bar.

See Also:
changeListener, fireStateChanged(), ChangeListener, BoundedRangeModel

addChangeListener

public void addChangeListener(ChangeListener l)
Adds the specified ChangeListener to the progress bar.

Parameters:
l - the ChangeListener to add

removeChangeListener

public void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the progress bar.

Parameters:
l - the ChangeListener to remove

getChangeListeners

public ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this progress bar with addChangeListener.

Returns:
all of the ChangeListeners added or an empty array if no listeners have been added
Since:
1.4

fireStateChanged

protected void fireStateChanged()
Send a ChangeEvent, whose source is this JProgressBar, to all ChangeListeners that have registered interest in ChangeEvents. This method is called each time a ChangeEvent is received from the model.

The event instance is created if necessary, and stored in changeEvent.

See Also:
addChangeListener(javax.swing.event.ChangeListener), EventListenerList

getModel

public BoundedRangeModel getModel()
Returns the data model used by this progress bar.

Returns:
the BoundedRangeModel currently in use
See Also:
setModel(javax.swing.BoundedRangeModel), BoundedRangeModel

setModel

public void setModel(BoundedRangeModel newModel)
Sets the data model used by the JProgressBar. Note that the BoundedRangeModel's extent is not used, and is set to 0.

Parameters:
newModel - the BoundedRangeModel to use

getValue

public int getValue()
Returns the progress bar's current value from the BoundedRangeModel. The value is always between the minimum and maximum values, inclusive.

Returns:
the current value of the progress bar
See Also:
setValue(int), BoundedRangeModel.getValue()

getMinimum

public int getMinimum()
Returns the progress bar's minimum value from the BoundedRangeModel.

Returns:
the progress bar's minimum value
See Also:
setMinimum(int), BoundedRangeModel.getMinimum()

getMaximum

public int getMaximum()
Returns the progress bar's maximum value from the BoundedRangeModel.

Returns:
the progress bar's maximum value
See Also:
setMaximum(int), BoundedRangeModel.getMaximum()

setValue

public void setValue(int n)
Sets the progress bar's current value to n. This method forwards the new value to the model.

The data model (an instance of BoundedRangeModel) handles any mathematical issues arising from assigning faulty values. See the BoundedRangeModel documentation for details.

If the new value is different from the previous value, all change listeners are notified.

Parameters:
n - the new value
See Also:
getValue(),
addChangeListener(javax.swing.event.ChangeListener),
BoundedRangeModel.setValue(int)

setMinimum

public void setMinimum(int n)
Sets the progress bar's minimum value (stored in the progress bar's data model) to n.

The data model (a BoundedRangeModel instance) handles any mathematical issues arising from assigning faulty values. See the BoundedRangeModel documentation for details.

If the minimum value is different from the previous minimum, all change listeners are notified.

Parameters:
n - the new minimum
See Also:
getMinimum(),
addChangeListener(javax.swing.event.ChangeListener),
BoundedRangeModel.setMinimum(int)

setMaximum

public void setMaximum(int n)
Sets the progress bar's maximum value (stored in the progress bar's data model) to n.

The underlying BoundedRangeModel handles any mathematical issues arising from assigning faulty values. See the BoundedRangeModel documentation for details.

If the maximum value is different from the previous maximum, all change listeners are notified.

Parameters:
n - the new maximum
See Also:
getMaximum(),
addChangeListener(javax.swing.event.ChangeListener),
BoundedRangeModel.setMaximum(int)

setIndeterminate

public void setIndeterminate(boolean newValue)
Sets the indeterminate property of the progress bar, which determines whether the progress bar is in determinate or indeterminate mode. An indeterminate progress bar continuously displays animation indicating that an operation of unknown length is occurring. By default, this property is false. Some look and feels might not support indeterminate progress bars; they will ignore this property.

See How to Monitor Progress for examples of using indeterminate progress bars.

Parameters:
newValue - true if the progress bar should change to indeterminate mode; false if it should revert to normal.
Since:
1.4
See Also:
isIndeterminate(), BasicProgressBarUI

isIndeterminate

public boolean isIndeterminate()
Returns the value of the indeterminate property.

Returns:
the value of the indeterminate property
Since:
1.4
See Also:
setIndeterminate(boolean)

paramString

protected String paramString()
Returns a string representation of this JProgressBar. This method is intended to be used only for debugging purposes. The content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JProgressBar

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JProgressBar. For progress bars, the AccessibleContext takes the form of an AccessibleJProgressBar. A new AccessibleJProgressBar instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJProgressBar that serves as the AccessibleContext of this JProgressBar
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JProgressBar.AccessibleJProgressBar

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JProgressBar.AccessibleJProgressBar

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JProgressBar.AccessibleJProgressBar
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent, AccessibleValue
Enclosing class:
JProgressBar
protected class JProgressBar.AccessibleJProgressBar
extends JComponent.AccessibleJComponent
implements AccessibleValue

This class implements accessibility support for the JProgressBar class. It provides an implementation of the Java Accessibility API appropriate to progress bar user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JProgressBar.AccessibleJProgressBar()
Method Summary
AccessibleRole | getAccessibleRole() Gets the role of this object.
AccessibleStateSet | getAccessibleStateSet() Gets the state set of this object.
AccessibleValue | getAccessibleValue() Gets the AccessibleValue associated with this object.
Number | getCurrentAccessibleValue() Gets the accessible value of this object.
Number | getMaximumAccessibleValue() Gets the maximum accessible value of this object.
Number | getMinimumAccessibleValue() Gets the minimum accessible value of this object.
boolean | setCurrentAccessibleValue(Number n) Sets the value of this object as a Number.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JProgressBar.AccessibleJProgressBar

protected JProgressBar.AccessibleJProgressBar()
Method Detail

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Gets the state set of this object.

Overrides:
getAccessibleStateSet in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleState containing the current state of the object
See Also:
AccessibleState

getAccessibleRole

public AccessibleRole getAccessibleRole()
Gets the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleValue

public AccessibleValue getAccessibleValue()
Gets the AccessibleValue associated with this object. In the implementation of the Java Accessibility API for this class, returns this object, which is responsible for implementing the AccessibleValue interface on behalf of itself.

Overrides:
getAccessibleValue in class AccessibleContext
Returns:
this object
See Also:
AccessibleValue

getCurrentAccessibleValue

public Number getCurrentAccessibleValue()
Gets the accessible value of this object.

Specified by:
getCurrentAccessibleValue in interface AccessibleValue
Returns:
the current value of this object
See Also:
AccessibleValue.setCurrentAccessibleValue(java.lang.Number)

setCurrentAccessibleValue

public boolean setCurrentAccessibleValue(Number n)
Sets the value of this object as a Number.

Specified by:
setCurrentAccessibleValue in interface AccessibleValue
Returns:
true if the value was set
See Also:
AccessibleValue.getCurrentAccessibleValue()

getMinimumAccessibleValue

public Number getMinimumAccessibleValue()
Gets the minimum accessible value of this object.

Specified by:
getMinimumAccessibleValue in interface AccessibleValue
Returns:
the minimum value of this object
See Also:
AccessibleValue.getMaximumAccessibleValue()

getMaximumAccessibleValue

public Number getMaximumAccessibleValue()
Gets the maximum accessible value of this object.

Specified by:
getMaximumAccessibleValue in interface AccessibleValue
Returns:
the maximum value of this object
See Also:
AccessibleValue.getMinimumAccessibleValue()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JRadioButton

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JRadioButton

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.AbstractButton
                    extended by  javax.swing.JToggleButton
                        extended by  javax.swing.JRadioButton
All Implemented Interfaces:
ImageObserver, ItemSelectable, MenuContainer, Serializable, Accessible, SwingConstants
public class JRadioButton
extends JToggleButton
implements Accessible

An implementation of a radio button -- an item that can be selected or deselected, and which displays its state to the user. Used with a ButtonGroup object to create a group of buttons in which only one button at a time can be selected. (Create a ButtonGroup object and use its add method to include the JRadioButton objects in the group.)

Note: The ButtonGroup object is a logical grouping -- not a physical grouping. Tocreate a button panel, you should still create a JPanel or similar container-object and add a Border to it to set it off from surrounding components.

Buttons can be configured, and to some degree controlled, by Actions. Using an Action with a button has many benefits beyond directly configuring a button. Refer to Swing Components Supporting Action for more details, and you can find more information in How to Use Actions, a section in The Java Tutorial.

See How to Use Buttons, Check Boxes, and Radio Buttons in The Java Tutorial for further documentation.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
ButtonGroup, JCheckBox

Nested Class Summary
protected  class JRadioButton.AccessibleJRadioButton
This class implements accessibility support for the JRadioButton class.
Nested classes/interfaces inherited from class javax.swing.JToggleButton
JToggleButton.AccessibleJToggleButton, JToggleButton.ToggleButtonModel
Nested classes/interfaces inherited from class javax.swing.AbstractButton
AbstractButton.AccessibleAbstractButton, AbstractButton.ButtonChangeListener
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.AbstractButton
actionListener, BORDER_PAINTED_CHANGED_PROPERTY, changeEvent, changeListener, CONTENT_AREA_FILLED_CHANGED_PROPERTY, DISABLED_ICON_CHANGED_PROPERTY, DISABLED_SELECTED_ICON_CHANGED_PROPERTY, FOCUS_PAINTED_CHANGED_PROPERTY, HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY, HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY, ICON_CHANGED_PROPERTY, itemListener, MARGIN_CHANGED_PROPERTY, MNEMONIC_CHANGED_PROPERTY, model, MODEL_CHANGED_PROPERTY, PRESSED_ICON_CHANGED_PROPERTY, ROLLOVER_ENABLED_CHANGED_PROPERTY, ROLLOVER_ICON_CHANGED_PROPERTY, ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY, SELECTED_ICON_CHANGED_PROPERTY, TEXT_CHANGED_PROPERTY, VERTICAL_ALIGNMENT_CHANGED_PROPERTY, VERTICAL_TEXT_POSITION_CHANGED_PROPERTY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JRadioButton()
Creates an initially unselected radio button with no set text.
JRadioButton(Action a)
Creates a radiobutton where properties are taken from the Action supplied.
JRadioButton(Icon icon)
Creates an initially unselected radio button with the specified image but no text.
JRadioButton(Icon icon, boolean selected)
Creates a radio button with the specified image and selection state, but no text.
JRadioButton(String text)
Creates an unselected radio button with the specified text.
JRadioButton(String text, boolean selected)
Creates a radio button with the specified text and selection state.
JRadioButton(String text, Icon icon)
Creates a radio button that has the specified text and image, and that is initially unselected.
JRadioButton(String text, Icon icon, boolean selected)
Creates a radio button that has the specified text, image, and selection state.
Method Summary
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JRadioButton.
String | getUIClassID() Returns the name of the L&F class that renders this component.
protected String | paramString() Returns a string representation of this JRadioButton.
void | updateUI() Resets the UI property to a value from the current look and feel.
Methods inherited from class javax.swing.AbstractButton
actionPropertyChanged, addActionListener, addChangeListener, addImpl, addItemListener, checkHorizontalKey, checkVerticalKey, configurePropertiesFromAction, createActionListener, createActionPropertyChangeListener, createChangeListener, createItemListener, doClick, doClick, fireActionPerformed, fireItemStateChanged, fireStateChanged, getAction, getActionCommand, getActionListeners, getChangeListeners, getDisabledIcon, getDisabledSelectedIcon, getDisplayedMnemonicIndex, getHideActionText, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getItemListeners, getLabel, getMargin, getMnemonic, getModel, getMultiClickThreshhold, getPressedIcon, getRolloverIcon, getRolloverSelectedIcon, getSelectedIcon, getSelectedObjects, getText, getUI, getVerticalAlignment, getVerticalTextPosition, imageUpdate, init, isBorderPainted, isContentAreaFilled, isFocusPainted, isRolloverEnabled, isSelected, paintBorder, removeActionListener, removeChangeListener, removeItemListener, removeNotify, setAction, setActionCommand, setBorderPainted, setContentAreaFilled, setDisabledIcon, setDisabledSelectedIcon, setDisplayedMnemonicIndex, setEnabled, setFocusPainted, setHideActionText, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabel, setLayout, setMargin, setMnemonic, setMnemonic, setModel, setMultiClickThreshhold, setPressedIcon, setRolloverEnabled, setRolloverIcon, setRolloverSelectedIcon, setSelected, setSelectedIcon, setText, setUI, setVerticalAlignment, setVerticalTextPosition
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JRadioButton

public JRadioButton()
Creates an initially unselected radio button with no set text.

JRadioButton

public JRadioButton(Icon icon)
Creates an initially unselected radio button with the specified image but no text.

Parameters:
icon - the image that the button should display

JRadioButton

public JRadioButton(Action a)
Creates a radiobutton where properties are taken from the Action supplied.

Since:
1.3

JRadioButton

public JRadioButton(Icon icon,
                    boolean selected)
Creates a radio button with the specified image and selection state, but no text.

Parameters:
icon - the image that the button should display
selected - if true, the button is initially selected; otherwise, the button is initially unselected

JRadioButton

public JRadioButton(String text)
Creates an unselected radio button with the specified text.

Parameters:
text - the string displayed on the radio button

JRadioButton

public JRadioButton(String text,
                    boolean selected)
Creates a radio button with the specified text and selection state.

Parameters:
text - the string displayed on the radio button
selected - if true, the button is initially selected; otherwise, the button is initially unselected

JRadioButton

public JRadioButton(String text,
                    Icon icon)
Creates a radio button that has the specified text and image, and that is initially unselected.

Parameters:
text - the string displayed on the radio button
icon - the image that the button should display

JRadioButton

public JRadioButton(String text,
                    Icon icon,
                    boolean selected)
Creates a radio button that has the specified text, image, and selection state.

Parameters:
text - the string displayed on the radio button
icon - the image that the button should display
Method Detail

updateUI

public void updateUI()
Resets the UI property to a value from the current look and feel.

Overrides:
updateUI in class JToggleButton
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JToggleButton
Returns:
String "RadioButtonUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

paramString

protected String paramString()
Returns a string representation of this JRadioButton. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JToggleButton
Returns:
a string representation of this JRadioButton.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JRadioButton. For JRadioButtons, the AccessibleContext takes the form of an AccessibleJRadioButton. A new AccessibleJRadioButton instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JToggleButton
Returns:
an AccessibleJRadioButton that serves as the AccessibleContext of this JRadioButton
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JRadioButton.AccessibleJRadioButton

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JRadioButton.AccessibleJRadioButton

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.AbstractButton.AccessibleAbstractButton
                        extended by  javax.swing.JToggleButton.AccessibleJToggleButton
                            extended by  javax.swing.JRadioButton.AccessibleJRadioButton
All Implemented Interfaces:
ItemListener, Serializable, EventListener, AccessibleAction, AccessibleComponent, AccessibleExtendedComponent, AccessibleText, AccessibleValue
Enclosing class:
JRadioButton
protected class JRadioButton.AccessibleJRadioButton
extends JToggleButton.AccessibleJToggleButton

This class implements accessibility support for the JRadioButton class. It provides an implementation of the Java Accessibility API appropriate to radio button user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Constructor Summary
protected JRadioButton.AccessibleJRadioButton()
Method Summary
 AccessibleRole getAccessibleRole()
Get the role of this object.
Methods inherited from class javax.swing.JToggleButton.AccessibleJToggleButton
itemStateChanged
Methods inherited from class javax.swing.AbstractButton.AccessibleAbstractButton
doAccessibleAction, getAccessibleAction, getAccessibleActionCount, getAccessibleActionDescription, getAccessibleIcon, getAccessibleKeyBinding, getAccessibleName, getAccessibleRelationSet, getAccessibleStateSet, getAccessibleText, getAccessibleValue, getAfterIndex, getAtIndex, getBeforeIndex, getCaretPosition, getCharacterAttribute, getCharacterBounds, getCharCount, getCurrentAccessibleValue, getIndexAtPoint, getMaximumAccessibleValue, getMinimumAccessibleValue, getSelectedText, getSelectionEnd, getSelectionStart, getTitledBorderText, getToolTipText, setCurrentAccessibleValue
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getBorderTitle, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleEditableText, getAccessibleSelection, getAccessibleTable, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JRadioButton.AccessibleJRadioButton

protected JRadioButton.AccessibleJRadioButton()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JToggleButton.AccessibleJToggleButton
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JRadioButtonMenuItem

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JRadioButtonMenuItem

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.AbstractButton
                    extended by  javax.swing.JMenuItem
                        extended by  javax.swing.JRadioButtonMenuItem
All Implemented Interfaces:
ImageObserver, ItemSelectable, MenuContainer, Serializable, Accessible, MenuElement, SwingConstants
public class JRadioButtonMenuItem
extends JMenuItem
implements Accessible

An implementation of a radio button menu item. A JRadioButtonMenuItem is a menu item that is part of a group of menu items in which only one item in the group can be selected. The selected item displays its selected state. Selecting it causes any other selected item to switch to the unselected state. To control the selected state of a group of radio button menu items, use a ButtonGroup object.

Menu items can be configured, and to some degree controlled, by Actions. Using an Action with a menu item has many benefits beyond directly configuring a menu item. Refer to Swing Components Supporting Action for more details, and you can find more information in How to Use Actions, a section in The Java Tutorial.

For further documentation and examples see How to Use Menus, a section in The Java Tutorial.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
ButtonGroup

Nested Class Summary
protected  class JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem
This class implements accessibility support for the JRadioButtonMenuItem class.
Nested classes/interfaces inherited from class javax.swing.JMenuItem
JMenuItem.AccessibleJMenuItem
Nested classes/interfaces inherited from class javax.swing.AbstractButton
AbstractButton.AccessibleAbstractButton, AbstractButton.ButtonChangeListener
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.AbstractButton
actionListener, BORDER_PAINTED_CHANGED_PROPERTY, changeEvent, changeListener, CONTENT_AREA_FILLED_CHANGED_PROPERTY, DISABLED_ICON_CHANGED_PROPERTY, DISABLED_SELECTED_ICON_CHANGED_PROPERTY, FOCUS_PAINTED_CHANGED_PROPERTY, HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY, HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY, ICON_CHANGED_PROPERTY, itemListener, MARGIN_CHANGED_PROPERTY, MNEMONIC_CHANGED_PROPERTY, model, MODEL_CHANGED_PROPERTY, PRESSED_ICON_CHANGED_PROPERTY, ROLLOVER_ENABLED_CHANGED_PROPERTY, ROLLOVER_ICON_CHANGED_PROPERTY, ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY, SELECTED_ICON_CHANGED_PROPERTY, TEXT_CHANGED_PROPERTY, VERTICAL_ALIGNMENT_CHANGED_PROPERTY, VERTICAL_TEXT_POSITION_CHANGED_PROPERTY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JRadioButtonMenuItem()
Creates a JRadioButtonMenuItem with no set text or icon.
JRadioButtonMenuItem(Action a)
Creates a radio button menu item whose properties are taken from the Action supplied.
JRadioButtonMenuItem(Icon icon)
Creates a JRadioButtonMenuItem with an icon.
JRadioButtonMenuItem(Icon icon, boolean selected)
Creates a radio button menu item with the specified image and selection state, but no text.
JRadioButtonMenuItem(String text)
Creates a JRadioButtonMenuItem with text.
JRadioButtonMenuItem(String text, boolean selected)
Creates a radio button menu item with the specified text and selection state.
JRadioButtonMenuItem(String text, Icon icon)
Creates a radio button menu item with the specified text and Icon.
JRadioButtonMenuItem(String text, Icon icon, boolean selected)
Creates a radio button menu item that has the specified text, image, and selection state.
Method Summary
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JRadioButtonMenuItem.
String | getUIClassID() Returns the name of the L&F class that renders this component.
protected String | paramString() Returns a string representation of this JRadioButtonMenuItem.
Methods inherited from class javax.swing.JMenuItem
actionPropertyChanged, addMenuDragMouseListener, addMenuKeyListener, configurePropertiesFromAction, fireMenuDragMouseDragged, fireMenuDragMouseEntered, fireMenuDragMouseExited, fireMenuDragMouseReleased, fireMenuKeyPressed, fireMenuKeyReleased, fireMenuKeyTyped, getAccelerator, getComponent, getMenuDragMouseListeners, getMenuKeyListeners, getSubElements, init, isArmed, menuSelectionChanged, processKeyEvent, processMenuDragMouseEvent, processMenuKeyEvent, processMouseEvent, removeMenuDragMouseListener, removeMenuKeyListener, setAccelerator, setArmed, setEnabled, setModel, setUI, updateUI
Methods inherited from class javax.swing.AbstractButton
addActionListener, addChangeListener, addImpl, addItemListener, checkHorizontalKey, checkVerticalKey, createActionListener, createActionPropertyChangeListener, createChangeListener, createItemListener, doClick, doClick, fireActionPerformed, fireItemStateChanged, fireStateChanged, getAction, getActionCommand, getActionListeners, getChangeListeners, getDisabledIcon, getDisabledSelectedIcon, getDisplayedMnemonicIndex, getHideActionText, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getItemListeners, getLabel, getMargin, getMnemonic, getModel, getMultiClickThreshhold, getPressedIcon, getRolloverIcon, getRolloverSelectedIcon, getSelectedIcon, getSelectedObjects, getText, getUI, getVerticalAlignment, getVerticalTextPosition, imageUpdate, isBorderPainted, isContentAreaFilled, isFocusPainted, isRolloverEnabled, isSelected, paintBorder, removeActionListener, removeChangeListener, removeItemListener, removeNotify, setAction, setActionCommand, setBorderPainted, setContentAreaFilled, setDisabledIcon, setDisabledSelectedIcon, setDisplayedMnemonicIndex, setFocusPainted, setHideActionText, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabel, setLayout, setMargin, setMnemonic, setMnemonic, setMultiClickThreshhold, setPressedIcon, setRolloverEnabled, setRolloverIcon, setRolloverSelectedIcon, setSelected, setSelectedIcon, setText, setUI, setVerticalAlignment, setVerticalTextPosition
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JRadioButtonMenuItem

public JRadioButtonMenuItem()
Creates a JRadioButtonMenuItem with no set text or icon.

JRadioButtonMenuItem

public JRadioButtonMenuItem(Icon icon)
Creates a JRadioButtonMenuItem with an icon.

Parameters:
icon - the Icon to display on the JRadioButtonMenuItem

JRadioButtonMenuItem

public JRadioButtonMenuItem(String text)
Creates a JRadioButtonMenuItem with text.

Parameters:
text - the text of the JRadioButtonMenuItem

JRadioButtonMenuItem

public JRadioButtonMenuItem(Action a)
Creates a radio button menu item whose properties are taken from the Action supplied.

Parameters:
a - the Action on which to base the radio button menu item
Since:
1.3

JRadioButtonMenuItem

public JRadioButtonMenuItem(String text,
                            Icon icon)
Creates a radio button menu item with the specified text and Icon.

Parameters:
text - the text of the JRadioButtonMenuItem
icon - the icon to display on the JRadioButtonMenuItem

JRadioButtonMenuItem

public JRadioButtonMenuItem(String text,
                            boolean selected)
Creates a radio button menu item with the specified text and selection state.

Parameters:
text - the text of the CheckBoxMenuItem
selected - the selected state of the CheckBoxMenuItem

JRadioButtonMenuItem

public JRadioButtonMenuItem(Icon icon,
                            boolean selected)
Creates a radio button menu item with the specified image and selection state, but no text.

Parameters:
icon - the image that the button should display
selected - if true, the button is initially selected; otherwise, the button is initially unselected

JRadioButtonMenuItem

public JRadioButtonMenuItem(String text,
                            Icon icon,
                            boolean selected)
Creates a radio button menu item that has the specified text, image, and selection state. All other constructors defer to this one.

Parameters:
text - the string displayed on the radio button
icon - the image that the button should display
Method Detail

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JMenuItem
Returns:
the string "RadioButtonMenuItemUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

paramString

protected String paramString()
Returns a string representation of this JRadioButtonMenuItem. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JMenuItem
Returns:
a string representation of this JRadioButtonMenuItem

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JRadioButtonMenuItem. For JRadioButtonMenuItems, the AccessibleContext takes the form of an AccessibleJRadioButtonMenuItem. A new AccessibleJRadioButtonMenuItem instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JMenuItem
Returns:
an AccessibleJRadioButtonMenuItem that serves as the AccessibleContext of this JRadioButtonMenuItem
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.AbstractButton.AccessibleAbstractButton
                        extended by  javax.swing.JMenuItem.AccessibleJMenuItem
                            extended by  javax.swing.JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem
All Implemented Interfaces:
Serializable, EventListener, AccessibleAction, AccessibleComponent, AccessibleExtendedComponent, AccessibleText, AccessibleValue, ChangeListener
Enclosing class:
JRadioButtonMenuItem
protected class JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem
extends JMenuItem.AccessibleJMenuItem

This class implements accessibility support for the JRadioButtonMenuItem class. It provides an implementation of the Java Accessibility API appropriate to JRadioButtonMenuItem user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Constructor Summary
protected JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem()
Method Summary
 AccessibleRole getAccessibleRole()
Get the role of this object.
Methods inherited from class javax.swing.JMenuItem.AccessibleJMenuItem
stateChanged
Methods inherited from class javax.swing.AbstractButton.AccessibleAbstractButton
doAccessibleAction, getAccessibleAction, getAccessibleActionCount, getAccessibleActionDescription, getAccessibleIcon, getAccessibleKeyBinding, getAccessibleName, getAccessibleRelationSet, getAccessibleStateSet, getAccessibleText, getAccessibleValue, getAfterIndex, getAtIndex, getBeforeIndex, getCaretPosition, getCharacterAttribute, getCharacterBounds, getCharCount, getCurrentAccessibleValue, getIndexAtPoint, getMaximumAccessibleValue, getMinimumAccessibleValue, getSelectedText, getSelectionEnd, getSelectionStart, getTitledBorderText, getToolTipText, setCurrentAccessibleValue
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getBorderTitle, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleEditableText, getAccessibleSelection, getAccessibleTable, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem

protected JRadioButtonMenuItem.AccessibleJRadioButtonMenuItem()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JMenuItem.AccessibleJMenuItem
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JRootPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JRootPane

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JRootPane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public class JRootPane
extends JComponent
implements Accessible

A lightweight container used behind the scenes by JFrame, JDialog, JWindow, JApplet, and JInternalFrame. For task-oriented information on functionality provided by root panes see How to Use Root Panes, a section in The Java Tutorial.

The following image shows the relationships between the classes that use root panes.

The following text describes this graphic.

The "heavyweight" components (those that delegate to a peer, or native component on the host system) are shown with a darker, heavier box. The four heavyweight JFC/Swing containers (JFrame, JDialog, JWindow, and JApplet) are shown in relation to the AWT classes they extend. These four components are the only heavyweight containers in the Swing library. The lightweight container JInternalFrame is also shown. All five of these JFC/Swing containers implement the RootPaneContainer interface, and they all delegate their operations to a JRootPane (shown with a little "handle" on top).
Note: The JComponent method getRootPane can be used to obtain the JRootPane that contains a given component.
The following text describes this graphic.
The diagram at right shows the structure of a JRootPane. A JRootpane is made up of a glassPane, an optional menuBar, and a contentPane. (The JLayeredPane manages the menuBar and the contentPane.) The glassPane sits over the top of everything, where it is in a position to intercept mouse movements. Since the glassPane (like the contentPane) can be an arbitrary component, it is also possible to set up the glassPane for drawing. Lines and images on the glassPane can then range over the frames underneath without being limited by their boundaries.

Although the menuBar component is optional, the layeredPane, contentPane, and glassPane always exist. Attempting to set them to null generates an exception.

To add components to the JRootPane (other than the optional menu bar), you add the object to the contentPane of the JRootPane, like this:

       rootPane.getContentPane().add(child);
The same principle holds true for setting layout managers, removing components, listing children, etc. All these methods are invoked on the contentPane instead of on the JRootPane.
Note: The default layout manager for the contentPane is a BorderLayout manager. However, the JRootPane uses a custom LayoutManager. So, when you want to change the layout manager for the components you added to a JRootPane, be sure to use code like this:
    rootPane.getContentPane().setLayout(new BoxLayout());
If a JMenuBar component is set on the JRootPane, it is positioned along the upper edge of the frame. The contentPane is adjusted in location and size to fill the remaining area. (The JMenuBar and the contentPane are added to the layeredPane component at the JLayeredPane.FRAME_CONTENT_LAYER layer.)

The layeredPane is the parent of all children in the JRootPane -- both as the direct parent of the menu and the grandparent of all components added to the contentPane. It is an instance of JLayeredPane, which provides the ability to add components at several layers. This capability is very useful when working with menu popups, dialog boxes, and dragging -- situations in which you need to place a component on top of all other components in the pane.

The glassPane sits on top of all other components in the JRootPane. That provides a convenient place to draw above all other components, and makes it possible to intercept mouse events, which is useful both for dragging and for drawing. Developers can use setVisible on the glassPane to control when the glassPane displays over the other children. By default the glassPane is not visible.

The custom LayoutManager used by JRootPane ensures that:

  1. The glassPane fills the entire viewable area of the JRootPane (bounds - insets).
  2. The layeredPane fills the entire viewable area of the JRootPane. (bounds - insets)
  3. The menuBar is positioned at the upper edge of the layeredPane.
  4. The contentPane fills the entire viewable area, minus the menuBar, if present.
Any other views in the JRootPane view hierarchy are ignored.

If you replace the LayoutManager of the JRootPane, you are responsible for managing all of these views. So ordinarily you will want to be sure that you change the layout manager for the contentPane rather than for the JRootPane itself!

The painting architecture of Swing requires an opaque JComponent to exist in the containment hieararchy above all other components. This is typically provided by way of the content pane. If you replace the content pane, it is recommended that you make the content pane opaque by way of setOpaque(true). Additionally, if the content pane overrides paintComponent, it will need to completely fill in the background in an opaque color in paintComponent.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JLayeredPane, JMenuBar, JWindow, JFrame, JDialog, JApplet, JInternalFrame, JComponent, BoxLayout, Mixing Heavy and Light Components

Nested Class Summary
protected class | JRootPane.AccessibleJRootPane This class implements accessibility support for the JRootPane class.
protected class | JRootPane.RootLayout A custom layout manager that is responsible for the layout of layeredPane, glassPane, and menuBar.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
static int | COLOR_CHOOSER_DIALOG Constant used for the windowDecorationStyle property.
protected Container | contentPane The content pane.
protected JButton | defaultButton The button that gets activated when the pane has the focus and a UI-specific action like pressing the Enter key occurs.
protected javax.swing.JRootPane.DefaultAction | defaultPressAction Deprecated. As of Java 2 platform v1.3.
protected javax.swing.JRootPane.DefaultAction | defaultReleaseAction Deprecated. As of Java 2 platform v1.3.
static int | ERROR_DIALOG Constant used for the windowDecorationStyle property.
static int | FILE_CHOOSER_DIALOG Constant used for the windowDecorationStyle property.
static int | FRAME Constant used for the windowDecorationStyle property.
protected Component | glassPane The glass pane that overlays the menu bar and content pane, so it can intercept mouse movements and such.
static int | INFORMATION_DIALOG Constant used for the windowDecorationStyle property.
protected JLayeredPane | layeredPane The layered pane that manages the menu bar and content pane.
protected JMenuBar | menuBar The menu bar.
static int | NONE Constant used for the windowDecorationStyle property.
static int | PLAIN_DIALOG Constant used for the windowDecorationStyle property.
static int | QUESTION_DIALOG Constant used for the windowDecorationStyle property.
static int | WARNING_DIALOG Constant used for the windowDecorationStyle property.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JRootPane()
Creates a JRootPane, setting up its glassPane, layeredPane, and contentPane.
Method Summary
protected  void addImpl(Component comp, Object constraints, int index)
Overridden to enforce the position of the glass component as the zero child.
 void addNotify()
Register ourselves with the SystemEventQueueUtils as a new root pane.
protected  Container createContentPane()
Called by the constructor methods to create the default contentPane.
protected  Component createGlassPane()
Called by the constructor methods to create the default glassPane.
protected  JLayeredPane createLayeredPane()
Called by the constructor methods to create the default layeredPane.
protected  LayoutManager createRootLayout()
Called by the constructor methods to create the default layoutManager.
 AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JRootPane.
 Container getContentPane()
Returns the content pane -- the container that holds the components parented by the root pane.
 JButton getDefaultButton()
Returns the value of the defaultButton property.
 Component getGlassPane()
Returns the current glass pane for this JRootPane.
 JMenuBar getJMenuBar()
Returns the menu bar from the layered pane.
 JLayeredPane getLayeredPane()
Gets the layered pane used by the root pane.
 JMenuBar getMenuBar()
Deprecated. As of Swing version 1.0.3 replaced by getJMenuBar().
 RootPaneUI getUI()
Returns the L&F object that renders this component.
 String getUIClassID()
Returns a string that specifies the name of the L&F class that renders this component.
 int getWindowDecorationStyle()
Returns a constant identifying the type of Window decorations the JRootPane is providing.
 boolean isOptimizedDrawingEnabled()
The glassPane and contentPane have the same bounds, which means JRootPane does not tiles its children and this should return false.
 boolean isValidateRoot()
If a descendant of this JRootPane calls revalidate, validate from here on down.
protected  String paramString()
Returns a string representation of this JRootPane.
 void removeNotify()
Unregister ourselves from SystemEventQueueUtils.
 void setContentPane(Container content)
Sets the content pane -- the container that holds the components parented by the root pane.
 void setDefaultButton(JButton defaultButton)
Sets the defaultButton property, which determines the current default button for this JRootPane.
 void setDoubleBuffered(boolean aFlag)
Sets whether this component should use a buffer to paint.
 void setGlassPane(Component glass)
Sets a specified Component to be the glass pane for this root pane.
 void setJMenuBar(JMenuBar menu)
Adds or changes the menu bar used in the layered pane.
 void setLayeredPane(JLayeredPane layered)
Sets the layered pane for the root pane.
 void setMenuBar(JMenuBar menu)
Deprecated. As of Swing version 1.0.3 replaced by setJMenuBar(JMenuBar menu).
 void setUI(RootPaneUI ui)
Sets the L&F object that renders this component.
 void setWindowDecorationStyle(int windowDecorationStyle)
Sets the type of Window decorations (such as borders, widgets for closing a Window, title ...) the JRootPane should provide.
 void updateUI()
Resets the UI property to a value from the current look and feel.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

NONE

public static final int NONE
Constant used for the windowDecorationStyle property. Indicates that the JRootPane should not provide any sort of Window decorations.

Since:
1.4
See Also:
Constant Field Values

FRAME

public static final int FRAME
Constant used for the windowDecorationStyle property. Indicates that the JRootPane should provide decorations appropriate for a Frame.

Since:
1.4
See Also:
Constant Field Values

PLAIN_DIALOG

public static final int PLAIN_DIALOG
Constant used for the windowDecorationStyle property. Indicates that the JRootPane should provide decorations appropriate for a Dialog.

Since:
1.4
See Also:
Constant Field Values

INFORMATION_DIALOG

public static final int INFORMATION_DIALOG
Constant used for the windowDecorationStyle property. Indicates that the JRootPane should provide decorations appropriate for a Dialog used to display an informational message.

Since:
1.4
See Also:
Constant Field Values

ERROR_DIALOG

public static final int ERROR_DIALOG
Constant used for the windowDecorationStyle property. Indicates that the JRootPane should provide decorations appropriate for a Dialog used to display an error message.

Since:
1.4
See Also:
Constant Field Values

COLOR_CHOOSER_DIALOG

public static final int COLOR_CHOOSER_DIALOG
Constant used for the windowDecorationStyle property. Indicates that the JRootPane should provide decorations appropriate for a Dialog used to display a JColorChooser.

Since:
1.4
See Also:
Constant Field Values

FILE_CHOOSER_DIALOG

public static final int FILE_CHOOSER_DIALOG
Constant used for the windowDecorationStyle property. Indicates that the JRootPane should provide decorations appropriate for a Dialog used to display a JFileChooser.

Since:
1.4
See Also:
Constant Field Values

QUESTION_DIALOG

public static final int QUESTION_DIALOG
Constant used for the windowDecorationStyle property. Indicates that the JRootPane should provide decorations appropriate for a Dialog used to present a question to the user.

Since:
1.4
See Also:
Constant Field Values

WARNING_DIALOG

public static final int WARNING_DIALOG
Constant used for the windowDecorationStyle property. Indicates that the JRootPane should provide decorations appropriate for a Dialog used to display a warning message.

Since:
1.4
See Also:
Constant Field Values

menuBar

protected JMenuBar menuBar
The menu bar.

contentPane

protected Container contentPane
The content pane.

layeredPane

protected JLayeredPane layeredPane
The layered pane that manages the menu bar and content pane.

glassPane

protected Component glassPane
The glass pane that overlays the menu bar and content pane, so it can intercept mouse movements and such.

defaultButton

protected JButton defaultButton
The button that gets activated when the pane has the focus and a UI-specific action like pressing the Enter key occurs.

defaultPressAction

@Deprecated
protected javax.swing.JRootPane.DefaultAction defaultPressAction
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this unusable field is no longer used. To override the default button you should replace the Action in the JRootPane's ActionMap. Please refer to the key bindings specification for further details.

See Also:
defaultButton

defaultReleaseAction

@Deprecated
protected javax.swing.JRootPane.DefaultAction defaultReleaseAction
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this unusable field is no longer used. To override the default button you should replace the Action in the JRootPane's ActionMap. Please refer to the key bindings specification for further details.

See Also:
defaultButton
Constructor Detail

JRootPane

public JRootPane()
Creates a JRootPane, setting up its glassPane, layeredPane, and contentPane.

Method Detail

setDoubleBuffered

public void setDoubleBuffered(boolean aFlag)
Sets whether this component should use a buffer to paint. If set to true, all the drawing from this component will be done in an offscreen painting buffer. The offscreen painting buffer will the be copied onto the screen. If a Component is buffered and one of its ancestor is also buffered, the ancestor buffer will be used.

Overrides:
setDoubleBuffered in class JComponent
Parameters:
aFlag - if true, set this component to be double buffered
Since:
1.6

getWindowDecorationStyle

public int getWindowDecorationStyle()
Returns a constant identifying the type of Window decorations the JRootPane is providing.

Returns:
One of NONE, FRAME, PLAIN_DIALOG, INFORMATION_DIALOG, ERROR_DIALOG, COLOR_CHOOSER_DIALOG, FILE_CHOOSER_DIALOG, QUESTION_DIALOG or WARNING_DIALOG.
Since:
1.4
See Also:
setWindowDecorationStyle(int)

setWindowDecorationStyle

public void setWindowDecorationStyle(int windowDecorationStyle)
Sets the type of Window decorations (such as borders, widgets for closing a Window, title ...) the JRootPane should provide. The default is to provide no Window decorations (NONE).

This is only a hint, and some look and feels may not support this. This is a bound property.

Parameters:
windowDecorationStyle - Constant identifying Window decorations to provide.
Throws:
IllegalArgumentException - if style is not one of: NONE, FRAME, PLAIN_DIALOG, INFORMATION_DIALOG, ERROR_DIALOG, COLOR_CHOOSER_DIALOG, FILE_CHOOSER_DIALOG, QUESTION_DIALOG, or WARNING_DIALOG.
Since:
1.4
See Also:
JDialog.setDefaultLookAndFeelDecorated(boolean),
JFrame.setDefaultLookAndFeelDecorated(boolean),
LookAndFeel.getSupportsWindowDecorations()

getUI

public RootPaneUI getUI()
Returns the L&F object that renders this component.

Returns:
LabelUI object
Since:
1.3

setUI

public void setUI(RootPaneUI ui)
Sets the L&F object that renders this component.

Parameters:
ui - the LabelUI L&F object
Since:
1.3
See Also:
UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Resets the UI property to a value from the current look and feel.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns a string that specifies the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "RootPaneUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

createLayeredPane

protected JLayeredPane createLayeredPane()
Called by the constructor methods to create the default layeredPane. Bt default it creates a new JLayeredPane.

Returns:
the default layeredPane

createContentPane

protected Container createContentPane()
Called by the constructor methods to create the default contentPane. By default this method creates a new JComponent add sets a BorderLayout as its LayoutManager.

Returns:
the default contentPane

createGlassPane

protected Component createGlassPane()
Called by the constructor methods to create the default glassPane. By default this method creates a new JComponent with visibility set to false.

Returns:
the default glassPane

createRootLayout

protected LayoutManager createRootLayout()
Called by the constructor methods to create the default layoutManager.

Returns:
the default layoutManager.

setJMenuBar

public void setJMenuBar(JMenuBar menu)
Adds or changes the menu bar used in the layered pane.

Parameters:
menu - the JMenuBar to add

setMenuBar

@Deprecated
public void setMenuBar(JMenuBar menu)
Deprecated. As of Swing version 1.0.3 replaced by setJMenuBar(JMenuBar menu).

Specifies the menu bar value.

Parameters:
menu - the JMenuBar to add.

getJMenuBar

public JMenuBar getJMenuBar()
Returns the menu bar from the layered pane.

Returns:
the JMenuBar used in the pane

getMenuBar

@Deprecated
public JMenuBar getMenuBar()
Deprecated. As of Swing version 1.0.3 replaced by getJMenuBar().

Returns the menu bar value.

Returns:
the JMenuBar used in the pane

setContentPane

public void setContentPane(Container content)
Sets the content pane -- the container that holds the components parented by the root pane.

Swing's painting architecture requires an opaque JComponent in the containment hiearchy. This is typically provided by the content pane. If you replace the content pane it is recommended you replace it with an opaque JComponent.

Parameters:
content - the Container to use for component-contents
Throws:
IllegalComponentStateException - (a runtime exception) if the content pane parameter is null

getContentPane

public Container getContentPane()
Returns the content pane -- the container that holds the components parented by the root pane.

Returns:
the Container that holds the component-contents

setLayeredPane

public void setLayeredPane(JLayeredPane layered)
Sets the layered pane for the root pane. The layered pane typically holds a content pane and an optional JMenuBar.

Parameters:
layered - the JLayeredPane to use
Throws:
IllegalComponentStateException - (a runtime exception) if the layered pane parameter is null

getLayeredPane

public JLayeredPane getLayeredPane()
Gets the layered pane used by the root pane. The layered pane typically holds a content pane and an optional JMenuBar.

Returns:
the JLayeredPane currently in use

setGlassPane

public void setGlassPane(Component glass)
Sets a specified Component to be the glass pane for this root pane. The glass pane should normally be a lightweight, transparent component, because it will be made visible when ever the root pane needs to grab input events.

The new glass pane's visibility is changed to match that of the current glass pane. An implication of this is that care must be taken when you want to replace the glass pane and make it visible. Either of the following will work:

   root.setGlassPane(newGlassPane);
   newGlassPane.setVisible(true);
or:
   root.getGlassPane().setVisible(true);
   root.setGlassPane(newGlassPane);

Parameters:
glass - the Component to use as the glass pane for this JRootPane
Throws:
NullPointerException - if the glass parameter is null

getGlassPane

public Component getGlassPane()
Returns the current glass pane for this JRootPane.

Returns:
the current glass pane
See Also:
setGlassPane(java.awt.Component)

isValidateRoot

public boolean isValidateRoot()
If a descendant of this JRootPane calls revalidate, validate from here on down.

Deferred requests to layout a component and its descendents again. For example, calls to revalidate, are pushed upwards to either a JRootPane or a JScrollPane because both classes override isValidateRoot to return true.

Overrides:
isValidateRoot in class JComponent
Returns:
true
See Also:
JComponent.isValidateRoot()

isOptimizedDrawingEnabled

public boolean isOptimizedDrawingEnabled()
The glassPane and contentPane have the same bounds, which means JRootPane does not tiles its children and this should return false. On the other hand, the glassPane is normally not visible, and so this can return true if the glassPane isn't visible. Therefore, the return value here depends upon the visiblity of the glassPane.

Overrides:
isOptimizedDrawingEnabled in class JComponent
Returns:
true if this component's children don't overlap

addNotify

public void addNotify()
Register ourselves with the SystemEventQueueUtils as a new root pane.

Overrides:
addNotify in class JComponent
See Also:
JComponent.registerKeyboardAction(java.awt.event.ActionListener, java.lang.String, javax.swing.KeyStroke, int)

removeNotify

public void removeNotify()
Unregister ourselves from SystemEventQueueUtils.

Overrides:
removeNotify in class JComponent
See Also:
addNotify()

setDefaultButton

public void setDefaultButton(JButton defaultButton)
Sets the defaultButton property, which determines the current default button for this JRootPane. The default button is the button which will be activated when a UI-defined activation event (typically the Enter key) occurs in the root pane regardless of whether or not the button has keyboard focus (unless there is another component within the root pane which consumes the activation event, such as a JTextPane). For default activation to work, the button must be an enabled descendent of the root pane when activation occurs. To remove a default button from this root pane, set this property to null.

Parameters:
defaultButton - the JButton which is to be the default button
See Also:
JButton.isDefaultButton()

getDefaultButton

public JButton getDefaultButton()
Returns the value of the defaultButton property.

Returns:
the JButton which is currently the default button
See Also:
setDefaultButton(javax.swing.JButton)

addImpl

protected void addImpl(Component comp,
                       Object constraints,
                       int index)
Overridden to enforce the position of the glass component as the zero child.

Overrides:
addImpl in class Container
Parameters:
comp - the component to be enhanced
constraints - the constraints to be respected
index - the index
See Also:
Container.add(Component),
Container.add(Component, int),
Container.add(Component, java.lang.Object),
LayoutManager,
LayoutManager2

paramString

protected String paramString()
Returns a string representation of this JRootPane. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JRootPane.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JRootPane. For root panes, the AccessibleContext takes the form of an AccessibleJRootPane. A new AccessibleJRootPane instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJRootPane that serves as the AccessibleContext of this JRootPane
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JRootPane.AccessibleJRootPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JRootPane.AccessibleJRootPane

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JRootPane.AccessibleJRootPane
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent
Enclosing class:
JRootPane
protected class JRootPane.AccessibleJRootPane
extends JComponent.AccessibleJComponent

This class implements accessibility support for the JRootPane class. It provides an implementation of the Java Accessibility API appropriate to root pane user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JRootPane.AccessibleJRootPane()
Method Summary
Accessible | getAccessibleChild(int i) Returns the specified Accessible child of the object.
int | getAccessibleChildrenCount() Returns the number of accessible children of the object.
AccessibleRole | getAccessibleRole() Get the role of this object.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JRootPane.AccessibleJRootPane

protected JRootPane.AccessibleJRootPane()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleChildrenCount

public int getAccessibleChildrenCount()
Returns the number of accessible children of the object.

Overrides:
getAccessibleChildrenCount in class JComponent.AccessibleJComponent
Returns:
the number of accessible children of the object.

getAccessibleChild

public Accessible getAccessibleChild(int i)
Returns the specified Accessible child of the object. The Accessible children of an Accessible object are zero-based, so the first child of an Accessible child is at index 0, the second child is at index 1, and so on.

Overrides:
getAccessibleChild in class JComponent.AccessibleJComponent
Parameters:
i - zero-based index of child
Returns:
the Accessible child of the object
See Also:
getAccessibleChildrenCount()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JRootPane.RootLayout

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JRootPane.RootLayout

java.lang.Object
    extended by  javax.swing.JRootPane.RootLayout
All Implemented Interfaces:
LayoutManager, LayoutManager2, Serializable
Enclosing class:
JRootPane
protected class JRootPane.RootLayout
extends Object
implements LayoutManager2, Serializable

A custom layout manager that is responsible for the layout of layeredPane, glassPane, and menuBar.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
protected JRootPane.RootLayout()
Method Summary
void | addLayoutComponent(Component comp, Object constraints) Adds the specified component to the layout, using the specified constraint object.
void | addLayoutComponent(String name, Component comp) If the layout manager uses a per-component string, adds the component comp to the layout, associating it with the string specified by name.
float | getLayoutAlignmentX(Container target) Returns the alignment along the x axis.
float | getLayoutAlignmentY(Container target) Returns the alignment along the y axis.
void | invalidateLayout(Container target) Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.
void | layoutContainer(Container parent) Instructs the layout manager to perform the layout for the specified container.
Dimension | maximumLayoutSize(Container target) Returns the maximum amount of space the layout can use.
Dimension | minimumLayoutSize(Container parent) Returns the minimum amount of space the layout needs.
Dimension | preferredLayoutSize(Container parent) Returns the amount of space the layout would like to have.
void | removeLayoutComponent(Component comp) Removes the specified component from the layout.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JRootPane.RootLayout

protected JRootPane.RootLayout()
Method Detail

preferredLayoutSize

public Dimension preferredLayoutSize(Container parent)
Returns the amount of space the layout would like to have.

Specified by:
preferredLayoutSize in interface LayoutManager
Parameters:
parent - the Container for which this layout manager is being used
Returns:
a Dimension object containing the layout's preferred size
See Also:
LayoutManager.minimumLayoutSize(java.awt.Container)

minimumLayoutSize

public Dimension minimumLayoutSize(Container parent)
Returns the minimum amount of space the layout needs.

Specified by:
minimumLayoutSize in interface LayoutManager
Parameters:
parent - the Container for which this layout manager is being used
Returns:
a Dimension object containing the layout's minimum size
See Also:
LayoutManager.preferredLayoutSize(java.awt.Container)

maximumLayoutSize

public Dimension maximumLayoutSize(Container target)
Returns the maximum amount of space the layout can use.

Specified by:
maximumLayoutSize in interface LayoutManager2
Parameters:
target - the Container for which this layout manager is being used
Returns:
a Dimension object containing the layout's maximum size
See Also:
Component.getMaximumSize(), LayoutManager

layoutContainer

public void layoutContainer(Container parent)
Instructs the layout manager to perform the layout for the specified container.

Specified by:
layoutContainer in interface LayoutManager
Parameters:
parent - the Container for which this layout manager is being used

addLayoutComponent

public void addLayoutComponent(String name,
                               Component comp)
Description copied from interface: LayoutManager
If the layout manager uses a per-component string, adds the component comp to the layout, associating it with the string specified by name.

Specified by:
addLayoutComponent in interface LayoutManager
Parameters:
name - the string to be associated with the component
comp - the component to be added

removeLayoutComponent

public void removeLayoutComponent(Component comp)
Description copied from interface: LayoutManager
Removes the specified component from the layout.

Specified by:
removeLayoutComponent in interface LayoutManager
Parameters:
comp - the component to be removed

addLayoutComponent

public void addLayoutComponent(Component comp,
                               Object constraints)
Description copied from interface: LayoutManager2
Adds the specified component to the layout, using the specified constraint object.

Specified by:
addLayoutComponent in interface LayoutManager2
Parameters:
comp - the component to be added
constraints - where/how the component is added to the layout.

getLayoutAlignmentX

public float getLayoutAlignmentX(Container target)
Description copied from interface: LayoutManager2
Returns the alignment along the x axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.

Specified by:
getLayoutAlignmentX in interface LayoutManager2

getLayoutAlignmentY

public float getLayoutAlignmentY(Container target)
Description copied from interface: LayoutManager2
Returns the alignment along the y axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.

Specified by:
getLayoutAlignmentY in interface LayoutManager2

invalidateLayout

public void invalidateLayout(Container target)
Description copied from interface: LayoutManager2
Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.

Specified by:
invalidateLayout in interface LayoutManager2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JScrollBar

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JScrollBar

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JScrollBar
All Implemented Interfaces:
Adjustable, ImageObserver, MenuContainer, Serializable, Accessible
Direct Known Subclasses:
JScrollPane.ScrollBar
public class JScrollBar
extends JComponent
implements Adjustable, Accessible

An implementation of a scrollbar. The user positions the knob in the scrollbar to determine the contents of the viewing area. The program typically adjusts the display so that the end of the scrollbar represents the end of the displayable contents, or 100% of the contents. The start of the scrollbar is the beginning of the displayable contents, or 0%. The position of the knob within those bounds then translates to the corresponding percentage of the displayable contents.

Typically, as the position of the knob in the scrollbar changes a corresponding change is made to the position of the JViewport on the underlying view, changing the contents of the JViewport.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JScrollPane

Nested Class Summary
protected  class JScrollBar.AccessibleJScrollBar
This class implements accessibility support for the JScrollBar class.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected int | blockIncrement
protected BoundedRangeModel | model The model that represents the scrollbar's minimum, maximum, extent (aka "visibleAmount") and current value.
protected int | orientation
protected int | unitIncrement
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.Adjustable
HORIZONTAL, NO_ORIENTATION, VERTICAL
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JScrollBar()
Creates a vertical scrollbar with the following initial values:
JScrollBar(int orientation)
Creates a scrollbar with the specified orientation and the following initial values:
JScrollBar(int orientation, int value, int extent, int min, int max)
Creates a scrollbar with the specified orientation, value, extent, minimum, and maximum.
Method Summary
 void addAdjustmentListener(AdjustmentListener l)
Adds an AdjustmentListener.
protected  void fireAdjustmentValueChanged(int id, int type, int value)
Notify listeners that the scrollbar's model has changed.
 AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JScrollBar.
 AdjustmentListener[] getAdjustmentListeners()
Returns an array of all the AdjustmentListeners added to this JScrollBar with addAdjustmentListener().
 int getBlockIncrement()
For backwards compatibility with java.awt.Scrollbar.
 int getBlockIncrement(int direction)
Returns the amount to change the scrollbar's value by, given a block (usually "page") up/down request.
 int getMaximum()
The maximum value of the scrollbar is maximum - extent.
 Dimension getMaximumSize()
The scrollbar is flexible along it's scrolling axis and rigid along the other axis.
 int getMinimum()
Returns the minimum value supported by the scrollbar (usually zero).
 Dimension getMinimumSize()
The scrollbar is flexible along it's scrolling axis and rigid along the other axis.
 BoundedRangeModel getModel()
Returns data model that handles the scrollbar's four fundamental properties: minimum, maximum, value, extent.
 int getOrientation()
Returns the component's orientation (horizontal or vertical).
 ScrollBarUI getUI()
Returns the delegate that implements the look and feel for this component.
 String getUIClassID()
Returns the name of the LookAndFeel class for this component.
 int getUnitIncrement()
For backwards compatibility with java.awt.Scrollbar.
 int getUnitIncrement(int direction)
Returns the amount to change the scrollbar's value by, given a unit up/down request.
 int getValue()
Returns the scrollbar's value.
 boolean getValueIsAdjusting()
True if the scrollbar knob is being dragged.
 int getVisibleAmount()
Returns the scrollbar's extent, aka its "visibleAmount".
protected  String paramString()
Returns a string representation of this JScrollBar.
 void removeAdjustmentListener(AdjustmentListener l)
Removes an AdjustmentEvent listener.
 void setBlockIncrement(int blockIncrement)
Sets the blockIncrement property.
 void setEnabled(boolean x)
Enables the component so that the knob position can be changed.
 void setMaximum(int maximum)
Sets the model's maximum property.
 void setMinimum(int minimum)
Sets the model's minimum property.
 void setModel(BoundedRangeModel newModel)
Sets the model that handles the scrollbar's four fundamental properties: minimum, maximum, value, extent.
 void setOrientation(int orientation)
Set the scrollbar's orientation to either VERTICAL or HORIZONTAL.
 void setUI(ScrollBarUI ui)
Sets the L&F object that renders this component.
 void setUnitIncrement(int unitIncrement)
Sets the unitIncrement property.
 void setValue(int value)
Sets the scrollbar's value.
 void setValueIsAdjusting(boolean b)
Sets the model's valueIsAdjusting property.
 void setValues(int newValue, int newExtent, int newMin, int newMax)
Sets the four BoundedRangeModel properties after forcing the arguments to obey the usual constraints:
 void setVisibleAmount(int extent)
Set the model's extent property.
 void updateUI()
Overrides JComponent.updateUI.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

model

protected BoundedRangeModel model
The model that represents the scrollbar's minimum, maximum, extent (aka "visibleAmount") and current value.

See Also:
setModel(javax.swing.BoundedRangeModel)

orientation

protected int orientation
See Also:
setOrientation(int)

unitIncrement

protected int unitIncrement
See Also:
setUnitIncrement(int)

blockIncrement

protected int blockIncrement
See Also:
setBlockIncrement(int)
Constructor Detail

JScrollBar

public JScrollBar(int orientation,
                  int value,
                  int extent,
                  int min,
                  int max)
Creates a scrollbar with the specified orientation, value, extent, minimum, and maximum. The "extent" is the size of the viewable area. It is also known as the "visible amount".

Note: Use setBlockIncrement to set the block increment to a size slightly smaller than the view's extent. That way, when the user jumps the knob to an adjacent position, one or two lines of the original contents remain in view.

Throws:
IllegalArgumentException - if orientation is not one of VERTICAL, HORIZONTAL
See Also:
setOrientation(int), setValue(int), setVisibleAmount(int), setMinimum(int), setMaximum(int)

JScrollBar

public JScrollBar(int orientation)
Creates a scrollbar with the specified orientation and the following initial values:
 minimum = 0
 maximum = 100
 value = 0
 extent = 10

JScrollBar

public JScrollBar()
Creates a vertical scrollbar with the following initial values:
 minimum = 0
 maximum = 100
 value = 0
 extent = 10

Method Detail

setUI

public void setUI(ScrollBarUI ui)
Sets the L&F object that renders this component.

Parameters:
ui - the ScrollBarUI L&F object
Since:
1.4
See Also:
UIDefaults.getUI(javax.swing.JComponent)

getUI

public ScrollBarUI getUI()
Returns the delegate that implements the look and feel for this component.

See Also:
JComponent.setUI(javax.swing.plaf.ComponentUI)

updateUI

public void updateUI()
Overrides JComponent.updateUI.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the LookAndFeel class for this component.

Overrides:
getUIClassID in class JComponent
Returns:
"ScrollBarUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

getOrientation

public int getOrientation()
Returns the component's orientation (horizontal or vertical).

Specified by:
getOrientation in interface Adjustable
Returns:
VERTICAL or HORIZONTAL
See Also:
setOrientation(int), Adjustable.getOrientation()

setOrientation

public void setOrientation(int orientation)
Set the scrollbar's orientation to either VERTICAL or HORIZONTAL.

Throws:
IllegalArgumentException - if orientation is not one of VERTICAL, HORIZONTAL
See Also:
getOrientation()

getModel

public BoundedRangeModel getModel()
Returns data model that handles the scrollbar's four fundamental properties: minimum, maximum, value, extent.

See Also:
setModel(javax.swing.BoundedRangeModel)

setModel

public void setModel(BoundedRangeModel newModel)
Sets the model that handles the scrollbar's four fundamental properties: minimum, maximum, value, extent.

See Also:
getModel()

getUnitIncrement

public int getUnitIncrement(int direction)
Returns the amount to change the scrollbar's value by, given a unit up/down request. A ScrollBarUI implementation typically calls this method when the user clicks on a scrollbar up/down arrow and uses the result to update the scrollbar's value. Subclasses my override this method to compute a value, e.g. the change required to scroll up or down one (variable height) line text or one row in a table.

The JScrollPane component creates scrollbars (by default) that override this method and delegate to the viewports Scrollable view, if it has one. The Scrollable interface provides a more specialized version of this method.

Parameters:
direction - is -1 or 1 for up/down respectively
Returns:
the value of the unitIncrement property
See Also:
setUnitIncrement(int), setValue(int), Scrollable.getScrollableUnitIncrement(java.awt.Rectangle, int, int)

setUnitIncrement

public void setUnitIncrement(int unitIncrement)
Sets the unitIncrement property.

Note, that if the argument is equal to the value of Integer.MIN_VALUE, the most look and feels will not provide the scrolling to the right/down.

Specified by:
setUnitIncrement in interface Adjustable
Parameters:
unitIncrement - the unit increment
See Also:
getUnitIncrement(int)

getBlockIncrement

public int getBlockIncrement(int direction)
Returns the amount to change the scrollbar's value by, given a block (usually "page") up/down request. A ScrollBarUI implementation typically calls this method when the user clicks above or below the scrollbar "knob" to change the value up or down by large amount. Subclasses my override this method to compute a value, e.g. the change required to scroll up or down one paragraph in a text document.

The JScrollPane component creates scrollbars (by default) that override this method and delegate to the viewports Scrollable view, if it has one. The Scrollable interface provides a more specialized version of this method.

Parameters:
direction - is -1 or 1 for up/down respectively
Returns:
the value of the blockIncrement property
See Also:
setBlockIncrement(int), setValue(int), Scrollable.getScrollableBlockIncrement(java.awt.Rectangle, int, int)

setBlockIncrement

public void setBlockIncrement(int blockIncrement)
Sets the blockIncrement property.

Note, that if the argument is equal to the value of Integer.MIN_VALUE, the most look and feels will not provide the scrolling to the right/down.

Specified by:
setBlockIncrement in interface Adjustable
Parameters:
blockIncrement - the block increment
See Also:
getBlockIncrement()

getUnitIncrement

public int getUnitIncrement()
For backwards compatibility with java.awt.Scrollbar.

Specified by:
getUnitIncrement in interface Adjustable
Returns:
the unit value increment for the adjustable object
See Also:
Adjustable.getUnitIncrement(), getUnitIncrement(int)

getBlockIncrement

public int getBlockIncrement()
For backwards compatibility with java.awt.Scrollbar.

Specified by:
getBlockIncrement in interface Adjustable
Returns:
the block value increment for the adjustable object
See Also:
Adjustable.getBlockIncrement(), getBlockIncrement(int)

getValue

public int getValue()
Returns the scrollbar's value.

Specified by:
getValue in interface Adjustable
Returns:
the model's value property
See Also:
setValue(int)

setValue

public void setValue(int value)
Sets the scrollbar's value. This method just forwards the value to the model.

Specified by:
setValue in interface Adjustable
Parameters:
value - the current value, between minimum and maximum - visibleAmount
See Also:
getValue(), BoundedRangeModel.setValue(int)

getVisibleAmount

public int getVisibleAmount()
Returns the scrollbar's extent, aka its "visibleAmount". In many scrollbar look and feel implementations the size of the scrollbar "knob" or "thumb" is proportional to the extent.

Specified by:
getVisibleAmount in interface Adjustable
Returns:
the value of the model's extent property
See Also:
setVisibleAmount(int)

setVisibleAmount

public void setVisibleAmount(int extent)
Set the model's extent property.

Specified by:
setVisibleAmount in interface Adjustable
Parameters:
extent - the length of the indicator
See Also:
getVisibleAmount(), BoundedRangeModel.setExtent(int)

getMinimum

public int getMinimum()
Returns the minimum value supported by the scrollbar (usually zero).

Specified by:
getMinimum in interface Adjustable
Returns:
the value of the model's minimum property
See Also:
setMinimum(int)

setMinimum

public void setMinimum(int minimum)
Sets the model's minimum property.

Specified by:
setMinimum in interface Adjustable
Parameters:
minimum - the minimum value
See Also:
getMinimum(), BoundedRangeModel.setMinimum(int)

getMaximum

public int getMaximum()
The maximum value of the scrollbar is maximum - extent.

Specified by:
getMaximum in interface Adjustable
Returns:
the value of the model's maximum property
See Also:
setMaximum(int)

setMaximum

public void setMaximum(int maximum)
Sets the model's maximum property. Note that the scrollbar's value can only be set to maximum - extent.

Specified by:
setMaximum in interface Adjustable
Parameters:
maximum - the maximum value
See Also:
getMaximum(), BoundedRangeModel.setMaximum(int)

getValueIsAdjusting

public boolean getValueIsAdjusting()
True if the scrollbar knob is being dragged.

Returns:
the value of the model's valueIsAdjusting property
See Also:
setValueIsAdjusting(boolean)

setValueIsAdjusting

public void setValueIsAdjusting(boolean b)
Sets the model's valueIsAdjusting property. Scrollbar look and feel implementations should set this property to true when a knob drag begins, and to false when the drag ends. The scrollbar model will not generate ChangeEvents while valueIsAdjusting is true.

See Also:
getValueIsAdjusting(), BoundedRangeModel.setValueIsAdjusting(boolean)

setValues

public void setValues(int newValue,
                      int newExtent,
                      int newMin,
                      int newMax)
Sets the four BoundedRangeModel properties after forcing the arguments to obey the usual constraints:
 minimum <= value="value" <="value+extent" <="maximum"

See Also:
BoundedRangeModel.setRangeProperties(int, int, int, int, boolean),
setValue(int),
setVisibleAmount(int),
setMinimum(int),
setMaximum(int)

addAdjustmentListener

public void addAdjustmentListener(AdjustmentListener l)
Adds an AdjustmentListener. Adjustment listeners are notified each time the scrollbar's model changes. Adjustment events are provided for backwards compatibility with java.awt.Scrollbar.

Note that the AdjustmentEvents type property will always have a placeholder value of AdjustmentEvent.TRACK because all changes to a BoundedRangeModels value are considered equivalent. To change the value of a BoundedRangeModel one just sets its value property, i.e. model.setValue(123). No information about the origin of the change, e.g. it's a block decrement, is provided. We don't try fabricate the origin of the change here.

Specified by:
addAdjustmentListener in interface Adjustable
Parameters:
l - the AdjustmentLister to add
See Also:
removeAdjustmentListener(java.awt.event.AdjustmentListener), BoundedRangeModel.addChangeListener(javax.swing.event.ChangeListener)

removeAdjustmentListener

public void removeAdjustmentListener(AdjustmentListener l)
Removes an AdjustmentEvent listener.

Specified by:
removeAdjustmentListener in interface Adjustable
Parameters:
l - the AdjustmentLister to remove
See Also:
addAdjustmentListener(java.awt.event.AdjustmentListener)

getAdjustmentListeners

public AdjustmentListener[] getAdjustmentListeners()
Returns an array of all the AdjustmentListeners added to this JScrollBar with addAdjustmentListener().

Returns:
all of the AdjustmentListeners added or an empty array if no listeners have been added
Since:
1.4

fireAdjustmentValueChanged

protected void fireAdjustmentValueChanged(int id,
                                          int type,
                                          int value)
Notify listeners that the scrollbar's model has changed.

See Also:
addAdjustmentListener(java.awt.event.AdjustmentListener), EventListenerList

getMinimumSize

public Dimension getMinimumSize()
The scrollbar is flexible along it's scrolling axis and rigid along the other axis.

Overrides:
getMinimumSize in class JComponent
Returns:
the value of the minimumSize property
See Also:
JComponent.setMinimumSize(java.awt.Dimension), ComponentUI

getMaximumSize

public Dimension getMaximumSize()
The scrollbar is flexible along it's scrolling axis and rigid along the other axis.

Overrides:
getMaximumSize in class JComponent
Returns:
the value of the maximumSize property
See Also:
JComponent.setMaximumSize(java.awt.Dimension), ComponentUI

setEnabled

public void setEnabled(boolean x)
Enables the component so that the knob position can be changed. When the disabled, the knob position cannot be changed.

Overrides:
setEnabled in class JComponent
Parameters:
x - a boolean value, where true enables the component and false disables it
See Also:
Component.isEnabled(), Component.isLightweight()

paramString

protected String paramString()
Returns a string representation of this JScrollBar. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JScrollBar.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JScrollBar. For JScrollBar, the AccessibleContext takes the form of an AccessibleJScrollBar. A new AccessibleJScrollBar instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJScrollBar that serves as the AccessibleContext of this JScrollBar
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JScrollBar.AccessibleJScrollBar

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JScrollBar.AccessibleJScrollBar

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JScrollBar.AccessibleJScrollBar
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent, AccessibleValue
Enclosing class:
JScrollBar
protected class JScrollBar.AccessibleJScrollBar
extends JComponent.AccessibleJComponent
implements AccessibleValue

This class implements accessibility support for the JScrollBar class. It provides an implementation of the Java Accessibility API appropriate to scroll bar user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JScrollBar.AccessibleJScrollBar()
Method Summary
AccessibleRole | getAccessibleRole() Get the role of this object.
AccessibleStateSet | getAccessibleStateSet() Get the state set of this object.
AccessibleValue | getAccessibleValue() Get the AccessibleValue associated with this object.
Number | getCurrentAccessibleValue() Get the accessible value of this object.
Number | getMaximumAccessibleValue() Get the maximum accessible value of this object.
Number | getMinimumAccessibleValue() Get the minimum accessible value of this object.
boolean | setCurrentAccessibleValue(Number n) Set the value of this object as a Number.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JScrollBar.AccessibleJScrollBar

protected JScrollBar.AccessibleJScrollBar()
Method Detail

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Get the state set of this object.

Overrides:
getAccessibleStateSet in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleState containing the current state of the object
See Also:
AccessibleState

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleValue

public AccessibleValue getAccessibleValue()
Get the AccessibleValue associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleValue interface on behalf of itself.

Overrides:
getAccessibleValue in class AccessibleContext
Returns:
this object
See Also:
AccessibleValue

getCurrentAccessibleValue

public Number getCurrentAccessibleValue()
Get the accessible value of this object.

Specified by:
getCurrentAccessibleValue in interface AccessibleValue
Returns:
The current value of this object.
See Also:
AccessibleValue.setCurrentAccessibleValue(java.lang.Number)

setCurrentAccessibleValue

public boolean setCurrentAccessibleValue(Number n)
Set the value of this object as a Number.

Specified by:
setCurrentAccessibleValue in interface AccessibleValue
Returns:
True if the value was set.
See Also:
AccessibleValue.getCurrentAccessibleValue()

getMinimumAccessibleValue

public Number getMinimumAccessibleValue()
Get the minimum accessible value of this object.

Specified by:
getMinimumAccessibleValue in interface AccessibleValue
Returns:
The minimum value of this object.
See Also:
AccessibleValue.getMaximumAccessibleValue()

getMaximumAccessibleValue

public Number getMaximumAccessibleValue()
Get the maximum accessible value of this object.

Specified by:
getMaximumAccessibleValue in interface AccessibleValue
Returns:
The maximum value of this object.
See Also:
AccessibleValue.getMinimumAccessibleValue()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JScrollPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JScrollPane

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JScrollPane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, ScrollPaneConstants
public class JScrollPane
extends JComponent
implements ScrollPaneConstants, Accessible

Provides a scrollable view of a lightweight component. A JScrollPane manages a viewport, optional vertical and horizontal scroll bars, and optional row and column heading viewports. You can find task-oriented documentation of JScrollPane in How to Use Scroll Panes, a section in The Java Tutorial. Note that JScrollPane does not support heavyweight components.

The following text describes this image.

The JViewport provides a window, or "viewport" onto a data source -- for example, a text file. That data source is the "scrollable client" (aka data model) displayed by the JViewport view. A JScrollPane basically consists of JScrollBars, a JViewport, and the wiring between them, as shown in the diagram at right.

In addition to the scroll bars and viewport, a JScrollPane can have a column header and a row header. Each of these is a JViewport object that you specify with setRowHeaderView, and setColumnHeaderView. The column header viewport automatically scrolls left and right, tracking the left-right scrolling of the main viewport. (It never scrolls vertically, however.) The row header acts in a similar fashion.

Where two scroll bars meet, the row header meets the column header, or a scroll bar meets one of the headers, both components stop short of the corner, leaving a rectangular space which is, by default, empty. These spaces can potentially exist in any number of the four corners. In the previous diagram, the top right space is present and identified by the label "corner component".

Any number of these empty spaces can be replaced by using the setCorner method to add a component to a particular corner. (Note: The same component cannot be added to multiple corners.) This is useful if there's some extra decoration or function you'd like to add to the scroll pane. The size of each corner component is entirely determined by the size of the headers and/or scroll bars that surround it.

A corner component will only be visible if there is an empty space in that corner for it to exist in. For example, consider a component set into the top right corner of a scroll pane with a column header. If the scroll pane's vertical scrollbar is not present, perhaps because the view component hasn't grown large enough to require it, then the corner component will not be shown (since there is no empty space in that corner created by the meeting of the header and vertical scroll bar). Forcing the scroll bar to always be shown, using setVerticalScrollBarPolicy(VERTICAL_SCROLLBAR_ALWAYS), will ensure that the space for the corner component always exists.

To add a border around the main viewport, you can use setViewportBorder. (Of course, you can also add a border around the whole scroll pane using setBorder.)

A common operation to want to do is to set the background color that will be used if the main viewport view is smaller than the viewport, or is not opaque. This can be accomplished by setting the background color of the viewport, via scrollPane.getViewport().setBackground(). The reason for setting the color of the viewport and not the scrollpane is that by default JViewport is opaque which, among other things, means it will completely fill in its background using its background color. Therefore when JScrollPane draws its background the viewport will usually draw over it.

By default JScrollPane uses ScrollPaneLayout to handle the layout of its child Components. ScrollPaneLayout determines the size to make the viewport view in one of two ways:

  1. If the view implements Scrollable a combination of getPreferredScrollableViewportSize, getScrollableTracksViewportWidth and getScrollableTracksViewportHeightis used, otherwise
  2. getPreferredSize is used.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JScrollBar,
JViewport,
ScrollPaneLayout,
Scrollable,
Component.getPreferredSize(),
setViewportView(java.awt.Component),
setRowHeaderView(java.awt.Component),
setColumnHeaderView(java.awt.Component),
setCorner(java.lang.String, java.awt.Component),
setViewportBorder(javax.swing.border.Border)

Nested Class Summary
protected class | JScrollPane.AccessibleJScrollPane This class implements accessibility support for the JScrollPane class.
protected class | JScrollPane.ScrollBar By default JScrollPane creates scrollbars that are instances of this class.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected JViewport | columnHeader The column header child.
protected JScrollBar | horizontalScrollBar The scrollpane's horizontal scrollbar child.
protected int | horizontalScrollBarPolicy The display policy for the horizontal scrollbar.
protected Component | lowerLeft The component to display in the lower left corner.
protected Component | lowerRight The component to display in the lower right corner.
protected JViewport | rowHeader The row header child.
protected Component | upperLeft The component to display in the upper left corner.
protected Component | upperRight The component to display in the upper right corner.
protected JScrollBar | verticalScrollBar The scrollpane's vertical scrollbar child.
protected int | verticalScrollBarPolicy The display policy for the vertical scrollbar.
protected JViewport | viewport The scrollpane's viewport child.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.ScrollPaneConstants
COLUMN_HEADER, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_ALWAYS, HORIZONTAL_SCROLLBAR_AS_NEEDED, HORIZONTAL_SCROLLBAR_NEVER, HORIZONTAL_SCROLLBAR_POLICY, LOWER_LEADING_CORNER, LOWER_LEFT_CORNER, LOWER_RIGHT_CORNER, LOWER_TRAILING_CORNER, ROW_HEADER, UPPER_LEADING_CORNER, UPPER_LEFT_CORNER, UPPER_RIGHT_CORNER, UPPER_TRAILING_CORNER, VERTICAL_SCROLLBAR, VERTICAL_SCROLLBAR_ALWAYS, VERTICAL_SCROLLBAR_AS_NEEDED, VERTICAL_SCROLLBAR_NEVER, VERTICAL_SCROLLBAR_POLICY, VIEWPORT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JScrollPane()
Creates an empty (no viewport view) JScrollPane where both horizontal and vertical scrollbars appear when needed.
JScrollPane(Component view)
Creates a JScrollPane that displays the contents of the specified component, where both horizontal and vertical scrollbars appear whenever the component's contents are larger than the view.
JScrollPane(Component view, int vsbPolicy, int hsbPolicy)
Creates a JScrollPane that displays the view component in a viewport whose view position can be controlled with a pair of scrollbars.
JScrollPane(int vsbPolicy, int hsbPolicy)
Creates an empty (no viewport view) JScrollPane with specified scrollbar policies.
Method Summary
JScrollBar | createHorizontalScrollBar() Returns a JScrollPane.ScrollBar by default.
JScrollBar | createVerticalScrollBar() Returns a JScrollPane.ScrollBar by default.
protected JViewport | createViewport() Returns a new JViewport by default.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JScrollPane.
JViewport | getColumnHeader() Returns the column header.
Component | getCorner(String key) Returns the component at the specified corner.
JScrollBar | getHorizontalScrollBar() Returns the horizontal scroll bar that controls the viewport's horizontal view position.
int | getHorizontalScrollBarPolicy() Returns the horizontal scroll bar policy value.
JViewport | getRowHeader() Returns the row header.
ScrollPaneUI | getUI() Returns the look and feel (L&F) object that renders this component.
String | getUIClassID() Returns the suffix used to construct the name of the L&F class used to render this component.
JScrollBar | getVerticalScrollBar() Returns the vertical scroll bar that controls the viewports vertical view position.
int | getVerticalScrollBarPolicy() Returns the vertical scroll bar policy value.
JViewport | getViewport() Returns the current JViewport.
Border | getViewportBorder() Returns the Border object that surrounds the viewport.
Rectangle | getViewportBorderBounds() Returns the bounds of the viewport's border.
boolean | isValidateRoot() Overridden to return true so that any calls to revalidate on any descendants of this JScrollPane will cause the entire tree beginning with this JScrollPane to be validated.
boolean | isWheelScrollingEnabled() Indicates whether or not scrolling will take place in response to the mouse wheel.
protected String | paramString() Returns a string representation of this JScrollPane.
void | setColumnHeader(JViewport columnHeader) Removes the old columnHeader, if it exists; if the new columnHeader isn't null, syncs the x coordinate of its viewPosition with the viewport (if there is one) and then adds it to the scroll pane.
void | setColumnHeaderView(Component view) Creates a column-header viewport if necessary, sets its view, and then adds the column-header viewport to the scrollpane.
void | setComponentOrientation(ComponentOrientation co) Sets the orientation for the vertical and horizontal scrollbars as determined by the ComponentOrientation argument.
void | setCorner(String key, Component corner) Adds a child that will appear in one of the scroll panes corners, if there's room.
void | setHorizontalScrollBar(JScrollBar horizontalScrollBar) Adds the scrollbar that controls the viewport's horizontal view position to the scrollpane.
void | setHorizontalScrollBarPolicy(int policy) Determines when the horizontal scrollbar appears in the scrollpane.
void | setLayout(LayoutManager layout) Sets the layout manager for this JScrollPane.
void | setRowHeader(JViewport rowHeader) Removes the old rowHeader, if it exists; if the new rowHeader isn't null, syncs the y coordinate of its viewPosition with the viewport (if there is one) and then adds it to the scroll pane.
void | setRowHeaderView(Component view) Creates a row-header viewport if necessary, sets its view and then adds the row-header viewport to the scrollpane.
void | setUI(ScrollPaneUI ui) Sets the ScrollPaneUI object that provides the look and feel (L&F) for this component.
void | setVerticalScrollBar(JScrollBar verticalScrollBar) Adds the scrollbar that controls the viewports vertical view position to the scrollpane.
void | setVerticalScrollBarPolicy(int policy) Determines when the vertical scrollbar appears in the scrollpane.
void | setViewport(JViewport viewport) Removes the old viewport (if there is one); forces the viewPosition of the new viewport to be in the +x,+y quadrant; syncs up the row and column headers (if there are any) with the new viewport; and finally syncs the scrollbars and headers with the new viewport.
void | setViewportBorder(Border viewportBorder) Adds a border around the viewport.
void | setViewportView(Component view) Creates a viewport if necessary and then sets its view.
void | setWheelScrollingEnabled(boolean handleWheel) Enables/disables scrolling in response to movement of the mouse wheel.
void | updateUI() Replaces the current ScrollPaneUI object with a version from the current default look and feel.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

verticalScrollBarPolicy

protected int verticalScrollBarPolicy
The display policy for the vertical scrollbar. The default is ScrollPaneConstants.VERTICAL_SCROLLBAR_AS_NEEDED.

See Also:
setVerticalScrollBarPolicy(int)

horizontalScrollBarPolicy

protected int horizontalScrollBarPolicy
The display policy for the horizontal scrollbar. The default is ScrollPaneConstants.HORIZONTAL_SCROLLBAR_AS_NEEDED.

See Also:
setHorizontalScrollBarPolicy(int)

viewport

protected JViewport viewport
The scrollpane's viewport child. Default is an empty JViewport.

See Also:
setViewport(javax.swing.JViewport)

verticalScrollBar

protected JScrollBar verticalScrollBar
The scrollpane's vertical scrollbar child. Default is a JScrollBar.

See Also:
setVerticalScrollBar(javax.swing.JScrollBar)

horizontalScrollBar

protected JScrollBar horizontalScrollBar
The scrollpane's horizontal scrollbar child. Default is a JScrollBar.

See Also:
setHorizontalScrollBar(javax.swing.JScrollBar)

rowHeader

protected JViewport rowHeader
The row header child. Default is null.

See Also:
setRowHeader(javax.swing.JViewport)

columnHeader

protected JViewport columnHeader
The column header child. Default is null.

See Also:
setColumnHeader(javax.swing.JViewport)

lowerLeft

protected Component lowerLeft
The component to display in the lower left corner. Default is null.

See Also:
setCorner(java.lang.String, java.awt.Component)

lowerRight

protected Component lowerRight
The component to display in the lower right corner. Default is null.

See Also:
setCorner(java.lang.String, java.awt.Component)

upperLeft

protected Component upperLeft
The component to display in the upper left corner. Default is null.

See Also:
setCorner(java.lang.String, java.awt.Component)

upperRight

protected Component upperRight
The component to display in the upper right corner. Default is null.

See Also:
setCorner(java.lang.String, java.awt.Component)
Constructor Detail

JScrollPane

public JScrollPane(Component view,
                   int vsbPolicy,
                   int hsbPolicy)
Creates a JScrollPane that displays the view component in a viewport whose view position can be controlled with a pair of scrollbars. The scrollbar policies specify when the scrollbars are displayed, For example, if vsbPolicy is VERTICAL_SCROLLBAR_AS_NEEDED then the vertical scrollbar only appears if the view doesn't fit vertically. The available policy settings are listed at setVerticalScrollBarPolicy(int) and setHorizontalScrollBarPolicy(int).

Parameters:
view - the component to display in the scrollpanes viewport
vsbPolicy - an integer that specifies the vertical scrollbar policy
hsbPolicy - an integer that specifies the horizontal scrollbar policy
See Also:
setViewportView(java.awt.Component)

JScrollPane

public JScrollPane(Component view)
Creates a JScrollPane that displays the contents of the specified component, where both horizontal and vertical scrollbars appear whenever the component's contents are larger than the view.

Parameters:
view - the component to display in the scrollpane's viewport
See Also:
setViewportView(java.awt.Component)

JScrollPane

public JScrollPane(int vsbPolicy,
                   int hsbPolicy)
Creates an empty (no viewport view) JScrollPane with specified scrollbar policies. The available policy settings are listed at setVerticalScrollBarPolicy(int) and setHorizontalScrollBarPolicy(int).

Parameters:
vsbPolicy - an integer that specifies the vertical scrollbar policy
hsbPolicy - an integer that specifies the horizontal scrollbar policy
See Also:
setViewportView(java.awt.Component)

JScrollPane

public JScrollPane()
Creates an empty (no viewport view) JScrollPane where both horizontal and vertical scrollbars appear when needed.

Method Detail

getUI

public ScrollPaneUI getUI()
Returns the look and feel (L&F) object that renders this component.

Returns:
the ScrollPaneUI object that renders this component
See Also:
setUI(javax.swing.plaf.ScrollPaneUI)

setUI

public void setUI(ScrollPaneUI ui)
Sets the ScrollPaneUI object that provides the look and feel (L&F) for this component.

Parameters:
ui - the ScrollPaneUI L&F object
See Also:
getUI()

updateUI

public void updateUI()
Replaces the current ScrollPaneUI object with a version from the current default look and feel. To be called when the default look and feel changes.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI(), UIManager.getUI(javax.swing.JComponent)

getUIClassID

public String getUIClassID()
Returns the suffix used to construct the name of the L&F class used to render this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "ScrollPaneUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

setLayout

public void setLayout(LayoutManager layout)
Sets the layout manager for this JScrollPane. This method overrides setLayout in java.awt.Container to ensure that only LayoutManagers which are subclasses of ScrollPaneLayout can be used in a JScrollPane. If layout is non-null, this will invoke syncWithScrollPane on it.

Overrides:
setLayout in class Container
Parameters:
layout - the specified layout manager
Throws:
ClassCastException - if layout is not a ScrollPaneLayout
See Also:
Container.getLayout(), Container.setLayout(java.awt.LayoutManager)

isValidateRoot

public boolean isValidateRoot()
Overridden to return true so that any calls to revalidate on any descendants of this JScrollPane will cause the entire tree beginning with this JScrollPane to be validated.

Overrides:
isValidateRoot in class JComponent
Returns:
true
See Also:
Container.validate(),
JComponent.revalidate(),
JComponent.isValidateRoot()

getVerticalScrollBarPolicy

public int getVerticalScrollBarPolicy()
Returns the vertical scroll bar policy value.

Returns:
the verticalScrollBarPolicy property
See Also:
setVerticalScrollBarPolicy(int)

setVerticalScrollBarPolicy

public void setVerticalScrollBarPolicy(int policy)
Determines when the vertical scrollbar appears in the scrollpane. Legal values are:
  • ScrollPaneConstants.VERTICAL_SCROLLBAR_AS_NEEDED
  • ScrollPaneConstants.VERTICAL_SCROLLBAR_NEVER
  • ScrollPaneConstants.VERTICAL_SCROLLBAR_ALWAYS

Parameters:
policy - one of the three values listed above
Throws:
IllegalArgumentException - if policy is not one of the legal values shown above
See Also:
getVerticalScrollBarPolicy()

getHorizontalScrollBarPolicy

public int getHorizontalScrollBarPolicy()
Returns the horizontal scroll bar policy value.

Returns:
the horizontalScrollBarPolicy property
See Also:
setHorizontalScrollBarPolicy(int)

setHorizontalScrollBarPolicy

public void setHorizontalScrollBarPolicy(int policy)
Determines when the horizontal scrollbar appears in the scrollpane. The options are:
  • ScrollPaneConstants.HORIZONTAL_SCROLLBAR_AS_NEEDED
  • ScrollPaneConstants.HORIZONTAL_SCROLLBAR_NEVER
  • ScrollPaneConstants.HORIZONTAL_SCROLLBAR_ALWAYS

Parameters:
policy - one of the three values listed above
Throws:
IllegalArgumentException - if policy is not one of the legal values shown above
See Also:
getHorizontalScrollBarPolicy()

getViewportBorder

public Border getViewportBorder()
Returns the Border object that surrounds the viewport.

Returns:
the viewportBorder property
See Also:
setViewportBorder(javax.swing.border.Border)

setViewportBorder

public void setViewportBorder(Border viewportBorder)
Adds a border around the viewport. Note that the border isn't set on the viewport directly, JViewport doesn't support the JComponent border property. Similarly setting the JScrollPanes viewport doesn't affect the viewportBorder property.

The default value of this property is computed by the look and feel implementation.

Parameters:
viewportBorder - the border to be added
See Also:
getViewportBorder(), setViewport(javax.swing.JViewport)

getViewportBorderBounds

public Rectangle getViewportBorderBounds()
Returns the bounds of the viewport's border.

Returns:
a Rectangle object specifying the viewport border

createHorizontalScrollBar

public JScrollBar createHorizontalScrollBar()
Returns a JScrollPane.ScrollBar by default. Subclasses may override this method to force ScrollPaneUI implementations to use a JScrollBar subclass. Used by ScrollPaneUI implementations to create the horizontal scrollbar.

Returns:
a JScrollBar with a horizontal orientation
See Also:
JScrollBar

getHorizontalScrollBar

public JScrollBar getHorizontalScrollBar()
Returns the horizontal scroll bar that controls the viewport's horizontal view position.

Returns:
the horizontalScrollBar property
See Also:
setHorizontalScrollBar(javax.swing.JScrollBar)

setHorizontalScrollBar

public void setHorizontalScrollBar(JScrollBar horizontalScrollBar)
Adds the scrollbar that controls the viewport's horizontal view position to the scrollpane. This is usually unnecessary, as JScrollPane creates horizontal and vertical scrollbars by default.

Parameters:
horizontalScrollBar - the horizontal scrollbar to be added
See Also:
createHorizontalScrollBar(), getHorizontalScrollBar()

createVerticalScrollBar

public JScrollBar createVerticalScrollBar()
Returns a JScrollPane.ScrollBar by default. Subclasses may override this method to force ScrollPaneUI implementations to use a JScrollBar subclass. Used by ScrollPaneUI implementations to create the vertical scrollbar.

Returns:
a JScrollBar with a vertical orientation
See Also:
JScrollBar

getVerticalScrollBar

public JScrollBar getVerticalScrollBar()
Returns the vertical scroll bar that controls the viewports vertical view position.

Returns:
the verticalScrollBar property
See Also:
setVerticalScrollBar(javax.swing.JScrollBar)

setVerticalScrollBar

public void setVerticalScrollBar(JScrollBar verticalScrollBar)
Adds the scrollbar that controls the viewports vertical view position to the scrollpane. This is usually unnecessary, as JScrollPane creates vertical and horizontal scrollbars by default.

Parameters:
verticalScrollBar - the new vertical scrollbar to be added
See Also:
createVerticalScrollBar(), getVerticalScrollBar()

createViewport

protected JViewport createViewport()
Returns a new JViewport by default. Used to create the viewport (as needed) in setViewportView, setRowHeaderView, and setColumnHeaderView. Subclasses may override this method to return a subclass of JViewport.

Returns:
a new JViewport

getViewport

public JViewport getViewport()
Returns the current JViewport.

Returns:
the viewport property
See Also:
setViewport(javax.swing.JViewport)

setViewport

public void setViewport(JViewport viewport)
Removes the old viewport (if there is one); forces the viewPosition of the new viewport to be in the +x,+y quadrant; syncs up the row and column headers (if there are any) with the new viewport; and finally syncs the scrollbars and headers with the new viewport.

Most applications will find it more convenient to use setViewportView to add a viewport and a view to the scrollpane.

Parameters:
viewport - the new viewport to be used; if viewport is null, the old viewport is still removed and the new viewport is set to null
See Also:
createViewport(),
getViewport(),
setViewportView(java.awt.Component)

setViewportView

public void setViewportView(Component view)
Creates a viewport if necessary and then sets its view. Applications that don't provide the view directly to the JScrollPane constructor should use this method to specify the scrollable child that's going to be displayed in the scrollpane. For example:
 JScrollPane scrollpane = new JScrollPane();
 scrollpane.setViewportView(myBigComponentToScroll);
Applications should not add children directly to the scrollpane.

Parameters:
view - the component to add to the viewport
See Also:
setViewport(javax.swing.JViewport), JViewport.setView(java.awt.Component)

getRowHeader

public JViewport getRowHeader()
Returns the row header.

Returns:
the rowHeader property
See Also:
setRowHeader(javax.swing.JViewport)

setRowHeader

public void setRowHeader(JViewport rowHeader)
Removes the old rowHeader, if it exists; if the new rowHeader isn't null, syncs the y coordinate of its viewPosition with the viewport (if there is one) and then adds it to the scroll pane.

Most applications will find it more convenient to use setRowHeaderView to add a row header component and its viewport to the scroll pane.

Parameters:
rowHeader - the new row header to be used; if null the old row header is still removed and the new rowHeader is set to null
See Also:
getRowHeader(), setRowHeaderView(java.awt.Component)

setRowHeaderView

public void setRowHeaderView(Component view)
Creates a row-header viewport if necessary, sets its view and then adds the row-header viewport to the scrollpane. For example:
 JScrollPane scrollpane = new JScrollPane();
 scrollpane.setViewportView(myBigComponentToScroll);
 scrollpane.setRowHeaderView(myBigComponentsRowHeader);

Parameters:
view - the component to display as the row header
See Also:
setRowHeader(javax.swing.JViewport), JViewport.setView(java.awt.Component)

getColumnHeader

public JViewport getColumnHeader()
Returns the column header.

Returns:
the columnHeader property
See Also:
setColumnHeader(javax.swing.JViewport)

setColumnHeader

public void setColumnHeader(JViewport columnHeader)
Removes the old columnHeader, if it exists; if the new columnHeader isn't null, syncs the x coordinate of its viewPosition with the viewport (if there is one) and then adds it to the scroll pane.

Most applications will find it more convenient to use setColumnHeaderView to add a column header component and its viewport to the scroll pane.

See Also:
getColumnHeader(), setColumnHeaderView(java.awt.Component)

setColumnHeaderView

public void setColumnHeaderView(Component view)
Creates a column-header viewport if necessary, sets its view, and then adds the column-header viewport to the scrollpane. For example:
 JScrollPane scrollpane = new JScrollPane();
 scrollpane.setViewportView(myBigComponentToScroll);
 scrollpane.setColumnHeaderView(myBigComponentsColumnHeader);

Parameters:
view - the component to display as the column header
See Also:
setColumnHeader(javax.swing.JViewport), JViewport.setView(java.awt.Component)

getCorner

public Component getCorner(String key)
Returns the component at the specified corner. The key value specifying the corner is one of:
  • ScrollPaneConstants.LOWER_LEFT_CORNER
  • ScrollPaneConstants.LOWER_RIGHT_CORNER
  • ScrollPaneConstants.UPPER_LEFT_CORNER
  • ScrollPaneConstants.UPPER_RIGHT_CORNER
  • ScrollPaneConstants.LOWER_LEADING_CORNER
  • ScrollPaneConstants.LOWER_TRAILING_CORNER
  • ScrollPaneConstants.UPPER_LEADING_CORNER
  • ScrollPaneConstants.UPPER_TRAILING_CORNER

Parameters:
key - one of the values as shown above
Returns:
the corner component (which may be null) identified by the given key, or null if the key is invalid
See Also:
setCorner(java.lang.String, java.awt.Component)

setCorner

public void setCorner(String key,
                      Component corner)
Adds a child that will appear in one of the scroll panes corners, if there's room. For example with both scrollbars showing (on the right and bottom edges of the scrollpane) the lower left corner component will be shown in the space between ends of the two scrollbars. Legal values for the key are:
  • ScrollPaneConstants.LOWER_LEFT_CORNER
  • ScrollPaneConstants.LOWER_RIGHT_CORNER
  • ScrollPaneConstants.UPPER_LEFT_CORNER
  • ScrollPaneConstants.UPPER_RIGHT_CORNER
  • ScrollPaneConstants.LOWER_LEADING_CORNER
  • ScrollPaneConstants.LOWER_TRAILING_CORNER
  • ScrollPaneConstants.UPPER_LEADING_CORNER
  • ScrollPaneConstants.UPPER_TRAILING_CORNER

Although "corner" doesn't match any beans property signature, PropertyChange events are generated with the property name set to the corner key.

Parameters:
key - identifies which corner the component will appear in
corner - one of the following components:
  • lowerLeft
  • lowerRight
  • upperLeft
  • upperRight
Throws:
IllegalArgumentException - if corner key is invalid

setComponentOrientation

public void setComponentOrientation(ComponentOrientation co)
Sets the orientation for the vertical and horizontal scrollbars as determined by the ComponentOrientation argument.

Overrides:
setComponentOrientation in class Component
Parameters:
co - one of the following values:
  • java.awt.ComponentOrientation.LEFT_TO_RIGHT
  • java.awt.ComponentOrientation.RIGHT_TO_LEFT
  • java.awt.ComponentOrientation.UNKNOWN
See Also:
ComponentOrientation

isWheelScrollingEnabled

public boolean isWheelScrollingEnabled()
Indicates whether or not scrolling will take place in response to the mouse wheel. Wheel scrolling is enabled by default.

Since:
1.4
See Also:
setWheelScrollingEnabled(boolean)

setWheelScrollingEnabled

public void setWheelScrollingEnabled(boolean handleWheel)
Enables/disables scrolling in response to movement of the mouse wheel. Wheel scrolling is enabled by default.

Parameters:
handleWheel - true if scrolling should be done automatically for a MouseWheelEvent, false otherwise.
Since:
1.4
See Also:
isWheelScrollingEnabled(), MouseWheelEvent, MouseWheelListener

paramString

protected String paramString()
Returns a string representation of this JScrollPane. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JScrollPane.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JScrollPane. For scroll panes, the AccessibleContext takes the form of an AccessibleJScrollPane. A new AccessibleJScrollPane instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJScrollPane that serves as the AccessibleContext of this JScrollPane
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JScrollPane.AccessibleJScrollPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JScrollPane.AccessibleJScrollPane

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JScrollPane.AccessibleJScrollPane
All Implemented Interfaces:
PropertyChangeListener, Serializable, EventListener, AccessibleComponent, AccessibleExtendedComponent, ChangeListener
Enclosing class:
JScrollPane
protected class JScrollPane.AccessibleJScrollPane
extends JComponent.AccessibleJComponent
implements ChangeListener, PropertyChangeListener

This class implements accessibility support for the JScrollPane class. It provides an implementation of the Java Accessibility API appropriate to scroll pane user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
protected  JViewport viewPort
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
JScrollPane.AccessibleJScrollPane()
AccessibleJScrollPane constructor
Method Summary
AccessibleRole | getAccessibleRole() Get the role of this object.
void | propertyChange(PropertyChangeEvent e) This method gets called when a bound property is changed.
void | resetViewPort()
void | stateChanged(ChangeEvent e) Invoked when the target of the listener has changed its state.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Field Detail

viewPort

protected JViewport viewPort
Constructor Detail

JScrollPane.AccessibleJScrollPane

public JScrollPane.AccessibleJScrollPane()
AccessibleJScrollPane constructor

Method Detail

resetViewPort

public void resetViewPort()

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

stateChanged

public void stateChanged(ChangeEvent e)
Invoked when the target of the listener has changed its state.

Specified by:
stateChanged in interface ChangeListener
Parameters:
e - a ChangeEvent object. Must not be null.
Throws:
NullPointerException - if the parameter is null.

propertyChange

public void propertyChange(PropertyChangeEvent e)
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed. Must not be null.
Throws:
NullPointerException - if the parameter is null.
Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JScrollPane.ScrollBar

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JScrollPane.ScrollBar

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JScrollBar
                    extended by  javax.swing.JScrollPane.ScrollBar
All Implemented Interfaces:
Adjustable, ImageObserver, MenuContainer, Serializable, Accessible, UIResource
Enclosing class:
JScrollPane
protected class JScrollPane.ScrollBar
extends JScrollBar
implements UIResource

By default JScrollPane creates scrollbars that are instances of this class. Scrollbar overrides the getUnitIncrement and getBlockIncrement methods so that, if the viewport's view is a Scrollable, the view is asked to compute these values. Unless the unit/block increment have been explicitly set.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
Scrollable, JScrollPane.createVerticalScrollBar(), JScrollPane.createHorizontalScrollBar()

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JScrollBar
JScrollBar.AccessibleJScrollBar
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JScrollBar
blockIncrement, model, orientation, unitIncrement
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.Adjustable
HORIZONTAL, NO_ORIENTATION, VERTICAL
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JScrollPane.ScrollBar(int orientation)
Creates a scrollbar with the specified orientation.
Method Summary
int | getBlockIncrement(int direction) Computes the block increment for scrolling if the viewport's view is a Scrollable object.
int | getUnitIncrement(int direction) Computes the unit increment for scrolling if the viewport's view is a Scrollable object.
void | setBlockIncrement(int blockIncrement) Messages super to set the value, and resets the blockIncrementSet instance variable to true.
void | setUnitIncrement(int unitIncrement) Messages super to set the value, and resets the unitIncrementSet instance variable to true.
Methods inherited from class javax.swing.JScrollBar
addAdjustmentListener, fireAdjustmentValueChanged, getAccessibleContext, getAdjustmentListeners, getBlockIncrement, getMaximum, getMaximumSize, getMinimum, getMinimumSize, getModel, getOrientation, getUI, getUIClassID, getUnitIncrement, getValue, getValueIsAdjusting, getVisibleAmount, paramString, removeAdjustmentListener, setEnabled, setMaximum, setMinimum, setModel, setOrientation, setUI, setValue, setValueIsAdjusting, setValues, setVisibleAmount, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JScrollPane.ScrollBar

public JScrollPane.ScrollBar(int orientation)
Creates a scrollbar with the specified orientation. The options are:
  • ScrollPaneConstants.VERTICAL
  • ScrollPaneConstants.HORIZONTAL

Parameters:
orientation - an integer specifying one of the legal orientation values shown above
Since:
1.4
Method Detail

setUnitIncrement

public void setUnitIncrement(int unitIncrement)
Messages super to set the value, and resets the unitIncrementSet instance variable to true.

Specified by:
setUnitIncrement in interface Adjustable
Overrides:
setUnitIncrement in class JScrollBar
Parameters:
unitIncrement - the new unit increment value, in pixels
See Also:
JScrollBar.getUnitIncrement(int)

getUnitIncrement

public int getUnitIncrement(int direction)
Computes the unit increment for scrolling if the viewport's view is a Scrollable object. Otherwise return super.getUnitIncrement.

Overrides:
getUnitIncrement in class JScrollBar
Parameters:
direction - less than zero to scroll up/left, greater than zero for down/right
Returns:
an integer, in pixels, containing the unit increment
See Also:
Scrollable.getScrollableUnitIncrement(java.awt.Rectangle, int, int)

setBlockIncrement

public void setBlockIncrement(int blockIncrement)
Messages super to set the value, and resets the blockIncrementSet instance variable to true.

Specified by:
setBlockIncrement in interface Adjustable
Overrides:
setBlockIncrement in class JScrollBar
Parameters:
blockIncrement - the new block increment value, in pixels
See Also:
JScrollBar.getBlockIncrement()

getBlockIncrement

public int getBlockIncrement(int direction)
Computes the block increment for scrolling if the viewport's view is a Scrollable object. Otherwise the blockIncrement equals the viewport's width or height. If there's no viewport return super.getBlockIncrement.

Overrides:
getBlockIncrement in class JScrollBar
Parameters:
direction - less than zero to scroll up/left, greater than zero for down/right
Returns:
an integer, in pixels, containing the block increment
See Also:
Scrollable.getScrollableBlockIncrement(java.awt.Rectangle, int, int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JSeparator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JSeparator

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JSeparator
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, SwingConstants
Direct Known Subclasses:
JPopupMenu.Separator, JToolBar.Separator
public class JSeparator
extends JComponent
implements SwingConstants, Accessible

JSeparator provides a general purpose component for implementing divider lines - most commonly used as a divider between menu items that breaks them up into logical groupings. Instead of using JSeparator directly, you can use the JMenu or JPopupMenu addSeparator method to create and add a separator. JSeparators may also be used elsewhere in a GUI wherever a visual divider is useful.

For more information and examples see How to Use Menus, a section in The Java Tutorial.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class JSeparator.AccessibleJSeparator
This class implements accessibility support for the JSeparator class.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JSeparator()
Creates a new horizontal separator.
JSeparator(int orientation)
Creates a new separator with the specified horizontal or vertical orientation.
Method Summary
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JSeparator.
int | getOrientation() Returns the orientation of this separator.
SeparatorUI | getUI() Returns the L&F object that renders this component.
String | getUIClassID() Returns the name of the L&F class that renders this component.
protected String | paramString() Returns a string representation of this JSeparator.
void | setOrientation(int orientation) Sets the orientation of the separator.
void | setUI(SeparatorUI ui) Sets the L&F object that renders this component.
void | updateUI() Resets the UI property to a value from the current look and feel.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JSeparator

public JSeparator()
Creates a new horizontal separator.

JSeparator

public JSeparator(int orientation)
Creates a new separator with the specified horizontal or vertical orientation.

Parameters:
orientation - an integer specifying SwingConstants.HORIZONTAL or SwingConstants.VERTICAL
Throws:
IllegalArgumentException - if orientation is neither SwingConstants.HORIZONTAL nor SwingConstants.VERTICAL
Method Detail

getUI

public SeparatorUI getUI()
Returns the L&F object that renders this component.

Returns:
the SeparatorUI object that renders this component

setUI

public void setUI(SeparatorUI ui)
Sets the L&F object that renders this component.

Parameters:
ui - the SeparatorUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Resets the UI property to a value from the current look and feel.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "SeparatorUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

getOrientation

public int getOrientation()
Returns the orientation of this separator.

Returns:
The value of the orientation property, one of the following constants defined in SwingConstants: VERTICAL, or HORIZONTAL.
See Also:
SwingConstants, setOrientation(int)

setOrientation

public void setOrientation(int orientation)
Sets the orientation of the separator. The default value of this property is HORIZONTAL.

Parameters:
orientation - either SwingConstants.HORIZONTAL or SwingConstants.VERTICAL
Throws:
IllegalArgumentException - if orientation is neither SwingConstants.HORIZONTAL nor SwingConstants.VERTICAL
See Also:
SwingConstants, getOrientation()

paramString

protected String paramString()
Returns a string representation of this JSeparator. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JSeparator

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JSeparator. For separators, the AccessibleContext takes the form of an AccessibleJSeparator. A new AccessibleJSeparator instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJSeparator that serves as the AccessibleContext of this JSeparator
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JSeparator.AccessibleJSeparator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JSeparator.AccessibleJSeparator

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JSeparator.AccessibleJSeparator
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent
Enclosing class:
JSeparator
protected class JSeparator.AccessibleJSeparator
extends JComponent.AccessibleJComponent

This class implements accessibility support for the JSeparator class. It provides an implementation of the Java Accessibility API appropriate to separator user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JSeparator.AccessibleJSeparator()
Method Summary
 AccessibleRole getAccessibleRole()
Get the role of this object.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JSeparator.AccessibleJSeparator

protected JSeparator.AccessibleJSeparator()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JSlider

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JSlider

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JSlider
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, SwingConstants
public class JSlider
extends JComponent
implements SwingConstants, Accessible

A component that lets the user graphically select a value by sliding a knob within a bounded interval.

The slider can show both major tick marks, and minor tick marks between the major ones. The number of values between the tick marks is controlled with setMajorTickSpacing and setMinorTickSpacing. Painting of tick marks is controlled by setPaintTicks.

Sliders can also print text labels at regular intervals (or at arbitrary locations) along the slider track. Painting of labels is controlled by setLabelTable and setPaintLabels.

For further information and examples see How to Use Sliders, a section in The Java Tutorial.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class JSlider.AccessibleJSlider
This class implements accessibility support for the JSlider class.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected ChangeEvent | changeEvent Only one ChangeEvent is needed per slider instance since the event's only (read-only) state is the source property.
protected ChangeListener | changeListener The changeListener (no suffix) is the listener we add to the slider's model.
protected int | majorTickSpacing The number of values between the major tick marks -- the larger marks that break up the minor tick marks.
protected int | minorTickSpacing The number of values between the minor tick marks -- the smaller marks that occur between the major tick marks.
protected int | orientation Whether the slider is horizontal or vertical The default is horizontal.
protected BoundedRangeModel | sliderModel The data model that handles the numeric maximum value, minimum value, and current-position value for the slider.
protected boolean | snapToTicks If true, the knob (and the data value it represents) resolve to the closest tick mark next to where the user positioned the knob.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JSlider()
Creates a horizontal slider with the range 0 to 100 and an initial value of 50.
JSlider(BoundedRangeModel brm)
Creates a horizontal slider using the specified BoundedRangeModel.
JSlider(int orientation)
Creates a slider using the specified orientation with the range 0 to 100 and an initial value of 50.
JSlider(int min, int max)
Creates a horizontal slider using the specified min and max with an initial value equal to the average of the min plus max.
JSlider(int min, int max, int value)
Creates a horizontal slider using the specified min, max and value.
JSlider(int orientation, int min, int max, int value)
Creates a slider with the specified orientation and the specified minimum, maximum, and initial values.
Method Summary
 void addChangeListener(ChangeListener l)
Adds a ChangeListener to the slider.
protected  ChangeListener createChangeListener()
Subclasses that want to handle ChangeEvents from the model differently can override this to return an instance of a custom ChangeListener implementation.
 Hashtable createStandardLabels(int increment)
Creates a Hashtable of numerical text labels, starting at the slider minimum, and using the increment specified.
 Hashtable createStandardLabels(int increment, int start)
Creates a Hashtable of numerical text labels, starting at the starting point specified, and using the increment specified.
protected  void fireStateChanged()
Send a ChangeEvent, whose source is this JSlider, to all ChangeListeners that have registered interest in ChangeEvents.
 AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JSlider.
 ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this JSlider with addChangeListener().
 int getExtent()
Returns the "extent" from the BoundedRangeModel.
 boolean getInverted()
Returns true if the value-range shown for the slider is reversed,
 Dictionary getLabelTable()
Returns the dictionary of what labels to draw at which values.
 int getMajorTickSpacing()
This method returns the major tick spacing.
 int getMaximum()
Returns the maximum value supported by the slider from the BoundedRangeModel.
 int getMinimum()
Returns the minimum value supported by the slider from the BoundedRangeModel.
 int getMinorTickSpacing()
This method returns the minor tick spacing.
 BoundedRangeModel getModel()
Returns the BoundedRangeModel that handles the slider's three fundamental properties: minimum, maximum, value.
 int getOrientation()
Return this slider's vertical or horizontal orientation.
 boolean getPaintLabels()
Tells if labels are to be painted.
 boolean getPaintTicks()
Tells if tick marks are to be painted.
 boolean getPaintTrack()
Tells if the track (area the slider slides in) is to be painted.
 boolean getSnapToTicks()
Returns true if the knob (and the data value it represents) resolve to the closest tick mark next to where the user positioned the knob.
 SliderUI getUI()
Gets the UI object which implements the L&F for this component.
 String getUIClassID()
Returns the name of the L&F class that renders this component.
 int getValue()
Returns the slider's current value from the BoundedRangeModel.
 boolean getValueIsAdjusting()
Returns the valueIsAdjusting property from the model.
protected  String paramString()
Returns a string representation of this JSlider.
 void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the slider.
 void setExtent(int extent)
Sets the size of the range "covered" by the knob.
 void setFont(Font font)
Sets the font for this component.
 void setInverted(boolean b)
Specify true to reverse the value-range shown for the slider and false to put the value range in the normal order.
 void setLabelTable(Dictionary labels)
Used to specify what label will be drawn at any given value.
 void setMajorTickSpacing(int n)
This method sets the major tick spacing.
 void setMaximum(int maximum)
Sets the slider's maximum value to maximum.
 void setMinimum(int minimum)
Sets the slider's minimum value to minimum.
 void setMinorTickSpacing(int n)
This method sets the minor tick spacing.
 void setModel(BoundedRangeModel newModel)
Sets the BoundedRangeModel that handles the slider's three fundamental properties: minimum, maximum, value.
 void setOrientation(int orientation)
Set the slider's orientation to either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL.
 void setPaintLabels(boolean b)
Determines whether labels are painted on the slider.
 void setPaintTicks(boolean b)
Determines whether tick marks are painted on the slider.
 void setPaintTrack(boolean b)
Determines whether the track is painted on the slider.
 void setSnapToTicks(boolean b)
Specifying true makes the knob (and the data value it represents) resolve to the closest tick mark next to where the user positioned the knob.
 void setUI(SliderUI ui)
Sets the UI object which implements the L&F for this component.
 void setValue(int n)
Sets the slider's current value to n.
 void setValueIsAdjusting(boolean b)
Sets the model's valueIsAdjusting property.
protected  void updateLabelUIs()
Updates the UIs for the labels in the label table by calling updateUI on each label.
 void updateUI()
Resets the UI property to a value from the current look and feel.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

sliderModel

protected BoundedRangeModel sliderModel
The data model that handles the numeric maximum value, minimum value, and current-position value for the slider.

majorTickSpacing

protected int majorTickSpacing
The number of values between the major tick marks -- the larger marks that break up the minor tick marks.

minorTickSpacing

protected int minorTickSpacing
The number of values between the minor tick marks -- the smaller marks that occur between the major tick marks.

See Also:
setMinorTickSpacing(int)

snapToTicks

protected boolean snapToTicks
If true, the knob (and the data value it represents) resolve to the closest tick mark next to where the user positioned the knob. The default is false.

See Also:
setSnapToTicks(boolean)

orientation

protected int orientation
Whether the slider is horizontal or vertical The default is horizontal.

See Also:
setOrientation(int)

changeListener

protected ChangeListener changeListener
The changeListener (no suffix) is the listener we add to the slider's model. This listener is initialized to the ChangeListener returned from createChangeListener, which by default just forwards events to ChangeListeners (if any) added directly to the slider.

See Also:
addChangeListener(javax.swing.event.ChangeListener), createChangeListener()

changeEvent

protected transient ChangeEvent changeEvent
Only one ChangeEvent is needed per slider instance since the event's only (read-only) state is the source property. The source of events generated here is always "this". The event is lazily created the first time that an event notification is fired.

See Also:
fireStateChanged()
Constructor Detail

JSlider

public JSlider()
Creates a horizontal slider with the range 0 to 100 and an initial value of 50.

JSlider

public JSlider(int orientation)
Creates a slider using the specified orientation with the range 0 to 100 and an initial value of 50. The orientation can be either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL.

Parameters:
orientation - the orientation of the slider
Throws:
IllegalArgumentException - if orientation is not one of VERTICAL, HORIZONTAL
See Also:
setOrientation(int)

JSlider

public JSlider(int min,
               int max)
Creates a horizontal slider using the specified min and max with an initial value equal to the average of the min plus max.

The BoundedRangeModel that holds the slider's data handles any issues that may arise from improperly setting the minimum and maximum values on the slider. See the BoundedRangeModel documentation for details.

Parameters:
min - the minimum value of the slider
max - the maximum value of the slider
See Also:
BoundedRangeModel, setMinimum(int), setMaximum(int)

JSlider

public JSlider(int min,
               int max,
               int value)
Creates a horizontal slider using the specified min, max and value.

The BoundedRangeModel that holds the slider's data handles any issues that may arise from improperly setting the minimum, initial, and maximum values on the slider. See the BoundedRangeModel documentation for details.

Parameters:
min - the minimum value of the slider
max - the maximum value of the slider
value - the initial value of the slider
See Also:
BoundedRangeModel, setMinimum(int), setMaximum(int), setValue(int)

JSlider

public JSlider(int orientation,
               int min,
               int max,
               int value)
Creates a slider with the specified orientation and the specified minimum, maximum, and initial values. The orientation can be either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL.

The BoundedRangeModel that holds the slider's data handles any issues that may arise from improperly setting the minimum, initial, and maximum values on the slider. See the BoundedRangeModel documentation for details.

Parameters:
orientation - the orientation of the slider
min - the minimum value of the slider
max - the maximum value of the slider
value - the initial value of the slider
Throws:
IllegalArgumentException - if orientation is not one of VERTICAL, HORIZONTAL
See Also:
BoundedRangeModel, setOrientation(int), setMinimum(int), setMaximum(int), setValue(int)

JSlider

public JSlider(BoundedRangeModel brm)
Creates a horizontal slider using the specified BoundedRangeModel.

Method Detail

getUI

public SliderUI getUI()
Gets the UI object which implements the L&F for this component.

Returns:
the SliderUI object that implements the Slider L&F

setUI

public void setUI(SliderUI ui)
Sets the UI object which implements the L&F for this component.

Parameters:
ui - the SliderUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Resets the UI property to a value from the current look and feel.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
"SliderUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

createChangeListener

protected ChangeListener createChangeListener()
Subclasses that want to handle ChangeEvents from the model differently can override this to return an instance of a custom ChangeListener implementation. The default ChangeListener simply calls the fireStateChanged method to forward ChangeEvents to the ChangeListeners that have been added directly to the slider.

See Also:
changeListener, fireStateChanged(), ChangeListener, BoundedRangeModel

addChangeListener

public void addChangeListener(ChangeListener l)
Adds a ChangeListener to the slider.

Parameters:
l - the ChangeListener to add
See Also:
fireStateChanged(), removeChangeListener(javax.swing.event.ChangeListener)

removeChangeListener

public void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the slider.

Parameters:
l - the ChangeListener to remove
See Also:
fireStateChanged(), addChangeListener(javax.swing.event.ChangeListener)

getChangeListeners

public ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this JSlider with addChangeListener().

Returns:
all of the ChangeListeners added or an empty array if no listeners have been added
Since:
1.4

fireStateChanged

protected void fireStateChanged()
Send a ChangeEvent, whose source is this JSlider, to all ChangeListeners that have registered interest in ChangeEvents. This method is called each time a ChangeEvent is received from the model.

The event instance is created if necessary, and stored in changeEvent.

See Also:
addChangeListener(javax.swing.event.ChangeListener), EventListenerList

getModel

public BoundedRangeModel getModel()
Returns the BoundedRangeModel that handles the slider's three fundamental properties: minimum, maximum, value.

Returns:
the data model for this component
See Also:
setModel(javax.swing.BoundedRangeModel), BoundedRangeModel

setModel

public void setModel(BoundedRangeModel newModel)
Sets the BoundedRangeModel that handles the slider's three fundamental properties: minimum, maximum, value.

Attempts to pass a null model to this method result in undefined behavior, and, most likely, exceptions.

Parameters:
newModel - the new, non-null BoundedRangeModel to use
See Also:
getModel(), BoundedRangeModel

getValue

public int getValue()
Returns the slider's current value from the BoundedRangeModel.

Returns:
the current value of the slider
See Also:
setValue(int), BoundedRangeModel.getValue()

setValue

public void setValue(int n)
Sets the slider's current value to n. This method forwards the new value to the model.

The data model (an instance of BoundedRangeModel) handles any mathematical issues arising from assigning faulty values. See the BoundedRangeModel documentation for details.

If the new value is different from the previous value, all change listeners are notified.

Parameters:
n - the new value
See Also:
getValue(),
addChangeListener(javax.swing.event.ChangeListener),
BoundedRangeModel.setValue(int)

getMinimum

public int getMinimum()
Returns the minimum value supported by the slider from the BoundedRangeModel.

Returns:
the value of the model's minimum property
See Also:
setMinimum(int), BoundedRangeModel.getMinimum()

setMinimum

public void setMinimum(int minimum)
Sets the slider's minimum value to minimum. This method forwards the new minimum value to the model.

The data model (an instance of BoundedRangeModel) handles any mathematical issues arising from assigning faulty values. See the BoundedRangeModel documentation for details.

If the new minimum value is different from the previous minimum value, all change listeners are notified.

Parameters:
n - the new minimum
See Also:
getMinimum(),
addChangeListener(javax.swing.event.ChangeListener),
BoundedRangeModel.setMinimum(int)

getMaximum

public int getMaximum()
Returns the maximum value supported by the slider from the BoundedRangeModel.

Returns:
the value of the model's maximum property
See Also:
setMaximum(int), BoundedRangeModel.getMaximum()

setMaximum

public void setMaximum(int maximum)
Sets the slider's maximum value to maximum. This method forwards the new maximum value to the model.

The data model (an instance of BoundedRangeModel) handles any mathematical issues arising from assigning faulty values. See the BoundedRangeModel documentation for details.

If the new maximum value is different from the previous maximum value, all change listeners are notified.

Parameters:
n - the new maximum
See Also:
getMaximum(),
addChangeListener(javax.swing.event.ChangeListener),
BoundedRangeModel.setMaximum(int)

getValueIsAdjusting

public boolean getValueIsAdjusting()
Returns the valueIsAdjusting property from the model. For details on how this is used, see the setValueIsAdjusting documentation.

Returns:
the value of the model's valueIsAdjusting property
See Also:
setValueIsAdjusting(boolean)

setValueIsAdjusting

public void setValueIsAdjusting(boolean b)
Sets the model's valueIsAdjusting property. Slider look and feel implementations should set this property to true when a knob drag begins, and to false when the drag ends. The slider model will not generate ChangeEvents while valueIsAdjusting is true.

Parameters:
b - the new value for the valueIsAdjusting property
See Also:
getValueIsAdjusting(), BoundedRangeModel.setValueIsAdjusting(boolean)

getExtent

public int getExtent()
Returns the "extent" from the BoundedRangeModel. This respresents the range of values "covered" by the knob.

Returns:
an int representing the extent
See Also:
setExtent(int), BoundedRangeModel.getExtent()

setExtent

public void setExtent(int extent)
Sets the size of the range "covered" by the knob. Most look and feel implementations will change the value by this amount if the user clicks on either side of the knob. This method just forwards the new extent value to the model.

The data model (an instance of BoundedRangeModel) handles any mathematical issues arising from assigning faulty values. See the BoundedRangeModel documentation for details.

If the new extent value is different from the previous extent value, all change listeners are notified.

Parameters:
extent - the new extent
See Also:
getExtent(), BoundedRangeModel.setExtent(int)

getOrientation

public int getOrientation()
Return this slider's vertical or horizontal orientation.

Returns:
SwingConstants.VERTICAL or SwingConstants.HORIZONTAL
See Also:
setOrientation(int)

setOrientation

public void setOrientation(int orientation)
Set the slider's orientation to either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL.

Parameters:
orientation - HORIZONTAL or VERTICAL
Throws:
IllegalArgumentException - if orientation is not one of VERTICAL, HORIZONTAL
See Also:
getOrientation()

setFont

public void setFont(Font font)
Sets the font for this component.

Overrides:
setFont in class JComponent
Parameters:
font - the desired Font for this component
Since:
1.6
See Also:
Component.getFont()

getLabelTable

public Dictionary getLabelTable()
Returns the dictionary of what labels to draw at which values.

Returns:
the Dictionary containing labels and where to draw them

setLabelTable

public void setLabelTable(Dictionary labels)
Used to specify what label will be drawn at any given value. The key-value pairs are of this format: { Integer value, java.swing.JComponent label }.

An easy way to generate a standard table of value labels is by using the createStandardLabels method.

Once the labels have been set, this method calls updateLabelUIs(). Note that the labels are only painted if the paintLabels property is true.

Parameters:
labels - new Dictionary of labels, or null to remove all labels
See Also:
createStandardLabels(int), getLabelTable(), setPaintLabels(boolean)

updateLabelUIs

protected void updateLabelUIs()
Updates the UIs for the labels in the label table by calling updateUI on each label. The UIs are updated from the current look and feel. The labels are also set to their preferred size.

See Also:
setLabelTable(java.util.Dictionary), JComponent.updateUI()

createStandardLabels

public Hashtable createStandardLabels(int increment)
Creates a Hashtable of numerical text labels, starting at the slider minimum, and using the increment specified. For example, if you call createStandardLabels( 10 ) and the slider minimum is zero, then labels will be created for the values 0, 10, 20, 30, and so on.

For the labels to be drawn on the slider, the returned Hashtable must be passed into setLabelTable, and setPaintLabels must be set to true.

For further details on the makeup of the returned Hashtable, see the setLabelTable documentation.

Parameters:
increment - distance between labels in the generated hashtable
Returns:
a new Hashtable of labels
Throws:
IllegalArgumentException - if increment is less than or equal to zero
See Also:
setLabelTable(java.util.Dictionary), setPaintLabels(boolean)

createStandardLabels

public Hashtable createStandardLabels(int increment,
                                      int start)
Creates a Hashtable of numerical text labels, starting at the starting point specified, and using the increment specified. For example, if you call createStandardLabels( 10, 2 ), then labels will be created for the values 2, 12, 22, 32, and so on.

For the labels to be drawn on the slider, the returned Hashtable must be passed into setLabelTable, and setPaintLabels must be set to true.

For further details on the makeup of the returned Hashtable, see the setLabelTable documentation.

Parameters:
increment - distance between labels in the generated hashtable
start - value at which the labels will begin
Returns:
a new Hashtable of labels
Throws:
IllegalArgumentException - if start is out of range, or if increment is less than or equal to zero
See Also:
setLabelTable(java.util.Dictionary), setPaintLabels(boolean)

getInverted

public boolean getInverted()
Returns true if the value-range shown for the slider is reversed,

Returns:
true if the slider values are reversed from their normal order
See Also:
setInverted(boolean)

setInverted

public void setInverted(boolean b)
Specify true to reverse the value-range shown for the slider and false to put the value range in the normal order. The order depends on the slider's ComponentOrientation property. Normal (non-inverted) horizontal sliders with a ComponentOrientation value of LEFT_TO_RIGHT have their maximum on the right. Normal horizontal sliders with a ComponentOrientation value of RIGHT_TO_LEFT have their maximum on the left. Normal vertical sliders have their maximum on the top. These labels are reversed when the slider is inverted.

By default, the value of this property is false.

Parameters:
b - true to reverse the slider values from their normal order

getMajorTickSpacing

public int getMajorTickSpacing()
This method returns the major tick spacing. The number that is returned represents the distance, measured in values, between each major tick mark. If you have a slider with a range from 0 to 50 and the major tick spacing is set to 10, you will get major ticks next to the following values: 0, 10, 20, 30, 40, 50.

Returns:
the number of values between major ticks
See Also:
setMajorTickSpacing(int)

setMajorTickSpacing

public void setMajorTickSpacing(int n)
This method sets the major tick spacing. The number that is passed in represents the distance, measured in values, between each major tick mark. If you have a slider with a range from 0 to 50 and the major tick spacing is set to 10, you will get major ticks next to the following values: 0, 10, 20, 30, 40, 50.

In order for major ticks to be painted, setPaintTicks must be set to true.

This method will also set up a label table for you. If there is not already a label table, and the major tick spacing is > 0, and getPaintLabels returns true, a standard label table will be generated (by calling createStandardLabels) with labels at the major tick marks. For the example above, you would get text labels: "0", "10", "20", "30", "40", "50". The label table is then set on the slider by calling setLabelTable.

Parameters:
n - new value for the majorTickSpacing property
See Also:
getMajorTickSpacing(), setPaintTicks(boolean), setLabelTable(java.util.Dictionary), createStandardLabels(int)

getMinorTickSpacing

public int getMinorTickSpacing()
This method returns the minor tick spacing. The number that is returned represents the distance, measured in values, between each minor tick mark. If you have a slider with a range from 0 to 50 and the minor tick spacing is set to 10, you will get minor ticks next to the following values: 0, 10, 20, 30, 40, 50.

Returns:
the number of values between minor ticks
See Also:
getMinorTickSpacing()

setMinorTickSpacing

public void setMinorTickSpacing(int n)
This method sets the minor tick spacing. The number that is passed in represents the distance, measured in values, between each minor tick mark. If you have a slider with a range from 0 to 50 and the minor tick spacing is set to 10, you will get minor ticks next to the following values: 0, 10, 20, 30, 40, 50.

In order for minor ticks to be painted, setPaintTicks must be set to true.

Parameters:
n - new value for the minorTickSpacing property
See Also:
getMinorTickSpacing(), setPaintTicks(boolean)

getSnapToTicks

public boolean getSnapToTicks()
Returns true if the knob (and the data value it represents) resolve to the closest tick mark next to where the user positioned the knob.

Returns:
true if the value snaps to the nearest tick mark, else false
See Also:
setSnapToTicks(boolean)

setSnapToTicks

public void setSnapToTicks(boolean b)
Specifying true makes the knob (and the data value it represents) resolve to the closest tick mark next to where the user positioned the knob. By default, this property is false.

Parameters:
b - true to snap the knob to the nearest tick mark
See Also:
getSnapToTicks()

getPaintTicks

public boolean getPaintTicks()
Tells if tick marks are to be painted.

Returns:
true if tick marks are painted, else false
See Also:
setPaintTicks(boolean)

setPaintTicks

public void setPaintTicks(boolean b)
Determines whether tick marks are painted on the slider. By default, this property is false.

Parameters:
b - whether or not tick marks should be painted
See Also:
getPaintTicks()

getPaintTrack

public boolean getPaintTrack()
Tells if the track (area the slider slides in) is to be painted.

Returns:
true if track is painted, else false
See Also:
setPaintTrack(boolean)

setPaintTrack

public void setPaintTrack(boolean b)
Determines whether the track is painted on the slider. By default, this property is true.

Parameters:
b - whether or not to paint the slider track
See Also:
getPaintTrack()

getPaintLabels

public boolean getPaintLabels()
Tells if labels are to be painted.

Returns:
true if labels are painted, else false
See Also:
setPaintLabels(boolean)

setPaintLabels

public void setPaintLabels(boolean b)
Determines whether labels are painted on the slider.

This method will also set up a label table for you. If there is not already a label table, and the major tick spacing is > 0, a standard label table will be generated (by calling createStandardLabels) with labels at the major tick marks. The label table is then set on the slider by calling setLabelTable.

By default, this property is false.

Parameters:
b - whether or not to paint labels
See Also:
getPaintLabels(),
getLabelTable(),
createStandardLabels(int)

paramString

protected String paramString()
Returns a string representation of this JSlider. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JSlider.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JSlider. For sliders, the AccessibleContext takes the form of an AccessibleJSlider. A new AccessibleJSlider instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJSlider that serves as the AccessibleContext of this JSlider
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JSlider.AccessibleJSlider

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JSlider.AccessibleJSlider

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JSlider.AccessibleJSlider
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent, AccessibleValue
Enclosing class:
JSlider
protected class JSlider.AccessibleJSlider
extends JComponent.AccessibleJComponent
implements AccessibleValue

This class implements accessibility support for the JSlider class. It provides an implementation of the Java Accessibility API appropriate to slider user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JSlider.AccessibleJSlider()
Method Summary
AccessibleRole | getAccessibleRole() Get the role of this object.
AccessibleStateSet | getAccessibleStateSet() Get the state set of this object.
AccessibleValue | getAccessibleValue() Get the AccessibleValue associated with this object.
Number | getCurrentAccessibleValue() Get the accessible value of this object.
Number | getMaximumAccessibleValue() Get the maximum accessible value of this object.
Number | getMinimumAccessibleValue() Get the minimum accessible value of this object.
boolean | setCurrentAccessibleValue(Number n) Set the value of this object as a Number.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JSlider.AccessibleJSlider

protected JSlider.AccessibleJSlider()
Method Detail

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Get the state set of this object.

Overrides:
getAccessibleStateSet in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleState containing the current state of the object
See Also:
AccessibleState

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleValue

public AccessibleValue getAccessibleValue()
Get the AccessibleValue associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleValue interface on behalf of itself.

Overrides:
getAccessibleValue in class AccessibleContext
Returns:
this object
See Also:
AccessibleValue

getCurrentAccessibleValue

public Number getCurrentAccessibleValue()
Get the accessible value of this object.

Specified by:
getCurrentAccessibleValue in interface AccessibleValue
Returns:
The current value of this object.
See Also:
AccessibleValue.setCurrentAccessibleValue(java.lang.Number)

setCurrentAccessibleValue

public boolean setCurrentAccessibleValue(Number n)
Set the value of this object as a Number.

Specified by:
setCurrentAccessibleValue in interface AccessibleValue
Returns:
True if the value was set.
See Also:
AccessibleValue.getCurrentAccessibleValue()

getMinimumAccessibleValue

public Number getMinimumAccessibleValue()
Get the minimum accessible value of this object.

Specified by:
getMinimumAccessibleValue in interface AccessibleValue
Returns:
The minimum value of this object.
See Also:
AccessibleValue.getMaximumAccessibleValue()

getMaximumAccessibleValue

public Number getMaximumAccessibleValue()
Get the maximum accessible value of this object.

Specified by:
getMaximumAccessibleValue in interface AccessibleValue
Returns:
The maximum value of this object.
See Also:
AccessibleValue.getMinimumAccessibleValue()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JSpinner

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JSpinner

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JSpinner
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public class JSpinner
extends JComponent
implements Accessible

A single line input field that lets the user select a number or an object value from an ordered sequence. Spinners typically provide a pair of tiny arrow buttons for stepping through the elements of the sequence. The keyboard up/down arrow keys also cycle through the elements. The user may also be allowed to type a (legal) value directly into the spinner. Although combo boxes provide similar functionality, spinners are sometimes preferred because they don't require a drop down list that can obscure important data.

A JSpinner's sequence value is defined by its SpinnerModel. The model can be specified as a constructor argument and changed with the model property. SpinnerModel classes for some common types are provided: SpinnerListModel, SpinnerNumberModel, and SpinnerDateModel.

A JSpinner has a single child component that's responsible for displaying and potentially changing the current element or value of the model, which is called the editor. The editor is created by the JSpinner's constructor and can be changed with the editor property. The JSpinner's editor stays in sync with the model by listening for ChangeEvents. If the user has changed the value displayed by the editor it is possible for the model's value to differ from that of the editor. To make sure the model has the same value as the editor use the commitEdit method, eg:

   try {
       spinner.commitEdit();
   }
   catch (ParseException pe) {{
       // Edited value is invalid, spinner.getValue() will return
       // the last valid value, you could revert the spinner to show that:
       JComponent editor = spinner.getEditor()
       if (editor instanceof DefaultEditor) {
           ((DefaultEditor)editor).getTextField().setValue(spinner.getValue();
       }
       // reset the value to some known value:
       spinner.setValue(fallbackValue);
       // or treat the last valid value as the current, in which
       // case you don't need to do anything.
   }
   return spinner.getValue();

For information and examples of using spinner see How to Use Spinners, a section in The Java Tutorial.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Since:
1.4
See Also:
SpinnerModel, AbstractSpinnerModel, SpinnerListModel, SpinnerNumberModel, SpinnerDateModel, JFormattedTextField

Nested Class Summary
protected class | JSpinner.AccessibleJSpinner AccessibleJSpinner implements accessibility support for the JSpinner class.
static class | JSpinner.DateEditor An editor for a JSpinner whose model is a SpinnerDateModel.
static class | JSpinner.DefaultEditor A simple base class for more specialized editors that displays a read-only view of the model's current value with a JFormattedTextField.
static class | JSpinner.ListEditor An editor for a JSpinner whose model is a SpinnerListModel.
static class | JSpinner.NumberEditor An editor for a JSpinner whose model is a SpinnerNumberModel.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JSpinner()
Constructs a spinner with an Integer SpinnerNumberModel with initial value 0 and no minimum or maximum limits.
JSpinner(SpinnerModel model)
Constructs a complete spinner with pair of next/previous buttons and an editor for the SpinnerModel.
Method Summary
 void addChangeListener(ChangeListener listener)
Adds a listener to the list that is notified each time a change to the model occurs.
 void commitEdit()
Commits the currently edited value to the SpinnerModel.
protected  JComponent createEditor(SpinnerModel model)
This method is called by the constructors to create the JComponent that displays the current value of the sequence.
protected  void fireStateChanged()
Sends a ChangeEvent, whose source is this JSpinner, to each ChangeListener.
 AccessibleContext getAccessibleContext()
Gets the AccessibleContext for the JSpinner
 ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this JSpinner with addChangeListener().
 JComponent getEditor()
Returns the component that displays and potentially changes the model's value.
 SpinnerModel getModel()
Returns the SpinnerModel that defines this spinners sequence of values.
 Object getNextValue()
Returns the object in the sequence that comes after the object returned by getValue().
 Object getPreviousValue()
Returns the object in the sequence that comes before the object returned by getValue().
 SpinnerUI getUI()
Returns the look and feel (L&F) object that renders this component.
 String getUIClassID()
Returns the suffix used to construct the name of the look and feel (L&F) class used to render this component.
 Object getValue()
Returns the current value of the model, typically this value is displayed by the editor.
 void removeChangeListener(ChangeListener listener)
Removes a ChangeListener from this spinner.
 void setEditor(JComponent editor)
Changes the JComponent that displays the current value of the SpinnerModel.
 void setModel(SpinnerModel model)
Changes the model that represents the value of this spinner.
 void setUI(SpinnerUI ui)
Sets the look and feel (L&F) object that renders this component.
 void setValue(Object value)
Changes current value of the model, typically this value is displayed by the editor.
 void updateUI()
Resets the UI property with the value from the current look and feel.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JSpinner

public JSpinner(SpinnerModel model)
Constructs a complete spinner with pair of next/previous buttons and an editor for the SpinnerModel.

JSpinner

public JSpinner()
Constructs a spinner with an Integer SpinnerNumberModel with initial value 0 and no minimum or maximum limits.

Method Detail

getUI

public SpinnerUI getUI()
Returns the look and feel (L&F) object that renders this component.

Returns:
the SpinnerUI object that renders this component

setUI

public void setUI(SpinnerUI ui)
Sets the look and feel (L&F) object that renders this component.

Parameters:
ui - the SpinnerUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

getUIClassID

public String getUIClassID()
Returns the suffix used to construct the name of the look and feel (L&F) class used to render this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "SpinnerUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Resets the UI property with the value from the current look and feel.

Overrides:
updateUI in class JComponent
See Also:
UIManager.getUI(javax.swing.JComponent)

createEditor

protected JComponent createEditor(SpinnerModel model)
This method is called by the constructors to create the JComponent that displays the current value of the sequence. The editor may also allow the user to enter an element of the sequence directly. An editor must listen for ChangeEvents on the model and keep the value it displays in sync with the value of the model.

Subclasses may override this method to add support for new SpinnerModel classes. Alternatively one can just replace the editor created here with the setEditor method. The default mapping from model type to editor is:

  • SpinnerNumberModel => JSpinner.NumberEditor
  • SpinnerDateModel => JSpinner.DateEditor
  • SpinnerListModel => JSpinner.ListEditor
  • all others => JSpinner.DefaultEditor

Parameters:
model - the value of getModel
Returns:
a component that displays the current value of the sequence
See Also:
getModel(), setEditor(javax.swing.JComponent)

setModel

public void setModel(SpinnerModel model)
Changes the model that represents the value of this spinner. If the editor property has not been explicitly set, the editor property is (implicitly) set after the "model" PropertyChangeEvent has been fired. The editor property is set to the value returned by createEditor, as in:
 setEditor(createEditor(model));

Parameters:
model - the new SpinnerModel
Throws:
IllegalArgumentException - if model is null
See Also:
getModel(),
getEditor(),
setEditor(javax.swing.JComponent)

getModel

public SpinnerModel getModel()
Returns the SpinnerModel that defines this spinners sequence of values.

Returns:
the value of the model property
See Also:
setModel(javax.swing.SpinnerModel)

getValue

public Object getValue()
Returns the current value of the model, typically this value is displayed by the editor. If the user has changed the value displayed by the editor it is possible for the model's value to differ from that of the editor, refer to the class level javadoc for examples of how to deal with this.

This method simply delegates to the model. It is equivalent to:

 getModel().getValue()

See Also:
setValue(java.lang.Object), SpinnerModel.getValue()

setValue

public void setValue(Object value)
Changes current value of the model, typically this value is displayed by the editor. If the SpinnerModel implementation doesn't support the specified value then an IllegalArgumentException is thrown.

This method simply delegates to the model. It is equivalent to:

 getModel().setValue(value)

Throws:
IllegalArgumentException - if value isn't allowed
See Also:
getValue(), SpinnerModel.setValue(java.lang.Object)

getNextValue

public Object getNextValue()
Returns the object in the sequence that comes after the object returned by getValue(). If the end of the sequence has been reached then return null. Calling this method does not effect value.

This method simply delegates to the model. It is equivalent to:

 getModel().getNextValue()

Returns:
the next legal value or null if one doesn't exist
See Also:
getValue(),
getPreviousValue(),
SpinnerModel.getNextValue()

addChangeListener

public void addChangeListener(ChangeListener listener)
Adds a listener to the list that is notified each time a change to the model occurs. The source of ChangeEvents delivered to ChangeListeners will be this JSpinner. Note also that replacing the model will not affect listeners added directly to JSpinner. Applications can add listeners to the model directly. In that case is that the source of the event would be the SpinnerModel.

Parameters:
listener - the ChangeListener to add
See Also:
removeChangeListener(javax.swing.event.ChangeListener), getModel()

removeChangeListener

public void removeChangeListener(ChangeListener listener)
Removes a ChangeListener from this spinner.

Parameters:
listener - the ChangeListener to remove
See Also:
fireStateChanged(), addChangeListener(javax.swing.event.ChangeListener)

getChangeListeners

public ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this JSpinner with addChangeListener().

Returns:
all of the ChangeListeners added or an empty array if no listeners have been added
Since:
1.4

fireStateChanged

protected void fireStateChanged()
Sends a ChangeEvent, whose source is this JSpinner, to each ChangeListener. When a ChangeListener has been added to the spinner, this method method is called each time a ChangeEvent is received from the model.

See Also:
addChangeListener(javax.swing.event.ChangeListener), removeChangeListener(javax.swing.event.ChangeListener), EventListenerList

getPreviousValue

public Object getPreviousValue()
Returns the object in the sequence that comes before the object returned by getValue(). If the end of the sequence has been reached then return null. Calling this method does not effect value.

This method simply delegates to the model. It is equivalent to:

 getModel().getPreviousValue()

Returns:
the previous legal value or null if one doesn't exist
See Also:
getValue(),
getNextValue(),
SpinnerModel.getPreviousValue()

setEditor

public void setEditor(JComponent editor)
Changes the JComponent that displays the current value of the SpinnerModel. It is the responsibility of this method to disconnect the old editor from the model and to connect the new editor. This may mean removing the old editors ChangeListener from the model or the spinner itself and adding one for the new editor.

Parameters:
editor - the new editor
Throws:
IllegalArgumentException - if editor is null
See Also:
getEditor(),
createEditor(javax.swing.SpinnerModel),
getModel()

getEditor

public JComponent getEditor()
Returns the component that displays and potentially changes the model's value.

Returns:
the component that displays and potentially changes the model's value
See Also:
setEditor(javax.swing.JComponent), createEditor(javax.swing.SpinnerModel)

commitEdit

public void commitEdit()
                throws ParseException
Commits the currently edited value to the SpinnerModel.

If the editor is an instance of DefaultEditor, the call if forwarded to the editor, otherwise this does nothing.

Throws:
ParseException - if the currently edited value couldn't be commited.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext for the JSpinner

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
the AccessibleContext for the JSpinner
Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JSpinner.AccessibleJSpinner

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JSpinner.AccessibleJSpinner

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JSpinner.AccessibleJSpinner
All Implemented Interfaces:
Serializable, EventListener, AccessibleAction, AccessibleComponent, AccessibleEditableText, AccessibleExtendedComponent, AccessibleText, AccessibleValue, ChangeListener
Enclosing class:
JSpinner
protected class JSpinner.AccessibleJSpinner
extends JComponent.AccessibleJComponent
implements AccessibleValue, AccessibleAction, AccessibleText, AccessibleEditableText, ChangeListener

AccessibleJSpinner implements accessibility support for the JSpinner class.

Since:
1.5

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Constructor Summary
protected JSpinner.AccessibleJSpinner()
AccessibleJSpinner constructor
Method Summary
void | cut(int startIndex, int endIndex) Cuts the text between two indices into the system clipboard.
void | delete(int startIndex, int endIndex) Deletes the text between two indices
boolean | doAccessibleAction(int i) Performs the specified Action on the object
AccessibleAction | getAccessibleAction() Gets the AccessibleAction associated with this object that supports one or more actions.
int | getAccessibleActionCount() Returns the number of accessible actions available in this object If there are more than one, the first one is considered the "default" action of the object.
String | getAccessibleActionDescription(int i) Returns a description of the specified action of the object.
Accessible | getAccessibleChild(int i) Returns the specified Accessible child of the object.
int | getAccessibleChildrenCount() Returns the number of accessible children of the object.
AccessibleRole | getAccessibleRole() Gets the role of this object.
AccessibleText | getAccessibleText() Gets the AccessibleText associated with this object presenting text on the display.
AccessibleValue | getAccessibleValue() Gets the AccessibleValue associated with this object.
String | getAfterIndex(int part, int index) Returns the String after a given index.
String | getAtIndex(int part, int index) Returns the String at a given index.
String | getBeforeIndex(int part, int index) Returns the String before a given index.
int | getCaretPosition() Returns the zero-based offset of the caret.
AttributeSet | getCharacterAttribute(int i) Returns the AttributeSet for a given character at a given index
Rectangle | getCharacterBounds(int i) Determines the bounding box of the character at the given index into the string.
int | getCharCount() Returns the number of characters (valid indicies)
Number | getCurrentAccessibleValue() Get the value of this object as a Number.
int | getIndexAtPoint(Point p) Given a point in local coordinates, return the zero-based index of the character under that Point.
Number | getMaximumAccessibleValue() Get the maximum value of this object as a Number.
Number | getMinimumAccessibleValue() Get the minimum value of this object as a Number.
String | getSelectedText() Returns the portion of the text that is selected.
int | getSelectionEnd() Returns the end offset within the selected text.
int | getSelectionStart() Returns the start offset within the selected text.
String | getTextRange(int startIndex, int endIndex) Returns the text string between two indices.
void | insertTextAtIndex(int index, String s) Inserts the specified string at the given index/
void | paste(int startIndex) Pastes the text from the system clipboard into the text starting at the specified index.
void | replaceText(int startIndex, int endIndex, String s) Replaces the text between two indices with the specified string.
void | selectText(int startIndex, int endIndex) Selects the text between two indices.
void | setAttributes(int startIndex, int endIndex, AttributeSet as) Sets attributes for the text between two indices.
boolean | setCurrentAccessibleValue(Number n) Set the value of this object as a Number.
void | setTextContents(String s) Sets the text contents to the specified string.
void | stateChanged(ChangeEvent e) Invoked when the target of the listener has changed its state.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JSpinner.AccessibleJSpinner

protected JSpinner.AccessibleJSpinner()
AccessibleJSpinner constructor

Method Detail

stateChanged

public void stateChanged(ChangeEvent e)
Invoked when the target of the listener has changed its state.

Specified by:
stateChanged in interface ChangeListener
Parameters:
e - a ChangeEvent object. Must not be null.
Throws:
NullPointerException - if the parameter is null.

getAccessibleRole

public AccessibleRole getAccessibleRole()
Gets the role of this object. The role of the object is the generic purpose or use of the class of this object. For example, the role of a push button is AccessibleRole.PUSH_BUTTON. The roles in AccessibleRole are provided so component developers can pick from a set of predefined roles. This enables assistive technologies to provide a consistent interface to various tweaked subclasses of components (e.g., use AccessibleRole.PUSH_BUTTON for all components that act like a push button) as well as distinguish between sublasses that behave differently (e.g., AccessibleRole.CHECK_BOX for check boxes and AccessibleRole.RADIO_BUTTON for radio buttons).

Note that the AccessibleRole class is also extensible, so custom component developers can define their own AccessibleRole's if the set of predefined roles is inadequate.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleChildrenCount

public int getAccessibleChildrenCount()
Returns the number of accessible children of the object.

Overrides:
getAccessibleChildrenCount in class JComponent.AccessibleJComponent
Returns:
the number of accessible children of the object.

getAccessibleChild

public Accessible getAccessibleChild(int i)
Returns the specified Accessible child of the object. The Accessible children of an Accessible object are zero-based, so the first child of an Accessible child is at index 0, the second child is at index 1, and so on.

Overrides:
getAccessibleChild in class JComponent.AccessibleJComponent
Parameters:
i - zero-based index of child
Returns:
the Accessible child of the object
See Also:
getAccessibleChildrenCount()

getAccessibleAction

public AccessibleAction getAccessibleAction()
Gets the AccessibleAction associated with this object that supports one or more actions.

Overrides:
getAccessibleAction in class AccessibleContext
Returns:
AccessibleAction if supported by object; else return null
See Also:
AccessibleAction

getAccessibleText

public AccessibleText getAccessibleText()
Gets the AccessibleText associated with this object presenting text on the display.

Overrides:
getAccessibleText in class AccessibleContext
Returns:
AccessibleText if supported by object; else return null
See Also:
AccessibleText

getAccessibleValue

public AccessibleValue getAccessibleValue()
Gets the AccessibleValue associated with this object.

Overrides:
getAccessibleValue in class AccessibleContext
Returns:
AccessibleValue if supported by object; else return null
See Also:
AccessibleValue

getCurrentAccessibleValue

public Number getCurrentAccessibleValue()
Get the value of this object as a Number. If the value has not been set, the return value will be null.

Specified by:
getCurrentAccessibleValue in interface AccessibleValue
Returns:
value of the object
See Also:
setCurrentAccessibleValue(java.lang.Number)

setCurrentAccessibleValue

public boolean setCurrentAccessibleValue(Number n)
Set the value of this object as a Number.

Specified by:
setCurrentAccessibleValue in interface AccessibleValue
Parameters:
n - the value to set for this object
Returns:
true if the value was set; else False
See Also:
getCurrentAccessibleValue()

getMinimumAccessibleValue

public Number getMinimumAccessibleValue()
Get the minimum value of this object as a Number.

Specified by:
getMinimumAccessibleValue in interface AccessibleValue
Returns:
Minimum value of the object; null if this object does not have a minimum value
See Also:
getMaximumAccessibleValue()

getMaximumAccessibleValue

public Number getMaximumAccessibleValue()
Get the maximum value of this object as a Number.

Specified by:
getMaximumAccessibleValue in interface AccessibleValue
Returns:
Maximum value of the object; null if this object does not have a maximum value
See Also:
getMinimumAccessibleValue()

getAccessibleActionCount

public int getAccessibleActionCount()
Returns the number of accessible actions available in this object If there are more than one, the first one is considered the "default" action of the object. Two actions are supported: AccessibleAction.INCREMENT which increments the spinner value and AccessibleAction.DECREMENT which decrements the spinner value

Specified by:
getAccessibleActionCount in interface AccessibleAction
Returns:
the zero-based number of Actions in this object

getAccessibleActionDescription

public String getAccessibleActionDescription(int i)
Returns a description of the specified action of the object.

Specified by:
getAccessibleActionDescription in interface AccessibleAction
Parameters:
i - zero-based index of the actions
Returns:
a String description of the action
See Also:
getAccessibleActionCount()

doAccessibleAction

public boolean doAccessibleAction(int i)
Performs the specified Action on the object

Specified by:
doAccessibleAction in interface AccessibleAction
Parameters:
i - zero-based index of actions. The first action (index 0) is AccessibleAction.INCREMENT and the second action (index 1) is AccessibleAction.DECREMENT.
Returns:
true if the action was performed; otherwise false.
See Also:
getAccessibleActionCount()

getIndexAtPoint

public int getIndexAtPoint(Point p)
Given a point in local coordinates, return the zero-based index of the character under that Point. If the point is invalid, this method returns -1.

Specified by:
getIndexAtPoint in interface AccessibleText
Parameters:
p - the Point in local coordinates
Returns:
the zero-based index of the character under Point p; if Point is invalid return -1.

getCharacterBounds

public Rectangle getCharacterBounds(int i)
Determines the bounding box of the character at the given index into the string. The bounds are returned in local coordinates. If the index is invalid an empty rectangle is returned.

Specified by:
getCharacterBounds in interface AccessibleText
Parameters:
i - the index into the String
Returns:
the screen coordinates of the character's bounding box, if index is invalid return an empty rectangle.

getCharCount

public int getCharCount()
Returns the number of characters (valid indicies)

Specified by:
getCharCount in interface AccessibleText
Returns:
the number of characters

getCaretPosition

public int getCaretPosition()
Returns the zero-based offset of the caret. Note: That to the right of the caret will have the same index value as the offset (the caret is between two characters).

Specified by:
getCaretPosition in interface AccessibleText
Returns:
the zero-based offset of the caret.

getAtIndex

public String getAtIndex(int part,
                         int index)
Returns the String at a given index.

Specified by:
getAtIndex in interface AccessibleText
Parameters:
part - the CHARACTER, WORD, or SENTENCE to retrieve
index - an index within the text
Returns:
the letter, word, or sentence

getAfterIndex

public String getAfterIndex(int part,
                            int index)
Returns the String after a given index.

Specified by:
getAfterIndex in interface AccessibleText
Parameters:
part - the CHARACTER, WORD, or SENTENCE to retrieve
index - an index within the text
Returns:
the letter, word, or sentence

getBeforeIndex

public String getBeforeIndex(int part,
                             int index)
Returns the String before a given index.

Specified by:
getBeforeIndex in interface AccessibleText
Parameters:
part - the CHARACTER, WORD, or SENTENCE to retrieve
index - an index within the text
Returns:
the letter, word, or sentence

getCharacterAttribute

public AttributeSet getCharacterAttribute(int i)
Returns the AttributeSet for a given character at a given index

Specified by:
getCharacterAttribute in interface AccessibleText
Parameters:
i - the zero-based index into the text
Returns:
the AttributeSet of the character

getSelectionStart

public int getSelectionStart()
Returns the start offset within the selected text. If there is no selection, but there is a caret, the start and end offsets will be the same.

Specified by:
getSelectionStart in interface AccessibleText
Returns:
the index into the text of the start of the selection

getSelectionEnd

public int getSelectionEnd()
Returns the end offset within the selected text. If there is no selection, but there is a caret, the start and end offsets will be the same.

Specified by:
getSelectionEnd in interface AccessibleText
Returns:
the index into teh text of the end of the selection

getSelectedText

public String getSelectedText()
Returns the portion of the text that is selected.

Specified by:
getSelectedText in interface AccessibleText
Returns:
the String portion of the text that is selected

setTextContents

public void setTextContents(String s)
Sets the text contents to the specified string.

Specified by:
setTextContents in interface AccessibleEditableText
Parameters:
s - the string to set the text contents

insertTextAtIndex

public void insertTextAtIndex(int index,
                              String s)
Inserts the specified string at the given index/

Specified by:
insertTextAtIndex in interface AccessibleEditableText
Parameters:
index - the index in the text where the string will be inserted
s - the string to insert in the text

getTextRange

public String getTextRange(int startIndex,
                           int endIndex)
Returns the text string between two indices.

Specified by:
getTextRange in interface AccessibleEditableText
Parameters:
startIndex - the starting index in the text
endIndex - the ending index in the text
Returns:
the text string between the indices

delete

public void delete(int startIndex,
                   int endIndex)
Deletes the text between two indices

Specified by:
delete in interface AccessibleEditableText
Parameters:
startIndex - the starting index in the text
endIndex - the ending index in the text

cut

public void cut(int startIndex,
                int endIndex)
Cuts the text between two indices into the system clipboard.

Specified by:
cut in interface AccessibleEditableText
Parameters:
startIndex - the starting index in the text
endIndex - the ending index in the text

paste

public void paste(int startIndex)
Pastes the text from the system clipboard into the text starting at the specified index.

Specified by:
paste in interface AccessibleEditableText
Parameters:
startIndex - the starting index in the text

replaceText

public void replaceText(int startIndex,
                        int endIndex,
                        String s)
Replaces the text between two indices with the specified string.

Specified by:
replaceText in interface AccessibleEditableText
Parameters:
startIndex - the starting index in the text
endIndex - the ending index in the text
s - the string to replace the text between two indices

selectText

public void selectText(int startIndex,
                       int endIndex)
Selects the text between two indices.

Specified by:
selectText in interface AccessibleEditableText
Parameters:
startIndex - the starting index in the text
endIndex - the ending index in the text

setAttributes

public void setAttributes(int startIndex,
                          int endIndex,
                          AttributeSet as)
Sets attributes for the text between two indices.

Specified by:
setAttributes in interface AccessibleEditableText
Parameters:
startIndex - the starting index in the text
endIndex - the ending index in the text
as - the attribute set
See Also:
AttributeSet
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JSpinner.DateEditor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JSpinner.DateEditor

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JPanel
                    extended by  javax.swing.JSpinner.DefaultEditor
                        extended by  javax.swing.JSpinner.DateEditor
All Implemented Interfaces:
ImageObserver, LayoutManager, MenuContainer, PropertyChangeListener, Serializable, EventListener, Accessible, ChangeListener
Enclosing class:
JSpinner
public static class JSpinner.DateEditor
extends JSpinner.DefaultEditor

An editor for a JSpinner whose model is a SpinnerDateModel. The value of the editor is displayed with a JFormattedTextField whose format is defined by a DateFormatter instance whose minimum and maximum properties are mapped to the SpinnerDateModel.

Since:
1.4

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JPanel
JPanel.AccessibleJPanel
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JSpinner.DateEditor(JSpinner spinner)
Construct a JSpinner editor that supports displaying and editing the value of a SpinnerDateModel with a JFormattedTextField.
JSpinner.DateEditor(JSpinner spinner, String dateFormatPattern)
Construct a JSpinner editor that supports displaying and editing the value of a SpinnerDateModel with a JFormattedTextField.
Method Summary
SimpleDateFormat | getFormat() Returns the java.text.SimpleDateFormat object the JFormattedTextField uses to parse and format numbers.
SpinnerDateModel | getModel() Return our spinner ancestor's SpinnerDateModel.
Methods inherited from class javax.swing.JSpinner.DefaultEditor
addLayoutComponent, commitEdit, dismiss, getBaseline, getBaselineResizeBehavior, getSpinner, getTextField, layoutContainer, minimumLayoutSize, preferredLayoutSize, propertyChange, removeLayoutComponent, stateChanged
Methods inherited from class javax.swing.JPanel
getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JSpinner.DateEditor

public JSpinner.DateEditor(JSpinner spinner)
Construct a JSpinner editor that supports displaying and editing the value of a SpinnerDateModel with a JFormattedTextField. This DateEditor becomes both a ChangeListener on the spinners model and a PropertyChangeListener on the new JFormattedTextField.

Parameters:
spinner - the spinner whose model this editor will monitor
Throws:
IllegalArgumentException - if the spinners model is not an instance of SpinnerDateModel
See Also:
getModel(), getFormat(), SpinnerDateModel

JSpinner.DateEditor

public JSpinner.DateEditor(JSpinner spinner,
                           String dateFormatPattern)
Construct a JSpinner editor that supports displaying and editing the value of a SpinnerDateModel with a JFormattedTextField. This DateEditor becomes both a ChangeListener on the spinner and a PropertyChangeListener on the new JFormattedTextField.

Parameters:
spinner - the spinner whose model this editor will monitor
dateFormatPattern - the initial pattern for the SimpleDateFormat object that's used to display and parse the value of the text field.
Throws:
IllegalArgumentException - if the spinners model is not an instance of SpinnerDateModel
See Also:
getModel(), getFormat(), SpinnerDateModel, SimpleDateFormat
Method Detail

getFormat

public SimpleDateFormat getFormat()
Returns the java.text.SimpleDateFormat object the JFormattedTextField uses to parse and format numbers.

Returns:
the value of getTextField().getFormatter().getFormat().
See Also:
JSpinner.DefaultEditor.getTextField(), SimpleDateFormat

getModel

public SpinnerDateModel getModel()
Return our spinner ancestor's SpinnerDateModel.

Returns:
getSpinner().getModel()
See Also:
JSpinner.DefaultEditor.getSpinner(), JSpinner.DefaultEditor.getTextField()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JSpinner.DefaultEditor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JSpinner.DefaultEditor

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JPanel
                    extended by  javax.swing.JSpinner.DefaultEditor
All Implemented Interfaces:
ImageObserver, LayoutManager, MenuContainer, PropertyChangeListener, Serializable, EventListener, Accessible, ChangeListener
Direct Known Subclasses:
JSpinner.DateEditor, JSpinner.ListEditor, JSpinner.NumberEditor
Enclosing class:
JSpinner
public static class JSpinner.DefaultEditor
extends JPanel
implements ChangeListener, PropertyChangeListener, LayoutManager

A simple base class for more specialized editors that displays a read-only view of the model's current value with a JFormattedTextField. Subclasses can configure the JFormattedTextField to create an editor that's appropriate for the type of model they support and they may want to override the stateChanged and propertyChanged methods, which keep the model and the text field in sync.

This class defines a dismiss method that removes the editors ChangeListener from the JSpinner that it's part of. The setEditor method knows about DefaultEditor.dismiss, so if the developer replaces an editor that's derived from JSpinner.DefaultEditor its ChangeListener connection back to the JSpinner will be removed. However after that, it's up to the developer to manage their editor listeners. Similarly, if a subclass overrides createEditor, it's up to the subclasser to deal with their editor subsequently being replaced (with setEditor). We expect that in most cases, and in editor installed with setEditor or created by a createEditor override, will not be replaced anyway.

This class is the LayoutManager for it's single JFormattedTextField child. By default the child is just centered with the parents insets.

Since:
1.4

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JPanel
JPanel.AccessibleJPanel
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JSpinner.DefaultEditor(JSpinner spinner)
Constructs an editor component for the specified JSpinner.
Method Summary
void | addLayoutComponent(String name, Component child) This LayoutManager method does nothing.
void | commitEdit() Pushes the currently edited value to the SpinnerModel.
void | dismiss(JSpinner spinner) Disconnect this editor from the specified JSpinner.
int | getBaseline(int width, int height) Returns the baseline.
Component.BaselineResizeBehavior | getBaselineResizeBehavior() Returns an enum indicating how the baseline of the component changes as the size changes.
JSpinner | getSpinner() Returns the JSpinner ancestor of this editor or null if none of the ancestors are a JSpinner.
JFormattedTextField | getTextField() Returns the JFormattedTextField child of this editor.
void | layoutContainer(Container parent) Resize the one (and only) child to completely fill the area within the parents insets.
Dimension | minimumLayoutSize(Container parent) Returns the minimum size of first (and only) child plus the size of the parents insets.
Dimension | preferredLayoutSize(Container parent) Returns the preferred size of first (and only) child plus the size of the parents insets.
void | propertyChange(PropertyChangeEvent e) Called by the JFormattedTextField PropertyChangeListener.
void | removeLayoutComponent(Component child) This LayoutManager method does nothing.
void | stateChanged(ChangeEvent e) This method is called when the spinner's model's state changes.
Methods inherited from class javax.swing.JPanel
getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JSpinner.DefaultEditor

public JSpinner.DefaultEditor(JSpinner spinner)
Constructs an editor component for the specified JSpinner. This DefaultEditor is it's own layout manager and it is added to the spinner's ChangeListener list. The constructor creates a single JFormattedTextField child, initializes it's value to be the spinner model's current value and adds it to this DefaultEditor.

Parameters:
spinner - the spinner whose model this editor will monitor
See Also:
getTextField(), JSpinner.addChangeListener(javax.swing.event.ChangeListener)
Method Detail

dismiss

public void dismiss(JSpinner spinner)
Disconnect this editor from the specified JSpinner. By default, this method removes itself from the spinners ChangeListener list.

Parameters:
spinner - the JSpinner to disconnect this editor from; the same spinner as was passed to the constructor.

getSpinner

public JSpinner getSpinner()
Returns the JSpinner ancestor of this editor or null if none of the ancestors are a JSpinner. Typically the editor's parent is a JSpinner however subclasses of JSpinner may override the the createEditor method and insert one or more containers between the JSpinner and it's editor.

Returns:
JSpinner ancestor; null if none of the ancestors are a JSpinner
See Also:
JSpinner.createEditor(javax.swing.SpinnerModel)

getTextField

public JFormattedTextField getTextField()
Returns the JFormattedTextField child of this editor. By default the text field is the first and only child of editor.

Returns:
the JFormattedTextField that gives the user access to the SpinnerDateModel's value.
See Also:
getSpinner(), JSpinner.getModel()

stateChanged

public void stateChanged(ChangeEvent e)
This method is called when the spinner's model's state changes. It sets the value of the text field to the current value of the spinners model.

Specified by:
stateChanged in interface ChangeListener
Parameters:
e - the ChangeEvent whose source is the JSpinner whose model has changed.
See Also:
getTextField(), JSpinner.getValue()

propertyChange

public void propertyChange(PropertyChangeEvent e)
Called by the JFormattedTextField PropertyChangeListener. When the "value" property changes, which implies that the user has typed a new number, we set the value of the spinners model.

This class ignores PropertyChangeEvents whose source is not the JFormattedTextField, so subclasses may safely make this DefaultEditor a PropertyChangeListener on other objects.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - the PropertyChangeEvent whose source is the JFormattedTextField created by this class.
See Also:
getTextField()

addLayoutComponent

public void addLayoutComponent(String name,
                               Component child)
This LayoutManager method does nothing. We're only managing a single child and there's no support for layout constraints.

Specified by:
addLayoutComponent in interface LayoutManager
Parameters:
name - ignored
child - ignored

removeLayoutComponent

public void removeLayoutComponent(Component child)
This LayoutManager method does nothing. There isn't any per-child state.

Specified by:
removeLayoutComponent in interface LayoutManager
Parameters:
child - ignored

preferredLayoutSize

public Dimension preferredLayoutSize(Container parent)
Returns the preferred size of first (and only) child plus the size of the parents insets.

Specified by:
preferredLayoutSize in interface LayoutManager
Parameters:
parent - the Container that's managing the layout
Returns:
the preferred dimensions to lay out the subcomponents of the specified container.
See Also:
LayoutManager.minimumLayoutSize(java.awt.Container)

minimumLayoutSize

public Dimension minimumLayoutSize(Container parent)
Returns the minimum size of first (and only) child plus the size of the parents insets.

Specified by:
minimumLayoutSize in interface LayoutManager
Parameters:
parent - the Container that's managing the layout
Returns:
the minimum dimensions needed to lay out the subcomponents of the specified container.
See Also:
LayoutManager.preferredLayoutSize(java.awt.Container)

layoutContainer

public void layoutContainer(Container parent)
Resize the one (and only) child to completely fill the area within the parents insets.

Specified by:
layoutContainer in interface LayoutManager
Parameters:
parent - the container to be laid out

commitEdit

public void commitEdit()
                throws ParseException
Pushes the currently edited value to the SpinnerModel.

The default implementation invokes commitEdit on the JFormattedTextField.

Throws:
ParseException - if the edited value is not legal

getBaseline

public int getBaseline(int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class JComponent
Parameters:
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
the baseline or < 0 indicating there is no reasonable baseline
Throws:
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int,int), JComponent.getBaselineResizeBehavior()

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior()
Returns an enum indicating how the baseline of the component changes as the size changes.

Overrides:
getBaselineResizeBehavior in class JComponent
Returns:
an enum indicating how the baseline changes as the component size changes
Throws:
NullPointerException
Since:
1.6
See Also:
JComponent.getBaseline(int, int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JSpinner.ListEditor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JSpinner.ListEditor

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JPanel
                    extended by  javax.swing.JSpinner.DefaultEditor
                        extended by  javax.swing.JSpinner.ListEditor
All Implemented Interfaces:
ImageObserver, LayoutManager, MenuContainer, PropertyChangeListener, Serializable, EventListener, Accessible, ChangeListener
Enclosing class:
JSpinner
public static class JSpinner.ListEditor
extends JSpinner.DefaultEditor

An editor for a JSpinner whose model is a SpinnerListModel.

Since:
1.4

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JPanel
JPanel.AccessibleJPanel
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JSpinner.ListEditor(JSpinner spinner)
Construct a JSpinner editor that supports displaying and editing the value of a SpinnerListModel with a JFormattedTextField.
Method Summary
 SpinnerListModel getModel()
Return our spinner ancestor's SpinnerNumberModel.
Methods inherited from class javax.swing.JSpinner.DefaultEditor
addLayoutComponent, commitEdit, dismiss, getBaseline, getBaselineResizeBehavior, getSpinner, getTextField, layoutContainer, minimumLayoutSize, preferredLayoutSize, propertyChange, removeLayoutComponent, stateChanged
Methods inherited from class javax.swing.JPanel
getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JSpinner.ListEditor

public JSpinner.ListEditor(JSpinner spinner)
Construct a JSpinner editor that supports displaying and editing the value of a SpinnerListModel with a JFormattedTextField. This ListEditor becomes both a ChangeListener on the spinner and a PropertyChangeListener on the new JFormattedTextField.

Parameters:
spinner - the spinner whose model this editor will monitor
Throws:
IllegalArgumentException - if the spinners model is not an instance of SpinnerListModel
See Also:
getModel(), SpinnerListModel
Method Detail

getModel

public SpinnerListModel getModel()
Return our spinner ancestor's SpinnerNumberModel.

Returns:
getSpinner().getModel()
See Also:
JSpinner.DefaultEditor.getSpinner(), JSpinner.DefaultEditor.getTextField()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JSpinner.NumberEditor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JSpinner.NumberEditor

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JPanel
                    extended by  javax.swing.JSpinner.DefaultEditor
                        extended by  javax.swing.JSpinner.NumberEditor
All Implemented Interfaces:
ImageObserver, LayoutManager, MenuContainer, PropertyChangeListener, Serializable, EventListener, Accessible, ChangeListener
Enclosing class:
JSpinner
public static class JSpinner.NumberEditor
extends JSpinner.DefaultEditor

An editor for a JSpinner whose model is a SpinnerNumberModel. The value of the editor is displayed with a JFormattedTextField whose format is defined by a NumberFormatter instance whose minimum and maximum properties are mapped to the SpinnerNumberModel.

Since:
1.4

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JPanel
JPanel.AccessibleJPanel
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JSpinner.NumberEditor(JSpinner spinner)
Construct a JSpinner editor that supports displaying and editing the value of a SpinnerNumberModel with a JFormattedTextField.
JSpinner.NumberEditor(JSpinner spinner, String decimalFormatPattern)
Construct a JSpinner editor that supports displaying and editing the value of a SpinnerNumberModel with a JFormattedTextField.
Method Summary
DecimalFormat | getFormat() Returns the java.text.DecimalFormat object the JFormattedTextField uses to parse and format numbers.
SpinnerNumberModel | getModel() Return our spinner ancestor's SpinnerNumberModel.
Methods inherited from class javax.swing.JSpinner.DefaultEditor
addLayoutComponent, commitEdit, dismiss, getBaseline, getBaselineResizeBehavior, getSpinner, getTextField, layoutContainer, minimumLayoutSize, preferredLayoutSize, propertyChange, removeLayoutComponent, stateChanged
Methods inherited from class javax.swing.JPanel
getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JSpinner.NumberEditor

public JSpinner.NumberEditor(JSpinner spinner)
Construct a JSpinner editor that supports displaying and editing the value of a SpinnerNumberModel with a JFormattedTextField. This NumberEditor becomes both a ChangeListener on the spinner and a PropertyChangeListener on the new JFormattedTextField.

Parameters:
spinner - the spinner whose model this editor will monitor
Throws:
IllegalArgumentException - if the spinners model is not an instance of SpinnerNumberModel
See Also:
getModel(), getFormat(), SpinnerNumberModel

JSpinner.NumberEditor

public JSpinner.NumberEditor(JSpinner spinner,
                             String decimalFormatPattern)
Construct a JSpinner editor that supports displaying and editing the value of a SpinnerNumberModel with a JFormattedTextField. This NumberEditor becomes both a ChangeListener on the spinner and a PropertyChangeListener on the new JFormattedTextField.

Parameters:
spinner - the spinner whose model this editor will monitor
decimalFormatPattern - the initial pattern for the DecimalFormat object that's used to display and parse the value of the text field.
Throws:
IllegalArgumentException - if the spinners model is not an instance of SpinnerNumberModel or if decimalFormatPattern is not a legal argument to DecimalFormat
See Also:
JSpinner.DefaultEditor.getTextField(), SpinnerNumberModel, DecimalFormat
Method Detail

getFormat

public DecimalFormat getFormat()
Returns the java.text.DecimalFormat object the JFormattedTextField uses to parse and format numbers.

Returns:
the value of getTextField().getFormatter().getFormat().
See Also:
JSpinner.DefaultEditor.getTextField(), DecimalFormat

getModel

public SpinnerNumberModel getModel()
Return our spinner ancestor's SpinnerNumberModel.

Returns:
getSpinner().getModel()
See Also:
JSpinner.DefaultEditor.getSpinner(), JSpinner.DefaultEditor.getTextField()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JSplitPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JSplitPane

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JSplitPane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public class JSplitPane
extends JComponent
implements Accessible

JSplitPane is used to divide two (and only two) Components. The two Components are graphically divided based on the look and feel implementation, and the two Components can then be interactively resized by the user. Information on using JSplitPane is in How to Use Split Panes in The Java Tutorial.

The two Components in a split pane can be aligned left to right using JSplitPane.HORIZONTAL_SPLIT, or top to bottom using JSplitPane.VERTICAL_SPLIT. The preferred way to change the size of the Components is to invoke setDividerLocation where location is either the new x or y position, depending on the orientation of the JSplitPane.

To resize the Components to their preferred sizes invoke resetToPreferredSizes.

When the user is resizing the Components the minimum size of the Components is used to determine the maximum/minimum position the Components can be set to. If the minimum size of the two components is greater than the size of the split pane the divider will not allow you to resize it. To alter the minimum size of a JComponent, see JComponent.setMinimumSize(java.awt.Dimension).

When the user resizes the split pane the new space is distributed between the two components based on the resizeWeight property. A value of 0, the default, indicates the right/bottom component gets all the space, where as a value of 1 indicates the left/top component gets all the space.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
setDividerLocation(double), resetToPreferredSizes()

Nested Class Summary
protected  class JSplitPane.AccessibleJSplitPane
This class implements accessibility support for the JSplitPane class.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
static String | BOTTOM Used to add a Component below the other Component.
static String | CONTINUOUS_LAYOUT_PROPERTY Bound property name for continuousLayout.
protected boolean | continuousLayout Whether or not the views are continuously redisplayed while resizing.
static String | DIVIDER Used to add a Component that will represent the divider.
static String | DIVIDER_LOCATION_PROPERTY Bound property for the dividerLocation.
static String | DIVIDER_SIZE_PROPERTY Bound property name for border.
protected int | dividerSize Size of the divider.
static int | HORIZONTAL_SPLIT Horizontal split indicates the Components are split along the x axis.
static String | LAST_DIVIDER_LOCATION_PROPERTY Bound property for lastLocation.
protected int | lastDividerLocation Previous location of the split pane.
static String | LEFT Used to add a Component to the left of the other Component.
protected Component | leftComponent The left or top component.
static String | ONE_TOUCH_EXPANDABLE_PROPERTY Bound property for oneTouchExpandable.
protected boolean | oneTouchExpandable Is a little widget provided to quickly expand/collapse the split pane?
protected int | orientation How the views are split.
static String | ORIENTATION_PROPERTY Bound property name for orientation (horizontal or vertical).
static String | RESIZE_WEIGHT_PROPERTY Bound property for weight.
static String | RIGHT Used to add a Component to the right of the other Component.
protected Component | rightComponent The right or bottom component.
static String | TOP Used to add a Component above the other Component.
static int | VERTICAL_SPLIT Vertical split indicates the Components are split along the y axis.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JSplitPane()
Creates a new JSplitPane configured to arrange the child components side-by-side horizontally with no continuous layout, using two buttons for the components.
JSplitPane(int newOrientation)
Creates a new JSplitPane configured with the specified orientation and no continuous layout.
JSplitPane(int newOrientation, boolean newContinuousLayout)
Creates a new JSplitPane with the specified orientation and redrawing style.
JSplitPane(int newOrientation, boolean newContinuousLayout, Component newLeftComponent, Component newRightComponent)
Creates a new JSplitPane with the specified orientation and redrawing style, and with the specified components.
JSplitPane(int newOrientation, Component newLeftComponent, Component newRightComponent)
Creates a new JSplitPane with the specified orientation and with the specified components that do not do continuous redrawing.
Method Summary
protected void | addImpl(Component comp, Object constraints, int index) Adds the specified component to this split pane.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JSplitPane.
Component | getBottomComponent() Returns the component below, or to the right of the divider.
int | getDividerLocation() Returns the last value passed to setDividerLocation.
int | getDividerSize() Returns the size of the divider.
int | getLastDividerLocation() Returns the last location the divider was at.
Component | getLeftComponent() Returns the component to the left (or above) the divider.
int | getMaximumDividerLocation() Returns the maximum location of the divider from the look and feel implementation.
int | getMinimumDividerLocation() Returns the minimum location of the divider from the look and feel implementation.
int | getOrientation() Returns the orientation.
double | getResizeWeight() Returns the number that determines how extra space is distributed.
Component | getRightComponent() Returns the component to the right (or below) the divider.
Component | getTopComponent() Returns the component above, or to the left of the divider.
SplitPaneUI | getUI() Returns the SplitPaneUI that is providing the current look and feel.
String | getUIClassID() Returns the name of the L&F class that renders this component.
boolean | isContinuousLayout() Gets the continuousLayout property.
boolean | isOneTouchExpandable() Gets the oneTouchExpandable property.
boolean | isValidateRoot() Returns true, so that calls to revalidate on any descendant of this JSplitPane will cause a request to be queued that will validate the JSplitPane and all its descendants.
protected void | paintChildren(Graphics g) Subclassed to message the UI with finishedPaintingChildren after super has been messaged, as well as painting the border.
protected String | paramString() Returns a string representation of this JSplitPane.
void | remove(Component component) Removes the child component, component from the pane.
void | remove(int index) Removes the Component at the specified index.
void | removeAll() Removes all the child components from the split pane.
void | resetToPreferredSizes() Lays out the JSplitPane layout based on the preferred size of the children components.
void | setBottomComponent(Component comp) Sets the component below, or to the right of the divider.
void | setContinuousLayout(boolean newContinuousLayout) Sets the value of the continuousLayout property, which must be true for the child components to be continuously redisplayed and laid out during user intervention.
void | setDividerLocation(double proportionalLocation) Sets the divider location as a percentage of the JSplitPane's size.
void | setDividerLocation(int location) Sets the location of the divider.
void | setDividerSize(int newSize) Sets the size of the divider.
void | setLastDividerLocation(int newLastLocation) Sets the last location the divider was at to newLastLocation.
void | setLeftComponent(Component comp) Sets the component to the left (or above) the divider.
void | setOneTouchExpandable(boolean newValue) Sets the value of the oneTouchExpandable property, which must be true for the JSplitPane to provide a UI widget on the divider to quickly expand/collapse the divider.
void | setOrientation(int orientation) Sets the orientation, or how the splitter is divided.
void | setResizeWeight(double value) Specifies how to distribute extra space when the size of the split pane changes.
void | setRightComponent(Component comp) Sets the component to the right (or below) the divider.
void | setTopComponent(Component comp) Sets the component above, or to the left of the divider.
void | setUI(SplitPaneUI ui) Sets the L&F object that renders this component.
void | updateUI() Notification from the UIManager that the L&F has changed.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, paint, paintBorder, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

VERTICAL_SPLIT

public static final int VERTICAL_SPLIT
Vertical split indicates the Components are split along the y axis. For example the two Components will be split one on top of the other.

See Also:
Constant Field Values

HORIZONTAL_SPLIT

public static final int HORIZONTAL_SPLIT
Horizontal split indicates the Components are split along the x axis. For example the two Components will be split one to the left of the other.

See Also:
Constant Field Values

LEFT

public static final String LEFT
Used to add a Component to the left of the other Component.

See Also:
Constant Field Values

RIGHT

public static final String RIGHT
Used to add a Component to the right of the other Component.

See Also:
Constant Field Values

TOP

public static final String TOP
Used to add a Component above the other Component.

See Also:
Constant Field Values

BOTTOM

public static final String BOTTOM
Used to add a Component below the other Component.

See Also:
Constant Field Values

DIVIDER

public static final String DIVIDER
Used to add a Component that will represent the divider.

See Also:
Constant Field Values

ORIENTATION_PROPERTY

public static final String ORIENTATION_PROPERTY
Bound property name for orientation (horizontal or vertical).

See Also:
Constant Field Values

CONTINUOUS_LAYOUT_PROPERTY

public static final String CONTINUOUS_LAYOUT_PROPERTY
Bound property name for continuousLayout.

See Also:
Constant Field Values

DIVIDER_SIZE_PROPERTY

public static final String DIVIDER_SIZE_PROPERTY
Bound property name for border.

See Also:
Constant Field Values

ONE_TOUCH_EXPANDABLE_PROPERTY

public static final String ONE_TOUCH_EXPANDABLE_PROPERTY
Bound property for oneTouchExpandable.

See Also:
Constant Field Values

LAST_DIVIDER_LOCATION_PROPERTY

public static final String LAST_DIVIDER_LOCATION_PROPERTY
Bound property for lastLocation.

See Also:
Constant Field Values

DIVIDER_LOCATION_PROPERTY

public static final String DIVIDER_LOCATION_PROPERTY
Bound property for the dividerLocation.

Since:
1.3
See Also:
Constant Field Values

RESIZE_WEIGHT_PROPERTY

public static final String RESIZE_WEIGHT_PROPERTY
Bound property for weight.

Since:
1.3
See Also:
Constant Field Values

orientation

protected int orientation
How the views are split.

continuousLayout

protected boolean continuousLayout
Whether or not the views are continuously redisplayed while resizing.

leftComponent

protected Component leftComponent
The left or top component.

rightComponent

protected Component rightComponent
The right or bottom component.

dividerSize

protected int dividerSize
Size of the divider.

oneTouchExpandable

protected boolean oneTouchExpandable
Is a little widget provided to quickly expand/collapse the split pane?

lastDividerLocation

protected int lastDividerLocation
Previous location of the split pane.

Constructor Detail

JSplitPane

public JSplitPane()
Creates a new JSplitPane configured to arrange the child components side-by-side horizontally with no continuous layout, using two buttons for the components.

JSplitPane

public JSplitPane(int newOrientation)
Creates a new JSplitPane configured with the specified orientation and no continuous layout.

Parameters:
newOrientation - JSplitPane.HORIZONTAL_SPLIT or JSplitPane.VERTICAL_SPLIT
Throws:
IllegalArgumentException - if orientation is not one of HORIZONTAL_SPLIT or VERTICAL_SPLIT.

JSplitPane

public JSplitPane(int newOrientation,
                  boolean newContinuousLayout)
Creates a new JSplitPane with the specified orientation and redrawing style.

Parameters:
newOrientation - JSplitPane.HORIZONTAL_SPLIT or JSplitPane.VERTICAL_SPLIT
newContinuousLayout - a boolean, true for the components to redraw continuously as the divider changes position, false to wait until the divider position stops changing to redraw
Throws:
IllegalArgumentException - if orientation is not one of HORIZONTAL_SPLIT or VERTICAL_SPLIT

JSplitPane

public JSplitPane(int newOrientation,
                  Component newLeftComponent,
                  Component newRightComponent)
Creates a new JSplitPane with the specified orientation and with the specified components that do not do continuous redrawing.

Parameters:
newOrientation - JSplitPane.HORIZONTAL_SPLIT or JSplitPane.VERTICAL_SPLIT
newLeftComponent - the Component that will appear on the left of a horizontally-split pane, or at the top of a vertically-split pane
newRightComponent - the Component that will appear on the right of a horizontally-split pane, or at the bottom of a vertically-split pane
Throws:
IllegalArgumentException - if orientation is not one of: HORIZONTAL_SPLIT or VERTICAL_SPLIT

JSplitPane

public JSplitPane(int newOrientation,
                  boolean newContinuousLayout,
                  Component newLeftComponent,
                  Component newRightComponent)
Creates a new JSplitPane with the specified orientation and redrawing style, and with the specified components.

Parameters:
newOrientation - JSplitPane.HORIZONTAL_SPLIT or JSplitPane.VERTICAL_SPLIT
newContinuousLayout - a boolean, true for the components to redraw continuously as the divider changes position, false to wait until the divider position stops changing to redraw
newLeftComponent - the Component that will appear on the left of a horizontally-split pane, or at the top of a vertically-split pane
newRightComponent - the Component that will appear on the right of a horizontally-split pane, or at the bottom of a vertically-split pane
Throws:
IllegalArgumentException - if orientation is not one of HORIZONTAL_SPLIT or VERTICAL_SPLIT
Method Detail

setUI

public void setUI(SplitPaneUI ui)
Sets the L&F object that renders this component.

Parameters:
ui - the SplitPaneUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

getUI

public SplitPaneUI getUI()
Returns the SplitPaneUI that is providing the current look and feel.

Returns:
the SplitPaneUI object that renders this component

updateUI

public void updateUI()
Notification from the UIManager that the L&F has changed. Replaces the current UI object with the latest version from the UIManager.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "SplitPaneUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

setDividerSize

public void setDividerSize(int newSize)
Sets the size of the divider.

Parameters:
newSize - an integer giving the size of the divider in pixels

getDividerSize

public int getDividerSize()
Returns the size of the divider.

Returns:
an integer giving the size of the divider in pixels

setLeftComponent

public void setLeftComponent(Component comp)
Sets the component to the left (or above) the divider.

Parameters:
comp - the Component to display in that position

getLeftComponent

public Component getLeftComponent()
Returns the component to the left (or above) the divider.

Returns:
the Component displayed in that position

setTopComponent

public void setTopComponent(Component comp)
Sets the component above, or to the left of the divider.

Parameters:
comp - the Component to display in that position

getTopComponent

public Component getTopComponent()
Returns the component above, or to the left of the divider.

Returns:
the Component displayed in that position

setRightComponent

public void setRightComponent(Component comp)
Sets the component to the right (or below) the divider.

Parameters:
comp - the Component to display in that position

getRightComponent

public Component getRightComponent()
Returns the component to the right (or below) the divider.

Returns:
the Component displayed in that position

setBottomComponent

public void setBottomComponent(Component comp)
Sets the component below, or to the right of the divider.

Parameters:
comp - the Component to display in that position

getBottomComponent

public Component getBottomComponent()
Returns the component below, or to the right of the divider.

Returns:
the Component displayed in that position

setOneTouchExpandable

public void setOneTouchExpandable(boolean newValue)
Sets the value of the oneTouchExpandable property, which must be true for the JSplitPane to provide a UI widget on the divider to quickly expand/collapse the divider. The default value of this property is false. Some look and feels might not support one-touch expanding; they will ignore this property.

Parameters:
newValue - true to specify that the split pane should provide a collapse/expand widget
See Also:
isOneTouchExpandable()

isOneTouchExpandable

public boolean isOneTouchExpandable()
Gets the oneTouchExpandable property.

Returns:
the value of the oneTouchExpandable property
See Also:
setOneTouchExpandable(boolean)

setLastDividerLocation

public void setLastDividerLocation(int newLastLocation)
Sets the last location the divider was at to newLastLocation.

Parameters:
newLastLocation - an integer specifying the last divider location in pixels, from the left (or upper) edge of the pane to the left (or upper) edge of the divider

getLastDividerLocation

public int getLastDividerLocation()
Returns the last location the divider was at.

Returns:
an integer specifying the last divider location as a count of pixels from the left (or upper) edge of the pane to the left (or upper) edge of the divider

setOrientation

public void setOrientation(int orientation)
Sets the orientation, or how the splitter is divided. The options are:
  • JSplitPane.VERTICAL_SPLIT (above/below orientation of components)
  • JSplitPane.HORIZONTAL_SPLIT (left/right orientation of components)

Parameters:
orientation - an integer specifying the orientation
Throws:
IllegalArgumentException - if orientation is not one of: HORIZONTAL_SPLIT or VERTICAL_SPLIT.

getOrientation

public int getOrientation()
Returns the orientation.

Returns:
an integer giving the orientation
See Also:
setOrientation(int)

setContinuousLayout

public void setContinuousLayout(boolean newContinuousLayout)
Sets the value of the continuousLayout property, which must be true for the child components to be continuously redisplayed and laid out during user intervention. The default value of this property is false. Some look and feels might not support continuous layout; they will ignore this property.

Parameters:
newContinuousLayout - true if the components should continuously be redrawn as the divider changes position
See Also:
isContinuousLayout()

isContinuousLayout

public boolean isContinuousLayout()
Gets the continuousLayout property.

Returns:
the value of the continuousLayout property
See Also:
setContinuousLayout(boolean)

setResizeWeight

public void setResizeWeight(double value)
Specifies how to distribute extra space when the size of the split pane changes. A value of 0, the default, indicates the right/bottom component gets all the extra space (the left/top component acts fixed), where as a value of 1 specifies the left/top component gets all the extra space (the right/bottom component acts fixed). Specifically, the left/top component gets (weight * diff) extra space and the right/bottom component gets (1 - weight) * diff extra space.

Parameters:
value - as described above
Throws:
IllegalArgumentException - if value is < 0 or > 1
Since:
1.3

getResizeWeight

public double getResizeWeight()
Returns the number that determines how extra space is distributed.

Returns:
how extra space is to be distributed on a resize of the split pane
Since:
1.3

resetToPreferredSizes

public void resetToPreferredSizes()
Lays out the JSplitPane layout based on the preferred size of the children components. This will likely result in changing the divider location.

setDividerLocation

public void setDividerLocation(double proportionalLocation)
Sets the divider location as a percentage of the JSplitPane's size.

This method is implemented in terms of setDividerLocation(int). This method immediately changes the size of the split pane based on its current size. If the split pane is not correctly realized and on screen, this method will have no effect (new divider location will become (current size * proportionalLocation) which is 0).

Parameters:
proportionalLocation - a double-precision floating point value that specifies a percentage, from zero (top/left) to 1.0 (bottom/right)
Throws:
IllegalArgumentException - if the specified location is < 0 or > 1.0

setDividerLocation

public void setDividerLocation(int location)
Sets the location of the divider. This is passed off to the look and feel implementation, and then listeners are notified. A value less than 0 implies the divider should be reset to a value that attempts to honor the preferred size of the left/top component. After notifying the listeners, the last divider location is updated, via setLastDividerLocation.

Parameters:
location - an int specifying a UI-specific value (typically a pixel count)

getDividerLocation

public int getDividerLocation()
Returns the last value passed to setDividerLocation. The value returned from this method may differ from the actual divider location (if setDividerLocation was passed a value bigger than the curent size).

Returns:
an integer specifying the location of the divider

getMinimumDividerLocation

public int getMinimumDividerLocation()
Returns the minimum location of the divider from the look and feel implementation.

Returns:
an integer specifying a UI-specific value for the minimum location (typically a pixel count); or -1 if the UI is null

getMaximumDividerLocation

public int getMaximumDividerLocation()
Returns the maximum location of the divider from the look and feel implementation.

Returns:
an integer specifying a UI-specific value for the maximum location (typically a pixel count); or -1 if the UI is null

remove

public void remove(Component component)
Removes the child component, component from the pane. Resets the leftComponent or rightComponent instance variable, as necessary.

Overrides:
remove in class Container
Parameters:
component - the Component to remove
See Also:
Container.add(java.awt.Component),
Container.validate(),
Container.remove(int)

remove

public void remove(int index)
Removes the Component at the specified index. Updates the leftComponent and rightComponent instance variables as necessary, and then messages super.

Overrides:
remove in class Container
Parameters:
index - an integer specifying the component to remove, where 1 specifies the left/top component and 2 specifies the bottom/right component
See Also:
Container.add(java.awt.Component),
Container.validate(),
Container.getComponentCount()

removeAll

public void removeAll()
Removes all the child components from the split pane. Resets the leftComonent and rightComponent instance variables.

Overrides:
removeAll in class Container
See Also:
Container.add(java.awt.Component), Container.remove(int)

isValidateRoot

public boolean isValidateRoot()
Returns true, so that calls to revalidate on any descendant of this JSplitPane will cause a request to be queued that will validate the JSplitPane and all its descendants.

Overrides:
isValidateRoot in class JComponent
Returns:
true
See Also:
JComponent.revalidate()

addImpl

protected void addImpl(Component comp,
                       Object constraints,
                       int index)
Adds the specified component to this split pane. If constraints identifies the left/top or right/bottom child component, and a component with that identifier was previously added, it will be removed and then comp will be added in its place. If constraints is not one of the known identifiers the layout manager may throw an IllegalArgumentException.

The possible constraints objects (Strings) are:

  • JSplitPane.TOP
  • JSplitPane.LEFT
  • JSplitPane.BOTTOM
  • JSplitPane.RIGHT
If the constraints object is null, the component is added in the first available position (left/top if open, else right/bottom).

Overrides:
addImpl in class Container
Parameters:
comp - the component to add
constraints - an Object specifying the layout constraints (position) for this component
index - an integer specifying the index in the container's list.
Throws:
IllegalArgumentException - if the constraints object does not match an existing component
See Also:
Container.addImpl(Component, Object, int)

paintChildren

protected void paintChildren(Graphics g)
Subclassed to message the UI with finishedPaintingChildren after super has been messaged, as well as painting the border.

Overrides:
paintChildren in class JComponent
Parameters:
g - the Graphics context within which to paint
See Also:
JComponent.paint(java.awt.Graphics), Container.paint(java.awt.Graphics)

paramString

protected String paramString()
Returns a string representation of this JSplitPane. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JSplitPane.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JSplitPane. For split panes, the AccessibleContext takes the form of an AccessibleJSplitPane. A new AccessibleJSplitPane instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJSplitPane that serves as the AccessibleContext of this JSplitPane
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JSplitPane.AccessibleJSplitPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JSplitPane.AccessibleJSplitPane

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JSplitPane.AccessibleJSplitPane
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent, AccessibleValue
Enclosing class:
JSplitPane
protected class JSplitPane.AccessibleJSplitPane
extends JComponent.AccessibleJComponent
implements AccessibleValue

This class implements accessibility support for the JSplitPane class. It provides an implementation of the Java Accessibility API appropriate to split pane user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JSplitPane.AccessibleJSplitPane()
Method Summary
AccessibleRole | getAccessibleRole() Gets the role of this object.
AccessibleStateSet | getAccessibleStateSet() Gets the state set of this object.
AccessibleValue | getAccessibleValue() Get the AccessibleValue associated with this object.
Number | getCurrentAccessibleValue() Gets the accessible value of this object.
Number | getMaximumAccessibleValue() Gets the maximum accessible value of this object.
Number | getMinimumAccessibleValue() Gets the minimum accessible value of this object.
boolean | setCurrentAccessibleValue(Number n) Sets the value of this object as a Number.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JSplitPane.AccessibleJSplitPane

protected JSplitPane.AccessibleJSplitPane()
Method Detail

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Gets the state set of this object.

Overrides:
getAccessibleStateSet in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleState containing the current state of the object
See Also:
AccessibleState

getAccessibleValue

public AccessibleValue getAccessibleValue()
Get the AccessibleValue associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleValue interface on behalf of itself.

Overrides:
getAccessibleValue in class AccessibleContext
Returns:
this object
See Also:
AccessibleValue

getCurrentAccessibleValue

public Number getCurrentAccessibleValue()
Gets the accessible value of this object.

Specified by:
getCurrentAccessibleValue in interface AccessibleValue
Returns:
a localized String describing the value of this object
See Also:
AccessibleValue.setCurrentAccessibleValue(java.lang.Number)

setCurrentAccessibleValue

public boolean setCurrentAccessibleValue(Number n)
Sets the value of this object as a Number.

Specified by:
setCurrentAccessibleValue in interface AccessibleValue
Returns:
True if the value was set.
See Also:
AccessibleValue.getCurrentAccessibleValue()

getMinimumAccessibleValue

public Number getMinimumAccessibleValue()
Gets the minimum accessible value of this object.

Specified by:
getMinimumAccessibleValue in interface AccessibleValue
Returns:
The minimum value of this object.
See Also:
AccessibleValue.getMaximumAccessibleValue()

getMaximumAccessibleValue

public Number getMaximumAccessibleValue()
Gets the maximum accessible value of this object.

Specified by:
getMaximumAccessibleValue in interface AccessibleValue
Returns:
The maximum value of this object.
See Also:
AccessibleValue.getMinimumAccessibleValue()

getAccessibleRole

public AccessibleRole getAccessibleRole()
Gets the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTabbedPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTabbedPane

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JTabbedPane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, SwingConstants
public class JTabbedPane
extends JComponent
implements Serializable, Accessible, SwingConstants

A component that lets the user switch between a group of components by clicking on a tab with a given title and/or icon. For examples and information on using tabbed panes see How to Use Tabbed Panes, a section in The Java Tutorial.

Tabs/components are added to a TabbedPane object by using the addTab and insertTab methods. A tab is represented by an index corresponding to the position it was added in, where the first tab has an index equal to 0 and the last tab has an index equal to the tab count minus 1.

The TabbedPane uses a SingleSelectionModel to represent the set of tab indices and the currently selected index. If the tab count is greater than 0, then there will always be a selected index, which by default will be initialized to the first tab. If the tab count is 0, then the selected index will be -1.

The tab title can be rendered by a Component. For example, the following produce similar results:

 // In this case the look and feel renders the title for the tab.
 tabbedPane.addTab("Tab", myComponent);
 // In this case the custom component is responsible for rendering the
 // title of the tab.
 tabbedPane.addTab(null, myComponent);
 tabbedPane.setTabComponentAt(0, new JLabel("Tab"));
The latter is typically used when you want a more complex user interaction that requires custom components on the tab. For example, you could provide a custom component that animates or one that has widgets for closing the tab.

If you specify a component for a tab, the JTabbedPane will not render any text or icon you have specified for the tab.

Note: Do not use setVisible directly on a tab component to make it visible, use setSelectedComponent or setSelectedIndex methods instead.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
SingleSelectionModel

Nested Class Summary
protected class | JTabbedPane.AccessibleJTabbedPane This class implements accessibility support for the JTabbedPane class.
protected class | JTabbedPane.ModelListener We pass ModelChanged events along to the listeners with the tabbedpane (instead of the model itself) as the event source.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected ChangeEvent | changeEvent Only one ChangeEvent is needed per TabPane instance since the event's only (read-only) state is the source property.
protected ChangeListener | changeListener The changeListener is the listener we add to the model.
protected SingleSelectionModel | model The default selection model
static int | SCROLL_TAB_LAYOUT Tab layout policy for providing a subset of available tabs when all the tabs will not fit within a single run.
protected int | tabPlacement Where the tabs are placed.
static int | WRAP_TAB_LAYOUT The tab layout policy for wrapping tabs in multiple runs when all tabs will not fit within a single run.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JTabbedPane()
Creates an empty TabbedPane with a default tab placement of JTabbedPane.TOP.
JTabbedPane(int tabPlacement)
Creates an empty TabbedPane with the specified tab placement of either: JTabbedPane.TOP, JTabbedPane.BOTTOM, JTabbedPane.LEFT, or JTabbedPane.RIGHT.
JTabbedPane(int tabPlacement, int tabLayoutPolicy)
Creates an empty TabbedPane with the specified tab placement and tab layout policy.
Method Summary
Component | add(Component component) Adds a component with a tab title defaulting to the name of the component which is the result of calling component.getName.
Component | add(Component component, int index) Adds a component at the specified tab index with a tab title defaulting to the name of the component.
void | add(Component component, Object constraints) Adds a component to the tabbed pane.
void | add(Component component, Object constraints, int index) Adds a component at the specified tab index.
Component | add(String title, Component component) Adds a component with the specified tab title.
void | addChangeListener(ChangeListener l) Adds a ChangeListener to this tabbedpane.
void | addTab(String title, Component component) Adds a component represented by a title and no icon.
void | addTab(String title, Icon icon, Component component) Adds a component represented by a title and/or icon, either of which can be null.
void | addTab(String title, Icon icon, Component component, String tip) Adds a component and tip represented by a title and/or icon, either of which can be null.
protected ChangeListener | createChangeListener() Subclasses that want to handle ChangeEvents differently can override this to return a subclass of ModelListener or another ChangeListener implementation.
protected void | fireStateChanged() Sends a ChangeEvent, with this JTabbedPane as the source, to each registered listener.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JTabbedPane.
Color | getBackgroundAt(int index) Returns the tab background color at index.
Rectangle | getBoundsAt(int index) Returns the tab bounds at index.
ChangeListener[] | getChangeListeners() Returns an array of all the ChangeListeners added to this JTabbedPane with addChangeListener.
Component | getComponentAt(int index) Returns the component at index.
Icon | getDisabledIconAt(int index) Returns the tab disabled icon at index.
int | getDisplayedMnemonicIndexAt(int tabIndex) Returns the character, as an index, that the look and feel should provide decoration for as representing the mnemonic character.
Color | getForegroundAt(int index) Returns the tab foreground color at index.
Icon | getIconAt(int index) Returns the tab icon at index.
int | getMnemonicAt(int tabIndex) Returns the keyboard mnemonic for accessing the specified tab.
SingleSelectionModel | getModel() Returns the model associated with this tabbedpane.
Component | getSelectedComponent() Returns the currently selected component for this tabbedpane.
int | getSelectedIndex() Returns the currently selected index for this tabbedpane.
Component | getTabComponentAt(int index) Returns the tab component at index.
int | getTabCount() Returns the number of tabs in this tabbedpane.
int | getTabLayoutPolicy() Returns the policy used by the tabbedpane to layout the tabs when all the tabs will not fit within a single run.
int | getTabPlacement() Returns the placement of the tabs for this tabbedpane.
int | getTabRunCount() Returns the number of tab runs currently used to display the tabs.
String | getTitleAt(int index) Returns the tab title at index.
String | getToolTipText(MouseEvent event) Returns the tooltip text for the component determined by the mouse event location.
String | getToolTipTextAt(int index) Returns the tab tooltip text at index.
TabbedPaneUI | getUI() Returns the UI object which implements the L&F for this component.
String | getUIClassID() Returns the name of the UI class that implements the L&F for this component.
int | indexAtLocation(int x, int y) Returns the tab index corresponding to the tab whose bounds intersect the specified location.
int | indexOfComponent(Component component) Returns the index of the tab for the specified component.
int | indexOfTab(Icon icon) Returns the first tab index with a given icon, or -1 if no tab has this icon.
int | indexOfTab(String title) Returns the first tab index with a given title, or -1 if no tab has this title.
int | indexOfTabComponent(Component tabComponent) Returns the index of the tab for the specified tab component.
void | insertTab(String title, Icon icon, Component component, String tip, int index) Inserts a component, at index, represented by a title and/or icon, either of which may be null.
boolean | isEnabledAt(int index) Returns whether or not the tab at index is currently enabled.
protected String | paramString() Returns a string representation of this JTabbedPane.
void | remove(Component component) Removes the specified Component from the JTabbedPane.
void | remove(int index) Removes the tab and component which corresponds to the specified index.
void | removeAll() Removes all the tabs and their corresponding components from the tabbedpane.
void | removeChangeListener(ChangeListener l) Removes a ChangeListener from this tabbedpane.
void | removeTabAt(int index) Removes the tab at index.
void | setBackgroundAt(int index, Color background) Sets the background color at index to background which can be null, in which case the tab's background color will default to the background color of the tabbedpane.
void | setComponentAt(int index, Component component) Sets the component at index to component.
void | setDisabledIconAt(int index, Icon disabledIcon) Sets the disabled icon at index to icon which can be null.
void | setDisplayedMnemonicIndexAt(int tabIndex, int mnemonicIndex) Provides a hint to the look and feel as to which character in the text should be decorated to represent the mnemonic.
void | setEnabledAt(int index, boolean enabled) Sets whether or not the tab at index is enabled.
void | setForegroundAt(int index, Color foreground) Sets the foreground color at index to foreground which can be null, in which case the tab's foreground color will default to the foreground color of this tabbedpane.
void | setIconAt(int index, Icon icon) Sets the icon at index to icon which can be null.
void | setMnemonicAt(int tabIndex, int mnemonic) Sets the keyboard mnemonic for accessing the specified tab.
void | setModel(SingleSelectionModel model) Sets the model to be used with this tabbedpane.
void | setSelectedComponent(Component c) Sets the selected component for this tabbedpane.
void | setSelectedIndex(int index) Sets the selected index for this tabbedpane.
void | setTabComponentAt(int index, Component component) Sets the component that is responsible for rendering the title for the specified tab.
void | setTabLayoutPolicy(int tabLayoutPolicy) Sets the policy which the tabbedpane will use in laying out the tabs when all the tabs will not fit within a single run.
void | setTabPlacement(int tabPlacement) Sets the tab placement for this tabbedpane.
void | setTitleAt(int index, String title) Sets the title at index to title which can be null.
void | setToolTipTextAt(int index, String toolTipText) Sets the tooltip text at index to toolTipText which can be null.
void | setUI(TabbedPaneUI ui) Sets the UI object which implements the L&F for this component.
void | updateUI() Resets the UI property to a value from the current look and feel.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

WRAP_TAB_LAYOUT

public static final int WRAP_TAB_LAYOUT
The tab layout policy for wrapping tabs in multiple runs when all tabs will not fit within a single run.

See Also:
Constant Field Values

SCROLL_TAB_LAYOUT

public static final int SCROLL_TAB_LAYOUT
Tab layout policy for providing a subset of available tabs when all the tabs will not fit within a single run. If all the tabs do not fit within a single run the look and feel will provide a way to navigate to hidden tabs.

See Also:
Constant Field Values

tabPlacement

protected int tabPlacement
Where the tabs are placed.

See Also:
setTabPlacement(int)

model

protected SingleSelectionModel model
The default selection model

changeListener

protected ChangeListener changeListener
The changeListener is the listener we add to the model.

changeEvent

protected transient ChangeEvent changeEvent
Only one ChangeEvent is needed per TabPane instance since the event's only (read-only) state is the source property. The source of events generated here is always "this".

Constructor Detail

JTabbedPane

public JTabbedPane()
Creates an empty TabbedPane with a default tab placement of JTabbedPane.TOP.

See Also:
addTab(java.lang.String, javax.swing.Icon, java.awt.Component, java.lang.String)

JTabbedPane

public JTabbedPane(int tabPlacement)
Creates an empty TabbedPane with the specified tab placement of either: JTabbedPane.TOP, JTabbedPane.BOTTOM, JTabbedPane.LEFT, or JTabbedPane.RIGHT.

Parameters:
tabPlacement - the placement for the tabs relative to the content
See Also:
addTab(java.lang.String, javax.swing.Icon, java.awt.Component, java.lang.String)

JTabbedPane

public JTabbedPane(int tabPlacement,
                   int tabLayoutPolicy)
Creates an empty TabbedPane with the specified tab placement and tab layout policy. Tab placement may be either: JTabbedPane.TOP, JTabbedPane.BOTTOM, JTabbedPane.LEFT, or JTabbedPane.RIGHT. Tab layout policy may be either: JTabbedPane.WRAP_TAB_LAYOUT or JTabbedPane.SCROLL_TAB_LAYOUT.

Parameters:
tabPlacement - the placement for the tabs relative to the content
tabLayoutPolicy - the policy for laying out tabs when all tabs will not fit on one run
Throws:
IllegalArgumentException - if tab placement or tab layout policy are not one of the above supported values
Since:
1.4
See Also:
addTab(java.lang.String, javax.swing.Icon, java.awt.Component, java.lang.String)
Method Detail

getUI

public TabbedPaneUI getUI()
Returns the UI object which implements the L&F for this component.

Returns:
a TabbedPaneUI object
See Also:
setUI(javax.swing.plaf.TabbedPaneUI)

setUI

public void setUI(TabbedPaneUI ui)
Sets the UI object which implements the L&F for this component.

Parameters:
ui - the new UI object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Resets the UI property to a value from the current look and feel.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the UI class that implements the L&F for this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "TabbedPaneUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

createChangeListener

protected ChangeListener createChangeListener()
Subclasses that want to handle ChangeEvents differently can override this to return a subclass of ModelListener or another ChangeListener implementation.

See Also:
fireStateChanged()

addChangeListener

public void addChangeListener(ChangeListener l)
Adds a ChangeListener to this tabbedpane.

Parameters:
l - the ChangeListener to add
See Also:
fireStateChanged(), removeChangeListener(javax.swing.event.ChangeListener)

removeChangeListener

public void removeChangeListener(ChangeListener l)
Removes a ChangeListener from this tabbedpane.

Parameters:
l - the ChangeListener to remove
See Also:
fireStateChanged(), addChangeListener(javax.swing.event.ChangeListener)

getChangeListeners

public ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this JTabbedPane with addChangeListener.

Returns:
all of the ChangeListeners added or an empty array if no listeners have been added
Since:
1.4

fireStateChanged

protected void fireStateChanged()
Sends a ChangeEvent, with this JTabbedPane as the source, to each registered listener. This method is called each time there is a change to either the selected index or the selected tab in the JTabbedPane. Usually, the selected index and selected tab change together. However, there are some cases, such as tab addition, where the selected index changes and the same tab remains selected. There are other cases, such as deleting the selected tab, where the index remains the same, but a new tab moves to that index. Events are fired for all of these cases.

See Also:
addChangeListener(javax.swing.event.ChangeListener), EventListenerList

getModel

public SingleSelectionModel getModel()
Returns the model associated with this tabbedpane.

See Also:
setModel(javax.swing.SingleSelectionModel)

setModel

public void setModel(SingleSelectionModel model)
Sets the model to be used with this tabbedpane.

Parameters:
model - the model to be used
See Also:
getModel()

getTabPlacement

public int getTabPlacement()
Returns the placement of the tabs for this tabbedpane.

See Also:
setTabPlacement(int)

setTabPlacement

public void setTabPlacement(int tabPlacement)
Sets the tab placement for this tabbedpane. Possible values are:
  • JTabbedPane.TOP
  • JTabbedPane.BOTTOM
  • JTabbedPane.LEFT
  • JTabbedPane.RIGHT
The default value, if not set, is SwingConstants.TOP.

Parameters:
tabPlacement - the placement for the tabs relative to the content
Throws:
IllegalArgumentException - if tab placement value isn't one of the above valid values

getTabLayoutPolicy

public int getTabLayoutPolicy()
Returns the policy used by the tabbedpane to layout the tabs when all the tabs will not fit within a single run.

Since:
1.4
See Also:
setTabLayoutPolicy(int)

setTabLayoutPolicy

public void setTabLayoutPolicy(int tabLayoutPolicy)
Sets the policy which the tabbedpane will use in laying out the tabs when all the tabs will not fit within a single run. Possible values are:
  • JTabbedPane.WRAP_TAB_LAYOUT
  • JTabbedPane.SCROLL_TAB_LAYOUT
The default value, if not set by the UI, is JTabbedPane.WRAP_TAB_LAYOUT.

Some look and feels might only support a subset of the possible layout policies, in which case the value of this property may be ignored.

Parameters:
tabLayoutPolicy - the policy used to layout the tabs
Throws:
IllegalArgumentException - if layoutPolicy value isn't one of the above valid values
Since:
1.4
See Also:
getTabLayoutPolicy()

getSelectedIndex

public int getSelectedIndex()
Returns the currently selected index for this tabbedpane. Returns -1 if there is no currently selected tab.

Returns:
the index of the selected tab
See Also:
setSelectedIndex(int)

setSelectedIndex

public void setSelectedIndex(int index)
Sets the selected index for this tabbedpane. The index must be a valid tab index or -1, which indicates that no tab should be selected (can also be used when there are no tabs in the tabbedpane). If a -1 value is specified when the tabbedpane contains one or more tabs, then the results will be implementation defined.

Parameters:
index - the index to be selected
Throws:
IndexOutOfBoundsException - if index is out of range (index < -1 || index >= tab count)
See Also:
getSelectedIndex(), SingleSelectionModel.setSelectedIndex(int)

getSelectedComponent

public Component getSelectedComponent()
Returns the currently selected component for this tabbedpane. Returns null if there is no currently selected tab.

Returns:
the component corresponding to the selected tab
See Also:
setSelectedComponent(java.awt.Component)

setSelectedComponent

public void setSelectedComponent(Component c)
Sets the selected component for this tabbedpane. This will automatically set the selectedIndex to the index corresponding to the specified component.

Throws:
IllegalArgumentException - if component not found in tabbed pane
See Also:
getSelectedComponent()

insertTab

public void insertTab(String title,
                      Icon icon,
                      Component component,
                      String tip,
                      int index)
Inserts a component, at index, represented by a title and/or icon, either of which may be null. Uses java.util.Vector internally, see insertElementAt for details of insertion conventions.

Parameters:
title - the title to be displayed in this tab
icon - the icon to be displayed in this tab
component - The component to be displayed when this tab is clicked.
tip - the tooltip to be displayed for this tab
index - the position to insert this new tab
See Also:
addTab(java.lang.String, javax.swing.Icon, java.awt.Component, java.lang.String), removeTabAt(int)

addTab

public void addTab(String title,
                   Icon icon,
                   Component component,
                   String tip)
Adds a component and tip represented by a title and/or icon, either of which can be null. Cover method for insertTab.

Parameters:
title - the title to be displayed in this tab
icon - the icon to be displayed in this tab
component - the component to be displayed when this tab is clicked
tip - the tooltip to be displayed for this tab
See Also:
insertTab(java.lang.String, javax.swing.Icon, java.awt.Component, java.lang.String, int), removeTabAt(int)

addTab

public void addTab(String title,
                   Icon icon,
                   Component component)
Adds a component represented by a title and/or icon, either of which can be null. Cover method for insertTab.

Parameters:
title - the title to be displayed in this tab
icon - the icon to be displayed in this tab
component - the component to be displayed when this tab is clicked
See Also:
insertTab(java.lang.String, javax.swing.Icon, java.awt.Component, java.lang.String, int), removeTabAt(int)

addTab

public void addTab(String title,
                   Component component)
Adds a component represented by a title and no icon. Cover method for insertTab.

Parameters:
title - the title to be displayed in this tab
component - the component to be displayed when this tab is clicked
See Also:
insertTab(java.lang.String, javax.swing.Icon, java.awt.Component, java.lang.String, int), removeTabAt(int)

add

public Component add(Component component)
Adds a component with a tab title defaulting to the name of the component which is the result of calling component.getName. Cover method for insertTab.

Overrides:
add in class Container
Parameters:
component - the component to be displayed when this tab is clicked
Returns:
the component
See Also:
insertTab(java.lang.String, javax.swing.Icon, java.awt.Component, java.lang.String, int), removeTabAt(int)

add

public Component add(String title,
                     Component component)
Adds a component with the specified tab title. Cover method for insertTab.

Overrides:
add in class Container
Parameters:
title - the title to be displayed in this tab
component - the component to be displayed when this tab is clicked
Returns:
the component
See Also:
insertTab(java.lang.String, javax.swing.Icon, java.awt.Component, java.lang.String, int), removeTabAt(int)

add

public Component add(Component component,
                     int index)
Adds a component at the specified tab index with a tab title defaulting to the name of the component. Cover method for insertTab.

Overrides:
add in class Container
Parameters:
component - the component to be displayed when this tab is clicked
index - the position to insert this new tab
Returns:
the component
See Also:
insertTab(java.lang.String, javax.swing.Icon, java.awt.Component, java.lang.String, int), removeTabAt(int)

add

public void add(Component component,
                Object constraints)
Adds a component to the tabbed pane. If constraints is a String or an Icon, it will be used for the tab title, otherwise the component's name will be used as the tab title. Cover method for insertTab.

Overrides:
add in class Container
Parameters:
component - the component to be displayed when this tab is clicked
constraints - the object to be displayed in the tab
See Also:
insertTab(java.lang.String, javax.swing.Icon, java.awt.Component, java.lang.String, int), removeTabAt(int)

add

public void add(Component component,
                Object constraints,
                int index)
Adds a component at the specified tab index. If constraints is a String or an Icon, it will be used for the tab title, otherwise the component's name will be used as the tab title. Cover method for insertTab.

Overrides:
add in class Container
Parameters:
component - the component to be displayed when this tab is clicked
constraints - the object to be displayed in the tab
index - the position to insert this new tab
See Also:
insertTab(java.lang.String, javax.swing.Icon, java.awt.Component, java.lang.String, int), removeTabAt(int)

removeTabAt

public void removeTabAt(int index)
Removes the tab at index. After the component associated with index is removed, its visibility is reset to true to ensure it will be visible if added to other containers.

Parameters:
index - the index of the tab to be removed
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
See Also:
addTab(java.lang.String, javax.swing.Icon, java.awt.Component, java.lang.String), insertTab(java.lang.String, javax.swing.Icon, java.awt.Component, java.lang.String, int)

remove

public void remove(Component component)
Removes the specified Component from the JTabbedPane. The method does nothing if the component is null.

Overrides:
remove in class Container
Parameters:
component - the component to remove from the tabbedpane
See Also:
addTab(java.lang.String, javax.swing.Icon, java.awt.Component, java.lang.String), removeTabAt(int)

remove

public void remove(int index)
Removes the tab and component which corresponds to the specified index.

Overrides:
remove in class Container
Parameters:
index - the index of the component to remove from the tabbedpane
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
See Also:
addTab(java.lang.String, javax.swing.Icon, java.awt.Component, java.lang.String), removeTabAt(int)

removeAll

public void removeAll()
Removes all the tabs and their corresponding components from the tabbedpane.

Overrides:
removeAll in class Container
See Also:
addTab(java.lang.String, javax.swing.Icon, java.awt.Component, java.lang.String), removeTabAt(int)

getTabCount

public int getTabCount()
Returns the number of tabs in this tabbedpane.

Returns:
an integer specifying the number of tabbed pages

getTabRunCount

public int getTabRunCount()
Returns the number of tab runs currently used to display the tabs.

Returns:
an integer giving the number of rows if the tabPlacement is TOP or BOTTOM and the number of columns if tabPlacement is LEFT or RIGHT, or 0 if there is no UI set on this tabbedpane

getTitleAt

public String getTitleAt(int index)
Returns the tab title at index.

Parameters:
index - the index of the item being queried
Returns:
the title at index
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
See Also:
setTitleAt(int, java.lang.String)

getIconAt

public Icon getIconAt(int index)
Returns the tab icon at index.

Parameters:
index - the index of the item being queried
Returns:
the icon at index
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
See Also:
setIconAt(int, javax.swing.Icon)

getDisabledIconAt

public Icon getDisabledIconAt(int index)
Returns the tab disabled icon at index. If the tab disabled icon doesn't exist at index this will forward the call to the look and feel to construct an appropriate disabled Icon from the corresponding enabled Icon. Some look and feels might not render the disabled Icon, in which case it won't be created.

Parameters:
index - the index of the item being queried
Returns:
the icon at index
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
See Also:
setDisabledIconAt(int, javax.swing.Icon)

getToolTipTextAt

public String getToolTipTextAt(int index)
Returns the tab tooltip text at index.

Parameters:
index - the index of the item being queried
Returns:
a string containing the tool tip text at index
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
Since:
1.3
See Also:
setToolTipTextAt(int, java.lang.String)

getBackgroundAt

public Color getBackgroundAt(int index)
Returns the tab background color at index.

Parameters:
index - the index of the item being queried
Returns:
the Color of the tab background at index
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
See Also:
setBackgroundAt(int, java.awt.Color)

getForegroundAt

public Color getForegroundAt(int index)
Returns the tab foreground color at index.

Parameters:
index - the index of the item being queried
Returns:
the Color of the tab foreground at index
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
See Also:
setForegroundAt(int, java.awt.Color)

isEnabledAt

public boolean isEnabledAt(int index)
Returns whether or not the tab at index is currently enabled.

Parameters:
index - the index of the item being queried
Returns:
true if the tab at index is enabled; false otherwise
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
See Also:
setEnabledAt(int, boolean)

getComponentAt

public Component getComponentAt(int index)
Returns the component at index.

Parameters:
index - the index of the item being queried
Returns:
the Component at index
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
See Also:
setComponentAt(int, java.awt.Component)

getMnemonicAt

public int getMnemonicAt(int tabIndex)
Returns the keyboard mnemonic for accessing the specified tab. The mnemonic is the key which when combined with the look and feel's mouseless modifier (usually Alt) will activate the specified tab.

Parameters:
tabIndex - the index of the tab that the mnemonic refers to
Returns:
the key code which represents the mnemonic; -1 if a mnemonic is not specified for the tab
Throws:
IndexOutOfBoundsException - if index is out of range (tabIndex < 0 || tabIndex >= tab count)
Since:
1.4
See Also:
setDisplayedMnemonicIndexAt(int,int), setMnemonicAt(int,int)

getDisplayedMnemonicIndexAt

public int getDisplayedMnemonicIndexAt(int tabIndex)
Returns the character, as an index, that the look and feel should provide decoration for as representing the mnemonic character.

Parameters:
tabIndex - the index of the tab that the mnemonic refers to
Returns:
index representing mnemonic character if one exists; otherwise returns -1
Throws:
IndexOutOfBoundsException - if index is out of range (tabIndex < 0 || tabIndex >= tab count)
Since:
1.4
See Also:
setDisplayedMnemonicIndexAt(int,int), setMnemonicAt(int,int)

getBoundsAt

public Rectangle getBoundsAt(int index)
Returns the tab bounds at index. If the tab at this index is not currently visible in the UI, then returns null. If there is no UI set on this tabbedpane, then returns null.

Parameters:
index - the index to be queried
Returns:
a Rectangle containing the tab bounds at index, or null if tab at index is not currently visible in the UI, or if there is no UI set on this tabbedpane
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)

setTitleAt

public void setTitleAt(int index,
                       String title)
Sets the title at index to title which can be null. The title is not shown if a tab component for this tab was specified. An internal exception is raised if there is no tab at that index.

Parameters:
index - the tab index where the title should be set
title - the title to be displayed in the tab
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
See Also:
getTitleAt(int), setTabComponentAt(int, java.awt.Component)

setIconAt

public void setIconAt(int index,
                      Icon icon)
Sets the icon at index to icon which can be null. This does not set disabled icon at icon. If the new Icon is different than the current Icon and disabled icon is not explicitly set, the LookAndFeel will be asked to generate a disabled Icon. To explicitly set disabled icon, use setDisableIconAt(). The icon is not shown if a tab component for this tab was specified. An internal exception is raised if there is no tab at that index.

Parameters:
index - the tab index where the icon should be set
icon - the icon to be displayed in the tab
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
See Also:
setDisabledIconAt(int, javax.swing.Icon), getIconAt(int), getDisabledIconAt(int), setTabComponentAt(int, java.awt.Component)

setDisabledIconAt

public void setDisabledIconAt(int index,
                              Icon disabledIcon)
Sets the disabled icon at index to icon which can be null. An internal exception is raised if there is no tab at that index.

Parameters:
index - the tab index where the disabled icon should be set
disabledIcon - the icon to be displayed in the tab when disabled
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
See Also:
getDisabledIconAt(int)

setToolTipTextAt

public void setToolTipTextAt(int index,
                             String toolTipText)
Sets the tooltip text at index to toolTipText which can be null. An internal exception is raised if there is no tab at that index.

Parameters:
index - the tab index where the tooltip text should be set
toolTipText - the tooltip text to be displayed for the tab
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
Since:
1.3
See Also:
getToolTipTextAt(int)

setBackgroundAt

public void setBackgroundAt(int index,
                            Color background)
Sets the background color at index to background which can be null, in which case the tab's background color will default to the background color of the tabbedpane. An internal exception is raised if there is no tab at that index.

Parameters:
index - the tab index where the background should be set
background - the color to be displayed in the tab's background
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
See Also:
getBackgroundAt(int)

setForegroundAt

public void setForegroundAt(int index,
                            Color foreground)
Sets the foreground color at index to foreground which can be null, in which case the tab's foreground color will default to the foreground color of this tabbedpane. An internal exception is raised if there is no tab at that index.

Parameters:
index - the tab index where the foreground should be set
foreground - the color to be displayed as the tab's foreground
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
See Also:
getForegroundAt(int)

setEnabledAt

public void setEnabledAt(int index,
                         boolean enabled)
Sets whether or not the tab at index is enabled. An internal exception is raised if there is no tab at that index.

Parameters:
index - the tab index which should be enabled/disabled
enabled - whether or not the tab should be enabled
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
See Also:
isEnabledAt(int)

setComponentAt

public void setComponentAt(int index,
                           Component component)
Sets the component at index to component. An internal exception is raised if there is no tab at that index.

Parameters:
index - the tab index where this component is being placed
component - the component for the tab
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
See Also:
getComponentAt(int)

setDisplayedMnemonicIndexAt

public void setDisplayedMnemonicIndexAt(int tabIndex,
                                        int mnemonicIndex)
Provides a hint to the look and feel as to which character in the text should be decorated to represent the mnemonic. Not all look and feels may support this. A value of -1 indicates either there is no mnemonic for this tab, or you do not wish the mnemonic to be displayed for this tab.

The value of this is updated as the properties relating to the mnemonic change (such as the mnemonic itself, the text...). You should only ever have to call this if you do not wish the default character to be underlined. For example, if the text at tab index 3 was 'Apple Price', with a mnemonic of 'p', and you wanted the 'P' to be decorated, as 'Apple Price', you would have to invoke setDisplayedMnemonicIndex(3, 6) after invoking setMnemonicAt(3, KeyEvent.VK_P).

Note that it is the programmer's responsibility to ensure that each tab has a unique mnemonic or unpredictable results may occur.

Parameters:
tabIndex - the index of the tab that the mnemonic refers to
mnemonicIndex - index into the String to underline
Throws:
IndexOutOfBoundsException - if tabIndex is out of range (tabIndex < 0 || tabIndex >= tab count)
IllegalArgumentException - will be thrown if mnemonicIndex is >= length of the tab title , or < -1
Since:
1.4
See Also:
setMnemonicAt(int,int), getDisplayedMnemonicIndexAt(int)

setMnemonicAt

public void setMnemonicAt(int tabIndex,
                          int mnemonic)
Sets the keyboard mnemonic for accessing the specified tab. The mnemonic is the key which when combined with the look and feel's mouseless modifier (usually Alt) will activate the specified tab.

A mnemonic must correspond to a single key on the keyboard and should be specified using one of the VK_XXX keycodes defined in java.awt.event.KeyEvent. Mnemonics are case-insensitive, therefore a key event with the corresponding keycode would cause the button to be activated whether or not the Shift modifier was pressed.

This will update the displayed mnemonic property for the specified tab.

Parameters:
tabIndex - the index of the tab that the mnemonic refers to
mnemonic - the key code which represents the mnemonic
Throws:
IndexOutOfBoundsException - if tabIndex is out of range (tabIndex < 0 || tabIndex >= tab count)
Since:
1.4
See Also:
getMnemonicAt(int), setDisplayedMnemonicIndexAt(int,int)

indexOfTab

public int indexOfTab(String title)
Returns the first tab index with a given title, or -1 if no tab has this title.

Parameters:
title - the title for the tab
Returns:
the first tab index which matches title, or -1 if no tab has this title

indexOfTab

public int indexOfTab(Icon icon)
Returns the first tab index with a given icon, or -1 if no tab has this icon.

Parameters:
icon - the icon for the tab
Returns:
the first tab index which matches icon, or -1 if no tab has this icon

indexOfComponent

public int indexOfComponent(Component component)
Returns the index of the tab for the specified component. Returns -1 if there is no tab for this component.

Parameters:
component - the component for the tab
Returns:
the first tab which matches this component, or -1 if there is no tab for this component

indexAtLocation

public int indexAtLocation(int x,
                           int y)
Returns the tab index corresponding to the tab whose bounds intersect the specified location. Returns -1 if no tab intersects the location.

Parameters:
x - the x location relative to this tabbedpane
y - the y location relative to this tabbedpane
Returns:
the tab index which intersects the location, or -1 if no tab intersects the location
Since:
1.4

getToolTipText

public String getToolTipText(MouseEvent event)
Returns the tooltip text for the component determined by the mouse event location.

Overrides:
getToolTipText in class JComponent
Parameters:
event - the MouseEvent that tells where the cursor is lingering
Returns:
the String containing the tooltip text

paramString

protected String paramString()
Returns a string representation of this JTabbedPane. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JTabbedPane.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JTabbedPane. For tabbed panes, the AccessibleContext takes the form of an AccessibleJTabbedPane. A new AccessibleJTabbedPane instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJTabbedPane that serves as the AccessibleContext of this JTabbedPane

setTabComponentAt

public void setTabComponentAt(int index,
                              Component component)
Sets the component that is responsible for rendering the title for the specified tab. A null value means JTabbedPane will render the title and/or icon for the specified tab. A non-null value means the component will render the title and JTabbedPane will not render the title and/or icon.

Note: The component must not be one that the developer has already added to the tabbed pane.

Parameters:
index - the tab index where the component should be set
component - the component to render the title for the specified tab
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
IllegalArgumentException - if component has already been added to this JTabbedPane
Since:
1.6
See Also:
getTabComponentAt(int)

getTabComponentAt

public Component getTabComponentAt(int index)
Returns the tab component at index.

Parameters:
index - the index of the item being queried
Returns:
the tab component at index
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
Since:
1.6
See Also:
setTabComponentAt(int, java.awt.Component)

indexOfTabComponent

public int indexOfTabComponent(Component tabComponent)
Returns the index of the tab for the specified tab component. Returns -1 if there is no tab for this tab component.

Parameters:
tabComponent - the tab component for the tab
Returns:
the first tab which matches this tab component, or -1 if there is no tab for this tab component
Since:
1.6
See Also:
setTabComponentAt(int, java.awt.Component), getTabComponentAt(int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTabbedPane.AccessibleJTabbedPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTabbedPane.AccessibleJTabbedPane

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JTabbedPane.AccessibleJTabbedPane
All Implemented Interfaces:
Serializable, EventListener, AccessibleComponent, AccessibleExtendedComponent, AccessibleSelection, ChangeListener
Enclosing class:
JTabbedPane
protected class JTabbedPane.AccessibleJTabbedPane
extends JComponent.AccessibleJComponent
implements AccessibleSelection, ChangeListener

This class implements accessibility support for the JTabbedPane class. It provides an implementation of the Java Accessibility API appropriate to tabbed pane user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
JTabbedPane.AccessibleJTabbedPane()
Constructs an AccessibleJTabbedPane
Method Summary
void | addAccessibleSelection(int i) Adds the specified Accessible child of the object to the object's selection.
void | clearAccessibleSelection() Clears the selection in the object, so that no children in the object are selected.
Accessible | getAccessibleAt(Point p) Returns the Accessible child contained at the local coordinate Point, if one exists.
Accessible | getAccessibleChild(int i) Return the specified Accessible child of the object.
int | getAccessibleChildrenCount() Returns the number of accessible children in the object.
String | getAccessibleName() Returns the accessible name of this object, or null if there is no accessible name.
AccessibleRole | getAccessibleRole() Get the role of this object.
AccessibleSelection | getAccessibleSelection() Gets the AccessibleSelection associated with this object.
Accessible | getAccessibleSelection(int i) Returns an Accessible representing the specified selected child of the object.
int | getAccessibleSelectionCount() Returns the number of Accessible children currently selected.
boolean | isAccessibleChildSelected(int i) Determines if the current child of this object is selected.
void | removeAccessibleSelection(int i) Removes the specified child of the object from the object's selection.
void | selectAllAccessibleSelection() Causes every child of the object to be selected if the object supports multiple selections.
void | stateChanged(ChangeEvent e) Invoked when the target of the listener has changed its state.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JTabbedPane.AccessibleJTabbedPane

public JTabbedPane.AccessibleJTabbedPane()
Constructs an AccessibleJTabbedPane

Method Detail

getAccessibleName

public String getAccessibleName()
Returns the accessible name of this object, or null if there is no accessible name.

Overrides:
getAccessibleName in class JComponent.AccessibleJComponent
Returns:
the accessible name of this object, nor null.
Since:
1.6
See Also:
AccessibleContext.setAccessibleName(java.lang.String)

stateChanged

public void stateChanged(ChangeEvent e)
Description copied from interface: ChangeListener
Invoked when the target of the listener has changed its state.

Specified by:
stateChanged in interface ChangeListener
Parameters:
e - a ChangeEvent object

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleChildrenCount

public int getAccessibleChildrenCount()
Returns the number of accessible children in the object.

Overrides:
getAccessibleChildrenCount in class JComponent.AccessibleJComponent
Returns:
the number of accessible children in the object.

getAccessibleChild

public Accessible getAccessibleChild(int i)
Return the specified Accessible child of the object.

Overrides:
getAccessibleChild in class JComponent.AccessibleJComponent
Parameters:
i - zero-based index of child
Returns:
the Accessible child of the object
Throws:
IllegalArgumentException - if index is out of bounds
See Also:
AccessibleContext.getAccessibleChildrenCount()

getAccessibleSelection

public AccessibleSelection getAccessibleSelection()
Gets the AccessibleSelection associated with this object. In the implementation of the Java Accessibility API for this class, returns this object, which is responsible for implementing the AccessibleSelection interface on behalf of itself.

Overrides:
getAccessibleSelection in class AccessibleContext
Returns:
this object
See Also:
AccessibleSelection

getAccessibleAt

public Accessible getAccessibleAt(Point p)
Returns the Accessible child contained at the local coordinate Point, if one exists. Otherwise returns the currently selected tab.

Specified by:
getAccessibleAt in interface AccessibleComponent
Overrides:
getAccessibleAt in class Container.AccessibleAWTContainer
Parameters:
p - the point defining the top-left corner of the Accessible, given in the coordinate space of the object's parent
Returns:
the Accessible at the specified location, if it exists

getAccessibleSelectionCount

public int getAccessibleSelectionCount()
Description copied from interface: AccessibleSelection
Returns the number of Accessible children currently selected. If no children are selected, the return value will be 0.

Specified by:
getAccessibleSelectionCount in interface AccessibleSelection
Returns:
the number of items currently selected.

getAccessibleSelection

public Accessible getAccessibleSelection(int i)
Description copied from interface: AccessibleSelection
Returns an Accessible representing the specified selected child of the object. If there isn't a selection, or there are fewer children selected than the integer passed in, the return value will be null.

Note that the index represents the i-th selected child, which is different from the i-th child.

Specified by:
getAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of selected children
Returns:
the i-th selected child
See Also:
AccessibleSelection.getAccessibleSelectionCount()

isAccessibleChildSelected

public boolean isAccessibleChildSelected(int i)
Description copied from interface: AccessibleSelection
Determines if the current child of this object is selected.

Specified by:
isAccessibleChildSelected in interface AccessibleSelection
Parameters:
i - the zero-based index of the child in this Accessible object.
Returns:
true if the current child of this object is selected; else false.
See Also:
AccessibleContext.getAccessibleChild(int)

addAccessibleSelection

public void addAccessibleSelection(int i)
Description copied from interface: AccessibleSelection
Adds the specified Accessible child of the object to the object's selection. If the object supports multiple selections, the specified child is added to any existing selection, otherwise it replaces any existing selection in the object. If the specified child is already selected, this method has no effect.

Specified by:
addAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of the child
See Also:
AccessibleContext.getAccessibleChild(int)

removeAccessibleSelection

public void removeAccessibleSelection(int i)
Description copied from interface: AccessibleSelection
Removes the specified child of the object from the object's selection. If the specified item isn't currently selected, this method has no effect.

Specified by:
removeAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of the child
See Also:
AccessibleContext.getAccessibleChild(int)

clearAccessibleSelection

public void clearAccessibleSelection()
Description copied from interface: AccessibleSelection
Clears the selection in the object, so that no children in the object are selected.

Specified by:
clearAccessibleSelection in interface AccessibleSelection

selectAllAccessibleSelection

public void selectAllAccessibleSelection()
Description copied from interface: AccessibleSelection
Causes every child of the object to be selected if the object supports multiple selections.

Specified by:
selectAllAccessibleSelection in interface AccessibleSelection
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTabbedPane.ModelListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTabbedPane.ModelListener

java.lang.Object
    extended by  javax.swing.JTabbedPane.ModelListener
All Implemented Interfaces:
Serializable, EventListener, ChangeListener
Enclosing class:
JTabbedPane
protected class JTabbedPane.ModelListener
extends Object
implements ChangeListener, Serializable

We pass ModelChanged events along to the listeners with the tabbedpane (instead of the model itself) as the event source.

Constructor Summary
protected JTabbedPane.ModelListener()
Method Summary
 void stateChanged(ChangeEvent e)
Invoked when the target of the listener has changed its state.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JTabbedPane.ModelListener

protected JTabbedPane.ModelListener()
Method Detail

stateChanged

public void stateChanged(ChangeEvent e)
Description copied from interface: ChangeListener
Invoked when the target of the listener has changed its state.

Specified by:
stateChanged in interface ChangeListener
Parameters:
e - a ChangeEvent object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTable

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTable

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JTable
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, EventListener, Accessible, CellEditorListener, ListSelectionListener, RowSorterListener, TableColumnModelListener, TableModelListener, Scrollable
public class JTable
extends JComponent
implements TableModelListener, Scrollable, TableColumnModelListener, ListSelectionListener, CellEditorListener, Accessible, RowSorterListener

The JTable is used to display and edit regular two-dimensional tables of cells. See How to Use Tables in The Java Tutorial for task-oriented documentation and examples of using JTable.

The JTable has many facilities that make it possible to customize its rendering and editing but provides defaults for these features so that simple tables can be set up easily. For example, to set up a table with 10 rows and 10 columns of numbers:

      TableModel dataModel = new AbstractTableModel() {
          public int getColumnCount() { return 10; }
          public int getRowCount() { return 10;}
          public Object getValueAt(int row, int col) { return new Integer(row*col); }
      };
      JTable table = new JTable(dataModel);
      JScrollPane scrollpane = new JScrollPane(table);

Note that if you wish to use a JTable in a standalone view (outside of a JScrollPane) and want the header displayed, you can get it using getTableHeader() and display it separately.

To enable sorting and filtering of rows, use a RowSorter. You can set up a row sorter in either of two ways:

  • Directly set the RowSorter. For example: table.setRowSorter(new TableRowSorter(model)).
  • Set the autoCreateRowSorter property to true, so that the JTable creates a RowSorter for you. For example: setAutoCreateRowSorter(true).

When designing applications that use the JTable it is worth paying close attention to the data structures that will represent the table's data. The DefaultTableModel is a model implementation that uses a Vector of Vectors of Objects to store the cell values. As well as copying the data from an application into the DefaultTableModel, it is also possible to wrap the data in the methods of the TableModel interface so that the data can be passed to the JTable directly, as in the example above. This often results in more efficient applications because the model is free to choose the internal representation that best suits the data. A good rule of thumb for deciding whether to use the AbstractTableModel or the DefaultTableModel is to use the AbstractTableModel as the base class for creating subclasses and the DefaultTableModel when subclassing is not required.

The "TableExample" directory in the demo area of the source distribution gives a number of complete examples of JTable usage, covering how the JTable can be used to provide an editable view of data taken from a database and how to modify the columns in the display to use specialized renderers and editors.

The JTable uses integers exclusively to refer to both the rows and the columns of the model that it displays. The JTable simply takes a tabular range of cells and uses getValueAt(int, int) to retrieve the values from the model during painting. It is important to remember that the column and row indexes returned by various JTable methods are in terms of the JTable (the view) and are not necessarily the same indexes used by the model.

By default, columns may be rearranged in the JTable so that the view's columns appear in a different order to the columns in the model. This does not affect the implementation of the model at all: when the columns are reordered, the JTable maintains the new order of the columns internally and converts its column indices before querying the model.

So, when writing a TableModel, it is not necessary to listen for column reordering events as the model will be queried in its own coordinate system regardless of what is happening in the view. In the examples area there is a demonstration of a sorting algorithm making use of exactly this technique to interpose yet another coordinate system where the order of the rows is changed, rather than the order of the columns.

Similarly when using the sorting and filtering functionality provided by RowSorter the underlying TableModel does not need to know how to do sorting, rather RowSorter will handle it. Coordinate conversions will be necessary when using the row based methods of JTable with the underlying TableModel. All of JTables row based methods are in terms of the RowSorter, which is not necessarily the same as that of the underlying TableModel. For example, the selection is always in terms of JTable so that when using RowSorter you will need to convert using convertRowIndexToView or convertRowIndexToModel. The following shows how to convert coordinates from JTable to that of the underlying model:

   int[] selection = table.getSelectedRows();
   for (int i = 0; i < selection.length; i++) {
     selection[i] = table.convertRowIndexToModel(selection[i]);
   }
   // selection is now in terms of the underlying TableModel

By default if sorting is enabled JTable will persist the selection and variable row heights in terms of the model on sorting. For example if row 0, in terms of the underlying model, is currently selected, after the sort row 0, in terms of the underlying model will be selected. Visually the selection may change, but in terms of the underlying model it will remain the same. The one exception to that is if the model index is no longer visible or was removed. For example, if row 0 in terms of model was filtered out the selection will be empty after the sort.

J2SE 5 adds methods to JTable to provide convenient access to some common printing needs. Simple new print() methods allow for quick and easy addition of printing support to your application. In addition, a new getPrintable(javax.swing.JTable.PrintMode, java.text.MessageFormat, java.text.MessageFormat) method is available for more advanced printing needs.

As for all JComponent classes, you can use InputMap and ActionMap to associate an Action object with a KeyStroke and execute the action under specified conditions.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
DefaultTableModel, TableRowSorter

Nested Class Summary
protected class | JTable.AccessibleJTable This class implements accessibility support for the JTable class.
static class | JTable.DropLocation A subclass of TransferHandler.DropLocation representing a drop location for a JTable.
static class | JTable.PrintMode Printing modes, used in printing JTables.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
static int | AUTO_RESIZE_ALL_COLUMNS During all resize operations, proportionately resize all columns.
static int | AUTO_RESIZE_LAST_COLUMN During all resize operations, apply adjustments to the last column only.
static int | AUTO_RESIZE_NEXT_COLUMN When a column is adjusted in the UI, adjust the next column the opposite way.
static int | AUTO_RESIZE_OFF Do not adjust column widths automatically; use a scrollbar.
static int | AUTO_RESIZE_SUBSEQUENT_COLUMNS During UI adjustment, change subsequent columns to preserve the total width; this is the default behavior.
protected boolean | autoCreateColumnsFromModel The table will query the TableModel to build the default set of columns if this is true.
protected int | autoResizeMode Determines if the table automatically resizes the width of the table's columns to take up the entire width of the table, and how it does the resizing.
protected TableCellEditor | cellEditor The active cell editor object, that overwrites the screen real estate occupied by the current cell and allows the user to change its contents.
protected boolean | cellSelectionEnabled Obsolete as of Java 2 platform v1.3.
protected TableColumnModel | columnModel The TableColumnModel of the table.
protected TableModel | dataModel The TableModel of the table.
protected Hashtable | defaultEditorsByColumnClass A table of objects that display and edit the contents of a cell, indexed by class as declared in getColumnClass in the TableModel interface.
protected Hashtable | defaultRenderersByColumnClass A table of objects that display the contents of a cell, indexed by class as declared in getColumnClass in the TableModel interface.
protected int | editingColumn Identifies the column of the cell being edited.
protected int | editingRow Identifies the row of the cell being edited.
protected Component | editorComp If editing, the Component that is handling the editing.
protected Color | gridColor The color of the grid.
protected Dimension | preferredViewportSize Used by the Scrollable interface to determine the initial visible area.
protected int | rowHeight The height in pixels of each row in the table.
protected int | rowMargin The height in pixels of the margin between the cells in each row.
protected boolean | rowSelectionAllowed True if row selection is allowed in this table.
protected Color | selectionBackground The background color of selected cells.
protected Color | selectionForeground The foreground color of selected cells.
protected ListSelectionModel | selectionModel The ListSelectionModel of the table, used to keep track of row selections.
protected boolean | showHorizontalLines The table draws horizontal lines between cells if showHorizontalLines is true.
protected boolean | showVerticalLines The table draws vertical lines between cells if showVerticalLines is true.
protected JTableHeader | tableHeader The TableHeader working with the table.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JTable()
Constructs a default JTable that is initialized with a default data model, a default column model, and a default selection model.
JTable(int numRows, int numColumns)
Constructs a JTable with numRows and numColumns of empty cells using DefaultTableModel.
JTable(Object[][] rowData, Object[] columnNames)
Constructs a JTable to display the values in the two dimensional array, rowData, with column names, columnNames.
JTable(TableModel dm)
Constructs a JTable that is initialized with dm as the data model, a default column model, and a default selection model.
JTable(TableModel dm, TableColumnModel cm)
Constructs a JTable that is initialized with dm as the data model, cm as the column model, and a default selection model.
JTable(TableModel dm, TableColumnModel cm, ListSelectionModel sm)
Constructs a JTable that is initialized with dm as the data model, cm as the column model, and sm as the selection model.
JTable(Vector rowData, Vector columnNames)
Constructs a JTable to display the values in the Vector of Vectors, rowData, with column names, columnNames.
Method Summary
void | addColumn(TableColumn aColumn) Appends aColumn to the end of the array of columns held by this JTable's column model.
void | addColumnSelectionInterval(int index0, int index1) Adds the columns from index0 to index1, inclusive, to the current selection.
void | addNotify() Calls the configureEnclosingScrollPane method.
void | addRowSelectionInterval(int index0, int index1) Adds the rows from index0 to index1, inclusive, to the current selection.
void | changeSelection(int rowIndex, int columnIndex, boolean toggle, boolean extend) Updates the selection models of the table, depending on the state of the two flags: toggle and extend.
void | clearSelection() Deselects all selected columns and rows.
void | columnAdded(TableColumnModelEvent e) Invoked when a column is added to the table column model.
int | columnAtPoint(Point point) Returns the index of the column that point lies in, or -1 if the result is not in the range [0, getColumnCount()-1].
void | columnMarginChanged(ChangeEvent e) Invoked when a column is moved due to a margin change.
void | columnMoved(TableColumnModelEvent e) Invoked when a column is repositioned.
void | columnRemoved(TableColumnModelEvent e) Invoked when a column is removed from the table column model.
void | columnSelectionChanged(ListSelectionEvent e) Invoked when the selection model of the TableColumnModel is changed.
protected void | configureEnclosingScrollPane() If this JTable is the viewportView of an enclosing JScrollPane (the usual situation), configure this ScrollPane by, amongst other things, installing the table's tableHeader as the columnHeaderView of the scroll pane.
int | convertColumnIndexToModel(int viewColumnIndex) Maps the index of the column in the view at viewColumnIndex to the index of the column in the table model.
int | convertColumnIndexToView(int modelColumnIndex) Maps the index of the column in the table model at modelColumnIndex to the index of the column in the view.
int | convertRowIndexToModel(int viewRowIndex) Maps the index of the row in terms of the view to the underlying TableModel.
int | convertRowIndexToView(int modelRowIndex) Maps the index of the row in terms of the TableModel to the view.
protected TableColumnModel | createDefaultColumnModel() Returns the default column model object, which is a DefaultTableColumnModel.
void | createDefaultColumnsFromModel() Creates default columns for the table from the data model using the getColumnCount method defined in the TableModel interface.
protected TableModel | createDefaultDataModel() Returns the default table model object, which is a DefaultTableModel.
protected void | createDefaultEditors() Creates default cell editors for objects, numbers, and boolean values.
protected void | createDefaultRenderers() Creates default cell renderers for objects, numbers, doubles, dates, booleans, and icons.
protected ListSelectionModel | createDefaultSelectionModel() Returns the default selection model object, which is a DefaultListSelectionModel.
protected JTableHeader | createDefaultTableHeader() Returns the default table header object, which is a JTableHeader.
static JScrollPane | createScrollPaneForTable(JTable aTable) Deprecated. As of Swing version 1.0.2, replaced by new JScrollPane(aTable).
void | doLayout() Causes this table to lay out its rows and columns.
boolean | editCellAt(int row, int column) Programmatically starts editing the cell at row and column, if those indices are in the valid range, and the cell at those indices is editable.
boolean | editCellAt(int row, int column, EventObject e) Programmatically starts editing the cell at row and column, if those indices are in the valid range, and the cell at those indices is editable.
void | editingCanceled(ChangeEvent e) Invoked when editing is canceled.
void | editingStopped(ChangeEvent e) Invoked when editing is finished.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JTable.
boolean | getAutoCreateColumnsFromModel() Determines whether the table will create default columns from the model.
boolean | getAutoCreateRowSorter() Returns true if whenever the model changes, a new RowSorter should be created and installed as the table's sorter; otherwise, returns false.
int | getAutoResizeMode() Returns the auto resize mode of the table.
TableCellEditor | getCellEditor() Returns the active cell editor, which is null if the table is not currently editing.
TableCellEditor | getCellEditor(int row, int column) Returns an appropriate editor for the cell specified by row and column.
Rectangle | getCellRect(int row, int column, boolean includeSpacing) Returns a rectangle for the cell that lies at the intersection of row and column.
TableCellRenderer | getCellRenderer(int row, int column) Returns an appropriate renderer for the cell specified by this row and column.
boolean | getCellSelectionEnabled() Returns true if both row and column selection models are enabled.
TableColumn | getColumn(Object identifier) Returns the TableColumn object for the column in the table whose identifier is equal to identifier, when compared using equals.
Class<?> | getColumnClass(int column) Returns the type of the column appearing in the view at column position column.
int | getColumnCount() Returns the number of columns in the column model.
TableColumnModel | getColumnModel() Returns the TableColumnModel that contains all column information of this table.
String | getColumnName(int column) Returns the name of the column appearing in the view at column position column.
boolean | getColumnSelectionAllowed() Returns true if columns can be selected.
TableCellEditor | getDefaultEditor(Class<?> columnClass) Returns the editor to be used when no editor has been set in a TableColumn.
TableCellRenderer | getDefaultRenderer(Class<?> columnClass) Returns the cell renderer to be used when no renderer has been set in a TableColumn.
boolean | getDragEnabled() Returns whether or not automatic drag handling is enabled.
JTable.DropLocation | getDropLocation() Returns the location that this component should visually indicate as the drop location during a DnD operation over the component, or null if no location is to currently be shown.
DropMode | getDropMode() Returns the drop mode for this component.
int | getEditingColumn() Returns the index of the column that contains the cell currently being edited.
int | getEditingRow() Returns the index of the row that contains the cell currently being edited.
Component | getEditorComponent() Returns the component that is handling the editing session.
boolean | getFillsViewportHeight() Returns whether or not this table is always made large enough to fill the height of an enclosing viewport.
Color | getGridColor() Returns the color used to draw grid lines.
Dimension | getIntercellSpacing() Returns the horizontal and vertical space between cells.
TableModel | getModel() Returns the TableModel that provides the data displayed by this JTable.
Dimension | getPreferredScrollableViewportSize() Returns the preferred size of the viewport for this table.
Printable | getPrintable(JTable.PrintMode printMode, MessageFormat headerFormat, MessageFormat footerFormat) Return a Printable for use in printing this JTable.
int | getRowCount() Returns the number of rows that can be shown in the JTable, given unlimited space.
int | getRowHeight() Returns the height of a table row, in pixels.
int | getRowHeight(int row) Returns the height, in pixels, of the cells in row.
int | getRowMargin() Gets the amount of empty space, in pixels, between cells.
boolean | getRowSelectionAllowed() Returns true if rows can be selected.
RowSorter<? extends TableModel> | getRowSorter() Returns the object responsible for sorting.
int | getScrollableBlockIncrement(Rectangle visibleRect, int orientation, int direction) Returns visibleRect.height or visibleRect.width, depending on this table's orientation.
boolean | getScrollableTracksViewportHeight() Returns false to indicate that the height of the viewport does not determine the height of the table, unless getFillsViewportHeight is true and the preferred height of the table is smaller than the viewport's height.
boolean | getScrollableTracksViewportWidth() Returns false if autoResizeMode is set to AUTO_RESIZE_OFF, which indicates that the width of the viewport does not determine the width of the table.
int | getScrollableUnitIncrement(Rectangle visibleRect, int orientation, int direction) Returns the scroll increment (in pixels) that completely exposes one new row or column (depending on the orientation).
int | getSelectedColumn() Returns the index of the first selected column, -1 if no column is selected.
int | getSelectedColumnCount() Returns the number of selected columns.
int[] | getSelectedColumns() Returns the indices of all selected columns.
int | getSelectedRow() Returns the index of the first selected row, -1 if no row is selected.
int | getSelectedRowCount() Returns the number of selected rows.
int[] | getSelectedRows() Returns the indices of all selected rows.
Color | getSelectionBackground() Returns the background color for selected cells.
Color | getSelectionForeground() Returns the foreground color for selected cells.
ListSelectionModel | getSelectionModel() Returns the ListSelectionModel that is used to maintain row selection state.
boolean | getShowHorizontalLines() Returns true if the table draws horizontal lines between cells, false if it doesn't.
boolean | getShowVerticalLines() Returns true if the table draws vertical lines between cells, false if it doesn't.
boolean | getSurrendersFocusOnKeystroke() Returns true if the editor should get the focus when keystrokes cause the editor to be activated
JTableHeader | getTableHeader() Returns the tableHeader used by this JTable.
String | getToolTipText(MouseEvent event) Overrides JComponent's getToolTipText method in order to allow the renderer's tips to be used if it has text set.
TableUI | getUI() Returns the L&F object that renders this component.
String | getUIClassID() Returns the suffix used to construct the name of the L&F class used to render this component.
boolean | getUpdateSelectionOnSort() Returns true if the selection should be updated after sorting.
Object | getValueAt(int row, int column) Returns the cell value at row and column.
protected void | initializeLocalVars() Initializes table properties to their default values.
boolean | isCellEditable(int row, int column) Returns true if the cell at row and column is editable.
boolean | isCellSelected(int row, int column) Returns true if the specified indices are in the valid range of rows and columns and the cell at the specified position is selected.
boolean | isColumnSelected(int column) Returns true if the specified index is in the valid range of columns, and the column at that index is selected.
boolean | isEditing() Returns true if a cell is being edited.
boolean | isRowSelected(int row) Returns true if the specified index is in the valid range of rows, and the row at that index is selected.
void | moveColumn(int column, int targetColumn) Moves the column column to the position currently occupied by the column targetColumn in the view.
protected String | paramString() Returns a string representation of this table.
Component | prepareEditor(TableCellEditor editor, int row, int column) Prepares the editor by querying the data model for the value and selection state of the cell at row, column.
Component | prepareRenderer(TableCellRenderer renderer, int row, int column) Prepares the renderer by querying the data model for the value and selection state of the cell at row, column.
boolean | print() A convenience method that displays a printing dialog, and then prints this JTable in mode PrintMode.FIT_WIDTH, with no header or footer text.
boolean | print(JTable.PrintMode printMode) A convenience method that displays a printing dialog, and then prints this JTable in the given printing mode, with no header or footer text.
boolean | print(JTable.PrintMode printMode, MessageFormat headerFormat, MessageFormat footerFormat) A convenience method that displays a printing dialog, and then prints this JTable in the given printing mode, with the specified header and footer text.
boolean | print(JTable.PrintMode printMode, MessageFormat headerFormat, MessageFormat footerFormat, boolean showPrintDialog, PrintRequestAttributeSet attr, boolean interactive) Prints this table, as specified by the fully featured print method, with the default printer specified as the print service.
boolean | print(JTable.PrintMode printMode, MessageFormat headerFormat, MessageFormat footerFormat, boolean showPrintDialog, PrintRequestAttributeSet attr, boolean interactive, PrintService service) Prints this JTable.
protected boolean | processKeyBinding(KeyStroke ks, KeyEvent e, int condition, boolean pressed) Invoked to process the key bindings for ks as the result of the KeyEvent e.
void | removeColumn(TableColumn aColumn) Removes aColumn from this JTable's array of columns.
void | removeColumnSelectionInterval(int index0, int index1) Deselects the columns from index0 to index1, inclusive.
void | removeEditor() Discards the editor object and frees the real estate it used for cell rendering.
void | removeNotify() Calls the unconfigureEnclosingScrollPane method.
void | removeRowSelectionInterval(int index0, int index1) Deselects the rows from index0 to index1, inclusive.
protected void | resizeAndRepaint() Equivalent to revalidate followed by repaint.
int | rowAtPoint(Point point) Returns the index of the row that point lies in, or -1 if the result is not in the range [0, getRowCount()-1].
void | selectAll() Selects all rows, columns, and cells in the table.
void | setAutoCreateColumnsFromModel(boolean autoCreateColumnsFromModel) Sets this table's autoCreateColumnsFromModel flag.
void | setAutoCreateRowSorter(boolean autoCreateRowSorter) Specifies whether a RowSorter should be created for the table whenever its model changes.
void | setAutoResizeMode(int mode) Sets the table's auto resize mode when the table is resized.
void | setCellEditor(TableCellEditor anEditor) Sets the active cell editor.
void | setCellSelectionEnabled(boolean cellSelectionEnabled) Sets whether this table allows both a column selection and a row selection to exist simultaneously.
void | setColumnModel(TableColumnModel columnModel) Sets the column model for this table to newModel and registers for listener notifications from the new column model.
void | setColumnSelectionAllowed(boolean columnSelectionAllowed) Sets whether the columns in this model can be selected.
void | setColumnSelectionInterval(int index0, int index1) Selects the columns from index0 to index1, inclusive.
void | setDefaultEditor(Class<?> columnClass, TableCellEditor editor) Sets a default cell editor to be used if no editor has been set in a TableColumn.
void | setDefaultRenderer(Class<?> columnClass, TableCellRenderer renderer) Sets a default cell renderer to be used if no renderer has been set in a TableColumn.
void | setDragEnabled(boolean b) Turns on or off automatic drag handling.
void | setDropMode(DropMode dropMode) Sets the drop mode for this component.
void | setEditingColumn(int aColumn) Sets the editingColumn variable.
void | setEditingRow(int aRow) Sets the editingRow variable.
void | setFillsViewportHeight(boolean fillsViewportHeight) Sets whether or not this table is always made large enough to fill the height of an enclosing viewport.
void | setGridColor(Color gridColor) Sets the color used to draw grid lines to gridColor and redisplays.
void | setIntercellSpacing(Dimension intercellSpacing) Sets the rowMargin and the columnMargin -- the height and width of the space between cells -- to intercellSpacing.
void | setModel(TableModel dataModel) Sets the data model for this table to newModel and registers with it for listener notifications from the new data model.
void | setPreferredScrollableViewportSize(Dimension size) Sets the preferred size of the viewport for this table.
void | setRowHeight(int rowHeight) Sets the height, in pixels, of all cells to rowHeight, revalidates, and repaints.
void | setRowHeight(int row, int rowHeight) Sets the height for row to rowHeight, revalidates, and repaints.
void | setRowMargin(int rowMargin) Sets the amount of empty space between cells in adjacent rows.
void | setRowSelectionAllowed(boolean rowSelectionAllowed) Sets whether the rows in this model can be selected.
void | setRowSelectionInterval(int index0, int index1) Selects the rows from index0 to index1, inclusive.
void | setRowSorter(RowSorter<? extends TableModel> sorter) Sets the RowSorter.
void | setSelectionBackground(Color selectionBackground) Sets the background color for selected cells.
void | setSelectionForeground(Color selectionForeground) Sets the foreground color for selected cells.
void | setSelectionMode(int selectionMode) Sets the table's selection mode to allow only single selections, a single contiguous interval, or multiple intervals.
void | setSelectionModel(ListSelectionModel newModel) Sets the row selection model for this table to newModel and registers for listener notifications from the new selection model.
void | setShowGrid(boolean showGrid) Sets whether the table draws grid lines around cells.
void | setShowHorizontalLines(boolean showHorizontalLines) Sets whether the table draws horizontal lines between cells.
void | setShowVerticalLines(boolean showVerticalLines) Sets whether the table draws vertical lines between cells.
void | setSurrendersFocusOnKeystroke(boolean surrendersFocusOnKeystroke) Sets whether editors in this JTable get the keyboard focus when an editor is activated as a result of the JTable forwarding keyboard events for a cell.
void | setTableHeader(JTableHeader tableHeader) Sets the tableHeader working with this JTable to newHeader.
void | setUI(TableUI ui) Sets the L&F object that renders this component and repaints.
void | setUpdateSelectionOnSort(boolean update) Specifies whether the selection should be updated after sorting.
void | setValueAt(Object aValue, int row, int column) Sets the value for the cell in the table model at row and column.
void | sizeColumnsToFit(boolean lastColumnOnly) Deprecated. As of Swing version 1.0.3, replaced by doLayout().
void | sizeColumnsToFit(int resizingColumn) Obsolete as of Java 2 platform v1.4.
void | sorterChanged(RowSorterEvent e) RowSorterListener notification that the RowSorter has changed in some way.
void | tableChanged(TableModelEvent e) Invoked when this table's TableModel generates a TableModelEvent.
protected void | unconfigureEnclosingScrollPane() Reverses the effect of configureEnclosingScrollPane by replacing the columnHeaderView of the enclosing scroll pane with null.
void | updateUI() Notification from the UIManager that the L&F has changed.
void | valueChanged(ListSelectionEvent e) Invoked when the row selection changes -- repaints to show the new selection.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

AUTO_RESIZE_OFF

public static final int AUTO_RESIZE_OFF
Do not adjust column widths automatically; use a scrollbar.

See Also:
Constant Field Values

AUTO_RESIZE_NEXT_COLUMN

public static final int AUTO_RESIZE_NEXT_COLUMN
When a column is adjusted in the UI, adjust the next column the opposite way.

See Also:
Constant Field Values

AUTO_RESIZE_SUBSEQUENT_COLUMNS

public static final int AUTO_RESIZE_SUBSEQUENT_COLUMNS
During UI adjustment, change subsequent columns to preserve the total width; this is the default behavior.

See Also:
Constant Field Values

AUTO_RESIZE_LAST_COLUMN

public static final int AUTO_RESIZE_LAST_COLUMN
During all resize operations, apply adjustments to the last column only.

See Also:
Constant Field Values

AUTO_RESIZE_ALL_COLUMNS

public static final int AUTO_RESIZE_ALL_COLUMNS
During all resize operations, proportionately resize all columns.

See Also:
Constant Field Values

dataModel

protected TableModel dataModel
The TableModel of the table.

columnModel

protected TableColumnModel columnModel
The TableColumnModel of the table.

selectionModel

protected ListSelectionModel selectionModel
The ListSelectionModel of the table, used to keep track of row selections.

tableHeader

protected JTableHeader tableHeader
The TableHeader working with the table.

rowHeight

protected int rowHeight
The height in pixels of each row in the table.

rowMargin

protected int rowMargin
The height in pixels of the margin between the cells in each row.

gridColor

protected Color gridColor
The color of the grid.

showHorizontalLines

protected boolean showHorizontalLines
The table draws horizontal lines between cells if showHorizontalLines is true.

showVerticalLines

protected boolean showVerticalLines
The table draws vertical lines between cells if showVerticalLines is true.

autoResizeMode

protected int autoResizeMode
Determines if the table automatically resizes the width of the table's columns to take up the entire width of the table, and how it does the resizing.

autoCreateColumnsFromModel

protected boolean autoCreateColumnsFromModel
The table will query the TableModel to build the default set of columns if this is true.

preferredViewportSize

protected Dimension preferredViewportSize
Used by the Scrollable interface to determine the initial visible area.

rowSelectionAllowed

protected boolean rowSelectionAllowed
True if row selection is allowed in this table.

cellSelectionEnabled

protected boolean cellSelectionEnabled
Obsolete as of Java 2 platform v1.3. Please use the rowSelectionAllowed property and the columnSelectionAllowed property of the columnModel instead. Or use the method getCellSelectionEnabled.

editorComp

protected transient Component editorComp
If editing, the Component that is handling the editing.

cellEditor

protected transient TableCellEditor cellEditor
The active cell editor object, that overwrites the screen real estate occupied by the current cell and allows the user to change its contents. null if the table isn't currently editing.

editingColumn

protected transient int editingColumn
Identifies the column of the cell being edited.

editingRow

protected transient int editingRow
Identifies the row of the cell being edited.

defaultRenderersByColumnClass

protected transient Hashtable defaultRenderersByColumnClass
A table of objects that display the contents of a cell, indexed by class as declared in getColumnClass in the TableModel interface.

defaultEditorsByColumnClass

protected transient Hashtable defaultEditorsByColumnClass
A table of objects that display and edit the contents of a cell, indexed by class as declared in getColumnClass in the TableModel interface.

selectionForeground

protected Color selectionForeground
The foreground color of selected cells.

selectionBackground

protected Color selectionBackground
The background color of selected cells.

Constructor Detail

JTable

public JTable()
Constructs a default JTable that is initialized with a default data model, a default column model, and a default selection model.

See Also:
createDefaultDataModel(),
createDefaultColumnModel(),
createDefaultSelectionModel()

JTable

public JTable(TableModel dm)
Constructs a JTable that is initialized with dm as the data model, a default column model, and a default selection model.

Parameters:
dm - the data model for the table
See Also:
createDefaultColumnModel(), createDefaultSelectionModel()

JTable

public JTable(TableModel dm,
              TableColumnModel cm)
Constructs a JTable that is initialized with dm as the data model, cm as the column model, and a default selection model.

Parameters:
dm - the data model for the table
cm - the column model for the table
See Also:
createDefaultSelectionModel()

JTable

public JTable(TableModel dm,
              TableColumnModel cm,
              ListSelectionModel sm)
Constructs a JTable that is initialized with dm as the data model, cm as the column model, and sm as the selection model. If any of the parameters are null this method will initialize the table with the corresponding default model. The autoCreateColumnsFromModel flag is set to false if cm is non-null, otherwise it is set to true and the column model is populated with suitable TableColumns for the columns in dm.

Parameters:
dm - the data model for the table
cm - the column model for the table
sm - the row selection model for the table
See Also:
createDefaultDataModel(),
createDefaultColumnModel(),
createDefaultSelectionModel()

JTable

public JTable(int numRows,
              int numColumns)
Constructs a JTable with numRows and numColumns of empty cells using DefaultTableModel. The columns will have names of the form "A", "B", "C", etc.

Parameters:
numRows - the number of rows the table holds
numColumns - the number of columns the table holds
See Also:
DefaultTableModel

JTable

public JTable(Vector rowData,
              Vector columnNames)
Constructs a JTable to display the values in the Vector of Vectors, rowData, with column names, columnNames. The Vectors contained in rowData should contain the values for that row. In other words, the value of the cell at row 1, column 5 can be obtained with the following code:

((Vector)rowData.elementAt(1)).elementAt(5);

Parameters:
rowData - the data for the new table
columnNames - names of each column

JTable

public JTable(Object[][] rowData,
              Object[] columnNames)
Constructs a JTable to display the values in the two dimensional array, rowData, with column names, columnNames. rowData is an array of rows, so the value of the cell at row 1, column 5 can be obtained with the following code:

 rowData[1][5];

All rows must be of the same length as columnNames.

Parameters:
rowData - the data for the new table
columnNames - names of each column
Method Detail

addNotify

public void addNotify()
Calls the configureEnclosingScrollPane method.

Overrides:
addNotify in class JComponent
See Also:
configureEnclosingScrollPane()

configureEnclosingScrollPane

protected void configureEnclosingScrollPane()
If this JTable is the viewportView of an enclosing JScrollPane (the usual situation), configure this ScrollPane by, amongst other things, installing the table's tableHeader as the columnHeaderView of the scroll pane. When a JTable is added to a JScrollPane in the usual way, using new JScrollPane(myTable), addNotify is called in the JTable (when the table is added to the viewport). JTable's addNotify method in turn calls this method, which is protected so that this default installation procedure can be overridden by a subclass.

See Also:
addNotify()

removeNotify

public void removeNotify()
Calls the unconfigureEnclosingScrollPane method.

Overrides:
removeNotify in class JComponent
See Also:
unconfigureEnclosingScrollPane()

unconfigureEnclosingScrollPane

protected void unconfigureEnclosingScrollPane()
Reverses the effect of configureEnclosingScrollPane by replacing the columnHeaderView of the enclosing scroll pane with null. JTable's removeNotify method calls this method, which is protected so that this default uninstallation procedure can be overridden by a subclass.

Since:
1.3
See Also:
removeNotify(), configureEnclosingScrollPane()

createScrollPaneForTable

@Deprecated
public static JScrollPane createScrollPaneForTable(JTable aTable)
Deprecated. As of Swing version 1.0.2, replaced by new JScrollPane(aTable).

Equivalent to new JScrollPane(aTable).

setTableHeader

public void setTableHeader(JTableHeader tableHeader)
Sets the tableHeader working with this JTable to newHeader. It is legal to have a null tableHeader.

Parameters:
tableHeader - new tableHeader
See Also:
getTableHeader()

getTableHeader

public JTableHeader getTableHeader()
Returns the tableHeader used by this JTable.

Returns:
the tableHeader used by this table
See Also:
setTableHeader(javax.swing.table.JTableHeader)

setRowHeight

public void setRowHeight(int rowHeight)
Sets the height, in pixels, of all cells to rowHeight, revalidates, and repaints. The height of the cells will be equal to the row height minus the row margin.

Parameters:
rowHeight - new row height
Throws:
IllegalArgumentException - if rowHeight is less than 1
See Also:
getRowHeight()

getRowHeight

public int getRowHeight()
Returns the height of a table row, in pixels. The default row height is 16.0.

Returns:
the height in pixels of a table row
See Also:
setRowHeight(int)

setRowHeight

public void setRowHeight(int row,
                         int rowHeight)
Sets the height for row to rowHeight, revalidates, and repaints. The height of the cells in this row will be equal to the row height minus the row margin.

Parameters:
row - the row whose height is being changed
rowHeight - new row height, in pixels
Throws:
IllegalArgumentException - if rowHeight is less than 1
Since:
1.3

getRowHeight

public int getRowHeight(int row)
Returns the height, in pixels, of the cells in row.

Parameters:
row - the row whose height is to be returned
Returns:
the height, in pixels, of the cells in the row
Since:
1.3

setRowMargin

public void setRowMargin(int rowMargin)
Sets the amount of empty space between cells in adjacent rows.

Parameters:
rowMargin - the number of pixels between cells in a row
See Also:
getRowMargin()

getRowMargin

public int getRowMargin()
Gets the amount of empty space, in pixels, between cells. Equivalent to: getIntercellSpacing().height.

Returns:
the number of pixels between cells in a row
See Also:
setRowMargin(int)

setIntercellSpacing

public void setIntercellSpacing(Dimension intercellSpacing)
Sets the rowMargin and the columnMargin -- the height and width of the space between cells -- to intercellSpacing.

Parameters:
intercellSpacing - a Dimension specifying the new width and height between cells
See Also:
getIntercellSpacing()

getIntercellSpacing

public Dimension getIntercellSpacing()
Returns the horizontal and vertical space between cells. The default spacing is (1, 1), which provides room to draw the grid.

Returns:
the horizontal and vertical spacing between cells
See Also:
setIntercellSpacing(java.awt.Dimension)

setGridColor

public void setGridColor(Color gridColor)
Sets the color used to draw grid lines to gridColor and redisplays. The default color is look and feel dependent.

Parameters:
gridColor - the new color of the grid lines
Throws:
IllegalArgumentException - if gridColor is null
See Also:
getGridColor()

getGridColor

public Color getGridColor()
Returns the color used to draw grid lines. The default color is look and feel dependent.

Returns:
the color used to draw grid lines
See Also:
setGridColor(java.awt.Color)

setShowGrid

public void setShowGrid(boolean showGrid)
Sets whether the table draws grid lines around cells. If showGrid is true it does; if it is false it doesn't. There is no getShowGrid method as this state is held in two variables -- showHorizontalLines and showVerticalLines -- each of which can be queried independently.

Parameters:
showGrid - true if table view should draw grid lines
See Also:
setShowVerticalLines(boolean), setShowHorizontalLines(boolean)

setShowHorizontalLines

public void setShowHorizontalLines(boolean showHorizontalLines)
Sets whether the table draws horizontal lines between cells. If showHorizontalLines is true it does; if it is false it doesn't.

Parameters:
showHorizontalLines - true if table view should draw horizontal lines
See Also:
getShowHorizontalLines(), setShowGrid(boolean), setShowVerticalLines(boolean)

setShowVerticalLines

public void setShowVerticalLines(boolean showVerticalLines)
Sets whether the table draws vertical lines between cells. If showVerticalLines is true it does; if it is false it doesn't.

Parameters:
showVerticalLines - true if table view should draw vertical lines
See Also:
getShowVerticalLines(), setShowGrid(boolean), setShowHorizontalLines(boolean)

getShowHorizontalLines

public boolean getShowHorizontalLines()
Returns true if the table draws horizontal lines between cells, false if it doesn't. The default is true.

Returns:
true if the table draws horizontal lines between cells, false if it doesn't
See Also:
setShowHorizontalLines(boolean)

getShowVerticalLines

public boolean getShowVerticalLines()
Returns true if the table draws vertical lines between cells, false if it doesn't. The default is true.

Returns:
true if the table draws vertical lines between cells, false if it doesn't
See Also:
setShowVerticalLines(boolean)

setAutoResizeMode

public void setAutoResizeMode(int mode)
Sets the table's auto resize mode when the table is resized.

Parameters:
mode - One of 5 legal values: AUTO_RESIZE_OFF, AUTO_RESIZE_NEXT_COLUMN, AUTO_RESIZE_SUBSEQUENT_COLUMNS, AUTO_RESIZE_LAST_COLUMN, AUTO_RESIZE_ALL_COLUMNS
See Also:
getAutoResizeMode(), doLayout()

getAutoResizeMode

public int getAutoResizeMode()
Returns the auto resize mode of the table. The default mode is AUTO_RESIZE_SUBSEQUENT_COLUMNS.

Returns:
the autoResizeMode of the table
See Also:
setAutoResizeMode(int), doLayout()

setAutoCreateColumnsFromModel

public void setAutoCreateColumnsFromModel(boolean autoCreateColumnsFromModel)
Sets this table's autoCreateColumnsFromModel flag. This method calls createDefaultColumnsFromModel if autoCreateColumnsFromModel changes from false to true.

Parameters:
autoCreateColumnsFromModel - true if JTable should automatically create columns
See Also:
getAutoCreateColumnsFromModel(), createDefaultColumnsFromModel()

getAutoCreateColumnsFromModel

public boolean getAutoCreateColumnsFromModel()
Determines whether the table will create default columns from the model. If true, setModel will clear any existing columns and create new columns from the new model. Also, if the event in the tableChanged notification specifies that the entire table changed, then the columns will be rebuilt. The default is true.

Returns:
the autoCreateColumnsFromModel of the table
See Also:
setAutoCreateColumnsFromModel(boolean), createDefaultColumnsFromModel()

createDefaultColumnsFromModel

public void createDefaultColumnsFromModel()
Creates default columns for the table from the data model using the getColumnCount method defined in the TableModel interface.

Clears any existing columns before creating the new columns based on information from the model.

See Also:
getAutoCreateColumnsFromModel()

setDefaultRenderer

public void setDefaultRenderer(Class<?> columnClass,
                               TableCellRenderer renderer)
Sets a default cell renderer to be used if no renderer has been set in a TableColumn. If renderer is null, removes the default renderer for this column class.

Parameters:
columnClass - set the default cell renderer for this columnClass
renderer - default cell renderer to be used for this columnClass
See Also:
getDefaultRenderer(java.lang.Class), setDefaultEditor(java.lang.Class, javax.swing.table.TableCellEditor)

getDefaultRenderer

public TableCellRenderer getDefaultRenderer(Class<?> columnClass)
Returns the cell renderer to be used when no renderer has been set in a TableColumn. During the rendering of cells the renderer is fetched from a Hashtable of entries according to the class of the cells in the column. If there is no entry for this columnClass the method returns the entry for the most specific superclass. The JTable installs entries for Object, Number, and Boolean, all of which can be modified or replaced.

Parameters:
columnClass - return the default cell renderer for this columnClass
Returns:
the renderer for this columnClass
See Also:
setDefaultRenderer(java.lang.Class, javax.swing.table.TableCellRenderer), getColumnClass(int)

setDefaultEditor

public void setDefaultEditor(Class<?> columnClass,
                             TableCellEditor editor)
Sets a default cell editor to be used if no editor has been set in a TableColumn. If no editing is required in a table, or a particular column in a table, uses the isCellEditable method in the TableModel interface to ensure that this JTable will not start an editor in these columns. If editor is null, removes the default editor for this column class.

Parameters:
columnClass - set the default cell editor for this columnClass
editor - default cell editor to be used for this columnClass
See Also:
TableModel.isCellEditable(int, int),
getDefaultEditor(java.lang.Class),
setDefaultRenderer(java.lang.Class, javax.swing.table.TableCellRenderer)

getDefaultEditor

public TableCellEditor getDefaultEditor(Class<?> columnClass)
Returns the editor to be used when no editor has been set in a TableColumn. During the editing of cells the editor is fetched from a Hashtable of entries according to the class of the cells in the column. If there is no entry for this columnClass the method returns the entry for the most specific superclass. The JTable installs entries for Object, Number, and Boolean, all of which can be modified or replaced.

Parameters:
columnClass - return the default cell editor for this columnClass
Returns:
the default cell editor to be used for this columnClass
See Also:
setDefaultEditor(java.lang.Class, javax.swing.table.TableCellEditor), getColumnClass(int)

setDragEnabled

public void setDragEnabled(boolean b)
Turns on or off automatic drag handling. In order to enable automatic drag handling, this property should be set to true, and the table's TransferHandler needs to be non-null. The default value of the dragEnabled property is false.

The job of honoring this property, and recognizing a user drag gesture, lies with the look and feel implementation, and in particular, the table's TableUI. When automatic drag handling is enabled, most look and feels (including those that subclass BasicLookAndFeel) begin a drag and drop operation whenever the user presses the mouse button over an item (in single selection mode) or a selection (in other selection modes) and then moves the mouse a few pixels. Setting this property to true can therefore have a subtle effect on how selections behave.

If a look and feel is used that ignores this property, you can still begin a drag and drop operation by calling exportAsDrag on the table's TransferHandler.

Parameters:
b - whether or not to enable automatic drag handling
Throws:
HeadlessException - if b is true and GraphicsEnvironment.isHeadless() returns true
Since:
1.4
See Also:
GraphicsEnvironment.isHeadless(),
getDragEnabled(),
JComponent.setTransferHandler(javax.swing.TransferHandler),
TransferHandler

getDragEnabled

public boolean getDragEnabled()
Returns whether or not automatic drag handling is enabled.

Returns:
the value of the dragEnabled property
Since:
1.4
See Also:
setDragEnabled(boolean)

setDropMode

public final void setDropMode(DropMode dropMode)
Sets the drop mode for this component. For backward compatibility, the default for this property is DropMode.USE_SELECTION. Usage of one of the other modes is recommended, however, for an improved user experience. DropMode.ON, for instance, offers similar behavior of showing items as selected, but does so without affecting the actual selection in the table.

JTable supports the following drop modes:

  • DropMode.USE_SELECTION
  • DropMode.ON
  • DropMode.INSERT
  • DropMode.INSERT_ROWS
  • DropMode.INSERT_COLS
  • DropMode.ON_OR_INSERT
  • DropMode.ON_OR_INSERT_ROWS
  • DropMode.ON_OR_INSERT_COLS

The drop mode is only meaningful if this component has a TransferHandler that accepts drops.

Parameters:
dropMode - the drop mode to use
Throws:
IllegalArgumentException - if the drop mode is unsupported or null
Since:
1.6
See Also:
getDropMode(),
getDropLocation(),
JComponent.setTransferHandler(javax.swing.TransferHandler),
TransferHandler

getDropMode

public final DropMode getDropMode()
Returns the drop mode for this component.

Returns:
the drop mode for this component
Since:
1.6
See Also:
setDropMode(javax.swing.DropMode)

getDropLocation

public final JTable.DropLocation getDropLocation()
Returns the location that this component should visually indicate as the drop location during a DnD operation over the component, or null if no location is to currently be shown.

This method is not meant for querying the drop location from a TransferHandler, as the drop location is only set after the TransferHandler's canImport has returned and has allowed for the location to be shown.

When this property changes, a property change event with name "dropLocation" is fired by the component.

Returns:
the drop location
Since:
1.6
See Also:
setDropMode(javax.swing.DropMode), TransferHandler.canImport(TransferHandler.TransferSupport)

setAutoCreateRowSorter

public void setAutoCreateRowSorter(boolean autoCreateRowSorter)
Specifies whether a RowSorter should be created for the table whenever its model changes.

When setAutoCreateRowSorter(true) is invoked, a TableRowSorter is immediately created and installed on the table. While the autoCreateRowSorter property remains true, every time the model is changed, a new TableRowSorter is created and set as the table's row sorter.

Parameters:
autoCreateRowSorter - whether or not a RowSorter should be automatically created
Since:
1.6
See Also:
TableRowSorter

getAutoCreateRowSorter

public boolean getAutoCreateRowSorter()
Returns true if whenever the model changes, a new RowSorter should be created and installed as the table's sorter; otherwise, returns false.

Returns:
true if a RowSorter should be created when the model changes
Since:
1.6

setUpdateSelectionOnSort

public void setUpdateSelectionOnSort(boolean update)
Specifies whether the selection should be updated after sorting. If true, on sorting the selection is reset such that the same rows, in terms of the model, remain selected. The default is true.

Parameters:
update - whether or not to update the selection on sorting
Since:
1.6

getUpdateSelectionOnSort

public boolean getUpdateSelectionOnSort()
Returns true if the selection should be updated after sorting.

Returns:
whether to update the selection on a sort
Since:
1.6

setRowSorter

public void setRowSorter(RowSorter<? extends TableModel> sorter)
Sets the RowSorter. RowSorter is used to provide sorting and filtering to a JTable.

This method clears the selection and resets any variable row heights.

If the underlying model of the RowSorter differs from that of this JTable undefined behavior will result.

Parameters:
sorter - the RowSorter; null turns sorting off
Since:
1.6
See Also:
TableRowSorter

getRowSorter

public RowSorter<? extends TableModel> getRowSorter()
Returns the object responsible for sorting.

Returns:
the object responsible for sorting
Since:
1.6

setSelectionMode

public void setSelectionMode(int selectionMode)
Sets the table's selection mode to allow only single selections, a single contiguous interval, or multiple intervals.

Note: JTable provides all the methods for handling column and row selection. When setting states, such as setSelectionMode, it not only updates the mode for the row selection model but also sets similar values in the selection model of the columnModel. If you want to have the row and column selection models operating in different modes, set them both directly.

Both the row and column selection models for JTable default to using a DefaultListSelectionModel so that JTable works the same way as the JList. See the setSelectionMode method in JList for details about the modes.

See Also:
JList.setSelectionMode(int)

setRowSelectionAllowed

public void setRowSelectionAllowed(boolean rowSelectionAllowed)
Sets whether the rows in this model can be selected.

Parameters:
rowSelectionAllowed - true if this model will allow row selection
See Also:
getRowSelectionAllowed()

getRowSelectionAllowed

public boolean getRowSelectionAllowed()
Returns true if rows can be selected.

Returns:
true if rows can be selected, otherwise false
See Also:
setRowSelectionAllowed(boolean)

setColumnSelectionAllowed

public void setColumnSelectionAllowed(boolean columnSelectionAllowed)
Sets whether the columns in this model can be selected.

Parameters:
columnSelectionAllowed - true if this model will allow column selection
See Also:
getColumnSelectionAllowed()

getColumnSelectionAllowed

public boolean getColumnSelectionAllowed()
Returns true if columns can be selected.

Returns:
true if columns can be selected, otherwise false
See Also:
setColumnSelectionAllowed(boolean)

setCellSelectionEnabled

public void setCellSelectionEnabled(boolean cellSelectionEnabled)
Sets whether this table allows both a column selection and a row selection to exist simultaneously. When set, the table treats the intersection of the row and column selection models as the selected cells. Override isCellSelected to change this default behavior. This method is equivalent to setting both the rowSelectionAllowed property and columnSelectionAllowed property of the columnModel to the supplied value.

Parameters:
cellSelectionEnabled - true if simultaneous row and column selection is allowed
See Also:
getCellSelectionEnabled(), isCellSelected(int, int)

getCellSelectionEnabled

public boolean getCellSelectionEnabled()
Returns true if both row and column selection models are enabled. Equivalent to getRowSelectionAllowed() && getColumnSelectionAllowed().

Returns:
true if both row and column selection models are enabled
See Also:
setCellSelectionEnabled(boolean)

selectAll

public void selectAll()
Selects all rows, columns, and cells in the table.

clearSelection

public void clearSelection()
Deselects all selected columns and rows.

setRowSelectionInterval

public void setRowSelectionInterval(int index0,
                                    int index1)
Selects the rows from index0 to index1, inclusive.

Parameters:
index0 - one end of the interval
index1 - the other end of the interval
Throws:
IllegalArgumentException - if index0 or index1 lie outside [0, getRowCount()-1]

setColumnSelectionInterval

public void setColumnSelectionInterval(int index0,
                                       int index1)
Selects the columns from index0 to index1, inclusive.

Parameters:
index0 - one end of the interval
index1 - the other end of the interval
Throws:
IllegalArgumentException - if index0 or index1 lie outside [0, getColumnCount()-1]

addRowSelectionInterval

public void addRowSelectionInterval(int index0,
                                    int index1)
Adds the rows from index0 to index1, inclusive, to the current selection.

Parameters:
index0 - one end of the interval
index1 - the other end of the interval
Throws:
IllegalArgumentException - if index0 or index1 lie outside [0, getRowCount()-1]

addColumnSelectionInterval

public void addColumnSelectionInterval(int index0,
                                       int index1)
Adds the columns from index0 to index1, inclusive, to the current selection.

Parameters:
index0 - one end of the interval
index1 - the other end of the interval
Throws:
IllegalArgumentException - if index0 or index1 lie outside [0, getColumnCount()-1]

removeRowSelectionInterval

public void removeRowSelectionInterval(int index0,
                                       int index1)
Deselects the rows from index0 to index1, inclusive.

Parameters:
index0 - one end of the interval
index1 - the other end of the interval
Throws:
IllegalArgumentException - if index0 or index1 lie outside [0, getRowCount()-1]

removeColumnSelectionInterval

public void removeColumnSelectionInterval(int index0,
                                          int index1)
Deselects the columns from index0 to index1, inclusive.

Parameters:
index0 - one end of the interval
index1 - the other end of the interval
Throws:
IllegalArgumentException - if index0 or index1 lie outside [0, getColumnCount()-1]

getSelectedRow

public int getSelectedRow()
Returns the index of the first selected row, -1 if no row is selected.

Returns:
the index of the first selected row

getSelectedColumn

public int getSelectedColumn()
Returns the index of the first selected column, -1 if no column is selected.

Returns:
the index of the first selected column

getSelectedRows

public int[] getSelectedRows()
Returns the indices of all selected rows.

Returns:
an array of integers containing the indices of all selected rows, or an empty array if no row is selected
See Also:
getSelectedRow()

getSelectedColumns

public int[] getSelectedColumns()
Returns the indices of all selected columns.

Returns:
an array of integers containing the indices of all selected columns, or an empty array if no column is selected
See Also:
getSelectedColumn()

getSelectedRowCount

public int getSelectedRowCount()
Returns the number of selected rows.

Returns:
the number of selected rows, 0 if no rows are selected

getSelectedColumnCount

public int getSelectedColumnCount()
Returns the number of selected columns.

Returns:
the number of selected columns, 0 if no columns are selected

isRowSelected

public boolean isRowSelected(int row)
Returns true if the specified index is in the valid range of rows, and the row at that index is selected.

Returns:
true if row is a valid index and the row at that index is selected (where 0 is the first row)

isColumnSelected

public boolean isColumnSelected(int column)
Returns true if the specified index is in the valid range of columns, and the column at that index is selected.

Parameters:
column - the column in the column model
Returns:
true if column is a valid index and the column at that index is selected (where 0 is the first column)

isCellSelected

public boolean isCellSelected(int row,
                              int column)
Returns true if the specified indices are in the valid range of rows and columns and the cell at the specified position is selected.

Parameters:
row - the row being queried
column - the column being queried
Returns:
true if row and column are valid indices and the cell at index (row, column) is selected, where the first row and first column are at index 0

changeSelection

public void changeSelection(int rowIndex,
                            int columnIndex,
                            boolean toggle,
                            boolean extend)
Updates the selection models of the table, depending on the state of the two flags: toggle and extend. Most changes to the selection that are the result of keyboard or mouse events received by the UI are channeled through this method so that the behavior may be overridden by a subclass. Some UIs may need more functionality than this method provides, such as when manipulating the lead for discontiguous selection, and may not call into this method for some selection changes.

This implementation uses the following conventions:

  • toggle: false, extend: false. Clear the previous selection and ensure the new cell is selected.
  • toggle: false, extend: true. Extend the previous selection from the anchor to the specified cell, clearing all other selections.
  • toggle: true, extend: false. If the specified cell is selected, deselect it. If it is not selected, select it.
  • toggle: true, extend: true. Apply the selection state of the anchor to all cells between it and the specified cell.

Parameters:
rowIndex - affects the selection at row
columnIndex - affects the selection at column
toggle - see description above
extend - if true, extend the current selection
Since:
1.3

getSelectionForeground

public Color getSelectionForeground()
Returns the foreground color for selected cells.

Returns:
the Color object for the foreground property
See Also:
setSelectionForeground(java.awt.Color), setSelectionBackground(java.awt.Color)

setSelectionForeground

public void setSelectionForeground(Color selectionForeground)
Sets the foreground color for selected cells. Cell renderers can use this color to render text and graphics for selected cells.

The default value of this property is defined by the look and feel implementation.

This is a JavaBeans bound property.

Parameters:
selectionForeground - the Color to use in the foreground for selected list items
See Also:
getSelectionForeground(),
setSelectionBackground(java.awt.Color),
JComponent.setForeground(java.awt.Color),
JComponent.setBackground(java.awt.Color),
JComponent.setFont(java.awt.Font)

getSelectionBackground

public Color getSelectionBackground()
Returns the background color for selected cells.

Returns:
the Color used for the background of selected list items
See Also:
setSelectionBackground(java.awt.Color), setSelectionForeground(java.awt.Color)

setSelectionBackground

public void setSelectionBackground(Color selectionBackground)
Sets the background color for selected cells. Cell renderers can use this color to the fill selected cells.

The default value of this property is defined by the look and feel implementation.

This is a JavaBeans bound property.

Parameters:
selectionBackground - the Color to use for the background of selected cells
See Also:
getSelectionBackground(),
setSelectionForeground(java.awt.Color),
JComponent.setForeground(java.awt.Color),
JComponent.setBackground(java.awt.Color),
JComponent.setFont(java.awt.Font)

getColumn

public TableColumn getColumn(Object identifier)
Returns the TableColumn object for the column in the table whose identifier is equal to identifier, when compared using equals.

Parameters:
identifier - the identifier object
Returns:
the TableColumn object that matches the identifier
Throws:
IllegalArgumentException - if identifier is null or no TableColumn has this identifier

convertColumnIndexToModel

public int convertColumnIndexToModel(int viewColumnIndex)
Maps the index of the column in the view at viewColumnIndex to the index of the column in the table model. Returns the index of the corresponding column in the model. If viewColumnIndex is less than zero, returns viewColumnIndex.

Parameters:
viewColumnIndex - the index of the column in the view
Returns:
the index of the corresponding column in the model
See Also:
convertColumnIndexToView(int)

convertColumnIndexToView

public int convertColumnIndexToView(int modelColumnIndex)
Maps the index of the column in the table model at modelColumnIndex to the index of the column in the view. Returns the index of the corresponding column in the view; returns -1 if this column is not being displayed. If modelColumnIndex is less than zero, returns modelColumnIndex.

Parameters:
modelColumnIndex - the index of the column in the model
Returns:
the index of the corresponding column in the view
See Also:
convertColumnIndexToModel(int)

convertRowIndexToView

public int convertRowIndexToView(int modelRowIndex)
Maps the index of the row in terms of the TableModel to the view. If the contents of the model are not sorted the model and view indices are the same.

Parameters:
modelRowIndex - the index of the row in terms of the model
Returns:
the index of the corresponding row in the view, or -1 if the row isn't visible
Throws:
IndexOutOfBoundsException - if sorting is enabled and passed an index outside the number of rows of the TableModel
Since:
1.6
See Also:
TableRowSorter

convertRowIndexToModel

public int convertRowIndexToModel(int viewRowIndex)
Maps the index of the row in terms of the view to the underlying TableModel. If the contents of the model are not sorted the model and view indices are the same.

Parameters:
viewRowIndex - the index of the row in the view
Returns:
the index of the corresponding row in the model
Throws:
IndexOutOfBoundsException - if sorting is enabled and passed an index outside the range of the JTable as determined by the method getRowCount
Since:
1.6
See Also:
TableRowSorter, getRowCount()

getRowCount

public int getRowCount()
Returns the number of rows that can be shown in the JTable, given unlimited space. If a RowSorter with a filter has been specified, the number of rows returned may differ from that of the underlying TableModel.

Returns:
the number of rows shown in the JTable
See Also:
getColumnCount()

getColumnCount

public int getColumnCount()
Returns the number of columns in the column model. Note that this may be different from the number of columns in the table model.

Returns:
the number of columns in the table
See Also:
getRowCount(), removeColumn(javax.swing.table.TableColumn)

getColumnName

public String getColumnName(int column)
Returns the name of the column appearing in the view at column position column.

Parameters:
column - the column in the view being queried
Returns:
the name of the column at position column in the view where the first column is column 0

getColumnClass

public Class<?> getColumnClass(int column)
Returns the type of the column appearing in the view at column position column.

Parameters:
column - the column in the view being queried
Returns:
the type of the column at position column in the view where the first column is column 0

getValueAt

public Object getValueAt(int row,
                         int column)
Returns the cell value at row and column.

Note: The column is specified in the table view's display order, and not in the TableModel's column order. This is an important distinction because as the user rearranges the columns in the table, the column at a given index in the view will change. Meanwhile the user's actions never affect the model's column ordering.

Parameters:
row - the row whose value is to be queried
column - the column whose value is to be queried
Returns:
the Object at the specified cell

setValueAt

public void setValueAt(Object aValue,
                       int row,
                       int column)
Sets the value for the cell in the table model at row and column.

Note: The column is specified in the table view's display order, and not in the TableModel's column order. This is an important distinction because as the user rearranges the columns in the table, the column at a given index in the view will change. Meanwhile the user's actions never affect the model's column ordering. aValue is the new value.

Parameters:
aValue - the new value
row - the row of the cell to be changed
column - the column of the cell to be changed
See Also:
getValueAt(int, int)

isCellEditable

public boolean isCellEditable(int row,
                              int column)
Returns true if the cell at row and column is editable. Otherwise, invoking setValueAt on the cell will have no effect.

Note: The column is specified in the table view's display order, and not in the TableModel's column order. This is an important distinction because as the user rearranges the columns in the table, the column at a given index in the view will change. Meanwhile the user's actions never affect the model's column ordering.

Parameters:
row - the row whose value is to be queried
column - the column whose value is to be queried
Returns:
true if the cell is editable
See Also:
setValueAt(java.lang.Object, int, int)

addColumn

public void addColumn(TableColumn aColumn)
Appends aColumn to the end of the array of columns held by this JTable's column model. If the column name of aColumn is null, sets the column name of aColumn to the name returned by getModel().getColumnName().

To add a column to this JTable to display the modelColumn'th column of data in the model with a given width, cellRenderer, and cellEditor you can use:

      addColumn(new TableColumn(modelColumn, width, cellRenderer, cellEditor));
[Any of the TableColumn constructors can be used instead of this one.] The model column number is stored inside the TableColumn and is used during rendering and editing to locate the appropriates data values in the model. The model column number does not change when columns are reordered in the view.

Parameters:
aColumn - the TableColumn to be added
See Also:
removeColumn(javax.swing.table.TableColumn)

removeColumn

public void removeColumn(TableColumn aColumn)
Removes aColumn from this JTable's array of columns. Note: this method does not remove the column of data from the model; it just removes the TableColumn that was responsible for displaying it.

Parameters:
aColumn - the TableColumn to be removed
See Also:
addColumn(javax.swing.table.TableColumn)

moveColumn

public void moveColumn(int column,
                       int targetColumn)
Moves the column column to the position currently occupied by the column targetColumn in the view. The old column at targetColumn is shifted left or right to make room.

Parameters:
column - the index of column to be moved
targetColumn - the new index of the column

columnAtPoint

public int columnAtPoint(Point point)
Returns the index of the column that point lies in, or -1 if the result is not in the range [0, getColumnCount()-1].

Parameters:
point - the location of interest
Returns:
the index of the column that point lies in, or -1 if the result is not in the range [0, getColumnCount()-1]
See Also:
rowAtPoint(java.awt.Point)

rowAtPoint

public int rowAtPoint(Point point)
Returns the index of the row that point lies in, or -1 if the result is not in the range [0, getRowCount()-1].

Parameters:
point - the location of interest
Returns:
the index of the row that point lies in, or -1 if the result is not in the range [0, getRowCount()-1]
See Also:
columnAtPoint(java.awt.Point)

getCellRect

public Rectangle getCellRect(int row,
                             int column,
                             boolean includeSpacing)
Returns a rectangle for the cell that lies at the intersection of row and column. If includeSpacing is true then the value returned has the full height and width of the row and column specified. If it is false, the returned rectangle is inset by the intercell spacing to return the true bounds of the rendering or editing component as it will be set during rendering.

If the column index is valid but the row index is less than zero the method returns a rectangle with the y and height values set appropriately and the x and width values both set to zero. In general, when either the row or column indices indicate a cell outside the appropriate range, the method returns a rectangle depicting the closest edge of the closest cell that is within the table's range. When both row and column indices are out of range the returned rectangle covers the closest point of the closest cell.

In all cases, calculations that use this method to calculate results along one axis will not fail because of anomalies in calculations along the other axis. When the cell is not valid the includeSpacing parameter is ignored.

Parameters:
row - the row index where the desired cell is located
column - the column index where the desired cell is located in the display; this is not necessarily the same as the column index in the data model for the table; the convertColumnIndexToView(int) method may be used to convert a data model column index to a display column index
includeSpacing - if false, return the true cell bounds - computed by subtracting the intercell spacing from the height and widths of the column and row models
Returns:
the rectangle containing the cell at location row,column
See Also:
getIntercellSpacing()

doLayout

public void doLayout()
Causes this table to lay out its rows and columns. Overridden so that columns can be resized to accomodate a change in the size of a containing parent. Resizes one or more of the columns in the table so that the total width of all of this JTable's columns is equal to the width of the table.

Before the layout begins the method gets the resizingColumn of the tableHeader. When the method is called as a result of the resizing of an enclosing window, the resizingColumn is null. This means that resizing has taken place "outside" the JTable and the change - or "delta" - should be distributed to all of the columns regardless of this JTable's automatic resize mode.

If the resizingColumn is not null, it is one of the columns in the table that has changed size rather than the table itself. In this case the auto-resize modes govern the way the extra (or deficit) space is distributed amongst the available columns.

The modes are:

  • AUTO_RESIZE_OFF: Don't automatically adjust the column's widths at all. Use a horizontal scrollbar to accomodate the columns when their sum exceeds the width of the Viewport. If the JTable is not enclosed in a JScrollPane this may leave parts of the table invisible.
  • AUTO_RESIZE_NEXT_COLUMN: Use just the column after the resizing column. This results in the "boundary" or divider between adjacent cells being independently adjustable.
  • AUTO_RESIZE_SUBSEQUENT_COLUMNS: Use all columns after the one being adjusted to absorb the changes. This is the default behavior.
  • AUTO_RESIZE_LAST_COLUMN: Automatically adjust the size of the last column only. If the bounds of the last column prevent the desired size from being allocated, set the width of the last column to the appropriate limit and make no further adjustments.
  • AUTO_RESIZE_ALL_COLUMNS: Spread the delta amongst all the columns in the JTable, including the one that is being adjusted.

Note: When a JTable makes adjustments to the widths of the columns it respects their minimum and maximum values absolutely. It is therefore possible that, even after this method is called, the total width of the columns is still not equal to the width of the table. When this happens the JTable does not put itself in AUTO_RESIZE_OFF mode to bring up a scroll bar, or break other commitments of its current auto-resize mode -- instead it allows its bounds to be set larger (or smaller) than the total of the column minimum or maximum, meaning, either that there will not be enough room to display all of the columns, or that the columns will not fill the JTable's bounds. These respectively, result in the clipping of some columns or an area being painted in the JTable's background color during painting.

The mechanism for distributing the delta amongst the available columns is provided in a private method in the JTable class:

   adjustSizes(long targetSize, final Resizable3 r, boolean inverse)
an explanation of which is provided in the following section. Resizable3 is a private interface that allows any data structure containing a collection of elements with a size, preferred size, maximum size and minimum size to have its elements manipulated by the algorithm.

Distributing the delta

Overview

Call "DELTA" the difference between the target size and the sum of the preferred sizes of the elements in r. The individual sizes are calculated by taking the original preferred sizes and adding a share of the DELTA - that share being based on how far each preferred size is from its limiting bound (minimum or maximum).

Definition

Call the individual constraints min[i], max[i], and pref[i].

Call their respective sums: MIN, MAX, and PREF.

Each new size will be calculated using:

          size[i] = pref[i] + delta[i]
where each individual delta[i] is calculated according to:

If (DELTA < 0) we are in shrink mode where:

                        DELTA
          delta[i] = ------------ * (pref[i] - min[i])
                     (PREF - MIN)
If (DELTA > 0) we are in expand mode where:

                        DELTA
          delta[i] = ------------ * (max[i] - pref[i])
                      (MAX - PREF)

The overall effect is that the total size moves that same percentage, k, towards the total minimum or maximum and that percentage guarantees accomodation of the required space, DELTA.

Details

Naive evaluation of the formulae presented here would be subject to the aggregated rounding errors caused by doing this operation in finite precision (using ints). To deal with this, the multiplying factor above, is constantly recalculated and this takes account of the rounding errors in the previous iterations. The result is an algorithm that produces a set of integers whose values exactly sum to the supplied targetSize, and does so by spreading the rounding errors evenly over the given elements.

When the MAX and MIN bounds are hit

When targetSize is outside the [MIN, MAX] range, the algorithm sets all sizes to their appropriate limiting value (maximum or minimum).

Overrides:
doLayout in class Container
See Also:
LayoutManager.layoutContainer(java.awt.Container),
Container.setLayout(java.awt.LayoutManager),
Container.validate()

sizeColumnsToFit

@Deprecated
public void sizeColumnsToFit(boolean lastColumnOnly)
Deprecated. As of Swing version 1.0.3, replaced by doLayout().

Sizes the table columns to fit the available space.

See Also:
doLayout()

sizeColumnsToFit

public void sizeColumnsToFit(int resizingColumn)
Obsolete as of Java 2 platform v1.4. Please use the doLayout() method instead.

Parameters:
resizingColumn - the column whose resizing made this adjustment necessary or -1 if there is no such column
See Also:
doLayout()

getToolTipText

public String getToolTipText(MouseEvent event)
Overrides JComponent's getToolTipText method in order to allow the renderer's tips to be used if it has text set.

Note: For JTable to properly display tooltips of its renderers JTable must be a registered component with the ToolTipManager. This is done automatically in initializeLocalVars, but if at a later point JTable is told setToolTipText(null) it will unregister the table component, and no tips from renderers will display anymore.

Overrides:
getToolTipText in class JComponent
See Also:
JComponent.getToolTipText()

setSurrendersFocusOnKeystroke

public void setSurrendersFocusOnKeystroke(boolean surrendersFocusOnKeystroke)
Sets whether editors in this JTable get the keyboard focus when an editor is activated as a result of the JTable forwarding keyboard events for a cell. By default, this property is false, and the JTable retains the focus unless the cell is clicked.

Parameters:
surrendersFocusOnKeystroke - true if the editor should get the focus when keystrokes cause the editor to be activated
Since:
1.4
See Also:
getSurrendersFocusOnKeystroke()

getSurrendersFocusOnKeystroke

public boolean getSurrendersFocusOnKeystroke()
Returns true if the editor should get the focus when keystrokes cause the editor to be activated

Returns:
true if the editor should get the focus when keystrokes cause the editor to be activated
Since:
1.4
See Also:
setSurrendersFocusOnKeystroke(boolean)

editCellAt

public boolean editCellAt(int row,
                          int column)
Programmatically starts editing the cell at row and column, if those indices are in the valid range, and the cell at those indices is editable. Note that this is a convenience method for editCellAt(int, int, null).

Parameters:
row - the row to be edited
column - the column to be edited
Returns:
false if for any reason the cell cannot be edited, or if the indices are invalid

editCellAt

public boolean editCellAt(int row,
                          int column,
                          EventObject e)
Programmatically starts editing the cell at row and column, if those indices are in the valid range, and the cell at those indices is editable. To prevent the JTable from editing a particular table, column or cell value, return false from the isCellEditable method in the TableModel interface.

Parameters:
row - the row to be edited
column - the column to be edited
e - event to pass into shouldSelectCell; note that as of Java 2 platform v1.2, the call to shouldSelectCell is no longer made
Returns:
false if for any reason the cell cannot be edited, or if the indices are invalid

isEditing

public boolean isEditing()
Returns true if a cell is being edited.

Returns:
true if the table is editing a cell
See Also:
editingColumn, editingRow

getEditorComponent

public Component getEditorComponent()
Returns the component that is handling the editing session. If nothing is being edited, returns null.

Returns:
Component handling editing session

getEditingColumn

public int getEditingColumn()
Returns the index of the column that contains the cell currently being edited. If nothing is being edited, returns -1.

Returns:
the index of the column that contains the cell currently being edited; returns -1 if nothing being edited
See Also:
editingRow

getEditingRow

public int getEditingRow()
Returns the index of the row that contains the cell currently being edited. If nothing is being edited, returns -1.

Returns:
the index of the row that contains the cell currently being edited; returns -1 if nothing being edited
See Also:
editingColumn

getUI

public TableUI getUI()
Returns the L&F object that renders this component.

Returns:
the TableUI object that renders this component

setUI

public void setUI(TableUI ui)
Sets the L&F object that renders this component and repaints.

Parameters:
ui - the TableUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Notification from the UIManager that the L&F has changed. Replaces the current UI object with the latest version from the UIManager.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the suffix used to construct the name of the L&F class used to render this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "TableUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

setModel

public void setModel(TableModel dataModel)
Sets the data model for this table to newModel and registers with it for listener notifications from the new data model.

Parameters:
dataModel - the new data source for this table
Throws:
IllegalArgumentException - if newModel is null
See Also:
getModel()

getModel

public TableModel getModel()
Returns the TableModel that provides the data displayed by this JTable.

Returns:
the TableModel that provides the data displayed by this JTable
See Also:
setModel(javax.swing.table.TableModel)

setColumnModel

public void setColumnModel(TableColumnModel columnModel)
Sets the column model for this table to newModel and registers for listener notifications from the new column model. Also sets the column model of the JTableHeader to columnModel.

Parameters:
columnModel - the new data source for this table
Throws:
IllegalArgumentException - if columnModel is null
See Also:
getColumnModel()

getColumnModel

public TableColumnModel getColumnModel()
Returns the TableColumnModel that contains all column information of this table.

Returns:
the object that provides the column state of the table
See Also:
setColumnModel(javax.swing.table.TableColumnModel)

setSelectionModel

public void setSelectionModel(ListSelectionModel newModel)
Sets the row selection model for this table to newModel and registers for listener notifications from the new selection model.

Parameters:
newModel - the new selection model
Throws:
IllegalArgumentException - if newModel is null
See Also:
getSelectionModel()

getSelectionModel

public ListSelectionModel getSelectionModel()
Returns the ListSelectionModel that is used to maintain row selection state.

Returns:
the object that provides row selection state, null if row selection is not allowed
See Also:
setSelectionModel(javax.swing.ListSelectionModel)

sorterChanged

public void sorterChanged(RowSorterEvent e)
RowSorterListener notification that the RowSorter has changed in some way.

Specified by:
sorterChanged in interface RowSorterListener
Parameters:
e - the RowSorterEvent describing the change
Throws:
NullPointerException - if e is null
Since:
1.6

tableChanged

public void tableChanged(TableModelEvent e)
Invoked when this table's TableModel generates a TableModelEvent. The TableModelEvent should be constructed in the coordinate system of the model; the appropriate mapping to the view coordinate system is performed by this JTable when it receives the event.

Application code will not use these methods explicitly, they are used internally by JTable.

Note that as of 1.3, this method clears the selection, if any.

Specified by:
tableChanged in interface TableModelListener

columnAdded

public void columnAdded(TableColumnModelEvent e)
Invoked when a column is added to the table column model.

Application code will not use these methods explicitly, they are used internally by JTable.

Specified by:
columnAdded in interface TableColumnModelListener
See Also:
TableColumnModelListener

columnRemoved

public void columnRemoved(TableColumnModelEvent e)
Invoked when a column is removed from the table column model.

Application code will not use these methods explicitly, they are used internally by JTable.

Specified by:
columnRemoved in interface TableColumnModelListener
See Also:
TableColumnModelListener

columnMoved

public void columnMoved(TableColumnModelEvent e)
Invoked when a column is repositioned. If a cell is being edited, then editing is stopped and the cell is redrawn.

Application code will not use these methods explicitly, they are used internally by JTable.

Specified by:
columnMoved in interface TableColumnModelListener
Parameters:
e - the event received
See Also:
TableColumnModelListener

columnMarginChanged

public void columnMarginChanged(ChangeEvent e)
Invoked when a column is moved due to a margin change. If a cell is being edited, then editing is stopped and the cell is redrawn.

Application code will not use these methods explicitly, they are used internally by JTable.

Specified by:
columnMarginChanged in interface TableColumnModelListener
Parameters:
e - the event received
See Also:
TableColumnModelListener

columnSelectionChanged

public void columnSelectionChanged(ListSelectionEvent e)
Invoked when the selection model of the TableColumnModel is changed.

Application code will not use these methods explicitly, they are used internally by JTable.

Specified by:
columnSelectionChanged in interface TableColumnModelListener
Parameters:
e - the event received
See Also:
TableColumnModelListener

valueChanged

public void valueChanged(ListSelectionEvent e)
Invoked when the row selection changes -- repaints to show the new selection.

Application code will not use these methods explicitly, they are used internally by JTable.

Specified by:
valueChanged in interface ListSelectionListener
Parameters:
e - the event received
See Also:
ListSelectionListener

editingStopped

public void editingStopped(ChangeEvent e)
Invoked when editing is finished. The changes are saved and the editor is discarded.

Application code will not use these methods explicitly, they are used internally by JTable.

Specified by:
editingStopped in interface CellEditorListener
Parameters:
e - the event received
See Also:
CellEditorListener

editingCanceled

public void editingCanceled(ChangeEvent e)
Invoked when editing is canceled. The editor object is discarded and the cell is rendered once again.

Application code will not use these methods explicitly, they are used internally by JTable.

Specified by:
editingCanceled in interface CellEditorListener
Parameters:
e - the event received
See Also:
CellEditorListener

setPreferredScrollableViewportSize

public void setPreferredScrollableViewportSize(Dimension size)
Sets the preferred size of the viewport for this table.

Parameters:
size - a Dimension object specifying the preferredSize of a JViewport whose view is this table
See Also:
Scrollable.getPreferredScrollableViewportSize()

getPreferredScrollableViewportSize

public Dimension getPreferredScrollableViewportSize()
Returns the preferred size of the viewport for this table.

Specified by:
getPreferredScrollableViewportSize in interface Scrollable
Returns:
a Dimension object containing the preferredSize of the JViewport which displays this table
See Also:
Scrollable.getPreferredScrollableViewportSize()

getScrollableUnitIncrement

public int getScrollableUnitIncrement(Rectangle visibleRect,
                                      int orientation,
                                      int direction)
Returns the scroll increment (in pixels) that completely exposes one new row or column (depending on the orientation).

This method is called each time the user requests a unit scroll.

Specified by:
getScrollableUnitIncrement in interface Scrollable
Parameters:
visibleRect - the view area visible within the viewport
orientation - either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL
direction - less than zero to scroll up/left, greater than zero for down/right
Returns:
the "unit" increment for scrolling in the specified direction
See Also:
Scrollable.getScrollableUnitIncrement(java.awt.Rectangle, int, int)

getScrollableBlockIncrement

public int getScrollableBlockIncrement(Rectangle visibleRect,
                                       int orientation,
                                       int direction)
Returns visibleRect.height or visibleRect.width, depending on this table's orientation. Note that as of Swing 1.1.1 (Java 2 v 1.2.2) the value returned will ensure that the viewport is cleanly aligned on a row boundary.

Specified by:
getScrollableBlockIncrement in interface Scrollable
Parameters:
visibleRect - The view area visible within the viewport
orientation - Either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL.
direction - Less than zero to scroll up/left, greater than zero for down/right.
Returns:
visibleRect.height or visibleRect.width per the orientation
See Also:
Scrollable.getScrollableBlockIncrement(java.awt.Rectangle, int, int)

getScrollableTracksViewportWidth

public boolean getScrollableTracksViewportWidth()
Returns false if autoResizeMode is set to AUTO_RESIZE_OFF, which indicates that the width of the viewport does not determine the width of the table. Otherwise returns true.

Specified by:
getScrollableTracksViewportWidth in interface Scrollable
Returns:
false if autoResizeMode is set to AUTO_RESIZE_OFF, otherwise returns true
See Also:
Scrollable.getScrollableTracksViewportWidth()

getScrollableTracksViewportHeight

public boolean getScrollableTracksViewportHeight()
Returns false to indicate that the height of the viewport does not determine the height of the table, unless getFillsViewportHeight is true and the preferred height of the table is smaller than the viewport's height.

Specified by:
getScrollableTracksViewportHeight in interface Scrollable
Returns:
false unless getFillsViewportHeight is true and the table needs to be stretched to fill the viewport
See Also:
Scrollable.getScrollableTracksViewportHeight(), setFillsViewportHeight(boolean), getFillsViewportHeight()

setFillsViewportHeight

public void setFillsViewportHeight(boolean fillsViewportHeight)
Sets whether or not this table is always made large enough to fill the height of an enclosing viewport. If the preferred height of the table is smaller than the viewport, then the table will be stretched to fill the viewport. In other words, this ensures the table is never smaller than the viewport. The default for this property is false.

Parameters:
fillsViewportHeight - whether or not this table is always made large enough to fill the height of an enclosing viewport
Since:
1.6
See Also:
getFillsViewportHeight(), getScrollableTracksViewportHeight()

getFillsViewportHeight

public boolean getFillsViewportHeight()
Returns whether or not this table is always made large enough to fill the height of an enclosing viewport.

Returns:
whether or not this table is always made large enough to fill the height of an enclosing viewport
Since:
1.6
See Also:
setFillsViewportHeight(boolean)

processKeyBinding

protected boolean processKeyBinding(KeyStroke ks,
                                    KeyEvent e,
                                    int condition,
                                    boolean pressed)
Description copied from class: JComponent
Invoked to process the key bindings for ks as the result of the KeyEvent e. This obtains the appropriate InputMap, gets the binding, gets the action from the ActionMap, and then (if the action is found and the component is enabled) invokes notifyAction to notify the action.

Overrides:
processKeyBinding in class JComponent
Parameters:
ks - the KeyStroke queried
e - the KeyEvent
condition - one of the following values:
  • JComponent.WHEN_FOCUSED
  • JComponent.WHEN_ANCESTOR_OF_FOCUSED_COMPONENT
  • JComponent.WHEN_IN_FOCUSED_WINDOW
pressed - true if the key is pressed
Returns:
true if there was a binding to an action, and the action was enabled

createDefaultRenderers

protected void createDefaultRenderers()
Creates default cell renderers for objects, numbers, doubles, dates, booleans, and icons.

See Also:
DefaultTableCellRenderer

createDefaultEditors

protected void createDefaultEditors()
Creates default cell editors for objects, numbers, and boolean values.

See Also:
DefaultCellEditor

initializeLocalVars

protected void initializeLocalVars()
Initializes table properties to their default values.

createDefaultDataModel

protected TableModel createDefaultDataModel()
Returns the default table model object, which is a DefaultTableModel. A subclass can override this method to return a different table model object.

Returns:
the default table model object
See Also:
DefaultTableModel

createDefaultColumnModel

protected TableColumnModel createDefaultColumnModel()
Returns the default column model object, which is a DefaultTableColumnModel. A subclass can override this method to return a different column model object.

Returns:
the default column model object
See Also:
DefaultTableColumnModel

createDefaultSelectionModel

protected ListSelectionModel createDefaultSelectionModel()
Returns the default selection model object, which is a DefaultListSelectionModel. A subclass can override this method to return a different selection model object.

Returns:
the default selection model object
See Also:
DefaultListSelectionModel

createDefaultTableHeader

protected JTableHeader createDefaultTableHeader()
Returns the default table header object, which is a JTableHeader. A subclass can override this method to return a different table header object.

Returns:
the default table header object
See Also:
JTableHeader

resizeAndRepaint

protected void resizeAndRepaint()
Equivalent to revalidate followed by repaint.

getCellEditor

public TableCellEditor getCellEditor()
Returns the active cell editor, which is null if the table is not currently editing.

Returns:
the TableCellEditor that does the editing, or null if the table is not currently editing.
See Also:
cellEditor, getCellEditor(int, int)

setCellEditor

public void setCellEditor(TableCellEditor anEditor)
Sets the active cell editor.

Parameters:
anEditor - the active cell editor
See Also:
cellEditor

setEditingColumn

public void setEditingColumn(int aColumn)
Sets the editingColumn variable.

Parameters:
aColumn - the column of the cell to be edited
See Also:
editingColumn

setEditingRow

public void setEditingRow(int aRow)
Sets the editingRow variable.

Parameters:
aRow - the row of the cell to be edited
See Also:
editingRow

getCellRenderer

public TableCellRenderer getCellRenderer(int row,
                                         int column)
Returns an appropriate renderer for the cell specified by this row and column. If the TableColumn for this column has a non-null renderer, returns that. If not, finds the class of the data in this column (using getColumnClass) and returns the default renderer for this type of data.

Note: Throughout the table package, the internal implementations always use this method to provide renderers so that this default behavior can be safely overridden by a subclass.

Parameters:
row - the row of the cell to render, where 0 is the first row
column - the column of the cell to render, where 0 is the first column
Returns:
the assigned renderer; if null returns the default renderer for this type of object
See Also:
DefaultTableCellRenderer, TableColumn.setCellRenderer(javax.swing.table.TableCellRenderer), setDefaultRenderer(java.lang.Class, javax.swing.table.TableCellRenderer)

prepareRenderer

public Component prepareRenderer(TableCellRenderer renderer,
                                 int row,
                                 int column)
Prepares the renderer by querying the data model for the value and selection state of the cell at row, column. Returns the component (may be a Component or a JComponent) under the event location.

During a printing operation, this method will configure the renderer without indicating selection or focus, to prevent them from appearing in the printed output. To do other customizations based on whether or not the table is being printed, you can check the value of JComponent.isPaintingForPrint(), either here or within custom renderers.

Note: Throughout the table package, the internal implementations always use this method to prepare renderers so that this default behavior can be safely overridden by a subclass.

Parameters:
renderer - the TableCellRenderer to prepare
row - the row of the cell to render, where 0 is the first row
column - the column of the cell to render, where 0 is the first column
Returns:
the Component under the event location

getCellEditor

public TableCellEditor getCellEditor(int row,
                                     int column)
Returns an appropriate editor for the cell specified by row and column. If the TableColumn for this column has a non-null editor, returns that. If not, finds the class of the data in this column (using getColumnClass) and returns the default editor for this type of data.

Note: Throughout the table package, the internal implementations always use this method to provide editors so that this default behavior can be safely overridden by a subclass.

Parameters:
row - the row of the cell to edit, where 0 is the first row
column - the column of the cell to edit, where 0 is the first column
Returns:
the editor for this cell; if null return the default editor for this type of cell
See Also:
DefaultCellEditor

prepareEditor

public Component prepareEditor(TableCellEditor editor,
                               int row,
                               int column)
Prepares the editor by querying the data model for the value and selection state of the cell at row, column.

Note: Throughout the table package, the internal implementations always use this method to prepare editors so that this default behavior can be safely overridden by a subclass.

Parameters:
editor - the TableCellEditor to set up
row - the row of the cell to edit, where 0 is the first row
column - the column of the cell to edit, where 0 is the first column
Returns:
the Component being edited

removeEditor

public void removeEditor()
Discards the editor object and frees the real estate it used for cell rendering.

paramString

protected String paramString()
Returns a string representation of this table. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this table

print

public boolean print()
              throws PrinterException
A convenience method that displays a printing dialog, and then prints this JTable in mode PrintMode.FIT_WIDTH, with no header or footer text. A modal progress dialog, with an abort option, will be shown for the duration of printing.

Note: In headless mode, no dialogs are shown and printing occurs on the default printer.

Returns:
true, unless printing is cancelled by the user
Throws:
SecurityException - if this thread is not allowed to initiate a print job request
PrinterException - if an error in the print system causes the job to be aborted
Since:
1.5
See Also:
print(JTable.PrintMode, MessageFormat, MessageFormat, boolean, PrintRequestAttributeSet, boolean, PrintService), getPrintable(javax.swing.JTable.PrintMode, java.text.MessageFormat, java.text.MessageFormat)

print

public boolean print(JTable.PrintMode printMode)
              throws PrinterException
A convenience method that displays a printing dialog, and then prints this JTable in the given printing mode, with no header or footer text. A modal progress dialog, with an abort option, will be shown for the duration of printing.

Note: In headless mode, no dialogs are shown and printing occurs on the default printer.

Parameters:
printMode - the printing mode that the printable should use
Returns:
true, unless printing is cancelled by the user
Throws:
SecurityException - if this thread is not allowed to initiate a print job request
PrinterException - if an error in the print system causes the job to be aborted
Since:
1.5
See Also:
print(JTable.PrintMode, MessageFormat, MessageFormat, boolean, PrintRequestAttributeSet, boolean, PrintService), getPrintable(javax.swing.JTable.PrintMode, java.text.MessageFormat, java.text.MessageFormat)

print

public boolean print(JTable.PrintMode printMode,
                     MessageFormat headerFormat,
                     MessageFormat footerFormat)
              throws PrinterException
A convenience method that displays a printing dialog, and then prints this JTable in the given printing mode, with the specified header and footer text. A modal progress dialog, with an abort option, will be shown for the duration of printing.

Note: In headless mode, no dialogs are shown and printing occurs on the default printer.

Parameters:
printMode - the printing mode that the printable should use
headerFormat - a MessageFormat specifying the text to be used in printing a header, or null for none
footerFormat - a MessageFormat specifying the text to be used in printing a footer, or null for none
Returns:
true, unless printing is cancelled by the user
Throws:
SecurityException - if this thread is not allowed to initiate a print job request
PrinterException - if an error in the print system causes the job to be aborted
Since:
1.5
See Also:
print(JTable.PrintMode, MessageFormat, MessageFormat, boolean, PrintRequestAttributeSet, boolean, PrintService), getPrintable(javax.swing.JTable.PrintMode, java.text.MessageFormat, java.text.MessageFormat)

print

public boolean print(JTable.PrintMode printMode,
                     MessageFormat headerFormat,
                     MessageFormat footerFormat,
                     boolean showPrintDialog,
                     PrintRequestAttributeSet attr,
                     boolean interactive)
              throws PrinterException,
                     HeadlessException
Prints this table, as specified by the fully featured print method, with the default printer specified as the print service.

Parameters:
printMode - the printing mode that the printable should use
headerFormat - a MessageFormat specifying the text to be used in printing a header, or null for none
footerFormat - a MessageFormat specifying the text to be used in printing a footer, or null for none
showPrintDialog - whether or not to display a print dialog
attr - a PrintRequestAttributeSet specifying any printing attributes, or null for none
interactive - whether or not to print in an interactive mode
Returns:
true, unless printing is cancelled by the user
Throws:
HeadlessException - if the method is asked to show a printing dialog or run interactively, and GraphicsEnvironment.isHeadless returns true
SecurityException - if this thread is not allowed to initiate a print job request
PrinterException - if an error in the print system causes the job to be aborted
Since:
1.5
See Also:
print(JTable.PrintMode, MessageFormat, MessageFormat, boolean, PrintRequestAttributeSet, boolean, PrintService), getPrintable(javax.swing.JTable.PrintMode, java.text.MessageFormat, java.text.MessageFormat)

print

public boolean print(JTable.PrintMode printMode,
                     MessageFormat headerFormat,
                     MessageFormat footerFormat,
                     boolean showPrintDialog,
                     PrintRequestAttributeSet attr,
                     boolean interactive,
                     PrintService service)
              throws PrinterException,
                     HeadlessException
Prints this JTable. Takes steps that the majority of developers would take in order to print a JTable. In short, it prepares the table, calls getPrintable to fetch an appropriate Printable, and then sends it to the printer.

A boolean parameter allows you to specify whether or not a printing dialog is displayed to the user. When it is, the user may use the dialog to change the destination printer or printing attributes, or even to cancel the print. Another two parameters allow for a PrintService and printing attributes to be specified. These parameters can be used either to provide initial values for the print dialog, or to specify values when the dialog is not shown.

A second boolean parameter allows you to specify whether or not to perform printing in an interactive mode. If true, a modal progress dialog, with an abort option, is displayed for the duration of printing . This dialog also prevents any user action which may affect the table. However, it can not prevent the table from being modified by code (for example, another thread that posts updates using SwingUtilities.invokeLater). It is therefore the responsibility of the developer to ensure that no other code modifies the table in any way during printing (invalid modifications include changes in: size, renderers, or underlying data). Printing behavior is undefined when the table is changed during printing.

If false is specified for this parameter, no dialog will be displayed and printing will begin immediately on the event-dispatch thread. This blocks any other events, including repaints, from being processed until printing is complete. Although this effectively prevents the table from being changed, it doesn't provide a good user experience. For this reason, specifying false is only recommended when printing from an application with no visible GUI.

Note: Attempting to show the printing dialog or run interactively, while in headless mode, will result in a HeadlessException.

Before fetching the printable, this method will gracefully terminate editing, if necessary, to prevent an editor from showing in the printed result. Additionally, JTable will prepare its renderers during printing such that selection and focus are not indicated. As far as customizing further how the table looks in the printout, developers can provide custom renderers or paint code that conditionalize on the value of JComponent.isPaintingForPrint().

See getPrintable(javax.swing.JTable.PrintMode, java.text.MessageFormat, java.text.MessageFormat) for more description on how the table is printed.

Parameters:
printMode - the printing mode that the printable should use
headerFormat - a MessageFormat specifying the text to be used in printing a header, or null for none
footerFormat - a MessageFormat specifying the text to be used in printing a footer, or null for none
showPrintDialog - whether or not to display a print dialog
attr - a PrintRequestAttributeSet specifying any printing attributes, or null for none
interactive - whether or not to print in an interactive mode
service - the destination PrintService, or null to use the default printer
Returns:
true, unless printing is cancelled by the user
Throws:
HeadlessException - if the method is asked to show a printing dialog or run interactively, and GraphicsEnvironment.isHeadless returns true
SecurityException - if a security manager exists and its SecurityManager.checkPrintJobAccess() method disallows this thread from creating a print job request
PrinterException - if an error in the print system causes the job to be aborted
Since:
1.6
See Also:
getPrintable(javax.swing.JTable.PrintMode, java.text.MessageFormat, java.text.MessageFormat), GraphicsEnvironment.isHeadless()

getPrintable

public Printable getPrintable(JTable.PrintMode printMode,
                              MessageFormat headerFormat,
                              MessageFormat footerFormat)
Return a Printable for use in printing this JTable.

This method is meant for those wishing to customize the default Printable implementation used by JTable's print methods. Developers wanting simply to print the table should use one of those methods directly.

The Printable can be requested in one of two printing modes. In both modes, it spreads table rows naturally in sequence across multiple pages, fitting as many rows as possible per page. PrintMode.NORMAL specifies that the table be printed at its current size. In this mode, there may be a need to spread columns across pages in a similar manner to that of the rows. When the need arises, columns are distributed in an order consistent with the table's ComponentOrientation. PrintMode.FIT_WIDTH specifies that the output be scaled smaller, if necessary, to fit the table's entire width (and thereby all columns) on each page. Width and height are scaled equally, maintaining the aspect ratio of the output.

The Printable heads the portion of table on each page with the appropriate section from the table's JTableHeader, if it has one.

Header and footer text can be added to the output by providing MessageFormat arguments. The printing code requests Strings from the formats, providing a single item which may be included in the formatted string: an Integer representing the current page number.

You are encouraged to read the documentation for MessageFormat as some characters, such as single-quote, are special and need to be escaped.

Here's an example of creating a MessageFormat that can be used to print "Duke's Table: Page - " and the current page number:

     // notice the escaping of the single quote
     // notice how the page number is included with "{0}"
     MessageFormat format = new MessageFormat("Duke''s Table: Page - {0}");

The Printable constrains what it draws to the printable area of each page that it prints. Under certain circumstances, it may find it impossible to fit all of a page's content into that area. In these cases the output may be clipped, but the implementation makes an effort to do something reasonable. Here are a few situations where this is known to occur, and how they may be handled by this particular implementation:

  • In any mode, when the header or footer text is too wide to fit completely in the printable area -- print as much of the text as possible starting from the beginning, as determined by the table's ComponentOrientation.
  • In any mode, when a row is too tall to fit in the printable area -- print the upper-most portion of the row and paint no lower border on the table.
  • In PrintMode.NORMAL when a column is too wide to fit in the printable area -- print the center portion of the column and leave the left and right borders off the table.

It is entirely valid for this Printable to be wrapped inside another in order to create complex reports and documents. You may even request that different pages be rendered into different sized printable areas. The implementation must be prepared to handle this (possibly by doing its layout calculations on the fly). However, providing different heights to each page will likely not work well with PrintMode.NORMAL when it has to spread columns across pages.

As far as customizing how the table looks in the printed result, JTable itself will take care of hiding the selection and focus during printing. For additional customizations, your renderers or painting code can customize the look based on the value of JComponent.isPaintingForPrint()

Also, before calling this method you may wish to first modify the state of the table, such as to cancel cell editing or have the user size the table appropriately. However, you must not modify the state of the table after this Printable has been fetched (invalid modifications include changes in size or underlying data). The behavior of the returned Printable is undefined once the table has been changed.

Parameters:
printMode - the printing mode that the printable should use
headerFormat - a MessageFormat specifying the text to be used in printing a header, or null for none
footerFormat - a MessageFormat specifying the text to be used in printing a footer, or null for none
Returns:
a Printable for printing this JTable
Since:
1.5
See Also:
print(JTable.PrintMode, MessageFormat, MessageFormat, boolean, PrintRequestAttributeSet, boolean), Printable, PrinterJob

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JTable. For tables, the AccessibleContext takes the form of an AccessibleJTable. A new AccessibleJTable instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJTable that serves as the AccessibleContext of this JTable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTable.AccessibleJTable

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTable.AccessibleJTable

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JTable.AccessibleJTable
All Implemented Interfaces:
PropertyChangeListener, Serializable, EventListener, AccessibleComponent, AccessibleExtendedComponent, AccessibleExtendedTable, AccessibleSelection, AccessibleTable, CellEditorListener, ListSelectionListener, TableColumnModelListener, TableModelListener
Enclosing class:
JTable
protected class JTable.AccessibleJTable
extends JComponent.AccessibleJComponent
implements AccessibleSelection, ListSelectionListener, TableModelListener, TableColumnModelListener, CellEditorListener, PropertyChangeListener, AccessibleExtendedTable

This class implements accessibility support for the JTable class. It provides an implementation of the Java Accessibility API appropriate to table user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected class | JTable.AccessibleJTable.AccessibleJTableCell The class provides an implementation of the Java Accessibility API appropriate to table cells.
protected class | JTable.AccessibleJTable.AccessibleJTableModelChange
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JTable.AccessibleJTable()
AccessibleJTable constructor
Method Summary
void | addAccessibleSelection(int i) Adds the specified Accessible child of the object to the object's selection.
void | clearAccessibleSelection() Clears the selection in the object, so that no children in the object are selected.
void | columnAdded(TableColumnModelEvent e) Track changes to the table contents (column insertions)
void | columnMarginChanged(ChangeEvent e) Track changes of a column moving due to margin changes.
void | columnMoved(TableColumnModelEvent e) Track changes of a column repositioning.
void | columnRemoved(TableColumnModelEvent e) Track changes to the table contents (column deletions)
void | columnSelectionChanged(ListSelectionEvent e) Track that the selection model of the TableColumnModel changed.
void | editingCanceled(ChangeEvent e) Invoked when editing is canceled.
void | editingStopped(ChangeEvent e) Track changes to a cell's contents.
Accessible | getAccessibleAt(int r, int c) Returns the Accessible at a specified row and column in the table.
Accessible | getAccessibleAt(Point p) Returns the Accessible child, if one exists, contained at the local coordinate Point.
Accessible | getAccessibleCaption() Returns the caption for the table.
Accessible | getAccessibleChild(int i) Returns the nth Accessible child of the object.
int | getAccessibleChildrenCount() Returns the number of accessible children in the object.
int | getAccessibleColumn(int index) Returns the column number of an index in the table.
int | getAccessibleColumnAtIndex(int i) Returns the column at a given index into the table.
int | getAccessibleColumnCount() Returns the number of columns in the table.
Accessible | getAccessibleColumnDescription(int c) Returns the description of the specified column in the table.
int | getAccessibleColumnExtentAt(int r, int c) Returns the number of columns occupied by the Accessible at a given (row, column).
AccessibleTable | getAccessibleColumnHeader() Returns the column headers as an AccessibleTable.
int | getAccessibleIndex(int r, int c) Returns the index at a row and column in the table.
int | getAccessibleIndexAt(int r, int c) Returns the index at a given (row, column) in the table.
AccessibleRole | getAccessibleRole() Gets the role of this object.
int | getAccessibleRow(int index) Returns the row number of an index in the table.
int | getAccessibleRowAtIndex(int i) Returns the row at a given index into the table.
int | getAccessibleRowCount() Returns the number of rows in the table.
Accessible | getAccessibleRowDescription(int r) Returns the description of the specified row in the table.
int | getAccessibleRowExtentAt(int r, int c) Returns the number of rows occupied by the Accessible at a specified row and column in the table.
AccessibleTable | getAccessibleRowHeader() Returns the row headers as an AccessibleTable.
AccessibleSelection | getAccessibleSelection() Get the AccessibleSelection associated with this object.
Accessible | getAccessibleSelection(int i) Returns an Accessible representing the specified selected child in the object.
int | getAccessibleSelectionCount() Returns the number of Accessible children currently selected.
Accessible | getAccessibleSummary() Returns the summary description of the table.
AccessibleTable | getAccessibleTable() Gets the AccessibleTable associated with this object.
int[] | getSelectedAccessibleColumns() Returns the selected columns in a table.
int[] | getSelectedAccessibleRows() Returns the selected rows in a table.
boolean | isAccessibleChildSelected(int i) Determines if the current child of this object is selected.
boolean | isAccessibleColumnSelected(int c) Returns a boolean value indicating whether the specified column is selected.
boolean | isAccessibleRowSelected(int r) Returns a boolean value indicating whether the specified row is selected.
boolean | isAccessibleSelected(int r, int c) Returns a boolean value indicating whether the accessible at a given (row, column) is selected.
void | propertyChange(PropertyChangeEvent e) Track changes to selection model, column model, etc.
void | removeAccessibleSelection(int i) Removes the specified child of the object from the object's selection.
void | selectAllAccessibleSelection() Causes every child of the object to be selected, but only if the JTable supports multiple selections, and if individual cell selection is enabled.
void | setAccessibleCaption(Accessible a) Sets the caption for the table.
void | setAccessibleColumnDescription(int c, Accessible a) Sets the description text of the specified column of the table.
void | setAccessibleColumnHeader(AccessibleTable a) Sets the column headers as an AccessibleTable.
void | setAccessibleRowDescription(int r, Accessible a) Sets the description text of the specified row of the table.
void | setAccessibleRowHeader(AccessibleTable a) Sets the row headers as an AccessibleTable.
void | setAccessibleSummary(Accessible a) Sets the summary description of the table.
void | tableChanged(TableModelEvent e) Track changes to the table contents
void | tableRowsDeleted(TableModelEvent e) Track changes to the table contents (row deletions)
void | tableRowsInserted(TableModelEvent e) Track changes to the table contents (row insertions)
void | valueChanged(ListSelectionEvent e) Track changes to table cell selections
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JTable.AccessibleJTable

protected JTable.AccessibleJTable()
AccessibleJTable constructor

Since:
1.5
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
Track changes to selection model, column model, etc. so as to be able to re-place listeners on those in order to pass on information to the Accessibility PropertyChange mechanism

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.

tableChanged

public void tableChanged(TableModelEvent e)
Track changes to the table contents

Specified by:
tableChanged in interface TableModelListener

tableRowsInserted

public void tableRowsInserted(TableModelEvent e)
Track changes to the table contents (row insertions)

tableRowsDeleted

public void tableRowsDeleted(TableModelEvent e)
Track changes to the table contents (row deletions)

columnAdded

public void columnAdded(TableColumnModelEvent e)
Track changes to the table contents (column insertions)

Specified by:
columnAdded in interface TableColumnModelListener

columnRemoved

public void columnRemoved(TableColumnModelEvent e)
Track changes to the table contents (column deletions)

Specified by:
columnRemoved in interface TableColumnModelListener

columnMoved

public void columnMoved(TableColumnModelEvent e)
Track changes of a column repositioning.

Specified by:
columnMoved in interface TableColumnModelListener
See Also:
TableColumnModelListener

columnMarginChanged

public void columnMarginChanged(ChangeEvent e)
Track changes of a column moving due to margin changes.

Specified by:
columnMarginChanged in interface TableColumnModelListener
See Also:
TableColumnModelListener

columnSelectionChanged

public void columnSelectionChanged(ListSelectionEvent e)
Track that the selection model of the TableColumnModel changed.

Specified by:
columnSelectionChanged in interface TableColumnModelListener
See Also:
TableColumnModelListener

editingStopped

public void editingStopped(ChangeEvent e)
Track changes to a cell's contents. Invoked when editing is finished. The changes are saved, the editor object is discarded, and the cell is rendered once again.

Specified by:
editingStopped in interface CellEditorListener
See Also:
CellEditorListener

editingCanceled

public void editingCanceled(ChangeEvent e)
Invoked when editing is canceled. The editor object is discarded and the cell is rendered once again.

Specified by:
editingCanceled in interface CellEditorListener
See Also:
CellEditorListener

valueChanged

public void valueChanged(ListSelectionEvent e)
Track changes to table cell selections

Specified by:
valueChanged in interface ListSelectionListener
Parameters:
e - the event that characterizes the change.

getAccessibleSelection

public AccessibleSelection getAccessibleSelection()
Get the AccessibleSelection associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleSelection interface on behalf of itself.

Overrides:
getAccessibleSelection in class AccessibleContext
Returns:
this object
See Also:
AccessibleSelection

getAccessibleRole

public AccessibleRole getAccessibleRole()
Gets the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleAt

public Accessible getAccessibleAt(Point p)
Returns the Accessible child, if one exists, contained at the local coordinate Point.

Specified by:
getAccessibleAt in interface AccessibleComponent
Overrides:
getAccessibleAt in class Container.AccessibleAWTContainer
Parameters:
p - the point defining the top-left corner of the Accessible, given in the coordinate space of the object's parent
Returns:
the Accessible, if it exists, at the specified location; else null

getAccessibleChildrenCount

public int getAccessibleChildrenCount()
Returns the number of accessible children in the object. If all of the children of this object implement Accessible, then this method should return the number of children of this object.

Overrides:
getAccessibleChildrenCount in class JComponent.AccessibleJComponent
Returns:
the number of accessible children in the object

getAccessibleChild

public Accessible getAccessibleChild(int i)
Returns the nth Accessible child of the object.

Overrides:
getAccessibleChild in class JComponent.AccessibleJComponent
Parameters:
i - zero-based index of child
Returns:
the nth Accessible child of the object
See Also:
AccessibleContext.getAccessibleChildrenCount()

getAccessibleSelectionCount

public int getAccessibleSelectionCount()
Returns the number of Accessible children currently selected. If no children are selected, the return value will be 0.

Specified by:
getAccessibleSelectionCount in interface AccessibleSelection
Returns:
the number of items currently selected

getAccessibleSelection

public Accessible getAccessibleSelection(int i)
Returns an Accessible representing the specified selected child in the object. If there isn't a selection, or there are fewer children selected than the integer passed in, the return value will be null.

Note that the index represents the i-th selected child, which is different from the i-th child.

Specified by:
getAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of selected children
Returns:
the i-th selected child
See Also:
getAccessibleSelectionCount()

isAccessibleChildSelected

public boolean isAccessibleChildSelected(int i)
Determines if the current child of this object is selected.

Specified by:
isAccessibleChildSelected in interface AccessibleSelection
Parameters:
i - the zero-based index of the child in this Accessible object
Returns:
true if the current child of this object is selected
See Also:
AccessibleContext.getAccessibleChild(int)

addAccessibleSelection

public void addAccessibleSelection(int i)
Adds the specified Accessible child of the object to the object's selection. If the object supports multiple selections, the specified child is added to any existing selection, otherwise it replaces any existing selection in the object. If the specified child is already selected, this method has no effect.

This method only works on JTables which have individual cell selection enabled.

Specified by:
addAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of the child
See Also:
AccessibleContext.getAccessibleChild(int)

removeAccessibleSelection

public void removeAccessibleSelection(int i)
Removes the specified child of the object from the object's selection. If the specified item isn't currently selected, this method has no effect.

This method only works on JTables which have individual cell selection enabled.

Specified by:
removeAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of the child
See Also:
AccessibleContext.getAccessibleChild(int)

clearAccessibleSelection

public void clearAccessibleSelection()
Clears the selection in the object, so that no children in the object are selected.

Specified by:
clearAccessibleSelection in interface AccessibleSelection

selectAllAccessibleSelection

public void selectAllAccessibleSelection()
Causes every child of the object to be selected, but only if the JTable supports multiple selections, and if individual cell selection is enabled.

Specified by:
selectAllAccessibleSelection in interface AccessibleSelection

getAccessibleRow

public int getAccessibleRow(int index)
Returns the row number of an index in the table.

Specified by:
getAccessibleRow in interface AccessibleExtendedTable
Parameters:
index - the zero-based index in the table
Returns:
the zero-based row of the table if one exists; otherwise -1.
Since:
1.4

getAccessibleColumn

public int getAccessibleColumn(int index)
Returns the column number of an index in the table.

Specified by:
getAccessibleColumn in interface AccessibleExtendedTable
Parameters:
index - the zero-based index in the table
Returns:
the zero-based column of the table if one exists; otherwise -1.
Since:
1.4

getAccessibleIndex

public int getAccessibleIndex(int r,
                              int c)
Returns the index at a row and column in the table.

Specified by:
getAccessibleIndex in interface AccessibleExtendedTable
Parameters:
r - zero-based row of the table
c - zero-based column of the table
Returns:
the zero-based index in the table if one exists; otherwise -1.
Since:
1.4

getAccessibleTable

public AccessibleTable getAccessibleTable()
Gets the AccessibleTable associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleTables interface on behalf of itself.

Overrides:
getAccessibleTable in class AccessibleContext
Returns:
this object
Since:
1.3
See Also:
AccessibleTable

getAccessibleCaption

public Accessible getAccessibleCaption()
Returns the caption for the table.

Specified by:
getAccessibleCaption in interface AccessibleTable
Returns:
the caption for the table
Since:
1.3

setAccessibleCaption

public void setAccessibleCaption(Accessible a)
Sets the caption for the table.

Specified by:
setAccessibleCaption in interface AccessibleTable
Parameters:
a - the caption for the table
Since:
1.3

getAccessibleSummary

public Accessible getAccessibleSummary()
Returns the summary description of the table.

Specified by:
getAccessibleSummary in interface AccessibleTable
Returns:
the summary description of the table
Since:
1.3

setAccessibleSummary

public void setAccessibleSummary(Accessible a)
Sets the summary description of the table.

Specified by:
setAccessibleSummary in interface AccessibleTable
Parameters:
a - the summary description of the table
Since:
1.3

getAccessibleRowCount

public int getAccessibleRowCount()
Description copied from interface: AccessibleTable
Returns the number of rows in the table.

Specified by:
getAccessibleRowCount in interface AccessibleTable
Returns:
the number of rows in the table

getAccessibleColumnCount

public int getAccessibleColumnCount()
Description copied from interface: AccessibleTable
Returns the number of columns in the table.

Specified by:
getAccessibleColumnCount in interface AccessibleTable
Returns:
the number of columns in the table

getAccessibleAt

public Accessible getAccessibleAt(int r,
                                  int c)
Description copied from interface: AccessibleTable
Returns the Accessible at a specified row and column in the table.

Specified by:
getAccessibleAt in interface AccessibleTable
Parameters:
r - zero-based row of the table
c - zero-based column of the table
Returns:
the Accessible at the specified row and column

getAccessibleRowExtentAt

public int getAccessibleRowExtentAt(int r,
                                    int c)
Returns the number of rows occupied by the Accessible at a specified row and column in the table.

Specified by:
getAccessibleRowExtentAt in interface AccessibleTable
Returns:
the number of rows occupied by the Accessible at a specified row and column in the table
Since:
1.3

getAccessibleColumnExtentAt

public int getAccessibleColumnExtentAt(int r,
                                       int c)
Returns the number of columns occupied by the Accessible at a given (row, column).

Specified by:
getAccessibleColumnExtentAt in interface AccessibleTable
Returns:
the number of columns occupied by the Accessible at a specified row and column in the table
Since:
1.3

getAccessibleRowHeader

public AccessibleTable getAccessibleRowHeader()
Returns the row headers as an AccessibleTable.

Specified by:
getAccessibleRowHeader in interface AccessibleTable
Returns:
an AccessibleTable representing the row headers
Since:
1.3

setAccessibleRowHeader

public void setAccessibleRowHeader(AccessibleTable a)
Sets the row headers as an AccessibleTable.

Specified by:
setAccessibleRowHeader in interface AccessibleTable
Parameters:
a - an AccessibleTable representing the row headers
Since:
1.3

getAccessibleColumnHeader

public AccessibleTable getAccessibleColumnHeader()
Returns the column headers as an AccessibleTable.

Specified by:
getAccessibleColumnHeader in interface AccessibleTable
Returns:
an AccessibleTable representing the column headers, or null if the table header is null
Since:
1.3

setAccessibleColumnHeader

public void setAccessibleColumnHeader(AccessibleTable a)
Sets the column headers as an AccessibleTable.

Specified by:
setAccessibleColumnHeader in interface AccessibleTable
Parameters:
a - an AccessibleTable representing the column headers
Since:
1.3

getAccessibleRowDescription

public Accessible getAccessibleRowDescription(int r)
Returns the description of the specified row in the table.

Specified by:
getAccessibleRowDescription in interface AccessibleTable
Parameters:
r - zero-based row of the table
Returns:
the description of the row
Since:
1.3

setAccessibleRowDescription

public void setAccessibleRowDescription(int r,
                                        Accessible a)
Sets the description text of the specified row of the table.

Specified by:
setAccessibleRowDescription in interface AccessibleTable
Parameters:
r - zero-based row of the table
a - the description of the row
Since:
1.3

getAccessibleColumnDescription

public Accessible getAccessibleColumnDescription(int c)
Returns the description of the specified column in the table.

Specified by:
getAccessibleColumnDescription in interface AccessibleTable
Parameters:
c - zero-based column of the table
Returns:
the description of the column
Since:
1.3

setAccessibleColumnDescription

public void setAccessibleColumnDescription(int c,
                                           Accessible a)
Sets the description text of the specified column of the table.

Specified by:
setAccessibleColumnDescription in interface AccessibleTable
Parameters:
c - zero-based column of the table
a - the description of the column
Since:
1.3

isAccessibleSelected

public boolean isAccessibleSelected(int r,
                                    int c)
Returns a boolean value indicating whether the accessible at a given (row, column) is selected.

Specified by:
isAccessibleSelected in interface AccessibleTable
Parameters:
r - zero-based row of the table
c - zero-based column of the table
Returns:
the boolean value true if the accessible at (row, column) is selected; otherwise, the boolean value false
Since:
1.3

isAccessibleRowSelected

public boolean isAccessibleRowSelected(int r)
Returns a boolean value indicating whether the specified row is selected.

Specified by:
isAccessibleRowSelected in interface AccessibleTable
Parameters:
r - zero-based row of the table
Returns:
the boolean value true if the specified row is selected; otherwise, false
Since:
1.3

isAccessibleColumnSelected

public boolean isAccessibleColumnSelected(int c)
Returns a boolean value indicating whether the specified column is selected.

Specified by:
isAccessibleColumnSelected in interface AccessibleTable
Parameters:
c - zero-based column of the table
Returns:
the boolean value true if the specified column is selected; otherwise, false
Since:
1.3

getSelectedAccessibleRows

public int[] getSelectedAccessibleRows()
Returns the selected rows in a table.

Specified by:
getSelectedAccessibleRows in interface AccessibleTable
Returns:
an array of selected rows where each element is a zero-based row of the table
Since:
1.3

getSelectedAccessibleColumns

public int[] getSelectedAccessibleColumns()
Returns the selected columns in a table.

Specified by:
getSelectedAccessibleColumns in interface AccessibleTable
Returns:
an array of selected columns where each element is a zero-based column of the table
Since:
1.3

getAccessibleRowAtIndex

public int getAccessibleRowAtIndex(int i)
Returns the row at a given index into the table.

Parameters:
i - zero-based index into the table
Returns:
the row at a given index
Since:
1.3

getAccessibleColumnAtIndex

public int getAccessibleColumnAtIndex(int i)
Returns the column at a given index into the table.

Parameters:
i - zero-based index into the table
Returns:
the column at a given index
Since:
1.3

getAccessibleIndexAt

public int getAccessibleIndexAt(int r,
                                int c)
Returns the index at a given (row, column) in the table.

Parameters:
r - zero-based row of the table
c - zero-based column of the table
Returns:
the index into the table
Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTable.AccessibleJTable.AccessibleJTableCell

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTable.AccessibleJTable.AccessibleJTableCell

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  javax.swing.JTable.AccessibleJTable.AccessibleJTableCell
All Implemented Interfaces:
Accessible, AccessibleComponent
Enclosing class:
JTable.AccessibleJTable
protected class JTable.AccessibleJTable.AccessibleJTableCell
extends AccessibleContext
implements Accessible, AccessibleComponent

The class provides an implementation of the Java Accessibility API appropriate to table cells.

Field Summary
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
JTable.AccessibleJTable.AccessibleJTableCell(JTable t, int r, int c, int i)
Constructs an AccessibleJTableHeaderEntry.
Method Summary
void | addFocusListener(FocusListener l) Adds the specified focus listener to receive focus events from this component.
void | addPropertyChangeListener(PropertyChangeListener l) Adds a PropertyChangeListener to the listener list.
boolean | contains(Point p) Checks whether the specified point is within this object's bounds, where the point's x and y coordinates are defined to be relative to the coordinate system of the object.
AccessibleAction | getAccessibleAction() Gets the AccessibleAction associated with this object if one exists.
Accessible | getAccessibleAt(Point p) Returns the Accessible child, if one exists, contained at the local coordinate Point.
Accessible | getAccessibleChild(int i) Returns the specified Accessible child of the object.
int | getAccessibleChildrenCount() Returns the number of accessible children in the object.
AccessibleComponent | getAccessibleComponent() Gets the AccessibleComponent associated with this object if one exists.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this component.
String | getAccessibleDescription() Gets the accessible description of this object.
int | getAccessibleIndexInParent() Gets the index of this object in its accessible parent.
String | getAccessibleName() Gets the accessible name of this object.
Accessible | getAccessibleParent() Gets the Accessible parent of this object.
AccessibleRole | getAccessibleRole() Gets the role of this object.
AccessibleSelection | getAccessibleSelection() Gets the AccessibleSelection associated with this object if one exists.
AccessibleStateSet | getAccessibleStateSet() Gets the state set of this object.
AccessibleText | getAccessibleText() Gets the AccessibleText associated with this object if one exists.
AccessibleValue | getAccessibleValue() Gets the AccessibleValue associated with this object if one exists.
Color | getBackground() Gets the background color of this object.
Rectangle | getBounds() Gets the bounds of this object in the form of a Rectangle object.
protected AccessibleContext | getCurrentAccessibleContext() Gets the AccessibleContext for the table cell renderer.
protected Component | getCurrentComponent() Gets the table cell renderer component.
Cursor | getCursor() Gets the Cursor of this object.
Font | getFont() Gets the Font of this object.
FontMetrics | getFontMetrics(Font f) Gets the FontMetrics of this object.
Color | getForeground() Gets the foreground color of this object.
Locale | getLocale() Gets the locale of the component.
Point | getLocation() Gets the location of the object relative to the parent in the form of a point specifying the object's top-left corner in the screen's coordinate space.
Point | getLocationOnScreen() Returns the location of the object on the screen.
Dimension | getSize() Returns the size of this object in the form of a Dimension object.
boolean | isEnabled() Determines if the object is enabled.
boolean | isFocusTraversable() Returns whether this object can accept focus or not.
boolean | isShowing() Determines if the object is showing.
boolean | isVisible() Determines if this object is visible.
void | removeFocusListener(FocusListener l) Removes the specified focus listener so it no longer receives focus events from this component.
void | removePropertyChangeListener(PropertyChangeListener l) Removes a PropertyChangeListener from the listener list.
void | requestFocus() Requests focus for this object.
void | setAccessibleDescription(String s) Sets the accessible description of this object.
void | setAccessibleName(String s) Sets the localized accessible name of this object.
void | setBackground(Color c) Sets the background color of this object.
void | setBounds(Rectangle r) Sets the bounds of this object in the form of a Rectangle object.
void | setCursor(Cursor c) Sets the Cursor of this object.
void | setEnabled(boolean b) Sets the enabled state of the object.
void | setFont(Font f) Sets the Font of this object.
void | setForeground(Color c) Sets the foreground color of this object.
void | setLocation(Point p) Sets the location of the object relative to the parent.
void | setSize(Dimension d) Resizes this object so that it has width and height.
void | setVisible(boolean b) Sets the visible state of the object.
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleTable, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JTable.AccessibleJTable.AccessibleJTableCell

public JTable.AccessibleJTable.AccessibleJTableCell(JTable t,
                                                    int r,
                                                    int c,
                                                    int i)
Constructs an AccessibleJTableHeaderEntry.

Since:
1.4
Method Detail

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this component. In the implementation of the Java Accessibility API for this class, return this object, which is its own AccessibleContext.

Specified by:
getAccessibleContext in interface Accessible
Returns:
this object

getCurrentAccessibleContext

protected AccessibleContext getCurrentAccessibleContext()
Gets the AccessibleContext for the table cell renderer.

Returns:
the AccessibleContext for the table cell renderer if one exists; otherwise, returns null.
Since:
1.6

getCurrentComponent

protected Component getCurrentComponent()
Gets the table cell renderer component.

Returns:
the table cell renderer component if one exists; otherwise, returns null.
Since:
1.6

getAccessibleName

public String getAccessibleName()
Gets the accessible name of this object.

Overrides:
getAccessibleName in class AccessibleContext
Returns:
the localized name of the object; null if this object does not have a name
See Also:
AccessibleContext.setAccessibleName(java.lang.String)

setAccessibleName

public void setAccessibleName(String s)
Sets the localized accessible name of this object.

Overrides:
setAccessibleName in class AccessibleContext
Parameters:
s - the new localized name of the object
See Also:
AccessibleContext.getAccessibleName(), AccessibleContext.addPropertyChangeListener(java.beans.PropertyChangeListener)

getAccessibleDescription

public String getAccessibleDescription()
Gets the accessible description of this object.

Overrides:
getAccessibleDescription in class AccessibleContext
Returns:
the localized description of the object; null if this object does not have a description
See Also:
AccessibleContext.setAccessibleDescription(java.lang.String)

setAccessibleDescription

public void setAccessibleDescription(String s)
Sets the accessible description of this object.

Overrides:
setAccessibleDescription in class AccessibleContext
Parameters:
s - the new localized description of the object
See Also:
AccessibleContext.setAccessibleName(java.lang.String), AccessibleContext.addPropertyChangeListener(java.beans.PropertyChangeListener)

getAccessibleRole

public AccessibleRole getAccessibleRole()
Gets the role of this object.

Specified by:
getAccessibleRole in class AccessibleContext
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Gets the state set of this object.

Specified by:
getAccessibleStateSet in class AccessibleContext
Returns:
an instance of AccessibleStateSet containing the current state set of the object
See Also:
AccessibleState

getAccessibleParent

public Accessible getAccessibleParent()
Gets the Accessible parent of this object.

Overrides:
getAccessibleParent in class AccessibleContext
Returns:
the Accessible parent of this object; null if this object does not have an Accessible parent

getAccessibleIndexInParent

public int getAccessibleIndexInParent()
Gets the index of this object in its accessible parent.

Specified by:
getAccessibleIndexInParent in class AccessibleContext
Returns:
the index of this object in its parent; -1 if this object does not have an accessible parent
See Also:
getAccessibleParent()

getAccessibleChildrenCount

public int getAccessibleChildrenCount()
Returns the number of accessible children in the object.

Specified by:
getAccessibleChildrenCount in class AccessibleContext
Returns:
the number of accessible children in the object

getAccessibleChild

public Accessible getAccessibleChild(int i)
Returns the specified Accessible child of the object.

Specified by:
getAccessibleChild in class AccessibleContext
Parameters:
i - zero-based index of child
Returns:
the Accessible child of the object
See Also:
AccessibleContext.getAccessibleChildrenCount()

getLocale

public Locale getLocale()
Gets the locale of the component. If the component does not have a locale, then the locale of its parent is returned.

Specified by:
getLocale in class AccessibleContext
Returns:
this component's locale; if this component does not have a locale, the locale of its parent is returned
Throws:
IllegalComponentStateException - if the Component does not have its own locale and has not yet been added to a containment hierarchy such that the locale can be determined from the containing parent
See Also:
Component.setLocale(java.util.Locale)

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener l)
Adds a PropertyChangeListener to the listener list. The listener is registered for all properties.

Overrides:
addPropertyChangeListener in class AccessibleContext
Parameters:
l - the PropertyChangeListener to be added
See Also:
AccessibleContext.ACCESSIBLE_NAME_PROPERTY, AccessibleContext.ACCESSIBLE_DESCRIPTION_PROPERTY, AccessibleContext.ACCESSIBLE_STATE_PROPERTY, AccessibleContext.ACCESSIBLE_VALUE_PROPERTY, AccessibleContext.ACCESSIBLE_SELECTION_PROPERTY, AccessibleContext.ACCESSIBLE_TEXT_PROPERTY, AccessibleContext.ACCESSIBLE_VISIBLE_DATA_PROPERTY

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener l)
Removes a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties.

Overrides:
removePropertyChangeListener in class AccessibleContext
Parameters:
l - the PropertyChangeListener to be removed

getAccessibleAction

public AccessibleAction getAccessibleAction()
Gets the AccessibleAction associated with this object if one exists. Otherwise returns null.

Overrides:
getAccessibleAction in class AccessibleContext
Returns:
the AccessibleAction, or null
See Also:
AccessibleAction

getAccessibleComponent

public AccessibleComponent getAccessibleComponent()
Gets the AccessibleComponent associated with this object if one exists. Otherwise returns null.

Overrides:
getAccessibleComponent in class AccessibleContext
Returns:
the AccessibleComponent, or null
See Also:
AccessibleComponent

getAccessibleSelection

public AccessibleSelection getAccessibleSelection()
Gets the AccessibleSelection associated with this object if one exists. Otherwise returns null.

Overrides:
getAccessibleSelection in class AccessibleContext
Returns:
the AccessibleSelection, or null
See Also:
AccessibleSelection

getAccessibleText

public AccessibleText getAccessibleText()
Gets the AccessibleText associated with this object if one exists. Otherwise returns null.

Overrides:
getAccessibleText in class AccessibleContext
Returns:
the AccessibleText, or null
See Also:
AccessibleText

getAccessibleValue

public AccessibleValue getAccessibleValue()
Gets the AccessibleValue associated with this object if one exists. Otherwise returns null.

Overrides:
getAccessibleValue in class AccessibleContext
Returns:
the AccessibleValue, or null
See Also:
AccessibleValue

getBackground

public Color getBackground()
Gets the background color of this object.

Specified by:
getBackground in interface AccessibleComponent
Returns:
the background color, if supported, of the object; otherwise, null
See Also:
AccessibleComponent.setBackground(java.awt.Color)

setBackground

public void setBackground(Color c)
Sets the background color of this object.

Specified by:
setBackground in interface AccessibleComponent
Parameters:
c - the new Color for the background
See Also:
AccessibleComponent.setBackground(java.awt.Color)

getForeground

public Color getForeground()
Gets the foreground color of this object.

Specified by:
getForeground in interface AccessibleComponent
Returns:
the foreground color, if supported, of the object; otherwise, null
See Also:
AccessibleComponent.setForeground(java.awt.Color)

setForeground

public void setForeground(Color c)
Sets the foreground color of this object.

Specified by:
setForeground in interface AccessibleComponent
Parameters:
c - the new Color for the foreground
See Also:
AccessibleComponent.getForeground()

getCursor

public Cursor getCursor()
Gets the Cursor of this object.

Specified by:
getCursor in interface AccessibleComponent
Returns:
the Cursor, if supported, of the object; otherwise, null
See Also:
AccessibleComponent.setCursor(java.awt.Cursor)

setCursor

public void setCursor(Cursor c)
Sets the Cursor of this object.

Specified by:
setCursor in interface AccessibleComponent
Parameters:
c - the new Cursor for the object
See Also:
AccessibleComponent.getCursor()

getFont

public Font getFont()
Gets the Font of this object.

Specified by:
getFont in interface AccessibleComponent
Returns:
the Font,if supported, for the object; otherwise, null
See Also:
AccessibleComponent.setFont(java.awt.Font)

setFont

public void setFont(Font f)
Sets the Font of this object.

Specified by:
setFont in interface AccessibleComponent
Parameters:
f - the new Font for the object
See Also:
AccessibleComponent.getFont()

getFontMetrics

public FontMetrics getFontMetrics(Font f)
Gets the FontMetrics of this object.

Specified by:
getFontMetrics in interface AccessibleComponent
Parameters:
f - the Font
Returns:
the FontMetrics object, if supported; otherwise null
See Also:
getFont()

isEnabled

public boolean isEnabled()
Determines if the object is enabled.

Specified by:
isEnabled in interface AccessibleComponent
Returns:
true if object is enabled; otherwise, false
See Also:
AccessibleComponent.setEnabled(boolean), AccessibleContext.getAccessibleStateSet(), AccessibleState.ENABLED, AccessibleStateSet

setEnabled

public void setEnabled(boolean b)
Sets the enabled state of the object.

Specified by:
setEnabled in interface AccessibleComponent
Parameters:
b - if true, enables this object; otherwise, disables it
See Also:
AccessibleComponent.isEnabled()

isVisible

public boolean isVisible()
Determines if this object is visible. Note: this means that the object intends to be visible; however, it may not in fact be showing on the screen because one of the objects that this object is contained by is not visible. To determine if an object is showing on the screen, use isShowing.

Specified by:
isVisible in interface AccessibleComponent
Returns:
true if object is visible; otherwise, false
See Also:
AccessibleComponent.setVisible(boolean), AccessibleContext.getAccessibleStateSet(), AccessibleState.VISIBLE, AccessibleStateSet

setVisible

public void setVisible(boolean b)
Sets the visible state of the object.

Specified by:
setVisible in interface AccessibleComponent
Parameters:
b - if true, shows this object; otherwise, hides it
See Also:
AccessibleComponent.isVisible()

isShowing

public boolean isShowing()
Determines if the object is showing. This is determined by checking the visibility of the object and ancestors of the object. Note: this will return true even if the object is obscured by another (for example, it happens to be underneath a menu that was pulled down).

Specified by:
isShowing in interface AccessibleComponent
Returns:
true if the object is showing; otherwise, false

contains

public boolean contains(Point p)
Checks whether the specified point is within this object's bounds, where the point's x and y coordinates are defined to be relative to the coordinate system of the object.

Specified by:
contains in interface AccessibleComponent
Parameters:
p - the Point relative to the coordinate system of the object
Returns:
true if object contains Point; otherwise false
See Also:
AccessibleComponent.getBounds()

getLocationOnScreen

public Point getLocationOnScreen()
Returns the location of the object on the screen.

Specified by:
getLocationOnScreen in interface AccessibleComponent
Returns:
location of object on screen -- can be null if this object is not on the screen
See Also:
AccessibleComponent.getBounds(), AccessibleComponent.getLocation()

getLocation

public Point getLocation()
Gets the location of the object relative to the parent in the form of a point specifying the object's top-left corner in the screen's coordinate space.

Specified by:
getLocation in interface AccessibleComponent
Returns:
an instance of Point representing the top-left corner of the object's bounds in the coordinate space of the screen; null if this object or its parent are not on the screen
See Also:
AccessibleComponent.getBounds(), AccessibleComponent.getLocationOnScreen()

setLocation

public void setLocation(Point p)
Sets the location of the object relative to the parent.

Specified by:
setLocation in interface AccessibleComponent
Parameters:
p - the new position for the top-left corner
See Also:
AccessibleComponent.getLocation()

getBounds

public Rectangle getBounds()
Description copied from interface: AccessibleComponent
Gets the bounds of this object in the form of a Rectangle object. The bounds specify this object's width, height, and location relative to its parent.

Specified by:
getBounds in interface AccessibleComponent
Returns:
A rectangle indicating this component's bounds; null if this object is not on the screen.
See Also:
AccessibleComponent.contains(java.awt.Point)

setBounds

public void setBounds(Rectangle r)
Description copied from interface: AccessibleComponent
Sets the bounds of this object in the form of a Rectangle object. The bounds specify this object's width, height, and location relative to its parent.

Specified by:
setBounds in interface AccessibleComponent
Parameters:
r - rectangle indicating this component's bounds
See Also:
AccessibleComponent.getBounds()

getSize

public Dimension getSize()
Description copied from interface: AccessibleComponent
Returns the size of this object in the form of a Dimension object. The height field of the Dimension object contains this object's height, and the width field of the Dimension object contains this object's width.

Specified by:
getSize in interface AccessibleComponent
Returns:
A Dimension object that indicates the size of this component; null if this object is not on the screen
See Also:
AccessibleComponent.setSize(java.awt.Dimension)

setSize

public void setSize(Dimension d)
Description copied from interface: AccessibleComponent
Resizes this object so that it has width and height.

Specified by:
setSize in interface AccessibleComponent
Parameters:
d - The dimension specifying the new size of the object.
See Also:
AccessibleComponent.getSize()

getAccessibleAt

public Accessible getAccessibleAt(Point p)
Description copied from interface: AccessibleComponent
Returns the Accessible child, if one exists, contained at the local coordinate Point.

Specified by:
getAccessibleAt in interface AccessibleComponent
Parameters:
p - The point relative to the coordinate system of this object.
Returns:
the Accessible, if it exists, at the specified location; otherwise null

isFocusTraversable

public boolean isFocusTraversable()
Description copied from interface: AccessibleComponent
Returns whether this object can accept focus or not. Objects that can accept focus will also have the AccessibleState.FOCUSABLE state set in their AccessibleStateSets.

Specified by:
isFocusTraversable in interface AccessibleComponent
Returns:
true if object can accept focus; otherwise false
See Also:
AccessibleContext.getAccessibleStateSet(), AccessibleState.FOCUSABLE, AccessibleState.FOCUSED, AccessibleStateSet

requestFocus

public void requestFocus()
Description copied from interface: AccessibleComponent
Requests focus for this object. If this object cannot accept focus, nothing will happen. Otherwise, the object will attempt to take focus.

Specified by:
requestFocus in interface AccessibleComponent
See Also:
AccessibleComponent.isFocusTraversable()

addFocusListener

public void addFocusListener(FocusListener l)
Description copied from interface: AccessibleComponent
Adds the specified focus listener to receive focus events from this component.

Specified by:
addFocusListener in interface AccessibleComponent
Parameters:
l - the focus listener
See Also:
AccessibleComponent.removeFocusListener(java.awt.event.FocusListener)

removeFocusListener

public void removeFocusListener(FocusListener l)
Description copied from interface: AccessibleComponent
Removes the specified focus listener so it no longer receives focus events from this component.

Specified by:
removeFocusListener in interface AccessibleComponent
Parameters:
l - the focus listener
See Also:
AccessibleComponent.addFocusListener(java.awt.event.FocusListener)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTable.AccessibleJTable.AccessibleJTableModelChange

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTable.AccessibleJTable.AccessibleJTableModelChange

java.lang.Object
    extended by  javax.swing.JTable.AccessibleJTable.AccessibleJTableModelChange
All Implemented Interfaces:
AccessibleTableModelChange
Enclosing class:
JTable.AccessibleJTable
protected class JTable.AccessibleJTable.AccessibleJTableModelChange
extends Object
implements AccessibleTableModelChange

Field Summary
protected int | firstColumn
protected int | firstRow
protected int | lastColumn
protected int | lastRow
protected int | type
Fields inherited from interface javax.accessibility.AccessibleTableModelChange
DELETE, INSERT, UPDATE
Constructor Summary
protected JTable.AccessibleJTable.AccessibleJTableModelChange(int type, int firstRow, int lastRow, int firstColumn, int lastColumn)
Method Summary
int | getFirstColumn() Returns the first column that changed.
int | getFirstRow() Returns the first row that changed.
int | getLastColumn() Returns the last column that changed.
int | getLastRow() Returns the last row that changed.
int | getType() Returns the type of event
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

type

protected int type

firstRow

protected int firstRow

lastRow

protected int lastRow

firstColumn

protected int firstColumn

lastColumn

protected int lastColumn
Constructor Detail

JTable.AccessibleJTable.AccessibleJTableModelChange

protected JTable.AccessibleJTable.AccessibleJTableModelChange(int type,
                                                              int firstRow,
                                                              int lastRow,
                                                              int firstColumn,
                                                              int lastColumn)
Method Detail

getType

public int getType()
Description copied from interface: AccessibleTableModelChange
Returns the type of event

Specified by:
getType in interface AccessibleTableModelChange
See Also:
AccessibleTableModelChange.INSERT, AccessibleTableModelChange.UPDATE, AccessibleTableModelChange.DELETE

getFirstRow

public int getFirstRow()
Description copied from interface: AccessibleTableModelChange
Returns the first row that changed.

Specified by:
getFirstRow in interface AccessibleTableModelChange

getLastRow

public int getLastRow()
Description copied from interface: AccessibleTableModelChange
Returns the last row that changed.

Specified by:
getLastRow in interface AccessibleTableModelChange

getFirstColumn

public int getFirstColumn()
Description copied from interface: AccessibleTableModelChange
Returns the first column that changed.

Specified by:
getFirstColumn in interface AccessibleTableModelChange

getLastColumn

public int getLastColumn()
Description copied from interface: AccessibleTableModelChange
Returns the last column that changed.

Specified by:
getLastColumn in interface AccessibleTableModelChange
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTable.DropLocation

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTable.DropLocation

java.lang.Object
    extended by  javax.swing.TransferHandler.DropLocation
        extended by  javax.swing.JTable.DropLocation
Enclosing class:
JTable
public static final class JTable.DropLocation
extends TransferHandler.DropLocation

A subclass of TransferHandler.DropLocation representing a drop location for a JTable.

Since:
1.6
See Also:
JTable.getDropLocation()

Method Summary
int | getColumn() Returns the column index where a dropped item should be placed in the table.
int | getRow() Returns the row index where a dropped item should be placed in the table.
boolean | isInsertColumn() Returns whether or not this location represents an insert of a column.
boolean | isInsertRow() Returns whether or not this location represents an insert of a row.
String | toString() Returns a string representation of this drop location.
Methods inherited from class javax.swing.TransferHandler.DropLocation
getDropPoint
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getRow

public int getRow()
Returns the row index where a dropped item should be placed in the table. Interpretation of the value depends on the return of isInsertRow(). If that method returns true this value indicates the index where a new row should be inserted. Otherwise, it represents the value of an existing row on which the data was dropped. This index is in terms of the view.

-1 indicates that the drop occurred over empty space, and no row could be calculated.

Returns:
the drop row

getColumn

public int getColumn()
Returns the column index where a dropped item should be placed in the table. Interpretation of the value depends on the return of isInsertColumn(). If that method returns true this value indicates the index where a new column should be inserted. Otherwise, it represents the value of an existing column on which the data was dropped. This index is in terms of the view.

-1 indicates that the drop occurred over empty space, and no column could be calculated.

Returns:
the drop row

isInsertRow

public boolean isInsertRow()
Returns whether or not this location represents an insert of a row.

Returns:
whether or not this is an insert row

isInsertColumn

public boolean isInsertColumn()
Returns whether or not this location represents an insert of a column.

Returns:
whether or not this is an insert column

toString

public String toString()
Returns a string representation of this drop location. This method is intended to be used for debugging purposes, and the content and format of the returned string may vary between implementations.

Overrides:
toString in class TransferHandler.DropLocation
Returns:
a string representation of this drop location
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTable.PrintMode

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.swing
Enum JTable.PrintMode

java.lang.Object
    extended by  java.lang.Enum<JTable.PrintMode>
        extended by  javax.swing.JTable.PrintMode
All Implemented Interfaces:
Serializable, Comparable<JTable.PrintMode>
Enclosing class:
JTable
public static enum JTable.PrintMode
extends Enum<JTable.PrintMode>

Printing modes, used in printing JTables.

Since:
1.5
See Also:
JTable.print(JTable.PrintMode, MessageFormat, MessageFormat, boolean, PrintRequestAttributeSet, boolean), JTable.getPrintable(javax.swing.JTable.PrintMode, java.text.MessageFormat, java.text.MessageFormat)

Enum Constant Summary
FIT_WIDTH
Printing mode that scales the output smaller, if necessary, to fit the table's entire width (and thereby all columns) on each page; Rows are spread across multiple pages as necessary.
NORMAL
Printing mode that prints the table at its current size, spreading both columns and rows across multiple pages if necessary.
Method Summary
static JTable.PrintMode | valueOf(String name) Returns the enum constant of this type with the specified name.
static JTable.PrintMode[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

NORMAL

public static final JTable.PrintMode NORMAL
Printing mode that prints the table at its current size, spreading both columns and rows across multiple pages if necessary.

FIT_WIDTH

public static final JTable.PrintMode FIT_WIDTH
Printing mode that scales the output smaller, if necessary, to fit the table's entire width (and thereby all columns) on each page; Rows are spread across multiple pages as necessary.

Method Detail

values

public static JTable.PrintMode[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (JTable.PrintMode c : JTable.PrintMode.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static JTable.PrintMode valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


JTextArea

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTextArea

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.text.JTextComponent
                    extended by  javax.swing.JTextArea
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable
public class JTextArea
extends JTextComponent

A JTextArea is a multi-line area that displays plain text. It is intended to be a lightweight component that provides source compatibility with the java.awt.TextArea class where it can reasonably do so. You can find information and examples of using all the text components in Using Text Components, a section in The Java Tutorial.

This component has capabilities not found in the java.awt.TextArea class. The superclass should be consulted for additional capabilities. Alternative multi-line text classes with more capabilities are JTextPane and JEditorPane.

The java.awt.TextArea internally handles scrolling. JTextArea is different in that it doesn't manage scrolling, but implements the swing Scrollable interface. This allows it to be placed inside a JScrollPane if scrolling behavior is desired, and used directly if scrolling is not desired.

The java.awt.TextArea has the ability to do line wrapping. This was controlled by the horizontal scrolling policy. Since scrolling is not done by JTextArea directly, backward compatibility must be provided another way. JTextArea has a bound property for line wrapping that controls whether or not it will wrap lines. By default, the line wrapping property is set to false (not wrapped).

java.awt.TextArea has two properties rows and columns that are used to determine the preferred size. JTextArea uses these properties to indicate the preferred size of the viewport when placed inside a JScrollPane to match the functionality provided by java.awt.TextArea. JTextArea has a preferred size of what is needed to display all of the text, so that it functions properly inside of a JScrollPane. If the value for rows or columns is equal to zero, the preferred size along that axis is used for the viewport preferred size along the same axis.

The java.awt.TextArea could be monitored for changes by adding a TextListener for TextEvents. In the JTextComponent based components, changes are broadcasted from the model via a DocumentEvent to DocumentListeners. The DocumentEvent gives the location of the change and the kind of change if desired. The code fragment might look something like:

    DocumentListener myListener = ??;
    JTextArea myArea = ??;
    myArea.getDocument().addDocumentListener(myListener);

Newlines
For a discussion on how newlines are handled, see DefaultEditorKit.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JTextPane, JEditorPane

Nested Class Summary
protected  class JTextArea.AccessibleJTextArea
This class implements accessibility support for the JTextArea class.
Nested classes/interfaces inherited from class javax.swing.text.JTextComponent
JTextComponent.AccessibleJTextComponent, JTextComponent.DropLocation, JTextComponent.KeyBinding
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.text.JTextComponent
DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JTextArea()
Constructs a new TextArea.
JTextArea(Document doc)
Constructs a new JTextArea with the given document model, and defaults for all of the other arguments (null, 0, 0).
JTextArea(Document doc, String text, int rows, int columns)
Constructs a new JTextArea with the specified number of rows and columns, and the given model.
JTextArea(int rows, int columns)
Constructs a new empty TextArea with the specified number of rows and columns.
JTextArea(String text)
Constructs a new TextArea with the specified text displayed.
JTextArea(String text, int rows, int columns)
Constructs a new TextArea with the specified text and number of rows and columns.
Method Summary
void | append(String str) Appends the given text to the end of the document.
protected Document | createDefaultModel() Creates the default implementation of the model to be used at construction if one isn't explicitly given.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JTextArea.
int | getColumns() Returns the number of columns in the TextArea.
protected int | getColumnWidth() Gets column width.
int | getLineCount() Determines the number of lines contained in the area.
int | getLineEndOffset(int line) Determines the offset of the end of the given line.
int | getLineOfOffset(int offset) Translates an offset into the components text to a line number.
int | getLineStartOffset(int line) Determines the offset of the start of the given line.
boolean | getLineWrap() Gets the line-wrapping policy of the text area.
Dimension | getPreferredScrollableViewportSize() Returns the preferred size of the viewport if this component is embedded in a JScrollPane.
Dimension | getPreferredSize() Returns the preferred size of the TextArea.
protected int | getRowHeight() Defines the meaning of the height of a row.
int | getRows() Returns the number of rows in the TextArea.
boolean | getScrollableTracksViewportWidth() Returns true if a viewport should always force the width of this Scrollable to match the width of the viewport.
int | getScrollableUnitIncrement(Rectangle visibleRect, int orientation, int direction) Components that display logical rows or columns should compute the scroll increment that will completely expose one new row or column, depending on the value of orientation.
int | getTabSize() Gets the number of characters used to expand tabs.
String | getUIClassID() Returns the class ID for the UI.
boolean | getWrapStyleWord() Gets the style of wrapping used if the text area is wrapping lines.
void | insert(String str, int pos) Inserts the specified text at the specified position.
protected String | paramString() Returns a string representation of this JTextArea.
void | replaceRange(String str, int start, int end) Replaces text from the indicated start to end position with the new text specified.
void | setColumns(int columns) Sets the number of columns for this TextArea.
void | setFont(Font f) Sets the current font.
void | setLineWrap(boolean wrap) Sets the line-wrapping policy of the text area.
void | setRows(int rows) Sets the number of rows for this TextArea.
void | setTabSize(int size) Sets the number of characters to expand tabs to.
void | setWrapStyleWord(boolean word) Sets the style of wrapping used if the text area is wrapping lines.
Methods inherited from class javax.swing.text.JTextComponent
addCaretListener, addInputMethodListener, addKeymap, copy, cut, fireCaretUpdate, getActions, getCaret, getCaretColor, getCaretListeners, getCaretPosition, getDisabledTextColor, getDocument, getDragEnabled, getDropLocation, getDropMode, getFocusAccelerator, getHighlighter, getInputMethodRequests, getKeymap, getKeymap, getMargin, getNavigationFilter, getPrintable, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getText, getToolTipText, getUI, isEditable, loadKeymap, modelToView, moveCaretPosition, paste, print, print, print, processInputMethodEvent, read, removeCaretListener, removeKeymap, removeNotify, replaceSelection, select, selectAll, setCaret, setCaretColor, setCaretPosition, setComponentOrientation, setDisabledTextColor, setDocument, setDragEnabled, setDropMode, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, setUI, updateUI, viewToModel, write
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JTextArea

public JTextArea()
Constructs a new TextArea. A default model is set, the initial string is null, and rows/columns are set to 0.

JTextArea

public JTextArea(String text)
Constructs a new TextArea with the specified text displayed. A default model is created and rows/columns are set to 0.

Parameters:
text - the text to be displayed, or null

JTextArea

public JTextArea(int rows,
                 int columns)
Constructs a new empty TextArea with the specified number of rows and columns. A default model is created, and the initial string is null.

Parameters:
rows - the number of rows >= 0
columns - the number of columns >= 0
Throws:
IllegalArgumentException - if the rows or columns arguments are negative.

JTextArea

public JTextArea(String text,
                 int rows,
                 int columns)
Constructs a new TextArea with the specified text and number of rows and columns. A default model is created.

Parameters:
text - the text to be displayed, or null
rows - the number of rows >= 0
columns - the number of columns >= 0
Throws:
IllegalArgumentException - if the rows or columns arguments are negative.

JTextArea

public JTextArea(Document doc)
Constructs a new JTextArea with the given document model, and defaults for all of the other arguments (null, 0, 0).

Parameters:
doc - the model to use

JTextArea

public JTextArea(Document doc,
                 String text,
                 int rows,
                 int columns)
Constructs a new JTextArea with the specified number of rows and columns, and the given model. All of the constructors feed through this constructor.

Parameters:
doc - the model to use, or create a default one if null
text - the text to be displayed, null if none
rows - the number of rows >= 0
columns - the number of columns >= 0
Throws:
IllegalArgumentException - if the rows or columns arguments are negative.
Method Detail

getUIClassID

public String getUIClassID()
Returns the class ID for the UI.

Overrides:
getUIClassID in class JComponent
Returns:
the ID ("TextAreaUI")
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

createDefaultModel

protected Document createDefaultModel()
Creates the default implementation of the model to be used at construction if one isn't explicitly given. A new instance of PlainDocument is returned.

Returns:
the default document model

setTabSize

public void setTabSize(int size)
Sets the number of characters to expand tabs to. This will be multiplied by the maximum advance for variable width fonts. A PropertyChange event ("tabSize") is fired when the tab size changes.

Parameters:
size - number of characters to expand to
See Also:
getTabSize()

getTabSize

public int getTabSize()
Gets the number of characters used to expand tabs. If the document is null or doesn't have a tab setting, return a default of 8.

Returns:
the number of characters

setLineWrap

public void setLineWrap(boolean wrap)
Sets the line-wrapping policy of the text area. If set to true the lines will be wrapped if they are too long to fit within the allocated width. If set to false, the lines will always be unwrapped. A PropertyChange event ("lineWrap") is fired when the policy is changed. By default this property is false.

Parameters:
wrap - indicates if lines should be wrapped
See Also:
getLineWrap()

getLineWrap

public boolean getLineWrap()
Gets the line-wrapping policy of the text area. If set to true the lines will be wrapped if they are too long to fit within the allocated width. If set to false, the lines will always be unwrapped.

Returns:
if lines will be wrapped

setWrapStyleWord

public void setWrapStyleWord(boolean word)
Sets the style of wrapping used if the text area is wrapping lines. If set to true the lines will be wrapped at word boundaries (whitespace) if they are too long to fit within the allocated width. If set to false, the lines will be wrapped at character boundaries. By default this property is false.

Parameters:
word - indicates if word boundaries should be used for line wrapping
See Also:
getWrapStyleWord()

getWrapStyleWord

public boolean getWrapStyleWord()
Gets the style of wrapping used if the text area is wrapping lines. If set to true the lines will be wrapped at word boundaries (ie whitespace) if they are too long to fit within the allocated width. If set to false, the lines will be wrapped at character boundaries.

Returns:
if the wrap style should be word boundaries instead of character boundaries
See Also:
setWrapStyleWord(boolean)

getLineOfOffset

public int getLineOfOffset(int offset)
                    throws BadLocationException
Translates an offset into the components text to a line number.

Parameters:
offset - the offset >= 0
Returns:
the line number >= 0
Throws:
BadLocationException - thrown if the offset is less than zero or greater than the document length.

getLineCount

public int getLineCount()
Determines the number of lines contained in the area.

Returns:
the number of lines > 0

getLineStartOffset

public int getLineStartOffset(int line)
                       throws BadLocationException
Determines the offset of the start of the given line.

Parameters:
line - the line number to translate >= 0
Returns:
the offset >= 0
Throws:
BadLocationException - thrown if the line is less than zero or greater or equal to the number of lines contained in the document (as reported by getLineCount).

getLineEndOffset

public int getLineEndOffset(int line)
                     throws BadLocationException
Determines the offset of the end of the given line.

Parameters:
line - the line >= 0
Returns:
the offset >= 0
Throws:
BadLocationException - Thrown if the line is less than zero or greater or equal to the number of lines contained in the document (as reported by getLineCount).

insert

public void insert(String str,
                   int pos)
Inserts the specified text at the specified position. Does nothing if the model is null or if the text is null or empty.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Parameters:
str - the text to insert
pos - the position at which to insert >= 0
Throws:
IllegalArgumentException - if pos is an invalid position in the model
See Also:
TextComponent.setText(java.lang.String), replaceRange(java.lang.String, int, int)

append

public void append(String str)
Appends the given text to the end of the document. Does nothing if the model is null or the string is null or empty.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Parameters:
str - the text to insert
See Also:
insert(java.lang.String, int)

replaceRange

public void replaceRange(String str,
                         int start,
                         int end)
Replaces text from the indicated start to end position with the new text specified. Does nothing if the model is null. Simply does a delete if the new string is null or empty.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Parameters:
str - the text to use as the replacement
start - the start position >= 0
end - the end position >= start
Throws:
IllegalArgumentException - if part of the range is an invalid position in the model
See Also:
insert(java.lang.String, int), replaceRange(java.lang.String, int, int)

getRows

public int getRows()
Returns the number of rows in the TextArea.

Returns:
the number of rows >= 0

setRows

public void setRows(int rows)
Sets the number of rows for this TextArea. Calls invalidate() after setting the new value.

Parameters:
rows - the number of rows >= 0
Throws:
IllegalArgumentException - if rows is less than 0
See Also:
getRows()

getRowHeight

protected int getRowHeight()
Defines the meaning of the height of a row. This defaults to the height of the font.

Returns:
the height >= 1

getColumns

public int getColumns()
Returns the number of columns in the TextArea.

Returns:
number of columns >= 0

setColumns

public void setColumns(int columns)
Sets the number of columns for this TextArea. Does an invalidate() after setting the new value.

Parameters:
columns - the number of columns >= 0
Throws:
IllegalArgumentException - if columns is less than 0
See Also:
getColumns()

getColumnWidth

protected int getColumnWidth()
Gets column width. The meaning of what a column is can be considered a fairly weak notion for some fonts. This method is used to define the width of a column. By default this is defined to be the width of the character m for the font used. This method can be redefined to be some alternative amount.

Returns:
the column width >= 1

getPreferredSize

public Dimension getPreferredSize()
Returns the preferred size of the TextArea. This is the maximum of the size needed to display the text and the size requested for the viewport.

Overrides:
getPreferredSize in class JComponent
Returns:
the size
See Also:
JComponent.setPreferredSize(java.awt.Dimension), ComponentUI

setFont

public void setFont(Font f)
Sets the current font. This removes cached row height and column width so the new font will be reflected, and calls revalidate().

Overrides:
setFont in class JComponent
Parameters:
f - the font to use as the current font
See Also:
Component.getFont()

paramString

protected String paramString()
Returns a string representation of this JTextArea. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JTextComponent
Returns:
a string representation of this JTextArea.

getScrollableTracksViewportWidth

public boolean getScrollableTracksViewportWidth()
Returns true if a viewport should always force the width of this Scrollable to match the width of the viewport. This is implemented to return true if the line wrapping policy is true, and false if lines are not being wrapped.

Specified by:
getScrollableTracksViewportWidth in interface Scrollable
Overrides:
getScrollableTracksViewportWidth in class JTextComponent
Returns:
true if a viewport should force the Scrollables width to match its own.

getPreferredScrollableViewportSize

public Dimension getPreferredScrollableViewportSize()
Returns the preferred size of the viewport if this component is embedded in a JScrollPane. This uses the desired column and row settings if they have been set, otherwise the superclass behavior is used.

Specified by:
getPreferredScrollableViewportSize in interface Scrollable
Overrides:
getPreferredScrollableViewportSize in class JTextComponent
Returns:
The preferredSize of a JViewport whose view is this Scrollable.
See Also:
JComponent.getPreferredSize()

getScrollableUnitIncrement

public int getScrollableUnitIncrement(Rectangle visibleRect,
                                      int orientation,
                                      int direction)
Components that display logical rows or columns should compute the scroll increment that will completely expose one new row or column, depending on the value of orientation. This is implemented to use the values returned by the getRowHeight and getColumnWidth methods.

Scrolling containers, like JScrollPane, will use this method each time the user requests a unit scroll.

Specified by:
getScrollableUnitIncrement in interface Scrollable
Overrides:
getScrollableUnitIncrement in class JTextComponent
Parameters:
visibleRect - the view area visible within the viewport
orientation - Either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL.
direction - Less than zero to scroll up/left, greater than zero for down/right.
Returns:
The "unit" increment for scrolling in the specified direction
Throws:
IllegalArgumentException - for an invalid orientation
See Also:
JScrollBar.setUnitIncrement(int),
getRowHeight(),
getColumnWidth()

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JTextArea. For JTextAreas, the AccessibleContext takes the form of an AccessibleJTextArea. A new AccessibleJTextArea instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JTextComponent
Returns:
an AccessibleJTextArea that serves as the AccessibleContext of this JTextArea
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTextArea.AccessibleJTextArea

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTextArea.AccessibleJTextArea

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.text.JTextComponent.AccessibleJTextComponent
                        extended by  javax.swing.JTextArea.AccessibleJTextArea
All Implemented Interfaces:
Serializable, EventListener, AccessibleAction, AccessibleComponent, AccessibleEditableText, AccessibleExtendedComponent, AccessibleExtendedText, AccessibleText, CaretListener, DocumentListener
Enclosing class:
JTextArea
protected class JTextArea.AccessibleJTextArea
extends JTextComponent.AccessibleJTextComponent

This class implements accessibility support for the JTextArea class. It provides an implementation of the Java Accessibility API appropriate to text area user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Fields inherited from interface javax.accessibility.AccessibleExtendedText
ATTRIBUTE_RUN, LINE
Constructor Summary
protected JTextArea.AccessibleJTextArea()
Method Summary
 AccessibleStateSet getAccessibleStateSet()
Gets the state set of this object.
Methods inherited from class javax.swing.text.JTextComponent.AccessibleJTextComponent
caretUpdate, changedUpdate, cut, delete, doAccessibleAction, getAccessibleAction, getAccessibleActionCount, getAccessibleActionDescription, getAccessibleEditableText, getAccessibleRole, getAccessibleText, getAfterIndex, getAtIndex, getBeforeIndex, getCaretPosition, getCharacterAttribute, getCharacterBounds, getCharCount, getIndexAtPoint, getSelectedText, getSelectionEnd, getSelectionStart, getTextBounds, getTextRange, getTextSequenceAfter, getTextSequenceAt, getTextSequenceBefore, insertTextAtIndex, insertUpdate, paste, removeUpdate, replaceText, selectText, setAttributes, setTextContents
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JTextArea.AccessibleJTextArea

protected JTextArea.AccessibleJTextArea()
Method Detail

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Gets the state set of this object.

Overrides:
getAccessibleStateSet in class JTextComponent.AccessibleJTextComponent
Returns:
an instance of AccessibleStateSet describing the states of the object
See Also:
AccessibleStateSet
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTextField

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTextField

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.text.JTextComponent
                    extended by  javax.swing.JTextField
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable, SwingConstants
Direct Known Subclasses:
DefaultTreeCellEditor.DefaultTextField, JFormattedTextField, JPasswordField
public class JTextField
extends JTextComponent
implements SwingConstants

JTextField is a lightweight component that allows the editing of a single line of text. For information on and examples of using text fields, see How to Use Text Fields in The Java Tutorial.

JTextField is intended to be source-compatible with java.awt.TextField where it is reasonable to do so. This component has capabilities not found in the java.awt.TextField class. The superclass should be consulted for additional capabilities.

JTextField has a method to establish the string used as the command string for the action event that gets fired. The java.awt.TextField used the text of the field as the command string for the ActionEvent. JTextField will use the command string set with the setActionCommand method if not null, otherwise it will use the text of the field as a compatibility with java.awt.TextField.

The method setEchoChar and getEchoChar are not provided directly to avoid a new implementation of a pluggable look-and-feel inadvertently exposing password characters. To provide password-like services a separate class JPasswordField extends JTextField to provide this service with an independently pluggable look-and-feel.

The java.awt.TextField could be monitored for changes by adding a TextListener for TextEvent's. In the JTextComponent based components, changes are broadcasted from the model via a DocumentEvent to DocumentListeners. The DocumentEvent gives the location of the change and the kind of change if desired. The code fragment might look something like:

     DocumentListener myListener = ??;
     JTextField myArea = ??;
     myArea.getDocument().addDocumentListener(myListener);

The horizontal alignment of JTextField can be set to be left justified, leading justified, centered, right justified or trailing justified. Right/trailing justification is useful if the required size of the field text is smaller than the size allocated to it. This is determined by the setHorizontalAlignment and getHorizontalAlignment methods. The default is to be leading justified.

How the text field consumes VK_ENTER events depends on whether the text field has any action listeners. If so, then VK_ENTER results in the listeners getting an ActionEvent, and the VK_ENTER event is consumed. This is compatible with how AWT text fields handle VK_ENTER events. If the text field has no action listeners, then as of v 1.3 the VK_ENTER event is not consumed. Instead, the bindings of ancestor components are processed, which enables the default button feature of JFC/Swing to work.

Customized fields can easily be created by extending the model and changing the default model provided. For example, the following piece of code will create a field that holds only upper case characters. It will work even if text is pasted into from the clipboard or it is altered via programmatic changes.

 public class UpperCaseField extends JTextField {

     public UpperCaseField(int cols) {
         super(cols);
     }

     protected Document createDefaultModel() {
         return new UpperCaseDocument();
     }

     static class UpperCaseDocument extends PlainDocument {

         public void insertString(int offs, String str, AttributeSet a)
             throws BadLocationException {

             if (str == null) {
                 return;
             }
             char[] upper = str.toCharArray();
             for (int i = 0; i < upper.length; i++) {
                 upper[i] = Character.toUpperCase(upper[i]);
             }
             super.insertString(offs, new String(upper), a);
         }
     }
 }

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
setActionCommand(java.lang.String), JPasswordField, addActionListener(java.awt.event.ActionListener)

Nested Class Summary
protected  class JTextField.AccessibleJTextField
This class implements accessibility support for the JTextField class.
Nested classes/interfaces inherited from class javax.swing.text.JTextComponent
JTextComponent.AccessibleJTextComponent, JTextComponent.DropLocation, JTextComponent.KeyBinding
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
static String notifyAction
Name of the action to send notification that the contents of the field have been accepted.
Fields inherited from class javax.swing.text.JTextComponent
DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JTextField()
Constructs a new TextField.
JTextField(Document doc, String text, int columns)
Constructs a new JTextField that uses the given text storage model and the given number of columns.
JTextField(int columns)
Constructs a new empty TextField with the specified number of columns.
JTextField(String text)
Constructs a new TextField initialized with the specified text.
JTextField(String text, int columns)
Constructs a new TextField initialized with the specified text and columns.
Method Summary
protected  void actionPropertyChanged(Action action, String propertyName)
Updates the textfield's state in response to property changes in associated action.
 void addActionListener(ActionListener l)
Adds the specified action listener to receive action events from this textfield.
protected  void configurePropertiesFromAction(Action a)
Sets the properties on this textfield to match those in the specified Action.
protected  PropertyChangeListener createActionPropertyChangeListener(Action a)
Creates and returns a PropertyChangeListener that is responsible for listening for changes from the specified Action and updating the appropriate properties.
protected  Document createDefaultModel()
Creates the default implementation of the model to be used at construction if one isn't explicitly given.
protected  void fireActionPerformed()
Notifies all listeners that have registered interest for notification on this event type.
 AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JTextField.
 Action getAction()
Returns the currently set Action for this ActionEvent source, or null if no Action is set.
 ActionListener[] getActionListeners()
Returns an array of all the ActionListeners added to this JTextField with addActionListener().
 Action[] getActions()
Fetches the command list for the editor.
 int getColumns()
Returns the number of columns in this TextField.
protected  int getColumnWidth()
Returns the column width.
 int getHorizontalAlignment()
Returns the horizontal alignment of the text.
 BoundedRangeModel getHorizontalVisibility()
Gets the visibility of the text field.
 Dimension getPreferredSize()
Returns the preferred size Dimensions needed for this TextField.
 int getScrollOffset()
Gets the scroll offset, in pixels.
 String getUIClassID()
Gets the class ID for a UI.
 boolean isValidateRoot()
Calls to revalidate that come from within the textfield itself will be handled by validating the textfield, unless the textfield is contained within a JViewport, in which case this returns false.
protected  String paramString()
Returns a string representation of this JTextField.
 void postActionEvent()
Processes action events occurring on this textfield by dispatching them to any registered ActionListener objects.
 void removeActionListener(ActionListener l)
Removes the specified action listener so that it no longer receives action events from this textfield.
 void scrollRectToVisible(Rectangle r)
Scrolls the field left or right.
 void setAction(Action a)
Sets the Action for the ActionEvent source.
 void setActionCommand(String command)
Sets the command string used for action events.
 void setColumns(int columns)
Sets the number of columns in this TextField, and then invalidate the layout.
 void setDocument(Document doc)
Associates the editor with a text document.
 void setFont(Font f)
Sets the current font.
 void setHorizontalAlignment(int alignment)
Sets the horizontal alignment of the text.
 void setScrollOffset(int scrollOffset)
Sets the scroll offset, in pixels.
Methods inherited from class javax.swing.text.JTextComponent
addCaretListener, addInputMethodListener, addKeymap, copy, cut, fireCaretUpdate, getCaret, getCaretColor, getCaretListeners, getCaretPosition, getDisabledTextColor, getDocument, getDragEnabled, getDropLocation, getDropMode, getFocusAccelerator, getHighlighter, getInputMethodRequests, getKeymap, getKeymap, getMargin, getNavigationFilter, getPreferredScrollableViewportSize, getPrintable, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getScrollableUnitIncrement, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getText, getToolTipText, getUI, isEditable, loadKeymap, modelToView, moveCaretPosition, paste, print, print, print, processInputMethodEvent, read, removeCaretListener, removeKeymap, removeNotify, replaceSelection, select, selectAll, setCaret, setCaretColor, setCaretPosition, setComponentOrientation, setDisabledTextColor, setDragEnabled, setDropMode, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, setUI, updateUI, viewToModel, write
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

notifyAction

public static final String notifyAction
Name of the action to send notification that the contents of the field have been accepted. Typically this is bound to a carriage-return.

See Also:
Constant Field Values
Constructor Detail

JTextField

public JTextField()
Constructs a new TextField. A default model is created, the initial string is null, and the number of columns is set to 0.

JTextField

public JTextField(String text)
Constructs a new TextField initialized with the specified text. A default model is created and the number of columns is 0.

Parameters:
text - the text to be displayed, or null

JTextField

public JTextField(int columns)
Constructs a new empty TextField with the specified number of columns. A default model is created and the initial string is set to null.

Parameters:
columns - the number of columns to use to calculate the preferred width; if columns is set to zero, the preferred width will be whatever naturally results from the component implementation

JTextField

public JTextField(String text,
                  int columns)
Constructs a new TextField initialized with the specified text and columns. A default model is created.

Parameters:
text - the text to be displayed, or null
columns - the number of columns to use to calculate the preferred width; if columns is set to zero, the preferred width will be whatever naturally results from the component implementation

JTextField

public JTextField(Document doc,
                  String text,
                  int columns)
Constructs a new JTextField that uses the given text storage model and the given number of columns. This is the constructor through which the other constructors feed. If the document is null, a default model is created.

Parameters:
doc - the text storage to use; if this is null, a default will be provided by calling the createDefaultModel method
text - the initial string to display, or null
columns - the number of columns to use to calculate the preferred width >= 0; if columns is set to zero, the preferred width will be whatever naturally results from the component implementation
Throws:
IllegalArgumentException - if columns < 0
Method Detail

getUIClassID

public String getUIClassID()
Gets the class ID for a UI.

Overrides:
getUIClassID in class JComponent
Returns:
the string "TextFieldUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

setDocument

public void setDocument(Document doc)
Associates the editor with a text document. The currently registered factory is used to build a view for the document, which gets displayed by the editor after revalidation. A PropertyChange event ("document") is propagated to each listener.

Overrides:
setDocument in class JTextComponent
Parameters:
doc - the document to display/edit
See Also:
JTextComponent.getDocument()

isValidateRoot

public boolean isValidateRoot()
Calls to revalidate that come from within the textfield itself will be handled by validating the textfield, unless the textfield is contained within a JViewport, in which case this returns false.

Overrides:
isValidateRoot in class JComponent
Returns:
if the parent of this textfield is a JViewPort return false, otherwise return true
See Also:
JComponent.revalidate(), JComponent.isValidateRoot()

getHorizontalAlignment

public int getHorizontalAlignment()
Returns the horizontal alignment of the text. Valid keys are:
  • JTextField.LEFT
  • JTextField.CENTER
  • JTextField.RIGHT
  • JTextField.LEADING
  • JTextField.TRAILING

Returns:
the horizontal alignment

setHorizontalAlignment

public void setHorizontalAlignment(int alignment)
Sets the horizontal alignment of the text. Valid keys are:
  • JTextField.LEFT
  • JTextField.CENTER
  • JTextField.RIGHT
  • JTextField.LEADING
  • JTextField.TRAILING
invalidate and repaint are called when the alignment is set, and a PropertyChange event ("horizontalAlignment") is fired.

Parameters:
alignment - the alignment
Throws:
IllegalArgumentException - if alignment is not a valid key

createDefaultModel

protected Document createDefaultModel()
Creates the default implementation of the model to be used at construction if one isn't explicitly given. An instance of PlainDocument is returned.

Returns:
the default model implementation

getColumns

public int getColumns()
Returns the number of columns in this TextField.

Returns:
the number of columns >= 0

setColumns

public void setColumns(int columns)
Sets the number of columns in this TextField, and then invalidate the layout.

Parameters:
columns - the number of columns >= 0
Throws:
IllegalArgumentException - if columns is less than 0

getColumnWidth

protected int getColumnWidth()
Returns the column width. The meaning of what a column is can be considered a fairly weak notion for some fonts. This method is used to define the width of a column. By default this is defined to be the width of the character m for the font used. This method can be redefined to be some alternative amount

Returns:
the column width >= 1

getPreferredSize

public Dimension getPreferredSize()
Returns the preferred size Dimensions needed for this TextField. If a non-zero number of columns has been set, the width is set to the columns multiplied by the column width.

Overrides:
getPreferredSize in class JComponent
Returns:
the dimension of this textfield
See Also:
JComponent.setPreferredSize(java.awt.Dimension), ComponentUI

setFont

public void setFont(Font f)
Sets the current font. This removes cached row height and column width so the new font will be reflected. revalidate is called after setting the font.

Overrides:
setFont in class JComponent
Parameters:
f - the new font
See Also:
Component.getFont()

addActionListener

public void addActionListener(ActionListener l)
Adds the specified action listener to receive action events from this textfield.

Parameters:
l - the action listener to be added

removeActionListener

public void removeActionListener(ActionListener l)
Removes the specified action listener so that it no longer receives action events from this textfield.

Parameters:
l - the action listener to be removed

getActionListeners

public ActionListener[] getActionListeners()
Returns an array of all the ActionListeners added to this JTextField with addActionListener().

Returns:
all of the ActionListeners added or an empty array if no listeners have been added
Since:
1.4

fireActionPerformed

protected void fireActionPerformed()
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created. The listener list is processed in last to first order.

See Also:
EventListenerList

setActionCommand

public void setActionCommand(String command)
Sets the command string used for action events.

Parameters:
command - the command string

setAction

public void setAction(Action a)
Sets the Action for the ActionEvent source. The new Action replaces any previously set Action but does not affect ActionListeners independently added with addActionListener. If the Action is already a registered ActionListener for the ActionEvent source, it is not re-registered.

Setting the Action results in immediately changing all the properties described in Swing Components Supporting Action. Subsequently, the textfield's properties are automatically updated as the Action's properties change.

This method uses three other methods to set and help track the Action's property values. It uses the configurePropertiesFromAction method to immediately change the textfield's properties. To track changes in the Action's property values, this method registers the PropertyChangeListener returned by createActionPropertyChangeListener. The default PropertyChangeListener invokes the actionPropertyChanged method when a property in the Action changes.

Parameters:
a - the Action for the JTextField, or null
Since:
1.3
See Also:
Action,
getAction(),
configurePropertiesFromAction(javax.swing.Action),
createActionPropertyChangeListener(javax.swing.Action),
actionPropertyChanged(javax.swing.Action, java.lang.String)

getAction

public Action getAction()
Returns the currently set Action for this ActionEvent source, or null if no Action is set.

Returns:
the Action for this ActionEvent source, or null
Since:
1.3
See Also:
Action, setAction(javax.swing.Action)

configurePropertiesFromAction

protected void configurePropertiesFromAction(Action a)
Sets the properties on this textfield to match those in the specified Action. Refer to Swing Components Supporting Action for more details as to which properties this sets.

Parameters:
a - the Action from which to get the properties, or null
Since:
1.3
See Also:
Action, setAction(javax.swing.Action)

actionPropertyChanged

protected void actionPropertyChanged(Action action,
                                     String propertyName)
Updates the textfield's state in response to property changes in associated action. This method is invoked from the PropertyChangeListener returned from createActionPropertyChangeListener. Subclasses do not normally need to invoke this. Subclasses that support additional Action properties should override this and configurePropertiesFromAction.

Refer to the table at Swing Components Supporting Action for a list of the properties this method sets.

Parameters:
action - the Action associated with this textfield
propertyName - the name of the property that changed
Since:
1.6
See Also:
Action, configurePropertiesFromAction(javax.swing.Action)

createActionPropertyChangeListener

protected PropertyChangeListener createActionPropertyChangeListener(Action a)
Creates and returns a PropertyChangeListener that is responsible for listening for changes from the specified Action and updating the appropriate properties.

Warning: If you subclass this do not create an anonymous inner class. If you do the lifetime of the textfield will be tied to that of the Action.

Parameters:
a - the textfield's action
Since:
1.3
See Also:
Action, setAction(javax.swing.Action)

getActions

public Action[] getActions()
Fetches the command list for the editor. This is the list of commands supported by the plugged-in UI augmented by the collection of commands that the editor itself supports. These are useful for binding to events, such as in a keymap.

Overrides:
getActions in class JTextComponent
Returns:
the command list

postActionEvent

public void postActionEvent()
Processes action events occurring on this textfield by dispatching them to any registered ActionListener objects. This is normally called by the controller registered with textfield.

getHorizontalVisibility

public BoundedRangeModel getHorizontalVisibility()
Gets the visibility of the text field. This can be adjusted to change the location of the visible area if the size of the field is greater than the area that was allocated to the field.

The fields look-and-feel implementation manages the values of the minimum, maximum, and extent properties on the BoundedRangeModel.

Returns:
the visibility
See Also:
BoundedRangeModel

getScrollOffset

public int getScrollOffset()
Gets the scroll offset, in pixels.

Returns:
the offset >= 0

setScrollOffset

public void setScrollOffset(int scrollOffset)
Sets the scroll offset, in pixels.

Parameters:
scrollOffset - the offset >= 0

scrollRectToVisible

public void scrollRectToVisible(Rectangle r)
Scrolls the field left or right.

Overrides:
scrollRectToVisible in class JComponent
Parameters:
r - the region to scroll
See Also:
JViewport

paramString

protected String paramString()
Returns a string representation of this JTextField. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JTextComponent
Returns:
a string representation of this JTextField

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JTextField. For JTextFields, the AccessibleContext takes the form of an AccessibleJTextField. A new AccessibleJTextField instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JTextComponent
Returns:
an AccessibleJTextField that serves as the AccessibleContext of this JTextField
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTextField.AccessibleJTextField

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTextField.AccessibleJTextField

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.text.JTextComponent.AccessibleJTextComponent
                        extended by  javax.swing.JTextField.AccessibleJTextField
All Implemented Interfaces:
Serializable, EventListener, AccessibleAction, AccessibleComponent, AccessibleEditableText, AccessibleExtendedComponent, AccessibleExtendedText, AccessibleText, CaretListener, DocumentListener
Direct Known Subclasses:
JPasswordField.AccessibleJPasswordField
Enclosing class:
JTextField
protected class JTextField.AccessibleJTextField
extends JTextComponent.AccessibleJTextComponent

This class implements accessibility support for the JTextField class. It provides an implementation of the Java Accessibility API appropriate to text field user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Fields inherited from interface javax.accessibility.AccessibleExtendedText
ATTRIBUTE_RUN, LINE
Constructor Summary
protected JTextField.AccessibleJTextField()
Method Summary
 AccessibleStateSet getAccessibleStateSet()
Gets the state set of this object.
Methods inherited from class javax.swing.text.JTextComponent.AccessibleJTextComponent
caretUpdate, changedUpdate, cut, delete, doAccessibleAction, getAccessibleAction, getAccessibleActionCount, getAccessibleActionDescription, getAccessibleEditableText, getAccessibleRole, getAccessibleText, getAfterIndex, getAtIndex, getBeforeIndex, getCaretPosition, getCharacterAttribute, getCharacterBounds, getCharCount, getIndexAtPoint, getSelectedText, getSelectionEnd, getSelectionStart, getTextBounds, getTextRange, getTextSequenceAfter, getTextSequenceAt, getTextSequenceBefore, insertTextAtIndex, insertUpdate, paste, removeUpdate, replaceText, selectText, setAttributes, setTextContents
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JTextField.AccessibleJTextField

protected JTextField.AccessibleJTextField()
Method Detail

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Gets the state set of this object.

Overrides:
getAccessibleStateSet in class JTextComponent.AccessibleJTextComponent
Returns:
an instance of AccessibleStateSet describing the states of the object
See Also:
AccessibleState
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTextPane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTextPane

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.text.JTextComponent
                    extended by  javax.swing.JEditorPane
                        extended by  javax.swing.JTextPane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable
public class JTextPane
extends JEditorPane

A text component that can be marked up with attributes that are represented graphically. You can find how-to information and examples of using text panes in Using Text Components, a section in The Java Tutorial.

This component models paragraphs that are composed of runs of character level attributes. Each paragraph may have a logical style attached to it which contains the default attributes to use if not overridden by attributes set on the paragraph or character run. Components and images may be embedded in the flow of text.

Newlines
For a discussion on how newlines are handled, see DefaultEditorKit.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
StyledEditorKit

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JEditorPane
JEditorPane.AccessibleJEditorPane, JEditorPane.AccessibleJEditorPaneHTML, JEditorPane.JEditorPaneAccessibleHypertextSupport
Nested classes/interfaces inherited from class javax.swing.text.JTextComponent
JTextComponent.AccessibleJTextComponent, JTextComponent.DropLocation, JTextComponent.KeyBinding
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JEditorPane
HONOR_DISPLAY_PROPERTIES, W3C_LENGTH_UNITS
Fields inherited from class javax.swing.text.JTextComponent
DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JTextPane()
Creates a new JTextPane.
JTextPane(StyledDocument doc)
Creates a new JTextPane, with a specified document model.
Method Summary
Style | addStyle(String nm, Style parent) Adds a new style into the logical style hierarchy.
protected EditorKit | createDefaultEditorKit() Creates the EditorKit to use by default.
AttributeSet | getCharacterAttributes() Fetches the character attributes in effect at the current location of the caret, or null.
MutableAttributeSet | getInputAttributes() Gets the input attributes for the pane.
Style | getLogicalStyle() Fetches the logical style assigned to the paragraph represented by the current position of the caret, or null.
AttributeSet | getParagraphAttributes() Fetches the current paragraph attributes in effect at the location of the caret, or null if none.
Style | getStyle(String nm) Fetches a named non-null style previously added.
StyledDocument | getStyledDocument() Fetches the model associated with the editor.
protected StyledEditorKit | getStyledEditorKit() Gets the editor kit.
String | getUIClassID() Returns the class ID for the UI.
void | insertComponent(Component c) Inserts a component into the document as a replacement for the currently selected content.
void | insertIcon(Icon g) Inserts an icon into the document as a replacement for the currently selected content.
protected String | paramString() Returns a string representation of this JTextPane.
void | removeStyle(String nm) Removes a named non-null style previously added to the document.
void | replaceSelection(String content) Replaces the currently selected content with new content represented by the given string.
void | setCharacterAttributes(AttributeSet attr, boolean replace) Applies the given attributes to character content.
void | setDocument(Document doc) Associates the editor with a text document.
void | setEditorKit(EditorKit kit) Sets the currently installed kit for handling content.
void | setLogicalStyle(Style s) Sets the logical style to use for the paragraph at the current caret position.
void | setParagraphAttributes(AttributeSet attr, boolean replace) Applies the given attributes to paragraphs.
void | setStyledDocument(StyledDocument doc) Associates the editor with a text document.
Methods inherited from class javax.swing.JEditorPane
addHyperlinkListener, createEditorKitForContentType, fireHyperlinkUpdate, getAccessibleContext, getContentType, getEditorKit, getEditorKitClassNameForContentType, getEditorKitForContentType, getHyperlinkListeners, getPage, getPreferredSize, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getStream, getText, read, registerEditorKitForContentType, registerEditorKitForContentType, removeHyperlinkListener, scrollToReference, setContentType, setEditorKitForContentType, setPage, setPage, setText
Methods inherited from class javax.swing.text.JTextComponent
addCaretListener, addInputMethodListener, addKeymap, copy, cut, fireCaretUpdate, getActions, getCaret, getCaretColor, getCaretListeners, getCaretPosition, getDisabledTextColor, getDocument, getDragEnabled, getDropLocation, getDropMode, getFocusAccelerator, getHighlighter, getInputMethodRequests, getKeymap, getKeymap, getMargin, getNavigationFilter, getPreferredScrollableViewportSize, getPrintable, getScrollableBlockIncrement, getScrollableUnitIncrement, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getToolTipText, getUI, isEditable, loadKeymap, modelToView, moveCaretPosition, paste, print, print, print, processInputMethodEvent, read, removeCaretListener, removeKeymap, removeNotify, select, selectAll, setCaret, setCaretColor, setCaretPosition, setComponentOrientation, setDisabledTextColor, setDragEnabled, setDropMode, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setUI, updateUI, viewToModel, write
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JTextPane

public JTextPane()
Creates a new JTextPane. A new instance of StyledEditorKit is created and set, and the document model set to null.

JTextPane

public JTextPane(StyledDocument doc)
Creates a new JTextPane, with a specified document model. A new instance of javax.swing.text.StyledEditorKit is created and set.

Parameters:
doc - the document model
Method Detail

getUIClassID

public String getUIClassID()
Returns the class ID for the UI.

Overrides:
getUIClassID in class JEditorPane
Returns:
the string "TextPaneUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

setDocument

public void setDocument(Document doc)
Associates the editor with a text document. This must be a StyledDocument.

Overrides:
setDocument in class JTextComponent
Parameters:
doc - the document to display/edit
Throws:
IllegalArgumentException - if doc can't be narrowed to a StyledDocument which is the required type of model for this text component
See Also:
JTextComponent.getDocument()

setStyledDocument

public void setStyledDocument(StyledDocument doc)
Associates the editor with a text document. The currently registered factory is used to build a view for the document, which gets displayed by the editor.

Parameters:
doc - the document to display/edit

getStyledDocument

public StyledDocument getStyledDocument()
Fetches the model associated with the editor.

Returns:
the model

replaceSelection

public void replaceSelection(String content)
Replaces the currently selected content with new content represented by the given string. If there is no selection this amounts to an insert of the given text. If there is no replacement text this amounts to a removal of the current selection. The replacement text will have the attributes currently defined for input at the point of insertion. If the document is not editable, beep and return.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Overrides:
replaceSelection in class JEditorPane
Parameters:
content - the content to replace the selection with

insertComponent

public void insertComponent(Component c)
Inserts a component into the document as a replacement for the currently selected content. If there is no selection the component is effectively inserted at the current position of the caret. This is represented in the associated document as an attribute of one character of content.

The component given is the actual component used by the JTextPane. Since components cannot be a child of more than one container, this method should not be used in situations where the model is shared by text components.

The component is placed relative to the text baseline according to the value returned by Component.getAlignmentY. For Swing components this value can be conveniently set using the method JComponent.setAlignmentY. For example, setting a value of 0.75 will cause 75 percent of the component to be above the baseline, and 25 percent of the component to be below the baseline.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Parameters:
c - the component to insert

insertIcon

public void insertIcon(Icon g)
Inserts an icon into the document as a replacement for the currently selected content. If there is no selection the icon is effectively inserted at the current position of the caret. This is represented in the associated document as an attribute of one character of content.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Parameters:
g - the icon to insert
See Also:
Icon

addStyle

public Style addStyle(String nm,
                      Style parent)
Adds a new style into the logical style hierarchy. Style attributes resolve from bottom up so an attribute specified in a child will override an attribute specified in the parent.

Parameters:
nm - the name of the style (must be unique within the collection of named styles). The name may be null if the style is unnamed, but the caller is responsible for managing the reference returned as an unnamed style can't be fetched by name. An unnamed style may be useful for things like character attribute overrides such as found in a style run.
parent - the parent style. This may be null if unspecified attributes need not be resolved in some other style.
Returns:
the new Style

removeStyle

public void removeStyle(String nm)
Removes a named non-null style previously added to the document.

Parameters:
nm - the name of the style to remove

getStyle

public Style getStyle(String nm)
Fetches a named non-null style previously added.

Parameters:
nm - the name of the style
Returns:
the Style

setLogicalStyle

public void setLogicalStyle(Style s)
Sets the logical style to use for the paragraph at the current caret position. If attributes aren't explicitly set for character and paragraph attributes they will resolve through the logical style assigned to the paragraph, which in term may resolve through some hierarchy completely independent of the element hierarchy in the document.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Parameters:
s - the logical style to assign to the paragraph, or null for no style

getLogicalStyle

public Style getLogicalStyle()
Fetches the logical style assigned to the paragraph represented by the current position of the caret, or null.

Returns:
the Style

getCharacterAttributes

public AttributeSet getCharacterAttributes()
Fetches the character attributes in effect at the current location of the caret, or null.

Returns:
the attributes, or null

setCharacterAttributes

public void setCharacterAttributes(AttributeSet attr,
                                   boolean replace)
Applies the given attributes to character content. If there is a selection, the attributes are applied to the selection range. If there is no selection, the attributes are applied to the input attribute set which defines the attributes for any new text that gets inserted.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Parameters:
attr - the attributes
replace - if true, then replace the existing attributes first

getParagraphAttributes

public AttributeSet getParagraphAttributes()
Fetches the current paragraph attributes in effect at the location of the caret, or null if none.

Returns:
the attributes

setParagraphAttributes

public void setParagraphAttributes(AttributeSet attr,
                                   boolean replace)
Applies the given attributes to paragraphs. If there is a selection, the attributes are applied to the paragraphs that intersect the selection. If there is no selection, the attributes are applied to the paragraph at the current caret position.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Parameters:
attr - the non-null attributes
replace - if true, replace the existing attributes first

getInputAttributes

public MutableAttributeSet getInputAttributes()
Gets the input attributes for the pane.

Returns:
the attributes

getStyledEditorKit

protected final StyledEditorKit getStyledEditorKit()
Gets the editor kit.

Returns:
the editor kit

createDefaultEditorKit

protected EditorKit createDefaultEditorKit()
Creates the EditorKit to use by default. This is implemented to return javax.swing.text.StyledEditorKit.

Overrides:
createDefaultEditorKit in class JEditorPane
Returns:
the editor kit

setEditorKit

public final void setEditorKit(EditorKit kit)
Sets the currently installed kit for handling content. This is the bound property that establishes the content type of the editor.

Overrides:
setEditorKit in class JEditorPane
Parameters:
kit - the desired editor behavior
Throws:
IllegalArgumentException - if kit is not a StyledEditorKit
See Also:
JEditorPane.getEditorKit()

paramString

protected String paramString()
Returns a string representation of this JTextPane. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JEditorPane
Returns:
a string representation of this JTextPane
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JToggleButton

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JToggleButton

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.AbstractButton
                    extended by  javax.swing.JToggleButton
All Implemented Interfaces:
ImageObserver, ItemSelectable, MenuContainer, Serializable, Accessible, SwingConstants
Direct Known Subclasses:
JCheckBox, JRadioButton
public class JToggleButton
extends AbstractButton
implements Accessible

An implementation of a two-state button. The JRadioButton and JCheckBox classes are subclasses of this class. For information on using them see How to Use Buttons, Check Boxes, and Radio Buttons, a section in The Java Tutorial.

Buttons can be configured, and to some degree controlled, by Actions. Using an Action with a button has many benefits beyond directly configuring a button. Refer to Swing Components Supporting Action for more details, and you can find more information in How to Use Actions, a section in The Java Tutorial.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JRadioButton, JCheckBox

Nested Class Summary
protected class | JToggleButton.AccessibleJToggleButton This class implements accessibility support for the JToggleButton class.
static class | JToggleButton.ToggleButtonModel The ToggleButton model
Nested classes/interfaces inherited from class javax.swing.AbstractButton
AbstractButton.AccessibleAbstractButton, AbstractButton.ButtonChangeListener
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.AbstractButton
actionListener, BORDER_PAINTED_CHANGED_PROPERTY, changeEvent, changeListener, CONTENT_AREA_FILLED_CHANGED_PROPERTY, DISABLED_ICON_CHANGED_PROPERTY, DISABLED_SELECTED_ICON_CHANGED_PROPERTY, FOCUS_PAINTED_CHANGED_PROPERTY, HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY, HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY, ICON_CHANGED_PROPERTY, itemListener, MARGIN_CHANGED_PROPERTY, MNEMONIC_CHANGED_PROPERTY, model, MODEL_CHANGED_PROPERTY, PRESSED_ICON_CHANGED_PROPERTY, ROLLOVER_ENABLED_CHANGED_PROPERTY, ROLLOVER_ICON_CHANGED_PROPERTY, ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY, SELECTED_ICON_CHANGED_PROPERTY, TEXT_CHANGED_PROPERTY, VERTICAL_ALIGNMENT_CHANGED_PROPERTY, VERTICAL_TEXT_POSITION_CHANGED_PROPERTY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JToggleButton()
Creates an initially unselected toggle button without setting the text or image.
JToggleButton(Action a)
Creates a toggle button where properties are taken from the Action supplied.
JToggleButton(Icon icon)
Creates an initially unselected toggle button with the specified image but no text.
JToggleButton(Icon icon, boolean selected)
Creates a toggle button with the specified image and selection state, but no text.
JToggleButton(String text)
Creates an unselected toggle button with the specified text.
JToggleButton(String text, boolean selected)
Creates a toggle button with the specified text and selection state.
JToggleButton(String text, Icon icon)
Creates a toggle button that has the specified text and image, and that is initially unselected.
JToggleButton(String text, Icon icon, boolean selected)
Creates a toggle button with the specified text, image, and selection state.
Method Summary
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JToggleButton.
String | getUIClassID() Returns a string that specifies the name of the l&f class that renders this component.
protected String | paramString() Returns a string representation of this JToggleButton.
void | updateUI() Resets the UI property to a value from the current look and feel.
Methods inherited from class javax.swing.AbstractButton
actionPropertyChanged, addActionListener, addChangeListener, addImpl, addItemListener, checkHorizontalKey, checkVerticalKey, configurePropertiesFromAction, createActionListener, createActionPropertyChangeListener, createChangeListener, createItemListener, doClick, doClick, fireActionPerformed, fireItemStateChanged, fireStateChanged, getAction, getActionCommand, getActionListeners, getChangeListeners, getDisabledIcon, getDisabledSelectedIcon, getDisplayedMnemonicIndex, getHideActionText, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getItemListeners, getLabel, getMargin, getMnemonic, getModel, getMultiClickThreshhold, getPressedIcon, getRolloverIcon, getRolloverSelectedIcon, getSelectedIcon, getSelectedObjects, getText, getUI, getVerticalAlignment, getVerticalTextPosition, imageUpdate, init, isBorderPainted, isContentAreaFilled, isFocusPainted, isRolloverEnabled, isSelected, paintBorder, removeActionListener, removeChangeListener, removeItemListener, removeNotify, setAction, setActionCommand, setBorderPainted, setContentAreaFilled, setDisabledIcon, setDisabledSelectedIcon, setDisplayedMnemonicIndex, setEnabled, setFocusPainted, setHideActionText, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabel, setLayout, setMargin, setMnemonic, setMnemonic, setModel, setMultiClickThreshhold, setPressedIcon, setRolloverEnabled, setRolloverIcon, setRolloverSelectedIcon, setSelected, setSelectedIcon, setText, setUI, setVerticalAlignment, setVerticalTextPosition
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JToggleButton

public JToggleButton()
Creates an initially unselected toggle button without setting the text or image.

JToggleButton

public JToggleButton(Icon icon)
Creates an initially unselected toggle button with the specified image but no text.

Parameters:
icon - the image that the button should display

JToggleButton

public JToggleButton(Icon icon,
                     boolean selected)
Creates a toggle button with the specified image and selection state, but no text.

Parameters:
icon - the image that the button should display
selected - if true, the button is initially selected; otherwise, the button is initially unselected

JToggleButton

public JToggleButton(String text)
Creates an unselected toggle button with the specified text.

Parameters:
text - the string displayed on the toggle button

JToggleButton

public JToggleButton(String text,
                     boolean selected)
Creates a toggle button with the specified text and selection state.

Parameters:
text - the string displayed on the toggle button
selected - if true, the button is initially selected; otherwise, the button is initially unselected

JToggleButton

public JToggleButton(Action a)
Creates a toggle button where properties are taken from the Action supplied.

Since:
1.3

JToggleButton

public JToggleButton(String text,
                     Icon icon)
Creates a toggle button that has the specified text and image, and that is initially unselected.

Parameters:
text - the string displayed on the button
icon - the image that the button should display

JToggleButton

public JToggleButton(String text,
                     Icon icon,
                     boolean selected)
Creates a toggle button with the specified text, image, and selection state.

Parameters:
text - the text of the toggle button
icon - the image that the button should display
selected - if true, the button is initially selected; otherwise, the button is initially unselected
Method Detail

updateUI

public void updateUI()
Resets the UI property to a value from the current look and feel.

Overrides:
updateUI in class AbstractButton
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns a string that specifies the name of the l&f class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
String "ToggleButtonUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

paramString

protected String paramString()
Returns a string representation of this JToggleButton. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class AbstractButton
Returns:
a string representation of this JToggleButton.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JToggleButton. For toggle buttons, the AccessibleContext takes the form of an AccessibleJToggleButton. A new AccessibleJToggleButton instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJToggleButton that serves as the AccessibleContext of this JToggleButton
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JToggleButton.AccessibleJToggleButton

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JToggleButton.AccessibleJToggleButton

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.AbstractButton.AccessibleAbstractButton
                        extended by  javax.swing.JToggleButton.AccessibleJToggleButton
All Implemented Interfaces:
ItemListener, Serializable, EventListener, AccessibleAction, AccessibleComponent, AccessibleExtendedComponent, AccessibleText, AccessibleValue
Direct Known Subclasses:
JCheckBox.AccessibleJCheckBox, JRadioButton.AccessibleJRadioButton
Enclosing class:
JToggleButton
protected class JToggleButton.AccessibleJToggleButton
extends AbstractButton.AccessibleAbstractButton
implements ItemListener

This class implements accessibility support for the JToggleButton class. It provides an implementation of the Java Accessibility API appropriate to toggle button user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Constructor Summary
JToggleButton.AccessibleJToggleButton()
Method Summary
AccessibleRole | getAccessibleRole() Get the role of this object.
void | itemStateChanged(ItemEvent e) Fire accessible property change events when the state of the toggle button changes.
Methods inherited from class javax.swing.AbstractButton.AccessibleAbstractButton
doAccessibleAction, getAccessibleAction, getAccessibleActionCount, getAccessibleActionDescription, getAccessibleIcon, getAccessibleKeyBinding, getAccessibleName, getAccessibleRelationSet, getAccessibleStateSet, getAccessibleText, getAccessibleValue, getAfterIndex, getAtIndex, getBeforeIndex, getCaretPosition, getCharacterAttribute, getCharacterBounds, getCharCount, getCurrentAccessibleValue, getIndexAtPoint, getMaximumAccessibleValue, getMinimumAccessibleValue, getSelectedText, getSelectionEnd, getSelectionStart, getTitledBorderText, getToolTipText, setCurrentAccessibleValue
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getBorderTitle, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleEditableText, getAccessibleSelection, getAccessibleTable, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JToggleButton.AccessibleJToggleButton

public JToggleButton.AccessibleJToggleButton()
Method Detail

itemStateChanged

public void itemStateChanged(ItemEvent e)
Fire accessible property change events when the state of the toggle button changes.

Specified by:
itemStateChanged in interface ItemListener

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JToggleButton.ToggleButtonModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JToggleButton.ToggleButtonModel

java.lang.Object
    extended by  javax.swing.DefaultButtonModel
        extended by  javax.swing.JToggleButton.ToggleButtonModel
All Implemented Interfaces:
ItemSelectable, Serializable, ButtonModel
Enclosing class:
JToggleButton
public static class JToggleButton.ToggleButtonModel
extends DefaultButtonModel

The ToggleButton model

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class javax.swing.DefaultButtonModel
actionCommand, ARMED, changeEvent, ENABLED, group, listenerList, mnemonic, PRESSED, ROLLOVER, SELECTED, stateMask
Constructor Summary
JToggleButton.ToggleButtonModel()
Creates a new ToggleButton Model
Method Summary
boolean | isSelected() Checks if the button is selected.
void | setPressed(boolean b) Sets the pressed state of the toggle button.
void | setSelected(boolean b) Sets the selected state of the button.
Methods inherited from class javax.swing.DefaultButtonModel
addActionListener, addChangeListener, addItemListener, fireActionPerformed, fireItemStateChanged, fireStateChanged, getActionCommand, getActionListeners, getChangeListeners, getGroup, getItemListeners, getListeners, getMnemonic, getSelectedObjects, isArmed, isEnabled, isPressed, isRollover, removeActionListener, removeChangeListener, removeItemListener, setActionCommand, setArmed, setEnabled, setGroup, setMnemonic, setRollover
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JToggleButton.ToggleButtonModel

public JToggleButton.ToggleButtonModel()
Creates a new ToggleButton Model

Method Detail

isSelected

public boolean isSelected()
Checks if the button is selected.

Specified by:
isSelected in interface ButtonModel
Overrides:
isSelected in class DefaultButtonModel
Returns:
true if the button is selected

setSelected

public void setSelected(boolean b)
Sets the selected state of the button.

Specified by:
setSelected in interface ButtonModel
Overrides:
setSelected in class DefaultButtonModel
Parameters:
b - true selects the toggle button, false deselects the toggle button.

setPressed

public void setPressed(boolean b)
Sets the pressed state of the toggle button.

Specified by:
setPressed in interface ButtonModel
Overrides:
setPressed in class DefaultButtonModel
Parameters:
b - whether or not the button should be pressed
See Also:
ButtonModel.isPressed()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JToolBar

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JToolBar

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JToolBar
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, SwingConstants
public class JToolBar
extends JComponent
implements SwingConstants, Accessible

JToolBar provides a component that is useful for displaying commonly used Actions or controls. For examples and information on using tool bars see How to Use Tool Bars, a section in The Java Tutorial.

With most look and feels, the user can drag out a tool bar into a separate window (unless the floatable property is set to false). For drag-out to work correctly, it is recommended that you add JToolBar instances to one of the four "sides" of a container whose layout manager is a BorderLayout, and do not add children to any of the other four "sides".

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
Action

Nested Class Summary
protected class | JToolBar.AccessibleJToolBar This class implements accessibility support for the JToolBar class.
static class | JToolBar.Separator A toolbar-specific separator.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JToolBar()
Creates a new tool bar; orientation defaults to HORIZONTAL.
JToolBar(int orientation)
Creates a new tool bar with the specified orientation.
JToolBar(String name)
Creates a new tool bar with the specified name.
JToolBar(String name, int orientation)
Creates a new tool bar with a specified name and orientation.
Method Summary
JButton | add(Action a) Adds a new JButton which dispatches the action.
protected void | addImpl(Component comp, Object constraints, int index) If a JButton is being added, it is initially set to be disabled.
void | addSeparator() Appends a separator of default size to the end of the tool bar.
void | addSeparator(Dimension size) Appends a separator of a specified size to the end of the tool bar.
protected PropertyChangeListener | createActionChangeListener(JButton b) Returns a properly configured PropertyChangeListener which updates the control as changes to the Action occur, or null if the default property change listener for the control is desired.
protected JButton | createActionComponent(Action a) Factory method which creates the JButton for Actions added to the JToolBar.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JToolBar.
Component | getComponentAtIndex(int i) Returns the component at the specified index.
int | getComponentIndex(Component c) Returns the index of the specified component.
Insets | getMargin() Returns the margin between the tool bar's border and its buttons.
int | getOrientation() Returns the current orientation of the tool bar.
ToolBarUI | getUI() Returns the tool bar's current UI.
String | getUIClassID() Returns the name of the L&F class that renders this component.
boolean | isBorderPainted() Gets the borderPainted property.
boolean | isFloatable() Gets the floatable property.
boolean | isRollover() Returns the rollover state.
protected void | paintBorder(Graphics g) Paints the tool bar's border if the borderPainted property is true.
protected String | paramString() Returns a string representation of this JToolBar.
void | setBorderPainted(boolean b) Sets the borderPainted property, which is true if the border should be painted.
void | setFloatable(boolean b) Sets the floatable property, which must be true for the user to move the tool bar.
void | setLayout(LayoutManager mgr) Sets the layout manager for this container.
void | setMargin(Insets m) Sets the margin between the tool bar's border and its buttons.
void | setOrientation(int o) Sets the orientation of the tool bar.
void | setRollover(boolean rollover) Sets the rollover state of this toolbar.
void | setUI(ToolBarUI ui) Sets the L&F object that renders this component.
void | updateUI() Notification from the UIFactory that the L&F has changed.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JToolBar

public JToolBar()
Creates a new tool bar; orientation defaults to HORIZONTAL.

JToolBar

public JToolBar(int orientation)
Creates a new tool bar with the specified orientation. The orientation must be either HORIZONTAL or VERTICAL.

Parameters:
orientation - the orientation desired

JToolBar

public JToolBar(String name)
Creates a new tool bar with the specified name. The name is used as the title of the undocked tool bar. The default orientation is HORIZONTAL.

Parameters:
name - the name of the tool bar
Since:
1.3

JToolBar

public JToolBar(String name,
                int orientation)
Creates a new tool bar with a specified name and orientation. All other constructors call this constructor. If orientation is an invalid value, an exception will be thrown.

Parameters:
name - the name of the tool bar
orientation - the initial orientation -- it must be either HORIZONTAL or VERTICAL
Throws:
IllegalArgumentException - if orientation is neither HORIZONTAL nor VERTICAL
Since:
1.3
Method Detail

getUI

public ToolBarUI getUI()
Returns the tool bar's current UI.

See Also:
setUI(javax.swing.plaf.ToolBarUI)

setUI

public void setUI(ToolBarUI ui)
Sets the L&F object that renders this component.

Parameters:
ui - the ToolBarUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Notification from the UIFactory that the L&F has changed. Called to replace the UI with the latest version from the UIFactory.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "ToolBarUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

getComponentIndex

public int getComponentIndex(Component c)
Returns the index of the specified component. (Note: Separators occupy index positions.)

Parameters:
c - the Component to find
Returns:
an integer indicating the component's position, where 0 is first

getComponentAtIndex

public Component getComponentAtIndex(int i)
Returns the component at the specified index.

Parameters:
i - the component's position, where 0 is first
Returns:
the Component at that position, or null for an invalid index

setMargin

public void setMargin(Insets m)
Sets the margin between the tool bar's border and its buttons. Setting to null causes the tool bar to use the default margins. The tool bar's default Border object uses this value to create the proper margin. However, if a non-default border is set on the tool bar, it is that Border object's responsibility to create the appropriate margin space (otherwise this property will effectively be ignored).

Parameters:
m - an Insets object that defines the space between the border and the buttons
See Also:
Insets

getMargin

public Insets getMargin()
Returns the margin between the tool bar's border and its buttons.

Returns:
an Insets object containing the margin values
See Also:
Insets

isBorderPainted

public boolean isBorderPainted()
Gets the borderPainted property.

Returns:
the value of the borderPainted property
See Also:
setBorderPainted(boolean)

setBorderPainted

public void setBorderPainted(boolean b)
Sets the borderPainted property, which is true if the border should be painted. The default value for this property is true. Some look and feels might not implement painted borders; they will ignore this property.

Parameters:
b - if true, the border is painted
See Also:
isBorderPainted()

paintBorder

protected void paintBorder(Graphics g)
Paints the tool bar's border if the borderPainted property is true.

Overrides:
paintBorder in class JComponent
Parameters:
g - the Graphics context in which the painting is done
See Also:
JComponent.paint(java.awt.Graphics), JComponent.setBorder(javax.swing.border.Border)

isFloatable

public boolean isFloatable()
Gets the floatable property.

Returns:
the value of the floatable property
See Also:
setFloatable(boolean)

setFloatable

public void setFloatable(boolean b)
Sets the floatable property, which must be true for the user to move the tool bar. Typically, a floatable tool bar can be dragged into a different position within the same container or out into its own window. The default value of this property is true. Some look and feels might not implement floatable tool bars; they will ignore this property.

Parameters:
b - if true, the tool bar can be moved; false otherwise
See Also:
isFloatable()

getOrientation

public int getOrientation()
Returns the current orientation of the tool bar. The value is either HORIZONTAL or VERTICAL.

Returns:
an integer representing the current orientation -- either HORIZONTAL or VERTICAL
See Also:
setOrientation(int)

setOrientation

public void setOrientation(int o)
Sets the orientation of the tool bar. The orientation must have either the value HORIZONTAL or VERTICAL. If orientation is an invalid value, an exception will be thrown.

Parameters:
o - the new orientation -- either HORIZONTAL or VERTICAL
Throws:
IllegalArgumentException - if orientation is neither HORIZONTAL nor VERTICAL
See Also:
getOrientation()

setRollover

public void setRollover(boolean rollover)
Sets the rollover state of this toolbar. If the rollover state is true then the border of the toolbar buttons will be drawn only when the mouse pointer hovers over them. The default value of this property is false.

The implementation of a look and feel may choose to ignore this property.

Parameters:
rollover - true for rollover toolbar buttons; otherwise false
Since:
1.4

isRollover

public boolean isRollover()
Returns the rollover state.

Returns:
true if rollover toolbar buttons are to be drawn; otherwise false
Since:
1.4
See Also:
setRollover(boolean)

addSeparator

public void addSeparator()
Appends a separator of default size to the end of the tool bar. The default size is determined by the current look and feel.

addSeparator

public void addSeparator(Dimension size)
Appends a separator of a specified size to the end of the tool bar.

Parameters:
size - the Dimension of the separator

add

public JButton add(Action a)
Adds a new JButton which dispatches the action.

Parameters:
a - the Action object to add as a new menu item
Returns:
the new button which dispatches the action

createActionComponent

protected JButton createActionComponent(Action a)
Factory method which creates the JButton for Actions added to the JToolBar. The default name is empty if a null action is passed.

Parameters:
a - the Action for the button to be added
Returns:
the newly created button
Since:
1.3
See Also:
Action

createActionChangeListener

protected PropertyChangeListener createActionChangeListener(JButton b)
Returns a properly configured PropertyChangeListener which updates the control as changes to the Action occur, or null if the default property change listener for the control is desired.

Returns:
null

addImpl

protected void addImpl(Component comp,
                       Object constraints,
                       int index)
If a JButton is being added, it is initially set to be disabled.

Overrides:
addImpl in class Container
Parameters:
comp - the component to be enhanced
constraints - the constraints to be enforced on the component
index - the index of the component
See Also:
Container.add(Component),
Container.add(Component, int),
Container.add(Component, java.lang.Object),
LayoutManager,
LayoutManager2

paramString

protected String paramString()
Returns a string representation of this JToolBar. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JToolBar.

setLayout

public void setLayout(LayoutManager mgr)
Description copied from class: Container
Sets the layout manager for this container.

Overrides:
setLayout in class Container
Parameters:
mgr - the specified layout manager
See Also:
Container.doLayout(), Container.getLayout()

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JToolBar. For tool bars, the AccessibleContext takes the form of an AccessibleJToolBar. A new AccessibleJToolBar instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJToolBar that serves as the AccessibleContext of this JToolBar
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JToolBar.AccessibleJToolBar

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JToolBar.AccessibleJToolBar

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JToolBar.AccessibleJToolBar
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent
Enclosing class:
JToolBar
protected class JToolBar.AccessibleJToolBar
extends JComponent.AccessibleJComponent

This class implements accessibility support for the JToolBar class. It provides an implementation of the Java Accessibility API appropriate to toolbar user-interface elements.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JToolBar.AccessibleJToolBar()
Method Summary
AccessibleRole | getAccessibleRole() Get the role of this object.
AccessibleStateSet | getAccessibleStateSet() Get the state of this object.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JToolBar.AccessibleJToolBar

protected JToolBar.AccessibleJToolBar()
Method Detail

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Get the state of this object.

Overrides:
getAccessibleStateSet in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleStateSet containing the current state set of the object
See Also:
AccessibleState

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JToolBar.Separator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JToolBar.Separator

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JSeparator
                    extended by  javax.swing.JToolBar.Separator
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, SwingConstants
Enclosing class:
JToolBar
public static class JToolBar.Separator
extends JSeparator

A toolbar-specific separator. An object with dimension but no contents used to divide buttons on a tool bar into groups.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JSeparator
JSeparator.AccessibleJSeparator
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JToolBar.Separator()
Creates a new toolbar separator with the default size as defined by the current look and feel.
JToolBar.Separator(Dimension size)
Creates a new toolbar separator with the specified size.
Method Summary
Dimension | getMaximumSize() Returns the maximum size for the separator.
Dimension | getMinimumSize() Returns the minimum size for the separator.
Dimension | getPreferredSize() Returns the preferred size for the separator.
Dimension | getSeparatorSize() Returns the size of the separator
String | getUIClassID() Returns the name of the L&F class that renders this component.
void | setSeparatorSize(Dimension size) Sets the size of the separator.
Methods inherited from class javax.swing.JSeparator
getAccessibleContext, getOrientation, getUI, paramString, setOrientation, setUI, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JToolBar.Separator

public JToolBar.Separator()
Creates a new toolbar separator with the default size as defined by the current look and feel.

JToolBar.Separator

public JToolBar.Separator(Dimension size)
Creates a new toolbar separator with the specified size.

Parameters:
size - the Dimension of the separator
Method Detail

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JSeparator
Returns:
the string "ToolBarSeparatorUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

setSeparatorSize

public void setSeparatorSize(Dimension size)
Sets the size of the separator.

Parameters:
size - the new Dimension of the separator

getSeparatorSize

public Dimension getSeparatorSize()
Returns the size of the separator

Returns:
the Dimension object containing the separator's size (This is a reference, NOT a copy!)

getMinimumSize

public Dimension getMinimumSize()
Returns the minimum size for the separator.

Overrides:
getMinimumSize in class JComponent
Returns:
the Dimension object containing the separator's minimum size
See Also:
JComponent.setMinimumSize(java.awt.Dimension), ComponentUI

getMaximumSize

public Dimension getMaximumSize()
Returns the maximum size for the separator.

Overrides:
getMaximumSize in class JComponent
Returns:
the Dimension object containing the separator's maximum size
See Also:
JComponent.setMaximumSize(java.awt.Dimension), ComponentUI

getPreferredSize

public Dimension getPreferredSize()
Returns the preferred size for the separator.

Overrides:
getPreferredSize in class JComponent
Returns:
the Dimension object containing the separator's preferred size
See Also:
JComponent.setPreferredSize(java.awt.Dimension), ComponentUI
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JToolTip

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JToolTip

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JToolTip
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public class JToolTip
extends JComponent
implements Accessible

Used to display a "Tip" for a Component. Typically components provide api to automate the process of using ToolTips. For example, any Swing component can use the JComponent setToolTipText method to specify the text for a standard tooltip. A component that wants to create a custom ToolTip display can override JComponent's createToolTip method and use a subclass of this class.

See How to Use Tool Tips in The Java Tutorial for further documentation.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JComponent.setToolTipText(java.lang.String), JComponent.createToolTip()

Nested Class Summary
protected  class JToolTip.AccessibleJToolTip
This class implements accessibility support for the JToolTip class.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JToolTip()
Creates a tool tip.
Method Summary
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JToolTip.
JComponent | getComponent() Returns the component the tooltip applies to.
String | getTipText() Returns the text that is shown when the tool tip is displayed.
ToolTipUI | getUI() Returns the L&F object that renders this component.
String | getUIClassID() Returns the name of the L&F class that renders this component.
protected String | paramString() Returns a string representation of this JToolTip.
void | setComponent(JComponent c) Specifies the component that the tooltip describes.
void | setTipText(String tipText) Sets the text to show when the tool tip is displayed.
void | updateUI() Resets the UI property to a value from the current look and feel.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JToolTip

public JToolTip()
Creates a tool tip.

Method Detail

getUI

public ToolTipUI getUI()
Returns the L&F object that renders this component.

Returns:
the ToolTipUI object that renders this component

updateUI

public void updateUI()
Resets the UI property to a value from the current look and feel.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "ToolTipUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

setTipText

public void setTipText(String tipText)
Sets the text to show when the tool tip is displayed. The string tipText may be null.

Parameters:
tipText - the String to display

getTipText

public String getTipText()
Returns the text that is shown when the tool tip is displayed. The returned value may be null.

Returns:
the String that is displayed

setComponent

public void setComponent(JComponent c)
Specifies the component that the tooltip describes. The component c may be null and will have no effect.

This is a bound property.

Parameters:
c - the JComponent being described
See Also:
JComponent.createToolTip()

getComponent

public JComponent getComponent()
Returns the component the tooltip applies to. The returned value may be null.

Returns:
the component that the tooltip describes
See Also:
JComponent.createToolTip()

paramString

protected String paramString()
Returns a string representation of this JToolTip. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JToolTip

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JToolTip. For tool tips, the AccessibleContext takes the form of an AccessibleJToolTip. A new AccessibleJToolTip instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJToolTip that serves as the AccessibleContext of this JToolTip
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JToolTip.AccessibleJToolTip

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JToolTip.AccessibleJToolTip

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JToolTip.AccessibleJToolTip
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent
Enclosing class:
JToolTip
protected class JToolTip.AccessibleJToolTip
extends JComponent.AccessibleJComponent

This class implements accessibility support for the JToolTip class. It provides an implementation of the Java Accessibility API appropriate to tool tip user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JToolTip.AccessibleJToolTip()
Method Summary
String | getAccessibleDescription() Get the accessible description of this object.
AccessibleRole | getAccessibleRole() Get the role of this object.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleKeyBinding, getAccessibleName, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JToolTip.AccessibleJToolTip

protected JToolTip.AccessibleJToolTip()
Method Detail

getAccessibleDescription

public String getAccessibleDescription()
Get the accessible description of this object.

Overrides:
getAccessibleDescription in class JComponent.AccessibleJComponent
Returns:
a localized String describing this object.
See Also:
AccessibleContext.setAccessibleDescription(java.lang.String)

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTree

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTree

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JTree
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable
public class JTree
extends JComponent
implements Scrollable, Accessible

A control that displays a set of hierarchical data as an outline. You can find task-oriented documentation and examples of using trees in How to Use Trees, a section in The Java Tutorial.

A specific node in a tree can be identified either by a TreePath (an object that encapsulates a node and all of its ancestors), or by its display row, where each row in the display area displays one node. An expanded node is a non-leaf node (as identified by TreeModel.isLeaf(node) returning false) that will displays its children when all its ancestors are expanded. A collapsed node is one which hides them. A hidden node is one which is under a collapsed ancestor. All of a viewable nodes parents are expanded, but may or may not be displayed. A displayed node is both viewable and in the display area, where it can be seen.

The following JTree methods use "visible" to mean "displayed":

  • isRootVisible()
  • setRootVisible()
  • scrollPathToVisible()
  • scrollRowToVisible()
  • getVisibleRowCount()
  • setVisibleRowCount()

The next group of JTree methods use "visible" to mean "viewable" (under an expanded parent):

  • isVisible()
  • makeVisible()

If you are interested in knowing when the selection changes implement the TreeSelectionListener interface and add the instance using the method addTreeSelectionListener. valueChanged will be invoked when the selection changes, that is if the user clicks twice on the same node valueChanged will only be invoked once.

If you are interested in detecting either double-click events or when a user clicks on a node, regardless of whether or not it was selected, we recommend you do the following:

 final JTree tree = ...;

 MouseListener ml = new MouseAdapter() {
     public void mousePressed(MouseEvent e) {
         int selRow = tree.getRowForLocation(e.getX(), e.getY());
         TreePath selPath = tree.getPathForLocation(e.getX(), e.getY());
         if(selRow != -1) {
             if(e.getClickCount() == 1) {
                 mySingleClick(selRow, selPath);
             }
             else if(e.getClickCount() == 2) {
                 myDoubleClick(selRow, selPath);
             }
         }
     }
 };
 tree.addMouseListener(ml);
NOTE: This example obtains both the path and row, but you only need to get the one you're interested in.

To use JTree to display compound nodes (for example, nodes containing both a graphic icon and text), subclass TreeCellRenderer and use setCellRenderer(javax.swing.tree.TreeCellRenderer) to tell the tree to use it. To edit such nodes, subclass TreeCellEditor and use setCellEditor(javax.swing.tree.TreeCellEditor).

Like all JComponent classes, you can use InputMap and ActionMap to associate an Action object with a KeyStroke and execute the action under specified conditions.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected class | JTree.AccessibleJTree This class implements accessibility support for the JTree class.
static class | JTree.DropLocation A subclass of TransferHandler.DropLocation representing a drop location for a JTree.
static class | JTree.DynamicUtilTreeNode DynamicUtilTreeNode can wrap vectors/hashtables/arrays/strings and create the appropriate children tree nodes as necessary.
protected static class | JTree.EmptySelectionModel EmptySelectionModel is a TreeSelectionModel that does not allow anything to be selected.
protected class | JTree.TreeModelHandler Listens to the model and updates the expandedState accordingly when nodes are removed, or changed.
protected class | JTree.TreeSelectionRedirector Handles creating a new TreeSelectionEvent with the JTree as the source and passing it off to all the listeners.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
static String | ANCHOR_SELECTION_PATH_PROPERTY Bound property name for anchor selection path.
static String | CELL_EDITOR_PROPERTY Bound property name for cellEditor.
static String | CELL_RENDERER_PROPERTY Bound property name for cellRenderer.
protected TreeCellEditor | cellEditor Editor for the entries.
protected TreeCellRenderer | cellRenderer The cell used to draw nodes.
protected boolean | editable Is the tree editable? Default is false.
static String | EDITABLE_PROPERTY Bound property name for editable.
static String | EXPANDS_SELECTED_PATHS_PROPERTY Bound property name for expands selected paths property
static String | INVOKES_STOP_CELL_EDITING_PROPERTY Bound property name for messagesStopCellEditing.
protected boolean | invokesStopCellEditing If true, when editing is to be stopped by way of selection changing, data in tree changing or other means stopCellEditing is invoked, and changes are saved.
static String | LARGE_MODEL_PROPERTY Bound property name for largeModel.
protected boolean | largeModel Is this tree a large model? This is a code-optimization setting.
static String | LEAD_SELECTION_PATH_PROPERTY Bound property name for leadSelectionPath.
static String | ROOT_VISIBLE_PROPERTY Bound property name for rootVisible.
protected boolean | rootVisible True if the root node is displayed, false if its children are the highest visible nodes.
static String | ROW_HEIGHT_PROPERTY Bound property name for rowHeight.
protected int | rowHeight Height to use for each display row.
static String | SCROLLS_ON_EXPAND_PROPERTY Bound property name for scrollsOnExpand.
protected boolean | scrollsOnExpand If true, when a node is expanded, as many of the descendants are scrolled to be visible.
static String | SELECTION_MODEL_PROPERTY Bound property name for selectionModel.
protected TreeSelectionModel | selectionModel Models the set of selected nodes in this tree.
protected JTree.TreeSelectionRedirector | selectionRedirector Creates a new event and passed it off the selectionListeners.
static String | SHOWS_ROOT_HANDLES_PROPERTY Bound property name for showsRootHandles.
protected boolean | showsRootHandles True if handles are displayed at the topmost level of the tree.
static String | TOGGLE_CLICK_COUNT_PROPERTY Bound property name for toggleClickCount.
protected int | toggleClickCount Number of mouse clicks before a node is expanded.
static String | TREE_MODEL_PROPERTY Bound property name for treeModel.
protected TreeModel | treeModel The model that defines the tree displayed by this object.
protected TreeModelListener | treeModelListener Updates the expandedState.
static String | VISIBLE_ROW_COUNT_PROPERTY Bound property name for visibleRowCount.
protected int | visibleRowCount Number of rows to make visible at one time.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JTree()
Returns a JTree with a sample model.
JTree(Hashtable<?,?> value)
Returns a JTree created from a Hashtable which does not display with root.
JTree(Object[] value)
Returns a JTree with each element of the specified array as the child of a new root node which is not displayed.
JTree(TreeModel newModel)
Returns an instance of JTree which displays the root node -- the tree is created using the specified data model.
JTree(TreeNode root)
Returns a JTree with the specified TreeNode as its root, which displays the root node.
JTree(TreeNode root, boolean asksAllowsChildren)
Returns a JTree with the specified TreeNode as its root, which displays the root node and which decides whether a node is a leaf node in the specified manner.
JTree(Vector<?> value)
Returns a JTree with each element of the specified Vector as the child of a new root node which is not displayed.
Method Summary
 void addSelectionInterval(int index0, int index1)
Adds the paths between index0 and index1, inclusive, to the selection.
 void addSelectionPath(TreePath path)
Adds the node identified by the specified TreePath to the current selection.
 void addSelectionPaths(TreePath[] paths)
Adds each path in the array of paths to the current selection.
 void addSelectionRow(int row)
Adds the path at the specified row to the current selection.
 void addSelectionRows(int[] rows)
Adds the paths at each of the specified rows to the current selection.
 void addTreeExpansionListener(TreeExpansionListener tel)
Adds a listener for TreeExpansion events.
 void addTreeSelectionListener(TreeSelectionListener tsl)
Adds a listener for TreeSelection events.
 void addTreeWillExpandListener(TreeWillExpandListener tel)
Adds a listener for TreeWillExpand events.
 void cancelEditing()
Cancels the current editing session.
 void clearSelection()
Clears the selection.
protected  void clearToggledPaths()
Clears the cache of toggled tree paths.
 void collapsePath(TreePath path)
Ensures that the node identified by the specified path is collapsed and viewable.
 void collapseRow(int row)
Ensures that the node in the specified row is collapsed.
 String convertValueToText(Object value, boolean selected, boolean expanded, boolean leaf, int row, boolean hasFocus)
Called by the renderers to convert the specified value to text.
protected static TreeModel createTreeModel(Object value)
Returns a TreeModel wrapping the specified object.
protected  TreeModelListener createTreeModelListener()
Creates and returns an instance of TreeModelHandler.
 void expandPath(TreePath path)
Ensures that the node identified by the specified path is expanded and viewable.
 void expandRow(int row)
Ensures that the node in the specified row is expanded and viewable.
 void fireTreeCollapsed(TreePath path)
Notifies all listeners that have registered interest for notification on this event type.
 void fireTreeExpanded(TreePath path)
Notifies all listeners that have registered interest for notification on this event type.
 void fireTreeWillCollapse(TreePath path)
Notifies all listeners that have registered interest for notification on this event type.
 void fireTreeWillExpand(TreePath path)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireValueChanged(TreeSelectionEvent e)
Notifies all listeners that have registered interest for notification on this event type.
 AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JTree.
 TreePath getAnchorSelectionPath()
Returns the path identified as the anchor.
 TreeCellEditor getCellEditor()
Returns the editor used to edit entries in the tree.
 TreeCellRenderer getCellRenderer()
Returns the current TreeCellRenderer that is rendering each cell.
 TreePath getClosestPathForLocation(int x, int y)
Returns the path to the node that is closest to x,y.
 int getClosestRowForLocation(int x, int y)
Returns the row to the node that is closest to x,y.
protected static TreeModel getDefaultTreeModel()
Creates and returns a sample TreeModel.
protected  Enumeration<TreePath> getDescendantToggledPaths(TreePath parent)
Returns an Enumeration of TreePaths that have been expanded that are descendants of parent.
 boolean getDragEnabled()
Returns whether or not automatic drag handling is enabled.
 JTree.DropLocation getDropLocation()
Returns the location that this component should visually indicate as the drop location during a DnD operation over the component, or null if no location is to currently be shown.
 DropMode getDropMode()
Returns the drop mode for this component.
 TreePath getEditingPath()
Returns the path to the element that is currently being edited.
 Enumeration<TreePath> getExpandedDescendants(TreePath parent)
Returns an Enumeration of the descendants of the path parent that are currently expanded.
 boolean getExpandsSelectedPaths()
Returns the expandsSelectedPaths property.
 boolean getInvokesStopCellEditing()
Returns the indicator that tells what happens when editing is interrupted.
 Object getLastSelectedPathComponent()
Returns the last path component in the first node of the current selection.
 TreePath getLeadSelectionPath()
Returns the path identified as the lead.
 int getLeadSelectionRow()
Returns the row index corresponding to the lead path.
 int getMaxSelectionRow()
Returns the last selected row.
 int getMinSelectionRow()
Gets the first selected row.
 TreeModel getModel()
Returns the TreeModel that is providing the data.
 TreePath getNextMatch(String prefix, int startingRow, Position.Bias bias)
Returns the TreePath to the next tree element that begins with a prefix.
protected  TreePath[] getPathBetweenRows(int index0, int index1)
Returns JTreePath instances representing the path between index0 and index1 (including index1).
 Rectangle getPathBounds(TreePath path)
Returns the Rectangle that the specified node will be drawn into.
 TreePath getPathForLocation(int x, int y)
Returns the path for the node at the specified location.
 TreePath getPathForRow(int row)
Returns the path for the specified row.
 Dimension getPreferredScrollableViewportSize()
Returns the preferred display size of a JTree.
 Rectangle getRowBounds(int row)
Returns the Rectangle that the node at the specified row is drawn in.
 int getRowCount()
Returns the number of rows that are currently being displayed.
 int getRowForLocation(int x, int y)
Returns the row for the specified location.
 int getRowForPath(TreePath path)
Returns the row that displays the node identified by the specified path.
 int getRowHeight()
Returns the height of each row.
 int getScrollableBlockIncrement(Rectangle visibleRect, int orientation, int direction)
Returns the amount for a block increment, which is the height or width of visibleRect, based on orientation.
 boolean getScrollableTracksViewportHeight()
Returns false to indicate that the height of the viewport does not determine the height of the table, unless the preferred height of the tree is smaller than the viewports height.
 boolean getScrollableTracksViewportWidth()
Returns false to indicate that the width of the viewport does not determine the width of the table, unless the preferred width of the tree is smaller than the viewports width.
 int getScrollableUnitIncrement(Rectangle visibleRect, int orientation, int direction)
Returns the amount to increment when scrolling.
 boolean getScrollsOnExpand()
Returns the value of the scrollsOnExpand property.
 int getSelectionCount()
Returns the number of nodes selected.
 TreeSelectionModel getSelectionModel()
Returns the model for selections.
 TreePath getSelectionPath()
Returns the path to the first selected node.
 TreePath[] getSelectionPaths()
Returns the paths of all selected values.
 int[] getSelectionRows()
Returns all of the currently selected rows.
 boolean getShowsRootHandles()
Returns the value of the showsRootHandles property.
 int getToggleClickCount()
Returns the number of mouse clicks needed to expand or close a node.
 String getToolTipText(MouseEvent event)
Overrides JComponent's getToolTipText method in order to allow renderer's tips to be used if it has text set.
 TreeExpansionListener[] getTreeExpansionListeners()
Returns an array of all the TreeExpansionListeners added to this JTree with addTreeExpansionListener().
 TreeSelectionListener[] getTreeSelectionListeners()
Returns an array of all the TreeSelectionListeners added to this JTree with addTreeSelectionListener().
 TreeWillExpandListener[] getTreeWillExpandListeners()
Returns an array of all the TreeWillExpandListeners added to this JTree with addTreeWillExpandListener().
 TreeUI getUI()
Returns the L&F object that renders this component.
 String getUIClassID()
Returns the name of the L&F class that renders this component.
 int getVisibleRowCount()
Returns the number of rows that are displayed in the display area.
 boolean hasBeenExpanded(TreePath path)
Returns true if the node identified by the path has ever been expanded.
 boolean isCollapsed(int row)
Returns true if the node at the specified display row is collapsed.
 boolean isCollapsed(TreePath path)
Returns true if the value identified by path is currently collapsed, this will return false if any of the values in path are currently not being displayed.
 boolean isEditable()
Returns true if the tree is editable.
 boolean isEditing()
Returns true if the tree is being edited.
 boolean isExpanded(int row)
Returns true if the node at the specified display row is currently expanded.
 boolean isExpanded(TreePath path)
Returns true if the node identified by the path is currently expanded,
 boolean isFixedRowHeight()
Returns true if the height of each display row is a fixed size.
 boolean isLargeModel()
Returns true if the tree is configured for a large model.
 boolean isPathEditable(TreePath path)
Returns isEditable.
 boolean isPathSelected(TreePath path)
Returns true if the item identified by the path is currently selected.
 boolean isRootVisible()
Returns true if the root node of the tree is displayed.
 boolean isRowSelected(int row)
Returns true if the node identified by row is selected.
 boolean isSelectionEmpty()
Returns true if the selection is currently empty.
 boolean isVisible(TreePath path)
Returns true if the value identified by path is currently viewable, which means it is either the root or all of its parents are expanded.
 void makeVisible(TreePath path)
Ensures that the node identified by path is currently viewable.
protected  String paramString()
Returns a string representation of this JTree.
protected  boolean removeDescendantSelectedPaths(TreePath path, boolean includePath)
Removes any paths in the selection that are descendants of path.
protected  void removeDescendantToggledPaths(Enumeration<TreePath> toRemove)
Removes any descendants of the TreePaths in toRemove that have been expanded.
 void removeSelectionInterval(int index0, int index1)
Removes the nodes between index0 and index1, inclusive, from the selection.
 void removeSelectionPath(TreePath path)
Removes the node identified by the specified path from the current selection.
 void removeSelectionPaths(TreePath[] paths)
Removes the nodes identified by the specified paths from the current selection.
 void removeSelectionRow(int row)
Removes the row at the index row from the current selection.
 void removeSelectionRows(int[] rows)
Removes the rows that are selected at each of the specified rows.
 void removeTreeExpansionListener(TreeExpansionListener tel)
Removes a listener for TreeExpansion events.
 void removeTreeSelectionListener(TreeSelectionListener tsl)
Removes a TreeSelection listener.
 void removeTreeWillExpandListener(TreeWillExpandListener tel)
Removes a listener for TreeWillExpand events.
 void scrollPathToVisible(TreePath path)
Makes sure all the path components in path are expanded (except for the last path component) and scrolls so that the node identified by the path is displayed.
 void scrollRowToVisible(int row)
Scrolls the item identified by row until it is displayed.
 void setAnchorSelectionPath(TreePath newPath)
Sets the path identified as the anchor.
 void setCellEditor(TreeCellEditor cellEditor)
Sets the cell editor.
 void setCellRenderer(TreeCellRenderer x)
Sets the TreeCellRenderer that will be used to draw each cell.
 void setDragEnabled(boolean b)
Turns on or off automatic drag handling.
 void setDropMode(DropMode dropMode)
Sets the drop mode for this component.
 void setEditable(boolean flag)
Determines whether the tree is editable.
protected  void setExpandedState(TreePath path, boolean state)
Sets the expanded state of this JTree.
 void setExpandsSelectedPaths(boolean newValue)
Configures the expandsSelectedPaths property.
 void setInvokesStopCellEditing(boolean newValue)
Determines what happens when editing is interrupted by selecting another node in the tree, a change in the tree's data, or by some other means.
 void setLargeModel(boolean newValue)
Specifies whether the UI should use a large model.
 void setLeadSelectionPath(TreePath newPath)
Sets the path identifies as the lead.
 void setModel(TreeModel newModel)
Sets the TreeModel that will provide the data.
 void setRootVisible(boolean rootVisible)
Determines whether or not the root node from the TreeModel is visible.
 void setRowHeight(int rowHeight)
Sets the height of each cell, in pixels.
 void setScrollsOnExpand(boolean newValue)
Sets the scrollsOnExpand property, which determines whether the tree might scroll to show previously hidden children.
 void setSelectionInterval(int index0, int index1)
Selects the nodes between index0 and index1, inclusive.
 void setSelectionModel(TreeSelectionModel selectionModel)
Sets the tree's selection model.
 void setSelectionPath(TreePath path)
Selects the node identified by the specified path.
 void setSelectionPaths(TreePath[] paths)
Selects the nodes identified by the specified array of paths.
 void setSelectionRow(int row)
Selects the node at the specified row in the display.
 void setSelectionRows(int[] rows)
Selects the nodes corresponding to each of the specified rows in the display.
 void setShowsRootHandles(boolean newValue)
Sets the value of the showsRootHandles property, which specifies whether the node handles should be displayed.
 void setToggleClickCount(int clickCount)
Sets the number of mouse clicks before a node will expand or close.
 void setUI(TreeUI ui)
Sets the L&F object that renders this component.
 void setVisibleRowCount(int newCount)
Sets the number of rows that are to be displayed.
 void startEditingAtPath(TreePath path)
Selects the node identified by the specified path and initiates editing.
 boolean stopEditing()
Ends the current editing session.
 void treeDidChange()
Sent when the tree has changed enough that we need to resize the bounds, but not enough that we need to remove the expanded node set (e.g nodes were expanded or collapsed, or nodes were inserted into the tree).
 void updateUI()
Notification from the UIManager that the L&F has changed.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

treeModel

protected transient TreeModel treeModel
The model that defines the tree displayed by this object.

selectionModel

protected transient TreeSelectionModel selectionModel
Models the set of selected nodes in this tree.

rootVisible

protected boolean rootVisible
True if the root node is displayed, false if its children are the highest visible nodes.

cellRenderer

protected transient TreeCellRenderer cellRenderer
The cell used to draw nodes. If null, the UI uses a default cellRenderer.

rowHeight

protected int rowHeight
Height to use for each display row. If this is <= 0="0" the="the" renderer="renderer" determines="determines" the="the" height="height" for="for" each="each" row.="row."

showsRootHandles

protected boolean showsRootHandles
True if handles are displayed at the topmost level of the tree.

A handle is a small icon that displays adjacent to the node which allows the user to click once to expand or collapse the node. A common interface shows a plus sign (+) for a node which can be expanded and a minus sign (-) for a node which can be collapsed. Handles are always shown for nodes below the topmost level.

If the rootVisible setting specifies that the root node is to be displayed, then that is the only node at the topmost level. If the root node is not displayed, then all of its children are at the topmost level of the tree. Handles are always displayed for nodes other than the topmost.

If the root node isn't visible, it is generally a good to make this value true. Otherwise, the tree looks exactly like a list, and users may not know that the "list entries" are actually tree nodes.

See Also:
rootVisible

selectionRedirector

protected transient JTree.TreeSelectionRedirector selectionRedirector
Creates a new event and passed it off the selectionListeners.

cellEditor

protected transient TreeCellEditor cellEditor
Editor for the entries. Default is null (tree is not editable).

editable

protected boolean editable
Is the tree editable? Default is false.

largeModel

protected boolean largeModel
Is this tree a large model? This is a code-optimization setting. A large model can be used when the cell height is the same for all nodes. The UI will then cache very little information and instead continually message the model. Without a large model the UI caches most of the information, resulting in fewer method calls to the model.

This value is only a suggestion to the UI. Not all UIs will take advantage of it. Default value is false.

visibleRowCount

protected int visibleRowCount
Number of rows to make visible at one time. This value is used for the Scrollable interface. It determines the preferred size of the display area.

invokesStopCellEditing

protected boolean invokesStopCellEditing
If true, when editing is to be stopped by way of selection changing, data in tree changing or other means stopCellEditing is invoked, and changes are saved. If false, cancelCellEditing is invoked, and changes are discarded. Default is false.

scrollsOnExpand

protected boolean scrollsOnExpand
If true, when a node is expanded, as many of the descendants are scrolled to be visible.

toggleClickCount

protected int toggleClickCount
Number of mouse clicks before a node is expanded.

treeModelListener

protected transient TreeModelListener treeModelListener
Updates the expandedState.

CELL_RENDERER_PROPERTY

public static final String CELL_RENDERER_PROPERTY
Bound property name for cellRenderer.

See Also:
Constant Field Values

TREE_MODEL_PROPERTY

public static final String TREE_MODEL_PROPERTY
Bound property name for treeModel.

See Also:
Constant Field Values

ROOT_VISIBLE_PROPERTY

public static final String ROOT_VISIBLE_PROPERTY
Bound property name for rootVisible.

See Also:
Constant Field Values

SHOWS_ROOT_HANDLES_PROPERTY

public static final String SHOWS_ROOT_HANDLES_PROPERTY
Bound property name for showsRootHandles.

See Also:
Constant Field Values

ROW_HEIGHT_PROPERTY

public static final String ROW_HEIGHT_PROPERTY
Bound property name for rowHeight.

See Also:
Constant Field Values

CELL_EDITOR_PROPERTY

public static final String CELL_EDITOR_PROPERTY
Bound property name for cellEditor.

See Also:
Constant Field Values

EDITABLE_PROPERTY

public static final String EDITABLE_PROPERTY
Bound property name for editable.

See Also:
Constant Field Values

LARGE_MODEL_PROPERTY

public static final String LARGE_MODEL_PROPERTY
Bound property name for largeModel.

See Also:
Constant Field Values

SELECTION_MODEL_PROPERTY

public static final String SELECTION_MODEL_PROPERTY
Bound property name for selectionModel.

See Also:
Constant Field Values

VISIBLE_ROW_COUNT_PROPERTY

public static final String VISIBLE_ROW_COUNT_PROPERTY
Bound property name for visibleRowCount.

See Also:
Constant Field Values

INVOKES_STOP_CELL_EDITING_PROPERTY

public static final String INVOKES_STOP_CELL_EDITING_PROPERTY
Bound property name for messagesStopCellEditing.

See Also:
Constant Field Values

SCROLLS_ON_EXPAND_PROPERTY

public static final String SCROLLS_ON_EXPAND_PROPERTY
Bound property name for scrollsOnExpand.

See Also:
Constant Field Values

TOGGLE_CLICK_COUNT_PROPERTY

public static final String TOGGLE_CLICK_COUNT_PROPERTY
Bound property name for toggleClickCount.

See Also:
Constant Field Values

LEAD_SELECTION_PATH_PROPERTY

public static final String LEAD_SELECTION_PATH_PROPERTY
Bound property name for leadSelectionPath.

Since:
1.3
See Also:
Constant Field Values

ANCHOR_SELECTION_PATH_PROPERTY

public static final String ANCHOR_SELECTION_PATH_PROPERTY
Bound property name for anchor selection path.

Since:
1.3
See Also:
Constant Field Values

EXPANDS_SELECTED_PATHS_PROPERTY

public static final String EXPANDS_SELECTED_PATHS_PROPERTY
Bound property name for expands selected paths property

Since:
1.3
See Also:
Constant Field Values
Constructor Detail

JTree

public JTree()
Returns a JTree with a sample model. The default model used by the tree defines a leaf node as any node without children.

See Also:
DefaultTreeModel.asksAllowsChildren

JTree

public JTree(Object[] value)
Returns a JTree with each element of the specified array as the child of a new root node which is not displayed. By default, the tree defines a leaf node as any node without children.

Parameters:
value - an array of Objects
See Also:
DefaultTreeModel.asksAllowsChildren

JTree

public JTree(Vector<?> value)
Returns a JTree with each element of the specified Vector as the child of a new root node which is not displayed. By default, the tree defines a leaf node as any node without children.

Parameters:
value - a Vector
See Also:
DefaultTreeModel.asksAllowsChildren

JTree

public JTree(Hashtable<?,?> value)
Returns a JTree created from a Hashtable which does not display with root. Each value-half of the key/value pairs in the HashTable becomes a child of the new root node. By default, the tree defines a leaf node as any node without children.

Parameters:
value - a Hashtable
See Also:
DefaultTreeModel.asksAllowsChildren

JTree

public JTree(TreeNode root)
Returns a JTree with the specified TreeNode as its root, which displays the root node. By default, the tree defines a leaf node as any node without children.

Parameters:
root - a TreeNode object
See Also:
DefaultTreeModel.asksAllowsChildren

JTree

public JTree(TreeNode root,
             boolean asksAllowsChildren)
Returns a JTree with the specified TreeNode as its root, which displays the root node and which decides whether a node is a leaf node in the specified manner.

Parameters:
root - a TreeNode object
asksAllowsChildren - if false, any node without children is a leaf node; if true, only nodes that do not allow children are leaf nodes
See Also:
DefaultTreeModel.asksAllowsChildren

JTree

public JTree(TreeModel newModel)
Returns an instance of JTree which displays the root node -- the tree is created using the specified data model.

Parameters:
newModel - the TreeModel to use as the data model
Method Detail

getDefaultTreeModel

protected static TreeModel getDefaultTreeModel()
Creates and returns a sample TreeModel. Used primarily for beanbuilders to show something interesting.

Returns:
the default TreeModel

createTreeModel

protected static TreeModel createTreeModel(Object value)
Returns a TreeModel wrapping the specified object. If the object is:
  • an array of Objects,
  • a Hashtable, or
  • a Vector
then a new root node is created with each of the incoming objects as children. Otherwise, a new root is created with the specified object as its value.

Parameters:
value - the Object used as the foundation for the TreeModel
Returns:
a TreeModel wrapping the specified object

getUI

public TreeUI getUI()
Returns the L&F object that renders this component.

Returns:
the TreeUI object that renders this component

setUI

public void setUI(TreeUI ui)
Sets the L&F object that renders this component.

Parameters:
ui - the TreeUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Notification from the UIManager that the L&F has changed. Replaces the current UI object with the latest version from the UIManager.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "TreeUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

getCellRenderer

public TreeCellRenderer getCellRenderer()
Returns the current TreeCellRenderer that is rendering each cell.

Returns:
the TreeCellRenderer that is rendering each cell

setCellRenderer

public void setCellRenderer(TreeCellRenderer x)
Sets the TreeCellRenderer that will be used to draw each cell.

Parameters:
x - the TreeCellRenderer that is to render each cell

setEditable

public void setEditable(boolean flag)
Determines whether the tree is editable. Fires a property change event if the new setting is different from the existing setting.

Parameters:
flag - a boolean value, true if the tree is editable

isEditable

public boolean isEditable()
Returns true if the tree is editable.

Returns:
true if the tree is editable

setCellEditor

public void setCellEditor(TreeCellEditor cellEditor)
Sets the cell editor. A null value implies that the tree cannot be edited. If this represents a change in the cellEditor, the propertyChange method is invoked on all listeners.

Parameters:
cellEditor - the TreeCellEditor to use

getCellEditor

public TreeCellEditor getCellEditor()
Returns the editor used to edit entries in the tree.

Returns:
the TreeCellEditor in use, or null if the tree cannot be edited

getModel

public TreeModel getModel()
Returns the TreeModel that is providing the data.

Returns:
the TreeModel that is providing the data

setModel

public void setModel(TreeModel newModel)
Sets the TreeModel that will provide the data.

Parameters:
newModel - the TreeModel that is to provide the data

isRootVisible

public boolean isRootVisible()
Returns true if the root node of the tree is displayed.

Returns:
true if the root node of the tree is displayed
See Also:
rootVisible

setRootVisible

public void setRootVisible(boolean rootVisible)
Determines whether or not the root node from the TreeModel is visible.

Parameters:
rootVisible - true if the root node of the tree is to be displayed
See Also:
rootVisible

setShowsRootHandles

public void setShowsRootHandles(boolean newValue)
Sets the value of the showsRootHandles property, which specifies whether the node handles should be displayed. The default value of this property depends on the constructor used to create the JTree. Some look and feels might not support handles; they will ignore this property.

Parameters:
newValue - true if root handles should be displayed; otherwise, false
See Also:
showsRootHandles, getShowsRootHandles()

getShowsRootHandles

public boolean getShowsRootHandles()
Returns the value of the showsRootHandles property.

Returns:
the value of the showsRootHandles property
See Also:
showsRootHandles

setRowHeight

public void setRowHeight(int rowHeight)
Sets the height of each cell, in pixels. If the specified value is less than or equal to zero the current cell renderer is queried for each row's height.

Parameters:
rowHeight - the height of each cell, in pixels

getRowHeight

public int getRowHeight()
Returns the height of each row. If the returned value is less than or equal to 0 the height for each row is determined by the renderer.

isFixedRowHeight

public boolean isFixedRowHeight()
Returns true if the height of each display row is a fixed size.

Returns:
true if the height of each row is a fixed size

setLargeModel

public void setLargeModel(boolean newValue)
Specifies whether the UI should use a large model. (Not all UIs will implement this.) Fires a property change for the LARGE_MODEL_PROPERTY.

Parameters:
newValue - true to suggest a large model to the UI
See Also:
largeModel

isLargeModel

public boolean isLargeModel()
Returns true if the tree is configured for a large model.

Returns:
true if a large model is suggested
See Also:
largeModel

setInvokesStopCellEditing

public void setInvokesStopCellEditing(boolean newValue)
Determines what happens when editing is interrupted by selecting another node in the tree, a change in the tree's data, or by some other means. Setting this property to true causes the changes to be automatically saved when editing is interrupted.

Fires a property change for the INVOKES_STOP_CELL_EDITING_PROPERTY.

Parameters:
newValue - true means that stopCellEditing is invoked when editing is interrupted, and data is saved; false means that cancelCellEditing is invoked, and changes are lost

getInvokesStopCellEditing

public boolean getInvokesStopCellEditing()
Returns the indicator that tells what happens when editing is interrupted.

Returns:
the indicator that tells what happens when editing is interrupted
See Also:
setInvokesStopCellEditing(boolean)

setScrollsOnExpand

public void setScrollsOnExpand(boolean newValue)
Sets the scrollsOnExpand property, which determines whether the tree might scroll to show previously hidden children. If this property is true (the default), when a node expands the tree can use scrolling to make the maximum possible number of the node's descendants visible. In some look and feels, trees might not need to scroll when expanded; those look and feels will ignore this property.

Parameters:
newValue - false to disable scrolling on expansion; true to enable it
See Also:
getScrollsOnExpand()

getScrollsOnExpand

public boolean getScrollsOnExpand()
Returns the value of the scrollsOnExpand property.

Returns:
the value of the scrollsOnExpand property

setToggleClickCount

public void setToggleClickCount(int clickCount)
Sets the number of mouse clicks before a node will expand or close. The default is two.

Since:
1.3

getToggleClickCount

public int getToggleClickCount()
Returns the number of mouse clicks needed to expand or close a node.

Returns:
number of mouse clicks before node is expanded
Since:
1.3

setExpandsSelectedPaths

public void setExpandsSelectedPaths(boolean newValue)
Configures the expandsSelectedPaths property. If true, any time the selection is changed, either via the TreeSelectionModel, or the cover methods provided by JTree, the TreePaths parents will be expanded to make them visible (visible meaning the parent path is expanded, not necessarily in the visible rectangle of the JTree). If false, when the selection changes the nodes parent is not made visible (all its parents expanded). This is useful if you wish to have your selection model maintain paths that are not always visible (all parents expanded).

Parameters:
newValue - the new value for expandsSelectedPaths
Since:
1.3

getExpandsSelectedPaths

public boolean getExpandsSelectedPaths()
Returns the expandsSelectedPaths property.

Returns:
true if selection changes result in the parent path being expanded
Since:
1.3
See Also:
setExpandsSelectedPaths(boolean)

setDragEnabled

public void setDragEnabled(boolean b)
Turns on or off automatic drag handling. In order to enable automatic drag handling, this property should be set to true, and the tree's TransferHandler needs to be non-null. The default value of the dragEnabled property is false.

The job of honoring this property, and recognizing a user drag gesture, lies with the look and feel implementation, and in particular, the tree's TreeUI. When automatic drag handling is enabled, most look and feels (including those that subclass BasicLookAndFeel) begin a drag and drop operation whenever the user presses the mouse button over an item and then moves the mouse a few pixels. Setting this property to true can therefore have a subtle effect on how selections behave.

If a look and feel is used that ignores this property, you can still begin a drag and drop operation by calling exportAsDrag on the tree's TransferHandler.

Parameters:
b - whether or not to enable automatic drag handling
Throws:
HeadlessException - if b is true and GraphicsEnvironment.isHeadless() returns true
Since:
1.4
See Also:
GraphicsEnvironment.isHeadless(),
getDragEnabled(),
JComponent.setTransferHandler(javax.swing.TransferHandler),
TransferHandler

getDragEnabled

public boolean getDragEnabled()
Returns whether or not automatic drag handling is enabled.

Returns:
the value of the dragEnabled property
Since:
1.4
See Also:
setDragEnabled(boolean)

setDropMode

public final void setDropMode(DropMode dropMode)
Sets the drop mode for this component. For backward compatibility, the default for this property is DropMode.USE_SELECTION. Usage of one of the other modes is recommended, however, for an improved user experience. DropMode.ON, for instance, offers similar behavior of showing items as selected, but does so without affecting the actual selection in the tree.

JTree supports the following drop modes:

  • DropMode.USE_SELECTION
  • DropMode.ON
  • DropMode.INSERT
  • DropMode.ON_OR_INSERT

The drop mode is only meaningful if this component has a TransferHandler that accepts drops.

Parameters:
dropMode - the drop mode to use
Throws:
IllegalArgumentException - if the drop mode is unsupported or null
Since:
1.6
See Also:
getDropMode(),
getDropLocation(),
JComponent.setTransferHandler(javax.swing.TransferHandler),
TransferHandler

getDropMode

public final DropMode getDropMode()
Returns the drop mode for this component.

Returns:
the drop mode for this component
Since:
1.6
See Also:
setDropMode(javax.swing.DropMode)

getDropLocation

public final JTree.DropLocation getDropLocation()
Returns the location that this component should visually indicate as the drop location during a DnD operation over the component, or null if no location is to currently be shown.

This method is not meant for querying the drop location from a TransferHandler, as the drop location is only set after the TransferHandler's canImport has returned and has allowed for the location to be shown.

When this property changes, a property change event with name "dropLocation" is fired by the component.

Returns:
the drop location
Since:
1.6
See Also:
setDropMode(javax.swing.DropMode), TransferHandler.canImport(TransferHandler.TransferSupport)

isPathEditable

public boolean isPathEditable(TreePath path)
Returns isEditable. This is invoked from the UI before editing begins to insure that the given path can be edited. This is provided as an entry point for subclassers to add filtered editing without having to resort to creating a new editor.

Returns:
true if every parent node and the node itself is editable
See Also:
isEditable()

getToolTipText

public String getToolTipText(MouseEvent event)
Overrides JComponent's getToolTipText method in order to allow renderer's tips to be used if it has text set.

NOTE: For JTree to properly display tooltips of its renderers, JTree must be a registered component with the ToolTipManager. This can be done by invoking ToolTipManager.sharedInstance().registerComponent(tree). This is not done automatically!

Overrides:
getToolTipText in class JComponent
Parameters:
event - the MouseEvent that initiated the ToolTip display
Returns:
a string containing the tooltip or null if event is null

convertValueToText

public String convertValueToText(Object value,
                                 boolean selected,
                                 boolean expanded,
                                 boolean leaf,
                                 int row,
                                 boolean hasFocus)
Called by the renderers to convert the specified value to text. This implementation returns value.toString, ignoring all other arguments. To control the conversion, subclass this method and use any of the arguments you need.

Parameters:
value - the Object to convert to text
selected - true if the node is selected
expanded - true if the node is expanded
leaf - true if the node is a leaf node
row - an integer specifying the node's display row, where 0 is the first row in the display
hasFocus - true if the node has the focus
Returns:
the String representation of the node's value

getRowCount

public int getRowCount()
Returns the number of rows that are currently being displayed.

Returns:
the number of rows that are being displayed

setSelectionPath

public void setSelectionPath(TreePath path)
Selects the node identified by the specified path. If any component of the path is hidden (under a collapsed node), and getExpandsSelectedPaths is true it is exposed (made viewable).

Parameters:
path - the TreePath specifying the node to select

setSelectionPaths

public void setSelectionPaths(TreePath[] paths)
Selects the nodes identified by the specified array of paths. If any component in any of the paths is hidden (under a collapsed node), and getExpandsSelectedPaths is true it is exposed (made viewable).

Parameters:
paths - an array of TreePath objects that specifies the nodes to select

setLeadSelectionPath

public void setLeadSelectionPath(TreePath newPath)
Sets the path identifies as the lead. The lead may not be selected. The lead is not maintained by JTree, rather the UI will update it.

Parameters:
newPath - the new lead path
Since:
1.3

setAnchorSelectionPath

public void setAnchorSelectionPath(TreePath newPath)
Sets the path identified as the anchor. The anchor is not maintained by JTree, rather the UI will update it.

Parameters:
newPath - the new anchor path
Since:
1.3

setSelectionRow

public void setSelectionRow(int row)
Selects the node at the specified row in the display.

Parameters:
row - the row to select, where 0 is the first row in the display

setSelectionRows

public void setSelectionRows(int[] rows)
Selects the nodes corresponding to each of the specified rows in the display. If a particular element of rows is < 0 or >= getRowCount, it will be ignored. If none of the elements in rows are valid rows, the selection will be cleared. That is it will be as if clearSelection was invoked.

Parameters:
rows - an array of ints specifying the rows to select, where 0 indicates the first row in the display

addSelectionPath

public void addSelectionPath(TreePath path)
Adds the node identified by the specified TreePath to the current selection. If any component of the path isn't viewable, and getExpandsSelectedPaths is true it is made viewable.

Note that JTree does not allow duplicate nodes to exist as children under the same parent -- each sibling must be a unique object.

Parameters:
path - the TreePath to add

addSelectionPaths

public void addSelectionPaths(TreePath[] paths)
Adds each path in the array of paths to the current selection. If any component of any of the paths isn't viewable and getExpandsSelectedPaths is true, it is made viewable.

Note that JTree does not allow duplicate nodes to exist as children under the same parent -- each sibling must be a unique object.

Parameters:
paths - an array of TreePath objects that specifies the nodes to add

addSelectionRow

public void addSelectionRow(int row)
Adds the path at the specified row to the current selection.

Parameters:
row - an integer specifying the row of the node to add, where 0 is the first row in the display

addSelectionRows

public void addSelectionRows(int[] rows)
Adds the paths at each of the specified rows to the current selection.

Parameters:
rows - an array of ints specifying the rows to add, where 0 indicates the first row in the display

getLastSelectedPathComponent

public Object getLastSelectedPathComponent()
Returns the last path component in the first node of the current selection.

Returns:
the last Object in the first selected node's TreePath, or null if nothing is selected
See Also:
TreePath.getLastPathComponent()

getLeadSelectionPath

public TreePath getLeadSelectionPath()
Returns the path identified as the lead.

Returns:
path identified as the lead

getAnchorSelectionPath

public TreePath getAnchorSelectionPath()
Returns the path identified as the anchor.

Returns:
path identified as the anchor
Since:
1.3

getSelectionPath

public TreePath getSelectionPath()
Returns the path to the first selected node.

Returns:
the TreePath for the first selected node, or null if nothing is currently selected

getSelectionPaths

public TreePath[] getSelectionPaths()
Returns the paths of all selected values.

Returns:
an array of TreePath objects indicating the selected nodes, or null if nothing is currently selected

getSelectionRows

public int[] getSelectionRows()
Returns all of the currently selected rows. This method is simply forwarded to the TreeSelectionModel. If nothing is selected null or an empty array will be returned, based on the TreeSelectionModel implementation.

Returns:
an array of integers that identifies all currently selected rows where 0 is the first row in the display

getSelectionCount

public int getSelectionCount()
Returns the number of nodes selected.

Returns:
the number of nodes selected

getMinSelectionRow

public int getMinSelectionRow()
Gets the first selected row.

Returns:
an integer designating the first selected row, where 0 is the first row in the display

getMaxSelectionRow

public int getMaxSelectionRow()
Returns the last selected row.

Returns:
an integer designating the last selected row, where 0 is the first row in the display

getLeadSelectionRow

public int getLeadSelectionRow()
Returns the row index corresponding to the lead path.

Returns:
an integer giving the row index of the lead path, where 0 is the first row in the display; or -1 if leadPath is null

isPathSelected

public boolean isPathSelected(TreePath path)
Returns true if the item identified by the path is currently selected.

Parameters:
path - a TreePath identifying a node
Returns:
true if the node is selected

isRowSelected

public boolean isRowSelected(int row)
Returns true if the node identified by row is selected.

Parameters:
row - an integer specifying a display row, where 0 is the first row in the display
Returns:
true if the node is selected

getExpandedDescendants

public Enumeration<TreePath> getExpandedDescendants(TreePath parent)
Returns an Enumeration of the descendants of the path parent that are currently expanded. If parent is not currently expanded, this will return null. If you expand/collapse nodes while iterating over the returned Enumeration this may not return all the expanded paths, or may return paths that are no longer expanded.

Parameters:
parent - the path which is to be examined
Returns:
an Enumeration of the descendents of parent, or null if parent is not currently expanded

hasBeenExpanded

public boolean hasBeenExpanded(TreePath path)
Returns true if the node identified by the path has ever been expanded.

Returns:
true if the path has ever been expanded

isExpanded

public boolean isExpanded(TreePath path)
Returns true if the node identified by the path is currently expanded,

Parameters:
path - the TreePath specifying the node to check
Returns:
false if any of the nodes in the node's path are collapsed, true if all nodes in the path are expanded

isExpanded

public boolean isExpanded(int row)
Returns true if the node at the specified display row is currently expanded.

Parameters:
row - the row to check, where 0 is the first row in the display
Returns:
true if the node is currently expanded, otherwise false

isCollapsed

public boolean isCollapsed(TreePath path)
Returns true if the value identified by path is currently collapsed, this will return false if any of the values in path are currently not being displayed.

Parameters:
path - the TreePath to check
Returns:
true if any of the nodes in the node's path are collapsed, false if all nodes in the path are expanded

isCollapsed

public boolean isCollapsed(int row)
Returns true if the node at the specified display row is collapsed.

Parameters:
row - the row to check, where 0 is the first row in the display
Returns:
true if the node is currently collapsed, otherwise false

makeVisible

public void makeVisible(TreePath path)
Ensures that the node identified by path is currently viewable.

Parameters:
path - the TreePath to make visible

isVisible

public boolean isVisible(TreePath path)
Returns true if the value identified by path is currently viewable, which means it is either the root or all of its parents are expanded. Otherwise, this method returns false.

Returns:
true if the node is viewable, otherwise false

getPathBounds

public Rectangle getPathBounds(TreePath path)
Returns the Rectangle that the specified node will be drawn into. Returns null if any component in the path is hidden (under a collapsed parent).

Note:
This method returns a valid rectangle, even if the specified node is not currently displayed.

Parameters:
path - the TreePath identifying the node
Returns:
the Rectangle the node is drawn in, or null

getRowBounds

public Rectangle getRowBounds(int row)
Returns the Rectangle that the node at the specified row is drawn in.

Parameters:
row - the row to be drawn, where 0 is the first row in the display
Returns:
the Rectangle the node is drawn in

scrollPathToVisible

public void scrollPathToVisible(TreePath path)
Makes sure all the path components in path are expanded (except for the last path component) and scrolls so that the node identified by the path is displayed. Only works when this JTree is contained in a JScrollPane.

Parameters:
path - the TreePath identifying the node to bring into view

scrollRowToVisible

public void scrollRowToVisible(int row)
Scrolls the item identified by row until it is displayed. The minimum of amount of scrolling necessary to bring the row into view is performed. Only works when this JTree is contained in a JScrollPane.

Parameters:
row - an integer specifying the row to scroll, where 0 is the first row in the display

getPathForRow

public TreePath getPathForRow(int row)
Returns the path for the specified row. If row is not visible, null is returned.

Parameters:
row - an integer specifying a row
Returns:
the TreePath to the specified node, null if row < 0 or row > getRowCount()

getRowForPath

public int getRowForPath(TreePath path)
Returns the row that displays the node identified by the specified path.

Parameters:
path - the TreePath identifying a node
Returns:
an integer specifying the display row, where 0 is the first row in the display, or -1 if any of the elements in path are hidden under a collapsed parent.

expandPath

public void expandPath(TreePath path)
Ensures that the node identified by the specified path is expanded and viewable. If the last item in the path is a leaf, this will have no effect.

Parameters:
path - the TreePath identifying a node

expandRow

public void expandRow(int row)
Ensures that the node in the specified row is expanded and viewable.

If row is < 0 or >= getRowCount this will have no effect.

Parameters:
row - an integer specifying a display row, where 0 is the first row in the display

collapsePath

public void collapsePath(TreePath path)
Ensures that the node identified by the specified path is collapsed and viewable.

Parameters:
path - the TreePath identifying a node

collapseRow

public void collapseRow(int row)
Ensures that the node in the specified row is collapsed.

If row is < 0 or >= getRowCount this will have no effect.

Parameters:
row - an integer specifying a display row, where 0 is the first row in the display

getPathForLocation

public TreePath getPathForLocation(int x,
                                   int y)
Returns the path for the node at the specified location.

Parameters:
x - an integer giving the number of pixels horizontally from the left edge of the display area, minus any left margin
y - an integer giving the number of pixels vertically from the top of the display area, minus any top margin
Returns:
the TreePath for the node at that location

getRowForLocation

public int getRowForLocation(int x,
                             int y)
Returns the row for the specified location.

Parameters:
x - an integer giving the number of pixels horizontally from the left edge of the display area, minus any left margin
y - an integer giving the number of pixels vertically from the top of the display area, minus any top margin
Returns:
the row corresponding to the location, or -1 if the location is not within the bounds of a displayed cell
See Also:
getClosestRowForLocation(int, int)

getClosestPathForLocation

public TreePath getClosestPathForLocation(int x,
                                          int y)
Returns the path to the node that is closest to x,y. If no nodes are currently viewable, or there is no model, returns null, otherwise it always returns a valid path. To test if the node is exactly at x, y, get the node's bounds and test x, y against that.

Parameters:
x - an integer giving the number of pixels horizontally from the left edge of the display area, minus any left margin
y - an integer giving the number of pixels vertically from the top of the display area, minus any top margin
Returns:
the TreePath for the node closest to that location, null if nothing is viewable or there is no model
See Also:
getPathForLocation(int, int), getPathBounds(javax.swing.tree.TreePath)

getClosestRowForLocation

public int getClosestRowForLocation(int x,
                                    int y)
Returns the row to the node that is closest to x,y. If no nodes are viewable or there is no model, returns -1. Otherwise, it always returns a valid row. To test if the returned object is exactly at x, y, get the bounds for the node at the returned row and test x, y against that.

Parameters:
x - an integer giving the number of pixels horizontally from the left edge of the display area, minus any left margin
y - an integer giving the number of pixels vertically from the top of the display area, minus any top margin
Returns:
the row closest to the location, -1 if nothing is viewable or there is no model
See Also:
getRowForLocation(int, int), getRowBounds(int)

isEditing

public boolean isEditing()
Returns true if the tree is being edited. The item that is being edited can be obtained using getSelectionPath.

Returns:
true if the user is currently editing a node
See Also:
getSelectionPath()

stopEditing

public boolean stopEditing()
Ends the current editing session. (The DefaultTreeCellEditor object saves any edits that are currently in progress on a cell. Other implementations may operate differently.) Has no effect if the tree isn't being edited.
Note:
To make edit-saves automatic whenever the user changes their position in the tree, use setInvokesStopCellEditing(boolean).

Returns:
true if editing was in progress and is now stopped, false if editing was not in progress

cancelEditing

public void cancelEditing()
Cancels the current editing session. Has no effect if the tree isn't being edited.

startEditingAtPath

public void startEditingAtPath(TreePath path)
Selects the node identified by the specified path and initiates editing. The edit-attempt fails if the CellEditor does not allow editing for the specified item.

Parameters:
path - the TreePath identifying a node

getEditingPath

public TreePath getEditingPath()
Returns the path to the element that is currently being edited.

Returns:
the TreePath for the node being edited

setSelectionModel

public void setSelectionModel(TreeSelectionModel selectionModel)
Sets the tree's selection model. When a null value is specified an empty selectionModel is used, which does not allow selections.

Parameters:
selectionModel - the TreeSelectionModel to use, or null to disable selections
See Also:
TreeSelectionModel

getSelectionModel

public TreeSelectionModel getSelectionModel()
Returns the model for selections. This should always return a non-null value. If you don't want to allow anything to be selected set the selection model to null, which forces an empty selection model to be used.

See Also:
setSelectionModel(javax.swing.tree.TreeSelectionModel)

getPathBetweenRows

protected TreePath[] getPathBetweenRows(int index0,
                                        int index1)
Returns JTreePath instances representing the path between index0 and index1 (including index1). Returns null if there is no tree.

Parameters:
index0 - an integer specifying a display row, where 0 is the first row in the display
index1 - an integer specifying a second display row
Returns:
an array of TreePath objects, one for each node between index0 and index1, inclusive; or null if there is no tree

setSelectionInterval

public void setSelectionInterval(int index0,
                                 int index1)
Selects the nodes between index0 and index1, inclusive.

Parameters:
index0 - an integer specifying a display row, where 0 is the first row in the display
index1 - an integer specifying a second display row

addSelectionInterval

public void addSelectionInterval(int index0,
                                 int index1)
Adds the paths between index0 and index1, inclusive, to the selection.

Parameters:
index0 - an integer specifying a display row, where 0 is the first row in the display
index1 - an integer specifying a second display row

removeSelectionInterval

public void removeSelectionInterval(int index0,
                                    int index1)
Removes the nodes between index0 and index1, inclusive, from the selection.

Parameters:
index0 - an integer specifying a display row, where 0 is the first row in the display
index1 - an integer specifying a second display row

removeSelectionPath

public void removeSelectionPath(TreePath path)
Removes the node identified by the specified path from the current selection.

Parameters:
path - the TreePath identifying a node

removeSelectionPaths

public void removeSelectionPaths(TreePath[] paths)
Removes the nodes identified by the specified paths from the current selection.

Parameters:
paths - an array of TreePath objects that specifies the nodes to remove

removeSelectionRow

public void removeSelectionRow(int row)
Removes the row at the index row from the current selection.

Parameters:
row - the row to remove

removeSelectionRows

public void removeSelectionRows(int[] rows)
Removes the rows that are selected at each of the specified rows.

Parameters:
rows - an array of ints specifying display rows, where 0 is the first row in the display

clearSelection

public void clearSelection()
Clears the selection.

isSelectionEmpty

public boolean isSelectionEmpty()
Returns true if the selection is currently empty.

Returns:
true if the selection is currently empty

addTreeExpansionListener

public void addTreeExpansionListener(TreeExpansionListener tel)
Adds a listener for TreeExpansion events.

Parameters:
tel - a TreeExpansionListener that will be notified when a tree node is expanded or collapsed (a "negative expansion")

removeTreeExpansionListener

public void removeTreeExpansionListener(TreeExpansionListener tel)
Removes a listener for TreeExpansion events.

Parameters:
tel - the TreeExpansionListener to remove

getTreeExpansionListeners

public TreeExpansionListener[] getTreeExpansionListeners()
Returns an array of all the TreeExpansionListeners added to this JTree with addTreeExpansionListener().

Returns:
all of the TreeExpansionListeners added or an empty array if no listeners have been added
Since:
1.4

addTreeWillExpandListener

public void addTreeWillExpandListener(TreeWillExpandListener tel)
Adds a listener for TreeWillExpand events.

Parameters:
tel - a TreeWillExpandListener that will be notified when a tree node will be expanded or collapsed (a "negative expansion")

removeTreeWillExpandListener

public void removeTreeWillExpandListener(TreeWillExpandListener tel)
Removes a listener for TreeWillExpand events.

Parameters:
tel - the TreeWillExpandListener to remove

getTreeWillExpandListeners

public TreeWillExpandListener[] getTreeWillExpandListeners()
Returns an array of all the TreeWillExpandListeners added to this JTree with addTreeWillExpandListener().

Returns:
all of the TreeWillExpandListeners added or an empty array if no listeners have been added
Since:
1.4

fireTreeExpanded

public void fireTreeExpanded(TreePath path)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the path parameter.

Parameters:
path - the TreePath indicating the node that was expanded
See Also:
EventListenerList

fireTreeCollapsed

public void fireTreeCollapsed(TreePath path)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the path parameter.

Parameters:
path - the TreePath indicating the node that was collapsed
See Also:
EventListenerList

fireTreeWillExpand

public void fireTreeWillExpand(TreePath path)
                        throws ExpandVetoException
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the path parameter.

Parameters:
path - the TreePath indicating the node that was expanded
Throws:
ExpandVetoException
See Also:
EventListenerList

fireTreeWillCollapse

public void fireTreeWillCollapse(TreePath path)
                          throws ExpandVetoException
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the path parameter.

Parameters:
path - the TreePath indicating the node that was expanded
Throws:
ExpandVetoException
See Also:
EventListenerList

addTreeSelectionListener

public void addTreeSelectionListener(TreeSelectionListener tsl)
Adds a listener for TreeSelection events.

Parameters:
tsl - the TreeSelectionListener that will be notified when a node is selected or deselected (a "negative selection")

removeTreeSelectionListener

public void removeTreeSelectionListener(TreeSelectionListener tsl)
Removes a TreeSelection listener.

Parameters:
tsl - the TreeSelectionListener to remove

getTreeSelectionListeners

public TreeSelectionListener[] getTreeSelectionListeners()
Returns an array of all the TreeSelectionListeners added to this JTree with addTreeSelectionListener().

Returns:
all of the TreeSelectionListeners added or an empty array if no listeners have been added
Since:
1.4

fireValueChanged

protected void fireValueChanged(TreeSelectionEvent e)
Notifies all listeners that have registered interest for notification on this event type.

Parameters:
e - the TreeSelectionEvent to be fired; generated by the TreeSelectionModel when a node is selected or deselected
See Also:
EventListenerList

treeDidChange

public void treeDidChange()
Sent when the tree has changed enough that we need to resize the bounds, but not enough that we need to remove the expanded node set (e.g nodes were expanded or collapsed, or nodes were inserted into the tree). You should never have to invoke this, the UI will invoke this as it needs to.

setVisibleRowCount

public void setVisibleRowCount(int newCount)
Sets the number of rows that are to be displayed. This will only work if the tree is contained in a JScrollPane, and will adjust the preferred size and size of that scrollpane.

Parameters:
newCount - the number of rows to display

getVisibleRowCount

public int getVisibleRowCount()
Returns the number of rows that are displayed in the display area.

Returns:
the number of rows displayed

getNextMatch

public TreePath getNextMatch(String prefix,
                             int startingRow,
                             Position.Bias bias)
Returns the TreePath to the next tree element that begins with a prefix. To handle the conversion of a TreePath into a String, convertValueToText is used.

Parameters:
prefix - the string to test for a match
startingRow - the row for starting the search
bias - the search direction, either Position.Bias.Forward or Position.Bias.Backward.
Returns:
the TreePath of the next tree element that starts with the prefix; otherwise null
Throws:
IllegalArgumentException - if prefix is null or startingRow is out of bounds
Since:
1.4

getPreferredScrollableViewportSize

public Dimension getPreferredScrollableViewportSize()
Returns the preferred display size of a JTree. The height is determined from getVisibleRowCount and the width is the current preferred width.

Specified by:
getPreferredScrollableViewportSize in interface Scrollable
Returns:
a Dimension object containing the preferred size
See Also:
JComponent.getPreferredSize()

getScrollableUnitIncrement

public int getScrollableUnitIncrement(Rectangle visibleRect,
                                      int orientation,
                                      int direction)
Returns the amount to increment when scrolling. The amount is the height of the first displayed row that isn't completely in view or, if it is totally displayed, the height of the next row in the scrolling direction.

Specified by:
getScrollableUnitIncrement in interface Scrollable
Parameters:
visibleRect - the view area visible within the viewport
orientation - either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL
direction - less than zero to scroll up/left, greater than zero for down/right
Returns:
the "unit" increment for scrolling in the specified direction
See Also:
JScrollBar.setUnitIncrement(int)

getScrollableBlockIncrement

public int getScrollableBlockIncrement(Rectangle visibleRect,
                                       int orientation,
                                       int direction)
Returns the amount for a block increment, which is the height or width of visibleRect, based on orientation.

Specified by:
getScrollableBlockIncrement in interface Scrollable
Parameters:
visibleRect - the view area visible within the viewport
orientation - either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL
direction - less than zero to scroll up/left, greater than zero for down/right.
Returns:
the "block" increment for scrolling in the specified direction
See Also:
JScrollBar.setBlockIncrement(int)

getScrollableTracksViewportWidth

public boolean getScrollableTracksViewportWidth()
Returns false to indicate that the width of the viewport does not determine the width of the table, unless the preferred width of the tree is smaller than the viewports width. In other words: ensure that the tree is never smaller than its viewport.

Specified by:
getScrollableTracksViewportWidth in interface Scrollable
Returns:
false
See Also:
Scrollable.getScrollableTracksViewportWidth()

getScrollableTracksViewportHeight

public boolean getScrollableTracksViewportHeight()
Returns false to indicate that the height of the viewport does not determine the height of the table, unless the preferred height of the tree is smaller than the viewports height. In other words: ensure that the tree is never smaller than its viewport.

Specified by:
getScrollableTracksViewportHeight in interface Scrollable
Returns:
false
See Also:
Scrollable.getScrollableTracksViewportHeight()

setExpandedState

protected void setExpandedState(TreePath path,
                                boolean state)
Sets the expanded state of this JTree. If state is true, all parents of path and path are marked as expanded. If state is false, all parents of path are marked EXPANDED, but path itself is marked collapsed.

This will fail if a TreeWillExpandListener vetos it.

getDescendantToggledPaths

protected Enumeration<TreePath> getDescendantToggledPaths(TreePath parent)
Returns an Enumeration of TreePaths that have been expanded that are descendants of parent.

removeDescendantToggledPaths

protected void removeDescendantToggledPaths(Enumeration<TreePath> toRemove)
Removes any descendants of the TreePaths in toRemove that have been expanded.

clearToggledPaths

protected void clearToggledPaths()
Clears the cache of toggled tree paths. This does NOT send out any TreeExpansionListener events.

createTreeModelListener

protected TreeModelListener createTreeModelListener()
Creates and returns an instance of TreeModelHandler. The returned object is responsible for updating the expanded state when the TreeModel changes.

For more information on what expanded state means, see the JTree description above.

removeDescendantSelectedPaths

protected boolean removeDescendantSelectedPaths(TreePath path,
                                                boolean includePath)
Removes any paths in the selection that are descendants of path. If includePath is true and path is selected, it will be removed from the selection.

Returns:
true if a descendant was selected
Since:
1.3

paramString

protected String paramString()
Returns a string representation of this JTree. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JTree.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JTree. For JTrees, the AccessibleContext takes the form of an AccessibleJTree. A new AccessibleJTree instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJTree that serves as the AccessibleContext of this JTree
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTree.AccessibleJTree

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTree.AccessibleJTree

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JTree.AccessibleJTree
All Implemented Interfaces:
Serializable, EventListener, AccessibleComponent, AccessibleExtendedComponent, AccessibleSelection, TreeExpansionListener, TreeModelListener, TreeSelectionListener
Enclosing class:
JTree
protected class JTree.AccessibleJTree
extends JComponent.AccessibleJComponent
implements AccessibleSelection, TreeSelectionListener, TreeModelListener, TreeExpansionListener

This class implements accessibility support for the JTree class. It provides an implementation of the Java Accessibility API appropriate to tree user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class JTree.AccessibleJTree.AccessibleJTreeNode
This class implements accessibility support for the JTree child.
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
JTree.AccessibleJTree()
Method Summary
void | addAccessibleSelection(int i) Adds the specified selected item in the object to the object's selection.
void | clearAccessibleSelection() Clears the selection in the object, so that nothing in the object is selected.
void | fireVisibleDataPropertyChange() Fire a visible data property change notification.
Accessible | getAccessibleAt(Point p) Returns the Accessible child, if one exists, contained at the local coordinate Point.
Accessible | getAccessibleChild(int i) Return the nth Accessible child of the object.
int | getAccessibleChildrenCount() Returns the number of top-level children nodes of this JTree.
int | getAccessibleIndexInParent() Get the index of this object in its accessible parent.
AccessibleRole | getAccessibleRole() Get the role of this object.
AccessibleSelection | getAccessibleSelection() Get the AccessibleSelection associated with this object.
Accessible | getAccessibleSelection(int i) Returns an Accessible representing the specified selected item in the object.
int | getAccessibleSelectionCount() Returns the number of items currently selected.
boolean | isAccessibleChildSelected(int i) Returns true if the current child of this object is selected.
void | removeAccessibleSelection(int i) Removes the specified selected item in the object from the object's selection.
void | selectAllAccessibleSelection() Causes every selected item in the object to be selected if the object supports multiple selections.
void | treeCollapsed(TreeExpansionEvent e) Tree Collapsed notification.
void | treeExpanded(TreeExpansionEvent e) Tree Model Expansion notification.
void | treeNodesChanged(TreeModelEvent e) Tree Model Node change notification.
void | treeNodesInserted(TreeModelEvent e) Tree Model Node change notification.
void | treeNodesRemoved(TreeModelEvent e) Tree Model Node change notification.
void | treeStructureChanged(TreeModelEvent e) Tree Model structure change change notification.
void | valueChanged(TreeSelectionEvent e) Tree Selection Listener value change method.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JTree.AccessibleJTree

public JTree.AccessibleJTree()
Method Detail

valueChanged

public void valueChanged(TreeSelectionEvent e)
Tree Selection Listener value change method. Used to fire the property change

Specified by:
valueChanged in interface TreeSelectionListener
Parameters:
e - ListSelectionEvent

fireVisibleDataPropertyChange

public void fireVisibleDataPropertyChange()
Fire a visible data property change notification. A 'visible' data property is one that represents something about the way the component appears on the display, where that appearance isn't bound to any other property. It notifies screen readers that the visual appearance of the component has changed, so they can notify the user.

treeNodesChanged

public void treeNodesChanged(TreeModelEvent e)
Tree Model Node change notification.

Specified by:
treeNodesChanged in interface TreeModelListener
Parameters:
e - a Tree Model event

treeNodesInserted

public void treeNodesInserted(TreeModelEvent e)
Tree Model Node change notification.

Specified by:
treeNodesInserted in interface TreeModelListener
Parameters:
e - a Tree node insertion event

treeNodesRemoved

public void treeNodesRemoved(TreeModelEvent e)
Tree Model Node change notification.

Specified by:
treeNodesRemoved in interface TreeModelListener
Parameters:
e - a Tree node(s) removal event

treeStructureChanged

public void treeStructureChanged(TreeModelEvent e)
Tree Model structure change change notification.

Specified by:
treeStructureChanged in interface TreeModelListener
Parameters:
e - a Tree Model event

treeCollapsed

public void treeCollapsed(TreeExpansionEvent e)
Tree Collapsed notification.

Specified by:
treeCollapsed in interface TreeExpansionListener
Parameters:
e - a TreeExpansionEvent

treeExpanded

public void treeExpanded(TreeExpansionEvent e)
Tree Model Expansion notification.

Specified by:
treeExpanded in interface TreeExpansionListener
Parameters:
e - a Tree node insertion event

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleAt

public Accessible getAccessibleAt(Point p)
Returns the Accessible child, if one exists, contained at the local coordinate Point. Otherwise returns null.

Specified by:
getAccessibleAt in interface AccessibleComponent
Overrides:
getAccessibleAt in class Container.AccessibleAWTContainer
Parameters:
p - point in local coordinates of this Accessible
Returns:
the Accessible, if it exists, at the specified location; else null

getAccessibleChildrenCount

public int getAccessibleChildrenCount()
Returns the number of top-level children nodes of this JTree. Each of these nodes may in turn have children nodes.

Overrides:
getAccessibleChildrenCount in class JComponent.AccessibleJComponent
Returns:
the number of accessible children nodes in the tree.

getAccessibleChild

public Accessible getAccessibleChild(int i)
Return the nth Accessible child of the object.

Overrides:
getAccessibleChild in class JComponent.AccessibleJComponent
Parameters:
i - zero-based index of child
Returns:
the nth Accessible child of the object
See Also:
AccessibleContext.getAccessibleChildrenCount()

getAccessibleIndexInParent

public int getAccessibleIndexInParent()
Get the index of this object in its accessible parent.

Overrides:
getAccessibleIndexInParent in class Component.AccessibleAWTComponent
Returns:
the index of this object in its parent. Since a JTree top-level object does not have an accessible parent.
See Also:
Component.AccessibleAWTComponent.getAccessibleParent()

getAccessibleSelection

public AccessibleSelection getAccessibleSelection()
Get the AccessibleSelection associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleSelection interface on behalf of itself.

Overrides:
getAccessibleSelection in class AccessibleContext
Returns:
this object
See Also:
AccessibleSelection

getAccessibleSelectionCount

public int getAccessibleSelectionCount()
Returns the number of items currently selected. If no items are selected, the return value will be 0.

Specified by:
getAccessibleSelectionCount in interface AccessibleSelection
Returns:
the number of items currently selected.

getAccessibleSelection

public Accessible getAccessibleSelection(int i)
Returns an Accessible representing the specified selected item in the object. If there isn't a selection, or there are fewer items selected than the integer passed in, the return value will be null.

Specified by:
getAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of selected items
Returns:
an Accessible containing the selected item
See Also:
AccessibleSelection.getAccessibleSelectionCount()

isAccessibleChildSelected

public boolean isAccessibleChildSelected(int i)
Returns true if the current child of this object is selected.

Specified by:
isAccessibleChildSelected in interface AccessibleSelection
Parameters:
i - the zero-based index of the child in this Accessible object.
Returns:
true if the current child of this object is selected; else false.
See Also:
AccessibleContext.getAccessibleChild(int)

addAccessibleSelection

public void addAccessibleSelection(int i)
Adds the specified selected item in the object to the object's selection. If the object supports multiple selections, the specified item is added to any existing selection, otherwise it replaces any existing selection in the object. If the specified item is already selected, this method has no effect.

Specified by:
addAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of selectable items
See Also:
AccessibleContext.getAccessibleChild(int)

removeAccessibleSelection

public void removeAccessibleSelection(int i)
Removes the specified selected item in the object from the object's selection. If the specified item isn't currently selected, this method has no effect.

Specified by:
removeAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of selectable items
See Also:
AccessibleContext.getAccessibleChild(int)

clearAccessibleSelection

public void clearAccessibleSelection()
Clears the selection in the object, so that nothing in the object is selected.

Specified by:
clearAccessibleSelection in interface AccessibleSelection

selectAllAccessibleSelection

public void selectAllAccessibleSelection()
Causes every selected item in the object to be selected if the object supports multiple selections.

Specified by:
selectAllAccessibleSelection in interface AccessibleSelection
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTree.AccessibleJTree.AccessibleJTreeNode

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTree.AccessibleJTree.AccessibleJTreeNode

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  javax.swing.JTree.AccessibleJTree.AccessibleJTreeNode
All Implemented Interfaces:
Accessible, AccessibleAction, AccessibleComponent, AccessibleSelection
Enclosing class:
JTree.AccessibleJTree
protected class JTree.AccessibleJTree.AccessibleJTreeNode
extends AccessibleContext
implements Accessible, AccessibleComponent, AccessibleSelection, AccessibleAction

This class implements accessibility support for the JTree child. It provides an implementation of the Java Accessibility API appropriate to tree nodes.

Field Summary
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Constructor Summary
JTree.AccessibleJTree.AccessibleJTreeNode(JTree t, TreePath p, Accessible ap)
Constructs an AccessibleJTreeNode
Method Summary
void | addAccessibleSelection(int i) Adds the specified selected item in the object to the object's selection.
void | addFocusListener(FocusListener l) Adds the specified focus listener to receive focus events from this component.
void | addPropertyChangeListener(PropertyChangeListener l) Add a PropertyChangeListener to the listener list.
void | clearAccessibleSelection() Clears the selection in the object, so that nothing in the object is selected.
boolean | contains(Point p) Checks whether the specified point is within this object's bounds, where the point's x and y coordinates are defined to be relative to the coordinate system of the object.
boolean | doAccessibleAction(int i) Perform the specified Action on the tree node.
AccessibleAction | getAccessibleAction() Get the AccessibleAction associated with this object.
int | getAccessibleActionCount() Returns the number of accessible actions available in this tree node.
String | getAccessibleActionDescription(int i) Return a description of the specified action of the tree node.
Accessible | getAccessibleAt(Point p) Returns the Accessible child, if one exists, contained at the local coordinate Point.
Accessible | getAccessibleChild(int i) Return the specified Accessible child of the object.
int | getAccessibleChildrenCount() Returns the number of accessible children in the object.
AccessibleComponent | getAccessibleComponent() Get the AccessibleComponent associated with this object.
AccessibleContext | getAccessibleContext() Get the AccessibleContext associated with this tree node.
String | getAccessibleDescription() Get the accessible description of this object.
int | getAccessibleIndexInParent() Get the index of this object in its accessible parent.
String | getAccessibleName() Get the accessible name of this object.
Accessible | getAccessibleParent() Get the Accessible parent of this object.
AccessibleRole | getAccessibleRole() Get the role of this object.
AccessibleSelection | getAccessibleSelection() Get the AccessibleSelection associated with this object if one exists.
Accessible | getAccessibleSelection(int i) Returns an Accessible representing the specified selected item in the object.
int | getAccessibleSelectionCount() Returns the number of items currently selected.
AccessibleStateSet | getAccessibleStateSet() Get the state set of this object.
AccessibleText | getAccessibleText() Get the AccessibleText associated with this object if one exists.
AccessibleValue | getAccessibleValue() Get the AccessibleValue associated with this object if one exists.
Color | getBackground() Get the background color of this object.
Rectangle | getBounds() Gets the bounds of this object in the form of a Rectangle object.
Cursor | getCursor() Gets the Cursor of this object.
Font | getFont() Gets the Font of this object.
FontMetrics | getFontMetrics(Font f) Gets the FontMetrics of this object.
Color | getForeground() Get the foreground color of this object.
Locale | getLocale() Gets the locale of the component.
Point | getLocation() Gets the location of the object relative to the parent in the form of a point specifying the object's top-left corner in the screen's coordinate space.
protected Point | getLocationInJTree()
Point | getLocationOnScreen() Returns the location of the object on the screen.
Dimension | getSize() Returns the size of this object in the form of a Dimension object.
boolean | isAccessibleChildSelected(int i) Returns true if the current child of this object is selected.
boolean | isEnabled() Determines if the object is enabled.
boolean | isFocusTraversable() Returns whether this object can accept focus or not.
boolean | isShowing() Determines if the object is showing.
boolean | isVisible() Determines if the object is visible.
void | removeAccessibleSelection(int i) Removes the specified selected item in the object from the object's selection.
void | removeFocusListener(FocusListener l) Removes the specified focus listener so it no longer receives focus events from this component.
void | removePropertyChangeListener(PropertyChangeListener l) Remove a PropertyChangeListener from the listener list.
void | requestFocus() Requests focus for this object.
void | selectAllAccessibleSelection() Causes every selected item in the object to be selected if the object supports multiple selections.
void | setAccessibleDescription(String s) Set the accessible description of this object.
void | setAccessibleName(String s) Set the localized accessible name of this object.
void | setBackground(Color c) Set the background color of this object.
void | setBounds(Rectangle r) Sets the bounds of this object in the form of a Rectangle object.
void | setCursor(Cursor c) Sets the Cursor of this object.
void | setEnabled(boolean b) Sets the enabled state of the object.
void | setFont(Font f) Sets the Font of this object.
void | setForeground(Color c) Sets the foreground color of this object.
void | setLocation(Point p) Sets the location of the object relative to the parent.
void | setSize(Dimension d) Resizes this object so that it has width and height.
void | setVisible(boolean b) Sets the visible state of the object.
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleTable, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JTree.AccessibleJTree.AccessibleJTreeNode

public JTree.AccessibleJTree.AccessibleJTreeNode(JTree t,
                                                 TreePath p,
                                                 Accessible ap)
Constructs an AccessibleJTreeNode

Since:
1.4
Method Detail

getAccessibleContext

public AccessibleContext getAccessibleContext()
Get the AccessibleContext associated with this tree node. In the implementation of the Java Accessibility API for this class, return this object, which is its own AccessibleContext.

Specified by:
getAccessibleContext in interface Accessible
Returns:
this object

getAccessibleName

public String getAccessibleName()
Get the accessible name of this object.

Overrides:
getAccessibleName in class AccessibleContext
Returns:
the localized name of the object; null if this object does not have a name
See Also:
AccessibleContext.setAccessibleName(java.lang.String)

setAccessibleName

public void setAccessibleName(String s)
Set the localized accessible name of this object.

Overrides:
setAccessibleName in class AccessibleContext
Parameters:
s - the new localized name of the object.
See Also:
AccessibleContext.getAccessibleName(), AccessibleContext.addPropertyChangeListener(java.beans.PropertyChangeListener)

getAccessibleDescription

public String getAccessibleDescription()
Get the accessible description of this object.

Overrides:
getAccessibleDescription in class AccessibleContext
Returns:
the localized description of the object; null if this object does not have a description
See Also:
AccessibleContext.setAccessibleDescription(java.lang.String)

setAccessibleDescription

public void setAccessibleDescription(String s)
Set the accessible description of this object.

Overrides:
setAccessibleDescription in class AccessibleContext
Parameters:
s - the new localized description of the object
See Also:
AccessibleContext.setAccessibleName(java.lang.String), AccessibleContext.addPropertyChangeListener(java.beans.PropertyChangeListener)

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Specified by:
getAccessibleRole in class AccessibleContext
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Get the state set of this object.

Specified by:
getAccessibleStateSet in class AccessibleContext
Returns:
an instance of AccessibleStateSet containing the current state set of the object
See Also:
AccessibleState

getAccessibleParent

public Accessible getAccessibleParent()
Get the Accessible parent of this object.

Overrides:
getAccessibleParent in class AccessibleContext
Returns:
the Accessible parent of this object; null if this object does not have an Accessible parent

getAccessibleIndexInParent

public int getAccessibleIndexInParent()
Get the index of this object in its accessible parent.

Specified by:
getAccessibleIndexInParent in class AccessibleContext
Returns:
the index of this object in its parent; -1 if this object does not have an accessible parent.
See Also:
getAccessibleParent()

getAccessibleChildrenCount

public int getAccessibleChildrenCount()
Returns the number of accessible children in the object.

Specified by:
getAccessibleChildrenCount in class AccessibleContext
Returns:
the number of accessible children in the object.

getAccessibleChild

public Accessible getAccessibleChild(int i)
Return the specified Accessible child of the object.

Specified by:
getAccessibleChild in class AccessibleContext
Parameters:
i - zero-based index of child
Returns:
the Accessible child of the object
See Also:
AccessibleContext.getAccessibleChildrenCount()

getLocale

public Locale getLocale()
Gets the locale of the component. If the component does not have a locale, then the locale of its parent is returned.

Specified by:
getLocale in class AccessibleContext
Returns:
This component's locale. If this component does not have a locale, the locale of its parent is returned.
Throws:
IllegalComponentStateException - If the Component does not have its own locale and has not yet been added to a containment hierarchy such that the locale can be determined from the containing parent.
See Also:
Component.setLocale(java.util.Locale)

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener l)
Add a PropertyChangeListener to the listener list. The listener is registered for all properties.

Overrides:
addPropertyChangeListener in class AccessibleContext
Parameters:
l - The PropertyChangeListener to be added
See Also:
AccessibleContext.ACCESSIBLE_NAME_PROPERTY, AccessibleContext.ACCESSIBLE_DESCRIPTION_PROPERTY, AccessibleContext.ACCESSIBLE_STATE_PROPERTY, AccessibleContext.ACCESSIBLE_VALUE_PROPERTY, AccessibleContext.ACCESSIBLE_SELECTION_PROPERTY, AccessibleContext.ACCESSIBLE_TEXT_PROPERTY, AccessibleContext.ACCESSIBLE_VISIBLE_DATA_PROPERTY

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener l)
Remove a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties.

Overrides:
removePropertyChangeListener in class AccessibleContext
Parameters:
l - The PropertyChangeListener to be removed

getAccessibleAction

public AccessibleAction getAccessibleAction()
Get the AccessibleAction associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleAction interface on behalf of itself.

Overrides:
getAccessibleAction in class AccessibleContext
Returns:
this object
See Also:
AccessibleAction

getAccessibleComponent

public AccessibleComponent getAccessibleComponent()
Get the AccessibleComponent associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleComponent interface on behalf of itself.

Overrides:
getAccessibleComponent in class AccessibleContext
Returns:
this object
See Also:
AccessibleComponent

getAccessibleSelection

public AccessibleSelection getAccessibleSelection()
Get the AccessibleSelection associated with this object if one exists. Otherwise return null.

Overrides:
getAccessibleSelection in class AccessibleContext
Returns:
the AccessibleSelection, or null
See Also:
AccessibleSelection

getAccessibleText

public AccessibleText getAccessibleText()
Get the AccessibleText associated with this object if one exists. Otherwise return null.

Overrides:
getAccessibleText in class AccessibleContext
Returns:
the AccessibleText, or null
See Also:
AccessibleText

getAccessibleValue

public AccessibleValue getAccessibleValue()
Get the AccessibleValue associated with this object if one exists. Otherwise return null.

Overrides:
getAccessibleValue in class AccessibleContext
Returns:
the AccessibleValue, or null
See Also:
AccessibleValue

getBackground

public Color getBackground()
Get the background color of this object.

Specified by:
getBackground in interface AccessibleComponent
Returns:
the background color, if supported, of the object; otherwise, null
See Also:
AccessibleComponent.setBackground(java.awt.Color)

setBackground

public void setBackground(Color c)
Set the background color of this object.

Specified by:
setBackground in interface AccessibleComponent
Parameters:
c - the new Color for the background
See Also:
AccessibleComponent.setBackground(java.awt.Color)

getForeground

public Color getForeground()
Get the foreground color of this object.

Specified by:
getForeground in interface AccessibleComponent
Returns:
the foreground color, if supported, of the object; otherwise, null
See Also:
AccessibleComponent.setForeground(java.awt.Color)

setForeground

public void setForeground(Color c)
Description copied from interface: AccessibleComponent
Sets the foreground color of this object.

Specified by:
setForeground in interface AccessibleComponent
Parameters:
c - the new Color for the foreground
See Also:
AccessibleComponent.getForeground()

getCursor

public Cursor getCursor()
Description copied from interface: AccessibleComponent
Gets the Cursor of this object.

Specified by:
getCursor in interface AccessibleComponent
Returns:
the Cursor, if supported, of the object; otherwise, null
See Also:
AccessibleComponent.setCursor(java.awt.Cursor)

setCursor

public void setCursor(Cursor c)
Description copied from interface: AccessibleComponent
Sets the Cursor of this object.

Specified by:
setCursor in interface AccessibleComponent
Parameters:
c - the new Cursor for the object
See Also:
AccessibleComponent.getCursor()

getFont

public Font getFont()
Description copied from interface: AccessibleComponent
Gets the Font of this object.

Specified by:
getFont in interface AccessibleComponent
Returns:
the Font,if supported, for the object; otherwise, null
See Also:
AccessibleComponent.setFont(java.awt.Font)

setFont

public void setFont(Font f)
Description copied from interface: AccessibleComponent
Sets the Font of this object.

Specified by:
setFont in interface AccessibleComponent
Parameters:
f - the new Font for the object
See Also:
AccessibleComponent.getFont()

getFontMetrics

public FontMetrics getFontMetrics(Font f)
Description copied from interface: AccessibleComponent
Gets the FontMetrics of this object.

Specified by:
getFontMetrics in interface AccessibleComponent
Parameters:
f - the Font
Returns:
the FontMetrics, if supported, the object; otherwise, null
See Also:
AccessibleComponent.getFont()

isEnabled

public boolean isEnabled()
Description copied from interface: AccessibleComponent
Determines if the object is enabled. Objects that are enabled will also have the AccessibleState.ENABLED state set in their AccessibleStateSets.

Specified by:
isEnabled in interface AccessibleComponent
Returns:
true if object is enabled; otherwise, false
See Also:
AccessibleComponent.setEnabled(boolean), AccessibleContext.getAccessibleStateSet(), AccessibleState.ENABLED, AccessibleStateSet

setEnabled

public void setEnabled(boolean b)
Description copied from interface: AccessibleComponent
Sets the enabled state of the object.

Specified by:
setEnabled in interface AccessibleComponent
Parameters:
b - if true, enables this object; otherwise, disables it
See Also:
AccessibleComponent.isEnabled()

isVisible

public boolean isVisible()
Description copied from interface: AccessibleComponent
Determines if the object is visible. Note: this means that the object intends to be visible; however, it may not be showing on the screen because one of the objects that this object is contained by is currently not visible. To determine if an object is showing on the screen, use isShowing().

Objects that are visible will also have the AccessibleState.VISIBLE state set in their AccessibleStateSets.

Specified by:
isVisible in interface AccessibleComponent
Returns:
true if object is visible; otherwise, false
See Also:
AccessibleComponent.setVisible(boolean), AccessibleContext.getAccessibleStateSet(), AccessibleState.VISIBLE, AccessibleStateSet

setVisible

public void setVisible(boolean b)
Description copied from interface: AccessibleComponent
Sets the visible state of the object.

Specified by:
setVisible in interface AccessibleComponent
Parameters:
b - if true, shows this object; otherwise, hides it
See Also:
AccessibleComponent.isVisible()

isShowing

public boolean isShowing()
Description copied from interface: AccessibleComponent
Determines if the object is showing. This is determined by checking the visibility of the object and its ancestors. Note: this will return true even if the object is obscured by another (for example, it is underneath a menu that was pulled down).

Specified by:
isShowing in interface AccessibleComponent
Returns:
true if object is showing; otherwise, false

contains

public boolean contains(Point p)
Description copied from interface: AccessibleComponent
Checks whether the specified point is within this object's bounds, where the point's x and y coordinates are defined to be relative to the coordinate system of the object.

Specified by:
contains in interface AccessibleComponent
Parameters:
p - the Point relative to the coordinate system of the object
Returns:
true if object contains Point; otherwise false
See Also:
AccessibleComponent.getBounds()

getLocationOnScreen

public Point getLocationOnScreen()
Description copied from interface: AccessibleComponent
Returns the location of the object on the screen.

Specified by:
getLocationOnScreen in interface AccessibleComponent
Returns:
the location of the object on screen; null if this object is not on the screen
See Also:
AccessibleComponent.getBounds(), AccessibleComponent.getLocation()

getLocationInJTree

protected Point getLocationInJTree()

getLocation

public Point getLocation()
Description copied from interface: AccessibleComponent
Gets the location of the object relative to the parent in the form of a point specifying the object's top-left corner in the screen's coordinate space.

Specified by:
getLocation in interface AccessibleComponent
Returns:
An instance of Point representing the top-left corner of the object's bounds in the coordinate space of the screen; null if this object or its parent are not on the screen
See Also:
AccessibleComponent.getBounds(), AccessibleComponent.getLocationOnScreen()

setLocation

public void setLocation(Point p)
Description copied from interface: AccessibleComponent
Sets the location of the object relative to the parent.

Specified by:
setLocation in interface AccessibleComponent
Parameters:
p - the new position for the top-left corner
See Also:
AccessibleComponent.getLocation()

getBounds

public Rectangle getBounds()
Description copied from interface: AccessibleComponent
Gets the bounds of this object in the form of a Rectangle object. The bounds specify this object's width, height, and location relative to its parent.

Specified by:
getBounds in interface AccessibleComponent
Returns:
A rectangle indicating this component's bounds; null if this object is not on the screen.
See Also:
AccessibleComponent.contains(java.awt.Point)

setBounds

public void setBounds(Rectangle r)
Description copied from interface: AccessibleComponent
Sets the bounds of this object in the form of a Rectangle object. The bounds specify this object's width, height, and location relative to its parent.

Specified by:
setBounds in interface AccessibleComponent
Parameters:
r - rectangle indicating this component's bounds
See Also:
AccessibleComponent.getBounds()

getSize

public Dimension getSize()
Description copied from interface: AccessibleComponent
Returns the size of this object in the form of a Dimension object. The height field of the Dimension object contains this object's height, and the width field of the Dimension object contains this object's width.

Specified by:
getSize in interface AccessibleComponent
Returns:
A Dimension object that indicates the size of this component; null if this object is not on the screen
See Also:
AccessibleComponent.setSize(java.awt.Dimension)

setSize

public void setSize(Dimension d)
Description copied from interface: AccessibleComponent
Resizes this object so that it has width and height.

Specified by:
setSize in interface AccessibleComponent
Parameters:
d - The dimension specifying the new size of the object.
See Also:
AccessibleComponent.getSize()

getAccessibleAt

public Accessible getAccessibleAt(Point p)
Returns the Accessible child, if one exists, contained at the local coordinate Point. Otherwise returns null.

Specified by:
getAccessibleAt in interface AccessibleComponent
Parameters:
p - point in local coordinates of this Accessible
Returns:
the Accessible, if it exists, at the specified location; else null

isFocusTraversable

public boolean isFocusTraversable()
Description copied from interface: AccessibleComponent
Returns whether this object can accept focus or not. Objects that can accept focus will also have the AccessibleState.FOCUSABLE state set in their AccessibleStateSets.

Specified by:
isFocusTraversable in interface AccessibleComponent
Returns:
true if object can accept focus; otherwise false
See Also:
AccessibleContext.getAccessibleStateSet(), AccessibleState.FOCUSABLE, AccessibleState.FOCUSED, AccessibleStateSet

requestFocus

public void requestFocus()
Description copied from interface: AccessibleComponent
Requests focus for this object. If this object cannot accept focus, nothing will happen. Otherwise, the object will attempt to take focus.

Specified by:
requestFocus in interface AccessibleComponent
See Also:
AccessibleComponent.isFocusTraversable()

addFocusListener

public void addFocusListener(FocusListener l)
Description copied from interface: AccessibleComponent
Adds the specified focus listener to receive focus events from this component.

Specified by:
addFocusListener in interface AccessibleComponent
Parameters:
l - the focus listener
See Also:
AccessibleComponent.removeFocusListener(java.awt.event.FocusListener)

removeFocusListener

public void removeFocusListener(FocusListener l)
Description copied from interface: AccessibleComponent
Removes the specified focus listener so it no longer receives focus events from this component.

Specified by:
removeFocusListener in interface AccessibleComponent
Parameters:
l - the focus listener
See Also:
AccessibleComponent.addFocusListener(java.awt.event.FocusListener)

getAccessibleSelectionCount

public int getAccessibleSelectionCount()
Returns the number of items currently selected. If no items are selected, the return value will be 0.

Specified by:
getAccessibleSelectionCount in interface AccessibleSelection
Returns:
the number of items currently selected.

getAccessibleSelection

public Accessible getAccessibleSelection(int i)
Returns an Accessible representing the specified selected item in the object. If there isn't a selection, or there are fewer items selected than the integer passed in, the return value will be null.

Specified by:
getAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of selected items
Returns:
an Accessible containing the selected item
See Also:
AccessibleSelection.getAccessibleSelectionCount()

isAccessibleChildSelected

public boolean isAccessibleChildSelected(int i)
Returns true if the current child of this object is selected.

Specified by:
isAccessibleChildSelected in interface AccessibleSelection
Parameters:
i - the zero-based index of the child in this Accessible object.
Returns:
true if the current child of this object is selected; else false.
See Also:
AccessibleContext.getAccessibleChild(int)

addAccessibleSelection

public void addAccessibleSelection(int i)
Adds the specified selected item in the object to the object's selection. If the object supports multiple selections, the specified item is added to any existing selection, otherwise it replaces any existing selection in the object. If the specified item is already selected, this method has no effect.

Specified by:
addAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of selectable items
See Also:
AccessibleContext.getAccessibleChild(int)

removeAccessibleSelection

public void removeAccessibleSelection(int i)
Removes the specified selected item in the object from the object's selection. If the specified item isn't currently selected, this method has no effect.

Specified by:
removeAccessibleSelection in interface AccessibleSelection
Parameters:
i - the zero-based index of selectable items
See Also:
AccessibleContext.getAccessibleChild(int)

clearAccessibleSelection

public void clearAccessibleSelection()
Clears the selection in the object, so that nothing in the object is selected.

Specified by:
clearAccessibleSelection in interface AccessibleSelection

selectAllAccessibleSelection

public void selectAllAccessibleSelection()
Causes every selected item in the object to be selected if the object supports multiple selections.

Specified by:
selectAllAccessibleSelection in interface AccessibleSelection

getAccessibleActionCount

public int getAccessibleActionCount()
Returns the number of accessible actions available in this tree node. If this node is not a leaf, there is at least one action (toggle expand), in addition to any available on the object behind the TreeCellRenderer.

Specified by:
getAccessibleActionCount in interface AccessibleAction
Returns:
the number of Actions in this object

getAccessibleActionDescription

public String getAccessibleActionDescription(int i)
Return a description of the specified action of the tree node. If this node is not a leaf, there is at least one action description (toggle expand), in addition to any available on the object behind the TreeCellRenderer.

Specified by:
getAccessibleActionDescription in interface AccessibleAction
Parameters:
i - zero-based index of the actions
Returns:
a description of the action
See Also:
AccessibleAction.getAccessibleActionCount()

doAccessibleAction

public boolean doAccessibleAction(int i)
Perform the specified Action on the tree node. If this node is not a leaf, there is at least one action which can be done (toggle expand), in addition to any available on the object behind the TreeCellRenderer.

Specified by:
doAccessibleAction in interface AccessibleAction
Parameters:
i - zero-based index of actions
Returns:
true if the the action was performed; else false.
See Also:
AccessibleAction.getAccessibleActionCount()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTree.DropLocation

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTree.DropLocation

java.lang.Object
    extended by  javax.swing.TransferHandler.DropLocation
        extended by  javax.swing.JTree.DropLocation
Enclosing class:
JTree
public static final class JTree.DropLocation
extends TransferHandler.DropLocation

A subclass of TransferHandler.DropLocation representing a drop location for a JTree.

Since:
1.6
See Also:
JTree.getDropLocation()

Method Summary
 int getChildIndex()
Returns the index where the dropped data should be inserted with respect to the path returned by getPath().
 TreePath getPath()
Returns the path where dropped data should be placed in the tree.
 String toString()
Returns a string representation of this drop location.
Methods inherited from class javax.swing.TransferHandler.DropLocation
getDropPoint
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getChildIndex

public int getChildIndex()
Returns the index where the dropped data should be inserted with respect to the path returned by getPath().

For drop modes DropMode.USE_SELECTION and DropMode.ON, this index is unimportant (and it will always be -1) as the only interesting data is the path over which the drop operation occurred.

For drop mode DropMode.INSERT, this index indicates the index at which the data should be inserted into the parent path represented by getPath(). -1 indicates that the drop occurred over the parent itself, and in most cases should be treated as inserting into either the beginning or the end of the parent's list of children.

For DropMode.ON_OR_INSERT, this value will be an insert index, as described above, or -1 if the drop occurred over the path itself.

Returns:
the child index
See Also:
getPath()

getPath

public TreePath getPath()
Returns the path where dropped data should be placed in the tree.

Interpretation of this value depends on the drop mode set on the component. If the drop mode is DropMode.USE_SELECTION or DropMode.ON, the return value is the path in the tree over which the data has been (or will be) dropped. null indicates that the drop is over empty space, not associated with a particular path.

If the drop mode is DropMode.INSERT, the return value refers to the path that should become the parent of the new data, in which case getChildIndex() indicates where the new item should be inserted into this parent path. A null path indicates that no parent path has been determined, which can happen for multiple reasons:

  • The tree has no model
  • There is no root in the tree
  • The root is collapsed
  • The root is a leaf node
It is up to the developer to decide if and how they wish to handle the null case.

If the drop mode is DropMode.ON_OR_INSERT, getChildIndex can be used to determine whether the drop is on top of the path itself (-1) or the index at which it should be inserted into the path (values other than -1).

Returns:
the drop path
See Also:
getChildIndex()

toString

public String toString()
Returns a string representation of this drop location. This method is intended to be used for debugging purposes, and the content and format of the returned string may vary between implementations.

Overrides:
toString in class TransferHandler.DropLocation
Returns:
a string representation of this drop location
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTree.DynamicUtilTreeNode

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTree.DynamicUtilTreeNode

java.lang.Object
    extended by  javax.swing.tree.DefaultMutableTreeNode
        extended by  javax.swing.JTree.DynamicUtilTreeNode
All Implemented Interfaces:
Serializable, Cloneable, MutableTreeNode, TreeNode
Enclosing class:
JTree
public static class JTree.DynamicUtilTreeNode
extends DefaultMutableTreeNode

DynamicUtilTreeNode can wrap vectors/hashtables/arrays/strings and create the appropriate children tree nodes as necessary. It is dynamic in that it will only create the children as necessary.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected Object | childValue Value to create children with.
protected boolean | hasChildren Does the this JTree have children? This property is currently not implemented.
protected boolean | loadedChildren Have the children been loaded yet?
Fields inherited from class javax.swing.tree.DefaultMutableTreeNode
allowsChildren, children, EMPTY_ENUMERATION, parent, userObject
Constructor Summary
JTree.DynamicUtilTreeNode(Object value, Object children)
Creates a node with the specified object as its value and with the specified children.
Method Summary
Enumeration | children() Subclassed to load the children, if necessary.
static void | createChildren(DefaultMutableTreeNode parent, Object children) Adds to parent all the children in children.
TreeNode | getChildAt(int index) Subclassed to load the children, if necessary.
int | getChildCount() Returns the number of child nodes.
boolean | isLeaf() Returns true if this node allows children.
protected void | loadChildren() Loads the children based on childValue.
Methods inherited from class javax.swing.tree.DefaultMutableTreeNode
add, breadthFirstEnumeration, clone, depthFirstEnumeration, getAllowsChildren, getChildAfter, getChildBefore, getDepth, getFirstChild, getFirstLeaf, getIndex, getLastChild, getLastLeaf, getLeafCount, getLevel, getNextLeaf, getNextNode, getNextSibling, getParent, getPath, getPathToRoot, getPreviousLeaf, getPreviousNode, getPreviousSibling, getRoot, getSharedAncestor, getSiblingCount, getUserObject, getUserObjectPath, insert, isNodeAncestor, isNodeChild, isNodeDescendant, isNodeRelated, isNodeSibling, isRoot, pathFromAncestorEnumeration, postorderEnumeration, preorderEnumeration, remove, remove, removeAllChildren, removeFromParent, setAllowsChildren, setParent, setUserObject, toString
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

hasChildren

protected boolean hasChildren
Does the this JTree have children? This property is currently not implemented.

childValue

protected Object childValue
Value to create children with.

loadedChildren

protected boolean loadedChildren
Have the children been loaded yet?

Constructor Detail

JTree.DynamicUtilTreeNode

public JTree.DynamicUtilTreeNode(Object value,
                                 Object children)
Creates a node with the specified object as its value and with the specified children. For the node to allow children, the children-object must be an array of objects, a Vector, or a Hashtable -- even if empty. Otherwise, the node is not allowed to have children.

Parameters:
value - the Object that is the value for the new node
children - an array of Objects, a Vector, or a Hashtable used to create the child nodes; if any other object is specified, or if the value is null, then the node is not allowed to have children
Method Detail

createChildren

public static void createChildren(DefaultMutableTreeNode parent,
                                  Object children)
Adds to parent all the children in children. If children is an array or vector all of its elements are added is children, otherwise if children is a hashtable all the key/value pairs are added in the order Enumeration returns them.

isLeaf

public boolean isLeaf()
Returns true if this node allows children. Whether the node allows children depends on how it was created.

Specified by:
isLeaf in interface TreeNode
Overrides:
isLeaf in class DefaultMutableTreeNode
Returns:
true if this node allows children, false otherwise
See Also:
JTree.DynamicUtilTreeNode(java.lang.Object, java.lang.Object)

getChildCount

public int getChildCount()
Returns the number of child nodes.

Specified by:
getChildCount in interface TreeNode
Overrides:
getChildCount in class DefaultMutableTreeNode
Returns:
the number of child nodes

loadChildren

protected void loadChildren()
Loads the children based on childValue. If childValue is a Vector or array each element is added as a child, if childValue is a Hashtable each key/value pair is added in the order that Enumeration returns the keys.

getChildAt

public TreeNode getChildAt(int index)
Subclassed to load the children, if necessary.

Specified by:
getChildAt in interface TreeNode
Overrides:
getChildAt in class DefaultMutableTreeNode
Parameters:
index - an index into this node's child array
Returns:
the TreeNode in this node's child array at the specified index

children

public Enumeration children()
Subclassed to load the children, if necessary.

Specified by:
children in interface TreeNode
Overrides:
children in class DefaultMutableTreeNode
Returns:
an Enumeration of this node's children
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTree.EmptySelectionModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTree.EmptySelectionModel

java.lang.Object
    extended by  javax.swing.tree.DefaultTreeSelectionModel
        extended by  javax.swing.JTree.EmptySelectionModel
All Implemented Interfaces:
Serializable, Cloneable, TreeSelectionModel
Enclosing class:
JTree
protected static class JTree.EmptySelectionModel
extends DefaultTreeSelectionModel

EmptySelectionModel is a TreeSelectionModel that does not allow anything to be selected.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected static JTree.EmptySelectionModel sharedInstance
Unique shared instance.
Fields inherited from class javax.swing.tree.DefaultTreeSelectionModel
changeSupport, leadIndex, leadPath, leadRow, listenerList, listSelectionModel, rowMapper, selection, SELECTION_MODE_PROPERTY, selectionMode
Fields inherited from interface javax.swing.tree.TreeSelectionModel
CONTIGUOUS_TREE_SELECTION, DISCONTIGUOUS_TREE_SELECTION, SINGLE_TREE_SELECTION
Constructor Summary
protected JTree.EmptySelectionModel()
Method Summary
void | addSelectionPaths(TreePath[] paths) A null implementation that adds nothing.
void | removeSelectionPaths(TreePath[] paths) A null implementation that removes nothing.
void | setSelectionPaths(TreePath[] pPaths) A null implementation that selects nothing.
static JTree.EmptySelectionModel | sharedInstance() Returns a shared instance of an empty selection model.
Methods inherited from class javax.swing.tree.DefaultTreeSelectionModel
addPropertyChangeListener, addSelectionPath, addTreeSelectionListener, arePathsContiguous, canPathsBeAdded, canPathsBeRemoved, clearSelection, clone, fireValueChanged, getLeadSelectionPath, getLeadSelectionRow, getListeners, getMaxSelectionRow, getMinSelectionRow, getPropertyChangeListeners, getRowMapper, getSelectionCount, getSelectionMode, getSelectionPath, getSelectionPaths, getSelectionRows, getTreeSelectionListeners, insureRowContinuity, insureUniqueness, isPathSelected, isRowSelected, isSelectionEmpty, notifyPathChange, removePropertyChangeListener, removeSelectionPath, removeTreeSelectionListener, resetRowSelection, setRowMapper, setSelectionMode, setSelectionPath, toString, updateLeadIndex
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

sharedInstance

protected static final JTree.EmptySelectionModel sharedInstance
Unique shared instance.

Constructor Detail

JTree.EmptySelectionModel

protected JTree.EmptySelectionModel()
Method Detail

sharedInstance

public static JTree.EmptySelectionModel sharedInstance()
Returns a shared instance of an empty selection model.

setSelectionPaths

public void setSelectionPaths(TreePath[] pPaths)
A null implementation that selects nothing.

Specified by:
setSelectionPaths in interface TreeSelectionModel
Overrides:
setSelectionPaths in class DefaultTreeSelectionModel
Parameters:
pPaths - new selection

addSelectionPaths

public void addSelectionPaths(TreePath[] paths)
A null implementation that adds nothing.

Specified by:
addSelectionPaths in interface TreeSelectionModel
Overrides:
addSelectionPaths in class DefaultTreeSelectionModel
Parameters:
paths - the new path to add to the current selection

removeSelectionPaths

public void removeSelectionPaths(TreePath[] paths)
A null implementation that removes nothing.

Specified by:
removeSelectionPaths in interface TreeSelectionModel
Overrides:
removeSelectionPaths in class DefaultTreeSelectionModel
Parameters:
paths - the paths to remove from the selection
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTree.TreeModelHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTree.TreeModelHandler

java.lang.Object
    extended by  javax.swing.JTree.TreeModelHandler
All Implemented Interfaces:
EventListener, TreeModelListener
Enclosing class:
JTree
protected class JTree.TreeModelHandler
extends Object
implements TreeModelListener

Listens to the model and updates the expandedState accordingly when nodes are removed, or changed.

Constructor Summary
protected JTree.TreeModelHandler()
Method Summary
void | treeNodesChanged(TreeModelEvent e) Invoked after a node (or a set of siblings) has changed in some way.
void | treeNodesInserted(TreeModelEvent e) Invoked after nodes have been inserted into the tree.
void | treeNodesRemoved(TreeModelEvent e) Invoked after nodes have been removed from the tree.
void | treeStructureChanged(TreeModelEvent e) Invoked after the tree has drastically changed structure from a given node down.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JTree.TreeModelHandler

protected JTree.TreeModelHandler()
Method Detail

treeNodesChanged

public void treeNodesChanged(TreeModelEvent e)
Description copied from interface: TreeModelListener

Invoked after a node (or a set of siblings) has changed in some way. The node(s) have not changed locations in the tree or altered their children arrays, but other attributes have changed and may affect presentation. Example: the name of a file has changed, but it is in the same location in the file system.

To indicate the root has changed, childIndices and children will be null.

Use e.getPath() to get the parent of the changed node(s). e.getChildIndices() returns the index(es) of the changed node(s).

Specified by:
treeNodesChanged in interface TreeModelListener

treeNodesInserted

public void treeNodesInserted(TreeModelEvent e)
Description copied from interface: TreeModelListener

Invoked after nodes have been inserted into the tree.

Use e.getPath() to get the parent of the new node(s). e.getChildIndices() returns the index(es) of the new node(s) in ascending order.

Specified by:
treeNodesInserted in interface TreeModelListener

treeStructureChanged

public void treeStructureChanged(TreeModelEvent e)
Description copied from interface: TreeModelListener

Invoked after the tree has drastically changed structure from a given node down. If the path returned by e.getPath() is of length one and the first element does not identify the current root node the first element should become the new root of the tree.

Use e.getPath() to get the path to the node. e.getChildIndices() returns null.

Specified by:
treeStructureChanged in interface TreeModelListener

treeNodesRemoved

public void treeNodesRemoved(TreeModelEvent e)
Description copied from interface: TreeModelListener

Invoked after nodes have been removed from the tree. Note that if a subtree is removed from the tree, this method may only be invoked once for the root of the removed subtree, not once for each individual set of siblings removed.

Use e.getPath() to get the former parent of the deleted node(s). e.getChildIndices() returns, in ascending order, the index(es) the node(s) had before being deleted.

Specified by:
treeNodesRemoved in interface TreeModelListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTree.TreeSelectionRedirector

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JTree.TreeSelectionRedirector

java.lang.Object
    extended by  javax.swing.JTree.TreeSelectionRedirector
All Implemented Interfaces:
Serializable, EventListener, TreeSelectionListener
Enclosing class:
JTree
protected class JTree.TreeSelectionRedirector
extends Object
implements Serializable, TreeSelectionListener

Handles creating a new TreeSelectionEvent with the JTree as the source and passing it off to all the listeners.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
protected JTree.TreeSelectionRedirector()
Method Summary
 void valueChanged(TreeSelectionEvent e)
Invoked by the TreeSelectionModel when the selection changes.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JTree.TreeSelectionRedirector

protected JTree.TreeSelectionRedirector()
Method Detail

valueChanged

public void valueChanged(TreeSelectionEvent e)
Invoked by the TreeSelectionModel when the selection changes.

Specified by:
valueChanged in interface TreeSelectionListener
Parameters:
e - the TreeSelectionEvent generated by the TreeSelectionModel
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JViewport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JViewport

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JViewport
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public class JViewport
extends JComponent
implements Accessible

The "viewport" or "porthole" through which you see the underlying information. When you scroll, what moves is the viewport. It is like peering through a camera's viewfinder. Moving the viewfinder upwards brings new things into view at the top of the picture and loses things that were at the bottom.

By default, JViewport is opaque. To change this, use the setOpaque method.

NOTE:We have implemented a faster scrolling algorithm that does not require a buffer to draw in. The algorithm works as follows:

  1. The view and parent view and checked to see if they are JComponents, if they aren't, stop and repaint the whole viewport.
  2. If the viewport is obscured by an ancestor, stop and repaint the whole viewport.
  3. Compute the region that will become visible, if it is as big as the viewport, stop and repaint the whole view region.
  4. Obtain the ancestor Window's graphics and do a copyArea on the scrolled region.
  5. Message the view to repaint the newly visible region.
  6. The next time paint is invoked on the viewport, if the clip region is smaller than the viewport size a timer is kicked off to repaint the whole region.
In general this approach is much faster. Compared to the backing store approach this avoids the overhead of maintaining an offscreen buffer and having to do two copyAreas. Compared to the non backing store case this approach will greatly reduce the painted region.

This approach can cause slower times than the backing store approach when the viewport is obscured by another window, or partially offscreen. When another window obscures the viewport the copyArea will copy garbage and a paint event will be generated by the system to inform us we need to paint the newly exposed region. The only way to handle this is to repaint the whole viewport, which can cause slower performance than the backing store case. In most applications very rarely will the user be scrolling while the viewport is obscured by another window or offscreen, so this optimization is usually worth the performance hit when obscured.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JScrollPane

Nested Class Summary
protected class | JViewport.AccessibleJViewport This class implements accessibility support for the JViewport class.
protected class | JViewport.ViewListener A listener for the view.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected boolean | backingStore Deprecated. As of Java 2 platform v1.3
static int | BACKINGSTORE_SCROLL_MODE Draws viewport contents into an offscreen image.
protected Image | backingStoreImage The view image used for a backing store.
static int | BLIT_SCROLL_MODE Use graphics.copyArea to implement scrolling.
protected boolean | isViewSizeSet True when the viewport dimensions have been determined.
protected Point | lastPaintPosition The last viewPosition that we've painted, so we know how much of the backing store image is valid.
protected boolean | scrollUnderway The scrollUnderway flag is used for components like JList.
static int | SIMPLE_SCROLL_MODE This mode uses the very simple method of redrawing the entire contents of the scrollpane each time it is scrolled.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JViewport()
Creates a JViewport.
Method Summary
 void addChangeListener(ChangeListener l)
Adds a ChangeListener to the list that is notified each time the view's size, position, or the viewport's extent size has changed.
protected  void addImpl(Component child, Object constraints, int index)
Sets the JViewport's one lightweight child, which can be null.
protected  boolean computeBlit(int dx, int dy, Point blitFrom, Point blitTo, Dimension blitSize, Rectangle blitPaint)
Computes the parameters for a blit where the backing store image currently contains oldLoc in the upper left hand corner and we're scrolling to newLoc.
protected  LayoutManager createLayoutManager()
Subclassers can override this to install a different layout manager (or null) in the constructor.
protected  JViewport.ViewListener createViewListener()
Creates a listener for the view.
protected  void firePropertyChange(String propertyName, Object oldValue, Object newValue)
Notifies listeners of a property change.
protected  void fireStateChanged()
Notifies all ChangeListeners when the views size, position, or the viewports extent size has changed.
 AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JViewport.
 ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this JViewport with addChangeListener().
 Dimension getExtentSize()
Returns the size of the visible part of the view in view coordinates.
 Insets getInsets()
Returns the insets (border) dimensions as (0,0,0,0), since borders are not supported on a JViewport.
 Insets getInsets(Insets insets)
Returns an Insets object containing this JViewports inset values.
 int getScrollMode()
Returns the current scrolling mode.
 ViewportUI getUI()
Returns the L&F object that renders this component.
 String getUIClassID()
Returns a string that specifies the name of the L&F class that renders this component.
 Component getView()
Returns the JViewport's one child or null.
 Point getViewPosition()
Returns the view coordinates that appear in the upper left hand corner of the viewport, or 0,0 if there's no view.
 Rectangle getViewRect()
Returns a rectangle whose origin is getViewPosition and size is getExtentSize.
 Dimension getViewSize()
If the view's size hasn't been explicitly set, return the preferred size, otherwise return the view's current size.
 boolean isBackingStoreEnabled()
Deprecated. As of Java 2 platform v1.3, replaced by getScrollMode().
 boolean isOptimizedDrawingEnabled()
The JViewport overrides the default implementation of this method (in JComponent) to return false.
 void paint(Graphics g)
Depending on whether the backingStore is enabled, either paint the image through the backing store or paint just the recently exposed part, using the backing store to "blit" the remainder.
protected  String paramString()
Returns a string representation of this JViewport.
 void remove(Component child)
Removes the Viewports one lightweight child.
 void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the list that's notified each time the views size, position, or the viewports extent size has changed.
 void repaint(long tm, int x, int y, int w, int h)
Always repaint in the parents coordinate system to make sure only one paint is performed by the RepaintManager.
 void reshape(int x, int y, int w, int h)
Sets the bounds of this viewport.
 void scrollRectToVisible(Rectangle contentRect)
Scrolls the view so that Rectangle within the view becomes visible.
 void setBackingStoreEnabled(boolean enabled)
Deprecated. As of Java 2 platform v1.3, replaced by setScrollMode().
 void setBorder(Border border)
The viewport "scrolls" its child (called the "view") by the normal parent/child clipping (typically the view is moved in the opposite direction of the scroll).
 void setExtentSize(Dimension newExtent)
Sets the size of the visible part of the view using view coordinates.
 void setScrollMode(int mode)
Used to control the method of scrolling the viewport contents.
 void setUI(ViewportUI ui)
Sets the L&F object that renders this component.
 void setView(Component view)
Sets the JViewport's one lightweight child (view), which can be null.
 void setViewPosition(Point p)
Sets the view coordinates that appear in the upper left hand corner of the viewport, does nothing if there's no view.
 void setViewSize(Dimension newSize)
Sets the size of the view.
 Dimension toViewCoordinates(Dimension size)
Converts a size in pixel coordinates to view coordinates.
 Point toViewCoordinates(Point p)
Converts a point in pixel coordinates to view coordinates.
 void updateUI()
Resets the UI property to a value from the current look and feel.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, revalidate, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

isViewSizeSet

protected boolean isViewSizeSet
True when the viewport dimensions have been determined. The default is false.

lastPaintPosition

protected Point lastPaintPosition
The last viewPosition that we've painted, so we know how much of the backing store image is valid.

backingStore

@Deprecated
protected boolean backingStore
Deprecated. As of Java 2 platform v1.3
True when this viewport is maintaining an offscreen image of its contents, so that some scrolling can take place using fast "bit-blit" operations instead of by accessing the view object to construct the display. The default is false.

See Also:
setScrollMode(int)

backingStoreImage

protected transient Image backingStoreImage
The view image used for a backing store.

scrollUnderway

protected boolean scrollUnderway
The scrollUnderway flag is used for components like JList. When the downarrow key is pressed on a JList and the selected cell is the last in the list, the scrollpane autoscrolls. Here, the old selected cell needs repainting and so we need a flag to make the viewport do the optimized painting only when there is an explicit call to setViewPosition(Point). When setBounds is called through other routes, the flag is off and the view repaints normally. Another approach would be to remove this from the JViewport class and have the JList manage this case by using setBackingStoreEnabled. The default is false.

BLIT_SCROLL_MODE

public static final int BLIT_SCROLL_MODE
Use graphics.copyArea to implement scrolling. This is the fastest for most applications.

Since:
1.3
See Also:
setScrollMode(int), Constant Field Values

BACKINGSTORE_SCROLL_MODE

public static final int BACKINGSTORE_SCROLL_MODE
Draws viewport contents into an offscreen image. This was previously the default mode for JTable. This mode may offer advantages over "blit mode" in some cases, but it requires a large chunk of extra RAM.

Since:
1.3
See Also:
setScrollMode(int), Constant Field Values

SIMPLE_SCROLL_MODE

public static final int SIMPLE_SCROLL_MODE
This mode uses the very simple method of redrawing the entire contents of the scrollpane each time it is scrolled. This was the default behavior in Swing 1.0 and Swing 1.1. Either of the other two options will provide better performance in most cases.

Since:
1.3
See Also:
setScrollMode(int), Constant Field Values
Constructor Detail

JViewport

public JViewport()
Creates a JViewport.

Method Detail

getUI

public ViewportUI getUI()
Returns the L&F object that renders this component.

Returns:
a ViewportUI object
Since:
1.3

setUI

public void setUI(ViewportUI ui)
Sets the L&F object that renders this component.

Parameters:
ui - the ViewportUI L&F object
Since:
1.3
See Also:
UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Resets the UI property to a value from the current look and feel.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns a string that specifies the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "ViewportUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

addImpl

protected void addImpl(Component child,
                       Object constraints,
                       int index)
Sets the JViewport's one lightweight child, which can be null. (Since there is only one child which occupies the entire viewport, the constraints and index arguments are ignored.)

Overrides:
addImpl in class Container
Parameters:
child - the lightweight child of the viewport
constraints - the constraints to be respected
index - the index
See Also:
setView(java.awt.Component)

remove

public void remove(Component child)
Removes the Viewports one lightweight child.

Overrides:
remove in class Container
Parameters:
child - the component to be removed
See Also:
setView(java.awt.Component)

scrollRectToVisible

public void scrollRectToVisible(Rectangle contentRect)
Scrolls the view so that Rectangle within the view becomes visible.

This attempts to validate the view before scrolling if the view is currently not valid - isValid returns false. To avoid excessive validation when the containment hierarchy is being created this will not validate if one of the ancestors does not have a peer, or there is no validate root ancestor, or one of the ancestors is not a Window or Applet.

Note that this method will not scroll outside of the valid viewport; for example, if contentRect is larger than the viewport, scrolling will be confined to the viewport's bounds.

Overrides:
scrollRectToVisible in class JComponent
Parameters:
contentRect - the Rectangle to display
See Also:
JComponent.isValidateRoot(),
Component.isValid(),
Component.getPeer()

setBorder

public final void setBorder(Border border)
The viewport "scrolls" its child (called the "view") by the normal parent/child clipping (typically the view is moved in the opposite direction of the scroll). A non-null border, or non-zero insets, isn't supported, to prevent the geometry of this component from becoming complex enough to inhibit subclassing. To create a JViewport with a border, add it to a JPanel that has a border.

Note: If border is non-null, this method will throw an exception as borders are not supported on a JViewPort.

Overrides:
setBorder in class JComponent
Parameters:
border - the Border to set
Throws:
IllegalArgumentException - this method is not implemented
See Also:
Border, CompoundBorder

getInsets

public final Insets getInsets()
Returns the insets (border) dimensions as (0,0,0,0), since borders are not supported on a JViewport.

Overrides:
getInsets in class JComponent
Returns:
a Rectange of zero dimension and zero origin
See Also:
setBorder(javax.swing.border.Border)

getInsets

public final Insets getInsets(Insets insets)
Returns an Insets object containing this JViewports inset values. The passed-in Insets object will be reinitialized, and all existing values within this object are overwritten.

Overrides:
getInsets in class JComponent
Parameters:
insets - the Insets object which can be reused
Returns:
this viewports inset values
See Also:
getInsets()

isOptimizedDrawingEnabled

public boolean isOptimizedDrawingEnabled()
The JViewport overrides the default implementation of this method (in JComponent) to return false. This ensures that the drawing machinery will call the Viewport's paint implementation rather than messaging the JViewport's children directly.

Overrides:
isOptimizedDrawingEnabled in class JComponent
Returns:
false

paint

public void paint(Graphics g)
Depending on whether the backingStore is enabled, either paint the image through the backing store or paint just the recently exposed part, using the backing store to "blit" the remainder.
The term "blit" is the pronounced version of the PDP-10 BLT (BLock Transfer) instruction, which copied a block of bits. (In case you were curious.)

Overrides:
paint in class JComponent
Parameters:
g - the Graphics context within which to paint
See Also:
JComponent.paintComponent(java.awt.Graphics),
JComponent.paintBorder(java.awt.Graphics),
JComponent.paintChildren(java.awt.Graphics),
JComponent.getComponentGraphics(java.awt.Graphics),
JComponent.repaint(long, int, int, int, int)

reshape

public void reshape(int x,
                    int y,
                    int w,
                    int h)
Sets the bounds of this viewport. If the viewport's width or height has changed, fire a StateChanged event.

Overrides:
reshape in class JComponent
Parameters:
x - left edge of the origin
y - top edge of the origin
w - width in pixels
h - height in pixels
See Also:
JComponent.reshape(int, int, int, int)

setScrollMode

public void setScrollMode(int mode)
Used to control the method of scrolling the viewport contents. You may want to change this mode to get maximum performance for your use case.

Parameters:
mode - one of the following values:
  • JViewport.BLIT_SCROLL_MODE
  • JViewport.BACKINGSTORE_SCROLL_MODE
  • JViewport.SIMPLE_SCROLL_MODE
Since:
1.3
See Also:
BLIT_SCROLL_MODE, BACKINGSTORE_SCROLL_MODE, SIMPLE_SCROLL_MODE

getScrollMode

public int getScrollMode()
Returns the current scrolling mode.

Returns:
the scrollMode property
Since:
1.3
See Also:
setScrollMode(int)

isBackingStoreEnabled

@Deprecated
public boolean isBackingStoreEnabled()
Deprecated. As of Java 2 platform v1.3, replaced by getScrollMode().

Returns true if this viewport is maintaining an offscreen image of its contents.

Returns:
true if scrollMode is BACKINGSTORE_SCROLL_MODE

setBackingStoreEnabled

@Deprecated
public void setBackingStoreEnabled(boolean enabled)
Deprecated. As of Java 2 platform v1.3, replaced by setScrollMode().

If true if this viewport will maintain an offscreen image of its contents. The image is used to reduce the cost of small one dimensional changes to the viewPosition. Rather than repainting the entire viewport we use Graphics.copyArea to effect some of the scroll.

Parameters:
enabled - if true, maintain an offscreen backing store

getView

public Component getView()
Returns the JViewport's one child or null.

Returns:
the viewports child, or null if none exists
See Also:
setView(java.awt.Component)

setView

public void setView(Component view)
Sets the JViewport's one lightweight child (view), which can be null.

Parameters:
view - the viewport's new lightweight child
See Also:
getView()

getViewSize

public Dimension getViewSize()
If the view's size hasn't been explicitly set, return the preferred size, otherwise return the view's current size. If there is no view, return 0,0.

Returns:
a Dimension object specifying the size of the view

setViewSize

public void setViewSize(Dimension newSize)
Sets the size of the view. A state changed event will be fired.

Parameters:
newSize - a Dimension object specifying the new size of the view

getViewPosition

public Point getViewPosition()
Returns the view coordinates that appear in the upper left hand corner of the viewport, or 0,0 if there's no view.

Returns:
a Point object giving the upper left coordinates

setViewPosition

public void setViewPosition(Point p)
Sets the view coordinates that appear in the upper left hand corner of the viewport, does nothing if there's no view.

Parameters:
p - a Point object giving the upper left coordinates

getViewRect

public Rectangle getViewRect()
Returns a rectangle whose origin is getViewPosition and size is getExtentSize. This is the visible part of the view, in view coordinates.

Returns:
a Rectangle giving the visible part of the view using view coordinates.

computeBlit

protected boolean computeBlit(int dx,
                              int dy,
                              Point blitFrom,
                              Point blitTo,
                              Dimension blitSize,
                              Rectangle blitPaint)
Computes the parameters for a blit where the backing store image currently contains oldLoc in the upper left hand corner and we're scrolling to newLoc. The parameters are modified to return the values required for the blit.

Parameters:
dx - the horizontal delta
dy - the vertical delta
blitFrom - the Point we're blitting from
blitTo - the Point we're blitting to
blitSize - the Dimension of the area to blit
blitPaint - the area to blit
Returns:
true if the parameters are modified and we're ready to blit; false otherwise

getExtentSize

public Dimension getExtentSize()
Returns the size of the visible part of the view in view coordinates.

Returns:
a Dimension object giving the size of the view

toViewCoordinates

public Dimension toViewCoordinates(Dimension size)
Converts a size in pixel coordinates to view coordinates. Subclasses of viewport that support "logical coordinates" will override this method.

Parameters:
size - a Dimension object using pixel coordinates
Returns:
a Dimension object converted to view coordinates

toViewCoordinates

public Point toViewCoordinates(Point p)
Converts a point in pixel coordinates to view coordinates. Subclasses of viewport that support "logical coordinates" will override this method.

Parameters:
p - a Point object using pixel coordinates
Returns:
a Point object converted to view coordinates

setExtentSize

public void setExtentSize(Dimension newExtent)
Sets the size of the visible part of the view using view coordinates.

Parameters:
newExtent - a Dimension object specifying the size of the view

createViewListener

protected JViewport.ViewListener createViewListener()
Creates a listener for the view.

Returns:
a ViewListener

createLayoutManager

protected LayoutManager createLayoutManager()
Subclassers can override this to install a different layout manager (or null) in the constructor. Returns the LayoutManager to install on the JViewport.

Returns:
a LayoutManager

addChangeListener

public void addChangeListener(ChangeListener l)
Adds a ChangeListener to the list that is notified each time the view's size, position, or the viewport's extent size has changed.

Parameters:
l - the ChangeListener to add
See Also:
removeChangeListener(javax.swing.event.ChangeListener),
setViewPosition(java.awt.Point),
setViewSize(java.awt.Dimension),
setExtentSize(java.awt.Dimension)

removeChangeListener

public void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the list that's notified each time the views size, position, or the viewports extent size has changed.

Parameters:
l - the ChangeListener to remove
See Also:
addChangeListener(javax.swing.event.ChangeListener)

getChangeListeners

public ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this JViewport with addChangeListener().

Returns:
all of the ChangeListeners added or an empty array if no listeners have been added
Since:
1.4

fireStateChanged

protected void fireStateChanged()
Notifies all ChangeListeners when the views size, position, or the viewports extent size has changed.

See Also:
addChangeListener(javax.swing.event.ChangeListener), removeChangeListener(javax.swing.event.ChangeListener), EventListenerList

repaint

public void repaint(long tm,
                    int x,
                    int y,
                    int w,
                    int h)
Always repaint in the parents coordinate system to make sure only one paint is performed by the RepaintManager.

Overrides:
repaint in class JComponent
Parameters:
tm - maximum time in milliseconds before update
x - the x coordinate (pixels over from left)
y - the y coordinate (pixels down from top)
w - the width
h - the height
See Also:
Component.update(java.awt.Graphics)

paramString

protected String paramString()
Returns a string representation of this JViewport. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JViewport

firePropertyChange

protected void firePropertyChange(String propertyName,
                                  Object oldValue,
                                  Object newValue)
Notifies listeners of a property change. This is subclassed to update the windowBlit property. (The putClientProperty property is final).

Overrides:
firePropertyChange in class Component
Parameters:
propertyName - a string containing the property name
oldValue - the old value of the property
newValue - the new value of the property

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JViewport. For viewports, the AccessibleContext takes the form of an AccessibleJViewport. A new AccessibleJViewport instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJViewport that serves as the AccessibleContext of this JViewport
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JViewport.AccessibleJViewport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JViewport.AccessibleJViewport

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.JViewport.AccessibleJViewport
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent
Enclosing class:
JViewport
protected class JViewport.AccessibleJViewport
extends JComponent.AccessibleJComponent

This class implements accessibility support for the JViewport class. It provides an implementation of the Java Accessibility API appropriate to viewport user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JViewport.AccessibleJViewport()
Method Summary
 AccessibleRole getAccessibleRole()
Get the role of this object.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JViewport.AccessibleJViewport

protected JViewport.AccessibleJViewport()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JViewport.ViewListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JViewport.ViewListener

java.lang.Object
    extended by  java.awt.event.ComponentAdapter
        extended by  javax.swing.JViewport.ViewListener
All Implemented Interfaces:
ComponentListener, Serializable, EventListener
Enclosing class:
JViewport
protected class JViewport.ViewListener
extends ComponentAdapter
implements Serializable

A listener for the view.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
protected JViewport.ViewListener()
Method Summary
 void componentResized(ComponentEvent e)
Invoked when the component's size changes.
Methods inherited from class java.awt.event.ComponentAdapter
componentHidden, componentMoved, componentShown
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JViewport.ViewListener

protected JViewport.ViewListener()
Method Detail

componentResized

public void componentResized(ComponentEvent e)
Description copied from class: ComponentAdapter
Invoked when the component's size changes.

Specified by:
componentResized in interface ComponentListener
Overrides:
componentResized in class ComponentAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JWindow

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JWindow

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  java.awt.Window
                extended by  javax.swing.JWindow
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, RootPaneContainer
public class JWindow
extends Window
implements Accessible, RootPaneContainer

A JWindow is a container that can be displayed anywhere on the user's desktop. It does not have the title bar, window-management buttons, or other trimmings associated with a JFrame, but it is still a "first-class citizen" of the user's desktop, and can exist anywhere on it.

The JWindow component contains a JRootPane as its only child. The contentPane should be the parent of any children of the JWindow. As a conveniance add and its variants, remove and setLayout have been overridden to forward to the contentPane as necessary. This means you can write:

       window.add(child);
And the child will be added to the contentPane. The contentPane will always be non-null. Attempting to set it to null will cause the JWindow to throw an exception. The default contentPane will have a BorderLayout manager set on it. Refer to RootPaneContainer for details on adding, removing and setting the LayoutManager of a JWindow.

Please see the JRootPane documentation for a complete description of the contentPane, glassPane, and layeredPane components.

In a multi-screen environment, you can create a JWindow on a different screen device. See Window for more information.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JRootPane

Nested Class Summary
protected  class JWindow.AccessibleJWindow
This class implements accessibility support for the JWindow class.
Nested classes/interfaces inherited from class java.awt.Window
Window.AccessibleAWTWindow
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected AccessibleContext | accessibleContext The accessible context property.
protected JRootPane | rootPane The JRootPane instance that manages the contentPane and optional menuBar for this frame, as well as the glassPane.
protected boolean | rootPaneCheckingEnabled If true then calls to add and setLayout will be forwarded to the contentPane.
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JWindow()
Creates a window with no specified owner.
JWindow(Frame owner)
Creates a window with the specified owner frame.
JWindow(GraphicsConfiguration gc)
Creates a window with the specified GraphicsConfiguration of a screen device.
JWindow(Window owner)
Creates a window with the specified owner window.
JWindow(Window owner, GraphicsConfiguration gc)
Creates a window with the specified owner window and GraphicsConfiguration of a screen device.
Method Summary
protected void | addImpl(Component comp, Object constraints, int index) Adds the specified child Component.
protected JRootPane | createRootPane() Called by the constructor methods to create the default rootPane.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JWindow.
Container | getContentPane() Returns the Container which is the contentPane for this window.
Component | getGlassPane() Returns the glassPane Component for this window.
Graphics | getGraphics() Creates a graphics context for this component.
JLayeredPane | getLayeredPane() Returns the layeredPane object for this window.
JRootPane | getRootPane() Returns the rootPane object for this window.
TransferHandler | getTransferHandler() Gets the transferHandler property.
protected boolean | isRootPaneCheckingEnabled() Returns whether calls to add and setLayout are forwarded to the contentPane.
protected String | paramString() Returns a string representation of this JWindow.
void | remove(Component comp) Removes the specified component from the container.
void | repaint(long time, int x, int y, int width, int height) Repaints the specified rectangle of this component within time milliseconds.
void | setContentPane(Container contentPane) Sets the contentPane property for this window.
void | setGlassPane(Component glassPane) Sets the glassPane property.
void | setLayeredPane(JLayeredPane layeredPane) Sets the layeredPane property.
void | setLayout(LayoutManager manager) Sets the LayoutManager.
protected void | setRootPane(JRootPane root) Sets the new rootPane object for this window.
protected void | setRootPaneCheckingEnabled(boolean enabled) Sets whether calls to add and setLayout are forwarded to the contentPane.
void | setTransferHandler(TransferHandler newHandler) Sets the transferHandler property, which is a mechanism to support transfer of data into this component.
void | update(Graphics g) Calls paint(g).
protected void | windowInit() Called by the constructors to init the JWindow properly.
Methods inherited from class java.awt.Window
addNotify, addPropertyChangeListener, addPropertyChangeListener, addWindowFocusListener, addWindowListener, addWindowStateListener, applyResourceBundle, applyResourceBundle, createBufferStrategy, createBufferStrategy, dispose, getBufferStrategy, getFocusableWindowState, getFocusCycleRootAncestor, getFocusOwner, getFocusTraversalKeys, getGraphicsConfiguration, getIconImages, getInputContext, getListeners, getLocale, getModalExclusionType, getMostRecentFocusOwner, getOwnedWindows, getOwner, getOwnerlessWindows, getToolkit, getWarningString, getWindowFocusListeners, getWindowListeners, getWindows, getWindowStateListeners, hide, isActive, isAlwaysOnTop, isAlwaysOnTopSupported, isFocusableWindow, isFocusCycleRoot, isFocused, isLocationByPlatform, isShowing, pack, postEvent, processEvent, processWindowEvent, processWindowFocusEvent, processWindowStateEvent, removeNotify, removeWindowFocusListener, removeWindowListener, removeWindowStateListener, reshape, setAlwaysOnTop, setBounds, setBounds, setCursor, setFocusableWindowState, setFocusCycleRoot, setIconImage, setIconImages, setLocationByPlatform, setLocationRelativeTo, setMinimumSize, setModalExclusionType, setSize, setSize, setVisible, show, toBack, toFront
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalPolicy, getInsets, getLayout, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paint, paintComponents, preferredSize, print, printComponents, processContainerEvent, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resize, resize, setBackground, setComponentOrientation, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setName, setPreferredSize, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

rootPane

protected JRootPane rootPane
The JRootPane instance that manages the contentPane and optional menuBar for this frame, as well as the glassPane.

See Also:
getRootPane(), setRootPane(javax.swing.JRootPane)

rootPaneCheckingEnabled

protected boolean rootPaneCheckingEnabled
If true then calls to add and setLayout will be forwarded to the contentPane. This is initially false, but is set to true when the JWindow is constructed.

See Also:
isRootPaneCheckingEnabled(), setRootPaneCheckingEnabled(boolean), RootPaneContainer

accessibleContext

protected AccessibleContext accessibleContext
The accessible context property.

Constructor Detail

JWindow

public JWindow()
Creates a window with no specified owner. This window will not be focusable.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
GraphicsEnvironment.isHeadless(),
Window.isFocusableWindow(),
JComponent.getDefaultLocale()

JWindow

public JWindow(GraphicsConfiguration gc)
Creates a window with the specified GraphicsConfiguration of a screen device. This window will not be focusable.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
gc - the GraphicsConfiguration that is used to construct the new window with; if gc is null, the system default GraphicsConfiguration is assumed
Throws:
HeadlessException - If GraphicsEnvironment.isHeadless() returns true.
IllegalArgumentException - if gc is not from a screen device.
Since:
1.3
See Also:
GraphicsEnvironment.isHeadless(),
Window.isFocusableWindow(),
JComponent.getDefaultLocale()

JWindow

public JWindow(Frame owner)
Creates a window with the specified owner frame. If owner is null, the shared owner will be used and this window will not be focusable. Also, this window will not be focusable unless its owner is showing on the screen.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
owner - the frame from which the window is displayed
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
GraphicsEnvironment.isHeadless(),
Window.isFocusableWindow(),
JComponent.getDefaultLocale()

JWindow

public JWindow(Window owner)
Creates a window with the specified owner window. This window will not be focusable unless its owner is showing on the screen. If owner is null, the shared owner will be used and this window will not be focusable.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
owner - the window from which the window is displayed
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
See Also:
GraphicsEnvironment.isHeadless(),
Window.isFocusableWindow(),
JComponent.getDefaultLocale()

JWindow

public JWindow(Window owner,
               GraphicsConfiguration gc)
Creates a window with the specified owner window and GraphicsConfiguration of a screen device. If owner is null, the shared owner will be used and this window will not be focusable.

This constructor sets the component's locale property to the value returned by JComponent.getDefaultLocale.

Parameters:
owner - the window from which the window is displayed
gc - the GraphicsConfiguration that is used to construct the new window with; if gc is null, the system default GraphicsConfiguration is assumed, unless owner is also null, in which case the GraphicsConfiguration from the shared owner frame will be used.
Throws:
HeadlessException - if GraphicsEnvironment.isHeadless() returns true.
IllegalArgumentException - if gc is not from a screen device.
Since:
1.3
See Also:
GraphicsEnvironment.isHeadless(),
Window.isFocusableWindow(),
JComponent.getDefaultLocale()
Method Detail

windowInit

protected void windowInit()
Called by the constructors to init the JWindow properly.

createRootPane

protected JRootPane createRootPane()
Called by the constructor methods to create the default rootPane.

isRootPaneCheckingEnabled

protected boolean isRootPaneCheckingEnabled()
Returns whether calls to add and setLayout are forwarded to the contentPane.

Returns:
true if add and setLayout are fowarded; false otherwise
See Also:
addImpl(java.awt.Component, java.lang.Object, int), setLayout(java.awt.LayoutManager), setRootPaneCheckingEnabled(boolean), RootPaneContainer

setTransferHandler

public void setTransferHandler(TransferHandler newHandler)
Sets the transferHandler property, which is a mechanism to support transfer of data into this component. Use null if the component does not support data transfer operations.

If the system property suppressSwingDropSupport is false (the default) and the current drop target on this component is either null or not a user-set drop target, this method will change the drop target as follows: If newHandler is null it will clear the drop target. If not null it will install a new DropTarget.

Note: When used with JWindow, TransferHandler only provides data import capability, as the data export related methods are currently typed to JComponent.

Please see How to Use Drag and Drop and Data Transfer, a section in The Java Tutorial, for more information.

Parameters:
newHandler - the new TransferHandler
Since:
1.6
See Also:
TransferHandler, getTransferHandler(), Component.setDropTarget(java.awt.dnd.DropTarget)

getTransferHandler

public TransferHandler getTransferHandler()
Gets the transferHandler property.

Returns:
the value of the transferHandler property
Since:
1.6
See Also:
TransferHandler, setTransferHandler(javax.swing.TransferHandler)

update

public void update(Graphics g)
Calls paint(g). This method was overridden to prevent an unnecessary call to clear the background.

Overrides:
update in class Container
Parameters:
g - the Graphics context in which to paint
See Also:
Component.update(Graphics)

setRootPaneCheckingEnabled

protected void setRootPaneCheckingEnabled(boolean enabled)
Sets whether calls to add and setLayout are forwarded to the contentPane.

Parameters:
enabled - true if add and setLayout are forwarded, false if they should operate directly on the JWindow.
See Also:
addImpl(java.awt.Component, java.lang.Object, int),
setLayout(java.awt.LayoutManager),
isRootPaneCheckingEnabled(),
RootPaneContainer

addImpl

protected void addImpl(Component comp,
                       Object constraints,
                       int index)
Adds the specified child Component. This method is overridden to conditionally forward calls to the contentPane. By default, children are added to the contentPane instead of the frame, refer to RootPaneContainer for details.

Overrides:
addImpl in class Container
Parameters:
comp - the component to be enhanced
constraints - the constraints to be respected
index - the index
Throws:
IllegalArgumentException - if index is invalid
IllegalArgumentException - if adding the container's parent to itself
IllegalArgumentException - if adding a window to a container
See Also:
setRootPaneCheckingEnabled(boolean), RootPaneContainer

remove

public void remove(Component comp)
Removes the specified component from the container. If comp is not the rootPane, this will forward the call to the contentPane. This will do nothing if comp is not a child of the JWindow or contentPane.

Overrides:
remove in class Container
Parameters:
comp - the component to be removed
Throws:
NullPointerException - if comp is null
See Also:
Container.add(java.awt.Component), RootPaneContainer

setLayout

public void setLayout(LayoutManager manager)
Sets the LayoutManager. Overridden to conditionally forward the call to the contentPane. Refer to RootPaneContainer for more information.

Overrides:
setLayout in class Container
Parameters:
manager - the LayoutManager
See Also:
setRootPaneCheckingEnabled(boolean), RootPaneContainer

getRootPane

public JRootPane getRootPane()
Returns the rootPane object for this window.

Specified by:
getRootPane in interface RootPaneContainer
Returns:
the rootPane property for this window
See Also:
setRootPane(javax.swing.JRootPane), RootPaneContainer.getRootPane()

setRootPane

protected void setRootPane(JRootPane root)
Sets the new rootPane object for this window. This method is called by the constructor.

Parameters:
root - the new rootPane property
See Also:
getRootPane()

getContentPane

public Container getContentPane()
Returns the Container which is the contentPane for this window.

Specified by:
getContentPane in interface RootPaneContainer
Returns:
the contentPane property
See Also:
setContentPane(java.awt.Container), RootPaneContainer.getContentPane()

setContentPane

public void setContentPane(Container contentPane)
Sets the contentPane property for this window. This method is called by the constructor.

Specified by:
setContentPane in interface RootPaneContainer
Parameters:
contentPane - the new contentPane
Throws:
IllegalComponentStateException - (a runtime exception) if the content pane parameter is null
See Also:
getContentPane(), RootPaneContainer.setContentPane(java.awt.Container)

getLayeredPane

public JLayeredPane getLayeredPane()
Returns the layeredPane object for this window.

Specified by:
getLayeredPane in interface RootPaneContainer
Returns:
the layeredPane property
See Also:
setLayeredPane(javax.swing.JLayeredPane), RootPaneContainer.getLayeredPane()

setLayeredPane

public void setLayeredPane(JLayeredPane layeredPane)
Sets the layeredPane property. This method is called by the constructor.

Specified by:
setLayeredPane in interface RootPaneContainer
Parameters:
layeredPane - the new layeredPane object
Throws:
IllegalComponentStateException - (a runtime exception) if the content pane parameter is null
See Also:
getLayeredPane(), RootPaneContainer.setLayeredPane(javax.swing.JLayeredPane)

getGlassPane

public Component getGlassPane()
Returns the glassPane Component for this window.

Specified by:
getGlassPane in interface RootPaneContainer
Returns:
the glassPane property
See Also:
setGlassPane(java.awt.Component), RootPaneContainer.getGlassPane()

setGlassPane

public void setGlassPane(Component glassPane)
Sets the glassPane property. This method is called by the constructor.

Specified by:
setGlassPane in interface RootPaneContainer
Parameters:
glassPane - the glassPane object for this window
See Also:
getGlassPane(), RootPaneContainer.setGlassPane(java.awt.Component)

getGraphics

public Graphics getGraphics()
Creates a graphics context for this component. This method will return null if this component is currently not displayable.

Overrides:
getGraphics in class Component
Returns:
a graphics context for this component, or null if it has none
Since:
1.6
See Also:
Component.paint(java.awt.Graphics)

repaint

public void repaint(long time,
                    int x,
                    int y,
                    int width,
                    int height)
Repaints the specified rectangle of this component within time milliseconds. Refer to RepaintManager for details on how the repaint is handled.

Overrides:
repaint in class Component
Parameters:
time - maximum time in milliseconds before update
x - the x coordinate
y - the y coordinate
width - the width
height - the height
Since:
1.6
See Also:
RepaintManager

paramString

protected String paramString()
Returns a string representation of this JWindow. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class Container
Returns:
a string representation of this JWindow

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JWindow. For JWindows, the AccessibleContext takes the form of an AccessibleJWindow. A new AccessibleJWindow instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class Window
Returns:
an AccessibleJWindow that serves as the AccessibleContext of this JWindow
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JWindow.AccessibleJWindow

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class JWindow.AccessibleJWindow

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  java.awt.Window.AccessibleAWTWindow
                    extended by  javax.swing.JWindow.AccessibleJWindow
All Implemented Interfaces:
Serializable, AccessibleComponent
Enclosing class:
JWindow
protected class JWindow.AccessibleJWindow
extends Window.AccessibleAWTWindow

This class implements accessibility support for the JWindow class. It provides an implementation of the Java Accessibility API appropriate to window user-interface elements.

Nested Class Summary
Nested classes/interfaces inherited from class java.awt.Container.AccessibleAWTContainer
Container.AccessibleAWTContainer.AccessibleContainerHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class java.awt.Container.AccessibleAWTContainer
accessibleContainerHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JWindow.AccessibleJWindow()
Method Summary
Methods inherited from class java.awt.Window.AccessibleAWTWindow
getAccessibleRole, getAccessibleStateSet
Methods inherited from class java.awt.Container.AccessibleAWTContainer
addPropertyChangeListener, getAccessibleAt, getAccessibleChild, getAccessibleChildrenCount
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleDescription, getAccessibleIndexInParent, getAccessibleName, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, removePropertyChangeListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JWindow.AccessibleJWindow

protected JWindow.AccessibleJWindow()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


KeyStroke

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class KeyStroke

java.lang.Object
    extended by  java.awt.AWTKeyStroke
        extended by  javax.swing.KeyStroke
All Implemented Interfaces:
Serializable
public class KeyStroke
extends AWTKeyStroke

A KeyStroke represents a key action on the keyboard, or equivalent input device. KeyStrokes can correspond to only a press or release of a particular key, just as KEY_PRESSED and KEY_RELEASED KeyEvents do; alternately, they can correspond to typing a specific Java character, just as KEY_TYPED KeyEvents do. In all cases, KeyStrokes can specify modifiers (alt, shift, control, meta, altGraph, or a combination thereof) which must be present during the action for an exact match.

KeyStrokes are used to define high-level (semantic) action events. Instead of trapping every keystroke and throwing away the ones you are not interested in, those keystrokes you care about automatically initiate actions on the Components with which they are registered.

KeyStrokes are immutable, and are intended to be unique. Client code cannot create a KeyStroke; a variant of getKeyStroke must be used instead. These factory methods allow the KeyStroke implementation to cache and share instances efficiently.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
Keymap, getKeyStroke(char)

Method Summary
static KeyStroke | getKeyStroke(char keyChar) Returns a shared instance of a KeyStroke that represents a KEY_TYPED event for the specified character.
static KeyStroke | getKeyStroke(Character keyChar, int modifiers) Returns a shared instance of a KeyStroke that represents a KEY_TYPED event for the specified Character object and a set of modifiers.
static KeyStroke | getKeyStroke(char keyChar, boolean onKeyRelease) Deprecated. use getKeyStroke(char)
static KeyStroke | getKeyStroke(int keyCode, int modifiers) Returns a shared instance of a KeyStroke, given a numeric key code and a set of modifiers.
static KeyStroke | getKeyStroke(int keyCode, int modifiers, boolean onKeyRelease) Returns a shared instance of a KeyStroke, given a numeric key code and a set of modifiers, specifying whether the key is activated when it is pressed or released.
static KeyStroke | getKeyStroke(String s) Parses a string and returns a KeyStroke.
static KeyStroke | getKeyStrokeForEvent(KeyEvent anEvent) Returns a KeyStroke which represents the stroke which generated a given KeyEvent.
Methods inherited from class java.awt.AWTKeyStroke
equals, getAWTKeyStroke, getAWTKeyStroke, getAWTKeyStroke, getAWTKeyStroke, getAWTKeyStroke, getAWTKeyStrokeForEvent, getKeyChar, getKeyCode, getKeyEventType, getModifiers, hashCode, isOnKeyRelease, readResolve, registerSubclass, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

getKeyStroke

public static KeyStroke getKeyStroke(char keyChar)
Returns a shared instance of a KeyStroke that represents a KEY_TYPED event for the specified character.

Parameters:
keyChar - the character value for a keyboard key
Returns:
a KeyStroke object for that key

getKeyStroke

@Deprecated
public static KeyStroke getKeyStroke(char keyChar,
                                                boolean onKeyRelease)
Deprecated. use getKeyStroke(char)

Returns an instance of a KeyStroke, specifying whether the key is considered to be activated when it is pressed or released. Unlike all other factory methods in this class, the instances returned by this method are not necessarily cached or shared.

Parameters:
keyChar - the character value for a keyboard key
onKeyRelease - true if this KeyStroke corresponds to a key release; false otherwise.
Returns:
a KeyStroke object for that key

getKeyStroke

public static KeyStroke getKeyStroke(Character keyChar,
                                     int modifiers)
Returns a shared instance of a KeyStroke that represents a KEY_TYPED event for the specified Character object and a set of modifiers. Note that the first parameter is of type Character rather than char. This is to avoid inadvertent clashes with calls to getKeyStroke(int keyCode, int modifiers). The modifiers consist of any combination of following:
  • java.awt.event.InputEvent.SHIFT_DOWN_MASK
  • java.awt.event.InputEvent.CTRL_DOWN_MASK
  • java.awt.event.InputEvent.META_DOWN_MASK
  • java.awt.event.InputEvent.ALT_DOWN_MASK
  • java.awt.event.InputEvent.ALT_GRAPH_DOWN_MASK
The old modifiers listed below also can be used, but they are mapped to _DOWN_ modifiers.
  • java.awt.event.InputEvent.SHIFT_MASK
  • java.awt.event.InputEvent.CTRL_MASK
  • java.awt.event.InputEvent.META_MASK
  • java.awt.event.InputEvent.ALT_MASK
  • java.awt.event.InputEvent.ALT_GRAPH_MASK
also can be used, but they are mapped to _DOWN_ modifiers. Since these numbers are all different powers of two, any combination of them is an integer in which each bit represents a different modifier key. Use 0 to specify no modifiers.

Parameters:
keyChar - the Character object for a keyboard character
modifiers - a bitwise-ored combination of any modifiers
Returns:
an KeyStroke object for that key
Throws:
IllegalArgumentException - if keyChar is null
Since:
1.3
See Also:
InputEvent

getKeyStroke

public static KeyStroke getKeyStroke(int keyCode,
                                     int modifiers,
                                     boolean onKeyRelease)
Returns a shared instance of a KeyStroke, given a numeric key code and a set of modifiers, specifying whether the key is activated when it is pressed or released.

The "virtual key" constants defined in java.awt.event.KeyEvent can be used to specify the key code. For example:

  • java.awt.event.KeyEvent.VK_ENTER
  • java.awt.event.KeyEvent.VK_TAB
  • java.awt.event.KeyEvent.VK_SPACE
The modifiers consist of any combination of:
  • java.awt.event.InputEvent.SHIFT_DOWN_MASK
  • java.awt.event.InputEvent.CTRL_DOWN_MASK
  • java.awt.event.InputEvent.META_DOWN_MASK
  • java.awt.event.InputEvent.ALT_DOWN_MASK
  • java.awt.event.InputEvent.ALT_GRAPH_DOWN_MASK
The old modifiers
  • java.awt.event.InputEvent.SHIFT_MASK
  • java.awt.event.InputEvent.CTRL_MASK
  • java.awt.event.InputEvent.META_MASK
  • java.awt.event.InputEvent.ALT_MASK
  • java.awt.event.InputEvent.ALT_GRAPH_MASK
also can be used, but they are mapped to _DOWN_ modifiers. Since these numbers are all different powers of two, any combination of them is an integer in which each bit represents a different modifier key. Use 0 to specify no modifiers.

Parameters:
keyCode - an int specifying the numeric code for a keyboard key
modifiers - a bitwise-ored combination of any modifiers
onKeyRelease - true if the KeyStroke should represent a key release; false otherwise.
Returns:
a KeyStroke object for that key
See Also:
KeyEvent, InputEvent

getKeyStroke

public static KeyStroke getKeyStroke(int keyCode,
                                     int modifiers)
Returns a shared instance of a KeyStroke, given a numeric key code and a set of modifiers. The returned KeyStroke will correspond to a key press.

The "virtual key" constants defined in java.awt.event.KeyEvent can be used to specify the key code. For example:

  • java.awt.event.KeyEvent.VK_ENTER
  • java.awt.event.KeyEvent.VK_TAB
  • java.awt.event.KeyEvent.VK_SPACE
The modifiers consist of any combination of:
  • java.awt.event.InputEvent.SHIFT_DOWN_MASK
  • java.awt.event.InputEvent.CTRL_DOWN_MASK
  • java.awt.event.InputEvent.META_DOWN_MASK
  • java.awt.event.InputEvent.ALT_DOWN_MASK
  • java.awt.event.InputEvent.ALT_GRAPH_DOWN_MASK
The old modifiers
  • java.awt.event.InputEvent.SHIFT_MASK
  • java.awt.event.InputEvent.CTRL_MASK
  • java.awt.event.InputEvent.META_MASK
  • java.awt.event.InputEvent.ALT_MASK
  • java.awt.event.InputEvent.ALT_GRAPH_MASK
also can be used, but they are mapped to _DOWN_ modifiers. Since these numbers are all different powers of two, any combination of them is an integer in which each bit represents a different modifier key. Use 0 to specify no modifiers.

Parameters:
keyCode - an int specifying the numeric code for a keyboard key
modifiers - a bitwise-ored combination of any modifiers
Returns:
a KeyStroke object for that key
See Also:
KeyEvent, InputEvent

getKeyStrokeForEvent

public static KeyStroke getKeyStrokeForEvent(KeyEvent anEvent)
Returns a KeyStroke which represents the stroke which generated a given KeyEvent.

This method obtains the keyChar from a KeyTyped event, and the keyCode from a KeyPressed or KeyReleased event. The KeyEvent modifiers are obtained for all three types of KeyEvent.

Parameters:
anEvent - the KeyEvent from which to obtain the KeyStroke
Returns:
the KeyStroke that precipitated the event
Throws:
NullPointerException - if anEvent is null

getKeyStroke

public static KeyStroke getKeyStroke(String s)
Parses a string and returns a KeyStroke. The string must have the following syntax:
    <modifiers>* (<typedID> | <pressedReleasedID>)

    modifiers := shift | control | ctrl | meta | alt | altGraph
    typedID := typed <typedKey>
    typedKey := string of length 1 giving Unicode character.
    pressedReleasedID := (pressed | released) key
    key := KeyEvent key code name, i.e. the name following "VK_".
If typed, pressed or released is not specified, pressed is assumed. Here are some examples:
     "INSERT" => getKeyStroke(KeyEvent.VK_INSERT, 0);
     "control DELETE" => getKeyStroke(KeyEvent.VK_DELETE, InputEvent.CTRL_MASK);
     "alt shift X" => getKeyStroke(KeyEvent.VK_X, InputEvent.ALT_MASK | InputEvent.SHIFT_MASK);
     "alt shift released X" => getKeyStroke(KeyEvent.VK_X, InputEvent.ALT_MASK | InputEvent.SHIFT_MASK, true);
     "typed a" => getKeyStroke('a');
In order to maintain backward-compatibility, specifying a null String, or a String which is formatted incorrectly, returns null.

Parameters:
s - a String formatted as described above
Returns:
a KeyStroke object for that String, or null if the specified String is null, or is formatted incorrectly
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LayoutFocusTraversalPolicy

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class LayoutFocusTraversalPolicy

java.lang.Object
    extended by  java.awt.FocusTraversalPolicy
        extended by  javax.swing.InternalFrameFocusTraversalPolicy
            extended by  javax.swing.SortingFocusTraversalPolicy
                extended by  javax.swing.LayoutFocusTraversalPolicy
All Implemented Interfaces:
Serializable
public class LayoutFocusTraversalPolicy
extends SortingFocusTraversalPolicy
implements Serializable

A SortingFocusTraversalPolicy which sorts Components based on their size, position, and orientation. Based on their size and position, Components are roughly categorized into rows and columns. For a Container with horizontal orientation, columns run left-to-right or right-to-left, and rows run top- to-bottom. For a Container with vertical orientation, columns run top-to- bottom and rows run left-to-right or right-to-left. See ComponentOrientation for more information. All columns in a row are fully traversed before proceeding to the next row.

Since:
1.4
See Also:
ComponentOrientation

Constructor Summary
LayoutFocusTraversalPolicy()
Constructs a LayoutFocusTraversalPolicy.
Method Summary
protected boolean | accept(Component aComponent) Determines whether the specified Component is an acceptable choice as the new focus owner.
Component | getComponentAfter(Container aContainer, Component aComponent) Returns the Component that should receive the focus after aComponent.
Component | getComponentBefore(Container aContainer, Component aComponent) Returns the Component that should receive the focus before aComponent.
Component | getFirstComponent(Container aContainer) Returns the first Component in the traversal cycle.
Component | getLastComponent(Container aContainer) Returns the last Component in the traversal cycle.
Methods inherited from class javax.swing.SortingFocusTraversalPolicy
getComparator, getDefaultComponent, getImplicitDownCycleTraversal, setComparator, setImplicitDownCycleTraversal
Methods inherited from class javax.swing.InternalFrameFocusTraversalPolicy
getInitialComponent
Methods inherited from class java.awt.FocusTraversalPolicy
getInitialComponent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LayoutFocusTraversalPolicy

public LayoutFocusTraversalPolicy()
Constructs a LayoutFocusTraversalPolicy.

Method Detail

getComponentAfter

public Component getComponentAfter(Container aContainer,
                                   Component aComponent)
Returns the Component that should receive the focus after aComponent. aContainer must be a focus cycle root of aComponent.

By default, LayoutFocusTraversalPolicy implicitly transfers focus down- cycle. That is, during normal focus traversal, the Component traversed after a focus cycle root will be the focus-cycle-root's default Component to focus. This behavior can be disabled using the setImplicitDownCycleTraversal method.

If aContainer is focus traversal policy provider, the focus is always transferred down-cycle.

Overrides:
getComponentAfter in class SortingFocusTraversalPolicy
Parameters:
aContainer - a focus cycle root of aComponent or a focus traversal policy provider
aComponent - a (possibly indirect) child of aContainer, or aContainer itself
Returns:
the Component that should receive the focus after aComponent, or null if no suitable Component can be found
Throws:
IllegalArgumentException - if aContainer is not a focus cycle root of aComponent or a focus traversal policy provider, or if either aContainer or aComponent is null

getComponentBefore

public Component getComponentBefore(Container aContainer,
                                    Component aComponent)
Returns the Component that should receive the focus before aComponent. aContainer must be a focus cycle root of aComponent.

By default, LayoutFocusTraversalPolicy implicitly transfers focus down- cycle. That is, during normal focus traversal, the Component traversed after a focus cycle root will be the focus-cycle-root's default Component to focus. This behavior can be disabled using the setImplicitDownCycleTraversal method.

If aContainer is focus traversal policy provider, the focus is always transferred down-cycle.

Overrides:
getComponentBefore in class SortingFocusTraversalPolicy
Parameters:
aContainer - a focus cycle root of aComponent or a focus traversal policy provider
aComponent - a (possibly indirect) child of aContainer, or aContainer itself
Returns:
the Component that should receive the focus before aComponent, or null if no suitable Component can be found
Throws:
IllegalArgumentException - if aContainer is not a focus cycle root of aComponent or a focus traversal policy provider, or if either aContainer or aComponent is null

getFirstComponent

public Component getFirstComponent(Container aContainer)
Returns the first Component in the traversal cycle. This method is used to determine the next Component to focus when traversal wraps in the forward direction.

Overrides:
getFirstComponent in class SortingFocusTraversalPolicy
Parameters:
aContainer - a focus cycle root of aComponent or a focus traversal policy provider whose first Component is to be returned
Returns:
the first Component in the traversal cycle of aContainer, or null if no suitable Component can be found
Throws:
IllegalArgumentException - if aContainer is null

getLastComponent

public Component getLastComponent(Container aContainer)
Returns the last Component in the traversal cycle. This method is used to determine the next Component to focus when traversal wraps in the reverse direction.

Overrides:
getLastComponent in class SortingFocusTraversalPolicy
Parameters:
aContainer - a focus cycle root of aComponent or a focus traversal policy provider whose last Component is to be returned
Returns:
the last Component in the traversal cycle of aContainer, or null if no suitable Component can be found
Throws:
IllegalArgumentException - if aContainer is null

accept

protected boolean accept(Component aComponent)
Determines whether the specified Component is an acceptable choice as the new focus owner. This method performs the following sequence of operations:
  1. Checks whether aComponent is visible, displayable, enabled, and focusable. If any of these properties is false, this method returns false.
  2. If aComponent is an instance of JTable, returns true.
  3. If aComponent is an instance of JComboBox, then returns the value of aComponent.getUI().isFocusTraversable(aComponent).
  4. If aComponent is a JComponent with a JComponent.WHEN_FOCUSED InputMap that is neither null nor empty, returns true.
  5. Returns the value of DefaultFocusTraversalPolicy.accept(aComponent).

Overrides:
accept in class SortingFocusTraversalPolicy
Parameters:
aComponent - the Component whose fitness as a focus owner is to be tested
Returns:
true if aComponent is a valid choice for a focus owner; otherwise false
See Also:
Component.isVisible(),
Component.isDisplayable(),
Component.isEnabled(),
Component.isFocusable(),
ComboBoxUI.isFocusTraversable(javax.swing.JComboBox),
JComponent.getInputMap(int),
DefaultFocusTraversalPolicy.accept(java.awt.Component)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LayoutStyle

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class LayoutStyle

java.lang.Object
    extended by  javax.swing.LayoutStyle

public abstract class LayoutStyle
extends Object

LayoutStyle provides information about how to position components. This class is primarily useful for visual tools and layout managers. Most developers will not need to use this class.

You typically don't set or create a LayoutStyle. Instead use the static method getInstance to obtain the current instance.

Since:
1.6

Nested Class Summary
static class LayoutStyle.ComponentPlacement
ComponentPlacement is an enumeration of the possible ways two components can be placed relative to each other.
Constructor Summary
LayoutStyle()
Creates a new LayoutStyle.
Method Summary
abstract int | getContainerGap(JComponent component, int position, Container parent) Returns the amount of space to place between the component and specified edge of its parent.
static LayoutStyle | getInstance() Returns the shared instance of LayoutStyle.
abstract int | getPreferredGap(JComponent component1, JComponent component2, LayoutStyle.ComponentPlacement type, int position, Container parent) Returns the amount of space to use between two components.
static void | setInstance(LayoutStyle style) Sets the shared instance of LayoutStyle.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LayoutStyle

public LayoutStyle()
Creates a new LayoutStyle. You generally don't create a LayoutStyle. Instead use the method getInstance to obtain the current LayoutStyle.

Method Detail

setInstance

public static void setInstance(LayoutStyle style)
Sets the shared instance of LayoutStyle. Specifying null results in using the LayoutStyle from the current LookAndFeel.

Parameters:
style - the LayoutStyle, or null
See Also:
getInstance()

getInstance

public static LayoutStyle getInstance()
Returns the shared instance of LayoutStyle. If an instance has not been specified in setInstance, this will return the LayoutStyle from the current LookAndFeel.

Returns:
the shared instance of LayoutStyle
See Also:
LookAndFeel.getLayoutStyle()

getPreferredGap

public abstract int getPreferredGap(JComponent component1,
                                    JComponent component2,
                                    LayoutStyle.ComponentPlacement type,
                                    int position,
                                    Container parent)
Returns the amount of space to use between two components. The return value indicates the distance to place component2 relative to component1. For example, the following returns the amount of space to place between component2 and component1 when component2 is placed vertically above component1:
   int gap = getPreferredGap(component1, component2,
                             ComponentPlacement.RELATED,
                             SwingConstants.NORTH, parent);
The type parameter indicates the relation between the two components. If the two components will be contained in the same parent and are showing similar logically related items, use RELATED. If the two components will be contained in the same parent but show logically unrelated items use UNRELATED. Some look and feels may not distinguish between the RELATED and UNRELATED types.

The return value is not intended to take into account the current size and position of component2 or component1. The return value may take into consideration various properties of the components. For example, the space may vary based on font size, or the preferred size of the component.

Parameters:
component1 - the JComponent component2 is being placed relative to
component2 - the JComponent being placed
position - the position component2 is being placed relative to component1; one of SwingConstants.NORTH, SwingConstants.SOUTH, SwingConstants.EAST or SwingConstants.WEST
type - how the two components are being placed
parent - the parent of component2; this may differ from the actual parent and it may be null
Returns:
the amount of space to place between the two components
Throws:
NullPointerException - if component1, component2 or type is null
IllegalArgumentException - if position is not one of SwingConstants.NORTH, SwingConstants.SOUTH, SwingConstants.EAST or SwingConstants.WEST
Since:
1.6
See Also:
LookAndFeel.getLayoutStyle()

getContainerGap

public abstract int getContainerGap(JComponent component,
                                    int position,
                                    Container parent)
Returns the amount of space to place between the component and specified edge of its parent.

Parameters:
component - the JComponent being positioned
position - the position component is being placed relative to its parent; one of SwingConstants.NORTH, SwingConstants.SOUTH, SwingConstants.EAST or SwingConstants.WEST
parent - the parent of component; this may differ from the actual parent and may be null
Returns:
the amount of space to place between the component and specified edge
Throws:
IllegalArgumentException - if position is not one of SwingConstants.NORTH, SwingConstants.SOUTH, SwingConstants.EAST or SwingConstants.WEST
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LayoutStyle.ComponentPlacement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.swing
Enum LayoutStyle.ComponentPlacement

java.lang.Object
    extended by  java.lang.Enum<LayoutStyle.ComponentPlacement>
        extended by  javax.swing.LayoutStyle.ComponentPlacement
All Implemented Interfaces:
Serializable, Comparable<LayoutStyle.ComponentPlacement>
Enclosing class:
LayoutStyle
public static enum LayoutStyle.ComponentPlacement
extends Enum<LayoutStyle.ComponentPlacement>

ComponentPlacement is an enumeration of the possible ways two components can be placed relative to each other. ComponentPlacement is used by the LayoutStyle method getPreferredGap. Refer to LayoutStyle for more information.

Since:
1.6
See Also:
LayoutStyle.getPreferredGap(JComponent,JComponent, ComponentPlacement,int,Container)

Enum Constant Summary
INDENT
Enumeration value indicating the distance to indent a component is being requested.
RELATED
Enumeration value indicating the two components are visually related and will be placed in the same parent.
UNRELATED
Enumeration value indicating the two components are visually unrelated and will be placed in the same parent.
Method Summary
static LayoutStyle.ComponentPlacement | valueOf(String name) Returns the enum constant of this type with the specified name.
static LayoutStyle.ComponentPlacement[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

RELATED

public static final LayoutStyle.ComponentPlacement RELATED
Enumeration value indicating the two components are visually related and will be placed in the same parent. For example, a JLabel providing a label for a JTextField is typically visually associated with the JTextField; the constant RELATED is used for this.

UNRELATED

public static final LayoutStyle.ComponentPlacement UNRELATED
Enumeration value indicating the two components are visually unrelated and will be placed in the same parent. For example, groupings of components are usually visually separated; the constant UNRELATED is used for this.

INDENT

public static final LayoutStyle.ComponentPlacement INDENT
Enumeration value indicating the distance to indent a component is being requested. For example, often times the children of a label will be horizontally indented from the label. To determine the preferred distance for such a gap use the INDENT type.

This value is typically only useful with a direction of EAST or WEST.

Method Detail

values

public static LayoutStyle.ComponentPlacement[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (LayoutStyle.ComponentPlacement c : LayoutStyle.ComponentPlacement.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static LayoutStyle.ComponentPlacement valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


ListCellRenderer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface ListCellRenderer

All Known Implementing Classes:
BasicComboBoxRenderer, BasicComboBoxRenderer.UIResource, DefaultListCellRenderer, DefaultListCellRenderer.UIResource, MetalFileChooserUI.FileRenderer, MetalFileChooserUI.FilterComboBoxRenderer
public interface ListCellRenderer

Identifies components that can be used as "rubber stamps" to paint the cells in a JList. For example, to use a JLabel as a ListCellRenderer, you would write something like this:

 class MyCellRenderer extends JLabel implements ListCellRenderer {
     public MyCellRenderer() {
         setOpaque(true);
     }

     public Component getListCellRendererComponent(JList list,
                                                   Object value,
                                                   int index,
                                                   boolean isSelected,
                                                   boolean cellHasFocus) {

         setText(value.toString());

         Color background;
         Color foreground;

         // check if this cell represents the current DnD drop location
         JList.DropLocation dropLocation = list.getDropLocation();
         if (dropLocation != null
                 && !dropLocation.isInsert()
                 && dropLocation.getIndex() == index) {

             background = Color.BLUE;
             foreground = Color.WHITE;

         // check if this cell is selected
         } else if (isSelected) {
             background = Color.RED;
             foreground = Color.WHITE;

         // unselected, and not the DnD drop location
         } else {
             background = Color.WHITE;
             foreground = Color.BLACK;
         };

         setBackground(background);
         setForeground(foreground);

         return this;
     }
 }

See Also:
JList, DefaultListCellRenderer

Method Summary
 Component getListCellRendererComponent(JList list, Object value, int index, boolean isSelected, boolean cellHasFocus)
Return a component that has been configured to display the specified value.

Method Detail

getListCellRendererComponent

Component getListCellRendererComponent(JList list,
                                       Object value,
                                       int index,
                                       boolean isSelected,
                                       boolean cellHasFocus)
Return a component that has been configured to display the specified value. That component's paint method is then called to "render" the cell. If it is necessary to compute the dimensions of a list because the list cells do not have a fixed size, this method is called to generate a component on which getPreferredSize can be invoked.

Parameters:
list - The JList we're painting.
value - The value returned by list.getModel().getElementAt(index).
index - The cells index.
isSelected - True if the specified cell was selected.
cellHasFocus - True if the specified cell has the focus.
Returns:
A component whose paint() method will render the specified value.
See Also:
JList, ListSelectionModel, ListModel
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ListModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface ListModel

All Known Subinterfaces:
ComboBoxModel, MutableComboBoxModel
All Known Implementing Classes:
AbstractListModel, BasicDirectoryModel, DefaultComboBoxModel, DefaultListModel, MetalFileChooserUI.DirectoryComboBoxModel, MetalFileChooserUI.FilterComboBoxModel
public interface ListModel

This interface defines the methods components like JList use to get the value of each cell in a list and the length of the list. Logically the model is a vector, indices vary from 0 to ListDataModel.getSize() - 1. Any change to the contents or length of the data model must be reported to all of the ListDataListeners.

See Also:
JList

Method Summary
void | addListDataListener(ListDataListener l) Adds a listener to the list that's notified each time a change to the data model occurs.
Object | getElementAt(int index) Returns the value at the specified index.
int | getSize() Returns the length of the list.
void | removeListDataListener(ListDataListener l) Removes a listener from the list that's notified each time a change to the data model occurs.

Method Detail

getSize

int getSize()
Returns the length of the list.

Returns:
the length of the list

getElementAt

Object getElementAt(int index)
Returns the value at the specified index.

Parameters:
index - the requested index
Returns:
the value at index

addListDataListener

void addListDataListener(ListDataListener l)
Adds a listener to the list that's notified each time a change to the data model occurs.

Parameters:
l - the ListDataListener to be added

removeListDataListener

void removeListDataListener(ListDataListener l)
Removes a listener from the list that's notified each time a change to the data model occurs.

Parameters:
l - the ListDataListener to be removed
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ListSelectionModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface ListSelectionModel

All Known Implementing Classes:
DefaultListSelectionModel
public interface ListSelectionModel

This interface represents the current state of the selection for any of the components that display a list of values with stable indices. The selection is modeled as a set of intervals, each interval represents a contiguous range of selected list elements. The methods for modifying the set of selected intervals all take a pair of indices, index0 and index1, that represent a closed interval, i.e. the interval includes both index0 and index1.

See Also:
DefaultListSelectionModel

Field Summary
static int | MULTIPLE_INTERVAL_SELECTION A value for the selectionMode property: select one or more contiguous ranges of indices at a time.
static int | SINGLE_INTERVAL_SELECTION A value for the selectionMode property: select one contiguous range of indices at a time.
static int | SINGLE_SELECTION A value for the selectionMode property: select one list index at a time.
Method Summary
 void addListSelectionListener(ListSelectionListener x)
Add a listener to the list that's notified each time a change to the selection occurs.
 void addSelectionInterval(int index0, int index1)
Changes the selection to be the set union of the current selection and the indices between index0 and index1 inclusive.
 void clearSelection()
Change the selection to the empty set.
 int getAnchorSelectionIndex()
Return the first index argument from the most recent call to setSelectionInterval(), addSelectionInterval() or removeSelectionInterval().
 int getLeadSelectionIndex()
Return the second index argument from the most recent call to setSelectionInterval(), addSelectionInterval() or removeSelectionInterval().
 int getMaxSelectionIndex()
Returns the last selected index or -1 if the selection is empty.
 int getMinSelectionIndex()
Returns the first selected index or -1 if the selection is empty.
 int getSelectionMode()
Returns the current selection mode.
 boolean getValueIsAdjusting()
Returns true if the selection is undergoing a series of changes.
 void insertIndexInterval(int index, int length, boolean before)
Insert length indices beginning before/after index.
 boolean isSelectedIndex(int index)
Returns true if the specified index is selected.
 boolean isSelectionEmpty()
Returns true if no indices are selected.
 void removeIndexInterval(int index0, int index1)
Remove the indices in the interval index0,index1 (inclusive) from the selection model.
 void removeListSelectionListener(ListSelectionListener x)
Remove a listener from the list that's notified each time a change to the selection occurs.
 void removeSelectionInterval(int index0, int index1)
Changes the selection to be the set difference of the current selection and the indices between index0 and index1 inclusive.
 void setAnchorSelectionIndex(int index)
Set the anchor selection index.
 void setLeadSelectionIndex(int index)
Set the lead selection index.
 void setSelectionInterval(int index0, int index1)
Changes the selection to be between index0 and index1 inclusive.
 void setSelectionMode(int selectionMode)
Sets the selection mode.
 void setValueIsAdjusting(boolean valueIsAdjusting)
Sets the valueIsAdjusting property, which indicates whether or not upcoming selection changes should be considered part of a single change.

Field Detail

SINGLE_SELECTION

static final int SINGLE_SELECTION
A value for the selectionMode property: select one list index at a time.

See Also:
setSelectionMode(int), Constant Field Values

SINGLE_INTERVAL_SELECTION

static final int SINGLE_INTERVAL_SELECTION
A value for the selectionMode property: select one contiguous range of indices at a time.

See Also:
setSelectionMode(int), Constant Field Values

MULTIPLE_INTERVAL_SELECTION

static final int MULTIPLE_INTERVAL_SELECTION
A value for the selectionMode property: select one or more contiguous ranges of indices at a time.

See Also:
setSelectionMode(int), Constant Field Values
Method Detail

setSelectionInterval

void setSelectionInterval(int index0,
                          int index1)
Changes the selection to be between index0 and index1 inclusive. index0 doesn't have to be less than or equal to index1.

In SINGLE_SELECTION selection mode, only the second index is used.

If this represents a change to the current selection, then each ListSelectionListener is notified of the change.

Parameters:
index0 - one end of the interval.
index1 - other end of the interval
See Also:
addListSelectionListener(javax.swing.event.ListSelectionListener)

addSelectionInterval

void addSelectionInterval(int index0,
                          int index1)
Changes the selection to be the set union of the current selection and the indices between index0 and index1 inclusive. index0 doesn't have to be less than or equal to index1.

In SINGLE_SELECTION selection mode, this is equivalent to calling setSelectionInterval, and only the second index is used. In SINGLE_INTERVAL_SELECTION selection mode, this method behaves like setSelectionInterval, unless the given interval is immediately adjacent to or overlaps the existing selection, and can therefore be used to grow the selection.

If this represents a change to the current selection, then each ListSelectionListener is notified of the change.

Parameters:
index0 - one end of the interval.
index1 - other end of the interval
See Also:
addListSelectionListener(javax.swing.event.ListSelectionListener), setSelectionInterval(int, int)

removeSelectionInterval

void removeSelectionInterval(int index0,
                             int index1)
Changes the selection to be the set difference of the current selection and the indices between index0 and index1 inclusive. index0 doesn't have to be less than or equal to index1.

In SINGLE_INTERVAL_SELECTION selection mode, if the removal would produce two disjoint selections, the removal is extended through the greater end of the selection. For example, if the selection is 0-10 and you supply indices 5,6 (in any order) the resulting selection is 0-4.

If this represents a change to the current selection, then each ListSelectionListener is notified of the change.

Parameters:
index0 - one end of the interval.
index1 - other end of the interval
See Also:
addListSelectionListener(javax.swing.event.ListSelectionListener)

getMinSelectionIndex

int getMinSelectionIndex()
Returns the first selected index or -1 if the selection is empty.

getMaxSelectionIndex

int getMaxSelectionIndex()
Returns the last selected index or -1 if the selection is empty.

isSelectedIndex

boolean isSelectedIndex(int index)
Returns true if the specified index is selected.

getAnchorSelectionIndex

int getAnchorSelectionIndex()
Return the first index argument from the most recent call to setSelectionInterval(), addSelectionInterval() or removeSelectionInterval(). The most recent index0 is considered the "anchor" and the most recent index1 is considered the "lead". Some interfaces display these indices specially, e.g. Windows95 displays the lead index with a dotted yellow outline.

See Also:
getLeadSelectionIndex(),
setSelectionInterval(int, int),
addSelectionInterval(int, int)

setAnchorSelectionIndex

void setAnchorSelectionIndex(int index)
Set the anchor selection index.

See Also:
getAnchorSelectionIndex()

getLeadSelectionIndex

int getLeadSelectionIndex()
Return the second index argument from the most recent call to setSelectionInterval(), addSelectionInterval() or removeSelectionInterval().

See Also:
getAnchorSelectionIndex(),
setSelectionInterval(int, int),
addSelectionInterval(int, int)

setLeadSelectionIndex

void setLeadSelectionIndex(int index)
Set the lead selection index.

See Also:
getLeadSelectionIndex()

clearSelection

void clearSelection()
Change the selection to the empty set. If this represents a change to the current selection then notify each ListSelectionListener.

See Also:
addListSelectionListener(javax.swing.event.ListSelectionListener)

isSelectionEmpty

boolean isSelectionEmpty()
Returns true if no indices are selected.

insertIndexInterval

void insertIndexInterval(int index,
                         int length,
                         boolean before)
Insert length indices beginning before/after index. This is typically called to sync the selection model with a corresponding change in the data model.

removeIndexInterval

void removeIndexInterval(int index0,
                         int index1)
Remove the indices in the interval index0,index1 (inclusive) from the selection model. This is typically called to sync the selection model width a corresponding change in the data model.

setValueIsAdjusting

void setValueIsAdjusting(boolean valueIsAdjusting)
Sets the valueIsAdjusting property, which indicates whether or not upcoming selection changes should be considered part of a single change. The value of this property is used to initialize the valueIsAdjusting property of the ListSelectionEvents that are generated.

For example, if the selection is being updated in response to a user drag, this property can be set to true when the drag is initiated and set to false when the drag is finished. During the drag, listeners receive events with a valueIsAdjusting property set to true. At the end of the drag, when the change is finalized, listeners receive an event with the value set to false. Listeners can use this pattern if they wish to update only when a change has been finalized.

Setting this property to true begins a series of changes that is to be considered part of a single change. When the property is changed back to false, an event is sent out characterizing the entire selection change (if there was one), with the event's valueIsAdjusting property set to false.

Parameters:
valueIsAdjusting - the new value of the property
See Also:
getValueIsAdjusting(), ListSelectionEvent.getValueIsAdjusting()

getValueIsAdjusting

boolean getValueIsAdjusting()
Returns true if the selection is undergoing a series of changes.

Returns:
true if the selection is undergoing a series of changes
See Also:
setValueIsAdjusting(boolean)

setSelectionMode

void setSelectionMode(int selectionMode)
Sets the selection mode. The following list describes the accepted selection modes:
  • ListSelectionModel.SINGLE_SELECTION - Only one list index can be selected at a time. In this mode, setSelectionInterval and addSelectionInterval are equivalent, both replacing the current selection with the index represented by the second argument (the "lead").
  • ListSelectionModel.SINGLE_INTERVAL_SELECTION - Only one contiguous interval can be selected at a time. In this mode, addSelectionInterval behaves like setSelectionInterval (replacing the current selection), unless the given interval is immediately adjacent to or overlaps the existing selection, and can therefore be used to grow it.
  • ListSelectionModel.MULTIPLE_INTERVAL_SELECTION - In this mode, there's no restriction on what can be selected.

Throws:
IllegalArgumentException - if the selection mode isn't one of those allowed
See Also:
getSelectionMode()

getSelectionMode

int getSelectionMode()
Returns the current selection mode.

Returns:
the current selection mode
See Also:
setSelectionMode(int)

addListSelectionListener

void addListSelectionListener(ListSelectionListener x)
Add a listener to the list that's notified each time a change to the selection occurs.

Parameters:
x - the ListSelectionListener
See Also:
removeListSelectionListener(javax.swing.event.ListSelectionListener),
setSelectionInterval(int, int),
addSelectionInterval(int, int),
removeSelectionInterval(int, int),
clearSelection(),
insertIndexInterval(int, int, boolean),
removeIndexInterval(int, int)

removeListSelectionListener

void removeListSelectionListener(ListSelectionListener x)
Remove a listener from the list that's notified each time a change to the selection occurs.

Parameters:
x - the ListSelectionListener
See Also:
addListSelectionListener(javax.swing.event.ListSelectionListener)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LookAndFeel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class LookAndFeel

java.lang.Object
    extended by  javax.swing.LookAndFeel
Direct Known Subclasses:
BasicLookAndFeel, MultiLookAndFeel
public abstract class LookAndFeel
extends Object

LookAndFeel, as the name implies, encapsulates a look and feel. Beyond installing a look and feel most developers never need to interact directly with LookAndFeel. In general only developers creating a custom look and feel need to concern themselves with this class.

Swing is built upon the foundation that each JComponent subclass has an implementation of a specific ComponentUI subclass. The ComponentUI is often referred to as "the ui", "component ui", or "look and feel delegate". The ComponentUI subclass is responsible for providing the look and feel specific functionality of the component. For example, JTree requires an implementation of the ComponentUI subclass TreeUI. The implementation of the specific ComponentUI subclass is provided by the LookAndFeel. Each JComponent subclass identifies the ComponentUI subclass it requires by way of the JComponent method getUIClassID.

Each LookAndFeel implementation must provide an implementation of the appropriate ComponentUI subclass by specifying a value for each of Swing's ui class ids in the UIDefaults object returned from getDefaults. For example, BasicLookAndFeel uses BasicTreeUI as the concrete implementation for TreeUI. This is accomplished by BasicLookAndFeel providing the key-value pair "TreeUI"-"javax.swing.plaf.basic.BasicTreeUI", in the UIDefaults returned from getDefaults. Refer to UIDefaults.getUI(JComponent) for defails on how the implementation of the ComponentUI subclass is obtained.

When a LookAndFeel is installed the UIManager does not check that an entry exists for all ui class ids. As such, random exceptions will occur if the current look and feel has not provided a value for a particular ui class id and an instance of the JComponent subclass is created.

Recommendations for Look and Feels

As noted in UIManager each LookAndFeel has the opportunity to provide a set of defaults that are layered in with developer and system defaults. Some of Swing's components require the look and feel to provide a specific set of defaults. These are documented in the classes that require the specific default.

ComponentUIs and defaults

All ComponentUIs typically need to set various properties on the JComponent the ComponentUI is providing the look and feel for. This is typically done when the ComponentUI is installed on the JComponent. Setting a property should only be done if the developer has not set the property. For non-primitive values it is recommended that the ComponentUI only change the property on the JComponent if the current value is null or implements UIResource. If the current value is null or implements UIResource it indicates the property has not been set by the developer, and the ui is free to change it. For example, BasicButtonUI.installDefaults only changes the font on the JButton if the return value from button.getFont() is null or implements UIResource. On the other hand if button.getFont() returned a non-null value that did not implement UIResource then BasicButtonUI.installDefaults would not change the JButton's font.

For primitive values, such as opaque, the method installProperty should be invoked. installProperty only changes the correspoding property if the value has not been changed by the developer.

ComponentUI implementations should use the various install methods provided by this class as they handle the necessary checking and install the property using the recommended guidelines.

Exceptions

All of the install methods provided by LookAndFeel need to access the defaults if the value of the property being changed is null or a UIResource. For example, installing the font does the following:
   JComponent c;
   Font font = c.getFont();
   if (font == null || (font instanceof UIResource)) {
       c.setFont(UIManager.getFont("fontKey"));
   }
If the font is null or a UIResource, the defaults table is queried with the key fontKey. All of UIDefault's get methods throw a NullPointerException if passed in null. As such, unless otherwise noted each of the various install methods of LookAndFeel throw a NullPointerException if the current value is null or a UIResource and the supplied defaults key is null. In addition, unless otherwise specified all of the install methods throw a NullPointerException if a null component is passed in.

Constructor Summary
LookAndFeel()
Method Summary
 UIDefaults getDefaults()
Returns the look and feel defaults.
abstract  String getDescription()
Return a one line description of this look and feel implementation, e.g.
static Object getDesktopPropertyValue(String systemPropertyName, Object fallbackValue)
Returns the value of the specified system desktop property by invoking Toolkit.getDefaultToolkit().getDesktopProperty().
 Icon getDisabledIcon(JComponent component, Icon icon)
Returns an Icon with a disabled appearance.
 Icon getDisabledSelectedIcon(JComponent component, Icon icon)
Returns an Icon for use by disabled components that are also selected.
abstract  String getID()
Return a string that identifies this look and feel.
 LayoutStyle getLayoutStyle()
Returns the LayoutStyle for this look and feel.
abstract  String getName()
Return a short string that identifies this look and feel, e.g.
 boolean getSupportsWindowDecorations()
Returns true if the LookAndFeel returned RootPaneUI instances support providing Window decorations in a JRootPane.
 void initialize()
Initializes the look and feel.
static void installBorder(JComponent c, String defaultBorderName)
Convenience method for setting a component's border property with a value from the defaults.
static void installColors(JComponent c, String defaultBgName, String defaultFgName)
Convenience method for setting a component's foreground and background color properties with values from the defaults.
static void installColorsAndFont(JComponent c, String defaultBgName, String defaultFgName, String defaultFontName)
Convenience method for setting a component's foreground, background and font properties with values from the defaults.
static void installProperty(JComponent c, String propertyName, Object propertyValue)
Convenience method for installing a property with the specified name and value on a component if that property has not already been set by the developer.
abstract  boolean isNativeLookAndFeel()
If the underlying platform has a "native" look and feel, and this is an implementation of it, return true.
abstract  boolean isSupportedLookAndFeel()
Return true if the underlying platform supports and or permits this look and feel.
static void loadKeyBindings(InputMap retMap, Object[] keys)
Populates an InputMap with the specified bindings.
static ComponentInputMap makeComponentInputMap(JComponent c, Object[] keys)
Creates a ComponentInputMapUIResource from keys.
static Object makeIcon(Class<?> baseClass, String gifFile)
Creates and returns a UIDefault.LazyValue that loads an image.
static InputMap makeInputMap(Object[] keys)
Creates a InputMapUIResource from keys.
static JTextComponent.KeyBinding[] makeKeyBindings(Object[] keyBindingList)
Convenience method for building an array of KeyBindings.
 void provideErrorFeedback(Component component)
Invoked when the user attempts an invalid operation, such as pasting into an uneditable JTextField that has focus.
 String toString()
Returns a string that displays and identifies this object's properties.
 void uninitialize()
Uninitializes the look and feel.
static void uninstallBorder(JComponent c)
Convenience method for uninstalling a border.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

LookAndFeel

public LookAndFeel()
Method Detail

installColors

public static void installColors(JComponent c,
                                 String defaultBgName,
                                 String defaultFgName)
Convenience method for setting a component's foreground and background color properties with values from the defaults. The properties are only set if the current value is either null or a UIResource.

Parameters:
c - component to set the colors on
defaultBgName - key for the background
defaultFgName - key for the foreground
Throws:
NullPointerException - as described in exceptions
See Also:
installColorsAndFont(javax.swing.JComponent, java.lang.String, java.lang.String, java.lang.String), UIManager.getColor(java.lang.Object)

installColorsAndFont

public static void installColorsAndFont(JComponent c,
                                        String defaultBgName,
                                        String defaultFgName,
                                        String defaultFontName)
Convenience method for setting a component's foreground, background and font properties with values from the defaults. The properties are only set if the current value is either null or a UIResource.

Parameters:
c - component set to the colors and font on
defaultBgName - key for the background
defaultFgName - key for the foreground
defaultFontName - key for the font
Throws:
NullPointerException - as described in exceptions
See Also:
installColors(javax.swing.JComponent, java.lang.String, java.lang.String),
UIManager.getColor(java.lang.Object),
UIManager.getFont(java.lang.Object)

installBorder

public static void installBorder(JComponent c,
                                 String defaultBorderName)
Convenience method for setting a component's border property with a value from the defaults. The border is only set if the border is null or an instance of UIResource.

Parameters:
c - component to set the border on
defaultBorderName - key specifying the border
Throws:
NullPointerException - as described in exceptions

uninstallBorder

public static void uninstallBorder(JComponent c)
Convenience method for uninstalling a border. If the border of the component is a UIResource, it is set to null.

Parameters:
c - component to uninstall the border on
Throws:
NullPointerException - if c is null

installProperty

public static void installProperty(JComponent c,
                                   String propertyName,
                                   Object propertyValue)
Convenience method for installing a property with the specified name and value on a component if that property has not already been set by the developer. This method is intended to be used by ui delegate instances that need to specify a default value for a property of primitive type (boolean, int, ..), but do not wish to override a value set by the client. Since primitive property values cannot be wrapped with the UIResource marker, this method uses private state to determine whether the property has been set by the client.

Parameters:
c - target component to set the property on
propertyName - name of the property to set
propertyValue - value of the property
Throws:
IllegalArgumentException - if the specified property is not one which can be set using this method
ClassCastException - if the property value has not been set by the developer and the type does not match the property's type
NullPointerException - if c is null, or the named property has not been set by the developer and propertyValue is null
Since:
1.5

makeKeyBindings

public static JTextComponent.KeyBinding[] makeKeyBindings(Object[] keyBindingList)
Convenience method for building an array of KeyBindings. While this method is not deprecated, developers should instead use ActionMap and InputMap for supplying key bindings.

This method returns an array of KeyBindings, one for each alternating key-action pair in keyBindingList. A key can either be a String in the format specified by the KeyStroke.getKeyStroke method, or a KeyStroke. The action part of the pair is a String that corresponds to the name of the Action.

The following example illustrates creating a KeyBinding array from six alternating key-action pairs:

        JTextComponent.KeyBinding[] multilineBindings = makeKeyBindings( new Object[] {
          "UP", DefaultEditorKit.upAction,
        "DOWN", DefaultEditorKit.downAction,
     "PAGE_UP", DefaultEditorKit.pageUpAction,
   "PAGE_DOWN", DefaultEditorKit.pageDownAction,
       "ENTER", DefaultEditorKit.insertBreakAction,
         "TAB", DefaultEditorKit.insertTabAction
  });
If keyBindingList's length is odd, the last element is ignored.

Supplying a null value for either the key or action part of the key-action pair results in creating a KeyBinding with the corresponding value null. As other parts of Swing's expect non-null values in a KeyBinding, you should avoid supplying null as either the key or action part of the key-action pair.

Parameters:
keyBindingList - an array of key-action pairs
Returns:
an array of KeyBindings
Throws:
NullPointerException - if keyBindingList is null
ClassCastException - if the key part of the pair is not a KeyStroke or String, or the action part of the pair is not a String
See Also:
ActionMap, InputMap, KeyStroke.getKeyStroke(char)

makeInputMap

public static InputMap makeInputMap(Object[] keys)
Creates a InputMapUIResource from keys. This is a convenience method for creating a new InputMapUIResource, invoking loadKeyBindings(map, keys), and returning the InputMapUIResource.

Parameters:
keys - alternating pairs of keystroke-action key pairs as described in loadKeyBindings(javax.swing.InputMap, java.lang.Object[])
Returns:
newly created and populated InputMapUIResource
Since:
1.3
See Also:
loadKeyBindings(javax.swing.InputMap, java.lang.Object[])

makeComponentInputMap

public static ComponentInputMap makeComponentInputMap(JComponent c,
                                                      Object[] keys)
Creates a ComponentInputMapUIResource from keys. This is a convenience method for creating a new ComponentInputMapUIResource, invoking loadKeyBindings(map, keys), and returning the ComponentInputMapUIResource.

Parameters:
c - component to create the ComponentInputMapUIResource with
keys - alternating pairs of keystroke-action key pairs as described in loadKeyBindings(javax.swing.InputMap, java.lang.Object[])
Returns:
newly created and populated InputMapUIResource
Throws:
IllegalArgumentException - if c is null
Since:
1.3
See Also:
loadKeyBindings(javax.swing.InputMap, java.lang.Object[]), ComponentInputMapUIResource

loadKeyBindings

public static void loadKeyBindings(InputMap retMap,
                                   Object[] keys)
Populates an InputMap with the specified bindings. The bindings are supplied as a list of alternating keystroke-action key pairs. The keystroke is either an instance of KeyStroke, or a String that identifies the KeyStroke for the binding. Refer to KeyStroke.getKeyStroke(String) for the specific format. The action key part of the pair is the key registered in the InputMap for the KeyStroke.

The following illustrates loading an InputMap with two key-action pairs:

   LookAndFeel.loadKeyBindings(inputMap, new Object[] {
     "control X", "cut",
     "control V", "paste"
   });

Supplying a null list of bindings (keys) does not change retMap in any way.

Specifying a null action key results in removing the keystroke's entry from the InputMap. A null keystroke is ignored.

Parameters:
retMap - InputMap to add the key-action pairs to
keys - bindings to add to retMap
Throws:
NullPointerException - if keys is non-null, not empty, and retMap is null
Since:
1.3
See Also:
KeyStroke.getKeyStroke(String), InputMap

makeIcon

public static Object makeIcon(Class<?> baseClass,
                              String gifFile)
Creates and returns a UIDefault.LazyValue that loads an image. The returned value is an implementation of UIDefaults.LazyValue. When createValue is invoked on the returned object, the image is loaded. If the image is non-null, it is then wrapped in an Icon that implements UIResource. The image is loaded using Class.getResourceAsStream(gifFile).

This method does not check the arguments in any way. It is strongly recommended that non-null values are supplied else exceptions may occur when createValue is invoked on the returned object.

Parameters:
baseClass - Class used to load the resource
gifFile - path to the image to load
Returns:
a UIDefaults.LazyValue; when resolved the LazyValue loads the specified image
See Also:
UIDefaults.LazyValue, Icon, Class.getResourceAsStream(String)

getLayoutStyle

public LayoutStyle getLayoutStyle()
Returns the LayoutStyle for this look and feel. This never returns null.

You generally don't use the LayoutStyle from the look and feel, instead use the LayoutStyle method getInstance.

Returns:
the LayoutStyle for this look and feel
Since:
1.6
See Also:
LayoutStyle.getInstance()

provideErrorFeedback

public void provideErrorFeedback(Component component)
Invoked when the user attempts an invalid operation, such as pasting into an uneditable JTextField that has focus. The default implementation beeps. Subclasses that wish different behavior should override this and provide the additional feedback.

Parameters:
component - the Component the error occurred in, may be null indicating the error condition is not directly associated with a Component
Since:
1.4

getDesktopPropertyValue

public static Object getDesktopPropertyValue(String systemPropertyName,
                                             Object fallbackValue)
Returns the value of the specified system desktop property by invoking Toolkit.getDefaultToolkit().getDesktopProperty(). If the value of the specified property is null, fallbackValue is returned.

Parameters:
systemPropertyName - the name of the system desktop property being queried
fallbackValue - the object to be returned as the value if the system value is null
Returns:
the current value of the desktop property
Since:
1.4
See Also:
Toolkit.getDesktopProperty(java.lang.String)

getDisabledIcon

public Icon getDisabledIcon(JComponent component,
                            Icon icon)
Returns an Icon with a disabled appearance. This method is used to generate a disabled Icon when one has not been specified. For example, if you create a JButton and only specify an Icon via setIcon this method will be called to generate the disabled Icon. If null is passed as icon this method returns null.

Some look and feels might not render the disabled Icon, in which case they will ignore this.

Parameters:
component - JComponent that will display the Icon, may be null
icon - Icon to generate the disabled icon from
Returns:
disabled Icon, or null if a suitable Icon can not be generated
Since:
1.5

getDisabledSelectedIcon

public Icon getDisabledSelectedIcon(JComponent component,
                                    Icon icon)
Returns an Icon for use by disabled components that are also selected. This method is used to generate an Icon for components that are in both the disabled and selected states but do not have a specific Icon for this state. For example, if you create a JButton and only specify an Icon via setIcon this method will be called to generate the disabled and selected Icon. If null is passed as icon this methods returns null.

Some look and feels might not render the disabled and selected Icon, in which case they will ignore this.

Parameters:
component - JComponent that will display the Icon, may be null
icon - Icon to generate disabled and selected icon from
Returns:
disabled and selected icon, or null if a suitable Icon can not be generated.
Since:
1.5

getName

public abstract String getName()
Return a short string that identifies this look and feel, e.g. "CDE/Motif". This string should be appropriate for a menu item. Distinct look and feels should have different names, e.g. a subclass of MotifLookAndFeel that changes the way a few components are rendered should be called "CDE/Motif My Way"; something that would be useful to a user trying to select a L&F from a list of names.

Returns:
short identifier for the look and feel

getID

public abstract String getID()
Return a string that identifies this look and feel. This string will be used by applications/services that want to recognize well known look and feel implementations. Presently the well known names are "Motif", "Windows", "Mac", "Metal". Note that a LookAndFeel derived from a well known superclass that doesn't make any fundamental changes to the look or feel shouldn't override this method.

Returns:
identifier for the look and feel

getDescription

public abstract String getDescription()
Return a one line description of this look and feel implementation, e.g. "The CDE/Motif Look and Feel". This string is intended for the user, e.g. in the title of a window or in a ToolTip message.

Returns:
short description for the look and feel

getSupportsWindowDecorations

public boolean getSupportsWindowDecorations()
Returns true if the LookAndFeel returned RootPaneUI instances support providing Window decorations in a JRootPane.

The default implementation returns false, subclasses that support Window decorations should override this and return true.

Returns:
true if the RootPaneUI instances created by this look and feel support client side decorations
Since:
1.4
See Also:
JDialog.setDefaultLookAndFeelDecorated(boolean),
JFrame.setDefaultLookAndFeelDecorated(boolean),
JRootPane.setWindowDecorationStyle(int)

isNativeLookAndFeel

public abstract boolean isNativeLookAndFeel()
If the underlying platform has a "native" look and feel, and this is an implementation of it, return true. For example, when the underlying platform is Solaris running CDE a CDE/Motif look and feel implementation would return true.

Returns:
true if this look and feel represents the underlying platform look and feel

isSupportedLookAndFeel

public abstract boolean isSupportedLookAndFeel()
Return true if the underlying platform supports and or permits this look and feel. This method returns false if the look and feel depends on special resources or legal agreements that aren't defined for the current platform.

Returns:
true if this is a supported look and feel
See Also:
UIManager.setLookAndFeel(javax.swing.LookAndFeel)

initialize

public void initialize()
Initializes the look and feel. While this method is public, it should only be invoked by the UIManager when a look and feel is installed as the current look and feel. This method is invoked before the UIManager invokes getDefaults. This method is intended to perform any initialization for the look and feel. Subclasses should do any one-time setup they need here, rather than in a static initializer, because look and feel class objects may be loaded just to discover that isSupportedLookAndFeel() returns false.

See Also:
uninitialize(), UIManager.setLookAndFeel(javax.swing.LookAndFeel)

uninitialize

public void uninitialize()
Uninitializes the look and feel. While this method is public, it should only be invoked by the UIManager when the look and feel is uninstalled. For example, UIManager.setLookAndFeel invokes this when the look and feel is changed.

Subclasses may choose to free up some resources here.

See Also:
initialize(), UIManager.setLookAndFeel(javax.swing.LookAndFeel)

getDefaults

public UIDefaults getDefaults()
Returns the look and feel defaults. While this method is public, it should only be invoked by the UIManager when the look and feel is set as the current look and feel and after initialize has been invoked.

Returns:
the look and feel defaults
See Also:
initialize(),
uninitialize(),
UIManager.setLookAndFeel(javax.swing.LookAndFeel)

toString

public String toString()
Returns a string that displays and identifies this object's properties.

Overrides:
toString in class Object
Returns:
a String representation of this object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MenuElement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface MenuElement

All Known Implementing Classes:
BasicComboPopup, BasicInternalFrameTitlePane.SystemMenuBar, JCheckBoxMenuItem, JMenu, JMenuBar, JMenuItem, JPopupMenu, JRadioButtonMenuItem, MetalComboBoxUI.MetalComboPopup
public interface MenuElement

Any component that can be placed into a menu should implement this interface. This interface is used by MenuSelectionManager to handle selection and navigation in menu hierarchies.

Method Summary
Component | getComponent() This method should return the java.awt.Component used to paint the receiving element.
MenuElement[] | getSubElements() This method should return an array containing the sub-elements for the receiving menu element
void | menuSelectionChanged(boolean isIncluded) Call by the MenuSelectionManager when the MenuElement is added or remove from the menu selection.
void | processKeyEvent(KeyEvent event, MenuElement[] path, MenuSelectionManager manager) Process a key event.
void | processMouseEvent(MouseEvent event, MenuElement[] path, MenuSelectionManager manager) Processes a mouse event.

Method Detail

processMouseEvent

void processMouseEvent(MouseEvent event,
                       MenuElement[] path,
                       MenuSelectionManager manager)
Processes a mouse event. event is a MouseEvent with source being the receiving element's component. path is the path of the receiving element in the menu hierarchy including the receiving element itself. manager is the MenuSelectionManager for the menu hierarchy. This method should process the MouseEvent and change the menu selection if necessary by using MenuSelectionManager's API Note: you do not have to forward the event to sub-components. This is done automatically by the MenuSelectionManager.

processKeyEvent

void processKeyEvent(KeyEvent event,
                     MenuElement[] path,
                     MenuSelectionManager manager)
Process a key event.

menuSelectionChanged

void menuSelectionChanged(boolean isIncluded)
Call by the MenuSelectionManager when the MenuElement is added or remove from the menu selection.

getSubElements

MenuElement[] getSubElements()
This method should return an array containing the sub-elements for the receiving menu element

Returns:
an array of MenuElements

getComponent

Component getComponent()
This method should return the java.awt.Component used to paint the receiving element. The returned component will be used to convert events and detect if an event is inside a MenuElement's component.

Returns:
the Component value
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MenuSelectionManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class MenuSelectionManager

java.lang.Object
    extended by  javax.swing.MenuSelectionManager

public class MenuSelectionManager
extends Object

A MenuSelectionManager owns the selection in menu hierarchy.

Field Summary
protected ChangeEvent | changeEvent Only one ChangeEvent is needed per button model instance since the event's only state is the source property.
protected EventListenerList | listenerList
Constructor Summary
MenuSelectionManager()
Method Summary
 void addChangeListener(ChangeListener l)
Adds a ChangeListener to the button.
 void clearSelectedPath()
Tell the menu selection to close and unselect all the menu components.
 Component componentForPoint(Component source, Point sourcePoint)
Returns the component in the currently selected path which contains sourcePoint.
static MenuSelectionManager defaultManager()
Returns the default menu selection manager.
protected  void fireStateChanged()
Notifies all listeners that have registered interest for notification on this event type.
 ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this MenuSelectionManager with addChangeListener().
 MenuElement[] getSelectedPath()
Returns the path to the currently selected menu item
 boolean isComponentPartOfCurrentMenu(Component c)
Return true if c is part of the currently used menu
 void processKeyEvent(KeyEvent e)
When a MenuElement receives an event from a KeyListener, it should never process the event directly.
 void processMouseEvent(MouseEvent event)
When a MenuElement receives an event from a MouseListener, it should never process the event directly.
 void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the button.
 void setSelectedPath(MenuElement[] path)
Changes the selection in the menu hierarchy.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

changeEvent

protected transient ChangeEvent changeEvent
Only one ChangeEvent is needed per button model instance since the event's only state is the source property. The source of events generated is always "this".

listenerList

protected EventListenerList listenerList
Constructor Detail

MenuSelectionManager

public MenuSelectionManager()
Method Detail

defaultManager

public static MenuSelectionManager defaultManager()
Returns the default menu selection manager.

Returns:
a MenuSelectionManager object

setSelectedPath

public void setSelectedPath(MenuElement[] path)
Changes the selection in the menu hierarchy. The elements in the array are sorted in order from the root menu element to the currently selected menu element.

Note that this method is public but is used by the look and feel engine and should not be called by client applications.

Parameters:
path - an array of MenuElement objects specifying the selected path

getSelectedPath

public MenuElement[] getSelectedPath()
Returns the path to the currently selected menu item

Returns:
an array of MenuElement objects representing the selected path

clearSelectedPath

public void clearSelectedPath()
Tell the menu selection to close and unselect all the menu components. Call this method when a choice has been made

addChangeListener

public void addChangeListener(ChangeListener l)
Adds a ChangeListener to the button.

Parameters:
l - the listener to add

removeChangeListener

public void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the button.

Parameters:
l - the listener to remove

getChangeListeners

public ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this MenuSelectionManager with addChangeListener().

Returns:
all of the ChangeListeners added or an empty array if no listeners have been added
Since:
1.4

fireStateChanged

protected void fireStateChanged()
Notifies all listeners that have registered interest for notification on this event type. The event instance is created lazily.

See Also:
EventListenerList

processMouseEvent

public void processMouseEvent(MouseEvent event)
When a MenuElement receives an event from a MouseListener, it should never process the event directly. Instead all MenuElements should call this method with the event.

Parameters:
event - a MouseEvent object

componentForPoint

public Component componentForPoint(Component source,
                                   Point sourcePoint)
Returns the component in the currently selected path which contains sourcePoint.

Parameters:
source - The component in whose coordinate space sourcePoint is given
sourcePoint - The point which is being tested
Returns:
The component in the currently selected path which contains sourcePoint (relative to the source component's coordinate space. If sourcePoint is not inside a component on the currently selected path, null is returned.

processKeyEvent

public void processKeyEvent(KeyEvent e)
When a MenuElement receives an event from a KeyListener, it should never process the event directly. Instead all MenuElements should call this method with the event.

Parameters:
e - a KeyEvent object

isComponentPartOfCurrentMenu

public boolean isComponentPartOfCurrentMenu(Component c)
Return true if c is part of the currently used menu

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MutableComboBoxModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface MutableComboBoxModel

All Superinterfaces:
ComboBoxModel, ListModel
All Known Implementing Classes:
DefaultComboBoxModel
public interface MutableComboBoxModel
extends ComboBoxModel

A mutable version of ComboBoxModel.

Method Summary
void | addElement(Object obj) Adds an item at the end of the model.
void | insertElementAt(Object obj, int index) Adds an item at a specific index.
void | removeElement(Object obj) Removes an item from the model.
void | removeElementAt(int index) Removes an item at a specific index.
Methods inherited from interface javax.swing.ComboBoxModel
getSelectedItem, setSelectedItem
Methods inherited from interface javax.swing.ListModel
addListDataListener, getElementAt, getSize, removeListDataListener

Method Detail

addElement

void addElement(Object obj)
Adds an item at the end of the model. The implementation of this method should notify all registered ListDataListeners that the item has been added.

Parameters:
obj - the Object to be added

removeElement

void removeElement(Object obj)
Removes an item from the model. The implementation of this method should should notify all registered ListDataListeners that the item has been removed.

Parameters:
obj - the Object to be removed

insertElementAt

void insertElementAt(Object obj,
                     int index)
Adds an item at a specific index. The implementation of this method should notify all registered ListDataListeners that the item has been added.

Parameters:
obj - the Object to be added
index - location to add the object

removeElementAt

void removeElementAt(int index)
Removes an item at a specific index. The implementation of this method should notify all registered ListDataListeners that the item has been removed.

Parameters:
index - location of object to be removed
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OverlayLayout

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class OverlayLayout

java.lang.Object
    extended by  javax.swing.OverlayLayout
All Implemented Interfaces:
LayoutManager, LayoutManager2, Serializable
public class OverlayLayout
extends Object
implements LayoutManager2, Serializable

A layout manager to arrange components over the top of each other. The requested size of the container will be the largest requested size of the children, taking alignment needs into consideration. The alignment is based upon what is needed to properly fit the children in the allocation area. The children will be placed such that their alignment points are all on top of each other.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
OverlayLayout(Container target)
Constructs a layout manager that performs overlay arrangement of the children.
Method Summary
void | addLayoutComponent(Component comp, Object constraints) Adds the specified component to the layout, using the specified constraint object.
void | addLayoutComponent(String name, Component comp) Adds the specified component to the layout.
float | getLayoutAlignmentX(Container target) Returns the alignment along the x axis for the container.
float | getLayoutAlignmentY(Container target) Returns the alignment along the y axis for the container.
Container | getTarget() Returns the container that uses this layout manager.
void | invalidateLayout(Container target) Indicates a child has changed its layout related information, which causes any cached calculations to be flushed.
void | layoutContainer(Container target) Called by the AWT when the specified container needs to be laid out.
Dimension | maximumLayoutSize(Container target) Returns the maximum dimensions needed to lay out the components contained in the specified target container.
Dimension | minimumLayoutSize(Container target) Returns the minimum dimensions needed to lay out the components contained in the specified target container.
Dimension | preferredLayoutSize(Container target) Returns the preferred dimensions for this layout given the components in the specified target container.
void | removeLayoutComponent(Component comp) Removes the specified component from the layout.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

OverlayLayout

public OverlayLayout(Container target)
Constructs a layout manager that performs overlay arrangement of the children. The layout manager created is dedicated to the given container.

Parameters:
target - the container to do layout against
Method Detail

getTarget

public final Container getTarget()
Returns the container that uses this layout manager.

Returns:
the container that uses this layout manager
Since:
1.6

invalidateLayout

public void invalidateLayout(Container target)
Indicates a child has changed its layout related information, which causes any cached calculations to be flushed.

Specified by:
invalidateLayout in interface LayoutManager2
Parameters:
target - the container

addLayoutComponent

public void addLayoutComponent(String name,
                               Component comp)
Adds the specified component to the layout. Used by this class to know when to invalidate layout.

Specified by:
addLayoutComponent in interface LayoutManager
Parameters:
name - the name of the component
comp - the the component to be added

removeLayoutComponent

public void removeLayoutComponent(Component comp)
Removes the specified component from the layout. Used by this class to know when to invalidate layout.

Specified by:
removeLayoutComponent in interface LayoutManager
Parameters:
comp - the component to remove

addLayoutComponent

public void addLayoutComponent(Component comp,
                               Object constraints)
Adds the specified component to the layout, using the specified constraint object. Used by this class to know when to invalidate layout.

Specified by:
addLayoutComponent in interface LayoutManager2
Parameters:
comp - the component to be added
constraints - where/how the component is added to the layout.

preferredLayoutSize

public Dimension preferredLayoutSize(Container target)
Returns the preferred dimensions for this layout given the components in the specified target container. Recomputes the layout if it has been invalidated. Factors in the current inset setting returned by getInsets().

Specified by:
preferredLayoutSize in interface LayoutManager
Parameters:
target - the component which needs to be laid out
Returns:
a Dimension object containing the preferred dimensions
See Also:
minimumLayoutSize(java.awt.Container)

minimumLayoutSize

public Dimension minimumLayoutSize(Container target)
Returns the minimum dimensions needed to lay out the components contained in the specified target container. Recomputes the layout if it has been invalidated, and factors in the current inset setting.

Specified by:
minimumLayoutSize in interface LayoutManager
Parameters:
target - the component which needs to be laid out
Returns:
a Dimension object containing the minimum dimensions
See Also:
preferredLayoutSize(java.awt.Container)

maximumLayoutSize

public Dimension maximumLayoutSize(Container target)
Returns the maximum dimensions needed to lay out the components contained in the specified target container. Recomputes the layout if it has been invalidated, and factors in the inset setting returned by getInset.

Specified by:
maximumLayoutSize in interface LayoutManager2
Parameters:
target - the component that needs to be laid out
Returns:
a Dimension object containing the maximum dimensions
See Also:
preferredLayoutSize(java.awt.Container)

getLayoutAlignmentX

public float getLayoutAlignmentX(Container target)
Returns the alignment along the x axis for the container.

Specified by:
getLayoutAlignmentX in interface LayoutManager2
Parameters:
target - the container
Returns:
the alignment >= 0.0f && <= 1.0f

getLayoutAlignmentY

public float getLayoutAlignmentY(Container target)
Returns the alignment along the y axis for the container.

Specified by:
getLayoutAlignmentY in interface LayoutManager2
Parameters:
target - the container
Returns:
the alignment >= 0.0f && <= 1.0f

layoutContainer

public void layoutContainer(Container target)
Called by the AWT when the specified container needs to be laid out.

Specified by:
layoutContainer in interface LayoutManager
Parameters:
target - the container to lay out
Throws:
AWTError - if the target isn't the container specified to the constructor
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


plaf

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.swing.plaf

Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.

See:
Description

Interface Summary
UIResource This interface is used to mark objects created by ComponentUI delegates.

Class Summary
ActionMapUIResource | A subclass of javax.swing.ActionMap that implements UIResource.
BorderUIResource |
BorderUIResource.BevelBorderUIResource |
BorderUIResource.CompoundBorderUIResource |
BorderUIResource.EmptyBorderUIResource |
BorderUIResource.EtchedBorderUIResource |
BorderUIResource.LineBorderUIResource |
BorderUIResource.MatteBorderUIResource |
BorderUIResource.TitledBorderUIResource |
ButtonUI | Pluggable look and feel interface for JButton.
ColorChooserUI | Pluggable look and feel interface for JColorChooser.
ColorUIResource |
ComboBoxUI | Pluggable look and feel interface for JComboBox.
ComponentInputMapUIResource | A subclass of javax.swing.ComponentInputMap that implements UIResource.
ComponentUI | The base class for all UI delegate objects in the Swing pluggable look and feel architecture.
DesktopIconUI | Pluggable look and feel interface for JDesktopIcon.
DesktopPaneUI | Pluggable look and feel interface for JDesktopPane.
DimensionUIResource |
FileChooserUI | Pluggable look and feel interface for JFileChooser.
FontUIResource | A subclass of java.awt.Font that implements UIResource.
IconUIResource | An Icon wrapper class which implements UIResource.
InputMapUIResource | A subclass of javax.swing.InputMap that implements UIResource.
InsetsUIResource |
InternalFrameUI | Pluggable look and feel interface for JInternalFrame.
LabelUI | Pluggable look and feel interface for JLabel.
ListUI | The JList pluggable look and feel delegate.
MenuBarUI | Pluggable look and feel interface for JMenuBar.
MenuItemUI | Pluggable look and feel interface for JMenuItem.
OptionPaneUI | Pluggable look and feel interface for JOptionPane.
PanelUI | Pluggable look and feel interface for Panel.
PopupMenuUI | Pluggable look and feel interface for JPopupMenu.
ProgressBarUI | Pluggable look and feel interface for JProgressBar.
RootPaneUI | Pluggable look and feel interface for JRootPane.
ScrollBarUI | Pluggable look and feel interface for JScrollBar.
ScrollPaneUI | Pluggable look and feel interface for JScrollPane.
SeparatorUI | Pluggable look and feel interface for JSeparator.
SliderUI | Pluggable look and feel interface for JSlider.
SpinnerUI | Pluggable look and feel interface for JSpinner
SplitPaneUI | Pluggable look and feel interface for JSplitPane.
TabbedPaneUI | Pluggable look and feel interface for JTabbedPane.
TableHeaderUI | Pluggable look and feel interface for JTableHeader.
TableUI | Pluggable look and feel interface for JTable.
TextUI | Text editor user interface
ToolBarUI | Pluggable look and feel interface for JToolBar.
ToolTipUI | Pluggable look and feel interface for JToolTip.
TreeUI | Pluggable look and feel interface for JTree.
ViewportUI | Pluggable look and feel interface for JViewport.

Package javax.swing.plaf Description

Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities. Its classes are subclassed and implemented by look and feel UIs such as Basic and the Java look and feel (Metal). This package is only used by developers who cannot create a new look and feel by subclassing existing look-and-feel components (such as those provided by the javax.swing.plaf.basic and javax.swing.plaf.metal packages).

Note: Most of the Swing API is not thread safe. For details, see Threads and Swing, a section in The Java Tutorial.

Since:
1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.swing.plaf Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.swing.plaf

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.swing.border.AbstractBorder (implements javax.swing.border.Border, java.io.Serializable)
      • javax.swing.border.BevelBorder
        • javax.swing.plaf.BorderUIResource.BevelBorderUIResource (implements javax.swing.plaf.UIResource)
      • javax.swing.border.CompoundBorder
        • javax.swing.plaf.BorderUIResource.CompoundBorderUIResource (implements javax.swing.plaf.UIResource)
      • javax.swing.border.EmptyBorder (implements java.io.Serializable)
        • javax.swing.plaf.BorderUIResource.EmptyBorderUIResource (implements javax.swing.plaf.UIResource)
        • javax.swing.border.MatteBorder
          • javax.swing.plaf.BorderUIResource.MatteBorderUIResource (implements javax.swing.plaf.UIResource)
      • javax.swing.border.EtchedBorder
        • javax.swing.plaf.BorderUIResource.EtchedBorderUIResource (implements javax.swing.plaf.UIResource)
      • javax.swing.border.LineBorder
        • javax.swing.plaf.BorderUIResource.LineBorderUIResource (implements javax.swing.plaf.UIResource)
      • javax.swing.border.TitledBorder
        • javax.swing.plaf.BorderUIResource.TitledBorderUIResource (implements javax.swing.plaf.UIResource)
    • javax.swing.ActionMap (implements java.io.Serializable)
      • javax.swing.plaf.ActionMapUIResource (implements javax.swing.plaf.UIResource)
    • javax.swing.plaf.BorderUIResource (implements javax.swing.border.Border, java.io.Serializable, javax.swing.plaf.UIResource)
    • java.awt.Color (implements java.awt.Paint, java.io.Serializable)
      • javax.swing.plaf.ColorUIResource (implements javax.swing.plaf.UIResource)
    • javax.swing.plaf.ComponentUI
      • javax.swing.plaf.ButtonUI
        • javax.swing.plaf.MenuItemUI
      • javax.swing.plaf.ColorChooserUI
      • javax.swing.plaf.ComboBoxUI
      • javax.swing.plaf.DesktopIconUI
      • javax.swing.plaf.DesktopPaneUI
      • javax.swing.plaf.FileChooserUI
      • javax.swing.plaf.InternalFrameUI
      • javax.swing.plaf.LabelUI
      • javax.swing.plaf.ListUI
      • javax.swing.plaf.MenuBarUI
      • javax.swing.plaf.OptionPaneUI
      • javax.swing.plaf.PanelUI
      • javax.swing.plaf.PopupMenuUI
      • javax.swing.plaf.ProgressBarUI
      • javax.swing.plaf.RootPaneUI
      • javax.swing.plaf.ScrollBarUI
      • javax.swing.plaf.ScrollPaneUI
      • javax.swing.plaf.SeparatorUI
      • javax.swing.plaf.SliderUI
      • javax.swing.plaf.SpinnerUI
      • javax.swing.plaf.SplitPaneUI
      • javax.swing.plaf.TabbedPaneUI
      • javax.swing.plaf.TableHeaderUI
      • javax.swing.plaf.TableUI
      • javax.swing.plaf.TextUI
      • javax.swing.plaf.ToolBarUI
      • javax.swing.plaf.ToolTipUI
      • javax.swing.plaf.TreeUI
      • javax.swing.plaf.ViewportUI
    • java.awt.geom.Dimension2D (implements java.lang.Cloneable)
      • java.awt.Dimension (implements java.io.Serializable)
        • javax.swing.plaf.DimensionUIResource (implements javax.swing.plaf.UIResource)
    • java.awt.Font (implements java.io.Serializable)
      • javax.swing.plaf.FontUIResource (implements javax.swing.plaf.UIResource)
    • javax.swing.plaf.IconUIResource (implements javax.swing.Icon, java.io.Serializable, javax.swing.plaf.UIResource)
    • javax.swing.InputMap (implements java.io.Serializable)
      • javax.swing.ComponentInputMap
        • javax.swing.plaf.ComponentInputMapUIResource (implements javax.swing.plaf.UIResource)
      • javax.swing.plaf.InputMapUIResource (implements javax.swing.plaf.UIResource)
    • java.awt.Insets (implements java.lang.Cloneable, java.io.Serializable)
      • javax.swing.plaf.InsetsUIResource (implements javax.swing.plaf.UIResource)

Interface Hierarchy

  • javax.swing.plaf.UIResource
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


UIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Interface UIResource

All Known Implementing Classes:
ActionMapUIResource, BasicBorders.ButtonBorder, BasicBorders.FieldBorder, BasicBorders.MarginBorder, BasicBorders.MenuBarBorder, BasicBorders.RadioButtonBorder, BasicBorders.RolloverButtonBorder, BasicBorders.SplitPaneBorder, BasicBorders.ToggleButtonBorder, BasicComboBoxEditor.UIResource, BasicComboBoxRenderer.UIResource, BasicTextUI.BasicCaret, BasicTextUI.BasicHighlighter, BorderUIResource, BorderUIResource.BevelBorderUIResource, BorderUIResource.CompoundBorderUIResource, BorderUIResource.EmptyBorderUIResource, BorderUIResource.EtchedBorderUIResource, BorderUIResource.LineBorderUIResource, BorderUIResource.MatteBorderUIResource, BorderUIResource.TitledBorderUIResource, ColorUIResource, ComponentInputMapUIResource, DefaultListCellRenderer.UIResource, DefaultMenuLayout, DefaultTableCellRenderer.UIResource, DimensionUIResource, FontUIResource, IconUIResource, InputMapUIResource, InsetsUIResource, JScrollPane.ScrollBar, MetalBorders.ButtonBorder, MetalBorders.Flush3DBorder, MetalBorders.InternalFrameBorder, MetalBorders.MenuBarBorder, MetalBorders.MenuItemBorder, MetalBorders.OptionDialogBorder, MetalBorders.PaletteBorder, MetalBorders.PopupMenuBorder, MetalBorders.RolloverButtonBorder, MetalBorders.ScrollPaneBorder, MetalBorders.TextFieldBorder, MetalBorders.ToggleButtonBorder, MetalBorders.ToolBarBorder, MetalCheckBoxIcon, MetalComboBoxEditor.UIResource, MetalIconFactory.PaletteCloseIcon, ScrollPaneLayout.UIResource
public interface UIResource

This interface is used to mark objects created by ComponentUI delegates. The ComponentUI.installUI() and ComponentUI.uninstallUI() methods can use this interface to decide if a properties value has been overridden. For example, the JList cellRenderer property is initialized by BasicListUI.installUI(), only if it's initial value is null:

 if (list.getCellRenderer() == null) {
     list.setCellRenderer((ListCellRenderer)(UIManager.get("List.cellRenderer")));
 }
At uninstallUI() time we reset the property to null if its value is an instance of UIResource:
 if (list.getCellRenderer() instanceof UIResource) {
     list.setCellRenderer(null);
 }
This pattern applies to all properties except the java.awt.Component properties font, foreground, and background. If one of these properties isn't initialized, or is explicitly set to null, its container provides the value. For this reason the "== null" is unreliable when installUI() is called to dynamically change a components look and feel. So at installUI() time we check to see if the current value is a UIResource:
 if (!(list.getFont() instanceof UIResource)) {
     list.setFont(UIManager.getFont("List.font"));
 }

See Also:
ComponentUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Package javax.swing.plaf

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.swing.plaf

Packages that use javax.swing.plaf
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.
javax.swing.plaf.synth | Synth is a skinnable look and feel in which all painting is delegated.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Classes in javax.swing.plaf used by javax.swing
ButtonUI
Pluggable look and feel interface for JButton.
ColorChooserUI
Pluggable look and feel interface for JColorChooser.
ComboBoxUI
Pluggable look and feel interface for JComboBox.
ComponentUI
The base class for all UI delegate objects in the Swing pluggable look and feel architecture.
DesktopIconUI
Pluggable look and feel interface for JDesktopIcon.
DesktopPaneUI
Pluggable look and feel interface for JDesktopPane.
FileChooserUI
Pluggable look and feel interface for JFileChooser.
InternalFrameUI
Pluggable look and feel interface for JInternalFrame.
LabelUI
Pluggable look and feel interface for JLabel.
ListUI
The JList pluggable look and feel delegate.
MenuBarUI
Pluggable look and feel interface for JMenuBar.
MenuItemUI
Pluggable look and feel interface for JMenuItem.
OptionPaneUI
Pluggable look and feel interface for JOptionPane.
PanelUI
Pluggable look and feel interface for Panel.
PopupMenuUI
Pluggable look and feel interface for JPopupMenu.
ProgressBarUI
Pluggable look and feel interface for JProgressBar.
RootPaneUI
Pluggable look and feel interface for JRootPane.
ScrollBarUI
Pluggable look and feel interface for JScrollBar.
ScrollPaneUI
Pluggable look and feel interface for JScrollPane.
SeparatorUI
Pluggable look and feel interface for JSeparator.
SliderUI
Pluggable look and feel interface for JSlider.
SpinnerUI
Pluggable look and feel interface for JSpinner
SplitPaneUI
Pluggable look and feel interface for JSplitPane.
TabbedPaneUI
Pluggable look and feel interface for JTabbedPane.
TableUI
Pluggable look and feel interface for JTable.
ToolBarUI
Pluggable look and feel interface for JToolBar.
ToolTipUI
Pluggable look and feel interface for JToolTip.
TreeUI
Pluggable look and feel interface for JTree.
UIResource
This interface is used to mark objects created by ComponentUI delegates.
ViewportUI
Pluggable look and feel interface for JViewport.

Classes in javax.swing.plaf used by javax.swing.plaf
ButtonUI
Pluggable look and feel interface for JButton.
ComponentUI
The base class for all UI delegate objects in the Swing pluggable look and feel architecture.
UIResource
This interface is used to mark objects created by ComponentUI delegates.

Classes in javax.swing.plaf used by javax.swing.plaf.basic
ButtonUI
Pluggable look and feel interface for JButton.
ColorChooserUI
Pluggable look and feel interface for JColorChooser.
ComboBoxUI
Pluggable look and feel interface for JComboBox.
ComponentUI
The base class for all UI delegate objects in the Swing pluggable look and feel architecture.
DesktopIconUI
Pluggable look and feel interface for JDesktopIcon.
DesktopPaneUI
Pluggable look and feel interface for JDesktopPane.
FileChooserUI
Pluggable look and feel interface for JFileChooser.
InternalFrameUI
Pluggable look and feel interface for JInternalFrame.
LabelUI
Pluggable look and feel interface for JLabel.
ListUI
The JList pluggable look and feel delegate.
MenuBarUI
Pluggable look and feel interface for JMenuBar.
MenuItemUI
Pluggable look and feel interface for JMenuItem.
OptionPaneUI
Pluggable look and feel interface for JOptionPane.
PanelUI
Pluggable look and feel interface for Panel.
PopupMenuUI
Pluggable look and feel interface for JPopupMenu.
ProgressBarUI
Pluggable look and feel interface for JProgressBar.
RootPaneUI
Pluggable look and feel interface for JRootPane.
ScrollBarUI
Pluggable look and feel interface for JScrollBar.
ScrollPaneUI
Pluggable look and feel interface for JScrollPane.
SeparatorUI
Pluggable look and feel interface for JSeparator.
SliderUI
Pluggable look and feel interface for JSlider.
SpinnerUI
Pluggable look and feel interface for JSpinner
SplitPaneUI
Pluggable look and feel interface for JSplitPane.
TabbedPaneUI
Pluggable look and feel interface for JTabbedPane.
TableHeaderUI
Pluggable look and feel interface for JTableHeader.
TableUI
Pluggable look and feel interface for JTable.
TextUI
Text editor user interface
ToolBarUI
Pluggable look and feel interface for JToolBar.
ToolTipUI
Pluggable look and feel interface for JToolTip.
TreeUI
Pluggable look and feel interface for JTree.
UIResource
This interface is used to mark objects created by ComponentUI delegates.
ViewportUI
Pluggable look and feel interface for JViewport.

Classes in javax.swing.plaf used by javax.swing.plaf.metal
ButtonUI
Pluggable look and feel interface for JButton.
ColorUIResource
ComboBoxUI
Pluggable look and feel interface for JComboBox.
ComponentUI
The base class for all UI delegate objects in the Swing pluggable look and feel architecture.
DesktopIconUI
Pluggable look and feel interface for JDesktopIcon.
FileChooserUI
Pluggable look and feel interface for JFileChooser.
FontUIResource
A subclass of java.awt.Font that implements UIResource.
InternalFrameUI
Pluggable look and feel interface for JInternalFrame.
LabelUI
Pluggable look and feel interface for JLabel.
MenuBarUI
Pluggable look and feel interface for JMenuBar.
ProgressBarUI
Pluggable look and feel interface for JProgressBar.
RootPaneUI
Pluggable look and feel interface for JRootPane.
ScrollBarUI
Pluggable look and feel interface for JScrollBar.
ScrollPaneUI
Pluggable look and feel interface for JScrollPane.
SeparatorUI
Pluggable look and feel interface for JSeparator.
SliderUI
Pluggable look and feel interface for JSlider.
SplitPaneUI
Pluggable look and feel interface for JSplitPane.
TabbedPaneUI
Pluggable look and feel interface for JTabbedPane.
TextUI
Text editor user interface
ToolBarUI
Pluggable look and feel interface for JToolBar.
ToolTipUI
Pluggable look and feel interface for JToolTip.
TreeUI
Pluggable look and feel interface for JTree.
UIResource
This interface is used to mark objects created by ComponentUI delegates.

Classes in javax.swing.plaf used by javax.swing.plaf.multi
ButtonUI
Pluggable look and feel interface for JButton.
ColorChooserUI
Pluggable look and feel interface for JColorChooser.
ComboBoxUI
Pluggable look and feel interface for JComboBox.
ComponentUI
The base class for all UI delegate objects in the Swing pluggable look and feel architecture.
DesktopIconUI
Pluggable look and feel interface for JDesktopIcon.
DesktopPaneUI
Pluggable look and feel interface for JDesktopPane.
FileChooserUI
Pluggable look and feel interface for JFileChooser.
InternalFrameUI
Pluggable look and feel interface for JInternalFrame.
LabelUI
Pluggable look and feel interface for JLabel.
ListUI
The JList pluggable look and feel delegate.
MenuBarUI
Pluggable look and feel interface for JMenuBar.
MenuItemUI
Pluggable look and feel interface for JMenuItem.
OptionPaneUI
Pluggable look and feel interface for JOptionPane.
PanelUI
Pluggable look and feel interface for Panel.
PopupMenuUI
Pluggable look and feel interface for JPopupMenu.
ProgressBarUI
Pluggable look and feel interface for JProgressBar.
RootPaneUI
Pluggable look and feel interface for JRootPane.
ScrollBarUI
Pluggable look and feel interface for JScrollBar.
ScrollPaneUI
Pluggable look and feel interface for JScrollPane.
SeparatorUI
Pluggable look and feel interface for JSeparator.
SliderUI
Pluggable look and feel interface for JSlider.
SpinnerUI
Pluggable look and feel interface for JSpinner
SplitPaneUI
Pluggable look and feel interface for JSplitPane.
TabbedPaneUI
Pluggable look and feel interface for JTabbedPane.
TableHeaderUI
Pluggable look and feel interface for JTableHeader.
TableUI
Pluggable look and feel interface for JTable.
TextUI
Text editor user interface
ToolBarUI
Pluggable look and feel interface for JToolBar.
ToolTipUI
Pluggable look and feel interface for JToolTip.
TreeUI
Pluggable look and feel interface for JTree.
ViewportUI
Pluggable look and feel interface for JViewport.

Classes in javax.swing.plaf used by javax.swing.plaf.synth
ComponentUI
The base class for all UI delegate objects in the Swing pluggable look and feel architecture.

Classes in javax.swing.plaf used by javax.swing.table
TableHeaderUI
Pluggable look and feel interface for JTableHeader.
UIResource
This interface is used to mark objects created by ComponentUI delegates.

Classes in javax.swing.plaf used by javax.swing.text
ComponentUI
The base class for all UI delegate objects in the Swing pluggable look and feel architecture.
TextUI
Text editor user interface

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ActionMapUIResource

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class ActionMapUIResource

java.lang.Object
    extended by  javax.swing.ActionMap
        extended by  javax.swing.plaf.ActionMapUIResource
All Implemented Interfaces:
Serializable, UIResource
public class ActionMapUIResource
extends ActionMap
implements UIResource

A subclass of javax.swing.ActionMap that implements UIResource. UI classes which provide an ActionMap should use this class.

Since:
1.3

Constructor Summary
ActionMapUIResource()
Method Summary
Methods inherited from class javax.swing.ActionMap
allKeys, clear, get, getParent, keys, put, remove, setParent, size
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ActionMapUIResource

public ActionMapUIResource()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


basic

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.swing.plaf.basic

Provides user interface objects built according to the Basic look and feel.

See:
Description

Interface Summary
ComboPopup The interface which defines the methods required for the implementation of the popup portion of a combo box.

Class Summary
BasicArrowButton | JButton object that draws a scaled Arrow in one of the cardinal directions.
BasicBorders | Factory object that can vend Borders appropriate for the basic L & F.
BasicBorders.ButtonBorder |
BasicBorders.FieldBorder |
BasicBorders.MarginBorder |
BasicBorders.MenuBarBorder |
BasicBorders.RadioButtonBorder |
BasicBorders.RolloverButtonBorder | Special thin border for rollover toolbar buttons.
BasicBorders.SplitPaneBorder | Draws the border around the splitpane.
BasicBorders.ToggleButtonBorder |
BasicButtonListener | Button Listener
BasicButtonUI | BasicButton implementation
BasicCheckBoxMenuItemUI | BasicCheckboxMenuItem implementation
BasicCheckBoxUI | CheckboxUI implementation for BasicCheckboxUI
BasicColorChooserUI | Provides the basic look and feel for a JColorChooser.
BasicComboBoxEditor | The default editor for editable combo boxes.
BasicComboBoxEditor.UIResource | A subclass of BasicComboBoxEditor that implements UIResource.
BasicComboBoxRenderer | ComboBox renderer
BasicComboBoxRenderer.UIResource | A subclass of BasicComboBoxRenderer that implements UIResource.
BasicComboBoxUI | Basic UI implementation for JComboBox.
BasicComboPopup | This is a basic implementation of the ComboPopup interface.
BasicDesktopIconUI | Basic L&F for a minimized window on a desktop.
BasicDesktopPaneUI | Basic L&F for a desktop.
BasicDirectoryModel | Basic implementation of a file list.
BasicEditorPaneUI | Provides the look and feel for a JEditorPane.
BasicFileChooserUI | Basic L&F implementation of a FileChooser.
BasicFormattedTextFieldUI | Provides the look and feel implementation for JFormattedTextField.
BasicGraphicsUtils |
BasicHTML | Support for providing html views for the swing components.
BasicIconFactory | Factory object that can vend Icons appropriate for the basic L & F.
BasicInternalFrameTitlePane | The class that manages a basic title bar
BasicInternalFrameUI | A basic L&F implementation of JInternalFrame.
BasicLabelUI | A Windows L&F implementation of LabelUI.
BasicListUI | An extensible implementation of ListUI.
BasicLookAndFeel | A base class to use in creating a look and feel for Swing.
BasicMenuBarUI | A default L&F implementation of MenuBarUI.
BasicMenuItemUI | BasicMenuItem implementation
BasicMenuUI | A default L&F implementation of MenuUI.
BasicOptionPaneUI | Provides the basic look and feel for a JOptionPane.
BasicOptionPaneUI.ButtonAreaLayout | ButtonAreaLayout behaves in a similar manner to FlowLayout.
BasicPanelUI | BasicPanel implementation
BasicPasswordFieldUI | Provides the Windows look and feel for a password field.
BasicPopupMenuSeparatorUI | A Basic L&F implementation of PopupMenuSeparatorUI.
BasicPopupMenuUI | A Windows L&F implementation of PopupMenuUI.
BasicProgressBarUI | A Basic L&F implementation of ProgressBarUI.
BasicRadioButtonMenuItemUI | BasicRadioButtonMenuItem implementation
BasicRadioButtonUI | RadioButtonUI implementation for BasicRadioButtonUI
BasicRootPaneUI | Basic implementation of RootPaneUI, there is one shared between all JRootPane instances.
BasicScrollBarUI | Implementation of ScrollBarUI for the Basic Look and Feel
BasicScrollPaneUI | A default L&F implementation of ScrollPaneUI.
BasicSeparatorUI | A Basic L&F implementation of SeparatorUI.
BasicSliderUI | A Basic L&F implementation of SliderUI.
BasicSpinnerUI | The default Spinner UI delegate.
BasicSplitPaneDivider | Divider used by BasicSplitPaneUI.
BasicSplitPaneUI | A Basic L&F implementation of the SplitPaneUI.
BasicTabbedPaneUI | A Basic L&F implementation of TabbedPaneUI.
BasicTableHeaderUI | BasicTableHeaderUI implementation
BasicTableUI | BasicTableUI implementation
BasicTextAreaUI | Provides the look and feel for a plain text editor.
BasicTextFieldUI | Basis of a look and feel for a JTextField.
BasicTextPaneUI | Provides the look and feel for a styled text editor.
BasicTextUI | Basis of a text components look-and-feel.
BasicTextUI.BasicCaret |
BasicTextUI.BasicHighlighter |
BasicToggleButtonUI | BasicToggleButton implementation
BasicToolBarSeparatorUI | A Basic L&F implementation of ToolBarSeparatorUI.
BasicToolBarUI | A Basic L&F implementation of ToolBarUI.
BasicToolTipUI | Standard tool tip L&F.
BasicTreeUI | The basic L&F for a hierarchical data structure.
BasicViewportUI | BasicViewport implementation
DefaultMenuLayout | The default layout manager for Popup menus and menubars.

Package javax.swing.plaf.basic Description

Provides user interface objects built according to the Basic look and feel. The Basic look and feel provides default behavior used by many look and feel packages. It contains components, layout managers, events, event listeners, and adapters. You can subclass the classes in this package to create your own customized look and feel.

These classes are designed to be used while the corresponding LookAndFeel class has been installed (UIManager.setLookAndFeel(new XXXLookAndFeel())). Using them while a different LookAndFeel is installed may produce unexpected results, including exceptions. Additionally, changing the LookAndFeel maintained by the UIManager without updating the corresponding ComponentUI of any JComponents may also produce unexpected results, such as the wrong colors showing up, and is generally not encouraged.

Note: Most of the Swing API is not thread safe. For details, see Threads and Swing, a section in The Java Tutorial.

Since:
1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.swing.plaf.basic Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.swing.plaf.basic

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.swing.AbstractAction (implements javax.swing.Action, java.lang.Cloneable, java.io.Serializable)
      • javax.swing.plaf.basic.BasicDesktopPaneUI.CloseAction
      • javax.swing.plaf.basic.BasicDesktopPaneUI.MaximizeAction
      • javax.swing.plaf.basic.BasicDesktopPaneUI.MinimizeAction
      • javax.swing.plaf.basic.BasicDesktopPaneUI.NavigateAction
      • javax.swing.plaf.basic.BasicDesktopPaneUI.OpenAction
      • javax.swing.plaf.basic.BasicFileChooserUI.ApproveSelectionAction
      • javax.swing.plaf.basic.BasicFileChooserUI.CancelSelectionAction
      • javax.swing.plaf.basic.BasicFileChooserUI.ChangeToParentDirectoryAction
      • javax.swing.plaf.basic.BasicFileChooserUI.GoHomeAction
      • javax.swing.plaf.basic.BasicFileChooserUI.NewFolderAction
      • javax.swing.plaf.basic.BasicFileChooserUI.UpdateAction
      • javax.swing.plaf.basic.BasicInternalFrameTitlePane.CloseAction
      • javax.swing.plaf.basic.BasicInternalFrameTitlePane.IconifyAction
      • javax.swing.plaf.basic.BasicInternalFrameTitlePane.MaximizeAction
      • javax.swing.plaf.basic.BasicInternalFrameTitlePane.MoveAction
      • javax.swing.plaf.basic.BasicInternalFrameTitlePane.RestoreAction
      • javax.swing.plaf.basic.BasicInternalFrameTitlePane.SizeAction
      • javax.swing.plaf.basic.BasicSliderUI.ActionScroller
      • javax.swing.plaf.basic.BasicTreeUI.TreeCancelEditingAction
      • javax.swing.plaf.basic.BasicTreeUI.TreeHomeAction
      • javax.swing.plaf.basic.BasicTreeUI.TreeIncrementAction
      • javax.swing.plaf.basic.BasicTreeUI.TreePageAction
      • javax.swing.plaf.basic.BasicTreeUI.TreeToggleAction
      • javax.swing.plaf.basic.BasicTreeUI.TreeTraverseAction
    • javax.swing.border.AbstractBorder (implements javax.swing.border.Border, java.io.Serializable)
      • javax.swing.plaf.basic.BasicBorders.ButtonBorder (implements javax.swing.plaf.UIResource)
        • javax.swing.plaf.basic.BasicBorders.RadioButtonBorder
        • javax.swing.plaf.basic.BasicBorders.RolloverButtonBorder
        • javax.swing.plaf.basic.BasicBorders.ToggleButtonBorder
      • javax.swing.plaf.basic.BasicBorders.FieldBorder (implements javax.swing.plaf.UIResource)
      • javax.swing.plaf.basic.BasicBorders.MarginBorder (implements javax.swing.plaf.UIResource)
      • javax.swing.plaf.basic.BasicBorders.MenuBarBorder (implements javax.swing.plaf.UIResource)
    • javax.swing.tree.AbstractLayoutCache.NodeDimensions
      • javax.swing.plaf.basic.BasicTreeUI.NodeDimensionsHandler
    • javax.swing.AbstractListModel (implements javax.swing.ListModel, java.io.Serializable)
      • javax.swing.plaf.basic.BasicDirectoryModel (implements java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicBorders
    • javax.swing.plaf.basic.BasicBorders.SplitPaneBorder (implements javax.swing.border.Border, javax.swing.plaf.UIResource)
    • javax.swing.plaf.basic.BasicButtonListener (implements javax.swing.event.ChangeListener, java.awt.event.FocusListener, java.awt.event.MouseListener, java.awt.event.MouseMotionListener, java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicColorChooserUI.PropertyHandler (implements java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicComboBoxEditor (implements javax.swing.ComboBoxEditor, java.awt.event.FocusListener)
      • javax.swing.plaf.basic.BasicComboBoxEditor.UIResource (implements javax.swing.plaf.UIResource)
    • javax.swing.plaf.basic.BasicComboBoxUI.ComboBoxLayoutManager (implements java.awt.LayoutManager)
    • javax.swing.plaf.basic.BasicComboBoxUI.FocusHandler (implements java.awt.event.FocusListener)
    • javax.swing.plaf.basic.BasicComboBoxUI.ItemHandler (implements java.awt.event.ItemListener)
    • javax.swing.plaf.basic.BasicComboBoxUI.ListDataHandler (implements javax.swing.event.ListDataListener)
    • javax.swing.plaf.basic.BasicComboBoxUI.PropertyChangeHandler (implements java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicComboPopup.ItemHandler (implements java.awt.event.ItemListener)
    • javax.swing.plaf.basic.BasicComboPopup.ListDataHandler (implements javax.swing.event.ListDataListener)
    • javax.swing.plaf.basic.BasicComboPopup.ListSelectionHandler (implements javax.swing.event.ListSelectionListener)
    • javax.swing.plaf.basic.BasicComboPopup.PropertyChangeHandler (implements java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicFileChooserUI.SelectionListener (implements javax.swing.event.ListSelectionListener)
    • javax.swing.plaf.basic.BasicGraphicsUtils
    • javax.swing.plaf.basic.BasicHTML
    • javax.swing.plaf.basic.BasicIconFactory (implements java.io.Serializable)
    • javax.swing.plaf.basic.BasicInternalFrameTitlePane.PropertyChangeHandler (implements java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicInternalFrameTitlePane.TitlePaneLayout (implements java.awt.LayoutManager)
    • javax.swing.plaf.basic.BasicInternalFrameUI.BasicInternalFrameListener (implements javax.swing.event.InternalFrameListener)
    • javax.swing.plaf.basic.BasicInternalFrameUI.ComponentHandler (implements java.awt.event.ComponentListener)
    • javax.swing.plaf.basic.BasicInternalFrameUI.GlassPaneDispatcher (implements javax.swing.event.MouseInputListener)
    • javax.swing.plaf.basic.BasicInternalFrameUI.InternalFrameLayout (implements java.awt.LayoutManager)
    • javax.swing.plaf.basic.BasicInternalFrameUI.InternalFramePropertyChangeListener (implements java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicListUI.FocusHandler (implements java.awt.event.FocusListener)
    • javax.swing.plaf.basic.BasicListUI.ListDataHandler (implements javax.swing.event.ListDataListener)
    • javax.swing.plaf.basic.BasicListUI.ListSelectionHandler (implements javax.swing.event.ListSelectionListener)
    • javax.swing.plaf.basic.BasicListUI.MouseInputHandler (implements javax.swing.event.MouseInputListener)
    • javax.swing.plaf.basic.BasicListUI.PropertyChangeHandler (implements java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicMenuItemUI.MouseInputHandler (implements javax.swing.event.MouseInputListener)
    • javax.swing.plaf.basic.BasicMenuUI.ChangeHandler (implements javax.swing.event.ChangeListener)
    • javax.swing.plaf.basic.BasicMenuUI.MouseInputHandler (implements javax.swing.event.MouseInputListener)
    • javax.swing.plaf.basic.BasicOptionPaneUI.ButtonActionListener (implements java.awt.event.ActionListener)
    • javax.swing.plaf.basic.BasicOptionPaneUI.ButtonAreaLayout (implements java.awt.LayoutManager)
    • javax.swing.plaf.basic.BasicOptionPaneUI.PropertyChangeHandler (implements java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicProgressBarUI.ChangeHandler (implements javax.swing.event.ChangeListener)
    • javax.swing.plaf.basic.BasicScrollBarUI.ModelListener (implements javax.swing.event.ChangeListener)
    • javax.swing.plaf.basic.BasicScrollBarUI.PropertyChangeHandler (implements java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicScrollBarUI.ScrollListener (implements java.awt.event.ActionListener)
    • javax.swing.plaf.basic.BasicScrollPaneUI.HSBChangeListener (implements javax.swing.event.ChangeListener)
    • javax.swing.plaf.basic.BasicScrollPaneUI.MouseWheelHandler (implements java.awt.event.MouseWheelListener)
    • javax.swing.plaf.basic.BasicScrollPaneUI.PropertyChangeHandler (implements java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicScrollPaneUI.ViewportChangeHandler (implements javax.swing.event.ChangeListener)
    • javax.swing.plaf.basic.BasicScrollPaneUI.VSBChangeListener (implements javax.swing.event.ChangeListener)
    • javax.swing.plaf.basic.BasicSliderUI.ChangeHandler (implements javax.swing.event.ChangeListener)
    • javax.swing.plaf.basic.BasicSliderUI.FocusHandler (implements java.awt.event.FocusListener)
    • javax.swing.plaf.basic.BasicSliderUI.PropertyChangeHandler (implements java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicSliderUI.ScrollListener (implements java.awt.event.ActionListener)
    • javax.swing.plaf.basic.BasicSplitPaneDivider.DividerLayout (implements java.awt.LayoutManager)
    • javax.swing.plaf.basic.BasicSplitPaneDivider.DragController
      • javax.swing.plaf.basic.BasicSplitPaneDivider.VerticalDragController
    • javax.swing.plaf.basic.BasicSplitPaneUI.BasicHorizontalLayoutManager (implements java.awt.LayoutManager2)
      • javax.swing.plaf.basic.BasicSplitPaneUI.BasicVerticalLayoutManager
    • javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardDownRightHandler (implements java.awt.event.ActionListener)
    • javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardEndHandler (implements java.awt.event.ActionListener)
    • javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardHomeHandler (implements java.awt.event.ActionListener)
    • javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardResizeToggleHandler (implements java.awt.event.ActionListener)
    • javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardUpLeftHandler (implements java.awt.event.ActionListener)
    • javax.swing.plaf.basic.BasicSplitPaneUI.PropertyHandler (implements java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicTabbedPaneUI.PropertyChangeHandler (implements java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicTabbedPaneUI.TabbedPaneLayout (implements java.awt.LayoutManager)
    • javax.swing.plaf.basic.BasicTabbedPaneUI.TabSelectionHandler (implements javax.swing.event.ChangeListener)
    • javax.swing.plaf.basic.BasicTableHeaderUI.MouseInputHandler (implements javax.swing.event.MouseInputListener)
    • javax.swing.plaf.basic.BasicTableUI.FocusHandler (implements java.awt.event.FocusListener)
    • javax.swing.plaf.basic.BasicTableUI.KeyHandler (implements java.awt.event.KeyListener)
    • javax.swing.plaf.basic.BasicTableUI.MouseInputHandler (implements javax.swing.event.MouseInputListener)
    • javax.swing.plaf.basic.BasicToolBarUI.DockingListener (implements javax.swing.event.MouseInputListener)
    • javax.swing.plaf.basic.BasicToolBarUI.PropertyListener (implements java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicToolBarUI.ToolBarContListener (implements java.awt.event.ContainerListener)
    • javax.swing.plaf.basic.BasicToolBarUI.ToolBarFocusListener (implements java.awt.event.FocusListener)
    • javax.swing.plaf.basic.BasicTreeUI.CellEditorHandler (implements javax.swing.event.CellEditorListener)
    • javax.swing.plaf.basic.BasicTreeUI.FocusHandler (implements java.awt.event.FocusListener)
    • javax.swing.plaf.basic.BasicTreeUI.MouseInputHandler (implements javax.swing.event.MouseInputListener)
    • javax.swing.plaf.basic.BasicTreeUI.PropertyChangeHandler (implements java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicTreeUI.SelectionModelPropertyChangeHandler (implements java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicTreeUI.TreeExpansionHandler (implements javax.swing.event.TreeExpansionListener)
    • javax.swing.plaf.basic.BasicTreeUI.TreeModelHandler (implements javax.swing.event.TreeModelListener)
    • javax.swing.plaf.basic.BasicTreeUI.TreeSelectionHandler (implements javax.swing.event.TreeSelectionListener)
    • javax.swing.BoxLayout (implements java.awt.LayoutManager2, java.io.Serializable)
      • javax.swing.plaf.basic.DefaultMenuLayout (implements javax.swing.plaf.UIResource)
    • java.awt.Component (implements java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable)
      • java.awt.Container
        • javax.swing.plaf.basic.BasicSplitPaneDivider (implements java.beans.PropertyChangeListener)
        • javax.swing.JComponent (implements java.io.Serializable)
          • javax.swing.AbstractButton (implements java.awt.ItemSelectable, javax.swing.SwingConstants)
            • javax.swing.JButton (implements javax.accessibility.Accessible)
              • javax.swing.plaf.basic.BasicArrowButton (implements javax.swing.SwingConstants)
          • javax.swing.plaf.basic.BasicInternalFrameTitlePane
          • javax.swing.JLabel (implements javax.accessibility.Accessible, javax.swing.SwingConstants)
            • javax.swing.plaf.basic.BasicComboBoxRenderer (implements javax.swing.ListCellRenderer, java.io.Serializable)
              • javax.swing.plaf.basic.BasicComboBoxRenderer.UIResource (implements javax.swing.plaf.UIResource)
          • javax.swing.JMenuBar (implements javax.accessibility.Accessible, javax.swing.MenuElement)
            • javax.swing.plaf.basic.BasicInternalFrameTitlePane.SystemMenuBar
          • javax.swing.JPopupMenu (implements javax.accessibility.Accessible, javax.swing.MenuElement)
            • javax.swing.plaf.basic.BasicComboPopup (implements javax.swing.plaf.basic.ComboPopup)
        • java.awt.Window (implements javax.accessibility.Accessible)
          • javax.swing.plaf.basic.BasicToolBarUI.DragWindow
    • java.awt.event.ComponentAdapter (implements java.awt.event.ComponentListener)
      • javax.swing.plaf.basic.BasicSliderUI.ComponentHandler
      • javax.swing.plaf.basic.BasicTreeUI.ComponentHandler (implements java.awt.event.ActionListener)
    • javax.swing.plaf.ComponentUI
      • javax.swing.plaf.ButtonUI
        • javax.swing.plaf.basic.BasicButtonUI
          • javax.swing.plaf.basic.BasicToggleButtonUI
            • javax.swing.plaf.basic.BasicRadioButtonUI
              • javax.swing.plaf.basic.BasicCheckBoxUI
        • javax.swing.plaf.MenuItemUI
          • javax.swing.plaf.basic.BasicMenuItemUI
            • javax.swing.plaf.basic.BasicCheckBoxMenuItemUI
            • javax.swing.plaf.basic.BasicMenuUI
            • javax.swing.plaf.basic.BasicRadioButtonMenuItemUI
      • javax.swing.plaf.ColorChooserUI
        • javax.swing.plaf.basic.BasicColorChooserUI
      • javax.swing.plaf.ComboBoxUI
        • javax.swing.plaf.basic.BasicComboBoxUI
      • javax.swing.plaf.DesktopIconUI
        • javax.swing.plaf.basic.BasicDesktopIconUI
      • javax.swing.plaf.DesktopPaneUI
        • javax.swing.plaf.basic.BasicDesktopPaneUI
      • javax.swing.plaf.FileChooserUI
        • javax.swing.plaf.basic.BasicFileChooserUI
      • javax.swing.plaf.InternalFrameUI
        • javax.swing.plaf.basic.BasicInternalFrameUI
      • javax.swing.plaf.LabelUI
        • javax.swing.plaf.basic.BasicLabelUI (implements java.beans.PropertyChangeListener)
      • javax.swing.plaf.ListUI
        • javax.swing.plaf.basic.BasicListUI
      • javax.swing.plaf.MenuBarUI
        • javax.swing.plaf.basic.BasicMenuBarUI
      • javax.swing.plaf.OptionPaneUI
        • javax.swing.plaf.basic.BasicOptionPaneUI
      • javax.swing.plaf.PanelUI
        • javax.swing.plaf.basic.BasicPanelUI
      • javax.swing.plaf.PopupMenuUI
        • javax.swing.plaf.basic.BasicPopupMenuUI
      • javax.swing.plaf.ProgressBarUI
        • javax.swing.plaf.basic.BasicProgressBarUI
      • javax.swing.plaf.RootPaneUI
        • javax.swing.plaf.basic.BasicRootPaneUI (implements java.beans.PropertyChangeListener)
      • javax.swing.plaf.ScrollBarUI
        • javax.swing.plaf.basic.BasicScrollBarUI (implements java.awt.LayoutManager, javax.swing.SwingConstants)
      • javax.swing.plaf.ScrollPaneUI
        • javax.swing.plaf.basic.BasicScrollPaneUI (implements javax.swing.ScrollPaneConstants)
      • javax.swing.plaf.SeparatorUI
        • javax.swing.plaf.basic.BasicSeparatorUI
          • javax.swing.plaf.basic.BasicPopupMenuSeparatorUI
          • javax.swing.plaf.basic.BasicToolBarSeparatorUI
      • javax.swing.plaf.SliderUI
        • javax.swing.plaf.basic.BasicSliderUI
      • javax.swing.plaf.SpinnerUI
        • javax.swing.plaf.basic.BasicSpinnerUI
      • javax.swing.plaf.SplitPaneUI
        • javax.swing.plaf.basic.BasicSplitPaneUI
      • javax.swing.plaf.TabbedPaneUI
        • javax.swing.plaf.basic.BasicTabbedPaneUI (implements javax.swing.SwingConstants)
      • javax.swing.plaf.TableHeaderUI
        • javax.swing.plaf.basic.BasicTableHeaderUI
      • javax.swing.plaf.TableUI
        • javax.swing.plaf.basic.BasicTableUI
      • javax.swing.plaf.TextUI
        • javax.swing.plaf.basic.BasicTextUI (implements javax.swing.text.ViewFactory)
          • javax.swing.plaf.basic.BasicEditorPaneUI
            • javax.swing.plaf.basic.BasicTextPaneUI
          • javax.swing.plaf.basic.BasicTextAreaUI
          • javax.swing.plaf.basic.BasicTextFieldUI
            • javax.swing.plaf.basic.BasicFormattedTextFieldUI
            • javax.swing.plaf.basic.BasicPasswordFieldUI
      • javax.swing.plaf.ToolBarUI
        • javax.swing.plaf.basic.BasicToolBarUI (implements javax.swing.SwingConstants)
      • javax.swing.plaf.ToolTipUI
        • javax.swing.plaf.basic.BasicToolTipUI
      • javax.swing.plaf.TreeUI
        • javax.swing.plaf.basic.BasicTreeUI
      • javax.swing.plaf.ViewportUI
        • javax.swing.plaf.basic.BasicViewportUI
    • javax.swing.filechooser.FileFilter
      • javax.swing.plaf.basic.BasicFileChooserUI.AcceptAllFileFilter
    • javax.swing.filechooser.FileView
      • javax.swing.plaf.basic.BasicFileChooserUI.BasicFileView
    • java.awt.event.FocusAdapter (implements java.awt.event.FocusListener)
      • javax.swing.plaf.basic.BasicSplitPaneUI.FocusHandler
      • javax.swing.plaf.basic.BasicTabbedPaneUI.FocusHandler
    • java.awt.event.KeyAdapter (implements java.awt.event.KeyListener)
      • javax.swing.plaf.basic.BasicComboBoxUI.KeyHandler
      • javax.swing.plaf.basic.BasicComboPopup.InvocationKeyHandler
      • javax.swing.plaf.basic.BasicTreeUI.KeyHandler
    • javax.swing.text.LayeredHighlighter (implements javax.swing.text.Highlighter)
      • javax.swing.text.DefaultHighlighter
        • javax.swing.plaf.basic.BasicTextUI.BasicHighlighter (implements javax.swing.plaf.UIResource)
    • javax.swing.LookAndFeel
      • javax.swing.plaf.basic.BasicLookAndFeel (implements java.io.Serializable)
    • java.awt.event.MouseAdapter (implements java.awt.event.MouseListener, java.awt.event.MouseMotionListener, java.awt.event.MouseWheelListener)
      • javax.swing.plaf.basic.BasicComboPopup.InvocationMouseHandler
      • javax.swing.plaf.basic.BasicComboPopup.ListMouseHandler
      • javax.swing.plaf.basic.BasicFileChooserUI.DoubleClickListener
      • javax.swing.plaf.basic.BasicScrollBarUI.ArrowButtonListener
      • javax.swing.plaf.basic.BasicScrollBarUI.TrackListener (implements java.awt.event.MouseMotionListener)
      • javax.swing.plaf.basic.BasicSplitPaneDivider.MouseHandler (implements java.awt.event.MouseMotionListener)
      • javax.swing.plaf.basic.BasicTabbedPaneUI.MouseHandler
      • javax.swing.plaf.basic.BasicTreeUI.MouseHandler (implements java.awt.event.MouseMotionListener)
      • javax.swing.event.MouseInputAdapter (implements javax.swing.event.MouseInputListener)
        • javax.swing.plaf.basic.BasicDesktopIconUI.MouseInputHandler
        • javax.swing.plaf.basic.BasicInternalFrameUI.BorderListener (implements javax.swing.SwingConstants)
        • javax.swing.plaf.basic.BasicSliderUI.TrackListener
    • java.awt.event.MouseMotionAdapter (implements java.awt.event.MouseMotionListener)
      • javax.swing.plaf.basic.BasicComboPopup.InvocationMouseMotionHandler
      • javax.swing.plaf.basic.BasicComboPopup.ListMouseMotionHandler
    • java.awt.geom.RectangularShape (implements java.lang.Cloneable, java.awt.Shape)
      • java.awt.geom.Rectangle2D
        • java.awt.Rectangle (implements java.io.Serializable, java.awt.Shape)
          • javax.swing.text.DefaultCaret (implements javax.swing.text.Caret, java.awt.event.FocusListener, java.awt.event.MouseListener, java.awt.event.MouseMotionListener)
            • javax.swing.plaf.basic.BasicTextUI.BasicCaret (implements javax.swing.plaf.UIResource)
    • java.awt.event.WindowAdapter (implements java.awt.event.WindowFocusListener, java.awt.event.WindowListener, java.awt.event.WindowStateListener)
      • javax.swing.plaf.basic.BasicToolBarUI.FrameListener

Interface Hierarchy

  • javax.swing.plaf.basic.ComboPopup
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.swing.plaf.basic

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.swing.plaf.basic

Packages that use javax.swing.plaf.basic
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.synth | Synth is a skinnable look and feel in which all painting is delegated.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Classes in javax.swing.plaf.basic used by javax.swing.plaf.basic
BasicBorders.ButtonBorder
BasicButtonListener
Button Listener
BasicButtonUI
BasicButton implementation
BasicComboBoxEditor
The default editor for editable combo boxes.
BasicComboBoxRenderer
ComboBox renderer
BasicDirectoryModel
Basic implementation of a file list.
BasicEditorPaneUI
Provides the look and feel for a JEditorPane.
BasicInternalFrameTitlePane
The class that manages a basic title bar
BasicLabelUI
A Windows L&F implementation of LabelUI.
BasicMenuItemUI
BasicMenuItem implementation
BasicMenuUI
A default L&F implementation of MenuUI.
BasicRadioButtonUI
RadioButtonUI implementation for BasicRadioButtonUI
BasicScrollBarUI.ArrowButtonListener
Listener for cursor keys.
BasicScrollBarUI.ModelListener
A listener to listen for model changes.
BasicScrollBarUI.ScrollListener
Listener for scrolling events initiated in the ScrollPane.
BasicScrollBarUI.TrackListener
Track mouse drags.
BasicSeparatorUI
A Basic L&F implementation of SeparatorUI.
BasicSliderUI.ScrollListener
Scroll-event listener.
BasicSliderUI.TrackListener
Track mouse movements.
BasicSplitPaneDivider
Divider used by BasicSplitPaneUI.
BasicSplitPaneDivider.DragController
Handles the events during a dragging session for a HORIZONTAL_SPLIT oriented split pane.
BasicSplitPaneDivider.MouseHandler
MouseHandler is responsible for converting mouse events (released, dragged...) into the appropriate DragController methods.
BasicSplitPaneUI
A Basic L&F implementation of the SplitPaneUI.
BasicSplitPaneUI.BasicHorizontalLayoutManager
LayoutManager for JSplitPanes that have an orientation of HORIZONTAL_SPLIT.
BasicTextFieldUI
Basis of a look and feel for a JTextField.
BasicTextUI
Basis of a text components look-and-feel.
BasicToggleButtonUI
BasicToggleButton implementation
BasicToolBarUI.DragWindow
ComboPopup
The interface which defines the methods required for the implementation of the popup portion of a combo box.

Classes in javax.swing.plaf.basic used by javax.swing.plaf.metal
BasicArrowButton
JButton object that draws a scaled Arrow in one of the cardinal directions.
BasicButtonListener
Button Listener
BasicButtonUI
BasicButton implementation
BasicComboBoxEditor
The default editor for editable combo boxes.
BasicComboBoxUI
Basic UI implementation for JComboBox.
BasicComboBoxUI.ComboBoxLayoutManager
This layout manager handles the 'standard' layout of combo boxes.
BasicComboBoxUI.PropertyChangeHandler
This listener watches for bound properties that have changed in the combo box.
BasicComboPopup
This is a basic implementation of the ComboPopup interface.
BasicDesktopIconUI
Basic L&F for a minimized window on a desktop.
BasicFileChooserUI
Basic L&F implementation of a FileChooser.
BasicInternalFrameTitlePane
The class that manages a basic title bar
BasicInternalFrameUI
A basic L&F implementation of JInternalFrame.
BasicLabelUI
A Windows L&F implementation of LabelUI.
BasicLookAndFeel
A base class to use in creating a look and feel for Swing.
BasicMenuBarUI
A default L&F implementation of MenuBarUI.
BasicProgressBarUI
A Basic L&F implementation of ProgressBarUI.
BasicRadioButtonUI
RadioButtonUI implementation for BasicRadioButtonUI
BasicRootPaneUI
Basic implementation of RootPaneUI, there is one shared between all JRootPane instances.
BasicScrollBarUI
Implementation of ScrollBarUI for the Basic Look and Feel
BasicScrollPaneUI
A default L&F implementation of ScrollPaneUI.
BasicSeparatorUI
A Basic L&F implementation of SeparatorUI.
BasicSliderUI
A Basic L&F implementation of SliderUI.
BasicSliderUI.PropertyChangeHandler
BasicSplitPaneDivider
Divider used by BasicSplitPaneUI.
BasicSplitPaneUI
A Basic L&F implementation of the SplitPaneUI.
BasicTabbedPaneUI
A Basic L&F implementation of TabbedPaneUI.
BasicTabbedPaneUI.TabbedPaneLayout
This class should be treated as a "protected" inner class.
BasicTextFieldUI
Basis of a look and feel for a JTextField.
BasicTextUI
Basis of a text components look-and-feel.
BasicToggleButtonUI
BasicToggleButton implementation
BasicToolBarUI
A Basic L&F implementation of ToolBarUI.
BasicToolBarUI.DockingListener
This class should be treated as a "protected" inner class.
BasicToolBarUI.PropertyListener
BasicToolBarUI.ToolBarContListener
BasicToolTipUI
Standard tool tip L&F.
BasicTreeUI
The basic L&F for a hierarchical data structure.
ComboPopup
The interface which defines the methods required for the implementation of the popup portion of a combo box.

Classes in javax.swing.plaf.basic used by javax.swing.plaf.synth
BasicLookAndFeel
A base class to use in creating a look and feel for Swing.

Classes in javax.swing.plaf.basic used by javax.swing.text
BasicTextUI
Basis of a text components look-and-feel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


BasicArrowButton

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicArrowButton

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.AbstractButton
                    extended by  javax.swing.JButton
                        extended by  javax.swing.plaf.basic.BasicArrowButton
All Implemented Interfaces:
ImageObserver, ItemSelectable, MenuContainer, Serializable, Accessible, SwingConstants
Direct Known Subclasses:
MetalScrollButton
public class BasicArrowButton
extends JButton
implements SwingConstants

JButton object that draws a scaled Arrow in one of the cardinal directions.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JButton
JButton.AccessibleJButton
Nested classes/interfaces inherited from class javax.swing.AbstractButton
AbstractButton.AccessibleAbstractButton, AbstractButton.ButtonChangeListener
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected  int direction
The direction of the arrow.
Fields inherited from class javax.swing.AbstractButton
actionListener, BORDER_PAINTED_CHANGED_PROPERTY, changeEvent, changeListener, CONTENT_AREA_FILLED_CHANGED_PROPERTY, DISABLED_ICON_CHANGED_PROPERTY, DISABLED_SELECTED_ICON_CHANGED_PROPERTY, FOCUS_PAINTED_CHANGED_PROPERTY, HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY, HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY, ICON_CHANGED_PROPERTY, itemListener, MARGIN_CHANGED_PROPERTY, MNEMONIC_CHANGED_PROPERTY, model, MODEL_CHANGED_PROPERTY, PRESSED_ICON_CHANGED_PROPERTY, ROLLOVER_ENABLED_CHANGED_PROPERTY, ROLLOVER_ICON_CHANGED_PROPERTY, ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY, SELECTED_ICON_CHANGED_PROPERTY, TEXT_CHANGED_PROPERTY, VERTICAL_ALIGNMENT_CHANGED_PROPERTY, VERTICAL_TEXT_POSITION_CHANGED_PROPERTY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
BasicArrowButton(int direction)
Creates a BasicArrowButton whose arrow is drawn in the specified direction.
BasicArrowButton(int direction, Color background, Color shadow, Color darkShadow, Color highlight)
Creates a BasicArrowButton whose arrow is drawn in the specified direction and with the specified colors.
Method Summary
int | getDirection() Returns the direction of the arrow.
Dimension | getMaximumSize() Returns the maximum size of the BasicArrowButton.
Dimension | getMinimumSize() Returns the minimum size of the BasicArrowButton.
Dimension | getPreferredSize() Returns the preferred size of the BasicArrowButton.
boolean | isFocusTraversable() Returns whether the arrow button should get the focus.
void | paint(Graphics g) Invoked by Swing to draw components.
void | paintTriangle(Graphics g, int x, int y, int size, int direction, boolean isEnabled) Paints a triangle.
void | setDirection(int dir) Sets the direction of the arrow.
Methods inherited from class javax.swing.JButton
getAccessibleContext, getUIClassID, isDefaultButton, isDefaultCapable, paramString, removeNotify, setDefaultCapable, updateUI
Methods inherited from class javax.swing.AbstractButton
actionPropertyChanged, addActionListener, addChangeListener, addImpl, addItemListener, checkHorizontalKey, checkVerticalKey, configurePropertiesFromAction, createActionListener, createActionPropertyChangeListener, createChangeListener, createItemListener, doClick, doClick, fireActionPerformed, fireItemStateChanged, fireStateChanged, getAction, getActionCommand, getActionListeners, getChangeListeners, getDisabledIcon, getDisabledSelectedIcon, getDisplayedMnemonicIndex, getHideActionText, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getItemListeners, getLabel, getMargin, getMnemonic, getModel, getMultiClickThreshhold, getPressedIcon, getRolloverIcon, getRolloverSelectedIcon, getSelectedIcon, getSelectedObjects, getText, getUI, getVerticalAlignment, getVerticalTextPosition, imageUpdate, init, isBorderPainted, isContentAreaFilled, isFocusPainted, isRolloverEnabled, isSelected, paintBorder, removeActionListener, removeChangeListener, removeItemListener, setAction, setActionCommand, setBorderPainted, setContentAreaFilled, setDisabledIcon, setDisabledSelectedIcon, setDisplayedMnemonicIndex, setEnabled, setFocusPainted, setHideActionText, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabel, setLayout, setMargin, setMnemonic, setMnemonic, setModel, setMultiClickThreshhold, setPressedIcon, setRolloverEnabled, setRolloverIcon, setRolloverSelectedIcon, setSelected, setSelectedIcon, setText, setUI, setVerticalAlignment, setVerticalTextPosition
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

direction

protected int direction
The direction of the arrow. One of SwingConstants.NORTH, SwingConstants.SOUTH, SwingConstants.EAST or SwingConstants.WEST.

Constructor Detail

BasicArrowButton

public BasicArrowButton(int direction,
                        Color background,
                        Color shadow,
                        Color darkShadow,
                        Color highlight)
Creates a BasicArrowButton whose arrow is drawn in the specified direction and with the specified colors.

Parameters:
direction - the direction of the arrow; one of SwingConstants.NORTH, SwingConstants.SOUTH, SwingConstants.EAST or SwingConstants.WEST
background - the background color of the button
shadow - the color of the shadow
darkShadow - the color of the dark shadow
highlight - the color of the highlight
Since:
1.4

BasicArrowButton

public BasicArrowButton(int direction)
Creates a BasicArrowButton whose arrow is drawn in the specified direction.

Parameters:
direction - the direction of the arrow; one of SwingConstants.NORTH, SwingConstants.SOUTH, SwingConstants.EAST or SwingConstants.WEST
Method Detail

getDirection

public int getDirection()
Returns the direction of the arrow.

Parameters:
direction - the direction of the arrow; one of SwingConstants.NORTH, SwingConstants.SOUTH, SwingConstants.EAST or SwingConstants.WEST

setDirection

public void setDirection(int dir)
Sets the direction of the arrow.

Parameters:
direction - the direction of the arrow; one of of SwingConstants.NORTH, SwingConstants.SOUTH, SwingConstants.EAST or SwingConstants.WEST

paint

public void paint(Graphics g)
Description copied from class: JComponent
Invoked by Swing to draw components. Applications should not invoke paint directly, but should instead use the repaint method to schedule the component for redrawing.

This method actually delegates the work of painting to three protected methods: paintComponent, paintBorder, and paintChildren. They're called in the order listed to ensure that children appear on top of component itself. Generally speaking, the component and its children should not paint in the insets area allocated to the border. Subclasses can just override this method, as always. A subclass that just wants to specialize the UI (look and feel) delegate's paint method should just override paintComponent.

Overrides:
paint in class JComponent
Parameters:
g - the Graphics context in which to paint
See Also:
JComponent.paintComponent(java.awt.Graphics),
JComponent.paintBorder(java.awt.Graphics),
JComponent.paintChildren(java.awt.Graphics),
JComponent.getComponentGraphics(java.awt.Graphics),
JComponent.repaint(long, int, int, int, int)

getPreferredSize

public Dimension getPreferredSize()
Returns the preferred size of the BasicArrowButton.

Overrides:
getPreferredSize in class JComponent
Returns:
the preferred size
See Also:
JComponent.setPreferredSize(java.awt.Dimension), ComponentUI

getMinimumSize

public Dimension getMinimumSize()
Returns the minimum size of the BasicArrowButton.

Overrides:
getMinimumSize in class JComponent
Returns:
the minimum size
See Also:
JComponent.setMinimumSize(java.awt.Dimension), ComponentUI

getMaximumSize

public Dimension getMaximumSize()
Returns the maximum size of the BasicArrowButton.

Overrides:
getMaximumSize in class JComponent
Returns:
the maximum size
See Also:
JComponent.setMaximumSize(java.awt.Dimension), ComponentUI

isFocusTraversable

public boolean isFocusTraversable()
Returns whether the arrow button should get the focus. BasicArrowButtons are used as a child component of composite components such as JScrollBar and JComboBox. Since the composite component typically gets the focus, this method is overriden to return false.

Overrides:
isFocusTraversable in class Component
Returns:
false
See Also:
Component.setFocusable(boolean)

paintTriangle

public void paintTriangle(Graphics g,
                          int x,
                          int y,
                          int size,
                          int direction,
                          boolean isEnabled)
Paints a triangle.

Parameters:
g - the Graphics to draw to
x - the x coordinate
y - the y coordinate
size - the size of the triangle to draw
direction - the direction in which to draw the arrow; one of SwingConstants.NORTH, SwingConstants.SOUTH, SwingConstants.EAST or SwingConstants.WEST
isEnabled - whether or not the arrow is drawn enabled
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


BasicBorders

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicBorders

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicBorders

public class BasicBorders
extends Object

Factory object that can vend Borders appropriate for the basic L & F.

Nested Class Summary
static class | BasicBorders.ButtonBorder
static class | BasicBorders.FieldBorder
static class | BasicBorders.MarginBorder
static class | BasicBorders.MenuBarBorder
static class | BasicBorders.RadioButtonBorder
static class | BasicBorders.RolloverButtonBorder Special thin border for rollover toolbar buttons.
static class | BasicBorders.SplitPaneBorder Draws the border around the splitpane.
static class | BasicBorders.ToggleButtonBorder
Constructor Summary
BasicBorders()
Method Summary
static Border | getButtonBorder()
static Border | getInternalFrameBorder()
static Border | getMenuBarBorder()
static Border | getProgressBarBorder()
static Border | getRadioButtonBorder()
static Border | getSplitPaneBorder()
static Border | getSplitPaneDividerBorder() Returns a border instance for a JSplitPane divider
static Border | getTextFieldBorder()
static Border | getToggleButtonBorder()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicBorders

public BasicBorders()
Method Detail

getButtonBorder

public static Border getButtonBorder()

getRadioButtonBorder

public static Border getRadioButtonBorder()

getToggleButtonBorder

public static Border getToggleButtonBorder()

getMenuBarBorder

public static Border getMenuBarBorder()

getSplitPaneBorder

public static Border getSplitPaneBorder()

getSplitPaneDividerBorder

public static Border getSplitPaneDividerBorder()
Returns a border instance for a JSplitPane divider

Since:
1.3

getTextFieldBorder

public static Border getTextFieldBorder()

getProgressBarBorder

public static Border getProgressBarBorder()

getInternalFrameBorder

public static Border getInternalFrameBorder()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicBorders.ButtonBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicBorders.ButtonBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.basic.BasicBorders.ButtonBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Direct Known Subclasses:
BasicBorders.RadioButtonBorder, BasicBorders.RolloverButtonBorder, BasicBorders.ToggleButtonBorder
Enclosing class:
BasicBorders
public static class BasicBorders.ButtonBorder
extends AbstractBorder
implements UIResource

Field Summary
protected Color | darkShadow
protected Color | highlight
protected Color | lightHighlight
protected Color | shadow
Constructor Summary
BasicBorders.ButtonBorder(Color shadow, Color darkShadow, Color highlight, Color lightHighlight)
Method Summary
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
Insets | getBorderInsets(Component c, Insets insets) Reinitializes the insets parameter with this Border's current Insets.
void | paintBorder(Component c, Graphics g, int x, int y, int width, int height) This default implementation does no painting.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

shadow

protected Color shadow

darkShadow

protected Color darkShadow

highlight

protected Color highlight

lightHighlight

protected Color lightHighlight
Constructor Detail

BasicBorders.ButtonBorder

public BasicBorders.ButtonBorder(Color shadow,
                                 Color darkShadow,
                                 Color highlight,
                                 Color lightHighlight)
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int width,
                        int height)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
width - the width of the painted border
height - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from class: AbstractBorder
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets insets)
Description copied from class: AbstractBorder
Reinitializes the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
insets - the object to be reinitialized
Returns:
the insets object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicBorders.FieldBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicBorders.FieldBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.basic.BasicBorders.FieldBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
BasicBorders
public static class BasicBorders.FieldBorder
extends AbstractBorder
implements UIResource

Field Summary
protected Color | darkShadow
protected Color | highlight
protected Color | lightHighlight
protected Color | shadow
Constructor Summary
BasicBorders.FieldBorder(Color shadow, Color darkShadow, Color highlight, Color lightHighlight)
Method Summary
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
Insets | getBorderInsets(Component c, Insets insets) Reinitializes the insets parameter with this Border's current Insets.
void | paintBorder(Component c, Graphics g, int x, int y, int width, int height) This default implementation does no painting.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

shadow

protected Color shadow

darkShadow

protected Color darkShadow

highlight

protected Color highlight

lightHighlight

protected Color lightHighlight
Constructor Detail

BasicBorders.FieldBorder

public BasicBorders.FieldBorder(Color shadow,
                                Color darkShadow,
                                Color highlight,
                                Color lightHighlight)
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int width,
                        int height)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
width - the width of the painted border
height - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from class: AbstractBorder
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets insets)
Description copied from class: AbstractBorder
Reinitializes the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
insets - the object to be reinitialized
Returns:
the insets object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicBorders.MarginBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicBorders.MarginBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.basic.BasicBorders.MarginBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
BasicBorders
public static class BasicBorders.MarginBorder
extends AbstractBorder
implements UIResource

Constructor Summary
BasicBorders.MarginBorder()
Method Summary
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
Insets | getBorderInsets(Component c, Insets insets) Reinitializes the insets parameter with this Border's current Insets.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque, paintBorder
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicBorders.MarginBorder

public BasicBorders.MarginBorder()
Method Detail

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from class: AbstractBorder
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets insets)
Description copied from class: AbstractBorder
Reinitializes the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
insets - the object to be reinitialized
Returns:
the insets object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicBorders.MenuBarBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicBorders.MenuBarBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.basic.BasicBorders.MenuBarBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
BasicBorders
public static class BasicBorders.MenuBarBorder
extends AbstractBorder
implements UIResource

Constructor Summary
BasicBorders.MenuBarBorder(Color shadow, Color highlight)
Method Summary
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
Insets | getBorderInsets(Component c, Insets insets) Reinitializes the insets parameter with this Border's current Insets.
void | paintBorder(Component c, Graphics g, int x, int y, int width, int height) This default implementation does no painting.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicBorders.MenuBarBorder

public BasicBorders.MenuBarBorder(Color shadow,
                                  Color highlight)
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int width,
                        int height)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
width - the width of the painted border
height - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from class: AbstractBorder
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets insets)
Description copied from class: AbstractBorder
Reinitializes the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
insets - the object to be reinitialized
Returns:
the insets object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicBorders.RadioButtonBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicBorders.RadioButtonBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.basic.BasicBorders.ButtonBorder
            extended by  javax.swing.plaf.basic.BasicBorders.RadioButtonBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
BasicBorders
public static class BasicBorders.RadioButtonBorder
extends BasicBorders.ButtonBorder

Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicBorders.ButtonBorder
darkShadow, highlight, lightHighlight, shadow
Constructor Summary
BasicBorders.RadioButtonBorder(Color shadow, Color darkShadow, Color highlight, Color lightHighlight)
Method Summary
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
Insets | getBorderInsets(Component c, Insets insets) Reinitializes the insets parameter with this Border's current Insets.
void | paintBorder(Component c, Graphics g, int x, int y, int width, int height) This default implementation does no painting.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicBorders.RadioButtonBorder

public BasicBorders.RadioButtonBorder(Color shadow,
                                      Color darkShadow,
                                      Color highlight,
                                      Color lightHighlight)
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int width,
                        int height)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class BasicBorders.ButtonBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
width - the width of the painted border
height - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from class: AbstractBorder
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class BasicBorders.ButtonBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets insets)
Description copied from class: AbstractBorder
Reinitializes the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class BasicBorders.ButtonBorder
Parameters:
c - the component for which this border insets value applies
insets - the object to be reinitialized
Returns:
the insets object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicBorders.RolloverButtonBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicBorders.RolloverButtonBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.basic.BasicBorders.ButtonBorder
            extended by  javax.swing.plaf.basic.BasicBorders.RolloverButtonBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
BasicBorders
public static class BasicBorders.RolloverButtonBorder
extends BasicBorders.ButtonBorder

Special thin border for rollover toolbar buttons.

Since:
1.4

Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicBorders.ButtonBorder
darkShadow, highlight, lightHighlight, shadow
Constructor Summary
BasicBorders.RolloverButtonBorder(Color shadow, Color darkShadow, Color highlight, Color lightHighlight)
Method Summary
 void paintBorder(Component c, Graphics g, int x, int y, int w, int h)
This default implementation does no painting.
Methods inherited from class javax.swing.plaf.basic.BasicBorders.ButtonBorder
getBorderInsets, getBorderInsets
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicBorders.RolloverButtonBorder

public BasicBorders.RolloverButtonBorder(Color shadow,
                                         Color darkShadow,
                                         Color highlight,
                                         Color lightHighlight)
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int w,
                        int h)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class BasicBorders.ButtonBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
w - the width of the painted border
h - the height of the painted border
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicBorders.SplitPaneBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicBorders.SplitPaneBorder

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicBorders.SplitPaneBorder
All Implemented Interfaces:
Border, UIResource
Enclosing class:
BasicBorders
public static class BasicBorders.SplitPaneBorder
extends Object
implements Border, UIResource

Draws the border around the splitpane. To work correctly you shoudl also install a border on the divider (property SplitPaneDivider.border).

Field Summary
protected Color | highlight
protected Color | shadow
Constructor Summary
BasicBorders.SplitPaneBorder(Color highlight, Color shadow)
Method Summary
Insets | getBorderInsets(Component c) Returns the insets of the border.
boolean | isBorderOpaque() Returns whether or not the border is opaque.
void | paintBorder(Component c, Graphics g, int x, int y, int width, int height) Paints the border for the specified component with the specified position and size.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

highlight

protected Color highlight

shadow

protected Color shadow
Constructor Detail

BasicBorders.SplitPaneBorder

public BasicBorders.SplitPaneBorder(Color highlight,
                                    Color shadow)
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int width,
                        int height)
Description copied from interface: Border
Paints the border for the specified component with the specified position and size.

Specified by:
paintBorder in interface Border
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
width - the width of the painted border
height - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from interface: Border
Returns the insets of the border.

Specified by:
getBorderInsets in interface Border
Parameters:
c - the component for which this border insets value applies

isBorderOpaque

public boolean isBorderOpaque()
Description copied from interface: Border
Returns whether or not the border is opaque. If the border is opaque, it is responsible for filling in it's own background when painting.

Specified by:
isBorderOpaque in interface Border
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicBorders.ToggleButtonBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicBorders.ToggleButtonBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.basic.BasicBorders.ButtonBorder
            extended by  javax.swing.plaf.basic.BasicBorders.ToggleButtonBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
BasicBorders
public static class BasicBorders.ToggleButtonBorder
extends BasicBorders.ButtonBorder

Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicBorders.ButtonBorder
darkShadow, highlight, lightHighlight, shadow
Constructor Summary
BasicBorders.ToggleButtonBorder(Color shadow, Color darkShadow, Color highlight, Color lightHighlight)
Method Summary
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
Insets | getBorderInsets(Component c, Insets insets) Reinitializes the insets parameter with this Border's current Insets.
void | paintBorder(Component c, Graphics g, int x, int y, int width, int height) This default implementation does no painting.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicBorders.ToggleButtonBorder

public BasicBorders.ToggleButtonBorder(Color shadow,
                                       Color darkShadow,
                                       Color highlight,
                                       Color lightHighlight)
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int width,
                        int height)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class BasicBorders.ButtonBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
width - the width of the painted border
height - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from class: AbstractBorder
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class BasicBorders.ButtonBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets insets)
Description copied from class: AbstractBorder
Reinitializes the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class BasicBorders.ButtonBorder
Parameters:
c - the component for which this border insets value applies
insets - the object to be reinitialized
Returns:
the insets object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicButtonListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicButtonListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicButtonListener
All Implemented Interfaces:
FocusListener, MouseListener, MouseMotionListener, PropertyChangeListener, EventListener, ChangeListener
public class BasicButtonListener
extends Object
implements MouseListener, MouseMotionListener, FocusListener, ChangeListener, PropertyChangeListener

Button Listener

Constructor Summary
BasicButtonListener(AbstractButton b)
Method Summary
protected void | checkOpacity(AbstractButton b)
void | focusGained(FocusEvent e) Invoked when a component gains the keyboard focus.
void | focusLost(FocusEvent e) Invoked when a component loses the keyboard focus.
void | installKeyboardActions(JComponent c) Register default key actions: pressing space to "click" a button and registring the keyboard mnemonic (if any).
void | mouseClicked(MouseEvent e) Invoked when the mouse button has been clicked (pressed and released) on a component.
void | mouseDragged(MouseEvent e) Invoked when a mouse button is pressed on a component and then dragged.
void | mouseEntered(MouseEvent e) Invoked when the mouse enters a component.
void | mouseExited(MouseEvent e) Invoked when the mouse exits a component.
void | mouseMoved(MouseEvent e) Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.
void | mousePressed(MouseEvent e) Invoked when a mouse button has been pressed on a component.
void | mouseReleased(MouseEvent e) Invoked when a mouse button has been released on a component.
void | propertyChange(PropertyChangeEvent e) This method gets called when a bound property is changed.
void | stateChanged(ChangeEvent e) Invoked when the target of the listener has changed its state.
void | uninstallKeyboardActions(JComponent c) Unregister's default key actions
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicButtonListener

public BasicButtonListener(AbstractButton b)
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.

checkOpacity

protected void checkOpacity(AbstractButton b)

installKeyboardActions

public void installKeyboardActions(JComponent c)
Register default key actions: pressing space to "click" a button and registring the keyboard mnemonic (if any).

uninstallKeyboardActions

public void uninstallKeyboardActions(JComponent c)
Unregister's default key actions

stateChanged

public void stateChanged(ChangeEvent e)
Description copied from interface: ChangeListener
Invoked when the target of the listener has changed its state.

Specified by:
stateChanged in interface ChangeListener
Parameters:
e - a ChangeEvent object

focusGained

public void focusGained(FocusEvent e)
Description copied from interface: FocusListener
Invoked when a component gains the keyboard focus.

Specified by:
focusGained in interface FocusListener

focusLost

public void focusLost(FocusEvent e)
Description copied from interface: FocusListener
Invoked when a component loses the keyboard focus.

Specified by:
focusLost in interface FocusListener

mouseMoved

public void mouseMoved(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.

Specified by:
mouseMoved in interface MouseMotionListener

mouseDragged

public void mouseDragged(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when a mouse button is pressed on a component and then dragged. MOUSE_DRAGGED events will continue to be delivered to the component where the drag originated until the mouse button is released (regardless of whether the mouse position is within the bounds of the component).

Due to platform-dependent Drag&Drop implementations, MOUSE_DRAGGED events may not be delivered during a native Drag&Drop operation.

Specified by:
mouseDragged in interface MouseMotionListener

mouseClicked

public void mouseClicked(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse button has been clicked (pressed and released) on a component.

Specified by:
mouseClicked in interface MouseListener

mousePressed

public void mousePressed(MouseEvent e)
Description copied from interface: MouseListener
Invoked when a mouse button has been pressed on a component.

Specified by:
mousePressed in interface MouseListener

mouseReleased

public void mouseReleased(MouseEvent e)
Description copied from interface: MouseListener
Invoked when a mouse button has been released on a component.

Specified by:
mouseReleased in interface MouseListener

mouseEntered

public void mouseEntered(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse enters a component.

Specified by:
mouseEntered in interface MouseListener

mouseExited

public void mouseExited(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse exits a component.

Specified by:
mouseExited in interface MouseListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicButtonUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicButtonUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ButtonUI
            extended by  javax.swing.plaf.basic.BasicButtonUI
Direct Known Subclasses:
BasicToggleButtonUI, MetalButtonUI
public class BasicButtonUI
extends ButtonUI

BasicButton implementation

Field Summary
protected int | defaultTextIconGap
protected int | defaultTextShiftOffset
Constructor Summary
BasicButtonUI()
Method Summary
protected void | clearTextShiftOffset()
protected BasicButtonListener | createButtonListener(AbstractButton b)
static ComponentUI | createUI(JComponent c)
int | getBaseline(JComponent c, int width, int height) Returns the baseline.
Component.BaselineResizeBehavior | getBaselineResizeBehavior(JComponent c) Returns an enum indicating how the baseline of the component changes as the size changes.
int | getDefaultTextIconGap(AbstractButton b)
Dimension | getMaximumSize(JComponent c) Returns the specified component's maximum size appropriate for the look and feel.
Dimension | getMinimumSize(JComponent c) Returns the specified component's minimum size appropriate for the look and feel.
Dimension | getPreferredSize(JComponent c) Returns the specified component's preferred size appropriate for the look and feel.
protected String | getPropertyPrefix()
protected int | getTextShiftOffset()
protected void | installDefaults(AbstractButton b)
protected void | installKeyboardActions(AbstractButton b)
protected void | installListeners(AbstractButton b)
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
protected void | paintButtonPressed(Graphics g, AbstractButton b)
protected void | paintFocus(Graphics g, AbstractButton b, Rectangle viewRect, Rectangle textRect, Rectangle iconRect)
protected void | paintIcon(Graphics g, JComponent c, Rectangle iconRect)
protected void | paintText(Graphics g, AbstractButton b, Rectangle textRect, String text) Method which renders the text of the current button.
protected void | paintText(Graphics g, JComponent c, Rectangle textRect, String text) As of Java 2 platform v 1.4 this method should not be used or overriden.
protected void | setTextShiftOffset()
protected void | uninstallDefaults(AbstractButton b)
protected void | uninstallKeyboardActions(AbstractButton b)
protected void | uninstallListeners(AbstractButton b)
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

defaultTextIconGap

protected int defaultTextIconGap

defaultTextShiftOffset

protected int defaultTextShiftOffset
Constructor Detail

BasicButtonUI

public BasicButtonUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

getPropertyPrefix

protected String getPropertyPrefix()

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

installDefaults

protected void installDefaults(AbstractButton b)

installListeners

protected void installListeners(AbstractButton b)

installKeyboardActions

protected void installKeyboardActions(AbstractButton b)

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

uninstallKeyboardActions

protected void uninstallKeyboardActions(AbstractButton b)

uninstallListeners

protected void uninstallListeners(AbstractButton b)

uninstallDefaults

protected void uninstallDefaults(AbstractButton b)

createButtonListener

protected BasicButtonListener createButtonListener(AbstractButton b)

getDefaultTextIconGap

public int getDefaultTextIconGap(AbstractButton b)

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

paintIcon

protected void paintIcon(Graphics g,
                         JComponent c,
                         Rectangle iconRect)

paintText

protected void paintText(Graphics g,
                         JComponent c,
                         Rectangle textRect,
                         String text)
As of Java 2 platform v 1.4 this method should not be used or overriden. Use the paintText method which takes the AbstractButton argument.

paintText

protected void paintText(Graphics g,
                         AbstractButton b,
                         Rectangle textRect,
                         String text)
Method which renders the text of the current button.

Parameters:
g - Graphics context
b - Current button to render
textRect - Bounding rectangle to render the text.
text - String to render
Since:
1.4

paintFocus

protected void paintFocus(Graphics g,
                          AbstractButton b,
                          Rectangle viewRect,
                          Rectangle textRect,
                          Rectangle iconRect)

paintButtonPressed

protected void paintButtonPressed(Graphics g,
                                  AbstractButton b)

clearTextShiftOffset

protected void clearTextShiftOffset()

setTextShiftOffset

protected void setTextShiftOffset()

getTextShiftOffset

protected int getTextShiftOffset()

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's minimum size appropriate for the look and feel. If null is returned, the minimum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's maximum size appropriate for the look and feel. If null is returned, the maximum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getBaseline

public int getBaseline(JComponent c,
                       int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class ComponentUI
Parameters:
c - JComponent baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
NullPointerException - if c is null
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.

Overrides:
getBaselineResizeBehavior in class ComponentUI
Parameters:
c - JComponent to return baseline resize behavior for
Returns:
an enum indicating how the baseline changes as the component size changes
Throws:
NullPointerException - if c is null
Since:
1.6
See Also:
JComponent.getBaseline(int, int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicCheckBoxMenuItemUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicCheckBoxMenuItemUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ButtonUI
            extended by  javax.swing.plaf.MenuItemUI
                extended by  javax.swing.plaf.basic.BasicMenuItemUI
                    extended by  javax.swing.plaf.basic.BasicCheckBoxMenuItemUI

public class BasicCheckBoxMenuItemUI
extends BasicMenuItemUI

BasicCheckboxMenuItem implementation

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicMenuItemUI
BasicMenuItemUI.MouseInputHandler
Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicMenuItemUI
acceleratorFont, acceleratorForeground, acceleratorSelectionForeground, arrowIcon, checkIcon, defaultTextIconGap, disabledForeground, menuDragMouseListener, menuItem, menuKeyListener, mouseInputListener, oldBorderPainted, propertyChangeListener, selectionBackground, selectionForeground
Constructor Summary
BasicCheckBoxMenuItemUI()
Method Summary
static ComponentUI | createUI(JComponent c)
protected String | getPropertyPrefix()
void | processMouseEvent(JMenuItem item, MouseEvent e, MenuElement[] path, MenuSelectionManager manager)
Methods inherited from class javax.swing.plaf.basic.BasicMenuItemUI
createMenuDragMouseListener, createMenuKeyListener, createMouseInputListener, createPropertyChangeListener, doClick, getMaximumSize, getMinimumSize, getPath, getPreferredMenuItemSize, getPreferredSize, installComponents, installDefaults, installKeyboardActions, installListeners, installUI, paint, paintBackground, paintMenuItem, paintText, uninstallComponents, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, uninstallUI, update
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicCheckBoxMenuItemUI

public BasicCheckBoxMenuItemUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

getPropertyPrefix

protected String getPropertyPrefix()
Overrides:
getPropertyPrefix in class BasicMenuItemUI

processMouseEvent

public void processMouseEvent(JMenuItem item,
                              MouseEvent e,
                              MenuElement[] path,
                              MenuSelectionManager manager)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicCheckBoxUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicCheckBoxUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ButtonUI
            extended by  javax.swing.plaf.basic.BasicButtonUI
                extended by  javax.swing.plaf.basic.BasicToggleButtonUI
                    extended by  javax.swing.plaf.basic.BasicRadioButtonUI
                        extended by  javax.swing.plaf.basic.BasicCheckBoxUI

public class BasicCheckBoxUI
extends BasicRadioButtonUI

CheckboxUI implementation for BasicCheckboxUI

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicRadioButtonUI
icon
Fields inherited from class javax.swing.plaf.basic.BasicButtonUI
defaultTextIconGap, defaultTextShiftOffset
Constructor Summary
BasicCheckBoxUI()
Method Summary
static ComponentUI | createUI(JComponent b)
String | getPropertyPrefix()
Methods inherited from class javax.swing.plaf.basic.BasicRadioButtonUI
getDefaultIcon, getPreferredSize, installDefaults, paint, paintFocus, uninstallDefaults
Methods inherited from class javax.swing.plaf.basic.BasicToggleButtonUI
getTextShiftOffset, paintIcon
Methods inherited from class javax.swing.plaf.basic.BasicButtonUI
clearTextShiftOffset, createButtonListener, getBaseline, getBaselineResizeBehavior, getDefaultTextIconGap, getMaximumSize, getMinimumSize, installKeyboardActions, installListeners, installUI, paintButtonPressed, paintFocus, paintIcon, paintText, paintText, setTextShiftOffset, uninstallKeyboardActions, uninstallListeners, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicCheckBoxUI

public BasicCheckBoxUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent b)

getPropertyPrefix

public String getPropertyPrefix()
Overrides:
getPropertyPrefix in class BasicRadioButtonUI
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicColorChooserUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicColorChooserUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ColorChooserUI
            extended by  javax.swing.plaf.basic.BasicColorChooserUI

public class BasicColorChooserUI
extends ColorChooserUI

Provides the basic look and feel for a JColorChooser.

Nested Class Summary
 class BasicColorChooserUI.PropertyHandler
This inner class is marked "public" due to a compiler bug.
Field Summary
protected JColorChooser | chooser JColorChooser this BasicColorChooserUI is installed on.
protected AbstractColorChooserPanel[] | defaultChoosers
protected ChangeListener | previewListener
protected PropertyChangeListener | propertyChangeListener
Constructor Summary
BasicColorChooserUI()
Method Summary
protected AbstractColorChooserPanel[] | createDefaultChoosers()
protected PropertyChangeListener | createPropertyChangeListener()
static ComponentUI | createUI(JComponent c)
protected void | installDefaults()
protected void | installListeners()
protected void | installPreviewPanel()
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
protected void | uninstallDefaultChoosers()
protected void | uninstallDefaults()
protected void | uninstallListeners()
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, paint, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

chooser

protected JColorChooser chooser
JColorChooser this BasicColorChooserUI is installed on.

Since:
1.5

defaultChoosers

protected AbstractColorChooserPanel[] defaultChoosers

previewListener

protected ChangeListener previewListener

propertyChangeListener

protected PropertyChangeListener propertyChangeListener
Constructor Detail

BasicColorChooserUI

public BasicColorChooserUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

createDefaultChoosers

protected AbstractColorChooserPanel[] createDefaultChoosers()

uninstallDefaultChoosers

protected void uninstallDefaultChoosers()

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installPreviewPanel

protected void installPreviewPanel()

installDefaults

protected void installDefaults()

uninstallDefaults

protected void uninstallDefaults()

installListeners

protected void installListeners()

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener()

uninstallListeners

protected void uninstallListeners()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicColorChooserUI.PropertyHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicColorChooserUI.PropertyHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicColorChooserUI.PropertyHandler
All Implemented Interfaces:
PropertyChangeListener, EventListener
Enclosing class:
BasicColorChooserUI
public class BasicColorChooserUI.PropertyHandler
extends Object
implements PropertyChangeListener

This inner class is marked "public" due to a compiler bug. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Constructor Summary
BasicColorChooserUI.PropertyHandler()
Method Summary
 void propertyChange(PropertyChangeEvent e)
This method gets called when a bound property is changed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicColorChooserUI.PropertyHandler

public BasicColorChooserUI.PropertyHandler()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboBoxEditor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboBoxEditor

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicComboBoxEditor
All Implemented Interfaces:
FocusListener, EventListener, ComboBoxEditor
Direct Known Subclasses:
BasicComboBoxEditor.UIResource, MetalComboBoxEditor
public class BasicComboBoxEditor
extends Object
implements ComboBoxEditor, FocusListener

The default editor for editable combo boxes. The editor is implemented as a JTextField.

Nested Class Summary
static class BasicComboBoxEditor.UIResource
A subclass of BasicComboBoxEditor that implements UIResource.
Field Summary
protected  JTextField editor
Constructor Summary
BasicComboBoxEditor()
Method Summary
void | addActionListener(ActionListener l) Add an ActionListener.
protected JTextField | createEditorComponent() Creates the internal editor component.
void | focusGained(FocusEvent e) Invoked when a component gains the keyboard focus.
void | focusLost(FocusEvent e) Invoked when a component loses the keyboard focus.
Component | getEditorComponent() Return the component that should be added to the tree hierarchy for this editor
Object | getItem() Return the edited item
void | removeActionListener(ActionListener l) Remove an ActionListener
void | selectAll() Ask the editor to start editing and to select everything
void | setItem(Object anObject) Sets the item that should be edited.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

editor

protected JTextField editor
Constructor Detail

BasicComboBoxEditor

public BasicComboBoxEditor()
Method Detail

getEditorComponent

public Component getEditorComponent()
Description copied from interface: ComboBoxEditor
Return the component that should be added to the tree hierarchy for this editor

Specified by:
getEditorComponent in interface ComboBoxEditor

createEditorComponent

protected JTextField createEditorComponent()
Creates the internal editor component. Override this to provide a custom implementation.

Returns:
a new editor component
Since:
1.6

setItem

public void setItem(Object anObject)
Sets the item that should be edited.

Specified by:
setItem in interface ComboBoxEditor
Parameters:
anObject - the displayed value of the editor

getItem

public Object getItem()
Description copied from interface: ComboBoxEditor
Return the edited item

Specified by:
getItem in interface ComboBoxEditor

selectAll

public void selectAll()
Description copied from interface: ComboBoxEditor
Ask the editor to start editing and to select everything

Specified by:
selectAll in interface ComboBoxEditor

focusGained

public void focusGained(FocusEvent e)
Description copied from interface: FocusListener
Invoked when a component gains the keyboard focus.

Specified by:
focusGained in interface FocusListener

focusLost

public void focusLost(FocusEvent e)
Description copied from interface: FocusListener
Invoked when a component loses the keyboard focus.

Specified by:
focusLost in interface FocusListener

addActionListener

public void addActionListener(ActionListener l)
Description copied from interface: ComboBoxEditor
Add an ActionListener. An action event is generated when the edited item changes

Specified by:
addActionListener in interface ComboBoxEditor

removeActionListener

public void removeActionListener(ActionListener l)
Description copied from interface: ComboBoxEditor
Remove an ActionListener

Specified by:
removeActionListener in interface ComboBoxEditor
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboBoxEditor.UIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboBoxEditor.UIResource

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicComboBoxEditor
        extended by  javax.swing.plaf.basic.BasicComboBoxEditor.UIResource
All Implemented Interfaces:
FocusListener, EventListener, ComboBoxEditor, UIResource
Enclosing class:
BasicComboBoxEditor
public static class BasicComboBoxEditor.UIResource
extends BasicComboBoxEditor
implements UIResource

A subclass of BasicComboBoxEditor that implements UIResource. BasicComboBoxEditor doesn't implement UIResource directly so that applications can safely override the cellRenderer property with BasicListCellRenderer subclasses.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicComboBoxEditor
BasicComboBoxEditor.UIResource
Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicComboBoxEditor
editor
Constructor Summary
BasicComboBoxEditor.UIResource()
Method Summary
Methods inherited from class javax.swing.plaf.basic.BasicComboBoxEditor
addActionListener, createEditorComponent, focusGained, focusLost, getEditorComponent, getItem, removeActionListener, selectAll, setItem
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicComboBoxEditor.UIResource

public BasicComboBoxEditor.UIResource()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboBoxRenderer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboBoxRenderer

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JLabel
                    extended by  javax.swing.plaf.basic.BasicComboBoxRenderer
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, ListCellRenderer, SwingConstants
Direct Known Subclasses:
BasicComboBoxRenderer.UIResource
public class BasicComboBoxRenderer
extends JLabel
implements ListCellRenderer, Serializable

ComboBox renderer

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
static class BasicComboBoxRenderer.UIResource
A subclass of BasicComboBoxRenderer that implements UIResource.
Nested classes/interfaces inherited from class javax.swing.JLabel
JLabel.AccessibleJLabel
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected static Border noFocusBorder
An empty Border.
Fields inherited from class javax.swing.JLabel
labelFor
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
BasicComboBoxRenderer()
Method Summary
Component | getListCellRendererComponent(JList list, Object value, int index, boolean isSelected, boolean cellHasFocus) Return a component that has been configured to display the specified value.
Dimension | getPreferredSize() If the preferredSize has been set to a non-null value just returns it.
Methods inherited from class javax.swing.JLabel
checkHorizontalKey, checkVerticalKey, getAccessibleContext, getDisabledIcon, getDisplayedMnemonic, getDisplayedMnemonicIndex, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getLabelFor, getText, getUI, getUIClassID, getVerticalAlignment, getVerticalTextPosition, imageUpdate, paramString, setDisabledIcon, setDisplayedMnemonic, setDisplayedMnemonic, setDisplayedMnemonicIndex, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabelFor, setText, setUI, setVerticalAlignment, setVerticalTextPosition, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

noFocusBorder

protected static Border noFocusBorder
An empty Border. This field might not be used. To change the Border used by this renderer directly set it using the setBorder method.

Constructor Detail

BasicComboBoxRenderer

public BasicComboBoxRenderer()
Method Detail

getPreferredSize

public Dimension getPreferredSize()
Description copied from class: JComponent
If the preferredSize has been set to a non-null value just returns it. If the UI delegate's getPreferredSize method returns a non null value then return that; otherwise defer to the component's layout manager.

Overrides:
getPreferredSize in class JComponent
Returns:
the value of the preferredSize property
See Also:
JComponent.setPreferredSize(java.awt.Dimension), ComponentUI

getListCellRendererComponent

public Component getListCellRendererComponent(JList list,
                                              Object value,
                                              int index,
                                              boolean isSelected,
                                              boolean cellHasFocus)
Description copied from interface: ListCellRenderer
Return a component that has been configured to display the specified value. That component's paint method is then called to "render" the cell. If it is necessary to compute the dimensions of a list because the list cells do not have a fixed size, this method is called to generate a component on which getPreferredSize can be invoked.

Specified by:
getListCellRendererComponent in interface ListCellRenderer
Parameters:
list - The JList we're painting.
value - The value returned by list.getModel().getElementAt(index).
index - The cells index.
isSelected - True if the specified cell was selected.
cellHasFocus - True if the specified cell has the focus.
Returns:
A component whose paint() method will render the specified value.
See Also:
JList, ListSelectionModel, ListModel
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboBoxRenderer.UIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboBoxRenderer.UIResource

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JLabel
                    extended by  javax.swing.plaf.basic.BasicComboBoxRenderer
                        extended by  javax.swing.plaf.basic.BasicComboBoxRenderer.UIResource
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, ListCellRenderer, UIResource, SwingConstants
Enclosing class:
BasicComboBoxRenderer
public static class BasicComboBoxRenderer.UIResource
extends BasicComboBoxRenderer
implements UIResource

A subclass of BasicComboBoxRenderer that implements UIResource. BasicComboBoxRenderer doesn't implement UIResource directly so that applications can safely override the cellRenderer property with BasicListCellRenderer subclasses.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicComboBoxRenderer
BasicComboBoxRenderer.UIResource
Nested classes/interfaces inherited from class javax.swing.JLabel
JLabel.AccessibleJLabel
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicComboBoxRenderer
noFocusBorder
Fields inherited from class javax.swing.JLabel
labelFor
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
BasicComboBoxRenderer.UIResource()
Method Summary
Methods inherited from class javax.swing.plaf.basic.BasicComboBoxRenderer
getListCellRendererComponent, getPreferredSize
Methods inherited from class javax.swing.JLabel
checkHorizontalKey, checkVerticalKey, getAccessibleContext, getDisabledIcon, getDisplayedMnemonic, getDisplayedMnemonicIndex, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getLabelFor, getText, getUI, getUIClassID, getVerticalAlignment, getVerticalTextPosition, imageUpdate, paramString, setDisabledIcon, setDisplayedMnemonic, setDisplayedMnemonic, setDisplayedMnemonicIndex, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabelFor, setText, setUI, setVerticalAlignment, setVerticalTextPosition, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

BasicComboBoxRenderer.UIResource

public BasicComboBoxRenderer.UIResource()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboBoxUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboBoxUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ComboBoxUI
            extended by  javax.swing.plaf.basic.BasicComboBoxUI
Direct Known Subclasses:
MetalComboBoxUI
public class BasicComboBoxUI
extends ComboBoxUI

Basic UI implementation for JComboBox.

The combo box is a compound component which means that it is an agregate of many simpler components. This class creates and manages the listeners on the combo box and the combo box model. These listeners update the user interface in response to changes in the properties and state of the combo box.

All event handling is handled by listener classes created with the createxxxListener() methods and internal classes. You can change the behavior of this class by overriding the createxxxListener() methods and supplying your own event listeners or subclassing from the ones supplied in this class.

For adding specific actions, overide installKeyboardActions to add actions in response to KeyStroke bindings. See the article Keyboard Bindings in Swing at The Swing Connection.

Nested Class Summary
class | BasicComboBoxUI.ComboBoxLayoutManager This layout manager handles the 'standard' layout of combo boxes.
class | BasicComboBoxUI.FocusHandler This listener hides the popup when the focus is lost.
class | BasicComboBoxUI.ItemHandler This listener watches for changes to the selection in the combo box.
class | BasicComboBoxUI.KeyHandler This listener checks to see if the key event isn't a navigation key.
class | BasicComboBoxUI.ListDataHandler This listener watches for changes in the ComboBoxModel.
class | BasicComboBoxUI.PropertyChangeHandler This listener watches for bound properties that have changed in the combo box.
Field Summary
protected JButton | arrowButton
protected Dimension | cachedMinimumSize
protected JComboBox | comboBox
protected CellRendererPane | currentValuePane
protected Component | editor
protected FocusListener | focusListener This protected field is implementation specific.
protected boolean | hasFocus This protected field is implementation specific.
protected boolean | isMinimumSizeDirty
protected ItemListener | itemListener This protected field is implementation specific.
protected KeyListener | keyListener This protected field is implementation specific.
protected JList | listBox
protected ListDataListener | listDataListener This protected field is implementation specific.
protected ComboPopup | popup
protected KeyListener | popupKeyListener
protected MouseListener | popupMouseListener
protected MouseMotionListener | popupMouseMotionListener
protected PropertyChangeListener | propertyChangeListener This protected field is implementation specific.
Constructor Summary
BasicComboBoxUI()
Method Summary
void | addEditor() This public method is implementation specific and should be private.
void | configureArrowButton() This public method is implementation specific and should be private.
protected void | configureEditor() This protected method is implementation specific and should be private.
protected JButton | createArrowButton() Creates an button which will be used as the control to show or hide the popup portion of the combo box.
protected ComboBoxEditor | createEditor() Creates the default editor that will be used in editable combo boxes.
protected FocusListener | createFocusListener() Creates a FocusListener which will be added to the combo box.
protected ItemListener | createItemListener() Creates an ItemListener which will be added to the combo box.
protected KeyListener | createKeyListener() Creates a KeyListener which will be added to the combo box.
protected LayoutManager | createLayoutManager() Creates a layout manager for managing the components which make up the combo box.
protected ListDataListener | createListDataListener() Creates a list data listener which will be added to the ComboBoxModel.
protected ComboPopup | createPopup() Creates the popup portion of the combo box.
protected PropertyChangeListener | createPropertyChangeListener() Creates a PropertyChangeListener which will be added to the combo box.
protected ListCellRenderer | createRenderer() Creates the default renderer that will be used in a non-editiable combo box.
static ComponentUI | createUI(JComponent c)
Accessible | getAccessibleChild(JComponent c, int i) Returns the ith Accessible child of the object.
int | getAccessibleChildrenCount(JComponent c) Returns the number of accessible children in the object.
int | getBaseline(JComponent c, int width, int height) Returns the baseline.
Component.BaselineResizeBehavior | getBaselineResizeBehavior(JComponent c) Returns an enum indicating how the baseline of the component changes as the size changes.
protected Dimension | getDefaultSize() Return the default size of an empty display area of the combo box using the current renderer and font.
protected Dimension | getDisplaySize() Returns the calculated size of the display area.
protected Insets | getInsets() Gets the insets from the JComboBox.
Dimension | getMaximumSize(JComponent c) Returns the specified component's maximum size appropriate for the look and feel.
Dimension | getMinimumSize(JComponent c) The minumum size is the size of the display area plus insets plus the button.
Dimension | getPreferredSize(JComponent c) Returns the specified component's preferred size appropriate for the look and feel.
protected void | installComponents() Creates and initializes the components which make up the aggregate combo box.
protected void | installDefaults() Installs the default colors, default font, default renderer, and default editor into the JComboBox.
protected void | installKeyboardActions() Adds keyboard actions to the JComboBox.
protected void | installListeners() Create and install the listeners for the combo box and its model.
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
boolean | isFocusTraversable(JComboBox c) Determines if the JComboBox is focus traversable.
protected boolean | isNavigationKey(int keyCode) Returns whether or not the supplied keyCode maps to a key that is used for navigation.
boolean | isPopupVisible(JComboBox c) Tells if the popup is visible or not.
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
void | paintCurrentValue(Graphics g, Rectangle bounds, boolean hasFocus) Paints the currently selected item.
void | paintCurrentValueBackground(Graphics g, Rectangle bounds, boolean hasFocus) Paints the background of the currently selected item.
protected Rectangle | rectangleForCurrentValue() Returns the area that is reserved for drawing the currently selected item.
void | removeEditor() This public method is implementation specific and should be private.
protected void | selectNextPossibleValue() Selects the next item in the list.
protected void | selectPreviousPossibleValue() Selects the previous item in the list.
void | setPopupVisible(JComboBox c, boolean v) Hides the popup.
protected void | toggleOpenClose() Hides the popup if it is showing and shows the popup if it is hidden.
void | unconfigureArrowButton() This public method is implementation specific and should be private.
protected void | unconfigureEditor() This protected method is implementation specific and should be private.
protected void | uninstallComponents() The aggregate components which compise the combo box are unregistered and uninitialized.
protected void | uninstallDefaults() Uninstalls the default colors, default font, default renderer, and default editor into the JComboBox.
protected void | uninstallKeyboardActions() Removes the focus InputMap and ActionMap.
protected void | uninstallListeners() Remove the installed listeners from the combo box and its model.
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

comboBox

protected JComboBox comboBox

hasFocus

protected boolean hasFocus
This protected field is implementation specific. Do not access directly or override.

listBox

protected JList listBox

currentValuePane

protected CellRendererPane currentValuePane

popup

protected ComboPopup popup

editor

protected Component editor

arrowButton

protected JButton arrowButton

keyListener

protected KeyListener keyListener
This protected field is implementation specific. Do not access directly or override. Override the listener construction method instead.

See Also:
createKeyListener()

focusListener

protected FocusListener focusListener
This protected field is implementation specific. Do not access directly or override. Override the listener construction method instead.

See Also:
createFocusListener()

propertyChangeListener

protected PropertyChangeListener propertyChangeListener
This protected field is implementation specific. Do not access directly or override. Override the listener construction method instead.

See Also:
createPropertyChangeListener()

itemListener

protected ItemListener itemListener
This protected field is implementation specific. Do not access directly or override. Override the listener construction method instead.

See Also:
createItemListener()

popupMouseListener

protected MouseListener popupMouseListener

popupMouseMotionListener

protected MouseMotionListener popupMouseMotionListener

popupKeyListener

protected KeyListener popupKeyListener

listDataListener

protected ListDataListener listDataListener
This protected field is implementation specific. Do not access directly or override. Override the listener construction method instead.

See Also:
createListDataListener()

isMinimumSizeDirty

protected boolean isMinimumSizeDirty

cachedMinimumSize

protected Dimension cachedMinimumSize
Constructor Detail

BasicComboBoxUI

public BasicComboBoxUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installDefaults

protected void installDefaults()
Installs the default colors, default font, default renderer, and default editor into the JComboBox.

installListeners

protected void installListeners()
Create and install the listeners for the combo box and its model. This method is called when the UI is installed.

uninstallDefaults

protected void uninstallDefaults()
Uninstalls the default colors, default font, default renderer, and default editor into the JComboBox.

uninstallListeners

protected void uninstallListeners()
Remove the installed listeners from the combo box and its model. The number and types of listeners removed and in this method should be the same that was added in installListeners

createPopup

protected ComboPopup createPopup()
Creates the popup portion of the combo box.

Returns:
an instance of ComboPopup
See Also:
ComboPopup

createKeyListener

protected KeyListener createKeyListener()
Creates a KeyListener which will be added to the combo box. If this method returns null then it will not be added to the combo box.

Returns:
an instance KeyListener or null

createFocusListener

protected FocusListener createFocusListener()
Creates a FocusListener which will be added to the combo box. If this method returns null then it will not be added to the combo box.

Returns:
an instance of a FocusListener or null

createListDataListener

protected ListDataListener createListDataListener()
Creates a list data listener which will be added to the ComboBoxModel. If this method returns null then it will not be added to the combo box model.

Returns:
an instance of a ListDataListener or null

createItemListener

protected ItemListener createItemListener()
Creates an ItemListener which will be added to the combo box. If this method returns null then it will not be added to the combo box.

Subclasses may override this method to return instances of their own ItemEvent handlers.

Returns:
an instance of an ItemListener or null

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener()
Creates a PropertyChangeListener which will be added to the combo box. If this method returns null then it will not be added to the combo box.

Returns:
an instance of a PropertyChangeListener or null

createLayoutManager

protected LayoutManager createLayoutManager()
Creates a layout manager for managing the components which make up the combo box.

Returns:
an instance of a layout manager

createRenderer

protected ListCellRenderer createRenderer()
Creates the default renderer that will be used in a non-editiable combo box. A default renderer will used only if a renderer has not been explicitly set with setRenderer.

Returns:
a ListCellRender used for the combo box
See Also:
JComboBox.setRenderer(javax.swing.ListCellRenderer)

createEditor

protected ComboBoxEditor createEditor()
Creates the default editor that will be used in editable combo boxes. A default editor will be used only if an editor has not been explicitly set with setEditor.

Returns:
a ComboBoxEditor used for the combo box
See Also:
JComboBox.setEditor(javax.swing.ComboBoxEditor)

installComponents

protected void installComponents()
Creates and initializes the components which make up the aggregate combo box. This method is called as part of the UI installation process.

uninstallComponents

protected void uninstallComponents()
The aggregate components which compise the combo box are unregistered and uninitialized. This method is called as part of the UI uninstallation process.

addEditor

public void addEditor()
This public method is implementation specific and should be private. do not call or override. To implement a specific editor create a custom ComboBoxEditor

See Also:
createEditor(), JComboBox.setEditor(javax.swing.ComboBoxEditor), ComboBoxEditor

removeEditor

public void removeEditor()
This public method is implementation specific and should be private. do not call or override.

See Also:
addEditor()

configureEditor

protected void configureEditor()
This protected method is implementation specific and should be private. do not call or override.

See Also:
addEditor()

unconfigureEditor

protected void unconfigureEditor()
This protected method is implementation specific and should be private. Do not call or override.

See Also:
addEditor()

configureArrowButton

public void configureArrowButton()
This public method is implementation specific and should be private. Do not call or override.

See Also:
createArrowButton()

unconfigureArrowButton

public void unconfigureArrowButton()
This public method is implementation specific and should be private. Do not call or override.

See Also:
createArrowButton()

createArrowButton

protected JButton createArrowButton()
Creates an button which will be used as the control to show or hide the popup portion of the combo box.

Returns:
a button which represents the popup control

isPopupVisible

public boolean isPopupVisible(JComboBox c)
Tells if the popup is visible or not.

Specified by:
isPopupVisible in class ComboBoxUI

setPopupVisible

public void setPopupVisible(JComboBox c,
                            boolean v)
Hides the popup.

Specified by:
setPopupVisible in class ComboBoxUI

isFocusTraversable

public boolean isFocusTraversable(JComboBox c)
Determines if the JComboBox is focus traversable. If the JComboBox is editable this returns false, otherwise it returns true.

Specified by:
isFocusTraversable in class ComboBoxUI

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent c)
The minumum size is the size of the display area plus insets plus the button.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's maximum size appropriate for the look and feel. If null is returned, the maximum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getBaseline

public int getBaseline(JComponent c,
                       int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class ComponentUI
Parameters:
c - JComponent baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
NullPointerException - if c is null
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.

Overrides:
getBaselineResizeBehavior in class ComponentUI
Parameters:
c - JComponent to return baseline resize behavior for
Returns:
an enum indicating how the baseline changes as the component size changes
Throws:
NullPointerException - if c is null
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent c)
Description copied from class: ComponentUI
Returns the number of accessible children in the object. If all of the children of this object implement Accessible, this method should return the number of children of this object. UIs might wish to override this if they present areas on the screen that can be viewed as components, but actual components are not used for presenting those areas. Note: As of v1.3, it is recommended that developers call Component.AccessibleAWTComponent.getAccessibleChildrenCount() instead of this method.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the number of accessible children in the object
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent c,
                                     int i)
Description copied from class: ComponentUI
Returns the ith Accessible child of the object. UIs might need to override this if they present areas on the screen that can be viewed as components, but actual components are not used for presenting those areas.

Note: As of v1.3, it is recommended that developers call Component.AccessibleAWTComponent.getAccessibleChild() instead of this method.

Overrides:
getAccessibleChild in class ComponentUI
i - zero-based index of child
Returns:
the ith Accessible child of the object
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)

isNavigationKey

protected boolean isNavigationKey(int keyCode)
Returns whether or not the supplied keyCode maps to a key that is used for navigation. This is used for optimizing key input by only passing non- navigation keys to the type-ahead mechanism. Subclasses should override this if they change the navigation keys.

selectNextPossibleValue

protected void selectNextPossibleValue()
Selects the next item in the list. It won't change the selection if the currently selected item is already the last item.

selectPreviousPossibleValue

protected void selectPreviousPossibleValue()
Selects the previous item in the list. It won't change the selection if the currently selected item is already the first item.

toggleOpenClose

protected void toggleOpenClose()
Hides the popup if it is showing and shows the popup if it is hidden.

rectangleForCurrentValue

protected Rectangle rectangleForCurrentValue()
Returns the area that is reserved for drawing the currently selected item.

getInsets

protected Insets getInsets()
Gets the insets from the JComboBox.

paintCurrentValue

public void paintCurrentValue(Graphics g,
                              Rectangle bounds,
                              boolean hasFocus)
Paints the currently selected item.

paintCurrentValueBackground

public void paintCurrentValueBackground(Graphics g,
                                        Rectangle bounds,
                                        boolean hasFocus)
Paints the background of the currently selected item.

getDefaultSize

protected Dimension getDefaultSize()
Return the default size of an empty display area of the combo box using the current renderer and font.

Returns:
the size of an empty display area
See Also:
getDisplaySize()

getDisplaySize

protected Dimension getDisplaySize()
Returns the calculated size of the display area. The display area is the portion of the combo box in which the selected item is displayed. This method will use the prototype display value if it has been set.

For combo boxes with a non trivial number of items, it is recommended to use a prototype display value to significantly speed up the display size calculation.

Returns:
the size of the display area calculated from the combo box items
See Also:
JComboBox.setPrototypeDisplayValue(java.lang.Object)

installKeyboardActions

protected void installKeyboardActions()
Adds keyboard actions to the JComboBox. Actions on enter and esc are already supplied. Add more actions as you need them.

uninstallKeyboardActions

protected void uninstallKeyboardActions()
Removes the focus InputMap and ActionMap.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboBoxUI.ComboBoxLayoutManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboBoxUI.ComboBoxLayoutManager

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicComboBoxUI.ComboBoxLayoutManager
All Implemented Interfaces:
LayoutManager
Direct Known Subclasses:
MetalComboBoxUI.MetalComboBoxLayoutManager
Enclosing class:
BasicComboBoxUI
public class BasicComboBoxUI.ComboBoxLayoutManager
extends Object
implements LayoutManager

This layout manager handles the 'standard' layout of combo boxes. It puts the arrow button to the right and the editor to the left. If there is no editor it still keeps the arrow button to the right. This public inner class should be treated as protected. Instantiate it only within subclasses of BasicComboBoxUI.

Constructor Summary
BasicComboBoxUI.ComboBoxLayoutManager()
Method Summary
void | addLayoutComponent(String name, Component comp) If the layout manager uses a per-component string, adds the component comp to the layout, associating it with the string specified by name.
void | layoutContainer(Container parent) Lays out the specified container.
Dimension | minimumLayoutSize(Container parent) Calculates the minimum size dimensions for the specified container, given the components it contains.
Dimension | preferredLayoutSize(Container parent) Calculates the preferred size dimensions for the specified container, given the components it contains.
void | removeLayoutComponent(Component comp) Removes the specified component from the layout.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicComboBoxUI.ComboBoxLayoutManager

public BasicComboBoxUI.ComboBoxLayoutManager()
Method Detail

addLayoutComponent

public void addLayoutComponent(String name,
                               Component comp)
Description copied from interface: LayoutManager
If the layout manager uses a per-component string, adds the component comp to the layout, associating it with the string specified by name.

Specified by:
addLayoutComponent in interface LayoutManager
Parameters:
name - the string to be associated with the component
comp - the component to be added

removeLayoutComponent

public void removeLayoutComponent(Component comp)
Description copied from interface: LayoutManager
Removes the specified component from the layout.

Specified by:
removeLayoutComponent in interface LayoutManager
Parameters:
comp - the component to be removed

preferredLayoutSize

public Dimension preferredLayoutSize(Container parent)
Description copied from interface: LayoutManager
Calculates the preferred size dimensions for the specified container, given the components it contains.

Specified by:
preferredLayoutSize in interface LayoutManager
Parameters:
parent - the container to be laid out
See Also:
LayoutManager.minimumLayoutSize(java.awt.Container)

minimumLayoutSize

public Dimension minimumLayoutSize(Container parent)
Description copied from interface: LayoutManager
Calculates the minimum size dimensions for the specified container, given the components it contains.

Specified by:
minimumLayoutSize in interface LayoutManager
Parameters:
parent - the component to be laid out
See Also:
LayoutManager.preferredLayoutSize(java.awt.Container)

layoutContainer

public void layoutContainer(Container parent)
Description copied from interface: LayoutManager
Lays out the specified container.

Specified by:
layoutContainer in interface LayoutManager
Parameters:
parent - the container to be laid out
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboBoxUI.FocusHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboBoxUI.FocusHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicComboBoxUI.FocusHandler
All Implemented Interfaces:
FocusListener, EventListener
Enclosing class:
BasicComboBoxUI
public class BasicComboBoxUI.FocusHandler
extends Object
implements FocusListener

This listener hides the popup when the focus is lost. It also repaints when focus is gained or lost. This public inner class should be treated as protected. Instantiate it only within subclasses of BasicComboBoxUI.

Constructor Summary
BasicComboBoxUI.FocusHandler()
Method Summary
void | focusGained(FocusEvent e) Invoked when a component gains the keyboard focus.
void | focusLost(FocusEvent e) Invoked when a component loses the keyboard focus.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicComboBoxUI.FocusHandler

public BasicComboBoxUI.FocusHandler()
Method Detail

focusGained

public void focusGained(FocusEvent e)
Description copied from interface: FocusListener
Invoked when a component gains the keyboard focus.

Specified by:
focusGained in interface FocusListener

focusLost

public void focusLost(FocusEvent e)
Description copied from interface: FocusListener
Invoked when a component loses the keyboard focus.

Specified by:
focusLost in interface FocusListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboBoxUI.ItemHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboBoxUI.ItemHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicComboBoxUI.ItemHandler
All Implemented Interfaces:
ItemListener, EventListener
Enclosing class:
BasicComboBoxUI
public class BasicComboBoxUI.ItemHandler
extends Object
implements ItemListener

This listener watches for changes to the selection in the combo box.

This public inner class should be treated as protected. Instantiate it only within subclasses of BasicComboBoxUI.

See Also:
BasicComboBoxUI.createItemListener()

Constructor Summary
BasicComboBoxUI.ItemHandler()
Method Summary
 void itemStateChanged(ItemEvent e)
Invoked when an item has been selected or deselected by the user.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicComboBoxUI.ItemHandler

public BasicComboBoxUI.ItemHandler()
Method Detail

itemStateChanged

public void itemStateChanged(ItemEvent e)
Description copied from interface: ItemListener
Invoked when an item has been selected or deselected by the user. The code written for this method performs the operations that need to occur when an item is selected (or deselected).

Specified by:
itemStateChanged in interface ItemListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboBoxUI.KeyHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboBoxUI.KeyHandler

java.lang.Object
    extended by  java.awt.event.KeyAdapter
        extended by  javax.swing.plaf.basic.BasicComboBoxUI.KeyHandler
All Implemented Interfaces:
KeyListener, EventListener
Enclosing class:
BasicComboBoxUI
public class BasicComboBoxUI.KeyHandler
extends KeyAdapter

This listener checks to see if the key event isn't a navigation key. If it finds a key event that wasn't a navigation key it dispatches it to JComboBox.selectWithKeyChar() so that it can do type-ahead. This public inner class should be treated as protected. Instantiate it only within subclasses of BasicComboBoxUI.

Constructor Summary
BasicComboBoxUI.KeyHandler()
Method Summary
 void keyPressed(KeyEvent e)
Invoked when a key has been pressed.
Methods inherited from class java.awt.event.KeyAdapter
keyReleased, keyTyped
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicComboBoxUI.KeyHandler

public BasicComboBoxUI.KeyHandler()
Method Detail

keyPressed

public void keyPressed(KeyEvent e)
Description copied from class: KeyAdapter
Invoked when a key has been pressed.

Specified by:
keyPressed in interface KeyListener
Overrides:
keyPressed in class KeyAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboBoxUI.ListDataHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboBoxUI.ListDataHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicComboBoxUI.ListDataHandler
All Implemented Interfaces:
EventListener, ListDataListener
Enclosing class:
BasicComboBoxUI
public class BasicComboBoxUI.ListDataHandler
extends Object
implements ListDataListener

This listener watches for changes in the ComboBoxModel.

This public inner class should be treated as protected. Instantiate it only within subclasses of BasicComboBoxUI.

See Also:
BasicComboBoxUI.createListDataListener()

Constructor Summary
BasicComboBoxUI.ListDataHandler()
Method Summary
void | contentsChanged(ListDataEvent e) Sent when the contents of the list has changed in a way that's too complex to characterize with the previous methods.
void | intervalAdded(ListDataEvent e) Sent after the indices in the index0,index1 interval have been inserted in the data model.
void | intervalRemoved(ListDataEvent e) Sent after the indices in the index0,index1 interval have been removed from the data model.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicComboBoxUI.ListDataHandler

public BasicComboBoxUI.ListDataHandler()
Method Detail

contentsChanged

public void contentsChanged(ListDataEvent e)
Description copied from interface: ListDataListener
Sent when the contents of the list has changed in a way that's too complex to characterize with the previous methods. For example, this is sent when an item has been replaced. Index0 and index1 bracket the change.

Specified by:
contentsChanged in interface ListDataListener
Parameters:
e - a ListDataEvent encapsulating the event information

intervalAdded

public void intervalAdded(ListDataEvent e)
Description copied from interface: ListDataListener
Sent after the indices in the index0,index1 interval have been inserted in the data model. The new interval includes both index0 and index1.

Specified by:
intervalAdded in interface ListDataListener
Parameters:
e - a ListDataEvent encapsulating the event information

intervalRemoved

public void intervalRemoved(ListDataEvent e)
Description copied from interface: ListDataListener
Sent after the indices in the index0,index1 interval have been removed from the data model. The interval includes both index0 and index1.

Specified by:
intervalRemoved in interface ListDataListener
Parameters:
e - a ListDataEvent encapsulating the event information
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboBoxUI.PropertyChangeHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboBoxUI.PropertyChangeHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicComboBoxUI.PropertyChangeHandler
All Implemented Interfaces:
PropertyChangeListener, EventListener
Direct Known Subclasses:
MetalComboBoxUI.MetalPropertyChangeListener
Enclosing class:
BasicComboBoxUI
public class BasicComboBoxUI.PropertyChangeHandler
extends Object
implements PropertyChangeListener

This listener watches for bound properties that have changed in the combo box.

Subclasses which wish to listen to combo box property changes should call the superclass methods to ensure that the combo box ui correctly handles property changes.

This public inner class should be treated as protected. Instantiate it only within subclasses of BasicComboBoxUI.

See Also:
BasicComboBoxUI.createPropertyChangeListener()

Constructor Summary
BasicComboBoxUI.PropertyChangeHandler()
Method Summary
 void propertyChange(PropertyChangeEvent e)
This method gets called when a bound property is changed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicComboBoxUI.PropertyChangeHandler

public BasicComboBoxUI.PropertyChangeHandler()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboPopup

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboPopup

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JPopupMenu
                    extended by  javax.swing.plaf.basic.BasicComboPopup
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, MenuElement, ComboPopup
Direct Known Subclasses:
MetalComboBoxUI.MetalComboPopup
public class BasicComboPopup
extends JPopupMenu
implements ComboPopup

This is a basic implementation of the ComboPopup interface. This class represents the ui for the popup portion of the combo box.

All event handling is handled by listener classes created with the createxxxListener() methods and internal classes. You can change the behavior of this class by overriding the createxxxListener() methods and supplying your own event listeners or subclassing from the ones supplied in this class.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
class | BasicComboPopup.InvocationKeyHandler As of Java 2 platform v 1.4, this class is now obsolete and is only included for backwards API compatibility.
protected class | BasicComboPopup.InvocationMouseHandler A listener to be registered upon the combo box (not its popup menu) to handle mouse events that affect the state of the popup menu.
protected class | BasicComboPopup.InvocationMouseMotionHandler This listener watches for dragging and updates the current selection in the list if it is dragging over the list.
protected class | BasicComboPopup.ItemHandler This listener watches for changes to the selection in the combo box.
class | BasicComboPopup.ListDataHandler As of 1.4, this class is now obsolete, doesn't do anything, and is only included for backwards API compatibility.
protected class | BasicComboPopup.ListMouseHandler This listener hides the popup when the mouse is released in the list.
protected class | BasicComboPopup.ListMouseMotionHandler This listener changes the selected item as you move the mouse over the list.
protected class | BasicComboPopup.ListSelectionHandler As of Java 2 platform v 1.4, this class is now obsolete, doesn't do anything, and is only included for backwards API compatibility.
protected class | BasicComboPopup.PropertyChangeHandler This listener watches for bound properties that have changed in the combo box.
Nested classes/interfaces inherited from class javax.swing.JPopupMenu
JPopupMenu.AccessibleJPopupMenu, JPopupMenu.Separator
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected Timer | autoscrollTimer This protected field is implementation specific.
protected JComboBox | comboBox
protected boolean | hasEntered
protected boolean | isAutoScrolling
protected ItemListener | itemListener This protected field is implementation specific.
protected KeyListener | keyListener This protected field is implementation specific.
protected JList | list This protected field is implementation specific.
protected ListDataListener | listDataListener This protected field is implementation specific.
protected MouseListener | listMouseListener This protected field is implementation specific.
protected MouseMotionListener | listMouseMotionListener This protected field is implementation specific.
protected ListSelectionListener | listSelectionListener This protected field is implementation specific.
protected MouseListener | mouseListener This protected field is implementation specific.
protected MouseMotionListener | mouseMotionListener This protected field is implementation specific.
protected PropertyChangeListener | propertyChangeListener This protected field is implementation specific.
protected static int | SCROLL_DOWN
protected static int | SCROLL_UP
protected int | scrollDirection
protected JScrollPane | scroller This protected field is implementation specific.
protected boolean | valueIsAdjusting As of Java 2 platform v1.4 this previously undocumented field is no longer used.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
BasicComboPopup(JComboBox combo)
Method Summary
protected  void autoScrollDown()
This protected method is implementation specific and should be private.
protected  void autoScrollUp()
This protected method is implementation specific and should be private.
protected  Rectangle computePopupBounds(int px, int py, int pw, int ph)
Calculate the placement and size of the popup portion of the combo box based on the combo box location and the enclosing screen bounds.
protected  void configureList()
Configures the list which is used to hold the combo box items in the popup.
protected  void configurePopup()
Configures the popup portion of the combo box.
protected  void configureScroller()
Configures the scrollable portion which holds the list within the combo box popup.
protected  MouseEvent convertMouseEvent(MouseEvent e)
protected  ItemListener createItemListener()
Creates an ItemListener which will be added to the combo box.
protected  KeyListener createKeyListener()
Creates the key listener that will be added to the combo box.
protected  JList createList()
Creates the JList used in the popup to display the items in the combo box model.
protected  ListDataListener createListDataListener()
Creates a list data listener which will be added to the ComboBoxModel.
protected  MouseListener createListMouseListener()
Creates a mouse listener that watches for mouse events in the popup's list.
protected  MouseMotionListener createListMouseMotionListener()
Creates a mouse motion listener that watches for mouse motion events in the popup's list.
protected  ListSelectionListener createListSelectionListener()
Creates a list selection listener that watches for selection changes in the popup's list.
protected  MouseListener createMouseListener()
Creates a listener that will watch for mouse-press and release events on the combo box.
protected  MouseMotionListener createMouseMotionListener()
Creates the mouse motion listener which will be added to the combo box.
protected  PropertyChangeListener createPropertyChangeListener()
Creates a PropertyChangeListener which will be added to the combo box.
protected  JScrollPane createScroller()
Creates the scroll pane which houses the scrollable list.
protected  void delegateFocus(MouseEvent e)
This is is a utility method that helps event handlers figure out where to send the focus when the popup is brought up.
protected  void firePopupMenuCanceled()
Notifies PopupMenuListeners that this popup menu is cancelled.
protected  void firePopupMenuWillBecomeInvisible()
Notifies PopupMenuListeners that this popup menu will become invisible.
protected  void firePopupMenuWillBecomeVisible()
Notifies PopupMenuListeners that this popup menu will become visible.
 AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this BasicComboPopup.
 KeyListener getKeyListener()
Implementation of ComboPopup.getKeyListener().
 JList getList()
Implementation of ComboPopup.getList().
 MouseListener getMouseListener()
Implementation of ComboPopup.getMouseListener().
 MouseMotionListener getMouseMotionListener()
Implementation of ComboPopup.getMouseMotionListener().
protected  int getPopupHeightForRowCount(int maxRowCount)
Retrieves the height of the popup based on the current ListCellRenderer and the maximum row count.
 void hide()
Implementation of ComboPopup.hide().
protected  void installComboBoxListeners()
This method adds the necessary listeners to the JComboBox.
protected  void installComboBoxModelListeners(ComboBoxModel model)
Installs the listeners on the combo box model.
protected  void installKeyboardActions()
protected  void installListListeners()
Adds the listeners to the list control.
 boolean isFocusTraversable()
Overridden to unconditionally return false.
 void show()
Implementation of ComboPopup.show().
protected  void startAutoScrolling(int direction)
This protected method is implementation specific and should be private.
protected  void stopAutoScrolling()
This protected method is implementation specific and should be private.
protected  void togglePopup()
Makes the popup visible if it is hidden and makes it hidden if it is visible.
protected  void uninstallComboBoxModelListeners(ComboBoxModel model)
Removes the listeners from the combo box model
 void uninstallingUI()
Called when the UI is uninstalling.
protected  void uninstallKeyboardActions()
protected  void updateListBoxSelectionForEvent(MouseEvent anEvent, boolean shouldScroll)
A utility method used by the event listeners.
Methods inherited from class javax.swing.JPopupMenu
add, add, add, addMenuKeyListener, addPopupMenuListener, addSeparator, createActionChangeListener, createActionComponent, getComponent, getComponentAtIndex, getComponentIndex, getDefaultLightWeightPopupEnabled, getInvoker, getLabel, getMargin, getMenuKeyListeners, getPopupMenuListeners, getSelectionModel, getSubElements, getUI, getUIClassID, insert, insert, isBorderPainted, isLightWeightPopupEnabled, isPopupTrigger, isVisible, menuSelectionChanged, pack, paintBorder, paramString, processFocusEvent, processKeyEvent, processKeyEvent, processMouseEvent, remove, removeMenuKeyListener, removePopupMenuListener, setBorderPainted, setDefaultLightWeightPopupEnabled, setInvoker, setLabel, setLightWeightPopupEnabled, setLocation, setPopupSize, setPopupSize, setSelected, setSelectionModel, setUI, setVisible, show, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setName, setSize, setSize, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface javax.swing.plaf.basic.ComboPopup
isVisible

Field Detail

comboBox

protected JComboBox comboBox

list

protected JList list
This protected field is implementation specific. Do not access directly or override. Use the accessor methods instead.

See Also:
getList(), createList()

scroller

protected JScrollPane scroller
This protected field is implementation specific. Do not access directly or override. Use the create method instead

See Also:
createScroller()

valueIsAdjusting

protected boolean valueIsAdjusting
As of Java 2 platform v1.4 this previously undocumented field is no longer used.

mouseMotionListener

protected MouseMotionListener mouseMotionListener
This protected field is implementation specific. Do not access directly or override. Use the accessor or create methods instead.

See Also:
getMouseMotionListener(), createMouseMotionListener()

mouseListener

protected MouseListener mouseListener
This protected field is implementation specific. Do not access directly or override. Use the accessor or create methods instead.

See Also:
getMouseListener(), createMouseListener()

keyListener

protected KeyListener keyListener
This protected field is implementation specific. Do not access directly or override. Use the accessor or create methods instead.

See Also:
getKeyListener(), createKeyListener()

listSelectionListener

protected ListSelectionListener listSelectionListener
This protected field is implementation specific. Do not access directly or override. Use the create method instead.

See Also:
createListSelectionListener()

listMouseListener

protected MouseListener listMouseListener
This protected field is implementation specific. Do not access directly or override. Use the create method instead.

See Also:
createListMouseListener()

listMouseMotionListener

protected MouseMotionListener listMouseMotionListener
This protected field is implementation specific. Do not access directly or override. Use the create method instead

See Also:
createListMouseMotionListener()

propertyChangeListener

protected PropertyChangeListener propertyChangeListener
This protected field is implementation specific. Do not access directly or override. Use the create method instead

See Also:
createPropertyChangeListener()

listDataListener

protected ListDataListener listDataListener
This protected field is implementation specific. Do not access directly or override. Use the create method instead

See Also:
createListDataListener()

itemListener

protected ItemListener itemListener
This protected field is implementation specific. Do not access directly or override. Use the create method instead

See Also:
createItemListener()

autoscrollTimer

protected Timer autoscrollTimer
This protected field is implementation specific. Do not access directly or override.

hasEntered

protected boolean hasEntered

isAutoScrolling

protected boolean isAutoScrolling

scrollDirection

protected int scrollDirection

SCROLL_UP

protected static final int SCROLL_UP
See Also:
Constant Field Values

SCROLL_DOWN

protected static final int SCROLL_DOWN
See Also:
Constant Field Values
Constructor Detail

BasicComboPopup

public BasicComboPopup(JComboBox combo)
Method Detail

show

public void show()
Implementation of ComboPopup.show().

Specified by:
show in interface ComboPopup
Overrides:
show in class Component

hide

public void hide()
Implementation of ComboPopup.hide().

Specified by:
hide in interface ComboPopup
Overrides:
hide in class Component

getList

public JList getList()
Implementation of ComboPopup.getList().

Specified by:
getList in interface ComboPopup

getMouseListener

public MouseListener getMouseListener()
Implementation of ComboPopup.getMouseListener().

Specified by:
getMouseListener in interface ComboPopup
Returns:
a MouseListener or null
See Also:
ComboPopup.getMouseListener()

getMouseMotionListener

public MouseMotionListener getMouseMotionListener()
Implementation of ComboPopup.getMouseMotionListener().

Specified by:
getMouseMotionListener in interface ComboPopup
Returns:
a MouseMotionListener or null
See Also:
ComboPopup.getMouseMotionListener()

getKeyListener

public KeyListener getKeyListener()
Implementation of ComboPopup.getKeyListener().

Specified by:
getKeyListener in interface ComboPopup
Returns:
a KeyListener or null
See Also:
ComboPopup.getKeyListener()

uninstallingUI

public void uninstallingUI()
Called when the UI is uninstalling. Since this popup isn't in the component tree, it won't get it's uninstallUI() called. It removes the listeners that were added in addComboBoxListeners().

Specified by:
uninstallingUI in interface ComboPopup

uninstallComboBoxModelListeners

protected void uninstallComboBoxModelListeners(ComboBoxModel model)
Removes the listeners from the combo box model

Parameters:
model - The combo box model to install listeners
See Also:
installComboBoxModelListeners(javax.swing.ComboBoxModel)

uninstallKeyboardActions

protected void uninstallKeyboardActions()

firePopupMenuWillBecomeVisible

protected void firePopupMenuWillBecomeVisible()
Description copied from class: JPopupMenu
Notifies PopupMenuListeners that this popup menu will become visible.

Overrides:
firePopupMenuWillBecomeVisible in class JPopupMenu

firePopupMenuWillBecomeInvisible

protected void firePopupMenuWillBecomeInvisible()
Description copied from class: JPopupMenu
Notifies PopupMenuListeners that this popup menu will become invisible.

Overrides:
firePopupMenuWillBecomeInvisible in class JPopupMenu

firePopupMenuCanceled

protected void firePopupMenuCanceled()
Description copied from class: JPopupMenu
Notifies PopupMenuListeners that this popup menu is cancelled.

Overrides:
firePopupMenuCanceled in class JPopupMenu

createMouseListener

protected MouseListener createMouseListener()
Creates a listener that will watch for mouse-press and release events on the combo box. Warning: When overriding this method, make sure to maintain the existing behavior.

Returns:
a MouseListener which will be added to the combo box or null

createMouseMotionListener

protected MouseMotionListener createMouseMotionListener()
Creates the mouse motion listener which will be added to the combo box. Warning: When overriding this method, make sure to maintain the existing behavior.

Returns:
a MouseMotionListener which will be added to the combo box or null

createKeyListener

protected KeyListener createKeyListener()
Creates the key listener that will be added to the combo box. If this method returns null then it will not be added to the combo box.

Returns:
a KeyListener or null

createListSelectionListener

protected ListSelectionListener createListSelectionListener()
Creates a list selection listener that watches for selection changes in the popup's list. If this method returns null then it will not be added to the popup list.

Returns:
an instance of a ListSelectionListener or null

createListDataListener

protected ListDataListener createListDataListener()
Creates a list data listener which will be added to the ComboBoxModel. If this method returns null then it will not be added to the combo box model.

Returns:
an instance of a ListDataListener or null

createListMouseListener

protected MouseListener createListMouseListener()
Creates a mouse listener that watches for mouse events in the popup's list. If this method returns null then it will not be added to the combo box.

Returns:
an instance of a MouseListener or null

createListMouseMotionListener

protected MouseMotionListener createListMouseMotionListener()
Creates a mouse motion listener that watches for mouse motion events in the popup's list. If this method returns null then it will not be added to the combo box.

Returns:
an instance of a MouseMotionListener or null

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener()
Creates a PropertyChangeListener which will be added to the combo box. If this method returns null then it will not be added to the combo box.

Returns:
an instance of a PropertyChangeListener or null

createItemListener

protected ItemListener createItemListener()
Creates an ItemListener which will be added to the combo box. If this method returns null then it will not be added to the combo box.

Subclasses may override this method to return instances of their own ItemEvent handlers.

Returns:
an instance of an ItemListener or null

createList

protected JList createList()
Creates the JList used in the popup to display the items in the combo box model. This method is called when the UI class is created.

Returns:
a JList used to display the combo box items

configureList

protected void configureList()
Configures the list which is used to hold the combo box items in the popup. This method is called when the UI class is created.

See Also:
createList()

installListListeners

protected void installListListeners()
Adds the listeners to the list control.

createScroller

protected JScrollPane createScroller()
Creates the scroll pane which houses the scrollable list.

configureScroller

protected void configureScroller()
Configures the scrollable portion which holds the list within the combo box popup. This method is called when the UI class is created.

configurePopup

protected void configurePopup()
Configures the popup portion of the combo box. This method is called when the UI class is created.

installComboBoxListeners

protected void installComboBoxListeners()
This method adds the necessary listeners to the JComboBox.

installComboBoxModelListeners

protected void installComboBoxModelListeners(ComboBoxModel model)
Installs the listeners on the combo box model. Any listeners installed on the combo box model should be removed in uninstallComboBoxModelListeners.

Parameters:
model - The combo box model to install listeners
See Also:
uninstallComboBoxModelListeners(javax.swing.ComboBoxModel)

installKeyboardActions

protected void installKeyboardActions()

isFocusTraversable

public boolean isFocusTraversable()
Overridden to unconditionally return false.

Overrides:
isFocusTraversable in class Component
Returns:
true if this Component is focusable; false otherwise
See Also:
Component.setFocusable(boolean)

startAutoScrolling

protected void startAutoScrolling(int direction)
This protected method is implementation specific and should be private. do not call or override.

stopAutoScrolling

protected void stopAutoScrolling()
This protected method is implementation specific and should be private. do not call or override.

autoScrollUp

protected void autoScrollUp()
This protected method is implementation specific and should be private. do not call or override.

autoScrollDown

protected void autoScrollDown()
This protected method is implementation specific and should be private. do not call or override.

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this BasicComboPopup. The AccessibleContext will have its parent set to the ComboBox.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JPopupMenu
Returns:
an AccessibleContext for the BasicComboPopup
Since:
1.5

delegateFocus

protected void delegateFocus(MouseEvent e)
This is is a utility method that helps event handlers figure out where to send the focus when the popup is brought up. The standard implementation delegates the focus to the editor (if the combo box is editable) or to the JComboBox if it is not editable.

togglePopup

protected void togglePopup()
Makes the popup visible if it is hidden and makes it hidden if it is visible.

convertMouseEvent

protected MouseEvent convertMouseEvent(MouseEvent e)

getPopupHeightForRowCount

protected int getPopupHeightForRowCount(int maxRowCount)
Retrieves the height of the popup based on the current ListCellRenderer and the maximum row count.

computePopupBounds

protected Rectangle computePopupBounds(int px,
                                       int py,
                                       int pw,
                                       int ph)
Calculate the placement and size of the popup portion of the combo box based on the combo box location and the enclosing screen bounds. If no transformations are required, then the returned rectangle will have the same values as the parameters.

Parameters:
px - starting x location
py - starting y location
pw - starting width
ph - starting height
Returns:
a rectangle which represents the placement and size of the popup

updateListBoxSelectionForEvent

protected void updateListBoxSelectionForEvent(MouseEvent anEvent,
                                              boolean shouldScroll)
A utility method used by the event listeners. Given a mouse event, it changes the list selection to the list item below the mouse.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboPopup.InvocationKeyHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboPopup.InvocationKeyHandler

java.lang.Object
    extended by  java.awt.event.KeyAdapter
        extended by  javax.swing.plaf.basic.BasicComboPopup.InvocationKeyHandler
All Implemented Interfaces:
KeyListener, EventListener
Enclosing class:
BasicComboPopup
public class BasicComboPopup.InvocationKeyHandler
extends KeyAdapter

As of Java 2 platform v 1.4, this class is now obsolete and is only included for backwards API compatibility. Do not instantiate or subclass.

All the functionality of this class has been included in BasicComboBoxUI ActionMap/InputMap methods.

Constructor Summary
BasicComboPopup.InvocationKeyHandler()
Method Summary
 void keyReleased(KeyEvent e)
Invoked when a key has been released.
Methods inherited from class java.awt.event.KeyAdapter
keyPressed, keyTyped
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicComboPopup.InvocationKeyHandler

public BasicComboPopup.InvocationKeyHandler()
Method Detail

keyReleased

public void keyReleased(KeyEvent e)
Description copied from class: KeyAdapter
Invoked when a key has been released.

Specified by:
keyReleased in interface KeyListener
Overrides:
keyReleased in class KeyAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboPopup.InvocationMouseHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboPopup.InvocationMouseHandler

java.lang.Object
    extended by  java.awt.event.MouseAdapter
        extended by  javax.swing.plaf.basic.BasicComboPopup.InvocationMouseHandler
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, EventListener
Enclosing class:
BasicComboPopup
protected class BasicComboPopup.InvocationMouseHandler
extends MouseAdapter

A listener to be registered upon the combo box (not its popup menu) to handle mouse events that affect the state of the popup menu. The main purpose of this listener is to make the popup menu appear and disappear. This listener also helps with click-and-drag scenarios by setting the selection if the mouse was released over the list during a drag.

Warning: We recommend that you not create subclasses of this class. If you absolutely must create a subclass, be sure to invoke the superclass version of each method.

See Also:
BasicComboPopup.createMouseListener()

Constructor Summary
protected BasicComboPopup.InvocationMouseHandler()
Method Summary
void | mousePressed(MouseEvent e) Responds to mouse-pressed events on the combo box.
void | mouseReleased(MouseEvent e) Responds to the user terminating a click or drag that began on the combo box.
Methods inherited from class java.awt.event.MouseAdapter
mouseClicked, mouseDragged, mouseEntered, mouseExited, mouseMoved, mouseWheelMoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicComboPopup.InvocationMouseHandler

protected BasicComboPopup.InvocationMouseHandler()
Method Detail

mousePressed

public void mousePressed(MouseEvent e)
Responds to mouse-pressed events on the combo box.

Specified by:
mousePressed in interface MouseListener
Overrides:
mousePressed in class MouseAdapter
Parameters:
e - the mouse-press event to be handled

mouseReleased

public void mouseReleased(MouseEvent e)
Responds to the user terminating a click or drag that began on the combo box.

Specified by:
mouseReleased in interface MouseListener
Overrides:
mouseReleased in class MouseAdapter
Parameters:
e - the mouse-release event to be handled
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboPopup.InvocationMouseMotionHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboPopup.InvocationMouseMotionHandler

java.lang.Object
    extended by  java.awt.event.MouseMotionAdapter
        extended by  javax.swing.plaf.basic.BasicComboPopup.InvocationMouseMotionHandler
All Implemented Interfaces:
MouseMotionListener, EventListener
Enclosing class:
BasicComboPopup
protected class BasicComboPopup.InvocationMouseMotionHandler
extends MouseMotionAdapter

This listener watches for dragging and updates the current selection in the list if it is dragging over the list.

Constructor Summary
protected BasicComboPopup.InvocationMouseMotionHandler()
Method Summary
 void mouseDragged(MouseEvent e)
Invoked when a mouse button is pressed on a component and then dragged.
Methods inherited from class java.awt.event.MouseMotionAdapter
mouseMoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicComboPopup.InvocationMouseMotionHandler

protected BasicComboPopup.InvocationMouseMotionHandler()
Method Detail

mouseDragged

public void mouseDragged(MouseEvent e)
Description copied from class: MouseMotionAdapter
Invoked when a mouse button is pressed on a component and then dragged. Mouse drag events will continue to be delivered to the component where the first originated until the mouse button is released (regardless of whether the mouse position is within the bounds of the component).

Specified by:
mouseDragged in interface MouseMotionListener
Overrides:
mouseDragged in class MouseMotionAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboPopup.ItemHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboPopup.ItemHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicComboPopup.ItemHandler
All Implemented Interfaces:
ItemListener, EventListener
Enclosing class:
BasicComboPopup
protected class BasicComboPopup.ItemHandler
extends Object
implements ItemListener

This listener watches for changes to the selection in the combo box.

Constructor Summary
protected BasicComboPopup.ItemHandler()
Method Summary
 void itemStateChanged(ItemEvent e)
Invoked when an item has been selected or deselected by the user.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicComboPopup.ItemHandler

protected BasicComboPopup.ItemHandler()
Method Detail

itemStateChanged

public void itemStateChanged(ItemEvent e)
Description copied from interface: ItemListener
Invoked when an item has been selected or deselected by the user. The code written for this method performs the operations that need to occur when an item is selected (or deselected).

Specified by:
itemStateChanged in interface ItemListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboPopup.ListDataHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboPopup.ListDataHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicComboPopup.ListDataHandler
All Implemented Interfaces:
EventListener, ListDataListener
Enclosing class:
BasicComboPopup
public class BasicComboPopup.ListDataHandler
extends Object
implements ListDataListener

As of 1.4, this class is now obsolete, doesn't do anything, and is only included for backwards API compatibility. Do not call or override.

The functionality has been migrated into ItemHandler.

See Also:
BasicComboPopup.createItemListener()

Constructor Summary
BasicComboPopup.ListDataHandler()
Method Summary
void | contentsChanged(ListDataEvent e) Sent when the contents of the list has changed in a way that's too complex to characterize with the previous methods.
void | intervalAdded(ListDataEvent e) Sent after the indices in the index0,index1 interval have been inserted in the data model.
void | intervalRemoved(ListDataEvent e) Sent after the indices in the index0,index1 interval have been removed from the data model.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicComboPopup.ListDataHandler

public BasicComboPopup.ListDataHandler()
Method Detail

contentsChanged

public void contentsChanged(ListDataEvent e)
Description copied from interface: ListDataListener
Sent when the contents of the list has changed in a way that's too complex to characterize with the previous methods. For example, this is sent when an item has been replaced. Index0 and index1 bracket the change.

Specified by:
contentsChanged in interface ListDataListener
Parameters:
e - a ListDataEvent encapsulating the event information

intervalAdded

public void intervalAdded(ListDataEvent e)
Description copied from interface: ListDataListener
Sent after the indices in the index0,index1 interval have been inserted in the data model. The new interval includes both index0 and index1.

Specified by:
intervalAdded in interface ListDataListener
Parameters:
e - a ListDataEvent encapsulating the event information

intervalRemoved

public void intervalRemoved(ListDataEvent e)
Description copied from interface: ListDataListener
Sent after the indices in the index0,index1 interval have been removed from the data model. The interval includes both index0 and index1.

Specified by:
intervalRemoved in interface ListDataListener
Parameters:
e - a ListDataEvent encapsulating the event information
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboPopup.ListMouseHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboPopup.ListMouseHandler

java.lang.Object
    extended by  java.awt.event.MouseAdapter
        extended by  javax.swing.plaf.basic.BasicComboPopup.ListMouseHandler
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, EventListener
Enclosing class:
BasicComboPopup
protected class BasicComboPopup.ListMouseHandler
extends MouseAdapter

This listener hides the popup when the mouse is released in the list.

Constructor Summary
protected BasicComboPopup.ListMouseHandler()
Method Summary
void | mousePressed(MouseEvent e) Invoked when a mouse button has been pressed on a component.
void | mouseReleased(MouseEvent anEvent) Invoked when a mouse button has been released on a component.
Methods inherited from class java.awt.event.MouseAdapter
mouseClicked, mouseDragged, mouseEntered, mouseExited, mouseMoved, mouseWheelMoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicComboPopup.ListMouseHandler

protected BasicComboPopup.ListMouseHandler()
Method Detail

mousePressed

public void mousePressed(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when a mouse button has been pressed on a component.

Specified by:
mousePressed in interface MouseListener
Overrides:
mousePressed in class MouseAdapter

mouseReleased

public void mouseReleased(MouseEvent anEvent)
Description copied from class: MouseAdapter
Invoked when a mouse button has been released on a component.

Specified by:
mouseReleased in interface MouseListener
Overrides:
mouseReleased in class MouseAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboPopup.ListMouseMotionHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboPopup.ListMouseMotionHandler

java.lang.Object
    extended by  java.awt.event.MouseMotionAdapter
        extended by  javax.swing.plaf.basic.BasicComboPopup.ListMouseMotionHandler
All Implemented Interfaces:
MouseMotionListener, EventListener
Enclosing class:
BasicComboPopup
protected class BasicComboPopup.ListMouseMotionHandler
extends MouseMotionAdapter

This listener changes the selected item as you move the mouse over the list. The selection change is not committed to the model, this is for user feedback only.

Constructor Summary
protected BasicComboPopup.ListMouseMotionHandler()
Method Summary
 void mouseMoved(MouseEvent anEvent)
Invoked when the mouse button has been moved on a component (with no buttons no down).
Methods inherited from class java.awt.event.MouseMotionAdapter
mouseDragged
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicComboPopup.ListMouseMotionHandler

protected BasicComboPopup.ListMouseMotionHandler()
Method Detail

mouseMoved

public void mouseMoved(MouseEvent anEvent)
Description copied from class: MouseMotionAdapter
Invoked when the mouse button has been moved on a component (with no buttons no down).

Specified by:
mouseMoved in interface MouseMotionListener
Overrides:
mouseMoved in class MouseMotionAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboPopup.ListSelectionHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboPopup.ListSelectionHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicComboPopup.ListSelectionHandler
All Implemented Interfaces:
EventListener, ListSelectionListener
Enclosing class:
BasicComboPopup
protected class BasicComboPopup.ListSelectionHandler
extends Object
implements ListSelectionListener

As of Java 2 platform v 1.4, this class is now obsolete, doesn't do anything, and is only included for backwards API compatibility. Do not call or override.

Constructor Summary
protected BasicComboPopup.ListSelectionHandler()
Method Summary
 void valueChanged(ListSelectionEvent e)
Called whenever the value of the selection changes.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicComboPopup.ListSelectionHandler

protected BasicComboPopup.ListSelectionHandler()
Method Detail

valueChanged

public void valueChanged(ListSelectionEvent e)
Description copied from interface: ListSelectionListener
Called whenever the value of the selection changes.

Specified by:
valueChanged in interface ListSelectionListener
Parameters:
e - the event that characterizes the change.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicComboPopup.PropertyChangeHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicComboPopup.PropertyChangeHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicComboPopup.PropertyChangeHandler
All Implemented Interfaces:
PropertyChangeListener, EventListener
Enclosing class:
BasicComboPopup
protected class BasicComboPopup.PropertyChangeHandler
extends Object
implements PropertyChangeListener

This listener watches for bound properties that have changed in the combo box.

Subclasses which wish to listen to combo box property changes should call the superclass methods to ensure that the combo popup correctly handles property changes.

See Also:
BasicComboPopup.createPropertyChangeListener()

Constructor Summary
protected BasicComboPopup.PropertyChangeHandler()
Method Summary
 void propertyChange(PropertyChangeEvent e)
This method gets called when a bound property is changed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicComboPopup.PropertyChangeHandler

protected BasicComboPopup.PropertyChangeHandler()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicDesktopIconUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicDesktopIconUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.DesktopIconUI
            extended by  javax.swing.plaf.basic.BasicDesktopIconUI
Direct Known Subclasses:
MetalDesktopIconUI
public class BasicDesktopIconUI
extends DesktopIconUI

Basic L&F for a minimized window on a desktop.

Nested Class Summary
 class BasicDesktopIconUI.MouseInputHandler
Listens for mouse movements and acts on them.
Field Summary
protected JInternalFrame.JDesktopIcon | desktopIcon
protected JInternalFrame | frame
protected JComponent | iconPane The title pane component used in the desktop icon.
Constructor Summary
BasicDesktopIconUI()
Method Summary
protected MouseInputListener | createMouseInputListener()
static ComponentUI | createUI(JComponent c)
void | deiconize()
Insets | getInsets(JComponent c)
Dimension | getMaximumSize(JComponent c) Desktop icons can not be resized.
Dimension | getMinimumSize(JComponent c) Returns the specified component's minimum size appropriate for the look and feel.
Dimension | getPreferredSize(JComponent c) Returns the specified component's preferred size appropriate for the look and feel.
protected void | installComponents()
protected void | installDefaults()
protected void | installListeners()
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
protected void | uninstallComponents()
protected void | uninstallDefaults()
protected void | uninstallListeners()
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, paint, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

desktopIcon

protected JInternalFrame.JDesktopIcon desktopIcon

frame

protected JInternalFrame frame

iconPane

protected JComponent iconPane
The title pane component used in the desktop icon.

Since:
1.5
Constructor Detail

BasicDesktopIconUI

public BasicDesktopIconUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installComponents

protected void installComponents()

uninstallComponents

protected void uninstallComponents()

installListeners

protected void installListeners()

uninstallListeners

protected void uninstallListeners()

installDefaults

protected void installDefaults()

uninstallDefaults

protected void uninstallDefaults()

createMouseInputListener

protected MouseInputListener createMouseInputListener()

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's minimum size appropriate for the look and feel. If null is returned, the minimum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Desktop icons can not be resized. Therefore, we should always return the minimum size of the desktop icon.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
getMinimumSize(javax.swing.JComponent)

getInsets

public Insets getInsets(JComponent c)

deiconize

public void deiconize()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicDesktopIconUI.MouseInputHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicDesktopIconUI.MouseInputHandler

java.lang.Object
    extended by  java.awt.event.MouseAdapter
        extended by  javax.swing.event.MouseInputAdapter
            extended by  javax.swing.plaf.basic.BasicDesktopIconUI.MouseInputHandler
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, EventListener, MouseInputListener
Enclosing class:
BasicDesktopIconUI
public class BasicDesktopIconUI.MouseInputHandler
extends MouseInputAdapter

Listens for mouse movements and acts on them. This inner class is marked "public" due to a compiler bug. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Constructor Summary
BasicDesktopIconUI.MouseInputHandler()
Method Summary
void | mouseDragged(MouseEvent e) Invoked when a mouse button is pressed on a component and then dragged.
void | mouseMoved(MouseEvent e) Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.
void | mousePressed(MouseEvent e) Invoked when a mouse button has been pressed on a component.
void | mouseReleased(MouseEvent e) Invoked when a mouse button has been released on a component.
void | moveAndRepaint(JComponent f, int newX, int newY, int newWidth, int newHeight)
Methods inherited from class java.awt.event.MouseAdapter
mouseClicked, mouseEntered, mouseExited, mouseWheelMoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface java.awt.event.MouseListener
mouseClicked, mouseEntered, mouseExited

Constructor Detail

BasicDesktopIconUI.MouseInputHandler

public BasicDesktopIconUI.MouseInputHandler()
Method Detail

mouseReleased

public void mouseReleased(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when a mouse button has been released on a component.

Specified by:
mouseReleased in interface MouseListener
Overrides:
mouseReleased in class MouseAdapter

mousePressed

public void mousePressed(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when a mouse button has been pressed on a component.

Specified by:
mousePressed in interface MouseListener
Overrides:
mousePressed in class MouseAdapter

mouseMoved

public void mouseMoved(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.

Specified by:
mouseMoved in interface MouseMotionListener
Overrides:
mouseMoved in class MouseAdapter

mouseDragged

public void mouseDragged(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when a mouse button is pressed on a component and then dragged. MOUSE_DRAGGED events will continue to be delivered to the component where the drag originated until the mouse button is released (regardless of whether the mouse position is within the bounds of the component).

Due to platform-dependent Drag&Drop implementations, MOUSE_DRAGGED events may not be delivered during a native Drag&Drop operation.

Specified by:
mouseDragged in interface MouseMotionListener
Overrides:
mouseDragged in class MouseAdapter

moveAndRepaint

public void moveAndRepaint(JComponent f,
                           int newX,
                           int newY,
                           int newWidth,
                           int newHeight)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicDesktopPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicDesktopPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.DesktopPaneUI
            extended by  javax.swing.plaf.basic.BasicDesktopPaneUI

public class BasicDesktopPaneUI
extends DesktopPaneUI

Basic L&F for a desktop.

Nested Class Summary
protected class | BasicDesktopPaneUI.CloseAction Handles closing an internal frame.
protected class | BasicDesktopPaneUI.MaximizeAction Handles maximizing an internal frame.
protected class | BasicDesktopPaneUI.MinimizeAction Handles minimizing an internal frame.
protected class | BasicDesktopPaneUI.NavigateAction Handles navigating to the next internal frame.
protected class | BasicDesktopPaneUI.OpenAction Handles restoring a minimized or maximized internal frame.
Field Summary
protected KeyStroke | closeKey Deprecated. As of 1.3.
protected JDesktopPane | desktop
protected DesktopManager | desktopManager
protected KeyStroke | maximizeKey Deprecated. As of 1.3.
protected KeyStroke | minimizeKey Deprecated. As of 1.3.
protected KeyStroke | navigateKey Deprecated. As of 1.3.
protected KeyStroke | navigateKey2 Deprecated. As of 1.3.
Constructor Summary
BasicDesktopPaneUI()
Method Summary
protected PropertyChangeListener | createPropertyChangeListener() Returns the PropertyChangeListener to install on the JDesktopPane.
static ComponentUI | createUI(JComponent c)
Dimension | getMaximumSize(JComponent c) Returns the specified component's maximum size appropriate for the look and feel.
Dimension | getMinimumSize(JComponent c) Returns the specified component's minimum size appropriate for the look and feel.
Dimension | getPreferredSize(JComponent c) Returns the specified component's preferred size appropriate for the look and feel.
protected void | installDefaults()
protected void | installDesktopManager()
protected void | installKeyboardActions()
protected void | installListeners() Installs the PropertyChangeListener returned from createPropertyChangeListener on the JDesktopPane.
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
protected void | registerKeyboardActions()
protected void | uninstallDefaults()
protected void | uninstallDesktopManager()
protected void | uninstallKeyboardActions()
protected void | uninstallListeners() Uninstalls the PropertyChangeListener returned from createPropertyChangeListener from the JDesktopPane.
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
protected void | unregisterKeyboardActions()
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

desktop

protected JDesktopPane desktop

desktopManager

protected DesktopManager desktopManager

minimizeKey

@Deprecated
protected KeyStroke minimizeKey
Deprecated. As of 1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

maximizeKey

@Deprecated
protected KeyStroke maximizeKey
Deprecated. As of 1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

closeKey

@Deprecated
protected KeyStroke closeKey
Deprecated. As of 1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

navigateKey

@Deprecated
protected KeyStroke navigateKey
Deprecated. As of 1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

navigateKey2

@Deprecated
protected KeyStroke navigateKey2
Deprecated. As of 1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

Constructor Detail

BasicDesktopPaneUI

public BasicDesktopPaneUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installDefaults

protected void installDefaults()

uninstallDefaults

protected void uninstallDefaults()

installListeners

protected void installListeners()
Installs the PropertyChangeListener returned from createPropertyChangeListener on the JDesktopPane.

Since:
1.5
See Also:
createPropertyChangeListener()

uninstallListeners

protected void uninstallListeners()
Uninstalls the PropertyChangeListener returned from createPropertyChangeListener from the JDesktopPane.

Since:
1.5
See Also:
createPropertyChangeListener()

installDesktopManager

protected void installDesktopManager()

uninstallDesktopManager

protected void uninstallDesktopManager()

installKeyboardActions

protected void installKeyboardActions()

registerKeyboardActions

protected void registerKeyboardActions()

unregisterKeyboardActions

protected void unregisterKeyboardActions()

uninstallKeyboardActions

protected void uninstallKeyboardActions()

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's minimum size appropriate for the look and feel. If null is returned, the minimum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's maximum size appropriate for the look and feel. If null is returned, the maximum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener()
Returns the PropertyChangeListener to install on the JDesktopPane.

Returns:
The PropertyChangeListener that will be added to track changes in the desktop pane.
Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicDesktopPaneUI.CloseAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicDesktopPaneUI.CloseAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicDesktopPaneUI.CloseAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicDesktopPaneUI
protected class BasicDesktopPaneUI.CloseAction
extends AbstractAction

Handles closing an internal frame.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
protected BasicDesktopPaneUI.CloseAction()
Method Summary
void | actionPerformed(ActionEvent evt) Invoked when an action occurs.
boolean | isEnabled() Returns true if the action is enabled.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicDesktopPaneUI.CloseAction

protected BasicDesktopPaneUI.CloseAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent evt)
Description copied from interface: ActionListener
Invoked when an action occurs.

isEnabled

public boolean isEnabled()
Description copied from class: AbstractAction
Returns true if the action is enabled.

Specified by:
isEnabled in interface Action
Overrides:
isEnabled in class AbstractAction
Returns:
true if the action is enabled, false otherwise
See Also:
Action.isEnabled()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicDesktopPaneUI.MaximizeAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicDesktopPaneUI.MaximizeAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicDesktopPaneUI.MaximizeAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicDesktopPaneUI
protected class BasicDesktopPaneUI.MaximizeAction
extends AbstractAction

Handles maximizing an internal frame.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
protected BasicDesktopPaneUI.MaximizeAction()
Method Summary
void | actionPerformed(ActionEvent evt) Invoked when an action occurs.
boolean | isEnabled() Returns true if the action is enabled.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicDesktopPaneUI.MaximizeAction

protected BasicDesktopPaneUI.MaximizeAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent evt)
Description copied from interface: ActionListener
Invoked when an action occurs.

isEnabled

public boolean isEnabled()
Description copied from class: AbstractAction
Returns true if the action is enabled.

Specified by:
isEnabled in interface Action
Overrides:
isEnabled in class AbstractAction
Returns:
true if the action is enabled, false otherwise
See Also:
Action.isEnabled()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicDesktopPaneUI.MinimizeAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicDesktopPaneUI.MinimizeAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicDesktopPaneUI.MinimizeAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicDesktopPaneUI
protected class BasicDesktopPaneUI.MinimizeAction
extends AbstractAction

Handles minimizing an internal frame.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
protected BasicDesktopPaneUI.MinimizeAction()
Method Summary
void | actionPerformed(ActionEvent evt) Invoked when an action occurs.
boolean | isEnabled() Returns true if the action is enabled.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicDesktopPaneUI.MinimizeAction

protected BasicDesktopPaneUI.MinimizeAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent evt)
Description copied from interface: ActionListener
Invoked when an action occurs.

isEnabled

public boolean isEnabled()
Description copied from class: AbstractAction
Returns true if the action is enabled.

Specified by:
isEnabled in interface Action
Overrides:
isEnabled in class AbstractAction
Returns:
true if the action is enabled, false otherwise
See Also:
Action.isEnabled()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicDesktopPaneUI.NavigateAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicDesktopPaneUI.NavigateAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicDesktopPaneUI.NavigateAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicDesktopPaneUI
protected class BasicDesktopPaneUI.NavigateAction
extends AbstractAction

Handles navigating to the next internal frame.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
protected BasicDesktopPaneUI.NavigateAction()
Method Summary
void | actionPerformed(ActionEvent evt) Invoked when an action occurs.
boolean | isEnabled() Returns true if the action is enabled.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicDesktopPaneUI.NavigateAction

protected BasicDesktopPaneUI.NavigateAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent evt)
Description copied from interface: ActionListener
Invoked when an action occurs.

isEnabled

public boolean isEnabled()
Description copied from class: AbstractAction
Returns true if the action is enabled.

Specified by:
isEnabled in interface Action
Overrides:
isEnabled in class AbstractAction
Returns:
true if the action is enabled, false otherwise
See Also:
Action.isEnabled()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicDesktopPaneUI.OpenAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicDesktopPaneUI.OpenAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicDesktopPaneUI.OpenAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicDesktopPaneUI
protected class BasicDesktopPaneUI.OpenAction
extends AbstractAction

Handles restoring a minimized or maximized internal frame.

Since:
1.3

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
protected BasicDesktopPaneUI.OpenAction()
Method Summary
void | actionPerformed(ActionEvent evt) Invoked when an action occurs.
boolean | isEnabled() Returns true if the action is enabled.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicDesktopPaneUI.OpenAction

protected BasicDesktopPaneUI.OpenAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent evt)
Description copied from interface: ActionListener
Invoked when an action occurs.

isEnabled

public boolean isEnabled()
Description copied from class: AbstractAction
Returns true if the action is enabled.

Specified by:
isEnabled in interface Action
Overrides:
isEnabled in class AbstractAction
Returns:
true if the action is enabled, false otherwise
See Also:
Action.isEnabled()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicDirectoryModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicDirectoryModel

java.lang.Object
    extended by  javax.swing.AbstractListModel
        extended by  javax.swing.plaf.basic.BasicDirectoryModel
All Implemented Interfaces:
PropertyChangeListener, Serializable, EventListener, ListModel
public class BasicDirectoryModel
extends AbstractListModel
implements PropertyChangeListener

Basic implementation of a file list.

Field Summary
Fields inherited from class javax.swing.AbstractListModel
listenerList
Constructor Summary
BasicDirectoryModel(JFileChooser filechooser)
Method Summary
void | addPropertyChangeListener(PropertyChangeListener listener) Adds a PropertyChangeListener to the listener list.
boolean | contains(Object o)
void | fireContentsChanged()
protected void | firePropertyChange(String propertyName, Object oldValue, Object newValue) Support for reporting bound property changes for boolean properties.
Vector<File> | getDirectories()
Object | getElementAt(int index) Returns the value at the specified index.
Vector<File> | getFiles()
PropertyChangeListener[] | getPropertyChangeListeners() Returns an array of all the property change listeners registered on this component.
int | getSize() Returns the length of the list.
int | indexOf(Object o)
void | intervalAdded(ListDataEvent e) Obsolete - not used.
void | intervalRemoved(ListDataEvent e) Obsolete - not used.
void | invalidateFileCache() This method is used to interrupt file loading thread.
protected boolean | lt(File a, File b)
void | propertyChange(PropertyChangeEvent e) This method gets called when a bound property is changed.
void | removePropertyChangeListener(PropertyChangeListener listener) Removes a PropertyChangeListener from the listener list.
boolean | renameFile(File oldFile, File newFile) Renames a file in the underlying file system.
protected void | sort(Vector<? extends File> v)
void | validateFileCache()
Methods inherited from class javax.swing.AbstractListModel
addListDataListener, fireContentsChanged, fireIntervalAdded, fireIntervalRemoved, getListDataListeners, getListeners, removeListDataListener
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicDirectoryModel

public BasicDirectoryModel(JFileChooser filechooser)
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.

invalidateFileCache

public void invalidateFileCache()
This method is used to interrupt file loading thread.

getDirectories

public Vector<File> getDirectories()

getFiles

public Vector<File> getFiles()

validateFileCache

public void validateFileCache()

renameFile

public boolean renameFile(File oldFile,
                          File newFile)
Renames a file in the underlying file system.

Parameters:
oldFile - a File object representing the existing file
newFile - a File object representing the desired new file name
Returns:
true if rename succeeded, otherwise false
Since:
1.4

fireContentsChanged

public void fireContentsChanged()

getSize

public int getSize()
Description copied from interface: ListModel
Returns the length of the list.

Specified by:
getSize in interface ListModel
Returns:
the length of the list

contains

public boolean contains(Object o)

indexOf

public int indexOf(Object o)

getElementAt

public Object getElementAt(int index)
Description copied from interface: ListModel
Returns the value at the specified index.

Specified by:
getElementAt in interface ListModel
Parameters:
index - the requested index
Returns:
the value at index

intervalAdded

public void intervalAdded(ListDataEvent e)
Obsolete - not used.

intervalRemoved

public void intervalRemoved(ListDataEvent e)
Obsolete - not used.

sort

protected void sort(Vector<? extends File> v)

lt

protected boolean lt(File a,
                     File b)

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list. The listener is registered for all bound properties of this class.

If listener is null, no exception is thrown and no action is performed.

Parameters:
listener - the property change listener to be added
Since:
1.6
See Also:
removePropertyChangeListener(java.beans.PropertyChangeListener), getPropertyChangeListeners()

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list.

If listener is null, no exception is thrown and no action is performed.

Parameters:
listener - the PropertyChangeListener to be removed
Since:
1.6
See Also:
addPropertyChangeListener(java.beans.PropertyChangeListener), getPropertyChangeListeners()

getPropertyChangeListeners

public PropertyChangeListener[] getPropertyChangeListeners()
Returns an array of all the property change listeners registered on this component.

Returns:
all of this component's PropertyChangeListeners or an empty array if no property change listeners are currently registered
Since:
1.6
See Also:
addPropertyChangeListener(java.beans.PropertyChangeListener),
removePropertyChangeListener(java.beans.PropertyChangeListener),
PropertyChangeSupport.getPropertyChangeListeners()

firePropertyChange

protected void firePropertyChange(String propertyName,
                                  Object oldValue,
                                  Object newValue)
Support for reporting bound property changes for boolean properties. This method can be called when a bound property has changed and it will send the appropriate PropertyChangeEvent to any registered PropertyChangeListeners.

Parameters:
propertyName - the property whose value has changed
oldValue - the property's previous value
newValue - the property's new value
Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicEditorPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicEditorPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TextUI
            extended by  javax.swing.plaf.basic.BasicTextUI
                extended by  javax.swing.plaf.basic.BasicEditorPaneUI
All Implemented Interfaces:
ViewFactory
Direct Known Subclasses:
BasicTextPaneUI
public class BasicEditorPaneUI
extends BasicTextUI

Provides the look and feel for a JEditorPane.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicTextUI
BasicTextUI.BasicCaret, BasicTextUI.BasicHighlighter
Constructor Summary
BasicEditorPaneUI()
Creates a new BasicEditorPaneUI.
Method Summary
static ComponentUI | createUI(JComponent c) Creates a UI for the JTextPane.
EditorKit | getEditorKit(JTextComponent tc) Fetches the EditorKit for the UI.
protected String | getPropertyPrefix() Fetches the name used as a key to lookup properties through the UIManager.
void | installUI(JComponent c) Installs the UI for a component.
protected void | propertyChange(PropertyChangeEvent evt) This method gets called when a bound property is changed on the associated JTextComponent.
void | uninstallUI(JComponent c) Deinstalls the UI for a component.
Methods inherited from class javax.swing.plaf.basic.BasicTextUI
create, create, createCaret, createHighlighter, createKeymap, damageRange, damageRange, getComponent, getKeymapName, getMaximumSize, getMinimumSize, getNextVisualPositionFrom, getPreferredSize, getRootView, getToolTipText, getVisibleEditorRect, installDefaults, installKeyboardActions, installListeners, modelChanged, modelToView, modelToView, paint, paintBackground, paintSafely, setView, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, update, viewToModel, viewToModel
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicEditorPaneUI

public BasicEditorPaneUI()
Creates a new BasicEditorPaneUI.

Method Detail

createUI

public static ComponentUI createUI(JComponent c)
Creates a UI for the JTextPane.

Parameters:
c - the JTextPane component
Returns:
the UI

getPropertyPrefix

protected String getPropertyPrefix()
Fetches the name used as a key to lookup properties through the UIManager. This is used as a prefix to all the standard text properties.

Specified by:
getPropertyPrefix in class BasicTextUI
Returns:
the name ("EditorPane")

installUI

public void installUI(JComponent c)
Installs the UI for a component. This does the following things.
  1. Set the associated component to opaque (can be changed easily by a subclass or on JTextComponent directly), which is the most common case. This will cause the component's background color to be painted.
  2. Install the default caret and highlighter into the associated component.
  3. Attach to the editor and model. If there is no model, a default one is created.
  4. create the view factory and the view hierarchy used to represent the model.

Overrides:
installUI in class BasicTextUI
Parameters:
c - the editor component
Since:
1.5
See Also:
ComponentUI.installUI(javax.swing.JComponent)

uninstallUI

public void uninstallUI(JComponent c)
Deinstalls the UI for a component. This removes the listeners, uninstalls the highlighter, removes views, and nulls out the keymap.

Overrides:
uninstallUI in class BasicTextUI
Parameters:
c - the editor component
Since:
1.5
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent)

getEditorKit

public EditorKit getEditorKit(JTextComponent tc)
Fetches the EditorKit for the UI. This is whatever is currently set in the associated JEditorPane.

Overrides:
getEditorKit in class BasicTextUI
Parameters:
tc - the text component for which this UI is installed
Returns:
the editor capabilities
See Also:
TextUI.getEditorKit(javax.swing.text.JTextComponent)

propertyChange

protected void propertyChange(PropertyChangeEvent evt)
This method gets called when a bound property is changed on the associated JTextComponent. This is a hook which UI implementations may change to reflect how the UI displays bound properties of JTextComponent subclasses. This is implemented to rebuild the ActionMap based upon an EditorKit change.

Overrides:
propertyChange in class BasicTextUI
Parameters:
evt - the property change event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicFileChooserUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicFileChooserUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.FileChooserUI
            extended by  javax.swing.plaf.basic.BasicFileChooserUI
Direct Known Subclasses:
MetalFileChooserUI
public class BasicFileChooserUI
extends FileChooserUI

Basic L&F implementation of a FileChooser.

Nested Class Summary
protected class | BasicFileChooserUI.AcceptAllFileFilter
protected class | BasicFileChooserUI.ApproveSelectionAction Responds to an Open or Save request
protected class | BasicFileChooserUI.BasicFileView
protected class | BasicFileChooserUI.CancelSelectionAction Responds to a cancel request.
protected class | BasicFileChooserUI.ChangeToParentDirectoryAction
protected class | BasicFileChooserUI.DoubleClickListener
protected class | BasicFileChooserUI.GoHomeAction Acts on the "home" key event or equivalent event.
protected class | BasicFileChooserUI.NewFolderAction Creates a new folder.
protected class | BasicFileChooserUI.SelectionListener
protected class | BasicFileChooserUI.UpdateAction Rescans the files in the current directory
Field Summary
protected int | cancelButtonMnemonic
protected String | cancelButtonText
protected String | cancelButtonToolTipText
protected Icon | computerIcon
protected Icon | detailsViewIcon
protected Icon | directoryIcon
protected int | directoryOpenButtonMnemonic The mnemonic keycode used for the approve button when a directory is selected and the current selection mode is FILES_ONLY.
protected String | directoryOpenButtonText The label text displayed on the approve button when a directory is selected and the current selection mode is FILES_ONLY.
protected String | directoryOpenButtonToolTipText The tooltip text displayed on the approve button when a directory is selected and the current selection mode is FILES_ONLY.
protected Icon | fileIcon
protected Icon | floppyDriveIcon
protected Icon | hardDriveIcon
protected int | helpButtonMnemonic
protected String | helpButtonText
protected String | helpButtonToolTipText
protected Icon | homeFolderIcon
protected Icon | listViewIcon
protected Icon | newFolderIcon
protected int | openButtonMnemonic
protected String | openButtonText
protected String | openButtonToolTipText
protected int | saveButtonMnemonic
protected String | saveButtonText
protected String | saveButtonToolTipText
protected int | updateButtonMnemonic
protected String | updateButtonText
protected String | updateButtonToolTipText
protected Icon | upFolderIcon
Constructor Summary
BasicFileChooserUI(JFileChooser b)
Method Summary
void | clearIconCache()
protected MouseListener | createDoubleClickListener(JFileChooser fc, JList list)
ListSelectionListener | createListSelectionListener(JFileChooser fc)
protected void | createModel()
PropertyChangeListener | createPropertyChangeListener(JFileChooser fc)
void | ensureFileIsVisible(JFileChooser fc, File f)
FileFilter | getAcceptAllFileFilter(JFileChooser fc) Returns the default accept all file filter
JPanel | getAccessoryPanel()
protected JButton | getApproveButton(JFileChooser fc)
int | getApproveButtonMnemonic(JFileChooser fc)
String | getApproveButtonText(JFileChooser fc)
String | getApproveButtonToolTipText(JFileChooser fc)
Action | getApproveSelectionAction()
Action | getCancelSelectionAction()
Action | getChangeToParentDirectoryAction()
String | getDialogTitle(JFileChooser fc) Returns the title of this dialog
protected File | getDirectory() Property to remember the directory that is currently selected in the UI.
String | getDirectoryName()
JFileChooser | getFileChooser()
String | getFileName()
FileView | getFileView(JFileChooser fc)
Action | getGoHomeAction()
BasicDirectoryModel | getModel()
Action | getNewFolderAction()
Action | getUpdateAction()
void | installComponents(JFileChooser fc)
protected void | installDefaults(JFileChooser fc)
protected void | installIcons(JFileChooser fc)
protected void | installListeners(JFileChooser fc)
protected void | installStrings(JFileChooser fc)
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
protected boolean | isDirectorySelected() Property to remember whether a directory is currently selected in the UI.
void | rescanCurrentDirectory(JFileChooser fc)
protected void | setDirectory(File f) Property to remember the directory that is currently selected in the UI.
void | setDirectoryName(String dirname)
protected void | setDirectorySelected(boolean b) Property to remember whether a directory is currently selected in the UI.
void | setFileName(String filename)
void | uninstallComponents(JFileChooser fc)
protected void | uninstallDefaults(JFileChooser fc)
protected void | uninstallIcons(JFileChooser fc)
protected void | uninstallListeners(JFileChooser fc)
protected void | uninstallStrings(JFileChooser fc)
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, paint, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

directoryIcon

protected Icon directoryIcon

fileIcon

protected Icon fileIcon

computerIcon

protected Icon computerIcon

hardDriveIcon

protected Icon hardDriveIcon

floppyDriveIcon

protected Icon floppyDriveIcon

newFolderIcon

protected Icon newFolderIcon

upFolderIcon

protected Icon upFolderIcon

homeFolderIcon

protected Icon homeFolderIcon

listViewIcon

protected Icon listViewIcon

detailsViewIcon

protected Icon detailsViewIcon

saveButtonMnemonic

protected int saveButtonMnemonic

openButtonMnemonic

protected int openButtonMnemonic

cancelButtonMnemonic

protected int cancelButtonMnemonic

updateButtonMnemonic

protected int updateButtonMnemonic

helpButtonMnemonic

protected int helpButtonMnemonic

directoryOpenButtonMnemonic

protected int directoryOpenButtonMnemonic
The mnemonic keycode used for the approve button when a directory is selected and the current selection mode is FILES_ONLY.

Since:
1.4

saveButtonText

protected String saveButtonText

openButtonText

protected String openButtonText

cancelButtonText

protected String cancelButtonText

updateButtonText

protected String updateButtonText

helpButtonText

protected String helpButtonText

directoryOpenButtonText

protected String directoryOpenButtonText
The label text displayed on the approve button when a directory is selected and the current selection mode is FILES_ONLY.

Since:
1.4

saveButtonToolTipText

protected String saveButtonToolTipText

openButtonToolTipText

protected String openButtonToolTipText

cancelButtonToolTipText

protected String cancelButtonToolTipText

updateButtonToolTipText

protected String updateButtonToolTipText

helpButtonToolTipText

protected String helpButtonToolTipText

directoryOpenButtonToolTipText

protected String directoryOpenButtonToolTipText
The tooltip text displayed on the approve button when a directory is selected and the current selection mode is FILES_ONLY.

Since:
1.4
Constructor Detail

BasicFileChooserUI

public BasicFileChooserUI(JFileChooser b)
Method Detail

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installComponents

public void installComponents(JFileChooser fc)

uninstallComponents

public void uninstallComponents(JFileChooser fc)

installListeners

protected void installListeners(JFileChooser fc)

uninstallListeners

protected void uninstallListeners(JFileChooser fc)

installDefaults

protected void installDefaults(JFileChooser fc)

installIcons

protected void installIcons(JFileChooser fc)

installStrings

protected void installStrings(JFileChooser fc)

uninstallDefaults

protected void uninstallDefaults(JFileChooser fc)

uninstallIcons

protected void uninstallIcons(JFileChooser fc)

uninstallStrings

protected void uninstallStrings(JFileChooser fc)

createModel

protected void createModel()

getModel

public BasicDirectoryModel getModel()

createPropertyChangeListener

public PropertyChangeListener createPropertyChangeListener(JFileChooser fc)

getFileName

public String getFileName()

getDirectoryName

public String getDirectoryName()

setFileName

public void setFileName(String filename)

setDirectoryName

public void setDirectoryName(String dirname)

rescanCurrentDirectory

public void rescanCurrentDirectory(JFileChooser fc)
Specified by:
rescanCurrentDirectory in class FileChooserUI

ensureFileIsVisible

public void ensureFileIsVisible(JFileChooser fc,
                                File f)
Specified by:
ensureFileIsVisible in class FileChooserUI

getFileChooser

public JFileChooser getFileChooser()

getAccessoryPanel

public JPanel getAccessoryPanel()

getApproveButton

protected JButton getApproveButton(JFileChooser fc)

getApproveButtonToolTipText

public String getApproveButtonToolTipText(JFileChooser fc)

clearIconCache

public void clearIconCache()

createDoubleClickListener

protected MouseListener createDoubleClickListener(JFileChooser fc,
                                                  JList list)

createListSelectionListener

public ListSelectionListener createListSelectionListener(JFileChooser fc)

isDirectorySelected

protected boolean isDirectorySelected()
Property to remember whether a directory is currently selected in the UI.

Returns:
true iff a directory is currently selected.
Since:
1.4

setDirectorySelected

protected void setDirectorySelected(boolean b)
Property to remember whether a directory is currently selected in the UI. This is normally called by the UI on a selection event.

Parameters:
b - iff a directory is currently selected.
Since:
1.4

getDirectory

protected File getDirectory()
Property to remember the directory that is currently selected in the UI.

Returns:
the value of the directory property
Since:
1.4
See Also:
setDirectory(java.io.File)

setDirectory

protected void setDirectory(File f)
Property to remember the directory that is currently selected in the UI. This is normally called by the UI on a selection event.

Parameters:
f - the File object representing the directory that is currently selected
Since:
1.4

getAcceptAllFileFilter

public FileFilter getAcceptAllFileFilter(JFileChooser fc)
Returns the default accept all file filter

Specified by:
getAcceptAllFileFilter in class FileChooserUI

getFileView

public FileView getFileView(JFileChooser fc)
Specified by:
getFileView in class FileChooserUI

getDialogTitle

public String getDialogTitle(JFileChooser fc)
Returns the title of this dialog

Specified by:
getDialogTitle in class FileChooserUI

getApproveButtonMnemonic

public int getApproveButtonMnemonic(JFileChooser fc)

getApproveButtonText

public String getApproveButtonText(JFileChooser fc)
Specified by:
getApproveButtonText in class FileChooserUI

getNewFolderAction

public Action getNewFolderAction()

getGoHomeAction

public Action getGoHomeAction()

getChangeToParentDirectoryAction

public Action getChangeToParentDirectoryAction()

getApproveSelectionAction

public Action getApproveSelectionAction()

getCancelSelectionAction

public Action getCancelSelectionAction()

getUpdateAction

public Action getUpdateAction()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicFileChooserUI.AcceptAllFileFilter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicFileChooserUI.AcceptAllFileFilter

java.lang.Object
    extended by  javax.swing.filechooser.FileFilter
        extended by  javax.swing.plaf.basic.BasicFileChooserUI.AcceptAllFileFilter
Enclosing class:
BasicFileChooserUI
protected class BasicFileChooserUI.AcceptAllFileFilter
extends FileFilter

Constructor Summary
BasicFileChooserUI.AcceptAllFileFilter()
Method Summary
boolean | accept(File f) Whether the given file is accepted by this filter.
String | getDescription() The description of this filter.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicFileChooserUI.AcceptAllFileFilter

public BasicFileChooserUI.AcceptAllFileFilter()
Method Detail

accept

public boolean accept(File f)
Description copied from class: FileFilter
Whether the given file is accepted by this filter.

Specified by:
accept in class FileFilter

getDescription

public String getDescription()
Description copied from class: FileFilter
The description of this filter. For example: "JPG and GIF Images"

Specified by:
getDescription in class FileFilter
See Also:
FileView.getName(java.io.File)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicFileChooserUI.ApproveSelectionAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicFileChooserUI.ApproveSelectionAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicFileChooserUI.ApproveSelectionAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicFileChooserUI
protected class BasicFileChooserUI.ApproveSelectionAction
extends AbstractAction

Responds to an Open or Save request

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
protected BasicFileChooserUI.ApproveSelectionAction()
Method Summary
 void actionPerformed(ActionEvent e)
Invoked when an action occurs.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicFileChooserUI.ApproveSelectionAction

protected BasicFileChooserUI.ApproveSelectionAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicFileChooserUI.BasicFileView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicFileChooserUI.BasicFileView

java.lang.Object
    extended by  javax.swing.filechooser.FileView
        extended by  javax.swing.plaf.basic.BasicFileChooserUI.BasicFileView
Enclosing class:
BasicFileChooserUI
protected class BasicFileChooserUI.BasicFileView
extends FileView

Field Summary
protected  Hashtable<File,Icon> iconCache
Constructor Summary
BasicFileChooserUI.BasicFileView()
Method Summary
void | cacheIcon(File f, Icon i)
void | clearIconCache()
Icon | getCachedIcon(File f)
String | getDescription(File f) A human readable description of the file.
Icon | getIcon(File f) The icon that represents this file in the JFileChooser.
String | getName(File f) The name of the file.
String | getTypeDescription(File f) A human readable description of the type of the file.
Boolean | isHidden(File f)
Methods inherited from class javax.swing.filechooser.FileView
isTraversable
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

iconCache

protected Hashtable<File,Icon> iconCache
Constructor Detail

BasicFileChooserUI.BasicFileView

public BasicFileChooserUI.BasicFileView()
Method Detail

clearIconCache

public void clearIconCache()

getName

public String getName(File f)
Description copied from class: FileView
The name of the file. Normally this would be simply f.getName().

Overrides:
getName in class FileView

getDescription

public String getDescription(File f)
Description copied from class: FileView
A human readable description of the file. For example, a file named jag.jpg might have a description that read: "A JPEG image file of James Gosling's face".

Overrides:
getDescription in class FileView

getTypeDescription

public String getTypeDescription(File f)
Description copied from class: FileView
A human readable description of the type of the file. For example, a jpg file might have a type description of: "A JPEG Compressed Image File"

Overrides:
getTypeDescription in class FileView

getCachedIcon

public Icon getCachedIcon(File f)

cacheIcon

public void cacheIcon(File f,
                      Icon i)

getIcon

public Icon getIcon(File f)
Description copied from class: FileView
The icon that represents this file in the JFileChooser.

Overrides:
getIcon in class FileView

isHidden

public Boolean isHidden(File f)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicFileChooserUI.CancelSelectionAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicFileChooserUI.CancelSelectionAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicFileChooserUI.CancelSelectionAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicFileChooserUI
protected class BasicFileChooserUI.CancelSelectionAction
extends AbstractAction

Responds to a cancel request.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
protected BasicFileChooserUI.CancelSelectionAction()
Method Summary
 void actionPerformed(ActionEvent e)
Invoked when an action occurs.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicFileChooserUI.CancelSelectionAction

protected BasicFileChooserUI.CancelSelectionAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicFileChooserUI.ChangeToParentDirectoryAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicFileChooserUI.ChangeToParentDirectoryAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicFileChooserUI.ChangeToParentDirectoryAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicFileChooserUI
protected class BasicFileChooserUI.ChangeToParentDirectoryAction
extends AbstractAction

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
protected BasicFileChooserUI.ChangeToParentDirectoryAction()
Method Summary
 void actionPerformed(ActionEvent e)
Invoked when an action occurs.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicFileChooserUI.ChangeToParentDirectoryAction

protected BasicFileChooserUI.ChangeToParentDirectoryAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicFileChooserUI.DoubleClickListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicFileChooserUI.DoubleClickListener

java.lang.Object
    extended by  java.awt.event.MouseAdapter
        extended by  javax.swing.plaf.basic.BasicFileChooserUI.DoubleClickListener
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, EventListener
Enclosing class:
BasicFileChooserUI
protected class BasicFileChooserUI.DoubleClickListener
extends MouseAdapter

Constructor Summary
BasicFileChooserUI.DoubleClickListener(JList list)
Method Summary
void | mouseClicked(MouseEvent e) Invoked when the mouse button has been clicked (pressed and released) on a component.
void | mouseEntered(MouseEvent e) The JList used for representing the files is created by subclasses, but the selection is monitored in this class.
Methods inherited from class java.awt.event.MouseAdapter
mouseDragged, mouseExited, mouseMoved, mousePressed, mouseReleased, mouseWheelMoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicFileChooserUI.DoubleClickListener

public BasicFileChooserUI.DoubleClickListener(JList list)
Method Detail

mouseEntered

public void mouseEntered(MouseEvent e)
The JList used for representing the files is created by subclasses, but the selection is monitored in this class. The TransferHandler installed in the JFileChooser is also installed in the file list as it is used as the actual transfer source. The list is updated on a mouse enter to reflect the current data transfer state of the file chooser.

Specified by:
mouseEntered in interface MouseListener
Overrides:
mouseEntered in class MouseAdapter

mouseClicked

public void mouseClicked(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when the mouse button has been clicked (pressed and released) on a component.

Specified by:
mouseClicked in interface MouseListener
Overrides:
mouseClicked in class MouseAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicFileChooserUI.GoHomeAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicFileChooserUI.GoHomeAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicFileChooserUI.GoHomeAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicFileChooserUI
protected class BasicFileChooserUI.GoHomeAction
extends AbstractAction

Acts on the "home" key event or equivalent event.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
protected BasicFileChooserUI.GoHomeAction()
Method Summary
 void actionPerformed(ActionEvent e)
Invoked when an action occurs.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicFileChooserUI.GoHomeAction

protected BasicFileChooserUI.GoHomeAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicFileChooserUI.NewFolderAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicFileChooserUI.NewFolderAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicFileChooserUI.NewFolderAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicFileChooserUI
protected class BasicFileChooserUI.NewFolderAction
extends AbstractAction

Creates a new folder.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
protected BasicFileChooserUI.NewFolderAction()
Method Summary
 void actionPerformed(ActionEvent e)
Invoked when an action occurs.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicFileChooserUI.NewFolderAction

protected BasicFileChooserUI.NewFolderAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicFileChooserUI.SelectionListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicFileChooserUI.SelectionListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicFileChooserUI.SelectionListener
All Implemented Interfaces:
EventListener, ListSelectionListener
Enclosing class:
BasicFileChooserUI
protected class BasicFileChooserUI.SelectionListener
extends Object
implements ListSelectionListener

Constructor Summary
protected BasicFileChooserUI.SelectionListener()
Method Summary
 void valueChanged(ListSelectionEvent e)
Called whenever the value of the selection changes.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicFileChooserUI.SelectionListener

protected BasicFileChooserUI.SelectionListener()
Method Detail

valueChanged

public void valueChanged(ListSelectionEvent e)
Description copied from interface: ListSelectionListener
Called whenever the value of the selection changes.

Specified by:
valueChanged in interface ListSelectionListener
Parameters:
e - the event that characterizes the change.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicFileChooserUI.UpdateAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicFileChooserUI.UpdateAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicFileChooserUI.UpdateAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicFileChooserUI
protected class BasicFileChooserUI.UpdateAction
extends AbstractAction

Rescans the files in the current directory

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
protected BasicFileChooserUI.UpdateAction()
Method Summary
 void actionPerformed(ActionEvent e)
Invoked when an action occurs.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicFileChooserUI.UpdateAction

protected BasicFileChooserUI.UpdateAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicFormattedTextFieldUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicFormattedTextFieldUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TextUI
            extended by  javax.swing.plaf.basic.BasicTextUI
                extended by  javax.swing.plaf.basic.BasicTextFieldUI
                    extended by  javax.swing.plaf.basic.BasicFormattedTextFieldUI
All Implemented Interfaces:
ViewFactory
public class BasicFormattedTextFieldUI
extends BasicTextFieldUI

Provides the look and feel implementation for JFormattedTextField.

Since:
1.4

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicTextUI
BasicTextUI.BasicCaret, BasicTextUI.BasicHighlighter
Constructor Summary
BasicFormattedTextFieldUI()
Method Summary
static ComponentUI | createUI(JComponent c) Creates a UI for a JFormattedTextField.
protected String | getPropertyPrefix() Fetches the name used as a key to lookup properties through the UIManager.
Methods inherited from class javax.swing.plaf.basic.BasicTextFieldUI
create, getBaseline, getBaselineResizeBehavior
Methods inherited from class javax.swing.plaf.basic.BasicTextUI
create, createCaret, createHighlighter, createKeymap, damageRange, damageRange, getComponent, getEditorKit, getKeymapName, getMaximumSize, getMinimumSize, getNextVisualPositionFrom, getPreferredSize, getRootView, getToolTipText, getVisibleEditorRect, installDefaults, installKeyboardActions, installListeners, installUI, modelChanged, modelToView, modelToView, paint, paintBackground, paintSafely, propertyChange, setView, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, uninstallUI, update, viewToModel, viewToModel
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicFormattedTextFieldUI

public BasicFormattedTextFieldUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)
Creates a UI for a JFormattedTextField.

Parameters:
c - the formatted text field
Returns:
the UI

getPropertyPrefix

protected String getPropertyPrefix()
Fetches the name used as a key to lookup properties through the UIManager. This is used as a prefix to all the standard text properties.

Overrides:
getPropertyPrefix in class BasicTextFieldUI
Returns:
the name "FormattedTextField"
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicGraphicsUtils

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicGraphicsUtils

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicGraphicsUtils

public class BasicGraphicsUtils
extends Object

Constructor Summary
BasicGraphicsUtils()
Method Summary
static void drawBezel(Graphics g, int x, int y, int w, int h, boolean isPressed, boolean isDefault, Color shadow, Color darkShadow, Color highlight, Color lightHighlight)
static void drawDashedRect(Graphics g, int x, int y, int width, int height)
static void drawEtchedRect(Graphics g, int x, int y, int w, int h, Color shadow, Color darkShadow, Color highlight, Color lightHighlight)
static void drawGroove(Graphics g, int x, int y, int w, int h, Color shadow, Color highlight)
static void drawLoweredBezel(Graphics g, int x, int y, int w, int h, Color shadow, Color darkShadow, Color highlight, Color lightHighlight)
static void drawString(Graphics g, String text, int underlinedChar, int x, int y)
Draw a string with the graphics g at location (x,y) just like g.drawString would.
static void drawStringUnderlineCharAt(Graphics g, String text, int underlinedIndex, int x, int y)
Draw a string with the graphics g at location (x, y) just like g.drawString would.
static Insets getEtchedInsets()
Returns the amount of space taken up by a border drawn by drawEtchedRect()
static Insets getGrooveInsets()
Returns the amount of space taken up by a border drawn by drawGroove()
static Dimension getPreferredButtonSize(AbstractButton b, int textIconGap)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicGraphicsUtils

public BasicGraphicsUtils()
Method Detail

drawEtchedRect

public static void drawEtchedRect(Graphics g,
                                  int x,
                                  int y,
                                  int w,
                                  int h,
                                  Color shadow,
                                  Color darkShadow,
                                  Color highlight,
                                  Color lightHighlight)

getEtchedInsets

public static Insets getEtchedInsets()
Returns the amount of space taken up by a border drawn by drawEtchedRect()

Returns:
the inset of an etched rect

drawGroove

public static void drawGroove(Graphics g,
                              int x,
                              int y,
                              int w,
                              int h,
                              Color shadow,
                              Color highlight)

getGrooveInsets

public static Insets getGrooveInsets()
Returns the amount of space taken up by a border drawn by drawGroove()

Returns:
the inset of a groove border

drawBezel

public static void drawBezel(Graphics g,
                             int x,
                             int y,
                             int w,
                             int h,
                             boolean isPressed,
                             boolean isDefault,
                             Color shadow,
                             Color darkShadow,
                             Color highlight,
                             Color lightHighlight)

drawLoweredBezel

public static void drawLoweredBezel(Graphics g,
                                    int x,
                                    int y,
                                    int w,
                                    int h,
                                    Color shadow,
                                    Color darkShadow,
                                    Color highlight,
                                    Color lightHighlight)

drawString

public static void drawString(Graphics g,
                              String text,
                              int underlinedChar,
                              int x,
                              int y)
Draw a string with the graphics g at location (x,y) just like g.drawString would. The first occurrence of underlineChar in text will be underlined. The matching algorithm is not case sensitive.

drawStringUnderlineCharAt

public static void drawStringUnderlineCharAt(Graphics g,
                                             String text,
                                             int underlinedIndex,
                                             int x,
                                             int y)
Draw a string with the graphics g at location (x, y) just like g.drawString would. The character at index underlinedIndex in text will be underlined. If index is beyond the bounds of text (including < 0), nothing will be underlined.

Parameters:
g - Graphics to draw with
text - String to draw
underlinedIndex - Index of character in text to underline
x - x coordinate to draw at
y - y coordinate to draw at
Since:
1.4

drawDashedRect

public static void drawDashedRect(Graphics g,
                                  int x,
                                  int y,
                                  int width,
                                  int height)

getPreferredButtonSize

public static Dimension getPreferredButtonSize(AbstractButton b,
                                               int textIconGap)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicHTML

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicHTML

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicHTML

public class BasicHTML
extends Object

Support for providing html views for the swing components. This translates a simple html string to a javax.swing.text.View implementation that can render the html and provide the necessary layout semantics.

Since:
1.3

Field Summary
static String | documentBaseKey Key stored as a client property to indicate the base that relative references are resolved against.
static String | propertyKey Key to use for the html renderer when stored as a client property of a JComponent.
Constructor Summary
BasicHTML()
Method Summary
static View | createHTMLView(JComponent c, String html) Create an html renderer for the given component and string of html.
static int | getHTMLBaseline(View view, int w, int h) Returns the baseline for the html renderer.
static boolean | isHTMLString(String s) Check the given string to see if it should trigger the html rendering logic in a non-text component that supports html rendering.
static void | updateRenderer(JComponent c, String text) Stash the HTML render for the given text into the client properties of the given JComponent.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

propertyKey

public static final String propertyKey
Key to use for the html renderer when stored as a client property of a JComponent.

See Also:
Constant Field Values

documentBaseKey

public static final String documentBaseKey
Key stored as a client property to indicate the base that relative references are resolved against. For example, lets say you keep your images in the directory resources relative to the code path, you would use the following the set the base:
   jComponent.putClientProperty(documentBaseKey,
                                xxx.class.getResource("resources/"));

See Also:
Constant Field Values
Constructor Detail

BasicHTML

public BasicHTML()
Method Detail

createHTMLView

public static View createHTMLView(JComponent c,
                                  String html)
Create an html renderer for the given component and string of html.

getHTMLBaseline

public static int getHTMLBaseline(View view,
                                  int w,
                                  int h)
Returns the baseline for the html renderer.

Parameters:
view - the View to get the baseline for
w - the width to get the baseline for
h - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
FontMetrics, JComponent.getBaseline(int,int)

isHTMLString

public static boolean isHTMLString(String s)
Check the given string to see if it should trigger the html rendering logic in a non-text component that supports html rendering.

updateRenderer

public static void updateRenderer(JComponent c,
                                  String text)
Stash the HTML render for the given text into the client properties of the given JComponent. If the given text is NOT HTML the property will be cleared of any renderer.

This method is useful for ComponentUI implementations that are static (i.e. shared) and get their state entirely from the JComponent.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicIconFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicIconFactory

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicIconFactory
All Implemented Interfaces:
Serializable
public class BasicIconFactory
extends Object
implements Serializable

Factory object that can vend Icons appropriate for the basic L & F.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
BasicIconFactory()
Method Summary
static Icon | createEmptyFrameIcon()
static Icon | getCheckBoxIcon()
static Icon | getCheckBoxMenuItemIcon()
static Icon | getMenuArrowIcon()
static Icon | getMenuItemArrowIcon()
static Icon | getMenuItemCheckIcon()
static Icon | getRadioButtonIcon()
static Icon | getRadioButtonMenuItemIcon()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicIconFactory

public BasicIconFactory()
Method Detail

getMenuItemCheckIcon

public static Icon getMenuItemCheckIcon()

getMenuItemArrowIcon

public static Icon getMenuItemArrowIcon()

getMenuArrowIcon

public static Icon getMenuArrowIcon()

getCheckBoxIcon

public static Icon getCheckBoxIcon()

getRadioButtonIcon

public static Icon getRadioButtonIcon()

getCheckBoxMenuItemIcon

public static Icon getCheckBoxMenuItemIcon()

getRadioButtonMenuItemIcon

public static Icon getRadioButtonMenuItemIcon()

createEmptyFrameIcon

public static Icon createEmptyFrameIcon()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicInternalFrameTitlePane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicInternalFrameTitlePane

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.plaf.basic.BasicInternalFrameTitlePane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable
Direct Known Subclasses:
MetalInternalFrameTitlePane
public class BasicInternalFrameTitlePane
extends JComponent

The class that manages a basic title bar

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
class | BasicInternalFrameTitlePane.CloseAction This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.IconifyAction This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.MaximizeAction This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.MoveAction This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.PropertyChangeHandler This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.RestoreAction This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.SizeAction This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.SystemMenuBar This class should be treated as a "protected" inner class.
class | BasicInternalFrameTitlePane.TitlePaneLayout This class should be treated as a "protected" inner class.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected static String | CLOSE_CMD
protected Action | closeAction
protected JButton | closeButton
protected Icon | closeIcon
protected JInternalFrame | frame
protected JButton | iconButton
protected Icon | iconIcon
protected static String | ICONIFY_CMD
protected Action | iconifyAction
protected JButton | maxButton
protected Icon | maxIcon
protected static String | MAXIMIZE_CMD
protected Action | maximizeAction
protected JMenuBar | menuBar
protected Icon | minIcon
protected static String | MOVE_CMD
protected Action | moveAction
protected Color | notSelectedTextColor
protected Color | notSelectedTitleColor
protected PropertyChangeListener | propertyChangeListener
protected static String | RESTORE_CMD
protected Action | restoreAction
protected Color | selectedTextColor
protected Color | selectedTitleColor
protected static String | SIZE_CMD
protected Action | sizeAction
protected JMenu | windowMenu
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
BasicInternalFrameTitlePane(JInternalFrame f)
Method Summary
protected void | addSubComponents()
protected void | addSystemMenuItems(JMenu systemMenu)
protected void | assembleSystemMenu()
protected void | createActions()
protected void | createButtons()
protected LayoutManager | createLayout()
protected PropertyChangeListener | createPropertyChangeListener()
protected JMenu | createSystemMenu()
protected JMenuBar | createSystemMenuBar()
protected void | enableActions()
protected String | getTitle(String text, FontMetrics fm, int availTextWidth)
protected void | installDefaults()
protected void | installListeners()
protected void | installTitlePane()
void | paintComponent(Graphics g) Calls the UI delegate's paint method, if the UI delegate is non-null.
protected void | paintTitleBackground(Graphics g) Invoked from paintComponent.
protected void | postClosingEvent(JInternalFrame frame) Post a WINDOW_CLOSING-like event to the frame, so that it can be treated like a regular Frame.
protected void | setButtonIcons()
protected void | showSystemMenu()
protected void | uninstallDefaults()
protected void | uninstallListeners()
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update, updateUI
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

menuBar

protected JMenuBar menuBar

iconButton

protected JButton iconButton

maxButton

protected JButton maxButton

closeButton

protected JButton closeButton

windowMenu

protected JMenu windowMenu

frame

protected JInternalFrame frame

selectedTitleColor

protected Color selectedTitleColor

selectedTextColor

protected Color selectedTextColor

notSelectedTitleColor

protected Color notSelectedTitleColor

notSelectedTextColor

protected Color notSelectedTextColor

maxIcon

protected Icon maxIcon

minIcon

protected Icon minIcon

iconIcon

protected Icon iconIcon

closeIcon

protected Icon closeIcon

propertyChangeListener

protected PropertyChangeListener propertyChangeListener

closeAction

protected Action closeAction

maximizeAction

protected Action maximizeAction

iconifyAction

protected Action iconifyAction

restoreAction

protected Action restoreAction

moveAction

protected Action moveAction

sizeAction

protected Action sizeAction

CLOSE_CMD

protected static final String CLOSE_CMD

ICONIFY_CMD

protected static final String ICONIFY_CMD

RESTORE_CMD

protected static final String RESTORE_CMD

MAXIMIZE_CMD

protected static final String MAXIMIZE_CMD

MOVE_CMD

protected static final String MOVE_CMD

SIZE_CMD

protected static final String SIZE_CMD
Constructor Detail

BasicInternalFrameTitlePane

public BasicInternalFrameTitlePane(JInternalFrame f)
Method Detail

installTitlePane

protected void installTitlePane()

addSubComponents

protected void addSubComponents()

createActions

protected void createActions()

installListeners

protected void installListeners()

uninstallListeners

protected void uninstallListeners()

installDefaults

protected void installDefaults()

uninstallDefaults

protected void uninstallDefaults()

createButtons

protected void createButtons()

setButtonIcons

protected void setButtonIcons()

assembleSystemMenu

protected void assembleSystemMenu()

addSystemMenuItems

protected void addSystemMenuItems(JMenu systemMenu)

createSystemMenu

protected JMenu createSystemMenu()

createSystemMenuBar

protected JMenuBar createSystemMenuBar()

showSystemMenu

protected void showSystemMenu()

paintComponent

public void paintComponent(Graphics g)
Description copied from class: JComponent
Calls the UI delegate's paint method, if the UI delegate is non-null. We pass the delegate a copy of the Graphics object to protect the rest of the paint code from irrevocable changes (for example, Graphics.translate).

If you override this in a subclass you should not make permanent changes to the passed in Graphics. For example, you should not alter the clip Rectangle or modify the transform. If you need to do these operations you may find it easier to create a new Graphics from the passed in Graphics and manipulate it. Further, if you do not invoker super's implementation you must honor the opaque property, that is if this component is opaque, you must completely fill in the background in a non-opaque color. If you do not honor the opaque property you will likely see visual artifacts.

The passed in Graphics object might have a transform other than the identify transform installed on it. In this case, you might get unexpected results if you cumulatively apply another transform.

Overrides:
paintComponent in class JComponent
Parameters:
g - the Graphics object to protect
See Also:
JComponent.paint(java.awt.Graphics), ComponentUI

paintTitleBackground

protected void paintTitleBackground(Graphics g)
Invoked from paintComponent. Paints the background of the titlepane. All text and icons will then be rendered on top of this background.

Parameters:
g - the graphics to use to render the background
Since:
1.4

getTitle

protected String getTitle(String text,
                          FontMetrics fm,
                          int availTextWidth)

postClosingEvent

protected void postClosingEvent(JInternalFrame frame)
Post a WINDOW_CLOSING-like event to the frame, so that it can be treated like a regular Frame.

enableActions

protected void enableActions()

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener()

createLayout

protected LayoutManager createLayout()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicInternalFrameTitlePane.CloseAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicInternalFrameTitlePane.CloseAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicInternalFrameTitlePane.CloseAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicInternalFrameTitlePane
public class BasicInternalFrameTitlePane.CloseAction
extends AbstractAction

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
BasicInternalFrameTitlePane.CloseAction()
Method Summary
 void actionPerformed(ActionEvent e)
Invoked when an action occurs.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicInternalFrameTitlePane.CloseAction

public BasicInternalFrameTitlePane.CloseAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicInternalFrameTitlePane.IconifyAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicInternalFrameTitlePane.IconifyAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicInternalFrameTitlePane.IconifyAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicInternalFrameTitlePane
public class BasicInternalFrameTitlePane.IconifyAction
extends AbstractAction

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
BasicInternalFrameTitlePane.IconifyAction()
Method Summary
 void actionPerformed(ActionEvent e)
Invoked when an action occurs.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicInternalFrameTitlePane.IconifyAction

public BasicInternalFrameTitlePane.IconifyAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicInternalFrameTitlePane.MaximizeAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicInternalFrameTitlePane.MaximizeAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicInternalFrameTitlePane.MaximizeAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicInternalFrameTitlePane
public class BasicInternalFrameTitlePane.MaximizeAction
extends AbstractAction

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
BasicInternalFrameTitlePane.MaximizeAction()
Method Summary
 void actionPerformed(ActionEvent evt)
Invoked when an action occurs.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicInternalFrameTitlePane.MaximizeAction

public BasicInternalFrameTitlePane.MaximizeAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent evt)
Description copied from interface: ActionListener
Invoked when an action occurs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicInternalFrameTitlePane.MoveAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicInternalFrameTitlePane.MoveAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicInternalFrameTitlePane.MoveAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicInternalFrameTitlePane
public class BasicInternalFrameTitlePane.MoveAction
extends AbstractAction

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
BasicInternalFrameTitlePane.MoveAction()
Method Summary
 void actionPerformed(ActionEvent e)
Invoked when an action occurs.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicInternalFrameTitlePane.MoveAction

public BasicInternalFrameTitlePane.MoveAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicInternalFrameTitlePane.PropertyChangeHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicInternalFrameTitlePane.PropertyChangeHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicInternalFrameTitlePane.PropertyChangeHandler
All Implemented Interfaces:
PropertyChangeListener, EventListener
Enclosing class:
BasicInternalFrameTitlePane
public class BasicInternalFrameTitlePane.PropertyChangeHandler
extends Object
implements PropertyChangeListener

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Constructor Summary
BasicInternalFrameTitlePane.PropertyChangeHandler()
Method Summary
 void propertyChange(PropertyChangeEvent evt)
This method gets called when a bound property is changed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicInternalFrameTitlePane.PropertyChangeHandler

public BasicInternalFrameTitlePane.PropertyChangeHandler()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent evt)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
evt - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicInternalFrameTitlePane.RestoreAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicInternalFrameTitlePane.RestoreAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicInternalFrameTitlePane.RestoreAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicInternalFrameTitlePane
public class BasicInternalFrameTitlePane.RestoreAction
extends AbstractAction

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
BasicInternalFrameTitlePane.RestoreAction()
Method Summary
 void actionPerformed(ActionEvent evt)
Invoked when an action occurs.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicInternalFrameTitlePane.RestoreAction

public BasicInternalFrameTitlePane.RestoreAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent evt)
Description copied from interface: ActionListener
Invoked when an action occurs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicInternalFrameTitlePane.SizeAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicInternalFrameTitlePane.SizeAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicInternalFrameTitlePane.SizeAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicInternalFrameTitlePane
public class BasicInternalFrameTitlePane.SizeAction
extends AbstractAction

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
BasicInternalFrameTitlePane.SizeAction()
Method Summary
 void actionPerformed(ActionEvent e)
Invoked when an action occurs.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicInternalFrameTitlePane.SizeAction

public BasicInternalFrameTitlePane.SizeAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicInternalFrameTitlePane.SystemMenuBar

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicInternalFrameTitlePane.SystemMenuBar

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JMenuBar
                    extended by  javax.swing.plaf.basic.BasicInternalFrameTitlePane.SystemMenuBar
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, MenuElement
Enclosing class:
BasicInternalFrameTitlePane
public class BasicInternalFrameTitlePane.SystemMenuBar
extends JMenuBar

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JMenuBar
JMenuBar.AccessibleJMenuBar
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
BasicInternalFrameTitlePane.SystemMenuBar()
Method Summary
boolean | isFocusTraversable() Returns whether this Component can become the focus owner.
boolean | isOpaque() Returns true if this component is completely opaque.
void | paint(Graphics g) Invoked by Swing to draw components.
void | requestFocus() Requests that this Component gets the input focus.
Methods inherited from class javax.swing.JMenuBar
add, addNotify, getAccessibleContext, getComponent, getComponentAtIndex, getComponentIndex, getHelpMenu, getMargin, getMenu, getMenuCount, getSelectionModel, getSubElements, getUI, getUIClassID, isBorderPainted, isSelected, menuSelectionChanged, paintBorder, paramString, processKeyBinding, processKeyEvent, processMouseEvent, removeNotify, setBorderPainted, setHelpMenu, setMargin, setSelected, setSelectionModel, setUI, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

BasicInternalFrameTitlePane.SystemMenuBar

public BasicInternalFrameTitlePane.SystemMenuBar()
Method Detail

isFocusTraversable

public boolean isFocusTraversable()
Description copied from class: Component
Returns whether this Component can become the focus owner.

Overrides:
isFocusTraversable in class Component
Returns:
true if this Component is focusable; false otherwise
See Also:
Component.setFocusable(boolean)

requestFocus

public void requestFocus()
Description copied from class: JComponent
Requests that this Component gets the input focus. Refer to Component.requestFocus() for a complete description of this method.

Note that the use of this method is discouraged because its behavior is platform dependent. Instead we recommend the use of requestFocusInWindow(). If you would like more information on focus, see How to Use the Focus Subsystem, a section in The Java Tutorial.

Overrides:
requestFocus in class JComponent
See Also:
Component.requestFocusInWindow(), Component.requestFocusInWindow(boolean)

paint

public void paint(Graphics g)
Description copied from class: JComponent
Invoked by Swing to draw components. Applications should not invoke paint directly, but should instead use the repaint method to schedule the component for redrawing.

This method actually delegates the work of painting to three protected methods: paintComponent, paintBorder, and paintChildren. They're called in the order listed to ensure that children appear on top of component itself. Generally speaking, the component and its children should not paint in the insets area allocated to the border. Subclasses can just override this method, as always. A subclass that just wants to specialize the UI (look and feel) delegate's paint method should just override paintComponent.

Overrides:
paint in class JComponent
Parameters:
g - the Graphics context in which to paint
See Also:
JComponent.paintComponent(java.awt.Graphics),
JComponent.paintBorder(java.awt.Graphics),
JComponent.paintChildren(java.awt.Graphics),
JComponent.getComponentGraphics(java.awt.Graphics),
JComponent.repaint(long, int, int, int, int)

isOpaque

public boolean isOpaque()
Description copied from class: JComponent
Returns true if this component is completely opaque.

An opaque component paints every pixel within its rectangular bounds. A non-opaque component paints only a subset of its pixels or none at all, allowing the pixels underneath it to "show through". Therefore, a component that does not fully paint its pixels provides a degree of transparency.

Subclasses that guarantee to always completely paint their contents should override this method and return true.

Overrides:
isOpaque in class JComponent
Returns:
true if this component is completely opaque
See Also:
JComponent.setOpaque(boolean)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicInternalFrameTitlePane.TitlePaneLayout

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicInternalFrameTitlePane.TitlePaneLayout

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicInternalFrameTitlePane.TitlePaneLayout
All Implemented Interfaces:
LayoutManager
Enclosing class:
BasicInternalFrameTitlePane
public class BasicInternalFrameTitlePane.TitlePaneLayout
extends Object
implements LayoutManager

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Constructor Summary
BasicInternalFrameTitlePane.TitlePaneLayout()
Method Summary
void | addLayoutComponent(String name, Component c) If the layout manager uses a per-component string, adds the component comp to the layout, associating it with the string specified by name.
void | layoutContainer(Container c) Lays out the specified container.
Dimension | minimumLayoutSize(Container c) Calculates the minimum size dimensions for the specified container, given the components it contains.
Dimension | preferredLayoutSize(Container c) Calculates the preferred size dimensions for the specified container, given the components it contains.
void | removeLayoutComponent(Component c) Removes the specified component from the layout.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicInternalFrameTitlePane.TitlePaneLayout

public BasicInternalFrameTitlePane.TitlePaneLayout()
Method Detail

addLayoutComponent

public void addLayoutComponent(String name,
                               Component c)
Description copied from interface: LayoutManager
If the layout manager uses a per-component string, adds the component comp to the layout, associating it with the string specified by name.

Specified by:
addLayoutComponent in interface LayoutManager
Parameters:
name - the string to be associated with the component
c - the component to be added

removeLayoutComponent

public void removeLayoutComponent(Component c)
Description copied from interface: LayoutManager
Removes the specified component from the layout.

Specified by:
removeLayoutComponent in interface LayoutManager
Parameters:
c - the component to be removed

preferredLayoutSize

public Dimension preferredLayoutSize(Container c)
Description copied from interface: LayoutManager
Calculates the preferred size dimensions for the specified container, given the components it contains.

Specified by:
preferredLayoutSize in interface LayoutManager
Parameters:
c - the container to be laid out
See Also:
LayoutManager.minimumLayoutSize(java.awt.Container)

minimumLayoutSize

public Dimension minimumLayoutSize(Container c)
Description copied from interface: LayoutManager
Calculates the minimum size dimensions for the specified container, given the components it contains.

Specified by:
minimumLayoutSize in interface LayoutManager
Parameters:
c - the component to be laid out
See Also:
LayoutManager.preferredLayoutSize(java.awt.Container)

layoutContainer

public void layoutContainer(Container c)
Description copied from interface: LayoutManager
Lays out the specified container.

Specified by:
layoutContainer in interface LayoutManager
Parameters:
c - the container to be laid out
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicInternalFrameUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicInternalFrameUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.InternalFrameUI
            extended by  javax.swing.plaf.basic.BasicInternalFrameUI
Direct Known Subclasses:
MetalInternalFrameUI
public class BasicInternalFrameUI
extends InternalFrameUI

A basic L&F implementation of JInternalFrame.

Nested Class Summary
protected class | BasicInternalFrameUI.BasicInternalFrameListener
protected class | BasicInternalFrameUI.BorderListener Listens for border adjustments.
protected class | BasicInternalFrameUI.ComponentHandler
protected class | BasicInternalFrameUI.GlassPaneDispatcher
class | BasicInternalFrameUI.InternalFrameLayout
class | BasicInternalFrameUI.InternalFramePropertyChangeListener
Field Summary
protected MouseInputAdapter | borderListener
protected ComponentListener | componentListener
protected JComponent | eastPane
protected JInternalFrame | frame
protected MouseInputListener | glassPaneDispatcher
protected LayoutManager | internalFrameLayout
protected JComponent | northPane
protected KeyStroke | openMenuKey Deprecated. As of Java 2 platform v1.3.
protected PropertyChangeListener | propertyChangeListener
protected JComponent | southPane
protected BasicInternalFrameTitlePane | titlePane
protected JComponent | westPane
Constructor Summary
BasicInternalFrameUI(JInternalFrame b)
Method Summary
protected void | activateFrame(JInternalFrame f) This method is called when the frame becomes selected.
protected void | closeFrame(JInternalFrame f) This method is called when the user wants to close the frame.
protected MouseInputAdapter | createBorderListener(JInternalFrame w)
protected ComponentListener | createComponentListener()
protected DesktopManager | createDesktopManager()
protected JComponent | createEastPane(JInternalFrame w)
protected MouseInputListener | createGlassPaneDispatcher()
protected void | createInternalFrameListener()
protected LayoutManager | createLayoutManager()
protected JComponent | createNorthPane(JInternalFrame w)
protected PropertyChangeListener | createPropertyChangeListener()
protected JComponent | createSouthPane(JInternalFrame w)
static ComponentUI | createUI(JComponent b)
protected JComponent | createWestPane(JInternalFrame w)
protected void | deactivateFrame(JInternalFrame f) This method is called when the frame is no longer selected.
protected void | deiconifyFrame(JInternalFrame f) This method is called when the user wants to deiconify the frame.
protected void | deinstallMouseHandlers(JComponent c)
protected DesktopManager | getDesktopManager() Returns the proper DesktopManager.
JComponent | getEastPane()
Dimension | getMaximumSize(JComponent x) Returns the specified component's maximum size appropriate for the look and feel.
Dimension | getMinimumSize(JComponent x) Returns the specified component's minimum size appropriate for the look and feel.
JComponent | getNorthPane()
Dimension | getPreferredSize(JComponent x) Returns the specified component's preferred size appropriate for the look and feel.
JComponent | getSouthPane()
JComponent | getWestPane()
protected void | iconifyFrame(JInternalFrame f) This method is called when the user wants to iconify the frame.
protected void | installComponents()
protected void | installDefaults()
protected void | installKeyboardActions()
protected void | installListeners()
protected void | installMouseHandlers(JComponent c)
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
boolean | isKeyBindingActive()
protected boolean | isKeyBindingRegistered()
protected void | maximizeFrame(JInternalFrame f) This method is called when the user wants to maximize the frame.
protected void | minimizeFrame(JInternalFrame f) This method is called when the user wants to minimize the frame.
protected void | replacePane(JComponent currentPane, JComponent newPane) Installs necessary mouse handlers on newPane and adds it to the frame.
void | setEastPane(JComponent c)
protected void | setKeyBindingActive(boolean b)
protected void | setKeyBindingRegistered(boolean b)
void | setNorthPane(JComponent c)
void | setSouthPane(JComponent c)
protected void | setupMenuCloseKey()
protected void | setupMenuOpenKey()
void | setWestPane(JComponent c)
protected void | uninstallComponents()
protected void | uninstallDefaults()
protected void | uninstallKeyboardActions()
protected void | uninstallListeners()
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, paint, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

frame

protected JInternalFrame frame

borderListener

protected MouseInputAdapter borderListener

propertyChangeListener

protected PropertyChangeListener propertyChangeListener

internalFrameLayout

protected LayoutManager internalFrameLayout

componentListener

protected ComponentListener componentListener

glassPaneDispatcher

protected MouseInputListener glassPaneDispatcher

northPane

protected JComponent northPane

southPane

protected JComponent southPane

westPane

protected JComponent westPane

eastPane

protected JComponent eastPane

titlePane

protected BasicInternalFrameTitlePane titlePane

openMenuKey

@Deprecated
protected KeyStroke openMenuKey
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

Constructor Detail

BasicInternalFrameUI

public BasicInternalFrameUI(JInternalFrame b)
Method Detail

createUI

public static ComponentUI createUI(JComponent b)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installDefaults

protected void installDefaults()

installKeyboardActions

protected void installKeyboardActions()

installComponents

protected void installComponents()

installListeners

protected void installListeners()
Since:
1.3

uninstallDefaults

protected void uninstallDefaults()

uninstallComponents

protected void uninstallComponents()

uninstallListeners

protected void uninstallListeners()
Since:
1.3

uninstallKeyboardActions

protected void uninstallKeyboardActions()

createLayoutManager

protected LayoutManager createLayoutManager()

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener()

getPreferredSize

public Dimension getPreferredSize(JComponent x)
Description copied from class: ComponentUI
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
x - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent x)
Description copied from class: ComponentUI
Returns the specified component's minimum size appropriate for the look and feel. If null is returned, the minimum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
x - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent x)
Description copied from class: ComponentUI
Returns the specified component's maximum size appropriate for the look and feel. If null is returned, the maximum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
x - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

replacePane

protected void replacePane(JComponent currentPane,
                           JComponent newPane)
Installs necessary mouse handlers on newPane and adds it to the frame. Reverse process for the currentPane.

deinstallMouseHandlers

protected void deinstallMouseHandlers(JComponent c)

installMouseHandlers

protected void installMouseHandlers(JComponent c)

createNorthPane

protected JComponent createNorthPane(JInternalFrame w)

createSouthPane

protected JComponent createSouthPane(JInternalFrame w)

createWestPane

protected JComponent createWestPane(JInternalFrame w)

createEastPane

protected JComponent createEastPane(JInternalFrame w)

createBorderListener

protected MouseInputAdapter createBorderListener(JInternalFrame w)

createInternalFrameListener

protected void createInternalFrameListener()

isKeyBindingRegistered

protected final boolean isKeyBindingRegistered()

setKeyBindingRegistered

protected final void setKeyBindingRegistered(boolean b)

isKeyBindingActive

public final boolean isKeyBindingActive()

setKeyBindingActive

protected final void setKeyBindingActive(boolean b)

setupMenuOpenKey

protected void setupMenuOpenKey()

setupMenuCloseKey

protected void setupMenuCloseKey()

getNorthPane

public JComponent getNorthPane()

setNorthPane

public void setNorthPane(JComponent c)

getSouthPane

public JComponent getSouthPane()

setSouthPane

public void setSouthPane(JComponent c)

getWestPane

public JComponent getWestPane()

setWestPane

public void setWestPane(JComponent c)

getEastPane

public JComponent getEastPane()

setEastPane

public void setEastPane(JComponent c)

getDesktopManager

protected DesktopManager getDesktopManager()
Returns the proper DesktopManager. Calls getDesktopPane() to find the JDesktop component and returns the desktopManager from it. If this fails, it will return a default DesktopManager that should work in arbitrary parents.

createDesktopManager

protected DesktopManager createDesktopManager()

closeFrame

protected void closeFrame(JInternalFrame f)
This method is called when the user wants to close the frame. The playCloseSound Action is fired. This action is delegated to the desktopManager.

maximizeFrame

protected void maximizeFrame(JInternalFrame f)
This method is called when the user wants to maximize the frame. The playMaximizeSound Action is fired. This action is delegated to the desktopManager.

minimizeFrame

protected void minimizeFrame(JInternalFrame f)
This method is called when the user wants to minimize the frame. The playRestoreDownSound Action is fired. This action is delegated to the desktopManager.

iconifyFrame

protected void iconifyFrame(JInternalFrame f)
This method is called when the user wants to iconify the frame. The playMinimizeSound Action is fired. This action is delegated to the desktopManager.

deiconifyFrame

protected void deiconifyFrame(JInternalFrame f)
This method is called when the user wants to deiconify the frame. The playRestoreUpSound Action is fired. This action is delegated to the desktopManager.

activateFrame

protected void activateFrame(JInternalFrame f)
This method is called when the frame becomes selected. This action is delegated to the desktopManager.

deactivateFrame

protected void deactivateFrame(JInternalFrame f)
This method is called when the frame is no longer selected. This action is delegated to the desktopManager.

createComponentListener

protected ComponentListener createComponentListener()

createGlassPaneDispatcher

protected MouseInputListener createGlassPaneDispatcher()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicInternalFrameUI.BasicInternalFrameListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicInternalFrameUI.BasicInternalFrameListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicInternalFrameUI.BasicInternalFrameListener
All Implemented Interfaces:
EventListener, InternalFrameListener
Enclosing class:
BasicInternalFrameUI
protected class BasicInternalFrameUI.BasicInternalFrameListener
extends Object
implements InternalFrameListener

Constructor Summary
protected BasicInternalFrameUI.BasicInternalFrameListener()
Method Summary
void | internalFrameActivated(InternalFrameEvent e) Invoked when an internal frame is activated.
void | internalFrameClosed(InternalFrameEvent e) Invoked when an internal frame has been closed.
void | internalFrameClosing(InternalFrameEvent e) Invoked when an internal frame is in the process of being closed.
void | internalFrameDeactivated(InternalFrameEvent e) Invoked when an internal frame is de-activated.
void | internalFrameDeiconified(InternalFrameEvent e) Invoked when an internal frame is de-iconified.
void | internalFrameIconified(InternalFrameEvent e) Invoked when an internal frame is iconified.
void | internalFrameOpened(InternalFrameEvent e) Invoked when a internal frame has been opened.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicInternalFrameUI.BasicInternalFrameListener

protected BasicInternalFrameUI.BasicInternalFrameListener()
Method Detail

internalFrameClosing

public void internalFrameClosing(InternalFrameEvent e)
Description copied from interface: InternalFrameListener
Invoked when an internal frame is in the process of being closed. The close operation can be overridden at this point.

Specified by:
internalFrameClosing in interface InternalFrameListener
See Also:
JInternalFrame.setDefaultCloseOperation(int)

internalFrameClosed

public void internalFrameClosed(InternalFrameEvent e)
Description copied from interface: InternalFrameListener
Invoked when an internal frame has been closed.

Specified by:
internalFrameClosed in interface InternalFrameListener
See Also:
JInternalFrame.setClosed(boolean)

internalFrameOpened

public void internalFrameOpened(InternalFrameEvent e)
Description copied from interface: InternalFrameListener
Invoked when a internal frame has been opened.

Specified by:
internalFrameOpened in interface InternalFrameListener
See Also:
JInternalFrame.show()

internalFrameIconified

public void internalFrameIconified(InternalFrameEvent e)
Description copied from interface: InternalFrameListener
Invoked when an internal frame is iconified.

Specified by:
internalFrameIconified in interface InternalFrameListener
See Also:
JInternalFrame.setIcon(boolean)

internalFrameDeiconified

public void internalFrameDeiconified(InternalFrameEvent e)
Description copied from interface: InternalFrameListener
Invoked when an internal frame is de-iconified.

Specified by:
internalFrameDeiconified in interface InternalFrameListener
See Also:
JInternalFrame.setIcon(boolean)

internalFrameActivated

public void internalFrameActivated(InternalFrameEvent e)
Description copied from interface: InternalFrameListener
Invoked when an internal frame is activated.

Specified by:
internalFrameActivated in interface InternalFrameListener
See Also:
JInternalFrame.setSelected(boolean)

internalFrameDeactivated

public void internalFrameDeactivated(InternalFrameEvent e)
Description copied from interface: InternalFrameListener
Invoked when an internal frame is de-activated.

Specified by:
internalFrameDeactivated in interface InternalFrameListener
See Also:
JInternalFrame.setSelected(boolean)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicInternalFrameUI.BorderListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicInternalFrameUI.BorderListener

java.lang.Object
    extended by  java.awt.event.MouseAdapter
        extended by  javax.swing.event.MouseInputAdapter
            extended by  javax.swing.plaf.basic.BasicInternalFrameUI.BorderListener
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, EventListener, MouseInputListener, SwingConstants
Enclosing class:
BasicInternalFrameUI
protected class BasicInternalFrameUI.BorderListener
extends MouseInputAdapter
implements SwingConstants

Listens for border adjustments.

Field Summary
protected  int RESIZE_NONE
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
protected BasicInternalFrameUI.BorderListener()
Method Summary
void | mouseClicked(MouseEvent e) Invoked when the mouse button has been clicked (pressed and released) on a component.
void | mouseDragged(MouseEvent e) Invoked when a mouse button is pressed on a component and then dragged.
void | mouseEntered(MouseEvent e) Invoked when the mouse enters a component.
void | mouseExited(MouseEvent e) Invoked when the mouse exits a component.
void | mouseMoved(MouseEvent e) Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.
void | mousePressed(MouseEvent e) Invoked when a mouse button has been pressed on a component.
void | mouseReleased(MouseEvent e) Invoked when a mouse button has been released on a component.
Methods inherited from class java.awt.event.MouseAdapter
mouseWheelMoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

RESIZE_NONE

protected final int RESIZE_NONE
See Also:
Constant Field Values
Constructor Detail

BasicInternalFrameUI.BorderListener

protected BasicInternalFrameUI.BorderListener()
Method Detail

mouseClicked

public void mouseClicked(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when the mouse button has been clicked (pressed and released) on a component.

Specified by:
mouseClicked in interface MouseListener
Overrides:
mouseClicked in class MouseAdapter

mouseReleased

public void mouseReleased(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when a mouse button has been released on a component.

Specified by:
mouseReleased in interface MouseListener
Overrides:
mouseReleased in class MouseAdapter

mousePressed

public void mousePressed(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when a mouse button has been pressed on a component.

Specified by:
mousePressed in interface MouseListener
Overrides:
mousePressed in class MouseAdapter

mouseDragged

public void mouseDragged(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when a mouse button is pressed on a component and then dragged. MOUSE_DRAGGED events will continue to be delivered to the component where the drag originated until the mouse button is released (regardless of whether the mouse position is within the bounds of the component).

Due to platform-dependent Drag&Drop implementations, MOUSE_DRAGGED events may not be delivered during a native Drag&Drop operation.

Specified by:
mouseDragged in interface MouseMotionListener
Overrides:
mouseDragged in class MouseAdapter

mouseMoved

public void mouseMoved(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.

Specified by:
mouseMoved in interface MouseMotionListener
Overrides:
mouseMoved in class MouseAdapter

mouseEntered

public void mouseEntered(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when the mouse enters a component.

Specified by:
mouseEntered in interface MouseListener
Overrides:
mouseEntered in class MouseAdapter

mouseExited

public void mouseExited(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when the mouse exits a component.

Specified by:
mouseExited in interface MouseListener
Overrides:
mouseExited in class MouseAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicInternalFrameUI.ComponentHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicInternalFrameUI.ComponentHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicInternalFrameUI.ComponentHandler
All Implemented Interfaces:
ComponentListener, EventListener
Enclosing class:
BasicInternalFrameUI
protected class BasicInternalFrameUI.ComponentHandler
extends Object
implements ComponentListener

Constructor Summary
protected BasicInternalFrameUI.ComponentHandler()
Method Summary
void | componentHidden(ComponentEvent e) Invoked when the component has been made invisible.
void | componentMoved(ComponentEvent e) Invoked when the component's position changes.
void | componentResized(ComponentEvent e) Invoked when a JInternalFrame's parent's size changes.
void | componentShown(ComponentEvent e) Invoked when the component has been made visible.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicInternalFrameUI.ComponentHandler

protected BasicInternalFrameUI.ComponentHandler()
Method Detail

componentResized

public void componentResized(ComponentEvent e)
Invoked when a JInternalFrame's parent's size changes.

Specified by:
componentResized in interface ComponentListener

componentMoved

public void componentMoved(ComponentEvent e)
Description copied from interface: ComponentListener
Invoked when the component's position changes.

Specified by:
componentMoved in interface ComponentListener

componentShown

public void componentShown(ComponentEvent e)
Description copied from interface: ComponentListener
Invoked when the component has been made visible.

Specified by:
componentShown in interface ComponentListener

componentHidden

public void componentHidden(ComponentEvent e)
Description copied from interface: ComponentListener
Invoked when the component has been made invisible.

Specified by:
componentHidden in interface ComponentListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicInternalFrameUI.GlassPaneDispatcher

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicInternalFrameUI.GlassPaneDispatcher

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicInternalFrameUI.GlassPaneDispatcher
All Implemented Interfaces:
MouseListener, MouseMotionListener, EventListener, MouseInputListener
Enclosing class:
BasicInternalFrameUI
protected class BasicInternalFrameUI.GlassPaneDispatcher
extends Object
implements MouseInputListener

Constructor Summary
protected BasicInternalFrameUI.GlassPaneDispatcher()
Method Summary
void | mouseClicked(MouseEvent e) Invoked when the mouse button has been clicked (pressed and released) on a component.
void | mouseDragged(MouseEvent e) Invoked when a mouse button is pressed on a component and then dragged.
void | mouseEntered(MouseEvent e) Invoked when the mouse enters a component.
void | mouseExited(MouseEvent e) Invoked when the mouse exits a component.
void | mouseMoved(MouseEvent e) Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.
void | mousePressed(MouseEvent e) Invoked when a mouse button has been pressed on a component.
void | mouseReleased(MouseEvent e) Invoked when a mouse button has been released on a component.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicInternalFrameUI.GlassPaneDispatcher

protected BasicInternalFrameUI.GlassPaneDispatcher()
Method Detail

mousePressed

public void mousePressed(MouseEvent e)
Description copied from interface: MouseListener
Invoked when a mouse button has been pressed on a component.

Specified by:
mousePressed in interface MouseListener

mouseEntered

public void mouseEntered(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse enters a component.

Specified by:
mouseEntered in interface MouseListener

mouseMoved

public void mouseMoved(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.

Specified by:
mouseMoved in interface MouseMotionListener

mouseExited

public void mouseExited(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse exits a component.

Specified by:
mouseExited in interface MouseListener

mouseClicked

public void mouseClicked(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse button has been clicked (pressed and released) on a component.

Specified by:
mouseClicked in interface MouseListener

mouseReleased

public void mouseReleased(MouseEvent e)
Description copied from interface: MouseListener
Invoked when a mouse button has been released on a component.

Specified by:
mouseReleased in interface MouseListener

mouseDragged

public void mouseDragged(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when a mouse button is pressed on a component and then dragged. MOUSE_DRAGGED events will continue to be delivered to the component where the drag originated until the mouse button is released (regardless of whether the mouse position is within the bounds of the component).

Due to platform-dependent Drag&Drop implementations, MOUSE_DRAGGED events may not be delivered during a native Drag&Drop operation.

Specified by:
mouseDragged in interface MouseMotionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicInternalFrameUI.InternalFrameLayout

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicInternalFrameUI.InternalFrameLayout

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicInternalFrameUI.InternalFrameLayout
All Implemented Interfaces:
LayoutManager
Enclosing class:
BasicInternalFrameUI
public class BasicInternalFrameUI.InternalFrameLayout
extends Object
implements LayoutManager

Constructor Summary
BasicInternalFrameUI.InternalFrameLayout()
Method Summary
void | addLayoutComponent(String name, Component c) If the layout manager uses a per-component string, adds the component comp to the layout, associating it with the string specified by name.
void | layoutContainer(Container c) Lays out the specified container.
Dimension | minimumLayoutSize(Container c) Calculates the minimum size dimensions for the specified container, given the components it contains.
Dimension | preferredLayoutSize(Container c) Calculates the preferred size dimensions for the specified container, given the components it contains.
void | removeLayoutComponent(Component c) Removes the specified component from the layout.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicInternalFrameUI.InternalFrameLayout

public BasicInternalFrameUI.InternalFrameLayout()
Method Detail

addLayoutComponent

public void addLayoutComponent(String name,
                               Component c)
Description copied from interface: LayoutManager
If the layout manager uses a per-component string, adds the component comp to the layout, associating it with the string specified by name.

Specified by:
addLayoutComponent in interface LayoutManager
Parameters:
name - the string to be associated with the component
c - the component to be added

removeLayoutComponent

public void removeLayoutComponent(Component c)
Description copied from interface: LayoutManager
Removes the specified component from the layout.

Specified by:
removeLayoutComponent in interface LayoutManager
Parameters:
c - the component to be removed

preferredLayoutSize

public Dimension preferredLayoutSize(Container c)
Description copied from interface: LayoutManager
Calculates the preferred size dimensions for the specified container, given the components it contains.

Specified by:
preferredLayoutSize in interface LayoutManager
Parameters:
c - the container to be laid out
See Also:
LayoutManager.minimumLayoutSize(java.awt.Container)

minimumLayoutSize

public Dimension minimumLayoutSize(Container c)
Description copied from interface: LayoutManager
Calculates the minimum size dimensions for the specified container, given the components it contains.

Specified by:
minimumLayoutSize in interface LayoutManager
Parameters:
c - the component to be laid out
See Also:
LayoutManager.preferredLayoutSize(java.awt.Container)

layoutContainer

public void layoutContainer(Container c)
Description copied from interface: LayoutManager
Lays out the specified container.

Specified by:
layoutContainer in interface LayoutManager
Parameters:
c - the container to be laid out
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicInternalFrameUI.InternalFramePropertyChangeListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicInternalFrameUI.InternalFramePropertyChangeListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicInternalFrameUI.InternalFramePropertyChangeListener
All Implemented Interfaces:
PropertyChangeListener, EventListener
Enclosing class:
BasicInternalFrameUI
public class BasicInternalFrameUI.InternalFramePropertyChangeListener
extends Object
implements PropertyChangeListener

Constructor Summary
BasicInternalFrameUI.InternalFramePropertyChangeListener()
Method Summary
 void propertyChange(PropertyChangeEvent evt)
Detects changes in state from the JInternalFrame and handles actions.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicInternalFrameUI.InternalFramePropertyChangeListener

public BasicInternalFrameUI.InternalFramePropertyChangeListener()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent evt)
Detects changes in state from the JInternalFrame and handles actions.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
evt - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicLabelUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicLabelUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.LabelUI
            extended by  javax.swing.plaf.basic.BasicLabelUI
All Implemented Interfaces:
PropertyChangeListener, EventListener
Direct Known Subclasses:
MetalLabelUI
public class BasicLabelUI
extends LabelUI
implements PropertyChangeListener

A Windows L&F implementation of LabelUI. This implementation is completely static, i.e. there's only one UIView implementation that's shared by all JLabel objects.

Field Summary
protected static BasicLabelUI labelUI
The default BasicLabelUI instance.
Constructor Summary
BasicLabelUI()
Method Summary
static ComponentUI createUI(JComponent c)
 int getBaseline(JComponent c, int width, int height)
Returns the baseline.
 Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Dimension getMaximumSize(JComponent c)
Returns the specified component's maximum size appropriate for the look and feel.
 Dimension getMinimumSize(JComponent c)
Returns the specified component's minimum size appropriate for the look and feel.
 Dimension getPreferredSize(JComponent c)
Returns the specified component's preferred size appropriate for the look and feel.
protected  void installComponents(JLabel c)
protected  void installDefaults(JLabel c)
protected  void installKeyboardActions(JLabel l)
protected  void installListeners(JLabel c)
 void installUI(JComponent c)
Configures the specified component appropriate for the look and feel.
protected  String layoutCL(JLabel label, FontMetrics fontMetrics, String text, Icon icon, Rectangle viewR, Rectangle iconR, Rectangle textR)
Forwards the call to SwingUtilities.layoutCompoundLabel().
 void paint(Graphics g, JComponent c)
Paint the label text in the foreground color, if the label is opaque then paint the entire background with the background color.
protected  void paintDisabledText(JLabel l, Graphics g, String s, int textX, int textY)
Paint clippedText at textX, textY with background.lighter() and then shifted down and to the right by one pixel with background.darker().
protected  void paintEnabledText(JLabel l, Graphics g, String s, int textX, int textY)
Paint clippedText at textX, textY with the labels foreground color.
 void propertyChange(PropertyChangeEvent e)
This method gets called when a bound property is changed.
protected  void uninstallComponents(JLabel c)
protected  void uninstallDefaults(JLabel c)
protected  void uninstallKeyboardActions(JLabel c)
protected  void uninstallListeners(JLabel c)
 void uninstallUI(JComponent c)
Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

labelUI

protected static BasicLabelUI labelUI
The default BasicLabelUI instance. This field might not be used. To change the default instance use a subclass which overrides the createUI method, and place that class name in defaults table under the key "LabelUI".

Constructor Detail

BasicLabelUI

public BasicLabelUI()
Method Detail

layoutCL

protected String layoutCL(JLabel label,
                          FontMetrics fontMetrics,
                          String text,
                          Icon icon,
                          Rectangle viewR,
                          Rectangle iconR,
                          Rectangle textR)
Forwards the call to SwingUtilities.layoutCompoundLabel(). This method is here so that a subclass could do Label specific layout and to shorten the method name a little.

See Also:
SwingUtilities.layoutCompoundLabel(javax.swing.JComponent, java.awt.FontMetrics, java.lang.String, javax.swing.Icon, int, int, int, int, java.awt.Rectangle, java.awt.Rectangle, java.awt.Rectangle, int)

paintEnabledText

protected void paintEnabledText(JLabel l,
                                Graphics g,
                                String s,
                                int textX,
                                int textY)
Paint clippedText at textX, textY with the labels foreground color.

See Also:
paint(java.awt.Graphics, javax.swing.JComponent), paintDisabledText(javax.swing.JLabel, java.awt.Graphics, java.lang.String, int, int)

paintDisabledText

protected void paintDisabledText(JLabel l,
                                 Graphics g,
                                 String s,
                                 int textX,
                                 int textY)
Paint clippedText at textX, textY with background.lighter() and then shifted down and to the right by one pixel with background.darker().

See Also:
paint(java.awt.Graphics, javax.swing.JComponent), paintEnabledText(javax.swing.JLabel, java.awt.Graphics, java.lang.String, int, int)

paint

public void paint(Graphics g,
                  JComponent c)
Paint the label text in the foreground color, if the label is opaque then paint the entire background with the background color. The Label text is drawn by paintEnabledText() or paintDisabledText(). The locations of the label parts are computed by layoutCL.

Overrides:
paint in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
paintEnabledText(javax.swing.JLabel, java.awt.Graphics, java.lang.String, int, int), paintDisabledText(javax.swing.JLabel, java.awt.Graphics, java.lang.String, int, int), layoutCL(javax.swing.JLabel, java.awt.FontMetrics, java.lang.String, javax.swing.Icon, java.awt.Rectangle, java.awt.Rectangle, java.awt.Rectangle)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's minimum size appropriate for the look and feel. If null is returned, the minimum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
getPreferredSize(c)
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's maximum size appropriate for the look and feel. If null is returned, the maximum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
getPreferredSize(c)
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getBaseline

public int getBaseline(JComponent c,
                       int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class ComponentUI
Parameters:
c - JComponent baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
NullPointerException - if c is null
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.

Overrides:
getBaselineResizeBehavior in class ComponentUI
Parameters:
c - JComponent to return baseline resize behavior for
Returns:
an enum indicating how the baseline changes as the component size changes
Throws:
NullPointerException - if c is null
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installDefaults

protected void installDefaults(JLabel c)

installListeners

protected void installListeners(JLabel c)

installComponents

protected void installComponents(JLabel c)

installKeyboardActions

protected void installKeyboardActions(JLabel l)

uninstallDefaults

protected void uninstallDefaults(JLabel c)

uninstallListeners

protected void uninstallListeners(JLabel c)

uninstallComponents

protected void uninstallComponents(JLabel c)

uninstallKeyboardActions

protected void uninstallKeyboardActions(JLabel c)

createUI

public static ComponentUI createUI(JComponent c)

propertyChange

public void propertyChange(PropertyChangeEvent e)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicListUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicListUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ListUI
            extended by  javax.swing.plaf.basic.BasicListUI

public class BasicListUI
extends ListUI

An extensible implementation of ListUI.

BasicListUI instances cannot be shared between multiple lists.

Nested Class Summary
class | BasicListUI.FocusHandler This inner class is marked "public" due to a compiler bug.
class | BasicListUI.ListDataHandler The ListDataListener that's added to the JLists model at installUI time, and whenever the JList.model property changes.
class | BasicListUI.ListSelectionHandler The ListSelectionListener that's added to the JLists selection model at installUI time, and whenever the JList.selectionModel property changes.
class | BasicListUI.MouseInputHandler Mouse input, and focus handling for JList.
class | BasicListUI.PropertyChangeHandler The PropertyChangeListener that's added to the JList at installUI time.
Field Summary
protected int | cellHeight
protected int[] | cellHeights
protected static int | cellRendererChanged
protected int | cellWidth
protected static int | fixedCellHeightChanged
protected static int | fixedCellWidthChanged
protected FocusListener | focusListener
protected static int | fontChanged
protected JList | list
protected ListDataListener | listDataListener
protected ListSelectionListener | listSelectionListener
protected static int | modelChanged
protected MouseInputListener | mouseInputListener
protected PropertyChangeListener | propertyChangeListener
protected static int | prototypeCellValueChanged
protected CellRendererPane | rendererPane
protected static int | selectionModelChanged
protected int | updateLayoutStateNeeded
Constructor Summary
BasicListUI()
Method Summary
protected  int convertRowToY(int row)
Return the JList relative Y coordinate of the origin of the specified row or -1 if row isn't valid.
protected  int convertYToRow(int y0)
Convert the JList relative coordinate to the row that contains it, based on the current layout.
protected  FocusListener createFocusListener()
protected  ListDataListener createListDataListener()
Creates an instance of ListDataListener that's added to the JLists by model as needed.
protected  ListSelectionListener createListSelectionListener()
Creates an instance of ListSelectionHandler that's added to the JLists by selectionModel as needed.
protected  MouseInputListener createMouseInputListener()
Creates a delegate that implements MouseInputListener.
protected  PropertyChangeListener createPropertyChangeListener()
Creates an instance of PropertyChangeHandler that's added to the JList by installUI().
static ComponentUI createUI(JComponent list)
Returns a new instance of BasicListUI.
 int getBaseline(JComponent c, int width, int height)
Returns the baseline.
 Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Rectangle getCellBounds(JList list, int index1, int index2)
Returns the bounding rectangle, in the given list's coordinate system, for the range of cells specified by the two indices.
 Dimension getPreferredSize(JComponent c)
The preferredSize of the list depends upon the layout orientation.
protected  int getRowHeight(int row)
Returns the height of the specified row based on the current layout.
 Point indexToLocation(JList list, int index)
Returns the origin in the given JList, of the specified item, in the list's coordinate system.
protected  void installDefaults()
Initialize JList properties, e.g.
protected  void installKeyboardActions()
Registers the keyboard bindings on the JList that the BasicListUI is associated with.
protected  void installListeners()
Create and install the listeners for the JList, its model, and its selectionModel.
 void installUI(JComponent c)
Initializes this.list by calling installDefaults(), installListeners(), and installKeyboardActions() in order.
 int locationToIndex(JList list, Point location)
Returns the cell index in the specified JList closest to the given location in the list's coordinate system.
protected  void maybeUpdateLayoutState()
If updateLayoutStateNeeded is non zero, call updateLayoutState() and reset updateLayoutStateNeeded.
 void paint(Graphics g, JComponent c)
Paint the rows that intersect the Graphics objects clipRect.
protected  void paintCell(Graphics g, int row, Rectangle rowBounds, ListCellRenderer cellRenderer, ListModel dataModel, ListSelectionModel selModel, int leadIndex)
Paint one List cell: compute the relevant state, get the "rubber stamp" cell renderer component, and then use the CellRendererPane to paint it.
protected  void selectNextIndex()
Selected the previous row and force it to be visible.
protected  void selectPreviousIndex()
Selected the previous row and force it to be visible.
protected  void uninstallDefaults()
Set the JList properties that haven't been explicitly overridden to null.
protected  void uninstallKeyboardActions()
Unregisters keyboard actions installed from installKeyboardActions.
protected  void uninstallListeners()
Remove the listeners for the JList, its model, and its selectionModel.
 void uninstallUI(JComponent c)
Uninitializes this.list by calling uninstallListeners(), uninstallKeyboardActions(), and uninstallDefaults() in order.
protected  void updateLayoutState()
Recompute the value of cellHeight or cellHeights based and cellWidth, based on the current font and the current values of fixedCellWidth, fixedCellHeight, and prototypeCellValue.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getMaximumSize, getMinimumSize, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

list

protected JList list

rendererPane

protected CellRendererPane rendererPane

focusListener

protected FocusListener focusListener

mouseInputListener

protected MouseInputListener mouseInputListener

listSelectionListener

protected ListSelectionListener listSelectionListener

listDataListener

protected ListDataListener listDataListener

propertyChangeListener

protected PropertyChangeListener propertyChangeListener

cellHeights

protected int[] cellHeights

cellHeight

protected int cellHeight

cellWidth

protected int cellWidth

updateLayoutStateNeeded

protected int updateLayoutStateNeeded

modelChanged

protected static final int modelChanged
See Also:
Constant Field Values

selectionModelChanged

protected static final int selectionModelChanged
See Also:
Constant Field Values

fontChanged

protected static final int fontChanged
See Also:
Constant Field Values

fixedCellWidthChanged

protected static final int fixedCellWidthChanged
See Also:
Constant Field Values

fixedCellHeightChanged

protected static final int fixedCellHeightChanged
See Also:
Constant Field Values

prototypeCellValueChanged

protected static final int prototypeCellValueChanged
See Also:
Constant Field Values

cellRendererChanged

protected static final int cellRendererChanged
See Also:
Constant Field Values
Constructor Detail

BasicListUI

public BasicListUI()
Method Detail

paintCell

protected void paintCell(Graphics g,
                         int row,
                         Rectangle rowBounds,
                         ListCellRenderer cellRenderer,
                         ListModel dataModel,
                         ListSelectionModel selModel,
                         int leadIndex)
Paint one List cell: compute the relevant state, get the "rubber stamp" cell renderer component, and then use the CellRendererPane to paint it. Subclasses may want to override this method rather than paint().

See Also:
paint(java.awt.Graphics, javax.swing.JComponent)

paint

public void paint(Graphics g,
                  JComponent c)
Paint the rows that intersect the Graphics objects clipRect. This method calls paintCell as necessary. Subclasses may want to override these methods.

Overrides:
paint in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
paintCell(java.awt.Graphics, int, java.awt.Rectangle, javax.swing.ListCellRenderer, javax.swing.ListModel, javax.swing.ListSelectionModel, int)

getBaseline

public int getBaseline(JComponent c,
                       int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class ComponentUI
Parameters:
c - JComponent baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
NullPointerException - if c is null
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.

Overrides:
getBaselineResizeBehavior in class ComponentUI
Parameters:
c - JComponent to return baseline resize behavior for
Returns:
an enum indicating how the baseline changes as the component size changes
Throws:
NullPointerException - if c is null
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
The preferredSize of the list depends upon the layout orientation.
Layout Orientation | Preferred Size
JList.VERTICAL | The preferredSize of the list is total height of the rows and the maximum width of the cells. If JList.fixedCellHeight is specified then the total height of the rows is just (cellVerticalMargins + fixedCellHeight) * model.getSize() where rowVerticalMargins is the space we allocate for drawing the yellow focus outline. Similarly if fixedCellWidth is specified then we just use that.
JList.VERTICAL_WRAP If the visible row count is greater than zero, the preferredHeight is the maximum cell height * visibleRowCount. If the visible row count is <= 0,="0," the="the" preferred="preferred" height="height" is="is" either="either" the="the" current="current" height="height" of="of" the="the" list,="list," or="or" the="the" maximum="maximum" cell="cell" height,="height," whichever="whichever" is="is" bigger.="bigger." The="The" preferred="preferred" width="width" is="is" than="than" the="the" maximum="maximum" cell="cell" width="width" *="*" number="number" of="of" columns="columns" needed.="needed." Where="Where" the="the" number="number" of="of" columns="columns" needs="needs" is="is" list.height="list.height" /="/" max="max" cell="cell" height.="height." Max="Max" cell="cell" height="height" is="is" either="either" the="the" fixed="fixed" cell="cell" height,="height," or="or" is="is" determined="determined" by="by" iterating="iterating" through="through" all="all" the="the" cells="cells" to="to" find="find" the="the" maximum="maximum" height="height" from="from" the="the" ListCellRenderer.="ListCellRenderer." JList.HORIZONTAL_WRAP If the visible row count is greater than zero, the preferredHeight is the maximum cell height * adjustedRowCount. Where visibleRowCount is used to determine the number of columns. Because this lays out horizontally the number of rows is then determined from the column count. For example, lets say you have a model with 10 items and the visible row count is 8. The number of columns needed to display this is 2, but you no longer need 8 rows to display this, you only need 5, thus the adjustedRowCount is 5.

If the visible row count is <= 0,="0," the="the" preferred="preferred" height="height" is="is" dictated="dictated" by="by" the="the" number="number" of="of" columns,="columns," which="which" will="will" be="be" as="as" many="many" as="as" can="can" fit="fit" in="in" the="the" width="width" of="of" the="the" JList (width / max cell width), with at least one column. The preferred height then becomes the model size / number of columns * maximum cell height. Max cell height is either the fixed cell height, or is determined by iterating through all the cells to find the maximum height from the ListCellRenderer.

The above specifies the raw preferred width and height. The resulting preferred width is the above width + insets.left + insets.right and the resulting preferred height is the above height + insets.top + insets.bottom. Where the Insets are determined from list.getInsets().

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - The JList component.
Returns:
The total size of the list.
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

selectPreviousIndex

protected void selectPreviousIndex()
Selected the previous row and force it to be visible.

See Also:
JList.ensureIndexIsVisible(int)

selectNextIndex

protected void selectNextIndex()
Selected the previous row and force it to be visible.

See Also:
JList.ensureIndexIsVisible(int)

installKeyboardActions

protected void installKeyboardActions()
Registers the keyboard bindings on the JList that the BasicListUI is associated with. This method is called at installUI() time.

See Also:
installUI(javax.swing.JComponent)

uninstallKeyboardActions

protected void uninstallKeyboardActions()
Unregisters keyboard actions installed from installKeyboardActions. This method is called at uninstallUI() time - subclassess should ensure that all of the keyboard actions registered at installUI time are removed here.

See Also:
installUI(javax.swing.JComponent)

installListeners

protected void installListeners()
Create and install the listeners for the JList, its model, and its selectionModel. This method is called at installUI() time.

See Also:
installUI(javax.swing.JComponent), uninstallListeners()

uninstallListeners

protected void uninstallListeners()
Remove the listeners for the JList, its model, and its selectionModel. All of the listener fields, are reset to null here. This method is called at uninstallUI() time, it should be kept in sync with installListeners.

See Also:
uninstallUI(javax.swing.JComponent), installListeners()

installDefaults

protected void installDefaults()
Initialize JList properties, e.g. font, foreground, and background, and add the CellRendererPane. The font, foreground, and background properties are only set if their current value is either null or a UIResource, other properties are set if the current value is null.

See Also:
uninstallDefaults(), installUI(javax.swing.JComponent), CellRendererPane

uninstallDefaults

protected void uninstallDefaults()
Set the JList properties that haven't been explicitly overridden to null. A property is considered overridden if its current value is not a UIResource.

See Also:
installDefaults(), uninstallUI(javax.swing.JComponent), CellRendererPane

installUI

public void installUI(JComponent c)
Initializes this.list by calling installDefaults(), installListeners(), and installKeyboardActions() in order.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
installDefaults(),
installListeners(),
installKeyboardActions()

uninstallUI

public void uninstallUI(JComponent c)
Uninitializes this.list by calling uninstallListeners(), uninstallKeyboardActions(), and uninstallDefaults() in order. Sets this.list to null.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
uninstallListeners(),
uninstallKeyboardActions(),
uninstallDefaults()

createUI

public static ComponentUI createUI(JComponent list)
Returns a new instance of BasicListUI. BasicListUI delegates are allocated one per JList.

Returns:
A new ListUI implementation for the Windows look and feel.

locationToIndex

public int locationToIndex(JList list,
                           Point location)
Returns the cell index in the specified JList closest to the given location in the list's coordinate system. To determine if the cell actually contains the specified location, compare the point against the cell's bounds, as provided by getCellBounds. This method returns -1 if the list's model is empty.

Specified by:
locationToIndex in class ListUI
Parameters:
list - the list
location - the coordinates of the point
Returns:
the cell index closest to the given location, or -1
Throws:
NullPointerException - if location is null

indexToLocation

public Point indexToLocation(JList list,
                             int index)
Returns the origin in the given JList, of the specified item, in the list's coordinate system. Returns null if the index isn't valid.

Specified by:
indexToLocation in class ListUI
Parameters:
list - the list
index - the cell index
Returns:
the origin of the cell, or null

getCellBounds

public Rectangle getCellBounds(JList list,
                               int index1,
                               int index2)
Returns the bounding rectangle, in the given list's coordinate system, for the range of cells specified by the two indices. The indices can be supplied in any order.

If the smaller index is outside the list's range of cells, this method returns null. If the smaller index is valid, but the larger index is outside the list's range, the bounds of just the first index is returned. Otherwise, the bounds of the valid range is returned.

Specified by:
getCellBounds in class ListUI
Parameters:
list - the list
index1 - the first index in the range
index2 - the second index in the range
Returns:
the bounding rectangle for the range of cells, or null

getRowHeight

protected int getRowHeight(int row)
Returns the height of the specified row based on the current layout.

Returns:
The specified row height or -1 if row isn't valid.
See Also:
convertYToRow(int), convertRowToY(int), updateLayoutState()

convertYToRow

protected int convertYToRow(int y0)
Convert the JList relative coordinate to the row that contains it, based on the current layout. If y0 doesn't fall within any row, return -1.

Returns:
The row that contains y0, or -1.
See Also:
getRowHeight(int), updateLayoutState()

convertRowToY

protected int convertRowToY(int row)
Return the JList relative Y coordinate of the origin of the specified row or -1 if row isn't valid.

Returns:
The Y coordinate of the origin of row, or -1.
See Also:
getRowHeight(int), updateLayoutState()

maybeUpdateLayoutState

protected void maybeUpdateLayoutState()
If updateLayoutStateNeeded is non zero, call updateLayoutState() and reset updateLayoutStateNeeded. This method should be called by methods before doing any computation based on the geometry of the list. For example it's the first call in paint() and getPreferredSize().

See Also:
updateLayoutState()

updateLayoutState

protected void updateLayoutState()
Recompute the value of cellHeight or cellHeights based and cellWidth, based on the current font and the current values of fixedCellWidth, fixedCellHeight, and prototypeCellValue.

See Also:
maybeUpdateLayoutState()

createMouseInputListener

protected MouseInputListener createMouseInputListener()
Creates a delegate that implements MouseInputListener. The delegate is added to the corresponding java.awt.Component listener lists at installUI() time. Subclasses can override this method to return a custom MouseInputListener, e.g.
 class MyListUI extends BasicListUI {
    protected MouseInputListener createMouseInputListener() {
        return new MyMouseInputHandler();
    }
    public class MyMouseInputHandler extends MouseInputHandler {
        public void mouseMoved(MouseEvent e) {
            // do some extra work when the mouse moves
            super.mouseMoved(e);
        }
    }
 }

See Also:
BasicListUI.MouseInputHandler, installUI(javax.swing.JComponent)

createFocusListener

protected FocusListener createFocusListener()

createListSelectionListener

protected ListSelectionListener createListSelectionListener()
Creates an instance of ListSelectionHandler that's added to the JLists by selectionModel as needed. Subclasses can override this method to return a custom ListSelectionListener, e.g.
 class MyListUI extends BasicListUI {
    protected ListSelectionListener createListSelectionListener() {
        return new MySelectionListener();
    }
    public class MySelectionListener extends ListSelectionHandler {
        public void valueChanged(ListSelectionEvent e) {
            // do some extra work when the selection changes
            super.valueChange(e);
        }
    }
 }

See Also:
BasicListUI.ListSelectionHandler, installUI(javax.swing.JComponent)

createListDataListener

protected ListDataListener createListDataListener()
Creates an instance of ListDataListener that's added to the JLists by model as needed. Subclasses can override this method to return a custom ListDataListener, e.g.
 class MyListUI extends BasicListUI {
    protected ListDataListener createListDataListener() {
        return new MyListDataListener();
    }
    public class MyListDataListener extends ListDataHandler {
        public void contentsChanged(ListDataEvent e) {
            // do some extra work when the models contents change
            super.contentsChange(e);
        }
    }
 }

See Also:
ListDataListener, JList.getModel(), installUI(javax.swing.JComponent)

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener()
Creates an instance of PropertyChangeHandler that's added to the JList by installUI(). Subclasses can override this method to return a custom PropertyChangeListener, e.g.
 class MyListUI extends BasicListUI {
    protected PropertyChangeListener createPropertyChangeListener() {
        return new MyPropertyChangeListener();
    }
    public class MyPropertyChangeListener extends PropertyChangeHandler {
        public void propertyChange(PropertyChangeEvent e) {
            if (e.getPropertyName().equals("model")) {
                // do some extra work when the model changes
            }
            super.propertyChange(e);
        }
    }
 }

See Also:
PropertyChangeListener, installUI(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicListUI.FocusHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicListUI.FocusHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicListUI.FocusHandler
All Implemented Interfaces:
FocusListener, EventListener
Enclosing class:
BasicListUI
public class BasicListUI.FocusHandler
extends Object
implements FocusListener

This inner class is marked "public" due to a compiler bug. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicTableUI.

Constructor Summary
BasicListUI.FocusHandler()
Method Summary
void | focusGained(FocusEvent e) Invoked when a component gains the keyboard focus.
void | focusLost(FocusEvent e) Invoked when a component loses the keyboard focus.
protected void | repaintCellFocus()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicListUI.FocusHandler

public BasicListUI.FocusHandler()
Method Detail

repaintCellFocus

protected void repaintCellFocus()

focusGained

public void focusGained(FocusEvent e)
Description copied from interface: FocusListener
Invoked when a component gains the keyboard focus.

Specified by:
focusGained in interface FocusListener

focusLost

public void focusLost(FocusEvent e)
Description copied from interface: FocusListener
Invoked when a component loses the keyboard focus.

Specified by:
focusLost in interface FocusListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicListUI.ListDataHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicListUI.ListDataHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicListUI.ListDataHandler
All Implemented Interfaces:
EventListener, ListDataListener
Enclosing class:
BasicListUI
public class BasicListUI.ListDataHandler
extends Object
implements ListDataListener

The ListDataListener that's added to the JLists model at installUI time, and whenever the JList.model property changes.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JList.getModel(),
BasicListUI.maybeUpdateLayoutState(),
BasicListUI.createListDataListener(),
BasicListUI.installUI(javax.swing.JComponent)

Constructor Summary
BasicListUI.ListDataHandler()
Method Summary
void | contentsChanged(ListDataEvent e) Sent when the contents of the list has changed in a way that's too complex to characterize with the previous methods.
void | intervalAdded(ListDataEvent e) Sent after the indices in the index0,index1 interval have been inserted in the data model.
void | intervalRemoved(ListDataEvent e) Sent after the indices in the index0,index1 interval have been removed from the data model.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicListUI.ListDataHandler

public BasicListUI.ListDataHandler()
Method Detail

intervalAdded

public void intervalAdded(ListDataEvent e)
Description copied from interface: ListDataListener
Sent after the indices in the index0,index1 interval have been inserted in the data model. The new interval includes both index0 and index1.

Specified by:
intervalAdded in interface ListDataListener
Parameters:
e - a ListDataEvent encapsulating the event information

intervalRemoved

public void intervalRemoved(ListDataEvent e)
Description copied from interface: ListDataListener
Sent after the indices in the index0,index1 interval have been removed from the data model. The interval includes both index0 and index1.

Specified by:
intervalRemoved in interface ListDataListener
Parameters:
e - a ListDataEvent encapsulating the event information

contentsChanged

public void contentsChanged(ListDataEvent e)
Description copied from interface: ListDataListener
Sent when the contents of the list has changed in a way that's too complex to characterize with the previous methods. For example, this is sent when an item has been replaced. Index0 and index1 bracket the change.

Specified by:
contentsChanged in interface ListDataListener
Parameters:
e - a ListDataEvent encapsulating the event information
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicListUI.ListSelectionHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicListUI.ListSelectionHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicListUI.ListSelectionHandler
All Implemented Interfaces:
EventListener, ListSelectionListener
Enclosing class:
BasicListUI
public class BasicListUI.ListSelectionHandler
extends Object
implements ListSelectionListener

The ListSelectionListener that's added to the JLists selection model at installUI time, and whenever the JList.selectionModel property changes. When the selection changes we repaint the affected rows.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
BasicListUI.createListSelectionListener(),
BasicListUI.getCellBounds(javax.swing.JList, int, int),
BasicListUI.installUI(javax.swing.JComponent)

Constructor Summary
BasicListUI.ListSelectionHandler()
Method Summary
 void valueChanged(ListSelectionEvent e)
Called whenever the value of the selection changes.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicListUI.ListSelectionHandler

public BasicListUI.ListSelectionHandler()
Method Detail

valueChanged

public void valueChanged(ListSelectionEvent e)
Description copied from interface: ListSelectionListener
Called whenever the value of the selection changes.

Specified by:
valueChanged in interface ListSelectionListener
Parameters:
e - the event that characterizes the change.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicListUI.MouseInputHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicListUI.MouseInputHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicListUI.MouseInputHandler
All Implemented Interfaces:
MouseListener, MouseMotionListener, EventListener, MouseInputListener
Enclosing class:
BasicListUI
public class BasicListUI.MouseInputHandler
extends Object
implements MouseInputListener

Mouse input, and focus handling for JList. An instance of this class is added to the appropriate java.awt.Component lists at installUI() time. Note keyboard input is handled with JComponent KeyboardActions, see installKeyboardActions().

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
BasicListUI.createMouseInputListener(),
BasicListUI.installKeyboardActions(),
BasicListUI.installUI(javax.swing.JComponent)

Constructor Summary
BasicListUI.MouseInputHandler()
Method Summary
void | mouseClicked(MouseEvent e) Invoked when the mouse button has been clicked (pressed and released) on a component.
void | mouseDragged(MouseEvent e) Invoked when a mouse button is pressed on a component and then dragged.
void | mouseEntered(MouseEvent e) Invoked when the mouse enters a component.
void | mouseExited(MouseEvent e) Invoked when the mouse exits a component.
void | mouseMoved(MouseEvent e) Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.
void | mousePressed(MouseEvent e) Invoked when a mouse button has been pressed on a component.
void | mouseReleased(MouseEvent e) Invoked when a mouse button has been released on a component.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicListUI.MouseInputHandler

public BasicListUI.MouseInputHandler()
Method Detail

mouseClicked

public void mouseClicked(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse button has been clicked (pressed and released) on a component.

Specified by:
mouseClicked in interface MouseListener

mouseEntered

public void mouseEntered(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse enters a component.

Specified by:
mouseEntered in interface MouseListener

mouseExited

public void mouseExited(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse exits a component.

Specified by:
mouseExited in interface MouseListener

mousePressed

public void mousePressed(MouseEvent e)
Description copied from interface: MouseListener
Invoked when a mouse button has been pressed on a component.

Specified by:
mousePressed in interface MouseListener

mouseDragged

public void mouseDragged(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when a mouse button is pressed on a component and then dragged. MOUSE_DRAGGED events will continue to be delivered to the component where the drag originated until the mouse button is released (regardless of whether the mouse position is within the bounds of the component).

Due to platform-dependent Drag&Drop implementations, MOUSE_DRAGGED events may not be delivered during a native Drag&Drop operation.

Specified by:
mouseDragged in interface MouseMotionListener

mouseMoved

public void mouseMoved(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.

Specified by:
mouseMoved in interface MouseMotionListener

mouseReleased

public void mouseReleased(MouseEvent e)
Description copied from interface: MouseListener
Invoked when a mouse button has been released on a component.

Specified by:
mouseReleased in interface MouseListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicListUI.PropertyChangeHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicListUI.PropertyChangeHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicListUI.PropertyChangeHandler
All Implemented Interfaces:
PropertyChangeListener, EventListener
Enclosing class:
BasicListUI
public class BasicListUI.PropertyChangeHandler
extends Object
implements PropertyChangeListener

The PropertyChangeListener that's added to the JList at installUI time. When the value of a JList property that affects layout changes, we set a bit in updateLayoutStateNeeded. If the JLists model changes we additionally remove our listeners from the old model. Likewise for the JList selectionModel.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
BasicListUI.maybeUpdateLayoutState(),
BasicListUI.createPropertyChangeListener(),
BasicListUI.installUI(javax.swing.JComponent)

Constructor Summary
BasicListUI.PropertyChangeHandler()
Method Summary
 void propertyChange(PropertyChangeEvent e)
This method gets called when a bound property is changed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicListUI.PropertyChangeHandler

public BasicListUI.PropertyChangeHandler()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicLookAndFeel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicLookAndFeel

java.lang.Object
    extended by  javax.swing.LookAndFeel
        extended by  javax.swing.plaf.basic.BasicLookAndFeel
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
MetalLookAndFeel, SynthLookAndFeel
public abstract class BasicLookAndFeel
extends LookAndFeel
implements Serializable

A base class to use in creating a look and feel for Swing.

Each of the ComponentUIs provided by BasicLookAndFeel derives its behavior from the defaults table. Unless otherwise noted each of the ComponentUI implementations in this package document the set of defaults they use. Unless otherwise noted the defaults are installed at the time installUI is invoked, and follow the recommendations outlined in LookAndFeel for installing defaults.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
BasicLookAndFeel()
Method Summary
protected Action | createAudioAction(Object key) Creates and returns an Action used to play a sound.
protected ActionMap | getAudioActionMap() Returns an ActionMap containing the audio actions for this look and feel.
UIDefaults | getDefaults() Returns the look and feel defaults.
protected void | initClassDefaults(UIDefaults table) Populates table with mappings from uiClassID to the fully qualified name of the ui class.
protected void | initComponentDefaults(UIDefaults table) Populates table with the defaults for the basic look and feel.
void | initialize() Initializes the look and feel.
protected void | initSystemColorDefaults(UIDefaults table) Populates table with system colors.
protected void | loadSystemColors(UIDefaults table, String[] systemColors, boolean useNative) Populates table with the name-color pairs in systemColors.
protected void | playSound(Action audioAction) If necessary, invokes actionPerformed on audioAction to play a sound.
void | uninitialize() Uninitializes the look and feel.
Methods inherited from class javax.swing.LookAndFeel
getDescription, getDesktopPropertyValue, getDisabledIcon, getDisabledSelectedIcon, getID, getLayoutStyle, getName, getSupportsWindowDecorations, installBorder, installColors, installColorsAndFont, installProperty, isNativeLookAndFeel, isSupportedLookAndFeel, loadKeyBindings, makeComponentInputMap, makeIcon, makeInputMap, makeKeyBindings, provideErrorFeedback, toString, uninstallBorder
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

BasicLookAndFeel

public BasicLookAndFeel()
Method Detail

getDefaults

public UIDefaults getDefaults()
Returns the look and feel defaults. The returned UIDefaults is populated by invoking, in order, initClassDefaults, initSystemColorDefaults and initComponentDefaults.

While this method is public, it should only be invoked by the UIManager when the look and feel is set as the current look and feel and after initialize has been invoked.

Overrides:
getDefaults in class LookAndFeel
Returns:
the look and feel defaults
See Also:
initClassDefaults(javax.swing.UIDefaults),
initSystemColorDefaults(javax.swing.UIDefaults),
initComponentDefaults(javax.swing.UIDefaults)

initialize

public void initialize()
Initializes the look and feel. While this method is public, it should only be invoked by the UIManager when a look and feel is installed as the current look and feel. This method is invoked before the UIManager invokes getDefaults. This method is intended to perform any initialization for the look and feel. Subclasses should do any one-time setup they need here, rather than in a static initializer, because look and feel class objects may be loaded just to discover that isSupportedLookAndFeel() returns false.

Overrides:
initialize in class LookAndFeel
See Also:
LookAndFeel.uninitialize(), UIManager.setLookAndFeel(javax.swing.LookAndFeel)

uninitialize

public void uninitialize()
Uninitializes the look and feel. While this method is public, it should only be invoked by the UIManager when the look and feel is uninstalled. For example, UIManager.setLookAndFeel invokes this when the look and feel is changed.

Subclasses may choose to free up some resources here.

Overrides:
uninitialize in class LookAndFeel
See Also:
LookAndFeel.initialize(), UIManager.setLookAndFeel(javax.swing.LookAndFeel)

initClassDefaults

protected void initClassDefaults(UIDefaults table)
Populates table with mappings from uiClassID to the fully qualified name of the ui class. The value for a particular uiClassID is "javax.swing.plaf.basic.Basic + uiClassID". For example, the value for the uiClassID TreeUI is "javax.swing.plaf.basic.BasicTreeUI".

Parameters:
table - the UIDefaults instance the entries are added to
Throws:
NullPointerException - if table is null
See Also:
LookAndFeel, getDefaults()

initSystemColorDefaults

protected void initSystemColorDefaults(UIDefaults table)
Populates table with system colors. This creates an array of name-color pairs and invokes loadSystemColors.

The name is a String that corresponds to the name of one of the static SystemColor fields in the SystemColor class. A name-color pair is created for every such SystemColor field.

The color corresponds to a hex String as understood by Color.decode. For example, one of the name-color pairs is "desktop"-"#005C5C". This corresponds to the SystemColor field desktop, with a color value of new Color(0x005C5C).

The following shows two of the name-color pairs:

   String[] nameColorPairs = new String[] {
          "desktop", "#005C5C",
    "activeCaption", "#000080" };
   loadSystemColors(table, nameColorPairs, isNativeLookAndFeel());
As previously stated, this invokes loadSystemColors with the supplied table and name-color pair array. The last argument to loadSystemColors indicates whether the value of the field in SystemColor should be used. This method passes the value of isNativeLookAndFeel() as the last argument to loadSystemColors.

Parameters:
table - the UIDefaults object the values are added to
Throws:
NullPointerException - if table is null
See Also:
SystemColor, getDefaults(), loadSystemColors(javax.swing.UIDefaults, java.lang.String[], boolean)

loadSystemColors

protected void loadSystemColors(UIDefaults table,
                                String[] systemColors,
                                boolean useNative)
Populates table with the name-color pairs in systemColors. Refer to initSystemColorDefaults(UIDefaults) for details on the format of systemColors.

An entry is added to table for each of the name-color pairs in systemColors. The entry key is the name of the name-color pair.

The value of the entry corresponds to the color of the name-color pair. The value of the entry is calculated in one of two ways. With either approach the value is always a ColorUIResource.

If useNative is false, the color is created by using Color.decode to convert the String into a Color. If decode can not convert the String into a Color (NumberFormatException is thrown) then a ColorUIResource of black is used.

If useNative is true, the color is the value of the field in SystemColor with the same name as the name of the name-color pair. If the field is not valid, a ColorUIResource of black is used.

Parameters:
table - the UIDefaults object the values are added to
systemColors - array of name-color pairs as described in initSystemColorDefaults(UIDefaults)
useNative - whether the color is obtained from SystemColor or Color.decode
Throws:
NullPointerException - if systemColors is null; or systemColors is not empty, and table is null; or one of the names of the name-color pairs is null; or useNative is false and one of the colors of the name-color pairs is null
ArrayIndexOutOfBoundsException - if useNative is false and systemColors.length is odd
See Also:
initSystemColorDefaults(javax.swing.UIDefaults), SystemColor, Color.decode(String)

initComponentDefaults

protected void initComponentDefaults(UIDefaults table)
Populates table with the defaults for the basic look and feel.

Parameters:
table - the UIDefaults to add the values to
Throws:
NullPointerException - if table is null

getAudioActionMap

protected ActionMap getAudioActionMap()
Returns an ActionMap containing the audio actions for this look and feel.

The returned ActionMap contains Actions that embody the ability to render an auditory cue. These auditory cues map onto user and system activities that may be useful for an end user to know about (such as a dialog box appearing).

At the appropriate time, the ComponentUI is responsible for obtaining an Action out of the ActionMap and passing it to playSound.

This method first looks up the ActionMap from the defaults using the key "AuditoryCues.actionMap".

If the value is non-null, it is returned. If the value of the default "AuditoryCues.actionMap" is null and the value of the default "AuditoryCues.cueList" is non-null, an ActionMapUIResource is created and populated. Population is done by iterating over each of the elements of the "AuditoryCues.cueList" array, and invoking createAudioAction() to create an Action for each element. The resulting Action is placed in the ActionMapUIResource, using the array element as the key. For example, if the "AuditoryCues.cueList" array contains a single-element, "audioKey", the ActionMapUIResource is created, then populated by way of actionMap.put(cueList[0], createAudioAction(cueList[0])).

If the value of the default "AuditoryCues.actionMap" is null and the value of the default "AuditoryCues.cueList" is null, an empty ActionMapUIResource is created.

Returns:
an ActionMap containing Actions responsible for playing auditory cues
Throws:
ClassCastException - if the value of the default "AuditoryCues.actionMap" is not an ActionMap, or the value of the default "AuditoryCues.cueList" is not an Object[]
Since:
1.4
See Also:
createAudioAction(java.lang.Object), playSound(Action)

createAudioAction

protected Action createAudioAction(Object key)
Creates and returns an Action used to play a sound.

If key is non-null, an Action is created using the value from the defaults with key key. The value identifies the sound resource to load when actionPerformed is invoked on the Action. The sound resource is loaded into a byte[] by way of getClass().getResourceAsStream().

Parameters:
key - the key identifying the audio action
Returns:
an Action used to play the source, or null if key is null
Since:
1.4
See Also:
playSound(Action)

playSound

protected void playSound(Action audioAction)
If necessary, invokes actionPerformed on audioAction to play a sound. The actionPerformed method is invoked if the value of the "AuditoryCues.playList" default is a non-null Object[] containing a String entry equal to the name of the audioAction.

Parameters:
audioAction - an Action that knows how to render the audio associated with the system or user activity that is occurring; a value of null, is ignored
Throws:
ClassCastException - if audioAction is non-null and the value of the default "AuditoryCues.playList" is not an Object[]
Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicMenuBarUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicMenuBarUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.MenuBarUI
            extended by  javax.swing.plaf.basic.BasicMenuBarUI
Direct Known Subclasses:
MetalMenuBarUI
public class BasicMenuBarUI
extends MenuBarUI

A default L&F implementation of MenuBarUI. This implementation is a "combined" view/controller.

Field Summary
protected ChangeListener | changeListener
protected ContainerListener | containerListener
protected JMenuBar | menuBar
Constructor Summary
BasicMenuBarUI()
Method Summary
protected ChangeListener | createChangeListener()
protected ContainerListener | createContainerListener()
static ComponentUI | createUI(JComponent x)
Dimension | getMaximumSize(JComponent c) Returns the specified component's maximum size appropriate for the look and feel.
Dimension | getMinimumSize(JComponent c) Returns the specified component's minimum size appropriate for the look and feel.
protected void | installDefaults()
protected void | installKeyboardActions()
protected void | installListeners()
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
protected void | uninstallDefaults()
protected void | uninstallKeyboardActions()
protected void | uninstallListeners()
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getPreferredSize, paint, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

menuBar

protected JMenuBar menuBar

containerListener

protected ContainerListener containerListener

changeListener

protected ChangeListener changeListener
Constructor Detail

BasicMenuBarUI

public BasicMenuBarUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent x)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

installDefaults

protected void installDefaults()

installListeners

protected void installListeners()

installKeyboardActions

protected void installKeyboardActions()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

uninstallDefaults

protected void uninstallDefaults()

uninstallListeners

protected void uninstallListeners()

uninstallKeyboardActions

protected void uninstallKeyboardActions()

createContainerListener

protected ContainerListener createContainerListener()

createChangeListener

protected ChangeListener createChangeListener()

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's minimum size appropriate for the look and feel. If null is returned, the minimum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's maximum size appropriate for the look and feel. If null is returned, the maximum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicMenuItemUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicMenuItemUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ButtonUI
            extended by  javax.swing.plaf.MenuItemUI
                extended by  javax.swing.plaf.basic.BasicMenuItemUI
Direct Known Subclasses:
BasicCheckBoxMenuItemUI, BasicMenuUI, BasicRadioButtonMenuItemUI
public class BasicMenuItemUI
extends MenuItemUI

BasicMenuItem implementation

Nested Class Summary
protected  class BasicMenuItemUI.MouseInputHandler
Field Summary
protected Font | acceleratorFont
protected Color | acceleratorForeground
protected Color | acceleratorSelectionForeground
protected Icon | arrowIcon
protected Icon | checkIcon
protected int | defaultTextIconGap
protected Color | disabledForeground
protected MenuDragMouseListener | menuDragMouseListener
protected JMenuItem | menuItem
protected MenuKeyListener | menuKeyListener
protected MouseInputListener | mouseInputListener
protected boolean | oldBorderPainted
protected PropertyChangeListener | propertyChangeListener PropertyChangeListener returned from createPropertyChangeListener.
protected Color | selectionBackground
protected Color | selectionForeground
Constructor Summary
BasicMenuItemUI()
Method Summary
protected  MenuDragMouseListener createMenuDragMouseListener(JComponent c)
protected  MenuKeyListener createMenuKeyListener(JComponent c)
protected  MouseInputListener createMouseInputListener(JComponent c)
protected  PropertyChangeListener createPropertyChangeListener(JComponent c)
Creates a PropertyChangeListener which will be added to the menu item.
static ComponentUI createUI(JComponent c)
protected  void doClick(MenuSelectionManager msm)
Call this method when a menu item is to be activated.
 Dimension getMaximumSize(JComponent c)
Returns the specified component's maximum size appropriate for the look and feel.
 Dimension getMinimumSize(JComponent c)
Returns the specified component's minimum size appropriate for the look and feel.
 MenuElement[] getPath()
protected  Dimension getPreferredMenuItemSize(JComponent c, Icon checkIcon, Icon arrowIcon, int defaultTextIconGap)
 Dimension getPreferredSize(JComponent c)
Returns the specified component's preferred size appropriate for the look and feel.
protected  String getPropertyPrefix()
protected  void installComponents(JMenuItem menuItem)
protected  void installDefaults()
protected  void installKeyboardActions()
protected  void installListeners()
 void installUI(JComponent c)
Configures the specified component appropriate for the look and feel.
 void paint(Graphics g, JComponent c)
Paints the specified component appropriate for the look and feel.
protected  void paintBackground(Graphics g, JMenuItem menuItem, Color bgColor)
Draws the background of the menu item.
protected  void paintMenuItem(Graphics g, JComponent c, Icon checkIcon, Icon arrowIcon, Color background, Color foreground, int defaultTextIconGap)
protected  void paintText(Graphics g, JMenuItem menuItem, Rectangle textRect, String text)
Renders the text of the current menu item.
protected  void uninstallComponents(JMenuItem menuItem)
protected  void uninstallDefaults()
protected  void uninstallKeyboardActions()
protected  void uninstallListeners()
 void uninstallUI(JComponent c)
Reverses configuration which was done on the specified component during installUI.
 void update(Graphics g, JComponent c)
We draw the background in paintMenuItem() so override update (which fills the background of opaque components by default) to just call paint().
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

menuItem

protected JMenuItem menuItem

selectionBackground

protected Color selectionBackground

selectionForeground

protected Color selectionForeground

disabledForeground

protected Color disabledForeground

acceleratorForeground

protected Color acceleratorForeground

acceleratorSelectionForeground

protected Color acceleratorSelectionForeground

defaultTextIconGap

protected int defaultTextIconGap

acceleratorFont

protected Font acceleratorFont

mouseInputListener

protected MouseInputListener mouseInputListener

menuDragMouseListener

protected MenuDragMouseListener menuDragMouseListener

menuKeyListener

protected MenuKeyListener menuKeyListener

propertyChangeListener

protected PropertyChangeListener propertyChangeListener
PropertyChangeListener returned from createPropertyChangeListener. You should not need to access this field, rather if you want to customize the PropertyChangeListener override createPropertyChangeListener.

Since:
1.6
See Also:
createPropertyChangeListener(javax.swing.JComponent)

arrowIcon

protected Icon arrowIcon

checkIcon

protected Icon checkIcon

oldBorderPainted

protected boolean oldBorderPainted
Constructor Detail

BasicMenuItemUI

public BasicMenuItemUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

installDefaults

protected void installDefaults()

installComponents

protected void installComponents(JMenuItem menuItem)
Since:
1.3

getPropertyPrefix

protected String getPropertyPrefix()

installListeners

protected void installListeners()

installKeyboardActions

protected void installKeyboardActions()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

uninstallDefaults

protected void uninstallDefaults()

uninstallComponents

protected void uninstallComponents(JMenuItem menuItem)
Since:
1.3

uninstallListeners

protected void uninstallListeners()

uninstallKeyboardActions

protected void uninstallKeyboardActions()

createMouseInputListener

protected MouseInputListener createMouseInputListener(JComponent c)

createMenuDragMouseListener

protected MenuDragMouseListener createMenuDragMouseListener(JComponent c)

createMenuKeyListener

protected MenuKeyListener createMenuKeyListener(JComponent c)

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener(JComponent c)
Creates a PropertyChangeListener which will be added to the menu item. If this method returns null then it will not be added to the menu item.

Returns:
an instance of a PropertyChangeListener or null
Since:
1.6

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's minimum size appropriate for the look and feel. If null is returned, the minimum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's maximum size appropriate for the look and feel. If null is returned, the maximum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getPreferredMenuItemSize

protected Dimension getPreferredMenuItemSize(JComponent c,
                                             Icon checkIcon,
                                             Icon arrowIcon,
                                             int defaultTextIconGap)

update

public void update(Graphics g,
                   JComponent c)
We draw the background in paintMenuItem() so override update (which fills the background of opaque components by default) to just call paint().

Overrides:
update in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

paintMenuItem

protected void paintMenuItem(Graphics g,
                             JComponent c,
                             Icon checkIcon,
                             Icon arrowIcon,
                             Color background,
                             Color foreground,
                             int defaultTextIconGap)

paintBackground

protected void paintBackground(Graphics g,
                               JMenuItem menuItem,
                               Color bgColor)
Draws the background of the menu item.

Parameters:
g - the paint graphics
menuItem - menu item to be painted
bgColor - selection background color
Since:
1.4

paintText

protected void paintText(Graphics g,
                         JMenuItem menuItem,
                         Rectangle textRect,
                         String text)
Renders the text of the current menu item.

Parameters:
g - graphics context
menuItem - menu item to render
textRect - bounding rectangle for rendering the text
text - string to render
Since:
1.4

getPath

public MenuElement[] getPath()

doClick

protected void doClick(MenuSelectionManager msm)
Call this method when a menu item is to be activated. This method handles some of the details of menu item activation such as clearing the selected path and messaging the JMenuItem's doClick() method.

Parameters:
msm - A MenuSelectionManager. The visual feedback and internal bookkeeping tasks are delegated to this MenuSelectionManager. If null is passed as this argument, the MenuSelectionManager.defaultManager is used.
Since:
1.4
See Also:
MenuSelectionManager, AbstractButton.doClick(int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicMenuItemUI.MouseInputHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicMenuItemUI.MouseInputHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicMenuItemUI.MouseInputHandler
All Implemented Interfaces:
MouseListener, MouseMotionListener, EventListener, MouseInputListener
Enclosing class:
BasicMenuItemUI
protected class BasicMenuItemUI.MouseInputHandler
extends Object
implements MouseInputListener

Constructor Summary
protected BasicMenuItemUI.MouseInputHandler()
Method Summary
void | mouseClicked(MouseEvent e) Invoked when the mouse button has been clicked (pressed and released) on a component.
void | mouseDragged(MouseEvent e) Invoked when a mouse button is pressed on a component and then dragged.
void | mouseEntered(MouseEvent e) Invoked when the mouse enters a component.
void | mouseExited(MouseEvent e) Invoked when the mouse exits a component.
void | mouseMoved(MouseEvent e) Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.
void | mousePressed(MouseEvent e) Invoked when a mouse button has been pressed on a component.
void | mouseReleased(MouseEvent e) Invoked when a mouse button has been released on a component.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicMenuItemUI.MouseInputHandler

protected BasicMenuItemUI.MouseInputHandler()
Method Detail

mouseClicked

public void mouseClicked(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse button has been clicked (pressed and released) on a component.

Specified by:
mouseClicked in interface MouseListener

mousePressed

public void mousePressed(MouseEvent e)
Description copied from interface: MouseListener
Invoked when a mouse button has been pressed on a component.

Specified by:
mousePressed in interface MouseListener

mouseReleased

public void mouseReleased(MouseEvent e)
Description copied from interface: MouseListener
Invoked when a mouse button has been released on a component.

Specified by:
mouseReleased in interface MouseListener

mouseEntered

public void mouseEntered(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse enters a component.

Specified by:
mouseEntered in interface MouseListener

mouseExited

public void mouseExited(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse exits a component.

Specified by:
mouseExited in interface MouseListener

mouseDragged

public void mouseDragged(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when a mouse button is pressed on a component and then dragged. MOUSE_DRAGGED events will continue to be delivered to the component where the drag originated until the mouse button is released (regardless of whether the mouse position is within the bounds of the component).

Due to platform-dependent Drag&Drop implementations, MOUSE_DRAGGED events may not be delivered during a native Drag&Drop operation.

Specified by:
mouseDragged in interface MouseMotionListener

mouseMoved

public void mouseMoved(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.

Specified by:
mouseMoved in interface MouseMotionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicMenuUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicMenuUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ButtonUI
            extended by  javax.swing.plaf.MenuItemUI
                extended by  javax.swing.plaf.basic.BasicMenuItemUI
                    extended by  javax.swing.plaf.basic.BasicMenuUI

public class BasicMenuUI
extends BasicMenuItemUI

A default L&F implementation of MenuUI. This implementation is a "combined" view/controller.

Nested Class Summary
class | BasicMenuUI.ChangeHandler As of Java 2 platform 1.4, this previously undocumented class is now obsolete.
protected class | BasicMenuUI.MouseInputHandler Instantiated and used by a menu item to handle the current menu selection from mouse events.
Field Summary
protected ChangeListener | changeListener
protected MenuListener | menuListener
Fields inherited from class javax.swing.plaf.basic.BasicMenuItemUI
acceleratorFont, acceleratorForeground, acceleratorSelectionForeground, arrowIcon, checkIcon, defaultTextIconGap, disabledForeground, menuDragMouseListener, menuItem, menuKeyListener, mouseInputListener, oldBorderPainted, propertyChangeListener, selectionBackground, selectionForeground
Constructor Summary
BasicMenuUI()
Method Summary
protected ChangeListener | createChangeListener(JComponent c)
protected MenuDragMouseListener | createMenuDragMouseListener(JComponent c)
protected MenuKeyListener | createMenuKeyListener(JComponent c)
protected MenuListener | createMenuListener(JComponent c)
protected MouseInputListener | createMouseInputListener(JComponent c)
protected PropertyChangeListener | createPropertyChangeListener(JComponent c) Creates a PropertyChangeListener which will be added to the menu item.
static ComponentUI | createUI(JComponent x)
Dimension | getMaximumSize(JComponent c) Returns the specified component's maximum size appropriate for the look and feel.
protected String | getPropertyPrefix()
protected void | installDefaults()
protected void | installKeyboardActions()
protected void | installListeners()
protected void | setupPostTimer(JMenu menu)
protected void | uninstallDefaults()
protected void | uninstallKeyboardActions()
protected void | uninstallListeners()
Methods inherited from class javax.swing.plaf.basic.BasicMenuItemUI
doClick, getMinimumSize, getPath, getPreferredMenuItemSize, getPreferredSize, installComponents, installUI, paint, paintBackground, paintMenuItem, paintText, uninstallComponents, uninstallUI, update
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

changeListener

protected ChangeListener changeListener

menuListener

protected MenuListener menuListener
Constructor Detail

BasicMenuUI

public BasicMenuUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent x)

installDefaults

protected void installDefaults()
Overrides:
installDefaults in class BasicMenuItemUI

getPropertyPrefix

protected String getPropertyPrefix()
Overrides:
getPropertyPrefix in class BasicMenuItemUI

installListeners

protected void installListeners()
Overrides:
installListeners in class BasicMenuItemUI

installKeyboardActions

protected void installKeyboardActions()
Overrides:
installKeyboardActions in class BasicMenuItemUI

uninstallKeyboardActions

protected void uninstallKeyboardActions()
Overrides:
uninstallKeyboardActions in class BasicMenuItemUI

createMouseInputListener

protected MouseInputListener createMouseInputListener(JComponent c)
Overrides:
createMouseInputListener in class BasicMenuItemUI

createMenuListener

protected MenuListener createMenuListener(JComponent c)

createChangeListener

protected ChangeListener createChangeListener(JComponent c)

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener(JComponent c)
Description copied from class: BasicMenuItemUI
Creates a PropertyChangeListener which will be added to the menu item. If this method returns null then it will not be added to the menu item.

Overrides:
createPropertyChangeListener in class BasicMenuItemUI
Returns:
an instance of a PropertyChangeListener or null

uninstallDefaults

protected void uninstallDefaults()
Overrides:
uninstallDefaults in class BasicMenuItemUI

uninstallListeners

protected void uninstallListeners()
Overrides:
uninstallListeners in class BasicMenuItemUI

createMenuDragMouseListener

protected MenuDragMouseListener createMenuDragMouseListener(JComponent c)
Overrides:
createMenuDragMouseListener in class BasicMenuItemUI

createMenuKeyListener

protected MenuKeyListener createMenuKeyListener(JComponent c)
Overrides:
createMenuKeyListener in class BasicMenuItemUI

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's maximum size appropriate for the look and feel. If null is returned, the maximum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMaximumSize in class BasicMenuItemUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

setupPostTimer

protected void setupPostTimer(JMenu menu)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicMenuUI.ChangeHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicMenuUI.ChangeHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicMenuUI.ChangeHandler
All Implemented Interfaces:
EventListener, ChangeListener
Enclosing class:
BasicMenuUI
public class BasicMenuUI.ChangeHandler
extends Object
implements ChangeListener

As of Java 2 platform 1.4, this previously undocumented class is now obsolete. KeyBindings are now managed by the popup menu.

Field Summary
boolean | isSelected
JMenu | menu
BasicMenuUI | ui
Component | wasFocused
Constructor Summary
BasicMenuUI.ChangeHandler(JMenu m, BasicMenuUI ui)
Method Summary
 void stateChanged(ChangeEvent e)
Invoked when the target of the listener has changed its state.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

menu

public JMenu menu

ui

public BasicMenuUI ui

isSelected

public boolean isSelected

wasFocused

public Component wasFocused
Constructor Detail

BasicMenuUI.ChangeHandler

public BasicMenuUI.ChangeHandler(JMenu m,
                                 BasicMenuUI ui)
Method Detail

stateChanged

public void stateChanged(ChangeEvent e)
Description copied from interface: ChangeListener
Invoked when the target of the listener has changed its state.

Specified by:
stateChanged in interface ChangeListener
Parameters:
e - a ChangeEvent object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicMenuUI.MouseInputHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicMenuUI.MouseInputHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicMenuUI.MouseInputHandler
All Implemented Interfaces:
MouseListener, MouseMotionListener, EventListener, MouseInputListener
Enclosing class:
BasicMenuUI
protected class BasicMenuUI.MouseInputHandler
extends Object
implements MouseInputListener

Instantiated and used by a menu item to handle the current menu selection from mouse events. A MouseInputHandler processes and forwards all mouse events to a shared instance of the MenuSelectionManager.

This class is protected so that it can be subclassed by other look and feels to implement their own mouse handling behavior. All overridden methods should call the parent methods so that the menu selection is correct.

Since:
1.4
See Also:
MenuSelectionManager

Constructor Summary
protected BasicMenuUI.MouseInputHandler()
Method Summary
void | mouseClicked(MouseEvent e) Invoked when the mouse button has been clicked (pressed and released) on a component.
void | mouseDragged(MouseEvent e) Invoked when a mouse button is pressed on the menu and then dragged.
void | mouseEntered(MouseEvent e) Invoked when the cursor enters the menu.
void | mouseExited(MouseEvent e) Invoked when the mouse exits a component.
void | mouseMoved(MouseEvent e) Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.
void | mousePressed(MouseEvent e) Invoked when the mouse has been clicked on the menu.
void | mouseReleased(MouseEvent e) Invoked when the mouse has been released on the menu.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicMenuUI.MouseInputHandler

protected BasicMenuUI.MouseInputHandler()
Method Detail

mouseClicked

public void mouseClicked(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse button has been clicked (pressed and released) on a component.

Specified by:
mouseClicked in interface MouseListener

mousePressed

public void mousePressed(MouseEvent e)
Invoked when the mouse has been clicked on the menu. This method clears or sets the selection path of the MenuSelectionManager.

Specified by:
mousePressed in interface MouseListener
Parameters:
e - the mouse event

mouseReleased

public void mouseReleased(MouseEvent e)
Invoked when the mouse has been released on the menu. Delegates the mouse event to the MenuSelectionManager.

Specified by:
mouseReleased in interface MouseListener
Parameters:
e - the mouse event

mouseEntered

public void mouseEntered(MouseEvent e)
Invoked when the cursor enters the menu. This method sets the selected path for the MenuSelectionManager and handles the case in which a menu item is used to pop up an additional menu, as in a hierarchical menu system.

Specified by:
mouseEntered in interface MouseListener
Parameters:
e - the mouse event; not used

mouseExited

public void mouseExited(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse exits a component.

Specified by:
mouseExited in interface MouseListener

mouseDragged

public void mouseDragged(MouseEvent e)
Invoked when a mouse button is pressed on the menu and then dragged. Delegates the mouse event to the MenuSelectionManager.

Specified by:
mouseDragged in interface MouseMotionListener
Parameters:
e - the mouse event
See Also:
MouseMotionListener.mouseDragged(java.awt.event.MouseEvent)

mouseMoved

public void mouseMoved(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.

Specified by:
mouseMoved in interface MouseMotionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicOptionPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicOptionPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.OptionPaneUI
            extended by  javax.swing.plaf.basic.BasicOptionPaneUI

public class BasicOptionPaneUI
extends OptionPaneUI

Provides the basic look and feel for a JOptionPane. BasicMessagePaneUI provides a means to place an icon, message and buttons into a Container. Generally, the layout will look like:

        ------------------
        | i | message    |
        | c | message    |
        | o | message    |
        | n | message    |
        ------------------
        |     buttons    |
        |________________|
icon is an instance of Icon that is wrapped inside a JLabel. The message is an opaque object and is tested for the following: if the message is a Component it is added to the Container, if it is an Icon it is wrapped inside a JLabel and added to the Container otherwise it is wrapped inside a JLabel.

The above layout is used when the option pane's ComponentOrientation property is horizontal, left-to-right. The layout will be adjusted appropriately for other orientations.

The Container, message, icon, and buttons are all determined from abstract methods.

Nested Class Summary
class | BasicOptionPaneUI.ButtonActionListener This inner class is marked "public" due to a compiler bug.
static class | BasicOptionPaneUI.ButtonAreaLayout ButtonAreaLayout behaves in a similar manner to FlowLayout.
class | BasicOptionPaneUI.PropertyChangeHandler This inner class is marked "public" due to a compiler bug.
Field Summary
protected boolean | hasCustomComponents This is set to true in validateComponent if a Component is contained in either the message or the buttons.
protected Component | initialFocusComponent Component to receive focus when messaged with selectInitialValue.
protected JComponent | inputComponent JComponent provide for input if optionPane.getWantsInput() returns true.
static int | MinimumHeight
protected Dimension | minimumSize
static int | MinimumWidth
protected JOptionPane | optionPane JOptionPane that the receiver is providing the look and feel for.
protected PropertyChangeListener | propertyChangeListener
Constructor Summary
BasicOptionPaneUI()
Method Summary
protected void | addButtonComponents(Container container, Object[] buttons, int initialIndex) Creates the appropriate object to represent each of the objects in buttons and adds it to container.
protected void | addIcon(Container top) Creates and adds a JLabel representing the icon returned from getIcon to top.
protected void | addMessageComponents(Container container, GridBagConstraints cons, Object msg, int maxll, boolean internallyCreated) Creates the appropriate object to represent msg and places it into container.
protected void | burstStringInto(Container c, String d, int maxll) Recursively creates new JLabel instances to represent d.
boolean | containsCustomComponents(JOptionPane op) Returns true if in the last call to validateComponent the message or buttons contained a subclass of Component.
protected ActionListener | createButtonActionListener(int buttonIndex)
protected Container | createButtonArea() Creates and returns a Container containing the buttons.
protected LayoutManager | createLayoutManager()
protected Container | createMessageArea() Messaged from installComponents to create a Container containing the body of the message.
protected PropertyChangeListener | createPropertyChangeListener()
protected Container | createSeparator()
static ComponentUI | createUI(JComponent x) Creates a new BasicOptionPaneUI instance.
protected Object[] | getButtons() Returns the buttons to display from the JOptionPane the receiver is providing the look and feel for.
protected Icon | getIcon() Returns the icon from the JOptionPane the receiver is providing the look and feel for, or the default icon as returned from getDefaultIcon.
protected Icon | getIconForType(int messageType) Returns the icon to use for the passed in type.
protected int | getInitialValueIndex() Returns the initial index into the buttons to select.
protected int | getMaxCharactersPerLineCount() Returns the maximum number of characters to place on a line.
protected Object | getMessage() Returns the message to display from the JOptionPane the receiver is providing the look and feel for.
Dimension | getMinimumOptionPaneSize() Returns the minimum size the option pane should be.
Dimension | getPreferredSize(JComponent c) If c is the JOptionPane the receiver is contained in, the preferred size that is returned is the maximum of the preferred size of the LayoutManager for the JOptionPane, and getMinimumOptionPaneSize.
protected boolean | getSizeButtonsToSameWidth() Returns true, basic L&F wants all the buttons to have the same width.
protected void | installComponents()
protected void | installDefaults()
protected void | installKeyboardActions()
protected void | installListeners()
void | installUI(JComponent c) Installs the receiver as the L&F for the passed in JOptionPane.
protected void | resetInputValue() Sets the input value in the option pane the receiver is providing the look and feel for based on the value in the inputComponent.
void | selectInitialValue(JOptionPane op) If inputComponent is non-null, the focus is requested on that, otherwise request focus on the default value
protected void | uninstallComponents()
protected void | uninstallDefaults()
protected void | uninstallKeyboardActions()
protected void | uninstallListeners()
void | uninstallUI(JComponent c) Removes the receiver from the L&F controller of the passed in split pane.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, paint, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MinimumWidth

public static final int MinimumWidth
See Also:
Constant Field Values

MinimumHeight

public static final int MinimumHeight
See Also:
Constant Field Values

optionPane

protected JOptionPane optionPane
JOptionPane that the receiver is providing the look and feel for.

minimumSize

protected Dimension minimumSize

inputComponent

protected JComponent inputComponent
JComponent provide for input if optionPane.getWantsInput() returns true.

initialFocusComponent

protected Component initialFocusComponent
Component to receive focus when messaged with selectInitialValue.

hasCustomComponents

protected boolean hasCustomComponents
This is set to true in validateComponent if a Component is contained in either the message or the buttons.

propertyChangeListener

protected PropertyChangeListener propertyChangeListener
Constructor Detail

BasicOptionPaneUI

public BasicOptionPaneUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent x)
Creates a new BasicOptionPaneUI instance.

installUI

public void installUI(JComponent c)
Installs the receiver as the L&F for the passed in JOptionPane.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Removes the receiver from the L&F controller of the passed in split pane.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installDefaults

protected void installDefaults()

uninstallDefaults

protected void uninstallDefaults()

installComponents

protected void installComponents()

uninstallComponents

protected void uninstallComponents()

createLayoutManager

protected LayoutManager createLayoutManager()

installListeners

protected void installListeners()

uninstallListeners

protected void uninstallListeners()

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener()

installKeyboardActions

protected void installKeyboardActions()

uninstallKeyboardActions

protected void uninstallKeyboardActions()

getMinimumOptionPaneSize

public Dimension getMinimumOptionPaneSize()
Returns the minimum size the option pane should be. Primarily provided for subclassers wishing to offer a different minimum size.

getPreferredSize

public Dimension getPreferredSize(JComponent c)
If c is the JOptionPane the receiver is contained in, the preferred size that is returned is the maximum of the preferred size of the LayoutManager for the JOptionPane, and getMinimumOptionPaneSize.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

createMessageArea

protected Container createMessageArea()
Messaged from installComponents to create a Container containing the body of the message. The icon is the created by calling addIcon.

addMessageComponents

protected void addMessageComponents(Container container,
                                    GridBagConstraints cons,
                                    Object msg,
                                    int maxll,
                                    boolean internallyCreated)
Creates the appropriate object to represent msg and places it into container. If msg is an instance of Component, it is added directly, if it is an Icon, a JLabel is created to represent it, otherwise a JLabel is created for the string, if d is an Object[], this method will be recursively invoked for the children. internallyCreated is true if Objc is an instance of Component and was created internally by this method (this is used to correctly set hasCustomComponents only if !internallyCreated).

getMessage

protected Object getMessage()
Returns the message to display from the JOptionPane the receiver is providing the look and feel for.

addIcon

protected void addIcon(Container top)
Creates and adds a JLabel representing the icon returned from getIcon to top. This is messaged from createMessageArea

getIcon

protected Icon getIcon()
Returns the icon from the JOptionPane the receiver is providing the look and feel for, or the default icon as returned from getDefaultIcon.

getIconForType

protected Icon getIconForType(int messageType)
Returns the icon to use for the passed in type.

getMaxCharactersPerLineCount

protected int getMaxCharactersPerLineCount()
Returns the maximum number of characters to place on a line.

burstStringInto

protected void burstStringInto(Container c,
                               String d,
                               int maxll)
Recursively creates new JLabel instances to represent d. Each JLabel instance is added to c.

createSeparator

protected Container createSeparator()

createButtonArea

protected Container createButtonArea()
Creates and returns a Container containing the buttons. The buttons are created by calling getButtons.

addButtonComponents

protected void addButtonComponents(Container container,
                                   Object[] buttons,
                                   int initialIndex)
Creates the appropriate object to represent each of the objects in buttons and adds it to container. This differs from addMessageComponents in that it will recurse on buttons and that if button is not a Component it will create an instance of JButton.

createButtonActionListener

protected ActionListener createButtonActionListener(int buttonIndex)

getButtons

protected Object[] getButtons()
Returns the buttons to display from the JOptionPane the receiver is providing the look and feel for. If the JOptionPane has options set, they will be provided, otherwise if the optionType is YES_NO_OPTION, yesNoOptions is returned, if the type is YES_NO_CANCEL_OPTION yesNoCancelOptions is returned, otherwise defaultButtons are returned.

getSizeButtonsToSameWidth

protected boolean getSizeButtonsToSameWidth()
Returns true, basic L&F wants all the buttons to have the same width.

getInitialValueIndex

protected int getInitialValueIndex()
Returns the initial index into the buttons to select. The index is calculated from the initial value from the JOptionPane and options of the JOptionPane or 0.

resetInputValue

protected void resetInputValue()
Sets the input value in the option pane the receiver is providing the look and feel for based on the value in the inputComponent.

selectInitialValue

public void selectInitialValue(JOptionPane op)
If inputComponent is non-null, the focus is requested on that, otherwise request focus on the default value

Specified by:
selectInitialValue in class OptionPaneUI

containsCustomComponents

public boolean containsCustomComponents(JOptionPane op)
Returns true if in the last call to validateComponent the message or buttons contained a subclass of Component.

Specified by:
containsCustomComponents in class OptionPaneUI
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicOptionPaneUI.ButtonActionListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicOptionPaneUI.ButtonActionListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicOptionPaneUI.ButtonActionListener
All Implemented Interfaces:
ActionListener, EventListener
Enclosing class:
BasicOptionPaneUI
public class BasicOptionPaneUI.ButtonActionListener
extends Object
implements ActionListener

This inner class is marked "public" due to a compiler bug. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicOptionPaneUI.

Field Summary
protected  int buttonIndex
Constructor Summary
BasicOptionPaneUI.ButtonActionListener(int buttonIndex)
Method Summary
 void actionPerformed(ActionEvent e)
Invoked when an action occurs.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

buttonIndex

protected int buttonIndex
Constructor Detail

BasicOptionPaneUI.ButtonActionListener

public BasicOptionPaneUI.ButtonActionListener(int buttonIndex)
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

Specified by:
actionPerformed in interface ActionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicOptionPaneUI.ButtonAreaLayout

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicOptionPaneUI.ButtonAreaLayout

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicOptionPaneUI.ButtonAreaLayout
All Implemented Interfaces:
LayoutManager
Enclosing class:
BasicOptionPaneUI
public static class BasicOptionPaneUI.ButtonAreaLayout
extends Object
implements LayoutManager

ButtonAreaLayout behaves in a similar manner to FlowLayout. It lays out all components from left to right. If syncAllWidths is true, the widths of each component will be set to the largest preferred size width. This inner class is marked "public" due to a compiler bug. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicOptionPaneUI.

Field Summary
protected boolean | centersChildren If true, children are lumped together in parent.
protected int | padding
protected boolean | syncAllWidths
Constructor Summary
BasicOptionPaneUI.ButtonAreaLayout(boolean syncAllWidths, int padding)
Method Summary
void | addLayoutComponent(String string, Component comp) If the layout manager uses a per-component string, adds the component comp to the layout, associating it with the string specified by name.
boolean | getCentersChildren()
int | getPadding()
boolean | getSyncAllWidths()
void | layoutContainer(Container container) Lays out the specified container.
Dimension | minimumLayoutSize(Container c) Calculates the minimum size dimensions for the specified container, given the components it contains.
Dimension | preferredLayoutSize(Container c) Calculates the preferred size dimensions for the specified container, given the components it contains.
void | removeLayoutComponent(Component c) Removes the specified component from the layout.
void | setCentersChildren(boolean newValue)
void | setPadding(int newPadding)
void | setSyncAllWidths(boolean newValue)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

syncAllWidths

protected boolean syncAllWidths

padding

protected int padding

centersChildren

protected boolean centersChildren
If true, children are lumped together in parent.

Constructor Detail

BasicOptionPaneUI.ButtonAreaLayout

public BasicOptionPaneUI.ButtonAreaLayout(boolean syncAllWidths,
                                          int padding)
Method Detail

setSyncAllWidths

public void setSyncAllWidths(boolean newValue)

getSyncAllWidths

public boolean getSyncAllWidths()

setPadding

public void setPadding(int newPadding)

getPadding

public int getPadding()

setCentersChildren

public void setCentersChildren(boolean newValue)

getCentersChildren

public boolean getCentersChildren()

addLayoutComponent

public void addLayoutComponent(String string,
                               Component comp)
Description copied from interface: LayoutManager
If the layout manager uses a per-component string, adds the component comp to the layout, associating it with the string specified by name.

Specified by:
addLayoutComponent in interface LayoutManager
Parameters:
string - the string to be associated with the component
comp - the component to be added

layoutContainer

public void layoutContainer(Container container)
Description copied from interface: LayoutManager
Lays out the specified container.

Specified by:
layoutContainer in interface LayoutManager
Parameters:
container - the container to be laid out

minimumLayoutSize

public Dimension minimumLayoutSize(Container c)
Description copied from interface: LayoutManager
Calculates the minimum size dimensions for the specified container, given the components it contains.

Specified by:
minimumLayoutSize in interface LayoutManager
Parameters:
c - the component to be laid out
See Also:
LayoutManager.preferredLayoutSize(java.awt.Container)

preferredLayoutSize

public Dimension preferredLayoutSize(Container c)
Description copied from interface: LayoutManager
Calculates the preferred size dimensions for the specified container, given the components it contains.

Specified by:
preferredLayoutSize in interface LayoutManager
Parameters:
c - the container to be laid out
See Also:
LayoutManager.minimumLayoutSize(java.awt.Container)

removeLayoutComponent

public void removeLayoutComponent(Component c)
Description copied from interface: LayoutManager
Removes the specified component from the layout.

Specified by:
removeLayoutComponent in interface LayoutManager
Parameters:
c - the component to be removed
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicOptionPaneUI.PropertyChangeHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicOptionPaneUI.PropertyChangeHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicOptionPaneUI.PropertyChangeHandler
All Implemented Interfaces:
PropertyChangeListener, EventListener
Enclosing class:
BasicOptionPaneUI
public class BasicOptionPaneUI.PropertyChangeHandler
extends Object
implements PropertyChangeListener

This inner class is marked "public" due to a compiler bug. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicOptionPaneUI.

Constructor Summary
BasicOptionPaneUI.PropertyChangeHandler()
Method Summary
 void propertyChange(PropertyChangeEvent e)
If the source of the PropertyChangeEvent e equals the optionPane and is one of the ICON_PROPERTY, MESSAGE_PROPERTY, OPTIONS_PROPERTY or INITIAL_VALUE_PROPERTY, validateComponent is invoked.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicOptionPaneUI.PropertyChangeHandler

public BasicOptionPaneUI.PropertyChangeHandler()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
If the source of the PropertyChangeEvent e equals the optionPane and is one of the ICON_PROPERTY, MESSAGE_PROPERTY, OPTIONS_PROPERTY or INITIAL_VALUE_PROPERTY, validateComponent is invoked.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicPanelUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicPanelUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.PanelUI
            extended by  javax.swing.plaf.basic.BasicPanelUI

public class BasicPanelUI
extends PanelUI

BasicPanel implementation

Constructor Summary
BasicPanelUI()
Method Summary
static ComponentUI | createUI(JComponent c)
int | getBaseline(JComponent c, int width, int height) Returns the baseline.
Component.BaselineResizeBehavior | getBaselineResizeBehavior(JComponent c) Returns an enum indicating how the baseline of the component changes as the size changes.
protected void | installDefaults(JPanel p)
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
protected void | uninstallDefaults(JPanel p)
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getMaximumSize, getMinimumSize, getPreferredSize, paint, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicPanelUI

public BasicPanelUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installDefaults

protected void installDefaults(JPanel p)

uninstallDefaults

protected void uninstallDefaults(JPanel p)

getBaseline

public int getBaseline(JComponent c,
                       int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class ComponentUI
Parameters:
c - JComponent baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
NullPointerException - if c is null
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.

Overrides:
getBaselineResizeBehavior in class ComponentUI
Parameters:
c - JComponent to return baseline resize behavior for
Returns:
an enum indicating how the baseline changes as the component size changes
Throws:
NullPointerException - if c is null
Since:
1.6
See Also:
JComponent.getBaseline(int, int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicPasswordFieldUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicPasswordFieldUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TextUI
            extended by  javax.swing.plaf.basic.BasicTextUI
                extended by  javax.swing.plaf.basic.BasicTextFieldUI
                    extended by  javax.swing.plaf.basic.BasicPasswordFieldUI
All Implemented Interfaces:
ViewFactory
public class BasicPasswordFieldUI
extends BasicTextFieldUI

Provides the Windows look and feel for a password field. The only difference from the standard text field is that the view of the text is simply a string of the echo character as specified in JPasswordField, rather than the real text contained in the field.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicTextUI
BasicTextUI.BasicCaret, BasicTextUI.BasicHighlighter
Constructor Summary
BasicPasswordFieldUI()
Method Summary
View | create(Element elem) Creates a view (PasswordView) for an element.
static ComponentUI | createUI(JComponent c) Creates a UI for a JPasswordField.
protected String | getPropertyPrefix() Fetches the name used as a key to look up properties through the UIManager.
protected void | installDefaults() Installs the necessary properties on the JPasswordField.
Methods inherited from class javax.swing.plaf.basic.BasicTextFieldUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class javax.swing.plaf.basic.BasicTextUI
create, createCaret, createHighlighter, createKeymap, damageRange, damageRange, getComponent, getEditorKit, getKeymapName, getMaximumSize, getMinimumSize, getNextVisualPositionFrom, getPreferredSize, getRootView, getToolTipText, getVisibleEditorRect, installKeyboardActions, installListeners, installUI, modelChanged, modelToView, modelToView, paint, paintBackground, paintSafely, propertyChange, setView, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, uninstallUI, update, viewToModel, viewToModel
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicPasswordFieldUI

public BasicPasswordFieldUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)
Creates a UI for a JPasswordField.

Parameters:
c - the JPasswordField
Returns:
the UI

getPropertyPrefix

protected String getPropertyPrefix()
Fetches the name used as a key to look up properties through the UIManager. This is used as a prefix to all the standard text properties.

Overrides:
getPropertyPrefix in class BasicTextFieldUI
Returns:
the name ("PasswordField")

installDefaults

protected void installDefaults()
Installs the necessary properties on the JPasswordField.

Overrides:
installDefaults in class BasicTextUI
Since:
1.6
See Also:
BasicTextUI.uninstallDefaults(), BasicTextUI.installUI(javax.swing.JComponent)

create

public View create(Element elem)
Creates a view (PasswordView) for an element.

Specified by:
create in interface ViewFactory
Overrides:
create in class BasicTextFieldUI
Parameters:
elem - the element
Returns:
the view
See Also:
View
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicPopupMenuSeparatorUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicPopupMenuSeparatorUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SeparatorUI
            extended by  javax.swing.plaf.basic.BasicSeparatorUI
                extended by  javax.swing.plaf.basic.BasicPopupMenuSeparatorUI

public class BasicPopupMenuSeparatorUI
extends BasicSeparatorUI

A Basic L&F implementation of PopupMenuSeparatorUI. This implementation is a "combined" view/controller.

Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicSeparatorUI
highlight, shadow
Constructor Summary
BasicPopupMenuSeparatorUI()
Method Summary
static ComponentUI | createUI(JComponent c)
Dimension | getPreferredSize(JComponent c) Returns the specified component's preferred size appropriate for the look and feel.
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
Methods inherited from class javax.swing.plaf.basic.BasicSeparatorUI
getMaximumSize, getMinimumSize, installDefaults, installListeners, installUI, uninstallDefaults, uninstallListeners, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicPopupMenuSeparatorUI

public BasicPopupMenuSeparatorUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class BasicSeparatorUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Overrides:
getPreferredSize in class BasicSeparatorUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicPopupMenuUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicPopupMenuUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.PopupMenuUI
            extended by  javax.swing.plaf.basic.BasicPopupMenuUI

public class BasicPopupMenuUI
extends PopupMenuUI

A Windows L&F implementation of PopupMenuUI. This implementation is a "combined" view/controller.

Field Summary
protected  JPopupMenu popupMenu
Constructor Summary
BasicPopupMenuUI()
Method Summary
static ComponentUI | createUI(JComponent x)
void | installDefaults()
protected void | installKeyboardActions()
protected void | installListeners()
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
boolean | isPopupTrigger(MouseEvent e)
protected void | uninstallDefaults()
protected void | uninstallKeyboardActions()
protected void | uninstallListeners()
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.PopupMenuUI
getPopup
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, paint, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

popupMenu

protected JPopupMenu popupMenu
Constructor Detail

BasicPopupMenuUI

public BasicPopupMenuUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent x)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

installDefaults

public void installDefaults()

installListeners

protected void installListeners()

installKeyboardActions

protected void installKeyboardActions()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

uninstallDefaults

protected void uninstallDefaults()

uninstallListeners

protected void uninstallListeners()

uninstallKeyboardActions

protected void uninstallKeyboardActions()

isPopupTrigger

public boolean isPopupTrigger(MouseEvent e)
Overrides:
isPopupTrigger in class PopupMenuUI
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicProgressBarUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicProgressBarUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ProgressBarUI
            extended by  javax.swing.plaf.basic.BasicProgressBarUI
Direct Known Subclasses:
MetalProgressBarUI
public class BasicProgressBarUI
extends ProgressBarUI

A Basic L&F implementation of ProgressBarUI.

Nested Class Summary
 class BasicProgressBarUI.ChangeHandler
This inner class is marked "public" due to a compiler bug.
Field Summary
protected Rectangle | boxRect Used to hold the location and size of the bouncing box (returned by getBox) to be painted.
protected ChangeListener | changeListener
protected JProgressBar | progressBar
Constructor Summary
BasicProgressBarUI()
Method Summary
static ComponentUI | createUI(JComponent x)
protected int | getAmountFull(Insets b, int width, int height) This determines the amount of the progress bar that should be filled based on the percent done gathered from the model.
protected int | getAnimationIndex() Gets the index of the current animation frame.
int | getBaseline(JComponent c, int width, int height) Returns the baseline.
Component.BaselineResizeBehavior | getBaselineResizeBehavior(JComponent c) Returns an enum indicating how the baseline of the component changes as the size changes.
protected Rectangle | getBox(Rectangle r) Stores the position and size of the bouncing box that would be painted for the current animation index in r and returns r.
protected int | getBoxLength(int availableLength, int otherDimension) Returns the length of the "bouncing box" to be painted.
protected int | getCellLength() Returns the width (if HORIZONTAL) or height (if VERTICAL) of each of the indivdual cells/units to be rendered in the progress bar.
protected int | getCellSpacing() Returns the spacing between each of the cells/units in the progress bar.
protected int | getFrameCount() Returns the number of frames for the complete animation loop used by an indeterminate JProgessBar.
Dimension | getMaximumSize(JComponent c) Returns the specified component's maximum size appropriate for the look and feel.
Dimension | getMinimumSize(JComponent c) The Minimum size for this component is 10.
protected Dimension | getPreferredInnerHorizontal()
protected Dimension | getPreferredInnerVertical()
Dimension | getPreferredSize(JComponent c) Returns the specified component's preferred size appropriate for the look and feel.
protected Color | getSelectionBackground() The "selectionBackground" is the color of the text when it is painted over an unfilled area of the progress bar.
protected Color | getSelectionForeground() The "selectionForeground" is the color of the text when it is painted over a filled area of the progress bar.
protected Point | getStringPlacement(Graphics g, String progressString, int x, int y, int width, int height) Designate the place where the progress string will be painted.
protected void | incrementAnimationIndex() Sets the index of the current animation frame, to the next valid value, which results in the progress bar being repainted.
protected void | installDefaults()
protected void | installListeners()
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
void | paint(Graphics g, JComponent c) Delegates painting to one of two methods: paintDeterminate or paintIndeterminate.
protected void | paintDeterminate(Graphics g, JComponent c) All purpose paint method that should do the right thing for almost all linear, determinate progress bars.
protected void | paintIndeterminate(Graphics g, JComponent c) All purpose paint method that should do the right thing for all linear bouncing-box progress bars.
protected void | paintString(Graphics g, int x, int y, int width, int height, int amountFull, Insets b)
protected void | setAnimationIndex(int newValue) Sets the index of the current animation frame to the specified value and requests that the progress bar be repainted.
protected void | setCellLength(int cellLen)
protected void | setCellSpacing(int cellSpace)
protected void | startAnimationTimer() Starts the animation thread, creating and initializing it if necessary.
protected void | stopAnimationTimer() Stops the animation thread.
protected void | uninstallDefaults()
protected void | uninstallListeners() Removes all listeners installed by this object.
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

progressBar

protected JProgressBar progressBar

changeListener

protected ChangeListener changeListener

boxRect

protected Rectangle boxRect
Used to hold the location and size of the bouncing box (returned by getBox) to be painted.

Since:
1.5
Constructor Detail

BasicProgressBarUI

public BasicProgressBarUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent x)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installDefaults

protected void installDefaults()

uninstallDefaults

protected void uninstallDefaults()

installListeners

protected void installListeners()

startAnimationTimer

protected void startAnimationTimer()
Starts the animation thread, creating and initializing it if necessary. This method is invoked when an indeterminate progress bar should start animating. Reasons for this may include:
  • The progress bar is determinate and becomes displayable
  • The progress bar is displayable and becomes determinate
  • The progress bar is displayable and determinate and this UI is installed
If you implement your own animation thread, you must override this method.

Since:
1.4
See Also:
stopAnimationTimer()

stopAnimationTimer

protected void stopAnimationTimer()
Stops the animation thread. This method is invoked when the indeterminate animation should be stopped. Reasons for this may include:
  • The progress bar changes to determinate
  • The progress bar is no longer part of a displayable hierarchy
  • This UI in uninstalled
If you implement your own animation thread, you must override this method.

Since:
1.4
See Also:
startAnimationTimer()

uninstallListeners

protected void uninstallListeners()
Removes all listeners installed by this object.

getBaseline

public int getBaseline(JComponent c,
                       int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class ComponentUI
Parameters:
c - JComponent baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
NullPointerException - if c is null
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.

Overrides:
getBaselineResizeBehavior in class ComponentUI
Parameters:
c - JComponent to return baseline resize behavior for
Returns:
an enum indicating how the baseline changes as the component size changes
Throws:
NullPointerException - if c is null
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getPreferredInnerHorizontal

protected Dimension getPreferredInnerHorizontal()

getPreferredInnerVertical

protected Dimension getPreferredInnerVertical()

getSelectionForeground

protected Color getSelectionForeground()
The "selectionForeground" is the color of the text when it is painted over a filled area of the progress bar.

getSelectionBackground

protected Color getSelectionBackground()
The "selectionBackground" is the color of the text when it is painted over an unfilled area of the progress bar.

getCellLength

protected int getCellLength()
Returns the width (if HORIZONTAL) or height (if VERTICAL) of each of the indivdual cells/units to be rendered in the progress bar. However, for text rendering simplification and aesthetic considerations, this function will return 1 when the progress string is being rendered.

Returns:
the value representing the spacing between cells
See Also:
setCellLength(int), JProgressBar.isStringPainted()

setCellLength

protected void setCellLength(int cellLen)

getCellSpacing

protected int getCellSpacing()
Returns the spacing between each of the cells/units in the progress bar. However, for text rendering simplification and aesthetic considerations, this function will return 0 when the progress string is being rendered.

Returns:
the value representing the spacing between cells
See Also:
setCellSpacing(int), JProgressBar.isStringPainted()

setCellSpacing

protected void setCellSpacing(int cellSpace)

getAmountFull

protected int getAmountFull(Insets b,
                            int width,
                            int height)
This determines the amount of the progress bar that should be filled based on the percent done gathered from the model. This is a common operation so it was abstracted out. It assumes that your progress bar is linear. That is, if you are making a circular progress indicator, you will want to override this method.

paint

public void paint(Graphics g,
                  JComponent c)
Delegates painting to one of two methods: paintDeterminate or paintIndeterminate.

Overrides:
paint in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getBox

protected Rectangle getBox(Rectangle r)
Stores the position and size of the bouncing box that would be painted for the current animation index in r and returns r. Subclasses that add to the painting performed in this class's implementation of paintIndeterminate -- to draw an outline around the bouncing box, for example -- can use this method to get the location of the bouncing box that was just painted. By overriding this method, you have complete control over the size and position of the bouncing box, without having to reimplement paintIndeterminate.

Parameters:
r - the Rectangle instance to be modified; may be null
Returns:
null if no box should be drawn; otherwise, returns the passed-in rectangle (if non-null) or a new rectangle
Since:
1.4
See Also:
setAnimationIndex(int)

getBoxLength

protected int getBoxLength(int availableLength,
                           int otherDimension)
Returns the length of the "bouncing box" to be painted. This method is invoked by the default implementation of paintIndeterminate to get the width (if the progress bar is horizontal) or height (if vertical) of the box. For example:
boxRect.width = getBoxLength(componentInnards.width,
                             componentInnards.height);

Parameters:
availableLength - the amount of space available for the bouncing box to move in; for a horizontal progress bar, for example, this should be the inside width of the progress bar (the component width minus borders)
otherDimension - for a horizontal progress bar, this should be the inside height of the progress bar; this value might be used to constrain or determine the return value
Returns:
the size of the box dimension being determined; must be no larger than availableLength
Since:
1.5
See Also:
SwingUtilities.calculateInnerArea(javax.swing.JComponent, java.awt.Rectangle)

paintIndeterminate

protected void paintIndeterminate(Graphics g,
                                  JComponent c)
All purpose paint method that should do the right thing for all linear bouncing-box progress bars. Override this if you are making another kind of progress bar.

Since:
1.4
See Also:
paintDeterminate(java.awt.Graphics, javax.swing.JComponent)

paintDeterminate

protected void paintDeterminate(Graphics g,
                                JComponent c)
All purpose paint method that should do the right thing for almost all linear, determinate progress bars. By setting a few values in the defaults table, things should work just fine to paint your progress bar. Naturally, override this if you are making a circular or semi-circular progress bar.

Since:
1.4
See Also:
paintIndeterminate(java.awt.Graphics, javax.swing.JComponent)

paintString

protected void paintString(Graphics g,
                           int x,
                           int y,
                           int width,
                           int height,
                           int amountFull,
                           Insets b)

getStringPlacement

protected Point getStringPlacement(Graphics g,
                                   String progressString,
                                   int x,
                                   int y,
                                   int width,
                                   int height)
Designate the place where the progress string will be painted. This implementation places it at the center of the progress bar (in both x and y). Override this if you want to right, left, top, or bottom align the progress string or if you need to nudge it around for any reason.

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent c)
The Minimum size for this component is 10. The rationale here is that there should be at least one pixel per 10 percent.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's maximum size appropriate for the look and feel. If null is returned, the maximum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAnimationIndex

protected int getAnimationIndex()
Gets the index of the current animation frame.

Since:
1.4

getFrameCount

protected final int getFrameCount()
Returns the number of frames for the complete animation loop used by an indeterminate JProgessBar. The progress chunk will go from one end to the other and back during the entire loop. This visual behavior may be changed by subclasses in other Look and Feels.

Returns:
the number of frames
Since:
1.6

setAnimationIndex

protected void setAnimationIndex(int newValue)
Sets the index of the current animation frame to the specified value and requests that the progress bar be repainted. Subclasses that don't use the default painting code might need to override this method to change the way that the repaint method is invoked.

Parameters:
newValue - the new animation index; no checking is performed on its value
Since:
1.4
See Also:
incrementAnimationIndex()

incrementAnimationIndex

protected void incrementAnimationIndex()
Sets the index of the current animation frame, to the next valid value, which results in the progress bar being repainted. The next valid value is, by default, the current animation index plus one. If the new value would be too large, this method sets the index to 0. Subclasses might need to override this method to ensure that the index does not go over the number of frames needed for the particular progress bar instance. This method is invoked by the default animation thread every X milliseconds, where X is specified by the "ProgressBar.repaintInterval" UI default.

Since:
1.4
See Also:
setAnimationIndex(int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicProgressBarUI.ChangeHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicProgressBarUI.ChangeHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicProgressBarUI.ChangeHandler
All Implemented Interfaces:
EventListener, ChangeListener
Enclosing class:
BasicProgressBarUI
public class BasicProgressBarUI.ChangeHandler
extends Object
implements ChangeListener

This inner class is marked "public" due to a compiler bug. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicProgressBarUI.

Constructor Summary
BasicProgressBarUI.ChangeHandler()
Method Summary
 void stateChanged(ChangeEvent e)
Invoked when the target of the listener has changed its state.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicProgressBarUI.ChangeHandler

public BasicProgressBarUI.ChangeHandler()
Method Detail

stateChanged

public void stateChanged(ChangeEvent e)
Description copied from interface: ChangeListener
Invoked when the target of the listener has changed its state.

Specified by:
stateChanged in interface ChangeListener
Parameters:
e - a ChangeEvent object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicRadioButtonMenuItemUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicRadioButtonMenuItemUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ButtonUI
            extended by  javax.swing.plaf.MenuItemUI
                extended by  javax.swing.plaf.basic.BasicMenuItemUI
                    extended by  javax.swing.plaf.basic.BasicRadioButtonMenuItemUI

public class BasicRadioButtonMenuItemUI
extends BasicMenuItemUI

BasicRadioButtonMenuItem implementation

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicMenuItemUI
BasicMenuItemUI.MouseInputHandler
Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicMenuItemUI
acceleratorFont, acceleratorForeground, acceleratorSelectionForeground, arrowIcon, checkIcon, defaultTextIconGap, disabledForeground, menuDragMouseListener, menuItem, menuKeyListener, mouseInputListener, oldBorderPainted, propertyChangeListener, selectionBackground, selectionForeground
Constructor Summary
BasicRadioButtonMenuItemUI()
Method Summary
static ComponentUI | createUI(JComponent b)
protected String | getPropertyPrefix()
void | processMouseEvent(JMenuItem item, MouseEvent e, MenuElement[] path, MenuSelectionManager manager)
Methods inherited from class javax.swing.plaf.basic.BasicMenuItemUI
createMenuDragMouseListener, createMenuKeyListener, createMouseInputListener, createPropertyChangeListener, doClick, getMaximumSize, getMinimumSize, getPath, getPreferredMenuItemSize, getPreferredSize, installComponents, installDefaults, installKeyboardActions, installListeners, installUI, paint, paintBackground, paintMenuItem, paintText, uninstallComponents, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, uninstallUI, update
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicRadioButtonMenuItemUI

public BasicRadioButtonMenuItemUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent b)

getPropertyPrefix

protected String getPropertyPrefix()
Overrides:
getPropertyPrefix in class BasicMenuItemUI

processMouseEvent

public void processMouseEvent(JMenuItem item,
                              MouseEvent e,
                              MenuElement[] path,
                              MenuSelectionManager manager)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicRadioButtonUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicRadioButtonUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ButtonUI
            extended by  javax.swing.plaf.basic.BasicButtonUI
                extended by  javax.swing.plaf.basic.BasicToggleButtonUI
                    extended by  javax.swing.plaf.basic.BasicRadioButtonUI
Direct Known Subclasses:
BasicCheckBoxUI, MetalRadioButtonUI
public class BasicRadioButtonUI
extends BasicToggleButtonUI

RadioButtonUI implementation for BasicRadioButtonUI

Field Summary
protected  Icon icon
Fields inherited from class javax.swing.plaf.basic.BasicButtonUI
defaultTextIconGap, defaultTextShiftOffset
Constructor Summary
BasicRadioButtonUI()
Method Summary
static ComponentUI | createUI(JComponent b)
Icon | getDefaultIcon()
Dimension | getPreferredSize(JComponent c) The preferred size of the radio button
protected String | getPropertyPrefix()
protected void | installDefaults(AbstractButton b)
void | paint(Graphics g, JComponent c) paint the radio button
protected void | paintFocus(Graphics g, Rectangle textRect, Dimension size)
protected void | uninstallDefaults(AbstractButton b)
Methods inherited from class javax.swing.plaf.basic.BasicToggleButtonUI
getTextShiftOffset, paintIcon
Methods inherited from class javax.swing.plaf.basic.BasicButtonUI
clearTextShiftOffset, createButtonListener, getBaseline, getBaselineResizeBehavior, getDefaultTextIconGap, getMaximumSize, getMinimumSize, installKeyboardActions, installListeners, installUI, paintButtonPressed, paintFocus, paintIcon, paintText, paintText, setTextShiftOffset, uninstallKeyboardActions, uninstallListeners, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

icon

protected Icon icon
Constructor Detail

BasicRadioButtonUI

public BasicRadioButtonUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent b)

getPropertyPrefix

protected String getPropertyPrefix()
Overrides:
getPropertyPrefix in class BasicToggleButtonUI

installDefaults

protected void installDefaults(AbstractButton b)
Overrides:
installDefaults in class BasicButtonUI

uninstallDefaults

protected void uninstallDefaults(AbstractButton b)
Overrides:
uninstallDefaults in class BasicButtonUI

getDefaultIcon

public Icon getDefaultIcon()

paint

public void paint(Graphics g,
                  JComponent c)
paint the radio button

Overrides:
paint in class BasicToggleButtonUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

paintFocus

protected void paintFocus(Graphics g,
                          Rectangle textRect,
                          Dimension size)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
The preferred size of the radio button

Overrides:
getPreferredSize in class BasicButtonUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicRootPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicRootPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.RootPaneUI
            extended by  javax.swing.plaf.basic.BasicRootPaneUI
All Implemented Interfaces:
PropertyChangeListener, EventListener
Direct Known Subclasses:
MetalRootPaneUI
public class BasicRootPaneUI
extends RootPaneUI
implements PropertyChangeListener

Basic implementation of RootPaneUI, there is one shared between all JRootPane instances.

Since:
1.3

Constructor Summary
BasicRootPaneUI()
Method Summary
static ComponentUI | createUI(JComponent c)
protected void | installComponents(JRootPane root)
protected void | installDefaults(JRootPane c)
protected void | installKeyboardActions(JRootPane root)
protected void | installListeners(JRootPane root)
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
void | propertyChange(PropertyChangeEvent e) Invoked when a property changes on the root pane.
protected void | uninstallComponents(JRootPane root)
protected void | uninstallDefaults(JRootPane root)
protected void | uninstallKeyboardActions(JRootPane root)
protected void | uninstallListeners(JRootPane root)
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, paint, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicRootPaneUI

public BasicRootPaneUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installDefaults

protected void installDefaults(JRootPane c)

installComponents

protected void installComponents(JRootPane root)

installListeners

protected void installListeners(JRootPane root)

installKeyboardActions

protected void installKeyboardActions(JRootPane root)

uninstallDefaults

protected void uninstallDefaults(JRootPane root)

uninstallComponents

protected void uninstallComponents(JRootPane root)

uninstallListeners

protected void uninstallListeners(JRootPane root)

uninstallKeyboardActions

protected void uninstallKeyboardActions(JRootPane root)

propertyChange

public void propertyChange(PropertyChangeEvent e)
Invoked when a property changes on the root pane. If the event indicates the defaultButton has changed, this will reinstall the keyboard actions.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicScrollBarUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicScrollBarUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ScrollBarUI
            extended by  javax.swing.plaf.basic.BasicScrollBarUI
All Implemented Interfaces:
LayoutManager, SwingConstants
Direct Known Subclasses:
MetalScrollBarUI
public class BasicScrollBarUI
extends ScrollBarUI
implements LayoutManager, SwingConstants

Implementation of ScrollBarUI for the Basic Look and Feel

Nested Class Summary
protected class | BasicScrollBarUI.ArrowButtonListener Listener for cursor keys.
protected class | BasicScrollBarUI.ModelListener A listener to listen for model changes.
class | BasicScrollBarUI.PropertyChangeHandler
protected class | BasicScrollBarUI.ScrollListener Listener for scrolling events initiated in the ScrollPane.
protected class | BasicScrollBarUI.TrackListener Track mouse drags.
Field Summary
protected BasicScrollBarUI.ArrowButtonListener | buttonListener
protected JButton | decrButton
protected static int | DECREASE_HIGHLIGHT
protected JButton | incrButton
protected static int | INCREASE_HIGHLIGHT
protected boolean | isDragging
protected Dimension | maximumThumbSize
protected Dimension | minimumThumbSize
protected BasicScrollBarUI.ModelListener | modelListener
protected static int | NO_HIGHLIGHT
protected PropertyChangeListener | propertyChangeListener
protected JScrollBar | scrollbar
protected BasicScrollBarUI.ScrollListener | scrollListener
protected Timer | scrollTimer
protected Color | thumbColor
protected Color | thumbDarkShadowColor
protected Color | thumbHighlightColor
protected Color | thumbLightShadowColor
protected Rectangle | thumbRect
protected Color | trackColor
protected int | trackHighlight
protected Color | trackHighlightColor
protected BasicScrollBarUI.TrackListener | trackListener
protected Rectangle | trackRect
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
BasicScrollBarUI()
Method Summary
void | addLayoutComponent(String name, Component child) If the layout manager uses a per-component string, adds the component comp to the layout, associating it with the string specified by name.
protected void | configureScrollBarColors()
protected BasicScrollBarUI.ArrowButtonListener | createArrowButtonListener()
protected JButton | createDecreaseButton(int orientation)
protected JButton | createIncreaseButton(int orientation)
protected BasicScrollBarUI.ModelListener | createModelListener()
protected PropertyChangeListener | createPropertyChangeListener()
protected BasicScrollBarUI.ScrollListener | createScrollListener()
protected BasicScrollBarUI.TrackListener | createTrackListener()
static ComponentUI | createUI(JComponent c)
Dimension | getMaximumSize(JComponent c) Returns the specified component's maximum size appropriate for the look and feel.
protected Dimension | getMaximumThumbSize() Return the largest acceptable size for the thumb.
protected Dimension | getMinimumThumbSize() Return the smallest acceptable size for the thumb.
Dimension | getPreferredSize(JComponent c) A vertical scrollbar's preferred width is the maximum of preferred widths of the (non null) increment/decrement buttons, and the minimum width of the thumb.
boolean | getSupportsAbsolutePositioning() Indicates whether the user can absolutely position the thumb with a mouse gesture (usually the middle mouse button).
protected Rectangle | getThumbBounds() Return the current size/location of the thumb.
protected Rectangle | getTrackBounds() Returns the current bounds of the track, i.e.
protected void | installComponents()
protected void | installDefaults()
protected void | installKeyboardActions()
protected void | installListeners()
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
boolean | isThumbRollover() Returns true if the mouse is currently over the thumb.
void | layoutContainer(Container scrollbarContainer) Lays out the specified container.
protected void | layoutHScrollbar(JScrollBar sb)
protected void | layoutVScrollbar(JScrollBar sb)
Dimension | minimumLayoutSize(Container scrollbarContainer) Calculates the minimum size dimensions for the specified container, given the components it contains.
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
protected void | paintDecreaseHighlight(Graphics g)
protected void | paintIncreaseHighlight(Graphics g)
protected void | paintThumb(Graphics g, JComponent c, Rectangle thumbBounds)
protected void | paintTrack(Graphics g, JComponent c, Rectangle trackBounds)
Dimension | preferredLayoutSize(Container scrollbarContainer) Calculates the preferred size dimensions for the specified container, given the components it contains.
void | removeLayoutComponent(Component child) Removes the specified component from the layout.
protected void | scrollByBlock(int direction)
protected void | scrollByUnit(int direction)
protected void | setThumbBounds(int x, int y, int width, int height) Set the bounds of the thumb and force a repaint that includes the old thumbBounds and the new one.
protected void | setThumbRollover(boolean active) Sets whether or not the mouse is currently over the thumb.
protected void | uninstallComponents()
protected void | uninstallDefaults()
protected void | uninstallKeyboardActions()
protected void | uninstallListeners()
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMinimumSize, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

minimumThumbSize

protected Dimension minimumThumbSize

maximumThumbSize

protected Dimension maximumThumbSize

thumbHighlightColor

protected Color thumbHighlightColor

thumbLightShadowColor

protected Color thumbLightShadowColor

thumbDarkShadowColor

protected Color thumbDarkShadowColor

thumbColor

protected Color thumbColor

trackColor

protected Color trackColor

trackHighlightColor

protected Color trackHighlightColor

scrollbar

protected JScrollBar scrollbar

incrButton

protected JButton incrButton

decrButton

protected JButton decrButton

isDragging

protected boolean isDragging

trackListener

protected BasicScrollBarUI.TrackListener trackListener

buttonListener

protected BasicScrollBarUI.ArrowButtonListener buttonListener

modelListener

protected BasicScrollBarUI.ModelListener modelListener

thumbRect

protected Rectangle thumbRect

trackRect

protected Rectangle trackRect

trackHighlight

protected int trackHighlight

NO_HIGHLIGHT

protected static final int NO_HIGHLIGHT
See Also:
Constant Field Values

DECREASE_HIGHLIGHT

protected static final int DECREASE_HIGHLIGHT
See Also:
Constant Field Values

INCREASE_HIGHLIGHT

protected static final int INCREASE_HIGHLIGHT
See Also:
Constant Field Values

scrollListener

protected BasicScrollBarUI.ScrollListener scrollListener

propertyChangeListener

protected PropertyChangeListener propertyChangeListener

scrollTimer

protected Timer scrollTimer
Constructor Detail

BasicScrollBarUI

public BasicScrollBarUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

configureScrollBarColors

protected void configureScrollBarColors()

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installDefaults

protected void installDefaults()

installComponents

protected void installComponents()

uninstallComponents

protected void uninstallComponents()

installListeners

protected void installListeners()

installKeyboardActions

protected void installKeyboardActions()

uninstallKeyboardActions

protected void uninstallKeyboardActions()

uninstallListeners

protected void uninstallListeners()

uninstallDefaults

protected void uninstallDefaults()

createTrackListener

protected BasicScrollBarUI.TrackListener createTrackListener()

createArrowButtonListener

protected BasicScrollBarUI.ArrowButtonListener createArrowButtonListener()

createModelListener

protected BasicScrollBarUI.ModelListener createModelListener()

createScrollListener

protected BasicScrollBarUI.ScrollListener createScrollListener()

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener()

setThumbRollover

protected void setThumbRollover(boolean active)
Sets whether or not the mouse is currently over the thumb.

Parameters:
active - True indicates the thumb is currently active.
Since:
1.5

isThumbRollover

public boolean isThumbRollover()
Returns true if the mouse is currently over the thumb.

Returns:
true if the thumb is currently active
Since:
1.5

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
A vertical scrollbar's preferred width is the maximum of preferred widths of the (non null) increment/decrement buttons, and the minimum width of the thumb. The preferred height is the sum of the preferred heights of the same parts. The basis for the preferred size of a horizontal scrollbar is similar.

The preferredSize is only computed once, subsequent calls to this method just return a cached size.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - the JScrollBar that's delegating this method to us
Returns:
the preferred size of a Basic JScrollBar
See Also:
getMaximumSize(javax.swing.JComponent), ComponentUI.getMinimumSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's maximum size appropriate for the look and feel. If null is returned, the maximum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - The JScrollBar that's delegating this method to us.
Returns:
new Dimension(Integer.MAX_VALUE, Integer.MAX_VALUE);
See Also:
ComponentUI.getMinimumSize(javax.swing.JComponent), getPreferredSize(javax.swing.JComponent)

createDecreaseButton

protected JButton createDecreaseButton(int orientation)

createIncreaseButton

protected JButton createIncreaseButton(int orientation)

paintDecreaseHighlight

protected void paintDecreaseHighlight(Graphics g)

paintIncreaseHighlight

protected void paintIncreaseHighlight(Graphics g)

paintTrack

protected void paintTrack(Graphics g,
                          JComponent c,
                          Rectangle trackBounds)

paintThumb

protected void paintThumb(Graphics g,
                          JComponent c,
                          Rectangle thumbBounds)

getMinimumThumbSize

protected Dimension getMinimumThumbSize()
Return the smallest acceptable size for the thumb. If the scrollbar becomes so small that this size isn't available, the thumb will be hidden.

Warning : the value returned by this method should not be be modified, it's a shared static constant.

Returns:
The smallest acceptable size for the thumb.
See Also:
getMaximumThumbSize()

getMaximumThumbSize

protected Dimension getMaximumThumbSize()
Return the largest acceptable size for the thumb. To create a fixed size thumb one make this method and getMinimumThumbSize return the same value.

Warning : the value returned by this method should not be be modified, it's a shared static constant.

Returns:
The largest acceptable size for the thumb.
See Also:
getMinimumThumbSize()

addLayoutComponent

public void addLayoutComponent(String name,
                               Component child)
Description copied from interface: LayoutManager
If the layout manager uses a per-component string, adds the component comp to the layout, associating it with the string specified by name.

Specified by:
addLayoutComponent in interface LayoutManager
Parameters:
name - the string to be associated with the component
child - the component to be added

removeLayoutComponent

public void removeLayoutComponent(Component child)
Description copied from interface: LayoutManager
Removes the specified component from the layout.

Specified by:
removeLayoutComponent in interface LayoutManager
Parameters:
child - the component to be removed

preferredLayoutSize

public Dimension preferredLayoutSize(Container scrollbarContainer)
Description copied from interface: LayoutManager
Calculates the preferred size dimensions for the specified container, given the components it contains.

Specified by:
preferredLayoutSize in interface LayoutManager
Parameters:
scrollbarContainer - the container to be laid out
See Also:
LayoutManager.minimumLayoutSize(java.awt.Container)

minimumLayoutSize

public Dimension minimumLayoutSize(Container scrollbarContainer)
Description copied from interface: LayoutManager
Calculates the minimum size dimensions for the specified container, given the components it contains.

Specified by:
minimumLayoutSize in interface LayoutManager
Parameters:
scrollbarContainer - the component to be laid out
See Also:
LayoutManager.preferredLayoutSize(java.awt.Container)

layoutVScrollbar

protected void layoutVScrollbar(JScrollBar sb)

layoutHScrollbar

protected void layoutHScrollbar(JScrollBar sb)

layoutContainer

public void layoutContainer(Container scrollbarContainer)
Description copied from interface: LayoutManager
Lays out the specified container.

Specified by:
layoutContainer in interface LayoutManager
Parameters:
scrollbarContainer - the container to be laid out

setThumbBounds

protected void setThumbBounds(int x,
                              int y,
                              int width,
                              int height)
Set the bounds of the thumb and force a repaint that includes the old thumbBounds and the new one.

See Also:
getThumbBounds()

getThumbBounds

protected Rectangle getThumbBounds()
Return the current size/location of the thumb.

Warning : the value returned by this method should not be be modified, it's a reference to the actual rectangle, not a copy.

Returns:
The current size/location of the thumb.
See Also:
setThumbBounds(int, int, int, int)

getTrackBounds

protected Rectangle getTrackBounds()
Returns the current bounds of the track, i.e. the space in between the increment and decrement buttons, less the insets. The value returned by this method is updated each time the scrollbar is laid out (validated).

Warning : the value returned by this method should not be be modified, it's a reference to the actual rectangle, not a copy.

Returns:
the current bounds of the scrollbar track
See Also:
layoutContainer(java.awt.Container)

scrollByBlock

protected void scrollByBlock(int direction)

scrollByUnit

protected void scrollByUnit(int direction)

getSupportsAbsolutePositioning

public boolean getSupportsAbsolutePositioning()
Indicates whether the user can absolutely position the thumb with a mouse gesture (usually the middle mouse button).

Returns:
true if a mouse gesture can absolutely position the thumb
Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicScrollBarUI.ArrowButtonListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicScrollBarUI.ArrowButtonListener

java.lang.Object
    extended by  java.awt.event.MouseAdapter
        extended by  javax.swing.plaf.basic.BasicScrollBarUI.ArrowButtonListener
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, EventListener
Enclosing class:
BasicScrollBarUI
protected class BasicScrollBarUI.ArrowButtonListener
extends MouseAdapter

Listener for cursor keys.

Constructor Summary
protected BasicScrollBarUI.ArrowButtonListener()
Method Summary
void | mousePressed(MouseEvent e) Invoked when a mouse button has been pressed on a component.
void | mouseReleased(MouseEvent e) Invoked when a mouse button has been released on a component.
Methods inherited from class java.awt.event.MouseAdapter
mouseClicked, mouseDragged, mouseEntered, mouseExited, mouseMoved, mouseWheelMoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicScrollBarUI.ArrowButtonListener

protected BasicScrollBarUI.ArrowButtonListener()
Method Detail

mousePressed

public void mousePressed(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when a mouse button has been pressed on a component.

Specified by:
mousePressed in interface MouseListener
Overrides:
mousePressed in class MouseAdapter

mouseReleased

public void mouseReleased(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when a mouse button has been released on a component.

Specified by:
mouseReleased in interface MouseListener
Overrides:
mouseReleased in class MouseAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicScrollBarUI.ModelListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicScrollBarUI.ModelListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicScrollBarUI.ModelListener
All Implemented Interfaces:
EventListener, ChangeListener
Enclosing class:
BasicScrollBarUI
protected class BasicScrollBarUI.ModelListener
extends Object
implements ChangeListener

A listener to listen for model changes.

Constructor Summary
protected BasicScrollBarUI.ModelListener()
Method Summary
 void stateChanged(ChangeEvent e)
Invoked when the target of the listener has changed its state.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicScrollBarUI.ModelListener

protected BasicScrollBarUI.ModelListener()
Method Detail

stateChanged

public void stateChanged(ChangeEvent e)
Description copied from interface: ChangeListener
Invoked when the target of the listener has changed its state.

Specified by:
stateChanged in interface ChangeListener
Parameters:
e - a ChangeEvent object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicScrollBarUI.PropertyChangeHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicScrollBarUI.PropertyChangeHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicScrollBarUI.PropertyChangeHandler
All Implemented Interfaces:
PropertyChangeListener, EventListener
Enclosing class:
BasicScrollBarUI
public class BasicScrollBarUI.PropertyChangeHandler
extends Object
implements PropertyChangeListener

Constructor Summary
BasicScrollBarUI.PropertyChangeHandler()
Method Summary
 void propertyChange(PropertyChangeEvent e)
This method gets called when a bound property is changed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicScrollBarUI.PropertyChangeHandler

public BasicScrollBarUI.PropertyChangeHandler()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicScrollBarUI.ScrollListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicScrollBarUI.ScrollListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicScrollBarUI.ScrollListener
All Implemented Interfaces:
ActionListener, EventListener
Enclosing class:
BasicScrollBarUI
protected class BasicScrollBarUI.ScrollListener
extends Object
implements ActionListener

Listener for scrolling events initiated in the ScrollPane.

Constructor Summary
BasicScrollBarUI.ScrollListener()
BasicScrollBarUI.ScrollListener(int dir, boolean block)
Method Summary
void | actionPerformed(ActionEvent e) Invoked when an action occurs.
void | setDirection(int direction)
void | setScrollByBlock(boolean block)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicScrollBarUI.ScrollListener

public BasicScrollBarUI.ScrollListener()

BasicScrollBarUI.ScrollListener

public BasicScrollBarUI.ScrollListener(int dir,
                                       boolean block)
Method Detail

setDirection

public void setDirection(int direction)

setScrollByBlock

public void setScrollByBlock(boolean block)

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

Specified by:
actionPerformed in interface ActionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicScrollBarUI.TrackListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicScrollBarUI.TrackListener

java.lang.Object
    extended by  java.awt.event.MouseAdapter
        extended by  javax.swing.plaf.basic.BasicScrollBarUI.TrackListener
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, EventListener
Enclosing class:
BasicScrollBarUI
protected class BasicScrollBarUI.TrackListener
extends MouseAdapter
implements MouseMotionListener

Track mouse drags.

Field Summary
protected int | currentMouseX
protected int | currentMouseY
protected int | offset
Constructor Summary
protected BasicScrollBarUI.TrackListener()
Method Summary
void | mouseDragged(MouseEvent e) Set the models value to the position of the thumb's top of Vertical scrollbar, or the left/right of Horizontal scrollbar in left-to-right/right-to-left scrollbar relative to the origin of the track.
void | mouseExited(MouseEvent e) Invoked when the mouse exits the scrollbar.
void | mouseMoved(MouseEvent e) Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.
void | mousePressed(MouseEvent e) If the mouse is pressed above the "thumb" component then reduce the scrollbars value by one page ("page up"), otherwise increase it by one page.
void | mouseReleased(MouseEvent e) Invoked when a mouse button has been released on a component.
Methods inherited from class java.awt.event.MouseAdapter
mouseClicked, mouseEntered, mouseWheelMoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

offset

protected transient int offset

currentMouseX

protected transient int currentMouseX

currentMouseY

protected transient int currentMouseY
Constructor Detail

BasicScrollBarUI.TrackListener

protected BasicScrollBarUI.TrackListener()
Method Detail

mouseReleased

public void mouseReleased(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when a mouse button has been released on a component.

Specified by:
mouseReleased in interface MouseListener
Overrides:
mouseReleased in class MouseAdapter

mousePressed

public void mousePressed(MouseEvent e)
If the mouse is pressed above the "thumb" component then reduce the scrollbars value by one page ("page up"), otherwise increase it by one page. If there is no thumb then page up if the mouse is in the upper half of the track.

Specified by:
mousePressed in interface MouseListener
Overrides:
mousePressed in class MouseAdapter

mouseDragged

public void mouseDragged(MouseEvent e)
Set the models value to the position of the thumb's top of Vertical scrollbar, or the left/right of Horizontal scrollbar in left-to-right/right-to-left scrollbar relative to the origin of the track.

Specified by:
mouseDragged in interface MouseMotionListener
Overrides:
mouseDragged in class MouseAdapter

mouseMoved

public void mouseMoved(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.

Specified by:
mouseMoved in interface MouseMotionListener
Overrides:
mouseMoved in class MouseAdapter

mouseExited

public void mouseExited(MouseEvent e)
Invoked when the mouse exits the scrollbar.

Specified by:
mouseExited in interface MouseListener
Overrides:
mouseExited in class MouseAdapter
Parameters:
e - MouseEvent further describing the event
Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicScrollPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicScrollPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ScrollPaneUI
            extended by  javax.swing.plaf.basic.BasicScrollPaneUI
All Implemented Interfaces:
ScrollPaneConstants
Direct Known Subclasses:
MetalScrollPaneUI
public class BasicScrollPaneUI
extends ScrollPaneUI
implements ScrollPaneConstants

A default L&F implementation of ScrollPaneUI.

Nested Class Summary
class | BasicScrollPaneUI.HSBChangeListener Horizontal scrollbar listener.
protected class | BasicScrollPaneUI.MouseWheelHandler MouseWheelHandler is an inner class which implements the MouseWheelListener interface.
class | BasicScrollPaneUI.PropertyChangeHandler
class | BasicScrollPaneUI.ViewportChangeHandler Listener for viewport events.
class | BasicScrollPaneUI.VSBChangeListener Vertical scrollbar listener.
Field Summary
protected ChangeListener | hsbChangeListener
protected JScrollPane | scrollpane
protected PropertyChangeListener | spPropertyChangeListener
protected ChangeListener | viewportChangeListener
protected ChangeListener | vsbChangeListener
Fields inherited from interface javax.swing.ScrollPaneConstants
COLUMN_HEADER, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_ALWAYS, HORIZONTAL_SCROLLBAR_AS_NEEDED, HORIZONTAL_SCROLLBAR_NEVER, HORIZONTAL_SCROLLBAR_POLICY, LOWER_LEADING_CORNER, LOWER_LEFT_CORNER, LOWER_RIGHT_CORNER, LOWER_TRAILING_CORNER, ROW_HEADER, UPPER_LEADING_CORNER, UPPER_LEFT_CORNER, UPPER_RIGHT_CORNER, UPPER_TRAILING_CORNER, VERTICAL_SCROLLBAR, VERTICAL_SCROLLBAR_ALWAYS, VERTICAL_SCROLLBAR_AS_NEEDED, VERTICAL_SCROLLBAR_NEVER, VERTICAL_SCROLLBAR_POLICY, VIEWPORT
Constructor Summary
BasicScrollPaneUI()
Method Summary
protected  ChangeListener createHSBChangeListener()
protected  MouseWheelListener createMouseWheelListener()
Creates an instance of MouseWheelListener, which is added to the JScrollPane by installUI().
protected  PropertyChangeListener createPropertyChangeListener()
Creates an instance of PropertyChangeListener that's added to the JScrollPane by installUI().
static ComponentUI createUI(JComponent x)
protected  ChangeListener createViewportChangeListener()
protected  ChangeListener createVSBChangeListener()
 int getBaseline(JComponent c, int width, int height)
Returns the baseline.
 Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Dimension getMaximumSize(JComponent c)
Returns the specified component's maximum size appropriate for the look and feel.
protected  void installDefaults(JScrollPane scrollpane)
protected  void installKeyboardActions(JScrollPane c)
protected  void installListeners(JScrollPane c)
 void installUI(JComponent x)
Configures the specified component appropriate for the look and feel.
 void paint(Graphics g, JComponent c)
Paints the specified component appropriate for the look and feel.
protected  void syncScrollPaneWithViewport()
protected  void uninstallDefaults(JScrollPane c)
protected  void uninstallKeyboardActions(JScrollPane c)
protected  void uninstallListeners(JComponent c)
 void uninstallUI(JComponent c)
Reverses configuration which was done on the specified component during installUI.
protected  void updateColumnHeader(PropertyChangeEvent e)
protected  void updateRowHeader(PropertyChangeEvent e)
protected  void updateScrollBarDisplayPolicy(PropertyChangeEvent e)
protected  void updateViewport(PropertyChangeEvent e)
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getMinimumSize, getPreferredSize, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

scrollpane

protected JScrollPane scrollpane

vsbChangeListener

protected ChangeListener vsbChangeListener

hsbChangeListener

protected ChangeListener hsbChangeListener

viewportChangeListener

protected ChangeListener viewportChangeListener

spPropertyChangeListener

protected PropertyChangeListener spPropertyChangeListener
Constructor Detail

BasicScrollPaneUI

public BasicScrollPaneUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent x)

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's maximum size appropriate for the look and feel. If null is returned, the maximum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
new Dimension(Short.MAX_VALUE, Short.MAX_VALUE)
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

installDefaults

protected void installDefaults(JScrollPane scrollpane)

installListeners

protected void installListeners(JScrollPane c)

installKeyboardActions

protected void installKeyboardActions(JScrollPane c)

installUI

public void installUI(JComponent x)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
x - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallDefaults

protected void uninstallDefaults(JScrollPane c)

uninstallListeners

protected void uninstallListeners(JComponent c)

uninstallKeyboardActions

protected void uninstallKeyboardActions(JScrollPane c)

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

syncScrollPaneWithViewport

protected void syncScrollPaneWithViewport()

getBaseline

public int getBaseline(JComponent c,
                       int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class ComponentUI
Parameters:
c - JComponent baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
NullPointerException - if c is null
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.

Overrides:
getBaselineResizeBehavior in class ComponentUI
Parameters:
c - JComponent to return baseline resize behavior for
Returns:
an enum indicating how the baseline changes as the component size changes
Throws:
NullPointerException - if c is null
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

createViewportChangeListener

protected ChangeListener createViewportChangeListener()

createHSBChangeListener

protected ChangeListener createHSBChangeListener()

createVSBChangeListener

protected ChangeListener createVSBChangeListener()

createMouseWheelListener

protected MouseWheelListener createMouseWheelListener()
Creates an instance of MouseWheelListener, which is added to the JScrollPane by installUI(). The returned MouseWheelListener is used to handle mouse wheel-driven scrolling.

Returns:
MouseWheelListener which implements wheel-driven scrolling
Since:
1.4
See Also:
installUI(javax.swing.JComponent), BasicScrollPaneUI.MouseWheelHandler

updateScrollBarDisplayPolicy

protected void updateScrollBarDisplayPolicy(PropertyChangeEvent e)

updateViewport

protected void updateViewport(PropertyChangeEvent e)

updateRowHeader

protected void updateRowHeader(PropertyChangeEvent e)

updateColumnHeader

protected void updateColumnHeader(PropertyChangeEvent e)

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener()
Creates an instance of PropertyChangeListener that's added to the JScrollPane by installUI(). Subclasses can override this method to return a custom PropertyChangeListener, e.g.
 class MyScrollPaneUI extends BasicScrollPaneUI {
    protected PropertyChangeListener createPropertyChangeListener() {
        return new MyPropertyChangeListener();
    }
    public class MyPropertyChangeListener extends PropertyChangeListener {
        public void propertyChange(PropertyChangeEvent e) {
            if (e.getPropertyName().equals("viewport")) {
                // do some extra work when the viewport changes
            }
            super.propertyChange(e);
        }
    }
 }

See Also:
PropertyChangeListener, installUI(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicScrollPaneUI.HSBChangeListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicScrollPaneUI.HSBChangeListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicScrollPaneUI.HSBChangeListener
All Implemented Interfaces:
EventListener, ChangeListener
Enclosing class:
BasicScrollPaneUI
public class BasicScrollPaneUI.HSBChangeListener
extends Object
implements ChangeListener

Horizontal scrollbar listener.

Constructor Summary
BasicScrollPaneUI.HSBChangeListener()
Method Summary
 void stateChanged(ChangeEvent e)
Invoked when the target of the listener has changed its state.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicScrollPaneUI.HSBChangeListener

public BasicScrollPaneUI.HSBChangeListener()
Method Detail

stateChanged

public void stateChanged(ChangeEvent e)
Description copied from interface: ChangeListener
Invoked when the target of the listener has changed its state.

Specified by:
stateChanged in interface ChangeListener
Parameters:
e - a ChangeEvent object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicScrollPaneUI.MouseWheelHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicScrollPaneUI.MouseWheelHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicScrollPaneUI.MouseWheelHandler
All Implemented Interfaces:
MouseWheelListener, EventListener
Enclosing class:
BasicScrollPaneUI
protected class BasicScrollPaneUI.MouseWheelHandler
extends Object
implements MouseWheelListener

MouseWheelHandler is an inner class which implements the MouseWheelListener interface. MouseWheelHandler responds to MouseWheelEvents by scrolling the JScrollPane appropriately. If the scroll pane's isWheelScrollingEnabled method returns false, no scrolling occurs.

Since:
1.4
See Also:
JScrollPane.isWheelScrollingEnabled(), BasicScrollPaneUI.createMouseWheelListener(), MouseWheelListener, MouseWheelEvent

Constructor Summary
protected BasicScrollPaneUI.MouseWheelHandler()
Method Summary
 void mouseWheelMoved(MouseWheelEvent e)
Called when the mouse wheel is rotated while over a JScrollPane.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicScrollPaneUI.MouseWheelHandler

protected BasicScrollPaneUI.MouseWheelHandler()
Method Detail

mouseWheelMoved

public void mouseWheelMoved(MouseWheelEvent e)
Called when the mouse wheel is rotated while over a JScrollPane.

Specified by:
mouseWheelMoved in interface MouseWheelListener
Parameters:
e - MouseWheelEvent to be handled
Since:
1.4
See Also:
MouseWheelEvent
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicScrollPaneUI.PropertyChangeHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicScrollPaneUI.PropertyChangeHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicScrollPaneUI.PropertyChangeHandler
All Implemented Interfaces:
PropertyChangeListener, EventListener
Enclosing class:
BasicScrollPaneUI
public class BasicScrollPaneUI.PropertyChangeHandler
extends Object
implements PropertyChangeListener

Constructor Summary
BasicScrollPaneUI.PropertyChangeHandler()
Method Summary
 void propertyChange(PropertyChangeEvent e)
This method gets called when a bound property is changed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicScrollPaneUI.PropertyChangeHandler

public BasicScrollPaneUI.PropertyChangeHandler()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicScrollPaneUI.ViewportChangeHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicScrollPaneUI.ViewportChangeHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicScrollPaneUI.ViewportChangeHandler
All Implemented Interfaces:
EventListener, ChangeListener
Enclosing class:
BasicScrollPaneUI
public class BasicScrollPaneUI.ViewportChangeHandler
extends Object
implements ChangeListener

Listener for viewport events.

Constructor Summary
BasicScrollPaneUI.ViewportChangeHandler()
Method Summary
 void stateChanged(ChangeEvent e)
Invoked when the target of the listener has changed its state.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicScrollPaneUI.ViewportChangeHandler

public BasicScrollPaneUI.ViewportChangeHandler()
Method Detail

stateChanged

public void stateChanged(ChangeEvent e)
Description copied from interface: ChangeListener
Invoked when the target of the listener has changed its state.

Specified by:
stateChanged in interface ChangeListener
Parameters:
e - a ChangeEvent object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicScrollPaneUI.VSBChangeListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicScrollPaneUI.VSBChangeListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicScrollPaneUI.VSBChangeListener
All Implemented Interfaces:
EventListener, ChangeListener
Enclosing class:
BasicScrollPaneUI
public class BasicScrollPaneUI.VSBChangeListener
extends Object
implements ChangeListener

Vertical scrollbar listener.

Constructor Summary
BasicScrollPaneUI.VSBChangeListener()
Method Summary
 void stateChanged(ChangeEvent e)
Invoked when the target of the listener has changed its state.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicScrollPaneUI.VSBChangeListener

public BasicScrollPaneUI.VSBChangeListener()
Method Detail

stateChanged

public void stateChanged(ChangeEvent e)
Description copied from interface: ChangeListener
Invoked when the target of the listener has changed its state.

Specified by:
stateChanged in interface ChangeListener
Parameters:
e - a ChangeEvent object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSeparatorUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSeparatorUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SeparatorUI
            extended by  javax.swing.plaf.basic.BasicSeparatorUI
Direct Known Subclasses:
BasicPopupMenuSeparatorUI, BasicToolBarSeparatorUI, MetalSeparatorUI
public class BasicSeparatorUI
extends SeparatorUI

A Basic L&F implementation of SeparatorUI. This implementation is a "combined" view/controller.

Field Summary
protected Color | highlight
protected Color | shadow
Constructor Summary
BasicSeparatorUI()
Method Summary
static ComponentUI | createUI(JComponent c)
Dimension | getMaximumSize(JComponent c) Returns the specified component's maximum size appropriate for the look and feel.
Dimension | getMinimumSize(JComponent c) Returns the specified component's minimum size appropriate for the look and feel.
Dimension | getPreferredSize(JComponent c) Returns the specified component's preferred size appropriate for the look and feel.
protected void | installDefaults(JSeparator s)
protected void | installListeners(JSeparator s)
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
protected void | uninstallDefaults(JSeparator s)
protected void | uninstallListeners(JSeparator s)
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

shadow

protected Color shadow

highlight

protected Color highlight
Constructor Detail

BasicSeparatorUI

public BasicSeparatorUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installDefaults

protected void installDefaults(JSeparator s)

uninstallDefaults

protected void uninstallDefaults(JSeparator s)

installListeners

protected void installListeners(JSeparator s)

uninstallListeners

protected void uninstallListeners(JSeparator s)

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's minimum size appropriate for the look and feel. If null is returned, the minimum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's maximum size appropriate for the look and feel. If null is returned, the maximum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSliderUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSliderUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SliderUI
            extended by  javax.swing.plaf.basic.BasicSliderUI
Direct Known Subclasses:
MetalSliderUI
public class BasicSliderUI
extends SliderUI

A Basic L&F implementation of SliderUI.

Nested Class Summary
class | BasicSliderUI.ActionScroller As of Java 2 platform v1.3 this undocumented class is no longer used.
class | BasicSliderUI.ChangeHandler Data model listener.
class | BasicSliderUI.ComponentHandler Listener for resizing events.
class | BasicSliderUI.FocusHandler Focus-change listener.
class | BasicSliderUI.PropertyChangeHandler
class | BasicSliderUI.ScrollListener Scroll-event listener.
class | BasicSliderUI.TrackListener Track mouse movements.
Field Summary
protected ChangeListener | changeListener
protected ComponentListener | componentListener
protected Rectangle | contentRect
protected Insets | focusInsets
protected FocusListener | focusListener
protected Rectangle | focusRect
protected Insets | insetCache
protected Rectangle | labelRect
protected boolean | leftToRightCache
static int | MAX_SCROLL
static int | MIN_SCROLL
static int | NEGATIVE_SCROLL
static int | POSITIVE_SCROLL
protected PropertyChangeListener | propertyChangeListener
protected BasicSliderUI.ScrollListener | scrollListener
protected Timer | scrollTimer
protected JSlider | slider
protected Rectangle | thumbRect
protected Rectangle | tickRect
protected int | trackBuffer
protected BasicSliderUI.TrackListener | trackListener
protected Rectangle | trackRect
Constructor Summary
BasicSliderUI(JSlider b)
Method Summary
protected void | calculateContentRect()
protected void | calculateFocusRect()
protected void | calculateGeometry()
protected void | calculateLabelRect()
protected void | calculateThumbLocation()
protected void | calculateThumbSize()
protected void | calculateTickRect()
protected void | calculateTrackBuffer()
protected void | calculateTrackRect()
protected ChangeListener | createChangeListener(JSlider slider)
protected ComponentListener | createComponentListener(JSlider slider)
protected FocusListener | createFocusListener(JSlider slider)
protected PropertyChangeListener | createPropertyChangeListener(JSlider slider)
protected BasicSliderUI.ScrollListener | createScrollListener(JSlider slider)
protected BasicSliderUI.TrackListener | createTrackListener(JSlider slider)
static ComponentUI | createUI(JComponent b)
protected boolean | drawInverted()
int | getBaseline(JComponent c, int width, int height) Returns the baseline.
Component.BaselineResizeBehavior | getBaselineResizeBehavior(JComponent c) Returns an enum indicating how the baseline of the component changes as the size changes.
protected Color | getFocusColor()
protected int | getHeightOfHighValueLabel()
protected int | getHeightOfLowValueLabel()
protected int | getHeightOfTallestLabel()
protected Integer | getHighestValue() Returns the biggest value that has an entry in the label table.
protected Component | getHighestValueLabel() Returns the label that corresponds to the lowest slider value in the label table.
protected Color | getHighlightColor()
protected Integer | getLowestValue() Returns the smallest value that has an entry in the label table.
protected Component | getLowestValueLabel() Returns the label that corresponds to the highest slider value in the label table.
Dimension | getMaximumSize(JComponent c) Returns the specified component's maximum size appropriate for the look and feel.
Dimension | getMinimumHorizontalSize()
Dimension | getMinimumSize(JComponent c) Returns the specified component's minimum size appropriate for the look and feel.
Dimension | getMinimumVerticalSize()
Dimension | getPreferredHorizontalSize()
Dimension | getPreferredSize(JComponent c) Returns the specified component's preferred size appropriate for the look and feel.
Dimension | getPreferredVerticalSize()
protected Color | getShadowColor()
protected Dimension | getThumbSize()
protected int | getTickLength() Gets the height of the tick area for horizontal sliders and the width of the tick area for vertical sliders.
protected int | getWidthOfHighValueLabel()
protected int | getWidthOfLowValueLabel()
protected int | getWidthOfWidestLabel()
protected void | installDefaults(JSlider slider)
protected void | installKeyboardActions(JSlider slider)
protected void | installListeners(JSlider slider)
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
protected boolean | isDragging() Returns true if the user is dragging the slider.
protected boolean | labelsHaveSameBaselines() Returns true if all the labels from the label table have the same baseline.
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
void | paintFocus(Graphics g)
protected void | paintHorizontalLabel(Graphics g, int value, Component label) Called for every label in the label table.
void | paintLabels(Graphics g)
protected void | paintMajorTickForHorizSlider(Graphics g, Rectangle tickBounds, int x)
protected void | paintMajorTickForVertSlider(Graphics g, Rectangle tickBounds, int y)
protected void | paintMinorTickForHorizSlider(Graphics g, Rectangle tickBounds, int x)
protected void | paintMinorTickForVertSlider(Graphics g, Rectangle tickBounds, int y)
void | paintThumb(Graphics g)
void | paintTicks(Graphics g)
void | paintTrack(Graphics g)
protected void | paintVerticalLabel(Graphics g, int value, Component label) Called for every label in the label table.
protected void | recalculateIfInsetsChanged()
protected void | recalculateIfOrientationChanged()
void | scrollByBlock(int direction)
void | scrollByUnit(int direction)
protected void | scrollDueToClickInTrack(int dir) This function is called when a mousePressed was detected in the track, not in the thumb.
void | setThumbLocation(int x, int y)
protected void | uninstallKeyboardActions(JSlider slider)
protected void | uninstallListeners(JSlider slider)
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
int | valueForXPosition(int xPos) Returns a value give an x position.
int | valueForYPosition(int yPos) Returns a value give a y position.
protected int | xPositionForValue(int value)
protected int | yPositionForValue(int value)
protected int | yPositionForValue(int value, int trackY, int trackHeight) Returns the y location for the specified value.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

POSITIVE_SCROLL

public static final int POSITIVE_SCROLL
See Also:
Constant Field Values

NEGATIVE_SCROLL

public static final int NEGATIVE_SCROLL
See Also:
Constant Field Values

MIN_SCROLL

public static final int MIN_SCROLL
See Also:
Constant Field Values

MAX_SCROLL

public static final int MAX_SCROLL
See Also:
Constant Field Values

scrollTimer

protected Timer scrollTimer

slider

protected JSlider slider

focusInsets

protected Insets focusInsets

insetCache

protected Insets insetCache

leftToRightCache

protected boolean leftToRightCache

focusRect

protected Rectangle focusRect

contentRect

protected Rectangle contentRect

labelRect

protected Rectangle labelRect

tickRect

protected Rectangle tickRect

trackRect

protected Rectangle trackRect

thumbRect

protected Rectangle thumbRect

trackBuffer

protected int trackBuffer

trackListener

protected BasicSliderUI.TrackListener trackListener

changeListener

protected ChangeListener changeListener

componentListener

protected ComponentListener componentListener

focusListener

protected FocusListener focusListener

scrollListener

protected BasicSliderUI.ScrollListener scrollListener

propertyChangeListener

protected PropertyChangeListener propertyChangeListener
Constructor Detail

BasicSliderUI

public BasicSliderUI(JSlider b)
Method Detail

getShadowColor

protected Color getShadowColor()

getHighlightColor

protected Color getHighlightColor()

getFocusColor

protected Color getFocusColor()

isDragging

protected boolean isDragging()
Returns true if the user is dragging the slider.

Returns:
true if the user is dragging the slider
Since:
1.5

createUI

public static ComponentUI createUI(JComponent b)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installDefaults

protected void installDefaults(JSlider slider)

createTrackListener

protected BasicSliderUI.TrackListener createTrackListener(JSlider slider)

createChangeListener

protected ChangeListener createChangeListener(JSlider slider)

createComponentListener

protected ComponentListener createComponentListener(JSlider slider)

createFocusListener

protected FocusListener createFocusListener(JSlider slider)

createScrollListener

protected BasicSliderUI.ScrollListener createScrollListener(JSlider slider)

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener(JSlider slider)

installListeners

protected void installListeners(JSlider slider)

uninstallListeners

protected void uninstallListeners(JSlider slider)

installKeyboardActions

protected void installKeyboardActions(JSlider slider)

uninstallKeyboardActions

protected void uninstallKeyboardActions(JSlider slider)

getBaseline

public int getBaseline(JComponent c,
                       int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class ComponentUI
Parameters:
c - JComponent baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
NullPointerException - if c is null
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.

Overrides:
getBaselineResizeBehavior in class ComponentUI
Parameters:
c - JComponent to return baseline resize behavior for
Returns:
an enum indicating how the baseline changes as the component size changes
Throws:
NullPointerException - if c is null
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

labelsHaveSameBaselines

protected boolean labelsHaveSameBaselines()
Returns true if all the labels from the label table have the same baseline.

Returns:
true if all the labels from the label table have the same baseline
Since:
1.6

getPreferredHorizontalSize

public Dimension getPreferredHorizontalSize()

getPreferredVerticalSize

public Dimension getPreferredVerticalSize()

getMinimumHorizontalSize

public Dimension getMinimumHorizontalSize()

getMinimumVerticalSize

public Dimension getMinimumVerticalSize()

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's minimum size appropriate for the look and feel. If null is returned, the minimum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's maximum size appropriate for the look and feel. If null is returned, the maximum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

calculateGeometry

protected void calculateGeometry()

calculateFocusRect

protected void calculateFocusRect()

calculateThumbSize

protected void calculateThumbSize()

calculateContentRect

protected void calculateContentRect()

calculateThumbLocation

protected void calculateThumbLocation()

calculateTrackBuffer

protected void calculateTrackBuffer()

calculateTrackRect

protected void calculateTrackRect()

getTickLength

protected int getTickLength()
Gets the height of the tick area for horizontal sliders and the width of the tick area for vertical sliders. BasicSliderUI uses the returned value to determine the tick area rectangle. If you want to give your ticks some room, make this larger than you need and paint your ticks away from the sides in paintTicks().

calculateTickRect

protected void calculateTickRect()

calculateLabelRect

protected void calculateLabelRect()

getThumbSize

protected Dimension getThumbSize()

getWidthOfWidestLabel

protected int getWidthOfWidestLabel()

getHeightOfTallestLabel

protected int getHeightOfTallestLabel()

getWidthOfHighValueLabel

protected int getWidthOfHighValueLabel()

getWidthOfLowValueLabel

protected int getWidthOfLowValueLabel()

getHeightOfHighValueLabel

protected int getHeightOfHighValueLabel()

getHeightOfLowValueLabel

protected int getHeightOfLowValueLabel()

drawInverted

protected boolean drawInverted()

getHighestValue

protected Integer getHighestValue()
Returns the biggest value that has an entry in the label table.

Returns:
biggest value that has an entry in the label table, or null.
Since:
1.6

getLowestValue

protected Integer getLowestValue()
Returns the smallest value that has an entry in the label table.

Returns:
smallest value that has an entry in the label table, or null.
Since:
1.6

getLowestValueLabel

protected Component getLowestValueLabel()
Returns the label that corresponds to the highest slider value in the label table.

See Also:
JSlider.setLabelTable(java.util.Dictionary)

getHighestValueLabel

protected Component getHighestValueLabel()
Returns the label that corresponds to the lowest slider value in the label table.

See Also:
JSlider.setLabelTable(java.util.Dictionary)

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

recalculateIfInsetsChanged

protected void recalculateIfInsetsChanged()

recalculateIfOrientationChanged

protected void recalculateIfOrientationChanged()

paintFocus

public void paintFocus(Graphics g)

paintTrack

public void paintTrack(Graphics g)

paintTicks

public void paintTicks(Graphics g)

paintMinorTickForHorizSlider

protected void paintMinorTickForHorizSlider(Graphics g,
                                            Rectangle tickBounds,
                                            int x)

paintMajorTickForHorizSlider

protected void paintMajorTickForHorizSlider(Graphics g,
                                            Rectangle tickBounds,
                                            int x)

paintMinorTickForVertSlider

protected void paintMinorTickForVertSlider(Graphics g,
                                           Rectangle tickBounds,
                                           int y)

paintMajorTickForVertSlider

protected void paintMajorTickForVertSlider(Graphics g,
                                           Rectangle tickBounds,
                                           int y)

paintLabels

public void paintLabels(Graphics g)

paintHorizontalLabel

protected void paintHorizontalLabel(Graphics g,
                                    int value,
                                    Component label)
Called for every label in the label table. Used to draw the labels for horizontal sliders. The graphics have been translated to labelRect.y already.

See Also:
JSlider.setLabelTable(java.util.Dictionary)

paintVerticalLabel

protected void paintVerticalLabel(Graphics g,
                                  int value,
                                  Component label)
Called for every label in the label table. Used to draw the labels for vertical sliders. The graphics have been translated to labelRect.x already.

See Also:
JSlider.setLabelTable(java.util.Dictionary)

paintThumb

public void paintThumb(Graphics g)

setThumbLocation

public void setThumbLocation(int x,
                             int y)

scrollByBlock

public void scrollByBlock(int direction)

scrollByUnit

public void scrollByUnit(int direction)

scrollDueToClickInTrack

protected void scrollDueToClickInTrack(int dir)
This function is called when a mousePressed was detected in the track, not in the thumb. The default behavior is to scroll by block. You can override this method to stop it from scrolling or to add additional behavior.

xPositionForValue

protected int xPositionForValue(int value)

yPositionForValue

protected int yPositionForValue(int value)

yPositionForValue

protected int yPositionForValue(int value,
                                int trackY,
                                int trackHeight)
Returns the y location for the specified value. No checking is done on the arguments. In particular if trackHeight is negative undefined results may occur.

Parameters:
value - the slider value to get the location for
trackY - y-origin of the track
trackHeight - the height of the track
Since:
1.6

valueForYPosition

public int valueForYPosition(int yPos)
Returns a value give a y position. If yPos is past the track at the top or the bottom it will set the value to the min or max of the slider, depending if the slider is inverted or not.

valueForXPosition

public int valueForXPosition(int xPos)
Returns a value give an x position. If xPos is past the track at the left or the right it will set the value to the min or max of the slider, depending if the slider is inverted or not.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSliderUI.ActionScroller

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSliderUI.ActionScroller

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicSliderUI.ActionScroller
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicSliderUI
public class BasicSliderUI.ActionScroller
extends AbstractAction

As of Java 2 platform v1.3 this undocumented class is no longer used. The recommended approach to creating bindings is to use a combination of an ActionMap, to contain the action, and an InputMap to contain the mapping from KeyStroke to action description. The InputMap is is usually described in the LookAndFeel tables.

Please refer to the key bindings specification for further details.

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
BasicSliderUI.ActionScroller(JSlider slider, int dir, boolean block)
Method Summary
void | actionPerformed(ActionEvent e) Invoked when an action occurs.
boolean | isEnabled() Returns true if the action is enabled.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSliderUI.ActionScroller

public BasicSliderUI.ActionScroller(JSlider slider,
                                    int dir,
                                    boolean block)
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

isEnabled

public boolean isEnabled()
Description copied from class: AbstractAction
Returns true if the action is enabled.

Specified by:
isEnabled in interface Action
Overrides:
isEnabled in class AbstractAction
Returns:
true if the action is enabled, false otherwise
See Also:
Action.isEnabled()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSliderUI.ChangeHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSliderUI.ChangeHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicSliderUI.ChangeHandler
All Implemented Interfaces:
EventListener, ChangeListener
Enclosing class:
BasicSliderUI
public class BasicSliderUI.ChangeHandler
extends Object
implements ChangeListener

Data model listener. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Constructor Summary
BasicSliderUI.ChangeHandler()
Method Summary
 void stateChanged(ChangeEvent e)
Invoked when the target of the listener has changed its state.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSliderUI.ChangeHandler

public BasicSliderUI.ChangeHandler()
Method Detail

stateChanged

public void stateChanged(ChangeEvent e)
Description copied from interface: ChangeListener
Invoked when the target of the listener has changed its state.

Specified by:
stateChanged in interface ChangeListener
Parameters:
e - a ChangeEvent object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSliderUI.ComponentHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSliderUI.ComponentHandler

java.lang.Object
    extended by  java.awt.event.ComponentAdapter
        extended by  javax.swing.plaf.basic.BasicSliderUI.ComponentHandler
All Implemented Interfaces:
ComponentListener, EventListener
Enclosing class:
BasicSliderUI
public class BasicSliderUI.ComponentHandler
extends ComponentAdapter

Listener for resizing events.

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Constructor Summary
BasicSliderUI.ComponentHandler()
Method Summary
 void componentResized(ComponentEvent e)
Invoked when the component's size changes.
Methods inherited from class java.awt.event.ComponentAdapter
componentHidden, componentMoved, componentShown
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSliderUI.ComponentHandler

public BasicSliderUI.ComponentHandler()
Method Detail

componentResized

public void componentResized(ComponentEvent e)
Description copied from class: ComponentAdapter
Invoked when the component's size changes.

Specified by:
componentResized in interface ComponentListener
Overrides:
componentResized in class ComponentAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSliderUI.FocusHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSliderUI.FocusHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicSliderUI.FocusHandler
All Implemented Interfaces:
FocusListener, EventListener
Enclosing class:
BasicSliderUI
public class BasicSliderUI.FocusHandler
extends Object
implements FocusListener

Focus-change listener.

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Constructor Summary
BasicSliderUI.FocusHandler()
Method Summary
void | focusGained(FocusEvent e) Invoked when a component gains the keyboard focus.
void | focusLost(FocusEvent e) Invoked when a component loses the keyboard focus.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSliderUI.FocusHandler

public BasicSliderUI.FocusHandler()
Method Detail

focusGained

public void focusGained(FocusEvent e)
Description copied from interface: FocusListener
Invoked when a component gains the keyboard focus.

Specified by:
focusGained in interface FocusListener

focusLost

public void focusLost(FocusEvent e)
Description copied from interface: FocusListener
Invoked when a component loses the keyboard focus.

Specified by:
focusLost in interface FocusListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSliderUI.PropertyChangeHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSliderUI.PropertyChangeHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicSliderUI.PropertyChangeHandler
All Implemented Interfaces:
PropertyChangeListener, EventListener
Direct Known Subclasses:
MetalSliderUI.MetalPropertyListener
Enclosing class:
BasicSliderUI
public class BasicSliderUI.PropertyChangeHandler
extends Object
implements PropertyChangeListener

Constructor Summary
BasicSliderUI.PropertyChangeHandler()
Method Summary
 void propertyChange(PropertyChangeEvent e)
This method gets called when a bound property is changed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSliderUI.PropertyChangeHandler

public BasicSliderUI.PropertyChangeHandler()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSliderUI.ScrollListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSliderUI.ScrollListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicSliderUI.ScrollListener
All Implemented Interfaces:
ActionListener, EventListener
Enclosing class:
BasicSliderUI
public class BasicSliderUI.ScrollListener
extends Object
implements ActionListener

Scroll-event listener. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Constructor Summary
BasicSliderUI.ScrollListener()
BasicSliderUI.ScrollListener(int dir, boolean block)
Method Summary
void | actionPerformed(ActionEvent e) Invoked when an action occurs.
void | setDirection(int direction)
void | setScrollByBlock(boolean block)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSliderUI.ScrollListener

public BasicSliderUI.ScrollListener()

BasicSliderUI.ScrollListener

public BasicSliderUI.ScrollListener(int dir,
                                    boolean block)
Method Detail

setDirection

public void setDirection(int direction)

setScrollByBlock

public void setScrollByBlock(boolean block)

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

Specified by:
actionPerformed in interface ActionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSliderUI.TrackListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSliderUI.TrackListener

java.lang.Object
    extended by  java.awt.event.MouseAdapter
        extended by  javax.swing.event.MouseInputAdapter
            extended by  javax.swing.plaf.basic.BasicSliderUI.TrackListener
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, EventListener, MouseInputListener
Enclosing class:
BasicSliderUI
public class BasicSliderUI.TrackListener
extends MouseInputAdapter

Track mouse movements. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Field Summary
protected int | currentMouseX
protected int | currentMouseY
protected int | offset
Constructor Summary
BasicSliderUI.TrackListener()
Method Summary
void | mouseDragged(MouseEvent e) Set the models value to the position of the top/left of the thumb relative to the origin of the track.
void | mouseMoved(MouseEvent e) Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.
void | mousePressed(MouseEvent e) If the mouse is pressed above the "thumb" component then reduce the scrollbars value by one page ("page up"), otherwise increase it by one page.
void | mouseReleased(MouseEvent e) Invoked when a mouse button has been released on a component.
boolean | shouldScroll(int direction)
Methods inherited from class java.awt.event.MouseAdapter
mouseClicked, mouseEntered, mouseExited, mouseWheelMoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface java.awt.event.MouseListener
mouseClicked, mouseEntered, mouseExited

Field Detail

offset

protected transient int offset

currentMouseX

protected transient int currentMouseX

currentMouseY

protected transient int currentMouseY
Constructor Detail

BasicSliderUI.TrackListener

public BasicSliderUI.TrackListener()
Method Detail

mouseReleased

public void mouseReleased(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when a mouse button has been released on a component.

Specified by:
mouseReleased in interface MouseListener
Overrides:
mouseReleased in class MouseAdapter

mousePressed

public void mousePressed(MouseEvent e)
If the mouse is pressed above the "thumb" component then reduce the scrollbars value by one page ("page up"), otherwise increase it by one page. If there is no thumb then page up if the mouse is in the upper half of the track.

Specified by:
mousePressed in interface MouseListener
Overrides:
mousePressed in class MouseAdapter

shouldScroll

public boolean shouldScroll(int direction)

mouseDragged

public void mouseDragged(MouseEvent e)
Set the models value to the position of the top/left of the thumb relative to the origin of the track.

Specified by:
mouseDragged in interface MouseMotionListener
Overrides:
mouseDragged in class MouseAdapter

mouseMoved

public void mouseMoved(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.

Specified by:
mouseMoved in interface MouseMotionListener
Overrides:
mouseMoved in class MouseAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSpinnerUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSpinnerUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SpinnerUI
            extended by  javax.swing.plaf.basic.BasicSpinnerUI

public class BasicSpinnerUI
extends SpinnerUI

The default Spinner UI delegate.

Since:
1.4

Field Summary
protected  JSpinner spinner
The spinner that we're a UI delegate for.
Constructor Summary
BasicSpinnerUI()
Method Summary
protected JComponent | createEditor() This method is called by installUI to get the editor component of the JSpinner.
protected LayoutManager | createLayout() Create a LayoutManager that manages the editor, nextButton, and previousButton children of the JSpinner.
protected Component | createNextButton() Create a component that will replace the spinner models value with the object returned by spinner.getNextValue.
protected Component | createPreviousButton() Create a component that will replace the spinner models value with the object returned by spinner.getPreviousValue.
protected PropertyChangeListener | createPropertyChangeListener() Create a PropertyChangeListener that can be added to the JSpinner itself.
static ComponentUI | createUI(JComponent c) Returns a new instance of BasicSpinnerUI.
int | getBaseline(JComponent c, int width, int height) Returns the baseline.
Component.BaselineResizeBehavior | getBaselineResizeBehavior(JComponent c) Returns an enum indicating how the baseline of the component changes as the size changes.
protected void | installDefaults() Initialize the JSpinner border, foreground, and background, properties based on the corresponding "Spinner.*" properties from defaults table.
protected void | installKeyboardActions() Installs the keyboard Actions onto the JSpinner.
protected void | installListeners() Initializes PropertyChangeListener with a shared object that delegates interesting PropertyChangeEvents to protected methods.
protected void | installNextButtonListeners(Component c) Installs the necessary listeners on the next button, c, to update the JSpinner in response to a user gesture.
protected void | installPreviousButtonListeners(Component c) Installs the necessary listeners on the previous button, c, to update the JSpinner in response to a user gesture.
void | installUI(JComponent c) Calls installDefaults, installListeners, and then adds the components returned by createNextButton, createPreviousButton, and createEditor.
protected void | replaceEditor(JComponent oldEditor, JComponent newEditor) Called by the PropertyChangeListener when the JSpinner editor property changes.
protected void | uninstallDefaults() Sets the JSpinner's layout manager to null.
protected void | uninstallListeners() Removes the PropertyChangeListener added by installListeners.
void | uninstallUI(JComponent c) Calls uninstallDefaults, uninstallListeners, and then removes all of the spinners children.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getMaximumSize, getMinimumSize, getPreferredSize, paint, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

spinner

protected JSpinner spinner
The spinner that we're a UI delegate for. Initialized by the installUI method, and reset to null by uninstallUI.

See Also:
installUI(javax.swing.JComponent), uninstallUI(javax.swing.JComponent)
Constructor Detail

BasicSpinnerUI

public BasicSpinnerUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)
Returns a new instance of BasicSpinnerUI. SpinnerListUI delegates are allocated one per JSpinner.

Parameters:
c - the JSpinner (not used)
Returns:
a new BasicSpinnerUI object
See Also:
ComponentUI.createUI(javax.swing.JComponent)

installUI

public void installUI(JComponent c)
Calls installDefaults, installListeners, and then adds the components returned by createNextButton, createPreviousButton, and createEditor.

Overrides:
installUI in class ComponentUI
Parameters:
c - the JSpinner
See Also:
installDefaults(),
installListeners(),
createNextButton(),
createPreviousButton(),
createEditor()

uninstallUI

public void uninstallUI(JComponent c)
Calls uninstallDefaults, uninstallListeners, and then removes all of the spinners children.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the JSpinner (not used)
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installListeners

protected void installListeners()
Initializes PropertyChangeListener with a shared object that delegates interesting PropertyChangeEvents to protected methods.

This method is called by installUI.

See Also:
replaceEditor(javax.swing.JComponent, javax.swing.JComponent), uninstallListeners()

uninstallListeners

protected void uninstallListeners()
Removes the PropertyChangeListener added by installListeners.

This method is called by uninstallUI.

See Also:
installListeners()

installDefaults

protected void installDefaults()
Initialize the JSpinner border, foreground, and background, properties based on the corresponding "Spinner.*" properties from defaults table. The JSpinners layout is set to the value returned by createLayout. This method is called by installUI.

See Also:
uninstallDefaults(),
installUI(javax.swing.JComponent),
createLayout(),
LookAndFeel.installBorder(javax.swing.JComponent, java.lang.String),
LookAndFeel.installColors(javax.swing.JComponent, java.lang.String, java.lang.String)

uninstallDefaults

protected void uninstallDefaults()
Sets the JSpinner's layout manager to null. This method is called by uninstallUI.

See Also:
installDefaults(), uninstallUI(javax.swing.JComponent)

installNextButtonListeners

protected void installNextButtonListeners(Component c)
Installs the necessary listeners on the next button, c, to update the JSpinner in response to a user gesture.

Parameters:
c - Component to install the listeners on
Throws:
NullPointerException - if c is null.
Since:
1.5
See Also:
createNextButton()

installPreviousButtonListeners

protected void installPreviousButtonListeners(Component c)
Installs the necessary listeners on the previous button, c, to update the JSpinner in response to a user gesture.

Parameters:
c - Component to install the listeners on.
Throws:
NullPointerException - if c is null.
Since:
1.5
See Also:
createPreviousButton()

createLayout

protected LayoutManager createLayout()
Create a LayoutManager that manages the editor, nextButton, and previousButton children of the JSpinner. These three children must be added with a constraint that identifies their role: "Editor", "Next", and "Previous". The default layout manager can handle the absence of any of these children.

Returns:
a LayoutManager for the editor, next button, and previous button.
See Also:
createNextButton(),
createPreviousButton(),
createEditor()

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener()
Create a PropertyChangeListener that can be added to the JSpinner itself. Typically, this listener will call replaceEditor when the "editor" property changes, since it's the SpinnerUI's responsibility to add the editor to the JSpinner (and remove the old one). This method is called by installListeners.

Returns:
A PropertyChangeListener for the JSpinner itself
See Also:
installListeners()

createPreviousButton

protected Component createPreviousButton()
Create a component that will replace the spinner models value with the object returned by spinner.getPreviousValue. By default the previousButton is a JButton. This method invokes installPreviousButtonListeners to install the necessary listeners to update the JSpinner's model in response to a user gesture. If a previousButton isn't needed (in a subclass) then override this method to return null.

Returns:
a component that will replace the spinners model with the next value in the sequence, or null
See Also:
installUI(javax.swing.JComponent),
createNextButton(),
installPreviousButtonListeners(java.awt.Component)

createNextButton

protected Component createNextButton()
Create a component that will replace the spinner models value with the object returned by spinner.getNextValue. By default the nextButton is a JButton who's ActionListener updates it's JSpinner ancestors model. If a nextButton isn't needed (in a subclass) then override this method to return null.

Returns:
a component that will replace the spinners model with the next value in the sequence, or null
See Also:
installUI(javax.swing.JComponent),
createPreviousButton(),
installNextButtonListeners(java.awt.Component)

createEditor

protected JComponent createEditor()
This method is called by installUI to get the editor component of the JSpinner. By default it just returns JSpinner.getEditor(). Subclasses can override createEditor to return a component that contains the spinner's editor or null, if they're going to handle adding the editor to the JSpinner in an installUI override.

Typically this method would be overridden to wrap the editor with a container with a custom border, since one can't assume that the editors border can be set directly.

The replaceEditor method is called when the spinners editor is changed with JSpinner.setEditor. If you've overriden this method, then you'll probably want to override replaceEditor as well.

Returns:
the JSpinners editor JComponent, spinner.getEditor() by default
See Also:
installUI(javax.swing.JComponent),
replaceEditor(javax.swing.JComponent, javax.swing.JComponent),
JSpinner.getEditor()

replaceEditor

protected void replaceEditor(JComponent oldEditor,
                             JComponent newEditor)
Called by the PropertyChangeListener when the JSpinner editor property changes. It's the responsibility of this method to remove the old editor and add the new one. By default this operation is just:
 spinner.remove(oldEditor);
 spinner.add(newEditor, "Editor");
The implementation of replaceEditor should be coordinated with the createEditor method.

See Also:
createEditor(), createPropertyChangeListener()

installKeyboardActions

protected void installKeyboardActions()
Installs the keyboard Actions onto the JSpinner.

Since:
1.5

getBaseline

public int getBaseline(JComponent c,
                       int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class ComponentUI
Parameters:
c - JComponent baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
NullPointerException - if c is null
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.

Overrides:
getBaselineResizeBehavior in class ComponentUI
Parameters:
c - JComponent to return baseline resize behavior for
Returns:
an enum indicating how the baseline changes as the component size changes
Throws:
NullPointerException - if c is null
Since:
1.6
See Also:
JComponent.getBaseline(int, int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSplitPaneDivider

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSplitPaneDivider

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.plaf.basic.BasicSplitPaneDivider
All Implemented Interfaces:
ImageObserver, MenuContainer, PropertyChangeListener, Serializable, EventListener
public class BasicSplitPaneDivider
extends Container
implements PropertyChangeListener

Divider used by BasicSplitPaneUI. Subclassers may wish to override paint to do something more interesting. The border effect is drawn in BasicSplitPaneUI, so if you don't like that border, reset it there. To conditionally drag from certain areas subclass mousePressed and call super when you wish the dragging to begin.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected class | BasicSplitPaneDivider.DividerLayout Used to layout a BasicSplitPaneDivider.
protected class | BasicSplitPaneDivider.DragController Handles the events during a dragging session for a HORIZONTAL_SPLIT oriented split pane.
protected class | BasicSplitPaneDivider.MouseHandler MouseHandler is responsible for converting mouse events (released, dragged...) into the appropriate DragController methods.
protected class | BasicSplitPaneDivider.VerticalDragController Handles the events during a dragging session for a VERTICAL_SPLIT oriented split pane.
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected int | dividerSize Size of the divider.
protected BasicSplitPaneDivider.DragController | dragger Handles mouse dragging message to do the actual dragging.
protected Component | hiddenDivider Divider that is used for noncontinuous layout mode.
protected JButton | leftButton Button for quickly toggling the left component.
protected BasicSplitPaneDivider.MouseHandler | mouseHandler Handles mouse events from both this class, and the split pane.
protected static int | ONE_TOUCH_OFFSET
protected static int | ONE_TOUCH_SIZE Width or height of the divider based on orientation BasicSplitPaneUI adds two to this.
protected int | orientation Orientation of the JSplitPane.
protected JButton | rightButton Button for quickly toggling the right component.
protected JSplitPane | splitPane JSplitPane the receiver is contained in.
protected BasicSplitPaneUI | splitPaneUI UI this instance was created from.
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
BasicSplitPaneDivider(BasicSplitPaneUI ui)
Creates an instance of BasicSplitPaneDivider.
Method Summary
protected JButton | createLeftOneTouchButton() Creates and return an instance of JButton that can be used to collapse the left component in the split pane.
protected JButton | createRightOneTouchButton() Creates and return an instance of JButton that can be used to collapse the right component in the split pane.
protected void | dragDividerTo(int location) Messages the BasicSplitPaneUI with dragDividerTo that this instance is contained in.
protected void | finishDraggingTo(int location) Messages the BasicSplitPaneUI with finishDraggingTo that this instance is contained in.
BasicSplitPaneUI | getBasicSplitPaneUI() Returns the SplitPaneUI the receiver is currently in.
Border | getBorder() Returns the border of this component or null if no border is currently set.
int | getDividerSize() Returns the size of the divider, that is the width if the splitpane is HORIZONTAL_SPLIT, or the height of VERTICAL_SPLIT.
Insets | getInsets() If a border has been set on this component, returns the border's insets, else calls super.getInsets.
Dimension | getMinimumSize() Returns dividerSize x dividerSize
Dimension | getPreferredSize() Returns dividerSize x dividerSize
boolean | isMouseOver() Returns whether or not the mouse is currently over the divider
protected void | oneTouchExpandableChanged() Messaged when the oneTouchExpandable value of the JSplitPane the receiver is contained in changes.
void | paint(Graphics g) Paints the divider.
protected void | prepareForDragging() Message to prepare for dragging.
void | propertyChange(PropertyChangeEvent e) Property change event, presumably from the JSplitPane, will message updateOrientation if necessary.
void | setBasicSplitPaneUI(BasicSplitPaneUI newUI) Sets the SplitPaneUI that is using the receiver.
void | setBorder(Border border) Sets the border of this component.
void | setDividerSize(int newSize) Sets the size of the divider to newSize.
protected void | setMouseOver(boolean mouseOver) Sets whether or not the mouse is currently over the divider.
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addNotify, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getListeners, getMaximumSize, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, paramString, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, removeNotify, setComponentZOrder, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, setLayout, transferFocusBackward, transferFocusDownCycle, update, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAccessibleContext, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ONE_TOUCH_SIZE

protected static final int ONE_TOUCH_SIZE
Width or height of the divider based on orientation BasicSplitPaneUI adds two to this.

See Also:
Constant Field Values

ONE_TOUCH_OFFSET

protected static final int ONE_TOUCH_OFFSET
See Also:
Constant Field Values

dragger

protected BasicSplitPaneDivider.DragController dragger
Handles mouse dragging message to do the actual dragging.

splitPaneUI

protected BasicSplitPaneUI splitPaneUI
UI this instance was created from.

dividerSize

protected int dividerSize
Size of the divider.

hiddenDivider

protected Component hiddenDivider
Divider that is used for noncontinuous layout mode.

splitPane

protected JSplitPane splitPane
JSplitPane the receiver is contained in.

mouseHandler

protected BasicSplitPaneDivider.MouseHandler mouseHandler
Handles mouse events from both this class, and the split pane. Mouse events are handled for the splitpane since you want to be able to drag when clicking on the border of the divider, which is not drawn by the divider.

orientation

protected int orientation
Orientation of the JSplitPane.

leftButton

protected JButton leftButton
Button for quickly toggling the left component.

rightButton

protected JButton rightButton
Button for quickly toggling the right component.

Constructor Detail

BasicSplitPaneDivider

public BasicSplitPaneDivider(BasicSplitPaneUI ui)
Creates an instance of BasicSplitPaneDivider. Registers this instance for mouse events and mouse dragged events.

Method Detail

setBasicSplitPaneUI

public void setBasicSplitPaneUI(BasicSplitPaneUI newUI)
Sets the SplitPaneUI that is using the receiver.

getBasicSplitPaneUI

public BasicSplitPaneUI getBasicSplitPaneUI()
Returns the SplitPaneUI the receiver is currently in.

setDividerSize

public void setDividerSize(int newSize)
Sets the size of the divider to newSize. That is the width if the splitpane is HORIZONTAL_SPLIT, or the height of VERTICAL_SPLIT.

getDividerSize

public int getDividerSize()
Returns the size of the divider, that is the width if the splitpane is HORIZONTAL_SPLIT, or the height of VERTICAL_SPLIT.

setBorder

public void setBorder(Border border)
Sets the border of this component.

Since:
1.3

getBorder

public Border getBorder()
Returns the border of this component or null if no border is currently set.

Returns:
the border object for this component
Since:
1.3
See Also:
setBorder(javax.swing.border.Border)

getInsets

public Insets getInsets()
If a border has been set on this component, returns the border's insets, else calls super.getInsets.

Overrides:
getInsets in class Container
Returns:
the value of the insets property.
See Also:
setBorder(javax.swing.border.Border)

setMouseOver

protected void setMouseOver(boolean mouseOver)
Sets whether or not the mouse is currently over the divider.

Parameters:
mouseOver - whether or not the mouse is currently over the divider
Since:
1.5

isMouseOver

public boolean isMouseOver()
Returns whether or not the mouse is currently over the divider

Returns:
whether or not the mouse is currently over the divider
Since:
1.5

getPreferredSize

public Dimension getPreferredSize()
Returns dividerSize x dividerSize

Overrides:
getPreferredSize in class Container
Returns:
an instance of Dimension that represents the preferred size of this container.
See Also:
Container.getMinimumSize(),
Container.getMaximumSize(),
Container.getLayout(),
LayoutManager.preferredLayoutSize(Container),
Component.getPreferredSize()

getMinimumSize

public Dimension getMinimumSize()
Returns dividerSize x dividerSize

Overrides:
getMinimumSize in class Container
Returns:
an instance of Dimension that represents the minimum size of this container.
See Also:
Container.getPreferredSize(),
Container.getMaximumSize(),
Container.getLayout(),
LayoutManager.minimumLayoutSize(Container),
Component.getMinimumSize()

propertyChange

public void propertyChange(PropertyChangeEvent e)
Property change event, presumably from the JSplitPane, will message updateOrientation if necessary.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.

paint

public void paint(Graphics g)
Paints the divider.

Overrides:
paint in class Container
Parameters:
g - the specified Graphics window
See Also:
Component.update(Graphics)

oneTouchExpandableChanged

protected void oneTouchExpandableChanged()
Messaged when the oneTouchExpandable value of the JSplitPane the receiver is contained in changes. Will create the leftButton and rightButton if they are null. invalidates the receiver as well.

createLeftOneTouchButton

protected JButton createLeftOneTouchButton()
Creates and return an instance of JButton that can be used to collapse the left component in the split pane.

createRightOneTouchButton

protected JButton createRightOneTouchButton()
Creates and return an instance of JButton that can be used to collapse the right component in the split pane.

prepareForDragging

protected void prepareForDragging()
Message to prepare for dragging. This messages the BasicSplitPaneUI with startDragging.

dragDividerTo

protected void dragDividerTo(int location)
Messages the BasicSplitPaneUI with dragDividerTo that this instance is contained in.

finishDraggingTo

protected void finishDraggingTo(int location)
Messages the BasicSplitPaneUI with finishDraggingTo that this instance is contained in.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSplitPaneDivider.DividerLayout

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSplitPaneDivider.DividerLayout

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicSplitPaneDivider.DividerLayout
All Implemented Interfaces:
LayoutManager
Enclosing class:
BasicSplitPaneDivider
protected class BasicSplitPaneDivider.DividerLayout
extends Object
implements LayoutManager

Used to layout a BasicSplitPaneDivider. Layout for the divider involves appropriately moving the left/right buttons around.

Constructor Summary
protected BasicSplitPaneDivider.DividerLayout()
Method Summary
void | addLayoutComponent(String string, Component c) If the layout manager uses a per-component string, adds the component comp to the layout, associating it with the string specified by name.
void | layoutContainer(Container c) Lays out the specified container.
Dimension | minimumLayoutSize(Container c) Calculates the minimum size dimensions for the specified container, given the components it contains.
Dimension | preferredLayoutSize(Container c) Calculates the preferred size dimensions for the specified container, given the components it contains.
void | removeLayoutComponent(Component c) Removes the specified component from the layout.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSplitPaneDivider.DividerLayout

protected BasicSplitPaneDivider.DividerLayout()
Method Detail

layoutContainer

public void layoutContainer(Container c)
Description copied from interface: LayoutManager
Lays out the specified container.

Specified by:
layoutContainer in interface LayoutManager
Parameters:
c - the container to be laid out

minimumLayoutSize

public Dimension minimumLayoutSize(Container c)
Description copied from interface: LayoutManager
Calculates the minimum size dimensions for the specified container, given the components it contains.

Specified by:
minimumLayoutSize in interface LayoutManager
Parameters:
c - the component to be laid out
See Also:
LayoutManager.preferredLayoutSize(java.awt.Container)

preferredLayoutSize

public Dimension preferredLayoutSize(Container c)
Description copied from interface: LayoutManager
Calculates the preferred size dimensions for the specified container, given the components it contains.

Specified by:
preferredLayoutSize in interface LayoutManager
Parameters:
c - the container to be laid out
See Also:
LayoutManager.minimumLayoutSize(java.awt.Container)

removeLayoutComponent

public void removeLayoutComponent(Component c)
Description copied from interface: LayoutManager
Removes the specified component from the layout.

Specified by:
removeLayoutComponent in interface LayoutManager
Parameters:
c - the component to be removed

addLayoutComponent

public void addLayoutComponent(String string,
                               Component c)
Description copied from interface: LayoutManager
If the layout manager uses a per-component string, adds the component comp to the layout, associating it with the string specified by name.

Specified by:
addLayoutComponent in interface LayoutManager
Parameters:
string - the string to be associated with the component
c - the component to be added
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSplitPaneDivider.DragController

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSplitPaneDivider.DragController

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicSplitPaneDivider.DragController
Direct Known Subclasses:
BasicSplitPaneDivider.VerticalDragController
Enclosing class:
BasicSplitPaneDivider
protected class BasicSplitPaneDivider.DragController
extends Object

Handles the events during a dragging session for a HORIZONTAL_SPLIT oriented split pane. This continually messages dragDividerTo and then when done messages finishDraggingTo. When an instance is created it should be messaged with isValid to insure that dragging can happen (dragging won't be allowed if the two views can not be resized).

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
protected BasicSplitPaneDivider.DragController(MouseEvent e)
Method Summary
protected void | completeDrag(int x, int y)
protected void | completeDrag(MouseEvent e) Messages finishDraggingTo with the new location for the mouse event.
protected void | continueDrag(int newX, int newY)
protected void | continueDrag(MouseEvent e) Messages dragDividerTo with the new location for the mouse event.
protected int | getNeededLocation(int x, int y) Returns the x argument, since this is used for horizontal splits.
protected boolean | isValid() Returns true if the dragging session is valid.
protected int | positionForMouseEvent(MouseEvent e) Returns the new position to put the divider at based on the passed in MouseEvent.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSplitPaneDivider.DragController

protected BasicSplitPaneDivider.DragController(MouseEvent e)
Method Detail

isValid

protected boolean isValid()
Returns true if the dragging session is valid.

positionForMouseEvent

protected int positionForMouseEvent(MouseEvent e)
Returns the new position to put the divider at based on the passed in MouseEvent.

getNeededLocation

protected int getNeededLocation(int x,
                                int y)
Returns the x argument, since this is used for horizontal splits.

continueDrag

protected void continueDrag(int newX,
                            int newY)

continueDrag

protected void continueDrag(MouseEvent e)
Messages dragDividerTo with the new location for the mouse event.

completeDrag

protected void completeDrag(int x,
                            int y)

completeDrag

protected void completeDrag(MouseEvent e)
Messages finishDraggingTo with the new location for the mouse event.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSplitPaneDivider.MouseHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSplitPaneDivider.MouseHandler

java.lang.Object
    extended by  java.awt.event.MouseAdapter
        extended by  javax.swing.plaf.basic.BasicSplitPaneDivider.MouseHandler
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, EventListener
Enclosing class:
BasicSplitPaneDivider
protected class BasicSplitPaneDivider.MouseHandler
extends MouseAdapter
implements MouseMotionListener

MouseHandler is responsible for converting mouse events (released, dragged...) into the appropriate DragController methods.

Constructor Summary
protected BasicSplitPaneDivider.MouseHandler()
Method Summary
void | mouseDragged(MouseEvent e) If dragger is not null it is messaged with continueDrag.
void | mouseEntered(MouseEvent e) Invoked when the mouse enters a component.
void | mouseExited(MouseEvent e) Invoked when the mouse exits a component.
void | mouseMoved(MouseEvent e) Resets the cursor based on the orientation.
void | mousePressed(MouseEvent e) Starts the dragging session by creating the appropriate instance of DragController.
void | mouseReleased(MouseEvent e) If dragger is not null it is messaged with completeDrag.
Methods inherited from class java.awt.event.MouseAdapter
mouseClicked, mouseWheelMoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSplitPaneDivider.MouseHandler

protected BasicSplitPaneDivider.MouseHandler()
Method Detail

mousePressed

public void mousePressed(MouseEvent e)
Starts the dragging session by creating the appropriate instance of DragController.

Specified by:
mousePressed in interface MouseListener
Overrides:
mousePressed in class MouseAdapter

mouseReleased

public void mouseReleased(MouseEvent e)
If dragger is not null it is messaged with completeDrag.

Specified by:
mouseReleased in interface MouseListener
Overrides:
mouseReleased in class MouseAdapter

mouseDragged

public void mouseDragged(MouseEvent e)
If dragger is not null it is messaged with continueDrag.

Specified by:
mouseDragged in interface MouseMotionListener
Overrides:
mouseDragged in class MouseAdapter

mouseMoved

public void mouseMoved(MouseEvent e)
Resets the cursor based on the orientation.

Specified by:
mouseMoved in interface MouseMotionListener
Overrides:
mouseMoved in class MouseAdapter

mouseEntered

public void mouseEntered(MouseEvent e)
Invoked when the mouse enters a component.

Specified by:
mouseEntered in interface MouseListener
Overrides:
mouseEntered in class MouseAdapter
Parameters:
e - MouseEvent describing the details of the enter event.
Since:
1.5

mouseExited

public void mouseExited(MouseEvent e)
Invoked when the mouse exits a component.

Specified by:
mouseExited in interface MouseListener
Overrides:
mouseExited in class MouseAdapter
Parameters:
e - MouseEvent describing the details of the exit event.
Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSplitPaneDivider.VerticalDragController

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSplitPaneDivider.VerticalDragController

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicSplitPaneDivider.DragController
        extended by  javax.swing.plaf.basic.BasicSplitPaneDivider.VerticalDragController
Enclosing class:
BasicSplitPaneDivider
protected class BasicSplitPaneDivider.VerticalDragController
extends BasicSplitPaneDivider.DragController

Handles the events during a dragging session for a VERTICAL_SPLIT oriented split pane. This continually messages dragDividerTo and then when done messages finishDraggingTo. When an instance is created it should be messaged with isValid to insure that dragging can happen (dragging won't be allowed if the two views can not be resized).

Constructor Summary
protected BasicSplitPaneDivider.VerticalDragController(MouseEvent e)
Method Summary
protected int | getNeededLocation(int x, int y) Returns the y argument, since this is used for vertical splits.
protected int | positionForMouseEvent(MouseEvent e) Returns the new position to put the divider at based on the passed in MouseEvent.
Methods inherited from class javax.swing.plaf.basic.BasicSplitPaneDivider.DragController
completeDrag, completeDrag, continueDrag, continueDrag, isValid
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSplitPaneDivider.VerticalDragController

protected BasicSplitPaneDivider.VerticalDragController(MouseEvent e)
Method Detail

getNeededLocation

protected int getNeededLocation(int x,
                                int y)
Returns the y argument, since this is used for vertical splits.

Overrides:
getNeededLocation in class BasicSplitPaneDivider.DragController

positionForMouseEvent

protected int positionForMouseEvent(MouseEvent e)
Returns the new position to put the divider at based on the passed in MouseEvent.

Overrides:
positionForMouseEvent in class BasicSplitPaneDivider.DragController
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSplitPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSplitPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SplitPaneUI
            extended by  javax.swing.plaf.basic.BasicSplitPaneUI
Direct Known Subclasses:
MetalSplitPaneUI
public class BasicSplitPaneUI
extends SplitPaneUI

A Basic L&F implementation of the SplitPaneUI.

Nested Class Summary
class | BasicSplitPaneUI.BasicHorizontalLayoutManager LayoutManager for JSplitPanes that have an orientation of HORIZONTAL_SPLIT.
class | BasicSplitPaneUI.BasicVerticalLayoutManager LayoutManager used for JSplitPanes with an orientation of VERTICAL_SPLIT.
class | BasicSplitPaneUI.FocusHandler Implementation of the FocusListener that the JSplitPane UI uses.
class | BasicSplitPaneUI.KeyboardDownRightHandler Implementation of an ActionListener that the JSplitPane UI uses for handling specific key presses.
class | BasicSplitPaneUI.KeyboardEndHandler Implementation of an ActionListener that the JSplitPane UI uses for handling specific key presses.
class | BasicSplitPaneUI.KeyboardHomeHandler Implementation of an ActionListener that the JSplitPane UI uses for handling specific key presses.
class | BasicSplitPaneUI.KeyboardResizeToggleHandler Implementation of an ActionListener that the JSplitPane UI uses for handling specific key presses.
class | BasicSplitPaneUI.KeyboardUpLeftHandler Implementation of an ActionListener that the JSplitPane UI uses for handling specific key presses.
class | BasicSplitPaneUI.PropertyHandler Implementation of the PropertyChangeListener that the JSplitPane UI uses.
Field Summary
protected int | beginDragDividerLocation Location of the divider when the dragging session began.
protected BasicSplitPaneDivider | divider Instance of the divider for this JSplitPane.
protected KeyStroke | dividerResizeToggleKey Deprecated. As of Java 2 platform v1.3.
protected int | dividerSize The size of the divider while the dragging session is valid.
protected KeyStroke | downKey Deprecated. As of Java 2 platform v1.3.
protected boolean | draggingHW Set to true in startDragging if any of the children (not including the nonContinuousLayoutDivider) are heavy weights.
protected KeyStroke | endKey Deprecated. As of Java 2 platform v1.3.
protected FocusListener | focusListener Instance of the FocusListener for this JSplitPane.
protected KeyStroke | homeKey Deprecated. As of Java 2 platform v1.3.
protected static int | KEYBOARD_DIVIDER_MOVE_OFFSET How far (relative) the divider does move when it is moved around by the cursor keys on the keyboard.
protected ActionListener | keyboardDownRightListener Deprecated. As of Java 2 platform v1.3.
protected ActionListener | keyboardEndListener Deprecated. As of Java 2 platform v1.3.
protected ActionListener | keyboardHomeListener Deprecated. As of Java 2 platform v1.3.
protected ActionListener | keyboardResizeToggleListener Deprecated. As of Java 2 platform v1.3.
protected ActionListener | keyboardUpLeftListener Deprecated. As of Java 2 platform v1.3.
protected BasicSplitPaneUI.BasicHorizontalLayoutManager | layoutManager LayoutManager that is created and placed into the split pane.
protected KeyStroke | leftKey Deprecated. As of Java 2 platform v1.3.
protected static String | NON_CONTINUOUS_DIVIDER The divider used for non-continuous layout is added to the split pane with this object.
protected Component | nonContinuousLayoutDivider Instance for the shadow of the divider when non continuous layout is being used.
protected PropertyChangeListener | propertyChangeListener Instance of the PropertyChangeListener for this JSplitPane.
protected KeyStroke | rightKey Deprecated. As of Java 2 platform v1.3.
protected JSplitPane | splitPane JSplitPane instance this instance is providing the look and feel for.
protected KeyStroke | upKey Deprecated. As of Java 2 platform v1.3.
Constructor Summary
BasicSplitPaneUI()
Method Summary
BasicSplitPaneDivider | createDefaultDivider() Creates the default divider.
protected Component | createDefaultNonContinuousLayoutDivider() Returns the default non continuous layout divider, which is an instanceof Canvas that fills the background in dark gray.
protected FocusListener | createFocusListener() Creates a FocusListener for the JSplitPane UI.
protected ActionListener | createKeyboardDownRightListener() Deprecated. As of Java 2 platform v1.3.
protected ActionListener | createKeyboardEndListener() Deprecated. As of Java 2 platform v1.3.
protected ActionListener | createKeyboardHomeListener() Deprecated. As of Java 2 platform v1.3.
protected ActionListener | createKeyboardResizeToggleListener() Deprecated. As of Java 2 platform v1.3.
protected ActionListener | createKeyboardUpLeftListener() Deprecated. As of Java 2 platform v1.3.
protected PropertyChangeListener | createPropertyChangeListener() Creates a PropertyChangeListener for the JSplitPane UI.
static ComponentUI | createUI(JComponent x) Creates a new BasicSplitPaneUI instance
protected void | dragDividerTo(int location) Messaged during a dragging session to move the divider to the passed in location.
protected void | finishDraggingTo(int location) Messaged to finish the dragging session.
void | finishedPaintingChildren(JSplitPane jc, Graphics g) Messaged after the JSplitPane the receiver is providing the look and feel for paints its children.
BasicSplitPaneDivider | getDivider() Returns the divider between the top Components.
protected int | getDividerBorderSize() Deprecated. As of Java 2 platform v1.3, instead set the border on the divider.
int | getDividerLocation(JSplitPane jc) Returns the location of the divider, which may differ from what the splitpane thinks the location of the divider is.
Insets | getInsets(JComponent jc) Returns the insets.
int | getLastDragLocation() Returns the last drag location of the JSplitPane.
int | getMaximumDividerLocation(JSplitPane jc) Gets the maximum location of the divider.
Dimension | getMaximumSize(JComponent jc) Returns the maximum size for the passed in component, This is passed off to the current layoutmanager.
int | getMinimumDividerLocation(JSplitPane jc) Gets the minimum location of the divider.
Dimension | getMinimumSize(JComponent jc) Returns the minimum size for the passed in component, This is passed off to the current layoutmanager.
Component | getNonContinuousLayoutDivider() Returns the divider to use when the splitPane is configured to not continuously layout.
int | getOrientation() Returns the orientation for the JSplitPane.
Dimension | getPreferredSize(JComponent jc) Returns the preferred size for the passed in component, This is passed off to the current layoutmanager.
JSplitPane | getSplitPane() Returns the splitpane this instance is currently contained in.
protected void | installDefaults() Installs the UI defaults.
protected void | installKeyboardActions() Installs the keyboard actions for the UI.
protected void | installListeners() Installs the event listeners for the UI.
void | installUI(JComponent c) Installs the UI.
boolean | isContinuousLayout() Determines wether the JSplitPane is set to use a continuous layout.
void | paint(Graphics g, JComponent jc) Messaged to paint the look and feel.
protected void | resetLayoutManager() Resets the layout manager based on orientation and messages it with invalidateLayout to pull in appropriate Components.
void | resetToPreferredSizes(JSplitPane jc) Messaged to reset the preferred sizes.
void | setContinuousLayout(boolean b) Turn continuous layout on/off.
void | setDividerLocation(JSplitPane jc, int location) Sets the location of the divider to location.
void | setLastDragLocation(int l) Set the last drag location of the JSplitPane.
protected void | setNonContinuousLayoutDivider(Component newDivider) Sets the divider to use when the splitPane is configured to not continuously layout.
protected void | setNonContinuousLayoutDivider(Component newDivider, boolean rememberSizes) Sets the divider to use.
void | setOrientation(int orientation) Set the orientation for the JSplitPane.
protected void | startDragging() Should be messaged before the dragging session starts, resets lastDragLocation and dividerSize.
protected void | uninstallDefaults() Uninstalls the UI defaults.
protected void | uninstallKeyboardActions() Uninstalls the keyboard actions for the UI.
protected void | uninstallListeners() Uninstalls the event listeners for the UI.
void | uninstallUI(JComponent c) Uninstalls the UI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NON_CONTINUOUS_DIVIDER

protected static final String NON_CONTINUOUS_DIVIDER
The divider used for non-continuous layout is added to the split pane with this object.

See Also:
Constant Field Values

KEYBOARD_DIVIDER_MOVE_OFFSET

protected static int KEYBOARD_DIVIDER_MOVE_OFFSET
How far (relative) the divider does move when it is moved around by the cursor keys on the keyboard.

splitPane

protected JSplitPane splitPane
JSplitPane instance this instance is providing the look and feel for.

layoutManager

protected BasicSplitPaneUI.BasicHorizontalLayoutManager layoutManager
LayoutManager that is created and placed into the split pane.

divider

protected BasicSplitPaneDivider divider
Instance of the divider for this JSplitPane.

propertyChangeListener

protected PropertyChangeListener propertyChangeListener
Instance of the PropertyChangeListener for this JSplitPane.

focusListener

protected FocusListener focusListener
Instance of the FocusListener for this JSplitPane.

dividerSize

protected int dividerSize
The size of the divider while the dragging session is valid.

nonContinuousLayoutDivider

protected Component nonContinuousLayoutDivider
Instance for the shadow of the divider when non continuous layout is being used.

draggingHW

protected boolean draggingHW
Set to true in startDragging if any of the children (not including the nonContinuousLayoutDivider) are heavy weights.

beginDragDividerLocation

protected int beginDragDividerLocation
Location of the divider when the dragging session began.

upKey

@Deprecated
protected KeyStroke upKey
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

downKey

@Deprecated
protected KeyStroke downKey
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

leftKey

@Deprecated
protected KeyStroke leftKey
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

rightKey

@Deprecated
protected KeyStroke rightKey
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

homeKey

@Deprecated
protected KeyStroke homeKey
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

endKey

@Deprecated
protected KeyStroke endKey
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

dividerResizeToggleKey

@Deprecated
protected KeyStroke dividerResizeToggleKey
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

keyboardUpLeftListener

@Deprecated
protected ActionListener keyboardUpLeftListener
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

keyboardDownRightListener

@Deprecated
protected ActionListener keyboardDownRightListener
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

keyboardHomeListener

@Deprecated
protected ActionListener keyboardHomeListener
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

keyboardEndListener

@Deprecated
protected ActionListener keyboardEndListener
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

keyboardResizeToggleListener

@Deprecated
protected ActionListener keyboardResizeToggleListener
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

Constructor Detail

BasicSplitPaneUI

public BasicSplitPaneUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent x)
Creates a new BasicSplitPaneUI instance

installUI

public void installUI(JComponent c)
Installs the UI.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

installDefaults

protected void installDefaults()
Installs the UI defaults.

installListeners

protected void installListeners()
Installs the event listeners for the UI.

installKeyboardActions

protected void installKeyboardActions()
Installs the keyboard actions for the UI.

uninstallUI

public void uninstallUI(JComponent c)
Uninstalls the UI.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

uninstallDefaults

protected void uninstallDefaults()
Uninstalls the UI defaults.

uninstallListeners

protected void uninstallListeners()
Uninstalls the event listeners for the UI.

uninstallKeyboardActions

protected void uninstallKeyboardActions()
Uninstalls the keyboard actions for the UI.

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener()
Creates a PropertyChangeListener for the JSplitPane UI.

createFocusListener

protected FocusListener createFocusListener()
Creates a FocusListener for the JSplitPane UI.

createKeyboardUpLeftListener

@Deprecated
protected ActionListener createKeyboardUpLeftListener()
Deprecated. As of Java 2 platform v1.3.

As of Java 2 platform v1.3 this method is no longer used. Subclassers previously using this method should instead create an Action wrapping the ActionListener, and register that Action by overriding installKeyboardActions and placing the Action in the SplitPane's ActionMap. Please refer to the key bindings specification for further details.

Creates a ActionListener for the JSplitPane UI that listens for specific key presses.

createKeyboardDownRightListener

@Deprecated
protected ActionListener createKeyboardDownRightListener()
Deprecated. As of Java 2 platform v1.3.

As of Java 2 platform v1.3 this method is no longer used. Subclassers previously using this method should instead create an Action wrapping the ActionListener, and register that Action by overriding installKeyboardActions and placing the Action in the SplitPane's ActionMap. Please refer to the key bindings specification for further details.

Creates a ActionListener for the JSplitPane UI that listens for specific key presses.

createKeyboardHomeListener

@Deprecated
protected ActionListener createKeyboardHomeListener()
Deprecated. As of Java 2 platform v1.3.

As of Java 2 platform v1.3 this method is no longer used. Subclassers previously using this method should instead create an Action wrapping the ActionListener, and register that Action by overriding installKeyboardActions and placing the Action in the SplitPane's ActionMap. Please refer to the key bindings specification for further details.

Creates a ActionListener for the JSplitPane UI that listens for specific key presses.

createKeyboardEndListener

@Deprecated
protected ActionListener createKeyboardEndListener()
Deprecated. As of Java 2 platform v1.3.

As of Java 2 platform v1.3 this method is no longer used. Subclassers previously using this method should instead create an Action wrapping the ActionListener, and register that Action by overriding installKeyboardActions and placing the Action in the SplitPane's ActionMap. Please refer to the key bindings specification for further details.

Creates a ActionListener for the JSplitPane UI that listens for specific key presses.

createKeyboardResizeToggleListener

@Deprecated
protected ActionListener createKeyboardResizeToggleListener()
Deprecated. As of Java 2 platform v1.3.

As of Java 2 platform v1.3 this method is no longer used. Subclassers previously using this method should instead create an Action wrapping the ActionListener, and register that Action by overriding installKeyboardActions and placing the Action in the SplitPane's ActionMap. Please refer to the key bindings specification for further details.

Creates a ActionListener for the JSplitPane UI that listens for specific key presses.

getOrientation

public int getOrientation()
Returns the orientation for the JSplitPane.

setOrientation

public void setOrientation(int orientation)
Set the orientation for the JSplitPane.

isContinuousLayout

public boolean isContinuousLayout()
Determines wether the JSplitPane is set to use a continuous layout.

setContinuousLayout

public void setContinuousLayout(boolean b)
Turn continuous layout on/off.

getLastDragLocation

public int getLastDragLocation()
Returns the last drag location of the JSplitPane.

setLastDragLocation

public void setLastDragLocation(int l)
Set the last drag location of the JSplitPane.

getDivider

public BasicSplitPaneDivider getDivider()
Returns the divider between the top Components.

createDefaultNonContinuousLayoutDivider

protected Component createDefaultNonContinuousLayoutDivider()
Returns the default non continuous layout divider, which is an instanceof Canvas that fills the background in dark gray.

setNonContinuousLayoutDivider

protected void setNonContinuousLayoutDivider(Component newDivider)
Sets the divider to use when the splitPane is configured to not continuously layout. This divider will only be used during a dragging session. It is recommended that the passed in component be a heavy weight.

setNonContinuousLayoutDivider

protected void setNonContinuousLayoutDivider(Component newDivider,
                                             boolean rememberSizes)
Sets the divider to use.

getNonContinuousLayoutDivider

public Component getNonContinuousLayoutDivider()
Returns the divider to use when the splitPane is configured to not continuously layout. This divider will only be used during a dragging session.

getSplitPane

public JSplitPane getSplitPane()
Returns the splitpane this instance is currently contained in.

createDefaultDivider

public BasicSplitPaneDivider createDefaultDivider()
Creates the default divider.

resetToPreferredSizes

public void resetToPreferredSizes(JSplitPane jc)
Messaged to reset the preferred sizes.

Specified by:
resetToPreferredSizes in class SplitPaneUI

setDividerLocation

public void setDividerLocation(JSplitPane jc,
                               int location)
Sets the location of the divider to location.

Specified by:
setDividerLocation in class SplitPaneUI

getDividerLocation

public int getDividerLocation(JSplitPane jc)
Returns the location of the divider, which may differ from what the splitpane thinks the location of the divider is.

Specified by:
getDividerLocation in class SplitPaneUI

getMinimumDividerLocation

public int getMinimumDividerLocation(JSplitPane jc)
Gets the minimum location of the divider.

Specified by:
getMinimumDividerLocation in class SplitPaneUI

getMaximumDividerLocation

public int getMaximumDividerLocation(JSplitPane jc)
Gets the maximum location of the divider.

Specified by:
getMaximumDividerLocation in class SplitPaneUI

finishedPaintingChildren

public void finishedPaintingChildren(JSplitPane jc,
                                     Graphics g)
Messaged after the JSplitPane the receiver is providing the look and feel for paints its children.

Specified by:
finishedPaintingChildren in class SplitPaneUI

paint

public void paint(Graphics g,
                  JComponent jc)
Messaged to paint the look and feel.

Overrides:
paint in class ComponentUI
Parameters:
g - the Graphics context in which to paint
jc - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent jc)
Returns the preferred size for the passed in component, This is passed off to the current layoutmanager.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
jc - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent jc)
Returns the minimum size for the passed in component, This is passed off to the current layoutmanager.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
jc - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent jc)
Returns the maximum size for the passed in component, This is passed off to the current layoutmanager.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
jc - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getInsets

public Insets getInsets(JComponent jc)
Returns the insets. The insets are returned from the border insets of the current border.

resetLayoutManager

protected void resetLayoutManager()
Resets the layout manager based on orientation and messages it with invalidateLayout to pull in appropriate Components.

startDragging

protected void startDragging()
Should be messaged before the dragging session starts, resets lastDragLocation and dividerSize.

dragDividerTo

protected void dragDividerTo(int location)
Messaged during a dragging session to move the divider to the passed in location. If continuousLayout is true the location is reset and the splitPane validated.

finishDraggingTo

protected void finishDraggingTo(int location)
Messaged to finish the dragging session. If not continuous display the dividers location will be reset.

getDividerBorderSize

@Deprecated
protected int getDividerBorderSize()
Deprecated. As of Java 2 platform v1.3, instead set the border on the divider.

As of Java 2 platform v1.3 this method is no longer used. Instead you should set the border on the divider.

Returns the width of one side of the divider border.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSplitPaneUI.BasicHorizontalLayoutManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSplitPaneUI.BasicHorizontalLayoutManager

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicSplitPaneUI.BasicHorizontalLayoutManager
All Implemented Interfaces:
LayoutManager, LayoutManager2
Direct Known Subclasses:
BasicSplitPaneUI.BasicVerticalLayoutManager
Enclosing class:
BasicSplitPaneUI
public class BasicSplitPaneUI.BasicHorizontalLayoutManager
extends Object
implements LayoutManager2

LayoutManager for JSplitPanes that have an orientation of HORIZONTAL_SPLIT.

Field Summary
protected Component[] | components
protected int[] | sizes
Method Summary
void | addLayoutComponent(Component comp, Object constraints) Adds the specified component to the layout, using the specified constraint object.
void | addLayoutComponent(String place, Component component) Adds the component at place.
protected int | getAvailableSize(Dimension containerSize, Insets insets) Returns the available width based on the container size and Insets.
protected int | getInitialLocation(Insets insets) Returns the left inset, unless the Insets are null in which case 0 is returned.
float | getLayoutAlignmentX(Container target) Returns the alignment along the x axis.
float | getLayoutAlignmentY(Container target) Returns the alignment along the y axis.
protected int | getPreferredSizeOfComponent(Component c) Returns the width of the passed in Components preferred size.
protected int | getSizeOfComponent(Component c) Returns the width of the passed in component.
protected int[] | getSizes() Returns the sizes of the components.
void | invalidateLayout(Container c) Does nothing.
void | layoutContainer(Container container) Does the actual layout.
Dimension | maximumLayoutSize(Container target) Returns the maximum layout size, which is Integer.MAX_VALUE in both directions.
Dimension | minimumLayoutSize(Container container) Returns the minimum size needed to contain the children.
Dimension | preferredLayoutSize(Container container) Returns the preferred size needed to contain the children.
void | removeLayoutComponent(Component component) Removes the specified component from our knowledge.
protected void | resetSizeAt(int index) Resets the size of the Component at the passed in location.
void | resetToPreferredSizes() Marks the receiver so that the next time this instance is laid out it'll ask for the preferred sizes.
protected void | setComponentToSize(Component c, int size, int location, Insets insets, Dimension containerSize) Sets the width of the component c to be size, placing its x location at location, y to the insets.top and height to the containersize.height less the top and bottom insets.
protected void | setSizes(int[] newSizes) Sets the sizes to newSizes.
protected void | updateComponents() Determines the components.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

sizes

protected int[] sizes

components

protected Component[] components
Method Detail

layoutContainer

public void layoutContainer(Container container)
Does the actual layout.

Specified by:
layoutContainer in interface LayoutManager
Parameters:
container - the container to be laid out

addLayoutComponent

public void addLayoutComponent(String place,
                               Component component)
Adds the component at place. Place must be one of JSplitPane.LEFT, RIGHT, TOP, BOTTOM, or null (for the divider).

Specified by:
addLayoutComponent in interface LayoutManager
Parameters:
place - the string to be associated with the component
component - the component to be added

minimumLayoutSize

public Dimension minimumLayoutSize(Container container)
Returns the minimum size needed to contain the children. The width is the sum of all the childrens min widths and the height is the largest of the childrens minimum heights.

Specified by:
minimumLayoutSize in interface LayoutManager
Parameters:
container - the component to be laid out
See Also:
LayoutManager.preferredLayoutSize(java.awt.Container)

preferredLayoutSize

public Dimension preferredLayoutSize(Container container)
Returns the preferred size needed to contain the children. The width is the sum of all the childrens preferred widths and the height is the largest of the childrens preferred heights.

Specified by:
preferredLayoutSize in interface LayoutManager
Parameters:
container - the container to be laid out
See Also:
LayoutManager.minimumLayoutSize(java.awt.Container)

removeLayoutComponent

public void removeLayoutComponent(Component component)
Removes the specified component from our knowledge.

Specified by:
removeLayoutComponent in interface LayoutManager
Parameters:
component - the component to be removed

addLayoutComponent

public void addLayoutComponent(Component comp,
                               Object constraints)
Adds the specified component to the layout, using the specified constraint object.

Specified by:
addLayoutComponent in interface LayoutManager2
Parameters:
comp - the component to be added
constraints - where/how the component is added to the layout.

getLayoutAlignmentX

public float getLayoutAlignmentX(Container target)
Returns the alignment along the x axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.

Specified by:
getLayoutAlignmentX in interface LayoutManager2

getLayoutAlignmentY

public float getLayoutAlignmentY(Container target)
Returns the alignment along the y axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.

Specified by:
getLayoutAlignmentY in interface LayoutManager2

invalidateLayout

public void invalidateLayout(Container c)
Does nothing. If the developer really wants to change the size of one of the views JSplitPane.resetToPreferredSizes should be messaged.

Specified by:
invalidateLayout in interface LayoutManager2

maximumLayoutSize

public Dimension maximumLayoutSize(Container target)
Returns the maximum layout size, which is Integer.MAX_VALUE in both directions.

Specified by:
maximumLayoutSize in interface LayoutManager2
See Also:
Component.getMaximumSize(), LayoutManager

resetToPreferredSizes

public void resetToPreferredSizes()
Marks the receiver so that the next time this instance is laid out it'll ask for the preferred sizes.

resetSizeAt

protected void resetSizeAt(int index)
Resets the size of the Component at the passed in location.

setSizes

protected void setSizes(int[] newSizes)
Sets the sizes to newSizes.

getSizes

protected int[] getSizes()
Returns the sizes of the components.

getPreferredSizeOfComponent

protected int getPreferredSizeOfComponent(Component c)
Returns the width of the passed in Components preferred size.

getSizeOfComponent

protected int getSizeOfComponent(Component c)
Returns the width of the passed in component.

getAvailableSize

protected int getAvailableSize(Dimension containerSize,
                               Insets insets)
Returns the available width based on the container size and Insets.

getInitialLocation

protected int getInitialLocation(Insets insets)
Returns the left inset, unless the Insets are null in which case 0 is returned.

setComponentToSize

protected void setComponentToSize(Component c,
                                  int size,
                                  int location,
                                  Insets insets,
                                  Dimension containerSize)
Sets the width of the component c to be size, placing its x location at location, y to the insets.top and height to the containersize.height less the top and bottom insets.

updateComponents

protected void updateComponents()
Determines the components. This should be called whenever a new instance of this is installed into an existing SplitPane.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSplitPaneUI.BasicVerticalLayoutManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSplitPaneUI.BasicVerticalLayoutManager

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicSplitPaneUI.BasicHorizontalLayoutManager
        extended by  javax.swing.plaf.basic.BasicSplitPaneUI.BasicVerticalLayoutManager
All Implemented Interfaces:
LayoutManager, LayoutManager2
Enclosing class:
BasicSplitPaneUI
public class BasicSplitPaneUI.BasicVerticalLayoutManager
extends BasicSplitPaneUI.BasicHorizontalLayoutManager

LayoutManager used for JSplitPanes with an orientation of VERTICAL_SPLIT.

Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicSplitPaneUI.BasicHorizontalLayoutManager
components, sizes
Constructor Summary
BasicSplitPaneUI.BasicVerticalLayoutManager()
Method Summary
Methods inherited from class javax.swing.plaf.basic.BasicSplitPaneUI.BasicHorizontalLayoutManager
addLayoutComponent, addLayoutComponent, getAvailableSize, getInitialLocation, getLayoutAlignmentX, getLayoutAlignmentY, getPreferredSizeOfComponent, getSizeOfComponent, getSizes, invalidateLayout, layoutContainer, maximumLayoutSize, minimumLayoutSize, preferredLayoutSize, removeLayoutComponent, resetSizeAt, resetToPreferredSizes, setComponentToSize, setSizes, updateComponents
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSplitPaneUI.BasicVerticalLayoutManager

public BasicSplitPaneUI.BasicVerticalLayoutManager()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSplitPaneUI.FocusHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSplitPaneUI.FocusHandler

java.lang.Object
    extended by  java.awt.event.FocusAdapter
        extended by  javax.swing.plaf.basic.BasicSplitPaneUI.FocusHandler
All Implemented Interfaces:
FocusListener, EventListener
Enclosing class:
BasicSplitPaneUI
public class BasicSplitPaneUI.FocusHandler
extends FocusAdapter

Implementation of the FocusListener that the JSplitPane UI uses.

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicSplitPaneUI.

Constructor Summary
BasicSplitPaneUI.FocusHandler()
Method Summary
void | focusGained(FocusEvent ev) Invoked when a component gains the keyboard focus.
void | focusLost(FocusEvent ev) Invoked when a component loses the keyboard focus.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSplitPaneUI.FocusHandler

public BasicSplitPaneUI.FocusHandler()
Method Detail

focusGained

public void focusGained(FocusEvent ev)
Description copied from class: FocusAdapter
Invoked when a component gains the keyboard focus.

Specified by:
focusGained in interface FocusListener
Overrides:
focusGained in class FocusAdapter

focusLost

public void focusLost(FocusEvent ev)
Description copied from class: FocusAdapter
Invoked when a component loses the keyboard focus.

Specified by:
focusLost in interface FocusListener
Overrides:
focusLost in class FocusAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSplitPaneUI.KeyboardDownRightHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSplitPaneUI.KeyboardDownRightHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardDownRightHandler
All Implemented Interfaces:
ActionListener, EventListener
Enclosing class:
BasicSplitPaneUI
public class BasicSplitPaneUI.KeyboardDownRightHandler
extends Object
implements ActionListener

Implementation of an ActionListener that the JSplitPane UI uses for handling specific key presses.

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicSplitPaneUI.

Constructor Summary
BasicSplitPaneUI.KeyboardDownRightHandler()
Method Summary
 void actionPerformed(ActionEvent ev)
Invoked when an action occurs.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSplitPaneUI.KeyboardDownRightHandler

public BasicSplitPaneUI.KeyboardDownRightHandler()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent ev)
Description copied from interface: ActionListener
Invoked when an action occurs.

Specified by:
actionPerformed in interface ActionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSplitPaneUI.KeyboardEndHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSplitPaneUI.KeyboardEndHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardEndHandler
All Implemented Interfaces:
ActionListener, EventListener
Enclosing class:
BasicSplitPaneUI
public class BasicSplitPaneUI.KeyboardEndHandler
extends Object
implements ActionListener

Implementation of an ActionListener that the JSplitPane UI uses for handling specific key presses.

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicSplitPaneUI.

Constructor Summary
BasicSplitPaneUI.KeyboardEndHandler()
Method Summary
 void actionPerformed(ActionEvent ev)
Invoked when an action occurs.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSplitPaneUI.KeyboardEndHandler

public BasicSplitPaneUI.KeyboardEndHandler()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent ev)
Description copied from interface: ActionListener
Invoked when an action occurs.

Specified by:
actionPerformed in interface ActionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSplitPaneUI.KeyboardHomeHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSplitPaneUI.KeyboardHomeHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardHomeHandler
All Implemented Interfaces:
ActionListener, EventListener
Enclosing class:
BasicSplitPaneUI
public class BasicSplitPaneUI.KeyboardHomeHandler
extends Object
implements ActionListener

Implementation of an ActionListener that the JSplitPane UI uses for handling specific key presses.

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicSplitPaneUI.

Constructor Summary
BasicSplitPaneUI.KeyboardHomeHandler()
Method Summary
 void actionPerformed(ActionEvent ev)
Invoked when an action occurs.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSplitPaneUI.KeyboardHomeHandler

public BasicSplitPaneUI.KeyboardHomeHandler()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent ev)
Description copied from interface: ActionListener
Invoked when an action occurs.

Specified by:
actionPerformed in interface ActionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSplitPaneUI.KeyboardResizeToggleHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSplitPaneUI.KeyboardResizeToggleHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardResizeToggleHandler
All Implemented Interfaces:
ActionListener, EventListener
Enclosing class:
BasicSplitPaneUI
public class BasicSplitPaneUI.KeyboardResizeToggleHandler
extends Object
implements ActionListener

Implementation of an ActionListener that the JSplitPane UI uses for handling specific key presses.

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicSplitPaneUI.

Constructor Summary
BasicSplitPaneUI.KeyboardResizeToggleHandler()
Method Summary
 void actionPerformed(ActionEvent ev)
Invoked when an action occurs.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSplitPaneUI.KeyboardResizeToggleHandler

public BasicSplitPaneUI.KeyboardResizeToggleHandler()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent ev)
Description copied from interface: ActionListener
Invoked when an action occurs.

Specified by:
actionPerformed in interface ActionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSplitPaneUI.KeyboardUpLeftHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSplitPaneUI.KeyboardUpLeftHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardUpLeftHandler
All Implemented Interfaces:
ActionListener, EventListener
Enclosing class:
BasicSplitPaneUI
public class BasicSplitPaneUI.KeyboardUpLeftHandler
extends Object
implements ActionListener

Implementation of an ActionListener that the JSplitPane UI uses for handling specific key presses.

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicSplitPaneUI.

Constructor Summary
BasicSplitPaneUI.KeyboardUpLeftHandler()
Method Summary
 void actionPerformed(ActionEvent ev)
Invoked when an action occurs.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSplitPaneUI.KeyboardUpLeftHandler

public BasicSplitPaneUI.KeyboardUpLeftHandler()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent ev)
Description copied from interface: ActionListener
Invoked when an action occurs.

Specified by:
actionPerformed in interface ActionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicSplitPaneUI.PropertyHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicSplitPaneUI.PropertyHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicSplitPaneUI.PropertyHandler
All Implemented Interfaces:
PropertyChangeListener, EventListener
Enclosing class:
BasicSplitPaneUI
public class BasicSplitPaneUI.PropertyHandler
extends Object
implements PropertyChangeListener

Implementation of the PropertyChangeListener that the JSplitPane UI uses.

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicSplitPaneUI.

Constructor Summary
BasicSplitPaneUI.PropertyHandler()
Method Summary
 void propertyChange(PropertyChangeEvent e)
Messaged from the JSplitPane the receiver is contained in.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicSplitPaneUI.PropertyHandler

public BasicSplitPaneUI.PropertyHandler()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
Messaged from the JSplitPane the receiver is contained in. May potentially reset the layout manager and cause a validate to be sent.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTabbedPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTabbedPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TabbedPaneUI
            extended by  javax.swing.plaf.basic.BasicTabbedPaneUI
All Implemented Interfaces:
SwingConstants
Direct Known Subclasses:
MetalTabbedPaneUI
public class BasicTabbedPaneUI
extends TabbedPaneUI
implements SwingConstants

A Basic L&F implementation of TabbedPaneUI.

Nested Class Summary
class | BasicTabbedPaneUI.FocusHandler This class should be treated as a "protected" inner class.
class | BasicTabbedPaneUI.MouseHandler This class should be treated as a "protected" inner class.
class | BasicTabbedPaneUI.PropertyChangeHandler This class should be treated as a "protected" inner class.
class | BasicTabbedPaneUI.TabbedPaneLayout This class should be treated as a "protected" inner class.
class | BasicTabbedPaneUI.TabSelectionHandler This class should be treated as a "protected" inner class.
Field Summary
protected Rectangle | calcRect A rectangle used for general layout calculations in order to avoid constructing many new Rectangles on the fly.
protected Insets | contentBorderInsets
protected Color | darkShadow
protected KeyStroke | downKey Deprecated. As of Java 2 platform v1.3.
protected Color | focus
protected FocusListener | focusListener
protected Color | highlight
protected KeyStroke | leftKey Deprecated. As of Java 2 platform v1.3.
protected Color | lightHighlight
protected int | maxTabHeight
protected int | maxTabWidth
protected MouseListener | mouseListener
protected PropertyChangeListener | propertyChangeListener
protected Rectangle[] | rects
protected KeyStroke | rightKey Deprecated. As of Java 2 platform v1.3.
protected int | runCount
protected int | selectedRun
protected Insets | selectedTabPadInsets
protected Color | shadow
protected Insets | tabAreaInsets
protected ChangeListener | tabChangeListener
protected Insets | tabInsets
protected JTabbedPane | tabPane
protected int | tabRunOverlay
protected int[] | tabRuns
protected int | textIconGap
protected KeyStroke | upKey Deprecated. As of Java 2 platform v1.3.
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
BasicTabbedPaneUI()
Method Summary
protected void | assureRectsCreated(int tabCount)
protected int | calculateMaxTabHeight(int tabPlacement)
protected int | calculateMaxTabWidth(int tabPlacement)
protected int | calculateTabAreaHeight(int tabPlacement, int horizRunCount, int maxTabHeight)
protected int | calculateTabAreaWidth(int tabPlacement, int vertRunCount, int maxTabWidth)
protected int | calculateTabHeight(int tabPlacement, int tabIndex, int fontHeight)
protected int | calculateTabWidth(int tabPlacement, int tabIndex, FontMetrics metrics)
protected ChangeListener | createChangeListener()
protected FocusListener | createFocusListener()
protected LayoutManager | createLayoutManager() Invoked by installUI to create a layout manager object to manage the JTabbedPane.
protected MouseListener | createMouseListener()
protected PropertyChangeListener | createPropertyChangeListener()
protected JButton | createScrollButton(int direction) Creates and returns a JButton that will provide the user with a way to scroll the tabs in a particular direction.
static ComponentUI | createUI(JComponent c)
protected void | expandTabRunsArray()
protected int | getBaseline(int tab) Returns the baseline for the specified tab.
int | getBaseline(JComponent c, int width, int height) Returns the baseline.
protected int | getBaselineOffset() Returns the amount the baseline is offset by.
Component.BaselineResizeBehavior | getBaselineResizeBehavior(JComponent c) Returns an enum indicating how the baseline of the component changes as the size changes.
protected Insets | getContentBorderInsets(int tabPlacement)
protected int | getFocusIndex() Returns the index of the tab that has focus.
protected FontMetrics | getFontMetrics()
protected Icon | getIconForTab(int tabIndex)
Dimension | getMaximumSize(JComponent c) Returns the specified component's maximum size appropriate for the look and feel.
Dimension | getMinimumSize(JComponent c) Returns the specified component's minimum size appropriate for the look and feel.
protected int | getNextTabIndex(int base)
protected int | getNextTabIndexInRun(int tabCount, int base)
protected int | getNextTabRun(int baseRun)
protected int | getPreviousTabIndex(int base)
protected int | getPreviousTabIndexInRun(int tabCount, int base)
protected int | getPreviousTabRun(int baseRun)
protected int | getRolloverTab() Returns the tab the mouse is currently over, or -1 if the mouse is no longer over any tab.
protected int | getRunForTab(int tabCount, int tabIndex)
protected Insets | getSelectedTabPadInsets(int tabPlacement)
protected Insets | getTabAreaInsets(int tabPlacement)
protected Rectangle | getTabBounds(int tabIndex, Rectangle dest) Returns the bounds of the specified tab in the coordinate space of the JTabbedPane component.
Rectangle | getTabBounds(JTabbedPane pane, int i) Returns the bounds of the specified tab index.
protected Insets | getTabInsets(int tabPlacement, int tabIndex)
protected int | getTabLabelShiftX(int tabPlacement, int tabIndex, boolean isSelected)
protected int | getTabLabelShiftY(int tabPlacement, int tabIndex, boolean isSelected)
int | getTabRunCount(JTabbedPane pane)
protected int | getTabRunIndent(int tabPlacement, int run)
protected int | getTabRunOffset(int tabPlacement, int tabCount, int tabIndex, boolean forward)
protected int | getTabRunOverlay(int tabPlacement)
protected View | getTextViewForTab(int tabIndex) Returns the text View object required to render stylized text (HTML) for the specified tab or null if no specialized text rendering is needed for this tab.
protected Component | getVisibleComponent()
protected void | installComponents() Creates and installs any required subcomponents for the JTabbedPane.
protected void | installDefaults()
protected void | installKeyboardActions()
protected void | installListeners()
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
protected int | lastTabInRun(int tabCount, int run)
protected void | layoutLabel(int tabPlacement, FontMetrics metrics, int tabIndex, String title, Icon icon, Rectangle tabRect, Rectangle iconRect, Rectangle textRect, boolean isSelected)
protected void | navigateSelectedTab(int direction)
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
protected void | paintContentBorder(Graphics g, int tabPlacement, int selectedIndex)
protected void | paintContentBorderBottomEdge(Graphics g, int tabPlacement, int selectedIndex, int x, int y, int w, int h)
protected void | paintContentBorderLeftEdge(Graphics g, int tabPlacement, int selectedIndex, int x, int y, int w, int h)
protected void | paintContentBorderRightEdge(Graphics g, int tabPlacement, int selectedIndex, int x, int y, int w, int h)
protected void | paintContentBorderTopEdge(Graphics g, int tabPlacement, int selectedIndex, int x, int y, int w, int h)
protected void | paintFocusIndicator(Graphics g, int tabPlacement, Rectangle[] rects, int tabIndex, Rectangle iconRect, Rectangle textRect, boolean isSelected)
protected void | paintIcon(Graphics g, int tabPlacement, int tabIndex, Icon icon, Rectangle iconRect, boolean isSelected)
protected void | paintTab(Graphics g, int tabPlacement, Rectangle[] rects, int tabIndex, Rectangle iconRect, Rectangle textRect)
protected void | paintTabArea(Graphics g, int tabPlacement, int selectedIndex) Paints the tabs in the tab area.
protected void | paintTabBackground(Graphics g, int tabPlacement, int tabIndex, int x, int y, int w, int h, boolean isSelected)
protected void | paintTabBorder(Graphics g, int tabPlacement, int tabIndex, int x, int y, int w, int h, boolean isSelected) this function draws the border around each tab note that this function does now draw the background of the tab.
protected void | paintText(Graphics g, int tabPlacement, Font font, FontMetrics metrics, int tabIndex, String title, Rectangle textRect, boolean isSelected)
protected static void | rotateInsets(Insets topInsets, Insets targetInsets, int targetPlacement)
protected void | selectAdjacentRunTab(int tabPlacement, int tabIndex, int offset)
protected void | selectNextTab(int current)
protected void | selectNextTabInRun(int current)
protected void | selectPreviousTab(int current)
protected void | selectPreviousTabInRun(int current)
protected void | setRolloverTab(int index) Sets the tab the mouse is currently over to index.
protected void | setVisibleComponent(Component component)
protected boolean | shouldPadTabRun(int tabPlacement, int run)
protected boolean | shouldRotateTabRuns(int tabPlacement)
int | tabForCoordinate(JTabbedPane pane, int x, int y) Returns the tab index which intersects the specified point in the JTabbedPane's coordinate space.
protected void | uninstallComponents() Removes any installed subcomponents from the JTabbedPane.
protected void | uninstallDefaults()
protected void | uninstallKeyboardActions()
protected void | uninstallListeners()
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getPreferredSize, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

tabPane

protected JTabbedPane tabPane

highlight

protected Color highlight

lightHighlight

protected Color lightHighlight

shadow

protected Color shadow

darkShadow

protected Color darkShadow

focus

protected Color focus

textIconGap

protected int textIconGap

tabRunOverlay

protected int tabRunOverlay

tabInsets

protected Insets tabInsets

selectedTabPadInsets

protected Insets selectedTabPadInsets

tabAreaInsets

protected Insets tabAreaInsets

contentBorderInsets

protected Insets contentBorderInsets

upKey

@Deprecated
protected KeyStroke upKey
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

downKey

@Deprecated
protected KeyStroke downKey
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

leftKey

@Deprecated
protected KeyStroke leftKey
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

rightKey

@Deprecated
protected KeyStroke rightKey
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

tabRuns

protected int[] tabRuns

runCount

protected int runCount

selectedRun

protected int selectedRun

rects

protected Rectangle[] rects

maxTabHeight

protected int maxTabHeight

maxTabWidth

protected int maxTabWidth

tabChangeListener

protected ChangeListener tabChangeListener

propertyChangeListener

protected PropertyChangeListener propertyChangeListener

mouseListener

protected MouseListener mouseListener

focusListener

protected FocusListener focusListener

calcRect

protected transient Rectangle calcRect
A rectangle used for general layout calculations in order to avoid constructing many new Rectangles on the fly.

Constructor Detail

BasicTabbedPaneUI

public BasicTabbedPaneUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

createLayoutManager

protected LayoutManager createLayoutManager()
Invoked by installUI to create a layout manager object to manage the JTabbedPane.

Returns:
a layout manager object
See Also:
BasicTabbedPaneUI.TabbedPaneLayout, JTabbedPane.getTabLayoutPolicy()

installComponents

protected void installComponents()
Creates and installs any required subcomponents for the JTabbedPane. Invoked by installUI.

Since:
1.4

createScrollButton

protected JButton createScrollButton(int direction)
Creates and returns a JButton that will provide the user with a way to scroll the tabs in a particular direction. The returned JButton must be instance of UIResource.

Parameters:
direction - One of the SwingConstants constants: SOUTH, NORTH, EAST or WEST
Returns:
Widget for user to
Throws:
IllegalArgumentException - if direction is not one of NORTH, SOUTH, EAST or WEST
Since:
1.5
See Also:
JTabbedPane.setTabPlacement(int), SwingConstants

uninstallComponents

protected void uninstallComponents()
Removes any installed subcomponents from the JTabbedPane. Invoked by uninstallUI.

Since:
1.4

installDefaults

protected void installDefaults()

uninstallDefaults

protected void uninstallDefaults()

installListeners

protected void installListeners()

uninstallListeners

protected void uninstallListeners()

createMouseListener

protected MouseListener createMouseListener()

createFocusListener

protected FocusListener createFocusListener()

createChangeListener

protected ChangeListener createChangeListener()

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener()

installKeyboardActions

protected void installKeyboardActions()

uninstallKeyboardActions

protected void uninstallKeyboardActions()

setRolloverTab

protected void setRolloverTab(int index)
Sets the tab the mouse is currently over to index. index will be -1 if the mouse is no longer over any tab. No checking is done to ensure the passed in index identifies a valid tab.

Parameters:
index - Index of the tab the mouse is over.
Since:
1.5

getRolloverTab

protected int getRolloverTab()
Returns the tab the mouse is currently over, or -1 if the mouse is no longer over any tab.

Returns:
the tab the mouse is currently over, or -1 if the mouse is no longer over any tab
Since:
1.5

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's minimum size appropriate for the look and feel. If null is returned, the minimum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's maximum size appropriate for the look and feel. If null is returned, the maximum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getBaseline

public int getBaseline(JComponent c,
                       int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class ComponentUI
Parameters:
c - JComponent baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
NullPointerException - if c is null
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.

Overrides:
getBaselineResizeBehavior in class ComponentUI
Parameters:
c - JComponent to return baseline resize behavior for
Returns:
an enum indicating how the baseline changes as the component size changes
Throws:
NullPointerException - if c is null
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getBaseline

protected int getBaseline(int tab)
Returns the baseline for the specified tab.

Parameters:
tab - index of tab to get baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
IndexOutOfBoundsException - if index is out of range (index < 0 || index >= tab count)
Since:
1.6

getBaselineOffset

protected int getBaselineOffset()
Returns the amount the baseline is offset by. This is typically the same as getTabLabelShiftY.

Returns:
amount to offset the baseline by
Since:
1.6

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

paintTabArea

protected void paintTabArea(Graphics g,
                            int tabPlacement,
                            int selectedIndex)
Paints the tabs in the tab area. Invoked by paint(). The graphics parameter must be a valid Graphics object. Tab placement may be either: JTabbedPane.TOP, JTabbedPane.BOTTOM, JTabbedPane.LEFT, or JTabbedPane.RIGHT. The selected index must be a valid tabbed pane tab index (0 to tab count - 1, inclusive) or -1 if no tab is currently selected. The handling of invalid parameters is unspecified.

Parameters:
g - the graphics object to use for rendering
tabPlacement - the placement for the tabs within the JTabbedPane
selectedIndex - the tab index of the selected component
Since:
1.4

paintTab

protected void paintTab(Graphics g,
                        int tabPlacement,
                        Rectangle[] rects,
                        int tabIndex,
                        Rectangle iconRect,
                        Rectangle textRect)

layoutLabel

protected void layoutLabel(int tabPlacement,
                           FontMetrics metrics,
                           int tabIndex,
                           String title,
                           Icon icon,
                           Rectangle tabRect,
                           Rectangle iconRect,
                           Rectangle textRect,
                           boolean isSelected)

paintIcon

protected void paintIcon(Graphics g,
                         int tabPlacement,
                         int tabIndex,
                         Icon icon,
                         Rectangle iconRect,
                         boolean isSelected)

paintText

protected void paintText(Graphics g,
                         int tabPlacement,
                         Font font,
                         FontMetrics metrics,
                         int tabIndex,
                         String title,
                         Rectangle textRect,
                         boolean isSelected)

getTabLabelShiftX

protected int getTabLabelShiftX(int tabPlacement,
                                int tabIndex,
                                boolean isSelected)

getTabLabelShiftY

protected int getTabLabelShiftY(int tabPlacement,
                                int tabIndex,
                                boolean isSelected)

paintFocusIndicator

protected void paintFocusIndicator(Graphics g,
                                   int tabPlacement,
                                   Rectangle[] rects,
                                   int tabIndex,
                                   Rectangle iconRect,
                                   Rectangle textRect,
                                   boolean isSelected)

paintTabBorder

protected void paintTabBorder(Graphics g,
                              int tabPlacement,
                              int tabIndex,
                              int x,
                              int y,
                              int w,
                              int h,
                              boolean isSelected)
this function draws the border around each tab note that this function does now draw the background of the tab. that is done elsewhere

paintTabBackground

protected void paintTabBackground(Graphics g,
                                  int tabPlacement,
                                  int tabIndex,
                                  int x,
                                  int y,
                                  int w,
                                  int h,
                                  boolean isSelected)

paintContentBorder

protected void paintContentBorder(Graphics g,
                                  int tabPlacement,
                                  int selectedIndex)

paintContentBorderTopEdge

protected void paintContentBorderTopEdge(Graphics g,
                                         int tabPlacement,
                                         int selectedIndex,
                                         int x,
                                         int y,
                                         int w,
                                         int h)

paintContentBorderLeftEdge

protected void paintContentBorderLeftEdge(Graphics g,
                                          int tabPlacement,
                                          int selectedIndex,
                                          int x,
                                          int y,
                                          int w,
                                          int h)

paintContentBorderBottomEdge

protected void paintContentBorderBottomEdge(Graphics g,
                                            int tabPlacement,
                                            int selectedIndex,
                                            int x,
                                            int y,
                                            int w,
                                            int h)

paintContentBorderRightEdge

protected void paintContentBorderRightEdge(Graphics g,
                                           int tabPlacement,
                                           int selectedIndex,
                                           int x,
                                           int y,
                                           int w,
                                           int h)

getTabBounds

public Rectangle getTabBounds(JTabbedPane pane,
                              int i)
Returns the bounds of the specified tab index. The bounds are with respect to the JTabbedPane's coordinate space.

Specified by:
getTabBounds in class TabbedPaneUI

getTabRunCount

public int getTabRunCount(JTabbedPane pane)
Specified by:
getTabRunCount in class TabbedPaneUI

tabForCoordinate

public int tabForCoordinate(JTabbedPane pane,
                            int x,
                            int y)
Returns the tab index which intersects the specified point in the JTabbedPane's coordinate space.

Specified by:
tabForCoordinate in class TabbedPaneUI

getTabBounds

protected Rectangle getTabBounds(int tabIndex,
                                 Rectangle dest)
Returns the bounds of the specified tab in the coordinate space of the JTabbedPane component. This is required because the tab rects are by default defined in the coordinate space of the component where they are rendered, which could be the JTabbedPane (for WRAP_TAB_LAYOUT) or a ScrollableTabPanel (SCROLL_TAB_LAYOUT). This method should be used whenever the tab rectangle must be relative to the JTabbedPane itself and the result should be placed in a designated Rectangle object (rather than instantiating and returning a new Rectangle each time). The tab index parameter must be a valid tabbed pane tab index (0 to tab count - 1, inclusive). The destination rectangle parameter must be a valid Rectangle instance. The handling of invalid parameters is unspecified.

Parameters:
tabIndex - the index of the tab
dest - the rectangle where the result should be placed
Returns:
the resulting rectangle
Since:
1.4

getVisibleComponent

protected Component getVisibleComponent()

setVisibleComponent

protected void setVisibleComponent(Component component)

assureRectsCreated

protected void assureRectsCreated(int tabCount)

expandTabRunsArray

protected void expandTabRunsArray()

getRunForTab

protected int getRunForTab(int tabCount,
                           int tabIndex)

lastTabInRun

protected int lastTabInRun(int tabCount,
                           int run)

getTabRunOverlay

protected int getTabRunOverlay(int tabPlacement)

getTabRunIndent

protected int getTabRunIndent(int tabPlacement,
                              int run)

shouldPadTabRun

protected boolean shouldPadTabRun(int tabPlacement,
                                  int run)

shouldRotateTabRuns

protected boolean shouldRotateTabRuns(int tabPlacement)

getIconForTab

protected Icon getIconForTab(int tabIndex)

getTextViewForTab

protected View getTextViewForTab(int tabIndex)
Returns the text View object required to render stylized text (HTML) for the specified tab or null if no specialized text rendering is needed for this tab. This is provided to support html rendering inside tabs.

Parameters:
tabIndex - the index of the tab
Returns:
the text view to render the tab's text or null if no specialized rendering is required
Since:
1.4

calculateTabHeight

protected int calculateTabHeight(int tabPlacement,
                                 int tabIndex,
                                 int fontHeight)

calculateMaxTabHeight

protected int calculateMaxTabHeight(int tabPlacement)

calculateTabWidth

protected int calculateTabWidth(int tabPlacement,
                                int tabIndex,
                                FontMetrics metrics)

calculateMaxTabWidth

protected int calculateMaxTabWidth(int tabPlacement)

calculateTabAreaHeight

protected int calculateTabAreaHeight(int tabPlacement,
                                     int horizRunCount,
                                     int maxTabHeight)

calculateTabAreaWidth

protected int calculateTabAreaWidth(int tabPlacement,
                                    int vertRunCount,
                                    int maxTabWidth)

getTabInsets

protected Insets getTabInsets(int tabPlacement,
                              int tabIndex)

getSelectedTabPadInsets

protected Insets getSelectedTabPadInsets(int tabPlacement)

getTabAreaInsets

protected Insets getTabAreaInsets(int tabPlacement)

getContentBorderInsets

protected Insets getContentBorderInsets(int tabPlacement)

getFontMetrics

protected FontMetrics getFontMetrics()

navigateSelectedTab

protected void navigateSelectedTab(int direction)

selectNextTabInRun

protected void selectNextTabInRun(int current)

selectPreviousTabInRun

protected void selectPreviousTabInRun(int current)

selectNextTab

protected void selectNextTab(int current)

selectPreviousTab

protected void selectPreviousTab(int current)

selectAdjacentRunTab

protected void selectAdjacentRunTab(int tabPlacement,
                                    int tabIndex,
                                    int offset)

getFocusIndex

protected int getFocusIndex()
Returns the index of the tab that has focus.

Returns:
index of tab that has focus
Since:
1.5

getTabRunOffset

protected int getTabRunOffset(int tabPlacement,
                              int tabCount,
                              int tabIndex,
                              boolean forward)

getPreviousTabIndex

protected int getPreviousTabIndex(int base)

getNextTabIndex

protected int getNextTabIndex(int base)

getNextTabIndexInRun

protected int getNextTabIndexInRun(int tabCount,
                                   int base)

getPreviousTabIndexInRun

protected int getPreviousTabIndexInRun(int tabCount,
                                       int base)

getPreviousTabRun

protected int getPreviousTabRun(int baseRun)

getNextTabRun

protected int getNextTabRun(int baseRun)

rotateInsets

protected static void rotateInsets(Insets topInsets,
                                   Insets targetInsets,
                                   int targetPlacement)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTabbedPaneUI.FocusHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTabbedPaneUI.FocusHandler

java.lang.Object
    extended by  java.awt.event.FocusAdapter
        extended by  javax.swing.plaf.basic.BasicTabbedPaneUI.FocusHandler
All Implemented Interfaces:
FocusListener, EventListener
Enclosing class:
BasicTabbedPaneUI
public class BasicTabbedPaneUI.FocusHandler
extends FocusAdapter

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicTabbedPaneUI.

Constructor Summary
BasicTabbedPaneUI.FocusHandler()
Method Summary
void | focusGained(FocusEvent e) Invoked when a component gains the keyboard focus.
void | focusLost(FocusEvent e) Invoked when a component loses the keyboard focus.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTabbedPaneUI.FocusHandler

public BasicTabbedPaneUI.FocusHandler()
Method Detail

focusGained

public void focusGained(FocusEvent e)
Description copied from class: FocusAdapter
Invoked when a component gains the keyboard focus.

Specified by:
focusGained in interface FocusListener
Overrides:
focusGained in class FocusAdapter

focusLost

public void focusLost(FocusEvent e)
Description copied from class: FocusAdapter
Invoked when a component loses the keyboard focus.

Specified by:
focusLost in interface FocusListener
Overrides:
focusLost in class FocusAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTabbedPaneUI.MouseHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTabbedPaneUI.MouseHandler

java.lang.Object
    extended by  java.awt.event.MouseAdapter
        extended by  javax.swing.plaf.basic.BasicTabbedPaneUI.MouseHandler
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, EventListener
Enclosing class:
BasicTabbedPaneUI
public class BasicTabbedPaneUI.MouseHandler
extends MouseAdapter

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicTabbedPaneUI.

Constructor Summary
BasicTabbedPaneUI.MouseHandler()
Method Summary
 void mousePressed(MouseEvent e)
Invoked when a mouse button has been pressed on a component.
Methods inherited from class java.awt.event.MouseAdapter
mouseClicked, mouseDragged, mouseEntered, mouseExited, mouseMoved, mouseReleased, mouseWheelMoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTabbedPaneUI.MouseHandler

public BasicTabbedPaneUI.MouseHandler()
Method Detail

mousePressed

public void mousePressed(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when a mouse button has been pressed on a component.

Specified by:
mousePressed in interface MouseListener
Overrides:
mousePressed in class MouseAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTabbedPaneUI.PropertyChangeHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTabbedPaneUI.PropertyChangeHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicTabbedPaneUI.PropertyChangeHandler
All Implemented Interfaces:
PropertyChangeListener, EventListener
Enclosing class:
BasicTabbedPaneUI
public class BasicTabbedPaneUI.PropertyChangeHandler
extends Object
implements PropertyChangeListener

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicTabbedPaneUI.

Constructor Summary
BasicTabbedPaneUI.PropertyChangeHandler()
Method Summary
 void propertyChange(PropertyChangeEvent e)
This method gets called when a bound property is changed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTabbedPaneUI.PropertyChangeHandler

public BasicTabbedPaneUI.PropertyChangeHandler()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTabbedPaneUI.TabbedPaneLayout

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTabbedPaneUI.TabbedPaneLayout

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicTabbedPaneUI.TabbedPaneLayout
All Implemented Interfaces:
LayoutManager
Direct Known Subclasses:
MetalTabbedPaneUI.TabbedPaneLayout
Enclosing class:
BasicTabbedPaneUI
public class BasicTabbedPaneUI.TabbedPaneLayout
extends Object
implements LayoutManager

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicTabbedPaneUI.

Constructor Summary
BasicTabbedPaneUI.TabbedPaneLayout()
Method Summary
void | addLayoutComponent(String name, Component comp) If the layout manager uses a per-component string, adds the component comp to the layout, associating it with the string specified by name.
void | calculateLayoutInfo()
protected Dimension | calculateSize(boolean minimum)
protected void | calculateTabRects(int tabPlacement, int tabCount)
void | layoutContainer(Container parent) Lays out the specified container.
Dimension | minimumLayoutSize(Container parent) Calculates the minimum size dimensions for the specified container, given the components it contains.
protected void | normalizeTabRuns(int tabPlacement, int tabCount, int start, int max)
protected void | padSelectedTab(int tabPlacement, int selectedIndex)
protected void | padTabRun(int tabPlacement, int start, int end, int max)
Dimension | preferredLayoutSize(Container parent) Calculates the preferred size dimensions for the specified container, given the components it contains.
protected int | preferredTabAreaHeight(int tabPlacement, int width)
protected int | preferredTabAreaWidth(int tabPlacement, int height)
void | removeLayoutComponent(Component comp) Removes the specified component from the layout.
protected void | rotateTabRuns(int tabPlacement, int selectedRun)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTabbedPaneUI.TabbedPaneLayout

public BasicTabbedPaneUI.TabbedPaneLayout()
Method Detail

addLayoutComponent

public void addLayoutComponent(String name,
                               Component comp)
Description copied from interface: LayoutManager
If the layout manager uses a per-component string, adds the component comp to the layout, associating it with the string specified by name.

Specified by:
addLayoutComponent in interface LayoutManager
Parameters:
name - the string to be associated with the component
comp - the component to be added

removeLayoutComponent

public void removeLayoutComponent(Component comp)
Description copied from interface: LayoutManager
Removes the specified component from the layout.

Specified by:
removeLayoutComponent in interface LayoutManager
Parameters:
comp - the component to be removed

preferredLayoutSize

public Dimension preferredLayoutSize(Container parent)
Description copied from interface: LayoutManager
Calculates the preferred size dimensions for the specified container, given the components it contains.

Specified by:
preferredLayoutSize in interface LayoutManager
Parameters:
parent - the container to be laid out
See Also:
LayoutManager.minimumLayoutSize(java.awt.Container)

minimumLayoutSize

public Dimension minimumLayoutSize(Container parent)
Description copied from interface: LayoutManager
Calculates the minimum size dimensions for the specified container, given the components it contains.

Specified by:
minimumLayoutSize in interface LayoutManager
Parameters:
parent - the component to be laid out
See Also:
LayoutManager.preferredLayoutSize(java.awt.Container)

calculateSize

protected Dimension calculateSize(boolean minimum)

preferredTabAreaHeight

protected int preferredTabAreaHeight(int tabPlacement,
                                     int width)

preferredTabAreaWidth

protected int preferredTabAreaWidth(int tabPlacement,
                                    int height)

layoutContainer

public void layoutContainer(Container parent)
Description copied from interface: LayoutManager
Lays out the specified container.

Specified by:
layoutContainer in interface LayoutManager
Parameters:
parent - the container to be laid out

calculateLayoutInfo

public void calculateLayoutInfo()

calculateTabRects

protected void calculateTabRects(int tabPlacement,
                                 int tabCount)

rotateTabRuns

protected void rotateTabRuns(int tabPlacement,
                             int selectedRun)

normalizeTabRuns

protected void normalizeTabRuns(int tabPlacement,
                                int tabCount,
                                int start,
                                int max)

padTabRun

protected void padTabRun(int tabPlacement,
                         int start,
                         int end,
                         int max)

padSelectedTab

protected void padSelectedTab(int tabPlacement,
                              int selectedIndex)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTabbedPaneUI.TabSelectionHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTabbedPaneUI.TabSelectionHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicTabbedPaneUI.TabSelectionHandler
All Implemented Interfaces:
EventListener, ChangeListener
Enclosing class:
BasicTabbedPaneUI
public class BasicTabbedPaneUI.TabSelectionHandler
extends Object
implements ChangeListener

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicTabbedPaneUI.

Constructor Summary
BasicTabbedPaneUI.TabSelectionHandler()
Method Summary
 void stateChanged(ChangeEvent e)
Invoked when the target of the listener has changed its state.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTabbedPaneUI.TabSelectionHandler

public BasicTabbedPaneUI.TabSelectionHandler()
Method Detail

stateChanged

public void stateChanged(ChangeEvent e)
Description copied from interface: ChangeListener
Invoked when the target of the listener has changed its state.

Specified by:
stateChanged in interface ChangeListener
Parameters:
e - a ChangeEvent object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTableHeaderUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTableHeaderUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TableHeaderUI
            extended by  javax.swing.plaf.basic.BasicTableHeaderUI

public class BasicTableHeaderUI
extends TableHeaderUI

BasicTableHeaderUI implementation

Nested Class Summary
 class BasicTableHeaderUI.MouseInputHandler
This inner class is marked "public" due to a compiler bug.
Field Summary
protected JTableHeader | header The JTableHeader that is delegating the painting to this UI.
protected MouseInputListener | mouseInputListener
protected CellRendererPane | rendererPane
Constructor Summary
BasicTableHeaderUI()
Method Summary
protected MouseInputListener | createMouseInputListener() Creates the mouse listener for the JTableHeader.
static ComponentUI | createUI(JComponent h)
int | getBaseline(JComponent c, int width, int height) Returns the baseline.
Dimension | getMaximumSize(JComponent c) Return the maximum size of the header.
Dimension | getMinimumSize(JComponent c) Return the minimum size of the header.
Dimension | getPreferredSize(JComponent c) Return the preferred size of the header.
protected int | getRolloverColumn() Returns the index of the column header over which the mouse currently is.
protected void | installDefaults() Initialize JTableHeader properties, e.g.
protected void | installKeyboardActions() Register all keyboard actions on the JTableHeader.
protected void | installListeners() Attaches listeners to the JTableHeader.
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
protected void | rolloverColumnUpdated(int oldColumn, int newColumn) This method gets called every time the rollover column in the table header is updated.
protected void | uninstallDefaults()
protected void | uninstallKeyboardActions() Unregisters default key actions.
protected void | uninstallListeners()
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaselineResizeBehavior, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

header

protected JTableHeader header
The JTableHeader that is delegating the painting to this UI.

rendererPane

protected CellRendererPane rendererPane

mouseInputListener

protected MouseInputListener mouseInputListener
Constructor Detail

BasicTableHeaderUI

public BasicTableHeaderUI()
Method Detail

createMouseInputListener

protected MouseInputListener createMouseInputListener()
Creates the mouse listener for the JTableHeader.

createUI

public static ComponentUI createUI(JComponent h)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

installDefaults

protected void installDefaults()
Initialize JTableHeader properties, e.g. font, foreground, and background. The font, foreground, and background properties are only set if their current value is either null or a UIResource, other properties are set if the current value is null.

See Also:
installUI(javax.swing.JComponent)

installListeners

protected void installListeners()
Attaches listeners to the JTableHeader.

installKeyboardActions

protected void installKeyboardActions()
Register all keyboard actions on the JTableHeader.

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

uninstallDefaults

protected void uninstallDefaults()

uninstallListeners

protected void uninstallListeners()

uninstallKeyboardActions

protected void uninstallKeyboardActions()
Unregisters default key actions.

getRolloverColumn

protected int getRolloverColumn()
Returns the index of the column header over which the mouse currently is. When the mouse is not over the table header, -1 is returned.

Returns:
the index of the current rollover column
Since:
1.6
See Also:
rolloverColumnUpdated(int, int)

rolloverColumnUpdated

protected void rolloverColumnUpdated(int oldColumn,
                                     int newColumn)
This method gets called every time the rollover column in the table header is updated. Every look and feel supporting rollover effect in table header should override this method and repaint the header.

Parameters:
oldColumn - the index of the previous rollover column or -1 if the mouse was not over a column
newColumn - the index of the new rollover column or -1 if the mouse is not over a column
Since:
1.6
See Also:
getRolloverColumn(), JTableHeader.getHeaderRect(int)

getBaseline

public int getBaseline(JComponent c,
                       int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class ComponentUI
Parameters:
c - JComponent baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
NullPointerException - if c is null
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Return the minimum size of the header. The minimum width is the sum of the minimum widths of each column (plus inter-cell spacing).

Overrides:
getMinimumSize in class ComponentUI
Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Return the preferred size of the header. The preferred height is the maximum of the preferred heights of all of the components provided by the header renderers. The preferred width is the sum of the preferred widths of each column (plus inter-cell spacing).

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Return the maximum size of the header. The maximum width is the sum of the maximum widths of each column (plus inter-cell spacing).

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTableHeaderUI.MouseInputHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTableHeaderUI.MouseInputHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicTableHeaderUI.MouseInputHandler
All Implemented Interfaces:
MouseListener, MouseMotionListener, EventListener, MouseInputListener
Enclosing class:
BasicTableHeaderUI
public class BasicTableHeaderUI.MouseInputHandler
extends Object
implements MouseInputListener

This inner class is marked "public" due to a compiler bug. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicTableUI.

Constructor Summary
BasicTableHeaderUI.MouseInputHandler()
Method Summary
void | mouseClicked(MouseEvent e) Invoked when the mouse button has been clicked (pressed and released) on a component.
void | mouseDragged(MouseEvent e) Invoked when a mouse button is pressed on a component and then dragged.
void | mouseEntered(MouseEvent e) Invoked when the mouse enters a component.
void | mouseExited(MouseEvent e) Invoked when the mouse exits a component.
void | mouseMoved(MouseEvent e) Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.
void | mousePressed(MouseEvent e) Invoked when a mouse button has been pressed on a component.
void | mouseReleased(MouseEvent e) Invoked when a mouse button has been released on a component.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTableHeaderUI.MouseInputHandler

public BasicTableHeaderUI.MouseInputHandler()
Method Detail

mouseClicked

public void mouseClicked(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse button has been clicked (pressed and released) on a component.

Specified by:
mouseClicked in interface MouseListener

mousePressed

public void mousePressed(MouseEvent e)
Description copied from interface: MouseListener
Invoked when a mouse button has been pressed on a component.

Specified by:
mousePressed in interface MouseListener

mouseMoved

public void mouseMoved(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.

Specified by:
mouseMoved in interface MouseMotionListener

mouseDragged

public void mouseDragged(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when a mouse button is pressed on a component and then dragged. MOUSE_DRAGGED events will continue to be delivered to the component where the drag originated until the mouse button is released (regardless of whether the mouse position is within the bounds of the component).

Due to platform-dependent Drag&Drop implementations, MOUSE_DRAGGED events may not be delivered during a native Drag&Drop operation.

Specified by:
mouseDragged in interface MouseMotionListener

mouseReleased

public void mouseReleased(MouseEvent e)
Description copied from interface: MouseListener
Invoked when a mouse button has been released on a component.

Specified by:
mouseReleased in interface MouseListener

mouseEntered

public void mouseEntered(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse enters a component.

Specified by:
mouseEntered in interface MouseListener

mouseExited

public void mouseExited(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse exits a component.

Specified by:
mouseExited in interface MouseListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTableUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTableUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TableUI
            extended by  javax.swing.plaf.basic.BasicTableUI

public class BasicTableUI
extends TableUI

BasicTableUI implementation

Nested Class Summary
class | BasicTableUI.FocusHandler This inner class is marked "public" due to a compiler bug.
class | BasicTableUI.KeyHandler This inner class is marked "public" due to a compiler bug.
class | BasicTableUI.MouseInputHandler This inner class is marked "public" due to a compiler bug.
Field Summary
protected FocusListener | focusListener
protected KeyListener | keyListener
protected MouseInputListener | mouseInputListener
protected CellRendererPane | rendererPane
protected JTable | table
Constructor Summary
BasicTableUI()
Method Summary
protected  FocusListener createFocusListener()
Creates the focus listener for handling keyboard navigation in the JTable.
protected  KeyListener createKeyListener()
Creates the key listener for handling keyboard navigation in the JTable.
protected  MouseInputListener createMouseInputListener()
Creates the mouse listener for the JTable.
static ComponentUI createUI(JComponent c)
 int getBaseline(JComponent c, int width, int height)
Returns the baseline.
 Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
 Dimension getMaximumSize(JComponent c)
Return the maximum size of the table.
 Dimension getMinimumSize(JComponent c)
Return the minimum size of the table.
 Dimension getPreferredSize(JComponent c)
Return the preferred size of the table.
protected  void installDefaults()
Initialize JTable properties, e.g.
protected  void installKeyboardActions()
Register all keyboard actions on the JTable.
protected  void installListeners()
Attaches listeners to the JTable.
 void installUI(JComponent c)
Configures the specified component appropriate for the look and feel.
 void paint(Graphics g, JComponent c)
Paint a representation of the table instance that was set in installUI().
protected  void uninstallDefaults()
protected  void uninstallKeyboardActions()
protected  void uninstallListeners()
 void uninstallUI(JComponent c)
Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

table

protected JTable table

rendererPane

protected CellRendererPane rendererPane

keyListener

protected KeyListener keyListener

focusListener

protected FocusListener focusListener

mouseInputListener

protected MouseInputListener mouseInputListener
Constructor Detail

BasicTableUI

public BasicTableUI()
Method Detail

createKeyListener

protected KeyListener createKeyListener()
Creates the key listener for handling keyboard navigation in the JTable.

createFocusListener

protected FocusListener createFocusListener()
Creates the focus listener for handling keyboard navigation in the JTable.

createMouseInputListener

protected MouseInputListener createMouseInputListener()
Creates the mouse listener for the JTable.

createUI

public static ComponentUI createUI(JComponent c)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

installDefaults

protected void installDefaults()
Initialize JTable properties, e.g. font, foreground, and background. The font, foreground, and background properties are only set if their current value is either null or a UIResource, other properties are set if the current value is null.

See Also:
installUI(javax.swing.JComponent)

installListeners

protected void installListeners()
Attaches listeners to the JTable.

installKeyboardActions

protected void installKeyboardActions()
Register all keyboard actions on the JTable.

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

uninstallDefaults

protected void uninstallDefaults()

uninstallListeners

protected void uninstallListeners()

uninstallKeyboardActions

protected void uninstallKeyboardActions()

getBaseline

public int getBaseline(JComponent c,
                       int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class ComponentUI
Parameters:
c - JComponent baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
NullPointerException - if c is null
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.

Overrides:
getBaselineResizeBehavior in class ComponentUI
Parameters:
c - JComponent to return baseline resize behavior for
Returns:
an enum indicating how the baseline changes as the component size changes
Throws:
NullPointerException - if c is null
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Return the minimum size of the table. The minimum height is the row height times the number of rows. The minimum width is the sum of the minimum widths of each column.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Return the preferred size of the table. The preferred height is the row height times the number of rows. The preferred width is the sum of the preferred widths of each column.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Return the maximum size of the table. The maximum height is the row heighttimes the number of rows. The maximum width is the sum of the maximum widths of each column.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

paint

public void paint(Graphics g,
                  JComponent c)
Paint a representation of the table instance that was set in installUI().

Overrides:
paint in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTableUI.FocusHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTableUI.FocusHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicTableUI.FocusHandler
All Implemented Interfaces:
FocusListener, EventListener
Enclosing class:
BasicTableUI
public class BasicTableUI.FocusHandler
extends Object
implements FocusListener

This inner class is marked "public" due to a compiler bug. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicTableUI.

Constructor Summary
BasicTableUI.FocusHandler()
Method Summary
void | focusGained(FocusEvent e) Invoked when a component gains the keyboard focus.
void | focusLost(FocusEvent e) Invoked when a component loses the keyboard focus.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTableUI.FocusHandler

public BasicTableUI.FocusHandler()
Method Detail

focusGained

public void focusGained(FocusEvent e)
Description copied from interface: FocusListener
Invoked when a component gains the keyboard focus.

Specified by:
focusGained in interface FocusListener

focusLost

public void focusLost(FocusEvent e)
Description copied from interface: FocusListener
Invoked when a component loses the keyboard focus.

Specified by:
focusLost in interface FocusListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTableUI.KeyHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTableUI.KeyHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicTableUI.KeyHandler
All Implemented Interfaces:
KeyListener, EventListener
Enclosing class:
BasicTableUI
public class BasicTableUI.KeyHandler
extends Object
implements KeyListener

This inner class is marked "public" due to a compiler bug. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicTableUI.

As of Java 2 platform v1.3 this class is no longer used. Instead JTable overrides processKeyBinding to dispatch the event to the current TableCellEditor.

Constructor Summary
BasicTableUI.KeyHandler()
Method Summary
void | keyPressed(KeyEvent e) Invoked when a key has been pressed.
void | keyReleased(KeyEvent e) Invoked when a key has been released.
void | keyTyped(KeyEvent e) Invoked when a key has been typed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTableUI.KeyHandler

public BasicTableUI.KeyHandler()
Method Detail

keyPressed

public void keyPressed(KeyEvent e)
Description copied from interface: KeyListener
Invoked when a key has been pressed. See the class description for KeyEvent for a definition of a key pressed event.

Specified by:
keyPressed in interface KeyListener

keyReleased

public void keyReleased(KeyEvent e)
Description copied from interface: KeyListener
Invoked when a key has been released. See the class description for KeyEvent for a definition of a key released event.

Specified by:
keyReleased in interface KeyListener

keyTyped

public void keyTyped(KeyEvent e)
Description copied from interface: KeyListener
Invoked when a key has been typed. See the class description for KeyEvent for a definition of a key typed event.

Specified by:
keyTyped in interface KeyListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTableUI.MouseInputHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTableUI.MouseInputHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicTableUI.MouseInputHandler
All Implemented Interfaces:
MouseListener, MouseMotionListener, EventListener, MouseInputListener
Enclosing class:
BasicTableUI
public class BasicTableUI.MouseInputHandler
extends Object
implements MouseInputListener

This inner class is marked "public" due to a compiler bug. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicTableUI.

Constructor Summary
BasicTableUI.MouseInputHandler()
Method Summary
void | mouseClicked(MouseEvent e) Invoked when the mouse button has been clicked (pressed and released) on a component.
void | mouseDragged(MouseEvent e) Invoked when a mouse button is pressed on a component and then dragged.
void | mouseEntered(MouseEvent e) Invoked when the mouse enters a component.
void | mouseExited(MouseEvent e) Invoked when the mouse exits a component.
void | mouseMoved(MouseEvent e) Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.
void | mousePressed(MouseEvent e) Invoked when a mouse button has been pressed on a component.
void | mouseReleased(MouseEvent e) Invoked when a mouse button has been released on a component.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTableUI.MouseInputHandler

public BasicTableUI.MouseInputHandler()
Method Detail

mouseClicked

public void mouseClicked(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse button has been clicked (pressed and released) on a component.

Specified by:
mouseClicked in interface MouseListener

mousePressed

public void mousePressed(MouseEvent e)
Description copied from interface: MouseListener
Invoked when a mouse button has been pressed on a component.

Specified by:
mousePressed in interface MouseListener

mouseReleased

public void mouseReleased(MouseEvent e)
Description copied from interface: MouseListener
Invoked when a mouse button has been released on a component.

Specified by:
mouseReleased in interface MouseListener

mouseEntered

public void mouseEntered(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse enters a component.

Specified by:
mouseEntered in interface MouseListener

mouseExited

public void mouseExited(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse exits a component.

Specified by:
mouseExited in interface MouseListener

mouseMoved

public void mouseMoved(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.

Specified by:
mouseMoved in interface MouseMotionListener

mouseDragged

public void mouseDragged(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when a mouse button is pressed on a component and then dragged. MOUSE_DRAGGED events will continue to be delivered to the component where the drag originated until the mouse button is released (regardless of whether the mouse position is within the bounds of the component).

Due to platform-dependent Drag&Drop implementations, MOUSE_DRAGGED events may not be delivered during a native Drag&Drop operation.

Specified by:
mouseDragged in interface MouseMotionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTextAreaUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTextAreaUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TextUI
            extended by  javax.swing.plaf.basic.BasicTextUI
                extended by  javax.swing.plaf.basic.BasicTextAreaUI
All Implemented Interfaces:
ViewFactory
public class BasicTextAreaUI
extends BasicTextUI

Provides the look and feel for a plain text editor. In this implementation the default UI is extended to act as a simple view factory.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicTextUI
BasicTextUI.BasicCaret, BasicTextUI.BasicHighlighter
Constructor Summary
BasicTextAreaUI()
Constructs a new BasicTextAreaUI object.
Method Summary
View | create(Element elem) Creates the view for an element.
static ComponentUI | createUI(JComponent ta) Creates a UI for a JTextArea.
int | getBaseline(JComponent c, int width, int height) Returns the baseline.
Component.BaselineResizeBehavior | getBaselineResizeBehavior(JComponent c) Returns an enum indicating how the baseline of the component changes as the size changes.
Dimension | getMinimumSize(JComponent c) The method is overridden to take into account caret width.
Dimension | getPreferredSize(JComponent c) The method is overridden to take into account caret width.
protected String | getPropertyPrefix() Fetches the name used as a key to look up properties through the UIManager.
protected void | installDefaults() Initializes component properties, e.g.
protected void | propertyChange(PropertyChangeEvent evt) This method gets called when a bound property is changed on the associated JTextComponent.
Methods inherited from class javax.swing.plaf.basic.BasicTextUI
create, createCaret, createHighlighter, createKeymap, damageRange, damageRange, getComponent, getEditorKit, getKeymapName, getMaximumSize, getNextVisualPositionFrom, getRootView, getToolTipText, getVisibleEditorRect, installKeyboardActions, installListeners, installUI, modelChanged, modelToView, modelToView, paint, paintBackground, paintSafely, setView, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, uninstallUI, update, viewToModel, viewToModel
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTextAreaUI

public BasicTextAreaUI()
Constructs a new BasicTextAreaUI object.

Method Detail

createUI

public static ComponentUI createUI(JComponent ta)
Creates a UI for a JTextArea.

Parameters:
ta - a text area
Returns:
the UI

getPropertyPrefix

protected String getPropertyPrefix()
Fetches the name used as a key to look up properties through the UIManager. This is used as a prefix to all the standard text properties.

Specified by:
getPropertyPrefix in class BasicTextUI
Returns:
the name ("TextArea")

installDefaults

protected void installDefaults()
Description copied from class: BasicTextUI
Initializes component properties, e.g. font, foreground, background, caret color, selection color, selected text color, disabled text color, and border color. The font, foreground, and background properties are only set if their current value is either null or a UIResource, other properties are set if the current value is null.

Overrides:
installDefaults in class BasicTextUI
See Also:
BasicTextUI.uninstallDefaults(), BasicTextUI.installUI(javax.swing.JComponent)

propertyChange

protected void propertyChange(PropertyChangeEvent evt)
This method gets called when a bound property is changed on the associated JTextComponent. This is a hook which UI implementations may change to reflect how the UI displays bound properties of JTextComponent subclasses. This is implemented to rebuild the View when the WrapLine or the WrapStyleWord property changes.

Overrides:
propertyChange in class BasicTextUI
Parameters:
evt - the property change event

getPreferredSize

public Dimension getPreferredSize(JComponent c)
The method is overridden to take into account caret width.

Overrides:
getPreferredSize in class BasicTextUI
Parameters:
c - the editor component
Returns:
the preferred size
Throws:
IllegalArgumentException - if invalid value is passed
Since:
1.5
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent c)
The method is overridden to take into account caret width.

Overrides:
getMinimumSize in class BasicTextUI
Parameters:
c - the editor component
Returns:
the minimum size
Throws:
IllegalArgumentException - if invalid value is passed
Since:
1.5
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

create

public View create(Element elem)
Creates the view for an element. Returns a WrappedPlainView or PlainView.

Specified by:
create in interface ViewFactory
Overrides:
create in class BasicTextUI
Parameters:
elem - the element
Returns:
the view
See Also:
View

getBaseline

public int getBaseline(JComponent c,
                       int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class ComponentUI
Parameters:
c - JComponent baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
NullPointerException - if c is null
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.

Overrides:
getBaselineResizeBehavior in class ComponentUI
Parameters:
c - JComponent to return baseline resize behavior for
Returns:
an enum indicating how the baseline changes as the component size changes
Throws:
NullPointerException - if c is null
Since:
1.6
See Also:
JComponent.getBaseline(int, int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTextFieldUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTextFieldUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TextUI
            extended by  javax.swing.plaf.basic.BasicTextUI
                extended by  javax.swing.plaf.basic.BasicTextFieldUI
All Implemented Interfaces:
ViewFactory
Direct Known Subclasses:
BasicFormattedTextFieldUI, BasicPasswordFieldUI, MetalTextFieldUI
public class BasicTextFieldUI
extends BasicTextUI

Basis of a look and feel for a JTextField.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicTextUI
BasicTextUI.BasicCaret, BasicTextUI.BasicHighlighter
Constructor Summary
BasicTextFieldUI()
Creates a new BasicTextFieldUI.
Method Summary
View | create(Element elem) Creates a view (FieldView) based on an element.
static ComponentUI | createUI(JComponent c) Creates a UI for a JTextField.
int | getBaseline(JComponent c, int width, int height) Returns the baseline.
Component.BaselineResizeBehavior | getBaselineResizeBehavior(JComponent c) Returns an enum indicating how the baseline of the component changes as the size changes.
protected String | getPropertyPrefix() Fetches the name used as a key to lookup properties through the UIManager.
Methods inherited from class javax.swing.plaf.basic.BasicTextUI
create, createCaret, createHighlighter, createKeymap, damageRange, damageRange, getComponent, getEditorKit, getKeymapName, getMaximumSize, getMinimumSize, getNextVisualPositionFrom, getPreferredSize, getRootView, getToolTipText, getVisibleEditorRect, installDefaults, installKeyboardActions, installListeners, installUI, modelChanged, modelToView, modelToView, paint, paintBackground, paintSafely, propertyChange, setView, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, uninstallUI, update, viewToModel, viewToModel
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTextFieldUI

public BasicTextFieldUI()
Creates a new BasicTextFieldUI.

Method Detail

createUI

public static ComponentUI createUI(JComponent c)
Creates a UI for a JTextField.

Parameters:
c - the text field
Returns:
the UI

getPropertyPrefix

protected String getPropertyPrefix()
Fetches the name used as a key to lookup properties through the UIManager. This is used as a prefix to all the standard text properties.

Specified by:
getPropertyPrefix in class BasicTextUI
Returns:
the name ("TextField")

create

public View create(Element elem)
Creates a view (FieldView) based on an element.

Specified by:
create in interface ViewFactory
Overrides:
create in class BasicTextUI
Parameters:
elem - the element
Returns:
the view
See Also:
View

getBaseline

public int getBaseline(JComponent c,
                       int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class ComponentUI
Parameters:
c - JComponent baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
NullPointerException - if c is null
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.

Overrides:
getBaselineResizeBehavior in class ComponentUI
Parameters:
c - JComponent to return baseline resize behavior for
Returns:
an enum indicating how the baseline changes as the component size changes
Throws:
NullPointerException - if c is null
Since:
1.6
See Also:
JComponent.getBaseline(int, int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTextPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTextPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TextUI
            extended by  javax.swing.plaf.basic.BasicTextUI
                extended by  javax.swing.plaf.basic.BasicEditorPaneUI
                    extended by  javax.swing.plaf.basic.BasicTextPaneUI
All Implemented Interfaces:
ViewFactory
public class BasicTextPaneUI
extends BasicEditorPaneUI

Provides the look and feel for a styled text editor.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicTextUI
BasicTextUI.BasicCaret, BasicTextUI.BasicHighlighter
Constructor Summary
BasicTextPaneUI()
Creates a new BasicTextPaneUI.
Method Summary
static ComponentUI | createUI(JComponent c) Creates a UI for the JTextPane.
protected String | getPropertyPrefix() Fetches the name used as a key to lookup properties through the UIManager.
void | installUI(JComponent c) Installs the UI for a component.
protected void | propertyChange(PropertyChangeEvent evt) This method gets called when a bound property is changed on the associated JTextComponent.
Methods inherited from class javax.swing.plaf.basic.BasicEditorPaneUI
getEditorKit, uninstallUI
Methods inherited from class javax.swing.plaf.basic.BasicTextUI
create, create, createCaret, createHighlighter, createKeymap, damageRange, damageRange, getComponent, getKeymapName, getMaximumSize, getMinimumSize, getNextVisualPositionFrom, getPreferredSize, getRootView, getToolTipText, getVisibleEditorRect, installDefaults, installKeyboardActions, installListeners, modelChanged, modelToView, modelToView, paint, paintBackground, paintSafely, setView, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, update, viewToModel, viewToModel
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTextPaneUI

public BasicTextPaneUI()
Creates a new BasicTextPaneUI.

Method Detail

createUI

public static ComponentUI createUI(JComponent c)
Creates a UI for the JTextPane.

Parameters:
c - the JTextPane object
Returns:
the UI

getPropertyPrefix

protected String getPropertyPrefix()
Fetches the name used as a key to lookup properties through the UIManager. This is used as a prefix to all the standard text properties.

Overrides:
getPropertyPrefix in class BasicEditorPaneUI
Returns:
the name ("TextPane")

installUI

public void installUI(JComponent c)
Description copied from class: BasicEditorPaneUI
Installs the UI for a component. This does the following things.
  1. Set the associated component to opaque (can be changed easily by a subclass or on JTextComponent directly), which is the most common case. This will cause the component's background color to be painted.
  2. Install the default caret and highlighter into the associated component.
  3. Attach to the editor and model. If there is no model, a default one is created.
  4. create the view factory and the view hierarchy used to represent the model.

Overrides:
installUI in class BasicEditorPaneUI
Parameters:
c - the editor component
See Also:
ComponentUI.installUI(javax.swing.JComponent)

propertyChange

protected void propertyChange(PropertyChangeEvent evt)
This method gets called when a bound property is changed on the associated JTextComponent. This is a hook which UI implementations may change to reflect how the UI displays bound properties of JTextComponent subclasses. If the font, foreground or document has changed, the the appropriate property is set in the default style of the document.

Overrides:
propertyChange in class BasicEditorPaneUI
Parameters:
evt - the property change event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTextUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTextUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TextUI
            extended by  javax.swing.plaf.basic.BasicTextUI
All Implemented Interfaces:
ViewFactory
Direct Known Subclasses:
BasicEditorPaneUI, BasicTextAreaUI, BasicTextFieldUI, DefaultTextUI
public abstract class BasicTextUI
extends TextUI
implements ViewFactory

Basis of a text components look-and-feel. This provides the basic editor view and controller services that may be useful when creating a look-and-feel for an extension of JTextComponent.

Most state is held in the associated JTextComponent as bound properties, and the UI installs default values for the various properties. This default will install something for all of the properties. Typically, a LAF implementation will do more however. At a minimum, a LAF would generally install key bindings.

This class also provides some concurrency support if the Document associated with the JTextComponent is a subclass of AbstractDocument. Access to the View (or View hierarchy) is serialized between any thread mutating the model and the Swing event thread (which is expected to render, do model/view coordinate translation, etc). Any access to the root view should first acquire a read-lock on the AbstractDocument and release that lock in a finally block.

An important method to define is the getPropertyPrefix() method which is used as the basis of the keys used to fetch defaults from the UIManager. The string should reflect the type of TextUI (eg. TextField, TextArea, etc) without the particular LAF part of the name (eg Metal, Motif, etc).

To build a view of the model, one of the following strategies can be employed.

  1. One strategy is to simply redefine the ViewFactory interface in the UI. By default, this UI itself acts as the factory for View implementations. This is useful for simple factories. To do this reimplement the create(javax.swing.text.Element) method.
  2. A common strategy for creating more complex types of documents is to have the EditorKit implementation return a factory. Since the EditorKit ties all of the pieces necessary to maintain a type of document, the factory is typically an important part of that and should be produced by the EditorKit implementation.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
static class | BasicTextUI.BasicCaret
static class | BasicTextUI.BasicHighlighter
Constructor Summary
BasicTextUI()
Creates a new UI.
Method Summary
View | create(Element elem) Creates a view for an element.
View | create(Element elem, int p0, int p1) Creates a view for an element.
protected Caret | createCaret() Creates the object to use for a caret.
protected Highlighter | createHighlighter() Creates the object to use for adding highlights.
protected Keymap | createKeymap() Creates the keymap to use for the text component, and installs any necessary bindings into it.
void | damageRange(JTextComponent tc, int p0, int p1) Causes the portion of the view responsible for the given part of the model to be repainted.
void | damageRange(JTextComponent t, int p0, int p1, Position.Bias p0Bias, Position.Bias p1Bias) Causes the portion of the view responsible for the given part of the model to be repainted.
protected JTextComponent | getComponent() Fetches the text component associated with this UI implementation.
EditorKit | getEditorKit(JTextComponent tc) Fetches the EditorKit for the UI.
protected String | getKeymapName() Fetches the name of the keymap that will be installed/used by default for this UI.
Dimension | getMaximumSize(JComponent c) Gets the maximum size for the editor component.
Dimension | getMinimumSize(JComponent c) Gets the minimum size for the editor component.
int | getNextVisualPositionFrom(JTextComponent t, int pos, Position.Bias b, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
Dimension | getPreferredSize(JComponent c) Gets the preferred size for the editor component.
protected abstract String | getPropertyPrefix() Gets the name used as a key to look up properties through the UIManager.
View | getRootView(JTextComponent tc) Fetches a View with the allocation of the associated text component (i.e.
String | getToolTipText(JTextComponent t, Point pt) Returns the string to be used as the tooltip at the passed in location.
protected Rectangle | getVisibleEditorRect() Gets the allocation to give the root View.
protected void | installDefaults() Initializes component properties, e.g.
protected void | installKeyboardActions()
protected void | installListeners() Installs listeners for the UI.
void | installUI(JComponent c) Installs the UI for a component.
protected void | modelChanged() Flags model changes.
Rectangle | modelToView(JTextComponent tc, int pos) Converts the given location in the model to a place in the view coordinate system.
Rectangle | modelToView(JTextComponent tc, int pos, Position.Bias bias) Converts the given location in the model to a place in the view coordinate system.
void | paint(Graphics g, JComponent c) Paints the interface.
protected void | paintBackground(Graphics g) Paints a background for the view.
protected void | paintSafely(Graphics g) Paints the interface safely with a guarantee that the model won't change from the view of this thread.
protected void | propertyChange(PropertyChangeEvent evt) This method gets called when a bound property is changed on the associated JTextComponent.
protected void | setView(View v) Sets the current root of the view hierarchy and calls invalidate().
protected void | uninstallDefaults() Sets the component properties that haven't been explicitly overridden to null.
protected void | uninstallKeyboardActions()
protected void | uninstallListeners() Uninstalls listeners for the UI.
void | uninstallUI(JComponent c) Deinstalls the UI for a component.
void | update(Graphics g, JComponent c) Superclass paints background in an uncontrollable way (i.e.
int | viewToModel(JTextComponent tc, Point pt) Converts the given place in the view coordinate system to the nearest representative location in the model.
int | viewToModel(JTextComponent tc, Point pt, Position.Bias[] biasReturn) Converts the given place in the view coordinate system to the nearest representative location in the model.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTextUI

public BasicTextUI()
Creates a new UI.

Method Detail

createCaret

protected Caret createCaret()
Creates the object to use for a caret. By default an instance of BasicCaret is created. This method can be redefined to provide something else that implements the InputPosition interface or a subclass of JCaret.

Returns:
the caret object

createHighlighter

protected Highlighter createHighlighter()
Creates the object to use for adding highlights. By default an instance of BasicHighlighter is created. This method can be redefined to provide something else that implements the Highlighter interface or a subclass of DefaultHighlighter.

Returns:
the highlighter

getKeymapName

protected String getKeymapName()
Fetches the name of the keymap that will be installed/used by default for this UI. This is implemented to create a name based upon the classname. The name is the the name of the class with the package prefix removed.

Returns:
the name

createKeymap

protected Keymap createKeymap()
Creates the keymap to use for the text component, and installs any necessary bindings into it. By default, the keymap is shared between all instances of this type of TextUI. The keymap has the name defined by the getKeymapName method. If the keymap is not found, then DEFAULT_KEYMAP from JTextComponent is used.

The set of bindings used to create the keymap is fetched from the UIManager using a key formed by combining the getPropertyPrefix() method and the string .keyBindings. The type is expected to be JTextComponent.KeyBinding[].

Returns:
the keymap
See Also:
getKeymapName(), JTextComponent

propertyChange

protected void propertyChange(PropertyChangeEvent evt)
This method gets called when a bound property is changed on the associated JTextComponent. This is a hook which UI implementations may change to reflect how the UI displays bound properties of JTextComponent subclasses. This is implemented to do nothing (i.e. the response to properties in JTextComponent itself are handled prior to calling this method). This implementation updates the background of the text component if the editable and/or enabled state changes.

Parameters:
evt - the property change event

getPropertyPrefix

protected abstract String getPropertyPrefix()
Gets the name used as a key to look up properties through the UIManager. This is used as a prefix to all the standard text properties.

Returns:
the name

installDefaults

protected void installDefaults()
Initializes component properties, e.g. font, foreground, background, caret color, selection color, selected text color, disabled text color, and border color. The font, foreground, and background properties are only set if their current value is either null or a UIResource, other properties are set if the current value is null.

See Also:
uninstallDefaults(), installUI(javax.swing.JComponent)

uninstallDefaults

protected void uninstallDefaults()
Sets the component properties that haven't been explicitly overridden to null. A property is considered overridden if its current value is not a UIResource.

See Also:
installDefaults(), uninstallUI(javax.swing.JComponent)

installListeners

protected void installListeners()
Installs listeners for the UI.

uninstallListeners

protected void uninstallListeners()
Uninstalls listeners for the UI.

installKeyboardActions

protected void installKeyboardActions()

uninstallKeyboardActions

protected void uninstallKeyboardActions()

paintBackground

protected void paintBackground(Graphics g)
Paints a background for the view. This will only be called if isOpaque() on the associated component is true. The default is to paint the background color of the component.

Parameters:
g - the graphics context

getComponent

protected final JTextComponent getComponent()
Fetches the text component associated with this UI implementation. This will be null until the ui has been installed.

Returns:
the editor component

modelChanged

protected void modelChanged()
Flags model changes. This is called whenever the model has changed. It is implemented to rebuild the view hierarchy to represent the default root element of the associated model.

setView

protected final void setView(View v)
Sets the current root of the view hierarchy and calls invalidate(). If there were any child components, they will be removed (i.e. there are assumed to have come from components embedded in views).

Parameters:
v - the root view

paintSafely

protected void paintSafely(Graphics g)
Paints the interface safely with a guarantee that the model won't change from the view of this thread. This does the following things, rendering from back to front.
  1. If the component is marked as opaque, the background is painted in the current background color of the component.
  2. The highlights (if any) are painted.
  3. The view hierarchy is painted.
  4. The caret is painted.

Parameters:
g - the graphics context

installUI

public void installUI(JComponent c)
Installs the UI for a component. This does the following things.
  1. Set the associated component to opaque (can be changed easily by a subclass or on JTextComponent directly), which is the most common case. This will cause the component's background color to be painted.
  2. Install the default caret and highlighter into the associated component.
  3. Attach to the editor and model. If there is no model, a default one is created.
  4. create the view factory and the view hierarchy used to represent the model.

Overrides:
installUI in class ComponentUI
Parameters:
c - the editor component
See Also:
ComponentUI.installUI(javax.swing.JComponent)

uninstallUI

public void uninstallUI(JComponent c)
Deinstalls the UI for a component. This removes the listeners, uninstalls the highlighter, removes views, and nulls out the keymap.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the editor component
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent)

update

public void update(Graphics g,
                   JComponent c)
Superclass paints background in an uncontrollable way (i.e. one might want an image tiled into the background). To prevent this from happening twice, this method is reimplemented to simply paint.

NOTE: Superclass is also not thread-safe in it's rendering of the background, although that's not an issue with the default rendering.

Overrides:
update in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

paint

public final void paint(Graphics g,
                        JComponent c)
Paints the interface. This is routed to the paintSafely method under the guarantee that the model won't change from the view of this thread while it's rendering (if the associated model is derived from AbstractDocument). This enables the model to potentially be updated asynchronously.

Overrides:
paint in class ComponentUI
Parameters:
g - the graphics context
c - the editor component
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Gets the preferred size for the editor component. If the component has been given a size prior to receiving this request, it will set the size of the view hierarchy to reflect the size of the component before requesting the preferred size of the view hierarchy. This allows formatted views to format to the current component size before answering the request. Other views don't care about currently formatted size and give the same answer either way.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - the editor component
Returns:
the size
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Gets the minimum size for the editor component.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
c - the editor component
Returns:
the size
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Gets the maximum size for the editor component.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - the editor component
Returns:
the size
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getVisibleEditorRect

protected Rectangle getVisibleEditorRect()
Gets the allocation to give the root View. Due to an unfortunate set of historical events this method is inappropriately named. The Rectangle returned has nothing to do with visibility. The component must have a non-zero positive size for this translation to be computed.

Returns:
the bounding box for the root view

modelToView

public Rectangle modelToView(JTextComponent tc,
                             int pos)
                      throws BadLocationException
Converts the given location in the model to a place in the view coordinate system. The component must have a non-zero positive size for this translation to be computed.

Specified by:
modelToView in class TextUI
Parameters:
tc - the text component for which this UI is installed
pos - the local location in the model to translate >= 0
Returns:
the coordinates as a rectangle, null if the model is not painted
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
See Also:
TextUI.modelToView(javax.swing.text.JTextComponent, int)

modelToView

public Rectangle modelToView(JTextComponent tc,
                             int pos,
                             Position.Bias bias)
                      throws BadLocationException
Converts the given location in the model to a place in the view coordinate system. The component must have a non-zero positive size for this translation to be computed.

Specified by:
modelToView in class TextUI
Parameters:
tc - the text component for which this UI is installed
pos - the local location in the model to translate >= 0
Returns:
the coordinates as a rectangle, null if the model is not painted
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
See Also:
TextUI.modelToView(javax.swing.text.JTextComponent, int)

viewToModel

public int viewToModel(JTextComponent tc,
                       Point pt)
Converts the given place in the view coordinate system to the nearest representative location in the model. The component must have a non-zero positive size for this translation to be computed.

Specified by:
viewToModel in class TextUI
Parameters:
tc - the text component for which this UI is installed
pt - the location in the view to translate. This should be in the same coordinate system as the mouse events.
Returns:
the offset from the start of the document >= 0, -1 if not painted
See Also:
TextUI.viewToModel(javax.swing.text.JTextComponent, java.awt.Point)

viewToModel

public int viewToModel(JTextComponent tc,
                       Point pt,
                       Position.Bias[] biasReturn)
Converts the given place in the view coordinate system to the nearest representative location in the model. The component must have a non-zero positive size for this translation to be computed.

Specified by:
viewToModel in class TextUI
Parameters:
tc - the text component for which this UI is installed
pt - the location in the view to translate. This should be in the same coordinate system as the mouse events.
biasReturn - filled in by this method to indicate whether the point given is closer to the previous or the next character in the model
Returns:
the offset from the start of the document >= 0, -1 if the component doesn't yet have a positive size.
See Also:
TextUI.viewToModel(javax.swing.text.JTextComponent, java.awt.Point)

getNextVisualPositionFrom

public int getNextVisualPositionFrom(JTextComponent t,
                                     int pos,
                                     Position.Bias b,
                                     int direction,
                                     Position.Bias[] biasRet)
                              throws BadLocationException
Provides a way to determine the next visually represented model location that one might place a caret. Some views may not be visible, they might not be in the same order found in the model, or they just might not allow access to some of the locations in the model.

Specified by:
getNextVisualPositionFrom in class TextUI
Parameters:
t - the text component for which this UI is installed
pos - the position to convert >= 0
b - the bias for the position
direction - the direction from the current position that can be thought of as the arrow keys typically found on a keyboard. This may be SwingConstants.WEST, SwingConstants.EAST, SwingConstants.NORTH, or SwingConstants.SOUTH
biasRet - an array to contain the bias for the returned position
Returns:
the location within the model that best represents the next location visual position
Throws:
BadLocationException

damageRange

public void damageRange(JTextComponent tc,
                        int p0,
                        int p1)
Causes the portion of the view responsible for the given part of the model to be repainted. Does nothing if the view is not currently painted.

Specified by:
damageRange in class TextUI
Parameters:
tc - the text component for which this UI is installed
p0 - the beginning of the range >= 0
p1 - the end of the range >= p0
See Also:
TextUI.damageRange(javax.swing.text.JTextComponent, int, int)

damageRange

public void damageRange(JTextComponent t,
                        int p0,
                        int p1,
                        Position.Bias p0Bias,
                        Position.Bias p1Bias)
Causes the portion of the view responsible for the given part of the model to be repainted.

Specified by:
damageRange in class TextUI
Parameters:
p0 - the beginning of the range >= 0
p1 - the end of the range >= p0

getEditorKit

public EditorKit getEditorKit(JTextComponent tc)
Fetches the EditorKit for the UI.

Specified by:
getEditorKit in class TextUI
Parameters:
tc - the text component for which this UI is installed
Returns:
the editor capabilities
See Also:
TextUI.getEditorKit(javax.swing.text.JTextComponent)

getRootView

public View getRootView(JTextComponent tc)
Fetches a View with the allocation of the associated text component (i.e. the root of the hierarchy) that can be traversed to determine how the model is being represented spatially.

NOTE:The View hierarchy can be traversed from the root view, and other things can be done as well. Things done in this way cannot be protected like simple method calls through the TextUI. Therefore, proper operation in the presence of concurrency must be arranged by any logic that calls this method!

Specified by:
getRootView in class TextUI
Parameters:
tc - the text component for which this UI is installed
Returns:
the view
See Also:
TextUI.getRootView(javax.swing.text.JTextComponent)

getToolTipText

public String getToolTipText(JTextComponent t,
                             Point pt)
Returns the string to be used as the tooltip at the passed in location. This forwards the method onto the root View.

Overrides:
getToolTipText in class TextUI
Since:
1.4
See Also:
JTextComponent.getToolTipText(java.awt.event.MouseEvent), View.getToolTipText(float, float, java.awt.Shape)

create

public View create(Element elem)
Creates a view for an element. If a subclass wishes to directly implement the factory producing the view(s), it should reimplement this method. By default it simply returns null indicating it is unable to represent the element.

Specified by:
create in interface ViewFactory
Parameters:
elem - the element
Returns:
the view
See Also:
View

create

public View create(Element elem,
                   int p0,
                   int p1)
Creates a view for an element. If a subclass wishes to directly implement the factory producing the view(s), it should reimplement this method. By default it simply returns null indicating it is unable to represent the part of the element.

Parameters:
elem - the element
p0 - the starting offset >= 0
p1 - the ending offset >= p0
Returns:
the view
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTextUI.BasicCaret

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTextUI.BasicCaret

java.lang.Object
    extended by  java.awt.geom.RectangularShape
        extended by  java.awt.geom.Rectangle2D
            extended by  java.awt.Rectangle
                extended by  javax.swing.text.DefaultCaret
                    extended by  javax.swing.plaf.basic.BasicTextUI.BasicCaret
All Implemented Interfaces:
FocusListener, MouseListener, MouseMotionListener, Shape, Serializable, Cloneable, EventListener, UIResource, Caret
Enclosing class:
BasicTextUI
public static class BasicTextUI.BasicCaret
extends DefaultCaret
implements UIResource

Nested Class Summary
Nested classes/interfaces inherited from class java.awt.geom.Rectangle2D
Rectangle2D.Double, Rectangle2D.Float
Field Summary
Fields inherited from class javax.swing.text.DefaultCaret
ALWAYS_UPDATE, changeEvent, listenerList, NEVER_UPDATE, UPDATE_WHEN_ON_EDT
Fields inherited from class java.awt.Rectangle
height, width, x, y
Fields inherited from class java.awt.geom.Rectangle2D
OUT_BOTTOM, OUT_LEFT, OUT_RIGHT, OUT_TOP
Constructor Summary
BasicTextUI.BasicCaret()
Method Summary
Methods inherited from class javax.swing.text.DefaultCaret
addChangeListener, adjustVisibility, damage, deinstall, equals, fireStateChanged, focusGained, focusLost, getBlinkRate, getChangeListeners, getComponent, getDot, getDotBias, getListeners, getMagicCaretPosition, getMark, getMarkBias, getSelectionPainter, getUpdatePolicy, install, isActive, isSelectionVisible, isVisible, mouseClicked, mouseDragged, mouseEntered, mouseExited, mouseMoved, mousePressed, mouseReleased, moveCaret, moveDot, moveDot, paint, positionCaret, removeChangeListener, repaint, setBlinkRate, setDot, setDot, setMagicCaretPosition, setSelectionVisible, setUpdatePolicy, setVisible, toString
Methods inherited from class java.awt.Rectangle
add, add, add, contains, contains, contains, contains, createIntersection, createUnion, getBounds, getBounds2D, getHeight, getLocation, getSize, getWidth, getX, getY, grow, inside, intersection, intersects, isEmpty, move, outcode, reshape, resize, setBounds, setBounds, setLocation, setLocation, setRect, setSize, setSize, translate, union
Methods inherited from class java.awt.geom.Rectangle2D
add, add, add, contains, contains, getPathIterator, getPathIterator, hashCode, intersect, intersects, intersectsLine, intersectsLine, outcode, setFrame, setRect, union
Methods inherited from class java.awt.geom.RectangularShape
clone, contains, contains, getCenterX, getCenterY, getFrame, getMaxX, getMaxY, getMinX, getMinY, intersects, setFrame, setFrame, setFrameFromCenter, setFrameFromCenter, setFrameFromDiagonal, setFrameFromDiagonal
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.awt.Shape
contains, contains, contains, contains, getPathIterator, getPathIterator, intersects, intersects

Constructor Detail

BasicTextUI.BasicCaret

public BasicTextUI.BasicCaret()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTextUI.BasicHighlighter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTextUI.BasicHighlighter

java.lang.Object
    extended by  javax.swing.text.LayeredHighlighter
        extended by  javax.swing.text.DefaultHighlighter
            extended by  javax.swing.plaf.basic.BasicTextUI.BasicHighlighter
All Implemented Interfaces:
UIResource, Highlighter
Enclosing class:
BasicTextUI
public static class BasicTextUI.BasicHighlighter
extends DefaultHighlighter
implements UIResource

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.text.DefaultHighlighter
DefaultHighlighter.DefaultHighlightPainter
Nested classes/interfaces inherited from class javax.swing.text.LayeredHighlighter
LayeredHighlighter.LayerPainter
Nested classes/interfaces inherited from interface javax.swing.text.Highlighter
Highlighter.Highlight, Highlighter.HighlightPainter
Field Summary
Fields inherited from class javax.swing.text.DefaultHighlighter
DefaultPainter
Constructor Summary
BasicTextUI.BasicHighlighter()
Method Summary
Methods inherited from class javax.swing.text.DefaultHighlighter
addHighlight, changeHighlight, deinstall, getDrawsLayeredHighlights, getHighlights, install, paint, paintLayeredHighlights, removeAllHighlights, removeHighlight, setDrawsLayeredHighlights
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTextUI.BasicHighlighter

public BasicTextUI.BasicHighlighter()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicToggleButtonUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicToggleButtonUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ButtonUI
            extended by  javax.swing.plaf.basic.BasicButtonUI
                extended by  javax.swing.plaf.basic.BasicToggleButtonUI
Direct Known Subclasses:
BasicRadioButtonUI, MetalToggleButtonUI
public class BasicToggleButtonUI
extends BasicButtonUI

BasicToggleButton implementation

Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicButtonUI
defaultTextIconGap, defaultTextShiftOffset
Constructor Summary
BasicToggleButtonUI()
Method Summary
static ComponentUI | createUI(JComponent b)
protected String | getPropertyPrefix()
protected int | getTextShiftOffset() Overriden so that the text will not be rendered as shifted for Toggle buttons and subclasses.
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
protected void | paintIcon(Graphics g, AbstractButton b, Rectangle iconRect)
Methods inherited from class javax.swing.plaf.basic.BasicButtonUI
clearTextShiftOffset, createButtonListener, getBaseline, getBaselineResizeBehavior, getDefaultTextIconGap, getMaximumSize, getMinimumSize, getPreferredSize, installDefaults, installKeyboardActions, installListeners, installUI, paintButtonPressed, paintFocus, paintIcon, paintText, paintText, setTextShiftOffset, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicToggleButtonUI

public BasicToggleButtonUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent b)

getPropertyPrefix

protected String getPropertyPrefix()
Overrides:
getPropertyPrefix in class BasicButtonUI

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class BasicButtonUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

paintIcon

protected void paintIcon(Graphics g,
                         AbstractButton b,
                         Rectangle iconRect)

getTextShiftOffset

protected int getTextShiftOffset()
Overriden so that the text will not be rendered as shifted for Toggle buttons and subclasses.

Overrides:
getTextShiftOffset in class BasicButtonUI
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicToolBarSeparatorUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicToolBarSeparatorUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SeparatorUI
            extended by  javax.swing.plaf.basic.BasicSeparatorUI
                extended by  javax.swing.plaf.basic.BasicToolBarSeparatorUI

public class BasicToolBarSeparatorUI
extends BasicSeparatorUI

A Basic L&F implementation of ToolBarSeparatorUI. This implementation is a "combined" view/controller.

Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicSeparatorUI
highlight, shadow
Constructor Summary
BasicToolBarSeparatorUI()
Method Summary
static ComponentUI | createUI(JComponent c)
Dimension | getPreferredSize(JComponent c) Returns the specified component's preferred size appropriate for the look and feel.
protected void | installDefaults(JSeparator s)
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
Methods inherited from class javax.swing.plaf.basic.BasicSeparatorUI
getMaximumSize, getMinimumSize, installListeners, installUI, uninstallDefaults, uninstallListeners, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicToolBarSeparatorUI

public BasicToolBarSeparatorUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installDefaults

protected void installDefaults(JSeparator s)
Overrides:
installDefaults in class BasicSeparatorUI

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class BasicSeparatorUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Overrides:
getPreferredSize in class BasicSeparatorUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicToolBarUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicToolBarUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ToolBarUI
            extended by  javax.swing.plaf.basic.BasicToolBarUI
All Implemented Interfaces:
SwingConstants
Direct Known Subclasses:
MetalToolBarUI
public class BasicToolBarUI
extends ToolBarUI
implements SwingConstants

A Basic L&F implementation of ToolBarUI. This implementation is a "combined" view/controller.

Nested Class Summary
class | BasicToolBarUI.DockingListener This class should be treated as a "protected" inner class.
protected class | BasicToolBarUI.DragWindow
protected class | BasicToolBarUI.FrameListener
protected class | BasicToolBarUI.PropertyListener
protected class | BasicToolBarUI.ToolBarContListener
protected class | BasicToolBarUI.ToolBarFocusListener
Field Summary
protected String | constraintBeforeFloating
protected Color | dockingBorderColor
protected Color | dockingColor
protected MouseInputListener | dockingListener
protected KeyStroke | downKey Deprecated. As of Java 2 platform v1.3.
protected BasicToolBarUI.DragWindow | dragWindow
protected Color | floatingBorderColor
protected Color | floatingColor
protected int | focusedCompIndex
protected KeyStroke | leftKey Deprecated. As of Java 2 platform v1.3.
protected PropertyChangeListener | propertyListener
protected KeyStroke | rightKey Deprecated. As of Java 2 platform v1.3.
protected JToolBar | toolBar
protected ContainerListener | toolBarContListener
protected FocusListener | toolBarFocusListener
protected KeyStroke | upKey Deprecated. As of Java 2 platform v1.3.
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
BasicToolBarUI()
Method Summary
boolean | canDock(Component c, Point p)
protected MouseInputListener | createDockingListener()
protected BasicToolBarUI.DragWindow | createDragWindow(JToolBar toolbar)
protected JFrame | createFloatingFrame(JToolBar toolbar) No longer used, use BasicToolBarUI.createFloatingWindow(JToolBar)
protected RootPaneContainer | createFloatingWindow(JToolBar toolbar) Creates a window which contains the toolbar after it has been dragged out from its container
protected WindowListener | createFrameListener()
protected Border | createNonRolloverBorder() Creates the non rollover border for toolbar components.
protected PropertyChangeListener | createPropertyListener()
protected Border | createRolloverBorder() Creates a rollover border for toolbar components.
protected ContainerListener | createToolBarContListener()
protected FocusListener | createToolBarFocusListener()
static ComponentUI | createUI(JComponent c)
protected void | dragTo(Point position, Point origin)
protected void | floatAt(Point position, Point origin)
Color | getDockingColor() Gets the color displayed when over a docking area
Color | getFloatingColor() Gets the color displayed when over a floating area
protected Border | getNonRolloverBorder(AbstractButton b) Returns a non-rollover border for the button.
protected Border | getRolloverBorder(AbstractButton b) Returns a rollover border for the button.
protected void | installComponents()
protected void | installDefaults()
protected void | installKeyboardActions()
protected void | installListeners()
protected void | installNonRolloverBorders(JComponent c) Installs non-rollover borders on all the child components of the JComponent.
protected void | installNormalBorders(JComponent c) Installs normal borders on all the child components of the JComponent.
protected void | installRolloverBorders(JComponent c) Installs rollover borders on all the child components of the JComponent.
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
boolean | isFloating()
boolean | isRolloverBorders() Returns a flag to determine whether rollover button borders are enabled.
protected void | navigateFocusedComp(int direction)
protected void | paintDragWindow(Graphics g) Paints the contents of the window used for dragging.
protected void | setBorderToNonRollover(Component c) Sets the border of the component to have a non-rollover border which was created by createNonRolloverBorder.
protected void | setBorderToNormal(Component c) Sets the border of the component to have a normal border.
protected void | setBorderToRollover(Component c) Sets the border of the component to have a rollover border which was created by createRolloverBorder.
void | setDockingColor(Color c) Sets the color displayed when over a docking area
void | setFloating(boolean b, Point p)
void | setFloatingColor(Color c) Sets the color displayed when over a floating area
void | setFloatingLocation(int x, int y)
void | setOrientation(int orientation)
void | setRolloverBorders(boolean rollover) Sets the flag for enabling rollover borders on the toolbar and it will also install the apropriate border depending on the state of the flag.
protected void | uninstallComponents()
protected void | uninstallDefaults()
protected void | uninstallKeyboardActions()
protected void | uninstallListeners()
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, paint, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

toolBar

protected JToolBar toolBar

dragWindow

protected BasicToolBarUI.DragWindow dragWindow

focusedCompIndex

protected int focusedCompIndex

dockingColor

protected Color dockingColor

floatingColor

protected Color floatingColor

dockingBorderColor

protected Color dockingBorderColor

floatingBorderColor

protected Color floatingBorderColor

dockingListener

protected MouseInputListener dockingListener

propertyListener

protected PropertyChangeListener propertyListener

toolBarContListener

protected ContainerListener toolBarContListener

toolBarFocusListener

protected FocusListener toolBarFocusListener

constraintBeforeFloating

protected String constraintBeforeFloating

upKey

@Deprecated
protected KeyStroke upKey
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

downKey

@Deprecated
protected KeyStroke downKey
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

leftKey

@Deprecated
protected KeyStroke leftKey
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

rightKey

@Deprecated
protected KeyStroke rightKey
Deprecated. As of Java 2 platform v1.3.
As of Java 2 platform v1.3 this previously undocumented field is no longer used. Key bindings are now defined by the LookAndFeel, please refer to the key bindings specification for further details.

Constructor Detail

BasicToolBarUI

public BasicToolBarUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installDefaults

protected void installDefaults()

uninstallDefaults

protected void uninstallDefaults()

installComponents

protected void installComponents()

uninstallComponents

protected void uninstallComponents()

installListeners

protected void installListeners()

uninstallListeners

protected void uninstallListeners()

installKeyboardActions

protected void installKeyboardActions()

uninstallKeyboardActions

protected void uninstallKeyboardActions()

navigateFocusedComp

protected void navigateFocusedComp(int direction)

createRolloverBorder

protected Border createRolloverBorder()
Creates a rollover border for toolbar components. The rollover border will be installed if rollover borders are enabled.

Override this method to provide an alternate rollover border.

Since:
1.4

createNonRolloverBorder

protected Border createNonRolloverBorder()
Creates the non rollover border for toolbar components. This border will be installed as the border for components added to the toolbar if rollover borders are not enabled.

Override this method to provide an alternate rollover border.

Since:
1.4

createFloatingFrame

protected JFrame createFloatingFrame(JToolBar toolbar)
No longer used, use BasicToolBarUI.createFloatingWindow(JToolBar)

See Also:
createFloatingWindow(javax.swing.JToolBar)

createFloatingWindow

protected RootPaneContainer createFloatingWindow(JToolBar toolbar)
Creates a window which contains the toolbar after it has been dragged out from its container

Returns:
a RootPaneContainer object, containing the toolbar.
Since:
1.4

createDragWindow

protected BasicToolBarUI.DragWindow createDragWindow(JToolBar toolbar)

isRolloverBorders

public boolean isRolloverBorders()
Returns a flag to determine whether rollover button borders are enabled.

Returns:
true if rollover borders are enabled; false otherwise
Since:
1.4
See Also:
setRolloverBorders(boolean)

setRolloverBorders

public void setRolloverBorders(boolean rollover)
Sets the flag for enabling rollover borders on the toolbar and it will also install the apropriate border depending on the state of the flag.

Parameters:
rollover - if true, rollover borders are installed. Otherwise non-rollover borders are installed
Since:
1.4
See Also:
isRolloverBorders()

installRolloverBorders

protected void installRolloverBorders(JComponent c)
Installs rollover borders on all the child components of the JComponent.

This is a convenience method to call setBorderToRollover for each child component.

Parameters:
c - container which holds the child components (usally a JToolBar)
Since:
1.4
See Also:
setBorderToRollover(java.awt.Component)

installNonRolloverBorders

protected void installNonRolloverBorders(JComponent c)
Installs non-rollover borders on all the child components of the JComponent. A non-rollover border is the border that is installed on the child component while it is in the toolbar.

This is a convenience method to call setBorderToNonRollover for each child component.

Parameters:
c - container which holds the child components (usally a JToolBar)
Since:
1.4
See Also:
setBorderToNonRollover(java.awt.Component)

installNormalBorders

protected void installNormalBorders(JComponent c)
Installs normal borders on all the child components of the JComponent. A normal border is the original border that was installed on the child component before it was added to the toolbar.

This is a convenience method to call setBorderNormal for each child component.

Parameters:
c - container which holds the child components (usally a JToolBar)
Since:
1.4
See Also:
setBorderToNonRollover(java.awt.Component)

setBorderToRollover

protected void setBorderToRollover(Component c)
Sets the border of the component to have a rollover border which was created by createRolloverBorder.

Parameters:
c - component which will have a rollover border installed
Since:
1.4
See Also:
createRolloverBorder()

getRolloverBorder

protected Border getRolloverBorder(AbstractButton b)
Returns a rollover border for the button.

Parameters:
b - the button to calculate the rollover border for
Returns:
the rollover border
Since:
1.6
See Also:
setBorderToRollover(java.awt.Component)

setBorderToNonRollover

protected void setBorderToNonRollover(Component c)
Sets the border of the component to have a non-rollover border which was created by createNonRolloverBorder.

Parameters:
c - component which will have a non-rollover border installed
Since:
1.4
See Also:
createNonRolloverBorder()

getNonRolloverBorder

protected Border getNonRolloverBorder(AbstractButton b)
Returns a non-rollover border for the button.

Parameters:
b - the button to calculate the non-rollover border for
Returns:
the non-rollover border
Since:
1.6
See Also:
setBorderToNonRollover(java.awt.Component)

setBorderToNormal

protected void setBorderToNormal(Component c)
Sets the border of the component to have a normal border. A normal border is the original border that was installed on the child component before it was added to the toolbar.

Parameters:
c - component which will have a normal border re-installed
Since:
1.4
See Also:
createNonRolloverBorder()

setFloatingLocation

public void setFloatingLocation(int x,
                                int y)

isFloating

public boolean isFloating()

setFloating

public void setFloating(boolean b,
                        Point p)

setOrientation

public void setOrientation(int orientation)

getDockingColor

public Color getDockingColor()
Gets the color displayed when over a docking area

setDockingColor

public void setDockingColor(Color c)
Sets the color displayed when over a docking area

getFloatingColor

public Color getFloatingColor()
Gets the color displayed when over a floating area

setFloatingColor

public void setFloatingColor(Color c)
Sets the color displayed when over a floating area

canDock

public boolean canDock(Component c,
                       Point p)

dragTo

protected void dragTo(Point position,
                      Point origin)

floatAt

protected void floatAt(Point position,
                       Point origin)

createToolBarContListener

protected ContainerListener createToolBarContListener()

createToolBarFocusListener

protected FocusListener createToolBarFocusListener()

createPropertyListener

protected PropertyChangeListener createPropertyListener()

createDockingListener

protected MouseInputListener createDockingListener()

createFrameListener

protected WindowListener createFrameListener()

paintDragWindow

protected void paintDragWindow(Graphics g)
Paints the contents of the window used for dragging.

Parameters:
g - Graphics to paint to.
Throws:
NullPointerException - is g is null
Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicToolBarUI.DockingListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicToolBarUI.DockingListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicToolBarUI.DockingListener
All Implemented Interfaces:
MouseListener, MouseMotionListener, EventListener, MouseInputListener
Direct Known Subclasses:
MetalToolBarUI.MetalDockingListener
Enclosing class:
BasicToolBarUI
public class BasicToolBarUI.DockingListener
extends Object
implements MouseInputListener

This class should be treated as a "protected" inner class. Instantiate it only within subclasses of BasicToolBarUI.

Field Summary
protected boolean | isDragging
protected Point | origin
protected JToolBar | toolBar
Constructor Summary
BasicToolBarUI.DockingListener(JToolBar t)
Method Summary
void | mouseClicked(MouseEvent e) Invoked when the mouse button has been clicked (pressed and released) on a component.
void | mouseDragged(MouseEvent e) Invoked when a mouse button is pressed on a component and then dragged.
void | mouseEntered(MouseEvent e) Invoked when the mouse enters a component.
void | mouseExited(MouseEvent e) Invoked when the mouse exits a component.
void | mouseMoved(MouseEvent e) Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.
void | mousePressed(MouseEvent e) Invoked when a mouse button has been pressed on a component.
void | mouseReleased(MouseEvent e) Invoked when a mouse button has been released on a component.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

toolBar

protected JToolBar toolBar

isDragging

protected boolean isDragging

origin

protected Point origin
Constructor Detail

BasicToolBarUI.DockingListener

public BasicToolBarUI.DockingListener(JToolBar t)
Method Detail

mouseClicked

public void mouseClicked(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse button has been clicked (pressed and released) on a component.

Specified by:
mouseClicked in interface MouseListener

mousePressed

public void mousePressed(MouseEvent e)
Description copied from interface: MouseListener
Invoked when a mouse button has been pressed on a component.

Specified by:
mousePressed in interface MouseListener

mouseReleased

public void mouseReleased(MouseEvent e)
Description copied from interface: MouseListener
Invoked when a mouse button has been released on a component.

Specified by:
mouseReleased in interface MouseListener

mouseEntered

public void mouseEntered(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse enters a component.

Specified by:
mouseEntered in interface MouseListener

mouseExited

public void mouseExited(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse exits a component.

Specified by:
mouseExited in interface MouseListener

mouseDragged

public void mouseDragged(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when a mouse button is pressed on a component and then dragged. MOUSE_DRAGGED events will continue to be delivered to the component where the drag originated until the mouse button is released (regardless of whether the mouse position is within the bounds of the component).

Due to platform-dependent Drag&Drop implementations, MOUSE_DRAGGED events may not be delivered during a native Drag&Drop operation.

Specified by:
mouseDragged in interface MouseMotionListener

mouseMoved

public void mouseMoved(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.

Specified by:
mouseMoved in interface MouseMotionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicToolBarUI.DragWindow

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicToolBarUI.DragWindow

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  java.awt.Window
                extended by  javax.swing.plaf.basic.BasicToolBarUI.DragWindow
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
Enclosing class:
BasicToolBarUI
protected class BasicToolBarUI.DragWindow
extends Window

Nested Class Summary
Nested classes/interfaces inherited from class java.awt.Window
Window.AccessibleAWTWindow
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Method Summary
Color | getBorderColor()
Insets | getInsets() Determines the insets of this container, which indicate the size of the container's border.
Point | getOffset()
int | getOrientation() Returns the orientation of the toolbar window when the toolbar is floating.
void | paint(Graphics g) Paints the container.
void | setBorderColor(Color c)
void | setOffset(Point p)
void | setOrientation(int o)
Methods inherited from class java.awt.Window
addNotify, addPropertyChangeListener, addPropertyChangeListener, addWindowFocusListener, addWindowListener, addWindowStateListener, applyResourceBundle, applyResourceBundle, createBufferStrategy, createBufferStrategy, dispose, getAccessibleContext, getBufferStrategy, getFocusableWindowState, getFocusCycleRootAncestor, getFocusOwner, getFocusTraversalKeys, getGraphicsConfiguration, getIconImages, getInputContext, getListeners, getLocale, getModalExclusionType, getMostRecentFocusOwner, getOwnedWindows, getOwner, getOwnerlessWindows, getToolkit, getWarningString, getWindowFocusListeners, getWindowListeners, getWindows, getWindowStateListeners, hide, isActive, isAlwaysOnTop, isAlwaysOnTopSupported, isFocusableWindow, isFocusCycleRoot, isFocused, isLocationByPlatform, isShowing, pack, postEvent, processEvent, processWindowEvent, processWindowFocusEvent, processWindowStateEvent, removeNotify, removeWindowFocusListener, removeWindowListener, removeWindowStateListener, reshape, setAlwaysOnTop, setBounds, setBounds, setCursor, setFocusableWindowState, setFocusCycleRoot, setIconImage, setIconImages, setLocationByPlatform, setLocationRelativeTo, setMinimumSize, setModalExclusionType, setSize, setSize, setVisible, show, toBack, toFront
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalPolicy, getLayout, getMaximumSize, getMinimumSize, getMousePosition, getPreferredSize, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, paramString, preferredSize, print, printComponents, processContainerEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, setLayout, transferFocusBackward, transferFocusDownCycle, update, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resize, resize, setBackground, setComponentOrientation, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setName, setPreferredSize, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getOrientation

public int getOrientation()
Returns the orientation of the toolbar window when the toolbar is floating. The orientation is either one of JToolBar.HORIZONTAL or JToolBar.VERTICAL.

Returns:
the orientation of the toolbar window
Since:
1.6

setOrientation

public void setOrientation(int o)

getOffset

public Point getOffset()

setOffset

public void setOffset(Point p)

setBorderColor

public void setBorderColor(Color c)

getBorderColor

public Color getBorderColor()

paint

public void paint(Graphics g)
Description copied from class: Container
Paints the container. This forwards the paint to any lightweight components that are children of this container. If this method is reimplemented, super.paint(g) should be called so that lightweight components are properly rendered. If a child component is entirely clipped by the current clipping setting in g, paint() will not be forwarded to that child.

Overrides:
paint in class Container
Parameters:
g - the specified Graphics window
See Also:
Component.update(Graphics)

getInsets

public Insets getInsets()
Description copied from class: Container
Determines the insets of this container, which indicate the size of the container's border.

A Frame object, for example, has a top inset that corresponds to the height of the frame's title bar.

Overrides:
getInsets in class Container
Returns:
the insets of this container.
See Also:
Insets, LayoutManager
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicToolBarUI.FrameListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicToolBarUI.FrameListener

java.lang.Object
    extended by  java.awt.event.WindowAdapter
        extended by  javax.swing.plaf.basic.BasicToolBarUI.FrameListener
All Implemented Interfaces:
WindowFocusListener, WindowListener, WindowStateListener, EventListener
Enclosing class:
BasicToolBarUI
protected class BasicToolBarUI.FrameListener
extends WindowAdapter

Constructor Summary
protected BasicToolBarUI.FrameListener()
Method Summary
 void windowClosing(WindowEvent w)
Invoked when a window is in the process of being closed.
Methods inherited from class java.awt.event.WindowAdapter
windowActivated, windowClosed, windowDeactivated, windowDeiconified, windowGainedFocus, windowIconified, windowLostFocus, windowOpened, windowStateChanged
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicToolBarUI.FrameListener

protected BasicToolBarUI.FrameListener()
Method Detail

windowClosing

public void windowClosing(WindowEvent w)
Description copied from class: WindowAdapter
Invoked when a window is in the process of being closed. The close operation can be overridden at this point.

Specified by:
windowClosing in interface WindowListener
Overrides:
windowClosing in class WindowAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicToolBarUI.PropertyListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicToolBarUI.PropertyListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicToolBarUI.PropertyListener
All Implemented Interfaces:
PropertyChangeListener, EventListener
Direct Known Subclasses:
MetalToolBarUI.MetalRolloverListener
Enclosing class:
BasicToolBarUI
protected class BasicToolBarUI.PropertyListener
extends Object
implements PropertyChangeListener

Constructor Summary
protected BasicToolBarUI.PropertyListener()
Method Summary
 void propertyChange(PropertyChangeEvent e)
This method gets called when a bound property is changed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicToolBarUI.PropertyListener

protected BasicToolBarUI.PropertyListener()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicToolBarUI.ToolBarContListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicToolBarUI.ToolBarContListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicToolBarUI.ToolBarContListener
All Implemented Interfaces:
ContainerListener, EventListener
Direct Known Subclasses:
MetalToolBarUI.MetalContainerListener
Enclosing class:
BasicToolBarUI
protected class BasicToolBarUI.ToolBarContListener
extends Object
implements ContainerListener

Constructor Summary
protected BasicToolBarUI.ToolBarContListener()
Method Summary
void | componentAdded(ContainerEvent e) Invoked when a component has been added to the container.
void | componentRemoved(ContainerEvent e) Invoked when a component has been removed from the container.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicToolBarUI.ToolBarContListener

protected BasicToolBarUI.ToolBarContListener()
Method Detail

componentAdded

public void componentAdded(ContainerEvent e)
Description copied from interface: ContainerListener
Invoked when a component has been added to the container.

Specified by:
componentAdded in interface ContainerListener

componentRemoved

public void componentRemoved(ContainerEvent e)
Description copied from interface: ContainerListener
Invoked when a component has been removed from the container.

Specified by:
componentRemoved in interface ContainerListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicToolBarUI.ToolBarFocusListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicToolBarUI.ToolBarFocusListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicToolBarUI.ToolBarFocusListener
All Implemented Interfaces:
FocusListener, EventListener
Enclosing class:
BasicToolBarUI
protected class BasicToolBarUI.ToolBarFocusListener
extends Object
implements FocusListener

Constructor Summary
protected BasicToolBarUI.ToolBarFocusListener()
Method Summary
void | focusGained(FocusEvent e) Invoked when a component gains the keyboard focus.
void | focusLost(FocusEvent e) Invoked when a component loses the keyboard focus.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicToolBarUI.ToolBarFocusListener

protected BasicToolBarUI.ToolBarFocusListener()
Method Detail

focusGained

public void focusGained(FocusEvent e)
Description copied from interface: FocusListener
Invoked when a component gains the keyboard focus.

Specified by:
focusGained in interface FocusListener

focusLost

public void focusLost(FocusEvent e)
Description copied from interface: FocusListener
Invoked when a component loses the keyboard focus.

Specified by:
focusLost in interface FocusListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicToolTipUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicToolTipUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ToolTipUI
            extended by  javax.swing.plaf.basic.BasicToolTipUI
Direct Known Subclasses:
MetalToolTipUI
public class BasicToolTipUI
extends ToolTipUI

Standard tool tip L&F.

Constructor Summary
BasicToolTipUI()
Method Summary
static ComponentUI | createUI(JComponent c)
Dimension | getMaximumSize(JComponent c) Returns the specified component's maximum size appropriate for the look and feel.
Dimension | getMinimumSize(JComponent c) Returns the specified component's minimum size appropriate for the look and feel.
Dimension | getPreferredSize(JComponent c) Returns the specified component's preferred size appropriate for the look and feel.
protected void | installDefaults(JComponent c)
protected void | installListeners(JComponent c)
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
protected void | uninstallDefaults(JComponent c)
protected void | uninstallListeners(JComponent c)
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicToolTipUI

public BasicToolTipUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installDefaults

protected void installDefaults(JComponent c)

uninstallDefaults

protected void uninstallDefaults(JComponent c)

installListeners

protected void installListeners(JComponent c)

uninstallListeners

protected void uninstallListeners(JComponent c)

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's minimum size appropriate for the look and feel. If null is returned, the minimum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's maximum size appropriate for the look and feel. If null is returned, the maximum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TreeUI
            extended by  javax.swing.plaf.basic.BasicTreeUI
Direct Known Subclasses:
MetalTreeUI
public class BasicTreeUI
extends TreeUI

The basic L&F for a hierarchical data structure.

Nested Class Summary
class | BasicTreeUI.CellEditorHandler Listener responsible for getting cell editing events and updating the tree accordingly.
class | BasicTreeUI.ComponentHandler Updates the preferred size when scrolling (if necessary).
class | BasicTreeUI.FocusHandler Repaints the lead selection row when focus is lost/gained.
class | BasicTreeUI.KeyHandler This is used to get mutliple key down events to appropriately generate events.
class | BasicTreeUI.MouseHandler TreeMouseListener is responsible for updating the selection based on mouse events.
class | BasicTreeUI.MouseInputHandler MouseInputHandler handles passing all mouse events, including mouse motion events, until the mouse is released to the destination it is constructed with.
class | BasicTreeUI.NodeDimensionsHandler Class responsible for getting size of node, method is forwarded to BasicTreeUI method.
class | BasicTreeUI.PropertyChangeHandler PropertyChangeListener for the tree.
class | BasicTreeUI.SelectionModelPropertyChangeHandler Listener on the TreeSelectionModel, resets the row selection if any of the properties of the model change.
class | BasicTreeUI.TreeCancelEditingAction ActionListener that invokes cancelEditing when action performed.
class | BasicTreeUI.TreeExpansionHandler Updates the TreeState in response to nodes expanding/collapsing.
class | BasicTreeUI.TreeHomeAction TreeHomeAction is used to handle end/home actions.
class | BasicTreeUI.TreeIncrementAction TreeIncrementAction is used to handle up/down actions.
class | BasicTreeUI.TreeModelHandler Forwards all TreeModel events to the TreeState.
class | BasicTreeUI.TreePageAction TreePageAction handles page up and page down events.
class | BasicTreeUI.TreeSelectionHandler Listens for changes in the selection model and updates the display accordingly.
class | BasicTreeUI.TreeToggleAction For the first selected row expandedness will be toggled.
class | BasicTreeUI.TreeTraverseAction TreeTraverseAction is the action used for left/right keys.
Field Summary
protected TreeCellEditor | cellEditor Editor for the tree.
protected Icon | collapsedIcon
protected boolean | createdCellEditor Set to true if editor that is currently in the tree was created by this instance.
protected boolean | createdRenderer Set to true if the renderer that is currently in the tree was created by this instance.
protected TreeCellRenderer | currentCellRenderer Renderer that is being used to do the actual cell drawing.
protected int | depthOffset How much the depth should be offset to properly calculate x locations.
protected Hashtable<TreePath,Boolean> | drawingCache Used for minimizing the drawing of vertical lines.
protected Component | editingComponent When editing, this will be the Component that is doing the actual editing.
protected TreePath | editingPath Path that is being edited.
protected int | editingRow Row that is being edited.
protected boolean | editorHasDifferentSize Set to true if the editor has a different size than the renderer.
protected Icon | expandedIcon
protected boolean | largeModel True if doing optimizations for a largeModel.
protected int | lastSelectedRow Index of the row that was last selected.
protected int | leftChildIndent Distance between left margin and where vertical dashes will be drawn.
protected AbstractLayoutCache.NodeDimensions | nodeDimensions Reponsible for telling the TreeState the size needed for a node.
protected Dimension | preferredMinSize Minimum preferred size.
protected Dimension | preferredSize Size needed to completely display all the nodes.
protected CellRendererPane | rendererPane Used to paint the TreeCellRenderer.
protected int | rightChildIndent Distance to add to leftChildIndent to determine where cell contents will be drawn.
protected boolean | stopEditingInCompleteEditing Set to false when editing and shouldSelectCell() returns true meaning the node should be selected before editing, used in completeEditing.
protected int | totalChildIndent Total distance that will be indented.
protected JTree | tree Component that we're going to be drawing into.
protected TreeModel | treeModel Used to determine what to display.
protected TreeSelectionModel | treeSelectionModel Model maintaing the selection.
protected AbstractLayoutCache | treeState Object responsible for handling sizing and expanded issues.
protected boolean | validCachedPreferredSize Is the preferredSize valid?
Constructor Summary
BasicTreeUI()
Method Summary
 void cancelEditing(JTree tree)
Cancels the current editing session.
protected  void checkForClickInExpandControl(TreePath path, int mouseX, int mouseY)
If the mouseX and mouseY are in the expand/collapse region of the row, this will toggle the row.
protected  void completeEditing()
Messages to stop the editing session.
protected  void completeEditing(boolean messageStop, boolean messageCancel, boolean messageTree)
Stops the editing session.
protected  void completeUIInstall()
Invoked from installUI after all the defaults/listeners have been installed.
protected  void completeUIUninstall()
protected  void configureLayoutCache()
Resets the TreeState instance based on the tree we're providing the look and feel for.
protected  CellEditorListener createCellEditorListener()
Creates a listener to handle events from the current editor.
protected  CellRendererPane createCellRendererPane()
Returns the renderer pane that renderer components are placed in.
protected  ComponentListener createComponentListener()
Creates and returns a new ComponentHandler.
protected  TreeCellEditor createDefaultCellEditor()
Creates a default cell editor.
protected  TreeCellRenderer createDefaultCellRenderer()
Returns the default cell renderer that is used to do the stamping of each node.
protected  FocusListener createFocusListener()
Creates a listener that is responsible for updating the display when focus is lost/gained.
protected  KeyListener createKeyListener()
Creates the listener reponsible for getting key events from the tree.
protected  AbstractLayoutCache createLayoutCache()
Creates the object responsible for managing what is expanded, as well as the size of nodes.
protected  MouseListener createMouseListener()
Creates the listener responsible for updating the selection based on mouse events.
protected  AbstractLayoutCache.NodeDimensions createNodeDimensions()
Creates an instance of NodeDimensions that is able to determine the size of a given node in the tree.
protected  PropertyChangeListener createPropertyChangeListener()
Creates a listener that is responsible that updates the UI based on how the tree changes.
protected  PropertyChangeListener createSelectionModelPropertyChangeListener()
Creates the listener responsible for getting property change events from the selection model.
protected  TreeExpansionListener createTreeExpansionListener()
Creates and returns the object responsible for updating the treestate when nodes expanded state changes.
protected  TreeModelListener createTreeModelListener()
Returns a listener that can update the tree when the model changes.
protected  TreeSelectionListener createTreeSelectionListener()
Creates the listener that updates the display based on selection change methods.
static ComponentUI createUI(JComponent x)
protected  void drawCentered(Component c, Graphics graphics, Icon icon, int x, int y)
protected  void drawDashedHorizontalLine(Graphics g, int y, int x1, int x2)
protected  void drawDashedVerticalLine(Graphics g, int x, int y1, int y2)
protected  void ensureRowsAreVisible(int beginRow, int endRow)
Ensures that the rows identified by beginRow through endRow are visible.
 int getBaseline(JComponent c, int width, int height)
Returns the baseline.
 Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.
protected  TreeCellEditor getCellEditor()
protected  TreeCellRenderer getCellRenderer()
Return currentCellRenderer, which will either be the trees renderer, or defaultCellRenderer, which ever wasn't null.
 TreePath getClosestPathForLocation(JTree tree, int x, int y)
Returns the path to the node that is closest to x,y.
 Icon getCollapsedIcon()
 TreePath getEditingPath(JTree tree)
Returns the path to the element that is being edited.
 Icon getExpandedIcon()
protected  Color getHashColor()
protected  int getHorizontalLegBuffer()
The horizontal element of legs between nodes starts at the right of the left-hand side of the child node by default.
protected  TreePath getLastChildPath(TreePath parent)
Returns a path to the last child of parent.
 int getLeftChildIndent()
 Dimension getMaximumSize(JComponent c)
Returns the maximum size for this component, which will be the preferred size if the instance is currently in a JTree, or 0, 0.
 Dimension getMinimumSize(JComponent c)
Returns the minimum size for this component.
protected  TreeModel getModel()
 Rectangle getPathBounds(JTree tree, TreePath path)
Returns the Rectangle enclosing the label portion that the last item in path will be drawn into.
 TreePath getPathForRow(JTree tree, int row)
Returns the path for passed in row.
 Dimension getPreferredMinSize()
Returns the minimum preferred size.
 Dimension getPreferredSize(JComponent c)
Returns the preferred size to properly display the tree, this is a cover method for getPreferredSize(c, false).
 Dimension getPreferredSize(JComponent c, boolean checkConsistancy)
Returns the preferred size to represent the tree in c.
 int getRightChildIndent()
 int getRowCount(JTree tree)
Returns the number of rows that are being displayed.
 int getRowForPath(JTree tree, TreePath path)
Returns the row that the last item identified in path is visible at.
protected  int getRowHeight()
protected  int getRowX(int row, int depth)
Returns the location, along the x-axis, to render a particular row at.
protected  TreeSelectionModel getSelectionModel()
protected  boolean getShowsRootHandles()
protected  int getVerticalLegBuffer()
The vertical element of legs between nodes starts at the bottom of the parent node by default.
protected  void handleExpandControlClick(TreePath path, int mouseX, int mouseY)
Messaged when the user clicks the particular row, this invokes toggleExpandState.
protected  void installComponents()
Intalls the subcomponents of the tree, which is the renderer pane.
protected  void installDefaults()
protected  void installKeyboardActions()
protected  void installListeners()
 void installUI(JComponent c)
Configures the specified component appropriate for the look and feel.
protected  boolean isEditable()
 boolean isEditing(JTree tree)
Returns true if the tree is being edited.
protected  boolean isLargeModel()
protected  boolean isLeaf(int row)
protected  boolean isLocationInExpandControl(TreePath path, int mouseX, int mouseY)
Returns true if mouseX and mouseY fall in the area of row that is used to expand/collapse the node and the node at row does not represent a leaf.
protected  boolean isMultiSelectEvent(MouseEvent event)
Returning true signifies a mouse event on the node should select from the anchor point.
protected  boolean isRootVisible()
protected  boolean isToggleEvent(MouseEvent event)
Returning true indicates the row under the mouse should be toggled based on the event.
protected  boolean isToggleSelectionEvent(MouseEvent event)
Returning true signifies a mouse event on the node should toggle the selection of only the row under mouse.
 void paint(Graphics g, JComponent c)
Paints the specified component appropriate for the look and feel.
protected  void paintExpandControl(Graphics g, Rectangle clipBounds, Insets insets, Rectangle bounds, TreePath path, int row, boolean isExpanded, boolean hasBeenExpanded, boolean isLeaf)
Paints the expand (toggle) part of a row.
protected  void paintHorizontalLine(Graphics g, JComponent c, int y, int left, int right)
Paints a horizontal line.
protected  void paintHorizontalPartOfLeg(Graphics g, Rectangle clipBounds, Insets insets, Rectangle bounds, TreePath path, int row, boolean isExpanded, boolean hasBeenExpanded, boolean isLeaf)
Paints the horizontal part of the leg.
protected  void paintRow(Graphics g, Rectangle clipBounds, Insets insets, Rectangle bounds, TreePath path, int row, boolean isExpanded, boolean hasBeenExpanded, boolean isLeaf)
Paints the renderer part of a row.
protected  void paintVerticalLine(Graphics g, JComponent c, int x, int top, int bottom)
Paints a vertical line.
protected  void paintVerticalPartOfLeg(Graphics g, Rectangle clipBounds, Insets insets, TreePath path)
Paints the vertical part of the leg.
protected  void pathWasCollapsed(TreePath path)
Messaged from the VisibleTreeNode after it has collapsed.
protected  void pathWasExpanded(TreePath path)
Messaged from the VisibleTreeNode after it has been expanded.
protected  void prepareForUIInstall()
Invoked after the tree instance variable has been set, but before any defaults/listeners have been installed.
protected  void prepareForUIUninstall()
protected  void selectPathForEvent(TreePath path, MouseEvent event)
Messaged to update the selection based on a MouseEvent over a particular row.
protected  void setCellEditor(TreeCellEditor editor)
Sets the cell editor.
protected  void setCellRenderer(TreeCellRenderer tcr)
Sets the TreeCellRenderer to tcr.
 void setCollapsedIcon(Icon newG)
protected  void setEditable(boolean newValue)
Configures the receiver to allow, or not allow, editing.
 void setExpandedIcon(Icon newG)
protected  void setHashColor(Color color)
protected  void setLargeModel(boolean largeModel)
Updates the componentListener, if necessary.
 void setLeftChildIndent(int newAmount)
protected  void setModel(TreeModel model)
Sets the TreeModel.
 void setPreferredMinSize(Dimension newSize)
Sets the preferred minimum size.
 void setRightChildIndent(int newAmount)
protected  void setRootVisible(boolean newValue)
Sets the root to being visible.
protected  void setRowHeight(int rowHeight)
Sets the row height, this is forwarded to the treeState.
protected  void setSelectionModel(TreeSelectionModel newLSM)
Resets the selection model.
protected  void setShowsRootHandles(boolean newValue)
Determines whether the node handles are to be displayed.
protected  boolean shouldPaintExpandControl(TreePath path, int row, boolean isExpanded, boolean hasBeenExpanded, boolean isLeaf)
Returns true if the expand (toggle) control should be drawn for the specified row.
protected  boolean startEditing(TreePath path, MouseEvent event)
Will start editing for node if there is a cellEditor and shouldSelectCell returns true.
 void startEditingAtPath(JTree tree, TreePath path)
Selects the last item in path and tries to edit it.
 boolean stopEditing(JTree tree)
Stops the current editing session.
protected  void toggleExpandState(TreePath path)
Expands path if it is not expanded, or collapses row if it is expanded.
protected  void uninstallComponents()
Uninstalls the renderer pane.
protected  void uninstallDefaults()
protected  void uninstallKeyboardActions()
protected  void uninstallListeners()
 void uninstallUI(JComponent c)
Reverses configuration which was done on the specified component during installUI.
protected  void updateCachedPreferredSize()
Updates the preferredSize instance variable, which is returned from getPreferredSize().
protected  void updateCellEditor()
Updates the cellEditor based on the editability of the JTree that we're contained in.
protected  void updateDepthOffset()
Updates how much each depth should be offset by.
protected  void updateExpandedDescendants(TreePath path)
Updates the expanded state of all the descendants of path by getting the expanded descendants from the tree and forwarding to the tree state.
protected  void updateLayoutCacheExpandedNodes()
Makes all the nodes that are expanded in JTree expanded in LayoutCache.
protected  void updateRenderer()
Messaged from the tree we're in when the renderer has changed.
protected  void updateSize()
Marks the cached size as being invalid, and messages the tree with treeDidChange.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

collapsedIcon

protected transient Icon collapsedIcon

expandedIcon

protected transient Icon expandedIcon

leftChildIndent

protected int leftChildIndent
Distance between left margin and where vertical dashes will be drawn.

rightChildIndent

protected int rightChildIndent
Distance to add to leftChildIndent to determine where cell contents will be drawn.

totalChildIndent

protected int totalChildIndent
Total distance that will be indented. The sum of leftChildIndent and rightChildIndent.

preferredMinSize

protected Dimension preferredMinSize
Minimum preferred size.

lastSelectedRow

protected int lastSelectedRow
Index of the row that was last selected.

tree

protected JTree tree
Component that we're going to be drawing into.

currentCellRenderer

protected transient TreeCellRenderer currentCellRenderer
Renderer that is being used to do the actual cell drawing.

createdRenderer

protected boolean createdRenderer
Set to true if the renderer that is currently in the tree was created by this instance.

cellEditor

protected transient TreeCellEditor cellEditor
Editor for the tree.

createdCellEditor

protected boolean createdCellEditor
Set to true if editor that is currently in the tree was created by this instance.

stopEditingInCompleteEditing

protected boolean stopEditingInCompleteEditing
Set to false when editing and shouldSelectCell() returns true meaning the node should be selected before editing, used in completeEditing.

rendererPane

protected CellRendererPane rendererPane
Used to paint the TreeCellRenderer.

preferredSize

protected Dimension preferredSize
Size needed to completely display all the nodes.

validCachedPreferredSize

protected boolean validCachedPreferredSize
Is the preferredSize valid?

treeState

protected AbstractLayoutCache treeState
Object responsible for handling sizing and expanded issues.

drawingCache

protected Hashtable<TreePath,Boolean> drawingCache
Used for minimizing the drawing of vertical lines.

largeModel

protected boolean largeModel
True if doing optimizations for a largeModel. Subclasses that don't support this may wish to override createLayoutCache to not return a FixedHeightLayoutCache instance.

nodeDimensions

protected AbstractLayoutCache.NodeDimensions nodeDimensions
Reponsible for telling the TreeState the size needed for a node.

treeModel

protected TreeModel treeModel
Used to determine what to display.

treeSelectionModel

protected TreeSelectionModel treeSelectionModel
Model maintaing the selection.

depthOffset

protected int depthOffset
How much the depth should be offset to properly calculate x locations. This is based on whether or not the root is visible, and if the root handles are visible.

editingComponent

protected Component editingComponent
When editing, this will be the Component that is doing the actual editing.

editingPath

protected TreePath editingPath
Path that is being edited.

editingRow

protected int editingRow
Row that is being edited. Should only be referenced if editingComponent is not null.

editorHasDifferentSize

protected boolean editorHasDifferentSize
Set to true if the editor has a different size than the renderer.

Constructor Detail

BasicTreeUI

public BasicTreeUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent x)

getHashColor

protected Color getHashColor()

setHashColor

protected void setHashColor(Color color)

setLeftChildIndent

public void setLeftChildIndent(int newAmount)

getLeftChildIndent

public int getLeftChildIndent()

setRightChildIndent

public void setRightChildIndent(int newAmount)

getRightChildIndent

public int getRightChildIndent()

setExpandedIcon

public void setExpandedIcon(Icon newG)

getExpandedIcon

public Icon getExpandedIcon()

setCollapsedIcon

public void setCollapsedIcon(Icon newG)

getCollapsedIcon

public Icon getCollapsedIcon()

setLargeModel

protected void setLargeModel(boolean largeModel)
Updates the componentListener, if necessary.

isLargeModel

protected boolean isLargeModel()

setRowHeight

protected void setRowHeight(int rowHeight)
Sets the row height, this is forwarded to the treeState.

getRowHeight

protected int getRowHeight()

setCellRenderer

protected void setCellRenderer(TreeCellRenderer tcr)
Sets the TreeCellRenderer to tcr. This invokes updateRenderer.

getCellRenderer

protected TreeCellRenderer getCellRenderer()
Return currentCellRenderer, which will either be the trees renderer, or defaultCellRenderer, which ever wasn't null.

setModel

protected void setModel(TreeModel model)
Sets the TreeModel.

getModel

protected TreeModel getModel()

setRootVisible

protected void setRootVisible(boolean newValue)
Sets the root to being visible.

isRootVisible

protected boolean isRootVisible()

setShowsRootHandles

protected void setShowsRootHandles(boolean newValue)
Determines whether the node handles are to be displayed.

getShowsRootHandles

protected boolean getShowsRootHandles()

setCellEditor

protected void setCellEditor(TreeCellEditor editor)
Sets the cell editor.

getCellEditor

protected TreeCellEditor getCellEditor()

setEditable

protected void setEditable(boolean newValue)
Configures the receiver to allow, or not allow, editing.

isEditable

protected boolean isEditable()

setSelectionModel

protected void setSelectionModel(TreeSelectionModel newLSM)
Resets the selection model. The appropriate listener are installed on the model.

getSelectionModel

protected TreeSelectionModel getSelectionModel()

getPathBounds

public Rectangle getPathBounds(JTree tree,
                               TreePath path)
Returns the Rectangle enclosing the label portion that the last item in path will be drawn into. Will return null if any component in path is currently valid.

Specified by:
getPathBounds in class TreeUI

getPathForRow

public TreePath getPathForRow(JTree tree,
                              int row)
Returns the path for passed in row. If row is not visible null is returned.

Specified by:
getPathForRow in class TreeUI

getRowForPath

public int getRowForPath(JTree tree,
                         TreePath path)
Returns the row that the last item identified in path is visible at. Will return -1 if any of the elements in path are not currently visible.

Specified by:
getRowForPath in class TreeUI

getRowCount

public int getRowCount(JTree tree)
Returns the number of rows that are being displayed.

Specified by:
getRowCount in class TreeUI

getClosestPathForLocation

public TreePath getClosestPathForLocation(JTree tree,
                                          int x,
                                          int y)
Returns the path to the node that is closest to x,y. If there is nothing currently visible this will return null, otherwise it'll always return a valid path. If you need to test if the returned object is exactly at x, y you should get the bounds for the returned path and test x, y against that.

Specified by:
getClosestPathForLocation in class TreeUI

isEditing

public boolean isEditing(JTree tree)
Returns true if the tree is being edited. The item that is being edited can be returned by getEditingPath().

Specified by:
isEditing in class TreeUI

stopEditing

public boolean stopEditing(JTree tree)
Stops the current editing session. This has no effect if the tree isn't being edited. Returns true if the editor allows the editing session to stop.

Specified by:
stopEditing in class TreeUI

cancelEditing

public void cancelEditing(JTree tree)
Cancels the current editing session.

Specified by:
cancelEditing in class TreeUI

startEditingAtPath

public void startEditingAtPath(JTree tree,
                               TreePath path)
Selects the last item in path and tries to edit it. Editing will fail if the CellEditor won't allow it for the selected item.

Specified by:
startEditingAtPath in class TreeUI

getEditingPath

public TreePath getEditingPath(JTree tree)
Returns the path to the element that is being edited.

Specified by:
getEditingPath in class TreeUI

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

prepareForUIInstall

protected void prepareForUIInstall()
Invoked after the tree instance variable has been set, but before any defaults/listeners have been installed.

completeUIInstall

protected void completeUIInstall()
Invoked from installUI after all the defaults/listeners have been installed.

installDefaults

protected void installDefaults()

installListeners

protected void installListeners()

installKeyboardActions

protected void installKeyboardActions()

installComponents

protected void installComponents()
Intalls the subcomponents of the tree, which is the renderer pane.

createNodeDimensions

protected AbstractLayoutCache.NodeDimensions createNodeDimensions()
Creates an instance of NodeDimensions that is able to determine the size of a given node in the tree.

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener()
Creates a listener that is responsible that updates the UI based on how the tree changes.

createMouseListener

protected MouseListener createMouseListener()
Creates the listener responsible for updating the selection based on mouse events.

createFocusListener

protected FocusListener createFocusListener()
Creates a listener that is responsible for updating the display when focus is lost/gained.

createKeyListener

protected KeyListener createKeyListener()
Creates the listener reponsible for getting key events from the tree.

createSelectionModelPropertyChangeListener

protected PropertyChangeListener createSelectionModelPropertyChangeListener()
Creates the listener responsible for getting property change events from the selection model.

createTreeSelectionListener

protected TreeSelectionListener createTreeSelectionListener()
Creates the listener that updates the display based on selection change methods.

createCellEditorListener

protected CellEditorListener createCellEditorListener()
Creates a listener to handle events from the current editor.

createComponentListener

protected ComponentListener createComponentListener()
Creates and returns a new ComponentHandler. This is used for the large model to mark the validCachedPreferredSize as invalid when the component moves.

createTreeExpansionListener

protected TreeExpansionListener createTreeExpansionListener()
Creates and returns the object responsible for updating the treestate when nodes expanded state changes.

createLayoutCache

protected AbstractLayoutCache createLayoutCache()
Creates the object responsible for managing what is expanded, as well as the size of nodes.

createCellRendererPane

protected CellRendererPane createCellRendererPane()
Returns the renderer pane that renderer components are placed in.

createDefaultCellEditor

protected TreeCellEditor createDefaultCellEditor()
Creates a default cell editor.

createDefaultCellRenderer

protected TreeCellRenderer createDefaultCellRenderer()
Returns the default cell renderer that is used to do the stamping of each node.

createTreeModelListener

protected TreeModelListener createTreeModelListener()
Returns a listener that can update the tree when the model changes.

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

prepareForUIUninstall

protected void prepareForUIUninstall()

completeUIUninstall

protected void completeUIUninstall()

uninstallDefaults

protected void uninstallDefaults()

uninstallListeners

protected void uninstallListeners()

uninstallKeyboardActions

protected void uninstallKeyboardActions()

uninstallComponents

protected void uninstallComponents()
Uninstalls the renderer pane.

getBaseline

public int getBaseline(JComponent c,
                       int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class ComponentUI
Parameters:
c - JComponent baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
NullPointerException - if c is null
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of the component changes as the size changes.

Overrides:
getBaselineResizeBehavior in class ComponentUI
Parameters:
c - JComponent to return baseline resize behavior for
Returns:
an enum indicating how the baseline changes as the component size changes
Throws:
NullPointerException - if c is null
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

paintHorizontalPartOfLeg

protected void paintHorizontalPartOfLeg(Graphics g,
                                        Rectangle clipBounds,
                                        Insets insets,
                                        Rectangle bounds,
                                        TreePath path,
                                        int row,
                                        boolean isExpanded,
                                        boolean hasBeenExpanded,
                                        boolean isLeaf)
Paints the horizontal part of the leg. The receiver should NOT modify clipBounds, or insets.

NOTE: parentRow can be -1 if the root is not visible.

paintVerticalPartOfLeg

protected void paintVerticalPartOfLeg(Graphics g,
                                      Rectangle clipBounds,
                                      Insets insets,
                                      TreePath path)
Paints the vertical part of the leg. The receiver should NOT modify clipBounds, insets.

paintExpandControl

protected void paintExpandControl(Graphics g,
                                  Rectangle clipBounds,
                                  Insets insets,
                                  Rectangle bounds,
                                  TreePath path,
                                  int row,
                                  boolean isExpanded,
                                  boolean hasBeenExpanded,
                                  boolean isLeaf)
Paints the expand (toggle) part of a row. The receiver should NOT modify clipBounds, or insets.

paintRow

protected void paintRow(Graphics g,
                        Rectangle clipBounds,
                        Insets insets,
                        Rectangle bounds,
                        TreePath path,
                        int row,
                        boolean isExpanded,
                        boolean hasBeenExpanded,
                        boolean isLeaf)
Paints the renderer part of a row. The receiver should NOT modify clipBounds, or insets.

shouldPaintExpandControl

protected boolean shouldPaintExpandControl(TreePath path,
                                           int row,
                                           boolean isExpanded,
                                           boolean hasBeenExpanded,
                                           boolean isLeaf)
Returns true if the expand (toggle) control should be drawn for the specified row.

paintVerticalLine

protected void paintVerticalLine(Graphics g,
                                 JComponent c,
                                 int x,
                                 int top,
                                 int bottom)
Paints a vertical line.

paintHorizontalLine

protected void paintHorizontalLine(Graphics g,
                                   JComponent c,
                                   int y,
                                   int left,
                                   int right)
Paints a horizontal line.

getVerticalLegBuffer

protected int getVerticalLegBuffer()
The vertical element of legs between nodes starts at the bottom of the parent node by default. This method makes the leg start below that.

getHorizontalLegBuffer

protected int getHorizontalLegBuffer()
The horizontal element of legs between nodes starts at the right of the left-hand side of the child node by default. This method makes the leg end before that.

drawCentered

protected void drawCentered(Component c,
                            Graphics graphics,
                            Icon icon,
                            int x,
                            int y)

drawDashedHorizontalLine

protected void drawDashedHorizontalLine(Graphics g,
                                        int y,
                                        int x1,
                                        int x2)

drawDashedVerticalLine

protected void drawDashedVerticalLine(Graphics g,
                                      int x,
                                      int y1,
                                      int y2)

getRowX

protected int getRowX(int row,
                      int depth)
Returns the location, along the x-axis, to render a particular row at. The return value does not include any Insets specified on the JTree. This does not check for the validity of the row or depth, it is assumed to be correct and will not throw an Exception if the row or depth doesn't match that of the tree.

Parameters:
row - Row to return x location for
depth - Depth of the row
Returns:
amount to indent the given row.
Since:
1.5

updateLayoutCacheExpandedNodes

protected void updateLayoutCacheExpandedNodes()
Makes all the nodes that are expanded in JTree expanded in LayoutCache. This invokes updateExpandedDescendants with the root path.

updateExpandedDescendants

protected void updateExpandedDescendants(TreePath path)
Updates the expanded state of all the descendants of path by getting the expanded descendants from the tree and forwarding to the tree state.

getLastChildPath

protected TreePath getLastChildPath(TreePath parent)
Returns a path to the last child of parent.

updateDepthOffset

protected void updateDepthOffset()
Updates how much each depth should be offset by.

updateCellEditor

protected void updateCellEditor()
Updates the cellEditor based on the editability of the JTree that we're contained in. If the tree is editable but doesn't have a cellEditor, a basic one will be used.

updateRenderer

protected void updateRenderer()
Messaged from the tree we're in when the renderer has changed.

configureLayoutCache

protected void configureLayoutCache()
Resets the TreeState instance based on the tree we're providing the look and feel for.

updateSize

protected void updateSize()
Marks the cached size as being invalid, and messages the tree with treeDidChange.

updateCachedPreferredSize

protected void updateCachedPreferredSize()
Updates the preferredSize instance variable, which is returned from getPreferredSize().

For left to right orientations, the size is determined from the current AbstractLayoutCache. For RTL orientations, the preferred size becomes the width minus the minimum x position.

pathWasExpanded

protected void pathWasExpanded(TreePath path)
Messaged from the VisibleTreeNode after it has been expanded.

pathWasCollapsed

protected void pathWasCollapsed(TreePath path)
Messaged from the VisibleTreeNode after it has collapsed.

ensureRowsAreVisible

protected void ensureRowsAreVisible(int beginRow,
                                    int endRow)
Ensures that the rows identified by beginRow through endRow are visible.

setPreferredMinSize

public void setPreferredMinSize(Dimension newSize)
Sets the preferred minimum size.

getPreferredMinSize

public Dimension getPreferredMinSize()
Returns the minimum preferred size.

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Returns the preferred size to properly display the tree, this is a cover method for getPreferredSize(c, false).

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getPreferredSize

public Dimension getPreferredSize(JComponent c,
                                  boolean checkConsistancy)
Returns the preferred size to represent the tree in c. If checkConsistancy is true checkConsistancy is messaged first.

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Returns the minimum size for this component. Which will be the min preferred size or 0, 0.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Returns the maximum size for this component, which will be the preferred size if the instance is currently in a JTree, or 0, 0.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

completeEditing

protected void completeEditing()
Messages to stop the editing session. If the UI the receiver is providing the look and feel for returns true from getInvokesStopCellEditing, stopCellEditing will invoked on the current editor. Then completeEditing will be messaged with false, true, false to cancel any lingering editing.

completeEditing

protected void completeEditing(boolean messageStop,
                               boolean messageCancel,
                               boolean messageTree)
Stops the editing session. If messageStop is true the editor is messaged with stopEditing, if messageCancel is true the editor is messaged with cancelEditing. If messageTree is true the treeModel is messaged with valueForPathChanged.

startEditing

protected boolean startEditing(TreePath path,
                               MouseEvent event)
Will start editing for node if there is a cellEditor and shouldSelectCell returns true.

This assumes that path is valid and visible.

checkForClickInExpandControl

protected void checkForClickInExpandControl(TreePath path,
                                            int mouseX,
                                            int mouseY)
If the mouseX and mouseY are in the expand/collapse region of the row, this will toggle the row.

isLocationInExpandControl

protected boolean isLocationInExpandControl(TreePath path,
                                            int mouseX,
                                            int mouseY)
Returns true if mouseX and mouseY fall in the area of row that is used to expand/collapse the node and the node at row does not represent a leaf.

handleExpandControlClick

protected void handleExpandControlClick(TreePath path,
                                        int mouseX,
                                        int mouseY)
Messaged when the user clicks the particular row, this invokes toggleExpandState.

toggleExpandState

protected void toggleExpandState(TreePath path)
Expands path if it is not expanded, or collapses row if it is expanded. If expanding a path and JTree scrolls on expand, ensureRowsAreVisible is invoked to scroll as many of the children to visible as possible (tries to scroll to last visible descendant of path).

isToggleSelectionEvent

protected boolean isToggleSelectionEvent(MouseEvent event)
Returning true signifies a mouse event on the node should toggle the selection of only the row under mouse.

isMultiSelectEvent

protected boolean isMultiSelectEvent(MouseEvent event)
Returning true signifies a mouse event on the node should select from the anchor point.

isToggleEvent

protected boolean isToggleEvent(MouseEvent event)
Returning true indicates the row under the mouse should be toggled based on the event. This is invoked after checkForClickInExpandControl, implying the location is not in the expand (toggle) control

selectPathForEvent

protected void selectPathForEvent(TreePath path,
                                  MouseEvent event)
Messaged to update the selection based on a MouseEvent over a particular row. If the event is a toggle selection event, the row is either selected, or deselected. If the event identifies a multi selection event, the selection is updated from the anchor point. Otherwise the row is selected, and if the event specified a toggle event the row is expanded/collapsed.

isLeaf

protected boolean isLeaf(int row)
Returns:
true if the node at row is a leaf.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.CellEditorHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.CellEditorHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicTreeUI.CellEditorHandler
All Implemented Interfaces:
EventListener, CellEditorListener
Enclosing class:
BasicTreeUI
public class BasicTreeUI.CellEditorHandler
extends Object
implements CellEditorListener

Listener responsible for getting cell editing events and updating the tree accordingly.

Constructor Summary
BasicTreeUI.CellEditorHandler()
Method Summary
void | editingCanceled(ChangeEvent e) Messaged when editing has been canceled in the tree.
void | editingStopped(ChangeEvent e) Messaged when editing has stopped in the tree.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTreeUI.CellEditorHandler

public BasicTreeUI.CellEditorHandler()
Method Detail

editingStopped

public void editingStopped(ChangeEvent e)
Messaged when editing has stopped in the tree.

Specified by:
editingStopped in interface CellEditorListener

editingCanceled

public void editingCanceled(ChangeEvent e)
Messaged when editing has been canceled in the tree.

Specified by:
editingCanceled in interface CellEditorListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.ComponentHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.ComponentHandler

java.lang.Object
    extended by  java.awt.event.ComponentAdapter
        extended by  javax.swing.plaf.basic.BasicTreeUI.ComponentHandler
All Implemented Interfaces:
ActionListener, ComponentListener, EventListener
Enclosing class:
BasicTreeUI
public class BasicTreeUI.ComponentHandler
extends ComponentAdapter
implements ActionListener

Updates the preferred size when scrolling (if necessary).

Field Summary
protected JScrollBar | scrollBar ScrollBar that is being adjusted.
protected Timer | timer Timer used when inside a scrollpane and the scrollbar is adjusting.
Constructor Summary
BasicTreeUI.ComponentHandler()
Method Summary
void | actionPerformed(ActionEvent ae) Public as a result of Timer.
void | componentMoved(ComponentEvent e) Invoked when the component's position changes.
protected JScrollPane | getScrollPane() Returns the JScrollPane housing the JTree, or null if one isn't found.
protected void | startTimer() Creates, if necessary, and starts a Timer to check if need to resize the bounds.
Methods inherited from class java.awt.event.ComponentAdapter
componentHidden, componentResized, componentShown
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

timer

protected Timer timer
Timer used when inside a scrollpane and the scrollbar is adjusting.

scrollBar

protected JScrollBar scrollBar
ScrollBar that is being adjusted.

Constructor Detail

BasicTreeUI.ComponentHandler

public BasicTreeUI.ComponentHandler()
Method Detail

componentMoved

public void componentMoved(ComponentEvent e)
Description copied from class: ComponentAdapter
Invoked when the component's position changes.

Specified by:
componentMoved in interface ComponentListener
Overrides:
componentMoved in class ComponentAdapter

startTimer

protected void startTimer()
Creates, if necessary, and starts a Timer to check if need to resize the bounds.

getScrollPane

protected JScrollPane getScrollPane()
Returns the JScrollPane housing the JTree, or null if one isn't found.

actionPerformed

public void actionPerformed(ActionEvent ae)
Public as a result of Timer. If the scrollBar is null, or not adjusting, this stops the timer and updates the sizing.

Specified by:
actionPerformed in interface ActionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.FocusHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.FocusHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicTreeUI.FocusHandler
All Implemented Interfaces:
FocusListener, EventListener
Enclosing class:
BasicTreeUI
public class BasicTreeUI.FocusHandler
extends Object
implements FocusListener

Repaints the lead selection row when focus is lost/gained.

Constructor Summary
BasicTreeUI.FocusHandler()
Method Summary
void | focusGained(FocusEvent e) Invoked when focus is activated on the tree we're in, redraws the lead row.
void | focusLost(FocusEvent e) Invoked when focus is activated on the tree we're in, redraws the lead row.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTreeUI.FocusHandler

public BasicTreeUI.FocusHandler()
Method Detail

focusGained

public void focusGained(FocusEvent e)
Invoked when focus is activated on the tree we're in, redraws the lead row.

Specified by:
focusGained in interface FocusListener

focusLost

public void focusLost(FocusEvent e)
Invoked when focus is activated on the tree we're in, redraws the lead row.

Specified by:
focusLost in interface FocusListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.KeyHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.KeyHandler

java.lang.Object
    extended by  java.awt.event.KeyAdapter
        extended by  javax.swing.plaf.basic.BasicTreeUI.KeyHandler
All Implemented Interfaces:
KeyListener, EventListener
Enclosing class:
BasicTreeUI
public class BasicTreeUI.KeyHandler
extends KeyAdapter

This is used to get mutliple key down events to appropriately generate events.

Field Summary
protected boolean | isKeyDown Set to true while keyPressed is active.
protected Action | repeatKeyAction Key code that is being generated for.
Constructor Summary
BasicTreeUI.KeyHandler()
Method Summary
void | keyPressed(KeyEvent e) Invoked when a key has been pressed.
void | keyReleased(KeyEvent e) Invoked when a key has been released.
void | keyTyped(KeyEvent e) Invoked when a key has been typed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

repeatKeyAction

protected Action repeatKeyAction
Key code that is being generated for.

isKeyDown

protected boolean isKeyDown
Set to true while keyPressed is active.

Constructor Detail

BasicTreeUI.KeyHandler

public BasicTreeUI.KeyHandler()
Method Detail

keyTyped

public void keyTyped(KeyEvent e)
Invoked when a key has been typed. Moves the keyboard focus to the first element whose first letter matches the alphanumeric key pressed by the user. Subsequent same key presses move the keyboard focus to the next object that starts with the same letter.

Specified by:
keyTyped in interface KeyListener
Overrides:
keyTyped in class KeyAdapter

keyPressed

public void keyPressed(KeyEvent e)
Description copied from class: KeyAdapter
Invoked when a key has been pressed.

Specified by:
keyPressed in interface KeyListener
Overrides:
keyPressed in class KeyAdapter

keyReleased

public void keyReleased(KeyEvent e)
Description copied from class: KeyAdapter
Invoked when a key has been released.

Specified by:
keyReleased in interface KeyListener
Overrides:
keyReleased in class KeyAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.MouseHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.MouseHandler

java.lang.Object
    extended by  java.awt.event.MouseAdapter
        extended by  javax.swing.plaf.basic.BasicTreeUI.MouseHandler
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, EventListener
Enclosing class:
BasicTreeUI
public class BasicTreeUI.MouseHandler
extends MouseAdapter
implements MouseMotionListener

TreeMouseListener is responsible for updating the selection based on mouse events.

Constructor Summary
BasicTreeUI.MouseHandler()
Method Summary
void | mouseDragged(MouseEvent e) Invoked when a mouse button is pressed on a component and then dragged.
void | mouseMoved(MouseEvent e) Invoked when the mouse button has been moved on a component (with no buttons no down).
void | mousePressed(MouseEvent e) Invoked when a mouse button has been pressed on a component.
void | mouseReleased(MouseEvent e) Invoked when a mouse button has been released on a component.
Methods inherited from class java.awt.event.MouseAdapter
mouseClicked, mouseEntered, mouseExited, mouseWheelMoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTreeUI.MouseHandler

public BasicTreeUI.MouseHandler()
Method Detail

mousePressed

public void mousePressed(MouseEvent e)
Invoked when a mouse button has been pressed on a component.

Specified by:
mousePressed in interface MouseListener
Overrides:
mousePressed in class MouseAdapter

mouseDragged

public void mouseDragged(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when a mouse button is pressed on a component and then dragged. MOUSE_DRAGGED events will continue to be delivered to the component where the drag originated until the mouse button is released (regardless of whether the mouse position is within the bounds of the component).

Due to platform-dependent Drag&Drop implementations, MOUSE_DRAGGED events may not be delivered during a native Drag&Drop operation.

Specified by:
mouseDragged in interface MouseMotionListener
Overrides:
mouseDragged in class MouseAdapter

mouseMoved

public void mouseMoved(MouseEvent e)
Invoked when the mouse button has been moved on a component (with no buttons no down).

Specified by:
mouseMoved in interface MouseMotionListener
Overrides:
mouseMoved in class MouseAdapter
Since:
1.4

mouseReleased

public void mouseReleased(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when a mouse button has been released on a component.

Specified by:
mouseReleased in interface MouseListener
Overrides:
mouseReleased in class MouseAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.MouseInputHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.MouseInputHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicTreeUI.MouseInputHandler
All Implemented Interfaces:
MouseListener, MouseMotionListener, EventListener, MouseInputListener
Enclosing class:
BasicTreeUI
public class BasicTreeUI.MouseInputHandler
extends Object
implements MouseInputListener

MouseInputHandler handles passing all mouse events, including mouse motion events, until the mouse is released to the destination it is constructed with. It is assumed all the events are currently target at source.

Field Summary
protected Component | destination Destination that receives all events.
protected Component | source Source that events are coming from.
Constructor Summary
BasicTreeUI.MouseInputHandler(Component source, Component destination, MouseEvent event)
Method Summary
void | mouseClicked(MouseEvent e) Invoked when the mouse button has been clicked (pressed and released) on a component.
void | mouseDragged(MouseEvent e) Invoked when a mouse button is pressed on a component and then dragged.
void | mouseEntered(MouseEvent e) Invoked when the mouse enters a component.
void | mouseExited(MouseEvent e) Invoked when the mouse exits a component.
void | mouseMoved(MouseEvent e) Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.
void | mousePressed(MouseEvent e) Invoked when a mouse button has been pressed on a component.
void | mouseReleased(MouseEvent e) Invoked when a mouse button has been released on a component.
protected void | removeFromSource()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

source

protected Component source
Source that events are coming from.

destination

protected Component destination
Destination that receives all events.

Constructor Detail

BasicTreeUI.MouseInputHandler

public BasicTreeUI.MouseInputHandler(Component source,
                                     Component destination,
                                     MouseEvent event)
Method Detail

mouseClicked

public void mouseClicked(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse button has been clicked (pressed and released) on a component.

Specified by:
mouseClicked in interface MouseListener

mousePressed

public void mousePressed(MouseEvent e)
Description copied from interface: MouseListener
Invoked when a mouse button has been pressed on a component.

Specified by:
mousePressed in interface MouseListener

mouseReleased

public void mouseReleased(MouseEvent e)
Description copied from interface: MouseListener
Invoked when a mouse button has been released on a component.

Specified by:
mouseReleased in interface MouseListener

mouseEntered

public void mouseEntered(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse enters a component.

Specified by:
mouseEntered in interface MouseListener

mouseExited

public void mouseExited(MouseEvent e)
Description copied from interface: MouseListener
Invoked when the mouse exits a component.

Specified by:
mouseExited in interface MouseListener

mouseDragged

public void mouseDragged(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when a mouse button is pressed on a component and then dragged. MOUSE_DRAGGED events will continue to be delivered to the component where the drag originated until the mouse button is released (regardless of whether the mouse position is within the bounds of the component).

Due to platform-dependent Drag&Drop implementations, MOUSE_DRAGGED events may not be delivered during a native Drag&Drop operation.

Specified by:
mouseDragged in interface MouseMotionListener

mouseMoved

public void mouseMoved(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.

Specified by:
mouseMoved in interface MouseMotionListener

removeFromSource

protected void removeFromSource()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.NodeDimensionsHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.NodeDimensionsHandler

java.lang.Object
    extended by  javax.swing.tree.AbstractLayoutCache.NodeDimensions
        extended by  javax.swing.plaf.basic.BasicTreeUI.NodeDimensionsHandler
Enclosing class:
BasicTreeUI
public class BasicTreeUI.NodeDimensionsHandler
extends AbstractLayoutCache.NodeDimensions

Class responsible for getting size of node, method is forwarded to BasicTreeUI method. X location does not include insets, that is handled in getPathBounds.

Constructor Summary
BasicTreeUI.NodeDimensionsHandler()
Method Summary
Rectangle | getNodeDimensions(Object value, int row, int depth, boolean expanded, Rectangle size) Responsible for getting the size of a particular node.
protected int | getRowX(int row, int depth)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTreeUI.NodeDimensionsHandler

public BasicTreeUI.NodeDimensionsHandler()
Method Detail

getNodeDimensions

public Rectangle getNodeDimensions(Object value,
                                   int row,
                                   int depth,
                                   boolean expanded,
                                   Rectangle size)
Responsible for getting the size of a particular node.

Specified by:
getNodeDimensions in class AbstractLayoutCache.NodeDimensions
Parameters:
value - the value to be represented
row - row being queried
depth - the depth of the row
expanded - true if row is expanded, false otherwise
size - a Rectangle containing the size needed to represent value
Returns:
a Rectangle containing the node dimensions, or null if node has no dimension

getRowX

protected int getRowX(int row,
                      int depth)
Returns:
amount to indent the given row.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.PropertyChangeHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.PropertyChangeHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicTreeUI.PropertyChangeHandler
All Implemented Interfaces:
PropertyChangeListener, EventListener
Enclosing class:
BasicTreeUI
public class BasicTreeUI.PropertyChangeHandler
extends Object
implements PropertyChangeListener

PropertyChangeListener for the tree. Updates the appropriate varaible, or TreeState, based on what changes.

Constructor Summary
BasicTreeUI.PropertyChangeHandler()
Method Summary
 void propertyChange(PropertyChangeEvent event)
This method gets called when a bound property is changed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTreeUI.PropertyChangeHandler

public BasicTreeUI.PropertyChangeHandler()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent event)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
event - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.SelectionModelPropertyChangeHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.SelectionModelPropertyChangeHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicTreeUI.SelectionModelPropertyChangeHandler
All Implemented Interfaces:
PropertyChangeListener, EventListener
Enclosing class:
BasicTreeUI
public class BasicTreeUI.SelectionModelPropertyChangeHandler
extends Object
implements PropertyChangeListener

Listener on the TreeSelectionModel, resets the row selection if any of the properties of the model change.

Constructor Summary
BasicTreeUI.SelectionModelPropertyChangeHandler()
Method Summary
 void propertyChange(PropertyChangeEvent event)
This method gets called when a bound property is changed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTreeUI.SelectionModelPropertyChangeHandler

public BasicTreeUI.SelectionModelPropertyChangeHandler()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent event)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
event - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.TreeCancelEditingAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.TreeCancelEditingAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicTreeUI.TreeCancelEditingAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicTreeUI
public class BasicTreeUI.TreeCancelEditingAction
extends AbstractAction

ActionListener that invokes cancelEditing when action performed.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
BasicTreeUI.TreeCancelEditingAction(String name)
Method Summary
void | actionPerformed(ActionEvent e) Invoked when an action occurs.
boolean | isEnabled() Returns true if the action is enabled.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTreeUI.TreeCancelEditingAction

public BasicTreeUI.TreeCancelEditingAction(String name)
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

isEnabled

public boolean isEnabled()
Description copied from class: AbstractAction
Returns true if the action is enabled.

Specified by:
isEnabled in interface Action
Overrides:
isEnabled in class AbstractAction
Returns:
true if the action is enabled, false otherwise
See Also:
Action.isEnabled()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.TreeExpansionHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.TreeExpansionHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicTreeUI.TreeExpansionHandler
All Implemented Interfaces:
EventListener, TreeExpansionListener
Enclosing class:
BasicTreeUI
public class BasicTreeUI.TreeExpansionHandler
extends Object
implements TreeExpansionListener

Updates the TreeState in response to nodes expanding/collapsing.

Constructor Summary
BasicTreeUI.TreeExpansionHandler()
Method Summary
void | treeCollapsed(TreeExpansionEvent event) Called whenever an item in the tree has been collapsed.
void | treeExpanded(TreeExpansionEvent event) Called whenever an item in the tree has been expanded.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTreeUI.TreeExpansionHandler

public BasicTreeUI.TreeExpansionHandler()
Method Detail

treeExpanded

public void treeExpanded(TreeExpansionEvent event)
Called whenever an item in the tree has been expanded.

Specified by:
treeExpanded in interface TreeExpansionListener

treeCollapsed

public void treeCollapsed(TreeExpansionEvent event)
Called whenever an item in the tree has been collapsed.

Specified by:
treeCollapsed in interface TreeExpansionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.TreeHomeAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.TreeHomeAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicTreeUI.TreeHomeAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicTreeUI
public class BasicTreeUI.TreeHomeAction
extends AbstractAction

TreeHomeAction is used to handle end/home actions. Scrolls either the first or last cell to be visible based on direction.

Field Summary
protected  int direction
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
BasicTreeUI.TreeHomeAction(int direction, String name)
Method Summary
void | actionPerformed(ActionEvent e) Invoked when an action occurs.
boolean | isEnabled() Returns true if the action is enabled.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

direction

protected int direction
Constructor Detail

BasicTreeUI.TreeHomeAction

public BasicTreeUI.TreeHomeAction(int direction,
                                  String name)
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

isEnabled

public boolean isEnabled()
Description copied from class: AbstractAction
Returns true if the action is enabled.

Specified by:
isEnabled in interface Action
Overrides:
isEnabled in class AbstractAction
Returns:
true if the action is enabled, false otherwise
See Also:
Action.isEnabled()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.TreeIncrementAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.TreeIncrementAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicTreeUI.TreeIncrementAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicTreeUI
public class BasicTreeUI.TreeIncrementAction
extends AbstractAction

TreeIncrementAction is used to handle up/down actions. Selection is moved up or down based on direction.

Field Summary
protected  int direction
Specifies the direction to adjust the selection by.
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
BasicTreeUI.TreeIncrementAction(int direction, String name)
Method Summary
void | actionPerformed(ActionEvent e) Invoked when an action occurs.
boolean | isEnabled() Returns true if the action is enabled.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

direction

protected int direction
Specifies the direction to adjust the selection by.

Constructor Detail

BasicTreeUI.TreeIncrementAction

public BasicTreeUI.TreeIncrementAction(int direction,
                                       String name)
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

isEnabled

public boolean isEnabled()
Description copied from class: AbstractAction
Returns true if the action is enabled.

Specified by:
isEnabled in interface Action
Overrides:
isEnabled in class AbstractAction
Returns:
true if the action is enabled, false otherwise
See Also:
Action.isEnabled()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.TreeModelHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.TreeModelHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicTreeUI.TreeModelHandler
All Implemented Interfaces:
EventListener, TreeModelListener
Enclosing class:
BasicTreeUI
public class BasicTreeUI.TreeModelHandler
extends Object
implements TreeModelListener

Forwards all TreeModel events to the TreeState.

Constructor Summary
BasicTreeUI.TreeModelHandler()
Method Summary
void | treeNodesChanged(TreeModelEvent e) Invoked after a node (or a set of siblings) has changed in some way.
void | treeNodesInserted(TreeModelEvent e) Invoked after nodes have been inserted into the tree.
void | treeNodesRemoved(TreeModelEvent e) Invoked after nodes have been removed from the tree.
void | treeStructureChanged(TreeModelEvent e) Invoked after the tree has drastically changed structure from a given node down.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTreeUI.TreeModelHandler

public BasicTreeUI.TreeModelHandler()
Method Detail

treeNodesChanged

public void treeNodesChanged(TreeModelEvent e)
Description copied from interface: TreeModelListener

Invoked after a node (or a set of siblings) has changed in some way. The node(s) have not changed locations in the tree or altered their children arrays, but other attributes have changed and may affect presentation. Example: the name of a file has changed, but it is in the same location in the file system.

To indicate the root has changed, childIndices and children will be null.

Use e.getPath() to get the parent of the changed node(s). e.getChildIndices() returns the index(es) of the changed node(s).

Specified by:
treeNodesChanged in interface TreeModelListener

treeNodesInserted

public void treeNodesInserted(TreeModelEvent e)
Description copied from interface: TreeModelListener

Invoked after nodes have been inserted into the tree.

Use e.getPath() to get the parent of the new node(s). e.getChildIndices() returns the index(es) of the new node(s) in ascending order.

Specified by:
treeNodesInserted in interface TreeModelListener

treeNodesRemoved

public void treeNodesRemoved(TreeModelEvent e)
Description copied from interface: TreeModelListener

Invoked after nodes have been removed from the tree. Note that if a subtree is removed from the tree, this method may only be invoked once for the root of the removed subtree, not once for each individual set of siblings removed.

Use e.getPath() to get the former parent of the deleted node(s). e.getChildIndices() returns, in ascending order, the index(es) the node(s) had before being deleted.

Specified by:
treeNodesRemoved in interface TreeModelListener

treeStructureChanged

public void treeStructureChanged(TreeModelEvent e)
Description copied from interface: TreeModelListener

Invoked after the tree has drastically changed structure from a given node down. If the path returned by e.getPath() is of length one and the first element does not identify the current root node the first element should become the new root of the tree.

Use e.getPath() to get the path to the node. e.getChildIndices() returns null.

Specified by:
treeStructureChanged in interface TreeModelListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.TreePageAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.TreePageAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicTreeUI.TreePageAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicTreeUI
public class BasicTreeUI.TreePageAction
extends AbstractAction

TreePageAction handles page up and page down events.

Field Summary
protected  int direction
Specifies the direction to adjust the selection by.
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
BasicTreeUI.TreePageAction(int direction, String name)
Method Summary
void | actionPerformed(ActionEvent e) Invoked when an action occurs.
boolean | isEnabled() Returns true if the action is enabled.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

direction

protected int direction
Specifies the direction to adjust the selection by.

Constructor Detail

BasicTreeUI.TreePageAction

public BasicTreeUI.TreePageAction(int direction,
                                  String name)
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

isEnabled

public boolean isEnabled()
Description copied from class: AbstractAction
Returns true if the action is enabled.

Specified by:
isEnabled in interface Action
Overrides:
isEnabled in class AbstractAction
Returns:
true if the action is enabled, false otherwise
See Also:
Action.isEnabled()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.TreeSelectionHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.TreeSelectionHandler

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicTreeUI.TreeSelectionHandler
All Implemented Interfaces:
EventListener, TreeSelectionListener
Enclosing class:
BasicTreeUI
public class BasicTreeUI.TreeSelectionHandler
extends Object
implements TreeSelectionListener

Listens for changes in the selection model and updates the display accordingly.

Constructor Summary
BasicTreeUI.TreeSelectionHandler()
Method Summary
 void valueChanged(TreeSelectionEvent event)
Messaged when the selection changes in the tree we're displaying for.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTreeUI.TreeSelectionHandler

public BasicTreeUI.TreeSelectionHandler()
Method Detail

valueChanged

public void valueChanged(TreeSelectionEvent event)
Messaged when the selection changes in the tree we're displaying for. Stops editing, messages super and displays the changed paths.

Specified by:
valueChanged in interface TreeSelectionListener
Parameters:
event - the event that characterizes the change.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.TreeToggleAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.TreeToggleAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicTreeUI.TreeToggleAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicTreeUI
public class BasicTreeUI.TreeToggleAction
extends AbstractAction

For the first selected row expandedness will be toggled.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
BasicTreeUI.TreeToggleAction(String name)
Method Summary
void | actionPerformed(ActionEvent e) Invoked when an action occurs.
boolean | isEnabled() Returns true if the action is enabled.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicTreeUI.TreeToggleAction

public BasicTreeUI.TreeToggleAction(String name)
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

isEnabled

public boolean isEnabled()
Description copied from class: AbstractAction
Returns true if the action is enabled.

Specified by:
isEnabled in interface Action
Overrides:
isEnabled in class AbstractAction
Returns:
true if the action is enabled, false otherwise
See Also:
Action.isEnabled()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicTreeUI.TreeTraverseAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicTreeUI.TreeTraverseAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.basic.BasicTreeUI.TreeTraverseAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
BasicTreeUI
public class BasicTreeUI.TreeTraverseAction
extends AbstractAction

TreeTraverseAction is the action used for left/right keys. Will toggle the expandedness of a node, as well as potentially incrementing the selection.

Field Summary
protected  int direction
Determines direction to traverse, 1 means expand, -1 means collapse.
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
BasicTreeUI.TreeTraverseAction(int direction, String name)
Method Summary
void | actionPerformed(ActionEvent e) Invoked when an action occurs.
boolean | isEnabled() Returns true if the action is enabled.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

direction

protected int direction
Determines direction to traverse, 1 means expand, -1 means collapse.

Constructor Detail

BasicTreeUI.TreeTraverseAction

public BasicTreeUI.TreeTraverseAction(int direction,
                                      String name)
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

isEnabled

public boolean isEnabled()
Description copied from class: AbstractAction
Returns true if the action is enabled.

Specified by:
isEnabled in interface Action
Overrides:
isEnabled in class AbstractAction
Returns:
true if the action is enabled, false otherwise
See Also:
Action.isEnabled()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BasicViewportUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class BasicViewportUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ViewportUI
            extended by  javax.swing.plaf.basic.BasicViewportUI

public class BasicViewportUI
extends ViewportUI

BasicViewport implementation

Constructor Summary
BasicViewportUI()
Method Summary
static ComponentUI | createUI(JComponent c)
protected void | installDefaults(JComponent c)
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
protected void | uninstallDefaults(JComponent c)
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, paint, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BasicViewportUI

public BasicViewportUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class ComponentUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class ComponentUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installDefaults

protected void installDefaults(JComponent c)

uninstallDefaults

protected void uninstallDefaults(JComponent c)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.swing.plaf.basic.BasicArrowButton

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicArrowButton

Packages that use BasicArrowButton
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicArrowButton in javax.swing.plaf.metal

Subclasses of BasicArrowButton in javax.swing.plaf.metal
 class MetalScrollButton
JButton object for Metal scrollbar arrows.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicBorders

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicBorders

No usage of javax.swing.plaf.basic.BasicBorders

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicBorders.ButtonBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicBorders.ButtonBorder

Packages that use BasicBorders.ButtonBorder
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of BasicBorders.ButtonBorder in javax.swing.plaf.basic

Subclasses of BasicBorders.ButtonBorder in javax.swing.plaf.basic
static class | BasicBorders.RadioButtonBorder
static class | BasicBorders.RolloverButtonBorder Special thin border for rollover toolbar buttons.
static class | BasicBorders.ToggleButtonBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicBorders.FieldBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicBorders.FieldBorder

No usage of javax.swing.plaf.basic.BasicBorders.FieldBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicBorders.MarginBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicBorders.MarginBorder

No usage of javax.swing.plaf.basic.BasicBorders.MarginBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicBorders.MenuBarBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicBorders.MenuBarBorder

No usage of javax.swing.plaf.basic.BasicBorders.MenuBarBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicBorders.RadioButtonBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicBorders.RadioButtonBorder

No usage of javax.swing.plaf.basic.BasicBorders.RadioButtonBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicBorders.RolloverButtonBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicBorders.RolloverButtonBorder

No usage of javax.swing.plaf.basic.BasicBorders.RolloverButtonBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicBorders.SplitPaneBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicBorders.SplitPaneBorder

No usage of javax.swing.plaf.basic.BasicBorders.SplitPaneBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicBorders.ToggleButtonBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicBorders.ToggleButtonBorder

No usage of javax.swing.plaf.basic.BasicBorders.ToggleButtonBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicButtonListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicButtonListener

Packages that use BasicButtonListener
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicButtonListener in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic that return BasicButtonListener
protected  BasicButtonListener BasicButtonUI.createButtonListener(AbstractButton b)

Uses of BasicButtonListener in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal that return BasicButtonListener
protected  BasicButtonListener MetalButtonUI.createButtonListener(AbstractButton b)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicButtonUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicButtonUI

Packages that use BasicButtonUI
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicButtonUI in javax.swing.plaf.basic

Subclasses of BasicButtonUI in javax.swing.plaf.basic
class | BasicCheckBoxUI CheckboxUI implementation for BasicCheckboxUI
class | BasicRadioButtonUI RadioButtonUI implementation for BasicRadioButtonUI
class | BasicToggleButtonUI BasicToggleButton implementation

Uses of BasicButtonUI in javax.swing.plaf.metal

Subclasses of BasicButtonUI in javax.swing.plaf.metal
class | MetalButtonUI MetalButtonUI implementation
class | MetalCheckBoxUI CheckboxUI implementation for MetalCheckboxUI
class | MetalRadioButtonUI RadioButtonUI implementation for MetalRadioButtonUI
class | MetalToggleButtonUI MetalToggleButton implementation

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicCheckBoxMenuItemUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicCheckBoxMenuItemUI

No usage of javax.swing.plaf.basic.BasicCheckBoxMenuItemUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicCheckBoxUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicCheckBoxUI

No usage of javax.swing.plaf.basic.BasicCheckBoxUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicColorChooserUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicColorChooserUI

No usage of javax.swing.plaf.basic.BasicColorChooserUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicColorChooserUI.PropertyHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicColorChooserUI.PropertyHandler

No usage of javax.swing.plaf.basic.BasicColorChooserUI.PropertyHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboBoxEditor

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboBoxEditor

Packages that use BasicComboBoxEditor
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicComboBoxEditor in javax.swing.plaf.basic

Subclasses of BasicComboBoxEditor in javax.swing.plaf.basic
static class BasicComboBoxEditor.UIResource
A subclass of BasicComboBoxEditor that implements UIResource.

Uses of BasicComboBoxEditor in javax.swing.plaf.metal

Subclasses of BasicComboBoxEditor in javax.swing.plaf.metal
class | MetalComboBoxEditor The default editor for Metal editable combo boxes
static class | MetalComboBoxEditor.UIResource A subclass of BasicComboBoxEditor that implements UIResource.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboBoxEditor.UIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboBoxEditor.UIResource

No usage of javax.swing.plaf.basic.BasicComboBoxEditor.UIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboBoxRenderer

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboBoxRenderer

Packages that use BasicComboBoxRenderer
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of BasicComboBoxRenderer in javax.swing.plaf.basic

Subclasses of BasicComboBoxRenderer in javax.swing.plaf.basic
static class BasicComboBoxRenderer.UIResource
A subclass of BasicComboBoxRenderer that implements UIResource.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboBoxRenderer.UIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboBoxRenderer.UIResource

No usage of javax.swing.plaf.basic.BasicComboBoxRenderer.UIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboBoxUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboBoxUI

Packages that use BasicComboBoxUI
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicComboBoxUI in javax.swing.plaf.metal

Subclasses of BasicComboBoxUI in javax.swing.plaf.metal
 class MetalComboBoxUI
Metal UI for JComboBox

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboBoxUI.ComboBoxLayoutManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboBoxUI.ComboBoxLayoutManager

Packages that use BasicComboBoxUI.ComboBoxLayoutManager
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicComboBoxUI.ComboBoxLayoutManager in javax.swing.plaf.metal

Subclasses of BasicComboBoxUI.ComboBoxLayoutManager in javax.swing.plaf.metal
 class MetalComboBoxUI.MetalComboBoxLayoutManager
This inner class is marked "public" due to a compiler bug.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboBoxUI.FocusHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboBoxUI.FocusHandler

No usage of javax.swing.plaf.basic.BasicComboBoxUI.FocusHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboBoxUI.ItemHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboBoxUI.ItemHandler

No usage of javax.swing.plaf.basic.BasicComboBoxUI.ItemHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboBoxUI.KeyHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboBoxUI.KeyHandler

No usage of javax.swing.plaf.basic.BasicComboBoxUI.KeyHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboBoxUI.ListDataHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboBoxUI.ListDataHandler

No usage of javax.swing.plaf.basic.BasicComboBoxUI.ListDataHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboBoxUI.PropertyChangeHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboBoxUI.PropertyChangeHandler

Packages that use BasicComboBoxUI.PropertyChangeHandler
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicComboBoxUI.PropertyChangeHandler in javax.swing.plaf.metal

Subclasses of BasicComboBoxUI.PropertyChangeHandler in javax.swing.plaf.metal
 class MetalComboBoxUI.MetalPropertyChangeListener
This inner class is marked "public" due to a compiler bug.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboPopup

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboPopup

Packages that use BasicComboPopup
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicComboPopup in javax.swing.plaf.metal

Subclasses of BasicComboPopup in javax.swing.plaf.metal
 class MetalComboBoxUI.MetalComboPopup
Deprecated. As of Java 2 platform v1.4.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboPopup.InvocationKeyHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboPopup.InvocationKeyHandler

No usage of javax.swing.plaf.basic.BasicComboPopup.InvocationKeyHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboPopup.InvocationMouseHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboPopup.InvocationMouseHandler

No usage of javax.swing.plaf.basic.BasicComboPopup.InvocationMouseHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboPopup.InvocationMouseMotionHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboPopup.InvocationMouseMotionHandler

No usage of javax.swing.plaf.basic.BasicComboPopup.InvocationMouseMotionHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboPopup.ItemHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboPopup.ItemHandler

No usage of javax.swing.plaf.basic.BasicComboPopup.ItemHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboPopup.ListDataHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboPopup.ListDataHandler

No usage of javax.swing.plaf.basic.BasicComboPopup.ListDataHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboPopup.ListMouseHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboPopup.ListMouseHandler

No usage of javax.swing.plaf.basic.BasicComboPopup.ListMouseHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboPopup.ListMouseMotionHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboPopup.ListMouseMotionHandler

No usage of javax.swing.plaf.basic.BasicComboPopup.ListMouseMotionHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboPopup.ListSelectionHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboPopup.ListSelectionHandler

No usage of javax.swing.plaf.basic.BasicComboPopup.ListSelectionHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicComboPopup.PropertyChangeHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicComboPopup.PropertyChangeHandler

No usage of javax.swing.plaf.basic.BasicComboPopup.PropertyChangeHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicDesktopIconUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicDesktopIconUI

Packages that use BasicDesktopIconUI
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicDesktopIconUI in javax.swing.plaf.metal

Subclasses of BasicDesktopIconUI in javax.swing.plaf.metal
 class MetalDesktopIconUI
Metal desktop icon.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicDesktopIconUI.MouseInputHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicDesktopIconUI.MouseInputHandler

No usage of javax.swing.plaf.basic.BasicDesktopIconUI.MouseInputHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicDesktopPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicDesktopPaneUI

No usage of javax.swing.plaf.basic.BasicDesktopPaneUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicDesktopPaneUI.CloseAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicDesktopPaneUI.CloseAction

No usage of javax.swing.plaf.basic.BasicDesktopPaneUI.CloseAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicDesktopPaneUI.MaximizeAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicDesktopPaneUI.MaximizeAction

No usage of javax.swing.plaf.basic.BasicDesktopPaneUI.MaximizeAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicDesktopPaneUI.MinimizeAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicDesktopPaneUI.MinimizeAction

No usage of javax.swing.plaf.basic.BasicDesktopPaneUI.MinimizeAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicDesktopPaneUI.NavigateAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicDesktopPaneUI.NavigateAction

No usage of javax.swing.plaf.basic.BasicDesktopPaneUI.NavigateAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicDesktopPaneUI.OpenAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicDesktopPaneUI.OpenAction

No usage of javax.swing.plaf.basic.BasicDesktopPaneUI.OpenAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicDirectoryModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicDirectoryModel

Packages that use BasicDirectoryModel
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of BasicDirectoryModel in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic that return BasicDirectoryModel
 BasicDirectoryModel BasicFileChooserUI.getModel()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicEditorPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicEditorPaneUI

Packages that use BasicEditorPaneUI
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of BasicEditorPaneUI in javax.swing.plaf.basic

Subclasses of BasicEditorPaneUI in javax.swing.plaf.basic
 class BasicTextPaneUI
Provides the look and feel for a styled text editor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicFileChooserUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicFileChooserUI

Packages that use BasicFileChooserUI
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicFileChooserUI in javax.swing.plaf.metal

Subclasses of BasicFileChooserUI in javax.swing.plaf.metal
 class MetalFileChooserUI
Metal L&F implementation of a FileChooser.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicFileChooserUI.AcceptAllFileFilter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicFileChooserUI.AcceptAllFileFilter

No usage of javax.swing.plaf.basic.BasicFileChooserUI.AcceptAllFileFilter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicFileChooserUI.ApproveSelectionAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicFileChooserUI.ApproveSelectionAction

No usage of javax.swing.plaf.basic.BasicFileChooserUI.ApproveSelectionAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicFileChooserUI.BasicFileView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicFileChooserUI.BasicFileView

No usage of javax.swing.plaf.basic.BasicFileChooserUI.BasicFileView

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicFileChooserUI.CancelSelectionAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicFileChooserUI.CancelSelectionAction

No usage of javax.swing.plaf.basic.BasicFileChooserUI.CancelSelectionAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicFileChooserUI.ChangeToParentDirectoryAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicFileChooserUI.ChangeToParentDirectoryAction

No usage of javax.swing.plaf.basic.BasicFileChooserUI.ChangeToParentDirectoryAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicFileChooserUI.DoubleClickListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicFileChooserUI.DoubleClickListener

No usage of javax.swing.plaf.basic.BasicFileChooserUI.DoubleClickListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicFileChooserUI.GoHomeAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicFileChooserUI.GoHomeAction

No usage of javax.swing.plaf.basic.BasicFileChooserUI.GoHomeAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicFileChooserUI.NewFolderAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicFileChooserUI.NewFolderAction

No usage of javax.swing.plaf.basic.BasicFileChooserUI.NewFolderAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicFileChooserUI.SelectionListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicFileChooserUI.SelectionListener

No usage of javax.swing.plaf.basic.BasicFileChooserUI.SelectionListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicFileChooserUI.UpdateAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicFileChooserUI.UpdateAction

No usage of javax.swing.plaf.basic.BasicFileChooserUI.UpdateAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicFormattedTextFieldUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicFormattedTextFieldUI

No usage of javax.swing.plaf.basic.BasicFormattedTextFieldUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicGraphicsUtils

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicGraphicsUtils

No usage of javax.swing.plaf.basic.BasicGraphicsUtils

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicHTML

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicHTML

No usage of javax.swing.plaf.basic.BasicHTML

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicIconFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicIconFactory

No usage of javax.swing.plaf.basic.BasicIconFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicInternalFrameTitlePane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicInternalFrameTitlePane

Packages that use BasicInternalFrameTitlePane
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicInternalFrameTitlePane in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as BasicInternalFrameTitlePane
protected  BasicInternalFrameTitlePane BasicInternalFrameUI.titlePane

Uses of BasicInternalFrameTitlePane in javax.swing.plaf.metal

Subclasses of BasicInternalFrameTitlePane in javax.swing.plaf.metal
 class MetalInternalFrameTitlePane
Class that manages a JLF title bar

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicInternalFrameTitlePane.CloseAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicInternalFrameTitlePane.CloseAction

No usage of javax.swing.plaf.basic.BasicInternalFrameTitlePane.CloseAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicInternalFrameTitlePane.IconifyAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicInternalFrameTitlePane.IconifyAction

No usage of javax.swing.plaf.basic.BasicInternalFrameTitlePane.IconifyAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicInternalFrameTitlePane.MaximizeAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicInternalFrameTitlePane.MaximizeAction

No usage of javax.swing.plaf.basic.BasicInternalFrameTitlePane.MaximizeAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicInternalFrameTitlePane.MoveAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicInternalFrameTitlePane.MoveAction

No usage of javax.swing.plaf.basic.BasicInternalFrameTitlePane.MoveAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicInternalFrameTitlePane.PropertyChangeHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicInternalFrameTitlePane.PropertyChangeHandler

No usage of javax.swing.plaf.basic.BasicInternalFrameTitlePane.PropertyChangeHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicInternalFrameTitlePane.RestoreAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicInternalFrameTitlePane.RestoreAction

No usage of javax.swing.plaf.basic.BasicInternalFrameTitlePane.RestoreAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicInternalFrameTitlePane.SizeAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicInternalFrameTitlePane.SizeAction

No usage of javax.swing.plaf.basic.BasicInternalFrameTitlePane.SizeAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicInternalFrameTitlePane.SystemMenuBar

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicInternalFrameTitlePane.SystemMenuBar

No usage of javax.swing.plaf.basic.BasicInternalFrameTitlePane.SystemMenuBar

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicInternalFrameTitlePane.TitlePaneLayout

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicInternalFrameTitlePane.TitlePaneLayout

No usage of javax.swing.plaf.basic.BasicInternalFrameTitlePane.TitlePaneLayout

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicInternalFrameUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicInternalFrameUI

Packages that use BasicInternalFrameUI
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicInternalFrameUI in javax.swing.plaf.metal

Subclasses of BasicInternalFrameUI in javax.swing.plaf.metal
 class MetalInternalFrameUI
Metal implementation of JInternalFrame.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicInternalFrameUI.BasicInternalFrameListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicInternalFrameUI.BasicInternalFrameListener

No usage of javax.swing.plaf.basic.BasicInternalFrameUI.BasicInternalFrameListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicInternalFrameUI.BorderListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicInternalFrameUI.BorderListener

No usage of javax.swing.plaf.basic.BasicInternalFrameUI.BorderListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicInternalFrameUI.ComponentHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicInternalFrameUI.ComponentHandler

No usage of javax.swing.plaf.basic.BasicInternalFrameUI.ComponentHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicInternalFrameUI.GlassPaneDispatcher

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicInternalFrameUI.GlassPaneDispatcher

No usage of javax.swing.plaf.basic.BasicInternalFrameUI.GlassPaneDispatcher

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicInternalFrameUI.InternalFrameLayout

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicInternalFrameUI.InternalFrameLayout

No usage of javax.swing.plaf.basic.BasicInternalFrameUI.InternalFrameLayout

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicInternalFrameUI.InternalFramePropertyChangeListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicInternalFrameUI.InternalFramePropertyChangeListener

No usage of javax.swing.plaf.basic.BasicInternalFrameUI.InternalFramePropertyChangeListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicLabelUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicLabelUI

Packages that use BasicLabelUI
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicLabelUI in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as BasicLabelUI
protected static BasicLabelUI BasicLabelUI.labelUI
The default BasicLabelUI instance.

Uses of BasicLabelUI in javax.swing.plaf.metal

Subclasses of BasicLabelUI in javax.swing.plaf.metal
 class MetalLabelUI
A Windows L&F implementation of LabelUI.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicListUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicListUI

No usage of javax.swing.plaf.basic.BasicListUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicListUI.FocusHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicListUI.FocusHandler

No usage of javax.swing.plaf.basic.BasicListUI.FocusHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicListUI.ListDataHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicListUI.ListDataHandler

No usage of javax.swing.plaf.basic.BasicListUI.ListDataHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicListUI.ListSelectionHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicListUI.ListSelectionHandler

No usage of javax.swing.plaf.basic.BasicListUI.ListSelectionHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicListUI.MouseInputHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicListUI.MouseInputHandler

No usage of javax.swing.plaf.basic.BasicListUI.MouseInputHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicListUI.PropertyChangeHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicListUI.PropertyChangeHandler

No usage of javax.swing.plaf.basic.BasicListUI.PropertyChangeHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicLookAndFeel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicLookAndFeel

Packages that use BasicLookAndFeel
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.synth | Synth is a skinnable look and feel in which all painting is delegated.

Uses of BasicLookAndFeel in javax.swing.plaf.metal

Subclasses of BasicLookAndFeel in javax.swing.plaf.metal
 class MetalLookAndFeel
The Java Look and Feel, otherwise known as Metal.

Uses of BasicLookAndFeel in javax.swing.plaf.synth

Subclasses of BasicLookAndFeel in javax.swing.plaf.synth
 class SynthLookAndFeel
SynthLookAndFeel provides the basis for creating a customized look and feel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicMenuBarUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicMenuBarUI

Packages that use BasicMenuBarUI
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicMenuBarUI in javax.swing.plaf.metal

Subclasses of BasicMenuBarUI in javax.swing.plaf.metal
 class MetalMenuBarUI
Metal implementation of MenuBarUI.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicMenuItemUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicMenuItemUI

Packages that use BasicMenuItemUI
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of BasicMenuItemUI in javax.swing.plaf.basic

Subclasses of BasicMenuItemUI in javax.swing.plaf.basic
class | BasicCheckBoxMenuItemUI BasicCheckboxMenuItem implementation
class | BasicMenuUI A default L&F implementation of MenuUI.
class | BasicRadioButtonMenuItemUI BasicRadioButtonMenuItem implementation

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicMenuItemUI.MouseInputHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicMenuItemUI.MouseInputHandler

No usage of javax.swing.plaf.basic.BasicMenuItemUI.MouseInputHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicMenuUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicMenuUI

Packages that use BasicMenuUI
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of BasicMenuUI in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as BasicMenuUI
 BasicMenuUI BasicMenuUI.ChangeHandler.ui

Constructors in javax.swing.plaf.basic with parameters of type BasicMenuUI
BasicMenuUI.ChangeHandler(JMenu m, BasicMenuUI ui)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicMenuUI.ChangeHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicMenuUI.ChangeHandler

No usage of javax.swing.plaf.basic.BasicMenuUI.ChangeHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicMenuUI.MouseInputHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicMenuUI.MouseInputHandler

No usage of javax.swing.plaf.basic.BasicMenuUI.MouseInputHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicOptionPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicOptionPaneUI

No usage of javax.swing.plaf.basic.BasicOptionPaneUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicOptionPaneUI.ButtonActionListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicOptionPaneUI.ButtonActionListener

No usage of javax.swing.plaf.basic.BasicOptionPaneUI.ButtonActionListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicOptionPaneUI.ButtonAreaLayout

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicOptionPaneUI.ButtonAreaLayout

No usage of javax.swing.plaf.basic.BasicOptionPaneUI.ButtonAreaLayout

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicOptionPaneUI.PropertyChangeHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicOptionPaneUI.PropertyChangeHandler

No usage of javax.swing.plaf.basic.BasicOptionPaneUI.PropertyChangeHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicPanelUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicPanelUI

No usage of javax.swing.plaf.basic.BasicPanelUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicPasswordFieldUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicPasswordFieldUI

No usage of javax.swing.plaf.basic.BasicPasswordFieldUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicPopupMenuSeparatorUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicPopupMenuSeparatorUI

No usage of javax.swing.plaf.basic.BasicPopupMenuSeparatorUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicPopupMenuUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicPopupMenuUI

No usage of javax.swing.plaf.basic.BasicPopupMenuUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicProgressBarUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicProgressBarUI

Packages that use BasicProgressBarUI
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicProgressBarUI in javax.swing.plaf.metal

Subclasses of BasicProgressBarUI in javax.swing.plaf.metal
 class MetalProgressBarUI
The Metal implementation of ProgressBarUI.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicProgressBarUI.ChangeHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicProgressBarUI.ChangeHandler

No usage of javax.swing.plaf.basic.BasicProgressBarUI.ChangeHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicRadioButtonMenuItemUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicRadioButtonMenuItemUI

No usage of javax.swing.plaf.basic.BasicRadioButtonMenuItemUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicRadioButtonUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicRadioButtonUI

Packages that use BasicRadioButtonUI
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicRadioButtonUI in javax.swing.plaf.basic

Subclasses of BasicRadioButtonUI in javax.swing.plaf.basic
 class BasicCheckBoxUI
CheckboxUI implementation for BasicCheckboxUI

Uses of BasicRadioButtonUI in javax.swing.plaf.metal

Subclasses of BasicRadioButtonUI in javax.swing.plaf.metal
class | MetalCheckBoxUI CheckboxUI implementation for MetalCheckboxUI
class | MetalRadioButtonUI RadioButtonUI implementation for MetalRadioButtonUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicRootPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicRootPaneUI

Packages that use BasicRootPaneUI
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicRootPaneUI in javax.swing.plaf.metal

Subclasses of BasicRootPaneUI in javax.swing.plaf.metal
 class MetalRootPaneUI
Provides the metal look and feel implementation of RootPaneUI.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicScrollBarUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicScrollBarUI

Packages that use BasicScrollBarUI
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicScrollBarUI in javax.swing.plaf.metal

Subclasses of BasicScrollBarUI in javax.swing.plaf.metal
 class MetalScrollBarUI
Implementation of ScrollBarUI for the Metal Look and Feel

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicScrollBarUI.ArrowButtonListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicScrollBarUI.ArrowButtonListener

Packages that use BasicScrollBarUI.ArrowButtonListener
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of BasicScrollBarUI.ArrowButtonListener in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as BasicScrollBarUI.ArrowButtonListener
protected  BasicScrollBarUI.ArrowButtonListener BasicScrollBarUI.buttonListener

Methods in javax.swing.plaf.basic that return BasicScrollBarUI.ArrowButtonListener
protected  BasicScrollBarUI.ArrowButtonListener BasicScrollBarUI.createArrowButtonListener()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicScrollBarUI.ModelListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicScrollBarUI.ModelListener

Packages that use BasicScrollBarUI.ModelListener
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of BasicScrollBarUI.ModelListener in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as BasicScrollBarUI.ModelListener
protected  BasicScrollBarUI.ModelListener BasicScrollBarUI.modelListener

Methods in javax.swing.plaf.basic that return BasicScrollBarUI.ModelListener
protected  BasicScrollBarUI.ModelListener BasicScrollBarUI.createModelListener()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicScrollBarUI.PropertyChangeHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicScrollBarUI.PropertyChangeHandler

No usage of javax.swing.plaf.basic.BasicScrollBarUI.PropertyChangeHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicScrollBarUI.ScrollListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicScrollBarUI.ScrollListener

Packages that use BasicScrollBarUI.ScrollListener
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of BasicScrollBarUI.ScrollListener in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as BasicScrollBarUI.ScrollListener
protected  BasicScrollBarUI.ScrollListener BasicScrollBarUI.scrollListener

Methods in javax.swing.plaf.basic that return BasicScrollBarUI.ScrollListener
protected  BasicScrollBarUI.ScrollListener BasicScrollBarUI.createScrollListener()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicScrollBarUI.TrackListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicScrollBarUI.TrackListener

Packages that use BasicScrollBarUI.TrackListener
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of BasicScrollBarUI.TrackListener in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as BasicScrollBarUI.TrackListener
protected  BasicScrollBarUI.TrackListener BasicScrollBarUI.trackListener

Methods in javax.swing.plaf.basic that return BasicScrollBarUI.TrackListener
protected  BasicScrollBarUI.TrackListener BasicScrollBarUI.createTrackListener()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicScrollPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicScrollPaneUI

Packages that use BasicScrollPaneUI
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicScrollPaneUI in javax.swing.plaf.metal

Subclasses of BasicScrollPaneUI in javax.swing.plaf.metal
 class MetalScrollPaneUI
A Metal L&F implementation of ScrollPaneUI.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicScrollPaneUI.HSBChangeListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicScrollPaneUI.HSBChangeListener

No usage of javax.swing.plaf.basic.BasicScrollPaneUI.HSBChangeListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicScrollPaneUI.MouseWheelHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicScrollPaneUI.MouseWheelHandler

No usage of javax.swing.plaf.basic.BasicScrollPaneUI.MouseWheelHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicScrollPaneUI.PropertyChangeHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicScrollPaneUI.PropertyChangeHandler

No usage of javax.swing.plaf.basic.BasicScrollPaneUI.PropertyChangeHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicScrollPaneUI.ViewportChangeHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicScrollPaneUI.ViewportChangeHandler

No usage of javax.swing.plaf.basic.BasicScrollPaneUI.ViewportChangeHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicScrollPaneUI.VSBChangeListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicScrollPaneUI.VSBChangeListener

No usage of javax.swing.plaf.basic.BasicScrollPaneUI.VSBChangeListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSeparatorUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSeparatorUI

Packages that use BasicSeparatorUI
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicSeparatorUI in javax.swing.plaf.basic

Subclasses of BasicSeparatorUI in javax.swing.plaf.basic
class | BasicPopupMenuSeparatorUI A Basic L&F implementation of PopupMenuSeparatorUI.
class | BasicToolBarSeparatorUI A Basic L&F implementation of ToolBarSeparatorUI.

Uses of BasicSeparatorUI in javax.swing.plaf.metal

Subclasses of BasicSeparatorUI in javax.swing.plaf.metal
class | MetalPopupMenuSeparatorUI A Metal L&F implementation of PopupMenuSeparatorUI.
class | MetalSeparatorUI A Metal L&F implementation of SeparatorUI.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSliderUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSliderUI

Packages that use BasicSliderUI
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicSliderUI in javax.swing.plaf.metal

Subclasses of BasicSliderUI in javax.swing.plaf.metal
 class MetalSliderUI
A Java L&F implementation of SliderUI.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSliderUI.ActionScroller

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSliderUI.ActionScroller

No usage of javax.swing.plaf.basic.BasicSliderUI.ActionScroller

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSliderUI.ChangeHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSliderUI.ChangeHandler

No usage of javax.swing.plaf.basic.BasicSliderUI.ChangeHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSliderUI.ComponentHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSliderUI.ComponentHandler

No usage of javax.swing.plaf.basic.BasicSliderUI.ComponentHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSliderUI.FocusHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSliderUI.FocusHandler

No usage of javax.swing.plaf.basic.BasicSliderUI.FocusHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSliderUI.PropertyChangeHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSliderUI.PropertyChangeHandler

Packages that use BasicSliderUI.PropertyChangeHandler
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicSliderUI.PropertyChangeHandler in javax.swing.plaf.metal

Subclasses of BasicSliderUI.PropertyChangeHandler in javax.swing.plaf.metal
protected  class MetalSliderUI.MetalPropertyListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSliderUI.ScrollListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSliderUI.ScrollListener

Packages that use BasicSliderUI.ScrollListener
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of BasicSliderUI.ScrollListener in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as BasicSliderUI.ScrollListener
protected  BasicSliderUI.ScrollListener BasicSliderUI.scrollListener

Methods in javax.swing.plaf.basic that return BasicSliderUI.ScrollListener
protected  BasicSliderUI.ScrollListener BasicSliderUI.createScrollListener(JSlider slider)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSliderUI.TrackListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSliderUI.TrackListener

Packages that use BasicSliderUI.TrackListener
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of BasicSliderUI.TrackListener in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as BasicSliderUI.TrackListener
protected  BasicSliderUI.TrackListener BasicSliderUI.trackListener

Methods in javax.swing.plaf.basic that return BasicSliderUI.TrackListener
protected  BasicSliderUI.TrackListener BasicSliderUI.createTrackListener(JSlider slider)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSpinnerUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSpinnerUI

No usage of javax.swing.plaf.basic.BasicSpinnerUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSplitPaneDivider

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSplitPaneDivider

Packages that use BasicSplitPaneDivider
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicSplitPaneDivider in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as BasicSplitPaneDivider
protected  BasicSplitPaneDivider BasicSplitPaneUI.divider
Instance of the divider for this JSplitPane.

Methods in javax.swing.plaf.basic that return BasicSplitPaneDivider
BasicSplitPaneDivider | BasicSplitPaneUI.createDefaultDivider() Creates the default divider.
BasicSplitPaneDivider | BasicSplitPaneUI.getDivider() Returns the divider between the top Components.

Uses of BasicSplitPaneDivider in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal that return BasicSplitPaneDivider
 BasicSplitPaneDivider MetalSplitPaneUI.createDefaultDivider()
Creates the default divider.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSplitPaneDivider.DividerLayout

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSplitPaneDivider.DividerLayout

No usage of javax.swing.plaf.basic.BasicSplitPaneDivider.DividerLayout

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSplitPaneDivider.DragController

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSplitPaneDivider.DragController

Packages that use BasicSplitPaneDivider.DragController
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of BasicSplitPaneDivider.DragController in javax.swing.plaf.basic

Subclasses of BasicSplitPaneDivider.DragController in javax.swing.plaf.basic
protected  class BasicSplitPaneDivider.VerticalDragController
Handles the events during a dragging session for a VERTICAL_SPLIT oriented split pane.

Fields in javax.swing.plaf.basic declared as BasicSplitPaneDivider.DragController
protected  BasicSplitPaneDivider.DragController BasicSplitPaneDivider.dragger
Handles mouse dragging message to do the actual dragging.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSplitPaneDivider.MouseHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSplitPaneDivider.MouseHandler

Packages that use BasicSplitPaneDivider.MouseHandler
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of BasicSplitPaneDivider.MouseHandler in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as BasicSplitPaneDivider.MouseHandler
protected  BasicSplitPaneDivider.MouseHandler BasicSplitPaneDivider.mouseHandler
Handles mouse events from both this class, and the split pane.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSplitPaneDivider.VerticalDragController

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSplitPaneDivider.VerticalDragController

No usage of javax.swing.plaf.basic.BasicSplitPaneDivider.VerticalDragController

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSplitPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSplitPaneUI

Packages that use BasicSplitPaneUI
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicSplitPaneUI in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as BasicSplitPaneUI
protected  BasicSplitPaneUI BasicSplitPaneDivider.splitPaneUI
UI this instance was created from.

Methods in javax.swing.plaf.basic that return BasicSplitPaneUI
 BasicSplitPaneUI BasicSplitPaneDivider.getBasicSplitPaneUI()
Returns the SplitPaneUI the receiver is currently in.

Methods in javax.swing.plaf.basic with parameters of type BasicSplitPaneUI
 void BasicSplitPaneDivider.setBasicSplitPaneUI(BasicSplitPaneUI newUI)
Sets the SplitPaneUI that is using the receiver.

Constructors in javax.swing.plaf.basic with parameters of type BasicSplitPaneUI
BasicSplitPaneDivider(BasicSplitPaneUI ui)
Creates an instance of BasicSplitPaneDivider.

Uses of BasicSplitPaneUI in javax.swing.plaf.metal

Subclasses of BasicSplitPaneUI in javax.swing.plaf.metal
 class MetalSplitPaneUI
Metal split pane.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSplitPaneUI.BasicHorizontalLayoutManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSplitPaneUI.BasicHorizontalLayoutManager

Packages that use BasicSplitPaneUI.BasicHorizontalLayoutManager
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of BasicSplitPaneUI.BasicHorizontalLayoutManager in javax.swing.plaf.basic

Subclasses of BasicSplitPaneUI.BasicHorizontalLayoutManager in javax.swing.plaf.basic
 class BasicSplitPaneUI.BasicVerticalLayoutManager
LayoutManager used for JSplitPanes with an orientation of VERTICAL_SPLIT.

Fields in javax.swing.plaf.basic declared as BasicSplitPaneUI.BasicHorizontalLayoutManager
protected  BasicSplitPaneUI.BasicHorizontalLayoutManager BasicSplitPaneUI.layoutManager
LayoutManager that is created and placed into the split pane.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSplitPaneUI.BasicVerticalLayoutManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSplitPaneUI.BasicVerticalLayoutManager

No usage of javax.swing.plaf.basic.BasicSplitPaneUI.BasicVerticalLayoutManager

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSplitPaneUI.FocusHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSplitPaneUI.FocusHandler

No usage of javax.swing.plaf.basic.BasicSplitPaneUI.FocusHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardDownRightHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardDownRightHandler

No usage of javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardDownRightHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardEndHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardEndHandler

No usage of javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardEndHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardHomeHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardHomeHandler

No usage of javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardHomeHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardResizeToggleHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardResizeToggleHandler

No usage of javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardResizeToggleHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardUpLeftHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardUpLeftHandler

No usage of javax.swing.plaf.basic.BasicSplitPaneUI.KeyboardUpLeftHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicSplitPaneUI.PropertyHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicSplitPaneUI.PropertyHandler

No usage of javax.swing.plaf.basic.BasicSplitPaneUI.PropertyHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTabbedPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTabbedPaneUI

Packages that use BasicTabbedPaneUI
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicTabbedPaneUI in javax.swing.plaf.metal

Subclasses of BasicTabbedPaneUI in javax.swing.plaf.metal
 class MetalTabbedPaneUI
The Metal subclass of BasicTabbedPaneUI.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTabbedPaneUI.FocusHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTabbedPaneUI.FocusHandler

No usage of javax.swing.plaf.basic.BasicTabbedPaneUI.FocusHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTabbedPaneUI.MouseHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTabbedPaneUI.MouseHandler

No usage of javax.swing.plaf.basic.BasicTabbedPaneUI.MouseHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTabbedPaneUI.PropertyChangeHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTabbedPaneUI.PropertyChangeHandler

No usage of javax.swing.plaf.basic.BasicTabbedPaneUI.PropertyChangeHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTabbedPaneUI.TabbedPaneLayout

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTabbedPaneUI.TabbedPaneLayout

Packages that use BasicTabbedPaneUI.TabbedPaneLayout
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicTabbedPaneUI.TabbedPaneLayout in javax.swing.plaf.metal

Subclasses of BasicTabbedPaneUI.TabbedPaneLayout in javax.swing.plaf.metal
 class MetalTabbedPaneUI.TabbedPaneLayout
This inner class is marked "public" due to a compiler bug.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTabbedPaneUI.TabSelectionHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTabbedPaneUI.TabSelectionHandler

No usage of javax.swing.plaf.basic.BasicTabbedPaneUI.TabSelectionHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTableHeaderUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTableHeaderUI

No usage of javax.swing.plaf.basic.BasicTableHeaderUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTableHeaderUI.MouseInputHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTableHeaderUI.MouseInputHandler

No usage of javax.swing.plaf.basic.BasicTableHeaderUI.MouseInputHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTableUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTableUI

No usage of javax.swing.plaf.basic.BasicTableUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTableUI.FocusHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTableUI.FocusHandler

No usage of javax.swing.plaf.basic.BasicTableUI.FocusHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTableUI.KeyHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTableUI.KeyHandler

No usage of javax.swing.plaf.basic.BasicTableUI.KeyHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTableUI.MouseInputHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTableUI.MouseInputHandler

No usage of javax.swing.plaf.basic.BasicTableUI.MouseInputHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTextAreaUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTextAreaUI

No usage of javax.swing.plaf.basic.BasicTextAreaUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTextFieldUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTextFieldUI

Packages that use BasicTextFieldUI
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicTextFieldUI in javax.swing.plaf.basic

Subclasses of BasicTextFieldUI in javax.swing.plaf.basic
class | BasicFormattedTextFieldUI Provides the look and feel implementation for JFormattedTextField.
class | BasicPasswordFieldUI Provides the Windows look and feel for a password field.

Uses of BasicTextFieldUI in javax.swing.plaf.metal

Subclasses of BasicTextFieldUI in javax.swing.plaf.metal
 class MetalTextFieldUI
Basis of a look and feel for a JTextField.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTextPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTextPaneUI

No usage of javax.swing.plaf.basic.BasicTextPaneUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTextUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTextUI

Packages that use BasicTextUI
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of BasicTextUI in javax.swing.plaf.basic

Subclasses of BasicTextUI in javax.swing.plaf.basic
class | BasicEditorPaneUI Provides the look and feel for a JEditorPane.
class | BasicFormattedTextFieldUI Provides the look and feel implementation for JFormattedTextField.
class | BasicPasswordFieldUI Provides the Windows look and feel for a password field.
class | BasicTextAreaUI Provides the look and feel for a plain text editor.
class | BasicTextFieldUI Basis of a look and feel for a JTextField.
class | BasicTextPaneUI Provides the look and feel for a styled text editor.

Uses of BasicTextUI in javax.swing.plaf.metal

Subclasses of BasicTextUI in javax.swing.plaf.metal
 class MetalTextFieldUI
Basis of a look and feel for a JTextField.

Uses of BasicTextUI in javax.swing.text

Subclasses of BasicTextUI in javax.swing.text
 class DefaultTextUI
Deprecated.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTextUI.BasicCaret

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTextUI.BasicCaret

No usage of javax.swing.plaf.basic.BasicTextUI.BasicCaret

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTextUI.BasicHighlighter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTextUI.BasicHighlighter

No usage of javax.swing.plaf.basic.BasicTextUI.BasicHighlighter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicToggleButtonUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicToggleButtonUI

Packages that use BasicToggleButtonUI
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicToggleButtonUI in javax.swing.plaf.basic

Subclasses of BasicToggleButtonUI in javax.swing.plaf.basic
class | BasicCheckBoxUI CheckboxUI implementation for BasicCheckboxUI
class | BasicRadioButtonUI RadioButtonUI implementation for BasicRadioButtonUI

Uses of BasicToggleButtonUI in javax.swing.plaf.metal

Subclasses of BasicToggleButtonUI in javax.swing.plaf.metal
class | MetalCheckBoxUI CheckboxUI implementation for MetalCheckboxUI
class | MetalRadioButtonUI RadioButtonUI implementation for MetalRadioButtonUI
class | MetalToggleButtonUI MetalToggleButton implementation

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicToolBarSeparatorUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicToolBarSeparatorUI

No usage of javax.swing.plaf.basic.BasicToolBarSeparatorUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicToolBarUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicToolBarUI

Packages that use BasicToolBarUI
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicToolBarUI in javax.swing.plaf.metal

Subclasses of BasicToolBarUI in javax.swing.plaf.metal
 class MetalToolBarUI
A Metal Look and Feel implementation of ToolBarUI.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicToolBarUI.DockingListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicToolBarUI.DockingListener

Packages that use BasicToolBarUI.DockingListener
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicToolBarUI.DockingListener in javax.swing.plaf.metal

Subclasses of BasicToolBarUI.DockingListener in javax.swing.plaf.metal
protected  class MetalToolBarUI.MetalDockingListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicToolBarUI.DragWindow

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicToolBarUI.DragWindow

Packages that use BasicToolBarUI.DragWindow
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of BasicToolBarUI.DragWindow in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as BasicToolBarUI.DragWindow
protected  BasicToolBarUI.DragWindow BasicToolBarUI.dragWindow

Methods in javax.swing.plaf.basic that return BasicToolBarUI.DragWindow
protected  BasicToolBarUI.DragWindow BasicToolBarUI.createDragWindow(JToolBar toolbar)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicToolBarUI.FrameListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicToolBarUI.FrameListener

No usage of javax.swing.plaf.basic.BasicToolBarUI.FrameListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicToolBarUI.PropertyListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicToolBarUI.PropertyListener

Packages that use BasicToolBarUI.PropertyListener
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicToolBarUI.PropertyListener in javax.swing.plaf.metal

Subclasses of BasicToolBarUI.PropertyListener in javax.swing.plaf.metal
protected  class MetalToolBarUI.MetalRolloverListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicToolBarUI.ToolBarContListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicToolBarUI.ToolBarContListener

Packages that use BasicToolBarUI.ToolBarContListener
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicToolBarUI.ToolBarContListener in javax.swing.plaf.metal

Subclasses of BasicToolBarUI.ToolBarContListener in javax.swing.plaf.metal
protected  class MetalToolBarUI.MetalContainerListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicToolBarUI.ToolBarFocusListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicToolBarUI.ToolBarFocusListener

No usage of javax.swing.plaf.basic.BasicToolBarUI.ToolBarFocusListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicToolTipUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicToolTipUI

Packages that use BasicToolTipUI
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicToolTipUI in javax.swing.plaf.metal

Subclasses of BasicToolTipUI in javax.swing.plaf.metal
 class MetalToolTipUI
A Metal L&F extension of BasicToolTipUI.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI

Packages that use BasicTreeUI
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of BasicTreeUI in javax.swing.plaf.metal

Subclasses of BasicTreeUI in javax.swing.plaf.metal
 class MetalTreeUI
The metal look and feel implementation of TreeUI.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.CellEditorHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.CellEditorHandler

No usage of javax.swing.plaf.basic.BasicTreeUI.CellEditorHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.ComponentHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.ComponentHandler

No usage of javax.swing.plaf.basic.BasicTreeUI.ComponentHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.FocusHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.FocusHandler

No usage of javax.swing.plaf.basic.BasicTreeUI.FocusHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.KeyHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.KeyHandler

No usage of javax.swing.plaf.basic.BasicTreeUI.KeyHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.MouseHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.MouseHandler

No usage of javax.swing.plaf.basic.BasicTreeUI.MouseHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.MouseInputHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.MouseInputHandler

No usage of javax.swing.plaf.basic.BasicTreeUI.MouseInputHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.NodeDimensionsHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.NodeDimensionsHandler

No usage of javax.swing.plaf.basic.BasicTreeUI.NodeDimensionsHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.PropertyChangeHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.PropertyChangeHandler

No usage of javax.swing.plaf.basic.BasicTreeUI.PropertyChangeHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.SelectionModelPropertyChangeHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.SelectionModelPropertyChangeHandler

No usage of javax.swing.plaf.basic.BasicTreeUI.SelectionModelPropertyChangeHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.TreeCancelEditingAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.TreeCancelEditingAction

No usage of javax.swing.plaf.basic.BasicTreeUI.TreeCancelEditingAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.TreeExpansionHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.TreeExpansionHandler

No usage of javax.swing.plaf.basic.BasicTreeUI.TreeExpansionHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.TreeHomeAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.TreeHomeAction

No usage of javax.swing.plaf.basic.BasicTreeUI.TreeHomeAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.TreeIncrementAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.TreeIncrementAction

No usage of javax.swing.plaf.basic.BasicTreeUI.TreeIncrementAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.TreeModelHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.TreeModelHandler

No usage of javax.swing.plaf.basic.BasicTreeUI.TreeModelHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.TreePageAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.TreePageAction

No usage of javax.swing.plaf.basic.BasicTreeUI.TreePageAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.TreeSelectionHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.TreeSelectionHandler

No usage of javax.swing.plaf.basic.BasicTreeUI.TreeSelectionHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.TreeToggleAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.TreeToggleAction

No usage of javax.swing.plaf.basic.BasicTreeUI.TreeToggleAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicTreeUI.TreeTraverseAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicTreeUI.TreeTraverseAction

No usage of javax.swing.plaf.basic.BasicTreeUI.TreeTraverseAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.BasicViewportUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.BasicViewportUI

No usage of javax.swing.plaf.basic.BasicViewportUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.basic.DefaultMenuLayout

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.basic.DefaultMenuLayout

No usage of javax.swing.plaf.basic.DefaultMenuLayout

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.plaf.basic.ComboPopup

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.plaf.basic.ComboPopup

Packages that use ComboPopup
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of ComboPopup in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement ComboPopup
 class BasicComboPopup
This is a basic implementation of the ComboPopup interface.

Fields in javax.swing.plaf.basic declared as ComboPopup
protected  ComboPopup BasicComboBoxUI.popup

Methods in javax.swing.plaf.basic that return ComboPopup
protected  ComboPopup BasicComboBoxUI.createPopup()
Creates the popup portion of the combo box.

Uses of ComboPopup in javax.swing.plaf.metal

Classes in javax.swing.plaf.metal that implement ComboPopup
 class MetalComboBoxUI.MetalComboPopup
Deprecated. As of Java 2 platform v1.4.

Methods in javax.swing.plaf.metal that return ComboPopup
protected  ComboPopup MetalComboBoxUI.createPopup()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ComboPopup

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Interface ComboPopup

All Known Implementing Classes:
BasicComboPopup, MetalComboBoxUI.MetalComboPopup
public interface ComboPopup

The interface which defines the methods required for the implementation of the popup portion of a combo box.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Method Summary
KeyListener | getKeyListener() Returns a key listener that will be added to the combo box or null.
JList | getList() Returns the list that is being used to draw the items in the combo box.
MouseListener | getMouseListener() Returns a mouse listener that will be added to the combo box or null.
MouseMotionListener | getMouseMotionListener() Returns a mouse motion listener that will be added to the combo box or null.
void | hide() Hides the popup
boolean | isVisible() Returns true if the popup is visible (currently being displayed).
void | show() Shows the popup
void | uninstallingUI() Called to inform the ComboPopup that the UI is uninstalling.

Method Detail

show

void show()
Shows the popup

hide

void hide()
Hides the popup

isVisible

boolean isVisible()
Returns true if the popup is visible (currently being displayed).

Returns:
true if the component is visible; false otherwise.

getList

JList getList()
Returns the list that is being used to draw the items in the combo box. This method is highly implementation specific and should not be used for general list manipulation.

getMouseListener

MouseListener getMouseListener()
Returns a mouse listener that will be added to the combo box or null. If this method returns null then it will not be added to the combo box.

Returns:
a MouseListener or null

getMouseMotionListener

MouseMotionListener getMouseMotionListener()
Returns a mouse motion listener that will be added to the combo box or null. If this method returns null then it will not be added to the combo box.

Returns:
a MouseMotionListener or null

getKeyListener

KeyListener getKeyListener()
Returns a key listener that will be added to the combo box or null. If this method returns null then it will not be added to the combo box.

uninstallingUI

void uninstallingUI()
Called to inform the ComboPopup that the UI is uninstalling. If the ComboPopup added any listeners in the component, it should remove them here.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultMenuLayout

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.basic
Class DefaultMenuLayout

java.lang.Object
    extended by  javax.swing.BoxLayout
        extended by  javax.swing.plaf.basic.DefaultMenuLayout
All Implemented Interfaces:
LayoutManager, LayoutManager2, Serializable, UIResource
public class DefaultMenuLayout
extends BoxLayout
implements UIResource

The default layout manager for Popup menus and menubars. This class is an extension of BoxLayout which adds the UIResource tag so that plauggable L&Fs can distinguish it from user-installed layout managers on menus.

Field Summary
Fields inherited from class javax.swing.BoxLayout
LINE_AXIS, PAGE_AXIS, X_AXIS, Y_AXIS
Constructor Summary
DefaultMenuLayout(Container target, int axis)
Method Summary
 Dimension preferredLayoutSize(Container target)
Returns the preferred dimensions for this layout, given the components in the specified target container.
Methods inherited from class javax.swing.BoxLayout
addLayoutComponent, addLayoutComponent, getAxis, getLayoutAlignmentX, getLayoutAlignmentY, getTarget, invalidateLayout, layoutContainer, maximumLayoutSize, minimumLayoutSize, removeLayoutComponent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultMenuLayout

public DefaultMenuLayout(Container target,
                         int axis)
Method Detail

preferredLayoutSize

public Dimension preferredLayoutSize(Container target)
Description copied from class: BoxLayout
Returns the preferred dimensions for this layout, given the components in the specified target container.

Specified by:
preferredLayoutSize in interface LayoutManager
Overrides:
preferredLayoutSize in class BoxLayout
Parameters:
target - the container that needs to be laid out
Returns:
the dimensions >= 0 && <= Integer.MAX_VALUESee Also:
Container, BoxLayout.minimumLayoutSize(java.awt.Container), BoxLayout.maximumLayoutSize(java.awt.Container)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


BorderUIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class BorderUIResource

java.lang.Object
    extended by  javax.swing.plaf.BorderUIResource
All Implemented Interfaces:
Serializable, Border, UIResource
public class BorderUIResource
extends Object
implements Border, UIResource, Serializable

Nested Class Summary
static class | BorderUIResource.BevelBorderUIResource
static class | BorderUIResource.CompoundBorderUIResource
static class | BorderUIResource.EmptyBorderUIResource
static class | BorderUIResource.EtchedBorderUIResource
static class | BorderUIResource.LineBorderUIResource
static class | BorderUIResource.MatteBorderUIResource
static class | BorderUIResource.TitledBorderUIResource
Constructor Summary
BorderUIResource(Border delegate)
Creates a UIResource border object which wraps an existing Border instance.
Method Summary
static Border | getBlackLineBorderUIResource()
Insets | getBorderInsets(Component c) Returns the insets of the border.
static Border | getEtchedBorderUIResource()
static Border | getLoweredBevelBorderUIResource()
static Border | getRaisedBevelBorderUIResource()
boolean | isBorderOpaque() Returns whether or not the border is opaque.
void | paintBorder(Component c, Graphics g, int x, int y, int width, int height) Paints the border for the specified component with the specified position and size.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BorderUIResource

public BorderUIResource(Border delegate)
Creates a UIResource border object which wraps an existing Border instance.

Parameters:
delegate - the border being wrapped
Method Detail

getEtchedBorderUIResource

public static Border getEtchedBorderUIResource()

getLoweredBevelBorderUIResource

public static Border getLoweredBevelBorderUIResource()

getRaisedBevelBorderUIResource

public static Border getRaisedBevelBorderUIResource()

getBlackLineBorderUIResource

public static Border getBlackLineBorderUIResource()

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int width,
                        int height)
Description copied from interface: Border
Paints the border for the specified component with the specified position and size.

Specified by:
paintBorder in interface Border
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
width - the width of the painted border
height - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from interface: Border
Returns the insets of the border.

Specified by:
getBorderInsets in interface Border
Parameters:
c - the component for which this border insets value applies

isBorderOpaque

public boolean isBorderOpaque()
Description copied from interface: Border
Returns whether or not the border is opaque. If the border is opaque, it is responsible for filling in it's own background when painting.

Specified by:
isBorderOpaque in interface Border
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BorderUIResource.BevelBorderUIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class BorderUIResource.BevelBorderUIResource

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.border.BevelBorder
            extended by  javax.swing.plaf.BorderUIResource.BevelBorderUIResource
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
BorderUIResource
public static class BorderUIResource.BevelBorderUIResource
extends BevelBorder
implements UIResource

Field Summary
Fields inherited from class javax.swing.border.BevelBorder
bevelType, highlightInner, highlightOuter, LOWERED, RAISED, shadowInner, shadowOuter
Constructor Summary
BorderUIResource.BevelBorderUIResource(int bevelType)
BorderUIResource.BevelBorderUIResource(int bevelType, Color highlight, Color shadow)
BorderUIResource.BevelBorderUIResource(int bevelType, Color highlightOuter, Color highlightInner, Color shadowOuter, Color shadowInner)
Method Summary
Methods inherited from class javax.swing.border.BevelBorder
getBevelType, getBorderInsets, getBorderInsets, getHighlightInnerColor, getHighlightInnerColor, getHighlightOuterColor, getHighlightOuterColor, getShadowInnerColor, getShadowInnerColor, getShadowOuterColor, getShadowOuterColor, isBorderOpaque, paintBorder, paintLoweredBevel, paintRaisedBevel
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BorderUIResource.BevelBorderUIResource

public BorderUIResource.BevelBorderUIResource(int bevelType)

BorderUIResource.BevelBorderUIResource

public BorderUIResource.BevelBorderUIResource(int bevelType,
                                              Color highlight,
                                              Color shadow)

BorderUIResource.BevelBorderUIResource

public BorderUIResource.BevelBorderUIResource(int bevelType,
                                              Color highlightOuter,
                                              Color highlightInner,
                                              Color shadowOuter,
                                              Color shadowInner)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BorderUIResource.CompoundBorderUIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class BorderUIResource.CompoundBorderUIResource

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.border.CompoundBorder
            extended by  javax.swing.plaf.BorderUIResource.CompoundBorderUIResource
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
BorderUIResource
public static class BorderUIResource.CompoundBorderUIResource
extends CompoundBorder
implements UIResource

Field Summary
Fields inherited from class javax.swing.border.CompoundBorder
insideBorder, outsideBorder
Constructor Summary
BorderUIResource.CompoundBorderUIResource(Border outsideBorder, Border insideBorder)
Method Summary
Methods inherited from class javax.swing.border.CompoundBorder
getBorderInsets, getBorderInsets, getInsideBorder, getOutsideBorder, isBorderOpaque, paintBorder
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BorderUIResource.CompoundBorderUIResource

public BorderUIResource.CompoundBorderUIResource(Border outsideBorder,
                                                 Border insideBorder)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BorderUIResource.EmptyBorderUIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class BorderUIResource.EmptyBorderUIResource

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.border.EmptyBorder
            extended by  javax.swing.plaf.BorderUIResource.EmptyBorderUIResource
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
BorderUIResource
public static class BorderUIResource.EmptyBorderUIResource
extends EmptyBorder
implements UIResource

Field Summary
Fields inherited from class javax.swing.border.EmptyBorder
bottom, left, right, top
Constructor Summary
BorderUIResource.EmptyBorderUIResource(Insets insets)
BorderUIResource.EmptyBorderUIResource(int top, int left, int bottom, int right)
Method Summary
Methods inherited from class javax.swing.border.EmptyBorder
getBorderInsets, getBorderInsets, getBorderInsets, isBorderOpaque, paintBorder
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BorderUIResource.EmptyBorderUIResource

public BorderUIResource.EmptyBorderUIResource(int top,
                                              int left,
                                              int bottom,
                                              int right)

BorderUIResource.EmptyBorderUIResource

public BorderUIResource.EmptyBorderUIResource(Insets insets)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BorderUIResource.EtchedBorderUIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class BorderUIResource.EtchedBorderUIResource

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.border.EtchedBorder
            extended by  javax.swing.plaf.BorderUIResource.EtchedBorderUIResource
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
BorderUIResource
public static class BorderUIResource.EtchedBorderUIResource
extends EtchedBorder
implements UIResource

Field Summary
Fields inherited from class javax.swing.border.EtchedBorder
etchType, highlight, LOWERED, RAISED, shadow
Constructor Summary
BorderUIResource.EtchedBorderUIResource()
BorderUIResource.EtchedBorderUIResource(Color highlight, Color shadow)
BorderUIResource.EtchedBorderUIResource(int etchType)
BorderUIResource.EtchedBorderUIResource(int etchType, Color highlight, Color shadow)
Method Summary
Methods inherited from class javax.swing.border.EtchedBorder
getBorderInsets, getBorderInsets, getEtchType, getHighlightColor, getHighlightColor, getShadowColor, getShadowColor, isBorderOpaque, paintBorder
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BorderUIResource.EtchedBorderUIResource

public BorderUIResource.EtchedBorderUIResource()

BorderUIResource.EtchedBorderUIResource

public BorderUIResource.EtchedBorderUIResource(int etchType)

BorderUIResource.EtchedBorderUIResource

public BorderUIResource.EtchedBorderUIResource(Color highlight,
                                               Color shadow)

BorderUIResource.EtchedBorderUIResource

public BorderUIResource.EtchedBorderUIResource(int etchType,
                                               Color highlight,
                                               Color shadow)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BorderUIResource.LineBorderUIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class BorderUIResource.LineBorderUIResource

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.border.LineBorder
            extended by  javax.swing.plaf.BorderUIResource.LineBorderUIResource
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
BorderUIResource
public static class BorderUIResource.LineBorderUIResource
extends LineBorder
implements UIResource

Field Summary
Fields inherited from class javax.swing.border.LineBorder
lineColor, roundedCorners, thickness
Constructor Summary
BorderUIResource.LineBorderUIResource(Color color)
BorderUIResource.LineBorderUIResource(Color color, int thickness)
Method Summary
Methods inherited from class javax.swing.border.LineBorder
createBlackLineBorder, createGrayLineBorder, getBorderInsets, getBorderInsets, getLineColor, getRoundedCorners, getThickness, isBorderOpaque, paintBorder
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BorderUIResource.LineBorderUIResource

public BorderUIResource.LineBorderUIResource(Color color)

BorderUIResource.LineBorderUIResource

public BorderUIResource.LineBorderUIResource(Color color,
                                             int thickness)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BorderUIResource.MatteBorderUIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class BorderUIResource.MatteBorderUIResource

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.border.EmptyBorder
            extended by  javax.swing.border.MatteBorder
                extended by  javax.swing.plaf.BorderUIResource.MatteBorderUIResource
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
BorderUIResource
public static class BorderUIResource.MatteBorderUIResource
extends MatteBorder
implements UIResource

Field Summary
Fields inherited from class javax.swing.border.MatteBorder
color, tileIcon
Fields inherited from class javax.swing.border.EmptyBorder
bottom, left, right, top
Constructor Summary
BorderUIResource.MatteBorderUIResource(Icon tileIcon)
BorderUIResource.MatteBorderUIResource(int top, int left, int bottom, int right, Color color)
BorderUIResource.MatteBorderUIResource(int top, int left, int bottom, int right, Icon tileIcon)
Method Summary
Methods inherited from class javax.swing.border.MatteBorder
getBorderInsets, getBorderInsets, getBorderInsets, getMatteColor, getTileIcon, isBorderOpaque, paintBorder
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BorderUIResource.MatteBorderUIResource

public BorderUIResource.MatteBorderUIResource(int top,
                                              int left,
                                              int bottom,
                                              int right,
                                              Color color)

BorderUIResource.MatteBorderUIResource

public BorderUIResource.MatteBorderUIResource(int top,
                                              int left,
                                              int bottom,
                                              int right,
                                              Icon tileIcon)

BorderUIResource.MatteBorderUIResource

public BorderUIResource.MatteBorderUIResource(Icon tileIcon)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BorderUIResource.TitledBorderUIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class BorderUIResource.TitledBorderUIResource

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.border.TitledBorder
            extended by  javax.swing.plaf.BorderUIResource.TitledBorderUIResource
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
BorderUIResource
public static class BorderUIResource.TitledBorderUIResource
extends TitledBorder
implements UIResource

Field Summary
Fields inherited from class javax.swing.border.TitledBorder
ABOVE_BOTTOM, ABOVE_TOP, BELOW_BOTTOM, BELOW_TOP, border, BOTTOM, CENTER, DEFAULT_JUSTIFICATION, DEFAULT_POSITION, EDGE_SPACING, LEADING, LEFT, RIGHT, TEXT_INSET_H, TEXT_SPACING, title, titleColor, titleFont, titleJustification, titlePosition, TOP, TRAILING
Constructor Summary
BorderUIResource.TitledBorderUIResource(Border border)
BorderUIResource.TitledBorderUIResource(Border border, String title)
BorderUIResource.TitledBorderUIResource(Border border, String title, int titleJustification, int titlePosition)
BorderUIResource.TitledBorderUIResource(Border border, String title, int titleJustification, int titlePosition, Font titleFont)
BorderUIResource.TitledBorderUIResource(Border border, String title, int titleJustification, int titlePosition, Font titleFont, Color titleColor)
BorderUIResource.TitledBorderUIResource(String title)
Method Summary
Methods inherited from class javax.swing.border.TitledBorder
getBaseline, getBaselineResizeBehavior, getBorder, getBorderInsets, getBorderInsets, getFont, getMinimumSize, getTitle, getTitleColor, getTitleFont, getTitleJustification, getTitlePosition, isBorderOpaque, paintBorder, setBorder, setTitle, setTitleColor, setTitleFont, setTitleJustification, setTitlePosition
Methods inherited from class javax.swing.border.AbstractBorder
getInteriorRectangle, getInteriorRectangle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BorderUIResource.TitledBorderUIResource

public BorderUIResource.TitledBorderUIResource(String title)

BorderUIResource.TitledBorderUIResource

public BorderUIResource.TitledBorderUIResource(Border border)

BorderUIResource.TitledBorderUIResource

public BorderUIResource.TitledBorderUIResource(Border border,
                                               String title)

BorderUIResource.TitledBorderUIResource

public BorderUIResource.TitledBorderUIResource(Border border,
                                               String title,
                                               int titleJustification,
                                               int titlePosition)

BorderUIResource.TitledBorderUIResource

public BorderUIResource.TitledBorderUIResource(Border border,
                                               String title,
                                               int titleJustification,
                                               int titlePosition,
                                               Font titleFont)

BorderUIResource.TitledBorderUIResource

public BorderUIResource.TitledBorderUIResource(Border border,
                                               String title,
                                               int titleJustification,
                                               int titlePosition,
                                               Font titleFont,
                                               Color titleColor)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ButtonUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class ButtonUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ButtonUI
Direct Known Subclasses:
BasicButtonUI, MenuItemUI, MultiButtonUI
public abstract class ButtonUI
extends ComponentUI

Pluggable look and feel interface for JButton.

Constructor Summary
ButtonUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ButtonUI

public ButtonUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.swing.plaf.ActionMapUIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.ActionMapUIResource

No usage of javax.swing.plaf.ActionMapUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.BorderUIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.BorderUIResource

No usage of javax.swing.plaf.BorderUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.BorderUIResource.BevelBorderUIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.BorderUIResource.BevelBorderUIResource

No usage of javax.swing.plaf.BorderUIResource.BevelBorderUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.BorderUIResource.CompoundBorderUIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.BorderUIResource.CompoundBorderUIResource

No usage of javax.swing.plaf.BorderUIResource.CompoundBorderUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.BorderUIResource.EmptyBorderUIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.BorderUIResource.EmptyBorderUIResource

No usage of javax.swing.plaf.BorderUIResource.EmptyBorderUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.BorderUIResource.EtchedBorderUIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.BorderUIResource.EtchedBorderUIResource

No usage of javax.swing.plaf.BorderUIResource.EtchedBorderUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.BorderUIResource.LineBorderUIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.BorderUIResource.LineBorderUIResource

No usage of javax.swing.plaf.BorderUIResource.LineBorderUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.BorderUIResource.MatteBorderUIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.BorderUIResource.MatteBorderUIResource

No usage of javax.swing.plaf.BorderUIResource.MatteBorderUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.BorderUIResource.TitledBorderUIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.BorderUIResource.TitledBorderUIResource

No usage of javax.swing.plaf.BorderUIResource.TitledBorderUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.ButtonUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.ButtonUI

Packages that use ButtonUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of ButtonUI in javax.swing

Methods in javax.swing that return ButtonUI
 ButtonUI AbstractButton.getUI()
Returns the L&F object that renders this component.

Methods in javax.swing with parameters of type ButtonUI
 void AbstractButton.setUI(ButtonUI ui)
Sets the L&F object that renders this component.

Uses of ButtonUI in javax.swing.plaf

Subclasses of ButtonUI in javax.swing.plaf
 class MenuItemUI
Pluggable look and feel interface for JMenuItem.

Uses of ButtonUI in javax.swing.plaf.basic

Subclasses of ButtonUI in javax.swing.plaf.basic
class | BasicButtonUI BasicButton implementation
class | BasicCheckBoxMenuItemUI BasicCheckboxMenuItem implementation
class | BasicCheckBoxUI CheckboxUI implementation for BasicCheckboxUI
class | BasicMenuItemUI BasicMenuItem implementation
class | BasicMenuUI A default L&F implementation of MenuUI.
class | BasicRadioButtonMenuItemUI BasicRadioButtonMenuItem implementation
class | BasicRadioButtonUI RadioButtonUI implementation for BasicRadioButtonUI
class | BasicToggleButtonUI BasicToggleButton implementation

Uses of ButtonUI in javax.swing.plaf.metal

Subclasses of ButtonUI in javax.swing.plaf.metal
class | MetalButtonUI MetalButtonUI implementation
class | MetalCheckBoxUI CheckboxUI implementation for MetalCheckboxUI
class | MetalRadioButtonUI RadioButtonUI implementation for MetalRadioButtonUI
class | MetalToggleButtonUI MetalToggleButton implementation

Uses of ButtonUI in javax.swing.plaf.multi

Subclasses of ButtonUI in javax.swing.plaf.multi
class | MultiButtonUI A multiplexing UI used to combine ButtonUIs.
class | MultiMenuItemUI A multiplexing UI used to combine MenuItemUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.ColorChooserUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.ColorChooserUI

Packages that use ColorChooserUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of ColorChooserUI in javax.swing

Methods in javax.swing that return ColorChooserUI
 ColorChooserUI JColorChooser.getUI()
Returns the L&F object that renders this component.

Methods in javax.swing with parameters of type ColorChooserUI
 void JColorChooser.setUI(ColorChooserUI ui)
Sets the L&F object that renders this component.

Uses of ColorChooserUI in javax.swing.plaf.basic

Subclasses of ColorChooserUI in javax.swing.plaf.basic
 class BasicColorChooserUI
Provides the basic look and feel for a JColorChooser.

Uses of ColorChooserUI in javax.swing.plaf.multi

Subclasses of ColorChooserUI in javax.swing.plaf.multi
 class MultiColorChooserUI
A multiplexing UI used to combine ColorChooserUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.ColorUIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.ColorUIResource

Packages that use ColorUIResource
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of ColorUIResource in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal that return ColorUIResource
static ColorUIResource | MetalLookAndFeel.getAcceleratorForeground() Returns the accelerator foreground color of the current theme.
ColorUIResource | MetalTheme.getAcceleratorForeground() Returns the accelerator foreground color.
static ColorUIResource | MetalLookAndFeel.getAcceleratorSelectedForeground() Returns the accelerator selected foreground color of the current theme.
ColorUIResource | MetalTheme.getAcceleratorSelectedForeground() Returns the accelerator selected foreground color.
protected ColorUIResource | OceanTheme.getBlack() Returns the black color.
static ColorUIResource | MetalLookAndFeel.getBlack() Returns the black color of the current theme.
protected ColorUIResource | MetalTheme.getBlack() Returns the black color.
static ColorUIResource | MetalLookAndFeel.getControl() Returns the control color of the current theme.
ColorUIResource | MetalTheme.getControl() Returns the control color.
static ColorUIResource | MetalLookAndFeel.getControlDarkShadow() Returns the control dark shadow color of the current theme.
ColorUIResource | MetalTheme.getControlDarkShadow() Returns the control dark shadow color.
static ColorUIResource | MetalLookAndFeel.getControlDisabled() Returns the control disabled color of the current theme.
ColorUIResource | MetalTheme.getControlDisabled() Returns the control disabled color.
static ColorUIResource | MetalLookAndFeel.getControlHighlight() Returns the control highlight color of the current theme.
ColorUIResource | MetalTheme.getControlHighlight() Returns the control highlight color.
static ColorUIResource | MetalLookAndFeel.getControlInfo() Returns the control info color of the current theme.
ColorUIResource | MetalTheme.getControlInfo() Returns the control info color.
static ColorUIResource | MetalLookAndFeel.getControlShadow() Returns the control shadow color of the current theme.
ColorUIResource | MetalTheme.getControlShadow() Returns the control shadow color.
ColorUIResource | OceanTheme.getControlTextColor() Returns the control text color.
static ColorUIResource | MetalLookAndFeel.getControlTextColor() Returns the control text color of the current theme.
ColorUIResource | MetalTheme.getControlTextColor() Returns the control text color.
ColorUIResource | OceanTheme.getDesktopColor() Returns the desktop color.
static ColorUIResource | MetalLookAndFeel.getDesktopColor() Returns the desktop color of the current theme.
ColorUIResource | MetalTheme.getDesktopColor() Returns the desktop color.
static ColorUIResource | MetalLookAndFeel.getFocusColor() Returns the focus color of the current theme.
ColorUIResource | MetalTheme.getFocusColor() Returns the focus color.
static ColorUIResource | MetalLookAndFeel.getHighlightedTextColor() Returns the highlighted text color of the current theme.
ColorUIResource | MetalTheme.getHighlightedTextColor() Returns the highlighted text color.
ColorUIResource | OceanTheme.getInactiveControlTextColor() Returns the inactive control text color.
static ColorUIResource | MetalLookAndFeel.getInactiveControlTextColor() Returns the inactive control text color of the current theme.
ColorUIResource | MetalTheme.getInactiveControlTextColor() Returns the inactive control text color.
static ColorUIResource | MetalLookAndFeel.getInactiveSystemTextColor() Returns the inactive system text color of the current theme.
ColorUIResource | MetalTheme.getInactiveSystemTextColor() Returns the inactive system text color.
static ColorUIResource | MetalLookAndFeel.getMenuBackground() Returns the menu background color of the current theme.
ColorUIResource | MetalTheme.getMenuBackground() Returns the menu background color.
ColorUIResource | OceanTheme.getMenuDisabledForeground() Returns the menu disabled foreground color.
static ColorUIResource | MetalLookAndFeel.getMenuDisabledForeground() Returns the menu disabled foreground color of the current theme.
ColorUIResource | MetalTheme.getMenuDisabledForeground() Returns the menu disabled foreground color.
static ColorUIResource | MetalLookAndFeel.getMenuForeground() Returns the menu foreground color of the current theme.
ColorUIResource | MetalTheme.getMenuForeground() Returns the menu foreground color.
static ColorUIResource | MetalLookAndFeel.getMenuSelectedBackground() Returns the menu selected background color of the current theme.
ColorUIResource | MetalTheme.getMenuSelectedBackground() Returns the menu selected background color.
static ColorUIResource | MetalLookAndFeel.getMenuSelectedForeground() Returns the menu selected foreground color of the current theme.
ColorUIResource | MetalTheme.getMenuSelectedForeground() Returns the menu selected foreground color.
protected ColorUIResource | OceanTheme.getPrimary1() Returns the primary 1 color.
protected ColorUIResource | DefaultMetalTheme.getPrimary1() Returns the primary 1 color.
protected abstract ColorUIResource | MetalTheme.getPrimary1() Returns the primary 1 color.
protected ColorUIResource | OceanTheme.getPrimary2() Returns the primary 2 color.
protected ColorUIResource | DefaultMetalTheme.getPrimary2() Returns the primary 2 color.
protected abstract ColorUIResource | MetalTheme.getPrimary2() Returns the primary 2 color.
protected ColorUIResource | OceanTheme.getPrimary3() Returns the primary 3 color.
protected ColorUIResource | DefaultMetalTheme.getPrimary3() Returns the primary 3 color.
protected abstract ColorUIResource | MetalTheme.getPrimary3() Returns the primary 3 color.
static ColorUIResource | MetalLookAndFeel.getPrimaryControl() Returns the primary control color of the current theme.
ColorUIResource | MetalTheme.getPrimaryControl() Returns the primary control color.
static ColorUIResource | MetalLookAndFeel.getPrimaryControlDarkShadow() Returns the primary control dark shadow color of the current theme.
ColorUIResource | MetalTheme.getPrimaryControlDarkShadow() Returns the primary control dark shadow color.
static ColorUIResource | MetalLookAndFeel.getPrimaryControlHighlight() Returns the primary control highlight color of the current theme.
ColorUIResource | MetalTheme.getPrimaryControlHighlight() Returns the primary control highlight color.
static ColorUIResource | MetalLookAndFeel.getPrimaryControlInfo() Returns the primary control info color of the current theme.
ColorUIResource | MetalTheme.getPrimaryControlInfo() Returns the primary control info color.
static ColorUIResource | MetalLookAndFeel.getPrimaryControlShadow() Returns the primary control shadow color of the current theme.
ColorUIResource | MetalTheme.getPrimaryControlShadow() Returns the primary control shadow color.
protected ColorUIResource | OceanTheme.getSecondary1() Returns the secondary 1 color.
protected ColorUIResource | DefaultMetalTheme.getSecondary1() Returns the secondary 1 color.
protected abstract ColorUIResource | MetalTheme.getSecondary1() Returns the secondary 1 color.
protected ColorUIResource | OceanTheme.getSecondary2() Returns the secondary 2 color.
protected ColorUIResource | DefaultMetalTheme.getSecondary2() Returns the secondary 2 color.
protected abstract ColorUIResource | MetalTheme.getSecondary2() Returns the secondary 2 color.
protected ColorUIResource | OceanTheme.getSecondary3() Returns the secondary 3 color.
protected ColorUIResource | DefaultMetalTheme.getSecondary3() Returns the secondary 3 color.
protected abstract ColorUIResource | MetalTheme.getSecondary3() Returns the secondary 3 color.
static ColorUIResource | MetalLookAndFeel.getSeparatorBackground() Returns the separator background color of the current theme.
ColorUIResource | MetalTheme.getSeparatorBackground() Returns the separator background color.
static ColorUIResource | MetalLookAndFeel.getSeparatorForeground() Returns the separator foreground color of the current theme.
ColorUIResource | MetalTheme.getSeparatorForeground() Returns the separator foreground color.
static ColorUIResource | MetalLookAndFeel.getSystemTextColor() Returns the system text color of the current theme.
ColorUIResource | MetalTheme.getSystemTextColor() Returns the system text color.
static ColorUIResource | MetalLookAndFeel.getTextHighlightColor() Returns the text highlight color of the current theme.
ColorUIResource | MetalTheme.getTextHighlightColor() Returns the text highlight color.
static ColorUIResource | MetalLookAndFeel.getUserTextColor() Returns the user text color of the current theme.
ColorUIResource | MetalTheme.getUserTextColor() Returns the user text color.
static ColorUIResource | MetalLookAndFeel.getWhite() Returns the white color of the current theme.
protected ColorUIResource | MetalTheme.getWhite() Returns the white color.
static ColorUIResource | MetalLookAndFeel.getWindowBackground() Returns the window background color of the current theme.
ColorUIResource | MetalTheme.getWindowBackground() Returns the window background color.
static ColorUIResource | MetalLookAndFeel.getWindowTitleBackground() Returns the window title background color of the current theme.
ColorUIResource | MetalTheme.getWindowTitleBackground() Returns the window title background color.
static ColorUIResource | MetalLookAndFeel.getWindowTitleForeground() Returns the window title foreground color of the current theme.
ColorUIResource | MetalTheme.getWindowTitleForeground() Returns the window title foreground color.
static ColorUIResource | MetalLookAndFeel.getWindowTitleInactiveBackground() Returns the window title inactive background color of the current theme.
ColorUIResource | MetalTheme.getWindowTitleInactiveBackground() Returns the window title inactive background color.
static ColorUIResource | MetalLookAndFeel.getWindowTitleInactiveForeground() Returns the window title inactive foreground color of the current theme.
ColorUIResource | MetalTheme.getWindowTitleInactiveForeground() Returns the window title inactive foreground color.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.ComboBoxUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.ComboBoxUI

Packages that use ComboBoxUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of ComboBoxUI in javax.swing

Methods in javax.swing that return ComboBoxUI
 ComboBoxUI JComboBox.getUI()
Returns the L&F object that renders this component.

Methods in javax.swing with parameters of type ComboBoxUI
 void JComboBox.setUI(ComboBoxUI ui)
Sets the L&F object that renders this component.

Uses of ComboBoxUI in javax.swing.plaf.basic

Subclasses of ComboBoxUI in javax.swing.plaf.basic
 class BasicComboBoxUI
Basic UI implementation for JComboBox.

Uses of ComboBoxUI in javax.swing.plaf.metal

Subclasses of ComboBoxUI in javax.swing.plaf.metal
 class MetalComboBoxUI
Metal UI for JComboBox

Uses of ComboBoxUI in javax.swing.plaf.multi

Subclasses of ComboBoxUI in javax.swing.plaf.multi
 class MultiComboBoxUI
A multiplexing UI used to combine ComboBoxUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.ComponentInputMapUIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.ComponentInputMapUIResource

No usage of javax.swing.plaf.ComponentInputMapUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.ComponentUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.ComponentUI

Packages that use ComponentUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.
javax.swing.plaf.synth | Synth is a skinnable look and feel in which all painting is delegated.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of ComponentUI in javax.swing

Fields in javax.swing declared as ComponentUI
protected  ComponentUI JComponent.ui
The look and feel delegate for this component.

Methods in javax.swing that return ComponentUI
ComponentUI | UIDefaults.getUI(JComponent target) Creates an ComponentUI implementation for the specified component.
static ComponentUI | UIManager.getUI(JComponent target) Returns the appropriate ComponentUI implementation for target.

Methods in javax.swing that return types with arguments of type ComponentUI
Class<? extends ComponentUI> | UIDefaults.getUIClass(String uiClassID) Returns the L&F class that renders this component.
Class<? extends ComponentUI> | UIDefaults.getUIClass(String uiClassID, ClassLoader uiClassLoader) The value of get(uidClassID) must be the String name of a class that implements the corresponding ComponentUI class.

Methods in javax.swing with parameters of type ComponentUI
protected  void JComponent.setUI(ComponentUI newUI)
Sets the look and feel delegate for this component.

Uses of ComponentUI in javax.swing.plaf

Subclasses of ComponentUI in javax.swing.plaf
class | ButtonUI Pluggable look and feel interface for JButton.
class | ColorChooserUI Pluggable look and feel interface for JColorChooser.
class | ComboBoxUI Pluggable look and feel interface for JComboBox.
class | DesktopIconUI Pluggable look and feel interface for JDesktopIcon.
class | DesktopPaneUI Pluggable look and feel interface for JDesktopPane.
class | FileChooserUI Pluggable look and feel interface for JFileChooser.
class | InternalFrameUI Pluggable look and feel interface for JInternalFrame.
class | LabelUI Pluggable look and feel interface for JLabel.
class | ListUI The JList pluggable look and feel delegate.
class | MenuBarUI Pluggable look and feel interface for JMenuBar.
class | MenuItemUI Pluggable look and feel interface for JMenuItem.
class | OptionPaneUI Pluggable look and feel interface for JOptionPane.
class | PanelUI Pluggable look and feel interface for Panel.
class | PopupMenuUI Pluggable look and feel interface for JPopupMenu.
class | ProgressBarUI Pluggable look and feel interface for JProgressBar.
class | RootPaneUI Pluggable look and feel interface for JRootPane.
class | ScrollBarUI Pluggable look and feel interface for JScrollBar.
class | ScrollPaneUI Pluggable look and feel interface for JScrollPane.
class | SeparatorUI Pluggable look and feel interface for JSeparator.
class | SliderUI Pluggable look and feel interface for JSlider.
class | SpinnerUI Pluggable look and feel interface for JSpinner
class | SplitPaneUI Pluggable look and feel interface for JSplitPane.
class | TabbedPaneUI Pluggable look and feel interface for JTabbedPane.
class | TableHeaderUI Pluggable look and feel interface for JTableHeader.
class | TableUI Pluggable look and feel interface for JTable.
class | TextUI Text editor user interface
class | ToolBarUI Pluggable look and feel interface for JToolBar.
class | ToolTipUI Pluggable look and feel interface for JToolTip.
class | TreeUI Pluggable look and feel interface for JTree.
class | ViewportUI Pluggable look and feel interface for JViewport.

Methods in javax.swing.plaf that return ComponentUI
static ComponentUI ComponentUI.createUI(JComponent c)
Returns an instance of the UI delegate for the specified component.

Uses of ComponentUI in javax.swing.plaf.basic

Subclasses of ComponentUI in javax.swing.plaf.basic
class | BasicButtonUI BasicButton implementation
class | BasicCheckBoxMenuItemUI BasicCheckboxMenuItem implementation
class | BasicCheckBoxUI CheckboxUI implementation for BasicCheckboxUI
class | BasicColorChooserUI Provides the basic look and feel for a JColorChooser.
class | BasicComboBoxUI Basic UI implementation for JComboBox.
class | BasicDesktopIconUI Basic L&F for a minimized window on a desktop.
class | BasicDesktopPaneUI Basic L&F for a desktop.
class | BasicEditorPaneUI Provides the look and feel for a JEditorPane.
class | BasicFileChooserUI Basic L&F implementation of a FileChooser.
class | BasicFormattedTextFieldUI Provides the look and feel implementation for JFormattedTextField.
class | BasicInternalFrameUI A basic L&F implementation of JInternalFrame.
class | BasicLabelUI A Windows L&F implementation of LabelUI.
class | BasicListUI An extensible implementation of ListUI.
class | BasicMenuBarUI A default L&F implementation of MenuBarUI.
class | BasicMenuItemUI BasicMenuItem implementation
class | BasicMenuUI A default L&F implementation of MenuUI.
class | BasicOptionPaneUI Provides the basic look and feel for a JOptionPane.
class | BasicPanelUI BasicPanel implementation
class | BasicPasswordFieldUI Provides the Windows look and feel for a password field.
class | BasicPopupMenuSeparatorUI A Basic L&F implementation of PopupMenuSeparatorUI.
class | BasicPopupMenuUI A Windows L&F implementation of PopupMenuUI.
class | BasicProgressBarUI A Basic L&F implementation of ProgressBarUI.
class | BasicRadioButtonMenuItemUI BasicRadioButtonMenuItem implementation
class | BasicRadioButtonUI RadioButtonUI implementation for BasicRadioButtonUI
class | BasicRootPaneUI Basic implementation of RootPaneUI, there is one shared between all JRootPane instances.
class | BasicScrollBarUI Implementation of ScrollBarUI for the Basic Look and Feel
class | BasicScrollPaneUI A default L&F implementation of ScrollPaneUI.
class | BasicSeparatorUI A Basic L&F implementation of SeparatorUI.
class | BasicSliderUI A Basic L&F implementation of SliderUI.
class | BasicSpinnerUI The default Spinner UI delegate.
class | BasicSplitPaneUI A Basic L&F implementation of the SplitPaneUI.
class | BasicTabbedPaneUI A Basic L&F implementation of TabbedPaneUI.
class | BasicTableHeaderUI BasicTableHeaderUI implementation
class | BasicTableUI BasicTableUI implementation
class | BasicTextAreaUI Provides the look and feel for a plain text editor.
class | BasicTextFieldUI Basis of a look and feel for a JTextField.
class | BasicTextPaneUI Provides the look and feel for a styled text editor.
class | BasicTextUI Basis of a text components look-and-feel.
class | BasicToggleButtonUI BasicToggleButton implementation
class | BasicToolBarSeparatorUI A Basic L&F implementation of ToolBarSeparatorUI.
class | BasicToolBarUI A Basic L&F implementation of ToolBarUI.
class | BasicToolTipUI Standard tool tip L&F.
class | BasicTreeUI The basic L&F for a hierarchical data structure.
class | BasicViewportUI BasicViewport implementation

Methods in javax.swing.plaf.basic that return ComponentUI
static ComponentUI | BasicPopupMenuSeparatorUI.createUI(JComponent c)
static ComponentUI | BasicRadioButtonUI.createUI(JComponent b)
static ComponentUI | BasicCheckBoxUI.createUI(JComponent b)
static ComponentUI | BasicViewportUI.createUI(JComponent c)
static ComponentUI | BasicToolBarSeparatorUI.createUI(JComponent c)
static ComponentUI | BasicRadioButtonMenuItemUI.createUI(JComponent b)
static ComponentUI | BasicSeparatorUI.createUI(JComponent c)
static ComponentUI | BasicPasswordFieldUI.createUI(JComponent c) Creates a UI for a JPasswordField.
static ComponentUI | BasicFormattedTextFieldUI.createUI(JComponent c) Creates a UI for a JFormattedTextField.
static ComponentUI | BasicToggleButtonUI.createUI(JComponent b)
static ComponentUI | BasicCheckBoxMenuItemUI.createUI(JComponent c)
static ComponentUI | BasicTextPaneUI.createUI(JComponent c) Creates a UI for the JTextPane.
static ComponentUI | BasicToolTipUI.createUI(JComponent c)
static ComponentUI | BasicToolBarUI.createUI(JComponent c)
static ComponentUI | BasicTextAreaUI.createUI(JComponent ta) Creates a UI for a JTextArea.
static ComponentUI | BasicTableHeaderUI.createUI(JComponent h)
static ComponentUI | BasicTableUI.createUI(JComponent c)
static ComponentUI | BasicTabbedPaneUI.createUI(JComponent c)
static ComponentUI | BasicSpinnerUI.createUI(JComponent c) Returns a new instance of BasicSpinnerUI.
static ComponentUI | BasicSliderUI.createUI(JComponent b)
static ComponentUI | BasicScrollPaneUI.createUI(JComponent x)
static ComponentUI | BasicScrollBarUI.createUI(JComponent c)
static ComponentUI | BasicProgressBarUI.createUI(JComponent x)
static ComponentUI | BasicPanelUI.createUI(JComponent c)
static ComponentUI | BasicOptionPaneUI.createUI(JComponent x) Creates a new BasicOptionPaneUI instance.
static ComponentUI | BasicMenuUI.createUI(JComponent x)
static ComponentUI | BasicMenuBarUI.createUI(JComponent x)
static ComponentUI | BasicListUI.createUI(JComponent list) Returns a new instance of BasicListUI.
static ComponentUI | BasicLabelUI.createUI(JComponent c)
static ComponentUI | BasicInternalFrameUI.createUI(JComponent b)
static ComponentUI | BasicTextFieldUI.createUI(JComponent c) Creates a UI for a JTextField.
static ComponentUI | BasicEditorPaneUI.createUI(JComponent c) Creates a UI for the JTextPane.
static ComponentUI | BasicDesktopIconUI.createUI(JComponent c)
static ComponentUI | BasicDesktopPaneUI.createUI(JComponent c)
static ComponentUI | BasicColorChooserUI.createUI(JComponent c)
static ComponentUI | BasicButtonUI.createUI(JComponent c)
static ComponentUI | BasicTreeUI.createUI(JComponent x)
static ComponentUI | BasicRootPaneUI.createUI(JComponent c)
static ComponentUI | BasicSplitPaneUI.createUI(JComponent x) Creates a new BasicSplitPaneUI instance
static ComponentUI | BasicComboBoxUI.createUI(JComponent c)
static ComponentUI | BasicMenuItemUI.createUI(JComponent c)
static ComponentUI | BasicPopupMenuUI.createUI(JComponent x)

Uses of ComponentUI in javax.swing.plaf.metal

Subclasses of ComponentUI in javax.swing.plaf.metal
class | MetalButtonUI MetalButtonUI implementation
class | MetalCheckBoxUI CheckboxUI implementation for MetalCheckboxUI
class | MetalComboBoxUI Metal UI for JComboBox
class | MetalDesktopIconUI Metal desktop icon.
class | MetalFileChooserUI Metal L&F implementation of a FileChooser.
class | MetalInternalFrameUI Metal implementation of JInternalFrame.
class | MetalLabelUI A Windows L&F implementation of LabelUI.
class | MetalMenuBarUI Metal implementation of MenuBarUI.
class | MetalPopupMenuSeparatorUI A Metal L&F implementation of PopupMenuSeparatorUI.
class | MetalProgressBarUI The Metal implementation of ProgressBarUI.
class | MetalRadioButtonUI RadioButtonUI implementation for MetalRadioButtonUI
class | MetalRootPaneUI Provides the metal look and feel implementation of RootPaneUI.
class | MetalScrollBarUI Implementation of ScrollBarUI for the Metal Look and Feel
class | MetalScrollPaneUI A Metal L&F implementation of ScrollPaneUI.
class | MetalSeparatorUI A Metal L&F implementation of SeparatorUI.
class | MetalSliderUI A Java L&F implementation of SliderUI.
class | MetalSplitPaneUI Metal split pane.
class | MetalTabbedPaneUI The Metal subclass of BasicTabbedPaneUI.
class | MetalTextFieldUI Basis of a look and feel for a JTextField.
class | MetalToggleButtonUI MetalToggleButton implementation
class | MetalToolBarUI A Metal Look and Feel implementation of ToolBarUI.
class | MetalToolTipUI A Metal L&F extension of BasicToolTipUI.
class | MetalTreeUI The metal look and feel implementation of TreeUI.

Methods in javax.swing.plaf.metal that return ComponentUI
static ComponentUI | MetalPopupMenuSeparatorUI.createUI(JComponent c)
static ComponentUI | MetalRadioButtonUI.createUI(JComponent c)
static ComponentUI | MetalCheckBoxUI.createUI(JComponent b)
static ComponentUI | MetalTreeUI.createUI(JComponent x)
static ComponentUI | MetalToolTipUI.createUI(JComponent c)
static ComponentUI | MetalToolBarUI.createUI(JComponent c)
static ComponentUI | MetalToggleButtonUI.createUI(JComponent b)
static ComponentUI | MetalTextFieldUI.createUI(JComponent c)
static ComponentUI | MetalTabbedPaneUI.createUI(JComponent x)
static ComponentUI | MetalSplitPaneUI.createUI(JComponent x) Creates a new MetalSplitPaneUI instance
static ComponentUI | MetalSliderUI.createUI(JComponent c)
static ComponentUI | MetalScrollPaneUI.createUI(JComponent x)
static ComponentUI | MetalScrollBarUI.createUI(JComponent c)
static ComponentUI | MetalRootPaneUI.createUI(JComponent c) Creates a UI for a JRootPane.
static ComponentUI | MetalProgressBarUI.createUI(JComponent c)
static ComponentUI | MetalSeparatorUI.createUI(JComponent c)
static ComponentUI | MetalMenuBarUI.createUI(JComponent x) Creates the ComponentUI implementation for the passed in component.
static ComponentUI | MetalLabelUI.createUI(JComponent c)
static ComponentUI | MetalInternalFrameUI.createUI(JComponent c)
static ComponentUI | MetalFileChooserUI.createUI(JComponent c)
static ComponentUI | MetalDesktopIconUI.createUI(JComponent c)
static ComponentUI | MetalComboBoxUI.createUI(JComponent c)
static ComponentUI | MetalButtonUI.createUI(JComponent c)

Uses of ComponentUI in javax.swing.plaf.multi

Subclasses of ComponentUI in javax.swing.plaf.multi
class | MultiButtonUI A multiplexing UI used to combine ButtonUIs.
class | MultiColorChooserUI A multiplexing UI used to combine ColorChooserUIs.
class | MultiComboBoxUI A multiplexing UI used to combine ComboBoxUIs.
class | MultiDesktopIconUI A multiplexing UI used to combine DesktopIconUIs.
class | MultiDesktopPaneUI A multiplexing UI used to combine DesktopPaneUIs.
class | MultiFileChooserUI A multiplexing UI used to combine FileChooserUIs.
class | MultiInternalFrameUI A multiplexing UI used to combine InternalFrameUIs.
class | MultiLabelUI A multiplexing UI used to combine LabelUIs.
class | MultiListUI A multiplexing UI used to combine ListUIs.
class | MultiMenuBarUI A multiplexing UI used to combine MenuBarUIs.
class | MultiMenuItemUI A multiplexing UI used to combine MenuItemUIs.
class | MultiOptionPaneUI A multiplexing UI used to combine OptionPaneUIs.
class | MultiPanelUI A multiplexing UI used to combine PanelUIs.
class | MultiPopupMenuUI A multiplexing UI used to combine PopupMenuUIs.
class | MultiProgressBarUI A multiplexing UI used to combine ProgressBarUIs.
class | MultiRootPaneUI A multiplexing UI used to combine RootPaneUIs.
class | MultiScrollBarUI A multiplexing UI used to combine ScrollBarUIs.
class | MultiScrollPaneUI A multiplexing UI used to combine ScrollPaneUIs.
class | MultiSeparatorUI A multiplexing UI used to combine SeparatorUIs.
class | MultiSliderUI A multiplexing UI used to combine SliderUIs.
class | MultiSpinnerUI A multiplexing UI used to combine SpinnerUIs.
class | MultiSplitPaneUI A multiplexing UI used to combine SplitPaneUIs.
class | MultiTabbedPaneUI A multiplexing UI used to combine TabbedPaneUIs.
class | MultiTableHeaderUI A multiplexing UI used to combine TableHeaderUIs.
class | MultiTableUI A multiplexing UI used to combine TableUIs.
class | MultiTextUI A multiplexing UI used to combine TextUIs.
class | MultiToolBarUI A multiplexing UI used to combine ToolBarUIs.
class | MultiToolTipUI A multiplexing UI used to combine ToolTipUIs.
class | MultiTreeUI A multiplexing UI used to combine TreeUIs.
class | MultiViewportUI A multiplexing UI used to combine ViewportUIs.

Methods in javax.swing.plaf.multi that return ComponentUI
static ComponentUI | MultiViewportUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiTreeUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiToolTipUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiToolBarUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiTextUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiTableUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiTableHeaderUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiTabbedPaneUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiSplitPaneUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiSpinnerUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiSliderUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiSeparatorUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiScrollPaneUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiScrollBarUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiRootPaneUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiProgressBarUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiPopupMenuUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiPanelUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiOptionPaneUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiMenuItemUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiMenuBarUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiListUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiLabelUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiInternalFrameUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiFileChooserUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiDesktopPaneUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiDesktopIconUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiComboBoxUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiColorChooserUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiButtonUI.createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
static ComponentUI | MultiLookAndFeel.createUIs(ComponentUI mui, Vector uis, JComponent target) Creates the ComponentUI objects required to present the target component, placing the objects in the uis vector and returning the ComponentUI object that best represents the component's UI.
ComponentUI[] | MultiViewportUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiTreeUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiToolTipUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiToolBarUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiTextUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiTableUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiTableHeaderUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiTabbedPaneUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiSplitPaneUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiSpinnerUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiSliderUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiSeparatorUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiScrollPaneUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiScrollBarUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiRootPaneUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiProgressBarUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiPopupMenuUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiPanelUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiOptionPaneUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiMenuItemUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiMenuBarUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiListUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiLabelUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiInternalFrameUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiFileChooserUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiDesktopPaneUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiDesktopIconUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiComboBoxUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiColorChooserUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
ComponentUI[] | MultiButtonUI.getUIs() Returns the list of UIs associated with this multiplexing UI.
protected static ComponentUI[] | MultiLookAndFeel.uisToArray(Vector uis) Creates an array, populates it with UI objects from the passed-in vector, and returns the array.

Methods in javax.swing.plaf.multi with parameters of type ComponentUI
static ComponentUI MultiLookAndFeel.createUIs(ComponentUI mui, Vector uis, JComponent target)
Creates the ComponentUI objects required to present the target component, placing the objects in the uis vector and returning the ComponentUI object that best represents the component's UI.

Uses of ComponentUI in javax.swing.plaf.synth

Methods in javax.swing.plaf.synth that return ComponentUI
static ComponentUI SynthLookAndFeel.createUI(JComponent c)
Creates the Synth look and feel ComponentUI for the passed in JComponent.

Uses of ComponentUI in javax.swing.text

Subclasses of ComponentUI in javax.swing.text
 class DefaultTextUI
Deprecated.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.DesktopIconUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.DesktopIconUI

Packages that use DesktopIconUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of DesktopIconUI in javax.swing

Methods in javax.swing that return DesktopIconUI
 DesktopIconUI JInternalFrame.JDesktopIcon.getUI()
Returns the look-and-feel object that renders this component.

Methods in javax.swing with parameters of type DesktopIconUI
 void JInternalFrame.JDesktopIcon.setUI(DesktopIconUI ui)
Sets the look-and-feel object that renders this component.

Uses of DesktopIconUI in javax.swing.plaf.basic

Subclasses of DesktopIconUI in javax.swing.plaf.basic
 class BasicDesktopIconUI
Basic L&F for a minimized window on a desktop.

Uses of DesktopIconUI in javax.swing.plaf.metal

Subclasses of DesktopIconUI in javax.swing.plaf.metal
 class MetalDesktopIconUI
Metal desktop icon.

Uses of DesktopIconUI in javax.swing.plaf.multi

Subclasses of DesktopIconUI in javax.swing.plaf.multi
 class MultiDesktopIconUI
A multiplexing UI used to combine DesktopIconUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.DesktopPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.DesktopPaneUI

Packages that use DesktopPaneUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of DesktopPaneUI in javax.swing

Methods in javax.swing that return DesktopPaneUI
 DesktopPaneUI JDesktopPane.getUI()
Returns the L&F object that renders this component.

Methods in javax.swing with parameters of type DesktopPaneUI
 void JDesktopPane.setUI(DesktopPaneUI ui)
Sets the L&F object that renders this component.

Uses of DesktopPaneUI in javax.swing.plaf.basic

Subclasses of DesktopPaneUI in javax.swing.plaf.basic
 class BasicDesktopPaneUI
Basic L&F for a desktop.

Uses of DesktopPaneUI in javax.swing.plaf.multi

Subclasses of DesktopPaneUI in javax.swing.plaf.multi
 class MultiDesktopPaneUI
A multiplexing UI used to combine DesktopPaneUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.DimensionUIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.DimensionUIResource

No usage of javax.swing.plaf.DimensionUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.FileChooserUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.FileChooserUI

Packages that use FileChooserUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of FileChooserUI in javax.swing

Methods in javax.swing that return FileChooserUI
 FileChooserUI JFileChooser.getUI()
Gets the UI object which implements the L&F for this component.

Uses of FileChooserUI in javax.swing.plaf.basic

Subclasses of FileChooserUI in javax.swing.plaf.basic
 class BasicFileChooserUI
Basic L&F implementation of a FileChooser.

Uses of FileChooserUI in javax.swing.plaf.metal

Subclasses of FileChooserUI in javax.swing.plaf.metal
 class MetalFileChooserUI
Metal L&F implementation of a FileChooser.

Uses of FileChooserUI in javax.swing.plaf.multi

Subclasses of FileChooserUI in javax.swing.plaf.multi
 class MultiFileChooserUI
A multiplexing UI used to combine FileChooserUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.FontUIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.FontUIResource

Packages that use FontUIResource
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of FontUIResource in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal that return FontUIResource
static FontUIResource | MetalLookAndFeel.getControlTextFont() Returns the control text font of the current theme.
FontUIResource | DefaultMetalTheme.getControlTextFont() Returns the control text font.
abstract FontUIResource | MetalTheme.getControlTextFont() Returns the control text font.
static FontUIResource | MetalLookAndFeel.getMenuTextFont() Returns the menu text font of the current theme.
FontUIResource | DefaultMetalTheme.getMenuTextFont() Returns the menu text font.
abstract FontUIResource | MetalTheme.getMenuTextFont() Returns the menu text font.
static FontUIResource | MetalLookAndFeel.getSubTextFont() Returns the sub-text font of the current theme.
FontUIResource | DefaultMetalTheme.getSubTextFont() Returns the sub-text font.
abstract FontUIResource | MetalTheme.getSubTextFont() Returns the sub-text font.
static FontUIResource | MetalLookAndFeel.getSystemTextFont() Returns the sytem text font of the current theme.
FontUIResource | DefaultMetalTheme.getSystemTextFont() Returns the system text font.
abstract FontUIResource | MetalTheme.getSystemTextFont() Returns the system text font.
static FontUIResource | MetalLookAndFeel.getUserTextFont() Returns the user text font of the current theme.
FontUIResource | DefaultMetalTheme.getUserTextFont() Returns the user text font.
abstract FontUIResource | MetalTheme.getUserTextFont() Returns the user text font.
static FontUIResource | MetalLookAndFeel.getWindowTitleFont() Returns the window title font of the current theme.
FontUIResource | DefaultMetalTheme.getWindowTitleFont() Returns the window title font.
abstract FontUIResource | MetalTheme.getWindowTitleFont() Returns the window title font.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.IconUIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.IconUIResource

No usage of javax.swing.plaf.IconUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.InputMapUIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.InputMapUIResource

No usage of javax.swing.plaf.InputMapUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.InsetsUIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.InsetsUIResource

No usage of javax.swing.plaf.InsetsUIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.InternalFrameUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.InternalFrameUI

Packages that use InternalFrameUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of InternalFrameUI in javax.swing

Methods in javax.swing that return InternalFrameUI
 InternalFrameUI JInternalFrame.getUI()
Returns the look-and-feel object that renders this component.

Methods in javax.swing with parameters of type InternalFrameUI
 void JInternalFrame.setUI(InternalFrameUI ui)
Sets the UI delegate for this JInternalFrame.

Uses of InternalFrameUI in javax.swing.plaf.basic

Subclasses of InternalFrameUI in javax.swing.plaf.basic
 class BasicInternalFrameUI
A basic L&F implementation of JInternalFrame.

Uses of InternalFrameUI in javax.swing.plaf.metal

Subclasses of InternalFrameUI in javax.swing.plaf.metal
 class MetalInternalFrameUI
Metal implementation of JInternalFrame.

Uses of InternalFrameUI in javax.swing.plaf.multi

Subclasses of InternalFrameUI in javax.swing.plaf.multi
 class MultiInternalFrameUI
A multiplexing UI used to combine InternalFrameUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.LabelUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.LabelUI

Packages that use LabelUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of LabelUI in javax.swing

Methods in javax.swing that return LabelUI
 LabelUI JLabel.getUI()
Returns the L&F object that renders this component.

Methods in javax.swing with parameters of type LabelUI
 void JLabel.setUI(LabelUI ui)
Sets the L&F object that renders this component.

Uses of LabelUI in javax.swing.plaf.basic

Subclasses of LabelUI in javax.swing.plaf.basic
 class BasicLabelUI
A Windows L&F implementation of LabelUI.

Uses of LabelUI in javax.swing.plaf.metal

Subclasses of LabelUI in javax.swing.plaf.metal
 class MetalLabelUI
A Windows L&F implementation of LabelUI.

Uses of LabelUI in javax.swing.plaf.multi

Subclasses of LabelUI in javax.swing.plaf.multi
 class MultiLabelUI
A multiplexing UI used to combine LabelUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.ListUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.ListUI

Packages that use ListUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of ListUI in javax.swing

Methods in javax.swing that return ListUI
 ListUI JList.getUI()
Returns the ListUI, the look and feel object that renders this component.

Methods in javax.swing with parameters of type ListUI
 void JList.setUI(ListUI ui)
Sets the ListUI, the look and feel object that renders this component.

Uses of ListUI in javax.swing.plaf.basic

Subclasses of ListUI in javax.swing.plaf.basic
 class BasicListUI
An extensible implementation of ListUI.

Uses of ListUI in javax.swing.plaf.multi

Subclasses of ListUI in javax.swing.plaf.multi
 class MultiListUI
A multiplexing UI used to combine ListUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.MenuBarUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.MenuBarUI

Packages that use MenuBarUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of MenuBarUI in javax.swing

Methods in javax.swing that return MenuBarUI
 MenuBarUI JMenuBar.getUI()
Returns the menubar's current UI.

Methods in javax.swing with parameters of type MenuBarUI
 void JMenuBar.setUI(MenuBarUI ui)
Sets the L&F object that renders this component.

Uses of MenuBarUI in javax.swing.plaf.basic

Subclasses of MenuBarUI in javax.swing.plaf.basic
 class BasicMenuBarUI
A default L&F implementation of MenuBarUI.

Uses of MenuBarUI in javax.swing.plaf.metal

Subclasses of MenuBarUI in javax.swing.plaf.metal
 class MetalMenuBarUI
Metal implementation of MenuBarUI.

Uses of MenuBarUI in javax.swing.plaf.multi

Subclasses of MenuBarUI in javax.swing.plaf.multi
 class MultiMenuBarUI
A multiplexing UI used to combine MenuBarUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.MenuItemUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.MenuItemUI

Packages that use MenuItemUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of MenuItemUI in javax.swing

Methods in javax.swing with parameters of type MenuItemUI
 void JMenuItem.setUI(MenuItemUI ui)
Sets the look and feel object that renders this component.

Uses of MenuItemUI in javax.swing.plaf.basic

Subclasses of MenuItemUI in javax.swing.plaf.basic
class | BasicCheckBoxMenuItemUI BasicCheckboxMenuItem implementation
class | BasicMenuItemUI BasicMenuItem implementation
class | BasicMenuUI A default L&F implementation of MenuUI.
class | BasicRadioButtonMenuItemUI BasicRadioButtonMenuItem implementation

Uses of MenuItemUI in javax.swing.plaf.multi

Subclasses of MenuItemUI in javax.swing.plaf.multi
 class MultiMenuItemUI
A multiplexing UI used to combine MenuItemUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.OptionPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.OptionPaneUI

Packages that use OptionPaneUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of OptionPaneUI in javax.swing

Methods in javax.swing that return OptionPaneUI
 OptionPaneUI JOptionPane.getUI()
Returns the UI object which implements the L&F for this component.

Methods in javax.swing with parameters of type OptionPaneUI
 void JOptionPane.setUI(OptionPaneUI ui)
Sets the UI object which implements the L&F for this component.

Uses of OptionPaneUI in javax.swing.plaf.basic

Subclasses of OptionPaneUI in javax.swing.plaf.basic
 class BasicOptionPaneUI
Provides the basic look and feel for a JOptionPane.

Uses of OptionPaneUI in javax.swing.plaf.multi

Subclasses of OptionPaneUI in javax.swing.plaf.multi
 class MultiOptionPaneUI
A multiplexing UI used to combine OptionPaneUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.PanelUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.PanelUI

Packages that use PanelUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of PanelUI in javax.swing

Methods in javax.swing that return PanelUI
 PanelUI JPanel.getUI()
Returns the look and feel (L&F) object that renders this component.

Methods in javax.swing with parameters of type PanelUI
 void JPanel.setUI(PanelUI ui)
Sets the look and feel (L&F) object that renders this component.

Uses of PanelUI in javax.swing.plaf.basic

Subclasses of PanelUI in javax.swing.plaf.basic
 class BasicPanelUI
BasicPanel implementation

Uses of PanelUI in javax.swing.plaf.multi

Subclasses of PanelUI in javax.swing.plaf.multi
 class MultiPanelUI
A multiplexing UI used to combine PanelUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.PopupMenuUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.PopupMenuUI

Packages that use PopupMenuUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of PopupMenuUI in javax.swing

Methods in javax.swing that return PopupMenuUI
 PopupMenuUI JPopupMenu.getUI()
Returns the look and feel (L&F) object that renders this component.

Methods in javax.swing with parameters of type PopupMenuUI
 void JPopupMenu.setUI(PopupMenuUI ui)
Sets the L&F object that renders this component.

Uses of PopupMenuUI in javax.swing.plaf.basic

Subclasses of PopupMenuUI in javax.swing.plaf.basic
 class BasicPopupMenuUI
A Windows L&F implementation of PopupMenuUI.

Uses of PopupMenuUI in javax.swing.plaf.multi

Subclasses of PopupMenuUI in javax.swing.plaf.multi
 class MultiPopupMenuUI
A multiplexing UI used to combine PopupMenuUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.ProgressBarUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.ProgressBarUI

Packages that use ProgressBarUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of ProgressBarUI in javax.swing

Methods in javax.swing that return ProgressBarUI
 ProgressBarUI JProgressBar.getUI()
Returns the look-and-feel object that renders this component.

Methods in javax.swing with parameters of type ProgressBarUI
 void JProgressBar.setUI(ProgressBarUI ui)
Sets the look-and-feel object that renders this component.

Uses of ProgressBarUI in javax.swing.plaf.basic

Subclasses of ProgressBarUI in javax.swing.plaf.basic
 class BasicProgressBarUI
A Basic L&F implementation of ProgressBarUI.

Uses of ProgressBarUI in javax.swing.plaf.metal

Subclasses of ProgressBarUI in javax.swing.plaf.metal
 class MetalProgressBarUI
The Metal implementation of ProgressBarUI.

Uses of ProgressBarUI in javax.swing.plaf.multi

Subclasses of ProgressBarUI in javax.swing.plaf.multi
 class MultiProgressBarUI
A multiplexing UI used to combine ProgressBarUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.RootPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.RootPaneUI

Packages that use RootPaneUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of RootPaneUI in javax.swing

Methods in javax.swing that return RootPaneUI
 RootPaneUI JRootPane.getUI()
Returns the L&F object that renders this component.

Methods in javax.swing with parameters of type RootPaneUI
 void JRootPane.setUI(RootPaneUI ui)
Sets the L&F object that renders this component.

Uses of RootPaneUI in javax.swing.plaf.basic

Subclasses of RootPaneUI in javax.swing.plaf.basic
 class BasicRootPaneUI
Basic implementation of RootPaneUI, there is one shared between all JRootPane instances.

Uses of RootPaneUI in javax.swing.plaf.metal

Subclasses of RootPaneUI in javax.swing.plaf.metal
 class MetalRootPaneUI
Provides the metal look and feel implementation of RootPaneUI.

Uses of RootPaneUI in javax.swing.plaf.multi

Subclasses of RootPaneUI in javax.swing.plaf.multi
 class MultiRootPaneUI
A multiplexing UI used to combine RootPaneUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.ScrollBarUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.ScrollBarUI

Packages that use ScrollBarUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of ScrollBarUI in javax.swing

Methods in javax.swing that return ScrollBarUI
 ScrollBarUI JScrollBar.getUI()
Returns the delegate that implements the look and feel for this component.

Methods in javax.swing with parameters of type ScrollBarUI
 void JScrollBar.setUI(ScrollBarUI ui)
Sets the L&F object that renders this component.

Uses of ScrollBarUI in javax.swing.plaf.basic

Subclasses of ScrollBarUI in javax.swing.plaf.basic
 class BasicScrollBarUI
Implementation of ScrollBarUI for the Basic Look and Feel

Uses of ScrollBarUI in javax.swing.plaf.metal

Subclasses of ScrollBarUI in javax.swing.plaf.metal
 class MetalScrollBarUI
Implementation of ScrollBarUI for the Metal Look and Feel

Uses of ScrollBarUI in javax.swing.plaf.multi

Subclasses of ScrollBarUI in javax.swing.plaf.multi
 class MultiScrollBarUI
A multiplexing UI used to combine ScrollBarUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.ScrollPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.ScrollPaneUI

Packages that use ScrollPaneUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of ScrollPaneUI in javax.swing

Methods in javax.swing that return ScrollPaneUI
 ScrollPaneUI JScrollPane.getUI()
Returns the look and feel (L&F) object that renders this component.

Methods in javax.swing with parameters of type ScrollPaneUI
 void JScrollPane.setUI(ScrollPaneUI ui)
Sets the ScrollPaneUI object that provides the look and feel (L&F) for this component.

Uses of ScrollPaneUI in javax.swing.plaf.basic

Subclasses of ScrollPaneUI in javax.swing.plaf.basic
 class BasicScrollPaneUI
A default L&F implementation of ScrollPaneUI.

Uses of ScrollPaneUI in javax.swing.plaf.metal

Subclasses of ScrollPaneUI in javax.swing.plaf.metal
 class MetalScrollPaneUI
A Metal L&F implementation of ScrollPaneUI.

Uses of ScrollPaneUI in javax.swing.plaf.multi

Subclasses of ScrollPaneUI in javax.swing.plaf.multi
 class MultiScrollPaneUI
A multiplexing UI used to combine ScrollPaneUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.SeparatorUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.SeparatorUI

Packages that use SeparatorUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of SeparatorUI in javax.swing

Methods in javax.swing that return SeparatorUI
 SeparatorUI JSeparator.getUI()
Returns the L&F object that renders this component.

Methods in javax.swing with parameters of type SeparatorUI
 void JSeparator.setUI(SeparatorUI ui)
Sets the L&F object that renders this component.

Uses of SeparatorUI in javax.swing.plaf.basic

Subclasses of SeparatorUI in javax.swing.plaf.basic
class | BasicPopupMenuSeparatorUI A Basic L&F implementation of PopupMenuSeparatorUI.
class | BasicSeparatorUI A Basic L&F implementation of SeparatorUI.
class | BasicToolBarSeparatorUI A Basic L&F implementation of ToolBarSeparatorUI.

Uses of SeparatorUI in javax.swing.plaf.metal

Subclasses of SeparatorUI in javax.swing.plaf.metal
class | MetalPopupMenuSeparatorUI A Metal L&F implementation of PopupMenuSeparatorUI.
class | MetalSeparatorUI A Metal L&F implementation of SeparatorUI.

Uses of SeparatorUI in javax.swing.plaf.multi

Subclasses of SeparatorUI in javax.swing.plaf.multi
 class MultiSeparatorUI
A multiplexing UI used to combine SeparatorUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.SliderUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.SliderUI

Packages that use SliderUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of SliderUI in javax.swing

Methods in javax.swing that return SliderUI
 SliderUI JSlider.getUI()
Gets the UI object which implements the L&F for this component.

Methods in javax.swing with parameters of type SliderUI
 void JSlider.setUI(SliderUI ui)
Sets the UI object which implements the L&F for this component.

Uses of SliderUI in javax.swing.plaf.basic

Subclasses of SliderUI in javax.swing.plaf.basic
 class BasicSliderUI
A Basic L&F implementation of SliderUI.

Uses of SliderUI in javax.swing.plaf.metal

Subclasses of SliderUI in javax.swing.plaf.metal
 class MetalSliderUI
A Java L&F implementation of SliderUI.

Uses of SliderUI in javax.swing.plaf.multi

Subclasses of SliderUI in javax.swing.plaf.multi
 class MultiSliderUI
A multiplexing UI used to combine SliderUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.SpinnerUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.SpinnerUI

Packages that use SpinnerUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of SpinnerUI in javax.swing

Methods in javax.swing that return SpinnerUI
 SpinnerUI JSpinner.getUI()
Returns the look and feel (L&F) object that renders this component.

Methods in javax.swing with parameters of type SpinnerUI
 void JSpinner.setUI(SpinnerUI ui)
Sets the look and feel (L&F) object that renders this component.

Uses of SpinnerUI in javax.swing.plaf.basic

Subclasses of SpinnerUI in javax.swing.plaf.basic
 class BasicSpinnerUI
The default Spinner UI delegate.

Uses of SpinnerUI in javax.swing.plaf.multi

Subclasses of SpinnerUI in javax.swing.plaf.multi
 class MultiSpinnerUI
A multiplexing UI used to combine SpinnerUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.SplitPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.SplitPaneUI

Packages that use SplitPaneUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of SplitPaneUI in javax.swing

Methods in javax.swing that return SplitPaneUI
 SplitPaneUI JSplitPane.getUI()
Returns the SplitPaneUI that is providing the current look and feel.

Methods in javax.swing with parameters of type SplitPaneUI
 void JSplitPane.setUI(SplitPaneUI ui)
Sets the L&F object that renders this component.

Uses of SplitPaneUI in javax.swing.plaf.basic

Subclasses of SplitPaneUI in javax.swing.plaf.basic
 class BasicSplitPaneUI
A Basic L&F implementation of the SplitPaneUI.

Uses of SplitPaneUI in javax.swing.plaf.metal

Subclasses of SplitPaneUI in javax.swing.plaf.metal
 class MetalSplitPaneUI
Metal split pane.

Uses of SplitPaneUI in javax.swing.plaf.multi

Subclasses of SplitPaneUI in javax.swing.plaf.multi
 class MultiSplitPaneUI
A multiplexing UI used to combine SplitPaneUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.TabbedPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.TabbedPaneUI

Packages that use TabbedPaneUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of TabbedPaneUI in javax.swing

Methods in javax.swing that return TabbedPaneUI
 TabbedPaneUI JTabbedPane.getUI()
Returns the UI object which implements the L&F for this component.

Methods in javax.swing with parameters of type TabbedPaneUI
 void JTabbedPane.setUI(TabbedPaneUI ui)
Sets the UI object which implements the L&F for this component.

Uses of TabbedPaneUI in javax.swing.plaf.basic

Subclasses of TabbedPaneUI in javax.swing.plaf.basic
 class BasicTabbedPaneUI
A Basic L&F implementation of TabbedPaneUI.

Uses of TabbedPaneUI in javax.swing.plaf.metal

Subclasses of TabbedPaneUI in javax.swing.plaf.metal
 class MetalTabbedPaneUI
The Metal subclass of BasicTabbedPaneUI.

Uses of TabbedPaneUI in javax.swing.plaf.multi

Subclasses of TabbedPaneUI in javax.swing.plaf.multi
 class MultiTabbedPaneUI
A multiplexing UI used to combine TabbedPaneUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.TableHeaderUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.TableHeaderUI

Packages that use TableHeaderUI
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of TableHeaderUI in javax.swing.plaf.basic

Subclasses of TableHeaderUI in javax.swing.plaf.basic
 class BasicTableHeaderUI
BasicTableHeaderUI implementation

Uses of TableHeaderUI in javax.swing.plaf.multi

Subclasses of TableHeaderUI in javax.swing.plaf.multi
 class MultiTableHeaderUI
A multiplexing UI used to combine TableHeaderUIs.

Uses of TableHeaderUI in javax.swing.table

Methods in javax.swing.table that return TableHeaderUI
 TableHeaderUI JTableHeader.getUI()
Returns the look and feel (L&F) object that renders this component.

Methods in javax.swing.table with parameters of type TableHeaderUI
 void JTableHeader.setUI(TableHeaderUI ui)
Sets the look and feel (L&F) object that renders this component.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.TableUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.TableUI

Packages that use TableUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of TableUI in javax.swing

Methods in javax.swing that return TableUI
 TableUI JTable.getUI()
Returns the L&F object that renders this component.

Methods in javax.swing with parameters of type TableUI
 void JTable.setUI(TableUI ui)
Sets the L&F object that renders this component and repaints.

Uses of TableUI in javax.swing.plaf.basic

Subclasses of TableUI in javax.swing.plaf.basic
 class BasicTableUI
BasicTableUI implementation

Uses of TableUI in javax.swing.plaf.multi

Subclasses of TableUI in javax.swing.plaf.multi
 class MultiTableUI
A multiplexing UI used to combine TableUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.TextUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.TextUI

Packages that use TextUI
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of TextUI in javax.swing.plaf.basic

Subclasses of TextUI in javax.swing.plaf.basic
class | BasicEditorPaneUI Provides the look and feel for a JEditorPane.
class | BasicFormattedTextFieldUI Provides the look and feel implementation for JFormattedTextField.
class | BasicPasswordFieldUI Provides the Windows look and feel for a password field.
class | BasicTextAreaUI Provides the look and feel for a plain text editor.
class | BasicTextFieldUI Basis of a look and feel for a JTextField.
class | BasicTextPaneUI Provides the look and feel for a styled text editor.
class | BasicTextUI Basis of a text components look-and-feel.

Uses of TextUI in javax.swing.plaf.metal

Subclasses of TextUI in javax.swing.plaf.metal
 class MetalTextFieldUI
Basis of a look and feel for a JTextField.

Uses of TextUI in javax.swing.plaf.multi

Subclasses of TextUI in javax.swing.plaf.multi
 class MultiTextUI
A multiplexing UI used to combine TextUIs.

Uses of TextUI in javax.swing.text

Subclasses of TextUI in javax.swing.text
 class DefaultTextUI
Deprecated.

Methods in javax.swing.text that return TextUI
 TextUI JTextComponent.getUI()
Fetches the user-interface factory for this text-oriented editor.

Methods in javax.swing.text with parameters of type TextUI
 void JTextComponent.setUI(TextUI ui)
Sets the user-interface factory for this text-oriented editor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.ToolBarUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.ToolBarUI

Packages that use ToolBarUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of ToolBarUI in javax.swing

Methods in javax.swing that return ToolBarUI
 ToolBarUI JToolBar.getUI()
Returns the tool bar's current UI.

Methods in javax.swing with parameters of type ToolBarUI
 void JToolBar.setUI(ToolBarUI ui)
Sets the L&F object that renders this component.

Uses of ToolBarUI in javax.swing.plaf.basic

Subclasses of ToolBarUI in javax.swing.plaf.basic
 class BasicToolBarUI
A Basic L&F implementation of ToolBarUI.

Uses of ToolBarUI in javax.swing.plaf.metal

Subclasses of ToolBarUI in javax.swing.plaf.metal
 class MetalToolBarUI
A Metal Look and Feel implementation of ToolBarUI.

Uses of ToolBarUI in javax.swing.plaf.multi

Subclasses of ToolBarUI in javax.swing.plaf.multi
 class MultiToolBarUI
A multiplexing UI used to combine ToolBarUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.ToolTipUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.ToolTipUI

Packages that use ToolTipUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of ToolTipUI in javax.swing

Methods in javax.swing that return ToolTipUI
 ToolTipUI JToolTip.getUI()
Returns the L&F object that renders this component.

Uses of ToolTipUI in javax.swing.plaf.basic

Subclasses of ToolTipUI in javax.swing.plaf.basic
 class BasicToolTipUI
Standard tool tip L&F.

Uses of ToolTipUI in javax.swing.plaf.metal

Subclasses of ToolTipUI in javax.swing.plaf.metal
 class MetalToolTipUI
A Metal L&F extension of BasicToolTipUI.

Uses of ToolTipUI in javax.swing.plaf.multi

Subclasses of ToolTipUI in javax.swing.plaf.multi
 class MultiToolTipUI
A multiplexing UI used to combine ToolTipUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.TreeUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.TreeUI

Packages that use TreeUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of TreeUI in javax.swing

Methods in javax.swing that return TreeUI
 TreeUI JTree.getUI()
Returns the L&F object that renders this component.

Methods in javax.swing with parameters of type TreeUI
 void JTree.setUI(TreeUI ui)
Sets the L&F object that renders this component.

Uses of TreeUI in javax.swing.plaf.basic

Subclasses of TreeUI in javax.swing.plaf.basic
 class BasicTreeUI
The basic L&F for a hierarchical data structure.

Uses of TreeUI in javax.swing.plaf.metal

Subclasses of TreeUI in javax.swing.plaf.metal
 class MetalTreeUI
The metal look and feel implementation of TreeUI.

Uses of TreeUI in javax.swing.plaf.multi

Subclasses of TreeUI in javax.swing.plaf.multi
 class MultiTreeUI
A multiplexing UI used to combine TreeUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.ViewportUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.ViewportUI

Packages that use ViewportUI
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.

Uses of ViewportUI in javax.swing

Methods in javax.swing that return ViewportUI
 ViewportUI JViewport.getUI()
Returns the L&F object that renders this component.

Methods in javax.swing with parameters of type ViewportUI
 void JViewport.setUI(ViewportUI ui)
Sets the L&F object that renders this component.

Uses of ViewportUI in javax.swing.plaf.basic

Subclasses of ViewportUI in javax.swing.plaf.basic
 class BasicViewportUI
BasicViewport implementation

Uses of ViewportUI in javax.swing.plaf.multi

Subclasses of ViewportUI in javax.swing.plaf.multi
 class MultiViewportUI
A multiplexing UI used to combine ViewportUIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.plaf.UIResource

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.plaf.UIResource

Packages that use UIResource
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of UIResource in javax.swing

Classes in javax.swing that implement UIResource
static class | DefaultListCellRenderer.UIResource A subclass of DefaultListCellRenderer that implements UIResource.
protected class | JScrollPane.ScrollBar By default JScrollPane creates scrollbars that are instances of this class.
static class | ScrollPaneLayout.UIResource The UI resource version of ScrollPaneLayout.

Uses of UIResource in javax.swing.plaf

Classes in javax.swing.plaf that implement UIResource
class | ActionMapUIResource A subclass of javax.swing.ActionMap that implements UIResource.
class | BorderUIResource
static class | BorderUIResource.BevelBorderUIResource
static class | BorderUIResource.CompoundBorderUIResource
static class | BorderUIResource.EmptyBorderUIResource
static class | BorderUIResource.EtchedBorderUIResource
static class | BorderUIResource.LineBorderUIResource
static class | BorderUIResource.MatteBorderUIResource
static class | BorderUIResource.TitledBorderUIResource
class | ColorUIResource
class | ComponentInputMapUIResource A subclass of javax.swing.ComponentInputMap that implements UIResource.
class | DimensionUIResource
class | FontUIResource A subclass of java.awt.Font that implements UIResource.
class | IconUIResource An Icon wrapper class which implements UIResource.
class | InputMapUIResource A subclass of javax.swing.InputMap that implements UIResource.
class | InsetsUIResource

Uses of UIResource in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement UIResource
static class | BasicBorders.ButtonBorder
static class | BasicBorders.FieldBorder
static class | BasicBorders.MarginBorder
static class | BasicBorders.MenuBarBorder
static class | BasicBorders.RadioButtonBorder
static class | BasicBorders.RolloverButtonBorder Special thin border for rollover toolbar buttons.
static class | BasicBorders.SplitPaneBorder Draws the border around the splitpane.
static class | BasicBorders.ToggleButtonBorder
static class | BasicComboBoxEditor.UIResource A subclass of BasicComboBoxEditor that implements UIResource.
static class | BasicComboBoxRenderer.UIResource A subclass of BasicComboBoxRenderer that implements UIResource.
static class | BasicTextUI.BasicCaret
static class | BasicTextUI.BasicHighlighter
class | DefaultMenuLayout The default layout manager for Popup menus and menubars.

Uses of UIResource in javax.swing.plaf.metal

Classes in javax.swing.plaf.metal that implement UIResource
static class | MetalBorders.ButtonBorder
static class | MetalBorders.Flush3DBorder
static class | MetalBorders.InternalFrameBorder
static class | MetalBorders.MenuBarBorder
static class | MetalBorders.MenuItemBorder
static class | MetalBorders.OptionDialogBorder
static class | MetalBorders.PaletteBorder Border for a Palette.
static class | MetalBorders.PopupMenuBorder
static class | MetalBorders.RolloverButtonBorder
static class | MetalBorders.ScrollPaneBorder
static class | MetalBorders.TextFieldBorder
static class | MetalBorders.ToggleButtonBorder
static class | MetalBorders.ToolBarBorder
class | MetalCheckBoxIcon CheckboxIcon implementation for OrganicCheckBoxUI
static class | MetalComboBoxEditor.UIResource A subclass of BasicComboBoxEditor that implements UIResource.
static class | MetalIconFactory.PaletteCloseIcon Defines an icon for Palette close

Uses of UIResource in javax.swing.table

Classes in javax.swing.table that implement UIResource
static class DefaultTableCellRenderer.UIResource
A subclass of DefaultTableCellRenderer that implements UIResource.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ColorChooserUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class ColorChooserUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ColorChooserUI
Direct Known Subclasses:
BasicColorChooserUI, MultiColorChooserUI
public abstract class ColorChooserUI
extends ComponentUI

Pluggable look and feel interface for JColorChooser.

Constructor Summary
ColorChooserUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ColorChooserUI

public ColorChooserUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ColorUIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class ColorUIResource

java.lang.Object
    extended by  java.awt.Color
        extended by  javax.swing.plaf.ColorUIResource
All Implemented Interfaces:
Paint, Transparency, Serializable, UIResource
public class ColorUIResource
extends Color
implements UIResource

Field Summary
Fields inherited from class java.awt.Color
black, BLACK, blue, BLUE, cyan, CYAN, DARK_GRAY, darkGray, gray, GRAY, green, GREEN, LIGHT_GRAY, lightGray, magenta, MAGENTA, orange, ORANGE, pink, PINK, red, RED, white, WHITE, yellow, YELLOW
Fields inherited from interface java.awt.Transparency
BITMASK, OPAQUE, TRANSLUCENT
Constructor Summary
ColorUIResource(Color c)
ColorUIResource(float r, float g, float b)
ColorUIResource(int rgb)
ColorUIResource(int r, int g, int b)
Method Summary
Methods inherited from class java.awt.Color
brighter, createContext, darker, decode, equals, getAlpha, getBlue, getColor, getColor, getColor, getColorComponents, getColorComponents, getColorSpace, getComponents, getComponents, getGreen, getHSBColor, getRed, getRGB, getRGBColorComponents, getRGBComponents, getTransparency, hashCode, HSBtoRGB, RGBtoHSB, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ColorUIResource

public ColorUIResource(int r,
                       int g,
                       int b)

ColorUIResource

public ColorUIResource(int rgb)

ColorUIResource

public ColorUIResource(float r,
                       float g,
                       float b)

ColorUIResource

public ColorUIResource(Color c)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ComboBoxUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class ComboBoxUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ComboBoxUI
Direct Known Subclasses:
BasicComboBoxUI, MultiComboBoxUI
public abstract class ComboBoxUI
extends ComponentUI

Pluggable look and feel interface for JComboBox.

Constructor Summary
ComboBoxUI()
Method Summary
abstract boolean | isFocusTraversable(JComboBox c) Determine whether or not the combo box itself is traversable
abstract boolean | isPopupVisible(JComboBox c) Determine the visibility of the popup
abstract void | setPopupVisible(JComboBox c, boolean v) Set the visiblity of the popup
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ComboBoxUI

public ComboBoxUI()
Method Detail

setPopupVisible

public abstract void setPopupVisible(JComboBox c,
                                     boolean v)
Set the visiblity of the popup

isPopupVisible

public abstract boolean isPopupVisible(JComboBox c)
Determine the visibility of the popup

isFocusTraversable

public abstract boolean isFocusTraversable(JComboBox c)
Determine whether or not the combo box itself is traversable

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ComponentInputMapUIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class ComponentInputMapUIResource

java.lang.Object
    extended by  javax.swing.InputMap
        extended by  javax.swing.ComponentInputMap
            extended by  javax.swing.plaf.ComponentInputMapUIResource
All Implemented Interfaces:
Serializable, UIResource
public class ComponentInputMapUIResource
extends ComponentInputMap
implements UIResource

A subclass of javax.swing.ComponentInputMap that implements UIResource. UI classes which provide a ComponentInputMap should use this class.

Since:
1.3

Constructor Summary
ComponentInputMapUIResource(JComponent component)
Method Summary
Methods inherited from class javax.swing.ComponentInputMap
clear, getComponent, put, remove, setParent
Methods inherited from class javax.swing.InputMap
allKeys, get, getParent, keys, size
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ComponentInputMapUIResource

public ComponentInputMapUIResource(JComponent component)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ComponentUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class ComponentUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
Direct Known Subclasses:
ButtonUI, ColorChooserUI, ComboBoxUI, DesktopIconUI, DesktopPaneUI, FileChooserUI, InternalFrameUI, LabelUI, ListUI, MenuBarUI, OptionPaneUI, PanelUI, PopupMenuUI, ProgressBarUI, RootPaneUI, ScrollBarUI, ScrollPaneUI, SeparatorUI, SliderUI, SpinnerUI, SplitPaneUI, TabbedPaneUI, TableHeaderUI, TableUI, TextUI, ToolBarUI, ToolTipUI, TreeUI, ViewportUI
public abstract class ComponentUI
extends Object

The base class for all UI delegate objects in the Swing pluggable look and feel architecture. The UI delegate object for a Swing component is responsible for implementing the aspects of the component that depend on the look and feel. The JComponent class invokes methods from this class in order to delegate operations (painting, layout calculations, etc.) that may vary depending on the look and feel installed. Client programs should not invoke methods on this class directly.

See Also:
JComponent, UIManager

Constructor Summary
ComponentUI()
Sole constructor.
Method Summary
boolean | contains(JComponent c, int x, int y) Returns true if the specified x,y location is contained within the look and feel's defined shape of the specified component.
static ComponentUI | createUI(JComponent c) Returns an instance of the UI delegate for the specified component.
Accessible | getAccessibleChild(JComponent c, int i) Returns the ith Accessible child of the object.
int | getAccessibleChildrenCount(JComponent c) Returns the number of accessible children in the object.
int | getBaseline(JComponent c, int width, int height) Returns the baseline.
Component.BaselineResizeBehavior | getBaselineResizeBehavior(JComponent c) Returns an enum indicating how the baseline of he component changes as the size changes.
Dimension | getMaximumSize(JComponent c) Returns the specified component's maximum size appropriate for the look and feel.
Dimension | getMinimumSize(JComponent c) Returns the specified component's minimum size appropriate for the look and feel.
Dimension | getPreferredSize(JComponent c) Returns the specified component's preferred size appropriate for the look and feel.
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
void | update(Graphics g, JComponent c) Notifies this UI delegate that it's time to paint the specified component.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ComponentUI

public ComponentUI()
Sole constructor. (For invocation by subclass constructors, typically implicit.)

Method Detail

installUI

public void installUI(JComponent c)
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Parameters:
c - the component where this UI delegate is being installed
See Also:
uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics g,
                  JComponent c)
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
update(java.awt.Graphics, javax.swing.JComponent)

update

public void update(Graphics g,
                   JComponent c)
Notifies this UI delegate that it's time to paint the specified component. This method is invoked by JComponent when the specified component is being painted. By default this method will fill the specified component with its background color (if its opaque property is true) and then immediately call paint. In general this method need not be overridden by subclasses; all look-and-feel rendering code should reside in the paint method.

Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Returns the specified component's minimum size appropriate for the look and feel. If null is returned, the minimum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Returns the specified component's maximum size appropriate for the look and feel. If null is returned, the maximum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

contains

public boolean contains(JComponent c,
                        int x,
                        int y)
Returns true if the specified x,y location is contained within the look and feel's defined shape of the specified component. x and y are defined to be relative to the coordinate system of the specified component. Although a component's bounds is constrained to a rectangle, this method provides the means for defining a non-rectangular shape within those bounds for the purpose of hit detection.

Parameters:
c - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
x - the x coordinate of the point
y - the y coordinate of the point
See Also:
JComponent.contains(int, int), Component.contains(int, int)

createUI

public static ComponentUI createUI(JComponent c)
Returns an instance of the UI delegate for the specified component. Each subclass must provide its own static createUI method that returns an instance of that UI delegate subclass. If the UI delegate subclass is stateless, it may return an instance that is shared by multiple components. If the UI delegate is stateful, then it should return a new instance per component. The default implementation of this method throws an error, as it should never be invoked.

getBaseline

public int getBaseline(JComponent c,
                       int width,
                       int height)
Returns the baseline. The baseline is measured from the top of the component. This method is primarily meant for LayoutManagers to align components along their baseline. A return value less than 0 indicates this component does not have a reasonable baseline and that LayoutManagers should not align this component on its baseline.

This method returns -1. Subclasses that have a meaningful baseline should override appropriately.

Parameters:
c - JComponent baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
NullPointerException - if c is null
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int,int)

getBaselineResizeBehavior

public Component.BaselineResizeBehavior getBaselineResizeBehavior(JComponent c)
Returns an enum indicating how the baseline of he component changes as the size changes. This method is primarily meant for layout managers and GUI builders.

This method returns BaselineResizeBehavior.OTHER. Subclasses that support a baseline should override appropriately.

Parameters:
c - JComponent to return baseline resize behavior for
Returns:
an enum indicating how the baseline changes as the component size changes
Throws:
NullPointerException - if c is null
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent c)
Returns the number of accessible children in the object. If all of the children of this object implement Accessible, this method should return the number of children of this object. UIs might wish to override this if they present areas on the screen that can be viewed as components, but actual components are not used for presenting those areas. Note: As of v1.3, it is recommended that developers call Component.AccessibleAWTComponent.getAccessibleChildrenCount() instead of this method.

Returns:
the number of accessible children in the object
See Also:
getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent c,
                                     int i)
Returns the ith Accessible child of the object. UIs might need to override this if they present areas on the screen that can be viewed as components, but actual components are not used for presenting those areas.

Note: As of v1.3, it is recommended that developers call Component.AccessibleAWTComponent.getAccessibleChild() instead of this method.

Parameters:
i - zero-based index of child
Returns:
the ith Accessible child of the object
See Also:
getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DesktopIconUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class DesktopIconUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.DesktopIconUI
Direct Known Subclasses:
BasicDesktopIconUI, MultiDesktopIconUI
public abstract class DesktopIconUI
extends ComponentUI

Pluggable look and feel interface for JDesktopIcon.

Constructor Summary
DesktopIconUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DesktopIconUI

public DesktopIconUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DesktopPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class DesktopPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.DesktopPaneUI
Direct Known Subclasses:
BasicDesktopPaneUI, MultiDesktopPaneUI
public abstract class DesktopPaneUI
extends ComponentUI

Pluggable look and feel interface for JDesktopPane.

Constructor Summary
DesktopPaneUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DesktopPaneUI

public DesktopPaneUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DimensionUIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class DimensionUIResource

java.lang.Object
    extended by  java.awt.geom.Dimension2D
        extended by  java.awt.Dimension
            extended by  javax.swing.plaf.DimensionUIResource
All Implemented Interfaces:
Serializable, Cloneable, UIResource
public class DimensionUIResource
extends Dimension
implements UIResource

Field Summary
Fields inherited from class java.awt.Dimension
height, width
Constructor Summary
DimensionUIResource(int width, int height)
Method Summary
Methods inherited from class java.awt.Dimension
equals, getHeight, getSize, getWidth, hashCode, setSize, setSize, setSize, toString
Methods inherited from class java.awt.geom.Dimension2D
clone, setSize
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DimensionUIResource

public DimensionUIResource(int width,
                           int height)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FileChooserUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class FileChooserUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.FileChooserUI
Direct Known Subclasses:
BasicFileChooserUI, MultiFileChooserUI
public abstract class FileChooserUI
extends ComponentUI

Pluggable look and feel interface for JFileChooser.

Constructor Summary
FileChooserUI()
Method Summary
abstract void | ensureFileIsVisible(JFileChooser fc, File f)
abstract FileFilter | getAcceptAllFileFilter(JFileChooser fc)
abstract String | getApproveButtonText(JFileChooser fc)
abstract String | getDialogTitle(JFileChooser fc)
abstract FileView | getFileView(JFileChooser fc)
abstract void | rescanCurrentDirectory(JFileChooser fc)
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FileChooserUI

public FileChooserUI()
Method Detail

getAcceptAllFileFilter

public abstract FileFilter getAcceptAllFileFilter(JFileChooser fc)

getFileView

public abstract FileView getFileView(JFileChooser fc)

getApproveButtonText

public abstract String getApproveButtonText(JFileChooser fc)

getDialogTitle

public abstract String getDialogTitle(JFileChooser fc)

rescanCurrentDirectory

public abstract void rescanCurrentDirectory(JFileChooser fc)

ensureFileIsVisible

public abstract void ensureFileIsVisible(JFileChooser fc,
                                         File f)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FontUIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class FontUIResource

java.lang.Object
    extended by  java.awt.Font
        extended by  javax.swing.plaf.FontUIResource
All Implemented Interfaces:
Serializable, UIResource
public class FontUIResource
extends Font
implements UIResource

A subclass of java.awt.Font that implements UIResource. UI classes which set default font properties should use this class.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
UIResource

Field Summary
Fields inherited from class java.awt.Font
BOLD, CENTER_BASELINE, DIALOG, DIALOG_INPUT, HANGING_BASELINE, ITALIC, LAYOUT_LEFT_TO_RIGHT, LAYOUT_NO_LIMIT_CONTEXT, LAYOUT_NO_START_CONTEXT, LAYOUT_RIGHT_TO_LEFT, MONOSPACED, name, PLAIN, pointSize, ROMAN_BASELINE, SANS_SERIF, SERIF, size, style, TRUETYPE_FONT, TYPE1_FONT
Constructor Summary
FontUIResource(Font font)
FontUIResource(String name, int style, int size)
Method Summary
Methods inherited from class java.awt.Font
canDisplay, canDisplay, canDisplayUpTo, canDisplayUpTo, canDisplayUpTo, createFont, createFont, createGlyphVector, createGlyphVector, createGlyphVector, createGlyphVector, decode, deriveFont, deriveFont, deriveFont, deriveFont, deriveFont, deriveFont, equals, finalize, getAttributes, getAvailableAttributes, getBaselineFor, getFamily, getFamily, getFont, getFont, getFont, getFontName, getFontName, getItalicAngle, getLineMetrics, getLineMetrics, getLineMetrics, getLineMetrics, getMaxCharBounds, getMissingGlyphCode, getName, getNumGlyphs, getPeer, getPSName, getSize, getSize2D, getStringBounds, getStringBounds, getStringBounds, getStringBounds, getStyle, getTransform, hashCode, hasLayoutAttributes, hasUniformLineMetrics, isBold, isItalic, isPlain, isTransformed, layoutGlyphVector, toString
Methods inherited from class java.lang.Object
clone, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

FontUIResource

public FontUIResource(String name,
                      int style,
                      int size)

FontUIResource

public FontUIResource(Font font)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IconUIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class IconUIResource

java.lang.Object
    extended by  javax.swing.plaf.IconUIResource
All Implemented Interfaces:
Serializable, Icon, UIResource
public class IconUIResource
extends Object
implements Icon, UIResource, Serializable

An Icon wrapper class which implements UIResource. UI classes which set icon properties should use this class to wrap any icons specified as defaults. This class delegates all method invocations to the Icon "delegate" object specified at construction.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
UIResource

Constructor Summary
IconUIResource(Icon delegate)
Creates a UIResource icon object which wraps an existing Icon instance.
Method Summary
int | getIconHeight() Returns the icon's height.
int | getIconWidth() Returns the icon's width.
void | paintIcon(Component c, Graphics g, int x, int y) Draw the icon at the specified location.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IconUIResource

public IconUIResource(Icon delegate)
Creates a UIResource icon object which wraps an existing Icon instance.

Parameters:
delegate - the icon being wrapped
Method Detail

paintIcon

public void paintIcon(Component c,
                      Graphics g,
                      int x,
                      int y)
Description copied from interface: Icon
Draw the icon at the specified location. Icon implementations may use the Component argument to get properties useful for painting, e.g. the foreground or background color.

Specified by:
paintIcon in interface Icon

getIconWidth

public int getIconWidth()
Description copied from interface: Icon
Returns the icon's width.

Specified by:
getIconWidth in interface Icon
Returns:
an int specifying the fixed width of the icon.

getIconHeight

public int getIconHeight()
Description copied from interface: Icon
Returns the icon's height.

Specified by:
getIconHeight in interface Icon
Returns:
an int specifying the fixed height of the icon.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InputMapUIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class InputMapUIResource

java.lang.Object
    extended by  javax.swing.InputMap
        extended by  javax.swing.plaf.InputMapUIResource
All Implemented Interfaces:
Serializable, UIResource
public class InputMapUIResource
extends InputMap
implements UIResource

A subclass of javax.swing.InputMap that implements UIResource. UI classes which provide a InputMap should use this class.

Since:
1.3

Constructor Summary
InputMapUIResource()
Method Summary
Methods inherited from class javax.swing.InputMap
allKeys, clear, get, getParent, keys, put, remove, setParent, size
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InputMapUIResource

public InputMapUIResource()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InsetsUIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class InsetsUIResource

java.lang.Object
    extended by  java.awt.Insets
        extended by  javax.swing.plaf.InsetsUIResource
All Implemented Interfaces:
Serializable, Cloneable, UIResource
public class InsetsUIResource
extends Insets
implements UIResource

Field Summary
Fields inherited from class java.awt.Insets
bottom, left, right, top
Constructor Summary
InsetsUIResource(int top, int left, int bottom, int right)
Method Summary
Methods inherited from class java.awt.Insets
clone, equals, hashCode, set, toString
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

InsetsUIResource

public InsetsUIResource(int top,
                        int left,
                        int bottom,
                        int right)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InternalFrameUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class InternalFrameUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.InternalFrameUI
Direct Known Subclasses:
BasicInternalFrameUI, MultiInternalFrameUI
public abstract class InternalFrameUI
extends ComponentUI

Pluggable look and feel interface for JInternalFrame.

Constructor Summary
InternalFrameUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InternalFrameUI

public InternalFrameUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LabelUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class LabelUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.LabelUI
Direct Known Subclasses:
BasicLabelUI, MultiLabelUI
public abstract class LabelUI
extends ComponentUI

Pluggable look and feel interface for JLabel.

Constructor Summary
LabelUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LabelUI

public LabelUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ListUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class ListUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ListUI
Direct Known Subclasses:
BasicListUI, MultiListUI
public abstract class ListUI
extends ComponentUI

The JList pluggable look and feel delegate.

Constructor Summary
ListUI()
Method Summary
abstract Rectangle | getCellBounds(JList list, int index1, int index2) Returns the bounding rectangle, in the given list's coordinate system, for the range of cells specified by the two indices.
abstract Point | indexToLocation(JList list, int index) Returns the origin in the given JList, of the specified item, in the list's coordinate system.
abstract int | locationToIndex(JList list, Point location) Returns the cell index in the specified JList closest to the given location in the list's coordinate system.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ListUI

public ListUI()
Method Detail

locationToIndex

public abstract int locationToIndex(JList list,
                                    Point location)
Returns the cell index in the specified JList closest to the given location in the list's coordinate system. To determine if the cell actually contains the specified location, compare the point against the cell's bounds, as provided by getCellBounds. This method returns -1 if the list's model is empty.

Parameters:
list - the list
location - the coordinates of the point
Returns:
the cell index closest to the given location, or -1
Throws:
NullPointerException - if location is null

indexToLocation

public abstract Point indexToLocation(JList list,
                                      int index)
Returns the origin in the given JList, of the specified item, in the list's coordinate system. Returns null if the index isn't valid.

Parameters:
list - the list
index - the cell index
Returns:
the origin of the cell, or null

getCellBounds

public abstract Rectangle getCellBounds(JList list,
                                        int index1,
                                        int index2)
Returns the bounding rectangle, in the given list's coordinate system, for the range of cells specified by the two indices. The indices can be supplied in any order.

If the smaller index is outside the list's range of cells, this method returns null. If the smaller index is valid, but the larger index is outside the list's range, the bounds of just the first index is returned. Otherwise, the bounds of the valid range is returned.

Parameters:
list - the list
index1 - the first index in the range
index2 - the second index in the range
Returns:
the bounding rectangle for the range of cells, or null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MenuBarUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class MenuBarUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.MenuBarUI
Direct Known Subclasses:
BasicMenuBarUI, MultiMenuBarUI
public abstract class MenuBarUI
extends ComponentUI

Pluggable look and feel interface for JMenuBar.

Constructor Summary
MenuBarUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MenuBarUI

public MenuBarUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MenuItemUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class MenuItemUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ButtonUI
            extended by  javax.swing.plaf.MenuItemUI
Direct Known Subclasses:
BasicMenuItemUI, MultiMenuItemUI
public abstract class MenuItemUI
extends ButtonUI

Pluggable look and feel interface for JMenuItem.

Constructor Summary
MenuItemUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MenuItemUI

public MenuItemUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


metal

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.swing.plaf.metal

Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

See:
Description

Class Summary
DefaultMetalTheme | A concrete implementation of MetalTheme providing the original look of the Java Look and Feel, code-named "Steel".
MetalBorders | Factory object that can vend Borders appropriate for the metal L & F.
MetalBorders.ButtonBorder |
MetalBorders.Flush3DBorder |
MetalBorders.InternalFrameBorder |
MetalBorders.MenuBarBorder |
MetalBorders.MenuItemBorder |
MetalBorders.OptionDialogBorder |
MetalBorders.PaletteBorder | Border for a Palette.
MetalBorders.PopupMenuBorder |
MetalBorders.RolloverButtonBorder |
MetalBorders.ScrollPaneBorder |
MetalBorders.TableHeaderBorder | Border for a Table Header
MetalBorders.TextFieldBorder |
MetalBorders.ToggleButtonBorder |
MetalBorders.ToolBarBorder |
MetalButtonUI | MetalButtonUI implementation
MetalCheckBoxIcon | CheckboxIcon implementation for OrganicCheckBoxUI
MetalCheckBoxUI | CheckboxUI implementation for MetalCheckboxUI
MetalComboBoxButton | JButton subclass to help out MetalComboBoxUI
MetalComboBoxEditor | The default editor for Metal editable combo boxes
MetalComboBoxEditor.UIResource | A subclass of BasicComboBoxEditor that implements UIResource.
MetalComboBoxIcon | This utility class draws the horizontal bars which indicate a MetalComboBox
MetalComboBoxUI | Metal UI for JComboBox
MetalDesktopIconUI | Metal desktop icon.
MetalFileChooserUI | Metal L&F implementation of a FileChooser.
MetalIconFactory | Factory object that vends Icons for the JavaTM look and feel (Metal).
MetalIconFactory.FileIcon16 | Warning: Serialized objects of this class will not be compatible with future Swing releases.
MetalIconFactory.FolderIcon16 | Warning: Serialized objects of this class will not be compatible with future Swing releases.
MetalIconFactory.PaletteCloseIcon | Defines an icon for Palette close
MetalIconFactory.TreeControlIcon | Warning: Serialized objects of this class will not be compatible with future Swing releases.
MetalIconFactory.TreeFolderIcon | Warning: Serialized objects of this class will not be compatible with future Swing releases.
MetalIconFactory.TreeLeafIcon |
MetalInternalFrameTitlePane | Class that manages a JLF title bar
MetalInternalFrameUI | Metal implementation of JInternalFrame.
MetalLabelUI | A Windows L&F implementation of LabelUI.
MetalLookAndFeel | The Java Look and Feel, otherwise known as Metal.
MetalMenuBarUI | Metal implementation of MenuBarUI.
MetalPopupMenuSeparatorUI | A Metal L&F implementation of PopupMenuSeparatorUI.
MetalProgressBarUI | The Metal implementation of ProgressBarUI.
MetalRadioButtonUI | RadioButtonUI implementation for MetalRadioButtonUI
MetalRootPaneUI | Provides the metal look and feel implementation of RootPaneUI.
MetalScrollBarUI | Implementation of ScrollBarUI for the Metal Look and Feel
MetalScrollButton | JButton object for Metal scrollbar arrows.
MetalScrollPaneUI | A Metal L&F implementation of ScrollPaneUI.
MetalSeparatorUI | A Metal L&F implementation of SeparatorUI.
MetalSliderUI | A Java L&F implementation of SliderUI.
MetalSplitPaneUI | Metal split pane.
MetalTabbedPaneUI | The Metal subclass of BasicTabbedPaneUI.
MetalTextFieldUI | Basis of a look and feel for a JTextField.
MetalTheme | MetalTheme provides the color palette and fonts used by the Java Look and Feel.
MetalToggleButtonUI | MetalToggleButton implementation
MetalToolBarUI | A Metal Look and Feel implementation of ToolBarUI.
MetalToolTipUI | A Metal L&F extension of BasicToolTipUI.
MetalTreeUI | The metal look and feel implementation of TreeUI.
OceanTheme | The default theme for the MetalLookAndFeel.

Package javax.swing.plaf.metal Description

Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

These classes are designed to be used while the corresponding LookAndFeel class has been installed (UIManager.setLookAndFeel(new XXXLookAndFeel())). Using them while a different LookAndFeel is installed may produce unexpected results, including exceptions. Additionally, changing the LookAndFeel maintained by the UIManager without updating the corresponding ComponentUI of any JComponents may also produce unexpected results, such as the wrong colors showing up, and is generally not encouraged.

Note: Most of the Swing API is not thread safe. For details, see Threads and Swing, a section in The Java Tutorial.

Since:
1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.swing.plaf.metal Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.swing.plaf.metal

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.swing.AbstractAction (implements javax.swing.Action, java.lang.Cloneable, java.io.Serializable)
      • javax.swing.plaf.metal.MetalFileChooserUI.DirectoryComboBoxAction
    • javax.swing.border.AbstractBorder (implements javax.swing.border.Border, java.io.Serializable)
      • javax.swing.plaf.metal.MetalBorders.ButtonBorder (implements javax.swing.plaf.UIResource)
        • javax.swing.plaf.metal.MetalBorders.RolloverButtonBorder
        • javax.swing.plaf.metal.MetalBorders.ToggleButtonBorder
      • javax.swing.plaf.metal.MetalBorders.Flush3DBorder (implements javax.swing.plaf.UIResource)
        • javax.swing.plaf.metal.MetalBorders.TextFieldBorder
      • javax.swing.plaf.metal.MetalBorders.InternalFrameBorder (implements javax.swing.plaf.UIResource)
      • javax.swing.plaf.metal.MetalBorders.MenuBarBorder (implements javax.swing.plaf.UIResource)
      • javax.swing.plaf.metal.MetalBorders.MenuItemBorder (implements javax.swing.plaf.UIResource)
      • javax.swing.plaf.metal.MetalBorders.OptionDialogBorder (implements javax.swing.plaf.UIResource)
      • javax.swing.plaf.metal.MetalBorders.PaletteBorder (implements javax.swing.plaf.UIResource)
      • javax.swing.plaf.metal.MetalBorders.PopupMenuBorder (implements javax.swing.plaf.UIResource)
      • javax.swing.plaf.metal.MetalBorders.ScrollPaneBorder (implements javax.swing.plaf.UIResource)
      • javax.swing.plaf.metal.MetalBorders.TableHeaderBorder
      • javax.swing.plaf.metal.MetalBorders.ToolBarBorder (implements javax.swing.SwingConstants, javax.swing.plaf.UIResource)
    • javax.swing.AbstractListModel (implements javax.swing.ListModel, java.io.Serializable)
      • javax.swing.plaf.metal.MetalFileChooserUI.DirectoryComboBoxModel (implements javax.swing.ComboBoxModel)
      • javax.swing.plaf.metal.MetalFileChooserUI.FilterComboBoxModel (implements javax.swing.ComboBoxModel, java.beans.PropertyChangeListener)
    • javax.swing.plaf.basic.BasicComboBoxEditor (implements javax.swing.ComboBoxEditor, java.awt.event.FocusListener)
      • javax.swing.plaf.metal.MetalComboBoxEditor
        • javax.swing.plaf.metal.MetalComboBoxEditor.UIResource (implements javax.swing.plaf.UIResource)
    • javax.swing.plaf.basic.BasicComboBoxUI.ComboBoxLayoutManager (implements java.awt.LayoutManager)
      • javax.swing.plaf.metal.MetalComboBoxUI.MetalComboBoxLayoutManager
    • javax.swing.plaf.basic.BasicComboBoxUI.PropertyChangeHandler (implements java.beans.PropertyChangeListener)
      • javax.swing.plaf.metal.MetalComboBoxUI.MetalPropertyChangeListener
    • javax.swing.plaf.basic.BasicSliderUI.PropertyChangeHandler (implements java.beans.PropertyChangeListener)
      • javax.swing.plaf.metal.MetalSliderUI.MetalPropertyListener
    • javax.swing.plaf.basic.BasicTabbedPaneUI.TabbedPaneLayout (implements java.awt.LayoutManager)
      • javax.swing.plaf.metal.MetalTabbedPaneUI.TabbedPaneLayout
    • javax.swing.plaf.basic.BasicToolBarUI.DockingListener (implements javax.swing.event.MouseInputListener)
      • javax.swing.plaf.metal.MetalToolBarUI.MetalDockingListener
    • javax.swing.plaf.basic.BasicToolBarUI.PropertyListener (implements java.beans.PropertyChangeListener)
      • javax.swing.plaf.metal.MetalToolBarUI.MetalRolloverListener
    • javax.swing.plaf.basic.BasicToolBarUI.ToolBarContListener (implements java.awt.event.ContainerListener)
      • javax.swing.plaf.metal.MetalToolBarUI.MetalContainerListener
    • java.awt.Component (implements java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable)
      • java.awt.Container
        • javax.swing.JComponent (implements java.io.Serializable)
          • javax.swing.AbstractButton (implements java.awt.ItemSelectable, javax.swing.SwingConstants)
            • javax.swing.JButton (implements javax.accessibility.Accessible)
              • javax.swing.plaf.basic.BasicArrowButton (implements javax.swing.SwingConstants)
                • javax.swing.plaf.metal.MetalScrollButton
              • javax.swing.plaf.metal.MetalComboBoxButton
          • javax.swing.plaf.basic.BasicInternalFrameTitlePane
            • javax.swing.plaf.metal.MetalInternalFrameTitlePane
          • javax.swing.JLabel (implements javax.accessibility.Accessible, javax.swing.SwingConstants)
            • javax.swing.DefaultListCellRenderer (implements javax.swing.ListCellRenderer, java.io.Serializable)
              • javax.swing.plaf.metal.MetalFileChooserUI.FileRenderer
              • javax.swing.plaf.metal.MetalFileChooserUI.FilterComboBoxRenderer
          • javax.swing.JPopupMenu (implements javax.accessibility.Accessible, javax.swing.MenuElement)
            • javax.swing.plaf.basic.BasicComboPopup (implements javax.swing.plaf.basic.ComboPopup)
              • javax.swing.plaf.metal.MetalComboBoxUI.MetalComboPopup
    • javax.swing.plaf.ComponentUI
      • javax.swing.plaf.ButtonUI
        • javax.swing.plaf.basic.BasicButtonUI
          • javax.swing.plaf.basic.BasicToggleButtonUI
            • javax.swing.plaf.basic.BasicRadioButtonUI
              • javax.swing.plaf.metal.MetalRadioButtonUI
                • javax.swing.plaf.metal.MetalCheckBoxUI
            • javax.swing.plaf.metal.MetalToggleButtonUI
          • javax.swing.plaf.metal.MetalButtonUI
      • javax.swing.plaf.ComboBoxUI
        • javax.swing.plaf.basic.BasicComboBoxUI
          • javax.swing.plaf.metal.MetalComboBoxUI
      • javax.swing.plaf.DesktopIconUI
        • javax.swing.plaf.basic.BasicDesktopIconUI
          • javax.swing.plaf.metal.MetalDesktopIconUI
      • javax.swing.plaf.FileChooserUI
        • javax.swing.plaf.basic.BasicFileChooserUI
          • javax.swing.plaf.metal.MetalFileChooserUI
      • javax.swing.plaf.InternalFrameUI
        • javax.swing.plaf.basic.BasicInternalFrameUI
          • javax.swing.plaf.metal.MetalInternalFrameUI
      • javax.swing.plaf.LabelUI
        • javax.swing.plaf.basic.BasicLabelUI (implements java.beans.PropertyChangeListener)
          • javax.swing.plaf.metal.MetalLabelUI
      • javax.swing.plaf.MenuBarUI
        • javax.swing.plaf.basic.BasicMenuBarUI
          • javax.swing.plaf.metal.MetalMenuBarUI
      • javax.swing.plaf.ProgressBarUI
        • javax.swing.plaf.basic.BasicProgressBarUI
          • javax.swing.plaf.metal.MetalProgressBarUI
      • javax.swing.plaf.RootPaneUI
        • javax.swing.plaf.basic.BasicRootPaneUI (implements java.beans.PropertyChangeListener)
          • javax.swing.plaf.metal.MetalRootPaneUI
      • javax.swing.plaf.ScrollBarUI
        • javax.swing.plaf.basic.BasicScrollBarUI (implements java.awt.LayoutManager, javax.swing.SwingConstants)
          • javax.swing.plaf.metal.MetalScrollBarUI
      • javax.swing.plaf.ScrollPaneUI
        • javax.swing.plaf.basic.BasicScrollPaneUI (implements javax.swing.ScrollPaneConstants)
          • javax.swing.plaf.metal.MetalScrollPaneUI
      • javax.swing.plaf.SeparatorUI
        • javax.swing.plaf.basic.BasicSeparatorUI
          • javax.swing.plaf.metal.MetalSeparatorUI
            • javax.swing.plaf.metal.MetalPopupMenuSeparatorUI
      • javax.swing.plaf.SliderUI
        • javax.swing.plaf.basic.BasicSliderUI
          • javax.swing.plaf.metal.MetalSliderUI
      • javax.swing.plaf.SplitPaneUI
        • javax.swing.plaf.basic.BasicSplitPaneUI
          • javax.swing.plaf.metal.MetalSplitPaneUI
      • javax.swing.plaf.TabbedPaneUI
        • javax.swing.plaf.basic.BasicTabbedPaneUI (implements javax.swing.SwingConstants)
          • javax.swing.plaf.metal.MetalTabbedPaneUI
      • javax.swing.plaf.TextUI
        • javax.swing.plaf.basic.BasicTextUI (implements javax.swing.text.ViewFactory)
          • javax.swing.plaf.basic.BasicTextFieldUI
            • javax.swing.plaf.metal.MetalTextFieldUI
      • javax.swing.plaf.ToolBarUI
        • javax.swing.plaf.basic.BasicToolBarUI (implements javax.swing.SwingConstants)
          • javax.swing.plaf.metal.MetalToolBarUI
      • javax.swing.plaf.ToolTipUI
        • javax.swing.plaf.basic.BasicToolTipUI
          • javax.swing.plaf.metal.MetalToolTipUI
      • javax.swing.plaf.TreeUI
        • javax.swing.plaf.basic.BasicTreeUI
          • javax.swing.plaf.metal.MetalTreeUI
    • javax.swing.LookAndFeel
      • javax.swing.plaf.basic.BasicLookAndFeel (implements java.io.Serializable)
        • javax.swing.plaf.metal.MetalLookAndFeel
    • javax.swing.plaf.metal.MetalBorders
    • javax.swing.plaf.metal.MetalCheckBoxIcon (implements javax.swing.Icon, java.io.Serializable, javax.swing.plaf.UIResource)
    • javax.swing.plaf.metal.MetalComboBoxIcon (implements javax.swing.Icon, java.io.Serializable)
    • javax.swing.plaf.metal.MetalIconFactory (implements java.io.Serializable)
    • javax.swing.plaf.metal.MetalIconFactory.FileIcon16 (implements javax.swing.Icon, java.io.Serializable)
      • javax.swing.plaf.metal.MetalIconFactory.TreeLeafIcon
    • javax.swing.plaf.metal.MetalIconFactory.FolderIcon16 (implements javax.swing.Icon, java.io.Serializable)
      • javax.swing.plaf.metal.MetalIconFactory.TreeFolderIcon
    • javax.swing.plaf.metal.MetalIconFactory.PaletteCloseIcon (implements javax.swing.Icon, java.io.Serializable, javax.swing.plaf.UIResource)
    • javax.swing.plaf.metal.MetalIconFactory.TreeControlIcon (implements javax.swing.Icon, java.io.Serializable)
    • javax.swing.plaf.metal.MetalTheme
      • javax.swing.plaf.metal.DefaultMetalTheme
        • javax.swing.plaf.metal.OceanTheme
    • java.awt.event.MouseAdapter (implements java.awt.event.MouseListener, java.awt.event.MouseMotionListener, java.awt.event.MouseWheelListener)
      • javax.swing.plaf.metal.MetalFileChooserUI.SingleClickListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.swing.plaf.metal

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.swing.plaf.metal

Packages that use javax.swing.plaf.metal
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Classes in javax.swing.plaf.metal used by javax.swing.plaf.metal
DefaultMetalTheme
A concrete implementation of MetalTheme providing the original look of the Java Look and Feel, code-named "Steel".
MetalBorders.ButtonBorder
MetalBorders.Flush3DBorder
MetalComboBoxEditor
The default editor for Metal editable combo boxes
MetalComboBoxUI.MetalComboBoxLayoutManager
This inner class is marked "public" due to a compiler bug.
MetalFileChooserUI.DirectoryComboBoxModel
Data model for a type-face selection combo-box.
MetalFileChooserUI.FilterComboBoxModel
Data model for a type-face selection combo-box.
MetalFileChooserUI.FilterComboBoxRenderer
Render different type sizes and styles.
MetalIconFactory.FileIcon16
Warning: Serialized objects of this class will not be compatible with future Swing releases.
MetalIconFactory.FolderIcon16
Warning: Serialized objects of this class will not be compatible with future Swing releases.
MetalLabelUI
A Windows L&F implementation of LabelUI.
MetalRadioButtonUI
RadioButtonUI implementation for MetalRadioButtonUI
MetalScrollButton
JButton object for Metal scrollbar arrows.
MetalSeparatorUI
A Metal L&F implementation of SeparatorUI.
MetalTheme
MetalTheme provides the color palette and fonts used by the Java Look and Feel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.DefaultMetalTheme

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.DefaultMetalTheme

Packages that use DefaultMetalTheme
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of DefaultMetalTheme in javax.swing.plaf.metal

Subclasses of DefaultMetalTheme in javax.swing.plaf.metal
 class OceanTheme
The default theme for the MetalLookAndFeel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalBorders

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalBorders

No usage of javax.swing.plaf.metal.MetalBorders

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalBorders.ButtonBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalBorders.ButtonBorder

Packages that use MetalBorders.ButtonBorder
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of MetalBorders.ButtonBorder in javax.swing.plaf.metal

Subclasses of MetalBorders.ButtonBorder in javax.swing.plaf.metal
static class | MetalBorders.RolloverButtonBorder
static class | MetalBorders.ToggleButtonBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalBorders.Flush3DBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalBorders.Flush3DBorder

Packages that use MetalBorders.Flush3DBorder
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of MetalBorders.Flush3DBorder in javax.swing.plaf.metal

Subclasses of MetalBorders.Flush3DBorder in javax.swing.plaf.metal
static class MetalBorders.TextFieldBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalBorders.InternalFrameBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalBorders.InternalFrameBorder

No usage of javax.swing.plaf.metal.MetalBorders.InternalFrameBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalBorders.MenuBarBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalBorders.MenuBarBorder

No usage of javax.swing.plaf.metal.MetalBorders.MenuBarBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalBorders.MenuItemBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalBorders.MenuItemBorder

No usage of javax.swing.plaf.metal.MetalBorders.MenuItemBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalBorders.OptionDialogBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalBorders.OptionDialogBorder

No usage of javax.swing.plaf.metal.MetalBorders.OptionDialogBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalBorders.PaletteBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalBorders.PaletteBorder

No usage of javax.swing.plaf.metal.MetalBorders.PaletteBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalBorders.PopupMenuBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalBorders.PopupMenuBorder

No usage of javax.swing.plaf.metal.MetalBorders.PopupMenuBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalBorders.RolloverButtonBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalBorders.RolloverButtonBorder

No usage of javax.swing.plaf.metal.MetalBorders.RolloverButtonBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalBorders.ScrollPaneBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalBorders.ScrollPaneBorder

No usage of javax.swing.plaf.metal.MetalBorders.ScrollPaneBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalBorders.TableHeaderBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalBorders.TableHeaderBorder

No usage of javax.swing.plaf.metal.MetalBorders.TableHeaderBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalBorders.TextFieldBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalBorders.TextFieldBorder

No usage of javax.swing.plaf.metal.MetalBorders.TextFieldBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalBorders.ToggleButtonBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalBorders.ToggleButtonBorder

No usage of javax.swing.plaf.metal.MetalBorders.ToggleButtonBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalBorders.ToolBarBorder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalBorders.ToolBarBorder

No usage of javax.swing.plaf.metal.MetalBorders.ToolBarBorder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalButtonUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalButtonUI

No usage of javax.swing.plaf.metal.MetalButtonUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalCheckBoxIcon

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalCheckBoxIcon

No usage of javax.swing.plaf.metal.MetalCheckBoxIcon

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalCheckBoxUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalCheckBoxUI

No usage of javax.swing.plaf.metal.MetalCheckBoxUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalComboBoxButton

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalComboBoxButton

No usage of javax.swing.plaf.metal.MetalComboBoxButton

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalComboBoxEditor

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalComboBoxEditor

Packages that use MetalComboBoxEditor
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of MetalComboBoxEditor in javax.swing.plaf.metal

Subclasses of MetalComboBoxEditor in javax.swing.plaf.metal
static class MetalComboBoxEditor.UIResource
A subclass of BasicComboBoxEditor that implements UIResource.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalComboBoxEditor.UIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalComboBoxEditor.UIResource

No usage of javax.swing.plaf.metal.MetalComboBoxEditor.UIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalComboBoxIcon

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalComboBoxIcon

No usage of javax.swing.plaf.metal.MetalComboBoxIcon

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalComboBoxUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalComboBoxUI

No usage of javax.swing.plaf.metal.MetalComboBoxUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalComboBoxUI.MetalComboBoxLayoutManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalComboBoxUI.MetalComboBoxLayoutManager

Packages that use MetalComboBoxUI.MetalComboBoxLayoutManager
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of MetalComboBoxUI.MetalComboBoxLayoutManager in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal with parameters of type MetalComboBoxUI.MetalComboBoxLayoutManager
 void MetalComboBoxUI.layoutComboBox(Container parent, MetalComboBoxUI.MetalComboBoxLayoutManager manager)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalComboBoxUI.MetalComboPopup

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalComboBoxUI.MetalComboPopup

No usage of javax.swing.plaf.metal.MetalComboBoxUI.MetalComboPopup

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalComboBoxUI.MetalPropertyChangeListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalComboBoxUI.MetalPropertyChangeListener

No usage of javax.swing.plaf.metal.MetalComboBoxUI.MetalPropertyChangeListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalDesktopIconUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalDesktopIconUI

No usage of javax.swing.plaf.metal.MetalDesktopIconUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalFileChooserUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalFileChooserUI

No usage of javax.swing.plaf.metal.MetalFileChooserUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalFileChooserUI.DirectoryComboBoxAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalFileChooserUI.DirectoryComboBoxAction

No usage of javax.swing.plaf.metal.MetalFileChooserUI.DirectoryComboBoxAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalFileChooserUI.DirectoryComboBoxModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalFileChooserUI.DirectoryComboBoxModel

Packages that use MetalFileChooserUI.DirectoryComboBoxModel
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of MetalFileChooserUI.DirectoryComboBoxModel in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal that return MetalFileChooserUI.DirectoryComboBoxModel
protected  MetalFileChooserUI.DirectoryComboBoxModel MetalFileChooserUI.createDirectoryComboBoxModel(JFileChooser fc)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalFileChooserUI.FileRenderer

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalFileChooserUI.FileRenderer

No usage of javax.swing.plaf.metal.MetalFileChooserUI.FileRenderer

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalFileChooserUI.FilterComboBoxModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalFileChooserUI.FilterComboBoxModel

Packages that use MetalFileChooserUI.FilterComboBoxModel
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of MetalFileChooserUI.FilterComboBoxModel in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal that return MetalFileChooserUI.FilterComboBoxModel
protected  MetalFileChooserUI.FilterComboBoxModel MetalFileChooserUI.createFilterComboBoxModel()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalFileChooserUI.FilterComboBoxRenderer

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalFileChooserUI.FilterComboBoxRenderer

Packages that use MetalFileChooserUI.FilterComboBoxRenderer
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of MetalFileChooserUI.FilterComboBoxRenderer in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal that return MetalFileChooserUI.FilterComboBoxRenderer
protected  MetalFileChooserUI.FilterComboBoxRenderer MetalFileChooserUI.createFilterComboBoxRenderer()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalFileChooserUI.SingleClickListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalFileChooserUI.SingleClickListener

No usage of javax.swing.plaf.metal.MetalFileChooserUI.SingleClickListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalIconFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalIconFactory

No usage of javax.swing.plaf.metal.MetalIconFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalIconFactory.FileIcon16

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalIconFactory.FileIcon16

Packages that use MetalIconFactory.FileIcon16
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of MetalIconFactory.FileIcon16 in javax.swing.plaf.metal

Subclasses of MetalIconFactory.FileIcon16 in javax.swing.plaf.metal
static class MetalIconFactory.TreeLeafIcon

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalIconFactory.FolderIcon16

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalIconFactory.FolderIcon16

Packages that use MetalIconFactory.FolderIcon16
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of MetalIconFactory.FolderIcon16 in javax.swing.plaf.metal

Subclasses of MetalIconFactory.FolderIcon16 in javax.swing.plaf.metal
static class MetalIconFactory.TreeFolderIcon
Warning: Serialized objects of this class will not be compatible with future Swing releases.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalIconFactory.PaletteCloseIcon

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalIconFactory.PaletteCloseIcon

No usage of javax.swing.plaf.metal.MetalIconFactory.PaletteCloseIcon

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalIconFactory.TreeControlIcon

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalIconFactory.TreeControlIcon

No usage of javax.swing.plaf.metal.MetalIconFactory.TreeControlIcon

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalIconFactory.TreeFolderIcon

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalIconFactory.TreeFolderIcon

No usage of javax.swing.plaf.metal.MetalIconFactory.TreeFolderIcon

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalIconFactory.TreeLeafIcon

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalIconFactory.TreeLeafIcon

No usage of javax.swing.plaf.metal.MetalIconFactory.TreeLeafIcon

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalInternalFrameTitlePane

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalInternalFrameTitlePane

No usage of javax.swing.plaf.metal.MetalInternalFrameTitlePane

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalInternalFrameUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalInternalFrameUI

No usage of javax.swing.plaf.metal.MetalInternalFrameUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalLabelUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalLabelUI

Packages that use MetalLabelUI
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of MetalLabelUI in javax.swing.plaf.metal

Fields in javax.swing.plaf.metal declared as MetalLabelUI
protected static MetalLabelUI MetalLabelUI.metalLabelUI
The default MetalLabelUI instance.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalLookAndFeel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalLookAndFeel

No usage of javax.swing.plaf.metal.MetalLookAndFeel

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalMenuBarUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalMenuBarUI

No usage of javax.swing.plaf.metal.MetalMenuBarUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalPopupMenuSeparatorUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalPopupMenuSeparatorUI

No usage of javax.swing.plaf.metal.MetalPopupMenuSeparatorUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalProgressBarUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalProgressBarUI

No usage of javax.swing.plaf.metal.MetalProgressBarUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalRadioButtonUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalRadioButtonUI

Packages that use MetalRadioButtonUI
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of MetalRadioButtonUI in javax.swing.plaf.metal

Subclasses of MetalRadioButtonUI in javax.swing.plaf.metal
 class MetalCheckBoxUI
CheckboxUI implementation for MetalCheckboxUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalRootPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalRootPaneUI

No usage of javax.swing.plaf.metal.MetalRootPaneUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalScrollBarUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalScrollBarUI

No usage of javax.swing.plaf.metal.MetalScrollBarUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalScrollButton

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalScrollButton

Packages that use MetalScrollButton
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of MetalScrollButton in javax.swing.plaf.metal

Fields in javax.swing.plaf.metal declared as MetalScrollButton
protected MetalScrollButton | MetalScrollBarUI.decreaseButton
protected MetalScrollButton | MetalScrollBarUI.increaseButton

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalScrollPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalScrollPaneUI

No usage of javax.swing.plaf.metal.MetalScrollPaneUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalSeparatorUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalSeparatorUI

Packages that use MetalSeparatorUI
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of MetalSeparatorUI in javax.swing.plaf.metal

Subclasses of MetalSeparatorUI in javax.swing.plaf.metal
 class MetalPopupMenuSeparatorUI
A Metal L&F implementation of PopupMenuSeparatorUI.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalSliderUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalSliderUI

No usage of javax.swing.plaf.metal.MetalSliderUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalSliderUI.MetalPropertyListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalSliderUI.MetalPropertyListener

No usage of javax.swing.plaf.metal.MetalSliderUI.MetalPropertyListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalSplitPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalSplitPaneUI

No usage of javax.swing.plaf.metal.MetalSplitPaneUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalTabbedPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalTabbedPaneUI

No usage of javax.swing.plaf.metal.MetalTabbedPaneUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalTabbedPaneUI.TabbedPaneLayout

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalTabbedPaneUI.TabbedPaneLayout

No usage of javax.swing.plaf.metal.MetalTabbedPaneUI.TabbedPaneLayout

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalTextFieldUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalTextFieldUI

No usage of javax.swing.plaf.metal.MetalTextFieldUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalTheme

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalTheme

Packages that use MetalTheme
javax.swing.plaf.metal Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.

Uses of MetalTheme in javax.swing.plaf.metal

Subclasses of MetalTheme in javax.swing.plaf.metal
class | DefaultMetalTheme A concrete implementation of MetalTheme providing the original look of the Java Look and Feel, code-named "Steel".
class | OceanTheme The default theme for the MetalLookAndFeel.

Methods in javax.swing.plaf.metal that return MetalTheme
static MetalTheme MetalLookAndFeel.getCurrentTheme()
Return the theme currently being used by MetalLookAndFeel.

Methods in javax.swing.plaf.metal with parameters of type MetalTheme
static void MetalLookAndFeel.setCurrentTheme(MetalTheme theme)
Set the theme used by MetalLookAndFeel.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalToggleButtonUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalToggleButtonUI

No usage of javax.swing.plaf.metal.MetalToggleButtonUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalToolBarUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalToolBarUI

No usage of javax.swing.plaf.metal.MetalToolBarUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalToolBarUI.MetalContainerListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalToolBarUI.MetalContainerListener

No usage of javax.swing.plaf.metal.MetalToolBarUI.MetalContainerListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalToolBarUI.MetalDockingListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalToolBarUI.MetalDockingListener

No usage of javax.swing.plaf.metal.MetalToolBarUI.MetalDockingListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalToolBarUI.MetalRolloverListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalToolBarUI.MetalRolloverListener

No usage of javax.swing.plaf.metal.MetalToolBarUI.MetalRolloverListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalToolTipUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalToolTipUI

No usage of javax.swing.plaf.metal.MetalToolTipUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.MetalTreeUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.MetalTreeUI

No usage of javax.swing.plaf.metal.MetalTreeUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.metal.OceanTheme

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.metal.OceanTheme

No usage of javax.swing.plaf.metal.OceanTheme

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DefaultMetalTheme

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class DefaultMetalTheme

java.lang.Object
    extended by  javax.swing.plaf.metal.MetalTheme
        extended by  javax.swing.plaf.metal.DefaultMetalTheme
Direct Known Subclasses:
OceanTheme
public class DefaultMetalTheme
extends MetalTheme

A concrete implementation of MetalTheme providing the original look of the Java Look and Feel, code-named "Steel". Refer to MetalLookAndFeel.setCurrentTheme(javax.swing.plaf.metal.MetalTheme) for details on changing the default theme.

All colors returned by DefaultMetalTheme are completely opaque.

Font Style

DefaultMetalTheme uses bold fonts for many controls. To make all controls (with the exception of the internal frame title bars and client decorated frame title bars) use plain fonts you can do either of the following:
  • Set the system property swing.boldMetal to false. For example, java -Dswing.boldMetal=false MyApp.
  • Set the defaults property swing.boldMetal to Boolean.FALSE. For example: UIManager.put("swing.boldMetal", Boolean.FALSE);
The defaults property swing.boldMetal, if set, takes precendence over the system property of the same name. After setting this defaults property you need to re-install MetalLookAndFeel, as well as update the UI of any previously created widgets. Otherwise the results are undefined. The following illustrates how to do this:
   // turn off bold fonts
   UIManager.put("swing.boldMetal", Boolean.FALSE);

   // re-install the Metal Look and Feel
   UIManager.setLookAndFeel(new MetalLookAndFeel());

   // Update the ComponentUIs for all Components. This
   // needs to be invoked for all windows.
   SwingUtilities.updateComponentTreeUI(rootComponent);

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
MetalLookAndFeel, MetalLookAndFeel.setCurrentTheme(javax.swing.plaf.metal.MetalTheme)

Constructor Summary
DefaultMetalTheme()
Creates and returns an instance of DefaultMetalTheme.
Method Summary
FontUIResource | getControlTextFont() Returns the control text font.
FontUIResource | getMenuTextFont() Returns the menu text font.
String | getName() Returns the name of this theme.
protected ColorUIResource | getPrimary1() Returns the primary 1 color.
protected ColorUIResource | getPrimary2() Returns the primary 2 color.
protected ColorUIResource | getPrimary3() Returns the primary 3 color.
protected ColorUIResource | getSecondary1() Returns the secondary 1 color.
protected ColorUIResource | getSecondary2() Returns the secondary 2 color.
protected ColorUIResource | getSecondary3() Returns the secondary 3 color.
FontUIResource | getSubTextFont() Returns the sub-text font.
FontUIResource | getSystemTextFont() Returns the system text font.
FontUIResource | getUserTextFont() Returns the user text font.
FontUIResource | getWindowTitleFont() Returns the window title font.
Methods inherited from class javax.swing.plaf.metal.MetalTheme
addCustomEntriesToTable, getAcceleratorForeground, getAcceleratorSelectedForeground, getBlack, getControl, getControlDarkShadow, getControlDisabled, getControlHighlight, getControlInfo, getControlShadow, getControlTextColor, getDesktopColor, getFocusColor, getHighlightedTextColor, getInactiveControlTextColor, getInactiveSystemTextColor, getMenuBackground, getMenuDisabledForeground, getMenuForeground, getMenuSelectedBackground, getMenuSelectedForeground, getPrimaryControl, getPrimaryControlDarkShadow, getPrimaryControlHighlight, getPrimaryControlInfo, getPrimaryControlShadow, getSeparatorBackground, getSeparatorForeground, getSystemTextColor, getTextHighlightColor, getUserTextColor, getWhite, getWindowBackground, getWindowTitleBackground, getWindowTitleForeground, getWindowTitleInactiveBackground, getWindowTitleInactiveForeground
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultMetalTheme

public DefaultMetalTheme()
Creates and returns an instance of DefaultMetalTheme.

Method Detail

getName

public String getName()
Returns the name of this theme. This returns "Steel".

Specified by:
getName in class MetalTheme
Returns:
the name of this theme.

getPrimary1

protected ColorUIResource getPrimary1()
Returns the primary 1 color. This returns a color with rgb values of 102, 102, and 153, respectively.

Specified by:
getPrimary1 in class MetalTheme
Returns:
the primary 1 color

getPrimary2

protected ColorUIResource getPrimary2()
Returns the primary 2 color. This returns a color with rgb values of 153, 153, 204, respectively.

Specified by:
getPrimary2 in class MetalTheme
Returns:
the primary 2 color

getPrimary3

protected ColorUIResource getPrimary3()
Returns the primary 3 color. This returns a color with rgb values 204, 204, 255, respectively.

Specified by:
getPrimary3 in class MetalTheme
Returns:
the primary 3 color

getSecondary1

protected ColorUIResource getSecondary1()
Returns the secondary 1 color. This returns a color with rgb values 102, 102, and 102, respectively.

Specified by:
getSecondary1 in class MetalTheme
Returns:
the secondary 1 color

getSecondary2

protected ColorUIResource getSecondary2()
Returns the secondary 2 color. This returns a color with rgb values 153, 153, and 153, respectively.

Specified by:
getSecondary2 in class MetalTheme
Returns:
the secondary 2 color

getSecondary3

protected ColorUIResource getSecondary3()
Returns the secondary 3 color. This returns a color with rgb values 204, 204, and 204, respectively.

Specified by:
getSecondary3 in class MetalTheme
Returns:
the secondary 3 color

getControlTextFont

public FontUIResource getControlTextFont()
Returns the control text font. This returns Dialog, 12pt. If plain fonts have been enabled as described in font style, the font style is plain. Otherwise the font style is bold.

Specified by:
getControlTextFont in class MetalTheme
Returns:
the control text font

getSystemTextFont

public FontUIResource getSystemTextFont()
Returns the system text font. This returns Dialog, 12pt, plain.

Specified by:
getSystemTextFont in class MetalTheme
Returns:
the sytem text font

getUserTextFont

public FontUIResource getUserTextFont()
Returns the user text font. This returns Dialog, 12pt, plain.

Specified by:
getUserTextFont in class MetalTheme
Returns:
the user text font

getMenuTextFont

public FontUIResource getMenuTextFont()
Returns the menu text font. This returns Dialog, 12pt. If plain fonts have been enabled as described in font style, the font style is plain. Otherwise the font style is bold.

Specified by:
getMenuTextFont in class MetalTheme
Returns:
the menu text font

getWindowTitleFont

public FontUIResource getWindowTitleFont()
Returns the window title font. This returns Dialog, 12pt, bold.

Specified by:
getWindowTitleFont in class MetalTheme
Returns:
the window title font

getSubTextFont

public FontUIResource getSubTextFont()
Returns the sub-text font. This returns Dialog, 10pt, plain.

Specified by:
getSubTextFont in class MetalTheme
Returns:
the sub-text font
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


MetalBorders

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalBorders

java.lang.Object
    extended by  javax.swing.plaf.metal.MetalBorders

public class MetalBorders
extends Object

Factory object that can vend Borders appropriate for the metal L & F.

Nested Class Summary
static class | MetalBorders.ButtonBorder
static class | MetalBorders.Flush3DBorder
static class | MetalBorders.InternalFrameBorder
static class | MetalBorders.MenuBarBorder
static class | MetalBorders.MenuItemBorder
static class | MetalBorders.OptionDialogBorder
static class | MetalBorders.PaletteBorder Border for a Palette.
static class | MetalBorders.PopupMenuBorder
static class | MetalBorders.RolloverButtonBorder
static class | MetalBorders.ScrollPaneBorder
static class | MetalBorders.TableHeaderBorder Border for a Table Header
static class | MetalBorders.TextFieldBorder
static class | MetalBorders.ToggleButtonBorder
static class | MetalBorders.ToolBarBorder
Constructor Summary
MetalBorders()
Method Summary
static Border | getButtonBorder() Returns a border instance for a JButton
static Border | getDesktopIconBorder() Returns a border instance for a Desktop Icon
static Border | getTextBorder() Returns a border instance for a text component
static Border | getTextFieldBorder() Returns a border instance for a JTextField
static Border | getToggleButtonBorder() Returns a border instance for a JToggleButton
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalBorders

public MetalBorders()
Method Detail

getButtonBorder

public static Border getButtonBorder()
Returns a border instance for a JButton

Since:
1.3

getTextBorder

public static Border getTextBorder()
Returns a border instance for a text component

Since:
1.3

getTextFieldBorder

public static Border getTextFieldBorder()
Returns a border instance for a JTextField

Since:
1.3

getToggleButtonBorder

public static Border getToggleButtonBorder()
Returns a border instance for a JToggleButton

Since:
1.3

getDesktopIconBorder

public static Border getDesktopIconBorder()
Returns a border instance for a Desktop Icon

Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalBorders.ButtonBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalBorders.ButtonBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.metal.MetalBorders.ButtonBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Direct Known Subclasses:
MetalBorders.RolloverButtonBorder, MetalBorders.ToggleButtonBorder
Enclosing class:
MetalBorders
public static class MetalBorders.ButtonBorder
extends AbstractBorder
implements UIResource

Field Summary
protected static Insets borderInsets
Constructor Summary
MetalBorders.ButtonBorder()
Method Summary
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
Insets | getBorderInsets(Component c, Insets newInsets) Reinitializes the insets parameter with this Border's current Insets.
void | paintBorder(Component c, Graphics g, int x, int y, int w, int h) This default implementation does no painting.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

borderInsets

protected static Insets borderInsets
Constructor Detail

MetalBorders.ButtonBorder

public MetalBorders.ButtonBorder()
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int w,
                        int h)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
w - the width of the painted border
h - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from class: AbstractBorder
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets newInsets)
Description copied from class: AbstractBorder
Reinitializes the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
newInsets - the object to be reinitialized
Returns:
the insets object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalBorders.Flush3DBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalBorders.Flush3DBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.metal.MetalBorders.Flush3DBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Direct Known Subclasses:
MetalBorders.TextFieldBorder
Enclosing class:
MetalBorders
public static class MetalBorders.Flush3DBorder
extends AbstractBorder
implements UIResource

Constructor Summary
MetalBorders.Flush3DBorder()
Method Summary
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
Insets | getBorderInsets(Component c, Insets newInsets) Reinitializes the insets parameter with this Border's current Insets.
void | paintBorder(Component c, Graphics g, int x, int y, int w, int h) This default implementation does no painting.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalBorders.Flush3DBorder

public MetalBorders.Flush3DBorder()
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int w,
                        int h)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
w - the width of the painted border
h - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from class: AbstractBorder
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets newInsets)
Description copied from class: AbstractBorder
Reinitializes the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
newInsets - the object to be reinitialized
Returns:
the insets object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalBorders.InternalFrameBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalBorders.InternalFrameBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.metal.MetalBorders.InternalFrameBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
MetalBorders
public static class MetalBorders.InternalFrameBorder
extends AbstractBorder
implements UIResource

Constructor Summary
MetalBorders.InternalFrameBorder()
Method Summary
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
Insets | getBorderInsets(Component c, Insets newInsets) Reinitializes the insets parameter with this Border's current Insets.
void | paintBorder(Component c, Graphics g, int x, int y, int w, int h) This default implementation does no painting.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalBorders.InternalFrameBorder

public MetalBorders.InternalFrameBorder()
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int w,
                        int h)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
w - the width of the painted border
h - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from class: AbstractBorder
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets newInsets)
Description copied from class: AbstractBorder
Reinitializes the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
newInsets - the object to be reinitialized
Returns:
the insets object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalBorders.MenuBarBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalBorders.MenuBarBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.metal.MetalBorders.MenuBarBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
MetalBorders
public static class MetalBorders.MenuBarBorder
extends AbstractBorder
implements UIResource

Field Summary
protected static Insets borderInsets
Constructor Summary
MetalBorders.MenuBarBorder()
Method Summary
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
Insets | getBorderInsets(Component c, Insets newInsets) Reinitializes the insets parameter with this Border's current Insets.
void | paintBorder(Component c, Graphics g, int x, int y, int w, int h) This default implementation does no painting.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

borderInsets

protected static Insets borderInsets
Constructor Detail

MetalBorders.MenuBarBorder

public MetalBorders.MenuBarBorder()
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int w,
                        int h)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
w - the width of the painted border
h - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from class: AbstractBorder
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets newInsets)
Description copied from class: AbstractBorder
Reinitializes the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
newInsets - the object to be reinitialized
Returns:
the insets object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalBorders.MenuItemBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalBorders.MenuItemBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.metal.MetalBorders.MenuItemBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
MetalBorders
public static class MetalBorders.MenuItemBorder
extends AbstractBorder
implements UIResource

Field Summary
protected static Insets borderInsets
Constructor Summary
MetalBorders.MenuItemBorder()
Method Summary
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
Insets | getBorderInsets(Component c, Insets newInsets) Reinitializes the insets parameter with this Border's current Insets.
void | paintBorder(Component c, Graphics g, int x, int y, int w, int h) This default implementation does no painting.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

borderInsets

protected static Insets borderInsets
Constructor Detail

MetalBorders.MenuItemBorder

public MetalBorders.MenuItemBorder()
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int w,
                        int h)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
w - the width of the painted border
h - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from class: AbstractBorder
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets newInsets)
Description copied from class: AbstractBorder
Reinitializes the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
newInsets - the object to be reinitialized
Returns:
the insets object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalBorders.OptionDialogBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalBorders.OptionDialogBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.metal.MetalBorders.OptionDialogBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
MetalBorders
public static class MetalBorders.OptionDialogBorder
extends AbstractBorder
implements UIResource

Constructor Summary
MetalBorders.OptionDialogBorder()
Method Summary
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
Insets | getBorderInsets(Component c, Insets newInsets) Reinitializes the insets parameter with this Border's current Insets.
void | paintBorder(Component c, Graphics g, int x, int y, int w, int h) This default implementation does no painting.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalBorders.OptionDialogBorder

public MetalBorders.OptionDialogBorder()
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int w,
                        int h)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
w - the width of the painted border
h - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from class: AbstractBorder
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets newInsets)
Description copied from class: AbstractBorder
Reinitializes the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
newInsets - the object to be reinitialized
Returns:
the insets object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalBorders.PaletteBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalBorders.PaletteBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.metal.MetalBorders.PaletteBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
MetalBorders
public static class MetalBorders.PaletteBorder
extends AbstractBorder
implements UIResource

Border for a Palette.

Since:
1.3

Constructor Summary
MetalBorders.PaletteBorder()
Method Summary
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
Insets | getBorderInsets(Component c, Insets newInsets) Reinitializes the insets parameter with this Border's current Insets.
void | paintBorder(Component c, Graphics g, int x, int y, int w, int h) This default implementation does no painting.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalBorders.PaletteBorder

public MetalBorders.PaletteBorder()
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int w,
                        int h)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
w - the width of the painted border
h - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from class: AbstractBorder
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets newInsets)
Description copied from class: AbstractBorder
Reinitializes the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
newInsets - the object to be reinitialized
Returns:
the insets object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalBorders.PopupMenuBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalBorders.PopupMenuBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.metal.MetalBorders.PopupMenuBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
MetalBorders
public static class MetalBorders.PopupMenuBorder
extends AbstractBorder
implements UIResource

Field Summary
protected static Insets borderInsets
Constructor Summary
MetalBorders.PopupMenuBorder()
Method Summary
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
Insets | getBorderInsets(Component c, Insets newInsets) Reinitializes the insets parameter with this Border's current Insets.
void | paintBorder(Component c, Graphics g, int x, int y, int w, int h) This default implementation does no painting.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

borderInsets

protected static Insets borderInsets
Constructor Detail

MetalBorders.PopupMenuBorder

public MetalBorders.PopupMenuBorder()
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int w,
                        int h)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
w - the width of the painted border
h - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from class: AbstractBorder
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets newInsets)
Description copied from class: AbstractBorder
Reinitializes the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
newInsets - the object to be reinitialized
Returns:
the insets object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalBorders.RolloverButtonBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalBorders.RolloverButtonBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.metal.MetalBorders.ButtonBorder
            extended by  javax.swing.plaf.metal.MetalBorders.RolloverButtonBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
MetalBorders
public static class MetalBorders.RolloverButtonBorder
extends MetalBorders.ButtonBorder

Field Summary
Fields inherited from class javax.swing.plaf.metal.MetalBorders.ButtonBorder
borderInsets
Constructor Summary
MetalBorders.RolloverButtonBorder()
Method Summary
 void paintBorder(Component c, Graphics g, int x, int y, int w, int h)
This default implementation does no painting.
Methods inherited from class javax.swing.plaf.metal.MetalBorders.ButtonBorder
getBorderInsets, getBorderInsets
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalBorders.RolloverButtonBorder

public MetalBorders.RolloverButtonBorder()
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int w,
                        int h)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class MetalBorders.ButtonBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
w - the width of the painted border
h - the height of the painted border
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalBorders.ScrollPaneBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalBorders.ScrollPaneBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.metal.MetalBorders.ScrollPaneBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
MetalBorders
public static class MetalBorders.ScrollPaneBorder
extends AbstractBorder
implements UIResource

Constructor Summary
MetalBorders.ScrollPaneBorder()
Method Summary
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
void | paintBorder(Component c, Graphics g, int x, int y, int w, int h) This default implementation does no painting.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getBorderInsets, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalBorders.ScrollPaneBorder

public MetalBorders.ScrollPaneBorder()
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int w,
                        int h)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
w - the width of the painted border
h - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from class: AbstractBorder
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalBorders.TableHeaderBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalBorders.TableHeaderBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.metal.MetalBorders.TableHeaderBorder
All Implemented Interfaces:
Serializable, Border
Enclosing class:
MetalBorders
public static class MetalBorders.TableHeaderBorder
extends AbstractBorder

Border for a Table Header

Since:
1.3

Field Summary
protected  Insets editorBorderInsets
Constructor Summary
MetalBorders.TableHeaderBorder()
Method Summary
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
void | paintBorder(Component c, Graphics g, int x, int y, int w, int h) This default implementation does no painting.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getBorderInsets, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

editorBorderInsets

protected Insets editorBorderInsets
Constructor Detail

MetalBorders.TableHeaderBorder

public MetalBorders.TableHeaderBorder()
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int w,
                        int h)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
w - the width of the painted border
h - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from class: AbstractBorder
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalBorders.TextFieldBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalBorders.TextFieldBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.metal.MetalBorders.Flush3DBorder
            extended by  javax.swing.plaf.metal.MetalBorders.TextFieldBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
MetalBorders
public static class MetalBorders.TextFieldBorder
extends MetalBorders.Flush3DBorder

Constructor Summary
MetalBorders.TextFieldBorder()
Method Summary
 void paintBorder(Component c, Graphics g, int x, int y, int w, int h)
This default implementation does no painting.
Methods inherited from class javax.swing.plaf.metal.MetalBorders.Flush3DBorder
getBorderInsets, getBorderInsets
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalBorders.TextFieldBorder

public MetalBorders.TextFieldBorder()
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int w,
                        int h)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class MetalBorders.Flush3DBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
w - the width of the painted border
h - the height of the painted border
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalBorders.ToggleButtonBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalBorders.ToggleButtonBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.metal.MetalBorders.ButtonBorder
            extended by  javax.swing.plaf.metal.MetalBorders.ToggleButtonBorder
All Implemented Interfaces:
Serializable, Border, UIResource
Enclosing class:
MetalBorders
public static class MetalBorders.ToggleButtonBorder
extends MetalBorders.ButtonBorder

Since:
1.3

Field Summary
Fields inherited from class javax.swing.plaf.metal.MetalBorders.ButtonBorder
borderInsets
Constructor Summary
MetalBorders.ToggleButtonBorder()
Method Summary
 void paintBorder(Component c, Graphics g, int x, int y, int w, int h)
This default implementation does no painting.
Methods inherited from class javax.swing.plaf.metal.MetalBorders.ButtonBorder
getBorderInsets, getBorderInsets
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalBorders.ToggleButtonBorder

public MetalBorders.ToggleButtonBorder()
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int w,
                        int h)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class MetalBorders.ButtonBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
w - the width of the painted border
h - the height of the painted border
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalBorders.ToolBarBorder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalBorders.ToolBarBorder

java.lang.Object
    extended by  javax.swing.border.AbstractBorder
        extended by  javax.swing.plaf.metal.MetalBorders.ToolBarBorder
All Implemented Interfaces:
Serializable, Border, UIResource, SwingConstants
Enclosing class:
MetalBorders
public static class MetalBorders.ToolBarBorder
extends AbstractBorder
implements UIResource, SwingConstants

Field Summary
protected  javax.swing.plaf.metal.MetalBumps bumps
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
MetalBorders.ToolBarBorder()
Method Summary
Insets | getBorderInsets(Component c) This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.
Insets | getBorderInsets(Component c, Insets newInsets) Reinitializes the insets parameter with this Border's current Insets.
void | paintBorder(Component c, Graphics g, int x, int y, int w, int h) This default implementation does no painting.
Methods inherited from class javax.swing.border.AbstractBorder
getBaseline, getBaselineResizeBehavior, getInteriorRectangle, getInteriorRectangle, isBorderOpaque
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

bumps

protected javax.swing.plaf.metal.MetalBumps bumps
Constructor Detail

MetalBorders.ToolBarBorder

public MetalBorders.ToolBarBorder()
Method Detail

paintBorder

public void paintBorder(Component c,
                        Graphics g,
                        int x,
                        int y,
                        int w,
                        int h)
Description copied from class: AbstractBorder
This default implementation does no painting.

Specified by:
paintBorder in interface Border
Overrides:
paintBorder in class AbstractBorder
Parameters:
c - the component for which this border is being painted
g - the paint graphics
x - the x position of the painted border
y - the y position of the painted border
w - the width of the painted border
h - the height of the painted border

getBorderInsets

public Insets getBorderInsets(Component c)
Description copied from class: AbstractBorder
This default implementation returns a new Insets instance where the top, left, bottom, and right fields are set to 0.

Specified by:
getBorderInsets in interface Border
Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
Returns:
the new Insets object initialized to 0

getBorderInsets

public Insets getBorderInsets(Component c,
                              Insets newInsets)
Description copied from class: AbstractBorder
Reinitializes the insets parameter with this Border's current Insets.

Overrides:
getBorderInsets in class AbstractBorder
Parameters:
c - the component for which this border insets value applies
newInsets - the object to be reinitialized
Returns:
the insets object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalButtonUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalButtonUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ButtonUI
            extended by  javax.swing.plaf.basic.BasicButtonUI
                extended by  javax.swing.plaf.metal.MetalButtonUI

public class MetalButtonUI
extends BasicButtonUI

MetalButtonUI implementation

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected Color | disabledTextColor
protected Color | focusColor
protected Color | selectColor
Fields inherited from class javax.swing.plaf.basic.BasicButtonUI
defaultTextIconGap, defaultTextShiftOffset
Constructor Summary
MetalButtonUI()
Method Summary
protected BasicButtonListener | createButtonListener(AbstractButton b)
static ComponentUI | createUI(JComponent c)
protected Color | getDisabledTextColor()
protected Color | getFocusColor()
protected Color | getSelectColor()
void | installDefaults(AbstractButton b)
protected void | paintButtonPressed(Graphics g, AbstractButton b)
protected void | paintFocus(Graphics g, AbstractButton b, Rectangle viewRect, Rectangle textRect, Rectangle iconRect)
protected void | paintText(Graphics g, JComponent c, Rectangle textRect, String text) As of Java 2 platform v 1.4 this method should not be used or overriden.
void | uninstallDefaults(AbstractButton b)
void | update(Graphics g, JComponent c) If necessary paints the background of the component, then invokes paint.
Methods inherited from class javax.swing.plaf.basic.BasicButtonUI
clearTextShiftOffset, getBaseline, getBaselineResizeBehavior, getDefaultTextIconGap, getMaximumSize, getMinimumSize, getPreferredSize, getPropertyPrefix, getTextShiftOffset, installKeyboardActions, installListeners, installUI, paint, paintIcon, paintText, setTextShiftOffset, uninstallKeyboardActions, uninstallListeners, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

focusColor

protected Color focusColor

selectColor

protected Color selectColor

disabledTextColor

protected Color disabledTextColor
Constructor Detail

MetalButtonUI

public MetalButtonUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installDefaults

public void installDefaults(AbstractButton b)
Overrides:
installDefaults in class BasicButtonUI

uninstallDefaults

public void uninstallDefaults(AbstractButton b)
Overrides:
uninstallDefaults in class BasicButtonUI

createButtonListener

protected BasicButtonListener createButtonListener(AbstractButton b)
Overrides:
createButtonListener in class BasicButtonUI

getSelectColor

protected Color getSelectColor()

getDisabledTextColor

protected Color getDisabledTextColor()

getFocusColor

protected Color getFocusColor()

update

public void update(Graphics g,
                   JComponent c)
If necessary paints the background of the component, then invokes paint.

Overrides:
update in class ComponentUI
Parameters:
g - Graphics to paint to
c - JComponent painting on
Throws:
NullPointerException - if g or c is null
Since:
1.5
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent), ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent)

paintButtonPressed

protected void paintButtonPressed(Graphics g,
                                  AbstractButton b)
Overrides:
paintButtonPressed in class BasicButtonUI

paintFocus

protected void paintFocus(Graphics g,
                          AbstractButton b,
                          Rectangle viewRect,
                          Rectangle textRect,
                          Rectangle iconRect)
Overrides:
paintFocus in class BasicButtonUI

paintText

protected void paintText(Graphics g,
                         JComponent c,
                         Rectangle textRect,
                         String text)
Description copied from class: BasicButtonUI
As of Java 2 platform v 1.4 this method should not be used or overriden. Use the paintText method which takes the AbstractButton argument.

Overrides:
paintText in class BasicButtonUI
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalCheckBoxIcon

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalCheckBoxIcon

java.lang.Object
    extended by  javax.swing.plaf.metal.MetalCheckBoxIcon
All Implemented Interfaces:
Serializable, Icon, UIResource
public class MetalCheckBoxIcon
extends Object
implements Icon, UIResource, Serializable

CheckboxIcon implementation for OrganicCheckBoxUI

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
MetalCheckBoxIcon()
Method Summary
protected void | drawCheck(Component c, Graphics g, int x, int y)
protected int | getControlSize()
int | getIconHeight() Returns the icon's height.
int | getIconWidth() Returns the icon's width.
void | paintIcon(Component c, Graphics g, int x, int y) Draw the icon at the specified location.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalCheckBoxIcon

public MetalCheckBoxIcon()
Method Detail

getControlSize

protected int getControlSize()

paintIcon

public void paintIcon(Component c,
                      Graphics g,
                      int x,
                      int y)
Description copied from interface: Icon
Draw the icon at the specified location. Icon implementations may use the Component argument to get properties useful for painting, e.g. the foreground or background color.

Specified by:
paintIcon in interface Icon

drawCheck

protected void drawCheck(Component c,
                         Graphics g,
                         int x,
                         int y)

getIconWidth

public int getIconWidth()
Description copied from interface: Icon
Returns the icon's width.

Specified by:
getIconWidth in interface Icon
Returns:
an int specifying the fixed width of the icon.

getIconHeight

public int getIconHeight()
Description copied from interface: Icon
Returns the icon's height.

Specified by:
getIconHeight in interface Icon
Returns:
an int specifying the fixed height of the icon.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalCheckBoxUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalCheckBoxUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ButtonUI
            extended by  javax.swing.plaf.basic.BasicButtonUI
                extended by  javax.swing.plaf.basic.BasicToggleButtonUI
                    extended by  javax.swing.plaf.basic.BasicRadioButtonUI
                        extended by  javax.swing.plaf.metal.MetalRadioButtonUI
                            extended by  javax.swing.plaf.metal.MetalCheckBoxUI

public class MetalCheckBoxUI
extends MetalRadioButtonUI

CheckboxUI implementation for MetalCheckboxUI

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class javax.swing.plaf.metal.MetalRadioButtonUI
disabledTextColor, focusColor, selectColor
Fields inherited from class javax.swing.plaf.basic.BasicRadioButtonUI
icon
Fields inherited from class javax.swing.plaf.basic.BasicButtonUI
defaultTextIconGap, defaultTextShiftOffset
Constructor Summary
MetalCheckBoxUI()
Method Summary
static ComponentUI | createUI(JComponent b)
String | getPropertyPrefix()
void | installDefaults(AbstractButton b)
protected void | uninstallDefaults(AbstractButton b)
Methods inherited from class javax.swing.plaf.metal.MetalRadioButtonUI
getDisabledTextColor, getFocusColor, getSelectColor, paint, paintFocus
Methods inherited from class javax.swing.plaf.basic.BasicRadioButtonUI
getDefaultIcon, getPreferredSize
Methods inherited from class javax.swing.plaf.basic.BasicToggleButtonUI
getTextShiftOffset, paintIcon
Methods inherited from class javax.swing.plaf.basic.BasicButtonUI
clearTextShiftOffset, createButtonListener, getBaseline, getBaselineResizeBehavior, getDefaultTextIconGap, getMaximumSize, getMinimumSize, installKeyboardActions, installListeners, installUI, paintButtonPressed, paintFocus, paintIcon, paintText, paintText, setTextShiftOffset, uninstallKeyboardActions, uninstallListeners, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalCheckBoxUI

public MetalCheckBoxUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent b)

getPropertyPrefix

public String getPropertyPrefix()
Overrides:
getPropertyPrefix in class BasicRadioButtonUI

installDefaults

public void installDefaults(AbstractButton b)
Overrides:
installDefaults in class MetalRadioButtonUI

uninstallDefaults

protected void uninstallDefaults(AbstractButton b)
Overrides:
uninstallDefaults in class MetalRadioButtonUI
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalComboBoxButton

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalComboBoxButton

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.AbstractButton
                    extended by  javax.swing.JButton
                        extended by  javax.swing.plaf.metal.MetalComboBoxButton
All Implemented Interfaces:
ImageObserver, ItemSelectable, MenuContainer, Serializable, Accessible, SwingConstants
public class MetalComboBoxButton
extends JButton

JButton subclass to help out MetalComboBoxUI

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
MetalComboBoxButton

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JButton
JButton.AccessibleJButton
Nested classes/interfaces inherited from class javax.swing.AbstractButton
AbstractButton.AccessibleAbstractButton, AbstractButton.ButtonChangeListener
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected JComboBox | comboBox
protected Icon | comboIcon
protected boolean | iconOnly
protected JList | listBox
protected CellRendererPane | rendererPane
Fields inherited from class javax.swing.AbstractButton
actionListener, BORDER_PAINTED_CHANGED_PROPERTY, changeEvent, changeListener, CONTENT_AREA_FILLED_CHANGED_PROPERTY, DISABLED_ICON_CHANGED_PROPERTY, DISABLED_SELECTED_ICON_CHANGED_PROPERTY, FOCUS_PAINTED_CHANGED_PROPERTY, HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY, HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY, ICON_CHANGED_PROPERTY, itemListener, MARGIN_CHANGED_PROPERTY, MNEMONIC_CHANGED_PROPERTY, model, MODEL_CHANGED_PROPERTY, PRESSED_ICON_CHANGED_PROPERTY, ROLLOVER_ENABLED_CHANGED_PROPERTY, ROLLOVER_ICON_CHANGED_PROPERTY, ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY, SELECTED_ICON_CHANGED_PROPERTY, TEXT_CHANGED_PROPERTY, VERTICAL_ALIGNMENT_CHANGED_PROPERTY, VERTICAL_TEXT_POSITION_CHANGED_PROPERTY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
MetalComboBoxButton(JComboBox cb, Icon i, boolean onlyIcon, CellRendererPane pane, JList list)
MetalComboBoxButton(JComboBox cb, Icon i, CellRendererPane pane, JList list)
Method Summary
JComboBox | getComboBox()
Icon | getComboIcon()
Dimension | getMinimumSize() If the minimum size has been set to a non-null value just returns it.
boolean | isFocusTraversable() Returns whether this Component can become the focus owner.
boolean | isIconOnly()
void | paintComponent(Graphics g) Calls the UI delegate's paint method, if the UI delegate is non-null.
void | setComboBox(JComboBox cb)
void | setComboIcon(Icon i)
void | setEnabled(boolean enabled) Enables (or disables) the button.
void | setIconOnly(boolean isIconOnly)
Methods inherited from class javax.swing.JButton
getAccessibleContext, getUIClassID, isDefaultButton, isDefaultCapable, paramString, removeNotify, setDefaultCapable, updateUI
Methods inherited from class javax.swing.AbstractButton
actionPropertyChanged, addActionListener, addChangeListener, addImpl, addItemListener, checkHorizontalKey, checkVerticalKey, configurePropertiesFromAction, createActionListener, createActionPropertyChangeListener, createChangeListener, createItemListener, doClick, doClick, fireActionPerformed, fireItemStateChanged, fireStateChanged, getAction, getActionCommand, getActionListeners, getChangeListeners, getDisabledIcon, getDisabledSelectedIcon, getDisplayedMnemonicIndex, getHideActionText, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getItemListeners, getLabel, getMargin, getMnemonic, getModel, getMultiClickThreshhold, getPressedIcon, getRolloverIcon, getRolloverSelectedIcon, getSelectedIcon, getSelectedObjects, getText, getUI, getVerticalAlignment, getVerticalTextPosition, imageUpdate, init, isBorderPainted, isContentAreaFilled, isFocusPainted, isRolloverEnabled, isSelected, paintBorder, removeActionListener, removeChangeListener, removeItemListener, setAction, setActionCommand, setBorderPainted, setContentAreaFilled, setDisabledIcon, setDisabledSelectedIcon, setDisplayedMnemonicIndex, setFocusPainted, setHideActionText, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabel, setLayout, setMargin, setMnemonic, setMnemonic, setModel, setMultiClickThreshhold, setPressedIcon, setRolloverEnabled, setRolloverIcon, setRolloverSelectedIcon, setSelected, setSelectedIcon, setText, setUI, setVerticalAlignment, setVerticalTextPosition
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

comboBox

protected JComboBox comboBox

listBox

protected JList listBox

rendererPane

protected CellRendererPane rendererPane

comboIcon

protected Icon comboIcon

iconOnly

protected boolean iconOnly
Constructor Detail

MetalComboBoxButton

public MetalComboBoxButton(JComboBox cb,
                           Icon i,
                           CellRendererPane pane,
                           JList list)

MetalComboBoxButton

public MetalComboBoxButton(JComboBox cb,
                           Icon i,
                           boolean onlyIcon,
                           CellRendererPane pane,
                           JList list)
Method Detail

getComboBox

public final JComboBox getComboBox()

setComboBox

public final void setComboBox(JComboBox cb)

getComboIcon

public final Icon getComboIcon()

setComboIcon

public final void setComboIcon(Icon i)

isIconOnly

public final boolean isIconOnly()

setIconOnly

public final void setIconOnly(boolean isIconOnly)

isFocusTraversable

public boolean isFocusTraversable()
Description copied from class: Component
Returns whether this Component can become the focus owner.

Overrides:
isFocusTraversable in class Component
Returns:
true if this Component is focusable; false otherwise
See Also:
Component.setFocusable(boolean)

setEnabled

public void setEnabled(boolean enabled)
Description copied from class: AbstractButton
Enables (or disables) the button.

Overrides:
setEnabled in class AbstractButton
Parameters:
enabled - true to enable the button, otherwise false
See Also:
Component.isEnabled(), Component.isLightweight()

paintComponent

public void paintComponent(Graphics g)
Description copied from class: JComponent
Calls the UI delegate's paint method, if the UI delegate is non-null. We pass the delegate a copy of the Graphics object to protect the rest of the paint code from irrevocable changes (for example, Graphics.translate).

If you override this in a subclass you should not make permanent changes to the passed in Graphics. For example, you should not alter the clip Rectangle or modify the transform. If you need to do these operations you may find it easier to create a new Graphics from the passed in Graphics and manipulate it. Further, if you do not invoker super's implementation you must honor the opaque property, that is if this component is opaque, you must completely fill in the background in a non-opaque color. If you do not honor the opaque property you will likely see visual artifacts.

The passed in Graphics object might have a transform other than the identify transform installed on it. In this case, you might get unexpected results if you cumulatively apply another transform.

Overrides:
paintComponent in class JComponent
Parameters:
g - the Graphics object to protect
See Also:
JComponent.paint(java.awt.Graphics), ComponentUI

getMinimumSize

public Dimension getMinimumSize()
Description copied from class: JComponent
If the minimum size has been set to a non-null value just returns it. If the UI delegate's getMinimumSize method returns a non-null value then return that; otherwise defer to the component's layout manager.

Overrides:
getMinimumSize in class JComponent
Returns:
the value of the minimumSize property
See Also:
JComponent.setMinimumSize(java.awt.Dimension), ComponentUI
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalComboBoxEditor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalComboBoxEditor

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicComboBoxEditor
        extended by  javax.swing.plaf.metal.MetalComboBoxEditor
All Implemented Interfaces:
FocusListener, EventListener, ComboBoxEditor
Direct Known Subclasses:
MetalComboBoxEditor.UIResource
public class MetalComboBoxEditor
extends BasicComboBoxEditor

The default editor for Metal editable combo boxes

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
static class MetalComboBoxEditor.UIResource
A subclass of BasicComboBoxEditor that implements UIResource.
Field Summary
protected static Insets editorBorderInsets
The default editor border Insets.
Fields inherited from class javax.swing.plaf.basic.BasicComboBoxEditor
editor
Constructor Summary
MetalComboBoxEditor()
Method Summary
Methods inherited from class javax.swing.plaf.basic.BasicComboBoxEditor
addActionListener, createEditorComponent, focusGained, focusLost, getEditorComponent, getItem, removeActionListener, selectAll, setItem
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

editorBorderInsets

protected static Insets editorBorderInsets
The default editor border Insets. This field might not be used.

Constructor Detail

MetalComboBoxEditor

public MetalComboBoxEditor()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalComboBoxEditor.UIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalComboBoxEditor.UIResource

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicComboBoxEditor
        extended by  javax.swing.plaf.metal.MetalComboBoxEditor
            extended by  javax.swing.plaf.metal.MetalComboBoxEditor.UIResource
All Implemented Interfaces:
FocusListener, EventListener, ComboBoxEditor, UIResource
Enclosing class:
MetalComboBoxEditor
public static class MetalComboBoxEditor.UIResource
extends MetalComboBoxEditor
implements UIResource

A subclass of BasicComboBoxEditor that implements UIResource. BasicComboBoxEditor doesn't implement UIResource directly so that applications can safely override the cellRenderer property with BasicListCellRenderer subclasses.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.metal.MetalComboBoxEditor
MetalComboBoxEditor.UIResource
Field Summary
Fields inherited from class javax.swing.plaf.metal.MetalComboBoxEditor
editorBorderInsets
Fields inherited from class javax.swing.plaf.basic.BasicComboBoxEditor
editor
Constructor Summary
MetalComboBoxEditor.UIResource()
Method Summary
Methods inherited from class javax.swing.plaf.basic.BasicComboBoxEditor
addActionListener, createEditorComponent, focusGained, focusLost, getEditorComponent, getItem, removeActionListener, selectAll, setItem
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalComboBoxEditor.UIResource

public MetalComboBoxEditor.UIResource()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalComboBoxIcon

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalComboBoxIcon

java.lang.Object
    extended by  javax.swing.plaf.metal.MetalComboBoxIcon
All Implemented Interfaces:
Serializable, Icon
public class MetalComboBoxIcon
extends Object
implements Icon, Serializable

This utility class draws the horizontal bars which indicate a MetalComboBox

See Also:
MetalComboBoxUI

Constructor Summary
MetalComboBoxIcon()
Method Summary
int | getIconHeight() Created a stub to satisfy the interface.
int | getIconWidth() Created a stub to satisfy the interface.
void | paintIcon(Component c, Graphics g, int x, int y) Paints the horizontal bars for the
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalComboBoxIcon

public MetalComboBoxIcon()
Method Detail

paintIcon

public void paintIcon(Component c,
                      Graphics g,
                      int x,
                      int y)
Paints the horizontal bars for the

Specified by:
paintIcon in interface Icon

getIconWidth

public int getIconWidth()
Created a stub to satisfy the interface.

Specified by:
getIconWidth in interface Icon
Returns:
an int specifying the fixed width of the icon.

getIconHeight

public int getIconHeight()
Created a stub to satisfy the interface.

Specified by:
getIconHeight in interface Icon
Returns:
an int specifying the fixed height of the icon.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalComboBoxUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalComboBoxUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ComboBoxUI
            extended by  javax.swing.plaf.basic.BasicComboBoxUI
                extended by  javax.swing.plaf.metal.MetalComboBoxUI

public class MetalComboBoxUI
extends BasicComboBoxUI

Metal UI for JComboBox

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
MetalComboBoxEditor, MetalComboBoxButton

Nested Class Summary
class | MetalComboBoxUI.MetalComboBoxLayoutManager This inner class is marked "public" due to a compiler bug.
class | MetalComboBoxUI.MetalComboPopup Deprecated. As of Java 2 platform v1.4.
class | MetalComboBoxUI.MetalPropertyChangeListener This inner class is marked "public" due to a compiler bug.
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicComboBoxUI
BasicComboBoxUI.ComboBoxLayoutManager, BasicComboBoxUI.FocusHandler, BasicComboBoxUI.ItemHandler, BasicComboBoxUI.KeyHandler, BasicComboBoxUI.ListDataHandler, BasicComboBoxUI.PropertyChangeHandler
Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicComboBoxUI
arrowButton, cachedMinimumSize, comboBox, currentValuePane, editor, focusListener, hasFocus, isMinimumSizeDirty, itemListener, keyListener, listBox, listDataListener, popup, popupKeyListener, popupMouseListener, popupMouseMotionListener, propertyChangeListener
Constructor Summary
MetalComboBoxUI()
Method Summary
void | configureEditor() This protected method is implementation specific and should be private.
protected JButton | createArrowButton() Creates an button which will be used as the control to show or hide the popup portion of the combo box.
protected ComboBoxEditor | createEditor() Creates the default editor that will be used in editable combo boxes.
protected LayoutManager | createLayoutManager() Creates a layout manager for managing the components which make up the combo box.
protected ComboPopup | createPopup() Creates the popup portion of the combo box.
PropertyChangeListener | createPropertyChangeListener() Creates a PropertyChangeListener which will be added to the combo box.
static ComponentUI | createUI(JComponent c)
protected void | editablePropertyChanged(PropertyChangeEvent e) Deprecated. As of Java 2 platform v1.4.
int | getBaseline(JComponent c, int width, int height) Returns the baseline.
Dimension | getMinimumSize(JComponent c) The minumum size is the size of the display area plus insets plus the button.
void | layoutComboBox(Container parent, MetalComboBoxUI.MetalComboBoxLayoutManager manager)
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
void | paintCurrentValue(Graphics g, Rectangle bounds, boolean hasFocus) If necessary paints the currently selected item.
void | paintCurrentValueBackground(Graphics g, Rectangle bounds, boolean hasFocus) If necessary paints the background of the currently selected item.
protected void | removeListeners() Deprecated. As of Java 2 platform v1.4.
void | unconfigureEditor() This protected method is implementation specific and should be private.
Methods inherited from class javax.swing.plaf.basic.BasicComboBoxUI
addEditor, configureArrowButton, createFocusListener, createItemListener, createKeyListener, createListDataListener, createRenderer, getAccessibleChild, getAccessibleChildrenCount, getBaselineResizeBehavior, getDefaultSize, getDisplaySize, getInsets, getMaximumSize, getPreferredSize, installComponents, installDefaults, installKeyboardActions, installListeners, installUI, isFocusTraversable, isNavigationKey, isPopupVisible, rectangleForCurrentValue, removeEditor, selectNextPossibleValue, selectPreviousPossibleValue, setPopupVisible, toggleOpenClose, unconfigureArrowButton, uninstallComponents, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalComboBoxUI

public MetalComboBoxUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class BasicComboBoxUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

paintCurrentValue

public void paintCurrentValue(Graphics g,
                              Rectangle bounds,
                              boolean hasFocus)
If necessary paints the currently selected item.

Overrides:
paintCurrentValue in class BasicComboBoxUI
Parameters:
g - Graphics to paint to
bounds - Region to paint current value to
hasFocus - whether or not the JComboBox has focus
Throws:
NullPointerException - if any of the arguments are null.
Since:
1.5

paintCurrentValueBackground

public void paintCurrentValueBackground(Graphics g,
                                        Rectangle bounds,
                                        boolean hasFocus)
If necessary paints the background of the currently selected item.

Overrides:
paintCurrentValueBackground in class BasicComboBoxUI
Parameters:
g - Graphics to paint to
bounds - Region to paint background to
hasFocus - whether or not the JComboBox has focus
Throws:
NullPointerException - if any of the arguments are null.
Since:
1.5

getBaseline

public int getBaseline(JComponent c,
                       int width,
                       int height)
Returns the baseline.

Overrides:
getBaseline in class BasicComboBoxUI
Parameters:
c - JComponent baseline is being requested for
width - the width to get the baseline for
height - the height to get the baseline for
Returns:
baseline or a value < 0 indicating there is no reasonable baseline
Throws:
NullPointerException - if c is null
IllegalArgumentException - if width or height is < 0
Since:
1.6
See Also:
JComponent.getBaseline(int, int)

createEditor

protected ComboBoxEditor createEditor()
Description copied from class: BasicComboBoxUI
Creates the default editor that will be used in editable combo boxes. A default editor will be used only if an editor has not been explicitly set with setEditor.

Overrides:
createEditor in class BasicComboBoxUI
Returns:
a ComboBoxEditor used for the combo box
See Also:
JComboBox.setEditor(javax.swing.ComboBoxEditor)

createPopup

protected ComboPopup createPopup()
Description copied from class: BasicComboBoxUI
Creates the popup portion of the combo box.

Overrides:
createPopup in class BasicComboBoxUI
Returns:
an instance of ComboPopup
See Also:
ComboPopup

createArrowButton

protected JButton createArrowButton()
Description copied from class: BasicComboBoxUI
Creates an button which will be used as the control to show or hide the popup portion of the combo box.

Overrides:
createArrowButton in class BasicComboBoxUI
Returns:
a button which represents the popup control

createPropertyChangeListener

public PropertyChangeListener createPropertyChangeListener()
Description copied from class: BasicComboBoxUI
Creates a PropertyChangeListener which will be added to the combo box. If this method returns null then it will not be added to the combo box.

Overrides:
createPropertyChangeListener in class BasicComboBoxUI
Returns:
an instance of a PropertyChangeListener or null

editablePropertyChanged

@Deprecated
protected void editablePropertyChanged(PropertyChangeEvent e)
Deprecated. As of Java 2 platform v1.4.

As of Java 2 platform v1.4 this method is no longer used. Do not call or override. All the functionality of this method is in the MetalPropertyChangeListener.

createLayoutManager

protected LayoutManager createLayoutManager()
Description copied from class: BasicComboBoxUI
Creates a layout manager for managing the components which make up the combo box.

Overrides:
createLayoutManager in class BasicComboBoxUI
Returns:
an instance of a layout manager

layoutComboBox

public void layoutComboBox(Container parent,
                           MetalComboBoxUI.MetalComboBoxLayoutManager manager)

removeListeners

@Deprecated
protected void removeListeners()
Deprecated. As of Java 2 platform v1.4.

As of Java 2 platform v1.4 this method is no longer used.

configureEditor

public void configureEditor()
Description copied from class: BasicComboBoxUI
This protected method is implementation specific and should be private. do not call or override.

Overrides:
configureEditor in class BasicComboBoxUI
See Also:
BasicComboBoxUI.addEditor()

unconfigureEditor

public void unconfigureEditor()
Description copied from class: BasicComboBoxUI
This protected method is implementation specific and should be private. Do not call or override.

Overrides:
unconfigureEditor in class BasicComboBoxUI
See Also:
BasicComboBoxUI.addEditor()

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Description copied from class: BasicComboBoxUI
The minumum size is the size of the display area plus insets plus the button.

Overrides:
getMinimumSize in class BasicComboBoxUI
Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalComboBoxUI.MetalComboBoxLayoutManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalComboBoxUI.MetalComboBoxLayoutManager

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicComboBoxUI.ComboBoxLayoutManager
        extended by  javax.swing.plaf.metal.MetalComboBoxUI.MetalComboBoxLayoutManager
All Implemented Interfaces:
LayoutManager
Enclosing class:
MetalComboBoxUI
public class MetalComboBoxUI.MetalComboBoxLayoutManager
extends BasicComboBoxUI.ComboBoxLayoutManager

This inner class is marked "public" due to a compiler bug. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Constructor Summary
MetalComboBoxUI.MetalComboBoxLayoutManager()
Method Summary
void | layoutContainer(Container parent) Lays out the specified container.
void | superLayout(Container parent)
Methods inherited from class javax.swing.plaf.basic.BasicComboBoxUI.ComboBoxLayoutManager
addLayoutComponent, minimumLayoutSize, preferredLayoutSize, removeLayoutComponent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalComboBoxUI.MetalComboBoxLayoutManager

public MetalComboBoxUI.MetalComboBoxLayoutManager()
Method Detail

layoutContainer

public void layoutContainer(Container parent)
Description copied from interface: LayoutManager
Lays out the specified container.

Specified by:
layoutContainer in interface LayoutManager
Overrides:
layoutContainer in class BasicComboBoxUI.ComboBoxLayoutManager
Parameters:
parent - the container to be laid out

superLayout

public void superLayout(Container parent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalComboBoxUI.MetalComboPopup

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalComboBoxUI.MetalComboPopup

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JPopupMenu
                    extended by  javax.swing.plaf.basic.BasicComboPopup
                        extended by  javax.swing.plaf.metal.MetalComboBoxUI.MetalComboPopup
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, MenuElement, ComboPopup
Enclosing class:
MetalComboBoxUI
Deprecated. As of Java 2 platform v1.4.

@Deprecated
public class MetalComboBoxUI.MetalComboPopup
extends BasicComboPopup

This inner class is marked "public" due to a compiler bug. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of . This class is now obsolete and doesn't do anything and is only included for backwards API compatibility. Do not call or override.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicComboPopup
BasicComboPopup.InvocationKeyHandler, BasicComboPopup.InvocationMouseHandler, BasicComboPopup.InvocationMouseMotionHandler, BasicComboPopup.ItemHandler, BasicComboPopup.ListDataHandler, BasicComboPopup.ListMouseHandler, BasicComboPopup.ListMouseMotionHandler, BasicComboPopup.ListSelectionHandler, BasicComboPopup.PropertyChangeHandler
Nested classes/interfaces inherited from class javax.swing.JPopupMenu
JPopupMenu.AccessibleJPopupMenu, JPopupMenu.Separator
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicComboPopup
autoscrollTimer, comboBox, hasEntered, isAutoScrolling, itemListener, keyListener, list, listDataListener, listMouseListener, listMouseMotionListener, listSelectionListener, mouseListener, mouseMotionListener, propertyChangeListener, SCROLL_DOWN, SCROLL_UP, scrollDirection, scroller, valueIsAdjusting
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
MetalComboBoxUI.MetalComboPopup(JComboBox cBox)
Deprecated.
Method Summary
 void delegateFocus(MouseEvent e)
Deprecated. This is is a utility method that helps event handlers figure out where to send the focus when the popup is brought up.
Methods inherited from class javax.swing.plaf.basic.BasicComboPopup
autoScrollDown, autoScrollUp, computePopupBounds, configureList, configurePopup, configureScroller, convertMouseEvent, createItemListener, createKeyListener, createList, createListDataListener, createListMouseListener, createListMouseMotionListener, createListSelectionListener, createMouseListener, createMouseMotionListener, createPropertyChangeListener, createScroller, firePopupMenuCanceled, firePopupMenuWillBecomeInvisible, firePopupMenuWillBecomeVisible, getAccessibleContext, getKeyListener, getList, getMouseListener, getMouseMotionListener, getPopupHeightForRowCount, hide, installComboBoxListeners, installComboBoxModelListeners, installKeyboardActions, installListListeners, isFocusTraversable, show, startAutoScrolling, stopAutoScrolling, togglePopup, uninstallComboBoxModelListeners, uninstallingUI, uninstallKeyboardActions, updateListBoxSelectionForEvent
Methods inherited from class javax.swing.JPopupMenu
add, add, add, addMenuKeyListener, addPopupMenuListener, addSeparator, createActionChangeListener, createActionComponent, getComponent, getComponentAtIndex, getComponentIndex, getDefaultLightWeightPopupEnabled, getInvoker, getLabel, getMargin, getMenuKeyListeners, getPopupMenuListeners, getSelectionModel, getSubElements, getUI, getUIClassID, insert, insert, isBorderPainted, isLightWeightPopupEnabled, isPopupTrigger, isVisible, menuSelectionChanged, pack, paintBorder, paramString, processFocusEvent, processKeyEvent, processKeyEvent, processMouseEvent, remove, removeMenuKeyListener, removePopupMenuListener, setBorderPainted, setDefaultLightWeightPopupEnabled, setInvoker, setLabel, setLightWeightPopupEnabled, setLocation, setPopupSize, setPopupSize, setSelected, setSelectionModel, setUI, setVisible, show, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setName, setSize, setSize, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface javax.swing.plaf.basic.ComboPopup
isVisible

Constructor Detail

MetalComboBoxUI.MetalComboPopup

public MetalComboBoxUI.MetalComboPopup(JComboBox cBox)
Deprecated.
Method Detail

delegateFocus

public void delegateFocus(MouseEvent e)
Deprecated.
Description copied from class: BasicComboPopup
This is is a utility method that helps event handlers figure out where to send the focus when the popup is brought up. The standard implementation delegates the focus to the editor (if the combo box is editable) or to the JComboBox if it is not editable.

Overrides:
delegateFocus in class BasicComboPopup
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalComboBoxUI.MetalPropertyChangeListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalComboBoxUI.MetalPropertyChangeListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicComboBoxUI.PropertyChangeHandler
        extended by  javax.swing.plaf.metal.MetalComboBoxUI.MetalPropertyChangeListener
All Implemented Interfaces:
PropertyChangeListener, EventListener
Enclosing class:
MetalComboBoxUI
public class MetalComboBoxUI.MetalPropertyChangeListener
extends BasicComboBoxUI.PropertyChangeHandler

This inner class is marked "public" due to a compiler bug. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of .

Constructor Summary
MetalComboBoxUI.MetalPropertyChangeListener()
Method Summary
 void propertyChange(PropertyChangeEvent e)
This method gets called when a bound property is changed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalComboBoxUI.MetalPropertyChangeListener

public MetalComboBoxUI.MetalPropertyChangeListener()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Overrides:
propertyChange in class BasicComboBoxUI.PropertyChangeHandler
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalDesktopIconUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalDesktopIconUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.DesktopIconUI
            extended by  javax.swing.plaf.basic.BasicDesktopIconUI
                extended by  javax.swing.plaf.metal.MetalDesktopIconUI

public class MetalDesktopIconUI
extends BasicDesktopIconUI

Metal desktop icon.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicDesktopIconUI
BasicDesktopIconUI.MouseInputHandler
Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicDesktopIconUI
desktopIcon, frame, iconPane
Constructor Summary
MetalDesktopIconUI()
Method Summary
static ComponentUI | createUI(JComponent c)
Dimension | getMaximumSize(JComponent c) Desktop icons can not be resized.
Dimension | getMinimumSize(JComponent c) Returns the specified component's minimum size appropriate for the look and feel.
Dimension | getPreferredSize(JComponent c) Returns the specified component's preferred size appropriate for the look and feel.
protected void | installComponents()
protected void | installDefaults()
protected void | installListeners()
protected void | uninstallComponents()
protected void | uninstallListeners()
Methods inherited from class javax.swing.plaf.basic.BasicDesktopIconUI
createMouseInputListener, deiconize, getInsets, installUI, uninstallDefaults, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, paint, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalDesktopIconUI

public MetalDesktopIconUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installDefaults

protected void installDefaults()
Overrides:
installDefaults in class BasicDesktopIconUI

installComponents

protected void installComponents()
Overrides:
installComponents in class BasicDesktopIconUI

uninstallComponents

protected void uninstallComponents()
Overrides:
uninstallComponents in class BasicDesktopIconUI

installListeners

protected void installListeners()
Overrides:
installListeners in class BasicDesktopIconUI

uninstallListeners

protected void uninstallListeners()
Overrides:
uninstallListeners in class BasicDesktopIconUI

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Overrides:
getPreferredSize in class BasicDesktopIconUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's minimum size appropriate for the look and feel. If null is returned, the minimum size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method invokes getPreferredSize and returns that value.

Overrides:
getMinimumSize in class BasicDesktopIconUI
Parameters:
c - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Description copied from class: BasicDesktopIconUI
Desktop icons can not be resized. Therefore, we should always return the minimum size of the desktop icon.

Overrides:
getMaximumSize in class BasicDesktopIconUI
Parameters:
c - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
a Dimension object or null
See Also:
BasicDesktopIconUI.getMinimumSize(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalFileChooserUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalFileChooserUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.FileChooserUI
            extended by  javax.swing.plaf.basic.BasicFileChooserUI
                extended by  javax.swing.plaf.metal.MetalFileChooserUI

public class MetalFileChooserUI
extends BasicFileChooserUI

Metal L&F implementation of a FileChooser.

Nested Class Summary
protected class | MetalFileChooserUI.DirectoryComboBoxAction Acts when DirectoryComboBox has changed the selected item.
protected class | MetalFileChooserUI.DirectoryComboBoxModel Data model for a type-face selection combo-box.
protected class | MetalFileChooserUI.FileRenderer
protected class | MetalFileChooserUI.FilterComboBoxModel Data model for a type-face selection combo-box.
class | MetalFileChooserUI.FilterComboBoxRenderer Render different type sizes and styles.
protected class | MetalFileChooserUI.SingleClickListener
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicFileChooserUI
BasicFileChooserUI.AcceptAllFileFilter, BasicFileChooserUI.ApproveSelectionAction, BasicFileChooserUI.BasicFileView, BasicFileChooserUI.CancelSelectionAction, BasicFileChooserUI.ChangeToParentDirectoryAction, BasicFileChooserUI.DoubleClickListener, BasicFileChooserUI.GoHomeAction, BasicFileChooserUI.NewFolderAction, BasicFileChooserUI.SelectionListener, BasicFileChooserUI.UpdateAction
Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicFileChooserUI
cancelButtonMnemonic, cancelButtonText, cancelButtonToolTipText, computerIcon, detailsViewIcon, directoryIcon, directoryOpenButtonMnemonic, directoryOpenButtonText, directoryOpenButtonToolTipText, fileIcon, floppyDriveIcon, hardDriveIcon, helpButtonMnemonic, helpButtonText, helpButtonToolTipText, homeFolderIcon, listViewIcon, newFolderIcon, openButtonMnemonic, openButtonText, openButtonToolTipText, saveButtonMnemonic, saveButtonText, saveButtonToolTipText, updateButtonMnemonic, updateButtonText, updateButtonToolTipText, upFolderIcon
Constructor Summary
MetalFileChooserUI(JFileChooser filechooser)
Method Summary
protected void | addControlButtons()
protected ActionMap | createActionMap()
protected JPanel | createDetailsView(JFileChooser fc)
protected MetalFileChooserUI.DirectoryComboBoxModel | createDirectoryComboBoxModel(JFileChooser fc)
protected javax.swing.plaf.metal.MetalFileChooserUI.DirectoryComboBoxRenderer | createDirectoryComboBoxRenderer(JFileChooser fc)
protected MetalFileChooserUI.FilterComboBoxModel | createFilterComboBoxModel()
protected MetalFileChooserUI.FilterComboBoxRenderer | createFilterComboBoxRenderer()
protected JPanel | createList(JFileChooser fc)
ListSelectionListener | createListSelectionListener(JFileChooser fc) Creates a selection listener for the list of files and directories.
PropertyChangeListener | createPropertyChangeListener(JFileChooser fc)
static ComponentUI | createUI(JComponent c)
void | ensureFileIsVisible(JFileChooser fc, File f)
protected ActionMap | getActionMap()
protected JButton | getApproveButton(JFileChooser fc)
protected JPanel | getBottomPanel()
protected JPanel | getButtonPanel()
String | getDirectoryName()
String | getFileName()
Dimension | getMaximumSize(JComponent c) Returns the maximum size of the JFileChooser.
Dimension | getMinimumSize(JComponent c) Returns the minimum size of the JFileChooser.
Dimension | getPreferredSize(JComponent c) Returns the preferred size of the specified JFileChooser.
void | installComponents(JFileChooser fc)
protected void | installListeners(JFileChooser fc)
protected void | installStrings(JFileChooser fc)
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
protected void | removeControlButtons()
void | rescanCurrentDirectory(JFileChooser fc)
void | setDirectoryName(String dirname)
protected void | setDirectorySelected(boolean directorySelected) Property to remember whether a directory is currently selected in the UI.
void | setFileName(String filename)
void | uninstallComponents(JFileChooser fc)
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
void | valueChanged(ListSelectionEvent e)
Methods inherited from class javax.swing.plaf.basic.BasicFileChooserUI
clearIconCache, createDoubleClickListener, createModel, getAcceptAllFileFilter, getAccessoryPanel, getApproveButtonMnemonic, getApproveButtonText, getApproveButtonToolTipText, getApproveSelectionAction, getCancelSelectionAction, getChangeToParentDirectoryAction, getDialogTitle, getDirectory, getFileChooser, getFileView, getGoHomeAction, getModel, getNewFolderAction, getUpdateAction, installDefaults, installIcons, isDirectorySelected, setDirectory, uninstallDefaults, uninstallIcons, uninstallListeners, uninstallStrings
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, paint, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalFileChooserUI

public MetalFileChooserUI(JFileChooser filechooser)
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class BasicFileChooserUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallComponents

public void uninstallComponents(JFileChooser fc)
Overrides:
uninstallComponents in class BasicFileChooserUI

installComponents

public void installComponents(JFileChooser fc)
Overrides:
installComponents in class BasicFileChooserUI

getButtonPanel

protected JPanel getButtonPanel()

getBottomPanel

protected JPanel getBottomPanel()

installStrings

protected void installStrings(JFileChooser fc)
Overrides:
installStrings in class BasicFileChooserUI

installListeners

protected void installListeners(JFileChooser fc)
Overrides:
installListeners in class BasicFileChooserUI

getActionMap

protected ActionMap getActionMap()

createActionMap

protected ActionMap createActionMap()

createList

protected JPanel createList(JFileChooser fc)

createDetailsView

protected JPanel createDetailsView(JFileChooser fc)

createListSelectionListener

public ListSelectionListener createListSelectionListener(JFileChooser fc)
Creates a selection listener for the list of files and directories.

Overrides:
createListSelectionListener in class BasicFileChooserUI
Parameters:
fc - a JFileChooser
Returns:
a ListSelectionListener

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class BasicFileChooserUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Returns the preferred size of the specified JFileChooser. The preferred size is at least as large, in both height and width, as the preferred size recommended by the file chooser's layout manager.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
c - a JFileChooser
Returns:
a Dimension specifying the preferred width and height of the file chooser
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent c)
Returns the minimum size of the JFileChooser.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
c - a JFileChooser
Returns:
a Dimension specifying the minimum width and height of the file chooser
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent c)
Returns the maximum size of the JFileChooser.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
c - a JFileChooser
Returns:
a Dimension specifying the maximum width and height of the file chooser
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

createPropertyChangeListener

public PropertyChangeListener createPropertyChangeListener(JFileChooser fc)
Overrides:
createPropertyChangeListener in class BasicFileChooserUI

removeControlButtons

protected void removeControlButtons()

addControlButtons

protected void addControlButtons()

ensureFileIsVisible

public void ensureFileIsVisible(JFileChooser fc,
                                File f)
Overrides:
ensureFileIsVisible in class BasicFileChooserUI

rescanCurrentDirectory

public void rescanCurrentDirectory(JFileChooser fc)
Overrides:
rescanCurrentDirectory in class BasicFileChooserUI

getFileName

public String getFileName()
Overrides:
getFileName in class BasicFileChooserUI

setFileName

public void setFileName(String filename)
Overrides:
setFileName in class BasicFileChooserUI

setDirectorySelected

protected void setDirectorySelected(boolean directorySelected)
Property to remember whether a directory is currently selected in the UI. This is normally called by the UI on a selection event.

Overrides:
setDirectorySelected in class BasicFileChooserUI
Parameters:
directorySelected - if a directory is currently selected.
Since:
1.4

getDirectoryName

public String getDirectoryName()
Overrides:
getDirectoryName in class BasicFileChooserUI

setDirectoryName

public void setDirectoryName(String dirname)
Overrides:
setDirectoryName in class BasicFileChooserUI

createDirectoryComboBoxRenderer

protected javax.swing.plaf.metal.MetalFileChooserUI.DirectoryComboBoxRenderer createDirectoryComboBoxRenderer(JFileChooser fc)

createDirectoryComboBoxModel

protected MetalFileChooserUI.DirectoryComboBoxModel createDirectoryComboBoxModel(JFileChooser fc)

createFilterComboBoxRenderer

protected MetalFileChooserUI.FilterComboBoxRenderer createFilterComboBoxRenderer()

createFilterComboBoxModel

protected MetalFileChooserUI.FilterComboBoxModel createFilterComboBoxModel()

valueChanged

public void valueChanged(ListSelectionEvent e)

getApproveButton

protected JButton getApproveButton(JFileChooser fc)
Overrides:
getApproveButton in class BasicFileChooserUI
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalFileChooserUI.DirectoryComboBoxAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalFileChooserUI.DirectoryComboBoxAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.plaf.metal.MetalFileChooserUI.DirectoryComboBoxAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
MetalFileChooserUI
protected class MetalFileChooserUI.DirectoryComboBoxAction
extends AbstractAction

Acts when DirectoryComboBox has changed the selected item.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
protected MetalFileChooserUI.DirectoryComboBoxAction()
Method Summary
 void actionPerformed(ActionEvent e)
Invoked when an action occurs.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalFileChooserUI.DirectoryComboBoxAction

protected MetalFileChooserUI.DirectoryComboBoxAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalFileChooserUI.DirectoryComboBoxModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalFileChooserUI.DirectoryComboBoxModel

java.lang.Object
    extended by  javax.swing.AbstractListModel
        extended by  javax.swing.plaf.metal.MetalFileChooserUI.DirectoryComboBoxModel
All Implemented Interfaces:
Serializable, ComboBoxModel, ListModel
Enclosing class:
MetalFileChooserUI
protected class MetalFileChooserUI.DirectoryComboBoxModel
extends AbstractListModel
implements ComboBoxModel

Data model for a type-face selection combo-box.

Field Summary
Fields inherited from class javax.swing.AbstractListModel
listenerList
Constructor Summary
MetalFileChooserUI.DirectoryComboBoxModel()
Method Summary
int | getDepth(int i)
Object | getElementAt(int index) Returns the value at the specified index.
Object | getSelectedItem() Returns the selected item
int | getSize() Returns the length of the list.
void | setSelectedItem(Object selectedDirectory) Set the selected item.
Methods inherited from class javax.swing.AbstractListModel
addListDataListener, fireContentsChanged, fireIntervalAdded, fireIntervalRemoved, getListDataListeners, getListeners, removeListDataListener
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.swing.ListModel
addListDataListener, removeListDataListener

Constructor Detail

MetalFileChooserUI.DirectoryComboBoxModel

public MetalFileChooserUI.DirectoryComboBoxModel()
Method Detail

getDepth

public int getDepth(int i)

setSelectedItem

public void setSelectedItem(Object selectedDirectory)
Description copied from interface: ComboBoxModel
Set the selected item. The implementation of this method should notify all registered ListDataListeners that the contents have changed.

Specified by:
setSelectedItem in interface ComboBoxModel
Parameters:
selectedDirectory - the list object to select or null to clear the selection

getSelectedItem

public Object getSelectedItem()
Description copied from interface: ComboBoxModel
Returns the selected item

Specified by:
getSelectedItem in interface ComboBoxModel
Returns:
The selected item or null if there is no selection

getSize

public int getSize()
Description copied from interface: ListModel
Returns the length of the list.

Specified by:
getSize in interface ListModel
Returns:
the length of the list

getElementAt

public Object getElementAt(int index)
Description copied from interface: ListModel
Returns the value at the specified index.

Specified by:
getElementAt in interface ListModel
Parameters:
index - the requested index
Returns:
the value at index
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalFileChooserUI.FileRenderer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalFileChooserUI.FileRenderer

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JLabel
                    extended by  javax.swing.DefaultListCellRenderer
                        extended by  javax.swing.plaf.metal.MetalFileChooserUI.FileRenderer
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, ListCellRenderer, SwingConstants
Enclosing class:
MetalFileChooserUI
protected class MetalFileChooserUI.FileRenderer
extends DefaultListCellRenderer

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.DefaultListCellRenderer
DefaultListCellRenderer.UIResource
Nested classes/interfaces inherited from class javax.swing.JLabel
JLabel.AccessibleJLabel
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.DefaultListCellRenderer
noFocusBorder
Fields inherited from class javax.swing.JLabel
labelFor
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
protected MetalFileChooserUI.FileRenderer()
Method Summary
Methods inherited from class javax.swing.DefaultListCellRenderer
firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getListCellRendererComponent, invalidate, isOpaque, repaint, repaint, repaint, revalidate, validate
Methods inherited from class javax.swing.JLabel
checkHorizontalKey, checkVerticalKey, getAccessibleContext, getDisabledIcon, getDisplayedMnemonic, getDisplayedMnemonicIndex, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getLabelFor, getText, getUI, getUIClassID, getVerticalAlignment, getVerticalTextPosition, imageUpdate, paramString, setDisabledIcon, setDisplayedMnemonic, setDisplayedMnemonic, setDisplayedMnemonicIndex, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabelFor, setText, setUI, setVerticalAlignment, setVerticalTextPosition, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MetalFileChooserUI.FileRenderer

protected MetalFileChooserUI.FileRenderer()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalFileChooserUI.FilterComboBoxModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalFileChooserUI.FilterComboBoxModel

java.lang.Object
    extended by  javax.swing.AbstractListModel
        extended by  javax.swing.plaf.metal.MetalFileChooserUI.FilterComboBoxModel
All Implemented Interfaces:
PropertyChangeListener, Serializable, EventListener, ComboBoxModel, ListModel
Enclosing class:
MetalFileChooserUI
protected class MetalFileChooserUI.FilterComboBoxModel
extends AbstractListModel
implements ComboBoxModel, PropertyChangeListener

Data model for a type-face selection combo-box.

Field Summary
protected  FileFilter[] filters
Fields inherited from class javax.swing.AbstractListModel
listenerList
Constructor Summary
protected MetalFileChooserUI.FilterComboBoxModel()
Method Summary
Object | getElementAt(int index) Returns the value at the specified index.
Object | getSelectedItem() Returns the selected item
int | getSize() Returns the length of the list.
void | propertyChange(PropertyChangeEvent e) This method gets called when a bound property is changed.
void | setSelectedItem(Object filter) Set the selected item.
Methods inherited from class javax.swing.AbstractListModel
addListDataListener, fireContentsChanged, fireIntervalAdded, fireIntervalRemoved, getListDataListeners, getListeners, removeListDataListener
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.swing.ListModel
addListDataListener, removeListDataListener

Field Detail

filters

protected FileFilter[] filters
Constructor Detail

MetalFileChooserUI.FilterComboBoxModel

protected MetalFileChooserUI.FilterComboBoxModel()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.

setSelectedItem

public void setSelectedItem(Object filter)
Description copied from interface: ComboBoxModel
Set the selected item. The implementation of this method should notify all registered ListDataListeners that the contents have changed.

Specified by:
setSelectedItem in interface ComboBoxModel
Parameters:
filter - the list object to select or null to clear the selection

getSelectedItem

public Object getSelectedItem()
Description copied from interface: ComboBoxModel
Returns the selected item

Specified by:
getSelectedItem in interface ComboBoxModel
Returns:
The selected item or null if there is no selection

getSize

public int getSize()
Description copied from interface: ListModel
Returns the length of the list.

Specified by:
getSize in interface ListModel
Returns:
the length of the list

getElementAt

public Object getElementAt(int index)
Description copied from interface: ListModel
Returns the value at the specified index.

Specified by:
getElementAt in interface ListModel
Parameters:
index - the requested index
Returns:
the value at index
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalFileChooserUI.FilterComboBoxRenderer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalFileChooserUI.FilterComboBoxRenderer

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JLabel
                    extended by  javax.swing.DefaultListCellRenderer
                        extended by  javax.swing.plaf.metal.MetalFileChooserUI.FilterComboBoxRenderer
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, ListCellRenderer, SwingConstants
Enclosing class:
MetalFileChooserUI
public class MetalFileChooserUI.FilterComboBoxRenderer
extends DefaultListCellRenderer

Render different type sizes and styles.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.DefaultListCellRenderer
DefaultListCellRenderer.UIResource
Nested classes/interfaces inherited from class javax.swing.JLabel
JLabel.AccessibleJLabel
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.DefaultListCellRenderer
noFocusBorder
Fields inherited from class javax.swing.JLabel
labelFor
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
MetalFileChooserUI.FilterComboBoxRenderer()
Method Summary
 Component getListCellRendererComponent(JList list, Object value, int index, boolean isSelected, boolean cellHasFocus)
Return a component that has been configured to display the specified value.
Methods inherited from class javax.swing.DefaultListCellRenderer
firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, invalidate, isOpaque, repaint, repaint, repaint, revalidate, validate
Methods inherited from class javax.swing.JLabel
checkHorizontalKey, checkVerticalKey, getAccessibleContext, getDisabledIcon, getDisplayedMnemonic, getDisplayedMnemonicIndex, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getLabelFor, getText, getUI, getUIClassID, getVerticalAlignment, getVerticalTextPosition, imageUpdate, paramString, setDisabledIcon, setDisplayedMnemonic, setDisplayedMnemonic, setDisplayedMnemonicIndex, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabelFor, setText, setUI, setVerticalAlignment, setVerticalTextPosition, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MetalFileChooserUI.FilterComboBoxRenderer

public MetalFileChooserUI.FilterComboBoxRenderer()
Method Detail

getListCellRendererComponent

public Component getListCellRendererComponent(JList list,
                                              Object value,
                                              int index,
                                              boolean isSelected,
                                              boolean cellHasFocus)
Description copied from interface: ListCellRenderer
Return a component that has been configured to display the specified value. That component's paint method is then called to "render" the cell. If it is necessary to compute the dimensions of a list because the list cells do not have a fixed size, this method is called to generate a component on which getPreferredSize can be invoked.

Specified by:
getListCellRendererComponent in interface ListCellRenderer
Overrides:
getListCellRendererComponent in class DefaultListCellRenderer
Parameters:
list - The JList we're painting.
value - The value returned by list.getModel().getElementAt(index).
index - The cells index.
isSelected - True if the specified cell was selected.
cellHasFocus - True if the specified cell has the focus.
Returns:
A component whose paint() method will render the specified value.
See Also:
JList, ListSelectionModel, ListModel
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalFileChooserUI.SingleClickListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalFileChooserUI.SingleClickListener

java.lang.Object
    extended by  java.awt.event.MouseAdapter
        extended by  javax.swing.plaf.metal.MetalFileChooserUI.SingleClickListener
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, EventListener
Enclosing class:
MetalFileChooserUI
protected class MetalFileChooserUI.SingleClickListener
extends MouseAdapter

Constructor Summary
MetalFileChooserUI.SingleClickListener(JList list)
Method Summary
Methods inherited from class java.awt.event.MouseAdapter
mouseClicked, mouseDragged, mouseEntered, mouseExited, mouseMoved, mousePressed, mouseReleased, mouseWheelMoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalFileChooserUI.SingleClickListener

public MetalFileChooserUI.SingleClickListener(JList list)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalIconFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalIconFactory

java.lang.Object
    extended by  javax.swing.plaf.metal.MetalIconFactory
All Implemented Interfaces:
Serializable
public class MetalIconFactory
extends Object
implements Serializable

Factory object that vends Icons for the JavaTM look and feel (Metal). These icons are used extensively in Metal via the defaults mechanism. While other look and feels often use GIFs for icons, creating icons in code facilitates switching to other themes.

Each method in this class returns either an Icon or null, where null implies that there is no default icon.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
static class | MetalIconFactory.FileIcon16 Warning: Serialized objects of this class will not be compatible with future Swing releases.
static class | MetalIconFactory.FolderIcon16 Warning: Serialized objects of this class will not be compatible with future Swing releases.
static class | MetalIconFactory.PaletteCloseIcon Defines an icon for Palette close
static class | MetalIconFactory.TreeControlIcon Warning: Serialized objects of this class will not be compatible with future Swing releases.
static class | MetalIconFactory.TreeFolderIcon Warning: Serialized objects of this class will not be compatible with future Swing releases.
static class | MetalIconFactory.TreeLeafIcon
Field Summary
static boolean | DARK
static boolean | LIGHT
Constructor Summary
MetalIconFactory()
Method Summary
static Icon | getCheckBoxIcon() Returns a checkbox icon.
static Icon | getCheckBoxMenuItemIcon()
static Icon | getFileChooserDetailViewIcon()
static Icon | getFileChooserHomeFolderIcon()
static Icon | getFileChooserListViewIcon()
static Icon | getFileChooserNewFolderIcon()
static Icon | getFileChooserUpFolderIcon()
static Icon | getHorizontalSliderThumbIcon()
static Icon | getInternalFrameAltMaximizeIcon(int size)
static Icon | getInternalFrameCloseIcon(int size)
static Icon | getInternalFrameDefaultMenuIcon()
static Icon | getInternalFrameMaximizeIcon(int size)
static Icon | getInternalFrameMinimizeIcon(int size)
static Icon | getMenuArrowIcon()
static Icon | getMenuItemArrowIcon()
static Icon | getMenuItemCheckIcon() Returns an icon to be used by JCheckBoxMenuItem.
static Icon | getRadioButtonIcon()
static Icon | getRadioButtonMenuItemIcon()
static Icon | getTreeComputerIcon()
static Icon | getTreeControlIcon(boolean isCollapsed)
static Icon | getTreeFloppyDriveIcon()
static Icon | getTreeFolderIcon()
static Icon | getTreeHardDriveIcon()
static Icon | getTreeLeafIcon()
static Icon | getVerticalSliderThumbIcon()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DARK

public static final boolean DARK
See Also:
Constant Field Values

LIGHT

public static final boolean LIGHT
See Also:
Constant Field Values
Constructor Detail

MetalIconFactory

public MetalIconFactory()
Method Detail

getFileChooserDetailViewIcon

public static Icon getFileChooserDetailViewIcon()

getFileChooserHomeFolderIcon

public static Icon getFileChooserHomeFolderIcon()

getFileChooserListViewIcon

public static Icon getFileChooserListViewIcon()

getFileChooserNewFolderIcon

public static Icon getFileChooserNewFolderIcon()

getFileChooserUpFolderIcon

public static Icon getFileChooserUpFolderIcon()

getInternalFrameAltMaximizeIcon

public static Icon getInternalFrameAltMaximizeIcon(int size)

getInternalFrameCloseIcon

public static Icon getInternalFrameCloseIcon(int size)

getInternalFrameDefaultMenuIcon

public static Icon getInternalFrameDefaultMenuIcon()

getInternalFrameMaximizeIcon

public static Icon getInternalFrameMaximizeIcon(int size)

getInternalFrameMinimizeIcon

public static Icon getInternalFrameMinimizeIcon(int size)

getRadioButtonIcon

public static Icon getRadioButtonIcon()

getCheckBoxIcon

public static Icon getCheckBoxIcon()
Returns a checkbox icon.

Since:
1.3

getTreeComputerIcon

public static Icon getTreeComputerIcon()

getTreeFloppyDriveIcon

public static Icon getTreeFloppyDriveIcon()

getTreeFolderIcon

public static Icon getTreeFolderIcon()

getTreeHardDriveIcon

public static Icon getTreeHardDriveIcon()

getTreeLeafIcon

public static Icon getTreeLeafIcon()

getTreeControlIcon

public static Icon getTreeControlIcon(boolean isCollapsed)

getMenuArrowIcon

public static Icon getMenuArrowIcon()

getMenuItemCheckIcon

public static Icon getMenuItemCheckIcon()
Returns an icon to be used by JCheckBoxMenuItem.

Returns:
the default icon for check box menu items, or null if no default exists

getMenuItemArrowIcon

public static Icon getMenuItemArrowIcon()

getCheckBoxMenuItemIcon

public static Icon getCheckBoxMenuItemIcon()

getRadioButtonMenuItemIcon

public static Icon getRadioButtonMenuItemIcon()

getHorizontalSliderThumbIcon

public static Icon getHorizontalSliderThumbIcon()

getVerticalSliderThumbIcon

public static Icon getVerticalSliderThumbIcon()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalIconFactory.FileIcon16

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalIconFactory.FileIcon16

java.lang.Object
    extended by  javax.swing.plaf.metal.MetalIconFactory.FileIcon16
All Implemented Interfaces:
Serializable, Icon
Direct Known Subclasses:
MetalIconFactory.TreeLeafIcon
Enclosing class:
MetalIconFactory
public static class MetalIconFactory.FileIcon16
extends Object
implements Icon, Serializable

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
MetalIconFactory.FileIcon16()
Method Summary
int | getAdditionalHeight()
int | getIconHeight() Returns the icon's height.
int | getIconWidth() Returns the icon's width.
int | getShift()
void | paintIcon(Component c, Graphics g, int x, int y) Draw the icon at the specified location.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalIconFactory.FileIcon16

public MetalIconFactory.FileIcon16()
Method Detail

paintIcon

public void paintIcon(Component c,
                      Graphics g,
                      int x,
                      int y)
Description copied from interface: Icon
Draw the icon at the specified location. Icon implementations may use the Component argument to get properties useful for painting, e.g. the foreground or background color.

Specified by:
paintIcon in interface Icon

getShift

public int getShift()

getAdditionalHeight

public int getAdditionalHeight()

getIconWidth

public int getIconWidth()
Description copied from interface: Icon
Returns the icon's width.

Specified by:
getIconWidth in interface Icon
Returns:
an int specifying the fixed width of the icon.

getIconHeight

public int getIconHeight()
Description copied from interface: Icon
Returns the icon's height.

Specified by:
getIconHeight in interface Icon
Returns:
an int specifying the fixed height of the icon.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalIconFactory.FolderIcon16

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalIconFactory.FolderIcon16

java.lang.Object
    extended by  javax.swing.plaf.metal.MetalIconFactory.FolderIcon16
All Implemented Interfaces:
Serializable, Icon
Direct Known Subclasses:
MetalIconFactory.TreeFolderIcon
Enclosing class:
MetalIconFactory
public static class MetalIconFactory.FolderIcon16
extends Object
implements Icon, Serializable

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
MetalIconFactory.FolderIcon16()
Method Summary
int | getAdditionalHeight()
int | getIconHeight() Returns the icon's height.
int | getIconWidth() Returns the icon's width.
int | getShift()
void | paintIcon(Component c, Graphics g, int x, int y) Draw the icon at the specified location.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalIconFactory.FolderIcon16

public MetalIconFactory.FolderIcon16()
Method Detail

paintIcon

public void paintIcon(Component c,
                      Graphics g,
                      int x,
                      int y)
Description copied from interface: Icon
Draw the icon at the specified location. Icon implementations may use the Component argument to get properties useful for painting, e.g. the foreground or background color.

Specified by:
paintIcon in interface Icon

getShift

public int getShift()

getAdditionalHeight

public int getAdditionalHeight()

getIconWidth

public int getIconWidth()
Description copied from interface: Icon
Returns the icon's width.

Specified by:
getIconWidth in interface Icon
Returns:
an int specifying the fixed width of the icon.

getIconHeight

public int getIconHeight()
Description copied from interface: Icon
Returns the icon's height.

Specified by:
getIconHeight in interface Icon
Returns:
an int specifying the fixed height of the icon.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalIconFactory.PaletteCloseIcon

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalIconFactory.PaletteCloseIcon

java.lang.Object
    extended by  javax.swing.plaf.metal.MetalIconFactory.PaletteCloseIcon
All Implemented Interfaces:
Serializable, Icon, UIResource
Enclosing class:
MetalIconFactory
public static class MetalIconFactory.PaletteCloseIcon
extends Object
implements Icon, UIResource, Serializable

Defines an icon for Palette close

Since:
1.3

Constructor Summary
MetalIconFactory.PaletteCloseIcon()
Method Summary
int | getIconHeight() Returns the icon's height.
int | getIconWidth() Returns the icon's width.
void | paintIcon(Component c, Graphics g, int x, int y) Draw the icon at the specified location.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalIconFactory.PaletteCloseIcon

public MetalIconFactory.PaletteCloseIcon()
Method Detail

paintIcon

public void paintIcon(Component c,
                      Graphics g,
                      int x,
                      int y)
Description copied from interface: Icon
Draw the icon at the specified location. Icon implementations may use the Component argument to get properties useful for painting, e.g. the foreground or background color.

Specified by:
paintIcon in interface Icon

getIconWidth

public int getIconWidth()
Description copied from interface: Icon
Returns the icon's width.

Specified by:
getIconWidth in interface Icon
Returns:
an int specifying the fixed width of the icon.

getIconHeight

public int getIconHeight()
Description copied from interface: Icon
Returns the icon's height.

Specified by:
getIconHeight in interface Icon
Returns:
an int specifying the fixed height of the icon.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalIconFactory.TreeControlIcon

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalIconFactory.TreeControlIcon

java.lang.Object
    extended by  javax.swing.plaf.metal.MetalIconFactory.TreeControlIcon
All Implemented Interfaces:
Serializable, Icon
Enclosing class:
MetalIconFactory
public static class MetalIconFactory.TreeControlIcon
extends Object
implements Icon, Serializable

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected  boolean isLight
Constructor Summary
MetalIconFactory.TreeControlIcon(boolean isCollapsed)
Method Summary
int | getIconHeight() Returns the icon's height.
int | getIconWidth() Returns the icon's width.
void | paintIcon(Component c, Graphics g, int x, int y) Draw the icon at the specified location.
void | paintMe(Component c, Graphics g, int x, int y)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

isLight

protected boolean isLight
Constructor Detail

MetalIconFactory.TreeControlIcon

public MetalIconFactory.TreeControlIcon(boolean isCollapsed)
Method Detail

paintIcon

public void paintIcon(Component c,
                      Graphics g,
                      int x,
                      int y)
Description copied from interface: Icon
Draw the icon at the specified location. Icon implementations may use the Component argument to get properties useful for painting, e.g. the foreground or background color.

Specified by:
paintIcon in interface Icon

paintMe

public void paintMe(Component c,
                    Graphics g,
                    int x,
                    int y)

getIconWidth

public int getIconWidth()
Description copied from interface: Icon
Returns the icon's width.

Specified by:
getIconWidth in interface Icon
Returns:
an int specifying the fixed width of the icon.

getIconHeight

public int getIconHeight()
Description copied from interface: Icon
Returns the icon's height.

Specified by:
getIconHeight in interface Icon
Returns:
an int specifying the fixed height of the icon.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalIconFactory.TreeFolderIcon

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalIconFactory.TreeFolderIcon

java.lang.Object
    extended by  javax.swing.plaf.metal.MetalIconFactory.FolderIcon16
        extended by  javax.swing.plaf.metal.MetalIconFactory.TreeFolderIcon
All Implemented Interfaces:
Serializable, Icon
Enclosing class:
MetalIconFactory
public static class MetalIconFactory.TreeFolderIcon
extends MetalIconFactory.FolderIcon16

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
MetalIconFactory.TreeFolderIcon()
Method Summary
int | getAdditionalHeight()
int | getShift()
Methods inherited from class javax.swing.plaf.metal.MetalIconFactory.FolderIcon16
getIconHeight, getIconWidth, paintIcon
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalIconFactory.TreeFolderIcon

public MetalIconFactory.TreeFolderIcon()
Method Detail

getShift

public int getShift()
Overrides:
getShift in class MetalIconFactory.FolderIcon16

getAdditionalHeight

public int getAdditionalHeight()
Overrides:
getAdditionalHeight in class MetalIconFactory.FolderIcon16
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalIconFactory.TreeLeafIcon

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalIconFactory.TreeLeafIcon

java.lang.Object
    extended by  javax.swing.plaf.metal.MetalIconFactory.FileIcon16
        extended by  javax.swing.plaf.metal.MetalIconFactory.TreeLeafIcon
All Implemented Interfaces:
Serializable, Icon
Enclosing class:
MetalIconFactory
public static class MetalIconFactory.TreeLeafIcon
extends MetalIconFactory.FileIcon16

Constructor Summary
MetalIconFactory.TreeLeafIcon()
Method Summary
int | getAdditionalHeight()
int | getShift()
Methods inherited from class javax.swing.plaf.metal.MetalIconFactory.FileIcon16
getIconHeight, getIconWidth, paintIcon
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalIconFactory.TreeLeafIcon

public MetalIconFactory.TreeLeafIcon()
Method Detail

getShift

public int getShift()
Overrides:
getShift in class MetalIconFactory.FileIcon16

getAdditionalHeight

public int getAdditionalHeight()
Overrides:
getAdditionalHeight in class MetalIconFactory.FileIcon16
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalInternalFrameTitlePane

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalInternalFrameTitlePane

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.plaf.basic.BasicInternalFrameTitlePane
                    extended by  javax.swing.plaf.metal.MetalInternalFrameTitlePane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable
public class MetalInternalFrameTitlePane
extends BasicInternalFrameTitlePane

Class that manages a JLF title bar

Since:
1.3

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicInternalFrameTitlePane
BasicInternalFrameTitlePane.CloseAction, BasicInternalFrameTitlePane.IconifyAction, BasicInternalFrameTitlePane.MaximizeAction, BasicInternalFrameTitlePane.MoveAction, BasicInternalFrameTitlePane.PropertyChangeHandler, BasicInternalFrameTitlePane.RestoreAction, BasicInternalFrameTitlePane.SizeAction, BasicInternalFrameTitlePane.SystemMenuBar, BasicInternalFrameTitlePane.TitlePaneLayout
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected boolean | isPalette
protected Icon | paletteCloseIcon
protected int | paletteTitleHeight
Fields inherited from class javax.swing.plaf.basic.BasicInternalFrameTitlePane
CLOSE_CMD, closeAction, closeButton, closeIcon, frame, iconButton, iconIcon, ICONIFY_CMD, iconifyAction, maxButton, maxIcon, MAXIMIZE_CMD, maximizeAction, menuBar, minIcon, MOVE_CMD, moveAction, notSelectedTextColor, notSelectedTitleColor, propertyChangeListener, RESTORE_CMD, restoreAction, selectedTextColor, selectedTitleColor, SIZE_CMD, sizeAction, windowMenu
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
MetalInternalFrameTitlePane(JInternalFrame f)
Method Summary
void | addNotify() Notifies this component that it now has a parent component.
protected void | addSubComponents() Override the parent's method avoid creating a menu bar.
protected void | addSystemMenuItems(JMenu systemMenu) Override the parent's method to do nothing.
protected void | assembleSystemMenu() Override the parent's method to do nothing.
protected void | createButtons()
protected LayoutManager | createLayout()
protected PropertyChangeListener | createPropertyChangeListener()
protected void | installDefaults()
void | paintComponent(Graphics g) Calls the UI delegate's paint method, if the UI delegate is non-null.
void | paintPalette(Graphics g)
void | setPalette(boolean b)
protected void | showSystemMenu() Override the parent's method to do nothing.
protected void | uninstallDefaults()
Methods inherited from class javax.swing.plaf.basic.BasicInternalFrameTitlePane
createActions, createSystemMenu, createSystemMenuBar, enableActions, getTitle, installListeners, installTitlePane, paintTitleBackground, postClosingEvent, setButtonIcons, uninstallListeners
Methods inherited from class javax.swing.JComponent
addAncestorListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update, updateUI
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

isPalette

protected boolean isPalette

paletteCloseIcon

protected Icon paletteCloseIcon

paletteTitleHeight

protected int paletteTitleHeight
Constructor Detail

MetalInternalFrameTitlePane

public MetalInternalFrameTitlePane(JInternalFrame f)
Method Detail

addNotify

public void addNotify()
Description copied from class: JComponent
Notifies this component that it now has a parent component. When this method is invoked, the chain of parent components is set up with KeyboardAction event listeners.

Overrides:
addNotify in class JComponent
See Also:
JComponent.registerKeyboardAction(java.awt.event.ActionListener, java.lang.String, javax.swing.KeyStroke, int)

installDefaults

protected void installDefaults()
Overrides:
installDefaults in class BasicInternalFrameTitlePane

uninstallDefaults

protected void uninstallDefaults()
Overrides:
uninstallDefaults in class BasicInternalFrameTitlePane

createButtons

protected void createButtons()
Overrides:
createButtons in class BasicInternalFrameTitlePane

assembleSystemMenu

protected void assembleSystemMenu()
Override the parent's method to do nothing. Metal frames do not have system menus.

Overrides:
assembleSystemMenu in class BasicInternalFrameTitlePane

addSystemMenuItems

protected void addSystemMenuItems(JMenu systemMenu)
Override the parent's method to do nothing. Metal frames do not have system menus.

Overrides:
addSystemMenuItems in class BasicInternalFrameTitlePane

showSystemMenu

protected void showSystemMenu()
Override the parent's method to do nothing. Metal frames do not have system menus.

Overrides:
showSystemMenu in class BasicInternalFrameTitlePane

addSubComponents

protected void addSubComponents()
Override the parent's method avoid creating a menu bar. Metal frames do not have system menus.

Overrides:
addSubComponents in class BasicInternalFrameTitlePane

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener()
Overrides:
createPropertyChangeListener in class BasicInternalFrameTitlePane

createLayout

protected LayoutManager createLayout()
Overrides:
createLayout in class BasicInternalFrameTitlePane

paintPalette

public void paintPalette(Graphics g)

paintComponent

public void paintComponent(Graphics g)
Description copied from class: JComponent
Calls the UI delegate's paint method, if the UI delegate is non-null. We pass the delegate a copy of the Graphics object to protect the rest of the paint code from irrevocable changes (for example, Graphics.translate).

If you override this in a subclass you should not make permanent changes to the passed in Graphics. For example, you should not alter the clip Rectangle or modify the transform. If you need to do these operations you may find it easier to create a new Graphics from the passed in Graphics and manipulate it. Further, if you do not invoker super's implementation you must honor the opaque property, that is if this component is opaque, you must completely fill in the background in a non-opaque color. If you do not honor the opaque property you will likely see visual artifacts.

The passed in Graphics object might have a transform other than the identify transform installed on it. In this case, you might get unexpected results if you cumulatively apply another transform.

Overrides:
paintComponent in class BasicInternalFrameTitlePane
Parameters:
g - the Graphics object to protect
See Also:
JComponent.paint(java.awt.Graphics), ComponentUI

setPalette

public void setPalette(boolean b)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalInternalFrameUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalInternalFrameUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.InternalFrameUI
            extended by  javax.swing.plaf.basic.BasicInternalFrameUI
                extended by  javax.swing.plaf.metal.MetalInternalFrameUI

public class MetalInternalFrameUI
extends BasicInternalFrameUI

Metal implementation of JInternalFrame.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicInternalFrameUI
BasicInternalFrameUI.BasicInternalFrameListener, BasicInternalFrameUI.BorderListener, BasicInternalFrameUI.ComponentHandler, BasicInternalFrameUI.GlassPaneDispatcher, BasicInternalFrameUI.InternalFrameLayout, BasicInternalFrameUI.InternalFramePropertyChangeListener
Field Summary
protected static String IS_PALETTE
Fields inherited from class javax.swing.plaf.basic.BasicInternalFrameUI
borderListener, componentListener, eastPane, frame, glassPaneDispatcher, internalFrameLayout, northPane, openMenuKey, propertyChangeListener, southPane, titlePane, westPane
Constructor Summary
MetalInternalFrameUI(JInternalFrame b)
Method Summary
protected MouseInputAdapter | createBorderListener(JInternalFrame w) Returns the MouseInputAdapter that will be installed on the TitlePane.
protected JComponent | createNorthPane(JInternalFrame w)
static ComponentUI | createUI(JComponent c)
protected void | installKeyboardActions()
protected void | installListeners()
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
void | setPalette(boolean isPalette)
protected void | uninstallComponents()
protected void | uninstallKeyboardActions()
protected void | uninstallListeners()
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.basic.BasicInternalFrameUI
activateFrame, closeFrame, createComponentListener, createDesktopManager, createEastPane, createGlassPaneDispatcher, createInternalFrameListener, createLayoutManager, createPropertyChangeListener, createSouthPane, createWestPane, deactivateFrame, deiconifyFrame, deinstallMouseHandlers, getDesktopManager, getEastPane, getMaximumSize, getMinimumSize, getNorthPane, getPreferredSize, getSouthPane, getWestPane, iconifyFrame, installComponents, installDefaults, installMouseHandlers, isKeyBindingActive, isKeyBindingRegistered, maximizeFrame, minimizeFrame, replacePane, setEastPane, setKeyBindingActive, setKeyBindingRegistered, setNorthPane, setSouthPane, setupMenuCloseKey, setupMenuOpenKey, setWestPane, uninstallDefaults
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, paint, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

IS_PALETTE

protected static String IS_PALETTE
Constructor Detail

MetalInternalFrameUI

public MetalInternalFrameUI(JInternalFrame b)
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class BasicInternalFrameUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class BasicInternalFrameUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installListeners

protected void installListeners()
Overrides:
installListeners in class BasicInternalFrameUI

uninstallListeners

protected void uninstallListeners()
Overrides:
uninstallListeners in class BasicInternalFrameUI

installKeyboardActions

protected void installKeyboardActions()
Overrides:
installKeyboardActions in class BasicInternalFrameUI

uninstallKeyboardActions

protected void uninstallKeyboardActions()
Overrides:
uninstallKeyboardActions in class BasicInternalFrameUI

uninstallComponents

protected void uninstallComponents()
Overrides:
uninstallComponents in class BasicInternalFrameUI

createNorthPane

protected JComponent createNorthPane(JInternalFrame w)
Overrides:
createNorthPane in class BasicInternalFrameUI

setPalette

public void setPalette(boolean isPalette)

createBorderListener

protected MouseInputAdapter createBorderListener(JInternalFrame w)
Returns the MouseInputAdapter that will be installed on the TitlePane.

Overrides:
createBorderListener in class BasicInternalFrameUI
Parameters:
w - the JInternalFrame
Returns:
the MouseInputAdapter that will be installed on the TitlePane.
Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalLabelUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalLabelUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.LabelUI
            extended by  javax.swing.plaf.basic.BasicLabelUI
                extended by  javax.swing.plaf.metal.MetalLabelUI
All Implemented Interfaces:
PropertyChangeListener, EventListener
public class MetalLabelUI
extends BasicLabelUI

A Windows L&F implementation of LabelUI. This implementation is completely static, i.e. there's only one UIView implementation that's shared by all JLabel objects.

Field Summary
protected static MetalLabelUI metalLabelUI
The default MetalLabelUI instance.
Fields inherited from class javax.swing.plaf.basic.BasicLabelUI
labelUI
Constructor Summary
MetalLabelUI()
Method Summary
static ComponentUI | createUI(JComponent c)
protected void | paintDisabledText(JLabel l, Graphics g, String s, int textX, int textY) Just paint the text gray (Label.disabledForeground) rather than in the labels foreground color.
Methods inherited from class javax.swing.plaf.basic.BasicLabelUI
getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installComponents, installDefaults, installKeyboardActions, installListeners, installUI, layoutCL, paint, paintEnabledText, propertyChange, uninstallComponents, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

metalLabelUI

protected static MetalLabelUI metalLabelUI
The default MetalLabelUI instance. This field might not be used. To change the default instance use a subclass which overrides the createUI method, and place that class name in defaults table under the key "LabelUI".

Constructor Detail

MetalLabelUI

public MetalLabelUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

paintDisabledText

protected void paintDisabledText(JLabel l,
                                 Graphics g,
                                 String s,
                                 int textX,
                                 int textY)
Just paint the text gray (Label.disabledForeground) rather than in the labels foreground color.

Overrides:
paintDisabledText in class BasicLabelUI
See Also:
BasicLabelUI.paint(java.awt.Graphics, javax.swing.JComponent), BasicLabelUI.paintEnabledText(javax.swing.JLabel, java.awt.Graphics, java.lang.String, int, int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalLookAndFeel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalLookAndFeel

java.lang.Object
    extended by  javax.swing.LookAndFeel
        extended by  javax.swing.plaf.basic.BasicLookAndFeel
            extended by  javax.swing.plaf.metal.MetalLookAndFeel
All Implemented Interfaces:
Serializable
public class MetalLookAndFeel
extends BasicLookAndFeel

The Java Look and Feel, otherwise known as Metal.

Each of the ComponentUIs provided by MetalLookAndFeel derives its behavior from the defaults table. Unless otherwise noted each of the ComponentUI implementations in this package document the set of defaults they use. Unless otherwise noted the defaults are installed at the time installUI is invoked, and follow the recommendations outlined in LookAndFeel for installing defaults.

MetalLookAndFeel derives it's color palette and fonts from MetalTheme. The default theme is OceanTheme. The theme can be changed using the setCurrentTheme method, refer to it for details on changing the theme. Prior to 1.5 the default theme was DefaultMetalTheme. The system property "swing.metalTheme" can be set to "steel" to indicate the default should be DefaultMetalTheme.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
MetalTheme, DefaultMetalTheme, OceanTheme

Constructor Summary
MetalLookAndFeel()
Method Summary
protected void | createDefaultTheme() Ensures the current MetalTheme is non-null.
static ColorUIResource | getAcceleratorForeground() Returns the accelerator foreground color of the current theme.
static ColorUIResource | getAcceleratorSelectedForeground() Returns the accelerator selected foreground color of the current theme.
static ColorUIResource | getBlack() Returns the black color of the current theme.
static ColorUIResource | getControl() Returns the control color of the current theme.
static ColorUIResource | getControlDarkShadow() Returns the control dark shadow color of the current theme.
static ColorUIResource | getControlDisabled() Returns the control disabled color of the current theme.
static ColorUIResource | getControlHighlight() Returns the control highlight color of the current theme.
static ColorUIResource | getControlInfo() Returns the control info color of the current theme.
static ColorUIResource | getControlShadow() Returns the control shadow color of the current theme.
static ColorUIResource | getControlTextColor() Returns the control text color of the current theme.
static FontUIResource | getControlTextFont() Returns the control text font of the current theme.
static MetalTheme | getCurrentTheme() Return the theme currently being used by MetalLookAndFeel.
UIDefaults | getDefaults() Returns the look and feel defaults.
String | getDescription() Returns a short description of this look and feel.
static ColorUIResource | getDesktopColor() Returns the desktop color of the current theme.
Icon | getDisabledIcon(JComponent component, Icon icon) Returns an Icon with a disabled appearance.
Icon | getDisabledSelectedIcon(JComponent component, Icon icon) Returns an Icon for use by disabled components that are also selected.
static ColorUIResource | getFocusColor() Returns the focus color of the current theme.
static ColorUIResource | getHighlightedTextColor() Returns the highlighted text color of the current theme.
String | getID() Returns an identifier for this look and feel.
static ColorUIResource | getInactiveControlTextColor() Returns the inactive control text color of the current theme.
static ColorUIResource | getInactiveSystemTextColor() Returns the inactive system text color of the current theme.
LayoutStyle | getLayoutStyle() Returns a LayoutStyle implementing the Java look and feel design guidelines as specified at http://java.sun.com/products/jlf/ed2/book/HIG.Visual2.html.
static ColorUIResource | getMenuBackground() Returns the menu background color of the current theme.
static ColorUIResource | getMenuDisabledForeground() Returns the menu disabled foreground color of the current theme.
static ColorUIResource | getMenuForeground() Returns the menu foreground color of the current theme.
static ColorUIResource | getMenuSelectedBackground() Returns the menu selected background color of the current theme.
static ColorUIResource | getMenuSelectedForeground() Returns the menu selected foreground color of the current theme.
static FontUIResource | getMenuTextFont() Returns the menu text font of the current theme.
String | getName() Returns the name of this look and feel.
static ColorUIResource | getPrimaryControl() Returns the primary control color of the current theme.
static ColorUIResource | getPrimaryControlDarkShadow() Returns the primary control dark shadow color of the current theme.
static ColorUIResource | getPrimaryControlHighlight() Returns the primary control highlight color of the current theme.
static ColorUIResource | getPrimaryControlInfo() Returns the primary control info color of the current theme.
static ColorUIResource | getPrimaryControlShadow() Returns the primary control shadow color of the current theme.
static ColorUIResource | getSeparatorBackground() Returns the separator background color of the current theme.
static ColorUIResource | getSeparatorForeground() Returns the separator foreground color of the current theme.
static FontUIResource | getSubTextFont() Returns the sub-text font of the current theme.
boolean | getSupportsWindowDecorations() Returns true; metal can provide Window decorations.
static ColorUIResource | getSystemTextColor() Returns the system text color of the current theme.
static FontUIResource | getSystemTextFont() Returns the sytem text font of the current theme.
static ColorUIResource | getTextHighlightColor() Returns the text highlight color of the current theme.
static ColorUIResource | getUserTextColor() Returns the user text color of the current theme.
static FontUIResource | getUserTextFont() Returns the user text font of the current theme.
static ColorUIResource | getWhite() Returns the white color of the current theme.
static ColorUIResource | getWindowBackground() Returns the window background color of the current theme.
static ColorUIResource | getWindowTitleBackground() Returns the window title background color of the current theme.
static FontUIResource | getWindowTitleFont() Returns the window title font of the current theme.
static ColorUIResource | getWindowTitleForeground() Returns the window title foreground color of the current theme.
static ColorUIResource | getWindowTitleInactiveBackground() Returns the window title inactive background color of the current theme.
static ColorUIResource | getWindowTitleInactiveForeground() Returns the window title inactive foreground color of the current theme.
protected void | initClassDefaults(UIDefaults table) Populates table with mappings from uiClassID to the fully qualified name of the ui class.
protected void | initComponentDefaults(UIDefaults table) Populates table with the defaults for metal.
protected void | initSystemColorDefaults(UIDefaults table) Populates table with system colors.
boolean | isNativeLookAndFeel() Returns false; MetalLookAndFeel is not a native look and feel.
boolean | isSupportedLookAndFeel() Returns true; MetalLookAndFeel can be run on any platform.
void | provideErrorFeedback(Component component) Invoked when the user attempts an invalid operation, such as pasting into an uneditable JTextField that has focus.
static void | setCurrentTheme(MetalTheme theme) Set the theme used by MetalLookAndFeel.
Methods inherited from class javax.swing.plaf.basic.BasicLookAndFeel
createAudioAction, getAudioActionMap, initialize, loadSystemColors, playSound, uninitialize
Methods inherited from class javax.swing.LookAndFeel
getDesktopPropertyValue, installBorder, installColors, installColorsAndFont, installProperty, loadKeyBindings, makeComponentInputMap, makeIcon, makeInputMap, makeKeyBindings, toString, uninstallBorder
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MetalLookAndFeel

public MetalLookAndFeel()
Method Detail

getName

public String getName()
Returns the name of this look and feel. This returns "Metal".

Specified by:
getName in class LookAndFeel
Returns:
the name of this look and feel

getID

public String getID()
Returns an identifier for this look and feel. This returns "Metal".

Specified by:
getID in class LookAndFeel
Returns:
the identifier of this look and feel

getDescription

public String getDescription()
Returns a short description of this look and feel. This returns "The Java(tm) Look and Feel".

Specified by:
getDescription in class LookAndFeel
Returns:
a short description for the look and feel

isNativeLookAndFeel

public boolean isNativeLookAndFeel()
Returns false; MetalLookAndFeel is not a native look and feel.

Specified by:
isNativeLookAndFeel in class LookAndFeel
Returns:
false

isSupportedLookAndFeel

public boolean isSupportedLookAndFeel()
Returns true; MetalLookAndFeel can be run on any platform.

Specified by:
isSupportedLookAndFeel in class LookAndFeel
Returns:
true
See Also:
UIManager.setLookAndFeel(javax.swing.LookAndFeel)

getSupportsWindowDecorations

public boolean getSupportsWindowDecorations()
Returns true; metal can provide Window decorations.

Overrides:
getSupportsWindowDecorations in class LookAndFeel
Returns:
true
Since:
1.4
See Also:
JDialog.setDefaultLookAndFeelDecorated(boolean),
JFrame.setDefaultLookAndFeelDecorated(boolean),
JRootPane.setWindowDecorationStyle(int)

initClassDefaults

protected void initClassDefaults(UIDefaults table)
Populates table with mappings from uiClassID to the fully qualified name of the ui class. MetalLookAndFeel registers an entry for each of the classes in the package javax.swing.plaf.metal that are named MetalXXXUI. The string XXX is one of Swing's uiClassIDs. For the uiClassIDs that do not have a class in metal, the corresponding class in javax.swing.plaf.basic is used. For example, metal does not have a class named "MetalColorChooserUI", as such, javax.swing.plaf.basic.BasicColorChooserUI is used.

Overrides:
initClassDefaults in class BasicLookAndFeel
Parameters:
table - the UIDefaults instance the entries are added to
Throws:
NullPointerException - if table is null
See Also:
BasicLookAndFeel.initClassDefaults(javax.swing.UIDefaults)

initSystemColorDefaults

protected void initSystemColorDefaults(UIDefaults table)
Populates table with system colors. The following values are added to table:
Key | Value
"desktop" | theme.getDesktopColor()
"activeCaption" | theme.getWindowTitleBackground()
"activeCaptionText" | theme.getWindowTitleForeground()
"activeCaptionBorder" | theme.getPrimaryControlShadow()
"inactiveCaption" | theme.getWindowTitleInactiveBackground()
"inactiveCaptionText" | theme.getWindowTitleInactiveForeground()
"inactiveCaptionBorder" | theme.getControlShadow()
"window" | theme.getWindowBackground()
"windowBorder" | theme.getControl()
"windowText" | theme.getUserTextColor()
"menu" | theme.getMenuBackground()
"menuText" | theme.getMenuForeground()
"text" | theme.getWindowBackground()
"textText" | theme.getUserTextColor()
"textHighlight" | theme.getTextHighlightColor()
"textHighlightText" | theme.getHighlightedTextColor()
"textInactiveText" | theme.getInactiveSystemTextColor()
"control" | theme.getControl()
"controlText" | theme.getControlTextColor()
"controlHighlight" | theme.getControlHighlight()
"controlLtHighlight" | theme.getControlHighlight()
"controlShadow" | theme.getControlShadow()
"controlDkShadow" | theme.getControlDarkShadow()
"scrollbar" | theme.getControl()
"info" | theme.getPrimaryControl()
"infoText" | theme.getPrimaryControlInfo()
The value theme corresponds to the current MetalTheme.

Overrides:
initSystemColorDefaults in class BasicLookAndFeel
Parameters:
table - the UIDefaults object the values are added to
Throws:
NullPointerException - if table is null
See Also:
SystemColor, BasicLookAndFeel.getDefaults(), BasicLookAndFeel.loadSystemColors(javax.swing.UIDefaults, java.lang.String[], boolean)

initComponentDefaults

protected void initComponentDefaults(UIDefaults table)
Populates table with the defaults for metal.

Overrides:
initComponentDefaults in class BasicLookAndFeel
Parameters:
table - the UIDefaults to add the values to
Throws:
NullPointerException - if table is null

createDefaultTheme

protected void createDefaultTheme()
Ensures the current MetalTheme is non-null. This is a cover method for getCurrentTheme.

See Also:
getCurrentTheme()

getDefaults

public UIDefaults getDefaults()
Returns the look and feel defaults. This invokes, in order, createDefaultTheme(), super.getDefaults() and getCurrentTheme().addCustomEntriesToTable(table).

While this method is public, it should only be invoked by the UIManager when the look and feel is set as the current look and feel and after initialize has been invoked.

Overrides:
getDefaults in class BasicLookAndFeel
Returns:
the look and feel defaults
See Also:
createDefaultTheme(),
BasicLookAndFeel.getDefaults(),
MetalTheme.addCustomEntriesToTable(UIDefaults)

provideErrorFeedback

public void provideErrorFeedback(Component component)
Invoked when the user attempts an invalid operation, such as pasting into an uneditable JTextField that has focus. The default implementation beeps. Subclasses that wish different behavior should override this and provide the additional feedback.

Overrides:
provideErrorFeedback in class LookAndFeel
Parameters:
component - the Component the error occurred in, may be null indicating the error condition is not directly associated with a Component
Since:
1.4

setCurrentTheme

public static void setCurrentTheme(MetalTheme theme)
Set the theme used by MetalLookAndFeel.

After the theme is set, MetalLookAndFeel needs to be re-installed and the uis need to be recreated. The following shows how to do this:

   MetalLookAndFeel.setCurrentTheme(theme);

   // re-install the Metal Look and Feel
   UIManager.setLookAndFeel(new MetalLookAndFeel());

   // Update the ComponentUIs for all Components. This
   // needs to be invoked for all windows.
   SwingUtilities.updateComponentTreeUI(rootComponent);
If this is not done the results are undefined.

Parameters:
theme - the theme to use
Throws:
NullPointerException - if theme is null
See Also:
getCurrentTheme()

getCurrentTheme

public static MetalTheme getCurrentTheme()
Return the theme currently being used by MetalLookAndFeel. If the current theme is null, the default theme is created.

Returns:
the current theme
Since:
1.5
See Also:
setCurrentTheme(javax.swing.plaf.metal.MetalTheme)

getDisabledIcon

public Icon getDisabledIcon(JComponent component,
                            Icon icon)
Returns an Icon with a disabled appearance. This method is used to generate a disabled Icon when one has not been specified. For example, if you create a JButton and only specify an Icon via setIcon this method will be called to generate the disabled Icon. If null is passed as icon this method returns null.

Some look and feels might not render the disabled Icon, in which case they will ignore this.

Overrides:
getDisabledIcon in class LookAndFeel
Parameters:
component - JComponent that will display the Icon, may be null
icon - Icon to generate disable icon from.
Returns:
Disabled icon, or null if a suitable Icon can not be generated.
Since:
1.5

getDisabledSelectedIcon

public Icon getDisabledSelectedIcon(JComponent component,
                                    Icon icon)
Returns an Icon for use by disabled components that are also selected. This method is used to generate an Icon for components that are in both the disabled and selected states but do not have a specific Icon for this state. For example, if you create a JButton and only specify an Icon via setIcon this method will be called to generate the disabled and selected Icon. If null is passed as icon this method returns null.

Some look and feels might not render the disabled and selected Icon, in which case they will ignore this.

Overrides:
getDisabledSelectedIcon in class LookAndFeel
Parameters:
component - JComponent that will display the Icon, may be null
icon - Icon to generate disabled and selected icon from.
Returns:
Disabled and Selected icon, or null if a suitable Icon can not be generated.
Since:
1.5

getControlTextFont

public static FontUIResource getControlTextFont()
Returns the control text font of the current theme. This is a cover method for getCurrentTheme().getControlTextColor().

Returns:
the control text font
See Also:
MetalTheme

getSystemTextFont

public static FontUIResource getSystemTextFont()
Returns the sytem text font of the current theme. This is a cover method for getCurrentTheme().getSystemTextFont().

Returns:
the system text font
See Also:
MetalTheme

getUserTextFont

public static FontUIResource getUserTextFont()
Returns the user text font of the current theme. This is a cover method for getCurrentTheme().getUserTextFont().

Returns:
the user text font
See Also:
MetalTheme

getMenuTextFont

public static FontUIResource getMenuTextFont()
Returns the menu text font of the current theme. This is a cover method for getCurrentTheme().getMenuTextFont().

Returns:
the menu text font
See Also:
MetalTheme

getWindowTitleFont

public static FontUIResource getWindowTitleFont()
Returns the window title font of the current theme. This is a cover method for getCurrentTheme().getWindowTitleFont().

Returns:
the window title font
See Also:
MetalTheme

getSubTextFont

public static FontUIResource getSubTextFont()
Returns the sub-text font of the current theme. This is a cover method for getCurrentTheme().getSubTextFont().

Returns:
the sub-text font
See Also:
MetalTheme

getDesktopColor

public static ColorUIResource getDesktopColor()
Returns the desktop color of the current theme. This is a cover method for getCurrentTheme().getDesktopColor().

Returns:
the desktop color
See Also:
MetalTheme

getFocusColor

public static ColorUIResource getFocusColor()
Returns the focus color of the current theme. This is a cover method for getCurrentTheme().getFocusColor().

Returns:
the focus color
See Also:
MetalTheme

getWhite

public static ColorUIResource getWhite()
Returns the white color of the current theme. This is a cover method for getCurrentTheme().getWhite().

Returns:
the white color
See Also:
MetalTheme

getBlack

public static ColorUIResource getBlack()
Returns the black color of the current theme. This is a cover method for getCurrentTheme().getBlack().

Returns:
the black color
See Also:
MetalTheme

getControl

public static ColorUIResource getControl()
Returns the control color of the current theme. This is a cover method for getCurrentTheme().getControl().

Returns:
the control color
See Also:
MetalTheme

getControlShadow

public static ColorUIResource getControlShadow()
Returns the control shadow color of the current theme. This is a cover method for getCurrentTheme().getControlShadow().

Returns:
the control shadow color
See Also:
MetalTheme

getControlDarkShadow

public static ColorUIResource getControlDarkShadow()
Returns the control dark shadow color of the current theme. This is a cover method for getCurrentTheme().getControlDarkShadow().

Returns:
the control dark shadow color
See Also:
MetalTheme

getControlInfo

public static ColorUIResource getControlInfo()
Returns the control info color of the current theme. This is a cover method for getCurrentTheme().getControlInfo().

Returns:
the control info color
See Also:
MetalTheme

getControlHighlight

public static ColorUIResource getControlHighlight()
Returns the control highlight color of the current theme. This is a cover method for getCurrentTheme().getControlHighlight().

Returns:
the control highlight color
See Also:
MetalTheme

getControlDisabled

public static ColorUIResource getControlDisabled()
Returns the control disabled color of the current theme. This is a cover method for getCurrentTheme().getControlDisabled().

Returns:
the control disabled color
See Also:
MetalTheme

getPrimaryControl

public static ColorUIResource getPrimaryControl()
Returns the primary control color of the current theme. This is a cover method for getCurrentTheme().getPrimaryControl().

Returns:
the primary control color
See Also:
MetalTheme

getPrimaryControlShadow

public static ColorUIResource getPrimaryControlShadow()
Returns the primary control shadow color of the current theme. This is a cover method for getCurrentTheme().getPrimaryControlShadow().

Returns:
the primary control shadow color
See Also:
MetalTheme

getPrimaryControlDarkShadow

public static ColorUIResource getPrimaryControlDarkShadow()
Returns the primary control dark shadow color of the current theme. This is a cover method for getCurrentTheme().getPrimaryControlDarkShadow().

Returns:
the primary control dark shadow color
See Also:
MetalTheme

getPrimaryControlInfo

public static ColorUIResource getPrimaryControlInfo()
Returns the primary control info color of the current theme. This is a cover method for getCurrentTheme().getPrimaryControlInfo().

Returns:
the primary control info color
See Also:
MetalTheme

getPrimaryControlHighlight

public static ColorUIResource getPrimaryControlHighlight()
Returns the primary control highlight color of the current theme. This is a cover method for getCurrentTheme().getPrimaryControlHighlight().

Returns:
the primary control highlight color
See Also:
MetalTheme

getSystemTextColor

public static ColorUIResource getSystemTextColor()
Returns the system text color of the current theme. This is a cover method for getCurrentTheme().getSystemTextColor().

Returns:
the system text color
See Also:
MetalTheme

getControlTextColor

public static ColorUIResource getControlTextColor()
Returns the control text color of the current theme. This is a cover method for getCurrentTheme().getControlTextColor().

Returns:
the control text color
See Also:
MetalTheme

getInactiveControlTextColor

public static ColorUIResource getInactiveControlTextColor()
Returns the inactive control text color of the current theme. This is a cover method for getCurrentTheme().getInactiveControlTextColor().

Returns:
the inactive control text color
See Also:
MetalTheme

getInactiveSystemTextColor

public static ColorUIResource getInactiveSystemTextColor()
Returns the inactive system text color of the current theme. This is a cover method for getCurrentTheme().getInactiveSystemTextColor().

Returns:
the inactive system text color
See Also:
MetalTheme

getUserTextColor

public static ColorUIResource getUserTextColor()
Returns the user text color of the current theme. This is a cover method for getCurrentTheme().getUserTextColor().

Returns:
the user text color
See Also:
MetalTheme

getTextHighlightColor

public static ColorUIResource getTextHighlightColor()
Returns the text highlight color of the current theme. This is a cover method for getCurrentTheme().getTextHighlightColor().

Returns:
the text highlight color
See Also:
MetalTheme

getHighlightedTextColor

public static ColorUIResource getHighlightedTextColor()
Returns the highlighted text color of the current theme. This is a cover method for getCurrentTheme().getHighlightedTextColor().

Returns:
the highlighted text color
See Also:
MetalTheme

getWindowBackground

public static ColorUIResource getWindowBackground()
Returns the window background color of the current theme. This is a cover method for getCurrentTheme().getWindowBackground().

Returns:
the window background color
See Also:
MetalTheme

getWindowTitleBackground

public static ColorUIResource getWindowTitleBackground()
Returns the window title background color of the current theme. This is a cover method for getCurrentTheme().getWindowTitleBackground().

Returns:
the window title background color
See Also:
MetalTheme

getWindowTitleForeground

public static ColorUIResource getWindowTitleForeground()
Returns the window title foreground color of the current theme. This is a cover method for getCurrentTheme().getWindowTitleForeground().

Returns:
the window title foreground color
See Also:
MetalTheme

getWindowTitleInactiveBackground

public static ColorUIResource getWindowTitleInactiveBackground()
Returns the window title inactive background color of the current theme. This is a cover method for getCurrentTheme().getWindowTitleInactiveBackground().

Returns:
the window title inactive background color
See Also:
MetalTheme

getWindowTitleInactiveForeground

public static ColorUIResource getWindowTitleInactiveForeground()
Returns the window title inactive foreground color of the current theme. This is a cover method for getCurrentTheme().getWindowTitleInactiveForeground().

Returns:
the window title inactive foreground color
See Also:
MetalTheme

getMenuBackground

public static ColorUIResource getMenuBackground()
Returns the menu background color of the current theme. This is a cover method for getCurrentTheme().getMenuBackground().

Returns:
the menu background color
See Also:
MetalTheme

getMenuForeground

public static ColorUIResource getMenuForeground()
Returns the menu foreground color of the current theme. This is a cover method for getCurrentTheme().getMenuForeground().

Returns:
the menu foreground color
See Also:
MetalTheme

getMenuSelectedBackground

public static ColorUIResource getMenuSelectedBackground()
Returns the menu selected background color of the current theme. This is a cover method for getCurrentTheme().getMenuSelectedBackground().

Returns:
the menu selected background color
See Also:
MetalTheme

getMenuSelectedForeground

public static ColorUIResource getMenuSelectedForeground()
Returns the menu selected foreground color of the current theme. This is a cover method for getCurrentTheme().getMenuSelectedForeground().

Returns:
the menu selected foreground color
See Also:
MetalTheme

getMenuDisabledForeground

public static ColorUIResource getMenuDisabledForeground()
Returns the menu disabled foreground color of the current theme. This is a cover method for getCurrentTheme().getMenuDisabledForeground().

Returns:
the menu disabled foreground color
See Also:
MetalTheme

getSeparatorBackground

public static ColorUIResource getSeparatorBackground()
Returns the separator background color of the current theme. This is a cover method for getCurrentTheme().getSeparatorBackground().

Returns:
the separator background color
See Also:
MetalTheme

getSeparatorForeground

public static ColorUIResource getSeparatorForeground()
Returns the separator foreground color of the current theme. This is a cover method for getCurrentTheme().getSeparatorForeground().

Returns:
the separator foreground color
See Also:
MetalTheme

getAcceleratorForeground

public static ColorUIResource getAcceleratorForeground()
Returns the accelerator foreground color of the current theme. This is a cover method for getCurrentTheme().getAcceleratorForeground().

Returns:
the separator accelerator foreground color
See Also:
MetalTheme

getAcceleratorSelectedForeground

public static ColorUIResource getAcceleratorSelectedForeground()
Returns the accelerator selected foreground color of the current theme. This is a cover method for getCurrentTheme().getAcceleratorSelectedForeground().

Returns:
the accelerator selected foreground color
See Also:
MetalTheme

getLayoutStyle

public LayoutStyle getLayoutStyle()
Returns a LayoutStyle implementing the Java look and feel design guidelines as specified at http://java.sun.com/products/jlf/ed2/book/HIG.Visual2.html.

Overrides:
getLayoutStyle in class LookAndFeel
Returns:
LayoutStyle implementing the Java look and feel design guidelines
Since:
1.6
See Also:
LayoutStyle.getInstance()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalMenuBarUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalMenuBarUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.MenuBarUI
            extended by  javax.swing.plaf.basic.BasicMenuBarUI
                extended by  javax.swing.plaf.metal.MetalMenuBarUI

public class MetalMenuBarUI
extends BasicMenuBarUI

Metal implementation of MenuBarUI. This class is responsible for providing the metal look and feel for JMenuBars.

Since:
1.5
See Also:
MenuBarUI

Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicMenuBarUI
changeListener, containerListener, menuBar
Constructor Summary
MetalMenuBarUI()
Method Summary
static ComponentUI | createUI(JComponent x) Creates the ComponentUI implementation for the passed in component.
void | installUI(JComponent c) Configures the specified component appropriate for the metal look and feel.
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
void | update(Graphics g, JComponent c) If necessary paints the background of the component, then invokes paint.
Methods inherited from class javax.swing.plaf.basic.BasicMenuBarUI
createChangeListener, createContainerListener, getMaximumSize, getMinimumSize, installDefaults, installKeyboardActions, installListeners, uninstallDefaults, uninstallKeyboardActions, uninstallListeners
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getPreferredSize, paint
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalMenuBarUI

public MetalMenuBarUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent x)
Creates the ComponentUI implementation for the passed in component.

Parameters:
x - JComponent to create the ComponentUI implementation for
Returns:
ComponentUI implementation for x
Throws:
NullPointerException - if x is null

installUI

public void installUI(JComponent c)
Configures the specified component appropriate for the metal look and feel.

Overrides:
installUI in class BasicMenuBarUI
Parameters:
c - the component where this UI delegate is being installed
Throws:
NullPointerException - if c is null.
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Reverses configuration which was done on the specified component during installUI.

Overrides:
uninstallUI in class BasicMenuBarUI
Parameters:
c - the component where this UI delegate is being installed
Throws:
NullPointerException - if c is null.
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

update

public void update(Graphics g,
                   JComponent c)
If necessary paints the background of the component, then invokes paint.

Overrides:
update in class ComponentUI
Parameters:
g - Graphics to paint to
c - JComponent painting on
Throws:
NullPointerException - if g or c is null
Since:
1.5
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent), ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalPopupMenuSeparatorUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalPopupMenuSeparatorUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SeparatorUI
            extended by  javax.swing.plaf.basic.BasicSeparatorUI
                extended by  javax.swing.plaf.metal.MetalSeparatorUI
                    extended by  javax.swing.plaf.metal.MetalPopupMenuSeparatorUI

public class MetalPopupMenuSeparatorUI
extends MetalSeparatorUI

A Metal L&F implementation of PopupMenuSeparatorUI. This implementation is a "combined" view/controller.

Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicSeparatorUI
highlight, shadow
Constructor Summary
MetalPopupMenuSeparatorUI()
Method Summary
static ComponentUI | createUI(JComponent c)
Dimension | getPreferredSize(JComponent c) Returns the specified component's preferred size appropriate for the look and feel.
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
Methods inherited from class javax.swing.plaf.metal.MetalSeparatorUI
installDefaults
Methods inherited from class javax.swing.plaf.basic.BasicSeparatorUI
getMaximumSize, getMinimumSize, installListeners, installUI, uninstallDefaults, uninstallListeners, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalPopupMenuSeparatorUI

public MetalPopupMenuSeparatorUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class MetalSeparatorUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Overrides:
getPreferredSize in class MetalSeparatorUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalProgressBarUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalProgressBarUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ProgressBarUI
            extended by  javax.swing.plaf.basic.BasicProgressBarUI
                extended by  javax.swing.plaf.metal.MetalProgressBarUI

public class MetalProgressBarUI
extends BasicProgressBarUI

The Metal implementation of ProgressBarUI.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicProgressBarUI
BasicProgressBarUI.ChangeHandler
Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicProgressBarUI
boxRect, changeListener, progressBar
Constructor Summary
MetalProgressBarUI()
Method Summary
static ComponentUI | createUI(JComponent c)
void | paintDeterminate(Graphics g, JComponent c) Draws a bit of special highlighting on the progress bar.
void | paintIndeterminate(Graphics g, JComponent c) Draws a bit of special highlighting on the progress bar and bouncing box.
Methods inherited from class javax.swing.plaf.basic.BasicProgressBarUI
getAmountFull, getAnimationIndex, getBaseline, getBaselineResizeBehavior, getBox, getBoxLength, getCellLength, getCellSpacing, getFrameCount, getMaximumSize, getMinimumSize, getPreferredInnerHorizontal, getPreferredInnerVertical, getPreferredSize, getSelectionBackground, getSelectionForeground, getStringPlacement, incrementAnimationIndex, installDefaults, installListeners, installUI, paint, paintString, setAnimationIndex, setCellLength, setCellSpacing, startAnimationTimer, stopAnimationTimer, uninstallDefaults, uninstallListeners, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalProgressBarUI

public MetalProgressBarUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

paintDeterminate

public void paintDeterminate(Graphics g,
                             JComponent c)
Draws a bit of special highlighting on the progress bar. The core painting is deferred to the BasicProgressBar's paintDeterminate method.

Overrides:
paintDeterminate in class BasicProgressBarUI
Since:
1.4
See Also:
BasicProgressBarUI.paintIndeterminate(java.awt.Graphics, javax.swing.JComponent)

paintIndeterminate

public void paintIndeterminate(Graphics g,
                               JComponent c)
Draws a bit of special highlighting on the progress bar and bouncing box. The core painting is deferred to the BasicProgressBar's paintIndeterminate method.

Overrides:
paintIndeterminate in class BasicProgressBarUI
Since:
1.4
See Also:
BasicProgressBarUI.paintDeterminate(java.awt.Graphics, javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalRadioButtonUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalRadioButtonUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ButtonUI
            extended by  javax.swing.plaf.basic.BasicButtonUI
                extended by  javax.swing.plaf.basic.BasicToggleButtonUI
                    extended by  javax.swing.plaf.basic.BasicRadioButtonUI
                        extended by  javax.swing.plaf.metal.MetalRadioButtonUI
Direct Known Subclasses:
MetalCheckBoxUI
public class MetalRadioButtonUI
extends BasicRadioButtonUI

RadioButtonUI implementation for MetalRadioButtonUI

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected Color | disabledTextColor
protected Color | focusColor
protected Color | selectColor
Fields inherited from class javax.swing.plaf.basic.BasicRadioButtonUI
icon
Fields inherited from class javax.swing.plaf.basic.BasicButtonUI
defaultTextIconGap, defaultTextShiftOffset
Constructor Summary
MetalRadioButtonUI()
Method Summary
static ComponentUI | createUI(JComponent c)
protected Color | getDisabledTextColor()
protected Color | getFocusColor()
protected Color | getSelectColor()
void | installDefaults(AbstractButton b)
void | paint(Graphics g, JComponent c) paint the radio button
protected void | paintFocus(Graphics g, Rectangle t, Dimension d)
protected void | uninstallDefaults(AbstractButton b)
Methods inherited from class javax.swing.plaf.basic.BasicRadioButtonUI
getDefaultIcon, getPreferredSize, getPropertyPrefix
Methods inherited from class javax.swing.plaf.basic.BasicToggleButtonUI
getTextShiftOffset, paintIcon
Methods inherited from class javax.swing.plaf.basic.BasicButtonUI
clearTextShiftOffset, createButtonListener, getBaseline, getBaselineResizeBehavior, getDefaultTextIconGap, getMaximumSize, getMinimumSize, installKeyboardActions, installListeners, installUI, paintButtonPressed, paintFocus, paintIcon, paintText, paintText, setTextShiftOffset, uninstallKeyboardActions, uninstallListeners, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

focusColor

protected Color focusColor

selectColor

protected Color selectColor

disabledTextColor

protected Color disabledTextColor
Constructor Detail

MetalRadioButtonUI

public MetalRadioButtonUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installDefaults

public void installDefaults(AbstractButton b)
Overrides:
installDefaults in class BasicRadioButtonUI

uninstallDefaults

protected void uninstallDefaults(AbstractButton b)
Overrides:
uninstallDefaults in class BasicRadioButtonUI

getSelectColor

protected Color getSelectColor()

getDisabledTextColor

protected Color getDisabledTextColor()

getFocusColor

protected Color getFocusColor()

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: BasicRadioButtonUI
paint the radio button

Overrides:
paint in class BasicRadioButtonUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

paintFocus

protected void paintFocus(Graphics g,
                          Rectangle t,
                          Dimension d)
Overrides:
paintFocus in class BasicRadioButtonUI
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalRootPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalRootPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.RootPaneUI
            extended by  javax.swing.plaf.basic.BasicRootPaneUI
                extended by  javax.swing.plaf.metal.MetalRootPaneUI
All Implemented Interfaces:
PropertyChangeListener, EventListener
public class MetalRootPaneUI
extends BasicRootPaneUI

Provides the metal look and feel implementation of RootPaneUI.

MetalRootPaneUI provides support for the windowDecorationStyle property of JRootPane. MetalRootPaneUI does this by way of installing a custom LayoutManager, a private Component to render the appropriate widgets, and a private Border. The LayoutManager is always installed, regardless of the value of the windowDecorationStyle property, but the Border and Component are only installed/added if the windowDecorationStyle is other than JRootPane.NONE.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Since:
1.4

Constructor Summary
MetalRootPaneUI()
Method Summary
static ComponentUI | createUI(JComponent c) Creates a UI for a JRootPane.
void | installUI(JComponent c) Invokes supers implementation of installUI to install the necessary state onto the passed in JRootPane to render the metal look and feel implementation of RootPaneUI.
void | propertyChange(PropertyChangeEvent e) Invoked when a property changes.
void | uninstallUI(JComponent c) Invokes supers implementation to uninstall any of its state.
Methods inherited from class javax.swing.plaf.basic.BasicRootPaneUI
installComponents, installDefaults, installKeyboardActions, installListeners, uninstallComponents, uninstallDefaults, uninstallKeyboardActions, uninstallListeners
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, paint, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalRootPaneUI

public MetalRootPaneUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)
Creates a UI for a JRootPane.

Parameters:
c - the JRootPane the RootPaneUI will be created for
Returns:
the RootPaneUI implementation for the passed in JRootPane

installUI

public void installUI(JComponent c)
Invokes supers implementation of installUI to install the necessary state onto the passed in JRootPane to render the metal look and feel implementation of RootPaneUI. If the windowDecorationStyle property of the JRootPane is other than JRootPane.NONE, this will add a custom Component to render the widgets to JRootPane, as well as installing a custom Border and LayoutManager on the JRootPane.

Overrides:
installUI in class BasicRootPaneUI
Parameters:
c - the JRootPane to install state onto
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Invokes supers implementation to uninstall any of its state. This will also reset the LayoutManager of the JRootPane. If a Component has been added to the JRootPane to render the window decoration style, this method will remove it. Similarly, this will revert the Border and LayoutManager of the JRootPane to what it was before installUI was invoked.

Overrides:
uninstallUI in class BasicRootPaneUI
Parameters:
c - the JRootPane to uninstall state from
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

propertyChange

public void propertyChange(PropertyChangeEvent e)
Invoked when a property changes. MetalRootPaneUI is primarily interested in events originating from the JRootPane it has been installed on identifying the property windowDecorationStyle. If the windowDecorationStyle has changed to a value other than JRootPane.NONE, this will add a Component to the JRootPane to render the window decorations, as well as installing a Border on the JRootPane. On the other hand, if the windowDecorationStyle has changed to JRootPane.NONE, this will remove the Component that has been added to the JRootPane as well resetting the Border to what it was before installUI was invoked.

Specified by:
propertyChange in interface PropertyChangeListener
Overrides:
propertyChange in class BasicRootPaneUI
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalScrollBarUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalScrollBarUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ScrollBarUI
            extended by  javax.swing.plaf.basic.BasicScrollBarUI
                extended by  javax.swing.plaf.metal.MetalScrollBarUI
All Implemented Interfaces:
LayoutManager, SwingConstants
public class MetalScrollBarUI
extends BasicScrollBarUI

Implementation of ScrollBarUI for the Metal Look and Feel

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicScrollBarUI
BasicScrollBarUI.ArrowButtonListener, BasicScrollBarUI.ModelListener, BasicScrollBarUI.PropertyChangeHandler, BasicScrollBarUI.ScrollListener, BasicScrollBarUI.TrackListener
Field Summary
protected javax.swing.plaf.metal.MetalBumps | bumps
protected MetalScrollButton | decreaseButton
static String | FREE_STANDING_PROP
protected MetalScrollButton | increaseButton
protected boolean | isFreeStanding
protected int | scrollBarWidth
Fields inherited from class javax.swing.plaf.basic.BasicScrollBarUI
buttonListener, decrButton, DECREASE_HIGHLIGHT, incrButton, INCREASE_HIGHLIGHT, isDragging, maximumThumbSize, minimumThumbSize, modelListener, NO_HIGHLIGHT, propertyChangeListener, scrollbar, scrollListener, scrollTimer, thumbDarkShadowColor, thumbLightShadowColor, thumbRect, trackColor, trackHighlight, trackHighlightColor, trackListener, trackRect
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
MetalScrollBarUI()
Method Summary
protected void | configureScrollBarColors()
protected JButton | createDecreaseButton(int orientation) Returns the view that represents the decrease view.
protected JButton | createIncreaseButton(int orientation) Returns the view that represents the increase view.
protected PropertyChangeListener | createPropertyChangeListener()
static ComponentUI | createUI(JComponent c)
protected Dimension | getMinimumThumbSize() Return the smallest acceptable size for the thumb.
Dimension | getPreferredSize(JComponent c) A vertical scrollbar's preferred width is the maximum of preferred widths of the (non null) increment/decrement buttons, and the minimum width of the thumb.
protected void | installDefaults()
protected void | installListeners()
protected void | paintThumb(Graphics g, JComponent c, Rectangle thumbBounds)
protected void | paintTrack(Graphics g, JComponent c, Rectangle trackBounds)
protected void | setThumbBounds(int x, int y, int width, int height) This is overridden only to increase the invalid area.
Methods inherited from class javax.swing.plaf.basic.BasicScrollBarUI
addLayoutComponent, createArrowButtonListener, createModelListener, createScrollListener, createTrackListener, getMaximumSize, getMaximumThumbSize, getSupportsAbsolutePositioning, getThumbBounds, getTrackBounds, installComponents, installKeyboardActions, installUI, isThumbRollover, layoutContainer, layoutHScrollbar, layoutVScrollbar, minimumLayoutSize, paint, paintDecreaseHighlight, paintIncreaseHighlight, preferredLayoutSize, removeLayoutComponent, scrollByBlock, scrollByUnit, setThumbRollover, uninstallComponents, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMinimumSize, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

bumps

protected javax.swing.plaf.metal.MetalBumps bumps

increaseButton

protected MetalScrollButton increaseButton

decreaseButton

protected MetalScrollButton decreaseButton

scrollBarWidth

protected int scrollBarWidth

FREE_STANDING_PROP

public static final String FREE_STANDING_PROP
See Also:
Constant Field Values

isFreeStanding

protected boolean isFreeStanding
Constructor Detail

MetalScrollBarUI

public MetalScrollBarUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installDefaults

protected void installDefaults()
Overrides:
installDefaults in class BasicScrollBarUI

installListeners

protected void installListeners()
Overrides:
installListeners in class BasicScrollBarUI

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener()
Overrides:
createPropertyChangeListener in class BasicScrollBarUI

configureScrollBarColors

protected void configureScrollBarColors()
Overrides:
configureScrollBarColors in class BasicScrollBarUI

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Description copied from class: BasicScrollBarUI
A vertical scrollbar's preferred width is the maximum of preferred widths of the (non null) increment/decrement buttons, and the minimum width of the thumb. The preferred height is the sum of the preferred heights of the same parts. The basis for the preferred size of a horizontal scrollbar is similar.

The preferredSize is only computed once, subsequent calls to this method just return a cached size.

Overrides:
getPreferredSize in class BasicScrollBarUI
Parameters:
c - the JScrollBar that's delegating this method to us
Returns:
the preferred size of a Basic JScrollBar
See Also:
BasicScrollBarUI.getMaximumSize(javax.swing.JComponent), ComponentUI.getMinimumSize(javax.swing.JComponent)

createDecreaseButton

protected JButton createDecreaseButton(int orientation)
Returns the view that represents the decrease view.

Overrides:
createDecreaseButton in class BasicScrollBarUI

createIncreaseButton

protected JButton createIncreaseButton(int orientation)
Returns the view that represents the increase view.

Overrides:
createIncreaseButton in class BasicScrollBarUI

paintTrack

protected void paintTrack(Graphics g,
                          JComponent c,
                          Rectangle trackBounds)
Overrides:
paintTrack in class BasicScrollBarUI

paintThumb

protected void paintThumb(Graphics g,
                          JComponent c,
                          Rectangle thumbBounds)
Overrides:
paintThumb in class BasicScrollBarUI

getMinimumThumbSize

protected Dimension getMinimumThumbSize()
Description copied from class: BasicScrollBarUI
Return the smallest acceptable size for the thumb. If the scrollbar becomes so small that this size isn't available, the thumb will be hidden.

Warning : the value returned by this method should not be be modified, it's a shared static constant.

Overrides:
getMinimumThumbSize in class BasicScrollBarUI
Returns:
The smallest acceptable size for the thumb.
See Also:
BasicScrollBarUI.getMaximumThumbSize()

setThumbBounds

protected void setThumbBounds(int x,
                              int y,
                              int width,
                              int height)
This is overridden only to increase the invalid area. This ensures that the "Shadow" below the thumb is invalidated

Overrides:
setThumbBounds in class BasicScrollBarUI
See Also:
BasicScrollBarUI.getThumbBounds()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalScrollButton

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalScrollButton

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.AbstractButton
                    extended by  javax.swing.JButton
                        extended by  javax.swing.plaf.basic.BasicArrowButton
                            extended by  javax.swing.plaf.metal.MetalScrollButton
All Implemented Interfaces:
ImageObserver, ItemSelectable, MenuContainer, Serializable, Accessible, SwingConstants
public class MetalScrollButton
extends BasicArrowButton

JButton object for Metal scrollbar arrows.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JButton
JButton.AccessibleJButton
Nested classes/interfaces inherited from class javax.swing.AbstractButton
AbstractButton.AccessibleAbstractButton, AbstractButton.ButtonChangeListener
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicArrowButton
direction
Fields inherited from class javax.swing.AbstractButton
actionListener, BORDER_PAINTED_CHANGED_PROPERTY, changeEvent, changeListener, CONTENT_AREA_FILLED_CHANGED_PROPERTY, DISABLED_ICON_CHANGED_PROPERTY, DISABLED_SELECTED_ICON_CHANGED_PROPERTY, FOCUS_PAINTED_CHANGED_PROPERTY, HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY, HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY, ICON_CHANGED_PROPERTY, itemListener, MARGIN_CHANGED_PROPERTY, MNEMONIC_CHANGED_PROPERTY, model, MODEL_CHANGED_PROPERTY, PRESSED_ICON_CHANGED_PROPERTY, ROLLOVER_ENABLED_CHANGED_PROPERTY, ROLLOVER_ICON_CHANGED_PROPERTY, ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY, SELECTED_ICON_CHANGED_PROPERTY, TEXT_CHANGED_PROPERTY, VERTICAL_ALIGNMENT_CHANGED_PROPERTY, VERTICAL_TEXT_POSITION_CHANGED_PROPERTY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
MetalScrollButton(int direction, int width, boolean freeStanding)
Method Summary
int | getButtonWidth()
Dimension | getMaximumSize() Returns the maximum size of the BasicArrowButton.
Dimension | getMinimumSize() Returns the minimum size of the BasicArrowButton.
Dimension | getPreferredSize() Returns the preferred size of the BasicArrowButton.
void | paint(Graphics g) Invoked by Swing to draw components.
void | setFreeStanding(boolean freeStanding)
Methods inherited from class javax.swing.plaf.basic.BasicArrowButton
getDirection, isFocusTraversable, paintTriangle, setDirection
Methods inherited from class javax.swing.JButton
getAccessibleContext, getUIClassID, isDefaultButton, isDefaultCapable, paramString, removeNotify, setDefaultCapable, updateUI
Methods inherited from class javax.swing.AbstractButton
actionPropertyChanged, addActionListener, addChangeListener, addImpl, addItemListener, checkHorizontalKey, checkVerticalKey, configurePropertiesFromAction, createActionListener, createActionPropertyChangeListener, createChangeListener, createItemListener, doClick, doClick, fireActionPerformed, fireItemStateChanged, fireStateChanged, getAction, getActionCommand, getActionListeners, getChangeListeners, getDisabledIcon, getDisabledSelectedIcon, getDisplayedMnemonicIndex, getHideActionText, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getItemListeners, getLabel, getMargin, getMnemonic, getModel, getMultiClickThreshhold, getPressedIcon, getRolloverIcon, getRolloverSelectedIcon, getSelectedIcon, getSelectedObjects, getText, getUI, getVerticalAlignment, getVerticalTextPosition, imageUpdate, init, isBorderPainted, isContentAreaFilled, isFocusPainted, isRolloverEnabled, isSelected, paintBorder, removeActionListener, removeChangeListener, removeItemListener, setAction, setActionCommand, setBorderPainted, setContentAreaFilled, setDisabledIcon, setDisabledSelectedIcon, setDisplayedMnemonicIndex, setEnabled, setFocusPainted, setHideActionText, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabel, setLayout, setMargin, setMnemonic, setMnemonic, setModel, setMultiClickThreshhold, setPressedIcon, setRolloverEnabled, setRolloverIcon, setRolloverSelectedIcon, setSelected, setSelectedIcon, setText, setUI, setVerticalAlignment, setVerticalTextPosition
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MetalScrollButton

public MetalScrollButton(int direction,
                         int width,
                         boolean freeStanding)
Method Detail

setFreeStanding

public void setFreeStanding(boolean freeStanding)

paint

public void paint(Graphics g)
Description copied from class: JComponent
Invoked by Swing to draw components. Applications should not invoke paint directly, but should instead use the repaint method to schedule the component for redrawing.

This method actually delegates the work of painting to three protected methods: paintComponent, paintBorder, and paintChildren. They're called in the order listed to ensure that children appear on top of component itself. Generally speaking, the component and its children should not paint in the insets area allocated to the border. Subclasses can just override this method, as always. A subclass that just wants to specialize the UI (look and feel) delegate's paint method should just override paintComponent.

Overrides:
paint in class BasicArrowButton
Parameters:
g - the Graphics context in which to paint
See Also:
JComponent.paintComponent(java.awt.Graphics),
JComponent.paintBorder(java.awt.Graphics),
JComponent.paintChildren(java.awt.Graphics),
JComponent.getComponentGraphics(java.awt.Graphics),
JComponent.repaint(long, int, int, int, int)

getPreferredSize

public Dimension getPreferredSize()
Description copied from class: BasicArrowButton
Returns the preferred size of the BasicArrowButton.

Overrides:
getPreferredSize in class BasicArrowButton
Returns:
the preferred size
See Also:
JComponent.setPreferredSize(java.awt.Dimension), ComponentUI

getMinimumSize

public Dimension getMinimumSize()
Description copied from class: BasicArrowButton
Returns the minimum size of the BasicArrowButton.

Overrides:
getMinimumSize in class BasicArrowButton
Returns:
the minimum size
See Also:
JComponent.setMinimumSize(java.awt.Dimension), ComponentUI

getMaximumSize

public Dimension getMaximumSize()
Description copied from class: BasicArrowButton
Returns the maximum size of the BasicArrowButton.

Overrides:
getMaximumSize in class BasicArrowButton
Returns:
the maximum size
See Also:
JComponent.setMaximumSize(java.awt.Dimension), ComponentUI

getButtonWidth

public int getButtonWidth()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalScrollPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalScrollPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ScrollPaneUI
            extended by  javax.swing.plaf.basic.BasicScrollPaneUI
                extended by  javax.swing.plaf.metal.MetalScrollPaneUI
All Implemented Interfaces:
ScrollPaneConstants
public class MetalScrollPaneUI
extends BasicScrollPaneUI

A Metal L&F implementation of ScrollPaneUI.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicScrollPaneUI
BasicScrollPaneUI.HSBChangeListener, BasicScrollPaneUI.MouseWheelHandler, BasicScrollPaneUI.PropertyChangeHandler, BasicScrollPaneUI.ViewportChangeHandler, BasicScrollPaneUI.VSBChangeListener
Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicScrollPaneUI
hsbChangeListener, scrollpane, spPropertyChangeListener, viewportChangeListener, vsbChangeListener
Fields inherited from interface javax.swing.ScrollPaneConstants
COLUMN_HEADER, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_ALWAYS, HORIZONTAL_SCROLLBAR_AS_NEEDED, HORIZONTAL_SCROLLBAR_NEVER, HORIZONTAL_SCROLLBAR_POLICY, LOWER_LEADING_CORNER, LOWER_LEFT_CORNER, LOWER_RIGHT_CORNER, LOWER_TRAILING_CORNER, ROW_HEADER, UPPER_LEADING_CORNER, UPPER_LEFT_CORNER, UPPER_RIGHT_CORNER, UPPER_TRAILING_CORNER, VERTICAL_SCROLLBAR, VERTICAL_SCROLLBAR_ALWAYS, VERTICAL_SCROLLBAR_AS_NEEDED, VERTICAL_SCROLLBAR_NEVER, VERTICAL_SCROLLBAR_POLICY, VIEWPORT
Constructor Summary
MetalScrollPaneUI()
Method Summary
protected PropertyChangeListener | createScrollBarSwapListener()
static ComponentUI | createUI(JComponent x)
void | installListeners(JScrollPane scrollPane)
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
void | uninstallListeners(JScrollPane scrollPane)
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.basic.BasicScrollPaneUI
createHSBChangeListener, createMouseWheelListener, createPropertyChangeListener, createViewportChangeListener, createVSBChangeListener, getBaseline, getBaselineResizeBehavior, getMaximumSize, installDefaults, installKeyboardActions, paint, syncScrollPaneWithViewport, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, updateColumnHeader, updateRowHeader, updateScrollBarDisplayPolicy, updateViewport
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getMinimumSize, getPreferredSize, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalScrollPaneUI

public MetalScrollPaneUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent x)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class BasicScrollPaneUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class BasicScrollPaneUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installListeners

public void installListeners(JScrollPane scrollPane)
Overrides:
installListeners in class BasicScrollPaneUI

uninstallListeners

public void uninstallListeners(JScrollPane scrollPane)

createScrollBarSwapListener

protected PropertyChangeListener createScrollBarSwapListener()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalSeparatorUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalSeparatorUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SeparatorUI
            extended by  javax.swing.plaf.basic.BasicSeparatorUI
                extended by  javax.swing.plaf.metal.MetalSeparatorUI
Direct Known Subclasses:
MetalPopupMenuSeparatorUI
public class MetalSeparatorUI
extends BasicSeparatorUI

A Metal L&F implementation of SeparatorUI. This implementation is a "combined" view/controller.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicSeparatorUI
highlight, shadow
Constructor Summary
MetalSeparatorUI()
Method Summary
static ComponentUI | createUI(JComponent c)
Dimension | getPreferredSize(JComponent c) Returns the specified component's preferred size appropriate for the look and feel.
protected void | installDefaults(JSeparator s)
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
Methods inherited from class javax.swing.plaf.basic.BasicSeparatorUI
getMaximumSize, getMinimumSize, installListeners, installUI, uninstallDefaults, uninstallListeners, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalSeparatorUI

public MetalSeparatorUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installDefaults

protected void installDefaults(JSeparator s)
Overrides:
installDefaults in class BasicSeparatorUI

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class BasicSeparatorUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Overrides:
getPreferredSize in class BasicSeparatorUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalSliderUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalSliderUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SliderUI
            extended by  javax.swing.plaf.basic.BasicSliderUI
                extended by  javax.swing.plaf.metal.MetalSliderUI

public class MetalSliderUI
extends BasicSliderUI

A Java L&F implementation of SliderUI.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class MetalSliderUI.MetalPropertyListener
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicSliderUI
BasicSliderUI.ActionScroller, BasicSliderUI.ChangeHandler, BasicSliderUI.ComponentHandler, BasicSliderUI.FocusHandler, BasicSliderUI.PropertyChangeHandler, BasicSliderUI.ScrollListener, BasicSliderUI.TrackListener
Field Summary
protected static Color | darkShadowColor
protected boolean | filledSlider
protected static Color | highlightColor
protected static Icon | horizThumbIcon A default horizontal thumb Icon.
protected String | SLIDER_FILL
protected static Color | thumbColor
protected int | TICK_BUFFER
protected static int | tickLength
protected static int | trackWidth
protected static Icon | vertThumbIcon A default vertical thumb Icon.
Fields inherited from class javax.swing.plaf.basic.BasicSliderUI
changeListener, componentListener, contentRect, focusInsets, focusListener, focusRect, insetCache, labelRect, leftToRightCache, MAX_SCROLL, MIN_SCROLL, NEGATIVE_SCROLL, POSITIVE_SCROLL, propertyChangeListener, scrollListener, scrollTimer, slider, thumbRect, tickRect, trackBuffer, trackListener, trackRect
Constructor Summary
MetalSliderUI()
Method Summary
protected PropertyChangeListener | createPropertyChangeListener(JSlider slider)
static ComponentUI | createUI(JComponent c)
protected int | getThumbOverhang() Returns the amount that the thumb goes past the slide bar.
protected Dimension | getThumbSize()
int | getTickLength() Gets the height of the tick area for horizontal sliders and the width of the tick area for vertical sliders.
protected int | getTrackLength() Returns the longer dimension of the slide bar.
protected int | getTrackWidth() Returns the shorter dimension of the track.
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
void | paintFocus(Graphics g)
protected void | paintMajorTickForHorizSlider(Graphics g, Rectangle tickBounds, int x)
protected void | paintMajorTickForVertSlider(Graphics g, Rectangle tickBounds, int y)
protected void | paintMinorTickForHorizSlider(Graphics g, Rectangle tickBounds, int x)
protected void | paintMinorTickForVertSlider(Graphics g, Rectangle tickBounds, int y)
void | paintThumb(Graphics g)
void | paintTrack(Graphics g)
protected void | scrollDueToClickInTrack(int dir) This function is called when a mousePressed was detected in the track, not in the thumb.
Methods inherited from class javax.swing.plaf.basic.BasicSliderUI
calculateContentRect, calculateFocusRect, calculateGeometry, calculateLabelRect, calculateThumbLocation, calculateThumbSize, calculateTickRect, calculateTrackBuffer, calculateTrackRect, createChangeListener, createComponentListener, createFocusListener, createScrollListener, createTrackListener, drawInverted, getBaseline, getBaselineResizeBehavior, getFocusColor, getHeightOfHighValueLabel, getHeightOfLowValueLabel, getHeightOfTallestLabel, getHighestValue, getHighestValueLabel, getHighlightColor, getLowestValue, getLowestValueLabel, getMaximumSize, getMinimumHorizontalSize, getMinimumSize, getMinimumVerticalSize, getPreferredHorizontalSize, getPreferredSize, getPreferredVerticalSize, getShadowColor, getWidthOfHighValueLabel, getWidthOfLowValueLabel, getWidthOfWidestLabel, installDefaults, installKeyboardActions, installListeners, isDragging, labelsHaveSameBaselines, paint, paintHorizontalLabel, paintLabels, paintTicks, paintVerticalLabel, recalculateIfInsetsChanged, recalculateIfOrientationChanged, scrollByBlock, scrollByUnit, setThumbLocation, uninstallKeyboardActions, uninstallListeners, uninstallUI, valueForXPosition, valueForYPosition, xPositionForValue, yPositionForValue, yPositionForValue
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TICK_BUFFER

protected final int TICK_BUFFER
See Also:
Constant Field Values

filledSlider

protected boolean filledSlider

thumbColor

protected static Color thumbColor

highlightColor

protected static Color highlightColor

darkShadowColor

protected static Color darkShadowColor

trackWidth

protected static int trackWidth

tickLength

protected static int tickLength

horizThumbIcon

protected static Icon horizThumbIcon
A default horizontal thumb Icon. This field might not be used. To change the Icon used by this delgate directly set it using the Slider.horizontalThumbIcon UIManager property.

vertThumbIcon

protected static Icon vertThumbIcon
A default vertical thumb Icon. This field might not be used. To change the Icon used by this delgate directly set it using the Slider.verticalThumbIcon UIManager property.

SLIDER_FILL

protected final String SLIDER_FILL
See Also:
Constant Field Values
Constructor Detail

MetalSliderUI

public MetalSliderUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class BasicSliderUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

createPropertyChangeListener

protected PropertyChangeListener createPropertyChangeListener(JSlider slider)
Overrides:
createPropertyChangeListener in class BasicSliderUI

paintThumb

public void paintThumb(Graphics g)
Overrides:
paintThumb in class BasicSliderUI

paintTrack

public void paintTrack(Graphics g)
Overrides:
paintTrack in class BasicSliderUI

paintFocus

public void paintFocus(Graphics g)
Overrides:
paintFocus in class BasicSliderUI

getThumbSize

protected Dimension getThumbSize()
Overrides:
getThumbSize in class BasicSliderUI

getTickLength

public int getTickLength()
Gets the height of the tick area for horizontal sliders and the width of the tick area for vertical sliders. BasicSliderUI uses the returned value to determine the tick area rectangle.

Overrides:
getTickLength in class BasicSliderUI

getTrackWidth

protected int getTrackWidth()
Returns the shorter dimension of the track.

getTrackLength

protected int getTrackLength()
Returns the longer dimension of the slide bar. (The slide bar is only the part that runs directly under the thumb)

getThumbOverhang

protected int getThumbOverhang()
Returns the amount that the thumb goes past the slide bar.

scrollDueToClickInTrack

protected void scrollDueToClickInTrack(int dir)
Description copied from class: BasicSliderUI
This function is called when a mousePressed was detected in the track, not in the thumb. The default behavior is to scroll by block. You can override this method to stop it from scrolling or to add additional behavior.

Overrides:
scrollDueToClickInTrack in class BasicSliderUI

paintMinorTickForHorizSlider

protected void paintMinorTickForHorizSlider(Graphics g,
                                            Rectangle tickBounds,
                                            int x)
Overrides:
paintMinorTickForHorizSlider in class BasicSliderUI

paintMajorTickForHorizSlider

protected void paintMajorTickForHorizSlider(Graphics g,
                                            Rectangle tickBounds,
                                            int x)
Overrides:
paintMajorTickForHorizSlider in class BasicSliderUI

paintMinorTickForVertSlider

protected void paintMinorTickForVertSlider(Graphics g,
                                           Rectangle tickBounds,
                                           int y)
Overrides:
paintMinorTickForVertSlider in class BasicSliderUI

paintMajorTickForVertSlider

protected void paintMajorTickForVertSlider(Graphics g,
                                           Rectangle tickBounds,
                                           int y)
Overrides:
paintMajorTickForVertSlider in class BasicSliderUI
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalSliderUI.MetalPropertyListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalSliderUI.MetalPropertyListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicSliderUI.PropertyChangeHandler
        extended by  javax.swing.plaf.metal.MetalSliderUI.MetalPropertyListener
All Implemented Interfaces:
PropertyChangeListener, EventListener
Enclosing class:
MetalSliderUI
protected class MetalSliderUI.MetalPropertyListener
extends BasicSliderUI.PropertyChangeHandler

Constructor Summary
protected MetalSliderUI.MetalPropertyListener()
Method Summary
 void propertyChange(PropertyChangeEvent e)
This method gets called when a bound property is changed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalSliderUI.MetalPropertyListener

protected MetalSliderUI.MetalPropertyListener()
Method Detail

propertyChange

public void propertyChange(PropertyChangeEvent e)
Description copied from interface: PropertyChangeListener
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Overrides:
propertyChange in class BasicSliderUI.PropertyChangeHandler
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalSplitPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalSplitPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SplitPaneUI
            extended by  javax.swing.plaf.basic.BasicSplitPaneUI
                extended by  javax.swing.plaf.metal.MetalSplitPaneUI

public class MetalSplitPaneUI
extends BasicSplitPaneUI

Metal split pane.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicSplitPaneUI
BasicSplitPaneUI.BasicHorizontalLayoutManager, BasicSplitPaneUI.BasicVerticalLayoutManager, BasicSplitPaneUI.FocusHandler, BasicSplitPaneUI.KeyboardDownRightHandler, BasicSplitPaneUI.KeyboardEndHandler, BasicSplitPaneUI.KeyboardHomeHandler, BasicSplitPaneUI.KeyboardResizeToggleHandler, BasicSplitPaneUI.KeyboardUpLeftHandler, BasicSplitPaneUI.PropertyHandler
Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicSplitPaneUI
beginDragDividerLocation, divider, dividerResizeToggleKey, dividerSize, downKey, draggingHW, endKey, focusListener, homeKey, KEYBOARD_DIVIDER_MOVE_OFFSET, keyboardDownRightListener, keyboardEndListener, keyboardHomeListener, keyboardResizeToggleListener, keyboardUpLeftListener, layoutManager, leftKey, NON_CONTINUOUS_DIVIDER, nonContinuousLayoutDivider, propertyChangeListener, rightKey, splitPane, upKey
Constructor Summary
MetalSplitPaneUI()
Method Summary
BasicSplitPaneDivider | createDefaultDivider() Creates the default divider.
static ComponentUI | createUI(JComponent x) Creates a new MetalSplitPaneUI instance
Methods inherited from class javax.swing.plaf.basic.BasicSplitPaneUI
createDefaultNonContinuousLayoutDivider, createFocusListener, createKeyboardDownRightListener, createKeyboardEndListener, createKeyboardHomeListener, createKeyboardResizeToggleListener, createKeyboardUpLeftListener, createPropertyChangeListener, dragDividerTo, finishDraggingTo, finishedPaintingChildren, getDivider, getDividerBorderSize, getDividerLocation, getInsets, getLastDragLocation, getMaximumDividerLocation, getMaximumSize, getMinimumDividerLocation, getMinimumSize, getNonContinuousLayoutDivider, getOrientation, getPreferredSize, getSplitPane, installDefaults, installKeyboardActions, installListeners, installUI, isContinuousLayout, paint, resetLayoutManager, resetToPreferredSizes, setContinuousLayout, setDividerLocation, setLastDragLocation, setNonContinuousLayoutDivider, setNonContinuousLayoutDivider, setOrientation, startDragging, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalSplitPaneUI

public MetalSplitPaneUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent x)
Creates a new MetalSplitPaneUI instance

createDefaultDivider

public BasicSplitPaneDivider createDefaultDivider()
Creates the default divider.

Overrides:
createDefaultDivider in class BasicSplitPaneUI
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalTabbedPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalTabbedPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TabbedPaneUI
            extended by  javax.swing.plaf.basic.BasicTabbedPaneUI
                extended by  javax.swing.plaf.metal.MetalTabbedPaneUI
All Implemented Interfaces:
SwingConstants
public class MetalTabbedPaneUI
extends BasicTabbedPaneUI

The Metal subclass of BasicTabbedPaneUI.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
 class MetalTabbedPaneUI.TabbedPaneLayout
This inner class is marked "public" due to a compiler bug.
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicTabbedPaneUI
BasicTabbedPaneUI.FocusHandler, BasicTabbedPaneUI.MouseHandler, BasicTabbedPaneUI.PropertyChangeHandler, BasicTabbedPaneUI.TabSelectionHandler
Field Summary
protected int | minTabWidth
protected Color | selectColor
protected Color | selectHighlight
protected Color | tabAreaBackground
Fields inherited from class javax.swing.plaf.basic.BasicTabbedPaneUI
calcRect, contentBorderInsets, darkShadow, downKey, focus, focusListener, highlight, leftKey, lightHighlight, maxTabHeight, maxTabWidth, mouseListener, propertyChangeListener, rects, rightKey, runCount, selectedRun, selectedTabPadInsets, shadow, tabAreaInsets, tabChangeListener, tabInsets, tabPane, tabRunOverlay, tabRuns, textIconGap, upKey
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
MetalTabbedPaneUI()
Method Summary
protected int | calculateMaxTabHeight(int tabPlacement)
protected LayoutManager | createLayoutManager() Invoked by installUI to create a layout manager object to manage the JTabbedPane.
static ComponentUI | createUI(JComponent x)
protected int | getBaselineOffset() Returns the amount the baseline is offset by.
protected Color | getColorForGap(int currentRun, int x, int y)
protected int | getTabLabelShiftX(int tabPlacement, int tabIndex, boolean isSelected) Overridden to do nothing for the Java L&F.
protected int | getTabLabelShiftY(int tabPlacement, int tabIndex, boolean isSelected) Overridden to do nothing for the Java L&F.
protected int | getTabRunOverlay(int tabPlacement)
protected void | installDefaults()
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
protected void | paintBottomTabBorder(int tabIndex, Graphics g, int x, int y, int w, int h, int btm, int rght, boolean isSelected)
protected void | paintContentBorderBottomEdge(Graphics g, int tabPlacement, int selectedIndex, int x, int y, int w, int h)
protected void | paintContentBorderLeftEdge(Graphics g, int tabPlacement, int selectedIndex, int x, int y, int w, int h)
protected void | paintContentBorderRightEdge(Graphics g, int tabPlacement, int selectedIndex, int x, int y, int w, int h)
protected void | paintContentBorderTopEdge(Graphics g, int tabPlacement, int selectedIndex, int x, int y, int w, int h)
protected void | paintFocusIndicator(Graphics g, int tabPlacement, Rectangle[] rects, int tabIndex, Rectangle iconRect, Rectangle textRect, boolean isSelected)
protected void | paintHighlightBelowTab()
protected void | paintLeftTabBorder(int tabIndex, Graphics g, int x, int y, int w, int h, int btm, int rght, boolean isSelected)
protected void | paintRightTabBorder(int tabIndex, Graphics g, int x, int y, int w, int h, int btm, int rght, boolean isSelected)
protected void | paintTabBackground(Graphics g, int tabPlacement, int tabIndex, int x, int y, int w, int h, boolean isSelected)
protected void | paintTabBorder(Graphics g, int tabPlacement, int tabIndex, int x, int y, int w, int h, boolean isSelected) this function draws the border around each tab note that this function does now draw the background of the tab.
protected void | paintTopTabBorder(int tabIndex, Graphics g, int x, int y, int w, int h, int btm, int rght, boolean isSelected)
protected boolean | shouldFillGap(int currentRun, int tabIndex, int x, int y)
protected boolean | shouldPadTabRun(int tabPlacement, int run)
protected boolean | shouldRotateTabRuns(int tabPlacement, int selectedRun)
void | update(Graphics g, JComponent c) Notifies this UI delegate that it's time to paint the specified component.
Methods inherited from class javax.swing.plaf.basic.BasicTabbedPaneUI
assureRectsCreated, calculateMaxTabWidth, calculateTabAreaHeight, calculateTabAreaWidth, calculateTabHeight, calculateTabWidth, createChangeListener, createFocusListener, createMouseListener, createPropertyChangeListener, createScrollButton, expandTabRunsArray, getBaseline, getBaseline, getBaselineResizeBehavior, getContentBorderInsets, getFocusIndex, getFontMetrics, getIconForTab, getMaximumSize, getMinimumSize, getNextTabIndex, getNextTabIndexInRun, getNextTabRun, getPreviousTabIndex, getPreviousTabIndexInRun, getPreviousTabRun, getRolloverTab, getRunForTab, getSelectedTabPadInsets, getTabAreaInsets, getTabBounds, getTabBounds, getTabInsets, getTabRunCount, getTabRunIndent, getTabRunOffset, getTextViewForTab, getVisibleComponent, installComponents, installKeyboardActions, installListeners, installUI, lastTabInRun, layoutLabel, navigateSelectedTab, paintContentBorder, paintIcon, paintTab, paintTabArea, paintText, rotateInsets, selectAdjacentRunTab, selectNextTab, selectNextTabInRun, selectPreviousTab, selectPreviousTabInRun, setRolloverTab, setVisibleComponent, shouldRotateTabRuns, tabForCoordinate, uninstallComponents, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getPreferredSize
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

minTabWidth

protected int minTabWidth

tabAreaBackground

protected Color tabAreaBackground

selectColor

protected Color selectColor

selectHighlight

protected Color selectHighlight
Constructor Detail

MetalTabbedPaneUI

public MetalTabbedPaneUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent x)

createLayoutManager

protected LayoutManager createLayoutManager()
Description copied from class: BasicTabbedPaneUI
Invoked by installUI to create a layout manager object to manage the JTabbedPane.

Overrides:
createLayoutManager in class BasicTabbedPaneUI
Returns:
a layout manager object
See Also:
BasicTabbedPaneUI.TabbedPaneLayout, JTabbedPane.getTabLayoutPolicy()

installDefaults

protected void installDefaults()
Overrides:
installDefaults in class BasicTabbedPaneUI

paintTabBorder

protected void paintTabBorder(Graphics g,
                              int tabPlacement,
                              int tabIndex,
                              int x,
                              int y,
                              int w,
                              int h,
                              boolean isSelected)
Description copied from class: BasicTabbedPaneUI
this function draws the border around each tab note that this function does now draw the background of the tab. that is done elsewhere

Overrides:
paintTabBorder in class BasicTabbedPaneUI

paintTopTabBorder

protected void paintTopTabBorder(int tabIndex,
                                 Graphics g,
                                 int x,
                                 int y,
                                 int w,
                                 int h,
                                 int btm,
                                 int rght,
                                 boolean isSelected)

shouldFillGap

protected boolean shouldFillGap(int currentRun,
                                int tabIndex,
                                int x,
                                int y)

getColorForGap

protected Color getColorForGap(int currentRun,
                               int x,
                               int y)

paintLeftTabBorder

protected void paintLeftTabBorder(int tabIndex,
                                  Graphics g,
                                  int x,
                                  int y,
                                  int w,
                                  int h,
                                  int btm,
                                  int rght,
                                  boolean isSelected)

paintBottomTabBorder

protected void paintBottomTabBorder(int tabIndex,
                                    Graphics g,
                                    int x,
                                    int y,
                                    int w,
                                    int h,
                                    int btm,
                                    int rght,
                                    boolean isSelected)

paintRightTabBorder

protected void paintRightTabBorder(int tabIndex,
                                   Graphics g,
                                   int x,
                                   int y,
                                   int w,
                                   int h,
                                   int btm,
                                   int rght,
                                   boolean isSelected)

update

public void update(Graphics g,
                   JComponent c)
Description copied from class: ComponentUI
Notifies this UI delegate that it's time to paint the specified component. This method is invoked by JComponent when the specified component is being painted. By default this method will fill the specified component with its background color (if its opaque property is true) and then immediately call paint. In general this method need not be overridden by subclasses; all look-and-feel rendering code should reside in the paint method.

Overrides:
update in class ComponentUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

paintTabBackground

protected void paintTabBackground(Graphics g,
                                  int tabPlacement,
                                  int tabIndex,
                                  int x,
                                  int y,
                                  int w,
                                  int h,
                                  boolean isSelected)
Overrides:
paintTabBackground in class BasicTabbedPaneUI

getTabLabelShiftX

protected int getTabLabelShiftX(int tabPlacement,
                                int tabIndex,
                                boolean isSelected)
Overridden to do nothing for the Java L&F.

Overrides:
getTabLabelShiftX in class BasicTabbedPaneUI

getTabLabelShiftY

protected int getTabLabelShiftY(int tabPlacement,
                                int tabIndex,
                                boolean isSelected)
Overridden to do nothing for the Java L&F.

Overrides:
getTabLabelShiftY in class BasicTabbedPaneUI

getBaselineOffset

protected int getBaselineOffset()
Returns the amount the baseline is offset by. This is typically the same as getTabLabelShiftY.

Overrides:
getBaselineOffset in class BasicTabbedPaneUI
Returns:
amount to offset the baseline by
Since:
1.6

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class BasicTabbedPaneUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

paintHighlightBelowTab

protected void paintHighlightBelowTab()

paintFocusIndicator

protected void paintFocusIndicator(Graphics g,
                                   int tabPlacement,
                                   Rectangle[] rects,
                                   int tabIndex,
                                   Rectangle iconRect,
                                   Rectangle textRect,
                                   boolean isSelected)
Overrides:
paintFocusIndicator in class BasicTabbedPaneUI

paintContentBorderTopEdge

protected void paintContentBorderTopEdge(Graphics g,
                                         int tabPlacement,
                                         int selectedIndex,
                                         int x,
                                         int y,
                                         int w,
                                         int h)
Overrides:
paintContentBorderTopEdge in class BasicTabbedPaneUI

paintContentBorderBottomEdge

protected void paintContentBorderBottomEdge(Graphics g,
                                            int tabPlacement,
                                            int selectedIndex,
                                            int x,
                                            int y,
                                            int w,
                                            int h)
Overrides:
paintContentBorderBottomEdge in class BasicTabbedPaneUI

paintContentBorderLeftEdge

protected void paintContentBorderLeftEdge(Graphics g,
                                          int tabPlacement,
                                          int selectedIndex,
                                          int x,
                                          int y,
                                          int w,
                                          int h)
Overrides:
paintContentBorderLeftEdge in class BasicTabbedPaneUI

paintContentBorderRightEdge

protected void paintContentBorderRightEdge(Graphics g,
                                           int tabPlacement,
                                           int selectedIndex,
                                           int x,
                                           int y,
                                           int w,
                                           int h)
Overrides:
paintContentBorderRightEdge in class BasicTabbedPaneUI

calculateMaxTabHeight

protected int calculateMaxTabHeight(int tabPlacement)
Overrides:
calculateMaxTabHeight in class BasicTabbedPaneUI

getTabRunOverlay

protected int getTabRunOverlay(int tabPlacement)
Overrides:
getTabRunOverlay in class BasicTabbedPaneUI

shouldRotateTabRuns

protected boolean shouldRotateTabRuns(int tabPlacement,
                                      int selectedRun)

shouldPadTabRun

protected boolean shouldPadTabRun(int tabPlacement,
                                  int run)
Overrides:
shouldPadTabRun in class BasicTabbedPaneUI
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalTabbedPaneUI.TabbedPaneLayout

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalTabbedPaneUI.TabbedPaneLayout

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicTabbedPaneUI.TabbedPaneLayout
        extended by  javax.swing.plaf.metal.MetalTabbedPaneUI.TabbedPaneLayout
All Implemented Interfaces:
LayoutManager
Enclosing class:
MetalTabbedPaneUI
public class MetalTabbedPaneUI.TabbedPaneLayout
extends BasicTabbedPaneUI.TabbedPaneLayout

This inner class is marked "public" due to a compiler bug. This class should be treated as a "protected" inner class. Instantiate it only within subclasses of MetalTabbedPaneUI.

Constructor Summary
MetalTabbedPaneUI.TabbedPaneLayout()
Method Summary
protected void | normalizeTabRuns(int tabPlacement, int tabCount, int start, int max)
protected void | padSelectedTab(int tabPlacement, int selectedIndex)
protected void | rotateTabRuns(int tabPlacement, int selectedRun)
Methods inherited from class javax.swing.plaf.basic.BasicTabbedPaneUI.TabbedPaneLayout
addLayoutComponent, calculateLayoutInfo, calculateSize, calculateTabRects, layoutContainer, minimumLayoutSize, padTabRun, preferredLayoutSize, preferredTabAreaHeight, preferredTabAreaWidth, removeLayoutComponent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalTabbedPaneUI.TabbedPaneLayout

public MetalTabbedPaneUI.TabbedPaneLayout()
Method Detail

normalizeTabRuns

protected void normalizeTabRuns(int tabPlacement,
                                int tabCount,
                                int start,
                                int max)
Overrides:
normalizeTabRuns in class BasicTabbedPaneUI.TabbedPaneLayout

rotateTabRuns

protected void rotateTabRuns(int tabPlacement,
                             int selectedRun)
Overrides:
rotateTabRuns in class BasicTabbedPaneUI.TabbedPaneLayout

padSelectedTab

protected void padSelectedTab(int tabPlacement,
                              int selectedIndex)
Overrides:
padSelectedTab in class BasicTabbedPaneUI.TabbedPaneLayout
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalTextFieldUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalTextFieldUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TextUI
            extended by  javax.swing.plaf.basic.BasicTextUI
                extended by  javax.swing.plaf.basic.BasicTextFieldUI
                    extended by  javax.swing.plaf.metal.MetalTextFieldUI
All Implemented Interfaces:
ViewFactory
public class MetalTextFieldUI
extends BasicTextFieldUI

Basis of a look and feel for a JTextField.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicTextUI
BasicTextUI.BasicCaret, BasicTextUI.BasicHighlighter
Constructor Summary
MetalTextFieldUI()
Method Summary
static ComponentUI | createUI(JComponent c)
void | propertyChange(PropertyChangeEvent evt) This method gets called when a bound property is changed on the associated JTextComponent.
Methods inherited from class javax.swing.plaf.basic.BasicTextFieldUI
create, getBaseline, getBaselineResizeBehavior, getPropertyPrefix
Methods inherited from class javax.swing.plaf.basic.BasicTextUI
create, createCaret, createHighlighter, createKeymap, damageRange, damageRange, getComponent, getEditorKit, getKeymapName, getMaximumSize, getMinimumSize, getNextVisualPositionFrom, getPreferredSize, getRootView, getToolTipText, getVisibleEditorRect, installDefaults, installKeyboardActions, installListeners, installUI, modelChanged, modelToView, modelToView, paint, paintBackground, paintSafely, setView, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, uninstallUI, update, viewToModel, viewToModel
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalTextFieldUI

public MetalTextFieldUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

propertyChange

public void propertyChange(PropertyChangeEvent evt)
This method gets called when a bound property is changed on the associated JTextComponent. This is a hook which UI implementations may change to reflect how the UI displays bound properties of JTextComponent subclasses.

Overrides:
propertyChange in class BasicTextUI
Parameters:
evt - the property change event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalTheme

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalTheme

java.lang.Object
    extended by  javax.swing.plaf.metal.MetalTheme
Direct Known Subclasses:
DefaultMetalTheme
public abstract class MetalTheme
extends Object

MetalTheme provides the color palette and fonts used by the Java Look and Feel.

MetalTheme is abstract, see DefaultMetalTheme and OceanTheme for concrete implementations.

MetalLookAndFeel maintains the current theme that the the ComponentUI implementations for metal use. Refer to MetalLookAndFeel.setCurrentTheme(MetalTheme) for details on changing the current theme.

MetalTheme provides a number of public methods for getting colors. These methods are implemented in terms of a handful of protected abstract methods. A subclass need only override the protected abstract methods (getPrimary1, getPrimary2, getPrimary3, getSecondary1, getSecondary2, and getSecondary3); although a subclass may override the other public methods for more control over the set of colors that are used.

Concrete implementations of MetalTheme must return non-null values from all methods. While the behavior of returning null is not specified, returning null will result in incorrect behavior.

It is strongly recommended that subclasses return completely opaque colors. To do otherwise may result in rendering problems, such as visual garbage.

See Also:
DefaultMetalTheme, OceanTheme, MetalLookAndFeel.setCurrentTheme(javax.swing.plaf.metal.MetalTheme)

Constructor Summary
MetalTheme()
Method Summary
void | addCustomEntriesToTable(UIDefaults table) Adds values specific to this theme to the defaults table.
ColorUIResource | getAcceleratorForeground() Returns the accelerator foreground color.
ColorUIResource | getAcceleratorSelectedForeground() Returns the accelerator selected foreground color.
protected ColorUIResource | getBlack() Returns the black color.
ColorUIResource | getControl() Returns the control color.
ColorUIResource | getControlDarkShadow() Returns the control dark shadow color.
ColorUIResource | getControlDisabled() Returns the control disabled color.
ColorUIResource | getControlHighlight() Returns the control highlight color.
ColorUIResource | getControlInfo() Returns the control info color.
ColorUIResource | getControlShadow() Returns the control shadow color.
ColorUIResource | getControlTextColor() Returns the control text color.
abstract FontUIResource | getControlTextFont() Returns the control text font.
ColorUIResource | getDesktopColor() Returns the desktop color.
ColorUIResource | getFocusColor() Returns the focus color.
ColorUIResource | getHighlightedTextColor() Returns the highlighted text color.
ColorUIResource | getInactiveControlTextColor() Returns the inactive control text color.
ColorUIResource | getInactiveSystemTextColor() Returns the inactive system text color.
ColorUIResource | getMenuBackground() Returns the menu background color.
ColorUIResource | getMenuDisabledForeground() Returns the menu disabled foreground color.
ColorUIResource | getMenuForeground() Returns the menu foreground color.
ColorUIResource | getMenuSelectedBackground() Returns the menu selected background color.
ColorUIResource | getMenuSelectedForeground() Returns the menu selected foreground color.
abstract FontUIResource | getMenuTextFont() Returns the menu text font.
abstract String | getName() Returns the name of this theme.
protected abstract ColorUIResource | getPrimary1() Returns the primary 1 color.
protected abstract ColorUIResource | getPrimary2() Returns the primary 2 color.
protected abstract ColorUIResource | getPrimary3() Returns the primary 3 color.
ColorUIResource | getPrimaryControl() Returns the primary control color.
ColorUIResource | getPrimaryControlDarkShadow() Returns the primary control dark shadow color.
ColorUIResource | getPrimaryControlHighlight() Returns the primary control highlight color.
ColorUIResource | getPrimaryControlInfo() Returns the primary control info color.
ColorUIResource | getPrimaryControlShadow() Returns the primary control shadow color.
protected abstract ColorUIResource | getSecondary1() Returns the secondary 1 color.
protected abstract ColorUIResource | getSecondary2() Returns the secondary 2 color.
protected abstract ColorUIResource | getSecondary3() Returns the secondary 3 color.
ColorUIResource | getSeparatorBackground() Returns the separator background color.
ColorUIResource | getSeparatorForeground() Returns the separator foreground color.
abstract FontUIResource | getSubTextFont() Returns the sub-text font.
ColorUIResource | getSystemTextColor() Returns the system text color.
abstract FontUIResource | getSystemTextFont() Returns the system text font.
ColorUIResource | getTextHighlightColor() Returns the text highlight color.
ColorUIResource | getUserTextColor() Returns the user text color.
abstract FontUIResource | getUserTextFont() Returns the user text font.
protected ColorUIResource | getWhite() Returns the white color.
ColorUIResource | getWindowBackground() Returns the window background color.
ColorUIResource | getWindowTitleBackground() Returns the window title background color.
abstract FontUIResource | getWindowTitleFont() Returns the window title font.
ColorUIResource | getWindowTitleForeground() Returns the window title foreground color.
ColorUIResource | getWindowTitleInactiveBackground() Returns the window title inactive background color.
ColorUIResource | getWindowTitleInactiveForeground() Returns the window title inactive foreground color.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalTheme

public MetalTheme()
Method Detail

getName

public abstract String getName()
Returns the name of this theme.

Returns:
the name of this theme

getPrimary1

protected abstract ColorUIResource getPrimary1()
Returns the primary 1 color.

Returns:
the primary 1 color

getPrimary2

protected abstract ColorUIResource getPrimary2()
Returns the primary 2 color.

Returns:
the primary 2 color

getPrimary3

protected abstract ColorUIResource getPrimary3()
Returns the primary 3 color.

Returns:
the primary 3 color

getSecondary1

protected abstract ColorUIResource getSecondary1()
Returns the secondary 1 color.

Returns:
the secondary 1 color

getSecondary2

protected abstract ColorUIResource getSecondary2()
Returns the secondary 2 color.

Returns:
the secondary 2 color

getSecondary3

protected abstract ColorUIResource getSecondary3()
Returns the secondary 3 color.

Returns:
the secondary 3 color

getControlTextFont

public abstract FontUIResource getControlTextFont()
Returns the control text font.

Returns:
the control text font

getSystemTextFont

public abstract FontUIResource getSystemTextFont()
Returns the system text font.

Returns:
the system text font

getUserTextFont

public abstract FontUIResource getUserTextFont()
Returns the user text font.

Returns:
the user text font

getMenuTextFont

public abstract FontUIResource getMenuTextFont()
Returns the menu text font.

Returns:
the menu text font

getWindowTitleFont

public abstract FontUIResource getWindowTitleFont()
Returns the window title font.

Returns:
the window title font

getSubTextFont

public abstract FontUIResource getSubTextFont()
Returns the sub-text font.

Returns:
the sub-text font

getWhite

protected ColorUIResource getWhite()
Returns the white color. This returns opaque white (0xFFFFFFFF).

Returns:
the white color

getBlack

protected ColorUIResource getBlack()
Returns the black color. This returns opaque black (0xFF000000).

Returns:
the black color

getFocusColor

public ColorUIResource getFocusColor()
Returns the focus color. This returns the value of getPrimary2().

Returns:
the focus color

getDesktopColor

public ColorUIResource getDesktopColor()
Returns the desktop color. This returns the value of getPrimary2().

Returns:
the desktop color

getControl

public ColorUIResource getControl()
Returns the control color. This returns the value of getSecondary3().

Returns:
the control color

getControlShadow

public ColorUIResource getControlShadow()
Returns the control shadow color. This returns the value of getSecondary2().

Returns:
the control shadow color

getControlDarkShadow

public ColorUIResource getControlDarkShadow()
Returns the control dark shadow color. This returns the value of getSecondary1().

Returns:
the control dark shadow color

getControlInfo

public ColorUIResource getControlInfo()
Returns the control info color. This returns the value of getBlack().

Returns:
the control info color

getControlHighlight

public ColorUIResource getControlHighlight()
Returns the control highlight color. This returns the value of getWhite().

Returns:
the control highlight color

getControlDisabled

public ColorUIResource getControlDisabled()
Returns the control disabled color. This returns the value of getSecondary2().

Returns:
the control disabled color

getPrimaryControl

public ColorUIResource getPrimaryControl()
Returns the primary control color. This returns the value of getPrimary3().

Returns:
the primary control color

getPrimaryControlShadow

public ColorUIResource getPrimaryControlShadow()
Returns the primary control shadow color. This returns the value of getPrimary2().

Returns:
the primary control shadow color

getPrimaryControlDarkShadow

public ColorUIResource getPrimaryControlDarkShadow()
Returns the primary control dark shadow color. This returns the value of getPrimary1().

Returns:
the primary control dark shadow color

getPrimaryControlInfo

public ColorUIResource getPrimaryControlInfo()
Returns the primary control info color. This returns the value of getBlack().

Returns:
the primary control info color

getPrimaryControlHighlight

public ColorUIResource getPrimaryControlHighlight()
Returns the primary control highlight color. This returns the value of getWhite().

Returns:
the primary control highlight color

getSystemTextColor

public ColorUIResource getSystemTextColor()
Returns the system text color. This returns the value of getBlack().

Returns:
the system text color

getControlTextColor

public ColorUIResource getControlTextColor()
Returns the control text color. This returns the value of getControlInfo().

Returns:
the control text color

getInactiveControlTextColor

public ColorUIResource getInactiveControlTextColor()
Returns the inactive control text color. This returns the value of getControlDisabled().

Returns:
the inactive control text color

getInactiveSystemTextColor

public ColorUIResource getInactiveSystemTextColor()
Returns the inactive system text color. This returns the value of getSecondary2().

Returns:
the inactive system text color

getUserTextColor

public ColorUIResource getUserTextColor()
Returns the user text color. This returns the value of getBlack().

Returns:
the user text color

getTextHighlightColor

public ColorUIResource getTextHighlightColor()
Returns the text highlight color. This returns the value of getPrimary3().

Returns:
the text highlight color

getHighlightedTextColor

public ColorUIResource getHighlightedTextColor()
Returns the highlighted text color. This returns the value of getControlTextColor().

Returns:
the highlighted text color

getWindowBackground

public ColorUIResource getWindowBackground()
Returns the window background color. This returns the value of getWhite().

Returns:
the window background color

getWindowTitleBackground

public ColorUIResource getWindowTitleBackground()
Returns the window title background color. This returns the value of getPrimary3().

Returns:
the window title background color

getWindowTitleForeground

public ColorUIResource getWindowTitleForeground()
Returns the window title foreground color. This returns the value of getBlack().

Returns:
the window title foreground color

getWindowTitleInactiveBackground

public ColorUIResource getWindowTitleInactiveBackground()
Returns the window title inactive background color. This returns the value of getSecondary3().

Returns:
the window title inactive background color

getWindowTitleInactiveForeground

public ColorUIResource getWindowTitleInactiveForeground()
Returns the window title inactive foreground color. This returns the value of getBlack().

Returns:
the window title inactive foreground color

getMenuBackground

public ColorUIResource getMenuBackground()
Returns the menu background color. This returns the value of getSecondary3().

Returns:
the menu background color

getMenuForeground

public ColorUIResource getMenuForeground()
Returns the menu foreground color. This returns the value of getBlack().

Returns:
the menu foreground color

getMenuSelectedBackground

public ColorUIResource getMenuSelectedBackground()
Returns the menu selected background color. This returns the value of getPrimary2().

Returns:
the menu selected background color

getMenuSelectedForeground

public ColorUIResource getMenuSelectedForeground()
Returns the menu selected foreground color. This returns the value of getBlack().

Returns:
the menu selected foreground color

getMenuDisabledForeground

public ColorUIResource getMenuDisabledForeground()
Returns the menu disabled foreground color. This returns the value of getSecondary2().

Returns:
the menu disabled foreground color

getSeparatorBackground

public ColorUIResource getSeparatorBackground()
Returns the separator background color. This returns the value of getWhite().

Returns:
the separator background color

getSeparatorForeground

public ColorUIResource getSeparatorForeground()
Returns the separator foreground color. This returns the value of getPrimary1().

Returns:
the separator foreground color

getAcceleratorForeground

public ColorUIResource getAcceleratorForeground()
Returns the accelerator foreground color. This returns the value of getPrimary1().

Returns:
the accelerator foreground color

getAcceleratorSelectedForeground

public ColorUIResource getAcceleratorSelectedForeground()
Returns the accelerator selected foreground color. This returns the value of getBlack().

Returns:
the accelerator selected foreground color

addCustomEntriesToTable

public void addCustomEntriesToTable(UIDefaults table)
Adds values specific to this theme to the defaults table. This method is invoked when the look and feel defaults are obtained from MetalLookAndFeel.

This implementation does nothing; it is provided for subclasses that wish to customize the defaults table.

Parameters:
table - the UIDefaults to add the values to
See Also:
MetalLookAndFeel.getDefaults()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalToggleButtonUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalToggleButtonUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ButtonUI
            extended by  javax.swing.plaf.basic.BasicButtonUI
                extended by  javax.swing.plaf.basic.BasicToggleButtonUI
                    extended by  javax.swing.plaf.metal.MetalToggleButtonUI

public class MetalToggleButtonUI
extends BasicToggleButtonUI

MetalToggleButton implementation

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected Color | disabledTextColor
protected Color | focusColor
protected Color | selectColor
Fields inherited from class javax.swing.plaf.basic.BasicButtonUI
defaultTextIconGap, defaultTextShiftOffset
Constructor Summary
MetalToggleButtonUI()
Method Summary
static ComponentUI | createUI(JComponent b)
protected Color | getDisabledTextColor()
protected Color | getFocusColor()
protected Color | getSelectColor()
void | installDefaults(AbstractButton b)
protected void | paintButtonPressed(Graphics g, AbstractButton b)
protected void | paintFocus(Graphics g, AbstractButton b, Rectangle viewRect, Rectangle textRect, Rectangle iconRect)
protected void | paintIcon(Graphics g, AbstractButton b, Rectangle iconRect) Paints the appropriate icon of the button b in the space iconRect.
protected void | paintText(Graphics g, JComponent c, Rectangle textRect, String text) As of Java 2 platform v 1.4 this method should not be used or overriden.
protected void | uninstallDefaults(AbstractButton b)
void | update(Graphics g, JComponent c) If necessary paints the background of the component, then invokes paint.
Methods inherited from class javax.swing.plaf.basic.BasicToggleButtonUI
getPropertyPrefix, getTextShiftOffset, paint
Methods inherited from class javax.swing.plaf.basic.BasicButtonUI
clearTextShiftOffset, createButtonListener, getBaseline, getBaselineResizeBehavior, getDefaultTextIconGap, getMaximumSize, getMinimumSize, getPreferredSize, installKeyboardActions, installListeners, installUI, paintIcon, paintText, setTextShiftOffset, uninstallKeyboardActions, uninstallListeners, uninstallUI
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

focusColor

protected Color focusColor

selectColor

protected Color selectColor

disabledTextColor

protected Color disabledTextColor
Constructor Detail

MetalToggleButtonUI

public MetalToggleButtonUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent b)

installDefaults

public void installDefaults(AbstractButton b)
Overrides:
installDefaults in class BasicButtonUI

uninstallDefaults

protected void uninstallDefaults(AbstractButton b)
Overrides:
uninstallDefaults in class BasicButtonUI

getSelectColor

protected Color getSelectColor()

getDisabledTextColor

protected Color getDisabledTextColor()

getFocusColor

protected Color getFocusColor()

update

public void update(Graphics g,
                   JComponent c)
If necessary paints the background of the component, then invokes paint.

Overrides:
update in class ComponentUI
Parameters:
g - Graphics to paint to
c - JComponent painting on
Throws:
NullPointerException - if g or c is null
Since:
1.5
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent), ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent)

paintButtonPressed

protected void paintButtonPressed(Graphics g,
                                  AbstractButton b)
Overrides:
paintButtonPressed in class BasicButtonUI

paintText

protected void paintText(Graphics g,
                         JComponent c,
                         Rectangle textRect,
                         String text)
Description copied from class: BasicButtonUI
As of Java 2 platform v 1.4 this method should not be used or overriden. Use the paintText method which takes the AbstractButton argument.

Overrides:
paintText in class BasicButtonUI

paintFocus

protected void paintFocus(Graphics g,
                          AbstractButton b,
                          Rectangle viewRect,
                          Rectangle textRect,
                          Rectangle iconRect)
Overrides:
paintFocus in class BasicButtonUI

paintIcon

protected void paintIcon(Graphics g,
                         AbstractButton b,
                         Rectangle iconRect)
Paints the appropriate icon of the button b in the space iconRect.

Overrides:
paintIcon in class BasicToggleButtonUI
Parameters:
g - Graphics to paint to
b - Button to render for
iconRect - space to render in
Throws:
NullPointerException - if any of the arguments are null.
Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalToolBarUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalToolBarUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ToolBarUI
            extended by  javax.swing.plaf.basic.BasicToolBarUI
                extended by  javax.swing.plaf.metal.MetalToolBarUI
All Implemented Interfaces:
SwingConstants
public class MetalToolBarUI
extends BasicToolBarUI

A Metal Look and Feel implementation of ToolBarUI. This implementation is a "combined" view/controller.

Nested Class Summary
protected class | MetalToolBarUI.MetalContainerListener
protected class | MetalToolBarUI.MetalDockingListener
protected class | MetalToolBarUI.MetalRolloverListener
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicToolBarUI
BasicToolBarUI.DockingListener, BasicToolBarUI.DragWindow, BasicToolBarUI.FrameListener, BasicToolBarUI.PropertyListener, BasicToolBarUI.ToolBarContListener, BasicToolBarUI.ToolBarFocusListener
Field Summary
protected ContainerListener | contListener This protected field is implemenation specific.
protected PropertyChangeListener | rolloverListener This protected field is implemenation specific.
Fields inherited from class javax.swing.plaf.basic.BasicToolBarUI
constraintBeforeFloating, dockingBorderColor, dockingColor, dockingListener, downKey, dragWindow, floatingBorderColor, floatingColor, focusedCompIndex, leftKey, propertyListener, rightKey, toolBar, toolBarContListener, toolBarFocusListener, upKey
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
MetalToolBarUI()
Method Summary
protected ContainerListener | createContainerListener() Creates a container listener that will be added to the JToolBar.
protected MouseInputListener | createDockingListener()
protected Border | createNonRolloverBorder() Creates the non rollover border for toolbar components.
protected Border | createRolloverBorder() Creates a rollover border for toolbar components.
protected PropertyChangeListener | createRolloverListener() Creates a property change listener that will be added to the JToolBar.
static ComponentUI | createUI(JComponent c)
protected void | installListeners()
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
protected void | setBorderToNonRollover(Component c) Sets the border of the component to have a non-rollover border which was created by createNonRolloverBorder.
protected void | setDragOffset(Point p)
protected void | uninstallListeners()
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
void | update(Graphics g, JComponent c) If necessary paints the background of the component, then invokes paint.
Methods inherited from class javax.swing.plaf.basic.BasicToolBarUI
canDock, createDragWindow, createFloatingFrame, createFloatingWindow, createFrameListener, createPropertyListener, createToolBarContListener, createToolBarFocusListener, dragTo, floatAt, getDockingColor, getFloatingColor, getNonRolloverBorder, getRolloverBorder, installComponents, installDefaults, installKeyboardActions, installNonRolloverBorders, installNormalBorders, installRolloverBorders, isFloating, isRolloverBorders, navigateFocusedComp, paintDragWindow, setBorderToNormal, setBorderToRollover, setDockingColor, setFloating, setFloatingColor, setFloatingLocation, setOrientation, setRolloverBorders, uninstallComponents, uninstallDefaults, uninstallKeyboardActions
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, paint
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

contListener

protected ContainerListener contListener
This protected field is implemenation specific. Do not access directly or override. Use the create method instead.

See Also:
createContainerListener()

rolloverListener

protected PropertyChangeListener rolloverListener
This protected field is implemenation specific. Do not access directly or override. Use the create method instead.

See Also:
createRolloverListener()
Constructor Detail

MetalToolBarUI

public MetalToolBarUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class BasicToolBarUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class BasicToolBarUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

installListeners

protected void installListeners()
Overrides:
installListeners in class BasicToolBarUI

uninstallListeners

protected void uninstallListeners()
Overrides:
uninstallListeners in class BasicToolBarUI

createRolloverBorder

protected Border createRolloverBorder()
Description copied from class: BasicToolBarUI
Creates a rollover border for toolbar components. The rollover border will be installed if rollover borders are enabled.

Override this method to provide an alternate rollover border.

Overrides:
createRolloverBorder in class BasicToolBarUI

createNonRolloverBorder

protected Border createNonRolloverBorder()
Description copied from class: BasicToolBarUI
Creates the non rollover border for toolbar components. This border will be installed as the border for components added to the toolbar if rollover borders are not enabled.

Override this method to provide an alternate rollover border.

Overrides:
createNonRolloverBorder in class BasicToolBarUI

setBorderToNonRollover

protected void setBorderToNonRollover(Component c)
Description copied from class: BasicToolBarUI
Sets the border of the component to have a non-rollover border which was created by createNonRolloverBorder.

Overrides:
setBorderToNonRollover in class BasicToolBarUI
Parameters:
c - component which will have a non-rollover border installed
See Also:
BasicToolBarUI.createNonRolloverBorder()

createContainerListener

protected ContainerListener createContainerListener()
Creates a container listener that will be added to the JToolBar. If this method returns null then it will not be added to the toolbar.

Returns:
an instance of a ContainerListener or null

createRolloverListener

protected PropertyChangeListener createRolloverListener()
Creates a property change listener that will be added to the JToolBar. If this method returns null then it will not be added to the toolbar.

Returns:
an instance of a PropertyChangeListener or null

createDockingListener

protected MouseInputListener createDockingListener()
Overrides:
createDockingListener in class BasicToolBarUI

setDragOffset

protected void setDragOffset(Point p)

update

public void update(Graphics g,
                   JComponent c)
If necessary paints the background of the component, then invokes paint.

Overrides:
update in class ComponentUI
Parameters:
g - Graphics to paint to
c - JComponent painting on
Throws:
NullPointerException - if g or c is null
Since:
1.5
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent), ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalToolBarUI.MetalContainerListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalToolBarUI.MetalContainerListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicToolBarUI.ToolBarContListener
        extended by  javax.swing.plaf.metal.MetalToolBarUI.MetalContainerListener
All Implemented Interfaces:
ContainerListener, EventListener
Enclosing class:
MetalToolBarUI
protected class MetalToolBarUI.MetalContainerListener
extends BasicToolBarUI.ToolBarContListener

Constructor Summary
protected MetalToolBarUI.MetalContainerListener()
Method Summary
Methods inherited from class javax.swing.plaf.basic.BasicToolBarUI.ToolBarContListener
componentAdded, componentRemoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalToolBarUI.MetalContainerListener

protected MetalToolBarUI.MetalContainerListener()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalToolBarUI.MetalDockingListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalToolBarUI.MetalDockingListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicToolBarUI.DockingListener
        extended by  javax.swing.plaf.metal.MetalToolBarUI.MetalDockingListener
All Implemented Interfaces:
MouseListener, MouseMotionListener, EventListener, MouseInputListener
Enclosing class:
MetalToolBarUI
protected class MetalToolBarUI.MetalDockingListener
extends BasicToolBarUI.DockingListener

Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicToolBarUI.DockingListener
isDragging, origin, toolBar
Constructor Summary
MetalToolBarUI.MetalDockingListener(JToolBar t)
Method Summary
void | mouseDragged(MouseEvent e) Invoked when a mouse button is pressed on a component and then dragged.
void | mousePressed(MouseEvent e) Invoked when a mouse button has been pressed on a component.
Methods inherited from class javax.swing.plaf.basic.BasicToolBarUI.DockingListener
mouseClicked, mouseEntered, mouseExited, mouseMoved, mouseReleased
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalToolBarUI.MetalDockingListener

public MetalToolBarUI.MetalDockingListener(JToolBar t)
Method Detail

mousePressed

public void mousePressed(MouseEvent e)
Description copied from interface: MouseListener
Invoked when a mouse button has been pressed on a component.

Specified by:
mousePressed in interface MouseListener
Overrides:
mousePressed in class BasicToolBarUI.DockingListener

mouseDragged

public void mouseDragged(MouseEvent e)
Description copied from interface: MouseMotionListener
Invoked when a mouse button is pressed on a component and then dragged. MOUSE_DRAGGED events will continue to be delivered to the component where the drag originated until the mouse button is released (regardless of whether the mouse position is within the bounds of the component).

Due to platform-dependent Drag&Drop implementations, MOUSE_DRAGGED events may not be delivered during a native Drag&Drop operation.

Specified by:
mouseDragged in interface MouseMotionListener
Overrides:
mouseDragged in class BasicToolBarUI.DockingListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalToolBarUI.MetalRolloverListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalToolBarUI.MetalRolloverListener

java.lang.Object
    extended by  javax.swing.plaf.basic.BasicToolBarUI.PropertyListener
        extended by  javax.swing.plaf.metal.MetalToolBarUI.MetalRolloverListener
All Implemented Interfaces:
PropertyChangeListener, EventListener
Enclosing class:
MetalToolBarUI
protected class MetalToolBarUI.MetalRolloverListener
extends BasicToolBarUI.PropertyListener

Constructor Summary
protected MetalToolBarUI.MetalRolloverListener()
Method Summary
Methods inherited from class javax.swing.plaf.basic.BasicToolBarUI.PropertyListener
propertyChange
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalToolBarUI.MetalRolloverListener

protected MetalToolBarUI.MetalRolloverListener()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalToolTipUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalToolTipUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ToolTipUI
            extended by  javax.swing.plaf.basic.BasicToolTipUI
                extended by  javax.swing.plaf.metal.MetalToolTipUI

public class MetalToolTipUI
extends BasicToolTipUI

A Metal L&F extension of BasicToolTipUI.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
static int padSpaceBetweenStrings
Constructor Summary
MetalToolTipUI()
Method Summary
static ComponentUI | createUI(JComponent c)
String | getAcceleratorString()
Dimension | getPreferredSize(JComponent c) Returns the specified component's preferred size appropriate for the look and feel.
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
protected boolean | isAcceleratorHidden()
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.basic.BasicToolTipUI
getMaximumSize, getMinimumSize, installDefaults, installListeners, uninstallDefaults, uninstallListeners
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

padSpaceBetweenStrings

public static final int padSpaceBetweenStrings
See Also:
Constant Field Values
Constructor Detail

MetalToolTipUI

public MetalToolTipUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent c)

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class BasicToolTipUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class BasicToolTipUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class BasicToolTipUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent c)
Description copied from class: ComponentUI
Returns the specified component's preferred size appropriate for the look and feel. If null is returned, the preferred size will be calculated by the component's layout manager instead (this is the preferred approach for any component with a specific layout manager installed). The default implementation of this method returns null.

Overrides:
getPreferredSize in class BasicToolTipUI
Parameters:
c - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

isAcceleratorHidden

protected boolean isAcceleratorHidden()

getAcceleratorString

public String getAcceleratorString()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MetalTreeUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class MetalTreeUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TreeUI
            extended by  javax.swing.plaf.basic.BasicTreeUI
                extended by  javax.swing.plaf.metal.MetalTreeUI

public class MetalTreeUI
extends BasicTreeUI

The metal look and feel implementation of TreeUI.

MetalTreeUI allows for configuring how to visually render the spacing and delineation between nodes. The following hints are supported:
Angled | A line is drawn connecting the child to the parent. For handling of the root node refer to JTree.setRootVisible(boolean) and JTree.setShowsRootHandles(boolean).
Horizontal | A horizontal line is drawn dividing the children of the root node.
None | Do not draw any visual indication between nodes.

As it is typically impratical to obtain the TreeUI from the JTree and cast to an instance of MetalTreeUI you enable this property via the client property JTree.lineStyle. For example, to switch to Horizontal style you would do: tree.putClientProperty("JTree.lineStyle", "Horizontal");

The default is Angled.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicTreeUI
BasicTreeUI.CellEditorHandler, BasicTreeUI.ComponentHandler, BasicTreeUI.FocusHandler, BasicTreeUI.KeyHandler, BasicTreeUI.MouseHandler, BasicTreeUI.MouseInputHandler, BasicTreeUI.NodeDimensionsHandler, BasicTreeUI.PropertyChangeHandler, BasicTreeUI.SelectionModelPropertyChangeHandler, BasicTreeUI.TreeCancelEditingAction, BasicTreeUI.TreeExpansionHandler, BasicTreeUI.TreeHomeAction, BasicTreeUI.TreeIncrementAction, BasicTreeUI.TreeModelHandler, BasicTreeUI.TreePageAction, BasicTreeUI.TreeSelectionHandler, BasicTreeUI.TreeToggleAction, BasicTreeUI.TreeTraverseAction
Field Summary
Fields inherited from class javax.swing.plaf.basic.BasicTreeUI
cellEditor, collapsedIcon, createdCellEditor, createdRenderer, currentCellRenderer, depthOffset, drawingCache, editingComponent, editingPath, editingRow, editorHasDifferentSize, expandedIcon, largeModel, lastSelectedRow, leftChildIndent, nodeDimensions, preferredMinSize, preferredSize, rendererPane, rightChildIndent, stopEditingInCompleteEditing, totalChildIndent, tree, treeModel, treeSelectionModel, treeState, validCachedPreferredSize
Constructor Summary
MetalTreeUI()
Method Summary
static ComponentUI | createUI(JComponent x)
protected void | decodeLineStyle(Object lineStyleFlag) this function converts between the string passed into the client property and the internal representation (currently and int)
protected int | getHorizontalLegBuffer() The horizontal element of legs between nodes starts at the right of the left-hand side of the child node by default.
void | installUI(JComponent c) Configures the specified component appropriate for the look and feel.
protected boolean | isLocationInExpandControl(int row, int rowLevel, int mouseX, int mouseY)
void | paint(Graphics g, JComponent c) Paints the specified component appropriate for the look and feel.
protected void | paintHorizontalPartOfLeg(Graphics g, Rectangle clipBounds, Insets insets, Rectangle bounds, TreePath path, int row, boolean isExpanded, boolean hasBeenExpanded, boolean isLeaf) Paints the horizontal part of the leg.
protected void | paintHorizontalSeparators(Graphics g, JComponent c)
protected void | paintVerticalPartOfLeg(Graphics g, Rectangle clipBounds, Insets insets, TreePath path) Paints the vertical part of the leg.
void | uninstallUI(JComponent c) Reverses configuration which was done on the specified component during installUI.
Methods inherited from class javax.swing.plaf.basic.BasicTreeUI
cancelEditing, checkForClickInExpandControl, completeEditing, completeEditing, completeUIInstall, completeUIUninstall, configureLayoutCache, createCellEditorListener, createCellRendererPane, createComponentListener, createDefaultCellEditor, createDefaultCellRenderer, createFocusListener, createKeyListener, createLayoutCache, createMouseListener, createNodeDimensions, createPropertyChangeListener, createSelectionModelPropertyChangeListener, createTreeExpansionListener, createTreeModelListener, createTreeSelectionListener, drawCentered, drawDashedHorizontalLine, drawDashedVerticalLine, ensureRowsAreVisible, getBaseline, getBaselineResizeBehavior, getCellEditor, getCellRenderer, getClosestPathForLocation, getCollapsedIcon, getEditingPath, getExpandedIcon, getHashColor, getLastChildPath, getLeftChildIndent, getMaximumSize, getMinimumSize, getModel, getPathBounds, getPathForRow, getPreferredMinSize, getPreferredSize, getPreferredSize, getRightChildIndent, getRowCount, getRowForPath, getRowHeight, getRowX, getSelectionModel, getShowsRootHandles, getVerticalLegBuffer, handleExpandControlClick, installComponents, installDefaults, installKeyboardActions, installListeners, isEditable, isEditing, isLargeModel, isLeaf, isLocationInExpandControl, isMultiSelectEvent, isRootVisible, isToggleEvent, isToggleSelectionEvent, paintExpandControl, paintHorizontalLine, paintRow, paintVerticalLine, pathWasCollapsed, pathWasExpanded, prepareForUIInstall, prepareForUIUninstall, selectPathForEvent, setCellEditor, setCellRenderer, setCollapsedIcon, setEditable, setExpandedIcon, setHashColor, setLargeModel, setLeftChildIndent, setModel, setPreferredMinSize, setRightChildIndent, setRootVisible, setRowHeight, setSelectionModel, setShowsRootHandles, shouldPaintExpandControl, startEditing, startEditingAtPath, stopEditing, toggleExpandState, uninstallComponents, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, updateCachedPreferredSize, updateCellEditor, updateDepthOffset, updateExpandedDescendants, updateLayoutCacheExpandedNodes, updateRenderer, updateSize
Methods inherited from class javax.swing.plaf.ComponentUI
contains, getAccessibleChild, getAccessibleChildrenCount, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetalTreeUI

public MetalTreeUI()
Method Detail

createUI

public static ComponentUI createUI(JComponent x)

getHorizontalLegBuffer

protected int getHorizontalLegBuffer()
Description copied from class: BasicTreeUI
The horizontal element of legs between nodes starts at the right of the left-hand side of the child node by default. This method makes the leg end before that.

Overrides:
getHorizontalLegBuffer in class BasicTreeUI

installUI

public void installUI(JComponent c)
Description copied from class: ComponentUI
Configures the specified component appropriate for the look and feel. This method is invoked when the ComponentUI instance is being installed as the UI delegate on the specified component. This method should completely configure the component for the look and feel, including the following:
  1. Install any default property values for color, fonts, borders, icons, opacity, etc. on the component. Whenever possible, property values initialized by the client program should not be overridden.
  2. Install a LayoutManager on the component if necessary.
  3. Create/add any required sub-components to the component.
  4. Create/install event listeners on the component.
  5. Create/install a PropertyChangeListener on the component in order to detect and respond to component property changes appropriately.
  6. Install keyboard UI (mnemonics, traversal, etc.) on the component.
  7. Initialize any appropriate instance data.

Overrides:
installUI in class BasicTreeUI
Parameters:
c - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent c)
Description copied from class: ComponentUI
Reverses configuration which was done on the specified component during installUI. This method is invoked when this UIComponent instance is being removed as the UI delegate for the specified component. This method should undo the configuration performed in installUI, being careful to leave the JComponent instance in a clean state (no extraneous listeners, look-and-feel-specific property objects, etc.). This should include the following:
  1. Remove any UI-set borders from the component.
  2. Remove any UI-set layout managers on the component.
  3. Remove any UI-added sub-components from the component.
  4. Remove any UI-added event/property listeners from the component.
  5. Remove any UI-installed keyboard UI from the component.
  6. Nullify any allocated instance data objects to allow for GC.

Overrides:
uninstallUI in class BasicTreeUI
Parameters:
c - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

decodeLineStyle

protected void decodeLineStyle(Object lineStyleFlag)
this function converts between the string passed into the client property and the internal representation (currently and int)

isLocationInExpandControl

protected boolean isLocationInExpandControl(int row,
                                            int rowLevel,
                                            int mouseX,
                                            int mouseY)

paint

public void paint(Graphics g,
                  JComponent c)
Description copied from class: ComponentUI
Paints the specified component appropriate for the look and feel. This method is invoked from the ComponentUI.update method when the specified component is being painted. Subclasses should override this method and use the specified Graphics object to render the content of the component.

Overrides:
paint in class BasicTreeUI
Parameters:
g - the Graphics context in which to paint
c - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

paintHorizontalSeparators

protected void paintHorizontalSeparators(Graphics g,
                                         JComponent c)

paintVerticalPartOfLeg

protected void paintVerticalPartOfLeg(Graphics g,
                                      Rectangle clipBounds,
                                      Insets insets,
                                      TreePath path)
Description copied from class: BasicTreeUI
Paints the vertical part of the leg. The receiver should NOT modify clipBounds, insets.

Overrides:
paintVerticalPartOfLeg in class BasicTreeUI

paintHorizontalPartOfLeg

protected void paintHorizontalPartOfLeg(Graphics g,
                                        Rectangle clipBounds,
                                        Insets insets,
                                        Rectangle bounds,
                                        TreePath path,
                                        int row,
                                        boolean isExpanded,
                                        boolean hasBeenExpanded,
                                        boolean isLeaf)
Description copied from class: BasicTreeUI
Paints the horizontal part of the leg. The receiver should NOT modify clipBounds, or insets.

NOTE: parentRow can be -1 if the root is not visible.

Overrides:
paintHorizontalPartOfLeg in class BasicTreeUI
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OceanTheme

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.metal
Class OceanTheme

java.lang.Object
    extended by  javax.swing.plaf.metal.MetalTheme
        extended by  javax.swing.plaf.metal.DefaultMetalTheme
            extended by  javax.swing.plaf.metal.OceanTheme

public class OceanTheme
extends DefaultMetalTheme

The default theme for the MetalLookAndFeel.

The designers of the Metal Look and Feel strive to keep the default look up to date, possibly through the use of new themes in the future. Therefore, developers should only use this class directly when they wish to customize the "Ocean" look, or force it to be the current theme, regardless of future updates.

All colors returned by OceanTheme are completely opaque.

Since:
1.5
See Also:
MetalLookAndFeel.setCurrentTheme(javax.swing.plaf.metal.MetalTheme)

Constructor Summary
OceanTheme()
Creates an instance of OceanTheme
Method Summary
void | addCustomEntriesToTable(UIDefaults table) Add this theme's custom entries to the defaults table.
protected ColorUIResource | getBlack() Returns the black color.
ColorUIResource | getControlTextColor() Returns the control text color.
ColorUIResource | getDesktopColor() Returns the desktop color.
ColorUIResource | getInactiveControlTextColor() Returns the inactive control text color.
ColorUIResource | getMenuDisabledForeground() Returns the menu disabled foreground color.
String | getName() Return the name of this theme, "Ocean".
protected ColorUIResource | getPrimary1() Returns the primary 1 color.
protected ColorUIResource | getPrimary2() Returns the primary 2 color.
protected ColorUIResource | getPrimary3() Returns the primary 3 color.
protected ColorUIResource | getSecondary1() Returns the secondary 1 color.
protected ColorUIResource | getSecondary2() Returns the secondary 2 color.
protected ColorUIResource | getSecondary3() Returns the secondary 3 color.
Methods inherited from class javax.swing.plaf.metal.DefaultMetalTheme
getControlTextFont, getMenuTextFont, getSubTextFont, getSystemTextFont, getUserTextFont, getWindowTitleFont
Methods inherited from class javax.swing.plaf.metal.MetalTheme
getAcceleratorForeground, getAcceleratorSelectedForeground, getControl, getControlDarkShadow, getControlDisabled, getControlHighlight, getControlInfo, getControlShadow, getFocusColor, getHighlightedTextColor, getInactiveSystemTextColor, getMenuBackground, getMenuForeground, getMenuSelectedBackground, getMenuSelectedForeground, getPrimaryControl, getPrimaryControlDarkShadow, getPrimaryControlHighlight, getPrimaryControlInfo, getPrimaryControlShadow, getSeparatorBackground, getSeparatorForeground, getSystemTextColor, getTextHighlightColor, getUserTextColor, getWhite, getWindowBackground, getWindowTitleBackground, getWindowTitleForeground, getWindowTitleInactiveBackground, getWindowTitleInactiveForeground
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

OceanTheme

public OceanTheme()
Creates an instance of OceanTheme

Method Detail

addCustomEntriesToTable

public void addCustomEntriesToTable(UIDefaults table)
Add this theme's custom entries to the defaults table.

Overrides:
addCustomEntriesToTable in class MetalTheme
Parameters:
table - the defaults table, non-null
Throws:
NullPointerException - if table is null
See Also:
MetalLookAndFeel.getDefaults()

getName

public String getName()
Return the name of this theme, "Ocean".

Overrides:
getName in class DefaultMetalTheme
Returns:
"Ocean"

getPrimary1

protected ColorUIResource getPrimary1()
Returns the primary 1 color. This returns a color with an rgb hex value of 0x6382BF.

Overrides:
getPrimary1 in class DefaultMetalTheme
Returns:
the primary 1 color
See Also:
Color.decode(java.lang.String)

getPrimary2

protected ColorUIResource getPrimary2()
Returns the primary 2 color. This returns a color with an rgb hex value of 0xA3B8CC.

Overrides:
getPrimary2 in class DefaultMetalTheme
Returns:
the primary 2 color
See Also:
Color.decode(java.lang.String)

getPrimary3

protected ColorUIResource getPrimary3()
Returns the primary 3 color. This returns a color with an rgb hex value of 0xB8CFE5.

Overrides:
getPrimary3 in class DefaultMetalTheme
Returns:
the primary 3 color
See Also:
Color.decode(java.lang.String)

getSecondary1

protected ColorUIResource getSecondary1()
Returns the secondary 1 color. This returns a color with an rgb hex value of 0x7A8A99.

Overrides:
getSecondary1 in class DefaultMetalTheme
Returns:
the secondary 1 color
See Also:
Color.decode(java.lang.String)

getSecondary2

protected ColorUIResource getSecondary2()
Returns the secondary 2 color. This returns a color with an rgb hex value of 0xB8CFE5.

Overrides:
getSecondary2 in class DefaultMetalTheme
Returns:
the secondary 2 color
See Also:
Color.decode(java.lang.String)

getSecondary3

protected ColorUIResource getSecondary3()
Returns the secondary 3 color. This returns a color with an rgb hex value of 0xEEEEEE.

Overrides:
getSecondary3 in class DefaultMetalTheme
Returns:
the secondary 3 color
See Also:
Color.decode(java.lang.String)

getBlack

protected ColorUIResource getBlack()
Returns the black color. This returns a color with an rgb hex value of 0x333333.

Overrides:
getBlack in class MetalTheme
Returns:
the black color
See Also:
Color.decode(java.lang.String)

getDesktopColor

public ColorUIResource getDesktopColor()
Returns the desktop color. This returns a color with an rgb hex value of 0xFFFFFF.

Overrides:
getDesktopColor in class MetalTheme
Returns:
the desktop color
See Also:
Color.decode(java.lang.String)

getInactiveControlTextColor

public ColorUIResource getInactiveControlTextColor()
Returns the inactive control text color. This returns a color with an rgb hex value of 0x999999.

Overrides:
getInactiveControlTextColor in class MetalTheme
Returns:
the inactive control text color

getControlTextColor

public ColorUIResource getControlTextColor()
Returns the control text color. This returns a color with an rgb hex value of 0x333333.

Overrides:
getControlTextColor in class MetalTheme
Returns:
the control text color

getMenuDisabledForeground

public ColorUIResource getMenuDisabledForeground()
Returns the menu disabled foreground color. This returns a color with an rgb hex value of 0x999999.

Overrides:
getMenuDisabledForeground in class MetalTheme
Returns:
the menu disabled foreground color
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


multi

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.swing.plaf.multi

Provides user interface objects that combine two or more look and feels.

See:
Description

Class Summary
MultiButtonUI | A multiplexing UI used to combine ButtonUIs.
MultiColorChooserUI | A multiplexing UI used to combine ColorChooserUIs.
MultiComboBoxUI | A multiplexing UI used to combine ComboBoxUIs.
MultiDesktopIconUI | A multiplexing UI used to combine DesktopIconUIs.
MultiDesktopPaneUI | A multiplexing UI used to combine DesktopPaneUIs.
MultiFileChooserUI | A multiplexing UI used to combine FileChooserUIs.
MultiInternalFrameUI | A multiplexing UI used to combine InternalFrameUIs.
MultiLabelUI | A multiplexing UI used to combine LabelUIs.
MultiListUI | A multiplexing UI used to combine ListUIs.
MultiLookAndFeel | A multiplexing look and feel that allows more than one UI to be associated with a component at the same time.
MultiMenuBarUI | A multiplexing UI used to combine MenuBarUIs.
MultiMenuItemUI | A multiplexing UI used to combine MenuItemUIs.
MultiOptionPaneUI | A multiplexing UI used to combine OptionPaneUIs.
MultiPanelUI | A multiplexing UI used to combine PanelUIs.
MultiPopupMenuUI | A multiplexing UI used to combine PopupMenuUIs.
MultiProgressBarUI | A multiplexing UI used to combine ProgressBarUIs.
MultiRootPaneUI | A multiplexing UI used to combine RootPaneUIs.
MultiScrollBarUI | A multiplexing UI used to combine ScrollBarUIs.
MultiScrollPaneUI | A multiplexing UI used to combine ScrollPaneUIs.
MultiSeparatorUI | A multiplexing UI used to combine SeparatorUIs.
MultiSliderUI | A multiplexing UI used to combine SliderUIs.
MultiSpinnerUI | A multiplexing UI used to combine SpinnerUIs.
MultiSplitPaneUI | A multiplexing UI used to combine SplitPaneUIs.
MultiTabbedPaneUI | A multiplexing UI used to combine TabbedPaneUIs.
MultiTableHeaderUI | A multiplexing UI used to combine TableHeaderUIs.
MultiTableUI | A multiplexing UI used to combine TableUIs.
MultiTextUI | A multiplexing UI used to combine TextUIs.
MultiToolBarUI | A multiplexing UI used to combine ToolBarUIs.
MultiToolTipUI | A multiplexing UI used to combine ToolTipUIs.
MultiTreeUI | A multiplexing UI used to combine TreeUIs.
MultiViewportUI | A multiplexing UI used to combine ViewportUIs.

Package javax.swing.plaf.multi Description

Provides user interface objects that combine two or more look and feels. When a component asks for its UI, this look and feel returns a multiplexing UI that handles all communications with both the default look and feel and one or more auxiliary look and feels. For example, if a user combines an auxiliary audio look and feel with the Motif look and feel, the JButton.getUI method would return an instance of MultiButtonUI, which would handle both a MotifButtonUI and an AudioButtonUI.

For more information, see Using the Multiplexing Look and Feel.

Note: Most of the Swing API is not thread safe. For details, see Threads and Swing, a section in The Java Tutorial.

Since:
1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.swing.plaf.multi Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.swing.plaf.multi

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.swing.plaf.ComponentUI
      • javax.swing.plaf.ButtonUI
        • javax.swing.plaf.MenuItemUI
          • javax.swing.plaf.multi.MultiMenuItemUI
        • javax.swing.plaf.multi.MultiButtonUI
      • javax.swing.plaf.ColorChooserUI
        • javax.swing.plaf.multi.MultiColorChooserUI
      • javax.swing.plaf.ComboBoxUI
        • javax.swing.plaf.multi.MultiComboBoxUI
      • javax.swing.plaf.DesktopIconUI
        • javax.swing.plaf.multi.MultiDesktopIconUI
      • javax.swing.plaf.DesktopPaneUI
        • javax.swing.plaf.multi.MultiDesktopPaneUI
      • javax.swing.plaf.FileChooserUI
        • javax.swing.plaf.multi.MultiFileChooserUI
      • javax.swing.plaf.InternalFrameUI
        • javax.swing.plaf.multi.MultiInternalFrameUI
      • javax.swing.plaf.LabelUI
        • javax.swing.plaf.multi.MultiLabelUI
      • javax.swing.plaf.ListUI
        • javax.swing.plaf.multi.MultiListUI
      • javax.swing.plaf.MenuBarUI
        • javax.swing.plaf.multi.MultiMenuBarUI
      • javax.swing.plaf.OptionPaneUI
        • javax.swing.plaf.multi.MultiOptionPaneUI
      • javax.swing.plaf.PanelUI
        • javax.swing.plaf.multi.MultiPanelUI
      • javax.swing.plaf.PopupMenuUI
        • javax.swing.plaf.multi.MultiPopupMenuUI
      • javax.swing.plaf.ProgressBarUI
        • javax.swing.plaf.multi.MultiProgressBarUI
      • javax.swing.plaf.RootPaneUI
        • javax.swing.plaf.multi.MultiRootPaneUI
      • javax.swing.plaf.ScrollBarUI
        • javax.swing.plaf.multi.MultiScrollBarUI
      • javax.swing.plaf.ScrollPaneUI
        • javax.swing.plaf.multi.MultiScrollPaneUI
      • javax.swing.plaf.SeparatorUI
        • javax.swing.plaf.multi.MultiSeparatorUI
      • javax.swing.plaf.SliderUI
        • javax.swing.plaf.multi.MultiSliderUI
      • javax.swing.plaf.SpinnerUI
        • javax.swing.plaf.multi.MultiSpinnerUI
      • javax.swing.plaf.SplitPaneUI
        • javax.swing.plaf.multi.MultiSplitPaneUI
      • javax.swing.plaf.TabbedPaneUI
        • javax.swing.plaf.multi.MultiTabbedPaneUI
      • javax.swing.plaf.TableHeaderUI
        • javax.swing.plaf.multi.MultiTableHeaderUI
      • javax.swing.plaf.TableUI
        • javax.swing.plaf.multi.MultiTableUI
      • javax.swing.plaf.TextUI
        • javax.swing.plaf.multi.MultiTextUI
      • javax.swing.plaf.ToolBarUI
        • javax.swing.plaf.multi.MultiToolBarUI
      • javax.swing.plaf.ToolTipUI
        • javax.swing.plaf.multi.MultiToolTipUI
      • javax.swing.plaf.TreeUI
        • javax.swing.plaf.multi.MultiTreeUI
      • javax.swing.plaf.ViewportUI
        • javax.swing.plaf.multi.MultiViewportUI
    • javax.swing.LookAndFeel
      • javax.swing.plaf.multi.MultiLookAndFeel
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.swing.plaf.multi

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.swing.plaf.multi

No usage of javax.swing.plaf.multi

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiButtonUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiButtonUI

No usage of javax.swing.plaf.multi.MultiButtonUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiColorChooserUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiColorChooserUI

No usage of javax.swing.plaf.multi.MultiColorChooserUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiComboBoxUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiComboBoxUI

No usage of javax.swing.plaf.multi.MultiComboBoxUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiDesktopIconUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiDesktopIconUI

No usage of javax.swing.plaf.multi.MultiDesktopIconUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiDesktopPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiDesktopPaneUI

No usage of javax.swing.plaf.multi.MultiDesktopPaneUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiFileChooserUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiFileChooserUI

No usage of javax.swing.plaf.multi.MultiFileChooserUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiInternalFrameUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiInternalFrameUI

No usage of javax.swing.plaf.multi.MultiInternalFrameUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiLabelUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiLabelUI

No usage of javax.swing.plaf.multi.MultiLabelUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiListUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiListUI

No usage of javax.swing.plaf.multi.MultiListUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiLookAndFeel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiLookAndFeel

No usage of javax.swing.plaf.multi.MultiLookAndFeel

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiMenuBarUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiMenuBarUI

No usage of javax.swing.plaf.multi.MultiMenuBarUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiMenuItemUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiMenuItemUI

No usage of javax.swing.plaf.multi.MultiMenuItemUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiOptionPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiOptionPaneUI

No usage of javax.swing.plaf.multi.MultiOptionPaneUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiPanelUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiPanelUI

No usage of javax.swing.plaf.multi.MultiPanelUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiPopupMenuUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiPopupMenuUI

No usage of javax.swing.plaf.multi.MultiPopupMenuUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiProgressBarUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiProgressBarUI

No usage of javax.swing.plaf.multi.MultiProgressBarUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiRootPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiRootPaneUI

No usage of javax.swing.plaf.multi.MultiRootPaneUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiScrollBarUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiScrollBarUI

No usage of javax.swing.plaf.multi.MultiScrollBarUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiScrollPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiScrollPaneUI

No usage of javax.swing.plaf.multi.MultiScrollPaneUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiSeparatorUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiSeparatorUI

No usage of javax.swing.plaf.multi.MultiSeparatorUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiSliderUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiSliderUI

No usage of javax.swing.plaf.multi.MultiSliderUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiSpinnerUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiSpinnerUI

No usage of javax.swing.plaf.multi.MultiSpinnerUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiSplitPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiSplitPaneUI

No usage of javax.swing.plaf.multi.MultiSplitPaneUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiTabbedPaneUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiTabbedPaneUI

No usage of javax.swing.plaf.multi.MultiTabbedPaneUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiTableHeaderUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiTableHeaderUI

No usage of javax.swing.plaf.multi.MultiTableHeaderUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiTableUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiTableUI

No usage of javax.swing.plaf.multi.MultiTableUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiTextUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiTextUI

No usage of javax.swing.plaf.multi.MultiTextUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiToolBarUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiToolBarUI

No usage of javax.swing.plaf.multi.MultiToolBarUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiToolTipUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiToolTipUI

No usage of javax.swing.plaf.multi.MultiToolTipUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiTreeUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiTreeUI

No usage of javax.swing.plaf.multi.MultiTreeUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.multi.MultiViewportUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.multi.MultiViewportUI

No usage of javax.swing.plaf.multi.MultiViewportUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


 Using the Multiplexing Look and Feel

This document is based on an article originally published in The Swing Connection.

The Multiplexing look and feel lets you supplement an ordinary look and feel (called the default look and feel) with one or more auxiliary look and feels. For example, you could simultaneously provide text-to-speech and Braille outputs, in addition to the ordinary visual output that a Swing-based application generates, by adding two auxiliary look and feels (one for text-to-speech, the other for Braille) to the default look and feel. The default look and feel can be any ordinary look and feel -- the Java or Windows look and feel, for example -- and requires no modifications to work with auxiliary look and feels.

This document has the following sections:

  • Overview
  • How to Use Auxiliary Look and Feels
  • Tips for Writing an Auxiliary Look and Feel
    • Dos and Don'ts
    • Extending UIDefaults
    • Examining Other UI Objects
  • How the Multiplexing Look and Feel is Implemented
  • How to Provide a Custom Multiplexing Look and Feel

Before reading further, you should be familiar with the concept of pluggable look and feels. For basic information, see Choosing the Look and Feel, a section in The Java Tutorial. For architectural details, you can read Pluggable look-and-feel architecture, a section within a Swing Connection article.

Overview

The classes in the javax.swing.plaf.multi package implement a multiplexing look and feel. A multiplexing look and feel transparently creates -- and simultaneously supports -- UI objects from several different look and feels in response to a component requesting its UI object (with the getUI method).

Without a multiplexing look and feel, a developer who wanted to enhance a particular look and feel would need to extend the classes supporting that look and feel. For example, to add text-to-speech support to the Java look and feel without using a multiplexing look and feel, the developer would need to create a group of classes that extend those of the Java look and feel, and add text-to-speech support to the new classes. If the developer also wanted to add text-to-speech support to other look and feels, such as Motif or Windows, the developers would need to create subclasses of those classes as well.

This approach has at least two shortcomings:

  • First, each subclass must use what is essentially a copy of the same code, potentially creating a difficult support situation for the developer.
  • Second, and more significantly for the end user, some application developers might force a particular look and feel to be used. When this approach is used, the end user can't even use the enhanced look and feel.

A multiplexing look and feel both these problems simultaneously because it allows multiple look and feels to be combined. The first problem (having to use what amounts to a second copy of the same code) is solved because the developer can create a specialized look and feel that can then be combined with other look and feels.

The second problem (having to force the use of a particular look and feel) is solved because a specialized look and feel can be used with whatever default look and feel the application may have locked in place.

The default multiplexing look and feel implementation, represented by the MultiLookAndFeel class in the javax.swing.plaf.multi package, is called (unsurprisingly) the Multiplexing look and feel.

How to Use Auxiliary Look and Feels

It's easy to use auxiliary look and feels with Swing. To instruct Swing to use the Multiplexing look and feel, all an application has to do is modify the $JDKHOME/lib/swing.properties file to include a definition of the swing.auxiliarylaf property. Swing treats the swing.auxiliarylaf property as a comma-separated list of LookAndFeel subclasses that specify what auxiliary look and feels should be used in addition to the default look and feel. If at least one valid LookAndFeel subclass is specified in the swing.auxiliarylaf property, Swing automatically uses the Multiplexing look and feel to load and support the default and auxiliary look and feels.

For example, let's assume that an application makes use of a look and feel that supports text-to-speech feedback, and also uses an look and feel that adds support for a device that emits perfume. Let's assume that the text-to-speech look and feel is named com.myco.TextTalkerLookAndFeel, and the look and feel that adds support for perfume is named com.smellco.OlfactoryLookAndFeel.

To tell Swing to use both these look and feels -- and to use a default look and feel at the same time -- your application could simply add the following line to the $JDKHOME/lib/swing.properties file:

    swing.auxiliarylaf=com.myco.TextTalkerLookAndFeel,
        com.smellco.OlfactoryLookAndFeel

This statement tells Swing to obtain a component's UI from the Multiplexing look and feel automatically, instead of obtaining it directly from the default look and feel. The resulting multiplexing UI is a small delegate that obtains and maintains UIs from the default and auxiliary look and feels. As a result, when a method is invoked in a multiplexing UI object, the multiplexing UI invokes the same method on each of the UIs obtained from the default and auxiliary look and feels.

Tips for Writing an Auxiliary Look and Feel

An auxiliary look and feel is like any other look and feel, except that it doesn't have to provide the complete support that a default look and feel must. For example, an auxiliary look and feel that supports just text-to-speech feedback doesn't need to provide any code for painting. Also, it might not need to support all components -- JSeparators, for example, might be ignored.

Auxiliary look and feels tend to be simple, so developing one can be easier than developing a visual look and feel. The developer can concentrate solely on providing the specialized functionality.

Because the primary purpose of an auxiliary look and feel is to enhance the default look and feel, auxiliary look and feels tend be nonvisual. Since an auxiliary look and feel is a genuine look and feel, however, there is nothing to prevent it from rendering information on the display.

Just like for any other look and feel, you implement an auxiliary look and feel by writing a subclass of javax.swing.LookAndFeel and creating subclasses of the FooUI classes defined in the javax.swing.plaf package.

Dos and Don'ts

The following paragraphs provide some general recommendations for developing auxiliary look and feels.

Use the installUI method to perform all initialization, and the uninstallUI method to perform all cleanup.

    The installUI and uninstallUI methods are invoked when a component's look and feel is set. The installUI method gives the new UI object a chance to add listeners on the component and its data model. Similarly, the uninstallUI method lets the previous UI object remove its listeners.

Don't extend visual look and feels.

    We recommended that you don't implement UI classes of an auxiliary look and feel as subclasses of the UI classes of a visual look and feel. Why not? Because they might accidentally inherit code that installs listeners on a component object or renders the component on the display. As a result, your auxiliary look and feel would compete with the default look and feel rather than cooperating with it.

    Instead, we recommend that the UI classes of an auxiliary look and feel directly extend the abstract UI classes in the javax.swing.plaf package. By using this strategy, the developer of an auxiliary look and feel can avoid competing with the default look and feel.

Override all UI-specific methods your UI classes inherit.

    We recommend that each UI class of an auxiliary look and feel override the methods defined in the javax.swing.plaf UI classes it descends from The reasons for this recommendation are similar to those for not extending a visual look and feel. For example, the ComponentUI class, from which all UI classes descend, provides a default implementation for the update method. This default implementation paints on the display if the component is opaque. If a UI class from a non-visual auxiliary look and feel does not override this method, all opaque components appear as blank areas on the screen!

Extending UIDefaults

In many cases, you might want an auxiliary look and feel to be "incomplete." That is, you might not need to support the complete set of components. For example, an auxiliary look and feel might choose to provide a ButtonUI subclass but no LabelUI subclass. This option is allowed, and the multiplexing look and feel gracefully handles such situations.

By default, however, Swing issues an error message when it asks a look and feel for a UI object and the look and feel does not support that UI. This message can be annoying, especially to auxiliary look-and-feel developers who don't want to support a particular component.

Fortunately, you can prevent this error message by creating a subclass of the UIDefaults class and returning an instance of it from the getDefaults method of your LookAndFeel class. For example:

public class MyAuxLookAndFeel
              extends LookAndFeel {
...
public UIDefaults getDefaults() {
UIDefaults table =
new MyAuxUIDefaults();
Object[] uiDefaults = {
"ButtonUI", "MyAuxButtonUI",
...
}
table.putDefaults(uiDefaults);
return table;
}
}

class MyAuxUIDefaults extends UIDefaults {
protected void getUIError(String msg) {
//System.err.println
//   ("An
              annoying message!");
}
}

In the preceding example, an auxiliary look and feel named MyAux creates a UIDefaults subclass that overrides the getUIError method. The getUIError method is the method that is invoked when Swing cannot find a UI object in a look and feel. By merely doing nothing in this method, you can avoid the error message.

Examining Other UI Objects

In rare instances, a UI object from an auxiliary look and feel may be interested in the default UI object used by the component. In these cases, the UI object from auxiliary look and feel can obtain the UI from a component by calling its getUI method. The returned UI is an instance of one of the multiplexing look and feel UI classes (for example, MultiButtonUI). The UI object from the auxiliary look and feel can call the getUIs method of the returned object to obtain an array containing a complete list of all UI objects handled by the multiplexing UI. The first element is guaranteed to be the UI created from the default look and feel.

How the Multiplexing Look and Feel Is Implemented

The Multiplexing look and feel (represented by javax.swing.plaf.multi.MultiLookAndFeel) is meant to be transparent to all developers and users. It should "just work" -- and it is used only when the user tells Swing to use an auxiliary look and feel.

When the Multiplexing look and feel is in use, the type of the UI object associated with each component depends on whether any of the auxiliary look and feels currently in use support the component. If so, the component's UI object is an instance of a multiplexing UI. If only the default look and feel supports the component, then the component gets a UI object from the default look and feel, just as if no auxiliary look and feels were installed.

A multiplexing UI object obtains and maintains UI objects from the default and auxiliary look and feels, referring to these UIs in the following manner:

  • The UI object from the default look and feel is always the first to be created. After that, a UI object is created from each auxiliary look and feel in the order they are specified in the swing.auxiliarylaf property.

  • When a method that requests information from a UI object is invoked, the multiplexing UI object invokes the method on all the UI objects, but returns only the results from the UI for the default look and feel. For example, when the getPreferredSize method is invoked on a multiplexing UI, the UI returns only the results of invoking getPreferredSize on the UI obtained from the default look and feel. The getPreferredSize method is also invoked on the UI object for each auxiliary look and feel, but the return values are ignored.

  • When a method that does not request information from the UI object is invoked, the multiplexing UI object invokes that method on all UIs -- on the UI object obtained from the default look and feel and on all the UIs obtained from the auxiliary look and feels, as well. For example, invoking the installUI method on a multiplexing UI causes the multiplexing UI to invoke installUI on the UI obtained from the default look and feel and the UIs obtained from the auxiliary factories.

In all cases, the UI object obtained from the default look and feel is acted upon first, and then the auxiliary look and feels are acted upon in the order they are specified in the swing.auxiliarylaf property.

How to Provide a Custom Multiplexing Look and Feel

While we hope the behavior of the Multiplexing look and feel is flexible enough not to require an alternative multiplexing look and feel, Swing allows the user to specify another multiplexing look and feel to use.

To do that, all the user has to do is modify the $JDKHOME/lib/swing.properties file to include a definition of the swing.plaf.multiplexinglaf property. Swing then treats the swing.plaf.multiplexinglaf property as a LookAndFeel subclass that supports multiplexing.

For example, if a user has a multiplexing look and feel represented by com.myco.SuperMultiLookAndFeel that is a better match for their needs than the Multiplexing look and feel (javax.swing.plaf.multi.MultiLookAndFeel), the user could include the following line in $JDKHOME/lib/swing.properties:

swing.plaf.multiplexinglaf = com.myco.SuperMultiLookAndFeel

This statement instructs Swing to use com.myco.SuperMultiLookAndFeel instead of javax.swing.plaf.multi.MultiLookAndFeel. But if you use this kind of statement, be careful, because the suppliers of auxiliary look and feels will most likely have developed and tested against our Multiplexing look and feel.


MultiButtonUI

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiButtonUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ButtonUI
            extended by  javax.swing.plaf.multi.MultiButtonUI

public class MultiButtonUI
extends ButtonUI

A multiplexing UI used to combine ButtonUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiButtonUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiButtonUI

public MultiButtonUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


MultiColorChooserUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiColorChooserUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ColorChooserUI
            extended by  javax.swing.plaf.multi.MultiColorChooserUI

public class MultiColorChooserUI
extends ColorChooserUI

A multiplexing UI used to combine ColorChooserUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiColorChooserUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiColorChooserUI

public MultiColorChooserUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiComboBoxUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiComboBoxUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ComboBoxUI
            extended by  javax.swing.plaf.multi.MultiComboBoxUI

public class MultiComboBoxUI
extends ComboBoxUI

A multiplexing UI used to combine ComboBoxUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiComboBoxUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
boolean | isFocusTraversable(JComboBox a) Invokes the isFocusTraversable method on each UI handled by this object.
boolean | isPopupVisible(JComboBox a) Invokes the isPopupVisible method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | setPopupVisible(JComboBox a, boolean b) Invokes the setPopupVisible method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiComboBoxUI

public MultiComboBoxUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

isFocusTraversable

public boolean isFocusTraversable(JComboBox a)
Invokes the isFocusTraversable method on each UI handled by this object.

Specified by:
isFocusTraversable in class ComboBoxUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

setPopupVisible

public void setPopupVisible(JComboBox a,
                            boolean b)
Invokes the setPopupVisible method on each UI handled by this object.

Specified by:
setPopupVisible in class ComboBoxUI

isPopupVisible

public boolean isPopupVisible(JComboBox a)
Invokes the isPopupVisible method on each UI handled by this object.

Specified by:
isPopupVisible in class ComboBoxUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiDesktopIconUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiDesktopIconUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.DesktopIconUI
            extended by  javax.swing.plaf.multi.MultiDesktopIconUI

public class MultiDesktopIconUI
extends DesktopIconUI

A multiplexing UI used to combine DesktopIconUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiDesktopIconUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiDesktopIconUI

public MultiDesktopIconUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiDesktopPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiDesktopPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.DesktopPaneUI
            extended by  javax.swing.plaf.multi.MultiDesktopPaneUI

public class MultiDesktopPaneUI
extends DesktopPaneUI

A multiplexing UI used to combine DesktopPaneUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiDesktopPaneUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiDesktopPaneUI

public MultiDesktopPaneUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiFileChooserUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiFileChooserUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.FileChooserUI
            extended by  javax.swing.plaf.multi.MultiFileChooserUI

public class MultiFileChooserUI
extends FileChooserUI

A multiplexing UI used to combine FileChooserUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiFileChooserUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
void | ensureFileIsVisible(JFileChooser a, File b) Invokes the ensureFileIsVisible method on each UI handled by this object.
FileFilter | getAcceptAllFileFilter(JFileChooser a) Invokes the getAcceptAllFileFilter method on each UI handled by this object.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
String | getApproveButtonText(JFileChooser a) Invokes the getApproveButtonText method on each UI handled by this object.
String | getDialogTitle(JFileChooser a) Invokes the getDialogTitle method on each UI handled by this object.
FileView | getFileView(JFileChooser a) Invokes the getFileView method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | rescanCurrentDirectory(JFileChooser a) Invokes the rescanCurrentDirectory method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiFileChooserUI

public MultiFileChooserUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

getAcceptAllFileFilter

public FileFilter getAcceptAllFileFilter(JFileChooser a)
Invokes the getAcceptAllFileFilter method on each UI handled by this object.

Specified by:
getAcceptAllFileFilter in class FileChooserUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

getFileView

public FileView getFileView(JFileChooser a)
Invokes the getFileView method on each UI handled by this object.

Specified by:
getFileView in class FileChooserUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

getApproveButtonText

public String getApproveButtonText(JFileChooser a)
Invokes the getApproveButtonText method on each UI handled by this object.

Specified by:
getApproveButtonText in class FileChooserUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

getDialogTitle

public String getDialogTitle(JFileChooser a)
Invokes the getDialogTitle method on each UI handled by this object.

Specified by:
getDialogTitle in class FileChooserUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

rescanCurrentDirectory

public void rescanCurrentDirectory(JFileChooser a)
Invokes the rescanCurrentDirectory method on each UI handled by this object.

Specified by:
rescanCurrentDirectory in class FileChooserUI

ensureFileIsVisible

public void ensureFileIsVisible(JFileChooser a,
                                File b)
Invokes the ensureFileIsVisible method on each UI handled by this object.

Specified by:
ensureFileIsVisible in class FileChooserUI

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiInternalFrameUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiInternalFrameUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.InternalFrameUI
            extended by  javax.swing.plaf.multi.MultiInternalFrameUI

public class MultiInternalFrameUI
extends InternalFrameUI

A multiplexing UI used to combine InternalFrameUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiInternalFrameUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiInternalFrameUI

public MultiInternalFrameUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiLabelUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiLabelUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.LabelUI
            extended by  javax.swing.plaf.multi.MultiLabelUI

public class MultiLabelUI
extends LabelUI

A multiplexing UI used to combine LabelUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiLabelUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiLabelUI

public MultiLabelUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiListUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiListUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ListUI
            extended by  javax.swing.plaf.multi.MultiListUI

public class MultiListUI
extends ListUI

A multiplexing UI used to combine ListUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiListUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Rectangle | getCellBounds(JList a, int b, int c) Invokes the getCellBounds method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
Point | indexToLocation(JList a, int b) Invokes the indexToLocation method on each UI handled by this object.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
int | locationToIndex(JList a, Point b) Invokes the locationToIndex method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiListUI

public MultiListUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

locationToIndex

public int locationToIndex(JList a,
                           Point b)
Invokes the locationToIndex method on each UI handled by this object.

Specified by:
locationToIndex in class ListUI
Parameters:
a - the list
b - the coordinates of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

indexToLocation

public Point indexToLocation(JList a,
                             int b)
Invokes the indexToLocation method on each UI handled by this object.

Specified by:
indexToLocation in class ListUI
Parameters:
a - the list
b - the cell index
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

getCellBounds

public Rectangle getCellBounds(JList a,
                               int b,
                               int c)
Invokes the getCellBounds method on each UI handled by this object.

Specified by:
getCellBounds in class ListUI
Parameters:
a - the list
b - the first index in the range
c - the second index in the range
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiLookAndFeel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiLookAndFeel

java.lang.Object
    extended by  javax.swing.LookAndFeel
        extended by  javax.swing.plaf.multi.MultiLookAndFeel

public class MultiLookAndFeel
extends LookAndFeel

A multiplexing look and feel that allows more than one UI to be associated with a component at the same time. The primary look and feel is called the default look and feel, and the other look and feels are called auxiliary.

For further information, see Using the Multiplexing Look and Feel.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
UIManager.addAuxiliaryLookAndFeel(javax.swing.LookAndFeel), javax.swing.plaf.multi

Constructor Summary
MultiLookAndFeel()
Method Summary
static ComponentUI | createUIs(ComponentUI mui, Vector uis, JComponent target) Creates the ComponentUI objects required to present the target component, placing the objects in the uis vector and returning the ComponentUI object that best represents the component's UI.
UIDefaults | getDefaults() Creates, initializes, and returns the look and feel specific defaults.
String | getDescription() Returns a one-line description of this look and feel.
String | getID() Returns a string, suitable for use by applications/services, that identifies this look and feel.
String | getName() Returns a string, suitable for use in menus, that identifies this look and feel.
boolean | isNativeLookAndFeel() Returns false; this look and feel is not native to any platform.
boolean | isSupportedLookAndFeel() Returns true; every platform permits this look and feel.
protected static ComponentUI[] | uisToArray(Vector uis) Creates an array, populates it with UI objects from the passed-in vector, and returns the array.
Methods inherited from class javax.swing.LookAndFeel
getDesktopPropertyValue, getDisabledIcon, getDisabledSelectedIcon, getLayoutStyle, getSupportsWindowDecorations, initialize, installBorder, installColors, installColorsAndFont, installProperty, loadKeyBindings, makeComponentInputMap, makeIcon, makeInputMap, makeKeyBindings, provideErrorFeedback, toString, uninitialize, uninstallBorder
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MultiLookAndFeel

public MultiLookAndFeel()
Method Detail

getName

public String getName()
Returns a string, suitable for use in menus, that identifies this look and feel.

Specified by:
getName in class LookAndFeel
Returns:
a string such as "Multiplexing Look and Feel"

getID

public String getID()
Returns a string, suitable for use by applications/services, that identifies this look and feel.

Specified by:
getID in class LookAndFeel
Returns:
"Multiplex"

getDescription

public String getDescription()
Returns a one-line description of this look and feel.

Specified by:
getDescription in class LookAndFeel
Returns:
a descriptive string such as "Allows multiple UI instances per component instance"

isNativeLookAndFeel

public boolean isNativeLookAndFeel()
Returns false; this look and feel is not native to any platform.

Specified by:
isNativeLookAndFeel in class LookAndFeel
Returns:
false

isSupportedLookAndFeel

public boolean isSupportedLookAndFeel()
Returns true; every platform permits this look and feel.

Specified by:
isSupportedLookAndFeel in class LookAndFeel
Returns:
true
See Also:
UIManager.setLookAndFeel(javax.swing.LookAndFeel)

getDefaults

public UIDefaults getDefaults()
Creates, initializes, and returns the look and feel specific defaults. For this look and feel, the defaults consist solely of mappings of UI class IDs (such as "ButtonUI") to ComponentUI class names (such as "javax.swing.plaf.multi.MultiButtonUI").

Overrides:
getDefaults in class LookAndFeel
Returns:
an initialized UIDefaults object
See Also:
JComponent.getUIClassID()

createUIs

public static ComponentUI createUIs(ComponentUI mui,
                                    Vector uis,
                                    JComponent target)
Creates the ComponentUI objects required to present the target component, placing the objects in the uis vector and returning the ComponentUI object that best represents the component's UI. This method finds the ComponentUI objects by invoking getDefaults().getUI(target) on each default and auxiliary look and feel currently in use. The first UI object this method adds to the uis vector is for the default look and feel.

This method is invoked by the createUI method of MultiXxxxUI classes.

Parameters:
mui - the ComponentUI object that represents the complete UI for the target component; this should be an instance of one of the MultiXxxxUI classes
uis - a Vector; generally this is the uis field of the mui argument
target - a component whose UI is represented by mui
Returns:
mui if the component has any auxiliary UI objects; otherwise, returns the UI object for the default look and feel or null if the default UI object couldn't be found
See Also:
UIManager.getAuxiliaryLookAndFeels(), UIDefaults.getUI(javax.swing.JComponent), MultiButtonUI.uis, MultiButtonUI.createUI(javax.swing.JComponent)

uisToArray

protected static ComponentUI[] uisToArray(Vector uis)
Creates an array, populates it with UI objects from the passed-in vector, and returns the array. If uis is null, this method returns an array with zero elements. If uis is an empty vector, this method returns null. A run-time error occurs if any objects in the uis vector are not of type ComponentUI.

Parameters:
uis - a vector containing ComponentUI objects
Returns:
an array equivalent to the passed-in vector
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiMenuBarUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiMenuBarUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.MenuBarUI
            extended by  javax.swing.plaf.multi.MultiMenuBarUI

public class MultiMenuBarUI
extends MenuBarUI

A multiplexing UI used to combine MenuBarUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiMenuBarUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiMenuBarUI

public MultiMenuBarUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiMenuItemUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiMenuItemUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ButtonUI
            extended by  javax.swing.plaf.MenuItemUI
                extended by  javax.swing.plaf.multi.MultiMenuItemUI

public class MultiMenuItemUI
extends MenuItemUI

A multiplexing UI used to combine MenuItemUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiMenuItemUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiMenuItemUI

public MultiMenuItemUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiOptionPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiOptionPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.OptionPaneUI
            extended by  javax.swing.plaf.multi.MultiOptionPaneUI

public class MultiOptionPaneUI
extends OptionPaneUI

A multiplexing UI used to combine OptionPaneUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiOptionPaneUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
boolean | containsCustomComponents(JOptionPane a) Invokes the containsCustomComponents method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | selectInitialValue(JOptionPane a) Invokes the selectInitialValue method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiOptionPaneUI

public MultiOptionPaneUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

selectInitialValue

public void selectInitialValue(JOptionPane a)
Invokes the selectInitialValue method on each UI handled by this object.

Specified by:
selectInitialValue in class OptionPaneUI

containsCustomComponents

public boolean containsCustomComponents(JOptionPane a)
Invokes the containsCustomComponents method on each UI handled by this object.

Specified by:
containsCustomComponents in class OptionPaneUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiPanelUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiPanelUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.PanelUI
            extended by  javax.swing.plaf.multi.MultiPanelUI

public class MultiPanelUI
extends PanelUI

A multiplexing UI used to combine PanelUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiPanelUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiPanelUI

public MultiPanelUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiPopupMenuUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiPopupMenuUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.PopupMenuUI
            extended by  javax.swing.plaf.multi.MultiPopupMenuUI

public class MultiPopupMenuUI
extends PopupMenuUI

A multiplexing UI used to combine PopupMenuUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiPopupMenuUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Popup | getPopup(JPopupMenu a, int b, int c) Invokes the getPopup method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
boolean | isPopupTrigger(MouseEvent a) Invokes the isPopupTrigger method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiPopupMenuUI

public MultiPopupMenuUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

isPopupTrigger

public boolean isPopupTrigger(MouseEvent a)
Invokes the isPopupTrigger method on each UI handled by this object.

Overrides:
isPopupTrigger in class PopupMenuUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
Since:
1.3

getPopup

public Popup getPopup(JPopupMenu a,
                      int b,
                      int c)
Invokes the getPopup method on each UI handled by this object.

Overrides:
getPopup in class PopupMenuUI
Parameters:
a - JPopupMenu requesting Popup
b - Screen x location Popup is to be shown at
c - Screen y location Popup is to be shown at.
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
Since:
1.4

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiProgressBarUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiProgressBarUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ProgressBarUI
            extended by  javax.swing.plaf.multi.MultiProgressBarUI

public class MultiProgressBarUI
extends ProgressBarUI

A multiplexing UI used to combine ProgressBarUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiProgressBarUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiProgressBarUI

public MultiProgressBarUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiRootPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiRootPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.RootPaneUI
            extended by  javax.swing.plaf.multi.MultiRootPaneUI

public class MultiRootPaneUI
extends RootPaneUI

A multiplexing UI used to combine RootPaneUIs.

This file was automatically generated by AutoMulti.

Since:
1.4

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiRootPaneUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiRootPaneUI

public MultiRootPaneUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiScrollBarUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiScrollBarUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ScrollBarUI
            extended by  javax.swing.plaf.multi.MultiScrollBarUI

public class MultiScrollBarUI
extends ScrollBarUI

A multiplexing UI used to combine ScrollBarUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiScrollBarUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiScrollBarUI

public MultiScrollBarUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiScrollPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiScrollPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ScrollPaneUI
            extended by  javax.swing.plaf.multi.MultiScrollPaneUI

public class MultiScrollPaneUI
extends ScrollPaneUI

A multiplexing UI used to combine ScrollPaneUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiScrollPaneUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiScrollPaneUI

public MultiScrollPaneUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiSeparatorUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiSeparatorUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SeparatorUI
            extended by  javax.swing.plaf.multi.MultiSeparatorUI

public class MultiSeparatorUI
extends SeparatorUI

A multiplexing UI used to combine SeparatorUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiSeparatorUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiSeparatorUI

public MultiSeparatorUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiSliderUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiSliderUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SliderUI
            extended by  javax.swing.plaf.multi.MultiSliderUI

public class MultiSliderUI
extends SliderUI

A multiplexing UI used to combine SliderUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiSliderUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiSliderUI

public MultiSliderUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiSpinnerUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiSpinnerUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SpinnerUI
            extended by  javax.swing.plaf.multi.MultiSpinnerUI

public class MultiSpinnerUI
extends SpinnerUI

A multiplexing UI used to combine SpinnerUIs.

This file was automatically generated by AutoMulti.

Since:
1.4

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiSpinnerUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiSpinnerUI

public MultiSpinnerUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiSplitPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiSplitPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SplitPaneUI
            extended by  javax.swing.plaf.multi.MultiSplitPaneUI

public class MultiSplitPaneUI
extends SplitPaneUI

A multiplexing UI used to combine SplitPaneUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiSplitPaneUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
void | finishedPaintingChildren(JSplitPane a, Graphics b) Invokes the finishedPaintingChildren method on each UI handled by this object.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
int | getDividerLocation(JSplitPane a) Invokes the getDividerLocation method on each UI handled by this object.
int | getMaximumDividerLocation(JSplitPane a) Invokes the getMaximumDividerLocation method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
int | getMinimumDividerLocation(JSplitPane a) Invokes the getMinimumDividerLocation method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | resetToPreferredSizes(JSplitPane a) Invokes the resetToPreferredSizes method on each UI handled by this object.
void | setDividerLocation(JSplitPane a, int b) Invokes the setDividerLocation method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiSplitPaneUI

public MultiSplitPaneUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

resetToPreferredSizes

public void resetToPreferredSizes(JSplitPane a)
Invokes the resetToPreferredSizes method on each UI handled by this object.

Specified by:
resetToPreferredSizes in class SplitPaneUI

setDividerLocation

public void setDividerLocation(JSplitPane a,
                               int b)
Invokes the setDividerLocation method on each UI handled by this object.

Specified by:
setDividerLocation in class SplitPaneUI

getDividerLocation

public int getDividerLocation(JSplitPane a)
Invokes the getDividerLocation method on each UI handled by this object.

Specified by:
getDividerLocation in class SplitPaneUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

getMinimumDividerLocation

public int getMinimumDividerLocation(JSplitPane a)
Invokes the getMinimumDividerLocation method on each UI handled by this object.

Specified by:
getMinimumDividerLocation in class SplitPaneUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

getMaximumDividerLocation

public int getMaximumDividerLocation(JSplitPane a)
Invokes the getMaximumDividerLocation method on each UI handled by this object.

Specified by:
getMaximumDividerLocation in class SplitPaneUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

finishedPaintingChildren

public void finishedPaintingChildren(JSplitPane a,
                                     Graphics b)
Invokes the finishedPaintingChildren method on each UI handled by this object.

Specified by:
finishedPaintingChildren in class SplitPaneUI

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiTabbedPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiTabbedPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TabbedPaneUI
            extended by  javax.swing.plaf.multi.MultiTabbedPaneUI

public class MultiTabbedPaneUI
extends TabbedPaneUI

A multiplexing UI used to combine TabbedPaneUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiTabbedPaneUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
Rectangle | getTabBounds(JTabbedPane a, int b) Invokes the getTabBounds method on each UI handled by this object.
int | getTabRunCount(JTabbedPane a) Invokes the getTabRunCount method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
int | tabForCoordinate(JTabbedPane a, int b, int c) Invokes the tabForCoordinate method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiTabbedPaneUI

public MultiTabbedPaneUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

tabForCoordinate

public int tabForCoordinate(JTabbedPane a,
                            int b,
                            int c)
Invokes the tabForCoordinate method on each UI handled by this object.

Specified by:
tabForCoordinate in class TabbedPaneUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

getTabBounds

public Rectangle getTabBounds(JTabbedPane a,
                              int b)
Invokes the getTabBounds method on each UI handled by this object.

Specified by:
getTabBounds in class TabbedPaneUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

getTabRunCount

public int getTabRunCount(JTabbedPane a)
Invokes the getTabRunCount method on each UI handled by this object.

Specified by:
getTabRunCount in class TabbedPaneUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiTableHeaderUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiTableHeaderUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TableHeaderUI
            extended by  javax.swing.plaf.multi.MultiTableHeaderUI

public class MultiTableHeaderUI
extends TableHeaderUI

A multiplexing UI used to combine TableHeaderUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiTableHeaderUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiTableHeaderUI

public MultiTableHeaderUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiTableUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiTableUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TableUI
            extended by  javax.swing.plaf.multi.MultiTableUI

public class MultiTableUI
extends TableUI

A multiplexing UI used to combine TableUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiTableUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiTableUI

public MultiTableUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiTextUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiTextUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TextUI
            extended by  javax.swing.plaf.multi.MultiTextUI

public class MultiTextUI
extends TextUI

A multiplexing UI used to combine TextUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiTextUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
void | damageRange(JTextComponent a, int b, int c) Invokes the damageRange method on each UI handled by this object.
void | damageRange(JTextComponent a, int b, int c, Position.Bias d, Position.Bias e) Invokes the damageRange method on each UI handled by this object.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
EditorKit | getEditorKit(JTextComponent a) Invokes the getEditorKit method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
int | getNextVisualPositionFrom(JTextComponent a, int b, Position.Bias c, int d, Position.Bias[] e) Invokes the getNextVisualPositionFrom method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
View | getRootView(JTextComponent a) Invokes the getRootView method on each UI handled by this object.
String | getToolTipText(JTextComponent a, Point b) Invokes the getToolTipText method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
Rectangle | modelToView(JTextComponent a, int b) Invokes the modelToView method on each UI handled by this object.
Rectangle | modelToView(JTextComponent a, int b, Position.Bias c) Invokes the modelToView method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
int | viewToModel(JTextComponent a, Point b) Invokes the viewToModel method on each UI handled by this object.
int | viewToModel(JTextComponent a, Point b, Position.Bias[] c) Invokes the viewToModel method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiTextUI

public MultiTextUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

getToolTipText

public String getToolTipText(JTextComponent a,
                             Point b)
Invokes the getToolTipText method on each UI handled by this object.

Overrides:
getToolTipText in class TextUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
Since:
1.4
See Also:
JTextComponent.getToolTipText(java.awt.event.MouseEvent)

modelToView

public Rectangle modelToView(JTextComponent a,
                             int b)
                      throws BadLocationException
Invokes the modelToView method on each UI handled by this object.

Specified by:
modelToView in class TextUI
b - the local location in the model to translate >= 0
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document

modelToView

public Rectangle modelToView(JTextComponent a,
                             int b,
                             Position.Bias c)
                      throws BadLocationException
Invokes the modelToView method on each UI handled by this object.

Specified by:
modelToView in class TextUI
b - the local location in the model to translate >= 0
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document

viewToModel

public int viewToModel(JTextComponent a,
                       Point b)
Invokes the viewToModel method on each UI handled by this object.

Specified by:
viewToModel in class TextUI
b - the location in the view to translate. This should be in the same coordinate system as the mouse events.
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

viewToModel

public int viewToModel(JTextComponent a,
                       Point b,
                       Position.Bias[] c)
Invokes the viewToModel method on each UI handled by this object.

Specified by:
viewToModel in class TextUI
b - the location in the view to translate. This should be in the same coordinate system as the mouse events.
c - filled in by this method to indicate whether the point given is closer to the previous or the next character in the model
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

getNextVisualPositionFrom

public int getNextVisualPositionFrom(JTextComponent a,
                                     int b,
                                     Position.Bias c,
                                     int d,
                                     Position.Bias[] e)
                              throws BadLocationException
Invokes the getNextVisualPositionFrom method on each UI handled by this object.

Specified by:
getNextVisualPositionFrom in class TextUI
Parameters:
a - the text component for which this UI is installed
b - the position to convert >= 0
c - the bias for the position
d - the direction from the current position that can be thought of as the arrow keys typically found on a keyboard. This may be SwingConstants.WEST, SwingConstants.EAST, SwingConstants.NORTH, or SwingConstants.SOUTH
e - an array to contain the bias for the returned position
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
Throws:
BadLocationException

damageRange

public void damageRange(JTextComponent a,
                        int b,
                        int c)
Invokes the damageRange method on each UI handled by this object.

Specified by:
damageRange in class TextUI
b - the beginning of the range >= 0
c - the end of the range >= p0

damageRange

public void damageRange(JTextComponent a,
                        int b,
                        int c,
                        Position.Bias d,
                        Position.Bias e)
Invokes the damageRange method on each UI handled by this object.

Specified by:
damageRange in class TextUI
b - the beginning of the range >= 0
c - the end of the range >= p0

getEditorKit

public EditorKit getEditorKit(JTextComponent a)
Invokes the getEditorKit method on each UI handled by this object.

Specified by:
getEditorKit in class TextUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

getRootView

public View getRootView(JTextComponent a)
Invokes the getRootView method on each UI handled by this object.

Specified by:
getRootView in class TextUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiToolBarUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiToolBarUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ToolBarUI
            extended by  javax.swing.plaf.multi.MultiToolBarUI

public class MultiToolBarUI
extends ToolBarUI

A multiplexing UI used to combine ToolBarUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiToolBarUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiToolBarUI

public MultiToolBarUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiToolTipUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiToolTipUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ToolTipUI
            extended by  javax.swing.plaf.multi.MultiToolTipUI

public class MultiToolTipUI
extends ToolTipUI

A multiplexing UI used to combine ToolTipUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiToolTipUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiToolTipUI

public MultiToolTipUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiTreeUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiTreeUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TreeUI
            extended by  javax.swing.plaf.multi.MultiTreeUI

public class MultiTreeUI
extends TreeUI

A multiplexing UI used to combine TreeUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiTreeUI()
Method Summary
void | cancelEditing(JTree a) Invokes the cancelEditing method on each UI handled by this object.
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
TreePath | getClosestPathForLocation(JTree a, int b, int c) Invokes the getClosestPathForLocation method on each UI handled by this object.
TreePath | getEditingPath(JTree a) Invokes the getEditingPath method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Rectangle | getPathBounds(JTree a, TreePath b) Invokes the getPathBounds method on each UI handled by this object.
TreePath | getPathForRow(JTree a, int b) Invokes the getPathForRow method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
int | getRowCount(JTree a) Invokes the getRowCount method on each UI handled by this object.
int | getRowForPath(JTree a, TreePath b) Invokes the getRowForPath method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
boolean | isEditing(JTree a) Invokes the isEditing method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | startEditingAtPath(JTree a, TreePath b) Invokes the startEditingAtPath method on each UI handled by this object.
boolean | stopEditing(JTree a) Invokes the stopEditing method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiTreeUI

public MultiTreeUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

getPathBounds

public Rectangle getPathBounds(JTree a,
                               TreePath b)
Invokes the getPathBounds method on each UI handled by this object.

Specified by:
getPathBounds in class TreeUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

getPathForRow

public TreePath getPathForRow(JTree a,
                              int b)
Invokes the getPathForRow method on each UI handled by this object.

Specified by:
getPathForRow in class TreeUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

getRowForPath

public int getRowForPath(JTree a,
                         TreePath b)
Invokes the getRowForPath method on each UI handled by this object.

Specified by:
getRowForPath in class TreeUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

getRowCount

public int getRowCount(JTree a)
Invokes the getRowCount method on each UI handled by this object.

Specified by:
getRowCount in class TreeUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

getClosestPathForLocation

public TreePath getClosestPathForLocation(JTree a,
                                          int b,
                                          int c)
Invokes the getClosestPathForLocation method on each UI handled by this object.

Specified by:
getClosestPathForLocation in class TreeUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

isEditing

public boolean isEditing(JTree a)
Invokes the isEditing method on each UI handled by this object.

Specified by:
isEditing in class TreeUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

stopEditing

public boolean stopEditing(JTree a)
Invokes the stopEditing method on each UI handled by this object.

Specified by:
stopEditing in class TreeUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

cancelEditing

public void cancelEditing(JTree a)
Invokes the cancelEditing method on each UI handled by this object.

Specified by:
cancelEditing in class TreeUI

startEditingAtPath

public void startEditingAtPath(JTree a,
                               TreePath b)
Invokes the startEditingAtPath method on each UI handled by this object.

Specified by:
startEditingAtPath in class TreeUI

getEditingPath

public TreePath getEditingPath(JTree a)
Invokes the getEditingPath method on each UI handled by this object.

Specified by:
getEditingPath in class TreeUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultiViewportUI

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.multi
Class MultiViewportUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ViewportUI
            extended by  javax.swing.plaf.multi.MultiViewportUI

public class MultiViewportUI
extends ViewportUI

A multiplexing UI used to combine ViewportUIs.

This file was automatically generated by AutoMulti.

Field Summary
protected  Vector uis
The vector containing the real UIs.
Constructor Summary
MultiViewportUI()
Method Summary
boolean | contains(JComponent a, int b, int c) Invokes the contains method on each UI handled by this object.
static ComponentUI | createUI(JComponent a) Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI.
Accessible | getAccessibleChild(JComponent a, int b) Invokes the getAccessibleChild method on each UI handled by this object.
int | getAccessibleChildrenCount(JComponent a) Invokes the getAccessibleChildrenCount method on each UI handled by this object.
Dimension | getMaximumSize(JComponent a) Invokes the getMaximumSize method on each UI handled by this object.
Dimension | getMinimumSize(JComponent a) Invokes the getMinimumSize method on each UI handled by this object.
Dimension | getPreferredSize(JComponent a) Invokes the getPreferredSize method on each UI handled by this object.
ComponentUI[] | getUIs() Returns the list of UIs associated with this multiplexing UI.
void | installUI(JComponent a) Invokes the installUI method on each UI handled by this object.
void | paint(Graphics a, JComponent b) Invokes the paint method on each UI handled by this object.
void | uninstallUI(JComponent a) Invokes the uninstallUI method on each UI handled by this object.
void | update(Graphics a, JComponent b) Invokes the update method on each UI handled by this object.
Methods inherited from class javax.swing.plaf.ComponentUI
getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

uis

protected Vector uis
The vector containing the real UIs. This is populated in the call to createUI, and can be obtained by calling the getUIs method. The first element is guaranteed to be the real UI obtained from the default look and feel.

Constructor Detail

MultiViewportUI

public MultiViewportUI()
Method Detail

getUIs

public ComponentUI[] getUIs()
Returns the list of UIs associated with this multiplexing UI. This allows processing of the UIs by an application aware of multiplexing UIs on components.

contains

public boolean contains(JComponent a,
                        int b,
                        int c)
Invokes the contains method on each UI handled by this object.

Overrides:
contains in class ComponentUI
Parameters:
a - the component where the x,y location is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
b - the x coordinate of the point
c - the y coordinate of the point
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.contains(int, int), Component.contains(int, int)

update

public void update(Graphics a,
                   JComponent b)
Invokes the update method on each UI handled by this object.

Overrides:
update in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.paint(java.awt.Graphics, javax.swing.JComponent), JComponent.paintComponent(java.awt.Graphics)

createUI

public static ComponentUI createUI(JComponent a)
Returns a multiplexing UI instance if any of the auxiliary LookAndFeels supports this UI. Otherwise, just returns the UI object obtained from the default LookAndFeel.

installUI

public void installUI(JComponent a)
Invokes the installUI method on each UI handled by this object.

Overrides:
installUI in class ComponentUI
Parameters:
a - the component where this UI delegate is being installed
See Also:
ComponentUI.uninstallUI(javax.swing.JComponent),
JComponent.setUI(javax.swing.plaf.ComponentUI),
JComponent.updateUI()

uninstallUI

public void uninstallUI(JComponent a)
Invokes the uninstallUI method on each UI handled by this object.

Overrides:
uninstallUI in class ComponentUI
Parameters:
a - the component from which this UI delegate is being removed; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.installUI(javax.swing.JComponent), JComponent.updateUI()

paint

public void paint(Graphics a,
                  JComponent b)
Invokes the paint method on each UI handled by this object.

Overrides:
paint in class ComponentUI
Parameters:
a - the Graphics context in which to paint
b - the component being painted; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
See Also:
ComponentUI.update(java.awt.Graphics, javax.swing.JComponent)

getPreferredSize

public Dimension getPreferredSize(JComponent a)
Invokes the getPreferredSize method on each UI handled by this object.

Overrides:
getPreferredSize in class ComponentUI
Parameters:
a - the component whose preferred size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getPreferredSize(), LayoutManager.preferredLayoutSize(java.awt.Container)

getMinimumSize

public Dimension getMinimumSize(JComponent a)
Invokes the getMinimumSize method on each UI handled by this object.

Overrides:
getMinimumSize in class ComponentUI
Parameters:
a - the component whose minimum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMinimumSize(),
LayoutManager.minimumLayoutSize(java.awt.Container),
ComponentUI.getPreferredSize(javax.swing.JComponent)

getMaximumSize

public Dimension getMaximumSize(JComponent a)
Invokes the getMaximumSize method on each UI handled by this object.

Overrides:
getMaximumSize in class ComponentUI
Parameters:
a - the component whose maximum size is being queried; this argument is often ignored, but might be used if the UI object is stateless and shared by multiple components
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
JComponent.getMaximumSize(), LayoutManager2.maximumLayoutSize(java.awt.Container)

getAccessibleChildrenCount

public int getAccessibleChildrenCount(JComponent a)
Invokes the getAccessibleChildrenCount method on each UI handled by this object.

Overrides:
getAccessibleChildrenCount in class ComponentUI
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChild(javax.swing.JComponent, int)

getAccessibleChild

public Accessible getAccessibleChild(JComponent a,
                                     int b)
Invokes the getAccessibleChild method on each UI handled by this object.

Overrides:
getAccessibleChild in class ComponentUI
b - zero-based index of child
Returns:
the value obtained from the first UI, which is the UI obtained from the default LookAndFeel
See Also:
ComponentUI.getAccessibleChildrenCount(javax.swing.JComponent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


OptionPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class OptionPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.OptionPaneUI
Direct Known Subclasses:
BasicOptionPaneUI, MultiOptionPaneUI
public abstract class OptionPaneUI
extends ComponentUI

Pluggable look and feel interface for JOptionPane.

Constructor Summary
OptionPaneUI()
Method Summary
abstract boolean | containsCustomComponents(JOptionPane op) Returns true if the user has supplied instances of Component for either the options or message.
abstract void | selectInitialValue(JOptionPane op) Requests the component representing the default value to have focus.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

OptionPaneUI

public OptionPaneUI()
Method Detail

selectInitialValue

public abstract void selectInitialValue(JOptionPane op)
Requests the component representing the default value to have focus.

containsCustomComponents

public abstract boolean containsCustomComponents(JOptionPane op)
Returns true if the user has supplied instances of Component for either the options or message.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PanelUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class PanelUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.PanelUI
Direct Known Subclasses:
BasicPanelUI, MultiPanelUI
public abstract class PanelUI
extends ComponentUI

Pluggable look and feel interface for Panel.

Constructor Summary
PanelUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PanelUI

public PanelUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PopupMenuUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class PopupMenuUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.PopupMenuUI
Direct Known Subclasses:
BasicPopupMenuUI, MultiPopupMenuUI
public abstract class PopupMenuUI
extends ComponentUI

Pluggable look and feel interface for JPopupMenu.

Constructor Summary
PopupMenuUI()
Method Summary
Popup | getPopup(JPopupMenu popup, int x, int y) Returns the Popup that will be responsible for displaying the JPopupMenu.
boolean | isPopupTrigger(MouseEvent e)
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PopupMenuUI

public PopupMenuUI()
Method Detail

isPopupTrigger

public boolean isPopupTrigger(MouseEvent e)
Since:
1.3

getPopup

public Popup getPopup(JPopupMenu popup,
                      int x,
                      int y)
Returns the Popup that will be responsible for displaying the JPopupMenu.

Parameters:
popup - JPopupMenu requesting Popup
x - Screen x location Popup is to be shown at
y - Screen y location Popup is to be shown at.
Returns:
Popup that will show the JPopupMenu
Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ProgressBarUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class ProgressBarUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ProgressBarUI
Direct Known Subclasses:
BasicProgressBarUI, MultiProgressBarUI
public abstract class ProgressBarUI
extends ComponentUI

Pluggable look and feel interface for JProgressBar.

Constructor Summary
ProgressBarUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ProgressBarUI

public ProgressBarUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RootPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class RootPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.RootPaneUI
Direct Known Subclasses:
BasicRootPaneUI, MultiRootPaneUI
public abstract class RootPaneUI
extends ComponentUI

Pluggable look and feel interface for JRootPane.

Since:
1.3

Constructor Summary
RootPaneUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RootPaneUI

public RootPaneUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ScrollBarUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class ScrollBarUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ScrollBarUI
Direct Known Subclasses:
BasicScrollBarUI, MultiScrollBarUI
public abstract class ScrollBarUI
extends ComponentUI

Pluggable look and feel interface for JScrollBar.

Constructor Summary
ScrollBarUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ScrollBarUI

public ScrollBarUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ScrollPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class ScrollPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ScrollPaneUI
Direct Known Subclasses:
BasicScrollPaneUI, MultiScrollPaneUI
public abstract class ScrollPaneUI
extends ComponentUI

Pluggable look and feel interface for JScrollPane.

Constructor Summary
ScrollPaneUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ScrollPaneUI

public ScrollPaneUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SeparatorUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class SeparatorUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SeparatorUI
Direct Known Subclasses:
BasicSeparatorUI, MultiSeparatorUI
public abstract class SeparatorUI
extends ComponentUI

Pluggable look and feel interface for JSeparator.

Constructor Summary
SeparatorUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SeparatorUI

public SeparatorUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SliderUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class SliderUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SliderUI
Direct Known Subclasses:
BasicSliderUI, MultiSliderUI
public abstract class SliderUI
extends ComponentUI

Pluggable look and feel interface for JSlider.

Constructor Summary
SliderUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SliderUI

public SliderUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SpinnerUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class SpinnerUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SpinnerUI
Direct Known Subclasses:
BasicSpinnerUI, MultiSpinnerUI
public abstract class SpinnerUI
extends ComponentUI

Pluggable look and feel interface for JSpinner

Since:
1.4

Constructor Summary
SpinnerUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SpinnerUI

public SpinnerUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SplitPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class SplitPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.SplitPaneUI
Direct Known Subclasses:
BasicSplitPaneUI, MultiSplitPaneUI
public abstract class SplitPaneUI
extends ComponentUI

Pluggable look and feel interface for JSplitPane.

Constructor Summary
SplitPaneUI()
Method Summary
abstract void | finishedPaintingChildren(JSplitPane jc, Graphics g) Messaged after the JSplitPane the receiver is providing the look and feel for paints its children.
abstract int | getDividerLocation(JSplitPane jc) Returns the location of the divider.
abstract int | getMaximumDividerLocation(JSplitPane jc) Returns the maximum possible location of the divider.
abstract int | getMinimumDividerLocation(JSplitPane jc) Returns the minimum possible location of the divider.
abstract void | resetToPreferredSizes(JSplitPane jc) Messaged to relayout the JSplitPane based on the preferred size of the children components.
abstract void | setDividerLocation(JSplitPane jc, int location) Sets the location of the divider to location.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SplitPaneUI

public SplitPaneUI()
Method Detail

resetToPreferredSizes

public abstract void resetToPreferredSizes(JSplitPane jc)
Messaged to relayout the JSplitPane based on the preferred size of the children components.

setDividerLocation

public abstract void setDividerLocation(JSplitPane jc,
                                        int location)
Sets the location of the divider to location.

getDividerLocation

public abstract int getDividerLocation(JSplitPane jc)
Returns the location of the divider.

getMinimumDividerLocation

public abstract int getMinimumDividerLocation(JSplitPane jc)
Returns the minimum possible location of the divider.

getMaximumDividerLocation

public abstract int getMaximumDividerLocation(JSplitPane jc)
Returns the maximum possible location of the divider.

finishedPaintingChildren

public abstract void finishedPaintingChildren(JSplitPane jc,
                                              Graphics g)
Messaged after the JSplitPane the receiver is providing the look and feel for paints its children.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


synth

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.swing.plaf.synth

Synth is a skinnable look and feel in which all painting is delegated.

See:
Description

Interface Summary
SynthConstants Constants used by Synth.

Class Summary
ColorType | A typesafe enumeration of colors that can be fetched from a style.
Region | A distinct rendering area of a Swing component.
SynthContext | An immutable transient object containing contextual information about a Region.
SynthGraphicsUtils | Wrapper for primitive graphics calls.
SynthLookAndFeel | SynthLookAndFeel provides the basis for creating a customized look and feel.
SynthPainter | SynthPainter is used for painting portions of JComponents.
SynthStyle | SynthStyle is a set of style properties.
SynthStyleFactory | Factory used for obtaining SynthStyles.

Package javax.swing.plaf.synth Description

Synth is a skinnable look and feel in which all painting is delegated. Synth does not provide a default look. In order to use Synth you need to specify a file, or provide a SynthStyleFactory. Both configuration options require an understanding of the synth architecture, which is described below, as well as an understanding of Swing's architecture.

Unless otherwise specified null is not a legal value to any of the methods defined in the synth package and if passed in will result in a NullPointerException.

Synth

Each ComponentUI implementation in Synth associates itself with one SynthStyle per Region, most Components only have one Region and therefor only one SynthStyle. SynthStyle is used to access all style related properties: fonts, colors and other Component properties. In addition SynthStyles are used to obtain SynthPainters for painting the background, border, focus and other portions of a Component. The ComponentUIs obtain SynthStyles from a SynthStyleFactory. A SynthStyleFactory can be provided directly by way of SynthLookAndFeel.setStyleFactory(javax.swing.plaf.synth.SynthStyleFactory), or indirectly by way of SynthLookAndFeel.load(java.io.InputStream, java.lang.Class). The following example uses the SynthLookAndFeel.load() method to configure a SynthLookAndFeel and sets it as the current look and feel:

  SynthLookAndFeel laf = new SynthLookAndFeel();
  laf.load(MyClass.class.getResourceAsStream("laf.xml"), MyClass.class);
  UIManager.setLookAndFeel(laf);

Many JComponents are broken down into smaller pieces and identified by the type safe enumeration in Region. For example, a JTabbedPane consists of a Region for the JTabbedPane (Region.TABBED_PANE), the content area (Region.TABBED_PANE_CONTENT), the area behind the tabs (Region.TABBED_PANE_TAB_AREA), and the tabs (Region.TABBED_PANE_TAB). Each Region of each JComponent will have a SynthStyle. This allows you to customize individual pieces of each region of each JComponent.

Many of the Synth methods take a SynthContext. This is used to provide information about the current Component and includes: the SynthStyle associated with the current Region, the state of the Component as a bitmask (refer to SynthConstants for the valid states), and a Region identifying the portion of the Component being painted.

All text rendering by non-JTextComponents is delegated to a SynthGraphicsUtils, which is obtained using the SynthStyle method SynthStyle.getGraphicsUtils(javax.swing.plaf.synth.SynthContext). You can customize text rendering by supplying your own SynthGraphicsUtils.

Notes on specific components

JTree

Synth provides a region for the cells of a tree: Region.TREE_CELL. To specify the colors of the renderer you'll want to provide a style for the TREE_CELL region. The following illustrates this:

  <style id="treeCellStyle">
    <opaque value="TRUE"/>
    <state>
      <color value="WHITE" type="TEXT_FOREGROUND"/>
      <color value="RED" type="TEXT_BACKGROUND"/>
    </state>
    <state value="SELECTED">
      <color value="RED" type="TEXT_FOREGROUND"/>
      <color value="WHITE" type="BACKGROUND"/>
    </state>
  </style>
  <bind style="treeCellStyle" type="region" key="TreeCell"/>

This specifies a color combination of red on white, when selected, and white on red when not selected. To see the background you need to specify that labels are not opaque. The following XML fragment does that:

  <style id="labelStyle">
    <opaque value="FALSE"/>
  </style>
  <bind style="labelStyle" type="region" key="Label"/>

JList and JTable

The colors that the renderers for JList and JTable use are specified by way of the list and table Regions. The following XML fragment illustrates how to specify red on white, when selected, and white on red when not selected:

  <style id="style">
    <opaque value="TRUE"/>
    <state>
      <color value="WHITE" type="TEXT_FOREGROUND"/>
      <color value="RED" type="TEXT_BACKGROUND"/>
      <color value="RED" type="BACKGROUND"/>
    </state>
    <state value="SELECTED">
      <color value="RED" type="TEXT_FOREGROUND"/>
      <color value="WHITE" type="TEXT_BACKGROUND"/>
    </state>
  </style>
  <bind style="style" type="region" key="Table"/>
  <bind style="style" type="region" key="List"/>

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.swing.plaf.synth Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.swing.plaf.synth

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.swing.plaf.synth.ColorType
    • javax.swing.LookAndFeel
      • javax.swing.plaf.basic.BasicLookAndFeel (implements java.io.Serializable)
        • javax.swing.plaf.synth.SynthLookAndFeel
    • javax.swing.plaf.synth.Region
    • javax.swing.plaf.synth.SynthContext
    • javax.swing.plaf.synth.SynthGraphicsUtils
    • javax.swing.plaf.synth.SynthPainter
    • javax.swing.plaf.synth.SynthStyle
    • javax.swing.plaf.synth.SynthStyleFactory

Interface Hierarchy

  • javax.swing.plaf.synth.SynthConstants
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.swing.plaf.synth

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.swing.plaf.synth

Packages that use javax.swing.plaf.synth
javax.swing.plaf.synth Synth is a skinnable look and feel in which all painting is delegated.

Classes in javax.swing.plaf.synth used by javax.swing.plaf.synth
ColorType
A typesafe enumeration of colors that can be fetched from a style.
Region
A distinct rendering area of a Swing component.
SynthContext
An immutable transient object containing contextual information about a Region.
SynthGraphicsUtils
Wrapper for primitive graphics calls.
SynthPainter
SynthPainter is used for painting portions of JComponents.
SynthStyle
SynthStyle is a set of style properties.
SynthStyleFactory
Factory used for obtaining SynthStyles.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.synth.ColorType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.synth.ColorType

Packages that use ColorType
javax.swing.plaf.synth Synth is a skinnable look and feel in which all painting is delegated.

Uses of ColorType in javax.swing.plaf.synth

Fields in javax.swing.plaf.synth declared as ColorType
static ColorType | ColorType.BACKGROUND ColorType for the background of a region.
static ColorType | ColorType.FOCUS ColorType for the focus.
static ColorType | ColorType.FOREGROUND ColorType for the foreground of a region.
static ColorType | ColorType.TEXT_BACKGROUND ColorType for the background of a region.
static ColorType | ColorType.TEXT_FOREGROUND ColorType for the foreground of a region.

Methods in javax.swing.plaf.synth with parameters of type ColorType
Color | SynthStyle.getColor(SynthContext context, ColorType type) Returns the color for the specified state.
protected abstract Color | SynthStyle.getColorForState(SynthContext context, ColorType type) Returns the color for the specified state.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.synth.Region

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.synth.Region

Packages that use Region
javax.swing.plaf.synth Synth is a skinnable look and feel in which all painting is delegated.

Uses of Region in javax.swing.plaf.synth

Fields in javax.swing.plaf.synth declared as Region
static Region | Region.ARROW_BUTTON ArrowButton's are special types of buttons that also render a directional indicator, typically an arrow.
static Region | Region.BUTTON Button region.
static Region | Region.CHECK_BOX CheckBox region.
static Region | Region.CHECK_BOX_MENU_ITEM CheckBoxMenuItem region.
static Region | Region.COLOR_CHOOSER ColorChooser region.
static Region | Region.COMBO_BOX ComboBox region.
static Region | Region.DESKTOP_ICON DesktopIcon region.
static Region | Region.DESKTOP_PANE DesktopPane region.
static Region | Region.EDITOR_PANE EditorPane region.
static Region | Region.FILE_CHOOSER FileChooser region.
static Region | Region.FORMATTED_TEXT_FIELD FormattedTextField region.
static Region | Region.INTERNAL_FRAME InternalFrame region.
static Region | Region.INTERNAL_FRAME_TITLE_PANE TitlePane of an InternalFrame.
static Region | Region.LABEL Label region.
static Region | Region.LIST List region.
static Region | Region.MENU Menu region.
static Region | Region.MENU_BAR MenuBar region.
static Region | Region.MENU_ITEM MenuItem region.
static Region | Region.MENU_ITEM_ACCELERATOR Accelerator region of a MenuItem.
static Region | Region.OPTION_PANE OptionPane region.
static Region | Region.PANEL Panel region.
static Region | Region.PASSWORD_FIELD PasswordField region.
static Region | Region.POPUP_MENU PopupMenu region.
static Region | Region.POPUP_MENU_SEPARATOR PopupMenuSeparator region.
static Region | Region.PROGRESS_BAR ProgressBar region.
static Region | Region.RADIO_BUTTON RadioButton region.
static Region | Region.RADIO_BUTTON_MENU_ITEM RegionButtonMenuItem region.
static Region | Region.ROOT_PANE RootPane region.
static Region | Region.SCROLL_BAR ScrollBar region.
static Region | Region.SCROLL_BAR_THUMB Thumb of the ScrollBar.
static Region | Region.SCROLL_BAR_TRACK Track of the ScrollBar.
static Region | Region.SCROLL_PANE ScrollPane region.
static Region | Region.SEPARATOR Separator region.
static Region | Region.SLIDER Slider region.
static Region | Region.SLIDER_THUMB Thumb of the Slider.
static Region | Region.SLIDER_TRACK Track of the Slider.
static Region | Region.SPINNER Spinner region.
static Region | Region.SPLIT_PANE SplitPane region.
static Region | Region.SPLIT_PANE_DIVIDER Divider of the SplitPane.
static Region | Region.TABBED_PANE TabbedPane region.
static Region | Region.TABBED_PANE_CONTENT Region of a TabbedPane containing the content.
static Region | Region.TABBED_PANE_TAB Region of a TabbedPane for one tab.
static Region | Region.TABBED_PANE_TAB_AREA Region of a TabbedPane containing the tabs.
static Region | Region.TABLE Table region.
static Region | Region.TABLE_HEADER TableHeader region.
static Region | Region.TEXT_AREA TextArea region.
static Region | Region.TEXT_FIELD TextField region.
static Region | Region.TEXT_PANE TextPane region.
static Region | Region.TOGGLE_BUTTON ToggleButton region.
static Region | Region.TOOL_BAR ToolBar region.
static Region | Region.TOOL_BAR_CONTENT Region of the ToolBar containing the content.
static Region | Region.TOOL_BAR_DRAG_WINDOW Region for the Window containing the ToolBar.
static Region | Region.TOOL_BAR_SEPARATOR ToolBar separator region.
static Region | Region.TOOL_TIP ToolTip region.
static Region | Region.TREE Tree region.
static Region | Region.TREE_CELL Region of the Tree for one cell.
static Region | Region.VIEWPORT Viewport region.

Methods in javax.swing.plaf.synth that return Region
Region | SynthContext.getRegion() Returns the Region identifying this state.
static Region | SynthLookAndFeel.getRegion(JComponent c) Returns the Region for the JComponent c.

Methods in javax.swing.plaf.synth with parameters of type Region
abstract SynthStyle | SynthStyleFactory.getStyle(JComponent c, Region id) Returns the style for the specified Component.
static SynthStyle | SynthLookAndFeel.getStyle(JComponent c, Region region) Gets a SynthStyle for the specified region of the specified component.

Constructors in javax.swing.plaf.synth with parameters of type Region
SynthContext(JComponent component, Region region, SynthStyle style, int state)
Creates a SynthContext with the specified values.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.synth.SynthContext

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.synth.SynthContext

Packages that use SynthContext
javax.swing.plaf.synth Synth is a skinnable look and feel in which all painting is delegated.

Uses of SynthContext in javax.swing.plaf.synth

Methods in javax.swing.plaf.synth with parameters of type SynthContext
int | SynthGraphicsUtils.computeStringWidth(SynthContext ss, Font font, FontMetrics metrics, String text) Returns the size of the passed in string.
void | SynthGraphicsUtils.drawLine(SynthContext context, Object paintKey, Graphics g, int x1, int y1, int x2, int y2) Draws a line between the two end points.
void | SynthGraphicsUtils.drawLine(SynthContext context, Object paintKey, Graphics g, int x1, int y1, int x2, int y2, Object styleKey) Draws a line between the two end points.
Object | SynthStyle.get(SynthContext context, Object key) Getter for a region specific style property.
boolean | SynthStyle.getBoolean(SynthContext context, Object key, boolean defaultValue) Convenience method to get a specific style property whose value is an Boolean.
Color | SynthStyle.getColor(SynthContext context, ColorType type) Returns the color for the specified state.
protected abstract Color | SynthStyle.getColorForState(SynthContext context, ColorType type) Returns the color for the specified state.
Font | SynthStyle.getFont(SynthContext context) Returns the Font for the specified state.
protected abstract Font | SynthStyle.getFontForState(SynthContext context) Returns the font for the specified state.
SynthGraphicsUtils | SynthStyle.getGraphicsUtils(SynthContext context) Returns the SynthGraphicUtils for the specified context.
Icon | SynthStyle.getIcon(SynthContext context, Object key) Convenience method to get a specific style property whose value is an Icon.
Insets | SynthStyle.getInsets(SynthContext context, Insets insets) Returns the Insets that are used to calculate sizing information.
int | SynthStyle.getInt(SynthContext context, Object key, int defaultValue) Convenience method to get a specific style property whose value is a Number.
int | SynthGraphicsUtils.getMaximumCharHeight(SynthContext context) Returns the maximum height of the the Font from the passed in SynthContext.
Dimension | SynthGraphicsUtils.getMaximumSize(SynthContext ss, Font font, String text, Icon icon, int hAlign, int vAlign, int hTextPosition, int vTextPosition, int iconTextGap, int mnemonicIndex) Returns the maximum size needed to properly render an icon and text.
Dimension | SynthGraphicsUtils.getMinimumSize(SynthContext ss, Font font, String text, Icon icon, int hAlign, int vAlign, int hTextPosition, int vTextPosition, int iconTextGap, int mnemonicIndex) Returns the minimum size needed to properly render an icon and text.
SynthPainter | SynthStyle.getPainter(SynthContext context) Returns the SynthPainter that will be used for painting.
Dimension | SynthGraphicsUtils.getPreferredSize(SynthContext ss, Font font, String text, Icon icon, int hAlign, int vAlign, int hTextPosition, int vTextPosition, int iconTextGap, int mnemonicIndex) Returns the preferred size needed to properly render an icon and text.
String | SynthStyle.getString(SynthContext context, Object key, String defaultValue) Convenience method to get a specific style property whose value is a String.
void | SynthStyle.installDefaults(SynthContext context) Installs the necessary state from this Style on the JComponent from context.
boolean | SynthStyle.isOpaque(SynthContext context) Returns true if the region is opaque.
String | SynthGraphicsUtils.layoutText(SynthContext ss, FontMetrics fm, String text, Icon icon, int hAlign, int vAlign, int hTextPosition, int vTextPosition, Rectangle viewR, Rectangle iconR, Rectangle textR, int iconTextGap) Lays out text and an icon returning, by reference, the location to place the icon and text.
void | SynthPainter.paintArrowButtonBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of an arrow button.
void | SynthPainter.paintArrowButtonBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of an arrow button.
void | SynthPainter.paintArrowButtonForeground(SynthContext context, Graphics g, int x, int y, int w, int h, int direction) Paints the foreground of an arrow button.
void | SynthPainter.paintButtonBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a button.
void | SynthPainter.paintButtonBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a button.
void | SynthPainter.paintCheckBoxBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a check box.
void | SynthPainter.paintCheckBoxBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a check box.
void | SynthPainter.paintCheckBoxMenuItemBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a check box menu item.
void | SynthPainter.paintCheckBoxMenuItemBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a check box menu item.
void | SynthPainter.paintColorChooserBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a color chooser.
void | SynthPainter.paintColorChooserBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a color chooser.
void | SynthPainter.paintComboBoxBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a combo box.
void | SynthPainter.paintComboBoxBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a combo box.
void | SynthPainter.paintDesktopIconBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a desktop icon.
void | SynthPainter.paintDesktopIconBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a desktop icon.
void | SynthPainter.paintDesktopPaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a desktop pane.
void | SynthPainter.paintDesktopPaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a desktop pane.
void | SynthPainter.paintEditorPaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of an editor pane.
void | SynthPainter.paintEditorPaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of an editor pane.
void | SynthPainter.paintFileChooserBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a file chooser.
void | SynthPainter.paintFileChooserBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a file chooser.
void | SynthPainter.paintFormattedTextFieldBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a formatted text field.
void | SynthPainter.paintFormattedTextFieldBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a formatted text field.
void | SynthPainter.paintInternalFrameBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of an internal frame.
void | SynthPainter.paintInternalFrameBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of an internal frame.
void | SynthPainter.paintInternalFrameTitlePaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of an internal frame title pane.
void | SynthPainter.paintInternalFrameTitlePaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of an internal frame title pane.
void | SynthPainter.paintLabelBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a label.
void | SynthPainter.paintLabelBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a label.
void | SynthPainter.paintListBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a list.
void | SynthPainter.paintListBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a list.
void | SynthPainter.paintMenuBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a menu.
void | SynthPainter.paintMenuBarBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a menu bar.
void | SynthPainter.paintMenuBarBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a menu bar.
void | SynthPainter.paintMenuBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a menu.
void | SynthPainter.paintMenuItemBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a menu item.
void | SynthPainter.paintMenuItemBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a menu item.
void | SynthPainter.paintOptionPaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of an option pane.
void | SynthPainter.paintOptionPaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of an option pane.
void | SynthPainter.paintPanelBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a panel.
void | SynthPainter.paintPanelBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a panel.
void | SynthPainter.paintPasswordFieldBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a password field.
void | SynthPainter.paintPasswordFieldBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a password field.
void | SynthPainter.paintPopupMenuBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a popup menu.
void | SynthPainter.paintPopupMenuBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a popup menu.
void | SynthPainter.paintProgressBarBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a progress bar.
void | SynthPainter.paintProgressBarBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of a progress bar.
void | SynthPainter.paintProgressBarBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a progress bar.
void | SynthPainter.paintProgressBarBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of a progress bar.
void | SynthPainter.paintProgressBarForeground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the foreground of a progress bar.
void | SynthPainter.paintRadioButtonBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a radio button.
void | SynthPainter.paintRadioButtonBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a radio button.
void | SynthPainter.paintRadioButtonMenuItemBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a radio button menu item.
void | SynthPainter.paintRadioButtonMenuItemBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a radio button menu item.
void | SynthPainter.paintRootPaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a root pane.
void | SynthPainter.paintRootPaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a root pane.
void | SynthPainter.paintScrollBarBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a scrollbar.
void | SynthPainter.paintScrollBarBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of a scrollbar.
void | SynthPainter.paintScrollBarBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a scrollbar.
void | SynthPainter.paintScrollBarBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of a scrollbar.
void | SynthPainter.paintScrollBarThumbBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of the thumb of a scrollbar.
void | SynthPainter.paintScrollBarThumbBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of the thumb of a scrollbar.
void | SynthPainter.paintScrollBarTrackBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the track of a scrollbar.
void | SynthPainter.paintScrollBarTrackBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of the track of a scrollbar.
void | SynthPainter.paintScrollBarTrackBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of the track of a scrollbar.
void | SynthPainter.paintScrollBarTrackBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of the track of a scrollbar.
void | SynthPainter.paintScrollPaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a scroll pane.
void | SynthPainter.paintScrollPaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a scroll pane.
void | SynthPainter.paintSeparatorBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a separator.
void | SynthPainter.paintSeparatorBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of a separator.
void | SynthPainter.paintSeparatorBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a separator.
void | SynthPainter.paintSeparatorBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of a separator.
void | SynthPainter.paintSeparatorForeground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the foreground of a separator.
void | SynthPainter.paintSliderBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a slider.
void | SynthPainter.paintSliderBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of a slider.
void | SynthPainter.paintSliderBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a slider.
void | SynthPainter.paintSliderBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of a slider.
void | SynthPainter.paintSliderThumbBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of the thumb of a slider.
void | SynthPainter.paintSliderThumbBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of the thumb of a slider.
void | SynthPainter.paintSliderTrackBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the track of a slider.
void | SynthPainter.paintSliderTrackBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of the track of a slider.
void | SynthPainter.paintSliderTrackBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of the track of a slider.
void | SynthPainter.paintSliderTrackBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of the track of a slider.
void | SynthPainter.paintSpinnerBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a spinner.
void | SynthPainter.paintSpinnerBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a spinner.
void | SynthPainter.paintSplitPaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a split pane.
void | SynthPainter.paintSplitPaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a split pane.
void | SynthPainter.paintSplitPaneDividerBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the divider of a split pane.
void | SynthPainter.paintSplitPaneDividerBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of the divider of a split pane.
void | SynthPainter.paintSplitPaneDividerForeground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the foreground of the divider of a split pane.
void | SynthPainter.paintSplitPaneDragDivider(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the divider, when the user is dragging the divider, of a split pane.
void | SynthPainter.paintTabbedPaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a tabbed pane.
void | SynthPainter.paintTabbedPaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a tabbed pane.
void | SynthPainter.paintTabbedPaneContentBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the area that contains the content of the selected tab of a tabbed pane.
void | SynthPainter.paintTabbedPaneContentBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of the area that contains the content of the selected tab of a tabbed pane.
void | SynthPainter.paintTabbedPaneTabAreaBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the area behind the tabs of a tabbed pane.
void | SynthPainter.paintTabbedPaneTabAreaBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of the area behind the tabs of a tabbed pane.
void | SynthPainter.paintTabbedPaneTabAreaBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of the area behind the tabs of a tabbed pane.
void | SynthPainter.paintTabbedPaneTabAreaBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of the area behind the tabs of a tabbed pane.
void | SynthPainter.paintTabbedPaneTabBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int tabIndex) Paints the background of a tab of a tabbed pane.
void | SynthPainter.paintTabbedPaneTabBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int tabIndex, int orientation) Paints the background of a tab of a tabbed pane.
void | SynthPainter.paintTabbedPaneTabBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int tabIndex) Paints the border of a tab of a tabbed pane.
void | SynthPainter.paintTabbedPaneTabBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int tabIndex, int orientation) Paints the border of a tab of a tabbed pane.
void | SynthPainter.paintTableBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a table.
void | SynthPainter.paintTableBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a table.
void | SynthPainter.paintTableHeaderBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the header of a table.
void | SynthPainter.paintTableHeaderBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of the header of a table.
void | SynthGraphicsUtils.paintText(SynthContext ss, Graphics g, String text, Icon icon, int hAlign, int vAlign, int hTextPosition, int vTextPosition, int iconTextGap, int mnemonicIndex, int textOffset) Paints an icon and text.
void | SynthGraphicsUtils.paintText(SynthContext ss, Graphics g, String text, int x, int y, int mnemonicIndex) Paints text at the specified location.
void | SynthGraphicsUtils.paintText(SynthContext ss, Graphics g, String text, Rectangle bounds, int mnemonicIndex) Paints text at the specified location.
void | SynthPainter.paintTextAreaBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a text area.
void | SynthPainter.paintTextAreaBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a text area.
void | SynthPainter.paintTextFieldBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a text field.
void | SynthPainter.paintTextFieldBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a text field.
void | SynthPainter.paintTextPaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a text pane.
void | SynthPainter.paintTextPaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a text pane.
void | SynthPainter.paintToggleButtonBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a toggle button.
void | SynthPainter.paintToggleButtonBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a toggle button.
void | SynthPainter.paintToolBarBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a tool bar.
void | SynthPainter.paintToolBarBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of a tool bar.
void | SynthPainter.paintToolBarBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a tool bar.
void | SynthPainter.paintToolBarBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of a tool bar.
void | SynthPainter.paintToolBarContentBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the tool bar's content area.
void | SynthPainter.paintToolBarContentBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of the tool bar's content area.
void | SynthPainter.paintToolBarContentBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of the content area of a tool bar.
void | SynthPainter.paintToolBarContentBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of the content area of a tool bar.
void | SynthPainter.paintToolBarDragWindowBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the window containing the tool bar when it has been detached from its primary frame.
void | SynthPainter.paintToolBarDragWindowBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of the window containing the tool bar when it has been detached from its primary frame.
void | SynthPainter.paintToolBarDragWindowBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of the window containing the tool bar when it has been detached from it's primary frame.
void | SynthPainter.paintToolBarDragWindowBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of the window containing the tool bar when it has been detached from it's primary frame.
void | SynthPainter.paintToolTipBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a tool tip.
void | SynthPainter.paintToolTipBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a tool tip.
void | SynthPainter.paintTreeBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a tree.
void | SynthPainter.paintTreeBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a tree.
void | SynthPainter.paintTreeCellBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the row containing a cell in a tree.
void | SynthPainter.paintTreeCellBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of the row containing a cell in a tree.
void | SynthPainter.paintTreeCellFocus(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the focus indicator for a cell in a tree when it has focus.
void | SynthPainter.paintViewportBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the viewport.
void | SynthPainter.paintViewportBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a viewport.
void | SynthStyle.uninstallDefaults(SynthContext context) Uninstalls any state that this style installed on the JComponent from context.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.synth.SynthGraphicsUtils

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.synth.SynthGraphicsUtils

Packages that use SynthGraphicsUtils
javax.swing.plaf.synth Synth is a skinnable look and feel in which all painting is delegated.

Uses of SynthGraphicsUtils in javax.swing.plaf.synth

Methods in javax.swing.plaf.synth that return SynthGraphicsUtils
 SynthGraphicsUtils SynthStyle.getGraphicsUtils(SynthContext context)
Returns the SynthGraphicUtils for the specified context.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.synth.SynthLookAndFeel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.synth.SynthLookAndFeel

No usage of javax.swing.plaf.synth.SynthLookAndFeel

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.synth.SynthPainter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.synth.SynthPainter

Packages that use SynthPainter
javax.swing.plaf.synth Synth is a skinnable look and feel in which all painting is delegated.

Uses of SynthPainter in javax.swing.plaf.synth

Methods in javax.swing.plaf.synth that return SynthPainter
 SynthPainter SynthStyle.getPainter(SynthContext context)
Returns the SynthPainter that will be used for painting.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.synth.SynthStyle

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.synth.SynthStyle

Packages that use SynthStyle
javax.swing.plaf.synth Synth is a skinnable look and feel in which all painting is delegated.

Uses of SynthStyle in javax.swing.plaf.synth

Methods in javax.swing.plaf.synth that return SynthStyle
SynthStyle | SynthContext.getStyle() Returns the style associated with this Region.
abstract SynthStyle | SynthStyleFactory.getStyle(JComponent c, Region id) Returns the style for the specified Component.
static SynthStyle | SynthLookAndFeel.getStyle(JComponent c, Region region) Gets a SynthStyle for the specified region of the specified component.

Constructors in javax.swing.plaf.synth with parameters of type SynthStyle
SynthContext(JComponent component, Region region, SynthStyle style, int state)
Creates a SynthContext with the specified values.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.plaf.synth.SynthStyleFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.plaf.synth.SynthStyleFactory

Packages that use SynthStyleFactory
javax.swing.plaf.synth Synth is a skinnable look and feel in which all painting is delegated.

Uses of SynthStyleFactory in javax.swing.plaf.synth

Methods in javax.swing.plaf.synth that return SynthStyleFactory
static SynthStyleFactory SynthLookAndFeel.getStyleFactory()
Returns the current SynthStyleFactory.

Methods in javax.swing.plaf.synth with parameters of type SynthStyleFactory
static void SynthLookAndFeel.setStyleFactory(SynthStyleFactory cache)
Sets the SynthStyleFactory that the UI classes provided by synth will use to obtain a SynthStyle.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.plaf.synth.SynthConstants

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.plaf.synth.SynthConstants

No usage of javax.swing.plaf.synth.SynthConstants

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ColorType

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.synth
Class ColorType

java.lang.Object
    extended by  javax.swing.plaf.synth.ColorType

public class ColorType
extends Object

A typesafe enumeration of colors that can be fetched from a style.

Each SynthStyle has a set of ColorTypes that are accessed by way of the SynthStyle.getColor(SynthContext, ColorType) method. SynthStyle's installDefaults will install the FOREGROUND color as the foreground of the Component, and the BACKGROUND color to the background of the component (assuming that you have not explicitly specified a foreground and background color). Some components support more color based properties, for example JList has the property selectionForeground which will be mapped to FOREGROUND with a component state of SynthConstants.SELECTED.

The following example shows a custom SynthStyle that returns a red Color for the DISABLED state, otherwise a black color.

 class MyStyle extends SynthStyle {
     private Color disabledColor = new ColorUIResource(Color.RED);
     private Color color = new ColorUIResource(Color.BLACK);
     protected Color getColorForState(SynthContext context, ColorType type){
         if (context.getComponentState() == SynthConstants.DISABLED) {
             return disabledColor;
         }
         return color;
     }
 }

Since:
1.5

Field Summary
static ColorType | BACKGROUND ColorType for the background of a region.
static ColorType | FOCUS ColorType for the focus.
static ColorType | FOREGROUND ColorType for the foreground of a region.
static int | MAX_COUNT Maximum number of ColorTypes.
static ColorType | TEXT_BACKGROUND ColorType for the background of a region.
static ColorType | TEXT_FOREGROUND ColorType for the foreground of a region.
Constructor Summary
protected ColorType(String description)
Creates a new ColorType with the specified description.
Method Summary
int | getID() Returns a unique id, as an integer, for this ColorType.
String | toString() Returns the textual description of this ColorType.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

FOREGROUND

public static final ColorType FOREGROUND
ColorType for the foreground of a region.

BACKGROUND

public static final ColorType BACKGROUND
ColorType for the background of a region.

TEXT_FOREGROUND

public static final ColorType TEXT_FOREGROUND
ColorType for the foreground of a region.

TEXT_BACKGROUND

public static final ColorType TEXT_BACKGROUND
ColorType for the background of a region.

FOCUS

public static final ColorType FOCUS
ColorType for the focus.

MAX_COUNT

public static final int MAX_COUNT
Maximum number of ColorTypes.

Constructor Detail

ColorType

protected ColorType(String description)
Creates a new ColorType with the specified description.

Parameters:
description - String description of the ColorType.
Method Detail

getID

public final int getID()
Returns a unique id, as an integer, for this ColorType.

Returns:
a unique id, as an integer, for this ColorType.

toString

public String toString()
Returns the textual description of this ColorType. This is the same value that the ColorType was created with.

Overrides:
toString in class Object
Returns:
the description of the string
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Component Specific Properties

The look, and to some degree the feel of Synth can be customized by way of component specific properties. These properties are accessed from SynthStyle#get. Refer to synth file format for examples of how to specify these properties in a synth configuration file.

This file specifies the expected class type each of the values are to take. The behavior of supplying the wrong type is unspecified: typically a ClassCastException is thrown, but it is implementation specific.

ArrowButton

ArrowButton is a special type of JButton that renders an arrow. ArrowButton is typically not created directly, rather some of the Components will create it to render a button with an arrow. The components that make use of ArrowButton are: JComboBox, JScrollBar and JSplitPane (for the buttons on the divider). In addition to the Button properties, ArrowButton supports the following propeties:

ArrowButton Specific Properties
Property | Expected Type | Default Value | Description
ArrowButton.size | Integer | 16 | Preferred size of the arrow button.

JButton

JButton paints text using the TEXT_FOREGROUND ColorType. In addition to the Button properties, JButton supports the following property:

JButton Specific Properties
Property | Expected Type | Default Value | Description
Button.defaultButtonFollowsFocus | Boolean | true | Whether or not the default JButton should change to the button that is receiving focus.

JCheckBox

JCheckBox paints text using the TEXT_FOREGROUND ColorType. In addition to the Button properties, JCheckBox supports the following property:

JCheckBox Specific Properties
Property | Expected Type | Default Value | Description
CheckBox.icon | Icon | null | Icon used to render the check.

JComboBox

JComboBox is a composite component that consists of the following child Components:

Name | Type | Description
ComboBox.arrowButton | SynthArrowButton | Renders the drop down indicator.
ComboBox.list | JList | JList used to render the values.
ComboBox.listRenderer | Component | The renderer used for the JComboBox's JList.
ComboBox.popup | JPopupMenu | JPopupMenu used to show the ComboBox.list of the JComboBox.
ComboBox.renderer | Component | The renderer used for the JComboBox. This is ONLY set if the renderer is a UIResource.
ComboBox.scrollPane | JScrollPane | JScrollPane containing the JList.
ComboBox.textField | JTextField | The editor.

JComboBox Specific Properties
Property | Expected Type | Default Value | Description
ComboBox.showPopupOnNavigation | Boolean | false | Whether or not the JPopupMenu should appear when navigating with the keyboard.

JFileChooser

JFileChooser Specific Properties
Property | Expected Type | Default Value | Description
FileChooser.cancelIcon | Icon | null | Icon displayed on cancel button of the file chooser.
FileChooser.okIcon | Icon | null | Icon displayed on the ok button of the file chooser.
FileView.directoryIcon | Icon | null | Icon used for directories.
FileView.fileIcon | Icon | null | Icon used for files.
FileView.computerIcon | Icon | null | Icon used for directories that represent the computer. Not all platforms will make use of this icon.
FileView.hardDriveIcon | Icon | null | Icon used to represent the root of a hard drive. For example, on Windows this would be used when viewing the C drive.
FileView.floppyDriveIcon | Icon | null | Icon used to represent a floppy disk.
FileChooser.newFolderIcon | Icon | null | Icon used by the button that creates a new folder.
FileChooser.upFolderIcon | Icon | null | Icon used by the button that navigates to the parent folder.
FileChooser.homeFolderIcon | Icon | null | Icon used by the button that navigates to the current user's home directory.
FileChooser.detailsViewIcon | Icon | null | Icon used by the button that toggles the detailed files list view.
FileChooser.listViewIcon | Icon | null | Icon used by the button that toggles the regular files list view, showing only an icon and the name of each file and directory.

JInternalFrame

JInternalFrame Specific Properties
Property | Expected Type | DefaultValue | Description
InternalFrame.icon | Icon | null | Icon drawn representing the system icon of the internal frame. If pressed the system menu will be shown.

JInternalFrameTitlePane

JInternalFrameTitlePane is the control bar located at the top of the internal frame similar to that found in a frame.

JInternalFrameTitlePane Specific Properties
Property | Expected Type | Default Value | Description
InternalFrameTitlePane.maximizeIcon | Icon | null | Icon drawn to indicate the ability to maximize the internal frame.
InternalFrameTitlePane.minimizeIcon | Icon | null | Icon drawn to indicate the ability to restore the internal frame back to its previous state.
InternalFrameTitlePane.iconifyIcon | Icon | null | Icon drawn to indicate the ability to minimize the internal frame.
InternalFrameTitlePane.closeIcon | Icon | null | Icon drawn to indicate the abililty to close the internal frame.
InternalFrameTitlePane.titleSpacing | Integer | 2 | Space between the buttons on the title pane and the title.
InternalFrameTitlePane.buttonSpacing | Integer | 2 | Space between the buttons on the title pane.
InternalFrameTitlePane.maxFrameIconSize | Dimension | 16x16 | Maximum size of the frame icon that will be rendered on the title pane. If the icon is bigger than this size, it will be scaled down.
InternalFrameTitlePane.titleAlignment | leading|trailing|center | leading | Alignment for the title. With a left to right component orientation leading is left and trailing right. With a right to left component orientation leading is right and trailing left.

JList

JList's sets the name of the renderer to List.renderer. JList supports the following properties:

JList Specific Properties
Property | Expected Type | Default Value | Description
List.rendererUseListColors | Boolean | true | If true the renderers state is not updated, and the text colors come from JList's getSelectionBackground and getSelectionForeground methods. If false, the renderer's state is updated and the colors will instead come from the Style.
List.rendererUseUIBorder | Boolean | true | If true setBorder on the renderer will succeed regardless of the border passed in, otherwise setBorder on the renderer will only succeed if it is a Synth Border.
List.cellHeight | Integer | -1 | Cell height of the JList. Is this is -1, setFixedCellHeight is not invoked.

Menu Properties

The Menu classes (JCheckBoxMenuItem, JMenu, JMenuItem, and JRadioButtonMenuItem) all support the same set of properties and behave similarly. Each component consists of two Regions: the region specific to the component and Region.MENU_ITEM_ACCELERATOR. MENU_ITEM_ACCELERATOR is used for painting the accelerator. Both Regions paint text using the TEXT_FOREGROUND ColorType. The following set of properties are supported:

Property | Expected Type | Default Value | Description
prefix.acceleratorDelimiter | String | + | String separator between the description of the modifiers and the key, for example Ctrl <acceleratorDelimiter> X.
prefix.arrowIcon | Icon | null | Icon drawn to the right of the text (or left when the ComponentOrientation is right to left) of the text. This is typically only defined for JMenu.
prefix.checkIcon | Icon | null | Icon drawn to the left of the text (or right when the ComponentOrientation is right to left) of the text. This is typically only defined for JCheckBoxMenuItem and JRadioButtonMenuItem to provide the check or radio button.
prefix.margin | Insets | Empty Insets (0, 0, 0, 0) | Margin for the JMenuItem. Refer to the javadoc of javax.swing.AbstractButton#setMargin(java.awt.Insets) for details of how the margin is used.
prefix.textIconGap | Integer | 4 | Padding between the icon and text. Refer to the javadoc for javax.swing.AbstractButton#setIconTextGap(int) for details of how this is used.

Prefix is one of: CheckBoxMenuItem, Menu, MenuItem, or RadioButtonMenuItem.

JMenu also supports the following properties:

Property | Expected Type | Default Value | Description
Menu.delay | Integer | 200 | Sets the delay before the menu appears.
Menu.shortcutKeys | int[] | KeyEvent.ALT_MASK | Array of the KeyEvent modifiers to use for shortcut keys.

JOptionPane

JOptionPane is a composite component and may consist of numerous child components, they are: OptionPane.button, OptionPane.label, OptionPane.comboBox, OptionPane.scrollPane, OptionPane.list, OptionPane.textField, OptionPane.iconLabel.

JOptionPane Specific Properties
Property | Expected Type | Default Value | Description
OptionPane.buttonAreaBorder | Border | null | Border around the button area.
OptionPane.buttonClickThreshhold | Integer | 0 | Passed to the created buttons setMultiClickThreshhold.
OptionPane.buttonOrientation | Integer | SwingConstants.CENTER | How the buttons should be layed out, one of SwingConstants.LEFT, SwingConstants.RIGHT or SwingConstants.CENTER (this will be flipped when in a right to left locale).
OptionPane.buttonPadding | Integer | 6 | Amount of space between buttons.
OptionPane.cancelIcon | Icon | null | Icon for the cancel button.
OptionPane.errorIcon | Icon | null | Icon used for ERROR_MESSAGE.
OptionPane.informationIcon | Icon | null | Icon used for INFORMATION_MESSAGE.
OptionPane.isYesLast | Boolean | false | If true the 'yes' button leads other buttons, otherwise it follows the other buttons.
OptionPane.questionIcon | Icon | null | Icon used for error QUESTION_MESSAGE.
OptionPane.minimumSize | Dimension | 262x90 | Minimum size for the JOptionPane.
OptionPane.noIcon | Icon | null | Icon for the no button.
OptionPane.okIcon | Icon | null | Icon for the ok button.
OptionPane.sameSizeButtons | Boolean | true | Whether or not all the buttons should be the same size.
OptionPane.separatorPadding | Integer | 6 | Amount of padding between the message area and separator.
OptionPane.yesIcon | Icon | null | Icon for the yes button.
OptionPane.warningIcon | Icon | null | Icon used for error WARNING_MESSAGE

JProgressBar

JProgressBar Specific Properties
Property | Expected Type | Default Value | Description
ProgressBar.repaintInterval | Integer | 50 | Number of milliseconds between repaints for indeterminate progress bars.
ProgressBar.cycleTime | Integer | 3000 | Number of milliseconds used to determine how far to move the bouncing box per frame when the progress bar is indeterminate.

JRadioButton

JRadioButton paints text using the TEXT_FOREGROUND ColorType. In addition to the Button properties, JRadioButton supports the following property:

JRadioButton Specific Properties
Property | Expected Type | Default Value | Description
RadioButton.icon | Icon | null | Icon used to render the radio indicator.

JScrollBar

JScrollBar is a composite component that consists of the following child Components:

Name | Type | Description
ScrollBar.button | SynthArrowButton | Identifies the increment/decrement buttons.

JScrollBar Specific Properties
Property | Expected Type | Default Value | Description
ScrollBar.allowsAbsolutePositioning | Boolean | false | If true, middle mouse click in the track will set the position of the track to where the mouse is.
ScrollBar.maximumThumbSize | Dimension | 4096x4096 | Maximum thumb size.
ScrollBar.minimumThumbSize | Dimension | Derived from ScrollBar.thumbHeight | The minimum thumb size. If this is not specified the minimum thumb size is ScrollBar.thumbHeight plus the insets of the scrollbar along the opposite axis of the scrollbar and 7 along the other axis. For example, if you have not specified Insets for a scrollbar, and the orientation of the scrollbar is vertical, than the minimum thumb size width is ScrollBar.thumbHeight with a height of 7.
ScrollBar.squareButtons | Boolean | false | If true, the width and height of the scrollbar buttons will be made equal.
ScrollBar.thumbHeight | Integer | 14 | The preferred height, when the orientation of the scrollbar is horizontal, or preferred width when the orientation of the scrollbar is vertical.

Separators

All of the separator classes, JSeparator, JPopupMenu.Separator and JToolBar.Separator use the same property:

Property | Expected Type | Default Value | Description
Separator.thickness | Integer | 2 | Preferred width, for vertically aligned separators, or preferred height for horizontally aligned separators. The resulting preferred size will include the Insets.

JToolBar.Separator also supports the following property:

Property | Expected Type | Default Value | Description
ToolBar.separatorSize | Dimension | null | The value of this is passed to the javax.swing.JToolBar$Separator#setSeparatorSize(java.awt.Dimension) method. If unspecified setSeparatorSize is not invoked.

JScrollPane

JScrollPane is unique in that it provides a method for setting the Border around the JViewport with JViewport throwing an IllegalArgumentException from setBorder. To accomodate this a special border is installed on the JScrollPane that uses the insets from the key ScrollPane.viewportBorderInsets. The SynthPainter method paintViewportBorder is called to paint the Viewports border.

JScrollPane Specific Properties
Property | Expected Type | Default Value | Description
ScrollPane.viewportBorderInsets | Insets | null | Insets for the viewport Border.

JSplitPane

JSplitPane is a composite component that will contain a divider and potentially two buttons, if setOneTouchExpandable(true) has been invoked. The two buttons will be named: SplitPaneDivider.leftOneTouchButton and SplitPaneDivider.rightOneTouchButton.

JSplitPane Specific Properties
Property | Expected Type | Default Value | Description
SplitPane.centerOneTouchButtons | Boolean | true | If true, the one touch buttons are centered on the divider.
SplitPane.oneTouchButtonOffset | Integer | 2 | Distance between the one touch buttons.
SplitPane.oneTouchButtonSize | Integer | 6 | Size to make the one touch buttons.
SplitPane.oneTouchExpandable | Boolean | null | If non null, the value of this is passed to setOneTouchExpandable.
SplitPane.size | Integer | 6 | Size of the divider

JSlider

JSlider Specific Properties
Property | Expected Type | Default Value | Description
Slider.thumbWidth | Integer | 30 | Width of the slider thumb
Slider.thumbHeight | Integer | 14 | Height of the slider thumb
Slider.trackBorder | Integer | 1 | Width of the track border
Slider.paintValue | Boolean | true | Whether or not to paint the current value of the slider.

JTabbedPane

JTabbedPane Specific Properties
Property | Expected Type | Default Value | Description
TabbedPane.tabRunOverlay | Integer | 0 | Number of pixels to overlap tabs when there is more than one row.
TabbedPane.textIconGap | Integer | 0 | Padding added between the icon and text on a tab. If there is no text or icon this value is not used.
TabbedPane.selectedTabPadInsets | Insets | Empty Insets (0, 0, 0, 0) | Extra insets added to the selected tab.
TabbedPane.selectionFollowsFocus | Boolean | true | If true the selection of the tabbed pane changes as the user navigates the tabs with a mouse.

JTable

JTable sets the name of the renderer to Table.cellRenderer. JTable supports the following properties:

JTable Specific Properties
Property | Expected Type | Default Value | Description
Table.gridColor | Color | null | Color used for the grid. If null the foreground from the style is used.
Table.rendererUseTableColors | Boolean | true | If true the renderers state is not updated, and the text colors come from JTable's getSelectionBackground and getSelectionForeground methods. If false, the renderer's state is updated and the colors will instead come from the Style.
Table.rendererUseUIBorder | Boolean | true | If true setBorder on the renderer will succeed regardless of the border passed in, otherwise setBorder on the renderer will only succeed if it is a Synth Border.
Table.rowHeight | Integer | -1 | If not -1 setRowHeight is invoked on the JTable.

JTree

JTree sets the name of the renderer to Tree.renderer, the name of the editor is Tree.cellEditor.

JTree Specific Properties
Property | Expected Type | Default Value | Description
Tree.collapsedIcon | Icon | null | Icon to use when a node is collapsed.
Tree.drawHorizontalLines | Boolean | true | If true nodes have a horizontal connecting them to the leading edge of their parent.
Tree.drawVerticalLines | Boolean | true | If true a vertical line is drawn down from expanded nodes.
Tree.expandedIcon | Icon | null | Icon to use when a node has been expanded.
Tree.leftChildIndent | Integer | 0 | This plus Tree.rightChildIndent account for the total space, along the y axis, to offset nodes from their parent.
Tree.rightChildIndent | Integer | 0 | This plus Tree.leftChildIndent account for the total space, along the y axis, to offset nodes from their parent.
Tree.rowHeight | Integer | -1 | Row height for the Tree.
Tree.scrollsHorizontallyAndVertically | Boolean | false | If false and scrolling needs to happen to accomodate cells it will only happen along the vertical axis, if true, scrolling may happen along both the horizontal and vertical axis.
Tree.scrollsOnExpand | Boolean | true | Whether or not the JTree should scroll when a node is expanded.
Tree.linesStyle | String |  | The styles of the lines in the tree. Synth supports solid lines (empty value) and dashed lines ("dashed" value). It is possible to add new styles by creating a new SynthGraphicsUtils and binding it to the tree.

JToggleButton

JToggleButton paints text using the TEXT_FOREGROUND ColorType. In addition to the Button properties, JToggleButton supports the following property:

JToggleButton Specific Properties
Property | Expected Type | Default Value | Description
ToggleButton.icon | Icon | null | Icon used to render the radio indicator.

Button Properties

Each of the Button classes (JButton, JCheckBox, JRadioButton, JToggleButton and SynthArrowButton) support a similar set of properties. These properties are:

Property | Expected Type | Default Value | Description
prefix.contentAreaFilled | Integer | true | Refer to the javadoc of javax.swing.AbstractButton#contentAreaFilled(boolean) for details of how this is used. It is up to the Painter to properly honor this property.
prefix.iconTextGap | Integer | If unspecified, JButton.setIconTextGap is not invoked. | Padding between the icon and text. Refer to the javadoc of javax.swing.AbstractButton#setIconTextGap(int) for details of how this is used.
prefix.margin | Insets | Empty Insets (0, 0, 0, 0) | Margin for the JButton. Refer to the javadoc of javax.swing.AbstractButton#setMargin(java.awt.Insets) for details of how the margin is used.
prefix.textShiftOffset | Integer | 0 | Amount to shift the text and icon, along the x and y axis, from where it would normally be layed out. This is only used when the button is in a pressed state and does not have a pressed icon.

Prefix is one of: Button, CheckBox, RadioButton or JToggleButton.

Text Properties

Property | Expected Type | Default Value | Description
prefix.caretForeground | Color | #000000 | Color of the caret.
prefix.margin | Insets | Empty Insets (0, 0, 0, 0), EditorPane and TextPane (3, 3, 3, 3) | Margins of the text component.
prefix.caretBlinkRate | Integer | 500 | Number of milliseconds defining the blink rate fo the caret.

Prefix is one of: EditorPane, FormattedTextField, PasswordField, TextArea, TextField or TextPane.


Synth File Format

File Format

Synth's file format (dtd) allows for specifying all the pieces necessary to create your own look and feel. A synth file is loaded by way of the SynthLookAndFeel.load(InputStream, Class) or SynthLookAndFeel.load(URL) methods. The following example uses the load method to configure a SynthLookAndFeel and sets it as the current look and feel:

  SynthLookAndFeel laf = new SynthLookAndFeel();
  laf.load(MyClass.class.getResourceAsStream("laf.xml"), MyClass.class);
  UIManager.setLookAndFeel(laf);

This example loads the look and feel from an input stream, using the specified class as the resource base to resolve paths. It is also possible to load a look and feel from an arbitrary URL as in the following example.

  SynthLookAndFeel laf = new SynthLookAndFeel();
  laf.load(new URL("file:///C:/java/synth/laf/laf.xml"));
  UIManager.setLookAndFeel(laf);

The method SynthLookAndFeel.load(URL) can be used, for instance, to load a look and feel from any of the following:

  • File, e.g. file:///C:/java/synth/laf/laf.xml
  • Web server, e.g. http://host/laf.xml
  • JAR file, e.g. jar:file:///C:/synth-laf.jar!/laf.xml
  • Remote JAR file, e.g. jar:http://host/synth-laf.jar!/laf.xml

While the DTD for synth is specified, the parser is not validating. Parsing will fail only if a necessary attribute is not specified, or of the wrong type.

The synth element

<!ELEMENT synth ((%beansPersistance;) | style | bind | font | color |
                 imagePainter | imageIcon | defaultsProperty)*>
<!ATTLIST synth
          version              CDATA          #IMPLIED
>

Attribute definitions

version
File format version, should be 1

The synth element contains all the other elements that make up a SynthLookAndFeel definition.

The style element

<!ELEMENT style (property | defaultsProperty | state | font | graphicsUtils |
                 insets | painter | imagePainter | opaque | (%beansPersistance;) |
                 imageIcon)*>
<!ATTLIST style
          id              ID          #IMPLIED
          clone           IDREF       #IMPLIED
>

Attribute definitions

id
Unique identifier for the style.
clone
Identifier of a previously defined style that is copied and used for the new style. This provides a conveniant mechanism for overriding only a portion of an existing style.

A style element corresponds to a SynthStyle, with the child elements specifying properties that apply to all states or state elements which contain properties specific to a particular state. The following example creates an opaque style with the id button, insets of 4, 4, 4, 4 and a font of Dialog 12.

<style id="button">
  <opaque value="true"/>
  <insets top="4" left="4" right="4" bottom="4"/>
  <font name="Dialog" size="12"/>
</style>

The following example creates a new style with an id of clonedButton that is a copy of the style with id button and has a font of Dialog, 14. The resulting style will be opaque, have insets of 4, 4, 4, 4 and a font of Dialog 14.

<style id="clonedButton" clone="button">
  <font name="Dialog" size="14"/>
</style>

The state element

<!ELEMENT state (color | font | painter | imagePainter | (%beansPersistance;) |
                 property |  imageIcon)*>
<!ATTLIST state
          id              ID             #IMPLIED
          clone           IDREF          #IMPLIED
          value           CDATA          #IMPLIED
          idref           IDREF          #IMPLIED
>

Attribute definitions

id
Unique identifier for the state.
clone
Identifier of a previously defined state that is copied and used for the new state.
value
Identifies the state of the Component the properties are to apply to. This is a list of: ENABLED, MOUSE_OVER, PRESSED, DISABLED, FOCUSED, SELECTED or DEFAULT. Multiple states should be separated by 'and.' If you do not specify a value, the contents apply to all states.
idref
Indicates this state should be the same as a previously defined state. This is useful for multiple styles that wish to share the same visual properties for a particular state.

The state element specifies the visual properties that are to be used for a particular state of a component. For example, you could specify the background color when the Component is enabled should look different than the background color when the component is disabled. Not all Components support all states. For example, a Panel only supports the states ENABLED and DISABLED.

The following example creates a state with a red background that will be used when the component is in an a selected and pressed state:

<state value="SELECTED AND PRESSED">
  <color value="RED" type="BACKGROUND"/>
</state>

The state with the most individual matches will be chosen. For example, the following defines two states:

<state value="SELECTED and PRESSED" id="one">
  <color value="RED" type="BACKGROUND"/>
</state>
<state value="SELECTED" id="two">
  <color value="RED" type="BACKGROUND"/>
</state>

State one is used when the Component is SELECTED and PRESSED, and state two when the Component is SELECTED. If the state of the Component contains at least SELECTED and PRESSED, state one will be chosen, otherwise if the state is SELECTED, but not does not contain PRESSED, state two will be used.

The font element

<!ELEMENT font EMPTY>
<!ATTLIST font
          id              ID             #IMPLIED
          clone           IDREF          #IMPLIED
          name            CDATA          #IMPLIED
          style           CDATA          #IMPLIED
          size            CDATA          #IMPLIED
>

Attribute definitions

id
Unique identifier for the Font.
idref
Identifier of a previously defined font.
name
Name of the font.
style
Style of the font. This is a list of the styles defined by Font separated by spaces: PLAIN, BOLD or ITALIC. If unspecified PLAIN is used.
size
Size of the font, in pixels

Defines the font for the current state, or style. You must specify either an idref or a name and size.

The following example creates a style with a Font of Dialog 12 Bold.

<style id="test">
  <font name="DIALOG" size="12" style="BOLD"/>
</style>

The following example creates a style with a font of Dialog 12 Bold that will be used if the component is ENABLED, otherwise Dialog 12 Italic will be used.

<style id="test">
  <font name="DIALOG" size="12" style="ITALIC"/>
  <state value="ENABLED">
    <font name="DIALOG" size="12" style="BOLD"/>
  </state>
</style>

While you can supply a different font per state, in general widgets will NOT revalidate when the state changes, so that you may run into sizing problems if you try to use a font with a significantly different size for different states.

The color element

<!ELEMENT color EMPTY>
<!ATTLIST color
          id              ID             #IMPLIED
          idref           IDREF          #IMPLIED
          type            CDATA          #IMPLIED
          value           CDATA          #IMPLIED
>

Attribute definitions

id
Unique identifier for the color.
idref
Identifier of a previously defined color.
type
Describes where this color should be used. This is typically one of the constants defined by ColorType: FOREGROUND, BACKGROUND, TEXT_FOREGROUND, TEXT_BACKGROUND or FOCUS. Alternatively you can specify the complete path to a class and field, for example javax.swing.plaf.synth.ColorType.FOREGROUND, this is useful for subclasses of synth that define additional color types.
value
Value for the color. This accepts the following forms.
  • The name of a constant in the Color class, for example RED.
  • A hex value of the form #RRGGBB where RR gives the red component, GG the green component and BB the blue component. You need not specify all color components. For example, #123 is equivalent to #000123.
  • A hex value of the form #ARRGGBB or #AARRGGBB. This is useful for alpha values other than 0xFF. The form #ARRGGBB is equivalent to #0ARRGGBB.

Color defines a color and what portion of the Component it should be applied to. The following example will use a background color of RED when the component is enabled.

<state value="ENABLED">
  <color value="RED" type="BACKGROUND"/>
</state>

The following example will have a red background when the Component is enabled, otherwise blue.

<style id="test">
  <state value="ENABLED">
    <color value="RED" type="BACKGROUND"/>
  </state>
  <state>
    <color value="#00FF00" type="BACKGROUND"/>
  </state>
</style>

The property element

<!ELEMENT property EMPTY>
<!ATTLIST property
          key               CDATA                                             #REQUIRED
          type              (idref|boolean|dimension|insets|integer|string)          "idref"
          value             CDATA                                             #REQUIRED
>

Attribute definitions

key
Name of the property.
type
Indicates the type of the property.
value
Value for the property. For boolean properties this will be be true or false, for integer properties this will be a valid integer, for dimensions this will be the width and height separated by a space, for insets properties this will be the top, left, bottom and right separated by a space and for idref properties this will be the unique id of a previously defined object.

Property elements are used to add key value pairs to a SynthStyle that can be accessed by way of the get method. Many Components use the key value pairs for configuring their visual appearance. Refer to property table for a list of the properties each Component supports. The following creates the properties ScrollBar.allowsAbsolutePositioning, OptionPane.minimumSize, ScrollPane.viewportBorderInsets, Tree.rowHeight and foreground with the values false, a dimensions of 262x90, an insets of 5, 5, 5, 5, the integer 20 and an instance of the class ArrowButtonPainter.

<style id="test">
  <property key="ScrollBar.allowsAbsolutePositioning" type="boolean" value="false"/>
  <property key="OptionPane.minimumSize" type="dimension" value="262 90"/>
  <property key="ScrollPane.viewportBorderInsets" type="insets" value="5 5 5 5"/>
  <property key="Tree.rowHeight" type="integer" value="20"/>
  <object class="ArrowButtonPainter" id="ArrowButtonPainter"/>
  <property key="foreground" type="idref" value="ArrowButtonPainter"/>
</style>

You can also specify properties that are to apply to specific states. Whether or not the property is accessed for each state depends upon how the property is used. For example, the following specifies a default icon and an icon to use while the mouse is over the component.

<style id="test">
  <imageIcon id="defaultIcon" path="resources/myImage.png"/>
  <property key="RadioButton.icon" value="defaultIcon"/>
  <state value="MOUSE_OVER">
    <imageIcon id="mouseOverIcon" path="resources/myMouseOverImage.png"/>
    <property key="RadioButton.icon" value="mouseOverIcon"/>
  </state>
</style>

<!ELEMENT defaultsProperty EMPTY>
<!ATTLIST defaultsProperty
          key               CDATA                                             #REQUIRED
          type              (idref|boolean|dimension|insets|integer|string)   "idref"
          value             CDATA                                             #REQUIRED
>

Attribute definitions

key
Name of the property.
type
Indicates the type of the property.
value
Value for the property. For boolean properties this will be true or false, for integer properties this will be a valid integer, for dimensions this will be the width and height separated by a space, for insets properties this will be the top, left, bottom and right separated by a space and for idref properties this will be the unique id of a previously defined object.

DefaultsProperty elements are used to define properties that will be placed in the UIDefaults table that SynthLookAndFeel supplies to the UIManager. The following assigns the the Color red to the value Table.focusCellForeground.

<style id="test">
  <object class="javax.swing.plaf.ColorUIResource" id="color">
    <int>255</int>
    <int>0</int>
    <int>0</int>
  </object>
  <defaultsProperty key="Table.focusCellForeground" type="idref" value="color"/>
</style>

This value could then be asked by way of UIManager.get("Table.focusCellForeground").

The graphicsUtils element

<!ELEMENT graphicsUtils EMPTY>
<!ATTLIST graphicsUtils
          idref           IDREF             #REQUIRED
>

Attribute definitions

idref
Identifer of a previously defined SynthGraphicsUtils object that is to be used as the SynthGraphicsUtils for the current style.

GraphicsUtils elements are used to define the SynthGraphicsUtils that the current style will use. The following example creates a style with an instance of CustomGraphicsUtils for the SynthGraphicsUtils.

<style id="test">
  <object class="CustomGraphicsUtils" id="graphics"/>
  <graphicsUtils idref="graphics"/>
</style>

The insets element

<!ELEMENT insets EMPTY>
<!ATTLIST insets
          id           ID             #IMPLIED
          idref        IDREF          #IMPLIED
          top          CDATA          #IMPLIED
          bottom       CDATA          #IMPLIED
          left         CDATA          #IMPLIED
          right        CDATA          #IMPLIED
>

Attribute definitions

id
Unique identifier for the Insets.
idref
Identifier of a previously defined Insets.
top
Top component of the Insets.
bottom
Bottom component of the Insets.
left
Left component of the Insets.
right
Right component of the Insets.

Insets elements are used to define the Insets for the current style. The insets will be set on any Components the style is associated with. The following example creates a style with insets of 1, 2, 3, 0.

<style id="test">
  <insets top="1" bottom="2" left="3"/>
</style>

The bind element

<!ELEMENT bind EMPTY>
<!ATTLIST bind
          style        IDREF             #REQUIRED
          type         (name|region)     #REQUIRED
          key          CDATA             #REQUIRED
>

Attribute definitions

style
Unique identifier of a previously defined style.
type
One of name or region. For type name component.getName() is used, otherwise the name of the Region is used.
key
Regular expression applied to the name of the Component, or the name of the Region, depending upon the value of type.

Bind elements specify which Regions a style is to be used for. The following example applies the style test to any Component whose name starts with test.

<style id="test">
  <insets top="1" bottom="2" left="3"/>
</style>
<bind style="test" type="name" key="test.*"/>

Numerous styles may apply to a region, in which case each of the matching styles is merged into a resulting style that is used. Precedence is given to styles defined later in the file. For example, the following defines two styles, a and b. Style a is applied to any component with a name starting with test, and style b is used for button regions.

<style id="a">
  <font name="DIALOG" size="12" style="ITALIC"/>
  <insets top="1" bottom="2" left="3"/>
</style>
<bind style="a" type="name" key="test.*"/>
<style id="b">
  <font name="DIALOG" size="12" style="BOLD"/>
</style>
<bind style="b" type="region" key="button"/>

For a button with the name test this is equivalent to:

<style>
  <font name="DIALOG" size="12" style="BOLD"/>
  <insets top="1" bottom="2" left="3"/>
</style>

Merging happens for states of a style as well.

<style id="a">
  <font name="DIALOG" size="12" style="ITALIC"/>
  <insets top="1" bottom="2" left="3"/>
  <state value="ENABLED">
    <object id="customPainter" class="CustomPainter"/>
    <painter idref="customPainter"/>
  </state>
</style>
<bind style="a" type="name" key="test.*"/>
<style id="b">
  <font name="DIALOG" size="12" style="BOLD"/>
  <state value="ENABLED">
    <font name="Lucida" size="12" style="ITALIC"/>
  </state>
</style>
<bind style="b" type="region" key="button"/>

For a button with the name test this is equivalent to:

<style>
  <font name="DIALOG" size="12" style="BOLD"/>
  <insets top="1" bottom="2" left="3"/>
  <state value="ENABLED">
    <object id="customPainter" class="CustomPainter"/>
    <painter idref="customPainter"/>
    <font name="Lucida" size="12" style="ITALIC"/>
  </state>
</style>

The painter element

<!ELEMENT painter EMPTY>
<!ATTLIST painter
          idref                 IDREF          #IMPLIED
          method                CDATA          #IMPLIED
          direction             (north|south|east|west|top|left|bottom|right|horizontal|vertical|horizontal_split|vertical_split)          #IMPLIED
>

Attribute definitions

idref
Identifier of a previously defined SynthPainter.
method
Identifies the SynthPainter method this is to be used for. The name corresponds to the method name of a paint method in SynthPainter with the paint prefix dropped, the remainder is case insensitive (using the latin1 case folding rules). For example SynthPainter.paintButtonBackground is identified by 'buttonBackground' or 'buttonbackground'. If this is not specified the painter is used for all methods that don't have a a specific painter for them.
direction
Identifies the direction, or orientation, this painter is to be used for. This is only useful for the SynthPainter methods that take a direction or orientation. If this is not specified the painter is used for all directions.

Painter defines a SynthPainter for the current style or the state of the current style. The following example binds an instance of the class MyPainter which must be a SynthPainter to the style test.

<style id="test">
  <object class="MyPainter" id="MyPainter"/>
  <painter idref="MyPainter"/>
</style>

The painter that is used for a particular method and state is determined as follows:

  1. Painter specified for the current state, method and direction.
  2. Painter specified for the current state and method.
  3. Painter specified for the current state.
  4. Painter specified for the style, method and direction.
  5. Painter specified for the style and method.
  6. Painter specified for the style.

Consider the following:

<style id="test">
  <painter idref="fallbackPainter"/>
  <painter idref="styleButtonBackgroundPainter" method="buttonBackground"/>
  <state value="SELECTED">
    <painter idref="stateFallbackPainter"/>
    <painter idref="stateButtonBackgroundPainter" method="buttonBackground"/>
  </state>
</style>

The following outlines which painter will be used for what SynthPainter method:

State | Method | Painter
SELECTED | paintButtonBackground | stateButtonBackgroundPainter
SELECTED | Anything but paintButtonBackground | stateFallbackPainter
Anything but SELECTED | paintButtonBackground | styleButtonBackgroundPainter
Anything but SELECTED | Anything but paintButtonBackground | fallbackPainter

When several identical painters are declared, they are aggregated into a single one. Two painters are identical if their direction and method attributes values are equal. Consider the following:

<style id="panelStyle">
  <imagePainter method="panelBackground" path="red.png" />
  <imagePainter method="panelBackground" path="green.png" />
  <imagePainter method="panelBackground" path="blue.png" />
</style>

These three painters are identical for they use the same method and the same direction (all directions by default). Synth aggregates these painters to create a single one that will paint its children painters in the order of declaration. Hence, Synth will first paint the red picture, then the green one and finally the blue one. Each child painter can be seen as a layer of the aggregate painter.

Painter aggregation, or multi-layering, is very useful to reuse elements. Imagine you want to use an highlight effect on buttons and on selected menu items. With painter aggregation, you just need to create a separate highlighting painter instead of having buttons and menu items painters handle it.

The imagePainter element

<!ELEMENT imagePainter EMPTY>
<!ATTLIST imagePainter
          id                    ID             #IMPLIED
          method                CDATA          #IMPLIED
          direction             (north|south|east|west|top|left|bottom|right|horizontal|vertical|horizontal_split|vertical_split)          #IMPLIED
          path                  CDATA          #REQUIRED
          sourceInsets          CDATA          #IMPLIED
          destinationInsets     CDATA          #IMPLIED
          paintCenter           (true|false)   "true"
          stretch               (true|false)   "true"
          center                (true|false)   "false"
>

Attribute definitions

id
Unique identifier for the imagePainter.
method
Identifies the SynthPainter method this is to be used for. The name corresponds to the method name of a paint method in SynthPainter with the paint prefix dropped, the remainder is case insensitive (using the latin1 case folding rules). For example SynthPainter.paintButtonBackground is identified by 'buttonBackground' or 'buttonbackground'. If this is not specified the painter is used for all methods that don't have a a specific painter for them.
direction
Identifies the direction, or orientation, this image is to be used for. This is only useful for the SynthPainter methods that take a direction or orientation. If this is not specified the image is used for all directions.
path
Path to the image. Path to the image. If SynthLookAndFeel.load is passed a Class this will use the Class method getResource (with with the Class suplied to the load method). If load is passed a URL this will use the URL constructor URL(context, path) to resolve the path.
sourceInsets
Insets on the source image. This is top, left, bottom, right with each component separated by a space.
destinationInsets
Insets of the destination image. This is top, left, bottom, right with each component separated by a space. If not specified the sourceInsets are used.
paintCenter
Whether or not the center of the image should be drawn.
stretch
Whether or not the north, south, east and west components of the resulting image should be scaled or tiled.
center
Whether or not the image is centered.

The ImagePainter element defines a painter for the current style or state that will render using the specified image. ImagePainter offers two distinct rendering modes. The first mode is used to center an image in the space provided. This is commonly used in rendering decorations on top of a widget, for example, to specify an arrow for a scroll button use the center mode. The following example illustrates this:

<style id="test">
  <imagePainter path="resources/myImage.png" center="true"/>
</style>

The second mode is used in scaling an image to fit in the provided space. In this mode sourceInsets is used to specify a border around an image where the north, south, east and west edges of the border are either stretched or tiled (stretch attribute), the four corners of the border drawn in place, and the center is stretched. In this mode you must specify sourceInsets. The following example illustrates an ImagePainter that is using the image MyImage.png and insets of 2 all the way around:

<style id="test">
  <imagePainter path="resources/myImage.png"
                sourceInsets="2 2 2 2"/>
</style>

Refer to the description of the painter element for details as to the precedence in choosing a painter and to understand how identical painters are handled.

The imageIcon element

<!ELEMENT imageIcon EMPTY>
<!ATTLIST imageIcon
          id                    ID             #REQUIRED
          path                  CDATA          #REQUIRED
>

Attribute definitions

id
Unique identifier for the imageIcon.
path
Path to the image. This uses the Class method getResource to resolve the path, with the Class supplied to SynthLookAndFeel.load.

ImageIcon is used to assign an Icon implementation that is wrapping an Image to a unique identifier. This is typically used for properties that take an Icon. The following example binds an ImageIcon to the property RadioButton.icon.

<style id="test">
  <imageIcon id="icon" path="resources/myImage.png"/>
  <property key="RadioButton.icon" value="icon"/>
</style>

The opaque element

<!ELEMENT opaque EMPTY>
<!ATTLIST opaque
          value              (true|false)   "true"
>

Attribute definitions

id
Whether or not the style should be opaque, if unspecified the style is opaque.

The opaque element indicates whether or not any Components the style is associated with are to be made opaque. The painter will be asked to paint regardless of the opacity of the associated Component. The following example creates a style that is not opaque.

<style id="test">
  <opaque value="FALSE">
  <painter idref="painter"/>
</style>

The beansPersistance entity

Beans persistance can be used to embed any Object. This is typically used for embedding your own Painters, but can be used for other arbritrary objects as well. Refer to http://java.sun.com/products/jfc/tsc/articles/persistence3/ for details on beans persistance.

Backing Style

In creating a Synth file it's good practice to create a backing style that is used by all components. This will make sure that any components that do not match a specific style will have a default font, foreground, background and opacity. The following example illustrates this:

<synth>
  <style id="backingStyle">
    <opaque value="true"/>
    <font name="Dialog" size="12"/>
    <state>
      <color value="BLACK" type="BACKGROUND"/>
      <color value="WHITE" type="FOREGROUND"/>
    </state>
  </style>
  <bind style="backingStyle" type="region" key=".*"/>
</synth>


Region

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.synth
Class Region

java.lang.Object
    extended by  javax.swing.plaf.synth.Region

public class Region
extends Object

A distinct rendering area of a Swing component. A component may support one or more regions. Specific component regions are defined by the typesafe enumeration in this class.

Regions are typically used as a way to identify the Components and areas a particular style is to apply to. Synth's file format allows you to bind styles based on the name of a Region. The name is derived from the field name of the constant:

  1. Map all characters to lowercase.
  2. Map the first character to uppercase.
  3. Map the first character after underscores to uppercase.
  4. Remove all underscores.
For example, to identify the SPLIT_PANE Region you would use SplitPane. The following shows a custom SynthStyleFactory that returns a specific style for split panes:
    public SynthStyle getStyle(JComponent c, Region id) {
        if (id == Region.SPLIT_PANE) {
            return splitPaneStyle;
        }
        ...
    }
The following xml accomplishes the same thing:
 <style id="splitPaneStyle">
   ...
 </style>
 <bind style="splitPaneStyle" type="region" key="SplitPane"/>

Since:
1.5

Field Summary
static Region | ARROW_BUTTON ArrowButton's are special types of buttons that also render a directional indicator, typically an arrow.
static Region | BUTTON Button region.
static Region | CHECK_BOX CheckBox region.
static Region | CHECK_BOX_MENU_ITEM CheckBoxMenuItem region.
static Region | COLOR_CHOOSER ColorChooser region.
static Region | COMBO_BOX ComboBox region.
static Region | DESKTOP_ICON DesktopIcon region.
static Region | DESKTOP_PANE DesktopPane region.
static Region | EDITOR_PANE EditorPane region.
static Region | FILE_CHOOSER FileChooser region.
static Region | FORMATTED_TEXT_FIELD FormattedTextField region.
static Region | INTERNAL_FRAME InternalFrame region.
static Region | INTERNAL_FRAME_TITLE_PANE TitlePane of an InternalFrame.
static Region | LABEL Label region.
static Region | LIST List region.
static Region | MENU Menu region.
static Region | MENU_BAR MenuBar region.
static Region | MENU_ITEM MenuItem region.
static Region | MENU_ITEM_ACCELERATOR Accelerator region of a MenuItem.
static Region | OPTION_PANE OptionPane region.
static Region | PANEL Panel region.
static Region | PASSWORD_FIELD PasswordField region.
static Region | POPUP_MENU PopupMenu region.
static Region | POPUP_MENU_SEPARATOR PopupMenuSeparator region.
static Region | PROGRESS_BAR ProgressBar region.
static Region | RADIO_BUTTON RadioButton region.
static Region | RADIO_BUTTON_MENU_ITEM RegionButtonMenuItem region.
static Region | ROOT_PANE RootPane region.
static Region | SCROLL_BAR ScrollBar region.
static Region | SCROLL_BAR_THUMB Thumb of the ScrollBar.
static Region | SCROLL_BAR_TRACK Track of the ScrollBar.
static Region | SCROLL_PANE ScrollPane region.
static Region | SEPARATOR Separator region.
static Region | SLIDER Slider region.
static Region | SLIDER_THUMB Thumb of the Slider.
static Region | SLIDER_TRACK Track of the Slider.
static Region | SPINNER Spinner region.
static Region | SPLIT_PANE SplitPane region.
static Region | SPLIT_PANE_DIVIDER Divider of the SplitPane.
static Region | TABBED_PANE TabbedPane region.
static Region | TABBED_PANE_CONTENT Region of a TabbedPane containing the content.
static Region | TABBED_PANE_TAB Region of a TabbedPane for one tab.
static Region | TABBED_PANE_TAB_AREA Region of a TabbedPane containing the tabs.
static Region | TABLE Table region.
static Region | TABLE_HEADER TableHeader region.
static Region | TEXT_AREA TextArea region.
static Region | TEXT_FIELD TextField region.
static Region | TEXT_PANE TextPane region.
static Region | TOGGLE_BUTTON ToggleButton region.
static Region | TOOL_BAR ToolBar region.
static Region | TOOL_BAR_CONTENT Region of the ToolBar containing the content.
static Region | TOOL_BAR_DRAG_WINDOW Region for the Window containing the ToolBar.
static Region | TOOL_BAR_SEPARATOR ToolBar separator region.
static Region | TOOL_TIP ToolTip region.
static Region | TREE Tree region.
static Region | TREE_CELL Region of the Tree for one cell.
static Region | VIEWPORT Viewport region.
Constructor Summary
protected Region(String name, String ui, boolean subregion)
Creates a Region with the specified name.
Method Summary
String | getName() Returns the name of the region.
boolean | isSubregion() Returns true if the Region is a subregion of a Component, otherwise false.
String | toString() Returns the name of the Region.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ARROW_BUTTON

public static final Region ARROW_BUTTON
ArrowButton's are special types of buttons that also render a directional indicator, typically an arrow. ArrowButtons are used by composite components, for example ScrollBar's contain ArrowButtons. To bind a style to this Region use the name ArrowButton.

BUTTON

public static final Region BUTTON
Button region. To bind a style to this Region use the name Button.

CHECK_BOX

public static final Region CHECK_BOX
CheckBox region. To bind a style to this Region use the name CheckBox.

CHECK_BOX_MENU_ITEM

public static final Region CHECK_BOX_MENU_ITEM
CheckBoxMenuItem region. To bind a style to this Region use the name CheckBoxMenuItem.

COLOR_CHOOSER

public static final Region COLOR_CHOOSER
ColorChooser region. To bind a style to this Region use the name ColorChooser.

COMBO_BOX

public static final Region COMBO_BOX
ComboBox region. To bind a style to this Region use the name ComboBox.

DESKTOP_PANE

public static final Region DESKTOP_PANE
DesktopPane region. To bind a style to this Region use the name DesktopPane.

DESKTOP_ICON

public static final Region DESKTOP_ICON
DesktopIcon region. To bind a style to this Region use the name DesktopIcon.

EDITOR_PANE

public static final Region EDITOR_PANE
EditorPane region. To bind a style to this Region use the name EditorPane.

FILE_CHOOSER

public static final Region FILE_CHOOSER
FileChooser region. To bind a style to this Region use the name FileChooser.

FORMATTED_TEXT_FIELD

public static final Region FORMATTED_TEXT_FIELD
FormattedTextField region. To bind a style to this Region use the name FormattedTextField.

INTERNAL_FRAME

public static final Region INTERNAL_FRAME
InternalFrame region. To bind a style to this Region use the name InternalFrame.

INTERNAL_FRAME_TITLE_PANE

public static final Region INTERNAL_FRAME_TITLE_PANE
TitlePane of an InternalFrame. The TitlePane typically shows a menu, title, widgets to manipulate the internal frame. To bind a style to this Region use the name InternalFrameTitlePane.

LABEL

public static final Region LABEL
Label region. To bind a style to this Region use the name Label.

LIST

public static final Region LIST
List region. To bind a style to this Region use the name List.

MENU

public static final Region MENU
Menu region. To bind a style to this Region use the name Menu.

MENU_BAR

public static final Region MENU_BAR
MenuBar region. To bind a style to this Region use the name MenuBar.

MENU_ITEM

public static final Region MENU_ITEM
MenuItem region. To bind a style to this Region use the name MenuItem.

MENU_ITEM_ACCELERATOR

public static final Region MENU_ITEM_ACCELERATOR
Accelerator region of a MenuItem. To bind a style to this Region use the name MenuItemAccelerator.

OPTION_PANE

public static final Region OPTION_PANE
OptionPane region. To bind a style to this Region use the name OptionPane.

PANEL

public static final Region PANEL
Panel region. To bind a style to this Region use the name Panel.

PASSWORD_FIELD

public static final Region PASSWORD_FIELD
PasswordField region. To bind a style to this Region use the name PasswordField.

POPUP_MENU

public static final Region POPUP_MENU
PopupMenu region. To bind a style to this Region use the name PopupMenu.

POPUP_MENU_SEPARATOR

public static final Region POPUP_MENU_SEPARATOR
PopupMenuSeparator region. To bind a style to this Region use the name PopupMenuSeparator.

PROGRESS_BAR

public static final Region PROGRESS_BAR
ProgressBar region. To bind a style to this Region use the name ProgressBar.

RADIO_BUTTON

public static final Region RADIO_BUTTON
RadioButton region. To bind a style to this Region use the name RadioButton.

RADIO_BUTTON_MENU_ITEM

public static final Region RADIO_BUTTON_MENU_ITEM
RegionButtonMenuItem region. To bind a style to this Region use the name RadioButtonMenuItem.

ROOT_PANE

public static final Region ROOT_PANE
RootPane region. To bind a style to this Region use the name RootPane.

SCROLL_BAR

public static final Region SCROLL_BAR
ScrollBar region. To bind a style to this Region use the name ScrollBar.

SCROLL_BAR_TRACK

public static final Region SCROLL_BAR_TRACK
Track of the ScrollBar. To bind a style to this Region use the name ScrollBarTrack.

SCROLL_BAR_THUMB

public static final Region SCROLL_BAR_THUMB
Thumb of the ScrollBar. The thumb is the region of the ScrollBar that gives a graphical depiction of what percentage of the View is currently visible. To bind a style to this Region use the name ScrollBarThumb.

SCROLL_PANE

public static final Region SCROLL_PANE
ScrollPane region. To bind a style to this Region use the name ScrollPane.

SEPARATOR

public static final Region SEPARATOR
Separator region. To bind a style to this Region use the name Separator.

SLIDER

public static final Region SLIDER
Slider region. To bind a style to this Region use the name Slider.

SLIDER_TRACK

public static final Region SLIDER_TRACK
Track of the Slider. To bind a style to this Region use the name SliderTrack.

SLIDER_THUMB

public static final Region SLIDER_THUMB
Thumb of the Slider. The thumb of the Slider identifies the current value. To bind a style to this Region use the name SliderThumb.

SPINNER

public static final Region SPINNER
Spinner region. To bind a style to this Region use the name Spinner.

SPLIT_PANE

public static final Region SPLIT_PANE
SplitPane region. To bind a style to this Region use the name SplitPane.

SPLIT_PANE_DIVIDER

public static final Region SPLIT_PANE_DIVIDER
Divider of the SplitPane. To bind a style to this Region use the name SplitPaneDivider.

TABBED_PANE

public static final Region TABBED_PANE
TabbedPane region. To bind a style to this Region use the name TabbedPane.

TABBED_PANE_TAB

public static final Region TABBED_PANE_TAB
Region of a TabbedPane for one tab. To bind a style to this Region use the name TabbedPaneTab.

TABBED_PANE_TAB_AREA

public static final Region TABBED_PANE_TAB_AREA
Region of a TabbedPane containing the tabs. To bind a style to this Region use the name TabbedPaneTabArea.

TABBED_PANE_CONTENT

public static final Region TABBED_PANE_CONTENT
Region of a TabbedPane containing the content. To bind a style to this Region use the name TabbedPaneContent.

TABLE

public static final Region TABLE
Table region. To bind a style to this Region use the name Table.

TABLE_HEADER

public static final Region TABLE_HEADER
TableHeader region. To bind a style to this Region use the name TableHeader.

TEXT_AREA

public static final Region TEXT_AREA
TextArea region. To bind a style to this Region use the name TextArea.

TEXT_FIELD

public static final Region TEXT_FIELD
TextField region. To bind a style to this Region use the name TextField.

TEXT_PANE

public static final Region TEXT_PANE
TextPane region. To bind a style to this Region use the name TextPane.

TOGGLE_BUTTON

public static final Region TOGGLE_BUTTON
ToggleButton region. To bind a style to this Region use the name ToggleButton.

TOOL_BAR

public static final Region TOOL_BAR
ToolBar region. To bind a style to this Region use the name ToolBar.

TOOL_BAR_CONTENT

public static final Region TOOL_BAR_CONTENT
Region of the ToolBar containing the content. To bind a style to this Region use the name ToolBarContent.

TOOL_BAR_DRAG_WINDOW

public static final Region TOOL_BAR_DRAG_WINDOW
Region for the Window containing the ToolBar. To bind a style to this Region use the name ToolBarDragWindow.

TOOL_TIP

public static final Region TOOL_TIP
ToolTip region. To bind a style to this Region use the name ToolTip.

TOOL_BAR_SEPARATOR

public static final Region TOOL_BAR_SEPARATOR
ToolBar separator region. To bind a style to this Region use the name ToolBarSeparator.

TREE

public static final Region TREE
Tree region. To bind a style to this Region use the name Tree.

TREE_CELL

public static final Region TREE_CELL
Region of the Tree for one cell. To bind a style to this Region use the name TreeCell.

VIEWPORT

public static final Region VIEWPORT
Viewport region. To bind a style to this Region use the name Viewport.

Constructor Detail

Region

protected Region(String name,
                 String ui,
                 boolean subregion)
Creates a Region with the specified name. This should only be used if you are creating your own JComponent subclass with a custom ComponentUI class.

Parameters:
name - Name of the region
ui - String that will be returned from component.getUIClassID. This will be null if this is a subregion.
subregion - Whether or not this is a subregion.
Method Detail

isSubregion

public boolean isSubregion()
Returns true if the Region is a subregion of a Component, otherwise false. For example, Region.BUTTON corresponds do a Component so that Region.BUTTON.isSubregion() returns false.

Returns:
true if the Region is a subregion of a Component.

getName

public String getName()
Returns the name of the region.

Returns:
name of the Region.

toString

public String toString()
Returns the name of the Region.

Overrides:
toString in class Object
Returns:
name of the Region.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SynthConstants

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.synth
Interface SynthConstants

public interface SynthConstants

Constants used by Synth. Not all Components support all states. A Component will at least be in one of the primary states. That is, the return value from SynthContext.getComponentState() will at least be one of ENABLED, MOUSE_OVER, PRESSED or DISABLED, and may also contain FOCUSED, SELECTED or DEFAULT.

Since:
1.5

Field Summary
static int | DEFAULT Indicates the region is the default.
static int | DISABLED Primary state indicating the region is not enabled.
static int | ENABLED Primary state indicating the component is enabled.
static int | FOCUSED Indicates the region has focus.
static int | MOUSE_OVER Primary state indicating the mouse is over the region.
static int | PRESSED Primary state indicating the region is in a pressed state.
static int | SELECTED Indicates the region is selected.

Field Detail

ENABLED

static final int ENABLED
Primary state indicating the component is enabled.

See Also:
Constant Field Values

MOUSE_OVER

static final int MOUSE_OVER
Primary state indicating the mouse is over the region.

See Also:
Constant Field Values

PRESSED

static final int PRESSED
Primary state indicating the region is in a pressed state. Pressed does not necessarily mean the user has pressed the mouse button.

See Also:
Constant Field Values

DISABLED

static final int DISABLED
Primary state indicating the region is not enabled.

See Also:
Constant Field Values

FOCUSED

static final int FOCUSED
Indicates the region has focus.

See Also:
Constant Field Values

SELECTED

static final int SELECTED
Indicates the region is selected.

See Also:
Constant Field Values

DEFAULT

static final int DEFAULT
Indicates the region is the default. This is typically used for buttons to indicate this button is somehow special.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SynthContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.synth
Class SynthContext

java.lang.Object
    extended by  javax.swing.plaf.synth.SynthContext

public class SynthContext
extends Object

An immutable transient object containing contextual information about a Region. A SynthContext should only be considered valid for the duration of the method it is passed to. In other words you should not cache a SynthContext that is passed to you and expect it to remain valid.

Since:
1.5

Constructor Summary
SynthContext(JComponent component, Region region, SynthStyle style, int state)
Creates a SynthContext with the specified values.
Method Summary
JComponent | getComponent() Returns the hosting component containing the region.
int | getComponentState() Returns the state of the widget, which is a bitmask of the values defined in SynthConstants.
Region | getRegion() Returns the Region identifying this state.
SynthStyle | getStyle() Returns the style associated with this Region.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SynthContext

public SynthContext(JComponent component,
                    Region region,
                    SynthStyle style,
                    int state)
Creates a SynthContext with the specified values. This is meant for subclasses and custom UI implementors. You very rarely need to construct a SynthContext, though some methods will take one.

Parameters:
component - JComponent
region - Identifies the portion of the JComponent
style - Style associated with the component
state - State of the component as defined in SynthConstants.
Throws:
NullPointerException - if component, region of style is null.
Method Detail

getComponent

public JComponent getComponent()
Returns the hosting component containing the region.

Returns:
Hosting Component

getRegion

public Region getRegion()
Returns the Region identifying this state.

Returns:
Region of the hosting component

getStyle

public SynthStyle getStyle()
Returns the style associated with this Region.

Returns:
SynthStyle associated with the region.

getComponentState

public int getComponentState()
Returns the state of the widget, which is a bitmask of the values defined in SynthConstants. A region will at least be in one of ENABLED, MOUSE_OVER, PRESSED or DISABLED.

Returns:
State of Component
See Also:
SynthConstants
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SynthGraphicsUtils

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.synth
Class SynthGraphicsUtils

java.lang.Object
    extended by  javax.swing.plaf.synth.SynthGraphicsUtils

public class SynthGraphicsUtils
extends Object

Wrapper for primitive graphics calls.

Since:
1.5

Constructor Summary
SynthGraphicsUtils()
Creates a SynthGraphicsUtils.
Method Summary
int | computeStringWidth(SynthContext ss, Font font, FontMetrics metrics, String text) Returns the size of the passed in string.
void | drawLine(SynthContext context, Object paintKey, Graphics g, int x1, int y1, int x2, int y2) Draws a line between the two end points.
void | drawLine(SynthContext context, Object paintKey, Graphics g, int x1, int y1, int x2, int y2, Object styleKey) Draws a line between the two end points.
int | getMaximumCharHeight(SynthContext context) Returns the maximum height of the the Font from the passed in SynthContext.
Dimension | getMaximumSize(SynthContext ss, Font font, String text, Icon icon, int hAlign, int vAlign, int hTextPosition, int vTextPosition, int iconTextGap, int mnemonicIndex) Returns the maximum size needed to properly render an icon and text.
Dimension | getMinimumSize(SynthContext ss, Font font, String text, Icon icon, int hAlign, int vAlign, int hTextPosition, int vTextPosition, int iconTextGap, int mnemonicIndex) Returns the minimum size needed to properly render an icon and text.
Dimension | getPreferredSize(SynthContext ss, Font font, String text, Icon icon, int hAlign, int vAlign, int hTextPosition, int vTextPosition, int iconTextGap, int mnemonicIndex) Returns the preferred size needed to properly render an icon and text.
String | layoutText(SynthContext ss, FontMetrics fm, String text, Icon icon, int hAlign, int vAlign, int hTextPosition, int vTextPosition, Rectangle viewR, Rectangle iconR, Rectangle textR, int iconTextGap) Lays out text and an icon returning, by reference, the location to place the icon and text.
void | paintText(SynthContext ss, Graphics g, String text, Icon icon, int hAlign, int vAlign, int hTextPosition, int vTextPosition, int iconTextGap, int mnemonicIndex, int textOffset) Paints an icon and text.
void | paintText(SynthContext ss, Graphics g, String text, int x, int y, int mnemonicIndex) Paints text at the specified location.
void | paintText(SynthContext ss, Graphics g, String text, Rectangle bounds, int mnemonicIndex) Paints text at the specified location.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SynthGraphicsUtils

public SynthGraphicsUtils()
Creates a SynthGraphicsUtils.

Method Detail

drawLine

public void drawLine(SynthContext context,
                     Object paintKey,
                     Graphics g,
                     int x1,
                     int y1,
                     int x2,
                     int y2)
Draws a line between the two end points.

Parameters:
context - Identifies hosting region.
paintKey - Identifies the portion of the component being asked to paint, may be null.
g - Graphics object to paint to
x1 - x origin
y1 - y origin
x2 - x destination
y2 - y destination

drawLine

public void drawLine(SynthContext context,
                     Object paintKey,
                     Graphics g,
                     int x1,
                     int y1,
                     int x2,
                     int y2,
                     Object styleKey)
Draws a line between the two end points.

This implementation supports only one line style key, "dashed". The "dashed" line style is applied only to vertical and horizontal lines.

Specifying null or any key different from "dashed" will draw solid lines.

Parameters:
context - identifies hosting region
paintKey - identifies the portion of the component being asked to paint, may be null
g - Graphics object to paint to
x1 - x origin
y1 - y origin
x2 - x destination
y2 - y destination
styleKey - identifies the requested style of the line (e.g. "dashed")
Since:
1.6

layoutText

public String layoutText(SynthContext ss,
                         FontMetrics fm,
                         String text,
                         Icon icon,
                         int hAlign,
                         int vAlign,
                         int hTextPosition,
                         int vTextPosition,
                         Rectangle viewR,
                         Rectangle iconR,
                         Rectangle textR,
                         int iconTextGap)
Lays out text and an icon returning, by reference, the location to place the icon and text.

Parameters:
ss - SynthContext
fm - FontMetrics for the Font to use, this may be ignored
text - Text to layout
icon - Icon to layout
hAlign - horizontal alignment
vAlign - vertical alignment
hTextPosition - horizontal text position
vTextPosition - vertical text position
viewR - Rectangle to layout text and icon in.
iconR - Rectangle to place icon bounds in
textR - Rectangle to place text in
iconTextGap - gap between icon and text

computeStringWidth

public int computeStringWidth(SynthContext ss,
                              Font font,
                              FontMetrics metrics,
                              String text)
Returns the size of the passed in string.

Parameters:
ss - SynthContext
font - Font to use
metrics - FontMetrics, may be ignored
text - Text to get size of.

getMinimumSize

public Dimension getMinimumSize(SynthContext ss,
                                Font font,
                                String text,
                                Icon icon,
                                int hAlign,
                                int vAlign,
                                int hTextPosition,
                                int vTextPosition,
                                int iconTextGap,
                                int mnemonicIndex)
Returns the minimum size needed to properly render an icon and text.

Parameters:
ss - SynthContext
font - Font to use
text - Text to layout
icon - Icon to layout
hAlign - horizontal alignment
vAlign - vertical alignment
hTextPosition - horizontal text position
vTextPosition - vertical text position
iconTextGap - gap between icon and text
mnemonicIndex - Index into text to render the mnemonic at, -1 indicates no mnemonic.

getMaximumSize

public Dimension getMaximumSize(SynthContext ss,
                                Font font,
                                String text,
                                Icon icon,
                                int hAlign,
                                int vAlign,
                                int hTextPosition,
                                int vTextPosition,
                                int iconTextGap,
                                int mnemonicIndex)
Returns the maximum size needed to properly render an icon and text.

Parameters:
ss - SynthContext
font - Font to use
text - Text to layout
icon - Icon to layout
hAlign - horizontal alignment
vAlign - vertical alignment
hTextPosition - horizontal text position
vTextPosition - vertical text position
iconTextGap - gap between icon and text
mnemonicIndex - Index into text to render the mnemonic at, -1 indicates no mnemonic.

getMaximumCharHeight

public int getMaximumCharHeight(SynthContext context)
Returns the maximum height of the the Font from the passed in SynthContext.

Parameters:
context - SynthContext used to determine font.
Returns:
maximum height of the characters for the font from the passed in context.

getPreferredSize

public Dimension getPreferredSize(SynthContext ss,
                                  Font font,
                                  String text,
                                  Icon icon,
                                  int hAlign,
                                  int vAlign,
                                  int hTextPosition,
                                  int vTextPosition,
                                  int iconTextGap,
                                  int mnemonicIndex)
Returns the preferred size needed to properly render an icon and text.

Parameters:
ss - SynthContext
font - Font to use
text - Text to layout
icon - Icon to layout
hAlign - horizontal alignment
vAlign - vertical alignment
hTextPosition - horizontal text position
vTextPosition - vertical text position
iconTextGap - gap between icon and text
mnemonicIndex - Index into text to render the mnemonic at, -1 indicates no mnemonic.

paintText

public void paintText(SynthContext ss,
                      Graphics g,
                      String text,
                      Rectangle bounds,
                      int mnemonicIndex)
Paints text at the specified location. This will not attempt to render the text as html nor will it offset by the insets of the component.

Parameters:
ss - SynthContext
g - Graphics used to render string in.
text - Text to render
bounds - Bounds of the text to be drawn.
mnemonicIndex - Index to draw string at.

paintText

public void paintText(SynthContext ss,
                      Graphics g,
                      String text,
                      int x,
                      int y,
                      int mnemonicIndex)
Paints text at the specified location. This will not attempt to render the text as html nor will it offset by the insets of the component.

Parameters:
ss - SynthContext
g - Graphics used to render string in.
text - Text to render
x - X location to draw text at.
y - Upper left corner to draw text at.
mnemonicIndex - Index to draw string at.

paintText

public void paintText(SynthContext ss,
                      Graphics g,
                      String text,
                      Icon icon,
                      int hAlign,
                      int vAlign,
                      int hTextPosition,
                      int vTextPosition,
                      int iconTextGap,
                      int mnemonicIndex,
                      int textOffset)
Paints an icon and text. This will render the text as html, if necessary, and offset the location by the insets of the component.

Parameters:
ss - SynthContext
g - Graphics to render string and icon into
text - Text to layout
icon - Icon to layout
hAlign - horizontal alignment
vAlign - vertical alignment
hTextPosition - horizontal text position
vTextPosition - vertical text position
iconTextGap - gap between icon and text
mnemonicIndex - Index into text to render the mnemonic at, -1 indicates no mnemonic.
textOffset - Amount to offset the text when painting
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SynthLookAndFeel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.synth
Class SynthLookAndFeel

java.lang.Object
    extended by  javax.swing.LookAndFeel
        extended by  javax.swing.plaf.basic.BasicLookAndFeel
            extended by  javax.swing.plaf.synth.SynthLookAndFeel
All Implemented Interfaces:
Serializable
public class SynthLookAndFeel
extends BasicLookAndFeel

SynthLookAndFeel provides the basis for creating a customized look and feel. SynthLookAndFeel does not directly provide a look, all painting is delegated. You need to either provide a configuration file, by way of the load(java.io.InputStream, java.lang.Class) method, or provide your own SynthStyleFactory to setStyleFactory(javax.swing.plaf.synth.SynthStyleFactory). Refer to the package summary for an example of loading a file, and SynthStyleFactory for an example of providing your own SynthStyleFactory to setStyleFactory.

Warning: This class implements Serializable as a side effect of it extending BasicLookAndFeel. It is not intended to be serialized. An attempt to serialize it will result in NotSerializableException.

Since:
1.5

Constructor Summary
SynthLookAndFeel()
Creates a SynthLookAndFeel.
Method Summary
static ComponentUI | createUI(JComponent c) Creates the Synth look and feel ComponentUI for the passed in JComponent.
UIDefaults | getDefaults() Returns the defaults for this SynthLookAndFeel.
String | getDescription() Returns a textual description of SynthLookAndFeel.
String | getID() Return a string that identifies this look and feel.
String | getName() Return a short string that identifies this look and feel.
static Region | getRegion(JComponent c) Returns the Region for the JComponent c.
static SynthStyle | getStyle(JComponent c, Region region) Gets a SynthStyle for the specified region of the specified component.
static SynthStyleFactory | getStyleFactory() Returns the current SynthStyleFactory.
void | initialize() Called by UIManager when this look and feel is installed.
boolean | isNativeLookAndFeel() Returns false, SynthLookAndFeel is not a native look and feel.
boolean | isSupportedLookAndFeel() Returns true, SynthLookAndFeel is always supported.
void | load(InputStream input, Class<?> resourceBase) Loads the set of SynthStyles that will be used by this SynthLookAndFeel.
void | load(URL url) Loads the set of SynthStyles that will be used by this SynthLookAndFeel.
static void | setStyleFactory(SynthStyleFactory cache) Sets the SynthStyleFactory that the UI classes provided by synth will use to obtain a SynthStyle.
boolean | shouldUpdateStyleOnAncestorChanged() Returns whether or not the UIs should update their SynthStyles from the SynthStyleFactory when the ancestor of the JComponent changes.
void | uninitialize() Called by UIManager when this look and feel is uninstalled.
static void | updateStyles(Component c) Updates the style associated with c, and all its children.
Methods inherited from class javax.swing.plaf.basic.BasicLookAndFeel
createAudioAction, getAudioActionMap, initClassDefaults, initComponentDefaults, initSystemColorDefaults, loadSystemColors, playSound
Methods inherited from class javax.swing.LookAndFeel
getDesktopPropertyValue, getDisabledIcon, getDisabledSelectedIcon, getLayoutStyle, getSupportsWindowDecorations, installBorder, installColors, installColorsAndFont, installProperty, loadKeyBindings, makeComponentInputMap, makeIcon, makeInputMap, makeKeyBindings, provideErrorFeedback, toString, uninstallBorder
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SynthLookAndFeel

public SynthLookAndFeel()
Creates a SynthLookAndFeel.

For the returned SynthLookAndFeel to be useful you need to invoke load to specify the set of SynthStyles, or invoke setStyleFactory.

See Also:
load(java.io.InputStream, java.lang.Class), setStyleFactory(javax.swing.plaf.synth.SynthStyleFactory)
Method Detail

setStyleFactory

public static void setStyleFactory(SynthStyleFactory cache)
Sets the SynthStyleFactory that the UI classes provided by synth will use to obtain a SynthStyle.

Parameters:
cache - SynthStyleFactory the UIs should use.

getStyleFactory

public static SynthStyleFactory getStyleFactory()
Returns the current SynthStyleFactory.

Returns:
SynthStyleFactory

getStyle

public static SynthStyle getStyle(JComponent c,
                                  Region region)
Gets a SynthStyle for the specified region of the specified component. This is not for general consumption, only custom UIs should call this method.

Parameters:
c - JComponent to get the SynthStyle for
region - Identifies the region of the specified component
Returns:
SynthStyle to use.

updateStyles

public static void updateStyles(Component c)
Updates the style associated with c, and all its children. This is a lighter version of SwingUtilities.updateComponentTreeUI.

Parameters:
c - Component to update style for.

getRegion

public static Region getRegion(JComponent c)
Returns the Region for the JComponent c.

Parameters:
c - JComponent to fetch the Region for
Returns:
Region corresponding to c

createUI

public static ComponentUI createUI(JComponent c)
Creates the Synth look and feel ComponentUI for the passed in JComponent.

Parameters:
c - JComponent to create the ComponentUI for
Returns:
ComponentUI to use for c

load

public void load(InputStream input,
                 Class<?> resourceBase)
          throws ParseException
Loads the set of SynthStyles that will be used by this SynthLookAndFeel. resourceBase is used to resolve any path based resources, for example an Image would be resolved by resourceBase.getResource(path). Refer to Synth File Format for more information.

Parameters:
input - InputStream to load from
resourceBase - used to resolve any images or other resources
Throws:
ParseException - if there is an error in parsing
IllegalArgumentException - if input or resourceBase is null

load

public void load(URL url)
          throws ParseException,
                 IOException
Loads the set of SynthStyles that will be used by this SynthLookAndFeel. Path based resources are resolved relatively to the specified URL of the style. For example an Image would be resolved by new URL(synthFile, path). Refer to Synth File Format for more information.

Parameters:
url - the URL to load the set of SynthStyle from
Throws:
ParseException - if there is an error in parsing
IllegalArgumentException - if synthSet is null
IOException - if synthSet cannot be opened as an InputStream
Since:
1.6

initialize

public void initialize()
Called by UIManager when this look and feel is installed.

Overrides:
initialize in class BasicLookAndFeel
See Also:
LookAndFeel.uninitialize(), UIManager.setLookAndFeel(javax.swing.LookAndFeel)

uninitialize

public void uninitialize()
Called by UIManager when this look and feel is uninstalled.

Overrides:
uninitialize in class BasicLookAndFeel
See Also:
LookAndFeel.initialize(), UIManager.setLookAndFeel(javax.swing.LookAndFeel)

getDefaults

public UIDefaults getDefaults()
Returns the defaults for this SynthLookAndFeel.

Overrides:
getDefaults in class BasicLookAndFeel
Returns:
Defaults table.
See Also:
BasicLookAndFeel.initClassDefaults(javax.swing.UIDefaults),
BasicLookAndFeel.initSystemColorDefaults(javax.swing.UIDefaults),
BasicLookAndFeel.initComponentDefaults(javax.swing.UIDefaults)

isSupportedLookAndFeel

public boolean isSupportedLookAndFeel()
Returns true, SynthLookAndFeel is always supported.

Specified by:
isSupportedLookAndFeel in class LookAndFeel
Returns:
true.
See Also:
UIManager.setLookAndFeel(javax.swing.LookAndFeel)

isNativeLookAndFeel

public boolean isNativeLookAndFeel()
Returns false, SynthLookAndFeel is not a native look and feel.

Specified by:
isNativeLookAndFeel in class LookAndFeel
Returns:
false

getDescription

public String getDescription()
Returns a textual description of SynthLookAndFeel.

Specified by:
getDescription in class LookAndFeel
Returns:
textual description of synth.

getName

public String getName()
Return a short string that identifies this look and feel.

Specified by:
getName in class LookAndFeel
Returns:
a short string identifying this look and feel.

getID

public String getID()
Return a string that identifies this look and feel.

Specified by:
getID in class LookAndFeel
Returns:
a short string identifying this look and feel.

shouldUpdateStyleOnAncestorChanged

public boolean shouldUpdateStyleOnAncestorChanged()
Returns whether or not the UIs should update their SynthStyles from the SynthStyleFactory when the ancestor of the JComponent changes. A subclass that provided a SynthStyleFactory that based the return value from getStyle off the containment hierarchy would override this method to return true.

Returns:
whether or not the UIs should update their SynthStyles from the SynthStyleFactory when the ancestor changed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SynthPainter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.synth
Class SynthPainter

java.lang.Object
    extended by  javax.swing.plaf.synth.SynthPainter

public abstract class SynthPainter
extends Object

SynthPainter is used for painting portions of JComponents. At a minimum each JComponent has two paint methods: one for the border and one for the background. Some JComponents have more than one Region, and as a consequence more paint methods.

Instances of SynthPainter are obtained from the SynthStyle.getPainter(javax.swing.plaf.synth.SynthContext) method.

You typically supply a SynthPainter by way of Synth's file format. The following example registers a painter for all JButtons that will render the image myImage.png:

  <style id="buttonStyle">
    <imagePainter path="myImage.png" sourceInsets="2 2 2 2"
                  paintCenter="true" stretch="true"/>
    <insets top="2" bottom="2" left="2" right="2"/>
  </style>
  <bind style="buttonStyle" type="REGION" key="button"/>

SynthPainter is abstract in so far as it does no painting, all the methods are empty. While none of these methods are typed to throw an exception, subclasses can assume that valid arguments are passed in, and if not they can throw a NullPointerException or IllegalArgumentException in response to invalid arguments.

Since:
1.5

Constructor Summary
SynthPainter()
Method Summary
void | paintArrowButtonBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of an arrow button.
void | paintArrowButtonBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of an arrow button.
void | paintArrowButtonForeground(SynthContext context, Graphics g, int x, int y, int w, int h, int direction) Paints the foreground of an arrow button.
void | paintButtonBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a button.
void | paintButtonBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a button.
void | paintCheckBoxBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a check box.
void | paintCheckBoxBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a check box.
void | paintCheckBoxMenuItemBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a check box menu item.
void | paintCheckBoxMenuItemBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a check box menu item.
void | paintColorChooserBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a color chooser.
void | paintColorChooserBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a color chooser.
void | paintComboBoxBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a combo box.
void | paintComboBoxBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a combo box.
void | paintDesktopIconBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a desktop icon.
void | paintDesktopIconBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a desktop icon.
void | paintDesktopPaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a desktop pane.
void | paintDesktopPaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a desktop pane.
void | paintEditorPaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of an editor pane.
void | paintEditorPaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of an editor pane.
void | paintFileChooserBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a file chooser.
void | paintFileChooserBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a file chooser.
void | paintFormattedTextFieldBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a formatted text field.
void | paintFormattedTextFieldBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a formatted text field.
void | paintInternalFrameBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of an internal frame.
void | paintInternalFrameBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of an internal frame.
void | paintInternalFrameTitlePaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of an internal frame title pane.
void | paintInternalFrameTitlePaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of an internal frame title pane.
void | paintLabelBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a label.
void | paintLabelBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a label.
void | paintListBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a list.
void | paintListBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a list.
void | paintMenuBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a menu.
void | paintMenuBarBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a menu bar.
void | paintMenuBarBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a menu bar.
void | paintMenuBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a menu.
void | paintMenuItemBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a menu item.
void | paintMenuItemBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a menu item.
void | paintOptionPaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of an option pane.
void | paintOptionPaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of an option pane.
void | paintPanelBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a panel.
void | paintPanelBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a panel.
void | paintPasswordFieldBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a password field.
void | paintPasswordFieldBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a password field.
void | paintPopupMenuBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a popup menu.
void | paintPopupMenuBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a popup menu.
void | paintProgressBarBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a progress bar.
void | paintProgressBarBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of a progress bar.
void | paintProgressBarBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a progress bar.
void | paintProgressBarBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of a progress bar.
void | paintProgressBarForeground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the foreground of a progress bar.
void | paintRadioButtonBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a radio button.
void | paintRadioButtonBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a radio button.
void | paintRadioButtonMenuItemBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a radio button menu item.
void | paintRadioButtonMenuItemBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a radio button menu item.
void | paintRootPaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a root pane.
void | paintRootPaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a root pane.
void | paintScrollBarBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a scrollbar.
void | paintScrollBarBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of a scrollbar.
void | paintScrollBarBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a scrollbar.
void | paintScrollBarBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of a scrollbar.
void | paintScrollBarThumbBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of the thumb of a scrollbar.
void | paintScrollBarThumbBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of the thumb of a scrollbar.
void | paintScrollBarTrackBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the track of a scrollbar.
void | paintScrollBarTrackBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of the track of a scrollbar.
void | paintScrollBarTrackBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of the track of a scrollbar.
void | paintScrollBarTrackBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of the track of a scrollbar.
void | paintScrollPaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a scroll pane.
void | paintScrollPaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a scroll pane.
void | paintSeparatorBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a separator.
void | paintSeparatorBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of a separator.
void | paintSeparatorBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a separator.
void | paintSeparatorBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of a separator.
void | paintSeparatorForeground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the foreground of a separator.
void | paintSliderBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a slider.
void | paintSliderBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of a slider.
void | paintSliderBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a slider.
void | paintSliderBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of a slider.
void | paintSliderThumbBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of the thumb of a slider.
void | paintSliderThumbBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of the thumb of a slider.
void | paintSliderTrackBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the track of a slider.
void | paintSliderTrackBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of the track of a slider.
void | paintSliderTrackBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of the track of a slider.
void | paintSliderTrackBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of the track of a slider.
void | paintSpinnerBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a spinner.
void | paintSpinnerBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a spinner.
void | paintSplitPaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a split pane.
void | paintSplitPaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a split pane.
void | paintSplitPaneDividerBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the divider of a split pane.
void | paintSplitPaneDividerBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of the divider of a split pane.
void | paintSplitPaneDividerForeground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the foreground of the divider of a split pane.
void | paintSplitPaneDragDivider(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the divider, when the user is dragging the divider, of a split pane.
void | paintTabbedPaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a tabbed pane.
void | paintTabbedPaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a tabbed pane.
void | paintTabbedPaneContentBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the area that contains the content of the selected tab of a tabbed pane.
void | paintTabbedPaneContentBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of the area that contains the content of the selected tab of a tabbed pane.
void | paintTabbedPaneTabAreaBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the area behind the tabs of a tabbed pane.
void | paintTabbedPaneTabAreaBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of the area behind the tabs of a tabbed pane.
void | paintTabbedPaneTabAreaBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of the area behind the tabs of a tabbed pane.
void | paintTabbedPaneTabAreaBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of the area behind the tabs of a tabbed pane.
void | paintTabbedPaneTabBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int tabIndex) Paints the background of a tab of a tabbed pane.
void | paintTabbedPaneTabBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int tabIndex, int orientation) Paints the background of a tab of a tabbed pane.
void | paintTabbedPaneTabBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int tabIndex) Paints the border of a tab of a tabbed pane.
void | paintTabbedPaneTabBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int tabIndex, int orientation) Paints the border of a tab of a tabbed pane.
void | paintTableBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a table.
void | paintTableBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a table.
void | paintTableHeaderBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the header of a table.
void | paintTableHeaderBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of the header of a table.
void | paintTextAreaBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a text area.
void | paintTextAreaBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a text area.
void | paintTextFieldBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a text field.
void | paintTextFieldBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a text field.
void | paintTextPaneBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a text pane.
void | paintTextPaneBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a text pane.
void | paintToggleButtonBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a toggle button.
void | paintToggleButtonBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a toggle button.
void | paintToolBarBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a tool bar.
void | paintToolBarBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of a tool bar.
void | paintToolBarBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a tool bar.
void | paintToolBarBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of a tool bar.
void | paintToolBarContentBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the tool bar's content area.
void | paintToolBarContentBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of the tool bar's content area.
void | paintToolBarContentBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of the content area of a tool bar.
void | paintToolBarContentBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of the content area of a tool bar.
void | paintToolBarDragWindowBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the window containing the tool bar when it has been detached from its primary frame.
void | paintToolBarDragWindowBackground(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the background of the window containing the tool bar when it has been detached from its primary frame.
void | paintToolBarDragWindowBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of the window containing the tool bar when it has been detached from it's primary frame.
void | paintToolBarDragWindowBorder(SynthContext context, Graphics g, int x, int y, int w, int h, int orientation) Paints the border of the window containing the tool bar when it has been detached from it's primary frame.
void | paintToolTipBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a tool tip.
void | paintToolTipBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a tool tip.
void | paintTreeBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of a tree.
void | paintTreeBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a tree.
void | paintTreeCellBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the row containing a cell in a tree.
void | paintTreeCellBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of the row containing a cell in a tree.
void | paintTreeCellFocus(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the focus indicator for a cell in a tree when it has focus.
void | paintViewportBackground(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the background of the viewport.
void | paintViewportBorder(SynthContext context, Graphics g, int x, int y, int w, int h) Paints the border of a viewport.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SynthPainter

public SynthPainter()
Method Detail

paintArrowButtonBackground

public void paintArrowButtonBackground(SynthContext context,
                                       Graphics g,
                                       int x,
                                       int y,
                                       int w,
                                       int h)
Paints the background of an arrow button. Arrow buttons are created by some components, such as JScrollBar.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintArrowButtonBorder

public void paintArrowButtonBorder(SynthContext context,
                                   Graphics g,
                                   int x,
                                   int y,
                                   int w,
                                   int h)
Paints the border of an arrow button. Arrow buttons are created by some components, such as JScrollBar.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintArrowButtonForeground

public void paintArrowButtonForeground(SynthContext context,
                                       Graphics g,
                                       int x,
                                       int y,
                                       int w,
                                       int h,
                                       int direction)
Paints the foreground of an arrow button. This method is responsible for drawing a graphical representation of a direction, typically an arrow. Arrow buttons are created by some components, such as JScrollBar

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
direction - One of SwingConstants.NORTH, SwingConstants.SOUTH SwingConstants.EAST or SwingConstants.WEST

paintButtonBackground

public void paintButtonBackground(SynthContext context,
                                  Graphics g,
                                  int x,
                                  int y,
                                  int w,
                                  int h)
Paints the background of a button.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintButtonBorder

public void paintButtonBorder(SynthContext context,
                              Graphics g,
                              int x,
                              int y,
                              int w,
                              int h)
Paints the border of a button.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintCheckBoxMenuItemBackground

public void paintCheckBoxMenuItemBackground(SynthContext context,
                                            Graphics g,
                                            int x,
                                            int y,
                                            int w,
                                            int h)
Paints the background of a check box menu item.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintCheckBoxMenuItemBorder

public void paintCheckBoxMenuItemBorder(SynthContext context,
                                        Graphics g,
                                        int x,
                                        int y,
                                        int w,
                                        int h)
Paints the border of a check box menu item.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintCheckBoxBackground

public void paintCheckBoxBackground(SynthContext context,
                                    Graphics g,
                                    int x,
                                    int y,
                                    int w,
                                    int h)
Paints the background of a check box.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintCheckBoxBorder

public void paintCheckBoxBorder(SynthContext context,
                                Graphics g,
                                int x,
                                int y,
                                int w,
                                int h)
Paints the border of a check box.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintColorChooserBackground

public void paintColorChooserBackground(SynthContext context,
                                        Graphics g,
                                        int x,
                                        int y,
                                        int w,
                                        int h)
Paints the background of a color chooser.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintColorChooserBorder

public void paintColorChooserBorder(SynthContext context,
                                    Graphics g,
                                    int x,
                                    int y,
                                    int w,
                                    int h)
Paints the border of a color chooser.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintComboBoxBackground

public void paintComboBoxBackground(SynthContext context,
                                    Graphics g,
                                    int x,
                                    int y,
                                    int w,
                                    int h)
Paints the background of a combo box.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintComboBoxBorder

public void paintComboBoxBorder(SynthContext context,
                                Graphics g,
                                int x,
                                int y,
                                int w,
                                int h)
Paints the border of a combo box.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintDesktopIconBackground

public void paintDesktopIconBackground(SynthContext context,
                                       Graphics g,
                                       int x,
                                       int y,
                                       int w,
                                       int h)
Paints the background of a desktop icon.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintDesktopIconBorder

public void paintDesktopIconBorder(SynthContext context,
                                   Graphics g,
                                   int x,
                                   int y,
                                   int w,
                                   int h)
Paints the border of a desktop icon.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintDesktopPaneBackground

public void paintDesktopPaneBackground(SynthContext context,
                                       Graphics g,
                                       int x,
                                       int y,
                                       int w,
                                       int h)
Paints the background of a desktop pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintDesktopPaneBorder

public void paintDesktopPaneBorder(SynthContext context,
                                   Graphics g,
                                   int x,
                                   int y,
                                   int w,
                                   int h)
Paints the background of a desktop pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintEditorPaneBackground

public void paintEditorPaneBackground(SynthContext context,
                                      Graphics g,
                                      int x,
                                      int y,
                                      int w,
                                      int h)
Paints the background of an editor pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintEditorPaneBorder

public void paintEditorPaneBorder(SynthContext context,
                                  Graphics g,
                                  int x,
                                  int y,
                                  int w,
                                  int h)
Paints the border of an editor pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintFileChooserBackground

public void paintFileChooserBackground(SynthContext context,
                                       Graphics g,
                                       int x,
                                       int y,
                                       int w,
                                       int h)
Paints the background of a file chooser.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintFileChooserBorder

public void paintFileChooserBorder(SynthContext context,
                                   Graphics g,
                                   int x,
                                   int y,
                                   int w,
                                   int h)
Paints the border of a file chooser.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintFormattedTextFieldBackground

public void paintFormattedTextFieldBackground(SynthContext context,
                                              Graphics g,
                                              int x,
                                              int y,
                                              int w,
                                              int h)
Paints the background of a formatted text field.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintFormattedTextFieldBorder

public void paintFormattedTextFieldBorder(SynthContext context,
                                          Graphics g,
                                          int x,
                                          int y,
                                          int w,
                                          int h)
Paints the border of a formatted text field.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintInternalFrameTitlePaneBackground

public void paintInternalFrameTitlePaneBackground(SynthContext context,
                                                  Graphics g,
                                                  int x,
                                                  int y,
                                                  int w,
                                                  int h)
Paints the background of an internal frame title pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintInternalFrameTitlePaneBorder

public void paintInternalFrameTitlePaneBorder(SynthContext context,
                                              Graphics g,
                                              int x,
                                              int y,
                                              int w,
                                              int h)
Paints the border of an internal frame title pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintInternalFrameBackground

public void paintInternalFrameBackground(SynthContext context,
                                         Graphics g,
                                         int x,
                                         int y,
                                         int w,
                                         int h)
Paints the background of an internal frame.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintInternalFrameBorder

public void paintInternalFrameBorder(SynthContext context,
                                     Graphics g,
                                     int x,
                                     int y,
                                     int w,
                                     int h)
Paints the border of an internal frame.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintLabelBackground

public void paintLabelBackground(SynthContext context,
                                 Graphics g,
                                 int x,
                                 int y,
                                 int w,
                                 int h)
Paints the background of a label.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintLabelBorder

public void paintLabelBorder(SynthContext context,
                             Graphics g,
                             int x,
                             int y,
                             int w,
                             int h)
Paints the border of a label.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintListBackground

public void paintListBackground(SynthContext context,
                                Graphics g,
                                int x,
                                int y,
                                int w,
                                int h)
Paints the background of a list.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintListBorder

public void paintListBorder(SynthContext context,
                            Graphics g,
                            int x,
                            int y,
                            int w,
                            int h)
Paints the border of a list.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintMenuBarBackground

public void paintMenuBarBackground(SynthContext context,
                                   Graphics g,
                                   int x,
                                   int y,
                                   int w,
                                   int h)
Paints the background of a menu bar.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintMenuBarBorder

public void paintMenuBarBorder(SynthContext context,
                               Graphics g,
                               int x,
                               int y,
                               int w,
                               int h)
Paints the border of a menu bar.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintMenuItemBackground

public void paintMenuItemBackground(SynthContext context,
                                    Graphics g,
                                    int x,
                                    int y,
                                    int w,
                                    int h)
Paints the background of a menu item.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintMenuItemBorder

public void paintMenuItemBorder(SynthContext context,
                                Graphics g,
                                int x,
                                int y,
                                int w,
                                int h)
Paints the border of a menu item.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintMenuBackground

public void paintMenuBackground(SynthContext context,
                                Graphics g,
                                int x,
                                int y,
                                int w,
                                int h)
Paints the background of a menu.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintMenuBorder

public void paintMenuBorder(SynthContext context,
                            Graphics g,
                            int x,
                            int y,
                            int w,
                            int h)
Paints the border of a menu.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintOptionPaneBackground

public void paintOptionPaneBackground(SynthContext context,
                                      Graphics g,
                                      int x,
                                      int y,
                                      int w,
                                      int h)
Paints the background of an option pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintOptionPaneBorder

public void paintOptionPaneBorder(SynthContext context,
                                  Graphics g,
                                  int x,
                                  int y,
                                  int w,
                                  int h)
Paints the border of an option pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintPanelBackground

public void paintPanelBackground(SynthContext context,
                                 Graphics g,
                                 int x,
                                 int y,
                                 int w,
                                 int h)
Paints the background of a panel.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintPanelBorder

public void paintPanelBorder(SynthContext context,
                             Graphics g,
                             int x,
                             int y,
                             int w,
                             int h)
Paints the border of a panel.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintPasswordFieldBackground

public void paintPasswordFieldBackground(SynthContext context,
                                         Graphics g,
                                         int x,
                                         int y,
                                         int w,
                                         int h)
Paints the background of a password field.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintPasswordFieldBorder

public void paintPasswordFieldBorder(SynthContext context,
                                     Graphics g,
                                     int x,
                                     int y,
                                     int w,
                                     int h)
Paints the border of a password field.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintPopupMenuBackground

public void paintPopupMenuBackground(SynthContext context,
                                     Graphics g,
                                     int x,
                                     int y,
                                     int w,
                                     int h)
Paints the background of a popup menu.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintPopupMenuBorder

public void paintPopupMenuBorder(SynthContext context,
                                 Graphics g,
                                 int x,
                                 int y,
                                 int w,
                                 int h)
Paints the border of a popup menu.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintProgressBarBackground

public void paintProgressBarBackground(SynthContext context,
                                       Graphics g,
                                       int x,
                                       int y,
                                       int w,
                                       int h)
Paints the background of a progress bar.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintProgressBarBackground

public void paintProgressBarBackground(SynthContext context,
                                       Graphics g,
                                       int x,
                                       int y,
                                       int w,
                                       int h,
                                       int orientation)
Paints the background of a progress bar. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - one of JProgressBar.HORIZONTAL or JProgressBar.VERTICAL
Since:
1.6

paintProgressBarBorder

public void paintProgressBarBorder(SynthContext context,
                                   Graphics g,
                                   int x,
                                   int y,
                                   int w,
                                   int h)
Paints the border of a progress bar.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintProgressBarBorder

public void paintProgressBarBorder(SynthContext context,
                                   Graphics g,
                                   int x,
                                   int y,
                                   int w,
                                   int h,
                                   int orientation)
Paints the border of a progress bar. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - one of JProgressBar.HORIZONTAL or JProgressBar.VERTICAL
Since:
1.6

paintProgressBarForeground

public void paintProgressBarForeground(SynthContext context,
                                       Graphics g,
                                       int x,
                                       int y,
                                       int w,
                                       int h,
                                       int orientation)
Paints the foreground of a progress bar. is responsible for providing an indication of the progress of the progress bar.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - one of JProgressBar.HORIZONTAL or JProgressBar.VERTICAL

paintRadioButtonMenuItemBackground

public void paintRadioButtonMenuItemBackground(SynthContext context,
                                               Graphics g,
                                               int x,
                                               int y,
                                               int w,
                                               int h)
Paints the background of a radio button menu item.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintRadioButtonMenuItemBorder

public void paintRadioButtonMenuItemBorder(SynthContext context,
                                           Graphics g,
                                           int x,
                                           int y,
                                           int w,
                                           int h)
Paints the border of a radio button menu item.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintRadioButtonBackground

public void paintRadioButtonBackground(SynthContext context,
                                       Graphics g,
                                       int x,
                                       int y,
                                       int w,
                                       int h)
Paints the background of a radio button.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintRadioButtonBorder

public void paintRadioButtonBorder(SynthContext context,
                                   Graphics g,
                                   int x,
                                   int y,
                                   int w,
                                   int h)
Paints the border of a radio button.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintRootPaneBackground

public void paintRootPaneBackground(SynthContext context,
                                    Graphics g,
                                    int x,
                                    int y,
                                    int w,
                                    int h)
Paints the background of a root pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintRootPaneBorder

public void paintRootPaneBorder(SynthContext context,
                                Graphics g,
                                int x,
                                int y,
                                int w,
                                int h)
Paints the border of a root pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintScrollBarBackground

public void paintScrollBarBackground(SynthContext context,
                                     Graphics g,
                                     int x,
                                     int y,
                                     int w,
                                     int h)
Paints the background of a scrollbar.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintScrollBarBackground

public void paintScrollBarBackground(SynthContext context,
                                     Graphics g,
                                     int x,
                                     int y,
                                     int w,
                                     int h,
                                     int orientation)
Paints the background of a scrollbar. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - Orientation of the JScrollBar, one of JScrollBar.HORIZONTAL or JScrollBar.VERTICAL
Since:
1.6

paintScrollBarBorder

public void paintScrollBarBorder(SynthContext context,
                                 Graphics g,
                                 int x,
                                 int y,
                                 int w,
                                 int h)
Paints the border of a scrollbar.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintScrollBarBorder

public void paintScrollBarBorder(SynthContext context,
                                 Graphics g,
                                 int x,
                                 int y,
                                 int w,
                                 int h,
                                 int orientation)
Paints the border of a scrollbar. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - Orientation of the JScrollBar, one of JScrollBar.HORIZONTAL or JScrollBar.VERTICAL
Since:
1.6

paintScrollBarThumbBackground

public void paintScrollBarThumbBackground(SynthContext context,
                                          Graphics g,
                                          int x,
                                          int y,
                                          int w,
                                          int h,
                                          int orientation)
Paints the background of the thumb of a scrollbar. The thumb provides a graphical indication as to how much of the Component is visible in a JScrollPane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - Orientation of the JScrollBar, one of JScrollBar.HORIZONTAL or JScrollBar.VERTICAL

paintScrollBarThumbBorder

public void paintScrollBarThumbBorder(SynthContext context,
                                      Graphics g,
                                      int x,
                                      int y,
                                      int w,
                                      int h,
                                      int orientation)
Paints the border of the thumb of a scrollbar. The thumb provides a graphical indication as to how much of the Component is visible in a JScrollPane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - Orientation of the JScrollBar, one of JScrollBar.HORIZONTAL or JScrollBar.VERTICAL

paintScrollBarTrackBackground

public void paintScrollBarTrackBackground(SynthContext context,
                                          Graphics g,
                                          int x,
                                          int y,
                                          int w,
                                          int h)
Paints the background of the track of a scrollbar. The track contains the thumb.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintScrollBarTrackBackground

public void paintScrollBarTrackBackground(SynthContext context,
                                          Graphics g,
                                          int x,
                                          int y,
                                          int w,
                                          int h,
                                          int orientation)
Paints the background of the track of a scrollbar. The track contains the thumb. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - Orientation of the JScrollBar, one of JScrollBar.HORIZONTAL or JScrollBar.VERTICAL
Since:
1.6

paintScrollBarTrackBorder

public void paintScrollBarTrackBorder(SynthContext context,
                                      Graphics g,
                                      int x,
                                      int y,
                                      int w,
                                      int h)
Paints the border of the track of a scrollbar. The track contains the thumb.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintScrollBarTrackBorder

public void paintScrollBarTrackBorder(SynthContext context,
                                      Graphics g,
                                      int x,
                                      int y,
                                      int w,
                                      int h,
                                      int orientation)
Paints the border of the track of a scrollbar. The track contains the thumb. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - Orientation of the JScrollBar, one of JScrollBar.HORIZONTAL or JScrollBar.VERTICAL
Since:
1.6

paintScrollPaneBackground

public void paintScrollPaneBackground(SynthContext context,
                                      Graphics g,
                                      int x,
                                      int y,
                                      int w,
                                      int h)
Paints the background of a scroll pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintScrollPaneBorder

public void paintScrollPaneBorder(SynthContext context,
                                  Graphics g,
                                  int x,
                                  int y,
                                  int w,
                                  int h)
Paints the border of a scroll pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintSeparatorBackground

public void paintSeparatorBackground(SynthContext context,
                                     Graphics g,
                                     int x,
                                     int y,
                                     int w,
                                     int h)
Paints the background of a separator.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintSeparatorBackground

public void paintSeparatorBackground(SynthContext context,
                                     Graphics g,
                                     int x,
                                     int y,
                                     int w,
                                     int h,
                                     int orientation)
Paints the background of a separator. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JSeparator.HORIZONTAL or JSeparator.VERTICAL
Since:
1.6

paintSeparatorBorder

public void paintSeparatorBorder(SynthContext context,
                                 Graphics g,
                                 int x,
                                 int y,
                                 int w,
                                 int h)
Paints the border of a separator.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintSeparatorBorder

public void paintSeparatorBorder(SynthContext context,
                                 Graphics g,
                                 int x,
                                 int y,
                                 int w,
                                 int h,
                                 int orientation)
Paints the border of a separator. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JSeparator.HORIZONTAL or JSeparator.VERTICAL
Since:
1.6

paintSeparatorForeground

public void paintSeparatorForeground(SynthContext context,
                                     Graphics g,
                                     int x,
                                     int y,
                                     int w,
                                     int h,
                                     int orientation)
Paints the foreground of a separator.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JSeparator.HORIZONTAL or JSeparator.VERTICAL

paintSliderBackground

public void paintSliderBackground(SynthContext context,
                                  Graphics g,
                                  int x,
                                  int y,
                                  int w,
                                  int h)
Paints the background of a slider.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintSliderBackground

public void paintSliderBackground(SynthContext context,
                                  Graphics g,
                                  int x,
                                  int y,
                                  int w,
                                  int h,
                                  int orientation)
Paints the background of a slider. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JSlider.HORIZONTAL or JSlider.VERTICAL
Since:
1.6

paintSliderBorder

public void paintSliderBorder(SynthContext context,
                              Graphics g,
                              int x,
                              int y,
                              int w,
                              int h)
Paints the border of a slider.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintSliderBorder

public void paintSliderBorder(SynthContext context,
                              Graphics g,
                              int x,
                              int y,
                              int w,
                              int h,
                              int orientation)
Paints the border of a slider. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JSlider.HORIZONTAL or JSlider.VERTICAL
Since:
1.6

paintSliderThumbBackground

public void paintSliderThumbBackground(SynthContext context,
                                       Graphics g,
                                       int x,
                                       int y,
                                       int w,
                                       int h,
                                       int orientation)
Paints the background of the thumb of a slider.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JSlider.HORIZONTAL or JSlider.VERTICAL

paintSliderThumbBorder

public void paintSliderThumbBorder(SynthContext context,
                                   Graphics g,
                                   int x,
                                   int y,
                                   int w,
                                   int h,
                                   int orientation)
Paints the border of the thumb of a slider.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JSlider.HORIZONTAL or JSlider.VERTICAL

paintSliderTrackBackground

public void paintSliderTrackBackground(SynthContext context,
                                       Graphics g,
                                       int x,
                                       int y,
                                       int w,
                                       int h)
Paints the background of the track of a slider.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintSliderTrackBackground

public void paintSliderTrackBackground(SynthContext context,
                                       Graphics g,
                                       int x,
                                       int y,
                                       int w,
                                       int h,
                                       int orientation)
Paints the background of the track of a slider. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JSlider.HORIZONTAL or JSlider.VERTICAL
Since:
1.6

paintSliderTrackBorder

public void paintSliderTrackBorder(SynthContext context,
                                   Graphics g,
                                   int x,
                                   int y,
                                   int w,
                                   int h)
Paints the border of the track of a slider.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintSliderTrackBorder

public void paintSliderTrackBorder(SynthContext context,
                                   Graphics g,
                                   int x,
                                   int y,
                                   int w,
                                   int h,
                                   int orientation)
Paints the border of the track of a slider. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JSlider.HORIZONTAL or JSlider.VERTICAL
Since:
1.6

paintSpinnerBackground

public void paintSpinnerBackground(SynthContext context,
                                   Graphics g,
                                   int x,
                                   int y,
                                   int w,
                                   int h)
Paints the background of a spinner.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintSpinnerBorder

public void paintSpinnerBorder(SynthContext context,
                               Graphics g,
                               int x,
                               int y,
                               int w,
                               int h)
Paints the border of a spinner.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintSplitPaneDividerBackground

public void paintSplitPaneDividerBackground(SynthContext context,
                                            Graphics g,
                                            int x,
                                            int y,
                                            int w,
                                            int h)
Paints the background of the divider of a split pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintSplitPaneDividerBackground

public void paintSplitPaneDividerBackground(SynthContext context,
                                            Graphics g,
                                            int x,
                                            int y,
                                            int w,
                                            int h,
                                            int orientation)
Paints the background of the divider of a split pane. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JSplitPane.HORIZONTAL_SPLIT or JSplitPane.VERTICAL_SPLIT
Since:
1.6

paintSplitPaneDividerForeground

public void paintSplitPaneDividerForeground(SynthContext context,
                                            Graphics g,
                                            int x,
                                            int y,
                                            int w,
                                            int h,
                                            int orientation)
Paints the foreground of the divider of a split pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JSplitPane.HORIZONTAL_SPLIT or JSplitPane.VERTICAL_SPLIT

paintSplitPaneDragDivider

public void paintSplitPaneDragDivider(SynthContext context,
                                      Graphics g,
                                      int x,
                                      int y,
                                      int w,
                                      int h,
                                      int orientation)
Paints the divider, when the user is dragging the divider, of a split pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JSplitPane.HORIZONTAL_SPLIT or JSplitPane.VERTICAL_SPLIT

paintSplitPaneBackground

public void paintSplitPaneBackground(SynthContext context,
                                     Graphics g,
                                     int x,
                                     int y,
                                     int w,
                                     int h)
Paints the background of a split pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintSplitPaneBorder

public void paintSplitPaneBorder(SynthContext context,
                                 Graphics g,
                                 int x,
                                 int y,
                                 int w,
                                 int h)
Paints the border of a split pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTabbedPaneBackground

public void paintTabbedPaneBackground(SynthContext context,
                                      Graphics g,
                                      int x,
                                      int y,
                                      int w,
                                      int h)
Paints the background of a tabbed pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTabbedPaneBorder

public void paintTabbedPaneBorder(SynthContext context,
                                  Graphics g,
                                  int x,
                                  int y,
                                  int w,
                                  int h)
Paints the border of a tabbed pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTabbedPaneTabAreaBackground

public void paintTabbedPaneTabAreaBackground(SynthContext context,
                                             Graphics g,
                                             int x,
                                             int y,
                                             int w,
                                             int h)
Paints the background of the area behind the tabs of a tabbed pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTabbedPaneTabAreaBackground

public void paintTabbedPaneTabAreaBackground(SynthContext context,
                                             Graphics g,
                                             int x,
                                             int y,
                                             int w,
                                             int h,
                                             int orientation)
Paints the background of the area behind the tabs of a tabbed pane. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JTabbedPane.TOP, JTabbedPane.LEFT, JTabbedPane.BOTTOM, or JTabbedPane.RIGHT
Since:
1.6

paintTabbedPaneTabAreaBorder

public void paintTabbedPaneTabAreaBorder(SynthContext context,
                                         Graphics g,
                                         int x,
                                         int y,
                                         int w,
                                         int h)
Paints the border of the area behind the tabs of a tabbed pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTabbedPaneTabAreaBorder

public void paintTabbedPaneTabAreaBorder(SynthContext context,
                                         Graphics g,
                                         int x,
                                         int y,
                                         int w,
                                         int h,
                                         int orientation)
Paints the border of the area behind the tabs of a tabbed pane. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JTabbedPane.TOP, JTabbedPane.LEFT, JTabbedPane.BOTTOM, or JTabbedPane.RIGHT
Since:
1.6

paintTabbedPaneTabBackground

public void paintTabbedPaneTabBackground(SynthContext context,
                                         Graphics g,
                                         int x,
                                         int y,
                                         int w,
                                         int h,
                                         int tabIndex)
Paints the background of a tab of a tabbed pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
tabIndex - Index of tab being painted.

paintTabbedPaneTabBackground

public void paintTabbedPaneTabBackground(SynthContext context,
                                         Graphics g,
                                         int x,
                                         int y,
                                         int w,
                                         int h,
                                         int tabIndex,
                                         int orientation)
Paints the background of a tab of a tabbed pane. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
tabIndex - Index of tab being painted.
orientation - One of JTabbedPane.TOP, JTabbedPane.LEFT, JTabbedPane.BOTTOM, or JTabbedPane.RIGHT
Since:
1.6

paintTabbedPaneTabBorder

public void paintTabbedPaneTabBorder(SynthContext context,
                                     Graphics g,
                                     int x,
                                     int y,
                                     int w,
                                     int h,
                                     int tabIndex)
Paints the border of a tab of a tabbed pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
tabIndex - Index of tab being painted.

paintTabbedPaneTabBorder

public void paintTabbedPaneTabBorder(SynthContext context,
                                     Graphics g,
                                     int x,
                                     int y,
                                     int w,
                                     int h,
                                     int tabIndex,
                                     int orientation)
Paints the border of a tab of a tabbed pane. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
tabIndex - Index of tab being painted.
orientation - One of JTabbedPane.TOP, JTabbedPane.LEFT, JTabbedPane.BOTTOM, or JTabbedPane.RIGHT
Since:
1.6

paintTabbedPaneContentBackground

public void paintTabbedPaneContentBackground(SynthContext context,
                                             Graphics g,
                                             int x,
                                             int y,
                                             int w,
                                             int h)
Paints the background of the area that contains the content of the selected tab of a tabbed pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTabbedPaneContentBorder

public void paintTabbedPaneContentBorder(SynthContext context,
                                         Graphics g,
                                         int x,
                                         int y,
                                         int w,
                                         int h)
Paints the border of the area that contains the content of the selected tab of a tabbed pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTableHeaderBackground

public void paintTableHeaderBackground(SynthContext context,
                                       Graphics g,
                                       int x,
                                       int y,
                                       int w,
                                       int h)
Paints the background of the header of a table.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTableHeaderBorder

public void paintTableHeaderBorder(SynthContext context,
                                   Graphics g,
                                   int x,
                                   int y,
                                   int w,
                                   int h)
Paints the border of the header of a table.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTableBackground

public void paintTableBackground(SynthContext context,
                                 Graphics g,
                                 int x,
                                 int y,
                                 int w,
                                 int h)
Paints the background of a table.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTableBorder

public void paintTableBorder(SynthContext context,
                             Graphics g,
                             int x,
                             int y,
                             int w,
                             int h)
Paints the border of a table.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTextAreaBackground

public void paintTextAreaBackground(SynthContext context,
                                    Graphics g,
                                    int x,
                                    int y,
                                    int w,
                                    int h)
Paints the background of a text area.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTextAreaBorder

public void paintTextAreaBorder(SynthContext context,
                                Graphics g,
                                int x,
                                int y,
                                int w,
                                int h)
Paints the border of a text area.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTextPaneBackground

public void paintTextPaneBackground(SynthContext context,
                                    Graphics g,
                                    int x,
                                    int y,
                                    int w,
                                    int h)
Paints the background of a text pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTextPaneBorder

public void paintTextPaneBorder(SynthContext context,
                                Graphics g,
                                int x,
                                int y,
                                int w,
                                int h)
Paints the border of a text pane.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTextFieldBackground

public void paintTextFieldBackground(SynthContext context,
                                     Graphics g,
                                     int x,
                                     int y,
                                     int w,
                                     int h)
Paints the background of a text field.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTextFieldBorder

public void paintTextFieldBorder(SynthContext context,
                                 Graphics g,
                                 int x,
                                 int y,
                                 int w,
                                 int h)
Paints the border of a text field.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintToggleButtonBackground

public void paintToggleButtonBackground(SynthContext context,
                                        Graphics g,
                                        int x,
                                        int y,
                                        int w,
                                        int h)
Paints the background of a toggle button.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintToggleButtonBorder

public void paintToggleButtonBorder(SynthContext context,
                                    Graphics g,
                                    int x,
                                    int y,
                                    int w,
                                    int h)
Paints the border of a toggle button.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintToolBarBackground

public void paintToolBarBackground(SynthContext context,
                                   Graphics g,
                                   int x,
                                   int y,
                                   int w,
                                   int h)
Paints the background of a tool bar.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintToolBarBackground

public void paintToolBarBackground(SynthContext context,
                                   Graphics g,
                                   int x,
                                   int y,
                                   int w,
                                   int h,
                                   int orientation)
Paints the background of a tool bar. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JToolBar.HORIZONTAL or JToolBar.VERTICAL
Since:
1.6

paintToolBarBorder

public void paintToolBarBorder(SynthContext context,
                               Graphics g,
                               int x,
                               int y,
                               int w,
                               int h)
Paints the border of a tool bar.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintToolBarBorder

public void paintToolBarBorder(SynthContext context,
                               Graphics g,
                               int x,
                               int y,
                               int w,
                               int h,
                               int orientation)
Paints the border of a tool bar. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JToolBar.HORIZONTAL or JToolBar.VERTICAL
Since:
1.6

paintToolBarContentBackground

public void paintToolBarContentBackground(SynthContext context,
                                          Graphics g,
                                          int x,
                                          int y,
                                          int w,
                                          int h)
Paints the background of the tool bar's content area.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintToolBarContentBackground

public void paintToolBarContentBackground(SynthContext context,
                                          Graphics g,
                                          int x,
                                          int y,
                                          int w,
                                          int h,
                                          int orientation)
Paints the background of the tool bar's content area. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JToolBar.HORIZONTAL or JToolBar.VERTICAL
Since:
1.6

paintToolBarContentBorder

public void paintToolBarContentBorder(SynthContext context,
                                      Graphics g,
                                      int x,
                                      int y,
                                      int w,
                                      int h)
Paints the border of the content area of a tool bar.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintToolBarContentBorder

public void paintToolBarContentBorder(SynthContext context,
                                      Graphics g,
                                      int x,
                                      int y,
                                      int w,
                                      int h,
                                      int orientation)
Paints the border of the content area of a tool bar. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JToolBar.HORIZONTAL or JToolBar.VERTICAL
Since:
1.6

paintToolBarDragWindowBackground

public void paintToolBarDragWindowBackground(SynthContext context,
                                             Graphics g,
                                             int x,
                                             int y,
                                             int w,
                                             int h)
Paints the background of the window containing the tool bar when it has been detached from its primary frame.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintToolBarDragWindowBackground

public void paintToolBarDragWindowBackground(SynthContext context,
                                             Graphics g,
                                             int x,
                                             int y,
                                             int w,
                                             int h,
                                             int orientation)
Paints the background of the window containing the tool bar when it has been detached from its primary frame. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JToolBar.HORIZONTAL or JToolBar.VERTICAL
Since:
1.6

paintToolBarDragWindowBorder

public void paintToolBarDragWindowBorder(SynthContext context,
                                         Graphics g,
                                         int x,
                                         int y,
                                         int w,
                                         int h)
Paints the border of the window containing the tool bar when it has been detached from it's primary frame.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintToolBarDragWindowBorder

public void paintToolBarDragWindowBorder(SynthContext context,
                                         Graphics g,
                                         int x,
                                         int y,
                                         int w,
                                         int h,
                                         int orientation)
Paints the border of the window containing the tool bar when it has been detached from it's primary frame. This implementation invokes the method of the same name without the orientation.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
orientation - One of JToolBar.HORIZONTAL or JToolBar.VERTICAL
Since:
1.6

paintToolTipBackground

public void paintToolTipBackground(SynthContext context,
                                   Graphics g,
                                   int x,
                                   int y,
                                   int w,
                                   int h)
Paints the background of a tool tip.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintToolTipBorder

public void paintToolTipBorder(SynthContext context,
                               Graphics g,
                               int x,
                               int y,
                               int w,
                               int h)
Paints the border of a tool tip.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTreeBackground

public void paintTreeBackground(SynthContext context,
                                Graphics g,
                                int x,
                                int y,
                                int w,
                                int h)
Paints the background of a tree.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTreeBorder

public void paintTreeBorder(SynthContext context,
                            Graphics g,
                            int x,
                            int y,
                            int w,
                            int h)
Paints the border of a tree.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTreeCellBackground

public void paintTreeCellBackground(SynthContext context,
                                    Graphics g,
                                    int x,
                                    int y,
                                    int w,
                                    int h)
Paints the background of the row containing a cell in a tree.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTreeCellBorder

public void paintTreeCellBorder(SynthContext context,
                                Graphics g,
                                int x,
                                int y,
                                int w,
                                int h)
Paints the border of the row containing a cell in a tree.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintTreeCellFocus

public void paintTreeCellFocus(SynthContext context,
                               Graphics g,
                               int x,
                               int y,
                               int w,
                               int h)
Paints the focus indicator for a cell in a tree when it has focus.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintViewportBackground

public void paintViewportBackground(SynthContext context,
                                    Graphics g,
                                    int x,
                                    int y,
                                    int w,
                                    int h)
Paints the background of the viewport.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to

paintViewportBorder

public void paintViewportBorder(SynthContext context,
                                Graphics g,
                                int x,
                                int y,
                                int w,
                                int h)
Paints the border of a viewport.

Parameters:
context - SynthContext identifying the JComponent and Region to paint to
g - Graphics to paint to
x - X coordinate of the area to paint to
y - Y coordinate of the area to paint to
w - Width of the area to paint to
h - Height of the area to paint to
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SynthStyle

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.synth
Class SynthStyle

java.lang.Object
    extended by  javax.swing.plaf.synth.SynthStyle

public abstract class SynthStyle
extends Object

SynthStyle is a set of style properties. Each SynthUI references at least one SynthStyle that is obtained using a SynthStyleFactory. You typically don't need to interact with this class directly, rather you will load a Synth File Format file into SynthLookAndFeel that will create a set of SynthStyles.

Since:
1.5
See Also:
SynthLookAndFeel, SynthStyleFactory

Constructor Summary
SynthStyle()
Constructs a SynthStyle.
Method Summary
Object | get(SynthContext context, Object key) Getter for a region specific style property.
boolean | getBoolean(SynthContext context, Object key, boolean defaultValue) Convenience method to get a specific style property whose value is an Boolean.
Color | getColor(SynthContext context, ColorType type) Returns the color for the specified state.
protected abstract Color | getColorForState(SynthContext context, ColorType type) Returns the color for the specified state.
Font | getFont(SynthContext context) Returns the Font for the specified state.
protected abstract Font | getFontForState(SynthContext context) Returns the font for the specified state.
SynthGraphicsUtils | getGraphicsUtils(SynthContext context) Returns the SynthGraphicUtils for the specified context.
Icon | getIcon(SynthContext context, Object key) Convenience method to get a specific style property whose value is an Icon.
Insets | getInsets(SynthContext context, Insets insets) Returns the Insets that are used to calculate sizing information.
int | getInt(SynthContext context, Object key, int defaultValue) Convenience method to get a specific style property whose value is a Number.
SynthPainter | getPainter(SynthContext context) Returns the SynthPainter that will be used for painting.
String | getString(SynthContext context, Object key, String defaultValue) Convenience method to get a specific style property whose value is a String.
void | installDefaults(SynthContext context) Installs the necessary state from this Style on the JComponent from context.
boolean | isOpaque(SynthContext context) Returns true if the region is opaque.
void | uninstallDefaults(SynthContext context) Uninstalls any state that this style installed on the JComponent from context.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SynthStyle

public SynthStyle()
Constructs a SynthStyle.

Method Detail

getGraphicsUtils

public SynthGraphicsUtils getGraphicsUtils(SynthContext context)
Returns the SynthGraphicUtils for the specified context.

Parameters:
context - SynthContext identifying requester
Returns:
SynthGraphicsUtils

getColor

public Color getColor(SynthContext context,
                      ColorType type)
Returns the color for the specified state. This gives precedence to foreground and background of the JComponent. If the Color from the JComponent is not appropriate, or not used, this will invoke getColorForState. Subclasses should generally not have to override this, instead override getColorForState(javax.swing.plaf.synth.SynthContext, javax.swing.plaf.synth.ColorType).

Parameters:
context - SynthContext identifying requester
type - Type of color being requested.
Returns:
Color

getColorForState

protected abstract Color getColorForState(SynthContext context,
                                          ColorType type)
Returns the color for the specified state. This should NOT call any methods on the JComponent.

Parameters:
context - SynthContext identifying requester
type - Type of color being requested.
Returns:
Color to render with

getFont

public Font getFont(SynthContext context)
Returns the Font for the specified state. This redirects to the JComponent from the context as necessary. If this does not redirect to the JComponent getFontForState(javax.swing.plaf.synth.SynthContext) is invoked.

Parameters:
context - SynthContext identifying requester
Returns:
Font to render with

getFontForState

protected abstract Font getFontForState(SynthContext context)
Returns the font for the specified state. This should NOT call any method on the JComponent.

Parameters:
context - SynthContext identifying requester
Returns:
Font to render with

getInsets

public Insets getInsets(SynthContext context,
                        Insets insets)
Returns the Insets that are used to calculate sizing information.

Parameters:
context - SynthContext identifying requester
insets - Insets to place return value in.
Returns:
Sizing Insets.

getPainter

public SynthPainter getPainter(SynthContext context)
Returns the SynthPainter that will be used for painting. This may return null.

Parameters:
context - SynthContext identifying requester
Returns:
SynthPainter to use

isOpaque

public boolean isOpaque(SynthContext context)
Returns true if the region is opaque.

Parameters:
context - SynthContext identifying requester
Returns:
true if region is opaque.

get

public Object get(SynthContext context,
                  Object key)
Getter for a region specific style property.

Parameters:
context - SynthContext identifying requester
key - Property being requested.
Returns:
Value of the named property

installDefaults

public void installDefaults(SynthContext context)
Installs the necessary state from this Style on the JComponent from context.

Parameters:
context - SynthContext identifying component to install properties to.

uninstallDefaults

public void uninstallDefaults(SynthContext context)
Uninstalls any state that this style installed on the JComponent from context.

Styles should NOT depend upon this being called, in certain cases it may never be called.

Parameters:
context - SynthContext identifying component to install properties to.

getInt

public int getInt(SynthContext context,
                  Object key,
                  int defaultValue)
Convenience method to get a specific style property whose value is a Number. If the value is a Number, intValue is returned, otherwise defaultValue is returned.

Parameters:
context - SynthContext identifying requester
key - Property being requested.
defaultValue - Value to return if the property has not been specified, or is not a Number
Returns:
Value of the named property

getBoolean

public boolean getBoolean(SynthContext context,
                          Object key,
                          boolean defaultValue)
Convenience method to get a specific style property whose value is an Boolean.

Parameters:
context - SynthContext identifying requester
key - Property being requested.
defaultValue - Value to return if the property has not been specified, or is not a Boolean
Returns:
Value of the named property

getIcon

public Icon getIcon(SynthContext context,
                    Object key)
Convenience method to get a specific style property whose value is an Icon.

Parameters:
context - SynthContext identifying requester
key - Property being requested.
Returns:
Value of the named property, or null if not specified

getString

public String getString(SynthContext context,
                        Object key,
                        String defaultValue)
Convenience method to get a specific style property whose value is a String.

Parameters:
context - SynthContext identifying requester
key - Property being requested.
defaultValue - Value to return if the property has not been specified, or is not a String
Returns:
Value of the named property
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SynthStyleFactory

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf.synth
Class SynthStyleFactory

java.lang.Object
    extended by  javax.swing.plaf.synth.SynthStyleFactory

public abstract class SynthStyleFactory
extends Object

Factory used for obtaining SynthStyles. Each of the Synth ComponentUIs will call into the current SynthStyleFactory to obtain a SynthStyle for each of the distinct regions they have.

The following example creates a custom SynthStyleFactory that returns a different style based on the Region:

 class MyStyleFactory extends SynthStyleFactory {
     public SynthStyle getStyle(JComponent c, Region id) {
         if (id == Region.BUTTON) {
             return buttonStyle;
         }
         else if (id == Region.TREE) {
             return treeStyle;
         }
         return defaultStyle;
     }
 }
 SynthLookAndFeel laf = new SynthLookAndFeel();
 UIManager.setLookAndFeel(laf);
 SynthLookAndFeel.setStyleFactory(new MyStyleFactory());

Since:
1.5
See Also:
SynthStyleFactory, SynthStyle

Constructor Summary
SynthStyleFactory()
Creates a SynthStyleFactory.
Method Summary
abstract  SynthStyle getStyle(JComponent c, Region id)
Returns the style for the specified Component.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SynthStyleFactory

public SynthStyleFactory()
Creates a SynthStyleFactory.

Method Detail

getStyle

public abstract SynthStyle getStyle(JComponent c,
                                    Region id)
Returns the style for the specified Component.

Parameters:
c - Component asking for
id - Region identifier
Returns:
SynthStyle for region.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


TabbedPaneUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class TabbedPaneUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TabbedPaneUI
Direct Known Subclasses:
BasicTabbedPaneUI, MultiTabbedPaneUI
public abstract class TabbedPaneUI
extends ComponentUI

Pluggable look and feel interface for JTabbedPane.

Constructor Summary
TabbedPaneUI()
Method Summary
abstract Rectangle | getTabBounds(JTabbedPane pane, int index)
abstract int | getTabRunCount(JTabbedPane pane)
abstract int | tabForCoordinate(JTabbedPane pane, int x, int y)
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TabbedPaneUI

public TabbedPaneUI()
Method Detail

tabForCoordinate

public abstract int tabForCoordinate(JTabbedPane pane,
                                     int x,
                                     int y)

getTabBounds

public abstract Rectangle getTabBounds(JTabbedPane pane,
                                       int index)

getTabRunCount

public abstract int getTabRunCount(JTabbedPane pane)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TableHeaderUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class TableHeaderUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TableHeaderUI
Direct Known Subclasses:
BasicTableHeaderUI, MultiTableHeaderUI
public abstract class TableHeaderUI
extends ComponentUI

Pluggable look and feel interface for JTableHeader.

Constructor Summary
TableHeaderUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TableHeaderUI

public TableHeaderUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TableUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class TableUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TableUI
Direct Known Subclasses:
BasicTableUI, MultiTableUI
public abstract class TableUI
extends ComponentUI

Pluggable look and feel interface for JTable.

Constructor Summary
TableUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TableUI

public TableUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TextUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class TextUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TextUI
Direct Known Subclasses:
BasicTextUI, MultiTextUI
public abstract class TextUI
extends ComponentUI

Text editor user interface

Constructor Summary
TextUI()
Method Summary
abstract void | damageRange(JTextComponent t, int p0, int p1) Causes the portion of the view responsible for the given part of the model to be repainted.
abstract void | damageRange(JTextComponent t, int p0, int p1, Position.Bias firstBias, Position.Bias secondBias) Causes the portion of the view responsible for the given part of the model to be repainted.
abstract EditorKit | getEditorKit(JTextComponent t) Fetches the binding of services that set a policy for the type of document being edited.
abstract int | getNextVisualPositionFrom(JTextComponent t, int pos, Position.Bias b, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
abstract View | getRootView(JTextComponent t) Fetches a View with the allocation of the associated text component (i.e.
String | getToolTipText(JTextComponent t, Point pt) Returns the string to be used as the tooltip at the passed in location.
abstract Rectangle | modelToView(JTextComponent t, int pos) Converts the given location in the model to a place in the view coordinate system.
abstract Rectangle | modelToView(JTextComponent t, int pos, Position.Bias bias) Converts the given location in the model to a place in the view coordinate system.
abstract int | viewToModel(JTextComponent t, Point pt) Converts the given place in the view coordinate system to the nearest representative location in the model.
abstract int | viewToModel(JTextComponent t, Point pt, Position.Bias[] biasReturn) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TextUI

public TextUI()
Method Detail

modelToView

public abstract Rectangle modelToView(JTextComponent t,
                                      int pos)
                               throws BadLocationException
Converts the given location in the model to a place in the view coordinate system.

Parameters:
pos - the local location in the model to translate >= 0
Returns:
the coordinates as a rectangle
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document

modelToView

public abstract Rectangle modelToView(JTextComponent t,
                                      int pos,
                                      Position.Bias bias)
                               throws BadLocationException
Converts the given location in the model to a place in the view coordinate system.

Parameters:
pos - the local location in the model to translate >= 0
Returns:
the coordinates as a rectangle
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document

viewToModel

public abstract int viewToModel(JTextComponent t,
                                Point pt)
Converts the given place in the view coordinate system to the nearest representative location in the model.

Parameters:
pt - the location in the view to translate. This should be in the same coordinate system as the mouse events.
Returns:
the offset from the start of the document >= 0

viewToModel

public abstract int viewToModel(JTextComponent t,
                                Point pt,
                                Position.Bias[] biasReturn)
Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Parameters:
pt - the location in the view to translate. This should be in the same coordinate system as the mouse events.
biasReturn - filled in by this method to indicate whether the point given is closer to the previous or the next character in the model
Returns:
the location within the model that best represents the given point in the view >= 0

getNextVisualPositionFrom

public abstract int getNextVisualPositionFrom(JTextComponent t,
                                              int pos,
                                              Position.Bias b,
                                              int direction,
                                              Position.Bias[] biasRet)
                                       throws BadLocationException
Provides a way to determine the next visually represented model location that one might place a caret. Some views may not be visible, they might not be in the same order found in the model, or they just might not allow access to some of the locations in the model.

Parameters:
t - the text component for which this UI is installed
pos - the position to convert >= 0
b - the bias for the position
direction - the direction from the current position that can be thought of as the arrow keys typically found on a keyboard. This may be SwingConstants.WEST, SwingConstants.EAST, SwingConstants.NORTH, or SwingConstants.SOUTH
biasRet - an array to contain the bias for the returned position
Returns:
the location within the model that best represents the next location visual position
Throws:
BadLocationException
IllegalArgumentException - for an invalid direction

damageRange

public abstract void damageRange(JTextComponent t,
                                 int p0,
                                 int p1)
Causes the portion of the view responsible for the given part of the model to be repainted.

Parameters:
p0 - the beginning of the range >= 0
p1 - the end of the range >= p0

damageRange

public abstract void damageRange(JTextComponent t,
                                 int p0,
                                 int p1,
                                 Position.Bias firstBias,
                                 Position.Bias secondBias)
Causes the portion of the view responsible for the given part of the model to be repainted.

Parameters:
p0 - the beginning of the range >= 0
p1 - the end of the range >= p0

getEditorKit

public abstract EditorKit getEditorKit(JTextComponent t)
Fetches the binding of services that set a policy for the type of document being edited. This contains things like the commands available, stream readers and writers, etc.

Returns:
the editor kit binding

getRootView

public abstract View getRootView(JTextComponent t)
Fetches a View with the allocation of the associated text component (i.e. the root of the hierarchy) that can be traversed to determine how the model is being represented spatially.

Returns:
the view

getToolTipText

public String getToolTipText(JTextComponent t,
                             Point pt)
Returns the string to be used as the tooltip at the passed in location.

Since:
1.4
See Also:
JTextComponent.getToolTipText(java.awt.event.MouseEvent)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ToolBarUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class ToolBarUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ToolBarUI
Direct Known Subclasses:
BasicToolBarUI, MultiToolBarUI
public abstract class ToolBarUI
extends ComponentUI

Pluggable look and feel interface for JToolBar.

Constructor Summary
ToolBarUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ToolBarUI

public ToolBarUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ToolTipUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class ToolTipUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ToolTipUI
Direct Known Subclasses:
BasicToolTipUI, MultiToolTipUI
public abstract class ToolTipUI
extends ComponentUI

Pluggable look and feel interface for JToolTip.

Constructor Summary
ToolTipUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ToolTipUI

public ToolTipUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TreeUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class TreeUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TreeUI
Direct Known Subclasses:
BasicTreeUI, MultiTreeUI
public abstract class TreeUI
extends ComponentUI

Pluggable look and feel interface for JTree.

Constructor Summary
TreeUI()
Method Summary
abstract void | cancelEditing(JTree tree) Cancels the current editing session.
abstract TreePath | getClosestPathForLocation(JTree tree, int x, int y) Returns the path to the node that is closest to x,y.
abstract TreePath | getEditingPath(JTree tree) Returns the path to the element that is being edited.
abstract Rectangle | getPathBounds(JTree tree, TreePath path) Returns the Rectangle enclosing the label portion that the last item in path will be drawn into.
abstract TreePath | getPathForRow(JTree tree, int row) Returns the path for passed in row.
abstract int | getRowCount(JTree tree) Returns the number of rows that are being displayed.
abstract int | getRowForPath(JTree tree, TreePath path) Returns the row that the last item identified in path is visible at.
abstract boolean | isEditing(JTree tree) Returns true if the tree is being edited.
abstract void | startEditingAtPath(JTree tree, TreePath path) Selects the last item in path and tries to edit it.
abstract boolean | stopEditing(JTree tree) Stops the current editing session.
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TreeUI

public TreeUI()
Method Detail

getPathBounds

public abstract Rectangle getPathBounds(JTree tree,
                                        TreePath path)
Returns the Rectangle enclosing the label portion that the last item in path will be drawn into. Will return null if any component in path is currently valid.

getPathForRow

public abstract TreePath getPathForRow(JTree tree,
                                       int row)
Returns the path for passed in row. If row is not visible null is returned.

getRowForPath

public abstract int getRowForPath(JTree tree,
                                  TreePath path)
Returns the row that the last item identified in path is visible at. Will return -1 if any of the elements in path are not currently visible.

getRowCount

public abstract int getRowCount(JTree tree)
Returns the number of rows that are being displayed.

getClosestPathForLocation

public abstract TreePath getClosestPathForLocation(JTree tree,
                                                   int x,
                                                   int y)
Returns the path to the node that is closest to x,y. If there is nothing currently visible this will return null, otherwise it'll always return a valid path. If you need to test if the returned object is exactly at x, y you should get the bounds for the returned path and test x, y against that.

isEditing

public abstract boolean isEditing(JTree tree)
Returns true if the tree is being edited. The item that is being edited can be returned by getEditingPath().

stopEditing

public abstract boolean stopEditing(JTree tree)
Stops the current editing session. This has no effect if the tree isn't being edited. Returns true if the editor allows the editing session to stop.

cancelEditing

public abstract void cancelEditing(JTree tree)
Cancels the current editing session. This has no effect if the tree isn't being edited. Returns true if the editor allows the editing session to stop.

startEditingAtPath

public abstract void startEditingAtPath(JTree tree,
                                        TreePath path)
Selects the last item in path and tries to edit it. Editing will fail if the CellEditor won't allow it for the selected item.

getEditingPath

public abstract TreePath getEditingPath(JTree tree)
Returns the path to the element that is being edited.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ViewportUI

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.plaf
Class ViewportUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.ViewportUI
Direct Known Subclasses:
BasicViewportUI, MultiViewportUI
public abstract class ViewportUI
extends ComponentUI

Pluggable look and feel interface for JViewport.

Constructor Summary
ViewportUI()
Method Summary
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior, getMaximumSize, getMinimumSize, getPreferredSize, installUI, paint, uninstallUI, update
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ViewportUI

public ViewportUI()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Popup

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class Popup

java.lang.Object
    extended by  javax.swing.Popup

public class Popup
extends Object

Popups are used to display a Component to the user, typically on top of all the other Components in a particular containment hierarchy. Popups have a very small life cycle. Once you have obtained a Popup, and hidden it (invoked the hide method), you should no longer invoke any methods on it. This allows the PopupFactory to cache Popups for later use.

The general contract is that if you need to change the size of the Component, or location of the Popup, you should obtain a new Popup.

Popup does not descend from Component, rather implementations of Popup are responsible for creating and maintaining their own Components to render the requested Component to the user.

You typically do not explicitly create an instance of Popup, instead obtain one from a PopupFactory.

Since:
1.4
See Also:
PopupFactory

Constructor Summary
protected | Popup() Creates a Popup.
protected | Popup(Component owner, Component contents, int x, int y) Creates a Popup for the Component owner containing the Component contents.
Method Summary
void | hide() Hides and disposes of the Popup.
void | show() Makes the Popup visible.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Popup

protected Popup(Component owner,
                Component contents,
                int x,
                int y)
Creates a Popup for the Component owner containing the Component contents. owner is used to determine which Window the new Popup will parent the Component the Popup creates to. A null owner implies there is no valid parent. x and y specify the preferred initial location to place the Popup at. Based on screen size, or other paramaters, the Popup may not display at x and y.

Parameters:
owner - Component mouse coordinates are relative to, may be null
contents - Contents of the Popup
x - Initial x screen coordinate
y - Initial y screen coordinate
Throws:
IllegalArgumentException - if contents is null

Popup

protected Popup()
Creates a Popup. This is provided for subclasses.

Method Detail

show

public void show()
Makes the Popup visible. If the Popup is currently visible, this has no effect.

hide

public void hide()
Hides and disposes of the Popup. Once a Popup has been disposed you should no longer invoke methods on it. A disposed Popup may be reclaimed and later used based on the PopupFactory. As such, if you invoke methods on a disposed Popup, indeterminate behavior will result.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PopupFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class PopupFactory

java.lang.Object
    extended by  javax.swing.PopupFactory

public class PopupFactory
extends Object

PopupFactory, as the name implies, is used to obtain instances of Popups. Popups are used to display a Component above all other Components in a particular containment hierarchy. The general contract is that once you have obtained a Popup from a PopupFactory, you must invoke hide on the Popup. The typical usage is:

   PopupFactory factory = PopupFactory.getSharedInstance();
   Popup popup = factory.getPopup(owner, contents, x, y);
   popup.show();
   ...
   popup.hide();

Since:
1.4
See Also:
Popup

Constructor Summary
PopupFactory()
Method Summary
Popup | getPopup(Component owner, Component contents, int x, int y) Creates a Popup for the Component owner containing the Component contents.
static PopupFactory | getSharedInstance() Returns the shared PopupFactory which can be used to obtain Popups.
static void | setSharedInstance(PopupFactory factory) Sets the PopupFactory that will be used to obtain Popups.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PopupFactory

public PopupFactory()
Method Detail

setSharedInstance

public static void setSharedInstance(PopupFactory factory)
Sets the PopupFactory that will be used to obtain Popups. This will throw an IllegalArgumentException if factory is null.

Parameters:
factory - Shared PopupFactory
Throws:
IllegalArgumentException - if factory is null
See Also:
getPopup(java.awt.Component, java.awt.Component, int, int)

getSharedInstance

public static PopupFactory getSharedInstance()
Returns the shared PopupFactory which can be used to obtain Popups.

Returns:
Shared PopupFactory

getPopup

public Popup getPopup(Component owner,
                      Component contents,
                      int x,
                      int y)
               throws IllegalArgumentException
Creates a Popup for the Component owner containing the Component contents. owner is used to determine which Window the new Popup will parent the Component the Popup creates to. A null owner implies there is no valid parent. x and y specify the preferred initial location to place the Popup at. Based on screen size, or other paramaters, the Popup may not display at x and y.

Parameters:
owner - Component mouse coordinates are relative to, may be null
contents - Contents of the Popup
x - Initial x screen coordinate
y - Initial y screen coordinate
Returns:
Popup containing Contents
Throws:
IllegalArgumentException - if contents is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ProgressMonitor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class ProgressMonitor

java.lang.Object
    extended by  javax.swing.ProgressMonitor
All Implemented Interfaces:
Accessible
public class ProgressMonitor
extends Object
implements Accessible

A class to monitor the progress of some operation. If it looks like the operation will take a while, a progress dialog will be popped up. When the ProgressMonitor is created it is given a numeric range and a descriptive string. As the operation progresses, call the setProgress method to indicate how far along the [min,max] range the operation is. Initially, there is no ProgressDialog. After the first millisToDecideToPopup milliseconds (default 500) the progress monitor will predict how long the operation will take. If it is longer than millisToPopup (default 2000, 2 seconds) a ProgressDialog will be popped up.

From time to time, when the Dialog box is visible, the progress bar will be updated when setProgress is called. setProgress won't always update the progress bar, it will only be done if the amount of progress is visibly significant.

For further documentation and examples see How to Monitor Progress, a section in The Java Tutorial.

See Also:
ProgressMonitorInputStream

Nested Class Summary
protected  class ProgressMonitor.AccessibleProgressMonitor
AccessibleProgressMonitor implements accessibility support for the ProgressMonitor class.
Field Summary
protected  AccessibleContext accessibleContext
The AccessibleContext for the ProgressMonitor
Constructor Summary
ProgressMonitor(Component parentComponent, Object message, String note, int min, int max)
Constructs a graphic object that shows progress, typically by filling in a rectangular bar as the process nears completion.
Method Summary
void | close() Indicate that the operation is complete.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext for the ProgressMonitor
int | getMaximum() Returns the maximum value -- the higher end of the progress value.
int | getMillisToDecideToPopup() Returns the amount of time this object waits before deciding whether or not to popup a progress monitor.
int | getMillisToPopup() Returns the amount of time it will take for the popup to appear.
int | getMinimum() Returns the minimum value -- the lower end of the progress value.
String | getNote() Specifies the additional note that is displayed along with the progress message.
boolean | isCanceled() Returns true if the user hits the Cancel button in the progress dialog.
void | setMaximum(int m) Specifies the maximum value.
void | setMillisToDecideToPopup(int millisToDecideToPopup) Specifies the amount of time to wait before deciding whether or not to popup a progress monitor.
void | setMillisToPopup(int millisToPopup) Specifies the amount of time it will take for the popup to appear.
void | setMinimum(int m) Specifies the minimum value.
void | setNote(String note) Specifies the additional note that is displayed along with the progress message.
void | setProgress(int nv) Indicate the progress of the operation being monitored.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

accessibleContext

protected AccessibleContext accessibleContext
The AccessibleContext for the ProgressMonitor

Since:
1.5
Constructor Detail

ProgressMonitor

public ProgressMonitor(Component parentComponent,
                       Object message,
                       String note,
                       int min,
                       int max)
Constructs a graphic object that shows progress, typically by filling in a rectangular bar as the process nears completion.

Parameters:
parentComponent - the parent component for the dialog box
message - a descriptive message that will be shown to the user to indicate what operation is being monitored. This does not change as the operation progresses. See the message parameters to methods in JOptionPane.message for the range of values.
note - a short note describing the state of the operation. As the operation progresses, you can call setNote to change the note displayed. This is used, for example, in operations that iterate through a list of files to show the name of the file being processes. If note is initially null, there will be no note line in the dialog box and setNote will be ineffective
min - the lower bound of the range
max - the upper bound of the range
See Also:
JDialog, JOptionPane
Method Detail

setProgress

public void setProgress(int nv)
Indicate the progress of the operation being monitored. If the specified value is >= the maximum, the progress monitor is closed.

Parameters:
nv - an int specifying the current value, between the maximum and minimum specified for this component
See Also:
setMinimum(int), setMaximum(int), close()

close

public void close()
Indicate that the operation is complete. This happens automatically when the value set by setProgress is >= max, but it may be called earlier if the operation ends early.

getMinimum

public int getMinimum()
Returns the minimum value -- the lower end of the progress value.

Returns:
an int representing the minimum value
See Also:
setMinimum(int)

setMinimum

public void setMinimum(int m)
Specifies the minimum value.

Parameters:
m - an int specifying the minimum value
See Also:
getMinimum()

getMaximum

public int getMaximum()
Returns the maximum value -- the higher end of the progress value.

Returns:
an int representing the maximum value
See Also:
setMaximum(int)

setMaximum

public void setMaximum(int m)
Specifies the maximum value.

Parameters:
m - an int specifying the maximum value
See Also:
getMaximum()

isCanceled

public boolean isCanceled()
Returns true if the user hits the Cancel button in the progress dialog.

setMillisToDecideToPopup

public void setMillisToDecideToPopup(int millisToDecideToPopup)
Specifies the amount of time to wait before deciding whether or not to popup a progress monitor.

Parameters:
millisToDecideToPopup - an int specifying the time to wait, in milliseconds
See Also:
getMillisToDecideToPopup()

getMillisToDecideToPopup

public int getMillisToDecideToPopup()
Returns the amount of time this object waits before deciding whether or not to popup a progress monitor.

See Also:
setMillisToDecideToPopup(int)

setMillisToPopup

public void setMillisToPopup(int millisToPopup)
Specifies the amount of time it will take for the popup to appear. (If the predicted time remaining is less than this time, the popup won't be displayed.)

Parameters:
millisToPopup - an int specifying the time in milliseconds
See Also:
getMillisToPopup()

getMillisToPopup

public int getMillisToPopup()
Returns the amount of time it will take for the popup to appear.

See Also:
setMillisToPopup(int)

setNote

public void setNote(String note)
Specifies the additional note that is displayed along with the progress message. Used, for example, to show which file the is currently being copied during a multiple-file copy.

Parameters:
note - a String specifying the note to display
See Also:
getNote()

getNote

public String getNote()
Specifies the additional note that is displayed along with the progress message.

Returns:
a String specifying the note to display
See Also:
setNote(java.lang.String)

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext for the ProgressMonitor

Specified by:
getAccessibleContext in interface Accessible
Returns:
the AccessibleContext for the ProgressMonitor
Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ProgressMonitor.AccessibleProgressMonitor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class ProgressMonitor.AccessibleProgressMonitor

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  javax.swing.ProgressMonitor.AccessibleProgressMonitor
All Implemented Interfaces:
PropertyChangeListener, EventListener, AccessibleText, ChangeListener
Enclosing class:
ProgressMonitor
protected class ProgressMonitor.AccessibleProgressMonitor
extends AccessibleContext
implements AccessibleText, ChangeListener, PropertyChangeListener

AccessibleProgressMonitor implements accessibility support for the ProgressMonitor class.

Since:
1.5

Field Summary
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Constructor Summary
protected ProgressMonitor.AccessibleProgressMonitor()
AccessibleProgressMonitor constructor
Method Summary
Accessible | getAccessibleChild(int i) Returns the specified Accessible child of the object.
int | getAccessibleChildrenCount() Returns the number of accessible children of the object.
AccessibleComponent | getAccessibleComponent() Gets the AccessibleComponent associated with this object that has a graphical representation.
String | getAccessibleDescription() Gets the accessibleDescription property of this object.
int | getAccessibleIndexInParent() Gets the 0-based index of this object in its accessible parent.
String | getAccessibleName() Gets the accessibleName property of this object.
Accessible | getAccessibleParent() Gets the Accessible parent of this object.
AccessibleRole | getAccessibleRole() Gets the role of this object.
AccessibleStateSet | getAccessibleStateSet() Gets the state set of this object.
AccessibleText | getAccessibleText() Gets the AccessibleText associated with this object presenting text on the display.
AccessibleValue | getAccessibleValue() Gets the AccessibleValue associated with this object that supports a Numerical value.
String | getAfterIndex(int part, int index) Returns the String after a given index.
String | getAtIndex(int part, int index) Returns the String at a given index.
String | getBeforeIndex(int part, int index) Returns the String before a given index.
int | getCaretPosition() Returns the zero-based offset of the caret.
AttributeSet | getCharacterAttribute(int i) Returns the AttributeSet for a given character at a given index
Rectangle | getCharacterBounds(int i) Determines the bounding box of the character at the given index into the string.
int | getCharCount() Returns the number of characters (valid indicies)
int | getIndexAtPoint(Point p) Given a point in local coordinates, return the zero-based index of the character under that Point.
Locale | getLocale() Gets the locale of the component.
String | getSelectedText() Returns the portion of the text that is selected.
int | getSelectionEnd() Returns the end offset within the selected text.
int | getSelectionStart() Returns the start offset within the selected text.
void | propertyChange(PropertyChangeEvent e) This method gets called when a bound property is changed.
void | stateChanged(ChangeEvent e) Invoked when the target of the listener has changed its state.
Methods inherited from class javax.accessibility.AccessibleContext
addPropertyChangeListener, firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, removePropertyChangeListener, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ProgressMonitor.AccessibleProgressMonitor

protected ProgressMonitor.AccessibleProgressMonitor()
AccessibleProgressMonitor constructor

Method Detail

stateChanged

public void stateChanged(ChangeEvent e)
Invoked when the target of the listener has changed its state.

Specified by:
stateChanged in interface ChangeListener
Parameters:
e - a ChangeEvent object. Must not be null.
Throws:
NullPointerException - if the parameter is null.

propertyChange

public void propertyChange(PropertyChangeEvent e)
This method gets called when a bound property is changed.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
e - A PropertyChangeEvent object describing the event source and the property that has changed. Must not be null.
Throws:
NullPointerException - if the parameter is null.

getAccessibleName

public String getAccessibleName()
Gets the accessibleName property of this object. The accessibleName property of an object is a localized String that designates the purpose of the object. For example, the accessibleName property of a label or button might be the text of the label or button itself. In the case of an object that doesn't display its name, the accessibleName should still be set. For example, in the case of a text field used to enter the name of a city, the accessibleName for the en_US locale could be 'city.'

Overrides:
getAccessibleName in class AccessibleContext
Returns:
the localized name of the object; null if this object does not have a name
See Also:
AccessibleContext.setAccessibleName(java.lang.String)

getAccessibleDescription

public String getAccessibleDescription()
Gets the accessibleDescription property of this object. The accessibleDescription property of this object is a short localized phrase describing the purpose of the object. For example, in the case of a 'Cancel' button, the accessibleDescription could be 'Ignore changes and close dialog box.'

Overrides:
getAccessibleDescription in class AccessibleContext
Returns:
the localized description of the object; null if this object does not have a description
See Also:
AccessibleContext.setAccessibleDescription(java.lang.String)

getAccessibleRole

public AccessibleRole getAccessibleRole()
Gets the role of this object. The role of the object is the generic purpose or use of the class of this object. For example, the role of a push button is AccessibleRole.PUSH_BUTTON. The roles in AccessibleRole are provided so component developers can pick from a set of predefined roles. This enables assistive technologies to provide a consistent interface to various tweaked subclasses of components (e.g., use AccessibleRole.PUSH_BUTTON for all components that act like a push button) as well as distinguish between sublasses that behave differently (e.g., AccessibleRole.CHECK_BOX for check boxes and AccessibleRole.RADIO_BUTTON for radio buttons).

Note that the AccessibleRole class is also extensible, so custom component developers can define their own AccessibleRole's if the set of predefined roles is inadequate.

Specified by:
getAccessibleRole in class AccessibleContext
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Gets the state set of this object. The AccessibleStateSet of an object is composed of a set of unique AccessibleStates. A change in the AccessibleStateSet of an object will cause a PropertyChangeEvent to be fired for the ACCESSIBLE_STATE_PROPERTY property.

Specified by:
getAccessibleStateSet in class AccessibleContext
Returns:
an instance of AccessibleStateSet containing the current state set of the object
See Also:
AccessibleStateSet, AccessibleState, AccessibleContext.addPropertyChangeListener(java.beans.PropertyChangeListener)

getAccessibleParent

public Accessible getAccessibleParent()
Gets the Accessible parent of this object.

Overrides:
getAccessibleParent in class AccessibleContext
Returns:
the Accessible parent of this object; null if this object does not have an Accessible parent

getAccessibleIndexInParent

public int getAccessibleIndexInParent()
Gets the 0-based index of this object in its accessible parent.

Specified by:
getAccessibleIndexInParent in class AccessibleContext
Returns:
the 0-based index of this object in its parent; -1 if this object does not have an accessible parent.
See Also:
getAccessibleParent(),
getAccessibleChildrenCount(),
getAccessibleChild(int)

getAccessibleChildrenCount

public int getAccessibleChildrenCount()
Returns the number of accessible children of the object.

Specified by:
getAccessibleChildrenCount in class AccessibleContext
Returns:
the number of accessible children of the object.

getAccessibleChild

public Accessible getAccessibleChild(int i)
Returns the specified Accessible child of the object. The Accessible children of an Accessible object are zero-based, so the first child of an Accessible child is at index 0, the second child is at index 1, and so on.

Specified by:
getAccessibleChild in class AccessibleContext
Parameters:
i - zero-based index of child
Returns:
the Accessible child of the object
See Also:
getAccessibleChildrenCount()

getLocale

public Locale getLocale()
                 throws IllegalComponentStateException
Gets the locale of the component. If the component does not have a locale, then the locale of its parent is returned.

Specified by:
getLocale in class AccessibleContext
Returns:
this component's locale. If this component does not have a locale, the locale of its parent is returned.
Throws:
IllegalComponentStateException - If the Component does not have its own locale and has not yet been added to a containment hierarchy such that the locale can be determined from the containing parent.

getAccessibleComponent

public AccessibleComponent getAccessibleComponent()
Gets the AccessibleComponent associated with this object that has a graphical representation.

Overrides:
getAccessibleComponent in class AccessibleContext
Returns:
AccessibleComponent if supported by object; else return null
See Also:
AccessibleComponent

getAccessibleValue

public AccessibleValue getAccessibleValue()
Gets the AccessibleValue associated with this object that supports a Numerical value.

Overrides:
getAccessibleValue in class AccessibleContext
Returns:
AccessibleValue if supported by object; else return null
See Also:
AccessibleValue

getAccessibleText

public AccessibleText getAccessibleText()
Gets the AccessibleText associated with this object presenting text on the display.

Overrides:
getAccessibleText in class AccessibleContext
Returns:
AccessibleText if supported by object; else return null
See Also:
AccessibleText

getIndexAtPoint

public int getIndexAtPoint(Point p)
Given a point in local coordinates, return the zero-based index of the character under that Point. If the point is invalid, this method returns -1.

Specified by:
getIndexAtPoint in interface AccessibleText
Parameters:
p - the Point in local coordinates
Returns:
the zero-based index of the character under Point p; if Point is invalid return -1.

getCharacterBounds

public Rectangle getCharacterBounds(int i)
Determines the bounding box of the character at the given index into the string. The bounds are returned in local coordinates. If the index is invalid an empty rectangle is returned.

Specified by:
getCharacterBounds in interface AccessibleText
Parameters:
i - the index into the String
Returns:
the screen coordinates of the character's bounding box, if index is invalid return an empty rectangle.

getCharCount

public int getCharCount()
Returns the number of characters (valid indicies)

Specified by:
getCharCount in interface AccessibleText
Returns:
the number of characters

getCaretPosition

public int getCaretPosition()
Returns the zero-based offset of the caret. Note: That to the right of the caret will have the same index value as the offset (the caret is between two characters).

Specified by:
getCaretPosition in interface AccessibleText
Returns:
the zero-based offset of the caret.

getAtIndex

public String getAtIndex(int part,
                         int index)
Returns the String at a given index.

Specified by:
getAtIndex in interface AccessibleText
Parameters:
part - the CHARACTER, WORD, or SENTENCE to retrieve
index - an index within the text
Returns:
the letter, word, or sentence

getAfterIndex

public String getAfterIndex(int part,
                            int index)
Returns the String after a given index.

Specified by:
getAfterIndex in interface AccessibleText
Parameters:
part - the CHARACTER, WORD, or SENTENCE to retrieve
index - an index within the text
Returns:
the letter, word, or sentence

getBeforeIndex

public String getBeforeIndex(int part,
                             int index)
Returns the String before a given index.

Specified by:
getBeforeIndex in interface AccessibleText
Parameters:
part - the CHARACTER, WORD, or SENTENCE to retrieve
index - an index within the text
Returns:
the letter, word, or sentence

getCharacterAttribute

public AttributeSet getCharacterAttribute(int i)
Returns the AttributeSet for a given character at a given index

Specified by:
getCharacterAttribute in interface AccessibleText
Parameters:
i - the zero-based index into the text
Returns:
the AttributeSet of the character

getSelectionStart

public int getSelectionStart()
Returns the start offset within the selected text. If there is no selection, but there is a caret, the start and end offsets will be the same.

Specified by:
getSelectionStart in interface AccessibleText
Returns:
the index into the text of the start of the selection

getSelectionEnd

public int getSelectionEnd()
Returns the end offset within the selected text. If there is no selection, but there is a caret, the start and end offsets will be the same.

Specified by:
getSelectionEnd in interface AccessibleText
Returns:
the index into teh text of the end of the selection

getSelectedText

public String getSelectedText()
Returns the portion of the text that is selected.

Specified by:
getSelectedText in interface AccessibleText
Returns:
the String portion of the text that is selected
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ProgressMonitorInputStream

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class ProgressMonitorInputStream

java.lang.Object
    extended by  java.io.InputStream
        extended by  java.io.FilterInputStream
            extended by  javax.swing.ProgressMonitorInputStream
All Implemented Interfaces:
Closeable
public class ProgressMonitorInputStream
extends FilterInputStream

Monitors the progress of reading from some InputStream. This ProgressMonitor is normally invoked in roughly this form:

 InputStream in = new BufferedInputStream(
                          new ProgressMonitorInputStream(
                                  parentComponent,
                                  "Reading " + fileName,
                                  new FileInputStream(fileName)));

This creates a progress monitor to monitor the progress of reading the input stream. If it's taking a while, a ProgressDialog will be popped up to inform the user. If the user hits the Cancel button an InterruptedIOException will be thrown on the next read. All the right cleanup is done when the stream is closed.

For further documentation and examples see How to Monitor Progress, a section in The Java Tutorial.

See Also:
ProgressMonitor, JOptionPane

Field Summary
Fields inherited from class java.io.FilterInputStream
in
Constructor Summary
ProgressMonitorInputStream(Component parentComponent, Object message, InputStream in)
Constructs an object to monitor the progress of an input stream.
Method Summary
void | close() Overrides FilterInputStream.close to close the progress monitor as well as the stream.
ProgressMonitor | getProgressMonitor() Get the ProgressMonitor object being used by this stream.
int | read() Overrides FilterInputStream.read to update the progress monitor after the read.
int | read(byte[] b) Overrides FilterInputStream.read to update the progress monitor after the read.
int | read(byte[] b, int off, int len) Overrides FilterInputStream.read to update the progress monitor after the read.
void | reset() Overrides FilterInputStream.reset to reset the progress monitor as well as the stream.
long | skip(long n) Overrides FilterInputStream.skip to update the progress monitor after the skip.
Methods inherited from class java.io.FilterInputStream
available, mark, markSupported
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ProgressMonitorInputStream

public ProgressMonitorInputStream(Component parentComponent,
                                  Object message,
                                  InputStream in)
Constructs an object to monitor the progress of an input stream.

Parameters:
message - Descriptive text to be placed in the dialog box if one is popped up.
parentComponent - The component triggering the operation being monitored.
in - The input stream to be monitored.
Method Detail

getProgressMonitor

public ProgressMonitor getProgressMonitor()
Get the ProgressMonitor object being used by this stream. Normally this isn't needed unless you want to do something like change the descriptive text partway through reading the file.

Returns:
the ProgressMonitor object used by this object

read

public int read()
         throws IOException
Overrides FilterInputStream.read to update the progress monitor after the read.

Overrides:
read in class FilterInputStream
Returns:
the next byte of data, or -1 if the end of the stream is reached.
Throws:
IOException - if an I/O error occurs.
See Also:
FilterInputStream.in

read

public int read(byte[] b)
         throws IOException
Overrides FilterInputStream.read to update the progress monitor after the read.

Overrides:
read in class FilterInputStream
Parameters:
b - the buffer into which the data is read.
Returns:
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.
Throws:
IOException - if an I/O error occurs.
See Also:
FilterInputStream.read(byte[], int, int)

read

public int read(byte[] b,
                int off,
                int len)
         throws IOException
Overrides FilterInputStream.read to update the progress monitor after the read.

Overrides:
read in class FilterInputStream
Parameters:
b - the buffer into which the data is read.
off - the start offset in the destination array b
len - the maximum number of bytes read.
Returns:
the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.
Throws:
IOException - if an I/O error occurs.
See Also:
FilterInputStream.in

skip

public long skip(long n)
          throws IOException
Overrides FilterInputStream.skip to update the progress monitor after the skip.

Overrides:
skip in class FilterInputStream
Parameters:
n - the number of bytes to be skipped.
Returns:
the actual number of bytes skipped.
Throws:
IOException - if the stream does not support seek, or if some other I/O error occurs.

close

public void close()
           throws IOException
Overrides FilterInputStream.close to close the progress monitor as well as the stream.

Specified by:
close in interface Closeable
Overrides:
close in class FilterInputStream
Throws:
IOException - if an I/O error occurs.
See Also:
FilterInputStream.in

reset

public void reset()
           throws IOException
Overrides FilterInputStream.reset to reset the progress monitor as well as the stream.

Overrides:
reset in class FilterInputStream
Throws:
IOException - if the stream has not been marked or if the mark has been invalidated.
See Also:
FilterInputStream.in, FilterInputStream.mark(int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Renderer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface Renderer

public interface Renderer

Defines the requirements for an object responsible for "rendering" (displaying) a value.

Method Summary
Component | getComponent() Returns the component used to render the value.
void | setValue(Object aValue, boolean isSelected) Specifies the value to display and whether or not the value should be portrayed as "currently selected".

Method Detail

setValue

void setValue(Object aValue,
              boolean isSelected)
Specifies the value to display and whether or not the value should be portrayed as "currently selected".

Parameters:
aValue - an Object object
isSelected - a boolean

getComponent

Component getComponent()
Returns the component used to render the value.

Returns:
the Component responsible for displaying the value
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RepaintManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class RepaintManager

java.lang.Object
    extended by  javax.swing.RepaintManager

public class RepaintManager
extends Object

This class manages repaint requests, allowing the number of repaints to be minimized, for example by collapsing multiple requests into a single repaint for members of a component tree.

As of 1.6 RepaintManager handles repaint requests for Swing's top level components (JApplet, JWindow, JFrame and JDialog). Any calls to repaint on one of these will call into the appropriate addDirtyRegion method.

Constructor Summary
RepaintManager()
Create a new RepaintManager instance.
Method Summary
void | addDirtyRegion(Applet applet, int x, int y, int w, int h) Adds applet to the list of Components that need to be repainted.
void | addDirtyRegion(JComponent c, int x, int y, int w, int h) Add a component in the list of components that should be refreshed.
void | addDirtyRegion(Window window, int x, int y, int w, int h) Adds window to the list of Components that need to be repainted.
void | addInvalidComponent(JComponent invalidComponent) Mark the component as in need of layout and queue a runnable for the event dispatching thread that will validate the components first isValidateRoot() ancestor.
static RepaintManager | currentManager(Component c) Return the RepaintManager for the calling thread given a Component.
static RepaintManager | currentManager(JComponent c) Return the RepaintManager for the calling thread given a JComponent.
Rectangle | getDirtyRegion(JComponent aComponent) Return the current dirty region for a component.
Dimension | getDoubleBufferMaximumSize() Returns the maximum double buffer size.
Image | getOffscreenBuffer(Component c, int proposedWidth, int proposedHeight) Return the offscreen buffer that should be used as a double buffer with the component c.
Image | getVolatileOffscreenBuffer(Component c, int proposedWidth, int proposedHeight) Return a volatile offscreen buffer that should be used as a double buffer with the specified component c.
boolean | isCompletelyDirty(JComponent aComponent) Convenience method that returns true if aComponent will be completely painted during the next paintDirtyRegions().
boolean | isDoubleBufferingEnabled() Returns true if this RepaintManager is double buffered.
void | markCompletelyClean(JComponent aComponent) Mark a component completely clean.
void | markCompletelyDirty(JComponent aComponent) Mark a component completely dirty.
void | paintDirtyRegions() Paint all of the components that have been marked dirty.
void | removeInvalidComponent(JComponent component) Remove a component from the list of invalid components.
static void | setCurrentManager(RepaintManager aRepaintManager) Set the RepaintManager that should be used for the calling thread.
void | setDoubleBufferingEnabled(boolean aFlag) Enables or disables double buffering in this RepaintManager.
void | setDoubleBufferMaximumSize(Dimension d) Set the maximum double buffer size.
String | toString() Returns a string that displays and identifies this object's properties.
void | validateInvalidComponents() Validate all of the components that have been marked invalid.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RepaintManager

public RepaintManager()
Create a new RepaintManager instance. You rarely call this constructor. directly. To get the default RepaintManager, use RepaintManager.currentManager(JComponent) (normally "this").

Method Detail

currentManager

public static RepaintManager currentManager(Component c)
Return the RepaintManager for the calling thread given a Component.

Parameters:
c - a Component -- unused in the default implementation, but could be used by an overridden version to return a different RepaintManager depending on the Component
Returns:
the RepaintManager object

currentManager

public static RepaintManager currentManager(JComponent c)
Return the RepaintManager for the calling thread given a JComponent.

Note: This method exists for backward binary compatibility with earlier versions of the Swing library. It simply returns the result returned by currentManager(Component).

Parameters:
c - a JComponent -- unused
Returns:
the RepaintManager object

setCurrentManager

public static void setCurrentManager(RepaintManager aRepaintManager)
Set the RepaintManager that should be used for the calling thread. aRepaintManager will become the current RepaintManager for the calling thread's thread group.

Parameters:
aRepaintManager - the RepaintManager object to use

addInvalidComponent

public void addInvalidComponent(JComponent invalidComponent)
Mark the component as in need of layout and queue a runnable for the event dispatching thread that will validate the components first isValidateRoot() ancestor.

See Also:
JComponent.isValidateRoot(), removeInvalidComponent(javax.swing.JComponent)

removeInvalidComponent

public void removeInvalidComponent(JComponent component)
Remove a component from the list of invalid components.

See Also:
addInvalidComponent(javax.swing.JComponent)

addDirtyRegion

public void addDirtyRegion(JComponent c,
                           int x,
                           int y,
                           int w,
                           int h)
Add a component in the list of components that should be refreshed. If c already has a dirty region, the rectangle (x,y,w,h) will be unioned with the region that should be redrawn.

Parameters:
c - Component to repaint, null results in nothing happening.
x - X coordinate of the region to repaint
y - Y coordinate of the region to repaint
w - Width of the region to repaint
h - Height of the region to repaint
See Also:
JComponent.repaint(long, int, int, int, int)

addDirtyRegion

public void addDirtyRegion(Window window,
                           int x,
                           int y,
                           int w,
                           int h)
Adds window to the list of Components that need to be repainted.

Parameters:
window - Window to repaint, null results in nothing happening.
x - X coordinate of the region to repaint
y - Y coordinate of the region to repaint
w - Width of the region to repaint
h - Height of the region to repaint
Since:
1.6
See Also:
JFrame.repaint(long, int, int, int, int),
JWindow.repaint(long, int, int, int, int),
JDialog.repaint(long, int, int, int, int)

addDirtyRegion

public void addDirtyRegion(Applet applet,
                           int x,
                           int y,
                           int w,
                           int h)
Adds applet to the list of Components that need to be repainted.

Parameters:
applet - Applet to repaint, null results in nothing happening.
x - X coordinate of the region to repaint
y - Y coordinate of the region to repaint
w - Width of the region to repaint
h - Height of the region to repaint
Since:
1.6
See Also:
JApplet.repaint(long, int, int, int, int)

getDirtyRegion

public Rectangle getDirtyRegion(JComponent aComponent)
Return the current dirty region for a component. Return an empty rectangle if the component is not dirty.

markCompletelyDirty

public void markCompletelyDirty(JComponent aComponent)
Mark a component completely dirty. aComponent will be completely painted during the next paintDirtyRegions() call.

markCompletelyClean

public void markCompletelyClean(JComponent aComponent)
Mark a component completely clean. aComponent will not get painted during the next paintDirtyRegions() call.

isCompletelyDirty

public boolean isCompletelyDirty(JComponent aComponent)
Convenience method that returns true if aComponent will be completely painted during the next paintDirtyRegions(). If computing dirty regions is expensive for your component, use this method and avoid computing dirty region if it return true.

validateInvalidComponents

public void validateInvalidComponents()
Validate all of the components that have been marked invalid.

See Also:
addInvalidComponent(javax.swing.JComponent)

paintDirtyRegions

public void paintDirtyRegions()
Paint all of the components that have been marked dirty.

See Also:
addDirtyRegion(javax.swing.JComponent, int, int, int, int)

toString

public String toString()
Returns a string that displays and identifies this object's properties.

Overrides:
toString in class Object
Returns:
a String representation of this object

getOffscreenBuffer

public Image getOffscreenBuffer(Component c,
                                int proposedWidth,
                                int proposedHeight)
Return the offscreen buffer that should be used as a double buffer with the component c. By default there is a double buffer per RepaintManager. The buffer might be smaller than (proposedWidth,proposedHeight) This happens when the maximum double buffer size as been set for the receiving repaint manager.

getVolatileOffscreenBuffer

public Image getVolatileOffscreenBuffer(Component c,
                                        int proposedWidth,
                                        int proposedHeight)
Return a volatile offscreen buffer that should be used as a double buffer with the specified component c. The image returned will be an instance of VolatileImage, or null if a VolatileImage object could not be instantiated. This buffer might be smaller than (proposedWidth,proposedHeight). This happens when the maximum double buffer size has been set for this repaint manager.

Since:
1.4
See Also:
VolatileImage

setDoubleBufferMaximumSize

public void setDoubleBufferMaximumSize(Dimension d)
Set the maximum double buffer size.

getDoubleBufferMaximumSize

public Dimension getDoubleBufferMaximumSize()
Returns the maximum double buffer size.

Returns:
a Dimension object representing the maximum size

setDoubleBufferingEnabled

public void setDoubleBufferingEnabled(boolean aFlag)
Enables or disables double buffering in this RepaintManager. CAUTION: The default value for this property is set for optimal paint performance on the given platform and it is not recommended that programs modify this property directly.

Parameters:
aFlag - true to activate double buffering
See Also:
isDoubleBufferingEnabled()

isDoubleBufferingEnabled

public boolean isDoubleBufferingEnabled()
Returns true if this RepaintManager is double buffered. The default value for this property may vary from platform to platform. On platforms where native double buffering is supported in the AWT, the default value will be false to avoid unnecessary buffering in Swing. On platforms where native double buffering is not supported, the default value will be true.

Returns:
true if this object is double buffered
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RootPaneContainer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface RootPaneContainer

All Known Implementing Classes:
JApplet, JDialog, JFrame, JInternalFrame, JWindow
public interface RootPaneContainer

This interface is implemented by components that have a single JRootPane child: JDialog, JFrame, JWindow, JApplet, JInternalFrame. The methods in this interface are just covers for the JRootPane properties, e.g. getContentPane() is generally implemented like this:

     public Container getContentPane() {
         return getRootPane().getContentPane();
     }
This interface serves as a marker for Swing GUI builders that need to treat components like JFrame, that contain a single JRootPane, specially. For example in a GUI builder, dropping a component on a RootPaneContainer would be interpreted as frame.getContentPane().add(child).

For conveniance JFrame, JDialog, JWindow, JApplet and JInternalFrame, by default, forward, by default, all calls to the add, remove and setLayout methods, to the contentPane. This means you can call:

 rootPaneContainer.add(component);
instead of:
 rootPaneContainer.getContentPane().add(component);

The behavior of the add and setLayout methods for JFrame, JDialog, JWindow, JApplet and JInternalFrame is controlled by the rootPaneCheckingEnabled property. If this property is true (the default), then calls to these methods are forwarded to the contentPane; if false, these methods operate directly on the RootPaneContainer. This property is only intended for subclasses, and is therefore protected.

See Also:
JRootPane, JFrame, JDialog, JWindow, JApplet, JInternalFrame

Method Summary
Container | getContentPane() Returns the contentPane.
Component | getGlassPane() Returns the glassPane.
JLayeredPane | getLayeredPane() Returns the layeredPane.
JRootPane | getRootPane() Return this component's single JRootPane child.
void | setContentPane(Container contentPane) The "contentPane" is the primary container for application specific components.
void | setGlassPane(Component glassPane) The glassPane is always the first child of the rootPane and the rootPanes layout manager ensures that it's always as big as the rootPane.
void | setLayeredPane(JLayeredPane layeredPane) A Container that manages the contentPane and in some cases a menu bar.

Method Detail

getRootPane

JRootPane getRootPane()
Return this component's single JRootPane child. A conventional implementation of this interface will have all of the other methods indirect through this one. The rootPane has two children: the glassPane and the layeredPane.

Returns:
this components single JRootPane child.
See Also:
JRootPane

setContentPane

void setContentPane(Container contentPane)
The "contentPane" is the primary container for application specific components. Applications should add children to the contentPane, set its layout manager, and so on.

The contentPane may not be null.

Generally implemented with getRootPane().setContentPane(contentPane);

Parameters:
contentPane - the Container to use for the contents of this JRootPane
Throws:
IllegalComponentStateException - (a runtime exception) if the content pane parameter is null
See Also:
JRootPane.getContentPane(), getContentPane()

getContentPane

Container getContentPane()
Returns the contentPane.

Returns:
the value of the contentPane property.
See Also:
setContentPane(java.awt.Container)

setLayeredPane

void setLayeredPane(JLayeredPane layeredPane)
A Container that manages the contentPane and in some cases a menu bar. The layeredPane can be used by descendants that want to add a child to the RootPaneContainer that isn't layout managed. For example an internal dialog or a drag and drop effect component.

The layeredPane may not be null.

Generally implemented with

    getRootPane().setLayeredPane(layeredPane);

Throws:
IllegalComponentStateException - (a runtime exception) if the layered pane parameter is null
See Also:
getLayeredPane(), JRootPane.getLayeredPane()

getLayeredPane

JLayeredPane getLayeredPane()
Returns the layeredPane.

Returns:
the value of the layeredPane property.
See Also:
setLayeredPane(javax.swing.JLayeredPane)

setGlassPane

void setGlassPane(Component glassPane)
The glassPane is always the first child of the rootPane and the rootPanes layout manager ensures that it's always as big as the rootPane. By default it's transparent and not visible. It can be used to temporarily grab all keyboard and mouse input by adding listeners and then making it visible. by default it's not visible.

The glassPane may not be null.

Generally implemented with getRootPane().setGlassPane(glassPane);

See Also:
getGlassPane(), JRootPane.setGlassPane(java.awt.Component)

getGlassPane

Component getGlassPane()
Returns the glassPane.

Returns:
the value of the glassPane property.
See Also:
setGlassPane(java.awt.Component)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RowFilter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class RowFilter<M,I>

java.lang.Object
    extended by  javax.swing.RowFilter<M,I>
Type Parameters:
M - the type of the model; for example PersonModel
I - the type of the identifier; when using TableRowSorter this will be Integer
public abstract class RowFilter<M,I>
extends Object

RowFilter is used to filter out entries from the model so that they are not shown in the view. For example, a RowFilter associated with a JTable might only allow rows that contain a column with a specific string. The meaning of entry depends on the component type. For example, when a filter is associated with a JTable, an entry corresponds to a row; when associated with a JTree, an entry corresponds to a node.

Subclasses must override the include method to indicate whether the entry should be shown in the view. The Entry argument can be used to obtain the values in each of the columns in that entry. The following example shows an include method that allows only entries containing one or more values starting with the string "a":

 RowFilter<Object,Object> startsWithAFilter = new RowFilter<Object,Object>() {
   public boolean include(Entry<? extends Object, ? extends Object> entry) {
     for (int i = entry.getValueCount() - 1; i >= 0; i--) {
       if (entry.getStringValue(i).startsWith("a")) {
         // The value starts with "a", include it
         return true;
       }
     }
     // None of the columns start with "a"; return false so that this
     // entry is not shown
     return false;
   }
 };
RowFilter has two formal type parameters that allow you to create a RowFilter for a specific model. For example, the following assumes a specific model that is wrapping objects of type Person. Only Persons with an age over 20 will be shown:
 RowFilter<PersonModel,Integer> ageFilter = new RowFilter<PersonModel,Integer>() {
   public boolean include(Entry<? extends PersonModel, ? extends Integer> entry) {
     PersonModel personModel = entry.getModel();
     Person person = personModel.getPerson(entry.getIdentifier());
     if (person.getAge() > 20) {
       // Returning true indicates this row should be shown.
       return true;
     }
     // Age is <= 20, don't show it.
     return false;
   }
 };
 PersonModel model = createPersonModel();
 TableRowSorter<PersonModel> sorter = new TableRowSorter<PersonModel>(model);
 sorter.setRowFilter(ageFilter);

Since:
1.6
See Also:
TableRowSorter

Nested Class Summary
static class | RowFilter.ComparisonType Enumeration of the possible comparison values supported by some of the default RowFilters.
static class | RowFilter.Entry<M,I> An Entry object is passed to instances of RowFilter, allowing the filter to get the value of the entry's data, and thus to determine whether the entry should be shown.
Constructor Summary
RowFilter()
Method Summary
static
<M,I> RowFilter<M,I>
andFilter(Iterable<? extends RowFilter<? super M,? super I>> filters)
Returns a RowFilter that includes entries if all of the supplied filters include the entry.
static
<M,I> RowFilter<M,I>
dateFilter(RowFilter.ComparisonType type, Date date, int... indices)
Returns a RowFilter that includes entries that have at least one Date value meeting the specified criteria.
abstract  boolean include(RowFilter.Entry<? extends M,? extends I> entry)
Returns true if the specified entry should be shown; returns false if the entry should be hidden.
static
<M,I> RowFilter<M,I>
notFilter(RowFilter<M,I> filter)
Returns a RowFilter that includes entries if the supplied filter does not include the entry.
static
<M,I> RowFilter<M,I>
numberFilter(RowFilter.ComparisonType type, Number number, int... indices)
Returns a RowFilter that includes entries that have at least one Number value meeting the specified criteria.
static
<M,I> RowFilter<M,I>
orFilter(Iterable<? extends RowFilter<? super M,? super I>> filters)
Returns a RowFilter that includes entries if any of the supplied filters includes the entry.
static
<M,I> RowFilter<M,I>
regexFilter(String regex, int... indices)
Returns a RowFilter that uses a regular expression to determine which entries to include.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RowFilter

public RowFilter()
Method Detail

regexFilter

public static <M,I> RowFilter<M,I> regexFilter(String regex,
                                               int... indices)
Returns a RowFilter that uses a regular expression to determine which entries to include. Only entries with at least one matching value are included. For example, the following creates a RowFilter that includes entries with at least one value starting with "a":
   RowFilter.regexFilter("^a");

The returned filter uses Matcher.find() to test for inclusion. To test for exact matches use the characters '^' and '$' to match the beginning and end of the string respectively. For example, "^foo$" includes only rows whose string is exactly "foo" and not, for example, "food". See Pattern for a complete description of the supported regular-expression constructs.

Parameters:
regex - the regular expression to filter on
indices - the indices of the values to check. If not supplied all values are evaluated
Returns:
a RowFilter implementing the specified criteria
Throws:
NullPointerException - if regex is null
IllegalArgumentException - if any of the indices are < 0
PatternSyntaxException - if regex is not a valid regular expression.
See Also:
Pattern

dateFilter

public static <M,I> RowFilter<M,I> dateFilter(RowFilter.ComparisonType type,
                                              Date date,
                                              int... indices)
Returns a RowFilter that includes entries that have at least one Date value meeting the specified criteria. For example, the following RowFilter includes only entries with at least one date value after the current date:
   RowFilter.dateFilter(ComparisonType.AFTER, new Date());

Parameters:
type - the type of comparison to perform
date - the date to compare against
indices - the indices of the values to check. If not supplied all values are evaluated
Returns:
a RowFilter implementing the specified criteria
Throws:
NullPointerException - if date is null
IllegalArgumentException - if any of the indices are < 0 or type is null
See Also:
Calendar, Date

numberFilter

public static <M,I> RowFilter<M,I> numberFilter(RowFilter.ComparisonType type,
                                                Number number,
                                                int... indices)
Returns a RowFilter that includes entries that have at least one Number value meeting the specified criteria. For example, the following filter will only include entries with at least one number value equal to 10:
   RowFilter.numberFilter(ComparisonType.EQUAL, 10);

Parameters:
type - the type of comparison to perform
indices - the indices of the values to check. If not supplied all values are evaluated
Returns:
a RowFilter implementing the specified criteria
Throws:
IllegalArgumentException - if any of the indices are < 0, type is null or number is null

orFilter

public static <M,I> RowFilter<M,I> orFilter(Iterable<? extends RowFilter<? super M,? super I>> filters)
Returns a RowFilter that includes entries if any of the supplied filters includes the entry.

The following example creates a RowFilter that will include any entries containing the string "foo" or the string "bar":

   List<RowFilter<Object,Object>> filters = new ArrayList<RowFilter<Object,Object>>(2);
   filters.add(RowFilter.regexFilter("foo"));
   filters.add(RowFilter.regexFilter("bar"));
   RowFilter<Object,Object> fooBarFilter = RowFilter.orFilter(filters);

Parameters:
filters - the RowFilters to test
Returns:
a RowFilter implementing the specified criteria
Throws:
IllegalArgumentException - if any of the filters are null
NullPointerException - if filters is null
See Also:
Arrays.asList(T...)

andFilter

public static <M,I> RowFilter<M,I> andFilter(Iterable<? extends RowFilter<? super M,? super I>> filters)
Returns a RowFilter that includes entries if all of the supplied filters include the entry.

The following example creates a RowFilter that will include any entries containing the string "foo" and the string "bar":

   List<RowFilter<Object,Object>> filters = new ArrayList<RowFilter<Object,Object>>(2);
   filters.add(RowFilter.regexFilter("foo"));
   filters.add(RowFilter.regexFilter("bar"));
   RowFilter<Object,Object> fooBarFilter = RowFilter.andFilter(filters);

Parameters:
filters - the RowFilters to test
Returns:
a RowFilter implementing the specified criteria
Throws:
IllegalArgumentException - if any of the filters are null
NullPointerException - if filters is null
See Also:
Arrays.asList(T...)

notFilter

public static <M,I> RowFilter<M,I> notFilter(RowFilter<M,I> filter)
Returns a RowFilter that includes entries if the supplied filter does not include the entry.

Parameters:
filter - the RowFilter to negate
Returns:
a RowFilter implementing the specified criteria
Throws:
IllegalArgumentException - if filter is null

include

public abstract boolean include(RowFilter.Entry<? extends M,? extends I> entry)
Returns true if the specified entry should be shown; returns false if the entry should be hidden.

The entry argument is valid only for the duration of the invocation. Using entry after the call returns results in undefined behavior.

Parameters:
entry - a non-null object that wraps the underlying object from the model
Returns:
true if the entry should be shown
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RowFilter.ComparisonType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.swing
Enum RowFilter.ComparisonType

java.lang.Object
    extended by  java.lang.Enum<RowFilter.ComparisonType>
        extended by  javax.swing.RowFilter.ComparisonType
All Implemented Interfaces:
Serializable, Comparable<RowFilter.ComparisonType>
Enclosing class:
RowFilter<M,I>
public static enum RowFilter.ComparisonType
extends Enum<RowFilter.ComparisonType>

Enumeration of the possible comparison values supported by some of the default RowFilters.

Since:
1.6
See Also:
RowFilter

Enum Constant Summary
AFTER
Indicates that entries with a value after the supplied value should be included.
BEFORE
Indicates that entries with a value before the supplied value should be included.
EQUAL
Indicates that entries with a value equal to the supplied value should be included.
NOT_EQUAL
Indicates that entries with a value not equal to the supplied value should be included.
Method Summary
static RowFilter.ComparisonType | valueOf(String name) Returns the enum constant of this type with the specified name.
static RowFilter.ComparisonType[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

BEFORE

public static final RowFilter.ComparisonType BEFORE
Indicates that entries with a value before the supplied value should be included.

AFTER

public static final RowFilter.ComparisonType AFTER
Indicates that entries with a value after the supplied value should be included.

EQUAL

public static final RowFilter.ComparisonType EQUAL
Indicates that entries with a value equal to the supplied value should be included.

NOT_EQUAL

public static final RowFilter.ComparisonType NOT_EQUAL
Indicates that entries with a value not equal to the supplied value should be included.

Method Detail

values

public static RowFilter.ComparisonType[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (RowFilter.ComparisonType c : RowFilter.ComparisonType.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static RowFilter.ComparisonType valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


RowFilter.Entry

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class RowFilter.Entry<M,I>

java.lang.Object
    extended by  javax.swing.RowFilter.Entry<M,I>
Type Parameters:
M - the type of the model; for example PersonModel
I - the type of the identifier; when using TableRowSorter this will be Integer
Enclosing class:
RowFilter<M,I>
public abstract static class RowFilter.Entry<M,I>
extends Object

An Entry object is passed to instances of RowFilter, allowing the filter to get the value of the entry's data, and thus to determine whether the entry should be shown. An Entry object contains information about the model as well as methods for getting the underlying values from the model.

Since:
1.6
See Also:
RowFilter, DefaultRowSorter.setRowFilter(javax.swing.RowFilter)

Constructor Summary
RowFilter.Entry()
Creates an Entry.
Method Summary
abstract I | getIdentifier() Returns the identifer (in the model) of the entry.
abstract M | getModel() Returns the underlying model.
String | getStringValue(int index) Returns the string value at the specified index.
abstract Object | getValue(int index) Returns the value at the specified index.
abstract int | getValueCount() Returns the number of values in the entry.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RowFilter.Entry

public RowFilter.Entry()
Creates an Entry.

Method Detail

getModel

public abstract M getModel()
Returns the underlying model.

Returns:
the model containing the data that this entry represents

getValueCount

public abstract int getValueCount()
Returns the number of values in the entry. For example, when used with a table this corresponds to the number of columns.

Returns:
number of values in the object being filtered

getValue

public abstract Object getValue(int index)
Returns the value at the specified index. This may return null. When used with a table, index corresponds to the column number in the model.

Parameters:
index - the index of the value to get
Returns:
value at the specified index
Throws:
IndexOutOfBoundsException - if index < 0 or >= getValueCount

getStringValue

public String getStringValue(int index)
Returns the string value at the specified index. If filtering is being done based on String values this method is preferred to that of getValue as getValue(index).toString() may return a different result than getStringValue(index).

This implementation calls getValue(index).toString() after checking for null. Subclasses that provide different string conversion should override this method if necessary.

Parameters:
index - the index of the value to get
Returns:
non-null string at the specified index
Throws:
IndexOutOfBoundsException - if index < 0 || >= getValueCount

getIdentifier

public abstract I getIdentifier()
Returns the identifer (in the model) of the entry. For a table this corresponds to the index of the row in the model, expressed as an Integer.

Returns:
a model-based (not view-based) identifier for this entry
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RowSorter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class RowSorter<M>

java.lang.Object
    extended by  javax.swing.RowSorter<M>
Type Parameters:
M - the type of the underlying model
Direct Known Subclasses:
DefaultRowSorter
public abstract class RowSorter<M>
extends Object

RowSorter provides the basis for sorting and filtering. Beyond creating and installing a RowSorter, you very rarely need to interact with one directly. Refer to TableRowSorter for a concrete implementation of RowSorter for JTable.

RowSorter's primary role is to provide a mapping between two coordinate systems: that of the view (for example a JTable) and that of the underlying data source, typically a model.

The view invokes the following methods on the RowSorter:

  • toggleSortOrder — The view invokes this when the appropriate user gesture has occurred to trigger a sort. For example, the user clicked a column header in a table.
  • One of the model change methods — The view invokes a model change method when the underlying model has changed. There may be order dependencies in how the events are delivered, so a RowSorter should not update its mapping until one of these methods is invoked.
Because the view makes extensive use of the convertRowIndexToModel, convertRowIndexToView and getViewRowCount methods, these methods need to be fast.

RowSorter provides notification of changes by way of RowSorterListener. Two types of notification are sent:

  • RowSorterEvent.Type.SORT_ORDER_CHANGED — notifies listeners that the sort order has changed. This is typically followed by a notification that the sort has changed.
  • RowSorterEvent.Type.SORTED — notifies listeners that the mapping maintained by the RowSorter has changed in some way.
RowSorter implementations typically don't have a one-to-one mapping with the underlying model, but they can. For example, if a database does the sorting, toggleSortOrder might call through to the database (on a background thread), and override the mapping methods to return the argument that is passed in.

Concrete implementations of RowSorter need to reference a model such as TableModel or ListModel. The view classes, such as JTable and JList, will also have a reference to the model. To avoid ordering dependencies, RowSorter implementations should not install a listener on the model. Instead the view class will call into the RowSorter when the model changes. For example, if a row is updated in a TableModel JTable invokes rowsUpdated. When the model changes, the view may call into any of the following methods: modelStructureChanged, allRowsChanged, rowsInserted, rowsDeleted and rowsUpdated.

Since:
1.6
See Also:
TableRowSorter

Nested Class Summary
static class RowSorter.SortKey
SortKey describes the sort order for a particular column.
Constructor Summary
RowSorter()
Creates a RowSorter.
Method Summary
void | addRowSorterListener(RowSorterListener l) Adds a RowSorterListener to receive notification about this RowSorter.
abstract void | allRowsChanged() Invoked when the contents of the underlying model have completely changed.
abstract int | convertRowIndexToModel(int index) Returns the location of index in terms of the underlying model.
abstract int | convertRowIndexToView(int index) Returns the location of index in terms of the view.
protected void | fireRowSorterChanged(int[] lastRowIndexToModel) Notifies listener that the mapping has changed.
protected void | fireSortOrderChanged() Notifies listener that the sort order has changed.
abstract M | getModel() Returns the underlying model.
abstract int | getModelRowCount() Returns the number of rows in the underlying model.
abstract List<? extends RowSorter.SortKey> | getSortKeys() Returns the current sort keys.
abstract int | getViewRowCount() Returns the number of rows in the view.
abstract void | modelStructureChanged() Invoked when the underlying model structure has completely changed.
void | removeRowSorterListener(RowSorterListener l) Removes a RowSorterListener.
abstract void | rowsDeleted(int firstRow, int endRow) Invoked when rows have been deleted from the underlying model in the specified range (inclusive).
abstract void | rowsInserted(int firstRow, int endRow) Invoked when rows have been inserted into the underlying model in the specified range (inclusive).
abstract void | rowsUpdated(int firstRow, int endRow) Invoked when rows have been changed in the underlying model between the specified range (inclusive).
abstract void | rowsUpdated(int firstRow, int endRow, int column) Invoked when the column in the rows have been updated in the underlying model between the specified range.
abstract void | setSortKeys(List<? extends RowSorter.SortKey> keys) Sets the current sort keys.
abstract void | toggleSortOrder(int column) Reverses the sort order of the specified column.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RowSorter

public RowSorter()
Creates a RowSorter.

Method Detail

getModel

public abstract M getModel()
Returns the underlying model.

Returns:
the underlying model

toggleSortOrder

public abstract void toggleSortOrder(int column)
Reverses the sort order of the specified column. It is up to subclasses to provide the exact behavior when invoked. Typically this will reverse the sort order from ascending to descending (or descending to ascending) if the specified column is already the primary sorted column; otherwise, makes the specified column the primary sorted column, with an ascending sort order. If the specified column is not sortable, this method has no effect.

If this results in changing the sort order and sorting, the appropriate RowSorterListener notification will be sent.

Parameters:
column - the column to toggle the sort ordering of, in terms of the underlying model
Throws:
IndexOutOfBoundsException - if column is outside the range of the underlying model

convertRowIndexToModel

public abstract int convertRowIndexToModel(int index)
Returns the location of index in terms of the underlying model. That is, for the row index in the coordinates of the view this returns the row index in terms of the underlying model.

Parameters:
index - the row index in terms of the underlying view
Returns:
row index in terms of the view
Throws:
IndexOutOfBoundsException - if index is outside the range of the view

convertRowIndexToView

public abstract int convertRowIndexToView(int index)
Returns the location of index in terms of the view. That is, for the row index in the coordinates of the underlying model this returns the row index in terms of the view.

Parameters:
index - the row index in terms of the underlying model
Returns:
row index in terms of the view, or -1 if index has been filtered out of the view
Throws:
IndexOutOfBoundsException - if index is outside the range of the model

setSortKeys

public abstract void setSortKeys(List<? extends RowSorter.SortKey> keys)
Sets the current sort keys.

Parameters:
keys - the new SortKeys; null is a shorthand for specifying an empty list, indicating that the view should be unsorted

getSortKeys

public abstract List<? extends RowSorter.SortKey> getSortKeys()
Returns the current sort keys. This must return a non-null List and may return an unmodifiable List. If you need to change the sort keys, make a copy of the returned List, mutate the copy and invoke setSortKeys with the new list.

Returns:
the current sort order

getViewRowCount

public abstract int getViewRowCount()
Returns the number of rows in the view. If the contents have been filtered this might differ from the row count of the underlying model.

Returns:
number of rows in the view
See Also:
getModelRowCount()

getModelRowCount

public abstract int getModelRowCount()
Returns the number of rows in the underlying model.

Returns:
number of rows in the underlying model
See Also:
getViewRowCount()

modelStructureChanged

public abstract void modelStructureChanged()
Invoked when the underlying model structure has completely changed. For example, if the number of columns in a TableModel changed, this method would be invoked.

You normally do not call this method. This method is public to allow view classes to call it.

allRowsChanged

public abstract void allRowsChanged()
Invoked when the contents of the underlying model have completely changed. The structure of the table is the same, only the contents have changed. This is typically sent when it is too expensive to characterize the change in terms of the other methods.

You normally do not call this method. This method is public to allow view classes to call it.

rowsInserted

public abstract void rowsInserted(int firstRow,
                                  int endRow)
Invoked when rows have been inserted into the underlying model in the specified range (inclusive).

The arguments give the indices of the effected range. The first argument is in terms of the model before the change, and must be less than or equal to the size of the model before the change. The second argument is in terms of the model after the change and must be less than the size of the model after the change. For example, if you have a 5-row model and add 3 items to the end of the model the indices are 5, 7.

You normally do not call this method. This method is public to allow view classes to call it.

Parameters:
firstRow - the first row
endRow - the last row
Throws:
IndexOutOfBoundsException - if either argument is invalid, or firstRow > endRow

rowsDeleted

public abstract void rowsDeleted(int firstRow,
                                 int endRow)
Invoked when rows have been deleted from the underlying model in the specified range (inclusive).

The arguments give the indices of the effected range and are in terms of the model before the change. For example, if you have a 5-row model and delete 3 items from the end of the model the indices are 2, 4.

You normally do not call this method. This method is public to allow view classes to call it.

Parameters:
firstRow - the first row
endRow - the last row
Throws:
IndexOutOfBoundsException - if either argument is outside the range of the model before the change, or firstRow > endRow

rowsUpdated

public abstract void rowsUpdated(int firstRow,
                                 int endRow)
Invoked when rows have been changed in the underlying model between the specified range (inclusive).

You normally do not call this method. This method is public to allow view classes to call it.

Parameters:
firstRow - the first row, in terms of the underlying model
endRow - the last row, in terms of the underlying model
Throws:
IndexOutOfBoundsException - if either argument is outside the range of the underlying model, or firstRow > endRow

rowsUpdated

public abstract void rowsUpdated(int firstRow,
                                 int endRow,
                                 int column)
Invoked when the column in the rows have been updated in the underlying model between the specified range.

You normally do not call this method. This method is public to allow view classes to call it.

Parameters:
firstRow - the first row, in terms of the underlying model
endRow - the last row, in terms of the underlying model
column - the column that has changed, in terms of the underlying model
Throws:
IndexOutOfBoundsException - if either argument is outside the range of the underlying model after the change, firstRow > endRow, or column is outside the range of the underlying model

addRowSorterListener

public void addRowSorterListener(RowSorterListener l)
Adds a RowSorterListener to receive notification about this RowSorter. If the same listener is added more than once it will receive multiple notifications. If l is null nothing is done.

Parameters:
l - the RowSorterListener

removeRowSorterListener

public void removeRowSorterListener(RowSorterListener l)
Removes a RowSorterListener. If l is null nothing is done.

Parameters:
l - the RowSorterListener

fireSortOrderChanged

protected void fireSortOrderChanged()
Notifies listener that the sort order has changed.

fireRowSorterChanged

protected void fireRowSorterChanged(int[] lastRowIndexToModel)
Notifies listener that the mapping has changed.

Parameters:
lastRowIndexToModel - the mapping from model indices to view indices prior to the sort, may be null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RowSorter.SortKey

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class RowSorter.SortKey

java.lang.Object
    extended by  javax.swing.RowSorter.SortKey
Enclosing class:
RowSorter<M>
public static class RowSorter.SortKey
extends Object

SortKey describes the sort order for a particular column. The column index is in terms of the underlying model, which may differ from that of the view.

Since:
1.6

Constructor Summary
RowSorter.SortKey(int column, SortOrder sortOrder)
Creates a SortKey for the specified column with the specified sort order.
Method Summary
boolean | equals(Object o) Returns true if this object equals the specified object.
int | getColumn() Returns the index of the column.
SortOrder | getSortOrder() Returns the sort order of the column.
int | hashCode() Returns the hash code for this SortKey.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RowSorter.SortKey

public RowSorter.SortKey(int column,
                         SortOrder sortOrder)
Creates a SortKey for the specified column with the specified sort order.

Parameters:
column - index of the column, in terms of the model
sortOrder - the sorter order
Throws:
IllegalArgumentException - if sortOrder is null
Method Detail

getColumn

public final int getColumn()
Returns the index of the column.

Returns:
index of column

getSortOrder

public final SortOrder getSortOrder()
Returns the sort order of the column.

Returns:
the sort order of the column

hashCode

public int hashCode()
Returns the hash code for this SortKey.

Overrides:
hashCode in class Object
Returns:
hash code
See Also:
Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object o)
Returns true if this object equals the specified object. If the specified object is a SortKey and references the same column and sort order, the two objects are equal.

Overrides:
equals in class Object
Parameters:
o - the object to compare to
Returns:
true if o is equal to this SortKey
See Also:
Object.hashCode(), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Scrollable

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface Scrollable

All Known Implementing Classes:
DefaultTreeCellEditor.DefaultTextField, JEditorPane, JFormattedTextField, JList, JPasswordField, JTable, JTextArea, JTextComponent, JTextField, JTextPane, JTree
public interface Scrollable

An interface that provides information to a scrolling container like JScrollPane. A complex component that's likely to be used as a viewing a JScrollPane viewport (or other scrolling container) should implement this interface.

See Also:
JViewport, JScrollPane, JScrollBar

Method Summary
Dimension | getPreferredScrollableViewportSize() Returns the preferred size of the viewport for a view component.
int | getScrollableBlockIncrement(Rectangle visibleRect, int orientation, int direction) Components that display logical rows or columns should compute the scroll increment that will completely expose one block of rows or columns, depending on the value of orientation.
boolean | getScrollableTracksViewportHeight() Return true if a viewport should always force the height of this Scrollable to match the height of the viewport.
boolean | getScrollableTracksViewportWidth() Return true if a viewport should always force the width of this Scrollable to match the width of the viewport.
int | getScrollableUnitIncrement(Rectangle visibleRect, int orientation, int direction) Components that display logical rows or columns should compute the scroll increment that will completely expose one new row or column, depending on the value of orientation.

Method Detail

getPreferredScrollableViewportSize

Dimension getPreferredScrollableViewportSize()
Returns the preferred size of the viewport for a view component. For example, the preferred size of a JList component is the size required to accommodate all of the cells in its list. However, the value of preferredScrollableViewportSize is the size required for JList.getVisibleRowCount rows. A component without any properties that would affect the viewport size should just return getPreferredSize here.

Returns:
the preferredSize of a JViewport whose view is this Scrollable
See Also:
JComponent.getPreferredSize()

getScrollableUnitIncrement

int getScrollableUnitIncrement(Rectangle visibleRect,
                               int orientation,
                               int direction)
Components that display logical rows or columns should compute the scroll increment that will completely expose one new row or column, depending on the value of orientation. Ideally, components should handle a partially exposed row or column by returning the distance required to completely expose the item.

Scrolling containers, like JScrollPane, will use this method each time the user requests a unit scroll.

Parameters:
visibleRect - The view area visible within the viewport
orientation - Either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL.
direction - Less than zero to scroll up/left, greater than zero for down/right.
Returns:
The "unit" increment for scrolling in the specified direction. This value should always be positive.
See Also:
JScrollBar.setUnitIncrement(int)

getScrollableBlockIncrement

int getScrollableBlockIncrement(Rectangle visibleRect,
                                int orientation,
                                int direction)
Components that display logical rows or columns should compute the scroll increment that will completely expose one block of rows or columns, depending on the value of orientation.

Scrolling containers, like JScrollPane, will use this method each time the user requests a block scroll.

Parameters:
visibleRect - The view area visible within the viewport
orientation - Either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL.
direction - Less than zero to scroll up/left, greater than zero for down/right.
Returns:
The "block" increment for scrolling in the specified direction. This value should always be positive.
See Also:
JScrollBar.setBlockIncrement(int)

getScrollableTracksViewportWidth

boolean getScrollableTracksViewportWidth()
Return true if a viewport should always force the width of this Scrollable to match the width of the viewport. For example a normal text view that supported line wrapping would return true here, since it would be undesirable for wrapped lines to disappear beyond the right edge of the viewport. Note that returning true for a Scrollable whose ancestor is a JScrollPane effectively disables horizontal scrolling.

Scrolling containers, like JViewport, will use this method each time they are validated.

Returns:
True if a viewport should force the Scrollables width to match its own.

getScrollableTracksViewportHeight

boolean getScrollableTracksViewportHeight()
Return true if a viewport should always force the height of this Scrollable to match the height of the viewport. For example a columnar text view that flowed text in left to right columns could effectively disable vertical scrolling by returning true here.

Scrolling containers, like JViewport, will use this method each time they are validated.

Returns:
True if a viewport should force the Scrollables height to match its own.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ScrollPaneConstants

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface ScrollPaneConstants

All Known Implementing Classes:
BasicScrollPaneUI, JScrollPane, MetalScrollPaneUI, ScrollPaneLayout, ScrollPaneLayout.UIResource
public interface ScrollPaneConstants

Constants used with the JScrollPane component.

Field Summary
static String | COLUMN_HEADER Identifies the area at the top the viewport between the upper left corner and the upper right corner.
static String | HORIZONTAL_SCROLLBAR Identifies a horizonal scrollbar.
static int | HORIZONTAL_SCROLLBAR_ALWAYS Used to set the horizontal scroll bar policy so that horizontal scrollbars are always displayed.
static int | HORIZONTAL_SCROLLBAR_AS_NEEDED Used to set the horizontal scroll bar policy so that horizontal scrollbars are displayed only when needed.
static int | HORIZONTAL_SCROLLBAR_NEVER Used to set the horizontal scroll bar policy so that horizontal scrollbars are never displayed.
static String | HORIZONTAL_SCROLLBAR_POLICY Identifies the horizontal scroll bar policy property.
static String | LOWER_LEADING_CORNER Identifies the lower leading edge corner of the viewport.
static String | LOWER_LEFT_CORNER Identifies the lower left corner of the viewport.
static String | LOWER_RIGHT_CORNER Identifies the lower right corner of the viewport.
static String | LOWER_TRAILING_CORNER Identifies the lower trailing edge corner of the viewport.
static String | ROW_HEADER Identifies the area along the left side of the viewport between the upper left corner and the lower left corner.
static String | UPPER_LEADING_CORNER Identifies the upper leading edge corner of the viewport.
static String | UPPER_LEFT_CORNER Identifies the upper left corner of the viewport.
static String | UPPER_RIGHT_CORNER Identifies the upper right corner of the viewport.
static String | UPPER_TRAILING_CORNER Identifies the upper trailing edge corner of the viewport.
static String | VERTICAL_SCROLLBAR Identifies a vertical scrollbar.
static int | VERTICAL_SCROLLBAR_ALWAYS Used to set the vertical scroll bar policy so that vertical scrollbars are always displayed.
static int | VERTICAL_SCROLLBAR_AS_NEEDED Used to set the vertical scroll bar policy so that vertical scrollbars are displayed only when needed.
static int | VERTICAL_SCROLLBAR_NEVER Used to set the vertical scroll bar policy so that vertical scrollbars are never displayed.
static String | VERTICAL_SCROLLBAR_POLICY Identifies the vertical scroll bar policy property.
static String | VIEWPORT Identifies a "viewport" or display area, within which scrolled contents are visible.

Field Detail

VIEWPORT

static final String VIEWPORT
Identifies a "viewport" or display area, within which scrolled contents are visible.

See Also:
Constant Field Values

VERTICAL_SCROLLBAR

static final String VERTICAL_SCROLLBAR
Identifies a vertical scrollbar.

See Also:
Constant Field Values

HORIZONTAL_SCROLLBAR

static final String HORIZONTAL_SCROLLBAR
Identifies a horizonal scrollbar.

See Also:
Constant Field Values

ROW_HEADER

static final String ROW_HEADER
Identifies the area along the left side of the viewport between the upper left corner and the lower left corner.

See Also:
Constant Field Values

COLUMN_HEADER

static final String COLUMN_HEADER
Identifies the area at the top the viewport between the upper left corner and the upper right corner.

See Also:
Constant Field Values

LOWER_LEFT_CORNER

static final String LOWER_LEFT_CORNER
Identifies the lower left corner of the viewport.

See Also:
Constant Field Values

LOWER_RIGHT_CORNER

static final String LOWER_RIGHT_CORNER
Identifies the lower right corner of the viewport.

See Also:
Constant Field Values

UPPER_LEFT_CORNER

static final String UPPER_LEFT_CORNER
Identifies the upper left corner of the viewport.

See Also:
Constant Field Values

UPPER_RIGHT_CORNER

static final String UPPER_RIGHT_CORNER
Identifies the upper right corner of the viewport.

See Also:
Constant Field Values

LOWER_LEADING_CORNER

static final String LOWER_LEADING_CORNER
Identifies the lower leading edge corner of the viewport. The leading edge is determined relative to the Scroll Pane's ComponentOrientation property.

See Also:
Constant Field Values

LOWER_TRAILING_CORNER

static final String LOWER_TRAILING_CORNER
Identifies the lower trailing edge corner of the viewport. The trailing edge is determined relative to the Scroll Pane's ComponentOrientation property.

See Also:
Constant Field Values

UPPER_LEADING_CORNER

static final String UPPER_LEADING_CORNER
Identifies the upper leading edge corner of the viewport. The leading edge is determined relative to the Scroll Pane's ComponentOrientation property.

See Also:
Constant Field Values

UPPER_TRAILING_CORNER

static final String UPPER_TRAILING_CORNER
Identifies the upper trailing edge corner of the viewport. The trailing edge is determined relative to the Scroll Pane's ComponentOrientation property.

See Also:
Constant Field Values

VERTICAL_SCROLLBAR_POLICY

static final String VERTICAL_SCROLLBAR_POLICY
Identifies the vertical scroll bar policy property.

See Also:
Constant Field Values

HORIZONTAL_SCROLLBAR_POLICY

static final String HORIZONTAL_SCROLLBAR_POLICY
Identifies the horizontal scroll bar policy property.

See Also:
Constant Field Values

VERTICAL_SCROLLBAR_AS_NEEDED

static final int VERTICAL_SCROLLBAR_AS_NEEDED
Used to set the vertical scroll bar policy so that vertical scrollbars are displayed only when needed.

See Also:
Constant Field Values

VERTICAL_SCROLLBAR_NEVER

static final int VERTICAL_SCROLLBAR_NEVER
Used to set the vertical scroll bar policy so that vertical scrollbars are never displayed.

See Also:
Constant Field Values

VERTICAL_SCROLLBAR_ALWAYS

static final int VERTICAL_SCROLLBAR_ALWAYS
Used to set the vertical scroll bar policy so that vertical scrollbars are always displayed.

See Also:
Constant Field Values

HORIZONTAL_SCROLLBAR_AS_NEEDED

static final int HORIZONTAL_SCROLLBAR_AS_NEEDED
Used to set the horizontal scroll bar policy so that horizontal scrollbars are displayed only when needed.

See Also:
Constant Field Values

HORIZONTAL_SCROLLBAR_NEVER

static final int HORIZONTAL_SCROLLBAR_NEVER
Used to set the horizontal scroll bar policy so that horizontal scrollbars are never displayed.

See Also:
Constant Field Values

HORIZONTAL_SCROLLBAR_ALWAYS

static final int HORIZONTAL_SCROLLBAR_ALWAYS
Used to set the horizontal scroll bar policy so that horizontal scrollbars are always displayed.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ScrollPaneLayout

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class ScrollPaneLayout

java.lang.Object
    extended by  javax.swing.ScrollPaneLayout
All Implemented Interfaces:
LayoutManager, Serializable, ScrollPaneConstants
Direct Known Subclasses:
ScrollPaneLayout.UIResource
public class ScrollPaneLayout
extends Object
implements LayoutManager, ScrollPaneConstants, Serializable

The layout manager used by JScrollPane. JScrollPaneLayout is responsible for nine components: a viewport, two scrollbars, a row header, a column header, and four "corner" components.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JScrollPane, JViewport

Nested Class Summary
static class ScrollPaneLayout.UIResource
The UI resource version of ScrollPaneLayout.
Field Summary
protected JViewport | colHead The column header child.
protected JScrollBar | hsb The scrollpane's horizontal scrollbar child.
protected int | hsbPolicy The display policy for the horizontal scrollbar.
protected Component | lowerLeft The component to display in the lower left corner.
protected Component | lowerRight The component to display in the lower right corner.
protected JViewport | rowHead The row header child.
protected Component | upperLeft The component to display in the upper left corner.
protected Component | upperRight The component to display in the upper right corner.
protected JViewport | viewport The scrollpane's viewport child.
protected JScrollBar | vsb The scrollpane's vertical scrollbar child.
protected int | vsbPolicy The display policy for the vertical scrollbar.
Fields inherited from interface javax.swing.ScrollPaneConstants
COLUMN_HEADER, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_ALWAYS, HORIZONTAL_SCROLLBAR_AS_NEEDED, HORIZONTAL_SCROLLBAR_NEVER, HORIZONTAL_SCROLLBAR_POLICY, LOWER_LEADING_CORNER, LOWER_LEFT_CORNER, LOWER_RIGHT_CORNER, LOWER_TRAILING_CORNER, ROW_HEADER, UPPER_LEADING_CORNER, UPPER_LEFT_CORNER, UPPER_RIGHT_CORNER, UPPER_TRAILING_CORNER, VERTICAL_SCROLLBAR, VERTICAL_SCROLLBAR_ALWAYS, VERTICAL_SCROLLBAR_AS_NEEDED, VERTICAL_SCROLLBAR_NEVER, VERTICAL_SCROLLBAR_POLICY, VIEWPORT
Constructor Summary
ScrollPaneLayout()
Method Summary
void | addLayoutComponent(String s, Component c) Adds the specified component to the layout.
protected Component | addSingletonComponent(Component oldC, Component newC) Removes an existing component.
JViewport | getColumnHeader() Returns the JViewport object that is the column header.
Component | getCorner(String key) Returns the Component at the specified corner.
JScrollBar | getHorizontalScrollBar() Returns the JScrollBar object that handles horizontal scrolling.
int | getHorizontalScrollBarPolicy() Returns the horizontal scrollbar-display policy.
JViewport | getRowHeader() Returns the JViewport object that is the row header.
JScrollBar | getVerticalScrollBar() Returns the JScrollBar object that handles vertical scrolling.
int | getVerticalScrollBarPolicy() Returns the vertical scrollbar-display policy.
JViewport | getViewport() Returns the JViewport object that displays the scrollable contents.
Rectangle | getViewportBorderBounds(JScrollPane scrollpane) Deprecated. As of JDK version Swing1.1 replaced by JScrollPane.getViewportBorderBounds().
void | layoutContainer(Container parent) Lays out the scrollpane.
Dimension | minimumLayoutSize(Container parent) The minimum size of a ScrollPane is the size of the insets plus minimum size of the viewport, plus the scrollpane's viewportBorder insets, plus the minimum size of the visible headers, plus the minimum size of the scrollbars whose displayPolicy isn't NEVER.
Dimension | preferredLayoutSize(Container parent) The preferred size of a ScrollPane is the size of the insets, plus the preferred size of the viewport, plus the preferred size of the visible headers, plus the preferred size of the scrollbars that will appear given the current view and the current scrollbar displayPolicies.
void | removeLayoutComponent(Component c) Removes the specified component from the layout.
void | setHorizontalScrollBarPolicy(int x) Sets the horizontal scrollbar-display policy.
void | setVerticalScrollBarPolicy(int x) Sets the vertical scrollbar-display policy.
void | syncWithScrollPane(JScrollPane sp) This method is invoked after the ScrollPaneLayout is set as the LayoutManager of a JScrollPane.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

viewport

protected JViewport viewport
The scrollpane's viewport child. Default is an empty JViewport.

See Also:
JScrollPane.setViewport(javax.swing.JViewport)

vsb

protected JScrollBar vsb
The scrollpane's vertical scrollbar child. Default is a JScrollBar.

See Also:
JScrollPane.setVerticalScrollBar(javax.swing.JScrollBar)

hsb

protected JScrollBar hsb
The scrollpane's horizontal scrollbar child. Default is a JScrollBar.

See Also:
JScrollPane.setHorizontalScrollBar(javax.swing.JScrollBar)

rowHead

protected JViewport rowHead
The row header child. Default is null.

See Also:
JScrollPane.setRowHeader(javax.swing.JViewport)

colHead

protected JViewport colHead
The column header child. Default is null.

See Also:
JScrollPane.setColumnHeader(javax.swing.JViewport)

lowerLeft

protected Component lowerLeft
The component to display in the lower left corner. Default is null.

See Also:
JScrollPane.setCorner(java.lang.String, java.awt.Component)

lowerRight

protected Component lowerRight
The component to display in the lower right corner. Default is null.

See Also:
JScrollPane.setCorner(java.lang.String, java.awt.Component)

upperLeft

protected Component upperLeft
The component to display in the upper left corner. Default is null.

See Also:
JScrollPane.setCorner(java.lang.String, java.awt.Component)

upperRight

protected Component upperRight
The component to display in the upper right corner. Default is null.

See Also:
JScrollPane.setCorner(java.lang.String, java.awt.Component)

vsbPolicy

protected int vsbPolicy
The display policy for the vertical scrollbar. The default is ScrollPaneConstants.VERTICAL_SCROLLBAR_AS_NEEDED.

This field is obsolete, please use the JScrollPane field instead.

See Also:
JScrollPane.setVerticalScrollBarPolicy(int)

hsbPolicy

protected int hsbPolicy
The display policy for the horizontal scrollbar. The default is ScrollPaneConstants.HORIZONTAL_SCROLLBAR_AS_NEEDED.

This field is obsolete, please use the JScrollPane field instead.

See Also:
JScrollPane.setHorizontalScrollBarPolicy(int)
Constructor Detail

ScrollPaneLayout

public ScrollPaneLayout()
Method Detail

syncWithScrollPane

public void syncWithScrollPane(JScrollPane sp)
This method is invoked after the ScrollPaneLayout is set as the LayoutManager of a JScrollPane. It initializes all of the internal fields that are ordinarily set by addLayoutComponent. For example:
 ScrollPaneLayout mySPLayout = new ScrollPanelLayout() {
     public void layoutContainer(Container p) {
         super.layoutContainer(p);
         // do some extra work here ...
     }
 };
 scrollpane.setLayout(mySPLayout):

addSingletonComponent

protected Component addSingletonComponent(Component oldC,
                                          Component newC)
Removes an existing component. When a new component, such as the left corner, or vertical scrollbar, is added, the old one, if it exists, must be removed.

This method returns newC. If oldC is not equal to newC and is non-null, it will be removed from its parent.

Parameters:
oldC - the Component to replace
newC - the Component to add
Returns:
the newC

addLayoutComponent

public void addLayoutComponent(String s,
                               Component c)
Adds the specified component to the layout. The layout is identified using one of:
  • ScrollPaneConstants.VIEWPORT
  • ScrollPaneConstants.VERTICAL_SCROLLBAR
  • ScrollPaneConstants.HORIZONTAL_SCROLLBAR
  • ScrollPaneConstants.ROW_HEADER
  • ScrollPaneConstants.COLUMN_HEADER
  • ScrollPaneConstants.LOWER_LEFT_CORNER
  • ScrollPaneConstants.LOWER_RIGHT_CORNER
  • ScrollPaneConstants.UPPER_LEFT_CORNER
  • ScrollPaneConstants.UPPER_RIGHT_CORNER

Specified by:
addLayoutComponent in interface LayoutManager
Parameters:
s - the component identifier
c - the the component to be added
Throws:
IllegalArgumentException - if s is an invalid key

removeLayoutComponent

public void removeLayoutComponent(Component c)
Removes the specified component from the layout.

Specified by:
removeLayoutComponent in interface LayoutManager
Parameters:
c - the component to remove

getVerticalScrollBarPolicy

public int getVerticalScrollBarPolicy()
Returns the vertical scrollbar-display policy.

Returns:
an integer giving the display policy
See Also:
setVerticalScrollBarPolicy(int)

setVerticalScrollBarPolicy

public void setVerticalScrollBarPolicy(int x)
Sets the vertical scrollbar-display policy. The options are:
  • ScrollPaneConstants.VERTICAL_SCROLLBAR_AS_NEEDED
  • ScrollPaneConstants.VERTICAL_SCROLLBAR_NEVER
  • ScrollPaneConstants.VERTICAL_SCROLLBAR_ALWAYS
Note: Applications should use the JScrollPane version of this method. It only exists for backwards compatibility with the Swing 1.0.2 (and earlier) versions of this class.

Parameters:
x - an integer giving the display policy
Throws:
IllegalArgumentException - if x is an invalid vertical scroll bar policy, as listed above

getHorizontalScrollBarPolicy

public int getHorizontalScrollBarPolicy()
Returns the horizontal scrollbar-display policy.

Returns:
an integer giving the display policy
See Also:
setHorizontalScrollBarPolicy(int)

setHorizontalScrollBarPolicy

public void setHorizontalScrollBarPolicy(int x)
Sets the horizontal scrollbar-display policy. The options are:
  • ScrollPaneConstants.HORIZONTAL_SCROLLBAR_AS_NEEDED
  • ScrollPaneConstants.HORIZONTAL_SCROLLBAR_NEVER
  • ScrollPaneConstants.HORIZONTAL_SCROLLBAR_ALWAYS
Note: Applications should use the JScrollPane version of this method. It only exists for backwards compatibility with the Swing 1.0.2 (and earlier) versions of this class.

Parameters:
x - an int giving the display policy
Throws:
IllegalArgumentException - if x is not a valid horizontal scrollbar policy, as listed above

getViewport

public JViewport getViewport()
Returns the JViewport object that displays the scrollable contents.

Returns:
the JViewport object that displays the scrollable contents
See Also:
JScrollPane.getViewport()

getHorizontalScrollBar

public JScrollBar getHorizontalScrollBar()
Returns the JScrollBar object that handles horizontal scrolling.

Returns:
the JScrollBar object that handles horizontal scrolling
See Also:
JScrollPane.getHorizontalScrollBar()

getVerticalScrollBar

public JScrollBar getVerticalScrollBar()
Returns the JScrollBar object that handles vertical scrolling.

Returns:
the JScrollBar object that handles vertical scrolling
See Also:
JScrollPane.getVerticalScrollBar()

getRowHeader

public JViewport getRowHeader()
Returns the JViewport object that is the row header.

Returns:
the JViewport object that is the row header
See Also:
JScrollPane.getRowHeader()

getColumnHeader

public JViewport getColumnHeader()
Returns the JViewport object that is the column header.

Returns:
the JViewport object that is the column header
See Also:
JScrollPane.getColumnHeader()

getCorner

public Component getCorner(String key)
Returns the Component at the specified corner.

Parameters:
key - the String specifying the corner
Returns:
the Component at the specified corner, as defined in ScrollPaneConstants; if key is not one of the four corners, null is returned
See Also:
JScrollPane.getCorner(java.lang.String)

preferredLayoutSize

public Dimension preferredLayoutSize(Container parent)
The preferred size of a ScrollPane is the size of the insets, plus the preferred size of the viewport, plus the preferred size of the visible headers, plus the preferred size of the scrollbars that will appear given the current view and the current scrollbar displayPolicies.

Note that the rowHeader is calculated as part of the preferred width and the colHeader is calculated as part of the preferred size.

Specified by:
preferredLayoutSize in interface LayoutManager
Parameters:
parent - the Container that will be laid out
Returns:
a Dimension object specifying the preferred size of the viewport and any scrollbars
See Also:
ViewportLayout, LayoutManager

minimumLayoutSize

public Dimension minimumLayoutSize(Container parent)
The minimum size of a ScrollPane is the size of the insets plus minimum size of the viewport, plus the scrollpane's viewportBorder insets, plus the minimum size of the visible headers, plus the minimum size of the scrollbars whose displayPolicy isn't NEVER.

Specified by:
minimumLayoutSize in interface LayoutManager
Parameters:
parent - the Container that will be laid out
Returns:
a Dimension object specifying the minimum size
See Also:
LayoutManager.preferredLayoutSize(java.awt.Container)

layoutContainer

public void layoutContainer(Container parent)
Lays out the scrollpane. The positioning of components depends on the following constraints:
  • The row header, if present and visible, gets its preferred width and the viewport's height.
  • The column header, if present and visible, gets its preferred height and the viewport's width.
  • If a vertical scrollbar is needed, i.e. if the viewport's extent height is smaller than its view height or if the displayPolicy is ALWAYS, it's treated like the row header with respect to its dimensions and is made visible.
  • If a horizontal scrollbar is needed, it is treated like the column header (see the paragraph above regarding the vertical scrollbar).
  • If the scrollpane has a non-null viewportBorder, then space is allocated for that.
  • The viewport gets the space available after accounting for the previous constraints.
  • The corner components, if provided, are aligned with the ends of the scrollbars and headers. If there is a vertical scrollbar, the right corners appear; if there is a horizontal scrollbar, the lower corners appear; a row header gets left corners, and a column header gets upper corners.

Specified by:
layoutContainer in interface LayoutManager
Parameters:
parent - the Container to lay out

getViewportBorderBounds

@Deprecated
public Rectangle getViewportBorderBounds(JScrollPane scrollpane)
Deprecated. As of JDK version Swing1.1 replaced by JScrollPane.getViewportBorderBounds().

Returns the bounds of the border around the specified scroll pane's viewport.

Returns:
the size and position of the viewport border
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ScrollPaneLayout.UIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class ScrollPaneLayout.UIResource

java.lang.Object
    extended by  javax.swing.ScrollPaneLayout
        extended by  javax.swing.ScrollPaneLayout.UIResource
All Implemented Interfaces:
LayoutManager, Serializable, UIResource, ScrollPaneConstants
Enclosing class:
ScrollPaneLayout
public static class ScrollPaneLayout.UIResource
extends ScrollPaneLayout
implements UIResource

The UI resource version of ScrollPaneLayout.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.ScrollPaneLayout
ScrollPaneLayout.UIResource
Field Summary
Fields inherited from class javax.swing.ScrollPaneLayout
colHead, hsb, hsbPolicy, lowerLeft, lowerRight, rowHead, upperLeft, upperRight, viewport, vsb, vsbPolicy
Fields inherited from interface javax.swing.ScrollPaneConstants
COLUMN_HEADER, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_ALWAYS, HORIZONTAL_SCROLLBAR_AS_NEEDED, HORIZONTAL_SCROLLBAR_NEVER, HORIZONTAL_SCROLLBAR_POLICY, LOWER_LEADING_CORNER, LOWER_LEFT_CORNER, LOWER_RIGHT_CORNER, LOWER_TRAILING_CORNER, ROW_HEADER, UPPER_LEADING_CORNER, UPPER_LEFT_CORNER, UPPER_RIGHT_CORNER, UPPER_TRAILING_CORNER, VERTICAL_SCROLLBAR, VERTICAL_SCROLLBAR_ALWAYS, VERTICAL_SCROLLBAR_AS_NEEDED, VERTICAL_SCROLLBAR_NEVER, VERTICAL_SCROLLBAR_POLICY, VIEWPORT
Constructor Summary
ScrollPaneLayout.UIResource()
Method Summary
Methods inherited from class javax.swing.ScrollPaneLayout
addLayoutComponent, addSingletonComponent, getColumnHeader, getCorner, getHorizontalScrollBar, getHorizontalScrollBarPolicy, getRowHeader, getVerticalScrollBar, getVerticalScrollBarPolicy, getViewport, getViewportBorderBounds, layoutContainer, minimumLayoutSize, preferredLayoutSize, removeLayoutComponent, setHorizontalScrollBarPolicy, setVerticalScrollBarPolicy, syncWithScrollPane
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ScrollPaneLayout.UIResource

public ScrollPaneLayout.UIResource()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SingleSelectionModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface SingleSelectionModel

All Known Implementing Classes:
DefaultSingleSelectionModel
public interface SingleSelectionModel

A model that supports at most one indexed selection.

Method Summary
void | addChangeListener(ChangeListener listener) Adds listener as a listener to changes in the model.
void | clearSelection() Clears the selection (to -1).
int | getSelectedIndex() Returns the model's selection.
boolean | isSelected() Returns true if the selection model currently has a selected value.
void | removeChangeListener(ChangeListener listener) Removes listener as a listener to changes in the model.
void | setSelectedIndex(int index) Sets the model's selected index to index.

Method Detail

getSelectedIndex

int getSelectedIndex()
Returns the model's selection.

Returns:
the model's selection, or -1 if there is no selection
See Also:
setSelectedIndex(int)

setSelectedIndex

void setSelectedIndex(int index)
Sets the model's selected index to index. Notifies any listeners if the model changes

Parameters:
index - an int specifying the model selection
See Also:
getSelectedIndex(), addChangeListener(javax.swing.event.ChangeListener)

clearSelection

void clearSelection()
Clears the selection (to -1).

isSelected

boolean isSelected()
Returns true if the selection model currently has a selected value.

Returns:
true if a value is currently selected

addChangeListener

void addChangeListener(ChangeListener listener)
Adds listener as a listener to changes in the model.

Parameters:
listener - the ChangeListener to add

removeChangeListener

void removeChangeListener(ChangeListener listener)
Removes listener as a listener to changes in the model.

Parameters:
listener - the ChangeListener to remove
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SizeRequirements

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class SizeRequirements

java.lang.Object
    extended by  javax.swing.SizeRequirements
All Implemented Interfaces:
Serializable
public class SizeRequirements
extends Object
implements Serializable

For the convenience of layout managers, calculates information about the size and position of components. All size and position calculation methods are class methods that take arrays of SizeRequirements as arguments. The SizeRequirements class supports two types of layout:

tiled
The components are placed end-to-end, starting either at coordinate 0 (the leftmost or topmost position) or at the coordinate representing the end of the allocated span (the rightmost or bottommost position).
aligned
The components are aligned as specified by each component's X or Y alignment value.

Each SizeRequirements object contains information about either the width (and X alignment) or height (and Y alignment) of a single component or a group of components:

minimum
The smallest reasonable width/height of the component or component group, in pixels.
preferred
The natural width/height of the component or component group, in pixels.
maximum
The largest reasonable width/height of the component or component group, in pixels.
alignment
The X/Y alignment of the component or component group.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
Component.getMinimumSize(),
Component.getPreferredSize(),
Component.getMaximumSize(),
Component.getAlignmentX(),
Component.getAlignmentY()

Field Summary
float | alignment The alignment, specified as a value between 0.0 and 1.0, inclusive.
int | maximum The maximum size allowed.
int | minimum The minimum size required.
int | preferred The preferred (natural) size.
Constructor Summary
SizeRequirements()
Creates a SizeRequirements object with the minimum, preferred, and maximum sizes set to zero and an alignment value of 0.5 (centered).
SizeRequirements(int min, int pref, int max, float a)
Creates a SizeRequirements object with the specified minimum, preferred, and maximum sizes and the specified alignment.
Method Summary
static int[] | adjustSizes(int delta, SizeRequirements[] children) Adjust a specified array of sizes by a given amount.
static void | calculateAlignedPositions(int allocated, SizeRequirements total, SizeRequirements[] children, int[] offsets, int[] spans) Creates a bunch of offset/span pairs specifying how to lay out a set of components with the specified alignments.
static void | calculateAlignedPositions(int allocated, SizeRequirements total, SizeRequirements[] children, int[] offsets, int[] spans, boolean normal) Creates a set of offset/span pairs specifying how to lay out a set of components with the specified alignments.
static void | calculateTiledPositions(int allocated, SizeRequirements total, SizeRequirements[] children, int[] offsets, int[] spans) Creates a set of offset/span pairs representing how to lay out a set of components end-to-end.
static void | calculateTiledPositions(int allocated, SizeRequirements total, SizeRequirements[] children, int[] offsets, int[] spans, boolean forward) Creates a set of offset/span pairs representing how to lay out a set of components end-to-end.
static SizeRequirements | getAlignedSizeRequirements(SizeRequirements[] children) Determines the total space necessary to align a set of components.
static SizeRequirements | getTiledSizeRequirements(SizeRequirements[] children) Determines the total space necessary to place a set of components end-to-end.
String | toString() Returns a string describing the minimum, preferred, and maximum size requirements, along with the alignment.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

minimum

public int minimum
The minimum size required. For a component comp, this should be equal to either comp.getMinimumSize().width or comp.getMinimumSize().height.

preferred

public int preferred
The preferred (natural) size. For a component comp, this should be equal to either comp.getPreferredSize().width or comp.getPreferredSize().height.

maximum

public int maximum
The maximum size allowed. For a component comp, this should be equal to either comp.getMaximumSize().width or comp.getMaximumSize().height.

alignment

public float alignment
The alignment, specified as a value between 0.0 and 1.0, inclusive. To specify centering, the alignment should be 0.5.

Constructor Detail

SizeRequirements

public SizeRequirements()
Creates a SizeRequirements object with the minimum, preferred, and maximum sizes set to zero and an alignment value of 0.5 (centered).

SizeRequirements

public SizeRequirements(int min,
                        int pref,
                        int max,
                        float a)
Creates a SizeRequirements object with the specified minimum, preferred, and maximum sizes and the specified alignment.

Parameters:
min - the minimum size >= 0
pref - the preferred size >= 0
max - the maximum size >= 0
a - the alignment >= 0.0f && <= 1.0f
Method Detail

toString

public String toString()
Returns a string describing the minimum, preferred, and maximum size requirements, along with the alignment.

Overrides:
toString in class Object
Returns:
the string

getTiledSizeRequirements

public static SizeRequirements getTiledSizeRequirements(SizeRequirements[] children)
Determines the total space necessary to place a set of components end-to-end. The needs of each component in the set are represented by an entry in the passed-in SizeRequirements array. The returned SizeRequirements object has an alignment of 0.5 (centered). The space requirement is never more than Integer.MAX_VALUE.

Parameters:
children - the space requirements for a set of components. The vector may be of zero length, which will result in a default SizeRequirements object instance being passed back.
Returns:
the total space requirements.

getAlignedSizeRequirements

public static SizeRequirements getAlignedSizeRequirements(SizeRequirements[] children)
Determines the total space necessary to align a set of components. The needs of each component in the set are represented by an entry in the passed-in SizeRequirements array. The total space required will never be more than Integer.MAX_VALUE.

Parameters:
children - the set of child requirements. If of zero length, the returns result will be a default instance of SizeRequirements.
Returns:
the total space requirements.

calculateTiledPositions

public static void calculateTiledPositions(int allocated,
                                           SizeRequirements total,
                                           SizeRequirements[] children,
                                           int[] offsets,
                                           int[] spans)
Creates a set of offset/span pairs representing how to lay out a set of components end-to-end. This method requires that you specify the total amount of space to be allocated, the size requirements for each component to be placed (specified as an array of SizeRequirements), and the total size requirement of the set of components. You can get the total size requirement by invoking the getTiledSizeRequirements method. The components will be tiled in the forward direction with offsets increasing from 0.

Parameters:
allocated - the total span to be allocated >= 0.
total - the total of the children requests. This argument is optional and may be null.
children - the size requirements for each component.
offsets - the offset from 0 for each child where the spans were allocated (determines placement of the span).
spans - the span allocated for each child to make the total target span.

calculateTiledPositions

public static void calculateTiledPositions(int allocated,
                                           SizeRequirements total,
                                           SizeRequirements[] children,
                                           int[] offsets,
                                           int[] spans,
                                           boolean forward)
Creates a set of offset/span pairs representing how to lay out a set of components end-to-end. This method requires that you specify the total amount of space to be allocated, the size requirements for each component to be placed (specified as an array of SizeRequirements), and the total size requirement of the set of components. You can get the total size requirement by invoking the getTiledSizeRequirements method. This method also requires a flag indicating whether components should be tiled in the forward direction (offsets increasing from 0) or reverse direction (offsets decreasing from the end of the allocated space). The forward direction represents components tiled from left to right or top to bottom. The reverse direction represents components tiled from right to left or bottom to top.

Parameters:
allocated - the total span to be allocated >= 0.
total - the total of the children requests. This argument is optional and may be null.
children - the size requirements for each component.
offsets - the offset from 0 for each child where the spans were allocated (determines placement of the span).
spans - the span allocated for each child to make the total target span.
forward - tile with offsets increasing from 0 if true and with offsets decreasing from the end of the allocated space if false.
Since:
1.4

calculateAlignedPositions

public static void calculateAlignedPositions(int allocated,
                                             SizeRequirements total,
                                             SizeRequirements[] children,
                                             int[] offsets,
                                             int[] spans)
Creates a bunch of offset/span pairs specifying how to lay out a set of components with the specified alignments. The resulting span allocations will overlap, with each one fitting as well as possible into the given total allocation. This method requires that you specify the total amount of space to be allocated, the size requirements for each component to be placed (specified as an array of SizeRequirements), and the total size requirements of the set of components (only the alignment field of which is actually used). You can get the total size requirement by invoking getAlignedSizeRequirements. Normal alignment will be done with an alignment value of 0.0f representing the left/top edge of a component.

Parameters:
allocated - the total span to be allocated >= 0.
total - the total of the children requests.
children - the size requirements for each component.
offsets - the offset from 0 for each child where the spans were allocated (determines placement of the span).
spans - the span allocated for each child to make the total target span.

calculateAlignedPositions

public static void calculateAlignedPositions(int allocated,
                                             SizeRequirements total,
                                             SizeRequirements[] children,
                                             int[] offsets,
                                             int[] spans,
                                             boolean normal)
Creates a set of offset/span pairs specifying how to lay out a set of components with the specified alignments. The resulting span allocations will overlap, with each one fitting as well as possible into the given total allocation. This method requires that you specify the total amount of space to be allocated, the size requirements for each component to be placed (specified as an array of SizeRequirements), and the total size requirements of the set of components (only the alignment field of which is actually used) You can get the total size requirement by invoking getAlignedSizeRequirements. This method also requires a flag indicating whether normal or reverse alignment should be performed. With normal alignment the value 0.0f represents the left/top edge of the component to be aligned. With reverse alignment, 0.0f represents the right/bottom edge.

Parameters:
allocated - the total span to be allocated >= 0.
total - the total of the children requests.
children - the size requirements for each component.
offsets - the offset from 0 for each child where the spans were allocated (determines placement of the span).
spans - the span allocated for each child to make the total target span.
normal - when true, the alignment value 0.0f means left/top; when false, it means right/bottom.
Since:
1.4

adjustSizes

public static int[] adjustSizes(int delta,
                                SizeRequirements[] children)
Adjust a specified array of sizes by a given amount.

Parameters:
delta - an int specifying the size difference
children - an array of SizeRequirements objects
Returns:
an array of ints containing the final size for each item
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SizeSequence

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class SizeSequence

java.lang.Object
    extended by  javax.swing.SizeSequence

public class SizeSequence
extends Object

A SizeSequence object efficiently maintains an ordered list of sizes and corresponding positions. One situation for which SizeSequence might be appropriate is in a component that displays multiple rows of unequal size. In this case, a single SizeSequence object could be used to track the heights and Y positions of all rows.

Another example would be a multi-column component, such as a JTable, in which the column sizes are not all equal. The JTable might use a single SizeSequence object to store the widths and X positions of all the columns. The JTable could then use the SizeSequence object to find the column corresponding to a certain position. The JTable could update the SizeSequence object whenever one or more column sizes changed.

The following figure shows the relationship between size and position data for a multi-column component.

The first item begins at position 0, the second at the position equal to the size of the previous item, and so on.

In the figure, the first index (0) corresponds to the first column, the second index (1) to the second column, and so on. The first column's position starts at 0, and the column occupies size0 pixels, where size0 is the value returned by getSize(0). Thus, the first column ends at size0 - 1. The second column then begins at the position size0 and occupies size1 (getSize(1)) pixels.

Note that a SizeSequence object simply represents intervals along an axis. In our examples, the intervals represent height or width in pixels. However, any other unit of measure (for example, time in days) could be just as valid.

Implementation Notes

Normally when storing the size and position of entries, one would choose between storing the sizes or storing their positions instead. The two common operations that are needed during rendering are: getIndex(position) and setSize(index, size). Whichever choice of internal format is made one of these operations is costly when the number of entries becomes large. If sizes are stored, finding the index of the entry that encloses a particular position is linear in the number of entries. If positions are stored instead, setting the size of an entry at a particular index requires updating the positions of the affected entries, which is also a linear calculation.

Like the above techniques this class holds an array of N integers internally but uses a hybrid encoding, which is halfway between the size-based and positional-based approaches. The result is a data structure that takes the same space to store the information but can perform most operations in Log(N) time instead of O(N), where N is the number of entries in the list.

Two operations that remain O(N) in the number of entries are the insertEntries and removeEntries methods, both of which are implemented by converting the internal array to a set of integer sizes, copying it into the new array, and then reforming the hybrid representation in place.

Since:
1.3

Constructor Summary
SizeSequence()
Creates a new SizeSequence object that contains no entries.
SizeSequence(int numEntries)
Creates a new SizeSequence object that contains the specified number of entries, all initialized to have size 0.
SizeSequence(int[] sizes)
Creates a new SizeSequence object that contains the specified sizes.
SizeSequence(int numEntries, int value)
Creates a new SizeSequence object that contains the specified number of entries, all initialized to have size value.
Method Summary
int | getIndex(int position) Returns the index of the entry that corresponds to the specified position.
int | getPosition(int index) Returns the start position for the specified entry.
int | getSize(int index) Returns the size of the specified entry.
int[] | getSizes() Returns the size of all entries.
void | insertEntries(int start, int length, int value) Adds a contiguous group of entries to this SizeSequence.
void | removeEntries(int start, int length) Removes a contiguous group of entries from this SizeSequence.
void | setSize(int index, int size) Sets the size of the specified entry.
void | setSizes(int[] sizes) Resets this SizeSequence object, using the data in the sizes argument.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SizeSequence

public SizeSequence()
Creates a new SizeSequence object that contains no entries. To add entries, you can use insertEntries or setSizes.

See Also:
insertEntries(int, int, int), setSizes(int, int)

SizeSequence

public SizeSequence(int numEntries)
Creates a new SizeSequence object that contains the specified number of entries, all initialized to have size 0.

Parameters:
numEntries - the number of sizes to track
Throws:
NegativeArraySizeException - if numEntries < 0

SizeSequence

public SizeSequence(int numEntries,
                    int value)
Creates a new SizeSequence object that contains the specified number of entries, all initialized to have size value.

Parameters:
numEntries - the number of sizes to track
value - the initial value of each size

SizeSequence

public SizeSequence(int[] sizes)
Creates a new SizeSequence object that contains the specified sizes.

Parameters:
sizes - the array of sizes to be contained in the SizeSequence
Method Detail

setSizes

public void setSizes(int[] sizes)
Resets this SizeSequence object, using the data in the sizes argument. This method reinitializes this object so that it contains as many entries as the sizes array. Each entry's size is initialized to the value of the corresponding item in sizes.

Parameters:
sizes - the array of sizes to be contained in this SizeSequence

getSizes

public int[] getSizes()
Returns the size of all entries.

Returns:
a new array containing the sizes in this object

getPosition

public int getPosition(int index)
Returns the start position for the specified entry. For example, getPosition(0) returns 0, getPosition(1) is equal to getSize(0), getPosition(2) is equal to getSize(0) + getSize(1), and so on.

Note that if index is greater than length the value returned may be meaningless.

Parameters:
index - the index of the entry whose position is desired
Returns:
the starting position of the specified entry

getIndex

public int getIndex(int position)
Returns the index of the entry that corresponds to the specified position. For example, getIndex(0) is 0, since the first entry always starts at position 0.

Parameters:
position - the position of the entry
Returns:
the index of the entry that occupies the specified position

getSize

public int getSize(int index)
Returns the size of the specified entry. If index is out of the range (0 <= index="index" <="<" getSizes().length) the behavior is unspecified.

Parameters:
index - the index corresponding to the entry
Returns:
the size of the entry

setSize

public void setSize(int index,
                    int size)
Sets the size of the specified entry. Note that if the value of index does not fall in the range: (0 <= index="index" <="<" getSizes().length) the behavior is unspecified.

Parameters:
index - the index corresponding to the entry
size - the size of the entry

insertEntries

public void insertEntries(int start,
                          int length,
                          int value)
Adds a contiguous group of entries to this SizeSequence. Note that the values of start and length must satisfy the following conditions: (0 <= start="start" <="<" getSizes().length)="getSizes().length)" AND="AND" (length="(length">= 0). If these conditions are not met, the behavior is unspecified and an exception may be thrown.

Parameters:
start - the index to be assigned to the first entry in the group
length - the number of entries in the group
value - the size to be assigned to each new entry
Throws:
ArrayIndexOutOfBoundsException - if the parameters are outside of the range: (0 <= start="start" <="<" (getSizes().length))="(getSizes().length))" AND="AND" (length="(length">= 0)

removeEntries

public void removeEntries(int start,
                          int length)
Removes a contiguous group of entries from this SizeSequence. Note that the values of start and length must satisfy the following conditions: (0 <= start="start" <="<" getSizes().length)="getSizes().length)" AND="AND" (length="(length">= 0). If these conditions are not met, the behavior is unspecified and an exception may be thrown.

Parameters:
start - the index of the first entry to be removed
length - the number of entries to be removed
Overview  Package   Class  Use  Tree  Deprecated  Index  Help
Java™ Platform
Standard Ed. 6
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SortingFocusTraversalPolicy

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class SortingFocusTraversalPolicy

java.lang.Object
    extended by  java.awt.FocusTraversalPolicy
        extended by  javax.swing.InternalFrameFocusTraversalPolicy
            extended by  javax.swing.SortingFocusTraversalPolicy
Direct Known Subclasses:
LayoutFocusTraversalPolicy
public class SortingFocusTraversalPolicy
extends InternalFrameFocusTraversalPolicy

A FocusTraversalPolicy that determines traversal order by sorting the Components of a focus traversal cycle based on a given Comparator. Portions of the Component hierarchy that are not visible and displayable will not be included.

By default, SortingFocusTraversalPolicy implicitly transfers focus down- cycle. That is, during normal focus traversal, the Component traversed after a focus cycle root will be the focus-cycle-root's default Component to focus. This behavior can be disabled using the setImplicitDownCycleTraversal method.

By default, methods of this class with return a Component only if it is visible, displayable, enabled, and focusable. Subclasses can modify this behavior by overriding the accept method.

This policy takes into account focus traversal policy providers. When searching for first/last/next/previous Component, if a focus traversal policy provider is encountered, its focus traversal policy is used to perform the search operation.

Since:
1.4
See Also:
Comparator

Constructor Summary
protected | SortingFocusTraversalPolicy() Constructs a SortingFocusTraversalPolicy without a Comparator.
 | SortingFocusTraversalPolicy(Comparator<? super Component> comparator) Constructs a SortingFocusTraversalPolicy with the specified Comparator.
Method Summary
protected boolean | accept(Component aComponent) Determines whether a Component is an acceptable choice as the new focus owner.
protected Comparator<? super Component> | getComparator() Returns the Comparator which will be used to sort the Components in a focus traversal cycle.
Component | getComponentAfter(Container aContainer, Component aComponent) Returns the Component that should receive the focus after aComponent.
Component | getComponentBefore(Container aContainer, Component aComponent) Returns the Component that should receive the focus before aComponent.
Component | getDefaultComponent(Container aContainer) Returns the default Component to focus.
Component | getFirstComponent(Container aContainer) Returns the first Component in the traversal cycle.
boolean | getImplicitDownCycleTraversal() Returns whether this SortingFocusTraversalPolicy transfers focus down- cycle implicitly.
Component | getLastComponent(Container aContainer) Returns the last Component in the traversal cycle.
protected void | setComparator(Comparator<? super Component> comparator) Sets the Comparator which will be used to sort the Components in a focus traversal cycle.
void | setImplicitDownCycleTraversal(boolean implicitDownCycleTraversal) Sets whether this SortingFocusTraversalPolicy transfers focus down-cycle implicitly.
Methods inherited from class javax.swing.InternalFrameFocusTraversalPolicy
getInitialComponent
Methods inherited from class java.awt.FocusTraversalPolicy
getInitialComponent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SortingFocusTraversalPolicy

protected SortingFocusTraversalPolicy()
Constructs a SortingFocusTraversalPolicy without a Comparator. Subclasses must set the Comparator using setComparator before installing this FocusTraversalPolicy on a focus cycle root or KeyboardFocusManager.

SortingFocusTraversalPolicy

public SortingFocusTraversalPolicy(Comparator<? super Component> comparator)
Constructs a SortingFocusTraversalPolicy with the specified Comparator.

Method Detail

getComponentAfter

public Component getComponentAfter(Container aContainer,
                                   Component aComponent)
Returns the Component that should receive the focus after aComponent. aContainer must be a focus cycle root of aComponent or a focus traversal policy provider.

By default, SortingFocusTraversalPolicy implicitly transfers focus down- cycle. That is, during normal focus traversal, the Component traversed after a focus cycle root will be the focus-cycle-root's default Component to focus. This behavior can be disabled using the setImplicitDownCycleTraversal method.

If aContainer is focus traversal policy provider, the focus is always transferred down-cycle.

Specified by:
getComponentAfter in class FocusTraversalPolicy
Parameters:
aContainer - a focus cycle root of aComponent or a focus traversal policy provider
aComponent - a (possibly indirect) child of aContainer, or aContainer itself
Returns:
the Component that should receive the focus after aComponent, or null if no suitable Component can be found
Throws:
IllegalArgumentException - if aContainer is not a focus cycle root of aComponent or a focus traversal policy provider, or if either aContainer or aComponent is null

getComponentBefore

public Component getComponentBefore(Container aContainer,
                                    Component aComponent)
Returns the Component that should receive the focus before aComponent. aContainer must be a focus cycle root of aComponent or a focus traversal policy provider.

By default, SortingFocusTraversalPolicy implicitly transfers focus down- cycle. That is, during normal focus traversal, the Component traversed after a focus cycle root will be the focus-cycle-root's default Component to focus. This behavior can be disabled using the setImplicitDownCycleTraversal method.

If aContainer is focus traversal policy provider, the focus is always transferred down-cycle.

Specified by:
getComponentBefore in class FocusTraversalPolicy
Parameters:
aContainer - a focus cycle root of aComponent or a focus traversal policy provider
aComponent - a (possibly indirect) child of aContainer, or aContainer itself
Returns:
the Component that should receive the focus before aComponent, or null if no suitable Component can be found
Throws:
IllegalArgumentException - if aContainer is not a focus cycle root of aComponent or a focus traversal policy provider, or if either aContainer or aComponent is null

getFirstComponent

public Component getFirstComponent(Container aContainer)
Returns the first Component in the traversal cycle. This method is used to determine the next Component to focus when traversal wraps in the forward direction.

Specified by:
getFirstComponent in class FocusTraversalPolicy
Parameters:
aContainer - a focus cycle root of aComponent or a focus traversal policy provider whose first Component is to be returned
Returns:
the first Component in the traversal cycle of aContainer, or null if no suitable Component can be found
Throws:
IllegalArgumentException - if aContainer is null

getLastComponent

public Component getLastComponent(Container aContainer)
Returns the last Component in the traversal cycle. This method is used to determine the next Component to focus when traversal wraps in the reverse direction.

Specified by:
getLastComponent in class FocusTraversalPolicy
Parameters:
aContainer - a focus cycle root of aComponent or a focus traversal policy provider whose last Component is to be returned
Returns:
the last Component in the traversal cycle of aContainer, or null if no suitable Component can be found
Throws:
IllegalArgumentException - if aContainer is null

getDefaultComponent

public Component getDefaultComponent(Container aContainer)
Returns the default Component to focus. This Component will be the first to receive focus when traversing down into a new focus traversal cycle rooted at aContainer. The default implementation of this method returns the same Component as getFirstComponent.

Specified by:
getDefaultComponent in class FocusTraversalPolicy
Parameters:
aContainer - a focus cycle root of aComponent or a focus traversal policy provider whose default Component is to be returned
Returns:
the default Component in the traversal cycle of aContainer, or null if no suitable Component can be found
Throws:
IllegalArgumentException - if aContainer is null
See Also:
getFirstComponent(java.awt.Container)

setImplicitDownCycleTraversal

public void setImplicitDownCycleTraversal(boolean implicitDownCycleTraversal)
Sets whether this SortingFocusTraversalPolicy transfers focus down-cycle implicitly. If true, during normal focus traversal, the Component traversed after a focus cycle root will be the focus- cycle-root's default Component to focus. If false, the next Component in the focus traversal cycle rooted at the specified focus cycle root will be traversed instead. The default value for this property is true.

Parameters:
implicitDownCycleTraversal - whether this SortingFocusTraversalPolicy transfers focus down-cycle implicitly
See Also:
getImplicitDownCycleTraversal(), getFirstComponent(java.awt.Container)

getImplicitDownCycleTraversal

public boolean getImplicitDownCycleTraversal()
Returns whether this SortingFocusTraversalPolicy transfers focus down- cycle implicitly. If true, during normal focus traversal, the Component traversed after a focus cycle root will be the focus-cycle-root's default Component to focus. If false, the next Component in the focus traversal cycle rooted at the specified focus cycle root will be traversed instead.

Returns:
whether this SortingFocusTraversalPolicy transfers focus down- cycle implicitly
See Also:
setImplicitDownCycleTraversal(boolean), getFirstComponent(java.awt.Container)

setComparator

protected void setComparator(Comparator<? super Component> comparator)
Sets the Comparator which will be used to sort the Components in a focus traversal cycle.

Parameters:
comparator - the Comparator which will be used for sorting

getComparator

protected Comparator<? super Component> getComparator()
Returns the Comparator which will be used to sort the Components in a focus traversal cycle.

Returns:
the Comparator which will be used for sorting

accept

protected boolean accept(Component aComponent)
Determines whether a Component is an acceptable choice as the new focus owner. By default, this method will accept a Component if and only if it is visible, displayable, enabled, and focusable.

Parameters:
aComponent - the Component whose fitness as a focus owner is to be tested
Returns:
true if aComponent is visible, displayable, enabled, and focusable; false otherwise
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SortOrder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.swing
Enum SortOrder

java.lang.Object
    extended by  java.lang.Enum<SortOrder>
        extended by  javax.swing.SortOrder
All Implemented Interfaces:
Serializable, Comparable<SortOrder>
public enum SortOrder
extends Enum<SortOrder>

SortOrder is an enumeration of the possible sort orderings.

Since:
1.6
See Also:
RowSorter

Enum Constant Summary
ASCENDING
Enumeration value indicating the items are sorted in increasing order.
DESCENDING
Enumeration value indicating the items are sorted in decreasing order.
UNSORTED
Enumeration value indicating the items are unordered.
Method Summary
static SortOrder | valueOf(String name) Returns the enum constant of this type with the specified name.
static SortOrder[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

ASCENDING

public static final SortOrder ASCENDING
Enumeration value indicating the items are sorted in increasing order. For example, the set 1, 4, 0 sorted in ASCENDING order is 0, 1, 4.

DESCENDING

public static final SortOrder DESCENDING
Enumeration value indicating the items are sorted in decreasing order. For example, the set 1, 4, 0 sorted in DESCENDING order is 4, 1, 0.

UNSORTED

public static final SortOrder UNSORTED
Enumeration value indicating the items are unordered. For example, the set 1, 4, 0 in UNSORTED order is 1, 4, 0.

Method Detail

values

public static SortOrder[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (SortOrder c : SortOrder.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static SortOrder valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


SpinnerDateModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class SpinnerDateModel

java.lang.Object
    extended by  javax.swing.AbstractSpinnerModel
        extended by  javax.swing.SpinnerDateModel
All Implemented Interfaces:
Serializable, SpinnerModel
public class SpinnerDateModel
extends AbstractSpinnerModel
implements Serializable

A SpinnerModel for sequences of Dates. The upper and lower bounds of the sequence are defined by properties called start and end and the size of the increase or decrease computed by the nextValue and previousValue methods is defined by a property called calendarField. The start and end properties can be null to indicate that the sequence has no lower or upper limit.

The value of the calendarField property must be one of the java.util.Calendar constants that specify a field within a Calendar. The getNextValue and getPreviousValue methods change the date forward or backwards by this amount. For example, if calendarField is Calendar.DAY_OF_WEEK, then nextValue produces a Date that's 24 hours after the current value, and previousValue produces a Date that's 24 hours earlier.

The legal values for calendarField are:

  • Calendar.ERA
  • Calendar.YEAR
  • Calendar.MONTH
  • Calendar.WEEK_OF_YEAR
  • Calendar.WEEK_OF_MONTH
  • Calendar.DAY_OF_MONTH
  • Calendar.DAY_OF_YEAR
  • Calendar.DAY_OF_WEEK
  • Calendar.DAY_OF_WEEK_IN_MONTH
  • Calendar.AM_PM
  • Calendar.HOUR
  • Calendar.HOUR_OF_DAY
  • Calendar.MINUTE
  • Calendar.SECOND
  • Calendar.MILLISECOND
However some UIs may set the calendarField before commiting the edit to spin the field under the cursor. If you only want one field to spin you can subclass and ignore the setCalendarField calls.

This model inherits a ChangeListener. The ChangeListeners are notified whenever the models value, calendarField, start, or end properties changes.

Since:
1.4
See Also:
JSpinner, SpinnerModel, AbstractSpinnerModel, SpinnerListModel, SpinnerNumberModel, Calendar.add(int, int)

Field Summary
Fields inherited from class javax.swing.AbstractSpinnerModel
listenerList
Constructor Summary
SpinnerDateModel()
Constructs a SpinnerDateModel whose initial value is the current date, calendarField is equal to Calendar.DAY_OF_MONTH, and for which there are no start/end limits.
SpinnerDateModel(Date value, Comparable start, Comparable end, int calendarField)
Creates a SpinnerDateModel that represents a sequence of dates between start and end.
Method Summary
int | getCalendarField() Returns the Calendar field that is added to or subtracted from by the nextValue and previousValue methods.
Date | getDate() Returns the current element in this sequence of Dates.
Comparable | getEnd() Returns the last Date in the sequence.
Object | getNextValue() Returns the next Date in the sequence, or null if the next date is after end.
Object | getPreviousValue() Returns the previous Date in the sequence, or null if the previous date is before start.
Comparable | getStart() Returns the first Date in the sequence.
Object | getValue() Returns the current element in this sequence of Dates.
void | setCalendarField(int calendarField) Changes the size of the date value change computed by the nextValue and previousValue methods.
void | setEnd(Comparable end) Changes the upper limit for Dates in this sequence.
void | setStart(Comparable start) Changes the lower limit for Dates in this sequence.
void | setValue(Object value) Sets the current Date for this sequence.
Methods inherited from class javax.swing.AbstractSpinnerModel
addChangeListener, fireStateChanged, getChangeListeners, getListeners, removeChangeListener
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SpinnerDateModel

public SpinnerDateModel(Date value,
                        Comparable start,
                        Comparable end,
                        int calendarField)
Creates a SpinnerDateModel that represents a sequence of dates between start and end. The nextValue and previousValue methods compute elements of the sequence by advancing or reversing the current date value by the calendarField time unit. For a precise description of what it means to increment or decrement a Calendar field, see the add method in java.util.Calendar.

The start and end parameters can be null to indicate that the range doesn't have an upper or lower bound. If value or calendarField is null, or if both start and end are specified and mininum > maximum then an IllegalArgumentException is thrown. Similarly if (minimum <= value <= maximum) is false, an IllegalArgumentException is thrown.

Parameters:
value - the current (non null) value of the model
start - the first date in the sequence or null
end - the last date in the sequence or null
calendarField - one of
  • Calendar.ERA
  • Calendar.YEAR
  • Calendar.MONTH
  • Calendar.WEEK_OF_YEAR
  • Calendar.WEEK_OF_MONTH
  • Calendar.DAY_OF_MONTH
  • Calendar.DAY_OF_YEAR
  • Calendar.DAY_OF_WEEK
  • Calendar.DAY_OF_WEEK_IN_MONTH
  • Calendar.AM_PM
  • Calendar.HOUR
  • Calendar.HOUR_OF_DAY
  • Calendar.MINUTE
  • Calendar.SECOND
  • Calendar.MILLISECOND
Throws:
IllegalArgumentException - if value or calendarField are null, if calendarField isn't valid, or if the following expression is false: (start <= value <= end).
See Also:
Calendar.add(int, int),
setValue(java.lang.Object),
setStart(java.lang.Comparable),
setEnd(java.lang.Comparable),
setCalendarField(int)

SpinnerDateModel

public SpinnerDateModel()
Constructs a SpinnerDateModel whose initial value is the current date, calendarField is equal to Calendar.DAY_OF_MONTH, and for which there are no start/end limits.

Method Detail

setStart

public void setStart(Comparable start)
Changes the lower limit for Dates in this sequence. If start is null, then there is no lower limit. No bounds checking is done here: the new start value may invalidate the (start <= value <= end) invariant enforced by the constructors. This is to simplify updating the model. Naturally one should ensure that the invariant is true before calling the nextValue, previousValue, or setValue methods.

Typically this property is a Date however it's possible to use a Comparable with a compareTo method for Dates. For example start might be an instance of a class like this:

 MyStartDate implements Comparable {
     long t = 12345;
     public int compareTo(Date d) {
            return (t < d.getTime() ? -1 : (t == d.getTime() ? 0 : 1));
     }
     public int compareTo(Object o) {
            return compareTo((Date)o);
     }
 }
Note that the above example will throw a ClassCastException if the Object passed to compareTo(Object) is not a Date.

This method fires a ChangeEvent if the start has changed.

Parameters:
start - defines the first date in the sequence
See Also:
getStart(),
setEnd(java.lang.Comparable),
AbstractSpinnerModel.addChangeListener(javax.swing.event.ChangeListener)

getStart

public Comparable getStart()
Returns the first Date in the sequence.

Returns:
the value of the start property
See Also:
setStart(java.lang.Comparable)

setEnd

public void setEnd(Comparable end)
Changes the upper limit for Dates in this sequence. If start is null, then there is no upper limit. No bounds checking is done here: the new start value may invalidate the (start <= value <= end) invariant enforced by the constructors. This is to simplify updating the model. Naturally, one should ensure that the invariant is true before calling the nextValue, previousValue, or setValue methods.

Typically this property is a Date however it's possible to use Comparable with a compareTo method for Dates. See setStart for an example.

This method fires a ChangeEvent if the end has changed.

Parameters:
end - defines the last date in the sequence
See Also:
getEnd(),
setStart(java.lang.Comparable),
AbstractSpinnerModel.addChangeListener(javax.swing.event.ChangeListener)

getEnd

public Comparable getEnd()
Returns the last Date in the sequence.

Returns:
the value of the end property
See Also:
setEnd(java.lang.Comparable)

setCalendarField

public void setCalendarField(int calendarField)
Changes the size of the date value change computed by the nextValue and previousValue methods. The calendarField parameter must be one of the Calendar field constants like Calendar.MONTH or Calendar.MINUTE. The nextValue and previousValue methods simply move the specified Calendar field forward or backward by one unit with the Calendar.add method. You should use this method with care as some UIs may set the calendarField before commiting the edit to spin the field under the cursor. If you only want one field to spin you can subclass and ignore the setCalendarField calls.

Parameters:
calendarField - one of
  • Calendar.ERA
  • Calendar.YEAR
  • Calendar.MONTH
  • Calendar.WEEK_OF_YEAR
  • Calendar.WEEK_OF_MONTH
  • Calendar.DAY_OF_MONTH
  • Calendar.DAY_OF_YEAR
  • Calendar.DAY_OF_WEEK
  • Calendar.DAY_OF_WEEK_IN_MONTH
  • Calendar.AM_PM
  • Calendar.HOUR
  • Calendar.HOUR_OF_DAY
  • Calendar.MINUTE
  • Calendar.SECOND
  • Calendar.MILLISECOND

This method fires a ChangeEvent if the calendarField has changed.

See Also:
getCalendarField(),
getNextValue(),
getPreviousValue(),
Calendar.add(int, int),
AbstractSpinnerModel.addChangeListener(javax.swing.event.ChangeListener)

getCalendarField

public int getCalendarField()
Returns the Calendar field that is added to or subtracted from by the nextValue and previousValue methods.

Returns:
the value of the calendarField property
See Also:
setCalendarField(int)

getNextValue

public Object getNextValue()
Returns the next Date in the sequence, or null if the next date is after end.

Specified by:
getNextValue in interface SpinnerModel
Returns:
the next Date in the sequence, or null if the next date is after end.
See Also:
SpinnerModel.getNextValue(),
getPreviousValue(),
setCalendarField(int)

getPreviousValue

public Object getPreviousValue()
Returns the previous Date in the sequence, or null if the previous date is before start.

Specified by:
getPreviousValue in interface SpinnerModel
Returns:
the previous Date in the sequence, or null if the previous date is before start
See Also:
SpinnerModel.getPreviousValue(),
getNextValue(),
setCalendarField(int)

getDate

public Date getDate()
Returns the current element in this sequence of Dates. This method is equivalent to (Date)getValue.

Returns:
the value property
See Also:
setValue(java.lang.Object)

getValue

public Object getValue()
Returns the current element in this sequence of Dates.

Specified by:
getValue in interface SpinnerModel
Returns:
the value property
See Also:
setValue(java.lang.Object), getDate()

setValue

public void setValue(Object value)
Sets the current Date for this sequence. If value is null, an IllegalArgumentException is thrown. No bounds checking is done here: the new value may invalidate the (start <= value < end) invariant enforced by the constructors. Naturally, one should ensure that the (start <= value <= maximum) invariant is true before calling the nextValue, previousValue, or setValue methods.

This method fires a ChangeEvent if the value has changed.

Specified by:
setValue in interface SpinnerModel
Parameters:
value - the current (non null) Date for this sequence
Throws:
IllegalArgumentException - if value is null or not a Date
See Also:
getDate(),
getValue(),
AbstractSpinnerModel.addChangeListener(javax.swing.event.ChangeListener)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SpinnerListModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class SpinnerListModel

java.lang.Object
    extended by  javax.swing.AbstractSpinnerModel
        extended by  javax.swing.SpinnerListModel
All Implemented Interfaces:
Serializable, SpinnerModel
public class SpinnerListModel
extends AbstractSpinnerModel
implements Serializable

A simple implementation of SpinnerModel whose values are defined by an array or a List. For example to create a model defined by an array of the names of the days of the week:

 String[] days = new DateFormatSymbols().getWeekdays();
 SpinnerModel model = new SpinnerListModel(Arrays.asList(days).subList(1, 8));
This class only stores a reference to the array or List so if an element of the underlying sequence changes, it's up to the application to notify the ChangeListeners by calling fireStateChanged.

This model inherits a ChangeListener. The ChangeListeners are notified whenever the model's value or list properties changes.

Since:
1.4
See Also:
JSpinner, SpinnerModel, AbstractSpinnerModel, SpinnerNumberModel, SpinnerDateModel

Field Summary
Fields inherited from class javax.swing.AbstractSpinnerModel
listenerList
Constructor Summary
SpinnerListModel()
Constructs an effectively empty SpinnerListModel.
SpinnerListModel(List<?> values)
Constructs a SpinnerModel whose sequence of values is defined by the specified List.
SpinnerListModel(Object[] values)
Constructs a SpinnerModel whose sequence of values is defined by the specified array.
Method Summary
List<?> | getList() Returns the List that defines the sequence for this model.
Object | getNextValue() Returns the next legal value of the underlying sequence or null if value is already the last element.
Object | getPreviousValue() Returns the previous element of the underlying sequence or null if value is already the first element.
Object | getValue() Returns the current element of the sequence.
void | setList(List<?> list) Changes the list that defines this sequence and resets the index of the models value to zero.
void | setValue(Object elt) Changes the current element of the sequence and notifies ChangeListeners.
Methods inherited from class javax.swing.AbstractSpinnerModel
addChangeListener, fireStateChanged, getChangeListeners, getListeners, removeChangeListener
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SpinnerListModel

public SpinnerListModel(List<?> values)
Constructs a SpinnerModel whose sequence of values is defined by the specified List. The initial value (current element) of the model will be values.get(0). If values is null or has zero size, an IllegalArugmentException is thrown.

Parameters:
values - the sequence this model represents
Throws:
IllegalArugmentException - if values is null or zero size

SpinnerListModel

public SpinnerListModel(Object[] values)
Constructs a SpinnerModel whose sequence of values is defined by the specified array. The initial value of the model will be values[0]. If values is null or has zero length, an IllegalArugmentException is thrown.

Parameters:
values - the sequence this model represents
Throws:
IllegalArugmentException - if values is null or zero length

SpinnerListModel

public SpinnerListModel()
Constructs an effectively empty SpinnerListModel. The model's list will contain a single "empty" string element.

Method Detail

getList

public List<?> getList()
Returns the List that defines the sequence for this model.

Returns:
the value of the list property
See Also:
setList(java.util.List)

setList

public void setList(List<?> list)
Changes the list that defines this sequence and resets the index of the models value to zero. Note that list is not copied, the model just stores a reference to it.

This method fires a ChangeEvent if list is not equal to the current list.

Parameters:
list - the sequence that this model represents
Throws:
IllegalArgumentException - if list is null or zero length
See Also:
getList()

getValue

public Object getValue()
Returns the current element of the sequence.

Specified by:
getValue in interface SpinnerModel
Returns:
the value property
See Also:
SpinnerModel.getValue(), setValue(java.lang.Object)

setValue

public void setValue(Object elt)
Changes the current element of the sequence and notifies ChangeListeners. If the specified value is not equal to an element of the underlying sequence then an IllegalArgumentException is thrown. In the following example the setValue call would cause an exception to be thrown:
 String[] values = {"one", "two", "free", "four"};
 SpinnerModel model = new SpinnerListModel(values);
 model.setValue("TWO");

Specified by:
setValue in interface SpinnerModel
Parameters:
elt - the sequence element that will be model's current value
Throws:
IllegalArgumentException - if the specified value isn't allowed
See Also:
SpinnerModel.setValue(java.lang.Object), getValue()

getNextValue

public Object getNextValue()
Returns the next legal value of the underlying sequence or null if value is already the last element.

Specified by:
getNextValue in interface SpinnerModel
Returns:
the next legal value of the underlying sequence or null if value is already the last element
See Also:
SpinnerModel.getNextValue(), getPreviousValue()

getPreviousValue

public Object getPreviousValue()
Returns the previous element of the underlying sequence or null if value is already the first element.

Specified by:
getPreviousValue in interface SpinnerModel
Returns:
the previous element of the underlying sequence or null if value is already the first element
See Also:
SpinnerModel.getPreviousValue(), getNextValue()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SpinnerModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface SpinnerModel

All Known Implementing Classes:
AbstractSpinnerModel, SpinnerDateModel, SpinnerListModel, SpinnerNumberModel
public interface SpinnerModel

A model for a potentially unbounded sequence of object values. This model is similar to ListModel however there are some important differences:

  • The number of sequence elements isn't neccessarily bounded.
  • The model doesn't support indexed random access to sequence elements. Only three sequence values are accessible at a time: current, next and previous.
  • The current sequence element, can be set.

A SpinnerModel has three properties, only the first is read/write.

value
The current element of the sequence.
nextValue
The following element or null if value is the last element of the sequence.
previousValue
The preceeding element or null if value is the first element of the sequence.
When the the value property changes, ChangeListeners are notified. SpinnerModel may choose to notify the ChangeListeners under other circumstances.

Since:
1.4
See Also:
JSpinner, AbstractSpinnerModel, SpinnerListModel, SpinnerNumberModel, SpinnerDateModel

Method Summary
 void addChangeListener(ChangeListener l)
Adds a ChangeListener to the model's listener list.
 Object getNextValue()
Return the object in the sequence that comes after the object returned by getValue().
 Object getPreviousValue()
Return the object in the sequence that comes before the object returned by getValue().
 Object getValue()
The current element of the sequence.
 void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the model's listener list.
 void setValue(Object value)
Changes current value of the model, typically this value is displayed by the editor part of a JSpinner.

Method Detail

getValue

Object getValue()
The current element of the sequence. This element is usually displayed by the editor part of a JSpinner.

Returns:
the current spinner value.
See Also:
setValue(java.lang.Object)

setValue

void setValue(Object value)
Changes current value of the model, typically this value is displayed by the editor part of a JSpinner. If the SpinnerModel implementation doesn't support the specified value then an IllegalArgumentException is thrown. For example a SpinnerModel for numbers might only support values that are integer multiples of ten. In that case, model.setValue(new Number(11)) would throw an exception.

Throws:
IllegalArgumentException - if value isn't allowed
See Also:
getValue()

getNextValue

Object getNextValue()
Return the object in the sequence that comes after the object returned by getValue(). If the end of the sequence has been reached then return null. Calling this method does not effect value.

Returns:
the next legal value or null if one doesn't exist
See Also:
getValue(), getPreviousValue()

getPreviousValue

Object getPreviousValue()
Return the object in the sequence that comes before the object returned by getValue(). If the end of the sequence has been reached then return null. Calling this method does not effect value.

Returns:
the previous legal value or null if one doesn't exist
See Also:
getValue(), getNextValue()

addChangeListener

void addChangeListener(ChangeListener l)
Adds a ChangeListener to the model's listener list. The ChangeListeners must be notified when models value changes.

Parameters:
l - the ChangeListener to add
See Also:
removeChangeListener(javax.swing.event.ChangeListener)

removeChangeListener

void removeChangeListener(ChangeListener l)
Removes a ChangeListener from the model's listener list.

Parameters:
l - the ChangeListener to remove
See Also:
addChangeListener(javax.swing.event.ChangeListener)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SpinnerNumberModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class SpinnerNumberModel

java.lang.Object
    extended by  javax.swing.AbstractSpinnerModel
        extended by  javax.swing.SpinnerNumberModel
All Implemented Interfaces:
Serializable, SpinnerModel
public class SpinnerNumberModel
extends AbstractSpinnerModel
implements Serializable

A SpinnerModel for sequences of numbers. The upper and lower bounds of the sequence are defined by properties called minimum and maximum. The size of the increase or decrease computed by the nextValue and previousValue methods is defined by a property called stepSize. The minimum and maximum properties can be null to indicate that the sequence has no lower or upper limit. All of the properties in this class are defined in terms of two generic types: Number and Comparable, so that all Java numeric types may be accommodated. Internally, there's only support for values whose type is one of the primitive Number types: Double, Float, Long, Integer, Short, or Byte.

To create a SpinnerNumberModel for the integer range zero to one hundred, with fifty as the initial value, one could write:

 Integer value = new Integer(50);
 Integer min = new Integer(0);
 Integer max = new Integer(100);
 Integer step = new Integer(1);
 SpinnerNumberModel model = new SpinnerNumberModel(value, min, max, step);
 int fifty = model.getNumber().intValue();

Spinners for integers and doubles are common, so special constructors for these cases are provided. For example to create the model in the previous example, one could also write:

 SpinnerNumberModel model = new SpinnerNumberModel(50, 0, 100, 1);

This model inherits a ChangeListener. The ChangeListeners are notified whenever the model's value, stepSize, minimum, or maximum properties changes.

Since:
1.4
See Also:
JSpinner, SpinnerModel, AbstractSpinnerModel, SpinnerListModel, SpinnerDateModel

Field Summary
Fields inherited from class javax.swing.AbstractSpinnerModel
listenerList
Constructor Summary
SpinnerNumberModel()
Constructs a SpinnerNumberModel with no minimum or maximum value, stepSize equal to one, and an initial value of zero.
SpinnerNumberModel(double value, double minimum, double maximum, double stepSize)
Constructs a SpinnerNumberModel with the specified value, minimum/maximum bounds, and stepSize.
SpinnerNumberModel(int value, int minimum, int maximum, int stepSize)
Constructs a SpinnerNumberModel with the specified value, minimum/maximum bounds, and stepSize.
SpinnerNumberModel(Number value, Comparable minimum, Comparable maximum, Number stepSize)
Constructs a SpinnerModel that represents a closed sequence of numbers from minimum to maximum.
Method Summary
Comparable | getMaximum() Returns the last number in the sequence.
Comparable | getMinimum() Returns the first number in this sequence.
Object | getNextValue() Returns the next number in the sequence.
Number | getNumber() Returns the value of the current element of the sequence.
Object | getPreviousValue() Returns the previous number in the sequence.
Number | getStepSize() Returns the size of the value change computed by the getNextValue and getPreviousValue methods.
Object | getValue() Returns the value of the current element of the sequence.
void | setMaximum(Comparable maximum) Changes the upper bound for numbers in this sequence.
void | setMinimum(Comparable minimum) Changes the lower bound for numbers in this sequence.
void | setStepSize(Number stepSize) Changes the size of the value change computed by the getNextValue and getPreviousValue methods.
void | setValue(Object value) Sets the current value for this sequence.
Methods inherited from class javax.swing.AbstractSpinnerModel
addChangeListener, fireStateChanged, getChangeListeners, getListeners, removeChangeListener
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SpinnerNumberModel

public SpinnerNumberModel(Number value,
                          Comparable minimum,
                          Comparable maximum,
                          Number stepSize)
Constructs a SpinnerModel that represents a closed sequence of numbers from minimum to maximum. The nextValue and previousValue methods compute elements of the sequence by adding or subtracting stepSize respectively. All of the parameters must be mutually Comparable, value and stepSize must be instances of Integer Long, Float, or Double.

The minimum and maximum parameters can be null to indicate that the range doesn't have an upper or lower bound. If value or stepSize is null, or if both minimum and maximum are specified and mininum > maximum then an IllegalArgumentException is thrown. Similarly if (minimum <= value <= maximum) is false, an IllegalArgumentException is thrown.

Parameters:
value - the current (non null) value of the model
minimum - the first number in the sequence or null
maximum - the last number in the sequence or null
stepSize - the difference between elements of the sequence
Throws:
IllegalArgumentException - if stepSize or value is null or if the following expression is false: minimum <= value <= maximum

SpinnerNumberModel

public SpinnerNumberModel(int value,
                          int minimum,
                          int maximum,
                          int stepSize)
Constructs a SpinnerNumberModel with the specified value, minimum/maximum bounds, and stepSize.

Parameters:
value - the current value of the model
minimum - the first number in the sequence
maximum - the last number in the sequence
stepSize - the difference between elements of the sequence
Throws:
IllegalArgumentException - if the following expression is false: minimum <= value <= maximum

SpinnerNumberModel

public SpinnerNumberModel(double value,
                          double minimum,
                          double maximum,
                          double stepSize)
Constructs a SpinnerNumberModel with the specified value, minimum/maximum bounds, and stepSize.

Parameters:
value - the current value of the model
minimum - the first number in the sequence
maximum - the last number in the sequence
stepSize - the difference between elements of the sequence
Throws:
IllegalArgumentException - if the following expression is false: minimum <= value <= maximum

SpinnerNumberModel

public SpinnerNumberModel()
Constructs a SpinnerNumberModel with no minimum or maximum value, stepSize equal to one, and an initial value of zero.

Method Detail

setMinimum

public void setMinimum(Comparable minimum)
Changes the lower bound for numbers in this sequence. If minimum is null, then there is no lower bound. No bounds checking is done here; the new minimum value may invalidate the (minimum <= value <= maximum) invariant enforced by the constructors. This is to simplify updating the model, naturally one should ensure that the invariant is true before calling the getNextValue, getPreviousValue, or setValue methods.

Typically this property is a Number of the same type as the value however it's possible to use any Comparable with a compareTo method for a Number with the same type as the value. For example if value was a Long, minimum might be a Date subclass defined like this:

 MyDate extends Date {  // Date already implements Comparable
     public int compareTo(Long o) {
         long t = getTime();
         return (t < o.longValue() ? -1 : (t == o.longValue() ? 0 : 1));
     }
 }

This method fires a ChangeEvent if the minimum has changed.

Parameters:
minimum - a Comparable that has a compareTo method for Numbers with the same type as value
See Also:
getMinimum(),
setMaximum(java.lang.Comparable),
SpinnerModel.addChangeListener(javax.swing.event.ChangeListener)

getMinimum

public Comparable getMinimum()
Returns the first number in this sequence.

Returns:
the value of the minimum property
See Also:
setMinimum(java.lang.Comparable)

setMaximum

public void setMaximum(Comparable maximum)
Changes the upper bound for numbers in this sequence. If maximum is null, then there is no upper bound. No bounds checking is done here; the new maximum value may invalidate the (minimum <= value="value" <="<" maximum) invariant enforced by the constructors. This is to simplify updating the model, naturally one should ensure that the invariant is true before calling the next, previous, or setValue methods.

Typically this property is a Number of the same type as the value however it's possible to use any Comparable with a compareTo method for a Number with the same type as the value. See setMinimum for an example.

This method fires a ChangeEvent if the maximum has changed.

Parameters:
maximum - a Comparable that has a compareTo method for Numbers with the same type as value
See Also:
getMaximum(),
setMinimum(java.lang.Comparable),
SpinnerModel.addChangeListener(javax.swing.event.ChangeListener)

getMaximum

public Comparable getMaximum()
Returns the last number in the sequence.

Returns:
the value of the maximum property
See Also:
setMaximum(java.lang.Comparable)

setStepSize

public void setStepSize(Number stepSize)
Changes the size of the value change computed by the getNextValue and getPreviousValue methods. An IllegalArgumentException is thrown if stepSize is null.

This method fires a ChangeEvent if the stepSize has changed.

Parameters:
stepSize - the size of the value change computed by the getNextValue and getPreviousValue methods
See Also:
getNextValue(),
getPreviousValue(),
getStepSize(),
SpinnerModel.addChangeListener(javax.swing.event.ChangeListener)

getStepSize

public Number getStepSize()
Returns the size of the value change computed by the getNextValue and getPreviousValue methods.

Returns:
the value of the stepSize property
See Also:
setStepSize(java.lang.Number)

getNextValue

public Object getNextValue()
Returns the next number in the sequence.

Specified by:
getNextValue in interface SpinnerModel
Returns:
value + stepSize or null if the sum exceeds maximum.
See Also:
SpinnerModel.getNextValue(),
getPreviousValue(),
setStepSize(java.lang.Number)

getPreviousValue

public Object getPreviousValue()
Returns the previous number in the sequence.

Specified by:
getPreviousValue in interface SpinnerModel
Returns:
value - stepSize, or null if the sum is less than minimum.
See Also:
SpinnerModel.getPreviousValue(),
getNextValue(),
setStepSize(java.lang.Number)

getNumber

public Number getNumber()
Returns the value of the current element of the sequence.

Returns:
the value property
See Also:
setValue(java.lang.Object)

getValue

public Object getValue()
Returns the value of the current element of the sequence.

Specified by:
getValue in interface SpinnerModel
Returns:
the value property
See Also:
setValue(java.lang.Object), getNumber()

setValue

public void setValue(Object value)
Sets the current value for this sequence. If value is null, or not a Number, an IllegalArgumentException is thrown. No bounds checking is done here; the new value may invalidate the (minimum <= value <= maximum) invariant enforced by the constructors. It's also possible to set the value to be something that wouldn't naturally occur in the sequence, i.e. a value that's not modulo the stepSize. This is to simplify updating the model, and to accommodate spinners that don't want to restrict values that have been directly entered by the user. Naturally, one should ensure that the (minimum <= value <= maximum) invariant is true before calling the next, previous, or setValue methods.

This method fires a ChangeEvent if the value has changed.

Specified by:
setValue in interface SpinnerModel
Parameters:
value - the current (non null) Number for this sequence
Throws:
IllegalArgumentException - if value is null or not a Number
See Also:
getNumber(),
getValue(),
SpinnerModel.addChangeListener(javax.swing.event.ChangeListener)
Overview  Package   Class  Use  Tree  Deprecated  Index  Help
Java™ Platform
Standard Ed. 6
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Spring

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class Spring

java.lang.Object
    extended by  javax.swing.Spring

public abstract class Spring
extends Object

An instance of the Spring class holds three properties that characterize its behavior: the minimum, preferred, and maximum values. Each of these properties may be involved in defining its fourth, value, property based on a series of rules.

An instance of the Spring class can be visualized as a mechanical spring that provides a corrective force as the spring is compressed or stretched away from its preferred value. This force is modelled as linear function of the distance from the preferred value, but with two different constants -- one for the compressional force and one for the tensional one. Those constants are specified by the minimum and maximum values of the spring such that a spring at its minimum value produces an equal and opposite force to that which is created when it is at its maximum value. The difference between the preferred and minimum values, therefore, represents the ease with which the spring can be compressed and the difference between its maximum and preferred values, indicates the ease with which the Spring can be extended. See the sum(javax.swing.Spring, javax.swing.Spring) method for details.

By defining simple arithmetic operations on Springs, the behavior of a collection of Springs can be reduced to that of an ordinary (non-compound) Spring. We define the "+", "-", max, and min operators on Springs so that, in each case, the result is a Spring whose characteristics bear a useful mathematical relationship to its constituent springs.

A Spring can be treated as a pair of intervals with a single common point: the preferred value. The following rules define some of the arithmetic operators that can be applied to intervals ([a, b] refers to the interval from a to b, where a <= b).

          [a1, b1] + [a2, b2] = [a1 + a2, b1 + b2]

                      -[a, b] = [-b, -a]

      max([a1, b1], [a2, b2]) = [max(a1, a2), max(b1, b2)]

If we denote Springs as [a, b, c], where a <= b <= c, we can define the same arithmetic operators on Springs:

          [a1, b1, c1] + [a2, b2, c2] = [a1 + a2, b1 + b2, c1 + c2]

                           -[a, b, c] = [-c, -b, -a]

      max([a1, b1, c1], [a2, b2, c2]) = [max(a1, a2), max(b1, b2), max(c1, c2)]

With both intervals and Springs we can define "-" and min in terms of negation:

      X - Y = X + (-Y)

      min(X, Y) = -max(-X, -Y)

For the static methods in this class that embody the arithmetic operators, we do not actually perform the operation in question as that would snapshot the values of the properties of the method's arguments at the time the static method is called. Instead, the static methods create a new Spring instance containing references to the method's arguments so that the characteristics of the new spring track the potentially changing characteristics of the springs from which it was made. This is a little like the idea of a lazy value in a functional language.

If you are implementing a SpringLayout you can find further information and examples in How to Use SpringLayout, a section in The Java Tutorial.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Since:
1.4
See Also:
SpringLayout, SpringLayout.Constraints

Field Summary
static int UNSET
An integer value signifying that a property value has not yet been calculated.
Constructor Summary
protected Spring()
Used by factory methods to create a Spring.
Method Summary
static Spring constant(int pref)
Returns a strut -- a spring whose minimum, preferred, and maximum values each have the value pref.
static Spring constant(int min, int pref, int max)
Returns a spring whose minimum, preferred, and maximum values have the values: min, pref, and max respectively.
abstract  int getMaximumValue()
Returns the maximum value of this Spring.
abstract  int getMinimumValue()
Returns the minimum value of this Spring.
abstract  int getPreferredValue()
Returns the preferred value of this Spring.
abstract  int getValue()
Returns the current value of this Spring.
static Spring height(Component c)
Returns a spring whose minimum, preferred, maximum and value properties are defined by the heights of the minimumSize, preferredSize, maximumSize and size properties of the supplied component.
static Spring max(Spring s1, Spring s2)
Returns max(s1, s2): a spring whose value is always greater than (or equal to) the values of both s1 and s2.
static Spring minus(Spring s)
Returns -s: a spring running in the opposite direction to s.
static Spring scale(Spring s, float factor)
Returns a spring whose minimum, preferred, maximum and value properties are each multiples of the properties of the argument spring, s.
abstract  void setValue(int value)
Sets the current value of this Spring to value.
static Spring sum(Spring s1, Spring s2)
Returns s1+s2: a spring representing s1 and s2 in series.
static Spring width(Component c)
Returns a spring whose minimum, preferred, maximum and value properties are defined by the widths of the minimumSize, preferredSize, maximumSize and size properties of the supplied component.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

UNSET

public static final int UNSET
An integer value signifying that a property value has not yet been calculated.

See Also:
Constant Field Values
Constructor Detail

Spring

protected Spring()
Used by factory methods to create a Spring.

See Also:
constant(int),
constant(int, int, int),
max(javax.swing.Spring, javax.swing.Spring),
minus(javax.swing.Spring),
sum(javax.swing.Spring, javax.swing.Spring),
SpringLayout.Constraints
Method Detail

getMinimumValue

public abstract int getMinimumValue()
Returns the minimum value of this Spring.

Returns:
the minimumValue property of this Spring

getPreferredValue

public abstract int getPreferredValue()
Returns the preferred value of this Spring.

Returns:
the preferredValue of this Spring

getMaximumValue

public abstract int getMaximumValue()
Returns the maximum value of this Spring.

Returns:
the maximumValue property of this Spring

getValue

public abstract int getValue()
Returns the current value of this Spring.

Returns:
the value property of this Spring
See Also:
setValue(int)

setValue

public abstract void setValue(int value)
Sets the current value of this Spring to value.

Parameters:
value - the new setting of the value property
See Also:
getValue()

constant

public static Spring constant(int pref)
Returns a strut -- a spring whose minimum, preferred, and maximum values each have the value pref.

Parameters:
pref - the minimum, preferred, and maximum values of the new spring
Returns:
a spring whose minimum, preferred, and maximum values each have the value pref
See Also:
Spring

constant

public static Spring constant(int min,
                              int pref,
                              int max)
Returns a spring whose minimum, preferred, and maximum values have the values: min, pref, and max respectively.

Parameters:
min - the minimum value of the new spring
pref - the preferred value of the new spring
max - the maximum value of the new spring
Returns:
a spring whose minimum, preferred, and maximum values have the values: min, pref, and max respectively
See Also:
Spring

minus

public static Spring minus(Spring s)
Returns -s: a spring running in the opposite direction to s.

Returns:
-s: a spring running in the opposite direction to s
See Also:
Spring

sum

public static Spring sum(Spring s1,
                         Spring s2)
Returns s1+s2: a spring representing s1 and s2 in series. In a sum, s3, of two springs, s1 and s2, the strains of s1, s2, and s3 are maintained at the same level (to within the precision implied by their integer values). The strain of a spring in compression is:
         value - pref
         ------------
          pref - min
and the strain of a spring in tension is:
         value - pref
         ------------
          max - pref
When setValue is called on the sum spring, s3, the strain in s3 is calculated using one of the formulas above. Once the strain of the sum is known, the values of s1 and s2 are then set so that they are have a strain equal to that of the sum. The formulas are evaluated so as to take rounding errors into account and ensure that the sum of the values of s1 and s2 is exactly equal to the value of s3.

Returns:
s1+s2: a spring representing s1 and s2 in series
See Also:
Spring

max

public static Spring max(Spring s1,
                         Spring s2)
Returns max(s1, s2): a spring whose value is always greater than (or equal to) the values of both s1 and s2.

Returns:
max(s1, s2): a spring whose value is always greater than (or equal to) the values of both s1 and s2
See Also:
Spring

scale

public static Spring scale(Spring s,
                           float factor)
Returns a spring whose minimum, preferred, maximum and value properties are each multiples of the properties of the argument spring, s. Minimum and maximum properties are swapped when factor is negative (in accordance with the rules of interval arithmetic).

When factor is, for example, 0.5f the result represents 'the mid-point' of its input - an operation that is useful for centering components in a container.

Parameters:
s - the spring to scale
factor - amount to scale by.
Returns:
a spring whose properties are those of the input spring s multiplied by factor
Throws:
NullPointerException - if s is null
Since:
1.5

width

public static Spring width(Component c)
Returns a spring whose minimum, preferred, maximum and value properties are defined by the widths of the minimumSize, preferredSize, maximumSize and size properties of the supplied component. The returned spring is a 'wrapper' implementation whose methods call the appropriate size methods of the supplied component. The minimum, preferred, maximum and value properties of the returned spring therefore report the current state of the appropriate properties in the component and track them as they change.

Parameters:
c - Component used for calculating size
Returns:
a spring whose properties are defined by the horizontal component of the component's size methods.
Throws:
NullPointerException - if c is null
Since:
1.5

height

public static Spring height(Component c)
Returns a spring whose minimum, preferred, maximum and value properties are defined by the heights of the minimumSize, preferredSize, maximumSize and size properties of the supplied component. The returned spring is a 'wrapper' implementation whose methods call the appropriate size methods of the supplied component. The minimum, preferred, maximum and value properties of the returned spring therefore report the current state of the appropriate properties in the component and track them as they change.

Parameters:
c - Component used for calculating size
Returns:
a spring whose properties are defined by the vertical component of the component's size methods.
Throws:
NullPointerException - if c is null
Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SpringLayout

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class SpringLayout

java.lang.Object
    extended by  javax.swing.SpringLayout
All Implemented Interfaces:
LayoutManager, LayoutManager2
public class SpringLayout
extends Object
implements LayoutManager2

A SpringLayout lays out the children of its associated container according to a set of constraints. See How to Use SpringLayout in The Java Tutorial for examples of using SpringLayout.

Each constraint, represented by a Spring object, controls the vertical or horizontal distance between two component edges. The edges can belong to any child of the container, or to the container itself. For example, the allowable width of a component can be expressed using a constraint that controls the distance between the west (left) and east (right) edges of the component. The allowable y coordinates for a component can be expressed by constraining the distance between the north (top) edge of the component and the north edge of its container.

Every child of a SpringLayout-controlled container, as well as the container itself, has exactly one set of constraints associated with it. These constraints are represented by a SpringLayout.Constraints object. By default, SpringLayout creates constraints that make their associated component have the minimum, preferred, and maximum sizes returned by the component's Component.getMinimumSize(), Component.getPreferredSize(), and Component.getMaximumSize() methods. The x and y positions are initially not constrained, so that until you constrain them the Component will be positioned at 0,0 relative to the Insets of the parent Container.

You can change a component's constraints in several ways. You can use one of the putConstraint methods to establish a spring linking the edges of two components within the same container. Or you can get the appropriate SpringLayout.Constraints object using getConstraints and then modify one or more of its springs. Or you can get the spring for a particular edge of a component using getConstraint, and modify it. You can also associate your own SpringLayout.Constraints object with a component by specifying the constraints object when you add the component to its container (using Container.add(Component, Object)).

The Spring object representing each constraint has a minimum, preferred, maximum, and current value. The current value of the spring is somewhere between the minimum and maximum values, according to the formula given in the Spring.sum(javax.swing.Spring, javax.swing.Spring) method description. When the minimum, preferred, and maximum values are the same, the current value is always equal to them; this inflexible spring is called a strut. You can create struts using the factory method Spring.constant(int). The Spring class also provides factory methods for creating other kinds of springs, including springs that depend on other springs.

In a SpringLayout, the position of each edge is dependent on the position of just one other edge. If a constraint is subsequently added to create a new binding for an edge, the previous binding is discarded and the edge remains dependent on a single edge. Springs should only be attached between edges of the container and its immediate children; the behavior of the SpringLayout when presented with constraints linking the edges of components from different containers (either internal or external) is undefined.

SpringLayout vs. Other Layout Managers

Note: Unlike many layout managers, SpringLayout doesn't automatically set the location of the components it manages. If you hand-code a GUI that uses SpringLayout, remember to initialize component locations by constraining the west/east and north/south locations.

Depending on the constraints you use, you may also need to set the size of the container explicitly.

Despite the simplicity of SpringLayout, it can emulate the behavior of most other layout managers. For some features, such as the line breaking provided by FlowLayout, you'll need to create a special-purpose subclass of the Spring class.

SpringLayout also provides a way to solve many of the difficult layout problems that cannot be solved by nesting combinations of Boxes. That said, SpringLayout honors the LayoutManager2 contract correctly and so can be nested with other layout managers -- a technique that can be preferable to creating the constraints implied by the other layout managers.

The asymptotic complexity of the layout operation of a SpringLayout is linear in the number of constraints (and/or components).

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Since:
1.4
See Also:
Spring, SpringLayout.Constraints

Nested Class Summary
static class SpringLayout.Constraints
A Constraints object holds the constraints that govern the way a component's size and position change in a container controlled by a SpringLayout.
Field Summary
static String | BASELINE Specifies the baseline of a component.
static String | EAST Specifies the right edge of a component's bounding rectangle.
static String | HEIGHT Specifies the height of a component's bounding rectangle.
static String | HORIZONTAL_CENTER Specifies the horizontal center of a component's bounding rectangle.
static String | NORTH Specifies the top edge of a component's bounding rectangle.
static String | SOUTH Specifies the bottom edge of a component's bounding rectangle.
static String | VERTICAL_CENTER Specifies the vertical center of a component's bounding rectangle.
static String | WEST Specifies the left edge of a component's bounding rectangle.
static String | WIDTH Specifies the width of a component's bounding rectangle.
Constructor Summary
SpringLayout()
Constructs a new SpringLayout.
Method Summary
void | addLayoutComponent(Component component, Object constraints) If constraints is an instance of SpringLayout.Constraints, associates the constraints with the specified component.
void | addLayoutComponent(String name, Component c) Has no effect, since this layout manager does not use a per-component string.
Spring | getConstraint(String edgeName, Component c) Returns the spring controlling the distance between the specified edge of the component and the top or left edge of its parent.
SpringLayout.Constraints | getConstraints(Component c) Returns the constraints for the specified component.
float | getLayoutAlignmentX(Container p) Returns 0.5f (centered).
float | getLayoutAlignmentY(Container p) Returns 0.5f (centered).
void | invalidateLayout(Container p) Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.
void | layoutContainer(Container parent) Lays out the specified container.
Dimension | maximumLayoutSize(Container parent) Calculates the maximum size dimensions for the specified container, given the components it contains.
Dimension | minimumLayoutSize(Container parent) Calculates the minimum size dimensions for the specified container, given the components it contains.
Dimension | preferredLayoutSize(Container parent) Calculates the preferred size dimensions for the specified container, given the components it contains.
void | putConstraint(String e1, Component c1, int pad, String e2, Component c2) Links edge e1 of component c1 to edge e2 of component c2, with a fixed distance between the edges.
void | putConstraint(String e1, Component c1, Spring s, String e2, Component c2) Links edge e1 of component c1 to edge e2 of component c2.
void | removeLayoutComponent(Component c) Removes the constraints associated with the specified component.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NORTH

public static final String NORTH
Specifies the top edge of a component's bounding rectangle.

See Also:
Constant Field Values

SOUTH

public static final String SOUTH
Specifies the bottom edge of a component's bounding rectangle.

See Also:
Constant Field Values

EAST

public static final String EAST
Specifies the right edge of a component's bounding rectangle.

See Also:
Constant Field Values

WEST

public static final String WEST
Specifies the left edge of a component's bounding rectangle.

See Also:
Constant Field Values

HORIZONTAL_CENTER

public static final String HORIZONTAL_CENTER
Specifies the horizontal center of a component's bounding rectangle.

Since:
1.6
See Also:
Constant Field Values

VERTICAL_CENTER

public static final String VERTICAL_CENTER
Specifies the vertical center of a component's bounding rectangle.

Since:
1.6
See Also:
Constant Field Values

BASELINE

public static final String BASELINE
Specifies the baseline of a component.

Since:
1.6
See Also:
Constant Field Values

WIDTH

public static final String WIDTH
Specifies the width of a component's bounding rectangle.

Since:
1.6
See Also:
Constant Field Values

HEIGHT

public static final String HEIGHT
Specifies the height of a component's bounding rectangle.

Since:
1.6
See Also:
Constant Field Values
Constructor Detail

SpringLayout

public SpringLayout()
Constructs a new SpringLayout.

Method Detail

addLayoutComponent

public void addLayoutComponent(String name,
                               Component c)
Has no effect, since this layout manager does not use a per-component string.

Specified by:
addLayoutComponent in interface LayoutManager
Parameters:
name - the string to be associated with the component
c - the component to be added

removeLayoutComponent

public void removeLayoutComponent(Component c)
Removes the constraints associated with the specified component.

Specified by:
removeLayoutComponent in interface LayoutManager
Parameters:
c - the component being removed from the container

minimumLayoutSize

public Dimension minimumLayoutSize(Container parent)
Description copied from interface: LayoutManager
Calculates the minimum size dimensions for the specified container, given the components it contains.

Specified by:
minimumLayoutSize in interface LayoutManager
Parameters:
parent - the component to be laid out
See Also:
LayoutManager.preferredLayoutSize(java.awt.Container)

preferredLayoutSize

public Dimension preferredLayoutSize(Container parent)
Description copied from interface: LayoutManager
Calculates the preferred size dimensions for the specified container, given the components it contains.

Specified by:
preferredLayoutSize in interface LayoutManager
Parameters:
parent - the container to be laid out
See Also:
LayoutManager.minimumLayoutSize(java.awt.Container)

maximumLayoutSize

public Dimension maximumLayoutSize(Container parent)
Description copied from interface: LayoutManager2
Calculates the maximum size dimensions for the specified container, given the components it contains.

Specified by:
maximumLayoutSize in interface LayoutManager2
See Also:
Component.getMaximumSize(), LayoutManager

addLayoutComponent

public void addLayoutComponent(Component component,
                               Object constraints)
If constraints is an instance of SpringLayout.Constraints, associates the constraints with the specified component.

Specified by:
addLayoutComponent in interface LayoutManager2
Parameters:
component - the component being added
constraints - the component's constraints
See Also:
SpringLayout.Constraints

getLayoutAlignmentX

public float getLayoutAlignmentX(Container p)
Returns 0.5f (centered).

Specified by:
getLayoutAlignmentX in interface LayoutManager2

getLayoutAlignmentY

public float getLayoutAlignmentY(Container p)
Returns 0.5f (centered).

Specified by:
getLayoutAlignmentY in interface LayoutManager2

invalidateLayout

public void invalidateLayout(Container p)
Description copied from interface: LayoutManager2
Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.

Specified by:
invalidateLayout in interface LayoutManager2

putConstraint

public void putConstraint(String e1,
                          Component c1,
                          int pad,
                          String e2,
                          Component c2)
Links edge e1 of component c1 to edge e2 of component c2, with a fixed distance between the edges. This constraint will cause the assignment
     value(e1, c1) = value(e2, c2) + pad
to take place during all subsequent layout operations.

Parameters:
e1 - the edge of the dependent
c1 - the component of the dependent
pad - the fixed distance between dependent and anchor
e2 - the edge of the anchor
c2 - the component of the anchor
See Also:
putConstraint(String, Component, Spring, String, Component)

putConstraint

public void putConstraint(String e1,
                          Component c1,
                          Spring s,
                          String e2,
                          Component c2)
Links edge e1 of component c1 to edge e2 of component c2. As edge (e2, c2) changes value, edge (e1, c1) will be calculated by taking the (spring) sum of (e2, c2) and s. Each edge must have one of the following values: SpringLayout.NORTH, SpringLayout.SOUTH, SpringLayout.EAST, SpringLayout.WEST, SpringLayout.VERTICAL_CENTER, SpringLayout.HORIZONTAL_CENTER or SpringLayout.BASELINE.

Parameters:
e1 - the edge of the dependent
c1 - the component of the dependent
s - the spring linking dependent and anchor
e2 - the edge of the anchor
c2 - the component of the anchor
See Also:
putConstraint(String, Component, int, String, Component), NORTH, SOUTH, EAST, WEST, VERTICAL_CENTER, HORIZONTAL_CENTER, BASELINE

getConstraints

public SpringLayout.Constraints getConstraints(Component c)
Returns the constraints for the specified component. Note that, unlike the GridBagLayout getConstraints method, this method does not clone constraints. If no constraints have been associated with this component, this method returns a default constraints object positioned at 0,0 relative to the parent's Insets and its width/height constrained to the minimum, maximum, and preferred sizes of the component. The size characteristics are not frozen at the time this method is called; instead this method returns a constraints object whose characteristics track the characteristics of the component as they change.

Parameters:
c - the component whose constraints will be returned
Returns:
the constraints for the specified component

getConstraint

public Spring getConstraint(String edgeName,
                            Component c)
Returns the spring controlling the distance between the specified edge of the component and the top or left edge of its parent. This method, instead of returning the current binding for the edge, returns a proxy that tracks the characteristics of the edge even if the edge is subsequently rebound. Proxies are intended to be used in builder envonments where it is useful to allow the user to define the constraints for a layout in any order. Proxies do, however, provide the means to create cyclic dependencies amongst the constraints of a layout. Such cycles are detected internally by SpringLayout so that the layout operation always terminates.

Parameters:
edgeName - must be one of SpringLayout.NORTH, SpringLayout.SOUTH, SpringLayout.EAST, SpringLayout.WEST, SpringLayout.VERTICAL_CENTER, SpringLayout.HORIZONTAL_CENTER or SpringLayout.BASELINE
c - the component whose edge spring is desired
Returns:
a proxy for the spring controlling the distance between the specified edge and the top or left edge of its parent
See Also:
NORTH, SOUTH, EAST, WEST, VERTICAL_CENTER, HORIZONTAL_CENTER, BASELINE

layoutContainer

public void layoutContainer(Container parent)
Description copied from interface: LayoutManager
Lays out the specified container.

Specified by:
layoutContainer in interface LayoutManager
Parameters:
parent - the container to be laid out
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SpringLayout.Constraints

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class SpringLayout.Constraints

java.lang.Object
    extended by  javax.swing.SpringLayout.Constraints
Enclosing class:
SpringLayout
public static class SpringLayout.Constraints
extends Object

A Constraints object holds the constraints that govern the way a component's size and position change in a container controlled by a SpringLayout. A Constraints object is like a Rectangle, in that it has x, y, width, and height properties. In the Constraints object, however, these properties have Spring values instead of integers. In addition, a Constraints object can be manipulated as four edges -- north, south, east, and west -- using the constraint property.

The following formulas are always true for a Constraints object (here WEST and x are synonyms, as are and NORTH and y):

               EAST = WEST + WIDTH
              SOUTH = NORTH + HEIGHT
  HORIZONTAL_CENTER = WEST + WIDTH/2
    VERTICAL_CENTER = NORTH + HEIGHT/2
  ABSOLUTE_BASELINE = NORTH + RELATIVE_BASELINE*

For example, if you have specified the WIDTH and WEST (X) location the EAST is calculated as WEST + WIDTH. If you instead specified the WIDTH and EAST locations the WEST (X) location is then calculated as EAST - WIDTH.

[RELATIVE_BASELINE is a private constraint that is set automatically when the SpringLayout.Constraints(Component) constuctor is called or when a constraints object is registered with a SpringLayout object.]

Note: In this document, operators represent methods in the Spring class. For example, "a + b" is equal to Spring.sum(a, b), and "a - b" is equal to Spring.sum(a, Spring.minus(b)). See the Spring API documentation for further details of spring arithmetic.

Because a Constraints object's properties -- representing its edges, size, and location -- can all be set independently and yet are interrelated, a Constraints object can become over-constrained. For example, if the WEST, WIDTH and EAST edges are all set, steps must be taken to ensure that the first of the formulas above holds. To do this, the Constraints object throws away the least recently set constraint so as to make the formulas hold.

Since:
1.4

Constructor Summary
SpringLayout.Constraints()
Creates an empty Constraints object.
SpringLayout.Constraints(Component c)
Creates a Constraints object with suitable x, y, width and height springs for component, c.
SpringLayout.Constraints(Spring x, Spring y)
Creates a Constraints object with the specified values for its x and y properties.
SpringLayout.Constraints(Spring x, Spring y, Spring width, Spring height)
Creates a Constraints object with the specified values for its x, y, width, and height properties.
Method Summary
Spring | getConstraint(String edgeName) Returns the value of the specified edge, which may be a derived value, or even null.
Spring | getHeight() Returns the value of the height property.
Spring | getWidth() Returns the value of the width property.
Spring | getX() Returns the value of the x property.
Spring | getY() Returns the value of the y property.
void | setConstraint(String edgeName, Spring s) Sets the spring controlling the specified edge.
void | setHeight(Spring height) Sets the height property, which controls the height of a component.
void | setWidth(Spring width) Sets the width property, which controls the width of a component.
void | setX(Spring x) Sets the x property, which controls the x value of a component's location.
void | setY(Spring y) Sets the y property, which controls the y value of a component's location.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SpringLayout.Constraints

public SpringLayout.Constraints()
Creates an empty Constraints object.

SpringLayout.Constraints

public SpringLayout.Constraints(Spring x,
                                Spring y)
Creates a Constraints object with the specified values for its x and y properties. The height and width springs have null values.

Parameters:
x - the spring controlling the component's x value
y - the spring controlling the component's y value

SpringLayout.Constraints

public SpringLayout.Constraints(Spring x,
                                Spring y,
                                Spring width,
                                Spring height)
Creates a Constraints object with the specified values for its x, y, width, and height properties. Note: If the SpringLayout class encounters null values in the Constraints object of a given component, it replaces them with suitable defaults.

Parameters:
x - the spring value for the x property
y - the spring value for the y property
width - the spring value for the width property
height - the spring value for the height property

SpringLayout.Constraints

public SpringLayout.Constraints(Component c)
Creates a Constraints object with suitable x, y, width and height springs for component, c. The x and y springs are constant springs initialised with the component's location at the time this method is called. The width and height springs are special springs, created by the Spring.width() and Spring.height() methods, which track the size characteristics of the component when they change.

Parameters:
c - the component whose characteristics will be reflected by this Constraints object
Throws:
NullPointerException - if c is null.
Since:
1.5
Method Detail

setX

public void setX(Spring x)
Sets the x property, which controls the x value of a component's location.

Parameters:
x - the spring controlling the x value of a component's location
See Also:
getX(), SpringLayout.Constraints

getX

public Spring getX()
Returns the value of the x property.

Returns:
the spring controlling the x value of a component's location
See Also:
setX(javax.swing.Spring), SpringLayout.Constraints

setY

public void setY(Spring y)
Sets the y property, which controls the y value of a component's location.

Parameters:
y - the spring controlling the y value of a component's location
See Also:
getY(), SpringLayout.Constraints

getY

public Spring getY()
Returns the value of the y property.

Returns:
the spring controlling the y value of a component's location
See Also:
setY(javax.swing.Spring), SpringLayout.Constraints

setWidth

public void setWidth(Spring width)
Sets the width property, which controls the width of a component.

Parameters:
width - the spring controlling the width of this Constraints object
See Also:
getWidth(), SpringLayout.Constraints

getWidth

public Spring getWidth()
Returns the value of the width property.

Returns:
the spring controlling the width of a component
See Also:
setWidth(javax.swing.Spring), SpringLayout.Constraints

setHeight

public void setHeight(Spring height)
Sets the height property, which controls the height of a component.

Parameters:
height - the spring controlling the height of this Constraints object
See Also:
getHeight(), SpringLayout.Constraints

getHeight

public Spring getHeight()
Returns the value of the height property.

Returns:
the spring controlling the height of a component
See Also:
setHeight(javax.swing.Spring), SpringLayout.Constraints

setConstraint

public void setConstraint(String edgeName,
                          Spring s)
Sets the spring controlling the specified edge. The edge must have one of the following values: SpringLayout.NORTH, SpringLayout.SOUTH, SpringLayout.EAST, SpringLayout.WEST, SpringLayout.HORIZONTAL_CENTER, SpringLayout.VERTICAL_CENTER, SpringLayout.BASELINE, SpringLayout.WIDTH or SpringLayout.HEIGHT. For any other String value passed as the edge, no action is taken. For a null edge, a NullPointerException is thrown.

Parameters:
edgeName - the edge to be set
s - the spring controlling the specified edge
Throws:
NullPointerException - if edgeName is null
See Also:
getConstraint(java.lang.String), SpringLayout.NORTH, SpringLayout.SOUTH, SpringLayout.EAST, SpringLayout.WEST, SpringLayout.HORIZONTAL_CENTER, SpringLayout.VERTICAL_CENTER, SpringLayout.BASELINE, SpringLayout.WIDTH, SpringLayout.HEIGHT, SpringLayout.Constraints

getConstraint

public Spring getConstraint(String edgeName)
Returns the value of the specified edge, which may be a derived value, or even null. The edge must have one of the following values: SpringLayout.NORTH, SpringLayout.SOUTH, SpringLayout.EAST, SpringLayout.WEST, SpringLayout.HORIZONTAL_CENTER, SpringLayout.VERTICAL_CENTER, SpringLayout.BASELINE, SpringLayout.WIDTH or SpringLayout.HEIGHT. For any other String value passed as the edge, null will be returned. Throws NullPointerException for a null edge.

Parameters:
edgeName - the edge whose value is to be returned
Returns:
the spring controlling the specified edge, may be null
Throws:
NullPointerException - if edgeName is null
See Also:
setConstraint(java.lang.String, javax.swing.Spring), SpringLayout.NORTH, SpringLayout.SOUTH, SpringLayout.EAST, SpringLayout.WEST, SpringLayout.HORIZONTAL_CENTER, SpringLayout.VERTICAL_CENTER, SpringLayout.BASELINE, SpringLayout.WIDTH, SpringLayout.HEIGHT, SpringLayout.Constraints
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SwingConstants

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface SwingConstants

All Known Implementing Classes:
AbstractButton, AsyncBoxView, BasicArrowButton, BasicComboBoxRenderer, BasicComboBoxRenderer.UIResource, BasicInternalFrameUI.BorderListener, BasicScrollBarUI, BasicTabbedPaneUI, BasicToolBarUI, BlockView, BoxView, ComponentView, CompositeView, DefaultListCellRenderer, DefaultListCellRenderer.UIResource, DefaultTableCellRenderer, DefaultTableCellRenderer.UIResource, DefaultTreeCellEditor.DefaultTextField, DefaultTreeCellRenderer, FieldView, FlowView, FormView, GlyphView, IconView, ImageView, InlineView, JButton, JCheckBox, JCheckBoxMenuItem, JFormattedTextField, JLabel, JMenu, JMenuItem, JPasswordField, JPopupMenu.Separator, JProgressBar, JRadioButton, JRadioButtonMenuItem, JSeparator, JSlider, JTabbedPane, JTextField, JToggleButton, JToolBar, JToolBar.Separator, LabelView, ListView, MetalBorders.ToolBarBorder, MetalComboBoxButton, MetalFileChooserUI.FileRenderer, MetalFileChooserUI.FilterComboBoxRenderer, MetalScrollBarUI, MetalScrollButton, MetalTabbedPaneUI, MetalToolBarUI, ObjectView, ParagraphView, ParagraphView, PasswordView, PlainView, SwingUtilities, TableView, TableView.TableCell, TableView.TableRow, View, WrappedPlainView, ZoneView
public interface SwingConstants

A collection of constants generally used for positioning and orienting components on the screen.

Field Summary
static int | BOTTOM Box-orientation constant used to specify the bottom of a box.
static int | CENTER The central position in an area.
static int | EAST Compass-direction east (right).
static int | HORIZONTAL Horizontal orientation.
static int | LEADING Identifies the leading edge of text for use with left-to-right and right-to-left languages.
static int | LEFT Box-orientation constant used to specify the left side of a box.
static int | NEXT Identifies the next direction in a sequence.
static int | NORTH Compass-direction North (up).
static int | NORTH_EAST Compass-direction north-east (upper right).
static int | NORTH_WEST Compass-direction north west (upper left).
static int | PREVIOUS Identifies the previous direction in a sequence.
static int | RIGHT Box-orientation constant used to specify the right side of a box.
static int | SOUTH Compass-direction south (down).
static int | SOUTH_EAST Compass-direction south-east (lower right).
static int | SOUTH_WEST Compass-direction south-west (lower left).
static int | TOP Box-orientation constant used to specify the top of a box.
static int | TRAILING Identifies the trailing edge of text for use with left-to-right and right-to-left languages.
static int | VERTICAL Vertical orientation.
static int | WEST Compass-direction west (left).

Field Detail

CENTER

static final int CENTER
The central position in an area. Used for both compass-direction constants (NORTH, etc.) and box-orientation constants (TOP, etc.).

See Also:
Constant Field Values

TOP

static final int TOP
Box-orientation constant used to specify the top of a box.

See Also:
Constant Field Values

LEFT

static final int LEFT
Box-orientation constant used to specify the left side of a box.

See Also:
Constant Field Values

BOTTOM

static final int BOTTOM
Box-orientation constant used to specify the bottom of a box.

See Also:
Constant Field Values

RIGHT

static final int RIGHT
Box-orientation constant used to specify the right side of a box.

See Also:
Constant Field Values

NORTH

static final int NORTH
Compass-direction North (up).

See Also:
Constant Field Values

NORTH_EAST

static final int NORTH_EAST
Compass-direction north-east (upper right).

See Also:
Constant Field Values

EAST

static final int EAST
Compass-direction east (right).

See Also:
Constant Field Values

SOUTH_EAST

static final int SOUTH_EAST
Compass-direction south-east (lower right).

See Also:
Constant Field Values

SOUTH

static final int SOUTH
Compass-direction south (down).

See Also:
Constant Field Values

SOUTH_WEST

static final int SOUTH_WEST
Compass-direction south-west (lower left).

See Also:
Constant Field Values

WEST

static final int WEST
Compass-direction west (left).

See Also:
Constant Field Values

NORTH_WEST

static final int NORTH_WEST
Compass-direction north west (upper left).

See Also:
Constant Field Values

HORIZONTAL

static final int HORIZONTAL
Horizontal orientation. Used for scrollbars and sliders.

See Also:
Constant Field Values

VERTICAL

static final int VERTICAL
Vertical orientation. Used for scrollbars and sliders.

See Also:
Constant Field Values

LEADING

static final int LEADING
Identifies the leading edge of text for use with left-to-right and right-to-left languages. Used by buttons and labels.

See Also:
Constant Field Values

TRAILING

static final int TRAILING
Identifies the trailing edge of text for use with left-to-right and right-to-left languages. Used by buttons and labels.

See Also:
Constant Field Values

NEXT

static final int NEXT
Identifies the next direction in a sequence.

Since:
1.4
See Also:
Constant Field Values

PREVIOUS

static final int PREVIOUS
Identifies the previous direction in a sequence.

Since:
1.4
See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SwingUtilities

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class SwingUtilities

java.lang.Object
    extended by  javax.swing.SwingUtilities
All Implemented Interfaces:
SwingConstants
public class SwingUtilities
extends Object
implements SwingConstants

A collection of utility methods for Swing.

Field Summary
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Method Summary
static Rectangle | calculateInnerArea(JComponent c, Rectangle r) Stores the position and size of the inner painting area of the specified component in r and returns r.
static Rectangle[] | computeDifference(Rectangle rectA, Rectangle rectB) Convenience returning an array of rect representing the regions within rectA that do not overlap with rectB.
static Rectangle | computeIntersection(int x, int y, int width, int height, Rectangle dest) Convenience to calculate the intersection of two rectangles without allocating a new rectangle.
static int | computeStringWidth(FontMetrics fm, String str) Compute the width of the string using a font with the specified "metrics" (sizes).
static Rectangle | computeUnion(int x, int y, int width, int height, Rectangle dest) Convenience method that calculates the union of two rectangles without allocating a new rectangle.
static MouseEvent | convertMouseEvent(Component source, MouseEvent sourceEvent, Component destination) Returns a MouseEvent similar to sourceEvent except that its x and y members have been converted to destination's coordinate system.
static Point | convertPoint(Component source, int x, int y, Component destination) Convert the point (x,y) in source coordinate system to destination coordinate system.
static Point | convertPoint(Component source, Point aPoint, Component destination) Convert a aPoint in source coordinate system to destination coordinate system.
static void | convertPointFromScreen(Point p, Component c) Convert a point from a screen coordinates to a component's coordinate system
static void | convertPointToScreen(Point p, Component c) Convert a point from a component's coordinate system to screen coordinates.
static Rectangle | convertRectangle(Component source, Rectangle aRectangle, Component destination) Convert the rectangle aRectangle in source coordinate system to destination coordinate system.
static Component | findFocusOwner(Component c) Deprecated. As of 1.4, replaced by KeyboardFocusManager.getFocusOwner().
static Accessible | getAccessibleAt(Component c, Point p) Returns the Accessible child contained at the local coordinate Point, if one exists.
static Accessible | getAccessibleChild(Component c, int i) Return the nth Accessible child of the object.
static int | getAccessibleChildrenCount(Component c) Returns the number of accessible children in the object.
static int | getAccessibleIndexInParent(Component c) Get the index of this object in its accessible parent.
static AccessibleStateSet | getAccessibleStateSet(Component c) Get the state of this object.
static Container | getAncestorNamed(String name, Component comp) Convenience method for searching above comp in the component hierarchy and returns the first object of name it finds.
static Container | getAncestorOfClass(Class<?> c, Component comp) Convenience method for searching above comp in the component hierarchy and returns the first object of class c it finds.
static Component | getDeepestComponentAt(Component parent, int x, int y) Returns the deepest visible descendent Component of parent that contains the location x, y.
static Rectangle | getLocalBounds(Component aComponent) Return the rectangle (0,0,bounds.width,bounds.height) for the component aComponent
static Component | getRoot(Component c) Returns the root component for the current component tree.
static JRootPane | getRootPane(Component c) If c is a JRootPane descendant return its JRootPane ancestor.
static ActionMap | getUIActionMap(JComponent component) Returns the ActionMap provided by the UI in component component.
static InputMap | getUIInputMap(JComponent component, int condition) Returns the InputMap provided by the UI for condition condition in component component.
static Window | getWindowAncestor(Component c) Returns the first Window ancestor of c, or null if c is not contained inside a Window.
static void | invokeAndWait(Runnable doRun) Causes doRun.run() to be executed synchronously on the AWT event dispatching thread.
static void | invokeLater(Runnable doRun) Causes doRun.run() to be executed asynchronously on the AWT event dispatching thread.
static boolean | isDescendingFrom(Component a, Component b) Return true if a component a descends from a component b
static boolean | isEventDispatchThread() Returns true if the current thread is an AWT event dispatching thread.
static boolean | isLeftMouseButton(MouseEvent anEvent) Returns true if the mouse event specifies the left mouse button.
static boolean | isMiddleMouseButton(MouseEvent anEvent) Returns true if the mouse event specifies the middle mouse button.
static boolean | isRectangleContainingRectangle(Rectangle a, Rectangle b) Return true if a contains b
static boolean | isRightMouseButton(MouseEvent anEvent) Returns true if the mouse event specifies the right mouse button.
static String | layoutCompoundLabel(FontMetrics fm, String text, Icon icon, int verticalAlignment, int horizontalAlignment, int verticalTextPosition, int horizontalTextPosition, Rectangle viewR, Rectangle iconR, Rectangle textR, int textIconGap) Compute and return the location of the icons origin, the location of origin of the text baseline, and a possibly clipped version of the compound labels string.
static String | layoutCompoundLabel(JComponent c, FontMetrics fm, String text, Icon icon, int verticalAlignment, int horizontalAlignment, int verticalTextPosition, int horizontalTextPosition, Rectangle viewR, Rectangle iconR, Rectangle textR, int textIconGap) Compute and return the location of the icons origin, the location of origin of the text baseline, and a possibly clipped version of the compound labels string.
static boolean | notifyAction(Action action, KeyStroke ks, KeyEvent event, Object sender, int modifiers) Invokes actionPerformed on action if action is enabled (and non-null).
static void | paintComponent(Graphics g, Component c, Container p, int x, int y, int w, int h) Paints a component to the specified Graphics.
static void | paintComponent(Graphics g, Component c, Container p, Rectangle r) Paints a component to the specified Graphics.
static boolean | processKeyBindings(KeyEvent event) Process the key bindings for the Component associated with event.
static void | replaceUIActionMap(JComponent component, ActionMap uiActionMap) Convenience method to change the UI ActionMap for component to uiActionMap.
static void | replaceUIInputMap(JComponent component, int type, InputMap uiInputMap) Convenience method to change the UI InputMap for component to uiInputMap.
static void | updateComponentTreeUI(Component c) A simple minded look and feel change: ask each node in the tree to updateUI() -- that is, to initialize its UI property with the current look and feel.
static Window | windowForComponent(Component c) Returns the first Window ancestor of c, or null if c is not contained inside a Window.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

isRectangleContainingRectangle

public static final boolean isRectangleContainingRectangle(Rectangle a,
                                                           Rectangle b)
Return true if a contains b

getLocalBounds

public static Rectangle getLocalBounds(Component aComponent)
Return the rectangle (0,0,bounds.width,bounds.height) for the component aComponent

getWindowAncestor

public static Window getWindowAncestor(Component c)
Returns the first Window ancestor of c, or null if c is not contained inside a Window.

Parameters:
c - Component to get Window ancestor of.
Returns:
the first Window ancestor of c, or null if c is not contained inside a Window.
Since:
1.3

convertPoint

public static Point convertPoint(Component source,
                                 Point aPoint,
                                 Component destination)
Convert a aPoint in source coordinate system to destination coordinate system. If source is null, aPoint is assumed to be in destination's root component coordinate system. If destination is null, aPoint will be converted to source's root component coordinate system. If both source and destination are null, return aPoint without any conversion.

convertPoint

public static Point convertPoint(Component source,
                                 int x,
                                 int y,
                                 Component destination)
Convert the point (x,y) in source coordinate system to destination coordinate system. If source is null, (x,y) is assumed to be in destination's root component coordinate system. If destination is null, (x,y) will be converted to source's root component coordinate system. If both source and destination are null, return (x,y) without any conversion.

convertRectangle

public static Rectangle convertRectangle(Component source,
                                         Rectangle aRectangle,
                                         Component destination)
Convert the rectangle aRectangle in source coordinate system to destination coordinate system. If source is null, aRectangle is assumed to be in destination's root component coordinate system. If destination is null, aRectangle will be converted to source's root component coordinate system. If both source and destination are null, return aRectangle without any conversion.

getAncestorOfClass

public static Container getAncestorOfClass(Class<?> c,
                                           Component comp)
Convenience method for searching above comp in the component hierarchy and returns the first object of class c it finds. Can return null, if a class c cannot be found.

getAncestorNamed

public static Container getAncestorNamed(String name,
                                         Component comp)
Convenience method for searching above comp in the component hierarchy and returns the first object of name it finds. Can return null, if name cannot be found.

getDeepestComponentAt

public static Component getDeepestComponentAt(Component parent,
                                              int x,
                                              int y)
Returns the deepest visible descendent Component of parent that contains the location x, y. If parent does not contain the specified location, then null is returned. If parent is not a container, or none of parent's visible descendents contain the specified location, parent is returned.

Parameters:
parent - the root component to begin the search
x - the x target location
y - the y target location

convertMouseEvent

public static MouseEvent convertMouseEvent(Component source,
                                           MouseEvent sourceEvent,
                                           Component destination)
Returns a MouseEvent similar to sourceEvent except that its x and y members have been converted to destination's coordinate system. If source is null, sourceEvent x and y members are assumed to be into destination's root component coordinate system. If destination is null, the returned MouseEvent will be in source's coordinate system. sourceEvent will not be changed. A new event is returned. the source field of the returned event will be set to destination if destination is non-null use the translateMouseEvent() method to translate a mouse event from one component to another without changing the source.

convertPointToScreen

public static void convertPointToScreen(Point p,
                                        Component c)
Convert a point from a component's coordinate system to screen coordinates.

Parameters:
p - a Point object (converted to the new coordinate system)
c - a Component object

convertPointFromScreen

public static void convertPointFromScreen(Point p,
                                          Component c)
Convert a point from a screen coordinates to a component's coordinate system

Parameters:
p - a Point object (converted to the new coordinate system)
c - a Component object

windowForComponent

public static Window windowForComponent(Component c)
Returns the first Window ancestor of c, or null if c is not contained inside a Window.

Note: This method provides the same functionality as getWindowAncestor.

Parameters:
c - Component to get Window ancestor of.
Returns:
the first Window ancestor of c, or null if c is not contained inside a Window.

isDescendingFrom

public static boolean isDescendingFrom(Component a,
                                       Component b)
Return true if a component a descends from a component b

computeIntersection

public static Rectangle computeIntersection(int x,
                                            int y,
                                            int width,
                                            int height,
                                            Rectangle dest)
Convenience to calculate the intersection of two rectangles without allocating a new rectangle. If the two rectangles don't intersect, then the returned rectangle begins at (0,0) and has zero width and height.

Parameters:
x - the X coordinate of the first rectangle's top-left point
y - the Y coordinate of the first rectangle's top-left point
width - the width of the first rectangle
height - the height of the first rectangle
dest - the second rectangle
Returns:
dest, modified to specify the intersection

computeUnion

public static Rectangle computeUnion(int x,
                                     int y,
                                     int width,
                                     int height,
                                     Rectangle dest)
Convenience method that calculates the union of two rectangles without allocating a new rectangle.

Parameters:
x - the x-coordinate of the first rectangle
y - the y-coordinate of the first rectangle
width - the width of the first rectangle
height - the height of the first rectangle
dest - the coordinates of the second rectangle; the union of the two rectangles is returned in this rectangle
Returns:
the dest Rectangle

computeDifference

public static Rectangle[] computeDifference(Rectangle rectA,
                                            Rectangle rectB)
Convenience returning an array of rect representing the regions within rectA that do not overlap with rectB. If the two Rects do not overlap, returns an empty array

isLeftMouseButton

public static boolean isLeftMouseButton(MouseEvent anEvent)
Returns true if the mouse event specifies the left mouse button.

Parameters:
anEvent - a MouseEvent object
Returns:
true if the left mouse button was active

isMiddleMouseButton

public static boolean isMiddleMouseButton(MouseEvent anEvent)
Returns true if the mouse event specifies the middle mouse button.

Parameters:
anEvent - a MouseEvent object
Returns:
true if the middle mouse button was active

isRightMouseButton

public static boolean isRightMouseButton(MouseEvent anEvent)
Returns true if the mouse event specifies the right mouse button.

Parameters:
anEvent - a MouseEvent object
Returns:
true if the right mouse button was active

computeStringWidth

public static int computeStringWidth(FontMetrics fm,
                                     String str)
Compute the width of the string using a font with the specified "metrics" (sizes).

Parameters:
fm - a FontMetrics object to compute with
str - the String to compute
Returns:
an int containing the string width

layoutCompoundLabel

public static String layoutCompoundLabel(JComponent c,
                                         FontMetrics fm,
                                         String text,
                                         Icon icon,
                                         int verticalAlignment,
                                         int horizontalAlignment,
                                         int verticalTextPosition,
                                         int horizontalTextPosition,
                                         Rectangle viewR,
                                         Rectangle iconR,
                                         Rectangle textR,
                                         int textIconGap)
Compute and return the location of the icons origin, the location of origin of the text baseline, and a possibly clipped version of the compound labels string. Locations are computed relative to the viewR rectangle. The JComponents orientation (LEADING/TRAILING) will also be taken into account and translated into LEFT/RIGHT values accordingly.

layoutCompoundLabel

public static String layoutCompoundLabel(FontMetrics fm,
                                         String text,
                                         Icon icon,
                                         int verticalAlignment,
                                         int horizontalAlignment,
                                         int verticalTextPosition,
                                         int horizontalTextPosition,
                                         Rectangle viewR,
                                         Rectangle iconR,
                                         Rectangle textR,
                                         int textIconGap)
Compute and return the location of the icons origin, the location of origin of the text baseline, and a possibly clipped version of the compound labels string. Locations are computed relative to the viewR rectangle. This layoutCompoundLabel() does not know how to handle LEADING/TRAILING values in horizontalTextPosition (they will default to RIGHT) and in horizontalAlignment (they will default to CENTER). Use the other version of layoutCompoundLabel() instead.

paintComponent

public static void paintComponent(Graphics g,
                                  Component c,
                                  Container p,
                                  int x,
                                  int y,
                                  int w,
                                  int h)
Paints a component to the specified Graphics. This method is primarily useful to render Components that don't exist as part of the visible containment hierarchy, but are used for rendering. For example, if you are doing your own rendering and want to render some text (or even HTML), you could make use of JLabel's text rendering support and have it paint directly by way of this method, without adding the label to the visible containment hierarchy.

This method makes use of CellRendererPane to handle the actual painting, and is only recommended if you use one component for rendering. If you make use of multiple components to handle the rendering, as JTable does, use CellRendererPane directly. Otherwise, as described below, you could end up with a CellRendererPane per Component.

If c's parent is not a CellRendererPane, a new CellRendererPane is created, c is added to it, and the CellRendererPane is added to p. If c's parent is a CellRendererPane and the CellRendererPanes parent is not p, it is added to p.

The component should either descend from JComponent or be another kind of lightweight component. A lightweight component is one whose "lightweight" property (returned by the Component isLightweight method) is true. If the Component is not lightweight, bad things map happen: crashes, exceptions, painting problems...

Parameters:
g - the Graphics object to draw on
c - the Component to draw
p - the intermediate Container
x - an int specifying the left side of the area draw in, in pixels, measured from the left edge of the graphics context
y - an int specifying the top of the area to draw in, in pixels measured down from the top edge of the graphics context
w - an int specifying the width of the area draw in, in pixels
h - an int specifying the height of the area draw in, in pixels
See Also:
CellRendererPane, Component.isLightweight()

paintComponent

public static void paintComponent(Graphics g,
                                  Component c,
                                  Container p,
                                  Rectangle r)
Paints a component to the specified Graphics. This is a cover method for paintComponent(Graphics,Component,Container,int,int,int,int). Refer to it for more information.

Parameters:
g - the Graphics object to draw on
c - the Component to draw
p - the intermediate Container
r - the Rectangle to draw in
See Also:
paintComponent(Graphics,Component,Container,int,int,int,int), CellRendererPane

updateComponentTreeUI

public static void updateComponentTreeUI(Component c)
A simple minded look and feel change: ask each node in the tree to updateUI() -- that is, to initialize its UI property with the current look and feel.

invokeLater

public static void invokeLater(Runnable doRun)
Causes doRun.run() to be executed asynchronously on the AWT event dispatching thread. This will happen after all pending AWT events have been processed. This method should be used when an application thread needs to update the GUI. In the following example the invokeLater call queues the Runnable object doHelloWorld on the event dispatching thread and then prints a message.
 Runnable doHelloWorld = new Runnable() {
     public void run() {
         System.out.println("Hello World on " + Thread.currentThread());
     }
 };

 SwingUtilities.invokeLater(doHelloWorld);
 System.out.println("This might well be displayed before the other message.");
If invokeLater is called from the event dispatching thread -- for example, from a JButton's ActionListener -- the doRun.run() will still be deferred until all pending events have been processed. Note that if the doRun.run() throws an uncaught exception the event dispatching thread will unwind (not the current thread).

Additional documentation and examples for this method can be found in How to Use Threads, in The Java Tutorial.

As of 1.3 this method is just a cover for java.awt.EventQueue.invokeLater().

Unlike the rest of Swing, this method can be invoked from any thread.

See Also:
invokeAndWait(java.lang.Runnable)

invokeAndWait

public static void invokeAndWait(Runnable doRun)
                          throws InterruptedException,
                                 InvocationTargetException
Causes doRun.run() to be executed synchronously on the AWT event dispatching thread. This call blocks until all pending AWT events have been processed and (then) doRun.run() returns. This method should be used when an application thread needs to update the GUI. It should'nt be called from the EventDispatchThread. Here's an example that creates a new application thread that uses invokeAndWait to print a string from the event dispatching thread and then, when that's finished, print a string from the application thread.
 final Runnable doHelloWorld = new Runnable() {
     public void run() {
         System.out.println("Hello World on " + Thread.currentThread());
     }
 };

 Thread appThread = new Thread() {
     public void run() {
         try {
             SwingUtilities.invokeAndWait(doHelloWorld);
         }
         catch (Exception e) {
             e.printStackTrace();
         }
         System.out.println("Finished on " + Thread.currentThread());
     }
 };
 appThread.start();
Note that if the Runnable.run method throws an uncaught exception (on the event dispatching thread) it's caught and rethrown, as an InvocationTargetException, on the caller's thread.

Additional documentation and examples for this method can be found in How to Use Threads, in The Java Tutorial.

As of 1.3 this method is just a cover for java.awt.EventQueue.invokeAndWait().

Throws:
InterruptedException - if we're interrupted while waiting for the event dispatching thread to finish excecuting doRun.run()
InvocationTargetException - if an exception is thrown while running doRun
See Also:
invokeLater(java.lang.Runnable)

isEventDispatchThread

public static boolean isEventDispatchThread()
Returns true if the current thread is an AWT event dispatching thread.

As of 1.3 this method is just a cover for java.awt.EventQueue.isDispatchThread().

Returns:
true if the current thread is an AWT event dispatching thread

getAccessibleIndexInParent

public static int getAccessibleIndexInParent(Component c)
Get the index of this object in its accessible parent.

Note: as of the Java 2 platform v1.3, it is recommended that developers call Component.AccessibleAWTComponent.getAccessibleIndexInParent() instead of using this method.

Returns:
-1 of this object does not have an accessible parent. Otherwise, the index of the child in its accessible parent.

getAccessibleAt

public static Accessible getAccessibleAt(Component c,
                                         Point p)
Returns the Accessible child contained at the local coordinate Point, if one exists. Otherwise returns null.

Returns:
the Accessible at the specified location, if it exists; otherwise null

getAccessibleStateSet

public static AccessibleStateSet getAccessibleStateSet(Component c)
Get the state of this object.

Note: as of the Java 2 platform v1.3, it is recommended that developers call Component.AccessibleAWTComponent.getAccessibleIndexInParent() instead of using this method.

Returns:
an instance of AccessibleStateSet containing the current state set of the object
See Also:
AccessibleState

getAccessibleChildrenCount

public static int getAccessibleChildrenCount(Component c)
Returns the number of accessible children in the object. If all of the children of this object implement Accessible, than this method should return the number of children of this object.

Note: as of the Java 2 platform v1.3, it is recommended that developers call Component.AccessibleAWTComponent.getAccessibleIndexInParent() instead of using this method.

Returns:
the number of accessible children in the object.

getAccessibleChild

public static Accessible getAccessibleChild(Component c,
                                            int i)
Return the nth Accessible child of the object.

Note: as of the Java 2 platform v1.3, it is recommended that developers call Component.AccessibleAWTComponent.getAccessibleIndexInParent() instead of using this method.

Parameters:
i - zero-based index of child
Returns:
the nth Accessible child of the object

findFocusOwner

@Deprecated
public static Component findFocusOwner(Component c)
Deprecated. As of 1.4, replaced by KeyboardFocusManager.getFocusOwner().

Return the child Component of the specified Component that is the focus owner, if any.

Parameters:
c - the root of the Component hierarchy to search for the focus owner
Returns:
the focus owner, or null if there is no focus owner, or if the focus owner is not comp, or a descendant of comp
See Also:
KeyboardFocusManager.getFocusOwner()

getRootPane

public static JRootPane getRootPane(Component c)
If c is a JRootPane descendant return its JRootPane ancestor. If c is a RootPaneContainer then return its JRootPane.

Returns:
the JRootPane for Component c or null.

getRoot

public static Component getRoot(Component c)
Returns the root component for the current component tree.

Returns:
the first ancestor of c that's a Window or the last Applet ancestor

processKeyBindings

public static boolean processKeyBindings(KeyEvent event)
Process the key bindings for the Component associated with event. This method is only useful if event.getComponent() does not descend from JComponent, or your are not invoking super.processKeyEvent from within your JComponent subclass. JComponent automatically processes bindings from within its processKeyEvent method, hence you rarely need to directly invoke this method.

Parameters:
event - KeyEvent used to identify which bindings to process, as well as which Component has focus.
Returns:
true if a binding has found and processed
Since:
1.4

notifyAction

public static boolean notifyAction(Action action,
                                   KeyStroke ks,
                                   KeyEvent event,
                                   Object sender,
                                   int modifiers)
Invokes actionPerformed on action if action is enabled (and non-null). The command for the ActionEvent is determined by:
  1. If the action was registered via registerKeyboardAction, then the command string passed in (null will be used if null was passed in).
  2. Action value with name Action.ACTION_COMMAND_KEY, unless null.
  3. String value of the KeyEvent, unless getKeyChar returns KeyEvent.CHAR_UNDEFINED..
This will return true if action is non-null and actionPerformed is invoked on it.

Since:
1.3

replaceUIInputMap

public static void replaceUIInputMap(JComponent component,
                                     int type,
                                     InputMap uiInputMap)
Convenience method to change the UI InputMap for component to uiInputMap. If uiInputMap is null, this removes any previously installed UI InputMap.

Since:
1.3

replaceUIActionMap

public static void replaceUIActionMap(JComponent component,
                                      ActionMap uiActionMap)
Convenience method to change the UI ActionMap for component to uiActionMap. If uiActionMap is null, this removes any previously installed UI ActionMap.

Since:
1.3

getUIInputMap

public static InputMap getUIInputMap(JComponent component,
                                     int condition)
Returns the InputMap provided by the UI for condition condition in component component.

This will return null if the UI has not installed a InputMap of the specified type.

Since:
1.3

getUIActionMap

public static ActionMap getUIActionMap(JComponent component)
Returns the ActionMap provided by the UI in component component.

This will return null if the UI has not installed an ActionMap.

Since:
1.3

calculateInnerArea

public static Rectangle calculateInnerArea(JComponent c,
                                           Rectangle r)
Stores the position and size of the inner painting area of the specified component in r and returns r. The position and size specify the bounds of the component, adjusted so as not to include the border area (the insets). This method is useful for classes that implement painting code.

Parameters:
c - the JComponent in question; if null, this method returns null
r - the Rectangle instance to be modified; may be null
Returns:
null if the Component is null; otherwise, returns the passed-in rectangle (if non-null) or a new rectangle specifying position and size information
Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SwingWorker

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class SwingWorker<T,V>

java.lang.Object
    extended by  javax.swing.SwingWorker<T,V>
Type Parameters:
T - the result type returned by this SwingWorker's doInBackground and get methods
V - the type used for carrying out intermediate results by this SwingWorker's publish and process methods
All Implemented Interfaces:
Runnable, Future<T>, RunnableFuture<T>
public abstract class SwingWorker<T,V>
extends Object
implements RunnableFuture<T>

An abstract class to perform lengthy GUI-interacting tasks in a dedicated thread.

When writing a multi-threaded application using Swing, there are two constraints to keep in mind: (refer to How to Use Threads for more details):

  • Time-consuming tasks should not be run on the Event Dispatch Thread. Otherwise the application becomes unresponsive.
  • Swing components should be accessed on the Event Dispatch Thread only.

These constraints mean that a GUI application with time intensive computing needs at least two threads: 1) a thread to perform the lengthy task and 2) the Event Dispatch Thread (EDT) for all GUI-related activities. This involves inter-thread communication which can be tricky to implement.

SwingWorker is designed for situations where you need to have a long running task run in a background thread and provide updates to the UI either when done, or while processing. Subclasses of SwingWorker must implement the doInBackground() method to perform the background computation.

Workflow

There are three threads involved in the life cycle of a SwingWorker :

  • Current thread: The execute() method is called on this thread. It schedules SwingWorker for the execution on a worker thread and returns immediately. One can wait for the SwingWorker to complete using the get methods.

  • Worker thread: The doInBackground() method is called on this thread. This is where all background activities should happen. To notify PropertyChangeListeners about bound properties changes use the firePropertyChange and getPropertyChangeSupport() methods. By default there are two bound properties available: state and progress.

  • Event Dispatch Thread: All Swing related activities occur on this thread. SwingWorker invokes the process and done() methods and notifies any PropertyChangeListeners on this thread.

Often, the Current thread is the Event Dispatch Thread.

Before the doInBackground method is invoked on a worker thread, SwingWorker notifies any PropertyChangeListeners about the state property change to StateValue.STARTED. After the doInBackground method is finished the done method is executed. Then SwingWorker notifies any PropertyChangeListeners about the state property change to StateValue.DONE.

SwingWorker is only designed to be executed once. Executing a SwingWorker more than once will not result in invoking the doInBackground method twice.

Sample Usage

The following example illustrates the simplest use case. Some processing is done in the background and when done you update a Swing component.

Say we want to find the "Meaning of Life" and display the result in a JLabel.

   final JLabel label;
   class MeaningOfLifeFinder extends SwingWorker<String, Object> {
       @Override
       public String doInBackground() {
           return findTheMeaningOfLife();
       }

       @Override
       protected void done() {
           try {
               label.setText(get());
           } catch (Exception ignore) {
           }
       }
   }

   (new MeaningOfLifeFinder()).execute();

The next example is useful in situations where you wish to process data as it is ready on the Event Dispatch Thread.

Now we want to find the first N prime numbers and display the results in a JTextArea. While this is computing, we want to update our progress in a JProgressBar. Finally, we also want to print the prime numbers to System.out.

 class PrimeNumbersTask extends
         SwingWorker<List<Integer>, Integer> {
     PrimeNumbersTask(JTextArea textArea, int numbersToFind) {
         //initialize
     }

     @Override
     public List<Integer> doInBackground() {
         while (! enough && ! isCancelled()) {
                 number = nextPrimeNumber();
                 publish(number);
                 setProgress(100 * numbers.size() / numbersToFind);
             }
         }
         return numbers;
     }

     @Override
     protected void process(List<Integer> chunks) {
         for (int number : chunks) {
             textArea.append(number + "\n");
         }
     }
 }

 JTextArea textArea = new JTextArea();
 final JProgressBar progressBar = new JProgressBar(0, 100);
 PrimeNumbersTask task = new PrimeNumbersTask(textArea, N);
 task.addPropertyChangeListener(
     new PropertyChangeListener() {
         public  void propertyChange(PropertyChangeEvent evt) {
             if ("progress".equals(evt.getPropertyName())) {
                 progressBar.setValue((Integer)evt.getNewValue());
             }
         }
     });

 task.execute();
 System.out.println(task.get()); //prints all prime numbers we have got

Because SwingWorker implements Runnable, a SwingWorker can be submitted to an Executor for execution.

Since:
1.6

Nested Class Summary
static class SwingWorker.StateValue
Values for the state bound property.
Constructor Summary
SwingWorker()
Constructs this SwingWorker.
Method Summary
 void addPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list.
 boolean cancel(boolean mayInterruptIfRunning)
Attempts to cancel execution of this task.
protected abstract  T doInBackground()
Computes a result, or throws an exception if unable to do so.
protected  void done()
Executed on the Event Dispatch Thread after the doInBackground method is finished.
 void execute()
Schedules this SwingWorker for execution on a worker thread.
 void firePropertyChange(String propertyName, Object oldValue, Object newValue)
Reports a bound property update to any registered listeners.
 T get()
Waits if necessary for the computation to complete, and then retrieves its result.
 T get(long timeout, TimeUnit unit)
Waits if necessary for at most the given time for the computation to complete, and then retrieves its result, if available.
 int getProgress()
Returns the progress bound property.
 PropertyChangeSupport getPropertyChangeSupport()
Returns the PropertyChangeSupport for this SwingWorker.
 SwingWorker.StateValue getState()
Returns the SwingWorker state bound property.
 boolean isCancelled()
Returns true if this task was cancelled before it completed normally.
 boolean isDone()
Returns true if this task completed.
protected  void process(List<V> chunks)
Receives data chunks from the publish method asynchronously on the Event Dispatch Thread.
protected  void publish(V... chunks)
Sends data chunks to the process(java.util.List) method.
 void removePropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list.
 void run()
Sets this Future to the result of computation unless it has been cancelled.
protected  void setProgress(int progress)
Sets the progress bound property.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SwingWorker

public SwingWorker()
Constructs this SwingWorker.

Method Detail

doInBackground

protected abstract T doInBackground()
                             throws Exception
Computes a result, or throws an exception if unable to do so.

Note that this method is executed only once.

Note: this method is executed in a background thread.

Returns:
the computed result
Throws:
Exception - if unable to compute a result

run

public final void run()
Sets this Future to the result of computation unless it has been cancelled.

Specified by:
run in interface Runnable
Specified by:
run in interface RunnableFuture<T>
See Also:
Thread.run()

publish

protected final void publish(V... chunks)
Sends data chunks to the process(java.util.List) method. This method is to be used from inside the doInBackground method to deliver intermediate results for processing on the Event Dispatch Thread inside the process method.

Because the process method is invoked asynchronously on the Event Dispatch Thread multiple invocations to the publish method might occur before the process method is executed. For performance purposes all these invocations are coalesced into one invocation with concatenated arguments.

For example:

 publish("1");
 publish("2", "3");
 publish("4", "5", "6");
might result in:
 process("1", "2", "3", "4", "5", "6")

Sample Usage. This code snippet loads some tabular data and updates DefaultTableModel with it. Note that it safe to mutate the tableModel from inside the process method because it is invoked on the Event Dispatch Thread.

 class TableSwingWorker extends
         SwingWorker<DefaultTableModel, Object[]> {
     private final DefaultTableModel tableModel;

     public TableSwingWorker(DefaultTableModel tableModel) {
         this.tableModel = tableModel;
     }

     @Override
     protected DefaultTableModel doInBackground() throws Exception {
         for (Object[] row = loadData();
                  ! isCancelled() && row != null;
                  row = loadData()) {
             publish((Object[]) row);
         }
         return tableModel;
     }

     @Override
     protected void process(List<Object[]> chunks) {
         for (Object[] row : chunks) {
             tableModel.addRow(row);
         }
     }
 }

Parameters:
chunks - intermediate results to process
See Also:
process(java.util.List)

process

protected void process(List<V> chunks)
Receives data chunks from the publish method asynchronously on the Event Dispatch Thread.

Please refer to the publish(V...) method for more details.

Parameters:
chunks - intermediate results to process
See Also:
publish(V...)

done

protected void done()
Executed on the Event Dispatch Thread after the doInBackground method is finished. The default implementation does nothing. Subclasses may override this method to perform completion actions on the Event Dispatch Thread. Note that you can query status inside the implementation of this method to determine the result of this task or whether this task has been cancelled.

See Also:
doInBackground(),
isCancelled(),
get()

setProgress

protected final void setProgress(int progress)
Sets the progress bound property. The value should be from 0 to 100.

Because PropertyChangeListeners are notified asynchronously on the Event Dispatch Thread multiple invocations to the setProgress method might occur before any PropertyChangeListeners are invoked. For performance purposes all these invocations are coalesced into one invocation with the last invocation argument only.

For example, the following invokations:

 setProgress(1);
 setProgress(2);
 setProgress(3);
might result in a single PropertyChangeListener notification with the value 3.

Parameters:
progress - the progress value to set
Throws:
IllegalArgumentException - is value not from 0 to 100

getProgress

public final int getProgress()
Returns the progress bound property.

Returns:
the progress bound property.

execute

public final void execute()
Schedules this SwingWorker for execution on a worker thread. There are a number of worker threads available. In the event all worker threads are busy handling other SwingWorkers this SwingWorker is placed in a waiting queue.

Note: SwingWorker is only designed to be executed once. Executing a SwingWorker more than once will not result in invoking the doInBackground method twice.

cancel

public final boolean cancel(boolean mayInterruptIfRunning)
Attempts to cancel execution of this task. This attempt will fail if the task has already completed, has already been cancelled, or could not be cancelled for some other reason. If successful, and this task has not started when cancel is called, this task should never run. If the task has already started, then the mayInterruptIfRunning parameter determines whether the thread executing this task should be interrupted in an attempt to stop the task.

After this method returns, subsequent calls to Future.isDone() will always return true. Subsequent calls to Future.isCancelled() will always return true if this method returned true.

Specified by:
cancel in interface Future<T>
Parameters:
mayInterruptIfRunning - true if the thread executing this task should be interrupted; otherwise, in-progress tasks are allowed to complete
Returns:
false if the task could not be cancelled, typically because it has already completed normally; true otherwise

isCancelled

public final boolean isCancelled()
Returns true if this task was cancelled before it completed normally.

Specified by:
isCancelled in interface Future<T>
Returns:
true if this task was cancelled before it completed

isDone

public final boolean isDone()
Returns true if this task completed. Completion may be due to normal termination, an exception, or cancellation -- in all of these cases, this method will return true.

Specified by:
isDone in interface Future<T>
Returns:
true if this task completed

get

public final T get()
            throws InterruptedException,
                   ExecutionException
Waits if necessary for the computation to complete, and then retrieves its result.

Note: calling get on the Event Dispatch Thread blocks all events, including repaints, from being processed until this SwingWorker is complete.

When you want the SwingWorker to block on the Event Dispatch Thread we recommend that you use a modal dialog.

For example:

 class SwingWorkerCompletionWaiter extends PropertyChangeListener {
     private JDialog dialog;

     public SwingWorkerCompletionWaiter(JDialog dialog) {
         this.dialog = dialog;
     }

     public void propertyChange(PropertyChangeEvent event) {
         if ("state".equals(event.getPropertyName())
                 && SwingWorker.StateValue.DONE == event.getNewValue()) {
             dialog.setVisible(false);
             dialog.dispose();
         }
     }
 }
 JDialog dialog = new JDialog(owner, true);
 swingWorker.addPropertyChangeListener(
     new SwingWorkerCompletionWaiter(dialog));
 swingWorker.execute();
 //the dialog will be visible until the SwingWorker is done
 dialog.setVisible(true);

Specified by:
get in interface Future<T>
Returns:
the computed result
Throws:
InterruptedException - if the current thread was interrupted while waiting
ExecutionException - if the computation threw an exception

get

public final T get(long timeout,
                   TimeUnit unit)
            throws InterruptedException,
                   ExecutionException,
                   TimeoutException
Waits if necessary for at most the given time for the computation to complete, and then retrieves its result, if available.

Please refer to get() for more details.

Specified by:
get in interface Future<T>
Parameters:
timeout - the maximum time to wait
unit - the time unit of the timeout argument
Returns:
the computed result
Throws:
InterruptedException - if the current thread was interrupted while waiting
ExecutionException - if the computation threw an exception
TimeoutException - if the wait timed out

addPropertyChangeListener

public final void addPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list. The listener is registered for all properties. The same listener object may be added more than once, and will be called as many times as it is added. If listener is null, no exception is thrown and no action is taken.

Note: This is merely a convenience wrapper. All work is delegated to PropertyChangeSupport from getPropertyChangeSupport().

Parameters:
listener - the PropertyChangeListener to be added

removePropertyChangeListener

public final void removePropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties. If listener was added more than once to the same event source, it will be notified one less time after being removed. If listener is null, or was never added, no exception is thrown and no action is taken.

Note: This is merely a convenience wrapper. All work is delegated to PropertyChangeSupport from getPropertyChangeSupport().

Parameters:
listener - the PropertyChangeListener to be removed

firePropertyChange

public final void firePropertyChange(String propertyName,
                                     Object oldValue,
                                     Object newValue)
Reports a bound property update to any registered listeners. No event is fired if old and new are equal and non-null.

This SwingWorker will be the source for any generated events.

When called off the Event Dispatch Thread PropertyChangeListeners are notified asynchronously on the Event Dispatch Thread.

Note: This is merely a convenience wrapper. All work is delegated to PropertyChangeSupport from getPropertyChangeSupport().

Parameters:
propertyName - the programmatic name of the property that was changed
oldValue - the old value of the property
newValue - the new value of the property

getPropertyChangeSupport

public final PropertyChangeSupport getPropertyChangeSupport()
Returns the PropertyChangeSupport for this SwingWorker. This method is used when flexible access to bound properties support is needed.

This SwingWorker will be the source for any generated events.

Note: The returned PropertyChangeSupport notifies any PropertyChangeListeners asynchronously on the Event Dispatch Thread in the event that firePropertyChange or fireIndexedPropertyChange are called off the Event Dispatch Thread.

Returns:
PropertyChangeSupport for this SwingWorker

getState

public final SwingWorker.StateValue getState()
Returns the SwingWorker state bound property.

Returns:
the current state
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SwingWorker.StateValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.swing
Enum SwingWorker.StateValue

java.lang.Object
    extended by  java.lang.Enum<SwingWorker.StateValue>
        extended by  javax.swing.SwingWorker.StateValue
All Implemented Interfaces:
Serializable, Comparable<SwingWorker.StateValue>
Enclosing class:
SwingWorker<T,V>
public static enum SwingWorker.StateValue
extends Enum<SwingWorker.StateValue>

Values for the state bound property.

Since:
1.6

Enum Constant Summary
DONE
SwingWorker is DONE after doInBackground method is finished.
PENDING
Initial SwingWorker state.
STARTED
SwingWorker is STARTED before invoking doInBackground.
Method Summary
static SwingWorker.StateValue | valueOf(String name) Returns the enum constant of this type with the specified name.
static SwingWorker.StateValue[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

PENDING

public static final SwingWorker.StateValue PENDING
Initial SwingWorker state.

STARTED

public static final SwingWorker.StateValue STARTED
SwingWorker is STARTED before invoking doInBackground.

DONE

public static final SwingWorker.StateValue DONE
SwingWorker is DONE after doInBackground method is finished.

Method Detail

values

public static SwingWorker.StateValue[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (SwingWorker.StateValue c : SwingWorker.StateValue.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static SwingWorker.StateValue valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


table

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.swing.table

Provides classes and interfaces for dealing with javax.swing.JTable.

See:
Description

Interface Summary
TableCellEditor | This interface defines the method any object that would like to be an editor of values for components such as JListBox, JComboBox, JTree, or JTable needs to implement.
TableCellRenderer | This interface defines the method required by any object that would like to be a renderer for cells in a JTable.
TableColumnModel | Defines the requirements for a table column model object suitable for use with JTable.
TableModel | The TableModel interface specifies the methods the JTable will use to interrogate a tabular data model.

Class Summary
AbstractTableModel | This abstract class provides default implementations for most of the methods in the TableModel interface.
DefaultTableCellRenderer | The standard class for rendering (displaying) individual cells in a JTable.
DefaultTableCellRenderer.UIResource | A subclass of DefaultTableCellRenderer that implements UIResource.
DefaultTableColumnModel | The standard column-handler for a JTable.
DefaultTableModel | This is an implementation of TableModel that uses a Vector of Vectors to store the cell value objects.
JTableHeader | This is the object which manages the header of the JTable.
TableColumn | A TableColumn represents all the attributes of a column in a JTable, such as width, resizibility, minimum and maximum width.
TableRowSorter<M extends TableModel> | An implementation of RowSorter that provides sorting and filtering using a TableModel.
TableStringConverter | TableStringConverter is used to convert objects from the model into strings.

Package javax.swing.table Description

Provides classes and interfaces for dealing with javax.swing.JTable. JTable is Swing's grid or tabular view for constructing user interfaces for tabular data structures inside an application. Use this package if you want control over how tables are constructed, updated, and rendered, as well as how data associated with the tables are viewed and managed.

Note: Most of the Swing API is not thread safe. For details, see Threads and Swing, a section in The Java Tutorial.

Related Documentation

For overviews, tutorials, examples, guides, and tool documentation, please see:
  • How to Use Tables, a section in The Java Tutorial

Since:
1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.swing.table Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.swing.table

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.swing.table.AbstractTableModel (implements java.io.Serializable, javax.swing.table.TableModel)
      • javax.swing.table.DefaultTableModel (implements java.io.Serializable)
    • javax.accessibility.AccessibleContext
      • java.awt.Component.AccessibleAWTComponent (implements javax.accessibility.AccessibleComponent, java.io.Serializable)
        • java.awt.Container.AccessibleAWTContainer
          • javax.swing.JComponent.AccessibleJComponent (implements javax.accessibility.AccessibleExtendedComponent)
            • javax.swing.table.JTableHeader.AccessibleJTableHeader
      • javax.swing.table.JTableHeader.AccessibleJTableHeader.AccessibleJTableHeaderEntry (implements javax.accessibility.Accessible, javax.accessibility.AccessibleComponent)
    • java.awt.Component (implements java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable)
      • java.awt.Container
        • javax.swing.JComponent (implements java.io.Serializable)
          • javax.swing.JLabel (implements javax.accessibility.Accessible, javax.swing.SwingConstants)
            • javax.swing.table.DefaultTableCellRenderer (implements java.io.Serializable, javax.swing.table.TableCellRenderer)
              • javax.swing.table.DefaultTableCellRenderer.UIResource (implements javax.swing.plaf.UIResource)
          • javax.swing.table.JTableHeader (implements javax.accessibility.Accessible, javax.swing.event.TableColumnModelListener)
    • javax.swing.table.DefaultTableColumnModel (implements javax.swing.event.ListSelectionListener, java.beans.PropertyChangeListener, java.io.Serializable, javax.swing.table.TableColumnModel)
    • javax.swing.RowSorter<M>
      • javax.swing.DefaultRowSorter<M,I>
        • javax.swing.table.TableRowSorter<M>
    • javax.swing.table.TableColumn (implements java.io.Serializable)
    • javax.swing.table.TableStringConverter

Interface Hierarchy

  • javax.swing.CellEditor
    • javax.swing.table.TableCellEditor
  • javax.swing.table.TableCellRenderer
  • javax.swing.table.TableColumnModel
  • javax.swing.table.TableModel
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.swing.table

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.swing.table

Packages that use javax.swing.table
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Classes in javax.swing.table used by javax.swing
JTableHeader
This is the object which manages the header of the JTable.
TableCellEditor
This interface defines the method any object that would like to be an editor of values for components such as JListBox, JComboBox, JTree, or JTable needs to implement.
TableCellRenderer
This interface defines the method required by any object that would like to be a renderer for cells in a JTable.
TableColumn
A TableColumn represents all the attributes of a column in a JTable, such as width, resizibility, minimum and maximum width.
TableColumnModel
Defines the requirements for a table column model object suitable for use with JTable.
TableModel
The TableModel interface specifies the methods the JTable will use to interrogate a tabular data model.

Classes in javax.swing.table used by javax.swing.event
TableColumnModel
Defines the requirements for a table column model object suitable for use with JTable.
TableModel
The TableModel interface specifies the methods the JTable will use to interrogate a tabular data model.

Classes in javax.swing.table used by javax.swing.plaf.basic
JTableHeader
This is the object which manages the header of the JTable.

Classes in javax.swing.table used by javax.swing.table
AbstractTableModel
This abstract class provides default implementations for most of the methods in the TableModel interface.
DefaultTableCellRenderer
The standard class for rendering (displaying) individual cells in a JTable.
JTableHeader
This is the object which manages the header of the JTable.
TableCellEditor
This interface defines the method any object that would like to be an editor of values for components such as JListBox, JComboBox, JTree, or JTable needs to implement.
TableCellRenderer
This interface defines the method required by any object that would like to be a renderer for cells in a JTable.
TableColumn
A TableColumn represents all the attributes of a column in a JTable, such as width, resizibility, minimum and maximum width.
TableColumnModel
Defines the requirements for a table column model object suitable for use with JTable.
TableModel
The TableModel interface specifies the methods the JTable will use to interrogate a tabular data model.
TableStringConverter
TableStringConverter is used to convert objects from the model into strings.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AbstractTableModel

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.table
Class AbstractTableModel

java.lang.Object
    extended by  javax.swing.table.AbstractTableModel
All Implemented Interfaces:
Serializable, TableModel
Direct Known Subclasses:
DefaultTableModel
public abstract class AbstractTableModel
extends Object
implements TableModel, Serializable

This abstract class provides default implementations for most of the methods in the TableModel interface. It takes care of the management of listeners and provides some conveniences for generating TableModelEvents and dispatching them to the listeners. To create a concrete TableModel as a subclass of AbstractTableModel you need only provide implementations for the following three methods:

  public int getRowCount();
  public int getColumnCount();
  public Object getValueAt(int row, int column);

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected  EventListenerList listenerList
List of listeners
Constructor Summary
AbstractTableModel()
Method Summary
 void addTableModelListener(TableModelListener l)
Adds a listener to the list that's notified each time a change to the data model occurs.
 int findColumn(String columnName)
Returns a column given its name.
 void fireTableCellUpdated(int row, int column)
Notifies all listeners that the value of the cell at [row, column] has been updated.
 void fireTableChanged(TableModelEvent e)
Forwards the given notification event to all TableModelListeners that registered themselves as listeners for this table model.
 void fireTableDataChanged()
Notifies all listeners that all cell values in the table's rows may have changed.
 void fireTableRowsDeleted(int firstRow, int lastRow)
Notifies all listeners that rows in the range [firstRow, lastRow], inclusive, have been deleted.
 void fireTableRowsInserted(int firstRow, int lastRow)
Notifies all listeners that rows in the range [firstRow, lastRow], inclusive, have been inserted.
 void fireTableRowsUpdated(int firstRow, int lastRow)
Notifies all listeners that rows in the range [firstRow, lastRow], inclusive, have been updated.
 void fireTableStructureChanged()
Notifies all listeners that the table's structure has changed.
 Class<?> getColumnClass(int columnIndex)
Returns Object.class regardless of columnIndex.
 String getColumnName(int column)
Returns a default name for the column using spreadsheet conventions: A, B, C, ...
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this AbstractTableModel.
 TableModelListener[] getTableModelListeners()
Returns an array of all the table model listeners registered on this model.
 boolean isCellEditable(int rowIndex, int columnIndex)
Returns false.
 void removeTableModelListener(TableModelListener l)
Removes a listener from the list that's notified each time a change to the data model occurs.
 void setValueAt(Object aValue, int rowIndex, int columnIndex)
This empty implementation is provided so users don't have to implement this method if their data model is not editable.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.swing.table.TableModel
getColumnCount, getRowCount, getValueAt

Field Detail

listenerList

protected EventListenerList listenerList
List of listeners

Constructor Detail

AbstractTableModel

public AbstractTableModel()
Method Detail

getColumnName

public String getColumnName(int column)
Returns a default name for the column using spreadsheet conventions: A, B, C, ... Z, AA, AB, etc. If column cannot be found, returns an empty string.

Specified by:
getColumnName in interface TableModel
Parameters:
column - the column being queried
Returns:
a string containing the default name of column

findColumn

public int findColumn(String columnName)
Returns a column given its name. Implementation is naive so this should be overridden if this method is to be called often. This method is not in the TableModel interface and is not used by the JTable.

Parameters:
columnName - string containing name of column to be located
Returns:
the column with columnName, or -1 if not found

getColumnClass

public Class<?> getColumnClass(int columnIndex)
Returns Object.class regardless of columnIndex.

Specified by:
getColumnClass in interface TableModel
Parameters:
columnIndex - the column being queried
Returns:
the Object.class

isCellEditable

public boolean isCellEditable(int rowIndex,
                              int columnIndex)
Returns false. This is the default implementation for all cells.

Specified by:
isCellEditable in interface TableModel
Parameters:
rowIndex - the row being queried
columnIndex - the column being queried
Returns:
false
See Also:
TableModel.setValueAt(java.lang.Object, int, int)

setValueAt

public void setValueAt(Object aValue,
                       int rowIndex,
                       int columnIndex)
This empty implementation is provided so users don't have to implement this method if their data model is not editable.

Specified by:
setValueAt in interface TableModel
Parameters:
aValue - value to assign to cell
rowIndex - row of cell
columnIndex - column of cell
See Also:
TableModel.getValueAt(int, int), TableModel.isCellEditable(int, int)

addTableModelListener

public void addTableModelListener(TableModelListener l)
Adds a listener to the list that's notified each time a change to the data model occurs.

Specified by:
addTableModelListener in interface TableModel
Parameters:
l - the TableModelListener

removeTableModelListener

public void removeTableModelListener(TableModelListener l)
Removes a listener from the list that's notified each time a change to the data model occurs.

Specified by:
removeTableModelListener in interface TableModel
Parameters:
l - the TableModelListener

getTableModelListeners

public TableModelListener[] getTableModelListeners()
Returns an array of all the table model listeners registered on this model.

Returns:
all of this model's TableModelListeners or an empty array if no table model listeners are currently registered
Since:
1.4
See Also:
addTableModelListener(javax.swing.event.TableModelListener), removeTableModelListener(javax.swing.event.TableModelListener)

fireTableDataChanged

public void fireTableDataChanged()
Notifies all listeners that all cell values in the table's rows may have changed. The number of rows may also have changed and the JTable should redraw the table from scratch. The structure of the table (as in the order of the columns) is assumed to be the same.

See Also:
TableModelEvent, EventListenerList, JTable.tableChanged(TableModelEvent)

fireTableStructureChanged

public void fireTableStructureChanged()
Notifies all listeners that the table's structure has changed. The number of columns in the table, and the names and types of the new columns may be different from the previous state. If the JTable receives this event and its autoCreateColumnsFromModel flag is set it discards any table columns that it had and reallocates default columns in the order they appear in the model. This is the same as calling setModel(TableModel) on the JTable.

See Also:
TableModelEvent, EventListenerList

fireTableRowsInserted

public void fireTableRowsInserted(int firstRow,
                                  int lastRow)
Notifies all listeners that rows in the range [firstRow, lastRow], inclusive, have been inserted.

Parameters:
firstRow - the first row
lastRow - the last row
See Also:
TableModelEvent, EventListenerList

fireTableRowsUpdated

public void fireTableRowsUpdated(int firstRow,
                                 int lastRow)
Notifies all listeners that rows in the range [firstRow, lastRow], inclusive, have been updated.

Parameters:
firstRow - the first row
lastRow - the last row
See Also:
TableModelEvent, EventListenerList

fireTableRowsDeleted

public void fireTableRowsDeleted(int firstRow,
                                 int lastRow)
Notifies all listeners that rows in the range [firstRow, lastRow], inclusive, have been deleted.

Parameters:
firstRow - the first row
lastRow - the last row
See Also:
TableModelEvent, EventListenerList

fireTableCellUpdated

public void fireTableCellUpdated(int row,
                                 int column)
Notifies all listeners that the value of the cell at [row, column] has been updated.

Parameters:
row - row of cell which has been updated
column - column of cell which has been updated
See Also:
TableModelEvent, EventListenerList

fireTableChanged

public void fireTableChanged(TableModelEvent e)
Forwards the given notification event to all TableModelListeners that registered themselves as listeners for this table model.

Parameters:
e - the event to be forwarded
See Also:
addTableModelListener(javax.swing.event.TableModelListener), TableModelEvent, EventListenerList

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this AbstractTableModel. FooListeners are registered using the addFooListener method.

You can specify the listenerType argument with a class literal, such as FooListener.class. For example, you can query a model m for its table model listeners with the following code:

TableModelListener[] tmls = (TableModelListener[])(m.getListeners(TableModelListener.class));
If no such listeners exist, this method returns an empty array.

Parameters:
listenerType - the type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener
Returns:
an array of all objects registered as FooListeners on this component, or an empty array if no such listeners have been added
Throws:
ClassCastException - if listenerType doesn't specify a class or interface that implements java.util.EventListener
Since:
1.3
See Also:
getTableModelListeners()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.swing.table.AbstractTableModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.table.AbstractTableModel

Packages that use AbstractTableModel
javax.swing.table Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of AbstractTableModel in javax.swing.table

Subclasses of AbstractTableModel in javax.swing.table
 class DefaultTableModel
This is an implementation of TableModel that uses a Vector of Vectors to store the cell value objects.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.table.DefaultTableCellRenderer

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.table.DefaultTableCellRenderer

Packages that use DefaultTableCellRenderer
javax.swing.table Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of DefaultTableCellRenderer in javax.swing.table

Subclasses of DefaultTableCellRenderer in javax.swing.table
static class DefaultTableCellRenderer.UIResource
A subclass of DefaultTableCellRenderer that implements UIResource.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.table.DefaultTableCellRenderer.UIResource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.table.DefaultTableCellRenderer.UIResource

No usage of javax.swing.table.DefaultTableCellRenderer.UIResource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.table.DefaultTableColumnModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.table.DefaultTableColumnModel

No usage of javax.swing.table.DefaultTableColumnModel

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.table.DefaultTableModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.table.DefaultTableModel

No usage of javax.swing.table.DefaultTableModel

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.table.JTableHeader

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.table.JTableHeader

Packages that use JTableHeader
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of JTableHeader in javax.swing

Fields in javax.swing declared as JTableHeader
protected  JTableHeader JTable.tableHeader
The TableHeader working with the table.

Methods in javax.swing that return JTableHeader
protected JTableHeader | JTable.createDefaultTableHeader() Returns the default table header object, which is a JTableHeader.
JTableHeader | JTable.getTableHeader() Returns the tableHeader used by this JTable.

Methods in javax.swing with parameters of type JTableHeader
 void JTable.setTableHeader(JTableHeader tableHeader)
Sets the tableHeader working with this JTable to newHeader.

Uses of JTableHeader in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as JTableHeader
protected  JTableHeader BasicTableHeaderUI.header
The JTableHeader that is delegating the painting to this UI.

Uses of JTableHeader in javax.swing.table

Constructors in javax.swing.table with parameters of type JTableHeader
JTableHeader.AccessibleJTableHeader.AccessibleJTableHeaderEntry(int c, JTableHeader p, JTable t)
Constructs an AccessiblJTableHeaaderEntry

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.table.JTableHeader.AccessibleJTableHeader

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.table.JTableHeader.AccessibleJTableHeader

No usage of javax.swing.table.JTableHeader.AccessibleJTableHeader

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.table.JTableHeader.AccessibleJTableHeader.AccessibleJTableHeaderEntry

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.table.JTableHeader.AccessibleJTableHeader.AccessibleJTableHeaderEntry

No usage of javax.swing.table.JTableHeader.AccessibleJTableHeader.AccessibleJTableHeaderEntry

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.table.TableColumn

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.table.TableColumn

Packages that use TableColumn
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of TableColumn in javax.swing

Methods in javax.swing that return TableColumn
 TableColumn JTable.getColumn(Object identifier)
Returns the TableColumn object for the column in the table whose identifier is equal to identifier, when compared using equals.

Methods in javax.swing with parameters of type TableColumn
void | JTable.addColumn(TableColumn aColumn) Appends aColumn to the end of the array of columns held by this JTable's column model.
void | JTable.removeColumn(TableColumn aColumn) Removes aColumn from this JTable's array of columns.

Uses of TableColumn in javax.swing.table

Fields in javax.swing.table declared as TableColumn
protected TableColumn | JTableHeader.draggedColumn The index of the column being dragged.
protected TableColumn | JTableHeader.resizingColumn The index of the column being resized.

Fields in javax.swing.table with type parameters of type TableColumn
protected  Vector<TableColumn> DefaultTableColumnModel.tableColumns
Array of TableColumn objects in this model

Methods in javax.swing.table that return TableColumn
TableColumn | DefaultTableColumnModel.getColumn(int columnIndex) Returns the TableColumn object for the column at columnIndex.
TableColumn | TableColumnModel.getColumn(int columnIndex) Returns the TableColumn object for the column at columnIndex.
TableColumn | JTableHeader.getDraggedColumn() Returns the the dragged column, if and only if, a drag is in process, otherwise returns null.
TableColumn | JTableHeader.getResizingColumn() Returns the resizing column.

Methods in javax.swing.table that return types with arguments of type TableColumn
Enumeration<TableColumn> | DefaultTableColumnModel.getColumns() Returns an Enumeration of all the columns in the model.
Enumeration<TableColumn> | TableColumnModel.getColumns() Returns an Enumeration of all the columns in the model.

Methods in javax.swing.table with parameters of type TableColumn
void | DefaultTableColumnModel.addColumn(TableColumn aColumn) Appends aColumn to the end of the tableColumns array.
void | TableColumnModel.addColumn(TableColumn aColumn) Appends aColumn to the end of the tableColumns array.
void | DefaultTableColumnModel.removeColumn(TableColumn column) Deletes the column from the tableColumns array.
void | TableColumnModel.removeColumn(TableColumn column) Deletes the TableColumn column from the tableColumns array.
void | JTableHeader.setDraggedColumn(TableColumn aColumn) Sets the header's draggedColumn to aColumn.
void | JTableHeader.setResizingColumn(TableColumn aColumn) Sets the header's resizingColumn to aColumn.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.table.TableRowSorter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.table.TableRowSorter

No usage of javax.swing.table.TableRowSorter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.table.TableStringConverter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.table.TableStringConverter

Packages that use TableStringConverter
javax.swing.table Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of TableStringConverter in javax.swing.table

Methods in javax.swing.table that return TableStringConverter
 TableStringConverter TableRowSorter.getStringConverter()
Returns the object responsible for converting values from the model to strings.

Methods in javax.swing.table with parameters of type TableStringConverter
 void TableRowSorter.setStringConverter(TableStringConverter stringConverter)
Sets the object responsible for converting values from the model to strings.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.table.TableCellEditor

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.table.TableCellEditor

Packages that use TableCellEditor
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of TableCellEditor in javax.swing

Classes in javax.swing that implement TableCellEditor
 class DefaultCellEditor
The default editor for table and tree cells.

Fields in javax.swing declared as TableCellEditor
protected  TableCellEditor JTable.cellEditor
The active cell editor object, that overwrites the screen real estate occupied by the current cell and allows the user to change its contents.

Methods in javax.swing that return TableCellEditor
TableCellEditor | JTable.getCellEditor() Returns the active cell editor, which is null if the table is not currently editing.
TableCellEditor | JTable.getCellEditor(int row, int column) Returns an appropriate editor for the cell specified by row and column.
TableCellEditor | JTable.getDefaultEditor(Class<?> columnClass) Returns the editor to be used when no editor has been set in a TableColumn.

Methods in javax.swing with parameters of type TableCellEditor
Component | JTable.prepareEditor(TableCellEditor editor, int row, int column) Prepares the editor by querying the data model for the value and selection state of the cell at row, column.
void | JTable.setCellEditor(TableCellEditor anEditor) Sets the active cell editor.
void | JTable.setDefaultEditor(Class<?> columnClass, TableCellEditor editor) Sets a default cell editor to be used if no editor has been set in a TableColumn.

Uses of TableCellEditor in javax.swing.table

Fields in javax.swing.table declared as TableCellEditor
protected  TableCellEditor TableColumn.cellEditor
The editor used to edit the data cells of the column.

Methods in javax.swing.table that return TableCellEditor
 TableCellEditor TableColumn.getCellEditor()
Returns the TableCellEditor used by the JTable to edit values for this column.

Methods in javax.swing.table with parameters of type TableCellEditor
 void TableColumn.setCellEditor(TableCellEditor cellEditor)
Sets the editor to used by when a cell in this column is edited.

Constructors in javax.swing.table with parameters of type TableCellEditor
TableColumn(int modelIndex, int width, TableCellRenderer cellRenderer, TableCellEditor cellEditor)
Creates and initializes an instance of TableColumn with the specified model index, width, cell renderer, and cell editor; all TableColumn constructors delegate to this one.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.table.TableCellRenderer

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.table.TableCellRenderer

Packages that use TableCellRenderer
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of TableCellRenderer in javax.swing

Methods in javax.swing that return TableCellRenderer
TableCellRenderer | JTable.getCellRenderer(int row, int column) Returns an appropriate renderer for the cell specified by this row and column.
TableCellRenderer | JTable.getDefaultRenderer(Class<?> columnClass) Returns the cell renderer to be used when no renderer has been set in a TableColumn.

Methods in javax.swing with parameters of type TableCellRenderer
Component | JTable.prepareRenderer(TableCellRenderer renderer, int row, int column) Prepares the renderer by querying the data model for the value and selection state of the cell at row, column.
void | JTable.setDefaultRenderer(Class<?> columnClass, TableCellRenderer renderer) Sets a default cell renderer to be used if no renderer has been set in a TableColumn.

Uses of TableCellRenderer in javax.swing.table

Classes in javax.swing.table that implement TableCellRenderer
class | DefaultTableCellRenderer The standard class for rendering (displaying) individual cells in a JTable.
static class | DefaultTableCellRenderer.UIResource A subclass of DefaultTableCellRenderer that implements UIResource.

Fields in javax.swing.table declared as TableCellRenderer
protected TableCellRenderer | TableColumn.cellRenderer The renderer used to draw the data cells of the column.
protected TableCellRenderer | TableColumn.headerRenderer The renderer used to draw the header of the column.

Methods in javax.swing.table that return TableCellRenderer
protected TableCellRenderer | TableColumn.createDefaultHeaderRenderer() As of Java 2 platform v1.3, this method is not called by the TableColumn constructor.
protected TableCellRenderer | JTableHeader.createDefaultRenderer() Returns a default renderer to be used when no header renderer is defined by a TableColumn.
TableCellRenderer | TableColumn.getCellRenderer() Returns the TableCellRenderer used by the JTable to draw values for this column.
TableCellRenderer | JTableHeader.getDefaultRenderer() Returns the default renderer used when no headerRenderer is defined by a TableColumn.
TableCellRenderer | TableColumn.getHeaderRenderer() Returns the TableCellRenderer used to draw the header of the TableColumn.

Methods in javax.swing.table with parameters of type TableCellRenderer
void | TableColumn.setCellRenderer(TableCellRenderer cellRenderer) Sets the TableCellRenderer used by JTable to draw individual values for this column.
void | JTableHeader.setDefaultRenderer(TableCellRenderer defaultRenderer) Sets the default renderer to be used when no headerRenderer is defined by a TableColumn.
void | TableColumn.setHeaderRenderer(TableCellRenderer headerRenderer) Sets the TableCellRenderer used to draw the TableColumn's header to headerRenderer.

Constructors in javax.swing.table with parameters of type TableCellRenderer
TableColumn(int modelIndex, int width, TableCellRenderer cellRenderer, TableCellEditor cellEditor)
Creates and initializes an instance of TableColumn with the specified model index, width, cell renderer, and cell editor; all TableColumn constructors delegate to this one.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.table.TableColumnModel

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.table.TableColumnModel

Packages that use TableColumnModel
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of TableColumnModel in javax.swing

Fields in javax.swing declared as TableColumnModel
protected  TableColumnModel JTable.columnModel
The TableColumnModel of the table.

Methods in javax.swing that return TableColumnModel
protected TableColumnModel | JTable.createDefaultColumnModel() Returns the default column model object, which is a DefaultTableColumnModel.
TableColumnModel | JTable.getColumnModel() Returns the TableColumnModel that contains all column information of this table.

Methods in javax.swing with parameters of type TableColumnModel
 void JTable.setColumnModel(TableColumnModel columnModel)
Sets the column model for this table to newModel and registers for listener notifications from the new column model.

Constructors in javax.swing with parameters of type TableColumnModel
JTable(TableModel dm, TableColumnModel cm)
Constructs a JTable that is initialized with dm as the data model, cm as the column model, and a default selection model.
JTable(TableModel dm, TableColumnModel cm, ListSelectionModel sm)
Constructs a JTable that is initialized with dm as the data model, cm as the column model, and sm as the selection model.

Uses of TableColumnModel in javax.swing.event

Constructors in javax.swing.event with parameters of type TableColumnModel
TableColumnModelEvent(TableColumnModel source, int from, int to)
Constructs a TableColumnModelEvent object.

Uses of TableColumnModel in javax.swing.table

Classes in javax.swing.table that implement TableColumnModel
 class DefaultTableColumnModel
The standard column-handler for a JTable.

Fields in javax.swing.table declared as TableColumnModel
protected  TableColumnModel JTableHeader.columnModel
The TableColumnModel of the table header.

Methods in javax.swing.table that return TableColumnModel
protected TableColumnModel | JTableHeader.createDefaultColumnModel() Returns the default column model object which is a DefaultTableColumnModel.
TableColumnModel | JTableHeader.getColumnModel() Returns the TableColumnModel that contains all column information of this table header.

Methods in javax.swing.table with parameters of type TableColumnModel
 void JTableHeader.setColumnModel(TableColumnModel columnModel)
Sets the column model for this table to newModel and registers for listener notifications from the new column model.

Constructors in javax.swing.table with parameters of type TableColumnModel
JTableHeader(TableColumnModel cm)
Constructs a JTableHeader which is initialized with cm as the column model.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.table.TableModel

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.table.TableModel

Packages that use TableModel
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.table | Provides classes and interfaces for dealing with javax.swing.JTable.

Uses of TableModel in javax.swing

Fields in javax.swing declared as TableModel
protected  TableModel JTable.dataModel
The TableModel of the table.

Methods in javax.swing that return TableModel
protected TableModel | JTable.createDefaultDataModel() Returns the default table model object, which is a DefaultTableModel.
TableModel | JTable.getModel() Returns the TableModel that provides the data displayed by this JTable.

Methods in javax.swing that return types with arguments of type TableModel
 RowSorter<? extends TableModel> JTable.getRowSorter()
Returns the object responsible for sorting.

Methods in javax.swing with parameters of type TableModel
 void JTable.setModel(TableModel dataModel)
Sets the data model for this table to newModel and registers with it for listener notifications from the new data model.

Method parameters in javax.swing with type arguments of type TableModel
 void JTable.setRowSorter(RowSorter<? extends TableModel> sorter)
Sets the RowSorter.

Constructors in javax.swing with parameters of type TableModel
JTable(TableModel dm)
Constructs a JTable that is initialized with dm as the data model, a default column model, and a default selection model.
JTable(TableModel dm, TableColumnModel cm)
Constructs a JTable that is initialized with dm as the data model, cm as the column model, and a default selection model.
JTable(TableModel dm, TableColumnModel cm, ListSelectionModel sm)
Constructs a JTable that is initialized with dm as the data model, cm as the column model, and sm as the selection model.

Uses of TableModel in javax.swing.event

Constructors in javax.swing.event with parameters of type TableModel
TableModelEvent(TableModel source)
All row data in the table has changed, listeners should discard any state that was based on the rows and requery the TableModel to get the new row count and all the appropriate values.
TableModelEvent(TableModel source, int row)
This row of data has been updated.
TableModelEvent(TableModel source, int firstRow, int lastRow)
The data in rows [firstRow, lastRow] have been updated.
TableModelEvent(TableModel source, int firstRow, int lastRow, int column)
The cells in column column in the range [firstRow, lastRow] have been updated.
TableModelEvent(TableModel source, int firstRow, int lastRow, int column, int type)
The cells from (firstRow, column) to (lastRow, column) have been changed.

Uses of TableModel in javax.swing.table

Classes in javax.swing.table with type parameters of type TableModel
 class TableRowSorter<M extends TableModel>
An implementation of RowSorter that provides sorting and filtering using a TableModel.

Classes in javax.swing.table that implement TableModel
class | AbstractTableModel This abstract class provides default implementations for most of the methods in the TableModel interface.
class | DefaultTableModel This is an implementation of TableModel that uses a Vector of Vectors to store the cell value objects.

Methods in javax.swing.table with parameters of type TableModel
abstract  String TableStringConverter.toString(TableModel model, int row, int column)
Returns the string representation of the value at the specified location.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DefaultTableCellRenderer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.table
Class DefaultTableCellRenderer

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JLabel
                    extended by  javax.swing.table.DefaultTableCellRenderer
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, SwingConstants, TableCellRenderer
Direct Known Subclasses:
DefaultTableCellRenderer.UIResource
public class DefaultTableCellRenderer
extends JLabel
implements TableCellRenderer, Serializable

The standard class for rendering (displaying) individual cells in a JTable.

Implementation Note: This class inherits from JLabel, a standard component class. However JTable employs a unique mechanism for rendering its cells and therefore requires some slightly modified behavior from its cell renderer. The table class defines a single cell renderer and uses it as a as a rubber-stamp for rendering all cells in the table; it renders the first cell, changes the contents of that cell renderer, shifts the origin to the new location, re-draws it, and so on. The standard JLabel component was not designed to be used this way and we want to avoid triggering a revalidate each time the cell is drawn. This would greatly decrease performance because the revalidate message would be passed up the hierarchy of the container to determine whether any other components would be affected. As the renderer is only parented for the lifetime of a painting operation we similarly want to avoid the overhead associated with walking the hierarchy for painting operations. So this class overrides the validate, invalidate, revalidate, repaint, and firePropertyChange methods to be no-ops and override the isOpaque method solely to improve performance. If you write your own renderer, please keep this performance consideration in mind.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JTable

Nested Class Summary
static class DefaultTableCellRenderer.UIResource
A subclass of DefaultTableCellRenderer that implements UIResource.
Nested classes/interfaces inherited from class javax.swing.JLabel
JLabel.AccessibleJLabel
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected static Border noFocusBorder
An empty Border.
Fields inherited from class javax.swing.JLabel
labelFor
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
DefaultTableCellRenderer()
Creates a default table cell renderer.
Method Summary
void | firePropertyChange(String propertyName, boolean oldValue, boolean newValue) Overridden for performance reasons.
protected void | firePropertyChange(String propertyName, Object oldValue, Object newValue) Overridden for performance reasons.
Component | getTableCellRendererComponent(JTable table, Object value, boolean isSelected, boolean hasFocus, int row, int column) Returns the default table cell renderer.
void | invalidate() Overridden for performance reasons.
boolean | isOpaque() Overridden for performance reasons.
void | repaint() Overridden for performance reasons.
void | repaint(long tm, int x, int y, int width, int height) Overridden for performance reasons.
void | repaint(Rectangle r) Overridden for performance reasons.
void | revalidate() Overridden for performance reasons.
void | setBackground(Color c) Overrides JComponent.setBackground to assign the unselected-background color to the specified color.
void | setForeground(Color c) Overrides JComponent.setForeground to assign the unselected-foreground color to the specified color.
protected void | setValue(Object value) Sets the String object for the cell being rendered to value.
void | updateUI() Notification from the UIManager that the look and feel [L&F] has changed.
void | validate() Overridden for performance reasons.
Methods inherited from class javax.swing.JLabel
checkHorizontalKey, checkVerticalKey, getAccessibleContext, getDisabledIcon, getDisplayedMnemonic, getDisplayedMnemonicIndex, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getLabelFor, getText, getUI, getUIClassID, getVerticalAlignment, getVerticalTextPosition, imageUpdate, paramString, setDisabledIcon, setDisplayedMnemonic, setDisplayedMnemonic, setDisplayedMnemonicIndex, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabelFor, setText, setUI, setVerticalAlignment, setVerticalTextPosition
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

noFocusBorder

protected static Border noFocusBorder
An empty Border. This field might not be used. To change the Border used by this renderer override the getTableCellRendererComponent method and set the border of the returned component directly.

Constructor Detail

DefaultTableCellRenderer

public DefaultTableCellRenderer()
Creates a default table cell renderer.

Method Detail

setForeground

public void setForeground(Color c)
Overrides JComponent.setForeground to assign the unselected-foreground color to the specified color.

Overrides:
setForeground in class JComponent
Parameters:
c - set the foreground color to this value
See Also:
Component.getForeground()

setBackground

public void setBackground(Color c)
Overrides JComponent.setBackground to assign the unselected-background color to the specified color.

Overrides:
setBackground in class JComponent
Parameters:
c - set the background color to this value
See Also:
Component.getBackground(), JComponent.setOpaque(boolean)

updateUI

public void updateUI()
Notification from the UIManager that the look and feel [L&F] has changed. Replaces the current UI object with the latest version from the UIManager.

Overrides:
updateUI in class JLabel
See Also:
JComponent.updateUI()

getTableCellRendererComponent

public Component getTableCellRendererComponent(JTable table,
                                               Object value,
                                               boolean isSelected,
                                               boolean hasFocus,
                                               int row,
                                               int column)
Returns the default table cell renderer.

During a printing operation, this method will be called with isSelected and hasFocus values of false to prevent selection and focus from appearing in the printed output. To do other customization based on whether or not the table is being printed, check the return value from JComponent.isPaintingForPrint().

Specified by:
getTableCellRendererComponent in interface TableCellRenderer
Parameters:
table - the JTable
value - the value to assign to the cell at [row, column]
isSelected - true if cell is selected
hasFocus - true if cell has focus
row - the row of the cell to render
column - the column of the cell to render
Returns:
the default table cell renderer
See Also:
JComponent.isPaintingForPrint()

isOpaque

public boolean isOpaque()
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
isOpaque in class JComponent
Returns:
true if this component is completely opaque
See Also:
JComponent.setOpaque(boolean)

invalidate

public void invalidate()
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
invalidate in class Container
Since:
1.5
See Also:
Container.validate(), Container.layout(), LayoutManager, LayoutManager2.invalidateLayout(Container)

validate

public void validate()
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
validate in class Container
See Also:
Container.add(java.awt.Component),
Component.invalidate(),
JComponent.revalidate(),
Container.validateTree()

revalidate

public void revalidate()
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
revalidate in class JComponent
See Also:
Component.invalidate(),
Container.validate(),
JComponent.isValidateRoot(),
RepaintManager.addInvalidComponent(javax.swing.JComponent)

repaint

public void repaint(long tm,
                    int x,
                    int y,
                    int width,
                    int height)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
repaint in class JComponent
Parameters:
tm - this parameter is not used
x - the x value of the dirty region
y - the y value of the dirty region
width - the width of the dirty region
height - the height of the dirty region
See Also:
Component.isShowing(), RepaintManager.addDirtyRegion(javax.swing.JComponent, int, int, int, int)

repaint

public void repaint(Rectangle r)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
repaint in class JComponent
Parameters:
r - a Rectangle containing the dirty region
See Also:
Component.isShowing(), RepaintManager.addDirtyRegion(javax.swing.JComponent, int, int, int, int)

repaint

public void repaint()
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
repaint in class Component
Since:
1.5
See Also:
Component.update(Graphics)

firePropertyChange

protected void firePropertyChange(String propertyName,
                                  Object oldValue,
                                  Object newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class Component
Parameters:
propertyName - the property whose value has changed
oldValue - the property's previous value
newValue - the property's new value

firePropertyChange

public void firePropertyChange(String propertyName,
                               boolean oldValue,
                               boolean newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class JComponent
Parameters:
propertyName - the property whose value has changed
oldValue - the property's previous value
newValue - the property's new value

setValue

protected void setValue(Object value)
Sets the String object for the cell being rendered to value.

Parameters:
value - the string value for this cell; if value is null it sets the text value to an empty string
See Also:
JLabel.setText(java.lang.String)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultTableCellRenderer.UIResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.table
Class DefaultTableCellRenderer.UIResource

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JLabel
                    extended by  javax.swing.table.DefaultTableCellRenderer
                        extended by  javax.swing.table.DefaultTableCellRenderer.UIResource
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, UIResource, SwingConstants, TableCellRenderer
Enclosing class:
DefaultTableCellRenderer
public static class DefaultTableCellRenderer.UIResource
extends DefaultTableCellRenderer
implements UIResource

A subclass of DefaultTableCellRenderer that implements UIResource. DefaultTableCellRenderer doesn't implement UIResource directly so that applications can safely override the cellRenderer property with DefaultTableCellRenderer subclasses.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.table.DefaultTableCellRenderer
DefaultTableCellRenderer.UIResource
Nested classes/interfaces inherited from class javax.swing.JLabel
JLabel.AccessibleJLabel
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class javax.swing.table.DefaultTableCellRenderer
noFocusBorder
Fields inherited from class javax.swing.JLabel
labelFor
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
DefaultTableCellRenderer.UIResource()
Method Summary
Methods inherited from class javax.swing.table.DefaultTableCellRenderer
firePropertyChange, firePropertyChange, getTableCellRendererComponent, invalidate, isOpaque, repaint, repaint, repaint, revalidate, setBackground, setForeground, setValue, updateUI, validate
Methods inherited from class javax.swing.JLabel
checkHorizontalKey, checkVerticalKey, getAccessibleContext, getDisabledIcon, getDisplayedMnemonic, getDisplayedMnemonicIndex, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getLabelFor, getText, getUI, getUIClassID, getVerticalAlignment, getVerticalTextPosition, imageUpdate, paramString, setDisabledIcon, setDisplayedMnemonic, setDisplayedMnemonic, setDisplayedMnemonicIndex, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabelFor, setText, setUI, setVerticalAlignment, setVerticalTextPosition
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DefaultTableCellRenderer.UIResource

public DefaultTableCellRenderer.UIResource()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultTableColumnModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.table
Class DefaultTableColumnModel

java.lang.Object
    extended by  javax.swing.table.DefaultTableColumnModel
All Implemented Interfaces:
PropertyChangeListener, Serializable, EventListener, ListSelectionListener, TableColumnModel
public class DefaultTableColumnModel
extends Object
implements TableColumnModel, PropertyChangeListener, ListSelectionListener, Serializable

The standard column-handler for a JTable.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JTable

Field Summary
protected ChangeEvent | changeEvent Change event (only one needed)
protected int | columnMargin Width margin between each column
protected boolean | columnSelectionAllowed Column selection allowed in this column model
protected EventListenerList | listenerList List of TableColumnModelListener
protected ListSelectionModel | selectionModel Model for keeping track of column selections
protected Vector<TableColumn> | tableColumns Array of TableColumn objects in this model
protected int | totalColumnWidth A local cache of the combined width of all columns
Constructor Summary
DefaultTableColumnModel()
Creates a default table column model.
Method Summary
 void addColumn(TableColumn aColumn)
Appends aColumn to the end of the tableColumns array.
 void addColumnModelListener(TableColumnModelListener x)
Adds a listener for table column model events.
protected  ListSelectionModel createSelectionModel()
Creates a new default list selection model.
protected  void fireColumnAdded(TableColumnModelEvent e)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireColumnMarginChanged()
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireColumnMoved(TableColumnModelEvent e)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireColumnRemoved(TableColumnModelEvent e)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireColumnSelectionChanged(ListSelectionEvent e)
Notifies all listeners that have registered interest for notification on this event type.
 TableColumn getColumn(int columnIndex)
Returns the TableColumn object for the column at columnIndex.
 int getColumnCount()
Returns the number of columns in the tableColumns array.
 int getColumnIndex(Object identifier)
Returns the index of the first column in the tableColumns array whose identifier is equal to identifier, when compared using equals.
 int getColumnIndexAtX(int x)
Returns the index of the column that lies at position x, or -1 if no column covers this point.
 int getColumnMargin()
Returns the width margin for TableColumn.
 TableColumnModelListener[] getColumnModelListeners()
Returns an array of all the column model listeners registered on this model.
 Enumeration<TableColumn> getColumns()
Returns an Enumeration of all the columns in the model.
 boolean getColumnSelectionAllowed()
Returns true if column selection is allowed, otherwise false.
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this model.
 int getSelectedColumnCount()
Returns the number of columns selected.
 int[] getSelectedColumns()
Returns an array of selected columns.
 ListSelectionModel getSelectionModel()
Returns the ListSelectionModel that is used to maintain column selection state.
 int getTotalColumnWidth()
Returns the total combined width of all columns.
 void moveColumn(int columnIndex, int newIndex)
Moves the column and heading at columnIndex to newIndex.
 void propertyChange(PropertyChangeEvent evt)
Property Change Listener change method.
protected  void recalcWidthCache()
Recalculates the total combined width of all columns.
 void removeColumn(TableColumn column)
Deletes the column from the tableColumns array.
 void removeColumnModelListener(TableColumnModelListener x)
Removes a listener for table column model events.
 void setColumnMargin(int newMargin)
Sets the column margin to newMargin.
 void setColumnSelectionAllowed(boolean flag)
Sets whether column selection is allowed.
 void setSelectionModel(ListSelectionModel newModel)
Sets the selection model for this TableColumnModel to newModel and registers for listener notifications from the new selection model.
 void valueChanged(ListSelectionEvent e)
A ListSelectionListener that forwards ListSelectionEvents when there is a column selection change.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

tableColumns

protected Vector<TableColumn> tableColumns
Array of TableColumn objects in this model

selectionModel

protected ListSelectionModel selectionModel
Model for keeping track of column selections

columnMargin

protected int columnMargin
Width margin between each column

listenerList

protected EventListenerList listenerList
List of TableColumnModelListener

changeEvent

protected transient ChangeEvent changeEvent
Change event (only one needed)

columnSelectionAllowed

protected boolean columnSelectionAllowed
Column selection allowed in this column model

totalColumnWidth

protected int totalColumnWidth
A local cache of the combined width of all columns

Constructor Detail

DefaultTableColumnModel

public DefaultTableColumnModel()
Creates a default table column model.

Method Detail

addColumn

public void addColumn(TableColumn aColumn)
Appends aColumn to the end of the tableColumns array. This method also posts the columnAdded event to its listeners.

Specified by:
addColumn in interface TableColumnModel
Parameters:
aColumn - the TableColumn to be added
Throws:
IllegalArgumentException - if aColumn is null
See Also:
removeColumn(javax.swing.table.TableColumn)

removeColumn

public void removeColumn(TableColumn column)
Deletes the column from the tableColumns array. This method will do nothing if column is not in the table's columns list. tile is called to resize both the header and table views. This method also posts a columnRemoved event to its listeners.

Specified by:
removeColumn in interface TableColumnModel
Parameters:
column - the TableColumn to be removed
See Also:
addColumn(javax.swing.table.TableColumn)

moveColumn

public void moveColumn(int columnIndex,
                       int newIndex)
Moves the column and heading at columnIndex to newIndex. The old column at columnIndex will now be found at newIndex. The column that used to be at newIndex is shifted left or right to make room. This will not move any columns if columnIndex equals newIndex. This method also posts a columnMoved event to its listeners.

Specified by:
moveColumn in interface TableColumnModel
Parameters:
columnIndex - the index of column to be moved
newIndex - new index to move the column
Throws:
IllegalArgumentException - if column or newIndex are not in the valid range

setColumnMargin

public void setColumnMargin(int newMargin)
Sets the column margin to newMargin. This method also posts a columnMarginChanged event to its listeners.

Specified by:
setColumnMargin in interface TableColumnModel
Parameters:
newMargin - the new margin width, in pixels
See Also:
getColumnMargin(), getTotalColumnWidth()

getColumnCount

public int getColumnCount()
Returns the number of columns in the tableColumns array.

Specified by:
getColumnCount in interface TableColumnModel
Returns:
the number of columns in the tableColumns array
See Also:
getColumns()

getColumns

public Enumeration<TableColumn> getColumns()
Returns an Enumeration of all the columns in the model.

Specified by:
getColumns in interface TableColumnModel
Returns:
an Enumeration of the columns in the model

getColumnIndex

public int getColumnIndex(Object identifier)
Returns the index of the first column in the tableColumns array whose identifier is equal to identifier, when compared using equals.

Specified by:
getColumnIndex in interface TableColumnModel
Parameters:
identifier - the identifier object
Returns:
the index of the first column in the tableColumns array whose identifier is equal to identifier
Throws:
IllegalArgumentException - if identifier is null, or if no TableColumn has this identifier
See Also:
getColumn(int)

getColumn

public TableColumn getColumn(int columnIndex)
Returns the TableColumn object for the column at columnIndex.

Specified by:
getColumn in interface TableColumnModel
Parameters:
columnIndex - the index of the column desired
Returns:
the TableColumn object for the column at columnIndex

getColumnMargin

public int getColumnMargin()
Returns the width margin for TableColumn. The default columnMargin is 1.

Specified by:
getColumnMargin in interface TableColumnModel
Returns:
the maximum width for the TableColumn
See Also:
setColumnMargin(int)

getColumnIndexAtX

public int getColumnIndexAtX(int x)
Returns the index of the column that lies at position x, or -1 if no column covers this point. In keeping with Swing's separable model architecture, a TableColumnModel does not know how the table columns actually appear on screen. The visual presentation of the columns is the responsibility of the view/controller object using this model (typically JTable). The view/controller need not display the columns sequentially from left to right. For example, columns could be displayed from right to left to accomodate a locale preference or some columns might be hidden at the request of the user. Because the model does not know how the columns are laid out on screen, the given xPosition should not be considered to be a coordinate in 2D graphics space. Instead, it should be considered to be a width from the start of the first column in the model. If the column index for a given X coordinate in 2D space is required, JTable.columnAtPoint can be used instead.

Specified by:
getColumnIndexAtX in interface TableColumnModel
Parameters:
x - the horizontal location of interest
Returns:
the index of the column or -1 if no column is found
See Also:
JTable.columnAtPoint(java.awt.Point)

getTotalColumnWidth

public int getTotalColumnWidth()
Returns the total combined width of all columns.

Specified by:
getTotalColumnWidth in interface TableColumnModel
Returns:
the totalColumnWidth property

setSelectionModel

public void setSelectionModel(ListSelectionModel newModel)
Sets the selection model for this TableColumnModel to newModel and registers for listener notifications from the new selection model. If newModel is null, an exception is thrown.

Specified by:
setSelectionModel in interface TableColumnModel
Parameters:
newModel - the new selection model
Throws:
IllegalArgumentException - if newModel is null
See Also:
getSelectionModel()

getSelectionModel

public ListSelectionModel getSelectionModel()
Returns the ListSelectionModel that is used to maintain column selection state.

Specified by:
getSelectionModel in interface TableColumnModel
Returns:
the object that provides column selection state. Or null if row selection is not allowed.
See Also:
setSelectionModel(javax.swing.ListSelectionModel)

setColumnSelectionAllowed

public void setColumnSelectionAllowed(boolean flag)
Sets whether column selection is allowed. The default is false.

Specified by:
setColumnSelectionAllowed in interface TableColumnModel
Parameters:
flag - true if column selection will be allowed, false otherwise
See Also:
TableColumnModel.getColumnSelectionAllowed()

getColumnSelectionAllowed

public boolean getColumnSelectionAllowed()
Returns true if column selection is allowed, otherwise false. The default is false.

Specified by:
getColumnSelectionAllowed in interface TableColumnModel
Returns:
the columnSelectionAllowed property
See Also:
TableColumnModel.setColumnSelectionAllowed(boolean)

getSelectedColumns

public int[] getSelectedColumns()
Returns an array of selected columns. If selectionModel is null, returns an empty array.

Specified by:
getSelectedColumns in interface TableColumnModel
Returns:
an array of selected columns or an empty array if nothing is selected or the selectionModel is null

getSelectedColumnCount

public int getSelectedColumnCount()
Returns the number of columns selected.

Specified by:
getSelectedColumnCount in interface TableColumnModel
Returns:
the number of columns selected

addColumnModelListener

public void addColumnModelListener(TableColumnModelListener x)
Adds a listener for table column model events.

Specified by:
addColumnModelListener in interface TableColumnModel
Parameters:
x - a TableColumnModelListener object

removeColumnModelListener

public void removeColumnModelListener(TableColumnModelListener x)
Removes a listener for table column model events.

Specified by:
removeColumnModelListener in interface TableColumnModel
Parameters:
x - a TableColumnModelListener object

getColumnModelListeners

public TableColumnModelListener[] getColumnModelListeners()
Returns an array of all the column model listeners registered on this model.

Returns:
all of this default table column model's ColumnModelListeners or an empty array if no column model listeners are currently registered
Since:
1.4
See Also:
addColumnModelListener(javax.swing.event.TableColumnModelListener), removeColumnModelListener(javax.swing.event.TableColumnModelListener)

fireColumnAdded

protected void fireColumnAdded(TableColumnModelEvent e)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

Parameters:
e - the event received
See Also:
EventListenerList

fireColumnRemoved

protected void fireColumnRemoved(TableColumnModelEvent e)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

Parameters:
e - the event received
See Also:
EventListenerList

fireColumnMoved

protected void fireColumnMoved(TableColumnModelEvent e)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

Parameters:
e - the event received
See Also:
EventListenerList

fireColumnSelectionChanged

protected void fireColumnSelectionChanged(ListSelectionEvent e)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

Parameters:
e - the event received
See Also:
EventListenerList

fireColumnMarginChanged

protected void fireColumnMarginChanged()
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

See Also:
EventListenerList

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this model. FooListeners are registered using the addFooListener method.

You can specify the listenerType argument with a class literal, such as FooListener.class. For example, you can query a DefaultTableColumnModel m for its column model listeners with the following code:

ColumnModelListener[] cmls = (ColumnModelListener[])(m.getListeners(ColumnModelListener.class));
If no such listeners exist, this method returns an empty array.

Parameters:
listenerType - the type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener
Returns:
an array of all objects registered as FooListeners on this model, or an empty array if no such listeners have been added
Throws:
ClassCastException - if listenerType doesn't specify a class or interface that implements java.util.EventListener
Since:
1.3
See Also:
getColumnModelListeners()

propertyChange

public void propertyChange(PropertyChangeEvent evt)
Property Change Listener change method. Used to track changes to the column width or preferred column width.

Specified by:
propertyChange in interface PropertyChangeListener
Parameters:
evt - PropertyChangeEvent

valueChanged

public void valueChanged(ListSelectionEvent e)
A ListSelectionListener that forwards ListSelectionEvents when there is a column selection change.

Specified by:
valueChanged in interface ListSelectionListener
Parameters:
e - the change event

createSelectionModel

protected ListSelectionModel createSelectionModel()
Creates a new default list selection model.

recalcWidthCache

protected void recalcWidthCache()
Recalculates the total combined width of all columns. Updates the totalColumnWidth property.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultTableModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.table
Class DefaultTableModel

java.lang.Object
    extended by  javax.swing.table.AbstractTableModel
        extended by  javax.swing.table.DefaultTableModel
All Implemented Interfaces:
Serializable, TableModel
public class DefaultTableModel
extends AbstractTableModel
implements Serializable

This is an implementation of TableModel that uses a Vector of Vectors to store the cell value objects.

Warning: DefaultTableModel returns a column class of Object. When DefaultTableModel is used with a TableRowSorter this will result in extensive use of toString, which for non-String data types is expensive. If you use DefaultTableModel with a TableRowSorter you are strongly encouraged to override getColumnClass to return the appropriate type.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
TableModel, getDataVector()

Field Summary
protected Vector | columnIdentifiers The Vector of column identifiers.
protected Vector | dataVector The Vector of Vectors of Object values.
Fields inherited from class javax.swing.table.AbstractTableModel
listenerList
Constructor Summary
DefaultTableModel()
Constructs a default DefaultTableModel which is a table of zero columns and zero rows.
DefaultTableModel(int rowCount, int columnCount)
Constructs a DefaultTableModel with rowCount and columnCount of null object values.
DefaultTableModel(Object[][] data, Object[] columnNames)
Constructs a DefaultTableModel and initializes the table by passing data and columnNames to the setDataVector method.
DefaultTableModel(Object[] columnNames, int rowCount)
Constructs a DefaultTableModel with as many columns as there are elements in columnNames and rowCount of null object values.
DefaultTableModel(Vector columnNames, int rowCount)
Constructs a DefaultTableModel with as many columns as there are elements in columnNames and rowCount of null object values.
DefaultTableModel(Vector data, Vector columnNames)
Constructs a DefaultTableModel and initializes the table by passing data and columnNames to the setDataVector method.
Method Summary
void | addColumn(Object columnName) Adds a column to the model.
void | addColumn(Object columnName, Object[] columnData) Adds a column to the model.
void | addColumn(Object columnName, Vector columnData) Adds a column to the model.
void | addRow(Object[] rowData) Adds a row to the end of the model.
void | addRow(Vector rowData) Adds a row to the end of the model.
protected static Vector | convertToVector(Object[] anArray) Returns a vector that contains the same objects as the array.
protected static Vector | convertToVector(Object[][] anArray) Returns a vector of vectors that contains the same objects as the array.
int | getColumnCount() Returns the number of columns in this data table.
String | getColumnName(int column) Returns the column name.
Vector | getDataVector() Returns the Vector of Vectors that contains the table's data values.
int | getRowCount() Returns the number of rows in this data table.
Object | getValueAt(int row, int column) Returns an attribute value for the cell at row and column.
void | insertRow(int row, Object[] rowData) Inserts a row at row in the model.
void | insertRow(int row, Vector rowData) Inserts a row at row in the model.
boolean | isCellEditable(int row, int column) Returns true regardless of parameter values.
void | moveRow(int start, int end, int to) Moves one or more rows from the inclusive range start to end to the to position in the model.
void | newDataAvailable(TableModelEvent event) Equivalent to fireTableChanged.
void | newRowsAdded(TableModelEvent e) Ensures that the new rows have the correct number of columns.
void | removeRow(int row) Removes the row at row from the model.
void | rowsRemoved(TableModelEvent event) Equivalent to fireTableChanged.
void | setColumnCount(int columnCount) Sets the number of columns in the model.
void | setColumnIdentifiers(Object[] newIdentifiers) Replaces the column identifiers in the model.
void | setColumnIdentifiers(Vector columnIdentifiers) Replaces the column identifiers in the model.
void | setDataVector(Object[][] dataVector, Object[] columnIdentifiers) Replaces the value in the dataVector instance variable with the values in the array dataVector.
void | setDataVector(Vector dataVector, Vector columnIdentifiers) Replaces the current dataVector instance variable with the new Vector of rows, dataVector.
void | setNumRows(int rowCount) Obsolete as of Java 2 platform v1.3.
void | setRowCount(int rowCount) Sets the number of rows in the model.
void | setValueAt(Object aValue, int row, int column) Sets the object value for the cell at column and row.
Methods inherited from class javax.swing.table.AbstractTableModel
addTableModelListener, findColumn, fireTableCellUpdated, fireTableChanged, fireTableDataChanged, fireTableRowsDeleted, fireTableRowsInserted, fireTableRowsUpdated, fireTableStructureChanged, getColumnClass, getListeners, getTableModelListeners, removeTableModelListener
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

dataVector

protected Vector dataVector
The Vector of Vectors of Object values.

columnIdentifiers

protected Vector columnIdentifiers
The Vector of column identifiers.

Constructor Detail

DefaultTableModel

public DefaultTableModel()
Constructs a default DefaultTableModel which is a table of zero columns and zero rows.

DefaultTableModel

public DefaultTableModel(int rowCount,
                         int columnCount)
Constructs a DefaultTableModel with rowCount and columnCount of null object values.

Parameters:
rowCount - the number of rows the table holds
columnCount - the number of columns the table holds
See Also:
setValueAt(java.lang.Object, int, int)

DefaultTableModel

public DefaultTableModel(Vector columnNames,
                         int rowCount)
Constructs a DefaultTableModel with as many columns as there are elements in columnNames and rowCount of null object values. Each column's name will be taken from the columnNames vector.

Parameters:
columnNames - vector containing the names of the new columns; if this is null then the model has no columns
rowCount - the number of rows the table holds
See Also:
setDataVector(java.util.Vector, java.util.Vector), setValueAt(java.lang.Object, int, int)

DefaultTableModel

public DefaultTableModel(Object[] columnNames,
                         int rowCount)
Constructs a DefaultTableModel with as many columns as there are elements in columnNames and rowCount of null object values. Each column's name will be taken from the columnNames array.

Parameters:
columnNames - array containing the names of the new columns; if this is null then the model has no columns
rowCount - the number of rows the table holds
See Also:
setDataVector(java.util.Vector, java.util.Vector), setValueAt(java.lang.Object, int, int)

DefaultTableModel

public DefaultTableModel(Vector data,
                         Vector columnNames)
Constructs a DefaultTableModel and initializes the table by passing data and columnNames to the setDataVector method.

Parameters:
data - the data of the table, a Vector of Vectors of Object values
columnNames - vector containing the names of the new columns
See Also:
getDataVector(), setDataVector(java.util.Vector, java.util.Vector)

DefaultTableModel

public DefaultTableModel(Object[][] data,
                         Object[] columnNames)
Constructs a DefaultTableModel and initializes the table by passing data and columnNames to the setDataVector method. The first index in the Object[][] array is the row index and the second is the column index.

Parameters:
data - the data of the table
columnNames - the names of the columns
See Also:
getDataVector(), setDataVector(java.util.Vector, java.util.Vector)
Method Detail

getDataVector

public Vector getDataVector()
Returns the Vector of Vectors that contains the table's data values. The vectors contained in the outer vector are each a single row of values. In other words, to get to the cell at row 1, column 5:

((Vector)getDataVector().elementAt(1)).elementAt(5);

Returns:
the vector of vectors containing the tables data values
See Also:
newDataAvailable(javax.swing.event.TableModelEvent),
newRowsAdded(javax.swing.event.TableModelEvent),
setDataVector(java.util.Vector, java.util.Vector)

setDataVector

public void setDataVector(Vector dataVector,
                          Vector columnIdentifiers)
Replaces the current dataVector instance variable with the new Vector of rows, dataVector. Each row is represented in dataVector as a Vector of Object values. columnIdentifiers are the names of the new columns. The first name in columnIdentifiers is mapped to column 0 in dataVector. Each row in dataVector is adjusted to match the number of columns in columnIdentifiers either by truncating the Vector if it is too long, or adding null values if it is too short.

Note that passing in a null value for dataVector results in unspecified behavior, an possibly an exception.

Parameters:
dataVector - the new data vector
columnIdentifiers - the names of the columns
See Also:
getDataVector()

setDataVector

public void setDataVector(Object[][] dataVector,
                          Object[] columnIdentifiers)
Replaces the value in the dataVector instance variable with the values in the array dataVector. The first index in the Object[][] array is the row index and the second is the column index. columnIdentifiers are the names of the new columns.

Parameters:
dataVector - the new data vector
columnIdentifiers - the names of the columns
See Also:
setDataVector(Vector, Vector)

newDataAvailable

public void newDataAvailable(TableModelEvent event)
Equivalent to fireTableChanged.

Parameters:
event - the change event

newRowsAdded

public void newRowsAdded(TableModelEvent e)
Ensures that the new rows have the correct number of columns. This is accomplished by using the setSize method in Vector which truncates vectors which are too long, and appends nulls if they are too short. This method also sends out a tableChanged notification message to all the listeners.

Parameters:
e - this TableModelEvent describes where the rows were added. If null it assumes all the rows were newly added
See Also:
getDataVector()

rowsRemoved

public void rowsRemoved(TableModelEvent event)
Equivalent to fireTableChanged.

Parameters:
event - the change event

setNumRows

public void setNumRows(int rowCount)
Obsolete as of Java 2 platform v1.3. Please use setRowCount instead.

setRowCount

public void setRowCount(int rowCount)
Sets the number of rows in the model. If the new size is greater than the current size, new rows are added to the end of the model If the new size is less than the current size, all rows at index rowCount and greater are discarded.

Since:
1.3
See Also:
setColumnCount(int)

addRow

public void addRow(Vector rowData)
Adds a row to the end of the model. The new row will contain null values unless rowData is specified. Notification of the row being added will be generated.

Parameters:
rowData - optional data of the row being added

addRow

public void addRow(Object[] rowData)
Adds a row to the end of the model. The new row will contain null values unless rowData is specified. Notification of the row being added will be generated.

Parameters:
rowData - optional data of the row being added

insertRow

public void insertRow(int row,
                      Vector rowData)
Inserts a row at row in the model. The new row will contain null values unless rowData is specified. Notification of the row being added will be generated.

Parameters:
row - the row index of the row to be inserted
rowData - optional data of the row being added
Throws:
ArrayIndexOutOfBoundsException - if the row was invalid

insertRow

public void insertRow(int row,
                      Object[] rowData)
Inserts a row at row in the model. The new row will contain null values unless rowData is specified. Notification of the row being added will be generated.

Parameters:
row - the row index of the row to be inserted
rowData - optional data of the row being added
Throws:
ArrayIndexOutOfBoundsException - if the row was invalid

moveRow

public void moveRow(int start,
                    int end,
                    int to)
Moves one or more rows from the inclusive range start to end to the to position in the model. After the move, the row that was at index start will be at index to. This method will send a tableChanged notification message to all the listeners.

  Examples of moves:

  1. moveRow(1,3,5);
          a|B|C|D|e|f|g|h|i|j|k   - before
          a|e|f|g|h|B|C|D|i|j|k   - after

  2. moveRow(6,7,1);
          a|b|c|d|e|f|G|H|i|j|k   - before
          a|G|H|b|c|d|e|f|i|j|k   - after

Parameters:
start - the starting row index to be moved
end - the ending row index to be moved
to - the destination of the rows to be moved
Throws:
ArrayIndexOutOfBoundsException - if any of the elements would be moved out of the table's range

removeRow

public void removeRow(int row)
Removes the row at row from the model. Notification of the row being removed will be sent to all the listeners.

Parameters:
row - the row index of the row to be removed
Throws:
ArrayIndexOutOfBoundsException - if the row was invalid

setColumnIdentifiers

public void setColumnIdentifiers(Vector columnIdentifiers)
Replaces the column identifiers in the model. If the number of newIdentifiers is greater than the current number of columns, new columns are added to the end of each row in the model. If the number of newIdentifiers is less than the current number of columns, all the extra columns at the end of a row are discarded.

Parameters:
columnIdentifiers - vector of column identifiers. If null, set the model to zero columns
See Also:
setNumRows(int)

setColumnIdentifiers

public void setColumnIdentifiers(Object[] newIdentifiers)
Replaces the column identifiers in the model. If the number of newIdentifiers is greater than the current number of columns, new columns are added to the end of each row in the model. If the number of newIdentifiers is less than the current number of columns, all the extra columns at the end of a row are discarded.

Parameters:
newIdentifiers - array of column identifiers. If null, set the model to zero columns
See Also:
setNumRows(int)

setColumnCount

public void setColumnCount(int columnCount)
Sets the number of columns in the model. If the new size is greater than the current size, new columns are added to the end of the model with null cell values. If the new size is less than the current size, all columns at index columnCount and greater are discarded.

Parameters:
columnCount - the new number of columns in the model
Since:
1.3
See Also:
setColumnCount(int)

addColumn

public void addColumn(Object columnName)
Adds a column to the model. The new column will have the identifier columnName, which may be null. This method will send a tableChanged notification message to all the listeners. This method is a cover for addColumn(Object, Vector) which uses null as the data vector.

Parameters:
columnName - the identifier of the column being added

addColumn

public void addColumn(Object columnName,
                      Vector columnData)
Adds a column to the model. The new column will have the identifier columnName, which may be null. columnData is the optional vector of data for the column. If it is null the column is filled with null values. Otherwise, the new data will be added to model starting with the first element going to row 0, etc. This method will send a tableChanged notification message to all the listeners.

Parameters:
columnName - the identifier of the column being added
columnData - optional data of the column being added

addColumn

public void addColumn(Object columnName,
                      Object[] columnData)
Adds a column to the model. The new column will have the identifier columnName. columnData is the optional array of data for the column. If it is null the column is filled with null values. Otherwise, the new data will be added to model starting with the first element going to row 0, etc. This method will send a tableChanged notification message to all the listeners.

See Also:
addColumn(Object, Vector)

getRowCount

public int getRowCount()
Returns the number of rows in this data table.

Specified by:
getRowCount in interface TableModel
Returns:
the number of rows in the model
See Also:
TableModel.getColumnCount()

getColumnCount

public int getColumnCount()
Returns the number of columns in this data table.

Specified by:
getColumnCount in interface TableModel
Returns:
the number of columns in the model
See Also:
TableModel.getRowCount()

getColumnName

public String getColumnName(int column)
Returns the column name.

Specified by:
getColumnName in interface TableModel
Overrides:
getColumnName in class AbstractTableModel
Parameters:
column - the column being queried
Returns:
a name for this column using the string value of the appropriate member in columnIdentifiers. If columnIdentifiers does not have an entry for this index, returns the default name provided by the superclass.

isCellEditable

public boolean isCellEditable(int row,
                              int column)
Returns true regardless of parameter values.

Specified by:
isCellEditable in interface TableModel
Overrides:
isCellEditable in class AbstractTableModel
Parameters:
row - the row whose value is to be queried
column - the column whose value is to be queried
Returns:
true
See Also:
setValueAt(java.lang.Object, int, int)

getValueAt

public Object getValueAt(int row,
                         int column)
Returns an attribute value for the cell at row and column.

Specified by:
getValueAt in interface TableModel
Parameters:
row - the row whose value is to be queried
column - the column whose value is to be queried
Returns:
the value Object at the specified cell
Throws:
ArrayIndexOutOfBoundsException - if an invalid row or column was given

setValueAt

public void setValueAt(Object aValue,
                       int row,
                       int column)
Sets the object value for the cell at column and row. aValue is the new value. This method will generate a tableChanged notification.

Specified by:
setValueAt in interface TableModel
Overrides:
setValueAt in class AbstractTableModel
Parameters:
aValue - the new value; this can be null
row - the row whose value is to be changed
column - the column whose value is to be changed
Throws:
ArrayIndexOutOfBoundsException - if an invalid row or column was given
See Also:
TableModel.getValueAt(int, int), TableModel.isCellEditable(int, int)

convertToVector

protected static Vector convertToVector(Object[] anArray)
Returns a vector that contains the same objects as the array.

Parameters:
anArray - the array to be converted
Returns:
the new vector; if anArray is null, returns null

convertToVector

protected static Vector convertToVector(Object[][] anArray)
Returns a vector of vectors that contains the same objects as the array.

Parameters:
anArray - the double array to be converted
Returns:
the new vector of vectors; if anArray is null, returns null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTableHeader

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.table
Class JTableHeader

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.table.JTableHeader
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, EventListener, Accessible, TableColumnModelListener
public class JTableHeader
extends JComponent
implements TableColumnModelListener, Accessible

This is the object which manages the header of the JTable.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JTable

Nested Class Summary
protected  class JTableHeader.AccessibleJTableHeader
This class implements accessibility support for the JTableHeader class.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected TableColumnModel | columnModel The TableColumnModel of the table header.
protected TableColumn | draggedColumn The index of the column being dragged.
protected int | draggedDistance The distance from its original position the column has been dragged.
protected boolean | reorderingAllowed If true, reordering of columns are allowed by the user; the default is true.
protected boolean | resizingAllowed If true, resizing of columns are allowed by the user; the default is true.
protected TableColumn | resizingColumn The index of the column being resized.
protected JTable | table The table for which this object is the header; the default is null.
protected boolean | updateTableInRealTime Obsolete as of Java 2 platform v1.3.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JTableHeader()
Constructs a JTableHeader with a default TableColumnModel.
JTableHeader(TableColumnModel cm)
Constructs a JTableHeader which is initialized with cm as the column model.
Method Summary
void | columnAdded(TableColumnModelEvent e) Invoked when a column is added to the table column model.
int | columnAtPoint(Point point) Returns the index of the column that point lies in, or -1 if it lies out of bounds.
void | columnMarginChanged(ChangeEvent e) Invoked when a column is moved due to a margin change.
void | columnMoved(TableColumnModelEvent e) Invoked when a column is repositioned.
void | columnRemoved(TableColumnModelEvent e) Invoked when a column is removed from the table column model.
void | columnSelectionChanged(ListSelectionEvent e) Invoked when the selection model of the TableColumnModel is changed.
protected TableColumnModel | createDefaultColumnModel() Returns the default column model object which is a DefaultTableColumnModel.
protected TableCellRenderer | createDefaultRenderer() Returns a default renderer to be used when no header renderer is defined by a TableColumn.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JTableHeader.
TableColumnModel | getColumnModel() Returns the TableColumnModel that contains all column information of this table header.
TableCellRenderer | getDefaultRenderer() Returns the default renderer used when no headerRenderer is defined by a TableColumn.
TableColumn | getDraggedColumn() Returns the the dragged column, if and only if, a drag is in process, otherwise returns null.
int | getDraggedDistance() Returns the column's horizontal distance from its original position, if and only if, a drag is in process.
Rectangle | getHeaderRect(int column) Returns the rectangle containing the header tile at column.
boolean | getReorderingAllowed() Returns true if the user is allowed to rearrange columns by dragging their headers, false otherwise.
boolean | getResizingAllowed() Returns true if the user is allowed to resize columns by dragging between their headers, false otherwise.
TableColumn | getResizingColumn() Returns the resizing column.
JTable | getTable() Returns the table associated with this header.
String | getToolTipText(MouseEvent event) Allows the renderer's tips to be used if there is text set.
TableHeaderUI | getUI() Returns the look and feel (L&F) object that renders this component.
String | getUIClassID() Returns the suffix used to construct the name of the look and feel (L&F) class used to render this component.
boolean | getUpdateTableInRealTime() Obsolete as of Java 2 platform v1.3.
protected void | initializeLocalVars() Initializes the local variables and properties with default values.
protected String | paramString() Returns a string representation of this JTableHeader.
void | resizeAndRepaint() Sizes the header and marks it as needing display.
void | setColumnModel(TableColumnModel columnModel) Sets the column model for this table to newModel and registers for listener notifications from the new column model.
void | setDefaultRenderer(TableCellRenderer defaultRenderer) Sets the default renderer to be used when no headerRenderer is defined by a TableColumn.
void | setDraggedColumn(TableColumn aColumn) Sets the header's draggedColumn to aColumn.
void | setDraggedDistance(int distance) Sets the header's draggedDistance to distance.
void | setReorderingAllowed(boolean reorderingAllowed) Sets whether the user can drag column headers to reorder columns.
void | setResizingAllowed(boolean resizingAllowed) Sets whether the user can resize columns by dragging between headers.
void | setResizingColumn(TableColumn aColumn) Sets the header's resizingColumn to aColumn.
void | setTable(JTable table) Sets the table associated with this header.
void | setUI(TableHeaderUI ui) Sets the look and feel (L&F) object that renders this component.
void | setUpdateTableInRealTime(boolean flag) Obsolete as of Java 2 platform v1.3.
void | updateUI() Notification from the UIManager that the look and feel (L&F) has changed.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

table

protected JTable table
The table for which this object is the header; the default is null.

columnModel

protected TableColumnModel columnModel
The TableColumnModel of the table header.

reorderingAllowed

protected boolean reorderingAllowed
If true, reordering of columns are allowed by the user; the default is true.

resizingAllowed

protected boolean resizingAllowed
If true, resizing of columns are allowed by the user; the default is true.

updateTableInRealTime

protected boolean updateTableInRealTime
Obsolete as of Java 2 platform v1.3. Real time repaints, in response to column dragging or resizing, are now unconditional.

resizingColumn

protected transient TableColumn resizingColumn
The index of the column being resized. null if not resizing.

draggedColumn

protected transient TableColumn draggedColumn
The index of the column being dragged. null if not dragging.

draggedDistance

protected transient int draggedDistance
The distance from its original position the column has been dragged.

Constructor Detail

JTableHeader

public JTableHeader()
Constructs a JTableHeader with a default TableColumnModel.

See Also:
createDefaultColumnModel()

JTableHeader

public JTableHeader(TableColumnModel cm)
Constructs a JTableHeader which is initialized with cm as the column model. If cm is null this method will initialize the table header with a default TableColumnModel.

Parameters:
cm - the column model for the table
See Also:
createDefaultColumnModel()
Method Detail

setTable

public void setTable(JTable table)
Sets the table associated with this header.

Parameters:
table - the new table

getTable

public JTable getTable()
Returns the table associated with this header.

Returns:
the table property

setReorderingAllowed

public void setReorderingAllowed(boolean reorderingAllowed)
Sets whether the user can drag column headers to reorder columns.

Parameters:
reorderingAllowed - true if the table view should allow reordering; otherwise false
See Also:
getReorderingAllowed()

getReorderingAllowed

public boolean getReorderingAllowed()
Returns true if the user is allowed to rearrange columns by dragging their headers, false otherwise. The default is true. You can rearrange columns programmatically regardless of this setting.

Returns:
the reorderingAllowed property
See Also:
setReorderingAllowed(boolean)

setResizingAllowed

public void setResizingAllowed(boolean resizingAllowed)
Sets whether the user can resize columns by dragging between headers.

Parameters:
resizingAllowed - true if table view should allow resizing
See Also:
getResizingAllowed()

getResizingAllowed

public boolean getResizingAllowed()
Returns true if the user is allowed to resize columns by dragging between their headers, false otherwise. The default is true. You can resize columns programmatically regardless of this setting.

Returns:
the resizingAllowed property
See Also:
setResizingAllowed(boolean)

getDraggedColumn

public TableColumn getDraggedColumn()
Returns the the dragged column, if and only if, a drag is in process, otherwise returns null.

Returns:
the dragged column, if a drag is in process, otherwise returns null
See Also:
getDraggedDistance()

getDraggedDistance

public int getDraggedDistance()
Returns the column's horizontal distance from its original position, if and only if, a drag is in process. Otherwise, the the return value is meaningless.

Returns:
the column's horizontal distance from its original position, if a drag is in process, otherwise the return value is meaningless
See Also:
getDraggedColumn()

getResizingColumn

public TableColumn getResizingColumn()
Returns the resizing column. If no column is being resized this method returns null.

Returns:
the resizing column, if a resize is in process, otherwise returns null

setUpdateTableInRealTime

public void setUpdateTableInRealTime(boolean flag)
Obsolete as of Java 2 platform v1.3. Real time repaints, in response to column dragging or resizing, are now unconditional.

getUpdateTableInRealTime

public boolean getUpdateTableInRealTime()
Obsolete as of Java 2 platform v1.3. Real time repaints, in response to column dragging or resizing, are now unconditional.

setDefaultRenderer

public void setDefaultRenderer(TableCellRenderer defaultRenderer)
Sets the default renderer to be used when no headerRenderer is defined by a TableColumn.

Parameters:
defaultRenderer - the default renderer
Since:
1.3

getDefaultRenderer

public TableCellRenderer getDefaultRenderer()
Returns the default renderer used when no headerRenderer is defined by a TableColumn.

Returns:
the default renderer
Since:
1.3

columnAtPoint

public int columnAtPoint(Point point)
Returns the index of the column that point lies in, or -1 if it lies out of bounds.

Returns:
the index of the column that point lies in, or -1 if it lies out of bounds

getHeaderRect

public Rectangle getHeaderRect(int column)
Returns the rectangle containing the header tile at column. When the column parameter is out of bounds this method uses the same conventions as the JTable method getCellRect.

Returns:
the rectangle containing the header tile at column
See Also:
JTable.getCellRect(int, int, boolean)

getToolTipText

public String getToolTipText(MouseEvent event)
Allows the renderer's tips to be used if there is text set.

Overrides:
getToolTipText in class JComponent
Parameters:
event - the location of the event identifies the proper renderer and, therefore, the proper tip
Returns:
the tool tip for this component

getUI

public TableHeaderUI getUI()
Returns the look and feel (L&F) object that renders this component.

Returns:
the TableHeaderUI object that renders this component

setUI

public void setUI(TableHeaderUI ui)
Sets the look and feel (L&F) object that renders this component.

Parameters:
ui - the TableHeaderUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Notification from the UIManager that the look and feel (L&F) has changed. Replaces the current UI object with the latest version from the UIManager.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

getUIClassID

public String getUIClassID()
Returns the suffix used to construct the name of the look and feel (L&F) class used to render this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string "TableHeaderUI"
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

setColumnModel

public void setColumnModel(TableColumnModel columnModel)
Sets the column model for this table to newModel and registers for listener notifications from the new column model.

Parameters:
columnModel - the new data source for this table
Throws:
IllegalArgumentException - if newModel is null
See Also:
getColumnModel()

getColumnModel

public TableColumnModel getColumnModel()
Returns the TableColumnModel that contains all column information of this table header.

Returns:
the columnModel property
See Also:
setColumnModel(javax.swing.table.TableColumnModel)

columnAdded

public void columnAdded(TableColumnModelEvent e)
Invoked when a column is added to the table column model.

Application code will not use these methods explicitly, they are used internally by JTable.

Specified by:
columnAdded in interface TableColumnModelListener
Parameters:
e - the event received
See Also:
TableColumnModelListener

columnRemoved

public void columnRemoved(TableColumnModelEvent e)
Invoked when a column is removed from the table column model.

Application code will not use these methods explicitly, they are used internally by JTable.

Specified by:
columnRemoved in interface TableColumnModelListener
Parameters:
e - the event received
See Also:
TableColumnModelListener

columnMoved

public void columnMoved(TableColumnModelEvent e)
Invoked when a column is repositioned.

Application code will not use these methods explicitly, they are used internally by JTable.

Specified by:
columnMoved in interface TableColumnModelListener
Parameters:
e - the event received
See Also:
TableColumnModelListener

columnMarginChanged

public void columnMarginChanged(ChangeEvent e)
Invoked when a column is moved due to a margin change.

Application code will not use these methods explicitly, they are used internally by JTable.

Specified by:
columnMarginChanged in interface TableColumnModelListener
Parameters:
e - the event received
See Also:
TableColumnModelListener

columnSelectionChanged

public void columnSelectionChanged(ListSelectionEvent e)
Invoked when the selection model of the TableColumnModel is changed. This method currently has no effect (the header is not redrawn).

Application code will not use these methods explicitly, they are used internally by JTable.

Specified by:
columnSelectionChanged in interface TableColumnModelListener
Parameters:
e - the event received
See Also:
TableColumnModelListener

createDefaultColumnModel

protected TableColumnModel createDefaultColumnModel()
Returns the default column model object which is a DefaultTableColumnModel. A subclass can override this method to return a different column model object

Returns:
the default column model object

createDefaultRenderer

protected TableCellRenderer createDefaultRenderer()
Returns a default renderer to be used when no header renderer is defined by a TableColumn.

Returns:
the default table column renderer
Since:
1.3

initializeLocalVars

protected void initializeLocalVars()
Initializes the local variables and properties with default values. Used by the constructor methods.

resizeAndRepaint

public void resizeAndRepaint()
Sizes the header and marks it as needing display. Equivalent to revalidate followed by repaint.

setDraggedColumn

public void setDraggedColumn(TableColumn aColumn)
Sets the header's draggedColumn to aColumn.

Application code will not use this method explicitly, it is used internally by the column dragging mechanism.

Parameters:
aColumn - the column being dragged, or null if no column is being dragged

setDraggedDistance

public void setDraggedDistance(int distance)
Sets the header's draggedDistance to distance.

Parameters:
distance - the distance dragged

setResizingColumn

public void setResizingColumn(TableColumn aColumn)
Sets the header's resizingColumn to aColumn.

Application code will not use this method explicitly, it is used internally by the column sizing mechanism.

Parameters:
aColumn - the column being resized, or null if no column is being resized

paramString

protected String paramString()
Returns a string representation of this JTableHeader. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overriding paramString to provide information about the specific new aspects of the JFC components.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JTableHeader

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JTableHeader. For JTableHeaders, the AccessibleContext takes the form of an AccessibleJTableHeader. A new AccessibleJTableHeader instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJTableHeader that serves as the AccessibleContext of this JTableHeader
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTableHeader.AccessibleJTableHeader

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.table
Class JTableHeader.AccessibleJTableHeader

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.table.JTableHeader.AccessibleJTableHeader
All Implemented Interfaces:
Serializable, AccessibleComponent, AccessibleExtendedComponent
Enclosing class:
JTableHeader
protected class JTableHeader.AccessibleJTableHeader
extends JComponent.AccessibleJComponent

This class implements accessibility support for the JTableHeader class. It provides an implementation of the Java Accessibility API appropriate to table header user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class JTableHeader.AccessibleJTableHeader.AccessibleJTableHeaderEntry
This class provides an implementation of the Java Accessibility API appropropriate for JTableHeader entries.
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
protected JTableHeader.AccessibleJTableHeader()
Method Summary
Accessible | getAccessibleAt(Point p) Returns the Accessible child, if one exists, contained at the local coordinate Point.
Accessible | getAccessibleChild(int i) Return the nth Accessible child of the object.
int | getAccessibleChildrenCount() Returns the number of accessible children in the object.
AccessibleRole | getAccessibleRole() Get the role of this object.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getAccessibleStateSet, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleAction, getAccessibleEditableText, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleText, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JTableHeader.AccessibleJTableHeader

protected JTableHeader.AccessibleJTableHeader()
Method Detail

getAccessibleRole

public AccessibleRole getAccessibleRole()
Get the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleAt

public Accessible getAccessibleAt(Point p)
Returns the Accessible child, if one exists, contained at the local coordinate Point.

Specified by:
getAccessibleAt in interface AccessibleComponent
Overrides:
getAccessibleAt in class Container.AccessibleAWTContainer
Parameters:
p - The point defining the top-left corner of the Accessible, given in the coordinate space of the object's parent.
Returns:
the Accessible, if it exists, at the specified location; else null

getAccessibleChildrenCount

public int getAccessibleChildrenCount()
Returns the number of accessible children in the object. If all of the children of this object implement Accessible, than this method should return the number of children of this object.

Overrides:
getAccessibleChildrenCount in class JComponent.AccessibleJComponent
Returns:
the number of accessible children in the object.

getAccessibleChild

public Accessible getAccessibleChild(int i)
Return the nth Accessible child of the object.

Overrides:
getAccessibleChild in class JComponent.AccessibleJComponent
Parameters:
i - zero-based index of child
Returns:
the nth Accessible child of the object
See Also:
AccessibleContext.getAccessibleChildrenCount()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTableHeader.AccessibleJTableHeader.AccessibleJTableHeaderEntry

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.table
Class JTableHeader.AccessibleJTableHeader.AccessibleJTableHeaderEntry

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  javax.swing.table.JTableHeader.AccessibleJTableHeader.AccessibleJTableHeaderEntry
All Implemented Interfaces:
Accessible, AccessibleComponent
Enclosing class:
JTableHeader.AccessibleJTableHeader
protected class JTableHeader.AccessibleJTableHeader.AccessibleJTableHeaderEntry
extends AccessibleContext
implements Accessible, AccessibleComponent

This class provides an implementation of the Java Accessibility API appropropriate for JTableHeader entries.

Field Summary
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Constructor Summary
JTableHeader.AccessibleJTableHeader.AccessibleJTableHeaderEntry(int c, JTableHeader p, JTable t)
Constructs an AccessiblJTableHeaaderEntry
Method Summary
void | addFocusListener(FocusListener l) Adds the specified focus listener to receive focus events from this component.
void | addPropertyChangeListener(PropertyChangeListener l) Adds a PropertyChangeListener to the listener list.
boolean | contains(Point p) Checks whether the specified point is within this object's bounds, where the point's x and y coordinates are defined to be relative to the coordinate system of the object.
AccessibleAction | getAccessibleAction() Gets the AccessibleAction associated with this object that supports one or more actions.
Accessible | getAccessibleAt(Point p) Returns the Accessible child, if one exists, contained at the local coordinate Point.
Accessible | getAccessibleChild(int i) Returns the specified Accessible child of the object.
int | getAccessibleChildrenCount() Returns the number of accessible children of the object.
AccessibleComponent | getAccessibleComponent() Get the AccessibleComponent associated with this object.
AccessibleContext | getAccessibleContext() Get the AccessibleContext associated with this object.
String | getAccessibleDescription() Gets the accessibleDescription property of this object.
int | getAccessibleIndexInParent() Gets the 0-based index of this object in its accessible parent.
String | getAccessibleName() Gets the accessibleName property of this object.
AccessibleRole | getAccessibleRole() Gets the role of this object.
AccessibleSelection | getAccessibleSelection() Gets the AccessibleSelection associated with this object which allows its Accessible children to be selected.
AccessibleStateSet | getAccessibleStateSet() Gets the state set of this object.
AccessibleText | getAccessibleText() Gets the AccessibleText associated with this object presenting text on the display.
AccessibleValue | getAccessibleValue() Gets the AccessibleValue associated with this object that supports a Numerical value.
Color | getBackground() Gets the background color of this object.
Rectangle | getBounds() Gets the bounds of this object in the form of a Rectangle object.
Cursor | getCursor() Gets the Cursor of this object.
Font | getFont() Gets the Font of this object.
FontMetrics | getFontMetrics(Font f) Gets the FontMetrics of this object.
Color | getForeground() Gets the foreground color of this object.
Locale | getLocale() Gets the locale of the component.
Point | getLocation() Gets the location of the object relative to the parent in the form of a point specifying the object's top-left corner in the screen's coordinate space.
Point | getLocationOnScreen() Returns the location of the object on the screen.
Dimension | getSize() Returns the size of this object in the form of a Dimension object.
boolean | isEnabled() Determines if the object is enabled.
boolean | isFocusTraversable() Returns whether this object can accept focus or not.
boolean | isShowing() Determines if the object is showing.
boolean | isVisible() Determines if the object is visible.
void | removeFocusListener(FocusListener l) Removes the specified focus listener so it no longer receives focus events from this component.
void | removePropertyChangeListener(PropertyChangeListener l) Removes a PropertyChangeListener from the listener list.
void | requestFocus() Requests focus for this object.
void | setAccessibleDescription(String s) Sets the accessible description of this object.
void | setAccessibleName(String s) Sets the localized accessible name of this object.
void | setBackground(Color c) Sets the background color of this object.
void | setBounds(Rectangle r) Sets the bounds of this object in the form of a Rectangle object.
void | setCursor(Cursor c) Sets the Cursor of this object.
void | setEnabled(boolean b) Sets the enabled state of the object.
void | setFont(Font f) Sets the Font of this object.
void | setForeground(Color c) Sets the foreground color of this object.
void | setLocation(Point p) Sets the location of the object relative to the parent.
void | setSize(Dimension d) Resizes this object so that it has width and height.
void | setVisible(boolean b) Sets the visible state of the object.
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleEditableText, getAccessibleIcon, getAccessibleParent, getAccessibleRelationSet, getAccessibleTable, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JTableHeader.AccessibleJTableHeader.AccessibleJTableHeaderEntry

public JTableHeader.AccessibleJTableHeader.AccessibleJTableHeaderEntry(int c,
                                                                       JTableHeader p,
                                                                       JTable t)
Constructs an AccessiblJTableHeaaderEntry

Since:
1.4
Method Detail

getAccessibleContext

public AccessibleContext getAccessibleContext()
Get the AccessibleContext associated with this object. In the implementation of the Java Accessibility API for this class, returns this object, which serves as its own AccessibleContext.

Specified by:
getAccessibleContext in interface Accessible
Returns:
this object

getAccessibleName

public String getAccessibleName()
Description copied from class: AccessibleContext
Gets the accessibleName property of this object. The accessibleName property of an object is a localized String that designates the purpose of the object. For example, the accessibleName property of a label or button might be the text of the label or button itself. In the case of an object that doesn't display its name, the accessibleName should still be set. For example, in the case of a text field used to enter the name of a city, the accessibleName for the en_US locale could be 'city.'

Overrides:
getAccessibleName in class AccessibleContext
Returns:
the localized name of the object; null if this object does not have a name
See Also:
AccessibleContext.setAccessibleName(java.lang.String)

setAccessibleName

public void setAccessibleName(String s)
Description copied from class: AccessibleContext
Sets the localized accessible name of this object. Changing the name will cause a PropertyChangeEvent to be fired for the ACCESSIBLE_NAME_PROPERTY property.

Overrides:
setAccessibleName in class AccessibleContext
Parameters:
s - the new localized name of the object.
See Also:
AccessibleContext.getAccessibleName(), AccessibleContext.addPropertyChangeListener(java.beans.PropertyChangeListener)

getAccessibleDescription

public String getAccessibleDescription()
Description copied from class: AccessibleContext
Gets the accessibleDescription property of this object. The accessibleDescription property of this object is a short localized phrase describing the purpose of the object. For example, in the case of a 'Cancel' button, the accessibleDescription could be 'Ignore changes and close dialog box.'

Overrides:
getAccessibleDescription in class AccessibleContext
Returns:
the localized description of the object; null if this object does not have a description
See Also:
AccessibleContext.setAccessibleDescription(java.lang.String)

setAccessibleDescription

public void setAccessibleDescription(String s)
Description copied from class: AccessibleContext
Sets the accessible description of this object. Changing the name will cause a PropertyChangeEvent to be fired for the ACCESSIBLE_DESCRIPTION_PROPERTY property.

Overrides:
setAccessibleDescription in class AccessibleContext
Parameters:
s - the new localized description of the object
See Also:
AccessibleContext.setAccessibleName(java.lang.String), AccessibleContext.addPropertyChangeListener(java.beans.PropertyChangeListener)

getAccessibleRole

public AccessibleRole getAccessibleRole()
Description copied from class: AccessibleContext
Gets the role of this object. The role of the object is the generic purpose or use of the class of this object. For example, the role of a push button is AccessibleRole.PUSH_BUTTON. The roles in AccessibleRole are provided so component developers can pick from a set of predefined roles. This enables assistive technologies to provide a consistent interface to various tweaked subclasses of components (e.g., use AccessibleRole.PUSH_BUTTON for all components that act like a push button) as well as distinguish between sublasses that behave differently (e.g., AccessibleRole.CHECK_BOX for check boxes and AccessibleRole.RADIO_BUTTON for radio buttons).

Note that the AccessibleRole class is also extensible, so custom component developers can define their own AccessibleRole's if the set of predefined roles is inadequate.

Specified by:
getAccessibleRole in class AccessibleContext
Returns:
an instance of AccessibleRole describing the role of the object
See Also:
AccessibleRole

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Description copied from class: AccessibleContext
Gets the state set of this object. The AccessibleStateSet of an object is composed of a set of unique AccessibleStates. A change in the AccessibleStateSet of an object will cause a PropertyChangeEvent to be fired for the ACCESSIBLE_STATE_PROPERTY property.

Specified by:
getAccessibleStateSet in class AccessibleContext
Returns:
an instance of AccessibleStateSet containing the current state set of the object
See Also:
AccessibleStateSet, AccessibleState, AccessibleContext.addPropertyChangeListener(java.beans.PropertyChangeListener)

getAccessibleIndexInParent

public int getAccessibleIndexInParent()
Description copied from class: AccessibleContext
Gets the 0-based index of this object in its accessible parent.

Specified by:
getAccessibleIndexInParent in class AccessibleContext
Returns:
the 0-based index of this object in its parent; -1 if this object does not have an accessible parent.
See Also:
AccessibleContext.getAccessibleParent(),
AccessibleContext.getAccessibleChildrenCount(),
AccessibleContext.getAccessibleChild(int)

getAccessibleChildrenCount

public int getAccessibleChildrenCount()
Description copied from class: AccessibleContext
Returns the number of accessible children of the object.

Specified by:
getAccessibleChildrenCount in class AccessibleContext
Returns:
the number of accessible children of the object.

getAccessibleChild

public Accessible getAccessibleChild(int i)
Description copied from class: AccessibleContext
Returns the specified Accessible child of the object. The Accessible children of an Accessible object are zero-based, so the first child of an Accessible child is at index 0, the second child is at index 1, and so on.

Specified by:
getAccessibleChild in class AccessibleContext
Parameters:
i - zero-based index of child
Returns:
the Accessible child of the object
See Also:
AccessibleContext.getAccessibleChildrenCount()

getLocale

public Locale getLocale()
Description copied from class: AccessibleContext
Gets the locale of the component. If the component does not have a locale, then the locale of its parent is returned.

Specified by:
getLocale in class AccessibleContext
Returns:
this component's locale. If this component does not have a locale, the locale of its parent is returned.

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener l)
Description copied from class: AccessibleContext
Adds a PropertyChangeListener to the listener list. The listener is registered for all Accessible properties and will be called when those properties change.

Overrides:
addPropertyChangeListener in class AccessibleContext
Parameters:
l - The PropertyChangeListener to be added
See Also:
AccessibleContext.ACCESSIBLE_NAME_PROPERTY, AccessibleContext.ACCESSIBLE_DESCRIPTION_PROPERTY, AccessibleContext.ACCESSIBLE_STATE_PROPERTY, AccessibleContext.ACCESSIBLE_VALUE_PROPERTY, AccessibleContext.ACCESSIBLE_SELECTION_PROPERTY, AccessibleContext.ACCESSIBLE_TEXT_PROPERTY, AccessibleContext.ACCESSIBLE_VISIBLE_DATA_PROPERTY

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener l)
Description copied from class: AccessibleContext
Removes a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties.

Overrides:
removePropertyChangeListener in class AccessibleContext
Parameters:
l - The PropertyChangeListener to be removed

getAccessibleAction

public AccessibleAction getAccessibleAction()
Description copied from class: AccessibleContext
Gets the AccessibleAction associated with this object that supports one or more actions.

Overrides:
getAccessibleAction in class AccessibleContext
Returns:
AccessibleAction if supported by object; else return null
See Also:
AccessibleAction

getAccessibleComponent

public AccessibleComponent getAccessibleComponent()
Get the AccessibleComponent associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleComponent interface on behalf of itself.

Overrides:
getAccessibleComponent in class AccessibleContext
Returns:
this object
See Also:
AccessibleComponent

getAccessibleSelection

public AccessibleSelection getAccessibleSelection()
Description copied from class: AccessibleContext
Gets the AccessibleSelection associated with this object which allows its Accessible children to be selected.

Overrides:
getAccessibleSelection in class AccessibleContext
Returns:
AccessibleSelection if supported by object; else return null
See Also:
AccessibleSelection

getAccessibleText

public AccessibleText getAccessibleText()
Description copied from class: AccessibleContext
Gets the AccessibleText associated with this object presenting text on the display.

Overrides:
getAccessibleText in class AccessibleContext
Returns:
AccessibleText if supported by object; else return null
See Also:
AccessibleText

getAccessibleValue

public AccessibleValue getAccessibleValue()
Description copied from class: AccessibleContext
Gets the AccessibleValue associated with this object that supports a Numerical value.

Overrides:
getAccessibleValue in class AccessibleContext
Returns:
AccessibleValue if supported by object; else return null
See Also:
AccessibleValue

getBackground

public Color getBackground()
Description copied from interface: AccessibleComponent
Gets the background color of this object.

Specified by:
getBackground in interface AccessibleComponent
Returns:
the background color, if supported, of the object; otherwise, null
See Also:
AccessibleComponent.setBackground(java.awt.Color)

setBackground

public void setBackground(Color c)
Description copied from interface: AccessibleComponent
Sets the background color of this object.

Specified by:
setBackground in interface AccessibleComponent
Parameters:
c - the new Color for the background
See Also:
AccessibleComponent.setBackground(java.awt.Color)

getForeground

public Color getForeground()
Description copied from interface: AccessibleComponent
Gets the foreground color of this object.

Specified by:
getForeground in interface AccessibleComponent
Returns:
the foreground color, if supported, of the object; otherwise, null
See Also:
AccessibleComponent.setForeground(java.awt.Color)

setForeground

public void setForeground(Color c)
Description copied from interface: AccessibleComponent
Sets the foreground color of this object.

Specified by:
setForeground in interface AccessibleComponent
Parameters:
c - the new Color for the foreground
See Also:
AccessibleComponent.getForeground()

getCursor

public Cursor getCursor()
Description copied from interface: AccessibleComponent
Gets the Cursor of this object.

Specified by:
getCursor in interface AccessibleComponent
Returns:
the Cursor, if supported, of the object; otherwise, null
See Also:
AccessibleComponent.setCursor(java.awt.Cursor)

setCursor

public void setCursor(Cursor c)
Description copied from interface: AccessibleComponent
Sets the Cursor of this object.

Specified by:
setCursor in interface AccessibleComponent
Parameters:
c - the new Cursor for the object
See Also:
AccessibleComponent.getCursor()

getFont

public Font getFont()
Description copied from interface: AccessibleComponent
Gets the Font of this object.

Specified by:
getFont in interface AccessibleComponent
Returns:
the Font,if supported, for the object; otherwise, null
See Also:
AccessibleComponent.setFont(java.awt.Font)

setFont

public void setFont(Font f)
Description copied from interface: AccessibleComponent
Sets the Font of this object.

Specified by:
setFont in interface AccessibleComponent
Parameters:
f - the new Font for the object
See Also:
AccessibleComponent.getFont()

getFontMetrics

public FontMetrics getFontMetrics(Font f)
Description copied from interface: AccessibleComponent
Gets the FontMetrics of this object.

Specified by:
getFontMetrics in interface AccessibleComponent
Parameters:
f - the Font
Returns:
the FontMetrics, if supported, the object; otherwise, null
See Also:
AccessibleComponent.getFont()

isEnabled

public boolean isEnabled()
Description copied from interface: AccessibleComponent
Determines if the object is enabled. Objects that are enabled will also have the AccessibleState.ENABLED state set in their AccessibleStateSets.

Specified by:
isEnabled in interface AccessibleComponent
Returns:
true if object is enabled; otherwise, false
See Also:
AccessibleComponent.setEnabled(boolean), AccessibleContext.getAccessibleStateSet(), AccessibleState.ENABLED, AccessibleStateSet

setEnabled

public void setEnabled(boolean b)
Description copied from interface: AccessibleComponent
Sets the enabled state of the object.

Specified by:
setEnabled in interface AccessibleComponent
Parameters:
b - if true, enables this object; otherwise, disables it
See Also:
AccessibleComponent.isEnabled()

isVisible

public boolean isVisible()
Description copied from interface: AccessibleComponent
Determines if the object is visible. Note: this means that the object intends to be visible; however, it may not be showing on the screen because one of the objects that this object is contained by is currently not visible. To determine if an object is showing on the screen, use isShowing().

Objects that are visible will also have the AccessibleState.VISIBLE state set in their AccessibleStateSets.

Specified by:
isVisible in interface AccessibleComponent
Returns:
true if object is visible; otherwise, false
See Also:
AccessibleComponent.setVisible(boolean), AccessibleContext.getAccessibleStateSet(), AccessibleState.VISIBLE, AccessibleStateSet

setVisible

public void setVisible(boolean b)
Description copied from interface: AccessibleComponent
Sets the visible state of the object.

Specified by:
setVisible in interface AccessibleComponent
Parameters:
b - if true, shows this object; otherwise, hides it
See Also:
AccessibleComponent.isVisible()

isShowing

public boolean isShowing()
Description copied from interface: AccessibleComponent
Determines if the object is showing. This is determined by checking the visibility of the object and its ancestors. Note: this will return true even if the object is obscured by another (for example, it is underneath a menu that was pulled down).

Specified by:
isShowing in interface AccessibleComponent
Returns:
true if object is showing; otherwise, false

contains

public boolean contains(Point p)
Description copied from interface: AccessibleComponent
Checks whether the specified point is within this object's bounds, where the point's x and y coordinates are defined to be relative to the coordinate system of the object.

Specified by:
contains in interface AccessibleComponent
Parameters:
p - the Point relative to the coordinate system of the object
Returns:
true if object contains Point; otherwise false
See Also:
AccessibleComponent.getBounds()

getLocationOnScreen

public Point getLocationOnScreen()
Description copied from interface: AccessibleComponent
Returns the location of the object on the screen.

Specified by:
getLocationOnScreen in interface AccessibleComponent
Returns:
the location of the object on screen; null if this object is not on the screen
See Also:
AccessibleComponent.getBounds(), AccessibleComponent.getLocation()

getLocation

public Point getLocation()
Description copied from interface: AccessibleComponent
Gets the location of the object relative to the parent in the form of a point specifying the object's top-left corner in the screen's coordinate space.

Specified by:
getLocation in interface AccessibleComponent
Returns:
An instance of Point representing the top-left corner of the object's bounds in the coordinate space of the screen; null if this object or its parent are not on the screen
See Also:
AccessibleComponent.getBounds(), AccessibleComponent.getLocationOnScreen()

setLocation

public void setLocation(Point p)
Description copied from interface: AccessibleComponent
Sets the location of the object relative to the parent.

Specified by:
setLocation in interface AccessibleComponent
Parameters:
p - the new position for the top-left corner
See Also:
AccessibleComponent.getLocation()

getBounds

public Rectangle getBounds()
Description copied from interface: AccessibleComponent
Gets the bounds of this object in the form of a Rectangle object. The bounds specify this object's width, height, and location relative to its parent.

Specified by:
getBounds in interface AccessibleComponent
Returns:
A rectangle indicating this component's bounds; null if this object is not on the screen.
See Also:
AccessibleComponent.contains(java.awt.Point)

setBounds

public void setBounds(Rectangle r)
Description copied from interface: AccessibleComponent
Sets the bounds of this object in the form of a Rectangle object. The bounds specify this object's width, height, and location relative to its parent.

Specified by:
setBounds in interface AccessibleComponent
Parameters:
r - rectangle indicating this component's bounds
See Also:
AccessibleComponent.getBounds()

getSize

public Dimension getSize()
Description copied from interface: AccessibleComponent
Returns the size of this object in the form of a Dimension object. The height field of the Dimension object contains this object's height, and the width field of the Dimension object contains this object's width.

Specified by:
getSize in interface AccessibleComponent
Returns:
A Dimension object that indicates the size of this component; null if this object is not on the screen
See Also:
AccessibleComponent.setSize(java.awt.Dimension)

setSize

public void setSize(Dimension d)
Description copied from interface: AccessibleComponent
Resizes this object so that it has width and height.

Specified by:
setSize in interface AccessibleComponent
Parameters:
d - The dimension specifying the new size of the object.
See Also:
AccessibleComponent.getSize()

getAccessibleAt

public Accessible getAccessibleAt(Point p)
Description copied from interface: AccessibleComponent
Returns the Accessible child, if one exists, contained at the local coordinate Point.

Specified by:
getAccessibleAt in interface AccessibleComponent
Parameters:
p - The point relative to the coordinate system of this object.
Returns:
the Accessible, if it exists, at the specified location; otherwise null

isFocusTraversable

public boolean isFocusTraversable()
Description copied from interface: AccessibleComponent
Returns whether this object can accept focus or not. Objects that can accept focus will also have the AccessibleState.FOCUSABLE state set in their AccessibleStateSets.

Specified by:
isFocusTraversable in interface AccessibleComponent
Returns:
true if object can accept focus; otherwise false
See Also:
AccessibleContext.getAccessibleStateSet(), AccessibleState.FOCUSABLE, AccessibleState.FOCUSED, AccessibleStateSet

requestFocus

public void requestFocus()
Description copied from interface: AccessibleComponent
Requests focus for this object. If this object cannot accept focus, nothing will happen. Otherwise, the object will attempt to take focus.

Specified by:
requestFocus in interface AccessibleComponent
See Also:
AccessibleComponent.isFocusTraversable()

addFocusListener

public void addFocusListener(FocusListener l)
Description copied from interface: AccessibleComponent
Adds the specified focus listener to receive focus events from this component.

Specified by:
addFocusListener in interface AccessibleComponent
Parameters:
l - the focus listener
See Also:
AccessibleComponent.removeFocusListener(java.awt.event.FocusListener)

removeFocusListener

public void removeFocusListener(FocusListener l)
Description copied from interface: AccessibleComponent
Removes the specified focus listener so it no longer receives focus events from this component.

Specified by:
removeFocusListener in interface AccessibleComponent
Parameters:
l - the focus listener
See Also:
AccessibleComponent.addFocusListener(java.awt.event.FocusListener)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TableCellEditor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.table
Interface TableCellEditor

All Superinterfaces:
CellEditor
All Known Implementing Classes:
DefaultCellEditor
public interface TableCellEditor
extends CellEditor

This interface defines the method any object that would like to be an editor of values for components such as JListBox, JComboBox, JTree, or JTable needs to implement.

Method Summary
 Component getTableCellEditorComponent(JTable table, Object value, boolean isSelected, int row, int column)
Sets an initial value for the editor.
Methods inherited from interface javax.swing.CellEditor
addCellEditorListener, cancelCellEditing, getCellEditorValue, isCellEditable, removeCellEditorListener, shouldSelectCell, stopCellEditing

Method Detail

getTableCellEditorComponent

Component getTableCellEditorComponent(JTable table,
                                      Object value,
                                      boolean isSelected,
                                      int row,
                                      int column)
Sets an initial value for the editor. This will cause the editor to stopEditing and lose any partially edited value if the editor is editing when this method is called.

Returns the component that should be added to the client's Component hierarchy. Once installed in the client's hierarchy this component will then be able to draw and receive user input.

Parameters:
table - the JTable that is asking the editor to edit; can be null
value - the value of the cell to be edited; it is up to the specific editor to interpret and draw the value. For example, if value is the string "true", it could be rendered as a string or it could be rendered as a check box that is checked. null is a valid value
isSelected - true if the cell is to be rendered with highlighting
row - the row of the cell being edited
column - the column of the cell being edited
Returns:
the component for editing
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TableCellRenderer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.table
Interface TableCellRenderer

All Known Implementing Classes:
DefaultTableCellRenderer, DefaultTableCellRenderer.UIResource
public interface TableCellRenderer

This interface defines the method required by any object that would like to be a renderer for cells in a JTable.

Method Summary
 Component getTableCellRendererComponent(JTable table, Object value, boolean isSelected, boolean hasFocus, int row, int column)
Returns the component used for drawing the cell.

Method Detail

getTableCellRendererComponent

Component getTableCellRendererComponent(JTable table,
                                        Object value,
                                        boolean isSelected,
                                        boolean hasFocus,
                                        int row,
                                        int column)
Returns the component used for drawing the cell. This method is used to configure the renderer appropriately before drawing.

The TableCellRenderer is also responsible for rendering the the cell representing the table's current DnD drop location if it has one. If this renderer cares about rendering the DnD drop location, it should query the table directly to see if the given row and column represent the drop location:

     JTable.DropLocation dropLocation = table.getDropLocation();
     if (dropLocation != null
             && !dropLocation.isInsertRow()
             && !dropLocation.isInsertColumn()
             && dropLocation.getRow() == row
             && dropLocation.getColumn() == column) {

         // this cell represents the current drop location
         // so render it specially, perhaps with a different color
     }

During a printing operation, this method will be called with isSelected and hasFocus values of false to prevent selection and focus from appearing in the printed output. To do other customization based on whether or not the table is being printed, check the return value from JComponent.isPaintingForPrint().

Parameters:
table - the JTable that is asking the renderer to draw; can be null
value - the value of the cell to be rendered. It is up to the specific renderer to interpret and draw the value. For example, if value is the string "true", it could be rendered as a string or it could be rendered as a check box that is checked. null is a valid value
isSelected - true if the cell is to be rendered with the selection highlighted; otherwise false
hasFocus - if true, render cell appropriately. For example, put a special border on the cell, if the cell can be edited, render in the color used to indicate editing
row - the row index of the cell being drawn. When drawing the header, the value of row is -1
column - the column index of the cell being drawn
See Also:
JComponent.isPaintingForPrint()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TableColumn

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.table
Class TableColumn

java.lang.Object
    extended by  javax.swing.table.TableColumn
All Implemented Interfaces:
Serializable
public class TableColumn
extends Object
implements Serializable

A TableColumn represents all the attributes of a column in a JTable, such as width, resizibility, minimum and maximum width. In addition, the TableColumn provides slots for a renderer and an editor that can be used to display and edit the values in this column.

It is also possible to specify renderers and editors on a per type basis rather than a per column basis - see the setDefaultRenderer method in the JTable class. This default mechanism is only used when the renderer (or editor) in the TableColumn is null.

The TableColumn stores the link between the columns in the JTable and the columns in the TableModel. The modelIndex is the column in the TableModel, which will be queried for the data values for the cells in this column. As the column moves around in the view this modelIndex does not change.

Note: Some implementations may assume that all TableColumnModels are unique, therefore we would recommend that the same TableColumn instance not be added more than once to a TableColumnModel. To show TableColumns with the same column of data from the model, create a new instance with the same modelIndex.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
TableColumnModel,
DefaultTableColumnModel,
JTableHeader.getDefaultRenderer(),
JTable.getDefaultRenderer(Class),
JTable.getDefaultEditor(Class),
JTable.getCellRenderer(int, int),
JTable.getCellEditor(int, int)

Field Summary
static String | CELL_RENDERER_PROPERTY Obsolete as of Java 2 platform v1.3.
protected TableCellEditor | cellEditor The editor used to edit the data cells of the column.
protected TableCellRenderer | cellRenderer The renderer used to draw the data cells of the column.
static String | COLUMN_WIDTH_PROPERTY Obsolete as of Java 2 platform v1.3.
static String | HEADER_RENDERER_PROPERTY Obsolete as of Java 2 platform v1.3.
static String | HEADER_VALUE_PROPERTY Obsolete as of Java 2 platform v1.3.
protected TableCellRenderer | headerRenderer The renderer used to draw the header of the column.
protected Object | headerValue The header value of the column.
protected Object | identifier This object is not used internally by the drawing machinery of the JTable; identifiers may be set in the TableColumn as as an optional way to tag and locate table columns.
protected boolean | isResizable If true, the user is allowed to resize the column; the default is true.
protected int | maxWidth The maximum width of the column.
protected int | minWidth The minimum width of the column.
protected int | modelIndex The index of the column in the model which is to be displayed by this TableColumn.
protected int | resizedPostingDisableCount Deprecated. as of Java 2 platform v1.3
protected int | width The width of the column.
Constructor Summary
TableColumn()
Cover method, using a default model index of 0, default width of 75, a null renderer and a null editor.
TableColumn(int modelIndex)
Cover method, using a default width of 75, a null renderer and a null editor.
TableColumn(int modelIndex, int width)
Cover method, using a null renderer and a null editor.
TableColumn(int modelIndex, int width, TableCellRenderer cellRenderer, TableCellEditor cellEditor)
Creates and initializes an instance of TableColumn with the specified model index, width, cell renderer, and cell editor; all TableColumn constructors delegate to this one.
Method Summary
 void addPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list.
protected  TableCellRenderer createDefaultHeaderRenderer()
As of Java 2 platform v1.3, this method is not called by the TableColumn constructor.
 void disableResizedPosting()
Deprecated. as of Java 2 platform v1.3
 void enableResizedPosting()
Deprecated. as of Java 2 platform v1.3
 TableCellEditor getCellEditor()
Returns the TableCellEditor used by the JTable to edit values for this column.
 TableCellRenderer getCellRenderer()
Returns the TableCellRenderer used by the JTable to draw values for this column.
 TableCellRenderer getHeaderRenderer()
Returns the TableCellRenderer used to draw the header of the TableColumn.
 Object getHeaderValue()
Returns the Object used as the value for the header renderer.
 Object getIdentifier()
Returns the identifier object for this column.
 int getMaxWidth()
Returns the maximum width for the TableColumn.
 int getMinWidth()
Returns the minimum width for the TableColumn.
 int getModelIndex()
Returns the model index for this column.
 int getPreferredWidth()
Returns the preferred width of the TableColumn.
 PropertyChangeListener[] getPropertyChangeListeners()
Returns an array of all the PropertyChangeListeners added to this TableColumn with addPropertyChangeListener().
 boolean getResizable()
Returns true if the user is allowed to resize the TableColumn's width, false otherwise.
 int getWidth()
Returns the width of the TableColumn.
 void removePropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list.
 void setCellEditor(TableCellEditor cellEditor)
Sets the editor to used by when a cell in this column is edited.
 void setCellRenderer(TableCellRenderer cellRenderer)
Sets the TableCellRenderer used by JTable to draw individual values for this column.
 void setHeaderRenderer(TableCellRenderer headerRenderer)
Sets the TableCellRenderer used to draw the TableColumn's header to headerRenderer.
 void setHeaderValue(Object headerValue)
Sets the Object whose string representation will be used as the value for the headerRenderer.
 void setIdentifier(Object identifier)
Sets the TableColumn's identifier to anIdentifier.
 void setMaxWidth(int maxWidth)
Sets the TableColumn's maximum width to maxWidth or, if maxWidth is less than the minimum width, to the minimum width.
 void setMinWidth(int minWidth)
Sets the TableColumn's minimum width to minWidth, adjusting the new minimum width if necessary to ensure that 0 <= minWidth <= maxWidth.
 void setModelIndex(int modelIndex)
Sets the model index for this column.
 void setPreferredWidth(int preferredWidth)
Sets this column's preferred width to preferredWidth.
 void setResizable(boolean isResizable)
Sets whether this column can be resized.
 void setWidth(int width)
This method should not be used to set the widths of columns in the JTable, use setPreferredWidth instead.
 void sizeWidthToFit()
Resizes the TableColumn to fit the width of its header cell.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

COLUMN_WIDTH_PROPERTY

public static final String COLUMN_WIDTH_PROPERTY
Obsolete as of Java 2 platform v1.3. Please use string literals to identify properties.

See Also:
Constant Field Values

HEADER_VALUE_PROPERTY

public static final String HEADER_VALUE_PROPERTY
Obsolete as of Java 2 platform v1.3. Please use string literals to identify properties.

See Also:
Constant Field Values

HEADER_RENDERER_PROPERTY

public static final String HEADER_RENDERER_PROPERTY
Obsolete as of Java 2 platform v1.3. Please use string literals to identify properties.

See Also:
Constant Field Values

CELL_RENDERER_PROPERTY

public static final String CELL_RENDERER_PROPERTY
Obsolete as of Java 2 platform v1.3. Please use string literals to identify properties.

See Also:
Constant Field Values

modelIndex

protected int modelIndex
The index of the column in the model which is to be displayed by this TableColumn. As columns are moved around in the view modelIndex remains constant.

identifier

protected Object identifier
This object is not used internally by the drawing machinery of the JTable; identifiers may be set in the TableColumn as as an optional way to tag and locate table columns. The table package does not modify or invoke any methods in these identifier objects other than the equals method which is used in the getColumnIndex() method in the DefaultTableColumnModel.

width

protected int width
The width of the column.

minWidth

protected int minWidth
The minimum width of the column.

maxWidth

protected int maxWidth
The maximum width of the column.

headerRenderer

protected TableCellRenderer headerRenderer
The renderer used to draw the header of the column.

headerValue

protected Object headerValue
The header value of the column.

cellRenderer

protected TableCellRenderer cellRenderer
The renderer used to draw the data cells of the column.

cellEditor

protected TableCellEditor cellEditor
The editor used to edit the data cells of the column.

isResizable

protected boolean isResizable
If true, the user is allowed to resize the column; the default is true.

resizedPostingDisableCount

@Deprecated
protected transient int resizedPostingDisableCount
Deprecated. as of Java 2 platform v1.3
This field was not used in previous releases and there are currently no plans to support it in the future.

Constructor Detail

TableColumn

public TableColumn()
Cover method, using a default model index of 0, default width of 75, a null renderer and a null editor. This method is intended for serialization.

See Also:
TableColumn(int, int, TableCellRenderer, TableCellEditor)

TableColumn

public TableColumn(int modelIndex)
Cover method, using a default width of 75, a null renderer and a null editor.

See Also:
TableColumn(int, int, TableCellRenderer, TableCellEditor)

TableColumn

public TableColumn(int modelIndex,
                   int width)
Cover method, using a null renderer and a null editor.

See Also:
TableColumn(int, int, TableCellRenderer, TableCellEditor)

TableColumn

public TableColumn(int modelIndex,
                   int width,
                   TableCellRenderer cellRenderer,
                   TableCellEditor cellEditor)
Creates and initializes an instance of TableColumn with the specified model index, width, cell renderer, and cell editor; all TableColumn constructors delegate to this one. The value of width is used for both the initial and preferred width; if width is negative, they're set to 0. The minimum width is set to 15 unless the initial width is less, in which case the minimum width is set to the initial width.

When the cellRenderer or cellEditor parameter is null, a default value provided by the JTable getDefaultRenderer or getDefaultEditor method, respectively, is used to provide defaults based on the type of the data in this column. This column-centric rendering strategy can be circumvented by overriding the getCellRenderer methods in JTable.

Parameters:
modelIndex - the index of the column in the model that supplies the data for this column in the table; the model index remains the same even when columns are reordered in the view
width - this column's preferred width and initial width
cellRenderer - the object used to render values in this column
cellEditor - the object used to edit values in this column
See Also:
getMinWidth(),
JTable.getDefaultRenderer(Class),
JTable.getDefaultEditor(Class),
JTable.getCellRenderer(int, int),
JTable.getCellEditor(int, int)
Method Detail

setModelIndex

public void setModelIndex(int modelIndex)
Sets the model index for this column. The model index is the index of the column in the model that will be displayed by this TableColumn. As the TableColumn is moved around in the view the model index remains constant.

Parameters:
modelIndex - the new modelIndex

getModelIndex

public int getModelIndex()
Returns the model index for this column.

Returns:
the modelIndex property

setIdentifier

public void setIdentifier(Object identifier)
Sets the TableColumn's identifier to anIdentifier.

Note: identifiers are not used by the JTable, they are purely a convenience for the external tagging and location of columns.

Parameters:
identifier - an identifier for this column
See Also:
getIdentifier()

getIdentifier

public Object getIdentifier()
Returns the identifier object for this column. Note identifiers are not used by JTable, they are purely a convenience for external use. If the identifier is null, getIdentifier() returns getHeaderValue as a default.

Returns:
the identifier property
See Also:
setIdentifier(java.lang.Object)

setHeaderValue

public void setHeaderValue(Object headerValue)
Sets the Object whose string representation will be used as the value for the headerRenderer. When the TableColumn is created, the default headerValue is null.

Parameters:
headerValue - the new headerValue
See Also:
getHeaderValue()

getHeaderValue

public Object getHeaderValue()
Returns the Object used as the value for the header renderer.

Returns:
the headerValue property
See Also:
setHeaderValue(java.lang.Object)

setHeaderRenderer

public void setHeaderRenderer(TableCellRenderer headerRenderer)
Sets the TableCellRenderer used to draw the TableColumn's header to headerRenderer.

It is the header renderers responsibility to render the sorting indicator. If you are using sorting and specify a renderer your renderer must render the sorting indication.

Parameters:
headerRenderer - the new headerRenderer
See Also:
getHeaderRenderer()

getHeaderRenderer

public TableCellRenderer getHeaderRenderer()
Returns the TableCellRenderer used to draw the header of the TableColumn. When the headerRenderer is null, the JTableHeader uses its defaultRenderer. The default value for a headerRenderer is null.

Returns:
the headerRenderer property
See Also:
setHeaderRenderer(javax.swing.table.TableCellRenderer),
setHeaderValue(java.lang.Object),
JTableHeader.getDefaultRenderer()

setCellRenderer

public void setCellRenderer(TableCellRenderer cellRenderer)
Sets the TableCellRenderer used by JTable to draw individual values for this column.

Parameters:
cellRenderer - the new cellRenderer
See Also:
getCellRenderer()

getCellRenderer

public TableCellRenderer getCellRenderer()
Returns the TableCellRenderer used by the JTable to draw values for this column. The cellRenderer of the column not only controls the visual look for the column, but is also used to interpret the value object supplied by the TableModel. When the cellRenderer is null, the JTable uses a default renderer based on the class of the cells in that column. The default value for a cellRenderer is null.

Returns:
the cellRenderer property
See Also:
setCellRenderer(javax.swing.table.TableCellRenderer), JTable.setDefaultRenderer(java.lang.Class, javax.swing.table.TableCellRenderer)

setCellEditor

public void setCellEditor(TableCellEditor cellEditor)
Sets the editor to used by when a cell in this column is edited.

Parameters:
cellEditor - the new cellEditor
See Also:
getCellEditor()

getCellEditor

public TableCellEditor getCellEditor()
Returns the TableCellEditor used by the JTable to edit values for this column. When the cellEditor is null, the JTable uses a default editor based on the class of the cells in that column. The default value for a cellEditor is null.

Returns:
the cellEditor property
See Also:
setCellEditor(javax.swing.table.TableCellEditor), JTable.setDefaultEditor(java.lang.Class, javax.swing.table.TableCellEditor)

setWidth

public void setWidth(int width)
This method should not be used to set the widths of columns in the JTable, use setPreferredWidth instead. Like a layout manager in the AWT, the JTable adjusts a column's width automatically whenever the table itself changes size, or a column's preferred width is changed. Setting widths programmatically therefore has no long term effect.

This method sets this column's width to width. If width exceeds the minimum or maximum width, it is adjusted to the appropriate limiting value.

Parameters:
width - the new width
See Also:
getWidth(), setMinWidth(int), setMaxWidth(int), setPreferredWidth(int), JTable.doLayout()

getWidth

public int getWidth()
Returns the width of the TableColumn. The default width is 75.

Returns:
the width property
See Also:
setWidth(int)

setPreferredWidth

public void setPreferredWidth(int preferredWidth)
Sets this column's preferred width to preferredWidth. If preferredWidth exceeds the minimum or maximum width, it is adjusted to the appropriate limiting value.

For details on how the widths of columns in the JTable (and JTableHeader) are calculated from the preferredWidth, see the doLayout method in JTable.

Parameters:
preferredWidth - the new preferred width
See Also:
getPreferredWidth(), JTable.doLayout()

getPreferredWidth

public int getPreferredWidth()
Returns the preferred width of the TableColumn. The default preferred width is 75.

Returns:
the preferredWidth property
See Also:
setPreferredWidth(int)

setMinWidth

public void setMinWidth(int minWidth)
Sets the TableColumn's minimum width to minWidth, adjusting the new minimum width if necessary to ensure that 0 <= minWidth <= maxWidth. For example, if the minWidth argument is negative, this method sets the minWidth property to 0.

If the value of the width or preferredWidth property is less than the new minimum width, this method sets that property to the new minimum width.

Parameters:
minWidth - the new minimum width
See Also:
getMinWidth(), setPreferredWidth(int), setMaxWidth(int)

getMinWidth

public int getMinWidth()
Returns the minimum width for the TableColumn. The TableColumn's width can't be made less than this either by the user or programmatically.

Returns:
the minWidth property
See Also:
setMinWidth(int), TableColumn(int, int, TableCellRenderer, TableCellEditor)

setMaxWidth

public void setMaxWidth(int maxWidth)
Sets the TableColumn's maximum width to maxWidth or, if maxWidth is less than the minimum width, to the minimum width.

If the value of the width or preferredWidth property is more than the new maximum width, this method sets that property to the new maximum width.

Parameters:
maxWidth - the new maximum width
See Also:
getMaxWidth(), setPreferredWidth(int), setMinWidth(int)

getMaxWidth

public int getMaxWidth()
Returns the maximum width for the TableColumn. The TableColumn's width can't be made larger than this either by the user or programmatically. The default maxWidth is Integer.MAX_VALUE.

Returns:
the maxWidth property
See Also:
setMaxWidth(int)

setResizable

public void setResizable(boolean isResizable)
Sets whether this column can be resized.

Parameters:
isResizable - if true, resizing is allowed; otherwise false
See Also:
getResizable()

getResizable

public boolean getResizable()
Returns true if the user is allowed to resize the TableColumn's width, false otherwise. You can change the width programmatically regardless of this setting. The default is true.

Returns:
the isResizable property
See Also:
setResizable(boolean)

sizeWidthToFit

public void sizeWidthToFit()
Resizes the TableColumn to fit the width of its header cell. This method does nothing if the header renderer is null (the default case). Otherwise, it sets the minimum, maximum and preferred widths of this column to the widths of the minimum, maximum and preferred sizes of the Component delivered by the header renderer. The transient "width" property of this TableColumn is also set to the preferred width. Note this method is not used internally by the table package.

See Also:
setPreferredWidth(int)

disableResizedPosting

@Deprecated
public void disableResizedPosting()
Deprecated. as of Java 2 platform v1.3

This field was not used in previous releases and there are currently no plans to support it in the future.

enableResizedPosting

@Deprecated
public void enableResizedPosting()
Deprecated. as of Java 2 platform v1.3

This field was not used in previous releases and there are currently no plans to support it in the future.

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list. The listener is registered for all properties.

A PropertyChangeEvent will get fired in response to an explicit call to setFont, setBackground, or setForeground on the current component. Note that if the current component is inheriting its foreground, background, or font from its container, then no event will be fired in response to a change in the inherited property.

Parameters:
listener - the listener to be added

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list. The PropertyChangeListener to be removed was registered for all properties.

Parameters:
listener - the listener to be removed

getPropertyChangeListeners

public PropertyChangeListener[] getPropertyChangeListeners()
Returns an array of all the PropertyChangeListeners added to this TableColumn with addPropertyChangeListener().

Returns:
all of the PropertyChangeListeners added or an empty array if no listeners have been added
Since:
1.4

createDefaultHeaderRenderer

protected TableCellRenderer createDefaultHeaderRenderer()
As of Java 2 platform v1.3, this method is not called by the TableColumn constructor. Previously this method was used by the TableColumn to create a default header renderer. As of Java 2 platform v1.3, the default header renderer is null. JTableHeader now provides its own shared default renderer, just as the JTable does for its cell renderers.

Returns:
the default header renderer
See Also:
JTableHeader.createDefaultRenderer()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TableColumnModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.table
Interface TableColumnModel

All Known Implementing Classes:
DefaultTableColumnModel
public interface TableColumnModel

Defines the requirements for a table column model object suitable for use with JTable.

See Also:
DefaultTableColumnModel

Method Summary
void | addColumn(TableColumn aColumn) Appends aColumn to the end of the tableColumns array.
void | addColumnModelListener(TableColumnModelListener x) Adds a listener for table column model events.
TableColumn | getColumn(int columnIndex) Returns the TableColumn object for the column at columnIndex.
int | getColumnCount() Returns the number of columns in the model.
int | getColumnIndex(Object columnIdentifier) Returns the index of the first column in the table whose identifier is equal to identifier, when compared using equals.
int | getColumnIndexAtX(int xPosition) Returns the index of the column that lies on the horizontal point, xPosition; or -1 if it lies outside the any of the column's bounds.
int | getColumnMargin() Returns the width between the cells in each column.
Enumeration<TableColumn> | getColumns() Returns an Enumeration of all the columns in the model.
boolean | getColumnSelectionAllowed() Returns true if columns may be selected.
int | getSelectedColumnCount() Returns the number of selected columns.
int[] | getSelectedColumns() Returns an array of indicies of all selected columns.
ListSelectionModel | getSelectionModel() Returns the current selection model.
int | getTotalColumnWidth() Returns the total width of all the columns.
void | moveColumn(int columnIndex, int newIndex) Moves the column and its header at columnIndex to newIndex.
void | removeColumn(TableColumn column) Deletes the TableColumn column from the tableColumns array.
void | removeColumnModelListener(TableColumnModelListener x) Removes a listener for table column model events.
void | setColumnMargin(int newMargin) Sets the TableColumn's column margin to newMargin.
void | setColumnSelectionAllowed(boolean flag) Sets whether the columns in this model may be selected.
void | setSelectionModel(ListSelectionModel newModel) Sets the selection model.

Method Detail

addColumn

void addColumn(TableColumn aColumn)
Appends aColumn to the end of the tableColumns array. This method posts a columnAdded event to its listeners.

Parameters:
aColumn - the TableColumn to be added
See Also:
removeColumn(javax.swing.table.TableColumn)

removeColumn

void removeColumn(TableColumn column)
Deletes the TableColumn column from the tableColumns array. This method will do nothing if column is not in the table's column list. This method posts a columnRemoved event to its listeners.

Parameters:
column - the TableColumn to be removed
See Also:
addColumn(javax.swing.table.TableColumn)

moveColumn

void moveColumn(int columnIndex,
                int newIndex)
Moves the column and its header at columnIndex to newIndex. The old column at columnIndex will now be found at newIndex. The column that used to be at newIndex is shifted left or right to make room. This will not move any columns if columnIndex equals newIndex. This method posts a columnMoved event to its listeners.

Parameters:
columnIndex - the index of column to be moved
newIndex - index of the column's new location
Throws:
IllegalArgumentException - if columnIndex or newIndex are not in the valid range

setColumnMargin

void setColumnMargin(int newMargin)
Sets the TableColumn's column margin to newMargin. This method posts a columnMarginChanged event to its listeners.

Parameters:
newMargin - the width, in pixels, of the new column margins
See Also:
getColumnMargin()

getColumnCount

int getColumnCount()
Returns the number of columns in the model.

Returns:
the number of columns in the model

getColumns

Enumeration<TableColumn> getColumns()
Returns an Enumeration of all the columns in the model.

Returns:
an Enumeration of all the columns in the model

getColumnIndex

int getColumnIndex(Object columnIdentifier)
Returns the index of the first column in the table whose identifier is equal to identifier, when compared using equals.

Parameters:
columnIdentifier - the identifier object
Returns:
the index of the first table column whose identifier is equal to identifier
Throws:
IllegalArgumentException - if identifier is null, or no TableColumn has this identifier
See Also:
getColumn(int)

getColumn

TableColumn getColumn(int columnIndex)
Returns the TableColumn object for the column at columnIndex.

Parameters:
columnIndex - the index of the desired column
Returns:
the TableColumn object for the column at columnIndex

getColumnMargin

int getColumnMargin()
Returns the width between the cells in each column.

Returns:
the margin, in pixels, between the cells

getColumnIndexAtX

int getColumnIndexAtX(int xPosition)
Returns the index of the column that lies on the horizontal point, xPosition; or -1 if it lies outside the any of the column's bounds. In keeping with Swing's separable model architecture, a TableColumnModel does not know how the table columns actually appear on screen. The visual presentation of the columns is the responsibility of the view/controller object using this model (typically JTable). The view/controller need not display the columns sequentially from left to right. For example, columns could be displayed from right to left to accomodate a locale preference or some columns might be hidden at the request of the user. Because the model does not know how the columns are laid out on screen, the given xPosition should not be considered to be a coordinate in 2D graphics space. Instead, it should be considered to be a width from the start of the first column in the model. If the column index for a given X coordinate in 2D space is required, JTable.columnAtPoint can be used instead.

Returns:
the index of the column; or -1 if no column is found
See Also:
JTable.columnAtPoint(java.awt.Point)

getTotalColumnWidth

int getTotalColumnWidth()
Returns the total width of all the columns.

Returns:
the total computed width of all columns

setColumnSelectionAllowed

void setColumnSelectionAllowed(boolean flag)
Sets whether the columns in this model may be selected.

Parameters:
flag - true if columns may be selected; otherwise false
See Also:
getColumnSelectionAllowed()

getColumnSelectionAllowed

boolean getColumnSelectionAllowed()
Returns true if columns may be selected.

Returns:
true if columns may be selected
See Also:
setColumnSelectionAllowed(boolean)

getSelectedColumns

int[] getSelectedColumns()
Returns an array of indicies of all selected columns.

Returns:
an array of integers containing the indicies of all selected columns; or an empty array if nothing is selected

getSelectedColumnCount

int getSelectedColumnCount()
Returns the number of selected columns.

Returns:
the number of selected columns; or 0 if no columns are selected

setSelectionModel

void setSelectionModel(ListSelectionModel newModel)
Sets the selection model.

Parameters:
newModel - a ListSelectionModel object
See Also:
getSelectionModel()

getSelectionModel

ListSelectionModel getSelectionModel()
Returns the current selection model.

Returns:
a ListSelectionModel object
See Also:
setSelectionModel(javax.swing.ListSelectionModel)

addColumnModelListener

void addColumnModelListener(TableColumnModelListener x)
Adds a listener for table column model events.

Parameters:
x - a TableColumnModelListener object

removeColumnModelListener

void removeColumnModelListener(TableColumnModelListener x)
Removes a listener for table column model events.

Parameters:
x - a TableColumnModelListener object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TableModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.table
Interface TableModel

All Known Implementing Classes:
AbstractTableModel, DefaultTableModel
public interface TableModel

The TableModel interface specifies the methods the JTable will use to interrogate a tabular data model.

The JTable can be set up to display any data model which implements the TableModel interface with a couple of lines of code:

        TableModel myData = new MyTableModel();
        JTable table = new JTable(myData);

For further documentation, see Creating a Table Model in The Java Tutorial.

See Also:
JTable

Method Summary
void | addTableModelListener(TableModelListener l) Adds a listener to the list that is notified each time a change to the data model occurs.
Class<?> | getColumnClass(int columnIndex) Returns the most specific superclass for all the cell values in the column.
int | getColumnCount() Returns the number of columns in the model.
String | getColumnName(int columnIndex) Returns the name of the column at columnIndex.
int | getRowCount() Returns the number of rows in the model.
Object | getValueAt(int rowIndex, int columnIndex) Returns the value for the cell at columnIndex and rowIndex.
boolean | isCellEditable(int rowIndex, int columnIndex) Returns true if the cell at rowIndex and columnIndex is editable.
void | removeTableModelListener(TableModelListener l) Removes a listener from the list that is notified each time a change to the data model occurs.
void | setValueAt(Object aValue, int rowIndex, int columnIndex) Sets the value in the cell at columnIndex and rowIndex to aValue.

Method Detail

getRowCount

int getRowCount()
Returns the number of rows in the model. A JTable uses this method to determine how many rows it should display. This method should be quick, as it is called frequently during rendering.

Returns:
the number of rows in the model
See Also:
getColumnCount()

getColumnCount

int getColumnCount()
Returns the number of columns in the model. A JTable uses this method to determine how many columns it should create and display by default.

Returns:
the number of columns in the model
See Also:
getRowCount()

getColumnName

String getColumnName(int columnIndex)
Returns the name of the column at columnIndex. This is used to initialize the table's column header name. Note: this name does not need to be unique; two columns in a table can have the same name.

Parameters:
columnIndex - the index of the column
Returns:
the name of the column

getColumnClass

Class<?> getColumnClass(int columnIndex)
Returns the most specific superclass for all the cell values in the column. This is used by the JTable to set up a default renderer and editor for the column.

Parameters:
columnIndex - the index of the column
Returns:
the common ancestor class of the object values in the model.

isCellEditable

boolean isCellEditable(int rowIndex,
                       int columnIndex)
Returns true if the cell at rowIndex and columnIndex is editable. Otherwise, setValueAt on the cell will not change the value of that cell.

Parameters:
rowIndex - the row whose value to be queried
columnIndex - the column whose value to be queried
Returns:
true if the cell is editable
See Also:
setValueAt(java.lang.Object, int, int)

getValueAt

Object getValueAt(int rowIndex,
                  int columnIndex)
Returns the value for the cell at columnIndex and rowIndex.

Parameters:
rowIndex - the row whose value is to be queried
columnIndex - the column whose value is to be queried
Returns:
the value Object at the specified cell

setValueAt

void setValueAt(Object aValue,
                int rowIndex,
                int columnIndex)
Sets the value in the cell at columnIndex and rowIndex to aValue.

Parameters:
aValue - the new value
rowIndex - the row whose value is to be changed
columnIndex - the column whose value is to be changed
See Also:
getValueAt(int, int), isCellEditable(int, int)

addTableModelListener

void addTableModelListener(TableModelListener l)
Adds a listener to the list that is notified each time a change to the data model occurs.

Parameters:
l - the TableModelListener

removeTableModelListener

void removeTableModelListener(TableModelListener l)
Removes a listener from the list that is notified each time a change to the data model occurs.

Parameters:
l - the TableModelListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TableRowSorter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.table
Class TableRowSorter<M extends TableModel>

java.lang.Object
    extended by  javax.swing.RowSorter<M>
        extended by  javax.swing.DefaultRowSorter<M,Integer>
            extended by  javax.swing.table.TableRowSorter<M>
Type Parameters:
M - the type of the model, which must be an implementation of TableModel
public class TableRowSorter<M extends TableModel>
extends DefaultRowSorter<M,Integer>

An implementation of RowSorter that provides sorting and filtering using a TableModel. The following example shows adding sorting to a JTable:

   TableModel myModel = createMyTableModel();
   JTable table = new JTable(myModel);
   table.setRowSorter(new TableRowSorter(myModel));
This will do all the wiring such that when the user does the appropriate gesture, such as clicking on the column header, the table will visually sort.

JTable's row-based methods and JTable's selection model refer to the view and not the underlying model. Therefore, it is necessary to convert between the two. For example, to get the selection in terms of myModel you need to convert the indices:

   int[] selection = table.getSelectedRows();
   for (int i = 0; i < selection.length; i++) {
     selection[i] = table.convertRowIndexToModel(selection[i]);
   }
Similarly to select a row in JTable based on a coordinate from the underlying model do the inverse:
   table.setRowSelectionInterval(table.convertRowIndexToView(row),
                                 table.convertRowIndexToView(row));

The previous example assumes you have not enabled filtering. If you have enabled filtering convertRowIndexToView will return -1 for locations that are not visible in the view.

TableRowSorter uses Comparators for doing comparisons. The following defines how a Comparator is chosen for a column:

  1. If a Comparator has been specified for the column by the setComparator method, use it.
  2. If the column class as returned by getColumnClass is String, use the Comparator returned by Collator.getInstance().
  3. If the column class implements Comparable, use a Comparator that invokes the compareTo method.
  4. If a TableStringConverter has been specified, use it to convert the values to Strings and then use the Comparator returned by Collator.getInstance().
  5. Otherwise use the Comparator returned by Collator.getInstance() on the results from calling toString on the objects.

In addition to sorting TableRowSorter provides the ability to filter. A filter is specified using the setFilter method. The following example will only show rows containing the string "foo":

   TableModel myModel = createMyTableModel();
   TableRowSorter sorter = new TableRowSorter(myModel);
   sorter.setRowFilter(RowFilter.regexFilter(".*foo.*"));
   JTable table = new JTable(myModel);
   table.setRowSorter(sorter);

If the underlying model structure changes (the modelStructureChanged method is invoked) the following are reset to their default values: Comparators by column, current sort order, and whether each column is sortable. The default sort order is natural (the same as the model), and columns are sortable by default.

TableRowSorter has one formal type parameter: the type of the model. Passing in a type that corresponds exactly to your model allows you to filter based on your model without casting. Refer to the documentation of RowFilter for an example of this.

WARNING: DefaultTableModel returns a column class of Object. As such all comparisons will be done using toString. This may be unnecessarily expensive. If the column only contains one type of value, such as an Integer, you should override getColumnClass and return the appropriate Class. This will dramatically increase the performance of this class.

Since:
1.6
See Also:
JTable, RowFilter, DefaultTableModel, Collator, Comparator

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.DefaultRowSorter
DefaultRowSorter.ModelWrapper<M,I>
Nested classes/interfaces inherited from class javax.swing.RowSorter
RowSorter.SortKey
Constructor Summary
TableRowSorter()
Creates a TableRowSorter with an empty model.
TableRowSorter(M model)
Creates a TableRowSorter using model as the underlying TableModel.
Method Summary
Comparator<?> | getComparator(int column) Returns the Comparator for the specified column.
TableStringConverter | getStringConverter() Returns the object responsible for converting values from the model to strings.
void | setModel(M model) Sets the TableModel to use as the underlying model for this TableRowSorter.
void | setStringConverter(TableStringConverter stringConverter) Sets the object responsible for converting values from the model to strings.
protected boolean | useToString(int column) Returns whether or not to convert the value to a string before doing comparisons when sorting.
Methods inherited from class javax.swing.DefaultRowSorter
allRowsChanged, convertRowIndexToModel, convertRowIndexToView, getMaxSortKeys, getModel, getModelRowCount, getModelWrapper, getRowFilter, getSortKeys, getSortsOnUpdates, getViewRowCount, isSortable, modelStructureChanged, rowsDeleted, rowsInserted, rowsUpdated, rowsUpdated, setComparator, setMaxSortKeys, setModelWrapper, setRowFilter, setSortable, setSortKeys, setSortsOnUpdates, sort, toggleSortOrder
Methods inherited from class javax.swing.RowSorter
addRowSorterListener, fireRowSorterChanged, fireSortOrderChanged, removeRowSorterListener
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TableRowSorter

public TableRowSorter()
Creates a TableRowSorter with an empty model.

TableRowSorter

public TableRowSorter(M model)
Creates a TableRowSorter using model as the underlying TableModel.

Parameters:
model - the underlying TableModel to use, null is treated as an empty model
Method Detail

setModel

public void setModel(M model)
Sets the TableModel to use as the underlying model for this TableRowSorter. A value of null can be used to set an empty model.

Parameters:
model - the underlying model to use, or null

setStringConverter

public void setStringConverter(TableStringConverter stringConverter)
Sets the object responsible for converting values from the model to strings. If non-null this is used to convert any object values, that do not have a registered Comparator, to strings.

Parameters:
stringConverter - the object responsible for converting values from the model to strings

getStringConverter

public TableStringConverter getStringConverter()
Returns the object responsible for converting values from the model to strings.

Returns:
object responsible for converting values to strings.

getComparator

public Comparator<?> getComparator(int column)
Returns the Comparator for the specified column. If a Comparator has not been specified using the setComparator method a Comparator will be returned based on the column class (TableModel.getColumnClass) of the specified column. If the column class is String, Collator.getInstance is returned. If the column class implements Comparable a private Comparator is returned that invokes the compareTo method. Otherwise Collator.getInstance is returned.

Overrides:
getComparator in class DefaultRowSorter<M extends TableModel,Integer>
Parameters:
column - the column to fetch the Comparator for, in terms of the underlying model
Returns:
the Comparator for the specified column
Throws:
IndexOutOfBoundsException - if column is outside the range of the underlying model

useToString

protected boolean useToString(int column)
Returns whether or not to convert the value to a string before doing comparisons when sorting. If true ModelWrapper.getStringValueAt will be used, otherwise ModelWrapper.getValueAt will be used. It is up to subclasses, such as TableRowSorter, to honor this value in their ModelWrapper implementation.

Overrides:
useToString in class DefaultRowSorter<M extends TableModel,Integer>
Parameters:
column - the index of the column to test, in terms of the underlying model
Throws:
IndexOutOfBoundsException - if column is not valid
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TableStringConverter

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.table
Class TableStringConverter

java.lang.Object
    extended by  javax.swing.table.TableStringConverter

public abstract class TableStringConverter
extends Object

TableStringConverter is used to convert objects from the model into strings. This is useful in filtering and searching when the model returns objects that do not have meaningful toString implementations.

Since:
1.6

Constructor Summary
TableStringConverter()
Method Summary
abstract  String toString(TableModel model, int row, int column)
Returns the string representation of the value at the specified location.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TableStringConverter

public TableStringConverter()
Method Detail

toString

public abstract String toString(TableModel model,
                                int row,
                                int column)
Returns the string representation of the value at the specified location.

Parameters:
model - the TableModel to fetch the value from
row - the row the string is being requested for
column - the column the string is being requested for
Returns:
the string representation. This should never return null.
Throws:
NullPointerException - if model is null
IndexOutOfBoundsException - if the arguments are outside the bounds of the model
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


text

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.swing.text

Provides classes and interfaces that deal with editable and noneditable text components.

See:
Description

Interface Summary
AbstractDocument.AttributeContext | An interface that can be used to allow MutableAttributeSet implementations to use pluggable attribute compression techniques.
AbstractDocument.Content | Interface to describe a sequence of character content that can be edited.
AttributeSet | A collection of unique attributes.
AttributeSet.CharacterAttribute | This interface is the type signature that is expected to be present on any attribute key that contributes to character level presentation.
AttributeSet.ColorAttribute | This interface is the type signature that is expected to be present on any attribute key that contributes to presentation of color.
AttributeSet.FontAttribute | This interface is the type signature that is expected to be present on any attribute key that contributes to the determination of what font to use to render some text.
AttributeSet.ParagraphAttribute | This interface is the type signature that is expected to be present on any attribute key that contributes to the paragraph level presentation.
Caret | A place within a document view that represents where things can be inserted into the document model.
Document | The Document is a container for text that serves as the model for swing text components.
Element | Interface to describe a structural piece of a document.
Highlighter | An interface for an object that allows one to mark up the background with colored areas.
Highlighter.Highlight |
Highlighter.HighlightPainter | Highlight renderer.
Keymap | A collection of bindings of KeyStrokes to actions.
MutableAttributeSet | A generic interface for a mutable collection of unique attributes.
Position | Represents a location within a document.
Style | A collection of attributes to associate with an element in a document.
StyledDocument | Interface for a generic styled document.
TabableView | Interface for Views that have size dependent upon tabs.
TabExpander | Simple interface to allow for different types of implementations of tab expansion.
ViewFactory | A factory to create a view of some portion of document subject.

Class Summary
AbstractDocument | An implementation of the document interface to serve as a basis for implementing various kinds of documents.
AbstractDocument.ElementEdit | An implementation of ElementChange that can be added to the document event.
AbstractWriter | AbstractWriter is an abstract class that actually does the work of writing out the element tree including the attributes.
AsyncBoxView | A box that does layout asynchronously.
BoxView | A view that arranges its children into a box shape by tiling its children along an axis.
ComponentView | Component decorator that implements the view interface.
CompositeView | CompositeView is an abstract View implementation which manages one or more child views.
DateFormatter | DateFormatter is an InternationalFormatter that does its formatting by way of an instance of java.text.DateFormat.
DefaultCaret | A default implementation of Caret.
DefaultEditorKit | This is the set of things needed by a text component to be a reasonably functioning editor for some type of text document.
DefaultEditorKit.BeepAction | Creates a beep.
DefaultEditorKit.CopyAction | Copies the selected region and place its contents into the system clipboard.
DefaultEditorKit.CutAction | Cuts the selected region and place its contents into the system clipboard.
DefaultEditorKit.DefaultKeyTypedAction | The action that is executed by default if a key typed event is received and there is no keymap entry.
DefaultEditorKit.InsertBreakAction | Places a line/paragraph break into the document.
DefaultEditorKit.InsertContentAction | Places content into the associated document.
DefaultEditorKit.InsertTabAction | Places a tab character into the document.
DefaultEditorKit.PasteAction | Pastes the contents of the system clipboard into the selected region, or before the caret if nothing is selected.
DefaultFormatter | DefaultFormatter formats aribtrary objects.
DefaultFormatterFactory | An implementation of JFormattedTextField.AbstractFormatterFactory.
DefaultHighlighter | Implements the Highlighter interfaces.
DefaultHighlighter.DefaultHighlightPainter | Simple highlight painter that fills a highlighted area with a solid color.
DefaultStyledDocument | A document that can be marked up with character and paragraph styles in a manner similar to the Rich Text Format.
DefaultStyledDocument.AttributeUndoableEdit | An UndoableEdit used to remember AttributeSet changes to an Element.
DefaultStyledDocument.ElementSpec | Specification for building elements.
DefaultTextUI | Deprecated.
DocumentFilter | DocumentFilter, as the name implies, is a filter for the Document mutation methods.
DocumentFilter.FilterBypass | Used as a way to circumvent calling back into the Document to change it.
EditorKit | Establishes the set of things needed by a text component to be a reasonably functioning editor for some type of text content.
ElementIterator | ElementIterator, as the name suggests, iteratates over the Element tree.
FieldView | Extends the multi-line plain text view to be suitable for a single-line editor view.
FlowView | A View that tries to flow it's children into some partially constrained space.
FlowView.FlowStrategy | Strategy for maintaining the physical form of the flow.
GapContent | An implementation of the AbstractDocument.Content interface implemented using a gapped buffer similar to that used by emacs.
GlyphView | A GlyphView is a styled chunk of text that represents a view mapped over an element in the text model.
GlyphView.GlyphPainter | A class to perform rendering of the glyphs.
IconView | Icon decorator that implements the view interface.
InternationalFormatter | InternationalFormatter extends DefaultFormatter, using an instance of java.text.Format to handle the conversion to a String, and the conversion from a String.
JTextComponent | JTextComponent is the base class for swing text components.
JTextComponent.DropLocation | Represents a drop location for JTextComponents.
JTextComponent.KeyBinding | Binding record for creating key bindings.
LabelView | A LabelView is a styled chunk of text that represents a view mapped over an element in the text model.
LayeredHighlighter |
LayeredHighlighter.LayerPainter | Layered highlight renderer.
LayoutQueue | A queue of text layout tasks.
MaskFormatter | MaskFormatter is used to format and edit strings.
NavigationFilter | NavigationFilter can be used to restrict where the cursor can be positioned.
NavigationFilter.FilterBypass | Used as a way to circumvent calling back into the caret to position the cursor.
NumberFormatter | NumberFormatter subclasses InternationalFormatter adding special behavior for numbers.
ParagraphView | View of a simple line-wrapping paragraph that supports multiple fonts, colors, components, icons, etc.
PasswordView | Implements a View suitable for use in JPasswordField UI implementations.
PlainDocument | A plain document that maintains no character attributes.
PlainView | Implements View interface for a simple multi-line text view that has text in one font and color.
Position.Bias | A typesafe enumeration to indicate bias to a position in the model.
Segment | A segment of a character array representing a fragment of text.
SimpleAttributeSet | A straightforward implementation of MutableAttributeSet using a hash table.
StringContent | An implementation of the AbstractDocument.Content interface that is a brute force implementation that is useful for relatively small documents and/or debugging.
StyleConstants | A collection of well known or common attribute keys and methods to apply to an AttributeSet or MutableAttributeSet to get/set the properties in a typesafe manner.
StyleConstants.CharacterConstants | This is a typesafe enumeration of the well-known attributes that contribute to a character style.
StyleConstants.ColorConstants | This is a typesafe enumeration of the well-known attributes that contribute to a color.
StyleConstants.FontConstants | This is a typesafe enumeration of the well-known attributes that contribute to a font.
StyleConstants.ParagraphConstants | This is a typesafe enumeration of the well-known attributes that contribute to a paragraph style.
StyleContext | A pool of styles and their associated resources.
StyledEditorKit | This is the set of things needed by a text component to be a reasonably functioning editor for some type of text document.
StyledEditorKit.AlignmentAction | An action to set paragraph alignment.
StyledEditorKit.BoldAction | An action to toggle the bold attribute.
StyledEditorKit.FontFamilyAction | An action to set the font family in the associated JEditorPane.
StyledEditorKit.FontSizeAction | An action to set the font size in the associated JEditorPane.
StyledEditorKit.ForegroundAction | An action to set foreground color.
StyledEditorKit.ItalicAction | An action to toggle the italic attribute.
StyledEditorKit.StyledTextAction | An action that assumes it's being fired on a JEditorPane with a StyledEditorKit (or subclass) installed.
StyledEditorKit.UnderlineAction | An action to toggle the underline attribute.
TableView | Implements View interface for a table, that is composed of an element structure where the child elements of the element this view is responsible for represent rows and the child elements of the row elements are cells.
TabSet | A TabSet is comprised of many TabStops.
TabStop | This class encapsulates a single tab stop (basically as tab stops are thought of by RTF).
TextAction | An Action implementation useful for key bindings that are shared across a number of different text components.
Utilities | A collection of methods to deal with various text related activities.
View | A very important part of the text package is the View class.
WrappedPlainView | View of plain text (text with only one font and color) that does line-wrapping.
ZoneView | ZoneView is a View implementation that creates zones for which the child views are not created or stored until they are needed for display or model/view translations.

Exception Summary
BadLocationException | This exception is to report bad locations within a document model (that is, attempts to reference a location that doesn't exist).
ChangedCharSetException | ChangedCharSetException as the name indicates is an exception thrown when the charset is changed.

Package javax.swing.text Description

Provides classes and interfaces that deal with editable and noneditable text components. Examples of text components are text fields and text areas, of which password fields and document editors are special instantiations. Features that are supported by this package include selection/highlighting, editing, style, and key mapping.

Note: Most of the Swing API is not thread safe. For details, see Threads and Swing, a section in The Java Tutorial.

Related Documentation

For overviews, tutorials, examples, guides, and tool documentation, please see:
  • Using Text Components, a section in The Java Tutorial

Since:
1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


AttributeSet.CharacterAttribute

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface AttributeSet.CharacterAttribute

All Known Implementing Classes:
StyleConstants.CharacterConstants, StyleConstants.ColorConstants, StyleConstants.FontConstants
Enclosing interface:
AttributeSet
public static interface AttributeSet.CharacterAttribute

This interface is the type signature that is expected to be present on any attribute key that contributes to character level presentation. This would be any attribute that applies to a so-called run of style.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AttributeSet.ColorAttribute

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface AttributeSet.ColorAttribute

All Known Implementing Classes:
StyleConstants.ColorConstants
Enclosing interface:
AttributeSet
public static interface AttributeSet.ColorAttribute

This interface is the type signature that is expected to be present on any attribute key that contributes to presentation of color.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AttributeSet.FontAttribute

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface AttributeSet.FontAttribute

All Known Implementing Classes:
StyleConstants.FontConstants
Enclosing interface:
AttributeSet
public static interface AttributeSet.FontAttribute

This interface is the type signature that is expected to be present on any attribute key that contributes to the determination of what font to use to render some text. This is not considered to be a closed set, the definition can change across version of the platform and can be amended by additional user added entries that correspond to logical settings that are specific to some type of content.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AttributeSet.ParagraphAttribute

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface AttributeSet.ParagraphAttribute

All Known Implementing Classes:
StyleConstants.ParagraphConstants
Enclosing interface:
AttributeSet
public static interface AttributeSet.ParagraphAttribute

This interface is the type signature that is expected to be present on any attribute key that contributes to the paragraph level presentation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


javax.swing.text Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.swing.text

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.swing.AbstractAction (implements javax.swing.Action, java.lang.Cloneable, java.io.Serializable)
      • javax.swing.text.TextAction
        • javax.swing.text.DefaultEditorKit.BeepAction
        • javax.swing.text.DefaultEditorKit.CopyAction
        • javax.swing.text.DefaultEditorKit.CutAction
        • javax.swing.text.DefaultEditorKit.DefaultKeyTypedAction
        • javax.swing.text.DefaultEditorKit.InsertBreakAction
        • javax.swing.text.DefaultEditorKit.InsertContentAction
        • javax.swing.text.DefaultEditorKit.InsertTabAction
        • javax.swing.text.DefaultEditorKit.PasteAction
        • javax.swing.text.StyledEditorKit.StyledTextAction
          • javax.swing.text.StyledEditorKit.AlignmentAction
          • javax.swing.text.StyledEditorKit.BoldAction
          • javax.swing.text.StyledEditorKit.FontFamilyAction
          • javax.swing.text.StyledEditorKit.FontSizeAction
          • javax.swing.text.StyledEditorKit.ForegroundAction
          • javax.swing.text.StyledEditorKit.ItalicAction
          • javax.swing.text.StyledEditorKit.UnderlineAction
    • javax.swing.text.AbstractDocument (implements javax.swing.text.Document, java.io.Serializable)
      • javax.swing.text.DefaultStyledDocument (implements javax.swing.text.StyledDocument)
      • javax.swing.text.PlainDocument
    • javax.swing.text.AbstractDocument.AbstractElement (implements javax.swing.text.Element, javax.swing.text.MutableAttributeSet, java.io.Serializable, javax.swing.tree.TreeNode)
      • javax.swing.text.AbstractDocument.BranchElement
        • javax.swing.text.DefaultStyledDocument.SectionElement
      • javax.swing.text.AbstractDocument.LeafElement
    • javax.swing.undo.AbstractUndoableEdit (implements java.io.Serializable, javax.swing.undo.UndoableEdit)
      • javax.swing.text.AbstractDocument.ElementEdit (implements javax.swing.event.DocumentEvent.ElementChange)
      • javax.swing.undo.CompoundEdit
        • javax.swing.text.AbstractDocument.DefaultDocumentEvent (implements javax.swing.event.DocumentEvent)
      • javax.swing.text.DefaultStyledDocument.AttributeUndoableEdit
    • javax.swing.text.AbstractWriter
    • javax.accessibility.AccessibleContext
      • java.awt.Component.AccessibleAWTComponent (implements javax.accessibility.AccessibleComponent, java.io.Serializable)
        • java.awt.Container.AccessibleAWTContainer
          • javax.swing.JComponent.AccessibleJComponent (implements javax.accessibility.AccessibleExtendedComponent)
            • javax.swing.text.JTextComponent.AccessibleJTextComponent (implements javax.accessibility.AccessibleAction, javax.accessibility.AccessibleEditableText, javax.accessibility.AccessibleExtendedText, javax.accessibility.AccessibleText, javax.swing.event.CaretListener, javax.swing.event.DocumentListener)
    • javax.swing.text.AsyncBoxView.ChildLocator
    • javax.swing.text.AsyncBoxView.ChildState (implements java.lang.Runnable)
    • java.awt.Component (implements java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable)
      • java.awt.Container
        • javax.swing.JComponent (implements java.io.Serializable)
          • javax.swing.text.JTextComponent (implements javax.accessibility.Accessible, javax.swing.Scrollable)
    • javax.swing.plaf.ComponentUI
      • javax.swing.plaf.TextUI
        • javax.swing.plaf.basic.BasicTextUI (implements javax.swing.text.ViewFactory)
          • javax.swing.text.DefaultTextUI
    • javax.swing.text.DefaultStyledDocument.ElementBuffer (implements java.io.Serializable)
    • javax.swing.text.DefaultStyledDocument.ElementSpec
    • javax.swing.text.DocumentFilter
    • javax.swing.text.DocumentFilter.FilterBypass
    • javax.swing.text.EditorKit (implements java.lang.Cloneable, java.io.Serializable)
      • javax.swing.text.DefaultEditorKit
        • javax.swing.text.StyledEditorKit
    • javax.swing.text.ElementIterator (implements java.lang.Cloneable)
    • javax.swing.text.FlowView.FlowStrategy
    • javax.swing.text.GapContent (implements javax.swing.text.AbstractDocument.Content, java.io.Serializable)
    • javax.swing.text.GlyphView.GlyphPainter
    • javax.swing.JFormattedTextField.AbstractFormatter (implements java.io.Serializable)
      • javax.swing.text.DefaultFormatter (implements java.lang.Cloneable, java.io.Serializable)
        • javax.swing.text.InternationalFormatter
          • javax.swing.text.DateFormatter
          • javax.swing.text.NumberFormatter
        • javax.swing.text.MaskFormatter
    • javax.swing.JFormattedTextField.AbstractFormatterFactory
      • javax.swing.text.DefaultFormatterFactory (implements java.io.Serializable)
    • javax.swing.text.JTextComponent.KeyBinding
    • javax.swing.text.LayeredHighlighter (implements javax.swing.text.Highlighter)
      • javax.swing.text.DefaultHighlighter
    • javax.swing.text.LayeredHighlighter.LayerPainter (implements javax.swing.text.Highlighter.HighlightPainter)
      • javax.swing.text.DefaultHighlighter.DefaultHighlightPainter
    • javax.swing.text.LayoutQueue
    • javax.swing.text.NavigationFilter
    • javax.swing.text.NavigationFilter.FilterBypass
    • javax.swing.text.Position.Bias
    • java.awt.geom.RectangularShape (implements java.lang.Cloneable, java.awt.Shape)
      • java.awt.geom.Rectangle2D
        • java.awt.Rectangle (implements java.io.Serializable, java.awt.Shape)
          • javax.swing.text.DefaultCaret (implements javax.swing.text.Caret, java.awt.event.FocusListener, java.awt.event.MouseListener, java.awt.event.MouseMotionListener)
    • javax.swing.text.Segment (implements java.text.CharacterIterator, java.lang.CharSequence, java.lang.Cloneable)
    • javax.swing.text.SimpleAttributeSet (implements java.lang.Cloneable, javax.swing.text.MutableAttributeSet, java.io.Serializable)
    • javax.swing.text.StringContent (implements javax.swing.text.AbstractDocument.Content, java.io.Serializable)
    • javax.swing.text.StyleConstants
      • javax.swing.text.StyleConstants.CharacterConstants (implements javax.swing.text.AttributeSet.CharacterAttribute)
      • javax.swing.text.StyleConstants.ColorConstants (implements javax.swing.text.AttributeSet.CharacterAttribute, javax.swing.text.AttributeSet.ColorAttribute)
      • javax.swing.text.StyleConstants.FontConstants (implements javax.swing.text.AttributeSet.CharacterAttribute, javax.swing.text.AttributeSet.FontAttribute)
      • javax.swing.text.StyleConstants.ParagraphConstants (implements javax.swing.text.AttributeSet.ParagraphAttribute)
    • javax.swing.text.StyleContext (implements javax.swing.text.AbstractDocument.AttributeContext, java.io.Serializable)
    • javax.swing.text.StyleContext.NamedStyle (implements java.io.Serializable, javax.swing.text.Style)
    • javax.swing.text.StyleContext.SmallAttributeSet (implements javax.swing.text.AttributeSet)
    • javax.swing.text.TabSet (implements java.io.Serializable)
    • javax.swing.text.TabStop (implements java.io.Serializable)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.swing.text.BadLocationException
        • java.io.IOException
          • javax.swing.text.ChangedCharSetException
    • javax.swing.TransferHandler.DropLocation
      • javax.swing.text.JTextComponent.DropLocation
    • javax.swing.text.Utilities
    • javax.swing.text.View (implements javax.swing.SwingConstants)
      • javax.swing.text.AsyncBoxView
      • javax.swing.text.ComponentView
      • javax.swing.text.CompositeView
        • javax.swing.text.BoxView
          • javax.swing.text.FlowView
            • javax.swing.text.ParagraphView (implements javax.swing.text.TabExpander)
          • javax.swing.text.TableView
          • javax.swing.text.TableView.TableCell
          • javax.swing.text.TableView.TableRow
          • javax.swing.text.WrappedPlainView (implements javax.swing.text.TabExpander)
          • javax.swing.text.ZoneView
      • javax.swing.text.GlyphView (implements java.lang.Cloneable, javax.swing.text.TabableView)
        • javax.swing.text.LabelView (implements javax.swing.text.TabableView)
      • javax.swing.text.IconView
      • javax.swing.text.PlainView (implements javax.swing.text.TabExpander)
        • javax.swing.text.FieldView
          • javax.swing.text.PasswordView

Interface Hierarchy

  • javax.swing.text.AbstractDocument.AttributeContext
  • javax.swing.text.AbstractDocument.Content
  • javax.swing.text.AttributeSet
    • javax.swing.text.MutableAttributeSet
      • javax.swing.text.Style
  • javax.swing.text.AttributeSet.CharacterAttribute
  • javax.swing.text.AttributeSet.ColorAttribute
  • javax.swing.text.AttributeSet.FontAttribute
  • javax.swing.text.AttributeSet.ParagraphAttribute
  • javax.swing.text.Caret
  • javax.swing.text.Document
    • javax.swing.text.StyledDocument
  • javax.swing.text.Element
  • javax.swing.text.Highlighter
  • javax.swing.text.Highlighter.Highlight
  • javax.swing.text.Highlighter.HighlightPainter
  • javax.swing.text.Keymap
  • javax.swing.text.Position
  • javax.swing.text.TabableView
  • javax.swing.text.TabExpander
  • javax.swing.text.ViewFactory
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.swing.text

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.swing.text

Packages that use javax.swing.text
java.awt | Contains all of the classes for creating user interfaces and for painting graphics and images.
javax.accessibility | Defines a contract between user-interface components and an assistive technology that provides access to those components.
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.
javax.swing.text.html.parser | Provides the default HTML parser, along with support classes.
javax.swing.text.rtf | Provides a class (RTFEditorKit) for creating Rich-Text-Format text editors.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Classes in javax.swing.text used by java.awt
AttributeSet
A collection of unique attributes.

Classes in javax.swing.text used by javax.accessibility
AttributeSet
A collection of unique attributes.

Classes in javax.swing.text used by javax.swing
AttributeSet
A collection of unique attributes.
BadLocationException
This exception is to report bad locations within a document model (that is, attempts to reference a location that doesn't exist).
Document
The Document is a container for text that serves as the model for swing text components.
DocumentFilter
DocumentFilter, as the name implies, is a filter for the Document mutation methods.
EditorKit
Establishes the set of things needed by a text component to be a reasonably functioning editor for some type of text content.
Element
Interface to describe a structural piece of a document.
JTextComponent
JTextComponent is the base class for swing text components.
JTextComponent.AccessibleJTextComponent
This class implements accessibility support for the JTextComponent class.
JTextComponent.KeyBinding
Binding record for creating key bindings.
MutableAttributeSet
A generic interface for a mutable collection of unique attributes.
NavigationFilter
NavigationFilter can be used to restrict where the cursor can be positioned.
Position.Bias
A typesafe enumeration to indicate bias to a position in the model.
Style
A collection of attributes to associate with an element in a document.
StyledDocument
Interface for a generic styled document.
StyledEditorKit
This is the set of things needed by a text component to be a reasonably functioning editor for some type of text document.

Classes in javax.swing.text used by javax.swing.event
Document
The Document is a container for text that serves as the model for swing text components.
Element
Interface to describe a structural piece of a document.

Classes in javax.swing.text used by javax.swing.plaf
BadLocationException
This exception is to report bad locations within a document model (that is, attempts to reference a location that doesn't exist).
EditorKit
Establishes the set of things needed by a text component to be a reasonably functioning editor for some type of text content.
JTextComponent
JTextComponent is the base class for swing text components.
Position.Bias
A typesafe enumeration to indicate bias to a position in the model.
View
A very important part of the text package is the View class.

Classes in javax.swing.text used by javax.swing.plaf.basic
BadLocationException
This exception is to report bad locations within a document model (that is, attempts to reference a location that doesn't exist).
Caret
A place within a document view that represents where things can be inserted into the document model.
DefaultCaret
A default implementation of Caret.
DefaultHighlighter
Implements the Highlighter interfaces.
EditorKit
Establishes the set of things needed by a text component to be a reasonably functioning editor for some type of text content.
Element
Interface to describe a structural piece of a document.
Highlighter
An interface for an object that allows one to mark up the background with colored areas.
JTextComponent
JTextComponent is the base class for swing text components.
Keymap
A collection of bindings of KeyStrokes to actions.
LayeredHighlighter
Position.Bias
A typesafe enumeration to indicate bias to a position in the model.
View
A very important part of the text package is the View class.
ViewFactory
A factory to create a view of some portion of document subject.

Classes in javax.swing.text used by javax.swing.plaf.metal
ViewFactory
A factory to create a view of some portion of document subject.

Classes in javax.swing.text used by javax.swing.plaf.multi
BadLocationException
This exception is to report bad locations within a document model (that is, attempts to reference a location that doesn't exist).
EditorKit
Establishes the set of things needed by a text component to be a reasonably functioning editor for some type of text content.
JTextComponent
JTextComponent is the base class for swing text components.
Position.Bias
A typesafe enumeration to indicate bias to a position in the model.
View
A very important part of the text package is the View class.

Classes in javax.swing.text used by javax.swing.text
AbstractDocument
An implementation of the document interface to serve as a basis for implementing various kinds of documents.
AbstractDocument.AbstractElement
Implements the abstract part of an element.
AbstractDocument.AttributeContext
An interface that can be used to allow MutableAttributeSet implementations to use pluggable attribute compression techniques.
AbstractDocument.BranchElement
Implements a composite element that contains other elements.
AbstractDocument.Content
Interface to describe a sequence of character content that can be edited.
AbstractDocument.DefaultDocumentEvent
Stores document changes as the document is being modified.
AsyncBoxView.ChildLocator
A class to manage the effective position of the child views in a localized area while changes are being made around the localized area.
AsyncBoxView.ChildState
A record representing the layout state of a child view.
AttributeSet
A collection of unique attributes.
AttributeSet.CharacterAttribute
This interface is the type signature that is expected to be present on any attribute key that contributes to character level presentation.
AttributeSet.ColorAttribute
This interface is the type signature that is expected to be present on any attribute key that contributes to presentation of color.
AttributeSet.FontAttribute
This interface is the type signature that is expected to be present on any attribute key that contributes to the determination of what font to use to render some text.
AttributeSet.ParagraphAttribute
This interface is the type signature that is expected to be present on any attribute key that contributes to the paragraph level presentation.
BadLocationException
This exception is to report bad locations within a document model (that is, attempts to reference a location that doesn't exist).
BoxView
A view that arranges its children into a box shape by tiling its children along an axis.
Caret
A place within a document view that represents where things can be inserted into the document model.
CompositeView
CompositeView is an abstract View implementation which manages one or more child views.
DefaultEditorKit
This is the set of things needed by a text component to be a reasonably functioning editor for some type of text document.
DefaultFormatter
DefaultFormatter formats aribtrary objects.
DefaultStyledDocument.ElementBuffer
Class to manage changes to the element hierarchy.
DefaultStyledDocument.ElementSpec
Specification for building elements.
Document
The Document is a container for text that serves as the model for swing text components.
DocumentFilter
DocumentFilter, as the name implies, is a filter for the Document mutation methods.
DocumentFilter.FilterBypass
Used as a way to circumvent calling back into the Document to change it.
EditorKit
Establishes the set of things needed by a text component to be a reasonably functioning editor for some type of text content.
Element
Interface to describe a structural piece of a document.
ElementIterator
ElementIterator, as the name suggests, iteratates over the Element tree.
FieldView
Extends the multi-line plain text view to be suitable for a single-line editor view.
FlowView
A View that tries to flow it's children into some partially constrained space.
FlowView.FlowStrategy
Strategy for maintaining the physical form of the flow.
GlyphView
A GlyphView is a styled chunk of text that represents a view mapped over an element in the text model.
GlyphView.GlyphPainter
A class to perform rendering of the glyphs.
Highlighter
An interface for an object that allows one to mark up the background with colored areas.
Highlighter.Highlight
Highlighter.HighlightPainter
Highlight renderer.
InternationalFormatter
InternationalFormatter extends DefaultFormatter, using an instance of java.text.Format to handle the conversion to a String, and the conversion from a String.
JTextComponent
JTextComponent is the base class for swing text components.
JTextComponent.DropLocation
Represents a drop location for JTextComponents.
JTextComponent.KeyBinding
Binding record for creating key bindings.
Keymap
A collection of bindings of KeyStrokes to actions.
LayeredHighlighter
LayeredHighlighter.LayerPainter
Layered highlight renderer.
LayoutQueue
A queue of text layout tasks.
MutableAttributeSet
A generic interface for a mutable collection of unique attributes.
NavigationFilter
NavigationFilter can be used to restrict where the cursor can be positioned.
NavigationFilter.FilterBypass
Used as a way to circumvent calling back into the caret to position the cursor.
PlainView
Implements View interface for a simple multi-line text view that has text in one font and color.
Position
Represents a location within a document.
Position.Bias
A typesafe enumeration to indicate bias to a position in the model.
Segment
A segment of a character array representing a fragment of text.
Style
A collection of attributes to associate with an element in a document.
StyleConstants
A collection of well known or common attribute keys and methods to apply to an AttributeSet or MutableAttributeSet to get/set the properties in a typesafe manner.
StyleContext
A pool of styles and their associated resources.
StyleContext.SmallAttributeSet
This class holds a small number of attributes in an array.
StyledDocument
Interface for a generic styled document.
StyledEditorKit
This is the set of things needed by a text component to be a reasonably functioning editor for some type of text document.
StyledEditorKit.StyledTextAction
An action that assumes it's being fired on a JEditorPane with a StyledEditorKit (or subclass) installed.
TabableView
Interface for Views that have size dependent upon tabs.
TabExpander
Simple interface to allow for different types of implementations of tab expansion.
TableView.TableCell
Deprecated. A table cell can now be any View implementation.
TableView.TableRow
View of a row in a row-centric table.
TabSet
A TabSet is comprised of many TabStops.
TabStop
This class encapsulates a single tab stop (basically as tab stops are thought of by RTF).
TextAction
An Action implementation useful for key bindings that are shared across a number of different text components.
View
A very important part of the text package is the View class.
ViewFactory
A factory to create a view of some portion of document subject.

Classes in javax.swing.text used by javax.swing.text.html
AbstractDocument
An implementation of the document interface to serve as a basis for implementing various kinds of documents.
AbstractDocument.AbstractElement
Implements the abstract part of an element.
AbstractDocument.AttributeContext
An interface that can be used to allow MutableAttributeSet implementations to use pluggable attribute compression techniques.
AbstractDocument.BranchElement
Implements a composite element that contains other elements.
AbstractDocument.Content
Interface to describe a sequence of character content that can be edited.
AbstractDocument.DefaultDocumentEvent
Stores document changes as the document is being modified.
AbstractDocument.LeafElement
Implements an element that directly represents content of some kind.
AbstractWriter
AbstractWriter is an abstract class that actually does the work of writing out the element tree including the attributes.
AttributeSet
A collection of unique attributes.
BadLocationException
This exception is to report bad locations within a document model (that is, attempts to reference a location that doesn't exist).
BoxView
A view that arranges its children into a box shape by tiling its children along an axis.
ComponentView
Component decorator that implements the view interface.
CompositeView
CompositeView is an abstract View implementation which manages one or more child views.
DefaultEditorKit
This is the set of things needed by a text component to be a reasonably functioning editor for some type of text document.
DefaultStyledDocument
A document that can be marked up with character and paragraph styles in a manner similar to the Rich Text Format.
DefaultStyledDocument.ElementSpec
Specification for building elements.
Document
The Document is a container for text that serves as the model for swing text components.
EditorKit
Establishes the set of things needed by a text component to be a reasonably functioning editor for some type of text content.
Element
Interface to describe a structural piece of a document.
GlyphView
A GlyphView is a styled chunk of text that represents a view mapped over an element in the text model.
LabelView
A LabelView is a styled chunk of text that represents a view mapped over an element in the text model.
MutableAttributeSet
A generic interface for a mutable collection of unique attributes.
ParagraphView
View of a simple line-wrapping paragraph that supports multiple fonts, colors, components, icons, etc.
Position.Bias
A typesafe enumeration to indicate bias to a position in the model.
Style
A collection of attributes to associate with an element in a document.
StyleContext
A pool of styles and their associated resources.
StyleContext.SmallAttributeSet
This class holds a small number of attributes in an array.
StyledDocument
Interface for a generic styled document.
StyledEditorKit
This is the set of things needed by a text component to be a reasonably functioning editor for some type of text document.
StyledEditorKit.StyledTextAction
An action that assumes it's being fired on a JEditorPane with a StyledEditorKit (or subclass) installed.
TabableView
Interface for Views that have size dependent upon tabs.
TextAction
An Action implementation useful for key bindings that are shared across a number of different text components.
View
A very important part of the text package is the View class.
ViewFactory
A factory to create a view of some portion of document subject.

Classes in javax.swing.text used by javax.swing.text.html.parser
ChangedCharSetException
ChangedCharSetException as the name indicates is an exception thrown when the charset is changed.
SimpleAttributeSet
A straightforward implementation of MutableAttributeSet using a hash table.

Classes in javax.swing.text used by javax.swing.text.rtf
BadLocationException
This exception is to report bad locations within a document model (that is, attempts to reference a location that doesn't exist).
DefaultEditorKit
This is the set of things needed by a text component to be a reasonably functioning editor for some type of text document.
Document
The Document is a container for text that serves as the model for swing text components.
EditorKit
Establishes the set of things needed by a text component to be a reasonably functioning editor for some type of text content.
StyledEditorKit
This is the set of things needed by a text component to be a reasonably functioning editor for some type of text document.

Classes in javax.swing.text used by javax.swing.tree
JTextComponent
JTextComponent is the base class for swing text components.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AbstractDocument

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class AbstractDocument

java.lang.Object
    extended by  javax.swing.text.AbstractDocument
All Implemented Interfaces:
Serializable, Document
Direct Known Subclasses:
DefaultStyledDocument, PlainDocument
public abstract class AbstractDocument
extends Object
implements Document, Serializable

An implementation of the document interface to serve as a basis for implementing various kinds of documents. At this level there is very little policy, so there is a corresponding increase in difficulty of use.

This class implements a locking mechanism for the document. It allows multiple readers or one writer, and writers must wait until all observers of the document have been notified of a previous change before beginning another mutation to the document. The read lock is acquired and released using the render method. A write lock is aquired by the methods that mutate the document, and are held for the duration of the method call. Notification is done on the thread that produced the mutation, and the thread has full read access to the document for the duration of the notification, but other readers are kept out until the notification has finished. The notification is a beans event notification which does not allow any further mutations until all listeners have been notified.

Any models subclassed from this class and used in conjunction with a text component that has a look and feel implementation that is derived from BasicTextUI may be safely updated asynchronously, because all access to the View hierarchy is serialized by BasicTextUI if the document is of type AbstractDocument. The locking assumes that an independent thread will access the View hierarchy only from the DocumentListener methods, and that there will be only one event thread active at a time.

If concurrency support is desired, there are the following additional implications. The code path for any DocumentListener implementation and any UndoListener implementation must be threadsafe, and not access the component lock if trying to be safe from deadlocks. The repaint and revalidate methods on JComponent are safe.

AbstractDocument models an implied break at the end of the document. Among other things this allows you to position the caret after the last character. As a result of this, getLength returns one less than the length of the Content. If you create your own Content, be sure and initialize it to have an additional character. Refer to StringContent and GapContent for examples of this. Another implication of this is that Elements that model the implied end character will have an endOffset == (getLength() + 1). For example, in DefaultStyledDocument getParagraphElement(getLength()).getEndOffset() == getLength() + 1 .

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
class | AbstractDocument.AbstractElement Implements the abstract part of an element.
static interface | AbstractDocument.AttributeContext An interface that can be used to allow MutableAttributeSet implementations to use pluggable attribute compression techniques.
class | AbstractDocument.BranchElement Implements a composite element that contains other elements.
static interface | AbstractDocument.Content Interface to describe a sequence of character content that can be edited.
class | AbstractDocument.DefaultDocumentEvent Stores document changes as the document is being modified.
static class | AbstractDocument.ElementEdit An implementation of ElementChange that can be added to the document event.
class | AbstractDocument.LeafElement Implements an element that directly represents content of some kind.
Field Summary
protected static String | BAD_LOCATION Error message to indicate a bad location.
static String | BidiElementName Name of elements used to hold a unidirectional run
static String | ContentElementName Name of elements used to represent content
static String | ElementNameAttribute Name of the attribute used to specify element names.
protected EventListenerList | listenerList The event listener list for the document.
static String | ParagraphElementName Name of elements used to represent paragraphs
static String | SectionElementName Name of elements used to hold sections (lines/paragraphs).
Fields inherited from interface javax.swing.text.Document
StreamDescriptionProperty, TitleProperty
Constructor Summary
protected | AbstractDocument(AbstractDocument.Content data) Constructs a new AbstractDocument, wrapped around some specified content storage mechanism.
protected | AbstractDocument(AbstractDocument.Content data, AbstractDocument.AttributeContext context) Constructs a new AbstractDocument, wrapped around some specified content storage mechanism.
Method Summary
 void addDocumentListener(DocumentListener listener)
Adds a document listener for notification of any changes.
 void addUndoableEditListener(UndoableEditListener listener)
Adds an undo listener for notification of any changes.
protected  Element createBranchElement(Element parent, AttributeSet a)
Creates a document branch element, that can contain other elements.
protected  Element createLeafElement(Element parent, AttributeSet a, int p0, int p1)
Creates a document leaf element.
 Position createPosition(int offs)
Returns a position that will track change as the document is altered.
 void dump(PrintStream out)
Gives a diagnostic dump.
protected  void fireChangedUpdate(DocumentEvent e)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireInsertUpdate(DocumentEvent e)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireRemoveUpdate(DocumentEvent e)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireUndoableEditUpdate(UndoableEditEvent e)
Notifies all listeners that have registered interest for notification on this event type.
 int getAsynchronousLoadPriority()
Gets the asynchronous loading priority.
protected  AbstractDocument.AttributeContext getAttributeContext()
Fetches the context for managing attributes.
 Element getBidiRootElement()
Returns the root element of the bidirectional structure for this document.
protected  AbstractDocument.Content getContent()
Gets the content for the document.
protected  Thread getCurrentWriter()
Fetches the current writing thread if there is one.
abstract  Element getDefaultRootElement()
Returns the root element that views should be based upon unless some other mechanism for assigning views to element structures is provided.
 DocumentFilter getDocumentFilter()
Returns the DocumentFilter that is responsible for filtering of insertion/removal.
 DocumentListener[] getDocumentListeners()
Returns an array of all the document listeners registered on this document.
 Dictionary<Object,Object> getDocumentProperties()
Supports managing a set of properties.
 Position getEndPosition()
Returns a position that represents the end of the document.
 int getLength()
Returns the length of the data.
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this document.
abstract  Element getParagraphElement(int pos)
Get the paragraph element containing the given position.
 Object getProperty(Object key)
A convenience method for looking up a property value.
 Element[] getRootElements()
Gets all root elements defined.
 Position getStartPosition()
Returns a position that represents the start of the document.
 String getText(int offset, int length)
Gets a sequence of text from the document.
 void getText(int offset, int length, Segment txt)
Fetches the text contained within the given portion of the document.
 UndoableEditListener[] getUndoableEditListeners()
Returns an array of all the undoable edit listeners registered on this document.
 void insertString(int offs, String str, AttributeSet a)
Inserts some content into the document.
protected  void insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr)
Updates document structure as a result of text insertion.
protected  void postRemoveUpdate(AbstractDocument.DefaultDocumentEvent chng)
Updates any document structure as a result of text removal.
 void putProperty(Object key, Object value)
A convenience method for storing up a property value.
 void readLock()
Acquires a lock to begin reading some state from the document.
 void readUnlock()
Does a read unlock.
 void remove(int offs, int len)
Removes some content from the document.
 void removeDocumentListener(DocumentListener listener)
Removes a document listener.
 void removeUndoableEditListener(UndoableEditListener listener)
Removes an undo listener.
protected  void removeUpdate(AbstractDocument.DefaultDocumentEvent chng)
Updates any document structure as a result of text removal.
 void render(Runnable r)
This allows the model to be safely rendered in the presence of currency, if the model supports being updated asynchronously.
 void replace(int offset, int length, String text, AttributeSet attrs)
Deletes the region of text from offset to offset + length, and replaces it with text.
 void setAsynchronousLoadPriority(int p)
Sets the asynchronous loading priority.
 void setDocumentFilter(DocumentFilter filter)
Sets the DocumentFilter.
 void setDocumentProperties(Dictionary<Object,Object> x)
Replaces the document properties dictionary for this document.
protected  void writeLock()
Acquires a lock to begin mutating the document this lock protects.
protected  void writeUnlock()
Releases a write lock previously obtained via writeLock.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

listenerList

protected EventListenerList listenerList
The event listener list for the document.

BAD_LOCATION

protected static final String BAD_LOCATION
Error message to indicate a bad location.

See Also:
Constant Field Values

ParagraphElementName

public static final String ParagraphElementName
Name of elements used to represent paragraphs

See Also:
Constant Field Values

ContentElementName

public static final String ContentElementName
Name of elements used to represent content

See Also:
Constant Field Values

SectionElementName

public static final String SectionElementName
Name of elements used to hold sections (lines/paragraphs).

See Also:
Constant Field Values

BidiElementName

public static final String BidiElementName
Name of elements used to hold a unidirectional run

See Also:
Constant Field Values

ElementNameAttribute

public static final String ElementNameAttribute
Name of the attribute used to specify element names.

See Also:
Constant Field Values
Constructor Detail

AbstractDocument

protected AbstractDocument(AbstractDocument.Content data)
Constructs a new AbstractDocument, wrapped around some specified content storage mechanism.

Parameters:
data - the content

AbstractDocument

protected AbstractDocument(AbstractDocument.Content data,
                           AbstractDocument.AttributeContext context)
Constructs a new AbstractDocument, wrapped around some specified content storage mechanism.

Parameters:
data - the content
context - the attribute context
Method Detail

getDocumentProperties

public Dictionary<Object,Object> getDocumentProperties()
Supports managing a set of properties. Callers can use the documentProperties dictionary to annotate the document with document-wide properties.

Returns:
a non-null Dictionary
See Also:
setDocumentProperties(java.util.Dictionary)

setDocumentProperties

public void setDocumentProperties(Dictionary<Object,Object> x)
Replaces the document properties dictionary for this document.

Parameters:
x - the new dictionary
See Also:
getDocumentProperties()

fireInsertUpdate

protected void fireInsertUpdate(DocumentEvent e)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

Parameters:
e - the event
See Also:
EventListenerList

fireChangedUpdate

protected void fireChangedUpdate(DocumentEvent e)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

Parameters:
e - the event
See Also:
EventListenerList

fireRemoveUpdate

protected void fireRemoveUpdate(DocumentEvent e)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

Parameters:
e - the event
See Also:
EventListenerList

fireUndoableEditUpdate

protected void fireUndoableEditUpdate(UndoableEditEvent e)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

Parameters:
e - the event
See Also:
EventListenerList

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this document. FooListeners are registered using the addFooListener method.

You can specify the listenerType argument with a class literal, such as FooListener.class. For example, you can query a document d for its document listeners with the following code:

DocumentListener[] mls = (DocumentListener[])(d.getListeners(DocumentListener.class));
If no such listeners exist, this method returns an empty array.

Parameters:
listenerType - the type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener
Returns:
an array of all objects registered as FooListeners on this component, or an empty array if no such listeners have been added
Throws:
ClassCastException - if listenerType doesn't specify a class or interface that implements java.util.EventListener
Since:
1.3
See Also:
getDocumentListeners(), getUndoableEditListeners()

getAsynchronousLoadPriority

public int getAsynchronousLoadPriority()
Gets the asynchronous loading priority. If less than zero, the document should not be loaded asynchronously.

Returns:
the asynchronous loading priority, or -1 if the document should not be loaded asynchronously

setAsynchronousLoadPriority

public void setAsynchronousLoadPriority(int p)
Sets the asynchronous loading priority.

Parameters:
p - the new asynchronous loading priority; a value less than zero indicates that the document should not be loaded asynchronously

setDocumentFilter

public void setDocumentFilter(DocumentFilter filter)
Sets the DocumentFilter. The DocumentFilter is passed insert and remove to conditionally allow inserting/deleting of the text. A null value indicates that no filtering will occur.

Parameters:
filter - the DocumentFilter used to constrain text
Since:
1.4
See Also:
getDocumentFilter()

getDocumentFilter

public DocumentFilter getDocumentFilter()
Returns the DocumentFilter that is responsible for filtering of insertion/removal. A null return value implies no filtering is to occur.

Returns:
the DocumentFilter
Since:
1.4
See Also:
setDocumentFilter(javax.swing.text.DocumentFilter)

render

public void render(Runnable r)
This allows the model to be safely rendered in the presence of currency, if the model supports being updated asynchronously. The given runnable will be executed in a way that allows it to safely read the model with no changes while the runnable is being executed. The runnable itself may not make any mutations.

This is implemented to aquire a read lock for the duration of the runnables execution. There may be multiple runnables executing at the same time, and all writers will be blocked while there are active rendering runnables. If the runnable throws an exception, its lock will be safely released. There is no protection against a runnable that never exits, which will effectively leave the document locked for it's lifetime.

If the given runnable attempts to make any mutations in this implementation, a deadlock will occur. There is no tracking of individual rendering threads to enable detecting this situation, but a subclass could incur the overhead of tracking them and throwing an error.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Specified by:
render in interface Document
Parameters:
r - the renderer to execute

getLength

public int getLength()
Returns the length of the data. This is the number of characters of content that represents the users data.

Specified by:
getLength in interface Document
Returns:
the length >= 0
See Also:
Document.getLength()

addDocumentListener

public void addDocumentListener(DocumentListener listener)
Adds a document listener for notification of any changes.

Specified by:
addDocumentListener in interface Document
Parameters:
listener - the DocumentListener to add
See Also:
Document.addDocumentListener(javax.swing.event.DocumentListener)

removeDocumentListener

public void removeDocumentListener(DocumentListener listener)
Removes a document listener.

Specified by:
removeDocumentListener in interface Document
Parameters:
listener - the DocumentListener to remove
See Also:
Document.removeDocumentListener(javax.swing.event.DocumentListener)

getDocumentListeners

public DocumentListener[] getDocumentListeners()
Returns an array of all the document listeners registered on this document.

Returns:
all of this document's DocumentListeners or an empty array if no document listeners are currently registered
Since:
1.4
See Also:
addDocumentListener(javax.swing.event.DocumentListener), removeDocumentListener(javax.swing.event.DocumentListener)

addUndoableEditListener

public void addUndoableEditListener(UndoableEditListener listener)
Adds an undo listener for notification of any changes. Undo/Redo operations performed on the UndoableEdit will cause the appropriate DocumentEvent to be fired to keep the view(s) in sync with the model.

Specified by:
addUndoableEditListener in interface Document
Parameters:
listener - the UndoableEditListener to add
See Also:
Document.addUndoableEditListener(javax.swing.event.UndoableEditListener)

removeUndoableEditListener

public void removeUndoableEditListener(UndoableEditListener listener)
Removes an undo listener.

Specified by:
removeUndoableEditListener in interface Document
Parameters:
listener - the UndoableEditListener to remove
See Also:
Document.removeDocumentListener(javax.swing.event.DocumentListener)

getUndoableEditListeners

public UndoableEditListener[] getUndoableEditListeners()
Returns an array of all the undoable edit listeners registered on this document.

Returns:
all of this document's UndoableEditListeners or an empty array if no undoable edit listeners are currently registered
Since:
1.4
See Also:
addUndoableEditListener(javax.swing.event.UndoableEditListener), removeUndoableEditListener(javax.swing.event.UndoableEditListener)

getProperty

public final Object getProperty(Object key)
A convenience method for looking up a property value. It is equivalent to:
 getDocumentProperties().get(key);

Specified by:
getProperty in interface Document
Parameters:
key - the non-null property key
Returns:
the value of this property or null
See Also:
getDocumentProperties()

putProperty

public final void putProperty(Object key,
                              Object value)
A convenience method for storing up a property value. It is equivalent to:
 getDocumentProperties().put(key, value);
If value is null this method will remove the property.

Specified by:
putProperty in interface Document
Parameters:
key - the non-null key
value - the property value
See Also:
getDocumentProperties()

remove

public void remove(int offs,
                   int len)
            throws BadLocationException
Removes some content from the document. Removing content causes a write lock to be held while the actual changes are taking place. Observers are notified of the change on the thread that called this method.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Specified by:
remove in interface Document
Parameters:
offs - the starting offset >= 0
len - the number of characters to remove >= 0
Throws:
BadLocationException - the given remove position is not a valid position within the document
See Also:
Document.remove(int, int)

replace

public void replace(int offset,
                    int length,
                    String text,
                    AttributeSet attrs)
             throws BadLocationException
Deletes the region of text from offset to offset + length, and replaces it with text. It is up to the implementation as to how this is implemented, some implementations may treat this as two distinct operations: a remove followed by an insert, others may treat the replace as one atomic operation.

Parameters:
offset - index of child element
length - length of text to delete, may be 0 indicating don't delete anything
text - text to insert, null indicates no text to insert
attrs - AttributeSet indicating attributes of inserted text, null is legal, and typically treated as an empty attributeset, but exact interpretation is left to the subclass
Throws:
BadLocationException - the given position is not a valid position within the document
Since:
1.4

insertString

public void insertString(int offs,
                         String str,
                         AttributeSet a)
                  throws BadLocationException
Inserts some content into the document. Inserting content causes a write lock to be held while the actual changes are taking place, followed by notification to the observers on the thread that grabbed the write lock.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Specified by:
insertString in interface Document
Parameters:
offs - the starting offset >= 0
str - the string to insert; does nothing with null/empty strings
a - the attributes for the inserted content
Throws:
BadLocationException - the given insert position is not a valid position within the document
See Also:
Document.insertString(int, java.lang.String, javax.swing.text.AttributeSet)

getText

public String getText(int offset,
                      int length)
               throws BadLocationException
Gets a sequence of text from the document.

Specified by:
getText in interface Document
Parameters:
offset - the starting offset >= 0
length - the number of characters to retrieve >= 0
Returns:
the text
Throws:
BadLocationException - the range given includes a position that is not a valid position within the document
See Also:
Document.getText(int, int)

getText

public void getText(int offset,
                    int length,
                    Segment txt)
             throws BadLocationException
Fetches the text contained within the given portion of the document.

If the partialReturn property on the txt parameter is false, the data returned in the Segment will be the entire length requested and may or may not be a copy depending upon how the data was stored. If the partialReturn property is true, only the amount of text that can be returned without creating a copy is returned. Using partial returns will give better performance for situations where large parts of the document are being scanned. The following is an example of using the partial return to access the entire document:

   int nleft = doc.getDocumentLength();
   Segment text = new Segment();
   int offs = 0;
   text.setPartialReturn(true);
   while (nleft > 0) {
       doc.getText(offs, nleft, text);
       // do something with text
       nleft -= text.count;
       offs += text.count;
   }

Specified by:
getText in interface Document
Parameters:
offset - the starting offset >= 0
length - the number of characters to retrieve >= 0
txt - the Segment object to retrieve the text into
Throws:
BadLocationException - the range given includes a position that is not a valid position within the document

createPosition

public Position createPosition(int offs)
                        throws BadLocationException
Returns a position that will track change as the document is altered.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Specified by:
createPosition in interface Document
Parameters:
offs - the position in the model >= 0
Returns:
the position
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
See Also:
Document.createPosition(int)

getStartPosition

public final Position getStartPosition()
Returns a position that represents the start of the document. The position returned can be counted on to track change and stay located at the beginning of the document.

Specified by:
getStartPosition in interface Document
Returns:
the position

getEndPosition

public final Position getEndPosition()
Returns a position that represents the end of the document. The position returned can be counted on to track change and stay located at the end of the document.

Specified by:
getEndPosition in interface Document
Returns:
the position

getRootElements

public Element[] getRootElements()
Gets all root elements defined. Typically, there will only be one so the default implementation is to return the default root element.

Specified by:
getRootElements in interface Document
Returns:
the root element

getDefaultRootElement

public abstract Element getDefaultRootElement()
Returns the root element that views should be based upon unless some other mechanism for assigning views to element structures is provided.

Specified by:
getDefaultRootElement in interface Document
Returns:
the root element
See Also:
Document.getDefaultRootElement()

getBidiRootElement

public Element getBidiRootElement()
Returns the root element of the bidirectional structure for this document. Its children represent character runs with a given Unicode bidi level.

getParagraphElement

public abstract Element getParagraphElement(int pos)
Get the paragraph element containing the given position. Sub-classes must define for themselves what exactly constitutes a paragraph. They should keep in mind however that a paragraph should at least be the unit of text over which to run the Unicode bidirectional algorithm.

Parameters:
pos - the starting offset >= 0
Returns:
the element

getAttributeContext

protected final AbstractDocument.AttributeContext getAttributeContext()
Fetches the context for managing attributes. This method effectively establishes the strategy used for compressing AttributeSet information.

Returns:
the context

insertUpdate

protected void insertUpdate(AbstractDocument.DefaultDocumentEvent chng,
                            AttributeSet attr)
Updates document structure as a result of text insertion. This will happen within a write lock. If a subclass of this class reimplements this method, it should delegate to the superclass as well.

Parameters:
chng - a description of the change
attr - the attributes for the change

removeUpdate

protected void removeUpdate(AbstractDocument.DefaultDocumentEvent chng)
Updates any document structure as a result of text removal. This method is called before the text is actually removed from the Content. This will happen within a write lock. If a subclass of this class reimplements this method, it should delegate to the superclass as well.

Parameters:
chng - a description of the change

postRemoveUpdate

protected void postRemoveUpdate(AbstractDocument.DefaultDocumentEvent chng)
Updates any document structure as a result of text removal. This method is called after the text has been removed from the Content. This will happen within a write lock. If a subclass of this class reimplements this method, it should delegate to the superclass as well.

Parameters:
chng - a description of the change

dump

public void dump(PrintStream out)
Gives a diagnostic dump.

Parameters:
out - the output stream

getContent

protected final AbstractDocument.Content getContent()
Gets the content for the document.

Returns:
the content

createLeafElement

protected Element createLeafElement(Element parent,
                                    AttributeSet a,
                                    int p0,
                                    int p1)
Creates a document leaf element. Hook through which elements are created to represent the document structure. Because this implementation keeps structure and content separate, elements grow automatically when content is extended so splits of existing elements follow. The document itself gets to decide how to generate elements to give flexibility in the type of elements used.

Parameters:
parent - the parent element
a - the attributes for the element
p0 - the beginning of the range >= 0
p1 - the end of the range >= p0
Returns:
the new element

createBranchElement

protected Element createBranchElement(Element parent,
                                      AttributeSet a)
Creates a document branch element, that can contain other elements.

Parameters:
parent - the parent element
a - the attributes
Returns:
the element

getCurrentWriter

protected final Thread getCurrentWriter()
Fetches the current writing thread if there is one. This can be used to distinguish whether a method is being called as part of an existing modification or if a lock needs to be acquired and a new transaction started.

Returns:
the thread actively modifying the document or null if there are no modifications in progress

writeLock

protected final void writeLock()
Acquires a lock to begin mutating the document this lock protects. There can be no writing, notification of changes, or reading going on in order to gain the lock. Additionally a thread is allowed to gain more than one writeLock, as long as it doesn't attempt to gain additional writeLocks from within document notification. Attempting to gain a writeLock from within a DocumentListener notification will result in an IllegalStateException. The ability to obtain more than one writeLock per thread allows subclasses to gain a writeLock, perform a number of operations, then release the lock.

Calls to writeLock must be balanced with calls to writeUnlock, else the Document will be left in a locked state so that no reading or writing can be done.

Throws:
IllegalStateException - thrown on illegal lock attempt. If the document is implemented properly, this can only happen if a document listener attempts to mutate the document. This situation violates the bean event model where order of delivery is not guaranteed and all listeners should be notified before further mutations are allowed.

writeUnlock

protected final void writeUnlock()
Releases a write lock previously obtained via writeLock. After decrementing the lock count if there are no oustanding locks this will allow a new writer, or readers.

See Also:
writeLock()

readLock

public final void readLock()
Acquires a lock to begin reading some state from the document. There can be multiple readers at the same time. Writing blocks the readers until notification of the change to the listeners has been completed. This method should be used very carefully to avoid unintended compromise of the document. It should always be balanced with a readUnlock.

See Also:
readUnlock()

readUnlock

public final void readUnlock()
Does a read unlock. This signals that one of the readers is done. If there are no more readers then writing can begin again. This should be balanced with a readLock, and should occur in a finally statement so that the balance is guaranteed. The following is an example.

     readLock();
     try {
         // do something
     } finally {
         readUnlock();
     }

See Also:
readLock()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AbstractDocument.AbstractElement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class AbstractDocument.AbstractElement

java.lang.Object
    extended by  javax.swing.text.AbstractDocument.AbstractElement
All Implemented Interfaces:
Serializable, AttributeSet, Element, MutableAttributeSet, TreeNode
Direct Known Subclasses:
AbstractDocument.BranchElement, AbstractDocument.LeafElement
Enclosing class:
AbstractDocument
public abstract class AbstractDocument.AbstractElement
extends Object
implements Element, MutableAttributeSet, Serializable, TreeNode

Implements the abstract part of an element. By default elements support attributes by having a field that represents the immutable part of the current attribute set for the element. The element itself implements MutableAttributeSet which can be used to modify the set by fetching a new immutable set. The immutable sets are provided by the AttributeContext associated with the document.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from interface javax.swing.text.AttributeSet
AttributeSet.CharacterAttribute, AttributeSet.ColorAttribute, AttributeSet.FontAttribute, AttributeSet.ParagraphAttribute
Field Summary
Fields inherited from interface javax.swing.text.AttributeSet
NameAttribute, ResolveAttribute
Constructor Summary
AbstractDocument.AbstractElement(Element parent, AttributeSet a)
Creates a new AbstractElement.
Method Summary
void | addAttribute(Object name, Object value) Adds an attribute to the element.
void | addAttributes(AttributeSet attr) Adds a set of attributes to the element.
abstract Enumeration | children() Returns the children of the receiver as an Enumeration.
boolean | containsAttribute(Object name, Object value) Checks whether a given attribute name/value is defined.
boolean | containsAttributes(AttributeSet attrs) Checks whether the element contains all the attributes.
AttributeSet | copyAttributes() Copies a set of attributes.
void | dump(PrintStream psOut, int indentAmount) Dumps a debugging representation of the element hierarchy.
abstract boolean | getAllowsChildren() Returns true if the receiver allows children.
Object | getAttribute(Object attrName) Gets the value of an attribute.
int | getAttributeCount() Gets the number of attributes that are defined.
Enumeration<?> | getAttributeNames() Gets the names of all attributes.
AttributeSet | getAttributes() Gets the attributes for the element.
TreeNode | getChildAt(int childIndex) Returns the child TreeNode at index childIndex.
int | getChildCount() Returns the number of children TreeNode's receiver contains.
Document | getDocument() Retrieves the underlying model.
abstract Element | getElement(int index) Gets a child element.
abstract int | getElementCount() Gets the number of children for the element.
abstract int | getElementIndex(int offset) Gets the child element index closest to the given model offset.
abstract int | getEndOffset() Gets the ending offset in the model for the element.
int | getIndex(TreeNode node) Returns the index of node in the receivers children.
String | getName() Gets the name of the element.
TreeNode | getParent() Returns the parent TreeNode of the receiver.
Element | getParentElement() Gets the parent of the element.
AttributeSet | getResolveParent() Gets the resolving parent.
abstract int | getStartOffset() Gets the starting offset in the model for the element.
boolean | isDefined(Object attrName) Checks whether a given attribute is defined.
boolean | isEqual(AttributeSet attr) Checks whether two attribute sets are equal.
abstract boolean | isLeaf() Checks whether the element is a leaf.
void | removeAttribute(Object name) Removes an attribute from the set.
void | removeAttributes(AttributeSet attrs) Removes a set of attributes for the element.
void | removeAttributes(Enumeration<?> names) Removes a set of attributes for the element.
void | setResolveParent(AttributeSet parent) Sets the resolving parent.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractDocument.AbstractElement

public AbstractDocument.AbstractElement(Element parent,
                                        AttributeSet a)
Creates a new AbstractElement.

Parameters:
parent - the parent element
a - the attributes for the element
Since:
1.4
Method Detail

dump

public void dump(PrintStream psOut,
                 int indentAmount)
Dumps a debugging representation of the element hierarchy.

Parameters:
psOut - the output stream
indentAmount - the indentation level >= 0

getAttributeCount

public int getAttributeCount()
Gets the number of attributes that are defined.

Specified by:
getAttributeCount in interface AttributeSet
Returns:
the number of attributes >= 0
See Also:
AttributeSet.getAttributeCount()

isDefined

public boolean isDefined(Object attrName)
Checks whether a given attribute is defined.

Specified by:
isDefined in interface AttributeSet
Parameters:
attrName - the non-null attribute name
Returns:
true if the attribute is defined
See Also:
AttributeSet.isDefined(java.lang.Object)

isEqual

public boolean isEqual(AttributeSet attr)
Checks whether two attribute sets are equal.

Specified by:
isEqual in interface AttributeSet
Parameters:
attr - the attribute set to check against
Returns:
true if the same
See Also:
AttributeSet.isEqual(javax.swing.text.AttributeSet)

copyAttributes

public AttributeSet copyAttributes()
Copies a set of attributes.

Specified by:
copyAttributes in interface AttributeSet
Returns:
the copy
See Also:
AttributeSet.copyAttributes()

getAttribute

public Object getAttribute(Object attrName)
Gets the value of an attribute.

Specified by:
getAttribute in interface AttributeSet
Parameters:
attrName - the non-null attribute name
Returns:
the attribute value
See Also:
AttributeSet.getAttribute(java.lang.Object)

getAttributeNames

public Enumeration<?> getAttributeNames()
Gets the names of all attributes.

Specified by:
getAttributeNames in interface AttributeSet
Returns:
the attribute names as an enumeration
See Also:
AttributeSet.getAttributeNames()

containsAttribute

public boolean containsAttribute(Object name,
                                 Object value)
Checks whether a given attribute name/value is defined.

Specified by:
containsAttribute in interface AttributeSet
Parameters:
name - the non-null attribute name
value - the attribute value
Returns:
true if the name/value is defined
See Also:
AttributeSet.containsAttribute(java.lang.Object, java.lang.Object)

containsAttributes

public boolean containsAttributes(AttributeSet attrs)
Checks whether the element contains all the attributes.

Specified by:
containsAttributes in interface AttributeSet
Parameters:
attrs - the attributes to check
Returns:
true if the element contains all the attributes
See Also:
AttributeSet.containsAttributes(javax.swing.text.AttributeSet)

getResolveParent

public AttributeSet getResolveParent()
Gets the resolving parent. If not overridden, the resolving parent defaults to the parent element.

Specified by:
getResolveParent in interface AttributeSet
Returns:
the attributes from the parent, null if none
See Also:
AttributeSet.getResolveParent()

addAttribute

public void addAttribute(Object name,
                         Object value)
Adds an attribute to the element.

Specified by:
addAttribute in interface MutableAttributeSet
Parameters:
name - the non-null attribute name
value - the attribute value
See Also:
MutableAttributeSet.addAttribute(java.lang.Object, java.lang.Object)

addAttributes

public void addAttributes(AttributeSet attr)
Adds a set of attributes to the element.

Specified by:
addAttributes in interface MutableAttributeSet
Parameters:
attr - the attributes to add
See Also:
MutableAttributeSet.addAttribute(java.lang.Object, java.lang.Object)

removeAttribute

public void removeAttribute(Object name)
Removes an attribute from the set.

Specified by:
removeAttribute in interface MutableAttributeSet
Parameters:
name - the non-null attribute name
See Also:
MutableAttributeSet.removeAttribute(java.lang.Object)

removeAttributes

public void removeAttributes(Enumeration<?> names)
Removes a set of attributes for the element.

Specified by:
removeAttributes in interface MutableAttributeSet
Parameters:
names - the attribute names
See Also:
MutableAttributeSet.removeAttributes(java.util.Enumeration)

removeAttributes

public void removeAttributes(AttributeSet attrs)
Removes a set of attributes for the element.

Specified by:
removeAttributes in interface MutableAttributeSet
Parameters:
attrs - the attributes
See Also:
MutableAttributeSet.removeAttributes(java.util.Enumeration)

setResolveParent

public void setResolveParent(AttributeSet parent)
Sets the resolving parent.

Specified by:
setResolveParent in interface MutableAttributeSet
Parameters:
parent - the parent, null if none
See Also:
MutableAttributeSet.setResolveParent(javax.swing.text.AttributeSet)

getDocument

public Document getDocument()
Retrieves the underlying model.

Specified by:
getDocument in interface Element
Returns:
the model

getParentElement

public Element getParentElement()
Gets the parent of the element.

Specified by:
getParentElement in interface Element
Returns:
the parent

getAttributes

public AttributeSet getAttributes()
Gets the attributes for the element.

Specified by:
getAttributes in interface Element
Returns:
the attribute set

getName

public String getName()
Gets the name of the element.

Specified by:
getName in interface Element
Returns:
the name, null if none

getStartOffset

public abstract int getStartOffset()
Gets the starting offset in the model for the element.

Specified by:
getStartOffset in interface Element
Returns:
the offset >= 0
See Also:
Document, AbstractDocument

getEndOffset

public abstract int getEndOffset()
Gets the ending offset in the model for the element.

Specified by:
getEndOffset in interface Element
Returns:
the offset >= 0
See Also:
Document, AbstractDocument

getElement

public abstract Element getElement(int index)
Gets a child element.

Specified by:
getElement in interface Element
Parameters:
index - the child index, >= 0 && < getElementCount()
Returns:
the child element

getElementCount

public abstract int getElementCount()
Gets the number of children for the element.

Specified by:
getElementCount in interface Element
Returns:
the number of children >= 0

getElementIndex

public abstract int getElementIndex(int offset)
Gets the child element index closest to the given model offset.

Specified by:
getElementIndex in interface Element
Parameters:
offset - the offset >= 0
Returns:
the element index >= 0

isLeaf

public abstract boolean isLeaf()
Checks whether the element is a leaf.

Specified by:
isLeaf in interface Element
Specified by:
isLeaf in interface TreeNode
Returns:
true if a leaf

getChildAt

public TreeNode getChildAt(int childIndex)
Returns the child TreeNode at index childIndex.

Specified by:
getChildAt in interface TreeNode

getChildCount

public int getChildCount()
Returns the number of children TreeNode's receiver contains.

Specified by:
getChildCount in interface TreeNode
Returns:
the number of children TreeNodews's receiver contains

getParent

public TreeNode getParent()
Returns the parent TreeNode of the receiver.

Specified by:
getParent in interface TreeNode
Returns:
the parent TreeNode of the receiver

getIndex

public int getIndex(TreeNode node)
Returns the index of node in the receivers children. If the receiver does not contain node, -1 will be returned.

Specified by:
getIndex in interface TreeNode
Parameters:
node - the location of interest
Returns:
the index of node in the receiver's children, or -1 if absent

getAllowsChildren

public abstract boolean getAllowsChildren()
Returns true if the receiver allows children.

Specified by:
getAllowsChildren in interface TreeNode
Returns:
true if the receiver allows children, otherwise false

children

public abstract Enumeration children()
Returns the children of the receiver as an Enumeration.

Specified by:
children in interface TreeNode
Returns:
the children of the receiver as an Enumeration
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AbstractDocument.AttributeContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface AbstractDocument.AttributeContext

All Known Implementing Classes:
StyleContext, StyleSheet
Enclosing class:
AbstractDocument
public static interface AbstractDocument.AttributeContext

An interface that can be used to allow MutableAttributeSet implementations to use pluggable attribute compression techniques. Each mutation of the attribute set can be used to exchange a previous AttributeSet instance with another, preserving the possibility of the AttributeSet remaining immutable. An implementation is provided by the StyleContext class. The Element implementations provided by this class use this interface to provide their MutableAttributeSet implementations, so that different AttributeSet compression techniques can be employed. The method getAttributeContext should be implemented to return the object responsible for implementing the desired compression technique.

See Also:
StyleContext

Method Summary
AttributeSet | addAttribute(AttributeSet old, Object name, Object value) Adds an attribute to the given set, and returns the new representative set.
AttributeSet | addAttributes(AttributeSet old, AttributeSet attr) Adds a set of attributes to the element.
AttributeSet | getEmptySet() Fetches an empty AttributeSet.
void | reclaim(AttributeSet a) Reclaims an attribute set.
AttributeSet | removeAttribute(AttributeSet old, Object name) Removes an attribute from the set.
AttributeSet | removeAttributes(AttributeSet old, AttributeSet attrs) Removes a set of attributes for the element.
AttributeSet | removeAttributes(AttributeSet old, Enumeration<?> names) Removes a set of attributes for the element.

Method Detail

addAttribute

AttributeSet addAttribute(AttributeSet old,
                          Object name,
                          Object value)
Adds an attribute to the given set, and returns the new representative set.

Parameters:
old - the old attribute set
name - the non-null attribute name
value - the attribute value
Returns:
the updated attribute set
See Also:
MutableAttributeSet.addAttribute(java.lang.Object, java.lang.Object)

addAttributes

AttributeSet addAttributes(AttributeSet old,
                           AttributeSet attr)
Adds a set of attributes to the element.

Parameters:
old - the old attribute set
attr - the attributes to add
Returns:
the updated attribute set
See Also:
MutableAttributeSet.addAttribute(java.lang.Object, java.lang.Object)

removeAttribute

AttributeSet removeAttribute(AttributeSet old,
                             Object name)
Removes an attribute from the set.

Parameters:
old - the old attribute set
name - the non-null attribute name
Returns:
the updated attribute set
See Also:
MutableAttributeSet.removeAttribute(java.lang.Object)

removeAttributes

AttributeSet removeAttributes(AttributeSet old,
                              Enumeration<?> names)
Removes a set of attributes for the element.

Parameters:
old - the old attribute set
names - the attribute names
Returns:
the updated attribute set
See Also:
MutableAttributeSet.removeAttributes(java.util.Enumeration)

removeAttributes

AttributeSet removeAttributes(AttributeSet old,
                              AttributeSet attrs)
Removes a set of attributes for the element.

Parameters:
old - the old attribute set
attrs - the attributes
Returns:
the updated attribute set
See Also:
MutableAttributeSet.removeAttributes(java.util.Enumeration)

getEmptySet

AttributeSet getEmptySet()
Fetches an empty AttributeSet.

Returns:
the attribute set

reclaim

void reclaim(AttributeSet a)
Reclaims an attribute set. This is a way for a MutableAttributeSet to mark that it no longer need a particular immutable set. This is only necessary in 1.1 where there are no weak references. A 1.1 implementation would call this in its finalize method.

Parameters:
a - the attribute set to reclaim
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AbstractDocument.BranchElement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class AbstractDocument.BranchElement

java.lang.Object
    extended by  javax.swing.text.AbstractDocument.AbstractElement
        extended by  javax.swing.text.AbstractDocument.BranchElement
All Implemented Interfaces:
Serializable, AttributeSet, Element, MutableAttributeSet, TreeNode
Direct Known Subclasses:
DefaultStyledDocument.SectionElement, HTMLDocument.BlockElement
Enclosing class:
AbstractDocument
public class AbstractDocument.BranchElement
extends AbstractDocument.AbstractElement

Implements a composite element that contains other elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from interface javax.swing.text.AttributeSet
AttributeSet.CharacterAttribute, AttributeSet.ColorAttribute, AttributeSet.FontAttribute, AttributeSet.ParagraphAttribute
Field Summary
Fields inherited from interface javax.swing.text.AttributeSet
NameAttribute, ResolveAttribute
Constructor Summary
AbstractDocument.BranchElement(Element parent, AttributeSet a)
Constructs a composite element that initially contains no children.
Method Summary
Enumeration | children() Returns the children of the receiver as an Enumeration.
boolean | getAllowsChildren() Returns true if the receiver allows children.
Element | getElement(int index) Gets a child element.
int | getElementCount() Gets the number of children for the element.
int | getElementIndex(int offset) Gets the child element index closest to the given model offset.
int | getEndOffset() Gets the ending offset in the model for the element.
String | getName() Gets the element name.
int | getStartOffset() Gets the starting offset in the model for the element.
boolean | isLeaf() Checks whether the element is a leaf.
Element | positionToElement(int pos) Gets the child element that contains the given model position.
void | replace(int offset, int length, Element[] elems) Replaces content with a new set of elements.
String | toString() Converts the element to a string.
Methods inherited from class javax.swing.text.AbstractDocument.AbstractElement
addAttribute, addAttributes, containsAttribute, containsAttributes, copyAttributes, dump, getAttribute, getAttributeCount, getAttributeNames, getAttributes, getChildAt, getChildCount, getDocument, getIndex, getParent, getParentElement, getResolveParent, isDefined, isEqual, removeAttribute, removeAttributes, removeAttributes, setResolveParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractDocument.BranchElement

public AbstractDocument.BranchElement(Element parent,
                                      AttributeSet a)
Constructs a composite element that initially contains no children.

Parameters:
parent - The parent element
a - the attributes for the element
Since:
1.4
Method Detail

positionToElement

public Element positionToElement(int pos)
Gets the child element that contains the given model position.

Parameters:
pos - the position >= 0
Returns:
the element, null if none

replace

public void replace(int offset,
                    int length,
                    Element[] elems)
Replaces content with a new set of elements.

Parameters:
offset - the starting offset >= 0
length - the length to replace >= 0
elems - the new elements

toString

public String toString()
Converts the element to a string.

Overrides:
toString in class Object
Returns:
the string

getName

public String getName()
Gets the element name.

Specified by:
getName in interface Element
Overrides:
getName in class AbstractDocument.AbstractElement
Returns:
the element name

getStartOffset

public int getStartOffset()
Gets the starting offset in the model for the element.

Specified by:
getStartOffset in interface Element
Specified by:
getStartOffset in class AbstractDocument.AbstractElement
Returns:
the offset >= 0
See Also:
Document, AbstractDocument

getEndOffset

public int getEndOffset()
Gets the ending offset in the model for the element.

Specified by:
getEndOffset in interface Element
Specified by:
getEndOffset in class AbstractDocument.AbstractElement
Returns:
the offset >= 0
Throws:
NullPointerException - if this element has no children
See Also:
Document, AbstractDocument

getElement

public Element getElement(int index)
Gets a child element.

Specified by:
getElement in interface Element
Specified by:
getElement in class AbstractDocument.AbstractElement
Parameters:
index - the child index, >= 0 && < getElementCount()
Returns:
the child element, null if none

getElementCount

public int getElementCount()
Gets the number of children for the element.

Specified by:
getElementCount in interface Element
Specified by:
getElementCount in class AbstractDocument.AbstractElement
Returns:
the number of children >= 0

getElementIndex

public int getElementIndex(int offset)
Gets the child element index closest to the given model offset.

Specified by:
getElementIndex in interface Element
Specified by:
getElementIndex in class AbstractDocument.AbstractElement
Parameters:
offset - the offset >= 0
Returns:
the element index >= 0

isLeaf

public boolean isLeaf()
Checks whether the element is a leaf.

Specified by:
isLeaf in interface Element
Specified by:
isLeaf in interface TreeNode
Specified by:
isLeaf in class AbstractDocument.AbstractElement
Returns:
true if a leaf

getAllowsChildren

public boolean getAllowsChildren()
Returns true if the receiver allows children.

Specified by:
getAllowsChildren in interface TreeNode
Specified by:
getAllowsChildren in class AbstractDocument.AbstractElement
Returns:
true if the receiver allows children, otherwise false

children

public Enumeration children()
Returns the children of the receiver as an Enumeration.

Specified by:
children in interface TreeNode
Specified by:
children in class AbstractDocument.AbstractElement
Returns:
the children of the receiver
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AbstractDocument.Content

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface AbstractDocument.Content

All Known Implementing Classes:
GapContent, StringContent
Enclosing class:
AbstractDocument
public static interface AbstractDocument.Content

Interface to describe a sequence of character content that can be edited. Implementations may or may not support a history mechanism which will be reflected by whether or not mutations return an UndoableEdit implementation.

See Also:
AbstractDocument

Method Summary
Position | createPosition(int offset) Creates a position within the content that will track change as the content is mutated.
void | getChars(int where, int len, Segment txt) Gets a sequence of characters and copies them into a Segment.
String | getString(int where, int len) Fetches a string of characters contained in the sequence.
UndoableEdit | insertString(int where, String str) Inserts a string of characters into the sequence.
int | length() Current length of the sequence of character content.
UndoableEdit | remove(int where, int nitems) Removes some portion of the sequence.

Method Detail

createPosition

Position createPosition(int offset)
                        throws BadLocationException
Creates a position within the content that will track change as the content is mutated.

Parameters:
offset - the offset in the content >= 0
Returns:
a Position
Throws:
BadLocationException - for an invalid offset

length

int length()
Current length of the sequence of character content.

Returns:
the length >= 0

insertString

UndoableEdit insertString(int where,
                          String str)
                          throws BadLocationException
Inserts a string of characters into the sequence.

Parameters:
where - offset into the sequence to make the insertion >= 0
str - string to insert
Returns:
if the implementation supports a history mechanism, a reference to an Edit implementation will be returned, otherwise returns null
Throws:
BadLocationException - thrown if the area covered by the arguments is not contained in the character sequence

remove

UndoableEdit remove(int where,
                    int nitems)
                    throws BadLocationException
Removes some portion of the sequence.

Parameters:
where - The offset into the sequence to make the insertion >= 0.
nitems - The number of items in the sequence to remove >= 0.
Returns:
If the implementation supports a history mechansim, a reference to an Edit implementation will be returned, otherwise null.
Throws:
BadLocationException - Thrown if the area covered by the arguments is not contained in the character sequence.

getString

String getString(int where,
                 int len)
                 throws BadLocationException
Fetches a string of characters contained in the sequence.

Parameters:
where - Offset into the sequence to fetch >= 0.
len - number of characters to copy >= 0.
Returns:
the string
Throws:
BadLocationException - Thrown if the area covered by the arguments is not contained in the character sequence.

getChars

void getChars(int where,
              int len,
              Segment txt)
              throws BadLocationException
Gets a sequence of characters and copies them into a Segment.

Parameters:
where - the starting offset >= 0
len - the number of characters >= 0
txt - the target location to copy into
Throws:
BadLocationException - Thrown if the area covered by the arguments is not contained in the character sequence.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AbstractDocument.DefaultDocumentEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class AbstractDocument.DefaultDocumentEvent

java.lang.Object
    extended by  javax.swing.undo.AbstractUndoableEdit
        extended by  javax.swing.undo.CompoundEdit
            extended by  javax.swing.text.AbstractDocument.DefaultDocumentEvent
All Implemented Interfaces:
Serializable, DocumentEvent, UndoableEdit
Enclosing class:
AbstractDocument
public class AbstractDocument.DefaultDocumentEvent
extends CompoundEdit
implements DocumentEvent

Stores document changes as the document is being modified. Can subsequently be used for change notification when done with the document modification transaction. This is used by the AbstractDocument class and its extensions for broadcasting change information to the document listeners.

Nested Class Summary
Nested classes/interfaces inherited from interface javax.swing.event.DocumentEvent
DocumentEvent.ElementChange, DocumentEvent.EventType
Field Summary
Fields inherited from class javax.swing.undo.CompoundEdit
edits
Fields inherited from class javax.swing.undo.AbstractUndoableEdit
RedoName, UndoName
Constructor Summary
AbstractDocument.DefaultDocumentEvent(int offs, int len, DocumentEvent.EventType type)
Constructs a change record.
Method Summary
boolean | addEdit(UndoableEdit anEdit) Adds a document edit.
DocumentEvent.ElementChange | getChange(Element elem) Gets the changes for an element.
Document | getDocument() Gets the document that sourced the change event.
int | getLength() Returns the length of the change.
int | getOffset() Returns the offset within the document of the start of the change.
String | getPresentationName() Provides a localized, human readable description of this edit suitable for use in, say, a change log.
String | getRedoPresentationName() Provides a localized, human readable description of the redoable form of this edit, e.g.
DocumentEvent.EventType | getType() Returns the type of event.
String | getUndoPresentationName() Provides a localized, human readable description of the undoable form of this edit, e.g.
boolean | isSignificant() DefaultDocument events are significant.
void | redo() Redoes a change.
String | toString() Returns a string description of the change event.
void | undo() Undoes a change.
Methods inherited from class javax.swing.undo.CompoundEdit
canRedo, canUndo, die, end, isInProgress, lastEdit
Methods inherited from class javax.swing.undo.AbstractUndoableEdit
replaceEdit
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractDocument.DefaultDocumentEvent

public AbstractDocument.DefaultDocumentEvent(int offs,
                                             int len,
                                             DocumentEvent.EventType type)
Constructs a change record.

Parameters:
offs - the offset into the document of the change >= 0
len - the length of the change >= 0
type - the type of event (DocumentEvent.EventType)
Since:
1.4
Method Detail

toString

public String toString()
Returns a string description of the change event.

Overrides:
toString in class CompoundEdit
Returns:
a string

addEdit

public boolean addEdit(UndoableEdit anEdit)
Adds a document edit. If the number of edits crosses a threshold, this switches on a hashtable lookup for ElementChange implementations since access of these needs to be relatively quick.

Specified by:
addEdit in interface UndoableEdit
Overrides:
addEdit in class CompoundEdit
Parameters:
anEdit - a document edit record
Returns:
true if the edit was added
See Also:
UndoableEdit.addEdit(javax.swing.undo.UndoableEdit)

redo

public void redo()
          throws CannotRedoException
Redoes a change.

Specified by:
redo in interface UndoableEdit
Overrides:
redo in class CompoundEdit
Throws:
CannotRedoException - if the change cannot be redone
See Also:
AbstractUndoableEdit.canRedo()

undo

public void undo()
          throws CannotUndoException
Undoes a change.

Specified by:
undo in interface UndoableEdit
Overrides:
undo in class CompoundEdit
Throws:
CannotUndoException - if the change cannot be undone
See Also:
AbstractUndoableEdit.canUndo()

isSignificant

public boolean isSignificant()
DefaultDocument events are significant. If you wish to aggregate DefaultDocumentEvents to present them as a single edit to the user place them into a CompoundEdit.

Specified by:
isSignificant in interface UndoableEdit
Overrides:
isSignificant in class CompoundEdit
Returns:
whether the event is significant for edit undo purposes
See Also:
UndoableEdit.isSignificant()

getPresentationName

public String getPresentationName()
Provides a localized, human readable description of this edit suitable for use in, say, a change log.

Specified by:
getPresentationName in interface UndoableEdit
Overrides:
getPresentationName in class CompoundEdit
Returns:
the description
See Also:
AbstractUndoableEdit.getUndoPresentationName(), AbstractUndoableEdit.getRedoPresentationName()

getUndoPresentationName

public String getUndoPresentationName()
Provides a localized, human readable description of the undoable form of this edit, e.g. for use as an Undo menu item. Typically derived from getDescription();

Specified by:
getUndoPresentationName in interface UndoableEdit
Overrides:
getUndoPresentationName in class CompoundEdit
Returns:
the description
See Also:
AbstractUndoableEdit.getPresentationName()

getRedoPresentationName

public String getRedoPresentationName()
Provides a localized, human readable description of the redoable form of this edit, e.g. for use as a Redo menu item. Typically derived from getPresentationName();

Specified by:
getRedoPresentationName in interface UndoableEdit
Overrides:
getRedoPresentationName in class CompoundEdit
Returns:
the description
See Also:
AbstractUndoableEdit.getPresentationName()

getType

public DocumentEvent.EventType getType()
Returns the type of event.

Specified by:
getType in interface DocumentEvent
Returns:
the event type as a DocumentEvent.EventType
See Also:
DocumentEvent.getType()

getOffset

public int getOffset()
Returns the offset within the document of the start of the change.

Specified by:
getOffset in interface DocumentEvent
Returns:
the offset >= 0
See Also:
DocumentEvent.getOffset()

getLength

public int getLength()
Returns the length of the change.

Specified by:
getLength in interface DocumentEvent
Returns:
the length >= 0
See Also:
DocumentEvent.getLength()

getDocument

public Document getDocument()
Gets the document that sourced the change event.

Specified by:
getDocument in interface DocumentEvent
Returns:
the document
See Also:
DocumentEvent.getDocument()

getChange

public DocumentEvent.ElementChange getChange(Element elem)
Gets the changes for an element.

Specified by:
getChange in interface DocumentEvent
Parameters:
elem - the element
Returns:
the changes
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AbstractDocument.ElementEdit

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class AbstractDocument.ElementEdit

java.lang.Object
    extended by  javax.swing.undo.AbstractUndoableEdit
        extended by  javax.swing.text.AbstractDocument.ElementEdit
All Implemented Interfaces:
Serializable, DocumentEvent.ElementChange, UndoableEdit
Enclosing class:
AbstractDocument
public static class AbstractDocument.ElementEdit
extends AbstractUndoableEdit
implements DocumentEvent.ElementChange

An implementation of ElementChange that can be added to the document event.

Field Summary
Fields inherited from class javax.swing.undo.AbstractUndoableEdit
RedoName, UndoName
Constructor Summary
AbstractDocument.ElementEdit(Element e, int index, Element[] removed, Element[] added)
Constructs an edit record.
Method Summary
Element[] | getChildrenAdded() Gets a list of children that were added.
Element[] | getChildrenRemoved() Gets a list of children that were removed.
Element | getElement() Returns the underlying element.
int | getIndex() Returns the index into the list of elements.
void | redo() Redoes a change.
void | undo() Undoes a change.
Methods inherited from class javax.swing.undo.AbstractUndoableEdit
addEdit, canRedo, canUndo, die, getPresentationName, getRedoPresentationName, getUndoPresentationName, isSignificant, replaceEdit, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractDocument.ElementEdit

public AbstractDocument.ElementEdit(Element e,
                                    int index,
                                    Element[] removed,
                                    Element[] added)
Constructs an edit record. This does not modify the element so it can safely be used to catch up a view to the current model state for views that just attached to a model.

Parameters:
e - the element
index - the index into the model >= 0
removed - a set of elements that were removed
added - a set of elements that were added
Method Detail

getElement

public Element getElement()
Returns the underlying element.

Specified by:
getElement in interface DocumentEvent.ElementChange
Returns:
the element

getIndex

public int getIndex()
Returns the index into the list of elements.

Specified by:
getIndex in interface DocumentEvent.ElementChange
Returns:
the index >= 0

getChildrenRemoved

public Element[] getChildrenRemoved()
Gets a list of children that were removed.

Specified by:
getChildrenRemoved in interface DocumentEvent.ElementChange
Returns:
the list

getChildrenAdded

public Element[] getChildrenAdded()
Gets a list of children that were added.

Specified by:
getChildrenAdded in interface DocumentEvent.ElementChange
Returns:
the list

redo

public void redo()
          throws CannotRedoException
Redoes a change.

Specified by:
redo in interface UndoableEdit
Overrides:
redo in class AbstractUndoableEdit
Throws:
CannotRedoException - if the change cannot be redone
See Also:
AbstractUndoableEdit.canRedo()

undo

public void undo()
          throws CannotUndoException
Undoes a change.

Specified by:
undo in interface UndoableEdit
Overrides:
undo in class AbstractUndoableEdit
Throws:
CannotUndoException - if the change cannot be undone
See Also:
AbstractUndoableEdit.canUndo()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AbstractDocument.LeafElement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class AbstractDocument.LeafElement

java.lang.Object
    extended by  javax.swing.text.AbstractDocument.AbstractElement
        extended by  javax.swing.text.AbstractDocument.LeafElement
All Implemented Interfaces:
Serializable, AttributeSet, Element, MutableAttributeSet, TreeNode
Direct Known Subclasses:
HTMLDocument.RunElement
Enclosing class:
AbstractDocument
public class AbstractDocument.LeafElement
extends AbstractDocument.AbstractElement

Implements an element that directly represents content of some kind.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
Element

Nested Class Summary
Nested classes/interfaces inherited from interface javax.swing.text.AttributeSet
AttributeSet.CharacterAttribute, AttributeSet.ColorAttribute, AttributeSet.FontAttribute, AttributeSet.ParagraphAttribute
Field Summary
Fields inherited from interface javax.swing.text.AttributeSet
NameAttribute, ResolveAttribute
Constructor Summary
AbstractDocument.LeafElement(Element parent, AttributeSet a, int offs0, int offs1)
Constructs an element that represents content within the document (has no children).
Method Summary
Enumeration | children() Returns the children of the receiver as an Enumeration.
boolean | getAllowsChildren() Returns true if the receiver allows children.
Element | getElement(int index) Gets a child element.
int | getElementCount() Returns the number of child elements.
int | getElementIndex(int pos) Gets the child element index closest to the given model offset.
int | getEndOffset() Gets the ending offset in the model for the element.
String | getName() Gets the element name.
int | getStartOffset() Gets the starting offset in the model for the element.
boolean | isLeaf() Checks whether the element is a leaf.
String | toString() Converts the element to a string.
Methods inherited from class javax.swing.text.AbstractDocument.AbstractElement
addAttribute, addAttributes, containsAttribute, containsAttributes, copyAttributes, dump, getAttribute, getAttributeCount, getAttributeNames, getAttributes, getChildAt, getChildCount, getDocument, getIndex, getParent, getParentElement, getResolveParent, isDefined, isEqual, removeAttribute, removeAttributes, removeAttributes, setResolveParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractDocument.LeafElement

public AbstractDocument.LeafElement(Element parent,
                                    AttributeSet a,
                                    int offs0,
                                    int offs1)
Constructs an element that represents content within the document (has no children).

Parameters:
parent - The parent element
a - The element attributes
offs0 - The start offset >= 0
offs1 - The end offset >= offs0
Since:
1.4
Method Detail

toString

public String toString()
Converts the element to a string.

Overrides:
toString in class Object
Returns:
the string

getStartOffset

public int getStartOffset()
Gets the starting offset in the model for the element.

Specified by:
getStartOffset in interface Element
Specified by:
getStartOffset in class AbstractDocument.AbstractElement
Returns:
the offset >= 0
See Also:
Document, AbstractDocument

getEndOffset

public int getEndOffset()
Gets the ending offset in the model for the element.

Specified by:
getEndOffset in interface Element
Specified by:
getEndOffset in class AbstractDocument.AbstractElement
Returns:
the offset >= 0
See Also:
Document, AbstractDocument

getName

public String getName()
Gets the element name.

Specified by:
getName in interface Element
Overrides:
getName in class AbstractDocument.AbstractElement
Returns:
the name

getElementIndex

public int getElementIndex(int pos)
Gets the child element index closest to the given model offset.

Specified by:
getElementIndex in interface Element
Specified by:
getElementIndex in class AbstractDocument.AbstractElement
Parameters:
pos - the offset >= 0
Returns:
the element index >= 0

getElement

public Element getElement(int index)
Gets a child element.

Specified by:
getElement in interface Element
Specified by:
getElement in class AbstractDocument.AbstractElement
Parameters:
index - the child index, >= 0 && < getElementCount()
Returns:
the child element

getElementCount

public int getElementCount()
Returns the number of child elements.

Specified by:
getElementCount in interface Element
Specified by:
getElementCount in class AbstractDocument.AbstractElement
Returns:
the number of children >= 0

isLeaf

public boolean isLeaf()
Checks whether the element is a leaf.

Specified by:
isLeaf in interface Element
Specified by:
isLeaf in interface TreeNode
Specified by:
isLeaf in class AbstractDocument.AbstractElement
Returns:
true if a leaf

getAllowsChildren

public boolean getAllowsChildren()
Returns true if the receiver allows children.

Specified by:
getAllowsChildren in interface TreeNode
Specified by:
getAllowsChildren in class AbstractDocument.AbstractElement
Returns:
true if the receiver allows children, otherwise false

children

public Enumeration children()
Returns the children of the receiver as an Enumeration.

Specified by:
children in interface TreeNode
Specified by:
children in class AbstractDocument.AbstractElement
Returns:
the children of the receiver
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AbstractWriter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class AbstractWriter

java.lang.Object
    extended by  javax.swing.text.AbstractWriter
Direct Known Subclasses:
HTMLWriter, MinimalHTMLWriter
public abstract class AbstractWriter
extends Object

AbstractWriter is an abstract class that actually does the work of writing out the element tree including the attributes. In terms of how much is written out per line, the writer defaults to 100. But this value can be set by subclasses.

Field Summary
protected static char NEWLINE
How the text packages models newlines.
Constructor Summary
protected | AbstractWriter(Writer w, Document doc) Creates a new AbstractWriter.
protected | AbstractWriter(Writer w, Document doc, int pos, int len) Creates a new AbstractWriter.
protected | AbstractWriter(Writer w, Element root) Creates a new AbstractWriter.
protected | AbstractWriter(Writer w, Element root, int pos, int len) Creates a new AbstractWriter.
Method Summary
protected void | decrIndent() Decrements the indent level.
protected boolean | getCanWrapLines() Returns whether or not the lines can be wrapped.
protected int | getCurrentLineLength() Returns the current line length.
protected Document | getDocument() Fetches the document.
protected ElementIterator | getElementIterator() Fetches the ElementIterator.
int | getEndOffset() Returns the last offset to be output.
protected int | getIndentLevel() Returns the current indentation level.
protected int | getIndentSpace() Returns the amount of space to indent.
protected int | getLineLength() Returns the maximum line length.
String | getLineSeparator() Returns the string used to represent newlines.
int | getStartOffset() Returns the first offset to be output.
protected String | getText(Element elem) Returns the text associated with the element.
protected Writer | getWriter() Returns the Writer that is used to output the content.
protected void | incrIndent() Increments the indent level.
protected void | indent() Does indentation.
protected boolean | inRange(Element next) This method determines whether the current element is in the range specified.
protected boolean | isLineEmpty() Returns true if the current line should be considered empty.
protected void | output(char[] content, int start, int length) The last stop in writing out content.
protected void | setCanWrapLines(boolean newValue) Sets whether or not lines can be wrapped.
protected void | setCurrentLineLength(int length) Sets the current line length.
protected void | setIndentSpace(int space) Enables subclasses to specify how many spaces an indent maps to.
protected void | setLineLength(int l) Enables subclasses to set the number of characters they want written per line.
void | setLineSeparator(String value) Sets the String used to reprsent newlines.
protected void | text(Element elem) Writes out text.
protected abstract void | write() This abstract method needs to be implemented by subclasses.
protected void | write(char ch) Writes out a character.
protected void | write(char[] chars, int startIndex, int length) All write methods call into this one.
protected void | write(String content) Writes out a string.
protected void | writeAttributes(AttributeSet attr) Writes out the set of attributes as " =" pairs.
protected void | writeLineSeparator() Writes the line separator.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NEWLINE

protected static final char NEWLINE
How the text packages models newlines.

See Also:
getLineSeparator(), Constant Field Values
Constructor Detail

AbstractWriter

protected AbstractWriter(Writer w,
                         Document doc)
Creates a new AbstractWriter. Initializes the ElementIterator with the default root of the document.

Parameters:
w - a Writer.
doc - a Document

AbstractWriter

protected AbstractWriter(Writer w,
                         Document doc,
                         int pos,
                         int len)
Creates a new AbstractWriter. Initializes the ElementIterator with the element passed in.

Parameters:
w - a Writer
doc - an Element
pos - The location in the document to fetch the content.
len - The amount to write out.

AbstractWriter

protected AbstractWriter(Writer w,
                         Element root)
Creates a new AbstractWriter. Initializes the ElementIterator with the element passed in.

Parameters:
w - a Writer
root - an Element

AbstractWriter

protected AbstractWriter(Writer w,
                         Element root,
                         int pos,
                         int len)
Creates a new AbstractWriter. Initializes the ElementIterator with the element passed in.

Parameters:
w - a Writer
root - an Element
pos - The location in the document to fetch the content.
len - The amount to write out.
Method Detail

getStartOffset

public int getStartOffset()
Returns the first offset to be output.

Since:
1.3

getEndOffset

public int getEndOffset()
Returns the last offset to be output.

Since:
1.3

getElementIterator

protected ElementIterator getElementIterator()
Fetches the ElementIterator.

Returns:
the ElementIterator.

getWriter

protected Writer getWriter()
Returns the Writer that is used to output the content.

Since:
1.3

getDocument

protected Document getDocument()
Fetches the document.

Returns:
the Document.

inRange

protected boolean inRange(Element next)
This method determines whether the current element is in the range specified. When no range is specified, the range is initialized to be the entire document. inRange() returns true if the range specified intersects with the element's range.

Parameters:
next - an Element.
Returns:
boolean that indicates whether the element is in the range.

write

protected abstract void write()
                       throws IOException,
                              BadLocationException
This abstract method needs to be implemented by subclasses. Its responsibility is to iterate over the elements and use the write() methods to generate output in the desired format.

Throws:
IOException
BadLocationException

getText

protected String getText(Element elem)
                  throws BadLocationException
Returns the text associated with the element. The assumption here is that the element is a leaf element. Throws a BadLocationException when encountered.

Parameters:
elem - an Element
Returns:
the text as a String
Throws:
BadLocationException - if pos represents an invalid location within the document

text

protected void text(Element elem)
             throws BadLocationException,
                    IOException
Writes out text. If a range is specified when the constructor is invoked, then only the appropriate range of text is written out.

Parameters:
elem - an Element.
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

setLineLength

protected void setLineLength(int l)
Enables subclasses to set the number of characters they want written per line. The default is 100.

Parameters:
l - the maximum line length.

getLineLength

protected int getLineLength()
Returns the maximum line length.

Since:
1.3

setCurrentLineLength

protected void setCurrentLineLength(int length)
Sets the current line length.

Since:
1.3

getCurrentLineLength

protected int getCurrentLineLength()
Returns the current line length.

Since:
1.3

isLineEmpty

protected boolean isLineEmpty()
Returns true if the current line should be considered empty. This is true when getCurrentLineLength == 0 || indent has been invoked on an empty line.

Since:
1.3

setCanWrapLines

protected void setCanWrapLines(boolean newValue)
Sets whether or not lines can be wrapped. This can be toggled during the writing of lines. For example, outputting HTML might set this to false when outputting a quoted string.

Since:
1.3

getCanWrapLines

protected boolean getCanWrapLines()
Returns whether or not the lines can be wrapped. If this is false no lineSeparator's will be output.

Since:
1.3

setIndentSpace

protected void setIndentSpace(int space)
Enables subclasses to specify how many spaces an indent maps to. When indentation takes place, the indent level is multiplied by this mapping. The default is 2.

Parameters:
space - an int representing the space to indent mapping.

getIndentSpace

protected int getIndentSpace()
Returns the amount of space to indent.

Since:
1.3

setLineSeparator

public void setLineSeparator(String value)
Sets the String used to reprsent newlines. This is initialized in the constructor from either the Document, or the System property line.separator.

Since:
1.3

getLineSeparator

public String getLineSeparator()
Returns the string used to represent newlines.

Since:
1.3

incrIndent

protected void incrIndent()
Increments the indent level. If indenting would cause getIndentSpace() *getIndentLevel() to be > than getLineLength() this will not cause an indent.

decrIndent

protected void decrIndent()
Decrements the indent level.

getIndentLevel

protected int getIndentLevel()
Returns the current indentation level. That is, the number of times incrIndent has been invoked minus the number of times decrIndent has been invoked.

Since:
1.3

indent

protected void indent()
               throws IOException
Does indentation. The number of spaces written out is indent level times the space to map mapping. If the current line is empty, this will not make it so that the current line is still considered empty.

Throws:
IOException - on any I/O error

write

protected void write(char ch)
              throws IOException
Writes out a character. This is implemented to invoke the write method that takes a char[].

Parameters:
ch - a char.
Throws:
IOException - on any I/O error

write

protected void write(String content)
              throws IOException
Writes out a string. This is implemented to invoke the write method that takes a char[].

Parameters:
content - a String.
Throws:
IOException - on any I/O error

writeLineSeparator

protected void writeLineSeparator()
                           throws IOException
Writes the line separator. This invokes output directly as well as setting the lineLength to 0.

Throws:
IOException
Since:
1.3

write

protected void write(char[] chars,
                     int startIndex,
                     int length)
              throws IOException
All write methods call into this one. If getCanWrapLines() returns false, this will call output with each sequence of chars that doesn't contain a NEWLINE, followed by a call to writeLineSeparator. On the other hand, if getCanWrapLines() returns true, this will split the string, as necessary, so getLineLength is honored. The only exception is if the current string contains no whitespace, and won't fit in which case the line length will exceed getLineLength.

Throws:
IOException
Since:
1.3

writeAttributes

protected void writeAttributes(AttributeSet attr)
                        throws IOException
Writes out the set of attributes as " =" pairs. It throws an IOException when encountered.

Parameters:
attr - an AttributeSet.
Throws:
IOException - on any I/O error

output

protected void output(char[] content,
                      int start,
                      int length)
               throws IOException
The last stop in writing out content. All the write methods eventually make it to this method, which invokes write on the Writer.

This method also updates the line length based on length. If this is invoked to output a newline, the current line length will need to be reset as will no longer be valid. If it is up to the caller to do this. Use writeLineSeparator to write out a newline, which will property update the current line length.

Throws:
IOException
Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AsyncBoxView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class AsyncBoxView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.AsyncBoxView
All Implemented Interfaces:
SwingConstants
public class AsyncBoxView
extends View

A box that does layout asynchronously. This is useful to keep the GUI event thread moving by not doing any layout on it. The layout is done on a granularity of operations on the child views. After each child view is accessed for some part of layout (a potentially time consuming operation) the remaining tasks can be abandoned or a new higher priority task (i.e. to service a synchronous request or a visible area) can be taken on.

While the child view is being accessed a read lock is aquired on the associated document so that the model is stable while being accessed.

Since:
1.3

Nested Class Summary
class | AsyncBoxView.ChildLocator A class to manage the effective position of the child views in a localized area while changes are being made around the localized area.
class | AsyncBoxView.ChildState A record representing the layout state of a child view.
Field Summary
protected  AsyncBoxView.ChildLocator locator
Object that manages the offsets of the children.
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
AsyncBoxView(Element elem, int axis)
Construct a box view that does asynchronous layout.
Method Summary
protected AsyncBoxView.ChildState | createChildState(View v) New ChildState records are created through this method to allow subclasses the extend the ChildState records to do/hold more
protected void | flushRequirementChanges() Publish the changes in preferences upward to the parent view.
float | getBottomInset() Get the bottom part of the margin around the view.
Shape | getChildAllocation(int index, Shape a) Fetches the allocation for the given child view.
protected AsyncBoxView.ChildState | getChildState(int index) Fetch the object representing the layout state of of the child at the given index.
protected boolean | getEstimatedMajorSpan() Is the major span currently estimated?
protected float | getInsetSpan(int axis) Fetch the span along an axis that is taken up by the insets.
protected LayoutQueue | getLayoutQueue() Fetch the queue to use for layout.
float | getLeftInset() Get the left part of the margin around the view.
int | getMajorAxis() Fetch the major axis (the axis the children are tiled along).
float | getMaximumSpan(int axis) Determines the maximum span for this view along an axis.
float | getMinimumSpan(int axis) Determines the minimum span for this view along an axis.
int | getMinorAxis() Fetch the minor axis (the axis orthoginal to the tiled axis).
int | getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
float | getPreferredSpan(int axis) Determines the preferred span for this view along an axis.
float | getRightInset() Get the right part of the margin around the view.
float | getTopInset() Get the top part of the margin around the view.
View | getView(int n) Gets the nth child view.
int | getViewCount() Returns the number of views in this view.
int | getViewIndex(int pos, Position.Bias b) Returns the child view index representing the given position in the model.
protected int | getViewIndexAtPosition(int pos, Position.Bias b) Fetches the child view index representing the given position in the model.
protected void | loadChildren(ViewFactory f) Loads all of the children to initialize the view.
protected void | majorRequirementChange(AsyncBoxView.ChildState cs, float delta) Requirements changed along the major axis.
protected void | minorRequirementChange(AsyncBoxView.ChildState cs) Requirements changed along the minor axis.
Shape | modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
void | paint(Graphics g, Shape alloc) Render the view using the given allocation and rendering surface.
void | preferenceChanged(View child, boolean width, boolean height) Child views can call this on the parent to indicate that the preference has changed and should be reconsidered for layout.
void | replace(int offset, int length, View[] views) Calls the superclass to update the child views, and updates the status records for the children.
void | setBottomInset(float i) Set the bottom part of the margin around the view.
protected void | setEstimatedMajorSpan(boolean isEstimated) Set the estimatedMajorSpan property that determines if the major span should be treated as being estimated.
void | setLeftInset(float i) Set the left part of the margin around the view.
void | setParent(View parent) Sets the parent of the view.
void | setRightInset(float i) Set the right part of the margin around the view.
void | setSize(float width, float height) Sets the size of the view.
void | setTopInset(float i) Set the top part of the margin around the view.
protected void | updateLayout(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a) Update the layout in response to receiving notification of change from the model.
int | viewToModel(float x, float y, Shape a, Position.Bias[] biasReturn) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
Methods inherited from class javax.swing.text.View
append, breakView, changedUpdate, createFragment, forwardUpdate, forwardUpdateToView, getAlignment, getAttributes, getBreakWeight, getContainer, getDocument, getElement, getEndOffset, getGraphics, getParent, getResizeWeight, getStartOffset, getToolTipText, getViewFactory, getViewIndex, insert, insertUpdate, isVisible, modelToView, modelToView, remove, removeAll, removeUpdate, updateChildren, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

locator

protected AsyncBoxView.ChildLocator locator
Object that manages the offsets of the children. All locking for management of child locations is on this object.

Constructor Detail

AsyncBoxView

public AsyncBoxView(Element elem,
                    int axis)
Construct a box view that does asynchronous layout.

Parameters:
elem - the element of the model to represent
axis - the axis to tile along. This can be either X_AXIS or Y_AXIS.
Method Detail

getMajorAxis

public int getMajorAxis()
Fetch the major axis (the axis the children are tiled along). This will have a value of either X_AXIS or Y_AXIS.

getMinorAxis

public int getMinorAxis()
Fetch the minor axis (the axis orthoginal to the tiled axis). This will have a value of either X_AXIS or Y_AXIS.

getTopInset

public float getTopInset()
Get the top part of the margin around the view.

setTopInset

public void setTopInset(float i)
Set the top part of the margin around the view.

Parameters:
i - the value of the inset

getBottomInset

public float getBottomInset()
Get the bottom part of the margin around the view.

setBottomInset

public void setBottomInset(float i)
Set the bottom part of the margin around the view.

Parameters:
i - the value of the inset

getLeftInset

public float getLeftInset()
Get the left part of the margin around the view.

setLeftInset

public void setLeftInset(float i)
Set the left part of the margin around the view.

Parameters:
i - the value of the inset

getRightInset

public float getRightInset()
Get the right part of the margin around the view.

setRightInset

public void setRightInset(float i)
Set the right part of the margin around the view.

Parameters:
i - the value of the inset

getInsetSpan

protected float getInsetSpan(int axis)
Fetch the span along an axis that is taken up by the insets.

Parameters:
axis - the axis to determine the total insets along, either X_AXIS or Y_AXIS.
Since:
1.4

setEstimatedMajorSpan

protected void setEstimatedMajorSpan(boolean isEstimated)
Set the estimatedMajorSpan property that determines if the major span should be treated as being estimated. If this property is true, the value of setSize along the major axis will change the requirements along the major axis and incremental changes will be ignored until all of the children have been updated (which will cause the property to automatically be set to false). If the property is false the value of the majorSpan will be considered to be accurate and incremental changes will be added into the total as they are calculated.

Since:
1.4

getEstimatedMajorSpan

protected boolean getEstimatedMajorSpan()
Is the major span currently estimated?

Since:
1.4

getChildState

protected AsyncBoxView.ChildState getChildState(int index)
Fetch the object representing the layout state of of the child at the given index.

Parameters:
index - the child index. This should be a value >= 0 and < getViewCount().

getLayoutQueue

protected LayoutQueue getLayoutQueue()
Fetch the queue to use for layout.

createChildState

protected AsyncBoxView.ChildState createChildState(View v)
New ChildState records are created through this method to allow subclasses the extend the ChildState records to do/hold more

majorRequirementChange

protected void majorRequirementChange(AsyncBoxView.ChildState cs,
                                      float delta)
Requirements changed along the major axis. This is called by the thread doing layout for the given ChildState object when it has completed fetching the child views new preferences. Typically this would be the layout thread, but might be the event thread if it is trying to update something immediately (such as to perform a model/view translation).

This is implemented to mark the major axis as having changed so that a future check to see if the requirements need to be published to the parent view will consider the major axis. If the span along the major axis is not estimated, it is updated by the given delta to reflect the incremental change. The delta is ignored if the major span is estimated.

minorRequirementChange

protected void minorRequirementChange(AsyncBoxView.ChildState cs)
Requirements changed along the minor axis. This is called by the thread doing layout for the given ChildState object when it has completed fetching the child views new preferences. Typically this would be the layout thread, but might be the GUI thread if it is trying to update something immediately (such as to perform a model/view translation).

flushRequirementChanges

protected void flushRequirementChanges()
Publish the changes in preferences upward to the parent view. This is normally called by the layout thread.

replace

public void replace(int offset,
                    int length,
                    View[] views)
Calls the superclass to update the child views, and updates the status records for the children. This is expected to be called while a write lock is held on the model so that interaction with the layout thread will not happen (i.e. the layout thread acquires a read lock before doing anything).

Overrides:
replace in class View
Parameters:
offset - the starting offset into the child views >= 0
length - the number of existing views to replace >= 0
views - the child views to insert

loadChildren

protected void loadChildren(ViewFactory f)
Loads all of the children to initialize the view. This is called by the setParent method. Subclasses can reimplement this to initialize their child views in a different manner. The default implementation creates a child view for each child element.

Normally a write-lock is held on the Document while the children are being changed, which keeps the rendering and layout threads safe. The exception to this is when the view is initialized to represent an existing element (via this method), so it is synchronized to exclude preferenceChanged while we are initializing.

Parameters:
f - the view factory
See Also:
setParent(javax.swing.text.View)

getViewIndexAtPosition

protected int getViewIndexAtPosition(int pos,
                                     Position.Bias b)
Fetches the child view index representing the given position in the model. This is implemented to fetch the view in the case where there is a child view for each child element.

Parameters:
pos - the position >= 0
Returns:
index of the view representing the given position, or -1 if no view represents that position

updateLayout

protected void updateLayout(DocumentEvent.ElementChange ec,
                            DocumentEvent e,
                            Shape a)
Update the layout in response to receiving notification of change from the model. This is implemented to note the change on the ChildLocator so that offsets of the children will be correctly computed.

Overrides:
updateLayout in class View
Parameters:
ec - changes to the element this view is responsible for (may be null if there were no changes).
e - the change information from the associated document
a - the current allocation of the view
See Also:
View.insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory),
View.removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory),
View.changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

setParent

public void setParent(View parent)
Sets the parent of the view. This is reimplemented to provide the superclass behavior as well as calling the loadChildren method if this view does not already have children. The children should not be loaded in the constructor because the act of setting the parent may cause them to try to search up the hierarchy (to get the hosting Container for example). If this view has children (the view is being moved from one place in the view hierarchy to another), the loadChildren method will not be called.

Overrides:
setParent in class View
Parameters:
parent - the parent of the view, null if none

preferenceChanged

public void preferenceChanged(View child,
                              boolean width,
                              boolean height)
Child views can call this on the parent to indicate that the preference has changed and should be reconsidered for layout. This is reimplemented to queue new work on the layout thread. This method gets messaged from multiple threads via the children.

Overrides:
preferenceChanged in class View
Parameters:
child - the child view
width - true if the width preference has changed
height - true if the height preference has changed
See Also:
JComponent.revalidate()

setSize

public void setSize(float width,
                    float height)
Sets the size of the view. This should cause layout of the view if the view caches any layout information.

Since the major axis is updated asynchronously and should be the sum of the tiled children the call is ignored for the major axis. Since the minor axis is flexible, work is queued to resize the children if the minor span changes.

Overrides:
setSize in class View
Parameters:
width - the width >= 0
height - the height >= 0

paint

public void paint(Graphics g,
                  Shape alloc)
Render the view using the given allocation and rendering surface.

This is implemented to determine whether or not the desired region to be rendered (i.e. the unclipped area) is up to date or not. If up-to-date the children are rendered. If not up-to-date, a task to build the desired area is placed on the layout queue as a high priority task. This keeps by event thread moving by rendering if ready, and postponing until a later time if not ready (since paint requests can be rescheduled).

Specified by:
paint in class View
Parameters:
g - the rendering surface to use
alloc - the allocated region to render into
See Also:
View.paint(java.awt.Graphics, java.awt.Shape)

getPreferredSpan

public float getPreferredSpan(int axis)
Determines the preferred span for this view along an axis.

Specified by:
getPreferredSpan in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned, although there is no guarantee. The parent may choose to resize or break the view.
Throws:
IllegalArgumentException - for an invalid axis type
See Also:
View.getPreferredSpan(int)

getMinimumSpan

public float getMinimumSpan(int axis)
Determines the minimum span for this view along an axis.

Overrides:
getMinimumSpan in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned, although there is no guarantee. The parent may choose to resize or break the view.
Throws:
IllegalArgumentException - for an invalid axis type
See Also:
View.getPreferredSpan(int)

getMaximumSpan

public float getMaximumSpan(int axis)
Determines the maximum span for this view along an axis.

Overrides:
getMaximumSpan in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned, although there is no guarantee. The parent may choose to resize or break the view.
Throws:
IllegalArgumentException - for an invalid axis type
See Also:
View.getPreferredSpan(int)

getViewCount

public int getViewCount()
Returns the number of views in this view. Since the default is to not be a composite view this returns 0.

Overrides:
getViewCount in class View
Returns:
the number of views >= 0
See Also:
View.getViewCount()

getView

public View getView(int n)
Gets the nth child view. Since there are no children by default, this returns null.

Overrides:
getView in class View
Parameters:
n - the number of the view to get, >= 0 && < getViewCount()
Returns:
the view

getChildAllocation

public Shape getChildAllocation(int index,
                                Shape a)
Fetches the allocation for the given child view. This enables finding out where various views are located, without assuming the views store their location. This returns null since the default is to not have any child views.

Overrides:
getChildAllocation in class View
Parameters:
index - the index of the child, >= 0 && < getViewCount()
a - the allocation to this view.
Returns:
the allocation to the child

getViewIndex

public int getViewIndex(int pos,
                        Position.Bias b)
Returns the child view index representing the given position in the model. By default a view has no children so this is implemented to return -1 to indicate there is no valid child index for any position.

Overrides:
getViewIndex in class View
Parameters:
pos - the position >= 0
Returns:
index of the view representing the given position, or -1 if no view represents that position
Since:
1.3

modelToView

public Shape modelToView(int pos,
                         Shape a,
                         Position.Bias b)
                  throws BadLocationException
Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.

Specified by:
modelToView in class View
Parameters:
pos - the position to convert >= 0
a - the allocated region to render into
b - the bias toward the previous character or the next character represented by the offset, in case the position is a boundary of two views.
Returns:
the bounding box of the given position is returned
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
IllegalArgumentException - for an invalid bias argument
See Also:
View.viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])

viewToModel

public int viewToModel(float x,
                       float y,
                       Shape a,
                       Position.Bias[] biasReturn)
Provides a mapping from the view coordinate space to the logical coordinate space of the model. The biasReturn argument will be filled in to indicate that the point given is closer to the next character in the model or the previous character in the model.

This is expected to be called by the GUI thread, holding a read-lock on the associated model. It is implemented to locate the child view and determine it's allocation with a lock on the ChildLocator object, and to call viewToModel on the child view with a lock on the ChildState object to avoid interaction with the layout thread.

Specified by:
viewToModel in class View
Parameters:
x - the X coordinate >= 0
y - the Y coordinate >= 0
a - the allocated region to render into
Returns:
the location within the model that best represents the given point in the view >= 0. The biasReturn argument will be filled in to indicate that the point given is closer to the next character in the model or the previous character in the model.

getNextVisualPositionFrom

public int getNextVisualPositionFrom(int pos,
                                     Position.Bias b,
                                     Shape a,
                                     int direction,
                                     Position.Bias[] biasRet)
                              throws BadLocationException
Provides a way to determine the next visually represented model location that one might place a caret. Some views may not be visible, they might not be in the same order found in the model, or they just might not allow access to some of the locations in the model.

Overrides:
getNextVisualPositionFrom in class View
Parameters:
pos - the position to convert >= 0
a - the allocated region to render into
direction - the direction from the current position that can be thought of as the arrow keys typically found on a keyboard; this may be one of the following:
    SwingConstants.WEST SwingConstants.EAST SwingConstants.NORTH SwingConstants.SOUTH
biasRet - an array contain the bias that was checked
Returns:
the location within the model that best represents the next location visual position
Throws:
BadLocationException
IllegalArgumentException - if direction is invalid
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AsyncBoxView.ChildLocator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class AsyncBoxView.ChildLocator

java.lang.Object
    extended by  javax.swing.text.AsyncBoxView.ChildLocator
Enclosing class:
AsyncBoxView
public class AsyncBoxView.ChildLocator
extends Object

A class to manage the effective position of the child views in a localized area while changes are being made around the localized area. The AsyncBoxView may be continuously changing, but the visible area needs to remain fairly stable until the layout thread decides to publish an update to the parent.

Since:
1.3

Field Summary
protected Rectangle | childAlloc A shape to use for the child allocation to avoid creating a lot of garbage.
protected Rectangle | lastAlloc The last seen allocation (for repainting when changes are flushed upward).
protected AsyncBoxView.ChildState | lastValidOffset The location of the last offset calculation that is valid.
Constructor Summary
AsyncBoxView.ChildLocator()
construct a child locator.
Method Summary
void | childChanged(AsyncBoxView.ChildState cs) Notification that a child changed.
protected Shape | getChildAllocation(int index) Fetch the allocation to use for a child view.
Shape | getChildAllocation(int index, Shape a) Fetch the allocation to use for a child view.
int | getViewIndexAtPoint(float x, float y, Shape a) Fetches the child view index at the given point.
protected int | getViewIndexAtVisualOffset(float targetOffset) Locate the view responsible for an offset into the box along the major axis.
void | paintChildren(Graphics g) Paint the children that intersect the clip area.
protected void | setAllocation(Shape a) Copy the currently allocated shape into the Rectangle used to store the current allocation.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

lastValidOffset

protected AsyncBoxView.ChildState lastValidOffset
The location of the last offset calculation that is valid.

lastAlloc

protected Rectangle lastAlloc
The last seen allocation (for repainting when changes are flushed upward).

childAlloc

protected Rectangle childAlloc
A shape to use for the child allocation to avoid creating a lot of garbage.

Constructor Detail

AsyncBoxView.ChildLocator

public AsyncBoxView.ChildLocator()
construct a child locator.

Method Detail

childChanged

public void childChanged(AsyncBoxView.ChildState cs)
Notification that a child changed. This can effect whether or not new offset calculations are needed. This is called by a ChildState object that has changed it's major span. This can therefore be called by multiple threads.

paintChildren

public void paintChildren(Graphics g)
Paint the children that intersect the clip area.

getChildAllocation

public Shape getChildAllocation(int index,
                                Shape a)
Fetch the allocation to use for a child view. This will update the offsets for all children not yet updated before the given index.

getViewIndexAtPoint

public int getViewIndexAtPoint(float x,
                               float y,
                               Shape a)
Fetches the child view index at the given point. This is called by the various View methods that need to calculate which child to forward a message to. This should be called by a block synchronized on this object, and would typically be followed with one or more calls to getChildAllocation that should also be in the synchronized block.

Parameters:
x - the X coordinate >= 0
y - the Y coordinate >= 0
a - the allocation to the View
Returns:
the nearest child index

getChildAllocation

protected Shape getChildAllocation(int index)
Fetch the allocation to use for a child view. This does not update the offsets in the ChildState records.

setAllocation

protected void setAllocation(Shape a)
Copy the currently allocated shape into the Rectangle used to store the current allocation. This would be a floating point rectangle in a Java2D-specific implmentation.

getViewIndexAtVisualOffset

protected int getViewIndexAtVisualOffset(float targetOffset)
Locate the view responsible for an offset into the box along the major axis. Make sure that offsets are set on the ChildState objects up to the given target span past the desired offset.

Returns:
index of the view representing the given visual location (targetOffset), or -1 if no view represents that location
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AsyncBoxView.ChildState

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class AsyncBoxView.ChildState

java.lang.Object
    extended by  javax.swing.text.AsyncBoxView.ChildState
All Implemented Interfaces:
Runnable
Enclosing class:
AsyncBoxView
public class AsyncBoxView.ChildState
extends Object
implements Runnable

A record representing the layout state of a child view. It is runnable as a task on another thread. All access to the child view that is based upon a read-lock on the model should synchronize on this object (i.e. The layout thread and the GUI thread can both have a read lock on the model at the same time and are not protected from each other). Access to a child view hierarchy is serialized via synchronization on the ChildState instance.

Since:
1.3

Constructor Summary
AsyncBoxView.ChildState(View v)
Construct a child status.
Method Summary
View | getChildView() Fetch the child view this record represents
float | getMajorOffset() Get the offset along the major axis
float | getMajorSpan() What is the span along the major axis.
float | getMinorOffset() What is the offset along the minor axis
float | getMinorSpan() What is the span along the minor axis.
boolean | isLayoutValid() Has the child view been laid out.
void | preferenceChanged(boolean width, boolean height) Mark preferences changed for this child.
void | run() Update the child state.
void | setMajorOffset(float offs) This method should only be called by the ChildLocator, it is simply a convenient place to hold the cached location.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AsyncBoxView.ChildState

public AsyncBoxView.ChildState(View v)
Construct a child status. This needs to start out as fairly large so we don't falsely begin with the idea that all of the children are visible.

Since:
1.4
Method Detail

getChildView

public View getChildView()
Fetch the child view this record represents

run

public void run()
Update the child state. This should be called by the thread that desires to spend time updating the child state (intended to be the layout thread).

This aquires a read lock on the associated document for the duration of the update to ensure the model is not changed while it is operating. The first thing to do would be to see if any work actually needs to be done. The following could have conceivably happened while the state was waiting to be updated:

  1. The child may have been removed from the view hierarchy.
  2. The child may have been updated by a higher priority operation (i.e. the child may have become visible).

Specified by:
run in interface Runnable
See Also:
Thread.run()

getMinorSpan

public float getMinorSpan()
What is the span along the minor axis.

getMinorOffset

public float getMinorOffset()
What is the offset along the minor axis

getMajorSpan

public float getMajorSpan()
What is the span along the major axis.

getMajorOffset

public float getMajorOffset()
Get the offset along the major axis

setMajorOffset

public void setMajorOffset(float offs)
This method should only be called by the ChildLocator, it is simply a convenient place to hold the cached location.

preferenceChanged

public void preferenceChanged(boolean width,
                              boolean height)
Mark preferences changed for this child.

Parameters:
width - true if the width preference has changed
height - true if the height preference has changed
See Also:
JComponent.revalidate()

isLayoutValid

public boolean isLayoutValid()
Has the child view been laid out.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AttributeSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface AttributeSet

All Known Subinterfaces:
MutableAttributeSet, Style
All Known Implementing Classes:
AbstractDocument.AbstractElement, AbstractDocument.BranchElement, AbstractDocument.LeafElement, DefaultStyledDocument.SectionElement, HTMLDocument.BlockElement, HTMLDocument.RunElement, SimpleAttributeSet, StyleContext.NamedStyle, StyleContext.SmallAttributeSet
public interface AttributeSet

A collection of unique attributes. This is a read-only, immutable interface. An attribute is basically a key and a value assigned to the key. The collection may represent something like a style run, a logical style, etc. These are generally used to describe features that will contribute to some graphical representation such as a font. The set of possible keys is unbounded and can be anything. Typically View implementations will respond to attribute definitions and render something to represent the attributes.

Attributes can potentially resolve in a hierarchy. If a key doesn't resolve locally, and a resolving parent exists, the key will be resolved through the parent.

See Also:
MutableAttributeSet

Nested Class Summary
static interface | AttributeSet.CharacterAttribute This interface is the type signature that is expected to be present on any attribute key that contributes to character level presentation.
static interface | AttributeSet.ColorAttribute This interface is the type signature that is expected to be present on any attribute key that contributes to presentation of color.
static interface | AttributeSet.FontAttribute This interface is the type signature that is expected to be present on any attribute key that contributes to the determination of what font to use to render some text.
static interface | AttributeSet.ParagraphAttribute This interface is the type signature that is expected to be present on any attribute key that contributes to the paragraph level presentation.
Field Summary
static Object | NameAttribute Attribute name used to name the collection of attributes.
static Object | ResolveAttribute Attribute name used to identify the resolving parent set of attributes, if one is defined.
Method Summary
boolean | containsAttribute(Object name, Object value) Returns true if this set defines an attribute with the same name and an equal value.
boolean | containsAttributes(AttributeSet attributes) Returns true if this set defines all the attributes from the given set with equal values.
AttributeSet | copyAttributes() Returns an attribute set that is guaranteed not to change over time.
Object | getAttribute(Object key) Fetches the value of the given attribute.
int | getAttributeCount() Returns the number of attributes that are defined locally in this set.
Enumeration<?> | getAttributeNames() Returns an enumeration over the names of the attributes that are defined locally in the set.
AttributeSet | getResolveParent() Gets the resolving parent.
boolean | isDefined(Object attrName) Checks whether the named attribute has a value specified in the set without resolving through another attribute set.
boolean | isEqual(AttributeSet attr) Determines if the two attribute sets are equivalent.

Field Detail

NameAttribute

static final Object NameAttribute
Attribute name used to name the collection of attributes.

ResolveAttribute

static final Object ResolveAttribute
Attribute name used to identify the resolving parent set of attributes, if one is defined.

Method Detail

getAttributeCount

int getAttributeCount()
Returns the number of attributes that are defined locally in this set. Attributes that are defined in the parent set are not included.

Returns:
the number of attributes >= 0

isDefined

boolean isDefined(Object attrName)
Checks whether the named attribute has a value specified in the set without resolving through another attribute set.

Parameters:
attrName - the attribute name
Returns:
true if the attribute has a value specified

isEqual

boolean isEqual(AttributeSet attr)
Determines if the two attribute sets are equivalent.

Parameters:
attr - an attribute set
Returns:
true if the sets are equivalent

copyAttributes

AttributeSet copyAttributes()
Returns an attribute set that is guaranteed not to change over time.

Returns:
a copy of the attribute set

getAttribute

Object getAttribute(Object key)
Fetches the value of the given attribute. If the value is not found locally, the search is continued upward through the resolving parent (if one exists) until the value is either found or there are no more parents. If the value is not found, null is returned.

Parameters:
key - the non-null key of the attribute binding
Returns:
the value

getAttributeNames

Enumeration<?> getAttributeNames()
Returns an enumeration over the names of the attributes that are defined locally in the set. Names of attributes defined in the resolving parent, if any, are not included. The values of the Enumeration may be anything and are not constrained to a particular Object type.

This method never returns null. For a set with no attributes, it returns an empty Enumeration.

Returns:
the names

containsAttribute

boolean containsAttribute(Object name,
                          Object value)
Returns true if this set defines an attribute with the same name and an equal value. If such an attribute is not found locally, it is searched through in the resolving parent hierarchy.

Parameters:
name - the non-null attribute name
value - the value
Returns:
true if the set defines the attribute with an equal value, either locally or through its resolving parent
Throws:
NullPointerException - if either name or value is null

containsAttributes

boolean containsAttributes(AttributeSet attributes)
Returns true if this set defines all the attributes from the given set with equal values. If an attribute is not found locally, it is searched through in the resolving parent hierarchy.

Parameters:
attributes - the set of attributes to check against
Returns:
true if this set defines all the attributes with equal values, either locally or through its resolving parent
Throws:
NullPointerException - if attributes is null

getResolveParent

AttributeSet getResolveParent()
Gets the resolving parent.

Returns:
the parent
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BadLocationException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class BadLocationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.swing.text.BadLocationException
All Implemented Interfaces:
Serializable
public class BadLocationException
extends Exception

This exception is to report bad locations within a document model (that is, attempts to reference a location that doesn't exist).

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
BadLocationException(String s, int offs)
Creates a new BadLocationException object.
Method Summary
 int offsetRequested()
Returns the offset into the document that was not legal.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

BadLocationException

public BadLocationException(String s,
                            int offs)
Creates a new BadLocationException object.

Parameters:
s - a string indicating what was wrong with the arguments
offs - offset within the document that was requested >= 0
Method Detail

offsetRequested

public int offsetRequested()
Returns the offset into the document that was not legal.

Returns:
the offset >= 0
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BoxView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class BoxView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.CompositeView
            extended by  javax.swing.text.BoxView
All Implemented Interfaces:
SwingConstants
Direct Known Subclasses:
BlockView, FlowView, TableView, TableView.TableCell, TableView.TableRow, WrappedPlainView, ZoneView
public class BoxView
extends CompositeView

A view that arranges its children into a box shape by tiling its children along an axis. The box is somewhat like that found in TeX where there is alignment of the children, flexibility of the children is considered, etc. This is a building block that might be useful to represent things like a collection of lines, paragraphs, lists, columns, pages, etc. The axis along which the children are tiled is considered the major axis. The orthoginal axis is the minor axis.

Layout for each axis is handled separately by the methods layoutMajorAxis and layoutMinorAxis. Subclasses can change the layout algorithm by reimplementing these methods. These methods will be called as necessary depending upon whether or not there is cached layout information and the cache is considered valid. These methods are typically called if the given size along the axis changes, or if layoutChanged is called to force an updated layout. The layoutChanged method invalidates cached layout information, if there is any. The requirements published to the parent view are calculated by the methods calculateMajorAxisRequirements and calculateMinorAxisRequirements. If the layout algorithm is changed, these methods will likely need to be reimplemented.

Field Summary
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
BoxView(Element elem, int axis)
Constructs a BoxView.
Method Summary
protected void | baselineLayout(int targetSpan, int axis, int[] offsets, int[] spans) Computes the location and extent of each child view in this BoxView given the targetSpan, which is the width (or height) of the region we have to work with.
protected SizeRequirements | baselineRequirements(int axis, SizeRequirements r) Calculates the size requirements for this BoxView by examining the size of each child view.
protected SizeRequirements | calculateMajorAxisRequirements(int axis, SizeRequirements r) Calculates the size requirements for the major axis axis.
protected SizeRequirements | calculateMinorAxisRequirements(int axis, SizeRequirements r) Calculates the size requirements for the minor axis axis.
protected void | childAllocation(int index, Rectangle alloc) Allocates a region for a child view.
protected boolean | flipEastAndWestAtEnds(int position, Position.Bias bias) Determines in which direction the next view lays.
protected void | forwardUpdate(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a, ViewFactory f) Forwards the given DocumentEvent to the child views that need to be notified of the change to the model.
float | getAlignment(int axis) Determines the desired alignment for this view along an axis.
int | getAxis() Fetches the tile axis property.
Shape | getChildAllocation(int index, Shape a) Fetches the allocation for the given child view.
int | getHeight() Returns the current height of the box.
float | getMaximumSpan(int axis) Determines the maximum span for this view along an axis.
float | getMinimumSpan(int axis) Determines the minimum span for this view along an axis.
protected int | getOffset(int axis, int childIndex) Fetches the offset of a particular child's current layout.
float | getPreferredSpan(int axis) Determines the preferred span for this view along an axis.
int | getResizeWeight(int axis) Gets the resize weight.
protected int | getSpan(int axis, int childIndex) Fetches the span of a particular childs current layout.
protected View | getViewAtPoint(int x, int y, Rectangle alloc) Fetches the child view at the given coordinates.
int | getWidth() Returns the current width of the box.
protected boolean | isAfter(int x, int y, Rectangle innerAlloc) Determines if a point falls after an allocated region.
protected boolean | isAllocationValid() Are the allocations for the children still valid?
protected boolean | isBefore(int x, int y, Rectangle innerAlloc) Determines if a point falls before an allocated region.
protected boolean | isLayoutValid(int axis) Determines if the layout is valid along the given axis.
protected void | layout(int width, int height) Perform layout on the box
void | layoutChanged(int axis) Invalidates the layout along an axis.
protected void | layoutMajorAxis(int targetSpan, int axis, int[] offsets, int[] spans) Performs layout for the major axis of the box (i.e.
protected void | layoutMinorAxis(int targetSpan, int axis, int[] offsets, int[] spans) Performs layout for the minor axis of the box (i.e.
Shape | modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
void | paint(Graphics g, Shape allocation) Renders the BoxView using the given rendering surface and area on that surface.
protected void | paintChild(Graphics g, Rectangle alloc, int index) Paints a child.
void | preferenceChanged(View child, boolean width, boolean height) This is called by a child to indicate its preferred span has changed.
void | replace(int index, int length, View[] elems) Invalidates the layout and resizes the cache of requests/allocations.
void | setAxis(int axis) Sets the tile axis property.
void | setSize(float width, float height) Sets the size of the view.
int | viewToModel(float x, float y, Shape a, Position.Bias[] bias) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
Methods inherited from class javax.swing.text.CompositeView
getBottomInset, getInsideAllocation, getLeftInset, getNextEastWestVisualPositionFrom, getNextNorthSouthVisualPositionFrom, getNextVisualPositionFrom, getRightInset, getTopInset, getView, getViewAtPosition, getViewCount, getViewIndex, getViewIndexAtPosition, loadChildren, modelToView, setInsets, setParagraphInsets, setParent
Methods inherited from class javax.swing.text.View
append, breakView, changedUpdate, createFragment, forwardUpdateToView, getAttributes, getBreakWeight, getContainer, getDocument, getElement, getEndOffset, getGraphics, getParent, getStartOffset, getToolTipText, getViewFactory, getViewIndex, insert, insertUpdate, isVisible, modelToView, remove, removeAll, removeUpdate, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BoxView

public BoxView(Element elem,
               int axis)
Constructs a BoxView.

Parameters:
elem - the element this view is responsible for
axis - either View.X_AXIS or View.Y_AXIS
Method Detail

getAxis

public int getAxis()
Fetches the tile axis property. This is the axis along which the child views are tiled.

Returns:
the major axis of the box, either View.X_AXIS or View.Y_AXIS
Since:
1.3

setAxis

public void setAxis(int axis)
Sets the tile axis property. This is the axis along which the child views are tiled.

Parameters:
axis - either View.X_AXIS or View.Y_AXIS
Since:
1.3

layoutChanged

public void layoutChanged(int axis)
Invalidates the layout along an axis. This happens automatically if the preferences have changed for any of the child views. In some cases the layout may need to be recalculated when the preferences have not changed. The layout can be marked as invalid by calling this method. The layout will be updated the next time the setSize method is called on this view (typically in paint).

Parameters:
axis - either View.X_AXIS or View.Y_AXIS
Since:
1.3

isLayoutValid

protected boolean isLayoutValid(int axis)
Determines if the layout is valid along the given axis.

Parameters:
axis - either View.X_AXIS or View.Y_AXIS
Since:
1.4

paintChild

protected void paintChild(Graphics g,
                          Rectangle alloc,
                          int index)
Paints a child. By default that is all it does, but a subclass can use this to paint things relative to the child.

Parameters:
g - the graphics context
alloc - the allocated region to paint into
index - the child index, >= 0 && < getViewCount()

replace

public void replace(int index,
                    int length,
                    View[] elems)
Invalidates the layout and resizes the cache of requests/allocations. The child allocations can still be accessed for the old layout, but the new children will have an offset and span of 0.

Overrides:
replace in class CompositeView
Parameters:
index - the starting index into the child views to insert the new views; this should be a value >= 0 and <= getViewCountlength - the number of existing child views to remove; This should be a value >= 0 and <= (getViewCount()="(getViewCount()" -="-" offset)elems - the child views to add; this value can be nullto indicate no children are being added (useful to remove)

forwardUpdate

protected void forwardUpdate(DocumentEvent.ElementChange ec,
                             DocumentEvent e,
                             Shape a,
                             ViewFactory f)
Forwards the given DocumentEvent to the child views that need to be notified of the change to the model. If a child changed its requirements and the allocation was valid prior to forwarding the portion of the box from the starting child to the end of the box will be repainted.

Overrides:
forwardUpdate in class View
Parameters:
ec - changes to the element this view is responsible for (may be null if there were no changes)
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
Since:
1.3
See Also:
View.insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory),
View.removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory),
View.changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

preferenceChanged

public void preferenceChanged(View child,
                              boolean width,
                              boolean height)
This is called by a child to indicate its preferred span has changed. This is implemented to throw away cached layout information so that new calculations will be done the next time the children need an allocation.

Overrides:
preferenceChanged in class View
Parameters:
child - the child view
width - true if the width preference should change
height - true if the height preference should change
See Also:
JComponent.revalidate()

getResizeWeight

public int getResizeWeight(int axis)
Gets the resize weight. A value of 0 or less is not resizable.

Overrides:
getResizeWeight in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the weight
Throws:
IllegalArgumentException - for an invalid axis

setSize

public void setSize(float width,
                    float height)
Sets the size of the view. This should cause layout of the view if the view caches any layout information. This is implemented to call the layout method with the sizes inside of the insets.

Overrides:
setSize in class View
Parameters:
width - the width >= 0
height - the height >= 0

paint

public void paint(Graphics g,
                  Shape allocation)
Renders the BoxView using the given rendering surface and area on that surface. Only the children that intersect the clip bounds of the given Graphics will be rendered.

Specified by:
paint in class View
Parameters:
g - the rendering surface to use
allocation - the allocated region to render into
See Also:
View.paint(java.awt.Graphics, java.awt.Shape)

getChildAllocation

public Shape getChildAllocation(int index,
                                Shape a)
Fetches the allocation for the given child view. This enables finding out where various views are located. This is implemented to return null if the layout is invalid, otherwise the superclass behavior is executed.

Overrides:
getChildAllocation in class CompositeView
Parameters:
index - the index of the child, >= 0 && < getViewCount()
a - the allocation to this view
Returns:
the allocation to the child; or null if a is null; or null if the layout is invalid

modelToView

public Shape modelToView(int pos,
                         Shape a,
                         Position.Bias b)
                  throws BadLocationException
Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it. This makes sure the allocation is valid before calling the superclass.

Overrides:
modelToView in class CompositeView
Parameters:
pos - the position to convert >= 0
a - the allocated region to render into
b - a bias value of either Position.Bias.Forward or Position.Bias.Backward
Returns:
the bounding box of the given position
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
See Also:
View.modelToView(int, java.awt.Shape, javax.swing.text.Position.Bias)

viewToModel

public int viewToModel(float x,
                       float y,
                       Shape a,
                       Position.Bias[] bias)
Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Overrides:
viewToModel in class CompositeView
Parameters:
x - x coordinate of the view location to convert >= 0
y - y coordinate of the view location to convert >= 0
a - the allocated region to render into
bias - either Position.Bias.Forward or Position.Bias.Backward
Returns:
the location within the model that best represents the given point in the view >= 0
See Also:
View.viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])

getAlignment

public float getAlignment(int axis)
Determines the desired alignment for this view along an axis. This is implemented to give the total alignment needed to position the children with the alignment points lined up along the axis orthoginal to the axis that is being tiled. The axis being tiled will request to be centered (i.e. 0.5f).

Overrides:
getAlignment in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the desired alignment >= 0.0f && <= 1.0f;="1.0f;" this="this" should="should" be="be" a="a" value="value" between="between" 0.0="0.0" and="and" 1.0="1.0" where="where" 0="0" indicates="indicates" alignment="alignment" at="at" the="the" origin="origin" and="and" 1.0="1.0" indicates="indicates" alignment="alignment" to="to" the="the" full="full" span="span" away="away" from="from" the="the" origin;="origin;" an="an" alignment="alignment" of="of" 0.5="0.5" would="would" be="be" the="the" center="center" of="of" the="the" view="view" Throws:
IllegalArgumentException - for an invalid axis

getPreferredSpan

public float getPreferredSpan(int axis)
Determines the preferred span for this view along an axis.

Specified by:
getPreferredSpan in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into >= 0; typically the view is told to render into the span that is returned, although there is no guarantee; the parent may choose to resize or break the view
Throws:
IllegalArgumentException - for an invalid axis type
See Also:
View.getPreferredSpan(int)

getMinimumSpan

public float getMinimumSpan(int axis)
Determines the minimum span for this view along an axis.

Overrides:
getMinimumSpan in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into >= 0; typically the view is told to render into the span that is returned, although there is no guarantee; the parent may choose to resize or break the view
Throws:
IllegalArgumentException - for an invalid axis type
See Also:
View.getPreferredSpan(int)

getMaximumSpan

public float getMaximumSpan(int axis)
Determines the maximum span for this view along an axis.

Overrides:
getMaximumSpan in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into >= 0; typically the view is told to render into the span that is returned, although there is no guarantee; the parent may choose to resize or break the view
Throws:
IllegalArgumentException - for an invalid axis type
See Also:
View.getPreferredSpan(int)

isAllocationValid

protected boolean isAllocationValid()
Are the allocations for the children still valid?

Returns:
true if allocations still valid

isBefore

protected boolean isBefore(int x,
                           int y,
                           Rectangle innerAlloc)
Determines if a point falls before an allocated region.

Specified by:
isBefore in class CompositeView
Parameters:
x - the X coordinate >= 0
y - the Y coordinate >= 0
innerAlloc - the allocated region; this is the area inside of the insets
Returns:
true if the point lies before the region else false

isAfter

protected boolean isAfter(int x,
                          int y,
                          Rectangle innerAlloc)
Determines if a point falls after an allocated region.

Specified by:
isAfter in class CompositeView
Parameters:
x - the X coordinate >= 0
y - the Y coordinate >= 0
innerAlloc - the allocated region; this is the area inside of the insets
Returns:
true if the point lies after the region else false

getViewAtPoint

protected View getViewAtPoint(int x,
                              int y,
                              Rectangle alloc)
Fetches the child view at the given coordinates.

Specified by:
getViewAtPoint in class CompositeView
Parameters:
x - the X coordinate >= 0
y - the Y coordinate >= 0
alloc - the parents inner allocation on entry, which should be changed to the childs allocation on exit
Returns:
the view

childAllocation

protected void childAllocation(int index,
                               Rectangle alloc)
Allocates a region for a child view.

Specified by:
childAllocation in class CompositeView
Parameters:
index - the index of the child view to allocate, >= 0 && < getViewCount()
alloc - the allocated region

layout

protected void layout(int width,
                      int height)
Perform layout on the box

Parameters:
width - the width (inside of the insets) >= 0
height - the height (inside of the insets) >= 0

getWidth

public int getWidth()
Returns the current width of the box. This is the width that it was last allocated.

Returns:
the current width of the box

getHeight

public int getHeight()
Returns the current height of the box. This is the height that it was last allocated.

Returns:
the current height of the box

layoutMajorAxis

protected void layoutMajorAxis(int targetSpan,
                               int axis,
                               int[] offsets,
                               int[] spans)
Performs layout for the major axis of the box (i.e. the axis that it represents). The results of the layout (the offset and span for each children) are placed in the given arrays which represent the allocations to the children along the major axis.

Parameters:
targetSpan - the total span given to the view, which would be used to layout the children
axis - the axis being layed out
offsets - the offsets from the origin of the view for each of the child views; this is a return value and is filled in by the implementation of this method
spans - the span of each child view; this is a return value and is filled in by the implementation of this method

layoutMinorAxis

protected void layoutMinorAxis(int targetSpan,
                               int axis,
                               int[] offsets,
                               int[] spans)
Performs layout for the minor axis of the box (i.e. the axis orthoginal to the axis that it represents). The results of the layout (the offset and span for each children) are placed in the given arrays which represent the allocations to the children along the minor axis.

Parameters:
targetSpan - the total span given to the view, which would be used to layout the children
axis - the axis being layed out
offsets - the offsets from the origin of the view for each of the child views; this is a return value and is filled in by the implementation of this method
spans - the span of each child view; this is a return value and is filled in by the implementation of this method

calculateMajorAxisRequirements

protected SizeRequirements calculateMajorAxisRequirements(int axis,
                                                          SizeRequirements r)
Calculates the size requirements for the major axis axis.

Parameters:
axis - the axis being studied
r - the SizeRequirements object; if null one will be created
Returns:
the newly initialized SizeRequirements object
See Also:
SizeRequirements

calculateMinorAxisRequirements

protected SizeRequirements calculateMinorAxisRequirements(int axis,
                                                          SizeRequirements r)
Calculates the size requirements for the minor axis axis.

Parameters:
axis - the axis being studied
r - the SizeRequirements object; if null one will be created
Returns:
the newly initialized SizeRequirements object
See Also:
SizeRequirements

baselineLayout

protected void baselineLayout(int targetSpan,
                              int axis,
                              int[] offsets,
                              int[] spans)
Computes the location and extent of each child view in this BoxView given the targetSpan, which is the width (or height) of the region we have to work with.

Parameters:
targetSpan - the total span given to the view, which would be used to layout the children
axis - the axis being studied, either View.X_AXIS or View.Y_AXIS
offsets - an empty array filled by this method with values specifying the location of each child view
spans - an empty array filled by this method with values specifying the extent of each child view

baselineRequirements

protected SizeRequirements baselineRequirements(int axis,
                                                SizeRequirements r)
Calculates the size requirements for this BoxView by examining the size of each child view.

Parameters:
axis - the axis being studied
r - the SizeRequirements object; if null one will be created
Returns:
the newly initialized SizeRequirements object

getOffset

protected int getOffset(int axis,
                        int childIndex)
Fetches the offset of a particular child's current layout.

Parameters:
axis - the axis being studied
childIndex - the index of the requested child
Returns:
the offset (location) for the specified child

getSpan

protected int getSpan(int axis,
                      int childIndex)
Fetches the span of a particular childs current layout.

Parameters:
axis - the axis being studied
childIndex - the index of the requested child
Returns:
the span (width or height) of the specified child

flipEastAndWestAtEnds

protected boolean flipEastAndWestAtEnds(int position,
                                        Position.Bias bias)
Determines in which direction the next view lays. Consider the View at index n. Typically the Views are layed out from left to right, so that the View to the EAST will be at index n + 1, and the View to the WEST will be at index n - 1. In certain situations, such as with bidirectional text, it is possible that the View to EAST is not at index n + 1, but rather at index n - 1, or that the View to the WEST is not at index n - 1, but index n + 1. In this case this method would return true, indicating the Views are layed out in descending order. Otherwise the method would return false indicating the Views are layed out in ascending order.

If the receiver is laying its Views along the Y_AXIS, this will will return the value from invoking the same method on the View responsible for rendering position and bias. Otherwise this will return false.

Overrides:
flipEastAndWestAtEnds in class CompositeView
Parameters:
position - position into the model
bias - either Position.Bias.Forward or Position.Bias.Backward
Returns:
true if the Views surrounding the View responding for rendering position and bias are layed out in descending order; otherwise false
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Caret

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface Caret

All Known Implementing Classes:
BasicTextUI.BasicCaret, DefaultCaret
public interface Caret

A place within a document view that represents where things can be inserted into the document model. A caret has a position in the document referred to as a dot. The dot is where the caret is currently located in the model. There is a second position maintained by the caret that represents the other end of a selection called mark. If there is no selection the dot and mark will be equal. If a selection exists, the two values will be different.

The dot can be placed by either calling setDot or moveDot. Setting the dot has the effect of removing any selection that may have previously existed. The dot and mark will be equal. Moving the dot has the effect of creating a selection as the mark is left at whatever position it previously had.

Method Summary
void | addChangeListener(ChangeListener l) Adds a listener to track whenever the caret position has been changed.
void | deinstall(JTextComponent c) Called when the UI is being removed from the interface of a JTextComponent.
int | getBlinkRate() Gets the blink rate of the caret.
int | getDot() Fetches the current position of the caret.
Point | getMagicCaretPosition() Gets the current caret visual location.
int | getMark() Fetches the current position of the mark.
void | install(JTextComponent c) Called when the UI is being installed into the interface of a JTextComponent.
boolean | isSelectionVisible() Determines if the selection is currently visible.
boolean | isVisible() Determines if the caret is currently visible.
void | moveDot(int dot) Moves the caret position (dot) to some other position, leaving behind the mark.
void | paint(Graphics g) Renders the caret.
void | removeChangeListener(ChangeListener l) Removes a listener that was tracking caret position changes.
void | setBlinkRate(int rate) Sets the blink rate of the caret.
void | setDot(int dot) Sets the caret position to some position.
void | setMagicCaretPosition(Point p) Set the current caret visual location.
void | setSelectionVisible(boolean v) Sets the visibility of the selection
void | setVisible(boolean v) Sets the visibility of the caret.

Method Detail

install

void install(JTextComponent c)
Called when the UI is being installed into the interface of a JTextComponent. This can be used to gain access to the model that is being navigated by the implementation of this interface.

Parameters:
c - the JTextComponent

deinstall

void deinstall(JTextComponent c)
Called when the UI is being removed from the interface of a JTextComponent. This is used to unregister any listeners that were attached.

Parameters:
c - the JTextComponent

paint

void paint(Graphics g)
Renders the caret. This method is called by UI classes.

Parameters:
g - the graphics context

addChangeListener

void addChangeListener(ChangeListener l)
Adds a listener to track whenever the caret position has been changed.

Parameters:
l - the change listener

removeChangeListener

void removeChangeListener(ChangeListener l)
Removes a listener that was tracking caret position changes.

Parameters:
l - the change listener

isVisible

boolean isVisible()
Determines if the caret is currently visible.

Returns:
true if the caret is visible else false

setVisible

void setVisible(boolean v)
Sets the visibility of the caret.

Parameters:
v - true if the caret should be shown, and false if the caret should be hidden

isSelectionVisible

boolean isSelectionVisible()
Determines if the selection is currently visible.

Returns:
true if the caret is visible else false

setSelectionVisible

void setSelectionVisible(boolean v)
Sets the visibility of the selection

Parameters:
v - true if the caret should be shown, and false if the caret should be hidden

setMagicCaretPosition

void setMagicCaretPosition(Point p)
Set the current caret visual location. This can be used when moving between lines that have uneven end positions (such as when caret up or down actions occur). If text flows left-to-right or right-to-left the x-coordinate will indicate the desired navigation location for vertical movement. If the text flow is top-to-bottom, the y-coordinate will indicate the desired navigation location for horizontal movement.

Parameters:
p - the Point to use for the saved position. This can be null to indicate there is no visual location.

getMagicCaretPosition

Point getMagicCaretPosition()
Gets the current caret visual location.

Returns:
the visual position.
See Also:
setMagicCaretPosition(java.awt.Point)

setBlinkRate

void setBlinkRate(int rate)
Sets the blink rate of the caret. This determines if and how fast the caret blinks, commonly used as one way to attract attention to the caret.

Parameters:
rate - the delay in milliseconds >= 0. If this is zero the caret will not blink.

getBlinkRate

int getBlinkRate()
Gets the blink rate of the caret. This determines if and how fast the caret blinks, commonly used as one way to attract attention to the caret.

Returns:
the delay in milliseconds >= 0. If this is zero the caret will not blink.

getDot

int getDot()
Fetches the current position of the caret.

Returns:
the position >= 0

getMark

int getMark()
Fetches the current position of the mark. If there is a selection, the mark will not be the same as the dot.

Returns:
the position >= 0

setDot

void setDot(int dot)
Sets the caret position to some position. This causes the mark to become the same as the dot, effectively setting the selection range to zero.

If the parameter is negative or beyond the length of the document, the caret is placed at the beginning or at the end, respectively.

Parameters:
dot - the new position to set the caret to

moveDot

void moveDot(int dot)
Moves the caret position (dot) to some other position, leaving behind the mark. This is useful for making selections.

Parameters:
dot - the new position to move the caret to >= 0
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ChangedCharSetException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class ChangedCharSetException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.io.IOException
                extended by  javax.swing.text.ChangedCharSetException
All Implemented Interfaces:
Serializable
public class ChangedCharSetException
extends IOException

ChangedCharSetException as the name indicates is an exception thrown when the charset is changed.

Constructor Summary
ChangedCharSetException(String charSetSpec, boolean charSetKey)
Method Summary
String | getCharSetSpec()
boolean | keyEqualsCharSet()
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ChangedCharSetException

public ChangedCharSetException(String charSetSpec,
                               boolean charSetKey)
Method Detail

getCharSetSpec

public String getCharSetSpec()

keyEqualsCharSet

public boolean keyEqualsCharSet()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.swing.text.AbstractDocument

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.AbstractDocument

Packages that use AbstractDocument
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of AbstractDocument in javax.swing.text

Subclasses of AbstractDocument in javax.swing.text
class | DefaultStyledDocument A document that can be marked up with character and paragraph styles in a manner similar to the Rich Text Format.
class | PlainDocument A plain document that maintains no character attributes.

Uses of AbstractDocument in javax.swing.text.html

Subclasses of AbstractDocument in javax.swing.text.html
 class HTMLDocument
A document that models HTML.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.AbstractDocument.AbstractElement

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.AbstractDocument.AbstractElement

Packages that use AbstractDocument.AbstractElement
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of AbstractDocument.AbstractElement in javax.swing.text

Subclasses of AbstractDocument.AbstractElement in javax.swing.text
class | AbstractDocument.BranchElement Implements a composite element that contains other elements.
class | AbstractDocument.LeafElement Implements an element that directly represents content of some kind.
protected class | DefaultStyledDocument.SectionElement Default root element for a document...

Methods in javax.swing.text that return AbstractDocument.AbstractElement
protected AbstractDocument.AbstractElement | PlainDocument.createDefaultRoot() Creates the root element to be used to represent the default document structure.
protected AbstractDocument.AbstractElement | DefaultStyledDocument.createDefaultRoot() Creates the root element to be used to represent the default document structure.

Uses of AbstractDocument.AbstractElement in javax.swing.text.html

Subclasses of AbstractDocument.AbstractElement in javax.swing.text.html
class | HTMLDocument.BlockElement An element that represents a structural block of HTML.
class | HTMLDocument.RunElement An element that represents a chunk of text that has a set of HTML character level attributes assigned to it.

Methods in javax.swing.text.html that return AbstractDocument.AbstractElement
protected  AbstractDocument.AbstractElement HTMLDocument.createDefaultRoot()
Creates the root element to be used to represent the default document structure.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.AbstractDocument.BranchElement

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.AbstractDocument.BranchElement

Packages that use AbstractDocument.BranchElement
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of AbstractDocument.BranchElement in javax.swing.text

Subclasses of AbstractDocument.BranchElement in javax.swing.text
protected  class DefaultStyledDocument.SectionElement
Default root element for a document...

Uses of AbstractDocument.BranchElement in javax.swing.text.html

Subclasses of AbstractDocument.BranchElement in javax.swing.text.html
 class HTMLDocument.BlockElement
An element that represents a structural block of HTML.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.AbstractDocument.DefaultDocumentEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.AbstractDocument.DefaultDocumentEvent

Packages that use AbstractDocument.DefaultDocumentEvent
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of AbstractDocument.DefaultDocumentEvent in javax.swing.text

Methods in javax.swing.text with parameters of type AbstractDocument.DefaultDocumentEvent
void | DefaultStyledDocument.ElementBuffer.change(int offset, int length, AbstractDocument.DefaultDocumentEvent de) Changes content.
void | DefaultStyledDocument.ElementBuffer.insert(int offset, int length, DefaultStyledDocument.ElementSpec[] data, AbstractDocument.DefaultDocumentEvent de) Inserts new content.
protected void | PlainDocument.insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr) Updates document structure as a result of text insertion.
protected void | DefaultStyledDocument.insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr) Updates document structure as a result of text insertion.
protected void | AbstractDocument.insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr) Updates document structure as a result of text insertion.
protected void | AbstractDocument.postRemoveUpdate(AbstractDocument.DefaultDocumentEvent chng) Updates any document structure as a result of text removal.
void | DefaultStyledDocument.ElementBuffer.remove(int offset, int length, AbstractDocument.DefaultDocumentEvent de) Removes content.
protected void | PlainDocument.removeUpdate(AbstractDocument.DefaultDocumentEvent chng) Updates any document structure as a result of text removal.
protected void | DefaultStyledDocument.removeUpdate(AbstractDocument.DefaultDocumentEvent chng) Updates document structure as a result of text removal.
protected void | AbstractDocument.removeUpdate(AbstractDocument.DefaultDocumentEvent chng) Updates any document structure as a result of text removal.

Uses of AbstractDocument.DefaultDocumentEvent in javax.swing.text.html

Methods in javax.swing.text.html with parameters of type AbstractDocument.DefaultDocumentEvent
protected  void HTMLDocument.insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr)
Updates document structure as a result of text insertion.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.AbstractDocument.ElementEdit

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.AbstractDocument.ElementEdit

No usage of javax.swing.text.AbstractDocument.ElementEdit

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.AbstractDocument.LeafElement

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.AbstractDocument.LeafElement

Packages that use AbstractDocument.LeafElement
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of AbstractDocument.LeafElement in javax.swing.text.html

Subclasses of AbstractDocument.LeafElement in javax.swing.text.html
 class HTMLDocument.RunElement
An element that represents a chunk of text that has a set of HTML character level attributes assigned to it.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.AbstractWriter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.AbstractWriter

Packages that use AbstractWriter
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of AbstractWriter in javax.swing.text.html

Subclasses of AbstractWriter in javax.swing.text.html
class | HTMLWriter This is a writer for HTMLDocuments.
class | MinimalHTMLWriter MinimalHTMLWriter is a fallback writer used by the HTMLEditorKit to write out HTML for a document that is a not produced by the EditorKit.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.AsyncBoxView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.AsyncBoxView

No usage of javax.swing.text.AsyncBoxView

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.AsyncBoxView.ChildLocator

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.AsyncBoxView.ChildLocator

Packages that use AsyncBoxView.ChildLocator
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of AsyncBoxView.ChildLocator in javax.swing.text

Fields in javax.swing.text declared as AsyncBoxView.ChildLocator
protected  AsyncBoxView.ChildLocator AsyncBoxView.locator
Object that manages the offsets of the children.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.AsyncBoxView.ChildState

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.AsyncBoxView.ChildState

Packages that use AsyncBoxView.ChildState
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of AsyncBoxView.ChildState in javax.swing.text

Fields in javax.swing.text declared as AsyncBoxView.ChildState
protected  AsyncBoxView.ChildState AsyncBoxView.ChildLocator.lastValidOffset
The location of the last offset calculation that is valid.

Methods in javax.swing.text that return AsyncBoxView.ChildState
protected AsyncBoxView.ChildState | AsyncBoxView.createChildState(View v) New ChildState records are created through this method to allow subclasses the extend the ChildState records to do/hold more
protected AsyncBoxView.ChildState | AsyncBoxView.getChildState(int index) Fetch the object representing the layout state of of the child at the given index.

Methods in javax.swing.text with parameters of type AsyncBoxView.ChildState
void | AsyncBoxView.ChildLocator.childChanged(AsyncBoxView.ChildState cs) Notification that a child changed.
protected void | AsyncBoxView.majorRequirementChange(AsyncBoxView.ChildState cs, float delta) Requirements changed along the major axis.
protected void | AsyncBoxView.minorRequirementChange(AsyncBoxView.ChildState cs) Requirements changed along the minor axis.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.BadLocationException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.BadLocationException

Packages that use BadLocationException
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.
javax.swing.text.rtf | Provides a class (RTFEditorKit) for creating Rich-Text-Format text editors.

Uses of BadLocationException in javax.swing

Methods in javax.swing that throw BadLocationException
int | JTextArea.getLineEndOffset(int line) Determines the offset of the end of the given line.
int | JTextArea.getLineOfOffset(int offset) Translates an offset into the components text to a line number.
int | JTextArea.getLineStartOffset(int line) Determines the offset of the start of the given line.
String | JPasswordField.getText(int offs, int len) Deprecated. As of Java 2 platform v1.2, replaced by getPassword.

Uses of BadLocationException in javax.swing.plaf

Methods in javax.swing.plaf that throw BadLocationException
abstract int | TextUI.getNextVisualPositionFrom(JTextComponent t, int pos, Position.Bias b, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
abstract Rectangle | TextUI.modelToView(JTextComponent t, int pos) Converts the given location in the model to a place in the view coordinate system.
abstract Rectangle | TextUI.modelToView(JTextComponent t, int pos, Position.Bias bias) Converts the given location in the model to a place in the view coordinate system.

Uses of BadLocationException in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic that throw BadLocationException
int | BasicTextUI.getNextVisualPositionFrom(JTextComponent t, int pos, Position.Bias b, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
Rectangle | BasicTextUI.modelToView(JTextComponent tc, int pos) Converts the given location in the model to a place in the view coordinate system.
Rectangle | BasicTextUI.modelToView(JTextComponent tc, int pos, Position.Bias bias) Converts the given location in the model to a place in the view coordinate system.

Uses of BadLocationException in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi that throw BadLocationException
int | MultiTextUI.getNextVisualPositionFrom(JTextComponent a, int b, Position.Bias c, int d, Position.Bias[] e) Invokes the getNextVisualPositionFrom method on each UI handled by this object.
Rectangle | MultiTextUI.modelToView(JTextComponent a, int b) Invokes the modelToView method on each UI handled by this object.
Rectangle | MultiTextUI.modelToView(JTextComponent a, int b, Position.Bias c) Invokes the modelToView method on each UI handled by this object.

Uses of BadLocationException in javax.swing.text

Methods in javax.swing.text that throw BadLocationException
Object | DefaultHighlighter.addHighlight(int p0, int p1, Highlighter.HighlightPainter p) Adds a highlight to the view.
Object | Highlighter.addHighlight(int p0, int p1, Highlighter.HighlightPainter p) Adds a highlight to the view.
void | DefaultHighlighter.changeHighlight(Object tag, int p0, int p1) Changes a highlight.
void | Highlighter.changeHighlight(Object tag, int p0, int p1) Changes the given highlight to span a different portion of the document.
Position | StringContent.createPosition(int offset) Creates a position within the content that will track change as the content is mutated.
Position | GapContent.createPosition(int offset) Creates a position within the content that will track change as the content is mutated.
Position | AbstractDocument.createPosition(int offs) Returns a position that will track change as the document is altered.
Position | AbstractDocument.Content.createPosition(int offset) Creates a position within the content that will track change as the content is mutated.
Position | Document.createPosition(int offs) This method allows an application to mark a place in a sequence of character content.
protected int | PasswordView.drawSelectedText(Graphics g, int x, int y, int p0, int p1) Renders the given range in the model as selected text.
protected int | WrappedPlainView.drawSelectedText(Graphics g, int x, int y, int p0, int p1) Renders the given range in the model as selected text.
protected int | PlainView.drawSelectedText(Graphics g, int x, int y, int p0, int p1) Renders the given range in the model as selected text.
protected int | PasswordView.drawUnselectedText(Graphics g, int x, int y, int p0, int p1) Renders the given range in the model as normal unselected text.
protected int | WrappedPlainView.drawUnselectedText(Graphics g, int x, int y, int p0, int p1) Renders the given range in the model as normal unselected text.
protected int | PlainView.drawUnselectedText(Graphics g, int x, int y, int p0, int p1) Renders the given range in the model as normal unselected text.
void | StringContent.getChars(int where, int len, Segment chars) Retrieves a portion of the content.
void | GapContent.getChars(int where, int len, Segment chars) Retrieves a portion of the content.
void | AbstractDocument.Content.getChars(int where, int len, Segment txt) Gets a sequence of characters and copies them into a Segment.
protected int | ParagraphView.getClosestPositionTo(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet, int rowIndex, int x) Returns the closest model position to x.
protected int | CompositeView.getNextEastWestVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Returns the next visual position for the cursor, in either the east or west direction.
protected int | ParagraphView.getNextNorthSouthVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Returns the next visual position for the cursor, in either the east or west direction.
protected int | CompositeView.getNextNorthSouthVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Returns the next visual position for the cursor, in either the north or south direction.
int | GlyphView.GlyphPainter.getNextVisualPositionFrom(GlyphView v, int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
int | AsyncBoxView.getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
int | GlyphView.getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
int | CompositeView.getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
int | View.getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location at which one might place a caret.
int | NavigationFilter.getNextVisualPositionFrom(JTextComponent text, int pos, Position.Bias bias, int direction, Position.Bias[] biasRet) Returns the next visual position to place the caret at from an existing position.
static int | Utilities.getNextWord(JTextComponent c, int offs) Determines the start of the next word for the given location.
static int | Utilities.getPositionAbove(JTextComponent c, int offs, int x) Determines the position in the model that is closest to the given view location in the row above.
static int | Utilities.getPositionBelow(JTextComponent c, int offs, int x) Determines the position in the model that is closest to the given view location in the row below.
static int | Utilities.getPreviousWord(JTextComponent c, int offs) Determine the start of the prev word for the given location.
static int | Utilities.getRowEnd(JTextComponent c, int offs) Determines the ending row model position of the row that contains the specified model position.
static int | Utilities.getRowStart(JTextComponent c, int offs) Determines the starting row model position of the row that contains the specified model position.
String | StringContent.getString(int where, int len) Retrieves a portion of the content.
String | GapContent.getString(int where, int len) Retrieves a portion of the content.
String | AbstractDocument.Content.getString(int where, int len) Fetches a string of characters contained in the sequence.
protected String | AbstractWriter.getText(Element elem) Returns the text associated with the element.
String | AbstractDocument.getText(int offset, int length) Gets a sequence of text from the document.
String | JTextComponent.getText(int offs, int len) Fetches a portion of the text represented by the component.
String | Document.getText(int offset, int length) Fetches the text contained within the given portion of the document.
void | AbstractDocument.getText(int offset, int length, Segment txt) Fetches the text contained within the given portion of the document.
void | Document.getText(int offset, int length, Segment txt) Fetches the text contained within the given portion of the document.
static int | Utilities.getWordEnd(JTextComponent c, int offs) Determines the end of a word for the given location.
static int | Utilities.getWordStart(JTextComponent c, int offs) Determines the start of a word for the given model location.
protected void | DefaultStyledDocument.insert(int offset, DefaultStyledDocument.ElementSpec[] data) Inserts new elements in bulk.
void | DocumentFilter.insertString(DocumentFilter.FilterBypass fb, int offset, String string, AttributeSet attr) Invoked prior to insertion of text into the specified Document.
UndoableEdit | StringContent.insertString(int where, String str) Inserts a string into the content.
UndoableEdit | GapContent.insertString(int where, String str) Inserts a string into the content.
UndoableEdit | AbstractDocument.Content.insertString(int where, String str) Inserts a string of characters into the sequence.
void | PlainDocument.insertString(int offs, String str, AttributeSet a) Inserts some content into the document.
void | AbstractDocument.insertString(int offs, String str, AttributeSet a) Inserts some content into the document.
abstract void | DocumentFilter.FilterBypass.insertString(int offset, String string, AttributeSet attr) Inserts the specified text, bypassing the DocumentFilter.
void | Document.insertString(int offset, String str, AttributeSet a) Inserts a string of content.
abstract Shape | GlyphView.GlyphPainter.modelToView(GlyphView v, int pos, Position.Bias bias, Shape a) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Rectangle | JTextComponent.modelToView(int pos) Converts the given location in the model to a place in the view coordinate system.
Shape | CompositeView.modelToView(int p0, Position.Bias b0, int p1, Position.Bias b1, Shape a) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | View.modelToView(int p0, Position.Bias b0, int p1, Position.Bias b1, Shape a) Provides a mapping, for a given region, from the document model coordinate space to the view coordinate space.
Shape | View.modelToView(int pos, Shape a) Deprecated.
Shape | PasswordView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | FieldView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | AsyncBoxView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | PlainView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | IconView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | BoxView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | ComponentView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the coordinate space of the model to that of the view.
Shape | GlyphView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | CompositeView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
abstract Shape | View.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping, for a given character, from the document model coordinate space to the view coordinate space.
void | DefaultEditorKit.read(InputStream in, Document doc, int pos) Inserts content from the given stream which is expected to be in a format appropriate for this kind of content handler.
abstract void | EditorKit.read(InputStream in, Document doc, int pos) Inserts content from the given stream which is expected to be in a format appropriate for this kind of content handler.
void | DefaultEditorKit.read(Reader in, Document doc, int pos) Inserts content from the given stream, which will be treated as plain text.
abstract void | EditorKit.read(Reader in, Document doc, int pos) Inserts content from the given stream which is expected to be in a format appropriate for this kind of content handler.
void | DocumentFilter.remove(DocumentFilter.FilterBypass fb, int offset, int length) Invoked prior to removal of the specified region in the specified Document.
UndoableEdit | StringContent.remove(int where, int nitems) Removes part of the content.
UndoableEdit | GapContent.remove(int where, int nitems) Removes part of the content.
void | AbstractDocument.remove(int offs, int len) Removes some content from the document.
UndoableEdit | AbstractDocument.Content.remove(int where, int nitems) Removes some portion of the sequence.
abstract void | DocumentFilter.FilterBypass.remove(int offset, int length) Removes the specified region of text, bypassing the DocumentFilter.
void | Document.remove(int offs, int len) Removes a portion of the content of the document.
void | DocumentFilter.replace(DocumentFilter.FilterBypass fb, int offset, int length, String text, AttributeSet attrs) Invoked prior to replacing a region of text in the specified Document.
void | AbstractDocument.replace(int offset, int length, String text, AttributeSet attrs) Deletes the region of text from offset to offset + length, and replaces it with text.
abstract void | DocumentFilter.FilterBypass.replace(int offset, int length, String string, AttributeSet attrs) Deletes the region of text from offset to offset + length, and replaces it with text.
protected void | AbstractWriter.text(Element elem) Writes out text.
protected abstract void | AbstractWriter.write() This abstract method needs to be implemented by subclasses.
void | DefaultEditorKit.write(OutputStream out, Document doc, int pos, int len) Writes content from a document to the given stream in a format appropriate for this kind of content handler.
abstract void | EditorKit.write(OutputStream out, Document doc, int pos, int len) Writes content from a document to the given stream in a format appropriate for this kind of content handler.
void | DefaultEditorKit.write(Writer out, Document doc, int pos, int len) Writes content from a document to the given stream as plain text.
abstract void | EditorKit.write(Writer out, Document doc, int pos, int len) Writes content from a document to the given stream in a format appropriate for this kind of content handler.

Uses of BadLocationException in javax.swing.text.html

Methods in javax.swing.text.html that throw BadLocationException
protected void | HTMLWriter.comment(Element elem) Writes out comments.
protected void | HTMLWriter.emptyTag(Element elem) Writes out all empty elements (all tags that have no corresponding end tag).
void | HTMLEditorKit.ParserCallback.flush()
void | HTMLDocument.HTMLReader.flush() The last method called on the reader.
protected void | HTMLDocument.insert(int offset, DefaultStyledDocument.ElementSpec[] data) Inserts new elements in bulk.
void | HTMLDocument.insertAfterEnd(Element elem, String htmlText) Inserts the HTML specified as a string after the the end of the given element.
void | HTMLDocument.insertAfterStart(Element elem, String htmlText) Inserts the HTML specified as a string at the start of the element.
void | HTMLDocument.insertBeforeEnd(Element elem, String htmlText) Inserts the HTML specified as a string at the end of the element.
void | HTMLDocument.insertBeforeStart(Element elem, String htmlText) Inserts the HTML specified as a string before the start of the given element.
void | HTMLEditorKit.insertHTML(HTMLDocument doc, int offset, String html, int popDepth, int pushDepth, HTML.Tag insertTag) Inserts HTML into an existing document.
Shape | ImageView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
void | HTMLEditorKit.read(Reader in, Document doc, int pos) Inserts content from the given stream.
void | HTMLDocument.setInnerHTML(Element elem, String htmlText) Replaces the children of the given element with the contents specified as an HTML string.
void | HTMLDocument.setOuterHTML(Element elem, String htmlText) Replaces the given element in the parent with the contents specified as an HTML string.
protected void | HTMLWriter.startTag(Element elem) Writes out a start tag for the element.
protected void | HTMLWriter.text(Element elem) Writes out text.
protected void | MinimalHTMLWriter.text(Element elem) Writes out text.
protected void | HTMLWriter.textAreaContent(AttributeSet attr) Writes out text that is contained in a TEXTAREA form element.
void | HTMLWriter.write() Iterates over the Element tree and controls the writing out of all the tags and its attributes.
void | MinimalHTMLWriter.write() Generates HTML output from a StyledDocument.
void | HTMLEditorKit.write(Writer out, Document doc, int pos, int len) Write content from a document to the given stream in a format appropriate for this kind of content handler.
protected void | MinimalHTMLWriter.writeBody() Iterates over the elements in the document and processes elements based on whether they are branch elements or leaf elements.
protected void | MinimalHTMLWriter.writeContent(Element elem, boolean needsIndenting) Writes out the attribute set in an HTML-compliant manner.

Uses of BadLocationException in javax.swing.text.rtf

Methods in javax.swing.text.rtf that throw BadLocationException
void | RTFEditorKit.read(InputStream in, Document doc, int pos) Insert content from the given stream which is expected to be in a format appropriate for this kind of content handler.
void | RTFEditorKit.read(Reader in, Document doc, int pos) Insert content from the given stream, which will be treated as plain text.
void | RTFEditorKit.write(OutputStream out, Document doc, int pos, int len) Write content from a document to the given stream in a format appropriate for this kind of content handler.
void | RTFEditorKit.write(Writer out, Document doc, int pos, int len) Write content from a document to the given stream as plain text.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.BoxView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.BoxView

Packages that use BoxView
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of BoxView in javax.swing.text

Subclasses of BoxView in javax.swing.text
class | FlowView A View that tries to flow it's children into some partially constrained space.
class | ParagraphView View of a simple line-wrapping paragraph that supports multiple fonts, colors, components, icons, etc.
class | TableView Implements View interface for a table, that is composed of an element structure where the child elements of the element this view is responsible for represent rows and the child elements of the row elements are cells.
class | TableView.TableCell Deprecated. A table cell can now be any View implementation.
class | TableView.TableRow View of a row in a row-centric table.
class | WrappedPlainView View of plain text (text with only one font and color) that does line-wrapping.
class | ZoneView ZoneView is a View implementation that creates zones for which the child views are not created or stored until they are needed for display or model/view translations.

Uses of BoxView in javax.swing.text.html

Subclasses of BoxView in javax.swing.text.html
class | BlockView A view implementation to display a block (as a box) with CSS specifications.
class | ListView A view implementation to display an html list

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.ChangedCharSetException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.ChangedCharSetException

Packages that use ChangedCharSetException
javax.swing.text.html.parser Provides the default HTML parser, along with support classes.

Uses of ChangedCharSetException in javax.swing.text.html.parser

Methods in javax.swing.text.html.parser that throw ChangedCharSetException
protected void | DocumentParser.handleEmptyTag(TagElement tag) Handle Empty Tag.
protected void | Parser.handleEmptyTag(TagElement tag) Called when an empty tag is encountered.
protected void | Parser.startTag(TagElement tag) Handle a start tag.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.ComponentView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.ComponentView

Packages that use ComponentView
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of ComponentView in javax.swing.text.html

Subclasses of ComponentView in javax.swing.text.html
class | FormView Component decorator that implements the view interface for form elements, <input>, <textarea>, and <select>.
class | ObjectView Component decorator that implements the view interface for <object> elements.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.CompositeView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.CompositeView

Packages that use CompositeView
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of CompositeView in javax.swing.text

Subclasses of CompositeView in javax.swing.text
class | BoxView A view that arranges its children into a box shape by tiling its children along an axis.
class | FlowView A View that tries to flow it's children into some partially constrained space.
class | ParagraphView View of a simple line-wrapping paragraph that supports multiple fonts, colors, components, icons, etc.
class | TableView Implements View interface for a table, that is composed of an element structure where the child elements of the element this view is responsible for represent rows and the child elements of the row elements are cells.
class | TableView.TableCell Deprecated. A table cell can now be any View implementation.
class | TableView.TableRow View of a row in a row-centric table.
class | WrappedPlainView View of plain text (text with only one font and color) that does line-wrapping.
class | ZoneView ZoneView is a View implementation that creates zones for which the child views are not created or stored until they are needed for display or model/view translations.

Uses of CompositeView in javax.swing.text.html

Subclasses of CompositeView in javax.swing.text.html
class | BlockView A view implementation to display a block (as a box) with CSS specifications.
class | ListView A view implementation to display an html list

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DateFormatter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DateFormatter

No usage of javax.swing.text.DateFormatter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultCaret

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultCaret

Packages that use DefaultCaret
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of DefaultCaret in javax.swing.plaf.basic

Subclasses of DefaultCaret in javax.swing.plaf.basic
static class BasicTextUI.BasicCaret

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultEditorKit

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultEditorKit

Packages that use DefaultEditorKit
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.
javax.swing.text.rtf | Provides a class (RTFEditorKit) for creating Rich-Text-Format text editors.

Uses of DefaultEditorKit in javax.swing.text

Subclasses of DefaultEditorKit in javax.swing.text
 class StyledEditorKit
This is the set of things needed by a text component to be a reasonably functioning editor for some type of text document.

Uses of DefaultEditorKit in javax.swing.text.html

Subclasses of DefaultEditorKit in javax.swing.text.html
 class HTMLEditorKit
The Swing JEditorPane text component supports different kinds of content via a plug-in mechanism called an EditorKit.

Uses of DefaultEditorKit in javax.swing.text.rtf

Subclasses of DefaultEditorKit in javax.swing.text.rtf
 class RTFEditorKit
This is the default implementation of RTF editing functionality.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultEditorKit.BeepAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultEditorKit.BeepAction

No usage of javax.swing.text.DefaultEditorKit.BeepAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultEditorKit.CopyAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultEditorKit.CopyAction

No usage of javax.swing.text.DefaultEditorKit.CopyAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultEditorKit.CutAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultEditorKit.CutAction

No usage of javax.swing.text.DefaultEditorKit.CutAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultEditorKit.DefaultKeyTypedAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultEditorKit.DefaultKeyTypedAction

No usage of javax.swing.text.DefaultEditorKit.DefaultKeyTypedAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultEditorKit.InsertBreakAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultEditorKit.InsertBreakAction

No usage of javax.swing.text.DefaultEditorKit.InsertBreakAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultEditorKit.InsertContentAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultEditorKit.InsertContentAction

No usage of javax.swing.text.DefaultEditorKit.InsertContentAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultEditorKit.InsertTabAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultEditorKit.InsertTabAction

No usage of javax.swing.text.DefaultEditorKit.InsertTabAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultEditorKit.PasteAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultEditorKit.PasteAction

No usage of javax.swing.text.DefaultEditorKit.PasteAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultFormatter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultFormatter

Packages that use DefaultFormatter
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of DefaultFormatter in javax.swing.text

Subclasses of DefaultFormatter in javax.swing.text
class | DateFormatter DateFormatter is an InternationalFormatter that does its formatting by way of an instance of java.text.DateFormat.
class | InternationalFormatter InternationalFormatter extends DefaultFormatter, using an instance of java.text.Format to handle the conversion to a String, and the conversion from a String.
class | MaskFormatter MaskFormatter is used to format and edit strings.
class | NumberFormatter NumberFormatter subclasses InternationalFormatter adding special behavior for numbers.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultFormatterFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultFormatterFactory

No usage of javax.swing.text.DefaultFormatterFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultHighlighter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultHighlighter

Packages that use DefaultHighlighter
javax.swing.plaf.basic Provides user interface objects built according to the Basic look and feel.

Uses of DefaultHighlighter in javax.swing.plaf.basic

Subclasses of DefaultHighlighter in javax.swing.plaf.basic
static class BasicTextUI.BasicHighlighter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultHighlighter.DefaultHighlightPainter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultHighlighter.DefaultHighlightPainter

No usage of javax.swing.text.DefaultHighlighter.DefaultHighlightPainter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultStyledDocument

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultStyledDocument

Packages that use DefaultStyledDocument
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of DefaultStyledDocument in javax.swing.text.html

Subclasses of DefaultStyledDocument in javax.swing.text.html
 class HTMLDocument
A document that models HTML.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultStyledDocument.AttributeUndoableEdit

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultStyledDocument.AttributeUndoableEdit

No usage of javax.swing.text.DefaultStyledDocument.AttributeUndoableEdit

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultStyledDocument.ElementBuffer

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultStyledDocument.ElementBuffer

Packages that use DefaultStyledDocument.ElementBuffer
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of DefaultStyledDocument.ElementBuffer in javax.swing.text

Fields in javax.swing.text declared as DefaultStyledDocument.ElementBuffer
protected  DefaultStyledDocument.ElementBuffer DefaultStyledDocument.buffer

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultStyledDocument.ElementSpec

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultStyledDocument.ElementSpec

Packages that use DefaultStyledDocument.ElementSpec
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of DefaultStyledDocument.ElementSpec in javax.swing.text

Methods in javax.swing.text with parameters of type DefaultStyledDocument.ElementSpec
protected void | DefaultStyledDocument.create(DefaultStyledDocument.ElementSpec[] data) Initialize the document to reflect the given element structure (i.e.
protected void | DefaultStyledDocument.insert(int offset, DefaultStyledDocument.ElementSpec[] data) Inserts new elements in bulk.
void | DefaultStyledDocument.ElementBuffer.insert(int offset, int length, DefaultStyledDocument.ElementSpec[] data, AbstractDocument.DefaultDocumentEvent de) Inserts new content.
protected void | DefaultStyledDocument.ElementBuffer.insertUpdate(DefaultStyledDocument.ElementSpec[] data) Inserts an update into the document.

Uses of DefaultStyledDocument.ElementSpec in javax.swing.text.html

Fields in javax.swing.text.html with type parameters of type DefaultStyledDocument.ElementSpec
protected  Vector<DefaultStyledDocument.ElementSpec> HTMLDocument.HTMLReader.parseBuffer

Methods in javax.swing.text.html with parameters of type DefaultStyledDocument.ElementSpec
protected void | HTMLDocument.create(DefaultStyledDocument.ElementSpec[] data) Replaces the contents of the document with the given element specifications.
protected void | HTMLDocument.insert(int offset, DefaultStyledDocument.ElementSpec[] data) Inserts new elements in bulk.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultStyledDocument.SectionElement

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultStyledDocument.SectionElement

No usage of javax.swing.text.DefaultStyledDocument.SectionElement

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DefaultTextUI

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DefaultTextUI

No usage of javax.swing.text.DefaultTextUI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DocumentFilter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DocumentFilter

Packages that use DocumentFilter
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of DocumentFilter in javax.swing

Methods in javax.swing that return DocumentFilter
protected  DocumentFilter JFormattedTextField.AbstractFormatter.getDocumentFilter()
Subclass and override if you wish to provide a DocumentFilter to restrict what can be input.

Uses of DocumentFilter in javax.swing.text

Methods in javax.swing.text that return DocumentFilter
protected DocumentFilter | DefaultFormatter.getDocumentFilter() Returns the DocumentFilter used to restrict the characters that can be input into the JFormattedTextField.
DocumentFilter | AbstractDocument.getDocumentFilter() Returns the DocumentFilter that is responsible for filtering of insertion/removal.

Methods in javax.swing.text with parameters of type DocumentFilter
 void AbstractDocument.setDocumentFilter(DocumentFilter filter)
Sets the DocumentFilter.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.DocumentFilter.FilterBypass

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.DocumentFilter.FilterBypass

Packages that use DocumentFilter.FilterBypass
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of DocumentFilter.FilterBypass in javax.swing.text

Methods in javax.swing.text with parameters of type DocumentFilter.FilterBypass
void | DocumentFilter.insertString(DocumentFilter.FilterBypass fb, int offset, String string, AttributeSet attr) Invoked prior to insertion of text into the specified Document.
void | DocumentFilter.remove(DocumentFilter.FilterBypass fb, int offset, int length) Invoked prior to removal of the specified region in the specified Document.
void | DocumentFilter.replace(DocumentFilter.FilterBypass fb, int offset, int length, String text, AttributeSet attrs) Invoked prior to replacing a region of text in the specified Document.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.EditorKit

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.EditorKit

Packages that use EditorKit
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.
javax.swing.text.rtf | Provides a class (RTFEditorKit) for creating Rich-Text-Format text editors.

Uses of EditorKit in javax.swing

Methods in javax.swing that return EditorKit
protected EditorKit | JTextPane.createDefaultEditorKit() Creates the EditorKit to use by default.
protected EditorKit | JEditorPane.createDefaultEditorKit() Creates the default editor kit (PlainEditorKit) for when the component is first created.
static EditorKit | JEditorPane.createEditorKitForContentType(String type) Creates a handler for the given type from the default registry of editor kits.
EditorKit | JEditorPane.getEditorKit() Fetches the currently installed kit for handling content.
EditorKit | JEditorPane.getEditorKitForContentType(String type) Fetches the editor kit to use for the given type of content.

Methods in javax.swing with parameters of type EditorKit
void | JTextPane.setEditorKit(EditorKit kit) Sets the currently installed kit for handling content.
void | JEditorPane.setEditorKit(EditorKit kit) Sets the currently installed kit for handling content.
void | JEditorPane.setEditorKitForContentType(String type, EditorKit k) Directly sets the editor kit to use for the given type.

Uses of EditorKit in javax.swing.plaf

Methods in javax.swing.plaf that return EditorKit
abstract  EditorKit TextUI.getEditorKit(JTextComponent t)
Fetches the binding of services that set a policy for the type of document being edited.

Uses of EditorKit in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic that return EditorKit
EditorKit | BasicEditorPaneUI.getEditorKit(JTextComponent tc) Fetches the EditorKit for the UI.
EditorKit | BasicTextUI.getEditorKit(JTextComponent tc) Fetches the EditorKit for the UI.

Uses of EditorKit in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi that return EditorKit
 EditorKit MultiTextUI.getEditorKit(JTextComponent a)
Invokes the getEditorKit method on each UI handled by this object.

Uses of EditorKit in javax.swing.text

Subclasses of EditorKit in javax.swing.text
class | DefaultEditorKit This is the set of things needed by a text component to be a reasonably functioning editor for some type of text document.
class | StyledEditorKit This is the set of things needed by a text component to be a reasonably functioning editor for some type of text document.

Uses of EditorKit in javax.swing.text.html

Subclasses of EditorKit in javax.swing.text.html
 class HTMLEditorKit
The Swing JEditorPane text component supports different kinds of content via a plug-in mechanism called an EditorKit.

Uses of EditorKit in javax.swing.text.rtf

Subclasses of EditorKit in javax.swing.text.rtf
 class RTFEditorKit
This is the default implementation of RTF editing functionality.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.ElementIterator

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.ElementIterator

Packages that use ElementIterator
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of ElementIterator in javax.swing.text

Methods in javax.swing.text that return ElementIterator
protected  ElementIterator AbstractWriter.getElementIterator()
Fetches the ElementIterator.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.FieldView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.FieldView

Packages that use FieldView
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of FieldView in javax.swing.text

Subclasses of FieldView in javax.swing.text
 class PasswordView
Implements a View suitable for use in JPasswordField UI implementations.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.FlowView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.FlowView

Packages that use FlowView
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of FlowView in javax.swing.text

Subclasses of FlowView in javax.swing.text
 class ParagraphView
View of a simple line-wrapping paragraph that supports multiple fonts, colors, components, icons, etc.

Methods in javax.swing.text with parameters of type FlowView
protected void | FlowView.FlowStrategy.adjustRow(FlowView fv, int rowIndex, int desiredSpan, int x) Adjusts the given row if possible to fit within the layout span.
void | FlowView.FlowStrategy.changedUpdate(FlowView fv, DocumentEvent e, Rectangle alloc) Gives notification from the document that attributes were changed in a location that this view is responsible for.
protected View | FlowView.FlowStrategy.createView(FlowView fv, int startOffset, int spanLeft, int rowIndex) Creates a view that can be used to represent the current piece of the flow.
protected View | FlowView.FlowStrategy.getLogicalView(FlowView fv) This method gives flow strategies access to the logical view of the FlowView.
void | FlowView.FlowStrategy.insertUpdate(FlowView fv, DocumentEvent e, Rectangle alloc) Gives notification that something was inserted into the document in a location that the given flow view is responsible for.
void | FlowView.FlowStrategy.layout(FlowView fv) Update the flow on the given FlowView.
protected int | FlowView.FlowStrategy.layoutRow(FlowView fv, int rowIndex, int pos) Creates a row of views that will fit within the layout span of the row.
void | FlowView.FlowStrategy.removeUpdate(FlowView fv, DocumentEvent e, Rectangle alloc) Gives notification that something was removed from the document in a location that the given flow view is responsible for.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.FlowView.FlowStrategy

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.FlowView.FlowStrategy

Packages that use FlowView.FlowStrategy
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of FlowView.FlowStrategy in javax.swing.text

Fields in javax.swing.text declared as FlowView.FlowStrategy
protected  FlowView.FlowStrategy FlowView.strategy
The behavior for keeping the flow updated.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.GapContent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.GapContent

No usage of javax.swing.text.GapContent

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.GlyphView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.GlyphView

Packages that use GlyphView
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of GlyphView in javax.swing.text

Subclasses of GlyphView in javax.swing.text
 class LabelView
A LabelView is a styled chunk of text that represents a view mapped over an element in the text model.

Methods in javax.swing.text with parameters of type GlyphView
abstract float | GlyphView.GlyphPainter.getAscent(GlyphView v)
abstract int | GlyphView.GlyphPainter.getBoundedPosition(GlyphView v, int p0, float x, float len) Determines the model location that represents the maximum advance that fits within the given span.
abstract float | GlyphView.GlyphPainter.getDescent(GlyphView v)
abstract float | GlyphView.GlyphPainter.getHeight(GlyphView v)
int | GlyphView.GlyphPainter.getNextVisualPositionFrom(GlyphView v, int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
GlyphView.GlyphPainter | GlyphView.GlyphPainter.getPainter(GlyphView v, int p0, int p1) Create a painter to use for the given GlyphView.
abstract float | GlyphView.GlyphPainter.getSpan(GlyphView v, int p0, int p1, TabExpander e, float x) Determine the span the glyphs given a start location (for tab expansion).
abstract Shape | GlyphView.GlyphPainter.modelToView(GlyphView v, int pos, Position.Bias bias, Shape a) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
abstract void | GlyphView.GlyphPainter.paint(GlyphView v, Graphics g, Shape a, int p0, int p1) Paint the glyphs representing the given range.
abstract int | GlyphView.GlyphPainter.viewToModel(GlyphView v, float x, float y, Shape a, Position.Bias[] biasReturn) Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Uses of GlyphView in javax.swing.text.html

Subclasses of GlyphView in javax.swing.text.html
 class InlineView
Displays the inline element styles based upon css attributes.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.GlyphView.GlyphPainter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.GlyphView.GlyphPainter

Packages that use GlyphView.GlyphPainter
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of GlyphView.GlyphPainter in javax.swing.text

Methods in javax.swing.text that return GlyphView.GlyphPainter
GlyphView.GlyphPainter | GlyphView.getGlyphPainter() Fetch the currently installed glyph painter.
GlyphView.GlyphPainter | GlyphView.GlyphPainter.getPainter(GlyphView v, int p0, int p1) Create a painter to use for the given GlyphView.

Methods in javax.swing.text with parameters of type GlyphView.GlyphPainter
 void GlyphView.setGlyphPainter(GlyphView.GlyphPainter p)
Sets the painter to use for rendering glyphs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.IconView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.IconView

No usage of javax.swing.text.IconView

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.InternationalFormatter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.InternationalFormatter

Packages that use InternationalFormatter
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of InternationalFormatter in javax.swing.text

Subclasses of InternationalFormatter in javax.swing.text
class | DateFormatter DateFormatter is an InternationalFormatter that does its formatting by way of an instance of java.text.DateFormat.
class | NumberFormatter NumberFormatter subclasses InternationalFormatter adding special behavior for numbers.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.JTextComponent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.JTextComponent

Packages that use JTextComponent
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of JTextComponent in javax.swing

Subclasses of JTextComponent in javax.swing
class | JEditorPane A text component to edit various kinds of content.
class | JFormattedTextField JFormattedTextField extends JTextField adding support for formatting arbitrary values, as well as retrieving a particular object once the user has edited the text.
class | JPasswordField JPasswordField is a lightweight component that allows the editing of a single line of text where the view indicates something was typed, but does not show the original characters.
class | JTextArea A JTextArea is a multi-line area that displays plain text.
class | JTextField JTextField is a lightweight component that allows the editing of a single line of text.
class | JTextPane A text component that can be marked up with attributes that are represented graphically.

Uses of JTextComponent in javax.swing.plaf

Methods in javax.swing.plaf with parameters of type JTextComponent
abstract void | TextUI.damageRange(JTextComponent t, int p0, int p1) Causes the portion of the view responsible for the given part of the model to be repainted.
abstract void | TextUI.damageRange(JTextComponent t, int p0, int p1, Position.Bias firstBias, Position.Bias secondBias) Causes the portion of the view responsible for the given part of the model to be repainted.
abstract EditorKit | TextUI.getEditorKit(JTextComponent t) Fetches the binding of services that set a policy for the type of document being edited.
abstract int | TextUI.getNextVisualPositionFrom(JTextComponent t, int pos, Position.Bias b, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
abstract View | TextUI.getRootView(JTextComponent t) Fetches a View with the allocation of the associated text component (i.e.
String | TextUI.getToolTipText(JTextComponent t, Point pt) Returns the string to be used as the tooltip at the passed in location.
abstract Rectangle | TextUI.modelToView(JTextComponent t, int pos) Converts the given location in the model to a place in the view coordinate system.
abstract Rectangle | TextUI.modelToView(JTextComponent t, int pos, Position.Bias bias) Converts the given location in the model to a place in the view coordinate system.
abstract int | TextUI.viewToModel(JTextComponent t, Point pt) Converts the given place in the view coordinate system to the nearest representative location in the model.
abstract int | TextUI.viewToModel(JTextComponent t, Point pt, Position.Bias[] biasReturn) Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Uses of JTextComponent in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic that return JTextComponent
protected  JTextComponent BasicTextUI.getComponent()
Fetches the text component associated with this UI implementation.

Methods in javax.swing.plaf.basic with parameters of type JTextComponent
void | BasicTextUI.damageRange(JTextComponent tc, int p0, int p1) Causes the portion of the view responsible for the given part of the model to be repainted.
void | BasicTextUI.damageRange(JTextComponent t, int p0, int p1, Position.Bias p0Bias, Position.Bias p1Bias) Causes the portion of the view responsible for the given part of the model to be repainted.
EditorKit | BasicEditorPaneUI.getEditorKit(JTextComponent tc) Fetches the EditorKit for the UI.
EditorKit | BasicTextUI.getEditorKit(JTextComponent tc) Fetches the EditorKit for the UI.
int | BasicTextUI.getNextVisualPositionFrom(JTextComponent t, int pos, Position.Bias b, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
View | BasicTextUI.getRootView(JTextComponent tc) Fetches a View with the allocation of the associated text component (i.e.
String | BasicTextUI.getToolTipText(JTextComponent t, Point pt) Returns the string to be used as the tooltip at the passed in location.
Rectangle | BasicTextUI.modelToView(JTextComponent tc, int pos) Converts the given location in the model to a place in the view coordinate system.
Rectangle | BasicTextUI.modelToView(JTextComponent tc, int pos, Position.Bias bias) Converts the given location in the model to a place in the view coordinate system.
int | BasicTextUI.viewToModel(JTextComponent tc, Point pt) Converts the given place in the view coordinate system to the nearest representative location in the model.
int | BasicTextUI.viewToModel(JTextComponent tc, Point pt, Position.Bias[] biasReturn) Converts the given place in the view coordinate system to the nearest representative location in the model.

Uses of JTextComponent in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi with parameters of type JTextComponent
void | MultiTextUI.damageRange(JTextComponent a, int b, int c) Invokes the damageRange method on each UI handled by this object.
void | MultiTextUI.damageRange(JTextComponent a, int b, int c, Position.Bias d, Position.Bias e) Invokes the damageRange method on each UI handled by this object.
EditorKit | MultiTextUI.getEditorKit(JTextComponent a) Invokes the getEditorKit method on each UI handled by this object.
int | MultiTextUI.getNextVisualPositionFrom(JTextComponent a, int b, Position.Bias c, int d, Position.Bias[] e) Invokes the getNextVisualPositionFrom method on each UI handled by this object.
View | MultiTextUI.getRootView(JTextComponent a) Invokes the getRootView method on each UI handled by this object.
String | MultiTextUI.getToolTipText(JTextComponent a, Point b) Invokes the getToolTipText method on each UI handled by this object.
Rectangle | MultiTextUI.modelToView(JTextComponent a, int b) Invokes the modelToView method on each UI handled by this object.
Rectangle | MultiTextUI.modelToView(JTextComponent a, int b, Position.Bias c) Invokes the modelToView method on each UI handled by this object.
int | MultiTextUI.viewToModel(JTextComponent a, Point b) Invokes the viewToModel method on each UI handled by this object.
int | MultiTextUI.viewToModel(JTextComponent a, Point b, Position.Bias[] c) Invokes the viewToModel method on each UI handled by this object.

Uses of JTextComponent in javax.swing.text

Methods in javax.swing.text that return JTextComponent
protected JTextComponent | DefaultCaret.getComponent() Gets the text editor component that this caret is is bound to.
protected JTextComponent | TextAction.getFocusedComponent() Fetches the text component that currently has focus.
protected JTextComponent | TextAction.getTextComponent(ActionEvent e) Determines the component to use for the action.

Methods in javax.swing.text with parameters of type JTextComponent
void | DefaultHighlighter.deinstall(JTextComponent c) Called when the UI is being removed from the interface of a JTextComponent.
void | DefaultCaret.deinstall(JTextComponent c) Called when the UI is being removed from the interface of a JTextComponent.
void | Highlighter.deinstall(JTextComponent c) Called when the UI is being removed from the interface of a JTextComponent.
void | Caret.deinstall(JTextComponent c) Called when the UI is being removed from the interface of a JTextComponent.
int | NavigationFilter.getNextVisualPositionFrom(JTextComponent text, int pos, Position.Bias bias, int direction, Position.Bias[] biasRet) Returns the next visual position to place the caret at from an existing position.
static int | Utilities.getNextWord(JTextComponent c, int offs) Determines the start of the next word for the given location.
static Element | Utilities.getParagraphElement(JTextComponent c, int offs) Determines the element to use for a paragraph/line.
static int | Utilities.getPositionAbove(JTextComponent c, int offs, int x) Determines the position in the model that is closest to the given view location in the row above.
static int | Utilities.getPositionBelow(JTextComponent c, int offs, int x) Determines the position in the model that is closest to the given view location in the row below.
static int | Utilities.getPreviousWord(JTextComponent c, int offs) Determine the start of the prev word for the given location.
static int | Utilities.getRowEnd(JTextComponent c, int offs) Determines the ending row model position of the row that contains the specified model position.
static int | Utilities.getRowStart(JTextComponent c, int offs) Determines the starting row model position of the row that contains the specified model position.
static int | Utilities.getWordEnd(JTextComponent c, int offs) Determines the end of a word for the given location.
static int | Utilities.getWordStart(JTextComponent c, int offs) Determines the start of a word for the given model location.
void | DefaultHighlighter.install(JTextComponent c) Called when the UI is being installed into the interface of a JTextComponent.
void | DefaultCaret.install(JTextComponent c) Called when the UI is being installed into the interface of a JTextComponent.
void | Highlighter.install(JTextComponent c) Called when the UI is being installed into the interface of a JTextComponent.
void | Caret.install(JTextComponent c) Called when the UI is being installed into the interface of a JTextComponent.
void | DefaultHighlighter.DefaultHighlightPainter.paint(Graphics g, int offs0, int offs1, Shape bounds, JTextComponent c) Paints a highlight.
void | Highlighter.HighlightPainter.paint(Graphics g, int p0, int p1, Shape bounds, JTextComponent c) Renders the highlight.
Shape | DefaultHighlighter.DefaultHighlightPainter.paintLayer(Graphics g, int offs0, int offs1, Shape bounds, JTextComponent c, View view) Paints a portion of a highlight.
abstract Shape | LayeredHighlighter.LayerPainter.paintLayer(Graphics g, int p0, int p1, Shape viewBounds, JTextComponent editor, View view)
void | DefaultHighlighter.paintLayeredHighlights(Graphics g, int p0, int p1, Shape viewBounds, JTextComponent editor, View view) When leaf Views (such as LabelView) are rendering they should call into this method.
abstract void | LayeredHighlighter.paintLayeredHighlights(Graphics g, int p0, int p1, Shape viewBounds, JTextComponent editor, View view) When leaf Views (such as LabelView) are rendering they should call into this method.

Uses of JTextComponent in javax.swing.tree

Subclasses of JTextComponent in javax.swing.tree
 class DefaultTreeCellEditor.DefaultTextField
TextField used when no editor is supplied.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.JTextComponent.AccessibleJTextComponent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.JTextComponent.AccessibleJTextComponent

Packages that use JTextComponent.AccessibleJTextComponent
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of JTextComponent.AccessibleJTextComponent in javax.swing

Subclasses of JTextComponent.AccessibleJTextComponent in javax.swing
protected class | JEditorPane.AccessibleJEditorPane This class implements accessibility support for the JEditorPane class.
protected class | JEditorPane.AccessibleJEditorPaneHTML This class provides support for AccessibleHypertext, and is used in instances where the EditorKit installed in this JEditorPane is an instance of HTMLEditorKit.
protected class | JEditorPane.JEditorPaneAccessibleHypertextSupport What's returned by AccessibleJEditorPaneHTML.getAccessibleText.
protected class | JPasswordField.AccessibleJPasswordField This class implements accessibility support for the JPasswordField class.
protected class | JTextArea.AccessibleJTextArea This class implements accessibility support for the JTextArea class.
protected class | JTextField.AccessibleJTextField This class implements accessibility support for the JTextField class.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.JTextComponent.DropLocation

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.JTextComponent.DropLocation

Packages that use JTextComponent.DropLocation
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of JTextComponent.DropLocation in javax.swing.text

Methods in javax.swing.text that return JTextComponent.DropLocation
 JTextComponent.DropLocation JTextComponent.getDropLocation()
Returns the location that this component should visually indicate as the drop location during a DnD operation over the component, or null if no location is to currently be shown.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.JTextComponent.KeyBinding

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.JTextComponent.KeyBinding

Packages that use JTextComponent.KeyBinding
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of JTextComponent.KeyBinding in javax.swing

Methods in javax.swing that return JTextComponent.KeyBinding
static JTextComponent.KeyBinding[] LookAndFeel.makeKeyBindings(Object[] keyBindingList)
Convenience method for building an array of KeyBindings.

Uses of JTextComponent.KeyBinding in javax.swing.text

Methods in javax.swing.text with parameters of type JTextComponent.KeyBinding
static void JTextComponent.loadKeymap(Keymap map, JTextComponent.KeyBinding[] bindings, Action[] actions)
Loads a keymap with a bunch of bindings.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.LabelView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.LabelView

Packages that use LabelView
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of LabelView in javax.swing.text.html

Subclasses of LabelView in javax.swing.text.html
 class InlineView
Displays the inline element styles based upon css attributes.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.LayeredHighlighter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.LayeredHighlighter

Packages that use LayeredHighlighter
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of LayeredHighlighter in javax.swing.plaf.basic

Subclasses of LayeredHighlighter in javax.swing.plaf.basic
static class BasicTextUI.BasicHighlighter

Uses of LayeredHighlighter in javax.swing.text

Subclasses of LayeredHighlighter in javax.swing.text
 class DefaultHighlighter
Implements the Highlighter interfaces.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.LayeredHighlighter.LayerPainter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.LayeredHighlighter.LayerPainter

Packages that use LayeredHighlighter.LayerPainter
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of LayeredHighlighter.LayerPainter in javax.swing.text

Subclasses of LayeredHighlighter.LayerPainter in javax.swing.text
static class DefaultHighlighter.DefaultHighlightPainter
Simple highlight painter that fills a highlighted area with a solid color.

Fields in javax.swing.text declared as LayeredHighlighter.LayerPainter
static LayeredHighlighter.LayerPainter DefaultHighlighter.DefaultPainter
Default implementation of LayeredHighlighter.LayerPainter that can be used for painting highlights.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.LayoutQueue

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.LayoutQueue

Packages that use LayoutQueue
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of LayoutQueue in javax.swing.text

Methods in javax.swing.text that return LayoutQueue
static LayoutQueue | LayoutQueue.getDefaultQueue() Fetch the default layout queue.
protected LayoutQueue | AsyncBoxView.getLayoutQueue() Fetch the queue to use for layout.

Methods in javax.swing.text with parameters of type LayoutQueue
static void LayoutQueue.setDefaultQueue(LayoutQueue q)
Set the default layout queue.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.MaskFormatter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.MaskFormatter

No usage of javax.swing.text.MaskFormatter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.NavigationFilter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.NavigationFilter

Packages that use NavigationFilter
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of NavigationFilter in javax.swing

Methods in javax.swing that return NavigationFilter
protected  NavigationFilter JFormattedTextField.AbstractFormatter.getNavigationFilter()
Subclass and override if you wish to provide a filter to restrict where the user can navigate to.

Uses of NavigationFilter in javax.swing.text

Methods in javax.swing.text that return NavigationFilter
protected NavigationFilter | DefaultFormatter.getNavigationFilter() Returns the NavigationFilter used to restrict where the cursor can be placed.
NavigationFilter | JTextComponent.getNavigationFilter() Returns the NavigationFilter.

Methods in javax.swing.text with parameters of type NavigationFilter
 void JTextComponent.setNavigationFilter(NavigationFilter filter)
Sets the NavigationFilter.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.NavigationFilter.FilterBypass

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.NavigationFilter.FilterBypass

Packages that use NavigationFilter.FilterBypass
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of NavigationFilter.FilterBypass in javax.swing.text

Methods in javax.swing.text with parameters of type NavigationFilter.FilterBypass
void | NavigationFilter.moveDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias) Invoked prior to the Caret moving the dot.
void | NavigationFilter.setDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias) Invoked prior to the Caret setting the dot.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.NumberFormatter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.NumberFormatter

No usage of javax.swing.text.NumberFormatter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.ParagraphView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.ParagraphView

Packages that use ParagraphView
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of ParagraphView in javax.swing.text.html

Subclasses of ParagraphView in javax.swing.text.html
 class ParagraphView
Displays the a paragraph, and uses css attributes for its configuration.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.PasswordView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.PasswordView

No usage of javax.swing.text.PasswordView

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.PlainDocument

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.PlainDocument

No usage of javax.swing.text.PlainDocument

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.PlainView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.PlainView

Packages that use PlainView
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of PlainView in javax.swing.text

Subclasses of PlainView in javax.swing.text
class | FieldView Extends the multi-line plain text view to be suitable for a single-line editor view.
class | PasswordView Implements a View suitable for use in JPasswordField UI implementations.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.Position.Bias

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.Position.Bias

Packages that use Position.Bias
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of Position.Bias in javax.swing

Methods in javax.swing with parameters of type Position.Bias
TreePath | JTree.getNextMatch(String prefix, int startingRow, Position.Bias bias) Returns the TreePath to the next tree element that begins with a prefix.
int | JList.getNextMatch(String prefix, int startIndex, Position.Bias bias) Returns the next list element whose toString value starts with the given prefix.

Uses of Position.Bias in javax.swing.plaf

Methods in javax.swing.plaf with parameters of type Position.Bias
abstract void | TextUI.damageRange(JTextComponent t, int p0, int p1, Position.Bias firstBias, Position.Bias secondBias) Causes the portion of the view responsible for the given part of the model to be repainted.
abstract int | TextUI.getNextVisualPositionFrom(JTextComponent t, int pos, Position.Bias b, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
abstract int | TextUI.getNextVisualPositionFrom(JTextComponent t, int pos, Position.Bias b, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
abstract Rectangle | TextUI.modelToView(JTextComponent t, int pos, Position.Bias bias) Converts the given location in the model to a place in the view coordinate system.
abstract int | TextUI.viewToModel(JTextComponent t, Point pt, Position.Bias[] biasReturn) Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Uses of Position.Bias in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic with parameters of type Position.Bias
void | BasicTextUI.damageRange(JTextComponent t, int p0, int p1, Position.Bias p0Bias, Position.Bias p1Bias) Causes the portion of the view responsible for the given part of the model to be repainted.
int | BasicTextUI.getNextVisualPositionFrom(JTextComponent t, int pos, Position.Bias b, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
int | BasicTextUI.getNextVisualPositionFrom(JTextComponent t, int pos, Position.Bias b, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
Rectangle | BasicTextUI.modelToView(JTextComponent tc, int pos, Position.Bias bias) Converts the given location in the model to a place in the view coordinate system.
int | BasicTextUI.viewToModel(JTextComponent tc, Point pt, Position.Bias[] biasReturn) Converts the given place in the view coordinate system to the nearest representative location in the model.

Uses of Position.Bias in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi with parameters of type Position.Bias
void | MultiTextUI.damageRange(JTextComponent a, int b, int c, Position.Bias d, Position.Bias e) Invokes the damageRange method on each UI handled by this object.
int | MultiTextUI.getNextVisualPositionFrom(JTextComponent a, int b, Position.Bias c, int d, Position.Bias[] e) Invokes the getNextVisualPositionFrom method on each UI handled by this object.
int | MultiTextUI.getNextVisualPositionFrom(JTextComponent a, int b, Position.Bias c, int d, Position.Bias[] e) Invokes the getNextVisualPositionFrom method on each UI handled by this object.
Rectangle | MultiTextUI.modelToView(JTextComponent a, int b, Position.Bias c) Invokes the modelToView method on each UI handled by this object.
int | MultiTextUI.viewToModel(JTextComponent a, Point b, Position.Bias[] c) Invokes the viewToModel method on each UI handled by this object.

Uses of Position.Bias in javax.swing.text

Fields in javax.swing.text declared as Position.Bias
static Position.Bias | Position.Bias.Backward Indicates a bias toward the previous character in the model.
static Position.Bias | Position.Bias.Forward Indicates to bias toward the next character in the model.

Methods in javax.swing.text that return Position.Bias
Position.Bias | JTextComponent.DropLocation.getBias() Returns the bias for the drop index.
Position.Bias | DefaultCaret.getDotBias() Returns the bias of the caret position.
Position.Bias | DefaultCaret.getMarkBias() Returns the bias of the mark.

Methods in javax.swing.text with parameters of type Position.Bias
protected boolean | BoxView.flipEastAndWestAtEnds(int position, Position.Bias bias) Determines in which direction the next view lays.
protected boolean | ParagraphView.flipEastAndWestAtEnds(int position, Position.Bias bias) Determines in which direction the next view lays.
protected boolean | CompositeView.flipEastAndWestAtEnds(int position, Position.Bias bias) Determines in which direction the next view lays.
protected int | ParagraphView.getClosestPositionTo(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet, int rowIndex, int x) Returns the closest model position to x.
protected int | ParagraphView.getClosestPositionTo(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet, int rowIndex, int x) Returns the closest model position to x.
protected int | CompositeView.getNextEastWestVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Returns the next visual position for the cursor, in either the east or west direction.
protected int | CompositeView.getNextEastWestVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Returns the next visual position for the cursor, in either the east or west direction.
protected int | ParagraphView.getNextNorthSouthVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Returns the next visual position for the cursor, in either the east or west direction.
protected int | ParagraphView.getNextNorthSouthVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Returns the next visual position for the cursor, in either the east or west direction.
protected int | CompositeView.getNextNorthSouthVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Returns the next visual position for the cursor, in either the north or south direction.
protected int | CompositeView.getNextNorthSouthVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Returns the next visual position for the cursor, in either the north or south direction.
int | GlyphView.GlyphPainter.getNextVisualPositionFrom(GlyphView v, int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
int | GlyphView.GlyphPainter.getNextVisualPositionFrom(GlyphView v, int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
int | AsyncBoxView.getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
int | AsyncBoxView.getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
int | GlyphView.getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
int | GlyphView.getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
int | CompositeView.getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
int | CompositeView.getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
int | View.getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location at which one might place a caret.
int | View.getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location at which one might place a caret.
int | NavigationFilter.getNextVisualPositionFrom(JTextComponent text, int pos, Position.Bias bias, int direction, Position.Bias[] biasRet) Returns the next visual position to place the caret at from an existing position.
int | NavigationFilter.getNextVisualPositionFrom(JTextComponent text, int pos, Position.Bias bias, int direction, Position.Bias[] biasRet) Returns the next visual position to place the caret at from an existing position.
int | AsyncBoxView.getViewIndex(int pos, Position.Bias b) Returns the child view index representing the given position in the model.
int | CompositeView.getViewIndex(int pos, Position.Bias b) Returns the child view index representing the given position in the model.
int | View.getViewIndex(int pos, Position.Bias b) Returns the child view index representing the given position in the model.
protected int | AsyncBoxView.getViewIndexAtPosition(int pos, Position.Bias b) Fetches the child view index representing the given position in the model.
abstract Shape | GlyphView.GlyphPainter.modelToView(GlyphView v, int pos, Position.Bias bias, Shape a) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | CompositeView.modelToView(int p0, Position.Bias b0, int p1, Position.Bias b1, Shape a) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | View.modelToView(int p0, Position.Bias b0, int p1, Position.Bias b1, Shape a) Provides a mapping, for a given region, from the document model coordinate space to the view coordinate space.
Shape | PasswordView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | FieldView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | AsyncBoxView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | PlainView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | IconView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | BoxView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | ComponentView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the coordinate space of the model to that of the view.
Shape | GlyphView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | CompositeView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
abstract Shape | View.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping, for a given character, from the document model coordinate space to the view coordinate space.
void | DefaultCaret.moveDot(int dot, Position.Bias dotBias) Moves the caret position to the specified position, with the specified bias.
abstract void | NavigationFilter.FilterBypass.moveDot(int dot, Position.Bias bias) Moves the caret location, bypassing the NavigationFilter.
void | NavigationFilter.moveDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias) Invoked prior to the Caret moving the dot.
void | DefaultCaret.setDot(int dot, Position.Bias dotBias) Sets the caret position and mark to the specified position, with the specified bias.
abstract void | NavigationFilter.FilterBypass.setDot(int dot, Position.Bias bias) Sets the caret location, bypassing the NavigationFilter.
void | NavigationFilter.setDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias) Invoked prior to the Caret setting the dot.
int | PasswordView.viewToModel(float fx, float fy, Shape a, Position.Bias[] bias) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
int | FieldView.viewToModel(float fx, float fy, Shape a, Position.Bias[] bias) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
int | AsyncBoxView.viewToModel(float x, float y, Shape a, Position.Bias[] biasReturn) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
int | PlainView.viewToModel(float fx, float fy, Shape a, Position.Bias[] bias) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
int | IconView.viewToModel(float x, float y, Shape a, Position.Bias[] bias) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
int | BoxView.viewToModel(float x, float y, Shape a, Position.Bias[] bias) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
int | ComponentView.viewToModel(float x, float y, Shape a, Position.Bias[] bias) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
int | GlyphView.viewToModel(float x, float y, Shape a, Position.Bias[] biasReturn) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
int | CompositeView.viewToModel(float x, float y, Shape a, Position.Bias[] bias) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
abstract int | View.viewToModel(float x, float y, Shape a, Position.Bias[] biasReturn) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
abstract int | GlyphView.GlyphPainter.viewToModel(GlyphView v, float x, float y, Shape a, Position.Bias[] biasReturn) Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Uses of Position.Bias in javax.swing.text.html

Methods in javax.swing.text.html with parameters of type Position.Bias
Shape | ImageView.modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
int | ImageView.viewToModel(float x, float y, Shape a, Position.Bias[] bias) Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.Segment

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.Segment

Packages that use Segment
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of Segment in javax.swing.text

Methods in javax.swing.text that return Segment
protected Segment | WrappedPlainView.getLineBuffer() Gives access to a buffer that can be used to fetch text from the associated document.
protected Segment | PlainView.getLineBuffer() Gives access to a buffer that can be used to fetch text from the associated document.
Segment | GlyphView.getText(int p0, int p1) Fetch a reference to the text that occupies the given range.

Methods in javax.swing.text with parameters of type Segment
static int | Utilities.drawTabbedText(Segment s, int x, int y, Graphics g, TabExpander e, int startOffset) Draws the given text, expanding any tabs that are contained using the given tab expansion technique.
static int | Utilities.getBreakLocation(Segment s, FontMetrics metrics, int x0, int x, TabExpander e, int startOffset) Determine where to break the given text to fit within the given span.
void | StringContent.getChars(int where, int len, Segment chars) Retrieves a portion of the content.
void | GapContent.getChars(int where, int len, Segment chars) Retrieves a portion of the content.
void | AbstractDocument.Content.getChars(int where, int len, Segment txt) Gets a sequence of characters and copies them into a Segment.
static int | Utilities.getTabbedTextOffset(Segment s, FontMetrics metrics, int x0, int x, TabExpander e, int startOffset) Determines the relative offset into the given text that best represents the given span in the view coordinate system.
static int | Utilities.getTabbedTextOffset(Segment s, FontMetrics metrics, int x0, int x, TabExpander e, int startOffset, boolean round)
static int | Utilities.getTabbedTextWidth(Segment s, FontMetrics metrics, int x, TabExpander e, int startOffset) Determines the width of the given segment of text taking tabs into consideration.
void | AbstractDocument.getText(int offset, int length, Segment txt) Fetches the text contained within the given portion of the document.
void | Document.getText(int offset, int length, Segment txt) Fetches the text contained within the given portion of the document.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.SimpleAttributeSet

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.SimpleAttributeSet

Packages that use SimpleAttributeSet
javax.swing.text.html.parser Provides the default HTML parser, along with support classes.

Uses of SimpleAttributeSet in javax.swing.text.html.parser

Methods in javax.swing.text.html.parser that return SimpleAttributeSet
protected  SimpleAttributeSet Parser.getAttributes()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StringContent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StringContent

No usage of javax.swing.text.StringContent

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StyleConstants

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StyleConstants

Packages that use StyleConstants
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of StyleConstants in javax.swing.text

Subclasses of StyleConstants in javax.swing.text
static class | StyleConstants.CharacterConstants This is a typesafe enumeration of the well-known attributes that contribute to a character style.
static class | StyleConstants.ColorConstants This is a typesafe enumeration of the well-known attributes that contribute to a color.
static class | StyleConstants.FontConstants This is a typesafe enumeration of the well-known attributes that contribute to a font.
static class | StyleConstants.ParagraphConstants This is a typesafe enumeration of the well-known attributes that contribute to a paragraph style.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StyleConstants.CharacterConstants

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StyleConstants.CharacterConstants

No usage of javax.swing.text.StyleConstants.CharacterConstants

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StyleConstants.ColorConstants

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StyleConstants.ColorConstants

No usage of javax.swing.text.StyleConstants.ColorConstants

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StyleConstants.FontConstants

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StyleConstants.FontConstants

No usage of javax.swing.text.StyleConstants.FontConstants

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StyleConstants.ParagraphConstants

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StyleConstants.ParagraphConstants

No usage of javax.swing.text.StyleConstants.ParagraphConstants

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StyleContext

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StyleContext

Packages that use StyleContext
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of StyleContext in javax.swing.text

Methods in javax.swing.text that return StyleContext
static StyleContext StyleContext.getDefaultStyleContext()
Returns default AttributeContext shared by all documents that don't bother to define/supply their own context.

Constructors in javax.swing.text with parameters of type StyleContext
DefaultStyledDocument(AbstractDocument.Content c, StyleContext styles)
Constructs a styled document.
DefaultStyledDocument(StyleContext styles)
Constructs a styled document with the default content storage implementation and a shared set of styles.

Uses of StyleContext in javax.swing.text.html

Subclasses of StyleContext in javax.swing.text.html
 class StyleSheet
Support for defining the visual characteristics of HTML views being rendered.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StyleContext.NamedStyle

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StyleContext.NamedStyle

No usage of javax.swing.text.StyleContext.NamedStyle

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StyleContext.SmallAttributeSet

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StyleContext.SmallAttributeSet

Packages that use StyleContext.SmallAttributeSet
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of StyleContext.SmallAttributeSet in javax.swing.text

Methods in javax.swing.text that return StyleContext.SmallAttributeSet
protected  StyleContext.SmallAttributeSet StyleContext.createSmallAttributeSet(AttributeSet a)
Create a compact set of attributes that might be shared.

Uses of StyleContext.SmallAttributeSet in javax.swing.text.html

Methods in javax.swing.text.html that return StyleContext.SmallAttributeSet
protected  StyleContext.SmallAttributeSet StyleSheet.createSmallAttributeSet(AttributeSet a)
Creates a compact set of attributes that might be shared.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StyledEditorKit

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StyledEditorKit

Packages that use StyledEditorKit
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.
javax.swing.text.rtf | Provides a class (RTFEditorKit) for creating Rich-Text-Format text editors.

Uses of StyledEditorKit in javax.swing

Methods in javax.swing that return StyledEditorKit
protected  StyledEditorKit JTextPane.getStyledEditorKit()
Gets the editor kit.

Uses of StyledEditorKit in javax.swing.text

Methods in javax.swing.text that return StyledEditorKit
protected  StyledEditorKit StyledEditorKit.StyledTextAction.getStyledEditorKit(JEditorPane e)
Gets the editor kit associated with an editor pane.

Uses of StyledEditorKit in javax.swing.text.html

Subclasses of StyledEditorKit in javax.swing.text.html
 class HTMLEditorKit
The Swing JEditorPane text component supports different kinds of content via a plug-in mechanism called an EditorKit.

Uses of StyledEditorKit in javax.swing.text.rtf

Subclasses of StyledEditorKit in javax.swing.text.rtf
 class RTFEditorKit
This is the default implementation of RTF editing functionality.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StyledEditorKit.AlignmentAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StyledEditorKit.AlignmentAction

No usage of javax.swing.text.StyledEditorKit.AlignmentAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StyledEditorKit.BoldAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StyledEditorKit.BoldAction

No usage of javax.swing.text.StyledEditorKit.BoldAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StyledEditorKit.FontFamilyAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StyledEditorKit.FontFamilyAction

No usage of javax.swing.text.StyledEditorKit.FontFamilyAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StyledEditorKit.FontSizeAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StyledEditorKit.FontSizeAction

No usage of javax.swing.text.StyledEditorKit.FontSizeAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StyledEditorKit.ForegroundAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StyledEditorKit.ForegroundAction

No usage of javax.swing.text.StyledEditorKit.ForegroundAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StyledEditorKit.ItalicAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StyledEditorKit.ItalicAction

No usage of javax.swing.text.StyledEditorKit.ItalicAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StyledEditorKit.StyledTextAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StyledEditorKit.StyledTextAction

Packages that use StyledEditorKit.StyledTextAction
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of StyledEditorKit.StyledTextAction in javax.swing.text

Subclasses of StyledEditorKit.StyledTextAction in javax.swing.text
static class | StyledEditorKit.AlignmentAction An action to set paragraph alignment.
static class | StyledEditorKit.BoldAction An action to toggle the bold attribute.
static class | StyledEditorKit.FontFamilyAction An action to set the font family in the associated JEditorPane.
static class | StyledEditorKit.FontSizeAction An action to set the font size in the associated JEditorPane.
static class | StyledEditorKit.ForegroundAction An action to set foreground color.
static class | StyledEditorKit.ItalicAction An action to toggle the italic attribute.
static class | StyledEditorKit.UnderlineAction An action to toggle the underline attribute.

Uses of StyledEditorKit.StyledTextAction in javax.swing.text.html

Subclasses of StyledEditorKit.StyledTextAction in javax.swing.text.html
static class | HTMLEditorKit.HTMLTextAction An abstract Action providing some convenience methods that may be useful in inserting HTML into an existing document.
static class | HTMLEditorKit.InsertHTMLTextAction InsertHTMLTextAction can be used to insert an arbitrary string of HTML into an existing HTML document.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.StyledEditorKit.UnderlineAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.StyledEditorKit.UnderlineAction

No usage of javax.swing.text.StyledEditorKit.UnderlineAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.TableView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.TableView

No usage of javax.swing.text.TableView

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.TableView.TableCell

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.TableView.TableCell

Packages that use TableView.TableCell
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of TableView.TableCell in javax.swing.text

Methods in javax.swing.text that return TableView.TableCell
protected  TableView.TableCell TableView.createTableCell(Element elem)
Deprecated. Table cells can now be any arbitrary View implementation and should be produced by the ViewFactory rather than the table.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.TableView.TableRow

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.TableView.TableRow

Packages that use TableView.TableRow
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of TableView.TableRow in javax.swing.text

Methods in javax.swing.text that return TableView.TableRow
protected  TableView.TableRow TableView.createTableRow(Element elem)
Creates a new table row.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.TabSet

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.TabSet

Packages that use TabSet
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of TabSet in javax.swing.text

Methods in javax.swing.text that return TabSet
protected TabSet | ParagraphView.getTabSet() Gets the Tabset to be used in calculating tabs.
static TabSet | StyleConstants.getTabSet(AttributeSet a) Gets the TabSet.

Methods in javax.swing.text with parameters of type TabSet
static void StyleConstants.setTabSet(MutableAttributeSet a, TabSet tabs)
Sets the TabSet.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.TabStop

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.TabStop

Packages that use TabStop
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of TabStop in javax.swing.text

Methods in javax.swing.text that return TabStop
TabStop | TabSet.getTab(int index) Returns the TabStop at index index.
TabStop | TabSet.getTabAfter(float location) Returns the Tab instance after location.

Methods in javax.swing.text with parameters of type TabStop
 int TabSet.getTabIndex(TabStop tab)

Constructors in javax.swing.text with parameters of type TabStop
TabSet(TabStop[] tabs)
Creates and returns an instance of TabSet.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.TextAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.TextAction

Packages that use TextAction
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of TextAction in javax.swing.text

Subclasses of TextAction in javax.swing.text
static class | DefaultEditorKit.BeepAction Creates a beep.
static class | DefaultEditorKit.CopyAction Copies the selected region and place its contents into the system clipboard.
static class | DefaultEditorKit.CutAction Cuts the selected region and place its contents into the system clipboard.
static class | DefaultEditorKit.DefaultKeyTypedAction The action that is executed by default if a key typed event is received and there is no keymap entry.
static class | DefaultEditorKit.InsertBreakAction Places a line/paragraph break into the document.
static class | DefaultEditorKit.InsertContentAction Places content into the associated document.
static class | DefaultEditorKit.InsertTabAction Places a tab character into the document.
static class | DefaultEditorKit.PasteAction Pastes the contents of the system clipboard into the selected region, or before the caret if nothing is selected.
static class | StyledEditorKit.AlignmentAction An action to set paragraph alignment.
static class | StyledEditorKit.BoldAction An action to toggle the bold attribute.
static class | StyledEditorKit.FontFamilyAction An action to set the font family in the associated JEditorPane.
static class | StyledEditorKit.FontSizeAction An action to set the font size in the associated JEditorPane.
static class | StyledEditorKit.ForegroundAction An action to set foreground color.
static class | StyledEditorKit.ItalicAction An action to toggle the italic attribute.
static class | StyledEditorKit.StyledTextAction An action that assumes it's being fired on a JEditorPane with a StyledEditorKit (or subclass) installed.
static class | StyledEditorKit.UnderlineAction An action to toggle the underline attribute.

Uses of TextAction in javax.swing.text.html

Subclasses of TextAction in javax.swing.text.html
static class | HTMLEditorKit.HTMLTextAction An abstract Action providing some convenience methods that may be useful in inserting HTML into an existing document.
static class | HTMLEditorKit.InsertHTMLTextAction InsertHTMLTextAction can be used to insert an arbitrary string of HTML into an existing HTML document.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.Utilities

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.Utilities

No usage of javax.swing.text.Utilities

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.View

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.View

Packages that use View
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of View in javax.swing.plaf

Methods in javax.swing.plaf that return View
abstract  View TextUI.getRootView(JTextComponent t)
Fetches a View with the allocation of the associated text component (i.e.

Uses of View in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic that return View
View | BasicPasswordFieldUI.create(Element elem) Creates a view (PasswordView) for an element.
View | BasicTextAreaUI.create(Element elem) Creates the view for an element.
View | BasicTextFieldUI.create(Element elem) Creates a view (FieldView) based on an element.
View | BasicTextUI.create(Element elem) Creates a view for an element.
View | BasicTextUI.create(Element elem, int p0, int p1) Creates a view for an element.
static View | BasicHTML.createHTMLView(JComponent c, String html) Create an html renderer for the given component and string of html.
View | BasicTextUI.getRootView(JTextComponent tc) Fetches a View with the allocation of the associated text component (i.e.
protected View | BasicTabbedPaneUI.getTextViewForTab(int tabIndex) Returns the text View object required to render stylized text (HTML) for the specified tab or null if no specialized text rendering is needed for this tab.

Methods in javax.swing.plaf.basic with parameters of type View
static int BasicHTML.getHTMLBaseline(View view, int w, int h)
Returns the baseline for the html renderer.
protected  void BasicTextUI.setView(View v)
Sets the current root of the view hierarchy and calls invalidate().

Uses of View in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi that return View
 View MultiTextUI.getRootView(JTextComponent a)
Invokes the getRootView method on each UI handled by this object.

Uses of View in javax.swing.text

Subclasses of View in javax.swing.text
class | AsyncBoxView A box that does layout asynchronously.
class | BoxView A view that arranges its children into a box shape by tiling its children along an axis.
class | ComponentView Component decorator that implements the view interface.
class | CompositeView CompositeView is an abstract View implementation which manages one or more child views.
class | FieldView Extends the multi-line plain text view to be suitable for a single-line editor view.
class | FlowView A View that tries to flow it's children into some partially constrained space.
class | GlyphView A GlyphView is a styled chunk of text that represents a view mapped over an element in the text model.
class | IconView Icon decorator that implements the view interface.
class | LabelView A LabelView is a styled chunk of text that represents a view mapped over an element in the text model.
class | ParagraphView View of a simple line-wrapping paragraph that supports multiple fonts, colors, components, icons, etc.
class | PasswordView Implements a View suitable for use in JPasswordField UI implementations.
class | PlainView Implements View interface for a simple multi-line text view that has text in one font and color.
class | TableView Implements View interface for a table, that is composed of an element structure where the child elements of the element this view is responsible for represent rows and the child elements of the row elements are cells.
class | TableView.TableCell Deprecated. A table cell can now be any View implementation.
class | TableView.TableRow View of a row in a row-centric table.
class | WrappedPlainView View of plain text (text with only one font and color) that does line-wrapping.
class | ZoneView ZoneView is a View implementation that creates zones for which the child views are not created or stored until they are needed for display or model/view translations.

Fields in javax.swing.text declared as View
protected  View FlowView.layoutPool
These are the views that represent the child elements of the element this view represents (The logical view to translate to a physical view).

Methods in javax.swing.text that return View
View | ParagraphView.breakView(int axis, float len, Shape a) Breaks this view on the given axis at the given length.
View | GlyphView.breakView(int axis, int p0, float pos, float len) Breaks this view on the given axis at the given length.
View | View.breakView(int axis, int offset, float pos, float len) Tries to break this view on the given axis.
View | ViewFactory.create(Element elem) Creates a view from the given structural element of a document.
View | GlyphView.createFragment(int p0, int p1) Creates a view that represents a portion of the element.
View | View.createFragment(int p0, int p1) Creates a view that represents a portion of the element.
protected abstract View | FlowView.createRow() Create a View that should be used to hold a a rows worth of children in a flow.
protected View | ParagraphView.createRow() Create a View that should be used to hold a a row's worth of children in a flow.
protected View | FlowView.FlowStrategy.createView(FlowView fv, int startOffset, int spanLeft, int rowIndex) Creates a view that can be used to represent the current piece of the flow.
protected View | ZoneView.createZone(int p0, int p1) Create a view to represent a zone for the given range within the model (which should be within the range of this objects responsibility).
View | AsyncBoxView.ChildState.getChildView() Fetch the child view this record represents
protected View | ParagraphView.getLayoutView(int index) Returns the view at a given index.
protected View | FlowView.FlowStrategy.getLogicalView(FlowView fv) This method gives flow strategies access to the logical view of the FlowView.
View | View.getParent() Returns the parent of the view.
View | AsyncBoxView.getView(int n) Gets the nth child view.
View | CompositeView.getView(int n) Returns the n-th view in this container.
View | View.getView(int n) Gets the nth child view.
protected View | BoxView.getViewAtPoint(int x, int y, Rectangle alloc) Fetches the child view at the given coordinates.
protected abstract View | CompositeView.getViewAtPoint(int x, int y, Rectangle alloc) Fetches the child view at the given coordinates.
protected View | TableView.getViewAtPosition(int pos, Rectangle a) Fetches the child view that represents the given position in the model.
protected View | TableView.TableRow.getViewAtPosition(int pos, Rectangle a) Fetches the child view that represents the given position in the model.
protected View | CompositeView.getViewAtPosition(int pos, Rectangle a) Fetches the child view that represents the given position in the model.

Methods in javax.swing.text with parameters of type View
void | View.append(View v) Appends a single child view.
protected AsyncBoxView.ChildState | AsyncBoxView.createChildState(View v) New ChildState records are created through this method to allow subclasses the extend the ChildState records to do/hold more
protected void | View.forwardUpdateToView(View v, DocumentEvent e, Shape a, ViewFactory f) Forwards the DocumentEvent to the give child view.
void | View.insert(int offs, View v) Inserts a single child view.
protected boolean | ZoneView.isZoneLoaded(View zone) Determine if a zone is in the loaded state.
Shape | DefaultHighlighter.DefaultHighlightPainter.paintLayer(Graphics g, int offs0, int offs1, Shape bounds, JTextComponent c, View view) Paints a portion of a highlight.
abstract Shape | LayeredHighlighter.LayerPainter.paintLayer(Graphics g, int p0, int p1, Shape viewBounds, JTextComponent editor, View view)
void | DefaultHighlighter.paintLayeredHighlights(Graphics g, int p0, int p1, Shape viewBounds, JTextComponent editor, View view) When leaf Views (such as LabelView) are rendering they should call into this method.
abstract void | LayeredHighlighter.paintLayeredHighlights(Graphics g, int p0, int p1, Shape viewBounds, JTextComponent editor, View view) When leaf Views (such as LabelView) are rendering they should call into this method.
void | AsyncBoxView.preferenceChanged(View child, boolean width, boolean height) Child views can call this on the parent to indicate that the preference has changed and should be reconsidered for layout.
void | BoxView.preferenceChanged(View child, boolean width, boolean height) This is called by a child to indicate its preferred span has changed.
void | View.preferenceChanged(View child, boolean width, boolean height) Child views can call this on the parent to indicate that the preference has changed and should be reconsidered for layout.
void | TableView.replace(int offset, int length, View[] views) Change the child views.
void | TableView.TableRow.replace(int offset, int length, View[] views) Change the child views.
void | AsyncBoxView.replace(int offset, int length, View[] views) Calls the superclass to update the child views, and updates the status records for the children.
void | BoxView.replace(int index, int length, View[] elems) Invalidates the layout and resizes the cache of requests/allocations.
void | CompositeView.replace(int offset, int length, View[] views) Replaces child views.
void | View.replace(int offset, int length, View[] views) Replaces child views.
void | AsyncBoxView.setParent(View parent) Sets the parent of the view.
void | FlowView.setParent(View parent) Sets the parent of the view.
void | ComponentView.setParent(View p) Sets the parent for a child view.
void | CompositeView.setParent(View parent) Sets the parent of the view.
void | View.setParent(View parent) Establishes the parent view for this view.
protected void | ZoneView.unloadZone(View zone) Unload a zone (Convert the zone to its memory saving state).
protected void | ZoneView.zoneWasLoaded(View zone) Called by a zone when it gets loaded.

Constructors in javax.swing.text with parameters of type View
AsyncBoxView.ChildState(View v)
Construct a child status.

Uses of View in javax.swing.text.html

Subclasses of View in javax.swing.text.html
class | BlockView A view implementation to display a block (as a box) with CSS specifications.
class | FormView Component decorator that implements the view interface for form elements, <input>, <textarea>, and <select>.
class | ImageView View of an Image, intended to support the HTML <IMG> tag.
class | InlineView Displays the inline element styles based upon css attributes.
class | ListView A view implementation to display an html list
class | ObjectView Component decorator that implements the view interface for <object> elements.

Methods in javax.swing.text.html that return View
View | InlineView.breakView(int axis, int offset, float pos, float len) Tries to break this view on the given axis.
View | HTMLEditorKit.HTMLFactory.create(Element elem) Creates a view from an element.

Methods in javax.swing.text.html with parameters of type View
float | StyleSheet.BoxPainter.getInset(int side, View v) Fetches the inset needed on a given side to account for the margin, border, and padding.
AttributeSet | StyleSheet.getViewAttributes(View v) Fetches a set of attributes to use in the view for displaying.
void | StyleSheet.BoxPainter.paint(Graphics g, float x, float y, float w, float h, View v) Paints the CSS box according to the attributes given.
void | StyleSheet.ListPainter.paint(Graphics g, float x, float y, float w, float h, View v, int item) Paints the CSS list decoration according to the attributes given.
void | BlockView.setParent(View parent) Establishes the parent view for this view.
void | ImageView.setParent(View parent) Establishes the parent view for this view.
void | ParagraphView.setParent(View parent) Establishes the parent view for this view.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.WrappedPlainView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.WrappedPlainView

No usage of javax.swing.text.WrappedPlainView

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.ZoneView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.ZoneView

No usage of javax.swing.text.ZoneView

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.AbstractDocument.AttributeContext

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.AbstractDocument.AttributeContext

Packages that use AbstractDocument.AttributeContext
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of AbstractDocument.AttributeContext in javax.swing.text

Classes in javax.swing.text that implement AbstractDocument.AttributeContext
 class StyleContext
A pool of styles and their associated resources.

Methods in javax.swing.text that return AbstractDocument.AttributeContext
protected  AbstractDocument.AttributeContext AbstractDocument.getAttributeContext()
Fetches the context for managing attributes.

Constructors in javax.swing.text with parameters of type AbstractDocument.AttributeContext
AbstractDocument(AbstractDocument.Content data, AbstractDocument.AttributeContext context)
Constructs a new AbstractDocument, wrapped around some specified content storage mechanism.

Uses of AbstractDocument.AttributeContext in javax.swing.text.html

Classes in javax.swing.text.html that implement AbstractDocument.AttributeContext
 class StyleSheet
Support for defining the visual characteristics of HTML views being rendered.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.AbstractDocument.Content

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.AbstractDocument.Content

Packages that use AbstractDocument.Content
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of AbstractDocument.Content in javax.swing.text

Classes in javax.swing.text that implement AbstractDocument.Content
class | GapContent An implementation of the AbstractDocument.Content interface implemented using a gapped buffer similar to that used by emacs.
class | StringContent An implementation of the AbstractDocument.Content interface that is a brute force implementation that is useful for relatively small documents and/or debugging.

Methods in javax.swing.text that return AbstractDocument.Content
protected  AbstractDocument.Content AbstractDocument.getContent()
Gets the content for the document.

Constructors in javax.swing.text with parameters of type AbstractDocument.Content
AbstractDocument(AbstractDocument.Content data)
Constructs a new AbstractDocument, wrapped around some specified content storage mechanism.
AbstractDocument(AbstractDocument.Content data, AbstractDocument.AttributeContext context)
Constructs a new AbstractDocument, wrapped around some specified content storage mechanism.
DefaultStyledDocument(AbstractDocument.Content c, StyleContext styles)
Constructs a styled document.
PlainDocument(AbstractDocument.Content c)
Constructs a plain text document.

Uses of AbstractDocument.Content in javax.swing.text.html

Constructors in javax.swing.text.html with parameters of type AbstractDocument.Content
HTMLDocument(AbstractDocument.Content c, StyleSheet styles)
Constructs an HTML document with the given content storage implementation and the given style/attribute storage mechanism.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.AttributeSet

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.AttributeSet

Packages that use AttributeSet
java.awt | Contains all of the classes for creating user interfaces and for painting graphics and images.
javax.accessibility | Defines a contract between user-interface components and an assistive technology that provides access to those components.
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of AttributeSet in java.awt

Methods in java.awt that return AttributeSet
 AttributeSet TextComponent.AccessibleAWTTextComponent.getCharacterAttribute(int i)
Returns the AttributeSet for a given character (at a given index).

Uses of AttributeSet in javax.accessibility

Fields in javax.accessibility declared as AttributeSet
 AttributeSet AccessibleAttributeSequence.attributes
The text attributes

Methods in javax.accessibility that return AttributeSet
 AttributeSet AccessibleText.getCharacterAttribute(int i)
Returns the AttributeSet for a given character at a given index

Methods in javax.accessibility with parameters of type AttributeSet
 void AccessibleEditableText.setAttributes(int startIndex, int endIndex, AttributeSet as)
Sets attributes for the text between two indices.

Constructors in javax.accessibility with parameters of type AttributeSet
AccessibleAttributeSequence(int start, int end, AttributeSet attr)
Constructs an AccessibleAttributeSequence with the given parameters.

Uses of AttributeSet in javax.swing

Methods in javax.swing that return AttributeSet
AttributeSet | ProgressMonitor.AccessibleProgressMonitor.getCharacterAttribute(int i) Returns the AttributeSet for a given character at a given index
AttributeSet | JSpinner.AccessibleJSpinner.getCharacterAttribute(int i) Returns the AttributeSet for a given character at a given index
AttributeSet | JLabel.AccessibleJLabel.getCharacterAttribute(int i) Return the AttributeSet for a given character at a given index
AttributeSet | AbstractButton.AccessibleAbstractButton.getCharacterAttribute(int i) Return the AttributeSet for a given character at a given index
AttributeSet | JTextPane.getCharacterAttributes() Fetches the character attributes in effect at the current location of the caret, or null.
AttributeSet | JTextPane.getParagraphAttributes() Fetches the current paragraph attributes in effect at the location of the caret, or null if none.

Methods in javax.swing with parameters of type AttributeSet
void | JSpinner.AccessibleJSpinner.setAttributes(int startIndex, int endIndex, AttributeSet as) Sets attributes for the text between two indices.
void | JTextPane.setCharacterAttributes(AttributeSet attr, boolean replace) Applies the given attributes to character content.
void | JTextPane.setParagraphAttributes(AttributeSet attr, boolean replace) Applies the given attributes to paragraphs.

Uses of AttributeSet in javax.swing.text

Subinterfaces of AttributeSet in javax.swing.text
interface | MutableAttributeSet A generic interface for a mutable collection of unique attributes.
interface | Style A collection of attributes to associate with an element in a document.

Classes in javax.swing.text that implement AttributeSet
class | AbstractDocument.AbstractElement Implements the abstract part of an element.
class | AbstractDocument.BranchElement Implements a composite element that contains other elements.
class | AbstractDocument.LeafElement Implements an element that directly represents content of some kind.
protected class | DefaultStyledDocument.SectionElement Default root element for a document...
class | SimpleAttributeSet A straightforward implementation of MutableAttributeSet using a hash table.
class | StyleContext.NamedStyle A collection of attributes, typically used to represent character and paragraph styles.
class | StyleContext.SmallAttributeSet This class holds a small number of attributes in an array.

Fields in javax.swing.text declared as AttributeSet
protected AttributeSet | DefaultStyledDocument.AttributeUndoableEdit.copy
static AttributeSet | SimpleAttributeSet.EMPTY An empty attribute set.
protected AttributeSet | DefaultStyledDocument.AttributeUndoableEdit.newAttributes

Methods in javax.swing.text that return AttributeSet
AttributeSet | AbstractDocument.AttributeContext.addAttribute(AttributeSet old, Object name, Object value) Adds an attribute to the given set, and returns the new representative set.
AttributeSet | StyleContext.addAttribute(AttributeSet old, Object name, Object value) Adds an attribute to the given set, and returns the new representative set.
AttributeSet | AbstractDocument.AttributeContext.addAttributes(AttributeSet old, AttributeSet attr) Adds a set of attributes to the element.
AttributeSet | StyleContext.addAttributes(AttributeSet old, AttributeSet attr) Adds a set of attributes to the element.
AttributeSet | AbstractDocument.AbstractElement.copyAttributes() Copies a set of attributes.
AttributeSet | StyleContext.SmallAttributeSet.copyAttributes() Copies a set of attributes.
AttributeSet | StyleContext.NamedStyle.copyAttributes() Copies a set of attributes.
AttributeSet | SimpleAttributeSet.copyAttributes() Makes a copy of the attributes.
AttributeSet | AttributeSet.copyAttributes() Returns an attribute set that is guaranteed not to change over time.
AttributeSet | DefaultStyledDocument.ElementSpec.getAttributes() Gets the element attributes.
AttributeSet | AbstractDocument.AbstractElement.getAttributes() Gets the attributes for the element.
AttributeSet | Element.getAttributes() Fetches the collection of attributes this element contains.
AttributeSet | View.getAttributes() Fetches the attributes to use when rendering.
AttributeSet | JTextComponent.AccessibleJTextComponent.getCharacterAttribute(int i) Returns the AttributeSet for a given character (at a given index).
AttributeSet | AbstractDocument.AttributeContext.getEmptySet() Fetches an empty AttributeSet.
AttributeSet | StyleContext.getEmptySet() Fetches an empty AttributeSet.
AttributeSet | AbstractDocument.AbstractElement.getResolveParent() Gets the resolving parent.
AttributeSet | StyleContext.SmallAttributeSet.getResolveParent() If not overriden, the resolving parent defaults to the parent element.
AttributeSet | StyleContext.NamedStyle.getResolveParent() Gets attributes from the parent.
AttributeSet | SimpleAttributeSet.getResolveParent() Gets the resolving parent.
AttributeSet | AttributeSet.getResolveParent() Gets the resolving parent.
AttributeSet | AbstractDocument.AttributeContext.removeAttribute(AttributeSet old, Object name) Removes an attribute from the set.
AttributeSet | StyleContext.removeAttribute(AttributeSet old, Object name) Removes an attribute from the set.
AttributeSet | AbstractDocument.AttributeContext.removeAttributes(AttributeSet old, AttributeSet attrs) Removes a set of attributes for the element.
AttributeSet | StyleContext.removeAttributes(AttributeSet old, AttributeSet attrs) Removes a set of attributes for the element.
AttributeSet | AbstractDocument.AttributeContext.removeAttributes(AttributeSet old, Enumeration<?> names) Removes a set of attributes for the element.
AttributeSet | StyleContext.removeAttributes(AttributeSet old, Enumeration<?> names) Removes a set of attributes for the element.

Methods in javax.swing.text with parameters of type AttributeSet
AttributeSet | AbstractDocument.AttributeContext.addAttribute(AttributeSet old, Object name, Object value) Adds an attribute to the given set, and returns the new representative set.
AttributeSet | StyleContext.addAttribute(AttributeSet old, Object name, Object value) Adds an attribute to the given set, and returns the new representative set.
void | AbstractDocument.AbstractElement.addAttributes(AttributeSet attr) Adds a set of attributes to the element.
void | StyleContext.NamedStyle.addAttributes(AttributeSet attr) Adds a set of attributes to the element.
void | MutableAttributeSet.addAttributes(AttributeSet attributes) Creates a new attribute set similar to this one except that it contains the given attributes and values.
void | SimpleAttributeSet.addAttributes(AttributeSet attributes) Adds a set of attributes to the list.
AttributeSet | AbstractDocument.AttributeContext.addAttributes(AttributeSet old, AttributeSet attr) Adds a set of attributes to the element.
AttributeSet | StyleContext.addAttributes(AttributeSet old, AttributeSet attr) Adds a set of attributes to the element.
boolean | AbstractDocument.AbstractElement.containsAttributes(AttributeSet attrs) Checks whether the element contains all the attributes.
boolean | StyleContext.SmallAttributeSet.containsAttributes(AttributeSet attrs) Checks whether the attribute set contains all of the given attributes.
boolean | StyleContext.NamedStyle.containsAttributes(AttributeSet attrs) Checks whether the element contains all the attributes.
boolean | SimpleAttributeSet.containsAttributes(AttributeSet attributes) Checks whether the attribute list contains all the specified name/value pairs.
boolean | AttributeSet.containsAttributes(AttributeSet attributes) Returns true if this set defines all the attributes from the given set with equal values.
protected Element | AbstractDocument.createBranchElement(Element parent, AttributeSet a) Creates a document branch element, that can contain other elements.
protected MutableAttributeSet | StyleContext.createLargeAttributeSet(AttributeSet a) Create a large set of attributes that should trade off space for time.
protected Element | AbstractDocument.createLeafElement(Element parent, AttributeSet a, int p0, int p1) Creates a document leaf element.
protected StyleContext.SmallAttributeSet | StyleContext.createSmallAttributeSet(AttributeSet a) Create a compact set of attributes that might be shared.
static int | StyleConstants.getAlignment(AttributeSet a) Gets the alignment setting.
Color | DefaultStyledDocument.getBackground(AttributeSet attr) Gets the background color from an attribute set.
static Color | StyleConstants.getBackground(AttributeSet a) Gets the background color setting from the attribute list.
Color | StyleContext.getBackground(AttributeSet attr) Takes a set of attributes and turn it into a background color specification.
Color | StyledDocument.getBackground(AttributeSet attr) Takes a set of attributes and turn it into a background color specification.
static int | StyleConstants.getBidiLevel(AttributeSet a) Gets the BidiLevel setting.
static Component | StyleConstants.getComponent(AttributeSet a) Gets the component setting from the attribute list.
static float | StyleConstants.getFirstLineIndent(AttributeSet a) Gets the first line indent setting.
Font | DefaultStyledDocument.getFont(AttributeSet attr) Gets the font from an attribute set.
Font | StyleContext.getFont(AttributeSet attr) Gets the font from an attribute set.
Font | StyledDocument.getFont(AttributeSet attr) Takes a set of attributes and turn it into a font specification.
static String | StyleConstants.getFontFamily(AttributeSet a) Gets the font family setting from the attribute list.
static int | StyleConstants.getFontSize(AttributeSet a) Gets the font size setting from the attribute list.
Color | DefaultStyledDocument.getForeground(AttributeSet attr) Gets the foreground color from an attribute set.
static Color | StyleConstants.getForeground(AttributeSet a) Gets the foreground color setting from the attribute list.
Color | StyleContext.getForeground(AttributeSet attr) Takes a set of attributes and turn it into a foreground color specification.
Color | StyledDocument.getForeground(AttributeSet attr) Takes a set of attributes and turn it into a foreground color specification.
static Icon | StyleConstants.getIcon(AttributeSet a) Gets the icon setting from the attribute list.
static float | StyleConstants.getLeftIndent(AttributeSet a) Gets the left indent setting.
static float | StyleConstants.getLineSpacing(AttributeSet a) Gets the line spacing setting.
static float | StyleConstants.getRightIndent(AttributeSet a) Gets the right indent setting.
static float | StyleConstants.getSpaceAbove(AttributeSet a) Gets the space above setting.
static float | StyleConstants.getSpaceBelow(AttributeSet a) Gets the space below setting.
static TabSet | StyleConstants.getTabSet(AttributeSet a) Gets the TabSet.
void | DocumentFilter.insertString(DocumentFilter.FilterBypass fb, int offset, String string, AttributeSet attr) Invoked prior to insertion of text into the specified Document.
void | PlainDocument.insertString(int offs, String str, AttributeSet a) Inserts some content into the document.
void | AbstractDocument.insertString(int offs, String str, AttributeSet a) Inserts some content into the document.
abstract void | DocumentFilter.FilterBypass.insertString(int offset, String string, AttributeSet attr) Inserts the specified text, bypassing the DocumentFilter.
void | Document.insertString(int offset, String str, AttributeSet a) Inserts a string of content.
protected void | PlainDocument.insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr) Updates document structure as a result of text insertion.
protected void | DefaultStyledDocument.insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr) Updates document structure as a result of text insertion.
protected void | AbstractDocument.insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr) Updates document structure as a result of text insertion.
static boolean | StyleConstants.isBold(AttributeSet a) Checks whether the bold attribute is set.
boolean | AbstractDocument.AbstractElement.isEqual(AttributeSet attr) Checks whether two attribute sets are equal.
boolean | StyleContext.SmallAttributeSet.isEqual(AttributeSet attr) Checks whether two attribute sets are equal.
boolean | StyleContext.NamedStyle.isEqual(AttributeSet attr) Checks whether two attribute sets are equal.
boolean | SimpleAttributeSet.isEqual(AttributeSet attr) Compares two attribute sets.
boolean | AttributeSet.isEqual(AttributeSet attr) Determines if the two attribute sets are equivalent.
static boolean | StyleConstants.isItalic(AttributeSet a) Checks whether the italic attribute is set.
static boolean | StyleConstants.isStrikeThrough(AttributeSet a) Checks whether the strikethrough attribute is set.
static boolean | StyleConstants.isSubscript(AttributeSet a) Checks whether the subscript attribute is set.
static boolean | StyleConstants.isSuperscript(AttributeSet a) Checks whether the superscript attribute is set.
static boolean | StyleConstants.isUnderline(AttributeSet a) Checks whether the underline attribute is set.
void | AbstractDocument.AttributeContext.reclaim(AttributeSet a) Reclaims an attribute set.
void | StyleContext.reclaim(AttributeSet a) Returns a set no longer needed by the MutableAttributeSet implmentation.
AttributeSet | AbstractDocument.AttributeContext.removeAttribute(AttributeSet old, Object name) Removes an attribute from the set.
AttributeSet | StyleContext.removeAttribute(AttributeSet old, Object name) Removes an attribute from the set.
void | AbstractDocument.AbstractElement.removeAttributes(AttributeSet attrs) Removes a set of attributes for the element.
void | StyleContext.NamedStyle.removeAttributes(AttributeSet attrs) Removes a set of attributes for the element.
void | MutableAttributeSet.removeAttributes(AttributeSet attributes) Removes a set of attributes with the given name.
void | SimpleAttributeSet.removeAttributes(AttributeSet attributes) Removes a set of attributes from the list.
AttributeSet | AbstractDocument.AttributeContext.removeAttributes(AttributeSet old, AttributeSet attrs) Removes a set of attributes for the element.
AttributeSet | StyleContext.removeAttributes(AttributeSet old, AttributeSet attrs) Removes a set of attributes for the element.
AttributeSet | AbstractDocument.AttributeContext.removeAttributes(AttributeSet old, Enumeration<?> names) Removes a set of attributes for the element.
AttributeSet | StyleContext.removeAttributes(AttributeSet old, Enumeration<?> names) Removes a set of attributes for the element.
void | DocumentFilter.replace(DocumentFilter.FilterBypass fb, int offset, int length, String text, AttributeSet attrs) Invoked prior to replacing a region of text in the specified Document.
void | AbstractDocument.replace(int offset, int length, String text, AttributeSet attrs) Deletes the region of text from offset to offset + length, and replaces it with text.
abstract void | DocumentFilter.FilterBypass.replace(int offset, int length, String string, AttributeSet attrs) Deletes the region of text from offset to offset + length, and replaces it with text.
void | JTextComponent.AccessibleJTextComponent.setAttributes(int startIndex, int endIndex, AttributeSet as) Sets attributes for the text between two indices.
void | DefaultStyledDocument.setCharacterAttributes(int offset, int length, AttributeSet s, boolean replace) Sets attributes for some part of the document.
void | StyledDocument.setCharacterAttributes(int offset, int length, AttributeSet s, boolean replace) Changes the content element attributes used for the given range of existing content in the document.
protected void | StyledEditorKit.StyledTextAction.setCharacterAttributes(JEditorPane editor, AttributeSet attr, boolean replace) Applies the given attributes to character content.
void | DefaultStyledDocument.setParagraphAttributes(int offset, int length, AttributeSet s, boolean replace) Sets attributes for a paragraph.
void | StyledDocument.setParagraphAttributes(int offset, int length, AttributeSet s, boolean replace) Sets paragraph attributes.
protected void | StyledEditorKit.StyledTextAction.setParagraphAttributes(JEditorPane editor, AttributeSet attr, boolean replace) Applies the given attributes to paragraphs.
protected void | CompositeView.setParagraphInsets(AttributeSet attr) Sets the insets from the paragraph attributes specified in the given attributes.
void | AbstractDocument.AbstractElement.setResolveParent(AttributeSet parent) Sets the resolving parent.
void | StyleContext.NamedStyle.setResolveParent(AttributeSet parent) Sets the resolving parent.
void | MutableAttributeSet.setResolveParent(AttributeSet parent) Sets the resolving parent.
void | SimpleAttributeSet.setResolveParent(AttributeSet parent) Sets the resolving parent.
protected void | AbstractWriter.writeAttributes(AttributeSet attr) Writes out the set of attributes as " =" pairs.
void | StyleContext.writeAttributes(ObjectOutputStream out, AttributeSet a) Context-specific handling of writing out attributes
static void | StyleContext.writeAttributeSet(ObjectOutputStream out, AttributeSet a) Writes a set of attributes to the given object stream for the purpose of serialization.

Constructors in javax.swing.text with parameters of type AttributeSet
AbstractDocument.AbstractElement(Element parent, AttributeSet a)
Creates a new AbstractElement.
AbstractDocument.BranchElement(Element parent, AttributeSet a)
Constructs a composite element that initially contains no children.
AbstractDocument.LeafElement(Element parent, AttributeSet a, int offs0, int offs1)
Constructs an element that represents content within the document (has no children).
DefaultStyledDocument.AttributeUndoableEdit(Element element, AttributeSet newAttributes, boolean isReplacing)
DefaultStyledDocument.ElementSpec(AttributeSet a, short type)
Constructor useful for markup when the markup will not be stored in the document.
DefaultStyledDocument.ElementSpec(AttributeSet a, short type, char[] txt, int offs, int len)
Constructor for creating a spec externally for batch input of content and markup into the document.
DefaultStyledDocument.ElementSpec(AttributeSet a, short type, int len)
Constructor for parsing inside the document when the data has already been added, but len information is needed.
SimpleAttributeSet(AttributeSet source)
Creates a new attribute set based on a supplied set of attributes.
StyleContext.SmallAttributeSet(AttributeSet attrs)

Uses of AttributeSet in javax.swing.text.html

Classes in javax.swing.text.html that implement AttributeSet
class | HTMLDocument.BlockElement An element that represents a structural block of HTML.
class | HTMLDocument.RunElement An element that represents a chunk of text that has a set of HTML character level attributes assigned to it.

Methods in javax.swing.text.html that return AttributeSet
AttributeSet | StyleSheet.addAttribute(AttributeSet old, Object key, Object value) Adds an attribute to the given set, and returns the new representative set.
AttributeSet | StyleSheet.addAttributes(AttributeSet old, AttributeSet attr) Adds a set of attributes to the element.
AttributeSet | BlockView.getAttributes() Fetches the attributes to use when rendering.
abstract AttributeSet | HTMLDocument.Iterator.getAttributes() Return the attributes for this tag.
AttributeSet | ImageView.getAttributes() Fetches the attributes to use when rendering.
AttributeSet | ParagraphView.getAttributes() Fetches the attributes to use when rendering.
AttributeSet | InlineView.getAttributes() Fetches the attributes to use when rendering.
AttributeSet | Option.getAttributes() Fetch the attributes associated with this option.
AttributeSet | StyleSheet.getDeclaration(String decl) Translates a CSS declaration to an AttributeSet that represents the CSS declaration.
AttributeSet | HTMLDocument.RunElement.getResolveParent() Gets the resolving parent.
AttributeSet | HTMLDocument.BlockElement.getResolveParent() Gets the resolving parent.
AttributeSet | StyleSheet.getViewAttributes(View v) Fetches a set of attributes to use in the view for displaying.
AttributeSet | StyleSheet.removeAttribute(AttributeSet old, Object key) Removes an attribute from the set.
AttributeSet | StyleSheet.removeAttributes(AttributeSet old, AttributeSet attrs) Removes a set of attributes.
AttributeSet | StyleSheet.removeAttributes(AttributeSet old, Enumeration<?> names) Removes a set of attributes for the element.
AttributeSet | StyleSheet.translateHTMLToCSS(AttributeSet htmlAttrSet) Converts a set of HTML attributes to an equivalent set of CSS attributes.

Methods in javax.swing.text.html with parameters of type AttributeSet
AttributeSet | StyleSheet.addAttribute(AttributeSet old, Object key, Object value) Adds an attribute to the given set, and returns the new representative set.
AttributeSet | StyleSheet.addAttributes(AttributeSet old, AttributeSet attr) Adds a set of attributes to the element.
protected void | HTMLWriter.closeOutUnwantedEmbeddedTags(AttributeSet attr) Searches the attribute set and for each tag that is stored in the tag vector.
protected Element | HTMLDocument.createBranchElement(Element parent, AttributeSet a) Creates a document branch element, that can contain other elements.
protected MutableAttributeSet | StyleSheet.createLargeAttributeSet(AttributeSet a) Creates a large set of attributes that should trade off space for time.
protected Element | HTMLDocument.createLeafElement(Element parent, AttributeSet a, int p0, int p1) Creates a document leaf element that directly represents text (doesn't have any children).
protected StyleContext.SmallAttributeSet | StyleSheet.createSmallAttributeSet(AttributeSet a) Creates a compact set of attributes that might be shared.
Color | StyleSheet.getBackground(AttributeSet a) Takes a set of attributes and turn it into a background color specification.
StyleSheet.BoxPainter | StyleSheet.getBoxPainter(AttributeSet a) Fetches the box formatter to use for the given set of CSS attributes.
Font | StyleSheet.getFont(AttributeSet a) Fetches the font to use for the given set of attributes.
Color | StyleSheet.getForeground(AttributeSet a) Takes a set of attributes and turn it into a foreground color specification.
static int | HTML.getIntegerAttributeValue(AttributeSet attr, HTML.Attribute key, int def) Fetches an integer attribute value.
StyleSheet.ListPainter | StyleSheet.getListPainter(AttributeSet a) Fetches the list formatter to use for the given set of CSS attributes.
protected void | HTMLDocument.insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr) Updates document structure as a result of text insertion.
protected boolean | HTMLWriter.isBlockTag(AttributeSet attr) Determines if the HTML.Tag associated with the element is a block tag.
protected boolean | HTMLWriter.matchNameAttribute(AttributeSet attr, HTML.Tag tag) Returns true if the StyleConstants.NameAttribute is equal to the tag that is passed in as a parameter.
AttributeSet | StyleSheet.removeAttribute(AttributeSet old, Object key) Removes an attribute from the set.
AttributeSet | StyleSheet.removeAttributes(AttributeSet old, AttributeSet attrs) Removes a set of attributes.
AttributeSet | StyleSheet.removeAttributes(AttributeSet old, Enumeration<?> names) Removes a set of attributes for the element.
protected void | HTMLWriter.selectContent(AttributeSet attr) Writes out the content of the SELECT form element.
void | HTMLDocument.setParagraphAttributes(int offset, int length, AttributeSet s, boolean replace) Sets attributes for a paragraph.
protected void | HTMLWriter.textAreaContent(AttributeSet attr) Writes out text that is contained in a TEXTAREA form element.
AttributeSet | StyleSheet.translateHTMLToCSS(AttributeSet htmlAttrSet) Converts a set of HTML attributes to an equivalent set of CSS attributes.
protected void | HTMLWriter.writeAttributes(AttributeSet attr) Writes out the attribute set.
protected void | MinimalHTMLWriter.writeAttributes(AttributeSet attr) Writes out all the attributes for the following types: StyleConstants.ParagraphConstants, StyleConstants.CharacterConstants, StyleConstants.FontConstants, StyleConstants.ColorConstants.
protected void | HTMLWriter.writeEmbeddedTags(AttributeSet attr) Searches for embedded tags in the AttributeSet and writes them out.
protected void | MinimalHTMLWriter.writeHTMLTags(AttributeSet attr) Generates bold <b>, italic <i>, and <u> tags for the text based on its attribute settings.
protected void | MinimalHTMLWriter.writeNonHTMLAttributes(AttributeSet attr) Writes out the remaining character-level attributes (attributes other than bold, italic, and underline) in an HTML-compliant way.

Constructors in javax.swing.text.html with parameters of type AttributeSet
HTMLDocument.BlockElement(Element parent, AttributeSet a)
Constructs a composite element that initially contains no children.
HTMLDocument.RunElement(Element parent, AttributeSet a, int offs0, int offs1)
Constructs an element that represents content within the document (has no children).
Option(AttributeSet attr)
Creates a new Option object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.AttributeSet.CharacterAttribute

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.AttributeSet.CharacterAttribute

Packages that use AttributeSet.CharacterAttribute
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of AttributeSet.CharacterAttribute in javax.swing.text

Classes in javax.swing.text that implement AttributeSet.CharacterAttribute
static class | StyleConstants.CharacterConstants This is a typesafe enumeration of the well-known attributes that contribute to a character style.
static class | StyleConstants.ColorConstants This is a typesafe enumeration of the well-known attributes that contribute to a color.
static class | StyleConstants.FontConstants This is a typesafe enumeration of the well-known attributes that contribute to a font.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.AttributeSet.ColorAttribute

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.AttributeSet.ColorAttribute

Packages that use AttributeSet.ColorAttribute
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of AttributeSet.ColorAttribute in javax.swing.text

Classes in javax.swing.text that implement AttributeSet.ColorAttribute
static class StyleConstants.ColorConstants
This is a typesafe enumeration of the well-known attributes that contribute to a color.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.AttributeSet.FontAttribute

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.AttributeSet.FontAttribute

Packages that use AttributeSet.FontAttribute
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of AttributeSet.FontAttribute in javax.swing.text

Classes in javax.swing.text that implement AttributeSet.FontAttribute
static class StyleConstants.FontConstants
This is a typesafe enumeration of the well-known attributes that contribute to a font.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.AttributeSet.ParagraphAttribute

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.AttributeSet.ParagraphAttribute

Packages that use AttributeSet.ParagraphAttribute
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of AttributeSet.ParagraphAttribute in javax.swing.text

Classes in javax.swing.text that implement AttributeSet.ParagraphAttribute
static class StyleConstants.ParagraphConstants
This is a typesafe enumeration of the well-known attributes that contribute to a paragraph style.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.Caret

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.Caret

Packages that use Caret
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of Caret in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement Caret
static class BasicTextUI.BasicCaret

Methods in javax.swing.plaf.basic that return Caret
protected  Caret BasicTextUI.createCaret()
Creates the object to use for a caret.

Uses of Caret in javax.swing.text

Classes in javax.swing.text that implement Caret
 class DefaultCaret
A default implementation of Caret.

Methods in javax.swing.text that return Caret
Caret | DefaultEditorKit.createCaret() Fetches a caret that can navigate through views produced by the associated ViewFactory.
abstract Caret | EditorKit.createCaret() Fetches a caret that can navigate through views produced by the associated ViewFactory.
Caret | JTextComponent.getCaret() Fetches the caret that allows text-oriented navigation over the view.
abstract Caret | NavigationFilter.FilterBypass.getCaret() Returns the Caret that is changing.

Methods in javax.swing.text with parameters of type Caret
 void JTextComponent.setCaret(Caret c)
Sets the caret to be used.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.Document

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.Document

Packages that use Document
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.
javax.swing.text.rtf | Provides a class (RTFEditorKit) for creating Rich-Text-Format text editors.

Uses of Document in javax.swing

Methods in javax.swing that return Document
protected Document | JTextArea.createDefaultModel() Creates the default implementation of the model to be used at construction if one isn't explicitly given.
protected Document | JTextField.createDefaultModel() Creates the default implementation of the model to be used at construction if one isn't explicitly given.

Methods in javax.swing with parameters of type Document
void | JFormattedTextField.setDocument(Document doc) Associates the editor with a text document.
void | JTextPane.setDocument(Document doc) Associates the editor with a text document.
void | JTextField.setDocument(Document doc) Associates the editor with a text document.

Constructors in javax.swing with parameters of type Document
JPasswordField(Document doc, String txt, int columns)
Constructs a new JPasswordField that uses the given text storage model and the given number of columns.
JTextArea(Document doc)
Constructs a new JTextArea with the given document model, and defaults for all of the other arguments (null, 0, 0).
JTextArea(Document doc, String text, int rows, int columns)
Constructs a new JTextArea with the specified number of rows and columns, and the given model.
JTextField(Document doc, String text, int columns)
Constructs a new JTextField that uses the given text storage model and the given number of columns.

Uses of Document in javax.swing.event

Methods in javax.swing.event that return Document
 Document DocumentEvent.getDocument()
Gets the document that sourced the change event.

Uses of Document in javax.swing.text

Subinterfaces of Document in javax.swing.text
 interface StyledDocument
Interface for a generic styled document.

Classes in javax.swing.text that implement Document
class | AbstractDocument An implementation of the document interface to serve as a basis for implementing various kinds of documents.
class | DefaultStyledDocument A document that can be marked up with character and paragraph styles in a manner similar to the Rich Text Format.
class | PlainDocument A plain document that maintains no character attributes.

Methods in javax.swing.text that return Document
Document | StyledEditorKit.createDefaultDocument() Creates an uninitialized text storage model that is appropriate for this type of editor.
Document | DefaultEditorKit.createDefaultDocument() Creates an uninitialized text storage model (PlainDocument) that is appropriate for this type of editor.
abstract Document | EditorKit.createDefaultDocument() Creates an uninitialized text storage model that is appropriate for this type of editor.
protected Document | AbstractWriter.getDocument() Fetches the document.
Document | AbstractDocument.AbstractElement.getDocument() Retrieves the underlying model.
Document | AbstractDocument.DefaultDocumentEvent.getDocument() Gets the document that sourced the change event.
Document | JTextComponent.getDocument() Fetches the model associated with the editor.
abstract Document | DocumentFilter.FilterBypass.getDocument() Returns the Document the mutation is occuring on.
Document | Element.getDocument() Fetches the document associated with this element.
Document | View.getDocument() Fetches the model associated with the view.

Methods in javax.swing.text with parameters of type Document
void | DefaultEditorKit.read(InputStream in, Document doc, int pos) Inserts content from the given stream which is expected to be in a format appropriate for this kind of content handler.
abstract void | EditorKit.read(InputStream in, Document doc, int pos) Inserts content from the given stream which is expected to be in a format appropriate for this kind of content handler.
void | DefaultEditorKit.read(Reader in, Document doc, int pos) Inserts content from the given stream, which will be treated as plain text.
abstract void | EditorKit.read(Reader in, Document doc, int pos) Inserts content from the given stream which is expected to be in a format appropriate for this kind of content handler.
void | JTextComponent.setDocument(Document doc) Associates the editor with a text document.
void | DefaultEditorKit.write(OutputStream out, Document doc, int pos, int len) Writes content from a document to the given stream in a format appropriate for this kind of content handler.
abstract void | EditorKit.write(OutputStream out, Document doc, int pos, int len) Writes content from a document to the given stream in a format appropriate for this kind of content handler.
void | DefaultEditorKit.write(Writer out, Document doc, int pos, int len) Writes content from a document to the given stream as plain text.
abstract void | EditorKit.write(Writer out, Document doc, int pos, int len) Writes content from a document to the given stream in a format appropriate for this kind of content handler.

Constructors in javax.swing.text with parameters of type Document
AbstractWriter(Writer w, Document doc)
Creates a new AbstractWriter.
AbstractWriter(Writer w, Document doc, int pos, int len)
Creates a new AbstractWriter.
ElementIterator(Document document)
Creates a new ElementIterator.

Uses of Document in javax.swing.text.html

Classes in javax.swing.text.html that implement Document
 class HTMLDocument
A document that models HTML.

Methods in javax.swing.text.html that return Document
 Document HTMLEditorKit.createDefaultDocument()
Create an uninitialized text storage model that is appropriate for this type of editor.

Methods in javax.swing.text.html with parameters of type Document
void | HTMLEditorKit.read(Reader in, Document doc, int pos) Inserts content from the given stream.
void | HTMLEditorKit.write(Writer out, Document doc, int pos, int len) Write content from a document to the given stream in a format appropriate for this kind of content handler.

Uses of Document in javax.swing.text.rtf

Methods in javax.swing.text.rtf with parameters of type Document
void | RTFEditorKit.read(InputStream in, Document doc, int pos) Insert content from the given stream which is expected to be in a format appropriate for this kind of content handler.
void | RTFEditorKit.read(Reader in, Document doc, int pos) Insert content from the given stream, which will be treated as plain text.
void | RTFEditorKit.write(OutputStream out, Document doc, int pos, int len) Write content from a document to the given stream in a format appropriate for this kind of content handler.
void | RTFEditorKit.write(Writer out, Document doc, int pos, int len) Write content from a document to the given stream as plain text.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.Element

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.Element

Packages that use Element
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of Element in javax.swing

Constructors in javax.swing with parameters of type Element
JEditorPane.JEditorPaneAccessibleHypertextSupport.HTMLLink(Element e)

Uses of Element in javax.swing.event

Methods in javax.swing.event that return Element
Element[] | DocumentEvent.ElementChange.getChildrenAdded() Gets the child elements that were added to the given parent element.
Element[] | DocumentEvent.ElementChange.getChildrenRemoved() Gets the child elements that were removed from the given parent element.
Element | DocumentEvent.ElementChange.getElement() Returns the element represented.
Element | HyperlinkEvent.getSourceElement() Returns the Element that corresponds to the source of the event.

Methods in javax.swing.event with parameters of type Element
 DocumentEvent.ElementChange DocumentEvent.getChange(Element elem)
Gets the change information for the given element.

Constructors in javax.swing.event with parameters of type Element
HyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL u, String desc, Element sourceElement)
Creates a new object representing a hypertext link event.

Uses of Element in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic with parameters of type Element
View | BasicPasswordFieldUI.create(Element elem) Creates a view (PasswordView) for an element.
View | BasicTextAreaUI.create(Element elem) Creates the view for an element.
View | BasicTextFieldUI.create(Element elem) Creates a view (FieldView) based on an element.
View | BasicTextUI.create(Element elem) Creates a view for an element.
View | BasicTextUI.create(Element elem, int p0, int p1) Creates a view for an element.

Uses of Element in javax.swing.text

Classes in javax.swing.text that implement Element
class | AbstractDocument.AbstractElement Implements the abstract part of an element.
class | AbstractDocument.BranchElement Implements a composite element that contains other elements.
class | AbstractDocument.LeafElement Implements an element that directly represents content of some kind.
protected class | DefaultStyledDocument.SectionElement Default root element for a document...

Fields in javax.swing.text declared as Element
protected  Element DefaultStyledDocument.AttributeUndoableEdit.element

Methods in javax.swing.text that return Element
Element | DefaultStyledDocument.ElementBuffer.clone(Element parent, Element clonee) Creates a copy of this element, with a different parent.
protected Element | AbstractDocument.createBranchElement(Element parent, AttributeSet a) Creates a document branch element, that can contain other elements.
protected Element | AbstractDocument.createLeafElement(Element parent, AttributeSet a, int p0, int p1) Creates a document leaf element.
Element | ElementIterator.current() Fetches the current Element.
Element | ElementIterator.first() Fetches the first element.
Element | AbstractDocument.getBidiRootElement() Returns the root element of the bidirectional structure for this document.
Element | StyledEditorKit.getCharacterAttributeRun() Fetches the element representing the current run of character attributes for the caret.
Element | DefaultStyledDocument.getCharacterElement(int pos) Gets a character element based on a position.
Element | StyledDocument.getCharacterElement(int pos) Gets the element that represents the character that is at the given offset within the document.
Element[] | AbstractDocument.ElementEdit.getChildrenAdded() Gets a list of children that were added.
Element[] | AbstractDocument.ElementEdit.getChildrenRemoved() Gets a list of children that were removed.
Element | PlainDocument.getDefaultRootElement() Gets the default root element for the document model.
Element | DefaultStyledDocument.getDefaultRootElement() Gets the default root element.
abstract Element | AbstractDocument.getDefaultRootElement() Returns the root element that views should be based upon unless some other mechanism for assigning views to element structures is provided.
Element | Document.getDefaultRootElement() Returns the root element that views should be based upon, unless some other mechanism for assigning views to element structures is provided.
Element | AbstractDocument.ElementEdit.getElement() Returns the underlying element.
Element | View.getElement() Fetches the structural portion of the subject that this view is mapped to.
abstract Element | AbstractDocument.AbstractElement.getElement(int index) Gets a child element.
Element | AbstractDocument.BranchElement.getElement(int index) Gets a child element.
Element | AbstractDocument.LeafElement.getElement(int index) Gets a child element.
Element | Element.getElement(int index) Fetches the child element at the given index.
Element | PlainDocument.getParagraphElement(int pos) Get the paragraph element containing the given position.
Element | DefaultStyledDocument.getParagraphElement(int pos) Gets the paragraph element at the offset pos.
abstract Element | AbstractDocument.getParagraphElement(int pos) Get the paragraph element containing the given position.
Element | StyledDocument.getParagraphElement(int pos) Gets the element that represents the paragraph that encloses the given offset within the document.
static Element | Utilities.getParagraphElement(JTextComponent c, int offs) Determines the element to use for a paragraph/line.
Element | AbstractDocument.AbstractElement.getParentElement() Gets the parent of the element.
Element | Element.getParentElement() Fetches the parent element.
Element | DefaultStyledDocument.ElementBuffer.getRootElement() Gets the root element.
Element[] | AbstractDocument.getRootElements() Gets all root elements defined.
Element[] | Document.getRootElements() Returns all of the root elements that are defined.
Element | ElementIterator.next() Fetches the next Element.
Element | AbstractDocument.BranchElement.positionToElement(int pos) Gets the child element that contains the given model position.
Element | ElementIterator.previous() Fetches the previous Element.

Methods in javax.swing.text with parameters of type Element
Element | DefaultStyledDocument.ElementBuffer.clone(Element parent, Element clonee) Creates a copy of this element, with a different parent.
View | ViewFactory.create(Element elem) Creates a view from the given structural element of a document.
protected Element | AbstractDocument.createBranchElement(Element parent, AttributeSet a) Creates a document branch element, that can contain other elements.
protected void | StyledEditorKit.createInputAttributes(Element element, MutableAttributeSet set) Copies the key/values in elements AttributeSet into set.
protected Element | AbstractDocument.createLeafElement(Element parent, AttributeSet a, int p0, int p1) Creates a document leaf element.
protected TableView.TableCell | TableView.createTableCell(Element elem) Deprecated. Table cells can now be any arbitrary View implementation and should be produced by the ViewFactory rather than the table.
protected TableView.TableRow | TableView.createTableRow(Element elem) Creates a new table row.
DocumentEvent.ElementChange | AbstractDocument.DefaultDocumentEvent.getChange(Element elem) Gets the changes for an element.
protected String | AbstractWriter.getText(Element elem) Returns the text associated with the element.
protected boolean | AbstractWriter.inRange(Element next) This method determines whether the current element is in the range specified.
void | AbstractDocument.BranchElement.replace(int offset, int length, Element[] elems) Replaces content with a new set of elements.
protected void | AbstractWriter.text(Element elem) Writes out text.

Constructors in javax.swing.text with parameters of type Element
AbstractDocument.AbstractElement(Element parent, AttributeSet a)
Creates a new AbstractElement.
AbstractDocument.BranchElement(Element parent, AttributeSet a)
Constructs a composite element that initially contains no children.
AbstractDocument.ElementEdit(Element e, int index, Element[] removed, Element[] added)
Constructs an edit record.
AbstractDocument.ElementEdit(Element e, int index, Element[] removed, Element[] added)
Constructs an edit record.
AbstractDocument.ElementEdit(Element e, int index, Element[] removed, Element[] added)
Constructs an edit record.
AbstractDocument.LeafElement(Element parent, AttributeSet a, int offs0, int offs1)
Constructs an element that represents content within the document (has no children).
AbstractWriter(Writer w, Element root)
Creates a new AbstractWriter.
AbstractWriter(Writer w, Element root, int pos, int len)
Creates a new AbstractWriter.
AsyncBoxView(Element elem, int axis)
Construct a box view that does asynchronous layout.
BoxView(Element elem, int axis)
Constructs a BoxView.
ComponentView(Element elem)
Creates a new ComponentView object.
CompositeView(Element elem)
Constructs a CompositeView for the given element.
DefaultStyledDocument.AttributeUndoableEdit(Element element, AttributeSet newAttributes, boolean isReplacing)
DefaultStyledDocument.ElementBuffer(Element root)
Creates a new ElementBuffer.
ElementIterator(Element root)
Creates a new ElementIterator.
FieldView(Element elem)
Constructs a new FieldView wrapped on an element.
FlowView(Element elem, int axis)
Constructs a FlowView for the given element.
GlyphView(Element elem)
Constructs a new view wrapped on an element.
IconView(Element elem)
Creates a new icon view that represents an element.
LabelView(Element elem)
Constructs a new view wrapped on an element.
ParagraphView(Element elem)
Constructs a ParagraphView for the given element.
PasswordView(Element elem)
Constructs a new view wrapped on an element.
PlainView(Element elem)
Constructs a new PlainView wrapped on an element.
TableView.TableCell(Element elem)
Deprecated. Constructs a TableCell for the given element.
TableView.TableRow(Element elem)
Constructs a TableView for the given element.
TableView(Element elem)
Constructs a TableView for the given element.
View(Element elem)
Creates a new View object.
WrappedPlainView(Element elem)
Creates a new WrappedPlainView.
WrappedPlainView(Element elem, boolean wordWrap)
Creates a new WrappedPlainView.
ZoneView(Element elem, int axis)
Constructs a ZoneView.

Uses of Element in javax.swing.text.html

Classes in javax.swing.text.html that implement Element
class | HTMLDocument.BlockElement An element that represents a structural block of HTML.
class | HTMLDocument.RunElement An element that represents a chunk of text that has a set of HTML character level attributes assigned to it.

Methods in javax.swing.text.html that return Element
protected Element | HTMLDocument.createBranchElement(Element parent, AttributeSet a) Creates a document branch element, that can contain other elements.
protected Element | HTMLDocument.createLeafElement(Element parent, AttributeSet a, int p0, int p1) Creates a document leaf element that directly represents text (doesn't have any children).
protected Element | HTMLEditorKit.HTMLTextAction.findElementMatchingTag(HTMLDocument doc, int offset, HTML.Tag tag) Returns the deepest element at offset matching tag.
Element | HTMLDocument.getElement(Element e, Object attribute, Object value) Returns the child element of e that contains the attribute, attribute with value value, or null if one isn't found.
Element | HTMLDocument.getElement(String id) Returns the element that has the given id Attribute.
protected Element[] | HTMLEditorKit.HTMLTextAction.getElementsAt(HTMLDocument doc, int offset) Returns an array of the Elements that contain offset.

Methods in javax.swing.text.html with parameters of type Element
protected void | HTMLWriter.comment(Element elem) Writes out comments.
View | HTMLEditorKit.HTMLFactory.create(Element elem) Creates a view from an element.
protected Element | HTMLDocument.createBranchElement(Element parent, AttributeSet a) Creates a document branch element, that can contain other elements.
protected void | HTMLEditorKit.createInputAttributes(Element element, MutableAttributeSet set) Copies the key/values in elements AttributeSet into set.
protected Element | HTMLDocument.createLeafElement(Element parent, AttributeSet a, int p0, int p1) Creates a document leaf element that directly represents text (doesn't have any children).
protected void | HTMLWriter.emptyTag(Element elem) Writes out all empty elements (all tags that have no corresponding end tag).
protected void | HTMLWriter.endTag(Element elem) Writes out an end tag for the element.
Element | HTMLDocument.getElement(Element e, Object attribute, Object value) Returns the child element of e that contains the attribute, attribute with value value, or null if one isn't found.
Style | StyleSheet.getRule(HTML.Tag t, Element e) Fetches the style to use to render the given type of HTML tag.
void | HTMLDocument.insertAfterEnd(Element elem, String htmlText) Inserts the HTML specified as a string after the the end of the given element.
void | HTMLDocument.insertAfterStart(Element elem, String htmlText) Inserts the HTML specified as a string at the start of the element.
protected void | HTMLEditorKit.InsertHTMLTextAction.insertAtBoundary(JEditorPane editor, HTMLDocument doc, int offset, Element insertElement, String html, HTML.Tag parentTag, HTML.Tag addTag) This is invoked when inserting at a boundary.
protected void | HTMLEditorKit.InsertHTMLTextAction.insertAtBoundry(JEditorPane editor, HTMLDocument doc, int offset, Element insertElement, String html, HTML.Tag parentTag, HTML.Tag addTag) Deprecated. As of Java 2 platform v1.3, use insertAtBoundary
void | HTMLDocument.insertBeforeEnd(Element elem, String htmlText) Inserts the HTML specified as a string at the end of the element.
void | HTMLDocument.insertBeforeStart(Element elem, String htmlText) Inserts the HTML specified as a string before the start of the given element.
protected boolean | MinimalHTMLWriter.isText(Element elem) Returns true if the element is a text element.
void | HTMLDocument.setInnerHTML(Element elem, String htmlText) Replaces the children of the given element with the contents specified as an HTML string.
void | HTMLDocument.setOuterHTML(Element elem, String htmlText) Replaces the given element in the parent with the contents specified as an HTML string.
protected void | HTMLWriter.startTag(Element elem) Writes out a start tag for the element.
protected boolean | HTMLWriter.synthesizedElement(Element elem) Returns true if the element is a synthesized element.
protected void | HTMLWriter.text(Element elem) Writes out text.
protected void | MinimalHTMLWriter.text(Element elem) Writes out text.
protected void | MinimalHTMLWriter.writeComponent(Element elem) Responsible for handling Component Elements; deliberately unimplemented.
protected void | MinimalHTMLWriter.writeContent(Element elem, boolean needsIndenting) Writes out the attribute set in an HTML-compliant manner.
protected void | MinimalHTMLWriter.writeImage(Element elem) Responsible for handling Icon Elements; deliberately unimplemented.
protected void | MinimalHTMLWriter.writeLeaf(Element elem) Responsible for writing out other non-text leaf elements.
protected void | MinimalHTMLWriter.writeStartParagraph(Element elem) Emits the start tag for a paragraph.

Constructors in javax.swing.text.html with parameters of type Element
BlockView(Element elem, int axis)
Creates a new view that represents an html box.
FormView(Element elem)
Creates a new FormView object.
HTMLDocument.BlockElement(Element parent, AttributeSet a)
Constructs a composite element that initially contains no children.
HTMLDocument.RunElement(Element parent, AttributeSet a, int offs0, int offs1)
Constructs an element that represents content within the document (has no children).
HTMLFrameHyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL targetURL, Element sourceElement, String targetFrame)
Creates a new object representing a hypertext link event.
HTMLFrameHyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL targetURL, String desc, Element sourceElement, String targetFrame)
Creates a new object representing a hypertext link event.
ImageView(Element elem)
Creates a new view that represents an IMG element.
InlineView(Element elem)
Constructs a new view wrapped on an element.
ListView(Element elem)
Creates a new view that represents a list element.
ObjectView(Element elem)
Creates a new ObjectView object.
ParagraphView(Element elem)
Constructs a ParagraphView for the given element.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.Highlighter

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.Highlighter

Packages that use Highlighter
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of Highlighter in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement Highlighter
static class BasicTextUI.BasicHighlighter

Methods in javax.swing.plaf.basic that return Highlighter
protected  Highlighter BasicTextUI.createHighlighter()
Creates the object to use for adding highlights.

Uses of Highlighter in javax.swing.text

Classes in javax.swing.text that implement Highlighter
class | DefaultHighlighter Implements the Highlighter interfaces.
class | LayeredHighlighter

Methods in javax.swing.text that return Highlighter
 Highlighter JTextComponent.getHighlighter()
Fetches the object responsible for making highlights.

Methods in javax.swing.text with parameters of type Highlighter
 void JTextComponent.setHighlighter(Highlighter h)
Sets the highlighter to be used.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.Highlighter.Highlight

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.Highlighter.Highlight

Packages that use Highlighter.Highlight
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of Highlighter.Highlight in javax.swing.text

Methods in javax.swing.text that return Highlighter.Highlight
Highlighter.Highlight[] | DefaultHighlighter.getHighlights() Makes a copy of the highlights.
Highlighter.Highlight[] | Highlighter.getHighlights() Fetches the current list of highlights.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.Highlighter.HighlightPainter

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.Highlighter.HighlightPainter

Packages that use Highlighter.HighlightPainter
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of Highlighter.HighlightPainter in javax.swing.text

Classes in javax.swing.text that implement Highlighter.HighlightPainter
static class | DefaultHighlighter.DefaultHighlightPainter Simple highlight painter that fills a highlighted area with a solid color.
static class | LayeredHighlighter.LayerPainter Layered highlight renderer.

Methods in javax.swing.text that return Highlighter.HighlightPainter
Highlighter.HighlightPainter | Highlighter.Highlight.getPainter() Gets the painter for the highlighter.
protected Highlighter.HighlightPainter | DefaultCaret.getSelectionPainter() Gets the painter for the Highlighter.

Methods in javax.swing.text with parameters of type Highlighter.HighlightPainter
Object | DefaultHighlighter.addHighlight(int p0, int p1, Highlighter.HighlightPainter p) Adds a highlight to the view.
Object | Highlighter.addHighlight(int p0, int p1, Highlighter.HighlightPainter p) Adds a highlight to the view.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.Keymap

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.Keymap

Packages that use Keymap
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.

Uses of Keymap in javax.swing.plaf.basic

Methods in javax.swing.plaf.basic that return Keymap
protected  Keymap BasicTextUI.createKeymap()
Creates the keymap to use for the text component, and installs any necessary bindings into it.

Uses of Keymap in javax.swing.text

Methods in javax.swing.text that return Keymap
static Keymap | JTextComponent.addKeymap(String nm, Keymap parent) Adds a new keymap into the keymap hierarchy.
Keymap | JTextComponent.getKeymap() Fetches the keymap currently active in this text component.
static Keymap | JTextComponent.getKeymap(String nm) Fetches a named keymap previously added to the document.
Keymap | Keymap.getResolveParent() Fetches the parent keymap used to resolve key-bindings.
static Keymap | JTextComponent.removeKeymap(String nm) Removes a named keymap previously added to the document.

Methods in javax.swing.text with parameters of type Keymap
static Keymap | JTextComponent.addKeymap(String nm, Keymap parent) Adds a new keymap into the keymap hierarchy.
static void | JTextComponent.loadKeymap(Keymap map, JTextComponent.KeyBinding[] bindings, Action[] actions) Loads a keymap with a bunch of bindings.
void | JTextComponent.setKeymap(Keymap map) Sets the keymap to use for binding events to actions.
void | Keymap.setResolveParent(Keymap parent) Sets the parent keymap, which will be used to resolve key-bindings.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.MutableAttributeSet

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.MutableAttributeSet

Packages that use MutableAttributeSet
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of MutableAttributeSet in javax.swing

Methods in javax.swing that return MutableAttributeSet
 MutableAttributeSet JTextPane.getInputAttributes()
Gets the input attributes for the pane.

Uses of MutableAttributeSet in javax.swing.text

Subinterfaces of MutableAttributeSet in javax.swing.text
 interface Style
A collection of attributes to associate with an element in a document.

Classes in javax.swing.text that implement MutableAttributeSet
class | AbstractDocument.AbstractElement Implements the abstract part of an element.
class | AbstractDocument.BranchElement Implements a composite element that contains other elements.
class | AbstractDocument.LeafElement Implements an element that directly represents content of some kind.
protected class | DefaultStyledDocument.SectionElement Default root element for a document...
class | SimpleAttributeSet A straightforward implementation of MutableAttributeSet using a hash table.
class | StyleContext.NamedStyle A collection of attributes, typically used to represent character and paragraph styles.

Methods in javax.swing.text that return MutableAttributeSet
protected MutableAttributeSet | StyleContext.createLargeAttributeSet(AttributeSet a) Create a large set of attributes that should trade off space for time.
MutableAttributeSet | StyledEditorKit.getInputAttributes() Gets the input attributes for the pane.

Methods in javax.swing.text with parameters of type MutableAttributeSet
protected void | StyledEditorKit.createInputAttributes(Element element, MutableAttributeSet set) Copies the key/values in elements AttributeSet into set.
void | StyleContext.readAttributes(ObjectInputStream in, MutableAttributeSet a) Context-specific handling of reading in attributes
static void | StyleContext.readAttributeSet(ObjectInputStream in, MutableAttributeSet a) Reads a set of attributes from the given object input stream that have been previously written out with writeAttributeSet.
static void | StyleConstants.setAlignment(MutableAttributeSet a, int align) Sets alignment.
static void | StyleConstants.setBackground(MutableAttributeSet a, Color fg) Sets the background color.
static void | StyleConstants.setBidiLevel(MutableAttributeSet a, int o) Sets the BidiLevel.
static void | StyleConstants.setBold(MutableAttributeSet a, boolean b) Sets the bold attribute.
static void | StyleConstants.setComponent(MutableAttributeSet a, Component c) Sets the component attribute.
static void | StyleConstants.setFirstLineIndent(MutableAttributeSet a, float i) Sets the first line indent.
static void | StyleConstants.setFontFamily(MutableAttributeSet a, String fam) Sets the font attribute.
static void | StyleConstants.setFontSize(MutableAttributeSet a, int s) Sets the font size attribute.
static void | StyleConstants.setForeground(MutableAttributeSet a, Color fg) Sets the foreground color.
static void | StyleConstants.setIcon(MutableAttributeSet a, Icon c) Sets the icon attribute.
static void | StyleConstants.setItalic(MutableAttributeSet a, boolean b) Sets the italic attribute.
static void | StyleConstants.setLeftIndent(MutableAttributeSet a, float i) Sets left indent.
static void | StyleConstants.setLineSpacing(MutableAttributeSet a, float i) Sets line spacing.
static void | StyleConstants.setRightIndent(MutableAttributeSet a, float i) Sets right indent.
static void | StyleConstants.setSpaceAbove(MutableAttributeSet a, float i) Sets space above.
static void | StyleConstants.setSpaceBelow(MutableAttributeSet a, float i) Sets space below.
static void | StyleConstants.setStrikeThrough(MutableAttributeSet a, boolean b) Sets the strikethrough attribute.
static void | StyleConstants.setSubscript(MutableAttributeSet a, boolean b) Sets the subscript attribute.
static void | StyleConstants.setSuperscript(MutableAttributeSet a, boolean b) Sets the superscript attribute.
static void | StyleConstants.setTabSet(MutableAttributeSet a, TabSet tabs) Sets the TabSet.
static void | StyleConstants.setUnderline(MutableAttributeSet a, boolean b) Sets the underline attribute.

Uses of MutableAttributeSet in javax.swing.text.html

Classes in javax.swing.text.html that implement MutableAttributeSet
class | HTMLDocument.BlockElement An element that represents a structural block of HTML.
class | HTMLDocument.RunElement An element that represents a chunk of text that has a set of HTML character level attributes assigned to it.

Fields in javax.swing.text.html declared as MutableAttributeSet
protected  MutableAttributeSet HTMLDocument.HTMLReader.charAttr

Methods in javax.swing.text.html that return MutableAttributeSet
protected MutableAttributeSet | StyleSheet.createLargeAttributeSet(AttributeSet a) Creates a large set of attributes that should trade off space for time.
MutableAttributeSet | HTMLEditorKit.getInputAttributes() Gets the input attributes used for the styled editing actions.

Methods in javax.swing.text.html with parameters of type MutableAttributeSet
void | StyleSheet.addCSSAttribute(MutableAttributeSet attr, CSS.Attribute key, String value) Adds a CSS attribute to the given set.
boolean | StyleSheet.addCSSAttributeFromHTML(MutableAttributeSet attr, CSS.Attribute key, String value) Adds a CSS attribute to the given set.
protected void | HTMLDocument.HTMLReader.addSpecialElement(HTML.Tag t, MutableAttributeSet a) Adds content that is basically specified entirely in the attribute set.
protected void | HTMLDocument.HTMLReader.blockOpen(HTML.Tag t, MutableAttributeSet attr) Adds an instruction to the parse buffer to create a block element with the given attributes.
protected void | HTMLEditorKit.createInputAttributes(Element element, MutableAttributeSet set) Copies the key/values in elements AttributeSet into set.
void | HTMLEditorKit.ParserCallback.handleSimpleTag(HTML.Tag t, MutableAttributeSet a, int pos)
void | HTMLDocument.HTMLReader.handleSimpleTag(HTML.Tag t, MutableAttributeSet a, int pos) Callback from the parser.
void | HTMLEditorKit.ParserCallback.handleStartTag(HTML.Tag t, MutableAttributeSet a, int pos)
void | HTMLDocument.HTMLReader.handleStartTag(HTML.Tag t, MutableAttributeSet a, int pos) Callback from the parser.
void | HTMLDocument.HTMLReader.TagAction.start(HTML.Tag t, MutableAttributeSet a) Called when a start tag is seen for the type of tag this action was registered to.
void | HTMLDocument.HTMLReader.BlockAction.start(HTML.Tag t, MutableAttributeSet attr)
void | HTMLDocument.HTMLReader.ParagraphAction.start(HTML.Tag t, MutableAttributeSet a)
void | HTMLDocument.HTMLReader.SpecialAction.start(HTML.Tag t, MutableAttributeSet a)
void | HTMLDocument.HTMLReader.IsindexAction.start(HTML.Tag t, MutableAttributeSet a)
void | HTMLDocument.HTMLReader.HiddenAction.start(HTML.Tag t, MutableAttributeSet a)
void | HTMLDocument.HTMLReader.PreAction.start(HTML.Tag t, MutableAttributeSet attr)
void | HTMLDocument.HTMLReader.CharacterAction.start(HTML.Tag t, MutableAttributeSet attr)
void | HTMLDocument.HTMLReader.FormAction.start(HTML.Tag t, MutableAttributeSet attr)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.Position

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.Position

Packages that use Position
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of Position in javax.swing.text

Methods in javax.swing.text that return Position
Position | StringContent.createPosition(int offset) Creates a position within the content that will track change as the content is mutated.
Position | GapContent.createPosition(int offset) Creates a position within the content that will track change as the content is mutated.
Position | AbstractDocument.createPosition(int offs) Returns a position that will track change as the document is altered.
Position | AbstractDocument.Content.createPosition(int offset) Creates a position within the content that will track change as the content is mutated.
Position | Document.createPosition(int offs) This method allows an application to mark a place in a sequence of character content.
Position | AbstractDocument.getEndPosition() Returns a position that represents the end of the document.
Position | Document.getEndPosition() Returns a position that represents the end of the document.
Position | AbstractDocument.getStartPosition() Returns a position that represents the start of the document.
Position | Document.getStartPosition() Returns a position that represents the start of the document.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.Style

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.Style

Packages that use Style
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of Style in javax.swing

Methods in javax.swing that return Style
Style | JTextPane.addStyle(String nm, Style parent) Adds a new style into the logical style hierarchy.
Style | JTextPane.getLogicalStyle() Fetches the logical style assigned to the paragraph represented by the current position of the caret, or null.
Style | JTextPane.getStyle(String nm) Fetches a named non-null style previously added.

Methods in javax.swing with parameters of type Style
Style | JTextPane.addStyle(String nm, Style parent) Adds a new style into the logical style hierarchy.
void | JTextPane.setLogicalStyle(Style s) Sets the logical style to use for the paragraph at the current caret position.

Uses of Style in javax.swing.text

Classes in javax.swing.text that implement Style
 class StyleContext.NamedStyle
A collection of attributes, typically used to represent character and paragraph styles.

Methods in javax.swing.text that return Style
Style | DefaultStyledDocument.addStyle(String nm, Style parent) Adds a new style into the logical style hierarchy.
Style | StyleContext.addStyle(String nm, Style parent) Adds a new style into the style hierarchy.
Style | StyledDocument.addStyle(String nm, Style parent) Adds a new style into the logical style hierarchy.
Style | DefaultStyledDocument.getLogicalStyle(int p) Fetches the logical style assigned to the paragraph represented by the given position.
Style | StyledDocument.getLogicalStyle(int p) Gets a logical style for a given position in a paragraph.
Style | DefaultStyledDocument.getStyle(String nm) Fetches a named style previously added.
Style | StyleContext.getStyle(String nm) Fetches a named style previously added to the document
Style | StyledDocument.getStyle(String nm) Fetches a named style previously added.

Methods in javax.swing.text with parameters of type Style
Style | DefaultStyledDocument.addStyle(String nm, Style parent) Adds a new style into the logical style hierarchy.
Style | StyleContext.addStyle(String nm, Style parent) Adds a new style into the style hierarchy.
Style | StyledDocument.addStyle(String nm, Style parent) Adds a new style into the logical style hierarchy.
void | DefaultStyledDocument.setLogicalStyle(int pos, Style s) Sets the logical style to use for the paragraph at the given position.
void | StyledDocument.setLogicalStyle(int pos, Style s) Sets the logical style to use for the paragraph at the given position.
protected void | DefaultStyledDocument.styleChanged(Style style) Called when any of this document's styles have changed.

Constructors in javax.swing.text with parameters of type Style
StyleContext.NamedStyle(String name, Style parent)
Creates a new named style.
StyleContext.NamedStyle(Style parent)
Creates a new named style.

Uses of Style in javax.swing.text.html

Methods in javax.swing.text.html that return Style
Style | StyleSheet.getRule(HTML.Tag t, Element e) Fetches the style to use to render the given type of HTML tag.
Style | StyleSheet.getRule(String selector) Fetches the rule that best matches the selector given in string form.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.StyledDocument

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.StyledDocument

Packages that use StyledDocument
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of StyledDocument in javax.swing

Methods in javax.swing that return StyledDocument
 StyledDocument JTextPane.getStyledDocument()
Fetches the model associated with the editor.

Methods in javax.swing with parameters of type StyledDocument
 void JTextPane.setStyledDocument(StyledDocument doc)
Associates the editor with a text document.

Constructors in javax.swing with parameters of type StyledDocument
JTextPane(StyledDocument doc)
Creates a new JTextPane, with a specified document model.

Uses of StyledDocument in javax.swing.text

Classes in javax.swing.text that implement StyledDocument
 class DefaultStyledDocument
A document that can be marked up with character and paragraph styles in a manner similar to the Rich Text Format.

Methods in javax.swing.text that return StyledDocument
protected  StyledDocument StyledEditorKit.StyledTextAction.getStyledDocument(JEditorPane e)
Gets the document associated with an editor pane.

Uses of StyledDocument in javax.swing.text.html

Classes in javax.swing.text.html that implement StyledDocument
 class HTMLDocument
A document that models HTML.

Constructors in javax.swing.text.html with parameters of type StyledDocument
MinimalHTMLWriter(Writer w, StyledDocument doc)
Creates a new MinimalHTMLWriter.
MinimalHTMLWriter(Writer w, StyledDocument doc, int pos, int len)
Creates a new MinimalHTMLWriter.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.TabableView

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.TabableView

Packages that use TabableView
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of TabableView in javax.swing.text

Classes in javax.swing.text that implement TabableView
class | GlyphView A GlyphView is a styled chunk of text that represents a view mapped over an element in the text model.
class | LabelView A LabelView is a styled chunk of text that represents a view mapped over an element in the text model.

Uses of TabableView in javax.swing.text.html

Classes in javax.swing.text.html that implement TabableView
 class InlineView
Displays the inline element styles based upon css attributes.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.TabExpander

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.TabExpander

Packages that use TabExpander
javax.swing.text Provides classes and interfaces that deal with editable and noneditable text components.

Uses of TabExpander in javax.swing.text

Classes in javax.swing.text that implement TabExpander
class | FieldView Extends the multi-line plain text view to be suitable for a single-line editor view.
class | ParagraphView View of a simple line-wrapping paragraph that supports multiple fonts, colors, components, icons, etc.
class | PasswordView Implements a View suitable for use in JPasswordField UI implementations.
class | PlainView Implements View interface for a simple multi-line text view that has text in one font and color.
class | WrappedPlainView View of plain text (text with only one font and color) that does line-wrapping.

Methods in javax.swing.text that return TabExpander
 TabExpander GlyphView.getTabExpander()
Fetch the TabExpander to use if tabs are present in this view.

Methods in javax.swing.text with parameters of type TabExpander
static int | Utilities.drawTabbedText(Segment s, int x, int y, Graphics g, TabExpander e, int startOffset) Draws the given text, expanding any tabs that are contained using the given tab expansion technique.
static int | Utilities.getBreakLocation(Segment s, FontMetrics metrics, int x0, int x, TabExpander e, int startOffset) Determine where to break the given text to fit within the given span.
abstract float | GlyphView.GlyphPainter.getSpan(GlyphView v, int p0, int p1, TabExpander e, float x) Determine the span the glyphs given a start location (for tab expansion).
float | TabableView.getTabbedSpan(float x, TabExpander e) Determines the desired span when using the given tab expansion implementation.
float | GlyphView.getTabbedSpan(float x, TabExpander e) Determines the desired span when using the given tab expansion implementation.
static int | Utilities.getTabbedTextOffset(Segment s, FontMetrics metrics, int x0, int x, TabExpander e, int startOffset) Determines the relative offset into the given text that best represents the given span in the view coordinate system.
static int | Utilities.getTabbedTextOffset(Segment s, FontMetrics metrics, int x0, int x, TabExpander e, int startOffset, boolean round)
static int | Utilities.getTabbedTextWidth(Segment s, FontMetrics metrics, int x, TabExpander e, int startOffset) Determines the width of the given segment of text taking tabs into consideration.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.ViewFactory

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.ViewFactory

Packages that use ViewFactory
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of ViewFactory in javax.swing.plaf.basic

Classes in javax.swing.plaf.basic that implement ViewFactory
class | BasicEditorPaneUI Provides the look and feel for a JEditorPane.
class | BasicFormattedTextFieldUI Provides the look and feel implementation for JFormattedTextField.
class | BasicPasswordFieldUI Provides the Windows look and feel for a password field.
class | BasicTextAreaUI Provides the look and feel for a plain text editor.
class | BasicTextFieldUI Basis of a look and feel for a JTextField.
class | BasicTextPaneUI Provides the look and feel for a styled text editor.
class | BasicTextUI Basis of a text components look-and-feel.

Uses of ViewFactory in javax.swing.plaf.metal

Classes in javax.swing.plaf.metal that implement ViewFactory
 class MetalTextFieldUI
Basis of a look and feel for a JTextField.

Uses of ViewFactory in javax.swing.text

Classes in javax.swing.text that implement ViewFactory
 class DefaultTextUI
Deprecated.

Methods in javax.swing.text that return ViewFactory
ViewFactory | StyledEditorKit.getViewFactory() Fetches a factory that is suitable for producing views of any models that are produced by this kit.
ViewFactory | DefaultEditorKit.getViewFactory() Fetches a factory that is suitable for producing views of any models that are produced by this kit.
ViewFactory | View.getViewFactory() Fetches the ViewFactory implementation that is feeding the view hierarchy.
abstract ViewFactory | EditorKit.getViewFactory() Fetches a factory that is suitable for producing views of any models that are produced by this kit.

Methods in javax.swing.text with parameters of type ViewFactory
void | WrappedPlainView.changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
void | PlainView.changedUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
void | FlowView.changedUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
void | ParagraphView.changedUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
void | LabelView.changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
void | GlyphView.changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
void | View.changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
protected void | TableView.forwardUpdate(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a, ViewFactory f)
protected void | BoxView.forwardUpdate(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a, ViewFactory f) Forwards the given DocumentEvent to the child views that need to be notified of the change to the model.
protected void | View.forwardUpdate(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a, ViewFactory f) Forwards the given DocumentEvent to the child views that need to be notified of the change to the model.
protected void | View.forwardUpdateToView(View v, DocumentEvent e, Shape a, ViewFactory f) Forwards the DocumentEvent to the give child view.
void | FieldView.insertUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
void | ZoneView.insertUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
void | WrappedPlainView.insertUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
void | PlainView.insertUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
void | FlowView.insertUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
void | GlyphView.insertUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
void | View.insertUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
protected void | ZoneView.loadChildren(ViewFactory f) Loads all of the children to initialize the view.
protected void | AsyncBoxView.loadChildren(ViewFactory f) Loads all of the children to initialize the view.
protected void | WrappedPlainView.loadChildren(ViewFactory f) Loads all of the children to initialize the view.
protected void | FlowView.loadChildren(ViewFactory f) Loads all of the children to initialize the view.
protected void | CompositeView.loadChildren(ViewFactory f) Loads all of the children to initialize the view.
void | FieldView.removeUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | ZoneView.removeUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | WrappedPlainView.removeUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | PlainView.removeUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | FlowView.removeUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | GlyphView.removeUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | View.removeUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
protected boolean | ZoneView.updateChildren(DocumentEvent.ElementChange ec, DocumentEvent e, ViewFactory f) The superclass behavior will try to update the child views which is not desired in this case, since the children are zones and not directly effected by the changes to the associated element.
protected boolean | View.updateChildren(DocumentEvent.ElementChange ec, DocumentEvent e, ViewFactory f) Updates the child views in response to receiving notification that the model changed, and there is change record for the element this view is responsible for.
protected void | PlainView.updateDamage(DocumentEvent changes, Shape a, ViewFactory f) Repaint the region of change covered by the given document event.

Uses of ViewFactory in javax.swing.text.html

Classes in javax.swing.text.html that implement ViewFactory
static class HTMLEditorKit.HTMLFactory
A factory to build views for HTML.

Methods in javax.swing.text.html that return ViewFactory
 ViewFactory HTMLEditorKit.getViewFactory()
Fetch a factory that is suitable for producing views of any models that are produced by this kit.

Methods in javax.swing.text.html with parameters of type ViewFactory
void | BlockView.changedUpdate(DocumentEvent changes, Shape a, ViewFactory f)
void | ImageView.changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Invoked when the Elements attributes have changed.
void | InlineView.changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
void | InlineView.insertUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
void | InlineView.removeUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ComponentView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class ComponentView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.ComponentView
All Implemented Interfaces:
SwingConstants
Direct Known Subclasses:
FormView, ObjectView
public class ComponentView
extends View

Component decorator that implements the view interface. The entire element is used to represent the component. This acts as a gateway from the display-only View implementations to interactive lightweight components (ie it allows components to be embedded into the View hierarchy).

The component is placed relative to the text baseline according to the value returned by Component.getAlignmentY. For Swing components this value can be conveniently set using the method JComponent.setAlignmentY. For example, setting a value of 0.75 will cause 75 percent of the component to be above the baseline, and 25 percent of the component to be below the baseline.

This class is implemented to do the extra work necessary to work properly in the presence of multiple threads (i.e. from asynchronous notification of model changes for example) by ensuring that all component access is done on the event thread.

The component used is determined by the return value of the createComponent method. The default implementation of this method is to return the component held as an attribute of the element (by calling StyleConstants.getComponent). A limitation of this behavior is that the component cannot be used by more than one text component (i.e. with a shared model). Subclasses can remove this constraint by implementing the createComponent to actually create a component based upon some kind of specification contained in the attributes. The ObjectView class in the html package is an example of a ComponentView implementation that supports multiple component views of a shared model.

Field Summary
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
ComponentView(Element elem)
Creates a new ComponentView object.
Method Summary
protected Component | createComponent() Create the component that is associated with this view.
float | getAlignment(int axis) Determines the desired alignment for this view along an axis.
Component | getComponent() Fetch the component associated with the view.
float | getMaximumSpan(int axis) Determines the maximum span for this view along an axis.
float | getMinimumSpan(int axis) Determines the minimum span for this view along an axis.
float | getPreferredSpan(int axis) Determines the preferred span for this view along an axis.
Shape | modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the coordinate space of the model to that of the view.
void | paint(Graphics g, Shape a) The real paint behavior occurs naturally from the association that the component has with its parent container (the same container hosting this view).
void | setParent(View p) Sets the parent for a child view.
int | viewToModel(float x, float y, Shape a, Position.Bias[] bias) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
Methods inherited from class javax.swing.text.View
append, breakView, changedUpdate, createFragment, forwardUpdate, forwardUpdateToView, getAttributes, getBreakWeight, getChildAllocation, getContainer, getDocument, getElement, getEndOffset, getGraphics, getNextVisualPositionFrom, getParent, getResizeWeight, getStartOffset, getToolTipText, getView, getViewCount, getViewFactory, getViewIndex, getViewIndex, insert, insertUpdate, isVisible, modelToView, modelToView, preferenceChanged, remove, removeAll, removeUpdate, replace, setSize, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ComponentView

public ComponentView(Element elem)
Creates a new ComponentView object.

Parameters:
elem - the element to decorate
Method Detail

createComponent

protected Component createComponent()
Create the component that is associated with this view. This will be called when it has been determined that a new component is needed. This would result from a call to setParent or as a result of being notified that attributes have changed.

getComponent

public final Component getComponent()
Fetch the component associated with the view.

paint

public void paint(Graphics g,
                  Shape a)
The real paint behavior occurs naturally from the association that the component has with its parent container (the same container hosting this view). This is implemented to do nothing.

Specified by:
paint in class View
Parameters:
g - the graphics context
a - the shape
See Also:
View.paint(java.awt.Graphics, java.awt.Shape)

getPreferredSpan

public float getPreferredSpan(int axis)
Determines the preferred span for this view along an axis. This is implemented to return the value returned by Component.getPreferredSize along the axis of interest.

Specified by:
getPreferredSpan in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned, although there is no guarantee. The parent may choose to resize or break the view.
Throws:
IllegalArgumentException - for an invalid axis
See Also:
View.getPreferredSpan(int)

getMinimumSpan

public float getMinimumSpan(int axis)
Determines the minimum span for this view along an axis. This is implemented to return the value returned by Component.getMinimumSize along the axis of interest.

Overrides:
getMinimumSpan in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned, although there is no guarantee. The parent may choose to resize or break the view.
Throws:
IllegalArgumentException - for an invalid axis
See Also:
View.getPreferredSpan(int)

getMaximumSpan

public float getMaximumSpan(int axis)
Determines the maximum span for this view along an axis. This is implemented to return the value returned by Component.getMaximumSize along the axis of interest.

Overrides:
getMaximumSpan in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned, although there is no guarantee. The parent may choose to resize or break the view.
Throws:
IllegalArgumentException - for an invalid axis
See Also:
View.getPreferredSpan(int)

getAlignment

public float getAlignment(int axis)
Determines the desired alignment for this view along an axis. This is implemented to give the alignment of the embedded component.

Overrides:
getAlignment in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the desired alignment. This should be a value between 0.0 and 1.0 where 0 indicates alignment at the origin and 1.0 indicates alignment to the full span away from the origin. An alignment of 0.5 would be the center of the view.

setParent

public void setParent(View p)
Sets the parent for a child view. The parent calls this on the child to tell it who its parent is, giving the view access to things like the hosting Container. The superclass behavior is executed, followed by a call to createComponent if the parent view parameter is non-null and a component has not yet been created. The embedded components parent is then set to the value returned by getContainer. If the parent view parameter is null, this view is being cleaned up, thus the component is removed from its parent.

The changing of the component hierarchy will touch the component lock, which is the one thing that is not safe from the View hierarchy. Therefore, this functionality is executed immediately if on the event thread, or is queued on the event queue if called from another thread (notification of change from an asynchronous update).

Overrides:
setParent in class View
Parameters:
p - the parent

modelToView

public Shape modelToView(int pos,
                         Shape a,
                         Position.Bias b)
                  throws BadLocationException
Provides a mapping from the coordinate space of the model to that of the view.

Specified by:
modelToView in class View
Parameters:
pos - the position to convert >= 0
a - the allocated region to render into
b - the bias toward the previous character or the next character represented by the offset, in case the position is a boundary of two views; b will have one of these values:
  • Position.Bias.Forward
  • Position.Bias.Backward
Returns:
the bounding box of the given position is returned
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
See Also:
View.modelToView(int, java.awt.Shape, javax.swing.text.Position.Bias)

viewToModel

public int viewToModel(float x,
                       float y,
                       Shape a,
                       Position.Bias[] bias)
Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Specified by:
viewToModel in class View
Parameters:
x - the X coordinate >= 0
y - the Y coordinate >= 0
a - the allocated region to render into
Returns:
the location within the model that best represents the given point in the view
See Also:
View.viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CompositeView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class CompositeView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.CompositeView
All Implemented Interfaces:
SwingConstants
Direct Known Subclasses:
BoxView
public abstract class CompositeView
extends View

CompositeView is an abstract View implementation which manages one or more child views. (Note that CompositeView is intended for managing relatively small numbers of child views.) CompositeView is intended to be used as a starting point for View implementations, such as BoxView, that will contain child Views. Subclasses that wish to manage the collection of child Views should use the replace(int, int, javax.swing.text.View[]) method. As View invokes replace during DocumentListener notification, you normally won't need to directly invoke replace.

While CompositeView does not impose a layout policy on its child Views, it does allow for inseting the child Views it will contain. The insets can be set by either setInsets(short, short, short, short) or setParagraphInsets(javax.swing.text.AttributeSet).

In addition to the abstract methods of View, subclasses of CompositeView will need to override:

  • isBefore(int, int, java.awt.Rectangle) - Used to test if a given View location is before the visual space of the CompositeView.
  • isAfter(int, int, java.awt.Rectangle) - Used to test if a given View location is after the visual space of the CompositeView.
  • getViewAtPoint(int, int, java.awt.Rectangle) - Returns the view at a given visual location.
  • childAllocation(int, java.awt.Rectangle) - Returns the bounds of a particular child View. getChildAllocation will invoke childAllocation after offseting the bounds by the Insets of the CompositeView.

Field Summary
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
CompositeView(Element elem)
Constructs a CompositeView for the given element.
Method Summary
protected abstract void | childAllocation(int index, Rectangle a) Returns the allocation for a given child.
protected boolean | flipEastAndWestAtEnds(int position, Position.Bias bias) Determines in which direction the next view lays.
protected short | getBottomInset() Gets the bottom inset.
Shape | getChildAllocation(int index, Shape a) Fetches the allocation for the given child view to render into.
protected Rectangle | getInsideAllocation(Shape a) Translates the immutable allocation given to the view to a mutable allocation that represents the interior allocation (i.e.
protected short | getLeftInset() Gets the left inset.
protected int | getNextEastWestVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Returns the next visual position for the cursor, in either the east or west direction.
protected int | getNextNorthSouthVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Returns the next visual position for the cursor, in either the north or south direction.
int | getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
protected short | getRightInset() Gets the right inset.
protected short | getTopInset() Gets the top inset.
View | getView(int n) Returns the n-th view in this container.
protected abstract View | getViewAtPoint(int x, int y, Rectangle alloc) Fetches the child view at the given coordinates.
protected View | getViewAtPosition(int pos, Rectangle a) Fetches the child view that represents the given position in the model.
int | getViewCount() Returns the number of child views of this view.
int | getViewIndex(int pos, Position.Bias b) Returns the child view index representing the given position in the model.
protected int | getViewIndexAtPosition(int pos) Fetches the child view index representing the given position in the model.
protected abstract boolean | isAfter(int x, int y, Rectangle alloc) Tests whether a point lies after the rectangle range.
protected abstract boolean | isBefore(int x, int y, Rectangle alloc) Tests whether a point lies before the rectangle range.
protected void | loadChildren(ViewFactory f) Loads all of the children to initialize the view.
Shape | modelToView(int p0, Position.Bias b0, int p1, Position.Bias b1, Shape a) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
Shape | modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
void | replace(int offset, int length, View[] views) Replaces child views.
protected void | setInsets(short top, short left, short bottom, short right) Sets the insets for the view.
protected void | setParagraphInsets(AttributeSet attr) Sets the insets from the paragraph attributes specified in the given attributes.
void | setParent(View parent) Sets the parent of the view.
int | viewToModel(float x, float y, Shape a, Position.Bias[] bias) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
Methods inherited from class javax.swing.text.View
append, breakView, changedUpdate, createFragment, forwardUpdate, forwardUpdateToView, getAlignment, getAttributes, getBreakWeight, getContainer, getDocument, getElement, getEndOffset, getGraphics, getMaximumSpan, getMinimumSpan, getParent, getPreferredSpan, getResizeWeight, getStartOffset, getToolTipText, getViewFactory, getViewIndex, insert, insertUpdate, isVisible, modelToView, paint, preferenceChanged, remove, removeAll, removeUpdate, setSize, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CompositeView

public CompositeView(Element elem)
Constructs a CompositeView for the given element.

Parameters:
elem - the element this view is responsible for
Method Detail

loadChildren

protected void loadChildren(ViewFactory f)
Loads all of the children to initialize the view. This is called by the setParent(javax.swing.text.View) method. Subclasses can reimplement this to initialize their child views in a different manner. The default implementation creates a child view for each child element.

Parameters:
f - the view factory
See Also:
setParent(javax.swing.text.View)

setParent

public void setParent(View parent)
Sets the parent of the view. This is reimplemented to provide the superclass behavior as well as calling the loadChildren method if this view does not already have children. The children should not be loaded in the constructor because the act of setting the parent may cause them to try to search up the hierarchy (to get the hosting Container for example). If this view has children (the view is being moved from one place in the view hierarchy to another), the loadChildren method will not be called.

Overrides:
setParent in class View
Parameters:
parent - the parent of the view, null if none

getViewCount

public int getViewCount()
Returns the number of child views of this view.

Overrides:
getViewCount in class View
Returns:
the number of views >= 0
See Also:
getView(int)

getView

public View getView(int n)
Returns the n-th view in this container.

Overrides:
getView in class View
Parameters:
n - the number of the desired view, >= 0 && < getViewCount()
Returns:
the view at index n

replace

public void replace(int offset,
                    int length,
                    View[] views)
Replaces child views. If there are no views to remove this acts as an insert. If there are no views to add this acts as a remove. Views being removed will have the parent set to null, and the internal reference to them removed so that they may be garbage collected.

Overrides:
replace in class View
Parameters:
offset - the starting index into the child views to insert the new views; >= 0 and <= getViewCountlength - the number of existing child views to remove; this should be a value >= 0 and <= (getViewCount()="(getViewCount()" -="-" offset)views - the child views to add; this value can be null to indicate no children are being added (useful to remove)

getChildAllocation

public Shape getChildAllocation(int index,
                                Shape a)
Fetches the allocation for the given child view to render into. This enables finding out where various views are located.

Overrides:
getChildAllocation in class View
Parameters:
index - the index of the child, >= 0 && < getViewCount()
a - the allocation to this view
Returns:
the allocation to the child

modelToView

public Shape modelToView(int pos,
                         Shape a,
                         Position.Bias b)
                  throws BadLocationException
Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.

Specified by:
modelToView in class View
Parameters:
pos - the position to convert >= 0
a - the allocated region to render into
b - a bias value of either Position.Bias.Forward or Position.Bias.Backward
Returns:
the bounding box of the given position
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
See Also:
View.modelToView(int, java.awt.Shape, javax.swing.text.Position.Bias)

modelToView

public Shape modelToView(int p0,
                         Position.Bias b0,
                         int p1,
                         Position.Bias b1,
                         Shape a)
                  throws BadLocationException
Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.

Overrides:
modelToView in class View
Parameters:
p0 - the position to convert >= 0
b0 - the bias toward the previous character or the next character represented by p0, in case the position is a boundary of two views; either Position.Bias.Forward or Position.Bias.Backward
p1 - the position to convert >= 0
b1 - the bias toward the previous character or the next character represented by p1, in case the position is a boundary of two views
a - the allocated region to render into
Returns:
the bounding box of the given position is returned
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
IllegalArgumentException - for an invalid bias argument
See Also:
View.viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])

viewToModel

public int viewToModel(float x,
                       float y,
                       Shape a,
                       Position.Bias[] bias)
Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Specified by:
viewToModel in class View
Parameters:
x - x coordinate of the view location to convert >= 0
y - y coordinate of the view location to convert >= 0
a - the allocated region to render into
bias - either Position.Bias.Forward or Position.Bias.Backward
Returns:
the location within the model that best represents the given point in the view >= 0
See Also:
View.viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])

getNextVisualPositionFrom

public int getNextVisualPositionFrom(int pos,
                                     Position.Bias b,
                                     Shape a,
                                     int direction,
                                     Position.Bias[] biasRet)
                              throws BadLocationException
Provides a way to determine the next visually represented model location that one might place a caret. Some views may not be visible, they might not be in the same order found in the model, or they just might not allow access to some of the locations in the model. This is a convenience method for getNextNorthSouthVisualPositionFrom(int, javax.swing.text.Position.Bias, java.awt.Shape, int, javax.swing.text.Position.Bias[]) and getNextEastWestVisualPositionFrom(int, javax.swing.text.Position.Bias, java.awt.Shape, int, javax.swing.text.Position.Bias[]).

Overrides:
getNextVisualPositionFrom in class View
Parameters:
pos - the position to convert >= 0
b - a bias value of either Position.Bias.Forward or Position.Bias.Backward
a - the allocated region to render into
direction - the direction from the current position that can be thought of as the arrow keys typically found on a keyboard; this may be one of the following:
  • SwingConstants.WEST
  • SwingConstants.EAST
  • SwingConstants.NORTH
  • SwingConstants.SOUTH
biasRet - an array containing the bias that was checked
Returns:
the location within the model that best represents the next location visual position
Throws:
BadLocationException
IllegalArgumentException - if direction is invalid

getViewIndex

public int getViewIndex(int pos,
                        Position.Bias b)
Returns the child view index representing the given position in the model. This is implemented to call the getViewIndexByPosition method for backward compatibility.

Overrides:
getViewIndex in class View
Parameters:
pos - the position >= 0
Returns:
index of the view representing the given position, or -1 if no view represents that position
Since:
1.3

isBefore

protected abstract boolean isBefore(int x,
                                    int y,
                                    Rectangle alloc)
Tests whether a point lies before the rectangle range.

Parameters:
x - the X coordinate >= 0
y - the Y coordinate >= 0
alloc - the rectangle
Returns:
true if the point is before the specified range

isAfter

protected abstract boolean isAfter(int x,
                                   int y,
                                   Rectangle alloc)
Tests whether a point lies after the rectangle range.

Parameters:
x - the X coordinate >= 0
y - the Y coordinate >= 0
alloc - the rectangle
Returns:
true if the point is after the specified range

getViewAtPoint

protected abstract View getViewAtPoint(int x,
                                       int y,
                                       Rectangle alloc)
Fetches the child view at the given coordinates.

Parameters:
x - the X coordinate >= 0
y - the Y coordinate >= 0
alloc - the parent's allocation on entry, which should be changed to the child's allocation on exit
Returns:
the child view

childAllocation

protected abstract void childAllocation(int index,
                                        Rectangle a)
Returns the allocation for a given child.

Parameters:
index - the index of the child, >= 0 && < getViewCount()
a - the allocation to the interior of the box on entry, and the allocation of the child view at the index on exit.

getViewAtPosition

protected View getViewAtPosition(int pos,
                                 Rectangle a)
Fetches the child view that represents the given position in the model. This is implemented to fetch the view in the case where there is a child view for each child element.

Parameters:
pos - the position >= 0
a - the allocation to the interior of the box on entry, and the allocation of the view containing the position on exit
Returns:
the view representing the given position, or null if there isn't one

getViewIndexAtPosition

protected int getViewIndexAtPosition(int pos)
Fetches the child view index representing the given position in the model. This is implemented to fetch the view in the case where there is a child view for each child element.

Parameters:
pos - the position >= 0
Returns:
index of the view representing the given position, or -1 if no view represents that position

getInsideAllocation

protected Rectangle getInsideAllocation(Shape a)
Translates the immutable allocation given to the view to a mutable allocation that represents the interior allocation (i.e. the bounds of the given allocation with the top, left, bottom, and right insets removed. It is expected that the returned value would be further mutated to represent an allocation to a child view. This is implemented to reuse an instance variable so it avoids creating excessive Rectangles. Typically the result of calling this method would be fed to the childAllocation method.

Parameters:
a - the allocation given to the view
Returns:
the allocation that represents the inside of the view after the margins have all been removed; if the given allocation was null, the return value is null

setParagraphInsets

protected void setParagraphInsets(AttributeSet attr)
Sets the insets from the paragraph attributes specified in the given attributes.

Parameters:
attr - the attributes

setInsets

protected void setInsets(short top,
                         short left,
                         short bottom,
                         short right)
Sets the insets for the view.

Parameters:
top - the top inset >= 0
left - the left inset >= 0
bottom - the bottom inset >= 0
right - the right inset >= 0

getLeftInset

protected short getLeftInset()
Gets the left inset.

Returns:
the inset >= 0

getRightInset

protected short getRightInset()
Gets the right inset.

Returns:
the inset >= 0

getTopInset

protected short getTopInset()
Gets the top inset.

Returns:
the inset >= 0

getBottomInset

protected short getBottomInset()
Gets the bottom inset.

Returns:
the inset >= 0

getNextNorthSouthVisualPositionFrom

protected int getNextNorthSouthVisualPositionFrom(int pos,
                                                  Position.Bias b,
                                                  Shape a,
                                                  int direction,
                                                  Position.Bias[] biasRet)
                                           throws BadLocationException
Returns the next visual position for the cursor, in either the north or south direction.

Parameters:
pos - the position to convert >= 0
b - a bias value of either Position.Bias.Forward or Position.Bias.Backward
a - the allocated region to render into
direction - the direction from the current position that can be thought of as the arrow keys typically found on a keyboard; this may be one of the following:
  • SwingConstants.NORTH
  • SwingConstants.SOUTH
biasRet - an array containing the bias that was checked
Returns:
the location within the model that best represents the next north or south location
Throws:
BadLocationException
IllegalArgumentException - if direction is invalid
See Also:
getNextVisualPositionFrom(int, javax.swing.text.Position.Bias, java.awt.Shape, int, javax.swing.text.Position.Bias[])

getNextEastWestVisualPositionFrom

protected int getNextEastWestVisualPositionFrom(int pos,
                                                Position.Bias b,
                                                Shape a,
                                                int direction,
                                                Position.Bias[] biasRet)
                                         throws BadLocationException
Returns the next visual position for the cursor, in either the east or west direction.

Parameters:
pos - the position to convert >= 0
b - a bias value of either Position.Bias.Forward or Position.Bias.Backward
a - the allocated region to render into
direction - the direction from the current position that can be thought of as the arrow keys typically found on a keyboard; this may be one of the following:
  • SwingConstants.WEST
  • SwingConstants.EAST
biasRet - an array containing the bias that was checked
Returns:
the location within the model that best represents the next west or east location
Throws:
BadLocationException
IllegalArgumentException - if direction is invalid
See Also:
getNextVisualPositionFrom(int, javax.swing.text.Position.Bias, java.awt.Shape, int, javax.swing.text.Position.Bias[])

flipEastAndWestAtEnds

protected boolean flipEastAndWestAtEnds(int position,
                                        Position.Bias bias)
Determines in which direction the next view lays. Consider the View at index n. Typically the Views are layed out from left to right, so that the View to the EAST will be at index n + 1, and the View to the WEST will be at index n - 1. In certain situations, such as with bidirectional text, it is possible that the View to EAST is not at index n + 1, but rather at index n - 1, or that the View to the WEST is not at index n - 1, but index n + 1. In this case this method would return true, indicating the Views are layed out in descending order.

This unconditionally returns false, subclasses should override this method if there is the possibility for laying Views in descending order.

Parameters:
position - position into the model
bias - either Position.Bias.Forward or Position.Bias.Backward
Returns:
false
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DateFormatter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DateFormatter

java.lang.Object
    extended by  javax.swing.JFormattedTextField.AbstractFormatter
        extended by  javax.swing.text.DefaultFormatter
            extended by  javax.swing.text.InternationalFormatter
                extended by  javax.swing.text.DateFormatter
All Implemented Interfaces:
Serializable, Cloneable
public class DateFormatter
extends InternationalFormatter

DateFormatter is an InternationalFormatter that does its formatting by way of an instance of java.text.DateFormat.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Since:
1.4
See Also:
DateFormat

Constructor Summary
DateFormatter()
This is shorthand for new DateFormatter(DateFormat.getDateInstance()).
DateFormatter(DateFormat format)
Returns a DateFormatter configured with the specified Format instance.
Method Summary
 void setFormat(DateFormat format)
Sets the format that dictates the legal values that can be edited and displayed.
Methods inherited from class javax.swing.text.InternationalFormatter
clone, getActions, getFields, getFormat, getMaximum, getMinimum, install, setFormat, setMaximum, setMinimum, stringToValue, valueToString
Methods inherited from class javax.swing.text.DefaultFormatter
getAllowsInvalid, getCommitsOnValidEdit, getDocumentFilter, getNavigationFilter, getOverwriteMode, getValueClass, setAllowsInvalid, setCommitsOnValidEdit, setOverwriteMode, setValueClass
Methods inherited from class javax.swing.JFormattedTextField.AbstractFormatter
getFormattedTextField, invalidEdit, setEditValid, uninstall
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DateFormatter

public DateFormatter()
This is shorthand for new DateFormatter(DateFormat.getDateInstance()).

DateFormatter

public DateFormatter(DateFormat format)
Returns a DateFormatter configured with the specified Format instance.

Parameters:
format - Format used to dictate legal values
Method Detail

setFormat

public void setFormat(DateFormat format)
Sets the format that dictates the legal values that can be edited and displayed.

If you have used the nullary constructor the value of this property will be determined for the current locale by way of the Dateformat.getDateInstance() method.

Parameters:
format - DateFormat instance used for converting from/to Strings
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultCaret

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultCaret

java.lang.Object
    extended by  java.awt.geom.RectangularShape
        extended by  java.awt.geom.Rectangle2D
            extended by  java.awt.Rectangle
                extended by  javax.swing.text.DefaultCaret
All Implemented Interfaces:
FocusListener, MouseListener, MouseMotionListener, Shape, Serializable, Cloneable, EventListener, Caret
Direct Known Subclasses:
BasicTextUI.BasicCaret
public class DefaultCaret
extends Rectangle
implements Caret, FocusListener, MouseListener, MouseMotionListener

A default implementation of Caret. The caret is rendered as a vertical line in the color specified by the CaretColor property of the associated JTextComponent. It can blink at the rate specified by the BlinkRate property.

This implementation expects two sources of asynchronous notification. The timer thread fires asynchronously, and causes the caret to simply repaint the most recent bounding box. The caret also tracks change as the document is modified. Typically this will happen on the event dispatch thread as a result of some mouse or keyboard event. The caret behavior on both synchronous and asynchronous documents updates is controlled by UpdatePolicy property. The repaint of the new caret location will occur on the event thread in any case, as calls to modelToView are only safe on the event thread.

The caret acts as a mouse and focus listener on the text component it has been installed in, and defines the caret semantics based upon those events. The listener methods can be reimplemented to change the semantics. By default, the first mouse button will be used to set focus and caret position. Dragging the mouse pointer with the first mouse button will sweep out a selection that is contiguous in the model. If the associated text component is editable, the caret will become visible when focus is gained, and invisible when focus is lost.

The Highlighter bound to the associated text component is used to render the selection by default. Selection appearance can be customized by supplying a painter to use for the highlights. By default a painter is used that will render a solid color as specified in the associated text component in the SelectionColor property. This can easily be changed by reimplementing the getSelectionHighlighter method.

A customized caret appearance can be achieved by reimplementing the paint method. If the paint method is changed, the damage method should also be reimplemented to cause a repaint for the area needed to render the caret. The caret extends the Rectangle class which is used to hold the bounding box for where the caret was last rendered. This enables the caret to repaint in a thread-safe manner when the caret moves without making a call to modelToView which is unstable between model updates and view repair (i.e. the order of delivery to DocumentListeners is not guaranteed).

The magic caret position is set to null when the caret position changes. A timer is used to determine the new location (after the caret change). When the timer fires, if the magic caret position is still null it is reset to the current caret position. Any actions that change the caret position and want the magic caret position to remain the same, must remember the magic caret position, change the cursor, and then set the magic caret position to its original value. This has the benefit that only actions that want the magic caret position to persist (such as open/down) need to know about it.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
Caret

Nested Class Summary
Nested classes/interfaces inherited from class java.awt.geom.Rectangle2D
Rectangle2D.Double, Rectangle2D.Float
Field Summary
static int | ALWAYS_UPDATE Indicates that the caret position is to be always updated accordingly to the document changes regardless whether the document updates are performed on the Event Dispatching Thread or not.
protected ChangeEvent | changeEvent The change event for the model.
protected EventListenerList | listenerList The event listener list.
static int | NEVER_UPDATE Indicates that the caret should remain at the same absolute position in the document regardless of any document updates, except when the document length becomes less than the current caret position due to removal.
static int | UPDATE_WHEN_ON_EDT Indicates that the caret position is to be updated only when document changes are performed on the Event Dispatching Thread.
Fields inherited from class java.awt.Rectangle
height, width, x, y
Fields inherited from class java.awt.geom.Rectangle2D
OUT_BOTTOM, OUT_LEFT, OUT_RIGHT, OUT_TOP
Constructor Summary
DefaultCaret()
Constructs a default caret.
Method Summary
 void addChangeListener(ChangeListener l)
Adds a listener to track whenever the caret position has been changed.
protected  void adjustVisibility(Rectangle nloc)
Scrolls the associated view (if necessary) to make the caret visible.
protected  void damage(Rectangle r)
Damages the area surrounding the caret to cause it to be repainted in a new location.
 void deinstall(JTextComponent c)
Called when the UI is being removed from the interface of a JTextComponent.
 boolean equals(Object obj)
Compares this object to the specified object.
protected  void fireStateChanged()
Notifies all listeners that have registered interest for notification on this event type.
 void focusGained(FocusEvent e)
Called when the component containing the caret gains focus.
 void focusLost(FocusEvent e)
Called when the component containing the caret loses focus.
 int getBlinkRate()
Gets the caret blink rate.
 ChangeListener[] getChangeListeners()
Returns an array of all the change listeners registered on this caret.
protected  JTextComponent getComponent()
Gets the text editor component that this caret is is bound to.
 int getDot()
Fetches the current position of the caret.
 Position.Bias getDotBias()
Returns the bias of the caret position.
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this caret.
 Point getMagicCaretPosition()
Gets the saved caret position.
 int getMark()
Fetches the current position of the mark.
 Position.Bias getMarkBias()
Returns the bias of the mark.
protected  Highlighter.HighlightPainter getSelectionPainter()
Gets the painter for the Highlighter.
 int getUpdatePolicy()
Gets the caret movement policy on document updates.
 void install(JTextComponent c)
Called when the UI is being installed into the interface of a JTextComponent.
 boolean isActive()
Determines if the caret is currently active.
 boolean isSelectionVisible()
Checks whether the current selection is visible.
 boolean isVisible()
Indicates whether or not the caret is currently visible.
 void mouseClicked(MouseEvent e)
Called when the mouse is clicked.
 void mouseDragged(MouseEvent e)
Moves the caret position according to the mouse pointer's current location.
 void mouseEntered(MouseEvent e)
Called when the mouse enters a region.
 void mouseExited(MouseEvent e)
Called when the mouse exits a region.
 void mouseMoved(MouseEvent e)
Called when the mouse is moved.
 void mousePressed(MouseEvent e)
If button 1 is pressed, this is implemented to request focus on the associated text component, and to set the caret position.
 void mouseReleased(MouseEvent e)
Called when the mouse is released.
protected  void moveCaret(MouseEvent e)
Tries to move the position of the caret from the coordinates of a mouse event, using viewToModel().
 void moveDot(int dot)
Moves the caret position to the specified position, with a forward bias.
 void moveDot(int dot, Position.Bias dotBias)
Moves the caret position to the specified position, with the specified bias.
 void paint(Graphics g)
Renders the caret as a vertical line.
protected  void positionCaret(MouseEvent e)
Tries to set the position of the caret from the coordinates of a mouse event, using viewToModel().
 void removeChangeListener(ChangeListener l)
Removes a listener that was tracking caret position changes.
protected  void repaint()
Cause the caret to be painted.
 void setBlinkRate(int rate)
Sets the caret blink rate.
 void setDot(int dot)
Sets the caret position and mark to the specified position, with a forward bias.
 void setDot(int dot, Position.Bias dotBias)
Sets the caret position and mark to the specified position, with the specified bias.
 void setMagicCaretPosition(Point p)
Saves the current caret position.
 void setSelectionVisible(boolean vis)
Changes the selection visibility.
 void setUpdatePolicy(int policy)
Sets the caret movement policy on the document updates.
 void setVisible(boolean e)
Sets the caret visibility, and repaints the caret.
 String toString()
Returns a String representing this Rectangle and its values.
Methods inherited from class java.awt.Rectangle
add, add, add, contains, contains, contains, contains, createIntersection, createUnion, getBounds, getBounds2D, getHeight, getLocation, getSize, getWidth, getX, getY, grow, inside, intersection, intersects, isEmpty, move, outcode, reshape, resize, setBounds, setBounds, setLocation, setLocation, setRect, setSize, setSize, translate, union
Methods inherited from class java.awt.geom.Rectangle2D
add, add, add, contains, contains, getPathIterator, getPathIterator, hashCode, intersect, intersects, intersectsLine, intersectsLine, outcode, setFrame, setRect, union
Methods inherited from class java.awt.geom.RectangularShape
clone, contains, contains, getCenterX, getCenterY, getFrame, getMaxX, getMaxY, getMinX, getMinY, intersects, setFrame, setFrame, setFrameFromCenter, setFrameFromCenter, setFrameFromDiagonal, setFrameFromDiagonal
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.awt.Shape
contains, contains, contains, contains, getPathIterator, getPathIterator, intersects, intersects

Field Detail

UPDATE_WHEN_ON_EDT

public static final int UPDATE_WHEN_ON_EDT
Indicates that the caret position is to be updated only when document changes are performed on the Event Dispatching Thread.

Since:
1.5
See Also:
setUpdatePolicy(int), getUpdatePolicy(), Constant Field Values

NEVER_UPDATE

public static final int NEVER_UPDATE
Indicates that the caret should remain at the same absolute position in the document regardless of any document updates, except when the document length becomes less than the current caret position due to removal. In that case the caret position is adjusted to the end of the document.

Since:
1.5
See Also:
setUpdatePolicy(int), getUpdatePolicy(), Constant Field Values

ALWAYS_UPDATE

public static final int ALWAYS_UPDATE
Indicates that the caret position is to be always updated accordingly to the document changes regardless whether the document updates are performed on the Event Dispatching Thread or not.

Since:
1.5
See Also:
setUpdatePolicy(int), getUpdatePolicy(), Constant Field Values

listenerList

protected EventListenerList listenerList
The event listener list.

changeEvent

protected transient ChangeEvent changeEvent
The change event for the model. Only one ChangeEvent is needed per model instance since the event's only (read-only) state is the source property. The source of events generated here is always "this".

Constructor Detail

DefaultCaret

public DefaultCaret()
Constructs a default caret.

Method Detail

setUpdatePolicy

public void setUpdatePolicy(int policy)
Sets the caret movement policy on the document updates. Normally the caret updates its absolute position within the document on insertions occurred before or at the caret position and on removals before the caret position. 'Absolute position' means here the position relative to the start of the document. For example if a character is typed within editable text component it is inserted at the caret position and the caret moves to the next absolute position within the document due to insertion and if BACKSPACE is typed then caret decreases its absolute position due to removal of a character before it. Sometimes it may be useful to turn off the caret position updates so that the caret stays at the same absolute position within the document position regardless of any document updates.

The following update policies are allowed:

  • NEVER_UPDATE: the caret stays at the same absolute position in the document regardless of any document updates, except when document length becomes less than the current caret position due to removal. In that case caret position is adjusted to the end of the document. The caret doesn't try to keep itself visible by scrolling the associated view when using this policy.
  • ALWAYS_UPDATE: the caret always tracks document changes. For regular changes it increases its position if an insertion occurs before or at its current position, and decreases position if a removal occurs before its current position. For undo/redo updates it is always moved to the position where update occurred. The caret also tries to keep itself visible by calling adjustVisibility method.
  • UPDATE_WHEN_ON_EDT: acts like ALWAYS_UPDATE if the document updates are performed on the Event Dispatching Thread and like NEVER_UPDATE if updates are performed on other thread.

The default property value is UPDATE_WHEN_ON_EDT.

Parameters:
policy - one of the following values : UPDATE_WHEN_ON_EDT, NEVER_UPDATE, ALWAYS_UPDATE
Throws:
IllegalArgumentException - if invalid value is passed
Since:
1.5
See Also:
getUpdatePolicy(), adjustVisibility(java.awt.Rectangle), UPDATE_WHEN_ON_EDT, NEVER_UPDATE, ALWAYS_UPDATE

getUpdatePolicy

public int getUpdatePolicy()
Gets the caret movement policy on document updates.

Returns:
one of the following values : UPDATE_WHEN_ON_EDT, NEVER_UPDATE, ALWAYS_UPDATE
Since:
1.5
See Also:
setUpdatePolicy(int), UPDATE_WHEN_ON_EDT, NEVER_UPDATE, ALWAYS_UPDATE

getComponent

protected final JTextComponent getComponent()
Gets the text editor component that this caret is is bound to.

Returns:
the component

repaint

protected final void repaint()
Cause the caret to be painted. The repaint area is the bounding box of the caret (i.e. the caret rectangle or this).

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

damage

protected void damage(Rectangle r)
Damages the area surrounding the caret to cause it to be repainted in a new location. If paint() is reimplemented, this method should also be reimplemented. This method should update the caret bounds (x, y, width, and height).

Parameters:
r - the current location of the caret
See Also:
paint(java.awt.Graphics)

adjustVisibility

protected void adjustVisibility(Rectangle nloc)
Scrolls the associated view (if necessary) to make the caret visible. Since how this should be done is somewhat of a policy, this method can be reimplemented to change the behavior. By default the scrollRectToVisible method is called on the associated component.

Parameters:
nloc - the new position to scroll to

getSelectionPainter

protected Highlighter.HighlightPainter getSelectionPainter()
Gets the painter for the Highlighter.

Returns:
the painter

positionCaret

protected void positionCaret(MouseEvent e)
Tries to set the position of the caret from the coordinates of a mouse event, using viewToModel().

Parameters:
e - the mouse event

moveCaret

protected void moveCaret(MouseEvent e)
Tries to move the position of the caret from the coordinates of a mouse event, using viewToModel(). This will cause a selection if the dot and mark are different.

Parameters:
e - the mouse event

focusGained

public void focusGained(FocusEvent e)
Called when the component containing the caret gains focus. This is implemented to set the caret to visible if the component is editable.

Specified by:
focusGained in interface FocusListener
Parameters:
e - the focus event
See Also:
FocusListener.focusGained(java.awt.event.FocusEvent)

focusLost

public void focusLost(FocusEvent e)
Called when the component containing the caret loses focus. This is implemented to set the caret to visibility to false.

Specified by:
focusLost in interface FocusListener
Parameters:
e - the focus event
See Also:
FocusListener.focusLost(java.awt.event.FocusEvent)

mouseClicked

public void mouseClicked(MouseEvent e)
Called when the mouse is clicked. If the click was generated from button1, a double click selects a word, and a triple click the current line.

Specified by:
mouseClicked in interface MouseListener
Parameters:
e - the mouse event
See Also:
MouseListener.mouseClicked(java.awt.event.MouseEvent)

mousePressed

public void mousePressed(MouseEvent e)
If button 1 is pressed, this is implemented to request focus on the associated text component, and to set the caret position. If the shift key is held down, the caret will be moved, potentially resulting in a selection, otherwise the caret position will be set to the new location. If the component is not enabled, there will be no request for focus.

Specified by:
mousePressed in interface MouseListener
Parameters:
e - the mouse event
See Also:
MouseListener.mousePressed(java.awt.event.MouseEvent)

mouseReleased

public void mouseReleased(MouseEvent e)
Called when the mouse is released.

Specified by:
mouseReleased in interface MouseListener
Parameters:
e - the mouse event
See Also:
MouseListener.mouseReleased(java.awt.event.MouseEvent)

mouseEntered

public void mouseEntered(MouseEvent e)
Called when the mouse enters a region.

Specified by:
mouseEntered in interface MouseListener
Parameters:
e - the mouse event
See Also:
MouseListener.mouseEntered(java.awt.event.MouseEvent)

mouseExited

public void mouseExited(MouseEvent e)
Called when the mouse exits a region.

Specified by:
mouseExited in interface MouseListener
Parameters:
e - the mouse event
See Also:
MouseListener.mouseExited(java.awt.event.MouseEvent)

mouseDragged

public void mouseDragged(MouseEvent e)
Moves the caret position according to the mouse pointer's current location. This effectively extends the selection. By default, this is only done for mouse button 1.

Specified by:
mouseDragged in interface MouseMotionListener
Parameters:
e - the mouse event
See Also:
MouseMotionListener.mouseDragged(java.awt.event.MouseEvent)

mouseMoved

public void mouseMoved(MouseEvent e)
Called when the mouse is moved.

Specified by:
mouseMoved in interface MouseMotionListener
Parameters:
e - the mouse event
See Also:
MouseMotionListener.mouseMoved(java.awt.event.MouseEvent)

paint

public void paint(Graphics g)
Renders the caret as a vertical line. If this is reimplemented the damage method should also be reimplemented as it assumes the shape of the caret is a vertical line. Sets the caret color to the value returned by getCaretColor().

If there are multiple text directions present in the associated document, a flag indicating the caret bias will be rendered. This will occur only if the associated document is a subclass of AbstractDocument and there are multiple bidi levels present in the bidi element structure (i.e. the text has multiple directions associated with it).

Specified by:
paint in interface Caret
Parameters:
g - the graphics context
See Also:
damage(java.awt.Rectangle)

install

public void install(JTextComponent c)
Called when the UI is being installed into the interface of a JTextComponent. This can be used to gain access to the model that is being navigated by the implementation of this interface. Sets the dot and mark to 0, and establishes document, property change, focus, mouse, and mouse motion listeners.

Specified by:
install in interface Caret
Parameters:
c - the component
See Also:
Caret.install(javax.swing.text.JTextComponent)

deinstall

public void deinstall(JTextComponent c)
Called when the UI is being removed from the interface of a JTextComponent. This is used to unregister any listeners that were attached.

Specified by:
deinstall in interface Caret
Parameters:
c - the component
See Also:
Caret.deinstall(javax.swing.text.JTextComponent)

addChangeListener

public void addChangeListener(ChangeListener l)
Adds a listener to track whenever the caret position has been changed.

Specified by:
addChangeListener in interface Caret
Parameters:
l - the listener
See Also:
Caret.addChangeListener(javax.swing.event.ChangeListener)

removeChangeListener

public void removeChangeListener(ChangeListener l)
Removes a listener that was tracking caret position changes.

Specified by:
removeChangeListener in interface Caret
Parameters:
l - the listener
See Also:
Caret.removeChangeListener(javax.swing.event.ChangeListener)

getChangeListeners

public ChangeListener[] getChangeListeners()
Returns an array of all the change listeners registered on this caret.

Returns:
all of this caret's ChangeListeners or an empty array if no change listeners are currently registered
Since:
1.4
See Also:
addChangeListener(javax.swing.event.ChangeListener), removeChangeListener(javax.swing.event.ChangeListener)

fireStateChanged

protected void fireStateChanged()
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method. The listener list is processed last to first.

See Also:
EventListenerList

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this caret. FooListeners are registered using the addFooListener method.

You can specify the listenerType argument with a class literal, such as FooListener.class. For example, you can query a DefaultCaret c for its change listeners with the following code:

ChangeListener[] cls = (ChangeListener[])(c.getListeners(ChangeListener.class));
If no such listeners exist, this method returns an empty array.

Parameters:
listenerType - the type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener
Returns:
an array of all objects registered as FooListeners on this component, or an empty array if no such listeners have been added
Throws:
ClassCastException - if listenerType doesn't specify a class or interface that implements java.util.EventListener
Since:
1.3
See Also:
getChangeListeners()

setSelectionVisible

public void setSelectionVisible(boolean vis)
Changes the selection visibility.

Specified by:
setSelectionVisible in interface Caret
Parameters:
vis - the new visibility

isSelectionVisible

public boolean isSelectionVisible()
Checks whether the current selection is visible.

Specified by:
isSelectionVisible in interface Caret
Returns:
true if the selection is visible

isActive

public boolean isActive()
Determines if the caret is currently active.

This method returns whether or not the Caret is currently in a blinking state. It does not provide information as to whether it is currently blinked on or off. To determine if the caret is currently painted use the isVisible method.

Returns:
true if active else false
Since:
1.5
See Also:
isVisible()

isVisible

public boolean isVisible()
Indicates whether or not the caret is currently visible. As the caret flashes on and off the return value of this will change between true, when the caret is painted, and false, when the caret is not painted. isActive indicates whether or not the caret is in a blinking state, such that it can be visible, and isVisible indicates whether or not the caret is actually visible.

Subclasses that wish to render a different flashing caret should override paint and only paint the caret if this method returns true.

Specified by:
isVisible in interface Caret
Returns:
true if visible else false
See Also:
Caret.isVisible(), isActive()

setVisible

public void setVisible(boolean e)
Sets the caret visibility, and repaints the caret. It is important to understand the relationship between this method, isVisible and isActive. Calling this method with a value of true activates the caret blinking. Setting it to false turns it completely off. To determine whether the blinking is active, you should call isActive. In effect, isActive is an appropriate corresponding "getter" method for this one. isVisible can be used to fetch the current visibility status of the caret, meaning whether or not it is currently painted. This status will change as the caret blinks on and off.

Here's a list showing the potential return values of both isActive and isVisible after calling this method:

setVisible(true):

  • isActive(): true
  • isVisible(): true or false depending on whether or not the caret is blinked on or off

setVisible(false):

  • isActive(): false
  • isVisible(): false

Specified by:
setVisible in interface Caret
Parameters:
e - the visibility specifier
See Also:
isActive(), Caret.setVisible(boolean)

setBlinkRate

public void setBlinkRate(int rate)
Sets the caret blink rate.

Specified by:
setBlinkRate in interface Caret
Parameters:
rate - the rate in milliseconds, 0 to stop blinking
See Also:
Caret.setBlinkRate(int)

getBlinkRate

public int getBlinkRate()
Gets the caret blink rate.

Specified by:
getBlinkRate in interface Caret
Returns:
the delay in milliseconds. If this is zero the caret will not blink.
See Also:
Caret.getBlinkRate()

getDot

public int getDot()
Fetches the current position of the caret.

Specified by:
getDot in interface Caret
Returns:
the position >= 0
See Also:
Caret.getDot()

getMark

public int getMark()
Fetches the current position of the mark. If there is a selection, the dot and mark will not be the same.

Specified by:
getMark in interface Caret
Returns:
the position >= 0
See Also:
Caret.getMark()

setDot

public void setDot(int dot)
Sets the caret position and mark to the specified position, with a forward bias. This implicitly sets the selection range to zero.

Specified by:
setDot in interface Caret
Parameters:
dot - the position >= 0
See Also:
setDot(int, Position.Bias), Caret.setDot(int)

moveDot

public void moveDot(int dot)
Moves the caret position to the specified position, with a forward bias.

Specified by:
moveDot in interface Caret
Parameters:
dot - the position >= 0
See Also:
moveDot(int, javax.swing.text.Position.Bias), Caret.moveDot(int)

moveDot

public void moveDot(int dot,
                    Position.Bias dotBias)
Moves the caret position to the specified position, with the specified bias.

Parameters:
dot - the position >= 0
dotBias - the bias for this position, not null
Throws:
IllegalArgumentException - if the bias is null
Since:
1.6
See Also:
Caret.moveDot(int)

setDot

public void setDot(int dot,
                   Position.Bias dotBias)
Sets the caret position and mark to the specified position, with the specified bias. This implicitly sets the selection range to zero.

Parameters:
dot - the position >= 0
dotBias - the bias for this position, not null
Throws:
IllegalArgumentException - if the bias is null
Since:
1.6
See Also:
Caret.setDot(int)

getDotBias

public Position.Bias getDotBias()
Returns the bias of the caret position.

Returns:
the bias of the caret position
Since:
1.6

getMarkBias

public Position.Bias getMarkBias()
Returns the bias of the mark.

Returns:
the bias of the mark
Since:
1.6

setMagicCaretPosition

public void setMagicCaretPosition(Point p)
Saves the current caret position. This is used when caret up/down actions occur, moving between lines that have uneven end positions.

Specified by:
setMagicCaretPosition in interface Caret
Parameters:
p - the position
See Also:
getMagicCaretPosition()

getMagicCaretPosition

public Point getMagicCaretPosition()
Gets the saved caret position.

Specified by:
getMagicCaretPosition in interface Caret
Returns:
the position see #setMagicCaretPosition
See Also:
Caret.setMagicCaretPosition(java.awt.Point)

equals

public boolean equals(Object obj)
Compares this object to the specified object. The superclass behavior of comparing rectangles is not desired, so this is changed to the Object behavior.

Overrides:
equals in class Rectangle
Parameters:
obj - the object to compare this font with
Returns:
true if the objects are equal; false otherwise
See Also:
Object.hashCode(), Hashtable

toString

public String toString()
Description copied from class: Rectangle
Returns a String representing this Rectangle and its values.

Overrides:
toString in class Rectangle
Returns:
a String representing this Rectangle object's coordinate and size values.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultEditorKit

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultEditorKit

java.lang.Object
    extended by  javax.swing.text.EditorKit
        extended by  javax.swing.text.DefaultEditorKit
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
StyledEditorKit
public class DefaultEditorKit
extends EditorKit

This is the set of things needed by a text component to be a reasonably functioning editor for some type of text document. This implementation provides a default implementation which treats text as plain text and provides a minimal set of actions for a simple editor.

Newlines
There are two properties which deal with newlines. The system property, line.separator, is defined to be platform-dependent, either "\n", "\r", or "\r\n". There is also a property defined in DefaultEditorKit, called EndOfLineStringProperty, which is defined automatically when a document is loaded, to be the first occurrence of any of the newline characters. When a document is loaded, EndOfLineStringProperty is set appropriately, and when the document is written back out, the EndOfLineStringProperty is used. But while the document is in memory, the "\n" character is used to define a newline, regardless of how the newline is defined when the document is on disk. Therefore, for searching purposes, "\n" should always be used. When a new document is created, and the EndOfLineStringProperty has not been defined, it will use the System property when writing out the document.

Note that EndOfLineStringProperty is set on the Document using the get/setProperty methods. Subclasses may override this behavior.

Nested Class Summary
static class | DefaultEditorKit.BeepAction Creates a beep.
static class | DefaultEditorKit.CopyAction Copies the selected region and place its contents into the system clipboard.
static class | DefaultEditorKit.CutAction Cuts the selected region and place its contents into the system clipboard.
static class | DefaultEditorKit.DefaultKeyTypedAction The action that is executed by default if a key typed event is received and there is no keymap entry.
static class | DefaultEditorKit.InsertBreakAction Places a line/paragraph break into the document.
static class | DefaultEditorKit.InsertContentAction Places content into the associated document.
static class | DefaultEditorKit.InsertTabAction Places a tab character into the document.
static class | DefaultEditorKit.PasteAction Pastes the contents of the system clipboard into the selected region, or before the caret if nothing is selected.
Field Summary
static String | backwardAction Name of the Action for moving the caret logically backward one position.
static String | beepAction Name of the action to create a beep.
static String | beginAction Name of the Action for moving the caret to the beginning of the document.
static String | beginLineAction Name of the Action for moving the caret to the beginning of a line.
static String | beginParagraphAction Name of the Action for moving the caret to the beginning of a paragraph.
static String | beginWordAction Name of the Action for moving the caret to the beginning of a word.
static String | copyAction Name of the action to copy the selected region and place the contents into the system clipboard.
static String | cutAction Name of the action to cut the selected region and place the contents into the system clipboard.
static String | defaultKeyTypedAction Name of the action that is executed by default if a key typed event is received and there is no keymap entry.
static String | deleteNextCharAction Name of the action to delete the character of content that follows the current caret position.
static String | deleteNextWordAction Name of the action to delete the word that follows the beginning of the selection.
static String | deletePrevCharAction Name of the action to delete the character of content that precedes the current caret position.
static String | deletePrevWordAction Name of the action to delete the word that precedes the beginning of the selection.
static String | downAction Name of the Action for moving the caret logically downward one position.
static String | endAction Name of the Action for moving the caret to the end of the document.
static String | endLineAction Name of the Action for moving the caret to the end of a line.
static String | EndOfLineStringProperty When reading a document if a CRLF is encountered a property with this name is added and the value will be "\r\n".
static String | endParagraphAction Name of the Action for moving the caret to the end of a paragraph.
static String | endWordAction Name of the Action for moving the caret to the end of a word.
static String | forwardAction Name of the Action for moving the caret logically forward one position.
static String | insertBreakAction Name of the action to place a line/paragraph break into the document.
static String | insertContentAction Name of the action to place content into the associated document.
static String | insertTabAction Name of the action to place a tab character into the document.
static String | nextWordAction Name of the Action for moving the caret to the beginning of the next word.
static String | pageDownAction Name of the action to page down vertically.
static String | pageUpAction Name of the action to page up vertically.
static String | pasteAction Name of the action to paste the contents of the system clipboard into the selected region, or before the caret if nothing is selected.
static String | previousWordAction Name of the Action for moving the caret to the beginning of the previous word.
static String | readOnlyAction Name of the action to set the editor into read-only mode.
static String | selectAllAction Name of the Action for selecting the entire document
static String | selectionBackwardAction Name of the Action for extending the selection by moving the caret logically backward one position.
static String | selectionBeginAction Name of the Action for moving the caret to the beginning of the document.
static String | selectionBeginLineAction Name of the Action for moving the caret to the beginning of a line, extending the selection.
static String | selectionBeginParagraphAction Name of the Action for moving the caret to the beginning of a paragraph, extending the selection.
static String | selectionBeginWordAction Name of the Action for moving the caret to the beginning of a word, extending the selection.
static String | selectionDownAction Name of the Action for moving the caret logically downward one position, extending the selection.
static String | selectionEndAction Name of the Action for moving the caret to the end of the document.
static String | selectionEndLineAction Name of the Action for moving the caret to the end of a line, extending the selection.
static String | selectionEndParagraphAction Name of the Action for moving the caret to the end of a paragraph, extending the selection.
static String | selectionEndWordAction Name of the Action for moving the caret to the end of a word, extending the selection.
static String | selectionForwardAction Name of the Action for extending the selection by moving the caret logically forward one position.
static String | selectionNextWordAction Name of the Action for moving the selection to the beginning of the next word, extending the selection.
static String | selectionPreviousWordAction Name of the Action for moving the selection to the beginning of the previous word, extending the selection.
static String | selectionUpAction Name of the Action for moving the caret logically upward one position, extending the selection.
static String | selectLineAction Name of the Action for selecting a line around the caret.
static String | selectParagraphAction Name of the Action for selecting a paragraph around the caret.
static String | selectWordAction Name of the Action for selecting a word around the caret.
static String | upAction Name of the Action for moving the caret logically upward one position.
static String | writableAction Name of the action to set the editor into writeable mode.
Constructor Summary
DefaultEditorKit()
default constructor for DefaultEditorKit
Method Summary
Caret | createCaret() Fetches a caret that can navigate through views produced by the associated ViewFactory.
Document | createDefaultDocument() Creates an uninitialized text storage model (PlainDocument) that is appropriate for this type of editor.
Action[] | getActions() Fetches the set of commands that can be used on a text component that is using a model and view produced by this kit.
String | getContentType() Gets the MIME type of the data that this kit represents support for.
ViewFactory | getViewFactory() Fetches a factory that is suitable for producing views of any models that are produced by this kit.
void | read(InputStream in, Document doc, int pos) Inserts content from the given stream which is expected to be in a format appropriate for this kind of content handler.
void | read(Reader in, Document doc, int pos) Inserts content from the given stream, which will be treated as plain text.
void | write(OutputStream out, Document doc, int pos, int len) Writes content from a document to the given stream in a format appropriate for this kind of content handler.
void | write(Writer out, Document doc, int pos, int len) Writes content from a document to the given stream as plain text.
Methods inherited from class javax.swing.text.EditorKit
clone, deinstall, install
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EndOfLineStringProperty

public static final String EndOfLineStringProperty
When reading a document if a CRLF is encountered a property with this name is added and the value will be "\r\n".

See Also:
Constant Field Values

insertContentAction

public static final String insertContentAction
Name of the action to place content into the associated document. If there is a selection, it is removed before the new content is added.

See Also:
getActions(), Constant Field Values

insertBreakAction

public static final String insertBreakAction
Name of the action to place a line/paragraph break into the document. If there is a selection, it is removed before the break is added.

See Also:
getActions(), Constant Field Values

insertTabAction

public static final String insertTabAction
Name of the action to place a tab character into the document. If there is a selection, it is removed before the tab is added.

See Also:
getActions(), Constant Field Values

deletePrevCharAction

public static final String deletePrevCharAction
Name of the action to delete the character of content that precedes the current caret position.

See Also:
getActions(), Constant Field Values

deleteNextCharAction

public static final String deleteNextCharAction
Name of the action to delete the character of content that follows the current caret position.

See Also:
getActions(), Constant Field Values

deleteNextWordAction

public static final String deleteNextWordAction
Name of the action to delete the word that follows the beginning of the selection.

Since:
1.6
See Also:
getActions(), JTextComponent.getSelectionStart(), Constant Field Values

deletePrevWordAction

public static final String deletePrevWordAction
Name of the action to delete the word that precedes the beginning of the selection.

Since:
1.6
See Also:
getActions(), JTextComponent.getSelectionStart(), Constant Field Values

readOnlyAction

public static final String readOnlyAction
Name of the action to set the editor into read-only mode.

See Also:
getActions(), Constant Field Values

writableAction

public static final String writableAction
Name of the action to set the editor into writeable mode.

See Also:
getActions(), Constant Field Values

cutAction

public static final String cutAction
Name of the action to cut the selected region and place the contents into the system clipboard.

See Also:
JTextComponent.cut(), getActions(), Constant Field Values

copyAction

public static final String copyAction
Name of the action to copy the selected region and place the contents into the system clipboard.

See Also:
JTextComponent.copy(), getActions(), Constant Field Values

pasteAction

public static final String pasteAction
Name of the action to paste the contents of the system clipboard into the selected region, or before the caret if nothing is selected.

See Also:
JTextComponent.paste(), getActions(), Constant Field Values

beepAction

public static final String beepAction
Name of the action to create a beep.

See Also:
getActions(), Constant Field Values

pageUpAction

public static final String pageUpAction
Name of the action to page up vertically.

See Also:
getActions(), Constant Field Values

pageDownAction

public static final String pageDownAction
Name of the action to page down vertically.

See Also:
getActions(), Constant Field Values

forwardAction

public static final String forwardAction
Name of the Action for moving the caret logically forward one position.

See Also:
getActions(), Constant Field Values

backwardAction

public static final String backwardAction
Name of the Action for moving the caret logically backward one position.

See Also:
getActions(), Constant Field Values

selectionForwardAction

public static final String selectionForwardAction
Name of the Action for extending the selection by moving the caret logically forward one position.

See Also:
getActions(), Constant Field Values

selectionBackwardAction

public static final String selectionBackwardAction
Name of the Action for extending the selection by moving the caret logically backward one position.

See Also:
getActions(), Constant Field Values

upAction

public static final String upAction
Name of the Action for moving the caret logically upward one position.

See Also:
getActions(), Constant Field Values

downAction

public static final String downAction
Name of the Action for moving the caret logically downward one position.

See Also:
getActions(), Constant Field Values

selectionUpAction

public static final String selectionUpAction
Name of the Action for moving the caret logically upward one position, extending the selection.

See Also:
getActions(), Constant Field Values

selectionDownAction

public static final String selectionDownAction
Name of the Action for moving the caret logically downward one position, extending the selection.

See Also:
getActions(), Constant Field Values

beginWordAction

public static final String beginWordAction
Name of the Action for moving the caret to the beginning of a word.

See Also:
getActions(), Constant Field Values

endWordAction

public static final String endWordAction
Name of the Action for moving the caret to the end of a word.

See Also:
getActions(), Constant Field Values

selectionBeginWordAction

public static final String selectionBeginWordAction
Name of the Action for moving the caret to the beginning of a word, extending the selection.

See Also:
getActions(), Constant Field Values

selectionEndWordAction

public static final String selectionEndWordAction
Name of the Action for moving the caret to the end of a word, extending the selection.

See Also:
getActions(), Constant Field Values

previousWordAction

public static final String previousWordAction
Name of the Action for moving the caret to the beginning of the previous word.

See Also:
getActions(), Constant Field Values

nextWordAction

public static final String nextWordAction
Name of the Action for moving the caret to the beginning of the next word.

See Also:
getActions(), Constant Field Values

selectionPreviousWordAction

public static final String selectionPreviousWordAction
Name of the Action for moving the selection to the beginning of the previous word, extending the selection.

See Also:
getActions(), Constant Field Values

selectionNextWordAction

public static final String selectionNextWordAction
Name of the Action for moving the selection to the beginning of the next word, extending the selection.

See Also:
getActions(), Constant Field Values

beginLineAction

public static final String beginLineAction
Name of the Action for moving the caret to the beginning of a line.

See Also:
getActions(), Constant Field Values

endLineAction

public static final String endLineAction
Name of the Action for moving the caret to the end of a line.

See Also:
getActions(), Constant Field Values

selectionBeginLineAction

public static final String selectionBeginLineAction
Name of the Action for moving the caret to the beginning of a line, extending the selection.

See Also:
getActions(), Constant Field Values

selectionEndLineAction

public static final String selectionEndLineAction
Name of the Action for moving the caret to the end of a line, extending the selection.

See Also:
getActions(), Constant Field Values

beginParagraphAction

public static final String beginParagraphAction
Name of the Action for moving the caret to the beginning of a paragraph.

See Also:
getActions(), Constant Field Values

endParagraphAction

public static final String endParagraphAction
Name of the Action for moving the caret to the end of a paragraph.

See Also:
getActions(), Constant Field Values

selectionBeginParagraphAction

public static final String selectionBeginParagraphAction
Name of the Action for moving the caret to the beginning of a paragraph, extending the selection.

See Also:
getActions(), Constant Field Values

selectionEndParagraphAction

public static final String selectionEndParagraphAction
Name of the Action for moving the caret to the end of a paragraph, extending the selection.

See Also:
getActions(), Constant Field Values

beginAction

public static final String beginAction
Name of the Action for moving the caret to the beginning of the document.

See Also:
getActions(), Constant Field Values

endAction

public static final String endAction
Name of the Action for moving the caret to the end of the document.

See Also:
getActions(), Constant Field Values

selectionBeginAction

public static final String selectionBeginAction
Name of the Action for moving the caret to the beginning of the document.

See Also:
getActions(), Constant Field Values

selectionEndAction

public static final String selectionEndAction
Name of the Action for moving the caret to the end of the document.

See Also:
getActions(), Constant Field Values

selectWordAction

public static final String selectWordAction
Name of the Action for selecting a word around the caret.

See Also:
getActions(), Constant Field Values

selectLineAction

public static final String selectLineAction
Name of the Action for selecting a line around the caret.

See Also:
getActions(), Constant Field Values

selectParagraphAction

public static final String selectParagraphAction
Name of the Action for selecting a paragraph around the caret.

See Also:
getActions(), Constant Field Values

selectAllAction

public static final String selectAllAction
Name of the Action for selecting the entire document

See Also:
getActions(), Constant Field Values

defaultKeyTypedAction

public static final String defaultKeyTypedAction
Name of the action that is executed by default if a key typed event is received and there is no keymap entry.

See Also:
getActions(), Constant Field Values
Constructor Detail

DefaultEditorKit

public DefaultEditorKit()
default constructor for DefaultEditorKit

Method Detail

getContentType

public String getContentType()
Gets the MIME type of the data that this kit represents support for. The default is text/plain.

Specified by:
getContentType in class EditorKit
Returns:
the type

getViewFactory

public ViewFactory getViewFactory()
Fetches a factory that is suitable for producing views of any models that are produced by this kit. The default is to have the UI produce the factory, so this method has no implementation.

Specified by:
getViewFactory in class EditorKit
Returns:
the view factory

getActions

public Action[] getActions()
Fetches the set of commands that can be used on a text component that is using a model and view produced by this kit.

Specified by:
getActions in class EditorKit
Returns:
the command list

createCaret

public Caret createCaret()
Fetches a caret that can navigate through views produced by the associated ViewFactory.

Specified by:
createCaret in class EditorKit
Returns:
the caret

createDefaultDocument

public Document createDefaultDocument()
Creates an uninitialized text storage model (PlainDocument) that is appropriate for this type of editor.

Specified by:
createDefaultDocument in class EditorKit
Returns:
the model

read

public void read(InputStream in,
                 Document doc,
                 int pos)
          throws IOException,
                 BadLocationException
Inserts content from the given stream which is expected to be in a format appropriate for this kind of content handler.

Specified by:
read in class EditorKit
Parameters:
in - The stream to read from
doc - The destination for the insertion.
pos - The location in the document to place the content >= 0.
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

write

public void write(OutputStream out,
                  Document doc,
                  int pos,
                  int len)
           throws IOException,
                  BadLocationException
Writes content from a document to the given stream in a format appropriate for this kind of content handler.

Specified by:
write in class EditorKit
Parameters:
out - The stream to write to
doc - The source for the write.
pos - The location in the document to fetch the content >= 0.
len - The amount to write out >= 0.
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

read

public void read(Reader in,
                 Document doc,
                 int pos)
          throws IOException,
                 BadLocationException
Inserts content from the given stream, which will be treated as plain text.

Specified by:
read in class EditorKit
Parameters:
in - The stream to read from
doc - The destination for the insertion.
pos - The location in the document to place the content >= 0.
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

write

public void write(Writer out,
                  Document doc,
                  int pos,
                  int len)
           throws IOException,
                  BadLocationException
Writes content from a document to the given stream as plain text.

Specified by:
write in class EditorKit
Parameters:
out - The stream to write to
doc - The source for the write.
pos - The location in the document to fetch the content from >= 0.
len - The amount to write out >= 0.
Throws:
IOException - on any I/O error
BadLocationException - if pos is not within 0 and the length of the document.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultEditorKit.BeepAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultEditorKit.BeepAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.DefaultEditorKit.BeepAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
DefaultEditorKit
public static class DefaultEditorKit.BeepAction
extends TextAction

Creates a beep.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
DefaultEditorKit.beepAction, DefaultEditorKit.getActions()

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
DefaultEditorKit.BeepAction()
Create this object with the appropriate identifier.
Method Summary
 void actionPerformed(ActionEvent e)
The operation to perform when this action is triggered.
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultEditorKit.BeepAction

public DefaultEditorKit.BeepAction()
Create this object with the appropriate identifier.

Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
The operation to perform when this action is triggered.

Parameters:
e - the action event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultEditorKit.CopyAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultEditorKit.CopyAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.DefaultEditorKit.CopyAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
DefaultEditorKit
public static class DefaultEditorKit.CopyAction
extends TextAction

Copies the selected region and place its contents into the system clipboard.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
DefaultEditorKit.copyAction, DefaultEditorKit.getActions()

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
DefaultEditorKit.CopyAction()
Create this object with the appropriate identifier.
Method Summary
 void actionPerformed(ActionEvent e)
The operation to perform when this action is triggered.
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultEditorKit.CopyAction

public DefaultEditorKit.CopyAction()
Create this object with the appropriate identifier.

Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
The operation to perform when this action is triggered.

Parameters:
e - the action event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultEditorKit.CutAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultEditorKit.CutAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.DefaultEditorKit.CutAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
DefaultEditorKit
public static class DefaultEditorKit.CutAction
extends TextAction

Cuts the selected region and place its contents into the system clipboard.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
DefaultEditorKit.cutAction, DefaultEditorKit.getActions()

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
DefaultEditorKit.CutAction()
Create this object with the appropriate identifier.
Method Summary
 void actionPerformed(ActionEvent e)
The operation to perform when this action is triggered.
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultEditorKit.CutAction

public DefaultEditorKit.CutAction()
Create this object with the appropriate identifier.

Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
The operation to perform when this action is triggered.

Parameters:
e - the action event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultEditorKit.DefaultKeyTypedAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultEditorKit.DefaultKeyTypedAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.DefaultEditorKit.DefaultKeyTypedAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
DefaultEditorKit
public static class DefaultEditorKit.DefaultKeyTypedAction
extends TextAction

The action that is executed by default if a key typed event is received and there is no keymap entry. There is a variation across different VM's in what gets sent as a key typed event, and this action tries to filter out the undesired events. This filters the control characters and those with the ALT modifier. It allows Control-Alt sequences through as these form legitimate unicode characters on some PC keyboards.

If the event doesn't get filtered, it will try to insert content into the text editor. The content is fetched from the command string of the ActionEvent. The text entry is done through the replaceSelection method on the target text component. This is the action that will be fired for most text entry tasks.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
DefaultEditorKit.defaultKeyTypedAction,
DefaultEditorKit.getActions(),
Keymap.setDefaultAction(javax.swing.Action),
Keymap.getDefaultAction()

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
DefaultEditorKit.DefaultKeyTypedAction()
Creates this object with the appropriate identifier.
Method Summary
 void actionPerformed(ActionEvent e)
The operation to perform when this action is triggered.
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultEditorKit.DefaultKeyTypedAction

public DefaultEditorKit.DefaultKeyTypedAction()
Creates this object with the appropriate identifier.

Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
The operation to perform when this action is triggered.

Parameters:
e - the action event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultEditorKit.InsertBreakAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultEditorKit.InsertBreakAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.DefaultEditorKit.InsertBreakAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
DefaultEditorKit
public static class DefaultEditorKit.InsertBreakAction
extends TextAction

Places a line/paragraph break into the document. If there is a selection, it is removed before the break is added.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
DefaultEditorKit.insertBreakAction, DefaultEditorKit.getActions()

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
DefaultEditorKit.InsertBreakAction()
Creates this object with the appropriate identifier.
Method Summary
 void actionPerformed(ActionEvent e)
The operation to perform when this action is triggered.
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultEditorKit.InsertBreakAction

public DefaultEditorKit.InsertBreakAction()
Creates this object with the appropriate identifier.

Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
The operation to perform when this action is triggered.

Parameters:
e - the action event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultEditorKit.InsertContentAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultEditorKit.InsertContentAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.DefaultEditorKit.InsertContentAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
DefaultEditorKit
public static class DefaultEditorKit.InsertContentAction
extends TextAction

Places content into the associated document. If there is a selection, it is removed before the new content is added.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
DefaultEditorKit.insertContentAction, DefaultEditorKit.getActions()

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
DefaultEditorKit.InsertContentAction()
Creates this object with the appropriate identifier.
Method Summary
 void actionPerformed(ActionEvent e)
The operation to perform when this action is triggered.
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultEditorKit.InsertContentAction

public DefaultEditorKit.InsertContentAction()
Creates this object with the appropriate identifier.

Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
The operation to perform when this action is triggered.

Parameters:
e - the action event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultEditorKit.InsertTabAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultEditorKit.InsertTabAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.DefaultEditorKit.InsertTabAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
DefaultEditorKit
public static class DefaultEditorKit.InsertTabAction
extends TextAction

Places a tab character into the document. If there is a selection, it is removed before the tab is added.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
DefaultEditorKit.insertTabAction, DefaultEditorKit.getActions()

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
DefaultEditorKit.InsertTabAction()
Creates this object with the appropriate identifier.
Method Summary
 void actionPerformed(ActionEvent e)
The operation to perform when this action is triggered.
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultEditorKit.InsertTabAction

public DefaultEditorKit.InsertTabAction()
Creates this object with the appropriate identifier.

Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
The operation to perform when this action is triggered.

Parameters:
e - the action event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultEditorKit.PasteAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultEditorKit.PasteAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.DefaultEditorKit.PasteAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
DefaultEditorKit
public static class DefaultEditorKit.PasteAction
extends TextAction

Pastes the contents of the system clipboard into the selected region, or before the caret if nothing is selected.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
DefaultEditorKit.pasteAction, DefaultEditorKit.getActions()

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
DefaultEditorKit.PasteAction()
Create this object with the appropriate identifier.
Method Summary
 void actionPerformed(ActionEvent e)
The operation to perform when this action is triggered.
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultEditorKit.PasteAction

public DefaultEditorKit.PasteAction()
Create this object with the appropriate identifier.

Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
The operation to perform when this action is triggered.

Parameters:
e - the action event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultFormatter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultFormatter

java.lang.Object
    extended by  javax.swing.JFormattedTextField.AbstractFormatter
        extended by  javax.swing.text.DefaultFormatter
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
InternationalFormatter, MaskFormatter
public class DefaultFormatter
extends JFormattedTextField.AbstractFormatter
implements Cloneable, Serializable

DefaultFormatter formats aribtrary objects. Formatting is done by invoking the toString method. In order to convert the value back to a String, your class must provide a constructor that takes a String argument. If no single argument constructor that takes a String is found, the returned value will be the String passed into stringToValue.

Instances of DefaultFormatter can not be used in multiple instances of JFormattedTextField. To obtain a copy of an already configured DefaultFormatter, use the clone method.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Since:
1.4
See Also:
JFormattedTextField.AbstractFormatter

Constructor Summary
DefaultFormatter()
Creates a DefaultFormatter.
Method Summary
Object | clone() Creates a copy of the DefaultFormatter.
boolean | getAllowsInvalid() Returns whether or not the value being edited is allowed to be invalid for a length of time.
boolean | getCommitsOnValidEdit() Returns when edits are published back to the JFormattedTextField.
protected DocumentFilter | getDocumentFilter() Returns the DocumentFilter used to restrict the characters that can be input into the JFormattedTextField.
protected NavigationFilter | getNavigationFilter() Returns the NavigationFilter used to restrict where the cursor can be placed.
boolean | getOverwriteMode() Returns the behavior when inserting characters.
Class<?> | getValueClass() Returns that class that is used to create new Objects.
void | install(JFormattedTextField ftf) Installs the DefaultFormatter onto a particular JFormattedTextField.
void | setAllowsInvalid(boolean allowsInvalid) Sets whether or not the value being edited is allowed to be invalid for a length of time (that is, stringToValue throws a ParseException).
void | setCommitsOnValidEdit(boolean commit) Sets when edits are published back to the JFormattedTextField.
void | setOverwriteMode(boolean overwriteMode) Configures the behavior when inserting characters.
void | setValueClass(Class<?> valueClass) Sets that class that is used to create new Objects.
Object | stringToValue(String string) Converts the passed in String into an instance of getValueClass by way of the constructor that takes a String argument.
String | valueToString(Object value) Converts the passed in Object into a String by way of the toString method.
Methods inherited from class javax.swing.JFormattedTextField.AbstractFormatter
getActions, getFormattedTextField, invalidEdit, setEditValid, uninstall
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultFormatter

public DefaultFormatter()
Creates a DefaultFormatter.

Method Detail

install

public void install(JFormattedTextField ftf)
Installs the DefaultFormatter onto a particular JFormattedTextField. This will invoke valueToString to convert the current value from the JFormattedTextField to a String. This will then install the Actions from getActions, the DocumentFilter returned from getDocumentFilter and the NavigationFilter returned from getNavigationFilter onto the JFormattedTextField.

Subclasses will typically only need to override this if they wish to install additional listeners on the JFormattedTextField.

If there is a ParseException in converting the current value to a String, this will set the text to an empty String, and mark the JFormattedTextField as being in an invalid state.

While this is a public method, this is typically only useful for subclassers of JFormattedTextField. JFormattedTextField will invoke this method at the appropriate times when the value changes, or its internal state changes.

Overrides:
install in class JFormattedTextField.AbstractFormatter
Parameters:
ftf - JFormattedTextField to format for, may be null indicating uninstall from current JFormattedTextField.

setCommitsOnValidEdit

public void setCommitsOnValidEdit(boolean commit)
Sets when edits are published back to the JFormattedTextField. If true, commitEdit is invoked after every valid edit (any time the text is edited). On the other hand, if this is false than the DefaultFormatter does not publish edits back to the JFormattedTextField. As such, the only time the value of the JFormattedTextField will change is when commitEdit is invoked on JFormattedTextField, typically when enter is pressed or focus leaves the JFormattedTextField.

Parameters:
commit - Used to indicate when edits are commited back to the JTextComponent

getCommitsOnValidEdit

public boolean getCommitsOnValidEdit()
Returns when edits are published back to the JFormattedTextField.

Returns:
true if edits are commited after evey valid edit

setOverwriteMode

public void setOverwriteMode(boolean overwriteMode)
Configures the behavior when inserting characters. If overwriteMode is true (the default), new characters overwrite existing characters in the model.

Parameters:
overwriteMode - Indicates if overwrite or overstrike mode is used

getOverwriteMode

public boolean getOverwriteMode()
Returns the behavior when inserting characters.

Returns:
true if newly inserted characters overwrite existing characters

setAllowsInvalid

public void setAllowsInvalid(boolean allowsInvalid)
Sets whether or not the value being edited is allowed to be invalid for a length of time (that is, stringToValue throws a ParseException). It is often convenient to allow the user to temporarily input an invalid value.

Parameters:
allowsInvalid - Used to indicate if the edited value must always be valid

getAllowsInvalid

public boolean getAllowsInvalid()
Returns whether or not the value being edited is allowed to be invalid for a length of time.

Returns:
false if the edited value must always be valid

setValueClass

public void setValueClass(Class<?> valueClass)
Sets that class that is used to create new Objects. If the passed in class does not have a single argument constructor that takes a String, String values will be used.

Parameters:
valueClass - Class used to construct return value from stringToValue

getValueClass

public Class<?> getValueClass()
Returns that class that is used to create new Objects.

Returns:
Class used to constuct return value from stringToValue

stringToValue

public Object stringToValue(String string)
                     throws ParseException
Converts the passed in String into an instance of getValueClass by way of the constructor that takes a String argument. If getValueClass returns null, the Class of the current value in the JFormattedTextField will be used. If this is null, a String will be returned. If the constructor thows an exception, a ParseException will be thrown. If there is no single argument String constructor, string will be returned.

Specified by:
stringToValue in class JFormattedTextField.AbstractFormatter
Parameters:
string - String to convert
Returns:
Object representation of text
Throws:
ParseException - if there is an error in the conversion

valueToString

public String valueToString(Object value)
                     throws ParseException
Converts the passed in Object into a String by way of the toString method.

Specified by:
valueToString in class JFormattedTextField.AbstractFormatter
Parameters:
value - Value to convert
Returns:
String representation of value
Throws:
ParseException - if there is an error in the conversion

getDocumentFilter

protected DocumentFilter getDocumentFilter()
Returns the DocumentFilter used to restrict the characters that can be input into the JFormattedTextField.

Overrides:
getDocumentFilter in class JFormattedTextField.AbstractFormatter
Returns:
DocumentFilter to restrict edits

getNavigationFilter

protected NavigationFilter getNavigationFilter()
Returns the NavigationFilter used to restrict where the cursor can be placed.

Overrides:
getNavigationFilter in class JFormattedTextField.AbstractFormatter
Returns:
NavigationFilter to restrict navigation

clone

public Object clone()
             throws CloneNotSupportedException
Creates a copy of the DefaultFormatter.

Overrides:
clone in class JFormattedTextField.AbstractFormatter
Returns:
copy of the DefaultFormatter
Throws:
CloneNotSupportedException - if the object's class does not support the Cloneable interface. Subclasses that override the clone method can also throw this exception to indicate that an instance cannot be cloned.
See Also:
Cloneable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultFormatterFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultFormatterFactory

java.lang.Object
    extended by  javax.swing.JFormattedTextField.AbstractFormatterFactory
        extended by  javax.swing.text.DefaultFormatterFactory
All Implemented Interfaces:
Serializable
public class DefaultFormatterFactory
extends JFormattedTextField.AbstractFormatterFactory
implements Serializable

An implementation of JFormattedTextField.AbstractFormatterFactory. DefaultFormatterFactory allows specifying a number of different JFormattedTextField.AbstractFormatters that are to be used. The most important one is the default one (setDefaultFormatter). The default formatter will be used if a more specific formatter could not be found. The following process is used to determine the appropriate formatter to use.

  1. Is the passed in value null? Use the null formatter.
  2. Does the JFormattedTextField have focus? Use the edit formatter.
  3. Otherwise, use the display formatter.
  4. If a non-null AbstractFormatter has not been found, use the default formatter.

The following code shows how to configure a JFormattedTextField with two JFormattedTextField.AbstractFormatters, one for display and one for editing.

 JFormattedTextField.AbstractFormatter editFormatter = ...;
 JFormattedTextField.AbstractFormatter displayFormatter = ...;
 DefaultFormatterFactory factory = new DefaultFormatterFactory(
                 displayFormatter, displayFormatter, editFormatter);
 JFormattedTextField tf = new JFormattedTextField(factory);

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Since:
1.4
See Also:
JFormattedTextField

Constructor Summary
DefaultFormatterFactory()
DefaultFormatterFactory(JFormattedTextField.AbstractFormatter defaultFormat)
Creates a DefaultFormatterFactory with the specified JFormattedTextField.AbstractFormatter.
DefaultFormatterFactory(JFormattedTextField.AbstractFormatter defaultFormat, JFormattedTextField.AbstractFormatter displayFormat)
Creates a DefaultFormatterFactory with the specified JFormattedTextField.AbstractFormatters.
DefaultFormatterFactory(JFormattedTextField.AbstractFormatter defaultFormat, JFormattedTextField.AbstractFormatter displayFormat, JFormattedTextField.AbstractFormatter editFormat)
Creates a DefaultFormatterFactory with the specified JFormattedTextField.AbstractFormatters.
DefaultFormatterFactory(JFormattedTextField.AbstractFormatter defaultFormat, JFormattedTextField.AbstractFormatter displayFormat, JFormattedTextField.AbstractFormatter editFormat, JFormattedTextField.AbstractFormatter nullFormat)
Creates a DefaultFormatterFactory with the specified JFormattedTextField.AbstractFormatters.
Method Summary
JFormattedTextField.AbstractFormatter | getDefaultFormatter() Returns the JFormattedTextField.AbstractFormatter to use as a last resort, eg in case a display, edit or null JFormattedTextField.AbstractFormatter has not been specified.
JFormattedTextField.AbstractFormatter | getDisplayFormatter() Returns the JFormattedTextField.AbstractFormatter to use if the JFormattedTextField is not being edited and either the value is not-null, or the value is null and a null formatter has has not been specified.
JFormattedTextField.AbstractFormatter | getEditFormatter() Returns the JFormattedTextField.AbstractFormatter to use if the JFormattedTextField is being edited and either the value is not-null, or the value is null and a null formatter has has not been specified.
JFormattedTextField.AbstractFormatter | getFormatter(JFormattedTextField source) Returns either the default formatter, display formatter, editor formatter or null formatter based on the state of the JFormattedTextField.
JFormattedTextField.AbstractFormatter | getNullFormatter() Returns the formatter to use if the value is null.
void | setDefaultFormatter(JFormattedTextField.AbstractFormatter atf) Sets the JFormattedTextField.AbstractFormatter to use as a last resort, eg in case a display, edit or null JFormattedTextField.AbstractFormatter has not been specified.
void | setDisplayFormatter(JFormattedTextField.AbstractFormatter atf) Sets the JFormattedTextField.AbstractFormatter to use if the JFormattedTextField is not being edited and either the value is not-null, or the value is null and a null formatter has has not been specified.
void | setEditFormatter(JFormattedTextField.AbstractFormatter atf) Sets the JFormattedTextField.AbstractFormatter to use if the JFormattedTextField is being edited and either the value is not-null, or the value is null and a null formatter has has not been specified.
void | setNullFormatter(JFormattedTextField.AbstractFormatter atf) Sets the formatter to use if the value of the JFormattedTextField is null.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultFormatterFactory

public DefaultFormatterFactory()

DefaultFormatterFactory

public DefaultFormatterFactory(JFormattedTextField.AbstractFormatter defaultFormat)
Creates a DefaultFormatterFactory with the specified JFormattedTextField.AbstractFormatter.

Parameters:
defaultFormat - JFormattedTextField.AbstractFormatter to be used if a more specific JFormattedTextField.AbstractFormatter can not be found.

DefaultFormatterFactory

public DefaultFormatterFactory(JFormattedTextField.AbstractFormatter defaultFormat,
                               JFormattedTextField.AbstractFormatter displayFormat)
Creates a DefaultFormatterFactory with the specified JFormattedTextField.AbstractFormatters.

Parameters:
defaultFormat - JFormattedTextField.AbstractFormatter to be used if a more specific JFormattedTextField.AbstractFormatter can not be found.
displayFormat - JFormattedTextField.AbstractFormatter to be used when the JFormattedTextField does not have focus.

DefaultFormatterFactory

public DefaultFormatterFactory(JFormattedTextField.AbstractFormatter defaultFormat,
                               JFormattedTextField.AbstractFormatter displayFormat,
                               JFormattedTextField.AbstractFormatter editFormat)
Creates a DefaultFormatterFactory with the specified JFormattedTextField.AbstractFormatters.

Parameters:
defaultFormat - JFormattedTextField.AbstractFormatter to be used if a more specific JFormattedTextField.AbstractFormatter can not be found.
displayFormat - JFormattedTextField.AbstractFormatter to be used when the JFormattedTextField does not have focus.
editFormat - JFormattedTextField.AbstractFormatter to be used when the JFormattedTextField has focus.

DefaultFormatterFactory

public DefaultFormatterFactory(JFormattedTextField.AbstractFormatter defaultFormat,
                               JFormattedTextField.AbstractFormatter displayFormat,
                               JFormattedTextField.AbstractFormatter editFormat,
                               JFormattedTextField.AbstractFormatter nullFormat)
Creates a DefaultFormatterFactory with the specified JFormattedTextField.AbstractFormatters.

Parameters:
defaultFormat - JFormattedTextField.AbstractFormatter to be used if a more specific JFormattedTextField.AbstractFormatter can not be found.
displayFormat - JFormattedTextField.AbstractFormatter to be used when the JFormattedTextField does not have focus.
editFormat - JFormattedTextField.AbstractFormatter to be used when the JFormattedTextField has focus.
nullFormat - JFormattedTextField.AbstractFormatter to be used when the JFormattedTextField has a null value.
Method Detail

setDefaultFormatter

public void setDefaultFormatter(JFormattedTextField.AbstractFormatter atf)
Sets the JFormattedTextField.AbstractFormatter to use as a last resort, eg in case a display, edit or null JFormattedTextField.AbstractFormatter has not been specified.

Parameters:
atf - JFormattedTextField.AbstractFormatter used if a more specific is not specified

getDefaultFormatter

public JFormattedTextField.AbstractFormatter getDefaultFormatter()
Returns the JFormattedTextField.AbstractFormatter to use as a last resort, eg in case a display, edit or null JFormattedTextField.AbstractFormatter has not been specified.

Returns:
JFormattedTextField.AbstractFormatter used if a more specific one is not specified.

setDisplayFormatter

public void setDisplayFormatter(JFormattedTextField.AbstractFormatter atf)
Sets the JFormattedTextField.AbstractFormatter to use if the JFormattedTextField is not being edited and either the value is not-null, or the value is null and a null formatter has has not been specified.

Parameters:
atf - JFormattedTextField.AbstractFormatter to use when the JFormattedTextField does not have focus

getDisplayFormatter

public JFormattedTextField.AbstractFormatter getDisplayFormatter()
Returns the JFormattedTextField.AbstractFormatter to use if the JFormattedTextField is not being edited and either the value is not-null, or the value is null and a null formatter has has not been specified.

Returns:
JFormattedTextField.AbstractFormatter to use when the JFormattedTextField does not have focus

setEditFormatter

public void setEditFormatter(JFormattedTextField.AbstractFormatter atf)
Sets the JFormattedTextField.AbstractFormatter to use if the JFormattedTextField is being edited and either the value is not-null, or the value is null and a null formatter has has not been specified.

Parameters:
atf - JFormattedTextField.AbstractFormatter to use when the component has focus

getEditFormatter

public JFormattedTextField.AbstractFormatter getEditFormatter()
Returns the JFormattedTextField.AbstractFormatter to use if the JFormattedTextField is being edited and either the value is not-null, or the value is null and a null formatter has has not been specified.

Returns:
JFormattedTextField.AbstractFormatter to use when the component has focus

setNullFormatter

public void setNullFormatter(JFormattedTextField.AbstractFormatter atf)
Sets the formatter to use if the value of the JFormattedTextField is null.

Parameters:
atf - JFormattedTextField.AbstractFormatter to use when the value of the JFormattedTextField is null.

getNullFormatter

public JFormattedTextField.AbstractFormatter getNullFormatter()
Returns the formatter to use if the value is null.

Returns:
JFormattedTextField.AbstractFormatter to use when the value is null

getFormatter

public JFormattedTextField.AbstractFormatter getFormatter(JFormattedTextField source)
Returns either the default formatter, display formatter, editor formatter or null formatter based on the state of the JFormattedTextField.

Specified by:
getFormatter in class JFormattedTextField.AbstractFormatterFactory
Parameters:
source - JFormattedTextField requesting JFormattedTextField.AbstractFormatter
Returns:
JFormattedTextField.AbstractFormatter to handle formatting duties.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultHighlighter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultHighlighter

java.lang.Object
    extended by  javax.swing.text.LayeredHighlighter
        extended by  javax.swing.text.DefaultHighlighter
All Implemented Interfaces:
Highlighter
Direct Known Subclasses:
BasicTextUI.BasicHighlighter
public class DefaultHighlighter
extends LayeredHighlighter

Implements the Highlighter interfaces. Implements a simple highlight painter that renders in a solid color.

See Also:
Highlighter

Nested Class Summary
static class DefaultHighlighter.DefaultHighlightPainter
Simple highlight painter that fills a highlighted area with a solid color.
Nested classes/interfaces inherited from class javax.swing.text.LayeredHighlighter
LayeredHighlighter.LayerPainter
Nested classes/interfaces inherited from interface javax.swing.text.Highlighter
Highlighter.Highlight, Highlighter.HighlightPainter
Field Summary
static LayeredHighlighter.LayerPainter DefaultPainter
Default implementation of LayeredHighlighter.LayerPainter that can be used for painting highlights.
Constructor Summary
DefaultHighlighter()
Creates a new DefaultHighlighther object.
Method Summary
Object | addHighlight(int p0, int p1, Highlighter.HighlightPainter p) Adds a highlight to the view.
void | changeHighlight(Object tag, int p0, int p1) Changes a highlight.
void | deinstall(JTextComponent c) Called when the UI is being removed from the interface of a JTextComponent.
boolean | getDrawsLayeredHighlights()
Highlighter.Highlight[] | getHighlights() Makes a copy of the highlights.
void | install(JTextComponent c) Called when the UI is being installed into the interface of a JTextComponent.
void | paint(Graphics g) Renders the highlights.
void | paintLayeredHighlights(Graphics g, int p0, int p1, Shape viewBounds, JTextComponent editor, View view) When leaf Views (such as LabelView) are rendering they should call into this method.
void | removeAllHighlights() Removes all highlights.
void | removeHighlight(Object tag) Removes a highlight from the view.
void | setDrawsLayeredHighlights(boolean newValue) If true, highlights are drawn as the Views draw the text.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DefaultPainter

public static final LayeredHighlighter.LayerPainter DefaultPainter
Default implementation of LayeredHighlighter.LayerPainter that can be used for painting highlights.

As of 1.4 this field is final.

Constructor Detail

DefaultHighlighter

public DefaultHighlighter()
Creates a new DefaultHighlighther object.

Method Detail

paint

public void paint(Graphics g)
Renders the highlights.

Parameters:
g - the graphics context

install

public void install(JTextComponent c)
Called when the UI is being installed into the interface of a JTextComponent. Installs the editor, and removes any existing highlights.

Parameters:
c - the editor component
See Also:
Highlighter.install(javax.swing.text.JTextComponent)

deinstall

public void deinstall(JTextComponent c)
Called when the UI is being removed from the interface of a JTextComponent.

Parameters:
c - the component
See Also:
Highlighter.deinstall(javax.swing.text.JTextComponent)

addHighlight

public Object addHighlight(int p0,
                           int p1,
                           Highlighter.HighlightPainter p)
                    throws BadLocationException
Adds a highlight to the view. Returns a tag that can be used to refer to the highlight.

Parameters:
p0 - the start offset of the range to highlight >= 0
p1 - the end offset of the range to highlight >= p0
p - the painter to use to actually render the highlight
Returns:
an object that can be used as a tag to refer to the highlight
Throws:
BadLocationException - if the specified location is invalid

removeHighlight

public void removeHighlight(Object tag)
Removes a highlight from the view.

Parameters:
tag - the reference to the highlight

removeAllHighlights

public void removeAllHighlights()
Removes all highlights.

changeHighlight

public void changeHighlight(Object tag,
                            int p0,
                            int p1)
                     throws BadLocationException
Changes a highlight.

Parameters:
tag - the highlight tag
p0 - the beginning of the range >= 0
p1 - the end of the range >= p0
Throws:
BadLocationException - if the specified location is invalid

getHighlights

public Highlighter.Highlight[] getHighlights()
Makes a copy of the highlights. Does not actually clone each highlight, but only makes references to them.

Returns:
the copy
See Also:
Highlighter.getHighlights()

paintLayeredHighlights

public void paintLayeredHighlights(Graphics g,
                                   int p0,
                                   int p1,
                                   Shape viewBounds,
                                   JTextComponent editor,
                                   View view)
When leaf Views (such as LabelView) are rendering they should call into this method. If a highlight is in the given region it will be drawn immediately.

Specified by:
paintLayeredHighlights in class LayeredHighlighter
Parameters:
g - Graphics used to draw
p0 - starting offset of view
p1 - ending offset of view
viewBounds - Bounds of View
editor - JTextComponent
view - View instance being rendered

setDrawsLayeredHighlights

public void setDrawsLayeredHighlights(boolean newValue)
If true, highlights are drawn as the Views draw the text. That is the Views will call into paintLayeredHighlight which will result in a rectangle being drawn before the text is drawn (if the offsets are in a highlighted region that is). For this to work the painter supplied must be an instance of LayeredHighlightPainter.

getDrawsLayeredHighlights

public boolean getDrawsLayeredHighlights()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultHighlighter.DefaultHighlightPainter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultHighlighter.DefaultHighlightPainter

java.lang.Object
    extended by  javax.swing.text.LayeredHighlighter.LayerPainter
        extended by  javax.swing.text.DefaultHighlighter.DefaultHighlightPainter
All Implemented Interfaces:
Highlighter.HighlightPainter
Enclosing class:
DefaultHighlighter
public static class DefaultHighlighter.DefaultHighlightPainter
extends LayeredHighlighter.LayerPainter

Simple highlight painter that fills a highlighted area with a solid color.

Constructor Summary
DefaultHighlighter.DefaultHighlightPainter(Color c)
Constructs a new highlight painter.
Method Summary
Color | getColor() Returns the color of the highlight.
void | paint(Graphics g, int offs0, int offs1, Shape bounds, JTextComponent c) Paints a highlight.
Shape | paintLayer(Graphics g, int offs0, int offs1, Shape bounds, JTextComponent c, View view) Paints a portion of a highlight.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultHighlighter.DefaultHighlightPainter

public DefaultHighlighter.DefaultHighlightPainter(Color c)
Constructs a new highlight painter. If c is null, the JTextComponent will be queried for its selection color.

Parameters:
c - the color for the highlight
Method Detail

getColor

public Color getColor()
Returns the color of the highlight.

Returns:
the color

paint

public void paint(Graphics g,
                  int offs0,
                  int offs1,
                  Shape bounds,
                  JTextComponent c)
Paints a highlight.

Parameters:
g - the graphics context
offs0 - the starting model offset >= 0
offs1 - the ending model offset >= offs1
bounds - the bounding box for the highlight
c - the editor

paintLayer

public Shape paintLayer(Graphics g,
                        int offs0,
                        int offs1,
                        Shape bounds,
                        JTextComponent c,
                        View view)
Paints a portion of a highlight.

Specified by:
paintLayer in class LayeredHighlighter.LayerPainter
Parameters:
g - the graphics context
offs0 - the starting model offset >= 0
offs1 - the ending model offset >= offs1
bounds - the bounding box of the view, which is not necessarily the region to paint.
c - the editor
view - View painting for
Returns:
region drawing occured in
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultStyledDocument

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultStyledDocument

java.lang.Object
    extended by  javax.swing.text.AbstractDocument
        extended by  javax.swing.text.DefaultStyledDocument
All Implemented Interfaces:
Serializable, Document, StyledDocument
Direct Known Subclasses:
HTMLDocument
public class DefaultStyledDocument
extends AbstractDocument
implements StyledDocument

A document that can be marked up with character and paragraph styles in a manner similar to the Rich Text Format. The element structure for this document represents style crossings for style runs. These style runs are mapped into a paragraph element structure (which may reside in some other structure). The style runs break at paragraph boundaries since logical styles are assigned to paragraph boundaries.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
Document, AbstractDocument

Nested Class Summary
static class | DefaultStyledDocument.AttributeUndoableEdit An UndoableEdit used to remember AttributeSet changes to an Element.
class | DefaultStyledDocument.ElementBuffer Class to manage changes to the element hierarchy.
static class | DefaultStyledDocument.ElementSpec Specification for building elements.
protected class | DefaultStyledDocument.SectionElement Default root element for a document...
Nested classes/interfaces inherited from class javax.swing.text.AbstractDocument
AbstractDocument.AbstractElement, AbstractDocument.AttributeContext, AbstractDocument.BranchElement, AbstractDocument.Content, AbstractDocument.DefaultDocumentEvent, AbstractDocument.ElementEdit, AbstractDocument.LeafElement
Field Summary
protected DefaultStyledDocument.ElementBuffer | buffer
static int | BUFFER_SIZE_DEFAULT The default size of the initial content buffer.
Fields inherited from class javax.swing.text.AbstractDocument
BAD_LOCATION, BidiElementName, ContentElementName, ElementNameAttribute, listenerList, ParagraphElementName, SectionElementName
Fields inherited from interface javax.swing.text.Document
StreamDescriptionProperty, TitleProperty
Constructor Summary
DefaultStyledDocument()
Constructs a default styled document.
DefaultStyledDocument(AbstractDocument.Content c, StyleContext styles)
Constructs a styled document.
DefaultStyledDocument(StyleContext styles)
Constructs a styled document with the default content storage implementation and a shared set of styles.
Method Summary
void | addDocumentListener(DocumentListener listener) Adds a document listener for notification of any changes.
Style | addStyle(String nm, Style parent) Adds a new style into the logical style hierarchy.
protected void | create(DefaultStyledDocument.ElementSpec[] data) Initialize the document to reflect the given element structure (i.e.
protected AbstractDocument.AbstractElement | createDefaultRoot() Creates the root element to be used to represent the default document structure.
Color | getBackground(AttributeSet attr) Gets the background color from an attribute set.
Element | getCharacterElement(int pos) Gets a character element based on a position.
Element | getDefaultRootElement() Gets the default root element.
Font | getFont(AttributeSet attr) Gets the font from an attribute set.
Color | getForeground(AttributeSet attr) Gets the foreground color from an attribute set.
Style | getLogicalStyle(int p) Fetches the logical style assigned to the paragraph represented by the given position.
Element | getParagraphElement(int pos) Gets the paragraph element at the offset pos.
Style | getStyle(String nm) Fetches a named style previously added.
Enumeration<?> | getStyleNames() Fetches the list of of style names.
protected void | insert(int offset, DefaultStyledDocument.ElementSpec[] data) Inserts new elements in bulk.
protected void | insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr) Updates document structure as a result of text insertion.
void | removeDocumentListener(DocumentListener listener) Removes a document listener.
void | removeStyle(String nm) Removes a named style previously added to the document.
protected void | removeUpdate(AbstractDocument.DefaultDocumentEvent chng) Updates document structure as a result of text removal.
void | setCharacterAttributes(int offset, int length, AttributeSet s, boolean replace) Sets attributes for some part of the document.
void | setLogicalStyle(int pos, Style s) Sets the logical style to use for the paragraph at the given position.
void | setParagraphAttributes(int offset, int length, AttributeSet s, boolean replace) Sets attributes for a paragraph.
protected void | styleChanged(Style style) Called when any of this document's styles have changed.
Methods inherited from class javax.swing.text.AbstractDocument
addUndoableEditListener, createBranchElement, createLeafElement, createPosition, dump, fireChangedUpdate, fireInsertUpdate, fireRemoveUpdate, fireUndoableEditUpdate, getAsynchronousLoadPriority, getAttributeContext, getBidiRootElement, getContent, getCurrentWriter, getDocumentFilter, getDocumentListeners, getDocumentProperties, getEndPosition, getLength, getListeners, getProperty, getRootElements, getStartPosition, getText, getText, getUndoableEditListeners, insertString, postRemoveUpdate, putProperty, readLock, readUnlock, remove, removeUndoableEditListener, render, replace, setAsynchronousLoadPriority, setDocumentFilter, setDocumentProperties, writeLock, writeUnlock
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.swing.text.Document
addUndoableEditListener, createPosition, getEndPosition, getLength, getProperty, getRootElements, getStartPosition, getText, getText, insertString, putProperty, remove, removeUndoableEditListener, render

Field Detail

BUFFER_SIZE_DEFAULT

public static final int BUFFER_SIZE_DEFAULT
The default size of the initial content buffer.

See Also:
Constant Field Values

buffer

protected DefaultStyledDocument.ElementBuffer buffer
Constructor Detail

DefaultStyledDocument

public DefaultStyledDocument(AbstractDocument.Content c,
                             StyleContext styles)
Constructs a styled document.

Parameters:
c - the container for the content
styles - resources and style definitions which may be shared across documents

DefaultStyledDocument

public DefaultStyledDocument(StyleContext styles)
Constructs a styled document with the default content storage implementation and a shared set of styles.

Parameters:
styles - the styles

DefaultStyledDocument

public DefaultStyledDocument()
Constructs a default styled document. This buffers input content by a size of BUFFER_SIZE_DEFAULT and has a style context that is scoped by the lifetime of the document and is not shared with other documents.

Method Detail

getDefaultRootElement

public Element getDefaultRootElement()
Gets the default root element.

Specified by:
getDefaultRootElement in interface Document
Specified by:
getDefaultRootElement in class AbstractDocument
Returns:
the root
See Also:
Document.getDefaultRootElement()

create

protected void create(DefaultStyledDocument.ElementSpec[] data)
Initialize the document to reflect the given element structure (i.e. the structure reported by the getDefaultRootElement method. If the document contained any data it will first be removed.

insert

protected void insert(int offset,
                      DefaultStyledDocument.ElementSpec[] data)
               throws BadLocationException
Inserts new elements in bulk. This is useful to allow parsing with the document in an unlocked state and prepare an element structure modification. This method takes an array of tokens that describe how to update an element structure so the time within a write lock can be greatly reduced in an asynchronous update situation.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Parameters:
offset - the starting offset >= 0
data - the element data
Throws:
BadLocationException - for an invalid starting offset

addStyle

public Style addStyle(String nm,
                      Style parent)
Adds a new style into the logical style hierarchy. Style attributes resolve from bottom up so an attribute specified in a child will override an attribute specified in the parent.

Specified by:
addStyle in interface StyledDocument
Parameters:
nm - the name of the style (must be unique within the collection of named styles). The name may be null if the style is unnamed, but the caller is responsible for managing the reference returned as an unnamed style can't be fetched by name. An unnamed style may be useful for things like character attribute overrides such as found in a style run.
parent - the parent style. This may be null if unspecified attributes need not be resolved in some other style.
Returns:
the style

removeStyle

public void removeStyle(String nm)
Removes a named style previously added to the document.

Specified by:
removeStyle in interface StyledDocument
Parameters:
nm - the name of the style to remove

getStyle

public Style getStyle(String nm)
Fetches a named style previously added.

Specified by:
getStyle in interface StyledDocument
Parameters:
nm - the name of the style
Returns:
the style

getStyleNames

public Enumeration<?> getStyleNames()
Fetches the list of of style names.

Returns:
all the style names

setLogicalStyle

public void setLogicalStyle(int pos,
                            Style s)
Sets the logical style to use for the paragraph at the given position. If attributes aren't explicitly set for character and paragraph attributes they will resolve through the logical style assigned to the paragraph, which in turn may resolve through some hierarchy completely independent of the element hierarchy in the document.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Specified by:
setLogicalStyle in interface StyledDocument
Parameters:
pos - the offset from the start of the document >= 0
s - the logical style to assign to the paragraph, null if none

getLogicalStyle

public Style getLogicalStyle(int p)
Fetches the logical style assigned to the paragraph represented by the given position.

Specified by:
getLogicalStyle in interface StyledDocument
Parameters:
p - the location to translate to a paragraph and determine the logical style assigned >= 0. This is an offset from the start of the document.
Returns:
the style, null if none

setCharacterAttributes

public void setCharacterAttributes(int offset,
                                   int length,
                                   AttributeSet s,
                                   boolean replace)
Sets attributes for some part of the document. A write lock is held by this operation while changes are being made, and a DocumentEvent is sent to the listeners after the change has been successfully completed.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Specified by:
setCharacterAttributes in interface StyledDocument
Parameters:
offset - the offset in the document >= 0
length - the length >= 0
s - the attributes
replace - true if the previous attributes should be replaced before setting the new attributes

setParagraphAttributes

public void setParagraphAttributes(int offset,
                                   int length,
                                   AttributeSet s,
                                   boolean replace)
Sets attributes for a paragraph.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Specified by:
setParagraphAttributes in interface StyledDocument
Parameters:
offset - the offset into the paragraph >= 0
length - the number of characters affected >= 0
s - the attributes
replace - whether to replace existing attributes, or merge them

getParagraphElement

public Element getParagraphElement(int pos)
Gets the paragraph element at the offset pos. A paragraph consists of at least one child Element, which is usually a leaf.

Specified by:
getParagraphElement in interface StyledDocument
Specified by:
getParagraphElement in class AbstractDocument
Parameters:
pos - the starting offset >= 0
Returns:
the element

getCharacterElement

public Element getCharacterElement(int pos)
Gets a character element based on a position.

Specified by:
getCharacterElement in interface StyledDocument
Parameters:
pos - the position in the document >= 0
Returns:
the element

insertUpdate

protected void insertUpdate(AbstractDocument.DefaultDocumentEvent chng,
                            AttributeSet attr)
Updates document structure as a result of text insertion. This will happen within a write lock. This implementation simply parses the inserted content for line breaks and builds up a set of instructions for the element buffer.

Overrides:
insertUpdate in class AbstractDocument
Parameters:
chng - a description of the document change
attr - the attributes

removeUpdate

protected void removeUpdate(AbstractDocument.DefaultDocumentEvent chng)
Updates document structure as a result of text removal.

Overrides:
removeUpdate in class AbstractDocument
Parameters:
chng - a description of the document change

createDefaultRoot

protected AbstractDocument.AbstractElement createDefaultRoot()
Creates the root element to be used to represent the default document structure.

Returns:
the element base

getForeground

public Color getForeground(AttributeSet attr)
Gets the foreground color from an attribute set.

Specified by:
getForeground in interface StyledDocument
Parameters:
attr - the attribute set
Returns:
the color

getBackground

public Color getBackground(AttributeSet attr)
Gets the background color from an attribute set.

Specified by:
getBackground in interface StyledDocument
Parameters:
attr - the attribute set
Returns:
the color

getFont

public Font getFont(AttributeSet attr)
Gets the font from an attribute set.

Specified by:
getFont in interface StyledDocument
Parameters:
attr - the attribute set
Returns:
the font

styleChanged

protected void styleChanged(Style style)
Called when any of this document's styles have changed. Subclasses may wish to be intelligent about what gets damaged.

Parameters:
style - The Style that has changed.

addDocumentListener

public void addDocumentListener(DocumentListener listener)
Adds a document listener for notification of any changes.

Specified by:
addDocumentListener in interface Document
Overrides:
addDocumentListener in class AbstractDocument
Parameters:
listener - the listener
See Also:
Document.addDocumentListener(javax.swing.event.DocumentListener)

removeDocumentListener

public void removeDocumentListener(DocumentListener listener)
Removes a document listener.

Specified by:
removeDocumentListener in interface Document
Overrides:
removeDocumentListener in class AbstractDocument
Parameters:
listener - the listener
See Also:
Document.removeDocumentListener(javax.swing.event.DocumentListener)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultStyledDocument.AttributeUndoableEdit

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultStyledDocument.AttributeUndoableEdit

java.lang.Object
    extended by  javax.swing.undo.AbstractUndoableEdit
        extended by  javax.swing.text.DefaultStyledDocument.AttributeUndoableEdit
All Implemented Interfaces:
Serializable, UndoableEdit
Enclosing class:
DefaultStyledDocument
public static class DefaultStyledDocument.AttributeUndoableEdit
extends AbstractUndoableEdit

An UndoableEdit used to remember AttributeSet changes to an Element.

Field Summary
protected AttributeSet | copy
protected Element | element
protected boolean | isReplacing
protected AttributeSet | newAttributes
Fields inherited from class javax.swing.undo.AbstractUndoableEdit
RedoName, UndoName
Constructor Summary
DefaultStyledDocument.AttributeUndoableEdit(Element element, AttributeSet newAttributes, boolean isReplacing)
Method Summary
void | redo() Redoes a change.
void | undo() Undoes a change.
Methods inherited from class javax.swing.undo.AbstractUndoableEdit
addEdit, canRedo, canUndo, die, getPresentationName, getRedoPresentationName, getUndoPresentationName, isSignificant, replaceEdit, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

newAttributes

protected AttributeSet newAttributes

copy

protected AttributeSet copy

isReplacing

protected boolean isReplacing

element

protected Element element
Constructor Detail

DefaultStyledDocument.AttributeUndoableEdit

public DefaultStyledDocument.AttributeUndoableEdit(Element element,
                                                   AttributeSet newAttributes,
                                                   boolean isReplacing)
Method Detail

redo

public void redo()
          throws CannotRedoException
Redoes a change.

Specified by:
redo in interface UndoableEdit
Overrides:
redo in class AbstractUndoableEdit
Throws:
CannotRedoException - if the change cannot be redone
See Also:
AbstractUndoableEdit.canRedo()

undo

public void undo()
          throws CannotUndoException
Undoes a change.

Specified by:
undo in interface UndoableEdit
Overrides:
undo in class AbstractUndoableEdit
Throws:
CannotUndoException - if the change cannot be undone
See Also:
AbstractUndoableEdit.canUndo()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultStyledDocument.ElementBuffer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultStyledDocument.ElementBuffer

java.lang.Object
    extended by  javax.swing.text.DefaultStyledDocument.ElementBuffer
All Implemented Interfaces:
Serializable
Enclosing class:
DefaultStyledDocument
public class DefaultStyledDocument.ElementBuffer
extends Object
implements Serializable

Class to manage changes to the element hierarchy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
DefaultStyledDocument.ElementBuffer(Element root)
Creates a new ElementBuffer.
Method Summary
void | change(int offset, int length, AbstractDocument.DefaultDocumentEvent de) Changes content.
protected void | changeUpdate() Updates the element structure in response to a change in the document.
Element | clone(Element parent, Element clonee) Creates a copy of this element, with a different parent.
Element | getRootElement() Gets the root element.
void | insert(int offset, int length, DefaultStyledDocument.ElementSpec[] data, AbstractDocument.DefaultDocumentEvent de) Inserts new content.
protected void | insertUpdate(DefaultStyledDocument.ElementSpec[] data) Inserts an update into the document.
void | remove(int offset, int length, AbstractDocument.DefaultDocumentEvent de) Removes content.
protected void | removeUpdate() Updates the element structure in response to a removal from the associated sequence in the document.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultStyledDocument.ElementBuffer

public DefaultStyledDocument.ElementBuffer(Element root)
Creates a new ElementBuffer.

Parameters:
root - the root element
Since:
1.4
Method Detail

getRootElement

public Element getRootElement()
Gets the root element.

Returns:
the root element

insert

public void insert(int offset,
                   int length,
                   DefaultStyledDocument.ElementSpec[] data,
                   AbstractDocument.DefaultDocumentEvent de)
Inserts new content.

Parameters:
offset - the starting offset >= 0
length - the length >= 0
data - the data to insert
de - the event capturing this edit

remove

public void remove(int offset,
                   int length,
                   AbstractDocument.DefaultDocumentEvent de)
Removes content.

Parameters:
offset - the starting offset >= 0
length - the length >= 0
de - the event capturing this edit

change

public void change(int offset,
                   int length,
                   AbstractDocument.DefaultDocumentEvent de)
Changes content.

Parameters:
offset - the starting offset >= 0
length - the length >= 0
de - the event capturing this edit

insertUpdate

protected void insertUpdate(DefaultStyledDocument.ElementSpec[] data)
Inserts an update into the document.

Parameters:
data - the elements to insert

removeUpdate

protected void removeUpdate()
Updates the element structure in response to a removal from the associated sequence in the document. Any elements consumed by the span of the removal are removed.

changeUpdate

protected void changeUpdate()
Updates the element structure in response to a change in the document.

clone

public Element clone(Element parent,
                     Element clonee)
Creates a copy of this element, with a different parent.

Parameters:
parent - the parent element
clonee - the element to be cloned
Returns:
the copy
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultStyledDocument.ElementSpec

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultStyledDocument.ElementSpec

java.lang.Object
    extended by  javax.swing.text.DefaultStyledDocument.ElementSpec
Enclosing class:
DefaultStyledDocument
public static class DefaultStyledDocument.ElementSpec
extends Object

Specification for building elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
static short | ContentType A possible value for getType.
static short | EndTagType A possible value for getType.
static short | JoinFractureDirection A possible value for getDirection.
static short | JoinNextDirection A possible value for getDirection.
static short | JoinPreviousDirection A possible value for getDirection.
static short | OriginateDirection A possible value for getDirection.
static short | StartTagType A possible value for getType.
Constructor Summary
DefaultStyledDocument.ElementSpec(AttributeSet a, short type)
Constructor useful for markup when the markup will not be stored in the document.
DefaultStyledDocument.ElementSpec(AttributeSet a, short type, char[] txt, int offs, int len)
Constructor for creating a spec externally for batch input of content and markup into the document.
DefaultStyledDocument.ElementSpec(AttributeSet a, short type, int len)
Constructor for parsing inside the document when the data has already been added, but len information is needed.
Method Summary
char[] | getArray() Gets the array of characters.
AttributeSet | getAttributes() Gets the element attributes.
short | getDirection() Gets the direction.
int | getLength() Gets the length.
int | getOffset() Gets the starting offset.
short | getType() Gets the element type.
void | setDirection(short direction) Sets the direction.
void | setType(short type) Sets the element type.
String | toString() Converts the element to a string.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

StartTagType

public static final short StartTagType
A possible value for getType. This specifies that this record type is a start tag and represents markup that specifies the start of an element.

See Also:
Constant Field Values

EndTagType

public static final short EndTagType
A possible value for getType. This specifies that this record type is a end tag and represents markup that specifies the end of an element.

See Also:
Constant Field Values

ContentType

public static final short ContentType
A possible value for getType. This specifies that this record type represents content.

See Also:
Constant Field Values

JoinPreviousDirection

public static final short JoinPreviousDirection
A possible value for getDirection. This specifies that the data associated with this record should be joined to what precedes it.

See Also:
Constant Field Values

JoinNextDirection

public static final short JoinNextDirection
A possible value for getDirection. This specifies that the data associated with this record should be joined to what follows it.

See Also:
Constant Field Values

OriginateDirection

public static final short OriginateDirection
A possible value for getDirection. This specifies that the data associated with this record should be used to originate a new element. This would be the normal value.

See Also:
Constant Field Values

JoinFractureDirection

public static final short JoinFractureDirection
A possible value for getDirection. This specifies that the data associated with this record should be joined to the fractured element.

See Also:
Constant Field Values
Constructor Detail

DefaultStyledDocument.ElementSpec

public DefaultStyledDocument.ElementSpec(AttributeSet a,
                                         short type)
Constructor useful for markup when the markup will not be stored in the document.

Parameters:
a - the attributes for the element
type - the type of the element (StartTagType, EndTagType, ContentType)

DefaultStyledDocument.ElementSpec

public DefaultStyledDocument.ElementSpec(AttributeSet a,
                                         short type,
                                         int len)
Constructor for parsing inside the document when the data has already been added, but len information is needed.

Parameters:
a - the attributes for the element
type - the type of the element (StartTagType, EndTagType, ContentType)
len - the length >= 0

DefaultStyledDocument.ElementSpec

public DefaultStyledDocument.ElementSpec(AttributeSet a,
                                         short type,
                                         char[] txt,
                                         int offs,
                                         int len)
Constructor for creating a spec externally for batch input of content and markup into the document.

Parameters:
a - the attributes for the element
type - the type of the element (StartTagType, EndTagType, ContentType)
txt - the text for the element
offs - the offset into the text >= 0
len - the length of the text >= 0
Method Detail

setType

public void setType(short type)
Sets the element type.

Parameters:
type - the type of the element (StartTagType, EndTagType, ContentType)

getType

public short getType()
Gets the element type.

Returns:
the type of the element (StartTagType, EndTagType, ContentType)

setDirection

public void setDirection(short direction)
Sets the direction.

Parameters:
direction - the direction (JoinPreviousDirection, JoinNextDirection)

getDirection

public short getDirection()
Gets the direction.

Returns:
the direction (JoinPreviousDirection, JoinNextDirection)

getAttributes

public AttributeSet getAttributes()
Gets the element attributes.

Returns:
the attribute set

getArray

public char[] getArray()
Gets the array of characters.

Returns:
the array

getOffset

public int getOffset()
Gets the starting offset.

Returns:
the offset >= 0

getLength

public int getLength()
Gets the length.

Returns:
the length >= 0

toString

public String toString()
Converts the element to a string.

Overrides:
toString in class Object
Returns:
the string
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultStyledDocument.SectionElement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultStyledDocument.SectionElement

java.lang.Object
    extended by  javax.swing.text.AbstractDocument.AbstractElement
        extended by  javax.swing.text.AbstractDocument.BranchElement
            extended by  javax.swing.text.DefaultStyledDocument.SectionElement
All Implemented Interfaces:
Serializable, AttributeSet, Element, MutableAttributeSet, TreeNode
Enclosing class:
DefaultStyledDocument
protected class DefaultStyledDocument.SectionElement
extends AbstractDocument.BranchElement

Default root element for a document... maps out the paragraphs/lines contained.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from interface javax.swing.text.AttributeSet
AttributeSet.CharacterAttribute, AttributeSet.ColorAttribute, AttributeSet.FontAttribute, AttributeSet.ParagraphAttribute
Field Summary
Fields inherited from interface javax.swing.text.AttributeSet
NameAttribute, ResolveAttribute
Constructor Summary
DefaultStyledDocument.SectionElement()
Creates a new SectionElement.
Method Summary
 String getName()
Gets the name of the element.
Methods inherited from class javax.swing.text.AbstractDocument.BranchElement
children, getAllowsChildren, getElement, getElementCount, getElementIndex, getEndOffset, getStartOffset, isLeaf, positionToElement, replace, toString
Methods inherited from class javax.swing.text.AbstractDocument.AbstractElement
addAttribute, addAttributes, containsAttribute, containsAttributes, copyAttributes, dump, getAttribute, getAttributeCount, getAttributeNames, getAttributes, getChildAt, getChildCount, getDocument, getIndex, getParent, getParentElement, getResolveParent, isDefined, isEqual, removeAttribute, removeAttributes, removeAttributes, setResolveParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DefaultStyledDocument.SectionElement

public DefaultStyledDocument.SectionElement()
Creates a new SectionElement.

Method Detail

getName

public String getName()
Gets the name of the element.

Specified by:
getName in interface Element
Overrides:
getName in class AbstractDocument.BranchElement
Returns:
the name
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultTextUI

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DefaultTextUI

java.lang.Object
    extended by  javax.swing.plaf.ComponentUI
        extended by  javax.swing.plaf.TextUI
            extended by  javax.swing.plaf.basic.BasicTextUI
                extended by  javax.swing.text.DefaultTextUI
All Implemented Interfaces:
ViewFactory
Deprecated.

@Deprecated
public abstract class DefaultTextUI
extends BasicTextUI

This class has been deprecated and should no longer be used. The basis of the various TextUI implementations can be found in the javax.swing.plaf.basic package and the class BasicTextUI replaces this class.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.plaf.basic.BasicTextUI
BasicTextUI.BasicCaret, BasicTextUI.BasicHighlighter
Constructor Summary
DefaultTextUI()
Deprecated.
Method Summary
Methods inherited from class javax.swing.plaf.basic.BasicTextUI
create, create, createCaret, createHighlighter, createKeymap, damageRange, damageRange, getComponent, getEditorKit, getKeymapName, getMaximumSize, getMinimumSize, getNextVisualPositionFrom, getPreferredSize, getPropertyPrefix, getRootView, getToolTipText, getVisibleEditorRect, installDefaults, installKeyboardActions, installListeners, installUI, modelChanged, modelToView, modelToView, paint, paintBackground, paintSafely, propertyChange, setView, uninstallDefaults, uninstallKeyboardActions, uninstallListeners, uninstallUI, update, viewToModel, viewToModel
Methods inherited from class javax.swing.plaf.ComponentUI
contains, createUI, getAccessibleChild, getAccessibleChildrenCount, getBaseline, getBaselineResizeBehavior
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultTextUI

public DefaultTextUI()
Deprecated.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Document

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface Document

All Known Subinterfaces:
StyledDocument
All Known Implementing Classes:
AbstractDocument, DefaultStyledDocument, HTMLDocument, PlainDocument
public interface Document

The Document is a container for text that serves as the model for swing text components. The goal for this interface is to scale from very simple needs (a plain text textfield) to complex needs (an HTML or XML document, for example).

Content

At the simplest level, text can be modeled as a linear sequence of characters. To support internationalization, the Swing text model uses unicode characters. The sequence of characters displayed in a text component is generally referred to as the component's content.

To refer to locations within the sequence, the coordinates used are the location between two characters. As the diagram below shows, a location in a text document can be referred to as a position, or an offset. This position is zero-based.

The following text describes this graphic.

In the example, if the content of a document is the sequence "The quick brown fox," as shown in the preceding diagram, the location just before the word "The" is 0, and the location after the word "The" and before the whitespace that follows it is 3. The entire sequence of characters in the sequence "The" is called a range.

The following methods give access to the character data that makes up the content.

  • getLength()
  • getText(int, int)
  • getText(int, int, Segment)

Structure

Text is rarely represented simply as featureless content. Rather, text typically has some sort of structure associated with it. Exactly what structure is modeled is up to a particular Document implementation. It might be as simple as no structure (i.e. a simple text field), or it might be something like diagram below.

Chapter->Paragraph">

The unit of structure (i.e. a node of the tree) is referred to by the Element interface. Each Element can be tagged with a set of attributes. These attributes (name/value pairs) are defined by the AttributeSet interface.

The following methods give access to the document structure.

  • getDefaultRootElement
  • getRootElements

Mutations

All documents need to be able to add and remove simple text. Typically, text is inserted and removed via gestures from a keyboard or a mouse. What effect the insertion or removal has upon the document structure is entirely up to the implementation of the document.

The following methods are related to mutation of the document content:

  • insertString(int, String, AttributeSet)
  • remove(int, int)
  • createPosition(int)

Notification

Mutations to the Document must be communicated to interested observers. The notification of change follows the event model guidelines that are specified for JavaBeans. In the JavaBeans event model, once an event notification is dispatched, all listeners must be notified before any further mutations occur to the source of the event. Further, order of delivery is not guaranteed.

Notification is provided as two separate events, DocumentEvent, and UndoableEditEvent. If a mutation is made to a Document through its api, a DocumentEvent will be sent to all of the registered DocumentListeners. If the Document implementation supports undo/redo capabilities, an UndoableEditEvent will be sent to all of the registered UndoableEditListeners. If an undoable edit is undone, a DocumentEvent should be fired from the Document to indicate it has changed again. In this case however, there should be no UndoableEditEvent generated since that edit is actually the source of the change rather than a mutation to the Document made through its api.

The preceeding text describes this graphic.

Referring to the above diagram, suppose that the component shown on the left mutates the document object represented by the blue rectangle. The document responds by dispatching a DocumentEvent to both component views and sends an UndoableEditEvent to the listening logic, which maintains a history buffer.

Now suppose that the component shown on the right mutates the same document. Again, the document dispatches a DocumentEvent to both component views and sends an UndoableEditEvent to the listening logic that is maintaining the history buffer.

If the history buffer is then rolled back (i.e. the last UndoableEdit undone), a DocumentEvent is sent to both views, causing both of them to reflect the undone mutation to the document (that is, the removal of the right component's mutation). If the history buffer again rolls back another change, another DocumentEvent is sent to both views, causing them to reflect the undone mutation to the document -- that is, the removal of the left component's mutation.

The methods related to observing mutations to the document are:

  • addDocumentListener(DocumentListener)
  • removeDocumentListener(DocumentListener)
  • addUndoableEditListener(UndoableEditListener)
  • removeUndoableEditListener(UndoableEditListener)

Properties

Document implementations will generally have some set of properties associated with them at runtime. Two well known properties are the StreamDescriptionProperty, which can be used to describe where the Document came from, and the TitleProperty, which can be used to name the Document. The methods related to the properties are:

  • getProperty(Object)
  • putProperty(Object, Object)

For more information on the Document class, see The Swing Connection and most particularly the article, The Element Interface.

See Also:
DocumentEvent, DocumentListener, UndoableEditEvent, UndoableEditListener, Element, Position, AttributeSet

Field Summary
static String | StreamDescriptionProperty The property name for the description of the stream used to initialize the document.
static String | TitleProperty The property name for the title of the document, if there is one.
Method Summary
void | addDocumentListener(DocumentListener listener) Registers the given observer to begin receiving notifications when changes are made to the document.
void | addUndoableEditListener(UndoableEditListener listener) Registers the given observer to begin receiving notifications when undoable edits are made to the document.
Position | createPosition(int offs) This method allows an application to mark a place in a sequence of character content.
Element | getDefaultRootElement() Returns the root element that views should be based upon, unless some other mechanism for assigning views to element structures is provided.
Position | getEndPosition() Returns a position that represents the end of the document.
int | getLength() Returns number of characters of content currently in the document.
Object | getProperty(Object key) Gets the properties associated with the document.
Element[] | getRootElements() Returns all of the root elements that are defined.
Position | getStartPosition() Returns a position that represents the start of the document.
String | getText(int offset, int length) Fetches the text contained within the given portion of the document.
void | getText(int offset, int length, Segment txt) Fetches the text contained within the given portion of the document.
void | insertString(int offset, String str, AttributeSet a) Inserts a string of content.
void | putProperty(Object key, Object value) Associates a property with the document.
void | remove(int offs, int len) Removes a portion of the content of the document.
void | removeDocumentListener(DocumentListener listener) Unregisters the given observer from the notification list so it will no longer receive change updates.
void | removeUndoableEditListener(UndoableEditListener listener) Unregisters the given observer from the notification list so it will no longer receive updates.
void | render(Runnable r) Allows the model to be safely rendered in the presence of concurrency, if the model supports being updated asynchronously.

Field Detail

StreamDescriptionProperty

static final String StreamDescriptionProperty
The property name for the description of the stream used to initialize the document. This should be used if the document was initialized from a stream and anything is known about the stream.

See Also:
Constant Field Values

TitleProperty

static final String TitleProperty
The property name for the title of the document, if there is one.

See Also:
Constant Field Values
Method Detail

getLength

int getLength()
Returns number of characters of content currently in the document.

Returns:
number of characters >= 0

addDocumentListener

void addDocumentListener(DocumentListener listener)
Registers the given observer to begin receiving notifications when changes are made to the document.

Parameters:
listener - the observer to register
See Also:
removeDocumentListener(javax.swing.event.DocumentListener)

removeDocumentListener

void removeDocumentListener(DocumentListener listener)
Unregisters the given observer from the notification list so it will no longer receive change updates.

Parameters:
listener - the observer to register
See Also:
addDocumentListener(javax.swing.event.DocumentListener)

addUndoableEditListener

void addUndoableEditListener(UndoableEditListener listener)
Registers the given observer to begin receiving notifications when undoable edits are made to the document.

Parameters:
listener - the observer to register
See Also:
UndoableEditEvent

removeUndoableEditListener

void removeUndoableEditListener(UndoableEditListener listener)
Unregisters the given observer from the notification list so it will no longer receive updates.

Parameters:
listener - the observer to register
See Also:
UndoableEditEvent

getProperty

Object getProperty(Object key)
Gets the properties associated with the document.

Parameters:
key - a non-null property key
Returns:
the properties
See Also:
putProperty(Object, Object)

putProperty

void putProperty(Object key,
                 Object value)
Associates a property with the document. Two standard property keys provided are: StreamDescriptionProperty and TitleProperty. Other properties, such as author, may also be defined.

Parameters:
key - the non-null property key
value - the property value
See Also:
getProperty(Object)

remove

void remove(int offs,
            int len)
            throws BadLocationException
Removes a portion of the content of the document. This will cause a DocumentEvent of type DocumentEvent.EventType.REMOVE to be sent to the registered DocumentListeners, unless an exception is thrown. The notification will be sent to the listeners by calling the removeUpdate method on the DocumentListeners.

To ensure reasonable behavior in the face of concurrency, the event is dispatched after the mutation has occurred. This means that by the time a notification of removal is dispatched, the document has already been updated and any marks created by createPosition have already changed. For a removal, the end of the removal range is collapsed down to the start of the range, and any marks in the removal range are collapsed down to the start of the range.

Diagram shows removal of 'quick' from 'The quick brown fox.'

If the Document structure changed as result of the removal, the details of what Elements were inserted and removed in response to the change will also be contained in the generated DocumentEvent. It is up to the implementation of a Document to decide how the structure should change in response to a remove.

If the Document supports undo/redo, an UndoableEditEvent will also be generated.

Parameters:
offs - the offset from the beginning >= 0
len - the number of characters to remove >= 0
Throws:
BadLocationException - some portion of the removal range was not a valid part of the document. The location in the exception is the first bad position encountered.
See Also:
DocumentEvent, DocumentListener, UndoableEditEvent, UndoableEditListener

insertString

void insertString(int offset,
                  String str,
                  AttributeSet a)
                  throws BadLocationException
Inserts a string of content. This will cause a DocumentEvent of type DocumentEvent.EventType.INSERT to be sent to the registered DocumentListers, unless an exception is thrown. The DocumentEvent will be delivered by calling the insertUpdate method on the DocumentListener. The offset and length of the generated DocumentEvent will indicate what change was actually made to the Document.

Diagram shows insertion of 'quick' in 'The quick brown fox'

If the Document structure changed as result of the insertion, the details of what Elements were inserted and removed in response to the change will also be contained in the generated DocumentEvent. It is up to the implementation of a Document to decide how the structure should change in response to an insertion.

If the Document supports undo/redo, an UndoableEditEvent will also be generated.

Parameters:
offset - the offset into the document to insert the content >= 0. All positions that track change at or after the given location will move.
str - the string to insert
a - the attributes to associate with the inserted content. This may be null if there are no attributes.
Throws:
BadLocationException - the given insert position is not a valid position within the document
See Also:
DocumentEvent, DocumentListener, UndoableEditEvent, UndoableEditListener

getText

String getText(int offset,
               int length)
               throws BadLocationException
Fetches the text contained within the given portion of the document.

Parameters:
offset - the offset into the document representing the desired start of the text >= 0
length - the length of the desired string >= 0
Returns:
the text, in a String of length >= 0
Throws:
BadLocationException - some portion of the given range was not a valid part of the document. The location in the exception is the first bad position encountered.

getText

void getText(int offset,
             int length,
             Segment txt)
             throws BadLocationException
Fetches the text contained within the given portion of the document.

If the partialReturn property on the txt parameter is false, the data returned in the Segment will be the entire length requested and may or may not be a copy depending upon how the data was stored. If the partialReturn property is true, only the amount of text that can be returned without creating a copy is returned. Using partial returns will give better performance for situations where large parts of the document are being scanned. The following is an example of using the partial return to access the entire document:

   int nleft = doc.getDocumentLength();
   Segment text = new Segment();
   int offs = 0;
   text.setPartialReturn(true);
   while (nleft > 0) {
       doc.getText(offs, nleft, text);
       // do someting with text
       nleft -= text.count;
       offs += text.count;
   }

Parameters:
offset - the offset into the document representing the desired start of the text >= 0
length - the length of the desired string >= 0
txt - the Segment object to return the text in
Throws:
BadLocationException - Some portion of the given range was not a valid part of the document. The location in the exception is the first bad position encountered.

getStartPosition

Position getStartPosition()
Returns a position that represents the start of the document. The position returned can be counted on to track change and stay located at the beginning of the document.

Returns:
the position

getEndPosition

Position getEndPosition()
Returns a position that represents the end of the document. The position returned can be counted on to track change and stay located at the end of the document.

Returns:
the position

createPosition

Position createPosition(int offs)
                        throws BadLocationException
This method allows an application to mark a place in a sequence of character content. This mark can then be used to tracks change as insertions and removals are made in the content. The policy is that insertions always occur prior to the current position (the most common case) unless the insertion location is zero, in which case the insertion is forced to a position that follows the original position.

Parameters:
offs - the offset from the start of the document >= 0
Returns:
the position
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document

getRootElements

Element[] getRootElements()
Returns all of the root elements that are defined.

Typically there will be only one document structure, but the interface supports building an arbitrary number of structural projections over the text data. The document can have multiple root elements to support multiple document structures. Some examples might be:

  • Text direction.
  • Lexical token streams.
  • Parse trees.
  • Conversions to formats other than the native format.
  • Modification specifications.
  • Annotations.

Returns:
the root element

getDefaultRootElement

Element getDefaultRootElement()
Returns the root element that views should be based upon, unless some other mechanism for assigning views to element structures is provided.

Returns:
the root element

render

void render(Runnable r)
Allows the model to be safely rendered in the presence of concurrency, if the model supports being updated asynchronously. The given runnable will be executed in a way that allows it to safely read the model with no changes while the runnable is being executed. The runnable itself may not make any mutations.

Parameters:
r - a Runnable used to render the model
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocumentFilter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DocumentFilter

java.lang.Object
    extended by  javax.swing.text.DocumentFilter

public class DocumentFilter
extends Object

DocumentFilter, as the name implies, is a filter for the Document mutation methods. When a Document containing a DocumentFilter is modified (either through insert or remove), it forwards the appropriate method invocation to the DocumentFilter. The default implementation allows the modification to occur. Subclasses can filter the modifications by conditionally invoking methods on the superclass, or invoking the necessary methods on the passed in FilterBypass. Subclasses should NOT call back into the Document for the modification instead call into the superclass or the FilterBypass.

When remove or insertString is invoked on the DocumentFilter, the DocumentFilter may callback into the FilterBypass multiple times, or for different regions, but it should not callback into the FilterBypass after returning from the remove or insertString method.

Since:
1.4
See Also:
Document

Nested Class Summary
static class DocumentFilter.FilterBypass
Used as a way to circumvent calling back into the Document to change it.
Constructor Summary
DocumentFilter()
Method Summary
void | insertString(DocumentFilter.FilterBypass fb, int offset, String string, AttributeSet attr) Invoked prior to insertion of text into the specified Document.
void | remove(DocumentFilter.FilterBypass fb, int offset, int length) Invoked prior to removal of the specified region in the specified Document.
void | replace(DocumentFilter.FilterBypass fb, int offset, int length, String text, AttributeSet attrs) Invoked prior to replacing a region of text in the specified Document.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DocumentFilter

public DocumentFilter()
Method Detail

remove

public void remove(DocumentFilter.FilterBypass fb,
                   int offset,
                   int length)
            throws BadLocationException
Invoked prior to removal of the specified region in the specified Document. Subclasses that want to conditionally allow removal should override this and only call supers implementation as necessary, or call directly into the FilterBypass as necessary.

Parameters:
fb - FilterBypass that can be used to mutate Document
offset - the offset from the beginning >= 0
length - the number of characters to remove >= 0
Throws:
BadLocationException - some portion of the removal range was not a valid part of the document. The location in the exception is the first bad position encountered.

insertString

public void insertString(DocumentFilter.FilterBypass fb,
                         int offset,
                         String string,
                         AttributeSet attr)
                  throws BadLocationException
Invoked prior to insertion of text into the specified Document. Subclasses that want to conditionally allow insertion should override this and only call supers implementation as necessary, or call directly into the FilterBypass.

Parameters:
fb - FilterBypass that can be used to mutate Document
offset - the offset into the document to insert the content >= 0. All positions that track change at or after the given location will move.
string - the string to insert
attr - the attributes to associate with the inserted content. This may be null if there are no attributes.
Throws:
BadLocationException - the given insert position is not a valid position within the document

replace

public void replace(DocumentFilter.FilterBypass fb,
                    int offset,
                    int length,
                    String text,
                    AttributeSet attrs)
             throws BadLocationException
Invoked prior to replacing a region of text in the specified Document. Subclasses that want to conditionally allow replace should override this and only call supers implementation as necessary, or call directly into the FilterBypass.

Parameters:
fb - FilterBypass that can be used to mutate Document
offset - Location in Document
length - Length of text to delete
text - Text to insert, null indicates no text to insert
attrs - AttributeSet indicating attributes of inserted text, null is legal.
Throws:
BadLocationException - the given insert position is not a valid position within the document
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocumentFilter.FilterBypass

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class DocumentFilter.FilterBypass

java.lang.Object
    extended by  javax.swing.text.DocumentFilter.FilterBypass
Enclosing class:
DocumentFilter
public abstract static class DocumentFilter.FilterBypass
extends Object

Used as a way to circumvent calling back into the Document to change it. Document implementations that wish to support a DocumentFilter must provide an implementation that will not callback into the DocumentFilter when the following methods are invoked from the DocumentFilter.

Since:
1.4

Constructor Summary
DocumentFilter.FilterBypass()
Method Summary
abstract Document | getDocument() Returns the Document the mutation is occuring on.
abstract void | insertString(int offset, String string, AttributeSet attr) Inserts the specified text, bypassing the DocumentFilter.
abstract void | remove(int offset, int length) Removes the specified region of text, bypassing the DocumentFilter.
abstract void | replace(int offset, int length, String string, AttributeSet attrs) Deletes the region of text from offset to offset + length, and replaces it with text.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DocumentFilter.FilterBypass

public DocumentFilter.FilterBypass()
Method Detail

getDocument

public abstract Document getDocument()
Returns the Document the mutation is occuring on.

Returns:
Document that remove/insertString will operate on

remove

public abstract void remove(int offset,
                            int length)
                     throws BadLocationException
Removes the specified region of text, bypassing the DocumentFilter.

Parameters:
offset - the offset from the beginning >= 0
length - the number of characters to remove >= 0
Throws:
BadLocationException - some portion of the removal range was not a valid part of the document. The location in the exception is the first bad position encountered.

insertString

public abstract void insertString(int offset,
                                  String string,
                                  AttributeSet attr)
                           throws BadLocationException
Inserts the specified text, bypassing the DocumentFilter.

Parameters:
offset - the offset into the document to insert the content >= 0. All positions that track change at or after the given location will move.
string - the string to insert
attr - the attributes to associate with the inserted content. This may be null if there are no attributes.
Throws:
BadLocationException - the given insert position is not a valid position within the document

replace

public abstract void replace(int offset,
                             int length,
                             String string,
                             AttributeSet attrs)
                      throws BadLocationException
Deletes the region of text from offset to offset + length, and replaces it with text.

Parameters:
offset - Location in Document
length - Length of text to delete
string - Text to insert, null indicates no text to insert
attrs - AttributeSet indicating attributes of inserted text, null is legal.
Throws:
BadLocationException - the given insert is not a valid position within the document
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EditorKit

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class EditorKit

java.lang.Object
    extended by  javax.swing.text.EditorKit
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
DefaultEditorKit
public abstract class EditorKit
extends Object
implements Cloneable, Serializable

Establishes the set of things needed by a text component to be a reasonably functioning editor for some type of text content. The EditorKit acts as a factory for some kind of policy. For example, an implementation of html and rtf can be provided that is replaceable with other implementations.

A kit can safely store editing state as an instance of the kit will be dedicated to a text component. New kits will normally be created by cloning a prototype kit. The kit will have it's setComponent method called to establish it's relationship with a JTextComponent.

Constructor Summary
EditorKit()
Construct an EditorKit.
Method Summary
Object | clone() Creates a copy of the editor kit.
abstract Caret | createCaret() Fetches a caret that can navigate through views produced by the associated ViewFactory.
abstract Document | createDefaultDocument() Creates an uninitialized text storage model that is appropriate for this type of editor.
void | deinstall(JEditorPane c) Called when the kit is being removed from the JEditorPane.
abstract Action[] | getActions() Fetches the set of commands that can be used on a text component that is using a model and view produced by this kit.
abstract String | getContentType() Gets the MIME type of the data that this kit represents support for.
abstract ViewFactory | getViewFactory() Fetches a factory that is suitable for producing views of any models that are produced by this kit.
void | install(JEditorPane c) Called when the kit is being installed into the a JEditorPane.
abstract void | read(InputStream in, Document doc, int pos) Inserts content from the given stream which is expected to be in a format appropriate for this kind of content handler.
abstract void | read(Reader in, Document doc, int pos) Inserts content from the given stream which is expected to be in a format appropriate for this kind of content handler.
abstract void | write(OutputStream out, Document doc, int pos, int len) Writes content from a document to the given stream in a format appropriate for this kind of content handler.
abstract void | write(Writer out, Document doc, int pos, int len) Writes content from a document to the given stream in a format appropriate for this kind of content handler.
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EditorKit

public EditorKit()
Construct an EditorKit.

Method Detail

clone

public Object clone()
Creates a copy of the editor kit. This is implemented to use Object.clone. If the kit cannot be cloned, null is returned.

Overrides:
clone in class Object
Returns:
the copy
See Also:
Cloneable

install

public void install(JEditorPane c)
Called when the kit is being installed into the a JEditorPane.

Parameters:
c - the JEditorPane

deinstall

public void deinstall(JEditorPane c)
Called when the kit is being removed from the JEditorPane. This is used to unregister any listeners that were attached.

Parameters:
c - the JEditorPane

getContentType

public abstract String getContentType()
Gets the MIME type of the data that this kit represents support for.

Returns:
the type

getViewFactory

public abstract ViewFactory getViewFactory()
Fetches a factory that is suitable for producing views of any models that are produced by this kit.

Returns:
the factory

getActions

public abstract Action[] getActions()
Fetches the set of commands that can be used on a text component that is using a model and view produced by this kit.

Returns:
the set of actions

createCaret

public abstract Caret createCaret()
Fetches a caret that can navigate through views produced by the associated ViewFactory.

Returns:
the caret

createDefaultDocument

public abstract Document createDefaultDocument()
Creates an uninitialized text storage model that is appropriate for this type of editor.

Returns:
the model

read

public abstract void read(InputStream in,
                          Document doc,
                          int pos)
                   throws IOException,
                          BadLocationException
Inserts content from the given stream which is expected to be in a format appropriate for this kind of content handler.

Parameters:
in - The stream to read from
doc - The destination for the insertion.
pos - The location in the document to place the content >= 0.
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

write

public abstract void write(OutputStream out,
                           Document doc,
                           int pos,
                           int len)
                    throws IOException,
                           BadLocationException
Writes content from a document to the given stream in a format appropriate for this kind of content handler.

Parameters:
out - The stream to write to
doc - The source for the write.
pos - The location in the document to fetch the content from >= 0.
len - The amount to write out >= 0.
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

read

public abstract void read(Reader in,
                          Document doc,
                          int pos)
                   throws IOException,
                          BadLocationException
Inserts content from the given stream which is expected to be in a format appropriate for this kind of content handler.

Since actual text editing is unicode based, this would generally be the preferred way to read in the data. Some types of content are stored in an 8-bit form however, and will favor the InputStream.

Parameters:
in - The stream to read from
doc - The destination for the insertion.
pos - The location in the document to place the content >= 0.
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

write

public abstract void write(Writer out,
                           Document doc,
                           int pos,
                           int len)
                    throws IOException,
                           BadLocationException
Writes content from a document to the given stream in a format appropriate for this kind of content handler.

Since actual text editing is unicode based, this would generally be the preferred way to write the data. Some types of content are stored in an 8-bit form however, and will favor the OutputStream.

Parameters:
out - The stream to write to
doc - The source for the write.
pos - The location in the document to fetch the content >= 0.
len - The amount to write out >= 0.
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Element

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface Element

All Known Implementing Classes:
AbstractDocument.AbstractElement, AbstractDocument.BranchElement, AbstractDocument.LeafElement, DefaultStyledDocument.SectionElement, HTMLDocument.BlockElement, HTMLDocument.RunElement
public interface Element

Interface to describe a structural piece of a document. It is intended to capture the spirit of an SGML element.

Method Summary
AttributeSet | getAttributes() Fetches the collection of attributes this element contains.
Document | getDocument() Fetches the document associated with this element.
Element | getElement(int index) Fetches the child element at the given index.
int | getElementCount() Gets the number of child elements contained by this element.
int | getElementIndex(int offset) Gets the child element index closest to the given offset.
int | getEndOffset() Fetches the offset from the beginning of the document that this element ends at.
String | getName() Fetches the name of the element.
Element | getParentElement() Fetches the parent element.
int | getStartOffset() Fetches the offset from the beginning of the document that this element begins at.
boolean | isLeaf() Is this element a leaf element? An element that may have children, even if it currently has no children, would return false.

Method Detail

getDocument

Document getDocument()
Fetches the document associated with this element.

Returns:
the document

getParentElement

Element getParentElement()
Fetches the parent element. If the element is a root level element returns null.

Returns:
the parent element

getName

String getName()
Fetches the name of the element. If the element is used to represent some type of structure, this would be the type name.

Returns:
the element name

getAttributes

AttributeSet getAttributes()
Fetches the collection of attributes this element contains.

Returns:
the attributes for the element

getStartOffset

int getStartOffset()
Fetches the offset from the beginning of the document that this element begins at. If this element has children, this will be the offset of the first child. As a document position, there is an implied forward bias.

Returns:
the starting offset >= 0 and < getEndOffset();
See Also:
Document, AbstractDocument

getEndOffset

int getEndOffset()
Fetches the offset from the beginning of the document that this element ends at. If this element has children, this will be the end offset of the last child. As a document position, there is an implied backward bias.

All the default Document implementations descend from AbstractDocument. AbstractDocument models an implied break at the end of the document. As a result of this, it is possible for this to return a value greater than the length of the document.

Returns:
the ending offset > getStartOffset() and <= getDocument().getLength()="getDocument().getLength()" +="+" 1See Also:
Document, AbstractDocument

getElementIndex

int getElementIndex(int offset)
Gets the child element index closest to the given offset. The offset is specified relative to the beginning of the document. Returns -1 if the Element is a leaf, otherwise returns the index of the Element that best represents the given location. Returns 0 if the location is less than the start offset. Returns getElementCount() - 1 if the location is greater than or equal to the end offset.

Parameters:
offset - the specified offset >= 0
Returns:
the element index >= 0

getElementCount

int getElementCount()
Gets the number of child elements contained by this element. If this element is a leaf, a count of zero is returned.

Returns:
the number of child elements >= 0

getElement

Element getElement(int index)
Fetches the child element at the given index.

Parameters:
index - the specified index >= 0
Returns:
the child element

isLeaf

boolean isLeaf()
Is this element a leaf element? An element that may have children, even if it currently has no children, would return false.

Returns:
true if a leaf element else false
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ElementIterator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class ElementIterator

java.lang.Object
    extended by  javax.swing.text.ElementIterator
All Implemented Interfaces:
Cloneable
public class ElementIterator
extends Object
implements Cloneable

ElementIterator, as the name suggests, iteratates over the Element tree. The constructor can be invoked with either Document or an Element as an argument. If the constructor is invoked with a Document as an argument then the root of the iteration is the return value of document.getDefaultRootElement(). The iteration happens in a depth-first manner. In terms of how boundary conditions are handled: a) if next() is called before first() or current(), the root will be returned. b) next() returns null to indicate the end of the list. c) previous() returns null when the current element is the root or next() has returned null. The ElementIterator does no locking of the Element tree. This means that it does not track any changes. It is the responsibility of the user of this class, to ensure that no changes happen during element iteration. Simple usage example: public void iterate() { ElementIterator it = new ElementIterator(root); Element elem; while (true) { if ((elem = next()) != null) { // process element System.out.println("elem: " + elem.getName()); } else { break; } } }

Constructor Summary
ElementIterator(Document document)
Creates a new ElementIterator.
ElementIterator(Element root)
Creates a new ElementIterator.
Method Summary
Object | clone() Clones the ElementIterator.
Element | current() Fetches the current Element.
int | depth() Fetches the current depth of element tree.
Element | first() Fetches the first element.
Element | next() Fetches the next Element.
Element | previous() Fetches the previous Element.
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ElementIterator

public ElementIterator(Document document)
Creates a new ElementIterator. The root element is taken to get the default root element of the document.

Parameters:
document - a Document.

ElementIterator

public ElementIterator(Element root)
Creates a new ElementIterator.

Parameters:
root - the root Element.
Method Detail

clone

public Object clone()
Clones the ElementIterator.

Overrides:
clone in class Object
Returns:
a cloned ElementIterator Object.
See Also:
Cloneable

first

public Element first()
Fetches the first element.

Returns:
an Element.

depth

public int depth()
Fetches the current depth of element tree.

Returns:
the depth.

current

public Element current()
Fetches the current Element.

Returns:
element on top of the stack or null if the root element is null

next

public Element next()
Fetches the next Element. The strategy used to locate the next element is a depth-first search.

Returns:
the next element or null at the end of the list.

previous

public Element previous()
Fetches the previous Element. If howver the current element is the last element, or the current element is null, then null is returned.

Returns:
previous Element if available
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FieldView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class FieldView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.PlainView
            extended by  javax.swing.text.FieldView
All Implemented Interfaces:
SwingConstants, TabExpander
Direct Known Subclasses:
PasswordView
public class FieldView
extends PlainView

Extends the multi-line plain text view to be suitable for a single-line editor view. If the view is allocated extra space, the field must adjust for it. If the hosting component is a JTextField, this view will manage the ranges of the associated BoundedRangeModel and will adjust the horizontal allocation to match the current visibility settings of the JTextField.

See Also:
View

Field Summary
Fields inherited from class javax.swing.text.PlainView
metrics
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
FieldView(Element elem)
Constructs a new FieldView wrapped on an element.
Method Summary
protected Shape | adjustAllocation(Shape a) Adjusts the allocation given to the view to be a suitable allocation for a text field.
protected FontMetrics | getFontMetrics() Fetches the font metrics associated with the component hosting this view.
float | getPreferredSpan(int axis) Determines the preferred span for this view along an axis.
int | getResizeWeight(int axis) Determines the resizability of the view along the given axis.
void | insertUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
Shape | modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
void | paint(Graphics g, Shape a) Renders using the given rendering surface and area on that surface.
void | removeUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
int | viewToModel(float fx, float fy, Shape a, Position.Bias[] bias) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
Methods inherited from class javax.swing.text.PlainView
changedUpdate, damageLineRange, drawLine, drawSelectedText, drawUnselectedText, getLineBuffer, getTabSize, lineToRect, nextTabStop, setSize, updateDamage, updateMetrics
Methods inherited from class javax.swing.text.View
append, breakView, createFragment, forwardUpdate, forwardUpdateToView, getAlignment, getAttributes, getBreakWeight, getChildAllocation, getContainer, getDocument, getElement, getEndOffset, getGraphics, getMaximumSpan, getMinimumSpan, getNextVisualPositionFrom, getParent, getStartOffset, getToolTipText, getView, getViewCount, getViewFactory, getViewIndex, getViewIndex, insert, isVisible, modelToView, modelToView, preferenceChanged, remove, removeAll, replace, setParent, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FieldView

public FieldView(Element elem)
Constructs a new FieldView wrapped on an element.

Parameters:
elem - the element
Method Detail

getFontMetrics

protected FontMetrics getFontMetrics()
Fetches the font metrics associated with the component hosting this view.

Returns:
the metrics

adjustAllocation

protected Shape adjustAllocation(Shape a)
Adjusts the allocation given to the view to be a suitable allocation for a text field. If the view has been allocated more than the preferred span vertically, the allocation is changed to be centered vertically. Horizontally the view is adjusted according to the horizontal alignment property set on the associated JTextField (if that is the type of the hosting component).

Parameters:
a - the allocation given to the view, which may need to be adjusted.
Returns:
the allocation that the superclass should use.

paint

public void paint(Graphics g,
                  Shape a)
Renders using the given rendering surface and area on that surface. The view may need to do layout and create child views to enable itself to render into the given allocation.

Overrides:
paint in class PlainView
Parameters:
g - the rendering surface to use
a - the allocated region to render into
See Also:
View.paint(java.awt.Graphics, java.awt.Shape)

getPreferredSpan

public float getPreferredSpan(int axis)
Determines the preferred span for this view along an axis.

Overrides:
getPreferredSpan in class PlainView
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned, although there is no guarantee. The parent may choose to resize or break the view.
See Also:
View.getPreferredSpan(int)

getResizeWeight

public int getResizeWeight(int axis)
Determines the resizability of the view along the given axis. A value of 0 or less is not resizable.

Overrides:
getResizeWeight in class View
Parameters:
axis - View.X_AXIS or View.Y_AXIS
Returns:
the weight -> 1 for View.X_AXIS, else 0

modelToView

public Shape modelToView(int pos,
                         Shape a,
                         Position.Bias b)
                  throws BadLocationException
Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.

Overrides:
modelToView in class PlainView
Parameters:
pos - the position to convert >= 0
a - the allocated region to render into
b - the bias toward the previous character or the next character represented by the offset, in case the position is a boundary of two views; b will have one of these values:
  • Position.Bias.Forward
  • Position.Bias.Backward
Returns:
the bounding box of the given position
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
See Also:
View.modelToView(int, java.awt.Shape, javax.swing.text.Position.Bias)

viewToModel

public int viewToModel(float fx,
                       float fy,
                       Shape a,
                       Position.Bias[] bias)
Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Overrides:
viewToModel in class PlainView
Parameters:
fx - the X coordinate >= 0.0f
fy - the Y coordinate >= 0.0f
a - the allocated region to render into
Returns:
the location within the model that best represents the given point in the view
See Also:
View.viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])

insertUpdate

public void insertUpdate(DocumentEvent changes,
                         Shape a,
                         ViewFactory f)
Gives notification that something was inserted into the document in a location that this view is responsible for.

Overrides:
insertUpdate in class PlainView
Parameters:
changes - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

removeUpdate

public void removeUpdate(DocumentEvent changes,
                         Shape a,
                         ViewFactory f)
Gives notification that something was removed from the document in a location that this view is responsible for.

Overrides:
removeUpdate in class PlainView
Parameters:
changes - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FlowView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class FlowView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.CompositeView
            extended by  javax.swing.text.BoxView
                extended by  javax.swing.text.FlowView
All Implemented Interfaces:
SwingConstants
Direct Known Subclasses:
ParagraphView
public abstract class FlowView
extends BoxView

A View that tries to flow it's children into some partially constrained space. This can be used to build things like paragraphs, pages, etc. The flow is made up of the following pieces of functionality.

  • A logical set of child views, which as used as a layout pool from which a physical view is formed.
  • A strategy for translating the logical view to a physical (flowed) view.
  • Constraints for the strategy to work against.
  • A physical structure, that represents the flow. The children of this view are where the pieces of of the logical views are placed to create the flow.

Since:
1.3
See Also:
View

Nested Class Summary
static class FlowView.FlowStrategy
Strategy for maintaining the physical form of the flow.
Field Summary
protected View | layoutPool These are the views that represent the child elements of the element this view represents (The logical view to translate to a physical view).
protected int | layoutSpan Default constraint against which the flow is created against.
protected FlowView.FlowStrategy | strategy The behavior for keeping the flow updated.
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
FlowView(Element elem, int axis)
Constructs a FlowView for the given element.
Method Summary
protected SizeRequirements | calculateMinorAxisRequirements(int axis, SizeRequirements r) Calculate equirements along the minor axis.
void | changedUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
protected abstract View | createRow() Create a View that should be used to hold a a rows worth of children in a flow.
int | getFlowAxis() Fetches the axis along which views should be flowed.
int | getFlowSpan(int index) Fetch the constraining span to flow against for the given child index.
int | getFlowStart(int index) Fetch the location along the flow axis that the flow span will start at.
protected int | getViewIndexAtPosition(int pos) Fetches the child view index representing the given position in the model.
void | insertUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
protected void | layout(int width, int height) Lays out the children.
protected void | loadChildren(ViewFactory f) Loads all of the children to initialize the view.
void | removeUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | setParent(View parent) Sets the parent of the view.
Methods inherited from class javax.swing.text.BoxView
baselineLayout, baselineRequirements, calculateMajorAxisRequirements, childAllocation, flipEastAndWestAtEnds, forwardUpdate, getAlignment, getAxis, getChildAllocation, getHeight, getMaximumSpan, getMinimumSpan, getOffset, getPreferredSpan, getResizeWeight, getSpan, getViewAtPoint, getWidth, isAfter, isAllocationValid, isBefore, isLayoutValid, layoutChanged, layoutMajorAxis, layoutMinorAxis, modelToView, paint, paintChild, preferenceChanged, replace, setAxis, setSize, viewToModel
Methods inherited from class javax.swing.text.CompositeView
getBottomInset, getInsideAllocation, getLeftInset, getNextEastWestVisualPositionFrom, getNextNorthSouthVisualPositionFrom, getNextVisualPositionFrom, getRightInset, getTopInset, getView, getViewAtPosition, getViewCount, getViewIndex, modelToView, setInsets, setParagraphInsets
Methods inherited from class javax.swing.text.View
append, breakView, createFragment, forwardUpdateToView, getAttributes, getBreakWeight, getContainer, getDocument, getElement, getEndOffset, getGraphics, getParent, getStartOffset, getToolTipText, getViewFactory, getViewIndex, insert, isVisible, modelToView, remove, removeAll, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

layoutSpan

protected int layoutSpan
Default constraint against which the flow is created against.

layoutPool

protected View layoutPool
These are the views that represent the child elements of the element this view represents (The logical view to translate to a physical view). These are not directly children of this view. These are either placed into the rows directly or used for the purpose of breaking into smaller chunks, to form the physical view.

strategy

protected FlowView.FlowStrategy strategy
The behavior for keeping the flow updated. By default this is a singleton shared by all instances of FlowView (FlowStrategy is stateless). Subclasses can create an alternative strategy, which might keep state.

Constructor Detail

FlowView

public FlowView(Element elem,
                int axis)
Constructs a FlowView for the given element.

Parameters:
elem - the element that this view is responsible for
axis - may be either View.X_AXIS or View.Y_AXIS
Method Detail

getFlowAxis

public int getFlowAxis()
Fetches the axis along which views should be flowed. By default, this will be the axis orthogonal to the axis along which the flow rows are tiled (the axis of the default flow rows themselves). This is typically used by the FlowStrategy.

getFlowSpan

public int getFlowSpan(int index)
Fetch the constraining span to flow against for the given child index. This is called by the FlowStrategy while it is updating the flow. A flow can be shaped by providing different values for the row constraints. By default, the entire span inside of the insets along the flow axis is returned.

Parameters:
index - the index of the row being updated. This should be a value >= 0 and < getViewCount().
See Also:
getFlowStart(int)

getFlowStart

public int getFlowStart(int index)
Fetch the location along the flow axis that the flow span will start at. This is called by the FlowStrategy while it is updating the flow. A flow can be shaped by providing different values for the row constraints.

Parameters:
index - the index of the row being updated. This should be a value >= 0 and < getViewCount().
See Also:
getFlowSpan(int)

createRow

protected abstract View createRow()
Create a View that should be used to hold a a rows worth of children in a flow. This is called by the FlowStrategy when new children are added or removed (i.e. rows are added or removed) in the process of updating the flow.

loadChildren

protected void loadChildren(ViewFactory f)
Loads all of the children to initialize the view. This is called by the setParent method. This is reimplemented to not load any children directly (as they are created in the process of formatting). If the layoutPool variable is null, an instance of LogicalView is created to represent the logical view that is used in the process of formatting.

Overrides:
loadChildren in class CompositeView
Parameters:
f - the view factory
See Also:
CompositeView.setParent(javax.swing.text.View)

getViewIndexAtPosition

protected int getViewIndexAtPosition(int pos)
Fetches the child view index representing the given position in the model.

Overrides:
getViewIndexAtPosition in class CompositeView
Parameters:
pos - the position >= 0
Returns:
index of the view representing the given position, or -1 if no view represents that position

layout

protected void layout(int width,
                      int height)
Lays out the children. If the span along the flow axis has changed, layout is marked as invalid which which will cause the superclass behavior to recalculate the layout along the box axis. The FlowStrategy.layout method will be called to rebuild the flow rows as appropriate. If the height of this view changes (determined by the perferred size along the box axis), a preferenceChanged is called. Following all of that, the normal box layout of the superclass is performed.

Overrides:
layout in class BoxView
Parameters:
width - the width to lay out against >= 0. This is the width inside of the inset area.
height - the height to lay out against >= 0 This is the height inside of the inset area.

calculateMinorAxisRequirements

protected SizeRequirements calculateMinorAxisRequirements(int axis,
                                                          SizeRequirements r)
Calculate equirements along the minor axis. This is implemented to forward the request to the logical view by calling getMinimumSpan, getPreferredSpan, and getMaximumSpan on it.

Overrides:
calculateMinorAxisRequirements in class BoxView
Parameters:
axis - the axis being studied
r - the SizeRequirements object; if null one will be created
Returns:
the newly initialized SizeRequirements object
See Also:
SizeRequirements

insertUpdate

public void insertUpdate(DocumentEvent changes,
                         Shape a,
                         ViewFactory f)
Gives notification that something was inserted into the document in a location that this view is responsible for.

Overrides:
insertUpdate in class View
Parameters:
changes - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

removeUpdate

public void removeUpdate(DocumentEvent changes,
                         Shape a,
                         ViewFactory f)
Gives notification that something was removed from the document in a location that this view is responsible for.

Overrides:
removeUpdate in class View
Parameters:
changes - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

changedUpdate

public void changedUpdate(DocumentEvent changes,
                          Shape a,
                          ViewFactory f)
Gives notification from the document that attributes were changed in a location that this view is responsible for.

Overrides:
changedUpdate in class View
Parameters:
changes - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

setParent

public void setParent(View parent)
Sets the parent of the view. This is reimplemented to provide the superclass behavior as well as calling the loadChildren method if this view does not already have children. The children should not be loaded in the constructor because the act of setting the parent may cause them to try to search up the hierarchy (to get the hosting Container for example). If this view has children (the view is being moved from one place in the view hierarchy to another), the loadChildren method will not be called.

Overrides:
setParent in class CompositeView
Parameters:
parent - the parent of the view, null if none
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FlowView.FlowStrategy

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class FlowView.FlowStrategy

java.lang.Object
    extended by  javax.swing.text.FlowView.FlowStrategy
Enclosing class:
FlowView
public static class FlowView.FlowStrategy
extends Object

Strategy for maintaining the physical form of the flow. The default implementation is completely stateless, and recalculates the entire flow if the layout is invalid on the given FlowView. Alternative strategies can be implemented by subclassing, and might perform incrementatal repair to the layout or alternative breaking behavior.

Since:
1.3

Constructor Summary
FlowView.FlowStrategy()
Method Summary
protected void | adjustRow(FlowView fv, int rowIndex, int desiredSpan, int x) Adjusts the given row if possible to fit within the layout span.
void | changedUpdate(FlowView fv, DocumentEvent e, Rectangle alloc) Gives notification from the document that attributes were changed in a location that this view is responsible for.
protected View | createView(FlowView fv, int startOffset, int spanLeft, int rowIndex) Creates a view that can be used to represent the current piece of the flow.
protected View | getLogicalView(FlowView fv) This method gives flow strategies access to the logical view of the FlowView.
void | insertUpdate(FlowView fv, DocumentEvent e, Rectangle alloc) Gives notification that something was inserted into the document in a location that the given flow view is responsible for.
void | layout(FlowView fv) Update the flow on the given FlowView.
protected int | layoutRow(FlowView fv, int rowIndex, int pos) Creates a row of views that will fit within the layout span of the row.
void | removeUpdate(FlowView fv, DocumentEvent e, Rectangle alloc) Gives notification that something was removed from the document in a location that the given flow view is responsible for.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FlowView.FlowStrategy

public FlowView.FlowStrategy()
Method Detail

insertUpdate

public void insertUpdate(FlowView fv,
                         DocumentEvent e,
                         Rectangle alloc)
Gives notification that something was inserted into the document in a location that the given flow view is responsible for. The strategy should update the appropriate changed region (which depends upon the strategy used for repair).

Parameters:
e - the change information from the associated document
alloc - the current allocation of the view inside of the insets. This value will be null if the view has not yet been displayed.
See Also:
View.insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

removeUpdate

public void removeUpdate(FlowView fv,
                         DocumentEvent e,
                         Rectangle alloc)
Gives notification that something was removed from the document in a location that the given flow view is responsible for.

Parameters:
e - the change information from the associated document
alloc - the current allocation of the view inside of the insets.
See Also:
View.removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

changedUpdate

public void changedUpdate(FlowView fv,
                          DocumentEvent e,
                          Rectangle alloc)
Gives notification from the document that attributes were changed in a location that this view is responsible for.

Parameters:
fv - the FlowView containing the changes
e - the DocumentEvent describing the changes done to the Document
alloc - Bounds of the View
See Also:
View.changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

getLogicalView

protected View getLogicalView(FlowView fv)
This method gives flow strategies access to the logical view of the FlowView.

layout

public void layout(FlowView fv)
Update the flow on the given FlowView. By default, this causes all of the rows (child views) to be rebuilt to match the given constraints for each row. This is called by a FlowView.layout to update the child views in the flow.

Parameters:
fv - the view to reflow

layoutRow

protected int layoutRow(FlowView fv,
                        int rowIndex,
                        int pos)
Creates a row of views that will fit within the layout span of the row. This is called by the layout method. This is implemented to fill the row by repeatedly calling the createView method until the available span has been exhausted, a forced break was encountered, or the createView method returned null. If the remaining span was exhaused, the adjustRow method will be called to perform adjustments to the row to try and make it fit into the given span.

Parameters:
rowIndex - the index of the row to fill in with views. The row is assumed to be empty on entry.
pos - The current position in the children of this views element from which to start.
Returns:
the position to start the next row

adjustRow

protected void adjustRow(FlowView fv,
                         int rowIndex,
                         int desiredSpan,
                         int x)
Adjusts the given row if possible to fit within the layout span. By default this will try to find the highest break weight possible nearest the end of the row. If a forced break is encountered, the break will be positioned there.

Parameters:
rowIndex - the row to adjust to the current layout span.
desiredSpan - the current layout span >= 0
x - the location r starts at.

createView

protected View createView(FlowView fv,
                          int startOffset,
                          int spanLeft,
                          int rowIndex)
Creates a view that can be used to represent the current piece of the flow. This can be either an entire view from the logical view, or a fragment of the logical view.

Parameters:
fv - the view holding the flow
startOffset - the start location for the view being created
spanLeft - the about of span left to fill in the row
rowIndex - the row the view will be placed into
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


GapContent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class GapContent

java.lang.Object
    extended by  javax.swing.text.GapContent
All Implemented Interfaces:
Serializable, AbstractDocument.Content
public class GapContent
extends Object
implements AbstractDocument.Content, Serializable

An implementation of the AbstractDocument.Content interface implemented using a gapped buffer similar to that used by emacs. The underlying storage is a array of unicode characters with a gap somewhere. The gap is moved to the location of changes to take advantage of common behavior where most changes are in the same location. Changes that occur at a gap boundary are generally cheap and moving the gap is generally cheaper than moving the array contents directly to accomodate the change.

The positions tracking change are also generally cheap to maintain. The Position implementations (marks) store the array index and can easily calculate the sequential position from the current gap location. Changes only require update to the the marks between the old and new gap boundaries when the gap is moved, so generally updating the marks is pretty cheap. The marks are stored sorted so they can be located quickly with a binary search. This increases the cost of adding a mark, and decreases the cost of keeping the mark updated.

Constructor Summary
GapContent()
Creates a new GapContent object.
GapContent(int initialLength)
Creates a new GapContent object, with the initial size specified.
Method Summary
protected Object | allocateArray(int len) Allocate an array to store items of the type appropriate (which is determined by the subclass).
Position | createPosition(int offset) Creates a position within the content that will track change as the content is mutated.
protected Object | getArray() Access to the array.
protected int | getArrayLength() Get the length of the allocated array.
void | getChars(int where, int len, Segment chars) Retrieves a portion of the content.
protected int | getGapEnd() Access to the end of the gap.
protected int | getGapStart() Access to the start of the gap.
protected Vector | getPositionsInRange(Vector v, int offset, int length) Returns a Vector containing instances of UndoPosRef for the Positions in the range offset to offset + length.
String | getString(int where, int len) Retrieves a portion of the content.
UndoableEdit | insertString(int where, String str) Inserts a string into the content.
int | length() Returns the length of the content.
UndoableEdit | remove(int where, int nitems) Removes part of the content.
protected void | replace(int position, int rmSize, Object addItems, int addSize) Replace the given logical position in the storage with the given new items.
protected void | resetMarksAtZero() Resets all the marks that have an offset of 0 to have an index of zero as well.
protected void | shiftEnd(int newSize) Make the gap bigger, moving any necessary data and updating the appropriate marks
protected void | shiftGap(int newGapStart) Move the start of the gap to a new location, without changing the size of the gap.
protected void | shiftGapEndUp(int newGapEnd) Adjust the gap end upward.
protected void | shiftGapStartDown(int newGapStart) Adjust the gap end downward.
protected void | updateUndoPositions(Vector positions, int offset, int length) Resets the location for all the UndoPosRef instances in positions.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GapContent

public GapContent()
Creates a new GapContent object. Initial size defaults to 10.

GapContent

public GapContent(int initialLength)
Creates a new GapContent object, with the initial size specified. The initial size will not be allowed to go below 2, to give room for the implied break and the gap.

Parameters:
initialLength - the initial size
Method Detail

allocateArray

protected Object allocateArray(int len)
Allocate an array to store items of the type appropriate (which is determined by the subclass).

getArrayLength

protected int getArrayLength()
Get the length of the allocated array.

length

public int length()
Returns the length of the content.

Specified by:
length in interface AbstractDocument.Content
Returns:
the length >= 1
See Also:
AbstractDocument.Content.length()

insertString

public UndoableEdit insertString(int where,
                                 String str)
                          throws BadLocationException
Inserts a string into the content.

Specified by:
insertString in interface AbstractDocument.Content
Parameters:
where - the starting position >= 0, < length()
str - the non-null string to insert
Returns:
an UndoableEdit object for undoing
Throws:
BadLocationException - if the specified position is invalid
See Also:
AbstractDocument.Content.insertString(int, java.lang.String)

remove

public UndoableEdit remove(int where,
                           int nitems)
                    throws BadLocationException
Removes part of the content.

Specified by:
remove in interface AbstractDocument.Content
Parameters:
where - the starting position >= 0, where + nitems < length()
nitems - the number of characters to remove >= 0
Returns:
an UndoableEdit object for undoing
Throws:
BadLocationException - if the specified position is invalid
See Also:
AbstractDocument.Content.remove(int, int)

getString

public String getString(int where,
                        int len)
                 throws BadLocationException
Retrieves a portion of the content.

Specified by:
getString in interface AbstractDocument.Content
Parameters:
where - the starting position >= 0
len - the length to retrieve >= 0
Returns:
a string representing the content
Throws:
BadLocationException - if the specified position is invalid
See Also:
AbstractDocument.Content.getString(int, int)

getChars

public void getChars(int where,
                     int len,
                     Segment chars)
              throws BadLocationException
Retrieves a portion of the content. If the desired content spans the gap, we copy the content. If the desired content does not span the gap, the actual store is returned to avoid the copy since it is contiguous.

Specified by:
getChars in interface AbstractDocument.Content
Parameters:
where - the starting position >= 0, where + len <= length()len - the number of characters to retrieve >= 0
chars - the Segment object to return the characters in
Throws:
BadLocationException - if the specified position is invalid
See Also:
AbstractDocument.Content.getChars(int, int, javax.swing.text.Segment)

createPosition

public Position createPosition(int offset)
                        throws BadLocationException
Creates a position within the content that will track change as the content is mutated.

Specified by:
createPosition in interface AbstractDocument.Content
Parameters:
offset - the offset to track >= 0
Returns:
the position
Throws:
BadLocationException - if the specified position is invalid

shiftEnd

protected void shiftEnd(int newSize)
Make the gap bigger, moving any necessary data and updating the appropriate marks

shiftGap

protected void shiftGap(int newGapStart)
Move the start of the gap to a new location, without changing the size of the gap. This moves the data in the array and updates the marks accordingly.

resetMarksAtZero

protected void resetMarksAtZero()
Resets all the marks that have an offset of 0 to have an index of zero as well.

shiftGapStartDown

protected void shiftGapStartDown(int newGapStart)
Adjust the gap end downward. This doesn't move any data, but it does update any marks affected by the boundary change. All marks from the old gap start down to the new gap start are squeezed to the end of the gap (their location has been removed).

shiftGapEndUp

protected void shiftGapEndUp(int newGapEnd)
Adjust the gap end upward. This doesn't move any data, but it does update any marks affected by the boundary change. All marks from the old gap end up to the new gap end are squeezed to the end of the gap (their location has been removed).

getPositionsInRange

protected Vector getPositionsInRange(Vector v,
                                     int offset,
                                     int length)
Returns a Vector containing instances of UndoPosRef for the Positions in the range offset to offset + length. If v is not null the matching Positions are placed in there. The vector with the resulting Positions are returned.

Parameters:
v - the Vector to use, with a new one created on null
offset - the starting offset >= 0
length - the length >= 0
Returns:
the set of instances

updateUndoPositions

protected void updateUndoPositions(Vector positions,
                                   int offset,
                                   int length)
Resets the location for all the UndoPosRef instances in positions.

This is meant for internal usage, and is generally not of interest to subclasses.

Parameters:
positions - the UndoPosRef instances to reset

getArray

protected final Object getArray()
Access to the array. The actual type of the array is known only by the subclass.

getGapStart

protected final int getGapStart()
Access to the start of the gap.

getGapEnd

protected final int getGapEnd()
Access to the end of the gap.

replace

protected void replace(int position,
                       int rmSize,
                       Object addItems,
                       int addSize)
Replace the given logical position in the storage with the given new items. This will move the gap to the area being changed if the gap is not currently located at the change location.

Parameters:
position - the location to make the replacement. This is not the location in the underlying storage array, but the location in the contiguous space being modeled.
rmSize - the number of items to remove
addItems - the new items to place in storage.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


GlyphView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class GlyphView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.GlyphView
All Implemented Interfaces:
Cloneable, SwingConstants, TabableView
Direct Known Subclasses:
LabelView
public class GlyphView
extends View
implements TabableView, Cloneable

A GlyphView is a styled chunk of text that represents a view mapped over an element in the text model. This view is generally responsible for displaying text glyphs using character level attributes in some way. An implementation of the GlyphPainter class is used to do the actual rendering and model/view translations. This separates rendering from layout and management of the association with the model.

The view supports breaking for the purpose of formatting. The fragments produced by breaking share the view that has primary responsibility for the element (i.e. they are nested classes and carry only a small amount of state of their own) so they can share its resources.

Since this view represents text that may have tabs embedded in it, it implements the TabableView interface. Tabs will only be expanded if this view is embedded in a container that does tab expansion. ParagraphView is an example of a container that does tab expansion.

Since:
1.3

Nested Class Summary
static class GlyphView.GlyphPainter
A class to perform rendering of the glyphs.
Field Summary
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
GlyphView(Element elem)
Constructs a new view wrapped on an element.
Method Summary
View | breakView(int axis, int p0, float pos, float len) Breaks this view on the given axis at the given length.
void | changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
protected void | checkPainter() Check to see that a glyph painter exists.
protected Object | clone() Creates a shallow copy.
View | createFragment(int p0, int p1) Creates a view that represents a portion of the element.
float | getAlignment(int axis) Determines the desired alignment for this view along an axis.
Color | getBackground() Fetch the background color to use to render the glyphs.
int | getBreakWeight(int axis, float pos, float len) Determines how attractive a break opportunity in this view is.
int | getEndOffset() Fetches the portion of the model that this view is responsible for.
Font | getFont() Fetch the font that the glyphs should be based upon.
Color | getForeground() Fetch the foreground color to use to render the glyphs.
GlyphView.GlyphPainter | getGlyphPainter() Fetch the currently installed glyph painter.
int | getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
float | getPartialSpan(int p0, int p1) Determines the span along the same axis as tab expansion for a portion of the view.
float | getPreferredSpan(int axis) Determines the preferred span for this view along an axis.
int | getStartOffset() Fetches the portion of the model that this view is responsible for.
float | getTabbedSpan(float x, TabExpander e) Determines the desired span when using the given tab expansion implementation.
TabExpander | getTabExpander() Fetch the TabExpander to use if tabs are present in this view.
Segment | getText(int p0, int p1) Fetch a reference to the text that occupies the given range.
void | insertUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
boolean | isStrikeThrough() Determine if the glyphs should have a strikethrough line.
boolean | isSubscript() Determine if the glyphs should be rendered as superscript.
boolean | isSuperscript() Determine if the glyphs should be rendered as subscript.
boolean | isUnderline() Determine if the glyphs should be underlined.
Shape | modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
void | paint(Graphics g, Shape a) Renders a portion of a text style run.
void | removeUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | setGlyphPainter(GlyphView.GlyphPainter p) Sets the painter to use for rendering glyphs.
int | viewToModel(float x, float y, Shape a, Position.Bias[] biasReturn) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
Methods inherited from class javax.swing.text.View
append, forwardUpdate, forwardUpdateToView, getAttributes, getChildAllocation, getContainer, getDocument, getElement, getGraphics, getMaximumSpan, getMinimumSpan, getParent, getResizeWeight, getToolTipText, getView, getViewCount, getViewFactory, getViewIndex, getViewIndex, insert, isVisible, modelToView, modelToView, preferenceChanged, remove, removeAll, replace, setParent, setSize, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GlyphView

public GlyphView(Element elem)
Constructs a new view wrapped on an element.

Parameters:
elem - the element
Method Detail

clone

protected final Object clone()
Creates a shallow copy. This is used by the createFragment and breakView methods.

Overrides:
clone in class Object
Returns:
the copy
See Also:
Cloneable

getGlyphPainter

public GlyphView.GlyphPainter getGlyphPainter()
Fetch the currently installed glyph painter. If a painter has not yet been installed, and a default was not yet needed, null is returned.

setGlyphPainter

public void setGlyphPainter(GlyphView.GlyphPainter p)
Sets the painter to use for rendering glyphs.

getText

public Segment getText(int p0,
                       int p1)
Fetch a reference to the text that occupies the given range. This is normally used by the GlyphPainter to determine what characters it should render glyphs for.

Parameters:
p0 - the starting document offset >= 0
p1 - the ending document offset >= p0
Returns:
the Segment containing the text

getBackground

public Color getBackground()
Fetch the background color to use to render the glyphs. If there is no background color, null should be returned. This is implemented to call StyledDocument.getBackground if the associated document is a styled document, otherwise it returns null.

getForeground

public Color getForeground()
Fetch the foreground color to use to render the glyphs. If there is no foreground color, null should be returned. This is implemented to call StyledDocument.getBackground if the associated document is a StyledDocument. If the associated document is not a StyledDocument, the associated components foreground color is used. If there is no associated component, null is returned.

getFont

public Font getFont()
Fetch the font that the glyphs should be based upon. This is implemented to call StyledDocument.getFont if the associated document is a StyledDocument. If the associated document is not a StyledDocument, the associated components font is used. If there is no associated component, null is returned.

isUnderline

public boolean isUnderline()
Determine if the glyphs should be underlined. If true, an underline should be drawn through the baseline.

isStrikeThrough

public boolean isStrikeThrough()
Determine if the glyphs should have a strikethrough line. If true, a line should be drawn through the center of the glyphs.

isSubscript

public boolean isSubscript()
Determine if the glyphs should be rendered as superscript.

isSuperscript

public boolean isSuperscript()
Determine if the glyphs should be rendered as subscript.

getTabExpander

public TabExpander getTabExpander()
Fetch the TabExpander to use if tabs are present in this view.

checkPainter

protected void checkPainter()
Check to see that a glyph painter exists. If a painter doesn't exist, a default glyph painter will be installed.

getTabbedSpan

public float getTabbedSpan(float x,
                           TabExpander e)
Determines the desired span when using the given tab expansion implementation.

Specified by:
getTabbedSpan in interface TabableView
Parameters:
x - the position the view would be located at for the purpose of tab expansion >= 0.
e - how to expand the tabs when encountered.
Returns:
the desired span >= 0
See Also:
TabableView.getTabbedSpan(float, javax.swing.text.TabExpander)

getPartialSpan

public float getPartialSpan(int p0,
                            int p1)
Determines the span along the same axis as tab expansion for a portion of the view. This is intended for use by the TabExpander for cases where the tab expansion involves aligning the portion of text that doesn't have whitespace relative to the tab stop. There is therefore an assumption that the range given does not contain tabs.

This method can be called while servicing the getTabbedSpan or getPreferredSize. It has to arrange for its own text buffer to make the measurements.

Specified by:
getPartialSpan in interface TabableView
Parameters:
p0 - the starting document offset >= 0
p1 - the ending document offset >= p0
Returns:
the span >= 0

getStartOffset

public int getStartOffset()
Fetches the portion of the model that this view is responsible for.

Overrides:
getStartOffset in class View
Returns:
the starting offset into the model
See Also:
View.getStartOffset()

getEndOffset

public int getEndOffset()
Fetches the portion of the model that this view is responsible for.

Overrides:
getEndOffset in class View
Returns:
the ending offset into the model
See Also:
View.getEndOffset()

paint

public void paint(Graphics g,
                  Shape a)
Renders a portion of a text style run.

Specified by:
paint in class View
Parameters:
g - the rendering surface to use
a - the allocated region to render into

getPreferredSpan

public float getPreferredSpan(int axis)
Determines the preferred span for this view along an axis.

Specified by:
getPreferredSpan in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned, although there is no guarantee. The parent may choose to resize or break the view.
See Also:
View.getPreferredSpan(int)

getAlignment

public float getAlignment(int axis)
Determines the desired alignment for this view along an axis. For the label, the alignment is along the font baseline for the y axis, and the superclasses alignment along the x axis.

Overrides:
getAlignment in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the desired alignment. This should be a value between 0.0 and 1.0 inclusive, where 0 indicates alignment at the origin and 1.0 indicates alignment to the full span away from the origin. An alignment of 0.5 would be the center of the view.

modelToView

public Shape modelToView(int pos,
                         Shape a,
                         Position.Bias b)
                  throws BadLocationException
Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.

Specified by:
modelToView in class View
Parameters:
pos - the position to convert >= 0
a - the allocated region to render into
b - either Position.Bias.Forward or Position.Bias.Backward
Returns:
the bounding box of the given position
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
See Also:
View.modelToView(int, java.awt.Shape, javax.swing.text.Position.Bias)

viewToModel

public int viewToModel(float x,
                       float y,
                       Shape a,
                       Position.Bias[] biasReturn)
Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Specified by:
viewToModel in class View
Parameters:
x - the X coordinate >= 0
y - the Y coordinate >= 0
a - the allocated region to render into
biasReturn - either Position.Bias.Forward or Position.Bias.Backward is returned as the zero-th element of this array
Returns:
the location within the model that best represents the given point of view >= 0
See Also:
View.viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])

getBreakWeight

public int getBreakWeight(int axis,
                          float pos,
                          float len)
Determines how attractive a break opportunity in this view is. This can be used for determining which view is the most attractive to call breakView on in the process of formatting. The higher the weight, the more attractive the break. A value equal to or lower than View.BadBreakWeight should not be considered for a break. A value greater than or equal to View.ForcedBreakWeight should be broken.

This is implemented to forward to the superclass for the Y_AXIS. Along the X_AXIS the following values may be returned.

View.ExcellentBreakWeight
if there is whitespace proceeding the desired break location.
View.BadBreakWeight
if the desired break location results in a break location of the starting offset.
View.GoodBreakWeight
if the other conditions don't occur.
This will normally result in the behavior of breaking on a whitespace location if one can be found, otherwise breaking between characters.

Overrides:
getBreakWeight in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
pos - the potential location of the start of the broken view >= 0. This may be useful for calculating tab positions.
len - specifies the relative length from pos where a potential break is desired >= 0.
Returns:
the weight, which should be a value between View.ForcedBreakWeight and View.BadBreakWeight.
See Also:
LabelView, ParagraphView, View.BadBreakWeight, View.GoodBreakWeight, View.ExcellentBreakWeight, View.ForcedBreakWeight

breakView

public View breakView(int axis,
                      int p0,
                      float pos,
                      float len)
Breaks this view on the given axis at the given length. This is implemented to attempt to break on a whitespace location, and returns a fragment with the whitespace at the end. If a whitespace location can't be found, the nearest character is used.

Overrides:
breakView in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
p0 - the location in the model where the fragment should start it's representation >= 0.
pos - the position along the axis that the broken view would occupy >= 0. This may be useful for things like tab calculations.
len - specifies the distance along the axis where a potential break is desired >= 0.
Returns:
the fragment of the view that represents the given span, if the view can be broken. If the view doesn't support breaking behavior, the view itself is returned.
See Also:
View.breakView(int, int, float, float)

createFragment

public View createFragment(int p0,
                           int p1)
Creates a view that represents a portion of the element. This is potentially useful during formatting operations for taking measurements of fragments of the view. If the view doesn't support fragmenting (the default), it should return itself.

This view does support fragmenting. It is implemented to return a nested class that shares state in this view representing only a portion of the view.

Overrides:
createFragment in class View
Parameters:
p0 - the starting offset >= 0. This should be a value greater or equal to the element starting offset and less than the element ending offset.
p1 - the ending offset > p0. This should be a value less than or equal to the elements end offset and greater than the elements starting offset.
Returns:
the view fragment, or itself if the view doesn't support breaking into fragments
See Also:
LabelView

getNextVisualPositionFrom

public int getNextVisualPositionFrom(int pos,
                                     Position.Bias b,
                                     Shape a,
                                     int direction,
                                     Position.Bias[] biasRet)
                              throws BadLocationException
Provides a way to determine the next visually represented model location that one might place a caret. Some views may not be visible, they might not be in the same order found in the model, or they just might not allow access to some of the locations in the model.

Overrides:
getNextVisualPositionFrom in class View
Parameters:
pos - the position to convert >= 0
a - the allocated region to render into
direction - the direction from the current position that can be thought of as the arrow keys typically found on a keyboard. This may be SwingConstants.WEST, SwingConstants.EAST, SwingConstants.NORTH, or SwingConstants.SOUTH.
Returns:
the location within the model that best represents the next location visual position.
Throws:
BadLocationException
IllegalArgumentException - for an invalid direction

insertUpdate

public void insertUpdate(DocumentEvent e,
                         Shape a,
                         ViewFactory f)
Gives notification that something was inserted into the document in a location that this view is responsible for. This is implemented to call preferenceChanged along the axis the glyphs are rendered.

Overrides:
insertUpdate in class View
Parameters:
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

removeUpdate

public void removeUpdate(DocumentEvent e,
                         Shape a,
                         ViewFactory f)
Gives notification that something was removed from the document in a location that this view is responsible for. This is implemented to call preferenceChanged along the axis the glyphs are rendered.

Overrides:
removeUpdate in class View
Parameters:
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

changedUpdate

public void changedUpdate(DocumentEvent e,
                          Shape a,
                          ViewFactory f)
Gives notification from the document that attributes were changed in a location that this view is responsible for. This is implemented to call preferenceChanged along both the horizontal and vertical axis.

Overrides:
changedUpdate in class View
Parameters:
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


GlyphView.GlyphPainter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class GlyphView.GlyphPainter

java.lang.Object
    extended by  javax.swing.text.GlyphView.GlyphPainter
Enclosing class:
GlyphView
public abstract static class GlyphView.GlyphPainter
extends Object

A class to perform rendering of the glyphs. This can be implemented to be stateless, or to hold some information as a cache to facilitate faster rendering and model/view translation. At a minimum, the GlyphPainter allows a View implementation to perform its duties independant of a particular version of JVM and selection of capabilities (i.e. shaping for i18n, etc).

Since:
1.3

Constructor Summary
GlyphView.GlyphPainter()
Method Summary
abstract float | getAscent(GlyphView v)
abstract int | getBoundedPosition(GlyphView v, int p0, float x, float len) Determines the model location that represents the maximum advance that fits within the given span.
abstract float | getDescent(GlyphView v)
abstract float | getHeight(GlyphView v)
int | getNextVisualPositionFrom(GlyphView v, int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location that one might place a caret.
GlyphView.GlyphPainter | getPainter(GlyphView v, int p0, int p1) Create a painter to use for the given GlyphView.
abstract float | getSpan(GlyphView v, int p0, int p1, TabExpander e, float x) Determine the span the glyphs given a start location (for tab expansion).
abstract Shape | modelToView(GlyphView v, int pos, Position.Bias bias, Shape a) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
abstract void | paint(GlyphView v, Graphics g, Shape a, int p0, int p1) Paint the glyphs representing the given range.
abstract int | viewToModel(GlyphView v, float x, float y, Shape a, Position.Bias[] biasReturn) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GlyphView.GlyphPainter

public GlyphView.GlyphPainter()
Method Detail

getSpan

public abstract float getSpan(GlyphView v,
                              int p0,
                              int p1,
                              TabExpander e,
                              float x)
Determine the span the glyphs given a start location (for tab expansion).

getHeight

public abstract float getHeight(GlyphView v)

getAscent

public abstract float getAscent(GlyphView v)

getDescent

public abstract float getDescent(GlyphView v)

paint

public abstract void paint(GlyphView v,
                           Graphics g,
                           Shape a,
                           int p0,
                           int p1)
Paint the glyphs representing the given range.

modelToView

public abstract Shape modelToView(GlyphView v,
                                  int pos,
                                  Position.Bias bias,
                                  Shape a)
                           throws BadLocationException
Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it. This is shared by the broken views.

Parameters:
v - the GlyphView containing the destination coordinate space
pos - the position to convert
bias - either Position.Bias.Forward or Position.Bias.Backward
a - Bounds of the View
Returns:
the bounding box of the given position
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
See Also:
View.modelToView(int, java.awt.Shape, javax.swing.text.Position.Bias)

viewToModel

public abstract int viewToModel(GlyphView v,
                                float x,
                                float y,
                                Shape a,
                                Position.Bias[] biasReturn)
Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Parameters:
v - the GlyphView to provide a mapping for
x - the X coordinate
y - the Y coordinate
a - the allocated region to render into
biasReturn - either Position.Bias.Forward or Position.Bias.Backward is returned as the zero-th element of this array
Returns:
the location within the model that best represents the given point of view
See Also:
View.viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])

getBoundedPosition

public abstract int getBoundedPosition(GlyphView v,
                                       int p0,
                                       float x,
                                       float len)
Determines the model location that represents the maximum advance that fits within the given span. This could be used to break the given view. The result should be a location just shy of the given advance. This differs from viewToModel which returns the closest position which might be proud of the maximum advance.

Parameters:
v - the view to find the model location to break at.
p0 - the location in the model where the fragment should start it's representation >= 0.
x - the graphic location along the axis that the broken view would occupy >= 0. This may be useful for things like tab calculations.
len - specifies the distance into the view where a potential break is desired >= 0.
Returns:
the maximum model location possible for a break.
See Also:
View.breakView(int, int, float, float)

getPainter

public GlyphView.GlyphPainter getPainter(GlyphView v,
                                         int p0,
                                         int p1)
Create a painter to use for the given GlyphView. If the painter carries state it can create another painter to represent a new GlyphView that is being created. If the painter doesn't hold any significant state, it can return itself. The default behavior is to return itself.

Parameters:
v - the GlyphView to provide a painter for
p0 - the starting document offset >= 0
p1 - the ending document offset >= p0

getNextVisualPositionFrom

public int getNextVisualPositionFrom(GlyphView v,
                                     int pos,
                                     Position.Bias b,
                                     Shape a,
                                     int direction,
                                     Position.Bias[] biasRet)
                              throws BadLocationException
Provides a way to determine the next visually represented model location that one might place a caret. Some views may not be visible, they might not be in the same order found in the model, or they just might not allow access to some of the locations in the model.

Parameters:
v - the view to use
pos - the position to convert >= 0
b - either Position.Bias.Forward or Position.Bias.Backward
a - the allocated region to render into
direction - the direction from the current position that can be thought of as the arrow keys typically found on a keyboard. This may be SwingConstants.WEST, SwingConstants.EAST, SwingConstants.NORTH, or SwingConstants.SOUTH.
biasRet - either Position.Bias.Forward or Position.Bias.Backward is returned as the zero-th element of this array
Returns:
the location within the model that best represents the next location visual position.
Throws:
BadLocationException
IllegalArgumentException - for an invalid direction
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Highlighter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface Highlighter

All Known Implementing Classes:
BasicTextUI.BasicHighlighter, DefaultHighlighter, LayeredHighlighter
public interface Highlighter

An interface for an object that allows one to mark up the background with colored areas.

Nested Class Summary
static interface | Highlighter.Highlight
static interface | Highlighter.HighlightPainter Highlight renderer.
Method Summary
Object | addHighlight(int p0, int p1, Highlighter.HighlightPainter p) Adds a highlight to the view.
void | changeHighlight(Object tag, int p0, int p1) Changes the given highlight to span a different portion of the document.
void | deinstall(JTextComponent c) Called when the UI is being removed from the interface of a JTextComponent.
Highlighter.Highlight[] | getHighlights() Fetches the current list of highlights.
void | install(JTextComponent c) Called when the UI is being installed into the interface of a JTextComponent.
void | paint(Graphics g) Renders the highlights.
void | removeAllHighlights() Removes all highlights this highlighter is responsible for.
void | removeHighlight(Object tag) Removes a highlight from the view.

Method Detail

install

void install(JTextComponent c)
Called when the UI is being installed into the interface of a JTextComponent. This can be used to gain access to the model that is being navigated by the implementation of this interface.

Parameters:
c - the JTextComponent editor

deinstall

void deinstall(JTextComponent c)
Called when the UI is being removed from the interface of a JTextComponent. This is used to unregister any listeners that were attached.

Parameters:
c - the JTextComponent editor

paint

void paint(Graphics g)
Renders the highlights.

Parameters:
g - the graphics context.

addHighlight

Object addHighlight(int p0,
                    int p1,
                    Highlighter.HighlightPainter p)
                    throws BadLocationException
Adds a highlight to the view. Returns a tag that can be used to refer to the highlight.

Parameters:
p0 - the beginning of the range >= 0
p1 - the end of the range >= p0
p - the painter to use for the actual highlighting
Returns:
an object that refers to the highlight
Throws:
BadLocationException - for an invalid range specification

removeHighlight

void removeHighlight(Object tag)
Removes a highlight from the view.

Parameters:
tag - which highlight to remove

removeAllHighlights

void removeAllHighlights()
Removes all highlights this highlighter is responsible for.

changeHighlight

void changeHighlight(Object tag,
                     int p0,
                     int p1)
                     throws BadLocationException
Changes the given highlight to span a different portion of the document. This may be more efficient than a remove/add when a selection is expanding/shrinking (such as a sweep with a mouse) by damaging only what changed.

Parameters:
tag - which highlight to change
p0 - the beginning of the range >= 0
p1 - the end of the range >= p0
Throws:
BadLocationException - for an invalid range specification

getHighlights

Highlighter.Highlight[] getHighlights()
Fetches the current list of highlights.

Returns:
the highlight list
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Highlighter.Highlight

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface Highlighter.Highlight

Enclosing interface:
Highlighter
public static interface Highlighter.Highlight

Method Summary
int | getEndOffset() Gets the ending model offset for the highlight.
Highlighter.HighlightPainter | getPainter() Gets the painter for the highlighter.
int | getStartOffset() Gets the starting model offset for the highlight.

Method Detail

getStartOffset

int getStartOffset()
Gets the starting model offset for the highlight.

Returns:
the starting offset >= 0

getEndOffset

int getEndOffset()
Gets the ending model offset for the highlight.

Returns:
the ending offset >= 0

getPainter

Highlighter.HighlightPainter getPainter()
Gets the painter for the highlighter.

Returns:
the painter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Highlighter.HighlightPainter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface Highlighter.HighlightPainter

All Known Implementing Classes:
DefaultHighlighter.DefaultHighlightPainter, LayeredHighlighter.LayerPainter
Enclosing interface:
Highlighter
public static interface Highlighter.HighlightPainter

Highlight renderer.

Method Summary
 void paint(Graphics g, int p0, int p1, Shape bounds, JTextComponent c)
Renders the highlight.

Method Detail

paint

void paint(Graphics g,
           int p0,
           int p1,
           Shape bounds,
           JTextComponent c)
Renders the highlight.

Parameters:
g - the graphics context
p0 - the starting offset in the model >= 0
p1 - the ending offset in the model >= p0
bounds - the bounding box for the highlight
c - the editor
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


html

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.swing.text.html

Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

See:
Description

Class Summary
BlockView | A view implementation to display a block (as a box) with CSS specifications.
CSS | Defines a set of CSS attributes as a typesafe enumeration.
CSS.Attribute | Definitions to be used as a key on AttributeSet's that might hold CSS attributes.
FormSubmitEvent | FormSubmitEvent is used to notify interested parties that a form was submited.
FormView | Component decorator that implements the view interface for form elements, <input>, <textarea>, and <select>.
HTML | Constants used in the HTMLDocument.
HTML.Attribute | Typesafe enumeration representing an HTML attribute.
HTML.Tag | Typesafe enumeration for an HTML tag.
HTML.UnknownTag |
HTMLDocument | A document that models HTML.
HTMLDocument.Iterator | An iterator to iterate over a particular type of tag.
HTMLEditorKit | The Swing JEditorPane text component supports different kinds of content via a plug-in mechanism called an EditorKit.
HTMLEditorKit.HTMLFactory | A factory to build views for HTML.
HTMLEditorKit.HTMLTextAction | An abstract Action providing some convenience methods that may be useful in inserting HTML into an existing document.
HTMLEditorKit.InsertHTMLTextAction | InsertHTMLTextAction can be used to insert an arbitrary string of HTML into an existing HTML document.
HTMLEditorKit.LinkController | Class to watch the associated component and fire hyperlink events on it when appropriate.
HTMLEditorKit.Parser | Interface to be supported by the parser.
HTMLEditorKit.ParserCallback | The result of parsing drives these callback methods.
HTMLFrameHyperlinkEvent | HTMLFrameHyperlinkEvent is used to notify interested parties that link was activated in a frame.
HTMLWriter | This is a writer for HTMLDocuments.
ImageView | View of an Image, intended to support the HTML <IMG> tag.
InlineView | Displays the inline element styles based upon css attributes.
ListView | A view implementation to display an html list
MinimalHTMLWriter | MinimalHTMLWriter is a fallback writer used by the HTMLEditorKit to write out HTML for a document that is a not produced by the EditorKit.
ObjectView | Component decorator that implements the view interface for <object> elements.
Option | Value for the ListModel used to represent <option> elements.
ParagraphView | Displays the a paragraph, and uses css attributes for its configuration.
StyleSheet | Support for defining the visual characteristics of HTML views being rendered.
StyleSheet.BoxPainter | Class to carry out some of the duties of CSS formatting.
StyleSheet.ListPainter | Class to carry out some of the duties of CSS list formatting.

Enum Summary
FormSubmitEvent.MethodType Represents an HTML form method type.

Package javax.swing.text.html Description

Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Note: Most of the Swing API is not thread safe. For details, see Threads and Swing, a section in The Java Tutorial.

Package Specification

  • HTML 3.2 Reference Specification - The HTML specification on which HTMLEditorKit is based.

Since:
1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.swing.text.html Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.swing.text.html

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.swing.AbstractAction (implements javax.swing.Action, java.lang.Cloneable, java.io.Serializable)
      • javax.swing.text.TextAction
        • javax.swing.text.StyledEditorKit.StyledTextAction
          • javax.swing.text.html.HTMLEditorKit.HTMLTextAction
            • javax.swing.text.html.HTMLEditorKit.InsertHTMLTextAction
    • javax.swing.text.AbstractDocument (implements javax.swing.text.Document, java.io.Serializable)
      • javax.swing.text.DefaultStyledDocument (implements javax.swing.text.StyledDocument)
        • javax.swing.text.html.HTMLDocument
    • javax.swing.text.AbstractDocument.AbstractElement (implements javax.swing.text.Element, javax.swing.text.MutableAttributeSet, java.io.Serializable, javax.swing.tree.TreeNode)
      • javax.swing.text.AbstractDocument.BranchElement
        • javax.swing.text.html.HTMLDocument.BlockElement
      • javax.swing.text.AbstractDocument.LeafElement
        • javax.swing.text.html.HTMLDocument.RunElement
    • javax.swing.text.AbstractWriter
      • javax.swing.text.html.HTMLWriter
      • javax.swing.text.html.MinimalHTMLWriter
    • javax.swing.text.html.CSS (implements java.io.Serializable)
    • javax.swing.text.html.CSS.Attribute
    • javax.swing.text.EditorKit (implements java.lang.Cloneable, java.io.Serializable)
      • javax.swing.text.DefaultEditorKit
        • javax.swing.text.StyledEditorKit
          • javax.swing.text.html.HTMLEditorKit (implements javax.accessibility.Accessible)
    • java.util.EventObject (implements java.io.Serializable)
      • javax.swing.event.HyperlinkEvent
        • javax.swing.text.html.HTMLFrameHyperlinkEvent
          • javax.swing.text.html.FormSubmitEvent
    • javax.swing.text.html.HTML
    • javax.swing.text.html.HTML.Attribute
    • javax.swing.text.html.HTML.Tag
      • javax.swing.text.html.HTML.UnknownTag (implements java.io.Serializable)
    • javax.swing.text.html.HTMLDocument.HTMLReader.TagAction
      • javax.swing.text.html.HTMLDocument.HTMLReader.BlockAction
        • javax.swing.text.html.HTMLDocument.HTMLReader.ParagraphAction
        • javax.swing.text.html.HTMLDocument.HTMLReader.PreAction
      • javax.swing.text.html.HTMLDocument.HTMLReader.CharacterAction
      • javax.swing.text.html.HTMLDocument.HTMLReader.HiddenAction
      • javax.swing.text.html.HTMLDocument.HTMLReader.IsindexAction
      • javax.swing.text.html.HTMLDocument.HTMLReader.SpecialAction
        • javax.swing.text.html.HTMLDocument.HTMLReader.FormAction
    • javax.swing.text.html.HTMLDocument.Iterator
    • javax.swing.text.html.HTMLEditorKit.HTMLFactory (implements javax.swing.text.ViewFactory)
    • javax.swing.text.html.HTMLEditorKit.Parser
    • javax.swing.text.html.HTMLEditorKit.ParserCallback
      • javax.swing.text.html.HTMLDocument.HTMLReader
    • java.awt.event.MouseAdapter (implements java.awt.event.MouseListener, java.awt.event.MouseMotionListener, java.awt.event.MouseWheelListener)
      • javax.swing.text.html.FormView.MouseEventListener
      • javax.swing.text.html.HTMLEditorKit.LinkController (implements java.awt.event.MouseMotionListener, java.io.Serializable)
    • javax.swing.text.html.Option (implements java.io.Serializable)
    • javax.swing.text.StyleContext (implements javax.swing.text.AbstractDocument.AttributeContext, java.io.Serializable)
      • javax.swing.text.html.StyleSheet
    • javax.swing.text.html.StyleSheet.BoxPainter (implements java.io.Serializable)
    • javax.swing.text.html.StyleSheet.ListPainter (implements java.io.Serializable)
    • javax.swing.text.View (implements javax.swing.SwingConstants)
      • javax.swing.text.ComponentView
        • javax.swing.text.html.FormView (implements java.awt.event.ActionListener)
        • javax.swing.text.html.ObjectView
      • javax.swing.text.CompositeView
        • javax.swing.text.BoxView
          • javax.swing.text.html.BlockView
            • javax.swing.text.html.ListView
          • javax.swing.text.FlowView
            • javax.swing.text.ParagraphView (implements javax.swing.text.TabExpander)
              • javax.swing.text.html.ParagraphView
      • javax.swing.text.GlyphView (implements java.lang.Cloneable, javax.swing.text.TabableView)
        • javax.swing.text.LabelView (implements javax.swing.text.TabableView)
          • javax.swing.text.html.InlineView
      • javax.swing.text.html.ImageView

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • javax.swing.text.html.FormSubmitEvent.MethodType
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.swing.text.html

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.swing.text.html

Packages that use javax.swing.text.html
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.
javax.swing.text.html.parser | Provides the default HTML parser, along with support classes.

Classes in javax.swing.text.html used by javax.swing.text.html
BlockView
A view implementation to display a block (as a box) with CSS specifications.
CSS.Attribute
Definitions to be used as a key on AttributeSet's that might hold CSS attributes.
FormSubmitEvent.MethodType
Represents an HTML form method type.
HTML.Attribute
Typesafe enumeration representing an HTML attribute.
HTML.Tag
Typesafe enumeration for an HTML tag.
HTMLDocument
A document that models HTML.
HTMLDocument.HTMLReader.BlockAction
HTMLDocument.HTMLReader.SpecialAction
HTMLDocument.HTMLReader.TagAction
An action to be performed in response to parsing a tag.
HTMLDocument.Iterator
An iterator to iterate over a particular type of tag.
HTMLEditorKit
The Swing JEditorPane text component supports different kinds of content via a plug-in mechanism called an EditorKit.
HTMLEditorKit.HTMLTextAction
An abstract Action providing some convenience methods that may be useful in inserting HTML into an existing document.
HTMLEditorKit.Parser
Interface to be supported by the parser.
HTMLEditorKit.ParserCallback
The result of parsing drives these callback methods.
HTMLFrameHyperlinkEvent
HTMLFrameHyperlinkEvent is used to notify interested parties that link was activated in a frame.
Option
Value for the ListModel used to represent <option> elements.
StyleSheet
Support for defining the visual characteristics of HTML views being rendered.
StyleSheet.BoxPainter
Class to carry out some of the duties of CSS formatting.
StyleSheet.ListPainter
Class to carry out some of the duties of CSS list formatting.

Classes in javax.swing.text.html used by javax.swing.text.html.parser
HTML.Tag
Typesafe enumeration for an HTML tag.
HTMLEditorKit.Parser
Interface to be supported by the parser.
HTMLEditorKit.ParserCallback
The result of parsing drives these callback methods.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


BlockView

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class BlockView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.CompositeView
            extended by  javax.swing.text.BoxView
                extended by  javax.swing.text.html.BlockView
All Implemented Interfaces:
SwingConstants
Direct Known Subclasses:
ListView
public class BlockView
extends BoxView

A view implementation to display a block (as a box) with CSS specifications.

Field Summary
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
BlockView(Element elem, int axis)
Creates a new view that represents an html box.
Method Summary
protected SizeRequirements | calculateMajorAxisRequirements(int axis, SizeRequirements r) Calculate the requirements of the block along the major axis (i.e.
protected SizeRequirements | calculateMinorAxisRequirements(int axis, SizeRequirements r) Calculate the requirements of the block along the minor axis (i.e.
void | changedUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
float | getAlignment(int axis) Gets the alignment.
AttributeSet | getAttributes() Fetches the attributes to use when rendering.
float | getMaximumSpan(int axis) Determines the maximum span for this view along an axis.
float | getMinimumSpan(int axis) Determines the minimum span for this view along an axis.
float | getPreferredSpan(int axis) Determines the preferred span for this view along an axis.
int | getResizeWeight(int axis) Gets the resize weight.
protected StyleSheet | getStyleSheet()
protected void | layoutMinorAxis(int targetSpan, int axis, int[] offsets, int[] spans) Performs layout for the minor axis of the box (i.e.
void | paint(Graphics g, Shape allocation) Renders using the given rendering surface and area on that surface.
void | setParent(View parent) Establishes the parent view for this view.
protected void | setPropertiesFromAttributes() Update any cached values that come from attributes.
Methods inherited from class javax.swing.text.BoxView
baselineLayout, baselineRequirements, childAllocation, flipEastAndWestAtEnds, forwardUpdate, getAxis, getChildAllocation, getHeight, getOffset, getSpan, getViewAtPoint, getWidth, isAfter, isAllocationValid, isBefore, isLayoutValid, layout, layoutChanged, layoutMajorAxis, modelToView, paintChild, preferenceChanged, replace, setAxis, setSize, viewToModel
Methods inherited from class javax.swing.text.CompositeView
getBottomInset, getInsideAllocation, getLeftInset, getNextEastWestVisualPositionFrom, getNextNorthSouthVisualPositionFrom, getNextVisualPositionFrom, getRightInset, getTopInset, getView, getViewAtPosition, getViewCount, getViewIndex, getViewIndexAtPosition, loadChildren, modelToView, setInsets, setParagraphInsets
Methods inherited from class javax.swing.text.View
append, breakView, createFragment, forwardUpdateToView, getBreakWeight, getContainer, getDocument, getElement, getEndOffset, getGraphics, getParent, getStartOffset, getToolTipText, getViewFactory, getViewIndex, insert, insertUpdate, isVisible, modelToView, remove, removeAll, removeUpdate, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BlockView

public BlockView(Element elem,
                 int axis)
Creates a new view that represents an html box. This can be used for a number of elements.

Parameters:
elem - the element to create a view for
axis - either View.X_AXIS or View.Y_AXIS
Method Detail

setParent

public void setParent(View parent)
Establishes the parent view for this view. This is guaranteed to be called before any other methods if the parent view is functioning properly.

This is implemented to forward to the superclass as well as call the setPropertiesFromAttributes() method to set the paragraph properties from the css attributes. The call is made at this time to ensure the ability to resolve upward through the parents view attributes.

Overrides:
setParent in class CompositeView
Parameters:
parent - the new parent, or null if the view is being removed from a parent it was previously added to

calculateMajorAxisRequirements

protected SizeRequirements calculateMajorAxisRequirements(int axis,
                                                          SizeRequirements r)
Calculate the requirements of the block along the major axis (i.e. the axis along with it tiles). This is implemented to provide the superclass behavior and then adjust it if the CSS width or height attribute is specified and applicable to the axis.

Overrides:
calculateMajorAxisRequirements in class BoxView
Parameters:
axis - the axis being studied
r - the SizeRequirements object; if null one will be created
Returns:
the newly initialized SizeRequirements object
See Also:
SizeRequirements

calculateMinorAxisRequirements

protected SizeRequirements calculateMinorAxisRequirements(int axis,
                                                          SizeRequirements r)
Calculate the requirements of the block along the minor axis (i.e. the axis orthoginal to the axis along with it tiles). This is implemented to provide the superclass behavior and then adjust it if the CSS width or height attribute is specified and applicable to the axis.

Overrides:
calculateMinorAxisRequirements in class BoxView
Parameters:
axis - the axis being studied
r - the SizeRequirements object; if null one will be created
Returns:
the newly initialized SizeRequirements object
See Also:
SizeRequirements

layoutMinorAxis

protected void layoutMinorAxis(int targetSpan,
                               int axis,
                               int[] offsets,
                               int[] spans)
Performs layout for the minor axis of the box (i.e. the axis orthoginal to the axis that it represents). The results of the layout (the offset and span for each children) are placed in the given arrays which represent the allocations to the children along the minor axis.

Overrides:
layoutMinorAxis in class BoxView
Parameters:
targetSpan - the total span given to the view, which whould be used to layout the childre.
axis - the axis being layed out
offsets - the offsets from the origin of the view for each of the child views; this is a return value and is filled in by the implementation of this method
spans - the span of each child view; this is a return value and is filled in by the implementation of this method

paint

public void paint(Graphics g,
                  Shape allocation)
Renders using the given rendering surface and area on that surface. This is implemented to delegate to the css box painter to paint the border and background prior to the interior.

Overrides:
paint in class BoxView
Parameters:
g - the rendering surface to use
allocation - the allocated region to render into
See Also:
View.paint(java.awt.Graphics, java.awt.Shape)

getAttributes

public AttributeSet getAttributes()
Fetches the attributes to use when rendering. This is implemented to multiplex the attributes specified in the model with a StyleSheet.

Overrides:
getAttributes in class View

getResizeWeight

public int getResizeWeight(int axis)
Gets the resize weight.

Overrides:
getResizeWeight in class BoxView
Parameters:
axis - may be either X_AXIS or Y_AXIS
Returns:
the weight
Throws:
IllegalArgumentException - for an invalid axis

getAlignment

public float getAlignment(int axis)
Gets the alignment.

Overrides:
getAlignment in class BoxView
Parameters:
axis - may be either X_AXIS or Y_AXIS
Returns:
the alignment

changedUpdate

public void changedUpdate(DocumentEvent changes,
                          Shape a,
                          ViewFactory f)
Description copied from class: View
Gives notification from the document that attributes were changed in a location that this view is responsible for. To reduce the burden to subclasses, this functionality is spread out into the following calls that subclasses can reimplement:
  1. updateChildren is called if there were any changes to the element this view is responsible for. If this view has child views that are represent the child elements, then this method should do whatever is necessary to make sure the child views correctly represent the model.
  2. forwardUpdate is called to forward the DocumentEvent to the appropriate child views.
  3. updateLayout is called to give the view a chance to either repair its layout, to reschedule layout, or do nothing.

Overrides:
changedUpdate in class View
Parameters:
changes - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

getPreferredSpan

public float getPreferredSpan(int axis)
Determines the preferred span for this view along an axis.

Overrides:
getPreferredSpan in class BoxView
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into >= 0; typically the view is told to render into the span that is returned, although there is no guarantee; the parent may choose to resize or break the view
Throws:
IllegalArgumentException - for an invalid axis type
See Also:
View.getPreferredSpan(int)

getMinimumSpan

public float getMinimumSpan(int axis)
Determines the minimum span for this view along an axis.

Overrides:
getMinimumSpan in class BoxView
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into >= 0; typically the view is told to render into the span that is returned, although there is no guarantee; the parent may choose to resize or break the view
Throws:
IllegalArgumentException - for an invalid axis type
See Also:
View.getPreferredSpan(int)

getMaximumSpan

public float getMaximumSpan(int axis)
Determines the maximum span for this view along an axis.

Overrides:
getMaximumSpan in class BoxView
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into >= 0; typically the view is told to render into the span that is returned, although there is no guarantee; the parent may choose to resize or break the view
Throws:
IllegalArgumentException - for an invalid axis type
See Also:
View.getPreferredSpan(int)

setPropertiesFromAttributes

protected void setPropertiesFromAttributes()
Update any cached values that come from attributes.

getStyleSheet

protected StyleSheet getStyleSheet()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.swing.text.html.BlockView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.BlockView

Packages that use BlockView
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of BlockView in javax.swing.text.html

Subclasses of BlockView in javax.swing.text.html
 class ListView
A view implementation to display an html list

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.CSS

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.CSS

No usage of javax.swing.text.html.CSS

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.CSS.Attribute

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.CSS.Attribute

Packages that use CSS.Attribute
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of CSS.Attribute in javax.swing.text.html

Fields in javax.swing.text.html declared as CSS.Attribute
static CSS.Attribute | CSS.Attribute.BACKGROUND
static CSS.Attribute | CSS.Attribute.BACKGROUND_ATTACHMENT
static CSS.Attribute | CSS.Attribute.BACKGROUND_COLOR
static CSS.Attribute | CSS.Attribute.BACKGROUND_IMAGE
static CSS.Attribute | CSS.Attribute.BACKGROUND_POSITION
static CSS.Attribute | CSS.Attribute.BACKGROUND_REPEAT
static CSS.Attribute | CSS.Attribute.BORDER
static CSS.Attribute | CSS.Attribute.BORDER_BOTTOM
static CSS.Attribute | CSS.Attribute.BORDER_BOTTOM_WIDTH
static CSS.Attribute | CSS.Attribute.BORDER_COLOR
static CSS.Attribute | CSS.Attribute.BORDER_LEFT
static CSS.Attribute | CSS.Attribute.BORDER_LEFT_WIDTH
static CSS.Attribute | CSS.Attribute.BORDER_RIGHT
static CSS.Attribute | CSS.Attribute.BORDER_RIGHT_WIDTH
static CSS.Attribute | CSS.Attribute.BORDER_STYLE
static CSS.Attribute | CSS.Attribute.BORDER_TOP
static CSS.Attribute | CSS.Attribute.BORDER_TOP_WIDTH
static CSS.Attribute | CSS.Attribute.BORDER_WIDTH
static CSS.Attribute | CSS.Attribute.CLEAR
static CSS.Attribute | CSS.Attribute.COLOR
static CSS.Attribute | CSS.Attribute.DISPLAY
static CSS.Attribute | CSS.Attribute.FLOAT
static CSS.Attribute | CSS.Attribute.FONT
static CSS.Attribute | CSS.Attribute.FONT_FAMILY
static CSS.Attribute | CSS.Attribute.FONT_SIZE
static CSS.Attribute | CSS.Attribute.FONT_STYLE
static CSS.Attribute | CSS.Attribute.FONT_VARIANT
static CSS.Attribute | CSS.Attribute.FONT_WEIGHT
static CSS.Attribute | CSS.Attribute.HEIGHT
static CSS.Attribute | CSS.Attribute.LETTER_SPACING
static CSS.Attribute | CSS.Attribute.LINE_HEIGHT
static CSS.Attribute | CSS.Attribute.LIST_STYLE
static CSS.Attribute | CSS.Attribute.LIST_STYLE_IMAGE
static CSS.Attribute | CSS.Attribute.LIST_STYLE_POSITION
static CSS.Attribute | CSS.Attribute.LIST_STYLE_TYPE
static CSS.Attribute | CSS.Attribute.MARGIN
static CSS.Attribute | CSS.Attribute.MARGIN_BOTTOM
static CSS.Attribute | CSS.Attribute.MARGIN_LEFT
static CSS.Attribute | CSS.Attribute.MARGIN_RIGHT
static CSS.Attribute | CSS.Attribute.MARGIN_TOP
static CSS.Attribute | CSS.Attribute.PADDING
static CSS.Attribute | CSS.Attribute.PADDING_BOTTOM
static CSS.Attribute | CSS.Attribute.PADDING_LEFT
static CSS.Attribute | CSS.Attribute.PADDING_RIGHT
static CSS.Attribute | CSS.Attribute.PADDING_TOP
static CSS.Attribute | CSS.Attribute.TEXT_ALIGN
static CSS.Attribute | CSS.Attribute.TEXT_DECORATION
static CSS.Attribute | CSS.Attribute.TEXT_INDENT
static CSS.Attribute | CSS.Attribute.TEXT_TRANSFORM
static CSS.Attribute | CSS.Attribute.VERTICAL_ALIGN
static CSS.Attribute | CSS.Attribute.WHITE_SPACE
static CSS.Attribute | CSS.Attribute.WIDTH
static CSS.Attribute | CSS.Attribute.WORD_SPACING

Methods in javax.swing.text.html that return CSS.Attribute
static CSS.Attribute[] | CSS.getAllAttributeKeys() Return the set of all possible CSS attribute keys.
static CSS.Attribute | CSS.getAttribute(String name) Translates a string to a CSS.Attribute object.

Methods in javax.swing.text.html with parameters of type CSS.Attribute
void | StyleSheet.addCSSAttribute(MutableAttributeSet attr, CSS.Attribute key, String value) Adds a CSS attribute to the given set.
boolean | StyleSheet.addCSSAttributeFromHTML(MutableAttributeSet attr, CSS.Attribute key, String value) Adds a CSS attribute to the given set.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.FormSubmitEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.FormSubmitEvent

No usage of javax.swing.text.html.FormSubmitEvent

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.FormSubmitEvent.MethodType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.FormSubmitEvent.MethodType

Packages that use FormSubmitEvent.MethodType
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of FormSubmitEvent.MethodType in javax.swing.text.html

Methods in javax.swing.text.html that return FormSubmitEvent.MethodType
FormSubmitEvent.MethodType | FormSubmitEvent.getMethod() Gets the form method type.
static FormSubmitEvent.MethodType | FormSubmitEvent.MethodType.valueOf(String name) Returns the enum constant of this type with the specified name.
static FormSubmitEvent.MethodType[] | FormSubmitEvent.MethodType.values() Returns an array containing the constants of this enum type, in the order they are declared.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.FormView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.FormView

No usage of javax.swing.text.html.FormView

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.FormView.MouseEventListener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.FormView.MouseEventListener

No usage of javax.swing.text.html.FormView.MouseEventListener

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTML

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTML

No usage of javax.swing.text.html.HTML

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTML.Attribute

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTML.Attribute

Packages that use HTML.Attribute
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of HTML.Attribute in javax.swing.text.html

Fields in javax.swing.text.html declared as HTML.Attribute
static HTML.Attribute | HTML.Attribute.ACTION
static HTML.Attribute | HTML.Attribute.ALIGN
static HTML.Attribute | HTML.Attribute.ALINK
static HTML.Attribute | HTML.Attribute.ALT
static HTML.Attribute | HTML.Attribute.ARCHIVE
static HTML.Attribute | HTML.Attribute.BACKGROUND
static HTML.Attribute | HTML.Attribute.BGCOLOR
static HTML.Attribute | HTML.Attribute.BORDER
static HTML.Attribute | HTML.Attribute.CELLPADDING
static HTML.Attribute | HTML.Attribute.CELLSPACING
static HTML.Attribute | HTML.Attribute.CHECKED
static HTML.Attribute | HTML.Attribute.CLASS
static HTML.Attribute | HTML.Attribute.CLASSID
static HTML.Attribute | HTML.Attribute.CLEAR
static HTML.Attribute | HTML.Attribute.CODE
static HTML.Attribute | HTML.Attribute.CODEBASE
static HTML.Attribute | HTML.Attribute.CODETYPE
static HTML.Attribute | HTML.Attribute.COLOR
static HTML.Attribute | HTML.Attribute.COLS
static HTML.Attribute | HTML.Attribute.COLSPAN
static HTML.Attribute | HTML.Attribute.COMMENT
static HTML.Attribute | HTML.Attribute.COMPACT
static HTML.Attribute | HTML.Attribute.CONTENT
static HTML.Attribute | HTML.Attribute.COORDS
static HTML.Attribute | HTML.Attribute.DATA
static HTML.Attribute | HTML.Attribute.DECLARE
static HTML.Attribute | HTML.Attribute.DIR
static HTML.Attribute | HTML.Attribute.DUMMY
static HTML.Attribute | HTML.Attribute.ENCTYPE
static HTML.Attribute | HTML.Attribute.ENDTAG
static HTML.Attribute | HTML.Attribute.FACE
static HTML.Attribute | HTML.Attribute.FRAMEBORDER
static HTML.Attribute | HTML.Attribute.HALIGN
static HTML.Attribute | HTML.Attribute.HEIGHT
static HTML.Attribute | HTML.Attribute.HREF
static HTML.Attribute | HTML.Attribute.HSPACE
static HTML.Attribute | HTML.Attribute.HTTPEQUIV
static HTML.Attribute | HTML.Attribute.ID
static HTML.Attribute | HTML.Attribute.ISMAP
static HTML.Attribute | HTML.Attribute.LANG
static HTML.Attribute | HTML.Attribute.LANGUAGE
static HTML.Attribute | HTML.Attribute.LINK
static HTML.Attribute | HTML.Attribute.LOWSRC
static HTML.Attribute | HTML.Attribute.MARGINHEIGHT
static HTML.Attribute | HTML.Attribute.MARGINWIDTH
static HTML.Attribute | HTML.Attribute.MAXLENGTH
static HTML.Attribute | HTML.Attribute.METHOD
static HTML.Attribute | HTML.Attribute.MULTIPLE
static HTML.Attribute | HTML.Attribute.N
static HTML.Attribute | HTML.Attribute.NAME
static HTML.Attribute | HTML.Attribute.NOHREF
static HTML.Attribute | HTML.Attribute.NORESIZE
static HTML.Attribute | HTML.Attribute.NOSHADE
static HTML.Attribute | HTML.Attribute.NOWRAP
static HTML.Attribute | HTML.Attribute.PROMPT
static HTML.Attribute | HTML.Attribute.REL
static HTML.Attribute | HTML.Attribute.REV
static HTML.Attribute | HTML.Attribute.ROWS
static HTML.Attribute | HTML.Attribute.ROWSPAN
static HTML.Attribute | HTML.Attribute.SCROLLING
static HTML.Attribute | HTML.Attribute.SELECTED
static HTML.Attribute | HTML.Attribute.SHAPE
static HTML.Attribute | HTML.Attribute.SHAPES
static HTML.Attribute | HTML.Attribute.SIZE
static HTML.Attribute | HTML.Attribute.SRC
static HTML.Attribute | HTML.Attribute.STANDBY
static HTML.Attribute | HTML.Attribute.START
static HTML.Attribute | HTML.Attribute.STYLE
static HTML.Attribute | HTML.Attribute.TARGET
static HTML.Attribute | HTML.Attribute.TEXT
static HTML.Attribute | HTML.Attribute.TITLE
static HTML.Attribute | HTML.Attribute.TYPE
static HTML.Attribute | HTML.Attribute.USEMAP
static HTML.Attribute | HTML.Attribute.VALIGN
static HTML.Attribute | HTML.Attribute.VALUE
static HTML.Attribute | HTML.Attribute.VALUETYPE
static HTML.Attribute | HTML.Attribute.VERSION
static HTML.Attribute | HTML.Attribute.VLINK
static HTML.Attribute | HTML.Attribute.VSPACE
static HTML.Attribute | HTML.Attribute.WIDTH

Methods in javax.swing.text.html that return HTML.Attribute
static HTML.Attribute[] | HTML.getAllAttributeKeys() Returns the set of HTML attributes recognized.
static HTML.Attribute | HTML.getAttributeKey(String attName) Fetches an attribute constant for a well-known attribute name (i.e.

Methods in javax.swing.text.html with parameters of type HTML.Attribute
static int HTML.getIntegerAttributeValue(AttributeSet attr, HTML.Attribute key, int def)
Fetches an integer attribute value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTML.Tag

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTML.Tag

Packages that use HTML.Tag
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.
javax.swing.text.html.parser | Provides the default HTML parser, along with support classes.

Uses of HTML.Tag in javax.swing.text.html

Subclasses of HTML.Tag in javax.swing.text.html
static class HTML.UnknownTag

Fields in javax.swing.text.html declared as HTML.Tag
static HTML.Tag | HTML.Tag.A
static HTML.Tag | HTML.Tag.ADDRESS
protected HTML.Tag | HTMLEditorKit.InsertHTMLTextAction.addTag Tag in HTML to start adding tags from.
protected HTML.Tag | HTMLEditorKit.InsertHTMLTextAction.alternateAddTag Alternate tag in HTML to start adding tags from if parentTag is not found and alternateParentTag is found.
protected HTML.Tag | HTMLEditorKit.InsertHTMLTextAction.alternateParentTag Alternate Tag to check for in the document if parentTag is not found.
static HTML.Tag | HTML.Tag.APPLET
static HTML.Tag | HTML.Tag.AREA
static HTML.Tag | HTML.Tag.B
static HTML.Tag | HTML.Tag.BASE
static HTML.Tag | HTML.Tag.BASEFONT
static HTML.Tag | HTML.Tag.BIG
static HTML.Tag | HTML.Tag.BLOCKQUOTE
static HTML.Tag | HTML.Tag.BODY
static HTML.Tag | HTML.Tag.BR
static HTML.Tag | HTML.Tag.CAPTION
static HTML.Tag | HTML.Tag.CENTER
static HTML.Tag | HTML.Tag.CITE
static HTML.Tag | HTML.Tag.CODE
static HTML.Tag | HTML.Tag.COMMENT All comments are labeled with this tag.
static HTML.Tag | HTML.Tag.CONTENT All text content is labeled with this tag.
static HTML.Tag | HTML.Tag.DD
static HTML.Tag | HTML.Tag.DFN
static HTML.Tag | HTML.Tag.DIR
static HTML.Tag | HTML.Tag.DIV
static HTML.Tag | HTML.Tag.DL
static HTML.Tag | HTML.Tag.DT
static HTML.Tag | HTML.Tag.EM
static HTML.Tag | HTML.Tag.FONT
static HTML.Tag | HTML.Tag.FORM
static HTML.Tag | HTML.Tag.FRAME
static HTML.Tag | HTML.Tag.FRAMESET
static HTML.Tag | HTML.Tag.H1
static HTML.Tag | HTML.Tag.H2
static HTML.Tag | HTML.Tag.H3
static HTML.Tag | HTML.Tag.H4
static HTML.Tag | HTML.Tag.H5
static HTML.Tag | HTML.Tag.H6
static HTML.Tag | HTML.Tag.HEAD
static HTML.Tag | HTML.Tag.HR
static HTML.Tag | HTML.Tag.HTML
static HTML.Tag | HTML.Tag.I
static HTML.Tag | HTML.Tag.IMG
static HTML.Tag | HTML.Tag.IMPLIED All text content must be in a paragraph element.
static HTML.Tag | HTML.Tag.INPUT
static HTML.Tag | HTML.Tag.ISINDEX
static HTML.Tag | HTML.Tag.KBD
static HTML.Tag | HTML.Tag.LI
static HTML.Tag | HTML.Tag.LINK
static HTML.Tag | HTML.Tag.MAP
static HTML.Tag | HTML.Tag.MENU
static HTML.Tag | HTML.Tag.META
static HTML.Tag | HTML.Tag.NOFRAMES
static HTML.Tag | HTML.Tag.OBJECT
static HTML.Tag | HTML.Tag.OL
static HTML.Tag | HTML.Tag.OPTION
static HTML.Tag | HTML.Tag.P
static HTML.Tag | HTML.Tag.PARAM
protected HTML.Tag | HTMLEditorKit.InsertHTMLTextAction.parentTag Tag to check for in the document.
static HTML.Tag | HTML.Tag.PRE
static HTML.Tag | HTML.Tag.S
static HTML.Tag | HTML.Tag.SAMP
static HTML.Tag | HTML.Tag.SCRIPT
static HTML.Tag | HTML.Tag.SELECT
static HTML.Tag | HTML.Tag.SMALL
static HTML.Tag | HTML.Tag.SPAN
static HTML.Tag | HTML.Tag.STRIKE
static HTML.Tag | HTML.Tag.STRONG
static HTML.Tag | HTML.Tag.STYLE
static HTML.Tag | HTML.Tag.SUB
static HTML.Tag | HTML.Tag.SUP
static HTML.Tag | HTML.Tag.TABLE
static HTML.Tag | HTML.Tag.TD
static HTML.Tag | HTML.Tag.TEXTAREA
static HTML.Tag | HTML.Tag.TH
static HTML.Tag | HTML.Tag.TITLE
static HTML.Tag | HTML.Tag.TR
static HTML.Tag | HTML.Tag.TT
static HTML.Tag | HTML.Tag.U
static HTML.Tag | HTML.Tag.UL
static HTML.Tag | HTML.Tag.VAR

Methods in javax.swing.text.html that return HTML.Tag
static HTML.Tag[] | HTML.getAllTags() Returns the set of actual HTML tags that are recognized by the default HTML reader.
abstract HTML.Tag | HTMLDocument.Iterator.getTag() Type of tag this iterator represents.
static HTML.Tag | HTML.getTag(String tagName) Fetches a tag constant for a well-known tag name (i.e.

Methods in javax.swing.text.html with parameters of type HTML.Tag
protected void | HTMLDocument.HTMLReader.addSpecialElement(HTML.Tag t, MutableAttributeSet a) Adds content that is basically specified entirely in the attribute set.
protected void | HTMLDocument.HTMLReader.blockClose(HTML.Tag t) Adds an instruction to the parse buffer to close out a block element of the given type.
protected void | HTMLDocument.HTMLReader.blockOpen(HTML.Tag t, MutableAttributeSet attr) Adds an instruction to the parse buffer to create a block element with the given attributes.
protected int | HTMLEditorKit.HTMLTextAction.elementCountToTag(HTMLDocument doc, int offset, HTML.Tag tag) Returns number of elements, starting at the deepest leaf, needed to get to an element representing tag.
void | HTMLDocument.HTMLReader.TagAction.end(HTML.Tag t) Called when an end tag is seen for the type of tag this action was registered to.
void | HTMLDocument.HTMLReader.BlockAction.end(HTML.Tag t)
void | HTMLDocument.HTMLReader.ParagraphAction.end(HTML.Tag t)
void | HTMLDocument.HTMLReader.HiddenAction.end(HTML.Tag t)
void | HTMLDocument.HTMLReader.PreAction.end(HTML.Tag t)
void | HTMLDocument.HTMLReader.CharacterAction.end(HTML.Tag t)
void | HTMLDocument.HTMLReader.FormAction.end(HTML.Tag t)
protected Element | HTMLEditorKit.HTMLTextAction.findElementMatchingTag(HTMLDocument doc, int offset, HTML.Tag tag) Returns the deepest element at offset matching tag.
HTMLDocument.Iterator | HTMLDocument.getIterator(HTML.Tag t) Fetches an iterator for the specified HTML tag.
HTMLEditorKit.ParserCallback | HTMLDocument.getReader(int pos, int popDepth, int pushDepth, HTML.Tag insertTag) Returns the reader for the parser to use to load the document with HTML.
Style | StyleSheet.getRule(HTML.Tag t, Element e) Fetches the style to use to render the given type of HTML tag.
void | HTMLEditorKit.ParserCallback.handleEndTag(HTML.Tag t, int pos)
void | HTMLDocument.HTMLReader.handleEndTag(HTML.Tag t, int pos) Callback from the parser.
void | HTMLEditorKit.ParserCallback.handleSimpleTag(HTML.Tag t, MutableAttributeSet a, int pos)
void | HTMLDocument.HTMLReader.handleSimpleTag(HTML.Tag t, MutableAttributeSet a, int pos) Callback from the parser.
void | HTMLEditorKit.ParserCallback.handleStartTag(HTML.Tag t, MutableAttributeSet a, int pos)
void | HTMLDocument.HTMLReader.handleStartTag(HTML.Tag t, MutableAttributeSet a, int pos) Callback from the parser.
protected void | HTMLEditorKit.InsertHTMLTextAction.insertAtBoundary(JEditorPane editor, HTMLDocument doc, int offset, Element insertElement, String html, HTML.Tag parentTag, HTML.Tag addTag) This is invoked when inserting at a boundary.
protected void | HTMLEditorKit.InsertHTMLTextAction.insertAtBoundry(JEditorPane editor, HTMLDocument doc, int offset, Element insertElement, String html, HTML.Tag parentTag, HTML.Tag addTag) Deprecated. As of Java 2 platform v1.3, use insertAtBoundary
void | HTMLEditorKit.insertHTML(HTMLDocument doc, int offset, String html, int popDepth, int pushDepth, HTML.Tag insertTag) Inserts HTML into an existing document.
protected void | HTMLEditorKit.InsertHTMLTextAction.insertHTML(JEditorPane editor, HTMLDocument doc, int offset, String html, int popDepth, int pushDepth, HTML.Tag addTag) A cover for HTMLEditorKit.insertHTML.
protected boolean | HTMLWriter.matchNameAttribute(AttributeSet attr, HTML.Tag tag) Returns true if the StyleConstants.NameAttribute is equal to the tag that is passed in as a parameter.
protected void | HTMLDocument.HTMLReader.registerTag(HTML.Tag t, HTMLDocument.HTMLReader.TagAction a) Registers a handler for the given tag.
void | HTMLDocument.HTMLReader.TagAction.start(HTML.Tag t, MutableAttributeSet a) Called when a start tag is seen for the type of tag this action was registered to.
void | HTMLDocument.HTMLReader.BlockAction.start(HTML.Tag t, MutableAttributeSet attr)
void | HTMLDocument.HTMLReader.ParagraphAction.start(HTML.Tag t, MutableAttributeSet a)
void | HTMLDocument.HTMLReader.SpecialAction.start(HTML.Tag t, MutableAttributeSet a)
void | HTMLDocument.HTMLReader.IsindexAction.start(HTML.Tag t, MutableAttributeSet a)
void | HTMLDocument.HTMLReader.HiddenAction.start(HTML.Tag t, MutableAttributeSet a)
void | HTMLDocument.HTMLReader.PreAction.start(HTML.Tag t, MutableAttributeSet attr)
void | HTMLDocument.HTMLReader.CharacterAction.start(HTML.Tag t, MutableAttributeSet attr)
void | HTMLDocument.HTMLReader.FormAction.start(HTML.Tag t, MutableAttributeSet attr)

Constructors in javax.swing.text.html with parameters of type HTML.Tag
HTMLDocument.HTMLReader(int offset, int popDepth, int pushDepth, HTML.Tag insertTag)
HTMLEditorKit.InsertHTMLTextAction(String name, String html, HTML.Tag parentTag, HTML.Tag addTag)
HTMLEditorKit.InsertHTMLTextAction(String name, String html, HTML.Tag parentTag, HTML.Tag addTag, HTML.Tag alternateParentTag, HTML.Tag alternateAddTag)

Uses of HTML.Tag in javax.swing.text.html.parser

Methods in javax.swing.text.html.parser that return HTML.Tag
 HTML.Tag TagElement.getHTMLTag()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTML.UnknownTag

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTML.UnknownTag

No usage of javax.swing.text.html.HTML.UnknownTag

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLDocument

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLDocument

Packages that use HTMLDocument
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of HTMLDocument in javax.swing.text.html

Methods in javax.swing.text.html that return HTMLDocument
protected  HTMLDocument HTMLEditorKit.HTMLTextAction.getHTMLDocument(JEditorPane e)

Methods in javax.swing.text.html with parameters of type HTMLDocument
protected int | HTMLEditorKit.HTMLTextAction.elementCountToTag(HTMLDocument doc, int offset, HTML.Tag tag) Returns number of elements, starting at the deepest leaf, needed to get to an element representing tag.
protected Element | HTMLEditorKit.HTMLTextAction.findElementMatchingTag(HTMLDocument doc, int offset, HTML.Tag tag) Returns the deepest element at offset matching tag.
protected Element[] | HTMLEditorKit.HTMLTextAction.getElementsAt(HTMLDocument doc, int offset) Returns an array of the Elements that contain offset.
protected void | HTMLEditorKit.InsertHTMLTextAction.insertAtBoundary(JEditorPane editor, HTMLDocument doc, int offset, Element insertElement, String html, HTML.Tag parentTag, HTML.Tag addTag) This is invoked when inserting at a boundary.
protected void | HTMLEditorKit.InsertHTMLTextAction.insertAtBoundry(JEditorPane editor, HTMLDocument doc, int offset, Element insertElement, String html, HTML.Tag parentTag, HTML.Tag addTag) Deprecated. As of Java 2 platform v1.3, use insertAtBoundary
void | HTMLEditorKit.insertHTML(HTMLDocument doc, int offset, String html, int popDepth, int pushDepth, HTML.Tag insertTag) Inserts HTML into an existing document.
protected void | HTMLEditorKit.InsertHTMLTextAction.insertHTML(JEditorPane editor, HTMLDocument doc, int offset, String html, int popDepth, int pushDepth, HTML.Tag addTag) A cover for HTMLEditorKit.insertHTML.

Constructors in javax.swing.text.html with parameters of type HTMLDocument
HTMLWriter(Writer w, HTMLDocument doc)
Creates a new HTMLWriter.
HTMLWriter(Writer w, HTMLDocument doc, int pos, int len)
Creates a new HTMLWriter.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLDocument.BlockElement

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLDocument.BlockElement

No usage of javax.swing.text.html.HTMLDocument.BlockElement

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLDocument.HTMLReader

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLDocument.HTMLReader

No usage of javax.swing.text.html.HTMLDocument.HTMLReader

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLDocument.HTMLReader.BlockAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLDocument.HTMLReader.BlockAction

Packages that use HTMLDocument.HTMLReader.BlockAction
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of HTMLDocument.HTMLReader.BlockAction in javax.swing.text.html

Subclasses of HTMLDocument.HTMLReader.BlockAction in javax.swing.text.html
class | HTMLDocument.HTMLReader.ParagraphAction
class | HTMLDocument.HTMLReader.PreAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLDocument.HTMLReader.CharacterAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLDocument.HTMLReader.CharacterAction

No usage of javax.swing.text.html.HTMLDocument.HTMLReader.CharacterAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLDocument.HTMLReader.FormAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLDocument.HTMLReader.FormAction

No usage of javax.swing.text.html.HTMLDocument.HTMLReader.FormAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLDocument.HTMLReader.HiddenAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLDocument.HTMLReader.HiddenAction

No usage of javax.swing.text.html.HTMLDocument.HTMLReader.HiddenAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLDocument.HTMLReader.IsindexAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLDocument.HTMLReader.IsindexAction

No usage of javax.swing.text.html.HTMLDocument.HTMLReader.IsindexAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLDocument.HTMLReader.ParagraphAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLDocument.HTMLReader.ParagraphAction

No usage of javax.swing.text.html.HTMLDocument.HTMLReader.ParagraphAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLDocument.HTMLReader.PreAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLDocument.HTMLReader.PreAction

No usage of javax.swing.text.html.HTMLDocument.HTMLReader.PreAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLDocument.HTMLReader.SpecialAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLDocument.HTMLReader.SpecialAction

Packages that use HTMLDocument.HTMLReader.SpecialAction
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of HTMLDocument.HTMLReader.SpecialAction in javax.swing.text.html

Subclasses of HTMLDocument.HTMLReader.SpecialAction in javax.swing.text.html
 class HTMLDocument.HTMLReader.FormAction
Action to support forms by building all of the elements used to represent form controls.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLDocument.HTMLReader.TagAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLDocument.HTMLReader.TagAction

Packages that use HTMLDocument.HTMLReader.TagAction
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of HTMLDocument.HTMLReader.TagAction in javax.swing.text.html

Subclasses of HTMLDocument.HTMLReader.TagAction in javax.swing.text.html
class | HTMLDocument.HTMLReader.BlockAction
class | HTMLDocument.HTMLReader.CharacterAction
class | HTMLDocument.HTMLReader.FormAction Action to support forms by building all of the elements used to represent form controls.
class | HTMLDocument.HTMLReader.HiddenAction
class | HTMLDocument.HTMLReader.IsindexAction
class | HTMLDocument.HTMLReader.ParagraphAction
class | HTMLDocument.HTMLReader.PreAction
class | HTMLDocument.HTMLReader.SpecialAction

Methods in javax.swing.text.html with parameters of type HTMLDocument.HTMLReader.TagAction
protected  void HTMLDocument.HTMLReader.registerTag(HTML.Tag t, HTMLDocument.HTMLReader.TagAction a)
Registers a handler for the given tag.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLDocument.Iterator

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLDocument.Iterator

Packages that use HTMLDocument.Iterator
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of HTMLDocument.Iterator in javax.swing.text.html

Methods in javax.swing.text.html that return HTMLDocument.Iterator
 HTMLDocument.Iterator HTMLDocument.getIterator(HTML.Tag t)
Fetches an iterator for the specified HTML tag.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLDocument.RunElement

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLDocument.RunElement

No usage of javax.swing.text.html.HTMLDocument.RunElement

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLEditorKit

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLEditorKit

Packages that use HTMLEditorKit
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of HTMLEditorKit in javax.swing.text.html

Methods in javax.swing.text.html that return HTMLEditorKit
protected  HTMLEditorKit HTMLEditorKit.HTMLTextAction.getHTMLEditorKit(JEditorPane e)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLEditorKit.HTMLFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLEditorKit.HTMLFactory

No usage of javax.swing.text.html.HTMLEditorKit.HTMLFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLEditorKit.HTMLTextAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLEditorKit.HTMLTextAction

Packages that use HTMLEditorKit.HTMLTextAction
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of HTMLEditorKit.HTMLTextAction in javax.swing.text.html

Subclasses of HTMLEditorKit.HTMLTextAction in javax.swing.text.html
static class HTMLEditorKit.InsertHTMLTextAction
InsertHTMLTextAction can be used to insert an arbitrary string of HTML into an existing HTML document.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLEditorKit.InsertHTMLTextAction

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLEditorKit.InsertHTMLTextAction

No usage of javax.swing.text.html.HTMLEditorKit.InsertHTMLTextAction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLEditorKit.LinkController

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLEditorKit.LinkController

No usage of javax.swing.text.html.HTMLEditorKit.LinkController

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLEditorKit.Parser

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLEditorKit.Parser

Packages that use HTMLEditorKit.Parser
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.
javax.swing.text.html.parser | Provides the default HTML parser, along with support classes.

Uses of HTMLEditorKit.Parser in javax.swing.text.html

Methods in javax.swing.text.html that return HTMLEditorKit.Parser
protected HTMLEditorKit.Parser | HTMLEditorKit.getParser() Fetch the parser to use for reading HTML streams.
HTMLEditorKit.Parser | HTMLDocument.getParser() Returns the parser that is used when inserting HTML into the existing document.

Methods in javax.swing.text.html with parameters of type HTMLEditorKit.Parser
 void HTMLDocument.setParser(HTMLEditorKit.Parser parser)
Sets the parser that is used by the methods that insert html into the existing document, such as setInnerHTML, and setOuterHTML.

Uses of HTMLEditorKit.Parser in javax.swing.text.html.parser

Subclasses of HTMLEditorKit.Parser in javax.swing.text.html.parser
 class ParserDelegator
Responsible for starting up a new DocumentParser each time its parse method is invoked.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLEditorKit.ParserCallback

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLEditorKit.ParserCallback

Packages that use HTMLEditorKit.ParserCallback
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.
javax.swing.text.html.parser | Provides the default HTML parser, along with support classes.

Uses of HTMLEditorKit.ParserCallback in javax.swing.text.html

Subclasses of HTMLEditorKit.ParserCallback in javax.swing.text.html
 class HTMLDocument.HTMLReader
An HTML reader to load an HTML document with an HTML element structure.

Methods in javax.swing.text.html that return HTMLEditorKit.ParserCallback
HTMLEditorKit.ParserCallback | HTMLDocument.getReader(int pos) Fetches the reader for the parser to use when loading the document with HTML.
HTMLEditorKit.ParserCallback | HTMLDocument.getReader(int pos, int popDepth, int pushDepth, HTML.Tag insertTag) Returns the reader for the parser to use to load the document with HTML.

Methods in javax.swing.text.html with parameters of type HTMLEditorKit.ParserCallback
abstract  void HTMLEditorKit.Parser.parse(Reader r, HTMLEditorKit.ParserCallback cb, boolean ignoreCharSet)
Parse the given stream and drive the given callback with the results of the parse.

Uses of HTMLEditorKit.ParserCallback in javax.swing.text.html.parser

Methods in javax.swing.text.html.parser with parameters of type HTMLEditorKit.ParserCallback
void | DocumentParser.parse(Reader in, HTMLEditorKit.ParserCallback callback, boolean ignoreCharSet)
void | ParserDelegator.parse(Reader r, HTMLEditorKit.ParserCallback cb, boolean ignoreCharSet)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLFrameHyperlinkEvent

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLFrameHyperlinkEvent

Packages that use HTMLFrameHyperlinkEvent
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of HTMLFrameHyperlinkEvent in javax.swing.text.html

Subclasses of HTMLFrameHyperlinkEvent in javax.swing.text.html
 class FormSubmitEvent
FormSubmitEvent is used to notify interested parties that a form was submited.

Methods in javax.swing.text.html with parameters of type HTMLFrameHyperlinkEvent
 void HTMLDocument.processHTMLFrameHyperlinkEvent(HTMLFrameHyperlinkEvent e)
Processes HyperlinkEvents that are generated by documents in an HTML frame.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.HTMLWriter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.HTMLWriter

No usage of javax.swing.text.html.HTMLWriter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.ImageView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.ImageView

No usage of javax.swing.text.html.ImageView

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.InlineView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.InlineView

No usage of javax.swing.text.html.InlineView

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.ListView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.ListView

No usage of javax.swing.text.html.ListView

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.MinimalHTMLWriter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.MinimalHTMLWriter

No usage of javax.swing.text.html.MinimalHTMLWriter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.ObjectView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.ObjectView

No usage of javax.swing.text.html.ObjectView

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.Option

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.Option

Packages that use Option
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of Option in javax.swing.text.html

Methods in javax.swing.text.html with parameters of type Option
protected  void HTMLWriter.writeOption(Option option)
Writes out the content of the Option form element.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.ParagraphView

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.ParagraphView

No usage of javax.swing.text.html.ParagraphView

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.StyleSheet

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.StyleSheet

Packages that use StyleSheet
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of StyleSheet in javax.swing.text.html

Methods in javax.swing.text.html that return StyleSheet
protected StyleSheet | BlockView.getStyleSheet()
StyleSheet | HTMLEditorKit.getStyleSheet() Get the set of styles currently being used to render the HTML elements.
StyleSheet | HTMLDocument.getStyleSheet() Fetches the StyleSheet with the document-specific display rules (CSS) that were specified in the HTML document itself.
protected StyleSheet | ImageView.getStyleSheet() Convenience method to get the StyleSheet.
protected StyleSheet | ParagraphView.getStyleSheet()
protected StyleSheet | InlineView.getStyleSheet()
StyleSheet[] | StyleSheet.getStyleSheets() Returns an array of the linked StyleSheets.

Methods in javax.swing.text.html with parameters of type StyleSheet
void | StyleSheet.addStyleSheet(StyleSheet ss) Adds the rules from the StyleSheet ss to those of the receiver.
void | StyleSheet.removeStyleSheet(StyleSheet ss) Removes the StyleSheet ss from those of the receiver.
void | HTMLEditorKit.setStyleSheet(StyleSheet s) Set the set of styles to be used to render the various HTML elements.

Constructors in javax.swing.text.html with parameters of type StyleSheet
HTMLDocument(AbstractDocument.Content c, StyleSheet styles)
Constructs an HTML document with the given content storage implementation and the given style/attribute storage mechanism.
HTMLDocument(StyleSheet styles)
Constructs an HTML document with the default content storage implementation and the specified style/attribute storage mechanism.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.StyleSheet.BoxPainter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.StyleSheet.BoxPainter

Packages that use StyleSheet.BoxPainter
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of StyleSheet.BoxPainter in javax.swing.text.html

Methods in javax.swing.text.html that return StyleSheet.BoxPainter
 StyleSheet.BoxPainter StyleSheet.getBoxPainter(AttributeSet a)
Fetches the box formatter to use for the given set of CSS attributes.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.StyleSheet.ListPainter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.StyleSheet.ListPainter

Packages that use StyleSheet.ListPainter
javax.swing.text.html Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.

Uses of StyleSheet.ListPainter in javax.swing.text.html

Methods in javax.swing.text.html that return StyleSheet.ListPainter
 StyleSheet.ListPainter StyleSheet.getListPainter(AttributeSet a)
Fetches the list formatter to use for the given set of CSS attributes.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


CSS

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class CSS

java.lang.Object
    extended by  javax.swing.text.html.CSS
All Implemented Interfaces:
Serializable
public class CSS
extends Object
implements Serializable

Defines a set of CSS attributes as a typesafe enumeration. The HTML View implementations use CSS attributes to determine how they will render. This also defines methods to map between CSS/HTML/StyleConstants. Any shorthand properties, such as font, are mapped to the intrinsic properties.

The following describes the CSS properties that are suppored by the rendering engine:

  • font-family
  • font-style
  • font-size (supports relative units)
  • font-weight
  • font
  • color
  • background-color (with the exception of transparent)
  • background-image
  • background-repeat
  • background-position
  • background
  • background-repeat
  • text-decoration (with the exception of blink and overline)
  • vertical-align (only sup and super)
  • text-align (justify is treated as center)
  • margin-top
  • margin-right
  • margin-bottom
  • margin-left
  • margin
  • padding-top
  • padding-right
  • padding-bottom
  • padding-left
  • border-style (only supports inset, outset and none)
  • list-style-type
  • list-style-position
The following are modeled, but currently not rendered.
  • font-variant
  • background-attachment (background always treated as scroll)
  • word-spacing
  • letter-spacing
  • text-indent
  • text-transform
  • line-height
  • border-top-width (this is used to indicate if a border should be used)
  • border-right-width
  • border-bottom-width
  • border-left-width
  • border-width
  • border-top
  • border-right
  • border-bottom
  • border-left
  • border
  • width
  • height
  • float
  • clear
  • display
  • white-space
  • list-style

Note: for the time being we do not fully support relative units, unless noted, so that p { margin-top: 10% } will be treated as if no margin-top was specified.

See Also:
StyleSheet

Nested Class Summary
static class CSS.Attribute
Definitions to be used as a key on AttributeSet's that might hold CSS attributes.
Constructor Summary
CSS()
Method Summary
static CSS.Attribute[] | getAllAttributeKeys() Return the set of all possible CSS attribute keys.
static CSS.Attribute | getAttribute(String name) Translates a string to a CSS.Attribute object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CSS

public CSS()
Method Detail

getAllAttributeKeys

public static CSS.Attribute[] getAllAttributeKeys()
Return the set of all possible CSS attribute keys.

getAttribute

public static final CSS.Attribute getAttribute(String name)
Translates a string to a CSS.Attribute object. This will return null if there is no attribute by the given name.

Parameters:
name - the name of the CSS attribute to fetch the typesafe enumeration for
Returns:
the CSS.Attribute object, or null if the string doesn't represent a valid attribute key
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CSS.Attribute

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class CSS.Attribute

java.lang.Object
    extended by  javax.swing.text.html.CSS.Attribute
Enclosing class:
CSS
public static final class CSS.Attribute
extends Object

Definitions to be used as a key on AttributeSet's that might hold CSS attributes. Since this is a closed set (i.e. defined exactly by the specification), it is final and cannot be extended.

Field Summary
static CSS.Attribute | BACKGROUND
static CSS.Attribute | BACKGROUND_ATTACHMENT
static CSS.Attribute | BACKGROUND_COLOR
static CSS.Attribute | BACKGROUND_IMAGE
static CSS.Attribute | BACKGROUND_POSITION
static CSS.Attribute | BACKGROUND_REPEAT
static CSS.Attribute | BORDER
static CSS.Attribute | BORDER_BOTTOM
static CSS.Attribute | BORDER_BOTTOM_WIDTH
static CSS.Attribute | BORDER_COLOR
static CSS.Attribute | BORDER_LEFT
static CSS.Attribute | BORDER_LEFT_WIDTH
static CSS.Attribute | BORDER_RIGHT
static CSS.Attribute | BORDER_RIGHT_WIDTH
static CSS.Attribute | BORDER_STYLE
static CSS.Attribute | BORDER_TOP
static CSS.Attribute | BORDER_TOP_WIDTH
static CSS.Attribute | BORDER_WIDTH
static CSS.Attribute | CLEAR
static CSS.Attribute | COLOR
static CSS.Attribute | DISPLAY
static CSS.Attribute | FLOAT
static CSS.Attribute | FONT
static CSS.Attribute | FONT_FAMILY
static CSS.Attribute | FONT_SIZE
static CSS.Attribute | FONT_STYLE
static CSS.Attribute | FONT_VARIANT
static CSS.Attribute | FONT_WEIGHT
static CSS.Attribute | HEIGHT
static CSS.Attribute | LETTER_SPACING
static CSS.Attribute | LINE_HEIGHT
static CSS.Attribute | LIST_STYLE
static CSS.Attribute | LIST_STYLE_IMAGE
static CSS.Attribute | LIST_STYLE_POSITION
static CSS.Attribute | LIST_STYLE_TYPE
static CSS.Attribute | MARGIN
static CSS.Attribute | MARGIN_BOTTOM
static CSS.Attribute | MARGIN_LEFT
static CSS.Attribute | MARGIN_RIGHT
static CSS.Attribute | MARGIN_TOP
static CSS.Attribute | PADDING
static CSS.Attribute | PADDING_BOTTOM
static CSS.Attribute | PADDING_LEFT
static CSS.Attribute | PADDING_RIGHT
static CSS.Attribute | PADDING_TOP
static CSS.Attribute | TEXT_ALIGN
static CSS.Attribute | TEXT_DECORATION
static CSS.Attribute | TEXT_INDENT
static CSS.Attribute | TEXT_TRANSFORM
static CSS.Attribute | VERTICAL_ALIGN
static CSS.Attribute | WHITE_SPACE
static CSS.Attribute | WIDTH
static CSS.Attribute | WORD_SPACING
Method Summary
String | getDefaultValue() Fetch the default value for the attribute.
boolean | isInherited() Indicates if the attribute should be inherited from the parent or not.
String | toString() The string representation of the attribute.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

BACKGROUND

public static final CSS.Attribute BACKGROUND

BACKGROUND_ATTACHMENT

public static final CSS.Attribute BACKGROUND_ATTACHMENT

BACKGROUND_COLOR

public static final CSS.Attribute BACKGROUND_COLOR

BACKGROUND_IMAGE

public static final CSS.Attribute BACKGROUND_IMAGE

BACKGROUND_POSITION

public static final CSS.Attribute BACKGROUND_POSITION

BACKGROUND_REPEAT

public static final CSS.Attribute BACKGROUND_REPEAT

BORDER

public static final CSS.Attribute BORDER

BORDER_BOTTOM

public static final CSS.Attribute BORDER_BOTTOM

BORDER_BOTTOM_WIDTH

public static final CSS.Attribute BORDER_BOTTOM_WIDTH

BORDER_COLOR

public static final CSS.Attribute BORDER_COLOR

BORDER_LEFT

public static final CSS.Attribute BORDER_LEFT

BORDER_LEFT_WIDTH

public static final CSS.Attribute BORDER_LEFT_WIDTH

BORDER_RIGHT

public static final CSS.Attribute BORDER_RIGHT

BORDER_RIGHT_WIDTH

public static final CSS.Attribute BORDER_RIGHT_WIDTH

BORDER_STYLE

public static final CSS.Attribute BORDER_STYLE

BORDER_TOP

public static final CSS.Attribute BORDER_TOP

BORDER_TOP_WIDTH

public static final CSS.Attribute BORDER_TOP_WIDTH

BORDER_WIDTH

public static final CSS.Attribute BORDER_WIDTH

CLEAR

public static final CSS.Attribute CLEAR

COLOR

public static final CSS.Attribute COLOR

DISPLAY

public static final CSS.Attribute DISPLAY

FLOAT

public static final CSS.Attribute FLOAT

FONT

public static final CSS.Attribute FONT

FONT_FAMILY

public static final CSS.Attribute FONT_FAMILY

FONT_SIZE

public static final CSS.Attribute FONT_SIZE

FONT_STYLE

public static final CSS.Attribute FONT_STYLE

FONT_VARIANT

public static final CSS.Attribute FONT_VARIANT

FONT_WEIGHT

public static final CSS.Attribute FONT_WEIGHT

HEIGHT

public static final CSS.Attribute HEIGHT

LETTER_SPACING

public static final CSS.Attribute LETTER_SPACING

LINE_HEIGHT

public static final CSS.Attribute LINE_HEIGHT

LIST_STYLE

public static final CSS.Attribute LIST_STYLE

LIST_STYLE_IMAGE

public static final CSS.Attribute LIST_STYLE_IMAGE

LIST_STYLE_POSITION

public static final CSS.Attribute LIST_STYLE_POSITION

LIST_STYLE_TYPE

public static final CSS.Attribute LIST_STYLE_TYPE

MARGIN

public static final CSS.Attribute MARGIN

MARGIN_BOTTOM

public static final CSS.Attribute MARGIN_BOTTOM

MARGIN_LEFT

public static final CSS.Attribute MARGIN_LEFT

MARGIN_RIGHT

public static final CSS.Attribute MARGIN_RIGHT

MARGIN_TOP

public static final CSS.Attribute MARGIN_TOP

PADDING

public static final CSS.Attribute PADDING

PADDING_BOTTOM

public static final CSS.Attribute PADDING_BOTTOM

PADDING_LEFT

public static final CSS.Attribute PADDING_LEFT

PADDING_RIGHT

public static final CSS.Attribute PADDING_RIGHT

PADDING_TOP

public static final CSS.Attribute PADDING_TOP

TEXT_ALIGN

public static final CSS.Attribute TEXT_ALIGN

TEXT_DECORATION

public static final CSS.Attribute TEXT_DECORATION

TEXT_INDENT

public static final CSS.Attribute TEXT_INDENT

TEXT_TRANSFORM

public static final CSS.Attribute TEXT_TRANSFORM

VERTICAL_ALIGN

public static final CSS.Attribute VERTICAL_ALIGN

WORD_SPACING

public static final CSS.Attribute WORD_SPACING

WHITE_SPACE

public static final CSS.Attribute WHITE_SPACE

WIDTH

public static final CSS.Attribute WIDTH
Method Detail

toString

public String toString()
The string representation of the attribute. This should exactly match the string specified in the CSS specification.

Overrides:
toString in class Object
Returns:
a string representation of the object.

getDefaultValue

public String getDefaultValue()
Fetch the default value for the attribute. If there is no default value (such as for composite attributes), null will be returned.

isInherited

public boolean isInherited()
Indicates if the attribute should be inherited from the parent or not.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FormSubmitEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class FormSubmitEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.swing.event.HyperlinkEvent
            extended by  javax.swing.text.html.HTMLFrameHyperlinkEvent
                extended by  javax.swing.text.html.FormSubmitEvent
All Implemented Interfaces:
Serializable
public class FormSubmitEvent
extends HTMLFrameHyperlinkEvent

FormSubmitEvent is used to notify interested parties that a form was submited.

Since:
1.5

Nested Class Summary
static class FormSubmitEvent.MethodType
Represents an HTML form method type.
Nested classes/interfaces inherited from class javax.swing.event.HyperlinkEvent
HyperlinkEvent.EventType
Field Summary
Fields inherited from class java.util.EventObject
source
Method Summary
String | getData() Gets the form submission data.
FormSubmitEvent.MethodType | getMethod() Gets the form method type.
Methods inherited from class javax.swing.text.html.HTMLFrameHyperlinkEvent
getTarget
Methods inherited from class javax.swing.event.HyperlinkEvent
getDescription, getEventType, getSourceElement, getURL
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getMethod

public FormSubmitEvent.MethodType getMethod()
Gets the form method type.

Returns:
the form method type, either Method.GET or Method.POST.

getData

public String getData()
Gets the form submission data.

Returns:
the string representing the form submission data.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FormSubmitEvent.MethodType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.swing.text.html
Enum FormSubmitEvent.MethodType

java.lang.Object
    extended by  java.lang.Enum<FormSubmitEvent.MethodType>
        extended by  javax.swing.text.html.FormSubmitEvent.MethodType
All Implemented Interfaces:
Serializable, Comparable<FormSubmitEvent.MethodType>
Enclosing class:
FormSubmitEvent
public static enum FormSubmitEvent.MethodType
extends Enum<FormSubmitEvent.MethodType>

Represents an HTML form method type.

  • GET corresponds to the GET form method
  • POST corresponds to the POST from method

Since:
1.5

Enum Constant Summary
GET
POST
Method Summary
static FormSubmitEvent.MethodType | valueOf(String name) Returns the enum constant of this type with the specified name.
static FormSubmitEvent.MethodType[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

GET

public static final FormSubmitEvent.MethodType GET

POST

public static final FormSubmitEvent.MethodType POST
Method Detail

values

public static FormSubmitEvent.MethodType[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (FormSubmitEvent.MethodType c : FormSubmitEvent.MethodType.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static FormSubmitEvent.MethodType valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


FormView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class FormView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.ComponentView
            extended by  javax.swing.text.html.FormView
All Implemented Interfaces:
ActionListener, EventListener, SwingConstants
public class FormView
extends ComponentView
implements ActionListener

Component decorator that implements the view interface for form elements, <input>, <textarea>, and <select>. The model for the component is stored as an attribute of the the element (using StyleConstants.ModelAttribute), and is used to build the component of the view. The type of the model is assumed to of the type that would be set by HTMLDocument.HTMLReader.FormAction. If there are multiple views mapped over the document, they will share the embedded component models.

The following table shows what components get built by this view.
Element Type | Component built
input, type button | JButton
input, type checkbox | JCheckBox
input, type image | JButton
input, type password | JPasswordField
input, type radio | JRadioButton
input, type reset | JButton
input, type submit | JButton
input, type text | JTextField
select, size > 1 or multiple attribute defined | JList in a JScrollPane
select, size unspecified or 1 | JComboBox
textarea | JTextArea in a JScrollPane
input, type file | JTextField

Nested Class Summary
protected  class FormView.MouseEventListener
MouseEventListener class to handle form submissions when an input with type equal to image is clicked on.
Field Summary
static String | RESET Deprecated. As of 1.3, value comes from UIManager UIManager property FormView.resetButtonText
static String | SUBMIT Deprecated. As of 1.3, value now comes from UIManager property FormView.submitButtonText
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
FormView(Element elem)
Creates a new FormView object.
Method Summary
void | actionPerformed(ActionEvent evt) Responsible for processeing the ActionEvent.
protected Component | createComponent() Create the component.
float | getMaximumSpan(int axis) Determines the maximum span for this view along an axis.
protected void | imageSubmit(String imageData) This method is called to submit a form in response to a click on an image -- an <INPUT> form element of type "image".
protected void | submitData(String data) This method is responsible for submitting the form data.
Methods inherited from class javax.swing.text.ComponentView
getAlignment, getComponent, getMinimumSpan, getPreferredSpan, modelToView, paint, setParent, viewToModel
Methods inherited from class javax.swing.text.View
append, breakView, changedUpdate, createFragment, forwardUpdate, forwardUpdateToView, getAttributes, getBreakWeight, getChildAllocation, getContainer, getDocument, getElement, getEndOffset, getGraphics, getNextVisualPositionFrom, getParent, getResizeWeight, getStartOffset, getToolTipText, getView, getViewCount, getViewFactory, getViewIndex, getViewIndex, insert, insertUpdate, isVisible, modelToView, modelToView, preferenceChanged, remove, removeAll, removeUpdate, replace, setSize, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SUBMIT

@Deprecated
public static final String SUBMIT
Deprecated. As of 1.3, value now comes from UIManager property FormView.submitButtonText
If a value attribute is not specified for a FORM input element of type "submit", then this default string is used.

RESET

@Deprecated
public static final String RESET
Deprecated. As of 1.3, value comes from UIManager UIManager property FormView.resetButtonText
If a value attribute is not specified for a FORM input element of type "reset", then this default string is used.

Constructor Detail

FormView

public FormView(Element elem)
Creates a new FormView object.

Parameters:
elem - the element to decorate
Method Detail

createComponent

protected Component createComponent()
Create the component. This is basically a big switch statement based upon the tag type and html attributes of the associated element.

Overrides:
createComponent in class ComponentView

getMaximumSpan

public float getMaximumSpan(int axis)
Determines the maximum span for this view along an axis. For certain components, the maximum and preferred span are the same. For others this will return the value returned by Component.getMaximumSize along the axis of interest.

Overrides:
getMaximumSpan in class ComponentView
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned, although there is no guarantee. The parent may choose to resize or break the view.
Throws:
IllegalArgumentException - for an invalid axis
See Also:
View.getPreferredSpan(int)

actionPerformed

public void actionPerformed(ActionEvent evt)
Responsible for processeing the ActionEvent. If the element associated with the FormView, has a type of "submit", "reset", "text" or "password" then the action is processed. In the case of a "submit" the form is submitted. In the case of a "reset" the form is reset to its original state. In the case of "text" or "password", if the element is the last one of type "text" or "password", the form is submitted. Otherwise, focus is transferred to the next component in the form.

Specified by:
actionPerformed in interface ActionListener
Parameters:
evt - the ActionEvent.

submitData

protected void submitData(String data)
This method is responsible for submitting the form data. A thread is forked to undertake the submission.

imageSubmit

protected void imageSubmit(String imageData)
This method is called to submit a form in response to a click on an image -- an <INPUT> form element of type "image".

Parameters:
imageData - the mouse click coordinates.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FormView.MouseEventListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class FormView.MouseEventListener

java.lang.Object
    extended by  java.awt.event.MouseAdapter
        extended by  javax.swing.text.html.FormView.MouseEventListener
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, EventListener
Enclosing class:
FormView
protected class FormView.MouseEventListener
extends MouseAdapter

MouseEventListener class to handle form submissions when an input with type equal to image is clicked on. A MouseListener is necessary since along with the image data the coordinates associated with the mouse click need to be submitted.

Constructor Summary
protected FormView.MouseEventListener()
Method Summary
 void mouseReleased(MouseEvent evt)
Invoked when a mouse button has been released on a component.
Methods inherited from class java.awt.event.MouseAdapter
mouseClicked, mouseDragged, mouseEntered, mouseExited, mouseMoved, mousePressed, mouseWheelMoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FormView.MouseEventListener

protected FormView.MouseEventListener()
Method Detail

mouseReleased

public void mouseReleased(MouseEvent evt)
Description copied from class: MouseAdapter
Invoked when a mouse button has been released on a component.

Specified by:
mouseReleased in interface MouseListener
Overrides:
mouseReleased in class MouseAdapter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTML

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTML

java.lang.Object
    extended by  javax.swing.text.html.HTML

public class HTML
extends Object

Constants used in the HTMLDocument. These are basically tag and attribute definitions.

Nested Class Summary
static class | HTML.Attribute Typesafe enumeration representing an HTML attribute.
static class | HTML.Tag Typesafe enumeration for an HTML tag.
static class | HTML.UnknownTag
Field Summary
static String NULL_ATTRIBUTE_VALUE
Constructor Summary
HTML()
Method Summary
static HTML.Attribute[] | getAllAttributeKeys() Returns the set of HTML attributes recognized.
static HTML.Tag[] | getAllTags() Returns the set of actual HTML tags that are recognized by the default HTML reader.
static HTML.Attribute | getAttributeKey(String attName) Fetches an attribute constant for a well-known attribute name (i.e.
static int | getIntegerAttributeValue(AttributeSet attr, HTML.Attribute key, int def) Fetches an integer attribute value.
static HTML.Tag | getTag(String tagName) Fetches a tag constant for a well-known tag name (i.e.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NULL_ATTRIBUTE_VALUE

public static final String NULL_ATTRIBUTE_VALUE
See Also:
Constant Field Values
Constructor Detail

HTML

public HTML()
Method Detail

getAllTags

public static HTML.Tag[] getAllTags()
Returns the set of actual HTML tags that are recognized by the default HTML reader. This set does not include tags that are manufactured by the reader.

getTag

public static HTML.Tag getTag(String tagName)
Fetches a tag constant for a well-known tag name (i.e. one of the tags in the set {A, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BIG, BLOCKQUOTE, BODY, BR, CAPTION, CENTER, CITE, CODE, DD, DFN, DIR, DIV, DL, DT, EM, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IMG, INPUT, ISINDEX, KBD, LI, LINK, MAP, MENU, META, NOBR, NOFRAMES, OBJECT, OL, OPTION, P, PARAM, PRE, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, S, STRONG, STYLE, SUB, SUP, TABLE, TD, TEXTAREA, TH, TITLE, TR, TT, U, UL, VAR}. If the given name does not represent one of the well-known tags, then null will be returned.

Parameters:
tagName - the String name requested
Returns:
a tag constant corresponding to the tagName, or null if not found

getIntegerAttributeValue

public static int getIntegerAttributeValue(AttributeSet attr,
                                           HTML.Attribute key,
                                           int def)
Fetches an integer attribute value. Attribute values are stored as a string, and this is a convenience method to convert to an actual integer.

Parameters:
attr - the set of attributes to use to try to fetch a value
key - the key to use to fetch the value
def - the default value to use if the attribute isn't defined or there is an error converting to an integer

getAllAttributeKeys

public static HTML.Attribute[] getAllAttributeKeys()
Returns the set of HTML attributes recognized.

Returns:
the set of HTML attributes recognized

getAttributeKey

public static HTML.Attribute getAttributeKey(String attName)
Fetches an attribute constant for a well-known attribute name (i.e. one of the attributes in the set {FACE, COMMENT, SIZE, COLOR, CLEAR, BACKGROUND, BGCOLOR, TEXT, LINK, VLINK, ALINK, WIDTH, HEIGHT, ALIGN, NAME, HREF, REL, REV, TITLE, TARGET, SHAPE, COORDS, ISMAP, NOHREF, ALT, ID, SRC, HSPACE, VSPACE, USEMAP, LOWSRC, CODEBASE, CODE, ARCHIVE, VALUE, VALUETYPE, TYPE, CLASS, STYLE, LANG, DIR, DECLARE, CLASSID, DATA, CODETYPE, STANDBY, BORDER, SHAPES, NOSHADE, COMPACT, START, ACTION, METHOD, ENCTYPE, CHECKED, MAXLENGTH, MULTIPLE, SELECTED, ROWS, COLS, DUMMY, CELLSPACING, CELLPADDING, VALIGN, HALIGN, NOWRAP, ROWSPAN, COLSPAN, PROMPT, HTTPEQUIV, CONTENT, LANGUAGE, VERSION, N, FRAMEBORDER, MARGINWIDTH, MARGINHEIGHT, SCROLLING, NORESIZE, MEDIA, ENDTAG}). If the given name does not represent one of the well-known attributes, then null will be returned.

Parameters:
attName - the String requested
Returns:
the Attribute corresponding to attName
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTML.Attribute

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTML.Attribute

java.lang.Object
    extended by  javax.swing.text.html.HTML.Attribute
Enclosing class:
HTML
public static final class HTML.Attribute
extends Object

Typesafe enumeration representing an HTML attribute.

Field Summary
static HTML.Attribute | ACTION
static HTML.Attribute | ALIGN
static HTML.Attribute | ALINK
static HTML.Attribute | ALT
static HTML.Attribute | ARCHIVE
static HTML.Attribute | BACKGROUND
static HTML.Attribute | BGCOLOR
static HTML.Attribute | BORDER
static HTML.Attribute | CELLPADDING
static HTML.Attribute | CELLSPACING
static HTML.Attribute | CHECKED
static HTML.Attribute | CLASS
static HTML.Attribute | CLASSID
static HTML.Attribute | CLEAR
static HTML.Attribute | CODE
static HTML.Attribute | CODEBASE
static HTML.Attribute | CODETYPE
static HTML.Attribute | COLOR
static HTML.Attribute | COLS
static HTML.Attribute | COLSPAN
static HTML.Attribute | COMMENT
static HTML.Attribute | COMPACT
static HTML.Attribute | CONTENT
static HTML.Attribute | COORDS
static HTML.Attribute | DATA
static HTML.Attribute | DECLARE
static HTML.Attribute | DIR
static HTML.Attribute | DUMMY
static HTML.Attribute | ENCTYPE
static HTML.Attribute | ENDTAG
static HTML.Attribute | FACE
static HTML.Attribute | FRAMEBORDER
static HTML.Attribute | HALIGN
static HTML.Attribute | HEIGHT
static HTML.Attribute | HREF
static HTML.Attribute | HSPACE
static HTML.Attribute | HTTPEQUIV
static HTML.Attribute | ID
static HTML.Attribute | ISMAP
static HTML.Attribute | LANG
static HTML.Attribute | LANGUAGE
static HTML.Attribute | LINK
static HTML.Attribute | LOWSRC
static HTML.Attribute | MARGINHEIGHT
static HTML.Attribute | MARGINWIDTH
static HTML.Attribute | MAXLENGTH
static HTML.Attribute | METHOD
static HTML.Attribute | MULTIPLE
static HTML.Attribute | N
static HTML.Attribute | NAME
static HTML.Attribute | NOHREF
static HTML.Attribute | NORESIZE
static HTML.Attribute | NOSHADE
static HTML.Attribute | NOWRAP
static HTML.Attribute | PROMPT
static HTML.Attribute | REL
static HTML.Attribute | REV
static HTML.Attribute | ROWS
static HTML.Attribute | ROWSPAN
static HTML.Attribute | SCROLLING
static HTML.Attribute | SELECTED
static HTML.Attribute | SHAPE
static HTML.Attribute | SHAPES
static HTML.Attribute | SIZE
static HTML.Attribute | SRC
static HTML.Attribute | STANDBY
static HTML.Attribute | START
static HTML.Attribute | STYLE
static HTML.Attribute | TARGET
static HTML.Attribute | TEXT
static HTML.Attribute | TITLE
static HTML.Attribute | TYPE
static HTML.Attribute | USEMAP
static HTML.Attribute | VALIGN
static HTML.Attribute | VALUE
static HTML.Attribute | VALUETYPE
static HTML.Attribute | VERSION
static HTML.Attribute | VLINK
static HTML.Attribute | VSPACE
static HTML.Attribute | WIDTH
Method Summary
 String toString()
Returns the string representation of this attribute.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

SIZE

public static final HTML.Attribute SIZE

COLOR

public static final HTML.Attribute COLOR

CLEAR

public static final HTML.Attribute CLEAR

BACKGROUND

public static final HTML.Attribute BACKGROUND

BGCOLOR

public static final HTML.Attribute BGCOLOR

TEXT

public static final HTML.Attribute TEXT

LINK

public static final HTML.Attribute LINK

VLINK

public static final HTML.Attribute VLINK

ALINK

public static final HTML.Attribute ALINK

WIDTH

public static final HTML.Attribute WIDTH

HEIGHT

public static final HTML.Attribute HEIGHT

ALIGN

public static final HTML.Attribute ALIGN

NAME

public static final HTML.Attribute NAME

HREF

public static final HTML.Attribute HREF

REL

public static final HTML.Attribute REL

REV

public static final HTML.Attribute REV

TITLE

public static final HTML.Attribute TITLE

TARGET

public static final HTML.Attribute TARGET

SHAPE

public static final HTML.Attribute SHAPE

COORDS

public static final HTML.Attribute COORDS

ISMAP

public static final HTML.Attribute ISMAP

NOHREF

public static final HTML.Attribute NOHREF

ALT

public static final HTML.Attribute ALT

ID

public static final HTML.Attribute ID

SRC

public static final HTML.Attribute SRC

HSPACE

public static final HTML.Attribute HSPACE

VSPACE

public static final HTML.Attribute VSPACE

USEMAP

public static final HTML.Attribute USEMAP

LOWSRC

public static final HTML.Attribute LOWSRC

CODEBASE

public static final HTML.Attribute CODEBASE

CODE

public static final HTML.Attribute CODE

ARCHIVE

public static final HTML.Attribute ARCHIVE

VALUE

public static final HTML.Attribute VALUE

VALUETYPE

public static final HTML.Attribute VALUETYPE

TYPE

public static final HTML.Attribute TYPE

CLASS

public static final HTML.Attribute CLASS

STYLE

public static final HTML.Attribute STYLE

LANG

public static final HTML.Attribute LANG

FACE

public static final HTML.Attribute FACE

DIR

public static final HTML.Attribute DIR

DECLARE

public static final HTML.Attribute DECLARE

CLASSID

public static final HTML.Attribute CLASSID

DATA

public static final HTML.Attribute DATA

CODETYPE

public static final HTML.Attribute CODETYPE

STANDBY

public static final HTML.Attribute STANDBY

BORDER

public static final HTML.Attribute BORDER

SHAPES

public static final HTML.Attribute SHAPES

NOSHADE

public static final HTML.Attribute NOSHADE

COMPACT

public static final HTML.Attribute COMPACT

START

public static final HTML.Attribute START

ACTION

public static final HTML.Attribute ACTION

METHOD

public static final HTML.Attribute METHOD

ENCTYPE

public static final HTML.Attribute ENCTYPE

CHECKED

public static final HTML.Attribute CHECKED

MAXLENGTH

public static final HTML.Attribute MAXLENGTH

MULTIPLE

public static final HTML.Attribute MULTIPLE

SELECTED

public static final HTML.Attribute SELECTED

ROWS

public static final HTML.Attribute ROWS

COLS

public static final HTML.Attribute COLS

DUMMY

public static final HTML.Attribute DUMMY

CELLSPACING

public static final HTML.Attribute CELLSPACING

CELLPADDING

public static final HTML.Attribute CELLPADDING

VALIGN

public static final HTML.Attribute VALIGN

HALIGN

public static final HTML.Attribute HALIGN

NOWRAP

public static final HTML.Attribute NOWRAP

ROWSPAN

public static final HTML.Attribute ROWSPAN

COLSPAN

public static final HTML.Attribute COLSPAN

PROMPT

public static final HTML.Attribute PROMPT

HTTPEQUIV

public static final HTML.Attribute HTTPEQUIV

CONTENT

public static final HTML.Attribute CONTENT

LANGUAGE

public static final HTML.Attribute LANGUAGE

VERSION

public static final HTML.Attribute VERSION

N

public static final HTML.Attribute N

FRAMEBORDER

public static final HTML.Attribute FRAMEBORDER

MARGINWIDTH

public static final HTML.Attribute MARGINWIDTH

MARGINHEIGHT

public static final HTML.Attribute MARGINHEIGHT

SCROLLING

public static final HTML.Attribute SCROLLING

NORESIZE

public static final HTML.Attribute NORESIZE

ENDTAG

public static final HTML.Attribute ENDTAG

COMMENT

public static final HTML.Attribute COMMENT
Method Detail

toString

public String toString()
Returns the string representation of this attribute.

Overrides:
toString in class Object
Returns:
the string representation of this attribute
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTML.Tag

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTML.Tag

java.lang.Object
    extended by  javax.swing.text.html.HTML.Tag
Direct Known Subclasses:
HTML.UnknownTag
Enclosing class:
HTML
public static class HTML.Tag
extends Object

Typesafe enumeration for an HTML tag. Although the set of HTML tags is a closed set, we have left the set open so that people can add their own tag types to their custom parser and still communicate to the reader.

Field Summary
static HTML.Tag | A
static HTML.Tag | ADDRESS
static HTML.Tag | APPLET
static HTML.Tag | AREA
static HTML.Tag | B
static HTML.Tag | BASE
static HTML.Tag | BASEFONT
static HTML.Tag | BIG
static HTML.Tag | BLOCKQUOTE
static HTML.Tag | BODY
static HTML.Tag | BR
static HTML.Tag | CAPTION
static HTML.Tag | CENTER
static HTML.Tag | CITE
static HTML.Tag | CODE
static HTML.Tag | COMMENT All comments are labeled with this tag.
static HTML.Tag | CONTENT All text content is labeled with this tag.
static HTML.Tag | DD
static HTML.Tag | DFN
static HTML.Tag | DIR
static HTML.Tag | DIV
static HTML.Tag | DL
static HTML.Tag | DT
static HTML.Tag | EM
static HTML.Tag | FONT
static HTML.Tag | FORM
static HTML.Tag | FRAME
static HTML.Tag | FRAMESET
static HTML.Tag | H1
static HTML.Tag | H2
static HTML.Tag | H3
static HTML.Tag | H4
static HTML.Tag | H5
static HTML.Tag | H6
static HTML.Tag | HEAD
static HTML.Tag | HR
static HTML.Tag | HTML
static HTML.Tag | I
static HTML.Tag | IMG
static HTML.Tag | IMPLIED All text content must be in a paragraph element.
static HTML.Tag | INPUT
static HTML.Tag | ISINDEX
static HTML.Tag | KBD
static HTML.Tag | LI
static HTML.Tag | LINK
static HTML.Tag | MAP
static HTML.Tag | MENU
static HTML.Tag | META
static HTML.Tag | NOFRAMES
static HTML.Tag | OBJECT
static HTML.Tag | OL
static HTML.Tag | OPTION
static HTML.Tag | P
static HTML.Tag | PARAM
static HTML.Tag | PRE
static HTML.Tag | S
static HTML.Tag | SAMP
static HTML.Tag | SCRIPT
static HTML.Tag | SELECT
static HTML.Tag | SMALL
static HTML.Tag | SPAN
static HTML.Tag | STRIKE
static HTML.Tag | STRONG
static HTML.Tag | STYLE
static HTML.Tag | SUB
static HTML.Tag | SUP
static HTML.Tag | TABLE
static HTML.Tag | TD
static HTML.Tag | TEXTAREA
static HTML.Tag | TH
static HTML.Tag | TITLE
static HTML.Tag | TR
static HTML.Tag | TT
static HTML.Tag | U
static HTML.Tag | UL
static HTML.Tag | VAR
Constructor Summary
 | HTML.Tag()
protected | HTML.Tag(String id) Creates a new Tag with the specified id, and with causesBreak and isBlock set to false.
protected | HTML.Tag(String id, boolean causesBreak, boolean isBlock) Creates a new Tag with the specified id; causesBreak and isBlock are defined by the user.
Method Summary
boolean | breaksFlow() Returns true if this tag causes a line break to the flow of data, otherwise returns false.
boolean | isBlock() Returns true if this tag is a block tag, which is a tag used to add structure to a document.
boolean | isPreformatted() Returns true if this tag is pre-formatted, which is true if the tag is either PRE or TEXTAREA.
String | toString() Returns the string representation of the tag.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

A

public static final HTML.Tag A

ADDRESS

public static final HTML.Tag ADDRESS

APPLET

public static final HTML.Tag APPLET

AREA

public static final HTML.Tag AREA

B

public static final HTML.Tag B

BASE

public static final HTML.Tag BASE

BASEFONT

public static final HTML.Tag BASEFONT

BIG

public static final HTML.Tag BIG

BLOCKQUOTE

public static final HTML.Tag BLOCKQUOTE

BODY

public static final HTML.Tag BODY

BR

public static final HTML.Tag BR

CAPTION

public static final HTML.Tag CAPTION

CENTER

public static final HTML.Tag CENTER

CITE

public static final HTML.Tag CITE

CODE

public static final HTML.Tag CODE

DD

public static final HTML.Tag DD

DFN

public static final HTML.Tag DFN

DIR

public static final HTML.Tag DIR

DIV

public static final HTML.Tag DIV

DL

public static final HTML.Tag DL

DT

public static final HTML.Tag DT

EM

public static final HTML.Tag EM

FONT

public static final HTML.Tag FONT

FORM

public static final HTML.Tag FORM

FRAME

public static final HTML.Tag FRAME

FRAMESET

public static final HTML.Tag FRAMESET

H1

public static final HTML.Tag H1

H2

public static final HTML.Tag H2

H3

public static final HTML.Tag H3

H4

public static final HTML.Tag H4

H5

public static final HTML.Tag H5

H6

public static final HTML.Tag H6

HEAD

public static final HTML.Tag HEAD

HR

public static final HTML.Tag HR

HTML

public static final HTML.Tag HTML

I

public static final HTML.Tag I

IMG

public static final HTML.Tag IMG

INPUT

public static final HTML.Tag INPUT

ISINDEX

public static final HTML.Tag ISINDEX

KBD

public static final HTML.Tag KBD

LI

public static final HTML.Tag LI

LINK

public static final HTML.Tag LINK

MAP

public static final HTML.Tag MAP

MENU

public static final HTML.Tag MENU

META

public static final HTML.Tag META

NOFRAMES

public static final HTML.Tag NOFRAMES

OBJECT

public static final HTML.Tag OBJECT

OL

public static final HTML.Tag OL

OPTION

public static final HTML.Tag OPTION

P

public static final HTML.Tag P

PARAM

public static final HTML.Tag PARAM

PRE

public static final HTML.Tag PRE

SAMP

public static final HTML.Tag SAMP

SCRIPT

public static final HTML.Tag SCRIPT

SELECT

public static final HTML.Tag SELECT

SMALL

public static final HTML.Tag SMALL

SPAN

public static final HTML.Tag SPAN

STRIKE

public static final HTML.Tag STRIKE

S

public static final HTML.Tag S

STRONG

public static final HTML.Tag STRONG

STYLE

public static final HTML.Tag STYLE

SUB

public static final HTML.Tag SUB

SUP

public static final HTML.Tag SUP

TABLE

public static final HTML.Tag TABLE

TD

public static final HTML.Tag TD

TEXTAREA

public static final HTML.Tag TEXTAREA

TH

public static final HTML.Tag TH

TITLE

public static final HTML.Tag TITLE

TR

public static final HTML.Tag TR

TT

public static final HTML.Tag TT

U

public static final HTML.Tag U

UL

public static final HTML.Tag UL

VAR

public static final HTML.Tag VAR

IMPLIED

public static final HTML.Tag IMPLIED
All text content must be in a paragraph element. If a paragraph didn't exist when content was encountered, a paragraph is manufactured.

This is a tag synthesized by the HTML reader. Since elements are identified by their tag type, we create a some fake tag types to mark the elements that were manufactured.

CONTENT

public static final HTML.Tag CONTENT
All text content is labeled with this tag.

This is a tag synthesized by the HTML reader. Since elements are identified by their tag type, we create a some fake tag types to mark the elements that were manufactured.

COMMENT

public static final HTML.Tag COMMENT
All comments are labeled with this tag.

This is a tag synthesized by the HTML reader. Since elements are identified by their tag type, we create a some fake tag types to mark the elements that were manufactured.

Constructor Detail

HTML.Tag

public HTML.Tag()
Since:
1.3

HTML.Tag

protected HTML.Tag(String id)
Creates a new Tag with the specified id, and with causesBreak and isBlock set to false.

Parameters:
id - the id of the new tag

HTML.Tag

protected HTML.Tag(String id,
                   boolean causesBreak,
                   boolean isBlock)
Creates a new Tag with the specified id; causesBreak and isBlock are defined by the user.

Parameters:
id - the id of the new tag
causesBreak - true if this tag causes a break to the flow of data
isBlock - true if the tag is used to add structure to a document
Method Detail

isBlock

public boolean isBlock()
Returns true if this tag is a block tag, which is a tag used to add structure to a document.

Returns:
true if this tag is a block tag, otherwise returns false

breaksFlow

public boolean breaksFlow()
Returns true if this tag causes a line break to the flow of data, otherwise returns false.

Returns:
true if this tag causes a line break to the flow of data, otherwise returns false

isPreformatted

public boolean isPreformatted()
Returns true if this tag is pre-formatted, which is true if the tag is either PRE or TEXTAREA.

Returns:
true if this tag is pre-formatted, otherwise returns false

toString

public String toString()
Returns the string representation of the tag.

Overrides:
toString in class Object
Returns:
the String representation of the tag
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTML.UnknownTag

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTML.UnknownTag

java.lang.Object
    extended by  javax.swing.text.html.HTML.Tag
        extended by  javax.swing.text.html.HTML.UnknownTag
All Implemented Interfaces:
Serializable
Enclosing class:
HTML
public static class HTML.UnknownTag
extends HTML.Tag
implements Serializable

Field Summary
Fields inherited from class javax.swing.text.html.HTML.Tag
A, ADDRESS, APPLET, AREA, B, BASE, BASEFONT, BIG, BLOCKQUOTE, BODY, BR, CAPTION, CENTER, CITE, CODE, COMMENT, CONTENT, DD, DFN, DIR, DIV, DL, DT, EM, FONT, FORM, FRAME, FRAMESET, H1, H2, H3, H4, H5, H6, HEAD, HR, HTML, I, IMG, IMPLIED, INPUT, ISINDEX, KBD, LI, LINK, MAP, MENU, META, NOFRAMES, OBJECT, OL, OPTION, P, PARAM, PRE, S, SAMP, SCRIPT, SELECT, SMALL, SPAN, STRIKE, STRONG, STYLE, SUB, SUP, TABLE, TD, TEXTAREA, TH, TITLE, TR, TT, U, UL, VAR
Constructor Summary
HTML.UnknownTag(String id)
Creates a new UnknownTag with the specified id.
Method Summary
boolean | equals(Object obj) Compares this object to the specifed object.
int | hashCode() Returns the hash code which corresponds to the string for this tag.
Methods inherited from class javax.swing.text.html.HTML.Tag
breaksFlow, isBlock, isPreformatted, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

HTML.UnknownTag

public HTML.UnknownTag(String id)
Creates a new UnknownTag with the specified id.

Parameters:
id - the id of the new tag
Method Detail

hashCode

public int hashCode()
Returns the hash code which corresponds to the string for this tag.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object obj)
Compares this object to the specifed object. The result is true if and only if the argument is not null and is an UnknownTag object with the same name.

Overrides:
equals in class Object
Parameters:
obj - the object to compare this tag with
Returns:
true if the objects are equal; false otherwise
See Also:
Object.hashCode(), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLDocument

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLDocument

java.lang.Object
    extended by  javax.swing.text.AbstractDocument
        extended by  javax.swing.text.DefaultStyledDocument
            extended by  javax.swing.text.html.HTMLDocument
All Implemented Interfaces:
Serializable, Document, StyledDocument
public class HTMLDocument
extends DefaultStyledDocument

A document that models HTML. The purpose of this model is to support both browsing and editing. As a result, the structure described by an HTML document is not exactly replicated by default. The element structure that is modeled by default, is built by the class HTMLDocument.HTMLReader, which implements the HTMLEditorKit.ParserCallback protocol that the parser expects. To change the structure one can subclass HTMLReader, and reimplement the method getReader(int) to return the new reader implementation. The documentation for HTMLReader should be consulted for the details of the default structure created. The intent is that the document be non-lossy (although reproducing the HTML format may result in a different format).

The document models only HTML, and makes no attempt to store view attributes in it. The elements are identified by the StyleContext.NameAttribute attribute, which should always have a value of type HTML.Tag that identifies the kind of element. Some of the elements (such as comments) are synthesized. The HTMLFactory uses this attribute to determine what kind of view to build.

This document supports incremental loading. The TokenThreshold property controls how much of the parse is buffered before trying to update the element structure of the document. This property is set by the EditorKit so that subclasses can disable it.

The Base property determines the URL against which relative URLs are resolved. By default, this will be the Document.StreamDescriptionProperty if the value of the property is a URL. If a <BASE> tag is encountered, the base will become the URL specified by that tag. Because the base URL is a property, it can of course be set directly.

The default content storage mechanism for this document is a gap buffer (GapContent). Alternatives can be supplied by using the constructor that takes a Content implementation.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
class | HTMLDocument.BlockElement An element that represents a structural block of HTML.
class | HTMLDocument.HTMLReader An HTML reader to load an HTML document with an HTML element structure.
static class | HTMLDocument.Iterator An iterator to iterate over a particular type of tag.
class | HTMLDocument.RunElement An element that represents a chunk of text that has a set of HTML character level attributes assigned to it.
Nested classes/interfaces inherited from class javax.swing.text.DefaultStyledDocument
DefaultStyledDocument.AttributeUndoableEdit, DefaultStyledDocument.ElementBuffer, DefaultStyledDocument.ElementSpec, DefaultStyledDocument.SectionElement
Nested classes/interfaces inherited from class javax.swing.text.AbstractDocument
AbstractDocument.AbstractElement, AbstractDocument.AttributeContext, AbstractDocument.BranchElement, AbstractDocument.Content, AbstractDocument.DefaultDocumentEvent, AbstractDocument.ElementEdit, AbstractDocument.LeafElement
Field Summary
static String AdditionalComments
Document property key value.
Fields inherited from class javax.swing.text.DefaultStyledDocument
buffer, BUFFER_SIZE_DEFAULT
Fields inherited from class javax.swing.text.AbstractDocument
BAD_LOCATION, BidiElementName, ContentElementName, ElementNameAttribute, listenerList, ParagraphElementName, SectionElementName
Fields inherited from interface javax.swing.text.Document
StreamDescriptionProperty, TitleProperty
Constructor Summary
HTMLDocument()
Constructs an HTML document using the default buffer size and a default StyleSheet.
HTMLDocument(AbstractDocument.Content c, StyleSheet styles)
Constructs an HTML document with the given content storage implementation and the given style/attribute storage mechanism.
HTMLDocument(StyleSheet styles)
Constructs an HTML document with the default content storage implementation and the specified style/attribute storage mechanism.
Method Summary
protected void | create(DefaultStyledDocument.ElementSpec[] data) Replaces the contents of the document with the given element specifications.
protected Element | createBranchElement(Element parent, AttributeSet a) Creates a document branch element, that can contain other elements.
protected AbstractDocument.AbstractElement | createDefaultRoot() Creates the root element to be used to represent the default document structure.
protected Element | createLeafElement(Element parent, AttributeSet a, int p0, int p1) Creates a document leaf element that directly represents text (doesn't have any children).
protected void | fireChangedUpdate(DocumentEvent e) Notifies all listeners that have registered interest for notification on this event type.
protected void | fireUndoableEditUpdate(UndoableEditEvent e) Notifies all listeners that have registered interest for notification on this event type.
URL | getBase() Returns the location to resolve relative URLs against.
Element | getElement(Element e, Object attribute, Object value) Returns the child element of e that contains the attribute, attribute with value value, or null if one isn't found.
Element | getElement(String id) Returns the element that has the given id Attribute.
HTMLDocument.Iterator | getIterator(HTML.Tag t) Fetches an iterator for the specified HTML tag.
HTMLEditorKit.Parser | getParser() Returns the parser that is used when inserting HTML into the existing document.
boolean | getPreservesUnknownTags() Returns the behavior the parser observes when encountering unknown tags.
HTMLEditorKit.ParserCallback | getReader(int pos) Fetches the reader for the parser to use when loading the document with HTML.
HTMLEditorKit.ParserCallback | getReader(int pos, int popDepth, int pushDepth, HTML.Tag insertTag) Returns the reader for the parser to use to load the document with HTML.
StyleSheet | getStyleSheet() Fetches the StyleSheet with the document-specific display rules (CSS) that were specified in the HTML document itself.
int | getTokenThreshold() Gets the number of tokens to buffer before trying to update the documents element structure.
protected void | insert(int offset, DefaultStyledDocument.ElementSpec[] data) Inserts new elements in bulk.
void | insertAfterEnd(Element elem, String htmlText) Inserts the HTML specified as a string after the the end of the given element.
void | insertAfterStart(Element elem, String htmlText) Inserts the HTML specified as a string at the start of the element.
void | insertBeforeEnd(Element elem, String htmlText) Inserts the HTML specified as a string at the end of the element.
void | insertBeforeStart(Element elem, String htmlText) Inserts the HTML specified as a string before the start of the given element.
protected void | insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr) Updates document structure as a result of text insertion.
void | processHTMLFrameHyperlinkEvent(HTMLFrameHyperlinkEvent e) Processes HyperlinkEvents that are generated by documents in an HTML frame.
void | setBase(URL u) Sets the location to resolve relative URLs against.
void | setInnerHTML(Element elem, String htmlText) Replaces the children of the given element with the contents specified as an HTML string.
void | setOuterHTML(Element elem, String htmlText) Replaces the given element in the parent with the contents specified as an HTML string.
void | setParagraphAttributes(int offset, int length, AttributeSet s, boolean replace) Sets attributes for a paragraph.
void | setParser(HTMLEditorKit.Parser parser) Sets the parser that is used by the methods that insert html into the existing document, such as setInnerHTML, and setOuterHTML.
void | setPreservesUnknownTags(boolean preservesTags) Determines how unknown tags are handled by the parser.
void | setTokenThreshold(int n) Sets the number of tokens to buffer before trying to update the documents element structure.
Methods inherited from class javax.swing.text.DefaultStyledDocument
addDocumentListener, addStyle, getBackground, getCharacterElement, getDefaultRootElement, getFont, getForeground, getLogicalStyle, getParagraphElement, getStyle, getStyleNames, removeDocumentListener, removeStyle, removeUpdate, setCharacterAttributes, setLogicalStyle, styleChanged
Methods inherited from class javax.swing.text.AbstractDocument
addUndoableEditListener, createPosition, dump, fireInsertUpdate, fireRemoveUpdate, getAsynchronousLoadPriority, getAttributeContext, getBidiRootElement, getContent, getCurrentWriter, getDocumentFilter, getDocumentListeners, getDocumentProperties, getEndPosition, getLength, getListeners, getProperty, getRootElements, getStartPosition, getText, getText, getUndoableEditListeners, insertString, postRemoveUpdate, putProperty, readLock, readUnlock, remove, removeUndoableEditListener, render, replace, setAsynchronousLoadPriority, setDocumentFilter, setDocumentProperties, writeLock, writeUnlock
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.swing.text.Document
addUndoableEditListener, createPosition, getEndPosition, getLength, getProperty, getRootElements, getStartPosition, getText, getText, insertString, putProperty, remove, removeUndoableEditListener, render

Field Detail

AdditionalComments

public static final String AdditionalComments
Document property key value. The value for the key will be a Vector of Strings that are comments not found in the body.

See Also:
Constant Field Values
Constructor Detail

HTMLDocument

public HTMLDocument()
Constructs an HTML document using the default buffer size and a default StyleSheet. This is a convenience method for the constructor HTMLDocument(Content, StyleSheet).

HTMLDocument

public HTMLDocument(StyleSheet styles)
Constructs an HTML document with the default content storage implementation and the specified style/attribute storage mechanism. This is a convenience method for the constructor HTMLDocument(Content, StyleSheet).

Parameters:
styles - the styles

HTMLDocument

public HTMLDocument(AbstractDocument.Content c,
                    StyleSheet styles)
Constructs an HTML document with the given content storage implementation and the given style/attribute storage mechanism.

Parameters:
c - the container for the content
styles - the styles
Method Detail

getReader

public HTMLEditorKit.ParserCallback getReader(int pos)
Fetches the reader for the parser to use when loading the document with HTML. This is implemented to return an instance of HTMLDocument.HTMLReader. Subclasses can reimplement this method to change how the document gets structured if desired. (For example, to handle custom tags, or structurally represent character style elements.)

Parameters:
pos - the starting position
Returns:
the reader used by the parser to load the document

getReader

public HTMLEditorKit.ParserCallback getReader(int pos,
                                              int popDepth,
                                              int pushDepth,
                                              HTML.Tag insertTag)
Returns the reader for the parser to use to load the document with HTML. This is implemented to return an instance of HTMLDocument.HTMLReader. Subclasses can reimplement this method to change how the document gets structured if desired. (For example, to handle custom tags, or structurally represent character style elements.)

This is a convenience method for getReader(int, int, int, HTML.Tag, TRUE).

Parameters:
popDepth - the number of ElementSpec.EndTagTypes to generate before inserting
pushDepth - the number of ElementSpec.StartTagTypes with a direction of ElementSpec.JoinNextDirection that should be generated before inserting, but after the end tags have been generated
insertTag - the first tag to start inserting into document
Returns:
the reader used by the parser to load the document

getBase

public URL getBase()
Returns the location to resolve relative URLs against. By default this will be the document's URL if the document was loaded from a URL. If a base tag is found and can be parsed, it will be used as the base location.

Returns:
the base location

setBase

public void setBase(URL u)
Sets the location to resolve relative URLs against. By default this will be the document's URL if the document was loaded from a URL. If a base tag is found and can be parsed, it will be used as the base location.

This also sets the base of the StyleSheet to be u as well as the base of the document.

Parameters:
u - the desired base URL

insert

protected void insert(int offset,
                      DefaultStyledDocument.ElementSpec[] data)
               throws BadLocationException
Inserts new elements in bulk. This is how elements get created in the document. The parsing determines what structure is needed and creates the specification as a set of tokens that describe the edit while leaving the document free of a write-lock. This method can then be called in bursts by the reader to acquire a write-lock for a shorter duration (i.e. while the document is actually being altered).

Overrides:
insert in class DefaultStyledDocument
Parameters:
offset - the starting offset
data - the element data
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document.

insertUpdate

protected void insertUpdate(AbstractDocument.DefaultDocumentEvent chng,
                            AttributeSet attr)
Updates document structure as a result of text insertion. This will happen within a write lock. This implementation simply parses the inserted content for line breaks and builds up a set of instructions for the element buffer.

Overrides:
insertUpdate in class DefaultStyledDocument
Parameters:
chng - a description of the document change
attr - the attributes

create

protected void create(DefaultStyledDocument.ElementSpec[] data)
Replaces the contents of the document with the given element specifications. This is called before insert if the loading is done in bursts. This is the only method called if loading the document entirely in one burst.

Overrides:
create in class DefaultStyledDocument
Parameters:
data - the new contents of the document

setParagraphAttributes

public void setParagraphAttributes(int offset,
                                   int length,
                                   AttributeSet s,
                                   boolean replace)
Sets attributes for a paragraph.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Specified by:
setParagraphAttributes in interface StyledDocument
Overrides:
setParagraphAttributes in class DefaultStyledDocument
Parameters:
offset - the offset into the paragraph (must be at least 0)
length - the number of characters affected (must be at least 0)
s - the attributes
replace - whether to replace existing attributes, or merge them

getStyleSheet

public StyleSheet getStyleSheet()
Fetches the StyleSheet with the document-specific display rules (CSS) that were specified in the HTML document itself.

Returns:
the StyleSheet

getIterator

public HTMLDocument.Iterator getIterator(HTML.Tag t)
Fetches an iterator for the specified HTML tag. This can be used for things like iterating over the set of anchors contained, or iterating over the input elements.

Parameters:
t - the requested HTML.Tag
Returns:
the Iterator for the given HTML tag
See Also:
HTML.Tag

createLeafElement

protected Element createLeafElement(Element parent,
                                    AttributeSet a,
                                    int p0,
                                    int p1)
Creates a document leaf element that directly represents text (doesn't have any children). This is implemented to return an element of type HTMLDocument.RunElement.

Overrides:
createLeafElement in class AbstractDocument
Parameters:
parent - the parent element
a - the attributes for the element
p0 - the beginning of the range (must be at least 0)
p1 - the end of the range (must be at least p0)
Returns:
the new element

createBranchElement

protected Element createBranchElement(Element parent,
                                      AttributeSet a)
Creates a document branch element, that can contain other elements. This is implemented to return an element of type HTMLDocument.BlockElement.

Overrides:
createBranchElement in class AbstractDocument
Parameters:
parent - the parent element
a - the attributes
Returns:
the element

createDefaultRoot

protected AbstractDocument.AbstractElement createDefaultRoot()
Creates the root element to be used to represent the default document structure.

Overrides:
createDefaultRoot in class DefaultStyledDocument
Returns:
the element base

setTokenThreshold

public void setTokenThreshold(int n)
Sets the number of tokens to buffer before trying to update the documents element structure.

Parameters:
n - the number of tokens to buffer

getTokenThreshold

public int getTokenThreshold()
Gets the number of tokens to buffer before trying to update the documents element structure. The default value is Integer.MAX_VALUE.

Returns:
the number of tokens to buffer

setPreservesUnknownTags

public void setPreservesUnknownTags(boolean preservesTags)
Determines how unknown tags are handled by the parser. If set to true, unknown tags are put in the model, otherwise they are dropped.

Parameters:
preservesTags - true if unknown tags should be saved in the model, otherwise tags are dropped
See Also:
HTML.Tag

getPreservesUnknownTags

public boolean getPreservesUnknownTags()
Returns the behavior the parser observes when encountering unknown tags.

Returns:
true if unknown tags are to be preserved when parsing
See Also:
HTML.Tag

processHTMLFrameHyperlinkEvent

public void processHTMLFrameHyperlinkEvent(HTMLFrameHyperlinkEvent e)
Processes HyperlinkEvents that are generated by documents in an HTML frame. The HyperlinkEvent type, as the parameter suggests, is HTMLFrameHyperlinkEvent. In addition to the typical information contained in a HyperlinkEvent, this event contains the element that corresponds to the frame in which the click happened (the source element) and the target name. The target name has 4 possible values:
  • _self
  • _parent
  • _top
  • a named frame
If target is _self, the action is to change the value of the HTML.Attribute.SRC attribute and fires a ChangedUpdate event.

If the target is _parent, then it deletes the parent element, which is a <FRAMESET> element, and inserts a new <FRAME> element, and sets its HTML.Attribute.SRC attribute to have a value equal to the destination URL and fire a RemovedUpdate and InsertUpdate.

If the target is _top, this method does nothing. In the implementation of the view for a frame, namely the FrameView, the processing of _top is handled. Given that _top implies replacing the entire document, it made sense to handle this outside of the document that it will replace.

If the target is a named frame, then the element hierarchy is searched for an element with a name equal to the target, its HTML.Attribute.SRC attribute is updated and a ChangedUpdate event is fired.

Parameters:
e - the event

setParser

public void setParser(HTMLEditorKit.Parser parser)
Sets the parser that is used by the methods that insert html into the existing document, such as setInnerHTML, and setOuterHTML.

HTMLEditorKit.createDefaultDocument will set the parser for you. If you create an HTMLDocument by hand, be sure and set the parser accordingly.

Parameters:
parser - the parser to be used for text insertion
Since:
1.3

getParser

public HTMLEditorKit.Parser getParser()
Returns the parser that is used when inserting HTML into the existing document.

Returns:
the parser used for text insertion
Since:
1.3

setInnerHTML

public void setInnerHTML(Element elem,
                         String htmlText)
                  throws BadLocationException,
                         IOException
Replaces the children of the given element with the contents specified as an HTML string.

This will be seen as at least two events, n inserts followed by a remove.

For this to work correcty, the document must have an HTMLEditorKit.Parser set. This will be the case if the document was created from an HTMLEditorKit via the createDefaultDocument method.

Parameters:
elem - the branch element whose children will be replaced
htmlText - the string to be parsed and assigned to elem
Throws:
IllegalArgumentException - if elem is a leaf
IllegalStateException - if an HTMLEditorKit.Parser has not been defined
BadLocationException
IOException
Since:
1.3

setOuterHTML

public void setOuterHTML(Element elem,
                         String htmlText)
                  throws BadLocationException,
                         IOException
Replaces the given element in the parent with the contents specified as an HTML string.

This will be seen as at least two events, n inserts followed by a remove.

When replacing a leaf this will attempt to make sure there is a newline present if one is needed. This may result in an additional element being inserted. Consider, if you were to replace a character element that contained a newline with <img> this would create two elements, one for the image, ane one for the newline.

If you try to replace the element at length you will most likely end up with two elements, eg setOuterHTML(getCharacterElement (getLength()), "blah") will result in two leaf elements at the end, one representing 'blah', and the other representing the end element.

For this to work correcty, the document must have an HTMLEditorKit.Parser set. This will be the case if the document was created from an HTMLEditorKit via the createDefaultDocument method.

Parameters:
elem - the branch element whose children will be replaced
htmlText - the string to be parsed and assigned to elem
Throws:
IllegalStateException - if an HTMLEditorKit.Parser has not been set
BadLocationException
IOException
Since:
1.3

insertAfterStart

public void insertAfterStart(Element elem,
                             String htmlText)
                      throws BadLocationException,
                             IOException
Inserts the HTML specified as a string at the start of the element.

For this to work correcty, the document must have an HTMLEditorKit.Parser set. This will be the case if the document was created from an HTMLEditorKit via the createDefaultDocument method.

Parameters:
elem - the branch element to be the root for the new text
htmlText - the string to be parsed and assigned to elem
Throws:
IllegalStateException - if an HTMLEditorKit.Parser has not been set on the document
BadLocationException
IOException
Since:
1.3

insertBeforeEnd

public void insertBeforeEnd(Element elem,
                            String htmlText)
                     throws BadLocationException,
                            IOException
Inserts the HTML specified as a string at the end of the element.

If elem's children are leaves, and the character at a elem.getEndOffset() - 1 is a newline, this will insert before the newline so that there isn't text after the newline.

For this to work correcty, the document must have an HTMLEditorKit.Parser set. This will be the case if the document was created from an HTMLEditorKit via the createDefaultDocument method.

Parameters:
elem - the element to be the root for the new text
htmlText - the string to be parsed and assigned to elem
Throws:
IllegalStateException - if an HTMLEditorKit.Parser has not been set on the document
BadLocationException
IOException
Since:
1.3

insertBeforeStart

public void insertBeforeStart(Element elem,
                              String htmlText)
                       throws BadLocationException,
                              IOException
Inserts the HTML specified as a string before the start of the given element.

For this to work correcty, the document must have an HTMLEditorKit.Parser set. This will be the case if the document was created from an HTMLEditorKit via the createDefaultDocument method.

Parameters:
elem - the element to be the root for the new text
htmlText - the string to be parsed and assigned to elem
Throws:
IllegalStateException - if an HTMLEditorKit.Parser has not been set on the document
BadLocationException
IOException
Since:
1.3

insertAfterEnd

public void insertAfterEnd(Element elem,
                           String htmlText)
                    throws BadLocationException,
                           IOException
Inserts the HTML specified as a string after the the end of the given element.

For this to work correcty, the document must have an HTMLEditorKit.Parser set. This will be the case if the document was created from an HTMLEditorKit via the createDefaultDocument method.

Parameters:
elem - the element to be the root for the new text
htmlText - the string to be parsed and assigned to elem
Throws:
IllegalStateException - if an HTMLEditorKit.Parser has not been set on the document
BadLocationException
IOException
Since:
1.3

getElement

public Element getElement(String id)
Returns the element that has the given id Attribute. If the element can't be found, null is returned. Note that this method works on an Attribute, not a character tag. In the following HTML snippet: <a id="HelloThere"> the attribute is 'id' and the character tag is 'a'. This is a convenience method for getElement(RootElement, HTML.Attribute.id, id). This is not thread-safe.

Parameters:
id - the string representing the desired Attribute
Returns:
the element with the specified Attribute or null if it can't be found, or null if id is null
Since:
1.3
See Also:
HTML.Attribute

getElement

public Element getElement(Element e,
                          Object attribute,
                          Object value)
Returns the child element of e that contains the attribute, attribute with value value, or null if one isn't found. This is not thread-safe.

Parameters:
e - the root element where the search begins
attribute - the desired Attribute
value - the values for the specified Attribute
Returns:
the element with the specified Attribute and the specified value, or null if it can't be found
Since:
1.3
See Also:
HTML.Attribute

fireChangedUpdate

protected void fireChangedUpdate(DocumentEvent e)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

Overrides:
fireChangedUpdate in class AbstractDocument
Parameters:
e - the event
See Also:
EventListenerList

fireUndoableEditUpdate

protected void fireUndoableEditUpdate(UndoableEditEvent e)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

Overrides:
fireUndoableEditUpdate in class AbstractDocument
Parameters:
e - the event
See Also:
EventListenerList
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLDocument.BlockElement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLDocument.BlockElement

java.lang.Object
    extended by  javax.swing.text.AbstractDocument.AbstractElement
        extended by  javax.swing.text.AbstractDocument.BranchElement
            extended by  javax.swing.text.html.HTMLDocument.BlockElement
All Implemented Interfaces:
Serializable, AttributeSet, Element, MutableAttributeSet, TreeNode
Enclosing class:
HTMLDocument
public class HTMLDocument.BlockElement
extends AbstractDocument.BranchElement

An element that represents a structural block of HTML.

Nested Class Summary
Nested classes/interfaces inherited from interface javax.swing.text.AttributeSet
AttributeSet.CharacterAttribute, AttributeSet.ColorAttribute, AttributeSet.FontAttribute, AttributeSet.ParagraphAttribute
Field Summary
Fields inherited from interface javax.swing.text.AttributeSet
NameAttribute, ResolveAttribute
Constructor Summary
HTMLDocument.BlockElement(Element parent, AttributeSet a)
Constructs a composite element that initially contains no children.
Method Summary
String | getName() Gets the name of the element.
AttributeSet | getResolveParent() Gets the resolving parent.
Methods inherited from class javax.swing.text.AbstractDocument.BranchElement
children, getAllowsChildren, getElement, getElementCount, getElementIndex, getEndOffset, getStartOffset, isLeaf, positionToElement, replace, toString
Methods inherited from class javax.swing.text.AbstractDocument.AbstractElement
addAttribute, addAttributes, containsAttribute, containsAttributes, copyAttributes, dump, getAttribute, getAttributeCount, getAttributeNames, getAttributes, getChildAt, getChildCount, getDocument, getIndex, getParent, getParentElement, isDefined, isEqual, removeAttribute, removeAttributes, removeAttributes, setResolveParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

HTMLDocument.BlockElement

public HTMLDocument.BlockElement(Element parent,
                                 AttributeSet a)
Constructs a composite element that initially contains no children.

Parameters:
parent - the parent element
a - the attributes for the element
Since:
1.4
Method Detail

getName

public String getName()
Gets the name of the element.

Specified by:
getName in interface Element
Overrides:
getName in class AbstractDocument.BranchElement
Returns:
the name, null if none

getResolveParent

public AttributeSet getResolveParent()
Gets the resolving parent. HTML attributes are not inherited at the model level so we override this to return null.

Specified by:
getResolveParent in interface AttributeSet
Overrides:
getResolveParent in class AbstractDocument.AbstractElement
Returns:
null, there are none
See Also:
AttributeSet.getResolveParent()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLDocument.HTMLReader

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLDocument.HTMLReader

java.lang.Object
    extended by  javax.swing.text.html.HTMLEditorKit.ParserCallback
        extended by  javax.swing.text.html.HTMLDocument.HTMLReader
Enclosing class:
HTMLDocument
public class HTMLDocument.HTMLReader
extends HTMLEditorKit.ParserCallback

An HTML reader to load an HTML document with an HTML element structure. This is a set of callbacks from the parser, implemented to create a set of elements tagged with attributes. The parse builds up tokens (ElementSpec) that describe the element subtree desired, and burst it into the document under the protection of a write lock using the insert method on the document outer class.

The reader can be configured by registering actions (of type HTMLDocument.HTMLReader.TagAction) that describe how to handle the action. The idea behind the actions provided is that the most natural text editing operations can be provided if the element structure boils down to paragraphs with runs of some kind of style in them. Some things are more naturally specified structurally, so arbitrary structure should be allowed above the paragraphs, but will need to be edited with structural actions. The implication of this is that some of the HTML elements specified in the stream being parsed will be collapsed into attributes, and in some cases paragraphs will be synthesized. When HTML elements have been converted to attributes, the attribute key will be of type HTML.Tag, and the value will be of type AttributeSet so that no information is lost. This enables many of the existing actions to work so that the user can type input, hit the return key, backspace, delete, etc and have a reasonable result. Selections can be created, and attributes applied or removed, etc. With this in mind, the work done by the reader can be categorized into the following kinds of tasks:

Block
Build the structure like it's specified in the stream. This produces elements that contain other elements.
Paragraph
Like block except that it's expected that the element will be used with a paragraph view so a paragraph element won't need to be synthesized.
Character
Contribute the element as an attribute that will start and stop at arbitrary text locations. This will ultimately be mixed into a run of text, with all of the currently flattened HTML character elements.
Special
Produce an embedded graphical element.
Form
Produce an element that is like the embedded graphical element, except that it also has a component model associated with it.
Hidden
Create an element that is hidden from view when the document is being viewed read-only, and visible when the document is being edited. This is useful to keep the model from losing information, and used to store things like comments and unrecognized tags.

Currently, <APPLET>, <PARAM>, <MAP>, <AREA>, <LINK>, <SCRIPT> and <STYLE> are unsupported.

The assignment of the actions described is shown in the following table for the tags defined in HTML.Tag.

Tag | Action
HTML.Tag.A | CharacterAction
HTML.Tag.ADDRESS | CharacterAction
HTML.Tag.APPLET | HiddenAction
HTML.Tag.AREA | AreaAction
HTML.Tag.B | CharacterAction
HTML.Tag.BASE | BaseAction
HTML.Tag.BASEFONT | CharacterAction
HTML.Tag.BIG | CharacterAction
HTML.Tag.BLOCKQUOTE | BlockAction
HTML.Tag.BODY | BlockAction
HTML.Tag.BR | SpecialAction
HTML.Tag.CAPTION | BlockAction
HTML.Tag.CENTER | BlockAction
HTML.Tag.CITE | CharacterAction
HTML.Tag.CODE | CharacterAction
HTML.Tag.DD | BlockAction
HTML.Tag.DFN | CharacterAction
HTML.Tag.DIR | BlockAction
HTML.Tag.DIV | BlockAction
HTML.Tag.DL | BlockAction
HTML.Tag.DT | ParagraphAction
HTML.Tag.EM | CharacterAction
HTML.Tag.FONT | CharacterAction
HTML.Tag.FORM | As of 1.4 a BlockAction
HTML.Tag.FRAME | SpecialAction
HTML.Tag.FRAMESET | BlockAction
HTML.Tag.H1 | ParagraphAction
HTML.Tag.H2 | ParagraphAction
HTML.Tag.H3 | ParagraphAction
HTML.Tag.H4 | ParagraphAction
HTML.Tag.H5 | ParagraphAction
HTML.Tag.H6 | ParagraphAction
HTML.Tag.HEAD | HeadAction
HTML.Tag.HR | SpecialAction
HTML.Tag.HTML | BlockAction
HTML.Tag.I | CharacterAction
HTML.Tag.IMG | SpecialAction
HTML.Tag.INPUT | FormAction
HTML.Tag.ISINDEX | IsndexAction
HTML.Tag.KBD | CharacterAction
HTML.Tag.LI | BlockAction
HTML.Tag.LINK | LinkAction
HTML.Tag.MAP | MapAction
HTML.Tag.MENU | BlockAction
HTML.Tag.META | MetaAction
HTML.Tag.NOFRAMES | BlockAction
HTML.Tag.OBJECT | SpecialAction
HTML.Tag.OL | BlockAction
HTML.Tag.OPTION | FormAction
HTML.Tag.P | ParagraphAction
HTML.Tag.PARAM | HiddenAction
HTML.Tag.PRE | PreAction
HTML.Tag.SAMP | CharacterAction
HTML.Tag.SCRIPT | HiddenAction
HTML.Tag.SELECT | FormAction
HTML.Tag.SMALL | CharacterAction
HTML.Tag.STRIKE | CharacterAction
HTML.Tag.S | CharacterAction
HTML.Tag.STRONG | CharacterAction
HTML.Tag.STYLE | StyleAction
HTML.Tag.SUB | CharacterAction
HTML.Tag.SUP | CharacterAction
HTML.Tag.TABLE | BlockAction
HTML.Tag.TD | BlockAction
HTML.Tag.TEXTAREA | FormAction
HTML.Tag.TH | BlockAction
HTML.Tag.TITLE | TitleAction
HTML.Tag.TR | BlockAction
HTML.Tag.TT | CharacterAction
HTML.Tag.U | CharacterAction
HTML.Tag.UL | BlockAction
HTML.Tag.VAR | CharacterAction

Once </html> is encountered, the Actions are no longer notified.

Nested Class Summary
class | HTMLDocument.HTMLReader.BlockAction
class | HTMLDocument.HTMLReader.CharacterAction
class | HTMLDocument.HTMLReader.FormAction Action to support forms by building all of the elements used to represent form controls.
class | HTMLDocument.HTMLReader.HiddenAction
class | HTMLDocument.HTMLReader.IsindexAction
class | HTMLDocument.HTMLReader.ParagraphAction
class | HTMLDocument.HTMLReader.PreAction
class | HTMLDocument.HTMLReader.SpecialAction
class | HTMLDocument.HTMLReader.TagAction An action to be performed in response to parsing a tag.
Field Summary
protected MutableAttributeSet | charAttr
protected Vector<DefaultStyledDocument.ElementSpec> | parseBuffer
Fields inherited from class javax.swing.text.html.HTMLEditorKit.ParserCallback
IMPLIED
Constructor Summary
HTMLDocument.HTMLReader(int offset)
HTMLDocument.HTMLReader(int offset, int popDepth, int pushDepth, HTML.Tag insertTag)
Method Summary
protected void | addContent(char[] data, int offs, int length) Adds some text with the current character attributes.
protected void | addContent(char[] data, int offs, int length, boolean generateImpliedPIfNecessary) Adds some text with the current character attributes.
protected void | addSpecialElement(HTML.Tag t, MutableAttributeSet a) Adds content that is basically specified entirely in the attribute set.
protected void | blockClose(HTML.Tag t) Adds an instruction to the parse buffer to close out a block element of the given type.
protected void | blockOpen(HTML.Tag t, MutableAttributeSet attr) Adds an instruction to the parse buffer to create a block element with the given attributes.
void | flush() The last method called on the reader.
void | handleComment(char[] data, int pos)
void | handleEndOfLineString(String eol) This is invoked after the stream has been parsed, but before flush.
void | handleEndTag(HTML.Tag t, int pos) Callback from the parser.
void | handleSimpleTag(HTML.Tag t, MutableAttributeSet a, int pos) Callback from the parser.
void | handleStartTag(HTML.Tag t, MutableAttributeSet a, int pos) Callback from the parser.
void | handleText(char[] data, int pos) Called by the parser to indicate a block of text was encountered.
protected void | popCharacterStyle() Pops a previously pushed character style off the stack to return to a previous style.
protected void | preContent(char[] data) Adds the given content that was encountered in a PRE element.
protected void | pushCharacterStyle() Pushes the current character style on a stack in preparation for forming a new nested character style.
protected void | registerTag(HTML.Tag t, HTMLDocument.HTMLReader.TagAction a) Registers a handler for the given tag.
protected void | textAreaContent(char[] data) Adds the given content to the textarea document.
Methods inherited from class javax.swing.text.html.HTMLEditorKit.ParserCallback
handleError
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

parseBuffer

protected Vector<DefaultStyledDocument.ElementSpec> parseBuffer

charAttr

protected MutableAttributeSet charAttr
Constructor Detail

HTMLDocument.HTMLReader

public HTMLDocument.HTMLReader(int offset)

HTMLDocument.HTMLReader

public HTMLDocument.HTMLReader(int offset,
                               int popDepth,
                               int pushDepth,
                               HTML.Tag insertTag)
Method Detail

flush

public void flush()
           throws BadLocationException
The last method called on the reader. It allows any pending changes to be flushed into the document. Since this is currently loading synchronously, the entire set of changes are pushed in at this point.

Overrides:
flush in class HTMLEditorKit.ParserCallback
Throws:
BadLocationException

handleText

public void handleText(char[] data,
                       int pos)
Called by the parser to indicate a block of text was encountered.

Overrides:
handleText in class HTMLEditorKit.ParserCallback

handleStartTag

public void handleStartTag(HTML.Tag t,
                           MutableAttributeSet a,
                           int pos)
Callback from the parser. Route to the appropriate handler for the tag.

Overrides:
handleStartTag in class HTMLEditorKit.ParserCallback

handleComment

public void handleComment(char[] data,
                          int pos)
Overrides:
handleComment in class HTMLEditorKit.ParserCallback

handleEndTag

public void handleEndTag(HTML.Tag t,
                         int pos)
Callback from the parser. Route to the appropriate handler for the tag.

Overrides:
handleEndTag in class HTMLEditorKit.ParserCallback

handleSimpleTag

public void handleSimpleTag(HTML.Tag t,
                            MutableAttributeSet a,
                            int pos)
Callback from the parser. Route to the appropriate handler for the tag.

Overrides:
handleSimpleTag in class HTMLEditorKit.ParserCallback

handleEndOfLineString

public void handleEndOfLineString(String eol)
This is invoked after the stream has been parsed, but before flush. eol will be one of \n, \r or \r\n, which ever is encountered the most in parsing the stream.

Overrides:
handleEndOfLineString in class HTMLEditorKit.ParserCallback
Since:
1.3

registerTag

protected void registerTag(HTML.Tag t,
                           HTMLDocument.HTMLReader.TagAction a)
Registers a handler for the given tag. By default all of the well-known tags will have been registered. This can be used to change the handling of a particular tag or to add support for custom tags.

pushCharacterStyle

protected void pushCharacterStyle()
Pushes the current character style on a stack in preparation for forming a new nested character style.

popCharacterStyle

protected void popCharacterStyle()
Pops a previously pushed character style off the stack to return to a previous style.

textAreaContent

protected void textAreaContent(char[] data)
Adds the given content to the textarea document. This method gets called when we are in a textarea context. Therefore all text that is seen belongs to the text area and is hence added to the TextAreaDocument associated with the text area.

preContent

protected void preContent(char[] data)
Adds the given content that was encountered in a PRE element. This synthesizes lines to hold the runs of text, and makes calls to addContent to actually add the text.

blockOpen

protected void blockOpen(HTML.Tag t,
                         MutableAttributeSet attr)
Adds an instruction to the parse buffer to create a block element with the given attributes.

blockClose

protected void blockClose(HTML.Tag t)
Adds an instruction to the parse buffer to close out a block element of the given type.

addContent

protected void addContent(char[] data,
                          int offs,
                          int length)
Adds some text with the current character attributes.

Parameters:
data - the content to add
offs - the initial offset
length - the length

addContent

protected void addContent(char[] data,
                          int offs,
                          int length,
                          boolean generateImpliedPIfNecessary)
Adds some text with the current character attributes.

Parameters:
data - the content to add
offs - the initial offset
length - the length
generateImpliedPIfNecessary - whether to generate implied paragraphs

addSpecialElement

protected void addSpecialElement(HTML.Tag t,
                                 MutableAttributeSet a)
Adds content that is basically specified entirely in the attribute set.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLDocument.HTMLReader.BlockAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLDocument.HTMLReader.BlockAction

java.lang.Object
    extended by  javax.swing.text.html.HTMLDocument.HTMLReader.TagAction
        extended by  javax.swing.text.html.HTMLDocument.HTMLReader.BlockAction
Direct Known Subclasses:
HTMLDocument.HTMLReader.ParagraphAction, HTMLDocument.HTMLReader.PreAction
Enclosing class:
HTMLDocument.HTMLReader
public class HTMLDocument.HTMLReader.BlockAction
extends HTMLDocument.HTMLReader.TagAction

Constructor Summary
HTMLDocument.HTMLReader.BlockAction()
Method Summary
void | end(HTML.Tag t) Called when an end tag is seen for the type of tag this action was registered to.
void | start(HTML.Tag t, MutableAttributeSet attr) Called when a start tag is seen for the type of tag this action was registered to.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HTMLDocument.HTMLReader.BlockAction

public HTMLDocument.HTMLReader.BlockAction()
Method Detail

start

public void start(HTML.Tag t,
                  MutableAttributeSet attr)
Description copied from class: HTMLDocument.HTMLReader.TagAction
Called when a start tag is seen for the type of tag this action was registered to. The tag argument indicates the actual tag for those actions that are shared across many tags. By default this does nothing and completely ignores the tag.

Overrides:
start in class HTMLDocument.HTMLReader.TagAction

end

public void end(HTML.Tag t)
Description copied from class: HTMLDocument.HTMLReader.TagAction
Called when an end tag is seen for the type of tag this action was registered to. The tag argument indicates the actual tag for those actions that are shared across many tags. By default this does nothing and completely ignores the tag.

Overrides:
end in class HTMLDocument.HTMLReader.TagAction
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLDocument.HTMLReader.CharacterAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLDocument.HTMLReader.CharacterAction

java.lang.Object
    extended by  javax.swing.text.html.HTMLDocument.HTMLReader.TagAction
        extended by  javax.swing.text.html.HTMLDocument.HTMLReader.CharacterAction
Enclosing class:
HTMLDocument.HTMLReader
public class HTMLDocument.HTMLReader.CharacterAction
extends HTMLDocument.HTMLReader.TagAction

Constructor Summary
HTMLDocument.HTMLReader.CharacterAction()
Method Summary
void | end(HTML.Tag t) Called when an end tag is seen for the type of tag this action was registered to.
void | start(HTML.Tag t, MutableAttributeSet attr) Called when a start tag is seen for the type of tag this action was registered to.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HTMLDocument.HTMLReader.CharacterAction

public HTMLDocument.HTMLReader.CharacterAction()
Method Detail

start

public void start(HTML.Tag t,
                  MutableAttributeSet attr)
Description copied from class: HTMLDocument.HTMLReader.TagAction
Called when a start tag is seen for the type of tag this action was registered to. The tag argument indicates the actual tag for those actions that are shared across many tags. By default this does nothing and completely ignores the tag.

Overrides:
start in class HTMLDocument.HTMLReader.TagAction

end

public void end(HTML.Tag t)
Description copied from class: HTMLDocument.HTMLReader.TagAction
Called when an end tag is seen for the type of tag this action was registered to. The tag argument indicates the actual tag for those actions that are shared across many tags. By default this does nothing and completely ignores the tag.

Overrides:
end in class HTMLDocument.HTMLReader.TagAction
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLDocument.HTMLReader.FormAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLDocument.HTMLReader.FormAction

java.lang.Object
    extended by  javax.swing.text.html.HTMLDocument.HTMLReader.TagAction
        extended by  javax.swing.text.html.HTMLDocument.HTMLReader.SpecialAction
            extended by  javax.swing.text.html.HTMLDocument.HTMLReader.FormAction
Enclosing class:
HTMLDocument.HTMLReader
public class HTMLDocument.HTMLReader.FormAction
extends HTMLDocument.HTMLReader.SpecialAction

Action to support forms by building all of the elements used to represent form controls. This will process the <INPUT>, <TEXTAREA>, <SELECT>, and <OPTION> tags. The element created by this action is expected to have the attribute StyleConstants.ModelAttribute set to the model that holds the state for the form control. This enables multiple views, and allows document to be iterated over picking up the data of the form. The following are the model assignments for the various type of form elements.
Element Type | Model Type
input, type button | DefaultButtonModel
input, type checkbox | JToggleButton.ToggleButtonModel
input, type image | DefaultButtonModel
input, type password | PlainDocument
input, type radio | JToggleButton.ToggleButtonModel
input, type reset | DefaultButtonModel
input, type submit | DefaultButtonModel
input, type text or type is null. | PlainDocument
select | DefaultComboBoxModel or an DefaultListModel, with an item type of Option
textarea | PlainDocument

Constructor Summary
HTMLDocument.HTMLReader.FormAction()
Method Summary
void | end(HTML.Tag t) Called when an end tag is seen for the type of tag this action was registered to.
void | start(HTML.Tag t, MutableAttributeSet attr) Called when a start tag is seen for the type of tag this action was registered to.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HTMLDocument.HTMLReader.FormAction

public HTMLDocument.HTMLReader.FormAction()
Method Detail

start

public void start(HTML.Tag t,
                  MutableAttributeSet attr)
Description copied from class: HTMLDocument.HTMLReader.TagAction
Called when a start tag is seen for the type of tag this action was registered to. The tag argument indicates the actual tag for those actions that are shared across many tags. By default this does nothing and completely ignores the tag.

Overrides:
start in class HTMLDocument.HTMLReader.SpecialAction

end

public void end(HTML.Tag t)
Description copied from class: HTMLDocument.HTMLReader.TagAction
Called when an end tag is seen for the type of tag this action was registered to. The tag argument indicates the actual tag for those actions that are shared across many tags. By default this does nothing and completely ignores the tag.

Overrides:
end in class HTMLDocument.HTMLReader.TagAction
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLDocument.HTMLReader.HiddenAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLDocument.HTMLReader.HiddenAction

java.lang.Object
    extended by  javax.swing.text.html.HTMLDocument.HTMLReader.TagAction
        extended by  javax.swing.text.html.HTMLDocument.HTMLReader.HiddenAction
Enclosing class:
HTMLDocument.HTMLReader
public class HTMLDocument.HTMLReader.HiddenAction
extends HTMLDocument.HTMLReader.TagAction

Constructor Summary
HTMLDocument.HTMLReader.HiddenAction()
Method Summary
void | end(HTML.Tag t) Called when an end tag is seen for the type of tag this action was registered to.
void | start(HTML.Tag t, MutableAttributeSet a) Called when a start tag is seen for the type of tag this action was registered to.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HTMLDocument.HTMLReader.HiddenAction

public HTMLDocument.HTMLReader.HiddenAction()
Method Detail

start

public void start(HTML.Tag t,
                  MutableAttributeSet a)
Description copied from class: HTMLDocument.HTMLReader.TagAction
Called when a start tag is seen for the type of tag this action was registered to. The tag argument indicates the actual tag for those actions that are shared across many tags. By default this does nothing and completely ignores the tag.

Overrides:
start in class HTMLDocument.HTMLReader.TagAction

end

public void end(HTML.Tag t)
Description copied from class: HTMLDocument.HTMLReader.TagAction
Called when an end tag is seen for the type of tag this action was registered to. The tag argument indicates the actual tag for those actions that are shared across many tags. By default this does nothing and completely ignores the tag.

Overrides:
end in class HTMLDocument.HTMLReader.TagAction
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLDocument.HTMLReader.IsindexAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLDocument.HTMLReader.IsindexAction

java.lang.Object
    extended by  javax.swing.text.html.HTMLDocument.HTMLReader.TagAction
        extended by  javax.swing.text.html.HTMLDocument.HTMLReader.IsindexAction
Enclosing class:
HTMLDocument.HTMLReader
public class HTMLDocument.HTMLReader.IsindexAction
extends HTMLDocument.HTMLReader.TagAction

Constructor Summary
HTMLDocument.HTMLReader.IsindexAction()
Method Summary
 void start(HTML.Tag t, MutableAttributeSet a)
Called when a start tag is seen for the type of tag this action was registered to.
Methods inherited from class javax.swing.text.html.HTMLDocument.HTMLReader.TagAction
end
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HTMLDocument.HTMLReader.IsindexAction

public HTMLDocument.HTMLReader.IsindexAction()
Method Detail

start

public void start(HTML.Tag t,
                  MutableAttributeSet a)
Description copied from class: HTMLDocument.HTMLReader.TagAction
Called when a start tag is seen for the type of tag this action was registered to. The tag argument indicates the actual tag for those actions that are shared across many tags. By default this does nothing and completely ignores the tag.

Overrides:
start in class HTMLDocument.HTMLReader.TagAction
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLDocument.HTMLReader.ParagraphAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLDocument.HTMLReader.ParagraphAction

java.lang.Object
    extended by  javax.swing.text.html.HTMLDocument.HTMLReader.TagAction
        extended by  javax.swing.text.html.HTMLDocument.HTMLReader.BlockAction
            extended by  javax.swing.text.html.HTMLDocument.HTMLReader.ParagraphAction
Enclosing class:
HTMLDocument.HTMLReader
public class HTMLDocument.HTMLReader.ParagraphAction
extends HTMLDocument.HTMLReader.BlockAction

Constructor Summary
HTMLDocument.HTMLReader.ParagraphAction()
Method Summary
void | end(HTML.Tag t) Called when an end tag is seen for the type of tag this action was registered to.
void | start(HTML.Tag t, MutableAttributeSet a) Called when a start tag is seen for the type of tag this action was registered to.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HTMLDocument.HTMLReader.ParagraphAction

public HTMLDocument.HTMLReader.ParagraphAction()
Method Detail

start

public void start(HTML.Tag t,
                  MutableAttributeSet a)
Description copied from class: HTMLDocument.HTMLReader.TagAction
Called when a start tag is seen for the type of tag this action was registered to. The tag argument indicates the actual tag for those actions that are shared across many tags. By default this does nothing and completely ignores the tag.

Overrides:
start in class HTMLDocument.HTMLReader.BlockAction

end

public void end(HTML.Tag t)
Description copied from class: HTMLDocument.HTMLReader.TagAction
Called when an end tag is seen for the type of tag this action was registered to. The tag argument indicates the actual tag for those actions that are shared across many tags. By default this does nothing and completely ignores the tag.

Overrides:
end in class HTMLDocument.HTMLReader.BlockAction
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLDocument.HTMLReader.PreAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLDocument.HTMLReader.PreAction

java.lang.Object
    extended by  javax.swing.text.html.HTMLDocument.HTMLReader.TagAction
        extended by  javax.swing.text.html.HTMLDocument.HTMLReader.BlockAction
            extended by  javax.swing.text.html.HTMLDocument.HTMLReader.PreAction
Enclosing class:
HTMLDocument.HTMLReader
public class HTMLDocument.HTMLReader.PreAction
extends HTMLDocument.HTMLReader.BlockAction

Constructor Summary
HTMLDocument.HTMLReader.PreAction()
Method Summary
void | end(HTML.Tag t) Called when an end tag is seen for the type of tag this action was registered to.
void | start(HTML.Tag t, MutableAttributeSet attr) Called when a start tag is seen for the type of tag this action was registered to.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HTMLDocument.HTMLReader.PreAction

public HTMLDocument.HTMLReader.PreAction()
Method Detail

start

public void start(HTML.Tag t,
                  MutableAttributeSet attr)
Description copied from class: HTMLDocument.HTMLReader.TagAction
Called when a start tag is seen for the type of tag this action was registered to. The tag argument indicates the actual tag for those actions that are shared across many tags. By default this does nothing and completely ignores the tag.

Overrides:
start in class HTMLDocument.HTMLReader.BlockAction

end

public void end(HTML.Tag t)
Description copied from class: HTMLDocument.HTMLReader.TagAction
Called when an end tag is seen for the type of tag this action was registered to. The tag argument indicates the actual tag for those actions that are shared across many tags. By default this does nothing and completely ignores the tag.

Overrides:
end in class HTMLDocument.HTMLReader.BlockAction
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLDocument.HTMLReader.SpecialAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLDocument.HTMLReader.SpecialAction

java.lang.Object
    extended by  javax.swing.text.html.HTMLDocument.HTMLReader.TagAction
        extended by  javax.swing.text.html.HTMLDocument.HTMLReader.SpecialAction
Direct Known Subclasses:
HTMLDocument.HTMLReader.FormAction
Enclosing class:
HTMLDocument.HTMLReader
public class HTMLDocument.HTMLReader.SpecialAction
extends HTMLDocument.HTMLReader.TagAction

Constructor Summary
HTMLDocument.HTMLReader.SpecialAction()
Method Summary
 void start(HTML.Tag t, MutableAttributeSet a)
Called when a start tag is seen for the type of tag this action was registered to.
Methods inherited from class javax.swing.text.html.HTMLDocument.HTMLReader.TagAction
end
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HTMLDocument.HTMLReader.SpecialAction

public HTMLDocument.HTMLReader.SpecialAction()
Method Detail

start

public void start(HTML.Tag t,
                  MutableAttributeSet a)
Description copied from class: HTMLDocument.HTMLReader.TagAction
Called when a start tag is seen for the type of tag this action was registered to. The tag argument indicates the actual tag for those actions that are shared across many tags. By default this does nothing and completely ignores the tag.

Overrides:
start in class HTMLDocument.HTMLReader.TagAction
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLDocument.HTMLReader.TagAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLDocument.HTMLReader.TagAction

java.lang.Object
    extended by  javax.swing.text.html.HTMLDocument.HTMLReader.TagAction
Direct Known Subclasses:
HTMLDocument.HTMLReader.BlockAction, HTMLDocument.HTMLReader.CharacterAction, HTMLDocument.HTMLReader.HiddenAction, HTMLDocument.HTMLReader.IsindexAction, HTMLDocument.HTMLReader.SpecialAction
Enclosing class:
HTMLDocument.HTMLReader
public class HTMLDocument.HTMLReader.TagAction
extends Object

An action to be performed in response to parsing a tag. This allows customization of how each tag is handled and avoids a large switch statement.

Constructor Summary
HTMLDocument.HTMLReader.TagAction()
Method Summary
void | end(HTML.Tag t) Called when an end tag is seen for the type of tag this action was registered to.
void | start(HTML.Tag t, MutableAttributeSet a) Called when a start tag is seen for the type of tag this action was registered to.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HTMLDocument.HTMLReader.TagAction

public HTMLDocument.HTMLReader.TagAction()
Method Detail

start

public void start(HTML.Tag t,
                  MutableAttributeSet a)
Called when a start tag is seen for the type of tag this action was registered to. The tag argument indicates the actual tag for those actions that are shared across many tags. By default this does nothing and completely ignores the tag.

end

public void end(HTML.Tag t)
Called when an end tag is seen for the type of tag this action was registered to. The tag argument indicates the actual tag for those actions that are shared across many tags. By default this does nothing and completely ignores the tag.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLDocument.Iterator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLDocument.Iterator

java.lang.Object
    extended by  javax.swing.text.html.HTMLDocument.Iterator
Enclosing class:
HTMLDocument
public abstract static class HTMLDocument.Iterator
extends Object

An iterator to iterate over a particular type of tag. The iterator is not thread safe. If reliable access to the document is not already ensured by the context under which the iterator is being used, its use should be performed under the protection of Document.render.

Constructor Summary
HTMLDocument.Iterator()
Method Summary
abstract AttributeSet | getAttributes() Return the attributes for this tag.
abstract int | getEndOffset() Returns the end of the range for which the current occurrence of the tag is defined and has the same attributes.
abstract int | getStartOffset() Returns the start of the range for which the current occurrence of the tag is defined and has the same attributes.
abstract HTML.Tag | getTag() Type of tag this iterator represents.
abstract boolean | isValid() Indicates if the iterator is currently representing an occurrence of a tag.
abstract void | next() Move the iterator forward to the next occurrence of the tag it represents.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HTMLDocument.Iterator

public HTMLDocument.Iterator()
Method Detail

getAttributes

public abstract AttributeSet getAttributes()
Return the attributes for this tag.

Returns:
the AttributeSet for this tag, or null if none can be found

getStartOffset

public abstract int getStartOffset()
Returns the start of the range for which the current occurrence of the tag is defined and has the same attributes.

Returns:
the start of the range, or -1 if it can't be found

getEndOffset

public abstract int getEndOffset()
Returns the end of the range for which the current occurrence of the tag is defined and has the same attributes.

Returns:
the end of the range

next

public abstract void next()
Move the iterator forward to the next occurrence of the tag it represents.

isValid

public abstract boolean isValid()
Indicates if the iterator is currently representing an occurrence of a tag. If false there are no more tags for this iterator.

Returns:
true if the iterator is currently representing an occurrence of a tag, otherwise returns false

getTag

public abstract HTML.Tag getTag()
Type of tag this iterator represents.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLDocument.RunElement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLDocument.RunElement

java.lang.Object
    extended by  javax.swing.text.AbstractDocument.AbstractElement
        extended by  javax.swing.text.AbstractDocument.LeafElement
            extended by  javax.swing.text.html.HTMLDocument.RunElement
All Implemented Interfaces:
Serializable, AttributeSet, Element, MutableAttributeSet, TreeNode
Enclosing class:
HTMLDocument
public class HTMLDocument.RunElement
extends AbstractDocument.LeafElement

An element that represents a chunk of text that has a set of HTML character level attributes assigned to it.

Nested Class Summary
Nested classes/interfaces inherited from interface javax.swing.text.AttributeSet
AttributeSet.CharacterAttribute, AttributeSet.ColorAttribute, AttributeSet.FontAttribute, AttributeSet.ParagraphAttribute
Field Summary
Fields inherited from interface javax.swing.text.AttributeSet
NameAttribute, ResolveAttribute
Constructor Summary
HTMLDocument.RunElement(Element parent, AttributeSet a, int offs0, int offs1)
Constructs an element that represents content within the document (has no children).
Method Summary
String | getName() Gets the name of the element.
AttributeSet | getResolveParent() Gets the resolving parent.
Methods inherited from class javax.swing.text.AbstractDocument.LeafElement
children, getAllowsChildren, getElement, getElementCount, getElementIndex, getEndOffset, getStartOffset, isLeaf, toString
Methods inherited from class javax.swing.text.AbstractDocument.AbstractElement
addAttribute, addAttributes, containsAttribute, containsAttributes, copyAttributes, dump, getAttribute, getAttributeCount, getAttributeNames, getAttributes, getChildAt, getChildCount, getDocument, getIndex, getParent, getParentElement, isDefined, isEqual, removeAttribute, removeAttributes, removeAttributes, setResolveParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

HTMLDocument.RunElement

public HTMLDocument.RunElement(Element parent,
                               AttributeSet a,
                               int offs0,
                               int offs1)
Constructs an element that represents content within the document (has no children).

Parameters:
parent - the parent element
a - the element attributes
offs0 - the start offset (must be at least 0)
offs1 - the end offset (must be at least offs0)
Since:
1.4
Method Detail

getName

public String getName()
Gets the name of the element.

Specified by:
getName in interface Element
Overrides:
getName in class AbstractDocument.LeafElement
Returns:
the name, null if none

getResolveParent

public AttributeSet getResolveParent()
Gets the resolving parent. HTML attributes are not inherited at the model level so we override this to return null.

Specified by:
getResolveParent in interface AttributeSet
Overrides:
getResolveParent in class AbstractDocument.AbstractElement
Returns:
null, there are none
See Also:
AttributeSet.getResolveParent()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLEditorKit

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLEditorKit

java.lang.Object
    extended by  javax.swing.text.EditorKit
        extended by  javax.swing.text.DefaultEditorKit
            extended by  javax.swing.text.StyledEditorKit
                extended by  javax.swing.text.html.HTMLEditorKit
All Implemented Interfaces:
Serializable, Cloneable, Accessible
public class HTMLEditorKit
extends StyledEditorKit
implements Accessible

The Swing JEditorPane text component supports different kinds of content via a plug-in mechanism called an EditorKit. Because HTML is a very popular format of content, some support is provided by default. The default support is provided by this class, which supports HTML version 3.2 (with some extensions), and is migrating toward version 4.0. The <applet> tag is not supported, but some support is provided for the <object> tag.

There are several goals of the HTML EditorKit provided, that have an effect upon the way that HTML is modeled. These have influenced its design in a substantial way.

Support editing
It might seem fairly obvious that a plug-in for JEditorPane should provide editing support, but that fact has several design considerations. There are a substantial number of HTML documents that don't properly conform to an HTML specification. These must be normalized somewhat into a correct form if one is to edit them. Additionally, users don't like to be presented with an excessive amount of structure editing, so using traditional text editing gestures is preferred over using the HTML structure exactly as defined in the HTML document.

The modeling of HTML is provided by the class HTMLDocument. Its documention describes the details of how the HTML is modeled. The editing support leverages heavily off of the text package.

Extendable/Scalable
To maximize the usefulness of this kit, a great deal of effort has gone into making it extendable. These are some of the features.
  1. The parser is replacable. The default parser is the Hot Java parser which is DTD based. A different DTD can be used, or an entirely different parser can be used. To change the parser, reimplement the getParser method. The default parser is dynamically loaded when first asked for, so the class files will never be loaded if an alternative parser is used. The default parser is in a separate package called parser below this package.
  2. The parser drives the ParserCallback, which is provided by HTMLDocument. To change the callback, subclass HTMLDocument and reimplement the createDefaultDocument method to return document that produces a different reader. The reader controls how the document is structured. Although the Document provides HTML support by default, there is nothing preventing support of non-HTML tags that result in alternative element structures.
  3. The default view of the models are provided as a hierarchy of View implementations, so one can easily customize how a particular element is displayed or add capabilities for new kinds of elements by providing new View implementations. The default set of views are provided by the HTMLFactory class. This can be easily changed by subclassing or replacing the HTMLFactory and reimplementing the getViewFactory method to return the alternative factory.
  4. The View implementations work primarily off of CSS attributes, which are kept in the views. This makes it possible to have multiple views mapped over the same model that appear substantially different. This can be especially useful for printing. For most HTML attributes, the HTML attributes are converted to CSS attributes for display. This helps make the View implementations more general purpose

Asynchronous Loading
Larger documents involve a lot of parsing and take some time to load. By default, this kit produces documents that will be loaded asynchronously if loaded using JEditorPane.setPage. This is controlled by a property on the document. The method createDefaultDocument can be overriden to change this. The batching of work is done by the HTMLDocument.HTMLReader class. The actual work is done by the DefaultStyledDocument and AbstractDocument classes in the text package.

Customization from current LAF
HTML provides a well known set of features without exactly specifying the display characteristics. Swing has a theme mechanism for its look-and-feel implementations. It is desirable for the look-and-feel to feed display characteristics into the HTML views. An user with poor vision for example would want high contrast and larger than typical fonts.

The support for this is provided by the StyleSheet class. The presentation of the HTML can be heavily influenced by the setting of the StyleSheet property on the EditorKit.

Not lossy
An EditorKit has the ability to be read and save documents. It is generally the most pleasing to users if there is no loss of data between the two operation. The policy of the HTMLEditorKit will be to store things not recognized or not necessarily visible so they can be subsequently written out. The model of the HTML document should therefore contain all information discovered while reading the document. This is constrained in some ways by the need to support editing (i.e. incorrect documents sometimes must be normalized). The guiding principle is that information shouldn't be lost, but some might be synthesized to produce a more correct model or it might be rearranged.

Nested Class Summary
static class | HTMLEditorKit.HTMLFactory A factory to build views for HTML.
static class | HTMLEditorKit.HTMLTextAction An abstract Action providing some convenience methods that may be useful in inserting HTML into an existing document.
static class | HTMLEditorKit.InsertHTMLTextAction InsertHTMLTextAction can be used to insert an arbitrary string of HTML into an existing HTML document.
static class | HTMLEditorKit.LinkController Class to watch the associated component and fire hyperlink events on it when appropriate.
static class | HTMLEditorKit.Parser Interface to be supported by the parser.
static class | HTMLEditorKit.ParserCallback The result of parsing drives these callback methods.
Nested classes/interfaces inherited from class javax.swing.text.StyledEditorKit
StyledEditorKit.AlignmentAction, StyledEditorKit.BoldAction, StyledEditorKit.FontFamilyAction, StyledEditorKit.FontSizeAction, StyledEditorKit.ForegroundAction, StyledEditorKit.ItalicAction, StyledEditorKit.StyledTextAction, StyledEditorKit.UnderlineAction
Nested classes/interfaces inherited from class javax.swing.text.DefaultEditorKit
DefaultEditorKit.BeepAction, DefaultEditorKit.CopyAction, DefaultEditorKit.CutAction, DefaultEditorKit.DefaultKeyTypedAction, DefaultEditorKit.InsertBreakAction, DefaultEditorKit.InsertContentAction, DefaultEditorKit.InsertTabAction, DefaultEditorKit.PasteAction
Field Summary
static String | BOLD_ACTION The bold action identifier
static String | COLOR_ACTION The Color choice action identifier The color is passed as an argument
static String | DEFAULT_CSS Default Cascading Style Sheet file that sets up the tag views.
static String | FONT_CHANGE_BIGGER The font size increase to next value action identifier
static String | FONT_CHANGE_SMALLER The font size decrease to next value action identifier
static String | IMG_ALIGN_BOTTOM Align images at the bottom.
static String | IMG_ALIGN_MIDDLE Align images in the middle.
static String | IMG_ALIGN_TOP Align images at the top.
static String | IMG_BORDER Align images at the border.
static String | ITALIC_ACTION The italic action identifier
static String | LOGICAL_STYLE_ACTION The logical style choice action identifier The logical style is passed in as an argument
static String | PARA_INDENT_LEFT The paragraph left indent action identifier
static String | PARA_INDENT_RIGHT The paragraph right indent action identifier
Fields inherited from class javax.swing.text.DefaultEditorKit
backwardAction, beepAction, beginAction, beginLineAction, beginParagraphAction, beginWordAction, copyAction, cutAction, defaultKeyTypedAction, deleteNextCharAction, deleteNextWordAction, deletePrevCharAction, deletePrevWordAction, downAction, endAction, endLineAction, EndOfLineStringProperty, endParagraphAction, endWordAction, forwardAction, insertBreakAction, insertContentAction, insertTabAction, nextWordAction, pageDownAction, pageUpAction, pasteAction, previousWordAction, readOnlyAction, selectAllAction, selectionBackwardAction, selectionBeginAction, selectionBeginLineAction, selectionBeginParagraphAction, selectionBeginWordAction, selectionDownAction, selectionEndAction, selectionEndLineAction, selectionEndParagraphAction, selectionEndWordAction, selectionForwardAction, selectionNextWordAction, selectionPreviousWordAction, selectionUpAction, selectLineAction, selectParagraphAction, selectWordAction, upAction, writableAction
Constructor Summary
HTMLEditorKit()
Constructs an HTMLEditorKit, creates a StyleContext, and loads the style sheet.
Method Summary
Object | clone() Creates a copy of the editor kit.
Document | createDefaultDocument() Create an uninitialized text storage model that is appropriate for this type of editor.
protected void | createInputAttributes(Element element, MutableAttributeSet set) Copies the key/values in elements AttributeSet into set.
void | deinstall(JEditorPane c) Called when the kit is being removed from the JEditorPane.
AccessibleContext | getAccessibleContext() returns the AccessibleContext associated with this editor kit
Action[] | getActions() Fetches the command list for the editor.
String | getContentType() Get the MIME type of the data that this kit represents support for.
Cursor | getDefaultCursor() Returns the default cursor.
MutableAttributeSet | getInputAttributes() Gets the input attributes used for the styled editing actions.
Cursor | getLinkCursor() Returns the cursor to use over hyper links.
protected HTMLEditorKit.Parser | getParser() Fetch the parser to use for reading HTML streams.
StyleSheet | getStyleSheet() Get the set of styles currently being used to render the HTML elements.
ViewFactory | getViewFactory() Fetch a factory that is suitable for producing views of any models that are produced by this kit.
void | insertHTML(HTMLDocument doc, int offset, String html, int popDepth, int pushDepth, HTML.Tag insertTag) Inserts HTML into an existing document.
void | install(JEditorPane c) Called when the kit is being installed into the a JEditorPane.
boolean | isAutoFormSubmission() Indicates whether an html form submission is processed automatically or only FormSubmitEvent is fired.
void | read(Reader in, Document doc, int pos) Inserts content from the given stream.
void | setAutoFormSubmission(boolean isAuto) Specifies if an html form submission is processed automatically or only FormSubmitEvent is fired.
void | setDefaultCursor(Cursor cursor) Sets the default cursor.
void | setLinkCursor(Cursor cursor) Sets the cursor to use over links.
void | setStyleSheet(StyleSheet s) Set the set of styles to be used to render the various HTML elements.
void | write(Writer out, Document doc, int pos, int len) Write content from a document to the given stream in a format appropriate for this kind of content handler.
Methods inherited from class javax.swing.text.StyledEditorKit
getCharacterAttributeRun
Methods inherited from class javax.swing.text.DefaultEditorKit
createCaret, read, write
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_CSS

public static final String DEFAULT_CSS
Default Cascading Style Sheet file that sets up the tag views.

See Also:
Constant Field Values

BOLD_ACTION

public static final String BOLD_ACTION
The bold action identifier

See Also:
Constant Field Values

ITALIC_ACTION

public static final String ITALIC_ACTION
The italic action identifier

See Also:
Constant Field Values

PARA_INDENT_LEFT

public static final String PARA_INDENT_LEFT
The paragraph left indent action identifier

See Also:
Constant Field Values

PARA_INDENT_RIGHT

public static final String PARA_INDENT_RIGHT
The paragraph right indent action identifier

See Also:
Constant Field Values

FONT_CHANGE_BIGGER

public static final String FONT_CHANGE_BIGGER
The font size increase to next value action identifier

See Also:
Constant Field Values

FONT_CHANGE_SMALLER

public static final String FONT_CHANGE_SMALLER
The font size decrease to next value action identifier

See Also:
Constant Field Values

COLOR_ACTION

public static final String COLOR_ACTION
The Color choice action identifier The color is passed as an argument

See Also:
Constant Field Values

LOGICAL_STYLE_ACTION

public static final String LOGICAL_STYLE_ACTION
The logical style choice action identifier The logical style is passed in as an argument

See Also:
Constant Field Values

IMG_ALIGN_TOP

public static final String IMG_ALIGN_TOP
Align images at the top.

See Also:
Constant Field Values

IMG_ALIGN_MIDDLE

public static final String IMG_ALIGN_MIDDLE
Align images in the middle.

See Also:
Constant Field Values

IMG_ALIGN_BOTTOM

public static final String IMG_ALIGN_BOTTOM
Align images at the bottom.

See Also:
Constant Field Values

IMG_BORDER

public static final String IMG_BORDER
Align images at the border.

See Also:
Constant Field Values
Constructor Detail

HTMLEditorKit

public HTMLEditorKit()
Constructs an HTMLEditorKit, creates a StyleContext, and loads the style sheet.

Method Detail

getContentType

public String getContentType()
Get the MIME type of the data that this kit represents support for. This kit supports the type text/html.

Overrides:
getContentType in class DefaultEditorKit
Returns:
the type

getViewFactory

public ViewFactory getViewFactory()
Fetch a factory that is suitable for producing views of any models that are produced by this kit.

Overrides:
getViewFactory in class StyledEditorKit
Returns:
the factory

createDefaultDocument

public Document createDefaultDocument()
Create an uninitialized text storage model that is appropriate for this type of editor.

Overrides:
createDefaultDocument in class StyledEditorKit
Returns:
the model

read

public void read(Reader in,
                 Document doc,
                 int pos)
          throws IOException,
                 BadLocationException
Inserts content from the given stream. If doc is an instance of HTMLDocument, this will read HTML 3.2 text. Inserting HTML into a non-empty document must be inside the body Element, if you do not insert into the body an exception will be thrown. When inserting into a non-empty document all tags outside of the body (head, title) will be dropped.

Overrides:
read in class DefaultEditorKit
Parameters:
in - the stream to read from
doc - the destination for the insertion
pos - the location in the document to place the content
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document
RuntimeException - (will eventually be a BadLocationException) if pos is invalid

insertHTML

public void insertHTML(HTMLDocument doc,
                       int offset,
                       String html,
                       int popDepth,
                       int pushDepth,
                       HTML.Tag insertTag)
                throws BadLocationException,
                       IOException
Inserts HTML into an existing document.

Parameters:
doc - the document to insert into
offset - the offset to insert HTML at
popDepth - the number of ElementSpec.EndTagTypes to generate before inserting
pushDepth - the number of ElementSpec.StartTagTypes with a direction of ElementSpec.JoinNextDirection that should be generated before inserting, but after the end tags have been generated
insertTag - the first tag to start inserting into document
Throws:
RuntimeException - (will eventually be a BadLocationException) if pos is invalid
BadLocationException
IOException

write

public void write(Writer out,
                  Document doc,
                  int pos,
                  int len)
           throws IOException,
                  BadLocationException
Write content from a document to the given stream in a format appropriate for this kind of content handler.

Overrides:
write in class DefaultEditorKit
Parameters:
out - the stream to write to
doc - the source for the write
pos - the location in the document to fetch the content
len - the amount to write out
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document

install

public void install(JEditorPane c)
Called when the kit is being installed into the a JEditorPane.

Overrides:
install in class StyledEditorKit
Parameters:
c - the JEditorPane

deinstall

public void deinstall(JEditorPane c)
Called when the kit is being removed from the JEditorPane. This is used to unregister any listeners that were attached.

Overrides:
deinstall in class StyledEditorKit
Parameters:
c - the JEditorPane

setStyleSheet

public void setStyleSheet(StyleSheet s)
Set the set of styles to be used to render the various HTML elements. These styles are specified in terms of CSS specifications. Each document produced by the kit will have a copy of the sheet which it can add the document specific styles to. By default, the StyleSheet specified is shared by all HTMLEditorKit instances. This should be reimplemented to provide a finer granularity if desired.

getStyleSheet

public StyleSheet getStyleSheet()
Get the set of styles currently being used to render the HTML elements. By default the resource specified by DEFAULT_CSS gets loaded, and is shared by all HTMLEditorKit instances.

getActions

public Action[] getActions()
Fetches the command list for the editor. This is the list of commands supported by the superclass augmented by the collection of commands defined locally for style operations.

Overrides:
getActions in class StyledEditorKit
Returns:
the command list

createInputAttributes

protected void createInputAttributes(Element element,
                                     MutableAttributeSet set)
Copies the key/values in elements AttributeSet into set. This does not copy component, icon, or element names attributes. Subclasses may wish to refine what is and what isn't copied here. But be sure to first remove all the attributes that are in set.

This is called anytime the caret moves over a different location.

Overrides:
createInputAttributes in class StyledEditorKit

getInputAttributes

public MutableAttributeSet getInputAttributes()
Gets the input attributes used for the styled editing actions.

Overrides:
getInputAttributes in class StyledEditorKit
Returns:
the attribute set

setDefaultCursor

public void setDefaultCursor(Cursor cursor)
Sets the default cursor.

Since:
1.3

getDefaultCursor

public Cursor getDefaultCursor()
Returns the default cursor.

Since:
1.3

setLinkCursor

public void setLinkCursor(Cursor cursor)
Sets the cursor to use over links.

Since:
1.3

getLinkCursor

public Cursor getLinkCursor()
Returns the cursor to use over hyper links.

Since:
1.3

isAutoFormSubmission

public boolean isAutoFormSubmission()
Indicates whether an html form submission is processed automatically or only FormSubmitEvent is fired.

Returns:
true if html form submission is processed automatically, false otherwise.
Since:
1.5
See Also:
setAutoFormSubmission(boolean)

setAutoFormSubmission

public void setAutoFormSubmission(boolean isAuto)
Specifies if an html form submission is processed automatically or only FormSubmitEvent is fired. By default it is set to true.

Since:
1.5
See Also:
isAutoFormSubmission, FormSubmitEvent

clone

public Object clone()
Creates a copy of the editor kit.

Overrides:
clone in class StyledEditorKit
Returns:
the copy
See Also:
Cloneable

getParser

protected HTMLEditorKit.Parser getParser()
Fetch the parser to use for reading HTML streams. This can be reimplemented to provide a different parser. The default implementation is loaded dynamically to avoid the overhead of loading the default parser if it's not used. The default parser is the HotJava parser using an HTML 3.2 DTD.

getAccessibleContext

public AccessibleContext getAccessibleContext()
returns the AccessibleContext associated with this editor kit

Specified by:
getAccessibleContext in interface Accessible
Returns:
the AccessibleContext associated with this editor kit
Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLEditorKit.HTMLFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLEditorKit.HTMLFactory

java.lang.Object
    extended by  javax.swing.text.html.HTMLEditorKit.HTMLFactory
All Implemented Interfaces:
ViewFactory
Enclosing class:
HTMLEditorKit
public static class HTMLEditorKit.HTMLFactory
extends Object
implements ViewFactory

A factory to build views for HTML. The following table describes what this factory will build by default.
Tag | View created
HTML.Tag.CONTENT | InlineView
HTML.Tag.IMPLIED | javax.swing.text.html.ParagraphView
HTML.Tag.P | javax.swing.text.html.ParagraphView
HTML.Tag.H1 | javax.swing.text.html.ParagraphView
HTML.Tag.H2 | javax.swing.text.html.ParagraphView
HTML.Tag.H3 | javax.swing.text.html.ParagraphView
HTML.Tag.H4 | javax.swing.text.html.ParagraphView
HTML.Tag.H5 | javax.swing.text.html.ParagraphView
HTML.Tag.H6 | javax.swing.text.html.ParagraphView
HTML.Tag.DT | javax.swing.text.html.ParagraphView
HTML.Tag.MENU | ListView
HTML.Tag.DIR | ListView
HTML.Tag.UL | ListView
HTML.Tag.OL | ListView
HTML.Tag.LI | BlockView
HTML.Tag.DL | BlockView
HTML.Tag.DD | BlockView
HTML.Tag.BODY | BlockView
HTML.Tag.HTML | BlockView
HTML.Tag.CENTER | BlockView
HTML.Tag.DIV | BlockView
HTML.Tag.BLOCKQUOTE | BlockView
HTML.Tag.PRE | BlockView
HTML.Tag.BLOCKQUOTE | BlockView
HTML.Tag.PRE | BlockView
HTML.Tag.IMG | ImageView
HTML.Tag.HR | HRuleView
HTML.Tag.BR | BRView
HTML.Tag.TABLE | javax.swing.text.html.TableView
HTML.Tag.INPUT | FormView
HTML.Tag.SELECT | FormView
HTML.Tag.TEXTAREA | FormView
HTML.Tag.OBJECT | ObjectView
HTML.Tag.FRAMESET | FrameSetView
HTML.Tag.FRAME | FrameView

Constructor Summary
HTMLEditorKit.HTMLFactory()
Method Summary
 View create(Element elem)
Creates a view from an element.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HTMLEditorKit.HTMLFactory

public HTMLEditorKit.HTMLFactory()
Method Detail

create

public View create(Element elem)
Creates a view from an element.

Specified by:
create in interface ViewFactory
Parameters:
elem - the element
Returns:
the view
See Also:
View
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLEditorKit.HTMLTextAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLEditorKit.HTMLTextAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.StyledEditorKit.StyledTextAction
                extended by  javax.swing.text.html.HTMLEditorKit.HTMLTextAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Direct Known Subclasses:
HTMLEditorKit.InsertHTMLTextAction
Enclosing class:
HTMLEditorKit
public abstract static class HTMLEditorKit.HTMLTextAction
extends StyledEditorKit.StyledTextAction

An abstract Action providing some convenience methods that may be useful in inserting HTML into an existing document.

NOTE: None of the convenience methods obtain a lock on the document. If you have another thread modifying the text these methods may have inconsistent behavior, or return the wrong thing.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
HTMLEditorKit.HTMLTextAction(String name)
Method Summary
protected int | elementCountToTag(HTMLDocument doc, int offset, HTML.Tag tag) Returns number of elements, starting at the deepest leaf, needed to get to an element representing tag.
protected Element | findElementMatchingTag(HTMLDocument doc, int offset, HTML.Tag tag) Returns the deepest element at offset matching tag.
protected Element[] | getElementsAt(HTMLDocument doc, int offset) Returns an array of the Elements that contain offset.
protected HTMLDocument | getHTMLDocument(JEditorPane e)
protected HTMLEditorKit | getHTMLEditorKit(JEditorPane e)
Methods inherited from class javax.swing.text.StyledEditorKit.StyledTextAction
getEditor, getStyledDocument, getStyledEditorKit, setCharacterAttributes, setParagraphAttributes
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface java.awt.event.ActionListener
actionPerformed

Constructor Detail

HTMLEditorKit.HTMLTextAction

public HTMLEditorKit.HTMLTextAction(String name)
Method Detail

getHTMLDocument

protected HTMLDocument getHTMLDocument(JEditorPane e)
Returns:
HTMLDocument of e.

getHTMLEditorKit

protected HTMLEditorKit getHTMLEditorKit(JEditorPane e)
Returns:
HTMLEditorKit for e.

getElementsAt

protected Element[] getElementsAt(HTMLDocument doc,
                                  int offset)
Returns an array of the Elements that contain offset. The first elements corresponds to the root.

elementCountToTag

protected int elementCountToTag(HTMLDocument doc,
                                int offset,
                                HTML.Tag tag)
Returns number of elements, starting at the deepest leaf, needed to get to an element representing tag. This will return -1 if no elements is found representing tag, or 0 if the parent of the leaf at offset represents tag.

findElementMatchingTag

protected Element findElementMatchingTag(HTMLDocument doc,
                                         int offset,
                                         HTML.Tag tag)
Returns the deepest element at offset matching tag.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLEditorKit.InsertHTMLTextAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLEditorKit.InsertHTMLTextAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.StyledEditorKit.StyledTextAction
                extended by  javax.swing.text.html.HTMLEditorKit.HTMLTextAction
                    extended by  javax.swing.text.html.HTMLEditorKit.InsertHTMLTextAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
HTMLEditorKit
public static class HTMLEditorKit.InsertHTMLTextAction
extends HTMLEditorKit.HTMLTextAction

InsertHTMLTextAction can be used to insert an arbitrary string of HTML into an existing HTML document. At least two HTML.Tags need to be supplied. The first Tag, parentTag, identifies the parent in the document to add the elements to. The second tag, addTag, identifies the first tag that should be added to the document as seen in the HTML string. One important thing to remember, is that the parser is going to generate all the appropriate tags, even if they aren't in the HTML string passed in.

For example, lets say you wanted to create an action to insert a table into the body. The parentTag would be HTML.Tag.BODY, addTag would be HTML.Tag.TABLE, and the string could be something like <table><tr><td></td></tr></table>.

There is also an option to supply an alternate parentTag and addTag. These will be checked for if there is no parentTag at offset.

Field Summary
protected HTML.Tag | addTag Tag in HTML to start adding tags from.
protected HTML.Tag | alternateAddTag Alternate tag in HTML to start adding tags from if parentTag is not found and alternateParentTag is found.
protected HTML.Tag | alternateParentTag Alternate Tag to check for in the document if parentTag is not found.
protected String | html HTML to insert.
protected HTML.Tag | parentTag Tag to check for in the document.
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
HTMLEditorKit.InsertHTMLTextAction(String name, String html, HTML.Tag parentTag, HTML.Tag addTag)
HTMLEditorKit.InsertHTMLTextAction(String name, String html, HTML.Tag parentTag, HTML.Tag addTag, HTML.Tag alternateParentTag, HTML.Tag alternateAddTag)
Method Summary
void | actionPerformed(ActionEvent ae) Inserts the HTML into the document.
protected void | insertAtBoundary(JEditorPane editor, HTMLDocument doc, int offset, Element insertElement, String html, HTML.Tag parentTag, HTML.Tag addTag) This is invoked when inserting at a boundary.
protected void | insertAtBoundry(JEditorPane editor, HTMLDocument doc, int offset, Element insertElement, String html, HTML.Tag parentTag, HTML.Tag addTag) Deprecated. As of Java 2 platform v1.3, use insertAtBoundary
protected void | insertHTML(JEditorPane editor, HTMLDocument doc, int offset, String html, int popDepth, int pushDepth, HTML.Tag addTag) A cover for HTMLEditorKit.insertHTML.
Methods inherited from class javax.swing.text.html.HTMLEditorKit.HTMLTextAction
elementCountToTag, findElementMatchingTag, getElementsAt, getHTMLDocument, getHTMLEditorKit
Methods inherited from class javax.swing.text.StyledEditorKit.StyledTextAction
getEditor, getStyledDocument, getStyledEditorKit, setCharacterAttributes, setParagraphAttributes
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

html

protected String html
HTML to insert.

parentTag

protected HTML.Tag parentTag
Tag to check for in the document.

addTag

protected HTML.Tag addTag
Tag in HTML to start adding tags from.

alternateParentTag

protected HTML.Tag alternateParentTag
Alternate Tag to check for in the document if parentTag is not found.

alternateAddTag

protected HTML.Tag alternateAddTag
Alternate tag in HTML to start adding tags from if parentTag is not found and alternateParentTag is found.

Constructor Detail

HTMLEditorKit.InsertHTMLTextAction

public HTMLEditorKit.InsertHTMLTextAction(String name,
                                          String html,
                                          HTML.Tag parentTag,
                                          HTML.Tag addTag)

HTMLEditorKit.InsertHTMLTextAction

public HTMLEditorKit.InsertHTMLTextAction(String name,
                                          String html,
                                          HTML.Tag parentTag,
                                          HTML.Tag addTag,
                                          HTML.Tag alternateParentTag,
                                          HTML.Tag alternateAddTag)
Method Detail

insertHTML

protected void insertHTML(JEditorPane editor,
                          HTMLDocument doc,
                          int offset,
                          String html,
                          int popDepth,
                          int pushDepth,
                          HTML.Tag addTag)
A cover for HTMLEditorKit.insertHTML. If an exception it thrown it is wrapped in a RuntimeException and thrown.

insertAtBoundary

protected void insertAtBoundary(JEditorPane editor,
                                HTMLDocument doc,
                                int offset,
                                Element insertElement,
                                String html,
                                HTML.Tag parentTag,
                                HTML.Tag addTag)
This is invoked when inserting at a boundary. It determines the number of pops, and then the number of pushes that need to be performed, and then invokes insertHTML.

Since:
1.3

insertAtBoundry

@Deprecated
protected void insertAtBoundry(JEditorPane editor,
                                          HTMLDocument doc,
                                          int offset,
                                          Element insertElement,
                                          String html,
                                          HTML.Tag parentTag,
                                          HTML.Tag addTag)
Deprecated. As of Java 2 platform v1.3, use insertAtBoundary

This is invoked when inserting at a boundary. It determines the number of pops, and then the number of pushes that need to be performed, and then invokes insertHTML.

actionPerformed

public void actionPerformed(ActionEvent ae)
Inserts the HTML into the document.

Parameters:
ae - the event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLEditorKit.LinkController

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLEditorKit.LinkController

java.lang.Object
    extended by  java.awt.event.MouseAdapter
        extended by  javax.swing.text.html.HTMLEditorKit.LinkController
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, Serializable, EventListener
Enclosing class:
HTMLEditorKit
public static class HTMLEditorKit.LinkController
extends MouseAdapter
implements MouseMotionListener, Serializable

Class to watch the associated component and fire hyperlink events on it when appropriate.

Constructor Summary
HTMLEditorKit.LinkController()
Method Summary
protected void | activateLink(int pos, JEditorPane editor) Calls linkActivated on the associated JEditorPane if the given position represents a link.
void | mouseClicked(MouseEvent e) Called for a mouse click event.
void | mouseDragged(MouseEvent e) Invoked when a mouse button is pressed on a component and then dragged.
void | mouseMoved(MouseEvent e) Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.
Methods inherited from class java.awt.event.MouseAdapter
mouseEntered, mouseExited, mousePressed, mouseReleased, mouseWheelMoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HTMLEditorKit.LinkController

public HTMLEditorKit.LinkController()
Method Detail

mouseClicked

public void mouseClicked(MouseEvent e)
Called for a mouse click event. If the component is read-only (ie a browser) then the clicked event is used to drive an attempt to follow the reference specified by a link.

Specified by:
mouseClicked in interface MouseListener
Overrides:
mouseClicked in class MouseAdapter
Parameters:
e - the mouse event
See Also:
MouseListener.mouseClicked(java.awt.event.MouseEvent)

mouseDragged

public void mouseDragged(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when a mouse button is pressed on a component and then dragged. MOUSE_DRAGGED events will continue to be delivered to the component where the drag originated until the mouse button is released (regardless of whether the mouse position is within the bounds of the component).

Due to platform-dependent Drag&Drop implementations, MOUSE_DRAGGED events may not be delivered during a native Drag&Drop operation.

Specified by:
mouseDragged in interface MouseMotionListener
Overrides:
mouseDragged in class MouseAdapter

mouseMoved

public void mouseMoved(MouseEvent e)
Description copied from class: MouseAdapter
Invoked when the mouse cursor has been moved onto a component but no buttons have been pushed.

Specified by:
mouseMoved in interface MouseMotionListener
Overrides:
mouseMoved in class MouseAdapter

activateLink

protected void activateLink(int pos,
                            JEditorPane editor)
Calls linkActivated on the associated JEditorPane if the given position represents a link.

This is implemented to forward to the method with the same name, but with the following args both == -1.

Parameters:
pos - the position
editor - the editor pane
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLEditorKit.Parser

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLEditorKit.Parser

java.lang.Object
    extended by  javax.swing.text.html.HTMLEditorKit.Parser
Direct Known Subclasses:
ParserDelegator
Enclosing class:
HTMLEditorKit
public abstract static class HTMLEditorKit.Parser
extends Object

Interface to be supported by the parser. This enables providing a different parser while reusing some of the implementation provided by this editor kit.

Constructor Summary
HTMLEditorKit.Parser()
Method Summary
abstract  void parse(Reader r, HTMLEditorKit.ParserCallback cb, boolean ignoreCharSet)
Parse the given stream and drive the given callback with the results of the parse.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HTMLEditorKit.Parser

public HTMLEditorKit.Parser()
Method Detail

parse

public abstract void parse(Reader r,
                           HTMLEditorKit.ParserCallback cb,
                           boolean ignoreCharSet)
                    throws IOException
Parse the given stream and drive the given callback with the results of the parse. This method should be implemented to be thread-safe.

Throws:
IOException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLEditorKit.ParserCallback

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLEditorKit.ParserCallback

java.lang.Object
    extended by  javax.swing.text.html.HTMLEditorKit.ParserCallback
Direct Known Subclasses:
HTMLDocument.HTMLReader
Enclosing class:
HTMLEditorKit
public static class HTMLEditorKit.ParserCallback
extends Object

The result of parsing drives these callback methods. The open and close actions should be balanced. The flush method will be the last method called, to give the receiver a chance to flush any pending data into the document.

Refer to DocumentParser, the default parser used, for further information on the contents of the AttributeSets, the positions, and other info.

See Also:
DocumentParser

Field Summary
static Object IMPLIED
This is passed as an attribute in the attributeset to indicate the element is implied eg, the string '<>foo<\t>' contains an implied html element and an implied body element.
Constructor Summary
HTMLEditorKit.ParserCallback()
Method Summary
void | flush()
void | handleComment(char[] data, int pos)
void | handleEndOfLineString(String eol) This is invoked after the stream has been parsed, but before flush.
void | handleEndTag(HTML.Tag t, int pos)
void | handleError(String errorMsg, int pos)
void | handleSimpleTag(HTML.Tag t, MutableAttributeSet a, int pos)
void | handleStartTag(HTML.Tag t, MutableAttributeSet a, int pos)
void | handleText(char[] data, int pos)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

IMPLIED

public static final Object IMPLIED
This is passed as an attribute in the attributeset to indicate the element is implied eg, the string '<>foo<\t>' contains an implied html element and an implied body element.

Since:
1.3
Constructor Detail

HTMLEditorKit.ParserCallback

public HTMLEditorKit.ParserCallback()
Method Detail

flush

public void flush()
           throws BadLocationException
Throws:
BadLocationException

handleText

public void handleText(char[] data,
                       int pos)

handleComment

public void handleComment(char[] data,
                          int pos)

handleStartTag

public void handleStartTag(HTML.Tag t,
                           MutableAttributeSet a,
                           int pos)

handleEndTag

public void handleEndTag(HTML.Tag t,
                         int pos)

handleSimpleTag

public void handleSimpleTag(HTML.Tag t,
                            MutableAttributeSet a,
                            int pos)

handleError

public void handleError(String errorMsg,
                        int pos)

handleEndOfLineString

public void handleEndOfLineString(String eol)
This is invoked after the stream has been parsed, but before flush. eol will be one of \n, \r or \r\n, which ever is encountered the most in parsing the stream.

Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLFrameHyperlinkEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLFrameHyperlinkEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  javax.swing.event.HyperlinkEvent
            extended by  javax.swing.text.html.HTMLFrameHyperlinkEvent
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
FormSubmitEvent
public class HTMLFrameHyperlinkEvent
extends HyperlinkEvent

HTMLFrameHyperlinkEvent is used to notify interested parties that link was activated in a frame.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.event.HyperlinkEvent
HyperlinkEvent.EventType
Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
HTMLFrameHyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL targetURL, Element sourceElement, String targetFrame)
Creates a new object representing a hypertext link event.
HTMLFrameHyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL targetURL, String targetFrame)
Creates a new object representing a html frame hypertext link event.
HTMLFrameHyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL targetURL, String desc, Element sourceElement, String targetFrame)
Creates a new object representing a hypertext link event.
HTMLFrameHyperlinkEvent(Object source, HyperlinkEvent.EventType type, URL targetURL, String desc, String targetFrame)
Creates a new object representing a hypertext link event.
Method Summary
 String getTarget()
returns the target for the link.
Methods inherited from class javax.swing.event.HyperlinkEvent
getDescription, getEventType, getSourceElement, getURL
Methods inherited from class java.util.EventObject
getSource, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

HTMLFrameHyperlinkEvent

public HTMLFrameHyperlinkEvent(Object source,
                               HyperlinkEvent.EventType type,
                               URL targetURL,
                               String targetFrame)
Creates a new object representing a html frame hypertext link event.

Parameters:
source - the object responsible for the event
type - the event type
targetURL - the affected URL
targetFrame - the Frame to display the document in

HTMLFrameHyperlinkEvent

public HTMLFrameHyperlinkEvent(Object source,
                               HyperlinkEvent.EventType type,
                               URL targetURL,
                               String desc,
                               String targetFrame)
Creates a new object representing a hypertext link event.

Parameters:
source - the object responsible for the event
type - the event type
targetURL - the affected URL
desc - a description
targetFrame - the Frame to display the document in

HTMLFrameHyperlinkEvent

public HTMLFrameHyperlinkEvent(Object source,
                               HyperlinkEvent.EventType type,
                               URL targetURL,
                               Element sourceElement,
                               String targetFrame)
Creates a new object representing a hypertext link event.

Parameters:
source - the object responsible for the event
type - the event type
targetURL - the affected URL
sourceElement - the element that corresponds to the source of the event
targetFrame - the Frame to display the document in

HTMLFrameHyperlinkEvent

public HTMLFrameHyperlinkEvent(Object source,
                               HyperlinkEvent.EventType type,
                               URL targetURL,
                               String desc,
                               Element sourceElement,
                               String targetFrame)
Creates a new object representing a hypertext link event.

Parameters:
source - the object responsible for the event
type - the event type
targetURL - the affected URL
desc - a desription
sourceElement - the element that corresponds to the source of the event
targetFrame - the Frame to display the document in
Method Detail

getTarget

public String getTarget()
returns the target for the link.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HTMLWriter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class HTMLWriter

java.lang.Object
    extended by  javax.swing.text.AbstractWriter
        extended by  javax.swing.text.html.HTMLWriter

public class HTMLWriter
extends AbstractWriter

This is a writer for HTMLDocuments.

Field Summary
Fields inherited from class javax.swing.text.AbstractWriter
NEWLINE
Constructor Summary
HTMLWriter(Writer w, HTMLDocument doc)
Creates a new HTMLWriter.
HTMLWriter(Writer w, HTMLDocument doc, int pos, int len)
Creates a new HTMLWriter.
Method Summary
protected void | closeOutUnwantedEmbeddedTags(AttributeSet attr) Searches the attribute set and for each tag that is stored in the tag vector.
protected void | comment(Element elem) Writes out comments.
protected void | emptyTag(Element elem) Writes out all empty elements (all tags that have no corresponding end tag).
protected void | endTag(Element elem) Writes out an end tag for the element.
protected boolean | isBlockTag(AttributeSet attr) Determines if the HTML.Tag associated with the element is a block tag.
protected boolean | matchNameAttribute(AttributeSet attr, HTML.Tag tag) Returns true if the StyleConstants.NameAttribute is equal to the tag that is passed in as a parameter.
protected void | output(char[] chars, int start, int length) This method is overriden to map any character entities, such as < to &lt;.
protected void | selectContent(AttributeSet attr) Writes out the content of the SELECT form element.
protected void | startTag(Element elem) Writes out a start tag for the element.
protected boolean | synthesizedElement(Element elem) Returns true if the element is a synthesized element.
protected void | text(Element elem) Writes out text.
protected void | textAreaContent(AttributeSet attr) Writes out text that is contained in a TEXTAREA form element.
void | write() Iterates over the Element tree and controls the writing out of all the tags and its attributes.
protected void | writeAttributes(AttributeSet attr) Writes out the attribute set.
protected void | writeEmbeddedTags(AttributeSet attr) Searches for embedded tags in the AttributeSet and writes them out.
protected void | writeLineSeparator() Writes the line separator.
protected void | writeOption(Option option) Writes out the content of the Option form element.
Methods inherited from class javax.swing.text.AbstractWriter
decrIndent, getCanWrapLines, getCurrentLineLength, getDocument, getElementIterator, getEndOffset, getIndentLevel, getIndentSpace, getLineLength, getLineSeparator, getStartOffset, getText, getWriter, incrIndent, indent, inRange, isLineEmpty, setCanWrapLines, setCurrentLineLength, setIndentSpace, setLineLength, setLineSeparator, write, write, write
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HTMLWriter

public HTMLWriter(Writer w,
                  HTMLDocument doc)
Creates a new HTMLWriter.

Parameters:
w - a Writer
doc - an HTMLDocument

HTMLWriter

public HTMLWriter(Writer w,
                  HTMLDocument doc,
                  int pos,
                  int len)
Creates a new HTMLWriter.

Parameters:
w - a Writer
doc - an HTMLDocument
pos - the document location from which to fetch the content
len - the amount to write out
Method Detail

write

public void write()
           throws IOException,
                  BadLocationException
Iterates over the Element tree and controls the writing out of all the tags and its attributes.

Specified by:
write in class AbstractWriter
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

writeAttributes

protected void writeAttributes(AttributeSet attr)
                        throws IOException
Writes out the attribute set. Ignores all attributes with a key of type HTML.Tag, attributes with a key of type StyleConstants, and attributes with a key of type HTML.Attribute.ENDTAG.

Overrides:
writeAttributes in class AbstractWriter
Parameters:
attr - an AttributeSet
Throws:
IOException - on any I/O error

emptyTag

protected void emptyTag(Element elem)
                 throws BadLocationException,
                        IOException
Writes out all empty elements (all tags that have no corresponding end tag).

Parameters:
elem - an Element
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

isBlockTag

protected boolean isBlockTag(AttributeSet attr)
Determines if the HTML.Tag associated with the element is a block tag.

Parameters:
attr - an AttributeSet
Returns:
true if tag is block tag, false otherwise.

startTag

protected void startTag(Element elem)
                 throws IOException,
                        BadLocationException
Writes out a start tag for the element. Ignores all synthesized elements.

Parameters:
elem - an Element
Throws:
IOException - on any I/O error
BadLocationException

textAreaContent

protected void textAreaContent(AttributeSet attr)
                        throws BadLocationException,
                               IOException
Writes out text that is contained in a TEXTAREA form element.

Parameters:
attr - an AttributeSet
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

text

protected void text(Element elem)
             throws BadLocationException,
                    IOException
Writes out text. If a range is specified when the constructor is invoked, then only the appropriate range of text is written out.

Overrides:
text in class AbstractWriter
Parameters:
elem - an Element
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

selectContent

protected void selectContent(AttributeSet attr)
                      throws IOException
Writes out the content of the SELECT form element.

Parameters:
attr - the AttributeSet associated with the form element
Throws:
IOException - on any I/O error

writeOption

protected void writeOption(Option option)
                    throws IOException
Writes out the content of the Option form element.

Parameters:
option - an Option
Throws:
IOException - on any I/O error

endTag

protected void endTag(Element elem)
               throws IOException
Writes out an end tag for the element.

Parameters:
elem - an Element
Throws:
IOException - on any I/O error

comment

protected void comment(Element elem)
                throws BadLocationException,
                       IOException
Writes out comments.

Parameters:
elem - an Element
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

synthesizedElement

protected boolean synthesizedElement(Element elem)
Returns true if the element is a synthesized element. Currently we are only testing for the p-implied tag.

matchNameAttribute

protected boolean matchNameAttribute(AttributeSet attr,
                                     HTML.Tag tag)
Returns true if the StyleConstants.NameAttribute is equal to the tag that is passed in as a parameter.

writeEmbeddedTags

protected void writeEmbeddedTags(AttributeSet attr)
                          throws IOException
Searches for embedded tags in the AttributeSet and writes them out. It also stores these tags in a vector so that when appropriate the corresponding end tags can be written out.

Throws:
IOException - on any I/O error

closeOutUnwantedEmbeddedTags

protected void closeOutUnwantedEmbeddedTags(AttributeSet attr)
                                     throws IOException
Searches the attribute set and for each tag that is stored in the tag vector. If the tag isnt found, then the tag is removed from the vector and a corresponding end tag is written out.

Throws:
IOException - on any I/O error

writeLineSeparator

protected void writeLineSeparator()
                           throws IOException
Writes the line separator. This is overriden to make sure we don't replace the newline content in case it is outside normal ascii.

Overrides:
writeLineSeparator in class AbstractWriter
Throws:
IOException
Since:
1.3

output

protected void output(char[] chars,
                      int start,
                      int length)
               throws IOException
This method is overriden to map any character entities, such as < to &lt;. super.output will be invoked to write the content.

Overrides:
output in class AbstractWriter
Throws:
IOException
Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ImageView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class ImageView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.html.ImageView
All Implemented Interfaces:
SwingConstants
public class ImageView
extends View

View of an Image, intended to support the HTML <IMG> tag. Supports scaling via the HEIGHT and WIDTH attributes of the tag. If the image is unable to be loaded any text specified via the ALT attribute will be rendered.

While this class has been part of swing for a while now, it is public as of 1.4.

Since:
1.4
See Also:
IconView

Field Summary
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
ImageView(Element elem)
Creates a new view that represents an IMG element.
Method Summary
void | changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Invoked when the Elements attributes have changed.
float | getAlignment(int axis) Determines the desired alignment for this view along an axis.
String | getAltText() Returns the text to display if the image can't be loaded.
AttributeSet | getAttributes() Fetches the attributes to use when rendering.
Image | getImage() Returns the image to render.
URL | getImageURL() Return a URL for the image source, or null if it could not be determined.
Icon | getLoadingImageIcon() Returns the icon to use while in the process of loading the image.
boolean | getLoadsSynchronously() Returns true if the image should be loaded when first asked for.
Icon | getNoImageIcon() Returns the icon to use if the image couldn't be found.
float | getPreferredSpan(int axis) Determines the preferred span for this view along an axis.
protected StyleSheet | getStyleSheet() Convenience method to get the StyleSheet.
String | getToolTipText(float x, float y, Shape allocation) For images the tooltip text comes from text specified with the ALT attribute.
Shape | modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
void | paint(Graphics g, Shape a) Paints the View.
void | setLoadsSynchronously(boolean newValue) Sets how the image is loaded.
void | setParent(View parent) Establishes the parent view for this view.
protected void | setPropertiesFromAttributes() Update any cached values that come from attributes.
void | setSize(float width, float height) Sets the size of the view.
int | viewToModel(float x, float y, Shape a, Position.Bias[] bias) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
Methods inherited from class javax.swing.text.View
append, breakView, createFragment, forwardUpdate, forwardUpdateToView, getBreakWeight, getChildAllocation, getContainer, getDocument, getElement, getEndOffset, getGraphics, getMaximumSpan, getMinimumSpan, getNextVisualPositionFrom, getParent, getResizeWeight, getStartOffset, getView, getViewCount, getViewFactory, getViewIndex, getViewIndex, insert, insertUpdate, isVisible, modelToView, modelToView, preferenceChanged, remove, removeAll, removeUpdate, replace, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ImageView

public ImageView(Element elem)
Creates a new view that represents an IMG element.

Parameters:
elem - the element to create a view for
Method Detail

getAltText

public String getAltText()
Returns the text to display if the image can't be loaded. This is obtained from the Elements attribute set with the attribute name HTML.Attribute.ALT.

getImageURL

public URL getImageURL()
Return a URL for the image source, or null if it could not be determined.

getNoImageIcon

public Icon getNoImageIcon()
Returns the icon to use if the image couldn't be found.

getLoadingImageIcon

public Icon getLoadingImageIcon()
Returns the icon to use while in the process of loading the image.

getImage

public Image getImage()
Returns the image to render.

setLoadsSynchronously

public void setLoadsSynchronously(boolean newValue)
Sets how the image is loaded. If newValue is true, the image we be loaded when first asked for, otherwise it will be loaded asynchronously. The default is to not load synchronously, that is to load the image asynchronously.

getLoadsSynchronously

public boolean getLoadsSynchronously()
Returns true if the image should be loaded when first asked for.

getStyleSheet

protected StyleSheet getStyleSheet()
Convenience method to get the StyleSheet.

getAttributes

public AttributeSet getAttributes()
Fetches the attributes to use when rendering. This is implemented to multiplex the attributes specified in the model with a StyleSheet.

Overrides:
getAttributes in class View

getToolTipText

public String getToolTipText(float x,
                             float y,
                             Shape allocation)
For images the tooltip text comes from text specified with the ALT attribute. This is overriden to return getAltText.

Overrides:
getToolTipText in class View
See Also:
JTextComponent.getToolTipText(java.awt.event.MouseEvent)

setPropertiesFromAttributes

protected void setPropertiesFromAttributes()
Update any cached values that come from attributes.

setParent

public void setParent(View parent)
Establishes the parent view for this view. Seize this moment to cache the AWT Container I'm in.

Overrides:
setParent in class View
Parameters:
parent - the new parent, or null if the view is being removed from a parent

changedUpdate

public void changedUpdate(DocumentEvent e,
                          Shape a,
                          ViewFactory f)
Invoked when the Elements attributes have changed. Recreates the image.

Overrides:
changedUpdate in class View
Parameters:
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

paint

public void paint(Graphics g,
                  Shape a)
Paints the View.

Specified by:
paint in class View
Parameters:
g - the rendering surface to use
a - the allocated region to render into
See Also:
View.paint(java.awt.Graphics, java.awt.Shape)

getPreferredSpan

public float getPreferredSpan(int axis)
Determines the preferred span for this view along an axis.

Specified by:
getPreferredSpan in class View
Parameters:
axis - may be either X_AXIS or Y_AXIS
Returns:
the span the view would like to be rendered into; typically the view is told to render into the span that is returned, although there is no guarantee; the parent may choose to resize or break the view
See Also:
View.getPreferredSpan(int)

getAlignment

public float getAlignment(int axis)
Determines the desired alignment for this view along an axis. This is implemented to give the alignment to the bottom of the icon along the y axis, and the default along the x axis.

Overrides:
getAlignment in class View
Parameters:
axis - may be either X_AXIS or Y_AXIS
Returns:
the desired alignment; this should be a value between 0.0 and 1.0 where 0 indicates alignment at the origin and 1.0 indicates alignment to the full span away from the origin; an alignment of 0.5 would be the center of the view

modelToView

public Shape modelToView(int pos,
                         Shape a,
                         Position.Bias b)
                  throws BadLocationException
Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.

Specified by:
modelToView in class View
Parameters:
pos - the position to convert
a - the allocated region to render into
b - the bias toward the previous character or the next character represented by the offset, in case the position is a boundary of two views; b will have one of these values:
  • Position.Bias.Forward
  • Position.Bias.Backward
Returns:
the bounding box of the given position
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
See Also:
View.modelToView(int, java.awt.Shape, javax.swing.text.Position.Bias)

viewToModel

public int viewToModel(float x,
                       float y,
                       Shape a,
                       Position.Bias[] bias)
Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Specified by:
viewToModel in class View
Parameters:
x - the X coordinate
y - the Y coordinate
a - the allocated region to render into
Returns:
the location within the model that best represents the given point of view
See Also:
View.viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])

setSize

public void setSize(float width,
                    float height)
Sets the size of the view. This should cause layout of the view if it has any layout duties.

Overrides:
setSize in class View
Parameters:
width - the width >= 0
height - the height >= 0
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InlineView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class InlineView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.GlyphView
            extended by  javax.swing.text.LabelView
                extended by  javax.swing.text.html.InlineView
All Implemented Interfaces:
Cloneable, SwingConstants, TabableView
public class InlineView
extends LabelView

Displays the inline element styles based upon css attributes.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.text.GlyphView
GlyphView.GlyphPainter
Field Summary
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
InlineView(Element elem)
Constructs a new view wrapped on an element.
Method Summary
View | breakView(int axis, int offset, float pos, float len) Tries to break this view on the given axis.
void | changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
AttributeSet | getAttributes() Fetches the attributes to use when rendering.
int | getBreakWeight(int axis, float pos, float len) Determines how attractive a break opportunity in this view is.
protected StyleSheet | getStyleSheet()
void | insertUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
void | removeUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
protected void | setPropertiesFromAttributes() Set the cached properties from the attributes.
Methods inherited from class javax.swing.text.LabelView
getBackground, getFont, getFontMetrics, getForeground, isStrikeThrough, isSubscript, isSuperscript, isUnderline, setBackground, setStrikeThrough, setSubscript, setSuperscript, setUnderline
Methods inherited from class javax.swing.text.GlyphView
checkPainter, clone, createFragment, getAlignment, getEndOffset, getGlyphPainter, getNextVisualPositionFrom, getPartialSpan, getPreferredSpan, getStartOffset, getTabbedSpan, getTabExpander, getText, modelToView, paint, setGlyphPainter, viewToModel
Methods inherited from class javax.swing.text.View
append, forwardUpdate, forwardUpdateToView, getChildAllocation, getContainer, getDocument, getElement, getGraphics, getMaximumSpan, getMinimumSpan, getParent, getResizeWeight, getToolTipText, getView, getViewCount, getViewFactory, getViewIndex, getViewIndex, insert, isVisible, modelToView, modelToView, preferenceChanged, remove, removeAll, replace, setParent, setSize, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.swing.text.TabableView
getPartialSpan, getTabbedSpan

Constructor Detail

InlineView

public InlineView(Element elem)
Constructs a new view wrapped on an element.

Parameters:
elem - the element
Method Detail

insertUpdate

public void insertUpdate(DocumentEvent e,
                         Shape a,
                         ViewFactory f)
Gives notification that something was inserted into the document in a location that this view is responsible for. If either parameter is null, behavior of this method is implementation dependent.

Overrides:
insertUpdate in class GlyphView
Parameters:
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
Since:
1.5
See Also:
View.insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

removeUpdate

public void removeUpdate(DocumentEvent e,
                         Shape a,
                         ViewFactory f)
Gives notification that something was removed from the document in a location that this view is responsible for. If either parameter is null, behavior of this method is implementation dependent.

Overrides:
removeUpdate in class GlyphView
Parameters:
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
Since:
1.5
See Also:
View.removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

changedUpdate

public void changedUpdate(DocumentEvent e,
                          Shape a,
                          ViewFactory f)
Gives notification from the document that attributes were changed in a location that this view is responsible for.

Overrides:
changedUpdate in class LabelView
Parameters:
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

getAttributes

public AttributeSet getAttributes()
Fetches the attributes to use when rendering. This is implemented to multiplex the attributes specified in the model with a StyleSheet.

Overrides:
getAttributes in class View

getBreakWeight

public int getBreakWeight(int axis,
                          float pos,
                          float len)
Determines how attractive a break opportunity in this view is. This can be used for determining which view is the most attractive to call breakView on in the process of formatting. A view that represents text that has whitespace in it might be more attractive than a view that has no whitespace, for example. The higher the weight, the more attractive the break. A value equal to or lower than BadBreakWeight should not be considered for a break. A value greater than or equal to ForcedBreakWeight should be broken.

This is implemented to provide the default behavior of returning BadBreakWeight unless the length is greater than the length of the view in which case the entire view represents the fragment. Unless a view has been written to support breaking behavior, it is not attractive to try and break the view. An example of a view that does support breaking is LabelView. An example of a view that uses break weight is ParagraphView.

Overrides:
getBreakWeight in class GlyphView
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
pos - the potential location of the start of the broken view >= 0. This may be useful for calculating tab positions.
len - specifies the relative length from pos where a potential break is desired >= 0.
Returns:
the weight, which should be a value between ForcedBreakWeight and BadBreakWeight.
See Also:
LabelView, ParagraphView, View.BadBreakWeight, View.GoodBreakWeight, View.ExcellentBreakWeight, View.ForcedBreakWeight

breakView

public View breakView(int axis,
                      int offset,
                      float pos,
                      float len)
Tries to break this view on the given axis. Refer to View.breakView(int, int, float, float) for a complete description of this method.

Behavior of this method is unspecified in case axis is neither View.X_AXIS nor View.Y_AXIS, and in case offset, pos, or len is null.

Overrides:
breakView in class GlyphView
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
offset - the location in the document model that a broken fragment would occupy >= 0. This would be the starting offset of the fragment returned
pos - the position along the axis that the broken view would occupy >= 0. This may be useful for things like tab calculations
len - specifies the distance along the axis where a potential break is desired >= 0
Returns:
the fragment of the view that represents the given span.
Since:
1.5
See Also:
View.breakView(int, int, float, float)

setPropertiesFromAttributes

protected void setPropertiesFromAttributes()
Set the cached properties from the attributes.

Overrides:
setPropertiesFromAttributes in class LabelView

getStyleSheet

protected StyleSheet getStyleSheet()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ListView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class ListView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.CompositeView
            extended by  javax.swing.text.BoxView
                extended by  javax.swing.text.html.BlockView
                    extended by  javax.swing.text.html.ListView
All Implemented Interfaces:
SwingConstants
public class ListView
extends BlockView

A view implementation to display an html list

Field Summary
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
ListView(Element elem)
Creates a new view that represents a list element.
Method Summary
 float getAlignment(int axis)
Calculates the desired shape of the list.
 void paint(Graphics g, Shape allocation)
Renders using the given rendering surface and area on that surface.
protected  void paintChild(Graphics g, Rectangle alloc, int index)
Paints one of the children; called by paint().
protected  void setPropertiesFromAttributes()
Update any cached values that come from attributes.
Methods inherited from class javax.swing.text.html.BlockView
calculateMajorAxisRequirements, calculateMinorAxisRequirements, changedUpdate, getAttributes, getMaximumSpan, getMinimumSpan, getPreferredSpan, getResizeWeight, getStyleSheet, layoutMinorAxis, setParent
Methods inherited from class javax.swing.text.BoxView
baselineLayout, baselineRequirements, childAllocation, flipEastAndWestAtEnds, forwardUpdate, getAxis, getChildAllocation, getHeight, getOffset, getSpan, getViewAtPoint, getWidth, isAfter, isAllocationValid, isBefore, isLayoutValid, layout, layoutChanged, layoutMajorAxis, modelToView, preferenceChanged, replace, setAxis, setSize, viewToModel
Methods inherited from class javax.swing.text.CompositeView
getBottomInset, getInsideAllocation, getLeftInset, getNextEastWestVisualPositionFrom, getNextNorthSouthVisualPositionFrom, getNextVisualPositionFrom, getRightInset, getTopInset, getView, getViewAtPosition, getViewCount, getViewIndex, getViewIndexAtPosition, loadChildren, modelToView, setInsets, setParagraphInsets
Methods inherited from class javax.swing.text.View
append, breakView, createFragment, forwardUpdateToView, getBreakWeight, getContainer, getDocument, getElement, getEndOffset, getGraphics, getParent, getStartOffset, getToolTipText, getViewFactory, getViewIndex, insert, insertUpdate, isVisible, modelToView, remove, removeAll, removeUpdate, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ListView

public ListView(Element elem)
Creates a new view that represents a list element.

Parameters:
elem - the element to create a view for
Method Detail

getAlignment

public float getAlignment(int axis)
Calculates the desired shape of the list.

Overrides:
getAlignment in class BlockView
Parameters:
axis - may be either X_AXIS or Y_AXIS
Returns:
the desired span
See Also:
View.getPreferredSpan(int)

paint

public void paint(Graphics g,
                  Shape allocation)
Renders using the given rendering surface and area on that surface.

Overrides:
paint in class BlockView
Parameters:
g - the rendering surface to use
allocation - the allocated region to render into
See Also:
View.paint(java.awt.Graphics, java.awt.Shape)

paintChild

protected void paintChild(Graphics g,
                          Rectangle alloc,
                          int index)
Paints one of the children; called by paint(). By default that is all it does, but a subclass can use this to paint things relative to the child.

Overrides:
paintChild in class BoxView
Parameters:
g - the graphics context
alloc - the allocated region to render the child into
index - the index of the child

setPropertiesFromAttributes

protected void setPropertiesFromAttributes()
Description copied from class: BlockView
Update any cached values that come from attributes.

Overrides:
setPropertiesFromAttributes in class BlockView
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MinimalHTMLWriter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class MinimalHTMLWriter

java.lang.Object
    extended by  javax.swing.text.AbstractWriter
        extended by  javax.swing.text.html.MinimalHTMLWriter

public class MinimalHTMLWriter
extends AbstractWriter

MinimalHTMLWriter is a fallback writer used by the HTMLEditorKit to write out HTML for a document that is a not produced by the EditorKit. The format for the document is:

 <html>
   <head>
     <style>
        <!-- list of named styles
         p.normal {
            font-family: SansSerif;
              margin-height: 0;
              font-size: 14
           }
        -->
      </style>
   </head>
   <body>
    <p style=normal>
        Bold, italic, and underline attributes
        of the run are emitted as HTML tags.
        The remaining attributes are emitted as
        part of the style attribute of a <span> tag.
        The syntax is similar to inline styles.
    </p>
   </body>
 </html>

Field Summary
Fields inherited from class javax.swing.text.AbstractWriter
NEWLINE
Constructor Summary
MinimalHTMLWriter(Writer w, StyledDocument doc)
Creates a new MinimalHTMLWriter.
MinimalHTMLWriter(Writer w, StyledDocument doc, int pos, int len)
Creates a new MinimalHTMLWriter.
Method Summary
protected  void endFontTag()
This is no longer used, instead <span> will be written out.
protected  boolean inFontTag()
Returns true if we are currently in a <font> tag.
protected  boolean isText(Element elem)
Returns true if the element is a text element.
protected  void startFontTag(String style)
This is no longer used, instead <span> will be written out.
protected  void text(Element elem)
Writes out text.
 void write()
Generates HTML output from a StyledDocument.
protected  void writeAttributes(AttributeSet attr)
Writes out all the attributes for the following types: StyleConstants.ParagraphConstants, StyleConstants.CharacterConstants, StyleConstants.FontConstants, StyleConstants.ColorConstants.
protected  void writeBody()
Iterates over the elements in the document and processes elements based on whether they are branch elements or leaf elements.
protected  void writeComponent(Element elem)
Responsible for handling Component Elements; deliberately unimplemented.
protected  void writeContent(Element elem, boolean needsIndenting)
Writes out the attribute set in an HTML-compliant manner.
protected  void writeEndParagraph()
Emits an end tag for a <p> tag.
protected  void writeEndTag(String endTag)
Writes out an end tag appropriately indented.
protected  void writeHeader()
Writes out the <head> and <style> tags, and then invokes writeStyles() to write out all the named styles as the content of the <style> tag.
protected  void writeHTMLTags(AttributeSet attr)
Generates bold <b>, italic <i>, and <u> tags for the text based on its attribute settings.
protected  void writeImage(Element elem)
Responsible for handling Icon Elements; deliberately unimplemented.
protected  void writeLeaf(Element elem)
Responsible for writing out other non-text leaf elements.
protected  void writeNonHTMLAttributes(AttributeSet attr)
Writes out the remaining character-level attributes (attributes other than bold, italic, and underline) in an HTML-compliant way.
protected  void writeStartParagraph(Element elem)
Emits the start tag for a paragraph.
protected  void writeStartTag(String tag)
Writes out a start tag appropriately indented.
protected  void writeStyles()
Writes out all the named styles as the content of the <style> tag.
Methods inherited from class javax.swing.text.AbstractWriter
decrIndent, getCanWrapLines, getCurrentLineLength, getDocument, getElementIterator, getEndOffset, getIndentLevel, getIndentSpace, getLineLength, getLineSeparator, getStartOffset, getText, getWriter, incrIndent, indent, inRange, isLineEmpty, output, setCanWrapLines, setCurrentLineLength, setIndentSpace, setLineLength, setLineSeparator, write, write, write, writeLineSeparator
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MinimalHTMLWriter

public MinimalHTMLWriter(Writer w,
                         StyledDocument doc)
Creates a new MinimalHTMLWriter.

Parameters:
w - Writer
doc - StyledDocument

MinimalHTMLWriter

public MinimalHTMLWriter(Writer w,
                         StyledDocument doc,
                         int pos,
                         int len)
Creates a new MinimalHTMLWriter.

Parameters:
w - Writer
doc - StyledDocument
pos - The location in the document to fetch the content.
len - The amount to write out.
Method Detail

write

public void write()
           throws IOException,
                  BadLocationException
Generates HTML output from a StyledDocument.

Specified by:
write in class AbstractWriter
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

writeAttributes

protected void writeAttributes(AttributeSet attr)
                        throws IOException
Writes out all the attributes for the following types: StyleConstants.ParagraphConstants, StyleConstants.CharacterConstants, StyleConstants.FontConstants, StyleConstants.ColorConstants. The attribute name and value are separated by a colon. Each pair is separated by a semicolon.

Overrides:
writeAttributes in class AbstractWriter
Parameters:
attr - an AttributeSet.
Throws:
IOException - on any I/O error

text

protected void text(Element elem)
             throws IOException,
                    BadLocationException
Writes out text.

Overrides:
text in class AbstractWriter
Parameters:
elem - an Element.
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

writeStartTag

protected void writeStartTag(String tag)
                      throws IOException
Writes out a start tag appropriately indented. Also increments the indent level.

Throws:
IOException - on any I/O error

writeEndTag

protected void writeEndTag(String endTag)
                    throws IOException
Writes out an end tag appropriately indented. Also decrements the indent level.

Throws:
IOException - on any I/O error

writeHeader

protected void writeHeader()
                    throws IOException
Writes out the <head> and <style> tags, and then invokes writeStyles() to write out all the named styles as the content of the <style> tag. The content is surrounded by valid HTML comment markers to ensure that the document is viewable in applications/browsers that do not support the tag.

Throws:
IOException - on any I/O error

writeStyles

protected void writeStyles()
                    throws IOException
Writes out all the named styles as the content of the <style> tag.

Throws:
IOException - on any I/O error

writeBody

protected void writeBody()
                  throws IOException,
                         BadLocationException
Iterates over the elements in the document and processes elements based on whether they are branch elements or leaf elements. This method specially handles leaf elements that are text.

Throws:
IOException - on any I/O error
BadLocationException

writeEndParagraph

protected void writeEndParagraph()
                          throws IOException
Emits an end tag for a <p> tag. Before writing out the tag, this method ensures that all other tags that have been opened are appropriately closed off.

Throws:
IOException - on any I/O error

writeStartParagraph

protected void writeStartParagraph(Element elem)
                            throws IOException
Emits the start tag for a paragraph. If the paragraph has a named style associated with it, then this method also generates a class attribute for the <p> tag and sets its value to be the name of the style.

Throws:
IOException - on any I/O error

writeLeaf

protected void writeLeaf(Element elem)
                  throws IOException
Responsible for writing out other non-text leaf elements.

Throws:
IOException - on any I/O error

writeImage

protected void writeImage(Element elem)
                   throws IOException
Responsible for handling Icon Elements; deliberately unimplemented. How to implement this method is an issue of policy. For example, if you're generating an <img> tag, how should you represent the src attribute (the location of the image)? In certain cases it could be a URL, in others it could be read from a stream.

Parameters:
elem - element of type StyleConstants.IconElementName
Throws:
IOException

writeComponent

protected void writeComponent(Element elem)
                       throws IOException
Responsible for handling Component Elements; deliberately unimplemented. How this method is implemented is a matter of policy.

Throws:
IOException

isText

protected boolean isText(Element elem)
Returns true if the element is a text element.

writeContent

protected void writeContent(Element elem,
                            boolean needsIndenting)
                     throws IOException,
                            BadLocationException
Writes out the attribute set in an HTML-compliant manner.

Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

writeHTMLTags

protected void writeHTMLTags(AttributeSet attr)
                      throws IOException
Generates bold <b>, italic <i>, and <u> tags for the text based on its attribute settings.

Throws:
IOException - on any I/O error

writeNonHTMLAttributes

protected void writeNonHTMLAttributes(AttributeSet attr)
                               throws IOException
Writes out the remaining character-level attributes (attributes other than bold, italic, and underline) in an HTML-compliant way. Given that attributes such as font family and font size have no direct mapping to HTML tags, a <span> tag is generated and its style attribute is set to contain the list of remaining attributes just like inline styles.

Throws:
IOException - on any I/O error

inFontTag

protected boolean inFontTag()
Returns true if we are currently in a <font> tag.

endFontTag

protected void endFontTag()
                   throws IOException
This is no longer used, instead <span> will be written out.

Writes out an end tag for the <font> tag.

Throws:
IOException - on any I/O error

startFontTag

protected void startFontTag(String style)
                     throws IOException
This is no longer used, instead <span> will be written out.

Writes out a start tag for the <font> tag. Because font tags cannot be nested, this method closes out any enclosing font tag before writing out a new start tag.

Throws:
IOException - on any I/O error
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class ObjectView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.ComponentView
            extended by  javax.swing.text.html.ObjectView
All Implemented Interfaces:
SwingConstants
public class ObjectView
extends ComponentView

Component decorator that implements the view interface for <object> elements.

This view will try to load the class specified by the classid attribute. If possible, the Classloader used to load the associated Document is used. This would typically be the same as the ClassLoader used to load the EditorKit. If the document's ClassLoader is null, Class.forName is used.

If the class can successfully be loaded, an attempt will be made to create an instance of it by calling Class.newInstance. An attempt will be made to narrow the instance to type java.awt.Component to display the object.

This view can also manage a set of parameters with limitations. The parameters to the <object> element are expected to be present on the associated elements attribute set as simple strings. Each bean property will be queried as a key on the AttributeSet, with the expectation that a non-null value (of type String) will be present if there was a parameter specification for the property. Reflection is used to set the parameter. Currently, this is limited to a very simple single parameter of type String.

A simple example HTML invocation is:

      <object classid="javax.swing.JLabel">
      <param name="text" value="sample text">
      </object>

Field Summary
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
ObjectView(Element elem)
Creates a new ObjectView object.
Method Summary
protected  Component createComponent()
Create the component.
Methods inherited from class javax.swing.text.ComponentView
getAlignment, getComponent, getMaximumSpan, getMinimumSpan, getPreferredSpan, modelToView, paint, setParent, viewToModel
Methods inherited from class javax.swing.text.View
append, breakView, changedUpdate, createFragment, forwardUpdate, forwardUpdateToView, getAttributes, getBreakWeight, getChildAllocation, getContainer, getDocument, getElement, getEndOffset, getGraphics, getNextVisualPositionFrom, getParent, getResizeWeight, getStartOffset, getToolTipText, getView, getViewCount, getViewFactory, getViewIndex, getViewIndex, insert, insertUpdate, isVisible, modelToView, modelToView, preferenceChanged, remove, removeAll, removeUpdate, replace, setSize, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ObjectView

public ObjectView(Element elem)
Creates a new ObjectView object.

Parameters:
elem - the element to decorate
Method Detail

createComponent

protected Component createComponent()
Create the component. The classid is used as a specification of the classname, which we try to load.

Overrides:
createComponent in class ComponentView
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Option

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class Option

java.lang.Object
    extended by  javax.swing.text.html.Option
All Implemented Interfaces:
Serializable
public class Option
extends Object
implements Serializable

Value for the ListModel used to represent <option> elements. This is the object installed as items of the DefaultComboBoxModel used to represent the <select> element.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
Option(AttributeSet attr)
Creates a new Option object.
Method Summary
AttributeSet | getAttributes() Fetch the attributes associated with this option.
String | getLabel() Fetch the label associated with the option.
String | getValue() Convenience method to return the string associated with the value attribute.
boolean | isSelected() Fetches the selection state associated with this option.
void | setLabel(String label) Sets the label to be used for the option.
protected void | setSelection(boolean state) Sets the selected state.
String | toString() String representation is the label.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Option

public Option(AttributeSet attr)
Creates a new Option object.

Parameters:
attr - the attributes associated with the option element. The attributes are copied to ensure they won't change.
Method Detail

setLabel

public void setLabel(String label)
Sets the label to be used for the option.

getLabel

public String getLabel()
Fetch the label associated with the option.

getAttributes

public AttributeSet getAttributes()
Fetch the attributes associated with this option.

toString

public String toString()
String representation is the label.

Overrides:
toString in class Object
Returns:
a string representation of the object.

setSelection

protected void setSelection(boolean state)
Sets the selected state.

isSelected

public boolean isSelected()
Fetches the selection state associated with this option.

getValue

public String getValue()
Convenience method to return the string associated with the value attribute. If the value has not been specified, the label will be returned.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ParagraphView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class ParagraphView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.CompositeView
            extended by  javax.swing.text.BoxView
                extended by  javax.swing.text.FlowView
                    extended by  javax.swing.text.ParagraphView
                        extended by  javax.swing.text.html.ParagraphView
All Implemented Interfaces:
SwingConstants, TabExpander
public class ParagraphView
extends ParagraphView

Displays the a paragraph, and uses css attributes for its configuration.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.text.FlowView
FlowView.FlowStrategy
Field Summary
Fields inherited from class javax.swing.text.ParagraphView
firstLineIndent
Fields inherited from class javax.swing.text.FlowView
layoutPool, layoutSpan, strategy
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
ParagraphView(Element elem)
Constructs a ParagraphView for the given element.
Method Summary
protected SizeRequirements | calculateMinorAxisRequirements(int axis, SizeRequirements r) Calculate the needs for the paragraph along the minor axis.
AttributeSet | getAttributes() Fetches the attributes to use when rendering.
float | getMaximumSpan(int axis) Determines the maximum span for this view along an axis.
float | getMinimumSpan(int axis) Determines the minimum span for this view along an axis.
float | getPreferredSpan(int axis) Determines the preferred span for this view.
protected StyleSheet | getStyleSheet()
boolean | isVisible() Indicates whether or not this view should be displayed.
void | paint(Graphics g, Shape a) Renders using the given rendering surface and area on that surface.
void | setParent(View parent) Establishes the parent view for this view.
protected void | setPropertiesFromAttributes() Sets up the paragraph from css attributes instead of the values found in StyleConstants (i.e.
Methods inherited from class javax.swing.text.ParagraphView
adjustRow, breakView, changedUpdate, createRow, findOffsetToCharactersInString, flipEastAndWestAtEnds, getAlignment, getBreakWeight, getClosestPositionTo, getFlowSpan, getFlowStart, getLayoutView, getLayoutViewCount, getNextNorthSouthVisualPositionFrom, getPartialSize, getTabBase, getTabSet, nextTabStop, setFirstLineIndent, setJustification, setLineSpacing
Methods inherited from class javax.swing.text.FlowView
getFlowAxis, getViewIndexAtPosition, insertUpdate, layout, loadChildren, removeUpdate
Methods inherited from class javax.swing.text.BoxView
baselineLayout, baselineRequirements, calculateMajorAxisRequirements, childAllocation, forwardUpdate, getAxis, getChildAllocation, getHeight, getOffset, getResizeWeight, getSpan, getViewAtPoint, getWidth, isAfter, isAllocationValid, isBefore, isLayoutValid, layoutChanged, layoutMajorAxis, layoutMinorAxis, modelToView, paintChild, preferenceChanged, replace, setAxis, setSize, viewToModel
Methods inherited from class javax.swing.text.CompositeView
getBottomInset, getInsideAllocation, getLeftInset, getNextEastWestVisualPositionFrom, getNextVisualPositionFrom, getRightInset, getTopInset, getView, getViewAtPosition, getViewCount, getViewIndex, modelToView, setInsets, setParagraphInsets
Methods inherited from class javax.swing.text.View
append, breakView, createFragment, forwardUpdateToView, getBreakWeight, getContainer, getDocument, getElement, getEndOffset, getGraphics, getParent, getStartOffset, getToolTipText, getViewFactory, getViewIndex, insert, modelToView, remove, removeAll, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ParagraphView

public ParagraphView(Element elem)
Constructs a ParagraphView for the given element.

Parameters:
elem - the element that this view is responsible for
Method Detail

setParent

public void setParent(View parent)
Establishes the parent view for this view. This is guaranteed to be called before any other methods if the parent view is functioning properly.

This is implemented to forward to the superclass as well as call the setPropertiesFromAttributes method to set the paragraph properties from the css attributes. The call is made at this time to ensure the ability to resolve upward through the parents view attributes.

Overrides:
setParent in class FlowView
Parameters:
parent - the new parent, or null if the view is being removed from a parent it was previously added to

getAttributes

public AttributeSet getAttributes()
Fetches the attributes to use when rendering. This is implemented to multiplex the attributes specified in the model with a StyleSheet.

Overrides:
getAttributes in class View

setPropertiesFromAttributes

protected void setPropertiesFromAttributes()
Sets up the paragraph from css attributes instead of the values found in StyleConstants (i.e. which are used by the superclass). Since

Overrides:
setPropertiesFromAttributes in class ParagraphView

getStyleSheet

protected StyleSheet getStyleSheet()

calculateMinorAxisRequirements

protected SizeRequirements calculateMinorAxisRequirements(int axis,
                                                          SizeRequirements r)
Calculate the needs for the paragraph along the minor axis. This implemented to use the requirements of the superclass, modified slightly to set a minimum span allowed. Typical html rendering doesn't let the view size shrink smaller than the length of the longest word.

Overrides:
calculateMinorAxisRequirements in class FlowView
Parameters:
axis - the axis being studied
r - the SizeRequirements object; if null one will be created
Returns:
the newly initialized SizeRequirements object
See Also:
SizeRequirements

isVisible

public boolean isVisible()
Indicates whether or not this view should be displayed. If none of the children wish to be displayed and the only visible child is the break that ends the paragraph, the paragraph will not be considered visible. Otherwise, it will be considered visible and return true.

Overrides:
isVisible in class View
Returns:
true if the paragraph should be displayed

paint

public void paint(Graphics g,
                  Shape a)
Renders using the given rendering surface and area on that surface. This is implemented to delgate to the superclass after stashing the base coordinate for tab calculations.

Overrides:
paint in class ParagraphView
Parameters:
g - the rendering surface to use
a - the allocated region to render into
See Also:
View.paint(java.awt.Graphics, java.awt.Shape)

getPreferredSpan

public float getPreferredSpan(int axis)
Determines the preferred span for this view. Returns 0 if the view is not visible, otherwise it calls the superclass method to get the preferred span. axis.

Overrides:
getPreferredSpan in class BoxView
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into; typically the view is told to render into the span that is returned, although there is no guarantee; the parent may choose to resize or break the view
See Also:
BoxView.getPreferredSpan(int)

getMinimumSpan

public float getMinimumSpan(int axis)
Determines the minimum span for this view along an axis. Returns 0 if the view is not visible, otherwise it calls the superclass method to get the minimum span.

Overrides:
getMinimumSpan in class BoxView
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the minimum span the view can be rendered into
See Also:
BoxView.getMinimumSpan(int)

getMaximumSpan

public float getMaximumSpan(int axis)
Determines the maximum span for this view along an axis. Returns 0 if the view is not visible, otherwise it calls the superclass method ot get the maximum span.

Overrides:
getMaximumSpan in class BoxView
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the maximum span the view can be rendered into
See Also:
BoxView.getMaximumSpan(int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


parser

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.swing.text.html.parser

Provides the default HTML parser, along with support classes.

See:
Description

Interface Summary
DTDConstants SGML constants used in a DTD.

Class Summary
AttributeList | This class defines the attributes of an SGML element as described in a DTD using the ATTLIST construct.
ContentModel | A representation of a content model.
DocumentParser | A Parser for HTML Documents (actually, you can specify a DTD, but you should really only use this class with the html dtd in swing).
DTD | The representation of an SGML DTD.
Element | An element as described in a DTD using the ELEMENT construct.
Entity | An entity is described in a DTD using the ENTITY construct.
Parser | A simple DTD-driven HTML parser.
ParserDelegator | Responsible for starting up a new DocumentParser each time its parse method is invoked.
TagElement | A generic HTML TagElement class.

Package javax.swing.text.html.parser Description

Provides the default HTML parser, along with support classes. As the stream is parsed, the parser notifies a delegate, which must implement the HTMLEditorKit.ParserCallback interface.

Note: Most of the Swing API is not thread safe. For details, see Threads and Swing, a section in The Java Tutorial.

Since:
1.2
See Also:
HTMLEditorKit.ParserCallback
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.swing.text.html.parser Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.swing.text.html.parser

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.swing.text.html.parser.AttributeList (implements javax.swing.text.html.parser.DTDConstants, java.io.Serializable)
    • javax.swing.text.html.parser.ContentModel (implements java.io.Serializable)
    • javax.swing.text.html.parser.DTD (implements javax.swing.text.html.parser.DTDConstants)
    • javax.swing.text.html.parser.Element (implements javax.swing.text.html.parser.DTDConstants, java.io.Serializable)
    • javax.swing.text.html.parser.Entity (implements javax.swing.text.html.parser.DTDConstants)
    • javax.swing.text.html.HTMLEditorKit.Parser
      • javax.swing.text.html.parser.ParserDelegator (implements java.io.Serializable)
    • javax.swing.text.html.parser.Parser (implements javax.swing.text.html.parser.DTDConstants)
      • javax.swing.text.html.parser.DocumentParser
    • javax.swing.text.html.parser.TagElement

Interface Hierarchy

  • javax.swing.text.html.parser.DTDConstants
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.swing.text.html.parser

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.swing.text.html.parser

Packages that use javax.swing.text.html.parser
javax.swing.text.html.parser Provides the default HTML parser, along with support classes.

Classes in javax.swing.text.html.parser used by javax.swing.text.html.parser
AttributeList
This class defines the attributes of an SGML element as described in a DTD using the ATTLIST construct.
ContentModel
A representation of a content model.
DTD
The representation of an SGML DTD.
DTDConstants
SGML constants used in a DTD.
Element
An element as described in a DTD using the ELEMENT construct.
Entity
An entity is described in a DTD using the ENTITY construct.
Parser
A simple DTD-driven HTML parser.
TagElement
A generic HTML TagElement class.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AttributeList

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html.parser
Class AttributeList

java.lang.Object
    extended by  javax.swing.text.html.parser.AttributeList
All Implemented Interfaces:
Serializable, DTDConstants
public final class AttributeList
extends Object
implements DTDConstants, Serializable

This class defines the attributes of an SGML element as described in a DTD using the ATTLIST construct. An AttributeList can be obtained from the Element class using the getAttributes() method.

It is actually an element in a linked list. Use the getNext() method repeatedly to enumerate all the attributes of an element.

See Also:
Element

Field Summary
int | modifier
String | name
AttributeList | next
int | type
String | value
Vector<?> | values
Fields inherited from interface javax.swing.text.html.parser.DTDConstants
ANY, CDATA, CONREF, CURRENT, DEFAULT, EMPTY, ENDTAG, ENTITIES, ENTITY, FIXED, GENERAL, ID, IDREF, IDREFS, IMPLIED, MD, MODEL, MS, NAME, NAMES, NMTOKEN, NMTOKENS, NOTATION, NUMBER, NUMBERS, NUTOKEN, NUTOKENS, PARAMETER, PI, PUBLIC, RCDATA, REQUIRED, SDATA, STARTTAG, SYSTEM
Constructor Summary
AttributeList(String name)
Create an attribute list element.
AttributeList(String name, int type, int modifier, String value, Vector<?> values, AttributeList next)
Create an attribute list element.
Method Summary
int | getModifier()
String | getName()
AttributeList | getNext()
int | getType()
String | getValue()
Enumeration<?> | getValues()
static int | name2type(String nm)
String | toString() Returns a string representation of the object.
static String | type2name(int tp)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

name

public String name

type

public int type

values

public Vector<?> values

modifier

public int modifier

value

public String value

next

public AttributeList next
Constructor Detail

AttributeList

public AttributeList(String name)
Create an attribute list element.

AttributeList

public AttributeList(String name,
                     int type,
                     int modifier,
                     String value,
                     Vector<?> values,
                     AttributeList next)
Create an attribute list element.

Method Detail

getName

public String getName()
Returns:
attribute name

getType

public int getType()
Returns:
attribute type
See Also:
DTDConstants

getModifier

public int getModifier()
Returns:
attribute modifier
See Also:
DTDConstants

getValues

public Enumeration<?> getValues()
Returns:
possible attribute values

getValue

public String getValue()
Returns:
default attribute value

getNext

public AttributeList getNext()
Returns:
the next attribute in the list

toString

public String toString()
Description copied from class: Object
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())

Overrides:
toString in class Object
Returns:
string representation

name2type

public static int name2type(String nm)

type2name

public static String type2name(int tp)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.swing.text.html.parser.AttributeList

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.parser.AttributeList

Packages that use AttributeList
javax.swing.text.html.parser Provides the default HTML parser, along with support classes.

Uses of AttributeList in javax.swing.text.html.parser

Fields in javax.swing.text.html.parser declared as AttributeList
AttributeList | Element.atts
AttributeList | AttributeList.next

Methods in javax.swing.text.html.parser that return AttributeList
protected AttributeList | DTD.defAttributeList(String name, int type, int modifier, String value, String values, AttributeList atts) Creates and returns an AttributeList.
AttributeList | Element.getAttribute(String name) Get an attribute by name.
AttributeList | Element.getAttributeByValue(String name) Get an attribute by value.
AttributeList | Element.getAttributes() Get the attributes.
AttributeList | AttributeList.getNext()

Methods in javax.swing.text.html.parser with parameters of type AttributeList
protected AttributeList | DTD.defAttributeList(String name, int type, int modifier, String value, String values, AttributeList atts) Creates and returns an AttributeList.
protected Element | DTD.defElement(String name, int type, boolean omitStart, boolean omitEnd, ContentModel content, String[] exclusions, String[] inclusions, AttributeList atts) Creates and returns an Element.
void | DTD.defineAttributes(String name, AttributeList atts) Defines attributes for an Element.
Element | DTD.defineElement(String name, int type, boolean omitStart, boolean omitEnd, ContentModel content, BitSet exclusions, BitSet inclusions, AttributeList atts) Returns the Element which matches the specified parameters.

Constructors in javax.swing.text.html.parser with parameters of type AttributeList
AttributeList(String name, int type, int modifier, String value, Vector<?> values, AttributeList next)
Create an attribute list element.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.parser.ContentModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.parser.ContentModel

Packages that use ContentModel
javax.swing.text.html.parser Provides the default HTML parser, along with support classes.

Uses of ContentModel in javax.swing.text.html.parser

Fields in javax.swing.text.html.parser declared as ContentModel
ContentModel | Element.content
ContentModel | ContentModel.next The next content model (in a ',', '|' or '&' expression).

Methods in javax.swing.text.html.parser that return ContentModel
protected ContentModel | DTD.defContentModel(int type, Object obj, ContentModel next) Creates and returns a new content model.
ContentModel | Element.getContent() Get content model

Methods in javax.swing.text.html.parser with parameters of type ContentModel
protected ContentModel | DTD.defContentModel(int type, Object obj, ContentModel next) Creates and returns a new content model.
protected Element | DTD.defElement(String name, int type, boolean omitStart, boolean omitEnd, ContentModel content, String[] exclusions, String[] inclusions, AttributeList atts) Creates and returns an Element.
Element | DTD.defineElement(String name, int type, boolean omitStart, boolean omitEnd, ContentModel content, BitSet exclusions, BitSet inclusions, AttributeList atts) Returns the Element which matches the specified parameters.

Constructors in javax.swing.text.html.parser with parameters of type ContentModel
ContentModel(int type, ContentModel content)
Create a content model of a particular type.
ContentModel(int type, Object content, ContentModel next)
Create a content model of a particular type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.parser.DocumentParser

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.parser.DocumentParser

No usage of javax.swing.text.html.parser.DocumentParser

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.parser.DTD

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.parser.DTD

Packages that use DTD
javax.swing.text.html.parser Provides the default HTML parser, along with support classes.

Uses of DTD in javax.swing.text.html.parser

Fields in javax.swing.text.html.parser declared as DTD
protected  DTD Parser.dtd

Methods in javax.swing.text.html.parser that return DTD
protected static DTD | ParserDelegator.createDTD(DTD dtd, String name)
static DTD | DTD.getDTD(String name) Returns a DTD with the specified name.

Methods in javax.swing.text.html.parser with parameters of type DTD
protected static DTD | ParserDelegator.createDTD(DTD dtd, String name)
static void | DTD.putDTDHash(String name, DTD dtd)

Constructors in javax.swing.text.html.parser with parameters of type DTD
DocumentParser(DTD dtd)
Parser(DTD dtd)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.parser.Element

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.parser.Element

Packages that use Element
javax.swing.text.html.parser Provides the default HTML parser, along with support classes.

Uses of Element in javax.swing.text.html.parser

Fields in javax.swing.text.html.parser declared as Element
Element | DTD.applet
Element | DTD.base
Element | DTD.body
Element | DTD.head
Element | DTD.html
Element | DTD.isindex
Element | DTD.meta
Element | DTD.p
Element | DTD.param
Element | DTD.pcdata
Element | DTD.title

Fields in javax.swing.text.html.parser with type parameters of type Element
Hashtable<String,Element> | DTD.elementHash
Vector<Element> | DTD.elements

Methods in javax.swing.text.html.parser that return Element
protected Element | DTD.defElement(String name, int type, boolean omitStart, boolean omitEnd, ContentModel content, String[] exclusions, String[] inclusions, AttributeList atts) Creates and returns an Element.
Element | DTD.defineElement(String name, int type, boolean omitStart, boolean omitEnd, ContentModel content, BitSet exclusions, BitSet inclusions, AttributeList atts) Returns the Element which matches the specified parameters.
Element | ContentModel.first() Return the element that must be next.
Element | TagElement.getElement()
Element | DTD.getElement(int index) Gets an element by index.
Element | DTD.getElement(String name) Gets an element by name.

Methods in javax.swing.text.html.parser with parameters of type Element
protected TagElement | Parser.makeTag(Element elem)
protected TagElement | Parser.makeTag(Element elem, boolean fictional) Makes a TagElement.
protected void | Parser.markFirstTime(Element elem) Marks the first time a tag has been seen in a document

Method parameters in javax.swing.text.html.parser with type arguments of type Element
 void ContentModel.getElements(Vector<Element> elemVec)
Update elemVec with the list of elements that are part of the this contentModel.

Constructors in javax.swing.text.html.parser with parameters of type Element
ContentModel(Element content)
Create a content model for an element.
TagElement(Element elem)
TagElement(Element elem, boolean fictional)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.parser.Entity

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.parser.Entity

Packages that use Entity
javax.swing.text.html.parser Provides the default HTML parser, along with support classes.

Uses of Entity in javax.swing.text.html.parser

Fields in javax.swing.text.html.parser with type parameters of type Entity
 Hashtable<Object,Entity> DTD.entityHash

Methods in javax.swing.text.html.parser that return Entity
Entity | DTD.defEntity(String name, int type, int ch) Creates and returns a character Entity.
protected Entity | DTD.defEntity(String name, int type, String str) Creates and returns an Entity.
Entity | DTD.defineEntity(String name, int type, char[] data) Defines an entity.
Entity | DTD.getEntity(int ch) Gets a character entity.
Entity | DTD.getEntity(String name) Gets an entity by name.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.parser.Parser

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.parser.Parser

Packages that use Parser
javax.swing.text.html.parser Provides the default HTML parser, along with support classes.

Uses of Parser in javax.swing.text.html.parser

Subclasses of Parser in javax.swing.text.html.parser
 class DocumentParser
A Parser for HTML Documents (actually, you can specify a DTD, but you should really only use this class with the html dtd in swing).

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.parser.ParserDelegator

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.parser.ParserDelegator

No usage of javax.swing.text.html.parser.ParserDelegator

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.html.parser.TagElement

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.html.parser.TagElement

Packages that use TagElement
javax.swing.text.html.parser Provides the default HTML parser, along with support classes.

Uses of TagElement in javax.swing.text.html.parser

Methods in javax.swing.text.html.parser that return TagElement
protected TagElement | Parser.makeTag(Element elem)
protected TagElement | Parser.makeTag(Element elem, boolean fictional) Makes a TagElement.

Methods in javax.swing.text.html.parser with parameters of type TagElement
protected void | DocumentParser.handleEmptyTag(TagElement tag) Handle Empty Tag.
protected void | Parser.handleEmptyTag(TagElement tag) Called when an empty tag is encountered.
protected void | DocumentParser.handleEndTag(TagElement tag) Handle End Tag.
protected void | Parser.handleEndTag(TagElement tag) Called when an end tag is encountered.
protected void | DocumentParser.handleStartTag(TagElement tag) Handle Start Tag.
protected void | Parser.handleStartTag(TagElement tag) Called when a start tag is encountered.
protected void | Parser.startTag(TagElement tag) Handle a start tag.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.text.html.parser.DTDConstants

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.text.html.parser.DTDConstants

Packages that use DTDConstants
javax.swing.text.html.parser Provides the default HTML parser, along with support classes.

Uses of DTDConstants in javax.swing.text.html.parser

Classes in javax.swing.text.html.parser that implement DTDConstants
class | AttributeList This class defines the attributes of an SGML element as described in a DTD using the ATTLIST construct.
class | DocumentParser A Parser for HTML Documents (actually, you can specify a DTD, but you should really only use this class with the html dtd in swing).
class | DTD The representation of an SGML DTD.
class | Element An element as described in a DTD using the ELEMENT construct.
class | Entity An entity is described in a DTD using the ENTITY construct.
class | Parser A simple DTD-driven HTML parser.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ContentModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html.parser
Class ContentModel

java.lang.Object
    extended by  javax.swing.text.html.parser.ContentModel
All Implemented Interfaces:
Serializable
public final class ContentModel
extends Object
implements Serializable

A representation of a content model. A content model is basically a restricted BNF expression. It is restricted in the sense that it must be deterministic. This means that you don't have to represent it as a finite state automata.

See Annex H on page 556 of the SGML handbook for more information.

Field Summary
Object | content The content.
ContentModel | next The next content model (in a ',', '|' or '&' expression).
int | type Type.
Constructor Summary
ContentModel()
ContentModel(Element content)
Create a content model for an element.
ContentModel(int type, ContentModel content)
Create a content model of a particular type.
ContentModel(int type, Object content, ContentModel next)
Create a content model of a particular type.
Method Summary
boolean | empty() Return true if the content model could match an empty input stream.
Element | first() Return the element that must be next.
boolean | first(Object token) Return true if the token could potentially be the first token in the input stream.
void | getElements(Vector<Element> elemVec) Update elemVec with the list of elements that are part of the this contentModel.
String | toString() Convert to a string.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

type

public int type
Type. Either '*', '?', '+', ',', '|', '&'.

content

public Object content
The content. Either an Element or a ContentModel.

next

public ContentModel next
The next content model (in a ',', '|' or '&' expression).

Constructor Detail

ContentModel

public ContentModel()

ContentModel

public ContentModel(Element content)
Create a content model for an element.

ContentModel

public ContentModel(int type,
                    ContentModel content)
Create a content model of a particular type.

ContentModel

public ContentModel(int type,
                    Object content,
                    ContentModel next)
Create a content model of a particular type.

Method Detail

empty

public boolean empty()
Return true if the content model could match an empty input stream.

getElements

public void getElements(Vector<Element> elemVec)
Update elemVec with the list of elements that are part of the this contentModel.

first

public boolean first(Object token)
Return true if the token could potentially be the first token in the input stream.

first

public Element first()
Return the element that must be next.

toString

public String toString()
Convert to a string.

Overrides:
toString in class Object
Returns:
a string representation of the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocumentParser

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html.parser
Class DocumentParser

java.lang.Object
    extended by  javax.swing.text.html.parser.Parser
        extended by  javax.swing.text.html.parser.DocumentParser
All Implemented Interfaces:
DTDConstants
public class DocumentParser
extends Parser

A Parser for HTML Documents (actually, you can specify a DTD, but you should really only use this class with the html dtd in swing). Reads an InputStream of HTML and invokes the appropriate methods in the ParserCallback class. This is the default parser used by HTMLEditorKit to parse HTML url's.

This will message the callback for all valid tags, as well as tags that are implied but not explicitly specified. For example, the html string (<p>blah) only has a p tag defined. The callback will see the following methods:

  1. handleStartTag(html, ...)
  2. handleStartTag(head, ...)
  3. handleEndTag(head)
  4. handleStartTag(body, ...)
  5. handleStartTag(p, ...)
  6. handleText(...)
  7. handleEndTag(p)
  8. handleEndTag(body)
  9. handleEndTag(html)
The items in italic are implied, that is, although they were not explicitly specified, to be correct html they should have been present (head isn't necessary, but it is still generated). For tags that are implied, the AttributeSet argument will have a value of Boolean.TRUE for the key HTMLEditorKit.ParserCallback.IMPLIED.

HTML.Attributes defines a type safe enumeration of html attributes. If an attribute key of a tag is defined in HTML.Attribute, the HTML.Attribute will be used as the key, otherwise a String will be used. For example <p foo=bar class=neat> has two attributes. foo is not defined in HTML.Attribute, where as class is, therefore the AttributeSet will have two values in it, HTML.Attribute.CLASS with a String value of 'neat' and the String key 'foo' with a String value of 'bar'.

The position argument will indicate the start of the tag, comment or text. Similiar to arrays, the first character in the stream has a position of 0. For tags that are implied the position will indicate the location of the next encountered tag. In the first example, the implied start body and html tags will have the same position as the p tag, and the implied end p, html and body tags will all have the same position.

As html skips whitespace the position for text will be the position of the first valid character, eg in the string '\n\n\nblah' the text 'blah' will have a position of 3, the newlines are skipped.

For attributes that do not have a value, eg in the html string <foo blah> the attribute blah does not have a value, there are two possible values that will be placed in the AttributeSet's value:

  • If the DTD does not contain an definition for the element, or the definition does not have an explicit value then the value in the AttributeSet will be HTML.NULL_ATTRIBUTE_VALUE.
  • If the DTD contains an explicit value, as in: <!ATTLIST OPTION selected (selected) #IMPLIED> this value from the dtd (in this case selected) will be used.

Once the stream has been parsed, the callback is notified of the most likely end of line string. The end of line string will be one of \n, \r or \r\n, which ever is encountered the most in parsing the stream.

Field Summary
Fields inherited from class javax.swing.text.html.parser.Parser
dtd, strict
Fields inherited from interface javax.swing.text.html.parser.DTDConstants
ANY, CDATA, CONREF, CURRENT, DEFAULT, EMPTY, ENDTAG, ENTITIES, ENTITY, FIXED, GENERAL, ID, IDREF, IDREFS, IMPLIED, MD, MODEL, MS, NAME, NAMES, NMTOKEN, NMTOKENS, NOTATION, NUMBER, NUMBERS, NUTOKEN, NUTOKENS, PARAMETER, PI, PUBLIC, RCDATA, REQUIRED, SDATA, STARTTAG, SYSTEM
Constructor Summary
DocumentParser(DTD dtd)
Method Summary
protected void | handleComment(char[] text) Called when an HTML comment is encountered.
protected void | handleEmptyTag(TagElement tag) Handle Empty Tag.
protected void | handleEndTag(TagElement tag) Handle End Tag.
protected void | handleError(int ln, String errorMsg) An error has occurred.
protected void | handleStartTag(TagElement tag) Handle Start Tag.
protected void | handleText(char[] data) Handle Text.
void | parse(Reader in, HTMLEditorKit.ParserCallback callback, boolean ignoreCharSet)
Methods inherited from class javax.swing.text.html.parser.Parser
endTag, error, error, error, error, flushAttributes, getAttributes, getCurrentLine, getCurrentPos, handleEOFInComment, handleTitle, makeTag, makeTag, markFirstTime, parse, parseDTDMarkup, parseMarkupDeclarations, startTag
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DocumentParser

public DocumentParser(DTD dtd)
Method Detail

parse

public void parse(Reader in,
                  HTMLEditorKit.ParserCallback callback,
                  boolean ignoreCharSet)
           throws IOException
Throws:
IOException

handleStartTag

protected void handleStartTag(TagElement tag)
Handle Start Tag.

Overrides:
handleStartTag in class Parser

handleComment

protected void handleComment(char[] text)
Description copied from class: Parser
Called when an HTML comment is encountered.

Overrides:
handleComment in class Parser

handleEmptyTag

protected void handleEmptyTag(TagElement tag)
                       throws ChangedCharSetException
Handle Empty Tag.

Overrides:
handleEmptyTag in class Parser
Throws:
ChangedCharSetException

handleEndTag

protected void handleEndTag(TagElement tag)
Handle End Tag.

Overrides:
handleEndTag in class Parser

handleText

protected void handleText(char[] data)
Handle Text.

Overrides:
handleText in class Parser

handleError

protected void handleError(int ln,
                           String errorMsg)
Description copied from class: Parser
An error has occurred.

Overrides:
handleError in class Parser
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DTD

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html.parser
Class DTD

java.lang.Object
    extended by  javax.swing.text.html.parser.DTD
All Implemented Interfaces:
DTDConstants
public class DTD
extends Object
implements DTDConstants

The representation of an SGML DTD. DTD describes a document syntax and is used in parsing of HTML documents. It contains a list of elements and their attributes as well as a list of entities defined in the DTD.

See Also:
Element, AttributeList, ContentModel, Parser

Field Summary
Element | applet
Element | base
Element | body
Hashtable<String,Element> | elementHash
Vector<Element> | elements
Hashtable<Object,Entity> | entityHash
static int | FILE_VERSION
Element | head
Element | html
Element | isindex
Element | meta
String | name
Element | p
Element | param
Element | pcdata
Element | title
Fields inherited from interface javax.swing.text.html.parser.DTDConstants
ANY, CDATA, CONREF, CURRENT, DEFAULT, EMPTY, ENDTAG, ENTITIES, ENTITY, FIXED, GENERAL, ID, IDREF, IDREFS, IMPLIED, MD, MODEL, MS, NAME, NAMES, NMTOKEN, NMTOKENS, NOTATION, NUMBER, NUMBERS, NUTOKEN, NUTOKENS, PARAMETER, PI, PUBLIC, RCDATA, REQUIRED, SDATA, STARTTAG, SYSTEM
Constructor Summary
protected DTD(String name)
Creates a new DTD with the specified name.
Method Summary
protected AttributeList | defAttributeList(String name, int type, int modifier, String value, String values, AttributeList atts) Creates and returns an AttributeList.
protected ContentModel | defContentModel(int type, Object obj, ContentModel next) Creates and returns a new content model.
protected Element | defElement(String name, int type, boolean omitStart, boolean omitEnd, ContentModel content, String[] exclusions, String[] inclusions, AttributeList atts) Creates and returns an Element.
Entity | defEntity(String name, int type, int ch) Creates and returns a character Entity.
protected Entity | defEntity(String name, int type, String str) Creates and returns an Entity.
void | defineAttributes(String name, AttributeList atts) Defines attributes for an Element.
Element | defineElement(String name, int type, boolean omitStart, boolean omitEnd, ContentModel content, BitSet exclusions, BitSet inclusions, AttributeList atts) Returns the Element which matches the specified parameters.
Entity | defineEntity(String name, int type, char[] data) Defines an entity.
static DTD | getDTD(String name) Returns a DTD with the specified name.
Element | getElement(int index) Gets an element by index.
Element | getElement(String name) Gets an element by name.
Entity | getEntity(int ch) Gets a character entity.
Entity | getEntity(String name) Gets an entity by name.
String | getName() Gets the name of the DTD.
static void | putDTDHash(String name, DTD dtd)
void | read(DataInputStream in) Recreates a DTD from an archived format.
String | toString() Returns a string representation of this DTD.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

name

public String name

elements

public Vector<Element> elements

elementHash

public Hashtable<String,Element> elementHash

entityHash

public Hashtable<Object,Entity> entityHash

pcdata

public final Element pcdata

html

public final Element html

meta

public final Element meta

base

public final Element base

isindex

public final Element isindex

head

public final Element head

body

public final Element body

applet

public final Element applet

param

public final Element param

p

public final Element p

title

public final Element title

FILE_VERSION

public static final int FILE_VERSION
See Also:
Constant Field Values
Constructor Detail

DTD

protected DTD(String name)
Creates a new DTD with the specified name.

Parameters:
name - the name, as a String of the new DTD
Method Detail

getName

public String getName()
Gets the name of the DTD.

Returns:
the name of the DTD

getEntity

public Entity getEntity(String name)
Gets an entity by name.

Returns:
the Entity corresponding to the name String

getEntity

public Entity getEntity(int ch)
Gets a character entity.

Returns:
the Entity corresponding to the ch character

getElement

public Element getElement(String name)
Gets an element by name. A new element is created if the element doesn't exist.

Parameters:
name - the requested String
Returns:
the Element corresponding to name, which may be newly created

getElement

public Element getElement(int index)
Gets an element by index.

Parameters:
index - the requested index
Returns:
the Element corresponding to index

defineEntity

public Entity defineEntity(String name,
                           int type,
                           char[] data)
Defines an entity. If the Entity specified by name, type, and data exists, it is returned; otherwise a new Entity is created and is returned.

Parameters:
name - the name of the Entity as a String
type - the type of the Entity
data - the Entity's data
Returns:
the Entity requested or a new Entity if not found

defineElement

public Element defineElement(String name,
                             int type,
                             boolean omitStart,
                             boolean omitEnd,
                             ContentModel content,
                             BitSet exclusions,
                             BitSet inclusions,
                             AttributeList atts)
Returns the Element which matches the specified parameters. If one doesn't exist, a new one is created and returned.

Parameters:
name - the name of the Element
type - the type of the Element
omitStart - true if start should be omitted
omitEnd - true if end should be omitted
content - the ContentModel
atts - the AttributeList specifying the Element
Returns:
the Element specified

defineAttributes

public void defineAttributes(String name,
                             AttributeList atts)
Defines attributes for an Element.

Parameters:
name - the name of the Element
atts - the AttributeList specifying the Element

defEntity

public Entity defEntity(String name,
                        int type,
                        int ch)
Creates and returns a character Entity.

Parameters:
name - the entity's name
Returns:
the new character Entity

defEntity

protected Entity defEntity(String name,
                           int type,
                           String str)
Creates and returns an Entity.

Parameters:
name - the entity's name
Returns:
the new Entity

defElement

protected Element defElement(String name,
                             int type,
                             boolean omitStart,
                             boolean omitEnd,
                             ContentModel content,
                             String[] exclusions,
                             String[] inclusions,
                             AttributeList atts)
Creates and returns an Element.

Parameters:
name - the element's name
Returns:
the new Element

defAttributeList

protected AttributeList defAttributeList(String name,
                                         int type,
                                         int modifier,
                                         String value,
                                         String values,
                                         AttributeList atts)
Creates and returns an AttributeList.

Parameters:
name - the attribute list's name
Returns:
the new AttributeList

defContentModel

protected ContentModel defContentModel(int type,
                                       Object obj,
                                       ContentModel next)
Creates and returns a new content model.

Parameters:
type - the type of the new content model
Returns:
the new ContentModel

toString

public String toString()
Returns a string representation of this DTD.

Overrides:
toString in class Object
Returns:
the string representation of this DTD

putDTDHash

public static void putDTDHash(String name,
                              DTD dtd)

getDTD

public static DTD getDTD(String name)
                  throws IOException
Returns a DTD with the specified name. If a DTD with that name doesn't exist, one is created and returned. Any uppercase characters in the name are converted to lowercase.

Parameters:
name - the name of the DTD
Returns:
the DTD which corresponds to name
Throws:
IOException

read

public void read(DataInputStream in)
          throws IOException
Recreates a DTD from an archived format.

Parameters:
in - the DataInputStream to read from
Throws:
IOException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DTDConstants

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html.parser
Interface DTDConstants

All Known Implementing Classes:
AttributeList, DocumentParser, DTD, Element, Entity, Parser
public interface DTDConstants

SGML constants used in a DTD. The names of the constants correspond the the equivalent SGML constructs as described in "The SGML Handbook" by Charles F. Goldfarb.

See Also:
DTD, Element

Field Summary
static int | ANY
static int | CDATA
static int | CONREF
static int | CURRENT
static int | DEFAULT
static int | EMPTY
static int | ENDTAG
static int | ENTITIES
static int | ENTITY
static int | FIXED
static int | GENERAL
static int | ID
static int | IDREF
static int | IDREFS
static int | IMPLIED
static int | MD
static int | MODEL
static int | MS
static int | NAME
static int | NAMES
static int | NMTOKEN
static int | NMTOKENS
static int | NOTATION
static int | NUMBER
static int | NUMBERS
static int | NUTOKEN
static int | NUTOKENS
static int | PARAMETER
static int | PI
static int | PUBLIC
static int | RCDATA
static int | REQUIRED
static int | SDATA
static int | STARTTAG
static int | SYSTEM

Field Detail

CDATA

static final int CDATA
See Also:
Constant Field Values

ENTITY

static final int ENTITY
See Also:
Constant Field Values

ENTITIES

static final int ENTITIES
See Also:
Constant Field Values

ID

static final int ID
See Also:
Constant Field Values

IDREF

static final int IDREF
See Also:
Constant Field Values

IDREFS

static final int IDREFS
See Also:
Constant Field Values

NAME

static final int NAME
See Also:
Constant Field Values

NAMES

static final int NAMES
See Also:
Constant Field Values

NMTOKEN

static final int NMTOKEN
See Also:
Constant Field Values

NMTOKENS

static final int NMTOKENS
See Also:
Constant Field Values

NOTATION

static final int NOTATION
See Also:
Constant Field Values

NUMBER

static final int NUMBER
See Also:
Constant Field Values

NUMBERS

static final int NUMBERS
See Also:
Constant Field Values

NUTOKEN

static final int NUTOKEN
See Also:
Constant Field Values

NUTOKENS

static final int NUTOKENS
See Also:
Constant Field Values

RCDATA

static final int RCDATA
See Also:
Constant Field Values

EMPTY

static final int EMPTY
See Also:
Constant Field Values

MODEL

static final int MODEL
See Also:
Constant Field Values

ANY

static final int ANY
See Also:
Constant Field Values

FIXED

static final int FIXED
See Also:
Constant Field Values

REQUIRED

static final int REQUIRED
See Also:
Constant Field Values

CURRENT

static final int CURRENT
See Also:
Constant Field Values

CONREF

static final int CONREF
See Also:
Constant Field Values

IMPLIED

static final int IMPLIED
See Also:
Constant Field Values

PUBLIC

static final int PUBLIC
See Also:
Constant Field Values

SDATA

static final int SDATA
See Also:
Constant Field Values

PI

static final int PI
See Also:
Constant Field Values

STARTTAG

static final int STARTTAG
See Also:
Constant Field Values

ENDTAG

static final int ENDTAG
See Also:
Constant Field Values

MS

static final int MS
See Also:
Constant Field Values

MD

static final int MD
See Also:
Constant Field Values

SYSTEM

static final int SYSTEM
See Also:
Constant Field Values

GENERAL

static final int GENERAL
See Also:
Constant Field Values

DEFAULT

static final int DEFAULT
See Also:
Constant Field Values

PARAMETER

static final int PARAMETER
See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Element

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html.parser
Class Element

java.lang.Object
    extended by  javax.swing.text.html.parser.Element
All Implemented Interfaces:
Serializable, DTDConstants
public final class Element
extends Object
implements DTDConstants, Serializable

An element as described in a DTD using the ELEMENT construct. This is essentiall the description of a tag. It describes the type, content model, attributes, attribute types etc. It is used to correctly parse a document by the Parser.

See Also:
DTD, AttributeList

Field Summary
AttributeList | atts
ContentModel | content
Object | data A field to store user data.
BitSet | exclusions
BitSet | inclusions
int | index
String | name
boolean | oEnd
boolean | oStart
int | type
Fields inherited from interface javax.swing.text.html.parser.DTDConstants
ANY, CDATA, CONREF, CURRENT, DEFAULT, EMPTY, ENDTAG, ENTITIES, ENTITY, FIXED, GENERAL, ID, IDREF, IDREFS, IMPLIED, MD, MODEL, MS, NAME, NAMES, NMTOKEN, NMTOKENS, NOTATION, NUMBER, NUMBERS, NUTOKEN, NUTOKENS, PARAMETER, PI, PUBLIC, RCDATA, REQUIRED, SDATA, STARTTAG, SYSTEM
Method Summary
AttributeList | getAttribute(String name) Get an attribute by name.
AttributeList | getAttributeByValue(String name) Get an attribute by value.
AttributeList | getAttributes() Get the attributes.
ContentModel | getContent() Get content model
int | getIndex() Get index.
String | getName() Get the name of the element.
int | getType() Get type.
boolean | isEmpty() Check if empty
static int | name2type(String nm)
boolean | omitEnd() Return true if the end tag can be omitted.
boolean | omitStart() Return true if the start tag can be omitted.
String | toString() Convert to a string.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

index

public int index

name

public String name

oStart

public boolean oStart

oEnd

public boolean oEnd

inclusions

public BitSet inclusions

exclusions

public BitSet exclusions

type

public int type

content

public ContentModel content

atts

public AttributeList atts

data

public Object data
A field to store user data. Mostly used to store style sheets.

Method Detail

getName

public String getName()
Get the name of the element.

omitStart

public boolean omitStart()
Return true if the start tag can be omitted.

omitEnd

public boolean omitEnd()
Return true if the end tag can be omitted.

getType

public int getType()
Get type.

getContent

public ContentModel getContent()
Get content model

getAttributes

public AttributeList getAttributes()
Get the attributes.

getIndex

public int getIndex()
Get index.

isEmpty

public boolean isEmpty()
Check if empty

toString

public String toString()
Convert to a string.

Overrides:
toString in class Object
Returns:
a string representation of the object.

getAttribute

public AttributeList getAttribute(String name)
Get an attribute by name.

getAttributeByValue

public AttributeList getAttributeByValue(String name)
Get an attribute by value.

name2type

public static int name2type(String nm)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Entity

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html.parser
Class Entity

java.lang.Object
    extended by  javax.swing.text.html.parser.Entity
All Implemented Interfaces:
DTDConstants
public final class Entity
extends Object
implements DTDConstants

An entity is described in a DTD using the ENTITY construct. It defines the type and value of the the entity.

See Also:
DTD

Field Summary
char[] | data
String | name
int | type
Fields inherited from interface javax.swing.text.html.parser.DTDConstants
ANY, CDATA, CONREF, CURRENT, DEFAULT, EMPTY, ENDTAG, ENTITIES, ENTITY, FIXED, GENERAL, ID, IDREF, IDREFS, IMPLIED, MD, MODEL, MS, NAME, NAMES, NMTOKEN, NMTOKENS, NOTATION, NUMBER, NUMBERS, NUTOKEN, NUTOKENS, PARAMETER, PI, PUBLIC, RCDATA, REQUIRED, SDATA, STARTTAG, SYSTEM
Constructor Summary
Entity(String name, int type, char[] data)
Creates an entity.
Method Summary
char[] | getData() Returns the data.
String | getName() Gets the name of the entity.
String | getString() Returns the data as a String.
int | getType() Gets the type of the entity.
boolean | isGeneral() Returns true if it is a general entity.
boolean | isParameter() Returns true if it is a parameter entity.
static int | name2type(String nm) Converts nm string to the corresponding entity type.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

name

public String name

type

public int type

data

public char[] data
Constructor Detail

Entity

public Entity(String name,
              int type,
              char[] data)
Creates an entity.

Parameters:
name - the name of the entity
type - the type of the entity
data - the char array of data
Method Detail

getName

public String getName()
Gets the name of the entity.

Returns:
the name of the entity, as a String

getType

public int getType()
Gets the type of the entity.

Returns:
the type of the entity

isParameter

public boolean isParameter()
Returns true if it is a parameter entity.

Returns:
true if it is a parameter entity

isGeneral

public boolean isGeneral()
Returns true if it is a general entity.

Returns:
true if it is a general entity

getData

public char[] getData()
Returns the data.

Returns:
the data

getString

public String getString()
Returns the data as a String.

Returns:
the data as a String

name2type

public static int name2type(String nm)
Converts nm string to the corresponding entity type. If the string does not have a corresponding entity type, returns the type corresponding to "CDATA". Valid entity types are: "PUBLIC", "CDATA", "SDATA", "PI", "STARTTAG", "ENDTAG", "MS", "MD", "SYSTEM".

Parameters:
nm - the string to be converted
Returns:
the corresponding entity type, or the type corresponding to "CDATA", if none exists
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Parser

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html.parser
Class Parser

java.lang.Object
    extended by  javax.swing.text.html.parser.Parser
All Implemented Interfaces:
DTDConstants
Direct Known Subclasses:
DocumentParser
public class Parser
extends Object
implements DTDConstants

A simple DTD-driven HTML parser. The parser reads an HTML file from an InputStream and calls various methods (which should be overridden in a subclass) when tags and data are encountered.

Unfortunately there are many badly implemented HTML parsers out there, and as a result there are many badly formatted HTML files. This parser attempts to parse most HTML files. This means that the implementation sometimes deviates from the SGML specification in favor of HTML.

The parser treats \r and \r\n as \n. Newlines after starttags and before end tags are ignored just as specified in the SGML/HTML specification.

The html spec does not specify how spaces are to be coalesced very well. Specifically, the following scenarios are not discussed (note that a space should be used here, but I am using &nbsp to force the space to be displayed):

'<b>blah <i> <strike> foo' which can be treated as: '<b>blah <i><strike>foo'

as well as: '<p><a href="xx"> <em>Using</em></a></p>' which appears to be treated as: '<p><a href="xx"><em>Using</em></a></p>'

If strict is false, when a tag that breaks flow, (TagElement.breaksFlows) or trailing whitespace is encountered, all whitespace will be ignored until a non whitespace character is encountered. This appears to give behavior closer to the popular browsers.

See Also:
DTD, TagElement, SimpleAttributeSet

Field Summary
protected DTD | dtd
protected boolean | strict This flag determines whether or not the Parser will be strict in enforcing SGML compatibility.
Fields inherited from interface javax.swing.text.html.parser.DTDConstants
ANY, CDATA, CONREF, CURRENT, DEFAULT, EMPTY, ENDTAG, ENTITIES, ENTITY, FIXED, GENERAL, ID, IDREF, IDREFS, IMPLIED, MD, MODEL, MS, NAME, NAMES, NMTOKEN, NMTOKENS, NOTATION, NUMBER, NUMBERS, NUTOKEN, NUTOKENS, PARAMETER, PI, PUBLIC, RCDATA, REQUIRED, SDATA, STARTTAG, SYSTEM
Constructor Summary
Parser(DTD dtd)
Method Summary
protected void | endTag(boolean omitted) Handle an end tag.
protected void | error(String err)
protected void | error(String err, String arg1)
protected void | error(String err, String arg1, String arg2)
protected void | error(String err, String arg1, String arg2, String arg3) Invoke the error handler.
protected void | flushAttributes()
protected SimpleAttributeSet | getAttributes()
protected int | getCurrentLine()
protected int | getCurrentPos()
protected void | handleComment(char[] text) Called when an HTML comment is encountered.
protected void | handleEmptyTag(TagElement tag) Called when an empty tag is encountered.
protected void | handleEndTag(TagElement tag) Called when an end tag is encountered.
protected void | handleEOFInComment()
protected void | handleError(int ln, String msg) An error has occurred.
protected void | handleStartTag(TagElement tag) Called when a start tag is encountered.
protected void | handleText(char[] text) Called when PCDATA is encountered.
protected void | handleTitle(char[] text) Called when an HTML title tag is encountered.
protected TagElement | makeTag(Element elem)
protected TagElement | makeTag(Element elem, boolean fictional) Makes a TagElement.
protected void | markFirstTime(Element elem) Marks the first time a tag has been seen in a document
void | parse(Reader in) Parse an HTML stream, given a DTD.
String | parseDTDMarkup() Parses th Document Declaration Type markup declaration.
protected boolean | parseMarkupDeclarations(StringBuffer strBuff) Parse markup declarations.
protected void | startTag(TagElement tag) Handle a start tag.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

dtd

protected DTD dtd

strict

protected boolean strict
This flag determines whether or not the Parser will be strict in enforcing SGML compatibility. If false, it will be lenient with certain common classes of erroneous HTML constructs. Strict or not, in either case an error will be recorded.

Constructor Detail

Parser

public Parser(DTD dtd)
Method Detail

getCurrentLine

protected int getCurrentLine()
Returns:
the line number of the line currently being parsed

makeTag

protected TagElement makeTag(Element elem,
                             boolean fictional)
Makes a TagElement.

makeTag

protected TagElement makeTag(Element elem)

getAttributes

protected SimpleAttributeSet getAttributes()

flushAttributes

protected void flushAttributes()

handleText

protected void handleText(char[] text)
Called when PCDATA is encountered.

handleTitle

protected void handleTitle(char[] text)
Called when an HTML title tag is encountered.

handleComment

protected void handleComment(char[] text)
Called when an HTML comment is encountered.

handleEOFInComment

protected void handleEOFInComment()

handleEmptyTag

protected void handleEmptyTag(TagElement tag)
                       throws ChangedCharSetException
Called when an empty tag is encountered.

Throws:
ChangedCharSetException

handleStartTag

protected void handleStartTag(TagElement tag)
Called when a start tag is encountered.

handleEndTag

protected void handleEndTag(TagElement tag)
Called when an end tag is encountered.

handleError

protected void handleError(int ln,
                           String msg)
An error has occurred.

error

protected void error(String err,
                     String arg1,
                     String arg2,
                     String arg3)
Invoke the error handler.

error

protected void error(String err,
                     String arg1,
                     String arg2)

error

protected void error(String err,
                     String arg1)

error

protected void error(String err)

startTag

protected void startTag(TagElement tag)
                 throws ChangedCharSetException
Handle a start tag. The new tag is pushed onto the tag stack. The attribute list is checked for required attributes.

Throws:
ChangedCharSetException

endTag

protected void endTag(boolean omitted)
Handle an end tag. The end tag is popped from the tag stack.

markFirstTime

protected void markFirstTime(Element elem)
Marks the first time a tag has been seen in a document

parseDTDMarkup

public String parseDTDMarkup()
                      throws IOException
Parses th Document Declaration Type markup declaration. Currently ignores it.

Throws:
IOException

parseMarkupDeclarations

protected boolean parseMarkupDeclarations(StringBuffer strBuff)
                                   throws IOException
Parse markup declarations. Currently only handles the Document Type Declaration markup. Returns true if it is a markup declaration false otherwise.

Throws:
IOException

parse

public void parse(Reader in)
           throws IOException
Parse an HTML stream, given a DTD.

Throws:
IOException

getCurrentPos

protected int getCurrentPos()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ParserDelegator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html.parser
Class ParserDelegator

java.lang.Object
    extended by  javax.swing.text.html.HTMLEditorKit.Parser
        extended by  javax.swing.text.html.parser.ParserDelegator
All Implemented Interfaces:
Serializable
public class ParserDelegator
extends HTMLEditorKit.Parser
implements Serializable

Responsible for starting up a new DocumentParser each time its parse method is invoked. Stores a reference to the dtd.

Constructor Summary
ParserDelegator()
Method Summary
protected static DTD | createDTD(DTD dtd, String name)
void | parse(Reader r, HTMLEditorKit.ParserCallback cb, boolean ignoreCharSet) Parse the given stream and drive the given callback with the results of the parse.
protected static void | setDefaultDTD()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ParserDelegator

public ParserDelegator()
Method Detail

setDefaultDTD

protected static void setDefaultDTD()

createDTD

protected static DTD createDTD(DTD dtd,
                               String name)

parse

public void parse(Reader r,
                  HTMLEditorKit.ParserCallback cb,
                  boolean ignoreCharSet)
           throws IOException
Description copied from class: HTMLEditorKit.Parser
Parse the given stream and drive the given callback with the results of the parse. This method should be implemented to be thread-safe.

Specified by:
parse in class HTMLEditorKit.Parser
Throws:
IOException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TagElement

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html.parser
Class TagElement

java.lang.Object
    extended by  javax.swing.text.html.parser.TagElement

public class TagElement
extends Object

A generic HTML TagElement class. The methods define how white space is interpreted around the tag.

Constructor Summary
TagElement(Element elem)
TagElement(Element elem, boolean fictional)
Method Summary
boolean | breaksFlow()
boolean | fictional()
Element | getElement()
HTML.Tag | getHTMLTag()
boolean | isPreformatted()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TagElement

public TagElement(Element elem)

TagElement

public TagElement(Element elem,
                  boolean fictional)
Method Detail

breaksFlow

public boolean breaksFlow()

isPreformatted

public boolean isPreformatted()

getElement

public Element getElement()

getHTMLTag

public HTML.Tag getHTMLTag()

fictional

public boolean fictional()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


StyleSheet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class StyleSheet

java.lang.Object
    extended by  javax.swing.text.StyleContext
        extended by  javax.swing.text.html.StyleSheet
All Implemented Interfaces:
Serializable, AbstractDocument.AttributeContext
public class StyleSheet
extends StyleContext

Support for defining the visual characteristics of HTML views being rendered. The StyleSheet is used to translate the HTML model into visual characteristics. This enables views to be customized by a look-and-feel, multiple views over the same model can be rendered differently, etc. This can be thought of as a CSS rule repository. The key for CSS attributes is an object of type CSS.Attribute. The type of the value is up to the StyleSheet implementation, but the toString method is required to return a string representation of CSS value.

The primary entry point for HTML View implementations to get their attributes is the getViewAttributes method. This should be implemented to establish the desired policy used to associate attributes with the view. Each HTMLEditorKit (i.e. and therefore each associated JEditorPane) can have its own StyleSheet, but by default one sheet will be shared by all of the HTMLEditorKit instances. HTMLDocument instance can also have a StyleSheet, which holds the document-specific CSS specifications.

In order for Views to store less state and therefore be more lightweight, the StyleSheet can act as a factory for painters that handle some of the rendering tasks. This allows implementations to determine what they want to cache and have the sharing potentially at the level that a selector is common to multiple views. Since the StyleSheet may be used by views over multiple documents and typically the HTML attributes don't effect the selector being used, the potential for sharing is significant.

The rules are stored as named styles, and other information is stored to translate the context of an element to a rule quickly. The following code fragment will display the named styles, and therefore the CSS rules contained.

   import java.util.*;
   import javax.swing.text.*;
   import javax.swing.text.html.*;

   public class ShowStyles {

       public static void main(String[] args) {
           HTMLEditorKit kit = new HTMLEditorKit();
           HTMLDocument doc = (HTMLDocument) kit.createDefaultDocument();
           StyleSheet styles = doc.getStyleSheet();

           Enumeration rules = styles.getStyleNames();
           while (rules.hasMoreElements()) {
               String name = (String) rules.nextElement();
               Style rule = styles.getStyle(name);
               System.out.println(rule.toString());
           }
           System.exit(0);
       }
   }

The semantics for when a CSS style should overide visual attributes defined by an element are not well defined. For example, the html <body bgcolor=red> makes the body have a red background. But if the html file also contains the CSS rule body { background: blue } it becomes less clear as to what color the background of the body should be. The current implemention gives visual attributes defined in the element the highest precedence, that is they are always checked before any styles. Therefore, in the previous example the background would have a red color as the body element defines the background color to be red.

As already mentioned this supports CSS. We don't support the full CSS spec. Refer to the javadoc of the CSS class to see what properties we support. The two major CSS parsing related concepts we do not currently support are pseudo selectors, such as A:link { color: red }, and the important modifier.

Note: This implementation is currently incomplete. It can be replaced with alternative implementations that are complete. Future versions of this class will provide better CSS support.

Nested Class Summary
static class | StyleSheet.BoxPainter Class to carry out some of the duties of CSS formatting.
static class | StyleSheet.ListPainter Class to carry out some of the duties of CSS list formatting.
Nested classes/interfaces inherited from class javax.swing.text.StyleContext
StyleContext.NamedStyle, StyleContext.SmallAttributeSet
Field Summary
Fields inherited from class javax.swing.text.StyleContext
DEFAULT_STYLE
Constructor Summary
StyleSheet()
Construct a StyleSheet
Method Summary
AttributeSet | addAttribute(AttributeSet old, Object key, Object value) Adds an attribute to the given set, and returns the new representative set.
AttributeSet | addAttributes(AttributeSet old, AttributeSet attr) Adds a set of attributes to the element.
void | addCSSAttribute(MutableAttributeSet attr, CSS.Attribute key, String value) Adds a CSS attribute to the given set.
boolean | addCSSAttributeFromHTML(MutableAttributeSet attr, CSS.Attribute key, String value) Adds a CSS attribute to the given set.
void | addRule(String rule) Adds a set of rules to the sheet.
void | addStyleSheet(StyleSheet ss) Adds the rules from the StyleSheet ss to those of the receiver.
protected MutableAttributeSet | createLargeAttributeSet(AttributeSet a) Creates a large set of attributes that should trade off space for time.
protected StyleContext.SmallAttributeSet | createSmallAttributeSet(AttributeSet a) Creates a compact set of attributes that might be shared.
Color | getBackground(AttributeSet a) Takes a set of attributes and turn it into a background color specification.
URL | getBase() Returns the base.
StyleSheet.BoxPainter | getBoxPainter(AttributeSet a) Fetches the box formatter to use for the given set of CSS attributes.
AttributeSet | getDeclaration(String decl) Translates a CSS declaration to an AttributeSet that represents the CSS declaration.
Font | getFont(AttributeSet a) Fetches the font to use for the given set of attributes.
Color | getForeground(AttributeSet a) Takes a set of attributes and turn it into a foreground color specification.
static int | getIndexOfSize(float pt)
StyleSheet.ListPainter | getListPainter(AttributeSet a) Fetches the list formatter to use for the given set of CSS attributes.
float | getPointSize(int index) Returns the point size, given a size index.
float | getPointSize(String size) Given a string such as "+2", "-2", or "2", returns a point size value.
Style | getRule(HTML.Tag t, Element e) Fetches the style to use to render the given type of HTML tag.
Style | getRule(String selector) Fetches the rule that best matches the selector given in string form.
StyleSheet[] | getStyleSheets() Returns an array of the linked StyleSheets.
AttributeSet | getViewAttributes(View v) Fetches a set of attributes to use in the view for displaying.
void | importStyleSheet(URL url) Imports a style sheet from url.
void | loadRules(Reader in, URL ref) Loads a set of rules that have been specified in terms of CSS1 grammar.
AttributeSet | removeAttribute(AttributeSet old, Object key) Removes an attribute from the set.
AttributeSet | removeAttributes(AttributeSet old, AttributeSet attrs) Removes a set of attributes.
AttributeSet | removeAttributes(AttributeSet old, Enumeration<?> names) Removes a set of attributes for the element.
void | removeStyle(String nm) Removes a named style previously added to the document.
void | removeStyleSheet(StyleSheet ss) Removes the StyleSheet ss from those of the receiver.
void | setBase(URL base) Sets the base.
void | setBaseFontSize(int sz) Sets the base font size, with valid values between 1 and 7.
void | setBaseFontSize(String size) Sets the base font size from the passed in String.
Color | stringToColor(String string) Converts a color string such as "RED" or "#NNNNNN" to a Color.
AttributeSet | translateHTMLToCSS(AttributeSet htmlAttrSet) Converts a set of HTML attributes to an equivalent set of CSS attributes.
Methods inherited from class javax.swing.text.StyleContext
addChangeListener, addStyle, getChangeListeners, getCompressionThreshold, getDefaultStyleContext, getEmptySet, getFont, getFontMetrics, getStaticAttribute, getStaticAttributeKey, getStyle, getStyleNames, readAttributes, readAttributeSet, reclaim, registerStaticAttributeKey, removeChangeListener, toString, writeAttributes, writeAttributeSet
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

StyleSheet

public StyleSheet()
Construct a StyleSheet

Method Detail

getRule

public Style getRule(HTML.Tag t,
                     Element e)
Fetches the style to use to render the given type of HTML tag. The element given is representing the tag and can be used to determine the nesting for situations where the attributes will differ if nesting inside of elements.

Parameters:
t - the type to translate to visual attributes
e - the element representing the tag; the element can be used to determine the nesting for situations where the attributes will differ if nested inside of other elements
Returns:
the set of CSS attributes to use to render the tag

getRule

public Style getRule(String selector)
Fetches the rule that best matches the selector given in string form. Where selector is a space separated String of the element names. For example, selector might be 'html body tr td''

The attributes of the returned Style will change as rules are added and removed. That is if you to ask for a rule with a selector "table p" and a new rule was added with a selector of "p" the returned Style would include the new attributes from the rule "p".

addRule

public void addRule(String rule)
Adds a set of rules to the sheet. The rules are expected to be in valid CSS format. Typically this would be called as a result of parsing a <style> tag.

getDeclaration

public AttributeSet getDeclaration(String decl)
Translates a CSS declaration to an AttributeSet that represents the CSS declaration. Typically this would be called as a result of encountering an HTML style attribute.

loadRules

public void loadRules(Reader in,
                      URL ref)
               throws IOException
Loads a set of rules that have been specified in terms of CSS1 grammar. If there are collisions with existing rules, the newly specified rule will win.

Parameters:
in - the stream to read the CSS grammar from
ref - the reference URL. This value represents the location of the stream and may be null. All relative URLs specified in the stream will be based upon this parameter.
Throws:
IOException

getViewAttributes

public AttributeSet getViewAttributes(View v)
Fetches a set of attributes to use in the view for displaying. This is basically a set of attributes that can be used for View.getAttributes.

removeStyle

public void removeStyle(String nm)
Removes a named style previously added to the document.

Overrides:
removeStyle in class StyleContext
Parameters:
nm - the name of the style to remove

addStyleSheet

public void addStyleSheet(StyleSheet ss)
Adds the rules from the StyleSheet ss to those of the receiver. ss's rules will override the rules of any previously added style sheets. An added StyleSheet will never override the rules of the receiving style sheet.

Since:
1.3

removeStyleSheet

public void removeStyleSheet(StyleSheet ss)
Removes the StyleSheet ss from those of the receiver.

Since:
1.3

getStyleSheets

public StyleSheet[] getStyleSheets()
Returns an array of the linked StyleSheets. Will return null if there are no linked StyleSheets.

Since:
1.3

importStyleSheet

public void importStyleSheet(URL url)
Imports a style sheet from url. The resulting rules are directly added to the receiver. If you do not want the rules to become part of the receiver, create a new StyleSheet and use addStyleSheet to link it in.

Since:
1.3

setBase

public void setBase(URL base)
Sets the base. All import statements that are relative, will be relative to base.

Since:
1.3

getBase

public URL getBase()
Returns the base.

Since:
1.3

addCSSAttribute

public void addCSSAttribute(MutableAttributeSet attr,
                            CSS.Attribute key,
                            String value)
Adds a CSS attribute to the given set.

Since:
1.3

addCSSAttributeFromHTML

public boolean addCSSAttributeFromHTML(MutableAttributeSet attr,
                                       CSS.Attribute key,
                                       String value)
Adds a CSS attribute to the given set.

Since:
1.3

translateHTMLToCSS

public AttributeSet translateHTMLToCSS(AttributeSet htmlAttrSet)
Converts a set of HTML attributes to an equivalent set of CSS attributes.

Parameters:
htmlAttrSet - AttributeSet containing the HTML attributes.

addAttribute

public AttributeSet addAttribute(AttributeSet old,
                                 Object key,
                                 Object value)
Adds an attribute to the given set, and returns the new representative set. This is reimplemented to convert StyleConstant attributes to CSS prior to forwarding to the superclass behavior. The StyleConstants attribute has no corresponding CSS entry, the StyleConstants attribute is stored (but will likely be unused).

Specified by:
addAttribute in interface AbstractDocument.AttributeContext
Overrides:
addAttribute in class StyleContext
Parameters:
old - the old attribute set
key - the non-null attribute key
value - the attribute value
Returns:
the updated attribute set
See Also:
MutableAttributeSet.addAttribute(java.lang.Object, java.lang.Object)

addAttributes

public AttributeSet addAttributes(AttributeSet old,
                                  AttributeSet attr)
Adds a set of attributes to the element. If any of these attributes are StyleConstants attributes, they will be converted to CSS prior to forwarding to the superclass behavior.

Specified by:
addAttributes in interface AbstractDocument.AttributeContext
Overrides:
addAttributes in class StyleContext
Parameters:
old - the old attribute set
attr - the attributes to add
Returns:
the updated attribute set
See Also:
MutableAttributeSet.addAttribute(java.lang.Object, java.lang.Object)

removeAttribute

public AttributeSet removeAttribute(AttributeSet old,
                                    Object key)
Removes an attribute from the set. If the attribute is a StyleConstants attribute, the request will be converted to a CSS attribute prior to forwarding to the superclass behavior.

Specified by:
removeAttribute in interface AbstractDocument.AttributeContext
Overrides:
removeAttribute in class StyleContext
Parameters:
old - the old set of attributes
key - the non-null attribute name
Returns:
the updated attribute set
See Also:
MutableAttributeSet.removeAttribute(java.lang.Object)

removeAttributes

public AttributeSet removeAttributes(AttributeSet old,
                                     Enumeration<?> names)
Removes a set of attributes for the element. If any of the attributes is a StyleConstants attribute, the request will be converted to a CSS attribute prior to forwarding to the superclass behavior.

Specified by:
removeAttributes in interface AbstractDocument.AttributeContext
Overrides:
removeAttributes in class StyleContext
Parameters:
old - the old attribute set
names - the attribute names
Returns:
the updated attribute set
See Also:
MutableAttributeSet.removeAttributes(java.util.Enumeration)

removeAttributes

public AttributeSet removeAttributes(AttributeSet old,
                                     AttributeSet attrs)
Removes a set of attributes. If any of the attributes is a StyleConstants attribute, the request will be converted to a CSS attribute prior to forwarding to the superclass behavior.

Specified by:
removeAttributes in interface AbstractDocument.AttributeContext
Overrides:
removeAttributes in class StyleContext
Parameters:
old - the old attribute set
attrs - the attributes
Returns:
the updated attribute set
See Also:
MutableAttributeSet.removeAttributes(java.util.Enumeration)

createSmallAttributeSet

protected StyleContext.SmallAttributeSet createSmallAttributeSet(AttributeSet a)
Creates a compact set of attributes that might be shared. This is a hook for subclasses that want to alter the behavior of SmallAttributeSet. This can be reimplemented to return an AttributeSet that provides some sort of attribute conversion.

Overrides:
createSmallAttributeSet in class StyleContext
Parameters:
a - The set of attributes to be represented in the the compact form.

createLargeAttributeSet

protected MutableAttributeSet createLargeAttributeSet(AttributeSet a)
Creates a large set of attributes that should trade off space for time. This set will not be shared. This is a hook for subclasses that want to alter the behavior of the larger attribute storage format (which is SimpleAttributeSet by default). This can be reimplemented to return a MutableAttributeSet that provides some sort of attribute conversion.

Overrides:
createLargeAttributeSet in class StyleContext
Parameters:
a - The set of attributes to be represented in the the larger form.

getFont

public Font getFont(AttributeSet a)
Fetches the font to use for the given set of attributes.

Overrides:
getFont in class StyleContext
Parameters:
a - the attribute set
Returns:
the font

getForeground

public Color getForeground(AttributeSet a)
Takes a set of attributes and turn it into a foreground color specification. This might be used to specify things like brighter, more hue, etc.

Overrides:
getForeground in class StyleContext
Parameters:
a - the set of attributes
Returns:
the color

getBackground

public Color getBackground(AttributeSet a)
Takes a set of attributes and turn it into a background color specification. This might be used to specify things like brighter, more hue, etc.

Overrides:
getBackground in class StyleContext
Parameters:
a - the set of attributes
Returns:
the color

getBoxPainter

public StyleSheet.BoxPainter getBoxPainter(AttributeSet a)
Fetches the box formatter to use for the given set of CSS attributes.

getListPainter

public StyleSheet.ListPainter getListPainter(AttributeSet a)
Fetches the list formatter to use for the given set of CSS attributes.

setBaseFontSize

public void setBaseFontSize(int sz)
Sets the base font size, with valid values between 1 and 7.

setBaseFontSize

public void setBaseFontSize(String size)
Sets the base font size from the passed in String. The string can either identify a specific font size, with legal values between 1 and 7, or identifiy a relative font size such as +1 or -2.

getIndexOfSize

public static int getIndexOfSize(float pt)

getPointSize

public float getPointSize(int index)
Returns the point size, given a size index.

getPointSize

public float getPointSize(String size)
Given a string such as "+2", "-2", or "2", returns a point size value.

stringToColor

public Color stringToColor(String string)
Converts a color string such as "RED" or "#NNNNNN" to a Color. Note: This will only convert the HTML3.2 color strings or a string of length 7; otherwise, it will return null.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyleSheet.BoxPainter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class StyleSheet.BoxPainter

java.lang.Object
    extended by  javax.swing.text.html.StyleSheet.BoxPainter
All Implemented Interfaces:
Serializable
Enclosing class:
StyleSheet
public static class StyleSheet.BoxPainter
extends Object
implements Serializable

Class to carry out some of the duties of CSS formatting. Implementations of this class enable views to present the CSS formatting while not knowing anything about how the CSS values are being cached.

As a delegate of Views, this object is responsible for the insets of a View and making sure the background is maintained according to the CSS attributes.

Method Summary
float | getInset(int side, View v) Fetches the inset needed on a given side to account for the margin, border, and padding.
void | paint(Graphics g, float x, float y, float w, float h, View v) Paints the CSS box according to the attributes given.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInset

public float getInset(int side,
                      View v)
Fetches the inset needed on a given side to account for the margin, border, and padding.

Parameters:
side - The size of the box to fetch the inset for. This can be View.TOP, View.LEFT, View.BOTTOM, or View.RIGHT.
v - the view making the request. This is used to get the AttributeSet, and may be used to resolve percentage arguments.
Throws:
IllegalArgumentException - for an invalid direction

paint

public void paint(Graphics g,
                  float x,
                  float y,
                  float w,
                  float h,
                  View v)
Paints the CSS box according to the attributes given. This should paint the border, padding, and background.

Parameters:
g - the rendering surface.
x - the x coordinate of the allocated area to render into.
y - the y coordinate of the allocated area to render into.
w - the width of the allocated area to render into.
h - the height of the allocated area to render into.
v - the view making the request. This is used to get the AttributeSet, and may be used to resolve percentage arguments.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyleSheet.ListPainter

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.html
Class StyleSheet.ListPainter

java.lang.Object
    extended by  javax.swing.text.html.StyleSheet.ListPainter
All Implemented Interfaces:
Serializable
Enclosing class:
StyleSheet
public static class StyleSheet.ListPainter
extends Object
implements Serializable

Class to carry out some of the duties of CSS list formatting. Implementations of this class enable views to present the CSS formatting while not knowing anything about how the CSS values are being cached.

Method Summary
 void paint(Graphics g, float x, float y, float w, float h, View v, int item)
Paints the CSS list decoration according to the attributes given.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

paint

public void paint(Graphics g,
                  float x,
                  float y,
                  float w,
                  float h,
                  View v,
                  int item)
Paints the CSS list decoration according to the attributes given.

Parameters:
g - the rendering surface.
x - the x coordinate of the list item allocation
y - the y coordinate of the list item allocation
w - the width of the list item allocation
h - the height of the list item allocation
v - the allocated area to paint into.
item - which list item is being painted. This is a number greater than or equal to 0.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


IconView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class IconView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.IconView
All Implemented Interfaces:
SwingConstants
public class IconView
extends View

Icon decorator that implements the view interface. The entire element is used to represent the icon. This acts as a gateway from the display-only View implementations to interactive lightweight icons (that is, it allows icons to be embedded into the View hierarchy. The parent of the icon is the container that is handed out by the associated view factory.

Field Summary
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
IconView(Element elem)
Creates a new icon view that represents an element.
Method Summary
float | getAlignment(int axis) Determines the desired alignment for this view along an axis.
float | getPreferredSpan(int axis) Determines the preferred span for this view along an axis.
Shape | modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
void | paint(Graphics g, Shape a) Paints the icon.
int | viewToModel(float x, float y, Shape a, Position.Bias[] bias) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
Methods inherited from class javax.swing.text.View
append, breakView, changedUpdate, createFragment, forwardUpdate, forwardUpdateToView, getAttributes, getBreakWeight, getChildAllocation, getContainer, getDocument, getElement, getEndOffset, getGraphics, getMaximumSpan, getMinimumSpan, getNextVisualPositionFrom, getParent, getResizeWeight, getStartOffset, getToolTipText, getView, getViewCount, getViewFactory, getViewIndex, getViewIndex, insert, insertUpdate, isVisible, modelToView, modelToView, preferenceChanged, remove, removeAll, removeUpdate, replace, setParent, setSize, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IconView

public IconView(Element elem)
Creates a new icon view that represents an element.

Parameters:
elem - the element to create a view for
Method Detail

paint

public void paint(Graphics g,
                  Shape a)
Paints the icon. The real paint behavior occurs naturally from the association that the icon has with its parent container (the same container hosting this view), so this simply allows us to position the icon properly relative to the view. Since the coordinate system for the view is simply the parent containers, positioning the child icon is easy.

Specified by:
paint in class View
Parameters:
g - the rendering surface to use
a - the allocated region to render into
See Also:
View.paint(java.awt.Graphics, java.awt.Shape)

getPreferredSpan

public float getPreferredSpan(int axis)
Determines the preferred span for this view along an axis.

Specified by:
getPreferredSpan in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into Typically the view is told to render into the span that is returned, although there is no guarantee. The parent may choose to resize or break the view.
Throws:
IllegalArgumentException - for an invalid axis
See Also:
View.getPreferredSpan(int)

getAlignment

public float getAlignment(int axis)
Determines the desired alignment for this view along an axis. This is implemented to give the alignment to the bottom of the icon along the y axis, and the default along the x axis.

Overrides:
getAlignment in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the desired alignment >= 0.0f && <= 1.0f.="1.0f." This="This" should="should" be="be" a="a" value="value" between="between" 0.0="0.0" and="and" 1.0="1.0" where="where" 0="0" indicates="indicates" alignment="alignment" at="at" the="the" origin="origin" and="and" 1.0="1.0" indicates="indicates" alignment="alignment" to="to" the="the" full="full" span="span" away="away" from="from" the="the" origin.="origin." An="An" alignment="alignment" of="of" 0.5="0.5" would="would" be="be" the="the" center="center" of="of" the="the" view.

modelToView

public Shape modelToView(int pos,
                         Shape a,
                         Position.Bias b)
                  throws BadLocationException
Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.

Specified by:
modelToView in class View
Parameters:
pos - the position to convert >= 0
a - the allocated region to render into
b - the bias toward the previous character or the next character represented by the offset, in case the position is a boundary of two views; b will have one of these values:
  • Position.Bias.Forward
  • Position.Bias.Backward
Returns:
the bounding box of the given position
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
See Also:
View.modelToView(int, java.awt.Shape, javax.swing.text.Position.Bias)

viewToModel

public int viewToModel(float x,
                       float y,
                       Shape a,
                       Position.Bias[] bias)
Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Specified by:
viewToModel in class View
Parameters:
x - the X coordinate >= 0
y - the Y coordinate >= 0
a - the allocated region to render into
Returns:
the location within the model that best represents the given point of view >= 0
See Also:
View.viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InternationalFormatter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class InternationalFormatter

java.lang.Object
    extended by  javax.swing.JFormattedTextField.AbstractFormatter
        extended by  javax.swing.text.DefaultFormatter
            extended by  javax.swing.text.InternationalFormatter
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
DateFormatter, NumberFormatter
public class InternationalFormatter
extends DefaultFormatter

InternationalFormatter extends DefaultFormatter, using an instance of java.text.Format to handle the conversion to a String, and the conversion from a String.

If getAllowsInvalid() is false, this will ask the Format to format the current text on every edit.

You can specify a minimum and maximum value by way of the setMinimum and setMaximum methods. In order for this to work the values returned from stringToValue must be comparable to the min/max values by way of the Comparable interface.

Be careful how you configure the Format and the InternationalFormatter, as it is possible to create a situation where certain values can not be input. Consider the date format 'M/d/yy', an InternationalFormatter that is always valid (setAllowsInvalid(false)), is in overwrite mode (setOverwriteMode(true)) and the date 7/1/99. In this case the user will not be able to enter a two digit month or day of month. To avoid this, the format should be 'MM/dd/yy'.

If InternationalFormatter is configured to only allow valid values (setAllowsInvalid(false)), every valid edit will result in the text of the JFormattedTextField being completely reset from the Format. The cursor position will also be adjusted as literal characters are added/removed from the resulting String.

InternationalFormatter's behavior of stringToValue is slightly different than that of DefaultTextFormatter, it does the following:

  1. parseObject is invoked on the Format specified by setFormat
  2. If a Class has been set for the values (setValueClass), supers implementation is invoked to convert the value returned from parseObject to the appropriate class.
  3. If a ParseException has not been thrown, and the value is outside the min/max a ParseException is thrown.
  4. The value is returned.
InternationalFormatter implements stringToValue in this manner so that you can specify an alternate Class than Format may return.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Since:
1.4
See Also:
Format, Comparable

Constructor Summary
InternationalFormatter()
Creates an InternationalFormatter with no Format specified.
InternationalFormatter(Format format)
Creates an InternationalFormatter with the specified Format instance.
Method Summary
Object | clone() Creates a copy of the DefaultFormatter.
protected Action[] | getActions() If getSupportsIncrement returns true, this returns two Actions suitable for incrementing/decrementing the value.
Format.Field[] | getFields(int offset) Returns the Format.Field constants associated with the text at offset.
Format | getFormat() Returns the format that dictates the legal values that can be edited and displayed.
Comparable | getMaximum() Returns the maximum permissible value.
Comparable | getMinimum() Returns the minimum permissible value.
void | install(JFormattedTextField ftf) Installs the DefaultFormatter onto a particular JFormattedTextField.
void | setFormat(Format format) Sets the format that dictates the legal values that can be edited and displayed.
void | setMaximum(Comparable max) Sets the maximum permissible value.
void | setMinimum(Comparable minimum) Sets the minimum permissible value.
Object | stringToValue(String text) Returns the Object representation of the String text.
String | valueToString(Object value) Returns a String representation of the Object value.
Methods inherited from class javax.swing.text.DefaultFormatter
getAllowsInvalid, getCommitsOnValidEdit, getDocumentFilter, getNavigationFilter, getOverwriteMode, getValueClass, setAllowsInvalid, setCommitsOnValidEdit, setOverwriteMode, setValueClass
Methods inherited from class javax.swing.JFormattedTextField.AbstractFormatter
getFormattedTextField, invalidEdit, setEditValid, uninstall
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InternationalFormatter

public InternationalFormatter()
Creates an InternationalFormatter with no Format specified.

InternationalFormatter

public InternationalFormatter(Format format)
Creates an InternationalFormatter with the specified Format instance.

Parameters:
format - Format instance used for converting from/to Strings
Method Detail

setFormat

public void setFormat(Format format)
Sets the format that dictates the legal values that can be edited and displayed.

Parameters:
format - Format instance used for converting from/to Strings

getFormat

public Format getFormat()
Returns the format that dictates the legal values that can be edited and displayed.

Returns:
Format instance used for converting from/to Strings

setMinimum

public void setMinimum(Comparable minimum)
Sets the minimum permissible value. If the valueClass has not been specified, and minimum is non null, the valueClass will be set to that of the class of minimum.

Parameters:
minimum - Minimum legal value that can be input
See Also:
DefaultFormatter.setValueClass(java.lang.Class)

getMinimum

public Comparable getMinimum()
Returns the minimum permissible value.

Returns:
Minimum legal value that can be input

setMaximum

public void setMaximum(Comparable max)
Sets the maximum permissible value. If the valueClass has not been specified, and max is non null, the valueClass will be set to that of the class of max.

Parameters:
max - Maximum legal value that can be input
See Also:
DefaultFormatter.setValueClass(java.lang.Class)

getMaximum

public Comparable getMaximum()
Returns the maximum permissible value.

Returns:
Maximum legal value that can be input

install

public void install(JFormattedTextField ftf)
Installs the DefaultFormatter onto a particular JFormattedTextField. This will invoke valueToString to convert the current value from the JFormattedTextField to a String. This will then install the Actions from getActions, the DocumentFilter returned from getDocumentFilter and the NavigationFilter returned from getNavigationFilter onto the JFormattedTextField.

Subclasses will typically only need to override this if they wish to install additional listeners on the JFormattedTextField.

If there is a ParseException in converting the current value to a String, this will set the text to an empty String, and mark the JFormattedTextField as being in an invalid state.

While this is a public method, this is typically only useful for subclassers of JFormattedTextField. JFormattedTextField will invoke this method at the appropriate times when the value changes, or its internal state changes.

Overrides:
install in class DefaultFormatter
Parameters:
ftf - JFormattedTextField to format for, may be null indicating uninstall from current JFormattedTextField.

valueToString

public String valueToString(Object value)
                     throws ParseException
Returns a String representation of the Object value. This invokes format on the current Format.

Overrides:
valueToString in class DefaultFormatter
Parameters:
value - Value to convert
Returns:
String representation of value
Throws:
ParseException - if there is an error in the conversion

stringToValue

public Object stringToValue(String text)
                     throws ParseException
Returns the Object representation of the String text.

Overrides:
stringToValue in class DefaultFormatter
Parameters:
text - String to convert
Returns:
Object representation of text
Throws:
ParseException - if there is an error in the conversion

getFields

public Format.Field[] getFields(int offset)
Returns the Format.Field constants associated with the text at offset. If offset is not a valid location into the current text, this will return an empty array.

Parameters:
offset - offset into text to be examined
Returns:
Format.Field constants associated with the text at the given position.

clone

public Object clone()
             throws CloneNotSupportedException
Creates a copy of the DefaultFormatter.

Overrides:
clone in class DefaultFormatter
Returns:
copy of the DefaultFormatter
Throws:
CloneNotSupportedException - if the object's class does not support the Cloneable interface. Subclasses that override the clone method can also throw this exception to indicate that an instance cannot be cloned.
See Also:
Cloneable

getActions

protected Action[] getActions()
If getSupportsIncrement returns true, this returns two Actions suitable for incrementing/decrementing the value.

Overrides:
getActions in class JFormattedTextField.AbstractFormatter
Returns:
Array of Actions to install on JFormattedTextField
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTextComponent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class JTextComponent

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.text.JTextComponent
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable
Direct Known Subclasses:
JEditorPane, JTextArea, JTextField
public abstract class JTextComponent
extends JComponent
implements Scrollable, Accessible

JTextComponent is the base class for swing text components. It tries to be compatible with the java.awt.TextComponent class where it can reasonably do so. Also provided are other services for additional flexibility (beyond the pluggable UI and bean support). You can find information on how to use the functionality this class provides in General Rules for Using Text Components, a section in The Java Tutorial.

Caret Changes
The caret is a pluggable object in swing text components. Notification of changes to the caret position and the selection are sent to implementations of the CaretListener interface that have been registered with the text component. The UI will install a default caret unless a customized caret has been set.
By default the caret tracks all the document changes performed on the Event Dispatching Thread and updates it's position accordingly if an insertion occurs before or at the caret position or a removal occurs before the caret position. DefaultCaret tries to make itself visible which may lead to scrolling of a text component within JScrollPane. The default caret behavior can be changed by the DefaultCaret.setUpdatePolicy(int) method.
Note: Non-editable text components also have a caret though it may not be painted.

Commands
Text components provide a number of commands that can be used to manipulate the component. This is essentially the way that the component expresses its capabilities. These are expressed in terms of the swing Action interface, using the TextAction implementation. The set of commands supported by the text component can be found with the getActions() method. These actions can be bound to key events, fired from buttons, etc.

Text Input
The text components support flexible and internationalized text input, using keymaps and the input method framework, while maintaining compatibility with the AWT listener model.

A Keymap lets an application bind key strokes to actions. In order to allow keymaps to be shared across multiple text components, they can use actions that extend TextAction. TextAction can determine which JTextComponent most recently has or had focus and therefore is the subject of the action (In the case that the ActionEvent sent to the action doesn't contain the target text component as its source).

The input method framework lets text components interact with input methods, separate software components that preprocess events to let users enter thousands of different characters using keyboards with far fewer keys. JTextComponent is an active client of the framework, so it implements the preferred user interface for interacting with input methods. As a consequence, some key events do not reach the text component because they are handled by an input method, and some text input reaches the text component as committed text within an InputMethodEvent instead of as a key event. The complete text input is the combination of the characters in keyTyped key events and committed text in input method events.

The AWT listener model lets applications attach event listeners to components in order to bind events to actions. Swing encourages the use of keymaps instead of listeners, but maintains compatibility with listeners by giving the listeners a chance to steal an event by consuming it.

Keyboard event and input method events are handled in the following stages, with each stage capable of consuming the event:

Stage

KeyEvent

InputMethodEvent

1. | input methods | (generated here)
2. | focus manager
3. | registered key listeners | registered input method listeners
4. | input method handling in JTextComponent
5. | keymap handling using the current keymap
6. | keyboard handling in JComponent (e.g. accelerators, component navigation, etc.)

To maintain compatibility with applications that listen to key events but are not aware of input method events, the input method handling in stage 4 provides a compatibility mode for components that do not process input method events. For these components, the committed text is converted to keyTyped key events and processed in the key event pipeline starting at stage 3 instead of in the input method event pipeline.

By default the component will create a keymap (named DEFAULT_KEYMAP) that is shared by all JTextComponent instances as the default keymap. Typically a look-and-feel implementation will install a different keymap that resolves to the default keymap for those bindings not found in the different keymap. The minimal bindings include:

  • inserting content into the editor for the printable keys.
  • removing content with the backspace and del keys.
  • caret movement forward and backward

Model/View Split
The text components have a model-view split. A text component pulls together the objects used to represent the model, view, and controller. The text document model may be shared by other views which act as observers of the model (e.g. a document may be shared by multiple components).

Diagram showing interaction between Controller, Document, events, and ViewFactory

The model is defined by the Document interface. This is intended to provide a flexible text storage mechanism that tracks change during edits and can be extended to more sophisticated models. The model interfaces are meant to capture the capabilities of expression given by SGML, a system used to express a wide variety of content. Each modification to the document causes notification of the details of the change to be sent to all observers in the form of a DocumentEvent which allows the views to stay up to date with the model. This event is sent to observers that have implemented the DocumentListener interface and registered interest with the model being observed.

Location Information
The capability of determining the location of text in the view is provided. There are two methods, modelToView(int) and viewToModel(java.awt.Point) for determining this information.

Undo/Redo support
Support for an edit history mechanism is provided to allow undo/redo operations. The text component does not itself provide the history buffer by default, but does provide the UndoableEdit records that can be used in conjunction with a history buffer to provide the undo/redo support. The support is provided by the Document model, which allows one to attach UndoableEditListener implementations.

Thread Safety
The swing text components provide some support of thread safe operations. Because of the high level of configurability of the text components, it is possible to circumvent the protection provided. The protection primarily comes from the model, so the documentation of AbstractDocument describes the assumptions of the protection provided. The methods that are safe to call asynchronously are marked with comments.

Newlines
For a discussion on how newlines are handled, see DefaultEditorKit.

Printing support
Several print methods are provided for basic document printing. If more advanced printing is needed, use the getPrintable(java.text.MessageFormat, java.text.MessageFormat) method.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
Document, DocumentEvent, DocumentListener, Caret, CaretEvent, CaretListener, TextUI, View, ViewFactory

Nested Class Summary
class | JTextComponent.AccessibleJTextComponent This class implements accessibility support for the JTextComponent class.
static class | JTextComponent.DropLocation Represents a drop location for JTextComponents.
static class | JTextComponent.KeyBinding Binding record for creating key bindings.
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
static String | DEFAULT_KEYMAP The default keymap that will be shared by all JTextComponent instances unless they have had a different keymap set.
static String | FOCUS_ACCELERATOR_KEY The bound property name for the focus accelerator.
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
JTextComponent()
Creates a new JTextComponent.
Method Summary
void | addCaretListener(CaretListener listener) Adds a caret listener for notification of any changes to the caret.
void | addInputMethodListener(InputMethodListener l) Adds the specified input method listener to receive input method events from this component.
static Keymap | addKeymap(String nm, Keymap parent) Adds a new keymap into the keymap hierarchy.
void | copy() Transfers the currently selected range in the associated text model to the system clipboard, leaving the contents in the text model.
void | cut() Transfers the currently selected range in the associated text model to the system clipboard, removing the contents from the model.
protected void | fireCaretUpdate(CaretEvent e) Notifies all listeners that have registered interest for notification on this event type.
AccessibleContext | getAccessibleContext() Gets the AccessibleContext associated with this JTextComponent.
Action[] | getActions() Fetches the command list for the editor.
Caret | getCaret() Fetches the caret that allows text-oriented navigation over the view.
Color | getCaretColor() Fetches the current color used to render the caret.
CaretListener[] | getCaretListeners() Returns an array of all the caret listeners registered on this text component.
int | getCaretPosition() Returns the position of the text insertion caret for the text component.
Color | getDisabledTextColor() Fetches the current color used to render the disabled text.
Document | getDocument() Fetches the model associated with the editor.
boolean | getDragEnabled() Returns whether or not automatic drag handling is enabled.
JTextComponent.DropLocation | getDropLocation() Returns the location that this component should visually indicate as the drop location during a DnD operation over the component, or null if no location is to currently be shown.
DropMode | getDropMode() Returns the drop mode for this component.
char | getFocusAccelerator() Returns the key accelerator that will cause the receiving text component to get the focus.
Highlighter | getHighlighter() Fetches the object responsible for making highlights.
InputMethodRequests | getInputMethodRequests() Gets the input method request handler which supports requests from input methods for this component.
Keymap | getKeymap() Fetches the keymap currently active in this text component.
static Keymap | getKeymap(String nm) Fetches a named keymap previously added to the document.
Insets | getMargin() Returns the margin between the text component's border and its text.
NavigationFilter | getNavigationFilter() Returns the NavigationFilter.
Dimension | getPreferredScrollableViewportSize() Returns the preferred size of the viewport for a view component.
Printable | getPrintable(MessageFormat headerFormat, MessageFormat footerFormat) Returns a Printable to use for printing the content of this JTextComponent.
int | getScrollableBlockIncrement(Rectangle visibleRect, int orientation, int direction) Components that display logical rows or columns should compute the scroll increment that will completely expose one block of rows or columns, depending on the value of orientation.
boolean | getScrollableTracksViewportHeight() Returns true if a viewport should always force the height of this Scrollable to match the height of the viewport.
boolean | getScrollableTracksViewportWidth() Returns true if a viewport should always force the width of this Scrollable to match the width of the viewport.
int | getScrollableUnitIncrement(Rectangle visibleRect, int orientation, int direction) Components that display logical rows or columns should compute the scroll increment that will completely expose one new row or column, depending on the value of orientation.
String | getSelectedText() Returns the selected text contained in this TextComponent.
Color | getSelectedTextColor() Fetches the current color used to render the selected text.
Color | getSelectionColor() Fetches the current color used to render the selection.
int | getSelectionEnd() Returns the selected text's end position.
int | getSelectionStart() Returns the selected text's start position.
String | getText() Returns the text contained in this TextComponent.
String | getText(int offs, int len) Fetches a portion of the text represented by the component.
String | getToolTipText(MouseEvent event) Returns the string to be used as the tooltip for event.
TextUI | getUI() Fetches the user-interface factory for this text-oriented editor.
boolean | isEditable() Returns the boolean indicating whether this TextComponent is editable or not.
static void | loadKeymap(Keymap map, JTextComponent.KeyBinding[] bindings, Action[] actions) Loads a keymap with a bunch of bindings.
Rectangle | modelToView(int pos) Converts the given location in the model to a place in the view coordinate system.
void | moveCaretPosition(int pos) Moves the caret to a new position, leaving behind a mark defined by the last time setCaretPosition was called.
protected String | paramString() Returns a string representation of this JTextComponent.
void | paste() Transfers the contents of the system clipboard into the associated text model.
boolean | print() A convenience print method that displays a print dialog, and then prints this JTextComponent in interactive mode with no header or footer text.
boolean | print(MessageFormat headerFormat, MessageFormat footerFormat) A convenience print method that displays a print dialog, and then prints this JTextComponent in interactive mode with the specified header and footer text.
boolean | print(MessageFormat headerFormat, MessageFormat footerFormat, boolean showPrintDialog, PrintService service, PrintRequestAttributeSet attributes, boolean interactive) Prints the content of this JTextComponent.
protected void | processInputMethodEvent(InputMethodEvent e) Processes input method events occurring on this component by dispatching them to any registered InputMethodListener objects.
void | read(Reader in, Object desc) Initializes from a stream.
void | removeCaretListener(CaretListener listener) Removes a caret listener.
static Keymap | removeKeymap(String nm) Removes a named keymap previously added to the document.
void | removeNotify() Notifies this component that it no longer has a parent component.
void | replaceSelection(String content) Replaces the currently selected content with new content represented by the given string.
void | select(int selectionStart, int selectionEnd) Selects the text between the specified start and end positions.
void | selectAll() Selects all the text in the TextComponent.
void | setCaret(Caret c) Sets the caret to be used.
void | setCaretColor(Color c) Sets the current color used to render the caret.
void | setCaretPosition(int position) Sets the position of the text insertion caret for the TextComponent.
void | setComponentOrientation(ComponentOrientation o) Sets the language-sensitive orientation that is to be used to order the elements or text within this component.
void | setDisabledTextColor(Color c) Sets the current color used to render the disabled text.
void | setDocument(Document doc) Associates the editor with a text document.
void | setDragEnabled(boolean b) Turns on or off automatic drag handling.
void | setDropMode(DropMode dropMode) Sets the drop mode for this component.
void | setEditable(boolean b) Sets the specified boolean to indicate whether or not this TextComponent should be editable.
void | setFocusAccelerator(char aKey) Sets the key accelerator that will cause the receiving text component to get the focus.
void | setHighlighter(Highlighter h) Sets the highlighter to be used.
void | setKeymap(Keymap map) Sets the keymap to use for binding events to actions.
void | setMargin(Insets m) Sets margin space between the text component's border and its text.
void | setNavigationFilter(NavigationFilter filter) Sets the NavigationFilter.
void | setSelectedTextColor(Color c) Sets the current color used to render the selected text.
void | setSelectionColor(Color c) Sets the current color used to render the selection.
void | setSelectionEnd(int selectionEnd) Sets the selection end to the specified position.
void | setSelectionStart(int selectionStart) Sets the selection start to the specified position.
void | setText(String t) Sets the text of this TextComponent to the specified text.
void | setUI(TextUI ui) Sets the user-interface factory for this text-oriented editor.
void | updateUI() Reloads the pluggable UI.
int | viewToModel(Point pt) Converts the given place in the view coordinate system to the nearest representative location in the model.
void | write(Writer out) Stores the contents of the model into the given stream.
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

FOCUS_ACCELERATOR_KEY

public static final String FOCUS_ACCELERATOR_KEY
The bound property name for the focus accelerator.

See Also:
Constant Field Values

DEFAULT_KEYMAP

public static final String DEFAULT_KEYMAP
The default keymap that will be shared by all JTextComponent instances unless they have had a different keymap set.

See Also:
Constant Field Values
Constructor Detail

JTextComponent

public JTextComponent()
Creates a new JTextComponent. Listeners for caret events are established, and the pluggable UI installed. The component is marked as editable. No layout manager is used, because layout is managed by the view subsystem of text. The document model is set to null.

Method Detail

getUI

public TextUI getUI()
Fetches the user-interface factory for this text-oriented editor.

Returns:
the factory

setUI

public void setUI(TextUI ui)
Sets the user-interface factory for this text-oriented editor.

Parameters:
ui - the factory

updateUI

public void updateUI()
Reloads the pluggable UI. The key used to fetch the new interface is getUIClassID(). The type of the UI is TextUI. invalidate is called after setting the UI.

Overrides:
updateUI in class JComponent
See Also:
JComponent.setUI(javax.swing.plaf.ComponentUI),
UIManager.getLookAndFeel(),
UIManager.getUI(javax.swing.JComponent)

addCaretListener

public void addCaretListener(CaretListener listener)
Adds a caret listener for notification of any changes to the caret.

Parameters:
listener - the listener to be added
See Also:
CaretEvent

removeCaretListener

public void removeCaretListener(CaretListener listener)
Removes a caret listener.

Parameters:
listener - the listener to be removed
See Also:
CaretEvent

getCaretListeners

public CaretListener[] getCaretListeners()
Returns an array of all the caret listeners registered on this text component.

Returns:
all of this component's CaretListeners or an empty array if no caret listeners are currently registered
Since:
1.4
See Also:
addCaretListener(javax.swing.event.CaretListener), removeCaretListener(javax.swing.event.CaretListener)

fireCaretUpdate

protected void fireCaretUpdate(CaretEvent e)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method. The listener list is processed in a last-to-first manner.

Parameters:
e - the event
See Also:
EventListenerList

setDocument

public void setDocument(Document doc)
Associates the editor with a text document. The currently registered factory is used to build a view for the document, which gets displayed by the editor after revalidation. A PropertyChange event ("document") is propagated to each listener.

Parameters:
doc - the document to display/edit
See Also:
getDocument()

getDocument

public Document getDocument()
Fetches the model associated with the editor. This is primarily for the UI to get at the minimal amount of state required to be a text editor. Subclasses will return the actual type of the model which will typically be something that extends Document.

Returns:
the model

setComponentOrientation

public void setComponentOrientation(ComponentOrientation o)
Description copied from class: Component
Sets the language-sensitive orientation that is to be used to order the elements or text within this component. Language-sensitive LayoutManager and Component subclasses will use this property to determine how to lay out and draw components.

At construction time, a component's orientation is set to ComponentOrientation.UNKNOWN, indicating that it has not been specified explicitly. The UNKNOWN orientation behaves the same as ComponentOrientation.LEFT_TO_RIGHT.

To set the orientation of a single component, use this method. To set the orientation of an entire component hierarchy, use applyComponentOrientation.

Overrides:
setComponentOrientation in class Component
See Also:
ComponentOrientation

getActions

public Action[] getActions()
Fetches the command list for the editor. This is the list of commands supported by the plugged-in UI augmented by the collection of commands that the editor itself supports. These are useful for binding to events, such as in a keymap.

Returns:
the command list

setMargin

public void setMargin(Insets m)
Sets margin space between the text component's border and its text. The text component's default Border object will use this value to create the proper margin. However, if a non-default border is set on the text component, it is that Border object's responsibility to create the appropriate margin space (else this property will effectively be ignored). This causes a redraw of the component. A PropertyChange event ("margin") is sent to all listeners.

Parameters:
m - the space between the border and the text

getMargin

public Insets getMargin()
Returns the margin between the text component's border and its text.

Returns:
the margin

setNavigationFilter

public void setNavigationFilter(NavigationFilter filter)
Sets the NavigationFilter. NavigationFilter is used by DefaultCaret and the default cursor movement actions as a way to restrict the cursor movement.

Since:
1.4

getNavigationFilter

public NavigationFilter getNavigationFilter()
Returns the NavigationFilter. NavigationFilter is used by DefaultCaret and the default cursor movement actions as a way to restrict the cursor movement. A null return value implies the cursor movement and selection should not be restricted.

Returns:
the NavigationFilter
Since:
1.4

getCaret

public Caret getCaret()
Fetches the caret that allows text-oriented navigation over the view.

Returns:
the caret

setCaret

public void setCaret(Caret c)
Sets the caret to be used. By default this will be set by the UI that gets installed. This can be changed to a custom caret if desired. Setting the caret results in a PropertyChange event ("caret") being fired.

Parameters:
c - the caret
See Also:
getCaret()

getHighlighter

public Highlighter getHighlighter()
Fetches the object responsible for making highlights.

Returns:
the highlighter

setHighlighter

public void setHighlighter(Highlighter h)
Sets the highlighter to be used. By default this will be set by the UI that gets installed. This can be changed to a custom highlighter if desired. The highlighter can be set to null to disable it. A PropertyChange event ("highlighter") is fired when a new highlighter is installed.

Parameters:
h - the highlighter
See Also:
getHighlighter()

setKeymap

public void setKeymap(Keymap map)
Sets the keymap to use for binding events to actions. Setting to null effectively disables keyboard input. A PropertyChange event ("keymap") is fired when a new keymap is installed.

Parameters:
map - the keymap
See Also:
getKeymap()

setDragEnabled

public void setDragEnabled(boolean b)
Turns on or off automatic drag handling. In order to enable automatic drag handling, this property should be set to true, and the component's TransferHandler needs to be non-null. The default value of the dragEnabled property is false.

The job of honoring this property, and recognizing a user drag gesture, lies with the look and feel implementation, and in particular, the component's TextUI. When automatic drag handling is enabled, most look and feels (including those that subclass BasicLookAndFeel) begin a drag and drop operation whenever the user presses the mouse button over a selection and then moves the mouse a few pixels. Setting this property to true can therefore have a subtle effect on how selections behave.

If a look and feel is used that ignores this property, you can still begin a drag and drop operation by calling exportAsDrag on the component's TransferHandler.

Parameters:
b - whether or not to enable automatic drag handling
Throws:
HeadlessException - if b is true and GraphicsEnvironment.isHeadless() returns true
Since:
1.4
See Also:
GraphicsEnvironment.isHeadless(),
getDragEnabled(),
JComponent.setTransferHandler(javax.swing.TransferHandler),
TransferHandler

getDragEnabled

public boolean getDragEnabled()
Returns whether or not automatic drag handling is enabled.

Returns:
the value of the dragEnabled property
Since:
1.4
See Also:
setDragEnabled(boolean)

setDropMode

public final void setDropMode(DropMode dropMode)
Sets the drop mode for this component. For backward compatibility, the default for this property is DropMode.USE_SELECTION. Usage of DropMode.INSERT is recommended, however, for an improved user experience. It offers similar behavior of dropping between text locations, but does so without affecting the actual text selection and caret location.

JTextComponents support the following drop modes:

  • DropMode.USE_SELECTION
  • DropMode.INSERT

The drop mode is only meaningful if this component has a TransferHandler that accepts drops.

Parameters:
dropMode - the drop mode to use
Throws:
IllegalArgumentException - if the drop mode is unsupported or null
Since:
1.6
See Also:
getDropMode(),
getDropLocation(),
JComponent.setTransferHandler(javax.swing.TransferHandler),
TransferHandler

getDropMode

public final DropMode getDropMode()
Returns the drop mode for this component.

Returns:
the drop mode for this component
Since:
1.6
See Also:
setDropMode(javax.swing.DropMode)

getDropLocation

public final JTextComponent.DropLocation getDropLocation()
Returns the location that this component should visually indicate as the drop location during a DnD operation over the component, or null if no location is to currently be shown.

This method is not meant for querying the drop location from a TransferHandler, as the drop location is only set after the TransferHandler's canImport has returned and has allowed for the location to be shown.

When this property changes, a property change event with name "dropLocation" is fired by the component.

Returns:
the drop location
Since:
1.6
See Also:
setDropMode(javax.swing.DropMode), TransferHandler.canImport(TransferHandler.TransferSupport)

getKeymap

public Keymap getKeymap()
Fetches the keymap currently active in this text component.

Returns:
the keymap

addKeymap

public static Keymap addKeymap(String nm,
                               Keymap parent)
Adds a new keymap into the keymap hierarchy. Keymap bindings resolve from bottom up so an attribute specified in a child will override an attribute specified in the parent.

Parameters:
nm - the name of the keymap (must be unique within the collection of named keymaps in the document); the name may be null if the keymap is unnamed, but the caller is responsible for managing the reference returned as an unnamed keymap can't be fetched by name
parent - the parent keymap; this may be null if unspecified bindings need not be resolved in some other keymap
Returns:
the keymap

removeKeymap

public static Keymap removeKeymap(String nm)
Removes a named keymap previously added to the document. Keymaps with null names may not be removed in this way.

Parameters:
nm - the name of the keymap to remove
Returns:
the keymap that was removed

getKeymap

public static Keymap getKeymap(String nm)
Fetches a named keymap previously added to the document. This does not work with null-named keymaps.

Parameters:
nm - the name of the keymap
Returns:
the keymap

loadKeymap

public static void loadKeymap(Keymap map,
                              JTextComponent.KeyBinding[] bindings,
                              Action[] actions)

Loads a keymap with a bunch of bindings. This can be used to take a static table of definitions and load them into some keymap. The following example illustrates an example of binding some keys to the cut, copy, and paste actions associated with a JTextComponent. A code fragment to accomplish this might look as follows:

   static final JTextComponent.KeyBinding[] defaultBindings = {
     new JTextComponent.KeyBinding(
       KeyStroke.getKeyStroke(KeyEvent.VK_C, InputEvent.CTRL_MASK),
       DefaultEditorKit.copyAction),
     new JTextComponent.KeyBinding(
       KeyStroke.getKeyStroke(KeyEvent.VK_V, InputEvent.CTRL_MASK),
       DefaultEditorKit.pasteAction),
     new JTextComponent.KeyBinding(
       KeyStroke.getKeyStroke(KeyEvent.VK_X, InputEvent.CTRL_MASK),
       DefaultEditorKit.cutAction),
   };

   JTextComponent c = new JTextPane();
   Keymap k = c.getKeymap();
   JTextComponent.loadKeymap(k, defaultBindings, c.getActions());
The sets of bindings and actions may be empty but must be non-null.

Parameters:
map - the keymap
bindings - the bindings
actions - the set of actions

getCaretColor

public Color getCaretColor()
Fetches the current color used to render the caret.

Returns:
the color

setCaretColor

public void setCaretColor(Color c)
Sets the current color used to render the caret. Setting to null effectively restores the default color. Setting the color results in a PropertyChange event ("caretColor") being fired.

Parameters:
c - the color
See Also:
getCaretColor()

getSelectionColor

public Color getSelectionColor()
Fetches the current color used to render the selection.

Returns:
the color

setSelectionColor

public void setSelectionColor(Color c)
Sets the current color used to render the selection. Setting the color to null is the same as setting Color.white. Setting the color results in a PropertyChange event ("selectionColor").

Parameters:
c - the color
See Also:
getSelectionColor()

getSelectedTextColor

public Color getSelectedTextColor()
Fetches the current color used to render the selected text.

Returns:
the color

setSelectedTextColor

public void setSelectedTextColor(Color c)
Sets the current color used to render the selected text. Setting the color to null is the same as Color.black. Setting the color results in a PropertyChange event ("selectedTextColor") being fired.

Parameters:
c - the color
See Also:
getSelectedTextColor()

getDisabledTextColor

public Color getDisabledTextColor()
Fetches the current color used to render the disabled text.

Returns:
the color

setDisabledTextColor

public void setDisabledTextColor(Color c)
Sets the current color used to render the disabled text. Setting the color fires off a PropertyChange event ("disabledTextColor").

Parameters:
c - the color
See Also:
getDisabledTextColor()

replaceSelection

public void replaceSelection(String content)
Replaces the currently selected content with new content represented by the given string. If there is no selection this amounts to an insert of the given text. If there is no replacement text this amounts to a removal of the current selection.

This is the method that is used by the default implementation of the action for inserting content that gets bound to the keymap actions.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Parameters:
content - the content to replace the selection with

getText

public String getText(int offs,
                      int len)
               throws BadLocationException
Fetches a portion of the text represented by the component. Returns an empty string if length is 0.

Parameters:
offs - the offset >= 0
len - the length >= 0
Returns:
the text
Throws:
BadLocationException - if the offset or length are invalid

modelToView

public Rectangle modelToView(int pos)
                      throws BadLocationException
Converts the given location in the model to a place in the view coordinate system. The component must have a positive size for this translation to be computed (i.e. layout cannot be computed until the component has been sized). The component does not have to be visible or painted.

Parameters:
pos - the position >= 0
Returns:
the coordinates as a rectangle, with (r.x, r.y) as the location in the coordinate system, or null if the component does not yet have a positive size.
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
See Also:
TextUI.modelToView(javax.swing.text.JTextComponent, int)

viewToModel

public int viewToModel(Point pt)
Converts the given place in the view coordinate system to the nearest representative location in the model. The component must have a positive size for this translation to be computed (i.e. layout cannot be computed until the component has been sized). The component does not have to be visible or painted.

Parameters:
pt - the location in the view to translate
Returns:
the offset >= 0 from the start of the document, or -1 if the component does not yet have a positive size.
See Also:
TextUI.viewToModel(javax.swing.text.JTextComponent, java.awt.Point)

cut

public void cut()
Transfers the currently selected range in the associated text model to the system clipboard, removing the contents from the model. The current selection is reset. Does nothing for null selections.

See Also:
Toolkit.getSystemClipboard(), Clipboard

copy

public void copy()
Transfers the currently selected range in the associated text model to the system clipboard, leaving the contents in the text model. The current selection remains intact. Does nothing for null selections.

See Also:
Toolkit.getSystemClipboard(), Clipboard

paste

public void paste()
Transfers the contents of the system clipboard into the associated text model. If there is a selection in the associated view, it is replaced with the contents of the clipboard. If there is no selection, the clipboard contents are inserted in front of the current insert position in the associated view. If the clipboard is empty, does nothing.

See Also:
replaceSelection(java.lang.String), Toolkit.getSystemClipboard(), Clipboard

moveCaretPosition

public void moveCaretPosition(int pos)
Moves the caret to a new position, leaving behind a mark defined by the last time setCaretPosition was called. This forms a selection. If the document is null, does nothing. The position must be between 0 and the length of the component's text or else an exception is thrown.

Parameters:
pos - the position
Throws:
IllegalArgumentException - if the value supplied for position is less than zero or greater than the component's text length
See Also:
setCaretPosition(int)

setFocusAccelerator

public void setFocusAccelerator(char aKey)
Sets the key accelerator that will cause the receiving text component to get the focus. The accelerator will be the key combination of the alt key and the character given (converted to upper case). By default, there is no focus accelerator key. Any previous key accelerator setting will be superseded. A '\0' key setting will be registered, and has the effect of turning off the focus accelerator. When the new key is set, a PropertyChange event (FOCUS_ACCELERATOR_KEY) will be fired.

Parameters:
aKey - the key
See Also:
getFocusAccelerator()

getFocusAccelerator

public char getFocusAccelerator()
Returns the key accelerator that will cause the receiving text component to get the focus. Return '\0' if no focus accelerator has been set.

Returns:
the key

read

public void read(Reader in,
                 Object desc)
          throws IOException
Initializes from a stream. This creates a model of the type appropriate for the component and initializes the model from the stream. By default this will load the model as plain text. Previous contents of the model are discarded.

Parameters:
in - the stream to read from
desc - an object describing the stream; this might be a string, a File, a URL, etc. Some kinds of documents (such as html for example) might be able to make use of this information; if non-null, it is added as a property of the document
Throws:
IOException - as thrown by the stream being used to initialize
See Also:
EditorKit.createDefaultDocument(), setDocument(javax.swing.text.Document), PlainDocument

write

public void write(Writer out)
           throws IOException
Stores the contents of the model into the given stream. By default this will store the model as plain text.

Parameters:
out - the output stream
Throws:
IOException - on any I/O error

removeNotify

public void removeNotify()
Description copied from class: JComponent
Notifies this component that it no longer has a parent component. When this method is invoked, any KeyboardActions set up in the the chain of parent components are removed.

Overrides:
removeNotify in class JComponent
See Also:
JComponent.registerKeyboardAction(java.awt.event.ActionListener, java.lang.String, javax.swing.KeyStroke, int)

setCaretPosition

public void setCaretPosition(int position)
Sets the position of the text insertion caret for the TextComponent. Note that the caret tracks change, so this may move if the underlying text of the component is changed. If the document is null, does nothing. The position must be between 0 and the length of the component's text or else an exception is thrown.

Parameters:
position - the position
Throws:
IllegalArgumentException - if the value supplied for position is less than zero or greater than the component's text length

getCaretPosition

public int getCaretPosition()
Returns the position of the text insertion caret for the text component.

Returns:
the position of the text insertion caret for the text component >= 0

setText

public void setText(String t)
Sets the text of this TextComponent to the specified text. If the text is null or empty, has the effect of simply deleting the old text. When text has been inserted, the resulting caret location is determined by the implementation of the caret class.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information. Note that text is not a bound property, so no PropertyChangeEvent is fired when it changes. To listen for changes to the text, use DocumentListener.

Parameters:
t - the new text to be set
See Also:
getText(int, int), DefaultCaret

getText

public String getText()
Returns the text contained in this TextComponent. If the underlying document is null, will give a NullPointerException. Note that text is not a bound property, so no PropertyChangeEvent is fired when it changes. To listen for changes to the text, use DocumentListener.

Returns:
the text
Throws:
NullPointerException - if the document is null
See Also:
setText(java.lang.String)

getSelectedText

public String getSelectedText()
Returns the selected text contained in this TextComponent. If the selection is null or the document empty, returns null.

Returns:
the text
Throws:
IllegalArgumentException - if the selection doesn't have a valid mapping into the document for some reason
See Also:
setText(java.lang.String)

isEditable

public boolean isEditable()
Returns the boolean indicating whether this TextComponent is editable or not.

Returns:
the boolean value
See Also:
setEditable(boolean)

setEditable

public void setEditable(boolean b)
Sets the specified boolean to indicate whether or not this TextComponent should be editable. A PropertyChange event ("editable") is fired when the state is changed.

Parameters:
b - the boolean to be set
See Also:
isEditable()

getSelectionStart

public int getSelectionStart()
Returns the selected text's start position. Return 0 for an empty document, or the value of dot if no selection.

Returns:
the start position >= 0

setSelectionStart

public void setSelectionStart(int selectionStart)
Sets the selection start to the specified position. The new starting point is constrained to be before or at the current selection end.

This is available for backward compatibility to code that called this method on java.awt.TextComponent. This is implemented to forward to the Caret implementation which is where the actual selection is maintained.

Parameters:
selectionStart - the start position of the text >= 0

getSelectionEnd

public int getSelectionEnd()
Returns the selected text's end position. Return 0 if the document is empty, or the value of dot if there is no selection.

Returns:
the end position >= 0

setSelectionEnd

public void setSelectionEnd(int selectionEnd)
Sets the selection end to the specified position. The new end point is constrained to be at or after the current selection start.

This is available for backward compatibility to code that called this method on java.awt.TextComponent. This is implemented to forward to the Caret implementation which is where the actual selection is maintained.

Parameters:
selectionEnd - the end position of the text >= 0

select

public void select(int selectionStart,
                   int selectionEnd)
Selects the text between the specified start and end positions.

This method sets the start and end positions of the selected text, enforcing the restriction that the start position must be greater than or equal to zero. The end position must be greater than or equal to the start position, and less than or equal to the length of the text component's text.

If the caller supplies values that are inconsistent or out of bounds, the method enforces these constraints silently, and without failure. Specifically, if the start position or end position is greater than the length of the text, it is reset to equal the text length. If the start position is less than zero, it is reset to zero, and if the end position is less than the start position, it is reset to the start position.

This call is provided for backward compatibility. It is routed to a call to setCaretPosition followed by a call to moveCaretPosition. The preferred way to manage selection is by calling those methods directly.

Parameters:
selectionStart - the start position of the text
selectionEnd - the end position of the text
See Also:
setCaretPosition(int), moveCaretPosition(int)

selectAll

public void selectAll()
Selects all the text in the TextComponent. Does nothing on a null or empty document.

getToolTipText

public String getToolTipText(MouseEvent event)
Returns the string to be used as the tooltip for event. This will return one of:
  1. If setToolTipText has been invoked with a non-null value, it will be returned, otherwise
  2. The value from invoking getToolTipText on the UI will be returned.
By default JTextComponent does not register itself with the ToolTipManager. This means that tooltips will NOT be shown from the TextUI unless registerComponent has been invoked on the ToolTipManager.

Overrides:
getToolTipText in class JComponent
Parameters:
event - the event in question
Returns:
the string to be used as the tooltip for event
See Also:
JComponent.setToolTipText(java.lang.String),
TextUI.getToolTipText(javax.swing.text.JTextComponent, java.awt.Point),
ToolTipManager.registerComponent(javax.swing.JComponent)

getPreferredScrollableViewportSize

public Dimension getPreferredScrollableViewportSize()
Returns the preferred size of the viewport for a view component. This is implemented to do the default behavior of returning the preferred size of the component.

Specified by:
getPreferredScrollableViewportSize in interface Scrollable
Returns:
the preferredSize of a JViewport whose view is this Scrollable
See Also:
JComponent.getPreferredSize()

getScrollableUnitIncrement

public int getScrollableUnitIncrement(Rectangle visibleRect,
                                      int orientation,
                                      int direction)
Components that display logical rows or columns should compute the scroll increment that will completely expose one new row or column, depending on the value of orientation. Ideally, components should handle a partially exposed row or column by returning the distance required to completely expose the item.

The default implementation of this is to simply return 10% of the visible area. Subclasses are likely to be able to provide a much more reasonable value.

Specified by:
getScrollableUnitIncrement in interface Scrollable
Parameters:
visibleRect - the view area visible within the viewport
orientation - either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL
direction - less than zero to scroll up/left, greater than zero for down/right
Returns:
the "unit" increment for scrolling in the specified direction
Throws:
IllegalArgumentException - for an invalid orientation
See Also:
JScrollBar.setUnitIncrement(int)

getScrollableBlockIncrement

public int getScrollableBlockIncrement(Rectangle visibleRect,
                                       int orientation,
                                       int direction)
Components that display logical rows or columns should compute the scroll increment that will completely expose one block of rows or columns, depending on the value of orientation.

The default implementation of this is to simply return the visible area. Subclasses will likely be able to provide a much more reasonable value.

Specified by:
getScrollableBlockIncrement in interface Scrollable
Parameters:
visibleRect - the view area visible within the viewport
orientation - either SwingConstants.VERTICAL or SwingConstants.HORIZONTAL
direction - less than zero to scroll up/left, greater than zero for down/right
Returns:
the "block" increment for scrolling in the specified direction
Throws:
IllegalArgumentException - for an invalid orientation
See Also:
JScrollBar.setBlockIncrement(int)

getScrollableTracksViewportWidth

public boolean getScrollableTracksViewportWidth()
Returns true if a viewport should always force the width of this Scrollable to match the width of the viewport. For example a normal text view that supported line wrapping would return true here, since it would be undesirable for wrapped lines to disappear beyond the right edge of the viewport. Note that returning true for a Scrollable whose ancestor is a JScrollPane effectively disables horizontal scrolling.

Scrolling containers, like JViewport, will use this method each time they are validated.

Specified by:
getScrollableTracksViewportWidth in interface Scrollable
Returns:
true if a viewport should force the Scrollables width to match its own

getScrollableTracksViewportHeight

public boolean getScrollableTracksViewportHeight()
Returns true if a viewport should always force the height of this Scrollable to match the height of the viewport. For example a columnar text view that flowed text in left to right columns could effectively disable vertical scrolling by returning true here.

Scrolling containers, like JViewport, will use this method each time they are validated.

Specified by:
getScrollableTracksViewportHeight in interface Scrollable
Returns:
true if a viewport should force the Scrollables height to match its own

print

public boolean print()
              throws PrinterException
A convenience print method that displays a print dialog, and then prints this JTextComponent in interactive mode with no header or footer text. Note: this method blocks until printing is done.

Note: In headless mode, no dialogs will be shown.

This method calls the full featured print method to perform printing.

Returns:
true, unless printing is canceled by the user
Throws:
PrinterException - if an error in the print system causes the job to be aborted
SecurityException - if this thread is not allowed to initiate a print job request
Since:
1.6
See Also:
print(MessageFormat, MessageFormat, boolean, PrintService, PrintRequestAttributeSet, boolean)

print

public boolean print(MessageFormat headerFormat,
                     MessageFormat footerFormat)
              throws PrinterException
A convenience print method that displays a print dialog, and then prints this JTextComponent in interactive mode with the specified header and footer text. Note: this method blocks until printing is done.

Note: In headless mode, no dialogs will be shown.

This method calls the full featured print method to perform printing.

Parameters:
headerFormat - the text, in MessageFormat, to be used as the header, or null for no header
footerFormat - the text, in MessageFormat, to be used as the footer, or null for no footer
Returns:
true, unless printing is canceled by the user
Throws:
PrinterException - if an error in the print system causes the job to be aborted
SecurityException - if this thread is not allowed to initiate a print job request
Since:
1.6
See Also:
print(MessageFormat, MessageFormat, boolean, PrintService, PrintRequestAttributeSet, boolean), MessageFormat

print

public boolean print(MessageFormat headerFormat,
                     MessageFormat footerFormat,
                     boolean showPrintDialog,
                     PrintService service,
                     PrintRequestAttributeSet attributes,
                     boolean interactive)
              throws PrinterException
Prints the content of this JTextComponent. Note: this method blocks until printing is done.

Page header and footer text can be added to the output by providing MessageFormat arguments. The printing code requests Strings from the formats, providing a single item which may be included in the formatted string: an Integer representing the current page number.

showPrintDialog boolean parameter allows you to specify whether a print dialog is displayed to the user. When it is, the user may use the dialog to change printing attributes or even cancel the print.

service allows you to provide the initial PrintService for the print dialog, or to specify PrintService to print to when the dialog is not shown.

attributes can be used to provide the initial values for the print dialog, or to supply any needed attributes when the dialog is not shown. attributes can be used to control how the job will print, for example duplex or single-sided.

interactive boolean parameter allows you to specify whether to perform printing in interactive mode. If true, a progress dialog, with an abort option, is displayed for the duration of printing. This dialog is modal when print is invoked on the Event Dispatch Thread and non-modal otherwise. Warning: calling this method on the Event Dispatch Thread with interactive false blocks all events, including repaints, from being processed until printing is complete. It is only recommended when printing from an application with no visible GUI.

Note: In headless mode, showPrintDialog and interactive parameters are ignored and no dialogs are shown.

This method ensures the document is not mutated during printing. To indicate it visually, setEnabled(false) is set for the duration of printing.

This method uses getPrintable(java.text.MessageFormat, java.text.MessageFormat) to render document content.

This method is thread-safe, although most Swing methods are not. Please see How to Use Threads for more information.

Sample Usage. This code snippet shows a cross-platform print dialog and then prints the JTextComponent in interactive mode unless the user cancels the dialog:

 textComponent.print(new MessageFormat("My text component header"),
     new MessageFormat("Footer. Page - {0}"), true, null, null, true);

Executing this code off the Event Dispatch Thread performs printing on the background. The following pattern might be used for background printing:

     FutureTask<Boolean> future =
         new FutureTask<Boolean>(
             new Callable<Boolean>() {
                 public Boolean call() {
                     return textComponent.print(.....);
                 }
             });
     executor.execute(future);

Parameters:
headerFormat - the text, in MessageFormat, to be used as the header, or null for no header
footerFormat - the text, in MessageFormat, to be used as the footer, or null for no footer
showPrintDialog - true to display a print dialog, false otherwise
service - initial PrintService, or null for the default
attributes - the job attributes to be applied to the print job, or null for none
interactive - whether to print in an interactive mode
Returns:
true, unless printing is canceled by the user
Throws:
PrinterException - if an error in the print system causes the job to be aborted
SecurityException - if this thread is not allowed to initiate a print job request
Since:
1.6
See Also:
getPrintable(java.text.MessageFormat, java.text.MessageFormat), MessageFormat, GraphicsEnvironment.isHeadless(), FutureTask

getPrintable

public Printable getPrintable(MessageFormat headerFormat,
                              MessageFormat footerFormat)
Returns a Printable to use for printing the content of this JTextComponent. The returned Printable prints the document as it looks on the screen except being reformatted to fit the paper. The returned Printable can be wrapped inside another Printable in order to create complex reports and documents.

The returned Printable shares the document with this JTextComponent. It is the responsibility of the developer to ensure that the document is not mutated while this Printable is used. Printing behavior is undefined when the document is mutated during printing.

Page header and footer text can be added to the output by providing MessageFormat arguments. The printing code requests Strings from the formats, providing a single item which may be included in the formatted string: an Integer representing the current page number.

The returned Printable when printed, formats the document content appropriately for the page size. For correct line wrapping the imageable width of all pages must be the same. See PageFormat.getImageableWidth().

This method is thread-safe, although most Swing methods are not. Please see How to Use Threads for more information.

The returned Printable can be printed on any thread.

This implementation returned Printable performs all painting on the Event Dispatch Thread, regardless of what thread it is used on.

Parameters:
headerFormat - the text, in MessageFormat, to be used as the header, or null for no header
footerFormat - the text, in MessageFormat, to be used as the footer, or null for no footer
Returns:
a Printable for use in printing content of this JTextComponent
Since:
1.6
See Also:
Printable, PageFormat, Document.render(java.lang.Runnable)

getAccessibleContext

public AccessibleContext getAccessibleContext()
Gets the AccessibleContext associated with this JTextComponent. For text components, the AccessibleContext takes the form of an AccessibleJTextComponent. A new AccessibleJTextComponent instance is created if necessary.

Specified by:
getAccessibleContext in interface Accessible
Overrides:
getAccessibleContext in class JComponent
Returns:
an AccessibleJTextComponent that serves as the AccessibleContext of this JTextComponent

paramString

protected String paramString()
Returns a string representation of this JTextComponent. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overriding paramString to provide information about the specific new aspects of the JFC components.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JTextComponent

processInputMethodEvent

protected void processInputMethodEvent(InputMethodEvent e)
Description copied from class: Component
Processes input method events occurring on this component by dispatching them to any registered InputMethodListener objects.

This method is not called unless input method events are enabled for this component. Input method events are enabled when one of the following occurs:

  • An InputMethodListener object is registered via addInputMethodListener.
  • Input method events are enabled via enableEvents.

Note that if the event parameter is null the behavior is unspecified and may result in an exception.

Overrides:
processInputMethodEvent in class Component
Parameters:
e - the input method event
See Also:
InputMethodEvent, InputMethodListener, Component.addInputMethodListener(java.awt.event.InputMethodListener), Component.enableEvents(long)

getInputMethodRequests

public InputMethodRequests getInputMethodRequests()
Description copied from class: Component
Gets the input method request handler which supports requests from input methods for this component. A component that supports on-the-spot text input must override this method to return an InputMethodRequests instance. At the same time, it also has to handle input method events.

Overrides:
getInputMethodRequests in class Component
Returns:
the input method request handler for this component, null by default
See Also:
Component.addInputMethodListener(java.awt.event.InputMethodListener)

addInputMethodListener

public void addInputMethodListener(InputMethodListener l)
Description copied from class: Component
Adds the specified input method listener to receive input method events from this component. A component will only receive input method events from input methods if it also overrides getInputMethodRequests to return an InputMethodRequests instance. If listener l is null, no exception is thrown and no action is performed.

Refer to AWT Threading Issues for details on AWT's threading model.

Overrides:
addInputMethodListener in class Component
Parameters:
l - the input method listener
See Also:
InputMethodEvent,
InputMethodListener,
Component.removeInputMethodListener(java.awt.event.InputMethodListener),
Component.getInputMethodListeners(),
Component.getInputMethodRequests()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTextComponent.AccessibleJTextComponent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class JTextComponent.AccessibleJTextComponent

java.lang.Object
    extended by  javax.accessibility.AccessibleContext
        extended by  java.awt.Component.AccessibleAWTComponent
            extended by  java.awt.Container.AccessibleAWTContainer
                extended by  javax.swing.JComponent.AccessibleJComponent
                    extended by  javax.swing.text.JTextComponent.AccessibleJTextComponent
All Implemented Interfaces:
Serializable, EventListener, AccessibleAction, AccessibleComponent, AccessibleEditableText, AccessibleExtendedComponent, AccessibleExtendedText, AccessibleText, CaretListener, DocumentListener
Direct Known Subclasses:
JEditorPane.AccessibleJEditorPane, JTextArea.AccessibleJTextArea, JTextField.AccessibleJTextField
Enclosing class:
JTextComponent
public class JTextComponent.AccessibleJTextComponent
extends JComponent.AccessibleJComponent
implements AccessibleText, CaretListener, DocumentListener, AccessibleAction, AccessibleEditableText, AccessibleExtendedText

This class implements accessibility support for the JTextComponent class. It provides an implementation of the Java Accessibility API appropriate to menu user-interface elements.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JComponent.AccessibleJComponent
JComponent.AccessibleJComponent.AccessibleContainerHandler, JComponent.AccessibleJComponent.AccessibleFocusHandler
Nested classes/interfaces inherited from class java.awt.Component.AccessibleAWTComponent
Component.AccessibleAWTComponent.AccessibleAWTComponentHandler, Component.AccessibleAWTComponent.AccessibleAWTFocusHandler
Field Summary
Fields inherited from class javax.swing.JComponent.AccessibleJComponent
accessibleContainerHandler, accessibleFocusHandler
Fields inherited from class java.awt.Component.AccessibleAWTComponent
accessibleAWTComponentHandler, accessibleAWTFocusHandler
Fields inherited from class javax.accessibility.AccessibleContext
ACCESSIBLE_ACTION_PROPERTY, ACCESSIBLE_ACTIVE_DESCENDANT_PROPERTY, ACCESSIBLE_CARET_PROPERTY, ACCESSIBLE_CHILD_PROPERTY, ACCESSIBLE_COMPONENT_BOUNDS_CHANGED, ACCESSIBLE_DESCRIPTION_PROPERTY, ACCESSIBLE_HYPERTEXT_OFFSET, ACCESSIBLE_INVALIDATE_CHILDREN, ACCESSIBLE_NAME_PROPERTY, ACCESSIBLE_SELECTION_PROPERTY, ACCESSIBLE_STATE_PROPERTY, ACCESSIBLE_TABLE_CAPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_COLUMN_HEADER_CHANGED, ACCESSIBLE_TABLE_MODEL_CHANGED, ACCESSIBLE_TABLE_ROW_DESCRIPTION_CHANGED, ACCESSIBLE_TABLE_ROW_HEADER_CHANGED, ACCESSIBLE_TABLE_SUMMARY_CHANGED, ACCESSIBLE_TEXT_ATTRIBUTES_CHANGED, ACCESSIBLE_TEXT_PROPERTY, ACCESSIBLE_VALUE_PROPERTY, ACCESSIBLE_VISIBLE_DATA_PROPERTY, accessibleDescription, accessibleName, accessibleParent
Fields inherited from interface javax.accessibility.AccessibleAction
CLICK, DECREMENT, INCREMENT, TOGGLE_EXPAND, TOGGLE_POPUP
Fields inherited from interface javax.accessibility.AccessibleText
CHARACTER, SENTENCE, WORD
Fields inherited from interface javax.accessibility.AccessibleExtendedText
ATTRIBUTE_RUN, LINE
Constructor Summary
JTextComponent.AccessibleJTextComponent()
Constructs an AccessibleJTextComponent.
Method Summary
void | caretUpdate(CaretEvent e) Handles caret updates (fire appropriate property change event, which are AccessibleContext.ACCESSIBLE_CARET_PROPERTY and AccessibleContext.ACCESSIBLE_SELECTION_PROPERTY).
void | changedUpdate(DocumentEvent e) Handles document remove (fire appropriate property change event, which is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY).
void | cut(int startIndex, int endIndex) Cuts the text between two indices into the system clipboard.
void | delete(int startIndex, int endIndex) Deletes the text between two indices
boolean | doAccessibleAction(int i) Performs the specified Action on the object
AccessibleAction | getAccessibleAction() Gets the AccessibleAction associated with this object that supports one or more actions.
int | getAccessibleActionCount() Returns the number of accessible actions available in this object If there are more than one, the first one is considered the "default" action of the object.
String | getAccessibleActionDescription(int i) Returns a description of the specified action of the object.
AccessibleEditableText | getAccessibleEditableText() Returns the AccessibleEditableText interface for this text component.
AccessibleRole | getAccessibleRole() Gets the role of this object.
AccessibleStateSet | getAccessibleStateSet() Gets the state set of the JTextComponent.
AccessibleText | getAccessibleText() Get the AccessibleText associated with this object.
String | getAfterIndex(int part, int index) Returns the String after a given index.
String | getAtIndex(int part, int index) Returns the String at a given index.
String | getBeforeIndex(int part, int index) Returns the String before a given index.
int | getCaretPosition() Returns the zero-based offset of the caret.
AttributeSet | getCharacterAttribute(int i) Returns the AttributeSet for a given character (at a given index).
Rectangle | getCharacterBounds(int i) Determines the bounding box of the character at the given index into the string.
int | getCharCount() Returns the number of characters (valid indices)
int | getIndexAtPoint(Point p) Given a point in local coordinates, return the zero-based index of the character under that Point.
String | getSelectedText() Returns the portion of the text that is selected.
int | getSelectionEnd() Returns the end offset within the selected text.
int | getSelectionStart() Returns the start offset within the selected text.
Rectangle | getTextBounds(int startIndex, int endIndex) Returns the Rectangle enclosing the text between two indicies.
String | getTextRange(int startIndex, int endIndex) Returns the text string between two indices.
AccessibleTextSequence | getTextSequenceAfter(int part, int index) Returns the AccessibleTextSequence after a given index.
AccessibleTextSequence | getTextSequenceAt(int part, int index) Returns the AccessibleTextSequence at a given index.
AccessibleTextSequence | getTextSequenceBefore(int part, int index) Returns the AccessibleTextSequence before a given index.
void | insertTextAtIndex(int index, String s) Inserts the specified string at the given index
void | insertUpdate(DocumentEvent e) Handles document insert (fire appropriate property change event which is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY).
void | paste(int startIndex) Pastes the text from the system clipboard into the text starting at the specified index.
void | removeUpdate(DocumentEvent e) Handles document remove (fire appropriate property change event, which is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY).
void | replaceText(int startIndex, int endIndex, String s) Replaces the text between two indices with the specified string.
void | selectText(int startIndex, int endIndex) Selects the text between two indices.
void | setAttributes(int startIndex, int endIndex, AttributeSet as) Sets attributes for the text between two indices.
void | setTextContents(String s) Sets the text contents to the specified string.
Methods inherited from class javax.swing.JComponent.AccessibleJComponent
addPropertyChangeListener, getAccessibleChild, getAccessibleChildrenCount, getAccessibleDescription, getAccessibleKeyBinding, getAccessibleName, getBorderTitle, getTitledBorderText, getToolTipText, removePropertyChangeListener
Methods inherited from class java.awt.Container.AccessibleAWTContainer
getAccessibleAt
Methods inherited from class java.awt.Component.AccessibleAWTComponent
addFocusListener, contains, getAccessibleComponent, getAccessibleIndexInParent, getAccessibleParent, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocale, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible
Methods inherited from class javax.accessibility.AccessibleContext
firePropertyChange, getAccessibleIcon, getAccessibleRelationSet, getAccessibleSelection, getAccessibleTable, getAccessibleValue, setAccessibleDescription, setAccessibleName, setAccessibleParent
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.accessibility.AccessibleComponent
addFocusListener, contains, getAccessibleAt, getBackground, getBounds, getCursor, getFont, getFontMetrics, getForeground, getLocation, getLocationOnScreen, getSize, isEnabled, isFocusTraversable, isShowing, isVisible, removeFocusListener, requestFocus, setBackground, setBounds, setCursor, setEnabled, setFont, setForeground, setLocation, setSize, setVisible

Constructor Detail

JTextComponent.AccessibleJTextComponent

public JTextComponent.AccessibleJTextComponent()
Constructs an AccessibleJTextComponent. Adds a listener to track caret change.

Method Detail

caretUpdate

public void caretUpdate(CaretEvent e)
Handles caret updates (fire appropriate property change event, which are AccessibleContext.ACCESSIBLE_CARET_PROPERTY and AccessibleContext.ACCESSIBLE_SELECTION_PROPERTY). This keeps track of the dot position internally. When the caret moves, the internal position is updated after firing the event.

Specified by:
caretUpdate in interface CaretListener
Parameters:
e - the CaretEvent

insertUpdate

public void insertUpdate(DocumentEvent e)
Handles document insert (fire appropriate property change event which is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY). This tracks the changed offset via the event.

Specified by:
insertUpdate in interface DocumentListener
Parameters:
e - the DocumentEvent

removeUpdate

public void removeUpdate(DocumentEvent e)
Handles document remove (fire appropriate property change event, which is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY). This tracks the changed offset via the event.

Specified by:
removeUpdate in interface DocumentListener
Parameters:
e - the DocumentEvent

changedUpdate

public void changedUpdate(DocumentEvent e)
Handles document remove (fire appropriate property change event, which is AccessibleContext.ACCESSIBLE_TEXT_PROPERTY). This tracks the changed offset via the event.

Specified by:
changedUpdate in interface DocumentListener
Parameters:
e - the DocumentEvent

getAccessibleStateSet

public AccessibleStateSet getAccessibleStateSet()
Gets the state set of the JTextComponent. The AccessibleStateSet of an object is composed of a set of unique AccessibleState's. A change in the AccessibleStateSet of an object will cause a PropertyChangeEvent to be fired for the AccessibleContext.ACCESSIBLE_STATE_PROPERTY property.

Overrides:
getAccessibleStateSet in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleStateSet containing the current state set of the object
See Also:
AccessibleStateSet, AccessibleState, JComponent.AccessibleJComponent.addPropertyChangeListener(java.beans.PropertyChangeListener)

getAccessibleRole

public AccessibleRole getAccessibleRole()
Gets the role of this object.

Overrides:
getAccessibleRole in class JComponent.AccessibleJComponent
Returns:
an instance of AccessibleRole describing the role of the object (AccessibleRole.TEXT)
See Also:
AccessibleRole

getAccessibleText

public AccessibleText getAccessibleText()
Get the AccessibleText associated with this object. In the implementation of the Java Accessibility API for this class, return this object, which is responsible for implementing the AccessibleText interface on behalf of itself.

Overrides:
getAccessibleText in class AccessibleContext
Returns:
this object
See Also:
AccessibleText

getIndexAtPoint

public int getIndexAtPoint(Point p)
Given a point in local coordinates, return the zero-based index of the character under that Point. If the point is invalid, this method returns -1.

Specified by:
getIndexAtPoint in interface AccessibleText
Parameters:
p - the Point in local coordinates
Returns:
the zero-based index of the character under Point p.

getCharacterBounds

public Rectangle getCharacterBounds(int i)
Determines the bounding box of the character at the given index into the string. The bounds are returned in local coordinates. If the index is invalid a null rectangle is returned. The screen coordinates returned are "unscrolled coordinates" if the JTextComponent is contained in a JScrollPane in which case the resulting rectangle should be composed with the parent coordinates. A good algorithm to use is: Accessible a: AccessibleText at = a.getAccessibleText(); AccessibleComponent ac = a.getAccessibleComponent(); Rectangle r = at.getCharacterBounds(); Point p = ac.getLocation(); r.x += p.x; r.y += p.y; Note: the JTextComponent must have a valid size (e.g. have been added to a parent container whose ancestor container is a valid top-level window) for this method to be able to return a meaningful (non-null) value.

Specified by:
getCharacterBounds in interface AccessibleText
Parameters:
i - the index into the String >= 0
Returns:
the screen coordinates of the character's bounding box

getCharCount

public int getCharCount()
Returns the number of characters (valid indices)

Specified by:
getCharCount in interface AccessibleText
Returns:
the number of characters >= 0

getCaretPosition

public int getCaretPosition()
Returns the zero-based offset of the caret. Note: The character to the right of the caret will have the same index value as the offset (the caret is between two characters).

Specified by:
getCaretPosition in interface AccessibleText
Returns:
the zero-based offset of the caret.

getCharacterAttribute

public AttributeSet getCharacterAttribute(int i)
Returns the AttributeSet for a given character (at a given index).

Specified by:
getCharacterAttribute in interface AccessibleText
Parameters:
i - the zero-based index into the text
Returns:
the AttributeSet of the character

getSelectionStart

public int getSelectionStart()
Returns the start offset within the selected text. If there is no selection, but there is a caret, the start and end offsets will be the same. Return 0 if the text is empty, or the caret position if no selection.

Specified by:
getSelectionStart in interface AccessibleText
Returns:
the index into the text of the start of the selection >= 0

getSelectionEnd

public int getSelectionEnd()
Returns the end offset within the selected text. If there is no selection, but there is a caret, the start and end offsets will be the same. Return 0 if the text is empty, or the caret position if no selection.

Specified by:
getSelectionEnd in interface AccessibleText
Returns:
the index into teh text of the end of the selection >= 0

getSelectedText

public String getSelectedText()
Returns the portion of the text that is selected.

Specified by:
getSelectedText in interface AccessibleText
Returns:
the text, null if no selection

getAtIndex

public String getAtIndex(int part,
                         int index)
Returns the String at a given index. Whitespace between words is treated as a word.

Specified by:
getAtIndex in interface AccessibleText
Parameters:
part - the CHARACTER, WORD, or SENTENCE to retrieve
index - an index within the text
Returns:
the letter, word, or sentence.

getAfterIndex

public String getAfterIndex(int part,
                            int index)
Returns the String after a given index. Whitespace between words is treated as a word.

Specified by:
getAfterIndex in interface AccessibleText
Parameters:
part - the CHARACTER, WORD, or SENTENCE to retrieve
index - an index within the text
Returns:
the letter, word, or sentence.

getBeforeIndex

public String getBeforeIndex(int part,
                             int index)
Returns the String before a given index. Whitespace between words is treated a word.

Specified by:
getBeforeIndex in interface AccessibleText
Parameters:
part - the CHARACTER, WORD, or SENTENCE to retrieve
index - an index within the text
Returns:
the letter, word, or sentence.

getAccessibleEditableText

public AccessibleEditableText getAccessibleEditableText()
Returns the AccessibleEditableText interface for this text component.

Overrides:
getAccessibleEditableText in class AccessibleContext
Returns:
the AccessibleEditableText interface
Since:
1.4
See Also:
AccessibleEditableText

setTextContents

public void setTextContents(String s)
Sets the text contents to the specified string.

Specified by:
setTextContents in interface AccessibleEditableText
Parameters:
s - the string to set the text contents
Since:
1.4

insertTextAtIndex

public void insertTextAtIndex(int index,
                              String s)
Inserts the specified string at the given index

Specified by:
insertTextAtIndex in interface AccessibleEditableText
Parameters:
index - the index in the text where the string will be inserted
s - the string to insert in the text
Since:
1.4

getTextRange

public String getTextRange(int startIndex,
                           int endIndex)
Returns the text string between two indices.

Specified by:
getTextRange in interface AccessibleEditableText
Specified by:
getTextRange in interface AccessibleExtendedText
Parameters:
startIndex - the starting index in the text
endIndex - the ending index in the text
Returns:
the text string between the indices
Since:
1.4

delete

public void delete(int startIndex,
                   int endIndex)
Deletes the text between two indices

Specified by:
delete in interface AccessibleEditableText
Parameters:
startIndex - the starting index in the text
endIndex - the ending index in the text
Since:
1.4

cut

public void cut(int startIndex,
                int endIndex)
Cuts the text between two indices into the system clipboard.

Specified by:
cut in interface AccessibleEditableText
Parameters:
startIndex - the starting index in the text
endIndex - the ending index in the text
Since:
1.4

paste

public void paste(int startIndex)
Pastes the text from the system clipboard into the text starting at the specified index.

Specified by:
paste in interface AccessibleEditableText
Parameters:
startIndex - the starting index in the text
Since:
1.4

replaceText

public void replaceText(int startIndex,
                        int endIndex,
                        String s)
Replaces the text between two indices with the specified string.

Specified by:
replaceText in interface AccessibleEditableText
Parameters:
startIndex - the starting index in the text
endIndex - the ending index in the text
s - the string to replace the text between two indices
Since:
1.4

selectText

public void selectText(int startIndex,
                       int endIndex)
Selects the text between two indices.

Specified by:
selectText in interface AccessibleEditableText
Parameters:
startIndex - the starting index in the text
endIndex - the ending index in the text
Since:
1.4

setAttributes

public void setAttributes(int startIndex,
                          int endIndex,
                          AttributeSet as)
Sets attributes for the text between two indices.

Specified by:
setAttributes in interface AccessibleEditableText
Parameters:
startIndex - the starting index in the text
endIndex - the ending index in the text
as - the attribute set
Since:
1.4
See Also:
AttributeSet

getTextSequenceAt

public AccessibleTextSequence getTextSequenceAt(int part,
                                                int index)
Returns the AccessibleTextSequence at a given index.

Specified by:
getTextSequenceAt in interface AccessibleExtendedText
Parameters:
part - the CHARACTER, WORD, SENTENCE, LINE or ATTRIBUTE_RUN to retrieve
index - an index within the text
Returns:
an AccessibleTextSequence specifying the text if part and index are valid. Otherwise, null is returned
Since:
1.6
See Also:
AccessibleText.CHARACTER, AccessibleText.WORD, AccessibleText.SENTENCE, AccessibleExtendedText.LINE, AccessibleExtendedText.ATTRIBUTE_RUN

getTextSequenceAfter

public AccessibleTextSequence getTextSequenceAfter(int part,
                                                   int index)
Returns the AccessibleTextSequence after a given index.

Specified by:
getTextSequenceAfter in interface AccessibleExtendedText
Parameters:
part - the CHARACTER, WORD, SENTENCE, LINE or ATTRIBUTE_RUN to retrieve
index - an index within the text
Returns:
an AccessibleTextSequence specifying the text if part and index are valid. Otherwise, null is returned
Since:
1.6
See Also:
AccessibleText.CHARACTER, AccessibleText.WORD, AccessibleText.SENTENCE, AccessibleExtendedText.LINE, AccessibleExtendedText.ATTRIBUTE_RUN

getTextSequenceBefore

public AccessibleTextSequence getTextSequenceBefore(int part,
                                                    int index)
Returns the AccessibleTextSequence before a given index.

Specified by:
getTextSequenceBefore in interface AccessibleExtendedText
Parameters:
part - the CHARACTER, WORD, SENTENCE, LINE or ATTRIBUTE_RUN to retrieve
index - an index within the text
Returns:
an AccessibleTextSequence specifying the text if part and index are valid. Otherwise, null is returned
Since:
1.6
See Also:
AccessibleText.CHARACTER, AccessibleText.WORD, AccessibleText.SENTENCE, AccessibleExtendedText.LINE, AccessibleExtendedText.ATTRIBUTE_RUN

getTextBounds

public Rectangle getTextBounds(int startIndex,
                               int endIndex)
Returns the Rectangle enclosing the text between two indicies.

Specified by:
getTextBounds in interface AccessibleExtendedText
Parameters:
startIndex - the start index in the text
endIndex - the end index in the text
Returns:
the bounding rectangle of the text if the indices are valid. Otherwise, null is returned
Since:
1.6

getAccessibleAction

public AccessibleAction getAccessibleAction()
Description copied from class: AccessibleContext
Gets the AccessibleAction associated with this object that supports one or more actions.

Overrides:
getAccessibleAction in class AccessibleContext
Returns:
AccessibleAction if supported by object; else return null
See Also:
AccessibleAction

getAccessibleActionCount

public int getAccessibleActionCount()
Returns the number of accessible actions available in this object If there are more than one, the first one is considered the "default" action of the object.

Specified by:
getAccessibleActionCount in interface AccessibleAction
Returns:
the zero-based number of Actions in this object
Since:
1.4

getAccessibleActionDescription

public String getAccessibleActionDescription(int i)
Returns a description of the specified action of the object.

Specified by:
getAccessibleActionDescription in interface AccessibleAction
Parameters:
i - zero-based index of the actions
Returns:
a String description of the action
Since:
1.4
See Also:
getAccessibleActionCount()

doAccessibleAction

public boolean doAccessibleAction(int i)
Performs the specified Action on the object

Specified by:
doAccessibleAction in interface AccessibleAction
Parameters:
i - zero-based index of actions
Returns:
true if the action was performed; otherwise false.
Since:
1.4
See Also:
getAccessibleActionCount()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTextComponent.DropLocation

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class JTextComponent.DropLocation

java.lang.Object
    extended by  javax.swing.TransferHandler.DropLocation
        extended by  javax.swing.text.JTextComponent.DropLocation
Enclosing class:
JTextComponent
public static final class JTextComponent.DropLocation
extends TransferHandler.DropLocation

Represents a drop location for JTextComponents.

Since:
1.6
See Also:
JTextComponent.getDropLocation()

Method Summary
Position.Bias | getBias() Returns the bias for the drop index.
int | getIndex() Returns the index where dropped data should be inserted into the associated component.
String | toString() Returns a string representation of this drop location.
Methods inherited from class javax.swing.TransferHandler.DropLocation
getDropPoint
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getIndex

public int getIndex()
Returns the index where dropped data should be inserted into the associated component. This index represents a position between characters, as would be interpreted by a caret.

Returns:
the drop index

getBias

public Position.Bias getBias()
Returns the bias for the drop index.

Returns:
the drop bias

toString

public String toString()
Returns a string representation of this drop location. This method is intended to be used for debugging purposes, and the content and format of the returned string may vary between implementations.

Overrides:
toString in class TransferHandler.DropLocation
Returns:
a string representation of this drop location
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JTextComponent.KeyBinding

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class JTextComponent.KeyBinding

java.lang.Object
    extended by  javax.swing.text.JTextComponent.KeyBinding
Enclosing class:
JTextComponent
public static class JTextComponent.KeyBinding
extends Object

Binding record for creating key bindings.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
String | actionName The name of the action for the key.
KeyStroke | key The key.
Constructor Summary
JTextComponent.KeyBinding(KeyStroke key, String actionName)
Creates a new key binding.
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

key

public KeyStroke key
The key.

actionName

public String actionName
The name of the action for the key.

Constructor Detail

JTextComponent.KeyBinding

public JTextComponent.KeyBinding(KeyStroke key,
                                 String actionName)
Creates a new key binding.

Parameters:
key - the key
actionName - the name of the action for the key
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Keymap

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface Keymap

public interface Keymap

A collection of bindings of KeyStrokes to actions. The bindings are basically name-value pairs that potentially resolve in a hierarchy.

Method Summary
void | addActionForKeyStroke(KeyStroke key, Action a) Adds a binding to the keymap.
Action | getAction(KeyStroke key) Fetches the action appropriate for the given symbolic event sequence.
Action[] | getBoundActions() Fetches all of the actions defined in this keymap.
KeyStroke[] | getBoundKeyStrokes() Fetches all of the keystrokes in this map that are bound to some action.
Action | getDefaultAction() Fetches the default action to fire if a key is typed (i.e.
KeyStroke[] | getKeyStrokesForAction(Action a) Fetches the keystrokes that will result in the given action.
String | getName() Fetches the name of the set of key-bindings.
Keymap | getResolveParent() Fetches the parent keymap used to resolve key-bindings.
boolean | isLocallyDefined(KeyStroke key) Determines if the given key sequence is locally defined.
void | removeBindings() Removes all bindings from the keymap.
void | removeKeyStrokeBinding(KeyStroke keys) Removes a binding from the keymap.
void | setDefaultAction(Action a) Set the default action to fire if a key is typed.
void | setResolveParent(Keymap parent) Sets the parent keymap, which will be used to resolve key-bindings.

Method Detail

getName

String getName()
Fetches the name of the set of key-bindings.

Returns:
the name

getDefaultAction

Action getDefaultAction()
Fetches the default action to fire if a key is typed (i.e. a KEY_TYPED KeyEvent is received) and there is no binding for it. Typically this would be some action that inserts text so that the keymap doesn't require an action for each possible key.

Returns:
the default action

setDefaultAction

void setDefaultAction(Action a)
Set the default action to fire if a key is typed.

Parameters:
a - the action

getAction

Action getAction(KeyStroke key)
Fetches the action appropriate for the given symbolic event sequence. This is used by JTextController to determine how to interpret key sequences. If the binding is not resolved locally, an attempt is made to resolve through the parent keymap, if one is set.

Parameters:
key - the key sequence
Returns:
the action associated with the key sequence if one is defined, otherwise null

getBoundKeyStrokes

KeyStroke[] getBoundKeyStrokes()
Fetches all of the keystrokes in this map that are bound to some action.

Returns:
the list of keystrokes

getBoundActions

Action[] getBoundActions()
Fetches all of the actions defined in this keymap.

Returns:
the list of actions

getKeyStrokesForAction

KeyStroke[] getKeyStrokesForAction(Action a)
Fetches the keystrokes that will result in the given action.

Parameters:
a - the action
Returns:
the list of keystrokes

isLocallyDefined

boolean isLocallyDefined(KeyStroke key)
Determines if the given key sequence is locally defined.

Parameters:
key - the key sequence
Returns:
true if the key sequence is locally defined else false

addActionForKeyStroke

void addActionForKeyStroke(KeyStroke key,
                           Action a)
Adds a binding to the keymap.

Parameters:
key - the key sequence
a - the action

removeKeyStrokeBinding

void removeKeyStrokeBinding(KeyStroke keys)
Removes a binding from the keymap.

Parameters:
keys - the key sequence

removeBindings

void removeBindings()
Removes all bindings from the keymap.

getResolveParent

Keymap getResolveParent()
Fetches the parent keymap used to resolve key-bindings.

Returns:
the keymap

setResolveParent

void setResolveParent(Keymap parent)
Sets the parent keymap, which will be used to resolve key-bindings.

Parameters:
parent - the parent keymap
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LabelView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class LabelView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.GlyphView
            extended by  javax.swing.text.LabelView
All Implemented Interfaces:
Cloneable, SwingConstants, TabableView
Direct Known Subclasses:
InlineView
public class LabelView
extends GlyphView
implements TabableView

A LabelView is a styled chunk of text that represents a view mapped over an element in the text model. It caches the character level attributes used for rendering.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.text.GlyphView
GlyphView.GlyphPainter
Field Summary
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
LabelView(Element elem)
Constructs a new view wrapped on an element.
Method Summary
void | changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
Color | getBackground() Fetches the background color to use to render the glyphs.
Font | getFont() Fetches the font that the glyphs should be based upon.
protected FontMetrics | getFontMetrics() Deprecated. FontMetrics are not used for glyph rendering when running in the JDK.
Color | getForeground() Fetches the foreground color to use to render the glyphs.
boolean | isStrikeThrough() Determines if the glyphs should have a strikethrough line.
boolean | isSubscript() Determines if the glyphs should be rendered as superscript.
boolean | isSuperscript() Determines if the glyphs should be rendered as subscript.
boolean | isUnderline() Determines if the glyphs should be underlined.
protected void | setBackground(Color bg) Sets the background color for the view.
protected void | setPropertiesFromAttributes() Sets the cached properties from the attributes.
protected void | setStrikeThrough(boolean s) Sets whether or not the view has a strike/line through it.
protected void | setSubscript(boolean s) Sets whether or not the view represents a subscript.
protected void | setSuperscript(boolean s) Sets whether or not the view represents a superscript.
protected void | setUnderline(boolean u) Sets whether or not the view is underlined.
Methods inherited from class javax.swing.text.GlyphView
breakView, checkPainter, clone, createFragment, getAlignment, getBreakWeight, getEndOffset, getGlyphPainter, getNextVisualPositionFrom, getPartialSpan, getPreferredSpan, getStartOffset, getTabbedSpan, getTabExpander, getText, insertUpdate, modelToView, paint, removeUpdate, setGlyphPainter, viewToModel
Methods inherited from class javax.swing.text.View
append, forwardUpdate, forwardUpdateToView, getAttributes, getChildAllocation, getContainer, getDocument, getElement, getGraphics, getMaximumSpan, getMinimumSpan, getParent, getResizeWeight, getToolTipText, getView, getViewCount, getViewFactory, getViewIndex, getViewIndex, insert, isVisible, modelToView, modelToView, preferenceChanged, remove, removeAll, replace, setParent, setSize, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.swing.text.TabableView
getPartialSpan, getTabbedSpan

Constructor Detail

LabelView

public LabelView(Element elem)
Constructs a new view wrapped on an element.

Parameters:
elem - the element
Method Detail

setUnderline

protected void setUnderline(boolean u)
Sets whether or not the view is underlined. Note that this setter is protected and is really only meant if you need to update some additional state when set.

Parameters:
u - true if the view is underlined, otherwise false
See Also:
isUnderline()

setStrikeThrough

protected void setStrikeThrough(boolean s)
Sets whether or not the view has a strike/line through it. Note that this setter is protected and is really only meant if you need to update some additional state when set.

Parameters:
s - true if the view has a strike/line through it, otherwise false
See Also:
isStrikeThrough()

setSuperscript

protected void setSuperscript(boolean s)
Sets whether or not the view represents a superscript. Note that this setter is protected and is really only meant if you need to update some additional state when set.

Parameters:
s - true if the view represents a superscript, otherwise false
See Also:
isSuperscript()

setSubscript

protected void setSubscript(boolean s)
Sets whether or not the view represents a subscript. Note that this setter is protected and is really only meant if you need to update some additional state when set.

Parameters:
s - true if the view represents a subscript, otherwise false
See Also:
isSubscript()

setBackground

protected void setBackground(Color bg)
Sets the background color for the view. This method is typically invoked as part of configuring this View. If you need to customize the background color you should override setPropertiesFromAttributes and invoke this method. A value of null indicates no background should be rendered, so that the background of the parent View will show through.

Parameters:
bg - background color, or null
Since:
1.5
See Also:
setPropertiesFromAttributes()

setPropertiesFromAttributes

protected void setPropertiesFromAttributes()
Sets the cached properties from the attributes.

getFontMetrics

@Deprecated
protected FontMetrics getFontMetrics()
Deprecated. FontMetrics are not used for glyph rendering when running in the JDK.

Fetches the FontMetrics used for this view.

getBackground

public Color getBackground()
Fetches the background color to use to render the glyphs. This is implemented to return a cached background color, which defaults to null.

Overrides:
getBackground in class GlyphView
Returns:
the cached background color
Since:
1.3

getForeground

public Color getForeground()
Fetches the foreground color to use to render the glyphs. This is implemented to return a cached foreground color, which defaults to null.

Overrides:
getForeground in class GlyphView
Returns:
the cached foreground color
Since:
1.3

getFont

public Font getFont()
Fetches the font that the glyphs should be based upon. This is implemented to return a cached font.

Overrides:
getFont in class GlyphView
Returns:
the cached font

isUnderline

public boolean isUnderline()
Determines if the glyphs should be underlined. If true, an underline should be drawn through the baseline. This is implemented to return the cached underline property.

When you request this property, LabelView re-syncs its state with the properties of the Element's AttributeSet. If Element's AttributeSet does not have this property set, it will revert to false.

Overrides:
isUnderline in class GlyphView
Returns:
the value of the cached underline property
Since:
1.3

isStrikeThrough

public boolean isStrikeThrough()
Determines if the glyphs should have a strikethrough line. If true, a line should be drawn through the center of the glyphs. This is implemented to return the cached strikeThrough property.

When you request this property, LabelView re-syncs its state with the properties of the Element's AttributeSet. If Element's AttributeSet does not have this property set, it will revert to false.

Overrides:
isStrikeThrough in class GlyphView
Returns:
the value of the cached strikeThrough property
Since:
1.3

isSubscript

public boolean isSubscript()
Determines if the glyphs should be rendered as superscript.

Overrides:
isSubscript in class GlyphView
Returns:
the value of the cached subscript property

When you request this property, LabelView re-syncs its state with the properties of the Element's AttributeSet. If Element's AttributeSet does not have this property set, it will revert to false.

Since:
1.3

isSuperscript

public boolean isSuperscript()
Determines if the glyphs should be rendered as subscript.

When you request this property, LabelView re-syncs its state with the properties of the Element's AttributeSet. If Element's AttributeSet does not have this property set, it will revert to false.

Overrides:
isSuperscript in class GlyphView
Returns:
the value of the cached superscript property
Since:
1.3

changedUpdate

public void changedUpdate(DocumentEvent e,
                          Shape a,
                          ViewFactory f)
Gives notification from the document that attributes were changed in a location that this view is responsible for.

Overrides:
changedUpdate in class GlyphView
Parameters:
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LayeredHighlighter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class LayeredHighlighter

java.lang.Object
    extended by  javax.swing.text.LayeredHighlighter
All Implemented Interfaces:
Highlighter
Direct Known Subclasses:
DefaultHighlighter
public abstract class LayeredHighlighter
extends Object
implements Highlighter

See Also:
Highlighter

Nested Class Summary
static class LayeredHighlighter.LayerPainter
Layered highlight renderer.
Nested classes/interfaces inherited from interface javax.swing.text.Highlighter
Highlighter.Highlight, Highlighter.HighlightPainter
Constructor Summary
LayeredHighlighter()
Method Summary
abstract  void paintLayeredHighlights(Graphics g, int p0, int p1, Shape viewBounds, JTextComponent editor, View view)
When leaf Views (such as LabelView) are rendering they should call into this method.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.swing.text.Highlighter
addHighlight, changeHighlight, deinstall, getHighlights, install, paint, removeAllHighlights, removeHighlight

Constructor Detail

LayeredHighlighter

public LayeredHighlighter()
Method Detail

paintLayeredHighlights

public abstract void paintLayeredHighlights(Graphics g,
                                            int p0,
                                            int p1,
                                            Shape viewBounds,
                                            JTextComponent editor,
                                            View view)
When leaf Views (such as LabelView) are rendering they should call into this method. If a highlight is in the given region it will be drawn immediately.

Parameters:
g - Graphics used to draw
p0 - starting offset of view
p1 - ending offset of view
viewBounds - Bounds of View
editor - JTextComponent
view - View instance being rendered
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LayeredHighlighter.LayerPainter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class LayeredHighlighter.LayerPainter

java.lang.Object
    extended by  javax.swing.text.LayeredHighlighter.LayerPainter
All Implemented Interfaces:
Highlighter.HighlightPainter
Direct Known Subclasses:
DefaultHighlighter.DefaultHighlightPainter
Enclosing class:
LayeredHighlighter
public abstract static class LayeredHighlighter.LayerPainter
extends Object
implements Highlighter.HighlightPainter

Layered highlight renderer.

Constructor Summary
LayeredHighlighter.LayerPainter()
Method Summary
abstract  Shape paintLayer(Graphics g, int p0, int p1, Shape viewBounds, JTextComponent editor, View view)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.swing.text.Highlighter.HighlightPainter
paint

Constructor Detail

LayeredHighlighter.LayerPainter

public LayeredHighlighter.LayerPainter()
Method Detail

paintLayer

public abstract Shape paintLayer(Graphics g,
                                 int p0,
                                 int p1,
                                 Shape viewBounds,
                                 JTextComponent editor,
                                 View view)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LayoutQueue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class LayoutQueue

java.lang.Object
    extended by  javax.swing.text.LayoutQueue

public class LayoutQueue
extends Object

A queue of text layout tasks.

Since:
1.3
See Also:
AsyncBoxView

Constructor Summary
LayoutQueue()
Construct a layout queue.
Method Summary
void | addTask(Runnable task) Add a task that is not needed immediately because the results are not believed to be visible.
static LayoutQueue | getDefaultQueue() Fetch the default layout queue.
static void | setDefaultQueue(LayoutQueue q) Set the default layout queue.
protected Runnable | waitForWork() Used by the worker thread to get a new task to execute
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LayoutQueue

public LayoutQueue()
Construct a layout queue.

Method Detail

getDefaultQueue

public static LayoutQueue getDefaultQueue()
Fetch the default layout queue.

setDefaultQueue

public static void setDefaultQueue(LayoutQueue q)
Set the default layout queue.

Parameters:
q - the new queue.

addTask

public void addTask(Runnable task)
Add a task that is not needed immediately because the results are not believed to be visible.

waitForWork

protected Runnable waitForWork()
Used by the worker thread to get a new task to execute

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MaskFormatter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class MaskFormatter

java.lang.Object
    extended by  javax.swing.JFormattedTextField.AbstractFormatter
        extended by  javax.swing.text.DefaultFormatter
            extended by  javax.swing.text.MaskFormatter
All Implemented Interfaces:
Serializable, Cloneable
public class MaskFormatter
extends DefaultFormatter

MaskFormatter is used to format and edit strings. The behavior of a MaskFormatter is controlled by way of a String mask that specifies the valid characters that can be contained at a particular location in the Document model. The following characters can be specified:
Character | Description
# | Any valid number, uses Character.isDigit.
' | Escape character, used to escape any of the special formatting characters.
U | Any character (Character.isLetter). All lowercase letters are mapped to upper case.
L | Any character (Character.isLetter). All upper case letters are mapped to lower case.
A | Any character or number (Character.isLetter or Character.isDigit)
? | Any character (Character.isLetter).
* | Anything.
H | Any hex character (0-9, a-f or A-F).

Typically characters correspond to one char, but in certain languages this is not the case. The mask is on a per character basis, and will thus adjust to fit as many chars as are needed.

You can further restrict the characters that can be input by the setInvalidCharacters and setValidCharacters methods. setInvalidCharacters allows you to specify which characters are not legal. setValidCharacters allows you to specify which characters are valid. For example, the following code block is equivalent to a mask of '0xHHH' with no invalid/valid characters:

 MaskFormatter formatter = new MaskFormatter("0x***");
 formatter.setValidCharacters("0123456789abcdefABCDEF");

When initially formatting a value if the length of the string is less than the length of the mask, two things can happen. Either the placeholder string will be used, or the placeholder character will be used. Precedence is given to the placeholder string. For example:

   MaskFormatter formatter = new MaskFormatter("###-####");
   formatter.setPlaceholderCharacter('_');
   formatter.getDisplayValue(tf, "123");

Would result in the string '123-____'. If setPlaceholder("555-1212") was invoked '123-1212' would result. The placeholder String is only used on the initial format, on subsequent formats only the placeholder character will be used.

If a MaskFormatter is configured to only allow valid characters (setAllowsInvalid(false)) literal characters will be skipped as necessary when editing. Consider a MaskFormatter with the mask "###-####" and current value "555-1212". Using the right arrow key to navigate through the field will result in (| indicates the position of the caret):

   |555-1212
   5|55-1212
   55|5-1212
   555-|1212
   555-1|212
The '-' is a literal (non-editable) character, and is skipped.

Similar behavior will result when editing. Consider inserting the string '123-45' and '12345' into the MaskFormatter in the previous example. Both inserts will result in the same String, '123-45__'. When MaskFormatter is processing the insert at character position 3 (the '-'), two things can happen:

  1. If the inserted character is '-', it is accepted.
  2. If the inserted character matches the mask for the next non-literal character, it is accepted at the new location.
  3. Anything else results in an invalid edit

By default MaskFormatter will not allow invalid edits, you can change this with the setAllowsInvalid method, and will commit edits on valid edits (use the setCommitsOnValidEdit to change this).

By default, MaskFormatter is in overwrite mode. That is as characters are typed a new character is not inserted, rather the character at the current location is replaced with the newly typed character. You can change this behavior by way of the method setOverwriteMode.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Since:
1.4

Constructor Summary
MaskFormatter()
Creates a MaskFormatter with no mask.
MaskFormatter(String mask)
Creates a MaskFormatter with the specified mask.
Method Summary
String | getInvalidCharacters() Returns the characters that are not valid for input.
String | getMask() Returns the formatting mask.
String | getPlaceholder() Returns the String to use if the value does not completely fill in the mask.
char | getPlaceholderCharacter() Returns the character to use in place of characters that are not present in the value, ie the user must fill them in.
String | getValidCharacters() Returns the valid characters that can be input.
boolean | getValueContainsLiteralCharacters() Returns true if stringToValue should return literal characters in the mask.
void | install(JFormattedTextField ftf) Installs the DefaultFormatter onto a particular JFormattedTextField.
void | setInvalidCharacters(String invalidCharacters) Allows for further restricting of the characters that can be input.
void | setMask(String mask) Sets the mask dictating the legal characters.
void | setPlaceholder(String placeholder) Sets the string to use if the value does not completely fill in the mask.
void | setPlaceholderCharacter(char placeholder) Sets the character to use in place of characters that are not present in the value, ie the user must fill them in.
void | setValidCharacters(String validCharacters) Allows for further restricting of the characters that can be input.
void | setValueContainsLiteralCharacters(boolean containsLiteralChars) If true, the returned value and set value will also contain the literal characters in mask.
Object | stringToValue(String value) Parses the text, returning the appropriate Object representation of the String value.
String | valueToString(Object value) Returns a String representation of the Object value based on the mask.
Methods inherited from class javax.swing.text.DefaultFormatter
clone, getAllowsInvalid, getCommitsOnValidEdit, getDocumentFilter, getNavigationFilter, getOverwriteMode, getValueClass, setAllowsInvalid, setCommitsOnValidEdit, setOverwriteMode, setValueClass
Methods inherited from class javax.swing.JFormattedTextField.AbstractFormatter
getActions, getFormattedTextField, invalidEdit, setEditValid, uninstall
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MaskFormatter

public MaskFormatter()
Creates a MaskFormatter with no mask.

MaskFormatter

public MaskFormatter(String mask)
              throws ParseException
Creates a MaskFormatter with the specified mask. A ParseException will be thrown if mask is an invalid mask.

Throws:
ParseException - if mask does not contain valid mask characters
Method Detail

setMask

public void setMask(String mask)
             throws ParseException
Sets the mask dictating the legal characters. This will throw a ParseException if mask is not valid.

Throws:
ParseException - if mask does not contain valid mask characters

getMask

public String getMask()
Returns the formatting mask.

Returns:
Mask dictating legal character values.

setValidCharacters

public void setValidCharacters(String validCharacters)
Allows for further restricting of the characters that can be input. Only characters specified in the mask, not in the invalidCharacters, and in validCharacters will be allowed to be input. Passing in null (the default) implies the valid characters are only bound by the mask and the invalid characters.

Parameters:
validCharacters - If non-null, specifies legal characters.

getValidCharacters

public String getValidCharacters()
Returns the valid characters that can be input.

Returns:
Legal characters

setInvalidCharacters

public void setInvalidCharacters(String invalidCharacters)
Allows for further restricting of the characters that can be input. Only characters specified in the mask, not in the invalidCharacters, and in validCharacters will be allowed to be input. Passing in null (the default) implies the valid characters are only bound by the mask and the valid characters.

Parameters:
invalidCharacters - If non-null, specifies illegal characters.

getInvalidCharacters

public String getInvalidCharacters()
Returns the characters that are not valid for input.

Returns:
illegal characters.

setPlaceholder

public void setPlaceholder(String placeholder)
Sets the string to use if the value does not completely fill in the mask. A null value implies the placeholder char should be used.

Parameters:
placeholder - String used when formatting if the value does not completely fill the mask

getPlaceholder

public String getPlaceholder()
Returns the String to use if the value does not completely fill in the mask.

Returns:
String used when formatting if the value does not completely fill the mask

setPlaceholderCharacter

public void setPlaceholderCharacter(char placeholder)
Sets the character to use in place of characters that are not present in the value, ie the user must fill them in. The default value is a space.

This is only applicable if the placeholder string has not been specified, or does not completely fill in the mask.

Parameters:
placeholder - Character used when formatting if the value does not completely fill the mask

getPlaceholderCharacter

public char getPlaceholderCharacter()
Returns the character to use in place of characters that are not present in the value, ie the user must fill them in.

Returns:
Character used when formatting if the value does not completely fill the mask

setValueContainsLiteralCharacters

public void setValueContainsLiteralCharacters(boolean containsLiteralChars)
If true, the returned value and set value will also contain the literal characters in mask.

For example, if the mask is '(###) ###-####', the current value is '(415) 555-1212', and valueContainsLiteralCharacters is true stringToValue will return '(415) 555-1212'. On the other hand, if valueContainsLiteralCharacters is false, stringToValue will return '4155551212'.

Parameters:
containsLiteralChars - Used to indicate if literal characters in mask should be returned in stringToValue

getValueContainsLiteralCharacters

public boolean getValueContainsLiteralCharacters()
Returns true if stringToValue should return literal characters in the mask.

Returns:
True if literal characters in mask should be returned in stringToValue

stringToValue

public Object stringToValue(String value)
                     throws ParseException
Parses the text, returning the appropriate Object representation of the String value. This strips the literal characters as necessary and invokes supers stringToValue, so that if you have specified a value class (setValueClass) an instance of it will be created. This will throw a ParseException if the value does not match the current mask. Refer to setValueContainsLiteralCharacters(boolean) for details on how literals are treated.

Overrides:
stringToValue in class DefaultFormatter
Parameters:
value - String to convert
Returns:
Object representation of text
Throws:
ParseException - if there is an error in the conversion
See Also:
setValueContainsLiteralCharacters(boolean)

valueToString

public String valueToString(Object value)
                     throws ParseException
Returns a String representation of the Object value based on the mask. Refer to setValueContainsLiteralCharacters(boolean) for details on how literals are treated.

Overrides:
valueToString in class DefaultFormatter
Parameters:
value - Value to convert
Returns:
String representation of value
Throws:
ParseException - if there is an error in the conversion
See Also:
setValueContainsLiteralCharacters(boolean)

install

public void install(JFormattedTextField ftf)
Installs the DefaultFormatter onto a particular JFormattedTextField. This will invoke valueToString to convert the current value from the JFormattedTextField to a String. This will then install the Actions from getActions, the DocumentFilter returned from getDocumentFilter and the NavigationFilter returned from getNavigationFilter onto the JFormattedTextField.

Subclasses will typically only need to override this if they wish to install additional listeners on the JFormattedTextField.

If there is a ParseException in converting the current value to a String, this will set the text to an empty String, and mark the JFormattedTextField as being in an invalid state.

While this is a public method, this is typically only useful for subclassers of JFormattedTextField. JFormattedTextField will invoke this method at the appropriate times when the value changes, or its internal state changes.

Overrides:
install in class DefaultFormatter
Parameters:
ftf - JFormattedTextField to format for, may be null indicating uninstall from current JFormattedTextField.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MutableAttributeSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface MutableAttributeSet

All Superinterfaces:
AttributeSet
All Known Subinterfaces:
Style
All Known Implementing Classes:
AbstractDocument.AbstractElement, AbstractDocument.BranchElement, AbstractDocument.LeafElement, DefaultStyledDocument.SectionElement, HTMLDocument.BlockElement, HTMLDocument.RunElement, SimpleAttributeSet, StyleContext.NamedStyle
public interface MutableAttributeSet
extends AttributeSet

A generic interface for a mutable collection of unique attributes. Implementations will probably want to provide a constructor of the form: public XXXAttributeSet(ConstAttributeSet source);

Nested Class Summary
Nested classes/interfaces inherited from interface javax.swing.text.AttributeSet
AttributeSet.CharacterAttribute, AttributeSet.ColorAttribute, AttributeSet.FontAttribute, AttributeSet.ParagraphAttribute
Field Summary
Fields inherited from interface javax.swing.text.AttributeSet
NameAttribute, ResolveAttribute
Method Summary
void | addAttribute(Object name, Object value) Creates a new attribute set similar to this one except that it contains an attribute with the given name and value.
void | addAttributes(AttributeSet attributes) Creates a new attribute set similar to this one except that it contains the given attributes and values.
void | removeAttribute(Object name) Removes an attribute with the given name.
void | removeAttributes(AttributeSet attributes) Removes a set of attributes with the given name.
void | removeAttributes(Enumeration<?> names) Removes an attribute set with the given names.
void | setResolveParent(AttributeSet parent) Sets the resolving parent.
Methods inherited from interface javax.swing.text.AttributeSet
containsAttribute, containsAttributes, copyAttributes, getAttribute, getAttributeCount, getAttributeNames, getResolveParent, isDefined, isEqual

Method Detail

addAttribute

void addAttribute(Object name,
                  Object value)
Creates a new attribute set similar to this one except that it contains an attribute with the given name and value. The object must be immutable, or not mutated by any client.

Parameters:
name - the name
value - the value

addAttributes

void addAttributes(AttributeSet attributes)
Creates a new attribute set similar to this one except that it contains the given attributes and values.

Parameters:
attributes - the set of attributes

removeAttribute

void removeAttribute(Object name)
Removes an attribute with the given name.

Parameters:
name - the attribute name

removeAttributes

void removeAttributes(Enumeration<?> names)
Removes an attribute set with the given names.

Parameters:
names - the set of names

removeAttributes

void removeAttributes(AttributeSet attributes)
Removes a set of attributes with the given name.

Parameters:
attributes - the set of attributes

setResolveParent

void setResolveParent(AttributeSet parent)
Sets the resolving parent. This is the set of attributes to resolve through if an attribute isn't defined locally.

Parameters:
parent - the parent
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NavigationFilter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class NavigationFilter

java.lang.Object
    extended by  javax.swing.text.NavigationFilter

public class NavigationFilter
extends Object

NavigationFilter can be used to restrict where the cursor can be positioned. When the default cursor positioning actions attempt to reposition the cursor they will call into the NavigationFilter, assuming the JTextComponent has a non-null NavigationFilter set. In this manner the NavigationFilter can effectively restrict where the cursor can be positioned. Similarly DefaultCaret will call into the NavigationFilter when the user is changing the selection to further restrict where the cursor can be positioned.

Subclasses can conditionally call into supers implementation to restrict where the cursor can be placed, or call directly into the FilterBypass.

Since:
1.4
See Also:
Caret, DefaultCaret, View

Nested Class Summary
static class NavigationFilter.FilterBypass
Used as a way to circumvent calling back into the caret to position the cursor.
Constructor Summary
NavigationFilter()
Method Summary
int | getNextVisualPositionFrom(JTextComponent text, int pos, Position.Bias bias, int direction, Position.Bias[] biasRet) Returns the next visual position to place the caret at from an existing position.
void | moveDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias) Invoked prior to the Caret moving the dot.
void | setDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias) Invoked prior to the Caret setting the dot.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NavigationFilter

public NavigationFilter()
Method Detail

setDot

public void setDot(NavigationFilter.FilterBypass fb,
                   int dot,
                   Position.Bias bias)
Invoked prior to the Caret setting the dot. The default implementation calls directly into the FilterBypass with the passed in arguments. Subclasses may wish to conditionally call super with a different location, or invoke the necessary method on the FilterBypass

Parameters:
fb - FilterBypass that can be used to mutate caret position
dot - the position >= 0
bias - Bias to place the dot at

moveDot

public void moveDot(NavigationFilter.FilterBypass fb,
                    int dot,
                    Position.Bias bias)
Invoked prior to the Caret moving the dot. The default implementation calls directly into the FilterBypass with the passed in arguments. Subclasses may wish to conditionally call super with a different location, or invoke the necessary methods on the FilterBypass.

Parameters:
fb - FilterBypass that can be used to mutate caret position
dot - the position >= 0
bias - Bias for new location

getNextVisualPositionFrom

public int getNextVisualPositionFrom(JTextComponent text,
                                     int pos,
                                     Position.Bias bias,
                                     int direction,
                                     Position.Bias[] biasRet)
                              throws BadLocationException
Returns the next visual position to place the caret at from an existing position. The default implementation simply forwards the method to the root View. Subclasses may wish to further restrict the location based on additional criteria.

Parameters:
text - JTextComponent containing text
pos - Position used in determining next position
bias - Bias used in determining next position
direction - the direction from the current position that can be thought of as the arrow keys typically found on a keyboard. This will be one of the following values:
  • SwingConstants.WEST
  • SwingConstants.EAST
  • SwingConstants.NORTH
  • SwingConstants.SOUTH
biasRet - Used to return resulting Bias of next position
Returns:
the location within the model that best represents the next location visual position
Throws:
BadLocationException
IllegalArgumentException - if direction doesn't have one of the legal values above
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NavigationFilter.FilterBypass

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class NavigationFilter.FilterBypass

java.lang.Object
    extended by  javax.swing.text.NavigationFilter.FilterBypass
Enclosing class:
NavigationFilter
public abstract static class NavigationFilter.FilterBypass
extends Object

Used as a way to circumvent calling back into the caret to position the cursor. Caret implementations that wish to support a NavigationFilter must provide an implementation that will not callback into the NavigationFilter.

Since:
1.4

Constructor Summary
NavigationFilter.FilterBypass()
Method Summary
abstract Caret | getCaret() Returns the Caret that is changing.
abstract void | moveDot(int dot, Position.Bias bias) Moves the caret location, bypassing the NavigationFilter.
abstract void | setDot(int dot, Position.Bias bias) Sets the caret location, bypassing the NavigationFilter.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NavigationFilter.FilterBypass

public NavigationFilter.FilterBypass()
Method Detail

getCaret

public abstract Caret getCaret()
Returns the Caret that is changing.

Returns:
Caret that is changing

setDot

public abstract void setDot(int dot,
                            Position.Bias bias)
Sets the caret location, bypassing the NavigationFilter.

Parameters:
dot - the position >= 0
bias - Bias to place the dot at

moveDot

public abstract void moveDot(int dot,
                             Position.Bias bias)
Moves the caret location, bypassing the NavigationFilter.

Parameters:
dot - the position >= 0
bias - Bias for new location
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NumberFormatter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class NumberFormatter

java.lang.Object
    extended by  javax.swing.JFormattedTextField.AbstractFormatter
        extended by  javax.swing.text.DefaultFormatter
            extended by  javax.swing.text.InternationalFormatter
                extended by  javax.swing.text.NumberFormatter
All Implemented Interfaces:
Serializable, Cloneable
public class NumberFormatter
extends InternationalFormatter

NumberFormatter subclasses InternationalFormatter adding special behavior for numbers. Among the specializations are (these are only used if the NumberFormatter does not display invalid nubers, eg setAllowsInvalid(false)):

  • Pressing +/- (- is determined from the DecimalFormatSymbols associated with the DecimalFormat) in any field but the exponent field will attempt to change the sign of the number to positive/negative.
  • Pressing +/- (- is determined from the DecimalFormatSymbols associated with the DecimalFormat) in the exponent field will attemp to change the sign of the exponent to positive/negative.

If you are displaying scientific numbers, you may wish to turn on overwrite mode, setOverwriteMode(true). For example:

 DecimalFormat decimalFormat = new DecimalFormat("0.000E0");
 NumberFormatter textFormatter = new NumberFormatter(decimalFormat);
 textFormatter.setOverwriteMode(true);
 textFormatter.setAllowsInvalid(false);

If you are going to allow the user to enter decimal values, you should either force the DecimalFormat to contain at least one decimal (#.0###), or allow the value to be invalid setAllowsInvalid(true). Otherwise users may not be able to input decimal values.

NumberFormatter provides slightly different behavior to stringToValue than that of its superclass. If you have specified a Class for values, DefaultFormatter.setValueClass(java.lang.Class), that is one of of Integer, Long, Float, Double, Byte or Short and the Format's parseObject returns an instance of Number, the corresponding instance of the value class will be created using the constructor appropriate for the primitive type the value class represents. For example: setValueClass(Integer.class) will cause the resulting value to be created via new Integer(((Number)formatter.parseObject(string)).intValue()). This is typically useful if you wish to set a min/max value as the various Number implementations are generally not comparable to each other. This is also useful if for some reason you need a specific Number implementation for your values.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Since:
1.4

Constructor Summary
NumberFormatter()
Creates a NumberFormatter with the a default NumberFormat instance obtained from NumberFormat.getNumberInstance().
NumberFormatter(NumberFormat format)
Creates a NumberFormatter with the specified Format instance.
Method Summary
 void setFormat(Format format)
Sets the format that dictates the legal values that can be edited and displayed.
Methods inherited from class javax.swing.text.InternationalFormatter
clone, getActions, getFields, getFormat, getMaximum, getMinimum, install, setMaximum, setMinimum, stringToValue, valueToString
Methods inherited from class javax.swing.text.DefaultFormatter
getAllowsInvalid, getCommitsOnValidEdit, getDocumentFilter, getNavigationFilter, getOverwriteMode, getValueClass, setAllowsInvalid, setCommitsOnValidEdit, setOverwriteMode, setValueClass
Methods inherited from class javax.swing.JFormattedTextField.AbstractFormatter
getFormattedTextField, invalidEdit, setEditValid, uninstall
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NumberFormatter

public NumberFormatter()
Creates a NumberFormatter with the a default NumberFormat instance obtained from NumberFormat.getNumberInstance().

NumberFormatter

public NumberFormatter(NumberFormat format)
Creates a NumberFormatter with the specified Format instance.

Parameters:
format - Format used to dictate legal values
Method Detail

setFormat

public void setFormat(Format format)
Sets the format that dictates the legal values that can be edited and displayed.

If you have used the nullary constructor the value of this property will be determined for the current locale by way of the NumberFormat.getNumberInstance() method.

Overrides:
setFormat in class InternationalFormatter
Parameters:
format - NumberFormat instance used to dictate legal values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ParagraphView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class ParagraphView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.CompositeView
            extended by  javax.swing.text.BoxView
                extended by  javax.swing.text.FlowView
                    extended by  javax.swing.text.ParagraphView
All Implemented Interfaces:
SwingConstants, TabExpander
Direct Known Subclasses:
ParagraphView
public class ParagraphView
extends FlowView
implements TabExpander

View of a simple line-wrapping paragraph that supports multiple fonts, colors, components, icons, etc. It is basically a vertical box with a margin around it. The contents of the box are a bunch of rows which are special horizontal boxes. This view creates a collection of views that represent the child elements of the paragraph element. Each of these views are placed into a row directly if they will fit, otherwise the breakView method is called to try and carve the view into pieces that fit.

See Also:
View

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.text.FlowView
FlowView.FlowStrategy
Field Summary
protected  int firstLineIndent
Indentation for the first line, from the left inset.
Fields inherited from class javax.swing.text.FlowView
layoutPool, layoutSpan, strategy
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
ParagraphView(Element elem)
Constructs a ParagraphView for the given element.
Method Summary
protected void | adjustRow(javax.swing.text.ParagraphView.Row r, int desiredSpan, int x) Adjusts the given row if possible to fit within the layout span.
View | breakView(int axis, float len, Shape a) Breaks this view on the given axis at the given length.
void | changedUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
protected View | createRow() Create a View that should be used to hold a a row's worth of children in a flow.
protected int | findOffsetToCharactersInString(char[] string, int start) Finds the next character in the document with a character in string, starting at offset start.
protected boolean | flipEastAndWestAtEnds(int position, Position.Bias bias) Determines in which direction the next view lays.
float | getAlignment(int axis) Determines the desired alignment for this view along an axis.
int | getBreakWeight(int axis, float len) Gets the break weight for a given location.
protected int | getClosestPositionTo(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet, int rowIndex, int x) Returns the closest model position to x.
int | getFlowSpan(int index) Fetches the constraining span to flow against for the given child index.
int | getFlowStart(int index) Fetches the location along the flow axis that the flow span will start at.
protected View | getLayoutView(int index) Returns the view at a given index.
protected int | getLayoutViewCount() Returns the number of views that this view is responsible for.
protected int | getNextNorthSouthVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Returns the next visual position for the cursor, in either the east or west direction.
protected float | getPartialSize(int startOffset, int endOffset) Returns the size used by the views between startOffset and endOffset.
protected float | getTabBase() Returns where the tabs are calculated from.
protected TabSet | getTabSet() Gets the Tabset to be used in calculating tabs.
float | nextTabStop(float x, int tabOffset) Returns the next tab stop position given a reference position.
void | paint(Graphics g, Shape a) Renders using the given rendering surface and area on that surface.
protected void | setFirstLineIndent(float fi) Sets the indent on the first line.
protected void | setJustification(int j) Sets the type of justification.
protected void | setLineSpacing(float ls) Sets the line spacing.
protected void | setPropertiesFromAttributes() Set the cached properties from the attributes.
Methods inherited from class javax.swing.text.FlowView
calculateMinorAxisRequirements, getFlowAxis, getViewIndexAtPosition, insertUpdate, layout, loadChildren, removeUpdate, setParent
Methods inherited from class javax.swing.text.BoxView
baselineLayout, baselineRequirements, calculateMajorAxisRequirements, childAllocation, forwardUpdate, getAxis, getChildAllocation, getHeight, getMaximumSpan, getMinimumSpan, getOffset, getPreferredSpan, getResizeWeight, getSpan, getViewAtPoint, getWidth, isAfter, isAllocationValid, isBefore, isLayoutValid, layoutChanged, layoutMajorAxis, layoutMinorAxis, modelToView, paintChild, preferenceChanged, replace, setAxis, setSize, viewToModel
Methods inherited from class javax.swing.text.CompositeView
getBottomInset, getInsideAllocation, getLeftInset, getNextEastWestVisualPositionFrom, getNextVisualPositionFrom, getRightInset, getTopInset, getView, getViewAtPosition, getViewCount, getViewIndex, modelToView, setInsets, setParagraphInsets
Methods inherited from class javax.swing.text.View
append, breakView, createFragment, forwardUpdateToView, getAttributes, getBreakWeight, getContainer, getDocument, getElement, getEndOffset, getGraphics, getParent, getStartOffset, getToolTipText, getViewFactory, getViewIndex, insert, isVisible, modelToView, remove, removeAll, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

firstLineIndent

protected int firstLineIndent
Indentation for the first line, from the left inset.

Constructor Detail

ParagraphView

public ParagraphView(Element elem)
Constructs a ParagraphView for the given element.

Parameters:
elem - the element that this view is responsible for
Method Detail

setJustification

protected void setJustification(int j)
Sets the type of justification.

Parameters:
j - one of the following values:
  • StyleConstants.ALIGN_LEFT
  • StyleConstants.ALIGN_CENTER
  • StyleConstants.ALIGN_RIGHT

setLineSpacing

protected void setLineSpacing(float ls)
Sets the line spacing.

Parameters:
ls - the value is a factor of the line hight

setFirstLineIndent

protected void setFirstLineIndent(float fi)
Sets the indent on the first line.

Parameters:
fi - the value in points

setPropertiesFromAttributes

protected void setPropertiesFromAttributes()
Set the cached properties from the attributes.

getLayoutViewCount

protected int getLayoutViewCount()
Returns the number of views that this view is responsible for. The child views of the paragraph are rows which have been used to arrange pieces of the Views that represent the child elements. This is the number of views that have been tiled in two dimensions, and should be equivalent to the number of child elements to the element this view is responsible for.

Returns:
the number of views that this ParagraphView is responsible for

getLayoutView

protected View getLayoutView(int index)
Returns the view at a given index. The child views of the paragraph are rows which have been used to arrange pieces of the Views that represent the child elements. This methods returns the view responsible for the child element index (prior to breaking). These are the Views that were produced from a factory (to represent the child elements) and used for layout.

Parameters:
index - the index of the desired view
Returns:
the view at index

adjustRow

protected void adjustRow(javax.swing.text.ParagraphView.Row r,
                         int desiredSpan,
                         int x)
Adjusts the given row if possible to fit within the layout span. By default this will try to find the highest break weight possible nearest the end of the row. If a forced break is encountered, the break will be positioned there.

This is meant for internal usage, and should not be used directly.

Parameters:
r - the row to adjust to the current layout span
desiredSpan - the current layout span >= 0
x - the location r starts at

getNextNorthSouthVisualPositionFrom

protected int getNextNorthSouthVisualPositionFrom(int pos,
                                                  Position.Bias b,
                                                  Shape a,
                                                  int direction,
                                                  Position.Bias[] biasRet)
                                           throws BadLocationException
Returns the next visual position for the cursor, in either the east or west direction. Overridden from CompositeView.

Overrides:
getNextNorthSouthVisualPositionFrom in class CompositeView
Parameters:
pos - position into the model
b - either Position.Bias.Forward or Position.Bias.Backward
a - the allocated region to render into
direction - either SwingConstants.NORTH or SwingConstants.SOUTH
biasRet - an array containing the bias that were checked in this method
Returns:
the location in the model that represents the next location visual position
Throws:
BadLocationException
See Also:
CompositeView.getNextVisualPositionFrom(int, javax.swing.text.Position.Bias, java.awt.Shape, int, javax.swing.text.Position.Bias[])

getClosestPositionTo

protected int getClosestPositionTo(int pos,
                                   Position.Bias b,
                                   Shape a,
                                   int direction,
                                   Position.Bias[] biasRet,
                                   int rowIndex,
                                   int x)
                            throws BadLocationException
Returns the closest model position to x. rowIndex gives the index of the view that corresponds that should be looked in.

Parameters:
pos - position into the model
a - the allocated region to render into
direction - one of the following values:
  • SwingConstants.NORTH
  • SwingConstants.SOUTH
biasRet - an array containing the bias that were checked in this method
rowIndex - the index of the view
x - the x coordinate of interest
Returns:
the closest model position to x
Throws:
BadLocationException

flipEastAndWestAtEnds

protected boolean flipEastAndWestAtEnds(int position,
                                        Position.Bias bias)
Determines in which direction the next view lays. Consider the View at index n. Typically the Views are layed out from left to right, so that the View to the EAST will be at index n + 1, and the View to the WEST will be at index n - 1. In certain situations, such as with bidirectional text, it is possible that the View to EAST is not at index n + 1, but rather at index n - 1, or that the View to the WEST is not at index n - 1, but index n + 1. In this case this method would return true, indicating the Views are layed out in descending order.

This will return true if the text is layed out right to left at position, otherwise false.

Overrides:
flipEastAndWestAtEnds in class BoxView
Parameters:
position - position into the model
bias - either Position.Bias.Forward or Position.Bias.Backward
Returns:
true if the text is layed out right to left at position, otherwise false.

getFlowSpan

public int getFlowSpan(int index)
Fetches the constraining span to flow against for the given child index.

Overrides:
getFlowSpan in class FlowView
Parameters:
index - the index of the view being queried
Returns:
the constraining span for the given view at index
Since:
1.3
See Also:
FlowView.getFlowStart(int)

getFlowStart

public int getFlowStart(int index)
Fetches the location along the flow axis that the flow span will start at.

Overrides:
getFlowStart in class FlowView
Parameters:
index - the index of the view being queried
Returns:
the location for the given view at index
Since:
1.3
See Also:
FlowView.getFlowSpan(int)

createRow

protected View createRow()
Create a View that should be used to hold a a row's worth of children in a flow.

Specified by:
createRow in class FlowView
Returns:
the new View
Since:
1.3

nextTabStop

public float nextTabStop(float x,
                         int tabOffset)
Returns the next tab stop position given a reference position. This view implements the tab coordinate system, and calls getTabbedSpan on the logical children in the process of layout to determine the desired span of the children. The logical children can delegate their tab expansion upward to the paragraph which knows how to expand tabs. LabelView is an example of a view that delegates its tab expansion needs upward to the paragraph.

This is implemented to try and locate a TabSet in the paragraph element's attribute set. If one can be found, its settings will be used, otherwise a default expansion will be provided. The base location for for tab expansion is the left inset from the paragraphs most recent allocation (which is what the layout of the children is based upon).

Specified by:
nextTabStop in interface TabExpander
Parameters:
x - the X reference position
tabOffset - the position within the text stream that the tab occurred at >= 0
Returns:
the trailing end of the tab expansion >= 0
See Also:
TabSet, TabStop, LabelView

getTabSet

protected TabSet getTabSet()
Gets the Tabset to be used in calculating tabs.

Returns:
the TabSet

getPartialSize

protected float getPartialSize(int startOffset,
                               int endOffset)
Returns the size used by the views between startOffset and endOffset. This uses getPartialView to calculate the size if the child view implements the TabableView interface. If a size is needed and a View does not implement the TabableView interface, the preferredSpan will be used.

Parameters:
startOffset - the starting document offset >= 0
endOffset - the ending document offset >= startOffset
Returns:
the size >= 0

findOffsetToCharactersInString

protected int findOffsetToCharactersInString(char[] string,
                                             int start)
Finds the next character in the document with a character in string, starting at offset start. If there are no characters found, -1 will be returned.

Parameters:
string - the string of characters
start - where to start in the model >= 0
Returns:
the document offset, or -1 if no characters found

getTabBase

protected float getTabBase()
Returns where the tabs are calculated from.

Returns:
where tabs are calculated from

paint

public void paint(Graphics g,
                  Shape a)
Renders using the given rendering surface and area on that surface. This is implemented to delgate to the superclass after stashing the base coordinate for tab calculations.

Overrides:
paint in class BoxView
Parameters:
g - the rendering surface to use
a - the allocated region to render into
See Also:
View.paint(java.awt.Graphics, java.awt.Shape)

getAlignment

public float getAlignment(int axis)
Determines the desired alignment for this view along an axis. This is implemented to give the alignment to the center of the first row along the y axis, and the default along the x axis.

Overrides:
getAlignment in class BoxView
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the desired alignment. This should be a value between 0.0 and 1.0 inclusive, where 0 indicates alignment at the origin and 1.0 indicates alignment to the full span away from the origin. An alignment of 0.5 would be the center of the view.

breakView

public View breakView(int axis,
                      float len,
                      Shape a)
Breaks this view on the given axis at the given length.

ParagraphView instances are breakable along the Y_AXIS only, and only if len is after the first line.

Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
len - specifies where a potential break is desired along the given axis >= 0
a - the current allocation of the view
Returns:
the fragment of the view that represents the given span, if the view can be broken; if the view doesn't support breaking behavior, the view itself is returned
See Also:
View.breakView(int, int, float, float)

getBreakWeight

public int getBreakWeight(int axis,
                          float len)
Gets the break weight for a given location.

ParagraphView instances are breakable along the Y_AXIS only, and only if len is after the first row. If the length is less than one row, a value of BadBreakWeight is returned.

Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
len - specifies where a potential break is desired >= 0
Returns:
a value indicating the attractiveness of breaking here; either GoodBreakWeight or BadBreakWeight
See Also:
View.getBreakWeight(int, float, float)

changedUpdate

public void changedUpdate(DocumentEvent changes,
                          Shape a,
                          ViewFactory f)
Gives notification from the document that attributes were changed in a location that this view is responsible for.

Overrides:
changedUpdate in class FlowView
Parameters:
changes - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PasswordView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class PasswordView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.PlainView
            extended by  javax.swing.text.FieldView
                extended by  javax.swing.text.PasswordView
All Implemented Interfaces:
SwingConstants, TabExpander
public class PasswordView
extends FieldView

Implements a View suitable for use in JPasswordField UI implementations. This is basically a field ui that renders its contents as the echo character specified in the associated component (if it can narrow the component to a JPasswordField).

See Also:
View

Field Summary
Fields inherited from class javax.swing.text.PlainView
metrics
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
PasswordView(Element elem)
Constructs a new view wrapped on an element.
Method Summary
protected int | drawEchoCharacter(Graphics g, int x, int y, char c) Renders the echo character, or whatever graphic should be used to display the password characters.
protected int | drawSelectedText(Graphics g, int x, int y, int p0, int p1) Renders the given range in the model as selected text.
protected int | drawUnselectedText(Graphics g, int x, int y, int p0, int p1) Renders the given range in the model as normal unselected text.
float | getPreferredSpan(int axis) Determines the preferred span for this view along an axis.
Shape | modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
int | viewToModel(float fx, float fy, Shape a, Position.Bias[] bias) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
Methods inherited from class javax.swing.text.FieldView
adjustAllocation, getFontMetrics, getResizeWeight, insertUpdate, paint, removeUpdate
Methods inherited from class javax.swing.text.PlainView
changedUpdate, damageLineRange, drawLine, getLineBuffer, getTabSize, lineToRect, nextTabStop, setSize, updateDamage, updateMetrics
Methods inherited from class javax.swing.text.View
append, breakView, createFragment, forwardUpdate, forwardUpdateToView, getAlignment, getAttributes, getBreakWeight, getChildAllocation, getContainer, getDocument, getElement, getEndOffset, getGraphics, getMaximumSpan, getMinimumSpan, getNextVisualPositionFrom, getParent, getStartOffset, getToolTipText, getView, getViewCount, getViewFactory, getViewIndex, getViewIndex, insert, isVisible, modelToView, modelToView, preferenceChanged, remove, removeAll, replace, setParent, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PasswordView

public PasswordView(Element elem)
Constructs a new view wrapped on an element.

Parameters:
elem - the element
Method Detail

drawUnselectedText

protected int drawUnselectedText(Graphics g,
                                 int x,
                                 int y,
                                 int p0,
                                 int p1)
                          throws BadLocationException
Renders the given range in the model as normal unselected text. This sets the foreground color and echos the characters using the value returned by getEchoChar().

Overrides:
drawUnselectedText in class PlainView
Parameters:
g - the graphics context
x - the starting X coordinate >= 0
y - the starting Y coordinate >= 0
p0 - the starting offset in the model >= 0
p1 - the ending offset in the model >= p0
Returns:
the X location of the end of the range >= 0
Throws:
BadLocationException - if p0 or p1 are out of range

drawSelectedText

protected int drawSelectedText(Graphics g,
                               int x,
                               int y,
                               int p0,
                               int p1)
                        throws BadLocationException
Renders the given range in the model as selected text. This is implemented to render the text in the color specified in the hosting component. It assumes the highlighter will render the selected background. Uses the result of getEchoChar() to display the characters.

Overrides:
drawSelectedText in class PlainView
Parameters:
g - the graphics context
x - the starting X coordinate >= 0
y - the starting Y coordinate >= 0
p0 - the starting offset in the model >= 0
p1 - the ending offset in the model >= p0
Returns:
the X location of the end of the range >= 0
Throws:
BadLocationException - if p0 or p1 are out of range

drawEchoCharacter

protected int drawEchoCharacter(Graphics g,
                                int x,
                                int y,
                                char c)
Renders the echo character, or whatever graphic should be used to display the password characters. The color in the Graphics object is set to the appropriate foreground color for selected or unselected text.

Parameters:
g - the graphics context
x - the starting X coordinate >= 0
y - the starting Y coordinate >= 0
c - the echo character
Returns:
the updated X position >= 0

modelToView

public Shape modelToView(int pos,
                         Shape a,
                         Position.Bias b)
                  throws BadLocationException
Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.

Overrides:
modelToView in class FieldView
Parameters:
pos - the position to convert >= 0
a - the allocated region to render into
b - the bias toward the previous character or the next character represented by the offset, in case the position is a boundary of two views; b will have one of these values:
  • Position.Bias.Forward
  • Position.Bias.Backward
Returns:
the bounding box of the given position
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
See Also:
View.modelToView(int, java.awt.Shape, javax.swing.text.Position.Bias)

viewToModel

public int viewToModel(float fx,
                       float fy,
                       Shape a,
                       Position.Bias[] bias)
Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Overrides:
viewToModel in class FieldView
Parameters:
fx - the X coordinate >= 0.0f
fy - the Y coordinate >= 0.0f
a - the allocated region to render into
Returns:
the location within the model that best represents the given point in the view
See Also:
View.viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])

getPreferredSpan

public float getPreferredSpan(int axis)
Determines the preferred span for this view along an axis.

Overrides:
getPreferredSpan in class FieldView
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned, although there is no guarantee. The parent may choose to resize or break the view.
See Also:
View.getPreferredSpan(int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PlainDocument

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class PlainDocument

java.lang.Object
    extended by  javax.swing.text.AbstractDocument
        extended by  javax.swing.text.PlainDocument
All Implemented Interfaces:
Serializable, Document
public class PlainDocument
extends AbstractDocument

A plain document that maintains no character attributes. The default element structure for this document is a map of the lines in the text. The Element returned by getDefaultRootElement is a map of the lines, and each child element represents a line. This model does not maintain any character level attributes, but each line can be tagged with an arbitrary set of attributes. Line to offset, and offset to line translations can be quickly performed using the default root element. The structure information of the DocumentEvent's fired by edits will indicate the line structure changes.

The default content storage management is performed by a gapped buffer implementation (GapContent). It supports editing reasonably large documents with good efficiency when the edits are contiguous or clustered, as is typical.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
Document, AbstractDocument

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.text.AbstractDocument
AbstractDocument.AbstractElement, AbstractDocument.AttributeContext, AbstractDocument.BranchElement, AbstractDocument.Content, AbstractDocument.DefaultDocumentEvent, AbstractDocument.ElementEdit, AbstractDocument.LeafElement
Field Summary
static String | lineLimitAttribute Name of the attribute that specifies the maximum length of a line, if there is a maximum length.
static String | tabSizeAttribute Name of the attribute that specifies the tab size for tabs contained in the content.
Fields inherited from class javax.swing.text.AbstractDocument
BAD_LOCATION, BidiElementName, ContentElementName, ElementNameAttribute, listenerList, ParagraphElementName, SectionElementName
Fields inherited from interface javax.swing.text.Document
StreamDescriptionProperty, TitleProperty
Constructor Summary
PlainDocument()
Constructs a plain text document.
PlainDocument(AbstractDocument.Content c)
Constructs a plain text document.
Method Summary
protected AbstractDocument.AbstractElement | createDefaultRoot() Creates the root element to be used to represent the default document structure.
Element | getDefaultRootElement() Gets the default root element for the document model.
Element | getParagraphElement(int pos) Get the paragraph element containing the given position.
void | insertString(int offs, String str, AttributeSet a) Inserts some content into the document.
protected void | insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr) Updates document structure as a result of text insertion.
protected void | removeUpdate(AbstractDocument.DefaultDocumentEvent chng) Updates any document structure as a result of text removal.
Methods inherited from class javax.swing.text.AbstractDocument
addDocumentListener, addUndoableEditListener, createBranchElement, createLeafElement, createPosition, dump, fireChangedUpdate, fireInsertUpdate, fireRemoveUpdate, fireUndoableEditUpdate, getAsynchronousLoadPriority, getAttributeContext, getBidiRootElement, getContent, getCurrentWriter, getDocumentFilter, getDocumentListeners, getDocumentProperties, getEndPosition, getLength, getListeners, getProperty, getRootElements, getStartPosition, getText, getText, getUndoableEditListeners, postRemoveUpdate, putProperty, readLock, readUnlock, remove, removeDocumentListener, removeUndoableEditListener, render, replace, setAsynchronousLoadPriority, setDocumentFilter, setDocumentProperties, writeLock, writeUnlock
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

tabSizeAttribute

public static final String tabSizeAttribute
Name of the attribute that specifies the tab size for tabs contained in the content. The type for the value is Integer.

See Also:
Constant Field Values

lineLimitAttribute

public static final String lineLimitAttribute
Name of the attribute that specifies the maximum length of a line, if there is a maximum length. The type for the value is Integer.

See Also:
Constant Field Values
Constructor Detail

PlainDocument

public PlainDocument()
Constructs a plain text document. A default model using GapContent is constructed and set.

PlainDocument

public PlainDocument(AbstractDocument.Content c)
Constructs a plain text document. A default root element is created, and the tab size set to 8.

Parameters:
c - the container for the content
Method Detail

insertString

public void insertString(int offs,
                         String str,
                         AttributeSet a)
                  throws BadLocationException
Inserts some content into the document. Inserting content causes a write lock to be held while the actual changes are taking place, followed by notification to the observers on the thread that grabbed the write lock.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Specified by:
insertString in interface Document
Overrides:
insertString in class AbstractDocument
Parameters:
offs - the starting offset >= 0
str - the string to insert; does nothing with null/empty strings
a - the attributes for the inserted content
Throws:
BadLocationException - the given insert position is not a valid position within the document
See Also:
Document.insertString(int, java.lang.String, javax.swing.text.AttributeSet)

getDefaultRootElement

public Element getDefaultRootElement()
Gets the default root element for the document model.

Specified by:
getDefaultRootElement in interface Document
Specified by:
getDefaultRootElement in class AbstractDocument
Returns:
the root
See Also:
Document.getDefaultRootElement()

createDefaultRoot

protected AbstractDocument.AbstractElement createDefaultRoot()
Creates the root element to be used to represent the default document structure.

Returns:
the element base

getParagraphElement

public Element getParagraphElement(int pos)
Get the paragraph element containing the given position. Since this document only models lines, it returns the line instead.

Specified by:
getParagraphElement in class AbstractDocument
Parameters:
pos - the starting offset >= 0
Returns:
the element

insertUpdate

protected void insertUpdate(AbstractDocument.DefaultDocumentEvent chng,
                            AttributeSet attr)
Updates document structure as a result of text insertion. This will happen within a write lock. Since this document simply maps out lines, we refresh the line map.

Overrides:
insertUpdate in class AbstractDocument
Parameters:
chng - the change event describing the dit
attr - the set of attributes for the inserted text

removeUpdate

protected void removeUpdate(AbstractDocument.DefaultDocumentEvent chng)
Updates any document structure as a result of text removal. This will happen within a write lock. Since the structure represents a line map, this just checks to see if the removal spans lines. If it does, the two lines outside of the removal area are joined together.

Overrides:
removeUpdate in class AbstractDocument
Parameters:
chng - the change event describing the edit
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PlainView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class PlainView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.PlainView
All Implemented Interfaces:
SwingConstants, TabExpander
Direct Known Subclasses:
FieldView
public class PlainView
extends View
implements TabExpander

Implements View interface for a simple multi-line text view that has text in one font and color. The view represents each child element as a line of text.

See Also:
View

Field Summary
protected  FontMetrics metrics
Font metrics for the current font.
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
PlainView(Element elem)
Constructs a new PlainView wrapped on an element.
Method Summary
void | changedUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
protected void | damageLineRange(int line0, int line1, Shape a, Component host) Repaint the given line range.
protected void | drawLine(int lineIndex, Graphics g, int x, int y) Renders a line of text, suppressing whitespace at the end and expanding any tabs.
protected int | drawSelectedText(Graphics g, int x, int y, int p0, int p1) Renders the given range in the model as selected text.
protected int | drawUnselectedText(Graphics g, int x, int y, int p0, int p1) Renders the given range in the model as normal unselected text.
protected Segment | getLineBuffer() Gives access to a buffer that can be used to fetch text from the associated document.
float | getPreferredSpan(int axis) Determines the preferred span for this view along an axis.
protected int | getTabSize() Returns the tab size set for the document, defaulting to 8.
void | insertUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
protected Rectangle | lineToRect(Shape a, int line) Determine the rectangle that represents the given line.
Shape | modelToView(int pos, Shape a, Position.Bias b) Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
float | nextTabStop(float x, int tabOffset) Returns the next tab stop position after a given reference position.
void | paint(Graphics g, Shape a) Renders using the given rendering surface and area on that surface.
void | removeUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | setSize(float width, float height) Sets the size of the view.
protected void | updateDamage(DocumentEvent changes, Shape a, ViewFactory f) Repaint the region of change covered by the given document event.
protected void | updateMetrics() Checks to see if the font metrics and longest line are up-to-date.
int | viewToModel(float fx, float fy, Shape a, Position.Bias[] bias) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
Methods inherited from class javax.swing.text.View
append, breakView, createFragment, forwardUpdate, forwardUpdateToView, getAlignment, getAttributes, getBreakWeight, getChildAllocation, getContainer, getDocument, getElement, getEndOffset, getGraphics, getMaximumSpan, getMinimumSpan, getNextVisualPositionFrom, getParent, getResizeWeight, getStartOffset, getToolTipText, getView, getViewCount, getViewFactory, getViewIndex, getViewIndex, insert, isVisible, modelToView, modelToView, preferenceChanged, remove, removeAll, replace, setParent, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

metrics

protected FontMetrics metrics
Font metrics for the current font.

Constructor Detail

PlainView

public PlainView(Element elem)
Constructs a new PlainView wrapped on an element.

Parameters:
elem - the element
Method Detail

getTabSize

protected int getTabSize()
Returns the tab size set for the document, defaulting to 8.

Returns:
the tab size

drawLine

protected void drawLine(int lineIndex,
                        Graphics g,
                        int x,
                        int y)
Renders a line of text, suppressing whitespace at the end and expanding any tabs. This is implemented to make calls to the methods drawUnselectedText and drawSelectedText so that the way selected and unselected text are rendered can be customized.

Parameters:
lineIndex - the line to draw >= 0
g - the Graphics context
x - the starting X position >= 0
y - the starting Y position >= 0
See Also:
drawUnselectedText(java.awt.Graphics, int, int, int, int), drawSelectedText(java.awt.Graphics, int, int, int, int)

drawUnselectedText

protected int drawUnselectedText(Graphics g,
                                 int x,
                                 int y,
                                 int p0,
                                 int p1)
                          throws BadLocationException
Renders the given range in the model as normal unselected text. Uses the foreground or disabled color to render the text.

Parameters:
g - the graphics context
x - the starting X coordinate >= 0
y - the starting Y coordinate >= 0
p0 - the beginning position in the model >= 0
p1 - the ending position in the model >= 0
Returns:
the X location of the end of the range >= 0
Throws:
BadLocationException - if the range is invalid

drawSelectedText

protected int drawSelectedText(Graphics g,
                               int x,
                               int y,
                               int p0,
                               int p1)
                        throws BadLocationException
Renders the given range in the model as selected text. This is implemented to render the text in the color specified in the hosting component. It assumes the highlighter will render the selected background.

Parameters:
g - the graphics context
x - the starting X coordinate >= 0
y - the starting Y coordinate >= 0
p0 - the beginning position in the model >= 0
p1 - the ending position in the model >= 0
Returns:
the location of the end of the range
Throws:
BadLocationException - if the range is invalid

getLineBuffer

protected final Segment getLineBuffer()
Gives access to a buffer that can be used to fetch text from the associated document.

Returns:
the buffer

updateMetrics

protected void updateMetrics()
Checks to see if the font metrics and longest line are up-to-date.

Since:
1.4

getPreferredSpan

public float getPreferredSpan(int axis)
Determines the preferred span for this view along an axis.

Specified by:
getPreferredSpan in class View
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into >= 0. Typically the view is told to render into the span that is returned, although there is no guarantee. The parent may choose to resize or break the view.
Throws:
IllegalArgumentException - for an invalid axis
See Also:
View.getPreferredSpan(int)

paint

public void paint(Graphics g,
                  Shape a)
Renders using the given rendering surface and area on that surface. The view may need to do layout and create child views to enable itself to render into the given allocation.

Specified by:
paint in class View
Parameters:
g - the rendering surface to use
a - the allocated region to render into
See Also:
View.paint(java.awt.Graphics, java.awt.Shape)

modelToView

public Shape modelToView(int pos,
                         Shape a,
                         Position.Bias b)
                  throws BadLocationException
Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.

Specified by:
modelToView in class View
Parameters:
pos - the position to convert >= 0
a - the allocated region to render into
b - the bias toward the previous character or the next character represented by the offset, in case the position is a boundary of two views; b will have one of these values:
  • Position.Bias.Forward
  • Position.Bias.Backward
Returns:
the bounding box of the given position
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
See Also:
View.modelToView(int, java.awt.Shape, javax.swing.text.Position.Bias)

viewToModel

public int viewToModel(float fx,
                       float fy,
                       Shape a,
                       Position.Bias[] bias)
Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Specified by:
viewToModel in class View
Parameters:
fx - the X coordinate >= 0
fy - the Y coordinate >= 0
a - the allocated region to render into
Returns:
the location within the model that best represents the given point in the view >= 0
See Also:
View.viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])

insertUpdate

public void insertUpdate(DocumentEvent changes,
                         Shape a,
                         ViewFactory f)
Gives notification that something was inserted into the document in a location that this view is responsible for.

Overrides:
insertUpdate in class View
Parameters:
changes - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

removeUpdate

public void removeUpdate(DocumentEvent changes,
                         Shape a,
                         ViewFactory f)
Gives notification that something was removed from the document in a location that this view is responsible for.

Overrides:
removeUpdate in class View
Parameters:
changes - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

changedUpdate

public void changedUpdate(DocumentEvent changes,
                          Shape a,
                          ViewFactory f)
Gives notification from the document that attributes were changed in a location that this view is responsible for.

Overrides:
changedUpdate in class View
Parameters:
changes - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

setSize

public void setSize(float width,
                    float height)
Sets the size of the view. This should cause layout of the view along the given axis, if it has any layout duties.

Overrides:
setSize in class View
Parameters:
width - the width >= 0
height - the height >= 0

nextTabStop

public float nextTabStop(float x,
                         int tabOffset)
Returns the next tab stop position after a given reference position. This implementation does not support things like centering so it ignores the tabOffset argument.

Specified by:
nextTabStop in interface TabExpander
Parameters:
x - the current position >= 0
tabOffset - the position within the text stream that the tab occurred at >= 0.
Returns:
the tab stop, measured in points >= 0

updateDamage

protected void updateDamage(DocumentEvent changes,
                            Shape a,
                            ViewFactory f)
Repaint the region of change covered by the given document event. Damages the line that begins the range to cover the case when the insert/remove is only on one line. If lines are added or removed, damages the whole view. The longest line is checked to see if it has changed.

Since:
1.4

damageLineRange

protected void damageLineRange(int line0,
                               int line1,
                               Shape a,
                               Component host)
Repaint the given line range.

Parameters:
host - the component hosting the view (used to call repaint)
a - the region allocated for the view to render into
line0 - the starting line number to repaint. This must be a valid line number in the model.
line1 - the ending line number to repaint. This must be a valid line number in the model.
Since:
1.4

lineToRect

protected Rectangle lineToRect(Shape a,
                               int line)
Determine the rectangle that represents the given line.

Parameters:
a - the region allocated for the view to render into
line - the line number to find the region of. This must be a valid line number in the model.
Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Position

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface Position

public interface Position

Represents a location within a document. It is intended to abstract away implementation details of the document and enable specification of positions within the document that are capable of tracking of change as the document is edited.

A Position object points at a location between two characters. As the surrounding content is altered, the Position object adjusts its offset automatically to reflect the changes. If content is inserted or removed before the Position object's location, then the Position increments or decrements its offset, respectively, so as to point to the same location. If a portion of the document is removed that contains a Position's offset, then the Position's offset becomes that of the beginning of the removed region. For example, if a Position has an offset of 5 and the region 2-10 is removed, then the Position's offset becomes 2.

Position with an offset of 0 is a special case. It never changes its offset while document content is altered.

Nested Class Summary
static class Position.Bias
A typesafe enumeration to indicate bias to a position in the model.
Method Summary
 int getOffset()
Fetches the current offset within the document.

Method Detail

getOffset

int getOffset()
Fetches the current offset within the document.

Returns:
the offset >= 0
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Position.Bias

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class Position.Bias

java.lang.Object
    extended by  javax.swing.text.Position.Bias
Enclosing interface:
Position
public static final class Position.Bias
extends Object

A typesafe enumeration to indicate bias to a position in the model. A position indicates a location between two characters. The bias can be used to indicate an interest toward one of the two sides of the position in boundary conditions where a simple offset is ambiguous.

Field Summary
static Position.Bias | Backward Indicates a bias toward the previous character in the model.
static Position.Bias | Forward Indicates to bias toward the next character in the model.
Method Summary
 String toString()
string representation
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

Forward

public static final Position.Bias Forward
Indicates to bias toward the next character in the model.

Backward

public static final Position.Bias Backward
Indicates a bias toward the previous character in the model.

Method Detail

toString

public String toString()
string representation

Overrides:
toString in class Object
Returns:
a string representation of the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


rtf

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.swing.text.rtf

Provides a class (RTFEditorKit) for creating Rich-Text-Format text editors.

See:
Description

Class Summary
RTFEditorKit This is the default implementation of RTF editing functionality.

Package javax.swing.text.rtf Description

Provides a class (RTFEditorKit) for creating Rich-Text-Format text editors.

Note: Most of the Swing API is not thread safe. For details, see Threads and Swing, a section in The Java Tutorial.

Since:
1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.swing.text.rtf Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.swing.text.rtf

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.swing.text.EditorKit (implements java.lang.Cloneable, java.io.Serializable)
      • javax.swing.text.DefaultEditorKit
        • javax.swing.text.StyledEditorKit
          • javax.swing.text.rtf.RTFEditorKit
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.swing.text.rtf

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.swing.text.rtf

No usage of javax.swing.text.rtf

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.text.rtf.RTFEditorKit

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.text.rtf.RTFEditorKit

No usage of javax.swing.text.rtf.RTFEditorKit

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


RTFEditorKit

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.text.rtf
Class RTFEditorKit

java.lang.Object
    extended by  javax.swing.text.EditorKit
        extended by  javax.swing.text.DefaultEditorKit
            extended by  javax.swing.text.StyledEditorKit
                extended by  javax.swing.text.rtf.RTFEditorKit
All Implemented Interfaces:
Serializable, Cloneable
public class RTFEditorKit
extends StyledEditorKit

This is the default implementation of RTF editing functionality. The RTF support was not written by the Swing team. In the future we hope to improve the support provided.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.text.StyledEditorKit
StyledEditorKit.AlignmentAction, StyledEditorKit.BoldAction, StyledEditorKit.FontFamilyAction, StyledEditorKit.FontSizeAction, StyledEditorKit.ForegroundAction, StyledEditorKit.ItalicAction, StyledEditorKit.StyledTextAction, StyledEditorKit.UnderlineAction
Nested classes/interfaces inherited from class javax.swing.text.DefaultEditorKit
DefaultEditorKit.BeepAction, DefaultEditorKit.CopyAction, DefaultEditorKit.CutAction, DefaultEditorKit.DefaultKeyTypedAction, DefaultEditorKit.InsertBreakAction, DefaultEditorKit.InsertContentAction, DefaultEditorKit.InsertTabAction, DefaultEditorKit.PasteAction
Field Summary
Fields inherited from class javax.swing.text.DefaultEditorKit
backwardAction, beepAction, beginAction, beginLineAction, beginParagraphAction, beginWordAction, copyAction, cutAction, defaultKeyTypedAction, deleteNextCharAction, deleteNextWordAction, deletePrevCharAction, deletePrevWordAction, downAction, endAction, endLineAction, EndOfLineStringProperty, endParagraphAction, endWordAction, forwardAction, insertBreakAction, insertContentAction, insertTabAction, nextWordAction, pageDownAction, pageUpAction, pasteAction, previousWordAction, readOnlyAction, selectAllAction, selectionBackwardAction, selectionBeginAction, selectionBeginLineAction, selectionBeginParagraphAction, selectionBeginWordAction, selectionDownAction, selectionEndAction, selectionEndLineAction, selectionEndParagraphAction, selectionEndWordAction, selectionForwardAction, selectionNextWordAction, selectionPreviousWordAction, selectionUpAction, selectLineAction, selectParagraphAction, selectWordAction, upAction, writableAction
Constructor Summary
RTFEditorKit()
Constructs an RTFEditorKit.
Method Summary
String | getContentType() Get the MIME type of the data that this kit represents support for.
void | read(InputStream in, Document doc, int pos) Insert content from the given stream which is expected to be in a format appropriate for this kind of content handler.
void | read(Reader in, Document doc, int pos) Insert content from the given stream, which will be treated as plain text.
void | write(OutputStream out, Document doc, int pos, int len) Write content from a document to the given stream in a format appropriate for this kind of content handler.
void | write(Writer out, Document doc, int pos, int len) Write content from a document to the given stream as plain text.
Methods inherited from class javax.swing.text.StyledEditorKit
clone, createDefaultDocument, createInputAttributes, deinstall, getActions, getCharacterAttributeRun, getInputAttributes, getViewFactory, install
Methods inherited from class javax.swing.text.DefaultEditorKit
createCaret
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RTFEditorKit

public RTFEditorKit()
Constructs an RTFEditorKit.

Method Detail

getContentType

public String getContentType()
Get the MIME type of the data that this kit represents support for. This kit supports the type text/rtf.

Overrides:
getContentType in class DefaultEditorKit
Returns:
the type

read

public void read(InputStream in,
                 Document doc,
                 int pos)
          throws IOException,
                 BadLocationException
Insert content from the given stream which is expected to be in a format appropriate for this kind of content handler.

Overrides:
read in class DefaultEditorKit
Parameters:
in - The stream to read from
doc - The destination for the insertion.
pos - The location in the document to place the content.
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

write

public void write(OutputStream out,
                  Document doc,
                  int pos,
                  int len)
           throws IOException,
                  BadLocationException
Write content from a document to the given stream in a format appropriate for this kind of content handler.

Overrides:
write in class DefaultEditorKit
Parameters:
out - The stream to write to
doc - The source for the write.
pos - The location in the document to fetch the content.
len - The amount to write out.
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

read

public void read(Reader in,
                 Document doc,
                 int pos)
          throws IOException,
                 BadLocationException
Insert content from the given stream, which will be treated as plain text.

Overrides:
read in class DefaultEditorKit
Parameters:
in - The stream to read from
doc - The destination for the insertion.
pos - The location in the document to place the content.
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.

write

public void write(Writer out,
                  Document doc,
                  int pos,
                  int len)
           throws IOException,
                  BadLocationException
Write content from a document to the given stream as plain text.

Overrides:
write in class DefaultEditorKit
Parameters:
out - The stream to write to
doc - The source for the write.
pos - The location in the document to fetch the content.
len - The amount to write out.
Throws:
IOException - on any I/O error
BadLocationException - if pos represents an invalid location within the document.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Segment

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class Segment

java.lang.Object
    extended by  javax.swing.text.Segment
All Implemented Interfaces:
CharSequence, Cloneable, CharacterIterator
public class Segment
extends Object
implements Cloneable, CharacterIterator, CharSequence

A segment of a character array representing a fragment of text. It should be treated as immutable even though the array is directly accessible. This gives fast access to fragments of text without the overhead of copying around characters. This is effectively an unprotected String.

The Segment implements the java.text.CharacterIterator interface to support use with the i18n support without copying text into a string.

Field Summary
char[] | array This is the array containing the text of interest.
int | count This is the number of array elements that make up the text of interest.
int | offset This is the offset into the array that the desired text begins.
Fields inherited from interface java.text.CharacterIterator
DONE
Constructor Summary
Segment()
Creates a new segment.
Segment(char[] array, int offset, int count)
Creates a new segment referring to an existing array.
Method Summary
 char charAt(int index)
Returns the char value at the specified index.
 Object clone()
Creates a shallow copy.
 char current()
Gets the character at the current position (as returned by getIndex()).
 char first()
Sets the position to getBeginIndex() and returns the character at that position.
 int getBeginIndex()
Returns the start index of the text.
 int getEndIndex()
Returns the end index of the text.
 int getIndex()
Returns the current index.
 boolean isPartialReturn()
Flag to indicate that partial returns are valid.
 char last()
Sets the position to getEndIndex()-1 (getEndIndex() if the text is empty) and returns the character at that position.
 int length()
Returns the length of this character sequence.
 char next()
Increments the iterator's index by one and returns the character at the new index.
 char previous()
Decrements the iterator's index by one and returns the character at the new index.
 char setIndex(int position)
Sets the position to the specified position in the text and returns that character.
 void setPartialReturn(boolean p)
Flag to indicate that partial returns are valid.
 CharSequence subSequence(int start, int end)
Returns a new CharSequence that is a subsequence of this sequence.
 String toString()
Converts a segment into a String.
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

array

public char[] array
This is the array containing the text of interest. This array should never be modified; it is available only for efficiency.

offset

public int offset
This is the offset into the array that the desired text begins.

count

public int count
This is the number of array elements that make up the text of interest.

Constructor Detail

Segment

public Segment()
Creates a new segment.

Segment

public Segment(char[] array,
               int offset,
               int count)
Creates a new segment referring to an existing array.

Parameters:
array - the array to refer to
offset - the offset into the array
count - the number of characters
Method Detail

setPartialReturn

public void setPartialReturn(boolean p)
Flag to indicate that partial returns are valid. If the flag is true, an implementation of the interface method Document.getText(position,length,Segment) should return as much text as possible without making a copy. The default state of the flag is false which will cause Document.getText(position,length,Segment) to provide the same return behavior it always had, which may or may not make a copy of the text depending upon the request.

Parameters:
p - whether or not partial returns are valid.
Since:
1.4

isPartialReturn

public boolean isPartialReturn()
Flag to indicate that partial returns are valid.

Returns:
whether or not partial returns are valid.
Since:
1.4

toString

public String toString()
Converts a segment into a String.

Specified by:
toString in interface CharSequence
Overrides:
toString in class Object
Returns:
the string

first

public char first()
Sets the position to getBeginIndex() and returns the character at that position.

Specified by:
first in interface CharacterIterator
Returns:
the first character in the text, or DONE if the text is empty
Since:
1.3
See Also:
getBeginIndex()

last

public char last()
Sets the position to getEndIndex()-1 (getEndIndex() if the text is empty) and returns the character at that position.

Specified by:
last in interface CharacterIterator
Returns:
the last character in the text, or DONE if the text is empty
Since:
1.3
See Also:
getEndIndex()

current

public char current()
Gets the character at the current position (as returned by getIndex()).

Specified by:
current in interface CharacterIterator
Returns:
the character at the current position or DONE if the current position is off the end of the text.
Since:
1.3
See Also:
getIndex()

next

public char next()
Increments the iterator's index by one and returns the character at the new index. If the resulting index is greater or equal to getEndIndex(), the current index is reset to getEndIndex() and a value of DONE is returned.

Specified by:
next in interface CharacterIterator
Returns:
the character at the new position or DONE if the new position is off the end of the text range.
Since:
1.3

previous

public char previous()
Decrements the iterator's index by one and returns the character at the new index. If the current index is getBeginIndex(), the index remains at getBeginIndex() and a value of DONE is returned.

Specified by:
previous in interface CharacterIterator
Returns:
the character at the new position or DONE if the current position is equal to getBeginIndex().
Since:
1.3

setIndex

public char setIndex(int position)
Sets the position to the specified position in the text and returns that character.

Specified by:
setIndex in interface CharacterIterator
Parameters:
position - the position within the text. Valid values range from getBeginIndex() to getEndIndex(). An IllegalArgumentException is thrown if an invalid value is supplied.
Returns:
the character at the specified position or DONE if the specified position is equal to getEndIndex()
Since:
1.3

getBeginIndex

public int getBeginIndex()
Returns the start index of the text.

Specified by:
getBeginIndex in interface CharacterIterator
Returns:
the index at which the text begins.
Since:
1.3

getEndIndex

public int getEndIndex()
Returns the end index of the text. This index is the index of the first character following the end of the text.

Specified by:
getEndIndex in interface CharacterIterator
Returns:
the index after the last character in the text
Since:
1.3

getIndex

public int getIndex()
Returns the current index.

Specified by:
getIndex in interface CharacterIterator
Returns:
the current index.
Since:
1.3

charAt

public char charAt(int index)
Returns the char value at the specified index. An index ranges from zero to length() - 1. The first char value of the sequence is at index zero, the next at index one, and so on, as for array indexing.

If the char value specified by the index is a surrogate, the surrogate value is returned.

Specified by:
charAt in interface CharSequence
Parameters:
index - the index of the char value to be returned
Returns:
the specified char value
Since:
1.6

length

public int length()
Returns the length of this character sequence. The length is the number of 16-bit chars in the sequence.

Specified by:
length in interface CharSequence
Returns:
the number of chars in this sequence
Since:
1.6

subSequence

public CharSequence subSequence(int start,
                                int end)
Returns a new CharSequence that is a subsequence of this sequence. The subsequence starts with the char value at the specified index and ends with the char value at index end - 1. The length (in chars) of the returned sequence is end - start, so if start == end then an empty sequence is returned.

Specified by:
subSequence in interface CharSequence
Parameters:
start - the start index, inclusive
end - the end index, exclusive
Returns:
the specified subsequence
Since:
1.6

clone

public Object clone()
Creates a shallow copy.

Specified by:
clone in interface CharacterIterator
Overrides:
clone in class Object
Returns:
the copy
See Also:
Cloneable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SimpleAttributeSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class SimpleAttributeSet

java.lang.Object
    extended by  javax.swing.text.SimpleAttributeSet
All Implemented Interfaces:
Serializable, Cloneable, AttributeSet, MutableAttributeSet
public class SimpleAttributeSet
extends Object
implements MutableAttributeSet, Serializable, Cloneable

A straightforward implementation of MutableAttributeSet using a hash table.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from interface javax.swing.text.AttributeSet
AttributeSet.CharacterAttribute, AttributeSet.ColorAttribute, AttributeSet.FontAttribute, AttributeSet.ParagraphAttribute
Field Summary
static AttributeSet EMPTY
An empty attribute set.
Fields inherited from interface javax.swing.text.AttributeSet
NameAttribute, ResolveAttribute
Constructor Summary
SimpleAttributeSet()
Creates a new attribute set.
SimpleAttributeSet(AttributeSet source)
Creates a new attribute set based on a supplied set of attributes.
Method Summary
void | addAttribute(Object name, Object value) Adds an attribute to the list.
void | addAttributes(AttributeSet attributes) Adds a set of attributes to the list.
Object | clone() Clones a set of attributes.
boolean | containsAttribute(Object name, Object value) Checks whether the attribute list contains a specified attribute name/value pair.
boolean | containsAttributes(AttributeSet attributes) Checks whether the attribute list contains all the specified name/value pairs.
AttributeSet | copyAttributes() Makes a copy of the attributes.
boolean | equals(Object obj) Compares this object to the specified object.
Object | getAttribute(Object name) Gets the value of an attribute.
int | getAttributeCount() Gets a count of the number of attributes.
Enumeration<?> | getAttributeNames() Gets the names of the attributes in the set.
AttributeSet | getResolveParent() Gets the resolving parent.
int | hashCode() Returns a hashcode for this set of attributes.
boolean | isDefined(Object attrName) Tells whether a given attribute is defined.
boolean | isEmpty() Checks whether the set of attributes is empty.
boolean | isEqual(AttributeSet attr) Compares two attribute sets.
void | removeAttribute(Object name) Removes an attribute from the list.
void | removeAttributes(AttributeSet attributes) Removes a set of attributes from the list.
void | removeAttributes(Enumeration<?> names) Removes a set of attributes from the list.
void | setResolveParent(AttributeSet parent) Sets the resolving parent.
String | toString() Converts the attribute set to a String.
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY

public static final AttributeSet EMPTY
An empty attribute set.

Constructor Detail

SimpleAttributeSet

public SimpleAttributeSet()
Creates a new attribute set.

SimpleAttributeSet

public SimpleAttributeSet(AttributeSet source)
Creates a new attribute set based on a supplied set of attributes.

Parameters:
source - the set of attributes
Method Detail

isEmpty

public boolean isEmpty()
Checks whether the set of attributes is empty.

Returns:
true if the set is empty else false

getAttributeCount

public int getAttributeCount()
Gets a count of the number of attributes.

Specified by:
getAttributeCount in interface AttributeSet
Returns:
the count

isDefined

public boolean isDefined(Object attrName)
Tells whether a given attribute is defined.

Specified by:
isDefined in interface AttributeSet
Parameters:
attrName - the attribute name
Returns:
true if the attribute is defined

isEqual

public boolean isEqual(AttributeSet attr)
Compares two attribute sets.

Specified by:
isEqual in interface AttributeSet
Parameters:
attr - the second attribute set
Returns:
true if the sets are equal, false otherwise

copyAttributes

public AttributeSet copyAttributes()
Makes a copy of the attributes.

Specified by:
copyAttributes in interface AttributeSet
Returns:
the copy

getAttributeNames

public Enumeration<?> getAttributeNames()
Gets the names of the attributes in the set.

Specified by:
getAttributeNames in interface AttributeSet
Returns:
the names as an Enumeration

getAttribute

public Object getAttribute(Object name)
Gets the value of an attribute.

Specified by:
getAttribute in interface AttributeSet
Parameters:
name - the attribute name
Returns:
the value

containsAttribute

public boolean containsAttribute(Object name,
                                 Object value)
Checks whether the attribute list contains a specified attribute name/value pair.

Specified by:
containsAttribute in interface AttributeSet
Parameters:
name - the name
value - the value
Returns:
true if the name/value pair is in the list

containsAttributes

public boolean containsAttributes(AttributeSet attributes)
Checks whether the attribute list contains all the specified name/value pairs.

Specified by:
containsAttributes in interface AttributeSet
Parameters:
attributes - the attribute list
Returns:
true if the list contains all the name/value pairs

addAttribute

public void addAttribute(Object name,
                         Object value)
Adds an attribute to the list.

Specified by:
addAttribute in interface MutableAttributeSet
Parameters:
name - the attribute name
value - the attribute value

addAttributes

public void addAttributes(AttributeSet attributes)
Adds a set of attributes to the list.

Specified by:
addAttributes in interface MutableAttributeSet
Parameters:
attributes - the set of attributes to add

removeAttribute

public void removeAttribute(Object name)
Removes an attribute from the list.

Specified by:
removeAttribute in interface MutableAttributeSet
Parameters:
name - the attribute name

removeAttributes

public void removeAttributes(Enumeration<?> names)
Removes a set of attributes from the list.

Specified by:
removeAttributes in interface MutableAttributeSet
Parameters:
names - the set of names to remove

removeAttributes

public void removeAttributes(AttributeSet attributes)
Removes a set of attributes from the list.

Specified by:
removeAttributes in interface MutableAttributeSet
Parameters:
attributes - the set of attributes to remove

getResolveParent

public AttributeSet getResolveParent()
Gets the resolving parent. This is the set of attributes to resolve through if an attribute isn't defined locally. This is null if there are no other sets of attributes to resolve through.

Specified by:
getResolveParent in interface AttributeSet
Returns:
the parent

setResolveParent

public void setResolveParent(AttributeSet parent)
Sets the resolving parent.

Specified by:
setResolveParent in interface MutableAttributeSet
Parameters:
parent - the parent

clone

public Object clone()
Clones a set of attributes.

Overrides:
clone in class Object
Returns:
the new set of attributes
See Also:
Cloneable

hashCode

public int hashCode()
Returns a hashcode for this set of attributes.

Overrides:
hashCode in class Object
Returns:
a hashcode value for this set of attributes.
See Also:
Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object obj)
Compares this object to the specified object. The result is true if the object is an equivalent set of attributes.

Overrides:
equals in class Object
Parameters:
obj - the object to compare this attribute set with
Returns:
true if the objects are equal; false otherwise
See Also:
Object.hashCode(), Hashtable

toString

public String toString()
Converts the attribute set to a String.

Overrides:
toString in class Object
Returns:
the string
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StringContent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StringContent

java.lang.Object
    extended by  javax.swing.text.StringContent
All Implemented Interfaces:
Serializable, AbstractDocument.Content
public final class StringContent
extends Object
implements AbstractDocument.Content, Serializable

An implementation of the AbstractDocument.Content interface that is a brute force implementation that is useful for relatively small documents and/or debugging. It manages the character content as a simple character array. It is also quite inefficient.

It is generally recommended that the gap buffer or piece table implementations be used instead. This buffer does not scale up to large sizes.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
StringContent()
Creates a new StringContent object.
StringContent(int initialLength)
Creates a new StringContent object, with the initial size specified.
Method Summary
Position | createPosition(int offset) Creates a position within the content that will track change as the content is mutated.
void | getChars(int where, int len, Segment chars) Retrieves a portion of the content.
protected Vector | getPositionsInRange(Vector v, int offset, int length) Returns a Vector containing instances of UndoPosRef for the Positions in the range offset to offset + length.
String | getString(int where, int len) Retrieves a portion of the content.
UndoableEdit | insertString(int where, String str) Inserts a string into the content.
int | length() Returns the length of the content.
UndoableEdit | remove(int where, int nitems) Removes part of the content.
protected void | updateUndoPositions(Vector positions) Resets the location for all the UndoPosRef instances in positions.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StringContent

public StringContent()
Creates a new StringContent object. Initial size defaults to 10.

StringContent

public StringContent(int initialLength)
Creates a new StringContent object, with the initial size specified. If the length is < 1, a size of 1 is used.

Parameters:
initialLength - the initial size
Method Detail

length

public int length()
Returns the length of the content.

Specified by:
length in interface AbstractDocument.Content
Returns:
the length >= 1
See Also:
AbstractDocument.Content.length()

insertString

public UndoableEdit insertString(int where,
                                 String str)
                          throws BadLocationException
Inserts a string into the content.

Specified by:
insertString in interface AbstractDocument.Content
Parameters:
where - the starting position >= 0 && < length()
str - the non-null string to insert
Returns:
an UndoableEdit object for undoing
Throws:
BadLocationException - if the specified position is invalid
See Also:
AbstractDocument.Content.insertString(int, java.lang.String)

remove

public UndoableEdit remove(int where,
                           int nitems)
                    throws BadLocationException
Removes part of the content. where + nitems must be < length().

Specified by:
remove in interface AbstractDocument.Content
Parameters:
where - the starting position >= 0
nitems - the number of characters to remove >= 0
Returns:
an UndoableEdit object for undoing
Throws:
BadLocationException - if the specified position is invalid
See Also:
AbstractDocument.Content.remove(int, int)

getString

public String getString(int where,
                        int len)
                 throws BadLocationException
Retrieves a portion of the content. where + len must be <= length().="length()."
Specified by:
getString in interface AbstractDocument.Content
Parameters:
where - the starting position >= 0
len - the length to retrieve >= 0
Returns:
a string representing the content; may be empty
Throws:
BadLocationException - if the specified position is invalid
See Also:
AbstractDocument.Content.getString(int, int)

getChars

public void getChars(int where,
                     int len,
                     Segment chars)
              throws BadLocationException
Retrieves a portion of the content. where + len must be <= length()="length()"
Specified by:
getChars in interface AbstractDocument.Content
Parameters:
where - the starting position >= 0
len - the number of characters to retrieve >= 0
chars - the Segment object to return the characters in
Throws:
BadLocationException - if the specified position is invalid
See Also:
AbstractDocument.Content.getChars(int, int, javax.swing.text.Segment)

createPosition

public Position createPosition(int offset)
                        throws BadLocationException
Creates a position within the content that will track change as the content is mutated.

Specified by:
createPosition in interface AbstractDocument.Content
Parameters:
offset - the offset to create a position for >= 0
Returns:
the position
Throws:
BadLocationException - if the specified position is invalid

getPositionsInRange

protected Vector getPositionsInRange(Vector v,
                                     int offset,
                                     int length)
Returns a Vector containing instances of UndoPosRef for the Positions in the range offset to offset + length. If v is not null the matching Positions are placed in there. The vector with the resulting Positions are returned.

This is meant for internal usage, and is generally not of interest to subclasses.

Parameters:
v - the Vector to use, with a new one created on null
offset - the starting offset >= 0
length - the length >= 0
Returns:
the set of instances

updateUndoPositions

protected void updateUndoPositions(Vector positions)
Resets the location for all the UndoPosRef instances in positions.

This is meant for internal usage, and is generally not of interest to subclasses.

Parameters:
positions - the positions of the instances
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Style

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface Style

All Superinterfaces:
AttributeSet, MutableAttributeSet
All Known Implementing Classes:
StyleContext.NamedStyle
public interface Style
extends MutableAttributeSet

A collection of attributes to associate with an element in a document. Since these are typically used to associate character and paragraph styles with the element, operations for this are provided. Other customized attributes that get associated with the element will effectively be name-value pairs that live in a hierarchy and if a name (key) is not found locally, the request is forwarded to the parent. Commonly used attributes are separated out to facilitate alternative implementations that are more efficient.

Nested Class Summary
Nested classes/interfaces inherited from interface javax.swing.text.AttributeSet
AttributeSet.CharacterAttribute, AttributeSet.ColorAttribute, AttributeSet.FontAttribute, AttributeSet.ParagraphAttribute
Field Summary
Fields inherited from interface javax.swing.text.AttributeSet
NameAttribute, ResolveAttribute
Method Summary
void | addChangeListener(ChangeListener l) Adds a listener to track whenever an attribute has been changed.
String | getName() Fetches the name of the style.
void | removeChangeListener(ChangeListener l) Removes a listener that was tracking attribute changes.
Methods inherited from interface javax.swing.text.MutableAttributeSet
addAttribute, addAttributes, removeAttribute, removeAttributes, removeAttributes, setResolveParent
Methods inherited from interface javax.swing.text.AttributeSet
containsAttribute, containsAttributes, copyAttributes, getAttribute, getAttributeCount, getAttributeNames, getResolveParent, isDefined, isEqual

Method Detail

getName

String getName()
Fetches the name of the style. A style is not required to be named, so null is returned if there is no name associated with the style.

Returns:
the name

addChangeListener

void addChangeListener(ChangeListener l)
Adds a listener to track whenever an attribute has been changed.

Parameters:
l - the change listener

removeChangeListener

void removeChangeListener(ChangeListener l)
Removes a listener that was tracking attribute changes.

Parameters:
l - the change listener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyleConstants

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StyleConstants

java.lang.Object
    extended by  javax.swing.text.StyleConstants
Direct Known Subclasses:
StyleConstants.CharacterConstants, StyleConstants.ColorConstants, StyleConstants.FontConstants, StyleConstants.ParagraphConstants
public class StyleConstants
extends Object

A collection of well known or common attribute keys and methods to apply to an AttributeSet or MutableAttributeSet to get/set the properties in a typesafe manner.

The paragraph attributes form the definition of a paragraph to be rendered. All sizes are specified in points (such as found in postscript), a device independent measure.

Diagram shows SpaceAbove, FirstLineIndent, LeftIndent, RightIndent, and SpaceBelow a paragraph.

Nested Class Summary
static class | StyleConstants.CharacterConstants This is a typesafe enumeration of the well-known attributes that contribute to a character style.
static class | StyleConstants.ColorConstants This is a typesafe enumeration of the well-known attributes that contribute to a color.
static class | StyleConstants.FontConstants This is a typesafe enumeration of the well-known attributes that contribute to a font.
static class | StyleConstants.ParagraphConstants This is a typesafe enumeration of the well-known attributes that contribute to a paragraph style.
Field Summary
static int | ALIGN_CENTER A possible value for paragraph alignment.
static int | ALIGN_JUSTIFIED A possible value for paragraph alignment.
static int | ALIGN_LEFT A possible value for paragraph alignment.
static int | ALIGN_RIGHT A possible value for paragraph alignment.
static Object | Alignment Alignment for the paragraph.
static Object | Background Name of the background color attribute.
static Object | BidiLevel Bidirectional level of a character as assigned by the Unicode bidi algorithm.
static Object | Bold Name of the bold attribute.
static Object | ComponentAttribute Name of the component attribute.
static String | ComponentElementName Name of elements used to represent components.
static Object | ComposedTextAttribute Name of the input method composed text attribute.
static Object | Family Name of the font family.
static Object | FirstLineIndent The amount of space to indent the first line of the paragraph.
static Object | FontFamily Name of the font family.
static Object | FontSize Name of the font size.
static Object | Foreground Name of the foreground color attribute.
static Object | IconAttribute Name of the icon attribute.
static String | IconElementName Name of elements used to represent icons.
static Object | Italic Name of the italic attribute.
static Object | LeftIndent The amount to indent the left side of the paragraph.
static Object | LineSpacing The amount of space between lines of the paragraph.
static Object | ModelAttribute Attribute used to identify the model for embedded objects that have a model view separation.
static Object | NameAttribute Attribute name used to name the collection of attributes.
static Object | Orientation Orientation for a paragraph.
static Object | ResolveAttribute Attribute name used to identifiy the resolving parent set of attributes, if one is defined.
static Object | RightIndent The amount to indent the right side of the paragraph.
static Object | Size Name of the font size.
static Object | SpaceAbove The amount of space above the paragraph.
static Object | SpaceBelow The amount of space below the paragraph.
static Object | StrikeThrough Name of the Strikethrough attribute.
static Object | Subscript Name of the Subscript attribute.
static Object | Superscript Name of the Superscript attribute.
static Object | TabSet TabSet for the paragraph, type is a TabSet containing TabStops.
static Object | Underline Name of the underline attribute.
Method Summary
static int | getAlignment(AttributeSet a) Gets the alignment setting.
static Color | getBackground(AttributeSet a) Gets the background color setting from the attribute list.
static int | getBidiLevel(AttributeSet a) Gets the BidiLevel setting.
static Component | getComponent(AttributeSet a) Gets the component setting from the attribute list.
static float | getFirstLineIndent(AttributeSet a) Gets the first line indent setting.
static String | getFontFamily(AttributeSet a) Gets the font family setting from the attribute list.
static int | getFontSize(AttributeSet a) Gets the font size setting from the attribute list.
static Color | getForeground(AttributeSet a) Gets the foreground color setting from the attribute list.
static Icon | getIcon(AttributeSet a) Gets the icon setting from the attribute list.
static float | getLeftIndent(AttributeSet a) Gets the left indent setting.
static float | getLineSpacing(AttributeSet a) Gets the line spacing setting.
static float | getRightIndent(AttributeSet a) Gets the right indent setting.
static float | getSpaceAbove(AttributeSet a) Gets the space above setting.
static float | getSpaceBelow(AttributeSet a) Gets the space below setting.
static TabSet | getTabSet(AttributeSet a) Gets the TabSet.
static boolean | isBold(AttributeSet a) Checks whether the bold attribute is set.
static boolean | isItalic(AttributeSet a) Checks whether the italic attribute is set.
static boolean | isStrikeThrough(AttributeSet a) Checks whether the strikethrough attribute is set.
static boolean | isSubscript(AttributeSet a) Checks whether the subscript attribute is set.
static boolean | isSuperscript(AttributeSet a) Checks whether the superscript attribute is set.
static boolean | isUnderline(AttributeSet a) Checks whether the underline attribute is set.
static void | setAlignment(MutableAttributeSet a, int align) Sets alignment.
static void | setBackground(MutableAttributeSet a, Color fg) Sets the background color.
static void | setBidiLevel(MutableAttributeSet a, int o) Sets the BidiLevel.
static void | setBold(MutableAttributeSet a, boolean b) Sets the bold attribute.
static void | setComponent(MutableAttributeSet a, Component c) Sets the component attribute.
static void | setFirstLineIndent(MutableAttributeSet a, float i) Sets the first line indent.
static void | setFontFamily(MutableAttributeSet a, String fam) Sets the font attribute.
static void | setFontSize(MutableAttributeSet a, int s) Sets the font size attribute.
static void | setForeground(MutableAttributeSet a, Color fg) Sets the foreground color.
static void | setIcon(MutableAttributeSet a, Icon c) Sets the icon attribute.
static void | setItalic(MutableAttributeSet a, boolean b) Sets the italic attribute.
static void | setLeftIndent(MutableAttributeSet a, float i) Sets left indent.
static void | setLineSpacing(MutableAttributeSet a, float i) Sets line spacing.
static void | setRightIndent(MutableAttributeSet a, float i) Sets right indent.
static void | setSpaceAbove(MutableAttributeSet a, float i) Sets space above.
static void | setSpaceBelow(MutableAttributeSet a, float i) Sets space below.
static void | setStrikeThrough(MutableAttributeSet a, boolean b) Sets the strikethrough attribute.
static void | setSubscript(MutableAttributeSet a, boolean b) Sets the subscript attribute.
static void | setSuperscript(MutableAttributeSet a, boolean b) Sets the superscript attribute.
static void | setTabSet(MutableAttributeSet a, TabSet tabs) Sets the TabSet.
static void | setUnderline(MutableAttributeSet a, boolean b) Sets the underline attribute.
String | toString() Returns the string representation.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ComponentElementName

public static final String ComponentElementName
Name of elements used to represent components.

See Also:
Constant Field Values

IconElementName

public static final String IconElementName
Name of elements used to represent icons.

See Also:
Constant Field Values

NameAttribute

public static final Object NameAttribute
Attribute name used to name the collection of attributes.

ResolveAttribute

public static final Object ResolveAttribute
Attribute name used to identifiy the resolving parent set of attributes, if one is defined.

ModelAttribute

public static final Object ModelAttribute
Attribute used to identify the model for embedded objects that have a model view separation.

BidiLevel

public static final Object BidiLevel
Bidirectional level of a character as assigned by the Unicode bidi algorithm.

FontFamily

public static final Object FontFamily
Name of the font family.

Family

public static final Object Family
Name of the font family.

Since:
1.5

FontSize

public static final Object FontSize
Name of the font size.

Size

public static final Object Size
Name of the font size.

Since:
1.5

Bold

public static final Object Bold
Name of the bold attribute.

Italic

public static final Object Italic
Name of the italic attribute.

Underline

public static final Object Underline
Name of the underline attribute.

StrikeThrough

public static final Object StrikeThrough
Name of the Strikethrough attribute.

Superscript

public static final Object Superscript
Name of the Superscript attribute.

Subscript

public static final Object Subscript
Name of the Subscript attribute.

Foreground

public static final Object Foreground
Name of the foreground color attribute.

Background

public static final Object Background
Name of the background color attribute.

ComponentAttribute

public static final Object ComponentAttribute
Name of the component attribute.

IconAttribute

public static final Object IconAttribute
Name of the icon attribute.

ComposedTextAttribute

public static final Object ComposedTextAttribute
Name of the input method composed text attribute. The value of this attribute is an instance of AttributedString which represents the composed text.

FirstLineIndent

public static final Object FirstLineIndent
The amount of space to indent the first line of the paragraph. This value may be negative to offset in the reverse direction. The type is Float and specifies the size of the space in points.

LeftIndent

public static final Object LeftIndent
The amount to indent the left side of the paragraph. Type is float and specifies the size in points.

RightIndent

public static final Object RightIndent
The amount to indent the right side of the paragraph. Type is float and specifies the size in points.

LineSpacing

public static final Object LineSpacing
The amount of space between lines of the paragraph. Type is float and specifies the size as a factor of the line height

SpaceAbove

public static final Object SpaceAbove
The amount of space above the paragraph. Type is float and specifies the size in points.

SpaceBelow

public static final Object SpaceBelow
The amount of space below the paragraph. Type is float and specifies the size in points.

Alignment

public static final Object Alignment
Alignment for the paragraph. The type is Integer. Valid values are:
  • ALIGN_LEFT
  • ALIGN_RIGHT
  • ALIGN_CENTER
  • ALIGN_JUSTIFED

TabSet

public static final Object TabSet
TabSet for the paragraph, type is a TabSet containing TabStops.

Orientation

public static final Object Orientation
Orientation for a paragraph.

ALIGN_LEFT

public static final int ALIGN_LEFT
A possible value for paragraph alignment. This specifies that the text is aligned to the left indent and extra whitespace should be placed on the right.

See Also:
Constant Field Values

ALIGN_CENTER

public static final int ALIGN_CENTER
A possible value for paragraph alignment. This specifies that the text is aligned to the center and extra whitespace should be placed equally on the left and right.

See Also:
Constant Field Values

ALIGN_RIGHT

public static final int ALIGN_RIGHT
A possible value for paragraph alignment. This specifies that the text is aligned to the right indent and extra whitespace should be placed on the left.

See Also:
Constant Field Values

ALIGN_JUSTIFIED

public static final int ALIGN_JUSTIFIED
A possible value for paragraph alignment. This specifies that extra whitespace should be spread out through the rows of the paragraph with the text lined up with the left and right indent except on the last line which should be aligned to the left.

See Also:
Constant Field Values
Method Detail

toString

public String toString()
Returns the string representation.

Overrides:
toString in class Object
Returns:
the string

getBidiLevel

public static int getBidiLevel(AttributeSet a)
Gets the BidiLevel setting.

Parameters:
a - the attribute set
Returns:
the value

setBidiLevel

public static void setBidiLevel(MutableAttributeSet a,
                                int o)
Sets the BidiLevel.

Parameters:
a - the attribute set
o - the bidi level value

getComponent

public static Component getComponent(AttributeSet a)
Gets the component setting from the attribute list.

Parameters:
a - the attribute set
Returns:
the component, null if none

setComponent

public static void setComponent(MutableAttributeSet a,
                                Component c)
Sets the component attribute.

Parameters:
a - the attribute set
c - the component

getIcon

public static Icon getIcon(AttributeSet a)
Gets the icon setting from the attribute list.

Parameters:
a - the attribute set
Returns:
the icon, null if none

setIcon

public static void setIcon(MutableAttributeSet a,
                           Icon c)
Sets the icon attribute.

Parameters:
a - the attribute set
c - the icon

getFontFamily

public static String getFontFamily(AttributeSet a)
Gets the font family setting from the attribute list.

Parameters:
a - the attribute set
Returns:
the font family, "Monospaced" as the default

setFontFamily

public static void setFontFamily(MutableAttributeSet a,
                                 String fam)
Sets the font attribute.

Parameters:
a - the attribute set
fam - the font

getFontSize

public static int getFontSize(AttributeSet a)
Gets the font size setting from the attribute list.

Parameters:
a - the attribute set
Returns:
the font size, 12 as the default

setFontSize

public static void setFontSize(MutableAttributeSet a,
                               int s)
Sets the font size attribute.

Parameters:
a - the attribute set
s - the font size

isBold

public static boolean isBold(AttributeSet a)
Checks whether the bold attribute is set.

Parameters:
a - the attribute set
Returns:
true if set else false

setBold

public static void setBold(MutableAttributeSet a,
                           boolean b)
Sets the bold attribute.

Parameters:
a - the attribute set
b - specifies true/false for setting the attribute

isItalic

public static boolean isItalic(AttributeSet a)
Checks whether the italic attribute is set.

Parameters:
a - the attribute set
Returns:
true if set else false

setItalic

public static void setItalic(MutableAttributeSet a,
                             boolean b)
Sets the italic attribute.

Parameters:
a - the attribute set
b - specifies true/false for setting the attribute

isUnderline

public static boolean isUnderline(AttributeSet a)
Checks whether the underline attribute is set.

Parameters:
a - the attribute set
Returns:
true if set else false

isStrikeThrough

public static boolean isStrikeThrough(AttributeSet a)
Checks whether the strikethrough attribute is set.

Parameters:
a - the attribute set
Returns:
true if set else false

isSuperscript

public static boolean isSuperscript(AttributeSet a)
Checks whether the superscript attribute is set.

Parameters:
a - the attribute set
Returns:
true if set else false

isSubscript

public static boolean isSubscript(AttributeSet a)
Checks whether the subscript attribute is set.

Parameters:
a - the attribute set
Returns:
true if set else false

setUnderline

public static void setUnderline(MutableAttributeSet a,
                                boolean b)
Sets the underline attribute.

Parameters:
a - the attribute set
b - specifies true/false for setting the attribute

setStrikeThrough

public static void setStrikeThrough(MutableAttributeSet a,
                                    boolean b)
Sets the strikethrough attribute.

Parameters:
a - the attribute set
b - specifies true/false for setting the attribute

setSuperscript

public static void setSuperscript(MutableAttributeSet a,
                                  boolean b)
Sets the superscript attribute.

Parameters:
a - the attribute set
b - specifies true/false for setting the attribute

setSubscript

public static void setSubscript(MutableAttributeSet a,
                                boolean b)
Sets the subscript attribute.

Parameters:
a - the attribute set
b - specifies true/false for setting the attribute

getForeground

public static Color getForeground(AttributeSet a)
Gets the foreground color setting from the attribute list.

Parameters:
a - the attribute set
Returns:
the color, Color.black as the default

setForeground

public static void setForeground(MutableAttributeSet a,
                                 Color fg)
Sets the foreground color.

Parameters:
a - the attribute set
fg - the color

getBackground

public static Color getBackground(AttributeSet a)
Gets the background color setting from the attribute list.

Parameters:
a - the attribute set
Returns:
the color, Color.black as the default

setBackground

public static void setBackground(MutableAttributeSet a,
                                 Color fg)
Sets the background color.

Parameters:
a - the attribute set
fg - the color

getFirstLineIndent

public static float getFirstLineIndent(AttributeSet a)
Gets the first line indent setting.

Parameters:
a - the attribute set
Returns:
the value, 0 if not set

setFirstLineIndent

public static void setFirstLineIndent(MutableAttributeSet a,
                                      float i)
Sets the first line indent.

Parameters:
a - the attribute set
i - the value

getRightIndent

public static float getRightIndent(AttributeSet a)
Gets the right indent setting.

Parameters:
a - the attribute set
Returns:
the value, 0 if not set

setRightIndent

public static void setRightIndent(MutableAttributeSet a,
                                  float i)
Sets right indent.

Parameters:
a - the attribute set
i - the value

getLeftIndent

public static float getLeftIndent(AttributeSet a)
Gets the left indent setting.

Parameters:
a - the attribute set
Returns:
the value, 0 if not set

setLeftIndent

public static void setLeftIndent(MutableAttributeSet a,
                                 float i)
Sets left indent.

Parameters:
a - the attribute set
i - the value

getLineSpacing

public static float getLineSpacing(AttributeSet a)
Gets the line spacing setting.

Parameters:
a - the attribute set
Returns:
the value, 0 if not set

setLineSpacing

public static void setLineSpacing(MutableAttributeSet a,
                                  float i)
Sets line spacing.

Parameters:
a - the attribute set
i - the value

getSpaceAbove

public static float getSpaceAbove(AttributeSet a)
Gets the space above setting.

Parameters:
a - the attribute set
Returns:
the value, 0 if not set

setSpaceAbove

public static void setSpaceAbove(MutableAttributeSet a,
                                 float i)
Sets space above.

Parameters:
a - the attribute set
i - the value

getSpaceBelow

public static float getSpaceBelow(AttributeSet a)
Gets the space below setting.

Parameters:
a - the attribute set
Returns:
the value, 0 if not set

setSpaceBelow

public static void setSpaceBelow(MutableAttributeSet a,
                                 float i)
Sets space below.

Parameters:
a - the attribute set
i - the value

getAlignment

public static int getAlignment(AttributeSet a)
Gets the alignment setting.

Parameters:
a - the attribute set
Returns:
the value StyleConstants.ALIGN_LEFT if not set

setAlignment

public static void setAlignment(MutableAttributeSet a,
                                int align)
Sets alignment.

Parameters:
a - the attribute set
align - the alignment value

getTabSet

public static TabSet getTabSet(AttributeSet a)
Gets the TabSet.

Parameters:
a - the attribute set
Returns:
the TabSet

setTabSet

public static void setTabSet(MutableAttributeSet a,
                             TabSet tabs)
Sets the TabSet.

Parameters:
a - the attribute set.
tabs - the TabSet
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyleConstants.CharacterConstants

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StyleConstants.CharacterConstants

java.lang.Object
    extended by  javax.swing.text.StyleConstants
        extended by  javax.swing.text.StyleConstants.CharacterConstants
All Implemented Interfaces:
AttributeSet.CharacterAttribute
Enclosing class:
StyleConstants
public static class StyleConstants.CharacterConstants
extends StyleConstants
implements AttributeSet.CharacterAttribute

This is a typesafe enumeration of the well-known attributes that contribute to a character style. These are aliased by the outer class for general presentation.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.text.StyleConstants
StyleConstants.CharacterConstants, StyleConstants.ColorConstants, StyleConstants.FontConstants, StyleConstants.ParagraphConstants
Field Summary
Fields inherited from class javax.swing.text.StyleConstants
ALIGN_CENTER, ALIGN_JUSTIFIED, ALIGN_LEFT, ALIGN_RIGHT, Alignment, Background, BidiLevel, Bold, ComponentAttribute, ComponentElementName, ComposedTextAttribute, Family, FirstLineIndent, FontFamily, FontSize, Foreground, IconAttribute, IconElementName, Italic, LeftIndent, LineSpacing, ModelAttribute, NameAttribute, Orientation, ResolveAttribute, RightIndent, Size, SpaceAbove, SpaceBelow, StrikeThrough, Subscript, Superscript, TabSet, Underline
Method Summary
Methods inherited from class javax.swing.text.StyleConstants
getAlignment, getBackground, getBidiLevel, getComponent, getFirstLineIndent, getFontFamily, getFontSize, getForeground, getIcon, getLeftIndent, getLineSpacing, getRightIndent, getSpaceAbove, getSpaceBelow, getTabSet, isBold, isItalic, isStrikeThrough, isSubscript, isSuperscript, isUnderline, setAlignment, setBackground, setBidiLevel, setBold, setComponent, setFirstLineIndent, setFontFamily, setFontSize, setForeground, setIcon, setItalic, setLeftIndent, setLineSpacing, setRightIndent, setSpaceAbove, setSpaceBelow, setStrikeThrough, setSubscript, setSuperscript, setTabSet, setUnderline, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyleConstants.ColorConstants

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StyleConstants.ColorConstants

java.lang.Object
    extended by  javax.swing.text.StyleConstants
        extended by  javax.swing.text.StyleConstants.ColorConstants
All Implemented Interfaces:
AttributeSet.CharacterAttribute, AttributeSet.ColorAttribute
Enclosing class:
StyleConstants
public static class StyleConstants.ColorConstants
extends StyleConstants
implements AttributeSet.ColorAttribute, AttributeSet.CharacterAttribute

This is a typesafe enumeration of the well-known attributes that contribute to a color. These are aliased by the outer class for general presentation.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.text.StyleConstants
StyleConstants.CharacterConstants, StyleConstants.ColorConstants, StyleConstants.FontConstants, StyleConstants.ParagraphConstants
Field Summary
Fields inherited from class javax.swing.text.StyleConstants
ALIGN_CENTER, ALIGN_JUSTIFIED, ALIGN_LEFT, ALIGN_RIGHT, Alignment, Background, BidiLevel, Bold, ComponentAttribute, ComponentElementName, ComposedTextAttribute, Family, FirstLineIndent, FontFamily, FontSize, Foreground, IconAttribute, IconElementName, Italic, LeftIndent, LineSpacing, ModelAttribute, NameAttribute, Orientation, ResolveAttribute, RightIndent, Size, SpaceAbove, SpaceBelow, StrikeThrough, Subscript, Superscript, TabSet, Underline
Method Summary
Methods inherited from class javax.swing.text.StyleConstants
getAlignment, getBackground, getBidiLevel, getComponent, getFirstLineIndent, getFontFamily, getFontSize, getForeground, getIcon, getLeftIndent, getLineSpacing, getRightIndent, getSpaceAbove, getSpaceBelow, getTabSet, isBold, isItalic, isStrikeThrough, isSubscript, isSuperscript, isUnderline, setAlignment, setBackground, setBidiLevel, setBold, setComponent, setFirstLineIndent, setFontFamily, setFontSize, setForeground, setIcon, setItalic, setLeftIndent, setLineSpacing, setRightIndent, setSpaceAbove, setSpaceBelow, setStrikeThrough, setSubscript, setSuperscript, setTabSet, setUnderline, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyleConstants.FontConstants

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StyleConstants.FontConstants

java.lang.Object
    extended by  javax.swing.text.StyleConstants
        extended by  javax.swing.text.StyleConstants.FontConstants
All Implemented Interfaces:
AttributeSet.CharacterAttribute, AttributeSet.FontAttribute
Enclosing class:
StyleConstants
public static class StyleConstants.FontConstants
extends StyleConstants
implements AttributeSet.FontAttribute, AttributeSet.CharacterAttribute

This is a typesafe enumeration of the well-known attributes that contribute to a font. These are aliased by the outer class for general presentation.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.text.StyleConstants
StyleConstants.CharacterConstants, StyleConstants.ColorConstants, StyleConstants.FontConstants, StyleConstants.ParagraphConstants
Field Summary
Fields inherited from class javax.swing.text.StyleConstants
ALIGN_CENTER, ALIGN_JUSTIFIED, ALIGN_LEFT, ALIGN_RIGHT, Alignment, Background, BidiLevel, Bold, ComponentAttribute, ComponentElementName, ComposedTextAttribute, Family, FirstLineIndent, FontFamily, FontSize, Foreground, IconAttribute, IconElementName, Italic, LeftIndent, LineSpacing, ModelAttribute, NameAttribute, Orientation, ResolveAttribute, RightIndent, Size, SpaceAbove, SpaceBelow, StrikeThrough, Subscript, Superscript, TabSet, Underline
Method Summary
Methods inherited from class javax.swing.text.StyleConstants
getAlignment, getBackground, getBidiLevel, getComponent, getFirstLineIndent, getFontFamily, getFontSize, getForeground, getIcon, getLeftIndent, getLineSpacing, getRightIndent, getSpaceAbove, getSpaceBelow, getTabSet, isBold, isItalic, isStrikeThrough, isSubscript, isSuperscript, isUnderline, setAlignment, setBackground, setBidiLevel, setBold, setComponent, setFirstLineIndent, setFontFamily, setFontSize, setForeground, setIcon, setItalic, setLeftIndent, setLineSpacing, setRightIndent, setSpaceAbove, setSpaceBelow, setStrikeThrough, setSubscript, setSuperscript, setTabSet, setUnderline, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyleConstants.ParagraphConstants

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StyleConstants.ParagraphConstants

java.lang.Object
    extended by  javax.swing.text.StyleConstants
        extended by  javax.swing.text.StyleConstants.ParagraphConstants
All Implemented Interfaces:
AttributeSet.ParagraphAttribute
Enclosing class:
StyleConstants
public static class StyleConstants.ParagraphConstants
extends StyleConstants
implements AttributeSet.ParagraphAttribute

This is a typesafe enumeration of the well-known attributes that contribute to a paragraph style. These are aliased by the outer class for general presentation.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.text.StyleConstants
StyleConstants.CharacterConstants, StyleConstants.ColorConstants, StyleConstants.FontConstants, StyleConstants.ParagraphConstants
Field Summary
Fields inherited from class javax.swing.text.StyleConstants
ALIGN_CENTER, ALIGN_JUSTIFIED, ALIGN_LEFT, ALIGN_RIGHT, Alignment, Background, BidiLevel, Bold, ComponentAttribute, ComponentElementName, ComposedTextAttribute, Family, FirstLineIndent, FontFamily, FontSize, Foreground, IconAttribute, IconElementName, Italic, LeftIndent, LineSpacing, ModelAttribute, NameAttribute, Orientation, ResolveAttribute, RightIndent, Size, SpaceAbove, SpaceBelow, StrikeThrough, Subscript, Superscript, TabSet, Underline
Method Summary
Methods inherited from class javax.swing.text.StyleConstants
getAlignment, getBackground, getBidiLevel, getComponent, getFirstLineIndent, getFontFamily, getFontSize, getForeground, getIcon, getLeftIndent, getLineSpacing, getRightIndent, getSpaceAbove, getSpaceBelow, getTabSet, isBold, isItalic, isStrikeThrough, isSubscript, isSuperscript, isUnderline, setAlignment, setBackground, setBidiLevel, setBold, setComponent, setFirstLineIndent, setFontFamily, setFontSize, setForeground, setIcon, setItalic, setLeftIndent, setLineSpacing, setRightIndent, setSpaceAbove, setSpaceBelow, setStrikeThrough, setSubscript, setSuperscript, setTabSet, setUnderline, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyleContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StyleContext

java.lang.Object
    extended by  javax.swing.text.StyleContext
All Implemented Interfaces:
Serializable, AbstractDocument.AttributeContext
Direct Known Subclasses:
StyleSheet
public class StyleContext
extends Object
implements Serializable, AbstractDocument.AttributeContext

A pool of styles and their associated resources. This class determines the lifetime of a group of resources by being a container that holds caches for various resources such as font and color that get reused by the various style definitions. This can be shared by multiple documents if desired to maximize the sharing of related resources.

This class also provides efficient support for small sets of attributes and compresses them by sharing across uses and taking advantage of their immutable nature. Since many styles are replicated, the potential for sharing is significant, and copies can be extremely cheap. Larger sets reduce the possibility of sharing, and therefore revert automatically to a less space-efficient implementation.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
class | StyleContext.NamedStyle A collection of attributes, typically used to represent character and paragraph styles.
class | StyleContext.SmallAttributeSet This class holds a small number of attributes in an array.
Field Summary
static String DEFAULT_STYLE
The name given to the default logical style attached to paragraphs.
Constructor Summary
StyleContext()
Creates a new StyleContext object.
Method Summary
 AttributeSet addAttribute(AttributeSet old, Object name, Object value)
Adds an attribute to the given set, and returns the new representative set.
 AttributeSet addAttributes(AttributeSet old, AttributeSet attr)
Adds a set of attributes to the element.
 void addChangeListener(ChangeListener l)
Adds a listener to track when styles are added or removed.
 Style addStyle(String nm, Style parent)
Adds a new style into the style hierarchy.
protected  MutableAttributeSet createLargeAttributeSet(AttributeSet a)
Create a large set of attributes that should trade off space for time.
protected  StyleContext.SmallAttributeSet createSmallAttributeSet(AttributeSet a)
Create a compact set of attributes that might be shared.
 Color getBackground(AttributeSet attr)
Takes a set of attributes and turn it into a background color specification.
 ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this StyleContext with addChangeListener().
protected  int getCompressionThreshold()
Returns the maximum number of key/value pairs to try and compress into unique/immutable sets.
static StyleContext getDefaultStyleContext()
Returns default AttributeContext shared by all documents that don't bother to define/supply their own context.
 AttributeSet getEmptySet()
Fetches an empty AttributeSet.
 Font getFont(AttributeSet attr)
Gets the font from an attribute set.
 Font getFont(String family, int style, int size)
Gets a new font.
 FontMetrics getFontMetrics(Font f)
Returns font metrics for a font.
 Color getForeground(AttributeSet attr)
Takes a set of attributes and turn it into a foreground color specification.
static Object getStaticAttribute(Object key)
Returns the object previously registered with registerStaticAttributeKey.
static Object getStaticAttributeKey(Object key)
Returns the String that key will be registered with
 Style getStyle(String nm)
Fetches a named style previously added to the document
 Enumeration<?> getStyleNames()
Fetches the names of the styles defined.
 void readAttributes(ObjectInputStream in, MutableAttributeSet a)
Context-specific handling of reading in attributes
static void readAttributeSet(ObjectInputStream in, MutableAttributeSet a)
Reads a set of attributes from the given object input stream that have been previously written out with writeAttributeSet.
 void reclaim(AttributeSet a)
Returns a set no longer needed by the MutableAttributeSet implmentation.
static void registerStaticAttributeKey(Object key)
Registers an object as a static object that is being used as a key in attribute sets.
 AttributeSet removeAttribute(AttributeSet old, Object name)
Removes an attribute from the set.
 AttributeSet removeAttributes(AttributeSet old, AttributeSet attrs)
Removes a set of attributes for the element.
 AttributeSet removeAttributes(AttributeSet old, Enumeration<?> names)
Removes a set of attributes for the element.
 void removeChangeListener(ChangeListener l)
Removes a listener that was tracking styles being added or removed.
 void removeStyle(String nm)
Removes a named style previously added to the document.
 String toString()
Converts a StyleContext to a String.
 void writeAttributes(ObjectOutputStream out, AttributeSet a)
Context-specific handling of writing out attributes
static void writeAttributeSet(ObjectOutputStream out, AttributeSet a)
Writes a set of attributes to the given object stream for the purpose of serialization.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_STYLE

public static final String DEFAULT_STYLE
The name given to the default logical style attached to paragraphs.

See Also:
Constant Field Values
Constructor Detail

StyleContext

public StyleContext()
Creates a new StyleContext object.

Method Detail

getDefaultStyleContext

public static final StyleContext getDefaultStyleContext()
Returns default AttributeContext shared by all documents that don't bother to define/supply their own context.

Returns:
the context

addStyle

public Style addStyle(String nm,
                      Style parent)
Adds a new style into the style hierarchy. Style attributes resolve from bottom up so an attribute specified in a child will override an attribute specified in the parent.

Parameters:
nm - the name of the style (must be unique within the collection of named styles in the document). The name may be null if the style is unnamed, but the caller is responsible for managing the reference returned as an unnamed style can't be fetched by name. An unnamed style may be useful for things like character attribute overrides such as found in a style run.
parent - the parent style. This may be null if unspecified attributes need not be resolved in some other style.
Returns:
the created style

removeStyle

public void removeStyle(String nm)
Removes a named style previously added to the document.

Parameters:
nm - the name of the style to remove

getStyle

public Style getStyle(String nm)
Fetches a named style previously added to the document

Parameters:
nm - the name of the style
Returns:
the style

getStyleNames

public Enumeration<?> getStyleNames()
Fetches the names of the styles defined.

Returns:
the list of names as an enumeration

addChangeListener

public void addChangeListener(ChangeListener l)
Adds a listener to track when styles are added or removed.

Parameters:
l - the change listener

removeChangeListener

public void removeChangeListener(ChangeListener l)
Removes a listener that was tracking styles being added or removed.

Parameters:
l - the change listener

getChangeListeners

public ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this StyleContext with addChangeListener().

Returns:
all of the ChangeListeners added or an empty array if no listeners have been added
Since:
1.4

getFont

public Font getFont(AttributeSet attr)
Gets the font from an attribute set. This is implemented to try and fetch a cached font for the given AttributeSet, and if that fails the font features are resolved and the font is fetched from the low-level font cache.

Parameters:
attr - the attribute set
Returns:
the font

getForeground

public Color getForeground(AttributeSet attr)
Takes a set of attributes and turn it into a foreground color specification. This might be used to specify things like brighter, more hue, etc. By default it simply returns the value specified by the StyleConstants.Foreground attribute.

Parameters:
attr - the set of attributes
Returns:
the color

getBackground

public Color getBackground(AttributeSet attr)
Takes a set of attributes and turn it into a background color specification. This might be used to specify things like brighter, more hue, etc. By default it simply returns the value specified by the StyleConstants.Background attribute.

Parameters:
attr - the set of attributes
Returns:
the color

getFont

public Font getFont(String family,
                    int style,
                    int size)
Gets a new font. This returns a Font from a cache if a cached font exists. If not, a Font is added to the cache. This is basically a low-level cache for 1.1 font features.

Parameters:
family - the font family (such as "Monospaced")
style - the style of the font (such as Font.PLAIN)
size - the point size >= 1
Returns:
the new font

getFontMetrics

public FontMetrics getFontMetrics(Font f)
Returns font metrics for a font.

Parameters:
f - the font
Returns:
the metrics

addAttribute

public AttributeSet addAttribute(AttributeSet old,
                                 Object name,
                                 Object value)
Adds an attribute to the given set, and returns the new representative set.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Specified by:
addAttribute in interface AbstractDocument.AttributeContext
Parameters:
old - the old attribute set
name - the non-null attribute name
value - the attribute value
Returns:
the updated attribute set
See Also:
MutableAttributeSet.addAttribute(java.lang.Object, java.lang.Object)

addAttributes

public AttributeSet addAttributes(AttributeSet old,
                                  AttributeSet attr)
Adds a set of attributes to the element.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Specified by:
addAttributes in interface AbstractDocument.AttributeContext
Parameters:
old - the old attribute set
attr - the attributes to add
Returns:
the updated attribute set
See Also:
MutableAttributeSet.addAttribute(java.lang.Object, java.lang.Object)

removeAttribute

public AttributeSet removeAttribute(AttributeSet old,
                                    Object name)
Removes an attribute from the set.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Specified by:
removeAttribute in interface AbstractDocument.AttributeContext
Parameters:
old - the old set of attributes
name - the non-null attribute name
Returns:
the updated attribute set
See Also:
MutableAttributeSet.removeAttribute(java.lang.Object)

removeAttributes

public AttributeSet removeAttributes(AttributeSet old,
                                     Enumeration<?> names)
Removes a set of attributes for the element.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Specified by:
removeAttributes in interface AbstractDocument.AttributeContext
Parameters:
old - the old attribute set
names - the attribute names
Returns:
the updated attribute set
See Also:
MutableAttributeSet.removeAttributes(java.util.Enumeration)

removeAttributes

public AttributeSet removeAttributes(AttributeSet old,
                                     AttributeSet attrs)
Removes a set of attributes for the element.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Specified by:
removeAttributes in interface AbstractDocument.AttributeContext
Parameters:
old - the old attribute set
attrs - the attributes
Returns:
the updated attribute set
See Also:
MutableAttributeSet.removeAttributes(java.util.Enumeration)

getEmptySet

public AttributeSet getEmptySet()
Fetches an empty AttributeSet.

Specified by:
getEmptySet in interface AbstractDocument.AttributeContext
Returns:
the set

reclaim

public void reclaim(AttributeSet a)
Returns a set no longer needed by the MutableAttributeSet implmentation. This is useful for operation under 1.1 where there are no weak references. This would typically be called by the finalize method of the MutableAttributeSet implementation.

This method is thread safe, although most Swing methods are not. Please see How to Use Threads for more information.

Specified by:
reclaim in interface AbstractDocument.AttributeContext
Parameters:
a - the set to reclaim

getCompressionThreshold

protected int getCompressionThreshold()
Returns the maximum number of key/value pairs to try and compress into unique/immutable sets. Any sets above this limit will use hashtables and be a MutableAttributeSet.

Returns:
the threshold

createSmallAttributeSet

protected StyleContext.SmallAttributeSet createSmallAttributeSet(AttributeSet a)
Create a compact set of attributes that might be shared. This is a hook for subclasses that want to alter the behavior of SmallAttributeSet. This can be reimplemented to return an AttributeSet that provides some sort of attribute conversion.

Parameters:
a - The set of attributes to be represented in the the compact form.

createLargeAttributeSet

protected MutableAttributeSet createLargeAttributeSet(AttributeSet a)
Create a large set of attributes that should trade off space for time. This set will not be shared. This is a hook for subclasses that want to alter the behavior of the larger attribute storage format (which is SimpleAttributeSet by default). This can be reimplemented to return a MutableAttributeSet that provides some sort of attribute conversion.

Parameters:
a - The set of attributes to be represented in the the larger form.

toString

public String toString()
Converts a StyleContext to a String.

Overrides:
toString in class Object
Returns:
the string

writeAttributes

public void writeAttributes(ObjectOutputStream out,
                            AttributeSet a)
                     throws IOException
Context-specific handling of writing out attributes

Throws:
IOException

readAttributes

public void readAttributes(ObjectInputStream in,
                           MutableAttributeSet a)
                    throws ClassNotFoundException,
                           IOException
Context-specific handling of reading in attributes

Throws:
ClassNotFoundException
IOException

writeAttributeSet

public static void writeAttributeSet(ObjectOutputStream out,
                                     AttributeSet a)
                              throws IOException
Writes a set of attributes to the given object stream for the purpose of serialization. This will take special care to deal with static attribute keys that have been registered wit the registerStaticAttributeKey method. Any attribute key not regsitered as a static key will be serialized directly. All values are expected to be serializable.

Parameters:
out - the output stream
a - the attribute set
Throws:
IOException - on any I/O error

readAttributeSet

public static void readAttributeSet(ObjectInputStream in,
                                    MutableAttributeSet a)
                             throws ClassNotFoundException,
                                    IOException
Reads a set of attributes from the given object input stream that have been previously written out with writeAttributeSet. This will try to restore keys that were static objects to the static objects in the current virtual machine considering only those keys that have been registered with the registerStaticAttributeKey method. The attributes retrieved from the stream will be placed into the given mutable set.

Parameters:
in - the object stream to read the attribute data from.
a - the attribute set to place the attribute definitions in.
Throws:
ClassNotFoundException - passed upward if encountered when reading the object stream.
IOException - passed upward if encountered when reading the object stream.

registerStaticAttributeKey

public static void registerStaticAttributeKey(Object key)
Registers an object as a static object that is being used as a key in attribute sets. This allows the key to be treated specially for serialization.

For operation under a 1.1 virtual machine, this uses the value returned by toString concatenated to the classname. The value returned by toString should not have the class reference in it (ie it should be reimplemented from the definition in Object) in order to be the same when recomputed later.

Parameters:
key - the non-null object key

getStaticAttribute

public static Object getStaticAttribute(Object key)
Returns the object previously registered with registerStaticAttributeKey.

getStaticAttributeKey

public static Object getStaticAttributeKey(Object key)
Returns the String that key will be registered with

See Also:
getStaticAttribute(java.lang.Object), registerStaticAttributeKey(java.lang.Object)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyleContext.NamedStyle

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StyleContext.NamedStyle

java.lang.Object
    extended by  javax.swing.text.StyleContext.NamedStyle
All Implemented Interfaces:
Serializable, AttributeSet, MutableAttributeSet, Style
Enclosing class:
StyleContext
public class StyleContext.NamedStyle
extends Object
implements Style, Serializable

A collection of attributes, typically used to represent character and paragraph styles. This is an implementation of MutableAttributeSet that can be observed if desired. These styles will take advantage of immutability while the sets are small enough, and may be substantially more efficient than something like SimpleAttributeSet.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from interface javax.swing.text.AttributeSet
AttributeSet.CharacterAttribute, AttributeSet.ColorAttribute, AttributeSet.FontAttribute, AttributeSet.ParagraphAttribute
Field Summary
protected ChangeEvent | changeEvent Only one ChangeEvent is needed per model instance since the event's only (read-only) state is the source property.
protected EventListenerList | listenerList The change listeners for the model.
Fields inherited from interface javax.swing.text.AttributeSet
NameAttribute, ResolveAttribute
Constructor Summary
StyleContext.NamedStyle()
Creates a new named style, with a null name and parent.
StyleContext.NamedStyle(String name, Style parent)
Creates a new named style.
StyleContext.NamedStyle(Style parent)
Creates a new named style.
Method Summary
 void addAttribute(Object name, Object value)
Adds an attribute.
 void addAttributes(AttributeSet attr)
Adds a set of attributes to the element.
 void addChangeListener(ChangeListener l)
Adds a change listener.
 boolean containsAttribute(Object name, Object value)
Checks whether a given attribute name/value is defined.
 boolean containsAttributes(AttributeSet attrs)
Checks whether the element contains all the attributes.
 AttributeSet copyAttributes()
Copies a set of attributes.
protected  void fireStateChanged()
Notifies all listeners that have registered interest for notification on this event type.
 Object getAttribute(Object attrName)
Gets the value of an attribute.
 int getAttributeCount()
Gets the number of attributes that are defined.
 Enumeration<?> getAttributeNames()
Gets the names of all attributes.
 ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this NamedStyle with addChangeListener().
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
Return an array of all the listeners of the given type that were added to this model.
 String getName()
Fetches the name of the style.
 AttributeSet getResolveParent()
Gets attributes from the parent.
 boolean isDefined(Object attrName)
Checks whether a given attribute is defined.
 boolean isEqual(AttributeSet attr)
Checks whether two attribute sets are equal.
 void removeAttribute(Object name)
Removes an attribute from the set.
 void removeAttributes(AttributeSet attrs)
Removes a set of attributes for the element.
 void removeAttributes(Enumeration<?> names)
Removes a set of attributes for the element.
 void removeChangeListener(ChangeListener l)
Removes a change listener.
 void setName(String name)
Changes the name of the style.
 void setResolveParent(AttributeSet parent)
Sets the resolving parent.
 String toString()
Converts the style to a string.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

listenerList

protected EventListenerList listenerList
The change listeners for the model.

changeEvent

protected transient ChangeEvent changeEvent
Only one ChangeEvent is needed per model instance since the event's only (read-only) state is the source property. The source of events generated here is always "this".

Constructor Detail

StyleContext.NamedStyle

public StyleContext.NamedStyle(String name,
                               Style parent)
Creates a new named style.

Parameters:
name - the style name, null for unnamed
parent - the parent style, null if none
Since:
1.4

StyleContext.NamedStyle

public StyleContext.NamedStyle(Style parent)
Creates a new named style.

Parameters:
parent - the parent style, null if none
Since:
1.4

StyleContext.NamedStyle

public StyleContext.NamedStyle()
Creates a new named style, with a null name and parent.

Method Detail

toString

public String toString()
Converts the style to a string.

Overrides:
toString in class Object
Returns:
the string

getName

public String getName()
Fetches the name of the style. A style is not required to be named, so null is returned if there is no name associated with the style.

Specified by:
getName in interface Style
Returns:
the name

setName

public void setName(String name)
Changes the name of the style. Does nothing with a null name.

Parameters:
name - the new name

addChangeListener

public void addChangeListener(ChangeListener l)
Adds a change listener.

Specified by:
addChangeListener in interface Style
Parameters:
l - the change listener

removeChangeListener

public void removeChangeListener(ChangeListener l)
Removes a change listener.

Specified by:
removeChangeListener in interface Style
Parameters:
l - the change listener

getChangeListeners

public ChangeListener[] getChangeListeners()
Returns an array of all the ChangeListeners added to this NamedStyle with addChangeListener().

Returns:
all of the ChangeListeners added or an empty array if no listeners have been added
Since:
1.4

fireStateChanged

protected void fireStateChanged()
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

See Also:
EventListenerList

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Return an array of all the listeners of the given type that were added to this model.

Returns:
all of the objects receiving listenerType notifications from this model
Since:
1.3

getAttributeCount

public int getAttributeCount()
Gets the number of attributes that are defined.

Specified by:
getAttributeCount in interface AttributeSet
Returns:
the number of attributes >= 0
See Also:
AttributeSet.getAttributeCount()

isDefined

public boolean isDefined(Object attrName)
Checks whether a given attribute is defined.

Specified by:
isDefined in interface AttributeSet
Parameters:
attrName - the non-null attribute name
Returns:
true if the attribute is defined
See Also:
AttributeSet.isDefined(java.lang.Object)

isEqual

public boolean isEqual(AttributeSet attr)
Checks whether two attribute sets are equal.

Specified by:
isEqual in interface AttributeSet
Parameters:
attr - the attribute set to check against
Returns:
true if the same
See Also:
AttributeSet.isEqual(javax.swing.text.AttributeSet)

copyAttributes

public AttributeSet copyAttributes()
Copies a set of attributes.

Specified by:
copyAttributes in interface AttributeSet
Returns:
the copy
See Also:
AttributeSet.copyAttributes()

getAttribute

public Object getAttribute(Object attrName)
Gets the value of an attribute.

Specified by:
getAttribute in interface AttributeSet
Parameters:
attrName - the non-null attribute name
Returns:
the attribute value
See Also:
AttributeSet.getAttribute(java.lang.Object)

getAttributeNames

public Enumeration<?> getAttributeNames()
Gets the names of all attributes.

Specified by:
getAttributeNames in interface AttributeSet
Returns:
the attribute names as an enumeration
See Also:
AttributeSet.getAttributeNames()

containsAttribute

public boolean containsAttribute(Object name,
                                 Object value)
Checks whether a given attribute name/value is defined.

Specified by:
containsAttribute in interface AttributeSet
Parameters:
name - the non-null attribute name
value - the attribute value
Returns:
true if the name/value is defined
See Also:
AttributeSet.containsAttribute(java.lang.Object, java.lang.Object)

containsAttributes

public boolean containsAttributes(AttributeSet attrs)
Checks whether the element contains all the attributes.

Specified by:
containsAttributes in interface AttributeSet
Parameters:
attrs - the attributes to check
Returns:
true if the element contains all the attributes
See Also:
AttributeSet.containsAttributes(javax.swing.text.AttributeSet)

getResolveParent

public AttributeSet getResolveParent()
Gets attributes from the parent. If not overriden, the resolving parent defaults to the parent element.

Specified by:
getResolveParent in interface AttributeSet
Returns:
the attributes from the parent
See Also:
AttributeSet.getResolveParent()

addAttribute

public void addAttribute(Object name,
                         Object value)
Adds an attribute.

Specified by:
addAttribute in interface MutableAttributeSet
Parameters:
name - the non-null attribute name
value - the attribute value
See Also:
MutableAttributeSet.addAttribute(java.lang.Object, java.lang.Object)

addAttributes

public void addAttributes(AttributeSet attr)
Adds a set of attributes to the element.

Specified by:
addAttributes in interface MutableAttributeSet
Parameters:
attr - the attributes to add
See Also:
MutableAttributeSet.addAttribute(java.lang.Object, java.lang.Object)

removeAttribute

public void removeAttribute(Object name)
Removes an attribute from the set.

Specified by:
removeAttribute in interface MutableAttributeSet
Parameters:
name - the non-null attribute name
See Also:
MutableAttributeSet.removeAttribute(java.lang.Object)

removeAttributes

public void removeAttributes(Enumeration<?> names)
Removes a set of attributes for the element.

Specified by:
removeAttributes in interface MutableAttributeSet
Parameters:
names - the attribute names
See Also:
MutableAttributeSet.removeAttributes(java.util.Enumeration)

removeAttributes

public void removeAttributes(AttributeSet attrs)
Removes a set of attributes for the element.

Specified by:
removeAttributes in interface MutableAttributeSet
Parameters:
attrs - the attributes
See Also:
MutableAttributeSet.removeAttributes(java.util.Enumeration)

setResolveParent

public void setResolveParent(AttributeSet parent)
Sets the resolving parent.

Specified by:
setResolveParent in interface MutableAttributeSet
Parameters:
parent - the parent, null if none
See Also:
MutableAttributeSet.setResolveParent(javax.swing.text.AttributeSet)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyleContext.SmallAttributeSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StyleContext.SmallAttributeSet

java.lang.Object
    extended by  javax.swing.text.StyleContext.SmallAttributeSet
All Implemented Interfaces:
AttributeSet
Enclosing class:
StyleContext
public class StyleContext.SmallAttributeSet
extends Object
implements AttributeSet

This class holds a small number of attributes in an array. The storage format is key, value, key, value, etc. The size of the set is the length of the array divided by two. By default, this is the class that will be used to store attributes when held in the compact sharable form.

Nested Class Summary
Nested classes/interfaces inherited from interface javax.swing.text.AttributeSet
AttributeSet.CharacterAttribute, AttributeSet.ColorAttribute, AttributeSet.FontAttribute, AttributeSet.ParagraphAttribute
Field Summary
Fields inherited from interface javax.swing.text.AttributeSet
NameAttribute, ResolveAttribute
Constructor Summary
StyleContext.SmallAttributeSet(AttributeSet attrs)
StyleContext.SmallAttributeSet(Object[] attributes)
Method Summary
Object | clone() Clones a set of attributes.
boolean | containsAttribute(Object name, Object value) Checks whether a given attribute name/value is defined.
boolean | containsAttributes(AttributeSet attrs) Checks whether the attribute set contains all of the given attributes.
AttributeSet | copyAttributes() Copies a set of attributes.
boolean | equals(Object obj) Compares this object to the specifed object.
Object | getAttribute(Object key) Gets the value of an attribute.
int | getAttributeCount() Gets the number of attributes that are defined.
Enumeration<?> | getAttributeNames() Gets the names of all attributes.
AttributeSet | getResolveParent() If not overriden, the resolving parent defaults to the parent element.
int | hashCode() Returns a hashcode for this set of attributes.
boolean | isDefined(Object key) Checks whether a given attribute is defined.
boolean | isEqual(AttributeSet attr) Checks whether two attribute sets are equal.
String | toString() Returns a string showing the key/value pairs
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

StyleContext.SmallAttributeSet

public StyleContext.SmallAttributeSet(Object[] attributes)

StyleContext.SmallAttributeSet

public StyleContext.SmallAttributeSet(AttributeSet attrs)
Method Detail

toString

public String toString()
Returns a string showing the key/value pairs

Overrides:
toString in class Object
Returns:
a string representation of the object.

hashCode

public int hashCode()
Returns a hashcode for this set of attributes.

Overrides:
hashCode in class Object
Returns:
a hashcode value for this set of attributes.
See Also:
Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object obj)
Compares this object to the specifed object. The result is true if the object is an equivalent set of attributes.

Overrides:
equals in class Object
Parameters:
obj - the object to compare with.
Returns:
true if the objects are equal; false otherwise.
See Also:
Object.hashCode(), Hashtable

clone

public Object clone()
Clones a set of attributes. Since the set is immutable, a clone is basically the same set.

Overrides:
clone in class Object
Returns:
the set of attributes
See Also:
Cloneable

getAttributeCount

public int getAttributeCount()
Gets the number of attributes that are defined.

Specified by:
getAttributeCount in interface AttributeSet
Returns:
the number of attributes
See Also:
AttributeSet.getAttributeCount()

isDefined

public boolean isDefined(Object key)
Checks whether a given attribute is defined.

Specified by:
isDefined in interface AttributeSet
Parameters:
key - the attribute key
Returns:
true if the attribute is defined
See Also:
AttributeSet.isDefined(java.lang.Object)

isEqual

public boolean isEqual(AttributeSet attr)
Checks whether two attribute sets are equal.

Specified by:
isEqual in interface AttributeSet
Parameters:
attr - the attribute set to check against
Returns:
true if the same
See Also:
AttributeSet.isEqual(javax.swing.text.AttributeSet)

copyAttributes

public AttributeSet copyAttributes()
Copies a set of attributes.

Specified by:
copyAttributes in interface AttributeSet
Returns:
the copy
See Also:
AttributeSet.copyAttributes()

getAttribute

public Object getAttribute(Object key)
Gets the value of an attribute.

Specified by:
getAttribute in interface AttributeSet
Parameters:
key - the attribute name
Returns:
the attribute value
See Also:
AttributeSet.getAttribute(java.lang.Object)

getAttributeNames

public Enumeration<?> getAttributeNames()
Gets the names of all attributes.

Specified by:
getAttributeNames in interface AttributeSet
Returns:
the attribute names
See Also:
AttributeSet.getAttributeNames()

containsAttribute

public boolean containsAttribute(Object name,
                                 Object value)
Checks whether a given attribute name/value is defined.

Specified by:
containsAttribute in interface AttributeSet
Parameters:
name - the attribute name
value - the attribute value
Returns:
true if the name/value is defined
See Also:
AttributeSet.containsAttribute(java.lang.Object, java.lang.Object)

containsAttributes

public boolean containsAttributes(AttributeSet attrs)
Checks whether the attribute set contains all of the given attributes.

Specified by:
containsAttributes in interface AttributeSet
Parameters:
attrs - the attributes to check
Returns:
true if the element contains all the attributes
See Also:
AttributeSet.containsAttributes(javax.swing.text.AttributeSet)

getResolveParent

public AttributeSet getResolveParent()
If not overriden, the resolving parent defaults to the parent element.

Specified by:
getResolveParent in interface AttributeSet
Returns:
the attributes from the parent
See Also:
AttributeSet.getResolveParent()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyledDocument

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface StyledDocument

All Superinterfaces:
Document
All Known Implementing Classes:
DefaultStyledDocument, HTMLDocument
public interface StyledDocument
extends Document

Interface for a generic styled document.

Field Summary
Fields inherited from interface javax.swing.text.Document
StreamDescriptionProperty, TitleProperty
Method Summary
Style | addStyle(String nm, Style parent) Adds a new style into the logical style hierarchy.
Color | getBackground(AttributeSet attr) Takes a set of attributes and turn it into a background color specification.
Element | getCharacterElement(int pos) Gets the element that represents the character that is at the given offset within the document.
Font | getFont(AttributeSet attr) Takes a set of attributes and turn it into a font specification.
Color | getForeground(AttributeSet attr) Takes a set of attributes and turn it into a foreground color specification.
Style | getLogicalStyle(int p) Gets a logical style for a given position in a paragraph.
Element | getParagraphElement(int pos) Gets the element that represents the paragraph that encloses the given offset within the document.
Style | getStyle(String nm) Fetches a named style previously added.
void | removeStyle(String nm) Removes a named style previously added to the document.
void | setCharacterAttributes(int offset, int length, AttributeSet s, boolean replace) Changes the content element attributes used for the given range of existing content in the document.
void | setLogicalStyle(int pos, Style s) Sets the logical style to use for the paragraph at the given position.
void | setParagraphAttributes(int offset, int length, AttributeSet s, boolean replace) Sets paragraph attributes.
Methods inherited from interface javax.swing.text.Document
addDocumentListener, addUndoableEditListener, createPosition, getDefaultRootElement, getEndPosition, getLength, getProperty, getRootElements, getStartPosition, getText, getText, insertString, putProperty, remove, removeDocumentListener, removeUndoableEditListener, render

Method Detail

addStyle

Style addStyle(String nm,
               Style parent)
Adds a new style into the logical style hierarchy. Style attributes resolve from bottom up so an attribute specified in a child will override an attribute specified in the parent.

Parameters:
nm - the name of the style (must be unique within the collection of named styles). The name may be null if the style is unnamed, but the caller is responsible for managing the reference returned as an unnamed style can't be fetched by name. An unnamed style may be useful for things like character attribute overrides such as found in a style run.
parent - the parent style. This may be null if unspecified attributes need not be resolved in some other style.
Returns:
the style

removeStyle

void removeStyle(String nm)
Removes a named style previously added to the document.

Parameters:
nm - the name of the style to remove

getStyle

Style getStyle(String nm)
Fetches a named style previously added.

Parameters:
nm - the name of the style
Returns:
the style

setCharacterAttributes

void setCharacterAttributes(int offset,
                            int length,
                            AttributeSet s,
                            boolean replace)
Changes the content element attributes used for the given range of existing content in the document. All of the attributes defined in the given Attributes argument are applied to the given range. This method can be used to completely remove all content level attributes for the given range by giving an Attributes argument that has no attributes defined and setting replace to true.

Parameters:
offset - the start of the change >= 0
length - the length of the change >= 0
s - the non-null attributes to change to. Any attributes defined will be applied to the text for the given range.
replace - indicates whether or not the previous attributes should be cleared before the new attributes as set. If true, the operation will replace the previous attributes entirely. If false, the new attributes will be merged with the previous attributes.

setParagraphAttributes

void setParagraphAttributes(int offset,
                            int length,
                            AttributeSet s,
                            boolean replace)
Sets paragraph attributes.

Parameters:
offset - the start of the change >= 0
length - the length of the change >= 0
s - the non-null attributes to change to. Any attributes defined will be applied to the text for the given range.
replace - indicates whether or not the previous attributes should be cleared before the new attributes are set. If true, the operation will replace the previous attributes entirely. If false, the new attributes will be merged with the previous attributes.

setLogicalStyle

void setLogicalStyle(int pos,
                     Style s)
Sets the logical style to use for the paragraph at the given position. If attributes aren't explicitly set for character and paragraph attributes they will resolve through the logical style assigned to the paragraph, which in turn may resolve through some hierarchy completely independent of the element hierarchy in the document.

Parameters:
pos - the starting position >= 0
s - the style to set

getLogicalStyle

Style getLogicalStyle(int p)
Gets a logical style for a given position in a paragraph.

Parameters:
p - the position >= 0
Returns:
the style

getParagraphElement

Element getParagraphElement(int pos)
Gets the element that represents the paragraph that encloses the given offset within the document.

Parameters:
pos - the offset >= 0
Returns:
the element

getCharacterElement

Element getCharacterElement(int pos)
Gets the element that represents the character that is at the given offset within the document.

Parameters:
pos - the offset >= 0
Returns:
the element

getForeground

Color getForeground(AttributeSet attr)
Takes a set of attributes and turn it into a foreground color specification. This might be used to specify things like brighter, more hue, etc.

Parameters:
attr - the set of attributes
Returns:
the color

getBackground

Color getBackground(AttributeSet attr)
Takes a set of attributes and turn it into a background color specification. This might be used to specify things like brighter, more hue, etc.

Parameters:
attr - the set of attributes
Returns:
the color

getFont

Font getFont(AttributeSet attr)
Takes a set of attributes and turn it into a font specification. This can be used to turn things like family, style, size, etc into a font that is available on the system the document is currently being used on.

Parameters:
attr - the set of attributes
Returns:
the font
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyledEditorKit

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StyledEditorKit

java.lang.Object
    extended by  javax.swing.text.EditorKit
        extended by  javax.swing.text.DefaultEditorKit
            extended by  javax.swing.text.StyledEditorKit
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
HTMLEditorKit, RTFEditorKit
public class StyledEditorKit
extends DefaultEditorKit

This is the set of things needed by a text component to be a reasonably functioning editor for some type of text document. This implementation provides a default implementation which treats text as styled text and provides a minimal set of actions for editing styled text.

Nested Class Summary
static class | StyledEditorKit.AlignmentAction An action to set paragraph alignment.
static class | StyledEditorKit.BoldAction An action to toggle the bold attribute.
static class | StyledEditorKit.FontFamilyAction An action to set the font family in the associated JEditorPane.
static class | StyledEditorKit.FontSizeAction An action to set the font size in the associated JEditorPane.
static class | StyledEditorKit.ForegroundAction An action to set foreground color.
static class | StyledEditorKit.ItalicAction An action to toggle the italic attribute.
static class | StyledEditorKit.StyledTextAction An action that assumes it's being fired on a JEditorPane with a StyledEditorKit (or subclass) installed.
static class | StyledEditorKit.UnderlineAction An action to toggle the underline attribute.
Nested classes/interfaces inherited from class javax.swing.text.DefaultEditorKit
DefaultEditorKit.BeepAction, DefaultEditorKit.CopyAction, DefaultEditorKit.CutAction, DefaultEditorKit.DefaultKeyTypedAction, DefaultEditorKit.InsertBreakAction, DefaultEditorKit.InsertContentAction, DefaultEditorKit.InsertTabAction, DefaultEditorKit.PasteAction
Field Summary
Fields inherited from class javax.swing.text.DefaultEditorKit
backwardAction, beepAction, beginAction, beginLineAction, beginParagraphAction, beginWordAction, copyAction, cutAction, defaultKeyTypedAction, deleteNextCharAction, deleteNextWordAction, deletePrevCharAction, deletePrevWordAction, downAction, endAction, endLineAction, EndOfLineStringProperty, endParagraphAction, endWordAction, forwardAction, insertBreakAction, insertContentAction, insertTabAction, nextWordAction, pageDownAction, pageUpAction, pasteAction, previousWordAction, readOnlyAction, selectAllAction, selectionBackwardAction, selectionBeginAction, selectionBeginLineAction, selectionBeginParagraphAction, selectionBeginWordAction, selectionDownAction, selectionEndAction, selectionEndLineAction, selectionEndParagraphAction, selectionEndWordAction, selectionForwardAction, selectionNextWordAction, selectionPreviousWordAction, selectionUpAction, selectLineAction, selectParagraphAction, selectWordAction, upAction, writableAction
Constructor Summary
StyledEditorKit()
Creates a new EditorKit used for styled documents.
Method Summary
Object | clone() Creates a copy of the editor kit.
Document | createDefaultDocument() Creates an uninitialized text storage model that is appropriate for this type of editor.
protected void | createInputAttributes(Element element, MutableAttributeSet set) Copies the key/values in elements AttributeSet into set.
void | deinstall(JEditorPane c) Called when the kit is being removed from the JEditorPane.
Action[] | getActions() Fetches the command list for the editor.
Element | getCharacterAttributeRun() Fetches the element representing the current run of character attributes for the caret.
MutableAttributeSet | getInputAttributes() Gets the input attributes for the pane.
ViewFactory | getViewFactory() Fetches a factory that is suitable for producing views of any models that are produced by this kit.
void | install(JEditorPane c) Called when the kit is being installed into a JEditorPane.
Methods inherited from class javax.swing.text.DefaultEditorKit
createCaret, getContentType, read, read, write, write
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StyledEditorKit

public StyledEditorKit()
Creates a new EditorKit used for styled documents.

Method Detail

getInputAttributes

public MutableAttributeSet getInputAttributes()
Gets the input attributes for the pane. When the caret moves and there is no selection, the input attributes are automatically mutated to reflect the character attributes of the current caret location. The styled editing actions use the input attributes to carry out their actions.

Returns:
the attribute set

getCharacterAttributeRun

public Element getCharacterAttributeRun()
Fetches the element representing the current run of character attributes for the caret.

Returns:
the element

getActions

public Action[] getActions()
Fetches the command list for the editor. This is the list of commands supported by the superclass augmented by the collection of commands defined locally for style operations.

Overrides:
getActions in class DefaultEditorKit
Returns:
the command list

createDefaultDocument

public Document createDefaultDocument()
Creates an uninitialized text storage model that is appropriate for this type of editor.

Overrides:
createDefaultDocument in class DefaultEditorKit
Returns:
the model

install

public void install(JEditorPane c)
Called when the kit is being installed into a JEditorPane.

Overrides:
install in class EditorKit
Parameters:
c - the JEditorPane

deinstall

public void deinstall(JEditorPane c)
Called when the kit is being removed from the JEditorPane. This is used to unregister any listeners that were attached.

Overrides:
deinstall in class EditorKit
Parameters:
c - the JEditorPane

getViewFactory

public ViewFactory getViewFactory()
Fetches a factory that is suitable for producing views of any models that are produced by this kit. This is implemented to return View implementations for the following kinds of elements:
  • AbstractDocument.ContentElementName
  • AbstractDocument.ParagraphElementName
  • AbstractDocument.SectionElementName
  • StyleConstants.ComponentElementName
  • StyleConstants.IconElementName

Overrides:
getViewFactory in class DefaultEditorKit
Returns:
the factory

clone

public Object clone()
Creates a copy of the editor kit.

Overrides:
clone in class EditorKit
Returns:
the copy
See Also:
Cloneable

createInputAttributes

protected void createInputAttributes(Element element,
                                     MutableAttributeSet set)
Copies the key/values in elements AttributeSet into set. This does not copy component, icon, or element names attributes. Subclasses may wish to refine what is and what isn't copied here. But be sure to first remove all the attributes that are in set.

This is called anytime the caret moves over a different location.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyledEditorKit.AlignmentAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StyledEditorKit.AlignmentAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.StyledEditorKit.StyledTextAction
                extended by  javax.swing.text.StyledEditorKit.AlignmentAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
StyledEditorKit
public static class StyledEditorKit.AlignmentAction
extends StyledEditorKit.StyledTextAction

An action to set paragraph alignment. This sets the StyleConstants.Alignment attribute for the currently selected range of the target JEditorPane. This is done by calling StyledDocument.setParagraphAttributes on the styled document associated with the target JEditorPane.

If the target text component is specified as the source of the ActionEvent and there is a command string, the command string will be interpreted as an integer that should be one of the legal values for the StyleConstants.Alignment attribute.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
StyledEditorKit.AlignmentAction(String nm, int a)
Creates a new AlignmentAction.
Method Summary
 void actionPerformed(ActionEvent e)
Sets the alignment.
Methods inherited from class javax.swing.text.StyledEditorKit.StyledTextAction
getEditor, getStyledDocument, getStyledEditorKit, setCharacterAttributes, setParagraphAttributes
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StyledEditorKit.AlignmentAction

public StyledEditorKit.AlignmentAction(String nm,
                                       int a)
Creates a new AlignmentAction.

Parameters:
nm - the action name
a - the alignment >= 0
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Sets the alignment.

Parameters:
e - the action event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyledEditorKit.BoldAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StyledEditorKit.BoldAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.StyledEditorKit.StyledTextAction
                extended by  javax.swing.text.StyledEditorKit.BoldAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
StyledEditorKit
public static class StyledEditorKit.BoldAction
extends StyledEditorKit.StyledTextAction

An action to toggle the bold attribute.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
StyledEditorKit.BoldAction()
Constructs a new BoldAction.
Method Summary
 void actionPerformed(ActionEvent e)
Toggles the bold attribute.
Methods inherited from class javax.swing.text.StyledEditorKit.StyledTextAction
getEditor, getStyledDocument, getStyledEditorKit, setCharacterAttributes, setParagraphAttributes
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StyledEditorKit.BoldAction

public StyledEditorKit.BoldAction()
Constructs a new BoldAction.

Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Toggles the bold attribute.

Parameters:
e - the action event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyledEditorKit.FontFamilyAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StyledEditorKit.FontFamilyAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.StyledEditorKit.StyledTextAction
                extended by  javax.swing.text.StyledEditorKit.FontFamilyAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
StyledEditorKit
public static class StyledEditorKit.FontFamilyAction
extends StyledEditorKit.StyledTextAction

An action to set the font family in the associated JEditorPane. This will use the family specified as the command string on the ActionEvent if there is one, otherwise the family that was initialized with will be used.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
StyledEditorKit.FontFamilyAction(String nm, String family)
Creates a new FontFamilyAction.
Method Summary
 void actionPerformed(ActionEvent e)
Sets the font family.
Methods inherited from class javax.swing.text.StyledEditorKit.StyledTextAction
getEditor, getStyledDocument, getStyledEditorKit, setCharacterAttributes, setParagraphAttributes
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StyledEditorKit.FontFamilyAction

public StyledEditorKit.FontFamilyAction(String nm,
                                        String family)
Creates a new FontFamilyAction.

Parameters:
nm - the action name
family - the font family
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Sets the font family.

Parameters:
e - the event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyledEditorKit.FontSizeAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StyledEditorKit.FontSizeAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.StyledEditorKit.StyledTextAction
                extended by  javax.swing.text.StyledEditorKit.FontSizeAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
StyledEditorKit
public static class StyledEditorKit.FontSizeAction
extends StyledEditorKit.StyledTextAction

An action to set the font size in the associated JEditorPane. This will use the size specified as the command string on the ActionEvent if there is one, otherwise the size that was initialized with will be used.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
StyledEditorKit.FontSizeAction(String nm, int size)
Creates a new FontSizeAction.
Method Summary
 void actionPerformed(ActionEvent e)
Sets the font size.
Methods inherited from class javax.swing.text.StyledEditorKit.StyledTextAction
getEditor, getStyledDocument, getStyledEditorKit, setCharacterAttributes, setParagraphAttributes
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StyledEditorKit.FontSizeAction

public StyledEditorKit.FontSizeAction(String nm,
                                      int size)
Creates a new FontSizeAction.

Parameters:
nm - the action name
size - the font size
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Sets the font size.

Parameters:
e - the action event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyledEditorKit.ForegroundAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StyledEditorKit.ForegroundAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.StyledEditorKit.StyledTextAction
                extended by  javax.swing.text.StyledEditorKit.ForegroundAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
StyledEditorKit
public static class StyledEditorKit.ForegroundAction
extends StyledEditorKit.StyledTextAction

An action to set foreground color. This sets the StyleConstants.Foreground attribute for the currently selected range of the target JEditorPane. This is done by calling StyledDocument.setCharacterAttributes on the styled document associated with the target JEditorPane.

If the target text component is specified as the source of the ActionEvent and there is a command string, the command string will be interpreted as the foreground color. It will be interpreted by called Color.decode, and should therefore be legal input for that method.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
StyledEditorKit.ForegroundAction(String nm, Color fg)
Creates a new ForegroundAction.
Method Summary
 void actionPerformed(ActionEvent e)
Sets the foreground color.
Methods inherited from class javax.swing.text.StyledEditorKit.StyledTextAction
getEditor, getStyledDocument, getStyledEditorKit, setCharacterAttributes, setParagraphAttributes
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StyledEditorKit.ForegroundAction

public StyledEditorKit.ForegroundAction(String nm,
                                        Color fg)
Creates a new ForegroundAction.

Parameters:
nm - the action name
fg - the foreground color
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Sets the foreground color.

Parameters:
e - the action event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyledEditorKit.ItalicAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StyledEditorKit.ItalicAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.StyledEditorKit.StyledTextAction
                extended by  javax.swing.text.StyledEditorKit.ItalicAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
StyledEditorKit
public static class StyledEditorKit.ItalicAction
extends StyledEditorKit.StyledTextAction

An action to toggle the italic attribute.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
StyledEditorKit.ItalicAction()
Constructs a new ItalicAction.
Method Summary
 void actionPerformed(ActionEvent e)
Toggles the italic attribute.
Methods inherited from class javax.swing.text.StyledEditorKit.StyledTextAction
getEditor, getStyledDocument, getStyledEditorKit, setCharacterAttributes, setParagraphAttributes
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StyledEditorKit.ItalicAction

public StyledEditorKit.ItalicAction()
Constructs a new ItalicAction.

Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Toggles the italic attribute.

Parameters:
e - the action event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyledEditorKit.StyledTextAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StyledEditorKit.StyledTextAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.StyledEditorKit.StyledTextAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Direct Known Subclasses:
HTMLEditorKit.HTMLTextAction, StyledEditorKit.AlignmentAction, StyledEditorKit.BoldAction, StyledEditorKit.FontFamilyAction, StyledEditorKit.FontSizeAction, StyledEditorKit.ForegroundAction, StyledEditorKit.ItalicAction, StyledEditorKit.UnderlineAction
Enclosing class:
StyledEditorKit
public abstract static class StyledEditorKit.StyledTextAction
extends TextAction

An action that assumes it's being fired on a JEditorPane with a StyledEditorKit (or subclass) installed. This has some convenience methods for causing character or paragraph level attribute changes. The convenience methods will throw an IllegalArgumentException if the assumption of a StyledDocument, a JEditorPane, or a StyledEditorKit fail to be true.

The component that gets acted upon by the action will be the source of the ActionEvent if the source can be narrowed to a JEditorPane type. If the source can't be narrowed, the most recently focused text component is changed. If neither of these are the case, the action cannot be performed.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
StyledEditorKit.StyledTextAction(String nm)
Creates a new StyledTextAction from a string action name.
Method Summary
protected JEditorPane | getEditor(ActionEvent e) Gets the target editor for an action.
protected StyledDocument | getStyledDocument(JEditorPane e) Gets the document associated with an editor pane.
protected StyledEditorKit | getStyledEditorKit(JEditorPane e) Gets the editor kit associated with an editor pane.
protected void | setCharacterAttributes(JEditorPane editor, AttributeSet attr, boolean replace) Applies the given attributes to character content.
protected void | setParagraphAttributes(JEditorPane editor, AttributeSet attr, boolean replace) Applies the given attributes to paragraphs.
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface java.awt.event.ActionListener
actionPerformed

Constructor Detail

StyledEditorKit.StyledTextAction

public StyledEditorKit.StyledTextAction(String nm)
Creates a new StyledTextAction from a string action name.

Parameters:
nm - the name of the action
Method Detail

getEditor

protected final JEditorPane getEditor(ActionEvent e)
Gets the target editor for an action.

Parameters:
e - the action event
Returns:
the editor

getStyledDocument

protected final StyledDocument getStyledDocument(JEditorPane e)
Gets the document associated with an editor pane.

Parameters:
e - the editor
Returns:
the document
Throws:
IllegalArgumentException - for the wrong document type

getStyledEditorKit

protected final StyledEditorKit getStyledEditorKit(JEditorPane e)
Gets the editor kit associated with an editor pane.

Parameters:
e - the editor pane
Returns:
the kit
Throws:
IllegalArgumentException - for the wrong document type

setCharacterAttributes

protected final void setCharacterAttributes(JEditorPane editor,
                                            AttributeSet attr,
                                            boolean replace)
Applies the given attributes to character content. If there is a selection, the attributes are applied to the selection range. If there is no selection, the attributes are applied to the input attribute set which defines the attributes for any new text that gets inserted.

Parameters:
editor - the editor
attr - the attributes
replace - if true, then replace the existing attributes first

setParagraphAttributes

protected final void setParagraphAttributes(JEditorPane editor,
                                            AttributeSet attr,
                                            boolean replace)
Applies the given attributes to paragraphs. If there is a selection, the attributes are applied to the paragraphs that intersect the selection. if there is no selection, the attributes are applied to the paragraph at the current caret position.

Parameters:
editor - the editor
attr - the attributes
replace - if true, replace the existing attributes first
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StyledEditorKit.UnderlineAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class StyledEditorKit.UnderlineAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
            extended by  javax.swing.text.StyledEditorKit.StyledTextAction
                extended by  javax.swing.text.StyledEditorKit.UnderlineAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Enclosing class:
StyledEditorKit
public static class StyledEditorKit.UnderlineAction
extends StyledEditorKit.StyledTextAction

An action to toggle the underline attribute.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
StyledEditorKit.UnderlineAction()
Constructs a new UnderlineAction.
Method Summary
 void actionPerformed(ActionEvent e)
Toggles the Underline attribute.
Methods inherited from class javax.swing.text.StyledEditorKit.StyledTextAction
getEditor, getStyledDocument, getStyledEditorKit, setCharacterAttributes, setParagraphAttributes
Methods inherited from class javax.swing.text.TextAction
augmentList, getFocusedComponent, getTextComponent
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StyledEditorKit.UnderlineAction

public StyledEditorKit.UnderlineAction()
Constructs a new UnderlineAction.

Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Toggles the Underline attribute.

Parameters:
e - the action event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TabableView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface TabableView

All Known Implementing Classes:
GlyphView, InlineView, LabelView
public interface TabableView

Interface for Views that have size dependent upon tabs.

See Also:
TabExpander, LabelView, ParagraphView

Method Summary
float | getPartialSpan(int p0, int p1) Determines the span along the same axis as tab expansion for a portion of the view.
float | getTabbedSpan(float x, TabExpander e) Determines the desired span when using the given tab expansion implementation.

Method Detail

getTabbedSpan

float getTabbedSpan(float x,
                    TabExpander e)
Determines the desired span when using the given tab expansion implementation. If a container calls this method, it will do so prior to the normal layout which would call getPreferredSpan. A view implementing this should give the same result in any subsequent calls to getPreferredSpan along the axis of tab expansion.

Parameters:
x - the position the view would be located at for the purpose of tab expansion >= 0.
e - how to expand the tabs when encountered.
Returns:
the desired span >= 0

getPartialSpan

float getPartialSpan(int p0,
                     int p1)
Determines the span along the same axis as tab expansion for a portion of the view. This is intended for use by the TabExpander for cases where the tab expansion involves aligning the portion of text that doesn't have whitespace relative to the tab stop. There is therefore an assumption that the range given does not contain tabs.

Parameters:
p0 - the starting location in the text document >= 0
p1 - the ending location in the text document >= p0
Returns:
the span >= 0
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TabExpander

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface TabExpander

All Known Implementing Classes:
FieldView, ParagraphView, ParagraphView, PasswordView, PlainView, WrappedPlainView
public interface TabExpander

Simple interface to allow for different types of implementations of tab expansion.

Method Summary
 float nextTabStop(float x, int tabOffset)
Returns the next tab stop position given a reference position.

Method Detail

nextTabStop

float nextTabStop(float x,
                  int tabOffset)
Returns the next tab stop position given a reference position. Values are expressed in points.

Parameters:
x - the position in points >= 0
tabOffset - the position within the text stream that the tab occurred at >= 0.
Returns:
the next tab stop >= 0
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TableView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class TableView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.CompositeView
            extended by  javax.swing.text.BoxView
                extended by  javax.swing.text.TableView
All Implemented Interfaces:
SwingConstants
public abstract class TableView
extends BoxView

Implements View interface for a table, that is composed of an element structure where the child elements of the element this view is responsible for represent rows and the child elements of the row elements are cells. The cell elements can have an arbitrary element structure under them, which will be built with the ViewFactory returned by the getViewFactory method.

    TABLE
      ROW
        CELL
        CELL
      ROW
        CELL
        CELL

This is implemented as a hierarchy of boxes, the table itself is a vertical box, the rows are horizontal boxes, and the cells are vertical boxes. The cells are allowed to span multiple columns and rows. By default, the table can be thought of as being formed over a grid (i.e. somewhat like one would find in gridbag layout), where table cells can request to span more than one grid cell. The default horizontal span of table cells will be based upon this grid, but can be changed by reimplementing the requested span of the cell (i.e. table cells can have independant spans if desired).

See Also:
View

Nested Class Summary
class | TableView.TableCell Deprecated. A table cell can now be any View implementation.
class | TableView.TableRow View of a row in a row-centric table.
Field Summary
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
TableView(Element elem)
Constructs a TableView for the given element.
Method Summary
protected SizeRequirements | calculateMinorAxisRequirements(int axis, SizeRequirements r) Calculate the requirements for the minor axis.
protected TableView.TableCell | createTableCell(Element elem) Deprecated. Table cells can now be any arbitrary View implementation and should be produced by the ViewFactory rather than the table.
protected TableView.TableRow | createTableRow(Element elem) Creates a new table row.
protected void | forwardUpdate(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a, ViewFactory f) Forwards the given DocumentEvent to the child views that need to be notified of the change to the model.
protected View | getViewAtPosition(int pos, Rectangle a) Fetches the child view that represents the given position in the model.
protected void | layoutColumns(int targetSpan, int[] offsets, int[] spans, SizeRequirements[] reqs) Lays out the columns to fit within the given target span.
protected void | layoutMinorAxis(int targetSpan, int axis, int[] offsets, int[] spans) Perform layout for the minor axis of the box (i.e.
void | replace(int offset, int length, View[] views) Change the child views.
Methods inherited from class javax.swing.text.BoxView
baselineLayout, baselineRequirements, calculateMajorAxisRequirements, childAllocation, flipEastAndWestAtEnds, getAlignment, getAxis, getChildAllocation, getHeight, getMaximumSpan, getMinimumSpan, getOffset, getPreferredSpan, getResizeWeight, getSpan, getViewAtPoint, getWidth, isAfter, isAllocationValid, isBefore, isLayoutValid, layout, layoutChanged, layoutMajorAxis, modelToView, paint, paintChild, preferenceChanged, setAxis, setSize, viewToModel
Methods inherited from class javax.swing.text.CompositeView
getBottomInset, getInsideAllocation, getLeftInset, getNextEastWestVisualPositionFrom, getNextNorthSouthVisualPositionFrom, getNextVisualPositionFrom, getRightInset, getTopInset, getView, getViewCount, getViewIndex, getViewIndexAtPosition, loadChildren, modelToView, setInsets, setParagraphInsets, setParent
Methods inherited from class javax.swing.text.View
append, breakView, changedUpdate, createFragment, forwardUpdateToView, getAttributes, getBreakWeight, getContainer, getDocument, getElement, getEndOffset, getGraphics, getParent, getStartOffset, getToolTipText, getViewFactory, getViewIndex, insert, insertUpdate, isVisible, modelToView, remove, removeAll, removeUpdate, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TableView

public TableView(Element elem)
Constructs a TableView for the given element.

Parameters:
elem - the element that this view is responsible for
Method Detail

createTableRow

protected TableView.TableRow createTableRow(Element elem)
Creates a new table row.

Parameters:
elem - an element
Returns:
the row

createTableCell

@Deprecated
protected TableView.TableCell createTableCell(Element elem)
Deprecated. Table cells can now be any arbitrary View implementation and should be produced by the ViewFactory rather than the table.

Parameters:
elem - an element
Returns:
the cell

forwardUpdate

protected void forwardUpdate(DocumentEvent.ElementChange ec,
                             DocumentEvent e,
                             Shape a,
                             ViewFactory f)
Description copied from class: BoxView
Forwards the given DocumentEvent to the child views that need to be notified of the change to the model. If a child changed its requirements and the allocation was valid prior to forwarding the portion of the box from the starting child to the end of the box will be repainted.

Overrides:
forwardUpdate in class BoxView
Parameters:
ec - changes to the element this view is responsible for (may be null if there were no changes)
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory),
View.removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory),
View.changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

replace

public void replace(int offset,
                    int length,
                    View[] views)
Change the child views. This is implemented to provide the superclass behavior and invalidate the grid so that rows and columns will be recalculated.

Overrides:
replace in class BoxView
Parameters:
offset - the starting index into the child views to insert the new views; this should be a value >= 0 and <= getViewCountlength - the number of existing child views to remove; This should be a value >= 0 and <= (getViewCount()="(getViewCount()" -="-" offset)views - the child views to add; this value can be nullto indicate no children are being added (useful to remove)

layoutColumns

protected void layoutColumns(int targetSpan,
                             int[] offsets,
                             int[] spans,
                             SizeRequirements[] reqs)
Lays out the columns to fit within the given target span. Returns the results through offsets and spans.

Parameters:
targetSpan - the given span for total of all the table columns
reqs - the requirements desired for each column. This is the column maximum of the cells minimum, preferred, and maximum requested span
spans - the return value of how much to allocated to each column
offsets - the return value of the offset from the origin for each column

layoutMinorAxis

protected void layoutMinorAxis(int targetSpan,
                               int axis,
                               int[] offsets,
                               int[] spans)
Perform layout for the minor axis of the box (i.e. the axis orthoginal to the axis that it represents). The results of the layout should be placed in the given arrays which represent the allocations to the children along the minor axis. This is called by the superclass whenever the layout needs to be updated along the minor axis.

This is implemented to call the layoutColumns method, and then forward to the superclass to actually carry out the layout of the tables rows.

Overrides:
layoutMinorAxis in class BoxView
Parameters:
targetSpan - the total span given to the view, which whould be used to layout the children.
axis - the axis being layed out.
offsets - the offsets from the origin of the view for each of the child views. This is a return value and is filled in by the implementation of this method.
spans - the span of each child view. This is a return value and is filled in by the implementation of this method.

calculateMinorAxisRequirements

protected SizeRequirements calculateMinorAxisRequirements(int axis,
                                                          SizeRequirements r)
Calculate the requirements for the minor axis. This is called by the superclass whenever the requirements need to be updated (i.e. a preferenceChanged was messaged through this view).

This is implemented to calculate the requirements as the sum of the requirements of the columns.

Overrides:
calculateMinorAxisRequirements in class BoxView
Parameters:
axis - the axis being studied
r - the SizeRequirements object; if null one will be created
Returns:
the newly initialized SizeRequirements object
See Also:
SizeRequirements

getViewAtPosition

protected View getViewAtPosition(int pos,
                                 Rectangle a)
Fetches the child view that represents the given position in the model. This is implemented to walk through the children looking for a range that contains the given position. In this view the children do not necessarily have a one to one mapping with the child elements.

Overrides:
getViewAtPosition in class CompositeView
Parameters:
pos - the search position >= 0
a - the allocation to the table on entry, and the allocation of the view containing the position on exit
Returns:
the view representing the given position, or null if there isn't one
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TableView.TableCell

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class TableView.TableCell

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.CompositeView
            extended by  javax.swing.text.BoxView
                extended by  javax.swing.text.TableView.TableCell
All Implemented Interfaces:
SwingConstants
Enclosing class:
TableView
Deprecated. A table cell can now be any View implementation.

@Deprecated
public class TableView.TableCell
extends BoxView

Field Summary
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
TableView.TableCell(Element elem)
Deprecated. Constructs a TableCell for the given element.
Method Summary
int | getColumnCount() Deprecated. Gets the number of columns this cell spans (e.g.
int | getGridColumn() Deprecated. Gets the column of the grid location
int | getGridRow() Deprecated. Gets the row of the grid location
int | getRowCount() Deprecated. Gets the number of rows this cell spans (that is, the grid height).
void | setGridLocation(int row, int col) Deprecated. Sets the grid location.
Methods inherited from class javax.swing.text.BoxView
baselineLayout, baselineRequirements, calculateMajorAxisRequirements, calculateMinorAxisRequirements, childAllocation, flipEastAndWestAtEnds, forwardUpdate, getAlignment, getAxis, getChildAllocation, getHeight, getMaximumSpan, getMinimumSpan, getOffset, getPreferredSpan, getResizeWeight, getSpan, getViewAtPoint, getWidth, isAfter, isAllocationValid, isBefore, isLayoutValid, layout, layoutChanged, layoutMajorAxis, layoutMinorAxis, modelToView, paint, paintChild, preferenceChanged, replace, setAxis, setSize, viewToModel
Methods inherited from class javax.swing.text.CompositeView
getBottomInset, getInsideAllocation, getLeftInset, getNextEastWestVisualPositionFrom, getNextNorthSouthVisualPositionFrom, getNextVisualPositionFrom, getRightInset, getTopInset, getView, getViewAtPosition, getViewCount, getViewIndex, getViewIndexAtPosition, loadChildren, modelToView, setInsets, setParagraphInsets, setParent
Methods inherited from class javax.swing.text.View
append, breakView, changedUpdate, createFragment, forwardUpdateToView, getAttributes, getBreakWeight, getContainer, getDocument, getElement, getEndOffset, getGraphics, getParent, getStartOffset, getToolTipText, getViewFactory, getViewIndex, insert, insertUpdate, isVisible, modelToView, remove, removeAll, removeUpdate, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TableView.TableCell

public TableView.TableCell(Element elem)
Deprecated.
Constructs a TableCell for the given element.

Parameters:
elem - the element that this view is responsible for
Since:
1.4
Method Detail

getColumnCount

public int getColumnCount()
Deprecated.
Gets the number of columns this cell spans (e.g. the grid width).

Returns:
the number of columns

getRowCount

public int getRowCount()
Deprecated.
Gets the number of rows this cell spans (that is, the grid height).

Returns:
the number of rows

setGridLocation

public void setGridLocation(int row,
                            int col)
Deprecated.
Sets the grid location.

Parameters:
row - the row >= 0
col - the column >= 0

getGridRow

public int getGridRow()
Deprecated.
Gets the row of the grid location

getGridColumn

public int getGridColumn()
Deprecated.
Gets the column of the grid location

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TableView.TableRow

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class TableView.TableRow

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.CompositeView
            extended by  javax.swing.text.BoxView
                extended by  javax.swing.text.TableView.TableRow
All Implemented Interfaces:
SwingConstants
Enclosing class:
TableView
public class TableView.TableRow
extends BoxView

View of a row in a row-centric table.

Field Summary
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
TableView.TableRow(Element elem)
Constructs a TableView for the given element.
Method Summary
int | getResizeWeight(int axis) Determines the resizability of the view along the given axis.
protected View | getViewAtPosition(int pos, Rectangle a) Fetches the child view that represents the given position in the model.
protected void | layoutMajorAxis(int targetSpan, int axis, int[] offsets, int[] spans) Perform layout for the major axis of the box (i.e.
protected void | layoutMinorAxis(int targetSpan, int axis, int[] offsets, int[] spans) Perform layout for the minor axis of the box (i.e.
void | replace(int offset, int length, View[] views) Change the child views.
Methods inherited from class javax.swing.text.BoxView
baselineLayout, baselineRequirements, calculateMajorAxisRequirements, calculateMinorAxisRequirements, childAllocation, flipEastAndWestAtEnds, forwardUpdate, getAlignment, getAxis, getChildAllocation, getHeight, getMaximumSpan, getMinimumSpan, getOffset, getPreferredSpan, getSpan, getViewAtPoint, getWidth, isAfter, isAllocationValid, isBefore, isLayoutValid, layout, layoutChanged, modelToView, paint, paintChild, preferenceChanged, setAxis, setSize, viewToModel
Methods inherited from class javax.swing.text.CompositeView
getBottomInset, getInsideAllocation, getLeftInset, getNextEastWestVisualPositionFrom, getNextNorthSouthVisualPositionFrom, getNextVisualPositionFrom, getRightInset, getTopInset, getView, getViewCount, getViewIndex, getViewIndexAtPosition, loadChildren, modelToView, setInsets, setParagraphInsets, setParent
Methods inherited from class javax.swing.text.View
append, breakView, changedUpdate, createFragment, forwardUpdateToView, getAttributes, getBreakWeight, getContainer, getDocument, getElement, getEndOffset, getGraphics, getParent, getStartOffset, getToolTipText, getViewFactory, getViewIndex, insert, insertUpdate, isVisible, modelToView, remove, removeAll, removeUpdate, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TableView.TableRow

public TableView.TableRow(Element elem)
Constructs a TableView for the given element.

Parameters:
elem - the element that this view is responsible for
Since:
1.4
Method Detail

replace

public void replace(int offset,
                    int length,
                    View[] views)
Change the child views. This is implemented to provide the superclass behavior and invalidate the grid so that rows and columns will be recalculated.

Overrides:
replace in class BoxView
Parameters:
offset - the starting index into the child views to insert the new views; this should be a value >= 0 and <= getViewCountlength - the number of existing child views to remove; This should be a value >= 0 and <= (getViewCount()="(getViewCount()" -="-" offset)views - the child views to add; this value can be nullto indicate no children are being added (useful to remove)

layoutMajorAxis

protected void layoutMajorAxis(int targetSpan,
                               int axis,
                               int[] offsets,
                               int[] spans)
Perform layout for the major axis of the box (i.e. the axis that it represents). The results of the layout should be placed in the given arrays which represent the allocations to the children along the major axis.

This is re-implemented to give each child the span of the column width for the table, and to give cells that span multiple columns the multi-column span.

Overrides:
layoutMajorAxis in class BoxView
Parameters:
targetSpan - the total span given to the view, which whould be used to layout the children.
axis - the axis being layed out.
offsets - the offsets from the origin of the view for each of the child views. This is a return value and is filled in by the implementation of this method.
spans - the span of each child view. This is a return value and is filled in by the implementation of this method.

layoutMinorAxis

protected void layoutMinorAxis(int targetSpan,
                               int axis,
                               int[] offsets,
                               int[] spans)
Perform layout for the minor axis of the box (i.e. the axis orthoginal to the axis that it represents). The results of the layout should be placed in the given arrays which represent the allocations to the children along the minor axis. This is called by the superclass whenever the layout needs to be updated along the minor axis.

This is implemented to delegate to the superclass, then adjust the span for any cell that spans multiple rows.

Overrides:
layoutMinorAxis in class BoxView
Parameters:
targetSpan - the total span given to the view, which whould be used to layout the children.
axis - the axis being layed out.
offsets - the offsets from the origin of the view for each of the child views. This is a return value and is filled in by the implementation of this method.
spans - the span of each child view. This is a return value and is filled in by the implementation of this method.

getResizeWeight

public int getResizeWeight(int axis)
Determines the resizability of the view along the given axis. A value of 0 or less is not resizable.

Overrides:
getResizeWeight in class BoxView
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the resize weight
Throws:
IllegalArgumentException - for an invalid axis

getViewAtPosition

protected View getViewAtPosition(int pos,
                                 Rectangle a)
Fetches the child view that represents the given position in the model. This is implemented to walk through the children looking for a range that contains the given position. In this view the children do not necessarily have a one to one mapping with the child elements.

Overrides:
getViewAtPosition in class CompositeView
Parameters:
pos - the search position >= 0
a - the allocation to the table on entry, and the allocation of the view containing the position on exit
Returns:
the view representing the given position, or null if there isn't one
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TabSet

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class TabSet

java.lang.Object
    extended by  javax.swing.text.TabSet
All Implemented Interfaces:
Serializable
public class TabSet
extends Object
implements Serializable

A TabSet is comprised of many TabStops. It offers methods for locating the closest TabStop to a given position and finding all the potential TabStops. It is also immutable.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
TabSet(TabStop[] tabs)
Creates and returns an instance of TabSet.
Method Summary
boolean | equals(Object o) Indicates whether this TabSet is equal to another one.
TabStop | getTab(int index) Returns the TabStop at index index.
TabStop | getTabAfter(float location) Returns the Tab instance after location.
int | getTabCount() Returns the number of Tab instances the receiver contains.
int | getTabIndex(TabStop tab)
int | getTabIndexAfter(float location) Returns the index of the Tab to be used after location.
int | hashCode() Returns a hashcode for this set of TabStops.
String | toString() Returns the string representation of the set of tabs.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

TabSet

public TabSet(TabStop[] tabs)
Creates and returns an instance of TabSet. The array of Tabs passed in must be sorted in ascending order.

Method Detail

getTabCount

public int getTabCount()
Returns the number of Tab instances the receiver contains.

getTab

public TabStop getTab(int index)
Returns the TabStop at index index. This will throw an IllegalArgumentException if index is outside the range of tabs.

getTabAfter

public TabStop getTabAfter(float location)
Returns the Tab instance after location. This will return null if there are no tabs after location.

getTabIndex

public int getTabIndex(TabStop tab)
Returns:
the index of the TabStop tab, or -1 if tab is not contained in the receiver.

getTabIndexAfter

public int getTabIndexAfter(float location)
Returns the index of the Tab to be used after location. This will return -1 if there are no tabs after location.

equals

public boolean equals(Object o)
Indicates whether this TabSet is equal to another one.

Overrides:
equals in class Object
Parameters:
o - the TabSet instance which this instance should be compared to.
Returns:
true if o is the instance of TabSet, has the same number of TabStops and they are all equal, false otherwise.
Since:
1.5
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns a hashcode for this set of TabStops.

Overrides:
hashCode in class Object
Returns:
a hashcode value for this set of TabStops.
Since:
1.5
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Returns the string representation of the set of tabs.

Overrides:
toString in class Object
Returns:
a string representation of the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TabStop

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class TabStop

java.lang.Object
    extended by  javax.swing.text.TabStop
All Implemented Interfaces:
Serializable
public class TabStop
extends Object
implements Serializable

This class encapsulates a single tab stop (basically as tab stops are thought of by RTF). A tab stop is at a specified distance from the left margin, aligns text in a specified way, and has a specified leader. TabStops are immutable, and usually contained in TabSets.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
static int | ALIGN_BAR
static int | ALIGN_CENTER Characters following tab are positioned such that all following characters up to next tab/newline are centered around the tabs location.
static int | ALIGN_DECIMAL Characters following tab are aligned such that next decimal/tab/newline is at the tab location, very similar to RIGHT_TAB, just includes decimal as additional character to look for.
static int | ALIGN_LEFT Character following tab is positioned at location.
static int | ALIGN_RIGHT Characters following tab are positioned such that all following characters up to next tab/newline end at location.
static int | LEAD_DOTS
static int | LEAD_EQUALS
static int | LEAD_HYPHENS
static int | LEAD_NONE
static int | LEAD_THICKLINE
static int | LEAD_UNDERLINE
Constructor Summary
TabStop(float pos)
Creates a tab at position pos with a default alignment and default leader.
TabStop(float pos, int align, int leader)
Creates a tab with the specified position pos, alignment align and leader leader.
Method Summary
boolean | equals(Object other) Returns true if the tabs are equal.
int | getAlignment() Returns the alignment, as an integer, of the tab.
int | getLeader() Returns the leader of the tab.
float | getPosition() Returns the position, as a float, of the tab.
int | hashCode() Returns the hashCode for the object.
String | toString() Returns a string representation of the object.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ALIGN_LEFT

public static final int ALIGN_LEFT
Character following tab is positioned at location.

See Also:
Constant Field Values

ALIGN_RIGHT

public static final int ALIGN_RIGHT
Characters following tab are positioned such that all following characters up to next tab/newline end at location.

See Also:
Constant Field Values

ALIGN_CENTER

public static final int ALIGN_CENTER
Characters following tab are positioned such that all following characters up to next tab/newline are centered around the tabs location.

See Also:
Constant Field Values

ALIGN_DECIMAL

public static final int ALIGN_DECIMAL
Characters following tab are aligned such that next decimal/tab/newline is at the tab location, very similar to RIGHT_TAB, just includes decimal as additional character to look for.

See Also:
Constant Field Values

ALIGN_BAR

public static final int ALIGN_BAR
See Also:
Constant Field Values

LEAD_NONE

public static final int LEAD_NONE
See Also:
Constant Field Values

LEAD_DOTS

public static final int LEAD_DOTS
See Also:
Constant Field Values

LEAD_HYPHENS

public static final int LEAD_HYPHENS
See Also:
Constant Field Values

LEAD_UNDERLINE

public static final int LEAD_UNDERLINE
See Also:
Constant Field Values

LEAD_THICKLINE

public static final int LEAD_THICKLINE
See Also:
Constant Field Values

LEAD_EQUALS

public static final int LEAD_EQUALS
See Also:
Constant Field Values
Constructor Detail

TabStop

public TabStop(float pos)
Creates a tab at position pos with a default alignment and default leader.

TabStop

public TabStop(float pos,
               int align,
               int leader)
Creates a tab with the specified position pos, alignment align and leader leader.

Method Detail

getPosition

public float getPosition()
Returns the position, as a float, of the tab.

Returns:
the position of the tab

getAlignment

public int getAlignment()
Returns the alignment, as an integer, of the tab.

Returns:
the alignment of the tab

getLeader

public int getLeader()
Returns the leader of the tab.

Returns:
the leader of the tab

equals

public boolean equals(Object other)
Returns true if the tabs are equal.

Overrides:
equals in class Object
Parameters:
other - the reference object with which to compare.
Returns:
true if the tabs are equal, otherwise false
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns the hashCode for the object. This must be defined here to ensure 100% pure.

Overrides:
hashCode in class Object
Returns:
the hashCode for the object
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
Description copied from class: Object
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())

Overrides:
toString in class Object
Returns:
a string representation of the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TextAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class TextAction

java.lang.Object
    extended by  javax.swing.AbstractAction
        extended by  javax.swing.text.TextAction
All Implemented Interfaces:
ActionListener, Serializable, Cloneable, EventListener, Action
Direct Known Subclasses:
DefaultEditorKit.BeepAction, DefaultEditorKit.CopyAction, DefaultEditorKit.CutAction, DefaultEditorKit.DefaultKeyTypedAction, DefaultEditorKit.InsertBreakAction, DefaultEditorKit.InsertContentAction, DefaultEditorKit.InsertTabAction, DefaultEditorKit.PasteAction, StyledEditorKit.StyledTextAction
public abstract class TextAction
extends AbstractAction

An Action implementation useful for key bindings that are shared across a number of different text components. Because the action is shared, it must have a way of getting it's target to act upon. This class provides support to try and find a text component to operate on. The preferred way of getting the component to act upon is through the ActionEvent that is received. If the Object returned by getSource can be narrowed to a text component, it will be used. If the action event is null or can't be narrowed, the last focused text component is tried. This is determined by being used in conjunction with a JTextController which arranges to share that information with a TextAction.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class javax.swing.AbstractAction
changeSupport, enabled
Fields inherited from interface javax.swing.Action
ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON
Constructor Summary
TextAction(String name)
Creates a new JTextAction object.
Method Summary
static Action[] | augmentList(Action[] list1, Action[] list2) Takes one list of commands and augments it with another list of commands.
protected JTextComponent | getFocusedComponent() Fetches the text component that currently has focus.
protected JTextComponent | getTextComponent(ActionEvent e) Determines the component to use for the action.
Methods inherited from class javax.swing.AbstractAction
addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface java.awt.event.ActionListener
actionPerformed

Constructor Detail

TextAction

public TextAction(String name)
Creates a new JTextAction object.

Parameters:
name - the name of the action
Method Detail

getTextComponent

protected final JTextComponent getTextComponent(ActionEvent e)
Determines the component to use for the action. This if fetched from the source of the ActionEvent if it's not null and can be narrowed. Otherwise, the last focused component is used.

Parameters:
e - the ActionEvent
Returns:
the component

augmentList

public static final Action[] augmentList(Action[] list1,
                                         Action[] list2)
Takes one list of commands and augments it with another list of commands. The second list takes precedence over the first list; that is, when both lists contain a command with the same name, the command from the second list is used.

Parameters:
list1 - the first list, may be empty but not null
list2 - the second list, may be empty but not null
Returns:
the augmented list

getFocusedComponent

protected final JTextComponent getFocusedComponent()
Fetches the text component that currently has focus. This allows actions to be shared across text components which is useful for key-bindings where a large set of actions are defined, but generally used the same way across many different components.

Returns:
the component
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Utilities

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class Utilities

java.lang.Object
    extended by  javax.swing.text.Utilities

public class Utilities
extends Object

A collection of methods to deal with various text related activities.

Constructor Summary
Utilities()
Method Summary
static int | drawTabbedText(Segment s, int x, int y, Graphics g, TabExpander e, int startOffset) Draws the given text, expanding any tabs that are contained using the given tab expansion technique.
static int | getBreakLocation(Segment s, FontMetrics metrics, int x0, int x, TabExpander e, int startOffset) Determine where to break the given text to fit within the given span.
static int | getNextWord(JTextComponent c, int offs) Determines the start of the next word for the given location.
static Element | getParagraphElement(JTextComponent c, int offs) Determines the element to use for a paragraph/line.
static int | getPositionAbove(JTextComponent c, int offs, int x) Determines the position in the model that is closest to the given view location in the row above.
static int | getPositionBelow(JTextComponent c, int offs, int x) Determines the position in the model that is closest to the given view location in the row below.
static int | getPreviousWord(JTextComponent c, int offs) Determine the start of the prev word for the given location.
static int | getRowEnd(JTextComponent c, int offs) Determines the ending row model position of the row that contains the specified model position.
static int | getRowStart(JTextComponent c, int offs) Determines the starting row model position of the row that contains the specified model position.
static int | getTabbedTextOffset(Segment s, FontMetrics metrics, int x0, int x, TabExpander e, int startOffset) Determines the relative offset into the given text that best represents the given span in the view coordinate system.
static int | getTabbedTextOffset(Segment s, FontMetrics metrics, int x0, int x, TabExpander e, int startOffset, boolean round)
static int | getTabbedTextWidth(Segment s, FontMetrics metrics, int x, TabExpander e, int startOffset) Determines the width of the given segment of text taking tabs into consideration.
static int | getWordEnd(JTextComponent c, int offs) Determines the end of a word for the given location.
static int | getWordStart(JTextComponent c, int offs) Determines the start of a word for the given model location.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Utilities

public Utilities()
Method Detail

drawTabbedText

public static final int drawTabbedText(Segment s,
                                       int x,
                                       int y,
                                       Graphics g,
                                       TabExpander e,
                                       int startOffset)
Draws the given text, expanding any tabs that are contained using the given tab expansion technique. This particular implementation renders in a 1.1 style coordinate system where ints are used and 72dpi is assumed.

Parameters:
s - the source of the text
x - the X origin >= 0
y - the Y origin >= 0
g - the graphics context
e - how to expand the tabs. If this value is null, tabs will be expanded as a space character.
startOffset - starting offset of the text in the document >= 0
Returns:
the X location at the end of the rendered text

getTabbedTextWidth

public static final int getTabbedTextWidth(Segment s,
                                           FontMetrics metrics,
                                           int x,
                                           TabExpander e,
                                           int startOffset)
Determines the width of the given segment of text taking tabs into consideration. This is implemented in a 1.1 style coordinate system where ints are used and 72dpi is assumed.

Parameters:
s - the source of the text
metrics - the font metrics to use for the calculation
x - the X origin >= 0
e - how to expand the tabs. If this value is null, tabs will be expanded as a space character.
startOffset - starting offset of the text in the document >= 0
Returns:
the width of the text

getTabbedTextOffset

public static final int getTabbedTextOffset(Segment s,
                                            FontMetrics metrics,
                                            int x0,
                                            int x,
                                            TabExpander e,
                                            int startOffset)
Determines the relative offset into the given text that best represents the given span in the view coordinate system. This is implemented in a 1.1 style coordinate system where ints are used and 72dpi is assumed.

Parameters:
s - the source of the text
metrics - the font metrics to use for the calculation
x0 - the starting view location representing the start of the given text >= 0.
x - the target view location to translate to an offset into the text >= 0.
e - how to expand the tabs. If this value is null, tabs will be expanded as a space character.
startOffset - starting offset of the text in the document >= 0
Returns:
the offset into the text >= 0

getTabbedTextOffset

public static final int getTabbedTextOffset(Segment s,
                                            FontMetrics metrics,
                                            int x0,
                                            int x,
                                            TabExpander e,
                                            int startOffset,
                                            boolean round)

getBreakLocation

public static final int getBreakLocation(Segment s,
                                         FontMetrics metrics,
                                         int x0,
                                         int x,
                                         TabExpander e,
                                         int startOffset)
Determine where to break the given text to fit within the given span. This tries to find a word boundary.

Parameters:
s - the source of the text
metrics - the font metrics to use for the calculation
x0 - the starting view location representing the start of the given text.
x - the target view location to translate to an offset into the text.
e - how to expand the tabs. If this value is null, tabs will be expanded as a space character.
startOffset - starting offset in the document of the text
Returns:
the offset into the given text

getRowStart

public static final int getRowStart(JTextComponent c,
                                    int offs)
                             throws BadLocationException
Determines the starting row model position of the row that contains the specified model position. The component given must have a size to compute the result. If the component doesn't have a size a value of -1 will be returned.

Parameters:
c - the editor
offs - the offset in the document >= 0
Returns:
the position >= 0 if the request can be computed, otherwise a value of -1 will be returned.
Throws:
BadLocationException - if the offset is out of range

getRowEnd

public static final int getRowEnd(JTextComponent c,
                                  int offs)
                           throws BadLocationException
Determines the ending row model position of the row that contains the specified model position. The component given must have a size to compute the result. If the component doesn't have a size a value of -1 will be returned.

Parameters:
c - the editor
offs - the offset in the document >= 0
Returns:
the position >= 0 if the request can be computed, otherwise a value of -1 will be returned.
Throws:
BadLocationException - if the offset is out of range

getPositionAbove

public static final int getPositionAbove(JTextComponent c,
                                         int offs,
                                         int x)
                                  throws BadLocationException
Determines the position in the model that is closest to the given view location in the row above. The component given must have a size to compute the result. If the component doesn't have a size a value of -1 will be returned.

Parameters:
c - the editor
offs - the offset in the document >= 0
x - the X coordinate >= 0
Returns:
the position >= 0 if the request can be computed, otherwise a value of -1 will be returned.
Throws:
BadLocationException - if the offset is out of range

getPositionBelow

public static final int getPositionBelow(JTextComponent c,
                                         int offs,
                                         int x)
                                  throws BadLocationException
Determines the position in the model that is closest to the given view location in the row below. The component given must have a size to compute the result. If the component doesn't have a size a value of -1 will be returned.

Parameters:
c - the editor
offs - the offset in the document >= 0
x - the X coordinate >= 0
Returns:
the position >= 0 if the request can be computed, otherwise a value of -1 will be returned.
Throws:
BadLocationException - if the offset is out of range

getWordStart

public static final int getWordStart(JTextComponent c,
                                     int offs)
                              throws BadLocationException
Determines the start of a word for the given model location. Uses BreakIterator.getWordInstance() to actually get the words.

Parameters:
c - the editor
offs - the offset in the document >= 0
Returns:
the location in the model of the word start >= 0
Throws:
BadLocationException - if the offset is out of range

getWordEnd

public static final int getWordEnd(JTextComponent c,
                                   int offs)
                            throws BadLocationException
Determines the end of a word for the given location. Uses BreakIterator.getWordInstance() to actually get the words.

Parameters:
c - the editor
offs - the offset in the document >= 0
Returns:
the location in the model of the word end >= 0
Throws:
BadLocationException - if the offset is out of range

getNextWord

public static final int getNextWord(JTextComponent c,
                                    int offs)
                             throws BadLocationException
Determines the start of the next word for the given location. Uses BreakIterator.getWordInstance() to actually get the words.

Parameters:
c - the editor
offs - the offset in the document >= 0
Returns:
the location in the model of the word start >= 0
Throws:
BadLocationException - if the offset is out of range

getPreviousWord

public static final int getPreviousWord(JTextComponent c,
                                        int offs)
                                 throws BadLocationException
Determine the start of the prev word for the given location. Uses BreakIterator.getWordInstance() to actually get the words.

Parameters:
c - the editor
offs - the offset in the document >= 0
Returns:
the location in the model of the word start >= 0
Throws:
BadLocationException - if the offset is out of range

getParagraphElement

public static final Element getParagraphElement(JTextComponent c,
                                                int offs)
Determines the element to use for a paragraph/line.

Parameters:
c - the editor
offs - the starting offset in the document >= 0
Returns:
the element
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


View

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class View

java.lang.Object
    extended by  javax.swing.text.View
All Implemented Interfaces:
SwingConstants
Direct Known Subclasses:
AsyncBoxView, ComponentView, CompositeView, GlyphView, IconView, ImageView, PlainView
public abstract class View
extends Object
implements SwingConstants

A very important part of the text package is the View class. As the name suggests it represents a view of the text model, or a piece of the text model. It is this class that is responsible for the look of the text component. The view is not intended to be some completely new thing that one must learn, but rather is much like a lightweight component.

By default, a view is very light. It contains a reference to the parent view from which it can fetch many things without holding state, and it contains a reference to a portion of the model (Element). A view does not have to exactly represent an element in the model, that is simply a typical and therefore convenient mapping. A view can alternatively maintain a couple of Position objects to maintain its location in the model (i.e. represent a fragment of an element). This is typically the result of formatting where views have been broken down into pieces. The convenience of a substantial relationship to the element makes it easier to build factories to produce the views, and makes it easier to keep track of the view pieces as the model is changed and the view must be changed to reflect the model. Simple views therefore represent an Element directly and complex views do not.

A view has the following responsibilities:

Participate in layout.

The view has a setSize method which is like doLayout and setSize in Component combined. The view has a preferenceChanged method which is like invalidate in Component except that one can invalidate just one axis and the child requesting the change is identified.

A View expresses the size that it would like to be in terms of three values, a minimum, a preferred, and a maximum span. Layout in a view is can be done independently upon each axis. For a properly functioning View implementation, the minimum span will be <= the preferred span which in turn will be <= the maximum span.

The above text describes this graphic.

The minimum set of methods for layout are:

  • getMinimumSpan
  • getPreferredSpan
  • getMaximumSpan
  • getAlignment
  • preferenceChanged
  • setSize

The setSize method should be prepared to be called a number of times (i.e. It may be called even if the size didn't change). The setSize method is generally called to make sure the View layout is complete prior to trying to perform an operation on it that requires an up-to-date layout. A view's size should always be set to a value within the minimum and maximum span specified by that view. Additionally, the view must always call the preferenceChanged method on the parent if it has changed the values for the layout it would like, and expects the parent to honor. The parent View is not required to recognize a change until the preferenceChanged has been sent. This allows parent View implementations to cache the child requirements if desired. The calling sequence looks something like the following:

Sample calling sequence between parent view and child view: setSize, getMinimum, getPreferred, getMaximum, getAlignment, setSize

The exact calling sequence is up to the layout functionality of the parent view (if the view has any children). The view may collect the preferences of the children prior to determining what it will give each child, or it might iteratively update the children one at a time.

Render a portion of the model.

This is done in the paint method, which is pretty much like a component paint method. Views are expected to potentially populate a fairly large tree. A View has the following semantics for rendering:

  • The view gets its allocation from the parent at paint time, so it must be prepared to redo layout if the allocated area is different from what it is prepared to deal with.
  • The coordinate system is the same as the hosting Component (i.e. the Component returned by the getContainer method). This means a child view lives in the same coordinate system as the parent view unless the parent has explicitly changed the coordinate system. To schedule itself to be repainted a view can call repaint on the hosting Component.
  • The default is to not clip the children. It is more efficient to allow a view to clip only if it really feels it needs clipping.
  • The Graphics object given is not initialized in any way. A view should set any settings needed.
  • A View is inherently transparent. While a view may render into its entire allocation, typically a view does not. Rendering is performed by tranversing down the tree of View implementations. Each View is responsible for rendering its children. This behavior is depended upon for thread safety. While view implementations do not necessarily have to be implemented with thread safety in mind, other view implementations that do make use of concurrency can depend upon a tree traversal to guarantee thread safety.
  • The order of views relative to the model is up to the implementation. Although child views will typically be arranged in the same order that they occur in the model, they may be visually arranged in an entirely different order. View implementations may have Z-Order associated with them if the children are overlapping.

The methods for rendering are:

  • paint

Translate between the model and view coordinate systems.

Because the view objects are produced from a factory and therefore cannot necessarily be counted upon to be in a particular pattern, one must be able to perform translation to properly locate spatial representation of the model. The methods for doing this are:

  • modelToView
  • viewToModel
  • getDocument
  • getElement
  • getStartOffset
  • getEndOffset

The layout must be valid prior to attempting to make the translation. The translation is not valid, and must not be attempted while changes are being broadcasted from the model via a DocumentEvent.

Respond to changes from the model.

If the overall view is represented by many pieces (which is the best situation if one want to be able to change the view and write the least amount of new code), it would be impractical to have a huge number of DocumentListeners. If each view listened to the model, only a few would actually be interested in the changes broadcasted at any given time. Since the model has no knowledge of views, it has no way to filter the broadcast of change information. The view hierarchy itself is instead responsible for propagating the change information. At any level in the view hierarchy, that view knows enough about its children to best distribute the change information further. Changes are therefore broadcasted starting from the root of the view hierarchy. The methods for doing this are:

  • insertUpdate
  • removeUpdate
  • changedUpdate

Field Summary
static int | BadBreakWeight The weight to indicate a view is a bad break opportunity for the purpose of formatting.
static int | ExcellentBreakWeight The weight to indicate a view supports breaking, and this represents a very attractive place to break.
static int | ForcedBreakWeight The weight to indicate a view supports breaking, and must be broken to be represented properly when placed in a view that formats its children by breaking them.
static int | GoodBreakWeight The weight to indicate a view supports breaking, but better opportunities probably exist.
static int | X_AXIS Axis for format/break operations.
static int | Y_AXIS Axis for format/break operations.
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
View(Element elem)
Creates a new View object.
Method Summary
void | append(View v) Appends a single child view.
View | breakView(int axis, int offset, float pos, float len) Tries to break this view on the given axis.
void | changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
View | createFragment(int p0, int p1) Creates a view that represents a portion of the element.
protected void | forwardUpdate(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a, ViewFactory f) Forwards the given DocumentEvent to the child views that need to be notified of the change to the model.
protected void | forwardUpdateToView(View v, DocumentEvent e, Shape a, ViewFactory f) Forwards the DocumentEvent to the give child view.
float | getAlignment(int axis) Determines the desired alignment for this view along an axis.
AttributeSet | getAttributes() Fetches the attributes to use when rendering.
int | getBreakWeight(int axis, float pos, float len) Determines how attractive a break opportunity in this view is.
Shape | getChildAllocation(int index, Shape a) Fetches the allocation for the given child view.
Container | getContainer() Fetches the container hosting the view.
Document | getDocument() Fetches the model associated with the view.
Element | getElement() Fetches the structural portion of the subject that this view is mapped to.
int | getEndOffset() Fetches the portion of the model for which this view is responsible.
Graphics | getGraphics() Fetch a Graphics for rendering.
float | getMaximumSpan(int axis) Determines the maximum span for this view along an axis.
float | getMinimumSpan(int axis) Determines the minimum span for this view along an axis.
int | getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) Provides a way to determine the next visually represented model location at which one might place a caret.
View | getParent() Returns the parent of the view.
abstract float | getPreferredSpan(int axis) Determines the preferred span for this view along an axis.
int | getResizeWeight(int axis) Determines the resizability of the view along the given axis.
int | getStartOffset() Fetches the portion of the model for which this view is responsible.
String | getToolTipText(float x, float y, Shape allocation) Returns the tooltip text at the specified location.
View | getView(int n) Gets the nth child view.
int | getViewCount() Returns the number of views in this view.
ViewFactory | getViewFactory() Fetches the ViewFactory implementation that is feeding the view hierarchy.
int | getViewIndex(float x, float y, Shape allocation) Returns the child view index representing the given position in the view.
int | getViewIndex(int pos, Position.Bias b) Returns the child view index representing the given position in the model.
void | insert(int offs, View v) Inserts a single child view.
void | insertUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
boolean | isVisible() Returns a boolean that indicates whether the view is visible or not.
Shape | modelToView(int p0, Position.Bias b0, int p1, Position.Bias b1, Shape a) Provides a mapping, for a given region, from the document model coordinate space to the view coordinate space.
Shape | modelToView(int pos, Shape a) Deprecated.
abstract Shape | modelToView(int pos, Shape a, Position.Bias b) Provides a mapping, for a given character, from the document model coordinate space to the view coordinate space.
abstract void | paint(Graphics g, Shape allocation) Renders using the given rendering surface and area on that surface.
void | preferenceChanged(View child, boolean width, boolean height) Child views can call this on the parent to indicate that the preference has changed and should be reconsidered for layout.
void | remove(int i) Removes one of the children at the given position.
void | removeAll() Removes all of the children.
void | removeUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | replace(int offset, int length, View[] views) Replaces child views.
void | setParent(View parent) Establishes the parent view for this view.
void | setSize(float width, float height) Sets the size of the view.
protected boolean | updateChildren(DocumentEvent.ElementChange ec, DocumentEvent e, ViewFactory f) Updates the child views in response to receiving notification that the model changed, and there is change record for the element this view is responsible for.
protected void | updateLayout(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a) Updates the layout in response to receiving notification of change from the model.
int | viewToModel(float x, float y, Shape a) Deprecated.
abstract int | viewToModel(float x, float y, Shape a, Position.Bias[] biasReturn) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

BadBreakWeight

public static final int BadBreakWeight
The weight to indicate a view is a bad break opportunity for the purpose of formatting. This value indicates that no attempt should be made to break the view into fragments as the view has not been written to support fragmenting.

See Also:
getBreakWeight(int, float, float), GoodBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, Constant Field Values

GoodBreakWeight

public static final int GoodBreakWeight
The weight to indicate a view supports breaking, but better opportunities probably exist.

See Also:
getBreakWeight(int, float, float), BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, Constant Field Values

ExcellentBreakWeight

public static final int ExcellentBreakWeight
The weight to indicate a view supports breaking, and this represents a very attractive place to break.

See Also:
getBreakWeight(int, float, float), BadBreakWeight, GoodBreakWeight, ForcedBreakWeight, Constant Field Values

ForcedBreakWeight

public static final int ForcedBreakWeight
The weight to indicate a view supports breaking, and must be broken to be represented properly when placed in a view that formats its children by breaking them.

See Also:
getBreakWeight(int, float, float), BadBreakWeight, GoodBreakWeight, ExcellentBreakWeight, Constant Field Values

X_AXIS

public static final int X_AXIS
Axis for format/break operations.

See Also:
Constant Field Values

Y_AXIS

public static final int Y_AXIS
Axis for format/break operations.

See Also:
Constant Field Values
Constructor Detail

View

public View(Element elem)
Creates a new View object.

Parameters:
elem - the Element to represent
Method Detail

getParent

public View getParent()
Returns the parent of the view.

Returns:
the parent, or null if none exists

isVisible

public boolean isVisible()
Returns a boolean that indicates whether the view is visible or not. By default all views are visible.

Returns:
always returns true

getPreferredSpan

public abstract float getPreferredSpan(int axis)
Determines the preferred span for this view along an axis.

Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into. Typically the view is told to render into the span that is returned, although there is no guarantee. The parent may choose to resize or break the view
See Also:
getPreferredSpan(int)

getMinimumSpan

public float getMinimumSpan(int axis)
Determines the minimum span for this view along an axis.

Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the minimum span the view can be rendered into
See Also:
getPreferredSpan(int)

getMaximumSpan

public float getMaximumSpan(int axis)
Determines the maximum span for this view along an axis.

Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the maximum span the view can be rendered into
See Also:
getPreferredSpan(int)

preferenceChanged

public void preferenceChanged(View child,
                              boolean width,
                              boolean height)
Child views can call this on the parent to indicate that the preference has changed and should be reconsidered for layout. By default this just propagates upward to the next parent. The root view will call revalidate on the associated text component.

Parameters:
child - the child view
width - true if the width preference has changed
height - true if the height preference has changed
See Also:
JComponent.revalidate()

getAlignment

public float getAlignment(int axis)
Determines the desired alignment for this view along an axis. The desired alignment is returned. This should be a value >= 0.0 and <= 1.0,="1.0," where="where" 0="0" indicates="indicates" alignment="alignment" at="at" the="the" origin="origin" and="and" 1.0="1.0" indicates="indicates" alignment="alignment" to="to" the="the" full="full" span="span" away="away" from="from" the="the" origin.="origin." An="An" alignment="alignment" of="of" 0.5="0.5" would="would" be="be" the="the" center="center" of="of" the="the" view.="view."
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the value 0.5

paint

public abstract void paint(Graphics g,
                           Shape allocation)
Renders using the given rendering surface and area on that surface. The view may need to do layout and create child views to enable itself to render into the given allocation.

Parameters:
g - the rendering surface to use
allocation - the allocated region to render into

setParent

public void setParent(View parent)
Establishes the parent view for this view. This is guaranteed to be called before any other methods if the parent view is functioning properly. This is also the last method called, since it is called to indicate the view has been removed from the hierarchy as well. When this method is called to set the parent to null, this method does the same for each of its children, propogating the notification that they have been disconnected from the view tree. If this is reimplemented, super.setParent() should be called.

Parameters:
parent - the new parent, or null if the view is being removed from a parent

getViewCount

public int getViewCount()
Returns the number of views in this view. Since the default is to not be a composite view this returns 0.

Returns:
the number of views >= 0
See Also:
getViewCount()

getView

public View getView(int n)
Gets the nth child view. Since there are no children by default, this returns null.

Parameters:
n - the number of the view to get, >= 0 && < getViewCount()
Returns:
the view

removeAll

public void removeAll()
Removes all of the children. This is a convenience call to replace.

Since:
1.3

remove

public void remove(int i)
Removes one of the children at the given position. This is a convenience call to replace.

Since:
1.3

insert

public void insert(int offs,
                   View v)
Inserts a single child view. This is a convenience call to replace.

Parameters:
offs - the offset of the view to insert before >= 0
v - the view
Since:
1.3
See Also:
replace(int, int, javax.swing.text.View[])

append

public void append(View v)
Appends a single child view. This is a convenience call to replace.

Parameters:
v - the view
Since:
1.3
See Also:
replace(int, int, javax.swing.text.View[])

replace

public void replace(int offset,
                    int length,
                    View[] views)
Replaces child views. If there are no views to remove this acts as an insert. If there are no views to add this acts as a remove. Views being removed will have the parent set to null, and the internal reference to them removed so that they can be garbage collected. This is implemented to do nothing, because by default a view has no children.

Parameters:
offset - the starting index into the child views to insert the new views. This should be a value >= 0 and <= getViewCountlength - the number of existing child views to remove This should be a value >= 0 and <= (getViewCount()="(getViewCount()" -="-" offset).views - the child views to add. This value can be null to indicate no children are being added (useful to remove).
Since:
1.3

getViewIndex

public int getViewIndex(int pos,
                        Position.Bias b)
Returns the child view index representing the given position in the model. By default a view has no children so this is implemented to return -1 to indicate there is no valid child index for any position.

Parameters:
pos - the position >= 0
Returns:
index of the view representing the given position, or -1 if no view represents that position
Since:
1.3

getChildAllocation

public Shape getChildAllocation(int index,
                                Shape a)
Fetches the allocation for the given child view. This enables finding out where various views are located, without assuming how the views store their location. This returns null since the default is to not have any child views.

Parameters:
index - the index of the child, >= 0 && <getViewCount()
a - the allocation to this view
Returns:
the allocation to the child

getNextVisualPositionFrom

public int getNextVisualPositionFrom(int pos,
                                     Position.Bias b,
                                     Shape a,
                                     int direction,
                                     Position.Bias[] biasRet)
                              throws BadLocationException
Provides a way to determine the next visually represented model location at which one might place a caret. Some views may not be visible, they might not be in the same order found in the model, or they just might not allow access to some of the locations in the model.

Parameters:
pos - the position to convert >= 0
a - the allocated region in which to render
direction - the direction from the current position that can be thought of as the arrow keys typically found on a keyboard. This will be one of the following values:
  • SwingConstants.WEST
  • SwingConstants.EAST
  • SwingConstants.NORTH
  • SwingConstants.SOUTH
Returns:
the location within the model that best represents the next location visual position
Throws:
BadLocationException
IllegalArgumentException - if direction doesn't have one of the legal values above

modelToView

public abstract Shape modelToView(int pos,
                                  Shape a,
                                  Position.Bias b)
                           throws BadLocationException
Provides a mapping, for a given character, from the document model coordinate space to the view coordinate space.

Parameters:
pos - the position of the desired character (>=0)
a - the area of the view, which encompasses the requested character
b - the bias toward the previous character or the next character represented by the offset, in case the position is a boundary of two views; b will have one of these values:
  • Position.Bias.Forward
  • Position.Bias.Backward
Returns:
the bounding box, in view coordinate space, of the character at the specified position
Throws:
BadLocationException - if the specified position does not represent a valid location in the associated document
IllegalArgumentException - if b is not one of the legal Position.Bias values listed above
See Also:
viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])

modelToView

public Shape modelToView(int p0,
                         Position.Bias b0,
                         int p1,
                         Position.Bias b1,
                         Shape a)
                  throws BadLocationException
Provides a mapping, for a given region, from the document model coordinate space to the view coordinate space. The specified region is created as a union of the first and last character positions.

Parameters:
p0 - the position of the first character (>=0)
b0 - the bias of the first character position, toward the previous character or the next character represented by the offset, in case the position is a boundary of two views; b0 will have one of these values:
  • Position.Bias.Forward
  • Position.Bias.Backward
p1 - the position of the last character (>=0)
b1 - the bias for the second character position, defined one of the legal values shown above
a - the area of the view, which encompasses the requested region
Returns:
the bounding box which is a union of the region specified by the first and last character positions
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
IllegalArgumentException - if b0 or b1 are not one of the legal Position.Bias values listed above
See Also:
viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])

viewToModel

public abstract int viewToModel(float x,
                                float y,
                                Shape a,
                                Position.Bias[] biasReturn)
Provides a mapping from the view coordinate space to the logical coordinate space of the model. The biasReturn argument will be filled in to indicate that the point given is closer to the next character in the model or the previous character in the model.

Parameters:
x - the X coordinate >= 0
y - the Y coordinate >= 0
a - the allocated region in which to render
Returns:
the location within the model that best represents the given point in the view >= 0. The biasReturn argument will be filled in to indicate that the point given is closer to the next character in the model or the previous character in the model.

insertUpdate

public void insertUpdate(DocumentEvent e,
                         Shape a,
                         ViewFactory f)
Gives notification that something was inserted into the document in a location that this view is responsible for. To reduce the burden to subclasses, this functionality is spread out into the following calls that subclasses can reimplement:
  1. updateChildren is called if there were any changes to the element this view is responsible for. If this view has child views that are represent the child elements, then this method should do whatever is necessary to make sure the child views correctly represent the model.
  2. forwardUpdate is called to forward the DocumentEvent to the appropriate child views.
  3. updateLayout is called to give the view a chance to either repair its layout, to reschedule layout, or do nothing.

Parameters:
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

removeUpdate

public void removeUpdate(DocumentEvent e,
                         Shape a,
                         ViewFactory f)
Gives notification that something was removed from the document in a location that this view is responsible for. To reduce the burden to subclasses, this functionality is spread out into the following calls that subclasses can reimplement:
  1. updateChildren is called if there were any changes to the element this view is responsible for. If this view has child views that are represent the child elements, then this method should do whatever is necessary to make sure the child views correctly represent the model.
  2. forwardUpdate is called to forward the DocumentEvent to the appropriate child views.
  3. updateLayout is called to give the view a chance to either repair its layout, to reschedule layout, or do nothing.

Parameters:
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

changedUpdate

public void changedUpdate(DocumentEvent e,
                          Shape a,
                          ViewFactory f)
Gives notification from the document that attributes were changed in a location that this view is responsible for. To reduce the burden to subclasses, this functionality is spread out into the following calls that subclasses can reimplement:
  1. updateChildren is called if there were any changes to the element this view is responsible for. If this view has child views that are represent the child elements, then this method should do whatever is necessary to make sure the child views correctly represent the model.
  2. forwardUpdate is called to forward the DocumentEvent to the appropriate child views.
  3. updateLayout is called to give the view a chance to either repair its layout, to reschedule layout, or do nothing.

Parameters:
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

getDocument

public Document getDocument()
Fetches the model associated with the view.

Returns:
the view model, null if none
See Also:
getDocument()

getStartOffset

public int getStartOffset()
Fetches the portion of the model for which this view is responsible.

Returns:
the starting offset into the model >= 0
See Also:
getStartOffset()

getEndOffset

public int getEndOffset()
Fetches the portion of the model for which this view is responsible.

Returns:
the ending offset into the model >= 0
See Also:
getEndOffset()

getElement

public Element getElement()
Fetches the structural portion of the subject that this view is mapped to. The view may not be responsible for the entire portion of the element.

Returns:
the subject
See Also:
getElement()

getGraphics

public Graphics getGraphics()
Fetch a Graphics for rendering. This can be used to determine font characteristics, and will be different for a print view than a component view.

Returns:
a Graphics object for rendering
Since:
1.3

getAttributes

public AttributeSet getAttributes()
Fetches the attributes to use when rendering. By default this simply returns the attributes of the associated element. This method should be used rather than using the element directly to obtain access to the attributes to allow view-specific attributes to be mixed in or to allow the view to have view-specific conversion of attributes by subclasses. Each view should document what attributes it recognizes for the purpose of rendering or layout, and should always access them through the AttributeSet returned by this method.

breakView

public View breakView(int axis,
                      int offset,
                      float pos,
                      float len)
Tries to break this view on the given axis. This is called by views that try to do formatting of their children. For example, a view of a paragraph will typically try to place its children into row and views representing chunks of text can sometimes be broken down into smaller pieces.

This is implemented to return the view itself, which represents the default behavior on not being breakable. If the view does support breaking, the starting offset of the view returned should be the given offset, and the end offset should be less than or equal to the end offset of the view being broken.

Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
offset - the location in the document model that a broken fragment would occupy >= 0. This would be the starting offset of the fragment returned
pos - the position along the axis that the broken view would occupy >= 0. This may be useful for things like tab calculations
len - specifies the distance along the axis where a potential break is desired >= 0
Returns:
the fragment of the view that represents the given span, if the view can be broken. If the view doesn't support breaking behavior, the view itself is returned.
See Also:
ParagraphView

createFragment

public View createFragment(int p0,
                           int p1)
Creates a view that represents a portion of the element. This is potentially useful during formatting operations for taking measurements of fragments of the view. If the view doesn't support fragmenting (the default), it should return itself.

Parameters:
p0 - the starting offset >= 0. This should be a value greater or equal to the element starting offset and less than the element ending offset.
p1 - the ending offset > p0. This should be a value less than or equal to the elements end offset and greater than the elements starting offset.
Returns:
the view fragment, or itself if the view doesn't support breaking into fragments
See Also:
LabelView

getBreakWeight

public int getBreakWeight(int axis,
                          float pos,
                          float len)
Determines how attractive a break opportunity in this view is. This can be used for determining which view is the most attractive to call breakView on in the process of formatting. A view that represents text that has whitespace in it might be more attractive than a view that has no whitespace, for example. The higher the weight, the more attractive the break. A value equal to or lower than BadBreakWeight should not be considered for a break. A value greater than or equal to ForcedBreakWeight should be broken.

This is implemented to provide the default behavior of returning BadBreakWeight unless the length is greater than the length of the view in which case the entire view represents the fragment. Unless a view has been written to support breaking behavior, it is not attractive to try and break the view. An example of a view that does support breaking is LabelView. An example of a view that uses break weight is ParagraphView.

Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
pos - the potential location of the start of the broken view >= 0. This may be useful for calculating tab positions
len - specifies the relative length from pos where a potential break is desired >= 0
Returns:
the weight, which should be a value between ForcedBreakWeight and BadBreakWeight
See Also:
LabelView, ParagraphView, BadBreakWeight, GoodBreakWeight, ExcellentBreakWeight, ForcedBreakWeight

getResizeWeight

public int getResizeWeight(int axis)
Determines the resizability of the view along the given axis. A value of 0 or less is not resizable.

Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the weight

setSize

public void setSize(float width,
                    float height)
Sets the size of the view. This should cause layout of the view along the given axis, if it has any layout duties.

Parameters:
width - the width >= 0
height - the height >= 0

getContainer

public Container getContainer()
Fetches the container hosting the view. This is useful for things like scheduling a repaint, finding out the host components font, etc. The default implementation of this is to forward the query to the parent view.

Returns:
the container, null if none

getViewFactory

public ViewFactory getViewFactory()
Fetches the ViewFactory implementation that is feeding the view hierarchy. Normally the views are given this as an argument to updates from the model when they are most likely to need the factory, but this method serves to provide it at other times.

Returns:
the factory, null if none

getToolTipText

public String getToolTipText(float x,
                             float y,
                             Shape allocation)
Returns the tooltip text at the specified location. The default implementation returns the value from the child View identified by the passed in location.

Since:
1.4
See Also:
JTextComponent.getToolTipText(java.awt.event.MouseEvent)

getViewIndex

public int getViewIndex(float x,
                        float y,
                        Shape allocation)
Returns the child view index representing the given position in the view. This iterates over all the children returning the first with a bounds that contains x, y.

Parameters:
x - the x coordinate
y - the y coordinate
allocation - current allocation of the View.
Returns:
index of the view representing the given location, or -1 if no view represents that position
Since:
1.4

updateChildren

protected boolean updateChildren(DocumentEvent.ElementChange ec,
                                 DocumentEvent e,
                                 ViewFactory f)
Updates the child views in response to receiving notification that the model changed, and there is change record for the element this view is responsible for. This is implemented to assume the child views are directly responsible for the child elements of the element this view represents. The ViewFactory is used to create child views for each element specified as added in the ElementChange, starting at the index specified in the given ElementChange. The number of child views representing the removed elements specified are removed.

Parameters:
ec - the change information for the element this view is responsible for. This should not be null if this method gets called
e - the change information from the associated document
f - the factory to use to build child views
Returns:
whether or not the child views represent the child elements of the element this view is responsible for. Some views create children that represent a portion of the element they are responsible for, and should return false. This information is used to determine if views in the range of the added elements should be forwarded to or not
Since:
1.3
See Also:
insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory),
removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory),
changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

forwardUpdate

protected void forwardUpdate(DocumentEvent.ElementChange ec,
                             DocumentEvent e,
                             Shape a,
                             ViewFactory f)
Forwards the given DocumentEvent to the child views that need to be notified of the change to the model. If there were changes to the element this view is responsible for, that should be considered when forwarding (i.e. new child views should not get notified).

Parameters:
ec - changes to the element this view is responsible for (may be null if there were no changes).
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
Since:
1.3
See Also:
insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory),
removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory),
changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

forwardUpdateToView

protected void forwardUpdateToView(View v,
                                   DocumentEvent e,
                                   Shape a,
                                   ViewFactory f)
Forwards the DocumentEvent to the give child view. This simply messages the view with a call to insertUpdate, removeUpdate, or changedUpdate depending upon the type of the event. This is called by forwardUpdate to forward the event to children that need it.

Parameters:
v - the child view to forward the event to
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
Since:
1.3
See Also:
forwardUpdate(javax.swing.event.DocumentEvent.ElementChange, javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

updateLayout

protected void updateLayout(DocumentEvent.ElementChange ec,
                            DocumentEvent e,
                            Shape a)
Updates the layout in response to receiving notification of change from the model. This is implemented to call preferenceChanged to reschedule a new layout if the ElementChange record is not null.

Parameters:
ec - changes to the element this view is responsible for (may be null if there were no changes)
e - the change information from the associated document
a - the current allocation of the view
Since:
1.3
See Also:
insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory),
removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory),
changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

modelToView

@Deprecated
public Shape modelToView(int pos,
                                    Shape a)
                  throws BadLocationException
Deprecated.

Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it. This is implemented to default the bias to Position.Bias.Forward which was previously implied.

Parameters:
pos - the position to convert >= 0
a - the allocated region in which to render
Returns:
the bounding box of the given position is returned
Throws:
BadLocationException - if the given position does not represent a valid location in the associated document
See Also:
modelToView(int, java.awt.Shape, javax.swing.text.Position.Bias)

viewToModel

@Deprecated
public int viewToModel(float x,
                                  float y,
                                  Shape a)
Deprecated.

Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Parameters:
x - the X coordinate >= 0
y - the Y coordinate >= 0
a - the allocated region in which to render
Returns:
the location within the model that best represents the given point in the view >= 0
See Also:
viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ViewFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Interface ViewFactory

All Known Implementing Classes:
BasicEditorPaneUI, BasicFormattedTextFieldUI, BasicPasswordFieldUI, BasicTextAreaUI, BasicTextFieldUI, BasicTextPaneUI, BasicTextUI, DefaultTextUI, HTMLEditorKit.HTMLFactory, MetalTextFieldUI
public interface ViewFactory

A factory to create a view of some portion of document subject. This is intended to enable customization of how views get mapped over a document model.

Method Summary
 View create(Element elem)
Creates a view from the given structural element of a document.

Method Detail

create

View create(Element elem)
Creates a view from the given structural element of a document.

Parameters:
elem - the piece of the document to build a view of
Returns:
the view
See Also:
View
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WrappedPlainView

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class WrappedPlainView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.CompositeView
            extended by  javax.swing.text.BoxView
                extended by  javax.swing.text.WrappedPlainView
All Implemented Interfaces:
SwingConstants, TabExpander
public class WrappedPlainView
extends BoxView
implements TabExpander

View of plain text (text with only one font and color) that does line-wrapping. This view expects that its associated element has child elements that represent the lines it should be wrapping. It is implemented as a vertical box that contains logical line views. The logical line views are nested classes that render the logical line as multiple physical line if the logical line is too wide to fit within the allocation. The line views draw upon the outer class for its state to reduce their memory requirements.

The line views do all of their rendering through the drawLine method which in turn does all of its rendering through the drawSelectedText and drawUnselectedText methods. This enables subclasses to easily specialize the rendering without concern for the layout aspects.

See Also:
View

Field Summary
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
WrappedPlainView(Element elem)
Creates a new WrappedPlainView.
WrappedPlainView(Element elem, boolean wordWrap)
Creates a new WrappedPlainView.
Method Summary
protected int | calculateBreakPosition(int p0, int p1) This is called by the nested wrapped line views to determine the break location.
void | changedUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
protected void | drawLine(int p0, int p1, Graphics g, int x, int y) Renders a line of text, suppressing whitespace at the end and expanding any tabs.
protected int | drawSelectedText(Graphics g, int x, int y, int p0, int p1) Renders the given range in the model as selected text.
protected int | drawUnselectedText(Graphics g, int x, int y, int p0, int p1) Renders the given range in the model as normal unselected text.
protected Segment | getLineBuffer() Gives access to a buffer that can be used to fetch text from the associated document.
float | getMaximumSpan(int axis) Determines the maximum span for this view along an axis.
float | getMinimumSpan(int axis) Determines the minimum span for this view along an axis.
float | getPreferredSpan(int axis) Determines the preferred span for this view along an axis.
protected int | getTabSize() Returns the tab size set for the document, defaulting to 8.
void | insertUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
protected void | loadChildren(ViewFactory f) Loads all of the children to initialize the view.
float | nextTabStop(float x, int tabOffset) Returns the next tab stop position after a given reference position.
void | paint(Graphics g, Shape a) Renders using the given rendering surface and area on that surface.
void | removeUpdate(DocumentEvent e, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | setSize(float width, float height) Sets the size of the view.
Methods inherited from class javax.swing.text.BoxView
baselineLayout, baselineRequirements, calculateMajorAxisRequirements, calculateMinorAxisRequirements, childAllocation, flipEastAndWestAtEnds, forwardUpdate, getAlignment, getAxis, getChildAllocation, getHeight, getOffset, getResizeWeight, getSpan, getViewAtPoint, getWidth, isAfter, isAllocationValid, isBefore, isLayoutValid, layout, layoutChanged, layoutMajorAxis, layoutMinorAxis, modelToView, paintChild, preferenceChanged, replace, setAxis, viewToModel
Methods inherited from class javax.swing.text.CompositeView
getBottomInset, getInsideAllocation, getLeftInset, getNextEastWestVisualPositionFrom, getNextNorthSouthVisualPositionFrom, getNextVisualPositionFrom, getRightInset, getTopInset, getView, getViewAtPosition, getViewCount, getViewIndex, getViewIndexAtPosition, modelToView, setInsets, setParagraphInsets, setParent
Methods inherited from class javax.swing.text.View
append, breakView, createFragment, forwardUpdateToView, getAttributes, getBreakWeight, getContainer, getDocument, getElement, getEndOffset, getGraphics, getParent, getStartOffset, getToolTipText, getViewFactory, getViewIndex, insert, isVisible, modelToView, remove, removeAll, updateChildren, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WrappedPlainView

public WrappedPlainView(Element elem)
Creates a new WrappedPlainView. Lines will be wrapped on character boundaries.

Parameters:
elem - the element underlying the view

WrappedPlainView

public WrappedPlainView(Element elem,
                        boolean wordWrap)
Creates a new WrappedPlainView. Lines can be wrapped on either character or word boundaries depending upon the setting of the wordWrap parameter.

Parameters:
elem - the element underlying the view
wordWrap - should lines be wrapped on word boundaries?
Method Detail

getTabSize

protected int getTabSize()
Returns the tab size set for the document, defaulting to 8.

Returns:
the tab size

drawLine

protected void drawLine(int p0,
                        int p1,
                        Graphics g,
                        int x,
                        int y)
Renders a line of text, suppressing whitespace at the end and expanding any tabs. This is implemented to make calls to the methods drawUnselectedText and drawSelectedText so that the way selected and unselected text are rendered can be customized.

Parameters:
p0 - the starting document location to use >= 0
p1 - the ending document location to use >= p1
g - the graphics context
x - the starting X position >= 0
y - the starting Y position >= 0
See Also:
drawUnselectedText(java.awt.Graphics, int, int, int, int), drawSelectedText(java.awt.Graphics, int, int, int, int)

drawUnselectedText

protected int drawUnselectedText(Graphics g,
                                 int x,
                                 int y,
                                 int p0,
                                 int p1)
                          throws BadLocationException
Renders the given range in the model as normal unselected text.

Parameters:
g - the graphics context
x - the starting X coordinate >= 0
y - the starting Y coordinate >= 0
p0 - the beginning position in the model >= 0
p1 - the ending position in the model >= p0
Returns:
the X location of the end of the range >= 0
Throws:
BadLocationException - if the range is invalid

drawSelectedText

protected int drawSelectedText(Graphics g,
                               int x,
                               int y,
                               int p0,
                               int p1)
                        throws BadLocationException
Renders the given range in the model as selected text. This is implemented to render the text in the color specified in the hosting component. It assumes the highlighter will render the selected background.

Parameters:
g - the graphics context
x - the starting X coordinate >= 0
y - the starting Y coordinate >= 0
p0 - the beginning position in the model >= 0
p1 - the ending position in the model >= p0
Returns:
the location of the end of the range.
Throws:
BadLocationException - if the range is invalid

getLineBuffer

protected final Segment getLineBuffer()
Gives access to a buffer that can be used to fetch text from the associated document.

Returns:
the buffer

calculateBreakPosition

protected int calculateBreakPosition(int p0,
                                     int p1)
This is called by the nested wrapped line views to determine the break location. This can be reimplemented to alter the breaking behavior. It will either break at word or character boundaries depending upon the break argument given at construction.

loadChildren

protected void loadChildren(ViewFactory f)
Loads all of the children to initialize the view. This is called by the setParent method. Subclasses can reimplement this to initialize their child views in a different manner. The default implementation creates a child view for each child element.

Overrides:
loadChildren in class CompositeView
Parameters:
f - the view factory
See Also:
CompositeView.setParent(javax.swing.text.View)

nextTabStop

public float nextTabStop(float x,
                         int tabOffset)
Returns the next tab stop position after a given reference position. This implementation does not support things like centering so it ignores the tabOffset argument.

Specified by:
nextTabStop in interface TabExpander
Parameters:
x - the current position >= 0
tabOffset - the position within the text stream that the tab occurred at >= 0.
Returns:
the tab stop, measured in points >= 0

paint

public void paint(Graphics g,
                  Shape a)
Renders using the given rendering surface and area on that surface. This is implemented to stash the selection positions, selection colors, and font metrics for the nested lines to use.

Overrides:
paint in class BoxView
Parameters:
g - the rendering surface to use
a - the allocated region to render into
See Also:
View.paint(java.awt.Graphics, java.awt.Shape)

setSize

public void setSize(float width,
                    float height)
Sets the size of the view. This should cause layout of the view along the given axis, if it has any layout duties.

Overrides:
setSize in class BoxView
Parameters:
width - the width >= 0
height - the height >= 0

getPreferredSpan

public float getPreferredSpan(int axis)
Determines the preferred span for this view along an axis. This is implemented to provide the superclass behavior after first making sure that the current font metrics are cached (for the nested lines which use the metrics to determine the height of the potentially wrapped lines).

Overrides:
getPreferredSpan in class BoxView
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into. Typically the view is told to render into the span that is returned, although there is no guarantee. The parent may choose to resize or break the view.
See Also:
View.getPreferredSpan(int)

getMinimumSpan

public float getMinimumSpan(int axis)
Determines the minimum span for this view along an axis. This is implemented to provide the superclass behavior after first making sure that the current font metrics are cached (for the nested lines which use the metrics to determine the height of the potentially wrapped lines).

Overrides:
getMinimumSpan in class BoxView
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into. Typically the view is told to render into the span that is returned, although there is no guarantee. The parent may choose to resize or break the view.
See Also:
View.getMinimumSpan(int)

getMaximumSpan

public float getMaximumSpan(int axis)
Determines the maximum span for this view along an axis. This is implemented to provide the superclass behavior after first making sure that the current font metrics are cached (for the nested lines which use the metrics to determine the height of the potentially wrapped lines).

Overrides:
getMaximumSpan in class BoxView
Parameters:
axis - may be either View.X_AXIS or View.Y_AXIS
Returns:
the span the view would like to be rendered into. Typically the view is told to render into the span that is returned, although there is no guarantee. The parent may choose to resize or break the view.
See Also:
View.getMaximumSpan(int)

insertUpdate

public void insertUpdate(DocumentEvent e,
                         Shape a,
                         ViewFactory f)
Gives notification that something was inserted into the document in a location that this view is responsible for. This is implemented to simply update the children.

Overrides:
insertUpdate in class View
Parameters:
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

removeUpdate

public void removeUpdate(DocumentEvent e,
                         Shape a,
                         ViewFactory f)
Gives notification that something was removed from the document in a location that this view is responsible for. This is implemented to simply update the children.

Overrides:
removeUpdate in class View
Parameters:
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

changedUpdate

public void changedUpdate(DocumentEvent e,
                          Shape a,
                          ViewFactory f)
Gives notification from the document that attributes were changed in a location that this view is responsible for.

Overrides:
changedUpdate in class View
Parameters:
e - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ZoneView

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.text
Class ZoneView

java.lang.Object
    extended by  javax.swing.text.View
        extended by  javax.swing.text.CompositeView
            extended by  javax.swing.text.BoxView
                extended by  javax.swing.text.ZoneView
All Implemented Interfaces:
SwingConstants
public class ZoneView
extends BoxView

ZoneView is a View implementation that creates zones for which the child views are not created or stored until they are needed for display or model/view translations. This enables a substantial reduction in memory consumption for situations where the model being represented is very large, by building view objects only for the region being actively viewed/edited. The size of the children can be estimated in some way, or calculated asynchronously with only the result being saved.

ZoneView extends BoxView to provide a box that implements zones for its children. The zones are special View implementations (the children of an instance of this class) that represent only a portion of the model that an instance of ZoneView is responsible for. The zones don't create child views until an attempt is made to display them. A box shaped view is well suited to this because:

  • Boxes are a heavily used view, and having a box that provides this behavior gives substantial opportunity to plug the behavior into a view hierarchy from the view factory.
  • Boxes are tiled in one direction, so it is easy to divide them into zones in a reliable way.
  • Boxes typically have a simple relationship to the model (i.e. they create child views that directly represent the child elements).
  • Boxes are easier to estimate the size of than some other shapes.

The default behavior is controled by two properties, maxZoneSize and maxZonesLoaded. Setting maxZoneSize to Integer.MAX_VALUE would have the effect of causing only one zone to be created. This would effectively turn the view into an implementation of the decorator pattern. Setting maxZonesLoaded to a value of Integer.MAX_VALUE would cause zones to never be unloaded. For simplicity, zones are created on boundaries represented by the child elements of the element the view is responsible for. The zones can be any View implementation, but the default implementation is based upon AsyncBoxView which supports fairly large zones efficiently.

Since:
1.3
See Also:
View

Field Summary
Fields inherited from class javax.swing.text.View
BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight, GoodBreakWeight, X_AXIS, Y_AXIS
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor Summary
ZoneView(Element elem, int axis)
Constructs a ZoneView.
Method Summary
protected View | createZone(int p0, int p1) Create a view to represent a zone for the given range within the model (which should be within the range of this objects responsibility).
int | getMaximumZoneSize() Get the current maximum zone size.
int | getMaxZonesLoaded() Get the current setting of the number of zones allowed to be loaded at the same time.
protected int | getViewIndexAtPosition(int pos) Returns the child view index representing the given position in the model.
void | insertUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was inserted into the document in a location that this view is responsible for.
protected boolean | isZoneLoaded(View zone) Determine if a zone is in the loaded state.
protected void | loadChildren(ViewFactory f) Loads all of the children to initialize the view.
void | removeUpdate(DocumentEvent changes, Shape a, ViewFactory f) Gives notification that something was removed from the document in a location that this view is responsible for.
void | setMaximumZoneSize(int size) Set the desired maximum zone size.
void | setMaxZonesLoaded(int mzl) Sets the current setting of the number of zones allowed to be loaded at the same time.
protected void | unloadZone(View zone) Unload a zone (Convert the zone to its memory saving state).
protected boolean | updateChildren(DocumentEvent.ElementChange ec, DocumentEvent e, ViewFactory f) The superclass behavior will try to update the child views which is not desired in this case, since the children are zones and not directly effected by the changes to the associated element.
protected void | zoneWasLoaded(View zone) Called by a zone when it gets loaded.
Methods inherited from class javax.swing.text.BoxView
baselineLayout, baselineRequirements, calculateMajorAxisRequirements, calculateMinorAxisRequirements, childAllocation, flipEastAndWestAtEnds, forwardUpdate, getAlignment, getAxis, getChildAllocation, getHeight, getMaximumSpan, getMinimumSpan, getOffset, getPreferredSpan, getResizeWeight, getSpan, getViewAtPoint, getWidth, isAfter, isAllocationValid, isBefore, isLayoutValid, layout, layoutChanged, layoutMajorAxis, layoutMinorAxis, modelToView, paint, paintChild, preferenceChanged, replace, setAxis, setSize, viewToModel
Methods inherited from class javax.swing.text.CompositeView
getBottomInset, getInsideAllocation, getLeftInset, getNextEastWestVisualPositionFrom, getNextNorthSouthVisualPositionFrom, getNextVisualPositionFrom, getRightInset, getTopInset, getView, getViewAtPosition, getViewCount, getViewIndex, modelToView, setInsets, setParagraphInsets, setParent
Methods inherited from class javax.swing.text.View
append, breakView, changedUpdate, createFragment, forwardUpdateToView, getAttributes, getBreakWeight, getContainer, getDocument, getElement, getEndOffset, getGraphics, getParent, getStartOffset, getToolTipText, getViewFactory, getViewIndex, insert, isVisible, modelToView, remove, removeAll, updateLayout, viewToModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ZoneView

public ZoneView(Element elem,
                int axis)
Constructs a ZoneView.

Parameters:
elem - the element this view is responsible for
axis - either View.X_AXIS or View.Y_AXIS
Method Detail

getMaximumZoneSize

public int getMaximumZoneSize()
Get the current maximum zone size.

setMaximumZoneSize

public void setMaximumZoneSize(int size)
Set the desired maximum zone size. A zone may get larger than this size if a single child view is larger than this size since zones are formed on child view boundaries.

Parameters:
size - the number of characters the zone may represent before attempting to break the zone into a smaller size.

getMaxZonesLoaded

public int getMaxZonesLoaded()
Get the current setting of the number of zones allowed to be loaded at the same time.

setMaxZonesLoaded

public void setMaxZonesLoaded(int mzl)
Sets the current setting of the number of zones allowed to be loaded at the same time. This will throw an IllegalArgumentException if mzl is less than 1.

Parameters:
mzl - the desired maximum number of zones to be actively loaded, must be greater than 0
Throws:
IllegalArgumentException - if mzl is < 1

zoneWasLoaded

protected void zoneWasLoaded(View zone)
Called by a zone when it gets loaded. This happens when an attempt is made to display or perform a model/view translation on a zone that was in an unloaded state. This is imlemented to check if the maximum number of zones was reached and to unload the oldest zone if so.

Parameters:
zone - the child view that was just loaded.

unloadZone

protected void unloadZone(View zone)
Unload a zone (Convert the zone to its memory saving state). The zones are expected to represent a subset of the child elements of the element this view is responsible for. Therefore, the default implementation is to simple remove all the children.

Parameters:
zone - the child view desired to be set to an unloaded state.

isZoneLoaded

protected boolean isZoneLoaded(View zone)
Determine if a zone is in the loaded state. The zones are expected to represent a subset of the child elements of the element this view is responsible for. Therefore, the default implementation is to return true if the view has children.

createZone

protected View createZone(int p0,
                          int p1)
Create a view to represent a zone for the given range within the model (which should be within the range of this objects responsibility). This is called by the zone management logic to create new zones. Subclasses can provide a different implementation for a zone by changing this method.

Parameters:
p0 - the start of the desired zone. This should be >= getStartOffset() and < getEndOffset(). This value should also be < p1.
p1 - the end of the desired zone. This should be > getStartOffset() and <= getEndOffset().="getEndOffset()." This="This" value="value" should="should" also="also" be="be"> p0.

loadChildren

protected void loadChildren(ViewFactory f)
Loads all of the children to initialize the view. This is called by the setParent method. This is reimplemented to not load any children directly (as they are created by the zones). This method creates the initial set of zones. Zones don't actually get populated however until an attempt is made to display them or to do model/view coordinate translation.

Overrides:
loadChildren in class CompositeView
Parameters:
f - the view factory
See Also:
CompositeView.setParent(javax.swing.text.View)

getViewIndexAtPosition

protected int getViewIndexAtPosition(int pos)
Returns the child view index representing the given position in the model.

Overrides:
getViewIndexAtPosition in class CompositeView
Parameters:
pos - the position >= 0
Returns:
index of the view representing the given position, or -1 if no view represents that position

updateChildren

protected boolean updateChildren(DocumentEvent.ElementChange ec,
                                 DocumentEvent e,
                                 ViewFactory f)
The superclass behavior will try to update the child views which is not desired in this case, since the children are zones and not directly effected by the changes to the associated element. This is reimplemented to do nothing and return false.

Overrides:
updateChildren in class View
Parameters:
ec - the change information for the element this view is responsible for. This should not be null if this method gets called
e - the change information from the associated document
f - the factory to use to build child views
Returns:
whether or not the child views represent the child elements of the element this view is responsible for. Some views create children that represent a portion of the element they are responsible for, and should return false. This information is used to determine if views in the range of the added elements should be forwarded to or not
See Also:
View.insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory),
View.removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory),
View.changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

insertUpdate

public void insertUpdate(DocumentEvent changes,
                         Shape a,
                         ViewFactory f)
Gives notification that something was inserted into the document in a location that this view is responsible for. This is largely delegated to the superclass, but is reimplemented to update the relevant zone (i.e. determine if a zone needs to be split into a set of 2 or more zones).

Overrides:
insertUpdate in class View
Parameters:
changes - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

removeUpdate

public void removeUpdate(DocumentEvent changes,
                         Shape a,
                         ViewFactory f)
Gives notification that something was removed from the document in a location that this view is responsible for. This is largely delegated to the superclass, but is reimplemented to update the relevant zones (i.e. determine if zones need to be removed or joined with another zone).

Overrides:
removeUpdate in class View
Parameters:
changes - the change information from the associated document
a - the current allocation of the view
f - the factory to use to rebuild if the view has children
See Also:
View.removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Timer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class Timer

java.lang.Object
    extended by  javax.swing.Timer
All Implemented Interfaces:
Serializable
public class Timer
extends Object
implements Serializable

Fires one or more ActionEvents at specified intervals. An example use is an animation object that uses a Timer as the trigger for drawing its frames.

Setting up a timer involves creating a Timer object, registering one or more action listeners on it, and starting the timer using the start method. For example, the following code creates and starts a timer that fires an action event once per second (as specified by the first argument to the Timer constructor). The second argument to the Timer constructor specifies a listener to receive the timer's action events.

  int delay = 1000; //milliseconds
  ActionListener taskPerformer = new ActionListener() {
      public void actionPerformed(ActionEvent evt) {
          //...Perform a task...
      }
  };
  new Timer(delay, taskPerformer).start();

Timers are constructed by specifying both a delay parameter and an ActionListener. The delay parameter is used to set both the initial delay and the delay between event firing, in milliseconds. Once the timer has been started, it waits for the initial delay before firing its first ActionEvent to registered listeners. After this first event, it continues to fire events every time the between-event delay has elapsed, until it is stopped.

After construction, the initial delay and the between-event delay can be changed independently, and additional ActionListeners may be added.

If you want the timer to fire only the first time and then stop, invoke setRepeats(false) on the timer.

Although all Timers perform their waiting using a single, shared thread (created by the first Timer object that executes), the action event handlers for Timers execute on another thread -- the event-dispatching thread. This means that the action handlers for Timers can safely perform operations on Swing components. However, it also means that the handlers must execute quickly to keep the GUI responsive.

In v 1.3, another Timer class was added to the Java platform: java.util.Timer. Both it and javax.swing.Timer provide the same basic functionality, but java.util.Timer is more general and has more features. The javax.swing.Timer has two features that can make it a little easier to use with GUIs. First, its event handling metaphor is familiar to GUI programmers and can make dealing with the event-dispatching thread a bit simpler. Second, its automatic thread sharing means that you don't have to take special steps to avoid spawning too many threads. Instead, your timer uses the same thread used to make cursors blink, tool tips appear, and so on.

You can find further documentation and several examples of using timers by visiting How to Use Timers, a section in The Java Tutorial. For more examples and help in choosing between this Timer class and java.util.Timer, see Using Timers in Swing Applications, an article in The Swing Connection.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
java.util.Timer

Field Summary
protected  EventListenerList listenerList
Constructor Summary
Timer(int delay, ActionListener listener)
Creates a Timer and initializes both the initial delay and between-event delay to delay milliseconds.
Method Summary
 void addActionListener(ActionListener listener)
Adds an action listener to the Timer.
protected  void fireActionPerformed(ActionEvent e)
Notifies all listeners that have registered interest for notification on this event type.
 String getActionCommand()
Returns the string that will be delivered as the action command in ActionEvents fired by this timer.
 ActionListener[] getActionListeners()
Returns an array of all the action listeners registered on this timer.
 int getDelay()
Returns the delay, in milliseconds, between firings of action events.
 int getInitialDelay()
Returns the Timer's initial delay.
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this Timer.
static boolean getLogTimers()
Returns true if logging is enabled.
 boolean isCoalesce()
Returns true if the Timer coalesces multiple pending action events.
 boolean isRepeats()
Returns true (the default) if the Timer will send an action event to its listeners multiple times.
 boolean isRunning()
Returns true if the Timer is running.
 void removeActionListener(ActionListener listener)
Removes the specified action listener from the Timer.
 void restart()
Restarts the Timer, canceling any pending firings and causing it to fire with its initial delay.
 void setActionCommand(String command)
Sets the string that will be delivered as the action command in ActionEvents fired by this timer.
 void setCoalesce(boolean flag)
Sets whether the Timer coalesces multiple pending ActionEvent firings.
 void setDelay(int delay)
Sets the Timer's between-event delay, the number of milliseconds between successive action events.
 void setInitialDelay(int initialDelay)
Sets the Timer's initial delay, the time in milliseconds to wait after the timer is started before firing the first event.
static void setLogTimers(boolean flag)
Enables or disables the timer log.
 void setRepeats(boolean flag)
If flag is false, instructs the Timer to send only one action event to its listeners.
 void start()
Starts the Timer, causing it to start sending action events to its listeners.
 void stop()
Stops the Timer, causing it to stop sending action events to its listeners.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

listenerList

protected EventListenerList listenerList
Constructor Detail

Timer

public Timer(int delay,
             ActionListener listener)
Creates a Timer and initializes both the initial delay and between-event delay to delay milliseconds. If delay is less than or equal to zero, the timer fires as soon as it is started. If listener is not null, it's registered as an action listener on the timer.

Parameters:
delay - milliseconds for the initial and between-event delay
listener - an initial listener; can be null
See Also:
addActionListener(java.awt.event.ActionListener), setInitialDelay(int), setRepeats(boolean)
Method Detail

addActionListener

public void addActionListener(ActionListener listener)
Adds an action listener to the Timer.

Parameters:
listener - the listener to add
See Also:
Timer(int, java.awt.event.ActionListener)

removeActionListener

public void removeActionListener(ActionListener listener)
Removes the specified action listener from the Timer.

Parameters:
listener - the listener to remove

getActionListeners

public ActionListener[] getActionListeners()
Returns an array of all the action listeners registered on this timer.

Returns:
all of the timer's ActionListeners or an empty array if no action listeners are currently registered
Since:
1.4
See Also:
addActionListener(java.awt.event.ActionListener), removeActionListener(java.awt.event.ActionListener)

fireActionPerformed

protected void fireActionPerformed(ActionEvent e)
Notifies all listeners that have registered interest for notification on this event type.

Parameters:
e - the action event to fire
See Also:
EventListenerList

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this Timer. FooListeners are registered using the addFooListener method.

You can specify the listenerType argument with a class literal, such as FooListener.class. For example, you can query a Timer instance t for its action listeners with the following code:

ActionListener[] als = (ActionListener[])(t.getListeners(ActionListener.class));
If no such listeners exist, this method returns an empty array.

Parameters:
listenerType - the type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener
Returns:
an array of all objects registered as FooListeners on this timer, or an empty array if no such listeners have been added
Throws:
ClassCastException - if listenerType doesn't specify a class or interface that implements java.util.EventListener
Since:
1.3
See Also:
getActionListeners(),
addActionListener(java.awt.event.ActionListener),
removeActionListener(java.awt.event.ActionListener)

setLogTimers

public static void setLogTimers(boolean flag)
Enables or disables the timer log. When enabled, a message is posted to System.out whenever the timer goes off.

Parameters:
flag - true to enable logging
See Also:
getLogTimers()

getLogTimers

public static boolean getLogTimers()
Returns true if logging is enabled.

Returns:
true if logging is enabled; otherwise, false
See Also:
setLogTimers(boolean)

setDelay

public void setDelay(int delay)
Sets the Timer's between-event delay, the number of milliseconds between successive action events. This does not affect the initial delay property, which can be set by the setInitialDelay method.

Parameters:
delay - the delay in milliseconds
See Also:
setInitialDelay(int)

getDelay

public int getDelay()
Returns the delay, in milliseconds, between firings of action events.

See Also:
setDelay(int), getInitialDelay()

setInitialDelay

public void setInitialDelay(int initialDelay)
Sets the Timer's initial delay, the time in milliseconds to wait after the timer is started before firing the first event. Upon construction, this is set to be the same as the between-event delay, but then its value is independent and remains unaffected by changes to the between-event delay.

Parameters:
initialDelay - the initial delay, in milliseconds
See Also:
setDelay(int)

getInitialDelay

public int getInitialDelay()
Returns the Timer's initial delay.

See Also:
setInitialDelay(int), setDelay(int)

setRepeats

public void setRepeats(boolean flag)
If flag is false, instructs the Timer to send only one action event to its listeners.

Parameters:
flag - specify false to make the timer stop after sending its first action event

isRepeats

public boolean isRepeats()
Returns true (the default) if the Timer will send an action event to its listeners multiple times.

See Also:
setRepeats(boolean)

setCoalesce

public void setCoalesce(boolean flag)
Sets whether the Timer coalesces multiple pending ActionEvent firings. A busy application may not be able to keep up with a Timer's event generation, causing multiple action events to be queued. When processed, the application sends these events one after the other, causing the Timer's listeners to receive a sequence of events with no delay between them. Coalescing avoids this situation by reducing multiple pending events to a single event. Timers coalesce events by default.

Parameters:
flag - specify false to turn off coalescing

isCoalesce

public boolean isCoalesce()
Returns true if the Timer coalesces multiple pending action events.

See Also:
setCoalesce(boolean)

setActionCommand

public void setActionCommand(String command)
Sets the string that will be delivered as the action command in ActionEvents fired by this timer. null is an acceptable value.

Parameters:
command - the action command
Since:
1.6

getActionCommand

public String getActionCommand()
Returns the string that will be delivered as the action command in ActionEvents fired by this timer. May be null, which is also the default.

Returns:
the action command used in firing events
Since:
1.6

start

public void start()
Starts the Timer, causing it to start sending action events to its listeners.

See Also:
stop()

isRunning

public boolean isRunning()
Returns true if the Timer is running.

See Also:
start()

stop

public void stop()
Stops the Timer, causing it to stop sending action events to its listeners.

See Also:
start()

restart

public void restart()
Restarts the Timer, canceling any pending firings and causing it to fire with its initial delay.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ToolTipManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class ToolTipManager

java.lang.Object
    extended by  java.awt.event.MouseAdapter
        extended by  javax.swing.ToolTipManager
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, EventListener
public class ToolTipManager
extends MouseAdapter
implements MouseMotionListener

Manages all the ToolTips in the system.

ToolTipManager contains numerous properties for configuring how long it will take for the tooltips to become visible, and how long till they hide. Consider a component that has a different tooltip based on where the mouse is, such as JTree. When the mouse moves into the JTree and over a region that has a valid tooltip, the tooltip will become visibile after initialDelay milliseconds. After dismissDelay milliseconds the tooltip will be hidden. If the mouse is over a region that has a valid tooltip, and the tooltip is currently visible, when the mouse moves to a region that doesn't have a valid tooltip the tooltip will be hidden. If the mouse then moves back into a region that has a valid tooltip within reshowDelay milliseconds, the tooltip will immediately be shown, otherwise the tooltip will be shown again after initialDelay milliseconds.

See Also:
JComponent.createToolTip()

Nested Class Summary
protected class | ToolTipManager.insideTimerAction
protected class | ToolTipManager.outsideTimerAction
protected class | ToolTipManager.stillInsideTimerAction
Field Summary
protected boolean | heavyWeightPopupEnabled
protected boolean | lightWeightPopupEnabled
Method Summary
int | getDismissDelay() Returns the dismissal delay value.
int | getInitialDelay() Returns the initial delay value.
int | getReshowDelay() Returns the reshow delay property.
boolean | isEnabled() Returns true if this object is enabled.
boolean | isLightWeightPopupEnabled() Returns true if lightweight (all-Java) Tooltips are in use, or false if heavyweight (native peer) Tooltips are being used.
void | mouseDragged(MouseEvent event) Called when the mouse is pressed and dragged.
void | mouseEntered(MouseEvent event) Called when the mouse enters the region of a component.
void | mouseExited(MouseEvent event) Called when the mouse exits the region of a component.
void | mouseMoved(MouseEvent event) Called when the mouse is moved.
void | mousePressed(MouseEvent event) Called when the mouse is pressed.
void | registerComponent(JComponent component) Registers a component for tooltip management.
void | setDismissDelay(int milliseconds) Specifies the dismissal delay value.
void | setEnabled(boolean flag) Enables or disables the tooltip.
void | setInitialDelay(int milliseconds) Specifies the initial delay value.
void | setLightWeightPopupEnabled(boolean aFlag) When displaying the JToolTip, the ToolTipManager chooses to use a lightweight JPanel if it fits.
void | setReshowDelay(int milliseconds) Used to specify the amount of time before the user has to wait initialDelay milliseconds before a tooltip will be shown.
static ToolTipManager | sharedInstance() Returns a shared ToolTipManager instance.
void | unregisterComponent(JComponent component) Removes a component from tooltip control.
Methods inherited from class java.awt.event.MouseAdapter
mouseClicked, mouseReleased, mouseWheelMoved
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

lightWeightPopupEnabled

protected boolean lightWeightPopupEnabled

heavyWeightPopupEnabled

protected boolean heavyWeightPopupEnabled
Method Detail

setEnabled

public void setEnabled(boolean flag)
Enables or disables the tooltip.

Parameters:
flag - true to enable the tip, false otherwise

isEnabled

public boolean isEnabled()
Returns true if this object is enabled.

Returns:
true if this object is enabled, false otherwise

setLightWeightPopupEnabled

public void setLightWeightPopupEnabled(boolean aFlag)
When displaying the JToolTip, the ToolTipManager chooses to use a lightweight JPanel if it fits. This method allows you to disable this feature. You have to do disable it if your application mixes light weight and heavy weights components.

Parameters:
aFlag - true if a lightweight panel is desired, false otherwise

isLightWeightPopupEnabled

public boolean isLightWeightPopupEnabled()
Returns true if lightweight (all-Java) Tooltips are in use, or false if heavyweight (native peer) Tooltips are being used.

Returns:
true if lightweight ToolTips are in use

setInitialDelay

public void setInitialDelay(int milliseconds)
Specifies the initial delay value.

Parameters:
milliseconds - the number of milliseconds to delay (after the cursor has paused) before displaying the tooltip
See Also:
getInitialDelay()

getInitialDelay

public int getInitialDelay()
Returns the initial delay value.

Returns:
an integer representing the initial delay value, in milliseconds
See Also:
setInitialDelay(int)

setDismissDelay

public void setDismissDelay(int milliseconds)
Specifies the dismissal delay value.

Parameters:
milliseconds - the number of milliseconds to delay before taking away the tooltip
See Also:
getDismissDelay()

getDismissDelay

public int getDismissDelay()
Returns the dismissal delay value.

Returns:
an integer representing the dismissal delay value, in milliseconds
See Also:
setDismissDelay(int)

setReshowDelay

public void setReshowDelay(int milliseconds)
Used to specify the amount of time before the user has to wait initialDelay milliseconds before a tooltip will be shown. That is, if the tooltip is hidden, and the user moves into a region of the same Component that has a valid tooltip within milliseconds milliseconds the tooltip will immediately be shown. Otherwise, if the user moves into a region with a valid tooltip after milliseconds milliseconds, the user will have to wait an additional initialDelay milliseconds before the tooltip is shown again.

Parameters:
milliseconds - time in milliseconds
See Also:
getReshowDelay()

getReshowDelay

public int getReshowDelay()
Returns the reshow delay property.

Returns:
reshown delay property
See Also:
setReshowDelay(int)

sharedInstance

public static ToolTipManager sharedInstance()
Returns a shared ToolTipManager instance.

Returns:
a shared ToolTipManager object

registerComponent

public void registerComponent(JComponent component)
Registers a component for tooltip management.

This will register key bindings to show and hide the tooltip text only if component has focus bindings. This is done so that components that are not normally focus traversable, such as JLabel, are not made focus traversable as a result of invoking this method.

Parameters:
component - a JComponent object to add
See Also:
Component.isFocusTraversable()

unregisterComponent

public void unregisterComponent(JComponent component)
Removes a component from tooltip control.

Parameters:
component - a JComponent object to remove

mouseEntered

public void mouseEntered(MouseEvent event)
Called when the mouse enters the region of a component. This determines whether the tool tip should be shown.

Specified by:
mouseEntered in interface MouseListener
Overrides:
mouseEntered in class MouseAdapter
Parameters:
event - the event in question

mouseExited

public void mouseExited(MouseEvent event)
Called when the mouse exits the region of a component. Any tool tip showing should be hidden.

Specified by:
mouseExited in interface MouseListener
Overrides:
mouseExited in class MouseAdapter
Parameters:
event - the event in question

mousePressed

public void mousePressed(MouseEvent event)
Called when the mouse is pressed. Any tool tip showing should be hidden.

Specified by:
mousePressed in interface MouseListener
Overrides:
mousePressed in class MouseAdapter
Parameters:
event - the event in question

mouseDragged

public void mouseDragged(MouseEvent event)
Called when the mouse is pressed and dragged. Does nothing.

Specified by:
mouseDragged in interface MouseMotionListener
Overrides:
mouseDragged in class MouseAdapter
Parameters:
event - the event in question

mouseMoved

public void mouseMoved(MouseEvent event)
Called when the mouse is moved. Determines whether the tool tip should be displayed.

Specified by:
mouseMoved in interface MouseMotionListener
Overrides:
mouseMoved in class MouseAdapter
Parameters:
event - the event in question
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ToolTipManager.insideTimerAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class ToolTipManager.insideTimerAction

java.lang.Object
    extended by  javax.swing.ToolTipManager.insideTimerAction
All Implemented Interfaces:
ActionListener, EventListener
Enclosing class:
ToolTipManager
protected class ToolTipManager.insideTimerAction
extends Object
implements ActionListener

Constructor Summary
protected ToolTipManager.insideTimerAction()
Method Summary
 void actionPerformed(ActionEvent e)
Invoked when an action occurs.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ToolTipManager.insideTimerAction

protected ToolTipManager.insideTimerAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

Specified by:
actionPerformed in interface ActionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ToolTipManager.outsideTimerAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class ToolTipManager.outsideTimerAction

java.lang.Object
    extended by  javax.swing.ToolTipManager.outsideTimerAction
All Implemented Interfaces:
ActionListener, EventListener
Enclosing class:
ToolTipManager
protected class ToolTipManager.outsideTimerAction
extends Object
implements ActionListener

Constructor Summary
protected ToolTipManager.outsideTimerAction()
Method Summary
 void actionPerformed(ActionEvent e)
Invoked when an action occurs.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ToolTipManager.outsideTimerAction

protected ToolTipManager.outsideTimerAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

Specified by:
actionPerformed in interface ActionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ToolTipManager.stillInsideTimerAction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class ToolTipManager.stillInsideTimerAction

java.lang.Object
    extended by  javax.swing.ToolTipManager.stillInsideTimerAction
All Implemented Interfaces:
ActionListener, EventListener
Enclosing class:
ToolTipManager
protected class ToolTipManager.stillInsideTimerAction
extends Object
implements ActionListener

Constructor Summary
protected ToolTipManager.stillInsideTimerAction()
Method Summary
 void actionPerformed(ActionEvent e)
Invoked when an action occurs.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ToolTipManager.stillInsideTimerAction

protected ToolTipManager.stillInsideTimerAction()
Method Detail

actionPerformed

public void actionPerformed(ActionEvent e)
Description copied from interface: ActionListener
Invoked when an action occurs.

Specified by:
actionPerformed in interface ActionListener
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TransferHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class TransferHandler

java.lang.Object
    extended by  javax.swing.TransferHandler
All Implemented Interfaces:
Serializable
public class TransferHandler
extends Object
implements Serializable

This class is used to handle the transfer of a Transferable to and from Swing components. The Transferable is used to represent data that is exchanged via a cut, copy, or paste to/from a clipboard. It is also used in drag-and-drop operations to represent a drag from a component, and a drop to a component. Swing provides functionality that automatically supports cut, copy, and paste keyboard bindings that use the functionality provided by an implementation of this class. Swing also provides functionality that automatically supports drag and drop that uses the functionality provided by an implementation of this class. The Swing developer can concentrate on specifying the semantics of a transfer primarily by setting the transferHandler property on a Swing component.

This class is implemented to provide a default behavior of transferring a component property simply by specifying the name of the property in the constructor. For example, to transfer the foreground color from one component to another either via the clipboard or a drag and drop operation a TransferHandler can be constructed with the string "foreground". The built in support will use the color returned by getForeground as the source of the transfer, and setForeground for the target of a transfer.

Please see How to Use Drag and Drop and Data Transfer, a section in The Java Tutorial, for more information.

Since:
1.4

Nested Class Summary
static class | TransferHandler.DropLocation Represents a location where dropped data should be inserted.
static class | TransferHandler.TransferSupport This class encapsulates all relevant details of a clipboard or drag and drop transfer, and also allows for customizing aspects of the drag and drop experience.
Field Summary
static int | COPY An int representing a "copy" transfer action.
static int | COPY_OR_MOVE An int representing a source action capability of either "copy" or "move".
static int | LINK An int representing a "link" transfer action.
static int | MOVE An int representing a "move" transfer action.
static int | NONE An int representing no transfer action.
Constructor Summary
protected | TransferHandler() Convenience constructor for subclasses.
 | TransferHandler(String property) Constructs a transfer handler that can transfer a Java Bean property from one component to another via the clipboard or a drag and drop operation.
Method Summary
boolean | canImport(JComponent comp, DataFlavor[] transferFlavors) Indicates whether a component will accept an import of the given set of data flavors prior to actually attempting to import it.
boolean | canImport(TransferHandler.TransferSupport support) This method is called repeatedly during a drag and drop operation to allow the developer to configure properties of, and to return the acceptability of transfers; with a return value of true indicating that the transfer represented by the given TransferSupport (which contains all of the details of the transfer) is acceptable at the current time, and a value of false rejecting the transfer.
protected Transferable | createTransferable(JComponent c) Creates a Transferable to use as the source for a data transfer.
void | exportAsDrag(JComponent comp, InputEvent e, int action) Causes the Swing drag support to be initiated.
protected void | exportDone(JComponent source, Transferable data, int action) Invoked after data has been exported.
void | exportToClipboard(JComponent comp, Clipboard clip, int action) Causes a transfer from the given component to the given clipboard.
static Action | getCopyAction() Returns an Action that performs copy operations to the clipboard.
static Action | getCutAction() Returns an Action that performs cut operations to the clipboard.
static Action | getPasteAction() Returns an Action that performs paste operations from the clipboard.
int | getSourceActions(JComponent c) Returns the type of transfer actions supported by the source; any bitwise-OR combination of COPY, MOVE and LINK.
Icon | getVisualRepresentation(Transferable t) Returns an object that establishes the look of a transfer.
boolean | importData(JComponent comp, Transferable t) Causes a transfer to a component from a clipboard or a DND drop operation.
boolean | importData(TransferHandler.TransferSupport support) Causes a transfer to occur from a clipboard or a drag and drop operation.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NONE

public static final int NONE
An int representing no transfer action.

See Also:
Constant Field Values

COPY

public static final int COPY
An int representing a "copy" transfer action. This value is used when data is copied to a clipboard or copied elsewhere in a drag and drop operation.

See Also:
Constant Field Values

MOVE

public static final int MOVE
An int representing a "move" transfer action. This value is used when data is moved to a clipboard (i.e. a cut) or moved elsewhere in a drag and drop operation.

See Also:
Constant Field Values

COPY_OR_MOVE

public static final int COPY_OR_MOVE
An int representing a source action capability of either "copy" or "move".

See Also:
Constant Field Values

LINK

public static final int LINK
An int representing a "link" transfer action. This value is used to specify that data should be linked in a drag and drop operation.

Since:
1.6
See Also:
DnDConstants.ACTION_LINK, Constant Field Values
Constructor Detail

TransferHandler

public TransferHandler(String property)
Constructs a transfer handler that can transfer a Java Bean property from one component to another via the clipboard or a drag and drop operation.

Parameters:
property - the name of the property to transfer; this can be null if there is no property associated with the transfer handler (a subclass that performs some other kind of transfer, for example)

TransferHandler

protected TransferHandler()
Convenience constructor for subclasses.

Method Detail

getCutAction

public static Action getCutAction()
Returns an Action that performs cut operations to the clipboard. When performed, this action operates on the JComponent source of the ActionEvent by invoking exportToClipboard, with a MOVE action, on the component's TransferHandler.

Returns:
an Action for performing cuts to the clipboard

getCopyAction

public static Action getCopyAction()
Returns an Action that performs copy operations to the clipboard. When performed, this action operates on the JComponent source of the ActionEvent by invoking exportToClipboard, with a COPY action, on the component's TransferHandler.

Returns:
an Action for performing copies to the clipboard

getPasteAction

public static Action getPasteAction()
Returns an Action that performs paste operations from the clipboard. When performed, this action operates on the JComponent source of the ActionEvent by invoking importData, with the clipboard contents, on the component's TransferHandler.

Returns:
an Action for performing pastes from the clipboard

exportAsDrag

public void exportAsDrag(JComponent comp,
                         InputEvent e,
                         int action)
Causes the Swing drag support to be initiated. This is called by the various UI implementations in the javax.swing.plaf.basic package if the dragEnabled property is set on the component. This can be called by custom UI implementations to use the Swing drag support. This method can also be called by a Swing extension written as a subclass of JComponent to take advantage of the Swing drag support.

The transfer will not necessarily have been completed at the return of this call (i.e. the call does not block waiting for the drop). The transfer will take place through the Swing implementation of the java.awt.dnd mechanism, requiring no further effort from the developer. The exportDone method will be called when the transfer has completed.

Parameters:
comp - the component holding the data to be transferred; provided to enable sharing of TransferHandlers
e - the event that triggered the transfer
action - the transfer action initially requested; either COPY, MOVE or LINK; the DnD system may change the action used during the course of the drag operation

exportToClipboard

public void exportToClipboard(JComponent comp,
                              Clipboard clip,
                              int action)
                       throws IllegalStateException
Causes a transfer from the given component to the given clipboard. This method is called by the default cut and copy actions registered in a component's action map.

The transfer will take place using the java.awt.datatransfer mechanism, requiring no further effort from the developer. Any data transfer will be complete and the exportDone method will be called with the action that occurred, before this method returns. Should the clipboard be unavailable when attempting to place data on it, the IllegalStateException thrown by Clipboard.setContents(Transferable, ClipboardOwner) will be propogated through this method. However, exportDone will first be called with an action of NONE for consistency.

Parameters:
comp - the component holding the data to be transferred; provided to enable sharing of TransferHandlers
clip - the clipboard to transfer the data into
action - the transfer action requested; this should be a value of either COPY or MOVE; the operation performed is the intersection of the transfer capabilities given by getSourceActions and the requested action; the intersection may result in an action of NONE if the requested action isn't supported
Throws:
IllegalStateException - if the clipboard is currently unavailable
See Also:
Clipboard.setContents(Transferable, ClipboardOwner)

importData

public boolean importData(TransferHandler.TransferSupport support)
Causes a transfer to occur from a clipboard or a drag and drop operation. The Transferable to be imported and the component to transfer to are contained within the TransferSupport.

While the drag and drop implementation calls canImport to determine the suitability of a transfer before calling this method, the implementation of paste does not. As such, it cannot be assumed that the transfer is acceptable upon a call to this method for paste. It is recommended that canImport be explicitly called to cover this case.

Note: The TransferSupport object passed to this method is only valid for the duration of the method call. It is undefined what values it may contain after this method returns.

Parameters:
support - the object containing the details of the transfer, not null.
Returns:
true if the data was inserted into the component, false otherwise
Throws:
NullPointerException - if support is null
Since:
1.6
See Also:
canImport(TransferHandler.TransferSupport)

importData

public boolean importData(JComponent comp,
                          Transferable t)
Causes a transfer to a component from a clipboard or a DND drop operation. The Transferable represents the data to be imported into the component.

Note: Swing now calls the newer version of importData that takes a TransferSupport, which in turn calls this method (if the component in the TransferSupport is a JComponent). Developers are encouraged to call and override the newer version as it provides more information (and is the only version that supports use with a TransferHandler set directly on a JFrame or other non-JComponent).

Parameters:
comp - the component to receive the transfer; provided to enable sharing of TransferHandlers
t - the data to import
Returns:
true if the data was inserted into the component, false otherwise
See Also:
importData(TransferHandler.TransferSupport)

canImport

public boolean canImport(TransferHandler.TransferSupport support)
This method is called repeatedly during a drag and drop operation to allow the developer to configure properties of, and to return the acceptability of transfers; with a return value of true indicating that the transfer represented by the given TransferSupport (which contains all of the details of the transfer) is acceptable at the current time, and a value of false rejecting the transfer.

For those components that automatically display a drop location during drag and drop, accepting the transfer, by default, tells them to show the drop location. This can be changed by calling setShowDropLocation on the TransferSupport.

By default, when the transfer is accepted, the chosen drop action is that picked by the user via their drag gesture. The developer can override this and choose a different action, from the supported source actions, by calling setDropAction on the TransferSupport.

On every call to canImport, the TransferSupport contains fresh state. As such, any properties set on it must be set on every call. Upon a drop, canImport is called one final time before calling into importData. Any state set on the TransferSupport during that last call will be available in importData.

This method is not called internally in response to paste operations. As such, it is recommended that implementations of importData explicitly call this method for such cases and that this method be prepared to return the suitability of paste operations as well.

Note: The TransferSupport object passed to this method is only valid for the duration of the method call. It is undefined what values it may contain after this method returns.

Parameters:
support - the object containing the details of the transfer, not null.
Returns:
true if the import can happen, false otherwise
Throws:
NullPointerException - if support is null
Since:
1.6
See Also:
importData(TransferHandler.TransferSupport),
TransferHandler.TransferSupport.setShowDropLocation(boolean),
TransferHandler.TransferSupport.setDropAction(int)

canImport

public boolean canImport(JComponent comp,
                         DataFlavor[] transferFlavors)
Indicates whether a component will accept an import of the given set of data flavors prior to actually attempting to import it.

Note: Swing now calls the newer version of canImport that takes a TransferSupport, which in turn calls this method (only if the component in the TransferSupport is a JComponent). Developers are encouraged to call and override the newer version as it provides more information (and is the only version that supports use with a TransferHandler set directly on a JFrame or other non-JComponent).

Parameters:
comp - the component to receive the transfer; provided to enable sharing of TransferHandlers
transferFlavors - the data formats available
Returns:
true if the data can be inserted into the component, false otherwise
See Also:
canImport(TransferHandler.TransferSupport)

getSourceActions

public int getSourceActions(JComponent c)
Returns the type of transfer actions supported by the source; any bitwise-OR combination of COPY, MOVE and LINK.

Some models are not mutable, so a transfer operation of MOVE should not be advertised in that case. Returning NONE disables transfers from the component.

Parameters:
c - the component holding the data to be transferred; provided to enable sharing of TransferHandlers
Returns:
COPY if the transfer property can be found, otherwise returns NONE

getVisualRepresentation

public Icon getVisualRepresentation(Transferable t)
Returns an object that establishes the look of a transfer. This is useful for both providing feedback while performing a drag operation and for representing the transfer in a clipboard implementation that has a visual appearance. The implementation of the Icon interface should not alter the graphics clip or alpha level. The icon implementation need not be rectangular or paint all of the bounding rectangle and logic that calls the icons paint method should not assume the all bits are painted. null is a valid return value for this method and indicates there is no visual representation provided. In that case, the calling logic is free to represent the transferable however it wants.

The default Swing logic will not do an alpha blended drag animation if the return is null.

Parameters:
t - the data to be transferred; this value is expected to have been created by the createTransferable method
Returns:
null, indicating there is no default visual representation

createTransferable

protected Transferable createTransferable(JComponent c)
Creates a Transferable to use as the source for a data transfer. Returns the representation of the data to be transferred, or null if the component's property is null

Parameters:
c - the component holding the data to be transferred; provided to enable sharing of TransferHandlers
Returns:
the representation of the data to be transferred, or null if the property associated with c is null

exportDone

protected void exportDone(JComponent source,
                          Transferable data,
                          int action)
Invoked after data has been exported. This method should remove the data that was transferred if the action was MOVE.

This method is implemented to do nothing since MOVE is not a supported action of this implementation (getSourceActions does not include MOVE).

Parameters:
source - the component that was the source of the data
data - The data that was transferred or possibly null if the action is NONE.
action - the actual action that was performed
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TransferHandler.DropLocation

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class TransferHandler.DropLocation

java.lang.Object
    extended by  javax.swing.TransferHandler.DropLocation
Direct Known Subclasses:
JList.DropLocation, JTable.DropLocation, JTextComponent.DropLocation, JTree.DropLocation
Enclosing class:
TransferHandler
public static class TransferHandler.DropLocation
extends Object

Represents a location where dropped data should be inserted. This is a base class that only encapsulates a point. Components supporting drop may provide subclasses of this containing more information.

Developers typically shouldn't create instances of, or extend, this class. Instead, these are something provided by the DnD implementation by TransferSupport instances and by components with a getDropLocation() method.

Since:
1.6
See Also:
TransferHandler.TransferSupport.getDropLocation()

Constructor Summary
protected TransferHandler.DropLocation(Point dropPoint)
Constructs a drop location for the given point.
Method Summary
Point | getDropPoint() Returns the drop point, representing the mouse's current location within the component.
String | toString() Returns a string representation of this drop location.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TransferHandler.DropLocation

protected TransferHandler.DropLocation(Point dropPoint)
Constructs a drop location for the given point.

Parameters:
dropPoint - the drop point, representing the mouse's current location within the component.
Throws:
IllegalArgumentException - if the point is null
Method Detail

getDropPoint

public final Point getDropPoint()
Returns the drop point, representing the mouse's current location within the component.

Returns:
the drop point.

toString

public String toString()
Returns a string representation of this drop location. This method is intended to be used for debugging purposes, and the content and format of the returned string may vary between implementations.

Overrides:
toString in class Object
Returns:
a string representation of this drop location
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TransferHandler.TransferSupport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class TransferHandler.TransferSupport

java.lang.Object
    extended by  javax.swing.TransferHandler.TransferSupport
Enclosing class:
TransferHandler
public static final class TransferHandler.TransferSupport
extends Object

This class encapsulates all relevant details of a clipboard or drag and drop transfer, and also allows for customizing aspects of the drag and drop experience.

The main purpose of this class is to provide the information needed by a developer to determine the suitability of a transfer or to import the data contained within. But it also doubles as a controller for customizing properties during drag and drop, such as whether or not to show the drop location, and which drop action to use.

Developers typically need not create instances of this class. Instead, they are something provided by the DnD implementation to certain methods in TransferHandler.

Since:
1.6
See Also:
TransferHandler.canImport(TransferHandler.TransferSupport), TransferHandler.importData(TransferHandler.TransferSupport)

Constructor Summary
TransferHandler.TransferSupport(Component component, Transferable transferable)
Create a TransferSupport with isDrop() false for the given component and Transferable.
Method Summary
Component | getComponent() Returns the target component of this transfer.
DataFlavor[] | getDataFlavors() Returns the data flavors for this transfer.
int | getDropAction() Returns the action chosen for the drop, when this TransferSupport represents a drop.
TransferHandler.DropLocation | getDropLocation() Returns the current (non-null) drop location for the component, when this TransferSupport represents a drop.
int | getSourceDropActions() Returns the drag source's supported drop actions, when this TransferSupport represents a drop.
Transferable | getTransferable() Returns the Transferable associated with this transfer.
int | getUserDropAction() Returns the user drop action for the drop, when this TransferSupport represents a drop.
boolean | isDataFlavorSupported(DataFlavor df) Returns whether or not the given data flavor is supported.
boolean | isDrop() Returns whether or not this TransferSupport represents a drop operation.
void | setDropAction(int dropAction) Sets the drop action for the transfer - which must represent a drop - to the given action, instead of the default user drop action.
void | setShowDropLocation(boolean showDropLocation) Sets whether or not the drop location should be visually indicated for the transfer - which must represent a drop.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TransferHandler.TransferSupport

public TransferHandler.TransferSupport(Component component,
                                       Transferable transferable)
Create a TransferSupport with isDrop() false for the given component and Transferable.

Parameters:
component - the target component
transferable - the transferable
Throws:
NullPointerException - if either parameter is null
Method Detail

isDrop

public boolean isDrop()
Returns whether or not this TransferSupport represents a drop operation.

Returns:
true if this is a drop operation, false otherwise.

getComponent

public Component getComponent()
Returns the target component of this transfer.

Returns:
the target component

getDropLocation

public TransferHandler.DropLocation getDropLocation()
Returns the current (non-null) drop location for the component, when this TransferSupport represents a drop.

Note: For components with built-in drop support, this location will be a subclass of DropLocation of the same type returned by that component's getDropLocation method.

This method is only for use with drag and drop transfers. Calling it when isDrop() is false results in an IllegalStateException.

Returns:
the drop location
Throws:
IllegalStateException - if this is not a drop
See Also:
isDrop

setShowDropLocation

public void setShowDropLocation(boolean showDropLocation)
Sets whether or not the drop location should be visually indicated for the transfer - which must represent a drop. This is applicable to those components that automatically show the drop location when appropriate during a drag and drop operation). By default, the drop location is shown only when the TransferHandler has said it can accept the import represented by this TransferSupport. With this method you can force the drop location to always be shown, or always not be shown.

This method is only for use with drag and drop transfers. Calling it when isDrop() is false results in an IllegalStateException.

Parameters:
showDropLocation - whether or not to indicate the drop location
Throws:
IllegalStateException - if this is not a drop
See Also:
isDrop

setDropAction

public void setDropAction(int dropAction)
Sets the drop action for the transfer - which must represent a drop - to the given action, instead of the default user drop action. The action must be supported by the source's drop actions, and must be one of COPY, MOVE or LINK.

This method is only for use with drag and drop transfers. Calling it when isDrop() is false results in an IllegalStateException.

Parameters:
dropAction - the drop action
Throws:
IllegalStateException - if this is not a drop
IllegalArgumentException - if an invalid action is specified
See Also:
getDropAction(),
getUserDropAction(),
getSourceDropActions(),
isDrop

getDropAction

public int getDropAction()
Returns the action chosen for the drop, when this TransferSupport represents a drop.

Unless explicitly chosen by way of setDropAction, this returns the user drop action provided by getUserDropAction.

You may wish to query this in TransferHandler's importData method to customize processing based on the action.

This method is only for use with drag and drop transfers. Calling it when isDrop() is false results in an IllegalStateException.

Returns:
the action chosen for the drop
Throws:
IllegalStateException - if this is not a drop
See Also:
setDropAction(int), getUserDropAction(), isDrop

getUserDropAction

public int getUserDropAction()
Returns the user drop action for the drop, when this TransferSupport represents a drop.

The user drop action is chosen for a drop as described in the documentation for DropTargetDragEvent and DropTargetDropEvent. A different action may be chosen as the drop action by way of the setDropAction method.

You may wish to query this in TransferHandler's canImport method when determining the suitability of a drop or when deciding on a drop action to explicitly choose.

This method is only for use with drag and drop transfers. Calling it when isDrop() is false results in an IllegalStateException.

Returns:
the user drop action
Throws:
IllegalStateException - if this is not a drop
See Also:
setDropAction(int), getDropAction(), isDrop

getSourceDropActions

public int getSourceDropActions()
Returns the drag source's supported drop actions, when this TransferSupport represents a drop.

The source actions represent the set of actions supported by the source of this transfer, and are represented as some bitwise-OR combination of COPY, MOVE and LINK. You may wish to query this in TransferHandler's canImport method when determining the suitability of a drop or when deciding on a drop action to explicitly choose. To determine if a particular action is supported by the source, bitwise-AND the action with the source drop actions, and then compare the result against the original action. For example:

 boolean copySupported = (COPY & getSourceDropActions()) == COPY;

This method is only for use with drag and drop transfers. Calling it when isDrop() is false results in an IllegalStateException.

Returns:
the drag source's supported drop actions
Throws:
IllegalStateException - if this is not a drop
See Also:
isDrop

getDataFlavors

public DataFlavor[] getDataFlavors()
Returns the data flavors for this transfer.

Returns:
the data flavors for this transfer

isDataFlavorSupported

public boolean isDataFlavorSupported(DataFlavor df)
Returns whether or not the given data flavor is supported.

Parameters:
df - the DataFlavor to test
Returns:
whether or not the given flavor is supported.

getTransferable

public Transferable getTransferable()
Returns the Transferable associated with this transfer.

Note: Unless it is necessary to fetch the Transferable directly, use one of the other methods on this class to inquire about the transfer. This may perform better than fetching the Transferable and asking it directly.

Returns:
the Transferable associated with this transfer
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


tree

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.swing.tree

Provides classes and interfaces for dealing with javax.swing.JTree.

See:
Description

Interface Summary
MutableTreeNode | Defines the requirements for a tree node object that can change -- by adding or removing child nodes, or by changing the contents of a user object stored in the node.
RowMapper | Defines the requirements for an object that translates paths in the tree into display rows.
TreeCellEditor | Adds to CellEditor the extensions necessary to configure an editor in a tree.
TreeCellRenderer | Defines the requirements for an object that displays a tree node.
TreeModel | The model used by JTree.
TreeNode | Defines the requirements for an object that can be used as a tree node in a JTree.
TreeSelectionModel | This interface represents the current state of the selection for the tree component.

Class Summary
AbstractLayoutCache | Warning: Serialized objects of this class will not be compatible with future Swing releases.
AbstractLayoutCache.NodeDimensions | Used by AbstractLayoutCache to determine the size and x origin of a particular node.
DefaultMutableTreeNode | A DefaultMutableTreeNode is a general-purpose node in a tree data structure.
DefaultTreeCellEditor | A TreeCellEditor.
DefaultTreeCellRenderer | Displays an entry in a tree.
DefaultTreeModel | A simple tree data model that uses TreeNodes.
DefaultTreeSelectionModel | Default implementation of TreeSelectionModel.
FixedHeightLayoutCache | NOTE: This will become more open in a future release.
TreePath | Represents a path to a node.
VariableHeightLayoutCache | NOTE: This will become more open in a future release.

Exception Summary
ExpandVetoException Exception used to stop and expand/collapse from happening.

Package javax.swing.tree Description

Provides classes and interfaces for dealing with javax.swing.JTree. You use these classes and interfaces if you want control over how trees are constructed, updated, and rendered, as well as how data associated with the tree nodes are viewed and managed.

Note: Most of the Swing API is not thread safe. For details, see Threads and Swing, a section in The Java Tutorial.

Related Documentation

For overviews, tutorials, examples, guides, and tool documentation, please see:
  • How to Use Trees, a section in The Java Tutorial

Since:
1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.swing.tree Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.swing.tree

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.swing.tree.AbstractLayoutCache (implements javax.swing.tree.RowMapper)
      • javax.swing.tree.FixedHeightLayoutCache
      • javax.swing.tree.VariableHeightLayoutCache
    • javax.swing.tree.AbstractLayoutCache.NodeDimensions
    • java.awt.Component (implements java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable)
      • java.awt.Container
        • javax.swing.tree.DefaultTreeCellEditor.EditorContainer
        • javax.swing.JComponent (implements java.io.Serializable)
          • javax.swing.JLabel (implements javax.accessibility.Accessible, javax.swing.SwingConstants)
            • javax.swing.tree.DefaultTreeCellRenderer (implements javax.swing.tree.TreeCellRenderer)
          • javax.swing.text.JTextComponent (implements javax.accessibility.Accessible, javax.swing.Scrollable)
            • javax.swing.JTextField (implements javax.swing.SwingConstants)
              • javax.swing.tree.DefaultTreeCellEditor.DefaultTextField
    • javax.swing.tree.DefaultMutableTreeNode (implements java.lang.Cloneable, javax.swing.tree.MutableTreeNode, java.io.Serializable)
    • javax.swing.tree.DefaultTreeCellEditor (implements java.awt.event.ActionListener, javax.swing.tree.TreeCellEditor, javax.swing.event.TreeSelectionListener)
    • javax.swing.tree.DefaultTreeModel (implements java.io.Serializable, javax.swing.tree.TreeModel)
    • javax.swing.tree.DefaultTreeSelectionModel (implements java.lang.Cloneable, java.io.Serializable, javax.swing.tree.TreeSelectionModel)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.swing.tree.ExpandVetoException
    • javax.swing.tree.TreePath (implements java.io.Serializable)

Interface Hierarchy

  • javax.swing.CellEditor
    • javax.swing.tree.TreeCellEditor
  • javax.swing.tree.RowMapper
  • javax.swing.tree.TreeCellRenderer
  • javax.swing.tree.TreeModel
  • javax.swing.tree.TreeNode
    • javax.swing.tree.MutableTreeNode
  • javax.swing.tree.TreeSelectionModel
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.swing.tree

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.swing.tree

Packages that use javax.swing.tree
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Classes in javax.swing.tree used by javax.swing
DefaultMutableTreeNode
A DefaultMutableTreeNode is a general-purpose node in a tree data structure.
DefaultTreeSelectionModel
Default implementation of TreeSelectionModel.
ExpandVetoException
Exception used to stop and expand/collapse from happening.
MutableTreeNode
Defines the requirements for a tree node object that can change -- by adding or removing child nodes, or by changing the contents of a user object stored in the node.
TreeCellEditor
Adds to CellEditor the extensions necessary to configure an editor in a tree.
TreeCellRenderer
Defines the requirements for an object that displays a tree node.
TreeModel
The model used by JTree.
TreeNode
Defines the requirements for an object that can be used as a tree node in a JTree.
TreePath
Represents a path to a node.
TreeSelectionModel
This interface represents the current state of the selection for the tree component.

Classes in javax.swing.tree used by javax.swing.event
ExpandVetoException
Exception used to stop and expand/collapse from happening.
TreePath
Represents a path to a node.

Classes in javax.swing.tree used by javax.swing.plaf
TreePath
Represents a path to a node.

Classes in javax.swing.tree used by javax.swing.plaf.basic
AbstractLayoutCache
Warning: Serialized objects of this class will not be compatible with future Swing releases.
AbstractLayoutCache.NodeDimensions
Used by AbstractLayoutCache to determine the size and x origin of a particular node.
TreeCellEditor
Adds to CellEditor the extensions necessary to configure an editor in a tree.
TreeCellRenderer
Defines the requirements for an object that displays a tree node.
TreeModel
The model used by JTree.
TreePath
Represents a path to a node.
TreeSelectionModel
This interface represents the current state of the selection for the tree component.

Classes in javax.swing.tree used by javax.swing.plaf.metal
TreePath
Represents a path to a node.

Classes in javax.swing.tree used by javax.swing.plaf.multi
TreePath
Represents a path to a node.

Classes in javax.swing.tree used by javax.swing.text
TreeNode
Defines the requirements for an object that can be used as a tree node in a JTree.

Classes in javax.swing.tree used by javax.swing.text.html
TreeNode
Defines the requirements for an object that can be used as a tree node in a JTree.

Classes in javax.swing.tree used by javax.swing.tree
AbstractLayoutCache
Warning: Serialized objects of this class will not be compatible with future Swing releases.
AbstractLayoutCache.NodeDimensions
Used by AbstractLayoutCache to determine the size and x origin of a particular node.
DefaultMutableTreeNode
A DefaultMutableTreeNode is a general-purpose node in a tree data structure.
DefaultTreeCellRenderer
Displays an entry in a tree.
MutableTreeNode
Defines the requirements for a tree node object that can change -- by adding or removing child nodes, or by changing the contents of a user object stored in the node.
RowMapper
Defines the requirements for an object that translates paths in the tree into display rows.
TreeCellEditor
Adds to CellEditor the extensions necessary to configure an editor in a tree.
TreeCellRenderer
Defines the requirements for an object that displays a tree node.
TreeModel
The model used by JTree.
TreeNode
Defines the requirements for an object that can be used as a tree node in a JTree.
TreePath
Represents a path to a node.
TreeSelectionModel
This interface represents the current state of the selection for the tree component.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AbstractLayoutCache

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Class AbstractLayoutCache

java.lang.Object
    extended by  javax.swing.tree.AbstractLayoutCache
All Implemented Interfaces:
RowMapper
Direct Known Subclasses:
FixedHeightLayoutCache, VariableHeightLayoutCache
public abstract class AbstractLayoutCache
extends Object
implements RowMapper

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
static class AbstractLayoutCache.NodeDimensions
Used by AbstractLayoutCache to determine the size and x origin of a particular node.
Field Summary
protected AbstractLayoutCache.NodeDimensions | nodeDimensions Object responsible for getting the size of a node.
protected boolean | rootVisible True if the root node is displayed, false if its children are the highest visible nodes.
protected int | rowHeight Height to use for each row.
protected TreeModel | treeModel Model providing information.
protected TreeSelectionModel | treeSelectionModel Selection model.
Constructor Summary
AbstractLayoutCache()
Method Summary
abstract Rectangle | getBounds(TreePath path, Rectangle placeIn) Returns a rectangle giving the bounds needed to draw path.
abstract boolean | getExpandedState(TreePath path) Returns true if the path is expanded, and visible.
TreeModel | getModel() Returns the TreeModel that is providing the data.
AbstractLayoutCache.NodeDimensions | getNodeDimensions() Returns the object that renders nodes in the tree, and which is responsible for calculating the dimensions of individual nodes.
protected Rectangle | getNodeDimensions(Object value, int row, int depth, boolean expanded, Rectangle placeIn) Returns, by reference in placeIn, the size needed to represent value.
abstract TreePath | getPathClosestTo(int x, int y) Returns the path to the node that is closest to x,y.
abstract TreePath | getPathForRow(int row) Returns the path for passed in row.
int | getPreferredHeight() Returns the preferred height.
int | getPreferredWidth(Rectangle bounds) Returns the preferred width for the passed in region.
abstract int | getRowCount() Number of rows being displayed.
abstract int | getRowForPath(TreePath path) Returns the row that the last item identified in path is visible at.
int | getRowHeight() Returns the height of each row.
int[] | getRowsForPaths(TreePath[] paths) Returns the rows that the TreePath instances in path are being displayed at.
TreeSelectionModel | getSelectionModel() Returns the model used to maintain the selection.
abstract int | getVisibleChildCount(TreePath path) Returns the number of visible children for row.
abstract Enumeration<TreePath> | getVisiblePathsFrom(TreePath path) Returns an Enumerator that increments over the visible paths starting at the passed in location.
abstract void | invalidatePathBounds(TreePath path) Instructs the LayoutCache that the bounds for path are invalid, and need to be updated.
abstract void | invalidateSizes() Informs the TreeState that it needs to recalculate all the sizes it is referencing.
abstract boolean | isExpanded(TreePath path) Returns true if the value identified by row is currently expanded.
protected boolean | isFixedRowHeight() Returns true if the height of each row is a fixed size.
boolean | isRootVisible() Returns true if the root node of the tree is displayed.
abstract void | setExpandedState(TreePath path, boolean isExpanded) Marks the path path expanded state to isExpanded.
void | setModel(TreeModel newModel) Sets the TreeModel that will provide the data.
void | setNodeDimensions(AbstractLayoutCache.NodeDimensions nd) Sets the renderer that is responsible for drawing nodes in the tree and which is threfore responsible for calculating the dimensions of individual nodes.
void | setRootVisible(boolean rootVisible) Determines whether or not the root node from the TreeModel is visible.
void | setRowHeight(int rowHeight) Sets the height of each cell.
void | setSelectionModel(TreeSelectionModel newLSM) Sets the TreeSelectionModel used to manage the selection to new LSM.
abstract void | treeNodesChanged(TreeModelEvent e) Invoked after a node (or a set of siblings) has changed in some way.
abstract void | treeNodesInserted(TreeModelEvent e) Invoked after nodes have been inserted into the tree.
abstract void | treeNodesRemoved(TreeModelEvent e) Invoked after nodes have been removed from the tree.
abstract void | treeStructureChanged(TreeModelEvent e) Invoked after the tree has drastically changed structure from a given node down.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

nodeDimensions

protected AbstractLayoutCache.NodeDimensions nodeDimensions
Object responsible for getting the size of a node.

treeModel

protected TreeModel treeModel
Model providing information.

treeSelectionModel

protected TreeSelectionModel treeSelectionModel
Selection model.

rootVisible

protected boolean rootVisible
True if the root node is displayed, false if its children are the highest visible nodes.

rowHeight

protected int rowHeight
Height to use for each row. If this is <= 0="0" the="the" renderer="renderer" will="will" be="be" used="used" to="to" determine="determine" the="the" height="height" for="for" each="each" row.="row."
Constructor Detail

AbstractLayoutCache

public AbstractLayoutCache()
Method Detail

setNodeDimensions

public void setNodeDimensions(AbstractLayoutCache.NodeDimensions nd)
Sets the renderer that is responsible for drawing nodes in the tree and which is threfore responsible for calculating the dimensions of individual nodes.

Parameters:
nd - a NodeDimensions object

getNodeDimensions

public AbstractLayoutCache.NodeDimensions getNodeDimensions()
Returns the object that renders nodes in the tree, and which is responsible for calculating the dimensions of individual nodes.

Returns:
the NodeDimensions object

setModel

public void setModel(TreeModel newModel)
Sets the TreeModel that will provide the data.

Parameters:
newModel - the TreeModel that is to provide the data

getModel

public TreeModel getModel()
Returns the TreeModel that is providing the data.

Returns:
the TreeModel that is providing the data

setRootVisible

public void setRootVisible(boolean rootVisible)
Determines whether or not the root node from the TreeModel is visible.

Parameters:
rootVisible - true if the root node of the tree is to be displayed
See Also:
rootVisible

isRootVisible

public boolean isRootVisible()
Returns true if the root node of the tree is displayed.

Returns:
true if the root node of the tree is displayed
See Also:
rootVisible

setRowHeight

public void setRowHeight(int rowHeight)
Sets the height of each cell. If the specified value is less than or equal to zero the current cell renderer is queried for each row's height.

Parameters:
rowHeight - the height of each cell, in pixels

getRowHeight

public int getRowHeight()
Returns the height of each row. If the returned value is less than or equal to 0 the height for each row is determined by the renderer.

setSelectionModel

public void setSelectionModel(TreeSelectionModel newLSM)
Sets the TreeSelectionModel used to manage the selection to new LSM.

Parameters:
newLSM - the new TreeSelectionModel

getSelectionModel

public TreeSelectionModel getSelectionModel()
Returns the model used to maintain the selection.

Returns:
the treeSelectionModel

getPreferredHeight

public int getPreferredHeight()
Returns the preferred height.

Returns:
the preferred height

getPreferredWidth

public int getPreferredWidth(Rectangle bounds)
Returns the preferred width for the passed in region. The region is defined by the path closest to (bounds.x, bounds.y) and ends at bounds.height + bounds.y. If bounds is null, the preferred width for all the nodes will be returned (and this may be a VERY expensive computation).

Parameters:
bounds - the region being queried
Returns:
the preferred width for the passed in region

isExpanded

public abstract boolean isExpanded(TreePath path)
Returns true if the value identified by row is currently expanded.

getBounds

public abstract Rectangle getBounds(TreePath path,
                                    Rectangle placeIn)
Returns a rectangle giving the bounds needed to draw path.

Parameters:
path - a TreePath specifying a node
placeIn - a Rectangle object giving the available space
Returns:
a Rectangle object specifying the space to be used

getPathForRow

public abstract TreePath getPathForRow(int row)
Returns the path for passed in row. If row is not visible null is returned.

Parameters:
row - the row being queried
Returns:
the TreePath for the given row

getRowForPath

public abstract int getRowForPath(TreePath path)
Returns the row that the last item identified in path is visible at. Will return -1 if any of the elements in path are not currently visible.

Parameters:
path - the TreePath being queried
Returns:
the row where the last item in path is visible or -1 if any elements in path aren't currently visible

getPathClosestTo

public abstract TreePath getPathClosestTo(int x,
                                          int y)
Returns the path to the node that is closest to x,y. If there is nothing currently visible this will return null, otherwise it'll always return a valid path. If you need to test if the returned object is exactly at x, y you should get the bounds for the returned path and test x, y against that.

Parameters:
x - the horizontal component of the desired location
y - the vertical component of the desired location
Returns:
the TreePath closest to the specified point

getVisiblePathsFrom

public abstract Enumeration<TreePath> getVisiblePathsFrom(TreePath path)
Returns an Enumerator that increments over the visible paths starting at the passed in location. The ordering of the enumeration is based on how the paths are displayed. The first element of the returned enumeration will be path, unless it isn't visible, in which case null will be returned.

Parameters:
path - the starting location for the enumeration
Returns:
the Enumerator starting at the desired location

getVisibleChildCount

public abstract int getVisibleChildCount(TreePath path)
Returns the number of visible children for row.

Parameters:
path - the path being queried
Returns:
the number of visible children for the specified path

setExpandedState

public abstract void setExpandedState(TreePath path,
                                      boolean isExpanded)
Marks the path path expanded state to isExpanded.

Parameters:
path - the path being expanded or collapsed
isExpanded - true if the path should be expanded, false otherwise

getExpandedState

public abstract boolean getExpandedState(TreePath path)
Returns true if the path is expanded, and visible.

Parameters:
path - the path being queried
Returns:
true if the path is expanded and visible, false otherwise

getRowCount

public abstract int getRowCount()
Number of rows being displayed.

Returns:
the number of rows being displayed

invalidateSizes

public abstract void invalidateSizes()
Informs the TreeState that it needs to recalculate all the sizes it is referencing.

invalidatePathBounds

public abstract void invalidatePathBounds(TreePath path)
Instructs the LayoutCache that the bounds for path are invalid, and need to be updated.

Parameters:
path - the path being updated

treeNodesChanged

public abstract void treeNodesChanged(TreeModelEvent e)

Invoked after a node (or a set of siblings) has changed in some way. The node(s) have not changed locations in the tree or altered their children arrays, but other attributes have changed and may affect presentation. Example: the name of a file has changed, but it is in the same location in the file system.

e.path() returns the path the parent of the changed node(s).

e.childIndices() returns the index(es) of the changed node(s).

Parameters:
e - the TreeModelEvent

treeNodesInserted

public abstract void treeNodesInserted(TreeModelEvent e)

Invoked after nodes have been inserted into the tree.

e.path() returns the parent of the new nodes

e.childIndices() returns the indices of the new nodes in ascending order.

Parameters:
e - the TreeModelEvent

treeNodesRemoved

public abstract void treeNodesRemoved(TreeModelEvent e)

Invoked after nodes have been removed from the tree. Note that if a subtree is removed from the tree, this method may only be invoked once for the root of the removed subtree, not once for each individual set of siblings removed.

e.path() returns the former parent of the deleted nodes.

e.childIndices() returns the indices the nodes had before they were deleted in ascending order.

Parameters:
e - the TreeModelEvent

treeStructureChanged

public abstract void treeStructureChanged(TreeModelEvent e)

Invoked after the tree has drastically changed structure from a given node down. If the path returned by e.getPath() is of length one and the first element does not identify the current root node the first element should become the new root of the tree.

e.path() holds the path to the node.

e.childIndices() returns null.

Parameters:
e - the TreeModelEvent

getRowsForPaths

public int[] getRowsForPaths(TreePath[] paths)
Returns the rows that the TreePath instances in path are being displayed at. This method should return an array of the same length as that passed in, and if one of the TreePaths in path is not valid its entry in the array should be set to -1.

Specified by:
getRowsForPaths in interface RowMapper
Parameters:
paths - the array of TreePaths being queried
Returns:
an array of the same length that is passed in containing the rows that each corresponding where each TreePath is displayed; if paths is null, null is returned

getNodeDimensions

protected Rectangle getNodeDimensions(Object value,
                                      int row,
                                      int depth,
                                      boolean expanded,
                                      Rectangle placeIn)
Returns, by reference in placeIn, the size needed to represent value. If inPlace is null, a newly created Rectangle should be returned, otherwise the value should be placed in inPlace and returned. This will return null if there is no renderer.

Parameters:
value - the value to be represented
row - row being queried
depth - the depth of the row
expanded - true if row is expanded, false otherwise
placeIn - a Rectangle containing the size needed to represent value
Returns:
a Rectangle containing the node dimensions, or null if node has no dimension

isFixedRowHeight

protected boolean isFixedRowHeight()
Returns true if the height of each row is a fixed size.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AbstractLayoutCache.NodeDimensions

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Class AbstractLayoutCache.NodeDimensions

java.lang.Object
    extended by  javax.swing.tree.AbstractLayoutCache.NodeDimensions
Direct Known Subclasses:
BasicTreeUI.NodeDimensionsHandler
Enclosing class:
AbstractLayoutCache
public abstract static class AbstractLayoutCache.NodeDimensions
extends Object

Used by AbstractLayoutCache to determine the size and x origin of a particular node.

Constructor Summary
AbstractLayoutCache.NodeDimensions()
Method Summary
abstract  Rectangle getNodeDimensions(Object value, int row, int depth, boolean expanded, Rectangle bounds)
Returns, by reference in bounds, the size and x origin to place value at.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractLayoutCache.NodeDimensions

public AbstractLayoutCache.NodeDimensions()
Method Detail

getNodeDimensions

public abstract Rectangle getNodeDimensions(Object value,
                                            int row,
                                            int depth,
                                            boolean expanded,
                                            Rectangle bounds)
Returns, by reference in bounds, the size and x origin to place value at. The calling method is responsible for determining the Y location. If bounds is null, a newly created Rectangle should be returned, otherwise the value should be placed in bounds and returned.

Parameters:
value - the value to be represented
row - row being queried
depth - the depth of the row
expanded - true if row is expanded, false otherwise
bounds - a Rectangle containing the size needed to represent value
Returns:
a Rectangle containing the node dimensions, or null if node has no dimension
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.swing.tree.AbstractLayoutCache

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.tree.AbstractLayoutCache

Packages that use AbstractLayoutCache
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of AbstractLayoutCache in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as AbstractLayoutCache
protected  AbstractLayoutCache BasicTreeUI.treeState
Object responsible for handling sizing and expanded issues.

Methods in javax.swing.plaf.basic that return AbstractLayoutCache
protected  AbstractLayoutCache BasicTreeUI.createLayoutCache()
Creates the object responsible for managing what is expanded, as well as the size of nodes.

Uses of AbstractLayoutCache in javax.swing.tree

Subclasses of AbstractLayoutCache in javax.swing.tree
class | FixedHeightLayoutCache NOTE: This will become more open in a future release.
class | VariableHeightLayoutCache NOTE: This will become more open in a future release.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.tree.AbstractLayoutCache.NodeDimensions

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.tree.AbstractLayoutCache.NodeDimensions

Packages that use AbstractLayoutCache.NodeDimensions
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of AbstractLayoutCache.NodeDimensions in javax.swing.plaf.basic

Subclasses of AbstractLayoutCache.NodeDimensions in javax.swing.plaf.basic
 class BasicTreeUI.NodeDimensionsHandler
Class responsible for getting size of node, method is forwarded to BasicTreeUI method.

Fields in javax.swing.plaf.basic declared as AbstractLayoutCache.NodeDimensions
protected  AbstractLayoutCache.NodeDimensions BasicTreeUI.nodeDimensions
Reponsible for telling the TreeState the size needed for a node.

Methods in javax.swing.plaf.basic that return AbstractLayoutCache.NodeDimensions
protected  AbstractLayoutCache.NodeDimensions BasicTreeUI.createNodeDimensions()
Creates an instance of NodeDimensions that is able to determine the size of a given node in the tree.

Uses of AbstractLayoutCache.NodeDimensions in javax.swing.tree

Fields in javax.swing.tree declared as AbstractLayoutCache.NodeDimensions
protected  AbstractLayoutCache.NodeDimensions AbstractLayoutCache.nodeDimensions
Object responsible for getting the size of a node.

Methods in javax.swing.tree that return AbstractLayoutCache.NodeDimensions
 AbstractLayoutCache.NodeDimensions AbstractLayoutCache.getNodeDimensions()
Returns the object that renders nodes in the tree, and which is responsible for calculating the dimensions of individual nodes.

Methods in javax.swing.tree with parameters of type AbstractLayoutCache.NodeDimensions
void | VariableHeightLayoutCache.setNodeDimensions(AbstractLayoutCache.NodeDimensions nd) Sets the renderer that is responsible for drawing nodes in the tree.
void | AbstractLayoutCache.setNodeDimensions(AbstractLayoutCache.NodeDimensions nd) Sets the renderer that is responsible for drawing nodes in the tree and which is threfore responsible for calculating the dimensions of individual nodes.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.tree.DefaultMutableTreeNode

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.tree.DefaultMutableTreeNode

Packages that use DefaultMutableTreeNode
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of DefaultMutableTreeNode in javax.swing

Subclasses of DefaultMutableTreeNode in javax.swing
static class JTree.DynamicUtilTreeNode
DynamicUtilTreeNode can wrap vectors/hashtables/arrays/strings and create the appropriate children tree nodes as necessary.

Methods in javax.swing with parameters of type DefaultMutableTreeNode
static void JTree.DynamicUtilTreeNode.createChildren(DefaultMutableTreeNode parent, Object children)
Adds to parent all the children in children.

Uses of DefaultMutableTreeNode in javax.swing.tree

Methods in javax.swing.tree that return DefaultMutableTreeNode
DefaultMutableTreeNode | DefaultMutableTreeNode.getFirstLeaf() Finds and returns the first leaf that is a descendant of this node -- either this node or its first child's first leaf.
DefaultMutableTreeNode | DefaultMutableTreeNode.getLastLeaf() Finds and returns the last leaf that is a descendant of this node -- either this node or its last child's last leaf.
DefaultMutableTreeNode | DefaultMutableTreeNode.getNextLeaf() Returns the leaf after this node or null if this node is the last leaf in the tree.
DefaultMutableTreeNode | DefaultMutableTreeNode.getNextNode() Returns the node that follows this node in a preorder traversal of this node's tree.
DefaultMutableTreeNode | DefaultMutableTreeNode.getNextSibling() Returns the next sibling of this node in the parent's children array.
DefaultMutableTreeNode | DefaultMutableTreeNode.getPreviousLeaf() Returns the leaf before this node or null if this node is the first leaf in the tree.
DefaultMutableTreeNode | DefaultMutableTreeNode.getPreviousNode() Returns the node that precedes this node in a preorder traversal of this node's tree.
DefaultMutableTreeNode | DefaultMutableTreeNode.getPreviousSibling() Returns the previous sibling of this node in the parent's children array.

Methods in javax.swing.tree with parameters of type DefaultMutableTreeNode
TreeNode | DefaultMutableTreeNode.getSharedAncestor(DefaultMutableTreeNode aNode) Returns the nearest common ancestor to this node and aNode.
boolean | DefaultMutableTreeNode.isNodeDescendant(DefaultMutableTreeNode anotherNode) Returns true if anotherNode is a descendant of this node -- if it is this node, one of this node's children, or a descendant of one of this node's children.
boolean | DefaultMutableTreeNode.isNodeRelated(DefaultMutableTreeNode aNode) Returns true if and only if aNode is in the same tree as this node.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.tree.DefaultTreeCellEditor

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.tree.DefaultTreeCellEditor

No usage of javax.swing.tree.DefaultTreeCellEditor

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.tree.DefaultTreeCellEditor.DefaultTextField

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.tree.DefaultTreeCellEditor.DefaultTextField

No usage of javax.swing.tree.DefaultTreeCellEditor.DefaultTextField

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.tree.DefaultTreeCellEditor.EditorContainer

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.tree.DefaultTreeCellEditor.EditorContainer

No usage of javax.swing.tree.DefaultTreeCellEditor.EditorContainer

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.tree.DefaultTreeCellRenderer

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.tree.DefaultTreeCellRenderer

Packages that use DefaultTreeCellRenderer
javax.swing.tree Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of DefaultTreeCellRenderer in javax.swing.tree

Fields in javax.swing.tree declared as DefaultTreeCellRenderer
protected  DefaultTreeCellRenderer DefaultTreeCellEditor.renderer
Renderer, used to get border and offsets from.

Constructors in javax.swing.tree with parameters of type DefaultTreeCellRenderer
DefaultTreeCellEditor(JTree tree, DefaultTreeCellRenderer renderer)
Constructs a DefaultTreeCellEditor object for a JTree using the specified renderer and a default editor.
DefaultTreeCellEditor(JTree tree, DefaultTreeCellRenderer renderer, TreeCellEditor editor)
Constructs a DefaultTreeCellEditor object for a JTree using the specified renderer and the specified editor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.tree.DefaultTreeModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.tree.DefaultTreeModel

No usage of javax.swing.tree.DefaultTreeModel

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.tree.DefaultTreeSelectionModel

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.tree.DefaultTreeSelectionModel

Packages that use DefaultTreeSelectionModel
javax.swing Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.

Uses of DefaultTreeSelectionModel in javax.swing

Subclasses of DefaultTreeSelectionModel in javax.swing
protected static class JTree.EmptySelectionModel
EmptySelectionModel is a TreeSelectionModel that does not allow anything to be selected.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.tree.ExpandVetoException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.tree.ExpandVetoException

Packages that use ExpandVetoException
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.

Uses of ExpandVetoException in javax.swing

Methods in javax.swing that throw ExpandVetoException
void | JTree.fireTreeWillCollapse(TreePath path) Notifies all listeners that have registered interest for notification on this event type.
void | JTree.fireTreeWillExpand(TreePath path) Notifies all listeners that have registered interest for notification on this event type.

Uses of ExpandVetoException in javax.swing.event

Methods in javax.swing.event that throw ExpandVetoException
void | TreeWillExpandListener.treeWillCollapse(TreeExpansionEvent event) Invoked whenever a node in the tree is about to be collapsed.
void | TreeWillExpandListener.treeWillExpand(TreeExpansionEvent event) Invoked whenever a node in the tree is about to be expanded.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.tree.FixedHeightLayoutCache

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.tree.FixedHeightLayoutCache

No usage of javax.swing.tree.FixedHeightLayoutCache

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.tree.TreePath

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.tree.TreePath

Packages that use TreePath
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.event | Provides for events fired by Swing components.
javax.swing.plaf | Provides one interface and many abstract classes that Swing uses to provide its pluggable look-and-feel capabilities.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.plaf.metal | Provides user interface objects built according to the Java look and feel (once codenamed Metal), which is the default look and feel.
javax.swing.plaf.multi | Provides user interface objects that combine two or more look and feels.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of TreePath in javax.swing

Methods in javax.swing that return TreePath
TreePath | JTree.getAnchorSelectionPath() Returns the path identified as the anchor.
TreePath | JTree.getClosestPathForLocation(int x, int y) Returns the path to the node that is closest to x,y.
TreePath | JTree.getEditingPath() Returns the path to the element that is currently being edited.
TreePath | JTree.getLeadSelectionPath() Returns the path identified as the lead.
TreePath | JTree.getNextMatch(String prefix, int startingRow, Position.Bias bias) Returns the TreePath to the next tree element that begins with a prefix.
TreePath | JTree.DropLocation.getPath() Returns the path where dropped data should be placed in the tree.
protected TreePath[] | JTree.getPathBetweenRows(int index0, int index1) Returns JTreePath instances representing the path between index0 and index1 (including index1).
TreePath | JTree.getPathForLocation(int x, int y) Returns the path for the node at the specified location.
TreePath | JTree.getPathForRow(int row) Returns the path for the specified row.
TreePath | JTree.getSelectionPath() Returns the path to the first selected node.
TreePath[] | JTree.getSelectionPaths() Returns the paths of all selected values.

Methods in javax.swing that return types with arguments of type TreePath
protected Enumeration<TreePath> | JTree.getDescendantToggledPaths(TreePath parent) Returns an Enumeration of TreePaths that have been expanded that are descendants of parent.
Enumeration<TreePath> | JTree.getExpandedDescendants(TreePath parent) Returns an Enumeration of the descendants of the path parent that are currently expanded.

Methods in javax.swing with parameters of type TreePath
void | JTree.addSelectionPath(TreePath path) Adds the node identified by the specified TreePath to the current selection.
void | JTree.addSelectionPaths(TreePath[] paths) Adds each path in the array of paths to the current selection.
void | JTree.EmptySelectionModel.addSelectionPaths(TreePath[] paths) A null implementation that adds nothing.
void | JTree.collapsePath(TreePath path) Ensures that the node identified by the specified path is collapsed and viewable.
void | JTree.expandPath(TreePath path) Ensures that the node identified by the specified path is expanded and viewable.
void | JTree.fireTreeCollapsed(TreePath path) Notifies all listeners that have registered interest for notification on this event type.
void | JTree.fireTreeExpanded(TreePath path) Notifies all listeners that have registered interest for notification on this event type.
void | JTree.fireTreeWillCollapse(TreePath path) Notifies all listeners that have registered interest for notification on this event type.
void | JTree.fireTreeWillExpand(TreePath path) Notifies all listeners that have registered interest for notification on this event type.
protected Enumeration<TreePath> | JTree.getDescendantToggledPaths(TreePath parent) Returns an Enumeration of TreePaths that have been expanded that are descendants of parent.
Enumeration<TreePath> | JTree.getExpandedDescendants(TreePath parent) Returns an Enumeration of the descendants of the path parent that are currently expanded.
Rectangle | JTree.getPathBounds(TreePath path) Returns the Rectangle that the specified node will be drawn into.
int | JTree.getRowForPath(TreePath path) Returns the row that displays the node identified by the specified path.
boolean | JTree.hasBeenExpanded(TreePath path) Returns true if the node identified by the path has ever been expanded.
boolean | JTree.isCollapsed(TreePath path) Returns true if the value identified by path is currently collapsed, this will return false if any of the values in path are currently not being displayed.
boolean | JTree.isExpanded(TreePath path) Returns true if the node identified by the path is currently expanded,
boolean | JTree.isPathEditable(TreePath path) Returns isEditable.
boolean | JTree.isPathSelected(TreePath path) Returns true if the item identified by the path is currently selected.
boolean | JTree.isVisible(TreePath path) Returns true if the value identified by path is currently viewable, which means it is either the root or all of its parents are expanded.
void | JTree.makeVisible(TreePath path) Ensures that the node identified by path is currently viewable.
protected boolean | JTree.removeDescendantSelectedPaths(TreePath path, boolean includePath) Removes any paths in the selection that are descendants of path.
void | JTree.removeSelectionPath(TreePath path) Removes the node identified by the specified path from the current selection.
void | JTree.removeSelectionPaths(TreePath[] paths) Removes the nodes identified by the specified paths from the current selection.
void | JTree.EmptySelectionModel.removeSelectionPaths(TreePath[] paths) A null implementation that removes nothing.
void | JTree.scrollPathToVisible(TreePath path) Makes sure all the path components in path are expanded (except for the last path component) and scrolls so that the node identified by the path is displayed.
void | JTree.setAnchorSelectionPath(TreePath newPath) Sets the path identified as the anchor.
protected void | JTree.setExpandedState(TreePath path, boolean state) Sets the expanded state of this JTree.
void | JTree.setLeadSelectionPath(TreePath newPath) Sets the path identifies as the lead.
void | JTree.setSelectionPath(TreePath path) Selects the node identified by the specified path.
void | JTree.setSelectionPaths(TreePath[] paths) Selects the nodes identified by the specified array of paths.
void | JTree.EmptySelectionModel.setSelectionPaths(TreePath[] pPaths) A null implementation that selects nothing.
void | JTree.startEditingAtPath(TreePath path) Selects the node identified by the specified path and initiates editing.

Method parameters in javax.swing with type arguments of type TreePath
protected  void JTree.removeDescendantToggledPaths(Enumeration<TreePath> toRemove)
Removes any descendants of the TreePaths in toRemove that have been expanded.

Constructors in javax.swing with parameters of type TreePath
JTree.AccessibleJTree.AccessibleJTreeNode(JTree t, TreePath p, Accessible ap)
Constructs an AccessibleJTreeNode

Uses of TreePath in javax.swing.event

Fields in javax.swing.event declared as TreePath
protected TreePath | TreeSelectionEvent.newLeadSelectionPath leadSelectionPath after the paths changed, may be null.
protected TreePath | TreeSelectionEvent.oldLeadSelectionPath leadSelectionPath before the paths changed, may be null.
protected TreePath | TreeExpansionEvent.path Path to the value this event represents.
protected TreePath | TreeModelEvent.path Path to the parent of the nodes that have changed.
protected TreePath[] | TreeSelectionEvent.paths Paths this event represents.

Methods in javax.swing.event that return TreePath
TreePath | TreeSelectionEvent.getNewLeadSelectionPath() Returns the current lead path.
TreePath | TreeSelectionEvent.getOldLeadSelectionPath() Returns the path that was previously the lead path.
TreePath | TreeExpansionEvent.getPath() Returns the path to the value that has been expanded/collapsed.
TreePath | TreeSelectionEvent.getPath() Returns the first path element.
TreePath[] | TreeSelectionEvent.getPaths() Returns the paths that have been added or removed from the selection.
TreePath | TreeModelEvent.getTreePath() For all events, except treeStructureChanged, returns the parent of the changed nodes.

Methods in javax.swing.event with parameters of type TreePath
 boolean TreeSelectionEvent.isAddedPath(TreePath path)
Returns true if the path identified by path was added to the selection.

Constructors in javax.swing.event with parameters of type TreePath
TreeExpansionEvent(Object source, TreePath path)
Constructs a TreeExpansionEvent object.
TreeModelEvent(Object source, TreePath path)
Used to create an event when the node structure has changed in some way, identifying the path to the root of the modified subtree as a TreePath object.
TreeModelEvent(Object source, TreePath path, int[] childIndices, Object[] children)
Used to create an event when nodes have been changed, inserted, or removed, identifying the path to the parent of the modified items as a TreePath object.
TreeSelectionEvent(Object source, TreePath[] paths, boolean[] areNew, TreePath oldLeadSelectionPath, TreePath newLeadSelectionPath)
Represents a change in the selection of a TreeSelectionModel.
TreeSelectionEvent(Object source, TreePath[] paths, boolean[] areNew, TreePath oldLeadSelectionPath, TreePath newLeadSelectionPath)
Represents a change in the selection of a TreeSelectionModel.
TreeSelectionEvent(Object source, TreePath path, boolean isNew, TreePath oldLeadSelectionPath, TreePath newLeadSelectionPath)
Represents a change in the selection of a TreeSelectionModel.

Uses of TreePath in javax.swing.plaf

Methods in javax.swing.plaf that return TreePath
abstract TreePath | TreeUI.getClosestPathForLocation(JTree tree, int x, int y) Returns the path to the node that is closest to x,y.
abstract TreePath | TreeUI.getEditingPath(JTree tree) Returns the path to the element that is being edited.
abstract TreePath | TreeUI.getPathForRow(JTree tree, int row) Returns the path for passed in row.

Methods in javax.swing.plaf with parameters of type TreePath
abstract Rectangle | TreeUI.getPathBounds(JTree tree, TreePath path) Returns the Rectangle enclosing the label portion that the last item in path will be drawn into.
abstract int | TreeUI.getRowForPath(JTree tree, TreePath path) Returns the row that the last item identified in path is visible at.
abstract void | TreeUI.startEditingAtPath(JTree tree, TreePath path) Selects the last item in path and tries to edit it.

Uses of TreePath in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as TreePath
protected  TreePath BasicTreeUI.editingPath
Path that is being edited.

Fields in javax.swing.plaf.basic with type parameters of type TreePath
protected  Hashtable<TreePath,Boolean> BasicTreeUI.drawingCache
Used for minimizing the drawing of vertical lines.

Methods in javax.swing.plaf.basic that return TreePath
TreePath | BasicTreeUI.getClosestPathForLocation(JTree tree, int x, int y) Returns the path to the node that is closest to x,y.
TreePath | BasicTreeUI.getEditingPath(JTree tree) Returns the path to the element that is being edited.
protected TreePath | BasicTreeUI.getLastChildPath(TreePath parent) Returns a path to the last child of parent.
TreePath | BasicTreeUI.getPathForRow(JTree tree, int row) Returns the path for passed in row.

Methods in javax.swing.plaf.basic with parameters of type TreePath
protected void | BasicTreeUI.checkForClickInExpandControl(TreePath path, int mouseX, int mouseY) If the mouseX and mouseY are in the expand/collapse region of the row, this will toggle the row.
protected TreePath | BasicTreeUI.getLastChildPath(TreePath parent) Returns a path to the last child of parent.
Rectangle | BasicTreeUI.getPathBounds(JTree tree, TreePath path) Returns the Rectangle enclosing the label portion that the last item in path will be drawn into.
int | BasicTreeUI.getRowForPath(JTree tree, TreePath path) Returns the row that the last item identified in path is visible at.
protected void | BasicTreeUI.handleExpandControlClick(TreePath path, int mouseX, int mouseY) Messaged when the user clicks the particular row, this invokes toggleExpandState.
protected boolean | BasicTreeUI.isLocationInExpandControl(TreePath path, int mouseX, int mouseY) Returns true if mouseX and mouseY fall in the area of row that is used to expand/collapse the node and the node at row does not represent a leaf.
protected void | BasicTreeUI.paintExpandControl(Graphics g, Rectangle clipBounds, Insets insets, Rectangle bounds, TreePath path, int row, boolean isExpanded, boolean hasBeenExpanded, boolean isLeaf) Paints the expand (toggle) part of a row.
protected void | BasicTreeUI.paintHorizontalPartOfLeg(Graphics g, Rectangle clipBounds, Insets insets, Rectangle bounds, TreePath path, int row, boolean isExpanded, boolean hasBeenExpanded, boolean isLeaf) Paints the horizontal part of the leg.
protected void | BasicTreeUI.paintRow(Graphics g, Rectangle clipBounds, Insets insets, Rectangle bounds, TreePath path, int row, boolean isExpanded, boolean hasBeenExpanded, boolean isLeaf) Paints the renderer part of a row.
protected void | BasicTreeUI.paintVerticalPartOfLeg(Graphics g, Rectangle clipBounds, Insets insets, TreePath path) Paints the vertical part of the leg.
protected void | BasicTreeUI.pathWasCollapsed(TreePath path) Messaged from the VisibleTreeNode after it has collapsed.
protected void | BasicTreeUI.pathWasExpanded(TreePath path) Messaged from the VisibleTreeNode after it has been expanded.
protected void | BasicTreeUI.selectPathForEvent(TreePath path, MouseEvent event) Messaged to update the selection based on a MouseEvent over a particular row.
protected boolean | BasicTreeUI.shouldPaintExpandControl(TreePath path, int row, boolean isExpanded, boolean hasBeenExpanded, boolean isLeaf) Returns true if the expand (toggle) control should be drawn for the specified row.
protected boolean | BasicTreeUI.startEditing(TreePath path, MouseEvent event) Will start editing for node if there is a cellEditor and shouldSelectCell returns true.
void | BasicTreeUI.startEditingAtPath(JTree tree, TreePath path) Selects the last item in path and tries to edit it.
protected void | BasicTreeUI.toggleExpandState(TreePath path) Expands path if it is not expanded, or collapses row if it is expanded.
protected void | BasicTreeUI.updateExpandedDescendants(TreePath path) Updates the expanded state of all the descendants of path by getting the expanded descendants from the tree and forwarding to the tree state.

Uses of TreePath in javax.swing.plaf.metal

Methods in javax.swing.plaf.metal with parameters of type TreePath
protected void | MetalTreeUI.paintHorizontalPartOfLeg(Graphics g, Rectangle clipBounds, Insets insets, Rectangle bounds, TreePath path, int row, boolean isExpanded, boolean hasBeenExpanded, boolean isLeaf)
protected void | MetalTreeUI.paintVerticalPartOfLeg(Graphics g, Rectangle clipBounds, Insets insets, TreePath path)

Uses of TreePath in javax.swing.plaf.multi

Methods in javax.swing.plaf.multi that return TreePath
TreePath | MultiTreeUI.getClosestPathForLocation(JTree a, int b, int c) Invokes the getClosestPathForLocation method on each UI handled by this object.
TreePath | MultiTreeUI.getEditingPath(JTree a) Invokes the getEditingPath method on each UI handled by this object.
TreePath | MultiTreeUI.getPathForRow(JTree a, int b) Invokes the getPathForRow method on each UI handled by this object.

Methods in javax.swing.plaf.multi with parameters of type TreePath
Rectangle | MultiTreeUI.getPathBounds(JTree a, TreePath b) Invokes the getPathBounds method on each UI handled by this object.
int | MultiTreeUI.getRowForPath(JTree a, TreePath b) Invokes the getRowForPath method on each UI handled by this object.
void | MultiTreeUI.startEditingAtPath(JTree a, TreePath b) Invokes the startEditingAtPath method on each UI handled by this object.

Uses of TreePath in javax.swing.tree

Fields in javax.swing.tree declared as TreePath
protected TreePath | DefaultTreeCellEditor.lastPath Last path that was selected.
protected TreePath | DefaultTreeSelectionModel.leadPath Last path that was added.
protected TreePath[] | DefaultTreeSelectionModel.selection Paths that are currently selected.

Methods in javax.swing.tree that return TreePath
TreePath | DefaultTreeSelectionModel.getLeadSelectionPath() Returns the last path that was added.
TreePath | TreeSelectionModel.getLeadSelectionPath() Returns the last path that was added.
TreePath | TreePath.getParentPath() Returns a path containing all the elements of this object, except the last path component.
TreePath | VariableHeightLayoutCache.getPathClosestTo(int x, int y) Returns the path to the node that is closest to x,y.
TreePath | FixedHeightLayoutCache.getPathClosestTo(int x, int y) Returns the path to the node that is closest to x,y.
abstract TreePath | AbstractLayoutCache.getPathClosestTo(int x, int y) Returns the path to the node that is closest to x,y.
TreePath | VariableHeightLayoutCache.getPathForRow(int row) Returns the path for row.
TreePath | FixedHeightLayoutCache.getPathForRow(int row) Returns the path for passed in row.
abstract TreePath | AbstractLayoutCache.getPathForRow(int row) Returns the path for passed in row.
TreePath | DefaultTreeSelectionModel.getSelectionPath() Returns the first path in the selection.
TreePath | TreeSelectionModel.getSelectionPath() Returns the first path in the selection.
TreePath[] | DefaultTreeSelectionModel.getSelectionPaths() Returns the paths in the selection.
TreePath[] | TreeSelectionModel.getSelectionPaths() Returns the paths in the selection.
TreePath | TreePath.pathByAddingChild(Object child) Returns a new path containing all the elements of this object plus child.

Methods in javax.swing.tree that return types with arguments of type TreePath
Enumeration<TreePath> | VariableHeightLayoutCache.getVisiblePathsFrom(TreePath path) Returns an Enumerator that increments over the visible paths starting at the passed in location.
Enumeration<TreePath> | FixedHeightLayoutCache.getVisiblePathsFrom(TreePath path) Returns an Enumerator that increments over the visible paths starting at the passed in location.
abstract Enumeration<TreePath> | AbstractLayoutCache.getVisiblePathsFrom(TreePath path) Returns an Enumerator that increments over the visible paths starting at the passed in location.

Methods in javax.swing.tree with parameters of type TreePath
void | DefaultTreeSelectionModel.addSelectionPath(TreePath path) Adds path to the current selection.
void | TreeSelectionModel.addSelectionPath(TreePath path) Adds path to the current selection.
void | DefaultTreeSelectionModel.addSelectionPaths(TreePath[] paths) Adds paths to the current selection.
void | TreeSelectionModel.addSelectionPaths(TreePath[] paths) Adds paths to the current selection.
protected boolean | DefaultTreeSelectionModel.arePathsContiguous(TreePath[] paths) Returns true if the paths are contiguous, or this object has no RowMapper.
protected boolean | DefaultTreeSelectionModel.canPathsBeAdded(TreePath[] paths) Used to test if a particular set of TreePaths can be added.
protected boolean | DefaultTreeSelectionModel.canPathsBeRemoved(TreePath[] paths) Returns true if the paths can be removed without breaking the continuity of the model.
Rectangle | VariableHeightLayoutCache.getBounds(TreePath path, Rectangle placeIn) Returns the Rectangle enclosing the label portion into which the item identified by path will be drawn.
Rectangle | FixedHeightLayoutCache.getBounds(TreePath path, Rectangle placeIn) Returns a rectangle giving the bounds needed to draw path.
abstract Rectangle | AbstractLayoutCache.getBounds(TreePath path, Rectangle placeIn) Returns a rectangle giving the bounds needed to draw path.
boolean | VariableHeightLayoutCache.getExpandedState(TreePath path) Returns true if the path is expanded, and visible.
boolean | FixedHeightLayoutCache.getExpandedState(TreePath path) Returns true if the path is expanded, and visible.
abstract boolean | AbstractLayoutCache.getExpandedState(TreePath path) Returns true if the path is expanded, and visible.
int | VariableHeightLayoutCache.getRowForPath(TreePath path) Returns the row where the last item identified in path is visible.
int | FixedHeightLayoutCache.getRowForPath(TreePath path) Returns the row that the last item identified in path is visible at.
abstract int | AbstractLayoutCache.getRowForPath(TreePath path) Returns the row that the last item identified in path is visible at.
int[] | AbstractLayoutCache.getRowsForPaths(TreePath[] paths) Returns the rows that the TreePath instances in path are being displayed at.
int[] | RowMapper.getRowsForPaths(TreePath[] path) Returns the rows that the TreePath instances in path are being displayed at.
int | VariableHeightLayoutCache.getVisibleChildCount(TreePath path) Returns the number of visible children for path.
int | FixedHeightLayoutCache.getVisibleChildCount(TreePath path) Returns the number of visible children for row.
abstract int | AbstractLayoutCache.getVisibleChildCount(TreePath path) Returns the number of visible children for row.
Enumeration<TreePath> | VariableHeightLayoutCache.getVisiblePathsFrom(TreePath path) Returns an Enumerator that increments over the visible paths starting at the passed in location.
Enumeration<TreePath> | FixedHeightLayoutCache.getVisiblePathsFrom(TreePath path) Returns an Enumerator that increments over the visible paths starting at the passed in location.
abstract Enumeration<TreePath> | AbstractLayoutCache.getVisiblePathsFrom(TreePath path) Returns an Enumerator that increments over the visible paths starting at the passed in location.
void | VariableHeightLayoutCache.invalidatePathBounds(TreePath path) Instructs the LayoutCache that the bounds for path are invalid, and need to be updated.
void | FixedHeightLayoutCache.invalidatePathBounds(TreePath path) Does nothing, FixedHeightLayoutCache doesn't cache width, and that is all that could change.
abstract void | AbstractLayoutCache.invalidatePathBounds(TreePath path) Instructs the LayoutCache that the bounds for path are invalid, and need to be updated.
boolean | TreePath.isDescendant(TreePath aTreePath) Returns true if aTreePath is a descendant of this TreePath.
boolean | VariableHeightLayoutCache.isExpanded(TreePath path) Returns true if the value identified by path is currently expanded.
boolean | FixedHeightLayoutCache.isExpanded(TreePath path) Returns true if the value identified by row is currently expanded.
abstract boolean | AbstractLayoutCache.isExpanded(TreePath path) Returns true if the value identified by row is currently expanded.
boolean | DefaultTreeSelectionModel.isPathSelected(TreePath path) Returns true if the path, path, is in the current selection.
boolean | TreeSelectionModel.isPathSelected(TreePath path) Returns true if the path, path, is in the current selection.
protected void | DefaultTreeSelectionModel.notifyPathChange(Vector<javax.swing.tree.PathPlaceHolder> changedPaths, TreePath oldLeadSelection) Notifies listeners of a change in path.
void | DefaultTreeSelectionModel.removeSelectionPath(TreePath path) Removes path from the selection.
void | TreeSelectionModel.removeSelectionPath(TreePath path) Removes path from the selection.
void | DefaultTreeSelectionModel.removeSelectionPaths(TreePath[] paths) Removes paths from the selection.
void | TreeSelectionModel.removeSelectionPaths(TreePath[] paths) Removes paths from the selection.
void | VariableHeightLayoutCache.setExpandedState(TreePath path, boolean isExpanded) Marks the path path expanded state to isExpanded.
void | FixedHeightLayoutCache.setExpandedState(TreePath path, boolean isExpanded) Marks the path path expanded state to isExpanded.
abstract void | AbstractLayoutCache.setExpandedState(TreePath path, boolean isExpanded) Marks the path path expanded state to isExpanded.
void | DefaultTreeSelectionModel.setSelectionPath(TreePath path) Sets the selection to path.
void | TreeSelectionModel.setSelectionPath(TreePath path) Sets the selection to path.
void | DefaultTreeSelectionModel.setSelectionPaths(TreePath[] pPaths) Sets the selection to the paths in paths.
void | TreeSelectionModel.setSelectionPaths(TreePath[] paths) Sets the selection to path.
void | DefaultTreeModel.valueForPathChanged(TreePath path, Object newValue) This sets the user object of the TreeNode identified by path and posts a node changed.
void | TreeModel.valueForPathChanged(TreePath path, Object newValue) Messaged when the user has altered the value for the item identified by path to newValue.

Constructors in javax.swing.tree with parameters of type TreePath
TreePath(TreePath parent, Object lastElement)
Constructs a new TreePath, which is the path identified by parent ending in lastElement.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.tree.VariableHeightLayoutCache

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.tree.VariableHeightLayoutCache

No usage of javax.swing.tree.VariableHeightLayoutCache

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.tree.MutableTreeNode

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.tree.MutableTreeNode

Packages that use MutableTreeNode
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of MutableTreeNode in javax.swing

Classes in javax.swing that implement MutableTreeNode
static class JTree.DynamicUtilTreeNode
DynamicUtilTreeNode can wrap vectors/hashtables/arrays/strings and create the appropriate children tree nodes as necessary.

Uses of MutableTreeNode in javax.swing.tree

Classes in javax.swing.tree that implement MutableTreeNode
 class DefaultMutableTreeNode
A DefaultMutableTreeNode is a general-purpose node in a tree data structure.

Fields in javax.swing.tree declared as MutableTreeNode
protected  MutableTreeNode DefaultMutableTreeNode.parent
this node's parent, or null if this node has no parent

Methods in javax.swing.tree with parameters of type MutableTreeNode
void | DefaultMutableTreeNode.add(MutableTreeNode newChild) Removes newChild from its parent and makes it a child of this node by adding it to the end of this node's child array.
void | MutableTreeNode.insert(MutableTreeNode child, int index) Adds child to the receiver at index.
void | DefaultMutableTreeNode.insert(MutableTreeNode newChild, int childIndex) Removes newChild from its present parent (if it has a parent), sets the child's parent to this node, and then adds the child to this node's child array at index childIndex.
void | DefaultTreeModel.insertNodeInto(MutableTreeNode newChild, MutableTreeNode parent, int index) Invoked this to insert newChild at location index in parents children.
void | MutableTreeNode.remove(MutableTreeNode node) Removes node from the receiver.
void | DefaultMutableTreeNode.remove(MutableTreeNode aChild) Removes aChild from this node's child array, giving it a null parent.
void | DefaultTreeModel.removeNodeFromParent(MutableTreeNode node) Message this to remove node from its parent.
void | MutableTreeNode.setParent(MutableTreeNode newParent) Sets the parent of the receiver to newParent.
void | DefaultMutableTreeNode.setParent(MutableTreeNode newParent) Sets this node's parent to newParent but does not change the parent's child array.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.tree.RowMapper

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.tree.RowMapper

Packages that use RowMapper
javax.swing.tree Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of RowMapper in javax.swing.tree

Classes in javax.swing.tree that implement RowMapper
class | AbstractLayoutCache Warning: Serialized objects of this class will not be compatible with future Swing releases.
class | FixedHeightLayoutCache NOTE: This will become more open in a future release.
class | VariableHeightLayoutCache NOTE: This will become more open in a future release.

Fields in javax.swing.tree declared as RowMapper
protected  RowMapper DefaultTreeSelectionModel.rowMapper
Provides a row for a given path.

Methods in javax.swing.tree that return RowMapper
RowMapper | DefaultTreeSelectionModel.getRowMapper() Returns the RowMapper instance that is able to map a TreePath to a row.
RowMapper | TreeSelectionModel.getRowMapper() Returns the RowMapper instance that is able to map a TreePath to a row.

Methods in javax.swing.tree with parameters of type RowMapper
void | DefaultTreeSelectionModel.setRowMapper(RowMapper newMapper) Sets the RowMapper instance.
void | TreeSelectionModel.setRowMapper(RowMapper newMapper) Sets the RowMapper instance.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.tree.TreeCellEditor

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.tree.TreeCellEditor

Packages that use TreeCellEditor
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of TreeCellEditor in javax.swing

Classes in javax.swing that implement TreeCellEditor
 class DefaultCellEditor
The default editor for table and tree cells.

Fields in javax.swing declared as TreeCellEditor
protected  TreeCellEditor JTree.cellEditor
Editor for the entries.

Methods in javax.swing that return TreeCellEditor
 TreeCellEditor JTree.getCellEditor()
Returns the editor used to edit entries in the tree.

Methods in javax.swing with parameters of type TreeCellEditor
 void JTree.setCellEditor(TreeCellEditor cellEditor)
Sets the cell editor.

Uses of TreeCellEditor in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as TreeCellEditor
protected  TreeCellEditor BasicTreeUI.cellEditor
Editor for the tree.

Methods in javax.swing.plaf.basic that return TreeCellEditor
protected TreeCellEditor | BasicTreeUI.createDefaultCellEditor() Creates a default cell editor.
protected TreeCellEditor | BasicTreeUI.getCellEditor()

Methods in javax.swing.plaf.basic with parameters of type TreeCellEditor
protected  void BasicTreeUI.setCellEditor(TreeCellEditor editor)
Sets the cell editor.

Uses of TreeCellEditor in javax.swing.tree

Classes in javax.swing.tree that implement TreeCellEditor
 class DefaultTreeCellEditor
A TreeCellEditor.

Fields in javax.swing.tree declared as TreeCellEditor
protected  TreeCellEditor DefaultTreeCellEditor.realEditor
Editor handling the editing.

Methods in javax.swing.tree that return TreeCellEditor
protected  TreeCellEditor DefaultTreeCellEditor.createTreeCellEditor()
This is invoked if a TreeCellEditor is not supplied in the constructor.

Constructors in javax.swing.tree with parameters of type TreeCellEditor
DefaultTreeCellEditor(JTree tree, DefaultTreeCellRenderer renderer, TreeCellEditor editor)
Constructs a DefaultTreeCellEditor object for a JTree using the specified renderer and the specified editor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.tree.TreeCellRenderer

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.tree.TreeCellRenderer

Packages that use TreeCellRenderer
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of TreeCellRenderer in javax.swing

Fields in javax.swing declared as TreeCellRenderer
protected  TreeCellRenderer JTree.cellRenderer
The cell used to draw nodes.

Methods in javax.swing that return TreeCellRenderer
 TreeCellRenderer JTree.getCellRenderer()
Returns the current TreeCellRenderer that is rendering each cell.

Methods in javax.swing with parameters of type TreeCellRenderer
 void JTree.setCellRenderer(TreeCellRenderer x)
Sets the TreeCellRenderer that will be used to draw each cell.

Uses of TreeCellRenderer in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as TreeCellRenderer
protected  TreeCellRenderer BasicTreeUI.currentCellRenderer
Renderer that is being used to do the actual cell drawing.

Methods in javax.swing.plaf.basic that return TreeCellRenderer
protected TreeCellRenderer | BasicTreeUI.createDefaultCellRenderer() Returns the default cell renderer that is used to do the stamping of each node.
protected TreeCellRenderer | BasicTreeUI.getCellRenderer() Return currentCellRenderer, which will either be the trees renderer, or defaultCellRenderer, which ever wasn't null.

Methods in javax.swing.plaf.basic with parameters of type TreeCellRenderer
protected  void BasicTreeUI.setCellRenderer(TreeCellRenderer tcr)
Sets the TreeCellRenderer to tcr.

Uses of TreeCellRenderer in javax.swing.tree

Classes in javax.swing.tree that implement TreeCellRenderer
 class DefaultTreeCellRenderer
Displays an entry in a tree.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.tree.TreeModel

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.tree.TreeModel

Packages that use TreeModel
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of TreeModel in javax.swing

Fields in javax.swing declared as TreeModel
protected  TreeModel JTree.treeModel
The model that defines the tree displayed by this object.

Methods in javax.swing that return TreeModel
protected static TreeModel | JTree.createTreeModel(Object value) Returns a TreeModel wrapping the specified object.
protected static TreeModel | JTree.getDefaultTreeModel() Creates and returns a sample TreeModel.
TreeModel | JTree.getModel() Returns the TreeModel that is providing the data.

Methods in javax.swing with parameters of type TreeModel
 void JTree.setModel(TreeModel newModel)
Sets the TreeModel that will provide the data.

Constructors in javax.swing with parameters of type TreeModel
JTree(TreeModel newModel)
Returns an instance of JTree which displays the root node -- the tree is created using the specified data model.

Uses of TreeModel in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as TreeModel
protected  TreeModel BasicTreeUI.treeModel
Used to determine what to display.

Methods in javax.swing.plaf.basic that return TreeModel
protected  TreeModel BasicTreeUI.getModel()

Methods in javax.swing.plaf.basic with parameters of type TreeModel
protected  void BasicTreeUI.setModel(TreeModel model)
Sets the TreeModel.

Uses of TreeModel in javax.swing.tree

Classes in javax.swing.tree that implement TreeModel
 class DefaultTreeModel
A simple tree data model that uses TreeNodes.

Fields in javax.swing.tree declared as TreeModel
protected  TreeModel AbstractLayoutCache.treeModel
Model providing information.

Methods in javax.swing.tree that return TreeModel
 TreeModel AbstractLayoutCache.getModel()
Returns the TreeModel that is providing the data.

Methods in javax.swing.tree with parameters of type TreeModel
void | VariableHeightLayoutCache.setModel(TreeModel newModel) Sets the TreeModel that will provide the data.
void | FixedHeightLayoutCache.setModel(TreeModel newModel) Sets the TreeModel that will provide the data.
void | AbstractLayoutCache.setModel(TreeModel newModel) Sets the TreeModel that will provide the data.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.tree.TreeNode

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.tree.TreeNode

Packages that use TreeNode
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.text.html | Provides the class HTMLEditorKit and supporting classes for creating HTML text editors.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of TreeNode in javax.swing

Classes in javax.swing that implement TreeNode
static class JTree.DynamicUtilTreeNode
DynamicUtilTreeNode can wrap vectors/hashtables/arrays/strings and create the appropriate children tree nodes as necessary.

Methods in javax.swing that return TreeNode
 TreeNode JTree.DynamicUtilTreeNode.getChildAt(int index)
Subclassed to load the children, if necessary.

Constructors in javax.swing with parameters of type TreeNode
JTree(TreeNode root)
Returns a JTree with the specified TreeNode as its root, which displays the root node.
JTree(TreeNode root, boolean asksAllowsChildren)
Returns a JTree with the specified TreeNode as its root, which displays the root node and which decides whether a node is a leaf node in the specified manner.

Uses of TreeNode in javax.swing.text

Classes in javax.swing.text that implement TreeNode
class | AbstractDocument.AbstractElement Implements the abstract part of an element.
class | AbstractDocument.BranchElement Implements a composite element that contains other elements.
class | AbstractDocument.LeafElement Implements an element that directly represents content of some kind.
protected class | DefaultStyledDocument.SectionElement Default root element for a document...

Methods in javax.swing.text that return TreeNode
TreeNode | AbstractDocument.AbstractElement.getChildAt(int childIndex) Returns the child TreeNode at index childIndex.
TreeNode | AbstractDocument.AbstractElement.getParent() Returns the parent TreeNode of the receiver.

Methods in javax.swing.text with parameters of type TreeNode
 int AbstractDocument.AbstractElement.getIndex(TreeNode node)
Returns the index of node in the receivers children.

Uses of TreeNode in javax.swing.text.html

Classes in javax.swing.text.html that implement TreeNode
class | HTMLDocument.BlockElement An element that represents a structural block of HTML.
class | HTMLDocument.RunElement An element that represents a chunk of text that has a set of HTML character level attributes assigned to it.

Uses of TreeNode in javax.swing.tree

Subinterfaces of TreeNode in javax.swing.tree
 interface MutableTreeNode
Defines the requirements for a tree node object that can change -- by adding or removing child nodes, or by changing the contents of a user object stored in the node.

Classes in javax.swing.tree that implement TreeNode
 class DefaultMutableTreeNode
A DefaultMutableTreeNode is a general-purpose node in a tree data structure.

Fields in javax.swing.tree declared as TreeNode
protected  TreeNode DefaultTreeModel.root
Root of the tree.

Fields in javax.swing.tree with type parameters of type TreeNode
static Enumeration<TreeNode> DefaultMutableTreeNode.EMPTY_ENUMERATION
An enumeration that is always empty.

Methods in javax.swing.tree that return TreeNode
TreeNode | DefaultMutableTreeNode.getChildAfter(TreeNode aChild) Returns the child in this node's child array that immediately follows aChild, which must be a child of this node.
TreeNode | DefaultMutableTreeNode.getChildAt(int index) Returns the child at the specified index in this node's child array.
TreeNode | TreeNode.getChildAt(int childIndex) Returns the child TreeNode at index childIndex.
TreeNode | DefaultMutableTreeNode.getChildBefore(TreeNode aChild) Returns the child in this node's child array that immediately precedes aChild, which must be a child of this node.
TreeNode | DefaultMutableTreeNode.getFirstChild() Returns this node's first child.
TreeNode | DefaultMutableTreeNode.getLastChild() Returns this node's last child.
TreeNode | DefaultMutableTreeNode.getParent() Returns this node's parent or null if this node has no parent.
TreeNode | TreeNode.getParent() Returns the parent TreeNode of the receiver.
TreeNode[] | DefaultMutableTreeNode.getPath() Returns the path from the root, to get to this node.
TreeNode[] | DefaultTreeModel.getPathToRoot(TreeNode aNode) Builds the parents of node up to and including the root node, where the original node is the last element in the returned array.
protected TreeNode[] | DefaultTreeModel.getPathToRoot(TreeNode aNode, int depth) Builds the parents of node up to and including the root node, where the original node is the last element in the returned array.
protected TreeNode[] | DefaultMutableTreeNode.getPathToRoot(TreeNode aNode, int depth) Builds the parents of node up to and including the root node, where the original node is the last element in the returned array.
TreeNode | DefaultMutableTreeNode.getRoot() Returns the root of the tree that contains this node.
TreeNode | DefaultMutableTreeNode.getSharedAncestor(DefaultMutableTreeNode aNode) Returns the nearest common ancestor to this node and aNode.

Methods in javax.swing.tree with parameters of type TreeNode
TreeNode | DefaultMutableTreeNode.getChildAfter(TreeNode aChild) Returns the child in this node's child array that immediately follows aChild, which must be a child of this node.
TreeNode | DefaultMutableTreeNode.getChildBefore(TreeNode aChild) Returns the child in this node's child array that immediately precedes aChild, which must be a child of this node.
int | DefaultMutableTreeNode.getIndex(TreeNode aChild) Returns the index of the specified child in this node's child array.
int | TreeNode.getIndex(TreeNode node) Returns the index of node in the receivers children.
TreeNode[] | DefaultTreeModel.getPathToRoot(TreeNode aNode) Builds the parents of node up to and including the root node, where the original node is the last element in the returned array.
protected TreeNode[] | DefaultTreeModel.getPathToRoot(TreeNode aNode, int depth) Builds the parents of node up to and including the root node, where the original node is the last element in the returned array.
protected TreeNode[] | DefaultMutableTreeNode.getPathToRoot(TreeNode aNode, int depth) Builds the parents of node up to and including the root node, where the original node is the last element in the returned array.
boolean | DefaultMutableTreeNode.isNodeAncestor(TreeNode anotherNode) Returns true if anotherNode is an ancestor of this node -- if it is this node, this node's parent, or an ancestor of this node's parent.
boolean | DefaultMutableTreeNode.isNodeChild(TreeNode aNode) Returns true if aNode is a child of this node.
boolean | DefaultMutableTreeNode.isNodeSibling(TreeNode anotherNode) Returns true if anotherNode is a sibling of (has the same parent as) this node.
void | DefaultTreeModel.nodeChanged(TreeNode node) Invoke this method after you've changed how node is to be represented in the tree.
void | DefaultTreeModel.nodesChanged(TreeNode node, int[] childIndices) Invoke this method after you've changed how the children identified by childIndicies are to be represented in the tree.
void | DefaultTreeModel.nodeStructureChanged(TreeNode node) Invoke this method if you've totally changed the children of node and its childrens children...
void | DefaultTreeModel.nodesWereInserted(TreeNode node, int[] childIndices) Invoke this method after you've inserted some TreeNodes into node.
void | DefaultTreeModel.nodesWereRemoved(TreeNode node, int[] childIndices, Object[] removedChildren) Invoke this method after you've removed some TreeNodes from node.
Enumeration | DefaultMutableTreeNode.pathFromAncestorEnumeration(TreeNode ancestor) Creates and returns an enumeration that follows the path from ancestor to this node.
void | DefaultTreeModel.reload(TreeNode node) Invoke this method if you've modified the TreeNodes upon which this model depends.
void | DefaultTreeModel.setRoot(TreeNode root) Sets the root to root.

Constructors in javax.swing.tree with parameters of type TreeNode
DefaultTreeModel(TreeNode root)
Creates a tree in which any node can have children.
DefaultTreeModel(TreeNode root, boolean asksAllowsChildren)
Creates a tree specifying whether any node can have children, or whether only certain nodes can have children.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.tree.TreeSelectionModel

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.tree.TreeSelectionModel

Packages that use TreeSelectionModel
javax.swing | Provides a set of "lightweight" (all-Java language) components that, to the maximum degree possible, work the same on all platforms.
javax.swing.plaf.basic | Provides user interface objects built according to the Basic look and feel.
javax.swing.tree | Provides classes and interfaces for dealing with javax.swing.JTree.

Uses of TreeSelectionModel in javax.swing

Classes in javax.swing that implement TreeSelectionModel
protected static class JTree.EmptySelectionModel
EmptySelectionModel is a TreeSelectionModel that does not allow anything to be selected.

Fields in javax.swing declared as TreeSelectionModel
protected  TreeSelectionModel JTree.selectionModel
Models the set of selected nodes in this tree.

Methods in javax.swing that return TreeSelectionModel
 TreeSelectionModel JTree.getSelectionModel()
Returns the model for selections.

Methods in javax.swing with parameters of type TreeSelectionModel
 void JTree.setSelectionModel(TreeSelectionModel selectionModel)
Sets the tree's selection model.

Uses of TreeSelectionModel in javax.swing.plaf.basic

Fields in javax.swing.plaf.basic declared as TreeSelectionModel
protected  TreeSelectionModel BasicTreeUI.treeSelectionModel
Model maintaing the selection.

Methods in javax.swing.plaf.basic that return TreeSelectionModel
protected  TreeSelectionModel BasicTreeUI.getSelectionModel()

Methods in javax.swing.plaf.basic with parameters of type TreeSelectionModel
protected  void BasicTreeUI.setSelectionModel(TreeSelectionModel newLSM)
Resets the selection model.

Uses of TreeSelectionModel in javax.swing.tree

Classes in javax.swing.tree that implement TreeSelectionModel
 class DefaultTreeSelectionModel
Default implementation of TreeSelectionModel.

Fields in javax.swing.tree declared as TreeSelectionModel
protected  TreeSelectionModel AbstractLayoutCache.treeSelectionModel
Selection model.

Methods in javax.swing.tree that return TreeSelectionModel
 TreeSelectionModel AbstractLayoutCache.getSelectionModel()
Returns the model used to maintain the selection.

Methods in javax.swing.tree with parameters of type TreeSelectionModel
 void AbstractLayoutCache.setSelectionModel(TreeSelectionModel newLSM)
Sets the TreeSelectionModel used to manage the selection to new LSM.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DefaultMutableTreeNode

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Class DefaultMutableTreeNode

java.lang.Object
    extended by  javax.swing.tree.DefaultMutableTreeNode
All Implemented Interfaces:
Serializable, Cloneable, MutableTreeNode, TreeNode
Direct Known Subclasses:
JTree.DynamicUtilTreeNode
public class DefaultMutableTreeNode
extends Object
implements Cloneable, MutableTreeNode, Serializable

A DefaultMutableTreeNode is a general-purpose node in a tree data structure. For examples of using default mutable tree nodes, see How to Use Trees in The Java Tutorial.

A tree node may have at most one parent and 0 or more children. DefaultMutableTreeNode provides operations for examining and modifying a node's parent and children and also operations for examining the tree that the node is a part of. A node's tree is the set of all nodes that can be reached by starting at the node and following all the possible links to parents and children. A node with no parent is the root of its tree; a node with no children is a leaf. A tree may consist of many subtrees, each node acting as the root for its own subtree.

This class provides enumerations for efficiently traversing a tree or subtree in various orders or for following the path between two nodes. A DefaultMutableTreeNode may also hold a reference to a user object, the use of which is left to the user. Asking a DefaultMutableTreeNode for its string representation with toString() returns the string representation of its user object.

This is not a thread safe class.If you intend to use a DefaultMutableTreeNode (or a tree of TreeNodes) in more than one thread, you need to do your own synchronizing. A good convention to adopt is synchronizing on the root node of a tree.

While DefaultMutableTreeNode implements the MutableTreeNode interface and will allow you to add in any implementation of MutableTreeNode not all of the methods in DefaultMutableTreeNode will be applicable to all MutableTreeNodes implementations. Especially with some of the enumerations that are provided, using some of these methods assumes the DefaultMutableTreeNode contains only DefaultMutableNode instances. All of the TreeNode/MutableTreeNode methods will behave as defined no matter what implementations are added.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
MutableTreeNode

Field Summary
protected boolean | allowsChildren true if the node is able to have children
protected Vector | children array of children, may be null if this node has no children
static Enumeration<TreeNode> | EMPTY_ENUMERATION An enumeration that is always empty.
protected MutableTreeNode | parent this node's parent, or null if this node has no parent
protected Object | userObject optional user object
Constructor Summary
DefaultMutableTreeNode()
Creates a tree node that has no parent and no children, but which allows children.
DefaultMutableTreeNode(Object userObject)
Creates a tree node with no parent, no children, but which allows children, and initializes it with the specified user object.
DefaultMutableTreeNode(Object userObject, boolean allowsChildren)
Creates a tree node with no parent, no children, initialized with the specified user object, and that allows children only if specified.
Method Summary
 void add(MutableTreeNode newChild)
Removes newChild from its parent and makes it a child of this node by adding it to the end of this node's child array.
 Enumeration breadthFirstEnumeration()
Creates and returns an enumeration that traverses the subtree rooted at this node in breadth-first order.
 Enumeration children()
Creates and returns a forward-order enumeration of this node's children.
 Object clone()
Overridden to make clone public.
 Enumeration depthFirstEnumeration()
Creates and returns an enumeration that traverses the subtree rooted at this node in depth-first order.
 boolean getAllowsChildren()
Returns true if this node is allowed to have children.
 TreeNode getChildAfter(TreeNode aChild)
Returns the child in this node's child array that immediately follows aChild, which must be a child of this node.
 TreeNode getChildAt(int index)
Returns the child at the specified index in this node's child array.
 TreeNode getChildBefore(TreeNode aChild)
Returns the child in this node's child array that immediately precedes aChild, which must be a child of this node.
 int getChildCount()
Returns the number of children of this node.
 int getDepth()
Returns the depth of the tree rooted at this node -- the longest distance from this node to a leaf.
 TreeNode getFirstChild()
Returns this node's first child.
 DefaultMutableTreeNode getFirstLeaf()
Finds and returns the first leaf that is a descendant of this node -- either this node or its first child's first leaf.
 int getIndex(TreeNode aChild)
Returns the index of the specified child in this node's child array.
 TreeNode getLastChild()
Returns this node's last child.
 DefaultMutableTreeNode getLastLeaf()
Finds and returns the last leaf that is a descendant of this node -- either this node or its last child's last leaf.
 int getLeafCount()
Returns the total number of leaves that are descendants of this node.
 int getLevel()
Returns the number of levels above this node -- the distance from the root to this node.
 DefaultMutableTreeNode getNextLeaf()
Returns the leaf after this node or null if this node is the last leaf in the tree.
 DefaultMutableTreeNode getNextNode()
Returns the node that follows this node in a preorder traversal of this node's tree.
 DefaultMutableTreeNode getNextSibling()
Returns the next sibling of this node in the parent's children array.
 TreeNode getParent()
Returns this node's parent or null if this node has no parent.
 TreeNode[] getPath()
Returns the path from the root, to get to this node.
protected  TreeNode[] getPathToRoot(TreeNode aNode, int depth)
Builds the parents of node up to and including the root node, where the original node is the last element in the returned array.
 DefaultMutableTreeNode getPreviousLeaf()
Returns the leaf before this node or null if this node is the first leaf in the tree.
 DefaultMutableTreeNode getPreviousNode()
Returns the node that precedes this node in a preorder traversal of this node's tree.
 DefaultMutableTreeNode getPreviousSibling()
Returns the previous sibling of this node in the parent's children array.
 TreeNode getRoot()
Returns the root of the tree that contains this node.
 TreeNode getSharedAncestor(DefaultMutableTreeNode aNode)
Returns the nearest common ancestor to this node and aNode.
 int getSiblingCount()
Returns the number of siblings of this node.
 Object getUserObject()
Returns this node's user object.
 Object[] getUserObjectPath()
Returns the user object path, from the root, to get to this node.
 void insert(MutableTreeNode newChild, int childIndex)
Removes newChild from its present parent (if it has a parent), sets the child's parent to this node, and then adds the child to this node's child array at index childIndex.
 boolean isLeaf()
Returns true if this node has no children.
 boolean isNodeAncestor(TreeNode anotherNode)
Returns true if anotherNode is an ancestor of this node -- if it is this node, this node's parent, or an ancestor of this node's parent.
 boolean isNodeChild(TreeNode aNode)
Returns true if aNode is a child of this node.
 boolean isNodeDescendant(DefaultMutableTreeNode anotherNode)
Returns true if anotherNode is a descendant of this node -- if it is this node, one of this node's children, or a descendant of one of this node's children.
 boolean isNodeRelated(DefaultMutableTreeNode aNode)
Returns true if and only if aNode is in the same tree as this node.
 boolean isNodeSibling(TreeNode anotherNode)
Returns true if anotherNode is a sibling of (has the same parent as) this node.
 boolean isRoot()
Returns true if this node is the root of the tree.
 Enumeration pathFromAncestorEnumeration(TreeNode ancestor)
Creates and returns an enumeration that follows the path from ancestor to this node.
 Enumeration postorderEnumeration()
Creates and returns an enumeration that traverses the subtree rooted at this node in postorder.
 Enumeration preorderEnumeration()
Creates and returns an enumeration that traverses the subtree rooted at this node in preorder.
 void remove(int childIndex)
Removes the child at the specified index from this node's children and sets that node's parent to null.
 void remove(MutableTreeNode aChild)
Removes aChild from this node's child array, giving it a null parent.
 void removeAllChildren()
Removes all of this node's children, setting their parents to null.
 void removeFromParent()
Removes the subtree rooted at this node from the tree, giving this node a null parent.
 void setAllowsChildren(boolean allows)
Determines whether or not this node is allowed to have children.
 void setParent(MutableTreeNode newParent)
Sets this node's parent to newParent but does not change the parent's child array.
 void setUserObject(Object userObject)
Sets the user object for this node to userObject.
 String toString()
Returns the result of sending toString() to this node's user object, or null if this node has no user object.
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY_ENUMERATION

public static final Enumeration<TreeNode> EMPTY_ENUMERATION
An enumeration that is always empty. This is used when an enumeration of a leaf node's children is requested.

parent

protected MutableTreeNode parent
this node's parent, or null if this node has no parent

children

protected Vector children
array of children, may be null if this node has no children

userObject

protected transient Object userObject
optional user object

allowsChildren

protected boolean allowsChildren
true if the node is able to have children

Constructor Detail

DefaultMutableTreeNode

public DefaultMutableTreeNode()
Creates a tree node that has no parent and no children, but which allows children.

DefaultMutableTreeNode

public DefaultMutableTreeNode(Object userObject)
Creates a tree node with no parent, no children, but which allows children, and initializes it with the specified user object.

Parameters:
userObject - an Object provided by the user that constitutes the node's data

DefaultMutableTreeNode

public DefaultMutableTreeNode(Object userObject,
                              boolean allowsChildren)
Creates a tree node with no parent, no children, initialized with the specified user object, and that allows children only if specified.

Parameters:
userObject - an Object provided by the user that constitutes the node's data
allowsChildren - if true, the node is allowed to have child nodes -- otherwise, it is always a leaf node
Method Detail

insert

public void insert(MutableTreeNode newChild,
                   int childIndex)
Removes newChild from its present parent (if it has a parent), sets the child's parent to this node, and then adds the child to this node's child array at index childIndex. newChild must not be null and must not be an ancestor of this node.

Specified by:
insert in interface MutableTreeNode
Parameters:
newChild - the MutableTreeNode to insert under this node
childIndex - the index in this node's child array where this node is to be inserted
Throws:
ArrayIndexOutOfBoundsException - if childIndex is out of bounds
IllegalArgumentException - if newChild is null or is an ancestor of this node
IllegalStateException - if this node does not allow children
See Also:
isNodeDescendant(javax.swing.tree.DefaultMutableTreeNode)

remove

public void remove(int childIndex)
Removes the child at the specified index from this node's children and sets that node's parent to null. The child node to remove must be a MutableTreeNode.

Specified by:
remove in interface MutableTreeNode
Parameters:
childIndex - the index in this node's child array of the child to remove
Throws:
ArrayIndexOutOfBoundsException - if childIndex is out of bounds

setParent

public void setParent(MutableTreeNode newParent)
Sets this node's parent to newParent but does not change the parent's child array. This method is called from insert() and remove() to reassign a child's parent, it should not be messaged from anywhere else.

Specified by:
setParent in interface MutableTreeNode
Parameters:
newParent - this node's new parent

getParent

public TreeNode getParent()
Returns this node's parent or null if this node has no parent.

Specified by:
getParent in interface TreeNode
Returns:
this node's parent TreeNode, or null if this node has no parent

getChildAt

public TreeNode getChildAt(int index)
Returns the child at the specified index in this node's child array.

Specified by:
getChildAt in interface TreeNode
Parameters:
index - an index into this node's child array
Returns:
the TreeNode in this node's child array at the specified index
Throws:
ArrayIndexOutOfBoundsException - if index is out of bounds

getChildCount

public int getChildCount()
Returns the number of children of this node.

Specified by:
getChildCount in interface TreeNode
Returns:
an int giving the number of children of this node

getIndex

public int getIndex(TreeNode aChild)
Returns the index of the specified child in this node's child array. If the specified node is not a child of this node, returns -1. This method performs a linear search and is O(n) where n is the number of children.

Specified by:
getIndex in interface TreeNode
Parameters:
aChild - the TreeNode to search for among this node's children
Returns:
an int giving the index of the node in this node's child array, or -1 if the specified node is a not a child of this node
Throws:
IllegalArgumentException - if aChild is null

children

public Enumeration children()
Creates and returns a forward-order enumeration of this node's children. Modifying this node's child array invalidates any child enumerations created before the modification.

Specified by:
children in interface TreeNode
Returns:
an Enumeration of this node's children

setAllowsChildren

public void setAllowsChildren(boolean allows)
Determines whether or not this node is allowed to have children. If allows is false, all of this node's children are removed.

Note: By default, a node allows children.

Parameters:
allows - true if this node is allowed to have children

getAllowsChildren

public boolean getAllowsChildren()
Returns true if this node is allowed to have children.

Specified by:
getAllowsChildren in interface TreeNode
Returns:
true if this node allows children, else false

setUserObject

public void setUserObject(Object userObject)
Sets the user object for this node to userObject.

Specified by:
setUserObject in interface MutableTreeNode
Parameters:
userObject - the Object that constitutes this node's user-specified data
See Also:
getUserObject(), toString()

getUserObject

public Object getUserObject()
Returns this node's user object.

Returns:
the Object stored at this node by the user
See Also:
setUserObject(java.lang.Object), toString()

removeFromParent

public void removeFromParent()
Removes the subtree rooted at this node from the tree, giving this node a null parent. Does nothing if this node is the root of its tree.

Specified by:
removeFromParent in interface MutableTreeNode

remove

public void remove(MutableTreeNode aChild)
Removes aChild from this node's child array, giving it a null parent.

Specified by:
remove in interface MutableTreeNode
Parameters:
aChild - a child of this node to remove
Throws:
IllegalArgumentException - if aChild is null or is not a child of this node

removeAllChildren

public void removeAllChildren()
Removes all of this node's children, setting their parents to null. If this node has no children, this method does nothing.

add

public void add(MutableTreeNode newChild)
Removes newChild from its parent and makes it a child of this node by adding it to the end of this node's child array.

Parameters:
newChild - node to add as a child of this node
Throws:
IllegalArgumentException - if newChild is null
IllegalStateException - if this node does not allow children
See Also:
insert(javax.swing.tree.MutableTreeNode, int)

isNodeAncestor

public boolean isNodeAncestor(TreeNode anotherNode)
Returns true if anotherNode is an ancestor of this node -- if it is this node, this node's parent, or an ancestor of this node's parent. (Note that a node is considered an ancestor of itself.) If anotherNode is null, this method returns false. This operation is at worst O(h) where h is the distance from the root to this node.

Parameters:
anotherNode - node to test as an ancestor of this node
Returns:
true if this node is a descendant of anotherNode
See Also:
isNodeDescendant(javax.swing.tree.DefaultMutableTreeNode), getSharedAncestor(javax.swing.tree.DefaultMutableTreeNode)

isNodeDescendant

public boolean isNodeDescendant(DefaultMutableTreeNode anotherNode)
Returns true if anotherNode is a descendant of this node -- if it is this node, one of this node's children, or a descendant of one of this node's children. Note that a node is considered a descendant of itself. If anotherNode is null, returns false. This operation is at worst O(h) where h is the distance from the root to anotherNode.

Parameters:
anotherNode - node to test as descendant of this node
Returns:
true if this node is an ancestor of anotherNode
See Also:
isNodeAncestor(javax.swing.tree.TreeNode), getSharedAncestor(javax.swing.tree.DefaultMutableTreeNode)

getSharedAncestor

public TreeNode getSharedAncestor(DefaultMutableTreeNode aNode)
Returns the nearest common ancestor to this node and aNode. Returns null, if no such ancestor exists -- if this node and aNode are in different trees or if aNode is null. A node is considered an ancestor of itself.

Parameters:
aNode - node to find common ancestor with
Returns:
nearest ancestor common to this node and aNode, or null if none
See Also:
isNodeAncestor(javax.swing.tree.TreeNode), isNodeDescendant(javax.swing.tree.DefaultMutableTreeNode)

isNodeRelated

public boolean isNodeRelated(DefaultMutableTreeNode aNode)
Returns true if and only if aNode is in the same tree as this node. Returns false if aNode is null.

Returns:
true if aNode is in the same tree as this node; false if aNode is null
See Also:
getSharedAncestor(javax.swing.tree.DefaultMutableTreeNode), getRoot()

getDepth

public int getDepth()
Returns the depth of the tree rooted at this node -- the longest distance from this node to a leaf. If this node has no children, returns 0. This operation is much more expensive than getLevel() because it must effectively traverse the entire tree rooted at this node.

Returns:
the depth of the tree whose root is this node
See Also:
getLevel()

getLevel

public int getLevel()
Returns the number of levels above this node -- the distance from the root to this node. If this node is the root, returns 0.

Returns:
the number of levels above this node
See Also:
getDepth()

getPath

public TreeNode[] getPath()
Returns the path from the root, to get to this node. The last element in the path is this node.

Returns:
an array of TreeNode objects giving the path, where the first element in the path is the root and the last element is this node.

getPathToRoot

protected TreeNode[] getPathToRoot(TreeNode aNode,
                                   int depth)
Builds the parents of node up to and including the root node, where the original node is the last element in the returned array. The length of the returned array gives the node's depth in the tree.

Parameters:
aNode - the TreeNode to get the path for
depth - an int giving the number of steps already taken towards the root (on recursive calls), used to size the returned array
Returns:
an array of TreeNodes giving the path from the root to the specified node

getUserObjectPath

public Object[] getUserObjectPath()
Returns the user object path, from the root, to get to this node. If some of the TreeNodes in the path have null user objects, the returned path will contain nulls.

getRoot

public TreeNode getRoot()
Returns the root of the tree that contains this node. The root is the ancestor with a null parent.

Returns:
the root of the tree that contains this node
See Also:
isNodeAncestor(javax.swing.tree.TreeNode)

isRoot

public boolean isRoot()
Returns true if this node is the root of the tree. The root is the only node in the tree with a null parent; every tree has exactly one root.

Returns:
true if this node is the root of its tree

getNextNode

public DefaultMutableTreeNode getNextNode()
Returns the node that follows this node in a preorder traversal of this node's tree. Returns null if this node is the last node of the traversal. This is an inefficient way to traverse the entire tree; use an enumeration, instead.

Returns:
the node that follows this node in a preorder traversal, or null if this node is last
See Also:
preorderEnumeration()

getPreviousNode

public DefaultMutableTreeNode getPreviousNode()
Returns the node that precedes this node in a preorder traversal of this node's tree. Returns null if this node is the first node of the traversal -- the root of the tree. This is an inefficient way to traverse the entire tree; use an enumeration, instead.

Returns:
the node that precedes this node in a preorder traversal, or null if this node is the first
See Also:
preorderEnumeration()

preorderEnumeration

public Enumeration preorderEnumeration()
Creates and returns an enumeration that traverses the subtree rooted at this node in preorder. The first node returned by the enumeration's nextElement() method is this node.

Modifying the tree by inserting, removing, or moving a node invalidates any enumerations created before the modification.

Returns:
an enumeration for traversing the tree in preorder
See Also:
postorderEnumeration()

postorderEnumeration

public Enumeration postorderEnumeration()
Creates and returns an enumeration that traverses the subtree rooted at this node in postorder. The first node returned by the enumeration's nextElement() method is the leftmost leaf. This is the same as a depth-first traversal.

Modifying the tree by inserting, removing, or moving a node invalidates any enumerations created before the modification.

Returns:
an enumeration for traversing the tree in postorder
See Also:
depthFirstEnumeration(), preorderEnumeration()

breadthFirstEnumeration

public Enumeration breadthFirstEnumeration()
Creates and returns an enumeration that traverses the subtree rooted at this node in breadth-first order. The first node returned by the enumeration's nextElement() method is this node.

Modifying the tree by inserting, removing, or moving a node invalidates any enumerations created before the modification.

Returns:
an enumeration for traversing the tree in breadth-first order
See Also:
depthFirstEnumeration()

depthFirstEnumeration

public Enumeration depthFirstEnumeration()
Creates and returns an enumeration that traverses the subtree rooted at this node in depth-first order. The first node returned by the enumeration's nextElement() method is the leftmost leaf. This is the same as a postorder traversal.

Modifying the tree by inserting, removing, or moving a node invalidates any enumerations created before the modification.

Returns:
an enumeration for traversing the tree in depth-first order
See Also:
breadthFirstEnumeration(), postorderEnumeration()

pathFromAncestorEnumeration

public Enumeration pathFromAncestorEnumeration(TreeNode ancestor)
Creates and returns an enumeration that follows the path from ancestor to this node. The enumeration's nextElement() method first returns ancestor, then the child of ancestor that is an ancestor of this node, and so on, and finally returns this node. Creation of the enumeration is O(m) where m is the number of nodes between this node and ancestor, inclusive. Each nextElement() message is O(1).

Modifying the tree by inserting, removing, or moving a node invalidates any enumerations created before the modification.

Returns:
an enumeration for following the path from an ancestor of this node to this one
Throws:
IllegalArgumentException - if ancestor is not an ancestor of this node
See Also:
isNodeAncestor(javax.swing.tree.TreeNode), isNodeDescendant(javax.swing.tree.DefaultMutableTreeNode)

isNodeChild

public boolean isNodeChild(TreeNode aNode)
Returns true if aNode is a child of this node. If aNode is null, this method returns false.

Returns:
true if aNode is a child of this node; false if aNode is null

getFirstChild

public TreeNode getFirstChild()
Returns this node's first child. If this node has no children, throws NoSuchElementException.

Returns:
the first child of this node
Throws:
NoSuchElementException - if this node has no children

getLastChild

public TreeNode getLastChild()
Returns this node's last child. If this node has no children, throws NoSuchElementException.

Returns:
the last child of this node
Throws:
NoSuchElementException - if this node has no children

getChildAfter

public TreeNode getChildAfter(TreeNode aChild)
Returns the child in this node's child array that immediately follows aChild, which must be a child of this node. If aChild is the last child, returns null. This method performs a linear search of this node's children for aChild and is O(n) where n is the number of children; to traverse the entire array of children, use an enumeration instead.

Returns:
the child of this node that immediately follows aChild
Throws:
IllegalArgumentException - if aChild is null or is not a child of this node
See Also:
children

getChildBefore

public TreeNode getChildBefore(TreeNode aChild)
Returns the child in this node's child array that immediately precedes aChild, which must be a child of this node. If aChild is the first child, returns null. This method performs a linear search of this node's children for aChild and is O(n) where n is the number of children.

Returns:
the child of this node that immediately precedes aChild
Throws:
IllegalArgumentException - if aChild is null or is not a child of this node

isNodeSibling

public boolean isNodeSibling(TreeNode anotherNode)
Returns true if anotherNode is a sibling of (has the same parent as) this node. A node is its own sibling. If anotherNode is null, returns false.

Parameters:
anotherNode - node to test as sibling of this node
Returns:
true if anotherNode is a sibling of this node

getSiblingCount

public int getSiblingCount()
Returns the number of siblings of this node. A node is its own sibling (if it has no parent or no siblings, this method returns 1).

Returns:
the number of siblings of this node

getNextSibling

public DefaultMutableTreeNode getNextSibling()
Returns the next sibling of this node in the parent's children array. Returns null if this node has no parent or is the parent's last child. This method performs a linear search that is O(n) where n is the number of children; to traverse the entire array, use the parent's child enumeration instead.

Returns:
the sibling of this node that immediately follows this node
See Also:
children

getPreviousSibling

public DefaultMutableTreeNode getPreviousSibling()
Returns the previous sibling of this node in the parent's children array. Returns null if this node has no parent or is the parent's first child. This method performs a linear search that is O(n) where n is the number of children.

Returns:
the sibling of this node that immediately precedes this node

isLeaf

public boolean isLeaf()
Returns true if this node has no children. To distinguish between nodes that have no children and nodes that cannot have children (e.g. to distinguish files from empty directories), use this method in conjunction with getAllowsChildren

Specified by:
isLeaf in interface TreeNode
Returns:
true if this node has no children
See Also:
getAllowsChildren()

getFirstLeaf

public DefaultMutableTreeNode getFirstLeaf()
Finds and returns the first leaf that is a descendant of this node -- either this node or its first child's first leaf. Returns this node if it is a leaf.

Returns:
the first leaf in the subtree rooted at this node
See Also:
isLeaf(), isNodeDescendant(javax.swing.tree.DefaultMutableTreeNode)

getLastLeaf

public DefaultMutableTreeNode getLastLeaf()
Finds and returns the last leaf that is a descendant of this node -- either this node or its last child's last leaf. Returns this node if it is a leaf.

Returns:
the last leaf in the subtree rooted at this node
See Also:
isLeaf(), isNodeDescendant(javax.swing.tree.DefaultMutableTreeNode)

getNextLeaf

public DefaultMutableTreeNode getNextLeaf()
Returns the leaf after this node or null if this node is the last leaf in the tree.

In this implementation of the MutableNode interface, this operation is very inefficient. In order to determine the next node, this method first performs a linear search in the parent's child-list in order to find the current node.

That implementation makes the operation suitable for short traversals from a known position. But to traverse all of the leaves in the tree, you should use depthFirstEnumeration to enumerate the nodes in the tree and use isLeaf on each node to determine which are leaves.

Returns:
returns the next leaf past this node
See Also:
depthFirstEnumeration(), isLeaf()

getPreviousLeaf

public DefaultMutableTreeNode getPreviousLeaf()
Returns the leaf before this node or null if this node is the first leaf in the tree.

In this implementation of the MutableNode interface, this operation is very inefficient. In order to determine the previous node, this method first performs a linear search in the parent's child-list in order to find the current node.

That implementation makes the operation suitable for short traversals from a known position. But to traverse all of the leaves in the tree, you should use depthFirstEnumeration to enumerate the nodes in the tree and use isLeaf on each node to determine which are leaves.

Returns:
returns the leaf before this node
See Also:
depthFirstEnumeration(), isLeaf()

getLeafCount

public int getLeafCount()
Returns the total number of leaves that are descendants of this node. If this node is a leaf, returns 1. This method is O(n) where n is the number of descendants of this node.

Returns:
the number of leaves beneath this node
See Also:
isNodeAncestor(javax.swing.tree.TreeNode)

toString

public String toString()
Returns the result of sending toString() to this node's user object, or null if this node has no user object.

Overrides:
toString in class Object
Returns:
a string representation of the object.
See Also:
getUserObject()

clone

public Object clone()
Overridden to make clone public. Returns a shallow copy of this node; the new node has no parent or children and has a reference to the same user object, if any.

Overrides:
clone in class Object
Returns:
a copy of this node
See Also:
Cloneable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultTreeCellEditor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Class DefaultTreeCellEditor

java.lang.Object
    extended by  javax.swing.tree.DefaultTreeCellEditor
All Implemented Interfaces:
ActionListener, EventListener, CellEditor, TreeSelectionListener, TreeCellEditor
public class DefaultTreeCellEditor
extends Object
implements ActionListener, TreeCellEditor, TreeSelectionListener

A TreeCellEditor. You need to supply an instance of DefaultTreeCellRenderer so that the icons can be obtained. You can optionally supply a TreeCellEditor that will be layed out according to the icon in the DefaultTreeCellRenderer. If you do not supply a TreeCellEditor, a TextField will be used. Editing is started on a triple mouse click, or after a click, pause, click and a delay of 1200 miliseconds.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JTree

Nested Class Summary
class | DefaultTreeCellEditor.DefaultTextField TextField used when no editor is supplied.
class | DefaultTreeCellEditor.EditorContainer Container responsible for placing the editingComponent.
Field Summary
protected Color | borderSelectionColor True if the border selection color should be drawn.
protected boolean | canEdit As of Java 2 platform v1.4 this field should no longer be used.
protected Component | editingComponent Component used in editing, obtained from the editingContainer.
protected Container | editingContainer Editing container, will contain the editorComponent.
protected Icon | editingIcon Icon to use when editing.
protected Font | font Font to paint with, null indicates font of renderer is to be used.
protected TreePath | lastPath Last path that was selected.
protected int | lastRow Row that was last passed into getTreeCellEditorComponent.
protected int | offset Used in editing.
protected TreeCellEditor | realEditor Editor handling the editing.
protected DefaultTreeCellRenderer | renderer Renderer, used to get border and offsets from.
protected Timer | timer Used before starting the editing session.
protected JTree | tree JTree instance listening too.
Constructor Summary
DefaultTreeCellEditor(JTree tree, DefaultTreeCellRenderer renderer)
Constructs a DefaultTreeCellEditor object for a JTree using the specified renderer and a default editor.
DefaultTreeCellEditor(JTree tree, DefaultTreeCellRenderer renderer, TreeCellEditor editor)
Constructs a DefaultTreeCellEditor object for a JTree using the specified renderer and the specified editor.
Method Summary
 void actionPerformed(ActionEvent e)
Messaged when the timer fires, this will start the editing session.
 void addCellEditorListener(CellEditorListener l)
Adds the CellEditorListener.
 void cancelCellEditing()
Messages cancelCellEditing to the realEditor and removes it from this instance.
protected  boolean canEditImmediately(EventObject event)
Returns true if event is null, or it is a MouseEvent with a click count > 2 and inHitRegion returns true.
protected  Container createContainer()
Creates the container to manage placement of editingComponent.
protected  TreeCellEditor createTreeCellEditor()
This is invoked if a TreeCellEditor is not supplied in the constructor.
protected  void determineOffset(JTree tree, Object value, boolean isSelected, boolean expanded, boolean leaf, int row)
 Color getBorderSelectionColor()
Returns the color the border is drawn.
 CellEditorListener[] getCellEditorListeners()
Returns an array of all the CellEditorListeners added to this DefaultTreeCellEditor with addCellEditorListener().
 Object getCellEditorValue()
Returns the value currently being edited.
 Font getFont()
Gets the font used for editing.
 Component getTreeCellEditorComponent(JTree tree, Object value, boolean isSelected, boolean expanded, boolean leaf, int row)
Configures the editor.
protected  boolean inHitRegion(int x, int y)
Returns true if the passed in location is a valid mouse location to start editing from.
 boolean isCellEditable(EventObject event)
If the realEditor returns true to this message, prepareForEditing is messaged and true is returned.
protected  void prepareForEditing()
Invoked just before editing is to start.
 void removeCellEditorListener(CellEditorListener l)
Removes the previously added CellEditorListener.
 void setBorderSelectionColor(Color newColor)
Sets the color to use for the border.
 void setFont(Font font)
Sets the font to edit with.
protected  void setTree(JTree newTree)
Sets the tree currently editing for.
 boolean shouldSelectCell(EventObject event)
Messages the realEditor for the return value.
protected  boolean shouldStartEditingTimer(EventObject event)
Returns true if event is a MouseEvent and the click count is 1.
protected  void startEditingTimer()
Starts the editing timer.
 boolean stopCellEditing()
If the realEditor will allow editing to stop, the realEditor is removed and true is returned, otherwise false is returned.
 void valueChanged(TreeSelectionEvent e)
Resets lastPath.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

realEditor

protected TreeCellEditor realEditor
Editor handling the editing.

renderer

protected DefaultTreeCellRenderer renderer
Renderer, used to get border and offsets from.

editingContainer

protected Container editingContainer
Editing container, will contain the editorComponent.

editingComponent

protected transient Component editingComponent
Component used in editing, obtained from the editingContainer.

canEdit

protected boolean canEdit
As of Java 2 platform v1.4 this field should no longer be used. If you wish to provide similar behavior you should directly override isCellEditable.

offset

protected transient int offset
Used in editing. Indicates x position to place editingComponent.

tree

protected transient JTree tree
JTree instance listening too.

lastPath

protected transient TreePath lastPath
Last path that was selected.

timer

protected transient Timer timer
Used before starting the editing session.

lastRow

protected transient int lastRow
Row that was last passed into getTreeCellEditorComponent.

borderSelectionColor

protected Color borderSelectionColor
True if the border selection color should be drawn.

editingIcon

protected transient Icon editingIcon
Icon to use when editing.

font

protected Font font
Font to paint with, null indicates font of renderer is to be used.

Constructor Detail

DefaultTreeCellEditor

public DefaultTreeCellEditor(JTree tree,
                             DefaultTreeCellRenderer renderer)
Constructs a DefaultTreeCellEditor object for a JTree using the specified renderer and a default editor. (Use this constructor for normal editing.)

Parameters:
tree - a JTree object
renderer - a DefaultTreeCellRenderer object

DefaultTreeCellEditor

public DefaultTreeCellEditor(JTree tree,
                             DefaultTreeCellRenderer renderer,
                             TreeCellEditor editor)
Constructs a DefaultTreeCellEditor object for a JTree using the specified renderer and the specified editor. (Use this constructor for specialized editing.)

Parameters:
tree - a JTree object
renderer - a DefaultTreeCellRenderer object
editor - a TreeCellEditor object
Method Detail

setBorderSelectionColor

public void setBorderSelectionColor(Color newColor)
Sets the color to use for the border.

Parameters:
newColor - the new border color

getBorderSelectionColor

public Color getBorderSelectionColor()
Returns the color the border is drawn.

Returns:
the border selection color

setFont

public void setFont(Font font)
Sets the font to edit with. null indicates the renderers font should be used. This will NOT override any font you have set in the editor the receiver was instantied with. If null for an editor was passed in a default editor will be created that will pick up this font.

Parameters:
font - the editing Font
See Also:
getFont()

getFont

public Font getFont()
Gets the font used for editing.

Returns:
the editing Font
See Also:
setFont(java.awt.Font)

getTreeCellEditorComponent

public Component getTreeCellEditorComponent(JTree tree,
                                            Object value,
                                            boolean isSelected,
                                            boolean expanded,
                                            boolean leaf,
                                            int row)
Configures the editor. Passed onto the realEditor.

Specified by:
getTreeCellEditorComponent in interface TreeCellEditor
Parameters:
tree - the JTree that is asking the editor to edit; this parameter can be null
value - the value of the cell to be edited
isSelected - true if the cell is to be rendered with selection highlighting
expanded - true if the node is expanded
leaf - true if the node is a leaf node
row - the row index of the node being edited
Returns:
the component for editing

getCellEditorValue

public Object getCellEditorValue()
Returns the value currently being edited.

Specified by:
getCellEditorValue in interface CellEditor
Returns:
the value currently being edited

isCellEditable

public boolean isCellEditable(EventObject event)
If the realEditor returns true to this message, prepareForEditing is messaged and true is returned.

Specified by:
isCellEditable in interface CellEditor
Parameters:
event - the event the editor should use to consider whether to begin editing or not
Returns:
true if editing can be started
See Also:
CellEditor.shouldSelectCell(java.util.EventObject)

shouldSelectCell

public boolean shouldSelectCell(EventObject event)
Messages the realEditor for the return value.

Specified by:
shouldSelectCell in interface CellEditor
Parameters:
event - the event the editor should use to start editing
Returns:
true if the editor would like the editing cell to be selected; otherwise returns false
See Also:
CellEditor.isCellEditable(java.util.EventObject)

stopCellEditing

public boolean stopCellEditing()
If the realEditor will allow editing to stop, the realEditor is removed and true is returned, otherwise false is returned.

Specified by:
stopCellEditing in interface CellEditor
Returns:
true if editing was stopped; false otherwise

cancelCellEditing

public void cancelCellEditing()
Messages cancelCellEditing to the realEditor and removes it from this instance.

Specified by:
cancelCellEditing in interface CellEditor

addCellEditorListener

public void addCellEditorListener(CellEditorListener l)
Adds the CellEditorListener.

Specified by:
addCellEditorListener in interface CellEditor
Parameters:
l - the listener to be added

removeCellEditorListener

public void removeCellEditorListener(CellEditorListener l)
Removes the previously added CellEditorListener.

Specified by:
removeCellEditorListener in interface CellEditor
Parameters:
l - the listener to be removed

getCellEditorListeners

public CellEditorListener[] getCellEditorListeners()
Returns an array of all the CellEditorListeners added to this DefaultTreeCellEditor with addCellEditorListener().

Returns:
all of the CellEditorListeners added or an empty array if no listeners have been added
Since:
1.4

valueChanged

public void valueChanged(TreeSelectionEvent e)
Resets lastPath.

Specified by:
valueChanged in interface TreeSelectionListener
Parameters:
e - the event that characterizes the change.

actionPerformed

public void actionPerformed(ActionEvent e)
Messaged when the timer fires, this will start the editing session.

Specified by:
actionPerformed in interface ActionListener

setTree

protected void setTree(JTree newTree)
Sets the tree currently editing for. This is needed to add a selection listener.

Parameters:
newTree - the new tree to be edited

shouldStartEditingTimer

protected boolean shouldStartEditingTimer(EventObject event)
Returns true if event is a MouseEvent and the click count is 1.

Parameters:
event - the event being studied

startEditingTimer

protected void startEditingTimer()
Starts the editing timer.

canEditImmediately

protected boolean canEditImmediately(EventObject event)
Returns true if event is null, or it is a MouseEvent with a click count > 2 and inHitRegion returns true.

Parameters:
event - the event being studied

inHitRegion

protected boolean inHitRegion(int x,
                              int y)
Returns true if the passed in location is a valid mouse location to start editing from. This is implemented to return false if x is <= the="the" width="width" of="of" the="the" icon="icon" and="and" icon="icon" gap="gap" displayed="displayed" by="by" the="the" renderer.="renderer." In="In" other="other" words="words" this="this" returns="returns" true="true" if="if" the="the" user="user" clicks="clicks" over="over" the="the" text="text" part="part" displayed="displayed" by="by" the="the" renderer,="renderer," and="and" false="false" otherwise.="otherwise."
Parameters:
x - the x-coordinate of the point
y - the y-coordinate of the point
Returns:
true if the passed in location is a valid mouse location

determineOffset

protected void determineOffset(JTree tree,
                               Object value,
                               boolean isSelected,
                               boolean expanded,
                               boolean leaf,
                               int row)

prepareForEditing

protected void prepareForEditing()
Invoked just before editing is to start. Will add the editingComponent to the editingContainer.

createContainer

protected Container createContainer()
Creates the container to manage placement of editingComponent.

createTreeCellEditor

protected TreeCellEditor createTreeCellEditor()
This is invoked if a TreeCellEditor is not supplied in the constructor. It returns a TextField editor.

Returns:
a new TextField editor
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultTreeCellEditor.DefaultTextField

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Class DefaultTreeCellEditor.DefaultTextField

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.text.JTextComponent
                    extended by  javax.swing.JTextField
                        extended by  javax.swing.tree.DefaultTreeCellEditor.DefaultTextField
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable, SwingConstants
Enclosing class:
DefaultTreeCellEditor
public class DefaultTreeCellEditor.DefaultTextField
extends JTextField

TextField used when no editor is supplied. This textfield locks into the border it is constructed with. It also prefers its parents font over its font. And if the renderer is not null and no font has been specified the preferred height is that of the renderer.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JTextField
JTextField.AccessibleJTextField
Nested classes/interfaces inherited from class javax.swing.text.JTextComponent
JTextComponent.AccessibleJTextComponent, JTextComponent.DropLocation, JTextComponent.KeyBinding
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected  Border border
Border to use.
Fields inherited from class javax.swing.JTextField
notifyAction
Fields inherited from class javax.swing.text.JTextComponent
DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEY
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
DefaultTreeCellEditor.DefaultTextField(Border border)
Constructs a DefaultTreeCellEditor.DefaultTextField object.
Method Summary
Border | getBorder() Overrides JComponent.getBorder to returns the current border.
Font | getFont() Gets the font of this component.
Dimension | getPreferredSize() Overrides JTextField.getPreferredSize to return the preferred size based on current font, if set, or else use renderer's font.
void | setBorder(Border border) Sets the border of this component.
Methods inherited from class javax.swing.JTextField
actionPropertyChanged, addActionListener, configurePropertiesFromAction, createActionPropertyChangeListener, createDefaultModel, fireActionPerformed, getAccessibleContext, getAction, getActionListeners, getActions, getColumns, getColumnWidth, getHorizontalAlignment, getHorizontalVisibility, getScrollOffset, getUIClassID, isValidateRoot, paramString, postActionEvent, removeActionListener, scrollRectToVisible, setAction, setActionCommand, setColumns, setDocument, setFont, setHorizontalAlignment, setScrollOffset
Methods inherited from class javax.swing.text.JTextComponent
addCaretListener, addInputMethodListener, addKeymap, copy, cut, fireCaretUpdate, getCaret, getCaretColor, getCaretListeners, getCaretPosition, getDisabledTextColor, getDocument, getDragEnabled, getDropLocation, getDropMode, getFocusAccelerator, getHighlighter, getInputMethodRequests, getKeymap, getKeymap, getMargin, getNavigationFilter, getPreferredScrollableViewportSize, getPrintable, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getScrollableUnitIncrement, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getText, getToolTipText, getUI, isEditable, loadKeymap, modelToView, moveCaretPosition, paste, print, print, print, processInputMethodEvent, read, removeCaretListener, removeKeymap, removeNotify, replaceSelection, select, selectAll, setCaret, setCaretColor, setCaretPosition, setComponentOrientation, setDisabledTextColor, setDragEnabled, setDropMode, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, setUI, updateUI, viewToModel, write
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

border

protected Border border
Border to use.

Constructor Detail

DefaultTreeCellEditor.DefaultTextField

public DefaultTreeCellEditor.DefaultTextField(Border border)
Constructs a DefaultTreeCellEditor.DefaultTextField object.

Parameters:
border - a Border object
Since:
1.4
Method Detail

setBorder

public void setBorder(Border border)
Sets the border of this component.

This is a bound property.

Overrides:
setBorder in class JComponent
Parameters:
border - the border to be rendered for this component
See Also:
Border, CompoundBorder

getBorder

public Border getBorder()
Overrides JComponent.getBorder to returns the current border.

Overrides:
getBorder in class JComponent
Returns:
the border object for this component
See Also:
JComponent.setBorder(javax.swing.border.Border)

getFont

public Font getFont()
Description copied from class: Component
Gets the font of this component.

Specified by:
getFont in interface MenuContainer
Overrides:
getFont in class Component
Returns:
this component's font; if a font has not been set for this component, the font of its parent is returned
See Also:
Component.setFont(java.awt.Font)

getPreferredSize

public Dimension getPreferredSize()
Overrides JTextField.getPreferredSize to return the preferred size based on current font, if set, or else use renderer's font.

Overrides:
getPreferredSize in class JTextField
Returns:
a Dimension object containing the preferred size
See Also:
JComponent.setPreferredSize(java.awt.Dimension), ComponentUI
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultTreeCellEditor.EditorContainer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Class DefaultTreeCellEditor.EditorContainer

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.tree.DefaultTreeCellEditor.EditorContainer
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable
Enclosing class:
DefaultTreeCellEditor
public class DefaultTreeCellEditor.EditorContainer
extends Container

Container responsible for placing the editingComponent.

Nested Class Summary
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
DefaultTreeCellEditor.EditorContainer()
Constructs an EditorContainer object.
Method Summary
void | doLayout() Lays out this Container.
void | EditorContainer()
Dimension | getPreferredSize() Returns the preferred size for the Container.
void | paint(Graphics g) Overrides Container.paint to paint the node's icon and use the selection color for the background.
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addNotify, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, findComponentAt, findComponentAt, getAlignmentX, getAlignmentY, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getInsets, getLayout, getListeners, getMaximumSize, getMinimumSize, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, paramString, preferredSize, print, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, removeNotify, setComponentZOrder, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setFont, setLayout, transferFocusBackward, transferFocusDownCycle, update, validate, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAccessibleContext, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeysEnabled, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DefaultTreeCellEditor.EditorContainer

public DefaultTreeCellEditor.EditorContainer()
Constructs an EditorContainer object.

Method Detail

EditorContainer

public void EditorContainer()

paint

public void paint(Graphics g)
Overrides Container.paint to paint the node's icon and use the selection color for the background.

Overrides:
paint in class Container
Parameters:
g - the specified Graphics window
See Also:
Component.update(Graphics)

doLayout

public void doLayout()
Lays out this Container. If editing, the editor will be placed at offset in the x direction and 0 for y.

Overrides:
doLayout in class Container
See Also:
LayoutManager.layoutContainer(java.awt.Container),
Container.setLayout(java.awt.LayoutManager),
Container.validate()

getPreferredSize

public Dimension getPreferredSize()
Returns the preferred size for the Container. This will be at least preferred size of the editor plus offset.

Overrides:
getPreferredSize in class Container
Returns:
a Dimension containing the preferred size for the Container; if editingComponent is null the Dimension returned is 0, 0
See Also:
Container.getMinimumSize(),
Container.getMaximumSize(),
Container.getLayout(),
LayoutManager.preferredLayoutSize(Container),
Component.getPreferredSize()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultTreeCellRenderer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Class DefaultTreeCellRenderer

java.lang.Object
    extended by  java.awt.Component
        extended by  java.awt.Container
            extended by  javax.swing.JComponent
                extended by  javax.swing.JLabel
                    extended by  javax.swing.tree.DefaultTreeCellRenderer
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, SwingConstants, TreeCellRenderer
public class DefaultTreeCellRenderer
extends JLabel
implements TreeCellRenderer

Displays an entry in a tree. DefaultTreeCellRenderer is not opaque and unless you subclass paint you should not change this. See How to Use Trees in The Java Tutorial for examples of customizing node display using this class.

Implementation Note: This class overrides invalidate, validate, revalidate, repaint, and firePropertyChange solely to improve performance. If not overridden, these frequently called methods would execute code paths that are unnecessary for the default tree cell renderer. If you write your own renderer, take care to weigh the benefits and drawbacks of overriding these methods.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.JLabel
JLabel.AccessibleJLabel
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
Field Summary
protected Color | backgroundNonSelectionColor Color to use for the background when the node isn't selected.
protected Color | backgroundSelectionColor Color to use for the background when a node is selected.
protected Color | borderSelectionColor Color to use for the focus indicator when the node has focus.
protected Icon | closedIcon Icon used to show non-leaf nodes that aren't expanded.
protected boolean | hasFocus True if has focus.
protected Icon | leafIcon Icon used to show leaf nodes.
protected Icon | openIcon Icon used to show non-leaf nodes that are expanded.
protected boolean | selected Is the value currently selected.
protected Color | textNonSelectionColor Color to use for the foreground for non-selected nodes.
protected Color | textSelectionColor Color to use for the foreground for selected nodes.
Fields inherited from class javax.swing.JLabel
labelFor
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
Constructor Summary
DefaultTreeCellRenderer()
Returns a new instance of DefaultTreeCellRenderer.
Method Summary
void | firePropertyChange(String propertyName, boolean oldValue, boolean newValue) Overridden for performance reasons.
void | firePropertyChange(String propertyName, byte oldValue, byte newValue) Overridden for performance reasons.
void | firePropertyChange(String propertyName, char oldValue, char newValue) Overridden for performance reasons.
void | firePropertyChange(String propertyName, double oldValue, double newValue) Overridden for performance reasons.
void | firePropertyChange(String propertyName, float oldValue, float newValue) Overridden for performance reasons.
void | firePropertyChange(String propertyName, int oldValue, int newValue) Overridden for performance reasons.
void | firePropertyChange(String propertyName, long oldValue, long newValue) Overridden for performance reasons.
protected void | firePropertyChange(String propertyName, Object oldValue, Object newValue) Overridden for performance reasons.
void | firePropertyChange(String propertyName, short oldValue, short newValue) Overridden for performance reasons.
Color | getBackgroundNonSelectionColor() Returns the background color to be used for non selected nodes.
Color | getBackgroundSelectionColor() Returns the color to use for the background if node is selected.
Color | getBorderSelectionColor() Returns the color the border is drawn.
Icon | getClosedIcon() Returns the icon used to represent non-leaf nodes that are not expanded.
Icon | getDefaultClosedIcon() Returns the default icon, for the current laf, that is used to represent non-leaf nodes that are not expanded.
Icon | getDefaultLeafIcon() Returns the default icon, for the current laf, that is used to represent leaf nodes.
Icon | getDefaultOpenIcon() Returns the default icon, for the current laf, that is used to represent non-leaf nodes that are expanded.
Font | getFont() Gets the font of this component.
Icon | getLeafIcon() Returns the icon used to represent leaf nodes.
Icon | getOpenIcon() Returns the icon used to represent non-leaf nodes that are expanded.
Dimension | getPreferredSize() Overrides JComponent.getPreferredSize to return slightly wider preferred size value.
Color | getTextNonSelectionColor() Returns the color the text is drawn with when the node isn't selected.
Color | getTextSelectionColor() Returns the color the text is drawn with when the node is selected.
Component | getTreeCellRendererComponent(JTree tree, Object value, boolean sel, boolean expanded, boolean leaf, int row, boolean hasFocus) Configures the renderer based on the passed in components.
void | invalidate() Overridden for performance reasons.
void | paint(Graphics g) Paints the value.
void | repaint() Overridden for performance reasons.
void | repaint(long tm, int x, int y, int width, int height) Overridden for performance reasons.
void | repaint(Rectangle r) Overridden for performance reasons.
void | revalidate() Overridden for performance reasons.
void | setBackground(Color color) Subclassed to map ColorUIResources to null.
void | setBackgroundNonSelectionColor(Color newColor) Sets the background color to be used for non selected nodes.
void | setBackgroundSelectionColor(Color newColor) Sets the color to use for the background if node is selected.
void | setBorderSelectionColor(Color newColor) Sets the color to use for the border.
void | setClosedIcon(Icon newIcon) Sets the icon used to represent non-leaf nodes that are not expanded.
void | setFont(Font font) Subclassed to map FontUIResources to null.
void | setLeafIcon(Icon newIcon) Sets the icon used to represent leaf nodes.
void | setOpenIcon(Icon newIcon) Sets the icon used to represent non-leaf nodes that are expanded.
void | setTextNonSelectionColor(Color newColor) Sets the color the text is drawn with when the node isn't selected.
void | setTextSelectionColor(Color newColor) Sets the color the text is drawn with when the node is selected.
void | validate() Overridden for performance reasons.
Methods inherited from class javax.swing.JLabel
checkHorizontalKey, checkVerticalKey, getAccessibleContext, getDisabledIcon, getDisplayedMnemonic, getDisplayedMnemonicIndex, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getLabelFor, getText, getUI, getUIClassID, getVerticalAlignment, getVerticalTextPosition, imageUpdate, paramString, setDisabledIcon, setDisplayedMnemonic, setDisplayedMnemonic, setDisplayedMnemonicIndex, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabelFor, setText, setUI, setVerticalAlignment, setVerticalTextPosition, updateUI
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validateTree
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

selected

protected boolean selected
Is the value currently selected.

hasFocus

protected boolean hasFocus
True if has focus.

closedIcon

protected transient Icon closedIcon
Icon used to show non-leaf nodes that aren't expanded.

leafIcon

protected transient Icon leafIcon
Icon used to show leaf nodes.

openIcon

protected transient Icon openIcon
Icon used to show non-leaf nodes that are expanded.

textSelectionColor

protected Color textSelectionColor
Color to use for the foreground for selected nodes.

textNonSelectionColor

protected Color textNonSelectionColor
Color to use for the foreground for non-selected nodes.

backgroundSelectionColor

protected Color backgroundSelectionColor
Color to use for the background when a node is selected.

backgroundNonSelectionColor

protected Color backgroundNonSelectionColor
Color to use for the background when the node isn't selected.

borderSelectionColor

protected Color borderSelectionColor
Color to use for the focus indicator when the node has focus.

Constructor Detail

DefaultTreeCellRenderer

public DefaultTreeCellRenderer()
Returns a new instance of DefaultTreeCellRenderer. Alignment is set to left aligned. Icons and text color are determined from the UIManager.

Method Detail

getDefaultOpenIcon

public Icon getDefaultOpenIcon()
Returns the default icon, for the current laf, that is used to represent non-leaf nodes that are expanded.

getDefaultClosedIcon

public Icon getDefaultClosedIcon()
Returns the default icon, for the current laf, that is used to represent non-leaf nodes that are not expanded.

getDefaultLeafIcon

public Icon getDefaultLeafIcon()
Returns the default icon, for the current laf, that is used to represent leaf nodes.

setOpenIcon

public void setOpenIcon(Icon newIcon)
Sets the icon used to represent non-leaf nodes that are expanded.

getOpenIcon

public Icon getOpenIcon()
Returns the icon used to represent non-leaf nodes that are expanded.

setClosedIcon

public void setClosedIcon(Icon newIcon)
Sets the icon used to represent non-leaf nodes that are not expanded.

getClosedIcon

public Icon getClosedIcon()
Returns the icon used to represent non-leaf nodes that are not expanded.

setLeafIcon

public void setLeafIcon(Icon newIcon)
Sets the icon used to represent leaf nodes.

getLeafIcon

public Icon getLeafIcon()
Returns the icon used to represent leaf nodes.

setTextSelectionColor

public void setTextSelectionColor(Color newColor)
Sets the color the text is drawn with when the node is selected.

getTextSelectionColor

public Color getTextSelectionColor()
Returns the color the text is drawn with when the node is selected.

setTextNonSelectionColor

public void setTextNonSelectionColor(Color newColor)
Sets the color the text is drawn with when the node isn't selected.

getTextNonSelectionColor

public Color getTextNonSelectionColor()
Returns the color the text is drawn with when the node isn't selected.

setBackgroundSelectionColor

public void setBackgroundSelectionColor(Color newColor)
Sets the color to use for the background if node is selected.

getBackgroundSelectionColor

public Color getBackgroundSelectionColor()
Returns the color to use for the background if node is selected.

setBackgroundNonSelectionColor

public void setBackgroundNonSelectionColor(Color newColor)
Sets the background color to be used for non selected nodes.

getBackgroundNonSelectionColor

public Color getBackgroundNonSelectionColor()
Returns the background color to be used for non selected nodes.

setBorderSelectionColor

public void setBorderSelectionColor(Color newColor)
Sets the color to use for the border.

getBorderSelectionColor

public Color getBorderSelectionColor()
Returns the color the border is drawn.

setFont

public void setFont(Font font)
Subclassed to map FontUIResources to null. If font is null, or a FontUIResource, this has the effect of letting the font of the JTree show through. On the other hand, if font is non-null, and not a FontUIResource, the font becomes font.

Overrides:
setFont in class JComponent
Parameters:
font - the desired Font for this component
See Also:
Component.getFont()

getFont

public Font getFont()
Gets the font of this component.

Specified by:
getFont in interface MenuContainer
Overrides:
getFont in class Component
Returns:
this component's font; if a font has not been set for this component, the font of its parent is returned
See Also:
Component.setFont(java.awt.Font)

setBackground

public void setBackground(Color color)
Subclassed to map ColorUIResources to null. If color is null, or a ColorUIResource, this has the effect of letting the background color of the JTree show through. On the other hand, if color is non-null, and not a ColorUIResource, the background becomes color.

Overrides:
setBackground in class JComponent
Parameters:
color - the desired background Color
See Also:
Component.getBackground(), JComponent.setOpaque(boolean)

getTreeCellRendererComponent

public Component getTreeCellRendererComponent(JTree tree,
                                              Object value,
                                              boolean sel,
                                              boolean expanded,
                                              boolean leaf,
                                              int row,
                                              boolean hasFocus)
Configures the renderer based on the passed in components. The value is set from messaging the tree with convertValueToText, which ultimately invokes toString on value. The foreground color is set based on the selection and the icon is set based on the leaf and expanded parameters.

Specified by:
getTreeCellRendererComponent in interface TreeCellRenderer
Returns:
the Component that the renderer uses to draw the value

paint

public void paint(Graphics g)
Paints the value. The background is filled based on selected.

Overrides:
paint in class JComponent
Parameters:
g - the Graphics context in which to paint
See Also:
JComponent.paintComponent(java.awt.Graphics),
JComponent.paintBorder(java.awt.Graphics),
JComponent.paintChildren(java.awt.Graphics),
JComponent.getComponentGraphics(java.awt.Graphics),
JComponent.repaint(long, int, int, int, int)

getPreferredSize

public Dimension getPreferredSize()
Overrides JComponent.getPreferredSize to return slightly wider preferred size value.

Overrides:
getPreferredSize in class JComponent
Returns:
the value of the preferredSize property
See Also:
JComponent.setPreferredSize(java.awt.Dimension), ComponentUI

validate

public void validate()
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
validate in class Container
See Also:
Container.add(java.awt.Component),
Component.invalidate(),
JComponent.revalidate(),
Container.validateTree()

invalidate

public void invalidate()
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
invalidate in class Container
Since:
1.5
See Also:
Container.validate(), Container.layout(), LayoutManager, LayoutManager2.invalidateLayout(Container)

revalidate

public void revalidate()
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
revalidate in class JComponent
See Also:
Component.invalidate(),
Container.validate(),
JComponent.isValidateRoot(),
RepaintManager.addInvalidComponent(javax.swing.JComponent)

repaint

public void repaint(long tm,
                    int x,
                    int y,
                    int width,
                    int height)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
repaint in class JComponent
Parameters:
tm - this parameter is not used
x - the x value of the dirty region
y - the y value of the dirty region
width - the width of the dirty region
height - the height of the dirty region
See Also:
Component.isShowing(), RepaintManager.addDirtyRegion(javax.swing.JComponent, int, int, int, int)

repaint

public void repaint(Rectangle r)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
repaint in class JComponent
Parameters:
r - a Rectangle containing the dirty region
See Also:
Component.isShowing(), RepaintManager.addDirtyRegion(javax.swing.JComponent, int, int, int, int)

repaint

public void repaint()
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
repaint in class Component
Since:
1.5
See Also:
Component.update(Graphics)

firePropertyChange

protected void firePropertyChange(String propertyName,
                                  Object oldValue,
                                  Object newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class Component
Parameters:
propertyName - the property whose value has changed
oldValue - the property's previous value
newValue - the property's new value

firePropertyChange

public void firePropertyChange(String propertyName,
                               byte oldValue,
                               byte newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class Component
Parameters:
propertyName - the programmatic name of the property that was changed
oldValue - the old value of the property (as a byte)
newValue - the new value of the property (as a byte)
See Also:
Component.firePropertyChange(java.lang.String, java.lang.Object, java.lang.Object)

firePropertyChange

public void firePropertyChange(String propertyName,
                               char oldValue,
                               char newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class JComponent
Parameters:
propertyName - the programmatic name of the property that was changed
oldValue - the old value of the property (as a char)
newValue - the new value of the property (as a char)
See Also:
Component.firePropertyChange(java.lang.String, java.lang.Object, java.lang.Object)

firePropertyChange

public void firePropertyChange(String propertyName,
                               short oldValue,
                               short newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class Component
Parameters:
propertyName - the programmatic name of the property that was changed
oldValue - the old value of the property (as a short)
newValue - the old value of the property (as a short)
See Also:
Component.firePropertyChange(java.lang.String, java.lang.Object, java.lang.Object)

firePropertyChange

public void firePropertyChange(String propertyName,
                               int oldValue,
                               int newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class JComponent
Parameters:
propertyName - the property whose value has changed
oldValue - the property's previous value
newValue - the property's new value

firePropertyChange

public void firePropertyChange(String propertyName,
                               long oldValue,
                               long newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class Component
Parameters:
propertyName - the programmatic name of the property that was changed
oldValue - the old value of the property (as a long)
newValue - the new value of the property (as a long)
See Also:
Component.firePropertyChange(java.lang.String, java.lang.Object, java.lang.Object)

firePropertyChange

public void firePropertyChange(String propertyName,
                               float oldValue,
                               float newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class Component
Parameters:
propertyName - the programmatic name of the property that was changed
oldValue - the old value of the property (as a float)
newValue - the new value of the property (as a float)
See Also:
Component.firePropertyChange(java.lang.String, java.lang.Object, java.lang.Object)

firePropertyChange

public void firePropertyChange(String propertyName,
                               double oldValue,
                               double newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class Component
Parameters:
propertyName - the programmatic name of the property that was changed
oldValue - the old value of the property (as a double)
newValue - the new value of the property (as a double)
See Also:
Component.firePropertyChange(java.lang.String, java.lang.Object, java.lang.Object)

firePropertyChange

public void firePropertyChange(String propertyName,
                               boolean oldValue,
                               boolean newValue)
Overridden for performance reasons. See the Implementation Note for more information.

Overrides:
firePropertyChange in class JComponent
Parameters:
propertyName - the property whose value has changed
oldValue - the property's previous value
newValue - the property's new value
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultTreeModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Class DefaultTreeModel

java.lang.Object
    extended by  javax.swing.tree.DefaultTreeModel
All Implemented Interfaces:
Serializable, TreeModel
public class DefaultTreeModel
extends Object
implements Serializable, TreeModel

A simple tree data model that uses TreeNodes. For further information and examples that use DefaultTreeModel, see How to Use Trees in The Java Tutorial.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
protected boolean | asksAllowsChildren Determines how the isLeaf method figures out if a node is a leaf node.
protected EventListenerList | listenerList Listeners.
protected TreeNode | root Root of the tree.
Constructor Summary
DefaultTreeModel(TreeNode root)
Creates a tree in which any node can have children.
DefaultTreeModel(TreeNode root, boolean asksAllowsChildren)
Creates a tree specifying whether any node can have children, or whether only certain nodes can have children.
Method Summary
 void addTreeModelListener(TreeModelListener l)
Adds a listener for the TreeModelEvent posted after the tree changes.
 boolean asksAllowsChildren()
Tells how leaf nodes are determined.
protected  void fireTreeNodesChanged(Object source, Object[] path, int[] childIndices, Object[] children)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireTreeNodesInserted(Object source, Object[] path, int[] childIndices, Object[] children)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireTreeNodesRemoved(Object source, Object[] path, int[] childIndices, Object[] children)
Notifies all listeners that have registered interest for notification on this event type.
protected  void fireTreeStructureChanged(Object source, Object[] path, int[] childIndices, Object[] children)
Notifies all listeners that have registered interest for notification on this event type.
 Object getChild(Object parent, int index)
Returns the child of parent at index index in the parent's child array.
 int getChildCount(Object parent)
Returns the number of children of parent.
 int getIndexOfChild(Object parent, Object child)
Returns the index of child in parent.
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this model.
 TreeNode[] getPathToRoot(TreeNode aNode)
Builds the parents of node up to and including the root node, where the original node is the last element in the returned array.
protected  TreeNode[] getPathToRoot(TreeNode aNode, int depth)
Builds the parents of node up to and including the root node, where the original node is the last element in the returned array.
 Object getRoot()
Returns the root of the tree.
 TreeModelListener[] getTreeModelListeners()
Returns an array of all the tree model listeners registered on this model.
 void insertNodeInto(MutableTreeNode newChild, MutableTreeNode parent, int index)
Invoked this to insert newChild at location index in parents children.
 boolean isLeaf(Object node)
Returns whether the specified node is a leaf node.
 void nodeChanged(TreeNode node)
Invoke this method after you've changed how node is to be represented in the tree.
 void nodesChanged(TreeNode node, int[] childIndices)
Invoke this method after you've changed how the children identified by childIndicies are to be represented in the tree.
 void nodeStructureChanged(TreeNode node)
Invoke this method if you've totally changed the children of node and its childrens children...
 void nodesWereInserted(TreeNode node, int[] childIndices)
Invoke this method after you've inserted some TreeNodes into node.
 void nodesWereRemoved(TreeNode node, int[] childIndices, Object[] removedChildren)
Invoke this method after you've removed some TreeNodes from node.
 void reload()
Invoke this method if you've modified the TreeNodes upon which this model depends.
 void reload(TreeNode node)
Invoke this method if you've modified the TreeNodes upon which this model depends.
 void removeNodeFromParent(MutableTreeNode node)
Message this to remove node from its parent.
 void removeTreeModelListener(TreeModelListener l)
Removes a listener previously added with addTreeModelListener().
 void setAsksAllowsChildren(boolean newValue)
Sets whether or not to test leafness by asking getAllowsChildren() or isLeaf() to the TreeNodes.
 void setRoot(TreeNode root)
Sets the root to root.
 void valueForPathChanged(TreePath path, Object newValue)
This sets the user object of the TreeNode identified by path and posts a node changed.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

root

protected TreeNode root
Root of the tree.

listenerList

protected EventListenerList listenerList
Listeners.

asksAllowsChildren

protected boolean asksAllowsChildren
Determines how the isLeaf method figures out if a node is a leaf node. If true, a node is a leaf node if it does not allow children. (If it allows children, it is not a leaf node, even if no children are present.) That lets you distinguish between folder nodes and file nodes in a file system, for example.

If this value is false, then any node which has no children is a leaf node, and any node may acquire children.

See Also:
TreeNode.getAllowsChildren(),
TreeModel.isLeaf(java.lang.Object),
setAsksAllowsChildren(boolean)
Constructor Detail

DefaultTreeModel

public DefaultTreeModel(TreeNode root)
Creates a tree in which any node can have children.

Parameters:
root - a TreeNode object that is the root of the tree
See Also:
DefaultTreeModel(TreeNode, boolean)

DefaultTreeModel

public DefaultTreeModel(TreeNode root,
                        boolean asksAllowsChildren)
Creates a tree specifying whether any node can have children, or whether only certain nodes can have children.

Parameters:
root - a TreeNode object that is the root of the tree
asksAllowsChildren - a boolean, false if any node can have children, true if each node is asked to see if it can have children
See Also:
asksAllowsChildren
Method Detail

setAsksAllowsChildren

public void setAsksAllowsChildren(boolean newValue)
Sets whether or not to test leafness by asking getAllowsChildren() or isLeaf() to the TreeNodes. If newvalue is true, getAllowsChildren() is messaged, otherwise isLeaf() is messaged.

asksAllowsChildren

public boolean asksAllowsChildren()
Tells how leaf nodes are determined.

Returns:
true if only nodes which do not allow children are leaf nodes, false if nodes which have no children (even if allowed) are leaf nodes
See Also:
asksAllowsChildren

setRoot

public void setRoot(TreeNode root)
Sets the root to root. A null root implies the tree is to display nothing, and is legal.

getRoot

public Object getRoot()
Returns the root of the tree. Returns null only if the tree has no nodes.

Specified by:
getRoot in interface TreeModel
Returns:
the root of the tree

getIndexOfChild

public int getIndexOfChild(Object parent,
                           Object child)
Returns the index of child in parent. If either the parent or child is null, returns -1.

Specified by:
getIndexOfChild in interface TreeModel
Parameters:
parent - a note in the tree, obtained from this data source
child - the node we are interested in
Returns:
the index of the child in the parent, or -1 if either the parent or the child is null

getChild

public Object getChild(Object parent,
                       int index)
Returns the child of parent at index index in the parent's child array. parent must be a node previously obtained from this data source. This should not return null if index is a valid index for parent (that is index >= 0 && index < getChildCount(parent)).

Specified by:
getChild in interface TreeModel
Parameters:
parent - a node in the tree, obtained from this data source
Returns:
the child of parent at index index

getChildCount

public int getChildCount(Object parent)
Returns the number of children of parent. Returns 0 if the node is a leaf or if it has no children. parent must be a node previously obtained from this data source.

Specified by:
getChildCount in interface TreeModel
Parameters:
parent - a node in the tree, obtained from this data source
Returns:
the number of children of the node parent

isLeaf

public boolean isLeaf(Object node)
Returns whether the specified node is a leaf node. The way the test is performed depends on the askAllowsChildren setting.

Specified by:
isLeaf in interface TreeModel
Parameters:
node - the node to check
Returns:
true if the node is a leaf node
See Also:
asksAllowsChildren, TreeModel.isLeaf(java.lang.Object)

reload

public void reload()
Invoke this method if you've modified the TreeNodes upon which this model depends. The model will notify all of its listeners that the model has changed.

valueForPathChanged

public void valueForPathChanged(TreePath path,
                                Object newValue)
This sets the user object of the TreeNode identified by path and posts a node changed. If you use custom user objects in the TreeModel you're going to need to subclass this and set the user object of the changed node to something meaningful.

Specified by:
valueForPathChanged in interface TreeModel
Parameters:
path - path to the node that the user has altered
newValue - the new value from the TreeCellEditor

insertNodeInto

public void insertNodeInto(MutableTreeNode newChild,
                           MutableTreeNode parent,
                           int index)
Invoked this to insert newChild at location index in parents children. This will then message nodesWereInserted to create the appropriate event. This is the preferred way to add children as it will create the appropriate event.

removeNodeFromParent

public void removeNodeFromParent(MutableTreeNode node)
Message this to remove node from its parent. This will message nodesWereRemoved to create the appropriate event. This is the preferred way to remove a node as it handles the event creation for you.

nodeChanged

public void nodeChanged(TreeNode node)
Invoke this method after you've changed how node is to be represented in the tree.

reload

public void reload(TreeNode node)
Invoke this method if you've modified the TreeNodes upon which this model depends. The model will notify all of its listeners that the model has changed below the given node.

Parameters:
node - the node below which the model has changed

nodesWereInserted

public void nodesWereInserted(TreeNode node,
                              int[] childIndices)
Invoke this method after you've inserted some TreeNodes into node. childIndices should be the index of the new elements and must be sorted in ascending order.

nodesWereRemoved

public void nodesWereRemoved(TreeNode node,
                             int[] childIndices,
                             Object[] removedChildren)
Invoke this method after you've removed some TreeNodes from node. childIndices should be the index of the removed elements and must be sorted in ascending order. And removedChildren should be the array of the children objects that were removed.

nodesChanged

public void nodesChanged(TreeNode node,
                         int[] childIndices)
Invoke this method after you've changed how the children identified by childIndicies are to be represented in the tree.

nodeStructureChanged

public void nodeStructureChanged(TreeNode node)
Invoke this method if you've totally changed the children of node and its childrens children... This will post a treeStructureChanged event.

getPathToRoot

public TreeNode[] getPathToRoot(TreeNode aNode)
Builds the parents of node up to and including the root node, where the original node is the last element in the returned array. The length of the returned array gives the node's depth in the tree.

Parameters:
aNode - the TreeNode to get the path for

getPathToRoot

protected TreeNode[] getPathToRoot(TreeNode aNode,
                                   int depth)
Builds the parents of node up to and including the root node, where the original node is the last element in the returned array. The length of the returned array gives the node's depth in the tree.

Parameters:
aNode - the TreeNode to get the path for
depth - an int giving the number of steps already taken towards the root (on recursive calls), used to size the returned array
Returns:
an array of TreeNodes giving the path from the root to the specified node

addTreeModelListener

public void addTreeModelListener(TreeModelListener l)
Adds a listener for the TreeModelEvent posted after the tree changes.

Specified by:
addTreeModelListener in interface TreeModel
Parameters:
l - the listener to add
See Also:
removeTreeModelListener(javax.swing.event.TreeModelListener)

removeTreeModelListener

public void removeTreeModelListener(TreeModelListener l)
Removes a listener previously added with addTreeModelListener().

Specified by:
removeTreeModelListener in interface TreeModel
Parameters:
l - the listener to remove
See Also:
addTreeModelListener(javax.swing.event.TreeModelListener)

getTreeModelListeners

public TreeModelListener[] getTreeModelListeners()
Returns an array of all the tree model listeners registered on this model.

Returns:
all of this model's TreeModelListeners or an empty array if no tree model listeners are currently registered
Since:
1.4
See Also:
addTreeModelListener(javax.swing.event.TreeModelListener), removeTreeModelListener(javax.swing.event.TreeModelListener)

fireTreeNodesChanged

protected void fireTreeNodesChanged(Object source,
                                    Object[] path,
                                    int[] childIndices,
                                    Object[] children)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

Parameters:
source - the node being changed
path - the path to the root node
childIndices - the indices of the changed elements
children - the changed elements
See Also:
EventListenerList

fireTreeNodesInserted

protected void fireTreeNodesInserted(Object source,
                                     Object[] path,
                                     int[] childIndices,
                                     Object[] children)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

Parameters:
source - the node where new elements are being inserted
path - the path to the root node
childIndices - the indices of the new elements
children - the new elements
See Also:
EventListenerList

fireTreeNodesRemoved

protected void fireTreeNodesRemoved(Object source,
                                    Object[] path,
                                    int[] childIndices,
                                    Object[] children)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

Parameters:
source - the node where elements are being removed
path - the path to the root node
childIndices - the indices of the removed elements
children - the removed elements
See Also:
EventListenerList

fireTreeStructureChanged

protected void fireTreeStructureChanged(Object source,
                                        Object[] path,
                                        int[] childIndices,
                                        Object[] children)
Notifies all listeners that have registered interest for notification on this event type. The event instance is lazily created using the parameters passed into the fire method.

Parameters:
source - the node where the tree model has changed
path - the path to the root node
childIndices - the indices of the affected elements
children - the affected elements
See Also:
EventListenerList

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this model. FooListeners are registered using the addFooListener method.

You can specify the listenerType argument with a class literal, such as FooListener.class. For example, you can query a DefaultTreeModel m for its tree model listeners with the following code:

TreeModelListener[] tmls = (TreeModelListener[])(m.getListeners(TreeModelListener.class));
If no such listeners exist, this method returns an empty array.

Parameters:
listenerType - the type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener
Returns:
an array of all objects registered as FooListeners on this component, or an empty array if no such listeners have been added
Throws:
ClassCastException - if listenerType doesn't specify a class or interface that implements java.util.EventListener
Since:
1.3
See Also:
getTreeModelListeners()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultTreeSelectionModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Class DefaultTreeSelectionModel

java.lang.Object
    extended by  javax.swing.tree.DefaultTreeSelectionModel
All Implemented Interfaces:
Serializable, Cloneable, TreeSelectionModel
Direct Known Subclasses:
JTree.EmptySelectionModel
public class DefaultTreeSelectionModel
extends Object
implements Cloneable, Serializable, TreeSelectionModel

Default implementation of TreeSelectionModel. Listeners are notified whenever the paths in the selection change, not the rows. In order to be able to track row changes you may wish to become a listener for expansion events on the tree and test for changes from there.

resetRowSelection is called from any of the methods that update the selected paths. If you subclass any of these methods to filter what is allowed to be selected, be sure and message resetRowSelection if you do not message super.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
JTree

Field Summary
protected SwingPropertyChangeSupport | changeSupport Used to messaged registered listeners.
protected int | leadIndex Index of the lead path in selection.
protected TreePath | leadPath Last path that was added.
protected int | leadRow Lead row.
protected EventListenerList | listenerList Event listener list.
protected DefaultListSelectionModel | listSelectionModel Handles maintaining the list selection model.
protected RowMapper | rowMapper Provides a row for a given path.
protected TreePath[] | selection Paths that are currently selected.
static String | SELECTION_MODE_PROPERTY Property name for selectionMode.
protected int | selectionMode Mode for the selection, will be either SINGLE_TREE_SELECTION, CONTIGUOUS_TREE_SELECTION or DISCONTIGUOUS_TREE_SELECTION.
Fields inherited from interface javax.swing.tree.TreeSelectionModel
CONTIGUOUS_TREE_SELECTION, DISCONTIGUOUS_TREE_SELECTION, SINGLE_TREE_SELECTION
Constructor Summary
DefaultTreeSelectionModel()
Creates a new instance of DefaultTreeSelectionModel that is empty, with a selection mode of DISCONTIGUOUS_TREE_SELECTION.
Method Summary
 void addPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list.
 void addSelectionPath(TreePath path)
Adds path to the current selection.
 void addSelectionPaths(TreePath[] paths)
Adds paths to the current selection.
 void addTreeSelectionListener(TreeSelectionListener x)
Adds x to the list of listeners that are notified each time the set of selected TreePaths changes.
protected  boolean arePathsContiguous(TreePath[] paths)
Returns true if the paths are contiguous, or this object has no RowMapper.
protected  boolean canPathsBeAdded(TreePath[] paths)
Used to test if a particular set of TreePaths can be added.
protected  boolean canPathsBeRemoved(TreePath[] paths)
Returns true if the paths can be removed without breaking the continuity of the model.
 void clearSelection()
Empties the current selection.
 Object clone()
Returns a clone of this object with the same selection.
protected  void fireValueChanged(TreeSelectionEvent e)
Notifies all listeners that are registered for tree selection events on this object.
 TreePath getLeadSelectionPath()
Returns the last path that was added.
 int getLeadSelectionRow()
Returns the lead selection index.
<T extends EventListener>
T[]
getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this model.
 int getMaxSelectionRow()
Returns the largest value obtained from the RowMapper for the current set of selected TreePaths.
 int getMinSelectionRow()
Returns the smallest value obtained from the RowMapper for the current set of selected TreePaths.
 PropertyChangeListener[] getPropertyChangeListeners()
Returns an array of all the property change listeners registered on this DefaultTreeSelectionModel.
 RowMapper getRowMapper()
Returns the RowMapper instance that is able to map a TreePath to a row.
 int getSelectionCount()
Returns the number of paths that are selected.
 int getSelectionMode()
Returns the selection mode, one of SINGLE_TREE_SELECTION, DISCONTIGUOUS_TREE_SELECTION or CONTIGUOUS_TREE_SELECTION.
 TreePath getSelectionPath()
Returns the first path in the selection.
 TreePath[] getSelectionPaths()
Returns the paths in the selection.
 int[] getSelectionRows()
Returns all of the currently selected rows.
 TreeSelectionListener[] getTreeSelectionListeners()
Returns an array of all the tree selection listeners registered on this model.
protected  void insureRowContinuity()
Makes sure the currently selected TreePaths are valid for the current selection mode.
protected  void insureUniqueness()
This method is obsolete and its implementation is now a noop.
 boolean isPathSelected(TreePath path)
Returns true if the path, path, is in the current selection.
 boolean isRowSelected(int row)
Returns true if the row identified by row is selected.
 boolean isSelectionEmpty()
Returns true if the selection is currently empty.
protected  void notifyPathChange(Vector<javax.swing.tree.PathPlaceHolder> changedPaths, TreePath oldLeadSelection)
Notifies listeners of a change in path.
 void removePropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list.
 void removeSelectionPath(TreePath path)
Removes path from the selection.
 void removeSelectionPaths(TreePath[] paths)
Removes paths from the selection.
 void removeTreeSelectionListener(TreeSelectionListener x)
Removes x from the list of listeners that are notified each time the set of selected TreePaths changes.
 void resetRowSelection()
Updates this object's mapping from TreePath to rows.
 void setRowMapper(RowMapper newMapper)
Sets the RowMapper instance.
 void setSelectionMode(int mode)
Sets the selection model, which must be one of SINGLE_TREE_SELECTION, CONTIGUOUS_TREE_SELECTION or DISCONTIGUOUS_TREE_SELECTION.
 void setSelectionPath(TreePath path)
Sets the selection to path.
 void setSelectionPaths(TreePath[] pPaths)
Sets the selection to the paths in paths.
 String toString()
Returns a string that displays and identifies this object's properties.
protected  void updateLeadIndex()
Updates the leadIndex instance variable.
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

SELECTION_MODE_PROPERTY

public static final String SELECTION_MODE_PROPERTY
Property name for selectionMode.

See Also:
Constant Field Values

changeSupport

protected SwingPropertyChangeSupport changeSupport
Used to messaged registered listeners.

selection

protected TreePath[] selection
Paths that are currently selected. Will be null if nothing is currently selected.

listenerList

protected EventListenerList listenerList
Event listener list.

rowMapper

protected transient RowMapper rowMapper
Provides a row for a given path.

listSelectionModel

protected DefaultListSelectionModel listSelectionModel
Handles maintaining the list selection model. The RowMapper is used to map from a TreePath to a row, and the value is then placed here.

selectionMode

protected int selectionMode
Mode for the selection, will be either SINGLE_TREE_SELECTION, CONTIGUOUS_TREE_SELECTION or DISCONTIGUOUS_TREE_SELECTION.

leadPath

protected TreePath leadPath
Last path that was added.

leadIndex

protected int leadIndex
Index of the lead path in selection.

leadRow

protected int leadRow
Lead row.

Constructor Detail

DefaultTreeSelectionModel

public DefaultTreeSelectionModel()
Creates a new instance of DefaultTreeSelectionModel that is empty, with a selection mode of DISCONTIGUOUS_TREE_SELECTION.

Method Detail

setRowMapper

public void setRowMapper(RowMapper newMapper)
Sets the RowMapper instance. This instance is used to determine the row for a particular TreePath.

Specified by:
setRowMapper in interface TreeSelectionModel

getRowMapper

public RowMapper getRowMapper()
Returns the RowMapper instance that is able to map a TreePath to a row.

Specified by:
getRowMapper in interface TreeSelectionModel

setSelectionMode

public void setSelectionMode(int mode)
Sets the selection model, which must be one of SINGLE_TREE_SELECTION, CONTIGUOUS_TREE_SELECTION or DISCONTIGUOUS_TREE_SELECTION. If mode is not one of the defined value, DISCONTIGUOUS_TREE_SELECTION is assumed.

This may change the selection if the current selection is not valid for the new mode. For example, if three TreePaths are selected when the mode is changed to SINGLE_TREE_SELECTION, only one TreePath will remain selected. It is up to the particular implementation to decide what TreePath remains selected.

Setting the mode to something other than the defined types will result in the mode becoming DISCONTIGUOUS_TREE_SELECTION.

Specified by:
setSelectionMode in interface TreeSelectionModel

getSelectionMode

public int getSelectionMode()
Returns the selection mode, one of SINGLE_TREE_SELECTION, DISCONTIGUOUS_TREE_SELECTION or CONTIGUOUS_TREE_SELECTION.

Specified by:
getSelectionMode in interface TreeSelectionModel

setSelectionPath

public void setSelectionPath(TreePath path)
Sets the selection to path. If this represents a change, then the TreeSelectionListeners are notified. If path is null, this has the same effect as invoking clearSelection.

Specified by:
setSelectionPath in interface TreeSelectionModel
Parameters:
path - new path to select

setSelectionPaths

public void setSelectionPaths(TreePath[] pPaths)
Sets the selection to the paths in paths. If this represents a change the TreeSelectionListeners are notified. Potentially paths will be held by this object; in other words don't change any of the objects in the array once passed in.

If paths is null, this has the same effect as invoking clearSelection.

The lead path is set to the last path in pPaths.

If the selection mode is CONTIGUOUS_TREE_SELECTION, and adding the new paths would make the selection discontiguous, the selection is reset to the first TreePath in paths.

Specified by:
setSelectionPaths in interface TreeSelectionModel
Parameters:
pPaths - new selection

addSelectionPath

public void addSelectionPath(TreePath path)
Adds path to the current selection. If path is not currently in the selection the TreeSelectionListeners are notified. This has no effect if path is null.

Specified by:
addSelectionPath in interface TreeSelectionModel
Parameters:
path - the new path to add to the current selection

addSelectionPaths

public void addSelectionPaths(TreePath[] paths)
Adds paths to the current selection. If any of the paths in paths are not currently in the selection the TreeSelectionListeners are notified. This has no effect if paths is null.

The lead path is set to the last element in paths.

If the selection mode is CONTIGUOUS_TREE_SELECTION, and adding the new paths would make the selection discontiguous. Then two things can result: if the TreePaths in paths are contiguous, then the selection becomes these TreePaths, otherwise the TreePaths aren't contiguous and the selection becomes the first TreePath in paths.

Specified by:
addSelectionPaths in interface TreeSelectionModel
Parameters:
paths - the new path to add to the current selection

removeSelectionPath

public void removeSelectionPath(TreePath path)
Removes path from the selection. If path is in the selection The TreeSelectionListeners are notified. This has no effect if path is null.

Specified by:
removeSelectionPath in interface TreeSelectionModel
Parameters:
path - the path to remove from the selection

removeSelectionPaths

public void removeSelectionPaths(TreePath[] paths)
Removes paths from the selection. If any of the paths in paths are in the selection the TreeSelectionListeners are notified. This has no effect if paths is null.

Specified by:
removeSelectionPaths in interface TreeSelectionModel
Parameters:
paths - the paths to remove from the selection

getSelectionPath

public TreePath getSelectionPath()
Returns the first path in the selection. This is useful if there if only one item currently selected.

Specified by:
getSelectionPath in interface TreeSelectionModel

getSelectionPaths

public TreePath[] getSelectionPaths()
Returns the paths in the selection. This will return null (or an empty array) if nothing is currently selected.

Specified by:
getSelectionPaths in interface TreeSelectionModel

getSelectionCount

public int getSelectionCount()
Returns the number of paths that are selected.

Specified by:
getSelectionCount in interface TreeSelectionModel

isPathSelected

public boolean isPathSelected(TreePath path)
Returns true if the path, path, is in the current selection.

Specified by:
isPathSelected in interface TreeSelectionModel

isSelectionEmpty

public boolean isSelectionEmpty()
Returns true if the selection is currently empty.

Specified by:
isSelectionEmpty in interface TreeSelectionModel

clearSelection

public void clearSelection()
Empties the current selection. If this represents a change in the current selection, the selection listeners are notified.

Specified by:
clearSelection in interface TreeSelectionModel

addTreeSelectionListener

public void addTreeSelectionListener(TreeSelectionListener x)
Adds x to the list of listeners that are notified each time the set of selected TreePaths changes.

Specified by:
addTreeSelectionListener in interface TreeSelectionModel
Parameters:
x - the new listener to be added

removeTreeSelectionListener

public void removeTreeSelectionListener(TreeSelectionListener x)
Removes x from the list of listeners that are notified each time the set of selected TreePaths changes.

Specified by:
removeTreeSelectionListener in interface TreeSelectionModel
Parameters:
x - the listener to remove

getTreeSelectionListeners

public TreeSelectionListener[] getTreeSelectionListeners()
Returns an array of all the tree selection listeners registered on this model.

Returns:
all of this model's TreeSelectionListeners or an empty array if no tree selection listeners are currently registered
Since:
1.4
See Also:
addTreeSelectionListener(javax.swing.event.TreeSelectionListener), removeTreeSelectionListener(javax.swing.event.TreeSelectionListener)

fireValueChanged

protected void fireValueChanged(TreeSelectionEvent e)
Notifies all listeners that are registered for tree selection events on this object.

See Also:
addTreeSelectionListener(javax.swing.event.TreeSelectionListener), EventListenerList

getListeners

public <T extends EventListener> T[] getListeners(Class<T> listenerType)
Returns an array of all the objects currently registered as FooListeners upon this model. FooListeners are registered using the addFooListener method.

You can specify the listenerType argument with a class literal, such as FooListener.class. For example, you can query a DefaultTreeSelectionModel m for its tree selection listeners with the following code:

TreeSelectionListener[] tsls = (TreeSelectionListener[])(m.getListeners(TreeSelectionListener.class));
If no such listeners exist, this method returns an empty array.

Parameters:
listenerType - the type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener
Returns:
an array of all objects registered as FooListeners on this component, or an empty array if no such listeners have been added
Throws:
ClassCastException - if listenerType doesn't specify a class or interface that implements java.util.EventListener
Since:
1.3
See Also:
getTreeSelectionListeners(), getPropertyChangeListeners()

getSelectionRows

public int[] getSelectionRows()
Returns all of the currently selected rows. This will return null (or an empty array) if there are no selected TreePaths or a RowMapper has not been set. This may return an array of length less that than of the selected TreePaths if some of the rows are not visible (that is the RowMapper returned -1 for the row corresponding to the TreePath).

Specified by:
getSelectionRows in interface TreeSelectionModel

getMinSelectionRow

public int getMinSelectionRow()
Returns the smallest value obtained from the RowMapper for the current set of selected TreePaths. If nothing is selected, or there is no RowMapper, this will return -1.

Specified by:
getMinSelectionRow in interface TreeSelectionModel

getMaxSelectionRow

public int getMaxSelectionRow()
Returns the largest value obtained from the RowMapper for the current set of selected TreePaths. If nothing is selected, or there is no RowMapper, this will return -1.

Specified by:
getMaxSelectionRow in interface TreeSelectionModel

isRowSelected

public boolean isRowSelected(int row)
Returns true if the row identified by row is selected.

Specified by:
isRowSelected in interface TreeSelectionModel

resetRowSelection

public void resetRowSelection()
Updates this object's mapping from TreePath to rows. This should be invoked when the mapping from TreePaths to integers has changed (for example, a node has been expanded).

You do not normally have to call this, JTree and its associated Listeners will invoke this for you. If you are implementing your own View class, then you will have to invoke this.

This will invoke insureRowContinuity to make sure the currently selected TreePaths are still valid based on the selection mode.

Specified by:
resetRowSelection in interface TreeSelectionModel

getLeadSelectionRow

public int getLeadSelectionRow()
Returns the lead selection index. That is the last index that was added.

Specified by:
getLeadSelectionRow in interface TreeSelectionModel

getLeadSelectionPath

public TreePath getLeadSelectionPath()
Returns the last path that was added. This may differ from the leadSelectionPath property maintained by the JTree.

Specified by:
getLeadSelectionPath in interface TreeSelectionModel

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list. The listener is registered for all properties.

A PropertyChangeEvent will get fired when the selection mode changes.

Specified by:
addPropertyChangeListener in interface TreeSelectionModel
Parameters:
listener - the PropertyChangeListener to be added

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties.

Specified by:
removePropertyChangeListener in interface TreeSelectionModel
Parameters:
listener - the PropertyChangeListener to be removed

getPropertyChangeListeners

public PropertyChangeListener[] getPropertyChangeListeners()
Returns an array of all the property change listeners registered on this DefaultTreeSelectionModel.

Returns:
all of this model's PropertyChangeListeners or an empty array if no property change listeners are currently registered
Since:
1.4
See Also:
addPropertyChangeListener(java.beans.PropertyChangeListener), removePropertyChangeListener(java.beans.PropertyChangeListener)

insureRowContinuity

protected void insureRowContinuity()
Makes sure the currently selected TreePaths are valid for the current selection mode. If the selection mode is CONTIGUOUS_TREE_SELECTION and a RowMapper exists, this will make sure all the rows are contiguous, that is, when sorted all the rows are in order with no gaps. If the selection isn't contiguous, the selection is reset to contain the first set, when sorted, of contiguous rows.

If the selection mode is SINGLE_TREE_SELECTION and more than one TreePath is selected, the selection is reset to contain the first path currently selected.

arePathsContiguous

protected boolean arePathsContiguous(TreePath[] paths)
Returns true if the paths are contiguous, or this object has no RowMapper.

canPathsBeAdded

protected boolean canPathsBeAdded(TreePath[] paths)
Used to test if a particular set of TreePaths can be added. This will return true if paths is null (or empty), or this object has no RowMapper, or nothing is currently selected, or the selection mode is DISCONTIGUOUS_TREE_SELECTION, or adding the paths to the current selection still results in a contiguous set of TreePaths.

canPathsBeRemoved

protected boolean canPathsBeRemoved(TreePath[] paths)
Returns true if the paths can be removed without breaking the continuity of the model. This is rather expensive.

notifyPathChange

protected void notifyPathChange(Vector<javax.swing.tree.PathPlaceHolder> changedPaths,
                                TreePath oldLeadSelection)
Notifies listeners of a change in path. changePaths should contain instances of PathPlaceHolder.

updateLeadIndex

protected void updateLeadIndex()
Updates the leadIndex instance variable.

insureUniqueness

protected void insureUniqueness()
This method is obsolete and its implementation is now a noop. It's still called by setSelectionPaths and addSelectionPaths, but only for backwards compatability.

toString

public String toString()
Returns a string that displays and identifies this object's properties.

Overrides:
toString in class Object
Returns:
a String representation of this object

clone

public Object clone()
             throws CloneNotSupportedException
Returns a clone of this object with the same selection. This method does not duplicate selection listeners and property listeners.

Overrides:
clone in class Object
Returns:
a clone of this instance.
Throws:
CloneNotSupportedException - never thrown by instances of this class
See Also:
Cloneable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ExpandVetoException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Class ExpandVetoException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.swing.tree.ExpandVetoException
All Implemented Interfaces:
Serializable
public class ExpandVetoException
extends Exception

Exception used to stop and expand/collapse from happening. See How to Write a Tree-Will-Expand Listener in The Java Tutorial for further information and examples.

Field Summary
protected  TreeExpansionEvent event
The event that the exception was created for.
Constructor Summary
ExpandVetoException(TreeExpansionEvent event)
Constructs an ExpandVetoException object with no message.
ExpandVetoException(TreeExpansionEvent event, String message)
Constructs an ExpandVetoException object with the specified message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

event

protected TreeExpansionEvent event
The event that the exception was created for.

Constructor Detail

ExpandVetoException

public ExpandVetoException(TreeExpansionEvent event)
Constructs an ExpandVetoException object with no message.

Parameters:
event - a TreeExpansionEvent object

ExpandVetoException

public ExpandVetoException(TreeExpansionEvent event,
                           String message)
Constructs an ExpandVetoException object with the specified message.

Parameters:
event - a TreeExpansionEvent object
message - a String containing the message
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FixedHeightLayoutCache

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Class FixedHeightLayoutCache

java.lang.Object
    extended by  javax.swing.tree.AbstractLayoutCache
        extended by  javax.swing.tree.FixedHeightLayoutCache
All Implemented Interfaces:
RowMapper
public class FixedHeightLayoutCache
extends AbstractLayoutCache

NOTE: This will become more open in a future release.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.tree.AbstractLayoutCache
AbstractLayoutCache.NodeDimensions
Field Summary
Fields inherited from class javax.swing.tree.AbstractLayoutCache
nodeDimensions, rootVisible, rowHeight, treeModel, treeSelectionModel
Constructor Summary
FixedHeightLayoutCache()
Method Summary
Rectangle | getBounds(TreePath path, Rectangle placeIn) Returns a rectangle giving the bounds needed to draw path.
boolean | getExpandedState(TreePath path) Returns true if the path is expanded, and visible.
TreePath | getPathClosestTo(int x, int y) Returns the path to the node that is closest to x,y.
TreePath | getPathForRow(int row) Returns the path for passed in row.
int | getRowCount() Returns the number of visible rows.
int | getRowForPath(TreePath path) Returns the row that the last item identified in path is visible at.
int | getVisibleChildCount(TreePath path) Returns the number of visible children for row.
Enumeration<TreePath> | getVisiblePathsFrom(TreePath path) Returns an Enumerator that increments over the visible paths starting at the passed in location.
void | invalidatePathBounds(TreePath path) Does nothing, FixedHeightLayoutCache doesn't cache width, and that is all that could change.
void | invalidateSizes() Informs the TreeState that it needs to recalculate all the sizes it is referencing.
boolean | isExpanded(TreePath path) Returns true if the value identified by row is currently expanded.
void | setExpandedState(TreePath path, boolean isExpanded) Marks the path path expanded state to isExpanded.
void | setModel(TreeModel newModel) Sets the TreeModel that will provide the data.
void | setRootVisible(boolean rootVisible) Determines whether or not the root node from the TreeModel is visible.
void | setRowHeight(int rowHeight) Sets the height of each cell.
void | treeNodesChanged(TreeModelEvent e) Invoked after a node (or a set of siblings) has changed in some way.
void | treeNodesInserted(TreeModelEvent e) Invoked after nodes have been inserted into the tree.
void | treeNodesRemoved(TreeModelEvent e) Invoked after nodes have been removed from the tree.
void | treeStructureChanged(TreeModelEvent e) Invoked after the tree has drastically changed structure from a given node down.
Methods inherited from class javax.swing.tree.AbstractLayoutCache
getModel, getNodeDimensions, getNodeDimensions, getPreferredHeight, getPreferredWidth, getRowHeight, getRowsForPaths, getSelectionModel, isFixedRowHeight, isRootVisible, setNodeDimensions, setSelectionModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FixedHeightLayoutCache

public FixedHeightLayoutCache()
Method Detail

setModel

public void setModel(TreeModel newModel)
Sets the TreeModel that will provide the data.

Overrides:
setModel in class AbstractLayoutCache
Parameters:
newModel - the TreeModel that is to provide the data

setRootVisible

public void setRootVisible(boolean rootVisible)
Determines whether or not the root node from the TreeModel is visible.

Overrides:
setRootVisible in class AbstractLayoutCache
Parameters:
rootVisible - true if the root node of the tree is to be displayed
See Also:
AbstractLayoutCache.rootVisible

setRowHeight

public void setRowHeight(int rowHeight)
Sets the height of each cell. If rowHeight is less than or equal to 0 this will throw an IllegalArgumentException.

Overrides:
setRowHeight in class AbstractLayoutCache
Parameters:
rowHeight - the height of each cell, in pixels

getRowCount

public int getRowCount()
Returns the number of visible rows.

Specified by:
getRowCount in class AbstractLayoutCache
Returns:
the number of rows being displayed

invalidatePathBounds

public void invalidatePathBounds(TreePath path)
Does nothing, FixedHeightLayoutCache doesn't cache width, and that is all that could change.

Specified by:
invalidatePathBounds in class AbstractLayoutCache
Parameters:
path - the path being updated

invalidateSizes

public void invalidateSizes()
Informs the TreeState that it needs to recalculate all the sizes it is referencing.

Specified by:
invalidateSizes in class AbstractLayoutCache

isExpanded

public boolean isExpanded(TreePath path)
Returns true if the value identified by row is currently expanded.

Specified by:
isExpanded in class AbstractLayoutCache

getBounds

public Rectangle getBounds(TreePath path,
                           Rectangle placeIn)
Returns a rectangle giving the bounds needed to draw path.

Specified by:
getBounds in class AbstractLayoutCache
Parameters:
path - a TreePath specifying a node
placeIn - a Rectangle object giving the available space
Returns:
a Rectangle object specifying the space to be used

getPathForRow

public TreePath getPathForRow(int row)
Returns the path for passed in row. If row is not visible null is returned.

Specified by:
getPathForRow in class AbstractLayoutCache
Parameters:
row - the row being queried
Returns:
the TreePath for the given row

getRowForPath

public int getRowForPath(TreePath path)
Returns the row that the last item identified in path is visible at. Will return -1 if any of the elements in path are not currently visible.

Specified by:
getRowForPath in class AbstractLayoutCache
Parameters:
path - the TreePath being queried
Returns:
the row where the last item in path is visible or -1 if any elements in path aren't currently visible

getPathClosestTo

public TreePath getPathClosestTo(int x,
                                 int y)
Returns the path to the node that is closest to x,y. If there is nothing currently visible this will return null, otherwise it'll always return a valid path. If you need to test if the returned object is exactly at x, y you should get the bounds for the returned path and test x, y against that.

Specified by:
getPathClosestTo in class AbstractLayoutCache
Parameters:
x - the horizontal component of the desired location
y - the vertical component of the desired location
Returns:
the TreePath closest to the specified point

getVisibleChildCount

public int getVisibleChildCount(TreePath path)
Returns the number of visible children for row.

Specified by:
getVisibleChildCount in class AbstractLayoutCache
Parameters:
path - the path being queried
Returns:
the number of visible children for the specified path

getVisiblePathsFrom

public Enumeration<TreePath> getVisiblePathsFrom(TreePath path)
Returns an Enumerator that increments over the visible paths starting at the passed in location. The ordering of the enumeration is based on how the paths are displayed.

Specified by:
getVisiblePathsFrom in class AbstractLayoutCache
Parameters:
path - the starting location for the enumeration
Returns:
the Enumerator starting at the desired location

setExpandedState

public void setExpandedState(TreePath path,
                             boolean isExpanded)
Marks the path path expanded state to isExpanded.

Specified by:
setExpandedState in class AbstractLayoutCache
Parameters:
path - the path being expanded or collapsed
isExpanded - true if the path should be expanded, false otherwise

getExpandedState

public boolean getExpandedState(TreePath path)
Returns true if the path is expanded, and visible.

Specified by:
getExpandedState in class AbstractLayoutCache
Parameters:
path - the path being queried
Returns:
true if the path is expanded and visible, false otherwise

treeNodesChanged

public void treeNodesChanged(TreeModelEvent e)

Invoked after a node (or a set of siblings) has changed in some way. The node(s) have not changed locations in the tree or altered their children arrays, but other attributes have changed and may affect presentation. Example: the name of a file has changed, but it is in the same location in the file system.

e.path() returns the path the parent of the changed node(s).

e.childIndices() returns the index(es) of the changed node(s).

Specified by:
treeNodesChanged in class AbstractLayoutCache
Parameters:
e - the TreeModelEvent

treeNodesInserted

public void treeNodesInserted(TreeModelEvent e)

Invoked after nodes have been inserted into the tree.

e.path() returns the parent of the new nodes

e.childIndices() returns the indices of the new nodes in ascending order.

Specified by:
treeNodesInserted in class AbstractLayoutCache
Parameters:
e - the TreeModelEvent

treeNodesRemoved

public void treeNodesRemoved(TreeModelEvent e)

Invoked after nodes have been removed from the tree. Note that if a subtree is removed from the tree, this method may only be invoked once for the root of the removed subtree, not once for each individual set of siblings removed.

e.path() returns the former parent of the deleted nodes.

e.childIndices() returns the indices the nodes had before they were deleted in ascending order.

Specified by:
treeNodesRemoved in class AbstractLayoutCache
Parameters:
e - the TreeModelEvent

treeStructureChanged

public void treeStructureChanged(TreeModelEvent e)

Invoked after the tree has drastically changed structure from a given node down. If the path returned by e.getPath() is of length one and the first element does not identify the current root node the first element should become the new root of the tree.

e.path() holds the path to the node.

e.childIndices() returns null.

Specified by:
treeStructureChanged in class AbstractLayoutCache
Parameters:
e - the TreeModelEvent
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MutableTreeNode

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Interface MutableTreeNode

All Superinterfaces:
TreeNode
All Known Implementing Classes:
DefaultMutableTreeNode, JTree.DynamicUtilTreeNode
public interface MutableTreeNode
extends TreeNode

Defines the requirements for a tree node object that can change -- by adding or removing child nodes, or by changing the contents of a user object stored in the node.

See Also:
DefaultMutableTreeNode, JTree

Method Summary
void | insert(MutableTreeNode child, int index) Adds child to the receiver at index.
void | remove(int index) Removes the child at index from the receiver.
void | remove(MutableTreeNode node) Removes node from the receiver.
void | removeFromParent() Removes the receiver from its parent.
void | setParent(MutableTreeNode newParent) Sets the parent of the receiver to newParent.
void | setUserObject(Object object) Resets the user object of the receiver to object.
Methods inherited from interface javax.swing.tree.TreeNode
children, getAllowsChildren, getChildAt, getChildCount, getIndex, getParent, isLeaf

Method Detail

insert

void insert(MutableTreeNode child,
            int index)
Adds child to the receiver at index. child will be messaged with setParent.

remove

void remove(int index)
Removes the child at index from the receiver.

remove

void remove(MutableTreeNode node)
Removes node from the receiver. setParent will be messaged on node.

setUserObject

void setUserObject(Object object)
Resets the user object of the receiver to object.

removeFromParent

void removeFromParent()
Removes the receiver from its parent.

setParent

void setParent(MutableTreeNode newParent)
Sets the parent of the receiver to newParent.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RowMapper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Interface RowMapper

All Known Implementing Classes:
AbstractLayoutCache, FixedHeightLayoutCache, VariableHeightLayoutCache
public interface RowMapper

Defines the requirements for an object that translates paths in the tree into display rows.

Method Summary
 int[] getRowsForPaths(TreePath[] path)
Returns the rows that the TreePath instances in path are being displayed at.

Method Detail

getRowsForPaths

int[] getRowsForPaths(TreePath[] path)
Returns the rows that the TreePath instances in path are being displayed at. The receiver should return an array of the same length as that passed in, and if one of the TreePaths in path is not valid its entry in the array should be set to -1.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TreeCellEditor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Interface TreeCellEditor

All Superinterfaces:
CellEditor
All Known Implementing Classes:
DefaultCellEditor, DefaultTreeCellEditor
public interface TreeCellEditor
extends CellEditor

Adds to CellEditor the extensions necessary to configure an editor in a tree.

See Also:
JTree

Method Summary
 Component getTreeCellEditorComponent(JTree tree, Object value, boolean isSelected, boolean expanded, boolean leaf, int row)
Sets an initial value for the editor.
Methods inherited from interface javax.swing.CellEditor
addCellEditorListener, cancelCellEditing, getCellEditorValue, isCellEditable, removeCellEditorListener, shouldSelectCell, stopCellEditing

Method Detail

getTreeCellEditorComponent

Component getTreeCellEditorComponent(JTree tree,
                                     Object value,
                                     boolean isSelected,
                                     boolean expanded,
                                     boolean leaf,
                                     int row)
Sets an initial value for the editor. This will cause the editor to stopEditing and lose any partially edited value if the editor is editing when this method is called.

Returns the component that should be added to the client's Component hierarchy. Once installed in the client's hierarchy this component will then be able to draw and receive user input.

Parameters:
tree - the JTree that is asking the editor to edit; this parameter can be null
value - the value of the cell to be edited
isSelected - true if the cell is to be rendered with selection highlighting
expanded - true if the node is expanded
leaf - true if the node is a leaf node
row - the row index of the node being edited
Returns:
the component for editing
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TreeCellRenderer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Interface TreeCellRenderer

All Known Implementing Classes:
DefaultTreeCellRenderer
public interface TreeCellRenderer

Defines the requirements for an object that displays a tree node. See How to Use Trees in The Java Tutorial for an example of implementing a tree cell renderer that displays custom icons.

Method Summary
 Component getTreeCellRendererComponent(JTree tree, Object value, boolean selected, boolean expanded, boolean leaf, int row, boolean hasFocus)
Sets the value of the current tree cell to value.

Method Detail

getTreeCellRendererComponent

Component getTreeCellRendererComponent(JTree tree,
                                       Object value,
                                       boolean selected,
                                       boolean expanded,
                                       boolean leaf,
                                       int row,
                                       boolean hasFocus)
Sets the value of the current tree cell to value. If selected is true, the cell will be drawn as if selected. If expanded is true the node is currently expanded and if leaf is true the node represents a leaf and if hasFocus is true the node currently has focus. tree is the JTree the receiver is being configured for. Returns the Component that the renderer uses to draw the value.

The TreeCellRenderer is also responsible for rendering the the cell representing the tree's current DnD drop location if it has one. If this renderer cares about rendering the DnD drop location, it should query the tree directly to see if the given row represents the drop location:

     JTree.DropLocation dropLocation = tree.getDropLocation();
     if (dropLocation != null
             && dropLocation.getChildIndex() == -1
             && tree.getRowForPath(dropLocation.getPath()) == row) {

         // this row represents the current drop location
         // so render it specially, perhaps with a different color
     }

Returns:
the Component that the renderer uses to draw the value
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TreeModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Interface TreeModel

All Known Implementing Classes:
DefaultTreeModel
public interface TreeModel

The model used by JTree.

JTree and its related classes make extensive use of TreePaths for indentifying nodes in the TreeModel. If a TreeModel returns the same object, as compared by equals, at two different indices under the same parent than the resulting TreePath objects will be considered equal as well. Some implementations may assume that if two TreePaths are equal, they identify the same node. If this condition is not met, painting problems and other oddities may result. In other words, if getChild for a given parent returns the same Object (as determined by equals) problems may result, and it is recommended you avoid doing this.

Similarly JTree and its related classes place TreePaths in Maps. As such if a node is requested twice, the return values must be equal (using the equals method) and have the same hashCode.

For further information on tree models, including an example of a custom implementation, see How to Use Trees in The Java Tutorial.

See Also:
TreePath

Method Summary
void | addTreeModelListener(TreeModelListener l) Adds a listener for the TreeModelEvent posted after the tree changes.
Object | getChild(Object parent, int index) Returns the child of parent at index index in the parent's child array.
int | getChildCount(Object parent) Returns the number of children of parent.
int | getIndexOfChild(Object parent, Object child) Returns the index of child in parent.
Object | getRoot() Returns the root of the tree.
boolean | isLeaf(Object node) Returns true if node is a leaf.
void | removeTreeModelListener(TreeModelListener l) Removes a listener previously added with addTreeModelListener.
void | valueForPathChanged(TreePath path, Object newValue) Messaged when the user has altered the value for the item identified by path to newValue.

Method Detail

getRoot

Object getRoot()
Returns the root of the tree. Returns null only if the tree has no nodes.

Returns:
the root of the tree

getChild

Object getChild(Object parent,
                int index)
Returns the child of parent at index index in the parent's child array. parent must be a node previously obtained from this data source. This should not return null if index is a valid index for parent (that is index >= 0 && index < getChildCount(parent)).

Parameters:
parent - a node in the tree, obtained from this data source
Returns:
the child of parent at index index

getChildCount

int getChildCount(Object parent)
Returns the number of children of parent. Returns 0 if the node is a leaf or if it has no children. parent must be a node previously obtained from this data source.

Parameters:
parent - a node in the tree, obtained from this data source
Returns:
the number of children of the node parent

isLeaf

boolean isLeaf(Object node)
Returns true if node is a leaf. It is possible for this method to return false even if node has no children. A directory in a filesystem, for example, may contain no files; the node representing the directory is not a leaf, but it also has no children.

Parameters:
node - a node in the tree, obtained from this data source
Returns:
true if node is a leaf

valueForPathChanged

void valueForPathChanged(TreePath path,
                         Object newValue)
Messaged when the user has altered the value for the item identified by path to newValue. If newValue signifies a truly new value the model should post a treeNodesChanged event.

Parameters:
path - path to the node that the user has altered
newValue - the new value from the TreeCellEditor

getIndexOfChild

int getIndexOfChild(Object parent,
                    Object child)
Returns the index of child in parent. If either parent or child is null, returns -1. If either parent or child don't belong to this tree model, returns -1.

Parameters:
parent - a node in the tree, obtained from this data source
child - the node we are interested in
Returns:
the index of the child in the parent, or -1 if either child or parent are null or don't belong to this tree model

addTreeModelListener

void addTreeModelListener(TreeModelListener l)
Adds a listener for the TreeModelEvent posted after the tree changes.

Parameters:
l - the listener to add
See Also:
removeTreeModelListener(javax.swing.event.TreeModelListener)

removeTreeModelListener

void removeTreeModelListener(TreeModelListener l)
Removes a listener previously added with addTreeModelListener.

Parameters:
l - the listener to remove
See Also:
addTreeModelListener(javax.swing.event.TreeModelListener)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TreeNode

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Interface TreeNode

All Known Subinterfaces:
MutableTreeNode
All Known Implementing Classes:
AbstractDocument.AbstractElement, AbstractDocument.BranchElement, AbstractDocument.LeafElement, DefaultMutableTreeNode, DefaultStyledDocument.SectionElement, HTMLDocument.BlockElement, HTMLDocument.RunElement, JTree.DynamicUtilTreeNode
public interface TreeNode

Defines the requirements for an object that can be used as a tree node in a JTree.

Implementations of TreeNode that override equals will typically need to override hashCode as well. Refer to TreeModel for more information. For further information and examples of using tree nodes, see How to Use Tree Nodes in The Java Tutorial.

Method Summary
Enumeration | children() Returns the children of the receiver as an Enumeration.
boolean | getAllowsChildren() Returns true if the receiver allows children.
TreeNode | getChildAt(int childIndex) Returns the child TreeNode at index childIndex.
int | getChildCount() Returns the number of children TreeNodes the receiver contains.
int | getIndex(TreeNode node) Returns the index of node in the receivers children.
TreeNode | getParent() Returns the parent TreeNode of the receiver.
boolean | isLeaf() Returns true if the receiver is a leaf.

Method Detail

getChildAt

TreeNode getChildAt(int childIndex)
Returns the child TreeNode at index childIndex.

getChildCount

int getChildCount()
Returns the number of children TreeNodes the receiver contains.

getParent

TreeNode getParent()
Returns the parent TreeNode of the receiver.

getIndex

int getIndex(TreeNode node)
Returns the index of node in the receivers children. If the receiver does not contain node, -1 will be returned.

getAllowsChildren

boolean getAllowsChildren()
Returns true if the receiver allows children.

isLeaf

boolean isLeaf()
Returns true if the receiver is a leaf.

children

Enumeration children()
Returns the children of the receiver as an Enumeration.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TreePath

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Class TreePath

java.lang.Object
    extended by  javax.swing.tree.TreePath
All Implemented Interfaces:
Serializable
public class TreePath
extends Object
implements Serializable

Represents a path to a node. A TreePath is an array of Objects that are vended from a TreeModel. The elements of the array are ordered such that the root is always the first element (index 0) of the array. TreePath is Serializable, but if any components of the path are not serializable, it will not be written out.

For further information and examples of using tree paths, see How to Use Trees in The Java Tutorial.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
protected | TreePath() Primarily provided for subclasses that represent paths in a different manner.
 | TreePath(Object singlePath) Constructs a TreePath containing only a single element.
 | TreePath(Object[] path) Constructs a path from an array of Objects, uniquely identifying the path from the root of the tree to a specific node, as returned by the tree's data model.
protected | TreePath(Object[] path, int length) Constructs a new TreePath with the identified path components of length length.
protected | TreePath(TreePath parent, Object lastElement) Constructs a new TreePath, which is the path identified by parent ending in lastElement.
Method Summary
boolean | equals(Object o) Tests two TreePaths for equality by checking each element of the paths for equality.
Object | getLastPathComponent() Returns the last component of this path.
TreePath | getParentPath() Returns a path containing all the elements of this object, except the last path component.
Object[] | getPath() Returns an ordered array of Objects containing the components of this TreePath.
Object | getPathComponent(int element) Returns the path component at the specified index.
int | getPathCount() Returns the number of elements in the path.
int | hashCode() Returns the hashCode for the object.
boolean | isDescendant(TreePath aTreePath) Returns true if aTreePath is a descendant of this TreePath.
TreePath | pathByAddingChild(Object child) Returns a new path containing all the elements of this object plus child.
String | toString() Returns a string that displays and identifies this object's properties.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

TreePath

public TreePath(Object[] path)
Constructs a path from an array of Objects, uniquely identifying the path from the root of the tree to a specific node, as returned by the tree's data model.

The model is free to return an array of any Objects it needs to represent the path. The DefaultTreeModel returns an array of TreeNode objects. The first TreeNode in the path is the root of the tree, the last TreeNode is the node identified by the path.

Parameters:
path - an array of Objects representing the path to a node

TreePath

public TreePath(Object singlePath)
Constructs a TreePath containing only a single element. This is usually used to construct a TreePath for the the root of the TreeModel.

Parameters:
singlePath - an Object representing the path to a node
See Also:
TreePath(Object[])

TreePath

protected TreePath(TreePath parent,
                   Object lastElement)
Constructs a new TreePath, which is the path identified by parent ending in lastElement.

TreePath

protected TreePath(Object[] path,
                   int length)
Constructs a new TreePath with the identified path components of length length.

TreePath

protected TreePath()
Primarily provided for subclasses that represent paths in a different manner. If a subclass uses this constructor, it should also override the getPath, getPathCount, and getPathComponent methods, and possibly the equals method.

Method Detail

getPath

public Object[] getPath()
Returns an ordered array of Objects containing the components of this TreePath. The first element (index 0) is the root.

Returns:
an array of Objects representing the TreePath
See Also:
TreePath(Object[])

getLastPathComponent

public Object getLastPathComponent()
Returns the last component of this path. For a path returned by DefaultTreeModel this will return an instance of TreeNode.

Returns:
the Object at the end of the path
See Also:
TreePath(Object[])

getPathCount

public int getPathCount()
Returns the number of elements in the path.

Returns:
an int giving a count of items the path

getPathComponent

public Object getPathComponent(int element)
Returns the path component at the specified index.

Parameters:
element - an int specifying an element in the path, where 0 is the first element in the path
Returns:
the Object at that index location
Throws:
IllegalArgumentException - if the index is beyond the length of the path
See Also:
TreePath(Object[])

equals

public boolean equals(Object o)
Tests two TreePaths for equality by checking each element of the paths for equality. Two paths are considered equal if they are of the same length, and contain the same elements (.equals).

Overrides:
equals in class Object
Parameters:
o - the Object to compare
Returns:
true if this object is the same as the obj argument; false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns the hashCode for the object. The hash code of a TreePath is defined to be the hash code of the last component in the path.

Overrides:
hashCode in class Object
Returns:
the hashCode for the object
See Also:
Object.equals(java.lang.Object), Hashtable

isDescendant

public boolean isDescendant(TreePath aTreePath)
Returns true if aTreePath is a descendant of this TreePath. A TreePath P1 is a descendant of a TreePath P2 if P1 contains all of the components that make up P2's path. For example, if this object has the path [a, b], and aTreePath has the path [a, b, c], then aTreePath is a descendant of this object. However, if aTreePath has the path [a], then it is not a descendant of this object. By this definition a TreePath is always considered a descendant of itself. That is, aTreePath.isDescendant(aTreePath) returns true.

Returns:
true if aTreePath is a descendant of this path

pathByAddingChild

public TreePath pathByAddingChild(Object child)
Returns a new path containing all the elements of this object plus child. child will be the last element of the newly created TreePath. This will throw a NullPointerException if child is null.

getParentPath

public TreePath getParentPath()
Returns a path containing all the elements of this object, except the last path component.

toString

public String toString()
Returns a string that displays and identifies this object's properties.

Overrides:
toString in class Object
Returns:
a String representation of this object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TreeSelectionModel

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Interface TreeSelectionModel

All Known Implementing Classes:
DefaultTreeSelectionModel, JTree.EmptySelectionModel
public interface TreeSelectionModel

This interface represents the current state of the selection for the tree component. For information and examples of using tree selection models, see How to Use Trees in The Java Tutorial.

The state of the tree selection is characterized by a set of TreePaths, and optionally a set of integers. The mapping from TreePath to integer is done by way of an instance of RowMapper. It is not necessary for a TreeSelectionModel to have a RowMapper to correctly operate, but without a RowMapper getSelectionRows will return null.

A TreeSelectionModel can be configured to allow only one path (SINGLE_TREE_SELECTION) a number of continguous paths (CONTIGUOUS_TREE_SELECTION) or a number of discontiguous paths (DISCONTIGUOUS_TREE_SELECTION). A RowMapper is used to determine if TreePaths are contiguous. In the absence of a RowMapper CONTIGUOUS_TREE_SELECTION and DISCONTIGUOUS_TREE_SELECTION behave the same, that is they allow any number of paths to be contained in the TreeSelectionModel.

For a selection model of CONTIGUOUS_TREE_SELECTION any time the paths are changed (setSelectionPath, addSelectionPath ...) the TreePaths are again checked to make they are contiguous. A check of the TreePaths can also be forced by invoking resetRowSelection. How a set of discontiguous TreePaths is mapped to a contiguous set is left to implementors of this interface to enforce a particular policy.

Implementations should combine duplicate TreePaths that are added to the selection. For example, the following code

   TreePath[] paths = new TreePath[] { treePath, treePath };
   treeSelectionModel.setSelectionPaths(paths);
should result in only one path being selected: treePath, and not two copies of treePath.

The lead TreePath is the last path that was added (or set). The lead row is then the row that corresponds to the TreePath as determined from the RowMapper.

Field Summary
static int | CONTIGUOUS_TREE_SELECTION Selection can only be contiguous.
static int | DISCONTIGUOUS_TREE_SELECTION Selection can contain any number of items that are not necessarily contiguous.
static int | SINGLE_TREE_SELECTION Selection can only contain one path at a time.
Method Summary
void | addPropertyChangeListener(PropertyChangeListener listener) Adds a PropertyChangeListener to the listener list.
void | addSelectionPath(TreePath path) Adds path to the current selection.
void | addSelectionPaths(TreePath[] paths) Adds paths to the current selection.
void | addTreeSelectionListener(TreeSelectionListener x) Adds x to the list of listeners that are notified each time the set of selected TreePaths changes.
void | clearSelection() Empties the current selection.
TreePath | getLeadSelectionPath() Returns the last path that was added.
int | getLeadSelectionRow() Returns the lead selection index.
int | getMaxSelectionRow() Returns the largest value obtained from the RowMapper for the current set of selected TreePaths.
int | getMinSelectionRow() Returns the smallest value obtained from the RowMapper for the current set of selected TreePaths.
RowMapper | getRowMapper() Returns the RowMapper instance that is able to map a TreePath to a row.
int | getSelectionCount() Returns the number of paths that are selected.
int | getSelectionMode() Returns the current selection mode, one of SINGLE_TREE_SELECTION, CONTIGUOUS_TREE_SELECTION or DISCONTIGUOUS_TREE_SELECTION.
TreePath | getSelectionPath() Returns the first path in the selection.
TreePath[] | getSelectionPaths() Returns the paths in the selection.
int[] | getSelectionRows() Returns all of the currently selected rows.
boolean | isPathSelected(TreePath path) Returns true if the path, path, is in the current selection.
boolean | isRowSelected(int row) Returns true if the row identified by row is selected.
boolean | isSelectionEmpty() Returns true if the selection is currently empty.
void | removePropertyChangeListener(PropertyChangeListener listener) Removes a PropertyChangeListener from the listener list.
void | removeSelectionPath(TreePath path) Removes path from the selection.
void | removeSelectionPaths(TreePath[] paths) Removes paths from the selection.
void | removeTreeSelectionListener(TreeSelectionListener x) Removes x from the list of listeners that are notified each time the set of selected TreePaths changes.
void | resetRowSelection() Updates this object's mapping from TreePaths to rows.
void | setRowMapper(RowMapper newMapper) Sets the RowMapper instance.
void | setSelectionMode(int mode) Sets the selection model, which must be one of SINGLE_TREE_SELECTION, CONTIGUOUS_TREE_SELECTION or DISCONTIGUOUS_TREE_SELECTION.
void | setSelectionPath(TreePath path) Sets the selection to path.
void | setSelectionPaths(TreePath[] paths) Sets the selection to path.

Field Detail

SINGLE_TREE_SELECTION

static final int SINGLE_TREE_SELECTION
Selection can only contain one path at a time.

See Also:
Constant Field Values

CONTIGUOUS_TREE_SELECTION

static final int CONTIGUOUS_TREE_SELECTION
Selection can only be contiguous. This will only be enforced if a RowMapper instance is provided. That is, if no RowMapper is set this behaves the same as DISCONTIGUOUS_TREE_SELECTION.

See Also:
Constant Field Values

DISCONTIGUOUS_TREE_SELECTION

static final int DISCONTIGUOUS_TREE_SELECTION
Selection can contain any number of items that are not necessarily contiguous.

See Also:
Constant Field Values
Method Detail

setSelectionMode

void setSelectionMode(int mode)
Sets the selection model, which must be one of SINGLE_TREE_SELECTION, CONTIGUOUS_TREE_SELECTION or DISCONTIGUOUS_TREE_SELECTION.

This may change the selection if the current selection is not valid for the new mode. For example, if three TreePaths are selected when the mode is changed to SINGLE_TREE_SELECTION, only one TreePath will remain selected. It is up to the particular implementation to decide what TreePath remains selected.

getSelectionMode

int getSelectionMode()
Returns the current selection mode, one of SINGLE_TREE_SELECTION, CONTIGUOUS_TREE_SELECTION or DISCONTIGUOUS_TREE_SELECTION.

setSelectionPath

void setSelectionPath(TreePath path)
Sets the selection to path. If this represents a change, then the TreeSelectionListeners are notified. If path is null, this has the same effect as invoking clearSelection.

Parameters:
path - new path to select

setSelectionPaths

void setSelectionPaths(TreePath[] paths)
Sets the selection to path. If this represents a change, then the TreeSelectionListeners are notified. If paths is null, this has the same effect as invoking clearSelection.

Parameters:
paths - new selection

addSelectionPath

void addSelectionPath(TreePath path)
Adds path to the current selection. If path is not currently in the selection the TreeSelectionListeners are notified. This has no effect if path is null.

Parameters:
path - the new path to add to the current selection

addSelectionPaths

void addSelectionPaths(TreePath[] paths)
Adds paths to the current selection. If any of the paths in paths are not currently in the selection the TreeSelectionListeners are notified. This has no effect if paths is null.

Parameters:
paths - the new paths to add to the current selection

removeSelectionPath

void removeSelectionPath(TreePath path)
Removes path from the selection. If path is in the selection The TreeSelectionListeners are notified. This has no effect if path is null.

Parameters:
path - the path to remove from the selection

removeSelectionPaths

void removeSelectionPaths(TreePath[] paths)
Removes paths from the selection. If any of the paths in paths are in the selection, the TreeSelectionListeners are notified. This method has no effect if paths is null.

Parameters:
paths - the path to remove from the selection

getSelectionPath

TreePath getSelectionPath()
Returns the first path in the selection. How first is defined is up to implementors, and may not necessarily be the TreePath with the smallest integer value as determined from the RowMapper.

getSelectionPaths

TreePath[] getSelectionPaths()
Returns the paths in the selection. This will return null (or an empty array) if nothing is currently selected.

getSelectionCount

int getSelectionCount()
Returns the number of paths that are selected.

isPathSelected

boolean isPathSelected(TreePath path)
Returns true if the path, path, is in the current selection.

isSelectionEmpty

boolean isSelectionEmpty()
Returns true if the selection is currently empty.

clearSelection

void clearSelection()
Empties the current selection. If this represents a change in the current selection, the selection listeners are notified.

setRowMapper

void setRowMapper(RowMapper newMapper)
Sets the RowMapper instance. This instance is used to determine the row for a particular TreePath.

getRowMapper

RowMapper getRowMapper()
Returns the RowMapper instance that is able to map a TreePath to a row.

getSelectionRows

int[] getSelectionRows()
Returns all of the currently selected rows. This will return null (or an empty array) if there are no selected TreePaths or a RowMapper has not been set.

getMinSelectionRow

int getMinSelectionRow()
Returns the smallest value obtained from the RowMapper for the current set of selected TreePaths. If nothing is selected, or there is no RowMapper, this will return -1.

getMaxSelectionRow

int getMaxSelectionRow()
Returns the largest value obtained from the RowMapper for the current set of selected TreePaths. If nothing is selected, or there is no RowMapper, this will return -1.

isRowSelected

boolean isRowSelected(int row)
Returns true if the row identified by row is selected.

resetRowSelection

void resetRowSelection()
Updates this object's mapping from TreePaths to rows. This should be invoked when the mapping from TreePaths to integers has changed (for example, a node has been expanded).

You do not normally have to call this; JTree and its associated listeners will invoke this for you. If you are implementing your own view class, then you will have to invoke this.

getLeadSelectionRow

int getLeadSelectionRow()
Returns the lead selection index. That is the last index that was added.

getLeadSelectionPath

TreePath getLeadSelectionPath()
Returns the last path that was added. This may differ from the leadSelectionPath property maintained by the JTree.

addPropertyChangeListener

void addPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list. The listener is registered for all properties.

A PropertyChangeEvent will get fired when the selection mode changes.

Parameters:
listener - the PropertyChangeListener to be added

removePropertyChangeListener

void removePropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties.

Parameters:
listener - the PropertyChangeListener to be removed

addTreeSelectionListener

void addTreeSelectionListener(TreeSelectionListener x)
Adds x to the list of listeners that are notified each time the set of selected TreePaths changes.

Parameters:
x - the new listener to be added

removeTreeSelectionListener

void removeTreeSelectionListener(TreeSelectionListener x)
Removes x from the list of listeners that are notified each time the set of selected TreePaths changes.

Parameters:
x - the listener to remove
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VariableHeightLayoutCache

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.tree
Class VariableHeightLayoutCache

java.lang.Object
    extended by  javax.swing.tree.AbstractLayoutCache
        extended by  javax.swing.tree.VariableHeightLayoutCache
All Implemented Interfaces:
RowMapper
public class VariableHeightLayoutCache
extends AbstractLayoutCache

NOTE: This will become more open in a future release.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.tree.AbstractLayoutCache
AbstractLayoutCache.NodeDimensions
Field Summary
Fields inherited from class javax.swing.tree.AbstractLayoutCache
nodeDimensions, rootVisible, rowHeight, treeModel, treeSelectionModel
Constructor Summary
VariableHeightLayoutCache()
Method Summary
Rectangle | getBounds(TreePath path, Rectangle placeIn) Returns the Rectangle enclosing the label portion into which the item identified by path will be drawn.
boolean | getExpandedState(TreePath path) Returns true if the path is expanded, and visible.
TreePath | getPathClosestTo(int x, int y) Returns the path to the node that is closest to x,y.
TreePath | getPathForRow(int row) Returns the path for row.
int | getPreferredHeight() Returns the preferred height.
int | getPreferredWidth(Rectangle bounds) Returns the preferred width and height for the region in visibleRegion.
int | getRowCount() Returns the number of visible rows.
int | getRowForPath(TreePath path) Returns the row where the last item identified in path is visible.
int | getVisibleChildCount(TreePath path) Returns the number of visible children for path.
Enumeration<TreePath> | getVisiblePathsFrom(TreePath path) Returns an Enumerator that increments over the visible paths starting at the passed in location.
void | invalidatePathBounds(TreePath path) Instructs the LayoutCache that the bounds for path are invalid, and need to be updated.
void | invalidateSizes() Informs the TreeState that it needs to recalculate all the sizes it is referencing.
boolean | isExpanded(TreePath path) Returns true if the value identified by path is currently expanded.
void | setExpandedState(TreePath path, boolean isExpanded) Marks the path path expanded state to isExpanded.
void | setModel(TreeModel newModel) Sets the TreeModel that will provide the data.
void | setNodeDimensions(AbstractLayoutCache.NodeDimensions nd) Sets the renderer that is responsible for drawing nodes in the tree.
void | setRootVisible(boolean rootVisible) Determines whether or not the root node from the TreeModel is visible.
void | setRowHeight(int rowHeight) Sets the height of each cell.
void | treeNodesChanged(TreeModelEvent e) Invoked after a node (or a set of siblings) has changed in some way.
void | treeNodesInserted(TreeModelEvent e) Invoked after nodes have been inserted into the tree.
void | treeNodesRemoved(TreeModelEvent e) Invoked after nodes have been removed from the tree.
void | treeStructureChanged(TreeModelEvent e) Invoked after the tree has drastically changed structure from a given node down.
Methods inherited from class javax.swing.tree.AbstractLayoutCache
getModel, getNodeDimensions, getNodeDimensions, getRowHeight, getRowsForPaths, getSelectionModel, isFixedRowHeight, isRootVisible, setSelectionModel
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

VariableHeightLayoutCache

public VariableHeightLayoutCache()
Method Detail

setModel

public void setModel(TreeModel newModel)
Sets the TreeModel that will provide the data.

Overrides:
setModel in class AbstractLayoutCache
Parameters:
newModel - the TreeModel that is to provide the data

setRootVisible

public void setRootVisible(boolean rootVisible)
Determines whether or not the root node from the TreeModel is visible.

Overrides:
setRootVisible in class AbstractLayoutCache
Parameters:
rootVisible - true if the root node of the tree is to be displayed
See Also:
AbstractLayoutCache.rootVisible

setRowHeight

public void setRowHeight(int rowHeight)
Sets the height of each cell. If the specified value is less than or equal to zero the current cell renderer is queried for each row's height.

Overrides:
setRowHeight in class AbstractLayoutCache
Parameters:
rowHeight - the height of each cell, in pixels

setNodeDimensions

public void setNodeDimensions(AbstractLayoutCache.NodeDimensions nd)
Sets the renderer that is responsible for drawing nodes in the tree.

Overrides:
setNodeDimensions in class AbstractLayoutCache
Parameters:
nd - the renderer

setExpandedState

public void setExpandedState(TreePath path,
                             boolean isExpanded)
Marks the path path expanded state to isExpanded.

Specified by:
setExpandedState in class AbstractLayoutCache
Parameters:
path - the TreePath of interest
isExpanded - true if the path should be expanded, otherwise false

getExpandedState

public boolean getExpandedState(TreePath path)
Returns true if the path is expanded, and visible.

Specified by:
getExpandedState in class AbstractLayoutCache
Parameters:
path - the path being queried
Returns:
true if the path is expanded and visible, otherwise false

getBounds

public Rectangle getBounds(TreePath path,
                           Rectangle placeIn)
Returns the Rectangle enclosing the label portion into which the item identified by path will be drawn.

Specified by:
getBounds in class AbstractLayoutCache
Parameters:
path - the path to be drawn
placeIn - the bounds of the enclosing rectangle
Returns:
the bounds of the enclosing rectangle or null if the node could not be ascertained

getPathForRow

public TreePath getPathForRow(int row)
Returns the path for row. If row is not visible, null is returned.

Specified by:
getPathForRow in class AbstractLayoutCache
Parameters:
row - the location of interest
Returns:
the path for row, or null if row is not visible

getRowForPath

public int getRowForPath(TreePath path)
Returns the row where the last item identified in path is visible. Will return -1 if any of the elements in path are not currently visible.

Specified by:
getRowForPath in class AbstractLayoutCache
Parameters:
path - the TreePath of interest
Returns:
the row where the last item in path is visible

getRowCount

public int getRowCount()
Returns the number of visible rows.

Specified by:
getRowCount in class AbstractLayoutCache
Returns:
the number of visible rows

invalidatePathBounds

public void invalidatePathBounds(TreePath path)
Instructs the LayoutCache that the bounds for path are invalid, and need to be updated.

Specified by:
invalidatePathBounds in class AbstractLayoutCache
Parameters:
path - the TreePath which is now invalid

getPreferredHeight

public int getPreferredHeight()
Returns the preferred height.

Overrides:
getPreferredHeight in class AbstractLayoutCache
Returns:
the preferred height

getPreferredWidth

public int getPreferredWidth(Rectangle bounds)
Returns the preferred width and height for the region in visibleRegion.

Overrides:
getPreferredWidth in class AbstractLayoutCache
Parameters:
bounds - the region being queried
Returns:
the preferred width for the passed in region

getPathClosestTo

public TreePath getPathClosestTo(int x,
                                 int y)
Returns the path to the node that is closest to x,y. If there is nothing currently visible this will return null, otherwise it will always return a valid path. If you need to test if the returned object is exactly at x, y you should get the bounds for the returned path and test x, y against that.

Specified by:
getPathClosestTo in class AbstractLayoutCache
Parameters:
x - the x-coordinate
y - the y-coordinate
Returns:
the path to the node that is closest to x, y

getVisiblePathsFrom

public Enumeration<TreePath> getVisiblePathsFrom(TreePath path)
Returns an Enumerator that increments over the visible paths starting at the passed in location. The ordering of the enumeration is based on how the paths are displayed.

Specified by:
getVisiblePathsFrom in class AbstractLayoutCache
Parameters:
path - the location in the TreePath to start
Returns:
an Enumerator that increments over the visible paths

getVisibleChildCount

public int getVisibleChildCount(TreePath path)
Returns the number of visible children for path.

Specified by:
getVisibleChildCount in class AbstractLayoutCache
Parameters:
path - the path being queried
Returns:
the number of visible children for path

invalidateSizes

public void invalidateSizes()
Informs the TreeState that it needs to recalculate all the sizes it is referencing.

Specified by:
invalidateSizes in class AbstractLayoutCache

isExpanded

public boolean isExpanded(TreePath path)
Returns true if the value identified by path is currently expanded.

Specified by:
isExpanded in class AbstractLayoutCache
Returns:
true if the value identified by path is currently expanded

treeNodesChanged

public void treeNodesChanged(TreeModelEvent e)
Invoked after a node (or a set of siblings) has changed in some way. The node(s) have not changed locations in the tree or altered their children arrays, but other attributes have changed and may affect presentation. Example: the name of a file has changed, but it is in the same location in the file system.

e.path returns the path the parent of the changed node(s).

e.childIndices returns the index(es) of the changed node(s).

Specified by:
treeNodesChanged in class AbstractLayoutCache
Parameters:
e - the TreeModelEvent of interest

treeNodesInserted

public void treeNodesInserted(TreeModelEvent e)
Invoked after nodes have been inserted into the tree.

e.path returns the parent of the new nodes.

e.childIndices returns the indices of the new nodes in ascending order.

Specified by:
treeNodesInserted in class AbstractLayoutCache
Parameters:
e - the TreeModelEvent of interest

treeNodesRemoved

public void treeNodesRemoved(TreeModelEvent e)
Invoked after nodes have been removed from the tree. Note that if a subtree is removed from the tree, this method may only be invoked once for the root of the removed subtree, not once for each individual set of siblings removed.

e.path returns the former parent of the deleted nodes.

e.childIndices returns the indices the nodes had before they were deleted in ascending order.

Specified by:
treeNodesRemoved in class AbstractLayoutCache
Parameters:
e - the TreeModelEvent of interest

treeStructureChanged

public void treeStructureChanged(TreeModelEvent e)
Invoked after the tree has drastically changed structure from a given node down. If the path returned by e.getPath is of length one and the first element does not identify the current root node the first element should become the new root of the tree.

e.path holds the path to the node.

e.childIndices returns null.

Specified by:
treeStructureChanged in class AbstractLayoutCache
Parameters:
e - the TreeModelEvent of interest
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


UIDefaults

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class UIDefaults

java.lang.Object
    extended by  java.util.Dictionary<K,V>
        extended by  java.util.Hashtable<Object,Object>
            extended by  javax.swing.UIDefaults
All Implemented Interfaces:
Serializable, Cloneable, Map<Object,Object>
public class UIDefaults
extends Hashtable<Object,Object>

A table of defaults for Swing components. Applications can set/get default values via the UIManager.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

See Also:
UIManager

Nested Class Summary
static interface | UIDefaults.ActiveValue This class enables one to store an entry in the defaults table that's constructed each time it's looked up with one of the getXXX(key) methods.
static class | UIDefaults.LazyInputMap LazyInputMap will create a InputMap in its createValue method.
static interface | UIDefaults.LazyValue This class enables one to store an entry in the defaults table that isn't constructed until the first time it's looked up with one of the getXXX(key) methods.
static class | UIDefaults.ProxyLazyValue This class provides an implementation of LazyValue which can be used to delay loading of the Class for the instance to be created.
Constructor Summary
UIDefaults()
Creates an empty defaults table.
UIDefaults(int initialCapacity, float loadFactor)
Creates an empty defaults table with the specified initial capacity and load factor.
UIDefaults(Object[] keyValueList)
Creates a defaults table initialized with the specified key/value pairs.
Method Summary
 void addPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list.
 void addResourceBundle(String bundleName)
Adds a resource bundle to the list of resource bundles that are searched for localized values.
protected  void firePropertyChange(String propertyName, Object oldValue, Object newValue)
Support for reporting bound property changes.
 Object get(Object key)
Returns the value for key.
 Object get(Object key, Locale l)
Returns the value for key associated with the given locale.
 boolean getBoolean(Object key)
If the value of key is boolean, return the boolean value, otherwise return false.
 boolean getBoolean(Object key, Locale l)
If the value of key for the given Locale is boolean, return the boolean value, otherwise return false.
 Border getBorder(Object key)
If the value of key is a Border return it, otherwise return null.
 Border getBorder(Object key, Locale l)
If the value of key for the given Locale is a Border return it, otherwise return null.
 Color getColor(Object key)
If the value of key is a Color return it, otherwise return null.
 Color getColor(Object key, Locale l)
If the value of key for the given Locale is a Color return it, otherwise return null.
 Locale getDefaultLocale()
Returns the default locale.
 Dimension getDimension(Object key)
If the value of key is a Dimension return it, otherwise return null.
 Dimension getDimension(Object key, Locale l)
If the value of key for the given Locale is a Dimension return it, otherwise return null.
 Font getFont(Object key)
If the value of key is a Font return it, otherwise return null.
 Font getFont(Object key, Locale l)
If the value of key for the given Locale is a Font return it, otherwise return null.
 Icon getIcon(Object key)
If the value of key is an Icon return it, otherwise return null.
 Icon getIcon(Object key, Locale l)
If the value of key for the given Locale is an Icon return it, otherwise return null.
 Insets getInsets(Object key)
If the value of key is an Insets return it, otherwise return null.
 Insets getInsets(Object key, Locale l)
If the value of key for the given Locale is an Insets return it, otherwise return null.
 int getInt(Object key)
If the value of key is an Integer return its integer value, otherwise return 0.
 int getInt(Object key, Locale l)
If the value of key for the given Locale is an Integer return its integer value, otherwise return 0.
 PropertyChangeListener[] getPropertyChangeListeners()
Returns an array of all the PropertyChangeListeners added to this UIDefaults with addPropertyChangeListener().
 String getString(Object key)
If the value of key is a String return it, otherwise return null.
 String getString(Object key, Locale l)
If the value of key for the given Locale is a String return it, otherwise return null.
 ComponentUI getUI(JComponent target)
Creates an ComponentUI implementation for the specified component.
 Class<? extends ComponentUI> getUIClass(String uiClassID)
Returns the L&F class that renders this component.
 Class<? extends ComponentUI> getUIClass(String uiClassID, ClassLoader uiClassLoader)
The value of get(uidClassID) must be the String name of a class that implements the corresponding ComponentUI class.
protected  void getUIError(String msg)
If getUI() fails for any reason, it calls this method before returning null.
 Object put(Object key, Object value)
Sets the value of key to value for all locales.
 void putDefaults(Object[] keyValueList)
Puts all of the key/value pairs in the database and unconditionally generates one PropertyChangeEvent.
 void removePropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list.
 void removeResourceBundle(String bundleName)
Removes a resource bundle from the list of resource bundles that are searched for localized defaults.
 void setDefaultLocale(Locale l)
Sets the default locale.
Methods inherited from class java.util.Hashtable
clear, clone, contains, containsKey, containsValue, elements, entrySet, equals, hashCode, isEmpty, keys, keySet, putAll, rehash, remove, size, toString, values
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

UIDefaults

public UIDefaults()
Creates an empty defaults table.

UIDefaults

public UIDefaults(int initialCapacity,
                  float loadFactor)
Creates an empty defaults table with the specified initial capacity and load factor.

Parameters:
initialCapacity - the initial capacity of the defaults table
loadFactor - the load factor of the defaults table
Since:
1.6
See Also:
Hashtable

UIDefaults

public UIDefaults(Object[] keyValueList)
Creates a defaults table initialized with the specified key/value pairs. For example:
        Object[] uiDefaults = {
             "Font", new Font("Dialog", Font.BOLD, 12),
            "Color", Color.red,
             "five", new Integer(5)
        }
        UIDefaults myDefaults = new UIDefaults(uiDefaults);

Parameters:
keyValueList - an array of objects containing the key/value pairs
Method Detail

get

public Object get(Object key)
Returns the value for key. If the value is a UIDefaults.LazyValue then the real value is computed with LazyValue.createValue(), the table entry is replaced, and the real value is returned. If the value is an UIDefaults.ActiveValue the table entry is not replaced - the value is computed with ActiveValue.createValue() for each get() call. If the key is not found in the table then it is searched for in the list of resource bundles maintained by this object. The resource bundles are searched most recently added first using the locale returned by getDefaultLocale. LazyValues and ActiveValues are not supported in the resource bundles.

Specified by:
get in interface Map<Object,Object>
Overrides:
get in class Hashtable<Object,Object>
Parameters:
key - the desired key
Returns:
the value for key
Since:
1.4
See Also:
UIDefaults.LazyValue,
UIDefaults.ActiveValue,
Hashtable.get(java.lang.Object),
getDefaultLocale(),
addResourceBundle(java.lang.String)

get

public Object get(Object key,
                  Locale l)
Returns the value for key associated with the given locale. If the value is a UIDefaults.LazyValue then the real value is computed with LazyValue.createValue(), the table entry is replaced, and the real value is returned. If the value is an UIDefaults.ActiveValue the table entry is not replaced - the value is computed with ActiveValue.createValue() for each get() call. If the key is not found in the table then it is searched for in the list of resource bundles maintained by this object. The resource bundles are searched most recently added first using the given locale. LazyValues and ActiveValues are not supported in the resource bundles.

Parameters:
key - the desired key
l - the desired locale
Returns:
the value for key
Since:
1.4
See Also:
UIDefaults.LazyValue, UIDefaults.ActiveValue, Hashtable.get(java.lang.Object), addResourceBundle(java.lang.String)

put

public Object put(Object key,
                  Object value)
Sets the value of key to value for all locales. If key is a string and the new value isn't equal to the old one, fire a PropertyChangeEvent. If value is null, the key is removed from the table.

Specified by:
put in interface Map<Object,Object>
Overrides:
put in class Hashtable<Object,Object>
Parameters:
key - the unique Object who's value will be used to retrieve the data value associated with it
value - the new Object to store as data under that key
Returns:
the previous Object value, or null
See Also:
putDefaults(java.lang.Object[]), Hashtable.put(K, V)

putDefaults

public void putDefaults(Object[] keyValueList)
Puts all of the key/value pairs in the database and unconditionally generates one PropertyChangeEvent. The events oldValue and newValue will be null and its propertyName will be "UIDefaults". The key/value pairs are added for all locales.

Parameters:
keyValueList - an array of key/value pairs
See Also:
put(java.lang.Object, java.lang.Object), Hashtable.put(K, V)

getFont

public Font getFont(Object key)
If the value of key is a Font return it, otherwise return null.

Parameters:
key - the desired key
Returns:
if the value for key is a Font, return the Font object; otherwise return null

getFont

public Font getFont(Object key,
                    Locale l)
If the value of key for the given Locale is a Font return it, otherwise return null.

Parameters:
key - the desired key
l - the desired locale
Returns:
if the value for key and Locale is a Font, return the Font object; otherwise return null
Since:
1.4

getColor

public Color getColor(Object key)
If the value of key is a Color return it, otherwise return null.

Parameters:
key - the desired key
Returns:
if the value for key is a Color, return the Color object; otherwise return null

getColor

public Color getColor(Object key,
                      Locale l)
If the value of key for the given Locale is a Color return it, otherwise return null.

Parameters:
key - the desired key
l - the desired locale
Returns:
if the value for key and Locale is a Color, return the Color object; otherwise return null
Since:
1.4

getIcon

public Icon getIcon(Object key)
If the value of key is an Icon return it, otherwise return null.

Parameters:
key - the desired key
Returns:
if the value for key is an Icon, return the Icon object; otherwise return null

getIcon

public Icon getIcon(Object key,
                    Locale l)
If the value of key for the given Locale is an Icon return it, otherwise return null.

Parameters:
key - the desired key
l - the desired locale
Returns:
if the value for key and Locale is an Icon, return the Icon object; otherwise return null
Since:
1.4

getBorder

public Border getBorder(Object key)
If the value of key is a Border return it, otherwise return null.

Parameters:
key - the desired key
Returns:
if the value for key is a Border, return the Border object; otherwise return null

getBorder

public Border getBorder(Object key,
                        Locale l)
If the value of key for the given Locale is a Border return it, otherwise return null.

Parameters:
key - the desired key
l - the desired locale
Returns:
if the value for key and Locale is a Border, return the Border object; otherwise return null
Since:
1.4

getString

public String getString(Object key)
If the value of key is a String return it, otherwise return null.

Parameters:
key - the desired key
Returns:
if the value for key is a String, return the String object; otherwise return null

getString

public String getString(Object key,
                        Locale l)
If the value of key for the given Locale is a String return it, otherwise return null.

Parameters:
key - the desired key
l - the desired Locale
Returns:
if the value for key for the given Locale is a String, return the String object; otherwise return null
Since:
1.4

getInt

public int getInt(Object key)
If the value of key is an Integer return its integer value, otherwise return 0.

Parameters:
key - the desired key
Returns:
if the value for key is an Integer, return its value, otherwise return 0

getInt

public int getInt(Object key,
                  Locale l)
If the value of key for the given Locale is an Integer return its integer value, otherwise return 0.

Parameters:
key - the desired key
l - the desired locale
Returns:
if the value for key and Locale is an Integer, return its value, otherwise return 0
Since:
1.4

getBoolean

public boolean getBoolean(Object key)
If the value of key is boolean, return the boolean value, otherwise return false.

Parameters:
key - an Object specifying the key for the desired boolean value
Returns:
if the value of key is boolean, return the boolean value, otherwise return false.
Since:
1.4

getBoolean

public boolean getBoolean(Object key,
                          Locale l)
If the value of key for the given Locale is boolean, return the boolean value, otherwise return false.

Parameters:
key - an Object specifying the key for the desired boolean value
l - the desired locale
Returns:
if the value for key and Locale is boolean, return the boolean value, otherwise return false.
Since:
1.4

getInsets

public Insets getInsets(Object key)
If the value of key is an Insets return it, otherwise return null.

Parameters:
key - the desired key
Returns:
if the value for key is an Insets, return the Insets object; otherwise return null

getInsets

public Insets getInsets(Object key,
                        Locale l)
If the value of key for the given Locale is an Insets return it, otherwise return null.

Parameters:
key - the desired key
l - the desired locale
Returns:
if the value for key and Locale is an Insets, return the Insets object; otherwise return null
Since:
1.4

getDimension

public Dimension getDimension(Object key)
If the value of key is a Dimension return it, otherwise return null.

Parameters:
key - the desired key
Returns:
if the value for key is a Dimension, return the Dimension object; otherwise return null

getDimension

public Dimension getDimension(Object key,
                              Locale l)
If the value of key for the given Locale is a Dimension return it, otherwise return null.

Parameters:
key - the desired key
l - the desired locale
Returns:
if the value for key and Locale is a Dimension, return the Dimension object; otherwise return null
Since:
1.4

getUIClass

public Class<? extends ComponentUI> getUIClass(String uiClassID,
                                               ClassLoader uiClassLoader)
The value of get(uidClassID) must be the String name of a class that implements the corresponding ComponentUI class. If the class hasn't been loaded before, this method looks up the class with uiClassLoader.loadClass() if a non null class loader is provided, classForName() otherwise.

If a mapping for uiClassID exists or if the specified class can't be found, return null.

This method is used by getUI, it's usually not necessary to call it directly.

Parameters:
uiClassID - a string containing the class ID
uiClassLoader - the object which will load the class
Returns:
the value of Class.forName(get(uidClassID))
See Also:
getUI(javax.swing.JComponent)

getUIClass

public Class<? extends ComponentUI> getUIClass(String uiClassID)
Returns the L&F class that renders this component.

Parameters:
uiClassID - a string containing the class ID
Returns:
the Class object returned by getUIClass(uiClassID, null)

getUIError

protected void getUIError(String msg)
If getUI() fails for any reason, it calls this method before returning null. Subclasses may choose to do more or less here.

Parameters:
msg - message string to print
See Also:
getUI(javax.swing.JComponent)

getUI

public ComponentUI getUI(JComponent target)
Creates an ComponentUI implementation for the specified component. In other words create the look and feel specific delegate object for target. This is done in two steps:
  • Look up the name of the ComponentUI implementation class under the value returned by target.getUIClassID().
  • Use the implementation classes static createUI() method to construct a look and feel delegate.

Parameters:
target - the JComponent which needs a UI
Returns:
the ComponentUI object

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list. The listener is registered for all properties.

A PropertyChangeEvent will get fired whenever a default is changed.

Parameters:
listener - the PropertyChangeListener to be added
See Also:
PropertyChangeSupport

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties.

Parameters:
listener - the PropertyChangeListener to be removed
See Also:
PropertyChangeSupport

getPropertyChangeListeners

public PropertyChangeListener[] getPropertyChangeListeners()
Returns an array of all the PropertyChangeListeners added to this UIDefaults with addPropertyChangeListener().

Returns:
all of the PropertyChangeListeners added or an empty array if no listeners have been added
Since:
1.4

firePropertyChange

protected void firePropertyChange(String propertyName,
                                  Object oldValue,
                                  Object newValue)
Support for reporting bound property changes. If oldValue and newValue are not equal and the PropertyChangeEventx listener list isn't empty, then fire a PropertyChange event to each listener.

Parameters:
propertyName - the programmatic name of the property that was changed
oldValue - the old value of the property
newValue - the new value of the property
See Also:
PropertyChangeSupport

addResourceBundle

public void addResourceBundle(String bundleName)
Adds a resource bundle to the list of resource bundles that are searched for localized values. Resource bundles are searched in the reverse order they were added. In other words, the most recently added bundle is searched first.

Parameters:
bundleName - the base name of the resource bundle to be added
Since:
1.4
See Also:
ResourceBundle, removeResourceBundle(java.lang.String)

removeResourceBundle

public void removeResourceBundle(String bundleName)
Removes a resource bundle from the list of resource bundles that are searched for localized defaults.

Parameters:
bundleName - the base name of the resource bundle to be removed
Since:
1.4
See Also:
ResourceBundle, addResourceBundle(java.lang.String)

setDefaultLocale

public void setDefaultLocale(Locale l)
Sets the default locale. The default locale is used in retrieving localized values via get methods that do not take a locale argument. As of release 1.4, Swing UI objects should retrieve localized values using the locale of their component rather than the default locale. The default locale exists to provide compatibility with pre 1.4 behaviour.

Parameters:
l - the new default locale
Since:
1.4
See Also:
getDefaultLocale(), get(Object), get(Object,Locale)

getDefaultLocale

public Locale getDefaultLocale()
Returns the default locale. The default locale is used in retrieving localized values via get methods that do not take a locale argument. As of release 1.4, Swing UI objects should retrieve localized values using the locale of their component rather than the default locale. The default locale exists to provide compatibility with pre 1.4 behaviour.

Returns:
the default locale
Since:
1.4
See Also:
setDefaultLocale(java.util.Locale), get(Object), get(Object,Locale)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UIDefaults.ActiveValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface UIDefaults.ActiveValue

Enclosing class:
UIDefaults
public static interface UIDefaults.ActiveValue

This class enables one to store an entry in the defaults table that's constructed each time it's looked up with one of the getXXX(key) methods. Here's an example of an ActiveValue that constructs a DefaultListCellRenderer:

  Object cellRendererActiveValue = new UIDefaults.ActiveValue() {
      public Object createValue(UIDefaults table) {
          return new DefaultListCellRenderer();
      }
  };

  uiDefaultsTable.put("MyRenderer", cellRendererActiveValue);

See Also:
UIDefaults.get(java.lang.Object)

Method Summary
 Object createValue(UIDefaults table)
Creates the value retrieved from the UIDefaults table.

Method Detail

createValue

Object createValue(UIDefaults table)
Creates the value retrieved from the UIDefaults table. The object is created each time it is accessed.

Parameters:
table - a UIDefaults table
Returns:
the created Object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UIDefaults.LazyInputMap

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class UIDefaults.LazyInputMap

java.lang.Object
    extended by  javax.swing.UIDefaults.LazyInputMap
All Implemented Interfaces:
UIDefaults.LazyValue
Enclosing class:
UIDefaults
public static class UIDefaults.LazyInputMap
extends Object
implements UIDefaults.LazyValue

LazyInputMap will create a InputMap in its createValue method. The bindings are passed in in the constructor. The bindings are an array with the even number entries being string KeyStrokes (eg "alt SPACE") and the odd number entries being the value to use in the InputMap (and the key in the ActionMap).

Since:
1.3

Constructor Summary
UIDefaults.LazyInputMap(Object[] bindings)
Method Summary
 Object createValue(UIDefaults table)
Creates an InputMap with the bindings that are passed in.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UIDefaults.LazyInputMap

public UIDefaults.LazyInputMap(Object[] bindings)
Method Detail

createValue

public Object createValue(UIDefaults table)
Creates an InputMap with the bindings that are passed in.

Specified by:
createValue in interface UIDefaults.LazyValue
Parameters:
table - a UIDefaults table
Returns:
the InputMap
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UIDefaults.LazyValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface UIDefaults.LazyValue

All Known Implementing Classes:
UIDefaults.LazyInputMap, UIDefaults.ProxyLazyValue
Enclosing class:
UIDefaults
public static interface UIDefaults.LazyValue

This class enables one to store an entry in the defaults table that isn't constructed until the first time it's looked up with one of the getXXX(key) methods. Lazy values are useful for defaults that are expensive to construct or are seldom retrieved. The first time a LazyValue is retrieved its "real value" is computed by calling LazyValue.createValue() and the real value is used to replace the LazyValue in the UIDefaults table. Subsequent lookups for the same key return the real value. Here's an example of a LazyValue that constructs a Border:

  Object borderLazyValue = new UIDefaults.LazyValue() {
      public Object createValue(UIDefaults table) {
          return new BorderFactory.createLoweredBevelBorder();
      }
  };

  uiDefaultsTable.put("MyBorder", borderLazyValue);

See Also:
UIDefaults.get(java.lang.Object)

Method Summary
 Object createValue(UIDefaults table)
Creates the actual value retrieved from the UIDefaults table.

Method Detail

createValue

Object createValue(UIDefaults table)
Creates the actual value retrieved from the UIDefaults table. When an object that implements this interface is retrieved from the table, this method is used to create the real value, which is then stored in the table and returned to the calling method.

Parameters:
table - a UIDefaults table
Returns:
the created Object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UIDefaults.ProxyLazyValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class UIDefaults.ProxyLazyValue

java.lang.Object
    extended by  javax.swing.UIDefaults.ProxyLazyValue
All Implemented Interfaces:
UIDefaults.LazyValue
Enclosing class:
UIDefaults
public static class UIDefaults.ProxyLazyValue
extends Object
implements UIDefaults.LazyValue

This class provides an implementation of LazyValue which can be used to delay loading of the Class for the instance to be created. It also avoids creation of an anonymous inner class for the LazyValue subclass. Both of these improve performance at the time that a a Look and Feel is loaded, at the cost of a slight performance reduction the first time createValue is called (since Reflection APIs are used).

Since:
1.3

Constructor Summary
UIDefaults.ProxyLazyValue(String c)
Creates a LazyValue which will construct an instance when asked.
UIDefaults.ProxyLazyValue(String c, Object[] o)
Creates a LazyValue which will construct an instance when asked.
UIDefaults.ProxyLazyValue(String c, String m)
Creates a LazyValue which will construct an instance when asked.
UIDefaults.ProxyLazyValue(String c, String m, Object[] o)
Creates a LazyValue which will construct an instance when asked.
Method Summary
 Object createValue(UIDefaults table)
Creates the value retrieved from the UIDefaults table.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UIDefaults.ProxyLazyValue

public UIDefaults.ProxyLazyValue(String c)
Creates a LazyValue which will construct an instance when asked.

Parameters:
c - a String specifying the classname of the instance to be created on demand

UIDefaults.ProxyLazyValue

public UIDefaults.ProxyLazyValue(String c,
                                 String m)
Creates a LazyValue which will construct an instance when asked.

Parameters:
c - a String specifying the classname of the class containing a static method to be called for instance creation
m - a String specifying the static method to be called on class c

UIDefaults.ProxyLazyValue

public UIDefaults.ProxyLazyValue(String c,
                                 Object[] o)
Creates a LazyValue which will construct an instance when asked.

Parameters:
c - a String specifying the classname of the instance to be created on demand
o - an array of Objects to be passed as paramaters to the constructor in class c

UIDefaults.ProxyLazyValue

public UIDefaults.ProxyLazyValue(String c,
                                 String m,
                                 Object[] o)
Creates a LazyValue which will construct an instance when asked.

Parameters:
c - a String specifying the classname of the class containing a static method to be called for instance creation.
m - a String specifying the static method to be called on class c
o - an array of Objects to be passed as paramaters to the static method in class c
Method Detail

createValue

public Object createValue(UIDefaults table)
Creates the value retrieved from the UIDefaults table. The object is created each time it is accessed.

Specified by:
createValue in interface UIDefaults.LazyValue
Parameters:
table - a UIDefaults table
Returns:
the created Object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UIManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class UIManager

java.lang.Object
    extended by  javax.swing.UIManager
All Implemented Interfaces:
Serializable
public class UIManager
extends Object
implements Serializable

UIManager manages the current look and feel, the set of available look and feels, PropertyChangeListeners that are notified when the look and feel changes, look and feel defaults, and convenience methods for obtaining various default values.

Specifying the look and feel

The look and feel can be specified in two distinct ways: by specifying the fully qualified name of the class for the look and feel, or by creating an instance of LookAndFeel and passing it to setLookAndFeel. The following example illustrates setting the look and feel to the system look and feel:
   UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName());
The following example illustrates setting the look and feel based on class name:
   UIManager.setLookAndFeel("javax.swing.plaf.metal.MetalLookAndFeel");
Once the look and feel has been changed it is imperative to invoke updateUI on all JComponents. The method SwingUtilities.updateComponentTreeUI(java.awt.Component) makes it easy to apply updateUI to a containment hierarchy. Refer to it for details. The exact behavior of not invoking updateUI after changing the look and feel is unspecified. It is very possible to receive unexpected exceptions, painting problems, or worse.

Default look and feel

The class used for the default look and feel is chosen in the following manner:
  1. If the system property swing.defaultlaf is non-null, use its value as the default look and feel class name.
  2. If the Properties file swing.properties exists and contains the key swing.defaultlaf, use its value as the default look and feel class name. The location that is checked for swing.properties may vary depending upon the implementation of the Java platform. In Sun's implementation the location is ${java.home}/lib/swing.properties. Refer to the release notes of the implementation being used for further details.
  3. Otherwise use the cross platform look and feel.

Defaults

UIManager manages three sets of UIDefaults. In order, they are:
  1. Developer defaults. With few exceptions Swing does not alter the developer defaults; these are intended to be modified and used by the developer.
  2. Look and feel defaults. The look and feel defaults are supplied by the look and feel at the time it is installed as the current look and feel (setLookAndFeel() is invoked). The look and feel defaults can be obtained using the getLookAndFeelDefaults() method.
  3. Sytem defaults. The system defaults are provided by Swing.
Invoking any of the various get methods results in checking each of the defaults, in order, returning the first non-null value. For example, invoking UIManager.getString("Table.foreground") results in first checking developer defaults. If the developer defaults contain a value for "Table.foreground" it is returned, otherwise the look and feel defaults are checked, followed by the system defaults.

It's important to note that getDefaults returns a custom instance of UIDefaults with this resolution logic built into it. For example, UIManager.getDefaults().getString("Table.foreground") is equivalent to UIManager.getString("Table.foreground"). Both resolve using the algorithm just described. In many places the documentation uses the word defaults to refer to the custom instance of UIDefaults with the resolution logic as previously described.

When the look and feel is changed, UIManager alters only the look and feel defaults; the developer and system defaults are not altered by the UIManager in any way.

The set of defaults a particular look and feel supports is defined and documented by that look and feel. In addition, each look and feel, or ComponentUI provided by a look and feel, may access the defaults at different times in their life cycle. Some look and feels may agressively look up defaults, so that changing a default may not have an effect after installing the look and feel. Other look and feels may lazily access defaults so that a change to the defaults may effect an existing look and feel. Finally, other look and feels might not configure themselves from the defaults table in any way. None-the-less it is usually the case that a look and feel expects certain defaults, so that in general a ComponentUI provided by one look and feel will not work with another look and feel.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
static class UIManager.LookAndFeelInfo
Provides a little information about an installed LookAndFeel for the sake of configuring a menu or for initial application set up.
Constructor Summary
UIManager()
Method Summary
static void addAuxiliaryLookAndFeel(LookAndFeel laf)
Adds a LookAndFeel to the list of auxiliary look and feels.
static void addPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list.
static Object get(Object key)
Returns an object from the defaults.
static Object get(Object key, Locale l)
Returns an object from the defaults that is appropriate for the given locale.
static LookAndFeel[] getAuxiliaryLookAndFeels()
Returns the list of auxiliary look and feels (can be null).
static boolean getBoolean(Object key)
Returns a boolean from the defaults which is associated with the key value.
static boolean getBoolean(Object key, Locale l)
Returns a boolean from the defaults which is associated with the key value and the given Locale.
static Border getBorder(Object key)
Returns a border from the defaults.
static Border getBorder(Object key, Locale l)
Returns a border from the defaults that is appropriate for the given locale.
static Color getColor(Object key)
Returns a color from the defaults.
static Color getColor(Object key, Locale l)
Returns a color from the defaults that is appropriate for the given locale.
static String getCrossPlatformLookAndFeelClassName()
Returns the name of the LookAndFeel class that implements the default cross platform look and feel -- the Java Look and Feel (JLF).
static UIDefaults getDefaults()
Returns the defaults.
static Dimension getDimension(Object key)
Returns a dimension from the defaults.
static Dimension getDimension(Object key, Locale l)
Returns a dimension from the defaults that is appropriate for the given locale.
static Font getFont(Object key)
Returns a font from the defaults.
static Font getFont(Object key, Locale l)
Returns a font from the defaults that is appropriate for the given locale.
static Icon getIcon(Object key)
Returns an Icon from the defaults.
static Icon getIcon(Object key, Locale l)
Returns an Icon from the defaults that is appropriate for the given locale.
static Insets getInsets(Object key)
Returns an Insets object from the defaults.
static Insets getInsets(Object key, Locale l)
Returns an Insets object from the defaults that is appropriate for the given locale.
static UIManager.LookAndFeelInfo[] getInstalledLookAndFeels()
Returns an array of LookAndFeelInfos representing the LookAndFeel implementations currently available.
static int getInt(Object key)
Returns an integer from the defaults.
static int getInt(Object key, Locale l)
Returns an integer from the defaults that is appropriate for the given locale.
static LookAndFeel getLookAndFeel()
Returns the current look and feel or null.
static UIDefaults getLookAndFeelDefaults()
Returns the UIDefaults from the current look and feel, that were obtained at the time the look and feel was installed.
static PropertyChangeListener[] getPropertyChangeListeners()
Returns an array of all the PropertyChangeListeners added to this UIManager with addPropertyChangeListener().
static String getString(Object key)
Returns a string from the defaults.
static String getString(Object key, Locale l)
Returns a string from the defaults that is appropriate for the given locale.
static String getSystemLookAndFeelClassName()
Returns the name of the LookAndFeel class that implements the native system look and feel if there is one, otherwise the name of the default cross platform LookAndFeel class.
static ComponentUI getUI(JComponent target)
Returns the appropriate ComponentUI implementation for target.
static void installLookAndFeel(String name, String className)
Adds the specified look and feel to the set of available look and feels.
static void installLookAndFeel(UIManager.LookAndFeelInfo info)
Adds the specified look and feel to the set of available look and feels.
static Object put(Object key, Object value)
Stores an object in the developer defaults.
static boolean removeAuxiliaryLookAndFeel(LookAndFeel laf)
Removes a LookAndFeel from the list of auxiliary look and feels.
static void removePropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list.
static void setInstalledLookAndFeels(UIManager.LookAndFeelInfo[] infos)
Sets the set of available look and feels.
static void setLookAndFeel(LookAndFeel newLookAndFeel)
Sets the current look and feel to newLookAndFeel.
static void setLookAndFeel(String className)
Loads the LookAndFeel specified by the given class name, using the current thread's context class loader, and passes it to setLookAndFeel(LookAndFeel).
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UIManager

public UIManager()
Method Detail

getInstalledLookAndFeels

public static UIManager.LookAndFeelInfo[] getInstalledLookAndFeels()
Returns an array of LookAndFeelInfos representing the LookAndFeel implementations currently available. The LookAndFeelInfo objects can be used by an application to construct a menu of look and feel options for the user, or to determine which look and feel to set at startup time. To avoid the penalty of creating numerous LookAndFeel objects, LookAndFeelInfo maintains the class name of the LookAndFeel class, not the actual LookAndFeel instance.

The following example illustrates setting the current look and feel from an instance of LookAndFeelInfo:

   UIManager.setLookAndFeel(info.getClassName());

Returns:
an array of LookAndFeelInfo objects
See Also:
setLookAndFeel(javax.swing.LookAndFeel)

setInstalledLookAndFeels

public static void setInstalledLookAndFeels(UIManager.LookAndFeelInfo[] infos)
                                     throws SecurityException
Sets the set of available look and feels. While this method does not check to ensure all of the LookAndFeelInfos are non-null, it is strongly recommended that only non-null values are supplied in the infos array.

Parameters:
infos - set of LookAndFeelInfo objects specifying the available look and feels
Throws:
NullPointerException - if infos is null
SecurityException
See Also:
getInstalledLookAndFeels()

installLookAndFeel

public static void installLookAndFeel(UIManager.LookAndFeelInfo info)
Adds the specified look and feel to the set of available look and feels. While this method allows a null info, it is strongly recommended that a non-null value be used.

Parameters:
info - a LookAndFeelInfo object that names the look and feel and identifies the class that implements it
See Also:
setInstalledLookAndFeels(javax.swing.UIManager.LookAndFeelInfo[])

installLookAndFeel

public static void installLookAndFeel(String name,
                                      String className)
Adds the specified look and feel to the set of available look and feels. While this method does not check the arguments in any way, it is strongly recommended that non-null values be supplied.

Parameters:
name - descriptive name of the look and feel
className - name of the class that implements the look and feel
See Also:
setInstalledLookAndFeels(javax.swing.UIManager.LookAndFeelInfo[])

getLookAndFeel

public static LookAndFeel getLookAndFeel()
Returns the current look and feel or null.

Returns:
current look and feel, or null
See Also:
setLookAndFeel(javax.swing.LookAndFeel)

setLookAndFeel

public static void setLookAndFeel(LookAndFeel newLookAndFeel)
                           throws UnsupportedLookAndFeelException
Sets the current look and feel to newLookAndFeel. If the current look and feel is non-null uninitialize is invoked on it. If newLookAndFeel is non-null, initialize is invoked on it followed by getDefaults. The defaults returned from newLookAndFeel.getDefaults() replace those of the defaults from the previous look and feel. If the newLookAndFeel is null, the look and feel defaults are set to null.

A value of null can be used to set the look and feel to null. As the LookAndFeel is required for most of Swing to function, setting the LookAndFeel to null is strongly discouraged.

This is a JavaBeans bound property.

Parameters:
newLookAndFeel - LookAndFeel to install
Throws:
UnsupportedLookAndFeelException - if newLookAndFeel is non-null and newLookAndFeel.isSupportedLookAndFeel() returns false
See Also:
getLookAndFeel()

setLookAndFeel

public static void setLookAndFeel(String className)
                           throws ClassNotFoundException,
                                  InstantiationException,
                                  IllegalAccessException,
                                  UnsupportedLookAndFeelException
Loads the LookAndFeel specified by the given class name, using the current thread's context class loader, and passes it to setLookAndFeel(LookAndFeel).

Parameters:
className - a string specifying the name of the class that implements the look and feel
Throws:
ClassNotFoundException - if the LookAndFeel class could not be found
InstantiationException - if a new instance of the class couldn't be created
IllegalAccessException - if the class or initializer isn't accessible
UnsupportedLookAndFeelException - if lnf.isSupportedLookAndFeel() is false
ClassCastException - if className does not identify a class that extends LookAndFeel

getSystemLookAndFeelClassName

public static String getSystemLookAndFeelClassName()
Returns the name of the LookAndFeel class that implements the native system look and feel if there is one, otherwise the name of the default cross platform LookAndFeel class. This value can be overriden by setting the swing.systemlaf system property.

Returns:
the String of the LookAndFeel class
See Also:
setLookAndFeel(javax.swing.LookAndFeel), getCrossPlatformLookAndFeelClassName()

getCrossPlatformLookAndFeelClassName

public static String getCrossPlatformLookAndFeelClassName()
Returns the name of the LookAndFeel class that implements the default cross platform look and feel -- the Java Look and Feel (JLF). This value can be overriden by setting the swing.crossplatformlaf system property.

Returns:
a string with the JLF implementation-class
See Also:
setLookAndFeel(javax.swing.LookAndFeel), getSystemLookAndFeelClassName()

getDefaults

public static UIDefaults getDefaults()
Returns the defaults. The returned defaults resolve using the logic specified in the class documentation.

Returns:
a UIDefaults object containing the default values

getFont

public static Font getFont(Object key)
Returns a font from the defaults. If the value for key is not a Font, null is returned.

Parameters:
key - an Object specifying the font
Returns:
the Font object
Throws:
NullPointerException - if key is null

getFont

public static Font getFont(Object key,
                           Locale l)
Returns a font from the defaults that is appropriate for the given locale. If the value for key is not a Font, null is returned.

Parameters:
key - an Object specifying the font
l - the Locale for which the font is desired; refer to UIDefaults for details on how a null Locale is handled
Returns:
the Font object
Throws:
NullPointerException - if key is null
Since:
1.4

getColor

public static Color getColor(Object key)
Returns a color from the defaults. If the value for key is not a Color, null is returned.

Parameters:
key - an Object specifying the color
Returns:
the Color object
Throws:
NullPointerException - if key is null

getColor

public static Color getColor(Object key,
                             Locale l)
Returns a color from the defaults that is appropriate for the given locale. If the value for key is not a Color, null is returned.

Parameters:
key - an Object specifying the color
l - the Locale for which the color is desired; refer to UIDefaults for details on how a null Locale is handled
Returns:
the Color object
Throws:
NullPointerException - if key is null
Since:
1.4

getIcon

public static Icon getIcon(Object key)
Returns an Icon from the defaults. If the value for key is not an Icon, null is returned.

Parameters:
key - an Object specifying the icon
Returns:
the Icon object
Throws:
NullPointerException - if key is null

getIcon

public static Icon getIcon(Object key,
                           Locale l)
Returns an Icon from the defaults that is appropriate for the given locale. If the value for key is not an Icon, null is returned.

Parameters:
key - an Object specifying the icon
l - the Locale for which the icon is desired; refer to UIDefaults for details on how a null Locale is handled
Returns:
the Icon object
Throws:
NullPointerException - if key is null
Since:
1.4

getBorder

public static Border getBorder(Object key)
Returns a border from the defaults. If the value for key is not a Border, null is returned.

Parameters:
key - an Object specifying the border
Returns:
the Border object
Throws:
NullPointerException - if key is null

getBorder

public static Border getBorder(Object key,
                               Locale l)
Returns a border from the defaults that is appropriate for the given locale. If the value for key is not a Border, null is returned.

Parameters:
key - an Object specifying the border
l - the Locale for which the border is desired; refer to UIDefaults for details on how a null Locale is handled
Returns:
the Border object
Throws:
NullPointerException - if key is null
Since:
1.4

getString

public static String getString(Object key)
Returns a string from the defaults. If the value for key is not a String, null is returned.

Parameters:
key - an Object specifying the string
Returns:
the String
Throws:
NullPointerException - if key is null

getString

public static String getString(Object key,
                               Locale l)
Returns a string from the defaults that is appropriate for the given locale. If the value for key is not a String, null is returned.

Parameters:
key - an Object specifying the string
l - the Locale for which the string is desired; refer to UIDefaults for details on how a null Locale is handled
Returns:
the String
Throws:
NullPointerException - if key is null
Since:
1.4

getInt

public static int getInt(Object key)
Returns an integer from the defaults. If the value for key is not an Integer, or does not exist, 0 is returned.

Parameters:
key - an Object specifying the int
Returns:
the int
Throws:
NullPointerException - if key is null

getInt

public static int getInt(Object key,
                         Locale l)
Returns an integer from the defaults that is appropriate for the given locale. If the value for key is not an Integer, or does not exist, 0 is returned.

Parameters:
key - an Object specifying the int
l - the Locale for which the int is desired; refer to UIDefaults for details on how a null Locale is handled
Returns:
the int
Throws:
NullPointerException - if key is null
Since:
1.4

getBoolean

public static boolean getBoolean(Object key)
Returns a boolean from the defaults which is associated with the key value. If the key is not found or the key doesn't represent a boolean value then false is returned.

Parameters:
key - an Object specifying the key for the desired boolean value
Returns:
the boolean value corresponding to the key
Throws:
NullPointerException - if key is null
Since:
1.4

getBoolean

public static boolean getBoolean(Object key,
                                 Locale l)
Returns a boolean from the defaults which is associated with the key value and the given Locale. If the key is not found or the key doesn't represent a boolean value then false will be returned.

Parameters:
key - an Object specifying the key for the desired boolean value
l - the Locale for which the boolean is desired; refer to UIDefaults for details on how a null Locale is handled
Returns:
the boolean value corresponding to the key
Throws:
NullPointerException - if key is null
Since:
1.4

getInsets

public static Insets getInsets(Object key)
Returns an Insets object from the defaults. If the value for key is not an Insets, null is returned.

Parameters:
key - an Object specifying the Insets object
Returns:
the Insets object
Throws:
NullPointerException - if key is null

getInsets

public static Insets getInsets(Object key,
                               Locale l)
Returns an Insets object from the defaults that is appropriate for the given locale. If the value for key is not an Insets, null is returned.

Parameters:
key - an Object specifying the Insets object
l - the Locale for which the object is desired; refer to UIDefaults for details on how a null Locale is handled
Returns:
the Insets object
Throws:
NullPointerException - if key is null
Since:
1.4

getDimension

public static Dimension getDimension(Object key)
Returns a dimension from the defaults. If the value for key is not a Dimension, null is returned.

Parameters:
key - an Object specifying the dimension object
Returns:
the Dimension object
Throws:
NullPointerException - if key is null

getDimension

public static Dimension getDimension(Object key,
                                     Locale l)
Returns a dimension from the defaults that is appropriate for the given locale. If the value for key is not a Dimension, null is returned.

Parameters:
key - an Object specifying the dimension object
l - the Locale for which the object is desired; refer to UIDefaults for details on how a null Locale is handled
Returns:
the Dimension object
Throws:
NullPointerException - if key is null
Since:
1.4

get

public static Object get(Object key)
Returns an object from the defaults.

Parameters:
key - an Object specifying the desired object
Returns:
the Object
Throws:
NullPointerException - if key is null

get

public static Object get(Object key,
                         Locale l)
Returns an object from the defaults that is appropriate for the given locale.

Parameters:
key - an Object specifying the desired object
l - the Locale for which the object is desired; refer to UIDefaults for details on how a null Locale is handled
Returns:
the Object
Throws:
NullPointerException - if key is null
Since:
1.4

put

public static Object put(Object key,
                         Object value)
Stores an object in the developer defaults. This is a cover method for getDefaults().put(key, value). This only effects the developer defaults, not the system or look and feel defaults.

Parameters:
key - an Object specifying the retrieval key
value - the Object to store; refer to UIDefaults for details on how null is handled
Returns:
the Object returned by UIDefaults.put(java.lang.Object, java.lang.Object)
Throws:
NullPointerException - if key is null
See Also:
UIDefaults.put(java.lang.Object, java.lang.Object)

getUI

public static ComponentUI getUI(JComponent target)
Returns the appropriate ComponentUI implementation for target. Typically, this is a cover for getDefaults().getUI(target). However, if an auxiliary look and feel has been installed, this first invokes getUI(target) on the multiplexing look and feel's defaults, and returns that value if it is non-null.

Parameters:
target - the JComponent to return the ComponentUI for
Returns:
the ComponentUI object for target
Throws:
NullPointerException - if target is null
See Also:
UIDefaults.getUI(javax.swing.JComponent)

getLookAndFeelDefaults

public static UIDefaults getLookAndFeelDefaults()
Returns the UIDefaults from the current look and feel, that were obtained at the time the look and feel was installed.

In general, developers should use the UIDefaults returned from getDefaults(). As the current look and feel may expect certain values to exist, altering the UIDefaults returned from this method could have unexpected results.

Returns:
UIDefaults from the current look and feel
See Also:
getDefaults(), setLookAndFeel(LookAndFeel), LookAndFeel.getDefaults()

addAuxiliaryLookAndFeel

public static void addAuxiliaryLookAndFeel(LookAndFeel laf)
Adds a LookAndFeel to the list of auxiliary look and feels. The auxiliary look and feels tell the multiplexing look and feel what other LookAndFeel classes for a component instance are to be used in addition to the default LookAndFeel class when creating a multiplexing UI. The change will only take effect when a new UI class is created or when the default look and feel is changed on a component instance.

Note these are not the same as the installed look and feels.

Parameters:
laf - the LookAndFeel object
See Also:
removeAuxiliaryLookAndFeel(javax.swing.LookAndFeel),
setLookAndFeel(javax.swing.LookAndFeel),
getAuxiliaryLookAndFeels(),
getInstalledLookAndFeels()

removeAuxiliaryLookAndFeel

public static boolean removeAuxiliaryLookAndFeel(LookAndFeel laf)
Removes a LookAndFeel from the list of auxiliary look and feels. The auxiliary look and feels tell the multiplexing look and feel what other LookAndFeel classes for a component instance are to be used in addition to the default LookAndFeel class when creating a multiplexing UI. The change will only take effect when a new UI class is created or when the default look and feel is changed on a component instance.

Note these are not the same as the installed look and feels.

Returns:
true if the LookAndFeel was removed from the list
See Also:
removeAuxiliaryLookAndFeel(javax.swing.LookAndFeel),
getAuxiliaryLookAndFeels(),
setLookAndFeel(javax.swing.LookAndFeel),
getInstalledLookAndFeels()

getAuxiliaryLookAndFeels

public static LookAndFeel[] getAuxiliaryLookAndFeels()
Returns the list of auxiliary look and feels (can be null). The auxiliary look and feels tell the multiplexing look and feel what other LookAndFeel classes for a component instance are to be used in addition to the default LookAndFeel class when creating a multiplexing UI.

Note these are not the same as the installed look and feels.

Returns:
list of auxiliary LookAndFeels or null
See Also:
addAuxiliaryLookAndFeel(javax.swing.LookAndFeel),
removeAuxiliaryLookAndFeel(javax.swing.LookAndFeel),
setLookAndFeel(javax.swing.LookAndFeel),
getInstalledLookAndFeels()

addPropertyChangeListener

public static void addPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list. The listener is registered for all properties.

Parameters:
listener - the PropertyChangeListener to be added
See Also:
PropertyChangeSupport

removePropertyChangeListener

public static void removePropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties.

Parameters:
listener - the PropertyChangeListener to be removed
See Also:
PropertyChangeSupport

getPropertyChangeListeners

public static PropertyChangeListener[] getPropertyChangeListeners()
Returns an array of all the PropertyChangeListeners added to this UIManager with addPropertyChangeListener().

Returns:
all of the PropertyChangeListeners added or an empty array if no listeners have been added
Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UIManager.LookAndFeelInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class UIManager.LookAndFeelInfo

java.lang.Object
    extended by  javax.swing.UIManager.LookAndFeelInfo
Enclosing class:
UIManager
public static class UIManager.LookAndFeelInfo
extends Object

Provides a little information about an installed LookAndFeel for the sake of configuring a menu or for initial application set up.

See Also:
UIManager.getInstalledLookAndFeels(), LookAndFeel

Constructor Summary
UIManager.LookAndFeelInfo(String name, String className)
Constructs a UIManagers LookAndFeelInfo object.
Method Summary
String | getClassName() Returns the name of the class that implements this look and feel.
String | getName() Returns the name of the look and feel in a form suitable for a menu or other presentation
String | toString() Returns a string that displays and identifies this object's properties.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UIManager.LookAndFeelInfo

public UIManager.LookAndFeelInfo(String name,
                                 String className)
Constructs a UIManagers LookAndFeelInfo object.

Parameters:
name - a String specifying the name of the look and feel
className - a String specifiying the name of the class that implements the look and feel
Method Detail

getName

public String getName()
Returns the name of the look and feel in a form suitable for a menu or other presentation

Returns:
a String containing the name
See Also:
LookAndFeel.getName()

getClassName

public String getClassName()
Returns the name of the class that implements this look and feel.

Returns:
the name of the class that implements this LookAndFeel
See Also:
LookAndFeel

toString

public String toString()
Returns a string that displays and identifies this object's properties.

Overrides:
toString in class Object
Returns:
a String representation of this object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


undo

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.swing.undo

Allows developers to provide support for undo/redo in applications such as text editors.

See:
Description

Interface Summary
StateEditable | StateEditable defines the interface for objects that can have their state undone/redone by a StateEdit.
UndoableEdit | An UndoableEdit represents an edit.

Class Summary
AbstractUndoableEdit | An abstract implementation of UndoableEdit, implementing simple responses to all boolean methods in that interface.
CompoundEdit | A concrete subclass of AbstractUndoableEdit, used to assemble little UndoableEdits into great big ones.
StateEdit | StateEdit is a general edit for objects that change state.
UndoableEditSupport | A support class used for managing UndoableEdit listeners.
UndoManager | UndoManager manages a list of UndoableEdits, providing a way to undo or redo the appropriate edits.

Exception Summary
CannotRedoException | Thrown when an UndoableEdit is told to redo() and can't.
CannotUndoException | Thrown when an UndoableEdit is told to undo() and can't.

Package javax.swing.undo Description

Allows developers to provide support for undo/redo in applications such as text editors.

Note: Most of the Swing API is not thread safe. For details, see Threads and Swing, a section in The Java Tutorial.

Related Documentation

For overviews, tutorials, examples, guides, and tool documentation, please see:
  • Implementing Undo and Redo, a section in The Java Tutorial

Since:
1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.swing.undo Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.swing.undo

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.swing.undo.AbstractUndoableEdit (implements java.io.Serializable, javax.swing.undo.UndoableEdit)
      • javax.swing.undo.CompoundEdit
        • javax.swing.undo.UndoManager (implements javax.swing.event.UndoableEditListener)
      • javax.swing.undo.StateEdit
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.lang.RuntimeException
          • javax.swing.undo.CannotRedoException
          • javax.swing.undo.CannotUndoException
    • javax.swing.undo.UndoableEditSupport

Interface Hierarchy

  • javax.swing.undo.StateEditable
  • javax.swing.undo.UndoableEdit
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.swing.undo

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.swing.undo

Packages that use javax.swing.undo
javax.swing.event | Provides for events fired by Swing components.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.undo | Allows developers to provide support for undo/redo in applications such as text editors.

Classes in javax.swing.undo used by javax.swing.event
UndoableEdit
An UndoableEdit represents an edit.

Classes in javax.swing.undo used by javax.swing.text
AbstractUndoableEdit
An abstract implementation of UndoableEdit, implementing simple responses to all boolean methods in that interface.
CannotRedoException
Thrown when an UndoableEdit is told to redo() and can't.
CannotUndoException
Thrown when an UndoableEdit is told to undo() and can't.
CompoundEdit
A concrete subclass of AbstractUndoableEdit, used to assemble little UndoableEdits into great big ones.
UndoableEdit
An UndoableEdit represents an edit.

Classes in javax.swing.undo used by javax.swing.undo
AbstractUndoableEdit
An abstract implementation of UndoableEdit, implementing simple responses to all boolean methods in that interface.
CannotRedoException
Thrown when an UndoableEdit is told to redo() and can't.
CannotUndoException
Thrown when an UndoableEdit is told to undo() and can't.
CompoundEdit
A concrete subclass of AbstractUndoableEdit, used to assemble little UndoableEdits into great big ones.
StateEditable
StateEditable defines the interface for objects that can have their state undone/redone by a StateEdit.
UndoableEdit
An UndoableEdit represents an edit.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AbstractUndoableEdit

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.undo
Class AbstractUndoableEdit

java.lang.Object
    extended by  javax.swing.undo.AbstractUndoableEdit
All Implemented Interfaces:
Serializable, UndoableEdit
Direct Known Subclasses:
AbstractDocument.ElementEdit, CompoundEdit, DefaultStyledDocument.AttributeUndoableEdit, StateEdit
public class AbstractUndoableEdit
extends Object
implements UndoableEdit, Serializable

An abstract implementation of UndoableEdit, implementing simple responses to all boolean methods in that interface.

Field Summary
protected static String | RedoName String returned by getRedoPresentationName; as of Java 2 platform v1.3.1 this field is no longer used.
protected static String | UndoName String returned by getUndoPresentationName; as of Java 2 platform v1.3.1 this field is no longer used.
Constructor Summary
AbstractUndoableEdit()
Creates an AbstractUndoableEdit which defaults hasBeenDone and alive to true.
Method Summary
boolean | addEdit(UndoableEdit anEdit) This default implementation returns false.
boolean | canRedo() Returns true if this edit is alive and hasBeenDone is false.
boolean | canUndo() Returns true if this edit is alive and hasBeenDone is true.
void | die() Sets alive to false.
String | getPresentationName() This default implementation returns "".
String | getRedoPresentationName() Retreives the value from the defaults table with key AbstractUndoableEdit.redoText and returns that value followed by a space, followed by getPresentationName.
String | getUndoPresentationName() Retreives the value from the defaults table with key AbstractUndoableEdit.undoText and returns that value followed by a space, followed by getPresentationName.
boolean | isSignificant() This default implementation returns true.
void | redo() Throws CannotRedoException if canRedo returns false.
boolean | replaceEdit(UndoableEdit anEdit) This default implementation returns false.
String | toString() Returns a string that displays and identifies this object's properties.
void | undo() Throws CannotUndoException if canUndo returns false.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

UndoName

protected static final String UndoName
String returned by getUndoPresentationName; as of Java 2 platform v1.3.1 this field is no longer used. This value is now localized and comes from the defaults table with key AbstractUndoableEdit.undoText.

See Also:
UIDefaults, Constant Field Values

RedoName

protected static final String RedoName
String returned by getRedoPresentationName; as of Java 2 platform v1.3.1 this field is no longer used. This value is now localized and comes from the defaults table with key AbstractUndoableEdit.redoText.

See Also:
UIDefaults, Constant Field Values
Constructor Detail

AbstractUndoableEdit

public AbstractUndoableEdit()
Creates an AbstractUndoableEdit which defaults hasBeenDone and alive to true.

Method Detail

die

public void die()
Sets alive to false. Note that this is a one way operation; dead edits cannot be resurrected. Sending undo or redo to a dead edit results in an exception being thrown.

Typically an edit is killed when it is consolidated by another edit's addEdit or replaceEdit method, or when it is dequeued from an UndoManager.

Specified by:
die in interface UndoableEdit
See Also:
CompoundEdit.die()

undo

public void undo()
          throws CannotUndoException
Throws CannotUndoException if canUndo returns false. Sets hasBeenDone to false. Subclasses should override to undo the operation represented by this edit. Override should begin with a call to super.

Specified by:
undo in interface UndoableEdit
Throws:
CannotUndoException - if canUndo returns false
See Also:
canUndo()

canUndo

public boolean canUndo()
Returns true if this edit is alive and hasBeenDone is true.

Specified by:
canUndo in interface UndoableEdit
Returns:
true if this edit is alive and hasBeenDone is true
See Also:
die(),
undo(),
redo()

redo

public void redo()
          throws CannotRedoException
Throws CannotRedoException if canRedo returns false. Sets hasBeenDone to true. Subclasses should override to redo the operation represented by this edit. Override should begin with a call to super.

Specified by:
redo in interface UndoableEdit
Throws:
CannotRedoException - if canRedo returns false
See Also:
canRedo()

canRedo

public boolean canRedo()
Returns true if this edit is alive and hasBeenDone is false.

Specified by:
canRedo in interface UndoableEdit
Returns:
true if this edit is alive and hasBeenDone is false
See Also:
die(),
undo(),
redo()

addEdit

public boolean addEdit(UndoableEdit anEdit)
This default implementation returns false.

Specified by:
addEdit in interface UndoableEdit
Parameters:
anEdit - the edit to be added
Returns:
false
See Also:
UndoableEdit.addEdit(javax.swing.undo.UndoableEdit)

replaceEdit

public boolean replaceEdit(UndoableEdit anEdit)
This default implementation returns false.

Specified by:
replaceEdit in interface UndoableEdit
Parameters:
anEdit - the edit to replace
Returns:
false
See Also:
UndoableEdit.replaceEdit(javax.swing.undo.UndoableEdit)

isSignificant

public boolean isSignificant()
This default implementation returns true.

Specified by:
isSignificant in interface UndoableEdit
Returns:
true
See Also:
UndoableEdit.isSignificant()

getPresentationName

public String getPresentationName()
This default implementation returns "". Used by getUndoPresentationName and getRedoPresentationName to construct the strings they return. Subclasses should override to return an appropriate description of the operation this edit represents.

Specified by:
getPresentationName in interface UndoableEdit
Returns:
the empty string ""
See Also:
getUndoPresentationName(), getRedoPresentationName()

getUndoPresentationName

public String getUndoPresentationName()
Retreives the value from the defaults table with key AbstractUndoableEdit.undoText and returns that value followed by a space, followed by getPresentationName. If getPresentationName returns "", then the defaults value is returned alone.

Specified by:
getUndoPresentationName in interface UndoableEdit
Returns:
the value from the defaults table with key AbstractUndoableEdit.undoText, followed by a space, followed by getPresentationName unless getPresentationName is "" in which case, the defaults value is returned alone.
See Also:
getPresentationName()

getRedoPresentationName

public String getRedoPresentationName()
Retreives the value from the defaults table with key AbstractUndoableEdit.redoText and returns that value followed by a space, followed by getPresentationName. If getPresentationName returns "", then the defaults value is returned alone.

Specified by:
getRedoPresentationName in interface UndoableEdit
Returns:
the value from the defaults table with key AbstractUndoableEdit.redoText, followed by a space, followed by getPresentationName unless getPresentationName is "" in which case, the defaults value is returned alone.
See Also:
getPresentationName()

toString

public String toString()
Returns a string that displays and identifies this object's properties.

Overrides:
toString in class Object
Returns:
a String representation of this object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


CannotRedoException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.undo
Class CannotRedoException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  javax.swing.undo.CannotRedoException
All Implemented Interfaces:
Serializable
public class CannotRedoException
extends RuntimeException

Thrown when an UndoableEdit is told to redo() and can't.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
CannotRedoException()
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CannotRedoException

public CannotRedoException()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CannotUndoException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.undo
Class CannotUndoException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  javax.swing.undo.CannotUndoException
All Implemented Interfaces:
Serializable
public class CannotUndoException
extends RuntimeException

Thrown when an UndoableEdit is told to undo() and can't.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
CannotUndoException()
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CannotUndoException

public CannotUndoException()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.swing.undo.AbstractUndoableEdit

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.undo.AbstractUndoableEdit

Packages that use AbstractUndoableEdit
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.undo | Allows developers to provide support for undo/redo in applications such as text editors.

Uses of AbstractUndoableEdit in javax.swing.text

Subclasses of AbstractUndoableEdit in javax.swing.text
class | AbstractDocument.DefaultDocumentEvent Stores document changes as the document is being modified.
static class | AbstractDocument.ElementEdit An implementation of ElementChange that can be added to the document event.
static class | DefaultStyledDocument.AttributeUndoableEdit An UndoableEdit used to remember AttributeSet changes to an Element.

Uses of AbstractUndoableEdit in javax.swing.undo

Subclasses of AbstractUndoableEdit in javax.swing.undo
class | CompoundEdit A concrete subclass of AbstractUndoableEdit, used to assemble little UndoableEdits into great big ones.
class | StateEdit StateEdit is a general edit for objects that change state.
class | UndoManager UndoManager manages a list of UndoableEdits, providing a way to undo or redo the appropriate edits.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.undo.CannotRedoException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.undo.CannotRedoException

Packages that use CannotRedoException
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.undo | Allows developers to provide support for undo/redo in applications such as text editors.

Uses of CannotRedoException in javax.swing.text

Methods in javax.swing.text that throw CannotRedoException
void | DefaultStyledDocument.AttributeUndoableEdit.redo() Redoes a change.
void | AbstractDocument.DefaultDocumentEvent.redo() Redoes a change.
void | AbstractDocument.ElementEdit.redo() Redoes a change.

Uses of CannotRedoException in javax.swing.undo

Methods in javax.swing.undo that throw CannotRedoException
void | UndoManager.redo() Redoes the appropriate edits.
void | CompoundEdit.redo() Sends redo to all contained UndoableEdits in the order in which they were added.
void | AbstractUndoableEdit.redo() Throws CannotRedoException if canRedo returns false.
void | UndoableEdit.redo() Re-applies the edit.
protected void | UndoManager.redoTo(UndoableEdit edit) Redoes all changes from the index of the next edit to edit, updating the index of the next edit appropriately.
void | UndoManager.undoOrRedo() Convenience method that invokes one of undo or redo.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.undo.CannotUndoException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.undo.CannotUndoException

Packages that use CannotUndoException
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.undo | Allows developers to provide support for undo/redo in applications such as text editors.

Uses of CannotUndoException in javax.swing.text

Methods in javax.swing.text that throw CannotUndoException
void | DefaultStyledDocument.AttributeUndoableEdit.undo() Undoes a change.
void | AbstractDocument.DefaultDocumentEvent.undo() Undoes a change.
void | AbstractDocument.ElementEdit.undo() Undoes a change.

Uses of CannotUndoException in javax.swing.undo

Methods in javax.swing.undo that throw CannotUndoException
void | UndoManager.undo() Undoes the appropriate edits.
void | CompoundEdit.undo() Sends undo to all contained UndoableEdits in the reverse of the order in which they were added.
void | AbstractUndoableEdit.undo() Throws CannotUndoException if canUndo returns false.
void | UndoableEdit.undo() Undo the edit.
void | UndoManager.undoOrRedo() Convenience method that invokes one of undo or redo.
protected void | UndoManager.undoTo(UndoableEdit edit) Undoes all changes from the index of the next edit to edit, updating the index of the next edit appropriately.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.undo.CompoundEdit

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.undo.CompoundEdit

Packages that use CompoundEdit
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.undo | Allows developers to provide support for undo/redo in applications such as text editors.

Uses of CompoundEdit in javax.swing.text

Subclasses of CompoundEdit in javax.swing.text
 class AbstractDocument.DefaultDocumentEvent
Stores document changes as the document is being modified.

Uses of CompoundEdit in javax.swing.undo

Subclasses of CompoundEdit in javax.swing.undo
 class UndoManager
UndoManager manages a list of UndoableEdits, providing a way to undo or redo the appropriate edits.

Fields in javax.swing.undo declared as CompoundEdit
protected  CompoundEdit UndoableEditSupport.compoundEdit

Methods in javax.swing.undo that return CompoundEdit
protected  CompoundEdit UndoableEditSupport.createCompoundEdit()
Called only from beginUpdate.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.undo.StateEdit

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.undo.StateEdit

No usage of javax.swing.undo.StateEdit

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.undo.UndoableEditSupport

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.undo.UndoableEditSupport

No usage of javax.swing.undo.UndoableEditSupport

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.swing.undo.UndoManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.swing.undo.UndoManager

No usage of javax.swing.undo.UndoManager

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.undo.StateEditable

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.undo.StateEditable

Packages that use StateEditable
javax.swing.undo Allows developers to provide support for undo/redo in applications such as text editors.

Uses of StateEditable in javax.swing.undo

Fields in javax.swing.undo declared as StateEditable
protected  StateEditable StateEdit.object
The object being edited

Methods in javax.swing.undo with parameters of type StateEditable
protected  void StateEdit.init(StateEditable anObject, String name)

Constructors in javax.swing.undo with parameters of type StateEditable
StateEdit(StateEditable anObject)
Create and return a new StateEdit.
StateEdit(StateEditable anObject, String name)
Create and return a new StateEdit with a presentation name.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.swing.undo.UndoableEdit

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.swing.undo.UndoableEdit

Packages that use UndoableEdit
javax.swing.event | Provides for events fired by Swing components.
javax.swing.text | Provides classes and interfaces that deal with editable and noneditable text components.
javax.swing.undo | Allows developers to provide support for undo/redo in applications such as text editors.

Uses of UndoableEdit in javax.swing.event

Methods in javax.swing.event that return UndoableEdit
 UndoableEdit UndoableEditEvent.getEdit()
Returns the edit value.

Constructors in javax.swing.event with parameters of type UndoableEdit
UndoableEditEvent(Object source, UndoableEdit edit)
Constructs an UndoableEditEvent object.

Uses of UndoableEdit in javax.swing.text

Classes in javax.swing.text that implement UndoableEdit
class | AbstractDocument.DefaultDocumentEvent Stores document changes as the document is being modified.
static class | AbstractDocument.ElementEdit An implementation of ElementChange that can be added to the document event.
static class | DefaultStyledDocument.AttributeUndoableEdit An UndoableEdit used to remember AttributeSet changes to an Element.

Methods in javax.swing.text that return UndoableEdit
UndoableEdit | StringContent.insertString(int where, String str) Inserts a string into the content.
UndoableEdit | GapContent.insertString(int where, String str) Inserts a string into the content.
UndoableEdit | AbstractDocument.Content.insertString(int where, String str) Inserts a string of characters into the sequence.
UndoableEdit | StringContent.remove(int where, int nitems) Removes part of the content.
UndoableEdit | GapContent.remove(int where, int nitems) Removes part of the content.
UndoableEdit | AbstractDocument.Content.remove(int where, int nitems) Removes some portion of the sequence.

Methods in javax.swing.text with parameters of type UndoableEdit
 boolean AbstractDocument.DefaultDocumentEvent.addEdit(UndoableEdit anEdit)
Adds a document edit.

Uses of UndoableEdit in javax.swing.undo

Classes in javax.swing.undo that implement UndoableEdit
class | AbstractUndoableEdit An abstract implementation of UndoableEdit, implementing simple responses to all boolean methods in that interface.
class | CompoundEdit A concrete subclass of AbstractUndoableEdit, used to assemble little UndoableEdits into great big ones.
class | StateEdit StateEdit is a general edit for objects that change state.
class | UndoManager UndoManager manages a list of UndoableEdits, providing a way to undo or redo the appropriate edits.

Fields in javax.swing.undo with type parameters of type UndoableEdit
protected  Vector<UndoableEdit> CompoundEdit.edits
The collection of UndoableEdits undone/redone en masse by this CompoundEdit.

Methods in javax.swing.undo that return UndoableEdit
protected UndoableEdit | UndoManager.editToBeRedone() Returns the the next significant edit to be redone if redo is invoked.
protected UndoableEdit | UndoManager.editToBeUndone() Returns the the next significant edit to be undone if undo is invoked.
protected UndoableEdit | CompoundEdit.lastEdit() Returns the last UndoableEdit in edits, or null if edits is empty.

Methods in javax.swing.undo with parameters of type UndoableEdit
protected void | UndoableEditSupport._postEdit(UndoableEdit e) Called only from postEdit and endUpdate.
boolean | UndoManager.addEdit(UndoableEdit anEdit) Adds an UndoableEdit to this UndoManager, if it's possible.
boolean | CompoundEdit.addEdit(UndoableEdit anEdit) If this edit is inProgress, accepts anEdit and returns true.
boolean | AbstractUndoableEdit.addEdit(UndoableEdit anEdit) This default implementation returns false.
boolean | UndoableEdit.addEdit(UndoableEdit anEdit) Adds an UndoableEdit to this UndoableEdit.
void | UndoableEditSupport.postEdit(UndoableEdit e) DEADLOCK WARNING: Calling this method may call undoableEditHappened in all listeners.
protected void | UndoManager.redoTo(UndoableEdit edit) Redoes all changes from the index of the next edit to edit, updating the index of the next edit appropriately.
boolean | AbstractUndoableEdit.replaceEdit(UndoableEdit anEdit) This default implementation returns false.
boolean | UndoableEdit.replaceEdit(UndoableEdit anEdit) Returns true if this UndoableEdit should replace anEdit.
protected void | UndoManager.undoTo(UndoableEdit edit) Undoes all changes from the index of the next edit to edit, updating the index of the next edit appropriately.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


CompoundEdit

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.undo
Class CompoundEdit

java.lang.Object
    extended by  javax.swing.undo.AbstractUndoableEdit
        extended by  javax.swing.undo.CompoundEdit
All Implemented Interfaces:
Serializable, UndoableEdit
Direct Known Subclasses:
AbstractDocument.DefaultDocumentEvent, UndoManager
public class CompoundEdit
extends AbstractUndoableEdit

A concrete subclass of AbstractUndoableEdit, used to assemble little UndoableEdits into great big ones.

Field Summary
protected  Vector<UndoableEdit> edits
The collection of UndoableEdits undone/redone en masse by this CompoundEdit.
Fields inherited from class javax.swing.undo.AbstractUndoableEdit
RedoName, UndoName
Constructor Summary
CompoundEdit()
Method Summary
boolean | addEdit(UndoableEdit anEdit) If this edit is inProgress, accepts anEdit and returns true.
boolean | canRedo() Returns false if isInProgress or if super returns false.
boolean | canUndo() Returns false if isInProgress or if super returns false.
void | die() Sends die to each subedit, in the reverse of the order that they were added.
void | end() Sets inProgress to false.
String | getPresentationName() Returns getPresentationName from the last UndoableEdit added to edits.
String | getRedoPresentationName() Returns getRedoPresentationName from the last UndoableEdit added to edits.
String | getUndoPresentationName() Returns getUndoPresentationName from the last UndoableEdit added to edits.
boolean | isInProgress() Returns true if this edit is in progress--that is, it has not received end.
boolean | isSignificant() Returns true if any of the UndoableEdits in edits do.
protected UndoableEdit | lastEdit() Returns the last UndoableEdit in edits, or null if edits is empty.
void | redo() Sends redo to all contained UndoableEdits in the order in which they were added.
String | toString() Returns a string that displays and identifies this object's properties.
void | undo() Sends undo to all contained UndoableEdits in the reverse of the order in which they were added.
Methods inherited from class javax.swing.undo.AbstractUndoableEdit
replaceEdit
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

edits

protected Vector<UndoableEdit> edits
The collection of UndoableEdits undone/redone en masse by this CompoundEdit.

Constructor Detail

CompoundEdit

public CompoundEdit()
Method Detail

undo

public void undo()
          throws CannotUndoException
Sends undo to all contained UndoableEdits in the reverse of the order in which they were added.

Specified by:
undo in interface UndoableEdit
Overrides:
undo in class AbstractUndoableEdit
Throws:
CannotUndoException - if canUndo returns false
See Also:
AbstractUndoableEdit.canUndo()

redo

public void redo()
          throws CannotRedoException
Sends redo to all contained UndoableEdits in the order in which they were added.

Specified by:
redo in interface UndoableEdit
Overrides:
redo in class AbstractUndoableEdit
Throws:
CannotRedoException - if canRedo returns false
See Also:
AbstractUndoableEdit.canRedo()

lastEdit

protected UndoableEdit lastEdit()
Returns the last UndoableEdit in edits, or null if edits is empty.

die

public void die()
Sends die to each subedit, in the reverse of the order that they were added.

Specified by:
die in interface UndoableEdit
Overrides:
die in class AbstractUndoableEdit
See Also:
die()

addEdit

public boolean addEdit(UndoableEdit anEdit)
If this edit is inProgress, accepts anEdit and returns true.

The last edit added to this CompoundEdit is given a chance to addEdit(anEdit). If it refuses (returns false), anEdit is given a chance to replaceEdit the last edit. If anEdit returns false here, it is added to edits.

Specified by:
addEdit in interface UndoableEdit
Overrides:
addEdit in class AbstractUndoableEdit
Parameters:
anEdit - the edit to be added
Returns:
true if the edit is inProgress; otherwise returns false
See Also:
UndoableEdit.addEdit(javax.swing.undo.UndoableEdit)

end

public void end()
Sets inProgress to false.

See Also:
canUndo(), canRedo()

canUndo

public boolean canUndo()
Returns false if isInProgress or if super returns false.

Specified by:
canUndo in interface UndoableEdit
Overrides:
canUndo in class AbstractUndoableEdit
Returns:
true if this edit is alive and hasBeenDone is true
See Also:
isInProgress()

canRedo

public boolean canRedo()
Returns false if isInProgress or if super returns false.

Specified by:
canRedo in interface UndoableEdit
Overrides:
canRedo in class AbstractUndoableEdit
Returns:
true if this edit is alive and hasBeenDone is false
See Also:
isInProgress()

isInProgress

public boolean isInProgress()
Returns true if this edit is in progress--that is, it has not received end. This generally means that edits are still being added to it.

See Also:
end()

isSignificant

public boolean isSignificant()
Returns true if any of the UndoableEdits in edits do. Returns false if they all return false.

Specified by:
isSignificant in interface UndoableEdit
Overrides:
isSignificant in class AbstractUndoableEdit
Returns:
true
See Also:
UndoableEdit.isSignificant()

getPresentationName

public String getPresentationName()
Returns getPresentationName from the last UndoableEdit added to edits. If edits is empty, calls super.

Specified by:
getPresentationName in interface UndoableEdit
Overrides:
getPresentationName in class AbstractUndoableEdit
Returns:
the empty string ""
See Also:
AbstractUndoableEdit.getUndoPresentationName(), AbstractUndoableEdit.getRedoPresentationName()

getUndoPresentationName

public String getUndoPresentationName()
Returns getUndoPresentationName from the last UndoableEdit added to edits. If edits is empty, calls super.

Specified by:
getUndoPresentationName in interface UndoableEdit
Overrides:
getUndoPresentationName in class AbstractUndoableEdit
Returns:
the value from the defaults table with key AbstractUndoableEdit.undoText, followed by a space, followed by getPresentationName unless getPresentationName is "" in which case, the defaults value is returned alone.
See Also:
AbstractUndoableEdit.getPresentationName()

getRedoPresentationName

public String getRedoPresentationName()
Returns getRedoPresentationName from the last UndoableEdit added to edits. If edits is empty, calls super.

Specified by:
getRedoPresentationName in interface UndoableEdit
Overrides:
getRedoPresentationName in class AbstractUndoableEdit
Returns:
the value from the defaults table with key AbstractUndoableEdit.redoText, followed by a space, followed by getPresentationName unless getPresentationName is "" in which case, the defaults value is returned alone.
See Also:
AbstractUndoableEdit.getPresentationName()

toString

public String toString()
Returns a string that displays and identifies this object's properties.

Overrides:
toString in class AbstractUndoableEdit
Returns:
a String representation of this object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StateEdit

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.undo
Class StateEdit

java.lang.Object
    extended by  javax.swing.undo.AbstractUndoableEdit
        extended by  javax.swing.undo.StateEdit
All Implemented Interfaces:
Serializable, UndoableEdit
public class StateEdit
extends AbstractUndoableEdit

StateEdit is a general edit for objects that change state. Objects being edited must conform to the StateEditable interface.

This edit class works by asking an object to store it's state in Hashtables before and after editing occurs. Upon undo or redo the object is told to restore it's state from these Hashtables.

A state edit is used as follows:
        // Create the edit during the "before" state of the object
        StateEdit newEdit = new StateEdit(myObject);
        // Modify the object
        myObject.someStateModifyingMethod();
        // "end" the edit when you are done modifying the object
        newEdit.end();

Note that when a StateEdit ends, it removes redundant state from the Hashtables - A state Hashtable is not guaranteed to contain all keys/values placed into it when the state is stored!

See Also:
StateEditable

Field Summary
protected StateEditable | object The object being edited
protected Hashtable<Object,Object> | postState The state information after the edit
protected Hashtable<Object,Object> | preState The state information prior to the edit
protected static String | RCSID
protected String | undoRedoName The undo/redo presentation name
Fields inherited from class javax.swing.undo.AbstractUndoableEdit
RedoName, UndoName
Constructor Summary
StateEdit(StateEditable anObject)
Create and return a new StateEdit.
StateEdit(StateEditable anObject, String name)
Create and return a new StateEdit with a presentation name.
Method Summary
void | end() Gets the post-edit state of the StateEditable object and ends the edit.
String | getPresentationName() Gets the presentation name for this edit
protected void | init(StateEditable anObject, String name)
void | redo() Tells the edited object to apply the state after the edit
protected void | removeRedundantState() Remove redundant key/values in state hashtables.
void | undo() Tells the edited object to apply the state prior to the edit
Methods inherited from class javax.swing.undo.AbstractUndoableEdit
addEdit, canRedo, canUndo, die, getRedoPresentationName, getUndoPresentationName, isSignificant, replaceEdit, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

RCSID

protected static final String RCSID
See Also:
Constant Field Values

object

protected StateEditable object
The object being edited

preState

protected Hashtable<Object,Object> preState
The state information prior to the edit

postState

protected Hashtable<Object,Object> postState
The state information after the edit

undoRedoName

protected String undoRedoName
The undo/redo presentation name

Constructor Detail

StateEdit

public StateEdit(StateEditable anObject)
Create and return a new StateEdit.

Parameters:
anObject - The object to watch for changing state
See Also:
StateEdit

StateEdit

public StateEdit(StateEditable anObject,
                 String name)
Create and return a new StateEdit with a presentation name.

Parameters:
anObject - The object to watch for changing state
name - The presentation name to be used for this edit
See Also:
StateEdit
Method Detail

init

protected void init(StateEditable anObject,
                    String name)

end

public void end()
Gets the post-edit state of the StateEditable object and ends the edit.

undo

public void undo()
Tells the edited object to apply the state prior to the edit

Specified by:
undo in interface UndoableEdit
Overrides:
undo in class AbstractUndoableEdit
See Also:
AbstractUndoableEdit.canUndo()

redo

public void redo()
Tells the edited object to apply the state after the edit

Specified by:
redo in interface UndoableEdit
Overrides:
redo in class AbstractUndoableEdit
See Also:
AbstractUndoableEdit.canRedo()

getPresentationName

public String getPresentationName()
Gets the presentation name for this edit

Specified by:
getPresentationName in interface UndoableEdit
Overrides:
getPresentationName in class AbstractUndoableEdit
Returns:
the empty string ""
See Also:
AbstractUndoableEdit.getUndoPresentationName(), AbstractUndoableEdit.getRedoPresentationName()

removeRedundantState

protected void removeRedundantState()
Remove redundant key/values in state hashtables.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StateEditable

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.undo
Interface StateEditable

public interface StateEditable

StateEditable defines the interface for objects that can have their state undone/redone by a StateEdit.

See Also:
StateEdit

Field Summary
static String RCSID
Resource ID for this class.
Method Summary
void | restoreState(Hashtable<?,?> state) Upon receiving this message the receiver should extract any relevant state out of state.
void | storeState(Hashtable<Object,Object> state) Upon receiving this message the receiver should place any relevant state into state.

Field Detail

RCSID

static final String RCSID
Resource ID for this class.

See Also:
Constant Field Values
Method Detail

storeState

void storeState(Hashtable<Object,Object> state)
Upon receiving this message the receiver should place any relevant state into state.

restoreState

void restoreState(Hashtable<?,?> state)
Upon receiving this message the receiver should extract any relevant state out of state.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UndoableEdit

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.undo
Interface UndoableEdit

All Known Implementing Classes:
AbstractDocument.DefaultDocumentEvent, AbstractDocument.ElementEdit, AbstractUndoableEdit, CompoundEdit, DefaultStyledDocument.AttributeUndoableEdit, StateEdit, UndoManager
public interface UndoableEdit

An UndoableEdit represents an edit. The edit may be undone, or if already undone the edit may be redone.

UndoableEdit is designed to be used with the UndoManager. As UndoableEdits are generated by an UndoableEditListener they are typically added to the UndoManager. When an UndoableEdit is added to an UndoManager the following occurs (assuming end has not been called on the UndoManager):

  1. If the UndoManager contains edits it will call addEdit on the current edit passing in the new edit as the argument. If addEdit returns true the new edit is assumed to have been incorporated into the current edit and the new edit will not be added to the list of current edits. Edits can use addEdit as a way for smaller edits to be incorporated into a larger edit and treated as a single edit.
  2. If addEdit returns false replaceEdit is called on the new edit with the current edit passed in as the argument. This is the inverse of addEdit — if the new edit returns true from replaceEdit, the new edit replaces the current edit.
The UndoManager makes use of isSignificant to determine how many edits should be undone or redone. The UndoManager will undo or redo all insignificant edits (isSignificant returns false) between the current edit and the last or next significant edit. addEdit and replaceEdit can be used to treat multiple edits as a single edit, returning false from isSignificant allows for treating can be used to have many smaller edits undone or redone at once. Similar functionality can also be done using the addEdit method.

Method Summary
boolean | addEdit(UndoableEdit anEdit) Adds an UndoableEdit to this UndoableEdit.
boolean | canRedo() Returns true if this edit may be redone.
boolean | canUndo() Returns true if this edit may be undone.
void | die() Informs the edit that it should no longer be used.
String | getPresentationName() Returns a localized, human-readable description of this edit, suitable for use in a change log, for example.
String | getRedoPresentationName() Returns a localized, human-readable description of the redoable form of this edit, suitable for use as a Redo menu item, for example.
String | getUndoPresentationName() Returns a localized, human-readable description of the undoable form of this edit, suitable for use as an Undo menu item, for example.
boolean | isSignificant() Returns true if this edit is considered significant.
void | redo() Re-applies the edit.
boolean | replaceEdit(UndoableEdit anEdit) Returns true if this UndoableEdit should replace anEdit.
void | undo() Undo the edit.

Method Detail

undo

void undo()
          throws CannotUndoException
Undo the edit.

Throws:
CannotUndoException - if this edit can not be undone

canUndo

boolean canUndo()
Returns true if this edit may be undone.

Returns:
true if this edit may be undone

redo

void redo()
          throws CannotRedoException
Re-applies the edit.

Throws:
CannotRedoException - if this edit can not be redone

canRedo

boolean canRedo()
Returns true if this edit may be redone.

Returns:
true if this edit may be redone

die

void die()
Informs the edit that it should no longer be used. Once an UndoableEdit has been marked as dead it can no longer be undone or redone.

This is a useful hook for cleaning up state no longer needed once undoing or redoing is impossible--for example, deleting file resources used by objects that can no longer be undeleted. UndoManager calls this before it dequeues edits.

Note that this is a one-way operation. There is no "un-die" method.

See Also:
CompoundEdit.die()

addEdit

boolean addEdit(UndoableEdit anEdit)
Adds an UndoableEdit to this UndoableEdit. This method can be used to coalesce smaller edits into a larger compound edit. For example, text editors typically allow undo operations to apply to words or sentences. The text editor may choose to generate edits on each key event, but allow those edits to be coalesced into a more user-friendly unit, such as a word. In this case, the UndoableEdit would override addEdit to return true when the edits may be coalesced.

A return value of true indicates anEdit was incorporated into this edit. A return value of false indicates anEdit may not be incorporated into this edit.

Typically the receiver is already in the queue of a UndoManager (or other UndoableEditListener), and is being given a chance to incorporate anEdit rather than letting it be added to the queue in turn.

If true is returned, from now on anEdit must return false from canUndo and canRedo, and must throw the appropriate exception on undo or redo.

Parameters:
anEdit - the edit to be added
Returns:
true if anEdit may be incorporated into this edit

replaceEdit

boolean replaceEdit(UndoableEdit anEdit)
Returns true if this UndoableEdit should replace anEdit. This method is used by CompoundEdit and the UndoManager; it is called if anEdit could not be added to the current edit (addEdit returns false).

This method provides a way for an edit to replace an existing edit.

This message is the opposite of addEdit--anEdit has typically already been queued in an UndoManager (or other UndoableEditListener), and the receiver is being given a chance to take its place.

If true is returned, from now on anEdit must return false from canUndo() and canRedo(), and must throw the appropriate exception on undo() or redo().

Parameters:
anEdit - the edit that replaces the current edit
Returns:
true if this edit should replace anEdit

isSignificant

boolean isSignificant()
Returns true if this edit is considered significant. A significant edit is typically an edit that should be presented to the user, perhaps on a menu item or tooltip. The UndoManager will undo, or redo, all insignificant edits to the next significant edit.

Returns:
true if this edit is significant

getPresentationName

String getPresentationName()
Returns a localized, human-readable description of this edit, suitable for use in a change log, for example.

Returns:
description of this edit

getUndoPresentationName

String getUndoPresentationName()
Returns a localized, human-readable description of the undoable form of this edit, suitable for use as an Undo menu item, for example. This is typically derived from getPresentationName.

Returns:
a description of the undoable form of this edit

getRedoPresentationName

String getRedoPresentationName()
Returns a localized, human-readable description of the redoable form of this edit, suitable for use as a Redo menu item, for example. This is typically derived from getPresentationName.

Returns:
a description of the redoable form of this edit
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UndoableEditSupport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing.undo
Class UndoableEditSupport

java.lang.Object
    extended by  javax.swing.undo.UndoableEditSupport

public class UndoableEditSupport
extends Object

A support class used for managing UndoableEdit listeners.

Field Summary
protected CompoundEdit | compoundEdit
protected Vector<UndoableEditListener> | listeners
protected Object | realSource
protected int | updateLevel
Constructor Summary
UndoableEditSupport()
Constructs an UndoableEditSupport object.
UndoableEditSupport(Object r)
Constructs an UndoableEditSupport object.
Method Summary
protected  void _postEdit(UndoableEdit e)
Called only from postEdit and endUpdate.
 void addUndoableEditListener(UndoableEditListener l)
Registers an UndoableEditListener.
 void beginUpdate()
protected  CompoundEdit createCompoundEdit()
Called only from beginUpdate.
 void endUpdate()
DEADLOCK WARNING: Calling this method may call undoableEditHappened in all listeners.
 UndoableEditListener[] getUndoableEditListeners()
Returns an array of all the UndoableEditListeners added to this UndoableEditSupport with addUndoableEditListener().
 int getUpdateLevel()
Returns the update level value.
 void postEdit(UndoableEdit e)
DEADLOCK WARNING: Calling this method may call undoableEditHappened in all listeners.
 void removeUndoableEditListener(UndoableEditListener l)
Removes an UndoableEditListener.
 String toString()
Returns a string that displays and identifies this object's properties.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

updateLevel

protected int updateLevel

compoundEdit

protected CompoundEdit compoundEdit

listeners

protected Vector<UndoableEditListener> listeners

realSource

protected Object realSource
Constructor Detail

UndoableEditSupport

public UndoableEditSupport()
Constructs an UndoableEditSupport object.

UndoableEditSupport

public UndoableEditSupport(Object r)
Constructs an UndoableEditSupport object.

Parameters:
r - an Object
Method Detail

addUndoableEditListener

public void addUndoableEditListener(UndoableEditListener l)
Registers an UndoableEditListener. The listener is notified whenever an edit occurs which can be undone.

Parameters:
l - an UndoableEditListener object
See Also:
removeUndoableEditListener(javax.swing.event.UndoableEditListener)

removeUndoableEditListener

public void removeUndoableEditListener(UndoableEditListener l)
Removes an UndoableEditListener.

Parameters:
l - the UndoableEditListener object to be removed
See Also:
addUndoableEditListener(javax.swing.event.UndoableEditListener)

getUndoableEditListeners

public UndoableEditListener[] getUndoableEditListeners()
Returns an array of all the UndoableEditListeners added to this UndoableEditSupport with addUndoableEditListener().

Returns:
all of the UndoableEditListeners added or an empty array if no listeners have been added
Since:
1.4

_postEdit

protected void _postEdit(UndoableEdit e)
Called only from postEdit and endUpdate. Calls undoableEditHappened in all listeners. No synchronization is performed here, since the two calling methods are synchronized.

postEdit

public void postEdit(UndoableEdit e)
DEADLOCK WARNING: Calling this method may call undoableEditHappened in all listeners. It is unwise to call this method from one of its listeners.

getUpdateLevel

public int getUpdateLevel()
Returns the update level value.

Returns:
an integer representing the update level

beginUpdate

public void beginUpdate()

createCompoundEdit

protected CompoundEdit createCompoundEdit()
Called only from beginUpdate. Exposed here for subclasses' use.

endUpdate

public void endUpdate()
DEADLOCK WARNING: Calling this method may call undoableEditHappened in all listeners. It is unwise to call this method from one of its listeners.

toString

public String toString()
Returns a string that displays and identifies this object's properties.

Overrides:
toString in class Object
Returns:
a String representation of this object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UndoManager

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing.undo
Class UndoManager

java.lang.Object
    extended by  javax.swing.undo.AbstractUndoableEdit
        extended by  javax.swing.undo.CompoundEdit
            extended by  javax.swing.undo.UndoManager
All Implemented Interfaces:
Serializable, EventListener, UndoableEditListener, UndoableEdit
public class UndoManager
extends CompoundEdit
implements UndoableEditListener

UndoManager manages a list of UndoableEdits, providing a way to undo or redo the appropriate edits. There are two ways to add edits to an UndoManager. Add the edit directly using the addEdit method, or add the UndoManager to a bean that supports UndoableEditListener. The following examples creates an UndoManager and adds it as an UndoableEditListener to a JTextField:

   UndoManager undoManager = new UndoManager();
   JTextField tf = ...;
   tf.getDocument().addUndoableEditListener(undoManager);

UndoManager maintains an ordered list of edits and the index of the next edit in that list. The index of the next edit is either the size of the current list of edits, or if undo has been invoked it corresponds to the index of the last significant edit that was undone. When undo is invoked all edits from the index of the next edit to the last significant edit are undone, in reverse order. For example, consider an UndoManager consisting of the following edits: A b c D. Edits with a upper-case letter in bold are significant, those in lower-case and italicized are insignificant.

Figure 1

As shown in figure 1, if D was just added, the index of the next edit will be 4. Invoking undo results in invoking undo on D and setting the index of the next edit to 3 (edit c), as shown in the following figure.

Figure 2

The last significant edit is A, so that invoking undo again invokes undo on c, b, and A, in that order, setting the index of the next edit to 0, as shown in the following figure.

Figure 3

Invoking redo results in invoking redo on all edits between the index of the next edit and the next significant edit (or the end of the list). Continuing with the previous example if redo were invoked, redo would in turn be invoked on A, b and c. In addition the index of the next edit is set to 3 (as shown in figure 2).

Adding an edit to an UndoManager results in removing all edits from the index of the next edit to the end of the list. Continuing with the previous example, if a new edit, e, is added the edit D is removed from the list (after having die invoked on it). If c is not incorporated by the next edit (c.addEdit(e) returns true), or replaced by it (e.replaceEdit(c) returns true), the new edit is added after c, as shown in the following figure.

Figure 4

Once end has been invoked on an UndoManager the superclass behavior is used for all UndoableEdit methods. Refer to CompoundEdit for more details on its behavior.

Unlike the rest of Swing, this class is thread safe.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Field Summary
Fields inherited from class javax.swing.undo.CompoundEdit
edits
Fields inherited from class javax.swing.undo.AbstractUndoableEdit
RedoName, UndoName
Constructor Summary
UndoManager()
Creates a new UndoManager.
Method Summary
boolean | addEdit(UndoableEdit anEdit) Adds an UndoableEdit to this UndoManager, if it's possible.
boolean | canRedo() Returns true if edits may be redone.
boolean | canUndo() Returns true if edits may be undone.
boolean | canUndoOrRedo() Returns true if it is possible to invoke undo or redo.
void | discardAllEdits() Empties the undo manager sending each edit a die message in the process.
protected UndoableEdit | editToBeRedone() Returns the the next significant edit to be redone if redo is invoked.
protected UndoableEdit | editToBeUndone() Returns the the next significant edit to be undone if undo is invoked.
void | end() Turns this UndoManager into a normal CompoundEdit.
int | getLimit() Returns the maximum number of edits this UndoManager holds.
String | getRedoPresentationName() Returns a description of the redoable form of this edit.
String | getUndoOrRedoPresentationName() Convenience method that returns either getUndoPresentationName or getRedoPresentationName.
String | getUndoPresentationName() Returns a description of the undoable form of this edit.
void | redo() Redoes the appropriate edits.
protected void | redoTo(UndoableEdit edit) Redoes all changes from the index of the next edit to edit, updating the index of the next edit appropriately.
void | setLimit(int l) Sets the maximum number of edits this UndoManager holds.
String | toString() Returns a string that displays and identifies this object's properties.
protected void | trimEdits(int from, int to) Removes edits in the specified range.
protected void | trimForLimit() Reduces the number of queued edits to a range of size limit, centered on the index of the next edit.
void | undo() Undoes the appropriate edits.
void | undoableEditHappened(UndoableEditEvent e) An UndoableEditListener method.
void | undoOrRedo() Convenience method that invokes one of undo or redo.
protected void | undoTo(UndoableEdit edit) Undoes all changes from the index of the next edit to edit, updating the index of the next edit appropriately.
Methods inherited from class javax.swing.undo.CompoundEdit
die, getPresentationName, isInProgress, isSignificant, lastEdit
Methods inherited from class javax.swing.undo.AbstractUndoableEdit
replaceEdit
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UndoManager

public UndoManager()
Creates a new UndoManager.

Method Detail

getLimit

public int getLimit()
Returns the maximum number of edits this UndoManager holds. A value less than 0 indicates the number of edits is not limited.

Returns:
the maximum number of edits this UndoManager holds
See Also:
addEdit(javax.swing.undo.UndoableEdit), setLimit(int)

discardAllEdits

public void discardAllEdits()
Empties the undo manager sending each edit a die message in the process.

See Also:
AbstractUndoableEdit.die()

trimForLimit

protected void trimForLimit()
Reduces the number of queued edits to a range of size limit, centered on the index of the next edit.

trimEdits

protected void trimEdits(int from,
                         int to)
Removes edits in the specified range. All edits in the given range (inclusive, and in reverse order) will have die invoked on them and are removed from the list of edits. This has no effect if from > to.

Parameters:
from - the minimum index to remove
to - the maximum index to remove

setLimit

public void setLimit(int l)
Sets the maximum number of edits this UndoManager holds. A value less than 0 indicates the number of edits is not limited. If edits need to be discarded to shrink the limit, die will be invoked on them in the reverse order they were added. The default is 100.

Parameters:
l - the new limit
Throws:
RuntimeException - if this UndoManager is not in progress (end has been invoked)
See Also:
CompoundEdit.isInProgress(),
end(),
addEdit(javax.swing.undo.UndoableEdit),
getLimit()

editToBeUndone

protected UndoableEdit editToBeUndone()
Returns the the next significant edit to be undone if undo is invoked. This returns null if there are no edits to be undone.

Returns:
the next significant edit to be undone

editToBeRedone

protected UndoableEdit editToBeRedone()
Returns the the next significant edit to be redone if redo is invoked. This returns null if there are no edits to be redone.

Returns:
the next significant edit to be redone

undoTo

protected void undoTo(UndoableEdit edit)
               throws CannotUndoException
Undoes all changes from the index of the next edit to edit, updating the index of the next edit appropriately.

Throws:
CannotUndoException - if one of the edits throws CannotUndoException

redoTo

protected void redoTo(UndoableEdit edit)
               throws CannotRedoException
Redoes all changes from the index of the next edit to edit, updating the index of the next edit appropriately.

Throws:
CannotRedoException - if one of the edits throws CannotRedoException

undoOrRedo

public void undoOrRedo()
                throws CannotRedoException,
                       CannotUndoException
Convenience method that invokes one of undo or redo. If any edits have been undone (the index of the next edit is less than the length of the edits list) this invokes redo, otherwise it invokes undo.

Throws:
CannotUndoException - if one of the edits throws CannotUndoException
CannotRedoException - if one of the edits throws CannotRedoException
See Also:
canUndoOrRedo(), getUndoOrRedoPresentationName()

canUndoOrRedo

public boolean canUndoOrRedo()
Returns true if it is possible to invoke undo or redo.

Returns:
true if invoking canUndoOrRedo is valid
See Also:
undoOrRedo()

undo

public void undo()
          throws CannotUndoException
Undoes the appropriate edits. If end has been invoked this calls through to the superclass, otherwise this invokes undo on all edits between the index of the next edit and the last significant edit, updating the index of the next edit appropriately.

Specified by:
undo in interface UndoableEdit
Overrides:
undo in class CompoundEdit
Throws:
CannotUndoException - if one of the edits throws CannotUndoException or there are no edits to be undone
See Also:
CompoundEdit.end(),
canUndo(),
editToBeUndone()

canUndo

public boolean canUndo()
Returns true if edits may be undone. If end has been invoked, this returns the value from super. Otherwise this returns true if there are any edits to be undone (editToBeUndone returns non-null).

Specified by:
canUndo in interface UndoableEdit
Overrides:
canUndo in class CompoundEdit
Returns:
true if there are edits to be undone
See Also:
CompoundEdit.canUndo(), editToBeUndone()

redo

public void redo()
          throws CannotRedoException
Redoes the appropriate edits. If end has been invoked this calls through to the superclass. Otherwise this invokes redo on all edits between the index of the next edit and the next significant edit, updating the index of the next edit appropriately.

Specified by:
redo in interface UndoableEdit
Overrides:
redo in class CompoundEdit
Throws:
CannotRedoException - if one of the edits throws CannotRedoException or there are no edits to be redone
See Also:
CompoundEdit.end(),
canRedo(),
editToBeRedone()

canRedo

public boolean canRedo()
Returns true if edits may be redone. If end has been invoked, this returns the value from super. Otherwise, this returns true if there are any edits to be redone (editToBeRedone returns non-null).

Specified by:
canRedo in interface UndoableEdit
Overrides:
canRedo in class CompoundEdit
Returns:
true if there are edits to be redone
See Also:
CompoundEdit.canRedo(), editToBeRedone()

addEdit

public boolean addEdit(UndoableEdit anEdit)
Adds an UndoableEdit to this UndoManager, if it's possible. This removes all edits from the index of the next edit to the end of the edits list. If end has been invoked the edit is not added and false is returned. If end hasn't been invoked this returns true.

Specified by:
addEdit in interface UndoableEdit
Overrides:
addEdit in class CompoundEdit
Parameters:
anEdit - the edit to be added
Returns:
true if anEdit can be incorporated into this edit
See Also:
CompoundEdit.end(), CompoundEdit.addEdit(javax.swing.undo.UndoableEdit)

end

public void end()
Turns this UndoManager into a normal CompoundEdit. This removes all edits that have been undone.

Overrides:
end in class CompoundEdit
See Also:
CompoundEdit.end()

getUndoOrRedoPresentationName

public String getUndoOrRedoPresentationName()
Convenience method that returns either getUndoPresentationName or getRedoPresentationName. If the index of the next edit equals the size of the edits list, getUndoPresentationName is returned, otherwise getRedoPresentationName is returned.

Returns:
undo or redo name

getUndoPresentationName

public String getUndoPresentationName()
Returns a description of the undoable form of this edit. If end has been invoked this calls into super. Otherwise if there are edits to be undone, this returns the value from the next significant edit that will be undone. If there are no edits to be undone and end has not been invoked this returns the value from the UIManager property "AbstractUndoableEdit.undoText".

Specified by:
getUndoPresentationName in interface UndoableEdit
Overrides:
getUndoPresentationName in class CompoundEdit
Returns:
a description of the undoable form of this edit
See Also:
undo(), CompoundEdit.getUndoPresentationName()

getRedoPresentationName

public String getRedoPresentationName()
Returns a description of the redoable form of this edit. If end has been invoked this calls into super. Otherwise if there are edits to be redone, this returns the value from the next significant edit that will be redone. If there are no edits to be redone and end has not been invoked this returns the value from the UIManager property "AbstractUndoableEdit.redoText".

Specified by:
getRedoPresentationName in interface UndoableEdit
Overrides:
getRedoPresentationName in class CompoundEdit
Returns:
a description of the redoable form of this edit
See Also:
redo(), CompoundEdit.getRedoPresentationName()

undoableEditHappened

public void undoableEditHappened(UndoableEditEvent e)
An UndoableEditListener method. This invokes addEdit with e.getEdit().

Specified by:
undoableEditHappened in interface UndoableEditListener
Parameters:
e - the UndoableEditEvent the UndoableEditEvent will be added from
See Also:
addEdit(javax.swing.undo.UndoableEdit)

toString

public String toString()
Returns a string that displays and identifies this object's properties.

Overrides:
toString in class CompoundEdit
Returns:
a String representation of this object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


UnsupportedLookAndFeelException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class UnsupportedLookAndFeelException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.swing.UnsupportedLookAndFeelException
All Implemented Interfaces:
Serializable
public class UnsupportedLookAndFeelException
extends Exception

An exception that indicates the requested look & feel management classes are not present on the user's system.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
UnsupportedLookAndFeelException(String s)
Constructs an UnsupportedLookAndFeelException object.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UnsupportedLookAndFeelException

public UnsupportedLookAndFeelException(String s)
Constructs an UnsupportedLookAndFeelException object.

Parameters:
s - a message String
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ViewportLayout

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.swing
Class ViewportLayout

java.lang.Object
    extended by  javax.swing.ViewportLayout
All Implemented Interfaces:
LayoutManager, Serializable
public class ViewportLayout
extends Object
implements LayoutManager, Serializable

The default layout manager for JViewport. ViewportLayout defines a policy for layout that should be useful for most applications. The viewport makes its view the same size as the viewport, however it will not make the view smaller than its minimum size. As the viewport grows the view is kept bottom justified until the entire view is visible, subsequently the view is kept top justified.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see XMLEncoder.

Constructor Summary
ViewportLayout()
Method Summary
void | addLayoutComponent(String name, Component c) Adds the specified component to the layout.
void | layoutContainer(Container parent) Called by the AWT when the specified container needs to be laid out.
Dimension | minimumLayoutSize(Container parent) Returns the minimum dimensions needed to layout the components contained in the specified target container.
Dimension | preferredLayoutSize(Container parent) Returns the preferred dimensions for this layout given the components in the specified target container.
void | removeLayoutComponent(Component c) Removes the specified component from the layout.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ViewportLayout

public ViewportLayout()
Method Detail

addLayoutComponent

public void addLayoutComponent(String name,
                               Component c)
Adds the specified component to the layout. Not used by this class.

Specified by:
addLayoutComponent in interface LayoutManager
Parameters:
name - the name of the component
c - the the component to be added

removeLayoutComponent

public void removeLayoutComponent(Component c)
Removes the specified component from the layout. Not used by this class.

Specified by:
removeLayoutComponent in interface LayoutManager
Parameters:
c - the component to remove

preferredLayoutSize

public Dimension preferredLayoutSize(Container parent)
Returns the preferred dimensions for this layout given the components in the specified target container.

Specified by:
preferredLayoutSize in interface LayoutManager
Parameters:
parent - the component which needs to be laid out
Returns:
a Dimension object containing the preferred dimensions
See Also:
minimumLayoutSize(java.awt.Container)

minimumLayoutSize

public Dimension minimumLayoutSize(Container parent)
Returns the minimum dimensions needed to layout the components contained in the specified target container.

Specified by:
minimumLayoutSize in interface LayoutManager
Parameters:
parent - the component which needs to be laid out
Returns:
a Dimension object containing the minimum dimensions
See Also:
preferredLayoutSize(java.awt.Container)

layoutContainer

public void layoutContainer(Container parent)
Called by the AWT when the specified container needs to be laid out.

Specified by:
layoutContainer in interface LayoutManager
Parameters:
parent - the container to lay out
Throws:
AWTError - if the target isn't the container specified to the BoxLayout constructor
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WindowConstants

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.swing
Interface WindowConstants

All Known Implementing Classes:
JDialog, JFrame, JInternalFrame
public interface WindowConstants

Constants used to control the window-closing operation. The setDefaultCloseOperation and getDefaultCloseOperation methods provided by JFrame, JInternalFrame, and JDialog use these constants. For examples of setting the default window-closing operation, see Responding to Window-Closing Events, a section in The Java Tutorial.

See Also:
JFrame.setDefaultCloseOperation(int),
JDialog.setDefaultCloseOperation(int),
JInternalFrame.setDefaultCloseOperation(int)

Field Summary
static int | DISPOSE_ON_CLOSE The dispose-window default window close operation.
static int | DO_NOTHING_ON_CLOSE The do-nothing default window close operation.
static int | EXIT_ON_CLOSE The exit application default window close operation.
static int | HIDE_ON_CLOSE The hide-window default window close operation

Field Detail

DO_NOTHING_ON_CLOSE

static final int DO_NOTHING_ON_CLOSE
The do-nothing default window close operation.

See Also:
Constant Field Values

HIDE_ON_CLOSE

static final int HIDE_ON_CLOSE
The hide-window default window close operation

See Also:
Constant Field Values

DISPOSE_ON_CLOSE

static final int DISPOSE_ON_CLOSE
The dispose-window default window close operation.

Note: When the last displayable window within the Java virtual machine (VM) is disposed of, the VM may terminate. See AWT Threading Issues for more information.

See Also:
Window.dispose(), JInternalFrame.dispose(), Constant Field Values

EXIT_ON_CLOSE

static final int EXIT_ON_CLOSE
The exit application default window close operation. Attempting to set this on Windows that support this, such as JFrame, may throw a SecurityException based on the SecurityManager. It is recommended you only use this in an application.

Since:
1.4
See Also:
JFrame.setDefaultCloseOperation(int), Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


tools

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.tools

Provides interfaces for tools which can be invoked from a program, for example, compilers.

See:
Description

Interface Summary
Diagnostic<S> | Interface for diagnostics from tools.
DiagnosticListener<S> | Interface for receiving diagnostics from tools.
FileObject | File abstraction for tools.
JavaCompiler | Interface to invoke Java™ programming language compilers from programs.
JavaCompiler.CompilationTask | Interface representing a future for a compilation task.
JavaFileManager | File manager for tools operating on Java™ programming language source and class files.
JavaFileManager.Location | Interface for locations of file objects.
JavaFileObject | File abstraction for tools operating on Java™ programming language source and class files.
OptionChecker | Interface for recognizing options.
StandardJavaFileManager | File manager based on java.io.File.
Tool | Common interface for tools that can be invoked from a program.

Class Summary
DiagnosticCollector<S> | Provides an easy way to collect diagnostics in a list.
ForwardingFileObject<F extends FileObject> | Forwards calls to a given file object.
ForwardingJavaFileManager<M extends JavaFileManager> | Forwards calls to a given file manager.
ForwardingJavaFileObject<F extends JavaFileObject> | Forwards calls to a given file object.
SimpleJavaFileObject | Provides simple implementations for most methods in JavaFileObject.
ToolProvider | Provides methods for locating tool providers, for example, providers of compilers.

Enum Summary
Diagnostic.Kind | Kinds of diagnostics, for example, error or warning.
JavaFileObject.Kind | Kinds of JavaFileObjects.
StandardLocation | Standard locations of file objects.

Package javax.tools Description

Provides interfaces for tools which can be invoked from a program, for example, compilers.

These interfaces and classes are required as part of the Java™ Platform, Standard Edition (Java SE), but there is no requirement to provide any tools implementing them.

Unless explicitly allowed, all methods in this package might throw a NullPointerException if given a null argument or if given a list or collection containing null elements. Similarly, no method may return null unless explicitly allowed.

This package is the home of the Java programming language compiler framework. This framework allows clients of the framework to locate and run compilers from programs. The framework also provides Service Provider Interfaces (SPI) for structured access to diagnostics (DiagnosticListener) as well as a file abstraction for overriding file access (JavaFileManager and JavaFileObject). See JavaCompiler for more details on using the SPI.

There is no requirement for a compiler at runtime. However, if a default compiler is provided, it can be located using the ToolProvider, for example:

JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();

It is possible to provide alternative compilers or tools through the service provider mechanism.

For example, if com.vendor.VendorJavaCompiler is a provider of the JavaCompiler tool then its jar file would contain the file META-INF/services/javax.tools.JavaCompiler. This file would contain the single line:

com.vendor.VendorJavaCompiler

If the jar file is on the class path, VendorJavaCompiler can be located using code like this:

JavaCompiler compiler = ServiceLoader.load(JavaCompiler.class).iterator().next();

Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.tools Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.tools

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.tools.DiagnosticCollector<S> (implements javax.tools.DiagnosticListener<S>)
    • javax.tools.ForwardingFileObject<F> (implements javax.tools.FileObject)
      • javax.tools.ForwardingJavaFileObject<F> (implements javax.tools.JavaFileObject)
    • javax.tools.ForwardingJavaFileManager<M> (implements javax.tools.JavaFileManager)
    • javax.tools.SimpleJavaFileObject (implements javax.tools.JavaFileObject)
    • javax.tools.ToolProvider

Interface Hierarchy

  • java.util.concurrent.Callable<V>
    • javax.tools.JavaCompiler.CompilationTask
  • java.io.Closeable
    • javax.tools.JavaFileManager (also extends java.io.Flushable, javax.tools.OptionChecker)
      • javax.tools.StandardJavaFileManager
  • javax.tools.Diagnostic<S>
  • javax.tools.DiagnosticListener<S>
  • javax.tools.FileObject
    • javax.tools.JavaFileObject
  • java.io.Flushable
    • javax.tools.JavaFileManager (also extends java.io.Closeable, javax.tools.OptionChecker)
      • javax.tools.StandardJavaFileManager
  • javax.tools.JavaFileManager.Location
  • javax.tools.OptionChecker
    • javax.tools.JavaCompiler (also extends javax.tools.Tool)
    • javax.tools.JavaFileManager (also extends java.io.Closeable, java.io.Flushable)
      • javax.tools.StandardJavaFileManager
  • javax.tools.Tool
    • javax.tools.JavaCompiler (also extends javax.tools.OptionChecker)

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • javax.tools.StandardLocation (implements javax.tools.JavaFileManager.Location)
      • javax.tools.JavaFileObject.Kind
      • javax.tools.Diagnostic.Kind
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.tools

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.tools

Packages that use javax.tools
javax.annotation.processing | Facilities for declaring annotation processors and for allowing annotation processors to communicate with an annotation processing tool environment.
javax.tools | Provides interfaces for tools which can be invoked from a program, for example, compilers.

Classes in javax.tools used by javax.annotation.processing
Diagnostic.Kind
Kinds of diagnostics, for example, error or warning.
FileObject
File abstraction for tools.
JavaFileManager.Location
Interface for locations of file objects.
JavaFileObject
File abstraction for tools operating on Java™ programming language source and class files.

Classes in javax.tools used by javax.tools
Diagnostic
Interface for diagnostics from tools.
Diagnostic.Kind
Kinds of diagnostics, for example, error or warning.
DiagnosticListener
Interface for receiving diagnostics from tools.
FileObject
File abstraction for tools.
ForwardingFileObject
Forwards calls to a given file object.
JavaCompiler
Interface to invoke Java™ programming language compilers from programs.
JavaCompiler.CompilationTask
Interface representing a future for a compilation task.
JavaFileManager
File manager for tools operating on Java™ programming language source and class files.
JavaFileManager.Location
Interface for locations of file objects.
JavaFileObject
File abstraction for tools operating on Java™ programming language source and class files.
JavaFileObject.Kind
Kinds of JavaFileObjects.
OptionChecker
Interface for recognizing options.
StandardJavaFileManager
File manager based on java.io.File.
StandardLocation
Standard locations of file objects.
Tool
Common interface for tools that can be invoked from a program.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.tools.Diagnostic.Kind

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.tools.Diagnostic.Kind

Packages that use Diagnostic.Kind
javax.annotation.processing | Facilities for declaring annotation processors and for allowing annotation processors to communicate with an annotation processing tool environment.
javax.tools | Provides interfaces for tools which can be invoked from a program, for example, compilers.

Uses of Diagnostic.Kind in javax.annotation.processing

Methods in javax.annotation.processing with parameters of type Diagnostic.Kind
void | Messager.printMessage(Diagnostic.Kind kind, CharSequence msg) Prints a message of the specified kind.
void | Messager.printMessage(Diagnostic.Kind kind, CharSequence msg, Element e) Prints a message of the specified kind at the location of the element.
void | Messager.printMessage(Diagnostic.Kind kind, CharSequence msg, Element e, AnnotationMirror a) Prints a message of the specified kind at the location of the annotation mirror of the annotated element.
void | Messager.printMessage(Diagnostic.Kind kind, CharSequence msg, Element e, AnnotationMirror a, AnnotationValue v) Prints a message of the specified kind at the location of the annotation value inside the annotation mirror of the annotated element.

Uses of Diagnostic.Kind in javax.tools

Methods in javax.tools that return Diagnostic.Kind
Diagnostic.Kind | Diagnostic.getKind() Gets the kind of this diagnostic, for example, error or warning.
static Diagnostic.Kind | Diagnostic.Kind.valueOf(String name) Returns the enum constant of this type with the specified name.
static Diagnostic.Kind[] | Diagnostic.Kind.values() Returns an array containing the constants of this enum type, in the order they are declared.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.tools.DiagnosticCollector

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.tools.DiagnosticCollector

No usage of javax.tools.DiagnosticCollector

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.tools.ForwardingFileObject

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.tools.ForwardingFileObject

Packages that use ForwardingFileObject
javax.tools Provides interfaces for tools which can be invoked from a program, for example, compilers.

Uses of ForwardingFileObject in javax.tools

Subclasses of ForwardingFileObject in javax.tools
 class ForwardingJavaFileObject<F extends JavaFileObject>
Forwards calls to a given file object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.tools.ForwardingJavaFileManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.tools.ForwardingJavaFileManager

No usage of javax.tools.ForwardingJavaFileManager

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.tools.ForwardingJavaFileObject

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.tools.ForwardingJavaFileObject

No usage of javax.tools.ForwardingJavaFileObject

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.tools.JavaFileObject.Kind

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.tools.JavaFileObject.Kind

Packages that use JavaFileObject.Kind
javax.tools Provides interfaces for tools which can be invoked from a program, for example, compilers.

Uses of JavaFileObject.Kind in javax.tools

Fields in javax.tools declared as JavaFileObject.Kind
protected  JavaFileObject.Kind SimpleJavaFileObject.kind
The kind of this file object.

Methods in javax.tools that return JavaFileObject.Kind
JavaFileObject.Kind | SimpleJavaFileObject.getKind()
JavaFileObject.Kind | ForwardingJavaFileObject.getKind()
JavaFileObject.Kind | JavaFileObject.getKind() Gets the kind of this file object.
static JavaFileObject.Kind | JavaFileObject.Kind.valueOf(String name) Returns the enum constant of this type with the specified name.
static JavaFileObject.Kind[] | JavaFileObject.Kind.values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods in javax.tools with parameters of type JavaFileObject.Kind
JavaFileObject | ForwardingJavaFileManager.getJavaFileForInput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind)
JavaFileObject | JavaFileManager.getJavaFileForInput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind) Gets a file object for input representing the specified class of the specified kind in the given location.
JavaFileObject | ForwardingJavaFileManager.getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling)
JavaFileObject | JavaFileManager.getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling) Gets a file object for output representing the specified class of the specified kind in the given location.
boolean | SimpleJavaFileObject.isNameCompatible(String simpleName, JavaFileObject.Kind kind) This implementation compares the path of its URI to the given simple name.
boolean | ForwardingJavaFileObject.isNameCompatible(String simpleName, JavaFileObject.Kind kind)
boolean | JavaFileObject.isNameCompatible(String simpleName, JavaFileObject.Kind kind) Checks if this file object is compatible with the specified simple name and kind.

Method parameters in javax.tools with type arguments of type JavaFileObject.Kind
Iterable<JavaFileObject> | ForwardingJavaFileManager.list(JavaFileManager.Location location, String packageName, Set<JavaFileObject.Kind> kinds, boolean recurse)
Iterable<JavaFileObject> | JavaFileManager.list(JavaFileManager.Location location, String packageName, Set<JavaFileObject.Kind> kinds, boolean recurse) Lists all file objects matching the given criteria in the given location.

Constructors in javax.tools with parameters of type JavaFileObject.Kind
SimpleJavaFileObject(URI uri, JavaFileObject.Kind kind)
Construct a SimpleJavaFileObject of the given kind and with the given URI.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.tools.SimpleJavaFileObject

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.tools.SimpleJavaFileObject

No usage of javax.tools.SimpleJavaFileObject

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.tools.StandardLocation

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.tools.StandardLocation

Packages that use StandardLocation
javax.tools Provides interfaces for tools which can be invoked from a program, for example, compilers.

Uses of StandardLocation in javax.tools

Methods in javax.tools that return StandardLocation
static StandardLocation | StandardLocation.valueOf(String name) Returns the enum constant of this type with the specified name.
static StandardLocation[] | StandardLocation.values() Returns an array containing the constants of this enum type, in the order they are declared.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.tools.ToolProvider

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.tools.ToolProvider

No usage of javax.tools.ToolProvider

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.tools.Diagnostic

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.tools.Diagnostic

Packages that use Diagnostic
javax.tools Provides interfaces for tools which can be invoked from a program, for example, compilers.

Uses of Diagnostic in javax.tools

Methods in javax.tools that return types with arguments of type Diagnostic
 List<Diagnostic<? extends S>> DiagnosticCollector.getDiagnostics()
Gets a list view of diagnostics collected by this object.

Methods in javax.tools with parameters of type Diagnostic
void | DiagnosticCollector.report(Diagnostic<? extends S> diagnostic)
void | DiagnosticListener.report(Diagnostic<? extends S> diagnostic) Invoked when a problem is found.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.tools.DiagnosticListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.tools.DiagnosticListener

Packages that use DiagnosticListener
javax.tools Provides interfaces for tools which can be invoked from a program, for example, compilers.

Uses of DiagnosticListener in javax.tools

Classes in javax.tools that implement DiagnosticListener
 class DiagnosticCollector<S>
Provides an easy way to collect diagnostics in a list.

Methods in javax.tools with parameters of type DiagnosticListener
StandardJavaFileManager | JavaCompiler.getStandardFileManager(DiagnosticListener<? super JavaFileObject> diagnosticListener, Locale locale, Charset charset) Gets a new instance of the standard file manager implementation for this tool.
JavaCompiler.CompilationTask | JavaCompiler.getTask(Writer out, JavaFileManager fileManager, DiagnosticListener<? super JavaFileObject> diagnosticListener, Iterable<String> options, Iterable<String> classes, Iterable<? extends JavaFileObject> compilationUnits) Creates a future for a compilation task with the given components and arguments.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.tools.FileObject

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.tools.FileObject

Packages that use FileObject
javax.annotation.processing | Facilities for declaring annotation processors and for allowing annotation processors to communicate with an annotation processing tool environment.
javax.tools | Provides interfaces for tools which can be invoked from a program, for example, compilers.

Uses of FileObject in javax.annotation.processing

Methods in javax.annotation.processing that return FileObject
FileObject | Filer.createResource(JavaFileManager.Location location, CharSequence pkg, CharSequence relativeName, Element... originatingElements) Creates a new auxiliary resource file for writing and returns a file object for it.
FileObject | Filer.getResource(JavaFileManager.Location location, CharSequence pkg, CharSequence relativeName) Returns an object for reading an existing resource.

Uses of FileObject in javax.tools

Classes in javax.tools with type parameters of type FileObject
 class ForwardingFileObject<F extends FileObject>
Forwards calls to a given file object.

Subinterfaces of FileObject in javax.tools
 interface JavaFileObject
File abstraction for tools operating on Java™ programming language source and class files.

Classes in javax.tools that implement FileObject
class | ForwardingFileObject<F extends FileObject> Forwards calls to a given file object.
class | ForwardingJavaFileObject<F extends JavaFileObject> Forwards calls to a given file object.
class | SimpleJavaFileObject Provides simple implementations for most methods in JavaFileObject.

Fields in javax.tools declared as FileObject
protected  F ForwardingFileObject.fileObject
The file object which all methods are delegated to.

Methods in javax.tools that return FileObject
FileObject | ForwardingJavaFileManager.getFileForInput(JavaFileManager.Location location, String packageName, String relativeName)
FileObject | JavaFileManager.getFileForInput(JavaFileManager.Location location, String packageName, String relativeName) Gets a file object for input representing the specified relative name in the specified package in the given location.
FileObject | ForwardingJavaFileManager.getFileForOutput(JavaFileManager.Location location, String packageName, String relativeName, FileObject sibling)
FileObject | JavaFileManager.getFileForOutput(JavaFileManager.Location location, String packageName, String relativeName, FileObject sibling) Gets a file object for output representing the specified relative name in the specified package in the given location.

Methods in javax.tools with parameters of type FileObject
FileObject | ForwardingJavaFileManager.getFileForOutput(JavaFileManager.Location location, String packageName, String relativeName, FileObject sibling)
FileObject | JavaFileManager.getFileForOutput(JavaFileManager.Location location, String packageName, String relativeName, FileObject sibling) Gets a file object for output representing the specified relative name in the specified package in the given location.
JavaFileObject | ForwardingJavaFileManager.getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling)
JavaFileObject | JavaFileManager.getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling) Gets a file object for output representing the specified class of the specified kind in the given location.
boolean | ForwardingJavaFileManager.isSameFile(FileObject a, FileObject b)
boolean | StandardJavaFileManager.isSameFile(FileObject a, FileObject b) Compares two file objects and return true if they represent the same canonical file, zip file entry, or entry in any file system based container.
boolean | JavaFileManager.isSameFile(FileObject a, FileObject b) Compares two file objects and return true if they represent the same underlying object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.tools.JavaCompiler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.tools.JavaCompiler

Packages that use JavaCompiler
javax.tools Provides interfaces for tools which can be invoked from a program, for example, compilers.

Uses of JavaCompiler in javax.tools

Methods in javax.tools that return JavaCompiler
static JavaCompiler ToolProvider.getSystemJavaCompiler()
Gets the Java™ programming language compiler provided with this platform.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.tools.JavaCompiler.CompilationTask

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.tools.JavaCompiler.CompilationTask

Packages that use JavaCompiler.CompilationTask
javax.tools Provides interfaces for tools which can be invoked from a program, for example, compilers.

Uses of JavaCompiler.CompilationTask in javax.tools

Methods in javax.tools that return JavaCompiler.CompilationTask
 JavaCompiler.CompilationTask JavaCompiler.getTask(Writer out, JavaFileManager fileManager, DiagnosticListener<? super JavaFileObject> diagnosticListener, Iterable<String> options, Iterable<String> classes, Iterable<? extends JavaFileObject> compilationUnits)
Creates a future for a compilation task with the given components and arguments.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.tools.JavaFileManager

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.tools.JavaFileManager

Packages that use JavaFileManager
javax.tools Provides interfaces for tools which can be invoked from a program, for example, compilers.

Uses of JavaFileManager in javax.tools

Classes in javax.tools with type parameters of type JavaFileManager
 class ForwardingJavaFileManager<M extends JavaFileManager>
Forwards calls to a given file manager.

Subinterfaces of JavaFileManager in javax.tools
 interface StandardJavaFileManager
File manager based on java.io.File.

Classes in javax.tools that implement JavaFileManager
 class ForwardingJavaFileManager<M extends JavaFileManager>
Forwards calls to a given file manager.

Fields in javax.tools declared as JavaFileManager
protected  M ForwardingJavaFileManager.fileManager
The file manager which all methods are delegated to.

Methods in javax.tools with parameters of type JavaFileManager
 JavaCompiler.CompilationTask JavaCompiler.getTask(Writer out, JavaFileManager fileManager, DiagnosticListener<? super JavaFileObject> diagnosticListener, Iterable<String> options, Iterable<String> classes, Iterable<? extends JavaFileObject> compilationUnits)
Creates a future for a compilation task with the given components and arguments.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.tools.JavaFileManager.Location

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.tools.JavaFileManager.Location

Packages that use JavaFileManager.Location
javax.annotation.processing | Facilities for declaring annotation processors and for allowing annotation processors to communicate with an annotation processing tool environment.
javax.tools | Provides interfaces for tools which can be invoked from a program, for example, compilers.

Uses of JavaFileManager.Location in javax.annotation.processing

Methods in javax.annotation.processing with parameters of type JavaFileManager.Location
FileObject | Filer.createResource(JavaFileManager.Location location, CharSequence pkg, CharSequence relativeName, Element... originatingElements) Creates a new auxiliary resource file for writing and returns a file object for it.
FileObject | Filer.getResource(JavaFileManager.Location location, CharSequence pkg, CharSequence relativeName) Returns an object for reading an existing resource.

Uses of JavaFileManager.Location in javax.tools

Classes in javax.tools that implement JavaFileManager.Location
 class StandardLocation
Standard locations of file objects.

Methods in javax.tools that return JavaFileManager.Location
static JavaFileManager.Location StandardLocation.locationFor(String name)
Gets a location object with the given name.

Methods in javax.tools with parameters of type JavaFileManager.Location
ClassLoader | ForwardingJavaFileManager.getClassLoader(JavaFileManager.Location location)
ClassLoader | JavaFileManager.getClassLoader(JavaFileManager.Location location) Gets a class loader for loading plug-ins from the given location.
FileObject | ForwardingJavaFileManager.getFileForInput(JavaFileManager.Location location, String packageName, String relativeName)
FileObject | JavaFileManager.getFileForInput(JavaFileManager.Location location, String packageName, String relativeName) Gets a file object for input representing the specified relative name in the specified package in the given location.
FileObject | ForwardingJavaFileManager.getFileForOutput(JavaFileManager.Location location, String packageName, String relativeName, FileObject sibling)
FileObject | JavaFileManager.getFileForOutput(JavaFileManager.Location location, String packageName, String relativeName, FileObject sibling) Gets a file object for output representing the specified relative name in the specified package in the given location.
JavaFileObject | ForwardingJavaFileManager.getJavaFileForInput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind)
JavaFileObject | JavaFileManager.getJavaFileForInput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind) Gets a file object for input representing the specified class of the specified kind in the given location.
JavaFileObject | ForwardingJavaFileManager.getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling)
JavaFileObject | JavaFileManager.getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling) Gets a file object for output representing the specified class of the specified kind in the given location.
Iterable<? extends File> | StandardJavaFileManager.getLocation(JavaFileManager.Location location) Gets the path associated with the given location.
boolean | ForwardingJavaFileManager.hasLocation(JavaFileManager.Location location)
boolean | JavaFileManager.hasLocation(JavaFileManager.Location location) Determines if a location is known to this file manager.
String | ForwardingJavaFileManager.inferBinaryName(JavaFileManager.Location location, JavaFileObject file)
String | JavaFileManager.inferBinaryName(JavaFileManager.Location location, JavaFileObject file) Infers a binary name of a file object based on a location.
Iterable<JavaFileObject> | ForwardingJavaFileManager.list(JavaFileManager.Location location, String packageName, Set<JavaFileObject.Kind> kinds, boolean recurse)
Iterable<JavaFileObject> | JavaFileManager.list(JavaFileManager.Location location, String packageName, Set<JavaFileObject.Kind> kinds, boolean recurse) Lists all file objects matching the given criteria in the given location.
void | StandardJavaFileManager.setLocation(JavaFileManager.Location location, Iterable<? extends File> path) Associates the given path with the given location.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.tools.JavaFileObject

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.tools.JavaFileObject

Packages that use JavaFileObject
javax.annotation.processing | Facilities for declaring annotation processors and for allowing annotation processors to communicate with an annotation processing tool environment.
javax.tools | Provides interfaces for tools which can be invoked from a program, for example, compilers.

Uses of JavaFileObject in javax.annotation.processing

Methods in javax.annotation.processing that return JavaFileObject
JavaFileObject | Filer.createClassFile(CharSequence name, Element... originatingElements) Creates a new class file, and returns an object to allow writing to it.
JavaFileObject | Filer.createSourceFile(CharSequence name, Element... originatingElements) Creates a new source file and returns an object to allow writing to it.

Uses of JavaFileObject in javax.tools

Classes in javax.tools with type parameters of type JavaFileObject
 class ForwardingJavaFileObject<F extends JavaFileObject>
Forwards calls to a given file object.

Classes in javax.tools that implement JavaFileObject
class | ForwardingJavaFileObject<F extends JavaFileObject> Forwards calls to a given file object.
class | SimpleJavaFileObject Provides simple implementations for most methods in JavaFileObject.

Methods in javax.tools that return JavaFileObject
JavaFileObject | ForwardingJavaFileManager.getJavaFileForInput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind)
JavaFileObject | JavaFileManager.getJavaFileForInput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind) Gets a file object for input representing the specified class of the specified kind in the given location.
JavaFileObject | ForwardingJavaFileManager.getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling)
JavaFileObject | JavaFileManager.getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling) Gets a file object for output representing the specified class of the specified kind in the given location.

Methods in javax.tools that return types with arguments of type JavaFileObject
Iterable<? extends JavaFileObject> | StandardJavaFileManager.getJavaFileObjects(File... files) Gets file objects representing the given files.
Iterable<? extends JavaFileObject> | StandardJavaFileManager.getJavaFileObjects(String... names) Gets file objects representing the given file names.
Iterable<? extends JavaFileObject> | StandardJavaFileManager.getJavaFileObjectsFromFiles(Iterable<? extends File> files) Gets file objects representing the given files.
Iterable<? extends JavaFileObject> | StandardJavaFileManager.getJavaFileObjectsFromStrings(Iterable<String> names) Gets file objects representing the given file names.
Iterable<JavaFileObject> | ForwardingJavaFileManager.list(JavaFileManager.Location location, String packageName, Set<JavaFileObject.Kind> kinds, boolean recurse)
Iterable<JavaFileObject> | JavaFileManager.list(JavaFileManager.Location location, String packageName, Set<JavaFileObject.Kind> kinds, boolean recurse) Lists all file objects matching the given criteria in the given location.

Methods in javax.tools with parameters of type JavaFileObject
String | ForwardingJavaFileManager.inferBinaryName(JavaFileManager.Location location, JavaFileObject file)
String | JavaFileManager.inferBinaryName(JavaFileManager.Location location, JavaFileObject file) Infers a binary name of a file object based on a location.

Method parameters in javax.tools with type arguments of type JavaFileObject
StandardJavaFileManager | JavaCompiler.getStandardFileManager(DiagnosticListener<? super JavaFileObject> diagnosticListener, Locale locale, Charset charset) Gets a new instance of the standard file manager implementation for this tool.
JavaCompiler.CompilationTask | JavaCompiler.getTask(Writer out, JavaFileManager fileManager, DiagnosticListener<? super JavaFileObject> diagnosticListener, Iterable<String> options, Iterable<String> classes, Iterable<? extends JavaFileObject> compilationUnits) Creates a future for a compilation task with the given components and arguments.
JavaCompiler.CompilationTask | JavaCompiler.getTask(Writer out, JavaFileManager fileManager, DiagnosticListener<? super JavaFileObject> diagnosticListener, Iterable<String> options, Iterable<String> classes, Iterable<? extends JavaFileObject> compilationUnits) Creates a future for a compilation task with the given components and arguments.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.tools.OptionChecker

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.tools.OptionChecker

Packages that use OptionChecker
javax.tools Provides interfaces for tools which can be invoked from a program, for example, compilers.

Uses of OptionChecker in javax.tools

Subinterfaces of OptionChecker in javax.tools
interface | JavaCompiler Interface to invoke Java™ programming language compilers from programs.
interface | JavaFileManager File manager for tools operating on Java™ programming language source and class files.
interface | StandardJavaFileManager File manager based on java.io.File.

Classes in javax.tools that implement OptionChecker
 class ForwardingJavaFileManager<M extends JavaFileManager>
Forwards calls to a given file manager.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.tools.StandardJavaFileManager

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.tools.StandardJavaFileManager

Packages that use StandardJavaFileManager
javax.tools Provides interfaces for tools which can be invoked from a program, for example, compilers.

Uses of StandardJavaFileManager in javax.tools

Methods in javax.tools that return StandardJavaFileManager
 StandardJavaFileManager JavaCompiler.getStandardFileManager(DiagnosticListener<? super JavaFileObject> diagnosticListener, Locale locale, Charset charset)
Gets a new instance of the standard file manager implementation for this tool.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.tools.Tool

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.tools.Tool

Packages that use Tool
javax.tools Provides interfaces for tools which can be invoked from a program, for example, compilers.

Uses of Tool in javax.tools

Subinterfaces of Tool in javax.tools
 interface JavaCompiler
Interface to invoke Java™ programming language compilers from programs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Diagnostic

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.tools
Interface Diagnostic<S>

Type Parameters:
S - the type of source object used by this diagnostic
public interface Diagnostic<S>

Interface for diagnostics from tools. A diagnostic usually reports a problem at a specific position in a source file. However, not all diagnostics are associated with a position or a file.

A position is a zero-based character offset from the beginning of a file. Negative values (except NOPOS) are not valid positions.

Line and column numbers begin at 1. Negative values (except NOPOS) and 0 are not valid line or column numbers.

Since:
1.6

Nested Class Summary
static class Diagnostic.Kind
Kinds of diagnostics, for example, error or warning.
Field Summary
static long NOPOS
Used to signal that no position is available.
Method Summary
 String getCode()
Gets a diagnostic code indicating the type of diagnostic.
 long getColumnNumber()
Gets the column number of the character offset returned by getPosition().
 long getEndPosition()
Gets the character offset from the beginning of the file associated with this diagnostic that indicates the end of the problem.
 Diagnostic.Kind getKind()
Gets the kind of this diagnostic, for example, error or warning.
 long getLineNumber()
Gets the line number of the character offset returned by getPosition().
 String getMessage(Locale locale)
Gets a localized message for the given locale.
 long getPosition()
Gets a character offset from the beginning of the source object associated with this diagnostic that indicates the location of the problem.
 S getSource()
Gets the source object associated with this diagnostic.
 long getStartPosition()
Gets the character offset from the beginning of the file associated with this diagnostic that indicates the start of the problem.

Field Detail

NOPOS

static final long NOPOS
Used to signal that no position is available.

See Also:
Constant Field Values
Method Detail

getKind

Diagnostic.Kind getKind()
Gets the kind of this diagnostic, for example, error or warning.

Returns:
the kind of this diagnostic

getSource

S getSource()
Gets the source object associated with this diagnostic.

Returns:
the source object associated with this diagnostic. null if no source object is associated with the diagnostic.

getPosition

long getPosition()
Gets a character offset from the beginning of the source object associated with this diagnostic that indicates the location of the problem. In addition, the following must be true:

getStartPostion() <= getPosition()

getPosition() <= getEndPosition()

Returns:
character offset from beginning of source; NOPOS if getSource() would return null or if no location is suitable

getStartPosition

long getStartPosition()
Gets the character offset from the beginning of the file associated with this diagnostic that indicates the start of the problem.

Returns:
offset from beginning of file; NOPOS if and only if getPosition() returns NOPOS

getEndPosition

long getEndPosition()
Gets the character offset from the beginning of the file associated with this diagnostic that indicates the end of the problem.

Returns:
offset from beginning of file; NOPOS if and only if getPosition() returns NOPOS

getLineNumber

long getLineNumber()
Gets the line number of the character offset returned by getPosition().

Returns:
a line number or NOPOS if and only if getPosition() returns NOPOS

getColumnNumber

long getColumnNumber()
Gets the column number of the character offset returned by getPosition().

Returns:
a column number or NOPOS if and only if getPosition() returns NOPOS

getCode

String getCode()
Gets a diagnostic code indicating the type of diagnostic. The code is implementation-dependent and might be null.

Returns:
a diagnostic code

getMessage

String getMessage(Locale locale)
Gets a localized message for the given locale. The actual message is implementation-dependent. If the locale is null use the default locale.

Parameters:
locale - a locale; might be null
Returns:
a localized message
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Diagnostic.Kind

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.tools
Enum Diagnostic.Kind

java.lang.Object
    extended by  java.lang.Enum<Diagnostic.Kind>
        extended by  javax.tools.Diagnostic.Kind
All Implemented Interfaces:
Serializable, Comparable<Diagnostic.Kind>
Enclosing interface:
Diagnostic<S>
public static enum Diagnostic.Kind
extends Enum<Diagnostic.Kind>

Kinds of diagnostics, for example, error or warning.

Enum Constant Summary
ERROR
Problem which prevents the tool's normal completion.
MANDATORY_WARNING
Problem similar to a warning, but is mandated by the tool's specification.
NOTE
Informative message from the tool.
OTHER
Diagnostic which does not fit within the other kinds.
WARNING
Problem which does not usually prevent the tool from completing normally.
Method Summary
static Diagnostic.Kind | valueOf(String name) Returns the enum constant of this type with the specified name.
static Diagnostic.Kind[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

ERROR

public static final Diagnostic.Kind ERROR
Problem which prevents the tool's normal completion.

WARNING

public static final Diagnostic.Kind WARNING
Problem which does not usually prevent the tool from completing normally.

MANDATORY_WARNING

public static final Diagnostic.Kind MANDATORY_WARNING
Problem similar to a warning, but is mandated by the tool's specification. For example, the Java™ Language Specification, 3rd Ed. mandates warnings on certain unchecked operations and the use of deprecated methods.

NOTE

public static final Diagnostic.Kind NOTE
Informative message from the tool.

OTHER

public static final Diagnostic.Kind OTHER
Diagnostic which does not fit within the other kinds.

Method Detail

values

public static Diagnostic.Kind[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (Diagnostic.Kind c : Diagnostic.Kind.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static Diagnostic.Kind valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


DiagnosticCollector

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.tools
Class DiagnosticCollector<S>

java.lang.Object
    extended by  javax.tools.DiagnosticCollector<S>
Type Parameters:
S - the type of source objects used by diagnostics received by this object
All Implemented Interfaces:
DiagnosticListener<S>
public final class DiagnosticCollector<S>
extends Object
implements DiagnosticListener<S>

Provides an easy way to collect diagnostics in a list.

Since:
1.6

Constructor Summary
DiagnosticCollector()
Method Summary
List<Diagnostic<? extends S>> | getDiagnostics() Gets a list view of diagnostics collected by this object.
void | report(Diagnostic<? extends S> diagnostic) Invoked when a problem is found.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DiagnosticCollector

public DiagnosticCollector()
Method Detail

report

public void report(Diagnostic<? extends S> diagnostic)
Description copied from interface: DiagnosticListener
Invoked when a problem is found.

Specified by:
report in interface DiagnosticListener<S>
Parameters:
diagnostic - a diagnostic representing the problem that was found

getDiagnostics

public List<Diagnostic<? extends S>> getDiagnostics()
Gets a list view of diagnostics collected by this object.

Returns:
a list view of diagnostics
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DiagnosticListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.tools
Interface DiagnosticListener<S>

Type Parameters:
S - the type of source objects used by diagnostics received by this listener
All Known Implementing Classes:
DiagnosticCollector
public interface DiagnosticListener<S>

Interface for receiving diagnostics from tools.

Since:
1.6

Method Summary
 void report(Diagnostic<? extends S> diagnostic)
Invoked when a problem is found.

Method Detail

report

void report(Diagnostic<? extends S> diagnostic)
Invoked when a problem is found.

Parameters:
diagnostic - a diagnostic representing the problem that was found
Throws:
NullPointerException - if the diagnostic argument is null and the implementation cannot handle null arguments
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FileObject

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.tools
Interface FileObject

All Known Subinterfaces:
JavaFileObject
All Known Implementing Classes:
ForwardingFileObject, ForwardingJavaFileObject, SimpleJavaFileObject
public interface FileObject

File abstraction for tools. In this context, file means an abstraction of regular files and other sources of data. For example, a file object can be used to represent regular files, memory cache, or data in databases.

All methods in this interface might throw a SecurityException if a security exception occurs.

Unless explicitly allowed, all methods in this interface might throw a NullPointerException if given a null argument.

Since:
1.6

Method Summary
boolean | delete() Deletes this file object.
CharSequence | getCharContent(boolean ignoreEncodingErrors) Gets the character content of this file object, if available.
long | getLastModified() Gets the time this file object was last modified.
String | getName() Gets a user-friendly name for this file object.
InputStream | openInputStream() Gets an InputStream for this file object.
OutputStream | openOutputStream() Gets an OutputStream for this file object.
Reader | openReader(boolean ignoreEncodingErrors) Gets a reader for this object.
Writer | openWriter() Gets a Writer for this file object.
URI | toUri() Returns a URI identifying this file object.

Method Detail

toUri

URI toUri()
Returns a URI identifying this file object.

Returns:
a URI

getName

String getName()
Gets a user-friendly name for this file object. The exact value returned is not specified but implementations should take care to preserve names as given by the user. For example, if the user writes the filename "BobsApp\Test.java" on the command line, this method should return "BobsApp\Test.java" whereas the toUri method might return file:///C:/Documents%20and%20Settings/UncleBob/BobsApp/Test.java.

Returns:
a user-friendly name

openInputStream

InputStream openInputStream()
                            throws IOException
Gets an InputStream for this file object.

Returns:
an InputStream
Throws:
IllegalStateException - if this file object was opened for writing and does not support reading
UnsupportedOperationException - if this kind of file object does not support byte access
IOException - if an I/O error occurred

openOutputStream

OutputStream openOutputStream()
                              throws IOException
Gets an OutputStream for this file object.

Returns:
an OutputStream
Throws:
IllegalStateException - if this file object was opened for reading and does not support writing
UnsupportedOperationException - if this kind of file object does not support byte access
IOException - if an I/O error occurred

openReader

Reader openReader(boolean ignoreEncodingErrors)
                  throws IOException
Gets a reader for this object. The returned reader will replace bytes that cannot be decoded with the default translation character. In addition, the reader may report a diagnostic unless ignoreEncodingErrors is true.

Parameters:
ignoreEncodingErrors - ignore encoding errors if true
Returns:
a Reader
Throws:
IllegalStateException - if this file object was opened for writing and does not support reading
UnsupportedOperationException - if this kind of file object does not support character access
IOException - if an I/O error occurred

getCharContent

CharSequence getCharContent(boolean ignoreEncodingErrors)
                            throws IOException
Gets the character content of this file object, if available. Any byte that cannot be decoded will be replaced by the default translation character. In addition, a diagnostic may be reported unless ignoreEncodingErrors is true.

Parameters:
ignoreEncodingErrors - ignore encoding errors if true
Returns:
a CharSequence if available; null otherwise
Throws:
IllegalStateException - if this file object was opened for writing and does not support reading
UnsupportedOperationException - if this kind of file object does not support character access
IOException - if an I/O error occurred

openWriter

Writer openWriter()
                  throws IOException
Gets a Writer for this file object.

Returns:
a Writer
Throws:
IllegalStateException - if this file object was opened for reading and does not support writing
UnsupportedOperationException - if this kind of file object does not support character access
IOException - if an I/O error occurred

getLastModified

long getLastModified()
Gets the time this file object was last modified. The time is measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

Returns:
the time this file object was last modified; or 0 if the file object does not exist, if an I/O error occurred, or if the operation is not supported

delete

boolean delete()
Deletes this file object. In case of errors, returns false.

Returns:
true if and only if this file object is successfully deleted; false otherwise
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ForwardingFileObject

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.tools
Class ForwardingFileObject<F extends FileObject>

java.lang.Object
    extended by  javax.tools.ForwardingFileObject<F>
Type Parameters:
F - the kind of file object forwarded to by this object
All Implemented Interfaces:
FileObject
Direct Known Subclasses:
ForwardingJavaFileObject
public class ForwardingFileObject<F extends FileObject>
extends Object
implements FileObject

Forwards calls to a given file object. Subclasses of this class might override some of these methods and might also provide additional fields and methods.

Since:
1.6

Field Summary
protected  F fileObject
The file object which all methods are delegated to.
Constructor Summary
protected ForwardingFileObject(F fileObject)
Creates a new instance of ForwardingFileObject.
Method Summary
boolean | delete() Deletes this file object.
CharSequence | getCharContent(boolean ignoreEncodingErrors) Gets the character content of this file object, if available.
long | getLastModified() Gets the time this file object was last modified.
String | getName() Gets a user-friendly name for this file object.
InputStream | openInputStream() Gets an InputStream for this file object.
OutputStream | openOutputStream() Gets an OutputStream for this file object.
Reader | openReader(boolean ignoreEncodingErrors) Gets a reader for this object.
Writer | openWriter() Gets a Writer for this file object.
URI | toUri() Returns a URI identifying this file object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

fileObject

protected final F extends FileObject fileObject
The file object which all methods are delegated to.

Constructor Detail

ForwardingFileObject

protected ForwardingFileObject(F fileObject)
Creates a new instance of ForwardingFileObject.

Parameters:
fileObject - delegate to this file object
Method Detail

toUri

public URI toUri()
Description copied from interface: FileObject
Returns a URI identifying this file object.

Specified by:
toUri in interface FileObject
Returns:
a URI

getName

public String getName()
Description copied from interface: FileObject
Gets a user-friendly name for this file object. The exact value returned is not specified but implementations should take care to preserve names as given by the user. For example, if the user writes the filename "BobsApp\Test.java" on the command line, this method should return "BobsApp\Test.java" whereas the toUri method might return file:///C:/Documents%20and%20Settings/UncleBob/BobsApp/Test.java.

Specified by:
getName in interface FileObject
Returns:
a user-friendly name

openInputStream

public InputStream openInputStream()
                            throws IOException
Description copied from interface: FileObject
Gets an InputStream for this file object.

Specified by:
openInputStream in interface FileObject
Returns:
an InputStream
Throws:
IllegalStateException - if this file object was opened for writing and does not support reading
UnsupportedOperationException - if this kind of file object does not support byte access
IOException - if an I/O error occurred

openOutputStream

public OutputStream openOutputStream()
                              throws IOException
Description copied from interface: FileObject
Gets an OutputStream for this file object.

Specified by:
openOutputStream in interface FileObject
Returns:
an OutputStream
Throws:
IllegalStateException - if this file object was opened for reading and does not support writing
UnsupportedOperationException - if this kind of file object does not support byte access
IOException - if an I/O error occurred

openReader

public Reader openReader(boolean ignoreEncodingErrors)
                  throws IOException
Description copied from interface: FileObject
Gets a reader for this object. The returned reader will replace bytes that cannot be decoded with the default translation character. In addition, the reader may report a diagnostic unless ignoreEncodingErrors is true.

Specified by:
openReader in interface FileObject
Parameters:
ignoreEncodingErrors - ignore encoding errors if true
Returns:
a Reader
Throws:
IllegalStateException - if this file object was opened for writing and does not support reading
UnsupportedOperationException - if this kind of file object does not support character access
IOException - if an I/O error occurred

getCharContent

public CharSequence getCharContent(boolean ignoreEncodingErrors)
                            throws IOException
Description copied from interface: FileObject
Gets the character content of this file object, if available. Any byte that cannot be decoded will be replaced by the default translation character. In addition, a diagnostic may be reported unless ignoreEncodingErrors is true.

Specified by:
getCharContent in interface FileObject
Parameters:
ignoreEncodingErrors - ignore encoding errors if true
Returns:
a CharSequence if available; null otherwise
Throws:
IllegalStateException - if this file object was opened for writing and does not support reading
UnsupportedOperationException - if this kind of file object does not support character access
IOException - if an I/O error occurred

openWriter

public Writer openWriter()
                  throws IOException
Description copied from interface: FileObject
Gets a Writer for this file object.

Specified by:
openWriter in interface FileObject
Returns:
a Writer
Throws:
IllegalStateException - if this file object was opened for reading and does not support writing
UnsupportedOperationException - if this kind of file object does not support character access
IOException - if an I/O error occurred

getLastModified

public long getLastModified()
Description copied from interface: FileObject
Gets the time this file object was last modified. The time is measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

Specified by:
getLastModified in interface FileObject
Returns:
the time this file object was last modified; or 0 if the file object does not exist, if an I/O error occurred, or if the operation is not supported

delete

public boolean delete()
Description copied from interface: FileObject
Deletes this file object. In case of errors, returns false.

Specified by:
delete in interface FileObject
Returns:
true if and only if this file object is successfully deleted; false otherwise
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ForwardingJavaFileManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.tools
Class ForwardingJavaFileManager<M extends JavaFileManager>

java.lang.Object
    extended by  javax.tools.ForwardingJavaFileManager<M>
Type Parameters:
M - the kind of file manager forwarded to by this object
All Implemented Interfaces:
Closeable, Flushable, JavaFileManager, OptionChecker
public class ForwardingJavaFileManager<M extends JavaFileManager>
extends Object
implements JavaFileManager

Forwards calls to a given file manager. Subclasses of this class might override some of these methods and might also provide additional fields and methods.

Since:
1.6

Nested Class Summary
Nested classes/interfaces inherited from interface javax.tools.JavaFileManager
JavaFileManager.Location
Field Summary
protected  M fileManager
The file manager which all methods are delegated to.
Constructor Summary
protected ForwardingJavaFileManager(M fileManager)
Creates a new instance of ForwardingJavaFileManager.
Method Summary
void | close() Releases any resources opened by this file manager directly or indirectly.
void | flush() Flushes any resources opened for output by this file manager directly or indirectly.
ClassLoader | getClassLoader(JavaFileManager.Location location) Gets a class loader for loading plug-ins from the given location.
FileObject | getFileForInput(JavaFileManager.Location location, String packageName, String relativeName) Gets a file object for input representing the specified relative name in the specified package in the given location.
FileObject | getFileForOutput(JavaFileManager.Location location, String packageName, String relativeName, FileObject sibling) Gets a file object for output representing the specified relative name in the specified package in the given location.
JavaFileObject | getJavaFileForInput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind) Gets a file object for input representing the specified class of the specified kind in the given location.
JavaFileObject | getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling) Gets a file object for output representing the specified class of the specified kind in the given location.
boolean | handleOption(String current, Iterator<String> remaining) Handles one option.
boolean | hasLocation(JavaFileManager.Location location) Determines if a location is known to this file manager.
String | inferBinaryName(JavaFileManager.Location location, JavaFileObject file) Infers a binary name of a file object based on a location.
boolean | isSameFile(FileObject a, FileObject b) Compares two file objects and return true if they represent the same underlying object.
int | isSupportedOption(String option) Determines if the given option is supported and if so, the number of arguments the option takes.
Iterable<JavaFileObject> | list(JavaFileManager.Location location, String packageName, Set<JavaFileObject.Kind> kinds, boolean recurse) Lists all file objects matching the given criteria in the given location.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

fileManager

protected final M extends JavaFileManager fileManager
The file manager which all methods are delegated to.

Constructor Detail

ForwardingJavaFileManager

protected ForwardingJavaFileManager(M fileManager)
Creates a new instance of ForwardingJavaFileManager.

Parameters:
fileManager - delegate to this file manager
Method Detail

getClassLoader

public ClassLoader getClassLoader(JavaFileManager.Location location)
Description copied from interface: JavaFileManager
Gets a class loader for loading plug-ins from the given location. For example, to load annotation processors, a compiler will request a class loader for the ANNOTATION_PROCESSOR_PATH location.

Specified by:
getClassLoader in interface JavaFileManager
Parameters:
location - a location
Returns:
a class loader for the given location; or null if loading plug-ins from the given location is disabled or if the location is not known
Throws:
SecurityException - if a class loader can not be created in the current security context
IllegalStateException - if JavaFileManager.close() has been called and this file manager cannot be reopened

list

public Iterable<JavaFileObject> list(JavaFileManager.Location location,
                                     String packageName,
                                     Set<JavaFileObject.Kind> kinds,
                                     boolean recurse)
                              throws IOException
Description copied from interface: JavaFileManager
Lists all file objects matching the given criteria in the given location. List file objects in "subpackages" if recurse is true.

Note: even if the given location is unknown to this file manager, it may not return null. Also, an unknown location may not cause an exception.

Specified by:
list in interface JavaFileManager
Parameters:
location - a location
packageName - a package name
kinds - return objects only of these kinds
recurse - if true include "subpackages"
Returns:
an Iterable of file objects matching the given criteria
Throws:
IOException - if an I/O error occurred, or if JavaFileManager.close() has been called and this file manager cannot be reopened
IllegalStateException - if JavaFileManager.close() has been called and this file manager cannot be reopened

inferBinaryName

public String inferBinaryName(JavaFileManager.Location location,
                              JavaFileObject file)
Description copied from interface: JavaFileManager
Infers a binary name of a file object based on a location. The binary name returned might not be a valid JLS binary name.

Specified by:
inferBinaryName in interface JavaFileManager
Parameters:
location - a location
file - a file object
Returns:
a binary name or null the file object is not found in the given location
Throws:
IllegalStateException - if JavaFileManager.close() has been called and this file manager cannot be reopened

isSameFile

public boolean isSameFile(FileObject a,
                          FileObject b)
Description copied from interface: JavaFileManager
Compares two file objects and return true if they represent the same underlying object.

Specified by:
isSameFile in interface JavaFileManager
Parameters:
a - a file object
b - a file object
Returns:
true if the given file objects represent the same underlying object
Throws:
IllegalArgumentException - if either of the arguments were created with another file manager and this file manager does not support foreign file objects

handleOption

public boolean handleOption(String current,
                            Iterator<String> remaining)
Description copied from interface: JavaFileManager
Handles one option. If current is an option to this file manager it will consume any arguments to that option from remaining and return true, otherwise return false.

Specified by:
handleOption in interface JavaFileManager
Parameters:
current - current option
remaining - remaining options
Returns:
true if this option was handled by this file manager, false otherwise
Throws:
IllegalArgumentException - if this option to this file manager is used incorrectly
IllegalStateException - if JavaFileManager.close() has been called and this file manager cannot be reopened

hasLocation

public boolean hasLocation(JavaFileManager.Location location)
Description copied from interface: JavaFileManager
Determines if a location is known to this file manager.

Specified by:
hasLocation in interface JavaFileManager
Parameters:
location - a location
Returns:
true if the location is known

isSupportedOption

public int isSupportedOption(String option)
Description copied from interface: OptionChecker
Determines if the given option is supported and if so, the number of arguments the option takes.

Specified by:
isSupportedOption in interface OptionChecker
Parameters:
option - an option
Returns:
the number of arguments the given option takes or -1 if the option is not supported

getJavaFileForInput

public JavaFileObject getJavaFileForInput(JavaFileManager.Location location,
                                          String className,
                                          JavaFileObject.Kind kind)
                                   throws IOException
Description copied from interface: JavaFileManager
Gets a file object for input representing the specified class of the specified kind in the given location.

Specified by:
getJavaFileForInput in interface JavaFileManager
Parameters:
location - a location
className - the name of a class
kind - the kind of file, must be one of SOURCE or CLASS
Returns:
a file object, might return null if the file does not exist
Throws:
IllegalArgumentException - if the location is not known to this file manager and the file manager does not support unknown locations, or if the kind is not valid
IllegalStateException - if JavaFileManager.close() has been called and this file manager cannot be reopened
IOException - if an I/O error occurred, or if JavaFileManager.close() has been called and this file manager cannot be reopened

getJavaFileForOutput

public JavaFileObject getJavaFileForOutput(JavaFileManager.Location location,
                                           String className,
                                           JavaFileObject.Kind kind,
                                           FileObject sibling)
                                    throws IOException
Description copied from interface: JavaFileManager
Gets a file object for output representing the specified class of the specified kind in the given location.

Optionally, this file manager might consider the sibling as a hint for where to place the output. The exact semantics of this hint is unspecified. Sun's compiler, javac, for example, will place class files in the same directories as originating source files unless a class file output directory is provided. To facilitate this behavior, javac might provide the originating source file as sibling when calling this method.

Specified by:
getJavaFileForOutput in interface JavaFileManager
Parameters:
location - a location
className - the name of a class
kind - the kind of file, must be one of SOURCE or CLASS
sibling - a file object to be used as hint for placement; might be null
Returns:
a file object for output
Throws:
IllegalArgumentException - if sibling is not known to this file manager, or if the location is not known to this file manager and the file manager does not support unknown locations, or if the kind is not valid
IllegalStateException - JavaFileManager.close() has been called and this file manager cannot be reopened
IOException - if an I/O error occurred, or if JavaFileManager.close() has been called and this file manager cannot be reopened

getFileForInput

public FileObject getFileForInput(JavaFileManager.Location location,
                                  String packageName,
                                  String relativeName)
                           throws IOException
Description copied from interface: JavaFileManager
Gets a file object for input representing the specified relative name in the specified package in the given location.

If the returned object represents a source or class file, it must be an instance of JavaFileObject.

Informally, the file object returned by this method is located in the concatenation of the location, package name, and relative name. For example, to locate the properties file "resources/compiler.properties" in the package "com.sun.tools.javac" in the SOURCE_PATH location, this method might be called like so:

getFileForInput(SOURCE_PATH, "com.sun.tools.javac", "resources/compiler.properties");

If the call was executed on Windows, with SOURCE_PATH set to "C:\Documents and Settings\UncleBob\src\share\classes", a valid result would be a file object representing the file "C:\Documents and Settings\UncleBob\src\share\classes\com\sun\tools\javac\resources\compiler.properties".

Specified by:
getFileForInput in interface JavaFileManager
Parameters:
location - a location
packageName - a package name
relativeName - a relative name
Returns:
a file object, might return null if the file does not exist
Throws:
IllegalArgumentException - if the location is not known to this file manager and the file manager does not support unknown locations, or if relativeName is not valid
IllegalStateException - if JavaFileManager.close() has been called and this file manager cannot be reopened
IOException - if an I/O error occurred, or if JavaFileManager.close() has been called and this file manager cannot be reopened

getFileForOutput

public FileObject getFileForOutput(JavaFileManager.Location location,
                                   String packageName,
                                   String relativeName,
                                   FileObject sibling)
                            throws IOException
Description copied from interface: JavaFileManager
Gets a file object for output representing the specified relative name in the specified package in the given location.

Optionally, this file manager might consider the sibling as a hint for where to place the output. The exact semantics of this hint is unspecified. Sun's compiler, javac, for example, will place class files in the same directories as originating source files unless a class file output directory is provided. To facilitate this behavior, javac might provide the originating source file as sibling when calling this method.

If the returned object represents a source or class file, it must be an instance of JavaFileObject.

Informally, the file object returned by this method is located in the concatenation of the location, package name, and relative name or next to the sibling argument. See getFileForInput for an example.

Specified by:
getFileForOutput in interface JavaFileManager
Parameters:
location - a location
packageName - a package name
relativeName - a relative name
sibling - a file object to be used as hint for placement; might be null
Returns:
a file object
Throws:
IllegalArgumentException - if sibling is not known to this file manager, or if the location is not known to this file manager and the file manager does not support unknown locations, or if relativeName is not valid
IllegalStateException - if JavaFileManager.close() has been called and this file manager cannot be reopened
IOException - if an I/O error occurred, or if JavaFileManager.close() has been called and this file manager cannot be reopened

flush

public void flush()
           throws IOException
Description copied from interface: JavaFileManager
Flushes any resources opened for output by this file manager directly or indirectly. Flushing a closed file manager has no effect.

Specified by:
flush in interface Flushable
Specified by:
flush in interface JavaFileManager
Throws:
IOException - if an I/O error occurred
See Also:
JavaFileManager.close()

close

public void close()
           throws IOException
Description copied from interface: JavaFileManager
Releases any resources opened by this file manager directly or indirectly. This might render this file manager useless and the effect of subsequent calls to methods on this object or any objects obtained through this object is undefined unless explicitly allowed. However, closing a file manager which has already been closed has no effect.

Specified by:
close in interface Closeable
Specified by:
close in interface JavaFileManager
Throws:
IOException - if an I/O error occurred
See Also:
JavaFileManager.flush()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ForwardingJavaFileObject

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.tools
Class ForwardingJavaFileObject<F extends JavaFileObject>

java.lang.Object
    extended by  javax.tools.ForwardingFileObject<F>
        extended by  javax.tools.ForwardingJavaFileObject<F>
Type Parameters:
F - the kind of file object forwarded to by this object
All Implemented Interfaces:
FileObject, JavaFileObject
public class ForwardingJavaFileObject<F extends JavaFileObject>
extends ForwardingFileObject<F>
implements JavaFileObject

Forwards calls to a given file object. Subclasses of this class might override some of these methods and might also provide additional fields and methods.

Since:
1.6

Nested Class Summary
Nested classes/interfaces inherited from interface javax.tools.JavaFileObject
JavaFileObject.Kind
Field Summary
Fields inherited from class javax.tools.ForwardingFileObject
fileObject
Constructor Summary
protected ForwardingJavaFileObject(F fileObject)
Creates a new instance of ForwardingJavaFileObject.
Method Summary
Modifier | getAccessLevel() Provides a hint about the access level of the class represented by this file object.
JavaFileObject.Kind | getKind() Gets the kind of this file object.
NestingKind | getNestingKind() Provides a hint about the nesting level of the class represented by this file object.
boolean | isNameCompatible(String simpleName, JavaFileObject.Kind kind) Checks if this file object is compatible with the specified simple name and kind.
Methods inherited from class javax.tools.ForwardingFileObject
delete, getCharContent, getLastModified, getName, openInputStream, openOutputStream, openReader, openWriter, toUri
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.tools.FileObject
delete, getCharContent, getLastModified, getName, openInputStream, openOutputStream, openReader, openWriter, toUri

Constructor Detail

ForwardingJavaFileObject

protected ForwardingJavaFileObject(F fileObject)
Creates a new instance of ForwardingJavaFileObject.

Parameters:
fileObject - delegate to this file object
Method Detail

getKind

public JavaFileObject.Kind getKind()
Description copied from interface: JavaFileObject
Gets the kind of this file object.

Specified by:
getKind in interface JavaFileObject
Returns:
the kind

isNameCompatible

public boolean isNameCompatible(String simpleName,
                                JavaFileObject.Kind kind)
Description copied from interface: JavaFileObject
Checks if this file object is compatible with the specified simple name and kind. A simple name is a single identifier (not qualified) as defined in the Java Language Specification 3rd ed., section 6.2 "Names and Identifiers".

Specified by:
isNameCompatible in interface JavaFileObject
Parameters:
simpleName - a simple name of a class
kind - a kind
Returns:
true if this file object is compatible; false otherwise

getNestingKind

public NestingKind getNestingKind()
Description copied from interface: JavaFileObject
Provides a hint about the nesting level of the class represented by this file object. This method may return NestingKind.MEMBER to mean NestingKind.LOCAL or NestingKind.ANONYMOUS. If the nesting level is not known or this file object does not represent a class file this method returns null.

Specified by:
getNestingKind in interface JavaFileObject
Returns:
the nesting kind, or null if the nesting kind is not known

getAccessLevel

public Modifier getAccessLevel()
Description copied from interface: JavaFileObject
Provides a hint about the access level of the class represented by this file object. If the access level is not known or if this file object does not represent a class file this method returns null.

Specified by:
getAccessLevel in interface JavaFileObject
Returns:
the access level
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JavaCompiler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.tools
Interface JavaCompiler

All Superinterfaces:
OptionChecker, Tool
public interface JavaCompiler
extends Tool, OptionChecker

Interface to invoke Java™ programming language compilers from programs.

The compiler might generate diagnostics during compilation (for example, error messages). If a diagnostic listener is provided, the diagnostics will be supplied to the listener. If no listener is provided, the diagnostics will be formatted in an unspecified format and written to the default output, which is System.err unless otherwise specified. Even if a diagnostic listener is supplied, some diagnostics might not fit in a Diagnostic and will be written to the default output.

A compiler tool has an associated standard file manager, which is the file manager that is native to the tool (or built-in). The standard file manager can be obtained by calling getStandardFileManager.

A compiler tool must function with any file manager as long as any additional requirements as detailed in the methods below are met. If no file manager is provided, the compiler tool will use a standard file manager such as the one returned by getStandardFileManager.

An instance implementing this interface must conform to the Java Language Specification and generate class files conforming to the Java Virtual Machine specification. The versions of these specifications are defined in the Tool interface. Additionally, an instance of this interface supporting SourceVersion.RELEASE_6 or higher must also support annotation processing.

The compiler relies on two services: diagnostic listener and file manager. Although most classes and interfaces in this package defines an API for compilers (and tools in general) the interfaces DiagnosticListener, JavaFileManager, FileObject, and JavaFileObject are not intended to be used in applications. Instead these interfaces are intended to be implemented and used to provide customized services for a compiler and thus defines an SPI for compilers.

There are a number of classes and interfaces in this package which are designed to ease the implementation of the SPI to customize the behavior of a compiler:

StandardJavaFileManager
Every compiler which implements this interface provides a standard file manager for operating on regular files. The StandardJavaFileManager interface defines additional methods for creating file objects from regular files.

The standard file manager serves two purposes:

  • basic building block for customizing how a compiler reads and writes files
  • sharing between multiple compilation tasks

Reusing a file manager can potentially reduce overhead of scanning the file system and reading jar files. Although there might be no reduction in overhead, a standard file manager must work with multiple sequential compilations making the following example a recommended coding pattern:

       Files[] files1 = ... ; // input for first compilation task
       Files[] files2 = ... ; // input for second compilation task

       JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
       StandardJavaFileManager fileManager = compiler.getStandardFileManager(null, null, null);

       Iterable<? extends JavaFileObject> compilationUnits1 =
           fileManager.getJavaFileObjectsFromFiles(Arrays.asList(files1));
       compiler.getTask(null, fileManager, null, null, null, compilationUnits1).call();

       Iterable<? extends JavaFileObject> compilationUnits2 =
           fileManager.getJavaFileObjects(files2); // use alternative method
       // reuse the same file manager to allow caching of jar files
       compiler.getTask(null, fileManager, null, null, null, compilationUnits2).call();

       fileManager.close();
DiagnosticCollector
Used to collect diagnostics in a list, for example:
       Iterable<? extends JavaFileObject> compilationUnits = ...;
       JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
       DiagnosticCollector<JavaFileObject> diagnostics = new DiagnosticCollector<JavaFileObject>();
       StandardJavaFileManager fileManager = compiler.getStandardFileManager(diagnostics, null, null);
       compiler.getTask(null, fileManager, diagnostics, null, null, compilationUnits).call();

       for (Diagnostic diagnostic : diagnostics.getDiagnostics())
           System.out.format("Error on line %d in %d%n",
                             diagnostic.getLineNumber()
                             diagnostic.getSource().toUri());

       fileManager.close();
ForwardingJavaFileManager, ForwardingFileObject, and ForwardingJavaFileObject
Subclassing is not available for overriding the behavior of a standard file manager as it is created by calling a method on a compiler, not by invoking a constructor. Instead forwarding (or delegation) should be used. These classes makes it easy to forward most calls to a given file manager or file object while allowing customizing behavior. For example, consider how to log all calls to JavaFileManager.flush():
       final Logger logger = ...;
       Iterable<? extends JavaFileObject> compilationUnits = ...;
       JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
       StandardJavaFileManager stdFileManager = compiler.getStandardFileManager(null, null, null);
       JavaFileManager fileManager = new ForwardingJavaFileManager(stdFileManager) {
           public void flush() {
               logger.entering(StandardJavaFileManager.class.getName(), "flush");
               super.flush();
               logger.exiting(StandardJavaFileManager.class.getName(), "flush");
           }
       };
       compiler.getTask(null, fileManager, null, null, null, compilationUnits).call();
SimpleJavaFileObject
This class provides a basic file object implementation which can be used as building block for creating file objects. For example, here is how to define a file object which represent source code stored in a string:
       /**
        * A file object used to represent source coming from a string.
        */
       public class JavaSourceFromString extends SimpleJavaFileObject {
           /**
            * The source code of this "file".
            */
           final String code;

           /**
            * Constructs a new JavaSourceFromString.
            * @param name the name of the compilation unit represented by this file object
            * @param code the source code for the compilation unit represented by this file object
            */
           JavaSourceFromString(String name, String code) {
               super(URI.create("string:///" + name.replace('.','/') + Kind.SOURCE.extension),
                     Kind.SOURCE);
               this.code = code;
           }

           @Override
           public CharSequence getCharContent(boolean ignoreEncodingErrors) {
               return code;
           }
       }

Since:
1.6
See Also:
DiagnosticListener, Diagnostic, JavaFileManager

Nested Class Summary
static interface JavaCompiler.CompilationTask
Interface representing a future for a compilation task.
Method Summary
StandardJavaFileManager | getStandardFileManager(DiagnosticListener<? super JavaFileObject> diagnosticListener, Locale locale, Charset charset) Gets a new instance of the standard file manager implementation for this tool.
JavaCompiler.CompilationTask | getTask(Writer out, JavaFileManager fileManager, DiagnosticListener<? super JavaFileObject> diagnosticListener, Iterable<String> options, Iterable<String> classes, Iterable<? extends JavaFileObject> compilationUnits) Creates a future for a compilation task with the given components and arguments.
Methods inherited from interface javax.tools.Tool
getSourceVersions, run
Methods inherited from interface javax.tools.OptionChecker
isSupportedOption

Method Detail

getTask

JavaCompiler.CompilationTask getTask(Writer out,
                                     JavaFileManager fileManager,
                                     DiagnosticListener<? super JavaFileObject> diagnosticListener,
                                     Iterable<String> options,
                                     Iterable<String> classes,
                                     Iterable<? extends JavaFileObject> compilationUnits)
Creates a future for a compilation task with the given components and arguments. The compilation might not have completed as described in the CompilationTask interface.

If a file manager is provided, it must be able to handle all locations defined in StandardLocation.

Parameters:
out - a Writer for additional output from the compiler; use System.err if null
fileManager - a file manager; if null use the compiler's standard filemanager
diagnosticListener - a diagnostic listener; if null use the compiler's default method for reporting diagnostics
options - compiler options, null means no options
classes - class names (for annotation processing), null means no class names
compilationUnits - the compilation units to compile, null means no compilation units
Returns:
an object representing the compilation
Throws:
RuntimeException - if an unrecoverable error occurred in a user supplied component. The cause will be the error in user code.
IllegalArgumentException - if any of the given compilation units are of other kind than source

getStandardFileManager

StandardJavaFileManager getStandardFileManager(DiagnosticListener<? super JavaFileObject> diagnosticListener,
                                               Locale locale,
                                               Charset charset)
Gets a new instance of the standard file manager implementation for this tool. The file manager will use the given diagnostic listener for producing any non-fatal diagnostics. Fatal errors will be signalled with the appropriate exceptions.

The standard file manager will be automatically reopened if it is accessed after calls to flush or close. The standard file manager must be usable with other tools.

Parameters:
diagnosticListener - a diagnostic listener for non-fatal diagnostics; if null use the compiler's default method for reporting diagnostics
locale - the locale to apply when formatting diagnostics; null means the default locale.
charset - the character set used for decoding bytes; if null use the platform default
Returns:
the standard file manager
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JavaCompiler.CompilationTask

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.tools
Interface JavaCompiler.CompilationTask

All Superinterfaces:
Callable<Boolean>
Enclosing interface:
JavaCompiler
public static interface JavaCompiler.CompilationTask
extends Callable<Boolean>

Interface representing a future for a compilation task. The compilation task has not yet started. To start the task, call the call method.

Before calling the call method, additional aspects of the task can be configured, for example, by calling the setProcessors method.

Method Summary
Boolean | call() Performs this compilation task.
void | setLocale(Locale locale) Set the locale to be applied when formatting diagnostics and other localized data.
void | setProcessors(Iterable<? extends Processor> processors) Sets processors (for annotation processing).

Method Detail

setProcessors

void setProcessors(Iterable<? extends Processor> processors)
Sets processors (for annotation processing). This will bypass the normal discovery mechanism.

Parameters:
processors - processors (for annotation processing)
Throws:
IllegalStateException - if the task has started

setLocale

void setLocale(Locale locale)
Set the locale to be applied when formatting diagnostics and other localized data.

Parameters:
locale - the locale to apply; null means apply no locale
Throws:
IllegalStateException - if the task has started

call

Boolean call()
Performs this compilation task. The compilation may only be performed once. Subsequent calls to this method throw IllegalStateException.

Specified by:
call in interface Callable<Boolean>
Returns:
true if and only all the files compiled without errors; false otherwise
Throws:
RuntimeException - if an unrecoverable error occurred in a user-supplied component. The cause will be the error in user code.
IllegalStateException - if called more than once
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JavaFileManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.tools
Interface JavaFileManager

All Superinterfaces:
Closeable, Flushable, OptionChecker
All Known Subinterfaces:
StandardJavaFileManager
All Known Implementing Classes:
ForwardingJavaFileManager
public interface JavaFileManager
extends Closeable, Flushable, OptionChecker

File manager for tools operating on Java™ programming language source and class files. In this context, file means an abstraction of regular files and other sources of data.

When constructing new JavaFileObjects, the file manager must determine where to create them. For example, if a file manager manages regular files on a file system, it would most likely have a current/working directory to use as default location when creating or finding files. A number of hints can be provided to a file manager as to where to create files. Any file manager might choose to ignore these hints.

Some methods in this interface use class names. Such class names must be given in the Java Virtual Machine internal form of fully qualified class and interface names. For convenience '.' and '/' are interchangeable. The internal form is defined in chapter four of the Java Virtual Machine Specification.

Discussion: this means that the names "java/lang.package-info", "java/lang/package-info", "java.lang.package-info", are valid and equivalent. Compare to binary name as defined in the Java Language Specification (JLS) section 13.1 "The Form of a Binary".

The case of names is significant. All names should be treated as case-sensitive. For example, some file systems have case-insensitive, case-aware file names. File objects representing such files should take care to preserve case by using File.getCanonicalFile() or similar means. If the system is not case-aware, file objects must use other means to preserve case.

Relative names: some methods in this interface use relative names. A relative name is a non-null, non-empty sequence of path segments separated by '/'. '.' or '..' are invalid path segments. A valid relative name must match the "path-rootless" rule of RFC 3986, section 3.3. Informally, this should be true:

  URI.create(relativeName).normalize().getPath().equals(relativeName)

All methods in this interface might throw a SecurityException.

An object of this interface is not required to support multi-threaded access, that is, be synchronized. However, it must support concurrent access to different file objects created by this object.

Implementation note: a consequence of this requirement is that a trivial implementation of output to a JarOutputStream is not a sufficient implementation. That is, rather than creating a JavaFileObject that returns the JarOutputStream directly, the contents must be cached until closed and then written to the JarOutputStream.

Unless explicitly allowed, all methods in this interface might throw a NullPointerException if given a null argument.

Since:
1.6
See Also:
JavaFileObject, FileObject

Nested Class Summary
static interface JavaFileManager.Location
Interface for locations of file objects.
Method Summary
void | close() Releases any resources opened by this file manager directly or indirectly.
void | flush() Flushes any resources opened for output by this file manager directly or indirectly.
ClassLoader | getClassLoader(JavaFileManager.Location location) Gets a class loader for loading plug-ins from the given location.
FileObject | getFileForInput(JavaFileManager.Location location, String packageName, String relativeName) Gets a file object for input representing the specified relative name in the specified package in the given location.
FileObject | getFileForOutput(JavaFileManager.Location location, String packageName, String relativeName, FileObject sibling) Gets a file object for output representing the specified relative name in the specified package in the given location.
JavaFileObject | getJavaFileForInput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind) Gets a file object for input representing the specified class of the specified kind in the given location.
JavaFileObject | getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling) Gets a file object for output representing the specified class of the specified kind in the given location.
boolean | handleOption(String current, Iterator<String> remaining) Handles one option.
boolean | hasLocation(JavaFileManager.Location location) Determines if a location is known to this file manager.
String | inferBinaryName(JavaFileManager.Location location, JavaFileObject file) Infers a binary name of a file object based on a location.
boolean | isSameFile(FileObject a, FileObject b) Compares two file objects and return true if they represent the same underlying object.
Iterable<JavaFileObject> | list(JavaFileManager.Location location, String packageName, Set<JavaFileObject.Kind> kinds, boolean recurse) Lists all file objects matching the given criteria in the given location.
Methods inherited from interface javax.tools.OptionChecker
isSupportedOption

Method Detail

getClassLoader

ClassLoader getClassLoader(JavaFileManager.Location location)
Gets a class loader for loading plug-ins from the given location. For example, to load annotation processors, a compiler will request a class loader for the ANNOTATION_PROCESSOR_PATH location.

Parameters:
location - a location
Returns:
a class loader for the given location; or null if loading plug-ins from the given location is disabled or if the location is not known
Throws:
SecurityException - if a class loader can not be created in the current security context
IllegalStateException - if close() has been called and this file manager cannot be reopened

list

Iterable<JavaFileObject> list(JavaFileManager.Location location,
                              String packageName,
                              Set<JavaFileObject.Kind> kinds,
                              boolean recurse)
                              throws IOException
Lists all file objects matching the given criteria in the given location. List file objects in "subpackages" if recurse is true.

Note: even if the given location is unknown to this file manager, it may not return null. Also, an unknown location may not cause an exception.

Parameters:
location - a location
packageName - a package name
kinds - return objects only of these kinds
recurse - if true include "subpackages"
Returns:
an Iterable of file objects matching the given criteria
Throws:
IOException - if an I/O error occurred, or if close() has been called and this file manager cannot be reopened
IllegalStateException - if close() has been called and this file manager cannot be reopened

inferBinaryName

String inferBinaryName(JavaFileManager.Location location,
                       JavaFileObject file)
Infers a binary name of a file object based on a location. The binary name returned might not be a valid JLS binary name.

Parameters:
location - a location
file - a file object
Returns:
a binary name or null the file object is not found in the given location
Throws:
IllegalStateException - if close() has been called and this file manager cannot be reopened

isSameFile

boolean isSameFile(FileObject a,
                   FileObject b)
Compares two file objects and return true if they represent the same underlying object.

Parameters:
a - a file object
b - a file object
Returns:
true if the given file objects represent the same underlying object
Throws:
IllegalArgumentException - if either of the arguments were created with another file manager and this file manager does not support foreign file objects

handleOption

boolean handleOption(String current,
                     Iterator<String> remaining)
Handles one option. If current is an option to this file manager it will consume any arguments to that option from remaining and return true, otherwise return false.

Parameters:
current - current option
remaining - remaining options
Returns:
true if this option was handled by this file manager, false otherwise
Throws:
IllegalArgumentException - if this option to this file manager is used incorrectly
IllegalStateException - if close() has been called and this file manager cannot be reopened

hasLocation

boolean hasLocation(JavaFileManager.Location location)
Determines if a location is known to this file manager.

Parameters:
location - a location
Returns:
true if the location is known

getJavaFileForInput

JavaFileObject getJavaFileForInput(JavaFileManager.Location location,
                                   String className,
                                   JavaFileObject.Kind kind)
                                   throws IOException
Gets a file object for input representing the specified class of the specified kind in the given location.

Parameters:
location - a location
className - the name of a class
kind - the kind of file, must be one of SOURCE or CLASS
Returns:
a file object, might return null if the file does not exist
Throws:
IllegalArgumentException - if the location is not known to this file manager and the file manager does not support unknown locations, or if the kind is not valid
IOException - if an I/O error occurred, or if close() has been called and this file manager cannot be reopened
IllegalStateException - if close() has been called and this file manager cannot be reopened

getJavaFileForOutput

JavaFileObject getJavaFileForOutput(JavaFileManager.Location location,
                                    String className,
                                    JavaFileObject.Kind kind,
                                    FileObject sibling)
                                    throws IOException
Gets a file object for output representing the specified class of the specified kind in the given location.

Optionally, this file manager might consider the sibling as a hint for where to place the output. The exact semantics of this hint is unspecified. Sun's compiler, javac, for example, will place class files in the same directories as originating source files unless a class file output directory is provided. To facilitate this behavior, javac might provide the originating source file as sibling when calling this method.

Parameters:
location - a location
className - the name of a class
kind - the kind of file, must be one of SOURCE or CLASS
sibling - a file object to be used as hint for placement; might be null
Returns:
a file object for output
Throws:
IllegalArgumentException - if sibling is not known to this file manager, or if the location is not known to this file manager and the file manager does not support unknown locations, or if the kind is not valid
IOException - if an I/O error occurred, or if close() has been called and this file manager cannot be reopened
IllegalStateException - close() has been called and this file manager cannot be reopened

getFileForInput

FileObject getFileForInput(JavaFileManager.Location location,
                           String packageName,
                           String relativeName)
                           throws IOException
Gets a file object for input representing the specified relative name in the specified package in the given location.

If the returned object represents a source or class file, it must be an instance of JavaFileObject.

Informally, the file object returned by this method is located in the concatenation of the location, package name, and relative name. For example, to locate the properties file "resources/compiler.properties" in the package "com.sun.tools.javac" in the SOURCE_PATH location, this method might be called like so:

getFileForInput(SOURCE_PATH, "com.sun.tools.javac", "resources/compiler.properties");

If the call was executed on Windows, with SOURCE_PATH set to "C:\Documents and Settings\UncleBob\src\share\classes", a valid result would be a file object representing the file "C:\Documents and Settings\UncleBob\src\share\classes\com\sun\tools\javac\resources\compiler.properties".

Parameters:
location - a location
packageName - a package name
relativeName - a relative name
Returns:
a file object, might return null if the file does not exist
Throws:
IllegalArgumentException - if the location is not known to this file manager and the file manager does not support unknown locations, or if relativeName is not valid
IOException - if an I/O error occurred, or if close() has been called and this file manager cannot be reopened
IllegalStateException - if close() has been called and this file manager cannot be reopened

getFileForOutput

FileObject getFileForOutput(JavaFileManager.Location location,
                            String packageName,
                            String relativeName,
                            FileObject sibling)
                            throws IOException
Gets a file object for output representing the specified relative name in the specified package in the given location.

Optionally, this file manager might consider the sibling as a hint for where to place the output. The exact semantics of this hint is unspecified. Sun's compiler, javac, for example, will place class files in the same directories as originating source files unless a class file output directory is provided. To facilitate this behavior, javac might provide the originating source file as sibling when calling this method.

If the returned object represents a source or class file, it must be an instance of JavaFileObject.

Informally, the file object returned by this method is located in the concatenation of the location, package name, and relative name or next to the sibling argument. See getFileForInput for an example.

Parameters:
location - a location
packageName - a package name
relativeName - a relative name
sibling - a file object to be used as hint for placement; might be null
Returns:
a file object
Throws:
IllegalArgumentException - if sibling is not known to this file manager, or if the location is not known to this file manager and the file manager does not support unknown locations, or if relativeName is not valid
IOException - if an I/O error occurred, or if close() has been called and this file manager cannot be reopened
IllegalStateException - if close() has been called and this file manager cannot be reopened

flush

void flush()
           throws IOException
Flushes any resources opened for output by this file manager directly or indirectly. Flushing a closed file manager has no effect.

Specified by:
flush in interface Flushable
Throws:
IOException - if an I/O error occurred
See Also:
close()

close

void close()
           throws IOException
Releases any resources opened by this file manager directly or indirectly. This might render this file manager useless and the effect of subsequent calls to methods on this object or any objects obtained through this object is undefined unless explicitly allowed. However, closing a file manager which has already been closed has no effect.

Specified by:
close in interface Closeable
Throws:
IOException - if an I/O error occurred
See Also:
flush()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JavaFileManager.Location

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.tools
Interface JavaFileManager.Location

All Known Implementing Classes:
StandardLocation
Enclosing interface:
JavaFileManager
public static interface JavaFileManager.Location

Interface for locations of file objects. Used by file managers to determine where to place or search for file objects.

Method Summary
String | getName() Gets the name of this location.
boolean | isOutputLocation() Determines if this is an output location.

Method Detail

getName

String getName()
Gets the name of this location.

Returns:
a name

isOutputLocation

boolean isOutputLocation()
Determines if this is an output location. An output location is a location that is conventionally used for output.

Returns:
true if this is an output location, false otherwise
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JavaFileObject

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.tools
Interface JavaFileObject

All Superinterfaces:
FileObject
All Known Implementing Classes:
ForwardingJavaFileObject, SimpleJavaFileObject
public interface JavaFileObject
extends FileObject

File abstraction for tools operating on Java™ programming language source and class files.

All methods in this interface might throw a SecurityException if a security exception occurs.

Unless explicitly allowed, all methods in this interface might throw a NullPointerException if given a null argument.

Since:
1.6
See Also:
JavaFileManager

Nested Class Summary
static class JavaFileObject.Kind
Kinds of JavaFileObjects.
Method Summary
Modifier | getAccessLevel() Provides a hint about the access level of the class represented by this file object.
JavaFileObject.Kind | getKind() Gets the kind of this file object.
NestingKind | getNestingKind() Provides a hint about the nesting level of the class represented by this file object.
boolean | isNameCompatible(String simpleName, JavaFileObject.Kind kind) Checks if this file object is compatible with the specified simple name and kind.
Methods inherited from interface javax.tools.FileObject
delete, getCharContent, getLastModified, getName, openInputStream, openOutputStream, openReader, openWriter, toUri

Method Detail

getKind

JavaFileObject.Kind getKind()
Gets the kind of this file object.

Returns:
the kind

isNameCompatible

boolean isNameCompatible(String simpleName,
                         JavaFileObject.Kind kind)
Checks if this file object is compatible with the specified simple name and kind. A simple name is a single identifier (not qualified) as defined in the Java Language Specification 3rd ed., section 6.2 "Names and Identifiers".

Parameters:
simpleName - a simple name of a class
kind - a kind
Returns:
true if this file object is compatible; false otherwise

getNestingKind

NestingKind getNestingKind()
Provides a hint about the nesting level of the class represented by this file object. This method may return NestingKind.MEMBER to mean NestingKind.LOCAL or NestingKind.ANONYMOUS. If the nesting level is not known or this file object does not represent a class file this method returns null.

Returns:
the nesting kind, or null if the nesting kind is not known

getAccessLevel

Modifier getAccessLevel()
Provides a hint about the access level of the class represented by this file object. If the access level is not known or if this file object does not represent a class file this method returns null.

Returns:
the access level
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JavaFileObject.Kind

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.tools
Enum JavaFileObject.Kind

java.lang.Object
    extended by  java.lang.Enum<JavaFileObject.Kind>
        extended by  javax.tools.JavaFileObject.Kind
All Implemented Interfaces:
Serializable, Comparable<JavaFileObject.Kind>
Enclosing interface:
JavaFileObject
public static enum JavaFileObject.Kind
extends Enum<JavaFileObject.Kind>

Kinds of JavaFileObjects.

Enum Constant Summary
CLASS
Class files for the Java Virtual Machine.
HTML
HTML files.
OTHER
Any other kind.
SOURCE
Source files written in the Java programming language.
Field Summary
 String extension
The extension which (by convention) is normally used for this kind of file object.
Method Summary
static JavaFileObject.Kind | valueOf(String name) Returns the enum constant of this type with the specified name.
static JavaFileObject.Kind[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

SOURCE

public static final JavaFileObject.Kind SOURCE
Source files written in the Java programming language. For example, regular files ending with .java.

CLASS

public static final JavaFileObject.Kind CLASS
Class files for the Java Virtual Machine. For example, regular files ending with .class.

HTML

public static final JavaFileObject.Kind HTML
HTML files. For example, regular files ending with .html.

OTHER

public static final JavaFileObject.Kind OTHER
Any other kind.

Field Detail

extension

public final String extension
The extension which (by convention) is normally used for this kind of file object. If no convention exists, the empty string ("") is used.

Method Detail

values

public static JavaFileObject.Kind[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (JavaFileObject.Kind c : JavaFileObject.Kind.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static JavaFileObject.Kind valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


OptionChecker

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.tools
Interface OptionChecker

All Known Subinterfaces:
JavaCompiler, JavaFileManager, StandardJavaFileManager
All Known Implementing Classes:
ForwardingJavaFileManager
public interface OptionChecker

Interface for recognizing options.

Since:
1.6

Method Summary
 int isSupportedOption(String option)
Determines if the given option is supported and if so, the number of arguments the option takes.

Method Detail

isSupportedOption

int isSupportedOption(String option)
Determines if the given option is supported and if so, the number of arguments the option takes.

Parameters:
option - an option
Returns:
the number of arguments the given option takes or -1 if the option is not supported
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SimpleJavaFileObject

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.tools
Class SimpleJavaFileObject

java.lang.Object
    extended by  javax.tools.SimpleJavaFileObject
All Implemented Interfaces:
FileObject, JavaFileObject
public class SimpleJavaFileObject
extends Object
implements JavaFileObject

Provides simple implementations for most methods in JavaFileObject. This class is designed to be subclassed and used as a basis for JavaFileObject implementations. Subclasses can override the implementation and specification of any method of this class as long as the general contract of JavaFileObject is obeyed.

Since:
1.6

Nested Class Summary
Nested classes/interfaces inherited from interface javax.tools.JavaFileObject
JavaFileObject.Kind
Field Summary
protected JavaFileObject.Kind | kind The kind of this file object.
protected URI | uri A URI for this file object.
Constructor Summary
protected SimpleJavaFileObject(URI uri, JavaFileObject.Kind kind)
Construct a SimpleJavaFileObject of the given kind and with the given URI.
Method Summary
boolean | delete() This implementation does nothing.
Modifier | getAccessLevel() This implementation returns null.
CharSequence | getCharContent(boolean ignoreEncodingErrors) This implementation always throws UnsupportedOperationException.
JavaFileObject.Kind | getKind() Gets the kind of this file object.
long | getLastModified() This implementation returns 0L.
String | getName() Gets a user-friendly name for this file object.
NestingKind | getNestingKind() This implementation returns null.
boolean | isNameCompatible(String simpleName, JavaFileObject.Kind kind) This implementation compares the path of its URI to the given simple name.
InputStream | openInputStream() This implementation always throws UnsupportedOperationException.
OutputStream | openOutputStream() This implementation always throws UnsupportedOperationException.
Reader | openReader(boolean ignoreEncodingErrors) Wraps the result of getCharContent(boolean) in a Reader.
Writer | openWriter() Wraps the result of openOutputStream in a Writer.
String | toString() Returns a string representation of the object.
URI | toUri() Returns a URI identifying this file object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

uri

protected final URI uri
A URI for this file object.

kind

protected final JavaFileObject.Kind kind
The kind of this file object.

Constructor Detail

SimpleJavaFileObject

protected SimpleJavaFileObject(URI uri,
                               JavaFileObject.Kind kind)
Construct a SimpleJavaFileObject of the given kind and with the given URI.

Parameters:
uri - the URI for this file object
kind - the kind of this file object
Method Detail

toUri

public URI toUri()
Description copied from interface: FileObject
Returns a URI identifying this file object.

Specified by:
toUri in interface FileObject
Returns:
a URI

getName

public String getName()
Description copied from interface: FileObject
Gets a user-friendly name for this file object. The exact value returned is not specified but implementations should take care to preserve names as given by the user. For example, if the user writes the filename "BobsApp\Test.java" on the command line, this method should return "BobsApp\Test.java" whereas the toUri method might return file:///C:/Documents%20and%20Settings/UncleBob/BobsApp/Test.java.

Specified by:
getName in interface FileObject
Returns:
a user-friendly name

openInputStream

public InputStream openInputStream()
                            throws IOException
This implementation always throws UnsupportedOperationException. Subclasses can change this behavior as long as the contract of FileObject is obeyed.

Specified by:
openInputStream in interface FileObject
Returns:
an InputStream
Throws:
IOException - if an I/O error occurred

openOutputStream

public OutputStream openOutputStream()
                              throws IOException
This implementation always throws UnsupportedOperationException. Subclasses can change this behavior as long as the contract of FileObject is obeyed.

Specified by:
openOutputStream in interface FileObject
Returns:
an OutputStream
Throws:
IOException - if an I/O error occurred

openReader

public Reader openReader(boolean ignoreEncodingErrors)
                  throws IOException
Wraps the result of getCharContent(boolean) in a Reader. Subclasses can change this behavior as long as the contract of FileObject is obeyed.

Specified by:
openReader in interface FileObject
Parameters:
ignoreEncodingErrors - ignore encoding errors if true
Returns:
a Reader wrapping the result of getCharContent
Throws:
IllegalStateException - if this file object was opened for writing and does not support reading
UnsupportedOperationException - if this kind of file object does not support character access
IOException - if an I/O error occurred

getCharContent

public CharSequence getCharContent(boolean ignoreEncodingErrors)
                            throws IOException
This implementation always throws UnsupportedOperationException. Subclasses can change this behavior as long as the contract of FileObject is obeyed.

Specified by:
getCharContent in interface FileObject
Parameters:
ignoreEncodingErrors - ignore encoding errors if true
Returns:
a CharSequence if available; null otherwise
Throws:
IOException - if an I/O error occurred

openWriter

public Writer openWriter()
                  throws IOException
Wraps the result of openOutputStream in a Writer. Subclasses can change this behavior as long as the contract of FileObject is obeyed.

Specified by:
openWriter in interface FileObject
Returns:
a Writer wrapping the result of openOutputStream
Throws:
IllegalStateException - if this file object was opened for reading and does not support writing
UnsupportedOperationException - if this kind of file object does not support character access
IOException - if an I/O error occurred

getLastModified

public long getLastModified()
This implementation returns 0L. Subclasses can change this behavior as long as the contract of FileObject is obeyed.

Specified by:
getLastModified in interface FileObject
Returns:
0L

delete

public boolean delete()
This implementation does nothing. Subclasses can change this behavior as long as the contract of FileObject is obeyed.

Specified by:
delete in interface FileObject
Returns:
false

getKind

public JavaFileObject.Kind getKind()
Description copied from interface: JavaFileObject
Gets the kind of this file object.

Specified by:
getKind in interface JavaFileObject
Returns:
this.kind

isNameCompatible

public boolean isNameCompatible(String simpleName,
                                JavaFileObject.Kind kind)
This implementation compares the path of its URI to the given simple name. This method returns true if the given kind is equal to the kind of this object, and if the path is equal to simpleName + kind.extension or if it ends with "/" + simpleName + kind.extension.

This method calls getKind() and toUri() and does not access the fields uri and kind directly.

Subclasses can change this behavior as long as the contract of JavaFileObject is obeyed.

Specified by:
isNameCompatible in interface JavaFileObject
Parameters:
simpleName - a simple name of a class
kind - a kind
Returns:
true if this file object is compatible; false otherwise

getNestingKind

public NestingKind getNestingKind()
This implementation returns null. Subclasses can change this behavior as long as the contract of JavaFileObject is obeyed.

Specified by:
getNestingKind in interface JavaFileObject
Returns:
the nesting kind, or null if the nesting kind is not known

getAccessLevel

public Modifier getAccessLevel()
This implementation returns null. Subclasses can change this behavior as long as the contract of JavaFileObject is obeyed.

Specified by:
getAccessLevel in interface JavaFileObject
Returns:
the access level

toString

public String toString()
Description copied from class: Object
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())

Overrides:
toString in class Object
Returns:
a string representation of the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StandardJavaFileManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.tools
Interface StandardJavaFileManager

All Superinterfaces:
Closeable, Flushable, JavaFileManager, OptionChecker
public interface StandardJavaFileManager
extends JavaFileManager

File manager based on java.io.File. A common way to obtain an instance of this class is using getStandardFileManager, for example:

   JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
   DiagnosticCollector<JavaFileObject> diagnostics =
       new DiagnosticCollector<JavaFileObject>();
   StandardJavaFileManager fm = compiler.getStandardFileManager(diagnostics, null, null);
This file manager creates file objects representing regular files, zip file entries, or entries in similar file system based containers. Any file object returned from a file manager implementing this interface must observe the following behavior:
  • File names need not be canonical.
  • For file objects representing regular files
    • the method FileObject.delete() is equivalent to File.delete(),
    • the method FileObject.getLastModified() is equivalent to File.lastModified(),
    • the methods FileObject.getCharContent(boolean), FileObject.openInputStream(), and FileObject.openReader(boolean) must succeed if the following would succeed (ignoring encoding issues):
      new FileInputStream(new File(fileObject.toUri()))
    • and the methods FileObject.openOutputStream(), and FileObject.openWriter() must succeed if the following would succeed (ignoring encoding issues):
      new FileOutputStream(new File(fileObject.toUri()))
  • The URI returned from FileObject.toUri()
    • must be absolute (have a schema), and
    • must have a normalized path component which can be resolved without any process-specific context such as the current directory (file names must be absolute).
According to these rules, the following URIs, for example, are allowed:
  • file:///C:/Documents%20and%20Settings/UncleBob/BobsApp/Test.java
  • jar:///C:/Documents%20and%20Settings/UncleBob/lib/vendorA.jar!com/vendora/LibraryClass.class
Whereas these are not (reason in parentheses):
  • file:BobsApp/Test.java (the file name is relative and depend on the current directory)
  • jar:lib/vendorA.jar!com/vendora/LibraryClass.class (the first half of the path depends on the current directory, whereas the component after ! is legal)
  • Test.java (this URI depends on the current directory and does not have a schema)
  • jar:///C:/Documents%20and%20Settings/UncleBob/BobsApp/../lib/vendorA.jar!com/vendora/LibraryClass.class (the path is not normalized)

Since:
1.6

Nested Class Summary
Nested classes/interfaces inherited from interface javax.tools.JavaFileManager
JavaFileManager.Location
Method Summary
Iterable<? extends JavaFileObject> | getJavaFileObjects(File... files) Gets file objects representing the given files.
Iterable<? extends JavaFileObject> | getJavaFileObjects(String... names) Gets file objects representing the given file names.
Iterable<? extends JavaFileObject> | getJavaFileObjectsFromFiles(Iterable<? extends File> files) Gets file objects representing the given files.
Iterable<? extends JavaFileObject> | getJavaFileObjectsFromStrings(Iterable<String> names) Gets file objects representing the given file names.
Iterable<? extends File> | getLocation(JavaFileManager.Location location) Gets the path associated with the given location.
boolean | isSameFile(FileObject a, FileObject b) Compares two file objects and return true if they represent the same canonical file, zip file entry, or entry in any file system based container.
void | setLocation(JavaFileManager.Location location, Iterable<? extends File> path) Associates the given path with the given location.
Methods inherited from interface javax.tools.JavaFileManager
close, flush, getClassLoader, getFileForInput, getFileForOutput, getJavaFileForInput, getJavaFileForOutput, handleOption, hasLocation, inferBinaryName, list
Methods inherited from interface javax.tools.OptionChecker
isSupportedOption

Method Detail

isSameFile

boolean isSameFile(FileObject a,
                   FileObject b)
Compares two file objects and return true if they represent the same canonical file, zip file entry, or entry in any file system based container.

Specified by:
isSameFile in interface JavaFileManager
Parameters:
a - a file object
b - a file object
Returns:
true if the given file objects represent the same canonical file or zip file entry; false otherwise
Throws:
IllegalArgumentException - if either of the arguments were created with another file manager implementation

getJavaFileObjectsFromFiles

Iterable<? extends JavaFileObject> getJavaFileObjectsFromFiles(Iterable<? extends File> files)
Gets file objects representing the given files.

Parameters:
files - a list of files
Returns:
a list of file objects
Throws:
IllegalArgumentException - if the list of files includes a directory

getJavaFileObjects

Iterable<? extends JavaFileObject> getJavaFileObjects(File... files)
Gets file objects representing the given files. Convenience method equivalent to:
     getJavaFileObjectsFromFiles(Arrays.asList(files))

Parameters:
files - an array of files
Returns:
a list of file objects
Throws:
IllegalArgumentException - if the array of files includes a directory
NullPointerException - if the given array contains null elements

getJavaFileObjectsFromStrings

Iterable<? extends JavaFileObject> getJavaFileObjectsFromStrings(Iterable<String> names)
Gets file objects representing the given file names.

Parameters:
names - a list of file names
Returns:
a list of file objects
Throws:
IllegalArgumentException - if the list of file names includes a directory

getJavaFileObjects

Iterable<? extends JavaFileObject> getJavaFileObjects(String... names)
Gets file objects representing the given file names. Convenience method equivalent to:
     getJavaFileObjectsFromStrings(Arrays.asList(names))

Parameters:
names - a list of file names
Returns:
a list of file objects
Throws:
IllegalArgumentException - if the array of file names includes a directory
NullPointerException - if the given array contains null elements

setLocation

void setLocation(JavaFileManager.Location location,
                 Iterable<? extends File> path)
                 throws IOException
Associates the given path with the given location. Any previous value will be discarded.

Parameters:
location - a location
path - a list of files, if null use the default path for this location
Throws:
IllegalArgumentException - if location is an output location and path does not contain exactly one element
IOException - if location is an output location and path does not represent an existing directory
See Also:
getLocation(javax.tools.JavaFileManager.Location)

getLocation

Iterable<? extends File> getLocation(JavaFileManager.Location location)
Gets the path associated with the given location.

Parameters:
location - a location
Returns:
a list of files or null if this location has no associated path
See Also:
setLocation(javax.tools.JavaFileManager.Location, java.lang.Iterable)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StandardLocation

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.tools
Enum StandardLocation

java.lang.Object
    extended by  java.lang.Enum<StandardLocation>
        extended by  javax.tools.StandardLocation
All Implemented Interfaces:
Serializable, Comparable<StandardLocation>, JavaFileManager.Location
public enum StandardLocation
extends Enum<StandardLocation>
implements JavaFileManager.Location

Standard locations of file objects.

Since:
1.6

Enum Constant Summary
ANNOTATION_PROCESSOR_PATH
Location to search for annotation processors.
CLASS_OUTPUT
Location of new class files.
CLASS_PATH
Location to search for user class files.
PLATFORM_CLASS_PATH
Location to search for platform classes.
SOURCE_OUTPUT
Location of new source files.
SOURCE_PATH
Location to search for existing source files.
Method Summary
String | getName() Gets the name of this location.
boolean | isOutputLocation() Determines if this is an output location.
static JavaFileManager.Location | locationFor(String name) Gets a location object with the given name.
static StandardLocation | valueOf(String name) Returns the enum constant of this type with the specified name.
static StandardLocation[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

CLASS_OUTPUT

public static final StandardLocation CLASS_OUTPUT
Location of new class files.

SOURCE_OUTPUT

public static final StandardLocation SOURCE_OUTPUT
Location of new source files.

CLASS_PATH

public static final StandardLocation CLASS_PATH
Location to search for user class files.

SOURCE_PATH

public static final StandardLocation SOURCE_PATH
Location to search for existing source files.

ANNOTATION_PROCESSOR_PATH

public static final StandardLocation ANNOTATION_PROCESSOR_PATH
Location to search for annotation processors.

PLATFORM_CLASS_PATH

public static final StandardLocation PLATFORM_CLASS_PATH
Location to search for platform classes. Sometimes called the boot class path.

Method Detail

values

public static StandardLocation[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (StandardLocation c : StandardLocation.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static StandardLocation valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null

locationFor

public static JavaFileManager.Location locationFor(String name)
Gets a location object with the given name. The following property must hold: locationFor(x) == locationFor(y) if and only if x.equals(y). The returned location will be an output location if and only if name ends with "_OUTPUT".

Parameters:
name - a name
Returns:
a location

getName

public String getName()
Description copied from interface: JavaFileManager.Location
Gets the name of this location.

Specified by:
getName in interface JavaFileManager.Location
Returns:
a name

isOutputLocation

public boolean isOutputLocation()
Description copied from interface: JavaFileManager.Location
Determines if this is an output location. An output location is a location that is conventionally used for output.

Specified by:
isOutputLocation in interface JavaFileManager.Location
Returns:
true if this is an output location, false otherwise
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


Tool

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.tools
Interface Tool

All Known Subinterfaces:
JavaCompiler
public interface Tool

Common interface for tools that can be invoked from a program. A tool is traditionally a command line program such as a compiler. The set of tools available with a platform is defined by the vendor.

Tools can be located using ServiceLoader.load(Class).

Since:
1.6

Method Summary
Set<SourceVersion> | getSourceVersions() Gets the source versions of the Java™ programming language supported by this tool.
int | run(InputStream in, OutputStream out, OutputStream err, String... arguments) Run the tool with the given I/O channels and arguments.

Method Detail

run

int run(InputStream in,
        OutputStream out,
        OutputStream err,
        String... arguments)
Run the tool with the given I/O channels and arguments. By convention a tool returns 0 for success and nonzero for errors. Any diagnostics generated will be written to either out or err in some unspecified format.

Parameters:
in - "standard" input; use System.in if null
out - "standard" output; use System.out if null
err - "standard" error; use System.err if null
arguments - arguments to pass to the tool
Returns:
0 for success; nonzero otherwise
Throws:
NullPointerException - if the array of arguments contains any null elements.

getSourceVersions

Set<SourceVersion> getSourceVersions()
Gets the source versions of the Java™ programming language supported by this tool.

Returns:
a set of supported source versions
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ToolProvider

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.tools
Class ToolProvider

java.lang.Object
    extended by  javax.tools.ToolProvider

public class ToolProvider
extends Object

Provides methods for locating tool providers, for example, providers of compilers. This class complements the functionality of ServiceLoader.

Since:
1.6

Method Summary
static JavaCompiler | getSystemJavaCompiler() Gets the Java™ programming language compiler provided with this platform.
static ClassLoader | getSystemToolClassLoader() Returns the class loader for tools provided with this platform.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getSystemJavaCompiler

public static JavaCompiler getSystemJavaCompiler()
Gets the Java™ programming language compiler provided with this platform.

Returns:
the compiler provided with this platform or null if no compiler is provided

getSystemToolClassLoader

public static ClassLoader getSystemToolClassLoader()
Returns the class loader for tools provided with this platform. This does not include user-installed tools. Use the service provider mechanism for locating user installed tools.

Returns:
the class loader for tools provided with this platform or null if no tools are provided
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


transaction

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.transaction

Contains three exceptions thrown by the ORB machinery during unmarshalling.

See:
Description

Exception Summary
InvalidTransactionException | This exception indicates that the request carried an invalid transaction context.
TransactionRequiredException | This exception indicates that a request carried a null transaction context, but the target object requires an activate transaction.
TransactionRolledbackException | This exception indicates that the transaction associated with processing of the request has been rolled back, or marked to roll back.

Package javax.transaction Description

Contains three exceptions thrown by the ORB machinery during unmarshalling.

Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.transaction Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.transaction

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.io.IOException
          • java.rmi.RemoteException
            • javax.transaction.InvalidTransactionException
            • javax.transaction.TransactionRequiredException
            • javax.transaction.TransactionRolledbackException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.transaction

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.transaction

No usage of javax.transaction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.transaction.InvalidTransactionException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.transaction.InvalidTransactionException

No usage of javax.transaction.InvalidTransactionException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.transaction.TransactionRequiredException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.transaction.TransactionRequiredException

No usage of javax.transaction.TransactionRequiredException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.transaction.TransactionRolledbackException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.transaction.TransactionRolledbackException

No usage of javax.transaction.TransactionRolledbackException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


InvalidTransactionException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.transaction
Class InvalidTransactionException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.io.IOException
                extended by  java.rmi.RemoteException
                    extended by  javax.transaction.InvalidTransactionException
All Implemented Interfaces:
Serializable
public class InvalidTransactionException
extends RemoteException

This exception indicates that the request carried an invalid transaction context. For example, this exception could be raised if an error occured when trying to register a resource.

See Also:
Serialized Form

Field Summary
Fields inherited from class java.rmi.RemoteException
detail
Constructor Summary
InvalidTransactionException()
InvalidTransactionException(String msg)
Method Summary
Methods inherited from class java.rmi.RemoteException
getCause, getMessage
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidTransactionException

public InvalidTransactionException()

InvalidTransactionException

public InvalidTransactionException(String msg)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


TransactionRequiredException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.transaction
Class TransactionRequiredException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.io.IOException
                extended by  java.rmi.RemoteException
                    extended by  javax.transaction.TransactionRequiredException
All Implemented Interfaces:
Serializable
public class TransactionRequiredException
extends RemoteException

This exception indicates that a request carried a null transaction context, but the target object requires an activate transaction.

See Also:
Serialized Form

Field Summary
Fields inherited from class java.rmi.RemoteException
detail
Constructor Summary
TransactionRequiredException()
TransactionRequiredException(String msg)
Method Summary
Methods inherited from class java.rmi.RemoteException
getCause, getMessage
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TransactionRequiredException

public TransactionRequiredException()

TransactionRequiredException

public TransactionRequiredException(String msg)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TransactionRolledbackException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.transaction
Class TransactionRolledbackException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.io.IOException
                extended by  java.rmi.RemoteException
                    extended by  javax.transaction.TransactionRolledbackException
All Implemented Interfaces:
Serializable
public class TransactionRolledbackException
extends RemoteException

This exception indicates that the transaction associated with processing of the request has been rolled back, or marked to roll back. Thus the requested operation either could not be performed or was not performed because further computation on behalf of the transaction would be fruitless

See Also:
Serialized Form

Field Summary
Fields inherited from class java.rmi.RemoteException
detail
Constructor Summary
TransactionRolledbackException()
TransactionRolledbackException(String msg)
Method Summary
Methods inherited from class java.rmi.RemoteException
getCause, getMessage
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TransactionRolledbackException

public TransactionRolledbackException()

TransactionRolledbackException

public TransactionRolledbackException(String msg)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


xa

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.transaction.xa

Provides the API that defines the contract between the transaction manager and the resource manager, which allows the transaction manager to enlist and delist resource objects (supplied by the resource manager driver) in JTA transactions.

See:
Description

Interface Summary
XAResource | The XAResource interface is a Java mapping of the industry standard XA interface based on the X/Open CAE Specification (Distributed Transaction Processing: The XA Specification).
Xid | The Xid interface is a Java mapping of the X/Open transaction identifier XID structure.

Exception Summary
XAException The XAException is thrown by the Resource Manager (RM) to inform the Transaction Manager of an error encountered by the involved transaction.

Package javax.transaction.xa Description

Provides the API that defines the contract between the transaction manager and the resource manager, which allows the transaction manager to enlist and delist resource objects (supplied by the resource manager driver) in JTA transactions. The driver vendor for a specific resource manager provides the implementation of this API.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.transaction.xa Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.transaction.xa

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.transaction.xa.XAException

Interface Hierarchy

  • javax.transaction.xa.XAResource
  • javax.transaction.xa.Xid
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.transaction.xa

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.transaction.xa

Packages that use javax.transaction.xa
javax.sql | Provides the API for server side data source access and processing from the JavaTM programming language.
javax.transaction.xa | Provides the API that defines the contract between the transaction manager and the resource manager, which allows the transaction manager to enlist and delist resource objects (supplied by the resource manager driver) in JTA transactions.

Classes in javax.transaction.xa used by javax.sql
XAResource
The XAResource interface is a Java mapping of the industry standard XA interface based on the X/Open CAE Specification (Distributed Transaction Processing: The XA Specification).

Classes in javax.transaction.xa used by javax.transaction.xa
XAException
The XAException is thrown by the Resource Manager (RM) to inform the Transaction Manager of an error encountered by the involved transaction.
XAResource
The XAResource interface is a Java mapping of the industry standard XA interface based on the X/Open CAE Specification (Distributed Transaction Processing: The XA Specification).
Xid
The Xid interface is a Java mapping of the X/Open transaction identifier XID structure.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.transaction.xa.XAException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.transaction.xa.XAException

Packages that use XAException
javax.transaction.xa Provides the API that defines the contract between the transaction manager and the resource manager, which allows the transaction manager to enlist and delist resource objects (supplied by the resource manager driver) in JTA transactions.

Uses of XAException in javax.transaction.xa

Methods in javax.transaction.xa that throw XAException
void | XAResource.commit(Xid xid, boolean onePhase) Commits the global transaction specified by xid.
void | XAResource.end(Xid xid, int flags) Ends the work performed on behalf of a transaction branch.
void | XAResource.forget(Xid xid) Tells the resource manager to forget about a heuristically completed transaction branch.
int | XAResource.getTransactionTimeout() Obtains the current transaction timeout value set for this XAResource instance.
boolean | XAResource.isSameRM(XAResource xares) This method is called to determine if the resource manager instance represented by the target object is the same as the resouce manager instance represented by the parameter xares.
int | XAResource.prepare(Xid xid) Ask the resource manager to prepare for a transaction commit of the transaction specified in xid.
Xid[] | XAResource.recover(int flag) Obtains a list of prepared transaction branches from a resource manager.
void | XAResource.rollback(Xid xid) Informs the resource manager to roll back work done on behalf of a transaction branch.
boolean | XAResource.setTransactionTimeout(int seconds) Sets the current transaction timeout value for this XAResource instance.
void | XAResource.start(Xid xid, int flags) Starts work on behalf of a transaction branch specified in xid.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.transaction.xa.XAResource

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.transaction.xa.XAResource

Packages that use XAResource
javax.sql | Provides the API for server side data source access and processing from the JavaTM programming language.
javax.transaction.xa | Provides the API that defines the contract between the transaction manager and the resource manager, which allows the transaction manager to enlist and delist resource objects (supplied by the resource manager driver) in JTA transactions.

Uses of XAResource in javax.sql

Methods in javax.sql that return XAResource
 XAResource XAConnection.getXAResource()
Retrieves an XAResource object that the transaction manager will use to manage this XAConnection object's participation in a distributed transaction.

Uses of XAResource in javax.transaction.xa

Methods in javax.transaction.xa with parameters of type XAResource
 boolean XAResource.isSameRM(XAResource xares)
This method is called to determine if the resource manager instance represented by the target object is the same as the resouce manager instance represented by the parameter xares.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.transaction.xa.Xid

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.transaction.xa.Xid

Packages that use Xid
javax.transaction.xa Provides the API that defines the contract between the transaction manager and the resource manager, which allows the transaction manager to enlist and delist resource objects (supplied by the resource manager driver) in JTA transactions.

Uses of Xid in javax.transaction.xa

Methods in javax.transaction.xa that return Xid
 Xid[] XAResource.recover(int flag)
Obtains a list of prepared transaction branches from a resource manager.

Methods in javax.transaction.xa with parameters of type Xid
void | XAResource.commit(Xid xid, boolean onePhase) Commits the global transaction specified by xid.
void | XAResource.end(Xid xid, int flags) Ends the work performed on behalf of a transaction branch.
void | XAResource.forget(Xid xid) Tells the resource manager to forget about a heuristically completed transaction branch.
int | XAResource.prepare(Xid xid) Ask the resource manager to prepare for a transaction commit of the transaction specified in xid.
void | XAResource.rollback(Xid xid) Informs the resource manager to roll back work done on behalf of a transaction branch.
void | XAResource.start(Xid xid, int flags) Starts work on behalf of a transaction branch specified in xid.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


XAException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.transaction.xa
Class XAException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.transaction.xa.XAException
All Implemented Interfaces:
Serializable
public class XAException
extends Exception

The XAException is thrown by the Resource Manager (RM) to inform the Transaction Manager of an error encountered by the involved transaction.

See Also:
Serialized Form

Field Summary
int | errorCode The error code with which to create the SystemException.
static int | XA_HEURCOM The transaction branch has been heuristically committed.
static int | XA_HEURHAZ The transaction branch may have been heuristically completed.
static int | XA_HEURMIX The transaction branch has been heuristically committed and rolled back.
static int | XA_HEURRB The transaction branch has been heuristically rolled back.
static int | XA_NOMIGRATE Resumption must occur where the suspension occurred.
static int | XA_RBBASE The inclusive lower bound of the rollback codes.
static int | XA_RBCOMMFAIL Indicates that the rollback was caused by a communication failure.
static int | XA_RBDEADLOCK A deadlock was detected.
static int | XA_RBEND The inclusive upper bound of the rollback error code.
static int | XA_RBINTEGRITY A condition that violates the integrity of the resource was detected.
static int | XA_RBOTHER The resource manager rolled back the transaction branch for a reason not on this list.
static int | XA_RBPROTO A protocol error occurred in the resource manager.
static int | XA_RBROLLBACK Indicates that the rollback was caused by an unspecified reason.
static int | XA_RBTIMEOUT A transaction branch took too long.
static int | XA_RBTRANSIENT May retry the transaction branch.
static int | XA_RDONLY The transaction branch was read-only and has been committed.
static int | XA_RETRY Routine returned with no effect and may be reissued.
static int | XAER_ASYNC There is an asynchronous operation already outstanding.
static int | XAER_DUPID The XID already exists.
static int | XAER_INVAL Invalid arguments were given.
static int | XAER_NOTA The XID is not valid.
static int | XAER_OUTSIDE The resource manager is doing work outside a global transaction.
static int | XAER_PROTO Routine was invoked in an inproper context.
static int | XAER_RMERR A resource manager error has occurred in the transaction branch.
static int | XAER_RMFAIL Resource manager is unavailable.
Constructor Summary
XAException()
Create an XAException.
XAException(int errcode)
Create an XAException with a given error code.
XAException(String s)
Create an XAException with a given string.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

errorCode

public int errorCode
The error code with which to create the SystemException.

XA_RBBASE

public static final int XA_RBBASE
The inclusive lower bound of the rollback codes.

See Also:
Constant Field Values

XA_RBROLLBACK

public static final int XA_RBROLLBACK
Indicates that the rollback was caused by an unspecified reason.

See Also:
Constant Field Values

XA_RBCOMMFAIL

public static final int XA_RBCOMMFAIL
Indicates that the rollback was caused by a communication failure.

See Also:
Constant Field Values

XA_RBDEADLOCK

public static final int XA_RBDEADLOCK
A deadlock was detected.

See Also:
Constant Field Values

XA_RBINTEGRITY

public static final int XA_RBINTEGRITY
A condition that violates the integrity of the resource was detected.

See Also:
Constant Field Values

XA_RBOTHER

public static final int XA_RBOTHER
The resource manager rolled back the transaction branch for a reason not on this list.

See Also:
Constant Field Values

XA_RBPROTO

public static final int XA_RBPROTO
A protocol error occurred in the resource manager.

See Also:
Constant Field Values

XA_RBTIMEOUT

public static final int XA_RBTIMEOUT
A transaction branch took too long.

See Also:
Constant Field Values

XA_RBTRANSIENT

public static final int XA_RBTRANSIENT
May retry the transaction branch.

See Also:
Constant Field Values

XA_RBEND

public static final int XA_RBEND
The inclusive upper bound of the rollback error code.

See Also:
Constant Field Values

XA_NOMIGRATE

public static final int XA_NOMIGRATE
Resumption must occur where the suspension occurred.

See Also:
Constant Field Values

XA_HEURHAZ

public static final int XA_HEURHAZ
The transaction branch may have been heuristically completed.

See Also:
Constant Field Values

XA_HEURCOM

public static final int XA_HEURCOM
The transaction branch has been heuristically committed.

See Also:
Constant Field Values

XA_HEURRB

public static final int XA_HEURRB
The transaction branch has been heuristically rolled back.

See Also:
Constant Field Values

XA_HEURMIX

public static final int XA_HEURMIX
The transaction branch has been heuristically committed and rolled back.

See Also:
Constant Field Values

XA_RETRY

public static final int XA_RETRY
Routine returned with no effect and may be reissued.

See Also:
Constant Field Values

XA_RDONLY

public static final int XA_RDONLY
The transaction branch was read-only and has been committed.

See Also:
Constant Field Values

XAER_ASYNC

public static final int XAER_ASYNC
There is an asynchronous operation already outstanding.

See Also:
Constant Field Values

XAER_RMERR

public static final int XAER_RMERR
A resource manager error has occurred in the transaction branch.

See Also:
Constant Field Values

XAER_NOTA

public static final int XAER_NOTA
The XID is not valid.

See Also:
Constant Field Values

XAER_INVAL

public static final int XAER_INVAL
Invalid arguments were given.

See Also:
Constant Field Values

XAER_PROTO

public static final int XAER_PROTO
Routine was invoked in an inproper context.

See Also:
Constant Field Values

XAER_RMFAIL

public static final int XAER_RMFAIL
Resource manager is unavailable.

See Also:
Constant Field Values

XAER_DUPID

public static final int XAER_DUPID
The XID already exists.

See Also:
Constant Field Values

XAER_OUTSIDE

public static final int XAER_OUTSIDE
The resource manager is doing work outside a global transaction.

See Also:
Constant Field Values
Constructor Detail

XAException

public XAException()
Create an XAException.

XAException

public XAException(String s)
Create an XAException with a given string.

Parameters:
s - The String object containing the exception message.

XAException

public XAException(int errcode)
Create an XAException with a given error code.

Parameters:
errcode - The error code identifying the exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


XAResource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.transaction.xa
Interface XAResource

public interface XAResource

The XAResource interface is a Java mapping of the industry standard XA interface based on the X/Open CAE Specification (Distributed Transaction Processing: The XA Specification).

The XA interface defines the contract between a Resource Manager and a Transaction Manager in a distributed transaction processing (DTP) environment. A JDBC driver or a JMS provider implements this interface to support the association between a global transaction and a database or message service connection.

The XAResource interface can be supported by any transactional resource that is intended to be used by application programs in an environment where transactions are controlled by an external transaction manager. An example of such a resource is a database management system. An application may access data through multiple database connections. Each database connection is enlisted with the transaction manager as a transactional resource. The transaction manager obtains an XAResource for each connection participating in a global transaction. The transaction manager uses the start method to associate the global transaction with the resource, and it uses the end method to disassociate the transaction from the resource. The resource manager is responsible for associating the global transaction to all work performed on its data between the start and end method invocations.

At transaction commit time, the resource managers are informed by the transaction manager to prepare, commit, or rollback a transaction according to the two-phase commit protocol.

Field Summary
static int | TMENDRSCAN Ends a recovery scan.
static int | TMFAIL Disassociates the caller and marks the transaction branch rollback-only.
static int | TMJOIN Caller is joining existing transaction branch.
static int | TMNOFLAGS Use TMNOFLAGS to indicate no flags value is selected.
static int | TMONEPHASE Caller is using one-phase optimization.
static int | TMRESUME Caller is resuming association with a suspended transaction branch.
static int | TMSTARTRSCAN Starts a recovery scan.
static int | TMSUCCESS Disassociates caller from a transaction branch.
static int | TMSUSPEND Caller is suspending (not ending) its association with a transaction branch.
static int | XA_OK The transaction work has been prepared normally.
static int | XA_RDONLY The transaction branch has been read-only and has been committed.
Method Summary
void | commit(Xid xid, boolean onePhase) Commits the global transaction specified by xid.
void | end(Xid xid, int flags) Ends the work performed on behalf of a transaction branch.
void | forget(Xid xid) Tells the resource manager to forget about a heuristically completed transaction branch.
int | getTransactionTimeout() Obtains the current transaction timeout value set for this XAResource instance.
boolean | isSameRM(XAResource xares) This method is called to determine if the resource manager instance represented by the target object is the same as the resouce manager instance represented by the parameter xares.
int | prepare(Xid xid) Ask the resource manager to prepare for a transaction commit of the transaction specified in xid.
Xid[] | recover(int flag) Obtains a list of prepared transaction branches from a resource manager.
void | rollback(Xid xid) Informs the resource manager to roll back work done on behalf of a transaction branch.
boolean | setTransactionTimeout(int seconds) Sets the current transaction timeout value for this XAResource instance.
void | start(Xid xid, int flags) Starts work on behalf of a transaction branch specified in xid.

Field Detail

TMENDRSCAN

static final int TMENDRSCAN
Ends a recovery scan.

See Also:
Constant Field Values

TMFAIL

static final int TMFAIL
Disassociates the caller and marks the transaction branch rollback-only.

See Also:
Constant Field Values

TMJOIN

static final int TMJOIN
Caller is joining existing transaction branch.

See Also:
Constant Field Values

TMNOFLAGS

static final int TMNOFLAGS
Use TMNOFLAGS to indicate no flags value is selected.

See Also:
Constant Field Values

TMONEPHASE

static final int TMONEPHASE
Caller is using one-phase optimization.

See Also:
Constant Field Values

TMRESUME

static final int TMRESUME
Caller is resuming association with a suspended transaction branch.

See Also:
Constant Field Values

TMSTARTRSCAN

static final int TMSTARTRSCAN
Starts a recovery scan.

See Also:
Constant Field Values

TMSUCCESS

static final int TMSUCCESS
Disassociates caller from a transaction branch.

See Also:
Constant Field Values

TMSUSPEND

static final int TMSUSPEND
Caller is suspending (not ending) its association with a transaction branch.

See Also:
Constant Field Values

XA_RDONLY

static final int XA_RDONLY
The transaction branch has been read-only and has been committed.

See Also:
Constant Field Values

XA_OK

static final int XA_OK
The transaction work has been prepared normally.

See Also:
Constant Field Values
Method Detail

commit

void commit(Xid xid,
            boolean onePhase)
            throws XAException
Commits the global transaction specified by xid.

Parameters:
xid - A global transaction identifier
onePhase - If true, the resource manager should use a one-phase commit protocol to commit the work done on behalf of xid.
Throws:
XAException - An error has occurred. Possible XAExceptions are XA_HEURHAZ, XA_HEURCOM, XA_HEURRB, XA_HEURMIX, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

If the resource manager did not commit the transaction and the paramether onePhase is set to true, the resource manager may throw one of the XA_RB* exceptions. Upon return, the resource manager has rolled back the branch's work and has released all held resources.

end

void end(Xid xid,
         int flags)
         throws XAException
Ends the work performed on behalf of a transaction branch. The resource manager disassociates the XA resource from the transaction branch specified and lets the transaction complete.

If TMSUSPEND is specified in the flags, the transaction branch is temporarily suspended in an incomplete state. The transaction context is in a suspended state and must be resumed via the start method with TMRESUME specified.

If TMFAIL is specified, the portion of work has failed. The resource manager may mark the transaction as rollback-only

If TMSUCCESS is specified, the portion of work has completed successfully.

Parameters:
xid - A global transaction identifier that is the same as the identifier used previously in the start method.
flags - One of TMSUCCESS, TMFAIL, or TMSUSPEND.
Throws:
XAException - An error has occurred. Possible XAException values are XAER_RMERR, XAER_RMFAILED, XAER_NOTA, XAER_INVAL, XAER_PROTO, or XA_RB*.

forget

void forget(Xid xid)
            throws XAException
Tells the resource manager to forget about a heuristically completed transaction branch.

Parameters:
xid - A global transaction identifier.
Throws:
XAException - An error has occurred. Possible exception values are XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

getTransactionTimeout

int getTransactionTimeout()
                          throws XAException
Obtains the current transaction timeout value set for this XAResource instance. If XAResource.setTransactionTimeout was not used prior to invoking this method, the return value is the default timeout set for the resource manager; otherwise, the value used in the previous setTransactionTimeout call is returned.

Returns:
the transaction timeout value in seconds.
Throws:
XAException - An error has occurred. Possible exception values are XAER_RMERR and XAER_RMFAIL.

isSameRM

boolean isSameRM(XAResource xares)
                 throws XAException
This method is called to determine if the resource manager instance represented by the target object is the same as the resouce manager instance represented by the parameter xares.

Parameters:
xares - An XAResource object whose resource manager instance is to be compared with the resource manager instance of the target object.
Returns:
true if it's the same RM instance; otherwise false.
Throws:
XAException - An error has occurred. Possible exception values are XAER_RMERR and XAER_RMFAIL.

prepare

int prepare(Xid xid)
            throws XAException
Ask the resource manager to prepare for a transaction commit of the transaction specified in xid.

Parameters:
xid - A global transaction identifier.
Returns:
A value indicating the resource manager's vote on the outcome of the transaction. The possible values are: XA_RDONLY or XA_OK. If the resource manager wants to roll back the transaction, it should do so by raising an appropriate XAException in the prepare method.
Throws:
XAException - An error has occurred. Possible exception values are: XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL, or XAER_PROTO.

recover

Xid[] recover(int flag)
              throws XAException
Obtains a list of prepared transaction branches from a resource manager. The transaction manager calls this method during recovery to obtain the list of transaction branches that are currently in prepared or heuristically completed states.

Parameters:
flag - One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS must be used when no other flags are set in the parameter.
Returns:
The resource manager returns zero or more XIDs of the transaction branches that are currently in a prepared or heuristically completed state. If an error occurs during the operation, the resource manager should throw the appropriate XAException.
Throws:
XAException - An error has occurred. Possible values are XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and XAER_PROTO.

rollback

void rollback(Xid xid)
              throws XAException
Informs the resource manager to roll back work done on behalf of a transaction branch.

Parameters:
xid - A global transaction identifier.
Throws:
XAException - An error has occurred.

setTransactionTimeout

boolean setTransactionTimeout(int seconds)
                              throws XAException

Sets the current transaction timeout value for this XAResource instance. Once set, this timeout value is effective until setTransactionTimeout is invoked again with a different value. To reset the timeout value to the default value used by the resource manager, set the value to zero. If the timeout operation is performed successfully, the method returns true; otherwise false. If a resource manager does not support explicitly setting the transaction timeout value, this method returns false.

Parameters:
seconds - The transaction timeout value in seconds.
Returns:
true if the transaction timeout value is set successfully; otherwise false.
Throws:
XAException - An error has occurred. Possible exception values are XAER_RMERR, XAER_RMFAIL, or XAER_INVAL.

start

void start(Xid xid,
           int flags)
           throws XAException
Starts work on behalf of a transaction branch specified in xid. If TMJOIN is specified, the start applies to joining a transaction previously seen by the resource manager. If TMRESUME is specified, the start applies to resuming a suspended transaction specified in the parameter xid. If neither TMJOIN nor TMRESUME is specified and the transaction specified by xid has previously been seen by the resource manager, the resource manager throws the XAException exception with XAER_DUPID error code.

Parameters:
xid - A global transaction identifier to be associated with the resource.
flags - One of TMNOFLAGS, TMJOIN, or TMRESUME.
Throws:
XAException - An error has occurred. Possible exceptions are XA_RB*, XAER_RMERR, XAER_RMFAIL, XAER_DUPID, XAER_OUTSIDE, XAER_NOTA, XAER_INVAL, or XAER_PROTO.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Xid

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.transaction.xa
Interface Xid

public interface Xid

The Xid interface is a Java mapping of the X/Open transaction identifier XID structure. This interface specifies three accessor methods to retrieve a global transaction format ID, global transaction ID, and branch qualifier. The Xid interface is used by the transaction manager and the resource managers. This interface is not visible to the application programs.

Field Summary
static int | MAXBQUALSIZE Maximum number of bytes returned by getBqual.
static int | MAXGTRIDSIZE Maximum number of bytes returned by getGtrid.
Method Summary
byte[] | getBranchQualifier() Obtain the transaction branch identifier part of XID as an array of bytes.
int | getFormatId() Obtain the format identifier part of the XID.
byte[] | getGlobalTransactionId() Obtain the global transaction identifier part of XID as an array of bytes.

Field Detail

MAXGTRIDSIZE

static final int MAXGTRIDSIZE
Maximum number of bytes returned by getGtrid.

See Also:
Constant Field Values

MAXBQUALSIZE

static final int MAXBQUALSIZE
Maximum number of bytes returned by getBqual.

See Also:
Constant Field Values
Method Detail

getFormatId

int getFormatId()
Obtain the format identifier part of the XID.

Returns:
Format identifier. O means the OSI CCR format.

getGlobalTransactionId

byte[] getGlobalTransactionId()
Obtain the global transaction identifier part of XID as an array of bytes.

Returns:
Global transaction identifier.

getBranchQualifier

byte[] getBranchQualifier()
Obtain the transaction branch identifier part of XID as an array of bytes.

Returns:
Global transaction identifier.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


xml

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml

Defines core XML constants and functionality from the XML specifications.

See:
Description

Class Summary
XMLConstants Utility class to contain basic XML values as constants.

Package javax.xml Description

Defines core XML constants and functionality from the XML specifications.

The following core XML standards apply:

  • Extensible Markup Language (XML) 1.1
  • Extensible Markup Language (XML) 1.0 (Second Edition)
  • XML 1.0 Second Edition Specification Errata
  • Namespaces in XML 1.1
  • Namespaces in XML
  • Namespaces in XML Errata

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.XMLConstants
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml

No usage of javax.xml

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


bind

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.bind

Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.

See:
Description

Interface Summary
DatatypeConverterInterface | The DatatypeConverterInterface is for JAXB provider use only.
Element | This is an element marker interface.
Marshaller | The Marshaller class is responsible for governing the process of serializing Java content trees back into XML data.
NotIdentifiableEvent | This event indicates that a problem was encountered resolving an ID/IDREF.
ParseConversionEvent | This event indicates that a problem was encountered while converting a string from the XML data into a value of the target Java data type.
PrintConversionEvent | This event indicates that a problem was encountered while converting data from the Java content tree into its lexical representation.
Unmarshaller | The Unmarshaller class governs the process of deserializing XML data into newly created Java content trees, optionally validating the XML data as it is unmarshalled.
UnmarshallerHandler | Unmarshaller implemented as SAX ContentHandler.
ValidationEvent | This event indicates that a problem was encountered while validating the incoming XML data during an unmarshal operation, while performing on-demand validation of the Java content tree, or while marshalling the Java content tree back to XML data.
ValidationEventHandler | A basic event handler interface for validation errors.
ValidationEventLocator | Encapsulate the location of a ValidationEvent.
Validator | Deprecated. since JAXB 2.0

Class Summary
Binder<XmlNode> | Enable synchronization between XML infoset nodes and JAXB objects representing same XML document.
DatatypeConverter | The javaType binding declaration can be used to customize the binding of an XML schema datatype to a Java datatype.
JAXBContext | The JAXBContext class provides the client's entry point to the JAXB API.
JAXBElement<T> | JAXB representation of an Xml Element.
JAXBElement.GlobalScope | Designates global scope for an xml element.
JAXBIntrospector | Provide access to JAXB xml binding data for a JAXB object.
Marshaller.Listener | Register an instance of an implementation of this class with a Marshaller to externally listen for marshal events.
SchemaOutputResolver | Controls where a JAXB implementation puts the generates schema files.
Unmarshaller.Listener | Register an instance of an implementation of this class with Unmarshaller to externally listen for unmarshal events.

Exception Summary
JAXBException | This is the root exception class for all JAXB exceptions.
MarshalException | This exception indicates that an error has occurred while performing a marshal operation that the provider is unable to recover from.
PropertyException | This exception indicates that an error was encountered while getting or setting a property.
TypeConstraintException | This exception indicates that a violation of a dynamically checked type constraint was detected.
UnmarshalException | This exception indicates that an error has occurred while performing an unmarshal operation that prevents the JAXB Provider from completing the operation.
ValidationException | This exception indicates that an error has occurred while performing a validate operation.

Package javax.xml.bind Description

Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.

JAXBContext is the client-entry point to the runtime binding framework.

Package Specification

  • JAXB Specification

Related Documentation

For overviews, tutorials, examples, guides, and tool documentation, please see:
  • The JAXB Website

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


Element

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Interface Element

public interface Element

This is an element marker interface. Under certain circumstances, it is necessary for the binding compiler to generate derived java content classes that implement this interface. In those cases, client applications must supply element instances rather than types of elements. For more detail, see section 5.7 "Element Declaration" and 5.7.1 "Bind to Java Element Interface" of the specification.

Since:
JAXB1.0

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


javax.xml.bind Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.bind

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.bind.Binder<XmlNode>
    • javax.xml.bind.DatatypeConverter
    • javax.xml.bind.JAXBContext
    • javax.xml.bind.JAXBElement<T> (implements java.io.Serializable)
    • javax.xml.bind.JAXBElement.GlobalScope
    • javax.xml.bind.JAXBIntrospector
    • javax.xml.bind.Marshaller.Listener
    • javax.xml.bind.SchemaOutputResolver
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.xml.bind.JAXBException
          • javax.xml.bind.MarshalException
          • javax.xml.bind.PropertyException
          • javax.xml.bind.UnmarshalException
          • javax.xml.bind.ValidationException
        • java.lang.RuntimeException
          • javax.xml.bind.TypeConstraintException
    • javax.xml.bind.Unmarshaller.Listener

Interface Hierarchy

  • org.xml.sax.ContentHandler
    • javax.xml.bind.UnmarshallerHandler
  • javax.xml.bind.DatatypeConverterInterface
  • javax.xml.bind.Element
  • javax.xml.bind.Marshaller
  • javax.xml.bind.Unmarshaller
  • javax.xml.bind.ValidationEvent
    • javax.xml.bind.NotIdentifiableEvent
    • javax.xml.bind.ParseConversionEvent
    • javax.xml.bind.PrintConversionEvent
  • javax.xml.bind.ValidationEventHandler
  • javax.xml.bind.ValidationEventLocator
  • javax.xml.bind.Validator
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


NotIdentifiableEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Interface NotIdentifiableEvent

All Superinterfaces:
ValidationEvent
All Known Implementing Classes:
NotIdentifiableEventImpl
public interface NotIdentifiableEvent
extends ValidationEvent

This event indicates that a problem was encountered resolving an ID/IDREF.

Since:
JAXB1.0
See Also:
Validator, ValidationEventHandler

Field Summary
Fields inherited from interface javax.xml.bind.ValidationEvent
ERROR, FATAL_ERROR, WARNING
Method Summary
Methods inherited from interface javax.xml.bind.ValidationEvent
getLinkedException, getLocator, getMessage, getSeverity

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ParseConversionEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Interface ParseConversionEvent

All Superinterfaces:
ValidationEvent
All Known Implementing Classes:
ParseConversionEventImpl
public interface ParseConversionEvent
extends ValidationEvent

This event indicates that a problem was encountered while converting a string from the XML data into a value of the target Java data type.

Since:
JAXB1.0
See Also:
ValidationEvent, ValidationEventHandler, Unmarshaller

Field Summary
Fields inherited from interface javax.xml.bind.ValidationEvent
ERROR, FATAL_ERROR, WARNING
Method Summary
Methods inherited from interface javax.xml.bind.ValidationEvent
getLinkedException, getLocator, getMessage, getSeverity

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrintConversionEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Interface PrintConversionEvent

All Superinterfaces:
ValidationEvent
All Known Implementing Classes:
PrintConversionEventImpl
public interface PrintConversionEvent
extends ValidationEvent

This event indicates that a problem was encountered while converting data from the Java content tree into its lexical representation.

Since:
JAXB1.0
See Also:
ValidationEvent, ValidationEventHandler, Marshaller

Field Summary
Fields inherited from interface javax.xml.bind.ValidationEvent
ERROR, FATAL_ERROR, WARNING
Method Summary
Methods inherited from interface javax.xml.bind.ValidationEvent
getLinkedException, getLocator, getMessage, getSeverity

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Package javax.xml.bind

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.bind

Packages that use javax.xml.bind
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.annotation | Defines annotations for customizing Java program elements to XML Schema mapping.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.bind.util | Useful client utility classes.
javax.xml.ws | This package contains the core JAX-WS APIs.
javax.xml.ws.handler.soap | This package defines APIs for SOAP message handlers.
javax.xml.ws.spi | This package defines SPIs for JAX-WS 2.0.

Classes in javax.xml.bind used by javax.xml.bind
Binder
Enable synchronization between XML infoset nodes and JAXB objects representing same XML document.
DatatypeConverterInterface
The DatatypeConverterInterface is for JAXB provider use only.
JAXBContext
The JAXBContext class provides the client's entry point to the JAXB API.
JAXBElement
JAXB representation of an Xml Element.
JAXBException
This is the root exception class for all JAXB exceptions.
JAXBIntrospector
Provide access to JAXB xml binding data for a JAXB object.
Marshaller
The Marshaller class is responsible for governing the process of serializing Java content trees back into XML data.
Marshaller.Listener

Register an instance of an implementation of this class with a Marshaller to externally listen for marshal events.

PropertyException
This exception indicates that an error was encountered while getting or setting a property.
SchemaOutputResolver
Controls where a JAXB implementation puts the generates schema files.
Unmarshaller
The Unmarshaller class governs the process of deserializing XML data into newly created Java content trees, optionally validating the XML data as it is unmarshalled.
Unmarshaller.Listener

Register an instance of an implementation of this class with Unmarshaller to externally listen for unmarshal events.

UnmarshallerHandler
Unmarshaller implemented as SAX ContentHandler.
ValidationEvent
This event indicates that a problem was encountered while validating the incoming XML data during an unmarshal operation, while performing on-demand validation of the Java content tree, or while marshalling the Java content tree back to XML data.
ValidationEventHandler
A basic event handler interface for validation errors.
ValidationEventLocator
Encapsulate the location of a ValidationEvent.
Validator
Deprecated. since JAXB 2.0

Classes in javax.xml.bind used by javax.xml.bind.annotation
ValidationEventHandler
A basic event handler interface for validation errors.

Classes in javax.xml.bind used by javax.xml.bind.helpers
JAXBElement
JAXB representation of an Xml Element.
JAXBException
This is the root exception class for all JAXB exceptions.
Marshaller
The Marshaller class is responsible for governing the process of serializing Java content trees back into XML data.
Marshaller.Listener

Register an instance of an implementation of this class with a Marshaller to externally listen for marshal events.

NotIdentifiableEvent
This event indicates that a problem was encountered resolving an ID/IDREF.
ParseConversionEvent
This event indicates that a problem was encountered while converting a string from the XML data into a value of the target Java data type.
PrintConversionEvent
This event indicates that a problem was encountered while converting data from the Java content tree into its lexical representation.
PropertyException
This exception indicates that an error was encountered while getting or setting a property.
UnmarshalException
This exception indicates that an error has occurred while performing an unmarshal operation that prevents the JAXB Provider from completing the operation.
Unmarshaller
The Unmarshaller class governs the process of deserializing XML data into newly created Java content trees, optionally validating the XML data as it is unmarshalled.
Unmarshaller.Listener

Register an instance of an implementation of this class with Unmarshaller to externally listen for unmarshal events.

ValidationEvent
This event indicates that a problem was encountered while validating the incoming XML data during an unmarshal operation, while performing on-demand validation of the Java content tree, or while marshalling the Java content tree back to XML data.
ValidationEventHandler
A basic event handler interface for validation errors.
ValidationEventLocator
Encapsulate the location of a ValidationEvent.

Classes in javax.xml.bind used by javax.xml.bind.util
JAXBContext
The JAXBContext class provides the client's entry point to the JAXB API.
JAXBException
This is the root exception class for all JAXB exceptions.
Marshaller
The Marshaller class is responsible for governing the process of serializing Java content trees back into XML data.
Unmarshaller
The Unmarshaller class governs the process of deserializing XML data into newly created Java content trees, optionally validating the XML data as it is unmarshalled.
ValidationEvent
This event indicates that a problem was encountered while validating the incoming XML data during an unmarshal operation, while performing on-demand validation of the Java content tree, or while marshalling the Java content tree back to XML data.
ValidationEventHandler
A basic event handler interface for validation errors.

Classes in javax.xml.bind used by javax.xml.ws
JAXBContext
The JAXBContext class provides the client's entry point to the JAXB API.

Classes in javax.xml.bind used by javax.xml.ws.handler.soap
JAXBContext
The JAXBContext class provides the client's entry point to the JAXB API.

Classes in javax.xml.bind used by javax.xml.ws.spi
JAXBContext
The JAXBContext class provides the client's entry point to the JAXB API.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


annotation

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.bind.annotation

Defines annotations for customizing Java program elements to XML Schema mapping.

See:
Description

Interface Summary
DomHandler<ElementT,ResultT extends Result> Converts an element (and its descendants) from/to DOM (or similar) representation.

Class Summary
W3CDomHandler | DomHandler implementation for W3C DOM (org.w3c.dom package.)
XmlElement.DEFAULT | Used in XmlElement.type() to signal that the type be inferred from the signature of the property.
XmlElementDecl.GLOBAL | Used in XmlElementDecl.scope() to signal that the declaration is in the global scope.
XmlElementRef.DEFAULT | Used in XmlElementRef.type() to signal that the type be inferred from the signature of the property.
XmlSchemaType.DEFAULT | Used in XmlSchemaType.type() to signal that the type be inferred from the signature of the property.
XmlType.DEFAULT | Used in XmlType.factoryClass() to signal that either factory mehod is not used or that it's in the class with this XmlType itself.

Enum Summary
XmlAccessOrder | Used by XmlAccessorOrder to control the ordering of properties and fields in a JAXB bound class.
XmlAccessType | Used by XmlAccessorType to control serialization of fields or properties.
XmlNsForm | Enumeration of XML Schema namespace qualifications.

Annotation Types Summary
XmlAccessorOrder | Controls the ordering of fields and properties in a class.
XmlAccessorType | Controls whether fields or Javabean properties are serialized by default.
XmlAnyAttribute | Maps a JavaBean property to a map of wildcard attributes.
XmlAnyElement | Maps a JavaBean property to XML infoset representation and/or JAXB element.
XmlAttachmentRef | Marks a field/property that its XML form is a uri reference to mime content.
XmlAttribute | Maps a JavaBean property to a XML attribute.
XmlElement | Maps a JavaBean property to a XML element derived from property name.
XmlElementDecl | Maps a factory method to a XML element.
XmlElementRef | Maps a JavaBean property to a XML element derived from property's type.
XmlElementRefs | Marks a property that refers to classes with XmlElement or JAXBElement.
XmlElements | A container for multiple @XmlElement annotations.
XmlElementWrapper | Generates a wrapper element around XML representation.
XmlEnum | Maps an enum type Enum to XML representation.
XmlEnumValue | Maps an enum constant in Enum type to XML representation.
XmlID | Maps a JavaBean property to XML ID.
XmlIDREF | Maps a JavaBean property to XML IDREF.
XmlInlineBinaryData | Disable consideration of XOP encoding for datatypes that are bound to base64-encoded binary data in XML.
XmlList | Used to map a property to a list simple type.
XmlMimeType | Associates the MIME type that controls the XML representation of the property.
XmlMixed | Annotate a JavaBean multi-valued property to support mixed content.
XmlNs | Associates a namespace prefix with a XML namespace URI.
XmlRegistry | Marks a class that has XmlElementDecls.
XmlRootElement | Maps a class or an enum type to an XML element.
XmlSchema | Maps a package name to a XML namespace.
XmlSchemaType | Maps a Java type to a simple schema built-in type.
XmlSchemaTypes | A container for multiple @XmlSchemaType annotations.
XmlTransient | Prevents the mapping of a JavaBean property to XML representation.
XmlType | Maps a class or an enum type to a XML Schema type.
XmlValue | Enables mapping a class to a XML Schema complex type with a simpleContent or a XML Schema simple type.

Package javax.xml.bind.annotation Description

Defines annotations for customizing Java program elements to XML Schema mapping.

Package Specification

The following table shows the JAXB mapping annotations that can be associated with each program element.

Program Element JAXB annotation
Package
XmlAccessorOrder
XmlAccessorType
XmlSchema
XmlSchemaType
XmlSchemaTypes
XmlJavaTypeAdapter
XmlJavaTypeAdapters
Class
XmlAccessorOrder
XmlAccessorType
XmlInlineBinaryData
XmlRootElement
XmlType
XmlJavaTypeAdapter
Enum type
XmlEnum
XmlEnumValue (enum constant only)
XmlRootElement
XmlType
XmlJavaTypeAdapter
JavaBean Property/field
XmlElement
XmlElements
XmlElementRef
XmlElementRefs
XmlElementWrapper
XmlAnyElement
XmlAttribute
XmlAnyAttribute
XmlTransient
XmlValue
XmlID
XmlIDREF
XmlList
XmlMixed
XmlMimeType
XmlAttachmentRef
XmlInlineBinaryData
XmlElementDecl (only on method)
XmlJavaTypeAdapter
Parameter
XmlList
XmlAttachmentRef
XmlMimeType
XmlJavaTypeAdapter

Terminology

JavaBean property and field: For the purposes of mapping, there is no semantic difference between a field and a JavaBean property. Thus, an annotation that can be applied to a JavaBean property can always be applied to a field. Hence in the Javadoc documentation, for brevity, the term JavaBean property or property is used to mean either JavaBean property or a field. Where required, both are explicitly mentioned.

top level class: For the purpose of mapping, there is no semantic difference between a top level class and a static nested class. Thus, an annotation that can be applied to a top level class, can always be applied to a nested static class. Hence in the Javadoc documentation, for brevity, the term "top level class" or just class is used to mean either a top level class or a nested static class.

mapping annotation:A JAXB 2.0 defined program annotation based on the JSR 175 programming annotation facility.

Common Usage Constraints

The following usage constraints are defined here since they apply to more than annotation:

  • For a property, a given annotation can be applied to either read or write property but not both.
  • A property name must be different from any other property name in any of the super classes of the class being mapped.
  • A mapped field name or the decapitalized name of a mapped property must be unique within a class.

Notations

Namespace prefixes

The following namespace prefixes are used in the XML Schema fragments in this package.

Prefix | Namespace | Notes
xs | http://www.w3.org/2001/XMLSchema | Namespace of XML Schema namespace
ref | http://ws-i.org/profiles/basic/1.1/xsd | Namespace for swaref schema component
xsi | http://www.w3.org/2001/XMLSchema-instance | XML Schema namespace for instances

Since:
JAXB 2.0
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.bind.annotation Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.bind.annotation

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.bind.annotation.W3CDomHandler (implements javax.xml.bind.annotation.DomHandler<ElementT,ResultT>)
    • javax.xml.bind.annotation.XmlElement.DEFAULT
    • javax.xml.bind.annotation.XmlElementDecl.GLOBAL
    • javax.xml.bind.annotation.XmlElementRef.DEFAULT
    • javax.xml.bind.annotation.XmlSchemaType.DEFAULT
    • javax.xml.bind.annotation.XmlType.DEFAULT

Interface Hierarchy

  • javax.xml.bind.annotation.DomHandler<ElementT,ResultT>

Annotation Type Hierarchy

  • javax.xml.bind.annotation.XmlValue (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlType (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlTransient (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlSchemaTypes (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlSchemaType (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlSchema (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlRootElement (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlRegistry (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlNs (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlMixed (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlMimeType (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlList (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlInlineBinaryData (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlIDREF (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlID (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlEnumValue (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlEnum (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlElements (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlElementWrapper (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlElementRefs (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlElementRef (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlElementDecl (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlElement (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlAttribute (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlAttachmentRef (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlAnyElement (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlAnyAttribute (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlAccessorType (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.XmlAccessorOrder (implements java.lang.annotation.Annotation)

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • javax.xml.bind.annotation.XmlNsForm
      • javax.xml.bind.annotation.XmlAccessType
      • javax.xml.bind.annotation.XmlAccessOrder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.bind.annotation

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.bind.annotation

Packages that use javax.xml.bind.annotation
javax.xml.bind.annotation Defines annotations for customizing Java program elements to XML Schema mapping.

Classes in javax.xml.bind.annotation used by javax.xml.bind.annotation
DomHandler
Converts an element (and its descendants) from/to DOM (or similar) representation.
XmlAccessOrder
Used by XmlAccessorOrder to control the ordering of properties and fields in a JAXB bound class.
XmlAccessType
Used by XmlAccessorType to control serialization of fields or properties.
XmlNsForm
Enumeration of XML Schema namespace qualifications.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


XmlAnyAttribute

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlAnyAttribute

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD})
public @interface XmlAnyAttribute

Maps a JavaBean property to a map of wildcard attributes.

Usage

The @XmlAnyAttribute annotation can be used with the following program elements:

  • JavaBean property
  • non static, non transient field

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

The usage is subject to the following constraints:
  • At most one field or property in a class can be annotated with @XmlAnyAttribute.
  • The type of the property or the field must java.util.Map

While processing attributes to be unmarshalled into a value class, each attribute that is not statically associated with another JavaBean property, via XmlAttribute, is entered into the wildcard attribute map represented by Map<QName,Object>. The attribute QName is the map's key. The key's value is the String value of the attribute.

Since:
JAXB2.0

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlAttachmentRef

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlAttachmentRef

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD,PARAMETER})
public @interface XmlAttachmentRef

Marks a field/property that its XML form is a uri reference to mime content. The mime content is optimally stored out-of-line as an attachment. A field/property must always map to the DataHandler class.

Usage

 @XmlRootElement
 class Foo {
   @XmlAttachmentRef
   @XmlAttribute
   DataHandler data;

   @XmlAttachmentRef
   @XmlElement
   DataHandler body;
 }
The above code maps to the following XML:

 <xs:element name="foo" xmlns:ref="http://ws-i.org/profiles/basic/1.1/xsd">
   <xs:complexType>
     <xs:sequence>
       <xs:element name="body" type="ref:swaRef" minOccurs="0" />
     </xs:sequence>
     <xs:attribute name="data" type="ref:swaRef" use="optional" />
   </xs:complexType>
 </xs:element>

The above binding supports WS-I AP 1.0 WS-I Attachments Profile Version 1.0.

Since:
JAXB2.0

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlID

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlID

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD})
public @interface XmlID

Maps a JavaBean property to XML ID.

To preserve referential integrity of an object graph across XML serialization followed by a XML deserialization, requires an object reference to be marshalled by reference or containment appropriately. Annotations @XmlID and @XmlIDREF together allow a customized mapping of a JavaBean property's type by containment or reference.

Usage

The @XmlID annotation can be used with the following program elements:
  • a JavaBean property
  • non static, non transient field

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

The usage is subject to the following constraints:
  • At most one field or property in a class can be annotated with @XmlID.
  • The JavaBean property's type must be java.lang.String.
  • The only other mapping annotations that can be used with @XmlID are:@XmlElement and @XmlAttribute.

Example: Map a JavaBean property's type to xs:ID

    // Example: code fragment
    public class Customer {
        @XmlAttribute
        @XmlID
        public String getCustomerID();
        public void setCustomerID(String id);
        .... other properties not shown
    }

    <!-- Example: XML Schema fragment -->
    <xs:complexType name="Customer">
      <xs:complexContent>
        <xs:sequence>
          ....
        </xs:sequence>
        <xs:attribute name="customerID" type="xs:ID"/>
      </xs:complexContent>
    </xs:complexType>

Since:
JAXB2.0
See Also:
XmlIDREF

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlIDREF

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlIDREF

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD})
public @interface XmlIDREF

Maps a JavaBean property to XML IDREF.

To preserve referential integrity of an object graph across XML serialization followed by a XML deserialization, requires an object reference to be marshalled by reference or containment appropriately. Annotations @XmlID and @XmlIDREF together allow a customized mapping of a JavaBean property's type by containment or reference.

Usage

The @XmlIDREF annotation can be used with the following program elements:
  • a JavaBean property
  • non static, non transient field

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

The usage is subject to the following constraints:

  • If the type of the field or property is a collection type, then the collection item type must contain a property or field annotated with @XmlID.
  • If the field or property is single valued, then the type of the property or field must contain a property or field annotated with @XmlID.

    Note: If the collection item type or the type of the property (for non collection type) is java.lang.Object, then the instance must contain a property/field annotated with @XmlID attribute.

  • This annotation can be used with the following annotations: XmlElement, XmlAttribute, XmlList, and XmlElements.

Example: Map a JavaBean property to xs:IDREF (i.e. by reference rather than by containment)

   //EXAMPLE: Code fragment
   public class Shipping {
       @XmlIDREF public Customer getCustomer();
       public void setCustomer(Customer customer);
       ....
    }

   <!-- Example: XML Schema fragment -->
   <xs:complexType name="Shipping">
     <xs:complexContent>
       <xs:sequence>
         <xs:element name="customer" type="xs:IDREF"/>
         ....
       </xs:sequence>
     </xs:complexContent>
   </xs:complexType>

Example 2: The following is a complete example of containment versus reference.

    // By default, Customer maps to complex type xs:Customer
    public class Customer {

        // map JavaBean property type to xs:ID
        @XmlID public String getCustomerID();
        public void setCustomerID(String id);

        // .... other properties not shown
    }

   // By default, Invoice maps to a complex type xs:Invoice
   public class Invoice {

       // map by reference
       @XmlIDREF public Customer getCustomer();
       public void setCustomer(Customer customer);

      // .... other properties not shown here
   }

   // By default, Shipping maps to complex type xs:Shipping
   public class Shipping {

       // map by reference
       @XmlIDREF public Customer getCustomer();
       public void setCustomer(Customer customer);
   }

   // at least one class must reference Customer by containment;
   // Customer instances won't be marshalled.
   @XmlElement(name="CustomerData")
   public class CustomerData {
       // map reference to Customer by containment by default.
       public Customer getCustomer();

       // maps reference to Shipping by containment by default.
       public Shipping getShipping();

       // maps reference to Invoice by containment by default.
       public Invoice getInvoice();
   }

   <!-- XML Schema mapping for above code frament -->

   <xs:complexType name="Invoice">
     <xs:complexContent>
       <xs:sequence>
         <xs:element name="customer" type="xs:IDREF"/>
         ....
       </xs:sequence>
     </xs:complexContent>
   </xs:complexType>

   <xs:complexType name="Shipping">
     <xs:complexContent>
       <xs:sequence>
         <xs:element name="customer" type="xs:IDREF"/>
         ....
       </xs:sequence>
     </xs:complexContent>
   </xs:complexType>

   <xs:complexType name="Customer">
     <xs:complexContent>
       <xs:sequence>
         ....
       </xs:sequence>
       <xs:attribute name="CustomerID" type="xs:ID"/>
     </xs:complexContent>
   </xs:complexType>

   <xs:complexType name="CustomerData">
     <xs:complexContent>
       <xs:sequence>
         <xs:element name="customer" type="xs:Customer"/>
         <xs:element name="shipping" type="xs:Shipping"/>
         <xs:element name="invoice"  type="xs:Invoice"/>
       </xs:sequence>
     </xs:complexContent>
   </xs:complexType>

   <xs:element name"customerData" type="xs:CustomerData"/>

   <!-- Instance document conforming to the above XML Schema -->
    <customerData>
       <customer customerID="Alice">
           ....
       </customer>

       <shipping customer="Alice">
           ....
       </shipping>

       <invoice customer="Alice">
           ....
       </invoice>
   </customerData>

Example 3: Mapping List to repeating element of type IDREF

     // Code fragment
     public class Shipping {
         @XmlIDREF
         @XmlElement(name="Alice")
             public List customers;
     }

     <!-- XML schema fragment -->
     <xs:complexType name="Shipping">
       <xs:sequence>
         <xs:choice minOccurs="0" maxOccurs="unbounded">
           <xs:element name="Alice" type="xs:IDREF"/>
         </xs:choice>
       </xs:sequence>
     </xs:complexType>

Example 4: Mapping a List to a list of elements of type IDREF.

     //Code fragment
     public class Shipping {
         @XmlIDREF
         @XmlElements(
             @XmlElement(name="Alice", type="Customer.class")
              @XmlElement(name="John", type="InternationalCustomer.class")
         public List customers;
     }

     <!-- XML Schema fragment -->
     <xs:complexType name="Shipping">
       <xs:sequence>
         <xs:choice minOccurs="0" maxOccurs="unbounded">
           <xs:element name="Alice" type="xs:IDREF"/>
           <xs:element name="John" type="xs:IDREF"/>
         </xs:choice>
       </xs:sequence>
     </xs:complexType>

Since:
JAXB2.0
See Also:
XmlID

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlInlineBinaryData

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlInlineBinaryData

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD,TYPE})
public @interface XmlInlineBinaryData

Disable consideration of XOP encoding for datatypes that are bound to base64-encoded binary data in XML.

When XOP encoding is enabled as described in AttachmentMarshaller.isXOPPackage(), this annotation disables datatypes such as Image or Source or byte[] that are bound to base64-encoded binary from being considered for XOP encoding. If a JAXB property is annotated with this annotation or if the JAXB property's base type is annotated with this annotation, neither AttachmentMarshaller.addMtomAttachment(DataHandler, String, String) nor AttachmentMarshaller.addMtomAttachment(byte[], int, int, String, String, String) is ever called for the property. The binary data will always be inlined.

Since:
JAXB2.0

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlList

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlList

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD,PARAMETER})
public @interface XmlList

Used to map a property to a list simple type.

Usage

The @XmlList annotation can be used with the following program elements:

  • JavaBean property
  • field

When a collection property is annotated just with @XmlElement, each item in the collection will be wrapped by an element. For example,

 @XmlRootElement
 class Foo {
     @XmlElement
     List<String> data;
 }
would produce XML like this:

 <foo>
   <data>abc</data>
   <data>def</data>
 </foo>
@XmlList annotation, on the other hand, allows multiple values to be represented as whitespace-separated tokens in a single element. For example,
 @XmlRootElement
 class Foo {
     @XmlElement
     @XmlList
     List<String> data;
 }
the above code will produce XML like this:

 <foo>
   <data>abc def</data>
 </foo>

This annotation can be used with the following annotations: XmlElement, XmlAttribute, XmlValue, XmlIDREF.

  • The use of @XmlList with XmlValue while allowed, is redundant since XmlList maps a collection type to a simple schema type that derives by list just as XmlValue would.
  • The use of @XmlList with XmlAttribute while allowed, is redundant since XmlList maps a collection type to a simple schema type that derives by list just as XmlAttribute would.

Since:
JAXB2.0

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlMixed

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlMixed

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD})
public @interface XmlMixed

Annotate a JavaBean multi-valued property to support mixed content.

The usage is subject to the following constraints:

  • can be used with @XmlElementRef, @XmlElementRefs or @XmlAnyElement

The following can be inserted into @XmlMixed annotated multi-valued property

  • XML text information items are added as values of java.lang.String.
  • Children element information items are added as instances of JAXBElement or instances with a class that is annotated with @XmlRootElement.
  • Unknown content that is not be bound to a JAXB mapped class is inserted as Element. (Assumes property annotated with @XmlAnyElement)
Below is an example of binding and creation of mixed content.

  <!-- schema fragment having  mixed content -->
  <xs:complexType name="letterBody" mixed="true">
    <xs:sequence>
        <xs:element name="name" type="xs:string" />
        <xs:element name="quantity" type="xs:positiveInteger" />
        <xs:element name="productName" type="xs:string" />
        <!-- etc. -->
    </xs:sequence>
  </xs:complexType>
  <xs:element name="letterBody" type="letterBody" />

 // Schema-derived Java code:
 // (Only annotations relevant to mixed content are shown below,
 //  others are ommitted.)
 import java.math.BigInteger;
 public class ObjectFactory {
        // element instance factories
        JAXBElement<LetterBody> createLetterBody(LetterBody value);
        JAXBElement<String>     createLetterBodyName(String value);
        JAXBElement<BigInteger> createLetterBodyQuantity(BigInteger value);
        JAXBElement<String>     createLetterBodyProductName(String value);
      // type instance factory
        LetterBody&gt; createLetterBody();
 }

 public class LetterBody {
        // Mixed content can contain instances of Element classes
        // Name, Quantity and ProductName. Text data is represented as
        // java.util.String for text.
        @XmlMixed
        @XmlElementRefs({
                @XmlElementRef(name="productName", type=JAXBElement.class),
                @XmlElementRef(name="quantity", type=JAXBElement.class),
                @XmlElementRef(name="name", type=JAXBElement.class)})
        List getContent(){...}
 }
The following is an XML instance document with mixed content

 <letterBody>
 Dear Mr.<name>Robert Smith</name>
 Your order of <quantity>1</quantity> <productName>Baby
 Monitor</productName> shipped from our warehouse. ....
 </letterBody>
that can be constructed using following JAXB API calls.

 LetterBody lb = ObjectFactory.createLetterBody();
 JAXBElement<LetterBody> lbe = ObjectFactory.createLetterBody(lb);
 List gcl = lb.getContent();  //add mixed content to general content property.
 gcl.add("Dear Mr.");  // add text information item as a String.

 // add child element information item
 gcl.add(ObjectFactory.createLetterBodyName("Robert Smith"));
 gcl.add("Your order of "); // add text information item as a String

 // add children element information items
 gcl.add(ObjectFactory.
                        createLetterBodyQuantity(new BigInteger("1")));
 gcl.add(ObjectFactory.createLetterBodyProductName("Baby Monitor"));
 gcl.add("shipped from our warehouse");  // add text information item

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

Since:
JAXB2.0

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlRegistry

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlRegistry

@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface XmlRegistry

Marks a class that has XmlElementDecls.

Since:
JAXB 2.0
See Also:
XmlElementDecl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlTransient

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlTransient

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD})
public @interface XmlTransient

Prevents the mapping of a JavaBean property to XML representation.

The @XmlTransient annotation is useful for resolving name collisions between a JavaBean property name and a field name or preventing the mapping of a field/property. A name collision can occur when the decapitalized JavaBean property name and a field name are the same. If the JavaBean property refers to the field, then the name collision can be resolved by preventing the mapping of either the field or the JavaBean property using the @XmlTransient annotation.

Usage

The @XmlTransient annotation can be used with the following program elements:

  • a JavaBean property
  • field

@XmlTransientis mutually exclusive with all other JAXB defined annotations.

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

Example: Resolve name collision between JavaBean property and field name

   // Example: Code fragment
   public class USAddress {

       // The field name "name" collides with the property name
       // obtained by bean decapitalization of getName() below
       @XmlTransient public String name;

       String getName() {..};
       String setName() {..};
   }

   <!-- Example: XML Schema fragment -->
   <xs:complexType name="USAddress">
     <xs:sequence>
       <xs:element name="name" type="xs:string"/>
     </xs:sequence>
   </xs:complexType>

Since:
JAXB2.0

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlValue

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL | DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlValue

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD})
public @interface XmlValue

Enables mapping a class to a XML Schema complex type with a simpleContent or a XML Schema simple type.

Usage:

The @XmlValue annotation can be used with the following program elements:

  • a JavaBean property.
  • non static, non transient field.

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

The usage is subject to the following usage constraints:
  • At most one field or property can be annotated with the @XmlValue annotation.
  • @XmlValue can be used with the following annotations: XmlList. However this is redundant since XmlList maps a type to a simple schema type that derives by list just as XmlValue would.
  • If the type of the field or property is a collection type, then the collection item type must map to a simple schema type.
  • If the type of the field or property is not a collection type, then the type must map to a XML Schema simple type.

If the annotated JavaBean property is the sole class member being mapped to XML Schema construct, then the class is mapped to a simple type. If there are additional JavaBean properties (other than the JavaBean property annotated with @XmlValue annotation) that are mapped to XML attributes, then the class is mapped to a complex type with simpleContent.

Example 1: Map a class to XML Schema simpleType

     // Example 1: Code fragment
     public class USPrice {
         @XmlValue
         public java.math.BigDecimal price;
     }

     <!-- Example 1: XML Schema fragment -->
     <xs:simpleType name="USPrice">
       <xs:restriction base="xs:decimal"/>
     </xs:simpleType>

Example 2: Map a class to XML Schema complexType with with simpleContent.

   // Example 2: Code fragment
   public class InternationalPrice {
       @XmlValue
       public java.math.BigDecimal price;

       @XmlAttribute
       public String currency;
   }

   <!-- Example 2: XML Schema fragment -->
   <xs:complexType name="InternationalPrice">
     <xs:simpleContent>
       <xs:extension base="xs:decimal">
         <xs:attribute name="currency" type="xs:string"/>
       </xs:extension>
     </xs:simpleContent>
   </xs:complexType>

Since:
JAXB2.0
See Also:
XmlType

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL | DETAIL: ELEMENT


adapters

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.bind.annotation.adapters

XmlAdapter and its spec-defined sub-classes to allow arbitrary Java classes to be used with JAXB.

See:
Description

Class Summary
CollapsedStringAdapter | Built-in XmlAdapter to handle xs:token and its derived types.
HexBinaryAdapter | XmlAdapter for xs:hexBinary.
NormalizedStringAdapter | XmlAdapter to handle xs:normalizedString.
XmlAdapter<ValueType,BoundType> | Adapts a Java type for custom marshaling.
XmlJavaTypeAdapter.DEFAULT | Used in XmlJavaTypeAdapter.type() to signal that the type be inferred from the signature of the field, property, parameter or the class.

Annotation Types Summary
XmlJavaTypeAdapter | Use an adapter that implements XmlAdapter for custom marshaling.
XmlJavaTypeAdapters | A container for multiple @XmlJavaTypeAdapter annotations.

Package javax.xml.bind.annotation.adapters Description

XmlAdapter and its spec-defined sub-classes to allow arbitrary Java classes to be used with JAXB.

Package Specification

  • JAXB Specification

Related Documentation

For overviews, tutorials, examples, guides, and tool documentation, please see:
  • The JAXB Website

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.bind.annotation.adapters Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.bind.annotation.adapters

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.bind.annotation.adapters.XmlAdapter<ValueType,BoundType>
      • javax.xml.bind.annotation.adapters.CollapsedStringAdapter
      • javax.xml.bind.annotation.adapters.HexBinaryAdapter
      • javax.xml.bind.annotation.adapters.NormalizedStringAdapter
    • javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter.DEFAULT

Annotation Type Hierarchy

  • javax.xml.bind.annotation.adapters.XmlJavaTypeAdapters (implements java.lang.annotation.Annotation)
  • javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter (implements java.lang.annotation.Annotation)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.bind.annotation.adapters

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.bind.annotation.adapters

Packages that use javax.xml.bind.annotation.adapters
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.annotation.adapters | XmlAdapter and its spec-defined sub-classes to allow arbitrary Java classes to be used with JAXB.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

Classes in javax.xml.bind.annotation.adapters used by javax.xml.bind
XmlAdapter
Adapts a Java type for custom marshaling.

Classes in javax.xml.bind.annotation.adapters used by javax.xml.bind.annotation.adapters
XmlAdapter
Adapts a Java type for custom marshaling.

Classes in javax.xml.bind.annotation.adapters used by javax.xml.bind.helpers
XmlAdapter
Adapts a Java type for custom marshaling.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.adapters.CollapsedStringAdapter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.adapters.CollapsedStringAdapter

No usage of javax.xml.bind.annotation.adapters.CollapsedStringAdapter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.adapters.HexBinaryAdapter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.adapters.HexBinaryAdapter

No usage of javax.xml.bind.annotation.adapters.HexBinaryAdapter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.adapters.NormalizedStringAdapter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.adapters.NormalizedStringAdapter

No usage of javax.xml.bind.annotation.adapters.NormalizedStringAdapter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.adapters.XmlAdapter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.adapters.XmlAdapter

Packages that use XmlAdapter
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.annotation.adapters | XmlAdapter and its spec-defined sub-classes to allow arbitrary Java classes to be used with JAXB.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

Uses of XmlAdapter in javax.xml.bind

Methods in javax.xml.bind with type parameters of type XmlAdapter
<A extends XmlAdapter>
A
Marshaller.getAdapter(Class<A> type)
Gets the adapter associated with the specified type.
<A extends XmlAdapter>
A
Unmarshaller.getAdapter(Class<A> type)
Gets the adapter associated with the specified type.
<A extends XmlAdapter>
void
Marshaller.setAdapter(Class<A> type, A adapter)
Associates a configured instance of XmlAdapter with this marshaller.
<A extends XmlAdapter>
void
Unmarshaller.setAdapter(Class<A> type, A adapter)
Associates a configured instance of XmlAdapter with this unmarshaller.

Methods in javax.xml.bind with parameters of type XmlAdapter
void | Marshaller.setAdapter(XmlAdapter adapter) Associates a configured instance of XmlAdapter with this marshaller.
void | Unmarshaller.setAdapter(XmlAdapter adapter) Associates a configured instance of XmlAdapter with this unmarshaller.

Uses of XmlAdapter in javax.xml.bind.annotation.adapters

Subclasses of XmlAdapter in javax.xml.bind.annotation.adapters
class | CollapsedStringAdapter Built-in XmlAdapter to handle xs:token and its derived types.
class | HexBinaryAdapter XmlAdapter for xs:hexBinary.
class | NormalizedStringAdapter XmlAdapter to handle xs:normalizedString.

Uses of XmlAdapter in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers with type parameters of type XmlAdapter
<A extends XmlAdapter>
A
AbstractUnmarshallerImpl.getAdapter(Class<A> type)
<A extends XmlAdapter>
A
AbstractMarshallerImpl.getAdapter(Class<A> type)
<A extends XmlAdapter>
void
AbstractUnmarshallerImpl.setAdapter(Class<A> type, A adapter)
<A extends XmlAdapter>
void
AbstractMarshallerImpl.setAdapter(Class<A> type, A adapter)

Methods in javax.xml.bind.helpers with parameters of type XmlAdapter
void | AbstractUnmarshallerImpl.setAdapter(XmlAdapter adapter)
void | AbstractMarshallerImpl.setAdapter(XmlAdapter adapter)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter

No usage of javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter.DEFAULT

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter.DEFAULT

No usage of javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter.DEFAULT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.adapters.XmlJavaTypeAdapters

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.adapters.XmlJavaTypeAdapters

No usage of javax.xml.bind.annotation.adapters.XmlJavaTypeAdapters

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


CollapsedStringAdapter

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.annotation.adapters
Class CollapsedStringAdapter

java.lang.Object
    extended by  javax.xml.bind.annotation.adapters.XmlAdapter<String,String>
        extended by  javax.xml.bind.annotation.adapters.CollapsedStringAdapter

public class CollapsedStringAdapter
extends XmlAdapter<String,String>

Built-in XmlAdapter to handle xs:token and its derived types.

This adapter removes leading and trailing whitespaces, then truncate any sequnce of tab, CR, LF, and SP by a single whitespace character ' '.

Since:
JAXB 2.0

Constructor Summary
CollapsedStringAdapter()
Method Summary
protected static boolean | isWhiteSpace(char ch) returns true if the specified char is a white space character.
String | marshal(String s) No-op.
String | unmarshal(String text) Removes leading and trailing whitespaces of the string given as the parameter, then truncate any sequnce of tab, CR, LF, and SP by a single whitespace character ' '.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CollapsedStringAdapter

public CollapsedStringAdapter()
Method Detail

unmarshal

public String unmarshal(String text)
Removes leading and trailing whitespaces of the string given as the parameter, then truncate any sequnce of tab, CR, LF, and SP by a single whitespace character ' '.

Specified by:
unmarshal in class XmlAdapter<String,String>
Parameters:
text - The value to be converted. Can be null.

marshal

public String marshal(String s)
No-op. Just return the same string given as the parameter.

Specified by:
marshal in class XmlAdapter<String,String>
Parameters:
s - The value to be convereted. Can be null.

isWhiteSpace

protected static boolean isWhiteSpace(char ch)
returns true if the specified char is a white space character.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


HexBinaryAdapter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.annotation.adapters
Class HexBinaryAdapter

java.lang.Object
    extended by  javax.xml.bind.annotation.adapters.XmlAdapter<String,byte[]>
        extended by  javax.xml.bind.annotation.adapters.HexBinaryAdapter

public final class HexBinaryAdapter
extends XmlAdapter<String,byte[]>

XmlAdapter for xs:hexBinary.

This XmlAdapter binds byte[] to the hexBinary representation in XML.

Since:
JAXB 2.0

Constructor Summary
HexBinaryAdapter()
Method Summary
String | marshal(byte[] bytes) Convert a bound type to a value type.
byte[] | unmarshal(String s) Convert a value type to a bound type.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HexBinaryAdapter

public HexBinaryAdapter()
Method Detail

unmarshal

public byte[] unmarshal(String s)
Description copied from class: XmlAdapter
Convert a value type to a bound type.

Specified by:
unmarshal in class XmlAdapter<String,byte[]>
Parameters:
s - The value to be converted. Can be null.

marshal

public String marshal(byte[] bytes)
Description copied from class: XmlAdapter
Convert a bound type to a value type.

Specified by:
marshal in class XmlAdapter<String,byte[]>
Parameters:
bytes - The value to be convereted. Can be null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NormalizedStringAdapter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.annotation.adapters
Class NormalizedStringAdapter

java.lang.Object
    extended by  javax.xml.bind.annotation.adapters.XmlAdapter<String,String>
        extended by  javax.xml.bind.annotation.adapters.NormalizedStringAdapter

public final class NormalizedStringAdapter
extends XmlAdapter<String,String>

XmlAdapter to handle xs:normalizedString.

This adapter removes leading and trailing whitespaces, then replace any tab, CR, and LF by a whitespace character ' '.

Since:
JAXB 2.0

Constructor Summary
NormalizedStringAdapter()
Method Summary
protected static boolean | isWhiteSpaceExceptSpace(char ch) Returns true if the specified char is a white space character but not 0x20.
String | marshal(String s) No-op.
String | unmarshal(String text) Removes leading and trailing whitespaces of the string given as the parameter, then replace any tab, CR, and LF by a whitespace character ' '.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NormalizedStringAdapter

public NormalizedStringAdapter()
Method Detail

unmarshal

public String unmarshal(String text)
Removes leading and trailing whitespaces of the string given as the parameter, then replace any tab, CR, and LF by a whitespace character ' '.

Specified by:
unmarshal in class XmlAdapter<String,String>
Parameters:
text - The value to be converted. Can be null.

marshal

public String marshal(String s)
No-op. Just return the same string given as the parameter.

Specified by:
marshal in class XmlAdapter<String,String>
Parameters:
s - The value to be convereted. Can be null.

isWhiteSpaceExceptSpace

protected static boolean isWhiteSpaceExceptSpace(char ch)
Returns true if the specified char is a white space character but not 0x20.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XmlAdapter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.annotation.adapters
Class XmlAdapter<ValueType,BoundType>

java.lang.Object
    extended by  javax.xml.bind.annotation.adapters.XmlAdapter<ValueType,BoundType>
Type Parameters:
BoundType - The type that JAXB doesn't know how to handle. An adapter is written to allow this type to be used as an in-memory representation through the ValueType.
ValueType - The type that JAXB knows how to handle out of the box.
Direct Known Subclasses:
CollapsedStringAdapter, HexBinaryAdapter, NormalizedStringAdapter
public abstract class XmlAdapter<ValueType,BoundType>
extends Object

Adapts a Java type for custom marshaling.

Usage:

Some Java types do not map naturally to a XML representation, for example HashMap or other non JavaBean classes. Conversely, a XML repsentation may map to a Java type but an application may choose to accesss the XML representation using another Java type. For example, the schema to Java binding rules bind xs:DateTime by default to XmlGregorianCalendar. But an application may desire to bind xs:DateTime to a custom type, MyXmlGregorianCalendar, for example. In both cases, there is a mismatch between bound type , used by an application to access XML content and the value type, that is mapped to an XML representation.

This abstract class defines methods for adapting a bound type to a value type or vice versa. The methods are invoked by the JAXB binding framework during marshaling and unmarshalling:

  • XmlAdapter.marshal(...): During marshalling, JAXB binding framework invokes XmlAdapter.marshal(..) to adapt a bound type to value type, which is then marshaled to XML representation.
  • XmlAdapter.unmarshal(...): During unmarshalling, JAXB binding framework first unmarshals XML representation to a value type and then invokes XmlAdapter.unmarshal(..) to adapt the value type to a bound type.
Writing an adapter therefore involves the following steps:
  • Write an adapter that implements this abstract class.
  • Install the adapter using the annotation XmlJavaTypeAdapter

Example: Customized mapping of HashMap

The following example illustrates the use of @XmlAdapter and @XmlJavaTypeAdapter to customize the mapping of a HashMap.

Step 1: Determine the desired XML representation for HashMap.

     <hashmap>
         <entry key="id123">this is a value</entry>
         <entry key="id312">this is another value</entry>
         ...
       </hashmap>

Step 2: Determine the schema definition that the desired XML representation shown above should follow.

     <xs:complexType name="myHashMapType">
       <xs:sequence>
         <xs:element name="entry" type="myHashMapEntryType"
                        minOccurs = "0" maxOccurs="unbounded"/>
       </xs:sequence>
     </xs:complexType>

     <xs:complexType name="myHashMapEntryType">
       <xs:simpleContent>
         <xs:extension base="xs:string">
           <xs:attribute name="key" type="xs:int"/>
         </xs:extension>
       </xs:simpleContent>
     </xs:complexType>

Step 3: Write value types that can generate the above schema definition.

     public class MyHashMapType {
         List<MyHashMapEntryType> entry;
     }

     public class MyHashMapEntryType {
         @XmlAttribute
         public Integer key;

         @XmlValue
         public String value;
     }

Step 4: Write the adapter that adapts the value type, MyHashMapType to a bound type, HashMap, used by the application.

     public final class MyHashMapAdapter extends
                        XmlAdapter<HashMap, MyHashMapType> { ... }

Step 5: Use the adapter.

     public class Foo {
         @XmlJavaTypeAdapter(MyHashMapAdapter.class)
         HashMap hashmap;
         ...
     }
The above code fragment will map to the following schema:
     <xs:complexType name="Foo">
       <xs:sequence>
         <xs:element name="hashmap" type="myHashMapType"
       </xs:sequence>
     </xs:complexType>

Since:
JAXB 2.0
See Also:
XmlJavaTypeAdapter

Constructor Summary
protected XmlAdapter()
Do-nothing constructor for the derived classes.
Method Summary
abstract ValueType | marshal(BoundType v) Convert a bound type to a value type.
abstract BoundType | unmarshal(ValueType v) Convert a value type to a bound type.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XmlAdapter

protected XmlAdapter()
Do-nothing constructor for the derived classes.

Method Detail

unmarshal

public abstract BoundType unmarshal(ValueType v)
                             throws Exception
Convert a value type to a bound type.

Parameters:
v - The value to be converted. Can be null.
Throws:
Exception - if there's an error during the conversion. The caller is responsible for reporting the error to the user through ValidationEventHandler.

marshal

public abstract ValueType marshal(BoundType v)
                           throws Exception
Convert a bound type to a value type.

Parameters:
v - The value to be convereted. Can be null.
Throws:
Exception - if there's an error during the conversion. The caller is responsible for reporting the error to the user through ValidationEventHandler.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XmlJavaTypeAdapter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation.adapters
Annotation Type XmlJavaTypeAdapter

@Retention(value=RUNTIME)
@Target(value={PACKAGE,FIELD,METHOD,TYPE,PARAMETER})
public @interface XmlJavaTypeAdapter

Use an adapter that implements XmlAdapter for custom marshaling.

Usage:

The @XmlJavaTypeAdapter annotation can be used with the following program elements:

  • a JavaBean property
  • field
  • parameter
  • package
  • from within XmlJavaTypeAdapters

When @XmlJavaTypeAdapter annotation is defined on a class, it applies to all references to the class.

When @XmlJavaTypeAdapter annotation is defined at the package level it applies to all references from within the package to @XmlJavaTypeAdapter.type().

When @XmlJavaTypeAdapter annotation is defined on the field, property or parameter, then the annotation applies to the field, property or the parameter only.

A @XmlJavaTypeAdapter annotation on a field, property or parameter overrides the @XmlJavaTypeAdapter annotation associated with the class being referenced by the field, property or parameter.

A @XmlJavaTypeAdapter annotation on a class overrides the @XmlJavaTypeAdapter annotation specified at the package level for that class.

This annotation can be used with the following other annotations: XmlElement, XmlAttribute, XmlElementRef, XmlElementRefs, XmlAnyElement. This can also be used at the package level with the following annotations: XmlAccessorType, XmlSchema, XmlSchemaType, XmlSchemaTypes.

Example: See example in XmlAdapter

Since:
JAXB2.0
See Also:
XmlAdapter

Required Element Summary
 Class<? extends XmlAdapter> value
Points to the clsss that converts a value type to a bound type or vice versa.
Optional Element Summary
 Class type
If this annotation is used at the package level, then value of the type() must be specified.

Element Detail

value

public abstract Class<? extends XmlAdapter> value
Points to the clsss that converts a value type to a bound type or vice versa. See XmlAdapter for more details.

type

public abstract Class type
If this annotation is used at the package level, then value of the type() must be specified.

Default:
javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter.DEFAULT.class
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlJavaTypeAdapter.DEFAULT

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.annotation.adapters
Class XmlJavaTypeAdapter.DEFAULT

java.lang.Object
    extended by  javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter.DEFAULT
Enclosing class:
XmlJavaTypeAdapter
public static final class XmlJavaTypeAdapter.DEFAULT
extends Object

Used in XmlJavaTypeAdapter.type() to signal that the type be inferred from the signature of the field, property, parameter or the class.

Constructor Summary
XmlJavaTypeAdapter.DEFAULT()
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XmlJavaTypeAdapter.DEFAULT

public XmlJavaTypeAdapter.DEFAULT()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XmlJavaTypeAdapters

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL | DETAIL: ELEMENT

javax.xml.bind.annotation.adapters
Annotation Type XmlJavaTypeAdapters

@Retention(value=RUNTIME)
@Target(value=PACKAGE)
public @interface XmlJavaTypeAdapters

A container for multiple @XmlJavaTypeAdapter annotations.

Multiple annotations of the same type are not allowed on a program element. This annotation therefore serves as a container annotation for multiple @XmlJavaTypeAdapter as follows:

 @XmlJavaTypeAdapters ({ @XmlJavaTypeAdapter(...),@XmlJavaTypeAdapter(...) })

The @XmlJavaTypeAdapters annnotation is useful for defining XmlJavaTypeAdapter annotations for different types at the package level.

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

Since:
JAXB2.0
See Also:
XmlJavaTypeAdapter

Required Element Summary
 XmlJavaTypeAdapter[] value
Collection of @XmlJavaTypeAdapter annotations

Element Detail

value

public abstract XmlJavaTypeAdapter[] value
Collection of @XmlJavaTypeAdapter annotations

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL | DETAIL: ELEMENT


Uses of Class javax.xml.bind.annotation.W3CDomHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.W3CDomHandler

No usage of javax.xml.bind.annotation.W3CDomHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlAccessOrder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlAccessOrder

Packages that use XmlAccessOrder
javax.xml.bind.annotation Defines annotations for customizing Java program elements to XML Schema mapping.

Uses of XmlAccessOrder in javax.xml.bind.annotation

Methods in javax.xml.bind.annotation that return XmlAccessOrder
static XmlAccessOrder | XmlAccessOrder.valueOf(String name) Returns the enum constant of this type with the specified name.
static XmlAccessOrder[] | XmlAccessOrder.values() Returns an array containing the constants of this enum type, in the order they are declared.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlAccessorOrder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlAccessorOrder

No usage of javax.xml.bind.annotation.XmlAccessorOrder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlAccessorType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlAccessorType

No usage of javax.xml.bind.annotation.XmlAccessorType

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlAccessType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlAccessType

Packages that use XmlAccessType
javax.xml.bind.annotation Defines annotations for customizing Java program elements to XML Schema mapping.

Uses of XmlAccessType in javax.xml.bind.annotation

Methods in javax.xml.bind.annotation that return XmlAccessType
static XmlAccessType | XmlAccessType.valueOf(String name) Returns the enum constant of this type with the specified name.
static XmlAccessType[] | XmlAccessType.values() Returns an array containing the constants of this enum type, in the order they are declared.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlAnyAttribute

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlAnyAttribute

No usage of javax.xml.bind.annotation.XmlAnyAttribute

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlAnyElement

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlAnyElement

No usage of javax.xml.bind.annotation.XmlAnyElement

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlAttachmentRef

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlAttachmentRef

No usage of javax.xml.bind.annotation.XmlAttachmentRef

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlAttribute

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlAttribute

No usage of javax.xml.bind.annotation.XmlAttribute

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlElement

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlElement

No usage of javax.xml.bind.annotation.XmlElement

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlElement.DEFAULT

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlElement.DEFAULT

No usage of javax.xml.bind.annotation.XmlElement.DEFAULT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlElementDecl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlElementDecl

No usage of javax.xml.bind.annotation.XmlElementDecl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlElementDecl.GLOBAL

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlElementDecl.GLOBAL

No usage of javax.xml.bind.annotation.XmlElementDecl.GLOBAL

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlElementRef

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlElementRef

No usage of javax.xml.bind.annotation.XmlElementRef

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlElementRef.DEFAULT

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlElementRef.DEFAULT

No usage of javax.xml.bind.annotation.XmlElementRef.DEFAULT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlElementRefs

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlElementRefs

No usage of javax.xml.bind.annotation.XmlElementRefs

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlElements

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlElements

No usage of javax.xml.bind.annotation.XmlElements

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlElementWrapper

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlElementWrapper

No usage of javax.xml.bind.annotation.XmlElementWrapper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlEnum

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlEnum

No usage of javax.xml.bind.annotation.XmlEnum

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlEnumValue

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlEnumValue

No usage of javax.xml.bind.annotation.XmlEnumValue

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlID

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlID

No usage of javax.xml.bind.annotation.XmlID

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlIDREF

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlIDREF

No usage of javax.xml.bind.annotation.XmlIDREF

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlInlineBinaryData

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlInlineBinaryData

No usage of javax.xml.bind.annotation.XmlInlineBinaryData

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlList

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlList

No usage of javax.xml.bind.annotation.XmlList

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlMimeType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlMimeType

No usage of javax.xml.bind.annotation.XmlMimeType

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlMixed

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlMixed

No usage of javax.xml.bind.annotation.XmlMixed

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlNs

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlNs

No usage of javax.xml.bind.annotation.XmlNs

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlNsForm

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlNsForm

Packages that use XmlNsForm
javax.xml.bind.annotation Defines annotations for customizing Java program elements to XML Schema mapping.

Uses of XmlNsForm in javax.xml.bind.annotation

Methods in javax.xml.bind.annotation that return XmlNsForm
static XmlNsForm | XmlNsForm.valueOf(String name) Returns the enum constant of this type with the specified name.
static XmlNsForm[] | XmlNsForm.values() Returns an array containing the constants of this enum type, in the order they are declared.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlRegistry

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlRegistry

No usage of javax.xml.bind.annotation.XmlRegistry

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlRootElement

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlRootElement

No usage of javax.xml.bind.annotation.XmlRootElement

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlSchema

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlSchema

No usage of javax.xml.bind.annotation.XmlSchema

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlSchemaType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlSchemaType

No usage of javax.xml.bind.annotation.XmlSchemaType

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlSchemaType.DEFAULT

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlSchemaType.DEFAULT

No usage of javax.xml.bind.annotation.XmlSchemaType.DEFAULT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlSchemaTypes

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlSchemaTypes

No usage of javax.xml.bind.annotation.XmlSchemaTypes

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlTransient

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlTransient

No usage of javax.xml.bind.annotation.XmlTransient

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlType

No usage of javax.xml.bind.annotation.XmlType

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlType.DEFAULT

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlType.DEFAULT

No usage of javax.xml.bind.annotation.XmlType.DEFAULT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.annotation.XmlValue

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.annotation.XmlValue

No usage of javax.xml.bind.annotation.XmlValue

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.bind.annotation.DomHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.bind.annotation.DomHandler

Packages that use DomHandler
javax.xml.bind.annotation Defines annotations for customizing Java program elements to XML Schema mapping.

Uses of DomHandler in javax.xml.bind.annotation

Classes in javax.xml.bind.annotation that implement DomHandler
 class W3CDomHandler
DomHandler implementation for W3C DOM (org.w3c.dom package.)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DomHandler

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.annotation
Interface DomHandler<ElementT,ResultT extends Result>

All Known Implementing Classes:
W3CDomHandler
public interface DomHandler<ElementT,ResultT extends Result>

Converts an element (and its descendants) from/to DOM (or similar) representation.

Implementations of this interface will be used in conjunction with XmlAnyElement annotation to map an element of XML into a representation of infoset such as W3C DOM.

Implementations hide how a portion of XML is converted into/from such DOM-like representation, allowing JAXB providers to work with arbitrary such library.

This interface is intended to be implemented by library writers and consumed by JAXB providers. None of those methods are intended to be called from applications.

Since:
JAXB2.0

Method Summary
ResultT | createUnmarshaller(ValidationEventHandler errorHandler) When a JAXB provider needs to unmarshal a part of a document into an infoset representation, it first calls this method to create a Result object.
ElementT | getElement(ResultT rt) Once the portion is sent to the Result.
Source | marshal(ElementT n, ValidationEventHandler errorHandler) This method is called when a JAXB provider needs to marshal an element to XML.

Method Detail

createUnmarshaller

ResultT createUnmarshaller(ValidationEventHandler errorHandler)
When a JAXB provider needs to unmarshal a part of a document into an infoset representation, it first calls this method to create a Result object.

A JAXB provider will then send a portion of the XML into the given result. Such a portion always form a subtree of the whole XML document rooted at an element.

Parameters:
errorHandler - if any error happens between the invocation of this method and the invocation of getElement(Result), they must be reported to this handler. The caller must provide a non-null error handler. The Result object created from this method may hold a reference to this error handler.
Returns:
null if the operation fails. The error must have been reported to the error handler.

getElement

ElementT getElement(ResultT rt)
Once the portion is sent to the Result. This method is called by a JAXB provider to obtain the unmarshalled element representation.

Multiple invocations of this method may return different objects. This method can be invoked only when the whole sub-tree are fed to the Result object.

Parameters:
rt - The Result object created by createUnmarshaller(ValidationEventHandler).
Returns:
null if the operation fails. The error must have been reported to the error handler.

marshal

Source marshal(ElementT n,
               ValidationEventHandler errorHandler)
This method is called when a JAXB provider needs to marshal an element to XML.

If non-null, the returned Source must contain a whole document rooted at one element, which will then be weaved into a bigger document that the JAXB provider is marshalling.

Parameters:
errorHandler - Receives any errors happened during the process of converting an element into a Source. The caller must provide a non-null error handler.
Returns:
null if there was an error. The error should have been reported to the handler.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


W3CDomHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.annotation
Class W3CDomHandler

java.lang.Object
    extended by  javax.xml.bind.annotation.W3CDomHandler
All Implemented Interfaces:
DomHandler<Element,DOMResult>
public class W3CDomHandler
extends Object
implements DomHandler<Element,DOMResult>

DomHandler implementation for W3C DOM (org.w3c.dom package.)

Since:
JAXB2.0

Constructor Summary
W3CDomHandler()
Default constructor.
W3CDomHandler(DocumentBuilder builder)
Constructor that allows applications to specify which DOM implementation to be used.
Method Summary
DOMResult | createUnmarshaller(ValidationEventHandler errorHandler) When a JAXB provider needs to unmarshal a part of a document into an infoset representation, it first calls this method to create a Result object.
DocumentBuilder | getBuilder()
Element | getElement(DOMResult r) Once the portion is sent to the Result.
Source | marshal(Element element, ValidationEventHandler errorHandler) This method is called when a JAXB provider needs to marshal an element to XML.
void | setBuilder(DocumentBuilder builder)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

W3CDomHandler

public W3CDomHandler()
Default constructor. It is up to a JAXB provider to decide which DOM implementation to use or how that is configured.

W3CDomHandler

public W3CDomHandler(DocumentBuilder builder)
Constructor that allows applications to specify which DOM implementation to be used.

Parameters:
builder - must not be null. JAXB uses this DocumentBuilder to create a new element.
Method Detail

getBuilder

public DocumentBuilder getBuilder()

setBuilder

public void setBuilder(DocumentBuilder builder)

createUnmarshaller

public DOMResult createUnmarshaller(ValidationEventHandler errorHandler)
Description copied from interface: DomHandler
When a JAXB provider needs to unmarshal a part of a document into an infoset representation, it first calls this method to create a Result object.

A JAXB provider will then send a portion of the XML into the given result. Such a portion always form a subtree of the whole XML document rooted at an element.

Specified by:
createUnmarshaller in interface DomHandler<Element,DOMResult>
Parameters:
errorHandler - if any error happens between the invocation of this method and the invocation of DomHandler.getElement(Result), they must be reported to this handler. The caller must provide a non-null error handler. The Result object created from this method may hold a reference to this error handler.
Returns:
null if the operation fails. The error must have been reported to the error handler.

getElement

public Element getElement(DOMResult r)
Description copied from interface: DomHandler
Once the portion is sent to the Result. This method is called by a JAXB provider to obtain the unmarshalled element representation.

Multiple invocations of this method may return different objects. This method can be invoked only when the whole sub-tree are fed to the Result object.

Specified by:
getElement in interface DomHandler<Element,DOMResult>
Parameters:
r - The Result object created by DomHandler.createUnmarshaller(ValidationEventHandler).
Returns:
null if the operation fails. The error must have been reported to the error handler.

marshal

public Source marshal(Element element,
                      ValidationEventHandler errorHandler)
Description copied from interface: DomHandler
This method is called when a JAXB provider needs to marshal an element to XML.

If non-null, the returned Source must contain a whole document rooted at one element, which will then be weaved into a bigger document that the JAXB provider is marshalling.

Specified by:
marshal in interface DomHandler<Element,DOMResult>
errorHandler - Receives any errors happened during the process of converting an element into a Source. The caller must provide a non-null error handler.
Returns:
null if there was an error. The error should have been reported to the handler.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XmlAccessOrder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.xml.bind.annotation
Enum XmlAccessOrder

java.lang.Object
    extended by  java.lang.Enum<XmlAccessOrder>
        extended by  javax.xml.bind.annotation.XmlAccessOrder
All Implemented Interfaces:
Serializable, Comparable<XmlAccessOrder>
public enum XmlAccessOrder
extends Enum<XmlAccessOrder>

Used by XmlAccessorOrder to control the ordering of properties and fields in a JAXB bound class.

Since:
JAXB2.0
See Also:
XmlAccessorOrder

Enum Constant Summary
ALPHABETICAL
The ordering of fields and properties in a class is in alphabetical order as determined by the method java.lang.String.compareTo(String anotherString).
UNDEFINED
The ordering of fields and properties in a class is undefined.
Method Summary
static XmlAccessOrder | valueOf(String name) Returns the enum constant of this type with the specified name.
static XmlAccessOrder[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

UNDEFINED

public static final XmlAccessOrder UNDEFINED
The ordering of fields and properties in a class is undefined.

ALPHABETICAL

public static final XmlAccessOrder ALPHABETICAL
The ordering of fields and properties in a class is in alphabetical order as determined by the method java.lang.String.compareTo(String anotherString).

Method Detail

values

public static XmlAccessOrder[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (XmlAccessOrder c : XmlAccessOrder.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static XmlAccessOrder valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


XmlAccessorOrder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlAccessorOrder

@Inherited
@Retention(value=RUNTIME)
@Target(value={PACKAGE,TYPE})
public @interface XmlAccessorOrder

Controls the ordering of fields and properties in a class.

Usage

@XmlAccessorOrder annotation can be used with the following program elements:

  • package
  • a top level class

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

The annotation @XmlAccessorOrder on a package applies to all classes in a package. The following inheritance semantics apply:

  • If there is a @XmlAccessorOrder on a class, then it is used.
  • Otherwise, if a @XmlAccessorOrder exists on one of its super classes, then it is inherited.
  • Otherwise, the @XmlAccessorOrder on a package is inherited.

Defaulting Rules:

By default, if @XmlAccessorOrder on a package is absent, then the following package level annotation is assumed.

    @XmlAccessorType(XmlAccessOrder.UNDEFINED)

By default, if @XmlAccessorOrder on a class is absent and none of super classes is annotated with XmlAccessorOrder , then the following default on the class is assumed:

    @XmlAccessorType(XmlAccessOrder.UNDEFINED)

This annotation can be used with the following annotations: XmlType, XmlRootElement, XmlAccessorType, XmlSchema, XmlSchemaType, XmlSchemaTypes, , XmlJavaTypeAdapter. It can also be used with the following annotations at the package level: XmlJavaTypeAdapter.

Since:
JAXB2.0
See Also:
XmlAccessOrder

Optional Element Summary
 XmlAccessOrder value

value

public abstract XmlAccessOrder value
Default:
javax.xml.bind.annotation.XmlAccessOrder.UNDEFINED
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlAccessorType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlAccessorType

@Inherited
@Retention(value=RUNTIME)
@Target(value={PACKAGE,TYPE})
public @interface XmlAccessorType

Controls whether fields or Javabean properties are serialized by default.

Usage

@XmlAccessorType annotation can be used with the following program elements:

  • package
  • a top level class

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

This annotation provides control over the default serialization of properties and fields in a class.

The annotation @XmlAccessorType on a package applies to all classes in the package. The following inheritance semantics apply:

  • If there is a @XmlAccessorType on a class, then it is used.
  • Otherwise, if a @XmlAccessorType exists on one of its super classes, then it is inherited.
  • Otherwise, the @XmlAccessorType on a package is inherited.

Defaulting Rules:

By default, if @XmlAccessorType on a package is absent, then the following package level annotation is assumed.

   @XmlAccessorType(XmlAccessType.PUBLIC_MEMBER)

By default, if @XmlAccessorType on a class is absent, and none of its super classes is annotated with @XmlAccessorType, then the following default on the class is assumed:

   @XmlAccessorType(XmlAccessType.PUBLIC_MEMBER)

This annotation can be used with the following annotations: XmlType, XmlRootElement, XmlAccessorOrder, XmlSchema, XmlSchemaType, XmlSchemaTypes, , XmlJavaTypeAdapter. It can also be used with the following annotations at the package level: XmlJavaTypeAdapter.

Since:
JAXB2.0
See Also:
XmlAccessType

Optional Element Summary
 XmlAccessType value
Specifies whether fields or properties are serialized.

value

public abstract XmlAccessType value
Specifies whether fields or properties are serialized.

See Also:
XmlAccessType
Default:
javax.xml.bind.annotation.XmlAccessType.PUBLIC_MEMBER
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlAccessType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.xml.bind.annotation
Enum XmlAccessType

java.lang.Object
    extended by  java.lang.Enum<XmlAccessType>
        extended by  javax.xml.bind.annotation.XmlAccessType
All Implemented Interfaces:
Serializable, Comparable<XmlAccessType>
public enum XmlAccessType
extends Enum<XmlAccessType>

Used by XmlAccessorType to control serialization of fields or properties.

Since:
JAXB2.0
See Also:
XmlAccessorType

Enum Constant Summary
FIELD
Every non static, non transient field in a JAXB-bound class will be automatically bound to XML, unless annotated by XmlTransient.
NONE
None of the fields or properties is bound to XML unless they are specifically annotated with some of the JAXB annotations.
PROPERTY
Every getter/setter pair in a JAXB-bound class will be automatically bound to XML, unless annotated by XmlTransient.
PUBLIC_MEMBER
Every public getter/setter pair and every public field will be automatically bound to XML, unless annotated by XmlTransient.
Method Summary
static XmlAccessType | valueOf(String name) Returns the enum constant of this type with the specified name.
static XmlAccessType[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

PROPERTY

public static final XmlAccessType PROPERTY
Every getter/setter pair in a JAXB-bound class will be automatically bound to XML, unless annotated by XmlTransient. Fields are bound to XML only when they are explicitly annotated by some of the JAXB annotations.

FIELD

public static final XmlAccessType FIELD
Every non static, non transient field in a JAXB-bound class will be automatically bound to XML, unless annotated by XmlTransient. Getter/setter pairs are bound to XML only when they are explicitly annotated by some of the JAXB annotations.

PUBLIC_MEMBER

public static final XmlAccessType PUBLIC_MEMBER
Every public getter/setter pair and every public field will be automatically bound to XML, unless annotated by XmlTransient. Fields or getter/setter pairs that are private, protected, or defaulted to package-only access are bound to XML only when they are explicitly annotated by the appropriate JAXB annotations.

NONE

public static final XmlAccessType NONE
None of the fields or properties is bound to XML unless they are specifically annotated with some of the JAXB annotations.

Method Detail

values

public static XmlAccessType[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (XmlAccessType c : XmlAccessType.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static XmlAccessType valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


XmlAnyElement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlAnyElement

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD})
public @interface XmlAnyElement

Maps a JavaBean property to XML infoset representation and/or JAXB element.

This annotation serves as a "catch-all" property while unmarshalling xml content into a instance of a JAXB annotated class. It typically annotates a multi-valued JavaBean property, but it can occur on single value JavaBean property. During unmarshalling, each xml element that does not match a static @XmlElement or @XmlElementRef annotation for the other JavaBean properties on the class, is added to this "catch-all" property.

Usages:

 @XmlAnyElement
 public Element[] others;

 // Collection of Element or JAXB elements.
 @XmlAnyElement(lax="true")
 public Object[] others;

 @XmlAnyElement
 private List<Element> nodes;

 @XmlAnyElement
 private Element node;

Restriction usage constraints

This annotation is mutually exclusive with XmlElement, XmlAttribute, XmlValue, XmlElements, XmlID, and XmlIDREF.

There can be only one XmlAnyElement annotated JavaBean property in a class and its super classes.

Relationship to other annotations

This annotation can be used with XmlJavaTypeAdapter, so that users can map their own data structure to DOM, which in turn can be composed into XML.

This annotation can be used with XmlMixed like this:

 // List of java.lang.String or DOM nodes.
 @XmlAnyElement @XmlMixed
 List<Object> others;

Schema To Java example

The following schema would produce the following Java class:

 <xs:complexType name="foo">
   <xs:sequence>
     <xs:element name="a" type="xs:int" />
     <xs:element name="b" type="xs:int" />
     <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
   </xs:sequence>
 </xs:complexType>

 class Foo {
   int a;
   int b;
   @XmlAnyElement
   List<Element> any;
 }
It can unmarshal instances like

 <foo xmlns:e="extra">
   <a>1</a>
   <e:other />  // this will be bound to DOM, because unmarshalling is orderless
   <b>3</b>
   <e:other />
   <c>5</c>     // this will be bound to DOM, because the annotation doesn't remember namespaces.
 </foo>
The following schema would produce the following Java class:

 <xs:complexType name="bar">
   <xs:complexContent>
   <xs:extension base="foo">
     <xs:sequence>
       <xs:element name="c" type="xs:int" />
       <xs:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
     </xs:sequence>
   </xs:extension>
 </xs:complexType>

 class Bar extends Foo {
   int c;
   // Foo.getAny() also represents wildcard content for type definition bar.
 }
It can unmarshal instances like

 <bar xmlns:e="extra">
   <a>1</a>
   <e:other />  // this will be bound to DOM, because unmarshalling is orderless
   <b>3</b>
   <e:other />
   <c>5</c>     // this now goes to Bar.c
   <e:other />  // this will go to Foo.any
 </bar>

Using XmlAnyElement with XmlElementRef

The XmlAnyElement annotation can be used with XmlElementRefs to designate additional elements that can participate in the content tree.

The following schema would produce the following Java class:

 <xs:complexType name="foo">
   <xs:choice maxOccurs="unbounded" minOccurs="0">
     <xs:element name="a" type="xs:int" />
     <xs:element name="b" type="xs:int" />
     <xs:any namespace="##other" processContents="lax" />
   </xs:choice>
 </xs:complexType>

 class Foo {
   @XmlAnyElement(lax="true")
   @XmlElementRefs({
     @XmlElementRef(name="a", type="JAXBElement.class")
     @XmlElementRef(name="b", type="JAXBElement.class")
   })
   List<Object> others;
 }

 @XmlRegistry
 class ObjectFactory {
   ...
   @XmlElementDecl(name = "a", namespace = "", scope = Foo.class)
   JAXBElement<Integer> createFooA( Integer i ) { ... }

   @XmlElementDecl(name = "b", namespace = "", scope = Foo.class)
   JAXBElement<Integer> createFooB( Integer i ) { ... }
It can unmarshal instances like

 <foo xmlns:e="extra">
   <a>1</a>     // this will unmarshal to a <A title="class in javax.xml.bind" href="/j2se6/api/javax/xml/bind/JAXBElement.html"><CODE>JAXBElement</CODE></A> instance whose value is 1.
   <e:other />  // this will unmarshal to a DOM <A title="interface in org.w3c.dom" href="/j2se6/api/org/w3c/dom/Element.html"><CODE>Element</CODE></A>.
   <b>3</b>     // this will unmarshal to a <A title="class in javax.xml.bind" href="/j2se6/api/javax/xml/bind/JAXBElement.html"><CODE>JAXBElement</CODE></A> instance whose value is 1.
 </foo>

W3C XML Schema "lax" wildcard emulation

The lax element of the annotation enables the emulation of the "lax" wildcard semantics. For example, when the Java source code is annotated like this:
 @XmlRootElement
 class Foo {
   @XmlAnyElement(lax=true)
   public Object[] others;
 }
then the following document will unmarshal like this:

 <foo>
   <unknown />
   <foo />
 </foo>

 Foo foo = unmarshal();
 // 1 for 'unknown', another for 'foo'
 assert foo.others.length==2;
 // 'unknown' unmarshals to a DOM element
 assert foo.others[0] instanceof Element;
 // because of lax=true, the 'foo' element eagerly
 // unmarshals to a Foo object.
 assert foo.others[1] instanceof Foo;

Since:
JAXB2.0

Optional Element Summary
boolean | lax Controls the unmarshaller behavior when it sees elements known to the current JAXBContext.
Class<? extends DomHandler> | value Specifies the DomHandler which is responsible for actually converting XML from/to a DOM-like data structure.

lax

public abstract boolean lax
Controls the unmarshaller behavior when it sees elements known to the current JAXBContext.

When false

If false, all the elements that match the property will be unmarshalled to DOM, and the property will only contain DOM elements.

When true

If true, when an element matches a property marked with XmlAnyElement is known to JAXBContext (for example, there's a class with XmlRootElement that has the same tag name, or there's XmlElementDecl that has the same tag name), the unmarshaller will eagerly unmarshal this element to the JAXB object, instead of unmarshalling it to DOM. Additionally, if the element is unknown but it has a known xsi:type, the unmarshaller eagerly unmarshals the element to a JAXBElement, with the unknown element name and the JAXBElement value is set to an instance of the JAXB mapping of the known xsi:type.

As a result, after the unmarshalling, the property can become heterogeneous; it can have both DOM nodes and some JAXB objects at the same time.

This can be used to emulate the "lax" wildcard semantics of the W3C XML Schema.

Default:
false

value

public abstract Class<? extends DomHandler> value
Specifies the DomHandler which is responsible for actually converting XML from/to a DOM-like data structure.

Default:
javax.xml.bind.annotation.W3CDomHandler.class
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlAttribute

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlAttribute

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD})
public @interface XmlAttribute

Maps a JavaBean property to a XML attribute.

Usage

The @XmlAttribute annotation can be used with the following program elements:

  • JavaBean property
  • field

A static final field is mapped to a XML fixed attribute.

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

The usage is subject to the following constraints:
  • If type of the field or the property is a collection type, then the collection item type must be mapped to schema simple type.
         // Examples
     @XmlAttribute List<Integer> items; //legal
     @XmlAttribute List<Bar> foo; // illegal if Bar does not map to a schema simple type
  • If the type of the field or the property is a non collection type, then the type of the property or field must map to a simple schema type.
         // Examples
     @XmlAttribute int foo; // legal
     @XmlAttribute Foo foo; // illegal if Foo does not map to a schema simple type
  • This annotation can be used with the following annotations: XmlID, XmlIDREF, XmlList, XmlSchemaType, XmlValue, XmlAttachmentRef, XmlMimeType, XmlInlineBinaryData, XmlJavaTypeAdapter
    • .

Example 1: Map a JavaBean property to an XML attribute.

     //Example: Code fragment
     public class USPrice {
         @XmlAttribute
         public java.math.BigDecimal getPrice() {...} ;
         public void setPrice(java.math.BigDecimal ) {...};
     }

     <!-- Example: XML Schema fragment -->
     <xs:complexType name="USPrice">
       <xs:sequence>
       </xs:sequence>
       <xs:attribute name="price" type="xs:decimal"/>
     </xs:complexType>

Example 2: Map a JavaBean property to an XML attribute with anonymous type.

See Example 7 in @XmlType.

Example 3: Map a JavaBean collection property to an XML attribute.

     // Example: Code fragment
     class Foo {
         ...
         @XmlAttribute List<Integer> items;
     }

     <!-- Example: XML Schema fragment -->
     <xs:complexType name="foo">
         ...
       <xs:attribute name="items">
         <xs:simpleType>
           <xs:list itemType="xs:int"/>
         </xs:simpleType>
     </xs:complexType>

Since:
JAXB2.0
See Also:
XmlType

Optional Element Summary
String | name Name of the XML Schema attribute.
String | namespace Specifies the XML target namespace of the XML Schema attribute.
boolean | required Specifies if the XML Schema attribute is optional or required.

name

public abstract String name
Name of the XML Schema attribute. By default, the XML Schema attribute name is derived from the JavaBean property name.

Default:
"##default"

required

public abstract boolean required
Specifies if the XML Schema attribute is optional or required. If true, then the JavaBean property is mapped to a XML Schema attribute that is required. Otherwise it is mapped to a XML Schema attribute that is optional.

Default:
false

namespace

public abstract String namespace
Specifies the XML target namespace of the XML Schema attribute.

Default:
"##default"
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlElement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlElement

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD})
public @interface XmlElement

Maps a JavaBean property to a XML element derived from property name.

Usage

@XmlElement annotation can be used with the following program elements:

  • a JavaBean property
  • non static, non transient field
  • within XmlElements

The usage is subject to the following constraints:
  • This annotation can be used with following annotations: XmlID, XmlIDREF, XmlList, XmlSchemaType, XmlValue, XmlAttachmentRef, XmlMimeType, XmlInlineBinaryData, XmlElementWrapper, XmlJavaTypeAdapter
  • if the type of JavaBean property is a collection type of array, an indexed property, or a parameterized list, and this annotation is used with XmlElements then, @XmlElement.type() must be DEFAULT.class since the collection item type is already known.

A JavaBean property, when annotated with @XmlElement annotation is mapped to a local element in the XML Schema complex type to which the containing class is mapped.

Example 1: Map a public non static non final field to local element

     //Example: Code fragment
     public class USPrice {
         @XmlElement(name="itemprice")
         public java.math.BigDecimal price;
     }

     <!-- Example: Local XML Schema element -->
     <xs:complexType name="USPrice"/>
       <xs:sequence>
         <xs:element name="itemprice" type="xs:decimal" minOccurs="0"/>
       </sequence>
     </xs:complexType>

Example 2: Map a field to a nillable element.

     //Example: Code fragment
     public class USPrice {
         @XmlElement(nillable=true)
         public java.math.BigDecimal price;
     }

     <!-- Example: Local XML Schema element -->
     <xs:complexType name="USPrice">
       <xs:sequence>
         <xs:element name="price" type="xs:decimal" nillable="true" minOccurs="0"/>
       </sequence>
     </xs:complexType>

Example 3: Map a field to a nillable, required element.

     //Example: Code fragment
     public class USPrice {
         @XmlElement(nillable=true, required=true)
         public java.math.BigDecimal price;
     }

     <!-- Example: Local XML Schema element -->
     <xs:complexType name="USPrice">
       <xs:sequence>
         <xs:element name="price" type="xs:decimal" nillable="true" minOccurs="1"/>
       </sequence>
     </xs:complexType>

Example 4: Map a JavaBean property to an XML element with anonymous type.

See Example 6 in @XmlType.

Since:
JAXB2.0

Optional Element Summary
String | defaultValue Default value of this element.
String | name Name of the XML Schema element.
String | namespace XML target namespace of the XML Schema element.
boolean | nillable Customize the element declaration to be nillable.
boolean | required Customize the element declaration to be required.
Class | type The Java class being referenced.

name

public abstract String name
Name of the XML Schema element.

If the value is "##default", then element name is derived from the JavaBean property name.

Default:
"##default"

nillable

public abstract boolean nillable
Customize the element declaration to be nillable.

If nillable() is true, then the JavaBean property is mapped to a XML Schema nillable element declaration.

Default:
false

required

public abstract boolean required
Customize the element declaration to be required.

If required() is true, then Javabean property is mapped to an XML schema element declaration with minOccurs="1". maxOccurs is "1" for a single valued property and "unbounded" for a multivalued property.

If required() is false, then the Javabean property is mapped to XML Schema element declaration with minOccurs="0". maxOccurs is "1" for a single valued property and "unbounded" for a multivalued property.

Default:
false

namespace

public abstract String namespace
XML target namespace of the XML Schema element.

If the value is "##default", then the namespace is determined as follows:

  1. If the enclosing package has XmlSchema annotation, and its elementFormDefault is QUALIFIED, then the namespace of the enclosing class.
  2. Otherwise "" (which produces unqualified element in the default namespace.

Default:
"##default"

defaultValue

public abstract String defaultValue
Default value of this element.

The '' value specified as a default of this annotation element is used as a poor-man's substitute for null to allow implementations to recognize the 'no default value' state.

Default:
"\u0000"

type

public abstract Class type
The Java class being referenced.

Default:
javax.xml.bind.annotation.XmlElement.DEFAULT.class
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlElement.DEFAULT

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.annotation
Class XmlElement.DEFAULT

java.lang.Object
    extended by  javax.xml.bind.annotation.XmlElement.DEFAULT
Enclosing class:
XmlElement
public static final class XmlElement.DEFAULT
extends Object

Used in XmlElement.type() to signal that the type be inferred from the signature of the property.

Constructor Summary
XmlElement.DEFAULT()
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XmlElement.DEFAULT

public XmlElement.DEFAULT()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XmlElementDecl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlElementDecl

@Retention(value=RUNTIME)
@Target(value=METHOD)
public @interface XmlElementDecl

Maps a factory method to a XML element.

Usage

The annotation creates a mapping between an XML schema element declaration and a element factory method that returns a JAXBElement instance representing the element declaration. Typically, the element factory method is generated (and annotated) from a schema into the ObjectFactory class in a Java package that represents the binding of the element declaration's target namespace. Thus, while the annotation syntax allows @XmlElementDecl to be used on any method, semantically its use is restricted to annotation of element factory method. The usage is subject to the following constraints:
  • The class containing the element factory method annotated with @XmlElementDecl must be marked with XmlRegistry.
  • The element factory method must take one parameter assignable to Object.

Example 1: Annotation on a factory method

     // Example: code fragment
     @XmlRegistry
     class ObjectFactory {
         @XmlElementDecl(name="foo")
         JAXBElement<String> createFoo(String s) { ... }
     }

     <!-- XML input -->
       <foo>string</foo>

     // Example: code fragment corresponding to XML input
     JAXBElement<String> o =
     (JAXBElement<String>)unmarshaller.unmarshal(aboveDocument);
     // print JAXBElement instance to show values
     System.out.println(o.getName());   // prints  "{}foo"
     System.out.println(o.getValue());  // prints  "string"
     System.out.println(o.getValue().getClass()); // prints "java.lang.String"

     <!-- Example: XML schema definition -->
     <xs:element name="foo" type="xs:string" />

Example 2: Element declaration with non local scope

The following example illustrates the use of scope annotation parameter in binding of element declaration in schema derived code.

The following example may be replaced in a future revision of this javadoc.

     <!-- Example: XML schema definition -->
     <xs:schema>
       <xs:complexType name="pea">
         <xs:choice maxOccurs="unbounded">
           <xs:element name="foo" type="xs:string" />
           <xs:element name="bar" type="xs:string" />
         </xs:choice>
       </xs:complexType>
       <xs:element name="foo" type="xs:int" />
     </xs:schema>

     // Example: expected default binding
     class Pea {
         @XmlElementRefs({
             @XmlElementRef(name="foo",type=JAXBElement.class)
             @XmlElementRef(name="bar",type=JAXBElement.class)
         })
         List<JAXBElement<String>> fooOrBar;
     }

     @XmlRegistry
     class ObjectFactory {
         @XmlElementDecl(scope=Pea.class,name="foo")
         JAXBElement createPeaFoo(String s);

         @XmlElementDecl(scope=Pea.class,name="bar")
         JAXBElement createPeaBar(String s);

         @XmlElementDecl(name="foo")
         JAXBElement createFoo(Integer i);
     }
Without scope createFoo and createPeaFoo would become ambiguous since both of them map to a XML schema element with the same local name "foo".

Since:
JAXB 2.0
See Also:
XmlRegistry

Required Element Summary
 String name
local name of the XML element.
Optional Element Summary
String | defaultValue Default value of this element.
String | namespace namespace name of the XML element.
Class | scope scope of the mapping.
String | substitutionHeadName XML local name of a substitution group's head element.
String | substitutionHeadNamespace namespace name of a substitution group's head XML element.

Element Detail

name

public abstract String name
local name of the XML element.

Note to reviewers: There is no default name; since the annotation is on a factory method, it is not clear that the method name can be derived from the factory method name.

See Also:
namespace()

scope

public abstract Class scope
scope of the mapping.

If this is not XmlElementDecl.GLOBAL, then this element declaration mapping is only active within the specified class.

Default:
javax.xml.bind.annotation.XmlElementDecl.GLOBAL.class

namespace

public abstract String namespace
namespace name of the XML element.

If the value is "##default", then the value is the namespace name for the package of the class containing this factory method.

See Also:
name()
Default:
"##default"

substitutionHeadNamespace

public abstract String substitutionHeadNamespace
namespace name of a substitution group's head XML element.

This specifies the namespace name of the XML element whose local name is specified by substitutionHeadName().

If susbtitutionHeadName() is "", then this value can only be "##default". But the value is ignored since since this element is not part of susbtitution group when the value of susbstitutionHeadName() is "".

If susbtitutionHeadName() is not "" and the value is "##default", then the namespace name is the namespace name to which the package of the containing class, marked with XmlRegistry, is mapped.

If susbtitutionHeadName() is not "" and the value is not "##default", then the value is the namespace name.

See Also:
substitutionHeadName()
Default:
"##default"

substitutionHeadName

public abstract String substitutionHeadName
XML local name of a substitution group's head element.

If the value is "", then this element is not part of any substitution group.

See Also:
substitutionHeadNamespace()
Default:
""

defaultValue

public abstract String defaultValue
Default value of this element.

The '' value specified as a default of this annotation element is used as a poor-man's substitute for null to allow implementations to recognize the 'no default value' state.

Default:
"\u0000"
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlElementDecl.GLOBAL

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.annotation
Class XmlElementDecl.GLOBAL

java.lang.Object
    extended by  javax.xml.bind.annotation.XmlElementDecl.GLOBAL
Enclosing class:
XmlElementDecl
public static final class XmlElementDecl.GLOBAL
extends Object

Used in XmlElementDecl.scope() to signal that the declaration is in the global scope.

Constructor Summary
XmlElementDecl.GLOBAL()
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XmlElementDecl.GLOBAL

public XmlElementDecl.GLOBAL()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XmlElementRef

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlElementRef

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD})
public @interface XmlElementRef

Maps a JavaBean property to a XML element derived from property's type.

Usage

@XmlElementRef annotation can be used with a JavaBean property or from within XmlElementRefs

This annotation dynamically associates an XML element name with the JavaBean property. When a JavaBean property is annotated with XmlElement, the XML element name is statically derived from the JavaBean property name. However, when this annotation is used, the XML element name is derived from the instance of the type of the JavaBean property at runtime.

XML Schema substitution group support

XML Schema allows a XML document author to use XML element names that were not statically specified in the content model of a schema using substitution groups. Schema derived code provides support for substitution groups using an element property, (section 5.5.5, "Element Property" of JAXB 2.0 specification). An element property method signature is of the form:

     public void setTerm(JAXBElement<? extends="extends" Operator="Operator">);
     public JAXBElement<? extends="extends" Operator="Operator"> getTerm();

An element factory method annotated with XmlElementDecl is used to create a JAXBElement instance, containing an XML element name. The presence of @XmlElementRef annotation on an element property indicates that the element name from JAXBElement instance be used instead of deriving an XML element name from the JavaBean property name.

The usage is subject to the following constraints:

  • If the collection item type (for collection property) or property type (for single valued property) is JAXBElement, then @XmlElementRef}.name() and @XmlElementRef.namespace() must point an element factory method with an @XmlElementDecl annotation in a class annotated with @XmlRegistry (usually ObjectFactory class generated by the schema compiler) :
    • @XmlElementDecl.name() must equal @XmlElementRef.name()
    • @XmlElementDecl.namespace() must equal @XmlElementRef.namespace().
  • If the collection item type (for collection property) or property type (for single valued property) is not JAXBElement, then the type referenced by the property or field must be annotated with XmlRootElement.
  • This annotation can be used with the following annotations: XmlElementWrapper, XmlJavaTypeAdapter.

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

Example 1: Ant Task Example

The following Java class hierarchy models an Ant build script. An Ant task corresponds to a class in the class hierarchy. The XML element name of an Ant task is indicated by the @XmlRootElement annotation on its corresponding class.
     @XmlRootElement(name="target")
     class Target {
         // The presence of @XmlElementRef indicates that the XML
         // element name will be derived from the @XmlRootElement
         // annotation on the type (for e.g. "jar" for JarTask).
         @XmlElementRef
         List<Task> tasks;
     }

     abstract class Task {
     }

     @XmlRootElement(name="jar")
     class JarTask extends Task {
         ...
     }

     @XmlRootElement(name="javac")
     class JavacTask extends Task {
         ...
     }

     <!-- XML Schema fragment -->
     <xs:element name="target" type="Target">
     <xs:complexType name="Target">
       <xs:sequence>
         <xs:choice maxOccurs="unbounded">
           <xs:element ref="jar">
           <xs:element ref="javac">
         </xs:choice>
       </xs:sequence>
     </xs:complexType>

Thus the following code fragment:

     Target target = new Target();
     target.tasks.add(new JarTask());
     target.tasks.add(new JavacTask());
     marshal(target);
will produce the following XML output:

     <target>
       <jar>
         ....
       </jar>
       <javac>
         ....
       </javac>
     </target>

It is not an error to have a class that extends Task that doesn't have XmlRootElement. But they can't show up in an XML instance (because they don't have XML element names).

Example 2: XML Schema Susbstitution group support

The following example shows the annotations for XML Schema substitution groups. The annotations and the ObjectFactory are derived from the schema.

     @XmlElement
     class Math {
         //  The value of type()is
         //  JAXBElement.class , which indicates the XML
         //  element name ObjectFactory - in general a class marked
         //  with @XmlRegistry. (See ObjectFactory below)
         //
         //  The name() is "operator", a pointer to a
         // factory method annotated with a
         //  XmlElementDecl with the name "operator". Since
         //  "operator" is the head of a substitution group that
         //  contains elements "add" and "sub" elements, "operator"
         //  element can be substituted in an instance document by
         //  elements "add" or "sub". At runtime, JAXBElement
         //  instance contains the element name that has been
         //  substituted in the XML document.
         //
         @XmlElementRef(type=JAXBElement.class,name="operator")
         JAXBElement<? extends Operator> term;
     }

     @XmlRegistry
     class ObjectFactory {
         @XmlElementDecl(name="operator")
         JAXBElement<Operator> createOperator(Operator o) {...}
         @XmlElementDecl(name="add",substitutionHeadName="operator")
         JAXBElement<Operator> createAdd(Operator o) {...}
         @XmlElementDecl(name="sub",substitutionHeadName="operator")
         JAXBElement<Operator> createSub(Operator o) {...}
     }

     class Operator {
         ...
     }

Thus, the following code fragment

     Math m = new Math();
     m.term = new ObjectFactory().createAdd(new Operator());
     marshal(m);
will produce the following XML output:
     <math>
       <add>...</add>
     </math>

Since:
JAXB2.0
See Also:
XmlElementRefs

Optional Element Summary
String | name
String | namespace This parameter and name() are used to determine the XML element for the JavaBean property.
Class | type The Java type being referenced.

type

public abstract Class type
The Java type being referenced.

If the value is DEFAULT.class, the type is inferred from the the type of the JavaBean property.

Default:
javax.xml.bind.annotation.XmlElementRef.DEFAULT.class

namespace

public abstract String namespace
This parameter and name() are used to determine the XML element for the JavaBean property.

If type() is JAXBElement.class , then namespace() and name() point to a factory method with XmlElementDecl. The XML element name is the element name from the factory method's XmlElementDecl annotation or if an element from its substitution group (of which it is a head element) has been substituted in the XML document, then the element name is from the XmlElementDecl on the substituted element.

If type() is not JAXBElement.class, then the XML element name is the XML element name statically associated with the type using the annotation XmlRootElement on the type. If the type is not annotated with an XmlElementDecl, then it is an error.

If type() is not JAXBElement.class, then this value must be "".

Default:
""

name

public abstract String name
See Also:
namespace()
Default:
"##default"
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlElementRef.DEFAULT

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.annotation
Class XmlElementRef.DEFAULT

java.lang.Object
    extended by  javax.xml.bind.annotation.XmlElementRef.DEFAULT
Enclosing class:
XmlElementRef
public static final class XmlElementRef.DEFAULT
extends Object

Used in XmlElementRef.type() to signal that the type be inferred from the signature of the property.

Constructor Summary
XmlElementRef.DEFAULT()
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XmlElementRef.DEFAULT

public XmlElementRef.DEFAULT()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XmlElementRefs

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlElementRefs

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD})
public @interface XmlElementRefs

Marks a property that refers to classes with XmlElement or JAXBElement.

Compared to an element property (property with XmlElement annotation), a reference property has a different substitution semantics. When a sub-class is assigned to a property, an element property produces the same tag name with @xsi:type, whereas a reference property produces a different tag name (the tag name that's on the the sub-class.)

This annotation can be used with the following annotations: XmlJavaTypeAdapter, XmlElementWrapper.

Since:
JAXB2.0
See Also:
XmlElementWrapper, XmlElementRef

Required Element Summary
 XmlElementRef[] value

Element Detail

value

public abstract XmlElementRef[] value
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlElements

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlElements

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD})
public @interface XmlElements

A container for multiple @XmlElement annotations. Multiple annotations of the same type are not allowed on a program element. This annotation therefore serves as a container annotation for multiple @XmlElements as follows:

 @XmlElements({ @XmlElement(...),@XmlElement(...) })

The @XmlElements annnotation can be used with the following program elements:

  • a JavaBean property
  • non static, non transient field
This annotation is intended for annotation a JavaBean collection property (e.g. List).

Usage

The usage is subject to the following constraints:

  • This annotation can be used with the following annotations: @XmlIDREF, @XmlElementWrapper.
  • If @XmlIDREF is also specified on the JavaBean property, then each @XmlElement.type() must contain a JavaBean property annotated with @XmlID.

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

Example 1: Map to a list of elements

    // Mapped code fragment
    public class Foo {
        @XmlElements(
            @XmlElement(name="A", type=Integer.class),
            @XmlElement(name="B", type=Float.class)
         }
         public List items;
    }

    <!-- XML Representation for a List of {1,2.5}
            XML output is not wrapped using another element -->
    ...
     1
     2.5
    ...

    <!-- XML Schema fragment -->
    <xs:complexType name="Foo">
      <xs:sequence>
        <xs:choice minOccurs="0" maxOccurs="unbounded">
          <xs:element name="A" type="xs:int"/>
          <xs:element name="B" type="xs:float"/>
        <xs:choice>
      </xs:sequence>
    </xs:complexType>

Example 2: Map to a list of elements wrapped with another element

    // Mapped code fragment
    public class Foo {
        @XmlElementWrapper(name="bar")
        @XmlElements(
            @XmlElement(name="A", type=Integer.class),
            @XmlElement(name="B", type=Float.class)
        }
        public List items;
    }

    <!-- XML Schema fragment -->
    <xs:complexType name="Foo">
      <xs:sequence>
        <xs:element name="bar">
          <xs:complexType>
            <xs:choice minOccurs="0" maxOccurs="unbounded">
              <xs:element name="A" type="xs:int"/>
              <xs:element name="B" type="xs:float"/>
            </xs:choice>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>

Example 3: Change element name based on type using an adapter.

    class Foo {
       @XmlJavaTypeAdapter(QtoPAdapter.class)
       @XmlElements({
           @XmlElement(name="A",type=PX.class),
           @XmlElement(name="B",type=PY.class)
       })
       Q bar;
    }

    @XmlType abstract class P {...}
    @XmlType(name="PX") class PX extends P {...}
    @XmlType(name="PY") class PY extends P {...}

    <!-- XML Schema fragment -->
    <xs:complexType name="Foo">
      <xs:sequence>
        <xs:element name="bar">
          <xs:complexType>
            <xs:choice minOccurs="0" maxOccurs="unbounded">
              <xs:element name="A" type="PX"/>
              <xs:element name="B" type="PY"/>
            </xs:choice>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>

Since:
JAXB2.0
See Also:
XmlElement, XmlElementRef, XmlElementRefs, XmlJavaTypeAdapter

Required Element Summary
 XmlElement[] value
Collection of @XmlElement annotations

Element Detail

value

public abstract XmlElement[] value
Collection of @XmlElement annotations

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlElementWrapper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlElementWrapper

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD})
public @interface XmlElementWrapper

Generates a wrapper element around XML representation. This is primarily intended to be used to produce a wrapper XML element around collections. The annotation therefore supports two forms of serialization shown below.

    //Example: code fragment
      int[] names;

    // XML Serialization Form 1 (Unwrapped collection)
    <names> ... </names>
    <names> ... </names>

    // XML Serialization Form 2 ( Wrapped collection )
    <wrapperElement>
       <names> value-of-item </names>
       <names> value-of-item </names>
       ....
    </wrapperElement>

The two serialized XML forms allow a null collection to be represented either by absence or presence of an element with a nillable attribute.

Usage

The @XmlElementWrapper annotation can be used with the following program elements:

  • JavaBean property
  • non static, non transient field

The usage is subject to the following constraints:

  • The property must be a collection property
  • This annotation can be used with the following annotations: XmlElement, XmlElements, XmlElementRef, XmlElementRefs, XmlJavaTypeAdapter
    • .

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

Since:
JAXB2.0
See Also:
XmlElement, XmlElements, XmlElementRef, XmlElementRefs

Optional Element Summary
String | name Name of the XML wrapper element.
String | namespace XML target namespace of the XML wrapper element.
boolean | nillable If true, the absence of the collection is represented by using xsi:nil='true'.

name

public abstract String name
Name of the XML wrapper element. By default, the XML wrapper element name is derived from the JavaBean property name.

Default:
"##default"

namespace

public abstract String namespace
XML target namespace of the XML wrapper element.

If the value is "##default", then the namespace is determined as follows:

  1. If the enclosing package has XmlSchema annotation, and its elementFormDefault is QUALIFIED, then the namespace of the enclosing class.
  2. Otherwise "" (which produces unqualified element in the default namespace.

Default:
"##default"

nillable

public abstract boolean nillable
If true, the absence of the collection is represented by using xsi:nil='true'. Otherwise, it is represented by the absence of the element.

Default:
false
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlEnum

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlEnum

@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface XmlEnum

Maps an enum type Enum to XML representation.

This annotation, together with XmlEnumValue provides a mapping of enum type to XML representation.

Usage

The @XmlEnum annotation can be used with the following program elements:

  • enum type

The usage is subject to the following constraints:

  • This annotation can be used the following other annotations: XmlType, XmlRootElement

See "Package Specification" in javax.xml.bind.package javadoc for additional common information

An enum type is mapped to a schema simple type with enumeration facets. The schema type is derived from the Java type to which @XmlEnum.value(). Each enum constant @XmlEnumValue must have a valid lexical representation for the type @XmlEnum.value() .

Examples: See examples in XmlEnumValue

Since:
JAXB2.0

Optional Element Summary
 Class<?> value
Java type that is mapped to a XML simple type.

value

public abstract Class<?> value
Java type that is mapped to a XML simple type.

Default:
java.lang.String.class
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlEnumValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlEnumValue

@Retention(value=RUNTIME)
@Target(value=FIELD)
public @interface XmlEnumValue

Maps an enum constant in Enum type to XML representation.

Usage

The @XmlEnumValue annotation can be used with the following program elements:

  • enum constant

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

This annotation, together with XmlEnum provides a mapping of enum type to XML representation.

An enum type is mapped to a schema simple type with enumeration facets. The schema type is derived from the Java type specified in @XmlEnum.value(). Each enum constant @XmlEnumValue must have a valid lexical representation for the type @XmlEnum.value()

In the absence of this annotation, Enum.name() is used as the XML representation.

Example 1: Map enum constant name -> enumeration facet

     //Example: Code fragment
     @XmlEnum(String.class)
     public enum Card { CLUBS, DIAMONDS, HEARTS, SPADES }

     <!-- Example: XML Schema fragment -->
     <xs:simpleType name="Card">
       <xs:restriction base="xs:string"/>
         <xs:enumeration value="CLUBS"/>
         <xs:enumeration value="DIAMONDS"/>
         <xs:enumeration value="HEARTS"/>
         <xs:enumeration value="SPADES"/>
     </xs:simpleType>

Example 2: Map enum constant name(value) -> enumeration facet

     //Example: code fragment
     @XmlType
     @XmlEnum(Integer.class)
     public enum Coin {
         @XmlEnumValue("1") PENNY(1),
         @XmlEnumValue("5") NICKEL(5),
         @XmlEnumValue("10") DIME(10),
         @XmlEnumValue("25") QUARTER(25) }

     <!-- Example: XML Schema fragment -->
     <xs:simpleType name="Coin">
       <xs:restriction base="xs:int">
         <xs:enumeration value="1"/>
         <xs:enumeration value="5"/>
         <xs:enumeration value="10"/>
         <xs:enumeration value="25"/>
       </xs:restriction>
     </xs:simpleType>

Example 3: Map enum constant name -> enumeration facet

     //Code fragment
     @XmlType
     @XmlEnum(Integer.class)
     public enum Code {
         @XmlEnumValue("1") ONE,
         @XmlEnumValue("2") TWO;
     }

     <!-- Example: XML Schema fragment -->
     <xs:simpleType name="Code">
       <xs:restriction base="xs:int">
         <xs:enumeration value="1"/>
         <xs:enumeration value="2"/>
       </xs:restriction>
     </xs:simpleType>

Since:
JAXB 2.0

Required Element Summary
 String value

Element Detail

value

public abstract String value
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlMimeType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlMimeType

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD,PARAMETER})
public @interface XmlMimeType

Associates the MIME type that controls the XML representation of the property.

This annotation is used in conjunction with datatypes such as Image or Source that are bound to base64-encoded binary in XML.

If a property that has this annotation has a sibling property bound to the xmime:contentType attribute, and if in the instance the property has a value, the value of the attribute takes precedence and that will control the marshalling.

Since:
JAXB2.0

Required Element Summary
 String value
The textual representation of the MIME type, such as "image/jpeg" "image/*", "text/xml; charset=iso-8859-1" and so on.

Element Detail

value

public abstract String value
The textual representation of the MIME type, such as "image/jpeg" "image/*", "text/xml; charset=iso-8859-1" and so on.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlNs

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlNs

@Retention(value=RUNTIME)
@Target(value={})
public @interface XmlNs

Associates a namespace prefix with a XML namespace URI.

Usage

@XmlNs annotation is intended for use from other program annotations.

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

Example:See XmlSchema annotation type for an example.

Since:
JAXB2.0

Required Element Summary
String | namespaceURI Namespace URI
String | prefix Namespace prefix

Element Detail

prefix

public abstract String prefix
Namespace prefix

namespaceURI

public abstract String namespaceURI
Namespace URI

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlNsForm

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.xml.bind.annotation
Enum XmlNsForm

java.lang.Object
    extended by  java.lang.Enum<XmlNsForm>
        extended by  javax.xml.bind.annotation.XmlNsForm
All Implemented Interfaces:
Serializable, Comparable<XmlNsForm>
public enum XmlNsForm
extends Enum<XmlNsForm>

Enumeration of XML Schema namespace qualifications.

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

Usage

The namespace qualification values are used in the annotations defined in this packge. The enumeration values are mapped as follows:

Enum Value | XML Schema Value
UNQUALIFIED | unqualified
QUALIFIED | qualified
UNSET | namespace qualification attribute is absent from the XML Schema fragment

Since:
JAXB2.0

Enum Constant Summary
QUALIFIED
UNQUALIFIED
UNSET
Method Summary
static XmlNsForm | valueOf(String name) Returns the enum constant of this type with the specified name.
static XmlNsForm[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

UNQUALIFIED

public static final XmlNsForm UNQUALIFIED

QUALIFIED

public static final XmlNsForm QUALIFIED

UNSET

public static final XmlNsForm UNSET
Method Detail

values

public static XmlNsForm[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (XmlNsForm c : XmlNsForm.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static XmlNsForm valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


XmlRootElement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlRootElement

@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface XmlRootElement

Maps a class or an enum type to an XML element.

Usage

The @XmlRootElement annotation can be used with the following program elements:

  • a top level class
  • an enum type

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

When a top level class or an enum type is annotated with the @XmlRootElement annotation, then its value is represented as XML element in an XML document.

This annotation can be used with the following annotations: XmlType, XmlEnum, XmlAccessorType, XmlAccessorOrder.

Example 1: Associate an element with XML Schema type

     // Example: Code fragment
     @XmlRootElement
     class Point {
        int x;
        int y;
        Point(int _x,int _y) {x=_x;y=_y;}
     }

     //Example: Code fragment corresponding to XML output
     marshal( new Point(3,5), System.out);

     <!-- Example: XML output -->
     <point>
       <x> 3 </x>
       <y> 5 </y>
     </point>
The annotation causes an global element declaration to be produced in the schema. The global element declaration is associated with the XML schema type to which the class is mapped.

     <!-- Example: XML schema definition -->
     <xs:element name="point" type="point" />
     <xs:complexType name="point">
       <xs:sequence>
         <xs:element name="x" type="xs:int" />
         <xs:element name="y" type="xs:int" />
       </xs:sequence>
     </xs:complexType>

Example 2: Orthogonality to type inheritance

An element declaration annotated on a type is not inherited by its derived types. The following example shows this.

     // Example: Code fragment
     @XmlRootElement
     class Point3D extends Point {
         int z;
         Point3D(int _x,int _y,int _z) {super(_x,_y);z=_z;}
     }

     //Example: Code fragment corresponding to XML output *
     marshal( new Point3D(3,5,0), System.out );

     <!-- Example: XML output -->
     <!-- The element name is point3D not point -->
     <point3D>
       <x>3</x>
       <y>5</y>
       <z>0</z>
     </point3D>

     <!-- Example: XML schema definition -->
     <xs:element name="point3D" type="point3D"/>
     <xs:complexType name="point3D">
       <xs:complexContent>
         <xs:extension base="point">
           <xs:sequence>
             <xs:element name="z" type="xs:int"/>
           </xs:sequence>
         </xs:extension>
       </xs:complexContent>
     </xs:complexType>
Example 3: Associate a global element with XML Schema type to which the class is mapped.
     //Example: Code fragment
     @XmlRootElement(name="PriceElement")
     public class USPrice {
         @XmlElement
         public java.math.BigDecimal price;
     }

     <!-- Example: XML schema definition -->
     <xs:element name="PriceElement" type="USPrice"/>
     <xs:complexType name="USPrice">
       <xs:sequence>
         <xs:element name="price" type="xs:decimal"/>
       </sequence>
     </xs:complexType>

Since:
JAXB2.0

Optional Element Summary
String | name local name of the XML element.
String | namespace namespace name of the XML element.

namespace

public abstract String namespace
namespace name of the XML element.

If the value is "##default", then the XML namespace name is derived from the package of the class ( XmlSchema ). If the package is unnamed, then the XML namespace is the default empty namespace.

Default:
"##default"

name

public abstract String name
local name of the XML element.

If the value is "##default", then the name is derived from the class name.

Default:
"##default"
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlSchema

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlSchema

@Retention(value=RUNTIME)
@Target(value=PACKAGE)
public @interface XmlSchema

Maps a package name to a XML namespace.

Usage

The XmlSchema annotation can be used with the following program elements:

  • package
This is a package level annotation and follows the recommendations and restrictions contained in JSR 175, section III, "Annotations". Thus the usage is subject to the following constraints and recommendations.
  • There can only be one package declaration as noted in JSR 175, section III, "Annotations".
  • JSR 175 recommends package-info.java for package level annotations. JAXB Providers that follow this recommendation will allow the package level annotations to be defined in package-info.java.

Example 1: Customize name of XML namespace to which package is mapped.

    @javax.xml.bind.annotation.XmlSchema (
      namespace = "http://www.example.com/MYPO1"
    )

    <!-- XML Schema fragment -->
    <schema
      xmlns=...
      xmlns:po=....
      targetNamespace="http://www.example.com/MYPO1"
    >
    <!-- prefixes generated by default are implementation
            depedenent -->

Example 2: Customize namespace prefix, namespace URI mapping

    // Package level annotation
    @javax.xml.bind.annotation.XmlSchema (
      xmlns = {
        @javax.xml.bind.annotation.XmlNs(prefix = "po",
                   namespaceURI="http://www.example.com/myPO1"),

        @javax.xml.bind.annotation.XmlNs(prefix="xs",
                   namespaceURI="http://www.w3.org/2001/XMLSchema")
      )
    )

    <!-- XML Schema fragment -->
    <schema
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:po="http://www.example.com/PO1"
        targetNamespace="http://www.example.com/PO1">

Example 3: Customize elementFormDefault

    @javax.xml.bind.annotation.XmlSchema (
      elementFormDefault=XmlNsForm.UNQUALIFIED
      ...
    )

    <!-- XML Schema fragment -->
    <schema
        xmlns="http://www.w3.org/2001/XMLSchema"
        xmlns:po="http://www.example.com/PO1"
        elementFormDefault="unqualified">

Since:
JAXB2.0

Optional Element Summary
XmlNsForm | attributeFormDefault Namespace qualification for attributes.
XmlNsForm | elementFormDefault Namespace qualification for elements.
String | namespace Name of the XML namespace.
XmlNs[] | xmlns Customize the namespace URI, prefix associations.

xmlns

public abstract XmlNs[] xmlns
Customize the namespace URI, prefix associations. By default, the namespace prefixes for a XML namespace are generated by a JAXB Provider in an implementation dependent way.

Default:
{}

namespace

public abstract String namespace
Name of the XML namespace.

Default:
""

elementFormDefault

public abstract XmlNsForm elementFormDefault
Namespace qualification for elements. By default, element default attribute will be absent from the XML Schema fragment.

Default:
javax.xml.bind.annotation.XmlNsForm.UNSET

attributeFormDefault

public abstract XmlNsForm attributeFormDefault
Namespace qualification for attributes. By default, attributesFormDefault will be absent from the XML Schema fragment.

Default:
javax.xml.bind.annotation.XmlNsForm.UNSET
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlSchemaType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlSchemaType

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD,PACKAGE})
public @interface XmlSchemaType

Maps a Java type to a simple schema built-in type.

Usage

@XmlSchemaType annotation can be used with the following program elements:

  • a JavaBean property
  • field
  • package

@XmlSchemaType annotation defined for Java type applies to all references to the Java type from a property/field. A @XmlSchemaType annotation specified on the property/field overrides the @XmlSchemaType annotation specified at the package level.

This annotation can be used with the following annotations: XmlElement, XmlAttribute.

Example 1: Customize mapping of XMLGregorianCalendar on the field.

     //Example: Code fragment
     public class USPrice {
         @XmlElement
         @XmlSchemaType(name="date")
         public XMLGregorianCalendar date;
     }

     <!-- Example: Local XML Schema element -->
     <xs:complexType name="USPrice"/>
       <xs:sequence>
         <xs:element name="date" type="xs:date"/>
       </sequence>
     </xs:complexType>

Example 2: Customize mapping of XMLGregorianCalendar at package level

     package foo;
     @javax.xml.bind.annotation.XmlSchemaType(
          name="date", type=javax.xml.datatype.XMLGregorianCalendar.class)
     }

Since:
JAXB2.0

Required Element Summary
 String name
Optional Element Summary
String | namespace
Class | type If this annotation is used at the package level, then value of the type() must be specified.

Element Detail

name

public abstract String name

namespace

public abstract String namespace
Default:
"http://www.w3.org/2001/XMLSchema"

type

public abstract Class type
If this annotation is used at the package level, then value of the type() must be specified.

Default:
javax.xml.bind.annotation.XmlSchemaType.DEFAULT.class
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlSchemaType.DEFAULT

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.annotation
Class XmlSchemaType.DEFAULT

java.lang.Object
    extended by  javax.xml.bind.annotation.XmlSchemaType.DEFAULT
Enclosing class:
XmlSchemaType
public static final class XmlSchemaType.DEFAULT
extends Object

Used in XmlSchemaType.type() to signal that the type be inferred from the signature of the property.

Constructor Summary
XmlSchemaType.DEFAULT()
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XmlSchemaType.DEFAULT

public XmlSchemaType.DEFAULT()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XmlSchemaTypes

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlSchemaTypes

@Retention(value=RUNTIME)
@Target(value=PACKAGE)
public @interface XmlSchemaTypes

A container for multiple @XmlSchemaType annotations.

Multiple annotations of the same type are not allowed on a program element. This annotation therefore serves as a container annotation for multiple @XmlSchemaType annotations as follows:

 @XmlSchemaTypes({ @XmlSchemaType(...), @XmlSchemaType(...) })

The @XmlSchemaTypes annnotation can be used to define XmlSchemaType for different types at the package level.

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

Since:
JAXB2.0
See Also:
XmlSchemaType

Required Element Summary
 XmlSchemaType[] value
Collection of @XmlSchemaType annotations

Element Detail

value

public abstract XmlSchemaType[] value
Collection of @XmlSchemaType annotations

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.bind.annotation
Annotation Type XmlType

@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface XmlType

Maps a class or an enum type to a XML Schema type.

Usage

The @XmlType annnotation can be used with the following program elements:

  • a top level class
  • an enum type

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

Mapping a Class

A class maps to a XML Schema type. A class is a data container for values represented by properties and fields. A schema type is a data container for values represented by schema components within a schema type's content model (e.g. model groups, attributes etc).

To be mapped, a class must either have a public no-arg constructor or a static no-arg factory method. The static factory method can be specified in factoryMethod() and factoryClass() annotation elements. The static factory method or the no-arg constructor is used during unmarshalling to create an instance of this class. If both are present, the static factory method overrides the no-arg constructor.

A class maps to either a XML Schema complex type or a XML Schema simple type. The XML Schema type is derived based on the mapping of JavaBean properties and fields contained within the class. The schema type to which the class is mapped can either be named or anonymous. A class can be mapped to an anonymous schema type by annotating the class with @XmlType(name="").

Either a global element, local element or a local attribute can be associated with an anonymous type as follows:

  • global element: A global element of an anonymous type can be derived by annotating the class with @XmlRootElement. See Example 3 below.
  • local element: A JavaBean property that references a class annotated with @XmlType(name="") and is mapped to the element associated with the anonymous type. See Example 4 below.
  • attribute: A JavaBean property that references a class annotated with @XmlType(name="") and is mapped to the attribute associated with the anonymous type. See Example 5 below.
Mapping to XML Schema Complex Type
  • If class is annotated with @XmlType(name="") , it is mapped to an anonymous type otherwise, the class name maps to a complex type name. The XmlName() annotation element can be used to customize the name.
  • Properties and fields that are mapped to elements are mapped to a content model within a complex type. The annotation element propOrder() can be used to customize the content model to be xs:all or xs:sequence. It is used for specifying the order of XML elements in xs:sequence.
  • Properties and fields can be mapped to attributes within the complex type.
  • The targetnamespace of the XML Schema type can be customized using the annotation element namespace().

Mapping class to XML Schema simple type

A class can be mapped to a XML Schema simple type using the @XmlValue annotation. For additional details and examples, see @XmlValue annotation type.

The following table shows the mapping of the class to a XML Schema complex type or simple type. The notational symbols used in the table are:

  • -> : represents a mapping
  • [x]+ : one or more occurances of x
  • [ @XmlValue property ]: JavaBean property annotated with @XmlValue
  • X : don't care
Target propOrder ClassBody ComplexType SimpleType
Class {} [property]+ -> elements complexcontent
xs:all
Class non empty [property]+ -> elements complexcontent
xs:sequence
Class X no property -> element complexcontent
empty sequence
Class X 1 [ @XmlValue property] &&
[property]+ ->attributes 		simplecontent
Class X 1 [ @XmlValue property ]&&
no properties -> attribute 		simpletype

Mapping an enum type

An enum type maps to a XML schema simple type with enumeration facets. The following annotation elements are ignored since they are not meaningful: propOrder() , factoryMethod() , factoryClass() .

Usage with other annotations

This annotation can be used with the following annotations: XmlRootElement, XmlAccessorOrder, XmlAccessorType, XmlEnum. However, XmlAccessorOrder and XmlAccessorType are ignored when this annotation is used on an enum type.

Example 1: Map a class to a complex type with xs:sequence with a customized ordering of JavaBean properties.

   @XmlType(propOrder={"street", "city" , "state", "zip", "name" })
   public class USAddress {
     String getName() {..};
     void setName(String) {..};

     String getStreet() {..};
     void setStreet(String) {..};

     String getCity() {..};
     void setCity(String) {..};

     String getState() {..};
     void setState(String) {..};

     java.math.BigDecimal getZip() {..};
     void setZip(java.math.BigDecimal) {..};
   }

   <!-- XML Schema mapping for USAddress -->
   <xs:complexType name="USAddress">
     <xs:sequence>
       <xs:element name="street" type="xs:string"/>
       <xs:element name="city" type="xs:string"/>
       <xs:element name="state" type="xs:string"/>
       <xs:element name="zip" type="xs:decimal"/>
       <xs:element name="name" type="xs:string"/>
     </xs:all>
   </xs:complexType>

Example 2: Map a class to a complex type with xs:all

 @XmlType(propOrder={})
 public class USAddress { ...}

 <!-- XML Schema mapping for USAddress -->
 <xs:complexType name="USAddress">
   <xs:all>
     <xs:element name="name" type="xs:string"/>
     <xs:element name="street" type="xs:string"/>
     <xs:element name="city" type="xs:string"/>
     <xs:element name="state" type="xs:string"/>
     <xs:element name="zip" type="xs:decimal"/>
   </xs:sequence>
 </xs:complexType>

Example 3: Map a class to a global element with an anonymous type.

   @XmlRootElement
   @XmlType(name="")
   public class USAddress { ...}

   <!-- XML Schema mapping for USAddress -->
   <xs:element name="USAddress">
     <xs:complexType>
       <xs:sequence>
         <xs:element name="name" type="xs:string"/>
         <xs:element name="street" type="xs:string"/>
         <xs:element name="city" type="xs:string"/>
         <xs:element name="state" type="xs:string"/>
         <xs:element name="zip" type="xs:decimal"/>
       </xs:sequence>
     </xs:complexType>
   </xs:element>

Example 4: Map a property to a local element with anonmyous type.

   //Example: Code fragment
   public class Invoice {
       USAddress addr;
           ...
       }

   @XmlType(name="")
   public class USAddress { ... }
   }

   <!-- XML Schema mapping for USAddress -->
   <xs:complexType name="Invoice">
     <xs:sequence>
       <xs:element name="addr">
         <xs:complexType>
           <xs:element name="name", type="xs:string"/>
           <xs:element name="city", type="xs:string"/>
           <xs:element name="city" type="xs:string"/>
           <xs:element name="state" type="xs:string"/>
           <xs:element name="zip" type="xs:decimal"/>
         </xs:complexType>
       ...
     </xs:sequence>
   </xs:complexType>

Example 5: Map a property to an attribute with anonymous type.

     //Example: Code fragment
     public class Item {
         public String name;
         @XmlAttribute
         public USPrice price;
     }

     // map class to anonymous simple type.
     @XmlType(name="")
     public class USPrice {
         @XmlValue
         public java.math.BigDecimal price;
     }

     <!-- Example: XML Schema fragment -->
     <xs:complexType name="Item">
       <xs:sequence>
         <xs:element name="name" type="xs:string"/>
         <xs:attribute name="price">
           <xs:simpleType>
             <xs:restriction base="xs:decimal"/>
           </xs:simpleType>
         </xs:attribute>
       </xs:sequence>
     </xs:complexType>

Example 6: Define a factoryClass and factoryMethod

      @XmlType(name="USAddressType", factoryClass=USAddressFactory.class,
      factoryMethod="getUSAddress")
      public class USAddress {

          private String city;
          private String name;
          private String state;
          private String street;
          private int    zip;

      public USAddress(String name, String street, String city,
          String state, int zip) {
          this.name = name;
          this.street = street;
          this.city = city;
          this.state = state;
          this.zip = zip;
      }
  }

  public class USAddressFactory {
      public static USAddress getUSAddress(){
       return new USAddress("Mark Baker", "23 Elm St",
          "Dayton", "OH", 90952);
  }

Example 7: Define factoryMethod and use the default factoryClass

      @XmlType(name="USAddressType", factoryMethod="getNewInstance")
      public class USAddress {

          private String city;
          private String name;
          private String state;
          private String street;
          private int    zip;

          private USAddress() {}

          public static USAddress getNewInstance(){
              return new USAddress();
          }
      }

Since:
JAXB2.0
See Also:
XmlElement, XmlAttribute, XmlValue, XmlSchema

Optional Element Summary
Class | factoryClass Class containing a no-arg factory method for creating an instance of this class.
String | factoryMethod Name of a no-arg factory method in the class specified in factoryClass factoryClass().
String | name Name of the XML Schema type which the class is mapped.
String | namespace Name of the target namespace of the XML Schema type.
String[] | propOrder Specifies the order for XML Schema elements when class is mapped to a XML Schema complex type.

name

public abstract String name
Name of the XML Schema type which the class is mapped.

Default:
"##default"

propOrder

public abstract String[] propOrder
Specifies the order for XML Schema elements when class is mapped to a XML Schema complex type.

Refer to the table for how the propOrder affects the mapping of class

The propOrder is a list of names of JavaBean properties in the class. Each name in the list is the name of a Java identifier of the JavaBean property. The order in which JavaBean properties are listed is the order of XML Schema elements to which the JavaBean properties are mapped.

All of the JavaBean properties being mapped to XML Schema elements must be listed.

A JavaBean property or field listed in propOrder must not be transient or annotated with @XmlTransient.

The default ordering of JavaBean properties is determined by @XmlAccessorOrder.

Default:
""

namespace

public abstract String namespace
Name of the target namespace of the XML Schema type. By default, this is the target namespace to which the package containing the class is mapped.

Default:
"##default"

factoryClass

public abstract Class factoryClass
Class containing a no-arg factory method for creating an instance of this class. The default is this class.

If factoryClass is DEFAULT.class and factoryMethod is "", then there is no static factory method.

If factoryClass is DEFAULT.class and factoryMethod is not "", then factoryMethod is the name of a static factory method in this class.

If factoryClass is not DEFAULT.class, then factoryMethod must not be "" and must be the name of a static factory method specified in factoryClass.

Default:
javax.xml.bind.annotation.XmlType.DEFAULT.class

factoryMethod

public abstract String factoryMethod
Name of a no-arg factory method in the class specified in factoryClass factoryClass().

Default:
""
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


XmlType.DEFAULT

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.annotation
Class XmlType.DEFAULT

java.lang.Object
    extended by  javax.xml.bind.annotation.XmlType.DEFAULT
Enclosing class:
XmlType
public static final class XmlType.DEFAULT
extends Object

Used in XmlType.factoryClass() to signal that either factory mehod is not used or that it's in the class with this XmlType itself.

Constructor Summary
XmlType.DEFAULT()
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XmlType.DEFAULT

public XmlType.DEFAULT()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


attachment

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.bind.attachment

This package is implemented by a MIME-based package processor that enables the interpretation and creation of optimized binary data within an MIME-based package format.

See:
Description

Class Summary
AttachmentMarshaller | Enable JAXB marshalling to optimize storage of binary data.
AttachmentUnmarshaller | Enables JAXB unmarshalling of a root document containing optimized binary data formats.

Package javax.xml.bind.attachment Description

This package is implemented by a MIME-based package processor that enables the interpretation and creation of optimized binary data within an MIME-based package format.

Soap MTOM[1], XOP([2][3]) and WS-I AP[4] standardize approaches to optimized transmission of binary datatypes as an attachment. To optimally support these standards within a message passing environment, this package enables an integrated solution between a MIME-based package processor and JAXB unmarshall/marshal processes.

Package Specification

  • JAXB Specification

Related Standards

  • [1]SOAP Message Transmission Optimization Mechanism
  • [2]XML-binary Optimized Packaging
  • [3]WS-I Attachments Profile Version 1.0.
  • [4]Describing Media Content of Binary Data in XML

Since:
JAXB 2.0
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.bind.attachment Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.bind.attachment

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.bind.attachment.AttachmentMarshaller
    • javax.xml.bind.attachment.AttachmentUnmarshaller
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.bind.attachment

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.bind.attachment

Packages that use javax.xml.bind.attachment
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

Classes in javax.xml.bind.attachment used by javax.xml.bind
AttachmentMarshaller
Enable JAXB marshalling to optimize storage of binary data.
AttachmentUnmarshaller
Enables JAXB unmarshalling of a root document containing optimized binary data formats.

Classes in javax.xml.bind.attachment used by javax.xml.bind.helpers
AttachmentMarshaller
Enable JAXB marshalling to optimize storage of binary data.
AttachmentUnmarshaller
Enables JAXB unmarshalling of a root document containing optimized binary data formats.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AttachmentMarshaller

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.attachment
Class AttachmentMarshaller

java.lang.Object
    extended by  javax.xml.bind.attachment.AttachmentMarshaller

public abstract class AttachmentMarshaller
extends Object

Enable JAXB marshalling to optimize storage of binary data.

This API enables an efficient cooperative creation of optimized binary data formats between a JAXB marshalling process and a MIME-based package processor. A JAXB implementation marshals the root body of a MIME-based package, delegating the creation of referenceable MIME parts to the MIME-based package processor that implements this abstraction.

XOP processing is enabled when isXOPPackage() is true. See addMtomAttachment(DataHandler, String, String) for details.

WS-I Attachment Profile 1.0 is supported by addSwaRefAttachment(DataHandler) being called by the marshaller for each JAXB property related to {http://ws-i.org/profiles/basic/1.1/xsd}swaRef.

Since:
JAXB 2.0
See Also:
Marshaller.setAttachmentMarshaller(AttachmentMarshaller), XML-binary Optimized Packaging, WS-I Attachments Profile Version 1.0.

Constructor Summary
AttachmentMarshaller()
Method Summary
abstract String | addMtomAttachment(byte[] data, int offset, int length, String mimeType, String elementNamespace, String elementLocalName) Consider binary data for optimized binary storage as an attachment.
abstract String | addMtomAttachment(DataHandler data, String elementNamespace, String elementLocalName) Consider MIME content data for optimized binary storage as an attachment.
abstract String | addSwaRefAttachment(DataHandler data) Add MIME data as an attachment and return attachment's content-id, cid.
boolean | isXOPPackage() Read-only property that returns true if JAXB marshaller should enable XOP creation.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AttachmentMarshaller

public AttachmentMarshaller()
Method Detail

addMtomAttachment

public abstract String addMtomAttachment(DataHandler data,
                                         String elementNamespace,
                                         String elementLocalName)

Consider MIME content data for optimized binary storage as an attachment.

This method is called by JAXB marshal process when isXOPPackage() is true, for each element whose datatype is "base64Binary", as described in Step 3 in Creating XOP Packages.

The method implementor determines whether data shall be attached separately or inlined as base64Binary data. If the implementation chooses to optimize the storage of the binary data as a MIME part, it is responsible for attaching data to the MIME-based package, and then assigning an unique content-id, cid, that identifies the MIME part within the MIME message. This method returns the cid, which enables the JAXB marshaller to marshal a XOP element that refers to that cid in place of marshalling the binary data. When the method returns null, the JAXB marshaller inlines data as base64binary data.

The caller of this method is required to meet the following constraint. If the element infoset item containing data has the attribute xmime:contentType or if the JAXB property/field representing datais annotated with a known MIME type, data.getContentType() should be set to that MIME type.

The elementNamespace and elementLocalName parameters provide the context that contains the binary data. This information could be used by the MIME-based package processor to determine if the binary data should be inlined or optimized as an attachment.

Parameters:
data - represents the data to be attached. Must be non-null.
elementNamespace - the namespace URI of the element that encloses the base64Binary data. Can be empty but never null.
elementLocalName - The local name of the element. Always a non-null valid string.
Returns:
a valid content-id URI (see RFC 2387) that identifies the attachment containing data. Otherwise, null if the attachment was not added and should instead be inlined in the message.
See Also:
XML-binary Optimized Packaging, Describing Media Content of Binary Data in XML

addMtomAttachment

public abstract String addMtomAttachment(byte[] data,
                                         int offset,
                                         int length,
                                         String mimeType,
                                         String elementNamespace,
                                         String elementLocalName)

Consider binary data for optimized binary storage as an attachment.

Since content type is not known, the attachment's MIME content type must be set to "application/octet-stream".

The elementNamespace and elementLocalName parameters provide the context that contains the binary data. This information could be used by the MIME-based package processor to determine if the binary data should be inlined or optimized as an attachment.

Parameters:
data - represents the data to be attached. Must be non-null. The actual data region is specified by (data,offset,length) tuple.
offset - The offset within the array of the first byte to be read; must be non-negative and no larger than array.length
length - The number of bytes to be read from the given array; must be non-negative and no larger than array.length
mimeType - If the data has an associated MIME type known to JAXB, that is passed as this parameter. If none is known, "application/octet-stream". This parameter may never be null.
elementNamespace - the namespace URI of the element that encloses the base64Binary data. Can be empty but never null.
elementLocalName - The local name of the element. Always a non-null valid string.
Returns:
content-id URI, cid, to the attachment containing data or null if data should be inlined.
See Also:
addMtomAttachment(DataHandler, String, String)

isXOPPackage

public boolean isXOPPackage()

Read-only property that returns true if JAXB marshaller should enable XOP creation.

This value must not change during the marshalling process. When this value is true, the addMtomAttachment(...) method is invoked when the appropriate binary datatypes are encountered by the marshal process.

Marshaller.marshal() must throw IllegalStateException if this value is true and the XML content to be marshalled violates Step 1 in Creating XOP Pacakges http://www.w3.org/TR/2005/REC-xop10-20050125/#creating_xop_packages. "Ensure the Original XML Infoset contains no element information item with a [namespace name] of "http://www.w3.org/2004/08/xop/include" and a [local name] of Include"

When this method returns true and during the marshal process at least one call to addMtomAttachment(...) returns a content-id, the MIME-based package processor must label the root part with the application/xop+xml media type as described in Step 5 of Creating XOP Pacakges.

Returns:
true when MIME context is a XOP Package.

addSwaRefAttachment

public abstract String addSwaRefAttachment(DataHandler data)

Add MIME data as an attachment and return attachment's content-id, cid.

This method is called by JAXB marshal process for each element/attribute typed as {http://ws-i.org/profiles/basic/1.1/xsd}swaRef. The MIME-based package processor implementing this method is responsible for attaching the specified data to a MIME attachment, and generating a content-id, cid, that uniquely identifies the attachment within the MIME-based package.

Caller inserts the returned content-id, cid, into the XML content being marshalled.

Parameters:
data - represents the data to be attached. Must be non-null.
Returns:
must be a valid URI used as cid. Must satisfy Conformance Requirement R2928 from WS-I Attachments Profile Version 1.0.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AttachmentUnmarshaller

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.attachment
Class AttachmentUnmarshaller

java.lang.Object
    extended by  javax.xml.bind.attachment.AttachmentUnmarshaller

public abstract class AttachmentUnmarshaller
extends Object

Enables JAXB unmarshalling of a root document containing optimized binary data formats.

This API enables an efficient cooperative processing of optimized binary data formats between a JAXB 2.0 implementation and MIME-based package processor (MTOM/XOP and WS-I AP 1.0). JAXB unmarshals the body of a package, delegating the understanding of the packaging format being used to a MIME-based package processor that implements this abstract class.

This abstract class identifies if a package requires XOP processing, isXOPPackage() and provides retrieval of binary content stored as attachments by content-id.

Identifying the content-id, cid, to pass to getAttachment*(String cid)

  • For XOP processing, the infoset representation of the cid is described in step 2a in Section 3.2 Interpreting XOP Packages
  • For WS-I AP 1.0, the cid is identified as an element or attribute of type ref:swaRef specified in Section 4.4 Referencing Attachments from the SOAP Envelope

Since:
JAXB 2.0
See Also:
Unmarshaller.setAttachmentUnmarshaller(AttachmentUnmarshaller), XML-binary Optimized Packaging, WS-I Attachments Profile Version 1.0., Describing Media Content of Binary Data in XML

Constructor Summary
AttachmentUnmarshaller()
Method Summary
abstract byte[] | getAttachmentAsByteArray(String cid) Retrieve the attachment identified by content-id, cid, as a byte[]
abstract DataHandler | getAttachmentAsDataHandler(String cid) Lookup MIME content by content-id, cid, and return as a DataHandler.
boolean | isXOPPackage() Read-only property that returns true if JAXB unmarshaller needs to perform XOP processing.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AttachmentUnmarshaller

public AttachmentUnmarshaller()
Method Detail

getAttachmentAsDataHandler

public abstract DataHandler getAttachmentAsDataHandler(String cid)

Lookup MIME content by content-id, cid, and return as a DataHandler.

The returned DataHandler instance must be configured to meet the following required mapping constaint.
Required Mappings between MIME and Java Types
MIME Type | Java Type
DataHandler.getContentType() | instanceof DataHandler.getContent()
image/gif | java.awt.Image
image/jpeg | java.awt.Image
text/xml or application/xml | javax.xml.transform.Source
Note that it is allowable to support additional mappings.

Parameters:
cid - It is expected to be a valid lexical form of the XML Schema xs:anyURI datatype. If isXOPPackage() ==true, it must be a valid URI per the cid: URI scheme (see RFC 2387)
Returns:
a DataHandler that represents the MIME attachment.
Throws:
IllegalArgumentException - if the attachment for the given cid is not found.

getAttachmentAsByteArray

public abstract byte[] getAttachmentAsByteArray(String cid)

Retrieve the attachment identified by content-id, cid, as a byte[]

.

Parameters:
cid - It is expected to be a valid lexical form of the XML Schema xs:anyURI datatype. If isXOPPackage() ==true, it must be a valid URI per the cid: URI scheme (see RFC 2387)
Returns:
byte[] representation of attachment identified by cid.
Throws:
IllegalArgumentException - if the attachment for the given cid is not found.

isXOPPackage

public boolean isXOPPackage()

Read-only property that returns true if JAXB unmarshaller needs to perform XOP processing.

This method returns true when the constraints specified in Identifying XOP Documents are met. This value must not change during the unmarshalling process.

Returns:
true when MIME context is a XOP Document.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.xml.bind.attachment.AttachmentMarshaller

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.attachment.AttachmentMarshaller

Packages that use AttachmentMarshaller
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

Uses of AttachmentMarshaller in javax.xml.bind

Methods in javax.xml.bind that return AttachmentMarshaller
 AttachmentMarshaller Marshaller.getAttachmentMarshaller()

Methods in javax.xml.bind with parameters of type AttachmentMarshaller
 void Marshaller.setAttachmentMarshaller(AttachmentMarshaller am)
Associate a context that enables binary data within an XML document to be transmitted as XML-binary optimized attachment.

Uses of AttachmentMarshaller in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers that return AttachmentMarshaller
 AttachmentMarshaller AbstractMarshallerImpl.getAttachmentMarshaller()

Methods in javax.xml.bind.helpers with parameters of type AttachmentMarshaller
 void AbstractMarshallerImpl.setAttachmentMarshaller(AttachmentMarshaller am)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.attachment.AttachmentUnmarshaller

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.attachment.AttachmentUnmarshaller

Packages that use AttachmentUnmarshaller
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

Uses of AttachmentUnmarshaller in javax.xml.bind

Methods in javax.xml.bind that return AttachmentUnmarshaller
 AttachmentUnmarshaller Unmarshaller.getAttachmentUnmarshaller()

Methods in javax.xml.bind with parameters of type AttachmentUnmarshaller
 void Unmarshaller.setAttachmentUnmarshaller(AttachmentUnmarshaller au)
Associate a context that resolves cid's, content-id URIs, to binary data passed as attachments.

Uses of AttachmentUnmarshaller in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers that return AttachmentUnmarshaller
 AttachmentUnmarshaller AbstractUnmarshallerImpl.getAttachmentUnmarshaller()

Methods in javax.xml.bind.helpers with parameters of type AttachmentUnmarshaller
 void AbstractUnmarshallerImpl.setAttachmentUnmarshaller(AttachmentUnmarshaller au)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Binder

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Class Binder<XmlNode>

java.lang.Object
    extended by  javax.xml.bind.Binder<XmlNode>

public abstract class Binder<XmlNode>
extends Object

Enable synchronization between XML infoset nodes and JAXB objects representing same XML document.

An instance of this class maintains the association between XML nodes of an infoset preserving view and a JAXB representation of an XML document. Navigation between the two views is provided by the methods getXMLNode(Object) and getJAXBNode(Object).

Modifications can be made to either the infoset preserving view or the JAXB representation of the document while the other view remains unmodified. The binder is able to synchronize the changes made in the modified view back into the other view using the appropriate Binder update methods, updateXML(Object, Object) or updateJAXB(Object).

A typical usage scenario is the following:

  • load XML document into an XML infoset representation
  • unmarshal(Object) XML infoset view to JAXB view. (Note to conserve resources, it is possible to only unmarshal a subtree of the XML infoset view to the JAXB view.)
  • application access/updates JAXB view of XML document.
  • updateXML(Object) synchronizes modifications to JAXB view back into the XML infoset view. Update operation preserves as much of original XML infoset as possible (i.e. comments, PI, ...)

A Binder instance is created using the factory method JAXBContext.createBinder() or JAXBContext.createBinder(Class).

The template parameter, XmlNode, is the root interface/class for the XML infoset preserving representation. A Binder implementation is required to minimally support an XmlNode value of org.w3c.dom.Node.class. A Binder implementation can support alternative XML infoset preserving representations.

Since:
JAXB 2.0

Constructor Summary
Binder()
Method Summary
abstract  ValidationEventHandler getEventHandler()
Return the current event handler or the default event handler if one hasn't been set.
abstract  Object getJAXBNode(XmlNode xmlNode)
Gets the JAXB object associated with the given XML element.
abstract  Object getProperty(String name)
Get the particular property in the underlying implementation of Binder.
abstract  Schema getSchema()
Gets the last Schema object (including null) set by the setSchema(Schema) method.
abstract  XmlNode getXMLNode(Object jaxbObject)
Gets the XML element associated with the given JAXB object.
abstract  void marshal(Object jaxbObject, XmlNode xmlNode)
Marshal a JAXB object tree to a new XML document.
abstract  void setEventHandler(ValidationEventHandler handler)
Allow an application to register a ValidationEventHandler.
abstract  void setProperty(String name, Object value)
Set the particular property in the underlying implementation of Binder.
abstract  void setSchema(Schema schema)
Specifies whether marshal, unmarshal and update methods performs validation on their XML content.
abstract  Object unmarshal(XmlNode xmlNode)
Unmarshal XML infoset view to a JAXB object tree.
abstract
<T> JAXBElement<T>
unmarshal(XmlNode xmlNode, Class<T> declaredType)
Unmarshal XML root element by provided declaredType to a JAXB object tree.
abstract  Object updateJAXB(XmlNode xmlNode)
Takes an XML node and updates its associated JAXB object and its descendants.
abstract  XmlNode updateXML(Object jaxbObject)
Takes an JAXB object and updates its associated XML node and its descendants.
abstract  XmlNode updateXML(Object jaxbObject, XmlNode xmlNode)
Changes in JAXB object tree are updated in its associated XML parse tree.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Binder

public Binder()
Method Detail

unmarshal

public abstract Object unmarshal(XmlNode xmlNode)
                          throws JAXBException
Unmarshal XML infoset view to a JAXB object tree.

This method is similar to Unmarshaller.unmarshal(Node) with the addition of maintaining the association between XML nodes and the produced JAXB objects, enabling future update operations, updateXML(Object, Object) or updateJAXB(Object).

When getSchema() is non-null, xmlNode and its descendants is validated during this operation.

This method throws UnmarshalException when the Binder's JAXBContext does not have a mapping for the XML element name or the type, specifiable via @xsi:type, of xmlNode to a JAXB mapped class. The method unmarshal(Object, Class) enables an application to specify the JAXB mapped class that the xmlNode should be mapped to.

Parameters:
xmlNode - the document/element to unmarshal XML data from.
Returns:
the newly created root object of the JAXB object tree.
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Binder is unable to perform the XML to Java binding.
IllegalArgumentException - If the node parameter is null

unmarshal

public abstract <T> JAXBElement<T> unmarshal(XmlNode xmlNode,
                                             Class<T> declaredType)
                                  throws JAXBException
Unmarshal XML root element by provided declaredType to a JAXB object tree.

Implements Unmarshal by Declared Type

This method is similar to Unmarshaller.unmarshal(Node, Class) with the addition of maintaining the association between XML nodes and the produced JAXB objects, enabling future update operations, updateXML(Object, Object) or updateJAXB(Object).

When getSchema() is non-null, xmlNode and its descendants is validated during this operation.

Parameters:
xmlNode - the document/element to unmarshal XML data from.
declaredType - appropriate JAXB mapped class to hold node's XML data.
Returns:
JAXB Element representation of node
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Binder is unable to perform the XML to Java binding.
IllegalArgumentException - If any of the input parameters are null
Since:
JAXB2.0

marshal

public abstract void marshal(Object jaxbObject,
                             XmlNode xmlNode)
                      throws JAXBException
Marshal a JAXB object tree to a new XML document.

This method is similar to Marshaller.marshal(Object, Node) with the addition of maintaining the association between JAXB objects and the produced XML nodes, enabling future update operations such as updateXML(Object, Object) or updateJAXB(Object).

When getSchema() is non-null, the marshalled xml content is validated during this operation.

Parameters:
jaxbObject - The content tree to be marshalled.
xmlNode - The parameter must be a Node that accepts children.
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Binder is unable to marshal jaxbObject (or any object reachable from jaxbObject).
IllegalArgumentException - If any of the method parameters are null

getXMLNode

public abstract XmlNode getXMLNode(Object jaxbObject)
Gets the XML element associated with the given JAXB object.

Once a JAXB object tree is associated with an XML fragment, this method enables navigation between the two trees.

An association between an XML element and a JAXB object is established by the bind methods and the update methods. Note that this association is partial; not all XML elements have associated JAXB objects, and not all JAXB objects have associated XML elements.

Parameters:
jaxbObject - An instance that is reachable from a prior call to a bind or update method that returned a JAXB object tree.
Returns:
null if the specified JAXB object is not known to this Binder, or if it is not associated with an XML element.
Throws:
IllegalArgumentException - If the jaxbObject parameter is null

getJAXBNode

public abstract Object getJAXBNode(XmlNode xmlNode)
Gets the JAXB object associated with the given XML element.

Once a JAXB object tree is associated with an XML fragment, this method enables navigation between the two trees.

An association between an XML element and a JAXB object is established by the unmarshal, marshal and update methods. Note that this association is partial; not all XML elements have associated JAXB objects, and not all JAXB objects have associated XML elements.

Returns:
null if the specified XML node is not known to this Binder, or if it is not associated with a JAXB object.
Throws:
IllegalArgumentException - If the node parameter is null

updateXML

public abstract XmlNode updateXML(Object jaxbObject)
                           throws JAXBException
Takes an JAXB object and updates its associated XML node and its descendants.

This is a convenience method of:

 updateXML( jaxbObject, getXMLNode(jaxbObject));

Throws:
JAXBException - If any unexpected problem occurs updating corresponding XML content.
IllegalArgumentException - If the jaxbObject parameter is null

updateXML

public abstract XmlNode updateXML(Object jaxbObject,
                                  XmlNode xmlNode)
                           throws JAXBException
Changes in JAXB object tree are updated in its associated XML parse tree.

This operation can be thought of as an "in-place" marshalling. The difference is that instead of creating a whole new XML tree, this operation updates an existing tree while trying to preserve the XML as much as possible.

For example, unknown elements/attributes in XML that were not bound to JAXB will be left untouched (whereas a marshalling operation would create a new tree that doesn't contain any of those.)

As a side-effect, this operation updates the association between XML nodes and JAXB objects.

Parameters:
jaxbObject - root of potentially modified JAXB object tree
xmlNode - root of update target XML parse tree
Returns:
Returns the updated XML node. Typically, this is the same node you passed in as xmlNode, but it maybe a different object, for example when the tag name of the object has changed.
Throws:
JAXBException - If any unexpected problem occurs updating corresponding XML content.
IllegalArgumentException - If any of the input parameters are null

updateJAXB

public abstract Object updateJAXB(XmlNode xmlNode)
                           throws JAXBException
Takes an XML node and updates its associated JAXB object and its descendants.

This operation can be thought of as an "in-place" unmarshalling. The difference is that instead of creating a whole new JAXB tree, this operation updates an existing tree, reusing as much JAXB objects as possible.

As a side-effect, this operation updates the association between XML nodes and JAXB objects.

Returns:
Returns the updated JAXB object. Typically, this is the same object that was returned from earlier marshal(Object,Object) or updateJAXB(Object) method invocation, but it maybe a different object, for example when the name of the XML element has changed.
Throws:
JAXBException - If any unexpected problem occurs updating corresponding JAXB mapped content.
IllegalArgumentException - If node parameter is null

setSchema

public abstract void setSchema(Schema schema)
Specifies whether marshal, unmarshal and update methods performs validation on their XML content.

Parameters:
schema - set to null to disable validation.
See Also:
Unmarshaller.setSchema(Schema)

getSchema

public abstract Schema getSchema()
Gets the last Schema object (including null) set by the setSchema(Schema) method.

Returns:
the Schema object for validation or null if not present

setEventHandler

public abstract void setEventHandler(ValidationEventHandler handler)
                              throws JAXBException
Allow an application to register a ValidationEventHandler.

The ValidationEventHandler will be called by the JAXB Provider if any validation errors are encountered during calls to any of the Binder unmarshal, marshal and update methods.

Calling this method with a null parameter will cause the Binder to revert back to the default default event handler.

Parameters:
handler - the validation event handler
Throws:
JAXBException - if an error was encountered while setting the event handler

getEventHandler

public abstract ValidationEventHandler getEventHandler()
                                                throws JAXBException
Return the current event handler or the default event handler if one hasn't been set.

Returns:
the current ValidationEventHandler or the default event handler if it hasn't been set
Throws:
JAXBException - if an error was encountered while getting the current event handler

setProperty

public abstract void setProperty(String name,
                                 Object value)
                          throws PropertyException
Set the particular property in the underlying implementation of Binder. This method can only be used to set one of the standard JAXB defined unmarshal/marshal properties or a provider specific property for binder, unmarshal or marshal. Attempting to set an undefined property will result in a PropertyException being thrown. See Supported Unmarshal Properties and Supported Marshal Properties.

Parameters:
name - the name of the property to be set. This value can either be specified using one of the constant fields or a user supplied string.
value - the value of the property to be set
Throws:
PropertyException - when there is an error processing the given property or value
IllegalArgumentException - If the name parameter is null

getProperty

public abstract Object getProperty(String name)
                            throws PropertyException
Get the particular property in the underlying implementation of Binder. This method can only be used to get one of the standard JAXB defined unmarshal/marshal properties or a provider specific property for binder, unmarshal or marshal. Attempting to get an undefined property will result in a PropertyException being thrown. See Supported Unmarshal Properties and Supported Marshal Properties.

Parameters:
name - the name of the property to retrieve
Returns:
the value of the requested property
Throws:
PropertyException - when there is an error retrieving the given property or value property name
IllegalArgumentException - If the name parameter is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.xml.bind.Binder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.Binder

Packages that use Binder
javax.xml.bind Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.

Uses of Binder in javax.xml.bind

Methods in javax.xml.bind that return Binder
 Binder<Node> JAXBContext.createBinder()
Creates a Binder for W3C DOM.
<T> Binder<T>
JAXBContext.createBinder(Class<T> domType)
Creates a Binder object that can be used for associative/in-place unmarshalling/marshalling.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.DatatypeConverter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.DatatypeConverter

No usage of javax.xml.bind.DatatypeConverter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.JAXBContext

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.JAXBContext

Packages that use JAXBContext
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.util | Useful client utility classes.
javax.xml.ws | This package contains the core JAX-WS APIs.
javax.xml.ws.handler.soap | This package defines APIs for SOAP message handlers.
javax.xml.ws.spi | This package defines SPIs for JAX-WS 2.0.

Uses of JAXBContext in javax.xml.bind

Methods in javax.xml.bind that return JAXBContext
static JAXBContext | JAXBContext.newInstance(Class... classesToBeBound) Obtain a new instance of a JAXBContext class.
static JAXBContext | JAXBContext.newInstance(Class[] classesToBeBound, Map<String,?> properties) Obtain a new instance of a JAXBContext class.
static JAXBContext | JAXBContext.newInstance(String contextPath) Obtain a new instance of a JAXBContext class.
static JAXBContext | JAXBContext.newInstance(String contextPath, ClassLoader classLoader) Obtain a new instance of a JAXBContext class.
static JAXBContext | JAXBContext.newInstance(String contextPath, ClassLoader classLoader, Map<String,?> properties) Obtain a new instance of a JAXBContext class.

Uses of JAXBContext in javax.xml.bind.util

Constructors in javax.xml.bind.util with parameters of type JAXBContext
JAXBResult(JAXBContext context)
Creates a new instance that uses the specified JAXBContext to unmarshal.
JAXBSource(JAXBContext context, Object contentObject)
Creates a new Source for the given content object.

Uses of JAXBContext in javax.xml.ws

Methods in javax.xml.ws with parameters of type JAXBContext
Dispatch<Object> | Service.createDispatch(QName portName, JAXBContext context, Service.Mode mode) Creates a Dispatch instance for use with JAXB generated objects.
Object | LogicalMessage.getPayload(JAXBContext context) Gets the message payload as a JAXB object.
void | LogicalMessage.setPayload(Object payload, JAXBContext context) Sets the message payload

Uses of JAXBContext in javax.xml.ws.handler.soap

Methods in javax.xml.ws.handler.soap with parameters of type JAXBContext
 Object[] SOAPMessageContext.getHeaders(QName header, JAXBContext context, boolean allRoles)
Gets headers that have a particular qualified name from the message in the message context.

Uses of JAXBContext in javax.xml.ws.spi

Methods in javax.xml.ws.spi with parameters of type JAXBContext
abstract  Dispatch<Object> ServiceDelegate.createDispatch(QName portName, JAXBContext context, Service.Mode mode)
Creates a Dispatch instance for use with JAXB generated objects.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.JAXBElement

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.JAXBElement

Packages that use JAXBElement
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

Uses of JAXBElement in javax.xml.bind

Methods in javax.xml.bind that return JAXBElement
<T> JAXBElement<T>
Unmarshaller.unmarshal(Node node, Class<T> declaredType)
Unmarshal XML data by JAXB mapped declaredType and return the resulting content tree.
<T> JAXBElement<T>
Unmarshaller.unmarshal(Source source, Class<T> declaredType)
Unmarshal XML data from the specified XML Source by declaredType and return the resulting content tree.
<T> JAXBElement<T>
Unmarshaller.unmarshal(XMLEventReader reader, Class<T> declaredType)
Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.
abstract
<T> JAXBElement<T>
Binder.unmarshal(XmlNode xmlNode, Class<T> declaredType)
Unmarshal XML root element by provided declaredType to a JAXB object tree.
<T> JAXBElement<T>
Unmarshaller.unmarshal(XMLStreamReader reader, Class<T> declaredType)
Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.

Uses of JAXBElement in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers that return JAXBElement
<T> JAXBElement<T>
AbstractUnmarshallerImpl.unmarshal(Node node, Class<T> expectedType)
<T> JAXBElement<T>
AbstractUnmarshallerImpl.unmarshal(Source source, Class<T> expectedType)
<T> JAXBElement<T>
AbstractUnmarshallerImpl.unmarshal(XMLEventReader reader, Class<T> expectedType)
<T> JAXBElement<T>
AbstractUnmarshallerImpl.unmarshal(XMLStreamReader reader, Class<T> expectedType)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.JAXBElement.GlobalScope

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.JAXBElement.GlobalScope

No usage of javax.xml.bind.JAXBElement.GlobalScope

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.JAXBException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.JAXBException

Packages that use JAXBException
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.bind.util | Useful client utility classes.

Uses of JAXBException in javax.xml.bind

Subclasses of JAXBException in javax.xml.bind
class | MarshalException This exception indicates that an error has occurred while performing a marshal operation that the provider is unable to recover from.
class | PropertyException This exception indicates that an error was encountered while getting or setting a property.
class | UnmarshalException This exception indicates that an error has occurred while performing an unmarshal operation that prevents the JAXB Provider from completing the operation.
class | ValidationException This exception indicates that an error has occurred while performing a validate operation.

Methods in javax.xml.bind that throw JAXBException
abstract  Marshaller JAXBContext.createMarshaller()
Create a Marshaller object that can be used to convert a java content tree into XML data.
abstract  Unmarshaller JAXBContext.createUnmarshaller()
Create an Unmarshaller object that can be used to convert XML data into a java content tree.
abstract  Validator JAXBContext.createValidator()
Deprecated. since JAXB2.0
 ValidationEventHandler Validator.getEventHandler()
Deprecated. since JAXB2.0
 ValidationEventHandler Marshaller.getEventHandler()
Return the current event handler or the default event handler if one hasn't been set.
 ValidationEventHandler Unmarshaller.getEventHandler()
Return the current event handler or the default event handler if one hasn't been set.
abstract  ValidationEventHandler Binder.getEventHandler()
Return the current event handler or the default event handler if one hasn't been set.
 Node Marshaller.getNode(Object contentTree)
Get a DOM tree view of the content tree(Optional).
 Object UnmarshallerHandler.getResult()
Obtains the unmarshalled result.
 boolean Unmarshaller.isValidating()
Deprecated. since JAXB2.0, please see Unmarshaller.getSchema()
 void Marshaller.marshal(Object jaxbElement, ContentHandler handler)
Marshal the content tree rooted at jaxbElement into SAX2 events.
 void Marshaller.marshal(Object jaxbElement, Node node)
Marshal the content tree rooted at jaxbElement into a DOM tree.
 void Marshaller.marshal(Object jaxbElement, OutputStream os)
Marshal the content tree rooted at jaxbElement into an output stream.
 void Marshaller.marshal(Object jaxbElement, Result result)
Marshal the content tree rooted at jaxbElement into the specified javax.xml.transform.Result.
 void Marshaller.marshal(Object jaxbElement, Writer writer)
Marshal the content tree rooted at jaxbElement into a Writer.
 void Marshaller.marshal(Object jaxbElement, XMLEventWriter writer)
Marshal the content tree rooted at jaxbElement into a XMLEventWriter.
abstract  void Binder.marshal(Object jaxbObject, XmlNode xmlNode)
Marshal a JAXB object tree to a new XML document.
 void Marshaller.marshal(Object jaxbElement, XMLStreamWriter writer)
Marshal the content tree rooted at jaxbElement into a XMLStreamWriter.
static JAXBContext JAXBContext.newInstance(Class... classesToBeBound)
Obtain a new instance of a JAXBContext class.
static JAXBContext JAXBContext.newInstance(Class[] classesToBeBound, Map<String,?> properties)
Obtain a new instance of a JAXBContext class.
static JAXBContext JAXBContext.newInstance(String contextPath)
Obtain a new instance of a JAXBContext class.
static JAXBContext JAXBContext.newInstance(String contextPath, ClassLoader classLoader)
Obtain a new instance of a JAXBContext class.
static JAXBContext JAXBContext.newInstance(String contextPath, ClassLoader classLoader, Map<String,?> properties)
Obtain a new instance of a JAXBContext class.
 void Validator.setEventHandler(ValidationEventHandler handler)
Deprecated. since JAXB2.0
 void Marshaller.setEventHandler(ValidationEventHandler handler)
Allow an application to register a validation event handler.
 void Unmarshaller.setEventHandler(ValidationEventHandler handler)
Allow an application to register a ValidationEventHandler.
abstract  void Binder.setEventHandler(ValidationEventHandler handler)
Allow an application to register a ValidationEventHandler.
 void Unmarshaller.setValidating(boolean validating)
Deprecated. since JAXB2.0, please see Unmarshaller.setSchema(javax.xml.validation.Schema)
 Object Unmarshaller.unmarshal(File f)
Unmarshal XML data from the specified file and return the resulting content tree.
 Object Unmarshaller.unmarshal(InputSource source)
Unmarshal XML data from the specified SAX InputSource and return the resulting content tree.
 Object Unmarshaller.unmarshal(InputStream is)
Unmarshal XML data from the specified InputStream and return the resulting content tree.
 Object Unmarshaller.unmarshal(Node node)
Unmarshal global XML data from the specified DOM tree and return the resulting content tree.
<T> JAXBElement<T>
Unmarshaller.unmarshal(Node node, Class<T> declaredType)
Unmarshal XML data by JAXB mapped declaredType and return the resulting content tree.
 Object Unmarshaller.unmarshal(Reader reader)
Unmarshal XML data from the specified Reader and return the resulting content tree.
 Object Unmarshaller.unmarshal(Source source)
Unmarshal XML data from the specified XML Source and return the resulting content tree.
<T> JAXBElement<T>
Unmarshaller.unmarshal(Source source, Class<T> declaredType)
Unmarshal XML data from the specified XML Source by declaredType and return the resulting content tree.
 Object Unmarshaller.unmarshal(URL url)
Unmarshal XML data from the specified URL and return the resulting content tree.
 Object Unmarshaller.unmarshal(XMLEventReader reader)
Unmarshal XML data from the specified pull parser and return the resulting content tree.
<T> JAXBElement<T>
Unmarshaller.unmarshal(XMLEventReader reader, Class<T> declaredType)
Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.
abstract  Object Binder.unmarshal(XmlNode xmlNode)
Unmarshal XML infoset view to a JAXB object tree.
abstract
<T> JAXBElement<T>
Binder.unmarshal(XmlNode xmlNode, Class<T> declaredType)
Unmarshal XML root element by provided declaredType to a JAXB object tree.
 Object Unmarshaller.unmarshal(XMLStreamReader reader)
Unmarshal XML data from the specified pull parser and return the resulting content tree.
<T> JAXBElement<T>
Unmarshaller.unmarshal(XMLStreamReader reader, Class<T> declaredType)
Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.
abstract  Object Binder.updateJAXB(XmlNode xmlNode)
Takes an XML node and updates its associated JAXB object and its descendants.
abstract  XmlNode Binder.updateXML(Object jaxbObject)
Takes an JAXB object and updates its associated XML node and its descendants.
abstract  XmlNode Binder.updateXML(Object jaxbObject, XmlNode xmlNode)
Changes in JAXB object tree are updated in its associated XML parse tree.
 boolean Validator.validate(Object subrootObj)
Deprecated. since JAXB2.0
 boolean Validator.validateRoot(Object rootObj)
Deprecated. since JAXB2.0

Uses of JAXBException in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers that throw JAXBException
 ValidationEventHandler AbstractUnmarshallerImpl.getEventHandler()
Return the current event handler or the default event handler if one hasn't been set.
 ValidationEventHandler AbstractMarshallerImpl.getEventHandler()
 Node AbstractMarshallerImpl.getNode(Object obj)
By default, the getNode method is unsupported and throw an UnsupportedOperationException.
protected  XMLReader AbstractUnmarshallerImpl.getXMLReader()
Obtains a configured XMLReader.
 boolean AbstractUnmarshallerImpl.isValidating()
Indicates whether or not the Unmarshaller is configured to validate during unmarshal operations.
 void AbstractMarshallerImpl.marshal(Object obj, ContentHandler handler)
 void AbstractMarshallerImpl.marshal(Object obj, Node node)
 void AbstractMarshallerImpl.marshal(Object obj, OutputStream os)
 void AbstractMarshallerImpl.marshal(Object obj, Writer w)
 void AbstractMarshallerImpl.marshal(Object obj, XMLEventWriter writer)
 void AbstractMarshallerImpl.marshal(Object obj, XMLStreamWriter writer)
 void AbstractUnmarshallerImpl.setEventHandler(ValidationEventHandler handler)
Allow an application to register a validation event handler.
 void AbstractMarshallerImpl.setEventHandler(ValidationEventHandler handler)
 void AbstractUnmarshallerImpl.setValidating(boolean validating)
Specifies whether or not the Unmarshaller should validate during unmarshal operations.
 Object AbstractUnmarshallerImpl.unmarshal(File f)
 Object AbstractUnmarshallerImpl.unmarshal(InputSource source)
 Object AbstractUnmarshallerImpl.unmarshal(InputStream is)
<T> JAXBElement<T>
AbstractUnmarshallerImpl.unmarshal(Node node, Class<T> expectedType)
 Object AbstractUnmarshallerImpl.unmarshal(Reader reader)
 Object AbstractUnmarshallerImpl.unmarshal(Source source)
<T> JAXBElement<T>
AbstractUnmarshallerImpl.unmarshal(Source source, Class<T> expectedType)
 Object AbstractUnmarshallerImpl.unmarshal(URL url)
 Object AbstractUnmarshallerImpl.unmarshal(XMLEventReader reader)
<T> JAXBElement<T>
AbstractUnmarshallerImpl.unmarshal(XMLEventReader reader, Class<T> expectedType)
protected abstract  Object AbstractUnmarshallerImpl.unmarshal(XMLReader reader, InputSource source)
Unmarshals an object by using the specified XMLReader and the InputSource.
 Object AbstractUnmarshallerImpl.unmarshal(XMLStreamReader reader)
<T> JAXBElement<T>
AbstractUnmarshallerImpl.unmarshal(XMLStreamReader reader, Class<T> expectedType)

Uses of JAXBException in javax.xml.bind.util

Methods in javax.xml.bind.util that throw JAXBException
 Object JAXBResult.getResult()
Gets the unmarshalled object created by the transformation.

Constructors in javax.xml.bind.util that throw JAXBException
JAXBResult(JAXBContext context)
Creates a new instance that uses the specified JAXBContext to unmarshal.
JAXBResult(Unmarshaller _unmarshaller)
Creates a new instance that uses the specified Unmarshaller to unmarshal an object.
JAXBSource(JAXBContext context, Object contentObject)
Creates a new Source for the given content object.
JAXBSource(Marshaller marshaller, Object contentObject)
Creates a new Source for the given content object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.JAXBIntrospector

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.JAXBIntrospector

Packages that use JAXBIntrospector
javax.xml.bind Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.

Uses of JAXBIntrospector in javax.xml.bind

Methods in javax.xml.bind that return JAXBIntrospector
 JAXBIntrospector JAXBContext.createJAXBIntrospector()
Creates a JAXBIntrospector object that can be used to introspect JAXB objects.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.MarshalException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.MarshalException

No usage of javax.xml.bind.MarshalException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.Marshaller.Listener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.Marshaller.Listener

Packages that use Marshaller.Listener
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

Uses of Marshaller.Listener in javax.xml.bind

Methods in javax.xml.bind that return Marshaller.Listener
 Marshaller.Listener Marshaller.getListener()
Return Marshaller.Listener registered with this Marshaller.

Methods in javax.xml.bind with parameters of type Marshaller.Listener
 void Marshaller.setListener(Marshaller.Listener listener)
Register marshal event callback Marshaller.Listener with this Marshaller.

Uses of Marshaller.Listener in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers that return Marshaller.Listener
 Marshaller.Listener AbstractMarshallerImpl.getListener()

Methods in javax.xml.bind.helpers with parameters of type Marshaller.Listener
 void AbstractMarshallerImpl.setListener(Marshaller.Listener listener)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.PropertyException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.PropertyException

Packages that use PropertyException
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

Uses of PropertyException in javax.xml.bind

Methods in javax.xml.bind that throw PropertyException
Object | Validator.getProperty(String name) Deprecated. since JAXB2.0
Object | Marshaller.getProperty(String name) Get the particular property in the underlying implementation of Marshaller.
Object | Unmarshaller.getProperty(String name) Get the particular property in the underlying implementation of Unmarshaller.
abstract Object | Binder.getProperty(String name) Get the particular property in the underlying implementation of Binder.
void | Validator.setProperty(String name, Object value) Deprecated. since JAXB2.0
void | Marshaller.setProperty(String name, Object value) Set the particular property in the underlying implementation of Marshaller.
void | Unmarshaller.setProperty(String name, Object value) Set the particular property in the underlying implementation of Unmarshaller.
abstract void | Binder.setProperty(String name, Object value) Set the particular property in the underlying implementation of Binder.

Uses of PropertyException in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers that throw PropertyException
Object | AbstractUnmarshallerImpl.getProperty(String name) Default implementation of the getProperty method always throws PropertyException since there are no required properties.
Object | AbstractMarshallerImpl.getProperty(String name) Default implementation of the getProperty method handles the four defined properties in Marshaller.
void | AbstractUnmarshallerImpl.setProperty(String name, Object value) Default implementation of the setProperty method always throws PropertyException since there are no required properties.
void | AbstractMarshallerImpl.setProperty(String name, Object value) Default implementation of the setProperty method handles the four defined properties in Marshaller.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.SchemaOutputResolver

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.SchemaOutputResolver

Packages that use SchemaOutputResolver
javax.xml.bind Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.

Uses of SchemaOutputResolver in javax.xml.bind

Methods in javax.xml.bind with parameters of type SchemaOutputResolver
 void JAXBContext.generateSchema(SchemaOutputResolver outputResolver)
Generates the schema documents for this context.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.TypeConstraintException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.TypeConstraintException

No usage of javax.xml.bind.TypeConstraintException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.UnmarshalException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.UnmarshalException

Packages that use UnmarshalException
javax.xml.bind.helpers JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

Uses of UnmarshalException in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers that return UnmarshalException
protected  UnmarshalException AbstractUnmarshallerImpl.createUnmarshalException(SAXException e)
Creates an UnmarshalException from a SAXException.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.Unmarshaller.Listener

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.Unmarshaller.Listener

Packages that use Unmarshaller.Listener
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

Uses of Unmarshaller.Listener in javax.xml.bind

Methods in javax.xml.bind that return Unmarshaller.Listener
 Unmarshaller.Listener Unmarshaller.getListener()
Return Unmarshaller.Listener registered with this Unmarshaller.

Methods in javax.xml.bind with parameters of type Unmarshaller.Listener
 void Unmarshaller.setListener(Unmarshaller.Listener listener)
Register unmarshal event callback Unmarshaller.Listener with this Unmarshaller.

Uses of Unmarshaller.Listener in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers that return Unmarshaller.Listener
 Unmarshaller.Listener AbstractUnmarshallerImpl.getListener()

Methods in javax.xml.bind.helpers with parameters of type Unmarshaller.Listener
 void AbstractUnmarshallerImpl.setListener(Unmarshaller.Listener listener)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.ValidationException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.ValidationException

No usage of javax.xml.bind.ValidationException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.bind.DatatypeConverterInterface

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.bind.DatatypeConverterInterface

Packages that use DatatypeConverterInterface
javax.xml.bind Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.

Uses of DatatypeConverterInterface in javax.xml.bind

Methods in javax.xml.bind with parameters of type DatatypeConverterInterface
static void DatatypeConverter.setDatatypeConverter(DatatypeConverterInterface converter)
This method is for JAXB provider use only.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.bind.Element

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.bind.Element

No usage of javax.xml.bind.Element

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.bind.Marshaller

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.bind.Marshaller

Packages that use Marshaller
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.bind.util | Useful client utility classes.

Uses of Marshaller in javax.xml.bind

Methods in javax.xml.bind that return Marshaller
abstract  Marshaller JAXBContext.createMarshaller()
Create a Marshaller object that can be used to convert a java content tree into XML data.

Uses of Marshaller in javax.xml.bind.helpers

Classes in javax.xml.bind.helpers that implement Marshaller
 class AbstractMarshallerImpl
Partial default Marshaller implementation.

Uses of Marshaller in javax.xml.bind.util

Constructors in javax.xml.bind.util with parameters of type Marshaller
JAXBSource(Marshaller marshaller, Object contentObject)
Creates a new Source for the given content object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.bind.NotIdentifiableEvent

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.bind.NotIdentifiableEvent

Packages that use NotIdentifiableEvent
javax.xml.bind.helpers JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

Uses of NotIdentifiableEvent in javax.xml.bind.helpers

Classes in javax.xml.bind.helpers that implement NotIdentifiableEvent
 class NotIdentifiableEventImpl
Default implementation of the NotIdentifiableEvent interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.bind.ParseConversionEvent

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.bind.ParseConversionEvent

Packages that use ParseConversionEvent
javax.xml.bind.helpers JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

Uses of ParseConversionEvent in javax.xml.bind.helpers

Classes in javax.xml.bind.helpers that implement ParseConversionEvent
 class ParseConversionEventImpl
Default implementation of the ParseConversionEvent interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.bind.PrintConversionEvent

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.bind.PrintConversionEvent

Packages that use PrintConversionEvent
javax.xml.bind.helpers JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

Uses of PrintConversionEvent in javax.xml.bind.helpers

Classes in javax.xml.bind.helpers that implement PrintConversionEvent
 class PrintConversionEventImpl
Default implementation of the PrintConversionEvent interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.bind.Unmarshaller

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.bind.Unmarshaller

Packages that use Unmarshaller
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.bind.util | Useful client utility classes.

Uses of Unmarshaller in javax.xml.bind

Methods in javax.xml.bind that return Unmarshaller
abstract  Unmarshaller JAXBContext.createUnmarshaller()
Create an Unmarshaller object that can be used to convert XML data into a java content tree.

Uses of Unmarshaller in javax.xml.bind.helpers

Classes in javax.xml.bind.helpers that implement Unmarshaller
 class AbstractUnmarshallerImpl
Partial default Unmarshaller implementation.

Uses of Unmarshaller in javax.xml.bind.util

Constructors in javax.xml.bind.util with parameters of type Unmarshaller
JAXBResult(Unmarshaller _unmarshaller)
Creates a new instance that uses the specified Unmarshaller to unmarshal an object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.bind.UnmarshallerHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.bind.UnmarshallerHandler

Packages that use UnmarshallerHandler
javax.xml.bind Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.

Uses of UnmarshallerHandler in javax.xml.bind

Methods in javax.xml.bind that return UnmarshallerHandler
 UnmarshallerHandler Unmarshaller.getUnmarshallerHandler()
Get an unmarshaller handler object that can be used as a component in an XML pipeline.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.bind.ValidationEvent

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.bind.ValidationEvent

Packages that use ValidationEvent
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.bind.util | Useful client utility classes.

Uses of ValidationEvent in javax.xml.bind

Subinterfaces of ValidationEvent in javax.xml.bind
interface | NotIdentifiableEvent This event indicates that a problem was encountered resolving an ID/IDREF.
interface | ParseConversionEvent This event indicates that a problem was encountered while converting a string from the XML data into a value of the target Java data type.
interface | PrintConversionEvent This event indicates that a problem was encountered while converting data from the Java content tree into its lexical representation.

Methods in javax.xml.bind with parameters of type ValidationEvent
 boolean ValidationEventHandler.handleEvent(ValidationEvent event)
Receive notification of a validation warning or error.

Uses of ValidationEvent in javax.xml.bind.helpers

Classes in javax.xml.bind.helpers that implement ValidationEvent
class | NotIdentifiableEventImpl Default implementation of the NotIdentifiableEvent interface.
class | ParseConversionEventImpl Default implementation of the ParseConversionEvent interface.
class | PrintConversionEventImpl Default implementation of the PrintConversionEvent interface.
class | ValidationEventImpl Default implementation of the ValidationEvent interface.

Methods in javax.xml.bind.helpers with parameters of type ValidationEvent
 boolean DefaultValidationEventHandler.handleEvent(ValidationEvent event)

Uses of ValidationEvent in javax.xml.bind.util

Methods in javax.xml.bind.util that return ValidationEvent
 ValidationEvent[] ValidationEventCollector.getEvents()
Return an array of ValidationEvent objects containing a copy of each of the collected errors and warnings.

Methods in javax.xml.bind.util with parameters of type ValidationEvent
 boolean ValidationEventCollector.handleEvent(ValidationEvent event)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.bind.ValidationEventHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.bind.ValidationEventHandler

Packages that use ValidationEventHandler
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.annotation | Defines annotations for customizing Java program elements to XML Schema mapping.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.bind.util | Useful client utility classes.

Uses of ValidationEventHandler in javax.xml.bind

Methods in javax.xml.bind that return ValidationEventHandler
ValidationEventHandler | Validator.getEventHandler() Deprecated. since JAXB2.0
ValidationEventHandler | Marshaller.getEventHandler() Return the current event handler or the default event handler if one hasn't been set.
ValidationEventHandler | Unmarshaller.getEventHandler() Return the current event handler or the default event handler if one hasn't been set.
abstract ValidationEventHandler | Binder.getEventHandler() Return the current event handler or the default event handler if one hasn't been set.

Methods in javax.xml.bind with parameters of type ValidationEventHandler
void | Validator.setEventHandler(ValidationEventHandler handler) Deprecated. since JAXB2.0
void | Marshaller.setEventHandler(ValidationEventHandler handler) Allow an application to register a validation event handler.
void | Unmarshaller.setEventHandler(ValidationEventHandler handler) Allow an application to register a ValidationEventHandler.
abstract void | Binder.setEventHandler(ValidationEventHandler handler) Allow an application to register a ValidationEventHandler.

Uses of ValidationEventHandler in javax.xml.bind.annotation

Methods in javax.xml.bind.annotation with parameters of type ValidationEventHandler
DOMResult | W3CDomHandler.createUnmarshaller(ValidationEventHandler errorHandler)
ResultT | DomHandler.createUnmarshaller(ValidationEventHandler errorHandler) When a JAXB provider needs to unmarshal a part of a document into an infoset representation, it first calls this method to create a Result object.
Source | DomHandler.marshal(ElementT n, ValidationEventHandler errorHandler) This method is called when a JAXB provider needs to marshal an element to XML.
Source | W3CDomHandler.marshal(Element element, ValidationEventHandler errorHandler)

Uses of ValidationEventHandler in javax.xml.bind.helpers

Classes in javax.xml.bind.helpers that implement ValidationEventHandler
 class DefaultValidationEventHandler
JAXB 1.0 only default validation event handler.

Methods in javax.xml.bind.helpers that return ValidationEventHandler
ValidationEventHandler | AbstractUnmarshallerImpl.getEventHandler() Return the current event handler or the default event handler if one hasn't been set.
ValidationEventHandler | AbstractMarshallerImpl.getEventHandler()

Methods in javax.xml.bind.helpers with parameters of type ValidationEventHandler
void | AbstractUnmarshallerImpl.setEventHandler(ValidationEventHandler handler) Allow an application to register a validation event handler.
void | AbstractMarshallerImpl.setEventHandler(ValidationEventHandler handler)

Uses of ValidationEventHandler in javax.xml.bind.util

Classes in javax.xml.bind.util that implement ValidationEventHandler
 class ValidationEventCollector
ValidationEventHandler implementation that collects all events.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.bind.ValidationEventLocator

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.bind.ValidationEventLocator

Packages that use ValidationEventLocator
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

Uses of ValidationEventLocator in javax.xml.bind

Methods in javax.xml.bind that return ValidationEventLocator
 ValidationEventLocator ValidationEvent.getLocator()
Retrieve the locator for this warning/error.

Uses of ValidationEventLocator in javax.xml.bind.helpers

Classes in javax.xml.bind.helpers that implement ValidationEventLocator
 class ValidationEventLocatorImpl
Default implementation of the ValidationEventLocator interface.

Methods in javax.xml.bind.helpers that return ValidationEventLocator
 ValidationEventLocator ValidationEventImpl.getLocator()

Methods in javax.xml.bind.helpers with parameters of type ValidationEventLocator
 void ValidationEventImpl.setLocator(ValidationEventLocator _locator)
Set the locator object for this event.

Constructors in javax.xml.bind.helpers with parameters of type ValidationEventLocator
NotIdentifiableEventImpl(int _severity, String _message, ValidationEventLocator _locator)
Create a new NotIdentifiableEventImpl.
NotIdentifiableEventImpl(int _severity, String _message, ValidationEventLocator _locator, Throwable _linkedException)
Create a new NotIdentifiableEventImpl.
ParseConversionEventImpl(int _severity, String _message, ValidationEventLocator _locator)
Create a new ParseConversionEventImpl.
ParseConversionEventImpl(int _severity, String _message, ValidationEventLocator _locator, Throwable _linkedException)
Create a new ParseConversionEventImpl.
PrintConversionEventImpl(int _severity, String _message, ValidationEventLocator _locator)
Create a new PrintConversionEventImpl.
PrintConversionEventImpl(int _severity, String _message, ValidationEventLocator _locator, Throwable _linkedException)
Create a new PrintConversionEventImpl.
ValidationEventImpl(int _severity, String _message, ValidationEventLocator _locator)
Create a new ValidationEventImpl.
ValidationEventImpl(int _severity, String _message, ValidationEventLocator _locator, Throwable _linkedException)
Create a new ValidationEventImpl.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.bind.Validator

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.bind.Validator

Packages that use Validator
javax.xml.bind Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.

Uses of Validator in javax.xml.bind

Methods in javax.xml.bind that return Validator
abstract  Validator JAXBContext.createValidator()
Deprecated. since JAXB2.0

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DatatypeConverter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Class DatatypeConverter

java.lang.Object
    extended by  javax.xml.bind.DatatypeConverter

public final class DatatypeConverter
extends Object

The javaType binding declaration can be used to customize the binding of an XML schema datatype to a Java datatype. Customizations can involve writing a parse and print method for parsing and printing lexical representations of a XML schema datatype respectively. However, writing parse and print methods requires knowledge of the lexical representations ( XML Schema Part2: Datatypes specification ) and hence may be difficult to write.

This class makes it easier to write parse and print methods. It defines static parse and print methods that provide access to a JAXB provider's implementation of parse and print methods. These methods are invoked by custom parse and print methods. For example, the binding of xsd:dateTime to a long can be customized using parse and print methods as follows:

    // Customized parse method
    public long myParseCal( String dateTimeString ) {
        java.util.Calendar cal = DatatypeConverter.parseDateTime(dateTimeString);
        long longval = convert_calendar_to_long(cal); //application specific
        return longval;
    }

    // Customized print method
    public String myPrintCal( Long longval ) {
        java.util.Calendar cal = convert_long_to_calendar(longval) ; //application specific
        String dateTimeString = DatatypeConverter.printDateTime(cal);
        return dateTimeString;
    }

There is a static parse and print method corresponding to each parse and print method respectively in the DatatypeConverterInterface.

The static methods defined in the class can also be used to specify a parse or a print method in a javaType binding declaration.

JAXB Providers are required to call the setDatatypeConverter api at some point before the first marshal or unmarshal operation (perhaps during the call to JAXBContext.newInstance). This step is necessary to configure the converter that should be used to perform the print and parse functionality.

A print method for a XML schema datatype can output any lexical representation that is valid with respect to the XML schema datatype. If an error is encountered during conversion, then an IllegalArgumentException, or a subclass of IllegalArgumentException must be thrown by the method.

Since:
JAXB1.0
See Also:
DatatypeConverterInterface, ParseConversionEvent, PrintConversionEvent

Method Summary
static String | parseAnySimpleType(String lexicalXSDAnySimpleType) Return a string containing the lexical representation of the simple type.
static byte[] | parseBase64Binary(String lexicalXSDBase64Binary) Converts the string argument into an array of bytes.
static boolean | parseBoolean(String lexicalXSDBoolean) Converts the string argument into a boolean value.
static byte | parseByte(String lexicalXSDByte) Converts the string argument into a byte value.
static Calendar | parseDate(String lexicalXSDDate) Converts the string argument into a Calendar value.
static Calendar | parseDateTime(String lexicalXSDDateTime) Converts the string argument into a Calendar value.
static BigDecimal | parseDecimal(String lexicalXSDDecimal) Converts the string argument into a BigDecimal value.
static double | parseDouble(String lexicalXSDDouble) Converts the string argument into a double value.
static float | parseFloat(String lexicalXSDFloat) Converts the string argument into a float value.
static byte[] | parseHexBinary(String lexicalXSDHexBinary) Converts the string argument into an array of bytes.
static int | parseInt(String lexicalXSDInt) Convert the string argument into an int value.
static BigInteger | parseInteger(String lexicalXSDInteger) Convert the string argument into a BigInteger value.
static long | parseLong(String lexicalXSDLong) Converts the string argument into a long value.
static QName | parseQName(String lexicalXSDQName, NamespaceContext nsc) Converts the string argument into a byte value.
static short | parseShort(String lexicalXSDShort) Converts the string argument into a short value.
static String | parseString(String lexicalXSDString) Convert the lexical XSD string argument into a String value.
static Calendar | parseTime(String lexicalXSDTime) Converts the string argument into a Calendar value.
static long | parseUnsignedInt(String lexicalXSDUnsignedInt) Converts the string argument into a long value.
static int | parseUnsignedShort(String lexicalXSDUnsignedShort) Converts the string argument into an int value.
static String | printAnySimpleType(String val) Converts a string value into a string.
static String | printBase64Binary(byte[] val) Converts an array of bytes into a string.
static String | printBoolean(boolean val) Converts a boolean value into a string.
static String | printByte(byte val) Converts a byte value into a string.
static String | printDate(Calendar val) Converts a Calendar value into a string.
static String | printDateTime(Calendar val) Converts a Calendar value into a string.
static String | printDecimal(BigDecimal val) Converts a BigDecimal value into a string.
static String | printDouble(double val) Converts a double value into a string.
static String | printFloat(float val) Converts a float value into a string.
static String | printHexBinary(byte[] val) Converts an array of bytes into a string.
static String | printInt(int val) Converts an int value into a string.
static String | printInteger(BigInteger val) Converts a BigInteger value into a string.
static String | printLong(long val) Converts A long value into a string.
static String | printQName(QName val, NamespaceContext nsc) Converts a QName instance into a string.
static String | printShort(short val) Converts a short value into a string.
static String | printString(String val) Converts the string argument into a string.
static String | printTime(Calendar val) Converts a Calendar value into a string.
static String | printUnsignedInt(long val) Converts a long value into a string.
static String | printUnsignedShort(int val) Converts an int value into a string.
static void | setDatatypeConverter(DatatypeConverterInterface converter) This method is for JAXB provider use only.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setDatatypeConverter

public static void setDatatypeConverter(DatatypeConverterInterface converter)
This method is for JAXB provider use only.

JAXB Providers are required to call this method at some point before allowing any of the JAXB client marshal or unmarshal operations to occur. This is necessary to configure the datatype converter that should be used to perform the print and parse conversions.

Calling this api repeatedly will have no effect - the DatatypeConverterInterface instance passed into the first invocation is the one that will be used from then on.

Parameters:
converter - an instance of a class that implements the DatatypeConverterInterface class - this parameter must not be null.
Throws:
IllegalArgumentException - if the parameter is null

parseString

public static String parseString(String lexicalXSDString)

Convert the lexical XSD string argument into a String value.

Parameters:
lexicalXSDString - A string containing a lexical representation of xsd:string.
Returns:
A String value represented by the string argument.

parseInteger

public static BigInteger parseInteger(String lexicalXSDInteger)

Convert the string argument into a BigInteger value.

Parameters:
lexicalXSDInteger - A string containing a lexical representation of xsd:integer.
Returns:
A BigInteger value represented by the string argument.
Throws:
NumberFormatException - lexicalXSDInteger is not a valid string representation of a BigInteger value.

parseInt

public static int parseInt(String lexicalXSDInt)

Convert the string argument into an int value.

Parameters:
lexicalXSDInt - A string containing a lexical representation of xsd:int.
Returns:
A int value represented by the string argument.
Throws:
NumberFormatException - lexicalXSDInt is not a valid string representation of an int value.

parseLong

public static long parseLong(String lexicalXSDLong)

Converts the string argument into a long value.

Parameters:
lexicalXSDLong - A string containing lexical representation of xsd:long.
Returns:
A long value represented by the string argument.
Throws:
NumberFormatException - lexicalXSDLong is not a valid string representation of a long value.

parseShort

public static short parseShort(String lexicalXSDShort)

Converts the string argument into a short value.

Parameters:
lexicalXSDShort - A string containing lexical representation of xsd:short.
Returns:
A short value represented by the string argument.
Throws:
NumberFormatException - lexicalXSDShort is not a valid string representation of a short value.

parseDecimal

public static BigDecimal parseDecimal(String lexicalXSDDecimal)

Converts the string argument into a BigDecimal value.

Parameters:
lexicalXSDDecimal - A string containing lexical representation of xsd:decimal.
Returns:
A BigDecimal value represented by the string argument.
Throws:
NumberFormatException - lexicalXSDDecimal is not a valid string representation of BigDecimal.

parseFloat

public static float parseFloat(String lexicalXSDFloat)

Converts the string argument into a float value.

Parameters:
lexicalXSDFloat - A string containing lexical representation of xsd:float.
Returns:
A float value represented by the string argument.
Throws:
NumberFormatException - lexicalXSDFloat is not a valid string representation of a float value.

parseDouble

public static double parseDouble(String lexicalXSDDouble)

Converts the string argument into a double value.

Parameters:
lexicalXSDDouble - A string containing lexical representation of xsd:double.
Returns:
A double value represented by the string argument.
Throws:
NumberFormatException - lexicalXSDDouble is not a valid string representation of a double value.

parseBoolean

public static boolean parseBoolean(String lexicalXSDBoolean)

Converts the string argument into a boolean value.

Parameters:
lexicalXSDBoolean - A string containing lexical representation of xsd:boolean.
Returns:
A boolean value represented by the string argument.
Throws:
IllegalArgumentException - if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:boolean.

parseByte

public static byte parseByte(String lexicalXSDByte)

Converts the string argument into a byte value.

Parameters:
lexicalXSDByte - A string containing lexical representation of xsd:byte.
Returns:
A byte value represented by the string argument.
Throws:
IllegalArgumentException - if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:byte.

parseQName

public static QName parseQName(String lexicalXSDQName,
                               NamespaceContext nsc)

Converts the string argument into a byte value.

String parameter lexicalXSDQname must conform to lexical value space specifed at XML Schema Part 2:Datatypes specification:QNames

Parameters:
lexicalXSDQName - A string containing lexical representation of xsd:QName.
nsc - A namespace context for interpreting a prefix within a QName.
Returns:
A QName value represented by the string argument.
Throws:
IllegalArgumentException - if string parameter does not conform to XML Schema Part 2 specification or if namespace prefix of lexicalXSDQname is not bound to a URI in NamespaceContext nsc.

parseDateTime

public static Calendar parseDateTime(String lexicalXSDDateTime)

Converts the string argument into a Calendar value.

Parameters:
lexicalXSDDateTime - A string containing lexical representation of xsd:datetime.
Returns:
A Calendar object represented by the string argument.
Throws:
IllegalArgumentException - if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:dateTime.

parseBase64Binary

public static byte[] parseBase64Binary(String lexicalXSDBase64Binary)

Converts the string argument into an array of bytes.

Parameters:
lexicalXSDBase64Binary - A string containing lexical representation of xsd:base64Binary.
Returns:
An array of bytes represented by the string argument.
Throws:
IllegalArgumentException - if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:base64Binary

parseHexBinary

public static byte[] parseHexBinary(String lexicalXSDHexBinary)

Converts the string argument into an array of bytes.

Parameters:
lexicalXSDHexBinary - A string containing lexical representation of xsd:hexBinary.
Returns:
An array of bytes represented by the string argument.
Throws:
IllegalArgumentException - if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:hexBinary.

parseUnsignedInt

public static long parseUnsignedInt(String lexicalXSDUnsignedInt)

Converts the string argument into a long value.

Parameters:
lexicalXSDUnsignedInt - A string containing lexical representation of xsd:unsignedInt.
Returns:
A long value represented by the string argument.
Throws:
NumberFormatException - if string parameter can not be parsed into a long value.

parseUnsignedShort

public static int parseUnsignedShort(String lexicalXSDUnsignedShort)

Converts the string argument into an int value.

Parameters:
lexicalXSDUnsignedShort - A string containing lexical representation of xsd:unsignedShort.
Returns:
An int value represented by the string argument.
Throws:
NumberFormatException - if string parameter can not be parsed into an int value.

parseTime

public static Calendar parseTime(String lexicalXSDTime)

Converts the string argument into a Calendar value.

Parameters:
lexicalXSDTime - A string containing lexical representation of xsd:time.
Returns:
A Calendar value represented by the string argument.
Throws:
IllegalArgumentException - if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Time.

parseDate

public static Calendar parseDate(String lexicalXSDDate)

Converts the string argument into a Calendar value.

Parameters:
lexicalXSDDate - A string containing lexical representation of xsd:Date.
Returns:
A Calendar value represented by the string argument.
Throws:
IllegalArgumentException - if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Date.

parseAnySimpleType

public static String parseAnySimpleType(String lexicalXSDAnySimpleType)

Return a string containing the lexical representation of the simple type.

Parameters:
lexicalXSDAnySimpleType - A string containing lexical representation of the simple type.
Returns:
A string containing the lexical representation of the simple type.

printString

public static String printString(String val)

Converts the string argument into a string.

Parameters:
val - A string value.
Returns:
A string containing a lexical representation of xsd:string.

printInteger

public static String printInteger(BigInteger val)

Converts a BigInteger value into a string.

Parameters:
val - A BigInteger value
Returns:
A string containing a lexical representation of xsd:integer
Throws:
IllegalArgumentException - val is null.

printInt

public static String printInt(int val)

Converts an int value into a string.

Parameters:
val - An int value
Returns:
A string containing a lexical representation of xsd:int

printLong

public static String printLong(long val)

Converts A long value into a string.

Parameters:
val - A long value
Returns:
A string containing a lexical representation of xsd:long

printShort

public static String printShort(short val)

Converts a short value into a string.

Parameters:
val - A short value
Returns:
A string containing a lexical representation of xsd:short

printDecimal

public static String printDecimal(BigDecimal val)

Converts a BigDecimal value into a string.

Parameters:
val - A BigDecimal value
Returns:
A string containing a lexical representation of xsd:decimal
Throws:
IllegalArgumentException - val is null.

printFloat

public static String printFloat(float val)

Converts a float value into a string.

Parameters:
val - A float value
Returns:
A string containing a lexical representation of xsd:float

printDouble

public static String printDouble(double val)

Converts a double value into a string.

Parameters:
val - A double value
Returns:
A string containing a lexical representation of xsd:double

printBoolean

public static String printBoolean(boolean val)

Converts a boolean value into a string.

Parameters:
val - A boolean value
Returns:
A string containing a lexical representation of xsd:boolean

printByte

public static String printByte(byte val)

Converts a byte value into a string.

Parameters:
val - A byte value
Returns:
A string containing a lexical representation of xsd:byte

printQName

public static String printQName(QName val,
                                NamespaceContext nsc)

Converts a QName instance into a string.

Parameters:
val - A QName value
nsc - A namespace context for interpreting a prefix within a QName.
Returns:
A string containing a lexical representation of QName
Throws:
IllegalArgumentException - if val is null or if nsc is non-null or nsc.getPrefix(nsprefixFromVal) is null.

printDateTime

public static String printDateTime(Calendar val)

Converts a Calendar value into a string.

Parameters:
val - A Calendar value
Returns:
A string containing a lexical representation of xsd:dateTime
Throws:
IllegalArgumentException - if val is null.

printBase64Binary

public static String printBase64Binary(byte[] val)

Converts an array of bytes into a string.

Parameters:
val - An array of bytes
Returns:
A string containing a lexical representation of xsd:base64Binary
Throws:
IllegalArgumentException - if val is null.

printHexBinary

public static String printHexBinary(byte[] val)

Converts an array of bytes into a string.

Parameters:
val - An array of bytes
Returns:
A string containing a lexical representation of xsd:hexBinary
Throws:
IllegalArgumentException - if val is null.

printUnsignedInt

public static String printUnsignedInt(long val)

Converts a long value into a string.

Parameters:
val - A long value
Returns:
A string containing a lexical representation of xsd:unsignedInt

printUnsignedShort

public static String printUnsignedShort(int val)

Converts an int value into a string.

Parameters:
val - An int value
Returns:
A string containing a lexical representation of xsd:unsignedShort

printTime

public static String printTime(Calendar val)

Converts a Calendar value into a string.

Parameters:
val - A Calendar value
Returns:
A string containing a lexical representation of xsd:time
Throws:
IllegalArgumentException - if val is null.

printDate

public static String printDate(Calendar val)

Converts a Calendar value into a string.

Parameters:
val - A Calendar value
Returns:
A string containing a lexical representation of xsd:date
Throws:
IllegalArgumentException - if val is null.

printAnySimpleType

public static String printAnySimpleType(String val)

Converts a string value into a string.

Parameters:
val - A string value
Returns:
A string containing a lexical representation of xsd:AnySimpleType
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DatatypeConverterInterface

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Interface DatatypeConverterInterface

public interface DatatypeConverterInterface

The DatatypeConverterInterface is for JAXB provider use only. A JAXB provider must supply a class that implements this interface. JAXB Providers are required to call the DatatypeConverter.setDatatypeConverter api at some point before the first marshal or unmarshal operation (perhaps during the call to JAXBContext.newInstance). This step is necessary to configure the converter that should be used to perform the print and parse functionality. Calling this api repeatedly will have no effect - the DatatypeConverter instance passed into the first invocation is the one that will be used from then on.

This interface defines the parse and print methods. There is one parse and print method for each XML schema datatype specified in the the default binding Table 5-1 in the JAXB specification.

The parse and print methods defined here are invoked by the static parse and print methods defined in the DatatypeConverter class.

A parse method for a XML schema datatype must be capable of converting any lexical representation of the XML schema datatype ( specified by the XML Schema Part2: Datatypes specification into a value in the value space of the XML schema datatype. If an error is encountered during conversion, then an IllegalArgumentException or a subclass of IllegalArgumentException must be thrown by the method.

A print method for a XML schema datatype can output any lexical representation that is valid with respect to the XML schema datatype. If an error is encountered during conversion, then an IllegalArgumentException, or a subclass of IllegalArgumentException must be thrown by the method.

The prefix xsd: is used to refer to XML schema datatypes XML Schema Part2: Datatypes specification.

Since:
JAXB1.0
See Also:
DatatypeConverter, ParseConversionEvent, PrintConversionEvent

Method Summary
String | parseAnySimpleType(String lexicalXSDAnySimpleType) Return a string containing the lexical representation of the simple type.
byte[] | parseBase64Binary(String lexicalXSDBase64Binary) Converts the string argument into an array of bytes.
boolean | parseBoolean(String lexicalXSDBoolean) Converts the string argument into a boolean value.
byte | parseByte(String lexicalXSDByte) Converts the string argument into a byte value.
Calendar | parseDate(String lexicalXSDDate) Converts the string argument into a Calendar value.
Calendar | parseDateTime(String lexicalXSDDateTime) Converts the string argument into a Calendar value.
BigDecimal | parseDecimal(String lexicalXSDDecimal) Converts the string argument into a BigDecimal value.
double | parseDouble(String lexicalXSDDouble) Converts the string argument into a double value.
float | parseFloat(String lexicalXSDFloat) Converts the string argument into a float value.
byte[] | parseHexBinary(String lexicalXSDHexBinary) Converts the string argument into an array of bytes.
int | parseInt(String lexicalXSDInt) Convert the string argument into an int value.
BigInteger | parseInteger(String lexicalXSDInteger) Convert the string argument into a BigInteger value.
long | parseLong(String lexicalXSDLong) Converts the string argument into a long value.
QName | parseQName(String lexicalXSDQName, NamespaceContext nsc) Converts the string argument into a QName value.
short | parseShort(String lexicalXSDShort) Converts the string argument into a short value.
String | parseString(String lexicalXSDString) Convert the string argument into a string.
Calendar | parseTime(String lexicalXSDTime) Converts the string argument into a Calendar value.
long | parseUnsignedInt(String lexicalXSDUnsignedInt) Converts the string argument into a long value.
int | parseUnsignedShort(String lexicalXSDUnsignedShort) Converts the string argument into an int value.
String | printAnySimpleType(String val) Converts a string value into a string.
String | printBase64Binary(byte[] val) Converts an array of bytes into a string.
String | printBoolean(boolean val) Converts a boolean value into a string.
String | printByte(byte val) Converts a byte value into a string.
String | printDate(Calendar val) Converts a Calendar value into a string.
String | printDateTime(Calendar val) Converts a Calendar value into a string.
String | printDecimal(BigDecimal val) Converts a BigDecimal value into a string.
String | printDouble(double val) Converts a double value into a string.
String | printFloat(float val) Converts a float value into a string.
String | printHexBinary(byte[] val) Converts an array of bytes into a string.
String | printInt(int val) Converts an int value into a string.
String | printInteger(BigInteger val) Converts a BigInteger value into a string.
String | printLong(long val) Converts a long value into a string.
String | printQName(QName val, NamespaceContext nsc) Converts a QName instance into a string.
String | printShort(short val) Converts a short value into a string.
String | printString(String val) Converts the string argument into a string.
String | printTime(Calendar val) Converts a Calendar value into a string.
String | printUnsignedInt(long val) Converts a long value into a string.
String | printUnsignedShort(int val) Converts an int value into a string.

Method Detail

parseString

String parseString(String lexicalXSDString)

Convert the string argument into a string.

Parameters:
lexicalXSDString - A lexical representation of the XML Schema datatype xsd:string
Returns:
A string that is the same as the input string.

parseInteger

BigInteger parseInteger(String lexicalXSDInteger)

Convert the string argument into a BigInteger value.

Parameters:
lexicalXSDInteger - A string containing a lexical representation of xsd:integer.
Returns:
A BigInteger value represented by the string argument.
Throws:
NumberFormatException - lexicalXSDInteger is not a valid string representation of a BigInteger value.

parseInt

int parseInt(String lexicalXSDInt)

Convert the string argument into an int value.

Parameters:
lexicalXSDInt - A string containing a lexical representation of xsd:int.
Returns:
An int value represented byte the string argument.
Throws:
NumberFormatException - lexicalXSDInt is not a valid string representation of an int value.

parseLong

long parseLong(String lexicalXSDLong)

Converts the string argument into a long value.

Parameters:
lexicalXSDLong - A string containing lexical representation of xsd:long.
Returns:
A long value represented by the string argument.
Throws:
NumberFormatException - lexicalXSDLong is not a valid string representation of a long value.

parseShort

short parseShort(String lexicalXSDShort)

Converts the string argument into a short value.

Parameters:
lexicalXSDShort - A string containing lexical representation of xsd:short.
Returns:
A short value represented by the string argument.
Throws:
NumberFormatException - lexicalXSDShort is not a valid string representation of a short value.

parseDecimal

BigDecimal parseDecimal(String lexicalXSDDecimal)

Converts the string argument into a BigDecimal value.

Parameters:
lexicalXSDDecimal - A string containing lexical representation of xsd:decimal.
Returns:
A BigDecimal value represented by the string argument.
Throws:
NumberFormatException - lexicalXSDDecimal is not a valid string representation of BigDecimal.

parseFloat

float parseFloat(String lexicalXSDFloat)

Converts the string argument into a float value.

Parameters:
lexicalXSDFloat - A string containing lexical representation of xsd:float.
Returns:
A float value represented by the string argument.
Throws:
NumberFormatException - lexicalXSDFloat is not a valid string representation of a float value.

parseDouble

double parseDouble(String lexicalXSDDouble)

Converts the string argument into a double value.

Parameters:
lexicalXSDDouble - A string containing lexical representation of xsd:double.
Returns:
A double value represented by the string argument.
Throws:
NumberFormatException - lexicalXSDDouble is not a valid string representation of a double value.

parseBoolean

boolean parseBoolean(String lexicalXSDBoolean)

Converts the string argument into a boolean value.

Parameters:
lexicalXSDBoolean - A string containing lexical representation of xsd:boolean.
Returns:
A boolean value represented by the string argument.
Throws:
IllegalArgumentException - if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:boolean.

parseByte

byte parseByte(String lexicalXSDByte)

Converts the string argument into a byte value.

Parameters:
lexicalXSDByte - A string containing lexical representation of xsd:byte.
Returns:
A byte value represented by the string argument.
Throws:
NumberFormatException - lexicalXSDByte does not contain a parseable byte.
IllegalArgumentException - if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:byte.

parseQName

QName parseQName(String lexicalXSDQName,
                 NamespaceContext nsc)

Converts the string argument into a QName value.

String parameter lexicalXSDQname must conform to lexical value space specifed at XML Schema Part 2:Datatypes specification:QNames

Parameters:
lexicalXSDQName - A string containing lexical representation of xsd:QName.
nsc - A namespace context for interpreting a prefix within a QName.
Returns:
A QName value represented by the string argument.
Throws:
IllegalArgumentException - if string parameter does not conform to XML Schema Part 2 specification or if namespace prefix of lexicalXSDQname is not bound to a URI in NamespaceContext nsc.

parseDateTime

Calendar parseDateTime(String lexicalXSDDateTime)

Converts the string argument into a Calendar value.

Parameters:
lexicalXSDDateTime - A string containing lexical representation of xsd:datetime.
Returns:
A Calendar object represented by the string argument.
Throws:
IllegalArgumentException - if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:dateTime.

parseBase64Binary

byte[] parseBase64Binary(String lexicalXSDBase64Binary)

Converts the string argument into an array of bytes.

Parameters:
lexicalXSDBase64Binary - A string containing lexical representation of xsd:base64Binary.
Returns:
An array of bytes represented by the string argument.
Throws:
IllegalArgumentException - if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:base64Binary

parseHexBinary

byte[] parseHexBinary(String lexicalXSDHexBinary)

Converts the string argument into an array of bytes.

Parameters:
lexicalXSDHexBinary - A string containing lexical representation of xsd:hexBinary.
Returns:
An array of bytes represented by the string argument.
Throws:
IllegalArgumentException - if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:hexBinary.

parseUnsignedInt

long parseUnsignedInt(String lexicalXSDUnsignedInt)

Converts the string argument into a long value.

Parameters:
lexicalXSDUnsignedInt - A string containing lexical representation of xsd:unsignedInt.
Returns:
A long value represented by the string argument.
Throws:
NumberFormatException - if string parameter can not be parsed into a long value.

parseUnsignedShort

int parseUnsignedShort(String lexicalXSDUnsignedShort)

Converts the string argument into an int value.

Parameters:
lexicalXSDUnsignedShort - A string containing lexical representation of xsd:unsignedShort.
Returns:
An int value represented by the string argument.
Throws:
NumberFormatException - if string parameter can not be parsed into an int value.

parseTime

Calendar parseTime(String lexicalXSDTime)

Converts the string argument into a Calendar value.

Parameters:
lexicalXSDTime - A string containing lexical representation of xsd:Time.
Returns:
A Calendar value represented by the string argument.
Throws:
IllegalArgumentException - if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Time.

parseDate

Calendar parseDate(String lexicalXSDDate)

Converts the string argument into a Calendar value.

Parameters:
lexicalXSDDate - A string containing lexical representation of xsd:Date.
Returns:
A Calendar value represented by the string argument.
Throws:
IllegalArgumentException - if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Date.

parseAnySimpleType

String parseAnySimpleType(String lexicalXSDAnySimpleType)

Return a string containing the lexical representation of the simple type.

Parameters:
lexicalXSDAnySimpleType - A string containing lexical representation of the simple type.
Returns:
A string containing the lexical representation of the simple type.

printString

String printString(String val)

Converts the string argument into a string.

Parameters:
val - A string value.
Returns:
A string containing a lexical representation of xsd:string

printInteger

String printInteger(BigInteger val)

Converts a BigInteger value into a string.

Parameters:
val - A BigInteger value
Returns:
A string containing a lexical representation of xsd:integer
Throws:
IllegalArgumentException - val is null.

printInt

String printInt(int val)

Converts an int value into a string.

Parameters:
val - An int value
Returns:
A string containing a lexical representation of xsd:int

printLong

String printLong(long val)

Converts a long value into a string.

Parameters:
val - A long value
Returns:
A string containing a lexical representation of xsd:long

printShort

String printShort(short val)

Converts a short value into a string.

Parameters:
val - A short value
Returns:
A string containing a lexical representation of xsd:short

printDecimal

String printDecimal(BigDecimal val)

Converts a BigDecimal value into a string.

Parameters:
val - A BigDecimal value
Returns:
A string containing a lexical representation of xsd:decimal
Throws:
IllegalArgumentException - val is null.

printFloat

String printFloat(float val)

Converts a float value into a string.

Parameters:
val - A float value
Returns:
A string containing a lexical representation of xsd:float

printDouble

String printDouble(double val)

Converts a double value into a string.

Parameters:
val - A double value
Returns:
A string containing a lexical representation of xsd:double

printBoolean

String printBoolean(boolean val)

Converts a boolean value into a string.

Parameters:
val - A boolean value
Returns:
A string containing a lexical representation of xsd:boolean

printByte

String printByte(byte val)

Converts a byte value into a string.

Parameters:
val - A byte value
Returns:
A string containing a lexical representation of xsd:byte

printQName

String printQName(QName val,
                  NamespaceContext nsc)

Converts a QName instance into a string.

Parameters:
val - A QName value
nsc - A namespace context for interpreting a prefix within a QName.
Returns:
A string containing a lexical representation of QName
Throws:
IllegalArgumentException - if val is null or if nsc is non-null or nsc.getPrefix(nsprefixFromVal) is null.

printDateTime

String printDateTime(Calendar val)

Converts a Calendar value into a string.

Parameters:
val - A Calendar value
Returns:
A string containing a lexical representation of xsd:dateTime
Throws:
IllegalArgumentException - if val is null.

printBase64Binary

String printBase64Binary(byte[] val)

Converts an array of bytes into a string.

Parameters:
val - an array of bytes
Returns:
A string containing a lexical representation of xsd:base64Binary
Throws:
IllegalArgumentException - if val is null.

printHexBinary

String printHexBinary(byte[] val)

Converts an array of bytes into a string.

Parameters:
val - an array of bytes
Returns:
A string containing a lexical representation of xsd:hexBinary
Throws:
IllegalArgumentException - if val is null.

printUnsignedInt

String printUnsignedInt(long val)

Converts a long value into a string.

Parameters:
val - A long value
Returns:
A string containing a lexical representation of xsd:unsignedInt

printUnsignedShort

String printUnsignedShort(int val)

Converts an int value into a string.

Parameters:
val - An int value
Returns:
A string containing a lexical representation of xsd:unsignedShort

printTime

String printTime(Calendar val)

Converts a Calendar value into a string.

Parameters:
val - A Calendar value
Returns:
A string containing a lexical representation of xsd:time
Throws:
IllegalArgumentException - if val is null.

printDate

String printDate(Calendar val)

Converts a Calendar value into a string.

Parameters:
val - A Calendar value
Returns:
A string containing a lexical representation of xsd:date
Throws:
IllegalArgumentException - if val is null.

printAnySimpleType

String printAnySimpleType(String val)

Converts a string value into a string.

Parameters:
val - A string value
Returns:
A string containing a lexical representation of xsd:AnySimpleType
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


helpers

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.bind.helpers

JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

See:
Description

Class Summary
AbstractMarshallerImpl | Partial default Marshaller implementation.
AbstractUnmarshallerImpl | Partial default Unmarshaller implementation.
DefaultValidationEventHandler | JAXB 1.0 only default validation event handler.
NotIdentifiableEventImpl | Default implementation of the NotIdentifiableEvent interface.
ParseConversionEventImpl | Default implementation of the ParseConversionEvent interface.
PrintConversionEventImpl | Default implementation of the PrintConversionEvent interface.
ValidationEventImpl | Default implementation of the ValidationEvent interface.
ValidationEventLocatorImpl | Default implementation of the ValidationEventLocator interface.

Package javax.xml.bind.helpers Description

JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

JAXB Providers can extend these classes and implement the abstract methods.

Package Specification

  • JAXB Specification

Related Documentation

For overviews, tutorials, examples, guides, and tool documentation, please see:
  • The JAXB Website

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.bind.helpers Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.bind.helpers

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.bind.helpers.AbstractMarshallerImpl (implements javax.xml.bind.Marshaller)
    • javax.xml.bind.helpers.AbstractUnmarshallerImpl (implements javax.xml.bind.Unmarshaller)
    • javax.xml.bind.helpers.DefaultValidationEventHandler (implements javax.xml.bind.ValidationEventHandler)
    • javax.xml.bind.helpers.ValidationEventImpl (implements javax.xml.bind.ValidationEvent)
      • javax.xml.bind.helpers.NotIdentifiableEventImpl (implements javax.xml.bind.NotIdentifiableEvent)
      • javax.xml.bind.helpers.ParseConversionEventImpl (implements javax.xml.bind.ParseConversionEvent)
      • javax.xml.bind.helpers.PrintConversionEventImpl (implements javax.xml.bind.PrintConversionEvent)
    • javax.xml.bind.helpers.ValidationEventLocatorImpl (implements javax.xml.bind.ValidationEventLocator)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.bind.helpers

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.bind.helpers

Packages that use javax.xml.bind.helpers
javax.xml.bind.helpers JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

Classes in javax.xml.bind.helpers used by javax.xml.bind.helpers
ValidationEventImpl
Default implementation of the ValidationEvent interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AbstractMarshallerImpl

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.helpers
Class AbstractMarshallerImpl

java.lang.Object
    extended by  javax.xml.bind.helpers.AbstractMarshallerImpl
All Implemented Interfaces:
Marshaller
public abstract class AbstractMarshallerImpl
extends Object
implements Marshaller

Partial default Marshaller implementation.

This class provides a partial default implementation for the Marshaller interface.

The only methods that a JAXB Provider has to implement are
marshal(Object, javax.xml.transform.Result),
marshal(Object, javax.xml.stream.XMLStreamWriter), and
marshal(Object, javax.xml.stream.XMLEventWriter).

Since:
JAXB1.0
See Also:
Marshaller

Nested Class Summary
Nested classes/interfaces inherited from interface javax.xml.bind.Marshaller
Marshaller.Listener
Field Summary
Fields inherited from interface javax.xml.bind.Marshaller
JAXB_ENCODING, JAXB_FORMATTED_OUTPUT, JAXB_FRAGMENT, JAXB_NO_NAMESPACE_SCHEMA_LOCATION, JAXB_SCHEMA_LOCATION
Constructor Summary
AbstractMarshallerImpl()
Method Summary
<A extends XmlAdapter>
A
getAdapter(Class<A> type)
Gets the adapter associated with the specified type.
 AttachmentMarshaller getAttachmentMarshaller()
protected  String getEncoding()
Convenience method for getting the current output encoding.
 ValidationEventHandler getEventHandler()
Return the current event handler or the default event handler if one hasn't been set.
protected  String getJavaEncoding(String encoding)
Gets the corresponding Java encoding name from an IANA name.
 Marshaller.Listener getListener()
Return Marshaller.Listener registered with this Marshaller.
 Node getNode(Object obj)
By default, the getNode method is unsupported and throw an UnsupportedOperationException.
protected  String getNoNSSchemaLocation()
Convenience method for getting the current noNamespaceSchemaLocation.
 Object getProperty(String name)
Default implementation of the getProperty method handles the four defined properties in Marshaller.
 Schema getSchema()
Get the JAXP 1.3 Schema object being used to perform marshal-time validation.
protected  String getSchemaLocation()
Convenience method for getting the current schemaLocation.
protected  boolean isFormattedOutput()
Convenience method for getting the formatted output flag.
protected  boolean isFragment()
Convenience method for getting the fragment flag.
 void marshal(Object obj, ContentHandler handler)
Marshal the content tree rooted at jaxbElement into SAX2 events.
 void marshal(Object obj, Node node)
Marshal the content tree rooted at jaxbElement into a DOM tree.
 void marshal(Object obj, OutputStream os)
Marshal the content tree rooted at jaxbElement into an output stream.
 void marshal(Object obj, Writer w)
Marshal the content tree rooted at jaxbElement into a Writer.
 void marshal(Object obj, XMLEventWriter writer)
Marshal the content tree rooted at jaxbElement into a XMLEventWriter.
 void marshal(Object obj, XMLStreamWriter writer)
Marshal the content tree rooted at jaxbElement into a XMLStreamWriter.
<A extends XmlAdapter>
void
setAdapter(Class<A> type, A adapter)
Associates a configured instance of XmlAdapter with this marshaller.
 void setAdapter(XmlAdapter adapter)
Associates a configured instance of XmlAdapter with this marshaller.
 void setAttachmentMarshaller(AttachmentMarshaller am)
Associate a context that enables binary data within an XML document to be transmitted as XML-binary optimized attachment.
protected  void setEncoding(String encoding)
Convenience method for setting the output encoding.
 void setEventHandler(ValidationEventHandler handler)
Allow an application to register a validation event handler.
protected  void setFormattedOutput(boolean v)
Convenience method for setting the formatted output flag.
protected  void setFragment(boolean v)
Convenience method for setting the fragment flag.
 void setListener(Marshaller.Listener listener)
Register marshal event callback Marshaller.Listener with this Marshaller.
protected  void setNoNSSchemaLocation(String location)
Convenience method for setting the noNamespaceSchemaLocation.
 void setProperty(String name, Object value)
Default implementation of the setProperty method handles the four defined properties in Marshaller.
 void setSchema(Schema schema)
Specify the JAXP 1.3 Schema object that should be used to validate subsequent marshal operations against.
protected  void setSchemaLocation(String location)
Convenience method for setting the schemaLocation.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.xml.bind.Marshaller
marshal

Constructor Detail

AbstractMarshallerImpl

public AbstractMarshallerImpl()
Method Detail

marshal

public final void marshal(Object obj,
                          OutputStream os)
                   throws JAXBException
Description copied from interface: Marshaller
Marshal the content tree rooted at jaxbElement into an output stream.

Specified by:
marshal in interface Marshaller
Parameters:
obj - The root of content tree to be marshalled.
os - XML will be added to this stream.
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal obj (or any object reachable from obj). See Marshalling a JAXB element.

marshal

public final void marshal(Object obj,
                          Writer w)
                   throws JAXBException
Description copied from interface: Marshaller
Marshal the content tree rooted at jaxbElement into a Writer.

Specified by:
marshal in interface Marshaller
Parameters:
obj - The root of content tree to be marshalled.
w - XML will be sent to this writer.
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal obj (or any object reachable from obj). See Marshalling a JAXB element.

marshal

public final void marshal(Object obj,
                          ContentHandler handler)
                   throws JAXBException
Description copied from interface: Marshaller
Marshal the content tree rooted at jaxbElement into SAX2 events.

Specified by:
marshal in interface Marshaller
Parameters:
obj - The root of content tree to be marshalled.
handler - XML will be sent to this handler as SAX2 events.
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal obj (or any object reachable from obj). See Marshalling a JAXB element.

marshal

public final void marshal(Object obj,
                          Node node)
                   throws JAXBException
Description copied from interface: Marshaller
Marshal the content tree rooted at jaxbElement into a DOM tree.

Specified by:
marshal in interface Marshaller
Parameters:
obj - The content tree to be marshalled.
node - DOM nodes will be added as children of this node. This parameter must be a Node that accepts children (Document, DocumentFragment, or Element)
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal jaxbElement (or any object reachable from jaxbElement). See Marshalling a JAXB element.

getNode

public Node getNode(Object obj)
             throws JAXBException
By default, the getNode method is unsupported and throw an UnsupportedOperationException. Implementations that choose to support this method must override this method.

Specified by:
getNode in interface Marshaller
Parameters:
obj - - JAXB Java representation of XML content
Returns:
the DOM tree view of the contentTree
Throws:
JAXBException - If any unexpected problem occurs

getEncoding

protected String getEncoding()
Convenience method for getting the current output encoding.

Returns:
the current encoding or "UTF-8" if it hasn't been set.

setEncoding

protected void setEncoding(String encoding)
Convenience method for setting the output encoding.

Parameters:
encoding - a valid encoding as specified in the Marshaller class documentation

getSchemaLocation

protected String getSchemaLocation()
Convenience method for getting the current schemaLocation.

Returns:
the current schemaLocation or null if it hasn't been set

setSchemaLocation

protected void setSchemaLocation(String location)
Convenience method for setting the schemaLocation.

Parameters:
location - the schemaLocation value

getNoNSSchemaLocation

protected String getNoNSSchemaLocation()
Convenience method for getting the current noNamespaceSchemaLocation.

Returns:
the current noNamespaceSchemaLocation or null if it hasn't been set

setNoNSSchemaLocation

protected void setNoNSSchemaLocation(String location)
Convenience method for setting the noNamespaceSchemaLocation.

Parameters:
location - the noNamespaceSchemaLocation value

isFormattedOutput

protected boolean isFormattedOutput()
Convenience method for getting the formatted output flag.

Returns:
the current value of the formatted output flag or false if it hasn't been set.

setFormattedOutput

protected void setFormattedOutput(boolean v)
Convenience method for setting the formatted output flag.

Parameters:
v - value of the formatted output flag.

isFragment

protected boolean isFragment()
Convenience method for getting the fragment flag.

Returns:
the current value of the fragment flag or false if it hasn't been set.

setFragment

protected void setFragment(boolean v)
Convenience method for setting the fragment flag.

Parameters:
v - value of the fragment flag.

getJavaEncoding

protected String getJavaEncoding(String encoding)
                          throws UnsupportedEncodingException
Gets the corresponding Java encoding name from an IANA name. This method is a helper method for the derived class to convert encoding names.

Throws:
UnsupportedEncodingException - If this implementation couldn't find the Java encoding name.

setProperty

public void setProperty(String name,
                        Object value)
                 throws PropertyException
Default implementation of the setProperty method handles the four defined properties in Marshaller. If a provider needs to handle additional properties, it should override this method in a derived class.

Specified by:
setProperty in interface Marshaller
Parameters:
name - the name of the property to be set. This value can either be specified using one of the constant fields or a user supplied string.
value - the value of the property to be set
Throws:
PropertyException - when there is an error processing the given property or value

getProperty

public Object getProperty(String name)
                   throws PropertyException
Default implementation of the getProperty method handles the four defined properties in Marshaller. If a provider needs to support additional provider specific properties, it should override this method in a derived class.

Specified by:
getProperty in interface Marshaller
Parameters:
name - the name of the property to retrieve
Returns:
the value of the requested property
Throws:
PropertyException - when there is an error retrieving the given property or value property name

getEventHandler

public ValidationEventHandler getEventHandler()
                                       throws JAXBException
Description copied from interface: Marshaller
Return the current event handler or the default event handler if one hasn't been set.

Specified by:
getEventHandler in interface Marshaller
Returns:
the current ValidationEventHandler or the default event handler if it hasn't been set
Throws:
JAXBException - if an error was encountered while getting the current event handler
See Also:
Marshaller.getEventHandler()

setEventHandler

public void setEventHandler(ValidationEventHandler handler)
                     throws JAXBException
Description copied from interface: Marshaller
Allow an application to register a validation event handler.

The validation event handler will be called by the JAXB Provider if any validation errors are encountered during calls to any of the marshal API's. If the client application does not register a validation event handler before invoking one of the marshal methods, then validation events will be handled by the default event handler which will terminate the marshal operation after the first error or fatal error is encountered.

Calling this method with a null parameter will cause the Marshaller to revert back to the default default event handler.

Specified by:
setEventHandler in interface Marshaller
Parameters:
handler - the validation event handler
Throws:
JAXBException - if an error was encountered while setting the event handler
See Also:
Marshaller.setEventHandler(ValidationEventHandler)

marshal

public void marshal(Object obj,
                    XMLEventWriter writer)
             throws JAXBException
Description copied from interface: Marshaller
Marshal the content tree rooted at jaxbElement into a XMLEventWriter.

Specified by:
marshal in interface Marshaller
Parameters:
obj - The content tree rooted at jaxbElement to be marshalled.
writer - XML will be sent to this writer.
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal obj (or any object reachable from obj). See Marshalling a JAXB element.

marshal

public void marshal(Object obj,
                    XMLStreamWriter writer)
             throws JAXBException
Description copied from interface: Marshaller
Marshal the content tree rooted at jaxbElement into a XMLStreamWriter.

Specified by:
marshal in interface Marshaller
Parameters:
obj - The content tree to be marshalled.
writer - XML will be sent to this writer.
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal obj (or any object reachable from obj). See Marshalling a JAXB element.

setSchema

public void setSchema(Schema schema)
Description copied from interface: Marshaller
Specify the JAXP 1.3 Schema object that should be used to validate subsequent marshal operations against. Passing null into this method will disable validation.

This method allows the caller to validate the marshalled XML as it's marshalled.

Initially this property is set to null.

Specified by:
setSchema in interface Marshaller
Parameters:
schema - Schema object to validate marshal operations against or null to disable validation

getSchema

public Schema getSchema()
Description copied from interface: Marshaller
Get the JAXP 1.3 Schema object being used to perform marshal-time validation. If there is no Schema set on the marshaller, then this method will return null indicating that marshal-time validation will not be performed.

Specified by:
getSchema in interface Marshaller
Returns:
the Schema object being used to perform marshal-time validation or null if not present.

setAdapter

public void setAdapter(XmlAdapter adapter)
Description copied from interface: Marshaller
Associates a configured instance of XmlAdapter with this marshaller.

This is a convenience method that invokes setAdapter(adapter.getClass(),adapter);.

Specified by:
setAdapter in interface Marshaller
See Also:
Marshaller.setAdapter(Class,XmlAdapter)

setAdapter

public <A extends XmlAdapter> void setAdapter(Class<A> type,
                                              A adapter)
Description copied from interface: Marshaller
Associates a configured instance of XmlAdapter with this marshaller.

Every marshaller internally maintains a Map<Class,XmlAdapter>, which it uses for marshalling classes whose fields/methods are annotated with XmlJavaTypeAdapter.

This method allows applications to use a configured instance of XmlAdapter. When an instance of an adapter is not given, a marshaller will create one by invoking its default constructor.

Specified by:
setAdapter in interface Marshaller
Parameters:
type - The type of the adapter. The specified instance will be used when XmlJavaTypeAdapter.value() refers to this type.
adapter - The instance of the adapter to be used. If null, it will un-register the current adapter set for this type.

getAdapter

public <A extends XmlAdapter> A getAdapter(Class<A> type)
Description copied from interface: Marshaller
Gets the adapter associated with the specified type. This is the reverse operation of the Marshaller.setAdapter(javax.xml.bind.annotation.adapters.XmlAdapter) method.

Specified by:
getAdapter in interface Marshaller

setAttachmentMarshaller

public void setAttachmentMarshaller(AttachmentMarshaller am)
Description copied from interface: Marshaller

Associate a context that enables binary data within an XML document to be transmitted as XML-binary optimized attachment. The attachment is referenced from the XML document content model by content-id URIs(cid) references stored within the xml document.

Specified by:
setAttachmentMarshaller in interface Marshaller

getAttachmentMarshaller

public AttachmentMarshaller getAttachmentMarshaller()
Specified by:
getAttachmentMarshaller in interface Marshaller

setListener

public void setListener(Marshaller.Listener listener)
Description copied from interface: Marshaller

Register marshal event callback Marshaller.Listener with this Marshaller.

There is only one Listener per Marshaller. Setting a Listener replaces the previous set Listener. One can unregister current Listener by setting listener to null.

Specified by:
setListener in interface Marshaller
Parameters:
listener - an instance of a class that implements Marshaller.Listener

getListener

public Marshaller.Listener getListener()
Description copied from interface: Marshaller

Return Marshaller.Listener registered with this Marshaller.

Specified by:
getListener in interface Marshaller
Returns:
registered Marshaller.Listener or null if no Listener is registered with this Marshaller.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AbstractUnmarshallerImpl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.helpers
Class AbstractUnmarshallerImpl

java.lang.Object
    extended by  javax.xml.bind.helpers.AbstractUnmarshallerImpl
All Implemented Interfaces:
Unmarshaller
public abstract class AbstractUnmarshallerImpl
extends Object
implements Unmarshaller

Partial default Unmarshaller implementation.

This class provides a partial default implementation for the Unmarshallerinterface.

A JAXB Provider has to implement five methods (getUnmarshallerHandler, unmarshal(Node), unmarshal(XMLReader,InputSource), unmarshal(XMLStreamReader), and unmarshal(XMLEventReader).

Since:
JAXB1.0
See Also:
Unmarshaller

Nested Class Summary
Nested classes/interfaces inherited from interface javax.xml.bind.Unmarshaller
Unmarshaller.Listener
Field Summary
protected  boolean validating
whether or not the unmarshaller will validate
Constructor Summary
AbstractUnmarshallerImpl()
Method Summary
protected  UnmarshalException createUnmarshalException(SAXException e)
Creates an UnmarshalException from a SAXException.
<A extends XmlAdapter>
A
getAdapter(Class<A> type)
Gets the adapter associated with the specified type.
 AttachmentUnmarshaller getAttachmentUnmarshaller()
 ValidationEventHandler getEventHandler()
Return the current event handler or the default event handler if one hasn't been set.
 Unmarshaller.Listener getListener()
Return Unmarshaller.Listener registered with this Unmarshaller.
 Object getProperty(String name)
Default implementation of the getProperty method always throws PropertyException since there are no required properties.
 Schema getSchema()
Get the JAXP 1.3 Schema object being used to perform unmarshal-time validation.
protected  XMLReader getXMLReader()
Obtains a configured XMLReader.
 boolean isValidating()
Indicates whether or not the Unmarshaller is configured to validate during unmarshal operations.
<A extends XmlAdapter>
void
setAdapter(Class<A> type, A adapter)
Associates a configured instance of XmlAdapter with this unmarshaller.
 void setAdapter(XmlAdapter adapter)
Associates a configured instance of XmlAdapter with this unmarshaller.
 void setAttachmentUnmarshaller(AttachmentUnmarshaller au)
Associate a context that resolves cid's, content-id URIs, to binary data passed as attachments.
 void setEventHandler(ValidationEventHandler handler)
Allow an application to register a validation event handler.
 void setListener(Unmarshaller.Listener listener)
Register unmarshal event callback Unmarshaller.Listener with this Unmarshaller.
 void setProperty(String name, Object value)
Default implementation of the setProperty method always throws PropertyException since there are no required properties.
 void setSchema(Schema schema)
Specify the JAXP 1.3 Schema object that should be used to validate subsequent unmarshal operations against.
 void setValidating(boolean validating)
Specifies whether or not the Unmarshaller should validate during unmarshal operations.
 Object unmarshal(File f)
Unmarshal XML data from the specified file and return the resulting content tree.
 Object unmarshal(InputSource source)
Unmarshal XML data from the specified SAX InputSource and return the resulting content tree.
 Object unmarshal(InputStream is)
Unmarshal XML data from the specified InputStream and return the resulting content tree.
<T> JAXBElement<T>
unmarshal(Node node, Class<T> expectedType)
Unmarshal XML data by JAXB mapped declaredType and return the resulting content tree.
 Object unmarshal(Reader reader)
Unmarshal XML data from the specified Reader and return the resulting content tree.
 Object unmarshal(Source source)
Unmarshal XML data from the specified XML Source and return the resulting content tree.
<T> JAXBElement<T>
unmarshal(Source source, Class<T> expectedType)
Unmarshal XML data from the specified XML Source by declaredType and return the resulting content tree.
 Object unmarshal(URL url)
Unmarshal XML data from the specified URL and return the resulting content tree.
 Object unmarshal(XMLEventReader reader)
Unmarshal XML data from the specified pull parser and return the resulting content tree.
<T> JAXBElement<T>
unmarshal(XMLEventReader reader, Class<T> expectedType)
Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.
protected abstract  Object unmarshal(XMLReader reader, InputSource source)
Unmarshals an object by using the specified XMLReader and the InputSource.
 Object unmarshal(XMLStreamReader reader)
Unmarshal XML data from the specified pull parser and return the resulting content tree.
<T> JAXBElement<T>
unmarshal(XMLStreamReader reader, Class<T> expectedType)
Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.xml.bind.Unmarshaller
getUnmarshallerHandler, unmarshal

Field Detail

validating

protected boolean validating
whether or not the unmarshaller will validate

Constructor Detail

AbstractUnmarshallerImpl

public AbstractUnmarshallerImpl()
Method Detail

getXMLReader

protected XMLReader getXMLReader()
                          throws JAXBException
Obtains a configured XMLReader. This method is used when the client-specified SAXSource object doesn't have XMLReader. Unmarshaller is not re-entrant, so we will only use one instance of XMLReader.

Throws:
JAXBException

unmarshal

public Object unmarshal(Source source)
                 throws JAXBException
Description copied from interface: Unmarshaller
Unmarshal XML data from the specified XML Source and return the resulting content tree.

Implements Unmarshal Global Root Element.

SAX 2.0 Parser Pluggability

A client application can choose not to use the default parser mechanism supplied with their JAXB provider. Any SAX 2.0 compliant parser can be substituted for the JAXB provider's default mechanism. To do so, the client application must properly configure a SAXSource containing an XMLReader implemented by the SAX 2.0 parser provider. If the XMLReader has an org.xml.sax.ErrorHandler registered on it, it will be replaced by the JAXB Provider so that validation errors can be reported via the ValidationEventHandler mechanism of JAXB. If the SAXSource does not contain an XMLReader, then the JAXB provider's default parser mechanism will be used.

This parser replacement mechanism can also be used to replace the JAXB provider's unmarshal-time validation engine. The client application must properly configure their SAX 2.0 compliant parser to perform validation (as shown in the example above). Any SAXParserExceptions encountered by the parser during the unmarshal operation will be processed by the JAXB provider and converted into JAXB ValidationEvent objects which will be reported back to the client via the ValidationEventHandler registered with the Unmarshaller. Note: specifying a substitute validating SAX 2.0 parser for unmarshalling does not necessarily replace the validation engine used by the JAXB provider for performing on-demand validation.

The only way for a client application to specify an alternate parser mechanism to be used during unmarshal is via the unmarshal(SAXSource) API. All other forms of the unmarshal method (File, URL, Node, etc) will use the JAXB provider's default parser and validator mechanisms.

Specified by:
unmarshal in interface Unmarshaller
Parameters:
source - the XML Source to unmarshal XML data from (providers are only required to support SAXSource, DOMSource, and StreamSource)
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
See Also:
Unmarshaller.unmarshal(javax.xml.transform.Source, Class)

unmarshal

protected abstract Object unmarshal(XMLReader reader,
                                    InputSource source)
                             throws JAXBException
Unmarshals an object by using the specified XMLReader and the InputSource. The callee should call the setErrorHandler method of the XMLReader so that errors are passed to the client-specified ValidationEventHandler.

Throws:
JAXBException

unmarshal

public final Object unmarshal(InputSource source)
                       throws JAXBException
Description copied from interface: Unmarshaller
Unmarshal XML data from the specified SAX InputSource and return the resulting content tree.

Implements Unmarshal Global Root Element.

Specified by:
unmarshal in interface Unmarshaller
Parameters:
source - the input source to unmarshal XML data from
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data

unmarshal

public final Object unmarshal(URL url)
                       throws JAXBException
Description copied from interface: Unmarshaller
Unmarshal XML data from the specified URL and return the resulting content tree.

Implements Unmarshal Global Root Element.

Specified by:
unmarshal in interface Unmarshaller
Parameters:
url - the url to unmarshal XML data from
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data

unmarshal

public final Object unmarshal(File f)
                       throws JAXBException
Description copied from interface: Unmarshaller
Unmarshal XML data from the specified file and return the resulting content tree.

Implements Unmarshal Global Root Element.

Specified by:
unmarshal in interface Unmarshaller
Parameters:
f - the file to unmarshal XML data from
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data

unmarshal

public final Object unmarshal(InputStream is)
                       throws JAXBException
Description copied from interface: Unmarshaller
Unmarshal XML data from the specified InputStream and return the resulting content tree. Validation event location information may be incomplete when using this form of the unmarshal API.

Implements Unmarshal Global Root Element.

Specified by:
unmarshal in interface Unmarshaller
Parameters:
is - the InputStream to unmarshal XML data from
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data

unmarshal

public final Object unmarshal(Reader reader)
                       throws JAXBException
Description copied from interface: Unmarshaller
Unmarshal XML data from the specified Reader and return the resulting content tree. Validation event location information may be incomplete when using this form of the unmarshal API, because a Reader does not provide the system ID.

Implements Unmarshal Global Root Element.

Specified by:
unmarshal in interface Unmarshaller
Parameters:
reader - the Reader to unmarshal XML data from
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data

isValidating

public boolean isValidating()
                     throws JAXBException
Indicates whether or not the Unmarshaller is configured to validate during unmarshal operations.

Note: I named this method isValidating() to stay in-line with JAXP, as opposed to naming it getValidating().

Specified by:
isValidating in interface Unmarshaller
Returns:
true if the Unmarshaller is configured to validate during unmarshal operations, false otherwise
Throws:
JAXBException - if an error occurs while retrieving the validating flag

setEventHandler

public void setEventHandler(ValidationEventHandler handler)
                     throws JAXBException
Allow an application to register a validation event handler.

The validation event handler will be called by the JAXB Provider if any validation errors are encountered during calls to any of the unmarshal methods. If the client application does not register a validation event handler before invoking the unmarshal methods, then all validation events will be silently ignored and may result in unexpected behaviour.

Specified by:
setEventHandler in interface Unmarshaller
Parameters:
handler - the validation event handler
Throws:
JAXBException - if an error was encountered while setting the event handler

setValidating

public void setValidating(boolean validating)
                   throws JAXBException
Specifies whether or not the Unmarshaller should validate during unmarshal operations. By default, the Unmarshaller does not validate.

This method may only be invoked before or after calling one of the unmarshal methods.

Specified by:
setValidating in interface Unmarshaller
Parameters:
validating - true if the Unmarshaller should validate during unmarshal, false otherwise
Throws:
JAXBException - if an error occurred while enabling or disabling validation at unmarshal time

getEventHandler

public ValidationEventHandler getEventHandler()
                                       throws JAXBException
Return the current event handler or the default event handler if one hasn't been set.

Specified by:
getEventHandler in interface Unmarshaller
Returns:
the current ValidationEventHandler or the default event handler if it hasn't been set
Throws:
JAXBException - if an error was encountered while getting the current event handler

createUnmarshalException

protected UnmarshalException createUnmarshalException(SAXException e)
Creates an UnmarshalException from a SAXException. This is an utility method provided for the derived classes.

When a provider-implemented ContentHandler wants to throw a JAXBException, it needs to wrap the exception by a SAXException. If the unmarshaller implementation blindly wrap SAXException by JAXBException, such an exception will be a JAXBException wrapped by a SAXException wrapped by another JAXBException. This is silly.

This method checks the nested exception of SAXException and reduce those excessive wrapping.

Returns:
the resulting UnmarshalException

setProperty

public void setProperty(String name,
                        Object value)
                 throws PropertyException
Default implementation of the setProperty method always throws PropertyException since there are no required properties. If a provider needs to handle additional properties, it should override this method in a derived class.

Specified by:
setProperty in interface Unmarshaller
Parameters:
name - the name of the property to be set. This value can either be specified using one of the constant fields or a user supplied string.
value - the value of the property to be set
Throws:
PropertyException - when there is an error processing the given property or value

getProperty

public Object getProperty(String name)
                   throws PropertyException
Default implementation of the getProperty method always throws PropertyException since there are no required properties. If a provider needs to handle additional properties, it should override this method in a derived class.

Specified by:
getProperty in interface Unmarshaller
Parameters:
name - the name of the property to retrieve
Returns:
the value of the requested property
Throws:
PropertyException - when there is an error retrieving the given property or value property name

unmarshal

public Object unmarshal(XMLEventReader reader)
                 throws JAXBException
Description copied from interface: Unmarshaller
Unmarshal XML data from the specified pull parser and return the resulting content tree.

This method is an Unmarshal Global Root method.

This method assumes that the parser is on a START_DOCUMENT or START_ELEMENT event. Unmarshalling will be done from this start event to the corresponding end event. If this method returns successfully, the reader will be pointing at the token right after the end event.

Specified by:
unmarshal in interface Unmarshaller
Parameters:
reader - The parser to be read.
Returns:
the newly created root object of the java content tree.
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
See Also:
Unmarshaller.unmarshal(javax.xml.stream.XMLEventReader, Class)

unmarshal

public Object unmarshal(XMLStreamReader reader)
                 throws JAXBException
Description copied from interface: Unmarshaller
Unmarshal XML data from the specified pull parser and return the resulting content tree.

Implements Unmarshal Global Root Element.

This method assumes that the parser is on a START_DOCUMENT or START_ELEMENT event. Unmarshalling will be done from this start event to the corresponding end event. If this method returns successfully, the reader will be pointing at the token right after the end event.

Specified by:
unmarshal in interface Unmarshaller
Parameters:
reader - The parser to be read.
Returns:
the newly created root object of the java content tree.
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
See Also:
Unmarshaller.unmarshal(javax.xml.stream.XMLStreamReader, Class)

unmarshal

public <T> JAXBElement<T> unmarshal(Node node,
                                    Class<T> expectedType)
                         throws JAXBException
Description copied from interface: Unmarshaller
Unmarshal XML data by JAXB mapped declaredType and return the resulting content tree.

Implements Unmarshal by Declared Type

Specified by:
unmarshal in interface Unmarshaller
Parameters:
node - the document/element to unmarshal XML data from. The caller must support at least Document and Element.
expectedType - appropriate JAXB mapped class to hold node's XML data.
Returns:
JAXB Element representation of node
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data

unmarshal

public <T> JAXBElement<T> unmarshal(Source source,
                                    Class<T> expectedType)
                         throws JAXBException
Description copied from interface: Unmarshaller
Unmarshal XML data from the specified XML Source by declaredType and return the resulting content tree.

Implements Unmarshal by Declared Type

See SAX 2.0 Parser Pluggability

Specified by:
unmarshal in interface Unmarshaller
Parameters:
source - the XML Source to unmarshal XML data from (providers are only required to support SAXSource, DOMSource, and StreamSource)
expectedType - appropriate JAXB mapped class to hold source's xml root element
Returns:
Java content rooted by JAXB Element
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data

unmarshal

public <T> JAXBElement<T> unmarshal(XMLStreamReader reader,
                                    Class<T> expectedType)
                         throws JAXBException
Description copied from interface: Unmarshaller
Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.

This method implements unmarshal by declaredType.

This method assumes that the parser is on a START_DOCUMENT or START_ELEMENT event. Unmarshalling will be done from this start event to the corresponding end event. If this method returns successfully, the reader will be pointing at the token right after the end event.

Specified by:
unmarshal in interface Unmarshaller
Parameters:
reader - The parser to be read.
expectedType - appropriate JAXB mapped class to hold reader's START_ELEMENT XML data.
Returns:
content tree rooted by JAXB Element representation
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data

unmarshal

public <T> JAXBElement<T> unmarshal(XMLEventReader reader,
                                    Class<T> expectedType)
                         throws JAXBException
Description copied from interface: Unmarshaller
Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.

This method implements unmarshal by declaredType.

This method assumes that the parser is on a START_DOCUMENT or START_ELEMENT event. Unmarshalling will be done from this start event to the corresponding end event. If this method returns successfully, the reader will be pointing at the token right after the end event.

Specified by:
unmarshal in interface Unmarshaller
Parameters:
reader - The parser to be read.
expectedType - appropriate JAXB mapped class to hold reader's START_ELEMENT XML data.
Returns:
content tree rooted by JAXB Element representation
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data

setSchema

public void setSchema(Schema schema)
Description copied from interface: Unmarshaller
Specify the JAXP 1.3 Schema object that should be used to validate subsequent unmarshal operations against. Passing null into this method will disable validation.

This method replaces the deprecated setValidating(boolean) API.

Initially this property is set to null.

Specified by:
setSchema in interface Unmarshaller
Parameters:
schema - Schema object to validate unmarshal operations against or null to disable validation

getSchema

public Schema getSchema()
Description copied from interface: Unmarshaller
Get the JAXP 1.3 Schema object being used to perform unmarshal-time validation. If there is no Schema set on the unmarshaller, then this method will return null indicating that unmarshal-time validation will not be performed.

This method provides replacement functionality for the deprecated Unmarshaller.isValidating() API as well as access to the Schema object. To determine if the Unmarshaller has validation enabled, simply test the return type for null:

boolean isValidating = u.getSchema()!=null;

Specified by:
getSchema in interface Unmarshaller
Returns:
the Schema object being used to perform unmarshal-time validation or null if not present

setAdapter

public void setAdapter(XmlAdapter adapter)
Description copied from interface: Unmarshaller
Associates a configured instance of XmlAdapter with this unmarshaller.

This is a convenience method that invokes setAdapter(adapter.getClass(),adapter);.

Specified by:
setAdapter in interface Unmarshaller
See Also:
Unmarshaller.setAdapter(Class,XmlAdapter)

setAdapter

public <A extends XmlAdapter> void setAdapter(Class<A> type,
                                              A adapter)
Description copied from interface: Unmarshaller
Associates a configured instance of XmlAdapter with this unmarshaller.

Every unmarshaller internally maintains a Map<Class,XmlAdapter>, which it uses for unmarshalling classes whose fields/methods are annotated with XmlJavaTypeAdapter.

This method allows applications to use a configured instance of XmlAdapter. When an instance of an adapter is not given, an unmarshaller will create one by invoking its default constructor.

Specified by:
setAdapter in interface Unmarshaller
Parameters:
type - The type of the adapter. The specified instance will be used when XmlJavaTypeAdapter.value() refers to this type.
adapter - The instance of the adapter to be used. If null, it will un-register the current adapter set for this type.

getAdapter

public <A extends XmlAdapter> A getAdapter(Class<A> type)
Description copied from interface: Unmarshaller
Gets the adapter associated with the specified type. This is the reverse operation of the Unmarshaller.setAdapter(javax.xml.bind.annotation.adapters.XmlAdapter) method.

Specified by:
getAdapter in interface Unmarshaller

setAttachmentUnmarshaller

public void setAttachmentUnmarshaller(AttachmentUnmarshaller au)
Description copied from interface: Unmarshaller

Associate a context that resolves cid's, content-id URIs, to binary data passed as attachments.

Unmarshal time validation, enabled via Unmarshaller.setSchema(Schema), must be supported even when unmarshaller is performing XOP processing.

Specified by:
setAttachmentUnmarshaller in interface Unmarshaller

getAttachmentUnmarshaller

public AttachmentUnmarshaller getAttachmentUnmarshaller()
Specified by:
getAttachmentUnmarshaller in interface Unmarshaller

setListener

public void setListener(Unmarshaller.Listener listener)
Description copied from interface: Unmarshaller

Register unmarshal event callback Unmarshaller.Listener with this Unmarshaller.

There is only one Listener per Unmarshaller. Setting a Listener replaces the previous set Listener. One can unregister current Listener by setting listener to null.

Specified by:
setListener in interface Unmarshaller
Parameters:
listener - provides unmarshal event callbacks for this Unmarshaller

getListener

public Unmarshaller.Listener getListener()
Description copied from interface: Unmarshaller

Return Unmarshaller.Listener registered with this Unmarshaller.

Specified by:
getListener in interface Unmarshaller
Returns:
registered Unmarshaller.Listener or null if no Listener is registered with this Unmarshaller.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.xml.bind.helpers.AbstractMarshallerImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.helpers.AbstractMarshallerImpl

No usage of javax.xml.bind.helpers.AbstractMarshallerImpl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.helpers.AbstractUnmarshallerImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.helpers.AbstractUnmarshallerImpl

No usage of javax.xml.bind.helpers.AbstractUnmarshallerImpl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.helpers.DefaultValidationEventHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.helpers.DefaultValidationEventHandler

No usage of javax.xml.bind.helpers.DefaultValidationEventHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.helpers.NotIdentifiableEventImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.helpers.NotIdentifiableEventImpl

No usage of javax.xml.bind.helpers.NotIdentifiableEventImpl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.helpers.ParseConversionEventImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.helpers.ParseConversionEventImpl

No usage of javax.xml.bind.helpers.ParseConversionEventImpl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.helpers.PrintConversionEventImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.helpers.PrintConversionEventImpl

No usage of javax.xml.bind.helpers.PrintConversionEventImpl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.helpers.ValidationEventImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.helpers.ValidationEventImpl

Packages that use ValidationEventImpl
javax.xml.bind.helpers JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.

Uses of ValidationEventImpl in javax.xml.bind.helpers

Subclasses of ValidationEventImpl in javax.xml.bind.helpers
class | NotIdentifiableEventImpl Default implementation of the NotIdentifiableEvent interface.
class | ParseConversionEventImpl Default implementation of the ParseConversionEvent interface.
class | PrintConversionEventImpl Default implementation of the PrintConversionEvent interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.helpers.ValidationEventLocatorImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.helpers.ValidationEventLocatorImpl

No usage of javax.xml.bind.helpers.ValidationEventLocatorImpl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DefaultValidationEventHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.helpers
Class DefaultValidationEventHandler

java.lang.Object
    extended by  javax.xml.bind.helpers.DefaultValidationEventHandler
All Implemented Interfaces:
ValidationEventHandler
public class DefaultValidationEventHandler
extends Object
implements ValidationEventHandler

JAXB 1.0 only default validation event handler. This is the default handler for all objects created from a JAXBContext that is managing schema-derived code generated by a JAXB 1.0 binding compiler.

This handler causes the unmarshal and validate operations to fail on the first error or fatal error.

This handler is not the default handler for JAXB mapped classes following JAXB 2.0 or later versions. Default validation event handling has changed and is specified in Unmarshaller and Marshaller.

Since:
JAXB1.0
See Also:
Unmarshaller, Validator, ValidationEventHandler

Constructor Summary
DefaultValidationEventHandler()
Method Summary
 boolean handleEvent(ValidationEvent event)
Receive notification of a validation warning or error.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultValidationEventHandler

public DefaultValidationEventHandler()
Method Detail

handleEvent

public boolean handleEvent(ValidationEvent event)
Description copied from interface: ValidationEventHandler
Receive notification of a validation warning or error. The ValidationEvent will have a ValidationEventLocator embedded in it that indicates where the error or warning occurred.

If an unchecked runtime exception is thrown from this method, the JAXB provider will treat it as if the method returned false and interrupt the current unmarshal, validate, or marshal operation.

Specified by:
handleEvent in interface ValidationEventHandler
Parameters:
event - the encapsulated validation event information. It is a provider error if this parameter is null.
Returns:
true if the JAXB Provider should attempt to continue the current unmarshal, validate, or marshal operation after handling this warning/error, false if the provider should terminate the current operation with the appropriate UnmarshalException, ValidationException, or MarshalException.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotIdentifiableEventImpl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.helpers
Class NotIdentifiableEventImpl

java.lang.Object
    extended by  javax.xml.bind.helpers.ValidationEventImpl
        extended by  javax.xml.bind.helpers.NotIdentifiableEventImpl
All Implemented Interfaces:
NotIdentifiableEvent, ValidationEvent
public class NotIdentifiableEventImpl
extends ValidationEventImpl
implements NotIdentifiableEvent

Default implementation of the NotIdentifiableEvent interface.

JAXB providers are allowed to use whatever class that implements the ValidationEvent interface. This class is just provided for a convenience.

Since:
JAXB1.0
See Also:
NotIdentifiableEvent, Validator, ValidationEventHandler, ValidationEvent, ValidationEventLocator

Field Summary
Fields inherited from interface javax.xml.bind.ValidationEvent
ERROR, FATAL_ERROR, WARNING
Constructor Summary
NotIdentifiableEventImpl(int _severity, String _message, ValidationEventLocator _locator)
Create a new NotIdentifiableEventImpl.
NotIdentifiableEventImpl(int _severity, String _message, ValidationEventLocator _locator, Throwable _linkedException)
Create a new NotIdentifiableEventImpl.
Method Summary
Methods inherited from class javax.xml.bind.helpers.ValidationEventImpl
getLinkedException, getLocator, getMessage, getSeverity, setLinkedException, setLocator, setMessage, setSeverity, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface javax.xml.bind.ValidationEvent
getLinkedException, getLocator, getMessage, getSeverity

Constructor Detail

NotIdentifiableEventImpl

public NotIdentifiableEventImpl(int _severity,
                                String _message,
                                ValidationEventLocator _locator)
Create a new NotIdentifiableEventImpl.

Parameters:
_severity - The severity value for this event. Must be one of ValidationEvent.WARNING, ValidationEvent.ERROR, or ValidationEvent.FATAL_ERROR
_message - The text message for this event - may be null.
_locator - The locator object for this event - may be null.
Throws:
IllegalArgumentException - if an illegal severity field is supplied

NotIdentifiableEventImpl

public NotIdentifiableEventImpl(int _severity,
                                String _message,
                                ValidationEventLocator _locator,
                                Throwable _linkedException)
Create a new NotIdentifiableEventImpl.

Parameters:
_severity - The severity value for this event. Must be one of ValidationEvent.WARNING, ValidationEvent.ERROR, or ValidationEvent.FATAL_ERROR
_message - The text message for this event - may be null.
_locator - The locator object for this event - may be null.
_linkedException - An optional linked exception that may provide additional information about the event - may be null.
Throws:
IllegalArgumentException - if an illegal severity field is supplied
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ParseConversionEventImpl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.helpers
Class ParseConversionEventImpl

java.lang.Object
    extended by  javax.xml.bind.helpers.ValidationEventImpl
        extended by  javax.xml.bind.helpers.ParseConversionEventImpl
All Implemented Interfaces:
ParseConversionEvent, ValidationEvent
public class ParseConversionEventImpl
extends ValidationEventImpl
implements ParseConversionEvent

Default implementation of the ParseConversionEvent interface.

JAXB providers are allowed to use whatever class that implements the ValidationEvent interface. This class is just provided for a convenience.

Since:
JAXB1.0
See Also:
ParseConversionEvent, Validator, ValidationEventHandler, ValidationEvent, ValidationEventLocator

Field Summary
Fields inherited from interface javax.xml.bind.ValidationEvent
ERROR, FATAL_ERROR, WARNING
Constructor Summary
ParseConversionEventImpl(int _severity, String _message, ValidationEventLocator _locator)
Create a new ParseConversionEventImpl.
ParseConversionEventImpl(int _severity, String _message, ValidationEventLocator _locator, Throwable _linkedException)
Create a new ParseConversionEventImpl.
Method Summary
Methods inherited from class javax.xml.bind.helpers.ValidationEventImpl
getLinkedException, getLocator, getMessage, getSeverity, setLinkedException, setLocator, setMessage, setSeverity, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface javax.xml.bind.ValidationEvent
getLinkedException, getLocator, getMessage, getSeverity

Constructor Detail

ParseConversionEventImpl

public ParseConversionEventImpl(int _severity,
                                String _message,
                                ValidationEventLocator _locator)
Create a new ParseConversionEventImpl.

Parameters:
_severity - The severity value for this event. Must be one of ValidationEvent.WARNING, ValidationEvent.ERROR, or ValidationEvent.FATAL_ERROR
_message - The text message for this event - may be null.
_locator - The locator object for this event - may be null.
Throws:
IllegalArgumentException - if an illegal severity field is supplied

ParseConversionEventImpl

public ParseConversionEventImpl(int _severity,
                                String _message,
                                ValidationEventLocator _locator,
                                Throwable _linkedException)
Create a new ParseConversionEventImpl.

Parameters:
_severity - The severity value for this event. Must be one of ValidationEvent.WARNING, ValidationEvent.ERROR, or ValidationEvent.FATAL_ERROR
_message - The text message for this event - may be null.
_locator - The locator object for this event - may be null.
_linkedException - An optional linked exception that may provide additional information about the event - may be null.
Throws:
IllegalArgumentException - if an illegal severity field is supplied
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrintConversionEventImpl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.helpers
Class PrintConversionEventImpl

java.lang.Object
    extended by  javax.xml.bind.helpers.ValidationEventImpl
        extended by  javax.xml.bind.helpers.PrintConversionEventImpl
All Implemented Interfaces:
PrintConversionEvent, ValidationEvent
public class PrintConversionEventImpl
extends ValidationEventImpl
implements PrintConversionEvent

Default implementation of the PrintConversionEvent interface.

JAXB providers are allowed to use whatever class that implements the ValidationEvent interface. This class is just provided for a convenience.

Since:
JAXB1.0
See Also:
PrintConversionEvent, Validator, ValidationEventHandler, ValidationEvent, ValidationEventLocator

Field Summary
Fields inherited from interface javax.xml.bind.ValidationEvent
ERROR, FATAL_ERROR, WARNING
Constructor Summary
PrintConversionEventImpl(int _severity, String _message, ValidationEventLocator _locator)
Create a new PrintConversionEventImpl.
PrintConversionEventImpl(int _severity, String _message, ValidationEventLocator _locator, Throwable _linkedException)
Create a new PrintConversionEventImpl.
Method Summary
Methods inherited from class javax.xml.bind.helpers.ValidationEventImpl
getLinkedException, getLocator, getMessage, getSeverity, setLinkedException, setLocator, setMessage, setSeverity, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface javax.xml.bind.ValidationEvent
getLinkedException, getLocator, getMessage, getSeverity

Constructor Detail

PrintConversionEventImpl

public PrintConversionEventImpl(int _severity,
                                String _message,
                                ValidationEventLocator _locator)
Create a new PrintConversionEventImpl.

Parameters:
_severity - The severity value for this event. Must be one of ValidationEvent.WARNING, ValidationEvent.ERROR, or ValidationEvent.FATAL_ERROR
_message - The text message for this event - may be null.
_locator - The locator object for this event - may be null.
Throws:
IllegalArgumentException - if an illegal severity field is supplied

PrintConversionEventImpl

public PrintConversionEventImpl(int _severity,
                                String _message,
                                ValidationEventLocator _locator,
                                Throwable _linkedException)
Create a new PrintConversionEventImpl.

Parameters:
_severity - The severity value for this event. Must be one of ValidationEvent.WARNING, ValidationEvent.ERROR, or ValidationEvent.FATAL_ERROR
_message - The text message for this event - may be null.
_locator - The locator object for this event - may be null.
_linkedException - An optional linked exception that may provide additional information about the event - may be null.
Throws:
IllegalArgumentException - if an illegal severity field is supplied
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ValidationEventImpl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.helpers
Class ValidationEventImpl

java.lang.Object
    extended by  javax.xml.bind.helpers.ValidationEventImpl
All Implemented Interfaces:
ValidationEvent
Direct Known Subclasses:
NotIdentifiableEventImpl, ParseConversionEventImpl, PrintConversionEventImpl
public class ValidationEventImpl
extends Object
implements ValidationEvent

Default implementation of the ValidationEvent interface.

JAXB providers are allowed to use whatever class that implements the ValidationEvent interface. This class is just provided for a convenience.

Since:
JAXB1.0
See Also:
Validator, ValidationEventHandler, ValidationEvent, ValidationEventLocator

Field Summary
Fields inherited from interface javax.xml.bind.ValidationEvent
ERROR, FATAL_ERROR, WARNING
Constructor Summary
ValidationEventImpl(int _severity, String _message, ValidationEventLocator _locator)
Create a new ValidationEventImpl.
ValidationEventImpl(int _severity, String _message, ValidationEventLocator _locator, Throwable _linkedException)
Create a new ValidationEventImpl.
Method Summary
Throwable | getLinkedException() Retrieve the linked exception for this warning/error.
ValidationEventLocator | getLocator() Retrieve the locator for this warning/error.
String | getMessage() Retrieve the text message for this warning/error.
int | getSeverity() Retrieve the severity code for this warning/error.
void | setLinkedException(Throwable _linkedException) Set the linked exception field of this event.
void | setLocator(ValidationEventLocator _locator) Set the locator object for this event.
void | setMessage(String _message) Set the message field of this event.
void | setSeverity(int _severity) Set the severity field of this event.
String | toString() Returns a string representation of this object in a format helpful to debugging.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ValidationEventImpl

public ValidationEventImpl(int _severity,
                           String _message,
                           ValidationEventLocator _locator)
Create a new ValidationEventImpl.

Parameters:
_severity - The severity value for this event. Must be one of ValidationEvent.WARNING, ValidationEvent.ERROR, or ValidationEvent.FATAL_ERROR
_message - The text message for this event - may be null.
_locator - The locator object for this event - may be null.
Throws:
IllegalArgumentException - if an illegal severity field is supplied

ValidationEventImpl

public ValidationEventImpl(int _severity,
                           String _message,
                           ValidationEventLocator _locator,
                           Throwable _linkedException)
Create a new ValidationEventImpl.

Parameters:
_severity - The severity value for this event. Must be one of ValidationEvent.WARNING, ValidationEvent.ERROR, or ValidationEvent.FATAL_ERROR
_message - The text message for this event - may be null.
_locator - The locator object for this event - may be null.
_linkedException - An optional linked exception that may provide additional information about the event - may be null.
Throws:
IllegalArgumentException - if an illegal severity field is supplied
Method Detail

getSeverity

public int getSeverity()
Description copied from interface: ValidationEvent
Retrieve the severity code for this warning/error.

Must be one of ValidationError.WARNING, ValidationError.ERROR, or ValidationError.FATAL_ERROR.

Specified by:
getSeverity in interface ValidationEvent
Returns:
the severity code for this warning/error

setSeverity

public void setSeverity(int _severity)
Set the severity field of this event.

Parameters:
_severity - Must be one of ValidationEvent.WARNING, ValidationEvent.ERROR, or ValidationEvent.FATAL_ERROR.
Throws:
IllegalArgumentException - if an illegal severity field is supplied

getMessage

public String getMessage()
Description copied from interface: ValidationEvent
Retrieve the text message for this warning/error.

Specified by:
getMessage in interface ValidationEvent
Returns:
the text message for this warning/error or null if one wasn't set

setMessage

public void setMessage(String _message)
Set the message field of this event.

Parameters:
_message - String message - may be null.

getLinkedException

public Throwable getLinkedException()
Description copied from interface: ValidationEvent
Retrieve the linked exception for this warning/error.

Specified by:
getLinkedException in interface ValidationEvent
Returns:
the linked exception for this warning/error or null if one wasn't set

setLinkedException

public void setLinkedException(Throwable _linkedException)
Set the linked exception field of this event.

Parameters:
_linkedException - Optional linked exception - may be null.

getLocator

public ValidationEventLocator getLocator()
Description copied from interface: ValidationEvent
Retrieve the locator for this warning/error.

Specified by:
getLocator in interface ValidationEvent
Returns:
the locator that indicates where the warning/error occurred

setLocator

public void setLocator(ValidationEventLocator _locator)
Set the locator object for this event.

Parameters:
_locator - The locator - may be null.

toString

public String toString()
Returns a string representation of this object in a format helpful to debugging.

Overrides:
toString in class Object
Returns:
a string representation of the object.
See Also:
Object.equals(Object)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ValidationEventLocatorImpl

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.helpers
Class ValidationEventLocatorImpl

java.lang.Object
    extended by  javax.xml.bind.helpers.ValidationEventLocatorImpl
All Implemented Interfaces:
ValidationEventLocator
public class ValidationEventLocatorImpl
extends Object
implements ValidationEventLocator

Default implementation of the ValidationEventLocator interface.

JAXB providers are allowed to use whatever class that implements the ValidationEventLocator interface. This class is just provided for a convenience.

Since:
JAXB1.0
See Also:
Validator, ValidationEventHandler, ValidationEvent, ValidationEventLocator

Constructor Summary
ValidationEventLocatorImpl()
Creates an object with all fields unavailable.
ValidationEventLocatorImpl(Locator loc)
Constructs an object from an org.xml.sax.Locator.
ValidationEventLocatorImpl(Node _node)
Constructs an object that points to a DOM Node.
ValidationEventLocatorImpl(Object _object)
Constructs an object that points to a JAXB content object.
ValidationEventLocatorImpl(SAXParseException e)
Constructs an object from the location information of a SAXParseException.
Method Summary
int | getColumnNumber() Return the column number if available
int | getLineNumber() Return the line number if available
Node | getNode() Return a reference to the DOM Node if available
Object | getObject() Return a reference to the object in the Java content tree if available
int | getOffset() Return the byte offset if available
URL | getURL() Return the name of the XML source as a URL if available
void | setColumnNumber(int _columnNumber) Set the columnNumber field on this event locator.
void | setLineNumber(int _lineNumber) Set the lineNumber field on this event locator.
void | setNode(Node _node) Set the Node field on this event locator.
void | setObject(Object _object) Set the Object field on this event locator.
void | setOffset(int _offset) Set the offset field on this event locator.
void | setURL(URL _url) Set the URL field on this event locator.
String | toString() Returns a string representation of this object in a format helpful to debugging.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ValidationEventLocatorImpl

public ValidationEventLocatorImpl()
Creates an object with all fields unavailable.

ValidationEventLocatorImpl

public ValidationEventLocatorImpl(Locator loc)
Constructs an object from an org.xml.sax.Locator. The object's ColumnNumber, LineNumber, and URL become available from the values returned by the locator's getColumnNumber(), getLineNumber(), and getSystemId() methods respectively. Node, Object, and Offset are not available.

Parameters:
loc - the SAX Locator object that will be used to populate this event locator.
Throws:
IllegalArgumentException - if the Locator is null

ValidationEventLocatorImpl

public ValidationEventLocatorImpl(SAXParseException e)
Constructs an object from the location information of a SAXParseException. The object's ColumnNumber, LineNumber, and URL become available from the values returned by the locator's getColumnNumber(), getLineNumber(), and getSystemId() methods respectively. Node, Object, and Offset are not available.

Parameters:
e - the SAXParseException object that will be used to populate this event locator.
Throws:
IllegalArgumentException - if the SAXParseException is null

ValidationEventLocatorImpl

public ValidationEventLocatorImpl(Node _node)
Constructs an object that points to a DOM Node. The object's Node becomes available. ColumnNumber, LineNumber, Object, Offset, and URL are not available.

Parameters:
_node - the DOM Node object that will be used to populate this event locator.
Throws:
IllegalArgumentException - if the Node is null

ValidationEventLocatorImpl

public ValidationEventLocatorImpl(Object _object)
Constructs an object that points to a JAXB content object. The object's Object becomes available. ColumnNumber, LineNumber, Node, Offset, and URL are not available.

Parameters:
_object - the Object that will be used to populate this event locator.
Throws:
IllegalArgumentException - if the Object is null
Method Detail

getURL

public URL getURL()
Description copied from interface: ValidationEventLocator
Return the name of the XML source as a URL if available

Specified by:
getURL in interface ValidationEventLocator
Returns:
the name of the XML source as a URL or null if unavailable
See Also:
ValidationEventLocator.getURL()

setURL

public void setURL(URL _url)
Set the URL field on this event locator. Null values are allowed.

Parameters:
_url - the url

getOffset

public int getOffset()
Description copied from interface: ValidationEventLocator
Return the byte offset if available

Specified by:
getOffset in interface ValidationEventLocator
Returns:
the byte offset into the input source or -1 if unavailable
See Also:
ValidationEventLocator.getOffset()

setOffset

public void setOffset(int _offset)
Set the offset field on this event locator.

Parameters:
_offset - the offset

getLineNumber

public int getLineNumber()
Description copied from interface: ValidationEventLocator
Return the line number if available

Specified by:
getLineNumber in interface ValidationEventLocator
Returns:
the line number or -1 if unavailable
See Also:
ValidationEventLocator.getLineNumber()

setLineNumber

public void setLineNumber(int _lineNumber)
Set the lineNumber field on this event locator.

Parameters:
_lineNumber - the line number

getColumnNumber

public int getColumnNumber()
Description copied from interface: ValidationEventLocator
Return the column number if available

Specified by:
getColumnNumber in interface ValidationEventLocator
Returns:
the column number or -1 if unavailable
See Also:
ValidationEventLocator.getColumnNumber()

setColumnNumber

public void setColumnNumber(int _columnNumber)
Set the columnNumber field on this event locator.

Parameters:
_columnNumber - the column number

getObject

public Object getObject()
Description copied from interface: ValidationEventLocator
Return a reference to the object in the Java content tree if available

Specified by:
getObject in interface ValidationEventLocator
Returns:
a reference to the object in the Java content tree or null if unavailable
See Also:
ValidationEventLocator.getObject()

setObject

public void setObject(Object _object)
Set the Object field on this event locator. Null values are allowed.

Parameters:
_object - the java content object

getNode

public Node getNode()
Description copied from interface: ValidationEventLocator
Return a reference to the DOM Node if available

Specified by:
getNode in interface ValidationEventLocator
Returns:
a reference to the DOM Node or null if unavailable
See Also:
ValidationEventLocator.getNode()

setNode

public void setNode(Node _node)
Set the Node field on this event locator. Null values are allowed.

Parameters:
_node - the Node

toString

public String toString()
Returns a string representation of this object in a format helpful to debugging.

Overrides:
toString in class Object
Returns:
a string representation of the object.
See Also:
Object.equals(Object)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


JAXBContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Class JAXBContext

java.lang.Object
    extended by  javax.xml.bind.JAXBContext

public abstract class JAXBContext
extends Object

The JAXBContext class provides the client's entry point to the JAXB API. It provides an abstraction for managing the XML/Java binding information necessary to implement the JAXB binding framework operations: unmarshal, marshal and validate.

A client application normally obtains new instances of this class using one of these two styles for newInstance methods, although there are other specialized forms of the method available:

  • JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )
    The JAXBContext instance is initialized from a list of colon separated Java package names. Each java package contains JAXB mapped classes, schema-derived classes and/or user annotated classes. Additionally, the java package may contain JAXB package annotations that must be processed. (see JLS 3rd Edition, Section 7.4.1. Package Annotations).
  • JAXBContext.newInstance( com.acme.foo.Foo.class )
    The JAXBContext instance is intialized with class(es) passed as parameter(s) and classes that are statically reachable from these class(es). See newInstance(Class...) for details.

SPEC REQUIREMENT: the provider must supply an implementation class containing the following method signatures:
 public static JAXBContext createContext( String contextPath, ClassLoader classLoader, Map properties ) throws JAXBException
 public static JAXBContext createContext( Class[] classes, Map properties ) throws JAXBException

The following JAXB 1.0 requirement is only required for schema to java interface/implementation binding. It does not apply to JAXB annotated classes. JAXB Providers must generate a jaxb.properties file in each package containing schema derived classes. The property file must contain a property named javax.xml.bind.context.factory whose value is the name of the class that implements the createContext APIs.

The class supplied by the provider does not have to be assignable to javax.xml.bind.JAXBContext, it simply has to provide a class that implements the createContext APIs.

In addition, the provider must call the DatatypeConverter.setDatatypeConverter api prior to any client invocations of the marshal and unmarshal methods. This is necessary to configure the datatype converter that will be used during these operations.

Unmarshalling

The Unmarshaller class provides the client application the ability to convert XML data into a tree of Java content objects. The unmarshal method allows for any global XML element declared in the schema to be unmarshalled as the root of an instance document. Additionally, the unmarshal method allows for an unrecognized root element that has an xsi:type attribute's value that references a type definition declared in the schema to be unmarshalled as the root of an instance document. The JAXBContext object allows the merging of global elements and type definitions across a set of schemas (listed in the contextPath). Since each schema in the schema set can belong to distinct namespaces, the unification of schemas to an unmarshalling context should be namespace independent. This means that a client application is able to unmarshal XML documents that are instances of any of the schemas listed in the contextPath. For example:
        JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );
        Unmarshaller u = jc.createUnmarshaller();
        FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok
        BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok
        BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath

The client application may also generate Java content trees explicitly rather than unmarshalling existing XML data. For all JAXB-annotated value classes, an application can create content using constructors. For schema-derived interface/implementation classes and for the creation of elements that are not bound to a JAXB-annotated class, an application needs to have access and knowledge about each of the schema derived ObjectFactory classes that exist in each of java packages contained in the contextPath. For each schema derived java class, there is a static factory method that produces objects of that type. For example, assume that after compiling a schema, you have a package com.acme.foo that contains a schema derived interface named PurchaseOrder. In order to create objects of that type, the client application would use the factory method like this:

       com.acme.foo.PurchaseOrder po =
           com.acme.foo.ObjectFactory.createPurchaseOrder();

Once the client application has an instance of the the schema derived object, it can use the mutator methods to set content on it.

For more information on the generated ObjectFactory classes, see Section 4.2 Java Package of the specification.

SPEC REQUIREMENT: the provider must generate a class in each package that contains all of the necessary object factory methods for that package named ObjectFactory as well as the static newInstance( javaContentInterface ) method

Marshalling

The Marshaller class provides the client application the ability to convert a Java content tree back into XML data. There is no difference between marshalling a content tree that is created manually using the factory methods and marshalling a content tree that is the result an unmarshal operation. Clients can marshal a java content tree back to XML data to a java.io.OutputStream or a java.io.Writer. The marshalling process can alternatively produce SAX2 event streams to a registered ContentHandler or produce a DOM Node object. Client applications have control over the output encoding as well as whether or not to marshal the XML data as a complete document or as a fragment.

Here is a simple example that unmarshals an XML document and then marshals it back out:

        JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );

        // unmarshal from foo.xml
        Unmarshaller u = jc.createUnmarshaller();
        FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) );

        // marshal to System.out
        Marshaller m = jc.createMarshaller();
        m.marshal( fooObj, System.out );

Validation

Validation has been changed significantly since JAXB 1.0. The Validator class has been deprecated and made optional. This means that you are advised not to use this class and, in fact, it may not even be available depending on your JAXB provider. JAXB 1.0 client applications that rely on Validator will still work properly when deployed with the JAXB 1.0 runtime system. In JAXB 2.0, the Unmarshaller has included convenince methods that expose the JAXP 1.3 javax.xml.validation framework. Please refer to the Unmarshaller.setSchema(javax.xml.validation.Schema) API for more information.

JAXB Runtime Binding Framework Compatibility

The following JAXB 1.0 restriction only applies to binding schema to interfaces/implementation classes. Since this binding does not require a common runtime system, a JAXB client application must not attempt to mix runtime objects (JAXBContext, Marshaller, etc. ) from different providers. This does not mean that the client application isn't portable, it simply means that a client has to use a runtime system provided by the same provider that was used to compile the schema.

Since:
JAXB1.0
See Also:
Marshaller, Unmarshaller, S 7.4.1.1 "Package Annotations" in Java Language Specification, 3rd Edition

Field Summary
static String JAXB_CONTEXT_FACTORY
The name of the property that contains the name of the class capable of creating new JAXBContext objects.
Constructor Summary
protected JAXBContext()
Method Summary
 Binder<Node> createBinder()
Creates a Binder for W3C DOM.
<T> Binder<T>
createBinder(Class<T> domType)
Creates a Binder object that can be used for associative/in-place unmarshalling/marshalling.
 JAXBIntrospector createJAXBIntrospector()
Creates a JAXBIntrospector object that can be used to introspect JAXB objects.
abstract  Marshaller createMarshaller()
Create a Marshaller object that can be used to convert a java content tree into XML data.
abstract  Unmarshaller createUnmarshaller()
Create an Unmarshaller object that can be used to convert XML data into a java content tree.
abstract  Validator createValidator()
Deprecated. since JAXB2.0
 void generateSchema(SchemaOutputResolver outputResolver)
Generates the schema documents for this context.
static JAXBContext newInstance(Class... classesToBeBound)
Obtain a new instance of a JAXBContext class.
static JAXBContext newInstance(Class[] classesToBeBound, Map<String,?> properties)
Obtain a new instance of a JAXBContext class.
static JAXBContext newInstance(String contextPath)
Obtain a new instance of a JAXBContext class.
static JAXBContext newInstance(String contextPath, ClassLoader classLoader)
Obtain a new instance of a JAXBContext class.
static JAXBContext newInstance(String contextPath, ClassLoader classLoader, Map<String,?> properties)
Obtain a new instance of a JAXBContext class.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

JAXB_CONTEXT_FACTORY

public static final String JAXB_CONTEXT_FACTORY
The name of the property that contains the name of the class capable of creating new JAXBContext objects.

See Also:
Constant Field Values
Constructor Detail

JAXBContext

protected JAXBContext()
Method Detail

newInstance

public static JAXBContext newInstance(String contextPath)
                               throws JAXBException

Obtain a new instance of a JAXBContext class.

This is a convenience method for the newInstance method. It uses the context class loader of the current thread. To specify the use of a different class loader, either set it via the Thread.setContextClassLoader() api or use the newInstance method.

Throws:
JAXBException - if an error was encountered while creating the JAXBContext such as
  1. failure to locate either ObjectFactory.class or jaxb.index in the packages
  2. an ambiguity among global elements contained in the contextPath
  3. failure to locate a value for the context factory provider property
  4. mixing schema derived packages from different providers on the same contextPath

newInstance

public static JAXBContext newInstance(String contextPath,
                                      ClassLoader classLoader)
                               throws JAXBException

Obtain a new instance of a JAXBContext class.

The client application must supply a context path which is a list of colon (':', \u003A) separated java package names that contain schema-derived classes and/or fully qualified JAXB-annotated classes. Schema-derived code is registered with the JAXBContext by the ObjectFactory.class generated per package. Alternatively than being listed in the context path, programmer annotated JAXB mapped classes can be listed in a jaxb.index resource file, format described below. Note that a java package can contain both schema-derived classes and user annotated JAXB classes. Additionally, the java package may contain JAXB package annotations that must be processed. (see JLS 3rd Edition, Section 7.4.1. "Package Annotations").

Every package listed on the contextPath must meet one or both of the following conditions otherwise a JAXBException will be thrown:

  1. it must contain ObjectFactory.class
  2. it must contain jaxb.index

Format for jaxb.index

The file contains a newline-separated list of class names. Space and tab characters, as well as blank lines, are ignored. The comment character is '#' (0x23); on each line all characters following the first comment character are ignored. The file must be encoded in UTF-8. Classes that are reachable, as defined in newInstance(Class...), from the listed classes are also registered with JAXBContext.

Constraints on class name occuring in a jaxb.index file are:

  • Must not end with ".class".
  • Class names are resolved relative to package containing jaxb.index file. Only classes occuring directly in package containing jaxb.index file are allowed.
  • Fully qualified class names are not allowed. A qualified class name,relative to current package, is only allowed to specify a nested or inner class.

To maintain compatibility with JAXB 1.0 schema to java interface/implementation binding, enabled by schema customization , the JAXB provider will ensure that each package on the context path has a jaxb.properties file which contains a value for the javax.xml.bind.context.factory property and that all values resolve to the same provider. This requirement does not apply to JAXB annotated classes.

If there are any global XML element name collisions across the various packages listed on the contextPath, a JAXBException will be thrown.

Mixing generated interface/impl bindings from multiple JAXB Providers in the same context path may result in a JAXBException being thrown.

Parameters:
contextPath - list of java package names that contain schema derived class and/or java to schema (JAXB-annotated) mapped classes
classLoader - This class loader will be used to locate the implementation classes.
Returns:
a new instance of a JAXBContext
Throws:
JAXBException - if an error was encountered while creating the JAXBContext such as
  1. failure to locate either ObjectFactory.class or jaxb.index in the packages
  2. an ambiguity among global elements contained in the contextPath
  3. failure to locate a value for the context factory provider property
  4. mixing schema derived packages from different providers on the same contextPath

newInstance

public static JAXBContext newInstance(String contextPath,
                                      ClassLoader classLoader,
                                      Map<String,?> properties)
                               throws JAXBException

Obtain a new instance of a JAXBContext class.

This is mostly the same as newInstance(String, ClassLoader), but this version allows you to pass in provider-specific properties to configure the instanciation of JAXBContext.

The interpretation of properties is up to implementations.

Parameters:
contextPath - list of java package names that contain schema derived classes
classLoader - This class loader will be used to locate the implementation classes.
properties - provider-specific properties
Returns:
a new instance of a JAXBContext
Throws:
JAXBException - if an error was encountered while creating the JAXBContext such as
  1. failure to locate either ObjectFactory.class or jaxb.index in the packages
  2. an ambiguity among global elements contained in the contextPath
  3. failure to locate a value for the context factory provider property
  4. mixing schema derived packages from different providers on the same contextPath
Since:
JAXB2.0

newInstance

public static JAXBContext newInstance(Class... classesToBeBound)
                               throws JAXBException

Obtain a new instance of a JAXBContext class.

The client application must supply a list of classes that the new context object needs to recognize. Not only the new context will recognize all the classes specified, but it will also recognize any classes that are directly/indirectly referenced statically from the specified classes. Subclasses of referenced classes nor @XmlTransient referenced classes are not registered with JAXBContext. For example, in the following Java code, if you do newInstance(Foo.class), the newly created JAXBContext will recognize both Foo and Bar, but not Zot or FooBar:

 class Foo {
      @XmlTransient FooBar c;
      Bar b;
 }
 class Bar { int x; }
 class Zot extends Bar { int y; }
 class FooBar { }
Therefore, a typical client application only needs to specify the top-level classes, but it needs to be careful.

Note that for each java package registered with JAXBContext, when the optional package annotations exist, they must be processed. (see JLS 3rd Edition, Section 7.4.1. "Package Annotations").

Parameters:
classesToBeBound - list of java classes to be recognized by the new JAXBContext. Can be empty, in which case a JAXBContext that only knows about spec-defined classes will be returned.
Returns:
A new instance of a JAXBContext. Always non-null valid object.
Throws:
JAXBException - if an error was encountered while creating the JAXBContext, such as (but not limited to):
  1. No JAXB implementation was discovered
  2. Classes use JAXB annotations incorrectly
  3. Classes have colliding annotations (i.e., two classes with the same type name)
  4. The JAXB implementation was unable to locate provider-specific out-of-band information (such as additional files generated at the development time.)
IllegalArgumentException - if the parameter contains null (i.e., newInstance(null);)
Since:
JAXB2.0

newInstance

public static JAXBContext newInstance(Class[] classesToBeBound,
                                      Map<String,?> properties)
                               throws JAXBException

Obtain a new instance of a JAXBContext class.

An overloading of newInstance(Class...) to configure 'properties' for this instantiation of JAXBContext.

The interpretation of properties is implementation specific.

Parameters:
classesToBeBound - list of java classes to be recognized by the new JAXBContext. Can be empty, in which case a JAXBContext that only knows about spec-defined classes will be returned.
Returns:
A new instance of a JAXBContext. Always non-null valid object.
Throws:
JAXBException - if an error was encountered while creating the JAXBContext, such as (but not limited to):
  1. No JAXB implementation was discovered
  2. Classes use JAXB annotations incorrectly
  3. Classes have colliding annotations (i.e., two classes with the same type name)
  4. The JAXB implementation was unable to locate provider-specific out-of-band information (such as additional files generated at the development time.)
IllegalArgumentException - if the parameter contains null (i.e., newInstance(null);)
Since:
JAXB2.0

createUnmarshaller

public abstract Unmarshaller createUnmarshaller()
                                         throws JAXBException
Create an Unmarshaller object that can be used to convert XML data into a java content tree.

Returns:
an Unmarshaller object
Throws:
JAXBException - if an error was encountered while creating the Unmarshaller object

createMarshaller

public abstract Marshaller createMarshaller()
                                     throws JAXBException
Create a Marshaller object that can be used to convert a java content tree into XML data.

Returns:
a Marshaller object
Throws:
JAXBException - if an error was encountered while creating the Marshaller object

createValidator

public abstract Validator createValidator()
                                   throws JAXBException
Deprecated. since JAXB2.0

Validator has been made optional and deprecated in JAXB 2.0. Please refer to the javadoc for Validator for more detail.

Create a Validator object that can be used to validate a java content tree against its source schema.

Returns:
a Validator object
Throws:
JAXBException - if an error was encountered while creating the Validator object

createBinder

public <T> Binder<T> createBinder(Class<T> domType)
Creates a Binder object that can be used for associative/in-place unmarshalling/marshalling.

Parameters:
domType - select the DOM API to use by passing in its DOM Node class.
Returns:
always a new valid Binder object.
Throws:
UnsupportedOperationException - if DOM API corresponding to domType is not supported by the implementation.
Since:
JAXB2.0

createBinder

public Binder<Node> createBinder()
Creates a Binder for W3C DOM.

Returns:
always a new valid Binder object.
Since:
JAXB2.0

createJAXBIntrospector

public JAXBIntrospector createJAXBIntrospector()
Creates a JAXBIntrospector object that can be used to introspect JAXB objects.

Returns:
always return a non-null valid JAXBIntrospector object.
Throws:
UnsupportedOperationException - Calling this method on JAXB 1.0 implementations will throw an UnsupportedOperationException.
Since:
JAXB2.0

generateSchema

public void generateSchema(SchemaOutputResolver outputResolver)
                    throws IOException
Generates the schema documents for this context.

Parameters:
outputResolver - this object controls the output to which schemas will be sent.
Throws:
IOException - if SchemaOutputResolver throws an IOException.
UnsupportedOperationException - Calling this method on JAXB 1.0 implementations will throw an UnsupportedOperationException.
Since:
JAXB 2.0
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JAXBElement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Class JAXBElement<T>

java.lang.Object
    extended by  javax.xml.bind.JAXBElement<T>
All Implemented Interfaces:
Serializable
public class JAXBElement<T>
extends Object
implements Serializable

JAXB representation of an Xml Element.

This class represents information about an Xml Element from both the element declaration within a schema and the element instance value within an xml document with the following properties

  • element's xml tag name
  • value represents the element instance's atttribute(s) and content model
  • element declaration's declaredType (xs:element @type attribute)
  • scope of element declaration
  • boolean nil property. (element instance's xsi:nil attribute)

The declaredType and scope property are the JAXB class binding for the xml type definition.

Scope is either JAXBElement.GlobalScope or the Java class representing the complex type definition containing the schema element declaration.

There is a property constraint that if value is null, then nil must be true. The converse is not true to enable representing a nil element with attribute(s). If nil is true, it is possible that value is non-null so it can hold the value of the attributes associated with a nil element.

Since:
JAXB 2.0
See Also:
Serialized Form

Nested Class Summary
static class JAXBElement.GlobalScope
Designates global scope for an xml element.
Field Summary
protected Class<T> | declaredType Java datatype binding for xml element declaration's type.
protected QName | name xml element tag name
protected boolean | nil true iff the xml element instance has xsi:nil="true".
protected Class | scope Scope of xml element declaration representing this xml element instance.
protected T | value xml element value.
Constructor Summary
JAXBElement(QName name, Class<T> declaredType, Class scope, T value)
Construct an xml element instance.
JAXBElement(QName name, Class<T> declaredType, T value)
Construct an xml element instance.
Method Summary
Class<T> | getDeclaredType() Returns the Java binding of the xml element declaration's type attribute.
QName | getName() Returns the xml element tag name.
Class | getScope() Returns scope of xml element declaration.
T | getValue() Return the content model and attribute values for this element.
boolean | isGlobalScope() Returns true iff this xml element declaration is global.
boolean | isNil() Returns true iff this element instance content model is nil.
boolean | isTypeSubstituted() Returns true iff this xml element instance's value has a different type than xml element declaration's declared type.
void | setNil(boolean value) Set whether this element has nil content.
void | setValue(T t) Set the content model and attributes of this xml element.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

name

protected final QName name
xml element tag name

declaredType

protected final Class<T> declaredType
Java datatype binding for xml element declaration's type.

scope

protected final Class scope
Scope of xml element declaration representing this xml element instance. Can be one of the following values: - JAXBElement.GlobalScope for global xml element declaration. - local element declaration has a scope set to the Java class representation of complex type defintion containing xml element declaration.

value

protected T value
xml element value. Represents content model and attributes of an xml element instance.

nil

protected boolean nil
true iff the xml element instance has xsi:nil="true".

Constructor Detail

JAXBElement

public JAXBElement(QName name,
                   Class<T> declaredType,
                   Class scope,
                   T value)

Construct an xml element instance.

Parameters:
name - Java binding of xml element tag name
declaredType - Java binding of xml element declaration's type
scope - Java binding of scope of xml element declaration. Passing null is the same as passing GlobalScope.class
value - Java instance representing xml element's value.
See Also:
getScope(), isTypeSubstituted()

JAXBElement

public JAXBElement(QName name,
                   Class<T> declaredType,
                   T value)
Construct an xml element instance. This is just a convenience method for new JAXBElement(name,declaredType,GlobalScope.class,value)

Method Detail

getDeclaredType

public Class<T> getDeclaredType()
Returns the Java binding of the xml element declaration's type attribute.

getName

public QName getName()
Returns the xml element tag name.

setValue

public void setValue(T t)

Set the content model and attributes of this xml element.

When this property is set to null, isNil() must by true. Details of constraint are described at isNil().

See Also:
isTypeSubstituted()

getValue

public T getValue()

Return the content model and attribute values for this element.

See isNil() for a description of a property constraint when this value is null

getScope

public Class getScope()
Returns scope of xml element declaration.

Returns:
GlobalScope.class if this element is of global scope.
See Also:
isGlobalScope()

isNil

public boolean isNil()

Returns true iff this element instance content model is nil.

This property always returns true when getValue() is null. Note that the converse is not true, when this property is true, getValue() can contain a non-null value for attribute(s). It is valid for a nil xml element to have attribute(s).

setNil

public void setNil(boolean value)

Set whether this element has nil content.

See Also:
isNil()

isGlobalScope

public boolean isGlobalScope()
Returns true iff this xml element declaration is global.

isTypeSubstituted

public boolean isTypeSubstituted()
Returns true iff this xml element instance's value has a different type than xml element declaration's declared type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JAXBElement.GlobalScope

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Class JAXBElement.GlobalScope

java.lang.Object
    extended by  javax.xml.bind.JAXBElement.GlobalScope
Enclosing class:
JAXBElement<T>
public static final class JAXBElement.GlobalScope
extends Object

Designates global scope for an xml element.

Constructor Summary
JAXBElement.GlobalScope()
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JAXBElement.GlobalScope

public JAXBElement.GlobalScope()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JAXBException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Class JAXBException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.bind.JAXBException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
MarshalException, PropertyException, UnmarshalException, ValidationException
public class JAXBException
extends Exception

This is the root exception class for all JAXB exceptions.

Since:
JAXB1.0
See Also:
JAXBContext, Marshaller, Unmarshaller, Serialized Form

Constructor Summary
JAXBException(String message)
Construct a JAXBException with the specified detail message.
JAXBException(String message, String errorCode)
Construct a JAXBException with the specified detail message and vendor specific errorCode.
JAXBException(String message, String errorCode, Throwable exception)
Construct a JAXBException with the specified detail message, vendor specific errorCode, and linkedException.
JAXBException(String message, Throwable exception)
Construct a JAXBException with the specified detail message and linkedException.
JAXBException(Throwable exception)
Construct a JAXBException with a linkedException.
Method Summary
Throwable | getCause() Returns the cause of this throwable or null if the cause is nonexistent or unknown.
String | getErrorCode() Get the vendor specific error code
Throwable | getLinkedException() Get the linked exception
void | printStackTrace() Prints this JAXBException and its stack trace (including the stack trace of the linkedException if it is non-null) to System.err.
void | printStackTrace(PrintStream s) Prints this JAXBException and its stack trace (including the stack trace of the linkedException if it is non-null) to the PrintStream.
void | printStackTrace(PrintWriter s) Prints this JAXBException and its stack trace (including the stack trace of the linkedException if it is non-null) to the PrintWriter.
void | setLinkedException(Throwable exception) Add a linked Exception.
String | toString() Returns a short description of this JAXBException.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JAXBException

public JAXBException(String message)
Construct a JAXBException with the specified detail message. The errorCode and linkedException will default to null.

Parameters:
message - a description of the exception

JAXBException

public JAXBException(String message,
                     String errorCode)
Construct a JAXBException with the specified detail message and vendor specific errorCode. The linkedException will default to null.

Parameters:
message - a description of the exception
errorCode - a string specifying the vendor specific error code

JAXBException

public JAXBException(Throwable exception)
Construct a JAXBException with a linkedException. The detail message and vendor specific errorCode will default to null.

Parameters:
exception - the linked exception

JAXBException

public JAXBException(String message,
                     Throwable exception)
Construct a JAXBException with the specified detail message and linkedException. The errorCode will default to null.

Parameters:
message - a description of the exception
exception - the linked exception

JAXBException

public JAXBException(String message,
                     String errorCode,
                     Throwable exception)
Construct a JAXBException with the specified detail message, vendor specific errorCode, and linkedException.

Parameters:
message - a description of the exception
errorCode - a string specifying the vendor specific error code
exception - the linked exception
Method Detail

getErrorCode

public String getErrorCode()
Get the vendor specific error code

Returns:
a string specifying the vendor specific error code

getLinkedException

public Throwable getLinkedException()
Get the linked exception

Returns:
the linked Exception, null if none exists

setLinkedException

public void setLinkedException(Throwable exception)
Add a linked Exception.

Parameters:
exception - the linked Exception (A null value is permitted and indicates that the linked exception does not exist or is unknown).

toString

public String toString()
Returns a short description of this JAXBException.

Overrides:
toString in class Throwable
Returns:
a string representation of this throwable.

printStackTrace

public void printStackTrace(PrintStream s)
Prints this JAXBException and its stack trace (including the stack trace of the linkedException if it is non-null) to the PrintStream.

Overrides:
printStackTrace in class Throwable
Parameters:
s - PrintStream to use for output

printStackTrace

public void printStackTrace()
Prints this JAXBException and its stack trace (including the stack trace of the linkedException if it is non-null) to System.err.

Overrides:
printStackTrace in class Throwable

printStackTrace

public void printStackTrace(PrintWriter s)
Prints this JAXBException and its stack trace (including the stack trace of the linkedException if it is non-null) to the PrintWriter.

Overrides:
printStackTrace in class Throwable
Parameters:
s - PrintWriter to use for output

getCause

public Throwable getCause()
Description copied from class: Throwable
Returns the cause of this throwable or null if the cause is nonexistent or unknown. (The cause is the throwable that caused this throwable to get thrown.)

This implementation returns the cause that was supplied via one of the constructors requiring a Throwable, or that was set after creation with the Throwable.initCause(Throwable) method. While it is typically unnecessary to override this method, a subclass can override it to return a cause set by some other means. This is appropriate for a "legacy chained throwable" that predates the addition of chained exceptions to Throwable. Note that it is not necessary to override any of the PrintStackTrace methods, all of which invoke the getCause method to determine the cause of a throwable.

Overrides:
getCause in class Throwable
Returns:
the cause of this throwable or null if the cause is nonexistent or unknown.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JAXBIntrospector

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Class JAXBIntrospector

java.lang.Object
    extended by  javax.xml.bind.JAXBIntrospector

public abstract class JAXBIntrospector
extends Object

Provide access to JAXB xml binding data for a JAXB object.

Intially, the intent of this class is to just conceptualize how a JAXB application developer can access xml binding information, independent if binding model is java to schema or schema to java. Since accessing the XML element name related to a JAXB element is a highly requested feature, demonstrate access to this binding information. The factory method to get a JAXBIntrospector instance is JAXBContext.createJAXBIntrospector().

Since:
JAXB2.0
See Also:
JAXBContext.createJAXBIntrospector()

Constructor Summary
JAXBIntrospector()
Method Summary
abstract QName | getElementName(Object jaxbElement) Get xml element qname for jaxbElement.
static Object | getValue(Object jaxbElement) Get the element value of a JAXB element.
abstract boolean | isElement(Object object) Return true iff object represents a JAXB element.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JAXBIntrospector

public JAXBIntrospector()
Method Detail

isElement

public abstract boolean isElement(Object object)

Return true iff object represents a JAXB element.

Parameter object is a JAXB element for following cases:

  1. It is an instance of javax.xml.bind.JAXBElement.
  2. The class of object is annotated with @XmlRootElement.

See Also:
getElementName(Object)

getElementName

public abstract QName getElementName(Object jaxbElement)

Get xml element qname for jaxbElement.

Parameters:
jaxbElement - is an object that isElement(Object) returned true.
Returns:
xml element qname associated with jaxbElement; null if jaxbElement is not a JAXB Element.

getValue

public static Object getValue(Object jaxbElement)

Get the element value of a JAXB element.

Convenience method to abstract whether working with either a javax.xml.bind.JAXBElement instance or an instance of @XmlRootElement annotated Java class.

Parameters:
jaxbElement - object that #isElement(Object) returns true.
Returns:
The element value of the jaxbElement.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MarshalException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Class MarshalException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.bind.JAXBException
                extended by  javax.xml.bind.MarshalException
All Implemented Interfaces:
Serializable
public class MarshalException
extends JAXBException

This exception indicates that an error has occurred while performing a marshal operation that the provider is unable to recover from.

The ValidationEventHandler can cause this exception to be thrown during the marshal operations. See ValidationEventHandler.handleEvent(ValidationEvent).

Since:
JAXB1.0
See Also:
JAXBException, Marshaller, Serialized Form

Constructor Summary
MarshalException(String message)
Construct a MarshalException with the specified detail message.
MarshalException(String message, String errorCode)
Construct a MarshalException with the specified detail message and vendor specific errorCode.
MarshalException(String message, String errorCode, Throwable exception)
Construct a MarshalException with the specified detail message, vendor specific errorCode, and linkedException.
MarshalException(String message, Throwable exception)
Construct a MarshalException with the specified detail message and linkedException.
MarshalException(Throwable exception)
Construct a MarshalException with a linkedException.
Method Summary
Methods inherited from class javax.xml.bind.JAXBException
getCause, getErrorCode, getLinkedException, printStackTrace, printStackTrace, printStackTrace, setLinkedException, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MarshalException

public MarshalException(String message)
Construct a MarshalException with the specified detail message. The errorCode and linkedException will default to null.

Parameters:
message - a description of the exception

MarshalException

public MarshalException(String message,
                        String errorCode)
Construct a MarshalException with the specified detail message and vendor specific errorCode. The linkedException will default to null.

Parameters:
message - a description of the exception
errorCode - a string specifying the vendor specific error code

MarshalException

public MarshalException(Throwable exception)
Construct a MarshalException with a linkedException. The detail message and vendor specific errorCode will default to null.

Parameters:
exception - the linked exception

MarshalException

public MarshalException(String message,
                        Throwable exception)
Construct a MarshalException with the specified detail message and linkedException. The errorCode will default to null.

Parameters:
message - a description of the exception
exception - the linked exception

MarshalException

public MarshalException(String message,
                        String errorCode,
                        Throwable exception)
Construct a MarshalException with the specified detail message, vendor specific errorCode, and linkedException.

Parameters:
message - a description of the exception
errorCode - a string specifying the vendor specific error code
exception - the linked exception
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Marshaller

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Interface Marshaller

All Known Implementing Classes:
AbstractMarshallerImpl
public interface Marshaller

The Marshaller class is responsible for governing the process of serializing Java content trees back into XML data. It provides the basic marshalling methods:

Assume the following setup code for all following code fragments:

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();
       Object element = u.unmarshal( new File( "foo.xml" ) );
       Marshaller m = jc.createMarshaller();

Marshalling to a File:

       OutputStream os = new FileOutputStream( "nosferatu.xml" );
       m.marshal( element, os );

Marshalling to a SAX ContentHandler:

       // assume MyContentHandler instanceof ContentHandler
       m.marshal( element, new MyContentHandler() );

Marshalling to a DOM Node:

       DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
       dbf.setNamespaceAware(true);
       DocumentBuilder db = dbf.newDocumentBuilder();
       Document doc = db.newDocument();

       m.marshal( element, doc );

Marshalling to a java.io.OutputStream:

       m.marshal( element, System.out );

Marshalling to a java.io.Writer:

       m.marshal( element, new PrintWriter( System.out ) );

Marshalling to a javax.xml.transform.SAXResult:

       // assume MyContentHandler instanceof ContentHandler
       SAXResult result = new SAXResult( new MyContentHandler() );

       m.marshal( element, result );

Marshalling to a javax.xml.transform.DOMResult:

       DOMResult result = new DOMResult();

       m.marshal( element, result );

Marshalling to a javax.xml.transform.StreamResult:

       StreamResult result = new StreamResult( System.out );

       m.marshal( element, result );

Marshalling to a javax.xml.stream.XMLStreamWriter:

       XMLStreamWriter xmlStreamWriter =
           XMLOutputFactory.newInstance().createXMLStreamWriter( ... );

       m.marshal( element, xmlStreamWriter );

Marshalling to a javax.xml.stream.XMLEventWriter:

       XMLEventWriter xmlEventWriter =
           XMLOutputFactory.newInstance().createXMLEventWriter( ... );

       m.marshal( element, xmlEventWriter );

Marshalling content tree rooted by a JAXB element

The first parameter of the overloaded Marshaller.marshal(java.lang.Object, ...) methods must be a JAXB element as computed by JAXBIntrospector.isElement(java.lang.Object); otherwise, a Marshaller.marshal method must throw a MarshalException. There exist two mechanisms to enable marshalling an instance that is not a JAXB element. One method is to wrap the instance as a value of a JAXBElement, and pass the wrapper element as the first parameter to a Marshaller.marshal method. For java to schema binding, it is also possible to simply annotate the instance's class with @XmlRootElement.

Encoding

By default, the Marshaller will use UTF-8 encoding when generating XML data to a java.io.OutputStream, or a java.io.Writer. Use the setProperty API to change the output encoding used during these marshal operations. Client applications are expected to supply a valid character encoding name as defined in the W3C XML 1.0 Recommendation and supported by your Java Platform.

Validation and Well-Formedness

Client applications are not required to validate the Java content tree prior to calling any of the marshal API's. Furthermore, there is no requirement that the Java content tree be valid with respect to its original schema in order to marshal it back into XML data. Different JAXB Providers will support marshalling invalid Java content trees at varying levels, however all JAXB Providers must be able to marshal a valid content tree back to XML data. A JAXB Provider must throw a MarshalException when it is unable to complete the marshal operation due to invalid content. Some JAXB Providers will fully allow marshalling invalid content, others will fail on the first validation error.

Even when schema validation is not explictly enabled for the marshal operation, it is possible that certain types of validation events will be detected during the operation. Validation events will be reported to the registered event handler. If the client application has not registered an event handler prior to invoking one of the marshal API's, then events will be delivered to a default event handler which will terminate the marshal operation after encountering the first error or fatal error. Note that for JAXB 2.0 and later versions, DefaultValidationEventHandler is no longer used.

Supported Properties

All JAXB Providers are required to support the following set of properties. Some providers may support additional properties.

jaxb.encoding - value must be a java.lang.String
The output encoding to use when marshalling the XML data. The Marshaller will use "UTF-8" by default if this property is not specified.
jaxb.formatted.output - value must be a java.lang.Boolean
This property controls whether or not the Marshaller will format the resulting XML data with line breaks and indentation. A true value for this property indicates human readable indented xml data, while a false value indicates unformatted xml data. The Marshaller will default to false (unformatted) if this property is not specified.
jaxb.schemaLocation - value must be a java.lang.String
This property allows the client application to specify an xsi:schemaLocation attribute in the generated XML data. The format of the schemaLocation attribute value is discussed in an easy to understand, non-normative form in Section 5.6 of the W3C XML Schema Part 0: Primer and specified in Section 2.6 of the W3C XML Schema Part 1: Structures.
jaxb.noNamespaceSchemaLocation - value must be a java.lang.String
This property allows the client application to specify an xsi:noNamespaceSchemaLocation attribute in the generated XML data. The format of the schemaLocation attribute value is discussed in an easy to understand, non-normative form in Section 5.6 of the W3C XML Schema Part 0: Primer and specified in Section 2.6 of the W3C XML Schema Part 1: Structures.
jaxb.fragment - value must be a java.lang.Boolean
This property determines whether or not document level events will be generated by the Marshaller. If the property is not specified, the default is false. This property has different implications depending on which marshal api you are using - when this property is set to true:
  • marshal(Object,ContentHandler) - the Marshaller won't
             invoke ContentHandler.startDocument() and
             ContentHandler.endDocument().
  • marshal(Object,Node) - the property has no effect on this API.
  • marshal(Object,OutputStream) - the Marshaller won't generate an xml declaration.
  • marshal(Object,Writer) - the Marshaller won't generate an xml declaration.
  • marshal(Object,Result) - depends on the kind of Result object, see semantics for Node, ContentHandler, and Stream APIs
  • marshal(Object,XMLEventWriter) - the Marshaller will not generate XMLStreamConstants.START_DOCUMENT and XMLStreamConstants.END_DOCUMENT events.
  • marshal(Object,XMLStreamWriter) - the Marshaller will not generate XMLStreamConstants.START_DOCUMENT and XMLStreamConstants.END_DOCUMENT events.

Marshal Event Callbacks

"The Marshaller provides two styles of callback mechanisms that allow application specific processing during key points in the unmarshalling process. In 'class defined' event callbacks, application specific code placed in JAXB mapped classes is triggered during marshalling. 'External listeners' allow for centralized processing of marshal events in one callback method rather than by type event callbacks.

Class defined event callback methods allow any JAXB mapped class to specify its own specific callback methods by defining methods with the following method signatures:

   // Invoked by Marshaller after it has created an instance of this object.
   boolean beforeMarshal(Marshaller, Object parent);

   // Invoked by Marshaller after it has marshalled all properties of this object.
   void afterMmarshal(Marshaller, Object parent);
The class defined event callback methods should be used when the callback method requires access to non-public methods and/or fields of the class.

The external listener callback mechanism enables the registration of a Marshaller.Listener instance with a setListener(Listener). The external listener receives all callback events, allowing for more centralized processing than per class defined callback methods.

The 'class defined' and external listener event callback methods are independent of each other, both can be called for one event. The invocation ordering when both listener callback methods exist is defined in Marshaller.Listener.beforeMarshal(Object) and Marshaller.Listener.afterMarshal(Object).

An event callback method throwing an exception terminates the current marshal process.

Since:
JAXB1.0
See Also:
JAXBContext, Validator, Unmarshaller

Nested Class Summary
static class Marshaller.Listener

Register an instance of an implementation of this class with a Marshaller to externally listen for marshal events.

Field Summary
static String | JAXB_ENCODING The name of the property used to specify the output encoding in the marshalled XML data.
static String | JAXB_FORMATTED_OUTPUT The name of the property used to specify whether or not the marshalled XML data is formatted with linefeeds and indentation.
static String | JAXB_FRAGMENT The name of the property used to specify whether or not the marshaller will generate document level events (ie calling startDocument or endDocument).
static String | JAXB_NO_NAMESPACE_SCHEMA_LOCATION The name of the property used to specify the xsi:noNamespaceSchemaLocation attribute value to place in the marshalled XML output.
static String | JAXB_SCHEMA_LOCATION The name of the property used to specify the xsi:schemaLocation attribute value to place in the marshalled XML output.
Method Summary
<A extends XmlAdapter>
A
getAdapter(Class<A> type)
Gets the adapter associated with the specified type.
 AttachmentMarshaller getAttachmentMarshaller()
 ValidationEventHandler getEventHandler()
Return the current event handler or the default event handler if one hasn't been set.
 Marshaller.Listener getListener()
Return Marshaller.Listener registered with this Marshaller.
 Node getNode(Object contentTree)
Get a DOM tree view of the content tree(Optional).
 Object getProperty(String name)
Get the particular property in the underlying implementation of Marshaller.
 Schema getSchema()
Get the JAXP 1.3 Schema object being used to perform marshal-time validation.
 void marshal(Object jaxbElement, ContentHandler handler)
Marshal the content tree rooted at jaxbElement into SAX2 events.
 void marshal(Object jaxbElement, Node node)
Marshal the content tree rooted at jaxbElement into a DOM tree.
 void marshal(Object jaxbElement, OutputStream os)
Marshal the content tree rooted at jaxbElement into an output stream.
 void marshal(Object jaxbElement, Result result)
Marshal the content tree rooted at jaxbElement into the specified javax.xml.transform.Result.
 void marshal(Object jaxbElement, Writer writer)
Marshal the content tree rooted at jaxbElement into a Writer.
 void marshal(Object jaxbElement, XMLEventWriter writer)
Marshal the content tree rooted at jaxbElement into a XMLEventWriter.
 void marshal(Object jaxbElement, XMLStreamWriter writer)
Marshal the content tree rooted at jaxbElement into a XMLStreamWriter.
<A extends XmlAdapter>
void
setAdapter(Class<A> type, A adapter)
Associates a configured instance of XmlAdapter with this marshaller.
 void setAdapter(XmlAdapter adapter)
Associates a configured instance of XmlAdapter with this marshaller.
 void setAttachmentMarshaller(AttachmentMarshaller am)
Associate a context that enables binary data within an XML document to be transmitted as XML-binary optimized attachment.
 void setEventHandler(ValidationEventHandler handler)
Allow an application to register a validation event handler.
 void setListener(Marshaller.Listener listener)
Register marshal event callback Marshaller.Listener with this Marshaller.
 void setProperty(String name, Object value)
Set the particular property in the underlying implementation of Marshaller.
 void setSchema(Schema schema)
Specify the JAXP 1.3 Schema object that should be used to validate subsequent marshal operations against.

Field Detail

JAXB_ENCODING

static final String JAXB_ENCODING
The name of the property used to specify the output encoding in the marshalled XML data.

See Also:
Constant Field Values

JAXB_FORMATTED_OUTPUT

static final String JAXB_FORMATTED_OUTPUT
The name of the property used to specify whether or not the marshalled XML data is formatted with linefeeds and indentation.

See Also:
Constant Field Values

JAXB_SCHEMA_LOCATION

static final String JAXB_SCHEMA_LOCATION
The name of the property used to specify the xsi:schemaLocation attribute value to place in the marshalled XML output.

See Also:
Constant Field Values

JAXB_NO_NAMESPACE_SCHEMA_LOCATION

static final String JAXB_NO_NAMESPACE_SCHEMA_LOCATION
The name of the property used to specify the xsi:noNamespaceSchemaLocation attribute value to place in the marshalled XML output.

See Also:
Constant Field Values

JAXB_FRAGMENT

static final String JAXB_FRAGMENT
The name of the property used to specify whether or not the marshaller will generate document level events (ie calling startDocument or endDocument).

See Also:
Constant Field Values
Method Detail

marshal

void marshal(Object jaxbElement,
             Result result)
             throws JAXBException
Marshal the content tree rooted at jaxbElement into the specified javax.xml.transform.Result.

All JAXB Providers must at least support DOMResult, SAXResult, and StreamResult. It can support other derived classes of Result as well.

Parameters:
jaxbElement - The root of content tree to be marshalled.
result - XML will be sent to this Result
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal obj (or any object reachable from obj). See Marshalling a JAXB element.
IllegalArgumentException - If any of the method parameters are null

marshal

void marshal(Object jaxbElement,
             OutputStream os)
             throws JAXBException
Marshal the content tree rooted at jaxbElement into an output stream.

Parameters:
jaxbElement - The root of content tree to be marshalled.
os - XML will be added to this stream.
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal obj (or any object reachable from obj). See Marshalling a JAXB element.
IllegalArgumentException - If any of the method parameters are null

marshal

void marshal(Object jaxbElement,
             Writer writer)
             throws JAXBException
Marshal the content tree rooted at jaxbElement into a Writer.

Parameters:
jaxbElement - The root of content tree to be marshalled.
writer - XML will be sent to this writer.
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal obj (or any object reachable from obj). See Marshalling a JAXB element.
IllegalArgumentException - If any of the method parameters are null

marshal

void marshal(Object jaxbElement,
             ContentHandler handler)
             throws JAXBException
Marshal the content tree rooted at jaxbElement into SAX2 events.

Parameters:
jaxbElement - The root of content tree to be marshalled.
handler - XML will be sent to this handler as SAX2 events.
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal obj (or any object reachable from obj). See Marshalling a JAXB element.
IllegalArgumentException - If any of the method parameters are null

marshal

void marshal(Object jaxbElement,
             Node node)
             throws JAXBException
Marshal the content tree rooted at jaxbElement into a DOM tree.

Parameters:
jaxbElement - The content tree to be marshalled.
node - DOM nodes will be added as children of this node. This parameter must be a Node that accepts children (Document, DocumentFragment, or Element)
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal jaxbElement (or any object reachable from jaxbElement). See Marshalling a JAXB element.
IllegalArgumentException - If any of the method parameters are null

marshal

void marshal(Object jaxbElement,
             XMLStreamWriter writer)
             throws JAXBException
Marshal the content tree rooted at jaxbElement into a XMLStreamWriter.

Parameters:
jaxbElement - The content tree to be marshalled.
writer - XML will be sent to this writer.
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal obj (or any object reachable from obj). See Marshalling a JAXB element.
IllegalArgumentException - If any of the method parameters are null
Since:
JAXB 2.0

marshal

void marshal(Object jaxbElement,
             XMLEventWriter writer)
             throws JAXBException
Marshal the content tree rooted at jaxbElement into a XMLEventWriter.

Parameters:
jaxbElement - The content tree rooted at jaxbElement to be marshalled.
writer - XML will be sent to this writer.
Throws:
JAXBException - If any unexpected problem occurs during the marshalling.
MarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Marshaller is unable to marshal obj (or any object reachable from obj). See Marshalling a JAXB element.
IllegalArgumentException - If any of the method parameters are null
Since:
JAXB 2.0

getNode

Node getNode(Object contentTree)
             throws JAXBException
Get a DOM tree view of the content tree(Optional). If the returned DOM tree is updated, these changes are also visible in the content tree. Use marshal(Object, org.w3c.dom.Node) to force a deep copy of the content tree to a DOM representation.

Parameters:
contentTree - - JAXB Java representation of XML content
Returns:
the DOM tree view of the contentTree
Throws:
UnsupportedOperationException - If the JAXB provider implementation does not support a DOM view of the content tree
IllegalArgumentException - If any of the method parameters are null
JAXBException - If any unexpected problem occurs

setProperty

void setProperty(String name,
                 Object value)
                 throws PropertyException
Set the particular property in the underlying implementation of Marshaller. This method can only be used to set one of the standard JAXB defined properties above or a provider specific property. Attempting to set an undefined property will result in a PropertyException being thrown. See Supported Properties.

Parameters:
name - the name of the property to be set. This value can either be specified using one of the constant fields or a user supplied string.
value - the value of the property to be set
Throws:
PropertyException - when there is an error processing the given property or value
IllegalArgumentException - If the name parameter is null

getProperty

Object getProperty(String name)
                   throws PropertyException
Get the particular property in the underlying implementation of Marshaller. This method can only be used to get one of the standard JAXB defined properties above or a provider specific property. Attempting to get an undefined property will result in a PropertyException being thrown. See Supported Properties.

Parameters:
name - the name of the property to retrieve
Returns:
the value of the requested property
Throws:
PropertyException - when there is an error retrieving the given property or value property name
IllegalArgumentException - If the name parameter is null

setEventHandler

void setEventHandler(ValidationEventHandler handler)
                     throws JAXBException
Allow an application to register a validation event handler.

The validation event handler will be called by the JAXB Provider if any validation errors are encountered during calls to any of the marshal API's. If the client application does not register a validation event handler before invoking one of the marshal methods, then validation events will be handled by the default event handler which will terminate the marshal operation after the first error or fatal error is encountered.

Calling this method with a null parameter will cause the Marshaller to revert back to the default default event handler.

Parameters:
handler - the validation event handler
Throws:
JAXBException - if an error was encountered while setting the event handler

getEventHandler

ValidationEventHandler getEventHandler()
                                       throws JAXBException
Return the current event handler or the default event handler if one hasn't been set.

Returns:
the current ValidationEventHandler or the default event handler if it hasn't been set
Throws:
JAXBException - if an error was encountered while getting the current event handler

setAdapter

void setAdapter(XmlAdapter adapter)
Associates a configured instance of XmlAdapter with this marshaller.

This is a convenience method that invokes setAdapter(adapter.getClass(),adapter);.

Throws:
IllegalArgumentException - if the adapter parameter is null.
UnsupportedOperationException - if invoked agains a JAXB 1.0 implementation.
Since:
JAXB 2.0
See Also:
setAdapter(Class,XmlAdapter)

setAdapter

<A extends XmlAdapter> void setAdapter(Class<A> type,
                                       A adapter)
Associates a configured instance of XmlAdapter with this marshaller.

Every marshaller internally maintains a Map<Class,XmlAdapter>, which it uses for marshalling classes whose fields/methods are annotated with XmlJavaTypeAdapter.

This method allows applications to use a configured instance of XmlAdapter. When an instance of an adapter is not given, a marshaller will create one by invoking its default constructor.

Parameters:
type - The type of the adapter. The specified instance will be used when XmlJavaTypeAdapter.value() refers to this type.
adapter - The instance of the adapter to be used. If null, it will un-register the current adapter set for this type.
Throws:
IllegalArgumentException - if the type parameter is null.
UnsupportedOperationException - if invoked agains a JAXB 1.0 implementation.
Since:
JAXB 2.0

getAdapter

<A extends XmlAdapter> A getAdapter(Class<A> type)
Gets the adapter associated with the specified type. This is the reverse operation of the setAdapter(javax.xml.bind.annotation.adapters.XmlAdapter) method.

Throws:
IllegalArgumentException - if the type parameter is null.
UnsupportedOperationException - if invoked agains a JAXB 1.0 implementation.
Since:
JAXB 2.0

setAttachmentMarshaller

void setAttachmentMarshaller(AttachmentMarshaller am)

Associate a context that enables binary data within an XML document to be transmitted as XML-binary optimized attachment. The attachment is referenced from the XML document content model by content-id URIs(cid) references stored within the xml document.

Throws:
IllegalStateException - if attempt to concurrently call this method during a marshal operation.

getAttachmentMarshaller

AttachmentMarshaller getAttachmentMarshaller()

setSchema

void setSchema(Schema schema)
Specify the JAXP 1.3 Schema object that should be used to validate subsequent marshal operations against. Passing null into this method will disable validation.

This method allows the caller to validate the marshalled XML as it's marshalled.

Initially this property is set to null.

Parameters:
schema - Schema object to validate marshal operations against or null to disable validation
Throws:
UnsupportedOperationException - could be thrown if this method is invoked on an Marshaller created from a JAXBContext referencing JAXB 1.0 mapped classes
Since:
JAXB2.0

getSchema

Schema getSchema()
Get the JAXP 1.3 Schema object being used to perform marshal-time validation. If there is no Schema set on the marshaller, then this method will return null indicating that marshal-time validation will not be performed.

Returns:
the Schema object being used to perform marshal-time validation or null if not present.
Throws:
UnsupportedOperationException - could be thrown if this method is invoked on an Marshaller created from a JAXBContext referencing JAXB 1.0 mapped classes
Since:
JAXB2.0

setListener

void setListener(Marshaller.Listener listener)

Register marshal event callback Marshaller.Listener with this Marshaller.

There is only one Listener per Marshaller. Setting a Listener replaces the previous set Listener. One can unregister current Listener by setting listener to null.

Parameters:
listener - an instance of a class that implements Marshaller.Listener
Since:
JAXB2.0

getListener

Marshaller.Listener getListener()

Return Marshaller.Listener registered with this Marshaller.

Returns:
registered Marshaller.Listener or null if no Listener is registered with this Marshaller.
Since:
JAXB2.0
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Marshaller.Listener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Class Marshaller.Listener

java.lang.Object
    extended by  javax.xml.bind.Marshaller.Listener
Enclosing interface:
Marshaller
public abstract static class Marshaller.Listener
extends Object

Register an instance of an implementation of this class with a Marshaller to externally listen for marshal events.

This class enables pre and post processing of each marshalled object. The event callbacks are called when marshalling from an instance that maps to an xml element or complex type definition. The event callbacks are not called when marshalling from an instance of a Java datatype that represents a simple type definition.

External listener is one of two different mechanisms for defining marshal event callbacks. See Marshal Event Callbacks for an overview.

Since:
JAXB2.0
See Also:
Marshaller.setListener(Listener), Marshaller.getListener()

Constructor Summary
Marshaller.Listener()
Method Summary
void | afterMarshal(Object source) Callback method invoked after marshalling source to XML.
void | beforeMarshal(Object source) Callback method invoked before marshalling from source to XML.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Marshaller.Listener

public Marshaller.Listener()
Method Detail

beforeMarshal

public void beforeMarshal(Object source)

Callback method invoked before marshalling from source to XML.

This method is invoked just before marshalling process starts to marshal source. Note that if the class of source defines its own beforeMarshal method, the class specific callback method is invoked just before this method is invoked.

Parameters:
source - instance of JAXB mapped class prior to marshalling from it.

afterMarshal

public void afterMarshal(Object source)

Callback method invoked after marshalling source to XML.

This method is invoked after source and all its descendants have been marshalled. Note that if the class of source defines its own afterMarshal method, the class specific callback method is invoked just before this method is invoked.

Parameters:
source - instance of JAXB mapped class after marshalling it.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PropertyException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Class PropertyException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.bind.JAXBException
                extended by  javax.xml.bind.PropertyException
All Implemented Interfaces:
Serializable
public class PropertyException
extends JAXBException

This exception indicates that an error was encountered while getting or setting a property.

Since:
JAXB1.0
See Also:
JAXBContext, Validator, Unmarshaller, Serialized Form

Constructor Summary
PropertyException(String message)
Construct a PropertyException with the specified detail message.
PropertyException(String name, Object value)
Construct a PropertyException whose message field is set based on the name of the property and value.toString().
PropertyException(String message, String errorCode)
Construct a PropertyException with the specified detail message and vendor specific errorCode.
PropertyException(String message, String errorCode, Throwable exception)
Construct a PropertyException with the specified detail message, vendor specific errorCode, and linkedException.
PropertyException(String message, Throwable exception)
Construct a PropertyException with the specified detail message and linkedException.
PropertyException(Throwable exception)
Construct a PropertyException with a linkedException.
Method Summary
Methods inherited from class javax.xml.bind.JAXBException
getCause, getErrorCode, getLinkedException, printStackTrace, printStackTrace, printStackTrace, setLinkedException, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PropertyException

public PropertyException(String message)
Construct a PropertyException with the specified detail message. The errorCode and linkedException will default to null.

Parameters:
message - a description of the exception

PropertyException

public PropertyException(String message,
                         String errorCode)
Construct a PropertyException with the specified detail message and vendor specific errorCode. The linkedException will default to null.

Parameters:
message - a description of the exception
errorCode - a string specifying the vendor specific error code

PropertyException

public PropertyException(Throwable exception)
Construct a PropertyException with a linkedException. The detail message and vendor specific errorCode will default to null.

Parameters:
exception - the linked exception

PropertyException

public PropertyException(String message,
                         Throwable exception)
Construct a PropertyException with the specified detail message and linkedException. The errorCode will default to null.

Parameters:
message - a description of the exception
exception - the linked exception

PropertyException

public PropertyException(String message,
                         String errorCode,
                         Throwable exception)
Construct a PropertyException with the specified detail message, vendor specific errorCode, and linkedException.

Parameters:
message - a description of the exception
errorCode - a string specifying the vendor specific error code
exception - the linked exception

PropertyException

public PropertyException(String name,
                         Object value)
Construct a PropertyException whose message field is set based on the name of the property and value.toString().

Parameters:
name - the name of the property related to this exception
value - the value of the property related to this exception
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SchemaOutputResolver

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Class SchemaOutputResolver

java.lang.Object
    extended by  javax.xml.bind.SchemaOutputResolver

public abstract class SchemaOutputResolver
extends Object

Controls where a JAXB implementation puts the generates schema files.

An implementation of this abstract class has to be provided by the calling application to generate schemas.

This is a class, not an interface so as to allow future versions to evolve without breaking the compatibility.

Constructor Summary
SchemaOutputResolver()
Method Summary
abstract  Result createOutput(String namespaceUri, String suggestedFileName)
Decides where the schema file (of the given namespace URI) will be written, and return it as a Result object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SchemaOutputResolver

public SchemaOutputResolver()
Method Detail

createOutput

public abstract Result createOutput(String namespaceUri,
                                    String suggestedFileName)
                             throws IOException
Decides where the schema file (of the given namespace URI) will be written, and return it as a Result object.

This method is called only once for any given namespace. IOW, all the components in one namespace is always written into the same schema document.

Parameters:
namespaceUri - The namespace URI that the schema declares. Can be the empty string, but never be null.
suggestedFileName - A JAXB implementation generates an unique file name (like "schema1.xsd") for the convenience of the callee. This name can be used for the file name of the schema, or the callee can just ignore this name and come up with its own name. This is just a hint.
Returns:
a Result object that encapsulates the actual destination of the schema. If the Result object has a system ID, it must be an absolute system ID. Those system IDs are relativized by the caller and used for <xs:import> statements. If the Result object does not have a system ID, a schema for the namespace URI is generated but it won't be explicitly <xs:import>ed from other schemas. If null is returned, the schema generation for this namespace URI will be skipped.
Throws:
IOException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TypeConstraintException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Class TypeConstraintException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  javax.xml.bind.TypeConstraintException
All Implemented Interfaces:
Serializable
public class TypeConstraintException
extends RuntimeException

This exception indicates that a violation of a dynamically checked type constraint was detected.

This exception can be thrown by the generated setter methods of the schema derived Java content classes. However, since fail-fast validation is an optional feature for JAXB Providers to support, not all setter methods will throw this exception when a type constraint is violated.

If this exception is throw while invoking a fail-fast setter, the value of the property is guaranteed to remain unchanged, as if the setter were never called.

Since:
JAXB1.0
See Also:
ValidationEvent, Serialized Form

Constructor Summary
TypeConstraintException(String message)
Construct a TypeConstraintException with the specified detail message.
TypeConstraintException(String message, String errorCode)
Construct a TypeConstraintException with the specified detail message and vendor specific errorCode.
TypeConstraintException(String message, String errorCode, Throwable exception)
Construct a TypeConstraintException with the specified detail message, vendor specific errorCode, and linkedException.
TypeConstraintException(String message, Throwable exception)
Construct a TypeConstraintException with the specified detail message and linkedException.
TypeConstraintException(Throwable exception)
Construct a TypeConstraintException with a linkedException.
Method Summary
String | getErrorCode() Get the vendor specific error code
Throwable | getLinkedException() Get the linked exception
void | printStackTrace() Prints this TypeConstraintException and its stack trace (including the stack trace of the linkedException if it is non-null) to System.err.
void | printStackTrace(PrintStream s) Prints this TypeConstraintException and its stack trace (including the stack trace of the linkedException if it is non-null) to the PrintStream.
void | setLinkedException(Throwable exception) Add a linked Exception.
String | toString() Returns a short description of this TypeConstraintException.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TypeConstraintException

public TypeConstraintException(String message)
Construct a TypeConstraintException with the specified detail message. The errorCode and linkedException will default to null.

Parameters:
message - a description of the exception

TypeConstraintException

public TypeConstraintException(String message,
                               String errorCode)
Construct a TypeConstraintException with the specified detail message and vendor specific errorCode. The linkedException will default to null.

Parameters:
message - a description of the exception
errorCode - a string specifying the vendor specific error code

TypeConstraintException

public TypeConstraintException(Throwable exception)
Construct a TypeConstraintException with a linkedException. The detail message and vendor specific errorCode will default to null.

Parameters:
exception - the linked exception

TypeConstraintException

public TypeConstraintException(String message,
                               Throwable exception)
Construct a TypeConstraintException with the specified detail message and linkedException. The errorCode will default to null.

Parameters:
message - a description of the exception
exception - the linked exception

TypeConstraintException

public TypeConstraintException(String message,
                               String errorCode,
                               Throwable exception)
Construct a TypeConstraintException with the specified detail message, vendor specific errorCode, and linkedException.

Parameters:
message - a description of the exception
errorCode - a string specifying the vendor specific error code
exception - the linked exception
Method Detail

getErrorCode

public String getErrorCode()
Get the vendor specific error code

Returns:
a string specifying the vendor specific error code

getLinkedException

public Throwable getLinkedException()
Get the linked exception

Returns:
the linked Exception, null if none exists

setLinkedException

public void setLinkedException(Throwable exception)
Add a linked Exception.

Parameters:
exception - the linked Exception (A null value is permitted and indicates that the linked exception does not exist or is unknown).

toString

public String toString()
Returns a short description of this TypeConstraintException.

Overrides:
toString in class Throwable
Returns:
a string representation of this throwable.

printStackTrace

public void printStackTrace(PrintStream s)
Prints this TypeConstraintException and its stack trace (including the stack trace of the linkedException if it is non-null) to the PrintStream.

Overrides:
printStackTrace in class Throwable
Parameters:
s - PrintStream to use for output

printStackTrace

public void printStackTrace()
Prints this TypeConstraintException and its stack trace (including the stack trace of the linkedException if it is non-null) to System.err.

Overrides:
printStackTrace in class Throwable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UnmarshalException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Class UnmarshalException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.bind.JAXBException
                extended by  javax.xml.bind.UnmarshalException
All Implemented Interfaces:
Serializable
public class UnmarshalException
extends JAXBException

This exception indicates that an error has occurred while performing an unmarshal operation that prevents the JAXB Provider from completing the operation.

The ValidationEventHandler can cause this exception to be thrown during the unmarshal operations. See ValidationEventHandler.handleEvent(ValidationEvent).

Since:
JAXB1.0
See Also:
JAXBException, Unmarshaller, ValidationEventHandler, Serialized Form

Constructor Summary
UnmarshalException(String message)
Construct an UnmarshalException with the specified detail message.
UnmarshalException(String message, String errorCode)
Construct an UnmarshalException with the specified detail message and vendor specific errorCode.
UnmarshalException(String message, String errorCode, Throwable exception)
Construct an UnmarshalException with the specified detail message, vendor specific errorCode, and linkedException.
UnmarshalException(String message, Throwable exception)
Construct an UnmarshalException with the specified detail message and linkedException.
UnmarshalException(Throwable exception)
Construct an UnmarshalException with a linkedException.
Method Summary
Methods inherited from class javax.xml.bind.JAXBException
getCause, getErrorCode, getLinkedException, printStackTrace, printStackTrace, printStackTrace, setLinkedException, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UnmarshalException

public UnmarshalException(String message)
Construct an UnmarshalException with the specified detail message. The errorCode and linkedException will default to null.

Parameters:
message - a description of the exception

UnmarshalException

public UnmarshalException(String message,
                          String errorCode)
Construct an UnmarshalException with the specified detail message and vendor specific errorCode. The linkedException will default to null.

Parameters:
message - a description of the exception
errorCode - a string specifying the vendor specific error code

UnmarshalException

public UnmarshalException(Throwable exception)
Construct an UnmarshalException with a linkedException. The detail message and vendor specific errorCode will default to null.

Parameters:
exception - the linked exception

UnmarshalException

public UnmarshalException(String message,
                          Throwable exception)
Construct an UnmarshalException with the specified detail message and linkedException. The errorCode will default to null.

Parameters:
message - a description of the exception
exception - the linked exception

UnmarshalException

public UnmarshalException(String message,
                          String errorCode,
                          Throwable exception)
Construct an UnmarshalException with the specified detail message, vendor specific errorCode, and linkedException.

Parameters:
message - a description of the exception
errorCode - a string specifying the vendor specific error code
exception - the linked exception
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Unmarshaller

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Interface Unmarshaller

All Known Implementing Classes:
AbstractUnmarshallerImpl
public interface Unmarshaller

The Unmarshaller class governs the process of deserializing XML data into newly created Java content trees, optionally validating the XML data as it is unmarshalled. It provides an overloading of unmarshal methods for many different input kinds.

Unmarshalling from a File:

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();
       Object o = u.unmarshal( new File( "nosferatu.xml" ) );

Unmarshalling from an InputStream:

       InputStream is = new FileInputStream( "nosferatu.xml" );
       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();
       Object o = u.unmarshal( is );

Unmarshalling from a URL:

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();
       URL url = new URL( "http://beaker.east/nosferatu.xml" );
       Object o = u.unmarshal( url );

Unmarshalling from a StringBuffer using a javax.xml.transform.stream.StreamSource:

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();
       StringBuffer xmlStr = new StringBuffer( "<?xml version="1.0"?>..." );
       Object o = u.unmarshal( new StreamSource( new StringReader( xmlStr.toString() ) ) );

Unmarshalling from a org.w3c.dom.Node:

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();

       DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
       dbf.setNamespaceAware(true);
       DocumentBuilder db = dbf.newDocumentBuilder();
       Document doc = db.parse(new File( "nosferatu.xml"));

       Object o = u.unmarshal( doc );

Unmarshalling from a javax.xml.transform.sax.SAXSource using a client specified validating SAX2.0 parser:

       // configure a validating SAX2.0 parser (Xerces2)
       static final String JAXP_SCHEMA_LANGUAGE =
           "http://java.sun.com/xml/jaxp/properties/schemaLanguage";
       static final String JAXP_SCHEMA_LOCATION =
           "http://java.sun.com/xml/jaxp/properties/schemaSource";
       static final String W3C_XML_SCHEMA =
           "http://www.w3.org/2001/XMLSchema";

       System.setProperty( "javax.xml.parsers.SAXParserFactory",
                           "org.apache.xerces.jaxp.SAXParserFactoryImpl" );

       SAXParserFactory spf = SAXParserFactory.newInstance();
       spf.setNamespaceAware(true);
       spf.setValidating(true);
       SAXParser saxParser = spf.newSAXParser();

       try {
           saxParser.setProperty(JAXP_SCHEMA_LANGUAGE, W3C_XML_SCHEMA);
           saxParser.setProperty(JAXP_SCHEMA_LOCATION, "http://....");
       } catch (SAXNotRecognizedException x) {
           // exception handling omitted
       }

       XMLReader xmlReader = saxParser.getXMLReader();
       SAXSource source =
           new SAXSource( xmlReader, new InputSource( "http://..." ) );

       // Setup JAXB to unmarshal
       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();
       ValidationEventCollector vec = new ValidationEventCollector();
       u.setEventHandler( vec );

       // turn off the JAXB provider's default validation mechanism to
       // avoid duplicate validation
       u.setValidating( false )

       // unmarshal
       Object o = u.unmarshal( source );

       // check for events
       if( vec.hasEvents() ) {
          // iterate over events
       }

Unmarshalling from a StAX XMLStreamReader:

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();

       javax.xml.stream.XMLStreamReader xmlStreamReader =
           javax.xml.stream.XMLInputFactory().newInstance().createXMLStreamReader( ... );

       Object o = u.unmarshal( xmlStreamReader );

Unmarshalling from a StAX XMLEventReader:

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();

       javax.xml.stream.XMLEventReader xmlEventReader =
           javax.xml.stream.XMLInputFactory().newInstance().createXMLEventReader( ... );

       Object o = u.unmarshal( xmlEventReader );

Unmarshalling XML Data

Unmarshalling can deserialize XML data that represents either an entire XML document or a subtree of an XML document. Typically, it is sufficient to use the unmarshalling methods described by Unmarshal root element that is declared globally. These unmarshal methods utilize JAXBContext's mapping of global XML element declarations and type definitions to JAXB mapped classes to initiate the unmarshalling of the root element of XML data. When the JAXBContext's mappings are not sufficient to unmarshal the root element of XML data, the application can assist the unmarshalling process by using the unmarshal by declaredType methods. These methods are useful for unmarshalling XML data where the root element corresponds to a local element declaration in the schema.
An unmarshal method never returns null. If the unmarshal process is unable to unmarshal the root of XML content to a JAXB mapped object, a fatal error is reported that terminates processing by throwing JAXBException.

Unmarshal a root element that is globally declared

The unmarshal methods that do not have an declaredType parameter use JAXBContext to unmarshal the root element of an XML data. The JAXBContext instance is the one that was used to create this Unmarshaller. The JAXBContext instance maintains a mapping of globally declared XML element and type definition names to JAXB mapped classes. The unmarshal method checks if JAXBContext has a mapping from the root element's XML name and/or @xsi:type to a JAXB mapped class. If it does, it umarshalls the XML data using the appropriate JAXB mapped class. Note that when the root element name is unknown and the root element has an @xsi:type, the XML data is unmarshalled using that JAXB mapped class as the value of a JAXBElement. When the JAXBContext object does not have a mapping for the root element's name nor its @xsi:type, if it exists, then the unmarshal operation will abort immediately by throwing a UnmarshalException. This exception scenario can be worked around by using the unmarshal by declaredType methods described in the next subsection.

Unmarshal by Declared Type

The unmarshal methods with a declaredType parameter enable an application to deserialize a root element of XML data, even when there is no mapping in JAXBContext of the root element's XML name. The unmarshaller unmarshals the root element using the application provided mapping specified as the declaredType parameter. Note that even when the root element's element name is mapped by JAXBContext, the declaredType parameter overrides that mapping for deserializing the root element when using these unmarshal methods. Additionally, when the root element of XML data has an xsi:type attribute and that attribute's value references a type definition that is mapped to a JAXB mapped class by JAXBContext, that the root element's xsi:type attribute takes precedence over the unmarshal methods declaredType parameter. These methods always return a JAXBElement<declaredType> instance. The table below shows how the properties of the returned JAXBElement instance are set.

Unmarshal By Declared Type returned JAXBElement
JAXBElement Property | Value
name | xml element name
value | instanceof declaredType
declaredType | unmarshal method declaredType parameter
scope | null (actual scope is unknown)

The following is an example of unmarshal by declaredType method.

Unmarshal by declaredType from a org.w3c.dom.Node:

       Schema fragment for example
       <xs:schema>
          <xs:complexType name="FooType">...<\xs:complexType>
          <!-- global element declaration "PurchaseOrder" -->
          <xs:element name="PurchaseOrder">
              <xs:complexType>
                 <xs:sequence>
                    <!-- local element declaration "foo" -->
                    <xs:element name="foo" type="FooType"/>
                    ...
                 </xs:sequence>
              </xs:complexType>
          </xs:element>
       </xs:schema>

       JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );
       Unmarshaller u = jc.createUnmarshaller();

       DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
       dbf.setNamespaceAware(true);
       DocumentBuilder db = dbf.newDocumentBuilder();
       Document doc = db.parse(new File( "nosferatu.xml"));
       Element  fooSubtree = ...; // traverse DOM till reach xml element foo, constrained by a
                                  // local element declaration in schema.

       // FooType is the JAXB mapping of the type of local element declaration foo.
       JAXBElement<FooType> foo = u.unmarshal( fooSubtree, FooType.class);

Support for SAX2.0 Compliant Parsers

A client application has the ability to select the SAX2.0 compliant parser of their choice. If a SAX parser is not selected, then the JAXB Provider's default parser will be used. Even though the JAXB Provider's default parser is not required to be SAX2.0 compliant, all providers are required to allow a client application to specify their own SAX2.0 parser. Some providers may require the client application to specify the SAX2.0 parser at schema compile time. See unmarshal(Source) for more detail.

Validation and Well-Formedness

A client application can enable or disable JAXP 1.3 validation mechanism via the setSchema(javax.xml.validation.Schema) API. Sophisticated clients can specify their own validating SAX 2.0 compliant parser and bypass the JAXP 1.3 validation mechanism using the unmarshal(Source) API.

Since unmarshalling invalid XML content is defined in JAXB 2.0, the Unmarshaller default validation event handler was made more lenient than in JAXB 1.0. When schema-derived code generated by JAXB 1.0 binding compiler is registered with JAXBContext, the default unmarshal validation handler is DefaultValidationEventHandler and it terminates the marshal operation after encountering either a fatal error or an error. For a JAXB 2.0 client application, there is no explicitly defined default validation handler and the default event handling only terminates the marshal operation after encountering a fatal error.

Supported Properties

There currently are not any properties required to be supported by all JAXB Providers on Unmarshaller. However, some providers may support their own set of provider specific properties.

Unmarshal Event Callbacks

The Unmarshaller provides two styles of callback mechanisms that allow application specific processing during key points in the unmarshalling process. In 'class defined' event callbacks, application specific code placed in JAXB mapped classes is triggered during unmarshalling. 'External listeners' allow for centralized processing of unmarshal events in one callback method rather than by type event callbacks.

'Class defined' event callback methods allow any JAXB mapped class to specify its own specific callback methods by defining methods with the following method signature:

   // This method is called immediately after the object is created and before the unmarshalling of this
   // object begins. The callback provides an opportunity to initialize JavaBean properties prior to unmarshalling.
   void beforeUnmarshal(Unmarshaller, Object parent);

   //This method is called after all the properties (except IDREF) are unmarshalled for this object,
   //but before this object is set to the parent object.
   void afterUnmarshal(Unmarshaller, Object parent);
The class defined callback methods should be used when the callback method requires access to non-public methods and/or fields of the class.

The external listener callback mechanism enables the registration of a Unmarshaller.Listener instance with an setListener(Listener). The external listener receives all callback events, allowing for more centralized processing than per class defined callback methods. The external listener receives events when unmarshalling proces is marshalling to a JAXB element or to JAXB mapped class.

The 'class defined' and external listener event callback methods are independent of each other, both can be called for one event. The invocation ordering when both listener callback methods exist is defined in Unmarshaller.Listener.beforeUnmarshal(Object, Object) and Unmarshaller.Listener.afterUnmarshal(Object, Object).

An event callback method throwing an exception terminates the current unmarshal process.

Since:
JAXB1.0
See Also:
JAXBContext, Marshaller, Validator

Nested Class Summary
static class Unmarshaller.Listener

Register an instance of an implementation of this class with Unmarshaller to externally listen for unmarshal events.

Method Summary
<A extends XmlAdapter>
A
getAdapter(Class<A> type)
Gets the adapter associated with the specified type.
 AttachmentUnmarshaller getAttachmentUnmarshaller()
 ValidationEventHandler getEventHandler()
Return the current event handler or the default event handler if one hasn't been set.
 Unmarshaller.Listener getListener()
Return Unmarshaller.Listener registered with this Unmarshaller.
 Object getProperty(String name)
Get the particular property in the underlying implementation of Unmarshaller.
 Schema getSchema()
Get the JAXP 1.3 Schema object being used to perform unmarshal-time validation.
 UnmarshallerHandler getUnmarshallerHandler()
Get an unmarshaller handler object that can be used as a component in an XML pipeline.
 boolean isValidating()
Deprecated. since JAXB2.0, please see getSchema()
<A extends XmlAdapter>
void
setAdapter(Class<A> type, A adapter)
Associates a configured instance of XmlAdapter with this unmarshaller.
 void setAdapter(XmlAdapter adapter)
Associates a configured instance of XmlAdapter with this unmarshaller.
 void setAttachmentUnmarshaller(AttachmentUnmarshaller au)
Associate a context that resolves cid's, content-id URIs, to binary data passed as attachments.
 void setEventHandler(ValidationEventHandler handler)
Allow an application to register a ValidationEventHandler.
 void setListener(Unmarshaller.Listener listener)
Register unmarshal event callback Unmarshaller.Listener with this Unmarshaller.
 void setProperty(String name, Object value)
Set the particular property in the underlying implementation of Unmarshaller.
 void setSchema(Schema schema)
Specify the JAXP 1.3 Schema object that should be used to validate subsequent unmarshal operations against.
 void setValidating(boolean validating)
Deprecated. since JAXB2.0, please see setSchema(javax.xml.validation.Schema)
 Object unmarshal(File f)
Unmarshal XML data from the specified file and return the resulting content tree.
 Object unmarshal(InputSource source)
Unmarshal XML data from the specified SAX InputSource and return the resulting content tree.
 Object unmarshal(InputStream is)
Unmarshal XML data from the specified InputStream and return the resulting content tree.
 Object unmarshal(Node node)
Unmarshal global XML data from the specified DOM tree and return the resulting content tree.
<T> JAXBElement<T>
unmarshal(Node node, Class<T> declaredType)
Unmarshal XML data by JAXB mapped declaredType and return the resulting content tree.
 Object unmarshal(Reader reader)
Unmarshal XML data from the specified Reader and return the resulting content tree.
 Object unmarshal(Source source)
Unmarshal XML data from the specified XML Source and return the resulting content tree.
<T> JAXBElement<T>
unmarshal(Source source, Class<T> declaredType)
Unmarshal XML data from the specified XML Source by declaredType and return the resulting content tree.
 Object unmarshal(URL url)
Unmarshal XML data from the specified URL and return the resulting content tree.
 Object unmarshal(XMLEventReader reader)
Unmarshal XML data from the specified pull parser and return the resulting content tree.
<T> JAXBElement<T>
unmarshal(XMLEventReader reader, Class<T> declaredType)
Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.
 Object unmarshal(XMLStreamReader reader)
Unmarshal XML data from the specified pull parser and return the resulting content tree.
<T> JAXBElement<T>
unmarshal(XMLStreamReader reader, Class<T> declaredType)
Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.

Method Detail

unmarshal

Object unmarshal(File f)
                 throws JAXBException
Unmarshal XML data from the specified file and return the resulting content tree.

Implements Unmarshal Global Root Element.

Parameters:
f - the file to unmarshal XML data from
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the file parameter is null

unmarshal

Object unmarshal(InputStream is)
                 throws JAXBException
Unmarshal XML data from the specified InputStream and return the resulting content tree. Validation event location information may be incomplete when using this form of the unmarshal API.

Implements Unmarshal Global Root Element.

Parameters:
is - the InputStream to unmarshal XML data from
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the InputStream parameter is null

unmarshal

Object unmarshal(Reader reader)
                 throws JAXBException
Unmarshal XML data from the specified Reader and return the resulting content tree. Validation event location information may be incomplete when using this form of the unmarshal API, because a Reader does not provide the system ID.

Implements Unmarshal Global Root Element.

Parameters:
reader - the Reader to unmarshal XML data from
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the InputStream parameter is null
Since:
JAXB2.0

unmarshal

Object unmarshal(URL url)
                 throws JAXBException
Unmarshal XML data from the specified URL and return the resulting content tree.

Implements Unmarshal Global Root Element.

Parameters:
url - the url to unmarshal XML data from
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the URL parameter is null

unmarshal

Object unmarshal(InputSource source)
                 throws JAXBException
Unmarshal XML data from the specified SAX InputSource and return the resulting content tree.

Implements Unmarshal Global Root Element.

Parameters:
source - the input source to unmarshal XML data from
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the InputSource parameter is null

unmarshal

Object unmarshal(Node node)
                 throws JAXBException
Unmarshal global XML data from the specified DOM tree and return the resulting content tree.

Implements Unmarshal Global Root Element.

Parameters:
node - the document/element to unmarshal XML data from. The caller must support at least Document and Element.
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the Node parameter is null
See Also:
unmarshal(org.w3c.dom.Node, Class)

unmarshal

<T> JAXBElement<T> unmarshal(Node node,
                             Class<T> declaredType)
                         throws JAXBException
Unmarshal XML data by JAXB mapped declaredType and return the resulting content tree.

Implements Unmarshal by Declared Type

Parameters:
node - the document/element to unmarshal XML data from. The caller must support at least Document and Element.
declaredType - appropriate JAXB mapped class to hold node's XML data.
Returns:
JAXB Element representation of node
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If any parameter is null
Since:
JAXB2.0

unmarshal

Object unmarshal(Source source)
                 throws JAXBException
Unmarshal XML data from the specified XML Source and return the resulting content tree.

Implements Unmarshal Global Root Element.

SAX 2.0 Parser Pluggability

A client application can choose not to use the default parser mechanism supplied with their JAXB provider. Any SAX 2.0 compliant parser can be substituted for the JAXB provider's default mechanism. To do so, the client application must properly configure a SAXSource containing an XMLReader implemented by the SAX 2.0 parser provider. If the XMLReader has an org.xml.sax.ErrorHandler registered on it, it will be replaced by the JAXB Provider so that validation errors can be reported via the ValidationEventHandler mechanism of JAXB. If the SAXSource does not contain an XMLReader, then the JAXB provider's default parser mechanism will be used.

This parser replacement mechanism can also be used to replace the JAXB provider's unmarshal-time validation engine. The client application must properly configure their SAX 2.0 compliant parser to perform validation (as shown in the example above). Any SAXParserExceptions encountered by the parser during the unmarshal operation will be processed by the JAXB provider and converted into JAXB ValidationEvent objects which will be reported back to the client via the ValidationEventHandler registered with the Unmarshaller. Note: specifying a substitute validating SAX 2.0 parser for unmarshalling does not necessarily replace the validation engine used by the JAXB provider for performing on-demand validation.

The only way for a client application to specify an alternate parser mechanism to be used during unmarshal is via the unmarshal(SAXSource) API. All other forms of the unmarshal method (File, URL, Node, etc) will use the JAXB provider's default parser and validator mechanisms.

Parameters:
source - the XML Source to unmarshal XML data from (providers are only required to support SAXSource, DOMSource, and StreamSource)
Returns:
the newly created root object of the java content tree
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the Source parameter is null
See Also:
unmarshal(javax.xml.transform.Source, Class)

unmarshal

<T> JAXBElement<T> unmarshal(Source source,
                             Class<T> declaredType)
                         throws JAXBException
Unmarshal XML data from the specified XML Source by declaredType and return the resulting content tree.

Implements Unmarshal by Declared Type

See SAX 2.0 Parser Pluggability

Parameters:
source - the XML Source to unmarshal XML data from (providers are only required to support SAXSource, DOMSource, and StreamSource)
declaredType - appropriate JAXB mapped class to hold source's xml root element
Returns:
Java content rooted by JAXB Element
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If any parameter is null
Since:
JAXB2.0

unmarshal

Object unmarshal(XMLStreamReader reader)
                 throws JAXBException
Unmarshal XML data from the specified pull parser and return the resulting content tree.

Implements Unmarshal Global Root Element.

This method assumes that the parser is on a START_DOCUMENT or START_ELEMENT event. Unmarshalling will be done from this start event to the corresponding end event. If this method returns successfully, the reader will be pointing at the token right after the end event.

Parameters:
reader - The parser to be read.
Returns:
the newly created root object of the java content tree.
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the reader parameter is null
IllegalStateException - If reader is not pointing to a START_DOCUMENT or START_ELEMENT event.
Since:
JAXB2.0
See Also:
unmarshal(javax.xml.stream.XMLStreamReader, Class)

unmarshal

<T> JAXBElement<T> unmarshal(XMLStreamReader reader,
                             Class<T> declaredType)
                         throws JAXBException
Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.

This method implements unmarshal by declaredType.

This method assumes that the parser is on a START_DOCUMENT or START_ELEMENT event. Unmarshalling will be done from this start event to the corresponding end event. If this method returns successfully, the reader will be pointing at the token right after the end event.

Parameters:
reader - The parser to be read.
declaredType - appropriate JAXB mapped class to hold reader's START_ELEMENT XML data.
Returns:
content tree rooted by JAXB Element representation
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If any parameter is null
Since:
JAXB2.0

unmarshal

Object unmarshal(XMLEventReader reader)
                 throws JAXBException
Unmarshal XML data from the specified pull parser and return the resulting content tree.

This method is an Unmarshal Global Root method.

This method assumes that the parser is on a START_DOCUMENT or START_ELEMENT event. Unmarshalling will be done from this start event to the corresponding end event. If this method returns successfully, the reader will be pointing at the token right after the end event.

Parameters:
reader - The parser to be read.
Returns:
the newly created root object of the java content tree.
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If the reader parameter is null
IllegalStateException - If reader is not pointing to a START_DOCUMENT or START_ELEMENT event.
Since:
JAXB2.0
See Also:
unmarshal(javax.xml.stream.XMLEventReader, Class)

unmarshal

<T> JAXBElement<T> unmarshal(XMLEventReader reader,
                             Class<T> declaredType)
                         throws JAXBException
Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.

This method implements unmarshal by declaredType.

This method assumes that the parser is on a START_DOCUMENT or START_ELEMENT event. Unmarshalling will be done from this start event to the corresponding end event. If this method returns successfully, the reader will be pointing at the token right after the end event.

Parameters:
reader - The parser to be read.
declaredType - appropriate JAXB mapped class to hold reader's START_ELEMENT XML data.
Returns:
content tree rooted by JAXB Element representation
Throws:
JAXBException - If any unexpected errors occur while unmarshalling
UnmarshalException - If the ValidationEventHandler returns false from its handleEvent method or the Unmarshaller is unable to perform the XML to Java binding. See Unmarshalling XML Data
IllegalArgumentException - If any parameter is null
Since:
JAXB2.0

getUnmarshallerHandler

UnmarshallerHandler getUnmarshallerHandler()
Get an unmarshaller handler object that can be used as a component in an XML pipeline.

The JAXB Provider can return the same handler object for multiple invocations of this method. In other words, this method does not necessarily create a new instance of UnmarshallerHandler. If the application needs to use more than one UnmarshallerHandler, it should create more than one Unmarshaller.

Returns:
the unmarshaller handler object
See Also:
UnmarshallerHandler

setValidating

void setValidating(boolean validating)
                   throws JAXBException
Deprecated. since JAXB2.0, please see setSchema(javax.xml.validation.Schema)

Specifies whether or not the default validation mechanism of the Unmarshaller should validate during unmarshal operations. By default, the Unmarshaller does not validate.

This method may only be invoked before or after calling one of the unmarshal methods.

This method only controls the JAXB Provider's default unmarshal-time validation mechanism - it has no impact on clients that specify their own validating SAX 2.0 compliant parser. Clients that specify their own unmarshal-time validation mechanism may wish to turn off the JAXB Provider's default validation mechanism via this API to avoid "double validation".

This method is deprecated as of JAXB 2.0 - please use the new setSchema(javax.xml.validation.Schema) API.

Parameters:
validating - true if the Unmarshaller should validate during unmarshal, false otherwise
Throws:
JAXBException - if an error occurred while enabling or disabling validation at unmarshal time
UnsupportedOperationException - could be thrown if this method is invoked on an Unmarshaller created from a JAXBContext referencing JAXB 2.0 mapped classes

isValidating

boolean isValidating()
                     throws JAXBException
Deprecated. since JAXB2.0, please see getSchema()

Indicates whether or not the Unmarshaller is configured to validate during unmarshal operations.

This API returns the state of the JAXB Provider's default unmarshal-time validation mechanism.

This method is deprecated as of JAXB 2.0 - please use the new getSchema() API.

Returns:
true if the Unmarshaller is configured to validate during unmarshal operations, false otherwise
Throws:
JAXBException - if an error occurs while retrieving the validating flag
UnsupportedOperationException - could be thrown if this method is invoked on an Unmarshaller created from a JAXBContext referencing JAXB 2.0 mapped classes

setEventHandler

void setEventHandler(ValidationEventHandler handler)
                     throws JAXBException
Allow an application to register a ValidationEventHandler.

The ValidationEventHandler will be called by the JAXB Provider if any validation errors are encountered during calls to any of the unmarshal methods. If the client application does not register a ValidationEventHandler before invoking the unmarshal methods, then ValidationEvents will be handled by the default event handler which will terminate the unmarshal operation after the first error or fatal error is encountered.

Calling this method with a null parameter will cause the Unmarshaller to revert back to the default event handler.

Parameters:
handler - the validation event handler
Throws:
JAXBException - if an error was encountered while setting the event handler

getEventHandler

ValidationEventHandler getEventHandler()
                                       throws JAXBException
Return the current event handler or the default event handler if one hasn't been set.

Returns:
the current ValidationEventHandler or the default event handler if it hasn't been set
Throws:
JAXBException - if an error was encountered while getting the current event handler

setProperty

void setProperty(String name,
                 Object value)
                 throws PropertyException
Set the particular property in the underlying implementation of Unmarshaller. This method can only be used to set one of the standard JAXB defined properties above or a provider specific property. Attempting to set an undefined property will result in a PropertyException being thrown. See Supported Properties.

Parameters:
name - the name of the property to be set. This value can either be specified using one of the constant fields or a user supplied string.
value - the value of the property to be set
Throws:
PropertyException - when there is an error processing the given property or value
IllegalArgumentException - If the name parameter is null

getProperty

Object getProperty(String name)
                   throws PropertyException
Get the particular property in the underlying implementation of Unmarshaller. This method can only be used to get one of the standard JAXB defined properties above or a provider specific property. Attempting to get an undefined property will result in a PropertyException being thrown. See Supported Properties.

Parameters:
name - the name of the property to retrieve
Returns:
the value of the requested property
Throws:
PropertyException - when there is an error retrieving the given property or value property name
IllegalArgumentException - If the name parameter is null

setSchema

void setSchema(Schema schema)
Specify the JAXP 1.3 Schema object that should be used to validate subsequent unmarshal operations against. Passing null into this method will disable validation.

This method replaces the deprecated setValidating(boolean) API.

Initially this property is set to null.

Parameters:
schema - Schema object to validate unmarshal operations against or null to disable validation
Throws:
UnsupportedOperationException - could be thrown if this method is invoked on an Unmarshaller created from a JAXBContext referencing JAXB 1.0 mapped classes
Since:
JAXB2.0

getSchema

Schema getSchema()
Get the JAXP 1.3 Schema object being used to perform unmarshal-time validation. If there is no Schema set on the unmarshaller, then this method will return null indicating that unmarshal-time validation will not be performed.

This method provides replacement functionality for the deprecated isValidating() API as well as access to the Schema object. To determine if the Unmarshaller has validation enabled, simply test the return type for null:

boolean isValidating = u.getSchema()!=null;

Returns:
the Schema object being used to perform unmarshal-time validation or null if not present
Throws:
UnsupportedOperationException - could be thrown if this method is invoked on an Unmarshaller created from a JAXBContext referencing JAXB 1.0 mapped classes
Since:
JAXB2.0

setAdapter

void setAdapter(XmlAdapter adapter)
Associates a configured instance of XmlAdapter with this unmarshaller.

This is a convenience method that invokes setAdapter(adapter.getClass(),adapter);.

Throws:
IllegalArgumentException - if the adapter parameter is null.
UnsupportedOperationException - if invoked agains a JAXB 1.0 implementation.
Since:
JAXB2.0
See Also:
setAdapter(Class,XmlAdapter)

setAdapter

<A extends XmlAdapter> void setAdapter(Class<A> type,
                                       A adapter)
Associates a configured instance of XmlAdapter with this unmarshaller.

Every unmarshaller internally maintains a Map<Class,XmlAdapter>, which it uses for unmarshalling classes whose fields/methods are annotated with XmlJavaTypeAdapter.

This method allows applications to use a configured instance of XmlAdapter. When an instance of an adapter is not given, an unmarshaller will create one by invoking its default constructor.

Parameters:
type - The type of the adapter. The specified instance will be used when XmlJavaTypeAdapter.value() refers to this type.
adapter - The instance of the adapter to be used. If null, it will un-register the current adapter set for this type.
Throws:
IllegalArgumentException - if the type parameter is null.
UnsupportedOperationException - if invoked agains a JAXB 1.0 implementation.
Since:
JAXB2.0

getAdapter

<A extends XmlAdapter> A getAdapter(Class<A> type)
Gets the adapter associated with the specified type. This is the reverse operation of the setAdapter(javax.xml.bind.annotation.adapters.XmlAdapter) method.

Throws:
IllegalArgumentException - if the type parameter is null.
UnsupportedOperationException - if invoked agains a JAXB 1.0 implementation.
Since:
JAXB2.0

setAttachmentUnmarshaller

void setAttachmentUnmarshaller(AttachmentUnmarshaller au)

Associate a context that resolves cid's, content-id URIs, to binary data passed as attachments.

Unmarshal time validation, enabled via setSchema(Schema), must be supported even when unmarshaller is performing XOP processing.

Throws:
IllegalStateException - if attempt to concurrently call this method during a unmarshal operation.

getAttachmentUnmarshaller

AttachmentUnmarshaller getAttachmentUnmarshaller()

setListener

void setListener(Unmarshaller.Listener listener)

Register unmarshal event callback Unmarshaller.Listener with this Unmarshaller.

There is only one Listener per Unmarshaller. Setting a Listener replaces the previous set Listener. One can unregister current Listener by setting listener to null.

Parameters:
listener - provides unmarshal event callbacks for this Unmarshaller
Since:
JAXB2.0

getListener

Unmarshaller.Listener getListener()

Return Unmarshaller.Listener registered with this Unmarshaller.

Returns:
registered Unmarshaller.Listener or null if no Listener is registered with this Unmarshaller.
Since:
JAXB2.0
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Unmarshaller.Listener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Class Unmarshaller.Listener

java.lang.Object
    extended by  javax.xml.bind.Unmarshaller.Listener
Enclosing interface:
Unmarshaller
public abstract static class Unmarshaller.Listener
extends Object

Register an instance of an implementation of this class with Unmarshaller to externally listen for unmarshal events.

This class enables pre and post processing of an instance of a JAXB mapped class as XML data is unmarshalled into it. The event callbacks are called when unmarshalling XML content into a JAXBElement instance or a JAXB mapped class that represents a complex type definition. The event callbacks are not called when unmarshalling to an instance of a Java datatype that represents a simple type definition.

External listener is one of two different mechanisms for defining unmarshal event callbacks. See Unmarshal Event Callbacks for an overview.

(@link #setListener(Listener)} (@link #getListener()}

Since:
JAXB2.0

Constructor Summary
Unmarshaller.Listener()
Method Summary
void | afterUnmarshal(Object target, Object parent) Callback method invoked after unmarshalling XML data into target.
void | beforeUnmarshal(Object target, Object parent) Callback method invoked before unmarshalling into target.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Unmarshaller.Listener

public Unmarshaller.Listener()
Method Detail

beforeUnmarshal

public void beforeUnmarshal(Object target,
                            Object parent)

Callback method invoked before unmarshalling into target.

This method is invoked immediately after target was created and before the unmarshalling of this object begins. Note that if the class of target defines its own beforeUnmarshal method, the class specific callback method is invoked before this method is invoked.

Parameters:
target - non-null instance of JAXB mapped class prior to unmarshalling into it.
parent - instance of JAXB mapped class that will eventually reference target. null when target is root element.

afterUnmarshal

public void afterUnmarshal(Object target,
                           Object parent)

Callback method invoked after unmarshalling XML data into target.

This method is invoked after all the properties (except IDREF) are unmarshalled into target, but before target is set into its parent object. Note that if the class of target defines its own afterUnmarshal method, the class specific callback method is invoked before this method is invoked.

Parameters:
target - non-null instance of JAXB mapped class prior to unmarshalling into it.
parent - instance of JAXB mapped class that will reference target. null when target is root element.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UnmarshallerHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Interface UnmarshallerHandler

All Superinterfaces:
ContentHandler
public interface UnmarshallerHandler
extends ContentHandler

Unmarshaller implemented as SAX ContentHandler.

Applications can use this interface to use their JAXB provider as a component in an XML pipeline. For example:

       JAXBContext context = JAXBContext.newInstance( "org.acme.foo" );

       Unmarshaller unmarshaller = context.createUnmarshaller();

       UnmarshallerHandler unmarshallerHandler = unmarshaller.getUnmarshallerHandler();

       SAXParserFactory spf = SAXParserFactory.newInstance();
       spf.setNamespaceAware( true );

       XMLReader xmlReader = spf.newSAXParser().getXMLReader();
       xmlReader.setContentHandler( unmarshallerHandler );
       xmlReader.parse(new InputSource( new FileInputStream( XML_FILE ) ) );

       MyObject myObject= (MyObject)unmarshallerHandler.getResult();

This interface is reusable: even if the user fails to unmarshal an object, s/he can still start a new round of unmarshalling.

Since:
JAXB1.0
See Also:
Unmarshaller.getUnmarshallerHandler()

Method Summary
 Object getResult()
Obtains the unmarshalled result.
Methods inherited from interface org.xml.sax.ContentHandler
characters, endDocument, endElement, endPrefixMapping, ignorableWhitespace, processingInstruction, setDocumentLocator, skippedEntity, startDocument, startElement, startPrefixMapping

Method Detail

getResult

Object getResult()
                 throws JAXBException,
                        IllegalStateException
Obtains the unmarshalled result. This method can be called only after this handler receives the endDocument SAX event.

Returns:
always return a non-null valid object which was unmarshalled.
Throws:
IllegalStateException - if this method is called before this handler receives the endDocument event.
JAXBException - if there is any unmarshalling error. Note that the implementation is allowed to throw SAXException during the parsing when it finds an error.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


util

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.bind.util

Useful client utility classes.

See:
Description

Class Summary
JAXBResult | JAXP Result implementation that unmarshals a JAXB object.
JAXBSource | JAXP Source implementation that marshals a JAXB-generated object.
ValidationEventCollector | ValidationEventHandler implementation that collects all events.

Package javax.xml.bind.util Description

Useful client utility classes.

Package Specification

  • JAXB Specification

Related Documentation

For overviews, tutorials, examples, guides, and tool documentation, please see:
  • The JAXB Website

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.bind.util Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.bind.util

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.transform.sax.SAXResult (implements javax.xml.transform.Result)
      • javax.xml.bind.util.JAXBResult
    • javax.xml.transform.sax.SAXSource (implements javax.xml.transform.Source)
      • javax.xml.bind.util.JAXBSource
    • javax.xml.bind.util.ValidationEventCollector (implements javax.xml.bind.ValidationEventHandler)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.bind.util

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.bind.util

No usage of javax.xml.bind.util

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.util.JAXBResult

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.util.JAXBResult

No usage of javax.xml.bind.util.JAXBResult

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.util.JAXBSource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.util.JAXBSource

No usage of javax.xml.bind.util.JAXBSource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.bind.util.ValidationEventCollector

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.bind.util.ValidationEventCollector

No usage of javax.xml.bind.util.ValidationEventCollector

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


JAXBResult

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.util
Class JAXBResult

java.lang.Object
    extended by  javax.xml.transform.sax.SAXResult
        extended by  javax.xml.bind.util.JAXBResult
All Implemented Interfaces:
Result
public class JAXBResult
extends SAXResult

JAXP Result implementation that unmarshals a JAXB object.

This utility class is useful to combine JAXB with other Java/XML technologies.

The following example shows how to use JAXB to unmarshal a document resulting from an XSLT transformation.

       JAXBResult result = new JAXBResult(
         JAXBContext.newInstance("org.acme.foo") );

       // set up XSLT transformation
       TransformerFactory tf = TransformerFactory.newInstance();
       Transformer t = tf.newTransformer(new StreamSource("test.xsl"));

       // run transformation
       t.transform(new StreamSource("document.xml"),result);

       // obtain the unmarshalled content tree
       Object o = result.getResult();

The fact that JAXBResult derives from SAXResult is an implementation detail. Thus in general applications are strongly discouraged from accessing methods defined on SAXResult.

In particular it shall never attempt to call the setHandler, setLexicalHandler, and setSystemId methods.

Field Summary
Fields inherited from class javax.xml.transform.sax.SAXResult
FEATURE
Fields inherited from interface javax.xml.transform.Result
PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING
Constructor Summary
JAXBResult(JAXBContext context)
Creates a new instance that uses the specified JAXBContext to unmarshal.
JAXBResult(Unmarshaller _unmarshaller)
Creates a new instance that uses the specified Unmarshaller to unmarshal an object.
Method Summary
 Object getResult()
Gets the unmarshalled object created by the transformation.
Methods inherited from class javax.xml.transform.sax.SAXResult
getHandler, getLexicalHandler, getSystemId, setHandler, setLexicalHandler, setSystemId
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JAXBResult

public JAXBResult(JAXBContext context)
           throws JAXBException
Creates a new instance that uses the specified JAXBContext to unmarshal.

Parameters:
context - The JAXBContext that will be used to create the necessary Unmarshaller. This parameter must not be null.
Throws:
JAXBException - if an error is encountered while creating the JAXBResult or if the context parameter is null.

JAXBResult

public JAXBResult(Unmarshaller _unmarshaller)
           throws JAXBException
Creates a new instance that uses the specified Unmarshaller to unmarshal an object.

This JAXBResult object will use the specified Unmarshaller instance. It is the caller's responsibility not to use the same Unmarshaller for other purposes while it is being used by this object.

The primary purpose of this method is to allow the client to configure Unmarshaller. Unless you know what you are doing, it's easier and safer to pass a JAXBContext.

Parameters:
_unmarshaller - the unmarshaller. This parameter must not be null.
Throws:
JAXBException - if an error is encountered while creating the JAXBResult or the Unmarshaller parameter is null.
Method Detail

getResult

public Object getResult()
                 throws JAXBException
Gets the unmarshalled object created by the transformation.

Returns:
Always return a non-null object.
Throws:
IllegalStateException - if this method is called before an object is unmarshalled.
JAXBException - if there is any unmarshalling error. Note that the implementation is allowed to throw SAXException during the parsing when it finds an error.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


JAXBSource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.util
Class JAXBSource

java.lang.Object
    extended by  javax.xml.transform.sax.SAXSource
        extended by  javax.xml.bind.util.JAXBSource
All Implemented Interfaces:
Source
public class JAXBSource
extends SAXSource

JAXP Source implementation that marshals a JAXB-generated object.

This utility class is useful to combine JAXB with other Java/XML technologies.

The following example shows how to use JAXB to marshal a document for transformation by XSLT.

       MyObject o = // get JAXB content tree

       // jaxbContext is a JAXBContext object from which 'o' is created.
       JAXBSource source = new JAXBSource( jaxbContext, o );

       // set up XSLT transformation
       TransformerFactory tf = TransformerFactory.newInstance();
       Transformer t = tf.newTransformer(new StreamSource("test.xsl"));

       // run transformation
       t.transform(source,new StreamResult(System.out));

The fact that JAXBSource derives from SAXSource is an implementation detail. Thus in general applications are strongly discouraged from accessing methods defined on SAXSource. In particular, the setXMLReader and setInputSource methods shall never be called. The XMLReader object obtained by the getXMLReader method shall be used only for parsing the InputSource object returned by the getInputSource method.

Similarly the InputSource object obtained by the getInputSource method shall be used only for being parsed by the XMLReader object returned by the getXMLReader.

Field Summary
Fields inherited from class javax.xml.transform.sax.SAXSource
FEATURE
Constructor Summary
JAXBSource(JAXBContext context, Object contentObject)
Creates a new Source for the given content object.
JAXBSource(Marshaller marshaller, Object contentObject)
Creates a new Source for the given content object.
Method Summary
Methods inherited from class javax.xml.transform.sax.SAXSource
getInputSource, getSystemId, getXMLReader, setInputSource, setSystemId, setXMLReader, sourceToInputSource
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JAXBSource

public JAXBSource(JAXBContext context,
                  Object contentObject)
           throws JAXBException
Creates a new Source for the given content object.

Parameters:
context - JAXBContext that was used to create contentObject. This context is used to create a new instance of marshaller and must not be null.
contentObject - An instance of a JAXB-generated class, which will be used as a Source (by marshalling it into XML). It must not be null.
Throws:
JAXBException - if an error is encountered while creating the JAXBSource or if either of the parameters are null.

JAXBSource

public JAXBSource(Marshaller marshaller,
                  Object contentObject)
           throws JAXBException
Creates a new Source for the given content object.

Parameters:
marshaller - A marshaller instance that will be used to marshal contentObject into XML. This must be created from a JAXBContext that was used to build contentObject and must not be null.
contentObject - An instance of a JAXB-generated class, which will be used as a Source (by marshalling it into XML). It must not be null.
Throws:
JAXBException - if an error is encountered while creating the JAXBSource or if either of the parameters are null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ValidationEventCollector

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind.util
Class ValidationEventCollector

java.lang.Object
    extended by  javax.xml.bind.util.ValidationEventCollector
All Implemented Interfaces:
ValidationEventHandler
public class ValidationEventCollector
extends Object
implements ValidationEventHandler

ValidationEventHandler implementation that collects all events.

To use this class, create a new instance and pass it to the setEventHandler method of the Validator, Unmarshaller, Marshaller class. After the call to validate or unmarshal completes, call the getEvents method to retrieve all the reported errors and warnings.

Since:
JAXB1.0
See Also:
Validator, ValidationEventHandler, ValidationEvent, ValidationEventLocator

Constructor Summary
ValidationEventCollector()
Method Summary
ValidationEvent[] | getEvents() Return an array of ValidationEvent objects containing a copy of each of the collected errors and warnings.
boolean | handleEvent(ValidationEvent event) Receive notification of a validation warning or error.
boolean | hasEvents() Returns true if this event collector contains at least one ValidationEvent.
void | reset() Clear all collected errors and warnings.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ValidationEventCollector

public ValidationEventCollector()
Method Detail

getEvents

public ValidationEvent[] getEvents()
Return an array of ValidationEvent objects containing a copy of each of the collected errors and warnings.

Returns:
a copy of all the collected errors and warnings or an empty array if there weren't any

reset

public void reset()
Clear all collected errors and warnings.

hasEvents

public boolean hasEvents()
Returns true if this event collector contains at least one ValidationEvent.

Returns:
true if this event collector contains at least one ValidationEvent, false otherwise

handleEvent

public boolean handleEvent(ValidationEvent event)
Description copied from interface: ValidationEventHandler
Receive notification of a validation warning or error. The ValidationEvent will have a ValidationEventLocator embedded in it that indicates where the error or warning occurred.

If an unchecked runtime exception is thrown from this method, the JAXB provider will treat it as if the method returned false and interrupt the current unmarshal, validate, or marshal operation.

Specified by:
handleEvent in interface ValidationEventHandler
Parameters:
event - the encapsulated validation event information. It is a provider error if this parameter is null.
Returns:
true if the JAXB Provider should attempt to continue the current unmarshal, validate, or marshal operation after handling this warning/error, false if the provider should terminate the current operation with the appropriate UnmarshalException, ValidationException, or MarshalException.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


ValidationEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Interface ValidationEvent

All Known Subinterfaces:
NotIdentifiableEvent, ParseConversionEvent, PrintConversionEvent
All Known Implementing Classes:
NotIdentifiableEventImpl, ParseConversionEventImpl, PrintConversionEventImpl, ValidationEventImpl
public interface ValidationEvent

This event indicates that a problem was encountered while validating the incoming XML data during an unmarshal operation, while performing on-demand validation of the Java content tree, or while marshalling the Java content tree back to XML data.

Since:
JAXB1.0
See Also:
Validator, ValidationEventHandler

Field Summary
static int | ERROR Conditions that correspond to the definition of "error" in section 1.2 of the W3C XML 1.0 Recommendation
static int | FATAL_ERROR Conditions that correspond to the definition of "fatal error" in section 1.2 of the W3C XML 1.0 Recommendation
static int | WARNING Conditions that are not errors or fatal errors as defined by the XML 1.0 recommendation
Method Summary
Throwable | getLinkedException() Retrieve the linked exception for this warning/error.
ValidationEventLocator | getLocator() Retrieve the locator for this warning/error.
String | getMessage() Retrieve the text message for this warning/error.
int | getSeverity() Retrieve the severity code for this warning/error.

Field Detail

WARNING

static final int WARNING
Conditions that are not errors or fatal errors as defined by the XML 1.0 recommendation

See Also:
Constant Field Values

ERROR

static final int ERROR
Conditions that correspond to the definition of "error" in section 1.2 of the W3C XML 1.0 Recommendation

See Also:
Constant Field Values

FATAL_ERROR

static final int FATAL_ERROR
Conditions that correspond to the definition of "fatal error" in section 1.2 of the W3C XML 1.0 Recommendation

See Also:
Constant Field Values
Method Detail

getSeverity

int getSeverity()
Retrieve the severity code for this warning/error.

Must be one of ValidationError.WARNING, ValidationError.ERROR, or ValidationError.FATAL_ERROR.

Returns:
the severity code for this warning/error

getMessage

String getMessage()
Retrieve the text message for this warning/error.

Returns:
the text message for this warning/error or null if one wasn't set

getLinkedException

Throwable getLinkedException()
Retrieve the linked exception for this warning/error.

Returns:
the linked exception for this warning/error or null if one wasn't set

getLocator

ValidationEventLocator getLocator()
Retrieve the locator for this warning/error.

Returns:
the locator that indicates where the warning/error occurred
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ValidationEventHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Interface ValidationEventHandler

All Known Implementing Classes:
DefaultValidationEventHandler, ValidationEventCollector
public interface ValidationEventHandler

A basic event handler interface for validation errors.

If an application needs to implement customized event handling, it must implement this interface and then register it with either the Unmarshaller, the Validator, or the Marshaller. The JAXB Provider will then report validation errors and warnings encountered during the unmarshal, marshal, and validate operations to these event handlers.

If the handleEvent method throws an unchecked runtime exception, the JAXB Provider must treat that as if the method returned false, effectively terminating whatever operation was in progress at the time (unmarshal, validate, or marshal).

Modifying the Java content tree within your event handler is undefined by the specification and may result in unexpected behaviour.

Failing to return false from the handleEvent method after encountering a fatal error is undefined by the specification and may result in unexpected behavior.

Default Event Handler

See: Validator javadocs

Since:
JAXB1.0
See Also:
Unmarshaller, Validator, Marshaller, ValidationEvent, ValidationEventCollector

Method Summary
 boolean handleEvent(ValidationEvent event)
Receive notification of a validation warning or error.

Method Detail

handleEvent

boolean handleEvent(ValidationEvent event)
Receive notification of a validation warning or error. The ValidationEvent will have a ValidationEventLocator embedded in it that indicates where the error or warning occurred.

If an unchecked runtime exception is thrown from this method, the JAXB provider will treat it as if the method returned false and interrupt the current unmarshal, validate, or marshal operation.

Parameters:
event - the encapsulated validation event information. It is a provider error if this parameter is null.
Returns:
true if the JAXB Provider should attempt to continue the current unmarshal, validate, or marshal operation after handling this warning/error, false if the provider should terminate the current operation with the appropriate UnmarshalException, ValidationException, or MarshalException.
Throws:
IllegalArgumentException - if the event object is null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ValidationEventLocator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Interface ValidationEventLocator

All Known Implementing Classes:
ValidationEventLocatorImpl
public interface ValidationEventLocator

Encapsulate the location of a ValidationEvent.

The ValidationEventLocator indicates where the ValidationEvent occurred. Different fields will be set depending on the type of validation that was being performed when the error or warning was detected. For example, on-demand validation would produce locators that contained references to objects in the Java content tree while unmarshal-time validation would produce locators containing information appropriate to the source of the XML data (file, url, Node, etc).

Since:
JAXB1.0
See Also:
Validator, ValidationEvent

Method Summary
int | getColumnNumber() Return the column number if available
int | getLineNumber() Return the line number if available
Node | getNode() Return a reference to the DOM Node if available
Object | getObject() Return a reference to the object in the Java content tree if available
int | getOffset() Return the byte offset if available
URL | getURL() Return the name of the XML source as a URL if available

Method Detail

getURL

URL getURL()
Return the name of the XML source as a URL if available

Returns:
the name of the XML source as a URL or null if unavailable

getOffset

int getOffset()
Return the byte offset if available

Returns:
the byte offset into the input source or -1 if unavailable

getLineNumber

int getLineNumber()
Return the line number if available

Returns:
the line number or -1 if unavailable

getColumnNumber

int getColumnNumber()
Return the column number if available

Returns:
the column number or -1 if unavailable

getObject

Object getObject()
Return a reference to the object in the Java content tree if available

Returns:
a reference to the object in the Java content tree or null if unavailable

getNode

Node getNode()
Return a reference to the DOM Node if available

Returns:
a reference to the DOM Node or null if unavailable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ValidationException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Class ValidationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.bind.JAXBException
                extended by  javax.xml.bind.ValidationException
All Implemented Interfaces:
Serializable
public class ValidationException
extends JAXBException

This exception indicates that an error has occurred while performing a validate operation.

The ValidationEventHandler can cause this exception to be thrown during the validate operations. See ValidationEventHandler.handleEvent(ValidationEvent).

Since:
JAXB1.0
See Also:
JAXBException, Validator, Serialized Form

Constructor Summary
ValidationException(String message)
Construct an ValidationException with the specified detail message.
ValidationException(String message, String errorCode)
Construct an ValidationException with the specified detail message and vendor specific errorCode.
ValidationException(String message, String errorCode, Throwable exception)
Construct an ValidationException with the specified detail message, vendor specific errorCode, and linkedException.
ValidationException(String message, Throwable exception)
Construct an ValidationException with the specified detail message and linkedException.
ValidationException(Throwable exception)
Construct an ValidationException with a linkedException.
Method Summary
Methods inherited from class javax.xml.bind.JAXBException
getCause, getErrorCode, getLinkedException, printStackTrace, printStackTrace, printStackTrace, setLinkedException, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ValidationException

public ValidationException(String message)
Construct an ValidationException with the specified detail message. The errorCode and linkedException will default to null.

Parameters:
message - a description of the exception

ValidationException

public ValidationException(String message,
                           String errorCode)
Construct an ValidationException with the specified detail message and vendor specific errorCode. The linkedException will default to null.

Parameters:
message - a description of the exception
errorCode - a string specifying the vendor specific error code

ValidationException

public ValidationException(Throwable exception)
Construct an ValidationException with a linkedException. The detail message and vendor specific errorCode will default to null.

Parameters:
exception - the linked exception

ValidationException

public ValidationException(String message,
                           Throwable exception)
Construct an ValidationException with the specified detail message and linkedException. The errorCode will default to null.

Parameters:
message - a description of the exception
exception - the linked exception

ValidationException

public ValidationException(String message,
                           String errorCode,
                           Throwable exception)
Construct an ValidationException with the specified detail message, vendor specific errorCode, and linkedException.

Parameters:
message - a description of the exception
errorCode - a string specifying the vendor specific error code
exception - the linked exception
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Validator

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.bind
Interface Validator

Deprecated. since JAXB 2.0

public interface Validator

As of JAXB 2.0, this class is deprecated and optional.

The Validator class is responsible for controlling the validation of content trees during runtime.

Three Forms of Validation

Unmarshal-Time Validation
This form of validation enables a client application to receive information about validation errors and warnings detected while unmarshalling XML data into a Java content tree and is completely orthogonal to the other types of validation. To enable or disable it, see the javadoc for Unmarshaller.setValidating. All JAXB 1.0 Providers are required to support this operation.
On-Demand Validation
This form of validation enables a client application to receive information about validation errors and warnings detected in the Java content tree. At any point, client applications can call the Validator.validate method on the Java content tree (or any sub-tree of it). All JAXB 1.0 Providers are required to support this operation.
Fail-Fast Validation
This form of validation enables a client application to receive immediate feedback about modifications to the Java content tree that violate type constraints on Java Properties as defined in the specification. JAXB Providers are not required support this type of validation. Of the JAXB Providers that do support this type of validation, some may require you to decide at schema compile time whether or not a client application will be allowed to request fail-fast validation at runtime.

The Validator class is responsible for managing On-Demand Validation. The Unmarshaller class is responsible for managing Unmarshal-Time Validation during the unmarshal operations. Although there is no formal method of enabling validation during the marshal operations, the Marshaller may detect errors, which will be reported to the ValidationEventHandler registered on it.

Using the Default EventHandler

If the client application does not set an event handler on their Validator, Unmarshaller, or Marshaller prior to calling the validate, unmarshal, or marshal methods, then a default event handler will receive notification of any errors or warnings encountered. The default event handler will cause the current operation to halt after encountering the first error or fatal error (but will attempt to continue after receiving warnings).

Handling Validation Events

There are three ways to handle events encountered during the unmarshal, validate, and marshal operations:
Use the default event handler
The default event handler will be used if you do not specify one via the setEventHandler API's on Validator, Unmarshaller, or Marshaller.
Implement and register a custom event handler
Client applications that require sophisticated event processing can implement the ValidationEventHandler interface and register it with the Unmarshaller and/or Validator.
Use the ValidationEventCollector utility
For convenience, a specialized event handler is provided that simply collects any ValidationEvent objects created during the unmarshal, validate, and marshal operations and returns them to the client application as a java.util.Collection.

Validation and Well-Formedness

Validation events are handled differently depending on how the client application is configured to process them as described in the previous section. However, there are certain cases where a JAXB Provider indicates that it is no longer able to reliably detect and report errors. In these cases, the JAXB Provider will set the severity of the ValidationEvent to FATAL_ERROR to indicate that the unmarshal, validate, or marshal operations should be terminated. The default event handler and ValidationEventCollector utility class must terminate processing after being notified of a fatal error. Client applications that supply their own ValidationEventHandler should also terminate processing after being notified of a fatal error. If not, unexpected behaviour may occur.

Supported Properties

There currently are not any properties required to be supported by all JAXB Providers on Validator. However, some providers may support their own set of provider specific properties.

Since:
JAXB1.0
See Also:
JAXBContext, Unmarshaller, ValidationEventHandler, ValidationEvent, ValidationEventCollector

Method Summary
ValidationEventHandler | getEventHandler() Deprecated. since JAXB2.0
Object | getProperty(String name) Deprecated. since JAXB2.0
void | setEventHandler(ValidationEventHandler handler) Deprecated. since JAXB2.0
void | setProperty(String name, Object value) Deprecated. since JAXB2.0
boolean | validate(Object subrootObj) Deprecated. since JAXB2.0
boolean | validateRoot(Object rootObj) Deprecated. since JAXB2.0

Method Detail

setEventHandler

void setEventHandler(ValidationEventHandler handler)
                     throws JAXBException
Deprecated. since JAXB2.0

Allow an application to register a validation event handler.

The validation event handler will be called by the JAXB Provider if any validation errors are encountered during calls to validate. If the client application does not register a validation event handler before invoking the validate method, then validation events will be handled by the default event handler which will terminate the validate operation after the first error or fatal error is encountered.

Calling this method with a null parameter will cause the Validator to revert back to the default default event handler.

Parameters:
handler - the validation event handler
Throws:
JAXBException - if an error was encountered while setting the event handler

getEventHandler

ValidationEventHandler getEventHandler()
                                       throws JAXBException
Deprecated. since JAXB2.0

Return the current event handler or the default event handler if one hasn't been set.

Returns:
the current ValidationEventHandler or the default event handler if it hasn't been set
Throws:
JAXBException - if an error was encountered while getting the current event handler

validate

boolean validate(Object subrootObj)
                 throws JAXBException
Deprecated. since JAXB2.0

Validate the Java content tree starting at subrootObj.

Client applications can use this method to validate Java content trees on-demand at runtime. This method can be used to validate any arbitrary subtree of the Java content tree. Global constraint checking will not be performed as part of this operation (i.e. ID/IDREF constraints).

Parameters:
subrootObj - the obj to begin validation at
Returns:
true if the subtree rooted at subrootObj is valid, false otherwise
Throws:
JAXBException - if any unexpected problem occurs during validation
ValidationException - If the ValidationEventHandler returns false from its handleEvent method or the Validator is unable to validate the content tree rooted at subrootObj
IllegalArgumentException - If the subrootObj parameter is null

validateRoot

boolean validateRoot(Object rootObj)
                     throws JAXBException
Deprecated. since JAXB2.0

Validate the Java content tree rooted at rootObj.

Client applications can use this method to validate Java content trees on-demand at runtime. This method is used to validate an entire Java content tree. Global constraint checking will be performed as part of this operation (i.e. ID/IDREF constraints).

Parameters:
rootObj - the root obj to begin validation at
Returns:
true if the tree rooted at rootObj is valid, false otherwise
Throws:
JAXBException - if any unexpected problem occurs during validation
ValidationException - If the ValidationEventHandler returns false from its handleEvent method or the Validator is unable to validate the content tree rooted at rootObj
IllegalArgumentException - If the rootObj parameter is null

setProperty

void setProperty(String name,
                 Object value)
                 throws PropertyException
Deprecated. since JAXB2.0

Set the particular property in the underlying implementation of Validator. This method can only be used to set one of the standard JAXB defined properties above or a provider specific property. Attempting to set an undefined property will result in a PropertyException being thrown. See Supported Properties.

Parameters:
name - the name of the property to be set. This value can either be specified using one of the constant fields or a user supplied string.
value - the value of the property to be set
Throws:
PropertyException - when there is an error processing the given property or value
IllegalArgumentException - If the name parameter is null

getProperty

Object getProperty(String name)
                   throws PropertyException
Deprecated. since JAXB2.0

Get the particular property in the underlying implementation of Validator. This method can only be used to get one of the standard JAXB defined properties above or a provider specific property. Attempting to get an undefined property will result in a PropertyException being thrown. See Supported Properties.

Parameters:
name - the name of the property to retrieve
Returns:
the value of the requested property
Throws:
PropertyException - when there is an error retrieving the given property or value property name
IllegalArgumentException - If the name parameter is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.xml.XMLConstants

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.XMLConstants

No usage of javax.xml.XMLConstants

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


crypto

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.crypto

Common classes for XML cryptography.

See:
Description

Interface Summary
AlgorithmMethod | An abstract representation of an algorithm defined in the XML Security specifications.
Data | An abstract representation of the result of dereferencing a URIReference or the input/output of subsequent Transforms.
KeySelectorResult | The result returned by the KeySelector.select method.
NodeSetData | An abstract representation of a Data type containing a node-set.
URIDereferencer | A dereferencer of URIReferences.
URIReference | Identifies a data object via a URI-Reference, as specified by RFC 2396.
XMLCryptoContext | Contains common context information for XML cryptographic operations.
XMLStructure | A representation of an XML structure from any namespace.

Class Summary
KeySelector | A selector that finds and returns a key using the data contained in a KeyInfo object.
KeySelector.Purpose | The purpose of the key that is to be selected.
OctetStreamData | A representation of a Data type containing an octet stream.

Exception Summary
KeySelectorException | Indicates an exceptional condition thrown by a KeySelector.
MarshalException | Indicates an exceptional condition that occured during the XML marshalling or unmarshalling process.
NoSuchMechanismException | This exception is thrown when a particular XML mechanism is requested but is not available in the environment.
URIReferenceException | Indicates an exceptional condition thrown while dereferencing a URIReference.

Package javax.xml.crypto Description

Common classes for XML cryptography. This package includes common classes that are used to perform XML cryptographic operations, such as generating an XML signature or encrypting XML data.

Package Specification

  • XML-Signature Syntax and Processing: W3C Recommendation
  • RFC 3275: XML-Signature Syntax and Processing

Since:
1.6

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


Data

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto
Interface Data

All Known Subinterfaces:
NodeSetData
All Known Implementing Classes:
OctetStreamData
public interface Data

An abstract representation of the result of dereferencing a URIReference or the input/output of subsequent Transforms. The primary purpose of this interface is to group and provide type safety for all Data subtypes.

Since:
1.6

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


javax.xml.crypto Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.crypto

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.crypto.KeySelector
    • javax.xml.crypto.KeySelector.Purpose
    • javax.xml.crypto.OctetStreamData (implements javax.xml.crypto.Data)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.xml.crypto.KeySelectorException
        • javax.xml.crypto.MarshalException
        • java.lang.RuntimeException
          • javax.xml.crypto.NoSuchMechanismException
        • javax.xml.crypto.URIReferenceException

Interface Hierarchy

  • javax.xml.crypto.AlgorithmMethod
  • javax.xml.crypto.Data
    • javax.xml.crypto.NodeSetData
  • javax.xml.crypto.KeySelectorResult
  • javax.xml.crypto.URIDereferencer
  • javax.xml.crypto.URIReference
  • javax.xml.crypto.XMLCryptoContext
  • javax.xml.crypto.XMLStructure
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.crypto

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.crypto

Packages that use javax.xml.crypto
javax.xml.crypto | Common classes for XML cryptography.
javax.xml.crypto.dom | DOM-specific classes for the javax.xml.crypto package.
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.dom | DOM-specific classes for the javax.xml.crypto.dsig package.
javax.xml.crypto.dsig.keyinfo | Classes for parsing and processing KeyInfo elements and structures.
javax.xml.crypto.dsig.spec | Parameter classes for XML digital signatures.

Classes in javax.xml.crypto used by javax.xml.crypto
AlgorithmMethod
An abstract representation of an algorithm defined in the XML Security specifications.
Data
An abstract representation of the result of dereferencing a URIReference or the input/output of subsequent Transforms.
KeySelector
A selector that finds and returns a key using the data contained in a KeyInfo object.
KeySelector.Purpose
The purpose of the key that is to be selected.
KeySelectorException
Indicates an exceptional condition thrown by a KeySelector.
KeySelectorResult
The result returned by the KeySelector.select method.
URIDereferencer
A dereferencer of URIReferences.
URIReference
Identifies a data object via a URI-Reference, as specified by RFC 2396.
URIReferenceException
Indicates an exceptional condition thrown while dereferencing a URIReference.
XMLCryptoContext
Contains common context information for XML cryptographic operations.

Classes in javax.xml.crypto used by javax.xml.crypto.dom
KeySelector
A selector that finds and returns a key using the data contained in a KeyInfo object.
URIDereferencer
A dereferencer of URIReferences.
URIReference
Identifies a data object via a URI-Reference, as specified by RFC 2396.
XMLCryptoContext
Contains common context information for XML cryptographic operations.
XMLStructure
A representation of an XML structure from any namespace.

Classes in javax.xml.crypto used by javax.xml.crypto.dsig
AlgorithmMethod
An abstract representation of an algorithm defined in the XML Security specifications.
Data
An abstract representation of the result of dereferencing a URIReference or the input/output of subsequent Transforms.
KeySelectorResult
The result returned by the KeySelector.select method.
MarshalException
Indicates an exceptional condition that occured during the XML marshalling or unmarshalling process.
URIDereferencer
A dereferencer of URIReferences.
URIReference
Identifies a data object via a URI-Reference, as specified by RFC 2396.
XMLCryptoContext
Contains common context information for XML cryptographic operations.
XMLStructure
A representation of an XML structure from any namespace.

Classes in javax.xml.crypto used by javax.xml.crypto.dsig.dom
KeySelector
A selector that finds and returns a key using the data contained in a KeyInfo object.
XMLCryptoContext
Contains common context information for XML cryptographic operations.

Classes in javax.xml.crypto used by javax.xml.crypto.dsig.keyinfo
Data
An abstract representation of the result of dereferencing a URIReference or the input/output of subsequent Transforms.
MarshalException
Indicates an exceptional condition that occured during the XML marshalling or unmarshalling process.
URIDereferencer
A dereferencer of URIReferences.
URIReference
Identifies a data object via a URI-Reference, as specified by RFC 2396.
URIReferenceException
Indicates an exceptional condition thrown while dereferencing a URIReference.
XMLCryptoContext
Contains common context information for XML cryptographic operations.
XMLStructure
A representation of an XML structure from any namespace.

Classes in javax.xml.crypto used by javax.xml.crypto.dsig.spec
XMLStructure
A representation of an XML structure from any namespace.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AlgorithmMethod

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto
Interface AlgorithmMethod

All Known Subinterfaces:
CanonicalizationMethod, DigestMethod, SignatureMethod, Transform
All Known Implementing Classes:
TransformService
public interface AlgorithmMethod

An abstract representation of an algorithm defined in the XML Security specifications. Subclasses represent specific types of XML security algorithms, such as a Transform.

Since:
1.6

Method Summary
String | getAlgorithm() Returns the algorithm URI of this AlgorithmMethod.
AlgorithmParameterSpec | getParameterSpec() Returns the algorithm parameters of this AlgorithmMethod.

Method Detail

getAlgorithm

String getAlgorithm()
Returns the algorithm URI of this AlgorithmMethod.

Returns:
the algorithm URI of this AlgorithmMethod

getParameterSpec

AlgorithmParameterSpec getParameterSpec()
Returns the algorithm parameters of this AlgorithmMethod.

Returns:
the algorithm parameters of this AlgorithmMethod. Returns null if this AlgorithmMethod does not require parameters and they are not specified.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.xml.crypto.KeySelector

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.KeySelector

Packages that use KeySelector
javax.xml.crypto | Common classes for XML cryptography.
javax.xml.crypto.dom | DOM-specific classes for the javax.xml.crypto package.
javax.xml.crypto.dsig.dom | DOM-specific classes for the javax.xml.crypto.dsig package.

Uses of KeySelector in javax.xml.crypto

Methods in javax.xml.crypto that return KeySelector
KeySelector | XMLCryptoContext.getKeySelector() Returns the key selector for finding a key.
static KeySelector | KeySelector.singletonKeySelector(Key key) Returns a KeySelector that always selects the specified key, regardless of the KeyInfo passed to it.

Methods in javax.xml.crypto with parameters of type KeySelector
 void XMLCryptoContext.setKeySelector(KeySelector ks)
Sets the key selector for finding a key.

Uses of KeySelector in javax.xml.crypto.dom

Methods in javax.xml.crypto.dom that return KeySelector
 KeySelector DOMCryptoContext.getKeySelector()

Methods in javax.xml.crypto.dom with parameters of type KeySelector
 void DOMCryptoContext.setKeySelector(KeySelector ks)

Uses of KeySelector in javax.xml.crypto.dsig.dom

Constructors in javax.xml.crypto.dsig.dom with parameters of type KeySelector
DOMSignContext(KeySelector ks, Node parent)
Creates a DOMSignContext with the specified key selector and parent node.
DOMSignContext(KeySelector ks, Node parent, Node nextSibling)
Creates a DOMSignContext with the specified key selector, parent and next sibling nodes.
DOMValidateContext(KeySelector ks, Node node)
Creates a DOMValidateContext containing the specified key selector and node.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.KeySelector.Purpose

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.KeySelector.Purpose

Packages that use KeySelector.Purpose
javax.xml.crypto Common classes for XML cryptography.

Uses of KeySelector.Purpose in javax.xml.crypto

Fields in javax.xml.crypto declared as KeySelector.Purpose
static KeySelector.Purpose | KeySelector.Purpose.DECRYPT A key for decrypting.
static KeySelector.Purpose | KeySelector.Purpose.ENCRYPT A key for encrypting.
static KeySelector.Purpose | KeySelector.Purpose.SIGN A key for signing.
static KeySelector.Purpose | KeySelector.Purpose.VERIFY A key for verifying.

Methods in javax.xml.crypto with parameters of type KeySelector.Purpose
abstract  KeySelectorResult KeySelector.select(KeyInfo keyInfo, KeySelector.Purpose purpose, AlgorithmMethod method, XMLCryptoContext context)
Attempts to find a key that satisfies the specified constraints.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.KeySelectorException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.KeySelectorException

Packages that use KeySelectorException
javax.xml.crypto Common classes for XML cryptography.

Uses of KeySelectorException in javax.xml.crypto

Methods in javax.xml.crypto that throw KeySelectorException
abstract  KeySelectorResult KeySelector.select(KeyInfo keyInfo, KeySelector.Purpose purpose, AlgorithmMethod method, XMLCryptoContext context)
Attempts to find a key that satisfies the specified constraints.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.MarshalException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.MarshalException

Packages that use MarshalException
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.keyinfo | Classes for parsing and processing KeyInfo elements and structures.

Uses of MarshalException in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that throw MarshalException
abstract void | TransformService.marshalParams(XMLStructure parent, XMLCryptoContext context) Marshals the algorithm-specific parameters.
void | XMLSignature.sign(XMLSignContext signContext) Signs this XMLSignature.
abstract XMLSignature | XMLSignatureFactory.unmarshalXMLSignature(XMLStructure xmlStructure) Unmarshals a new XMLSignature instance from a mechanism-specific XMLStructure instance.
abstract XMLSignature | XMLSignatureFactory.unmarshalXMLSignature(XMLValidateContext context) Unmarshals a new XMLSignature instance from a mechanism-specific XMLValidateContext instance.

Uses of MarshalException in javax.xml.crypto.dsig.keyinfo

Methods in javax.xml.crypto.dsig.keyinfo that throw MarshalException
void | KeyInfo.marshal(XMLStructure parent, XMLCryptoContext context) Marshals the key info to XML.
abstract KeyInfo | KeyInfoFactory.unmarshalKeyInfo(XMLStructure xmlStructure) Unmarshals a new KeyInfo instance from a mechanism-specific XMLStructure (ex: DOMStructure) instance.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.NoSuchMechanismException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.NoSuchMechanismException

No usage of javax.xml.crypto.NoSuchMechanismException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.OctetStreamData

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.OctetStreamData

No usage of javax.xml.crypto.OctetStreamData

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.URIReferenceException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.URIReferenceException

Packages that use URIReferenceException
javax.xml.crypto | Common classes for XML cryptography.
javax.xml.crypto.dsig.keyinfo | Classes for parsing and processing KeyInfo elements and structures.

Uses of URIReferenceException in javax.xml.crypto

Methods in javax.xml.crypto that throw URIReferenceException
 Data URIDereferencer.dereference(URIReference uriReference, XMLCryptoContext context)
Dereferences the specified URIReference and returns the dereferenced data.

Uses of URIReferenceException in javax.xml.crypto.dsig.keyinfo

Methods in javax.xml.crypto.dsig.keyinfo that throw URIReferenceException
 Data RetrievalMethod.dereference(XMLCryptoContext context)
Dereferences the KeyInfo information referenced by this RetrievalMethod and applies the specified Transforms.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.AlgorithmMethod

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.AlgorithmMethod

Packages that use AlgorithmMethod
javax.xml.crypto | Common classes for XML cryptography.
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.

Uses of AlgorithmMethod in javax.xml.crypto

Methods in javax.xml.crypto with parameters of type AlgorithmMethod
abstract  KeySelectorResult KeySelector.select(KeyInfo keyInfo, KeySelector.Purpose purpose, AlgorithmMethod method, XMLCryptoContext context)
Attempts to find a key that satisfies the specified constraints.

Uses of AlgorithmMethod in javax.xml.crypto.dsig

Subinterfaces of AlgorithmMethod in javax.xml.crypto.dsig
interface | CanonicalizationMethod A representation of the XML CanonicalizationMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | DigestMethod A representation of the XML DigestMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | SignatureMethod A representation of the XML SignatureMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | Transform A representation of the XML Transform element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.

Classes in javax.xml.crypto.dsig that implement AlgorithmMethod
 class TransformService
A Service Provider Interface for transform and canonicalization algorithms.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.Data

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.Data

Packages that use Data
javax.xml.crypto | Common classes for XML cryptography.
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.keyinfo | Classes for parsing and processing KeyInfo elements and structures.

Uses of Data in javax.xml.crypto

Subinterfaces of Data in javax.xml.crypto
 interface NodeSetData
An abstract representation of a Data type containing a node-set.

Classes in javax.xml.crypto that implement Data
 class OctetStreamData
A representation of a Data type containing an octet stream.

Methods in javax.xml.crypto that return Data
 Data URIDereferencer.dereference(URIReference uriReference, XMLCryptoContext context)
Dereferences the specified URIReference and returns the dereferenced data.

Uses of Data in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return Data
Data | Reference.getDereferencedData() Returns the dereferenced data, if reference caching is enabled.
Data | Transform.transform(Data data, XMLCryptoContext context) Transforms the specified data using the underlying transform algorithm.
Data | Transform.transform(Data data, XMLCryptoContext context, OutputStream os) Transforms the specified data using the underlying transform algorithm.

Methods in javax.xml.crypto.dsig with parameters of type Data
abstract Reference | XMLSignatureFactory.newReference(String uri, DigestMethod dm, List appliedTransforms, Data result, List transforms, String type, String id) Creates a Reference with the specified parameters.
Data | Transform.transform(Data data, XMLCryptoContext context) Transforms the specified data using the underlying transform algorithm.
Data | Transform.transform(Data data, XMLCryptoContext context, OutputStream os) Transforms the specified data using the underlying transform algorithm.

Uses of Data in javax.xml.crypto.dsig.keyinfo

Methods in javax.xml.crypto.dsig.keyinfo that return Data
 Data RetrievalMethod.dereference(XMLCryptoContext context)
Dereferences the KeyInfo information referenced by this RetrievalMethod and applies the specified Transforms.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.KeySelectorResult

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.KeySelectorResult

Packages that use KeySelectorResult
javax.xml.crypto | Common classes for XML cryptography.
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.

Uses of KeySelectorResult in javax.xml.crypto

Methods in javax.xml.crypto that return KeySelectorResult
abstract  KeySelectorResult KeySelector.select(KeyInfo keyInfo, KeySelector.Purpose purpose, AlgorithmMethod method, XMLCryptoContext context)
Attempts to find a key that satisfies the specified constraints.

Uses of KeySelectorResult in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return KeySelectorResult
 KeySelectorResult XMLSignature.getKeySelectorResult()
Returns the result of the KeySelector, if specified, after this XMLSignature has been signed or validated.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.NodeSetData

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.NodeSetData

No usage of javax.xml.crypto.NodeSetData

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.URIDereferencer

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.URIDereferencer

Packages that use URIDereferencer
javax.xml.crypto | Common classes for XML cryptography.
javax.xml.crypto.dom | DOM-specific classes for the javax.xml.crypto package.
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.keyinfo | Classes for parsing and processing KeyInfo elements and structures.

Uses of URIDereferencer in javax.xml.crypto

Methods in javax.xml.crypto that return URIDereferencer
 URIDereferencer XMLCryptoContext.getURIDereferencer()
Returns a URIDereferencer that is used to dereference URIReferences.

Methods in javax.xml.crypto with parameters of type URIDereferencer
 void XMLCryptoContext.setURIDereferencer(URIDereferencer dereferencer)
Sets a URIDereferencer that is used to dereference URIReferences.

Uses of URIDereferencer in javax.xml.crypto.dom

Methods in javax.xml.crypto.dom that return URIDereferencer
 URIDereferencer DOMCryptoContext.getURIDereferencer()

Methods in javax.xml.crypto.dom with parameters of type URIDereferencer
 void DOMCryptoContext.setURIDereferencer(URIDereferencer dereferencer)

Uses of URIDereferencer in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return URIDereferencer
abstract  URIDereferencer XMLSignatureFactory.getURIDereferencer()
Returns a reference to the URIDereferencer that is used by default to dereference URIs in Reference objects.

Uses of URIDereferencer in javax.xml.crypto.dsig.keyinfo

Methods in javax.xml.crypto.dsig.keyinfo that return URIDereferencer
abstract  URIDereferencer KeyInfoFactory.getURIDereferencer()
Returns a reference to the URIDereferencer that is used by default to dereference URIs in RetrievalMethod objects.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.URIReference

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.URIReference

Packages that use URIReference
javax.xml.crypto | Common classes for XML cryptography.
javax.xml.crypto.dom | DOM-specific classes for the javax.xml.crypto package.
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.keyinfo | Classes for parsing and processing KeyInfo elements and structures.

Uses of URIReference in javax.xml.crypto

Methods in javax.xml.crypto that return URIReference
 URIReference URIReferenceException.getURIReference()
Returns the URIReference that was being dereferenced when the exception was thrown.

Methods in javax.xml.crypto with parameters of type URIReference
 Data URIDereferencer.dereference(URIReference uriReference, XMLCryptoContext context)
Dereferences the specified URIReference and returns the dereferenced data.

Constructors in javax.xml.crypto with parameters of type URIReference
URIReferenceException(String message, Throwable cause, URIReference uriReference)
Constructs a new URIReferenceException with the specified detail message, cause and URIReference.

Uses of URIReference in javax.xml.crypto.dom

Subinterfaces of URIReference in javax.xml.crypto.dom
 interface DOMURIReference
A DOM-specific URIReference.

Uses of URIReference in javax.xml.crypto.dsig

Subinterfaces of URIReference in javax.xml.crypto.dsig
 interface Reference
A representation of the Reference element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.

Uses of URIReference in javax.xml.crypto.dsig.keyinfo

Subinterfaces of URIReference in javax.xml.crypto.dsig.keyinfo
 interface RetrievalMethod
A representation of the XML RetrievalMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.XMLCryptoContext

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.XMLCryptoContext

Packages that use XMLCryptoContext
javax.xml.crypto | Common classes for XML cryptography.
javax.xml.crypto.dom | DOM-specific classes for the javax.xml.crypto package.
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.dom | DOM-specific classes for the javax.xml.crypto.dsig package.
javax.xml.crypto.dsig.keyinfo | Classes for parsing and processing KeyInfo elements and structures.

Uses of XMLCryptoContext in javax.xml.crypto

Methods in javax.xml.crypto with parameters of type XMLCryptoContext
Data | URIDereferencer.dereference(URIReference uriReference, XMLCryptoContext context) Dereferences the specified URIReference and returns the dereferenced data.
abstract KeySelectorResult | KeySelector.select(KeyInfo keyInfo, KeySelector.Purpose purpose, AlgorithmMethod method, XMLCryptoContext context) Attempts to find a key that satisfies the specified constraints.

Uses of XMLCryptoContext in javax.xml.crypto.dom

Classes in javax.xml.crypto.dom that implement XMLCryptoContext
 class DOMCryptoContext
This class provides a DOM-specific implementation of the XMLCryptoContext interface.

Uses of XMLCryptoContext in javax.xml.crypto.dsig

Subinterfaces of XMLCryptoContext in javax.xml.crypto.dsig
interface | XMLSignContext Contains context information for generating XML Signatures.
interface | XMLValidateContext Contains context information for validating XML Signatures.

Methods in javax.xml.crypto.dsig with parameters of type XMLCryptoContext
abstract void | TransformService.init(XMLStructure parent, XMLCryptoContext context) Initializes this TransformService with the specified parameters and document context.
abstract void | TransformService.marshalParams(XMLStructure parent, XMLCryptoContext context) Marshals the algorithm-specific parameters.
Data | Transform.transform(Data data, XMLCryptoContext context) Transforms the specified data using the underlying transform algorithm.
Data | Transform.transform(Data data, XMLCryptoContext context, OutputStream os) Transforms the specified data using the underlying transform algorithm.

Uses of XMLCryptoContext in javax.xml.crypto.dsig.dom

Classes in javax.xml.crypto.dsig.dom that implement XMLCryptoContext
class | DOMSignContext A DOM-specific XMLSignContext.
class | DOMValidateContext A DOM-specific XMLValidateContext.

Uses of XMLCryptoContext in javax.xml.crypto.dsig.keyinfo

Methods in javax.xml.crypto.dsig.keyinfo with parameters of type XMLCryptoContext
Data | RetrievalMethod.dereference(XMLCryptoContext context) Dereferences the KeyInfo information referenced by this RetrievalMethod and applies the specified Transforms.
void | KeyInfo.marshal(XMLStructure parent, XMLCryptoContext context) Marshals the key info to XML.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.XMLStructure

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.XMLStructure

Packages that use XMLStructure
javax.xml.crypto.dom | DOM-specific classes for the javax.xml.crypto package.
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.keyinfo | Classes for parsing and processing KeyInfo elements and structures.
javax.xml.crypto.dsig.spec | Parameter classes for XML digital signatures.

Uses of XMLStructure in javax.xml.crypto.dom

Classes in javax.xml.crypto.dom that implement XMLStructure
 class DOMStructure
A DOM-specific XMLStructure.

Uses of XMLStructure in javax.xml.crypto.dsig

Subinterfaces of XMLStructure in javax.xml.crypto.dsig
interface | CanonicalizationMethod A representation of the XML CanonicalizationMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | DigestMethod A representation of the XML DigestMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | Manifest A representation of the XML Manifest element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | Reference A representation of the Reference element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | SignatureMethod A representation of the XML SignatureMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | SignatureProperties A representation of the XML SignatureProperties element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | SignatureProperty A representation of the XML SignatureProperty element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | SignedInfo An representation of the XML SignedInfo element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | Transform A representation of the XML Transform element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | XMLObject A representation of the XML Object element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | XMLSignature A representation of the XML Signature element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
static interface | XMLSignature.SignatureValue A representation of the XML SignatureValue element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.

Classes in javax.xml.crypto.dsig that implement XMLStructure
 class TransformService
A Service Provider Interface for transform and canonicalization algorithms.

Methods in javax.xml.crypto.dsig with parameters of type XMLStructure
abstract void | TransformService.init(XMLStructure parent, XMLCryptoContext context) Initializes this TransformService with the specified parameters and document context.
abstract void | TransformService.marshalParams(XMLStructure parent, XMLCryptoContext context) Marshals the algorithm-specific parameters.
abstract CanonicalizationMethod | XMLSignatureFactory.newCanonicalizationMethod(String algorithm, XMLStructure params) Creates a CanonicalizationMethod for the specified algorithm URI and parameters.
abstract Transform | XMLSignatureFactory.newTransform(String algorithm, XMLStructure params) Creates a Transform for the specified algorithm URI and parameters.
abstract XMLSignature | XMLSignatureFactory.unmarshalXMLSignature(XMLStructure xmlStructure) Unmarshals a new XMLSignature instance from a mechanism-specific XMLStructure instance.

Uses of XMLStructure in javax.xml.crypto.dsig.keyinfo

Subinterfaces of XMLStructure in javax.xml.crypto.dsig.keyinfo
interface | KeyInfo A representation of the XML KeyInfo element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | KeyName A representation of the XML KeyName element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | KeyValue A representation of the XML KeyValue element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | PGPData A representation of the XML PGPData element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | RetrievalMethod A representation of the XML RetrievalMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | X509Data A representation of the XML X509Data element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
interface | X509IssuerSerial A representation of the XML X509IssuerSerial element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.

Methods in javax.xml.crypto.dsig.keyinfo with parameters of type XMLStructure
void | KeyInfo.marshal(XMLStructure parent, XMLCryptoContext context) Marshals the key info to XML.
abstract KeyInfo | KeyInfoFactory.unmarshalKeyInfo(XMLStructure xmlStructure) Unmarshals a new KeyInfo instance from a mechanism-specific XMLStructure (ex: DOMStructure) instance.

Uses of XMLStructure in javax.xml.crypto.dsig.spec

Methods in javax.xml.crypto.dsig.spec that return XMLStructure
 XMLStructure XSLTTransformParameterSpec.getStylesheet()
Returns the stylesheet.

Constructors in javax.xml.crypto.dsig.spec with parameters of type XMLStructure
XSLTTransformParameterSpec(XMLStructure stylesheet)
Creates an XSLTTransformParameterSpec with the specified stylesheet.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


dom

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.crypto.dom

DOM-specific classes for the javax.xml.crypto package.

See:
Description

Interface Summary
DOMURIReference A DOM-specific URIReference.

Class Summary
DOMCryptoContext | This class provides a DOM-specific implementation of the XMLCryptoContext interface.
DOMStructure | A DOM-specific XMLStructure.

Package javax.xml.crypto.dom Description

DOM-specific classes for the javax.xml.crypto package. Only users who are using a DOM-based XML cryptographic implementations (ex: XMLSignatureFactory or KeyInfoFactory) should need to make direct use of this package.

Package Specification

  • XML-Signature Syntax and Processing: W3C Recommendation
  • RFC 3275: XML-Signature Syntax and Processing

Since:
1.6

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.crypto.dom Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.crypto.dom

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.crypto.dom.DOMCryptoContext (implements javax.xml.crypto.XMLCryptoContext)
    • javax.xml.crypto.dom.DOMStructure (implements javax.xml.crypto.XMLStructure)

Interface Hierarchy

  • javax.xml.crypto.URIReference
    • javax.xml.crypto.dom.DOMURIReference
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.crypto.dom

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.crypto.dom

Packages that use javax.xml.crypto.dom
javax.xml.crypto.dsig.dom DOM-specific classes for the javax.xml.crypto.dsig package.

Classes in javax.xml.crypto.dom used by javax.xml.crypto.dsig.dom
DOMCryptoContext
This class provides a DOM-specific implementation of the XMLCryptoContext interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.dom.DOMCryptoContext

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.dom.DOMCryptoContext

Packages that use DOMCryptoContext
javax.xml.crypto.dsig.dom DOM-specific classes for the javax.xml.crypto.dsig package.

Uses of DOMCryptoContext in javax.xml.crypto.dsig.dom

Subclasses of DOMCryptoContext in javax.xml.crypto.dsig.dom
class | DOMSignContext A DOM-specific XMLSignContext.
class | DOMValidateContext A DOM-specific XMLValidateContext.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.dom.DOMStructure

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.dom.DOMStructure

No usage of javax.xml.crypto.dom.DOMStructure

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dom.DOMURIReference

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dom.DOMURIReference

No usage of javax.xml.crypto.dom.DOMURIReference

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DOMCryptoContext

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dom
Class DOMCryptoContext

java.lang.Object
    extended by  javax.xml.crypto.dom.DOMCryptoContext
All Implemented Interfaces:
XMLCryptoContext
Direct Known Subclasses:
DOMSignContext, DOMValidateContext
public class DOMCryptoContext
extends Object
implements XMLCryptoContext

This class provides a DOM-specific implementation of the XMLCryptoContext interface. It also includes additional methods that are specific to a DOM-based implementation for registering and retrieving elements that contain attributes of type ID.

Since:
1.6

Constructor Summary
protected DOMCryptoContext()
Default constructor.
Method Summary
Object | get(Object key) This implementation uses an internal HashMap to get the object that the specified key maps to.
String | getBaseURI() Returns the base URI.
String | getDefaultNamespacePrefix() Returns the default namespace prefix.
Element | getElementById(String idValue) Returns the Element with the specified ID attribute value.
KeySelector | getKeySelector() Returns the key selector for finding a key.
String | getNamespacePrefix(String namespaceURI, String defaultPrefix) This implementation uses an internal HashMap to get the prefix that the specified URI maps to.
Object | getProperty(String name) This implementation uses an internal HashMap to get the object that the specified name maps to.
URIDereferencer | getURIDereferencer() Returns a URIDereferencer that is used to dereference URIReferences.
Iterator | iterator() Returns a read-only iterator over the set of Id/Element mappings of this DOMCryptoContext.
Object | put(Object key, Object value) This implementation uses an internal HashMap to map the key to the specified object.
String | putNamespacePrefix(String namespaceURI, String prefix) This implementation uses an internal HashMap to map the URI to the specified prefix.
void | setBaseURI(String baseURI) Sets the base URI.
void | setDefaultNamespacePrefix(String defaultPrefix) Sets the default namespace prefix.
void | setIdAttributeNS(Element element, String namespaceURI, String localName) Registers the element's attribute specified by the namespace URI and local name to be of type ID.
void | setKeySelector(KeySelector ks) Sets the key selector for finding a key.
Object | setProperty(String name, Object value) This implementation uses an internal HashMap to map the name to the specified object.
void | setURIDereferencer(URIDereferencer dereferencer) Sets a URIDereferencer that is used to dereference URIReferences.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DOMCryptoContext

protected DOMCryptoContext()
Default constructor. (For invocation by subclass constructors).

Method Detail

getNamespacePrefix

public String getNamespacePrefix(String namespaceURI,
                                 String defaultPrefix)
This implementation uses an internal HashMap to get the prefix that the specified URI maps to. It returns the defaultPrefix if it maps to null.

Specified by:
getNamespacePrefix in interface XMLCryptoContext
Parameters:
namespaceURI - a namespace URI
defaultPrefix - the prefix to be returned in the event that the the specified namespace URI has not been bound to a prefix.
Returns:
the prefix that is associated with the specified namespace URI, or defaultPrefix if the URI is not registered. If the namespace URI is registered but has no prefix, an empty string ("") is returned.
Throws:
NullPointerException - if namespaceURI is null
See Also:
XMLCryptoContext.putNamespacePrefix(String, String)

putNamespacePrefix

public String putNamespacePrefix(String namespaceURI,
                                 String prefix)
This implementation uses an internal HashMap to map the URI to the specified prefix.

Specified by:
putNamespacePrefix in interface XMLCryptoContext
Parameters:
namespaceURI - a namespace URI
prefix - a namespace prefix (or null to remove any existing mapping). Specifying the empty string ("") binds no prefix to the namespace URI.
Returns:
the previous prefix associated with the specified namespace URI, or null if there was none
Throws:
NullPointerException - if namespaceURI is null
See Also:
XMLCryptoContext.getNamespacePrefix(String, String)

getDefaultNamespacePrefix

public String getDefaultNamespacePrefix()
Description copied from interface: XMLCryptoContext
Returns the default namespace prefix. The default namespace prefix is the prefix for all namespace URIs not explicitly set by the putNamespacePrefix method.

Specified by:
getDefaultNamespacePrefix in interface XMLCryptoContext
Returns:
the default namespace prefix, or null if none has been set.
See Also:
XMLCryptoContext.setDefaultNamespacePrefix(String)

setDefaultNamespacePrefix

public void setDefaultNamespacePrefix(String defaultPrefix)
Description copied from interface: XMLCryptoContext
Sets the default namespace prefix. This sets the namespace prefix for all namespace URIs not explicitly set by the putNamespacePrefix method.

Specified by:
setDefaultNamespacePrefix in interface XMLCryptoContext
Parameters:
defaultPrefix - the default namespace prefix, or null to remove the current setting. Specify the empty string ("") to bind no prefix.
See Also:
XMLCryptoContext.getDefaultNamespacePrefix()

getBaseURI

public String getBaseURI()
Description copied from interface: XMLCryptoContext
Returns the base URI.

Specified by:
getBaseURI in interface XMLCryptoContext
Returns:
the base URI, or null if not specified
See Also:
XMLCryptoContext.setBaseURI(String)

setBaseURI

public void setBaseURI(String baseURI)
Description copied from interface: XMLCryptoContext
Sets the base URI.

Specified by:
setBaseURI in interface XMLCryptoContext
Parameters:
baseURI - the base URI, or null to remove current value
Throws:
IllegalArgumentException - if baseURI is not RFC 2396 compliant
See Also:
XMLCryptoContext.getBaseURI()

getURIDereferencer

public URIDereferencer getURIDereferencer()
Description copied from interface: XMLCryptoContext
Returns a URIDereferencer that is used to dereference URIReferences.

Specified by:
getURIDereferencer in interface XMLCryptoContext
Returns:
the URIDereferencer, or null if not specified
See Also:
XMLCryptoContext.setURIDereferencer(URIDereferencer)

setURIDereferencer

public void setURIDereferencer(URIDereferencer dereferencer)
Description copied from interface: XMLCryptoContext
Sets a URIDereferencer that is used to dereference URIReferences. The specified URIDereferencer is used in place of an implementation's default URIDereferencer.

Specified by:
setURIDereferencer in interface XMLCryptoContext
Parameters:
dereferencer - the URIDereferencer, or null to remove any current setting
See Also:
XMLCryptoContext.getURIDereferencer()

getProperty

public Object getProperty(String name)
This implementation uses an internal HashMap to get the object that the specified name maps to.

Specified by:
getProperty in interface XMLCryptoContext
Parameters:
name - the name of the property
Returns:
the current value of the specified property, or null if it does not have a value
Throws:
NullPointerException - if name is null
See Also:
XMLCryptoContext.setProperty(String, Object)

setProperty

public Object setProperty(String name,
                          Object value)
This implementation uses an internal HashMap to map the name to the specified object.

Specified by:
setProperty in interface XMLCryptoContext
Parameters:
name - the name of the property
value - the value of the property to be set
Returns:
the previous value of the specified property, or null if it did not have a value
Throws:
NullPointerException - if name is null
See Also:
XMLCryptoContext.getProperty(String)

getKeySelector

public KeySelector getKeySelector()
Description copied from interface: XMLCryptoContext
Returns the key selector for finding a key.

Specified by:
getKeySelector in interface XMLCryptoContext
Returns:
the key selector, or null if not specified
See Also:
XMLCryptoContext.setKeySelector(KeySelector)

setKeySelector

public void setKeySelector(KeySelector ks)
Description copied from interface: XMLCryptoContext
Sets the key selector for finding a key.

Specified by:
setKeySelector in interface XMLCryptoContext
Parameters:
ks - the key selector, or null to remove the current setting
See Also:
XMLCryptoContext.getKeySelector()

getElementById

public Element getElementById(String idValue)
Returns the Element with the specified ID attribute value.

This implementation uses an internal HashMap to get the element that the specified attribute value maps to.

Parameters:
idValue - the value of the ID
Returns:
the Element with the specified ID attribute value, or null if none.
Throws:
NullPointerException - if idValue is null
See Also:
setIdAttributeNS(org.w3c.dom.Element, java.lang.String, java.lang.String)

setIdAttributeNS

public void setIdAttributeNS(Element element,
                             String namespaceURI,
                             String localName)
Registers the element's attribute specified by the namespace URI and local name to be of type ID. The attribute must have a non-empty value.

This implementation uses an internal HashMap to map the attribute's value to the specified element.

Parameters:
element - the element
namespaceURI - the namespace URI of the attribute (specify null if not applicable)
localName - the local name of the attribute
Throws:
IllegalArgumentException - if localName is not an attribute of the specified element or it does not contain a specific value
NullPointerException - if element or localName is null
See Also:
getElementById(java.lang.String)

iterator

public Iterator iterator()
Returns a read-only iterator over the set of Id/Element mappings of this DOMCryptoContext. Attempts to modify the set via the Iterator.remove() method throw an UnsupportedOperationException. The mappings are returned in no particular order. Each element in the iteration is represented as a Map.Entry. If the DOMCryptoContext is modified while an iteration is in progress, the results of the iteration are undefined.

Returns:
a read-only iterator over the set of mappings

get

public Object get(Object key)
This implementation uses an internal HashMap to get the object that the specified key maps to.

Specified by:
get in interface XMLCryptoContext
Parameters:
key - the key whose associated value is to be returned
Returns:
the value to which this context maps the specified key, or null if there is no mapping for the key
See Also:
XMLCryptoContext.put(Object, Object)

put

public Object put(Object key,
                  Object value)
This implementation uses an internal HashMap to map the key to the specified object.

Specified by:
put in interface XMLCryptoContext
Parameters:
key - key with which the specified value is to be associated with
value - value to be associated with the specified key
Returns:
the previous value associated with the key, or null if there was no mapping for the key
Throws:
IllegalArgumentException - if some aspect of this key or value prevents it from being stored in this context
See Also:
XMLCryptoContext.get(Object)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


DOMStructure

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dom
Class DOMStructure

java.lang.Object
    extended by  javax.xml.crypto.dom.DOMStructure
All Implemented Interfaces:
XMLStructure
public class DOMStructure
extends Object
implements XMLStructure

A DOM-specific XMLStructure. The purpose of this class is to allow a DOM node to be used to represent extensible content (any elements or mixed content) in XML Signature structures.

If a sequence of nodes is needed, the node contained in the DOMStructure is the first node of the sequence and successive nodes can be accessed by invoking Node.getNextSibling().

If the owner document of the DOMStructure is different than the target document of an XMLSignature, the XMLSignature.sign(XMLSignContext) method imports the node into the target document before generating the signature.

Since:
1.6

Constructor Summary
DOMStructure(Node node)
Creates a DOMStructure containing the specified node.
Method Summary
Node | getNode() Returns the node contained in this DOMStructure.
boolean | isFeatureSupported(String feature) Indicates whether a specified feature is supported.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DOMStructure

public DOMStructure(Node node)
Creates a DOMStructure containing the specified node.

Parameters:
node - the node
Throws:
NullPointerException - if node is null
Method Detail

getNode

public Node getNode()
Returns the node contained in this DOMStructure.

Returns:
the node

isFeatureSupported

public boolean isFeatureSupported(String feature)
Description copied from interface: XMLStructure
Indicates whether a specified feature is supported.

Specified by:
isFeatureSupported in interface XMLStructure
Parameters:
feature - the feature name (as an absolute URI)
Returns:
true if the specified feature is supported, false otherwise
Throws:
NullPointerException - if feature is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DOMURIReference

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dom
Interface DOMURIReference

All Superinterfaces:
URIReference
public interface DOMURIReference
extends URIReference

A DOM-specific URIReference. The purpose of this class is to provide additional context necessary for resolving XPointer URIs or same-document references.

Since:
1.6

Method Summary
 Node getHere()
Returns the here node.
Methods inherited from interface javax.xml.crypto.URIReference
getType, getURI

Method Detail

getHere

Node getHere()
Returns the here node.

Returns:
the attribute or processing instruction node or the parent element of the text node that directly contains the URI
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


dsig

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.crypto.dsig

Classes for generating and validating XML digital signatures.

See:
Description

Interface Summary
CanonicalizationMethod | A representation of the XML CanonicalizationMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
DigestMethod | A representation of the XML DigestMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
Manifest | A representation of the XML Manifest element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
Reference | A representation of the Reference element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
SignatureMethod | A representation of the XML SignatureMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
SignatureProperties | A representation of the XML SignatureProperties element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
SignatureProperty | A representation of the XML SignatureProperty element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
SignedInfo | An representation of the XML SignedInfo element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
Transform | A representation of the XML Transform element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
XMLObject | A representation of the XML Object element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
XMLSignature | A representation of the XML Signature element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
XMLSignature.SignatureValue | A representation of the XML SignatureValue element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
XMLSignContext | Contains context information for generating XML Signatures.
XMLValidateContext | Contains context information for validating XML Signatures.

Class Summary
TransformService | A Service Provider Interface for transform and canonicalization algorithms.
XMLSignatureFactory | A factory for creating XMLSignature objects from scratch or for unmarshalling an XMLSignature object from a corresponding XML representation.

Exception Summary
TransformException | Indicates an exceptional condition that occured while executing a transform algorithm.
XMLSignatureException | Indicates an exceptional condition that occured during the XML signature generation or validation process.

Package javax.xml.crypto.dsig Description

Classes for generating and validating XML digital signatures. This package includes classes that represent the core elements defined in the W3C XML digital signature specification: XMLSignature, SignedInfo, CanonicalizationMethod, SignatureMethod, Reference, DigestMethod, XMLObject, Manifest, SignatureProperties, and SignatureProperty. KeyInfo types are defined in the javax.xml.crypto.dsig.keyinfo subpackage. XMLSignatureFactory is an abstract factory that creates XMLSignature objects from scratch or from a pre-existing XML representation, such as a DOM node. TransformService is a service provider interface for creating and plugging in implementations of transform and canonicalization algorithms.

Of primary significance in this package is the XMLSignature class, which allows you to sign and validate an XML digital signature.

Package Specification

  • XML-Signature Syntax and Processing: W3C Recommendation
  • RFC 3275: XML-Signature Syntax and Processing

Since:
1.6

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.crypto.dsig Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.crypto.dsig

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.xml.crypto.dsig.TransformException
        • javax.xml.crypto.dsig.XMLSignatureException
    • javax.xml.crypto.dsig.TransformService (implements javax.xml.crypto.dsig.Transform)
    • javax.xml.crypto.dsig.XMLSignatureFactory

Interface Hierarchy

  • javax.xml.crypto.AlgorithmMethod
    • javax.xml.crypto.dsig.DigestMethod (also extends javax.xml.crypto.XMLStructure)
    • javax.xml.crypto.dsig.SignatureMethod (also extends javax.xml.crypto.XMLStructure)
    • javax.xml.crypto.dsig.Transform (also extends javax.xml.crypto.XMLStructure)
      • javax.xml.crypto.dsig.CanonicalizationMethod
  • javax.xml.crypto.URIReference
    • javax.xml.crypto.dsig.Reference (also extends javax.xml.crypto.XMLStructure)
  • javax.xml.crypto.XMLCryptoContext
    • javax.xml.crypto.dsig.XMLSignContext
    • javax.xml.crypto.dsig.XMLValidateContext
  • javax.xml.crypto.XMLStructure
    • javax.xml.crypto.dsig.DigestMethod (also extends javax.xml.crypto.AlgorithmMethod)
    • javax.xml.crypto.dsig.Manifest
    • javax.xml.crypto.dsig.Reference (also extends javax.xml.crypto.URIReference)
    • javax.xml.crypto.dsig.SignatureMethod (also extends javax.xml.crypto.AlgorithmMethod)
    • javax.xml.crypto.dsig.SignatureProperties
    • javax.xml.crypto.dsig.SignatureProperty
    • javax.xml.crypto.dsig.SignedInfo
    • javax.xml.crypto.dsig.Transform (also extends javax.xml.crypto.AlgorithmMethod)
      • javax.xml.crypto.dsig.CanonicalizationMethod
    • javax.xml.crypto.dsig.XMLObject
    • javax.xml.crypto.dsig.XMLSignature
    • javax.xml.crypto.dsig.XMLSignature.SignatureValue
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.crypto.dsig

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.crypto.dsig

Packages that use javax.xml.crypto.dsig
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.dom | DOM-specific classes for the javax.xml.crypto.dsig package.

Classes in javax.xml.crypto.dsig used by javax.xml.crypto.dsig
CanonicalizationMethod
A representation of the XML CanonicalizationMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
DigestMethod
A representation of the XML DigestMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
Manifest
A representation of the XML Manifest element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
Reference
A representation of the Reference element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
SignatureMethod
A representation of the XML SignatureMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
SignatureProperties
A representation of the XML SignatureProperties element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
SignatureProperty
A representation of the XML SignatureProperty element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
SignedInfo
An representation of the XML SignedInfo element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
Transform
A representation of the XML Transform element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
TransformException
Indicates an exceptional condition that occured while executing a transform algorithm.
TransformService
A Service Provider Interface for transform and canonicalization algorithms.
XMLObject
A representation of the XML Object element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
XMLSignature
A representation of the XML Signature element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
XMLSignature.SignatureValue
A representation of the XML SignatureValue element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
XMLSignatureException
Indicates an exceptional condition that occured during the XML signature generation or validation process.
XMLSignatureFactory
A factory for creating XMLSignature objects from scratch or for unmarshalling an XMLSignature object from a corresponding XML representation.
XMLSignContext
Contains context information for generating XML Signatures.
XMLValidateContext
Contains context information for validating XML Signatures.

Classes in javax.xml.crypto.dsig used by javax.xml.crypto.dsig.dom
XMLSignContext
Contains context information for generating XML Signatures.
XMLValidateContext
Contains context information for validating XML Signatures.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


CanonicalizationMethod

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Interface CanonicalizationMethod

All Superinterfaces:
AlgorithmMethod, Transform, XMLStructure
public interface CanonicalizationMethod
extends Transform

A representation of the XML CanonicalizationMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. The XML Schema Definition is defined as:

   <element name="CanonicalizationMethod" type="ds:CanonicalizationMethodType"/>
     <complexType name="CanonicalizationMethodType" mixed="true">
       <sequence>
         <any namespace="##any" minOccurs="0" maxOccurs="unbounded"/>
           <!-- (0,unbounded) elements from (1,1) namespace -->
       </sequence>
       <attribute name="Algorithm" type="anyURI" use="required"/>
     </complexType>
A CanonicalizationMethod instance may be created by invoking the newCanonicalizationMethod method of the XMLSignatureFactory class.

Since:
1.6
See Also:
XMLSignatureFactory.newCanonicalizationMethod(String, C14NMethodParameterSpec)

Field Summary
static String | EXCLUSIVE The Exclusive Canonical XML (without comments) canonicalization method algorithm URI.
static String | EXCLUSIVE_WITH_COMMENTS The Exclusive Canonical XML with comments canonicalization method algorithm URI.
static String | INCLUSIVE The Canonical XML (without comments) canonicalization method algorithm URI.
static String | INCLUSIVE_WITH_COMMENTS The Canonical XML with comments canonicalization method algorithm URI.
Fields inherited from interface javax.xml.crypto.dsig.Transform
BASE64, ENVELOPED, XPATH, XPATH2, XSLT
Method Summary
 AlgorithmParameterSpec getParameterSpec()
Returns the algorithm-specific input parameters associated with this CanonicalizationMethod.
Methods inherited from interface javax.xml.crypto.dsig.Transform
transform, transform
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported
Methods inherited from interface javax.xml.crypto.AlgorithmMethod
getAlgorithm

Field Detail

INCLUSIVE

static final String INCLUSIVE
The Canonical XML (without comments) canonicalization method algorithm URI.

See Also:
Constant Field Values

INCLUSIVE_WITH_COMMENTS

static final String INCLUSIVE_WITH_COMMENTS
The Canonical XML with comments canonicalization method algorithm URI.

See Also:
Constant Field Values

EXCLUSIVE

static final String EXCLUSIVE
The Exclusive Canonical XML (without comments) canonicalization method algorithm URI.

See Also:
Constant Field Values

EXCLUSIVE_WITH_COMMENTS

static final String EXCLUSIVE_WITH_COMMENTS
The Exclusive Canonical XML with comments canonicalization method algorithm URI.

See Also:
Constant Field Values
Method Detail

getParameterSpec

AlgorithmParameterSpec getParameterSpec()
Returns the algorithm-specific input parameters associated with this CanonicalizationMethod.

The returned parameters can be typecast to a C14NMethodParameterSpec object.

Specified by:
getParameterSpec in interface AlgorithmMethod
Specified by:
getParameterSpec in interface Transform
Returns:
the algorithm-specific input parameters (may be null if not specified)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.xml.crypto.dsig.TransformException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.dsig.TransformException

Packages that use TransformException
javax.xml.crypto.dsig Classes for generating and validating XML digital signatures.

Uses of TransformException in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that throw TransformException
Data | Transform.transform(Data data, XMLCryptoContext context) Transforms the specified data using the underlying transform algorithm.
Data | Transform.transform(Data data, XMLCryptoContext context, OutputStream os) Transforms the specified data using the underlying transform algorithm.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.dsig.TransformService

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.dsig.TransformService

Packages that use TransformService
javax.xml.crypto.dsig Classes for generating and validating XML digital signatures.

Uses of TransformService in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return TransformService
static TransformService | TransformService.getInstance(String algorithm, String mechanismType) Returns a TransformService that supports the specified algorithm URI (ex: Transform.XPATH2) and mechanism type (ex: DOM).
static TransformService | TransformService.getInstance(String algorithm, String mechanismType, Provider provider) Returns a TransformService that supports the specified algorithm URI (ex: Transform.XPATH2) and mechanism type (ex: DOM) as supplied by the specified provider.
static TransformService | TransformService.getInstance(String algorithm, String mechanismType, String provider) Returns a TransformService that supports the specified algorithm URI (ex: Transform.XPATH2) and mechanism type (ex: DOM) as supplied by the specified provider.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.dsig.XMLSignatureException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.dsig.XMLSignatureException

Packages that use XMLSignatureException
javax.xml.crypto.dsig Classes for generating and validating XML digital signatures.

Uses of XMLSignatureException in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that throw XMLSignatureException
void | XMLSignature.sign(XMLSignContext signContext) Signs this XMLSignature.
boolean | XMLSignature.validate(XMLValidateContext validateContext) Validates the signature according to the core validation processing rules.
boolean | XMLSignature.SignatureValue.validate(XMLValidateContext validateContext) Validates the signature value.
boolean | Reference.validate(XMLValidateContext validateContext) Validates this reference.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.dsig.XMLSignatureFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.dsig.XMLSignatureFactory

Packages that use XMLSignatureFactory
javax.xml.crypto.dsig Classes for generating and validating XML digital signatures.

Uses of XMLSignatureFactory in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return XMLSignatureFactory
static XMLSignatureFactory | XMLSignatureFactory.getInstance() Returns an XMLSignatureFactory that supports the default XML processing mechanism and representation type ("DOM").
static XMLSignatureFactory | XMLSignatureFactory.getInstance(String mechanismType) Returns an XMLSignatureFactory that supports the specified XML processing mechanism and representation type (ex: "DOM").
static XMLSignatureFactory | XMLSignatureFactory.getInstance(String mechanismType, Provider provider) Returns an XMLSignatureFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.
static XMLSignatureFactory | XMLSignatureFactory.getInstance(String mechanismType, String provider) Returns an XMLSignatureFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.CanonicalizationMethod

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.CanonicalizationMethod

Packages that use CanonicalizationMethod
javax.xml.crypto.dsig Classes for generating and validating XML digital signatures.

Uses of CanonicalizationMethod in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return CanonicalizationMethod
CanonicalizationMethod | SignedInfo.getCanonicalizationMethod() Returns the canonicalization method of this SignedInfo.
abstract CanonicalizationMethod | XMLSignatureFactory.newCanonicalizationMethod(String algorithm, C14NMethodParameterSpec params) Creates a CanonicalizationMethod for the specified algorithm URI and parameters.
abstract CanonicalizationMethod | XMLSignatureFactory.newCanonicalizationMethod(String algorithm, XMLStructure params) Creates a CanonicalizationMethod for the specified algorithm URI and parameters.

Methods in javax.xml.crypto.dsig with parameters of type CanonicalizationMethod
abstract SignedInfo | XMLSignatureFactory.newSignedInfo(CanonicalizationMethod cm, SignatureMethod sm, List references) Creates a SignedInfo with the specified canonicalization and signature methods, and list of one or more references.
abstract SignedInfo | XMLSignatureFactory.newSignedInfo(CanonicalizationMethod cm, SignatureMethod sm, List references, String id) Creates a SignedInfo with the specified parameters.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.DigestMethod

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.DigestMethod

Packages that use DigestMethod
javax.xml.crypto.dsig Classes for generating and validating XML digital signatures.

Uses of DigestMethod in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return DigestMethod
DigestMethod | Reference.getDigestMethod() Returns the digest method of this Reference.
abstract DigestMethod | XMLSignatureFactory.newDigestMethod(String algorithm, DigestMethodParameterSpec params) Creates a DigestMethod for the specified algorithm URI and parameters.

Methods in javax.xml.crypto.dsig with parameters of type DigestMethod
abstract Reference | XMLSignatureFactory.newReference(String uri, DigestMethod dm) Creates a Reference with the specified URI and digest method.
abstract Reference | XMLSignatureFactory.newReference(String uri, DigestMethod dm, List appliedTransforms, Data result, List transforms, String type, String id) Creates a Reference with the specified parameters.
abstract Reference | XMLSignatureFactory.newReference(String uri, DigestMethod dm, List transforms, String type, String id) Creates a Reference with the specified parameters.
abstract Reference | XMLSignatureFactory.newReference(String uri, DigestMethod dm, List transforms, String type, String id, byte[] digestValue) Creates a Reference with the specified parameters and pre-calculated digest value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.Manifest

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.Manifest

Packages that use Manifest
javax.xml.crypto.dsig Classes for generating and validating XML digital signatures.

Uses of Manifest in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return Manifest
abstract Manifest | XMLSignatureFactory.newManifest(List references) Creates a Manifest containing the specified list of References.
abstract Manifest | XMLSignatureFactory.newManifest(List references, String id) Creates a Manifest containing the specified list of References and optional id.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.Reference

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.Reference

Packages that use Reference
javax.xml.crypto.dsig Classes for generating and validating XML digital signatures.

Uses of Reference in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return Reference
abstract Reference | XMLSignatureFactory.newReference(String uri, DigestMethod dm) Creates a Reference with the specified URI and digest method.
abstract Reference | XMLSignatureFactory.newReference(String uri, DigestMethod dm, List appliedTransforms, Data result, List transforms, String type, String id) Creates a Reference with the specified parameters.
abstract Reference | XMLSignatureFactory.newReference(String uri, DigestMethod dm, List transforms, String type, String id) Creates a Reference with the specified parameters.
abstract Reference | XMLSignatureFactory.newReference(String uri, DigestMethod dm, List transforms, String type, String id, byte[] digestValue) Creates a Reference with the specified parameters and pre-calculated digest value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.SignatureMethod

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.SignatureMethod

Packages that use SignatureMethod
javax.xml.crypto.dsig Classes for generating and validating XML digital signatures.

Uses of SignatureMethod in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return SignatureMethod
SignatureMethod | SignedInfo.getSignatureMethod() Returns the signature method of this SignedInfo.
abstract SignatureMethod | XMLSignatureFactory.newSignatureMethod(String algorithm, SignatureMethodParameterSpec params) Creates a SignatureMethod for the specified algorithm URI and parameters.

Methods in javax.xml.crypto.dsig with parameters of type SignatureMethod
abstract SignedInfo | XMLSignatureFactory.newSignedInfo(CanonicalizationMethod cm, SignatureMethod sm, List references) Creates a SignedInfo with the specified canonicalization and signature methods, and list of one or more references.
abstract SignedInfo | XMLSignatureFactory.newSignedInfo(CanonicalizationMethod cm, SignatureMethod sm, List references, String id) Creates a SignedInfo with the specified parameters.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.SignatureProperties

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.SignatureProperties

Packages that use SignatureProperties
javax.xml.crypto.dsig Classes for generating and validating XML digital signatures.

Uses of SignatureProperties in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return SignatureProperties
abstract  SignatureProperties XMLSignatureFactory.newSignatureProperties(List properties, String id)
Creates a SignatureProperties containing the specified list of SignaturePropertys and optional id.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.SignatureProperty

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.SignatureProperty

Packages that use SignatureProperty
javax.xml.crypto.dsig Classes for generating and validating XML digital signatures.

Uses of SignatureProperty in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return SignatureProperty
abstract  SignatureProperty XMLSignatureFactory.newSignatureProperty(List content, String target, String id)
Creates a SignatureProperty containing the specified list of XMLStructures, target URI and optional id.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.SignedInfo

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.SignedInfo

Packages that use SignedInfo
javax.xml.crypto.dsig Classes for generating and validating XML digital signatures.

Uses of SignedInfo in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return SignedInfo
SignedInfo | XMLSignature.getSignedInfo() Returns the signed info of this XMLSignature.
abstract SignedInfo | XMLSignatureFactory.newSignedInfo(CanonicalizationMethod cm, SignatureMethod sm, List references) Creates a SignedInfo with the specified canonicalization and signature methods, and list of one or more references.
abstract SignedInfo | XMLSignatureFactory.newSignedInfo(CanonicalizationMethod cm, SignatureMethod sm, List references, String id) Creates a SignedInfo with the specified parameters.

Methods in javax.xml.crypto.dsig with parameters of type SignedInfo
abstract XMLSignature | XMLSignatureFactory.newXMLSignature(SignedInfo si, KeyInfo ki) Creates an XMLSignature and initializes it with the contents of the specified SignedInfo and KeyInfo objects.
abstract XMLSignature | XMLSignatureFactory.newXMLSignature(SignedInfo si, KeyInfo ki, List objects, String id, String signatureValueId) Creates an XMLSignature and initializes it with the specified parameters.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.Transform

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.Transform

Packages that use Transform
javax.xml.crypto.dsig Classes for generating and validating XML digital signatures.

Uses of Transform in javax.xml.crypto.dsig

Subinterfaces of Transform in javax.xml.crypto.dsig
 interface CanonicalizationMethod
A representation of the XML CanonicalizationMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.

Classes in javax.xml.crypto.dsig that implement Transform
 class TransformService
A Service Provider Interface for transform and canonicalization algorithms.

Methods in javax.xml.crypto.dsig that return Transform
abstract Transform | XMLSignatureFactory.newTransform(String algorithm, TransformParameterSpec params) Creates a Transform for the specified algorithm URI and parameters.
abstract Transform | XMLSignatureFactory.newTransform(String algorithm, XMLStructure params) Creates a Transform for the specified algorithm URI and parameters.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.XMLObject

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.XMLObject

Packages that use XMLObject
javax.xml.crypto.dsig Classes for generating and validating XML digital signatures.

Uses of XMLObject in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return XMLObject
abstract  XMLObject XMLSignatureFactory.newXMLObject(List content, String id, String mimeType, String encoding)
Creates an XMLObject from the specified parameters.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.XMLSignature

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.XMLSignature

Packages that use XMLSignature
javax.xml.crypto.dsig Classes for generating and validating XML digital signatures.

Uses of XMLSignature in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return XMLSignature
abstract XMLSignature | XMLSignatureFactory.newXMLSignature(SignedInfo si, KeyInfo ki) Creates an XMLSignature and initializes it with the contents of the specified SignedInfo and KeyInfo objects.
abstract XMLSignature | XMLSignatureFactory.newXMLSignature(SignedInfo si, KeyInfo ki, List objects, String id, String signatureValueId) Creates an XMLSignature and initializes it with the specified parameters.
abstract XMLSignature | XMLSignatureFactory.unmarshalXMLSignature(XMLStructure xmlStructure) Unmarshals a new XMLSignature instance from a mechanism-specific XMLStructure instance.
abstract XMLSignature | XMLSignatureFactory.unmarshalXMLSignature(XMLValidateContext context) Unmarshals a new XMLSignature instance from a mechanism-specific XMLValidateContext instance.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.XMLSignature.SignatureValue

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.XMLSignature.SignatureValue

Packages that use XMLSignature.SignatureValue
javax.xml.crypto.dsig Classes for generating and validating XML digital signatures.

Uses of XMLSignature.SignatureValue in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return XMLSignature.SignatureValue
 XMLSignature.SignatureValue XMLSignature.getSignatureValue()
Returns the signature value of this XMLSignature.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.XMLSignContext

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.XMLSignContext

Packages that use XMLSignContext
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.dom | DOM-specific classes for the javax.xml.crypto.dsig package.

Uses of XMLSignContext in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig with parameters of type XMLSignContext
 void XMLSignature.sign(XMLSignContext signContext)
Signs this XMLSignature.

Uses of XMLSignContext in javax.xml.crypto.dsig.dom

Classes in javax.xml.crypto.dsig.dom that implement XMLSignContext
 class DOMSignContext
A DOM-specific XMLSignContext.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.XMLValidateContext

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.XMLValidateContext

Packages that use XMLValidateContext
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.dom | DOM-specific classes for the javax.xml.crypto.dsig package.

Uses of XMLValidateContext in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig with parameters of type XMLValidateContext
abstract XMLSignature | XMLSignatureFactory.unmarshalXMLSignature(XMLValidateContext context) Unmarshals a new XMLSignature instance from a mechanism-specific XMLValidateContext instance.
boolean | XMLSignature.validate(XMLValidateContext validateContext) Validates the signature according to the core validation processing rules.
boolean | XMLSignature.SignatureValue.validate(XMLValidateContext validateContext) Validates the signature value.
boolean | Reference.validate(XMLValidateContext validateContext) Validates this reference.

Uses of XMLValidateContext in javax.xml.crypto.dsig.dom

Classes in javax.xml.crypto.dsig.dom that implement XMLValidateContext
 class DOMValidateContext
A DOM-specific XMLValidateContext.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DigestMethod

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Interface DigestMethod

All Superinterfaces:
AlgorithmMethod, XMLStructure
public interface DigestMethod
extends XMLStructure, AlgorithmMethod

A representation of the XML DigestMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. The XML Schema Definition is defined as:

   <element name="DigestMethod" type="ds:DigestMethodType"/>
     <complexType name="DigestMethodType" mixed="true">
       <sequence>
         <any namespace="##any" minOccurs="0" maxOccurs="unbounded"/>
           <!-- (0,unbounded) elements from (1,1) namespace -->
       </sequence>
       <attribute name="Algorithm" type="anyURI" use="required"/>
     </complexType>
A DigestMethod instance may be created by invoking the newDigestMethod method of the XMLSignatureFactory class.

Since:
1.6
See Also:
XMLSignatureFactory.newDigestMethod(String, DigestMethodParameterSpec)

Field Summary
static String | RIPEMD160 The RIPEMD-160 digest method algorithm URI.
static String | SHA1 The SHA1 digest method algorithm URI.
static String | SHA256 The SHA256 digest method algorithm URI.
static String | SHA512 The SHA512 digest method algorithm URI.
Method Summary
 AlgorithmParameterSpec getParameterSpec()
Returns the algorithm-specific input parameters associated with this DigestMethod.
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported
Methods inherited from interface javax.xml.crypto.AlgorithmMethod
getAlgorithm

Field Detail

SHA1

static final String SHA1
The SHA1 digest method algorithm URI.

See Also:
Constant Field Values

SHA256

static final String SHA256
The SHA256 digest method algorithm URI.

See Also:
Constant Field Values

SHA512

static final String SHA512
The SHA512 digest method algorithm URI.

See Also:
Constant Field Values

RIPEMD160

static final String RIPEMD160
The RIPEMD-160 digest method algorithm URI.

See Also:
Constant Field Values
Method Detail

getParameterSpec

AlgorithmParameterSpec getParameterSpec()
Returns the algorithm-specific input parameters associated with this DigestMethod.

The returned parameters can be typecast to a DigestMethodParameterSpec object.

Specified by:
getParameterSpec in interface AlgorithmMethod
Returns:
the algorithm-specific parameters (may be null if not specified)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


dom

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.crypto.dsig.dom

DOM-specific classes for the javax.xml.crypto.dsig package.

See:
Description

Class Summary
DOMSignContext | A DOM-specific XMLSignContext.
DOMValidateContext | A DOM-specific XMLValidateContext.

Package javax.xml.crypto.dsig.dom Description

DOM-specific classes for the javax.xml.crypto.dsig package. Only users who are using a DOM-based XMLSignatureFactory or KeyInfoFactory should need to make direct use of this package.

Package Specification

  • XML-Signature Syntax and Processing: W3C Recommendation
  • RFC 3275: XML-Signature Syntax and Processing

Since:
1.6

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.crypto.dsig.dom Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.crypto.dsig.dom

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.crypto.dom.DOMCryptoContext (implements javax.xml.crypto.XMLCryptoContext)
      • javax.xml.crypto.dsig.dom.DOMSignContext (implements javax.xml.crypto.dsig.XMLSignContext)
      • javax.xml.crypto.dsig.dom.DOMValidateContext (implements javax.xml.crypto.dsig.XMLValidateContext)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.crypto.dsig.dom

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.crypto.dsig.dom

No usage of javax.xml.crypto.dsig.dom

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.dsig.dom.DOMSignContext

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.dsig.dom.DOMSignContext

No usage of javax.xml.crypto.dsig.dom.DOMSignContext

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.dsig.dom.DOMValidateContext

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.dsig.dom.DOMValidateContext

No usage of javax.xml.crypto.dsig.dom.DOMValidateContext

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DOMSignContext

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.dom
Class DOMSignContext

java.lang.Object
    extended by  javax.xml.crypto.dom.DOMCryptoContext
        extended by  javax.xml.crypto.dsig.dom.DOMSignContext
All Implemented Interfaces:
XMLSignContext, XMLCryptoContext
public class DOMSignContext
extends DOMCryptoContext
implements XMLSignContext

A DOM-specific XMLSignContext. This class contains additional methods to specify the location in a DOM tree where an XMLSignature object is to be marshalled when generating the signature.

Note that DOMSignContext instances can contain information and state specific to the XML signature structure it is used with. The results are unpredictable if a DOMSignContext is used with different signature structures (for example, you should not use the same DOMSignContext instance to sign two different XMLSignature objects).

Since:
1.6

Constructor Summary
DOMSignContext(Key signingKey, Node parent)
Creates a DOMSignContext with the specified signing key and parent node.
DOMSignContext(Key signingKey, Node parent, Node nextSibling)
Creates a DOMSignContext with the specified signing key, parent and next sibling nodes.
DOMSignContext(KeySelector ks, Node parent)
Creates a DOMSignContext with the specified key selector and parent node.
DOMSignContext(KeySelector ks, Node parent, Node nextSibling)
Creates a DOMSignContext with the specified key selector, parent and next sibling nodes.
Method Summary
Node | getNextSibling() Returns the nextSibling node.
Node | getParent() Returns the parent node.
void | setNextSibling(Node nextSibling) Sets the next sibling node.
void | setParent(Node parent) Sets the parent node.
Methods inherited from class javax.xml.crypto.dom.DOMCryptoContext
get, getBaseURI, getDefaultNamespacePrefix, getElementById, getKeySelector, getNamespacePrefix, getProperty, getURIDereferencer, iterator, put, putNamespacePrefix, setBaseURI, setDefaultNamespacePrefix, setIdAttributeNS, setKeySelector, setProperty, setURIDereferencer
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.xml.crypto.XMLCryptoContext
get, getBaseURI, getDefaultNamespacePrefix, getKeySelector, getNamespacePrefix, getProperty, getURIDereferencer, put, putNamespacePrefix, setBaseURI, setDefaultNamespacePrefix, setKeySelector, setProperty, setURIDereferencer

Constructor Detail

DOMSignContext

public DOMSignContext(Key signingKey,
                      Node parent)
Creates a DOMSignContext with the specified signing key and parent node. The signing key is stored in a singleton KeySelector that is returned by the getKeySelector method. The marshalled XMLSignature will be added as the last child element of the specified parent node unless a next sibling node is specified by invoking the setNextSibling method.

Parameters:
signingKey - the signing key
parent - the parent node
Throws:
NullPointerException - if signingKey or parent is null

DOMSignContext

public DOMSignContext(Key signingKey,
                      Node parent,
                      Node nextSibling)
Creates a DOMSignContext with the specified signing key, parent and next sibling nodes. The signing key is stored in a singleton KeySelector that is returned by the getKeySelector method. The marshalled XMLSignature will be inserted as a child element of the specified parent node and immediately before the specified next sibling node.

Parameters:
signingKey - the signing key
parent - the parent node
nextSibling - the next sibling node
Throws:
NullPointerException - if signingKey, parent or nextSibling is null

DOMSignContext

public DOMSignContext(KeySelector ks,
                      Node parent)
Creates a DOMSignContext with the specified key selector and parent node. The marshalled XMLSignature will be added as the last child element of the specified parent node unless a next sibling node is specified by invoking the setNextSibling method.

Parameters:
ks - the key selector
parent - the parent node
Throws:
NullPointerException - if ks or parent is null

DOMSignContext

public DOMSignContext(KeySelector ks,
                      Node parent,
                      Node nextSibling)
Creates a DOMSignContext with the specified key selector, parent and next sibling nodes. The marshalled XMLSignature will be inserted as a child element of the specified parent node and immediately before the specified next sibling node.

Parameters:
ks - the key selector
parent - the parent node
nextSibling - the next sibling node
Throws:
NullPointerException - if ks, parent or nextSibling is null
Method Detail

setParent

public void setParent(Node parent)
Sets the parent node.

Parameters:
parent - the parent node. The marshalled XMLSignature will be added as a child element of this node.
Throws:
NullPointerException - if parent is null
See Also:
getParent()

setNextSibling

public void setNextSibling(Node nextSibling)
Sets the next sibling node.

Parameters:
nextSibling - the next sibling node. The marshalled XMLSignature will be inserted immediately before this node. Specify null to remove the current setting.
See Also:
getNextSibling()

getParent

public Node getParent()
Returns the parent node.

Returns:
the parent node (never null)
See Also:
setParent(Node)

getNextSibling

public Node getNextSibling()
Returns the nextSibling node.

Returns:
the nextSibling node, or null if not specified.
See Also:
setNextSibling(Node)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


DOMValidateContext

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.dom
Class DOMValidateContext

java.lang.Object
    extended by  javax.xml.crypto.dom.DOMCryptoContext
        extended by  javax.xml.crypto.dsig.dom.DOMValidateContext
All Implemented Interfaces:
XMLValidateContext, XMLCryptoContext
public class DOMValidateContext
extends DOMCryptoContext
implements XMLValidateContext

A DOM-specific XMLValidateContext. This class contains additional methods to specify the location in a DOM tree where an XMLSignature is to be unmarshalled and validated from.

Note that the behavior of an unmarshalled XMLSignature is undefined if the contents of the underlying DOM tree are modified by the caller after the XMLSignature is created.

Also, note that DOMValidateContext instances can contain information and state specific to the XML signature structure it is used with. The results are unpredictable if a DOMValidateContext is used with different signature structures (for example, you should not use the same DOMValidateContext instance to validate two different XMLSignature objects).

Since:
1.6
See Also:
XMLSignatureFactory.unmarshalXMLSignature(XMLValidateContext)

Constructor Summary
DOMValidateContext(Key validatingKey, Node node)
Creates a DOMValidateContext containing the specified key and node.
DOMValidateContext(KeySelector ks, Node node)
Creates a DOMValidateContext containing the specified key selector and node.
Method Summary
Node | getNode() Returns the node.
void | setNode(Node node) Sets the node.
Methods inherited from class javax.xml.crypto.dom.DOMCryptoContext
get, getBaseURI, getDefaultNamespacePrefix, getElementById, getKeySelector, getNamespacePrefix, getProperty, getURIDereferencer, iterator, put, putNamespacePrefix, setBaseURI, setDefaultNamespacePrefix, setIdAttributeNS, setKeySelector, setProperty, setURIDereferencer
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.xml.crypto.XMLCryptoContext
get, getBaseURI, getDefaultNamespacePrefix, getKeySelector, getNamespacePrefix, getProperty, getURIDereferencer, put, putNamespacePrefix, setBaseURI, setDefaultNamespacePrefix, setKeySelector, setProperty, setURIDereferencer

Constructor Detail

DOMValidateContext

public DOMValidateContext(KeySelector ks,
                          Node node)
Creates a DOMValidateContext containing the specified key selector and node.

Parameters:
ks - a key selector for finding a validation key
node - the node
Throws:
NullPointerException - if ks or node is null

DOMValidateContext

public DOMValidateContext(Key validatingKey,
                          Node node)
Creates a DOMValidateContext containing the specified key and node. The validating key will be stored in a singleton KeySelector that is returned when the getKeySelector method is called.

Parameters:
validatingKey - the validating key
node - the node
Throws:
NullPointerException - if validatingKey or node is null
Method Detail

setNode

public void setNode(Node node)
Sets the node.

Parameters:
node - the node
Throws:
NullPointerException - if node is null
See Also:
getNode()

getNode

public Node getNode()
Returns the node.

Returns:
the node (never null)
See Also:
setNode(Node)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


keyinfo

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.crypto.dsig.keyinfo

Classes for parsing and processing KeyInfo elements and structures.

See:
Description

Interface Summary
KeyInfo | A representation of the XML KeyInfo element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
KeyName | A representation of the XML KeyName element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
KeyValue | A representation of the XML KeyValue element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
PGPData | A representation of the XML PGPData element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
RetrievalMethod | A representation of the XML RetrievalMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
X509Data | A representation of the XML X509Data element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
X509IssuerSerial | A representation of the XML X509IssuerSerial element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.

Class Summary
KeyInfoFactory A factory for creating KeyInfo objects from scratch or for unmarshalling a KeyInfo object from a corresponding XML representation.

Package javax.xml.crypto.dsig.keyinfo Description

Classes for parsing and processing KeyInfo elements and structures. KeyInfo is an optional element that enables the recipient(s) to obtain the key needed to validate an XMLSignature. KeyInfo may contain keys, names, certificates and other public key management information, such as in-band key distribution or key agreement data. This package contains classes representing types defined in the W3C specification for XML Signatures, such as KeyName, KeyValue, RetrievalMethod, X509Data, X509IssuerSerial, and PGPData. KeyInfoFactory is an abstract factory that creates KeyInfo objects from scratch.

Package Specification

  • XML-Signature Syntax and Processing: W3C Recommendation
  • RFC 3275: XML-Signature Syntax and Processing

Since:
1.6

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.crypto.dsig.keyinfo Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.crypto.dsig.keyinfo

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.crypto.dsig.keyinfo.KeyInfoFactory

Interface Hierarchy

  • javax.xml.crypto.URIReference
    • javax.xml.crypto.dsig.keyinfo.RetrievalMethod (also extends javax.xml.crypto.XMLStructure)
  • javax.xml.crypto.XMLStructure
    • javax.xml.crypto.dsig.keyinfo.KeyInfo
    • javax.xml.crypto.dsig.keyinfo.KeyName
    • javax.xml.crypto.dsig.keyinfo.KeyValue
    • javax.xml.crypto.dsig.keyinfo.PGPData
    • javax.xml.crypto.dsig.keyinfo.RetrievalMethod (also extends javax.xml.crypto.URIReference)
    • javax.xml.crypto.dsig.keyinfo.X509Data
    • javax.xml.crypto.dsig.keyinfo.X509IssuerSerial
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.crypto.dsig.keyinfo

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.crypto.dsig.keyinfo

Packages that use javax.xml.crypto.dsig.keyinfo
javax.xml.crypto | Common classes for XML cryptography.
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.keyinfo | Classes for parsing and processing KeyInfo elements and structures.

Classes in javax.xml.crypto.dsig.keyinfo used by javax.xml.crypto
KeyInfo
A representation of the XML KeyInfo element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.

Classes in javax.xml.crypto.dsig.keyinfo used by javax.xml.crypto.dsig
KeyInfo
A representation of the XML KeyInfo element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
KeyInfoFactory
A factory for creating KeyInfo objects from scratch or for unmarshalling a KeyInfo object from a corresponding XML representation.

Classes in javax.xml.crypto.dsig.keyinfo used by javax.xml.crypto.dsig.keyinfo
KeyInfo
A representation of the XML KeyInfo element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
KeyInfoFactory
A factory for creating KeyInfo objects from scratch or for unmarshalling a KeyInfo object from a corresponding XML representation.
KeyName
A representation of the XML KeyName element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
KeyValue
A representation of the XML KeyValue element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
PGPData
A representation of the XML PGPData element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
RetrievalMethod
A representation of the XML RetrievalMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
X509Data
A representation of the XML X509Data element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
X509IssuerSerial
A representation of the XML X509IssuerSerial element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.dsig.keyinfo.KeyInfoFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.dsig.keyinfo.KeyInfoFactory

Packages that use KeyInfoFactory
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.keyinfo | Classes for parsing and processing KeyInfo elements and structures.

Uses of KeyInfoFactory in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return KeyInfoFactory
 KeyInfoFactory XMLSignatureFactory.getKeyInfoFactory()
Returns a KeyInfoFactory that creates KeyInfo objects.

Uses of KeyInfoFactory in javax.xml.crypto.dsig.keyinfo

Methods in javax.xml.crypto.dsig.keyinfo that return KeyInfoFactory
static KeyInfoFactory | KeyInfoFactory.getInstance() Returns a KeyInfoFactory that supports the default XML processing mechanism and representation type ("DOM").
static KeyInfoFactory | KeyInfoFactory.getInstance(String mechanismType) Returns a KeyInfoFactory that supports the specified XML processing mechanism and representation type (ex: "DOM").
static KeyInfoFactory | KeyInfoFactory.getInstance(String mechanismType, Provider provider) Returns a KeyInfoFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.
static KeyInfoFactory | KeyInfoFactory.getInstance(String mechanismType, String provider) Returns a KeyInfoFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.keyinfo.KeyInfo

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.keyinfo.KeyInfo

Packages that use KeyInfo
javax.xml.crypto | Common classes for XML cryptography.
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.keyinfo | Classes for parsing and processing KeyInfo elements and structures.

Uses of KeyInfo in javax.xml.crypto

Methods in javax.xml.crypto with parameters of type KeyInfo
abstract  KeySelectorResult KeySelector.select(KeyInfo keyInfo, KeySelector.Purpose purpose, AlgorithmMethod method, XMLCryptoContext context)
Attempts to find a key that satisfies the specified constraints.

Uses of KeyInfo in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig that return KeyInfo
 KeyInfo XMLSignature.getKeyInfo()
Returns the key info of this XMLSignature.

Methods in javax.xml.crypto.dsig with parameters of type KeyInfo
abstract XMLSignature | XMLSignatureFactory.newXMLSignature(SignedInfo si, KeyInfo ki) Creates an XMLSignature and initializes it with the contents of the specified SignedInfo and KeyInfo objects.
abstract XMLSignature | XMLSignatureFactory.newXMLSignature(SignedInfo si, KeyInfo ki, List objects, String id, String signatureValueId) Creates an XMLSignature and initializes it with the specified parameters.

Uses of KeyInfo in javax.xml.crypto.dsig.keyinfo

Methods in javax.xml.crypto.dsig.keyinfo that return KeyInfo
abstract KeyInfo | KeyInfoFactory.newKeyInfo(List content) Creates a KeyInfo containing the specified list of key information types.
abstract KeyInfo | KeyInfoFactory.newKeyInfo(List content, String id) Creates a KeyInfo containing the specified list of key information types and optional id.
abstract KeyInfo | KeyInfoFactory.unmarshalKeyInfo(XMLStructure xmlStructure) Unmarshals a new KeyInfo instance from a mechanism-specific XMLStructure (ex: DOMStructure) instance.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.keyinfo.KeyName

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.keyinfo.KeyName

Packages that use KeyName
javax.xml.crypto.dsig.keyinfo Classes for parsing and processing KeyInfo elements and structures.

Uses of KeyName in javax.xml.crypto.dsig.keyinfo

Methods in javax.xml.crypto.dsig.keyinfo that return KeyName
abstract  KeyName KeyInfoFactory.newKeyName(String name)
Creates a KeyName from the specified name.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.keyinfo.KeyValue

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.keyinfo.KeyValue

Packages that use KeyValue
javax.xml.crypto.dsig.keyinfo Classes for parsing and processing KeyInfo elements and structures.

Uses of KeyValue in javax.xml.crypto.dsig.keyinfo

Methods in javax.xml.crypto.dsig.keyinfo that return KeyValue
abstract  KeyValue KeyInfoFactory.newKeyValue(PublicKey key)
Creates a KeyValue from the specified public key.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.keyinfo.PGPData

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.keyinfo.PGPData

Packages that use PGPData
javax.xml.crypto.dsig.keyinfo Classes for parsing and processing KeyInfo elements and structures.

Uses of PGPData in javax.xml.crypto.dsig.keyinfo

Methods in javax.xml.crypto.dsig.keyinfo that return PGPData
abstract PGPData | KeyInfoFactory.newPGPData(byte[] keyId) Creates a PGPData from the specified PGP public key identifier.
abstract PGPData | KeyInfoFactory.newPGPData(byte[] keyId, byte[] keyPacket, List other) Creates a PGPData from the specified PGP public key identifier, and optional key material packet and list of external elements.
abstract PGPData | KeyInfoFactory.newPGPData(byte[] keyPacket, List other) Creates a PGPData from the specified PGP key material packet and optional list of external elements.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.keyinfo.RetrievalMethod

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.keyinfo.RetrievalMethod

Packages that use RetrievalMethod
javax.xml.crypto.dsig.keyinfo Classes for parsing and processing KeyInfo elements and structures.

Uses of RetrievalMethod in javax.xml.crypto.dsig.keyinfo

Methods in javax.xml.crypto.dsig.keyinfo that return RetrievalMethod
abstract RetrievalMethod | KeyInfoFactory.newRetrievalMethod(String uri) Creates a RetrievalMethod from the specified URI.
abstract RetrievalMethod | KeyInfoFactory.newRetrievalMethod(String uri, String type, List transforms) Creates a RetrievalMethod from the specified parameters.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.keyinfo.X509Data

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.keyinfo.X509Data

Packages that use X509Data
javax.xml.crypto.dsig.keyinfo Classes for parsing and processing KeyInfo elements and structures.

Uses of X509Data in javax.xml.crypto.dsig.keyinfo

Methods in javax.xml.crypto.dsig.keyinfo that return X509Data
abstract  X509Data KeyInfoFactory.newX509Data(List content)
Creates a X509Data containing the specified list of X.509 content.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.keyinfo.X509IssuerSerial

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.keyinfo.X509IssuerSerial

Packages that use X509IssuerSerial
javax.xml.crypto.dsig.keyinfo Classes for parsing and processing KeyInfo elements and structures.

Uses of X509IssuerSerial in javax.xml.crypto.dsig.keyinfo

Methods in javax.xml.crypto.dsig.keyinfo that return X509IssuerSerial
abstract  X509IssuerSerial KeyInfoFactory.newX509IssuerSerial(String issuerName, BigInteger serialNumber)
Creates an X509IssuerSerial from the specified X.500 issuer distinguished name and serial number.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


KeyInfo

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.keyinfo
Interface KeyInfo

All Superinterfaces:
XMLStructure
public interface KeyInfo
extends XMLStructure

A representation of the XML KeyInfo element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. A KeyInfo contains a list of XMLStructures, each of which contain information that enables the recipient(s) to obtain the key needed to validate an XML signature. The XML Schema Definition is defined as:

 <element name="KeyInfo" type="ds:KeyInfoType"/>
 <complexType name="KeyInfoType" mixed="true">
   <choice maxOccurs="unbounded">
     <element ref="ds:KeyName"/>
     <element ref="ds:KeyValue"/>
     <element ref="ds:RetrievalMethod"/>
     <element ref="ds:X509Data"/>
     <element ref="ds:PGPData"/>
     <element ref="ds:SPKIData"/>
     <element ref="ds:MgmtData"/>
     <any processContents="lax" namespace="##other"/>
     <!-- (1,1) elements from (0,unbounded) namespaces -->
   </choice>
   <attribute name="Id" type="ID" use="optional"/>
 </complexType>
A KeyInfo instance may be created by invoking one of the newKeyInfo methods of the KeyInfoFactory class, and passing it a list of one or more XMLStructures and an optional id parameter; for example:
   KeyInfoFactory factory = KeyInfoFactory.getInstance("DOM");
   KeyInfo keyInfo = factory.newKeyInfo
        (Collections.singletonList(factory.newKeyName("Alice"), "keyinfo-1"));

KeyInfo objects can also be marshalled to XML by invoking the marshal method.

Since:
1.6
See Also:
KeyInfoFactory.newKeyInfo(List), KeyInfoFactory.newKeyInfo(List, String)

Method Summary
List | getContent() Returns an unmodifiable list containing the key information.
String | getId() Return the optional Id attribute of this KeyInfo, which may be useful for referencing this KeyInfo from other XML structures.
void | marshal(XMLStructure parent, XMLCryptoContext context) Marshals the key info to XML.
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported

Method Detail

getContent

List getContent()
Returns an unmodifiable list containing the key information. Each entry of the list is an XMLStructure.

If there is a public subclass representing the type of XMLStructure, it is returned as an instance of that class (ex: an X509Data element would be returned as an instance of X509Data).

Returns:
an unmodifiable list of one or more XMLStructures in this KeyInfo. Never returns null or an empty list.

getId

String getId()
Return the optional Id attribute of this KeyInfo, which may be useful for referencing this KeyInfo from other XML structures.

Returns:
the Id attribute of this KeyInfo (may be null if not specified)

marshal

void marshal(XMLStructure parent,
             XMLCryptoContext context)
             throws MarshalException
Marshals the key info to XML.

Parameters:
parent - a mechanism-specific structure containing the parent node that the marshalled key info will be appended to
context - the XMLCryptoContext containing additional context (may be null if not applicable)
Throws:
ClassCastException - if the type of parent or context is not compatible with this key info
MarshalException - if the key info cannot be marshalled
NullPointerException - if parent is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


KeyInfoFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.keyinfo
Class KeyInfoFactory

java.lang.Object
    extended by  javax.xml.crypto.dsig.keyinfo.KeyInfoFactory

public abstract class KeyInfoFactory
extends Object

A factory for creating KeyInfo objects from scratch or for unmarshalling a KeyInfo object from a corresponding XML representation.

Each instance of KeyInfoFactory supports a specific XML mechanism type. To create a KeyInfoFactory, call one of the static getInstance methods, passing in the XML mechanism type desired, for example:

KeyInfoFactory factory = KeyInfoFactory.getInstance("DOM");

The objects that this factory produces will be based on DOM and abide by the DOM interoperability requirements as defined in the DOM Mechanism Requirements section of the API overview. See the Service Providers section of the API overview for a list of standard mechanism types.

KeyInfoFactory implementations are registered and loaded using the Provider mechanism. For example, a service provider that supports the DOM mechanism would be specified in the Provider subclass as:

     put("KeyInfoFactory.DOM", "org.example.DOMKeyInfoFactory");

Also, the XMLStructures that are created by this factory may contain state specific to the KeyInfo and are not intended to be reusable.

An implementation MUST minimally support the default mechanism type: DOM.

Note that a caller must use the same KeyInfoFactory instance to create the XMLStructures of a particular KeyInfo object. The behavior is undefined if XMLStructures from different providers or different mechanism types are used together.

Concurrent Access

The static methods of this class are guaranteed to be thread-safe. Multiple threads may concurrently invoke the static methods defined in this class with no ill effects.

However, this is not true for the non-static methods defined by this class. Unless otherwise documented by a specific provider, threads that need to access a single KeyInfoFactory instance concurrently should synchronize amongst themselves and provide the necessary locking. Multiple threads each manipulating a different KeyInfoFactory instance need not synchronize.

Since:
1.6

Constructor Summary
protected KeyInfoFactory()
Default constructor, for invocation by subclasses.
Method Summary
static KeyInfoFactory | getInstance() Returns a KeyInfoFactory that supports the default XML processing mechanism and representation type ("DOM").
static KeyInfoFactory | getInstance(String mechanismType) Returns a KeyInfoFactory that supports the specified XML processing mechanism and representation type (ex: "DOM").
static KeyInfoFactory | getInstance(String mechanismType, Provider provider) Returns a KeyInfoFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.
static KeyInfoFactory | getInstance(String mechanismType, String provider) Returns a KeyInfoFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.
String | getMechanismType() Returns the type of the XML processing mechanism and representation supported by this KeyInfoFactory (ex: "DOM")
Provider | getProvider() Returns the provider of this KeyInfoFactory.
abstract URIDereferencer | getURIDereferencer() Returns a reference to the URIDereferencer that is used by default to dereference URIs in RetrievalMethod objects.
abstract boolean | isFeatureSupported(String feature) Indicates whether a specified feature is supported.
abstract KeyInfo | newKeyInfo(List content) Creates a KeyInfo containing the specified list of key information types.
abstract KeyInfo | newKeyInfo(List content, String id) Creates a KeyInfo containing the specified list of key information types and optional id.
abstract KeyName | newKeyName(String name) Creates a KeyName from the specified name.
abstract KeyValue | newKeyValue(PublicKey key) Creates a KeyValue from the specified public key.
abstract PGPData | newPGPData(byte[] keyId) Creates a PGPData from the specified PGP public key identifier.
abstract PGPData | newPGPData(byte[] keyId, byte[] keyPacket, List other) Creates a PGPData from the specified PGP public key identifier, and optional key material packet and list of external elements.
abstract PGPData | newPGPData(byte[] keyPacket, List other) Creates a PGPData from the specified PGP key material packet and optional list of external elements.
abstract RetrievalMethod | newRetrievalMethod(String uri) Creates a RetrievalMethod from the specified URI.
abstract RetrievalMethod | newRetrievalMethod(String uri, String type, List transforms) Creates a RetrievalMethod from the specified parameters.
abstract X509Data | newX509Data(List content) Creates a X509Data containing the specified list of X.509 content.
abstract X509IssuerSerial | newX509IssuerSerial(String issuerName, BigInteger serialNumber) Creates an X509IssuerSerial from the specified X.500 issuer distinguished name and serial number.
abstract KeyInfo | unmarshalKeyInfo(XMLStructure xmlStructure) Unmarshals a new KeyInfo instance from a mechanism-specific XMLStructure (ex: DOMStructure) instance.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

KeyInfoFactory

protected KeyInfoFactory()
Default constructor, for invocation by subclasses.

Method Detail

getInstance

public static KeyInfoFactory getInstance(String mechanismType)
Returns a KeyInfoFactory that supports the specified XML processing mechanism and representation type (ex: "DOM").

This method uses the standard JCA provider lookup mechanism to locate and instantiate a KeyInfoFactory implementation of the desired mechanism type. It traverses the list of registered security Providers, starting with the most preferred Provider. A new KeyInfoFactory object from the first Provider that supports the specified mechanism is returned.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters:
mechanismType - the type of the XML processing mechanism and representation. See the Service Providers section of the API overview for a list of standard mechanism types.
Returns:
a new KeyInfoFactory
Throws:
NullPointerException - if mechanismType is null
NoSuchMechanismException - if no Provider supports a KeyInfoFactory implementation for the specified mechanism
See Also:
Provider

getInstance

public static KeyInfoFactory getInstance(String mechanismType,
                                         Provider provider)
Returns a KeyInfoFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider. Note that the specified Provider object does not have to be registered in the provider list.

Parameters:
mechanismType - the type of the XML processing mechanism and representation. See the Service Providers section of the API overview for a list of standard mechanism types.
provider - the Provider object
Returns:
a new KeyInfoFactory
Throws:
NullPointerException - if mechanismType or provider are null
NoSuchMechanismException - if a KeyInfoFactory implementation for the specified mechanism is not available from the specified Provider object
See Also:
Provider

getInstance

public static KeyInfoFactory getInstance(String mechanismType,
                                         String provider)
                                  throws NoSuchProviderException
Returns a KeyInfoFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider. The specified provider must be registered in the security provider list.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters:
mechanismType - the type of the XML processing mechanism and representation. See the Service Providers section of the API overview for a list of standard mechanism types.
provider - the string name of the provider
Returns:
a new KeyInfoFactory
Throws:
NoSuchProviderException - if the specified provider is not registered in the security provider list
NullPointerException - if mechanismType or provider are null
NoSuchMechanismException - if a KeyInfoFactory implementation for the specified mechanism is not available from the specified provider
See Also:
Provider

getInstance

public static KeyInfoFactory getInstance()
Returns a KeyInfoFactory that supports the default XML processing mechanism and representation type ("DOM").

This method uses the standard JCA provider lookup mechanism to locate and instantiate a KeyInfoFactory implementation of the default mechanism type. It traverses the list of registered security Providers, starting with the most preferred Provider. A new KeyInfoFactory object from the first Provider that supports the DOM mechanism is returned.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Returns:
a new KeyInfoFactory
Throws:
NoSuchMechanismException - if no Provider supports a KeyInfoFactory implementation for the DOM mechanism
See Also:
Provider

getMechanismType

public final String getMechanismType()
Returns the type of the XML processing mechanism and representation supported by this KeyInfoFactory (ex: "DOM")

Returns:
the XML processing mechanism type supported by this KeyInfoFactory

getProvider

public final Provider getProvider()
Returns the provider of this KeyInfoFactory.

Returns:
the provider of this KeyInfoFactory

newKeyInfo

public abstract KeyInfo newKeyInfo(List content)
Creates a KeyInfo containing the specified list of key information types.

Parameters:
content - a list of one or more XMLStructures representing key information types. The list is defensively copied to protect against subsequent modification.
Returns:
a KeyInfo
Throws:
NullPointerException - if content is null
IllegalArgumentException - if content is empty
ClassCastException - if content contains any entries that are not of type XMLStructure

newKeyInfo

public abstract KeyInfo newKeyInfo(List content,
                                   String id)
Creates a KeyInfo containing the specified list of key information types and optional id. The id parameter represents the value of an XML ID attribute and is useful for referencing the KeyInfo from other XML structures.

Parameters:
content - a list of one or more XMLStructures representing key information types. The list is defensively copied to protect against subsequent modification.
id - the value of an XML ID (may be null)
Returns:
a KeyInfo
Throws:
NullPointerException - if content is null
IllegalArgumentException - if content is empty
ClassCastException - if content contains any entries that are not of type XMLStructure

newKeyName

public abstract KeyName newKeyName(String name)
Creates a KeyName from the specified name.

Parameters:
name - the name that identifies the key
Returns:
a KeyName
Throws:
NullPointerException - if name is null

newKeyValue

public abstract KeyValue newKeyValue(PublicKey key)
                              throws KeyException
Creates a KeyValue from the specified public key.

Parameters:
key - the public key
Returns:
a KeyValue
Throws:
KeyException - if the key's algorithm is not recognized or supported by this KeyInfoFactory
NullPointerException - if key is null

newPGPData

public abstract PGPData newPGPData(byte[] keyId)
Creates a PGPData from the specified PGP public key identifier.

Parameters:
keyId - a PGP public key identifier as defined in RFC 2440, section 11.2. The array is cloned to protect against subsequent modification.
Returns:
a PGPData
Throws:
NullPointerException - if keyId is null
IllegalArgumentException - if the key id is not in the correct format

newPGPData

public abstract PGPData newPGPData(byte[] keyId,
                                   byte[] keyPacket,
                                   List other)
Creates a PGPData from the specified PGP public key identifier, and optional key material packet and list of external elements.

Parameters:
keyId - a PGP public key identifier as defined in RFC 2440, section 11.2. The array is cloned to protect against subsequent modification.
keyPacket - a PGP key material packet as defined in RFC 2440, section 5.5. The array is cloned to protect against subsequent modification. May be null.
other - a list of XMLStructures representing elements from an external namespace. The list is defensively copied to protect against subsequent modification. May be null or empty.
Returns:
a PGPData
Throws:
NullPointerException - if keyId is null
IllegalArgumentException - if the keyId or keyPacket is not in the correct format. For keyPacket, the format of the packet header is checked and the tag is verified that it is of type key material. The contents and format of the packet body are not checked.
ClassCastException - if other contains any entries that are not of type XMLStructure

newPGPData

public abstract PGPData newPGPData(byte[] keyPacket,
                                   List other)
Creates a PGPData from the specified PGP key material packet and optional list of external elements.

Parameters:
keyPacket - a PGP key material packet as defined in RFC 2440, section 5.5. The array is cloned to protect against subsequent modification.
other - a list of XMLStructures representing elements from an external namespace. The list is defensively copied to protect against subsequent modification. May be null or empty.
Returns:
a PGPData
Throws:
NullPointerException - if keyPacket is null
IllegalArgumentException - if keyPacket is not in the correct format. For keyPacket, the format of the packet header is checked and the tag is verified that it is of type key material. The contents and format of the packet body are not checked.
ClassCastException - if other contains any entries that are not of type XMLStructure

newRetrievalMethod

public abstract RetrievalMethod newRetrievalMethod(String uri)
Creates a RetrievalMethod from the specified URI.

Parameters:
uri - the URI that identifies the KeyInfo information to be retrieved
Returns:
a RetrievalMethod
Throws:
NullPointerException - if uri is null
IllegalArgumentException - if uri is not RFC 2396 compliant

newRetrievalMethod

public abstract RetrievalMethod newRetrievalMethod(String uri,
                                                   String type,
                                                   List transforms)
Creates a RetrievalMethod from the specified parameters.

Parameters:
uri - the URI that identifies the KeyInfo information to be retrieved
type - a URI that identifies the type of KeyInfo information to be retrieved (may be null)
transforms - a list of Transforms. The list is defensively copied to protect against subsequent modification. May be null or empty.
Returns:
a RetrievalMethod
Throws:
NullPointerException - if uri is null
IllegalArgumentException - if uri is not RFC 2396 compliant
ClassCastException - if transforms contains any entries that are not of type Transform

newX509Data

public abstract X509Data newX509Data(List content)
Creates a X509Data containing the specified list of X.509 content.

Parameters:
content - a list of one or more X.509 content types. Valid types are String (subject names), byte[] (subject key ids), X509Certificate, X509CRL, or XMLStructure (X509IssuerSerial objects or elements from an external namespace). Subject names are distinguished names in RFC 2253 String format. Implementations MUST support the attribute type keywords defined in RFC 2253 (CN, L, ST, O, OU, C, STREET, DC and UID). Implementations MAY support additional keywords. The list is defensively copied to protect against subsequent modification.
Returns:
a X509Data
Throws:
NullPointerException - if content is null
IllegalArgumentException - if content is empty, or if a subject name is not RFC 2253 compliant or one of the attribute type keywords is not recognized.
ClassCastException - if content contains any entries that are not of one of the valid types mentioned above

newX509IssuerSerial

public abstract X509IssuerSerial newX509IssuerSerial(String issuerName,
                                                     BigInteger serialNumber)
Creates an X509IssuerSerial from the specified X.500 issuer distinguished name and serial number.

Parameters:
issuerName - the issuer's distinguished name in RFC 2253 String format. Implementations MUST support the attribute type keywords defined in RFC 2253 (CN, L, ST, O, OU, C, STREET, DC and UID). Implementations MAY support additional keywords.
serialNumber - the serial number
Returns:
an X509IssuerSerial
Throws:
NullPointerException - if issuerName or serialNumber are null
IllegalArgumentException - if the issuer name is not RFC 2253 compliant or one of the attribute type keywords is not recognized.

isFeatureSupported

public abstract boolean isFeatureSupported(String feature)
Indicates whether a specified feature is supported.

Parameters:
feature - the feature name (as an absolute URI)
Returns:
true if the specified feature is supported, false otherwise
Throws:
NullPointerException - if feature is null

getURIDereferencer

public abstract URIDereferencer getURIDereferencer()
Returns a reference to the URIDereferencer that is used by default to dereference URIs in RetrievalMethod objects.

Returns:
a reference to the default URIDereferencer

unmarshalKeyInfo

public abstract KeyInfo unmarshalKeyInfo(XMLStructure xmlStructure)
                                  throws MarshalException
Unmarshals a new KeyInfo instance from a mechanism-specific XMLStructure (ex: DOMStructure) instance.

Parameters:
xmlStructure - a mechanism-specific XML structure from which to unmarshal the keyinfo from
Returns:
the KeyInfo
Throws:
NullPointerException - if xmlStructure is null
ClassCastException - if the type of xmlStructure is inappropriate for this factory
MarshalException - if an unrecoverable exception occurs during unmarshalling
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


KeyName

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.keyinfo
Interface KeyName

All Superinterfaces:
XMLStructure
public interface KeyName
extends XMLStructure

A representation of the XML KeyName element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. A KeyName object contains a string value which may be used by the signer to communicate a key identifier to the recipient. The XML Schema Definition is defined as:

 <element name="KeyName" type="string"/>
A KeyName instance may be created by invoking the newKeyName method of the KeyInfoFactory class, and passing it a String representing the name of the key; for example:
 KeyInfoFactory factory = KeyInfoFactory.getInstance("DOM");
 KeyName keyName = factory.newKeyName("Alice");

Since:
1.6
See Also:
KeyInfoFactory.newKeyName(String)

Method Summary
 String getName()
Returns the name of this KeyName.
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported

Method Detail

getName

String getName()
Returns the name of this KeyName.

Returns:
the name of this KeyName (never null)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


KeyValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.keyinfo
Interface KeyValue

All Superinterfaces:
XMLStructure
public interface KeyValue
extends XMLStructure

A representation of the XML KeyValue element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. A KeyValue object contains a single public key that may be useful in validating the signature. The XML schema definition is defined as:

    <element name="KeyValue" type="ds:KeyValueType"/>
    <complexType name="KeyValueType" mixed="true">
      <choice>
        <element ref="ds:DSAKeyValue"/>
        <element ref="ds:RSAKeyValue"/>
        <any namespace="##other" processContents="lax"/>
      </choice>
    </complexType>

    <element name="DSAKeyValue" type="ds:DSAKeyValueType"/>
    <complexType name="DSAKeyValueType">
      <sequence>
        <sequence minOccurs="0">
          <element name="P" type="ds:CryptoBinary"/>
          <element name="Q" type="ds:CryptoBinary"/>
        </sequence>
        <element name="G" type="ds:CryptoBinary" minOccurs="0"/>
        <element name="Y" type="ds:CryptoBinary"/>
        <element name="J" type="ds:CryptoBinary" minOccurs="0"/>
        <sequence minOccurs="0">
          <element name="Seed" type="ds:CryptoBinary"/>
          <element name="PgenCounter" type="ds:CryptoBinary"/>
        </sequence>
      </sequence>
    </complexType>

    <element name="RSAKeyValue" type="ds:RSAKeyValueType"/>
    <complexType name="RSAKeyValueType">
      <sequence>
        <element name="Modulus" type="ds:CryptoBinary"/>
        <element name="Exponent" type="ds:CryptoBinary"/>
      </sequence>
    </complexType>
A KeyValue instance may be created by invoking the newKeyValue method of the KeyInfoFactory class, and passing it a PublicKey representing the value of the public key. Here is an example of creating a KeyValue from a DSAPublicKey of a Certificate stored in a KeyStore:
 KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());
 PublicKey dsaPublicKey = keyStore.getCertificate("myDSASigningCert").getPublicKey();
 KeyInfoFactory factory = KeyInfoFactory.getInstance("DOM");
 KeyValue keyValue = factory.newKeyValue(dsaPublicKey);
This class returns the DSAKeyValue and RSAKeyValue elements as objects of type DSAPublicKey and RSAPublicKey, respectively. Note that not all of the fields in the schema are accessible as parameters of these types.

Since:
1.6
See Also:
KeyInfoFactory.newKeyValue(PublicKey)

Field Summary
static String | DSA_TYPE URI identifying the DSA KeyValue KeyInfo type: http://www.w3.org/2000/09/xmldsig#DSAKeyValue.
static String | RSA_TYPE URI identifying the RSA KeyValue KeyInfo type: http://www.w3.org/2000/09/xmldsig#RSAKeyValue.
Method Summary
 PublicKey getPublicKey()
Returns the public key of this KeyValue.
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported

Field Detail

DSA_TYPE

static final String DSA_TYPE
URI identifying the DSA KeyValue KeyInfo type: http://www.w3.org/2000/09/xmldsig#DSAKeyValue. This can be specified as the value of the type parameter of the RetrievalMethod class to describe a remote DSAKeyValue structure.

See Also:
Constant Field Values

RSA_TYPE

static final String RSA_TYPE
URI identifying the RSA KeyValue KeyInfo type: http://www.w3.org/2000/09/xmldsig#RSAKeyValue. This can be specified as the value of the type parameter of the RetrievalMethod class to describe a remote RSAKeyValue structure.

See Also:
Constant Field Values
Method Detail

getPublicKey

PublicKey getPublicKey()
                       throws KeyException
Returns the public key of this KeyValue.

Returns:
the public key of this KeyValue
Throws:
KeyException - if this KeyValue cannot be converted to a PublicKey
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PGPData

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.keyinfo
Interface PGPData

All Superinterfaces:
XMLStructure
public interface PGPData
extends XMLStructure

A representation of the XML PGPData element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. A PGPData object is used to convey information related to PGP public key pairs and signatures on such keys. The XML Schema Definition is defined as:

    <element name="PGPData" type="ds:PGPDataType"/>
    <complexType name="PGPDataType">
      <choice>
        <sequence>
          <element name="PGPKeyID" type="base64Binary"/>
          <element name="PGPKeyPacket" type="base64Binary" minOccurs="0"/>
          <any namespace="##other" processContents="lax" minOccurs="0"
           maxOccurs="unbounded"/>
        </sequence>
        <sequence>
          <element name="PGPKeyPacket" type="base64Binary"/>
          <any namespace="##other" processContents="lax" minOccurs="0"
           maxOccurs="unbounded"/>
        </sequence>
      </choice>
    </complexType>
A PGPData instance may be created by invoking one of the newPGPData methods of the KeyInfoFactory class, and passing it byte arrays representing the contents of the PGP public key identifier and/or PGP key material packet, and an optional list of elements from an external namespace.

Since:
1.6
See Also:
KeyInfoFactory.newPGPData(byte[]),
KeyInfoFactory.newPGPData(byte[], byte[], List),
KeyInfoFactory.newPGPData(byte[], List)

Field Summary
static String TYPE
URI identifying the PGPData KeyInfo type: http://www.w3.org/2000/09/xmldsig#PGPData.
Method Summary
List | getExternalElements() Returns an unmodifiable list of XMLStructures representing elements from an external namespace.
byte[] | getKeyId() Returns the PGP public key identifier of this PGPData as defined in RFC 2440, section 11.2.
byte[] | getKeyPacket() Returns the PGP key material packet of this PGPData as defined in RFC 2440, section 5.5.
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported

Field Detail

TYPE

static final String TYPE
URI identifying the PGPData KeyInfo type: http://www.w3.org/2000/09/xmldsig#PGPData. This can be specified as the value of the type parameter of the RetrievalMethod class to describe a remote PGPData structure.

See Also:
Constant Field Values
Method Detail

getKeyId

byte[] getKeyId()
Returns the PGP public key identifier of this PGPData as defined in RFC 2440, section 11.2.

Returns:
the PGP public key identifier (may be null if not specified). Each invocation of this method returns a new clone to protect against subsequent modification.

getKeyPacket

byte[] getKeyPacket()
Returns the PGP key material packet of this PGPData as defined in RFC 2440, section 5.5.

Returns:
the PGP key material packet (may be null if not specified). Each invocation of this method returns a new clone to protect against subsequent modification.

getExternalElements

List getExternalElements()
Returns an unmodifiable list of XMLStructures representing elements from an external namespace.

Returns:
an unmodifiable list of XMLStructures (may be empty, but never null)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RetrievalMethod

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.keyinfo
Interface RetrievalMethod

All Superinterfaces:
URIReference, XMLStructure
public interface RetrievalMethod
extends URIReference, XMLStructure

A representation of the XML RetrievalMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. A RetrievalMethod object is used to convey a reference to KeyInfo information that is stored at another location. The XML schema definition is defined as:

   <element name="RetrievalMethod" type="ds:RetrievalMethodType"/>
   <complexType name="RetrievalMethodType">
     <sequence>
       <element name="Transforms" type="ds:TransformsType" minOccurs="0"/>
     </sequence>
     <attribute name="URI" type="anyURI"/>
     <attribute name="Type" type="anyURI" use="optional"/>
   </complexType>
A RetrievalMethod instance may be created by invoking one of the newRetrievalMethod methods of the KeyInfoFactory class, and passing it the URI identifying the location of the KeyInfo, an optional type URI identifying the type of KeyInfo, and an optional list of Transforms; for example:
   KeyInfoFactory factory = KeyInfoFactory.getInstance("DOM");
   RetrievalMethod rm = factory.newRetrievalMethod
      ("#KeyValue-1", KeyValue.DSA_TYPE, Collections.singletonList(Transform.BASE64));

Since:
1.6
See Also:
KeyInfoFactory.newRetrievalMethod(String), KeyInfoFactory.newRetrievalMethod(String, String, List)

Method Summary
Data | dereference(XMLCryptoContext context) Dereferences the KeyInfo information referenced by this RetrievalMethod and applies the specified Transforms.
List | getTransforms() Returns an unmodifiable list of Transforms of this RetrievalMethod.
String | getURI() Returns the URI of the referenced KeyInfo information.
Methods inherited from interface javax.xml.crypto.URIReference
getType
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported

Method Detail

getTransforms

List getTransforms()
Returns an unmodifiable list of Transforms of this RetrievalMethod.

Returns:
an unmodifiable list of Transform objects (may be empty but never null).

getURI

String getURI()
Returns the URI of the referenced KeyInfo information.

Specified by:
getURI in interface URIReference
Returns:
the URI of the referenced KeyInfo information in RFC 2396 format (never null)

dereference

Data dereference(XMLCryptoContext context)
                 throws URIReferenceException
Dereferences the KeyInfo information referenced by this RetrievalMethod and applies the specified Transforms.

Parameters:
context - an XMLCryptoContext that may contain additional useful information for dereferencing the URI. The context's baseURI and dereferencer parameters (if specified) are used to resolve and dereference this RetrievalMethod
Returns:
a Data object representing the raw contents of the KeyInfo information referenced by this RetrievalMethod. It is the caller's responsibility to convert the returned data to an appropriate KeyInfo object.
Throws:
NullPointerException - if context is null
URIReferenceException - if there is an error while dereferencing
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


X509Data

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.keyinfo
Interface X509Data

All Superinterfaces:
XMLStructure
public interface X509Data
extends XMLStructure

A representation of the XML X509Data element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. An X509Data object contains one or more identifers of keys or X.509 certificates (or certificates' identifiers or a revocation list). The XML Schema Definition is defined as:

    <element name="X509Data" type="ds:X509DataType"/>
    <complexType name="X509DataType">
        <sequence maxOccurs="unbounded">
          <choice>
            <element name="X509IssuerSerial" type="ds:X509IssuerSerialType"/>
            <element name="X509SKI" type="base64Binary"/>
            <element name="X509SubjectName" type="string"/>
            <element name="X509Certificate" type="base64Binary"/>
            <element name="X509CRL" type="base64Binary"/>
            <any namespace="##other" processContents="lax"/>
          </choice>
        </sequence>
    </complexType>

    <complexType name="X509IssuerSerialType">
      <sequence>
        <element name="X509IssuerName" type="string"/>
        <element name="X509SerialNumber" type="integer"/>
      </sequence>
    </complexType>
An X509Data instance may be created by invoking the newX509Data methods of the KeyInfoFactory class and passing it a list of one or more XMLStructures representing X.509 content; for example:
   KeyInfoFactory factory = KeyInfoFactory.getInstance("DOM");
   X509Data x509Data = factory.newX509Data
       (Collections.singletonList("cn=Alice"));

Since:
1.6
See Also:
KeyInfoFactory.newX509Data(List)

Field Summary
static String | RAW_X509_CERTIFICATE_TYPE URI identifying the binary (ASN.1 DER) X.509 Certificate KeyInfo type: http://www.w3.org/2000/09/xmldsig#rawX509Certificate.
static String | TYPE URI identifying the X509Data KeyInfo type: http://www.w3.org/2000/09/xmldsig#X509Data.
Method Summary
 List getContent()
Returns an unmodifiable list of the content in this X509Data.
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported

Field Detail

TYPE

static final String TYPE
URI identifying the X509Data KeyInfo type: http://www.w3.org/2000/09/xmldsig#X509Data. This can be specified as the value of the type parameter of the RetrievalMethod class to describe a remote X509Data structure.

See Also:
Constant Field Values

RAW_X509_CERTIFICATE_TYPE

static final String RAW_X509_CERTIFICATE_TYPE
URI identifying the binary (ASN.1 DER) X.509 Certificate KeyInfo type: http://www.w3.org/2000/09/xmldsig#rawX509Certificate. This can be specified as the value of the type parameter of the RetrievalMethod class to describe a remote X509 Certificate.

See Also:
Constant Field Values
Method Detail

getContent

List getContent()
Returns an unmodifiable list of the content in this X509Data. Valid types are String (subject names), byte[] (subject key ids), X509Certificate, X509CRL, or XMLStructure (X509IssuerSerial objects or elements from an external namespace).

Returns:
an unmodifiable list of the content in this X509Data (never null or empty)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


X509IssuerSerial

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.keyinfo
Interface X509IssuerSerial

All Superinterfaces:
XMLStructure
public interface X509IssuerSerial
extends XMLStructure

A representation of the XML X509IssuerSerial element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. An X509IssuerSerial object contains an X.509 issuer distinguished name (DN) and serial number pair. The XML schema definition is defined as:

   <element name="X509IssuerSerial" type="ds:X509IssuerSerialType"/>
   <complexType name="X509IssuerSerialType">
     <sequence>
       <element name="X509IssuerName" type="string"/>
       <element name="X509SerialNumber" type="integer"/>
     </sequence>
   </complexType>
An X509IssuerSerial instance may be created by invoking the newX509IssuerSerial method of the KeyInfoFactory class, and passing it a String and BigInteger representing the X.500 DN and serial number. Here is an example of creating an X509IssuerSerial from the issuer DN and serial number of an existing X509Certificate:
 KeyInfoFactory factory = KeyInfoFactory.getInstance("DOM");
 X509IssuerSerial issuer = factory.newX509IssuerSerial
     (cert.getIssuerX500Principal().getName(), cert.getSerialNumber());

Since:
1.6
See Also:
X509Data.getContent(), KeyInfoFactory.newX509IssuerSerial(String, BigInteger)

Method Summary
String | getIssuerName() Returns the X.500 distinguished name of this X509IssuerSerial in RFC 2253 String format.
BigInteger | getSerialNumber() Returns the serial number of this X509IssuerSerial.
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported

Method Detail

getIssuerName

String getIssuerName()
Returns the X.500 distinguished name of this X509IssuerSerial in RFC 2253 String format.

Returns:
the X.500 distinguished name in RFC 2253 String format (never null)

getSerialNumber

BigInteger getSerialNumber()
Returns the serial number of this X509IssuerSerial.

Returns:
the serial number (never null)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Manifest

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Interface Manifest

All Superinterfaces:
XMLStructure
public interface Manifest
extends XMLStructure

A representation of the XML Manifest element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. The XML Schema Definition is defined as:

 <element name="Manifest" type="ds:ManifestType"/>
   <complexType name="ManifestType">
     <sequence>
       <element ref="ds:Reference" maxOccurs="unbounded"/>
     </sequence>
     <attribute name="Id" type="ID" use="optional"/>
   </complexType>
A Manifest instance may be created by invoking one of the newManifest methods of the XMLSignatureFactory class; for example:
   XMLSignatureFactory factory = XMLSignatureFactory.getInstance("DOM");
   List references = Collections.singletonList(factory.newReference
       ("#reference-1", DigestMethod.SHA1));
   Manifest manifest = factory.newManifest(references, "manifest-1");

Since:
1.6
See Also:
XMLSignatureFactory.newManifest(List), XMLSignatureFactory.newManifest(List, String)

Field Summary
static String TYPE
URI that identifies the Manifest element (this can be specified as the value of the type parameter of the Reference class to identify the referent's type).
Method Summary
String | getId() Returns the Id of this Manifest.
List | getReferences() Returns an unmodifiable list of one or more References that are contained in this Manifest.
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported

Field Detail

TYPE

static final String TYPE
URI that identifies the Manifest element (this can be specified as the value of the type parameter of the Reference class to identify the referent's type).

See Also:
Constant Field Values
Method Detail

getId

String getId()
Returns the Id of this Manifest.

Returns:
the Id of this Manifest (or null if not specified)

getReferences

List getReferences()
Returns an unmodifiable list of one or more References that are contained in this Manifest.

Returns:
an unmodifiable list of one or more References
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Reference

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Interface Reference

All Superinterfaces:
URIReference, XMLStructure
public interface Reference
extends URIReference, XMLStructure

A representation of the Reference element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. The XML schema is defined as:

 <element name="Reference" type="ds:ReferenceType"/>
 <complexType name="ReferenceType">
   <sequence>
     <element ref="ds:Transforms" minOccurs="0"/>
     <element ref="ds:DigestMethod"/>
     <element ref="ds:DigestValue"/>
   </sequence>
   <attribute name="Id" type="ID" use="optional"/>
   <attribute name="URI" type="anyURI" use="optional"/>
   <attribute name="Type" type="anyURI" use="optional"/>
 </complexType>

 <element name="DigestValue" type="ds:DigestValueType"/>
 <simpleType name="DigestValueType">
   <restriction base="base64Binary"/>
 </simpleType>

A Reference instance may be created by invoking one of the newReference methods of the XMLSignatureFactory class; for example:

   XMLSignatureFactory factory = XMLSignatureFactory.getInstance("DOM");
   Reference ref = factory.newReference
     ("http://www.ietf.org/rfc/rfc3275.txt",
        factory.newDigestMethod(DigestMethod.SHA1, null));

Since:
1.6
See Also:
XMLSignatureFactory.newReference(String, DigestMethod), XMLSignatureFactory.newReference(String, DigestMethod, List, String, String)

Method Summary
byte[] | getCalculatedDigestValue() Returns the calculated digest value of this Reference after a validation operation.
Data | getDereferencedData() Returns the dereferenced data, if reference caching is enabled.
InputStream | getDigestInputStream() Returns the pre-digested input stream, if reference caching is enabled.
DigestMethod | getDigestMethod() Returns the digest method of this Reference.
byte[] | getDigestValue() Returns the digest value of this Reference.
String | getId() Returns the optional Id attribute of this Reference, which permits this reference to be referenced from elsewhere.
List | getTransforms() Returns an unmodifiable list of Transforms that are contained in this Reference.
boolean | validate(XMLValidateContext validateContext) Validates this reference.
Methods inherited from interface javax.xml.crypto.URIReference
getType, getURI
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported

Method Detail

getTransforms

List getTransforms()
Returns an unmodifiable list of Transforms that are contained in this Reference.

Returns:
an unmodifiable list of Transforms (may be empty but never null)

getDigestMethod

DigestMethod getDigestMethod()
Returns the digest method of this Reference.

Returns:
the digest method

getId

String getId()
Returns the optional Id attribute of this Reference, which permits this reference to be referenced from elsewhere.

Returns:
the Id attribute (may be null if not specified)

getDigestValue

byte[] getDigestValue()
Returns the digest value of this Reference.

Returns:
the raw digest value, or null if this reference has not been digested yet. Each invocation of this method returns a new clone to protect against subsequent modification.

getCalculatedDigestValue

byte[] getCalculatedDigestValue()
Returns the calculated digest value of this Reference after a validation operation. This method is useful for debugging if the reference fails to validate.

Returns:
the calculated digest value, or null if this reference has not been validated yet. Each invocation of this method returns a new clone to protect against subsequent modification.

validate

boolean validate(XMLValidateContext validateContext)
                 throws XMLSignatureException
Validates this reference. This method verifies the digest of this reference.

This method only validates the reference the first time it is invoked. On subsequent invocations, it returns a cached result.

Parameters:
validateContext - the validating context
Returns:
true if this reference was validated successfully; false otherwise
Throws:
NullPointerException - if validateContext is null
XMLSignatureException - if an unexpected exception occurs while validating the reference

getDereferencedData

Data getDereferencedData()
Returns the dereferenced data, if reference caching is enabled. This is the result of dereferencing the URI of this reference during a validation or generation operation.

Returns:
the dereferenced data, or null if reference caching is not enabled or this reference has not been generated or validated

getDigestInputStream

InputStream getDigestInputStream()
Returns the pre-digested input stream, if reference caching is enabled. This is the input to the digest operation during a validation or signing operation.

Returns:
an input stream containing the pre-digested input, or null if reference caching is not enabled or this reference has not been generated or validated
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SignatureMethod

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Interface SignatureMethod

All Superinterfaces:
AlgorithmMethod, XMLStructure
public interface SignatureMethod
extends XMLStructure, AlgorithmMethod

A representation of the XML SignatureMethod element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. The XML Schema Definition is defined as:

   <element name="SignatureMethod" type="ds:SignatureMethodType"/>
     <complexType name="SignatureMethodType" mixed="true">
       <sequence>
         <element name="HMACOutputLength" minOccurs="0" type="ds:HMACOutputLengthType"/>
         <any namespace="##any" minOccurs="0" maxOccurs="unbounded"/>
           <!-- (0,unbounded) elements from (1,1) namespace -->
       </sequence>
       <attribute name="Algorithm" type="anyURI" use="required"/>
     </complexType>
A SignatureMethod instance may be created by invoking the newSignatureMethod method of the XMLSignatureFactory class.

Since:
1.6
See Also:
XMLSignatureFactory.newSignatureMethod(String, SignatureMethodParameterSpec)

Field Summary
static String | DSA_SHA1 The DSAwithSHA1 (DSS) signature method algorithm URI.
static String | HMAC_SHA1 The HMAC-SHA1 MAC signature method algorithm URI
static String | RSA_SHA1 The RSAwithSHA1 (PKCS #1) signature method algorithm URI.
Method Summary
 AlgorithmParameterSpec getParameterSpec()
Returns the algorithm-specific input parameters of this SignatureMethod.
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported
Methods inherited from interface javax.xml.crypto.AlgorithmMethod
getAlgorithm

Field Detail

DSA_SHA1

static final String DSA_SHA1
The DSAwithSHA1 (DSS) signature method algorithm URI.

See Also:
Constant Field Values

RSA_SHA1

static final String RSA_SHA1
The RSAwithSHA1 (PKCS #1) signature method algorithm URI.

See Also:
Constant Field Values

HMAC_SHA1

static final String HMAC_SHA1
The HMAC-SHA1 MAC signature method algorithm URI

See Also:
Constant Field Values
Method Detail

getParameterSpec

AlgorithmParameterSpec getParameterSpec()
Returns the algorithm-specific input parameters of this SignatureMethod.

The returned parameters can be typecast to a SignatureMethodParameterSpec object.

Specified by:
getParameterSpec in interface AlgorithmMethod
Returns:
the algorithm-specific input parameters of this SignatureMethod (may be null if not specified)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SignatureProperties

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Interface SignatureProperties

All Superinterfaces:
XMLStructure
public interface SignatureProperties
extends XMLStructure

A representation of the XML SignatureProperties element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. The XML Schema Definition is defined as:

<element name="SignatureProperties" type="ds:SignaturePropertiesType"/>
   <complexType name="SignaturePropertiesType">
     <sequence>
       <element ref="ds:SignatureProperty" maxOccurs="unbounded"/>
     </sequence>
     <attribute name="Id" type="ID" use="optional"/>
   </complexType>
A SignatureProperties instance may be created by invoking the newSignatureProperties method of the XMLSignatureFactory class; for example:
   XMLSignatureFactory factory = XMLSignatureFactory.getInstance("DOM");
   SignatureProperties properties =
        factory.newSignatureProperties(props, "signature-properties-1");

Since:
1.6
See Also:
XMLSignatureFactory.newSignatureProperties(List, String), SignatureProperty

Field Summary
static String TYPE
URI that identifies the SignatureProperties element (this can be specified as the value of the type parameter of the Reference class to identify the referent's type).
Method Summary
String | getId() Returns the Id of this SignatureProperties.
List | getProperties() Returns an unmodifiable list of one or more SignaturePropertys that are contained in this SignatureProperties.
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported

Field Detail

TYPE

static final String TYPE
URI that identifies the SignatureProperties element (this can be specified as the value of the type parameter of the Reference class to identify the referent's type).

See Also:
Constant Field Values
Method Detail

getId

String getId()
Returns the Id of this SignatureProperties.

Returns:
the Id of this SignatureProperties (or null if not specified)

getProperties

List getProperties()
Returns an unmodifiable list of one or more SignaturePropertys that are contained in this SignatureProperties.

Returns:
an unmodifiable list of one or more SignaturePropertys
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SignatureProperty

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Interface SignatureProperty

All Superinterfaces:
XMLStructure
public interface SignatureProperty
extends XMLStructure

A representation of the XML SignatureProperty element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. The XML Schema Definition is defined as:

<element name="SignatureProperty" type="ds:SignaturePropertyType"/>
   <complexType name="SignaturePropertyType" mixed="true">
     <choice maxOccurs="unbounded">
       <any namespace="##other" processContents="lax"/>
       <!-- (1,1) elements from (1, unbounded) namespaces -->
     </choice>
     <attribute name="Target" type="anyURI" use="required"/>
     <attribute name="Id" type="ID" use="optional"/>
   </complexType>
A SignatureProperty instance may be created by invoking the newSignatureProperty method of the XMLSignatureFactory class; for example:
   XMLSignatureFactory factory = XMLSignatureFactory.getInstance("DOM");
   SignatureProperty property = factory.newSignatureProperty
        (Collections.singletonList(content), "#Signature-1", "TimeStamp");

Since:
1.6
See Also:
XMLSignatureFactory.newSignatureProperty(List, String, String), SignatureProperties

Method Summary
List | getContent() Returns an unmodifiable list of one or more XMLStructures that are contained in this SignatureProperty.
String | getId() Returns the Id of this SignatureProperty.
String | getTarget() Returns the target URI of this SignatureProperty.
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported

Method Detail

getTarget

String getTarget()
Returns the target URI of this SignatureProperty.

Returns:
the target URI of this SignatureProperty (never null)

getId

String getId()
Returns the Id of this SignatureProperty.

Returns:
the Id of this SignatureProperty (or null if not specified)

getContent

List getContent()
Returns an unmodifiable list of one or more XMLStructures that are contained in this SignatureProperty. These represent additional information items concerning the generation of the XMLSignature (i.e. date/time stamp or serial numbers of cryptographic hardware used in signature generation).

Returns:
an unmodifiable list of one or more XMLStructures
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SignedInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Interface SignedInfo

All Superinterfaces:
XMLStructure
public interface SignedInfo
extends XMLStructure

An representation of the XML SignedInfo element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. The XML Schema Definition is defined as:

 <element name="SignedInfo" type="ds:SignedInfoType"/>
 <complexType name="SignedInfoType">
   <sequence>
     <element ref="ds:CanonicalizationMethod"/>
     <element ref="ds:SignatureMethod"/>
     <element ref="ds:Reference" maxOccurs="unbounded"/>
   </sequence>
   <attribute name="Id" type="ID" use="optional"/>
 </complexType>
A SignedInfo instance may be created by invoking one of the newSignedInfo methods of the XMLSignatureFactory class.

Since:
1.6
See Also:
XMLSignatureFactory.newSignedInfo(CanonicalizationMethod, SignatureMethod, List), XMLSignatureFactory.newSignedInfo(CanonicalizationMethod, SignatureMethod, List, String)

Method Summary
CanonicalizationMethod | getCanonicalizationMethod() Returns the canonicalization method of this SignedInfo.
InputStream | getCanonicalizedData() Returns the canonicalized signed info bytes after a signing or validation operation.
String | getId() Returns the optional Id attribute of this SignedInfo.
List | getReferences() Returns an unmodifiable list of one or more References.
SignatureMethod | getSignatureMethod() Returns the signature method of this SignedInfo.
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported

Method Detail

getCanonicalizationMethod

CanonicalizationMethod getCanonicalizationMethod()
Returns the canonicalization method of this SignedInfo.

Returns:
the canonicalization method

getSignatureMethod

SignatureMethod getSignatureMethod()
Returns the signature method of this SignedInfo.

Returns:
the signature method

getReferences

List getReferences()
Returns an unmodifiable list of one or more References.

Returns:
an unmodifiable list of one or more References

getId

String getId()
Returns the optional Id attribute of this SignedInfo.

Returns:
the id (may be null if not specified)

getCanonicalizedData

InputStream getCanonicalizedData()
Returns the canonicalized signed info bytes after a signing or validation operation. This method is useful for debugging.

Returns:
an InputStream containing the canonicalized bytes, or null if this SignedInfo has not been signed or validated yet
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


spec

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.crypto.dsig.spec

Parameter classes for XML digital signatures.

See:
Description

Interface Summary
C14NMethodParameterSpec | A specification of algorithm parameters for a CanonicalizationMethod Algorithm.
DigestMethodParameterSpec | A specification of algorithm parameters for a DigestMethod algorithm.
SignatureMethodParameterSpec | A specification of algorithm parameters for an XML SignatureMethod algorithm.
TransformParameterSpec | A specification of algorithm parameters for a Transform algorithm.

Class Summary
ExcC14NParameterSpec | Parameters for the W3C Recommendation: Exclusive XML Canonicalization (C14N) algorithm.
HMACParameterSpec | Parameters for the XML Signature HMAC Algorithm.
XPathFilter2ParameterSpec | Parameters for the W3C Recommendation XPath Filter 2.0 Transform Algorithm.
XPathFilterParameterSpec | Parameters for the XPath Filtering Transform Algorithm.
XPathType | The XML Schema Definition of the XPath element as defined in the W3C Recommendation for XML-Signature XPath Filter 2.0:
XPathType.Filter | Represents the filter set operation.
XSLTTransformParameterSpec | Parameters for the XSLT Transform Algorithm.

Package javax.xml.crypto.dsig.spec Description

Parameter classes for XML digital signatures. This package contains interfaces and classes representing input parameters for the digest, signature, transform, or canonicalization algorithms used in the processing of XML signatures.

Package Specification

  • XML-Signature Syntax and Processing: W3C Recommendation
  • RFC 3275: XML-Signature Syntax and Processing
  • Exclusive XML Canonicalization algorithm: W3C Recommendation
  • XPath Filter 2.0 Transform Algorithm: W3C Recommendation

Since:
1.6

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


C14NMethodParameterSpec

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.spec
Interface C14NMethodParameterSpec

All Superinterfaces:
AlgorithmParameterSpec, TransformParameterSpec
All Known Implementing Classes:
ExcC14NParameterSpec
public interface C14NMethodParameterSpec
extends TransformParameterSpec

A specification of algorithm parameters for a CanonicalizationMethod Algorithm. The purpose of this interface is to group (and provide type safety for) all canonicalization (C14N) parameter specifications. All canonicalization parameter specifications must implement this interface.

Since:
1.6
See Also:
CanonicalizationMethod

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


DigestMethodParameterSpec

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.spec
Interface DigestMethodParameterSpec

All Superinterfaces:
AlgorithmParameterSpec
public interface DigestMethodParameterSpec
extends AlgorithmParameterSpec

A specification of algorithm parameters for a DigestMethod algorithm. The purpose of this interface is to group (and provide type safety for) all digest method parameter specifications. All digest method parameter specifications must implement this interface.

Since:
1.6
See Also:
DigestMethod

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


javax.xml.crypto.dsig.spec Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.crypto.dsig.spec

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.crypto.dsig.spec.ExcC14NParameterSpec (implements javax.xml.crypto.dsig.spec.C14NMethodParameterSpec)
    • javax.xml.crypto.dsig.spec.HMACParameterSpec (implements javax.xml.crypto.dsig.spec.SignatureMethodParameterSpec)
    • javax.xml.crypto.dsig.spec.XPathFilter2ParameterSpec (implements javax.xml.crypto.dsig.spec.TransformParameterSpec)
    • javax.xml.crypto.dsig.spec.XPathFilterParameterSpec (implements javax.xml.crypto.dsig.spec.TransformParameterSpec)
    • javax.xml.crypto.dsig.spec.XPathType
    • javax.xml.crypto.dsig.spec.XPathType.Filter
    • javax.xml.crypto.dsig.spec.XSLTTransformParameterSpec (implements javax.xml.crypto.dsig.spec.TransformParameterSpec)

Interface Hierarchy

  • java.security.spec.AlgorithmParameterSpec
    • javax.xml.crypto.dsig.spec.DigestMethodParameterSpec
    • javax.xml.crypto.dsig.spec.SignatureMethodParameterSpec
    • javax.xml.crypto.dsig.spec.TransformParameterSpec
      • javax.xml.crypto.dsig.spec.C14NMethodParameterSpec
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


SignatureMethodParameterSpec

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.spec
Interface SignatureMethodParameterSpec

All Superinterfaces:
AlgorithmParameterSpec
All Known Implementing Classes:
HMACParameterSpec
public interface SignatureMethodParameterSpec
extends AlgorithmParameterSpec

A specification of algorithm parameters for an XML SignatureMethod algorithm. The purpose of this interface is to group (and provide type safety for) all signature method parameter specifications. All signature method parameter specifications must implement this interface.

Since:
1.6
See Also:
SignatureMethod

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TransformParameterSpec

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.spec
Interface TransformParameterSpec

All Superinterfaces:
AlgorithmParameterSpec
All Known Subinterfaces:
C14NMethodParameterSpec
All Known Implementing Classes:
ExcC14NParameterSpec, XPathFilter2ParameterSpec, XPathFilterParameterSpec, XSLTTransformParameterSpec
public interface TransformParameterSpec
extends AlgorithmParameterSpec

A specification of algorithm parameters for a Transform algorithm. The purpose of this interface is to group (and provide type safety for) all transform parameter specifications. All transform parameter specifications must implement this interface.

Since:
1.6
See Also:
Transform

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Package javax.xml.crypto.dsig.spec

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.crypto.dsig.spec

Packages that use javax.xml.crypto.dsig.spec
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.spec | Parameter classes for XML digital signatures.

Classes in javax.xml.crypto.dsig.spec used by javax.xml.crypto.dsig
C14NMethodParameterSpec
A specification of algorithm parameters for a CanonicalizationMethod Algorithm.
DigestMethodParameterSpec
A specification of algorithm parameters for a DigestMethod algorithm.
SignatureMethodParameterSpec
A specification of algorithm parameters for an XML SignatureMethod algorithm.
TransformParameterSpec
A specification of algorithm parameters for a Transform algorithm.

Classes in javax.xml.crypto.dsig.spec used by javax.xml.crypto.dsig.spec
C14NMethodParameterSpec
A specification of algorithm parameters for a CanonicalizationMethod Algorithm.
SignatureMethodParameterSpec
A specification of algorithm parameters for an XML SignatureMethod algorithm.
TransformParameterSpec
A specification of algorithm parameters for a Transform algorithm.
XPathType.Filter
Represents the filter set operation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.dsig.spec.ExcC14NParameterSpec

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.dsig.spec.ExcC14NParameterSpec

No usage of javax.xml.crypto.dsig.spec.ExcC14NParameterSpec

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.dsig.spec.HMACParameterSpec

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.dsig.spec.HMACParameterSpec

No usage of javax.xml.crypto.dsig.spec.HMACParameterSpec

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.dsig.spec.XPathFilter2ParameterSpec

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.dsig.spec.XPathFilter2ParameterSpec

No usage of javax.xml.crypto.dsig.spec.XPathFilter2ParameterSpec

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.dsig.spec.XPathFilterParameterSpec

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.dsig.spec.XPathFilterParameterSpec

No usage of javax.xml.crypto.dsig.spec.XPathFilterParameterSpec

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.dsig.spec.XPathType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.dsig.spec.XPathType

No usage of javax.xml.crypto.dsig.spec.XPathType

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.dsig.spec.XPathType.Filter

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.dsig.spec.XPathType.Filter

Packages that use XPathType.Filter
javax.xml.crypto.dsig.spec Parameter classes for XML digital signatures.

Uses of XPathType.Filter in javax.xml.crypto.dsig.spec

Fields in javax.xml.crypto.dsig.spec declared as XPathType.Filter
static XPathType.Filter | XPathType.Filter.INTERSECT The intersect filter operation.
static XPathType.Filter | XPathType.Filter.SUBTRACT The subtract filter operation.
static XPathType.Filter | XPathType.Filter.UNION The union filter operation.

Methods in javax.xml.crypto.dsig.spec that return XPathType.Filter
 XPathType.Filter XPathType.getFilter()
Returns the filter operation.

Constructors in javax.xml.crypto.dsig.spec with parameters of type XPathType.Filter
XPathType(String expression, XPathType.Filter filter)
Creates an XPathType instance with the specified XPath expression and filter.
XPathType(String expression, XPathType.Filter filter, Map namespaceMap)
Creates an XPathType instance with the specified XPath expression, filter, and namespace map.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.crypto.dsig.spec.XSLTTransformParameterSpec

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.crypto.dsig.spec.XSLTTransformParameterSpec

No usage of javax.xml.crypto.dsig.spec.XSLTTransformParameterSpec

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.spec.C14NMethodParameterSpec

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.spec.C14NMethodParameterSpec

Packages that use C14NMethodParameterSpec
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.spec | Parameter classes for XML digital signatures.

Uses of C14NMethodParameterSpec in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig with parameters of type C14NMethodParameterSpec
abstract  CanonicalizationMethod XMLSignatureFactory.newCanonicalizationMethod(String algorithm, C14NMethodParameterSpec params)
Creates a CanonicalizationMethod for the specified algorithm URI and parameters.

Uses of C14NMethodParameterSpec in javax.xml.crypto.dsig.spec

Classes in javax.xml.crypto.dsig.spec that implement C14NMethodParameterSpec
 class ExcC14NParameterSpec
Parameters for the W3C Recommendation: Exclusive XML Canonicalization (C14N) algorithm.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.spec.DigestMethodParameterSpec

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.spec.DigestMethodParameterSpec

Packages that use DigestMethodParameterSpec
javax.xml.crypto.dsig Classes for generating and validating XML digital signatures.

Uses of DigestMethodParameterSpec in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig with parameters of type DigestMethodParameterSpec
abstract  DigestMethod XMLSignatureFactory.newDigestMethod(String algorithm, DigestMethodParameterSpec params)
Creates a DigestMethod for the specified algorithm URI and parameters.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.spec.SignatureMethodParameterSpec

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.spec.SignatureMethodParameterSpec

Packages that use SignatureMethodParameterSpec
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.spec | Parameter classes for XML digital signatures.

Uses of SignatureMethodParameterSpec in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig with parameters of type SignatureMethodParameterSpec
abstract  SignatureMethod XMLSignatureFactory.newSignatureMethod(String algorithm, SignatureMethodParameterSpec params)
Creates a SignatureMethod for the specified algorithm URI and parameters.

Uses of SignatureMethodParameterSpec in javax.xml.crypto.dsig.spec

Classes in javax.xml.crypto.dsig.spec that implement SignatureMethodParameterSpec
 class HMACParameterSpec
Parameters for the XML Signature HMAC Algorithm.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.crypto.dsig.spec.TransformParameterSpec

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.crypto.dsig.spec.TransformParameterSpec

Packages that use TransformParameterSpec
javax.xml.crypto.dsig | Classes for generating and validating XML digital signatures.
javax.xml.crypto.dsig.spec | Parameter classes for XML digital signatures.

Uses of TransformParameterSpec in javax.xml.crypto.dsig

Methods in javax.xml.crypto.dsig with parameters of type TransformParameterSpec
abstract void | TransformService.init(TransformParameterSpec params) Initializes this TransformService with the specified parameters.
abstract Transform | XMLSignatureFactory.newTransform(String algorithm, TransformParameterSpec params) Creates a Transform for the specified algorithm URI and parameters.

Uses of TransformParameterSpec in javax.xml.crypto.dsig.spec

Subinterfaces of TransformParameterSpec in javax.xml.crypto.dsig.spec
 interface C14NMethodParameterSpec
A specification of algorithm parameters for a CanonicalizationMethod Algorithm.

Classes in javax.xml.crypto.dsig.spec that implement TransformParameterSpec
class | ExcC14NParameterSpec Parameters for the W3C Recommendation: Exclusive XML Canonicalization (C14N) algorithm.
class | XPathFilter2ParameterSpec Parameters for the W3C Recommendation XPath Filter 2.0 Transform Algorithm.
class | XPathFilterParameterSpec Parameters for the XPath Filtering Transform Algorithm.
class | XSLTTransformParameterSpec Parameters for the XSLT Transform Algorithm.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ExcC14NParameterSpec

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.spec
Class ExcC14NParameterSpec

java.lang.Object
    extended by  javax.xml.crypto.dsig.spec.ExcC14NParameterSpec
All Implemented Interfaces:
AlgorithmParameterSpec, C14NMethodParameterSpec, TransformParameterSpec
public final class ExcC14NParameterSpec
extends Object
implements C14NMethodParameterSpec

Parameters for the W3C Recommendation: Exclusive XML Canonicalization (C14N) algorithm. The parameters include an optional inclusive namespace prefix list. The XML Schema Definition of the Exclusive XML Canonicalization parameters is defined as:

 <schema xmlns="http://www.w3.org/2001/XMLSchema"
         xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"
         targetNamespace="http://www.w3.org/2001/10/xml-exc-c14n#"
         version="0.1" elementFormDefault="qualified">

 <element name="InclusiveNamespaces" type="ec:InclusiveNamespaces"/>
 <complexType name="InclusiveNamespaces">
   <attribute name="PrefixList" type="xsd:string"/>
 </complexType>
 </schema>

Since:
1.6
See Also:
CanonicalizationMethod

Field Summary
static String DEFAULT
Indicates the default namespace ("#default").
Constructor Summary
ExcC14NParameterSpec()
Creates a ExcC14NParameterSpec with an empty prefix list.
ExcC14NParameterSpec(List prefixList)
Creates a ExcC14NParameterSpec with the specified list of prefixes.
Method Summary
 List getPrefixList()
Returns the inclusive namespace prefix list.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT

public static final String DEFAULT
Indicates the default namespace ("#default").

See Also:
Constant Field Values
Constructor Detail

ExcC14NParameterSpec

public ExcC14NParameterSpec()
Creates a ExcC14NParameterSpec with an empty prefix list.

ExcC14NParameterSpec

public ExcC14NParameterSpec(List prefixList)
Creates a ExcC14NParameterSpec with the specified list of prefixes. The list is copied to protect against subsequent modification.

Parameters:
prefixList - the inclusive namespace prefix list. Each entry in the list is a String that represents a namespace prefix.
Throws:
NullPointerException - if prefixList is null
ClassCastException - if any of the entries in the list are not of type String
Method Detail

getPrefixList

public List getPrefixList()
Returns the inclusive namespace prefix list. Each entry in the list is a String that represents a namespace prefix.

This implementation returns an unmodifiable list.

Returns:
the inclusive namespace prefix list (may be empty but never null)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HMACParameterSpec

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.spec
Class HMACParameterSpec

java.lang.Object
    extended by  javax.xml.crypto.dsig.spec.HMACParameterSpec
All Implemented Interfaces:
AlgorithmParameterSpec, SignatureMethodParameterSpec
public final class HMACParameterSpec
extends Object
implements SignatureMethodParameterSpec

Parameters for the XML Signature HMAC Algorithm. The parameters include an optional output length which specifies the MAC truncation length in bits. The resulting HMAC will be truncated to the specified number of bits. If the parameter is not specified, then this implies that all the bits of the hash are to be output. The XML Schema Definition of the HMACOutputLength element is defined as:

 <element name="HMACOutputLength" minOccurs="0" type="ds:HMACOutputLengthType"/>
 <simpleType name="HMACOutputLengthType">
   <restriction base="integer"/>
 </simpleType>

Since:
1.6
See Also:
SignatureMethod, RFC 2104

Constructor Summary
HMACParameterSpec(int outputLength)
Creates an HMACParameterSpec with the specified truncation length.
Method Summary
 int getOutputLength()
Returns the truncation length.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HMACParameterSpec

public HMACParameterSpec(int outputLength)
Creates an HMACParameterSpec with the specified truncation length.

Parameters:
outputLength - the truncation length in number of bits
Method Detail

getOutputLength

public int getOutputLength()
Returns the truncation length.

Returns:
the truncation length in number of bits
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XPathFilter2ParameterSpec

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.spec
Class XPathFilter2ParameterSpec

java.lang.Object
    extended by  javax.xml.crypto.dsig.spec.XPathFilter2ParameterSpec
All Implemented Interfaces:
AlgorithmParameterSpec, TransformParameterSpec
public final class XPathFilter2ParameterSpec
extends Object
implements TransformParameterSpec

Parameters for the W3C Recommendation XPath Filter 2.0 Transform Algorithm. The parameters include a list of one or more XPathType objects.

Since:
1.6
See Also:
Transform, XPathFilterParameterSpec

Constructor Summary
XPathFilter2ParameterSpec(List xPathList)
Creates an XPathFilter2ParameterSpec.
Method Summary
 List getXPathList()
Returns a list of one or more XPathType objects.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XPathFilter2ParameterSpec

public XPathFilter2ParameterSpec(List xPathList)
Creates an XPathFilter2ParameterSpec.

Parameters:
xPathList - a list of one or more XPathType objects. The list is defensively copied to protect against subsequent modification.
Throws:
ClassCastException - if xPathList contains any entries that are not of type XPathType
IllegalArgumentException - if xPathList is empty
NullPointerException - if xPathList is null
Method Detail

getXPathList

public List getXPathList()
Returns a list of one or more XPathType objects.

This implementation returns an unmodifiable list.

Returns:
a List of XPathType objects (never null or empty)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XPathFilterParameterSpec

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.spec
Class XPathFilterParameterSpec

java.lang.Object
    extended by  javax.xml.crypto.dsig.spec.XPathFilterParameterSpec
All Implemented Interfaces:
AlgorithmParameterSpec, TransformParameterSpec
public final class XPathFilterParameterSpec
extends Object
implements TransformParameterSpec

Parameters for the XPath Filtering Transform Algorithm. The parameters include the XPath expression and an optional Map of additional namespace prefix mappings. The XML Schema Definition of the XPath Filtering transform parameters is defined as:

 <element name="XPath" type="string"/>

Since:
1.6
See Also:
Transform

Constructor Summary
XPathFilterParameterSpec(String xPath)
Creates an XPathFilterParameterSpec with the specified XPath expression.
XPathFilterParameterSpec(String xPath, Map namespaceMap)
Creates an XPathFilterParameterSpec with the specified XPath expression and namespace map.
Method Summary
Map | getNamespaceMap() Returns a map of namespace prefixes.
String | getXPath() Returns the XPath expression to be evaluated.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XPathFilterParameterSpec

public XPathFilterParameterSpec(String xPath)
Creates an XPathFilterParameterSpec with the specified XPath expression.

Parameters:
xPath - the XPath expression to be evaluated
Throws:
NullPointerException - if xPath is null

XPathFilterParameterSpec

public XPathFilterParameterSpec(String xPath,
                                Map namespaceMap)
Creates an XPathFilterParameterSpec with the specified XPath expression and namespace map. The map is copied to protect against subsequent modification.

Parameters:
xPath - the XPath expression to be evaluated
namespaceMap - the map of namespace prefixes. Each key is a namespace prefix String that maps to a corresponding namespace URI String.
Throws:
NullPointerException - if xPath or namespaceMap are null
ClassCastException - if any of the map's keys or entries are not of type String
Method Detail

getXPath

public String getXPath()
Returns the XPath expression to be evaluated.

Returns:
the XPath expression to be evaluated

getNamespaceMap

public Map getNamespaceMap()
Returns a map of namespace prefixes. Each key is a namespace prefix String that maps to a corresponding namespace URI String.

This implementation returns an unmodifiable map.

Returns:
a Map of namespace prefixes to namespace URIs (may be empty, but never null)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XPathType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.spec
Class XPathType

java.lang.Object
    extended by  javax.xml.crypto.dsig.spec.XPathType

public class XPathType
extends Object

The XML Schema Definition of the XPath element as defined in the W3C Recommendation for XML-Signature XPath Filter 2.0:

 <schema xmlns="http://www.w3.org/2001/XMLSchema"
         xmlns:xf="http://www.w3.org/2002/06/xmldsig-filter2"
         targetNamespace="http://www.w3.org/2002/06/xmldsig-filter2"
         version="0.1" elementFormDefault="qualified">

 <element name="XPath"
          type="xf:XPathType"/>

 <complexType name="XPathType">
   <simpleContent>
     <extension base="string">
       <attribute name="Filter">
         <simpleType>
           <restriction base="string">
             <enumeration value="intersect"/>
             <enumeration value="subtract"/>
             <enumeration value="union"/>
           </restriction>
         </simpleType>
       </attribute>
     </extension>
   </simpleContent>
 </complexType>

Since:
1.6
See Also:
XPathFilter2ParameterSpec

Nested Class Summary
static class XPathType.Filter
Represents the filter set operation.
Constructor Summary
XPathType(String expression, XPathType.Filter filter)
Creates an XPathType instance with the specified XPath expression and filter.
XPathType(String expression, XPathType.Filter filter, Map namespaceMap)
Creates an XPathType instance with the specified XPath expression, filter, and namespace map.
Method Summary
String | getExpression() Returns the XPath expression to be evaluated.
XPathType.Filter | getFilter() Returns the filter operation.
Map | getNamespaceMap() Returns a map of namespace prefixes.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XPathType

public XPathType(String expression,
                 XPathType.Filter filter)
Creates an XPathType instance with the specified XPath expression and filter.

Parameters:
expression - the XPath expression to be evaluated
filter - the filter operation (XPathType.Filter.INTERSECT, XPathType.Filter.SUBTRACT, or XPathType.Filter.UNION)
Throws:
NullPointerException - if expression or filter is null

XPathType

public XPathType(String expression,
                 XPathType.Filter filter,
                 Map namespaceMap)
Creates an XPathType instance with the specified XPath expression, filter, and namespace map. The map is copied to protect against subsequent modification.

Parameters:
expression - the XPath expression to be evaluated
filter - the filter operation (XPathType.Filter.INTERSECT, XPathType.Filter.SUBTRACT, or XPathType.Filter.UNION)
namespaceMap - the map of namespace prefixes. Each key is a namespace prefix String that maps to a corresponding namespace URI String.
Throws:
NullPointerException - if expression, filter or namespaceMap are null
ClassCastException - if any of the map's keys or entries are not of type String
Method Detail

getExpression

public String getExpression()
Returns the XPath expression to be evaluated.

Returns:
the XPath expression to be evaluated

getFilter

public XPathType.Filter getFilter()
Returns the filter operation.

Returns:
the filter operation

getNamespaceMap

public Map getNamespaceMap()
Returns a map of namespace prefixes. Each key is a namespace prefix String that maps to a corresponding namespace URI String.

This implementation returns an unmodifiable map.

Returns:
a Map of namespace prefixes to namespace URIs (may be empty, but never null)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XPathType.Filter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.spec
Class XPathType.Filter

java.lang.Object
    extended by  javax.xml.crypto.dsig.spec.XPathType.Filter
Enclosing class:
XPathType
public static class XPathType.Filter
extends Object

Represents the filter set operation.

Field Summary
static XPathType.Filter | INTERSECT The intersect filter operation.
static XPathType.Filter | SUBTRACT The subtract filter operation.
static XPathType.Filter | UNION The union filter operation.
Method Summary
 String toString()
Returns the string form of the operation.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

INTERSECT

public static final XPathType.Filter INTERSECT
The intersect filter operation.

SUBTRACT

public static final XPathType.Filter SUBTRACT
The subtract filter operation.

UNION

public static final XPathType.Filter UNION
The union filter operation.

Method Detail

toString

public String toString()
Returns the string form of the operation.

Overrides:
toString in class Object
Returns:
the string form of the operation
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XSLTTransformParameterSpec

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig.spec
Class XSLTTransformParameterSpec

java.lang.Object
    extended by  javax.xml.crypto.dsig.spec.XSLTTransformParameterSpec
All Implemented Interfaces:
AlgorithmParameterSpec, TransformParameterSpec
public final class XSLTTransformParameterSpec
extends Object
implements TransformParameterSpec

Parameters for the XSLT Transform Algorithm. The parameters include a namespace-qualified stylesheet element.

An XSLTTransformParameterSpec is instantiated with a mechanism-dependent (ex: DOM) stylesheet element. For example:

   DOMStructure stylesheet = new DOMStructure(element)
   XSLTTransformParameterSpec spec = new XSLTransformParameterSpec(stylesheet);
where element is an Element containing the namespace-qualified stylesheet element.

Since:
1.6
See Also:
Transform

Constructor Summary
XSLTTransformParameterSpec(XMLStructure stylesheet)
Creates an XSLTTransformParameterSpec with the specified stylesheet.
Method Summary
 XMLStructure getStylesheet()
Returns the stylesheet.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XSLTTransformParameterSpec

public XSLTTransformParameterSpec(XMLStructure stylesheet)
Creates an XSLTTransformParameterSpec with the specified stylesheet.

Parameters:
stylesheet - the XSLT stylesheet to be used
Throws:
NullPointerException - if stylesheet is null
Method Detail

getStylesheet

public XMLStructure getStylesheet()
Returns the stylesheet.

Returns:
the stylesheet
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Transform

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Interface Transform

All Superinterfaces:
AlgorithmMethod, XMLStructure
All Known Subinterfaces:
CanonicalizationMethod
All Known Implementing Classes:
TransformService
public interface Transform
extends XMLStructure, AlgorithmMethod

A representation of the XML Transform element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. The XML Schema Definition is defined as:

 <element name="Transform" type="ds:TransformType"/>
   <complexType name="TransformType" mixed="true">
     <choice minOccurs="0" maxOccurs="unbounded">
       <any namespace="##other" processContents="lax"/>
       <!-- (1,1) elements from (0,unbounded) namespaces -->
       <element name="XPath" type="string"/>
     </choice>
     <attribute name="Algorithm" type="anyURI" use="required"/>
   </complexType>
A Transform instance may be created by invoking the newTransform method of the XMLSignatureFactory class.

Since:
1.6
See Also:
XMLSignatureFactory.newTransform(String, TransformParameterSpec)

Field Summary
static String | BASE64 The Base64 transform algorithm URI.
static String | ENVELOPED The Enveloped Signature transform algorithm URI.
static String | XPATH The XPath transform algorithm URI.
static String | XPATH2 The XPath Filter 2 transform algorithm URI.
static String | XSLT The XSLT transform algorithm URI.
Method Summary
AlgorithmParameterSpec | getParameterSpec() Returns the algorithm-specific input parameters associated with this Transform.
Data | transform(Data data, XMLCryptoContext context) Transforms the specified data using the underlying transform algorithm.
Data | transform(Data data, XMLCryptoContext context, OutputStream os) Transforms the specified data using the underlying transform algorithm.
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported
Methods inherited from interface javax.xml.crypto.AlgorithmMethod
getAlgorithm

Field Detail

BASE64

static final String BASE64
The Base64 transform algorithm URI.

See Also:
Constant Field Values

ENVELOPED

static final String ENVELOPED
The Enveloped Signature transform algorithm URI.

See Also:
Constant Field Values

XPATH

static final String XPATH
The XPath transform algorithm URI.

See Also:
Constant Field Values

XPATH2

static final String XPATH2
The XPath Filter 2 transform algorithm URI.

See Also:
Constant Field Values

XSLT

static final String XSLT
The XSLT transform algorithm URI.

See Also:
Constant Field Values
Method Detail

getParameterSpec

AlgorithmParameterSpec getParameterSpec()
Returns the algorithm-specific input parameters associated with this Transform.

The returned parameters can be typecast to a TransformParameterSpec object.

Specified by:
getParameterSpec in interface AlgorithmMethod
Returns:
the algorithm-specific input parameters (may be null if not specified)

transform

Data transform(Data data,
               XMLCryptoContext context)
               throws TransformException
Transforms the specified data using the underlying transform algorithm.

Parameters:
data - the data to be transformed
context - the XMLCryptoContext containing additional context (may be null if not applicable)
Returns:
the transformed data
Throws:
NullPointerException - if data is null
TransformException - if an error occurs while executing the transform

transform

Data transform(Data data,
               XMLCryptoContext context,
               OutputStream os)
               throws TransformException
Transforms the specified data using the underlying transform algorithm. If the output of this transform is an OctetStreamData, then this method returns null and the bytes are written to the specified OutputStream. Otherwise, the OutputStream is ignored and the method behaves as if transform(Data, XMLCryptoContext) were invoked.

Parameters:
data - the data to be transformed
context - the XMLCryptoContext containing additional context (may be null if not applicable)
os - the OutputStream that should be used to write the transformed data to
Returns:
the transformed data (or null if the data was written to the OutputStream parameter)
Throws:
NullPointerException - if data or os is null
TransformException - if an error occurs while executing the transform
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TransformException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Class TransformException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.crypto.dsig.TransformException
All Implemented Interfaces:
Serializable
public class TransformException
extends Exception

Indicates an exceptional condition that occured while executing a transform algorithm.

A TransformException can contain a cause: another throwable that caused this TransformException to get thrown.

Since:
1.6
See Also:
Transform.transform(javax.xml.crypto.Data, javax.xml.crypto.XMLCryptoContext), Serialized Form

Constructor Summary
TransformException()
Constructs a new TransformException with null as its detail message.
TransformException(String message)
Constructs a new TransformException with the specified detail message.
TransformException(String message, Throwable cause)
Constructs a new TransformException with the specified detail message and cause.
TransformException(Throwable cause)
Constructs a new TransformException with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).
Method Summary
Throwable | getCause() Returns the cause of this TransformException or null if the cause is nonexistent or unknown.
void | printStackTrace() Prints this TransformException, its backtrace and the cause's backtrace to the standard error stream.
void | printStackTrace(PrintStream s) Prints this TransformException, its backtrace and the cause's backtrace to the specified print stream.
void | printStackTrace(PrintWriter s) Prints this TransformException, its backtrace and the cause's backtrace to the specified print writer.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TransformException

public TransformException()
Constructs a new TransformException with null as its detail message.

TransformException

public TransformException(String message)
Constructs a new TransformException with the specified detail message.

Parameters:
message - the detail message

TransformException

public TransformException(String message,
                          Throwable cause)
Constructs a new TransformException with the specified detail message and cause.

Note that the detail message associated with cause is not automatically incorporated in this exception's detail message.

Parameters:
message - the detail message
cause - the cause (A null value is permitted, and indicates that the cause is nonexistent or unknown.)

TransformException

public TransformException(Throwable cause)
Constructs a new TransformException with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).

Parameters:
cause - the cause (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
Method Detail

getCause

public Throwable getCause()
Returns the cause of this TransformException or null if the cause is nonexistent or unknown. (The cause is the throwable that caused this TransformException to get thrown.)

Overrides:
getCause in class Throwable
Returns:
the cause of this TransformException or null if the cause is nonexistent or unknown.

printStackTrace

public void printStackTrace()
Prints this TransformException, its backtrace and the cause's backtrace to the standard error stream.

Overrides:
printStackTrace in class Throwable

printStackTrace

public void printStackTrace(PrintStream s)
Prints this TransformException, its backtrace and the cause's backtrace to the specified print stream.

Overrides:
printStackTrace in class Throwable
Parameters:
s - PrintStream to use for output

printStackTrace

public void printStackTrace(PrintWriter s)
Prints this TransformException, its backtrace and the cause's backtrace to the specified print writer.

Overrides:
printStackTrace in class Throwable
Parameters:
s - PrintWriter to use for output
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TransformService

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Class TransformService

java.lang.Object
    extended by  javax.xml.crypto.dsig.TransformService
All Implemented Interfaces:
AlgorithmMethod, Transform, XMLStructure
public abstract class TransformService
extends Object
implements Transform

A Service Provider Interface for transform and canonicalization algorithms.

Each instance of TransformService supports a specific transform or canonicalization algorithm and XML mechanism type. To create a TransformService, call one of the static getInstance methods, passing in the algorithm URI and XML mechanism type desired, for example:

TransformService ts = TransformService.getInstance(Transform.XPATH2, "DOM");

TransformService implementations are registered and loaded using the Provider mechanism. Each TransformService service provider implementation should include a MechanismType service attribute that identifies the XML mechanism type that it supports. If the attribute is not specified, "DOM" is assumed. For example, a service provider that supports the XPath Filter 2 Transform and DOM mechanism would be specified in the Provider subclass as:

     put("TransformService." + Transform.XPATH2,
         "org.example.XPath2TransformService");
     put("TransformService." + Transform.XPATH2 + " MechanismType", "DOM");
TransformService implementations that support the DOM mechanism type must abide by the DOM interoperability requirements defined in the DOM Mechanism Requirements section of the API overview. See the Service Providers section of the API overview for a list of standard mechanism types.

Once a TransformService has been created, it can be used to process Transform or CanonicalizationMethod objects. If the Transform or CanonicalizationMethod exists in XML form (for example, when validating an existing XMLSignature), the init(XMLStructure, XMLCryptoContext) method must be first called to initialize the transform and provide document context (even if there are no parameters). Alternatively, if the Transform or CanonicalizationMethod is being created from scratch, the init(TransformParameterSpec) method is called to initialize the transform with parameters and the marshalParams method is called to marshal the parameters to XML and provide the transform with document context. Finally, the transform method is called to perform the transformation.

Concurrent Access

The static methods of this class are guaranteed to be thread-safe. Multiple threads may concurrently invoke the static methods defined in this class with no ill effects.

However, this is not true for the non-static methods defined by this class. Unless otherwise documented by a specific provider, threads that need to access a single TransformService instance concurrently should synchronize amongst themselves and provide the necessary locking. Multiple threads each manipulating a different TransformService instance need not synchronize.

Since:
1.6

Field Summary
Fields inherited from interface javax.xml.crypto.dsig.Transform
BASE64, ENVELOPED, XPATH, XPATH2, XSLT
Constructor Summary
protected TransformService()
Default constructor, for invocation by subclasses.
Method Summary
String | getAlgorithm() Returns the URI of the algorithm supported by this TransformService.
static TransformService | getInstance(String algorithm, String mechanismType) Returns a TransformService that supports the specified algorithm URI (ex: Transform.XPATH2) and mechanism type (ex: DOM).
static TransformService | getInstance(String algorithm, String mechanismType, Provider provider) Returns a TransformService that supports the specified algorithm URI (ex: Transform.XPATH2) and mechanism type (ex: DOM) as supplied by the specified provider.
static TransformService | getInstance(String algorithm, String mechanismType, String provider) Returns a TransformService that supports the specified algorithm URI (ex: Transform.XPATH2) and mechanism type (ex: DOM) as supplied by the specified provider.
String | getMechanismType() Returns the mechanism type supported by this TransformService.
Provider | getProvider() Returns the provider of this TransformService.
abstract void | init(TransformParameterSpec params) Initializes this TransformService with the specified parameters.
abstract void | init(XMLStructure parent, XMLCryptoContext context) Initializes this TransformService with the specified parameters and document context.
abstract void | marshalParams(XMLStructure parent, XMLCryptoContext context) Marshals the algorithm-specific parameters.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.xml.crypto.dsig.Transform
getParameterSpec, transform, transform
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported

Constructor Detail

TransformService

protected TransformService()
Default constructor, for invocation by subclasses.

Method Detail

getInstance

public static TransformService getInstance(String algorithm,
                                           String mechanismType)
                                    throws NoSuchAlgorithmException
Returns a TransformService that supports the specified algorithm URI (ex: Transform.XPATH2) and mechanism type (ex: DOM).

This method uses the standard JCA provider lookup mechanism to locate and instantiate a TransformService implementation of the desired algorithm and MechanismType service attribute. It traverses the list of registered security Providers, starting with the most preferred Provider. A new TransformService object from the first Provider that supports the specified algorithm and mechanism type is returned.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters:
algorithm - the URI of the algorithm
mechanismType - the type of the XML processing mechanism and representation
Returns:
a new TransformService
Throws:
NullPointerException - if algorithm or mechanismType is null
NoSuchAlgorithmException - if no Provider supports a TransformService implementation for the specified algorithm and mechanism type
See Also:
Provider

getInstance

public static TransformService getInstance(String algorithm,
                                           String mechanismType,
                                           Provider provider)
                                    throws NoSuchAlgorithmException
Returns a TransformService that supports the specified algorithm URI (ex: Transform.XPATH2) and mechanism type (ex: DOM) as supplied by the specified provider. Note that the specified Provider object does not have to be registered in the provider list.

Parameters:
algorithm - the URI of the algorithm
mechanismType - the type of the XML processing mechanism and representation
provider - the Provider object
Returns:
a new TransformService
Throws:
NullPointerException - if provider, algorithm, or mechanismType is null
NoSuchAlgorithmException - if a TransformService implementation for the specified algorithm and mechanism type is not available from the specified Provider object
See Also:
Provider

getInstance

public static TransformService getInstance(String algorithm,
                                           String mechanismType,
                                           String provider)
                                    throws NoSuchAlgorithmException,
                                           NoSuchProviderException
Returns a TransformService that supports the specified algorithm URI (ex: Transform.XPATH2) and mechanism type (ex: DOM) as supplied by the specified provider. The specified provider must be registered in the security provider list.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters:
algorithm - the URI of the algorithm
mechanismType - the type of the XML processing mechanism and representation
provider - the string name of the provider
Returns:
a new TransformService
Throws:
NoSuchProviderException - if the specified provider is not registered in the security provider list
NullPointerException - if provider, mechanismType, or algorithm is null
NoSuchAlgorithmException - if a TransformService implementation for the specified algorithm and mechanism type is not available from the specified provider
See Also:
Provider

getMechanismType

public final String getMechanismType()
Returns the mechanism type supported by this TransformService.

Returns:
the mechanism type

getAlgorithm

public final String getAlgorithm()
Returns the URI of the algorithm supported by this TransformService.

Specified by:
getAlgorithm in interface AlgorithmMethod
Returns:
the algorithm URI

getProvider

public final Provider getProvider()
Returns the provider of this TransformService.

Returns:
the provider

init

public abstract void init(TransformParameterSpec params)
                   throws InvalidAlgorithmParameterException
Initializes this TransformService with the specified parameters.

If the parameters exist in XML form, the init(XMLStructure, XMLCryptoContext) method should be used to initialize the TransformService.

Parameters:
params - the algorithm parameters (may be null if not required or optional)
Throws:
InvalidAlgorithmParameterException - if the specified parameters are invalid for this algorithm

marshalParams

public abstract void marshalParams(XMLStructure parent,
                                   XMLCryptoContext context)
                            throws MarshalException
Marshals the algorithm-specific parameters. If there are no parameters to be marshalled, this method returns without throwing an exception.

Parameters:
parent - a mechanism-specific structure containing the parent node that the marshalled parameters should be appended to
context - the XMLCryptoContext containing additional context (may be null if not applicable)
Throws:
ClassCastException - if the type of parent or context is not compatible with this TransformService
NullPointerException - if parent is null
MarshalException - if the parameters cannot be marshalled

init

public abstract void init(XMLStructure parent,
                          XMLCryptoContext context)
                   throws InvalidAlgorithmParameterException
Initializes this TransformService with the specified parameters and document context.

Parameters:
parent - a mechanism-specific structure containing the parent structure
context - the XMLCryptoContext containing additional context (may be null if not applicable)
Throws:
ClassCastException - if the type of parent or context is not compatible with this TransformService
NullPointerException - if parent is null
InvalidAlgorithmParameterException - if the specified parameters are invalid for this algorithm
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLObject

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Interface XMLObject

All Superinterfaces:
XMLStructure
public interface XMLObject
extends XMLStructure

A representation of the XML Object element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. An XMLObject may contain any data and may include optional MIME type, ID, and encoding attributes. The XML Schema Definition is defined as:

 <element name="Object" type="ds:ObjectType"/>
 <complexType name="ObjectType" mixed="true">
   <sequence minOccurs="0" maxOccurs="unbounded">
     <any namespace="##any" processContents="lax"/>
   </sequence>
   <attribute name="Id" type="ID" use="optional"/>
   <attribute name="MimeType" type="string" use="optional"/>
   <attribute name="Encoding" type="anyURI" use="optional"/>
 </complexType>
A XMLObject instance may be created by invoking the newXMLObject method of the XMLSignatureFactory class; for example:
   XMLSignatureFactory fac = XMLSignatureFactory.getInstance("DOM");
   List content = Collections.singletonList(fac.newManifest(references)));
   XMLObject object = factory.newXMLObject(content, "object-1", null, null);

Note that this class is named XMLObject rather than Object to avoid naming clashes with the existing java.lang.Object class.

Since:
1.6
See Also:
XMLSignatureFactory.newXMLObject(List, String, String, String)

Field Summary
static String TYPE
URI that identifies the Object element (this can be specified as the value of the type parameter of the Reference class to identify the referent's type).
Method Summary
List | getContent() Returns an unmodifiable list of XMLStructures contained in this XMLObject, which represent elements from any namespace.
String | getEncoding() Returns the encoding URI of this XMLObject.
String | getId() Returns the Id of this XMLObject.
String | getMimeType() Returns the mime type of this XMLObject.
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported

Field Detail

TYPE

static final String TYPE
URI that identifies the Object element (this can be specified as the value of the type parameter of the Reference class to identify the referent's type).

See Also:
Constant Field Values
Method Detail

getContent

List getContent()
Returns an unmodifiable list of XMLStructures contained in this XMLObject, which represent elements from any namespace.

If there is a public subclass representing the type of XMLStructure, it is returned as an instance of that class (ex: a SignatureProperties element would be returned as an instance of SignatureProperties).

Returns:
an unmodifiable list of XMLStructures (may be empty but never null)

getId

String getId()
Returns the Id of this XMLObject.

Returns:
the Id (or null if not specified)

getMimeType

String getMimeType()
Returns the mime type of this XMLObject. The mime type is an optional attribute which describes the data within this XMLObject (independent of its encoding).

Returns:
the mime type (or null if not specified)

getEncoding

String getEncoding()
Returns the encoding URI of this XMLObject. The encoding URI identifies the method by which the object is encoded.

Returns:
the encoding URI (or null if not specified)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLSignature

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Interface XMLSignature

All Superinterfaces:
XMLStructure
public interface XMLSignature
extends XMLStructure

A representation of the XML Signature element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. This class contains methods for signing and validating XML signatures with behavior as defined by the W3C specification. The XML Schema Definition is defined as:

 <element name="Signature" type="ds:SignatureType"/>
 <complexType name="SignatureType">
    <sequence>
      <element ref="ds:SignedInfo"/>
      <element ref="ds:SignatureValue"/>
      <element ref="ds:KeyInfo" minOccurs="0"/>
      <element ref="ds:Object" minOccurs="0" maxOccurs="unbounded"/>
    </sequence>
    <attribute name="Id" type="ID" use="optional"/>
 </complexType>

An XMLSignature instance may be created by invoking one of the newXMLSignature methods of the XMLSignatureFactory class.

If the contents of the underlying document containing the XMLSignature are subsequently modified, the behavior is undefined.

Note that this class is named XMLSignature rather than Signature to avoid naming clashes with the existing java.security.Signature class.

Since:
1.6
See Also:
XMLSignatureFactory.newXMLSignature(SignedInfo, KeyInfo), XMLSignatureFactory.newXMLSignature(SignedInfo, KeyInfo, List, String, String)

Nested Class Summary
static interface XMLSignature.SignatureValue
A representation of the XML SignatureValue element as defined in the W3C Recommendation for XML-Signature Syntax and Processing.
Field Summary
static String XMLNS
The XML Namespace URI of the W3C Recommendation for XML-Signature Syntax and Processing.
Method Summary
String | getId() Returns the optional Id of this XMLSignature.
KeyInfo | getKeyInfo() Returns the key info of this XMLSignature.
KeySelectorResult | getKeySelectorResult() Returns the result of the KeySelector, if specified, after this XMLSignature has been signed or validated.
List | getObjects() Returns an unmodifiable list of XMLObjects contained in this XMLSignature.
XMLSignature.SignatureValue | getSignatureValue() Returns the signature value of this XMLSignature.
SignedInfo | getSignedInfo() Returns the signed info of this XMLSignature.
void | sign(XMLSignContext signContext) Signs this XMLSignature.
boolean | validate(XMLValidateContext validateContext) Validates the signature according to the core validation processing rules.
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported

Field Detail

XMLNS

static final String XMLNS
The XML Namespace URI of the W3C Recommendation for XML-Signature Syntax and Processing.

See Also:
Constant Field Values
Method Detail

validate

boolean validate(XMLValidateContext validateContext)
                 throws XMLSignatureException
Validates the signature according to the core validation processing rules. This method validates the signature using the existing state, it does not unmarshal and reinitialize the contents of the XMLSignature using the location information specified in the context.

This method only validates the signature the first time it is invoked. On subsequent invocations, it returns a cached result.

Parameters:
validateContext - the validating context
Returns:
true if the signature passed core validation, otherwise false
Throws:
ClassCastException - if the type of validateContext is not compatible with this XMLSignature
NullPointerException - if validateContext is null
XMLSignatureException - if an unexpected error occurs during validation that prevented the validation operation from completing

getKeyInfo

KeyInfo getKeyInfo()
Returns the key info of this XMLSignature.

Returns:
the key info (may be null if not specified)

getSignedInfo

SignedInfo getSignedInfo()
Returns the signed info of this XMLSignature.

Returns:
the signed info (never null)

getObjects

List getObjects()
Returns an unmodifiable list of XMLObjects contained in this XMLSignature.

Returns:
an unmodifiable list of XMLObjects (may be empty but never null)

getId

String getId()
Returns the optional Id of this XMLSignature.

Returns:
the Id (may be null if not specified)

getSignatureValue

XMLSignature.SignatureValue getSignatureValue()
Returns the signature value of this XMLSignature.

Returns:
the signature value

sign

void sign(XMLSignContext signContext)
          throws MarshalException,
                 XMLSignatureException
Signs this XMLSignature.

If this method throws an exception, this XMLSignature and the signContext parameter will be left in the state that it was in prior to the invocation.

Parameters:
signContext - the signing context
Throws:
ClassCastException - if the type of signContext is not compatible with this XMLSignature
NullPointerException - if signContext is null
MarshalException - if an exception occurs while marshalling
XMLSignatureException - if an unexpected exception occurs while generating the signature

getKeySelectorResult

KeySelectorResult getKeySelectorResult()
Returns the result of the KeySelector, if specified, after this XMLSignature has been signed or validated.

Returns:
the key selector result, or null if a key selector has not been specified or this XMLSignature has not been signed or validated
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLSignature.SignatureValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Interface XMLSignature.SignatureValue

All Superinterfaces:
XMLStructure
Enclosing interface:
XMLSignature
public static interface XMLSignature.SignatureValue
extends XMLStructure

A representation of the XML SignatureValue element as defined in the W3C Recommendation for XML-Signature Syntax and Processing. The XML Schema Definition is defined as:

   <element name="SignatureValue" type="ds:SignatureValueType"/>
     <complexType name="SignatureValueType">
       <simpleContent>
         <extension base="base64Binary">
           <attribute name="Id" type="ID" use="optional"/>
         </extension>
       </simpleContent>
     </complexType>

Method Summary
String | getId() Returns the optional Id attribute of this SignatureValue, which permits this element to be referenced from elsewhere.
byte[] | getValue() Returns the signature value of this SignatureValue.
boolean | validate(XMLValidateContext validateContext) Validates the signature value.
Methods inherited from interface javax.xml.crypto.XMLStructure
isFeatureSupported

Method Detail

getId

String getId()
Returns the optional Id attribute of this SignatureValue, which permits this element to be referenced from elsewhere.

Returns:
the Id attribute (may be null if not specified)

getValue

byte[] getValue()
Returns the signature value of this SignatureValue.

Returns:
the signature value (may be null if the XMLSignature has not been signed yet). Each invocation of this method returns a new clone of the array to prevent subsequent modification.

validate

boolean validate(XMLValidateContext validateContext)
                 throws XMLSignatureException
Validates the signature value. This method performs a cryptographic validation of the signature calculated over the SignedInfo of the XMLSignature.

This method only validates the signature the first time it is invoked. On subsequent invocations, it returns a cached result.

Parameters:
validateContext - the validating context
Returns:
true if the signature was validated successfully; false otherwise
Throws:
NullPointerException - if validateContext is null
XMLSignatureException - if an unexpected exception occurs while validating the signature
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLSignatureException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Class XMLSignatureException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.crypto.dsig.XMLSignatureException
All Implemented Interfaces:
Serializable
public class XMLSignatureException
extends Exception

Indicates an exceptional condition that occured during the XML signature generation or validation process.

An XMLSignatureException can contain a cause: another throwable that caused this XMLSignatureException to get thrown.

Since:
1.6
See Also:
Serialized Form

Constructor Summary
XMLSignatureException()
Constructs a new XMLSignatureException with null as its detail message.
XMLSignatureException(String message)
Constructs a new XMLSignatureException with the specified detail message.
XMLSignatureException(String message, Throwable cause)
Constructs a new XMLSignatureException with the specified detail message and cause.
XMLSignatureException(Throwable cause)
Constructs a new XMLSignatureException with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).
Method Summary
Throwable | getCause() Returns the cause of this XMLSignatureException or null if the cause is nonexistent or unknown.
void | printStackTrace() Prints this XMLSignatureException, its backtrace and the cause's backtrace to the standard error stream.
void | printStackTrace(PrintStream s) Prints this XMLSignatureException, its backtrace and the cause's backtrace to the specified print stream.
void | printStackTrace(PrintWriter s) Prints this XMLSignatureException, its backtrace and the cause's backtrace to the specified print writer.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

XMLSignatureException

public XMLSignatureException()
Constructs a new XMLSignatureException with null as its detail message.

XMLSignatureException

public XMLSignatureException(String message)
Constructs a new XMLSignatureException with the specified detail message.

Parameters:
message - the detail message

XMLSignatureException

public XMLSignatureException(String message,
                             Throwable cause)
Constructs a new XMLSignatureException with the specified detail message and cause.

Note that the detail message associated with cause is not automatically incorporated in this exception's detail message.

Parameters:
message - the detail message
cause - the cause (A null value is permitted, and indicates that the cause is nonexistent or unknown.)

XMLSignatureException

public XMLSignatureException(Throwable cause)
Constructs a new XMLSignatureException with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).

Parameters:
cause - the cause (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
Method Detail

getCause

public Throwable getCause()
Returns the cause of this XMLSignatureException or null if the cause is nonexistent or unknown. (The cause is the throwable that caused this XMLSignatureException to get thrown.)

Overrides:
getCause in class Throwable
Returns:
the cause of this XMLSignatureException or null if the cause is nonexistent or unknown.

printStackTrace

public void printStackTrace()
Prints this XMLSignatureException, its backtrace and the cause's backtrace to the standard error stream.

Overrides:
printStackTrace in class Throwable

printStackTrace

public void printStackTrace(PrintStream s)
Prints this XMLSignatureException, its backtrace and the cause's backtrace to the specified print stream.

Overrides:
printStackTrace in class Throwable
Parameters:
s - PrintStream to use for output

printStackTrace

public void printStackTrace(PrintWriter s)
Prints this XMLSignatureException, its backtrace and the cause's backtrace to the specified print writer.

Overrides:
printStackTrace in class Throwable
Parameters:
s - PrintWriter to use for output
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLSignatureFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Class XMLSignatureFactory

java.lang.Object
    extended by  javax.xml.crypto.dsig.XMLSignatureFactory

public abstract class XMLSignatureFactory
extends Object

A factory for creating XMLSignature objects from scratch or for unmarshalling an XMLSignature object from a corresponding XML representation.

XMLSignatureFactory Type

Each instance of XMLSignatureFactory supports a specific XML mechanism type. To create an XMLSignatureFactory, call one of the static getInstance methods, passing in the XML mechanism type desired, for example:

XMLSignatureFactory factory = XMLSignatureFactory.getInstance("DOM");

The objects that this factory produces will be based on DOM and abide by the DOM interoperability requirements as defined in the DOM Mechanism Requirements section of the API overview. See the Service Providers section of the API overview for a list of standard mechanism types.

XMLSignatureFactory implementations are registered and loaded using the Provider mechanism. For example, a service provider that supports the DOM mechanism would be specified in the Provider subclass as:

     put("XMLSignatureFactory.DOM", "org.example.DOMXMLSignatureFactory");

An implementation MUST minimally support the default mechanism type: DOM.

Note that a caller must use the same XMLSignatureFactory instance to create the XMLStructures of a particular XMLSignature that is to be generated. The behavior is undefined if XMLStructures from different providers or different mechanism types are used together.

Also, the XMLStructures that are created by this factory may contain state specific to the XMLSignature and are not intended to be reusable.

Creating XMLSignatures from scratch

Once the XMLSignatureFactory has been created, objects can be instantiated by calling the appropriate method. For example, a Reference instance may be created by invoking one of the newReference methods.

Unmarshalling XMLSignatures from XML

Alternatively, an XMLSignature may be created from an existing XML representation by invoking the unmarshalXMLSignature method and passing it a mechanism-specific XMLValidateContext instance containing the XML content:

 DOMValidateContext context = new DOMValidateContext(key, signatureElement);
 XMLSignature signature = factory.unmarshalXMLSignature(context);
Each XMLSignatureFactory must support the required XMLValidateContext types for that factory type, but may support others. A DOM XMLSignatureFactory must support DOMValidateContext objects.

Signing and marshalling XMLSignatures to XML

Each XMLSignature created by the factory can also be marshalled to an XML representation and signed, by invoking the sign method of the XMLSignature object and passing it a mechanism-specific XMLSignContext object containing the signing key and marshalling parameters (see DOMSignContext). For example:
    DOMSignContext context = new DOMSignContext(privateKey, document);
    signature.sign(context);
Concurrent Access

The static methods of this class are guaranteed to be thread-safe. Multiple threads may concurrently invoke the static methods defined in this class with no ill effects.

However, this is not true for the non-static methods defined by this class. Unless otherwise documented by a specific provider, threads that need to access a single XMLSignatureFactory instance concurrently should synchronize amongst themselves and provide the necessary locking. Multiple threads each manipulating a different XMLSignatureFactory instance need not synchronize.

Since:
1.6

Constructor Summary
protected XMLSignatureFactory()
Default constructor, for invocation by subclasses.
Method Summary
static XMLSignatureFactory | getInstance() Returns an XMLSignatureFactory that supports the default XML processing mechanism and representation type ("DOM").
static XMLSignatureFactory | getInstance(String mechanismType) Returns an XMLSignatureFactory that supports the specified XML processing mechanism and representation type (ex: "DOM").
static XMLSignatureFactory | getInstance(String mechanismType, Provider provider) Returns an XMLSignatureFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.
static XMLSignatureFactory | getInstance(String mechanismType, String provider) Returns an XMLSignatureFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider.
KeyInfoFactory | getKeyInfoFactory() Returns a KeyInfoFactory that creates KeyInfo objects.
String | getMechanismType() Returns the type of the XML processing mechanism and representation supported by this XMLSignatureFactory (ex: "DOM").
Provider | getProvider() Returns the provider of this XMLSignatureFactory.
abstract URIDereferencer | getURIDereferencer() Returns a reference to the URIDereferencer that is used by default to dereference URIs in Reference objects.
abstract boolean | isFeatureSupported(String feature) Indicates whether a specified feature is supported.
abstract CanonicalizationMethod | newCanonicalizationMethod(String algorithm, C14NMethodParameterSpec params) Creates a CanonicalizationMethod for the specified algorithm URI and parameters.
abstract CanonicalizationMethod | newCanonicalizationMethod(String algorithm, XMLStructure params) Creates a CanonicalizationMethod for the specified algorithm URI and parameters.
abstract DigestMethod | newDigestMethod(String algorithm, DigestMethodParameterSpec params) Creates a DigestMethod for the specified algorithm URI and parameters.
abstract Manifest | newManifest(List references) Creates a Manifest containing the specified list of References.
abstract Manifest | newManifest(List references, String id) Creates a Manifest containing the specified list of References and optional id.
abstract Reference | newReference(String uri, DigestMethod dm) Creates a Reference with the specified URI and digest method.
abstract Reference | newReference(String uri, DigestMethod dm, List appliedTransforms, Data result, List transforms, String type, String id) Creates a Reference with the specified parameters.
abstract Reference | newReference(String uri, DigestMethod dm, List transforms, String type, String id) Creates a Reference with the specified parameters.
abstract Reference | newReference(String uri, DigestMethod dm, List transforms, String type, String id, byte[] digestValue) Creates a Reference with the specified parameters and pre-calculated digest value.
abstract SignatureMethod | newSignatureMethod(String algorithm, SignatureMethodParameterSpec params) Creates a SignatureMethod for the specified algorithm URI and parameters.
abstract SignatureProperties | newSignatureProperties(List properties, String id) Creates a SignatureProperties containing the specified list of SignaturePropertys and optional id.
abstract SignatureProperty | newSignatureProperty(List content, String target, String id) Creates a SignatureProperty containing the specified list of XMLStructures, target URI and optional id.
abstract SignedInfo | newSignedInfo(CanonicalizationMethod cm, SignatureMethod sm, List references) Creates a SignedInfo with the specified canonicalization and signature methods, and list of one or more references.
abstract SignedInfo | newSignedInfo(CanonicalizationMethod cm, SignatureMethod sm, List references, String id) Creates a SignedInfo with the specified parameters.
abstract Transform | newTransform(String algorithm, TransformParameterSpec params) Creates a Transform for the specified algorithm URI and parameters.
abstract Transform | newTransform(String algorithm, XMLStructure params) Creates a Transform for the specified algorithm URI and parameters.
abstract XMLObject | newXMLObject(List content, String id, String mimeType, String encoding) Creates an XMLObject from the specified parameters.
abstract XMLSignature | newXMLSignature(SignedInfo si, KeyInfo ki) Creates an XMLSignature and initializes it with the contents of the specified SignedInfo and KeyInfo objects.
abstract XMLSignature | newXMLSignature(SignedInfo si, KeyInfo ki, List objects, String id, String signatureValueId) Creates an XMLSignature and initializes it with the specified parameters.
abstract XMLSignature | unmarshalXMLSignature(XMLStructure xmlStructure) Unmarshals a new XMLSignature instance from a mechanism-specific XMLStructure instance.
abstract XMLSignature | unmarshalXMLSignature(XMLValidateContext context) Unmarshals a new XMLSignature instance from a mechanism-specific XMLValidateContext instance.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XMLSignatureFactory

protected XMLSignatureFactory()
Default constructor, for invocation by subclasses.

Method Detail

getInstance

public static XMLSignatureFactory getInstance(String mechanismType)
Returns an XMLSignatureFactory that supports the specified XML processing mechanism and representation type (ex: "DOM").

This method uses the standard JCA provider lookup mechanism to locate and instantiate an XMLSignatureFactory implementation of the desired mechanism type. It traverses the list of registered security Providers, starting with the most preferred Provider. A new XMLSignatureFactory object from the first Provider that supports the specified mechanism is returned.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters:
mechanismType - the type of the XML processing mechanism and representation. See the Service Providers section of the API overview for a list of standard mechanism types.
Returns:
a new XMLSignatureFactory
Throws:
NullPointerException - if mechanismType is null
NoSuchMechanismException - if no Provider supports an XMLSignatureFactory implementation for the specified mechanism
See Also:
Provider

getInstance

public static XMLSignatureFactory getInstance(String mechanismType,
                                              Provider provider)
Returns an XMLSignatureFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider. Note that the specified Provider object does not have to be registered in the provider list.

Parameters:
mechanismType - the type of the XML processing mechanism and representation. See the Service Providers section of the API overview for a list of standard mechanism types.
provider - the Provider object
Returns:
a new XMLSignatureFactory
Throws:
NullPointerException - if provider or mechanismType is null
NoSuchMechanismException - if an XMLSignatureFactory implementation for the specified mechanism is not available from the specified Provider object
See Also:
Provider

getInstance

public static XMLSignatureFactory getInstance(String mechanismType,
                                              String provider)
                                       throws NoSuchProviderException
Returns an XMLSignatureFactory that supports the requested XML processing mechanism and representation type (ex: "DOM"), as supplied by the specified provider. The specified provider must be registered in the security provider list.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Parameters:
mechanismType - the type of the XML processing mechanism and representation. See the Service Providers section of the API overview for a list of standard mechanism types.
provider - the string name of the provider
Returns:
a new XMLSignatureFactory
Throws:
NoSuchProviderException - if the specified provider is not registered in the security provider list
NullPointerException - if provider or mechanismType is null
NoSuchMechanismException - if an XMLSignatureFactory implementation for the specified mechanism is not available from the specified provider
See Also:
Provider

getInstance

public static XMLSignatureFactory getInstance()
Returns an XMLSignatureFactory that supports the default XML processing mechanism and representation type ("DOM").

This method uses the standard JCA provider lookup mechanism to locate and instantiate an XMLSignatureFactory implementation of the default mechanism type. It traverses the list of registered security Providers, starting with the most preferred Provider. A new XMLSignatureFactory object from the first Provider that supports the DOM mechanism is returned.

Note that the list of registered providers may be retrieved via the Security.getProviders() method.

Returns:
a new XMLSignatureFactory
Throws:
NoSuchMechanismException - if no Provider supports an XMLSignatureFactory implementation for the DOM mechanism
See Also:
Provider

getMechanismType

public final String getMechanismType()
Returns the type of the XML processing mechanism and representation supported by this XMLSignatureFactory (ex: "DOM").

Returns:
the XML processing mechanism type supported by this XMLSignatureFactory

getProvider

public final Provider getProvider()
Returns the provider of this XMLSignatureFactory.

Returns:
the provider of this XMLSignatureFactory

newXMLSignature

public abstract XMLSignature newXMLSignature(SignedInfo si,
                                             KeyInfo ki)
Creates an XMLSignature and initializes it with the contents of the specified SignedInfo and KeyInfo objects.

Parameters:
si - the signed info
ki - the key info (may be null)
Returns:
an XMLSignature
Throws:
NullPointerException - if si is null

newXMLSignature

public abstract XMLSignature newXMLSignature(SignedInfo si,
                                             KeyInfo ki,
                                             List objects,
                                             String id,
                                             String signatureValueId)
Creates an XMLSignature and initializes it with the specified parameters.

Parameters:
si - the signed info
ki - the key info (may be null)
objects - a list of XMLObjects (may be empty or null)
id - the Id (may be null)
signatureValueId - the SignatureValue Id (may be null)
Returns:
an XMLSignature
Throws:
NullPointerException - if si is null
ClassCastException - if any of the objects are not of type XMLObject

newReference

public abstract Reference newReference(String uri,
                                       DigestMethod dm)
Creates a Reference with the specified URI and digest method.

Parameters:
uri - the reference URI (may be null)
dm - the digest method
Returns:
a Reference
Throws:
IllegalArgumentException - if uri is not RFC 2396 compliant
NullPointerException - if dm is null

newReference

public abstract Reference newReference(String uri,
                                       DigestMethod dm,
                                       List transforms,
                                       String type,
                                       String id)
Creates a Reference with the specified parameters.

Parameters:
uri - the reference URI (may be null)
dm - the digest method
transforms - a list of Transforms. The list is defensively copied to protect against subsequent modification. May be null or empty.
type - the reference type, as a URI (may be null)
id - the reference ID (may be null)
Returns:
a Reference
Throws:
ClassCastException - if any of the transforms are not of type Transform
IllegalArgumentException - if uri is not RFC 2396 compliant
NullPointerException - if dm is null

newReference

public abstract Reference newReference(String uri,
                                       DigestMethod dm,
                                       List transforms,
                                       String type,
                                       String id,
                                       byte[] digestValue)
Creates a Reference with the specified parameters and pre-calculated digest value.

This method is useful when the digest value of a Reference has been previously computed. See for example, the OASIS-DSS (Digital Signature Services) specification.

Parameters:
uri - the reference URI (may be null)
dm - the digest method
transforms - a list of Transforms. The list is defensively copied to protect against subsequent modification. May be null or empty.
type - the reference type, as a URI (may be null)
id - the reference ID (may be null)
digestValue - the digest value. The array is cloned to protect against subsequent modification.
Returns:
a Reference
Throws:
ClassCastException - if any of the transforms are not of type Transform
IllegalArgumentException - if uri is not RFC 2396 compliant
NullPointerException - if dm or digestValue is null

newReference

public abstract Reference newReference(String uri,
                                       DigestMethod dm,
                                       List appliedTransforms,
                                       Data result,
                                       List transforms,
                                       String type,
                                       String id)
Creates a Reference with the specified parameters.

This method is useful when a list of transforms have already been applied to the Reference. See for example, the OASIS-DSS (Digital Signature Services) specification.

When an XMLSignature containing this reference is generated, the specified transforms (if non-null) are applied to the specified result. The Transforms element of the resulting Reference element is set to the concatenation of the appliedTransforms and transforms.

Parameters:
uri - the reference URI (may be null)
dm - the digest method
appliedTransforms - a list of Transforms that have already been applied. The list is defensively copied to protect against subsequent modification. The list must contain at least one entry.
result - the result of processing the sequence of appliedTransforms
transforms - a list of Transforms that are to be applied when generating the signature. The list is defensively copied to protect against subsequent modification. May be null or empty.
type - the reference type, as a URI (may be null)
id - the reference ID (may be null)
Returns:
a Reference
Throws:
ClassCastException - if any of the transforms (in either list) are not of type Transform
IllegalArgumentException - if uri is not RFC 2396 compliant or appliedTransforms is empty
NullPointerException - if dm, appliedTransforms or result is null

newSignedInfo

public abstract SignedInfo newSignedInfo(CanonicalizationMethod cm,
                                         SignatureMethod sm,
                                         List references)
Creates a SignedInfo with the specified canonicalization and signature methods, and list of one or more references.

Parameters:
cm - the canonicalization method
sm - the signature method
references - a list of one or more References. The list is defensively copied to protect against subsequent modification.
Returns:
a SignedInfo
Throws:
ClassCastException - if any of the references are not of type Reference
IllegalArgumentException - if references is empty
NullPointerException - if any of the parameters are null

newSignedInfo

public abstract SignedInfo newSignedInfo(CanonicalizationMethod cm,
                                         SignatureMethod sm,
                                         List references,
                                         String id)
Creates a SignedInfo with the specified parameters.

Parameters:
cm - the canonicalization method
sm - the signature method
references - a list of one or more References. The list is defensively copied to protect against subsequent modification.
id - the id (may be null)
Returns:
a SignedInfo
Throws:
ClassCastException - if any of the references are not of type Reference
IllegalArgumentException - if references is empty
NullPointerException - if cm, sm, or references are null

newXMLObject

public abstract XMLObject newXMLObject(List content,
                                       String id,
                                       String mimeType,
                                       String encoding)
Creates an XMLObject from the specified parameters.

Parameters:
content - a list of XMLStructures. The list is defensively copied to protect against subsequent modification. May be null or empty.
id - the Id (may be null)
mimeType - the mime type (may be null)
encoding - the encoding (may be null)
Returns:
an XMLObject
Throws:
ClassCastException - if content contains any entries that are not of type XMLStructure

newManifest

public abstract Manifest newManifest(List references)
Creates a Manifest containing the specified list of References.

Parameters:
references - a list of one or more References. The list is defensively copied to protect against subsequent modification.
Returns:
a Manifest
Throws:
NullPointerException - if references is null
IllegalArgumentException - if references is empty
ClassCastException - if references contains any entries that are not of type Reference

newManifest

public abstract Manifest newManifest(List references,
                                     String id)
Creates a Manifest containing the specified list of References and optional id.

Parameters:
references - a list of one or more References. The list is defensively copied to protect against subsequent modification.
id - the id (may be null)
Returns:
a Manifest
Throws:
NullPointerException - if references is null
IllegalArgumentException - if references is empty
ClassCastException - if references contains any entries that are not of type Reference

newSignatureProperty

public abstract SignatureProperty newSignatureProperty(List content,
                                                       String target,
                                                       String id)
Creates a SignatureProperty containing the specified list of XMLStructures, target URI and optional id.

Parameters:
content - a list of one or more XMLStructures. The list is defensively copied to protect against subsequent modification.
target - the target URI of the Signature that this property applies to
id - the id (may be null)
Returns:
a SignatureProperty
Throws:
NullPointerException - if content or target is null
IllegalArgumentException - if content is empty
ClassCastException - if content contains any entries that are not of type XMLStructure

newSignatureProperties

public abstract SignatureProperties newSignatureProperties(List properties,
                                                           String id)
Creates a SignatureProperties containing the specified list of SignaturePropertys and optional id.

Parameters:
properties - a list of one or more SignaturePropertys. The list is defensively copied to protect against subsequent modification.
id - the id (may be null)
Returns:
a SignatureProperties
Throws:
NullPointerException - if properties is null
IllegalArgumentException - if properties is empty
ClassCastException - if properties contains any entries that are not of type SignatureProperty

newDigestMethod

public abstract DigestMethod newDigestMethod(String algorithm,
                                             DigestMethodParameterSpec params)
                                      throws NoSuchAlgorithmException,
                                             InvalidAlgorithmParameterException
Creates a DigestMethod for the specified algorithm URI and parameters.

Parameters:
algorithm - the URI identifying the digest algorithm
params - algorithm-specific digest parameters (may be null)
Returns:
the DigestMethod
Throws:
InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm
NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
NullPointerException - if algorithm is null

newSignatureMethod

public abstract SignatureMethod newSignatureMethod(String algorithm,
                                                   SignatureMethodParameterSpec params)
                                            throws NoSuchAlgorithmException,
                                                   InvalidAlgorithmParameterException
Creates a SignatureMethod for the specified algorithm URI and parameters.

Parameters:
algorithm - the URI identifying the signature algorithm
params - algorithm-specific signature parameters (may be null)
Returns:
the SignatureMethod
Throws:
InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm
NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
NullPointerException - if algorithm is null

newTransform

public abstract Transform newTransform(String algorithm,
                                       TransformParameterSpec params)
                                throws NoSuchAlgorithmException,
                                       InvalidAlgorithmParameterException
Creates a Transform for the specified algorithm URI and parameters.

Parameters:
algorithm - the URI identifying the transform algorithm
params - algorithm-specific transform parameters (may be null)
Returns:
the Transform
Throws:
InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm
NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
NullPointerException - if algorithm is null

newTransform

public abstract Transform newTransform(String algorithm,
                                       XMLStructure params)
                                throws NoSuchAlgorithmException,
                                       InvalidAlgorithmParameterException
Creates a Transform for the specified algorithm URI and parameters. The parameters are specified as a mechanism-specific XMLStructure (ex: DOMStructure). This method is useful when the parameters are in XML form or there is no standard class for specifying the parameters.

Parameters:
algorithm - the URI identifying the transform algorithm
params - a mechanism-specific XML structure from which to unmarshal the parameters from (may be null if not required or optional)
Returns:
the Transform
Throws:
ClassCastException - if the type of params is inappropriate for this XMLSignatureFactory
InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm
NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
NullPointerException - if algorithm is null

newCanonicalizationMethod

public abstract CanonicalizationMethod newCanonicalizationMethod(String algorithm,
                                                                 C14NMethodParameterSpec params)
                                                          throws NoSuchAlgorithmException,
                                                                 InvalidAlgorithmParameterException
Creates a CanonicalizationMethod for the specified algorithm URI and parameters.

Parameters:
algorithm - the URI identifying the canonicalization algorithm
params - algorithm-specific canonicalization parameters (may be null)
Returns:
the CanonicalizationMethod
Throws:
InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm
NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
NullPointerException - if algorithm is null

newCanonicalizationMethod

public abstract CanonicalizationMethod newCanonicalizationMethod(String algorithm,
                                                                 XMLStructure params)
                                                          throws NoSuchAlgorithmException,
                                                                 InvalidAlgorithmParameterException
Creates a CanonicalizationMethod for the specified algorithm URI and parameters. The parameters are specified as a mechanism-specific XMLStructure (ex: DOMStructure). This method is useful when the parameters are in XML form or there is no standard class for specifying the parameters.

Parameters:
algorithm - the URI identifying the canonicalization algorithm
params - a mechanism-specific XML structure from which to unmarshal the parameters from (may be null if not required or optional)
Returns:
the CanonicalizationMethod
Throws:
ClassCastException - if the type of params is inappropriate for this XMLSignatureFactory
InvalidAlgorithmParameterException - if the specified parameters are inappropriate for the requested algorithm
NoSuchAlgorithmException - if an implementation of the specified algorithm cannot be found
NullPointerException - if algorithm is null

getKeyInfoFactory

public final KeyInfoFactory getKeyInfoFactory()
Returns a KeyInfoFactory that creates KeyInfo objects. The returned KeyInfoFactory has the same mechanism type and provider as this XMLSignatureFactory.

Returns:
a KeyInfoFactory
Throws:
NoSuchMechanismException - if a KeyFactory implementation with the same mechanism type and provider is not available

unmarshalXMLSignature

public abstract XMLSignature unmarshalXMLSignature(XMLValidateContext context)
                                            throws MarshalException
Unmarshals a new XMLSignature instance from a mechanism-specific XMLValidateContext instance.

Parameters:
context - a mechanism-specific context from which to unmarshal the signature from
Returns:
the XMLSignature
Throws:
NullPointerException - if context is null
ClassCastException - if the type of context is inappropriate for this factory
MarshalException - if an unrecoverable exception occurs during unmarshalling

unmarshalXMLSignature

public abstract XMLSignature unmarshalXMLSignature(XMLStructure xmlStructure)
                                            throws MarshalException
Unmarshals a new XMLSignature instance from a mechanism-specific XMLStructure instance. This method is useful if you only want to unmarshal (and not validate) an XMLSignature.

Parameters:
xmlStructure - a mechanism-specific XML structure from which to unmarshal the signature from
Returns:
the XMLSignature
Throws:
NullPointerException - if xmlStructure is null
ClassCastException - if the type of xmlStructure is inappropriate for this factory
MarshalException - if an unrecoverable exception occurs during unmarshalling

isFeatureSupported

public abstract boolean isFeatureSupported(String feature)
Indicates whether a specified feature is supported.

Parameters:
feature - the feature name (as an absolute URI)
Returns:
true if the specified feature is supported, false otherwise
Throws:
NullPointerException - if feature is null

getURIDereferencer

public abstract URIDereferencer getURIDereferencer()
Returns a reference to the URIDereferencer that is used by default to dereference URIs in Reference objects.

Returns:
a reference to the default URIDereferencer (never null)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLSignContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Interface XMLSignContext

All Superinterfaces:
XMLCryptoContext
All Known Implementing Classes:
DOMSignContext
public interface XMLSignContext
extends XMLCryptoContext

Contains context information for generating XML Signatures. This interface is primarily intended for type-safety.

Note that XMLSignContext instances can contain information and state specific to the XML signature structure it is used with. The results are unpredictable if an XMLSignContext is used with different signature structures (for example, you should not use the same XMLSignContext instance to sign two different XMLSignature objects).

Supported Properties

The following properties can be set using the setProperty method.

  • javax.xml.crypto.dsig.cacheReference: value must be a Boolean. This property controls whether or not the digested Reference objects will cache the dereferenced content and pre-digested input for subsequent retrieval via the Reference.getDereferencedData and Reference.getDigestInputStream methods. The default value if not specified is Boolean.FALSE.

Since:
1.6
See Also:
XMLSignature.sign(XMLSignContext)

Method Summary
Methods inherited from interface javax.xml.crypto.XMLCryptoContext
get, getBaseURI, getDefaultNamespacePrefix, getKeySelector, getNamespacePrefix, getProperty, getURIDereferencer, put, putNamespacePrefix, setBaseURI, setDefaultNamespacePrefix, setKeySelector, setProperty, setURIDereferencer

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLValidateContext

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto.dsig
Interface XMLValidateContext

All Superinterfaces:
XMLCryptoContext
All Known Implementing Classes:
DOMValidateContext
public interface XMLValidateContext
extends XMLCryptoContext

Contains context information for validating XML Signatures. This interface is primarily intended for type-safety.

Note that XMLValidateContext instances can contain information and state specific to the XML signature structure it is used with. The results are unpredictable if an XMLValidateContext is used with different signature structures (for example, you should not use the same XMLValidateContext instance to validate two different XMLSignature objects).

Supported Properties

The following properties can be set by an application using the setProperty method.

  • javax.xml.crypto.dsig.cacheReference: value must be a Boolean. This property controls whether or not the Reference.validate method will cache the dereferenced content and pre-digested input for subsequent retrieval via the Reference.getDereferencedData and Reference.getDigestInputStream methods. The default value if not specified is Boolean.FALSE.

Since:
1.6
See Also:
XMLSignature.validate(XMLValidateContext), Reference.validate(XMLValidateContext)

Method Summary
Methods inherited from interface javax.xml.crypto.XMLCryptoContext
get, getBaseURI, getDefaultNamespacePrefix, getKeySelector, getNamespacePrefix, getProperty, getURIDereferencer, put, putNamespacePrefix, setBaseURI, setDefaultNamespacePrefix, setKeySelector, setProperty, setURIDereferencer

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


KeySelector

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto
Class KeySelector

java.lang.Object
    extended by  javax.xml.crypto.KeySelector

public abstract class KeySelector
extends Object

A selector that finds and returns a key using the data contained in a KeyInfo object. An example of an implementation of this class is one that searchs a KeyStore for trusted keys that match information contained in a KeyInfo.

Whether or not the returned key is trusted and the mechanisms used to determine that is implementation-specific.

Since:
1.6

Nested Class Summary
static class KeySelector.Purpose
The purpose of the key that is to be selected.
Constructor Summary
protected KeySelector()
Default no-args constructor; intended for invocation by subclasses only.
Method Summary
abstract KeySelectorResult | select(KeyInfo keyInfo, KeySelector.Purpose purpose, AlgorithmMethod method, XMLCryptoContext context) Attempts to find a key that satisfies the specified constraints.
static KeySelector | singletonKeySelector(Key key) Returns a KeySelector that always selects the specified key, regardless of the KeyInfo passed to it.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

KeySelector

protected KeySelector()
Default no-args constructor; intended for invocation by subclasses only.

Method Detail

select

public abstract KeySelectorResult select(KeyInfo keyInfo,
                                         KeySelector.Purpose purpose,
                                         AlgorithmMethod method,
                                         XMLCryptoContext context)
                                  throws KeySelectorException
Attempts to find a key that satisfies the specified constraints.

Parameters:
keyInfo - a KeyInfo (may be null)
purpose - the key's purpose (KeySelector.Purpose.SIGN, KeySelector.Purpose.VERIFY, KeySelector.Purpose.ENCRYPT, or KeySelector.Purpose.DECRYPT)
method - the algorithm method that this key is to be used for. Only keys that are compatible with the algorithm and meet the constraints of the specified algorithm should be returned.
context - an XMLCryptoContext that may contain useful information for finding an appropriate key. If this key selector supports resolving RetrievalMethod types, the context's baseURI and dereferencer parameters (if specified) should be used by the selector to resolve and dereference the URI.
Returns:
the result of the key selector
Throws:
KeySelectorException - if an exceptional condition occurs while attempting to find a key. Note that an inability to find a key is not considered an exception (null should be returned in that case). However, an error condition (ex: network communications failure) that prevented the KeySelector from finding a potential key should be considered an exception.
ClassCastException - if the data type of method is not supported by this key selector

singletonKeySelector

public static KeySelector singletonKeySelector(Key key)
Returns a KeySelector that always selects the specified key, regardless of the KeyInfo passed to it.

Parameters:
key - the sole key to be stored in the key selector
Returns:
a key selector that always selects the specified key
Throws:
NullPointerException - if key is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


KeySelector.Purpose

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto
Class KeySelector.Purpose

java.lang.Object
    extended by  javax.xml.crypto.KeySelector.Purpose
Enclosing class:
KeySelector
public static class KeySelector.Purpose
extends Object

The purpose of the key that is to be selected.

Field Summary
static KeySelector.Purpose | DECRYPT A key for decrypting.
static KeySelector.Purpose | ENCRYPT A key for encrypting.
static KeySelector.Purpose | SIGN A key for signing.
static KeySelector.Purpose | VERIFY A key for verifying.
Method Summary
 String toString()
Returns a string representation of this purpose ("sign", "verify", "encrypt", or "decrypt").
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

SIGN

public static final KeySelector.Purpose SIGN
A key for signing.

VERIFY

public static final KeySelector.Purpose VERIFY
A key for verifying.

ENCRYPT

public static final KeySelector.Purpose ENCRYPT
A key for encrypting.

DECRYPT

public static final KeySelector.Purpose DECRYPT
A key for decrypting.

Method Detail

toString

public String toString()
Returns a string representation of this purpose ("sign", "verify", "encrypt", or "decrypt").

Overrides:
toString in class Object
Returns:
a string representation of this purpose
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


KeySelectorException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto
Class KeySelectorException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.crypto.KeySelectorException
All Implemented Interfaces:
Serializable
public class KeySelectorException
extends Exception

Indicates an exceptional condition thrown by a KeySelector.

A KeySelectorException can contain a cause: another throwable that caused this KeySelectorException to get thrown.

Since:
1.6
See Also:
Serialized Form

Constructor Summary
KeySelectorException()
Constructs a new KeySelectorException with null as its detail message.
KeySelectorException(String message)
Constructs a new KeySelectorException with the specified detail message.
KeySelectorException(String message, Throwable cause)
Constructs a new KeySelectorException with the specified detail message and cause.
KeySelectorException(Throwable cause)
Constructs a new KeySelectorException with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).
Method Summary
Throwable | getCause() Returns the cause of this KeySelectorException or null if the cause is nonexistent or unknown.
void | printStackTrace() Prints this KeySelectorException, its backtrace and the cause's backtrace to the standard error stream.
void | printStackTrace(PrintStream s) Prints this KeySelectorException, its backtrace and the cause's backtrace to the specified print stream.
void | printStackTrace(PrintWriter s) Prints this KeySelectorException, its backtrace and the cause's backtrace to the specified print writer.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

KeySelectorException

public KeySelectorException()
Constructs a new KeySelectorException with null as its detail message.

KeySelectorException

public KeySelectorException(String message)
Constructs a new KeySelectorException with the specified detail message.

Parameters:
message - the detail message

KeySelectorException

public KeySelectorException(String message,
                            Throwable cause)
Constructs a new KeySelectorException with the specified detail message and cause.

Note that the detail message associated with cause is not automatically incorporated in this exception's detail message.

Parameters:
message - the detail message
cause - the cause (A null value is permitted, and indicates that the cause is nonexistent or unknown.)

KeySelectorException

public KeySelectorException(Throwable cause)
Constructs a new KeySelectorException with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).

Parameters:
cause - the cause (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
Method Detail

getCause

public Throwable getCause()
Returns the cause of this KeySelectorException or null if the cause is nonexistent or unknown. (The cause is the throwable that caused this KeySelectorException to get thrown.)

Overrides:
getCause in class Throwable
Returns:
the cause of this KeySelectorException or null if the cause is nonexistent or unknown.

printStackTrace

public void printStackTrace()
Prints this KeySelectorException, its backtrace and the cause's backtrace to the standard error stream.

Overrides:
printStackTrace in class Throwable

printStackTrace

public void printStackTrace(PrintStream s)
Prints this KeySelectorException, its backtrace and the cause's backtrace to the specified print stream.

Overrides:
printStackTrace in class Throwable
Parameters:
s - PrintStream to use for output

printStackTrace

public void printStackTrace(PrintWriter s)
Prints this KeySelectorException, its backtrace and the cause's backtrace to the specified print writer.

Overrides:
printStackTrace in class Throwable
Parameters:
s - PrintWriter to use for output
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


KeySelectorResult

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto
Interface KeySelectorResult

public interface KeySelectorResult

The result returned by the KeySelector.select method.

At a minimum, a KeySelectorResult contains the Key selected by the KeySelector. Implementations of this interface may add methods to return implementation or algorithm specific information, such as a chain of certificates or debugging information.

Since:
1.6
See Also:
KeySelector

Method Summary
 Key getKey()
Returns the selected key.

Method Detail

getKey

Key getKey()
Returns the selected key.

Returns:
the selected key, or null if none can be found
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MarshalException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto
Class MarshalException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.crypto.MarshalException
All Implemented Interfaces:
Serializable
public class MarshalException
extends Exception

Indicates an exceptional condition that occured during the XML marshalling or unmarshalling process.

A MarshalException can contain a cause: another throwable that caused this MarshalException to get thrown.

Since:
1.6
See Also:
XMLSignature.sign(XMLSignContext), XMLSignatureFactory.unmarshalXMLSignature(XMLValidateContext), Serialized Form

Constructor Summary
MarshalException()
Constructs a new MarshalException with null as its detail message.
MarshalException(String message)
Constructs a new MarshalException with the specified detail message.
MarshalException(String message, Throwable cause)
Constructs a new MarshalException with the specified detail message and cause.
MarshalException(Throwable cause)
Constructs a new MarshalException with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).
Method Summary
Throwable | getCause() Returns the cause of this MarshalException or null if the cause is nonexistent or unknown.
void | printStackTrace() Prints this MarshalException, its backtrace and the cause's backtrace to the standard error stream.
void | printStackTrace(PrintStream s) Prints this MarshalException, its backtrace and the cause's backtrace to the specified print stream.
void | printStackTrace(PrintWriter s) Prints this MarshalException, its backtrace and the cause's backtrace to the specified print writer.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MarshalException

public MarshalException()
Constructs a new MarshalException with null as its detail message.

MarshalException

public MarshalException(String message)
Constructs a new MarshalException with the specified detail message.

Parameters:
message - the detail message

MarshalException

public MarshalException(String message,
                        Throwable cause)
Constructs a new MarshalException with the specified detail message and cause.

Note that the detail message associated with cause is not automatically incorporated in this exception's detail message.

Parameters:
message - the detail message
cause - the cause (A null value is permitted, and indicates that the cause is nonexistent or unknown.)

MarshalException

public MarshalException(Throwable cause)
Constructs a new MarshalException with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).

Parameters:
cause - the cause (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
Method Detail

getCause

public Throwable getCause()
Returns the cause of this MarshalException or null if the cause is nonexistent or unknown. (The cause is the throwable that caused this MarshalException to get thrown.)

Overrides:
getCause in class Throwable
Returns:
the cause of this MarshalException or null if the cause is nonexistent or unknown.

printStackTrace

public void printStackTrace()
Prints this MarshalException, its backtrace and the cause's backtrace to the standard error stream.

Overrides:
printStackTrace in class Throwable

printStackTrace

public void printStackTrace(PrintStream s)
Prints this MarshalException, its backtrace and the cause's backtrace to the specified print stream.

Overrides:
printStackTrace in class Throwable
Parameters:
s - PrintStream to use for output

printStackTrace

public void printStackTrace(PrintWriter s)
Prints this MarshalException, its backtrace and the cause's backtrace to the specified print writer.

Overrides:
printStackTrace in class Throwable
Parameters:
s - PrintWriter to use for output
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NodeSetData

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto
Interface NodeSetData

All Superinterfaces:
Data
public interface NodeSetData
extends Data

An abstract representation of a Data type containing a node-set. The type (class) and ordering of the nodes contained in the set are not defined by this class; instead that behavior should be defined by NodeSetData subclasses.

Since:
1.6

Method Summary
 Iterator iterator()
Returns a read-only iterator over the nodes contained in this NodeSetData in document order.

Method Detail

iterator

Iterator iterator()
Returns a read-only iterator over the nodes contained in this NodeSetData in document order. Attempts to modify the returned iterator via the remove method throw UnsupportedOperationException.

Returns:
an Iterator over the nodes in this NodeSetData in document order
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NoSuchMechanismException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto
Class NoSuchMechanismException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  javax.xml.crypto.NoSuchMechanismException
All Implemented Interfaces:
Serializable
public class NoSuchMechanismException
extends RuntimeException

This exception is thrown when a particular XML mechanism is requested but is not available in the environment.

A NoSuchMechanismException can contain a cause: another throwable that caused this NoSuchMechanismException to get thrown.

Since:
1.6
See Also:
XMLSignatureFactory.getInstance, KeyInfoFactory.getInstance, Serialized Form

Constructor Summary
NoSuchMechanismException()
Constructs a new NoSuchMechanismException with null as its detail message.
NoSuchMechanismException(String message)
Constructs a new NoSuchMechanismException with the specified detail message.
NoSuchMechanismException(String message, Throwable cause)
Constructs a new NoSuchMechanismException with the specified detail message and cause.
NoSuchMechanismException(Throwable cause)
Constructs a new NoSuchMechanismException with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).
Method Summary
Throwable | getCause() Returns the cause of this NoSuchMechanismException or null if the cause is nonexistent or unknown.
void | printStackTrace() Prints this NoSuchMechanismException, its backtrace and the cause's backtrace to the standard error stream.
void | printStackTrace(PrintStream s) Prints this NoSuchMechanismException, its backtrace and the cause's backtrace to the specified print stream.
void | printStackTrace(PrintWriter s) Prints this NoSuchMechanismException, its backtrace and the cause's backtrace to the specified print writer.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NoSuchMechanismException

public NoSuchMechanismException()
Constructs a new NoSuchMechanismException with null as its detail message.

NoSuchMechanismException

public NoSuchMechanismException(String message)
Constructs a new NoSuchMechanismException with the specified detail message.

Parameters:
message - the detail message

NoSuchMechanismException

public NoSuchMechanismException(String message,
                                Throwable cause)
Constructs a new NoSuchMechanismException with the specified detail message and cause.

Note that the detail message associated with cause is not automatically incorporated in this exception's detail message.

Parameters:
message - the detail message
cause - the cause (A null value is permitted, and indicates that the cause is nonexistent or unknown.)

NoSuchMechanismException

public NoSuchMechanismException(Throwable cause)
Constructs a new NoSuchMechanismException with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).

Parameters:
cause - the cause (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
Method Detail

getCause

public Throwable getCause()
Returns the cause of this NoSuchMechanismException or null if the cause is nonexistent or unknown. (The cause is the throwable that caused this NoSuchMechanismException to get thrown.)

Overrides:
getCause in class Throwable
Returns:
the cause of this NoSuchMechanismException or null if the cause is nonexistent or unknown.

printStackTrace

public void printStackTrace()
Prints this NoSuchMechanismException, its backtrace and the cause's backtrace to the standard error stream.

Overrides:
printStackTrace in class Throwable

printStackTrace

public void printStackTrace(PrintStream s)
Prints this NoSuchMechanismException, its backtrace and the cause's backtrace to the specified print stream.

Overrides:
printStackTrace in class Throwable
Parameters:
s - PrintStream to use for output

printStackTrace

public void printStackTrace(PrintWriter s)
Prints this NoSuchMechanismException, its backtrace and the cause's backtrace to the specified print writer.

Overrides:
printStackTrace in class Throwable
Parameters:
s - PrintWriter to use for output
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OctetStreamData

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto
Class OctetStreamData

java.lang.Object
    extended by  javax.xml.crypto.OctetStreamData
All Implemented Interfaces:
Data
public class OctetStreamData
extends Object
implements Data

A representation of a Data type containing an octet stream.

Since:
1.6

Constructor Summary
OctetStreamData(InputStream octetStream)
Creates a new OctetStreamData.
OctetStreamData(InputStream octetStream, String uri, String mimeType)
Creates a new OctetStreamData.
Method Summary
String | getMimeType() Returns the MIME type associated with the data object represented by this OctetStreamData.
InputStream | getOctetStream() Returns the input stream of this OctetStreamData.
String | getURI() Returns the URI String identifying the data object represented by this OctetStreamData.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

OctetStreamData

public OctetStreamData(InputStream octetStream)
Creates a new OctetStreamData.

Parameters:
octetStream - the input stream containing the octets
Throws:
NullPointerException - if octetStream is null

OctetStreamData

public OctetStreamData(InputStream octetStream,
                       String uri,
                       String mimeType)
Creates a new OctetStreamData.

Parameters:
octetStream - the input stream containing the octets
uri - the URI String identifying the data object (may be null)
mimeType - the MIME type associated with the data object (may be null)
Throws:
NullPointerException - if octetStream is null
Method Detail

getOctetStream

public InputStream getOctetStream()
Returns the input stream of this OctetStreamData.

Returns:
the input stream of this OctetStreamData.

getURI

public String getURI()
Returns the URI String identifying the data object represented by this OctetStreamData.

Returns:
the URI String or null if not applicable

getMimeType

public String getMimeType()
Returns the MIME type associated with the data object represented by this OctetStreamData.

Returns:
the MIME type or null if not applicable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


URIDereferencer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto
Interface URIDereferencer

public interface URIDereferencer

A dereferencer of URIReferences.

The result of dereferencing a URIReference is either an instance of OctetStreamData or NodeSetData. Unless the URIReference is a same-document reference as defined in section 4.2 of the W3C Recommendation for XML-Signature Syntax and Processing, the result of dereferencing the URIReference MUST be an OctetStreamData.

Since:
1.6
See Also:
XMLCryptoContext.setURIDereferencer(URIDereferencer), XMLCryptoContext.getURIDereferencer()

Method Summary
 Data dereference(URIReference uriReference, XMLCryptoContext context)
Dereferences the specified URIReference and returns the dereferenced data.

Method Detail

dereference

Data dereference(URIReference uriReference,
                 XMLCryptoContext context)
                 throws URIReferenceException
Dereferences the specified URIReference and returns the dereferenced data.

Parameters:
uriReference - the URIReference
context - an XMLCryptoContext that may contain additional useful information for dereferencing the URI. This implementation should dereference the specified URIReference against the context's baseURI parameter, if specified.
Returns:
the dereferenced data
Throws:
NullPointerException - if uriReference or context are null
URIReferenceException - if an exception occurs while dereferencing the specified uriReference
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


URIReference

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto
Interface URIReference

All Known Subinterfaces:
DOMURIReference, Reference, RetrievalMethod
public interface URIReference

Identifies a data object via a URI-Reference, as specified by RFC 2396.

Note that some subclasses may not have a type attribute and for objects of those types, the getType() method always returns null.

Since:
1.6
See Also:
URIDereferencer

Method Summary
String | getType() Returns the type of data referenced by this URI.
String | getURI() Returns the URI of the referenced data object.

Method Detail

getURI

String getURI()
Returns the URI of the referenced data object.

Returns:
the URI of the data object in RFC 2396 format (may be null if not specified)

getType

String getType()
Returns the type of data referenced by this URI.

Returns:
the type (a URI) of the data object (may be null if not specified)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


URIReferenceException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto
Class URIReferenceException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.crypto.URIReferenceException
All Implemented Interfaces:
Serializable
public class URIReferenceException
extends Exception

Indicates an exceptional condition thrown while dereferencing a URIReference.

A URIReferenceException can contain a cause: another throwable that caused this URIReferenceException to get thrown.

Since:
1.6
See Also:
URIDereferencer.dereference(URIReference, XMLCryptoContext), RetrievalMethod.dereference(XMLCryptoContext), Serialized Form

Constructor Summary
URIReferenceException()
Constructs a new URIReferenceException with null as its detail message.
URIReferenceException(String message)
Constructs a new URIReferenceException with the specified detail message.
URIReferenceException(String message, Throwable cause)
Constructs a new URIReferenceException with the specified detail message and cause.
URIReferenceException(String message, Throwable cause, URIReference uriReference)
Constructs a new URIReferenceException with the specified detail message, cause and URIReference.
URIReferenceException(Throwable cause)
Constructs a new URIReferenceException with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).
Method Summary
Throwable | getCause() Returns the cause of this URIReferenceException or null if the cause is nonexistent or unknown.
URIReference | getURIReference() Returns the URIReference that was being dereferenced when the exception was thrown.
void | printStackTrace() Prints this URIReferenceException, its backtrace and the cause's backtrace to the standard error stream.
void | printStackTrace(PrintStream s) Prints this URIReferenceException, its backtrace and the cause's backtrace to the specified print stream.
void | printStackTrace(PrintWriter s) Prints this URIReferenceException, its backtrace and the cause's backtrace to the specified print writer.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

URIReferenceException

public URIReferenceException()
Constructs a new URIReferenceException with null as its detail message.

URIReferenceException

public URIReferenceException(String message)
Constructs a new URIReferenceException with the specified detail message.

Parameters:
message - the detail message

URIReferenceException

public URIReferenceException(String message,
                             Throwable cause)
Constructs a new URIReferenceException with the specified detail message and cause.

Note that the detail message associated with cause is not automatically incorporated in this exception's detail message.

Parameters:
message - the detail message
cause - the cause (A null value is permitted, and indicates that the cause is nonexistent or unknown.)

URIReferenceException

public URIReferenceException(String message,
                             Throwable cause,
                             URIReference uriReference)
Constructs a new URIReferenceException with the specified detail message, cause and URIReference.

Note that the detail message associated with cause is not automatically incorporated in this exception's detail message.

Parameters:
message - the detail message
cause - the cause (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
uriReference - the URIReference that was being dereferenced when the error was encountered
Throws:
NullPointerException - if uriReference is null

URIReferenceException

public URIReferenceException(Throwable cause)
Constructs a new URIReferenceException with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).

Parameters:
cause - the cause (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
Method Detail

getURIReference

public URIReference getURIReference()
Returns the URIReference that was being dereferenced when the exception was thrown.

Returns:
the URIReference that was being dereferenced when the exception was thrown, or null if not specified

getCause

public Throwable getCause()
Returns the cause of this URIReferenceException or null if the cause is nonexistent or unknown. (The cause is the throwable that caused this URIReferenceException to get thrown.)

Overrides:
getCause in class Throwable
Returns:
the cause of this URIReferenceException or null if the cause is nonexistent or unknown.

printStackTrace

public void printStackTrace()
Prints this URIReferenceException, its backtrace and the cause's backtrace to the standard error stream.

Overrides:
printStackTrace in class Throwable

printStackTrace

public void printStackTrace(PrintStream s)
Prints this URIReferenceException, its backtrace and the cause's backtrace to the specified print stream.

Overrides:
printStackTrace in class Throwable
Parameters:
s - PrintStream to use for output

printStackTrace

public void printStackTrace(PrintWriter s)
Prints this URIReferenceException, its backtrace and the cause's backtrace to the specified print writer.

Overrides:
printStackTrace in class Throwable
Parameters:
s - PrintWriter to use for output
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLCryptoContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto
Interface XMLCryptoContext

All Known Subinterfaces:
XMLSignContext, XMLValidateContext
All Known Implementing Classes:
DOMCryptoContext, DOMSignContext, DOMValidateContext
public interface XMLCryptoContext

Contains common context information for XML cryptographic operations.

This interface contains methods for setting and retrieving properties that affect the processing of XML signatures or XML encrypted structures.

Note that XMLCryptoContext instances can contain information and state specific to the XML cryptographic structure it is used with. The results are unpredictable if an XMLCryptoContext is used with multiple structures (for example, you should not use the same XMLValidateContext instance to validate two different XMLSignature objects).

Since:
1.6

Method Summary
Object | get(Object key) Returns the value to which this context maps the specified key.
String | getBaseURI() Returns the base URI.
String | getDefaultNamespacePrefix() Returns the default namespace prefix.
KeySelector | getKeySelector() Returns the key selector for finding a key.
String | getNamespacePrefix(String namespaceURI, String defaultPrefix) Returns the namespace prefix that the specified namespace URI is associated with.
Object | getProperty(String name) Returns the value of the specified property.
URIDereferencer | getURIDereferencer() Returns a URIDereferencer that is used to dereference URIReferences.
Object | put(Object key, Object value) Associates the specified value with the specified key in this context.
String | putNamespacePrefix(String namespaceURI, String prefix) Maps the specified namespace URI to the specified prefix.
void | setBaseURI(String baseURI) Sets the base URI.
void | setDefaultNamespacePrefix(String defaultPrefix) Sets the default namespace prefix.
void | setKeySelector(KeySelector ks) Sets the key selector for finding a key.
Object | setProperty(String name, Object value) Sets the specified property.
void | setURIDereferencer(URIDereferencer dereferencer) Sets a URIDereferencer that is used to dereference URIReferences.

Method Detail

getBaseURI

String getBaseURI()
Returns the base URI.

Returns:
the base URI, or null if not specified
See Also:
setBaseURI(String)

setBaseURI

void setBaseURI(String baseURI)
Sets the base URI.

Parameters:
baseURI - the base URI, or null to remove current value
Throws:
IllegalArgumentException - if baseURI is not RFC 2396 compliant
See Also:
getBaseURI()

getKeySelector

KeySelector getKeySelector()
Returns the key selector for finding a key.

Returns:
the key selector, or null if not specified
See Also:
setKeySelector(KeySelector)

setKeySelector

void setKeySelector(KeySelector ks)
Sets the key selector for finding a key.

Parameters:
ks - the key selector, or null to remove the current setting
See Also:
getKeySelector()

getURIDereferencer

URIDereferencer getURIDereferencer()
Returns a URIDereferencer that is used to dereference URIReferences.

Returns:
the URIDereferencer, or null if not specified
See Also:
setURIDereferencer(URIDereferencer)

setURIDereferencer

void setURIDereferencer(URIDereferencer dereferencer)
Sets a URIDereferencer that is used to dereference URIReferences. The specified URIDereferencer is used in place of an implementation's default URIDereferencer.

Parameters:
dereferencer - the URIDereferencer, or null to remove any current setting
See Also:
getURIDereferencer()

getNamespacePrefix

String getNamespacePrefix(String namespaceURI,
                          String defaultPrefix)
Returns the namespace prefix that the specified namespace URI is associated with. Returns the specified default prefix if the specified namespace URI has not been bound to a prefix. To bind a namespace URI to a prefix, call the putNamespacePrefix method.

Parameters:
namespaceURI - a namespace URI
defaultPrefix - the prefix to be returned in the event that the the specified namespace URI has not been bound to a prefix.
Returns:
the prefix that is associated with the specified namespace URI, or defaultPrefix if the URI is not registered. If the namespace URI is registered but has no prefix, an empty string ("") is returned.
Throws:
NullPointerException - if namespaceURI is null
See Also:
putNamespacePrefix(String, String)

putNamespacePrefix

String putNamespacePrefix(String namespaceURI,
                          String prefix)
Maps the specified namespace URI to the specified prefix. If there is already a prefix associated with the specified namespace URI, the old prefix is replaced by the specified prefix.

Parameters:
namespaceURI - a namespace URI
prefix - a namespace prefix (or null to remove any existing mapping). Specifying the empty string ("") binds no prefix to the namespace URI.
Returns:
the previous prefix associated with the specified namespace URI, or null if there was none
Throws:
NullPointerException - if namespaceURI is null
See Also:
getNamespacePrefix(String, String)

getDefaultNamespacePrefix

String getDefaultNamespacePrefix()
Returns the default namespace prefix. The default namespace prefix is the prefix for all namespace URIs not explicitly set by the putNamespacePrefix method.

Returns:
the default namespace prefix, or null if none has been set.
See Also:
setDefaultNamespacePrefix(String)

setDefaultNamespacePrefix

void setDefaultNamespacePrefix(String defaultPrefix)
Sets the default namespace prefix. This sets the namespace prefix for all namespace URIs not explicitly set by the putNamespacePrefix method.

Parameters:
defaultPrefix - the default namespace prefix, or null to remove the current setting. Specify the empty string ("") to bind no prefix.
See Also:
getDefaultNamespacePrefix()

setProperty

Object setProperty(String name,
                   Object value)
Sets the specified property.

Parameters:
name - the name of the property
value - the value of the property to be set
Returns:
the previous value of the specified property, or null if it did not have a value
Throws:
NullPointerException - if name is null
See Also:
getProperty(String)

getProperty

Object getProperty(String name)
Returns the value of the specified property.

Parameters:
name - the name of the property
Returns:
the current value of the specified property, or null if it does not have a value
Throws:
NullPointerException - if name is null
See Also:
setProperty(String, Object)

get

Object get(Object key)
Returns the value to which this context maps the specified key.

More formally, if this context contains a mapping from a key k to a value v such that (key==null ? k==null : key.equals(k)), then this method returns v; otherwise it returns null. (There can be at most one such mapping.)

This method is useful for retrieving arbitrary information that is specific to the cryptographic operation that this context is used for.

Parameters:
key - the key whose associated value is to be returned
Returns:
the value to which this context maps the specified key, or null if there is no mapping for the key
See Also:
put(Object, Object)

put

Object put(Object key,
           Object value)
Associates the specified value with the specified key in this context. If the context previously contained a mapping for this key, the old value is replaced by the specified value.

This method is useful for storing arbitrary information that is specific to the cryptographic operation that this context is used for.

Parameters:
key - key with which the specified value is to be associated with
value - value to be associated with the specified key
Returns:
the previous value associated with the key, or null if there was no mapping for the key
Throws:
IllegalArgumentException - if some aspect of this key or value prevents it from being stored in this context
See Also:
get(Object)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLStructure

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.crypto
Interface XMLStructure

All Known Subinterfaces:
CanonicalizationMethod, DigestMethod, KeyInfo, KeyName, KeyValue, Manifest, PGPData, Reference, RetrievalMethod, SignatureMethod, SignatureProperties, SignatureProperty, SignedInfo, Transform, X509Data, X509IssuerSerial, XMLObject, XMLSignature, XMLSignature.SignatureValue
All Known Implementing Classes:
DOMStructure, TransformService
public interface XMLStructure

A representation of an XML structure from any namespace. The purpose of this interface is to group (and provide type safety for) all representations of XML structures.

Since:
1.6

Method Summary
 boolean isFeatureSupported(String feature)
Indicates whether a specified feature is supported.

Method Detail

isFeatureSupported

boolean isFeatureSupported(String feature)
Indicates whether a specified feature is supported.

Parameters:
feature - the feature name (as an absolute URI)
Returns:
true if the specified feature is supported, false otherwise
Throws:
NullPointerException - if feature is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


datatype

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.datatype

XML/Java Type Mappings.

See:
Description

Class Summary
DatatypeConstants | Utility class to contain basic Datatype values as constants.
DatatypeConstants.Field | Type-safe enum class that represents six fields of the Duration class.
DatatypeFactory | Factory that creates new javax.xml.datatype Objects that map XML to/from Java Objects.
Duration | Immutable representation of a time span as defined in the W3C XML Schema 1.0 specification.
XMLGregorianCalendar | Representation for W3C XML Schema 1.0 date/time datatypes.

Exception Summary
DatatypeConfigurationException Indicates a serious configuration error.

Package javax.xml.datatype Description

XML/Java Type Mappings.

javax.xml.datatypeAPI provides XML/Java type mappings.

The following XML standards apply:

  • W3C XML Schema 1.0 Part 2, Section 3.2.7-14
  • XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration
  • XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration
W3C XML Schema Data Type | Java Data Type
xs:date | XMLGregorianCalendar
xs:dateTime | XMLGregorianCalendar
xs:duration | Duration
xs:gDay | XMLGregorianCalendar
xs:gMonth | XMLGregorianCalendar
xs:gMonthDay | XMLGregorianCalendar
xs:gYear | XMLGregorianCalendar
xs:gYearMonth | XMLGregorianCalendar
xs:time | XMLGregorianCalendar
XQuery 1.0 and XPath 2.0 Data Model | Java Data Type
xdt:dayTimeDuration | Duration
xdt:yearMonthDuration | Duration

W3C XML Schema data types that have a "natural" mapping to Java types are defined by JSR 31: Java™ Architecture for XML Binding (JAXB) Specification, Binding XML Schema to Java Representations. JAXB defined mappings for XML Schema built-in data types include:

  • xs:anySimpleType
  • xs:base64Binary
  • xs:boolean
  • xs:byte
  • xs:decimal
  • xs:double
  • xs:float
  • xs:hexBinary
  • xs:int
  • xs:integer
  • xs:long
  • xs:QName
  • xs:short
  • xs:string
  • xs:unsignedByte
  • xs:unsignedInt
  • xs:unsignedShort
  • Author Jeff Suttor
  • See W3C XML Schema 1.0 Part 2, Section 3.2.7-14
  • See XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration
  • See XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration
  • Since 1.5

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.datatype Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.datatype

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.datatype.DatatypeConstants
    • javax.xml.datatype.DatatypeConstants.Field
    • javax.xml.datatype.DatatypeFactory
    • javax.xml.datatype.Duration
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.xml.datatype.DatatypeConfigurationException
    • javax.xml.datatype.XMLGregorianCalendar (implements java.lang.Cloneable)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.datatype

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.datatype

Packages that use javax.xml.datatype
javax.xml.datatype XML/Java Type Mappings.

Classes in javax.xml.datatype used by javax.xml.datatype
DatatypeConfigurationException
Indicates a serious configuration error.
DatatypeConstants.Field
Type-safe enum class that represents six fields of the Duration class.
DatatypeFactory
Factory that creates new javax.xml.datatype Objects that map XML to/from Java Objects.
Duration
Immutable representation of a time span as defined in the W3C XML Schema 1.0 specification.
XMLGregorianCalendar
Representation for W3C XML Schema 1.0 date/time datatypes.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.datatype.DatatypeConfigurationException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.datatype.DatatypeConfigurationException

Packages that use DatatypeConfigurationException
javax.xml.datatype XML/Java Type Mappings.

Uses of DatatypeConfigurationException in javax.xml.datatype

Methods in javax.xml.datatype that throw DatatypeConfigurationException
static DatatypeFactory | DatatypeFactory.newInstance() Obtain a new instance of a DatatypeFactory.
static DatatypeFactory | DatatypeFactory.newInstance(String factoryClassName, ClassLoader classLoader) Obtain a new instance of a DatatypeFactory from class name.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.datatype.DatatypeConstants

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.datatype.DatatypeConstants

No usage of javax.xml.datatype.DatatypeConstants

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.datatype.DatatypeConstants.Field

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.datatype.DatatypeConstants.Field

Packages that use DatatypeConstants.Field
javax.xml.datatype XML/Java Type Mappings.

Uses of DatatypeConstants.Field in javax.xml.datatype

Fields in javax.xml.datatype declared as DatatypeConstants.Field
static DatatypeConstants.Field | DatatypeConstants.DAYS A constant that represents the days field.
static DatatypeConstants.Field | DatatypeConstants.HOURS A constant that represents the hours field.
static DatatypeConstants.Field | DatatypeConstants.MINUTES A constant that represents the minutes field.
static DatatypeConstants.Field | DatatypeConstants.MONTHS A constant that represents the months field.
static DatatypeConstants.Field | DatatypeConstants.SECONDS A constant that represents the seconds field.
static DatatypeConstants.Field | DatatypeConstants.YEARS A constant that represents the years field.

Methods in javax.xml.datatype with parameters of type DatatypeConstants.Field
abstract Number | Duration.getField(DatatypeConstants.Field field) Gets the value of a field.
abstract boolean | Duration.isSet(DatatypeConstants.Field field) Checks if a field is set.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.datatype.DatatypeFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.datatype.DatatypeFactory

Packages that use DatatypeFactory
javax.xml.datatype XML/Java Type Mappings.

Uses of DatatypeFactory in javax.xml.datatype

Methods in javax.xml.datatype that return DatatypeFactory
static DatatypeFactory | DatatypeFactory.newInstance() Obtain a new instance of a DatatypeFactory.
static DatatypeFactory | DatatypeFactory.newInstance(String factoryClassName, ClassLoader classLoader) Obtain a new instance of a DatatypeFactory from class name.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.datatype.Duration

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.datatype.Duration

Packages that use Duration
javax.xml.datatype XML/Java Type Mappings.

Uses of Duration in javax.xml.datatype

Methods in javax.xml.datatype that return Duration
abstract Duration | Duration.add(Duration rhs) Computes a new duration whose value is this+rhs.
abstract Duration | Duration.multiply(BigDecimal factor) Computes a new duration whose value is factor times longer than the value of this duration.
Duration | Duration.multiply(int factor) Computes a new duration whose value is factor times longer than the value of this duration.
abstract Duration | Duration.negate() Returns a new Duration object whose value is -this.
abstract Duration | DatatypeFactory.newDuration(boolean isPositive, BigInteger years, BigInteger months, BigInteger days, BigInteger hours, BigInteger minutes, BigDecimal seconds) Obtain a new instance of a Duration specifying the Duration as isPositive, years, months, days, hours, minutes, seconds.
Duration | DatatypeFactory.newDuration(boolean isPositive, int years, int months, int days, int hours, int minutes, int seconds) Obtain a new instance of a Duration specifying the Duration as isPositive, years, months, days, hours, minutes, seconds.
abstract Duration | DatatypeFactory.newDuration(long durationInMilliSeconds) Obtain a new instance of a Duration specifying the Duration as milliseconds.
abstract Duration | DatatypeFactory.newDuration(String lexicalRepresentation) Obtain a new instance of a Duration specifying the Duration as its string representation, "PnYnMnDTnHnMnS", as defined in XML Schema 1.0 section 3.2.6.1.
Duration | DatatypeFactory.newDurationDayTime(boolean isPositive, BigInteger day, BigInteger hour, BigInteger minute, BigInteger second) Create a Duration of type xdt:dayTimeDuration using the specified day, hour, minute and second as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration.
Duration | DatatypeFactory.newDurationDayTime(boolean isPositive, int day, int hour, int minute, int second) Create a Duration of type xdt:dayTimeDuration using the specified day, hour, minute and second as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration.
Duration | DatatypeFactory.newDurationDayTime(long durationInMilliseconds) Create a Duration of type xdt:dayTimeDuration using the specified milliseconds as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration.
Duration | DatatypeFactory.newDurationDayTime(String lexicalRepresentation) Create a Duration of type xdt:dayTimeDuration by parsing its String representation, "PnDTnHnMnS", XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration.
Duration | DatatypeFactory.newDurationYearMonth(boolean isPositive, BigInteger year, BigInteger month) Create a Duration of type xdt:yearMonthDuration using the specified year and month as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration.
Duration | DatatypeFactory.newDurationYearMonth(boolean isPositive, int year, int month) Create a Duration of type xdt:yearMonthDuration using the specified year and month as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration.
Duration | DatatypeFactory.newDurationYearMonth(long durationInMilliseconds) Create a Duration of type xdt:yearMonthDuration using the specified milliseconds as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration.
Duration | DatatypeFactory.newDurationYearMonth(String lexicalRepresentation) Create a Duration of type xdt:yearMonthDuration by parsing its String representation, "PnYnM", XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration.
abstract Duration | Duration.normalizeWith(Calendar startTimeInstant) Converts the years and months fields into the days field by using a specific time instant as the reference point.
Duration | Duration.subtract(Duration rhs) Computes a new duration whose value is this-rhs.

Methods in javax.xml.datatype with parameters of type Duration
abstract void | XMLGregorianCalendar.add(Duration duration) Add duration to this instance.
abstract Duration | Duration.add(Duration rhs) Computes a new duration whose value is this+rhs.
abstract int | Duration.compare(Duration duration) Partial order relation comparison with this Duration instance.
boolean | Duration.isLongerThan(Duration duration) Checks if this duration object is strictly longer than another Duration object.
boolean | Duration.isShorterThan(Duration duration) Checks if this duration object is strictly shorter than another Duration object.
Duration | Duration.subtract(Duration rhs) Computes a new duration whose value is this-rhs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.datatype.XMLGregorianCalendar

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.datatype.XMLGregorianCalendar

Packages that use XMLGregorianCalendar
javax.xml.datatype XML/Java Type Mappings.

Uses of XMLGregorianCalendar in javax.xml.datatype

Methods in javax.xml.datatype that return XMLGregorianCalendar
abstract XMLGregorianCalendar | DatatypeFactory.newXMLGregorianCalendar() Create a new instance of an XMLGregorianCalendar.
abstract XMLGregorianCalendar | DatatypeFactory.newXMLGregorianCalendar(BigInteger year, int month, int day, int hour, int minute, int second, BigDecimal fractionalSecond, int timezone) Constructor allowing for complete value spaces allowed by W3C XML Schema 1.0 recommendation for xsd:dateTime and related builtin datatypes.
abstract XMLGregorianCalendar | DatatypeFactory.newXMLGregorianCalendar(GregorianCalendar cal) Create an XMLGregorianCalendar from a GregorianCalendar.
XMLGregorianCalendar | DatatypeFactory.newXMLGregorianCalendar(int year, int month, int day, int hour, int minute, int second, int millisecond, int timezone) Constructor of value spaces that a java.util.GregorianCalendar instance would need to convert to an XMLGregorianCalendar instance.
abstract XMLGregorianCalendar | DatatypeFactory.newXMLGregorianCalendar(String lexicalRepresentation) Create a new XMLGregorianCalendar by parsing the String as a lexical representation.
XMLGregorianCalendar | DatatypeFactory.newXMLGregorianCalendarDate(int year, int month, int day, int timezone) Create a Java representation of XML Schema builtin datatype date or g*.
XMLGregorianCalendar | DatatypeFactory.newXMLGregorianCalendarTime(int hours, int minutes, int seconds, BigDecimal fractionalSecond, int timezone) Create a Java instance of XML Schema builtin datatype time.
XMLGregorianCalendar | DatatypeFactory.newXMLGregorianCalendarTime(int hours, int minutes, int seconds, int timezone) Create a Java instance of XML Schema builtin datatype time.
XMLGregorianCalendar | DatatypeFactory.newXMLGregorianCalendarTime(int hours, int minutes, int seconds, int milliseconds, int timezone) Create a Java instance of XML Schema builtin datatype time.
abstract XMLGregorianCalendar | XMLGregorianCalendar.normalize() Normalize this instance to UTC.

Methods in javax.xml.datatype with parameters of type XMLGregorianCalendar
abstract int | XMLGregorianCalendar.compare(XMLGregorianCalendar xmlGregorianCalendar) Compare two instances of W3C XML Schema 1.0 date/time datatypes according to partial order relation defined in W3C XML Schema 1.0 Part 2, Section 3.2.7.3, Order relation on dateTime.
abstract GregorianCalendar | XMLGregorianCalendar.toGregorianCalendar(TimeZone timezone, Locale aLocale, XMLGregorianCalendar defaults) Convert this XMLGregorianCalendar along with provided parameters to a GregorianCalendar instance.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DatatypeConfigurationException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.datatype
Class DatatypeConfigurationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.datatype.DatatypeConfigurationException
All Implemented Interfaces:
Serializable
public class DatatypeConfigurationException
extends Exception

Indicates a serious configuration error.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
DatatypeConfigurationException()
Create a new DatatypeConfigurationException with no specified detail mesage and cause.
DatatypeConfigurationException(String message)
Create a new DatatypeConfigurationException with the specified detail message.
DatatypeConfigurationException(String message, Throwable cause)
Create a new DatatypeConfigurationException with the specified detail message and cause.
DatatypeConfigurationException(Throwable cause)
Create a new DatatypeConfigurationException with the specified cause.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DatatypeConfigurationException

public DatatypeConfigurationException()

Create a new DatatypeConfigurationException with no specified detail mesage and cause.

DatatypeConfigurationException

public DatatypeConfigurationException(String message)

Create a new DatatypeConfigurationException with the specified detail message.

Parameters:
message - The detail message.

DatatypeConfigurationException

public DatatypeConfigurationException(String message,
                                      Throwable cause)

Create a new DatatypeConfigurationException with the specified detail message and cause.

Parameters:
message - The detail message.
cause - The cause. A null value is permitted, and indicates that the cause is nonexistent or unknown.

DatatypeConfigurationException

public DatatypeConfigurationException(Throwable cause)

Create a new DatatypeConfigurationException with the specified cause.

Parameters:
cause - The cause. A null value is permitted, and indicates that the cause is nonexistent or unknown.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


DatatypeConstants

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.datatype
Class DatatypeConstants

java.lang.Object
    extended by  javax.xml.datatype.DatatypeConstants

public final class DatatypeConstants
extends Object

Utility class to contain basic Datatype values as constants.

Since:
1.5

Nested Class Summary
static class DatatypeConstants.Field
Type-safe enum class that represents six fields of the Duration class.
Field Summary
static int | APRIL Value for fourth month of year.
static int | AUGUST Value for eighth month of year.
static QName | DATE Fully qualified name for W3C XML Schema 1.0 datatype date.
static QName | DATETIME Fully qualified name for W3C XML Schema 1.0 datatype dateTime.
static DatatypeConstants.Field | DAYS A constant that represents the days field.
static int | DECEMBER Value for twelve month of year.
static QName | DURATION Fully qualified name for W3C XML Schema datatype duration.
static QName | DURATION_DAYTIME Fully qualified name for XQuery 1.0 and XPath 2.0 datatype dayTimeDuration.
static QName | DURATION_YEARMONTH Fully qualified name for XQuery 1.0 and XPath 2.0 datatype yearMonthDuration.
static int | EQUAL Comparison result.
static int | FEBRUARY Value for second month of year.
static int | FIELD_UNDEFINED Designation that an "int" field is not set.
static QName | GDAY Fully qualified name for W3C XML Schema 1.0 datatype gDay.
static QName | GMONTH Fully qualified name for W3C XML Schema 1.0 datatype gMonth.
static QName | GMONTHDAY Fully qualified name for W3C XML Schema 1.0 datatype gMonthDay.
static int | GREATER Comparison result.
static QName | GYEAR Fully qualified name for W3C XML Schema 1.0 datatype gYear.
static QName | GYEARMONTH Fully qualified name for W3C XML Schema 1.0 datatype gYearMonth.
static DatatypeConstants.Field | HOURS A constant that represents the hours field.
static int | INDETERMINATE Comparison result.
static int | JANUARY Value for first month of year.
static int | JULY Value for seventh month of year.
static int | JUNE Value for sixth month of year.
static int | LESSER Comparison result.
static int | MARCH Value for third month of year.
static int | MAX_TIMEZONE_OFFSET W3C XML Schema max timezone offset is -14:00.
static int | MAY Value for fifth month of year.
static int | MIN_TIMEZONE_OFFSET W3C XML Schema min timezone offset is +14:00.
static DatatypeConstants.Field | MINUTES A constant that represents the minutes field.
static DatatypeConstants.Field | MONTHS A constant that represents the months field.
static int | NOVEMBER Value for eleven month of year.
static int | OCTOBER Value for tenth month of year.
static DatatypeConstants.Field | SECONDS A constant that represents the seconds field.
static int | SEPTEMBER Value for ninth month of year.
static QName | TIME Fully qualified name for W3C XML Schema 1.0 datatype time.
static DatatypeConstants.Field | YEARS A constant that represents the years field.
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

JANUARY

public static final int JANUARY
Value for first month of year.

See Also:
Constant Field Values

FEBRUARY

public static final int FEBRUARY
Value for second month of year.

See Also:
Constant Field Values

MARCH

public static final int MARCH
Value for third month of year.

See Also:
Constant Field Values

APRIL

public static final int APRIL
Value for fourth month of year.

See Also:
Constant Field Values

MAY

public static final int MAY
Value for fifth month of year.

See Also:
Constant Field Values

JUNE

public static final int JUNE
Value for sixth month of year.

See Also:
Constant Field Values

JULY

public static final int JULY
Value for seventh month of year.

See Also:
Constant Field Values

AUGUST

public static final int AUGUST
Value for eighth month of year.

See Also:
Constant Field Values

SEPTEMBER

public static final int SEPTEMBER
Value for ninth month of year.

See Also:
Constant Field Values

OCTOBER

public static final int OCTOBER
Value for tenth month of year.

See Also:
Constant Field Values

NOVEMBER

public static final int NOVEMBER
Value for eleven month of year.

See Also:
Constant Field Values

DECEMBER

public static final int DECEMBER
Value for twelve month of year.

See Also:
Constant Field Values

LESSER

public static final int LESSER

Comparison result.

See Also:
Constant Field Values

EQUAL

public static final int EQUAL

Comparison result.

See Also:
Constant Field Values

GREATER

public static final int GREATER

Comparison result.

See Also:
Constant Field Values

INDETERMINATE

public static final int INDETERMINATE

Comparison result.

See Also:
Constant Field Values

FIELD_UNDEFINED

public static final int FIELD_UNDEFINED
Designation that an "int" field is not set.

See Also:
Constant Field Values

YEARS

public static final DatatypeConstants.Field YEARS

A constant that represents the years field.

MONTHS

public static final DatatypeConstants.Field MONTHS

A constant that represents the months field.

DAYS

public static final DatatypeConstants.Field DAYS

A constant that represents the days field.

HOURS

public static final DatatypeConstants.Field HOURS

A constant that represents the hours field.

MINUTES

public static final DatatypeConstants.Field MINUTES

A constant that represents the minutes field.

SECONDS

public static final DatatypeConstants.Field SECONDS

A constant that represents the seconds field.

DATETIME

public static final QName DATETIME

Fully qualified name for W3C XML Schema 1.0 datatype dateTime.

TIME

public static final QName TIME

Fully qualified name for W3C XML Schema 1.0 datatype time.

DATE

public static final QName DATE

Fully qualified name for W3C XML Schema 1.0 datatype date.

GYEARMONTH

public static final QName GYEARMONTH

Fully qualified name for W3C XML Schema 1.0 datatype gYearMonth.

GMONTHDAY

public static final QName GMONTHDAY

Fully qualified name for W3C XML Schema 1.0 datatype gMonthDay.

GYEAR

public static final QName GYEAR

Fully qualified name for W3C XML Schema 1.0 datatype gYear.

GMONTH

public static final QName GMONTH

Fully qualified name for W3C XML Schema 1.0 datatype gMonth.

GDAY

public static final QName GDAY

Fully qualified name for W3C XML Schema 1.0 datatype gDay.

DURATION

public static final QName DURATION

Fully qualified name for W3C XML Schema datatype duration.

DURATION_DAYTIME

public static final QName DURATION_DAYTIME

Fully qualified name for XQuery 1.0 and XPath 2.0 datatype dayTimeDuration.

DURATION_YEARMONTH

public static final QName DURATION_YEARMONTH

Fully qualified name for XQuery 1.0 and XPath 2.0 datatype yearMonthDuration.

MAX_TIMEZONE_OFFSET

public static final int MAX_TIMEZONE_OFFSET
W3C XML Schema max timezone offset is -14:00. Zone offset is in minutes.

See Also:
Constant Field Values

MIN_TIMEZONE_OFFSET

public static final int MIN_TIMEZONE_OFFSET
W3C XML Schema min timezone offset is +14:00. Zone offset is in minutes.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DatatypeConstants.Field

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.datatype
Class DatatypeConstants.Field

java.lang.Object
    extended by  javax.xml.datatype.DatatypeConstants.Field
Enclosing class:
DatatypeConstants
public static final class DatatypeConstants.Field
extends Object

Type-safe enum class that represents six fields of the Duration class.

Since:
1.5

Method Summary
int | getId() Get id of this Field.
String | toString() Returns a field name in English.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

toString

public String toString()
Returns a field name in English. This method is intended to be used for debugging/diagnosis and not for display to end-users.

Overrides:
toString in class Object
Returns:
a non-null valid String constant.

getId

public int getId()

Get id of this Field.

Returns:
Id of field.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DatatypeFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.datatype
Class DatatypeFactory

java.lang.Object
    extended by  javax.xml.datatype.DatatypeFactory

public abstract class DatatypeFactory
extends Object

Factory that creates new javax.xml.datatype Objects that map XML to/from Java Objects.

newInstance() is used to create a new DatatypeFactory. The following implementation resolution mechanisms are used in the following order:

  1. If the system property specified by DATATYPEFACTORY_PROPERTY, "javax.xml.datatype.DatatypeFactory", exists, a class with the name of the property's value is instantiated. Any Exception thrown during the instantiation process is wrapped as a DatatypeConfigurationException.
  2. If the file ${JAVA_HOME}/lib/jaxp.properties exists, it is loaded in a Properties Object. The Properties Object is then queried for the property as documented in the prior step and processed as documented in the prior step.
  3. The services resolution mechanism is used, e.g. META-INF/services/java.xml.datatype.DatatypeFactory. Any Exception thrown during the instantiation process is wrapped as a DatatypeConfigurationException.
  4. The final mechanism is to attempt to instantiate the Class specified by DATATYPEFACTORY_IMPLEMENTATION_CLASS. Any Exception thrown during the instantiation process is wrapped as a DatatypeConfigurationException.

Since:
1.5

Field Summary
static String | DATATYPEFACTORY_IMPLEMENTATION_CLASS Default implementation class name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.
static String | DATATYPEFACTORY_PROPERTY Default property name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.
Constructor Summary
protected DatatypeFactory()
Protected constructor to prevent instaniation outside of package.
Method Summary
abstract Duration | newDuration(boolean isPositive, BigInteger years, BigInteger months, BigInteger days, BigInteger hours, BigInteger minutes, BigDecimal seconds) Obtain a new instance of a Duration specifying the Duration as isPositive, years, months, days, hours, minutes, seconds.
Duration | newDuration(boolean isPositive, int years, int months, int days, int hours, int minutes, int seconds) Obtain a new instance of a Duration specifying the Duration as isPositive, years, months, days, hours, minutes, seconds.
abstract Duration | newDuration(long durationInMilliSeconds) Obtain a new instance of a Duration specifying the Duration as milliseconds.
abstract Duration | newDuration(String lexicalRepresentation) Obtain a new instance of a Duration specifying the Duration as its string representation, "PnYnMnDTnHnMnS", as defined in XML Schema 1.0 section 3.2.6.1.
Duration | newDurationDayTime(boolean isPositive, BigInteger day, BigInteger hour, BigInteger minute, BigInteger second) Create a Duration of type xdt:dayTimeDuration using the specified day, hour, minute and second as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration.
Duration | newDurationDayTime(boolean isPositive, int day, int hour, int minute, int second) Create a Duration of type xdt:dayTimeDuration using the specified day, hour, minute and second as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration.
Duration | newDurationDayTime(long durationInMilliseconds) Create a Duration of type xdt:dayTimeDuration using the specified milliseconds as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration.
Duration | newDurationDayTime(String lexicalRepresentation) Create a Duration of type xdt:dayTimeDuration by parsing its String representation, "PnDTnHnMnS", XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration.
Duration | newDurationYearMonth(boolean isPositive, BigInteger year, BigInteger month) Create a Duration of type xdt:yearMonthDuration using the specified year and month as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration.
Duration | newDurationYearMonth(boolean isPositive, int year, int month) Create a Duration of type xdt:yearMonthDuration using the specified year and month as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration.
Duration | newDurationYearMonth(long durationInMilliseconds) Create a Duration of type xdt:yearMonthDuration using the specified milliseconds as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration.
Duration | newDurationYearMonth(String lexicalRepresentation) Create a Duration of type xdt:yearMonthDuration by parsing its String representation, "PnYnM", XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration.
static DatatypeFactory | newInstance() Obtain a new instance of a DatatypeFactory.
static DatatypeFactory | newInstance(String factoryClassName, ClassLoader classLoader) Obtain a new instance of a DatatypeFactory from class name.
abstract XMLGregorianCalendar | newXMLGregorianCalendar() Create a new instance of an XMLGregorianCalendar.
abstract XMLGregorianCalendar | newXMLGregorianCalendar(BigInteger year, int month, int day, int hour, int minute, int second, BigDecimal fractionalSecond, int timezone) Constructor allowing for complete value spaces allowed by W3C XML Schema 1.0 recommendation for xsd:dateTime and related builtin datatypes.
abstract XMLGregorianCalendar | newXMLGregorianCalendar(GregorianCalendar cal) Create an XMLGregorianCalendar from a GregorianCalendar.
XMLGregorianCalendar | newXMLGregorianCalendar(int year, int month, int day, int hour, int minute, int second, int millisecond, int timezone) Constructor of value spaces that a java.util.GregorianCalendar instance would need to convert to an XMLGregorianCalendar instance.
abstract XMLGregorianCalendar | newXMLGregorianCalendar(String lexicalRepresentation) Create a new XMLGregorianCalendar by parsing the String as a lexical representation.
XMLGregorianCalendar | newXMLGregorianCalendarDate(int year, int month, int day, int timezone) Create a Java representation of XML Schema builtin datatype date or g*.
XMLGregorianCalendar | newXMLGregorianCalendarTime(int hours, int minutes, int seconds, BigDecimal fractionalSecond, int timezone) Create a Java instance of XML Schema builtin datatype time.
XMLGregorianCalendar | newXMLGregorianCalendarTime(int hours, int minutes, int seconds, int timezone) Create a Java instance of XML Schema builtin datatype time.
XMLGregorianCalendar | newXMLGregorianCalendarTime(int hours, int minutes, int seconds, int milliseconds, int timezone) Create a Java instance of XML Schema builtin datatype time.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DATATYPEFACTORY_PROPERTY

public static final String DATATYPEFACTORY_PROPERTY

Default property name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.

Default value is javax.xml.datatype.DatatypeFactory.

See Also:
Constant Field Values

DATATYPEFACTORY_IMPLEMENTATION_CLASS

public static final String DATATYPEFACTORY_IMPLEMENTATION_CLASS

Default implementation class name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.

Implementers should specify the name of an appropriate class to be instantiated if no other implementation resolution mechanism succeeds.

Users should not refer to this field; it is intended only to document a factory implementation detail.

Constructor Detail

DatatypeFactory

protected DatatypeFactory()

Protected constructor to prevent instaniation outside of package.

Use newInstance() to create a DatatypeFactory.

Method Detail

newInstance

public static DatatypeFactory newInstance()
                                   throws DatatypeConfigurationException

Obtain a new instance of a DatatypeFactory.

The implementation resolution mechanisms are defined in this Class's documentation.

Returns:
New instance of a DatatypeFactory
Throws:
DatatypeConfigurationException - If the implementation is not available or cannot be instantiated.
See Also:
newInstance(String factoryClassName, ClassLoader classLoader)

newInstance

public static DatatypeFactory newInstance(String factoryClassName,
                                          ClassLoader classLoader)
                                   throws DatatypeConfigurationException

Obtain a new instance of a DatatypeFactory from class name. This function is useful when there are multiple providers in the classpath. It gives more control to the application as it can specify which provider should be loaded.

Once an application has obtained a reference to a DatatypeFactory it can use the factory to configure and obtain datatype instances.

Tip for Trouble-shooting

Setting the jaxp.debug system property will cause this method to print a lot of debug messages to System.err about what it is doing and where it is looking at.

If you have problems try:

 java -Djaxp.debug=1 YourProgram ....

Parameters:
factoryClassName - fully qualified factory class name that provides implementation of javax.xml.datatype.DatatypeFactory.
classLoader - ClassLoader used to load the factory class. If null current Thread's context classLoader is used to load the factory class.
Returns:
New instance of a DatatypeFactory
Throws:
DatatypeConfigurationException - if factoryClassName is null, or the factory class cannot be loaded, instantiated.
Since:
1.6
See Also:
newInstance()

newDuration

public abstract Duration newDuration(String lexicalRepresentation)

Obtain a new instance of a Duration specifying the Duration as its string representation, "PnYnMnDTnHnMnS", as defined in XML Schema 1.0 section 3.2.6.1.

XML Schema Part 2: Datatypes, 3.2.6 duration, defines duration as:

duration represents a duration of time. The value space of duration is a six-dimensional space where the coordinates designate the Gregorian year, month, day, hour, minute, and second components defined in Section 5.5.3.2 of [ISO 8601], respectively. These components are ordered in their significance by their order of appearance i.e. as year, month, day, hour, minute, and second.

All six values are set and availabe from the created Duration

The XML Schema specification states that values can be of an arbitrary size. Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. An UnsupportedOperationException will be thrown with a message indicating implementation limits if implementation capacities are exceeded.

Parameters:
lexicalRepresentation - String representation of a Duration.
Returns:
New Duration created from parsing the lexicalRepresentation.
Throws:
IllegalArgumentException - If lexicalRepresentation is not a valid representation of a Duration.
UnsupportedOperationException - If implementation cannot support requested values.
NullPointerException - if lexicalRepresentation is null.

newDuration

public abstract Duration newDuration(long durationInMilliSeconds)

Obtain a new instance of a Duration specifying the Duration as milliseconds.

XML Schema Part 2: Datatypes, 3.2.6 duration, defines duration as:

duration represents a duration of time. The value space of duration is a six-dimensional space where the coordinates designate the Gregorian year, month, day, hour, minute, and second components defined in Section 5.5.3.2 of [ISO 8601], respectively. These components are ordered in their significance by their order of appearance i.e. as year, month, day, hour, minute, and second.

All six values are set by computing their values from the specified milliseconds and are availabe using the get methods of the created Duration. The values conform to and are defined by:

  • ISO 8601:2000(E) Section 5.5.3.2 Alternative format
  • W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats
  • XMLGregorianCalendar Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation

The default start instance is defined by GregorianCalendar's use of the start of the epoch: i.e., Calendar.YEAR = 1970, Calendar.MONTH = Calendar.JANUARY, Calendar.DATE = 1, etc. This is important as there are variations in the Gregorian Calendar, e.g. leap years have different days in the month = Calendar.FEBRUARY so the result of Duration.getMonths() and Duration.getDays() can be influenced.

Parameters:
durationInMilliSeconds - Duration in milliseconds to create.
Returns:
New Duration representing durationInMilliSeconds.

newDuration

public abstract Duration newDuration(boolean isPositive,
                                     BigInteger years,
                                     BigInteger months,
                                     BigInteger days,
                                     BigInteger hours,
                                     BigInteger minutes,
                                     BigDecimal seconds)

Obtain a new instance of a Duration specifying the Duration as isPositive, years, months, days, hours, minutes, seconds.

The XML Schema specification states that values can be of an arbitrary size. Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. An UnsupportedOperationException will be thrown with a message indicating implementation limits if implementation capacities are exceeded.

A null value indicates that field is not set.

Parameters:
isPositive - Set to false to create a negative duration. When the length of the duration is zero, this parameter will be ignored.
years - of this Duration
months - of this Duration
days - of this Duration
hours - of this Duration
minutes - of this Duration
seconds - of this Duration
Returns:
New Duration created from the specified values.
Throws:
IllegalArgumentException - If the values are not a valid representation of a Duration: if all the fields (years, months, ...) are null or if any of the fields is negative.
UnsupportedOperationException - If implementation cannot support requested values.

newDuration

public Duration newDuration(boolean isPositive,
                            int years,
                            int months,
                            int days,
                            int hours,
                            int minutes,
                            int seconds)

Obtain a new instance of a Duration specifying the Duration as isPositive, years, months, days, hours, minutes, seconds.

A DatatypeConstants.FIELD_UNDEFINED value indicates that field is not set.

Parameters:
isPositive - Set to false to create a negative duration. When the length of the duration is zero, this parameter will be ignored.
years - of this Duration
months - of this Duration
days - of this Duration
hours - of this Duration
minutes - of this Duration
seconds - of this Duration
Returns:
New Duration created from the specified values.
Throws:
IllegalArgumentException - If the values are not a valid representation of a Duration: if any of the fields is negative.
See Also:
newDuration( boolean isPositive, BigInteger years, BigInteger months, BigInteger days, BigInteger hours, BigInteger minutes, BigDecimal seconds)

newDurationDayTime

public Duration newDurationDayTime(String lexicalRepresentation)

Create a Duration of type xdt:dayTimeDuration by parsing its String representation, "PnDTnHnMnS", XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration.

The datatype xdt:dayTimeDuration is a subtype of xs:duration whose lexical representation contains only day, hour, minute, and second components. This datatype resides in the namespace http://www.w3.org/2003/11/xpath-datatypes.

All four values are set and availabe from the created Duration

The XML Schema specification states that values can be of an arbitrary size. Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. An UnsupportedOperationException will be thrown with a message indicating implementation limits if implementation capacities are exceeded.

Parameters:
lexicalRepresentation - Lexical representation of a duration.
Returns:
New Duration created using the specified lexicalRepresentation.
Throws:
IllegalArgumentException - If lexicalRepresentation is not a valid representation of a Duration expressed only in terms of days and time.
UnsupportedOperationException - If implementation cannot support requested values.
NullPointerException - If lexicalRepresentation is null.

newDurationDayTime

public Duration newDurationDayTime(long durationInMilliseconds)

Create a Duration of type xdt:dayTimeDuration using the specified milliseconds as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration.

The datatype xdt:dayTimeDuration is a subtype of xs:duration whose lexical representation contains only day, hour, minute, and second components. This datatype resides in the namespace http://www.w3.org/2003/11/xpath-datatypes.

All four values are set by computing their values from the specified milliseconds and are availabe using the get methods of the created Duration. The values conform to and are defined by:

  • ISO 8601:2000(E) Section 5.5.3.2 Alternative format
  • W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats
  • XMLGregorianCalendar Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation

The default start instance is defined by GregorianCalendar's use of the start of the epoch: i.e., Calendar.YEAR = 1970, Calendar.MONTH = Calendar.JANUARY, Calendar.DATE = 1, etc. This is important as there are variations in the Gregorian Calendar, e.g. leap years have different days in the month = Calendar.FEBRUARY so the result of Duration.getDays() can be influenced.

Any remaining milliseconds after determining the day, hour, minute and second are discarded.

Parameters:
durationInMilliseconds - Milliseconds of Duration to create.
Returns:
New Duration created with the specified durationInMilliseconds.
See Also:
XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration

newDurationDayTime

public Duration newDurationDayTime(boolean isPositive,
                                   BigInteger day,
                                   BigInteger hour,
                                   BigInteger minute,
                                   BigInteger second)

Create a Duration of type xdt:dayTimeDuration using the specified day, hour, minute and second as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration.

The datatype xdt:dayTimeDuration is a subtype of xs:duration whose lexical representation contains only day, hour, minute, and second components. This datatype resides in the namespace http://www.w3.org/2003/11/xpath-datatypes.

The XML Schema specification states that values can be of an arbitrary size. Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. An UnsupportedOperationException will be thrown with a message indicating implementation limits if implementation capacities are exceeded.

A null value indicates that field is not set.

Parameters:
isPositive - Set to false to create a negative duration. When the length of the duration is zero, this parameter will be ignored.
day - Day of Duration.
hour - Hour of Duration.
minute - Minute of Duration.
second - Second of Duration.
Returns:
New Duration created with the specified day, hour, minute and second.
Throws:
IllegalArgumentException - If the values are not a valid representation of a Duration: if all the fields (day, hour, ...) are null or if any of the fields is negative.
UnsupportedOperationException - If implementation cannot support requested values.

newDurationDayTime

public Duration newDurationDayTime(boolean isPositive,
                                   int day,
                                   int hour,
                                   int minute,
                                   int second)

Create a Duration of type xdt:dayTimeDuration using the specified day, hour, minute and second as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:dayTimeDuration.

The datatype xdt:dayTimeDuration is a subtype of xs:duration whose lexical representation contains only day, hour, minute, and second components. This datatype resides in the namespace http://www.w3.org/2003/11/xpath-datatypes.

A DatatypeConstants.FIELD_UNDEFINED value indicates that field is not set.

Parameters:
isPositive - Set to false to create a negative duration. When the length of the duration is zero, this parameter will be ignored.
day - Day of Duration.
hour - Hour of Duration.
minute - Minute of Duration.
second - Second of Duration.
Returns:
New Duration created with the specified day, hour, minute and second.
Throws:
IllegalArgumentException - If the values are not a valid representation of a Duration: if any of the fields (day, hour, ...) is negative.

newDurationYearMonth

public Duration newDurationYearMonth(String lexicalRepresentation)

Create a Duration of type xdt:yearMonthDuration by parsing its String representation, "PnYnM", XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration.

The datatype xdt:yearMonthDuration is a subtype of xs:duration whose lexical representation contains only year and month components. This datatype resides in the namespace XMLConstants.W3C_XPATH_DATATYPE_NS_URI.

Both values are set and availabe from the created Duration

The XML Schema specification states that values can be of an arbitrary size. Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. An UnsupportedOperationException will be thrown with a message indicating implementation limits if implementation capacities are exceeded.

Parameters:
lexicalRepresentation - Lexical representation of a duration.
Returns:
New Duration created using the specified lexicalRepresentation.
Throws:
IllegalArgumentException - If lexicalRepresentation is not a valid representation of a Duration expressed only in terms of years and months.
UnsupportedOperationException - If implementation cannot support requested values.
NullPointerException - If lexicalRepresentation is null.

newDurationYearMonth

public Duration newDurationYearMonth(long durationInMilliseconds)

Create a Duration of type xdt:yearMonthDuration using the specified milliseconds as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration.

The datatype xdt:yearMonthDuration is a subtype of xs:duration whose lexical representation contains only year and month components. This datatype resides in the namespace XMLConstants.W3C_XPATH_DATATYPE_NS_URI.

Both values are set by computing their values from the specified milliseconds and are availabe using the get methods of the created Duration. The values conform to and are defined by:

  • ISO 8601:2000(E) Section 5.5.3.2 Alternative format
  • W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats
  • XMLGregorianCalendar Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation

The default start instance is defined by GregorianCalendar's use of the start of the epoch: i.e., Calendar.YEAR = 1970, Calendar.MONTH = Calendar.JANUARY, Calendar.DATE = 1, etc. This is important as there are variations in the Gregorian Calendar, e.g. leap years have different days in the month = Calendar.FEBRUARY so the result of Duration.getMonths() can be influenced.

Any remaining milliseconds after determining the year and month are discarded.

Parameters:
durationInMilliseconds - Milliseconds of Duration to create.
Returns:
New Duration created using the specified durationInMilliseconds.

newDurationYearMonth

public Duration newDurationYearMonth(boolean isPositive,
                                     BigInteger year,
                                     BigInteger month)

Create a Duration of type xdt:yearMonthDuration using the specified year and month as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration.

The XML Schema specification states that values can be of an arbitrary size. Implementations may chose not to or be incapable of supporting arbitrarily large and/or small values. An UnsupportedOperationException will be thrown with a message indicating implementation limits if implementation capacities are exceeded.

A null value indicates that field is not set.

Parameters:
isPositive - Set to false to create a negative duration. When the length of the duration is zero, this parameter will be ignored.
year - Year of Duration.
month - Month of Duration.
Returns:
New Duration created using the specified year and month.
Throws:
IllegalArgumentException - If the values are not a valid representation of a Duration: if all of the fields (year, month) are null or if any of the fields is negative.
UnsupportedOperationException - If implementation cannot support requested values.

newDurationYearMonth

public Duration newDurationYearMonth(boolean isPositive,
                                     int year,
                                     int month)

Create a Duration of type xdt:yearMonthDuration using the specified year and month as defined in XQuery 1.0 and XPath 2.0 Data Model, xdt:yearMonthDuration.

A DatatypeConstants.FIELD_UNDEFINED value indicates that field is not set.

Parameters:
isPositive - Set to false to create a negative duration. When the length of the duration is zero, this parameter will be ignored.
year - Year of Duration.
month - Month of Duration.
Returns:
New Duration created using the specified year and month.
Throws:
IllegalArgumentException - If the values are not a valid representation of a Duration: if any of the fields (year, month) is negative.

newXMLGregorianCalendar

public abstract XMLGregorianCalendar newXMLGregorianCalendar()

Create a new instance of an XMLGregorianCalendar.

All date/time datatype fields set to DatatypeConstants.FIELD_UNDEFINED or null.

Returns:
New XMLGregorianCalendar with all date/time datatype fields set to DatatypeConstants.FIELD_UNDEFINED or null.

newXMLGregorianCalendar

public abstract XMLGregorianCalendar newXMLGregorianCalendar(String lexicalRepresentation)

Create a new XMLGregorianCalendar by parsing the String as a lexical representation.

Parsing the lexical string representation is defined in XML Schema 1.0 Part 2, Section 3.2.[7-14].1, Lexical Representation.

The string representation may not have any leading and trailing whitespaces.

The parsing is done field by field so that the following holds for any lexically correct String x:

 newXMLGregorianCalendar(x).toXMLFormat().equals(x)

Except for the noted lexical/canonical representation mismatches listed in XML Schema 1.0 errata, Section 3.2.7.2.

Parameters:
lexicalRepresentation - Lexical representation of one the eight XML Schema date/time datatypes.
Returns:
XMLGregorianCalendar created from the lexicalRepresentation.
Throws:
IllegalArgumentException - If the lexicalRepresentation is not a valid XMLGregorianCalendar.
NullPointerException - If lexicalRepresentation is null.

newXMLGregorianCalendar

public abstract XMLGregorianCalendar newXMLGregorianCalendar(GregorianCalendar cal)

Create an XMLGregorianCalendar from a GregorianCalendar.

Field by Field Conversion from GregorianCalendar to an XMLGregorianCalendar
java.util.GregorianCalendar field | javax.xml.datatype.XMLGregorianCalendar field
ERA == GregorianCalendar.BC ? -YEAR : YEAR | XMLGregorianCalendar.setYear(int year)
MONTH + 1 | XMLGregorianCalendar.setMonth(int month)
DAY_OF_MONTH | XMLGregorianCalendar.setDay(int day)
HOUR_OF_DAY, MINUTE, SECOND, MILLISECOND | XMLGregorianCalendar.setTime(int hour, int minute, int second, BigDecimal fractional)
(ZONE_OFFSET + DST_OFFSET) / (60*1000)
(in minutes) 		XMLGregorianCalendar.setTimezone(int offset) *

*conversion loss of information. It is not possible to represent a java.util.GregorianCalendar daylight savings timezone id in the XML Schema 1.0 date/time datatype representation.

To compute the return value's TimeZone field,

  • when this.getTimezone() != FIELD_UNDEFINED, create a java.util.TimeZone with a custom timezone id using the this.getTimezone().
  • else use the GregorianCalendar default timezone value for the host is defined as specified by java.util.TimeZone.getDefault().

    • Parameters:
    cal - java.util.GregorianCalendar used to create XMLGregorianCalendar
    Returns:
    XMLGregorianCalendar created from java.util.GregorianCalendar
    Throws:
    NullPointerException - If cal is null.

newXMLGregorianCalendar

public abstract XMLGregorianCalendar newXMLGregorianCalendar(BigInteger year,
                                                             int month,
                                                             int day,
                                                             int hour,
                                                             int minute,
                                                             int second,
                                                             BigDecimal fractionalSecond,
                                                             int timezone)

Constructor allowing for complete value spaces allowed by W3C XML Schema 1.0 recommendation for xsd:dateTime and related builtin datatypes. Note that year parameter supports arbitrarily large numbers and fractionalSecond has infinite precision.

A null value indicates that field is not set.

Parameters:
year - of XMLGregorianCalendar to be created.
month - of XMLGregorianCalendar to be created.
day - of XMLGregorianCalendar to be created.
hour - of XMLGregorianCalendar to be created.
minute - of XMLGregorianCalendar to be created.
second - of XMLGregorianCalendar to be created.
fractionalSecond - of XMLGregorianCalendar to be created.
timezone - of XMLGregorianCalendar to be created.
Returns:
XMLGregorianCalendar created from specified values.
Throws:
IllegalArgumentException - If any individual parameter's value is outside the maximum value constraint for the field as determined by the Date/Time Data Mapping table in XMLGregorianCalendar or if the composite values constitute an invalid XMLGregorianCalendar instance as determined by XMLGregorianCalendar.isValid().

newXMLGregorianCalendar

public XMLGregorianCalendar newXMLGregorianCalendar(int year,
                                                    int month,
                                                    int day,
                                                    int hour,
                                                    int minute,
                                                    int second,
                                                    int millisecond,
                                                    int timezone)

Constructor of value spaces that a java.util.GregorianCalendar instance would need to convert to an XMLGregorianCalendar instance.

XMLGregorianCalendar eon and fractionalSecond are set to null

A DatatypeConstants.FIELD_UNDEFINED value indicates that field is not set.

Parameters:
year - of XMLGregorianCalendar to be created.
month - of XMLGregorianCalendar to be created.
day - of XMLGregorianCalendar to be created.
hour - of XMLGregorianCalendar to be created.
minute - of XMLGregorianCalendar to be created.
second - of XMLGregorianCalendar to be created.
millisecond - of XMLGregorianCalendar to be created.
timezone - of XMLGregorianCalendar to be created.
Returns:
XMLGregorianCalendar created from specified values.
Throws:
IllegalArgumentException - If any individual parameter's value is outside the maximum value constraint for the field as determined by the Date/Time Data Mapping table in XMLGregorianCalendar or if the composite values constitute an invalid XMLGregorianCalendar instance as determined by XMLGregorianCalendar.isValid().

newXMLGregorianCalendarDate

public XMLGregorianCalendar newXMLGregorianCalendarDate(int year,
                                                        int month,
                                                        int day,
                                                        int timezone)

Create a Java representation of XML Schema builtin datatype date or g*.

For example, an instance of gYear can be created invoking this factory with month and day parameters set to DatatypeConstants.FIELD_UNDEFINED.

A DatatypeConstants.FIELD_UNDEFINED value indicates that field is not set.

Parameters:
year - of XMLGregorianCalendar to be created.
month - of XMLGregorianCalendar to be created.
day - of XMLGregorianCalendar to be created.
timezone - offset in minutes. DatatypeConstants.FIELD_UNDEFINED indicates optional field is not set.
Returns:
XMLGregorianCalendar created from parameter values.
Throws:
IllegalArgumentException - If any individual parameter's value is outside the maximum value constraint for the field as determined by the Date/Time Data Mapping table in XMLGregorianCalendar or if the composite values constitute an invalid XMLGregorianCalendar instance as determined by XMLGregorianCalendar.isValid().
See Also:
DatatypeConstants.FIELD_UNDEFINED

newXMLGregorianCalendarTime

public XMLGregorianCalendar newXMLGregorianCalendarTime(int hours,
                                                        int minutes,
                                                        int seconds,
                                                        int timezone)

Create a Java instance of XML Schema builtin datatype time.

A DatatypeConstants.FIELD_UNDEFINED value indicates that field is not set.

Parameters:
hours - number of hours
minutes - number of minutes
seconds - number of seconds
timezone - offset in minutes. DatatypeConstants.FIELD_UNDEFINED indicates optional field is not set.
Returns:
XMLGregorianCalendar created from parameter values.
Throws:
IllegalArgumentException - If any individual parameter's value is outside the maximum value constraint for the field as determined by the Date/Time Data Mapping table in XMLGregorianCalendar or if the composite values constitute an invalid XMLGregorianCalendar instance as determined by XMLGregorianCalendar.isValid().
See Also:
DatatypeConstants.FIELD_UNDEFINED

newXMLGregorianCalendarTime

public XMLGregorianCalendar newXMLGregorianCalendarTime(int hours,
                                                        int minutes,
                                                        int seconds,
                                                        BigDecimal fractionalSecond,
                                                        int timezone)

Create a Java instance of XML Schema builtin datatype time.

A null value indicates that field is not set.

A DatatypeConstants.FIELD_UNDEFINED value indicates that field is not set.

Parameters:
hours - number of hours
minutes - number of minutes
seconds - number of seconds
fractionalSecond - value of null indicates that this optional field is not set.
timezone - offset in minutes. DatatypeConstants.FIELD_UNDEFINED indicates optional field is not set.
Returns:
XMLGregorianCalendar created from parameter values.
Throws:
IllegalArgumentException - If any individual parameter's value is outside the maximum value constraint for the field as determined by the Date/Time Data Mapping table in XMLGregorianCalendar or if the composite values constitute an invalid XMLGregorianCalendar instance as determined by XMLGregorianCalendar.isValid().
See Also:
DatatypeConstants.FIELD_UNDEFINED

newXMLGregorianCalendarTime

public XMLGregorianCalendar newXMLGregorianCalendarTime(int hours,
                                                        int minutes,
                                                        int seconds,
                                                        int milliseconds,
                                                        int timezone)

Create a Java instance of XML Schema builtin datatype time.

A DatatypeConstants.FIELD_UNDEFINED value indicates that field is not set.

Parameters:
hours - number of hours
minutes - number of minutes
seconds - number of seconds
milliseconds - number of milliseconds
timezone - offset in minutes. DatatypeConstants.FIELD_UNDEFINED indicates optional field is not set.
Returns:
XMLGregorianCalendar created from parameter values.
Throws:
IllegalArgumentException - If any individual parameter's value is outside the maximum value constraint for the field as determined by the Date/Time Data Mapping table in XMLGregorianCalendar or if the composite values constitute an invalid XMLGregorianCalendar instance as determined by XMLGregorianCalendar.isValid().
See Also:
DatatypeConstants.FIELD_UNDEFINED
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Duration

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.datatype
Class Duration

java.lang.Object
    extended by  javax.xml.datatype.Duration

public abstract class Duration
extends Object

Immutable representation of a time span as defined in the W3C XML Schema 1.0 specification.

A Duration object represents a period of Gregorian time, which consists of six fields (years, months, days, hours, minutes, and seconds) plus a sign (+/-) field.

The first five fields have non-negative (>=0) integers or null (which represents that the field is not set), and the seconds field has a non-negative decimal or null. A negative sign indicates a negative duration.

This class provides a number of methods that make it easy to use for the duration datatype of XML Schema 1.0 with the errata.

Order relationship

Duration objects only have partial order, where two values A and B maybe either:

  1. A<B (A is shorter than B)
  2. A>B (A is longer than B)
  3. A==B (A and B are of the same duration)
  4. A<>B (Comparison between A and B is indeterminate)

For example, 30 days cannot be meaningfully compared to one month. The compare(Duration duration) method implements this relationship.

See the isLongerThan(Duration) method for details about the order relationship among Duration objects.

Operations over Duration

This class provides a set of basic arithmetic operations, such as addition, subtraction and multiplication. Because durations don't have total order, an operation could fail for some combinations of operations. For example, you cannot subtract 15 days from 1 month. See the javadoc of those methods for detailed conditions where this could happen.

Also, division of a duration by a number is not provided because the Duration class can only deal with finite precision decimal numbers. For example, one cannot represent 1 sec divided by 3.

However, you could substitute a division by 3 with multiplying by numbers such as 0.3 or 0.333.

Range of allowed values

Because some operations of Duration rely on Calendar even though Duration can hold very large or very small values, some of the methods may not work correctly on such Durations. The impacted methods document their dependency on Calendar.

Since:
1.5
See Also:
XMLGregorianCalendar.add(Duration)

Constructor Summary
Duration()
Default no-arg constructor.
Method Summary
abstract Duration | add(Duration rhs) Computes a new duration whose value is this+rhs.
abstract void | addTo(Calendar calendar) Adds this duration to a Calendar object.
void | addTo(Date date) Adds this duration to a Date object.
abstract int | compare(Duration duration) Partial order relation comparison with this Duration instance.
boolean | equals(Object duration) Checks if this duration object has the same duration as another Duration object.
int | getDays() Obtains the value of the DAYS field as an integer value, or 0 if not present.
abstract Number | getField(DatatypeConstants.Field field) Gets the value of a field.
int | getHours() Obtains the value of the HOURS field as an integer value, or 0 if not present.
int | getMinutes() Obtains the value of the MINUTES field as an integer value, or 0 if not present.
int | getMonths() Obtains the value of the MONTHS field as an integer value, or 0 if not present.
int | getSeconds() Obtains the value of the SECONDS field as an integer value, or 0 if not present.
abstract int | getSign() Returns the sign of this duration in -1,0, or 1.
long | getTimeInMillis(Calendar startInstant) Returns the length of the duration in milli-seconds.
long | getTimeInMillis(Date startInstant) Returns the length of the duration in milli-seconds.
QName | getXMLSchemaType() Return the name of the XML Schema date/time type that this instance maps to.
int | getYears() Get the years value of this Duration as an int or 0 if not present.
abstract int | hashCode() Returns a hash code consistent with the definition of the equals method.
boolean | isLongerThan(Duration duration) Checks if this duration object is strictly longer than another Duration object.
abstract boolean | isSet(DatatypeConstants.Field field) Checks if a field is set.
boolean | isShorterThan(Duration duration) Checks if this duration object is strictly shorter than another Duration object.
abstract Duration | multiply(BigDecimal factor) Computes a new duration whose value is factor times longer than the value of this duration.
Duration | multiply(int factor) Computes a new duration whose value is factor times longer than the value of this duration.
abstract Duration | negate() Returns a new Duration object whose value is -this.
abstract Duration | normalizeWith(Calendar startTimeInstant) Converts the years and months fields into the days field by using a specific time instant as the reference point.
Duration | subtract(Duration rhs) Computes a new duration whose value is this-rhs.
String | toString() Returns a String representation of this Duration Object.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Duration

public Duration()
Default no-arg constructor.

Note: Always use the DatatypeFactory to construct an instance of Duration. The constructor on this class cannot be guaranteed to produce an object with a consistent state and may be removed in the future.

Method Detail

getXMLSchemaType

public QName getXMLSchemaType()

Return the name of the XML Schema date/time type that this instance maps to. Type is computed based on fields that are set, i.e. isSet(DatatypeConstants.Field field) == true.

Required fields for XML Schema 1.0 Date/Time Datatypes.
(timezone is optional for all date/time datatypes)
Datatype | year | month | day | hour | minute | second
DatatypeConstants.DURATION | X | X | X | X | X | X
DatatypeConstants.DURATION_DAYTIME | X | X | X | X
DatatypeConstants.DURATION_YEARMONTH | X | X

Returns:
one of the following constants: DatatypeConstants.DURATION, DatatypeConstants.DURATION_DAYTIME or DatatypeConstants.DURATION_YEARMONTH.
Throws:
IllegalStateException - If the combination of set fields does not match one of the XML Schema date/time datatypes.

getSign

public abstract int getSign()
Returns the sign of this duration in -1,0, or 1.

Returns:
-1 if this duration is negative, 0 if the duration is zero, and 1 if the duration is positive.

getYears

public int getYears()

Get the years value of this Duration as an int or 0 if not present.

getYears() is a convenience method for getField(DatatypeConstants.YEARS).

As the return value is an int, an incorrect value will be returned for Durations with years that go beyond the range of an int. Use getField(DatatypeConstants.YEARS) to avoid possible loss of precision.

Returns:
If the years field is present, return its value as an int, else return 0.

getMonths

public int getMonths()
Obtains the value of the MONTHS field as an integer value, or 0 if not present. This method works just like getYears() except that this method works on the MONTHS field.

Returns:
Months of this Duration.

getDays

public int getDays()
Obtains the value of the DAYS field as an integer value, or 0 if not present. This method works just like getYears() except that this method works on the DAYS field.

Returns:
Days of this Duration.

getHours

public int getHours()
Obtains the value of the HOURS field as an integer value, or 0 if not present. This method works just like getYears() except that this method works on the HOURS field.

Returns:
Hours of this Duration.

getMinutes

public int getMinutes()
Obtains the value of the MINUTES field as an integer value, or 0 if not present. This method works just like getYears() except that this method works on the MINUTES field.

Returns:
Minutes of this Duration.

getSeconds

public int getSeconds()
Obtains the value of the SECONDS field as an integer value, or 0 if not present. This method works just like getYears() except that this method works on the SECONDS field.

Returns:
seconds in the integer value. The fraction of seconds will be discarded (for example, if the actual value is 2.5, this method returns 2)

getTimeInMillis

public long getTimeInMillis(Calendar startInstant)

Returns the length of the duration in milli-seconds.

If the seconds field carries more digits than milli-second order, those will be simply discarded (or in other words, rounded to zero.) For example, for any Calendar value x,

 new Duration("PT10.00099S").getTimeInMills(x) == 10000.
 new Duration("-PT10.00099S").getTimeInMills(x) == -10000.

Note that this method uses the addTo(Calendar) method, which may work incorrectly with Duration objects with very large values in its fields. See the addTo(Calendar) method for details.

Parameters:
startInstant - The length of a month/year varies. The startInstant is used to disambiguate this variance. Specifically, this method returns the difference between startInstant and startInstant+duration
Returns:
milliseconds between startInstant and startInstant plus this Duration
Throws:
NullPointerException - if startInstant parameter is null.

getTimeInMillis

public long getTimeInMillis(Date startInstant)

Returns the length of the duration in milli-seconds.

If the seconds field carries more digits than milli-second order, those will be simply discarded (or in other words, rounded to zero.) For example, for any Date value x,

 new Duration("PT10.00099S").getTimeInMills(x) == 10000.
 new Duration("-PT10.00099S").getTimeInMills(x) == -10000.

Note that this method uses the addTo(Date) method, which may work incorrectly with Duration objects with very large values in its fields. See the addTo(Date) method for details.

Parameters:
startInstant - The length of a month/year varies. The startInstant is used to disambiguate this variance. Specifically, this method returns the difference between startInstant and startInstant+duration.
Returns:
milliseconds between startInstant and startInstant plus this Duration
Throws:
NullPointerException - If the startInstant parameter is null.
See Also:
getTimeInMillis(Calendar)

getField

public abstract Number getField(DatatypeConstants.Field field)
Gets the value of a field. Fields of a duration object may contain arbitrary large value. Therefore this method is designed to return a Number object. In case of YEARS, MONTHS, DAYS, HOURS, and MINUTES, the returned number will be a non-negative integer. In case of seconds, the returned number may be a non-negative decimal value.

Parameters:
field - one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.)
Returns:
If the specified field is present, this method returns a non-null non-negative Number object that represents its value. If it is not present, return null. For YEARS, MONTHS, DAYS, HOURS, and MINUTES, this method returns a BigInteger object. For SECONDS, this method returns a BigDecimal.
Throws:
NullPointerException - If the field is null.

isSet

public abstract boolean isSet(DatatypeConstants.Field field)
Checks if a field is set. A field of a duration object may or may not be present. This method can be used to test if a field is present.

Parameters:
field - one of the six Field constants (YEARS,MONTHS,DAYS,HOURS, MINUTES, or SECONDS.)
Returns:
true if the field is present. false if not.
Throws:
NullPointerException - If the field parameter is null.

add

public abstract Duration add(Duration rhs)

Computes a new duration whose value is this+rhs.

For example,

 "1 day" + "-3 days" = "-2 days"
 "1 year" + "1 day" = "1 year and 1 day"
 "-(1 hour,50 minutes)" + "-20 minutes" = "-(1 hours,70 minutes)"
 "15 hours" + "-3 days" = "-(2 days,9 hours)"
 "1 year" + "-1 day" = IllegalStateException

Since there's no way to meaningfully subtract 1 day from 1 month, there are cases where the operation fails in IllegalStateException.

Formally, the computation is defined as follows.

Firstly, we can assume that two Durations to be added are both positive without losing generality (i.e., (-X)+Y=Y-X, X+(-Y)=X-Y, (-X)+(-Y)=-(X+Y))

Addition of two positive Durations are simply defined as field by field addition where missing fields are treated as 0.

A field of the resulting Duration will be unset if and only if respective fields of two input Durations are unset.

Note that lhs.add(rhs) will be always successful if lhs.signum()*rhs.signum()!=-1 or both of them are normalized.

Parameters:
rhs - Duration to add to this Duration
Returns:
non-null valid Duration object.
Throws:
NullPointerException - If the rhs parameter is null.
IllegalStateException - If two durations cannot be meaningfully added. For example, adding negative one day to one month causes this exception.
See Also:
subtract(Duration)

addTo

public abstract void addTo(Calendar calendar)
Adds this duration to a Calendar object.

Calls Calendar.add(int,int) in the order of YEARS, MONTHS, DAYS, HOURS, MINUTES, SECONDS, and MILLISECONDS if those fields are present. Because the Calendar class uses int to hold values, there are cases where this method won't work correctly (for example if values of fields exceed the range of int.)

Also, since this duration class is a Gregorian duration, this method will not work correctly if the given Calendar object is based on some other calendar systems.

Any fractional parts of this Duration object beyond milliseconds will be simply ignored. For example, if this duration is "P1.23456S", then 1 is added to SECONDS, 234 is added to MILLISECONDS, and the rest will be unused.

Note that because Calendar.add(int, int) is using int, Duration with values beyond the range of int in its fields will cause overflow/underflow to the given Calendar. XMLGregorianCalendar.add(Duration) provides the same basic operation as this method while avoiding the overflow/underflow issues.

Parameters:
calendar - A calendar object whose value will be modified.
Throws:
NullPointerException - if the calendar parameter is null.

addTo

public void addTo(Date date)
Adds this duration to a Date object.

The given date is first converted into a GregorianCalendar, then the duration is added exactly like the addTo(Calendar) method.

The updated time instant is then converted back into a Date object and used to update the given Date object.

This somewhat redundant computation is necessary to unambiguously determine the duration of months and years.

Parameters:
date - A date object whose value will be modified.
Throws:
NullPointerException - if the date parameter is null.

subtract

public Duration subtract(Duration rhs)

Computes a new duration whose value is this-rhs.

For example:

 "1 day" - "-3 days" = "4 days"
 "1 year" - "1 day" = IllegalStateException
 "-(1 hour,50 minutes)" - "-20 minutes" = "-(1hours,30 minutes)"
 "15 hours" - "-3 days" = "3 days and 15 hours"
 "1 year" - "-1 day" = "1 year and 1 day"

Since there's no way to meaningfully subtract 1 day from 1 month, there are cases where the operation fails in IllegalStateException.

Formally the computation is defined as follows. First, we can assume that two Durations are both positive without losing generality. (i.e., (-X)-Y=-(X+Y), X-(-Y)=X+Y, (-X)-(-Y)=-(X-Y))

Then two durations are subtracted field by field. If the sign of any non-zero field F is different from the sign of the most significant field, 1 (if F is negative) or -1 (otherwise) will be borrowed from the next bigger unit of F.

This process is repeated until all the non-zero fields have the same sign.

If a borrow occurs in the days field (in other words, if the computation needs to borrow 1 or -1 month to compensate days), then the computation fails by throwing an IllegalStateException.

Parameters:
rhs - Duration to subtract from this Duration.
Returns:
New Duration created from subtracting rhs from this Duration.
Throws:
IllegalStateException - If two durations cannot be meaningfully subtracted. For example, subtracting one day from one month causes this exception.
NullPointerException - If the rhs parameter is null.
See Also:
add(Duration)

multiply

public Duration multiply(int factor)

Computes a new duration whose value is factor times longer than the value of this duration.

This method is provided for the convenience. It is functionally equivalent to the following code:

 multiply(new BigDecimal(String.valueOf(factor)))

Parameters:
factor - Factor times longer of new Duration to create.
Returns:
New Duration that is factortimes longer than this Duration.
See Also:
multiply(BigDecimal)

multiply

public abstract Duration multiply(BigDecimal factor)
Computes a new duration whose value is factor times longer than the value of this duration.

For example,

 "P1M" (1 month) * "12" = "P12M" (12 months)
 "PT1M" (1 min) * "0.3" = "PT18S" (18 seconds)
 "P1M" (1 month) * "1.5" = IllegalStateException

Since the Duration class is immutable, this method doesn't change the value of this object. It simply computes a new Duration object and returns it.

The operation will be performed field by field with the precision of BigDecimal. Since all the fields except seconds are restricted to hold integers, any fraction produced by the computation will be carried down toward the next lower unit. For example, if you multiply "P1D" (1 day) with "0.5", then it will be 0.5 day, which will be carried down to "PT12H" (12 hours). When fractions of month cannot be meaningfully carried down to days, or year to months, this will cause an IllegalStateException to be thrown. For example if you multiple one month by 0.5.

To avoid IllegalStateException, use the normalizeWith(Calendar) method to remove the years and months fields.

Parameters:
factor - to multiply by
Returns:
returns a non-null valid Duration object
Throws:
IllegalStateException - if operation produces fraction in the months field.
NullPointerException - if the factor parameter is null.

negate

public abstract Duration negate()
Returns a new Duration object whose value is -this.

Since the Duration class is immutable, this method doesn't change the value of this object. It simply computes a new Duration object and returns it.

Returns:
always return a non-null valid Duration object.

normalizeWith

public abstract Duration normalizeWith(Calendar startTimeInstant)

Converts the years and months fields into the days field by using a specific time instant as the reference point.

For example, duration of one month normalizes to 31 days given the start time instance "July 8th 2003, 17:40:32".

Formally, the computation is done as follows:

  1. the given Calendar object is cloned
  2. the years, months and days fields will be added to the Calendar object by using the Calendar.add(int,int) method
  3. the difference between the two Calendars in computed in milliseconds and converted to days, if a remainder occurs due to Daylight Savings Time, it is discarded
  4. the computed days, along with the hours, minutes and seconds fields of this duration object is used to construct a new Duration object.

Note that since the Calendar class uses int to hold the value of year and month, this method may produce an unexpected result if this duration object holds a very large value in the years or months fields.

Parameters:
startTimeInstant - Calendar reference point.
Returns:
Duration of years and months of this Duration as days.
Throws:
NullPointerException - If the startTimeInstant parameter is null.

compare

public abstract int compare(Duration duration)

Partial order relation comparison with this Duration instance.

Comparison result must be in accordance with W3C XML Schema 1.0 Part 2, Section 3.2.7.6.2, Order relation on duration.

Return:

  • DatatypeConstants.LESSER if this Duration is shorter than duration parameter
  • DatatypeConstants.EQUAL if this Duration is equal to duration parameter
  • DatatypeConstants.GREATER if this Duration is longer than duration parameter
  • DatatypeConstants.INDETERMINATE if a conclusive partial order relation cannot be determined

Parameters:
duration - to compare
Returns:
the relationship between this Durationand duration parameter as DatatypeConstants.LESSER, DatatypeConstants.EQUAL, DatatypeConstants.GREATER or DatatypeConstants.INDETERMINATE.
Throws:
UnsupportedOperationException - If the underlying implementation cannot reasonably process the request, e.g. W3C XML Schema allows for arbitrarily large/small/precise values, the request may be beyond the implementations capability.
NullPointerException - if duration is null.
See Also:
isShorterThan(Duration), isLongerThan(Duration)

isLongerThan

public boolean isLongerThan(Duration duration)

Checks if this duration object is strictly longer than another Duration object.

Duration X is "longer" than Y if and only if X>Y as defined in the section 3.2.6.2 of the XML Schema 1.0 specification.

For example, "P1D" (one day) > "PT12H" (12 hours) and "P2Y" (two years) > "P23M" (23 months).

Parameters:
duration - Duration to test this Duration against.
Returns:
true if the duration represented by this object is longer than the given duration. false otherwise.
Throws:
UnsupportedOperationException - If the underlying implementation cannot reasonably process the request, e.g. W3C XML Schema allows for arbitrarily large/small/precise values, the request may be beyond the implementations capability.
NullPointerException - If duration is null.
See Also:
isShorterThan(Duration), compare(Duration duration)

isShorterThan

public boolean isShorterThan(Duration duration)

Checks if this duration object is strictly shorter than another Duration object.

Parameters:
duration - Duration to test this Duration against.
Returns:
true if duration parameter is shorter than this Duration, else false.
Throws:
UnsupportedOperationException - If the underlying implementation cannot reasonably process the request, e.g. W3C XML Schema allows for arbitrarily large/small/precise values, the request may be beyond the implementations capability.
NullPointerException - if duration is null.
See Also:
isLongerThan(Duration duration), compare(Duration duration)

equals

public boolean equals(Object duration)

Checks if this duration object has the same duration as another Duration object.

For example, "P1D" (1 day) is equal to "PT24H" (24 hours).

Duration X is equal to Y if and only if time instant t+X and t+Y are the same for all the test time instants specified in the section 3.2.6.2 of the XML Schema 1.0 specification.

Note that there are cases where two Durations are "incomparable" to each other, like one month and 30 days. For example,

 !new Duration("P1M").isShorterThan(new Duration("P30D"))
 !new Duration("P1M").isLongerThan(new Duration("P30D"))
 !new Duration("P1M").equals(new Duration("P30D"))

Overrides:
equals in class Object
Parameters:
duration - The object to compare this Duration against.
Returns:
true if this duration is the same length as duration. false if duration is null, is not a Duration object, or its length is different from this duration.
Throws:
UnsupportedOperationException - If the underlying implementation cannot reasonably process the request, e.g. W3C XML Schema allows for arbitrarily large/small/precise values, the request may be beyond the implementations capability.
See Also:
compare(Duration duration)

hashCode

public abstract int hashCode()
Returns a hash code consistent with the definition of the equals method.

Overrides:
hashCode in class Object
Returns:
a hash code value for this object.
See Also:
Object.hashCode()

toString

public String toString()

Returns a String representation of this Duration Object.

The result is formatted according to the XML Schema 1.0 spec and can be always parsed back later into the equivalent Duration Object by DatatypeFactory.newDuration(String lexicalRepresentation).

Formally, the following holds for any Duration Object x:

 new Duration(x.toString()).equals(x)

Overrides:
toString in class Object
Returns:
A non-null valid String representation of this Duration.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLGregorianCalendar

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.datatype
Class XMLGregorianCalendar

java.lang.Object
    extended by  javax.xml.datatype.XMLGregorianCalendar
All Implemented Interfaces:
Cloneable
public abstract class XMLGregorianCalendar
extends Object
implements Cloneable

Representation for W3C XML Schema 1.0 date/time datatypes. Specifically, these date/time datatypes are DatatypeConstants.DATETIME, DatatypeConstants.TIME, DatatypeConstants.DATE, DatatypeConstants.GYEARMONTH, DatatypeConstants.GMONTHDAY, DatatypeConstants.GYEAR, DatatypeConstants.GMONTH, and DatatypeConstants.GDAY defined in the XML Namespace "http://www.w3.org/2001/XMLSchema". These datatypes are normatively defined in W3C XML Schema 1.0 Part 2, Section 3.2.7-14.

The table below defines the mapping between XML Schema 1.0 date/time datatype fields and this class' fields. It also summarizes the value constraints for the date and time fields defined in W3C XML Schema 1.0 Part 2, Appendix D, ISO 8601 Date and Time Formats.

Date/Time Datatype Field Mapping Between XML Schema 1.0 and Java Representation
XML Schema 1.0
datatype
field 		Related
XMLGregorianCalendar
Accessor(s) 		Value Range
year getYear() + getEon() or
getEonAndYear() 		getYear() is a value between -(10^9-1) to (10^9)-1 or DatatypeConstants.FIELD_UNDEFINED.
getEon() is high order year value in billion of years.
getEon() has values greater than or equal to (10^9) or less than or equal to -(10^9). A value of null indicates field is undefined.
Given that XML Schema 1.0 errata states that the year zero will be a valid lexical value in a future version of XML Schema, this class allows the year field to be set to zero. Otherwise, the year field value is handled exactly as described in the errata and [ISO-8601-1988]. Note that W3C XML Schema 1.0 validation does not allow for the year field to have a value of zero.
month | getMonth() | 1 to 12 or DatatypeConstants.FIELD_UNDEFINED
day getDay() Independent of month, max range is 1 to 31 or DatatypeConstants.FIELD_UNDEFINED.
The normative value constraint stated relative to month field's value is in W3C XML Schema 1.0 Part 2, Appendix D.
hour | getHour() | 0 to 24 or DatatypeConstants.FIELD_UNDEFINED. For a value of 24, the minute and second field must be zero per XML Schema Errata.
minute | getMinute() | 0 to 59 or DatatypeConstants.FIELD_UNDEFINED
second getSecond() + getMillisecond()/1000 or
getSecond() + getFractionalSecond() 		getSecond() from 0 to 60 or DatatypeConstants.FIELD_UNDEFINED.
(Note: 60 only allowable for leap second.)
getFractionalSecond() allows for infinite precision over the range from 0.0 to 1.0 when the getSecond() is defined.
FractionalSecond is optional and has a value of null when it is undefined.
getMillisecond() is the convenience millisecond precision of value of getFractionalSecond().
timezone | getTimezone() | Number of minutes or DatatypeConstants.FIELD_UNDEFINED. Value range from -14 hours (-14 * 60 minutes) to 14 hours (14 * 60 minutes).

All maximum value space constraints listed for the fields in the table above are checked by factory methods, @{link DatatypeFactory}, setter methods and parse methods of this class. IllegalArgumentException is thrown when a parameter's value is outside the value constraint for the field or if the composite values constitute an invalid XMLGregorianCalendar instance (for example, if the 31st of June is specified).

The following operations are defined for this class:

  • accessors/mutators for independent date/time fields
  • conversion between this class and W3C XML Schema 1.0 lexical representation, toString(), DatatypeFactory.newXMLGregorianCalendar(String lexicalRepresentation)
  • conversion between this class and GregorianCalendar, toGregorianCalendar(java.util.TimeZone timezone, java.util.Locale aLocale, XMLGregorianCalendar defaults), DatatypeFactory
  • partial order relation comparator method, compare(XMLGregorianCalendar xmlGregorianCalendar)
  • equals(Object) defined relative to compare(XMLGregorianCalendar xmlGregorianCalendar).
  • addition operation with Duration instance as defined in W3C XML Schema 1.0 Part 2, Appendix E, Adding durations to dateTimes.

Since:
1.5
See Also:
Duration, DatatypeFactory

Constructor Summary
XMLGregorianCalendar()
Default no-arg constructor.
Method Summary
abstract  void add(Duration duration)
Add duration to this instance.
abstract  void clear()
Unset all fields to undefined.
abstract  Object clone()
Creates and returns a copy of this object.
abstract  int compare(XMLGregorianCalendar xmlGregorianCalendar)
Compare two instances of W3C XML Schema 1.0 date/time datatypes according to partial order relation defined in W3C XML Schema 1.0 Part 2, Section 3.2.7.3, Order relation on dateTime.
 boolean equals(Object obj)
Compares this calendar to the specified object.
abstract  int getDay()
Return day in month or DatatypeConstants.FIELD_UNDEFINED.
abstract  BigInteger getEon()
Return high order component for XML Schema 1.0 dateTime datatype field for year.
abstract  BigInteger getEonAndYear()
Return XML Schema 1.0 dateTime datatype field for year.
abstract  BigDecimal getFractionalSecond()
Return fractional seconds.
abstract  int getHour()
Return hours or DatatypeConstants.FIELD_UNDEFINED.
 int getMillisecond()
Return millisecond precision of getFractionalSecond().
abstract  int getMinute()
Return minutes or DatatypeConstants.FIELD_UNDEFINED.
abstract  int getMonth()
Return number of month or DatatypeConstants.FIELD_UNDEFINED.
abstract  int getSecond()
Return seconds or DatatypeConstants.FIELD_UNDEFINED.
abstract  int getTimezone()
Return timezone offset in minutes or DatatypeConstants.FIELD_UNDEFINED if this optional field is not defined.
abstract  TimeZone getTimeZone(int defaultZoneoffset)
Returns a java.util.TimeZone for this class.
abstract  QName getXMLSchemaType()
Return the name of the XML Schema date/time type that this instance maps to.
abstract  int getYear()
Return low order component for XML Schema 1.0 dateTime datatype field for year or DatatypeConstants.FIELD_UNDEFINED.
 int hashCode()
Returns a hash code consistent with the definition of the equals method.
abstract  boolean isValid()
Validate instance by getXMLSchemaType() constraints.
abstract  XMLGregorianCalendar normalize()
Normalize this instance to UTC.
abstract  void reset()
Reset this XMLGregorianCalendar to its original values.
abstract  void setDay(int day)
Set days in month.
abstract  void setFractionalSecond(BigDecimal fractional)
Set fractional seconds.
abstract  void setHour(int hour)
Set hours.
abstract  void setMillisecond(int millisecond)
Set milliseconds.
abstract  void setMinute(int minute)
Set minutes.
abstract  void setMonth(int month)
Set month.
abstract  void setSecond(int second)
Set seconds.
 void setTime(int hour, int minute, int second)
Set time as one unit.
 void setTime(int hour, int minute, int second, BigDecimal fractional)
Set time as one unit, including the optional infinite precision fractional seconds.
 void setTime(int hour, int minute, int second, int millisecond)
Set time as one unit, including optional milliseconds.
abstract  void setTimezone(int offset)
Set the number of minutes in the timezone offset.
abstract  void setYear(BigInteger year)
Set low and high order component of XSD dateTime year field.
abstract  void setYear(int year)
Set year of XSD dateTime year field.
abstract  GregorianCalendar toGregorianCalendar()
Convert this XMLGregorianCalendar to a GregorianCalendar.
abstract  GregorianCalendar toGregorianCalendar(TimeZone timezone, Locale aLocale, XMLGregorianCalendar defaults)
Convert this XMLGregorianCalendar along with provided parameters to a GregorianCalendar instance.
 String toString()
Returns a String representation of this XMLGregorianCalendar Object.
abstract  String toXMLFormat()
Return the lexical representation of this instance.
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

XMLGregorianCalendar

public XMLGregorianCalendar()
Default no-arg constructor.

Note: Always use the DatatypeFactory to construct an instance of XMLGregorianCalendar. The constructor on this class cannot be guaranteed to produce an object with a consistent state and may be removed in the future.

Method Detail

clear

public abstract void clear()

Unset all fields to undefined.

Set all int fields to DatatypeConstants.FIELD_UNDEFINED and reference fields to null.

reset

public abstract void reset()

Reset this XMLGregorianCalendar to its original values.

XMLGregorianCalendar is reset to the same values as when it was created with DatatypeFactory.newXMLGregorianCalendar(), DatatypeFactory.newXMLGregorianCalendar(String lexicalRepresentation), DatatypeFactory.newXMLGregorianCalendar( BigInteger year, int month, int day, int hour, int minute, int second, BigDecimal fractionalSecond, int timezone), DatatypeFactory.newXMLGregorianCalendar( int year, int month, int day, int hour, int minute, int second, int millisecond, int timezone), DatatypeFactory.newXMLGregorianCalendar(GregorianCalendar cal), DatatypeFactory.newXMLGregorianCalendarDate( int year, int month, int day, int timezone), DatatypeFactory.newXMLGregorianCalendarTime( int hours, int minutes, int seconds, int timezone), DatatypeFactory.newXMLGregorianCalendarTime( int hours, int minutes, int seconds, BigDecimal fractionalSecond, int timezone) or DatatypeFactory.newXMLGregorianCalendarTime( int hours, int minutes, int seconds, int milliseconds, int timezone).

reset() is designed to allow the reuse of existing XMLGregorianCalendars thus saving resources associated with the creation of new XMLGregorianCalendars.

setYear

public abstract void setYear(BigInteger year)

Set low and high order component of XSD dateTime year field.

Unset this field by invoking the setter with a parameter value of null.

Parameters:
year - value constraints summarized in year field of date/time field mapping table.
Throws:
IllegalArgumentException - if year parameter is outside value constraints for the field as specified in date/time field mapping table.

setYear

public abstract void setYear(int year)

Set year of XSD dateTime year field.

Unset this field by invoking the setter with a parameter value of DatatypeConstants.FIELD_UNDEFINED.

Note: if the absolute value of the year parameter is less than 10^9, the eon component of the XSD year field is set to null by this method.

Parameters:
year - value constraints are summarized in year field of date/time field mapping table. If year is DatatypeConstants.FIELD_UNDEFINED, then eon is set to null.

setMonth

public abstract void setMonth(int month)

Set month.

Unset this field by invoking the setter with a parameter value of DatatypeConstants.FIELD_UNDEFINED.

Parameters:
month - value constraints summarized in month field of date/time field mapping table.
Throws:
IllegalArgumentException - if month parameter is outside value constraints for the field as specified in date/time field mapping table.

setDay

public abstract void setDay(int day)

Set days in month.

Unset this field by invoking the setter with a parameter value of DatatypeConstants.FIELD_UNDEFINED.

Parameters:
day - value constraints summarized in day field of date/time field mapping table.
Throws:
IllegalArgumentException - if day parameter is outside value constraints for the field as specified in date/time field mapping table.

setTimezone

public abstract void setTimezone(int offset)

Set the number of minutes in the timezone offset.

Unset this field by invoking the setter with a parameter value of DatatypeConstants.FIELD_UNDEFINED.

Parameters:
offset - value constraints summarized in timezone field of date/time field mapping table.
Throws:
IllegalArgumentException - if offset parameter is outside value constraints for the field as specified in date/time field mapping table.

setTime

public void setTime(int hour,
                    int minute,
                    int second)

Set time as one unit.

Parameters:
hour - value constraints are summarized in hour field of date/time field mapping table.
minute - value constraints are summarized in minute field of date/time field mapping table.
second - value constraints are summarized in second field of date/time field mapping table.
Throws:
IllegalArgumentException - if any parameter is outside value constraints for the field as specified in date/time field mapping table.
See Also:
setTime(int, int, int, BigDecimal)

setHour

public abstract void setHour(int hour)

Set hours.

Unset this field by invoking the setter with a parameter value of DatatypeConstants.FIELD_UNDEFINED.

Parameters:
hour - value constraints summarized in hour field of date/time field mapping table.
Throws:
IllegalArgumentException - if hour parameter is outside value constraints for the field as specified in date/time field mapping table.

setMinute

public abstract void setMinute(int minute)

Set minutes.

Unset this field by invoking the setter with a parameter value of DatatypeConstants.FIELD_UNDEFINED.

Parameters:
minute - value constraints summarized in minute field of date/time field mapping table.
Throws:
IllegalArgumentException - if minute parameter is outside value constraints for the field as specified in date/time field mapping table.

setSecond

public abstract void setSecond(int second)

Set seconds.

Unset this field by invoking the setter with a parameter value of DatatypeConstants.FIELD_UNDEFINED.

Parameters:
second - value constraints summarized in second field of date/time field mapping table.
Throws:
IllegalArgumentException - if second parameter is outside value constraints for the field as specified in date/time field mapping table.

setMillisecond

public abstract void setMillisecond(int millisecond)

Set milliseconds.

Unset this field by invoking the setter with a parameter value of DatatypeConstants.FIELD_UNDEFINED.

Parameters:
millisecond - value constraints summarized in second field of date/time field mapping table.
Throws:
IllegalArgumentException - if millisecond parameter is outside value constraints for the field as specified in date/time field mapping table.

setFractionalSecond

public abstract void setFractionalSecond(BigDecimal fractional)

Set fractional seconds.

Unset this field by invoking the setter with a parameter value of null.

Parameters:
fractional - value constraints summarized in second field of date/time field mapping table.
Throws:
IllegalArgumentException - if fractional parameter is outside value constraints for the field as specified in date/time field mapping table.

setTime

public void setTime(int hour,
                    int minute,
                    int second,
                    BigDecimal fractional)

Set time as one unit, including the optional infinite precision fractional seconds.

Parameters:
hour - value constraints are summarized in hour field of date/time field mapping table.
minute - value constraints are summarized in minute field of date/time field mapping table.
second - value constraints are summarized in second field of date/time field mapping table.
fractional - value of null indicates this optional field is not set.
Throws:
IllegalArgumentException - if any parameter is outside value constraints for the field as specified in date/time field mapping table.

setTime

public void setTime(int hour,
                    int minute,
                    int second,
                    int millisecond)

Set time as one unit, including optional milliseconds.

Parameters:
hour - value constraints are summarized in hour field of date/time field mapping table.
minute - value constraints are summarized in minute field of date/time field mapping table.
second - value constraints are summarized in second field of date/time field mapping table.
millisecond - value of DatatypeConstants.FIELD_UNDEFINED indicates this optional field is not set.
Throws:
IllegalArgumentException - if any parameter is outside value constraints for the field as specified in date/time field mapping table.

getEon

public abstract BigInteger getEon()

Return high order component for XML Schema 1.0 dateTime datatype field for year. null if this optional part of the year field is not defined.

Value constraints for this value are summarized in year field of date/time field mapping table.

Returns:
eon of this XMLGregorianCalendar. The value returned is an integer multiple of 10^9.
See Also:
getYear(), getEonAndYear()

getYear

public abstract int getYear()

Return low order component for XML Schema 1.0 dateTime datatype field for year or DatatypeConstants.FIELD_UNDEFINED.

Value constraints for this value are summarized in year field of date/time field mapping table.

Returns:
year of this XMLGregorianCalendar.
See Also:
getEon(), getEonAndYear()

getEonAndYear

public abstract BigInteger getEonAndYear()

Return XML Schema 1.0 dateTime datatype field for year.

Value constraints for this value are summarized in year field of date/time field mapping table.

Returns:
sum of eon and BigInteger.valueOf(year) when both fields are defined. When only year is defined, return it. When both eon and year are not defined, return null.
See Also:
getEon(), getYear()

getMonth

public abstract int getMonth()

Return number of month or DatatypeConstants.FIELD_UNDEFINED.

Value constraints for this value are summarized in month field of date/time field mapping table.

Returns:
year of this XMLGregorianCalendar.

getDay

public abstract int getDay()
Return day in month or DatatypeConstants.FIELD_UNDEFINED.

Value constraints for this value are summarized in day field of date/time field mapping table.

See Also:
setDay(int)

getTimezone

public abstract int getTimezone()
Return timezone offset in minutes or DatatypeConstants.FIELD_UNDEFINED if this optional field is not defined.

Value constraints for this value are summarized in timezone field of date/time field mapping table.

See Also:
setTimezone(int)

getHour

public abstract int getHour()
Return hours or DatatypeConstants.FIELD_UNDEFINED. Returns DatatypeConstants.FIELD_UNDEFINED if this field is not defined.

Value constraints for this value are summarized in hour field of date/time field mapping table.

See Also:
setTime(int, int, int)

getMinute

public abstract int getMinute()
Return minutes or DatatypeConstants.FIELD_UNDEFINED.

Returns DatatypeConstants.FIELD_UNDEFINED if this field is not defined.

Value constraints for this value are summarized in minute field of date/time field mapping table.

See Also:
setTime(int, int, int)

getSecond

public abstract int getSecond()

Return seconds or DatatypeConstants.FIELD_UNDEFINED.

Returns DatatypeConstants.FIELD_UNDEFINED if this field is not defined. When this field is not defined, the optional xs:dateTime fractional seconds field, represented by getFractionalSecond() and getMillisecond(), must not be defined.

Value constraints for this value are summarized in second field of date/time field mapping table.

Returns:
Second of this XMLGregorianCalendar.
See Also:
getFractionalSecond(),
getMillisecond(),
setTime(int, int, int)

getMillisecond

public int getMillisecond()

Return millisecond precision of getFractionalSecond().

This method represents a convenience accessor to infinite precision fractional second value returned by getFractionalSecond(). The returned value is the rounded down to milliseconds value of getFractionalSecond(). When getFractionalSecond() returns null, this method must return DatatypeConstants.FIELD_UNDEFINED.

Value constraints for this value are summarized in second field of date/time field mapping table.

Returns:
Millisecond of this XMLGregorianCalendar.
See Also:
getFractionalSecond(), setTime(int, int, int)

getFractionalSecond

public abstract BigDecimal getFractionalSecond()

Return fractional seconds.

null is returned when this optional field is not defined.

Value constraints are detailed in second field of date/time field mapping table.

This optional field can only have a defined value when the xs:dateTime second field, represented by getSecond(), does not return DatatypeConstants.FIELD_UNDEFINED.

Returns:
fractional seconds of this XMLGregorianCalendar.
See Also:
getSecond(), setTime(int, int, int, BigDecimal)

compare

public abstract int compare(XMLGregorianCalendar xmlGregorianCalendar)

Compare two instances of W3C XML Schema 1.0 date/time datatypes according to partial order relation defined in W3C XML Schema 1.0 Part 2, Section 3.2.7.3, Order relation on dateTime.

xsd:dateTime datatype field mapping to accessors of this class are defined in date/time field mapping table.

Parameters:
xmlGregorianCalendar - Instance of XMLGregorianCalendar to compare
Returns:
The relationship between this XMLGregorianCalendar and the specified xmlGregorianCalendar as DatatypeConstants.LESSER, DatatypeConstants.EQUAL, DatatypeConstants.GREATER or DatatypeConstants.INDETERMINATE.
Throws:
NullPointerException - if xmlGregorianCalendar is null.

normalize

public abstract XMLGregorianCalendar normalize()

Normalize this instance to UTC.

2000-03-04T23:00:00+03:00 normalizes to 2000-03-04T20:00:00Z

Implements W3C XML Schema Part 2, Section 3.2.7.3 (A).

Returns:
this XMLGregorianCalendar normalized to UTC.

equals

public boolean equals(Object obj)

Compares this calendar to the specified object. The result is true if and only if the argument is not null and is an XMLGregorianCalendar object that represents the same instant in time as this object.

Overrides:
equals in class Object
Parameters:
obj - to compare.
Returns:
true when obj is an instance of XMLGregorianCalendar and compare(XMLGregorianCalendar obj) returns DatatypeConstants.EQUAL, otherwise false.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()

Returns a hash code consistent with the definition of the equals method.

Overrides:
hashCode in class Object
Returns:
hash code of this object.
See Also:
Object.equals(java.lang.Object), Hashtable

toXMLFormat

public abstract String toXMLFormat()

Return the lexical representation of this instance. The format is specified in XML Schema 1.0 Part 2, Section 3.2.[7-14].1, Lexical Representation".

Specific target lexical representation format is determined by getXMLSchemaType().

Returns:
XML, as String, representation of this XMLGregorianCalendar
Throws:
IllegalStateException - if the combination of set fields does not match one of the eight defined XML Schema builtin date/time datatypes.

getXMLSchemaType

public abstract QName getXMLSchemaType()

Return the name of the XML Schema date/time type that this instance maps to. Type is computed based on fields that are set.

Required fields for XML Schema 1.0 Date/Time Datatypes.
(timezone is optional for all date/time datatypes)
Datatype | year | month | day | hour | minute | second
DatatypeConstants.DATETIME | X | X | X | X | X | X
DatatypeConstants.DATE | X | X | X
DatatypeConstants.TIME | X | X | X
DatatypeConstants.GYEARMONTH | X | X
DatatypeConstants.GMONTHDAY | X | X
DatatypeConstants.GYEAR | X
DatatypeConstants.GMONTH | X
DatatypeConstants.GDAY | X

Returns:
One of the following class constants: DatatypeConstants.DATETIME, DatatypeConstants.TIME, DatatypeConstants.DATE, DatatypeConstants.GYEARMONTH, DatatypeConstants.GMONTHDAY, DatatypeConstants.GYEAR, DatatypeConstants.GMONTH or DatatypeConstants.GDAY.
Throws:
IllegalStateException - if the combination of set fields does not match one of the eight defined XML Schema builtin date/time datatypes.

toString

public String toString()

Returns a String representation of this XMLGregorianCalendar Object.

The result is a lexical representation generated by toXMLFormat().

Overrides:
toString in class Object
Returns:
A non-null valid String representation of this XMLGregorianCalendar.
Throws:
IllegalStateException - if the combination of set fields does not match one of the eight defined XML Schema builtin date/time datatypes.
See Also:
toXMLFormat()

isValid

public abstract boolean isValid()
Validate instance by getXMLSchemaType() constraints.

Returns:
true if data values are valid.

add

public abstract void add(Duration duration)

Add duration to this instance.

The computation is specified in XML Schema 1.0 Part 2, Appendix E, Adding durations to dateTimes>. date/time field mapping table defines the mapping from XML Schema 1.0 dateTime fields to this class' representation of those fields.

Parameters:
duration - Duration to add to this XMLGregorianCalendar.
Throws:
NullPointerException - when duration parameter is null.

toGregorianCalendar

public abstract GregorianCalendar toGregorianCalendar()

Convert this XMLGregorianCalendar to a GregorianCalendar.

When this instance has an undefined field, this conversion relies on the java.util.GregorianCalendar default for its corresponding field. A notable difference between XML Schema 1.0 date/time datatypes and java.util.GregorianCalendar is that Timezone value is optional for date/time datatypes and it is a required field for java.util.GregorianCalendar. See javadoc for java.util.TimeZone.getDefault() on how the default is determined. To explicitly specify the TimeZone instance, see toGregorianCalendar(TimeZone, Locale, XMLGregorianCalendar).

Field by Field Conversion from this class to java.util.GregorianCalendar
java.util.GregorianCalendar field | javax.xml.datatype.XMLGregorianCalendar field
ERA | getEonAndYear() .signum() < 0 ? GregorianCalendar.BC : GregorianCalendar.AD
YEAR | getEonAndYear() .abs().intValue()*
MONTH | getMonth() - DatatypeConstants.JANUARY + Calendar.JANUARY
DAY_OF_MONTH | getDay()
HOUR_OF_DAY | getHour()
MINUTE | getMinute()
SECOND | getSecond()
MILLISECOND | get millisecond order from getFractionalSecond() *
GregorianCalendar.setTimeZone(TimeZone) | getTimezone() formatted into Custom timezone id
* designates possible loss of precision during the conversion due to source datatype having higher precision than target datatype.

To ensure consistency in conversion implementations, the new GregorianCalendar should be instantiated in following manner.

  • Using timeZone value as defined above, create a new java.util.GregorianCalendar(timeZone,Locale.getDefault()).
  • Initialize all GregorianCalendar fields by calling Calendar.clear().
  • Obtain a pure Gregorian Calendar by invoking GregorianCalendar.setGregorianChange( new Date(Long.MIN_VALUE)).
  • Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY, MINUTE, SECOND and MILLISECOND are set using the method Calendar.set(int,int)

See Also:
toGregorianCalendar(java.util.TimeZone, java.util.Locale, XMLGregorianCalendar)

toGregorianCalendar

public abstract GregorianCalendar toGregorianCalendar(TimeZone timezone,
                                                      Locale aLocale,
                                                      XMLGregorianCalendar defaults)

Convert this XMLGregorianCalendar along with provided parameters to a GregorianCalendar instance.

Since XML Schema 1.0 date/time datetypes has no concept of timezone ids or daylight savings timezone ids, this conversion operation allows the user to explicitly specify one with timezone parameter.

To compute the return value's TimeZone field,

  • when parameter timeZone is non-null, it is the timezone field.
  • else when this.getTimezone() != FIELD_UNDEFINED, create a java.util.TimeZone with a custom timezone id using the this.getTimezone().
  • else when defaults.getTimezone() != FIELD_UNDEFINED, create a java.util.TimeZone with a custom timezone id using defaults.getTimezone().
  • else use the GregorianCalendar default timezone value for the host is defined as specified by java.util.TimeZone.getDefault().

    • To ensure consistency in conversion implementations, the new GregorianCalendar should be instantiated in following manner.

    • Create a new java.util.GregorianCalendar(TimeZone, Locale) with TimeZone set as specified above and the Locale parameter.
    • Initialize all GregorianCalendar fields by calling Calendar.clear()
    • Obtain a pure Gregorian Calendar by invoking GregorianCalendar.setGregorianChange( new Date(Long.MIN_VALUE)).
    • Its fields ERA, YEAR, MONTH, DAY_OF_MONTH, HOUR_OF_DAY, MINUTE, SECOND and MILLISECOND are set using the method Calendar.set(int,int)

    Parameters:
    timezone - provide Timezone. null is a legal value.
    aLocale - provide explicit Locale. Use default GregorianCalendar locale if value is null.
    defaults - provide default field values to use when corresponding field for this instance is FIELD_UNDEFINED or null. If defaultsis null or a field within the specified defaults is undefined, just use java.util.GregorianCalendar defaults.
    Returns:
    a java.util.GregorianCalendar conversion of this instance.

getTimeZone

public abstract TimeZone getTimeZone(int defaultZoneoffset)

Returns a java.util.TimeZone for this class.

If timezone field is defined for this instance, returns TimeZone initialized with custom timezone id of zoneoffset. If timezone field is undefined, try the defaultZoneoffset that was passed in. If defaultZoneoffset is FIELD_UNDEFINED, return default timezone for this host. (Same default as java.util.GregorianCalendar).

Parameters:
defaultZoneoffset - default zoneoffset if this zoneoffset is DatatypeConstants.FIELD_UNDEFINED.
Returns:
TimeZone for this.

clone

public abstract Object clone()

Creates and returns a copy of this object.

Overrides:
clone in class Object
Returns:
copy of this Object
See Also:
Cloneable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


namespace

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.namespace

XML Namespace processing.

See:
Description

Interface Summary
NamespaceContext Interface for read only XML Namespace context processing.

Class Summary
QName QName represents a qualified name as defined in the XML specifications: XML Schema Part2: Datatypes specification, Namespaces in XML, Namespaces in XML Errata.

Package javax.xml.namespace Description

XML Namespace processing.

The following XML standards apply:

  • XML Schema Part2: Datatypes specification
  • Namespaces in XML
  • Namespaces in XML Errata

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.namespace Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.namespace

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.namespace.QName (implements java.io.Serializable)

Interface Hierarchy

  • javax.xml.namespace.NamespaceContext
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.namespace

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.namespace

Packages that use javax.xml.namespace
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.datatype | XML/Java Type Mappings.
javax.xml.namespace | XML Namespace processing.
javax.xml.soap | Provides the API for creating and building SOAP messages.
javax.xml.stream |
javax.xml.stream.events |
javax.xml.stream.util |
javax.xml.ws | This package contains the core JAX-WS APIs.
javax.xml.ws.handler | This package defines APIs for message handlers.
javax.xml.ws.handler.soap | This package defines APIs for SOAP message handlers.
javax.xml.ws.spi | This package defines SPIs for JAX-WS 2.0.
javax.xml.xpath | This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.

Classes in javax.xml.namespace used by javax.xml.bind
NamespaceContext
Interface for read only XML Namespace context processing.
QName
QName represents a qualified name as defined in the XML specifications: XML Schema Part2: Datatypes specification, Namespaces in XML, Namespaces in XML Errata.

Classes in javax.xml.namespace used by javax.xml.datatype
QName
QName represents a qualified name as defined in the XML specifications: XML Schema Part2: Datatypes specification, Namespaces in XML, Namespaces in XML Errata.

Classes in javax.xml.namespace used by javax.xml.namespace
QName
QName represents a qualified name as defined in the XML specifications: XML Schema Part2: Datatypes specification, Namespaces in XML, Namespaces in XML Errata.

Classes in javax.xml.namespace used by javax.xml.soap
QName
QName represents a qualified name as defined in the XML specifications: XML Schema Part2: Datatypes specification, Namespaces in XML, Namespaces in XML Errata.

Classes in javax.xml.namespace used by javax.xml.stream
NamespaceContext
Interface for read only XML Namespace context processing.
QName
QName represents a qualified name as defined in the XML specifications: XML Schema Part2: Datatypes specification, Namespaces in XML, Namespaces in XML Errata.

Classes in javax.xml.namespace used by javax.xml.stream.events
NamespaceContext
Interface for read only XML Namespace context processing.
QName
QName represents a qualified name as defined in the XML specifications: XML Schema Part2: Datatypes specification, Namespaces in XML, Namespaces in XML Errata.

Classes in javax.xml.namespace used by javax.xml.stream.util
NamespaceContext
Interface for read only XML Namespace context processing.
QName
QName represents a qualified name as defined in the XML specifications: XML Schema Part2: Datatypes specification, Namespaces in XML, Namespaces in XML Errata.

Classes in javax.xml.namespace used by javax.xml.ws
QName
QName represents a qualified name as defined in the XML specifications: XML Schema Part2: Datatypes specification, Namespaces in XML, Namespaces in XML Errata.

Classes in javax.xml.namespace used by javax.xml.ws.handler
QName
QName represents a qualified name as defined in the XML specifications: XML Schema Part2: Datatypes specification, Namespaces in XML, Namespaces in XML Errata.

Classes in javax.xml.namespace used by javax.xml.ws.handler.soap
QName
QName represents a qualified name as defined in the XML specifications: XML Schema Part2: Datatypes specification, Namespaces in XML, Namespaces in XML Errata.

Classes in javax.xml.namespace used by javax.xml.ws.spi
QName
QName represents a qualified name as defined in the XML specifications: XML Schema Part2: Datatypes specification, Namespaces in XML, Namespaces in XML Errata.

Classes in javax.xml.namespace used by javax.xml.xpath
NamespaceContext
Interface for read only XML Namespace context processing.
QName
QName represents a qualified name as defined in the XML specifications: XML Schema Part2: Datatypes specification, Namespaces in XML, Namespaces in XML Errata.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.namespace.QName

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.namespace.QName

Packages that use QName
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.datatype | XML/Java Type Mappings.
javax.xml.namespace | XML Namespace processing.
javax.xml.soap | Provides the API for creating and building SOAP messages.
javax.xml.stream |
javax.xml.stream.events |
javax.xml.stream.util |
javax.xml.ws | This package contains the core JAX-WS APIs.
javax.xml.ws.handler | This package defines APIs for message handlers.
javax.xml.ws.handler.soap | This package defines APIs for SOAP message handlers.
javax.xml.ws.spi | This package defines SPIs for JAX-WS 2.0.
javax.xml.xpath | This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.

Uses of QName in javax.xml.bind

Fields in javax.xml.bind declared as QName
protected  QName JAXBElement.name
xml element tag name

Methods in javax.xml.bind that return QName
abstract QName | JAXBIntrospector.getElementName(Object jaxbElement) Get xml element qname for jaxbElement.
QName | JAXBElement.getName() Returns the xml element tag name.
QName | DatatypeConverterInterface.parseQName(String lexicalXSDQName, NamespaceContext nsc) Converts the string argument into a QName value.
static QName | DatatypeConverter.parseQName(String lexicalXSDQName, NamespaceContext nsc) Converts the string argument into a byte value.

Methods in javax.xml.bind with parameters of type QName
String | DatatypeConverterInterface.printQName(QName val, NamespaceContext nsc) Converts a QName instance into a string.
static String | DatatypeConverter.printQName(QName val, NamespaceContext nsc) Converts a QName instance into a string.

Constructors in javax.xml.bind with parameters of type QName
JAXBElement(QName name, Class<T> declaredType, Class scope, T value)
Construct an xml element instance.
JAXBElement(QName name, Class<T> declaredType, T value)
Construct an xml element instance.

Uses of QName in javax.xml.datatype

Fields in javax.xml.datatype declared as QName
static QName | DatatypeConstants.DATE Fully qualified name for W3C XML Schema 1.0 datatype date.
static QName | DatatypeConstants.DATETIME Fully qualified name for W3C XML Schema 1.0 datatype dateTime.
static QName | DatatypeConstants.DURATION Fully qualified name for W3C XML Schema datatype duration.
static QName | DatatypeConstants.DURATION_DAYTIME Fully qualified name for XQuery 1.0 and XPath 2.0 datatype dayTimeDuration.
static QName | DatatypeConstants.DURATION_YEARMONTH Fully qualified name for XQuery 1.0 and XPath 2.0 datatype yearMonthDuration.
static QName | DatatypeConstants.GDAY Fully qualified name for W3C XML Schema 1.0 datatype gDay.
static QName | DatatypeConstants.GMONTH Fully qualified name for W3C XML Schema 1.0 datatype gMonth.
static QName | DatatypeConstants.GMONTHDAY Fully qualified name for W3C XML Schema 1.0 datatype gMonthDay.
static QName | DatatypeConstants.GYEAR Fully qualified name for W3C XML Schema 1.0 datatype gYear.
static QName | DatatypeConstants.GYEARMONTH Fully qualified name for W3C XML Schema 1.0 datatype gYearMonth.
static QName | DatatypeConstants.TIME Fully qualified name for W3C XML Schema 1.0 datatype time.

Methods in javax.xml.datatype that return QName
abstract QName | XMLGregorianCalendar.getXMLSchemaType() Return the name of the XML Schema date/time type that this instance maps to.
QName | Duration.getXMLSchemaType() Return the name of the XML Schema date/time type that this instance maps to.

Uses of QName in javax.xml.namespace

Methods in javax.xml.namespace that return QName
static QName QName.valueOf(String qNameAsString)
QName derived from parsing the formatted String.

Uses of QName in javax.xml.soap

Fields in javax.xml.soap declared as QName
static QName | SOAPConstants.SOAP_DATAENCODINGUNKNOWN_FAULT SOAP 1.2 DataEncodingUnknown Fault
static QName | SOAPConstants.SOAP_MUSTUNDERSTAND_FAULT SOAP 1.2 MustUnderstand Fault
static QName | SOAPConstants.SOAP_RECEIVER_FAULT SOAP 1.2 Receiver Fault
static QName | SOAPConstants.SOAP_SENDER_FAULT SOAP 1.2 Sender Fault
static QName | SOAPConstants.SOAP_VERSIONMISMATCH_FAULT SOAP 1.2 VersionMismatch Fault

Methods in javax.xml.soap that return QName
QName | SOAPElement.createQName(String localName, String prefix) Creates a QName whose namespace URI is the one associated with the parameter, prefix, in the context of this SOAPElement.
QName | SOAPElement.getElementQName() Returns the qname of this SOAPElement object.
QName | SOAPFault.getFaultCodeAsQName() Gets the fault code for this SOAPFault object as a QName object.

Methods in javax.xml.soap with parameters of type QName
SOAPElement | SOAPElement.addAttribute(QName qname, String value) Adds an attribute with the specified name and value to this SOAPElement object.
SOAPBodyElement | SOAPBody.addBodyElement(QName qname) Creates a new SOAPBodyElement object with the specified QName and adds it to this SOAPBody object.
SOAPElement | SOAPElement.addChildElement(QName qname) Creates a new SOAPElement object initialized with the given QName object and adds the new element to this SOAPElement object.
DetailEntry | Detail.addDetailEntry(QName qname) Creates a new DetailEntry object with the given QName and adds it to this Detail object.
SOAPFault | SOAPBody.addFault(QName faultCode, String faultString) Creates a new SOAPFault object and adds it to this SOAPBody object.
SOAPFault | SOAPBody.addFault(QName faultCode, String faultString, Locale locale) Creates a new SOAPFault object and adds it to this SOAPBody object.
SOAPHeaderElement | SOAPHeader.addHeaderElement(QName qname) Creates a new SOAPHeaderElement object initialized with the specified qname and adds it to this SOAPHeader object.
SOAPHeaderElement | SOAPHeader.addNotUnderstoodHeaderElement(QName name) Creates a new NotUnderstood SOAPHeaderElement object initialized with the specified name and adds it to this SOAPHeader object.
void | SOAPFault.appendFaultSubcode(QName subcode) Adds a Subcode to the end of the sequence of Subcodes contained by this SOAPFault.
SOAPElement | SOAPFactory.createElement(QName qname) Creates a SOAPElement object initialized with the given QName object.
abstract SOAPFault | SOAPFactory.createFault(String reasonText, QName faultCode) Creates a new SOAPFault object initialized with the given reasonText and faultCode
String | SOAPElement.getAttributeValue(QName qname) Returns the value of the attribute with the specified qname.
Iterator | SOAPElement.getChildElements(QName qname) Returns an Iterator over all the immediate child Nodes of this element with the specified qname.
boolean | SOAPElement.removeAttribute(QName qname) Removes the attribute with the specified qname.
SOAPElement | SOAPElement.setElementQName(QName newName) Changes the name of this Element to newName if possible.
void | SOAPFault.setFaultCode(QName faultCodeQName) Sets this SOAPFault object with the given fault code.

Uses of QName in javax.xml.stream

Methods in javax.xml.stream that return QName
QName | XMLStreamReader.getAttributeName(int index) Returns the qname of the attribute at the provided index
QName | XMLStreamReader.getName() Returns a QName for the current START_ELEMENT or END_ELEMENT event

Methods in javax.xml.stream with parameters of type QName
abstract Attribute | XMLEventFactory.createAttribute(QName name, String value) Create a new Attribute
abstract EndElement | XMLEventFactory.createEndElement(QName name, Iterator namespaces) Create a new EndElement
abstract StartElement | XMLEventFactory.createStartElement(QName name, Iterator attributes, Iterator namespaces) Create a new StartElement.

Uses of QName in javax.xml.stream.events

Methods in javax.xml.stream.events that return QName
QName | Attribute.getName() Returns the QName for this attribute
QName | EndElement.getName() Get the name of this event
QName | StartElement.getName() Get the name of this event
QName | XMLEvent.getSchemaType() This method is provided for implementations to provide optional type information about the associated event.

Methods in javax.xml.stream.events with parameters of type QName
 Attribute StartElement.getAttributeByName(QName name)
Returns the attribute referred to by this name

Uses of QName in javax.xml.stream.util

Methods in javax.xml.stream.util that return QName
QName | StreamReaderDelegate.getAttributeName(int index)
QName | StreamReaderDelegate.getName()

Uses of QName in javax.xml.ws

Methods in javax.xml.ws that return QName
 QName Service.getServiceName()
Gets the name of this service.

Methods in javax.xml.ws that return types with arguments of type QName
 Iterator<QName> Service.getPorts()
Returns an Iterator for the list of QNames of service endpoints grouped by this service

Methods in javax.xml.ws with parameters of type QName
 void Service.addPort(QName portName, String bindingId, String endpointAddress)
Creates a new port for the service.
static Service Service.create(QName serviceName)
Create a Service instance.
static Service Service.create(URL wsdlDocumentLocation, QName serviceName)
Create a Service instance.
<T> Dispatch<T>
Service.createDispatch(QName portName, Class<T> type, Service.Mode mode)
Creates a Dispatch instance for use with objects of the users choosing.
 Dispatch<Object> Service.createDispatch(QName portName, JAXBContext context, Service.Mode mode)
Creates a Dispatch instance for use with JAXB generated objects.
<T> T
Service.getPort(QName portName, Class<T> serviceEndpointInterface)
The getPort method returns a stub.

Constructors in javax.xml.ws with parameters of type QName
Service(URL wsdlDocumentLocation, QName serviceName)

Uses of QName in javax.xml.ws.handler

Methods in javax.xml.ws.handler that return QName
QName | PortInfo.getPortName() Gets the qualified name of the WSDL port being accessed.
QName | PortInfo.getServiceName() Gets the qualified name of the WSDL service name containing the port being accessed.

Uses of QName in javax.xml.ws.handler.soap

Methods in javax.xml.ws.handler.soap that return types with arguments of type QName
 Set<QName> SOAPHandler.getHeaders()
Gets the header blocks that can be processed by this Handler instance.

Methods in javax.xml.ws.handler.soap with parameters of type QName
 Object[] SOAPMessageContext.getHeaders(QName header, JAXBContext context, boolean allRoles)
Gets headers that have a particular qualified name from the message in the message context.

Uses of QName in javax.xml.ws.spi

Methods in javax.xml.ws.spi that return QName
abstract  QName ServiceDelegate.getServiceName()
Gets the name of this service.

Methods in javax.xml.ws.spi that return types with arguments of type QName
abstract  Iterator<QName> ServiceDelegate.getPorts()
Returns an Iterator for the list of QNames of service endpoints grouped by this service

Methods in javax.xml.ws.spi with parameters of type QName
abstract  void ServiceDelegate.addPort(QName portName, String bindingId, String endpointAddress)
Creates a new port for the service.
abstract
<T> Dispatch<T>
ServiceDelegate.createDispatch(QName portName, Class<T> type, Service.Mode mode)
Creates a Dispatch instance for use with objects of the users choosing.
abstract  Dispatch<Object> ServiceDelegate.createDispatch(QName portName, JAXBContext context, Service.Mode mode)
Creates a Dispatch instance for use with JAXB generated objects.
abstract  ServiceDelegate Provider.createServiceDelegate(URL wsdlDocumentLocation, QName serviceName, Class serviceClass)
Creates a service delegate object.
abstract
<T> T
ServiceDelegate.getPort(QName portName, Class<T> serviceEndpointInterface)
The getPort method returns a stub.

Uses of QName in javax.xml.xpath

Fields in javax.xml.xpath declared as QName
static QName | XPathConstants.BOOLEAN The XPath 1.0 boolean data type.
static QName | XPathConstants.NODE The XPath 1.0 NodeSet data type.
static QName | XPathConstants.NODESET The XPath 1.0 NodeSet data type.
static QName | XPathConstants.NUMBER The XPath 1.0 number data type.
static QName | XPathConstants.STRING The XPath 1.0 string data type.

Methods in javax.xml.xpath with parameters of type QName
Object | XPathExpression.evaluate(InputSource source, QName returnType) Evaluate the compiled XPath expression in the context of the specified InputSource and return the result as the specified type.
Object | XPathExpression.evaluate(Object item, QName returnType) Evaluate the compiled XPath expression in the specified context and return the result as the specified type.
Object | XPath.evaluate(String expression, InputSource source, QName returnType) Evaluate an XPath expression in the context of the specified InputSource and return the result as the specified type.
Object | XPath.evaluate(String expression, Object item, QName returnType) Evaluate an XPath expression in the specified context and return the result as the specified type.
XPathFunction | XPathFunctionResolver.resolveFunction(QName functionName, int arity) Find a function in the set of available functions.
Object | XPathVariableResolver.resolveVariable(QName variableName) Find a variable in the set of available variables.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.namespace.NamespaceContext

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.namespace.NamespaceContext

Packages that use NamespaceContext
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.stream |
javax.xml.stream.events |
javax.xml.stream.util |
javax.xml.xpath | This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.

Uses of NamespaceContext in javax.xml.bind

Methods in javax.xml.bind with parameters of type NamespaceContext
QName | DatatypeConverterInterface.parseQName(String lexicalXSDQName, NamespaceContext nsc) Converts the string argument into a QName value.
static QName | DatatypeConverter.parseQName(String lexicalXSDQName, NamespaceContext nsc) Converts the string argument into a byte value.
String | DatatypeConverterInterface.printQName(QName val, NamespaceContext nsc) Converts a QName instance into a string.
static String | DatatypeConverter.printQName(QName val, NamespaceContext nsc) Converts a QName instance into a string.

Uses of NamespaceContext in javax.xml.stream

Methods in javax.xml.stream that return NamespaceContext
NamespaceContext | XMLEventWriter.getNamespaceContext() Returns the current namespace context.
NamespaceContext | XMLStreamWriter.getNamespaceContext() Returns the current namespace context.
NamespaceContext | XMLStreamReader.getNamespaceContext() Returns a read only namespace context for the current position.

Methods in javax.xml.stream with parameters of type NamespaceContext
abstract StartElement | XMLEventFactory.createStartElement(String prefix, String namespaceUri, String localName, Iterator attributes, Iterator namespaces, NamespaceContext context) Create a new StartElement.
void | XMLEventWriter.setNamespaceContext(NamespaceContext context) Sets the current namespace context for prefix and uri bindings.
void | XMLStreamWriter.setNamespaceContext(NamespaceContext context) Sets the current namespace context for prefix and uri bindings.

Uses of NamespaceContext in javax.xml.stream.events

Methods in javax.xml.stream.events that return NamespaceContext
 NamespaceContext StartElement.getNamespaceContext()
Gets a read-only namespace context.

Uses of NamespaceContext in javax.xml.stream.util

Methods in javax.xml.stream.util that return NamespaceContext
 NamespaceContext StreamReaderDelegate.getNamespaceContext()

Uses of NamespaceContext in javax.xml.xpath

Methods in javax.xml.xpath that return NamespaceContext
 NamespaceContext XPath.getNamespaceContext()
Return the current namespace context.

Methods in javax.xml.xpath with parameters of type NamespaceContext
 void XPath.setNamespaceContext(NamespaceContext nsContext)
Establish a namespace context.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


NamespaceContext

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.namespace
Interface NamespaceContext

public interface NamespaceContext

Interface for read only XML Namespace context processing.

An XML Namespace has the properties:

  • Namespace URI: Namespace name expressed as a URI to which the prefix is bound
  • prefix: syntactically, this is the part of the attribute name following the XMLConstants.XMLNS_ATTRIBUTE ("xmlns") in the Namespace declaration

example: <element xmlns:prefix="http://Namespace-name-URI">

All get*(*) methods operate in the current scope for Namespace URI and prefix resolution.

Note that a Namespace URI can be bound to multiple prefixes in the current scope. This can occur when multiple XMLConstants.XMLNS_ATTRIBUTE ("xmlns") Namespace declarations occur in the same Start-Tag and refer to the same Namespace URI. e.g.

 <element xmlns:prefix1="http://Namespace-name-URI"
          xmlns:prefix2="http://Namespace-name-URI">
This can also occur when the same Namespace URI is used in multiple XMLConstants.XMLNS_ATTRIBUTE ("xmlns") Namespace declarations in the logical parent element hierarchy. e.g.
 <parent xmlns:prefix1="http://Namespace-name-URI">
   <child xmlns:prefix2="http://Namespace-name-URI">
     ...
   </child>
 </parent>

A prefix can only be bound to a single Namespace URI in the current scope.

Since:
1.5
See Also:
javax.xml.XMLConstants for declarations of common XML values, XML Schema Part2: Datatypes, Namespaces in XML, Namespaces in XML Errata

Method Summary
String | getNamespaceURI(String prefix) Get Namespace URI bound to a prefix in the current scope.
String | getPrefix(String namespaceURI) Get prefix bound to Namespace URI in the current scope.
Iterator | getPrefixes(String namespaceURI) Get all prefixes bound to a Namespace URI in the current scope.

Method Detail

getNamespaceURI

String getNamespaceURI(String prefix)

Get Namespace URI bound to a prefix in the current scope.

When requesting a Namespace URI by prefix, the following table describes the returned Namespace URI value for all possible prefix values:

getNamespaceURI(prefix) return value for specified prefixes
prefix parameter | Namespace URI return value
DEFAULT_NS_PREFIX ("") | default Namespace URI in the current scope or XMLConstants.NULL_NS_URI("") when there is no default Namespace URI in the current scope
bound prefix | Namespace URI bound to prefix in current scope
unbound prefix | XMLConstants.NULL_NS_URI("")
XMLConstants.XML_NS_PREFIX ("xml") | XMLConstants.XML_NS_URI ("http://www.w3.org/XML/1998/namespace")
XMLConstants.XMLNS_ATTRIBUTE ("xmlns") | XMLConstants.XMLNS_ATTRIBUTE_NS_URI ("http://www.w3.org/2000/xmlns/")
null | IllegalArgumentException is thrown

Parameters:
prefix - prefix to look up
Returns:
Namespace URI bound to prefix in the current scope
Throws:
IllegalArgumentException - When prefix is null

getPrefix

String getPrefix(String namespaceURI)

Get prefix bound to Namespace URI in the current scope.

To get all prefixes bound to a Namespace URI in the current scope, use getPrefixes(String namespaceURI).

When requesting a prefix by Namespace URI, the following table describes the returned prefix value for all Namespace URI values:

getPrefix(namespaceURI) return value for specified Namespace URIs
Namespace URI parameter | prefix value returned
<default Namespace URI> | XMLConstants.DEFAULT_NS_PREFIX ("")
bound Namespace URI | prefix bound to Namespace URI in the current scope, if multiple prefixes are bound to the Namespace URI in the current scope, a single arbitrary prefix, whose choice is implementation dependent, is returned
unbound Namespace URI | null
XMLConstants.XML_NS_URI ("http://www.w3.org/XML/1998/namespace") | XMLConstants.XML_NS_PREFIX ("xml")
XMLConstants.XMLNS_ATTRIBUTE_NS_URI ("http://www.w3.org/2000/xmlns/") | XMLConstants.XMLNS_ATTRIBUTE ("xmlns")
null | IllegalArgumentException is thrown

Parameters:
namespaceURI - URI of Namespace to lookup
Returns:
prefix bound to Namespace URI in current context
Throws:
IllegalArgumentException - When namespaceURI is null

getPrefixes

Iterator getPrefixes(String namespaceURI)

Get all prefixes bound to a Namespace URI in the current scope.

An Iterator over String elements is returned in an arbitrary, implementation dependent, order.

The Iterator is not modifiable. e.g. the remove() method will throw UnsupportedOperationException.

When requesting prefixes by Namespace URI, the following table describes the returned prefixes value for all Namespace URI values:

getPrefixes(namespaceURI) return value for specified Namespace URIs
Namespace URI parameter | prefixes value returned
bound Namespace URI, including the <default Namespace URI> | Iterator over prefixes bound to Namespace URI in the current scope in an arbitrary, implementation dependent, order
unbound Namespace URI | empty Iterator
XMLConstants.XML_NS_URI ("http://www.w3.org/XML/1998/namespace") | Iterator with one element set to XMLConstants.XML_NS_PREFIX ("xml")
XMLConstants.XMLNS_ATTRIBUTE_NS_URI ("http://www.w3.org/2000/xmlns/") | Iterator with one element set to XMLConstants.XMLNS_ATTRIBUTE ("xmlns")
null | IllegalArgumentException is thrown

Parameters:
namespaceURI - URI of Namespace to lookup
Returns:
Iterator for all prefixes bound to the Namespace URI in the current scope
Throws:
IllegalArgumentException - When namespaceURI is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


QName

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.namespace
Class QName

java.lang.Object
    extended by  javax.xml.namespace.QName
All Implemented Interfaces:
Serializable
public class QName
extends Object
implements Serializable

QName represents a qualified name as defined in the XML specifications: XML Schema Part2: Datatypes specification, Namespaces in XML, Namespaces in XML Errata.

The value of a QName contains a Namespace URI, local part and prefix.

The prefix is included in QName to retain lexical information when present in an XML input source. The prefix is NOT used in QName.equals(Object) or to compute the QName.hashCode(). Equality and the hash code are defined using only the Namespace URI and local part.

If not specified, the Namespace URI is set to XMLConstants.NULL_NS_URI. If not specified, the prefix is set to XMLConstants.DEFAULT_NS_PREFIX.

QName is immutable.

Since:
1.5
See Also:
XML Schema Part2: Datatypes specification, Namespaces in XML, Namespaces in XML Errata, Serialized Form

Constructor Summary
QName(String localPart)
QName constructor specifying the local part.
QName(String namespaceURI, String localPart)
QName constructor specifying the Namespace URI and local part.
QName(String namespaceURI, String localPart, String prefix)
QName constructor specifying the Namespace URI, local part and prefix.
Method Summary
boolean | equals(Object objectToTest) Test this QName for equality with another Object.
String | getLocalPart() Get the local part of this QName.
String | getNamespaceURI() Get the Namespace URI of this QName.
String | getPrefix() Get the prefix of this QName.
int | hashCode() Generate the hash code for this QName.
String | toString() String representation of this QName.
static QName | valueOf(String qNameAsString) QName derived from parsing the formatted String.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

QName

public QName(String namespaceURI,
             String localPart)

QName constructor specifying the Namespace URI and local part.

If the Namespace URI is null, it is set to XMLConstants.NULL_NS_URI. This value represents no explicitly defined Namespace as defined by the Namespaces in XML specification. This action preserves compatible behavior with QName 1.0. Explicitly providing the XMLConstants.NULL_NS_URI value is the preferred coding style.

If the local part is null an IllegalArgumentException is thrown. A local part of "" is allowed to preserve compatible behavior with QName 1.0.

When using this constructor, the prefix is set to XMLConstants.DEFAULT_NS_PREFIX.

The Namespace URI is not validated as a URI reference. The local part is not validated as a NCName as specified in Namespaces in XML.

Parameters:
namespaceURI - Namespace URI of the QName
localPart - local part of the QName
Throws:
IllegalArgumentException - When localPart is null
See Also:
QName(String namespaceURI, String localPart, String prefix)

QName

public QName(String namespaceURI,
             String localPart,
             String prefix)

QName constructor specifying the Namespace URI, local part and prefix.

If the Namespace URI is null, it is set to XMLConstants.NULL_NS_URI. This value represents no explicitly defined Namespace as defined by the Namespaces in XML specification. This action preserves compatible behavior with QName 1.0. Explicitly providing the XMLConstants.NULL_NS_URI value is the preferred coding style.

If the local part is null an IllegalArgumentException is thrown. A local part of "" is allowed to preserve compatible behavior with QName 1.0.

If the prefix is null, an IllegalArgumentException is thrown. Use XMLConstants.DEFAULT_NS_PREFIX to explicitly indicate that no prefix is present or the prefix is not relevant.

The Namespace URI is not validated as a URI reference. The local part and prefix are not validated as a NCName as specified in Namespaces in XML.

Parameters:
namespaceURI - Namespace URI of the QName
localPart - local part of the QName
prefix - prefix of the QName
Throws:
IllegalArgumentException - When localPart or prefix is null

QName

public QName(String localPart)

QName constructor specifying the local part.

If the local part is null an IllegalArgumentException is thrown. A local part of "" is allowed to preserve compatible behavior with QName 1.0.

When using this constructor, the Namespace URI is set to XMLConstants.NULL_NS_URI and the prefix is set to XMLConstants.DEFAULT_NS_PREFIX.

In an XML context, all Element and Attribute names exist in the context of a Namespace. Making this explicit during the construction of a QName helps prevent hard to diagnosis XML validity errors. The constructors QName(String namespaceURI, String localPart) and QName(String namespaceURI, String localPart, String prefix) are preferred.

The local part is not validated as a NCName as specified in Namespaces in XML.

Parameters:
localPart - local part of the QName
Throws:
IllegalArgumentException - When localPart is null
See Also:
QName(String namespaceURI, String localPart), QName(String namespaceURI, String localPart, String prefix)
Method Detail

getNamespaceURI

public String getNamespaceURI()

Get the Namespace URI of this QName.

Returns:
Namespace URI of this QName

getLocalPart

public String getLocalPart()

Get the local part of this QName.

Returns:
local part of this QName

getPrefix

public String getPrefix()

Get the prefix of this QName.

The prefix assigned to a QName might NOT be valid in a different context. For example, a QName may be assigned a prefix in the context of parsing a document but that prefix may be invalid in the context of a different document.

Returns:
prefix of this QName

equals

public final boolean equals(Object objectToTest)

Test this QName for equality with another Object.

If the Object to be tested is not a QName or is null, then this method returns false.

Two QNames are considered equal if and only if both the Namespace URI and local part are equal. This method uses String.equals() to check equality of the Namespace URI and local part. The prefix is NOT used to determine equality.

This method satisfies the general contract of Object.equals(Object)

Overrides:
equals in class Object
Parameters:
objectToTest - the Object to test for equality with this QName
Returns:
true if the given Object is equal to this QName else false
See Also:
Object.hashCode(), Hashtable

hashCode

public final int hashCode()

Generate the hash code for this QName.

The hash code is calculated using both the Namespace URI and the local part of the QName. The prefix is NOT used to calculate the hash code.

This method satisfies the general contract of Object.hashCode().

Overrides:
hashCode in class Object
Returns:
hash code for this QName Object
See Also:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()

String representation of this QName.

The commonly accepted way of representing a QName as a String was defined by James Clark. Although this is not a standard specification, it is in common use, e.g. Transformer.setParameter(String name, Object value). This implementation represents a QName as: "{" + Namespace URI + "}" + local part. If the Namespace URI .equals(XMLConstants.NULL_NS_URI), only the local part is returned. An appropriate use of this method is for debugging or logging for human consumption.

Note the prefix value is NOT returned as part of the String representation.

This method satisfies the general contract of Object.toString().

Overrides:
toString in class Object
Returns:
String representation of this QName

valueOf

public static QName valueOf(String qNameAsString)

QName derived from parsing the formatted String.

If the String is null or does not conform to QName.toString() formatting, an IllegalArgumentException is thrown.

The String MUST be in the form returned by QName.toString().

The commonly accepted way of representing a QName as a String was defined by James Clark. Although this is not a standard specification, it is in common use, e.g. Transformer.setParameter(String name, Object value). This implementation parses a String formatted as: "{" + Namespace URI + "}" + local part. If the Namespace URI .equals(XMLConstants.NULL_NS_URI), only the local part should be provided.

The prefix value CANNOT be represented in the String and will be set to XMLConstants.DEFAULT_NS_PREFIX.

This method does not do full validation of the resulting QName.

The Namespace URI is not validated as a URI reference. The local part is not validated as a NCName as specified in Namespaces in XML.

Parameters:
qNameAsString - String representation of the QName
Returns:
QName corresponding to the given String
Throws:
IllegalArgumentException - When qNameAsString is null or malformed
See Also:
QName.toString()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


parsers

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.parsers

Provides classes allowing the processing of XML documents.

See:
Description

Class Summary
DocumentBuilder | Defines the API to obtain DOM Document instances from an XML document.
DocumentBuilderFactory | Defines a factory API that enables applications to obtain a parser that produces DOM object trees from XML documents.
SAXParser | Defines the API that wraps an XMLReader implementation class.
SAXParserFactory | Defines a factory API that enables applications to configure and obtain a SAX based parser to parse XML documents.

Exception Summary
ParserConfigurationException Indicates a serious configuration error.

Error Summary
FactoryConfigurationError Thrown when a problem with configuration with the Parser Factories exists.

Package javax.xml.parsers Description

Provides classes allowing the processing of XML documents. Two types of plugable parsers are supported:

  • SAX (Simple API for XML)
  • DOM (Document Object Model)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.parsers Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.parsers

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.parsers.DocumentBuilder
    • javax.xml.parsers.DocumentBuilderFactory
    • javax.xml.parsers.SAXParser
    • javax.xml.parsers.SAXParserFactory
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Error
        • javax.xml.parsers.FactoryConfigurationError
      • java.lang.Exception
        • javax.xml.parsers.ParserConfigurationException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.parsers

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.parsers

Packages that use javax.xml.parsers
javax.xml.bind.annotation | Defines annotations for customizing Java program elements to XML Schema mapping.
javax.xml.parsers | Provides classes allowing the processing of XML documents.

Classes in javax.xml.parsers used by javax.xml.bind.annotation
DocumentBuilder
Defines the API to obtain DOM Document instances from an XML document.

Classes in javax.xml.parsers used by javax.xml.parsers
DocumentBuilder
Defines the API to obtain DOM Document instances from an XML document.
DocumentBuilderFactory
Defines a factory API that enables applications to obtain a parser that produces DOM object trees from XML documents.
ParserConfigurationException
Indicates a serious configuration error.
SAXParser
Defines the API that wraps an XMLReader implementation class.
SAXParserFactory
Defines a factory API that enables applications to configure and obtain a SAX based parser to parse XML documents.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.parsers.DocumentBuilder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.parsers.DocumentBuilder

Packages that use DocumentBuilder
javax.xml.bind.annotation | Defines annotations for customizing Java program elements to XML Schema mapping.
javax.xml.parsers | Provides classes allowing the processing of XML documents.

Uses of DocumentBuilder in javax.xml.bind.annotation

Methods in javax.xml.bind.annotation that return DocumentBuilder
 DocumentBuilder W3CDomHandler.getBuilder()

Methods in javax.xml.bind.annotation with parameters of type DocumentBuilder
 void W3CDomHandler.setBuilder(DocumentBuilder builder)

Constructors in javax.xml.bind.annotation with parameters of type DocumentBuilder
W3CDomHandler(DocumentBuilder builder)
Constructor that allows applications to specify which DOM implementation to be used.

Uses of DocumentBuilder in javax.xml.parsers

Methods in javax.xml.parsers that return DocumentBuilder
abstract  DocumentBuilder DocumentBuilderFactory.newDocumentBuilder()
Creates a new instance of a DocumentBuilder using the currently configured parameters.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.parsers.DocumentBuilderFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.parsers.DocumentBuilderFactory

Packages that use DocumentBuilderFactory
javax.xml.parsers Provides classes allowing the processing of XML documents.

Uses of DocumentBuilderFactory in javax.xml.parsers

Methods in javax.xml.parsers that return DocumentBuilderFactory
static DocumentBuilderFactory | DocumentBuilderFactory.newInstance() Obtain a new instance of a DocumentBuilderFactory.
static DocumentBuilderFactory | DocumentBuilderFactory.newInstance(String factoryClassName, ClassLoader classLoader) Obtain a new instance of a DocumentBuilderFactory from class name.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.parsers.FactoryConfigurationError

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.parsers.FactoryConfigurationError

No usage of javax.xml.parsers.FactoryConfigurationError

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.parsers.ParserConfigurationException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.parsers.ParserConfigurationException

Packages that use ParserConfigurationException
javax.xml.parsers Provides classes allowing the processing of XML documents.

Uses of ParserConfigurationException in javax.xml.parsers

Methods in javax.xml.parsers that throw ParserConfigurationException
abstract boolean | SAXParserFactory.getFeature(String name) Returns the particular property requested for in the underlying implementation of org.xml.sax.XMLReader.
abstract boolean | DocumentBuilderFactory.getFeature(String name) Get the state of the named feature.
abstract DocumentBuilder | DocumentBuilderFactory.newDocumentBuilder() Creates a new instance of a DocumentBuilder using the currently configured parameters.
abstract SAXParser | SAXParserFactory.newSAXParser() Creates a new instance of a SAXParser using the currently configured factory parameters.
abstract void | SAXParserFactory.setFeature(String name, boolean value) Sets the particular feature in the underlying implementation of org.xml.sax.XMLReader.
abstract void | DocumentBuilderFactory.setFeature(String name, boolean value) Set a feature for this DocumentBuilderFactory and DocumentBuilders created by this factory.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.parsers.SAXParser

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.parsers.SAXParser

Packages that use SAXParser
javax.xml.parsers Provides classes allowing the processing of XML documents.

Uses of SAXParser in javax.xml.parsers

Methods in javax.xml.parsers that return SAXParser
abstract  SAXParser SAXParserFactory.newSAXParser()
Creates a new instance of a SAXParser using the currently configured factory parameters.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.parsers.SAXParserFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.parsers.SAXParserFactory

Packages that use SAXParserFactory
javax.xml.parsers Provides classes allowing the processing of XML documents.

Uses of SAXParserFactory in javax.xml.parsers

Methods in javax.xml.parsers that return SAXParserFactory
static SAXParserFactory | SAXParserFactory.newInstance() Obtain a new instance of a SAXParserFactory.
static SAXParserFactory | SAXParserFactory.newInstance(String factoryClassName, ClassLoader classLoader) Obtain a new instance of a SAXParserFactory from class name.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DocumentBuilder

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.parsers
Class DocumentBuilder

java.lang.Object
    extended by  javax.xml.parsers.DocumentBuilder

public abstract class DocumentBuilder
extends Object

Defines the API to obtain DOM Document instances from an XML document. Using this class, an application programmer can obtain a Document from XML.

An instance of this class can be obtained from the DocumentBuilderFactory.newDocumentBuilder() method. Once an instance of this class is obtained, XML can be parsed from a variety of input sources. These input sources are InputStreams, Files, URLs, and SAX InputSources.

Note that this class reuses several classes from the SAX API. This does not require that the implementor of the underlying DOM implementation use a SAX parser to parse XML document into a Document. It merely requires that the implementation communicate with the application using these existing APIs.

Constructor Summary
protected DocumentBuilder()
Protected constructor
Method Summary
abstract DOMImplementation | getDOMImplementation() Obtain an instance of a DOMImplementation object.
Schema | getSchema() Get a reference to the the Schema being used by the XML processor.
abstract boolean | isNamespaceAware() Indicates whether or not this parser is configured to understand namespaces.
abstract boolean | isValidating() Indicates whether or not this parser is configured to validate XML documents.
boolean | isXIncludeAware() Get the XInclude processing mode for this parser.
abstract Document | newDocument() Obtain a new instance of a DOM Document object to build a DOM tree with.
Document | parse(File f) Parse the content of the given file as an XML document and return a new DOM Document object.
abstract Document | parse(InputSource is) Parse the content of the given input source as an XML document and return a new DOM Document object.
Document | parse(InputStream is) Parse the content of the given InputStream as an XML document and return a new DOM Document object.
Document | parse(InputStream is, String systemId) Parse the content of the given InputStream as an XML document and return a new DOM Document object.
Document | parse(String uri) Parse the content of the given URI as an XML document and return a new DOM Document object.
void | reset() Reset this DocumentBuilder to its original configuration.
abstract void | setEntityResolver(EntityResolver er) Specify the EntityResolver to be used to resolve entities present in the XML document to be parsed.
abstract void | setErrorHandler(ErrorHandler eh) Specify the ErrorHandler to be used by the parser.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DocumentBuilder

protected DocumentBuilder()
Protected constructor

Method Detail

reset

public void reset()

Reset this DocumentBuilder to its original configuration.

DocumentBuilder is reset to the same state as when it was created with DocumentBuilderFactory.newDocumentBuilder(). reset() is designed to allow the reuse of existing DocumentBuilders thus saving resources associated with the creation of new DocumentBuilders.

The reset DocumentBuilder is not guaranteed to have the same EntityResolver or ErrorHandler Objects, e.g. Object.equals(Object obj). It is guaranteed to have a functionally equal EntityResolver and ErrorHandler.

Throws:
UnsupportedOperationException - When implementation does not override this method.
Since:
1.5

parse

public Document parse(InputStream is)
               throws SAXException,
                      IOException
Parse the content of the given InputStream as an XML document and return a new DOM Document object. An IllegalArgumentException is thrown if the InputStream is null.

Parameters:
is - InputStream containing the content to be parsed.
Returns:
Document result of parsing the InputStream
Throws:
IOException - If any IO errors occur.
SAXException - If any parse errors occur.
IllegalArgumentException - When is is null
See Also:
DocumentHandler

parse

public Document parse(InputStream is,
                      String systemId)
               throws SAXException,
                      IOException
Parse the content of the given InputStream as an XML document and return a new DOM Document object. An IllegalArgumentException is thrown if the InputStream is null.

Parameters:
is - InputStream containing the content to be parsed.
systemId - Provide a base for resolving relative URIs.
Returns:
A new DOM Document object.
Throws:
IOException - If any IO errors occur.
SAXException - If any parse errors occur.
IllegalArgumentException - When is is null
See Also:
DocumentHandler

parse

public Document parse(String uri)
               throws SAXException,
                      IOException
Parse the content of the given URI as an XML document and return a new DOM Document object. An IllegalArgumentException is thrown if the URI is null null.

Parameters:
uri - The location of the content to be parsed.
Returns:
A new DOM Document object.
Throws:
IOException - If any IO errors occur.
SAXException - If any parse errors occur.
IllegalArgumentException - When uri is null
See Also:
DocumentHandler

parse

public Document parse(File f)
               throws SAXException,
                      IOException
Parse the content of the given file as an XML document and return a new DOM Document object. An IllegalArgumentException is thrown if the File is null null.

Parameters:
f - The file containing the XML to parse.
Returns:
A new DOM Document object.
Throws:
IOException - If any IO errors occur.
SAXException - If any parse errors occur.
IllegalArgumentException - When f is null
See Also:
DocumentHandler

parse

public abstract Document parse(InputSource is)
                        throws SAXException,
                               IOException
Parse the content of the given input source as an XML document and return a new DOM Document object. An IllegalArgumentException is thrown if the InputSource is null null.

Parameters:
is - InputSource containing the content to be parsed.
Returns:
A new DOM Document object.
Throws:
IOException - If any IO errors occur.
SAXException - If any parse errors occur.
IllegalArgumentException - When is is null
See Also:
DocumentHandler

isNamespaceAware

public abstract boolean isNamespaceAware()
Indicates whether or not this parser is configured to understand namespaces.

Returns:
true if this parser is configured to understand namespaces; false otherwise.

isValidating

public abstract boolean isValidating()
Indicates whether or not this parser is configured to validate XML documents.

Returns:
true if this parser is configured to validate XML documents; false otherwise.

setEntityResolver

public abstract void setEntityResolver(EntityResolver er)
Specify the EntityResolver to be used to resolve entities present in the XML document to be parsed. Setting this to null will result in the underlying implementation using it's own default implementation and behavior.

Parameters:
er - The EntityResolver to be used to resolve entities present in the XML document to be parsed.

setErrorHandler

public abstract void setErrorHandler(ErrorHandler eh)
Specify the ErrorHandler to be used by the parser. Setting this to null will result in the underlying implementation using it's own default implementation and behavior.

Parameters:
eh - The ErrorHandler to be used by the parser.

newDocument

public abstract Document newDocument()
Obtain a new instance of a DOM Document object to build a DOM tree with.

Returns:
A new instance of a DOM Document object.

getDOMImplementation

public abstract DOMImplementation getDOMImplementation()
Obtain an instance of a DOMImplementation object.

Returns:
A new instance of a DOMImplementation.

getSchema

public Schema getSchema()

Get a reference to the the Schema being used by the XML processor.

If no schema is being used, null is returned.

Returns:
Schema being used or null if none in use
Throws:
UnsupportedOperationException - When implementation does not override this method
Since:
1.5

isXIncludeAware

public boolean isXIncludeAware()

Get the XInclude processing mode for this parser.

Returns:
the return value of the DocumentBuilderFactory.isXIncludeAware() when this parser was created from factory.
Throws:
UnsupportedOperationException - When implementation does not override this method
Since:
1.5
See Also:
DocumentBuilderFactory.setXIncludeAware(boolean)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


DocumentBuilderFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.parsers
Class DocumentBuilderFactory

java.lang.Object
    extended by  javax.xml.parsers.DocumentBuilderFactory

public abstract class DocumentBuilderFactory
extends Object

Defines a factory API that enables applications to obtain a parser that produces DOM object trees from XML documents.

Constructor Summary
protected DocumentBuilderFactory()
Protected constructor to prevent instantiation.
Method Summary
abstract Object | getAttribute(String name) Allows the user to retrieve specific attributes on the underlying implementation.
abstract boolean | getFeature(String name) Get the state of the named feature.
Schema | getSchema() Gets the Schema object specified through the setSchema(Schema schema) method.
boolean | isCoalescing() Indicates whether or not the factory is configured to produce parsers which converts CDATA nodes to Text nodes and appends it to the adjacent (if any) Text node.
boolean | isExpandEntityReferences() Indicates whether or not the factory is configured to produce parsers which expand entity reference nodes.
boolean | isIgnoringComments() Indicates whether or not the factory is configured to produce parsers which ignores comments.
boolean | isIgnoringElementContentWhitespace() Indicates whether or not the factory is configured to produce parsers which ignore ignorable whitespace in element content.
boolean | isNamespaceAware() Indicates whether or not the factory is configured to produce parsers which are namespace aware.
boolean | isValidating() Indicates whether or not the factory is configured to produce parsers which validate the XML content during parse.
boolean | isXIncludeAware() Get state of XInclude processing.
abstract DocumentBuilder | newDocumentBuilder() Creates a new instance of a DocumentBuilder using the currently configured parameters.
static DocumentBuilderFactory | newInstance() Obtain a new instance of a DocumentBuilderFactory.
static DocumentBuilderFactory | newInstance(String factoryClassName, ClassLoader classLoader) Obtain a new instance of a DocumentBuilderFactory from class name.
abstract void | setAttribute(String name, Object value) Allows the user to set specific attributes on the underlying implementation.
void | setCoalescing(boolean coalescing) Specifies that the parser produced by this code will convert CDATA nodes to Text nodes and append it to the adjacent (if any) text node.
void | setExpandEntityReferences(boolean expandEntityRef) Specifies that the parser produced by this code will expand entity reference nodes.
abstract void | setFeature(String name, boolean value) Set a feature for this DocumentBuilderFactory and DocumentBuilders created by this factory.
void | setIgnoringComments(boolean ignoreComments) Specifies that the parser produced by this code will ignore comments.
void | setIgnoringElementContentWhitespace(boolean whitespace) Specifies that the parsers created by this factory must eliminate whitespace in element content (sometimes known loosely as 'ignorable whitespace') when parsing XML documents (see XML Rec 2.10).
void | setNamespaceAware(boolean awareness) Specifies that the parser produced by this code will provide support for XML namespaces.
void | setSchema(Schema schema) Set the Schema to be used by parsers created from this factory.
void | setValidating(boolean validating) Specifies that the parser produced by this code will validate documents as they are parsed.
void | setXIncludeAware(boolean state) Set state of XInclude processing.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DocumentBuilderFactory

protected DocumentBuilderFactory()

Protected constructor to prevent instantiation. Use newInstance().

Method Detail

newInstance

public static DocumentBuilderFactory newInstance()
Obtain a new instance of a DocumentBuilderFactory. This static method creates a new factory instance. This method uses the following ordered lookup procedure to determine the DocumentBuilderFactory implementation class to load:
  • Use the javax.xml.parsers.DocumentBuilderFactory system property.
  • Use the properties file "lib/jaxp.properties" in the JRE directory. This configuration file is in standard java.util.Properties format and contains the fully qualified name of the implementation class with the key being the system property defined above. The jaxp.properties file is read only once by the JAXP implementation and it's values are then cached for future use. If the file does not exist when the first attempt is made to read from it, no further attempts are made to check for its existence. It is not possible to change the value of any property in jaxp.properties after it has been read for the first time.
  • Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for a classname in the file META-INF/services/javax.xml.parsers.DocumentBuilderFactory in jars available to the runtime.
  • Platform default DocumentBuilderFactory instance.
Once an application has obtained a reference to a DocumentBuilderFactory it can use the factory to configure and obtain parser instances.

Tip for Trouble-shooting

Setting the jaxp.debug system property will cause this method to print a lot of debug messages to System.err about what it is doing and where it is looking at.

If you have problems loading DocumentBuilders, try:

 java -Djaxp.debug=1 YourProgram ....

Returns:
New instance of a DocumentBuilderFactory
Throws:
FactoryConfigurationError - if the implementation is not available or cannot be instantiated.

newInstance

public static DocumentBuilderFactory newInstance(String factoryClassName,
                                                 ClassLoader classLoader)

Obtain a new instance of a DocumentBuilderFactory from class name. This function is useful when there are multiple providers in the classpath. It gives more control to the application as it can specify which provider should be loaded.

Once an application has obtained a reference to a DocumentBuilderFactory it can use the factory to configure and obtain parser instances.

Tip for Trouble-shooting

Setting the jaxp.debug system property will cause this method to print a lot of debug messages to System.err about what it is doing and where it is looking at.

If you have problems try:

 java -Djaxp.debug=1 YourProgram ....

Parameters:
factoryClassName - fully qualified factory class name that provides implementation of javax.xml.parsers.DocumentBuilderFactory.
classLoader - ClassLoader used to load the factory class. If null current Thread's context classLoader is used to load the factory class.
Returns:
New instance of a DocumentBuilderFactory
Throws:
FactoryConfigurationError - if factoryClassName is null, or the factory class cannot be loaded, instantiated.
Since:
1.6
See Also:
newInstance()

newDocumentBuilder

public abstract DocumentBuilder newDocumentBuilder()
                                            throws ParserConfigurationException
Creates a new instance of a DocumentBuilder using the currently configured parameters.

Returns:
A new instance of a DocumentBuilder.
Throws:
ParserConfigurationException - if a DocumentBuilder cannot be created which satisfies the configuration requested.

setNamespaceAware

public void setNamespaceAware(boolean awareness)
Specifies that the parser produced by this code will provide support for XML namespaces. By default the value of this is set to false

Parameters:
awareness - true if the parser produced will provide support for XML namespaces; false otherwise.

setValidating

public void setValidating(boolean validating)
Specifies that the parser produced by this code will validate documents as they are parsed. By default the value of this is set to false.

Note that "the validation" here means a validating parser as defined in the XML recommendation. In other words, it essentially just controls the DTD validation. (except the legacy two properties defined in JAXP 1.2.)

To use modern schema languages such as W3C XML Schema or RELAX NG instead of DTD, you can configure your parser to be a non-validating parser by leaving the setValidating(boolean) method false, then use the setSchema(Schema) method to associate a schema to a parser.

Parameters:
validating - true if the parser produced will validate documents as they are parsed; false otherwise.

setIgnoringElementContentWhitespace

public void setIgnoringElementContentWhitespace(boolean whitespace)
Specifies that the parsers created by this factory must eliminate whitespace in element content (sometimes known loosely as 'ignorable whitespace') when parsing XML documents (see XML Rec 2.10). Note that only whitespace which is directly contained within element content that has an element only content model (see XML Rec 3.2.1) will be eliminated. Due to reliance on the content model this setting requires the parser to be in validating mode. By default the value of this is set to false.

Parameters:
whitespace - true if the parser created must eliminate whitespace in the element content when parsing XML documents; false otherwise.

setExpandEntityReferences

public void setExpandEntityReferences(boolean expandEntityRef)
Specifies that the parser produced by this code will expand entity reference nodes. By default the value of this is set to true

Parameters:
expandEntityRef - true if the parser produced will expand entity reference nodes; false otherwise.

setIgnoringComments

public void setIgnoringComments(boolean ignoreComments)

Specifies that the parser produced by this code will ignore comments. By default the value of this is set to false .

Parameters:
ignoreComments - boolean value to ignore comments during processing

setCoalescing

public void setCoalescing(boolean coalescing)
Specifies that the parser produced by this code will convert CDATA nodes to Text nodes and append it to the adjacent (if any) text node. By default the value of this is set to false

Parameters:
coalescing - true if the parser produced will convert CDATA nodes to Text nodes and append it to the adjacent (if any) text node; false otherwise.

isNamespaceAware

public boolean isNamespaceAware()
Indicates whether or not the factory is configured to produce parsers which are namespace aware.

Returns:
true if the factory is configured to produce parsers which are namespace aware; false otherwise.

isValidating

public boolean isValidating()
Indicates whether or not the factory is configured to produce parsers which validate the XML content during parse.

Returns:
true if the factory is configured to produce parsers which validate the XML content during parse; false otherwise.

isIgnoringElementContentWhitespace

public boolean isIgnoringElementContentWhitespace()
Indicates whether or not the factory is configured to produce parsers which ignore ignorable whitespace in element content.

Returns:
true if the factory is configured to produce parsers which ignore ignorable whitespace in element content; false otherwise.

isExpandEntityReferences

public boolean isExpandEntityReferences()
Indicates whether or not the factory is configured to produce parsers which expand entity reference nodes.

Returns:
true if the factory is configured to produce parsers which expand entity reference nodes; false otherwise.

isIgnoringComments

public boolean isIgnoringComments()
Indicates whether or not the factory is configured to produce parsers which ignores comments.

Returns:
true if the factory is configured to produce parsers which ignores comments; false otherwise.

isCoalescing

public boolean isCoalescing()
Indicates whether or not the factory is configured to produce parsers which converts CDATA nodes to Text nodes and appends it to the adjacent (if any) Text node.

Returns:
true if the factory is configured to produce parsers which converts CDATA nodes to Text nodes and appends it to the adjacent (if any) Text node; false otherwise.

setAttribute

public abstract void setAttribute(String name,
                                  Object value)
                           throws IllegalArgumentException
Allows the user to set specific attributes on the underlying implementation.

Parameters:
name - The name of the attribute.
value - The value of the attribute.
Throws:
IllegalArgumentException - thrown if the underlying implementation doesn't recognize the attribute.

getAttribute

public abstract Object getAttribute(String name)
                             throws IllegalArgumentException
Allows the user to retrieve specific attributes on the underlying implementation.

Parameters:
name - The name of the attribute.
Returns:
value The value of the attribute.
Throws:
IllegalArgumentException - thrown if the underlying implementation doesn't recognize the attribute.

setFeature

public abstract void setFeature(String name,
                                boolean value)
                         throws ParserConfigurationException

Set a feature for this DocumentBuilderFactory and DocumentBuilders created by this factory.

Feature names are fully qualified URIs. Implementations may define their own features. A ParserConfigurationException is thrown if this DocumentBuilderFactory or the DocumentBuilders it creates cannot support the feature. It is possible for a DocumentBuilderFactory to expose a feature value but be unable to change its state.

All implementations are required to support the XMLConstants.FEATURE_SECURE_PROCESSING feature. When the feature is:

  • true: the implementation will limit XML processing to conform to implementation limits. Examples include enity expansion limits and XML Schema constructs that would consume large amounts of resources. If XML processing is limited for security reasons, it will be reported via a call to the registered ErrorHandler.fatalError(SAXParseException exception). See DocumentBuilder.setErrorHandler(org.xml.sax.ErrorHandler errorHandler).
  • false: the implementation will processing XML according to the XML specifications without regard to possible implementation limits.

Parameters:
name - Feature name.
value - Is feature state true or false.
Throws:
ParserConfigurationException - if this DocumentBuilderFactory or the DocumentBuilders it creates cannot support this feature.
NullPointerException - If the name parameter is null.

getFeature

public abstract boolean getFeature(String name)
                            throws ParserConfigurationException

Get the state of the named feature.

Feature names are fully qualified URIs. Implementations may define their own features. An ParserConfigurationException is thrown if this DocumentBuilderFactory or the DocumentBuilders it creates cannot support the feature. It is possible for an DocumentBuilderFactory to expose a feature value but be unable to change its state.

Parameters:
name - Feature name.
Returns:
State of the named feature.
Throws:
ParserConfigurationException - if this DocumentBuilderFactory or the DocumentBuilders it creates cannot support this feature.

getSchema

public Schema getSchema()
Gets the Schema object specified through the setSchema(Schema schema) method.

Returns:
the Schema object that was last set through the setSchema(Schema) method, or null if the method was not invoked since a DocumentBuilderFactory is created.
Throws:
UnsupportedOperationException - When implementation does not override this method.
Since:
1.5

setSchema

public void setSchema(Schema schema)

Set the Schema to be used by parsers created from this factory.

When a Schema is non-null, a parser will use a validator created from it to validate documents before it passes information down to the application.

When errors are found by the validator, the parser is responsible to report them to the user-specified ErrorHandler (or if the error handler is not set, ignore them or throw them), just like any other errors found by the parser itself. In other words, if the user-specified ErrorHandler is set, it must receive those errors, and if not, they must be treated according to the implementation specific default error handling rules.

A validator may modify the outcome of a parse (for example by adding default values that were missing in documents), and a parser is responsible to make sure that the application will receive modified DOM trees.

Initialy, null is set as the Schema.

This processing will take effect even if the isValidating() method returns false.

It is an error to use the http://java.sun.com/xml/jaxp/properties/schemaSource property and/or the http://java.sun.com/xml/jaxp/properties/schemaLanguage property in conjunction with a Schema object. Such configuration will cause a ParserConfigurationException exception when the newDocumentBuilder() is invoked.

Note for implmentors

A parser must be able to work with any Schema implementation. However, parsers and schemas are allowed to use implementation-specific custom mechanisms as long as they yield the result described in the specification.

Parameters:
schema - Schema to use or null to remove a schema.
Throws:
UnsupportedOperationException - When implementation does not override this method.
Since:
1.5

setXIncludeAware

public void setXIncludeAware(boolean state)

Set state of XInclude processing.

If XInclude markup is found in the document instance, should it be processed as specified in XML Inclusions (XInclude) Version 1.0.

XInclude processing defaults to false.

Parameters:
state - Set XInclude processing to true or false
Throws:
UnsupportedOperationException - When implementation does not override this method.
Since:
1.5

isXIncludeAware

public boolean isXIncludeAware()

Get state of XInclude processing.

Returns:
current state of XInclude processing
Throws:
UnsupportedOperationException - When implementation does not override this method.
Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FactoryConfigurationError

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.parsers
Class FactoryConfigurationError

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Error
            extended by  javax.xml.parsers.FactoryConfigurationError
All Implemented Interfaces:
Serializable
public class FactoryConfigurationError
extends Error

Thrown when a problem with configuration with the Parser Factories exists. This error will typically be thrown when the class of a parser factory specified in the system properties cannot be found or instantiated.

See Also:
Serialized Form

Constructor Summary
FactoryConfigurationError()
Create a new FactoryConfigurationError with no detail mesage.
FactoryConfigurationError(Exception e)
Create a new FactoryConfigurationError with a given Exception base cause of the error.
FactoryConfigurationError(Exception e, String msg)
Create a new FactoryConfigurationError with the given Exception base cause and detail message.
FactoryConfigurationError(String msg)
Create a new FactoryConfigurationError with the String specified as an error message.
Method Summary
Exception | getException() Return the actual exception (if any) that caused this exception to be raised.
String | getMessage() Return the message (if any) for this error .
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

FactoryConfigurationError

public FactoryConfigurationError()
Create a new FactoryConfigurationError with no detail mesage.

FactoryConfigurationError

public FactoryConfigurationError(String msg)
Create a new FactoryConfigurationError with the String specified as an error message.

Parameters:
msg - The error message for the exception.

FactoryConfigurationError

public FactoryConfigurationError(Exception e)
Create a new FactoryConfigurationError with a given Exception base cause of the error.

Parameters:
e - The exception to be encapsulated in a FactoryConfigurationError.

FactoryConfigurationError

public FactoryConfigurationError(Exception e,
                                 String msg)
Create a new FactoryConfigurationError with the given Exception base cause and detail message.

Parameters:
e - The exception to be encapsulated in a FactoryConfigurationError
msg - The detail message.
Method Detail

getMessage

public String getMessage()
Return the message (if any) for this error . If there is no message for the exception and there is an encapsulated exception then the message of that exception, if it exists will be returned. Else the name of the encapsulated exception will be returned.

Overrides:
getMessage in class Throwable
Returns:
The error message.

getException

public Exception getException()
Return the actual exception (if any) that caused this exception to be raised.

Returns:
The encapsulated exception, or null if there is none.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ParserConfigurationException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.parsers
Class ParserConfigurationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.parsers.ParserConfigurationException
All Implemented Interfaces:
Serializable
public class ParserConfigurationException
extends Exception

Indicates a serious configuration error.

See Also:
Serialized Form

Constructor Summary
ParserConfigurationException()
Create a new ParserConfigurationException with no detail mesage.
ParserConfigurationException(String msg)
Create a new ParserConfigurationException with the String specified as an error message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ParserConfigurationException

public ParserConfigurationException()
Create a new ParserConfigurationException with no detail mesage.

ParserConfigurationException

public ParserConfigurationException(String msg)
Create a new ParserConfigurationException with the String specified as an error message.

Parameters:
msg - The error message for the exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SAXParser

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.parsers
Class SAXParser

java.lang.Object
    extended by  javax.xml.parsers.SAXParser

public abstract class SAXParser
extends Object

Defines the API that wraps an XMLReader implementation class. In JAXP 1.0, this class wrapped the Parser interface, however this interface was replaced by the XMLReader. For ease of transition, this class continues to support the same name and interface as well as supporting new methods. An instance of this class can be obtained from the SAXParserFactory.newSAXParser() method. Once an instance of this class is obtained, XML can be parsed from a variety of input sources. These input sources are InputStreams, Files, URLs, and SAX InputSources.

This static method creates a new factory instance based on a system property setting or uses the platform default if no property has been defined.

The system property that controls which Factory implementation to create is named "javax.xml.parsers.SAXParserFactory". This property names a class that is a concrete subclass of this abstract class. If no property is defined, a platform default will be used.

As the content is parsed by the underlying parser, methods of the given HandlerBase or the DefaultHandler are called.

Implementors of this class which wrap an underlaying implementation can consider using the ParserAdapter class to initially adapt their SAX1 impelemntation to work under this revised class.

Constructor Summary
protected SAXParser()
Protected constructor to prevent instaniation.
Method Summary
abstract Parser | getParser() Returns the SAX parser that is encapsultated by the implementation of this class.
abstract Object | getProperty(String name) Returns the particular property requested for in the underlying implementation of XMLReader.
Schema | getSchema() Get a reference to the the Schema being used by the XML processor.
abstract XMLReader | getXMLReader() Returns the XMLReader that is encapsulated by the implementation of this class.
abstract boolean | isNamespaceAware() Indicates whether or not this parser is configured to understand namespaces.
abstract boolean | isValidating() Indicates whether or not this parser is configured to validate XML documents.
boolean | isXIncludeAware() Get the XInclude processing mode for this parser.
void | parse(File f, DefaultHandler dh) Parse the content of the file specified as XML using the specified DefaultHandler.
void | parse(File f, HandlerBase hb) Parse the content of the file specified as XML using the specified HandlerBase.
void | parse(InputSource is, DefaultHandler dh) Parse the content given InputSource as XML using the specified DefaultHandler.
void | parse(InputSource is, HandlerBase hb) Parse the content given InputSource as XML using the specified HandlerBase.
void | parse(InputStream is, DefaultHandler dh) Parse the content of the given InputStream instance as XML using the specified DefaultHandler.
void | parse(InputStream is, DefaultHandler dh, String systemId) Parse the content of the given InputStream instance as XML using the specified DefaultHandler.
void | parse(InputStream is, HandlerBase hb) Parse the content of the given InputStream instance as XML using the specified HandlerBase.
void | parse(InputStream is, HandlerBase hb, String systemId) Parse the content of the given InputStream instance as XML using the specified HandlerBase.
void | parse(String uri, DefaultHandler dh) Parse the content described by the giving Uniform Resource Identifier (URI) as XML using the specified DefaultHandler.
void | parse(String uri, HandlerBase hb) Parse the content described by the giving Uniform Resource Identifier (URI) as XML using the specified HandlerBase.
void | reset() Reset this SAXParser to its original configuration.
abstract void | setProperty(String name, Object value) Sets the particular property in the underlying implementation of XMLReader.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SAXParser

protected SAXParser()

Protected constructor to prevent instaniation. Use SAXParserFactory.newSAXParser().

Method Detail

reset

public void reset()

Reset this SAXParser to its original configuration.

SAXParser is reset to the same state as when it was created with SAXParserFactory.newSAXParser(). reset() is designed to allow the reuse of existing SAXParsers thus saving resources associated with the creation of new SAXParsers.

The reset SAXParser is not guaranteed to have the same Schema Object, e.g. Object.equals(Object obj). It is guaranteed to have a functionally equal Schema.

Throws:
UnsupportedOperationException - When Implementations do not override this method
Since:
1.5

parse

public void parse(InputStream is,
                  HandlerBase hb)
           throws SAXException,
                  IOException

Parse the content of the given InputStream instance as XML using the specified HandlerBase. Use of the DefaultHandler version of this method is recommended as the HandlerBase class has been deprecated in SAX 2.0.

Parameters:
is - InputStream containing the content to be parsed.
hb - The SAX HandlerBase to use.
Throws:
IllegalArgumentException - If the given InputStream is null.
SAXException - If parse produces a SAX error.
IOException - If an IO error occurs interacting with the InputStream.
See Also:
DocumentHandler

parse

public void parse(InputStream is,
                  HandlerBase hb,
                  String systemId)
           throws SAXException,
                  IOException

Parse the content of the given InputStream instance as XML using the specified HandlerBase. Use of the DefaultHandler version of this method is recommended as the HandlerBase class has been deprecated in SAX 2.0.

Parameters:
is - InputStream containing the content to be parsed.
hb - The SAX HandlerBase to use.
systemId - The systemId which is needed for resolving relative URIs.
Throws:
IllegalArgumentException - If the given InputStream is null.
IOException - If any IO error occurs interacting with the InputStream.
SAXException - If any SAX errors occur during processing.
See Also:
version of this method instead.

parse

public void parse(InputStream is,
                  DefaultHandler dh)
           throws SAXException,
                  IOException
Parse the content of the given InputStream instance as XML using the specified DefaultHandler.

Parameters:
is - InputStream containing the content to be parsed.
dh - The SAX DefaultHandler to use.
Throws:
IllegalArgumentException - If the given InputStream is null.
IOException - If any IO errors occur.
SAXException - If any SAX errors occur during processing.
See Also:
DocumentHandler

parse

public void parse(InputStream is,
                  DefaultHandler dh,
                  String systemId)
           throws SAXException,
                  IOException
Parse the content of the given InputStream instance as XML using the specified DefaultHandler.

Parameters:
is - InputStream containing the content to be parsed.
dh - The SAX DefaultHandler to use.
systemId - The systemId which is needed for resolving relative URIs.
Throws:
IllegalArgumentException - If the given InputStream is null.
IOException - If any IO errors occur.
SAXException - If any SAX errors occur during processing.
See Also:
version of this method instead.

parse

public void parse(String uri,
                  HandlerBase hb)
           throws SAXException,
                  IOException
Parse the content described by the giving Uniform Resource Identifier (URI) as XML using the specified HandlerBase. Use of the DefaultHandler version of this method is recommended as the HandlerBase class has been deprecated in SAX 2.0

Parameters:
uri - The location of the content to be parsed.
hb - The SAX HandlerBase to use.
Throws:
IllegalArgumentException - If the uri is null.
IOException - If any IO errors occur.
SAXException - If any SAX errors occur during processing.
See Also:
DocumentHandler

parse

public void parse(String uri,
                  DefaultHandler dh)
           throws SAXException,
                  IOException
Parse the content described by the giving Uniform Resource Identifier (URI) as XML using the specified DefaultHandler.

Parameters:
uri - The location of the content to be parsed.
dh - The SAX DefaultHandler to use.
Throws:
IllegalArgumentException - If the uri is null.
IOException - If any IO errors occur.
SAXException - If any SAX errors occur during processing.
See Also:
DocumentHandler

parse

public void parse(File f,
                  HandlerBase hb)
           throws SAXException,
                  IOException
Parse the content of the file specified as XML using the specified HandlerBase. Use of the DefaultHandler version of this method is recommended as the HandlerBase class has been deprecated in SAX 2.0

Parameters:
f - The file containing the XML to parse
hb - The SAX HandlerBase to use.
Throws:
IllegalArgumentException - If the File object is null.
IOException - If any IO errors occur.
SAXException - If any SAX errors occur during processing.
See Also:
DocumentHandler

parse

public void parse(File f,
                  DefaultHandler dh)
           throws SAXException,
                  IOException
Parse the content of the file specified as XML using the specified DefaultHandler.

Parameters:
f - The file containing the XML to parse
dh - The SAX DefaultHandler to use.
Throws:
IllegalArgumentException - If the File object is null.
IOException - If any IO errors occur.
SAXException - If any SAX errors occur during processing.
See Also:
DocumentHandler

parse

public void parse(InputSource is,
                  HandlerBase hb)
           throws SAXException,
                  IOException
Parse the content given InputSource as XML using the specified HandlerBase. Use of the DefaultHandler version of this method is recommended as the HandlerBase class has been deprecated in SAX 2.0

Parameters:
is - The InputSource containing the content to be parsed.
hb - The SAX HandlerBase to use.
Throws:
IllegalArgumentException - If the InputSource object is null.
IOException - If any IO errors occur.
SAXException - If any SAX errors occur during processing.
See Also:
DocumentHandler

parse

public void parse(InputSource is,
                  DefaultHandler dh)
           throws SAXException,
                  IOException
Parse the content given InputSource as XML using the specified DefaultHandler.

Parameters:
is - The InputSource containing the content to be parsed.
dh - The SAX DefaultHandler to use.
Throws:
IllegalArgumentException - If the InputSource object is null.
IOException - If any IO errors occur.
SAXException - If any SAX errors occur during processing.
See Also:
DocumentHandler

getParser

public abstract Parser getParser()
                          throws SAXException
Returns the SAX parser that is encapsultated by the implementation of this class.

Returns:
The SAX parser that is encapsultated by the implementation of this class.
Throws:
SAXException - If any SAX errors occur during processing.

getXMLReader

public abstract XMLReader getXMLReader()
                                throws SAXException
Returns the XMLReader that is encapsulated by the implementation of this class.

Returns:
The XMLReader that is encapsulated by the implementation of this class.
Throws:
SAXException - If any SAX errors occur during processing.

isNamespaceAware

public abstract boolean isNamespaceAware()
Indicates whether or not this parser is configured to understand namespaces.

Returns:
true if this parser is configured to understand namespaces; false otherwise.

isValidating

public abstract boolean isValidating()
Indicates whether or not this parser is configured to validate XML documents.

Returns:
true if this parser is configured to validate XML documents; false otherwise.

setProperty

public abstract void setProperty(String name,
                                 Object value)
                          throws SAXNotRecognizedException,
                                 SAXNotSupportedException

Sets the particular property in the underlying implementation of XMLReader. A list of the core features and properties can be found at http://sax.sourceforge.net/?selected=get-set.

Parameters:
name - The name of the property to be set.
value - The value of the property to be set.
Throws:
SAXNotRecognizedException - When the underlying XMLReader does not recognize the property name.
SAXNotSupportedException - When the underlying XMLReader recognizes the property name but doesn't support the property.
See Also:
XMLReader.setProperty(java.lang.String, java.lang.Object)

getProperty

public abstract Object getProperty(String name)
                            throws SAXNotRecognizedException,
                                   SAXNotSupportedException

Returns the particular property requested for in the underlying implementation of XMLReader.

Parameters:
name - The name of the property to be retrieved.
Returns:
Value of the requested property.
Throws:
SAXNotRecognizedException - When the underlying XMLReader does not recognize the property name.
SAXNotSupportedException - When the underlying XMLReader recognizes the property name but doesn't support the property.
See Also:
XMLReader.getProperty(java.lang.String)

getSchema

public Schema getSchema()

Get a reference to the the Schema being used by the XML processor.

If no schema is being used, null is returned.

Returns:
Schema being used or null if none in use
Throws:
UnsupportedOperationException - When implementation does not override this method
Since:
1.5

isXIncludeAware

public boolean isXIncludeAware()

Get the XInclude processing mode for this parser.

Returns:
the return value of the SAXParserFactory.isXIncludeAware() when this parser was created from factory.
Throws:
UnsupportedOperationException - When implementation does not override this method
Since:
1.5
See Also:
SAXParserFactory.setXIncludeAware(boolean)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SAXParserFactory

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.parsers
Class SAXParserFactory

java.lang.Object
    extended by  javax.xml.parsers.SAXParserFactory

public abstract class SAXParserFactory
extends Object

Defines a factory API that enables applications to configure and obtain a SAX based parser to parse XML documents.

Constructor Summary
protected SAXParserFactory()
Protected constructor to force use of newInstance().
Method Summary
abstract boolean | getFeature(String name) Returns the particular property requested for in the underlying implementation of org.xml.sax.XMLReader.
Schema | getSchema() Gets the Schema object specified through the setSchema(Schema schema) method.
boolean | isNamespaceAware() Indicates whether or not the factory is configured to produce parsers which are namespace aware.
boolean | isValidating() Indicates whether or not the factory is configured to produce parsers which validate the XML content during parse.
boolean | isXIncludeAware() Get state of XInclude processing.
static SAXParserFactory | newInstance() Obtain a new instance of a SAXParserFactory.
static SAXParserFactory | newInstance(String factoryClassName, ClassLoader classLoader) Obtain a new instance of a SAXParserFactory from class name.
abstract SAXParser | newSAXParser() Creates a new instance of a SAXParser using the currently configured factory parameters.
abstract void | setFeature(String name, boolean value) Sets the particular feature in the underlying implementation of org.xml.sax.XMLReader.
void | setNamespaceAware(boolean awareness) Specifies that the parser produced by this code will provide support for XML namespaces.
void | setSchema(Schema schema) Set the Schema to be used by parsers created from this factory.
void | setValidating(boolean validating) Specifies that the parser produced by this code will validate documents as they are parsed.
void | setXIncludeAware(boolean state) Set state of XInclude processing.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SAXParserFactory

protected SAXParserFactory()

Protected constructor to force use of newInstance().

Method Detail

newInstance

public static SAXParserFactory newInstance()
Obtain a new instance of a SAXParserFactory. This static method creates a new factory instance This method uses the following ordered lookup procedure to determine the SAXParserFactory implementation class to load:
  • Use the javax.xml.parsers.SAXParserFactory system property.
  • Use the properties file "lib/jaxp.properties" in the JRE directory. This configuration file is in standard java.util.Properties format and contains the fully qualified name of the implementation class with the key being the system property defined above. The jaxp.properties file is read only once by the JAXP implementation and it's values are then cached for future use. If the file does not exist when the first attempt is made to read from it, no further attempts are made to check for its existence. It is not possible to change the value of any property in jaxp.properties after it has been read for the first time.
  • Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for a classname in the file META-INF/services/javax.xml.parsers.SAXParserFactory in jars available to the runtime.
  • Platform default SAXParserFactory instance.
Once an application has obtained a reference to a SAXParserFactory it can use the factory to configure and obtain parser instances.

Tip for Trouble-shooting

Setting the jaxp.debug system property will cause this method to print a lot of debug messages to System.err about what it is doing and where it is looking at.

If you have problems loading DocumentBuilders, try:

 java -Djaxp.debug=1 YourProgram ....

Returns:
A new instance of a SAXParserFactory.
Throws:
FactoryConfigurationError - if the implementation is not available or cannot be instantiated.

newInstance

public static SAXParserFactory newInstance(String factoryClassName,
                                           ClassLoader classLoader)

Obtain a new instance of a SAXParserFactory from class name. This function is useful when there are multiple providers in the classpath. It gives more control to the application as it can specify which provider should be loaded.

Once an application has obtained a reference to a SAXParserFactory it can use the factory to configure and obtain parser instances.

Tip for Trouble-shooting

Setting the jaxp.debug system property will cause this method to print a lot of debug messages to System.err about what it is doing and where it is looking at.

If you have problems, try:

 java -Djaxp.debug=1 YourProgram ....

Parameters:
factoryClassName - fully qualified factory class name that provides implementation of javax.xml.parsers.SAXParserFactory.
classLoader - ClassLoader used to load the factory class. If null current Thread's context classLoader is used to load the factory class.
Returns:
New instance of a SAXParserFactory
Throws:
FactoryConfigurationError - if factoryClassName is null, or the factory class cannot be loaded, instantiated.
Since:
1.6
See Also:
newInstance()

newSAXParser

public abstract SAXParser newSAXParser()
                                throws ParserConfigurationException,
                                       SAXException

Creates a new instance of a SAXParser using the currently configured factory parameters.

Returns:
A new instance of a SAXParser.
Throws:
ParserConfigurationException - if a parser cannot be created which satisfies the requested configuration.
SAXException - for SAX errors.

setNamespaceAware

public void setNamespaceAware(boolean awareness)
Specifies that the parser produced by this code will provide support for XML namespaces. By default the value of this is set to false.

Parameters:
awareness - true if the parser produced by this code will provide support for XML namespaces; false otherwise.

setValidating

public void setValidating(boolean validating)
Specifies that the parser produced by this code will validate documents as they are parsed. By default the value of this is set to false.

Note that "the validation" here means a validating parser as defined in the XML recommendation. In other words, it essentially just controls the DTD validation. (except the legacy two properties defined in JAXP 1.2.)

To use modern schema languages such as W3C XML Schema or RELAX NG instead of DTD, you can configure your parser to be a non-validating parser by leaving the setValidating(boolean) method false, then use the setSchema(Schema) method to associate a schema to a parser.

Parameters:
validating - true if the parser produced by this code will validate documents as they are parsed; false otherwise.

isNamespaceAware

public boolean isNamespaceAware()
Indicates whether or not the factory is configured to produce parsers which are namespace aware.

Returns:
true if the factory is configured to produce parsers which are namespace aware; false otherwise.

isValidating

public boolean isValidating()
Indicates whether or not the factory is configured to produce parsers which validate the XML content during parse.

Returns:
true if the factory is configured to produce parsers which validate the XML content during parse; false otherwise.

setFeature

public abstract void setFeature(String name,
                                boolean value)
                         throws ParserConfigurationException,
                                SAXNotRecognizedException,
                                SAXNotSupportedException

Sets the particular feature in the underlying implementation of org.xml.sax.XMLReader. A list of the core features and properties can be found at http://www.saxproject.org/

All implementations are required to support the XMLConstants.FEATURE_SECURE_PROCESSING feature. When the feature is

  • true: the implementation will limit XML processing to conform to implementation limits. Examples include enity expansion limits and XML Schema constructs that would consume large amounts of resources. If XML processing is limited for security reasons, it will be reported via a call to the registered ErrorHandler.fatalError(SAXParseException exception). See SAXParser parse methods for handler specification.
  • When the feature is false, the implementation will processing XML according to the XML specifications without regard to possible implementation limits.

Parameters:
name - The name of the feature to be set.
value - The value of the feature to be set.
Throws:
ParserConfigurationException - if a parser cannot be created which satisfies the requested configuration.
SAXNotRecognizedException - When the underlying XMLReader does not recognize the property name.
SAXNotSupportedException - When the underlying XMLReader recognizes the property name but doesn't support the property.
NullPointerException - If the name parameter is null.
See Also:
XMLReader.setFeature(java.lang.String, boolean)

getFeature

public abstract boolean getFeature(String name)
                            throws ParserConfigurationException,
                                   SAXNotRecognizedException,
                                   SAXNotSupportedException

Returns the particular property requested for in the underlying implementation of org.xml.sax.XMLReader.

Parameters:
name - The name of the property to be retrieved.
Returns:
Value of the requested property.
Throws:
ParserConfigurationException - if a parser cannot be created which satisfies the requested configuration.
SAXNotRecognizedException - When the underlying XMLReader does not recognize the property name.
SAXNotSupportedException - When the underlying XMLReader recognizes the property name but doesn't support the property.
See Also:
XMLReader.getProperty(java.lang.String)

getSchema

public Schema getSchema()
Gets the Schema object specified through the setSchema(Schema schema) method.

Returns:
the Schema object that was last set through the setSchema(Schema) method, or null if the method was not invoked since a SAXParserFactory is created.
Throws:
UnsupportedOperationException - When implementation does not override this method
Since:
1.5

setSchema

public void setSchema(Schema schema)

Set the Schema to be used by parsers created from this factory.

When a Schema is non-null, a parser will use a validator created from it to validate documents before it passes information down to the application.

When warnings/errors/fatal errors are found by the validator, the parser must handle them as if those errors were found by the parser itself. In other words, if the user-specified ErrorHandler is set, it must receive those errors, and if not, they must be treated according to the implementation specific default error handling rules.

A validator may modify the SAX event stream (for example by adding default values that were missing in documents), and a parser is responsible to make sure that the application will receive those modified event stream.

Initialy, null is set as the Schema.

This processing will take effect even if the isValidating() method returns false.

It is an error to use the http://java.sun.com/xml/jaxp/properties/schemaSource property and/or the http://java.sun.com/xml/jaxp/properties/schemaLanguage property in conjunction with a non-null Schema object. Such configuration will cause a SAXException exception when those properties are set on a SAXParser.

Note for implmentors

A parser must be able to work with any Schema implementation. However, parsers and schemas are allowed to use implementation-specific custom mechanisms as long as they yield the result described in the specification.

Parameters:
schema - Schema to use, null to remove a schema.
Throws:
UnsupportedOperationException - When implementation does not override this method
Since:
1.5

setXIncludeAware

public void setXIncludeAware(boolean state)

Set state of XInclude processing.

If XInclude markup is found in the document instance, should it be processed as specified in XML Inclusions (XInclude) Version 1.0.

XInclude processing defaults to false.

Parameters:
state - Set XInclude processing to true or false
Throws:
UnsupportedOperationException - When implementation does not override this method
Since:
1.5

isXIncludeAware

public boolean isXIncludeAware()

Get state of XInclude processing.

Returns:
current state of XInclude processing
Throws:
UnsupportedOperationException - When implementation does not override this method
Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


soap

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.soap

Provides the API for creating and building SOAP messages.

See:
Description

Interface Summary
Detail | A container for DetailEntry objects.
DetailEntry | The content for a Detail object, giving details for a SOAPFault object.
Name | A representation of an XML name.
Node | A representation of a node (element) in an XML document.
SOAPBody | An object that represents the contents of the SOAP body element in a SOAP message.
SOAPBodyElement | A SOAPBodyElement object represents the contents in a SOAPBody object.
SOAPConstants | The definition of constants pertaining to the SOAP protocol.
SOAPElement | An object representing an element of a SOAP message that is allowed but not specifically prescribed by a SOAP specification.
SOAPEnvelope | The container for the SOAPHeader and SOAPBody portions of a SOAPPart object.
SOAPFault | An element in the SOAPBody object that contains error and/or status information.
SOAPFaultElement | A representation of the contents in a SOAPFault object.
SOAPHeader | A representation of the SOAP header element.
SOAPHeaderElement | An object representing the contents in the SOAP header part of the SOAP envelope.
Text | A representation of a node whose value is text.

Class Summary
AttachmentPart | A single attachment to a SOAPMessage object.
MessageFactory | A factory for creating SOAPMessage objects.
MimeHeader | An object that stores a MIME header name and its value.
MimeHeaders | A container for MimeHeader objects, which represent the MIME headers present in a MIME part of a message.
SAAJMetaFactory | The access point for the implementation classes of the factories defined in the SAAJ API.
SAAJResult | Acts as a holder for the results of a JAXP transformation or a JAXB marshalling, in the form of a SAAJ tree.
SOAPConnection | A point-to-point connection that a client can use for sending messages directly to a remote party (represented by a URL, for instance).
SOAPConnectionFactory | A factory for creating SOAPConnection objects.
SOAPElementFactory | Deprecated. - Use javax.xml.soap.SOAPFactory for creating SOAPElements.
SOAPFactory | SOAPFactory is a factory for creating various objects that exist in the SOAP XML tree.
SOAPMessage | The root class for all SOAP messages.
SOAPPart | The container for the SOAP-specific portion of a SOAPMessage object.

Exception Summary
SOAPException An exception that signals that a SOAP exception has occurred.

Package javax.xml.soap Description

Provides the API for creating and building SOAP messages. This package is defined in the SOAP with Attachments API for JavaTM (SAAJ) 1.3 specification.

The API in the javax.xml.soap package allows you to do the following:

  • create a point-to-point connection to a specified endpoint
  • create a SOAP message
  • create an XML fragment
  • add content to the header of a SOAP message
  • add content to the body of a SOAP message
  • create attachment parts and add content to them
  • access/add/modify parts of a SOAP message
  • create/add/modify SOAP fault information
  • extract content from a SOAP message
  • send a SOAP request-response message

In addition the APIs in the javax.xml.soap package extend their counterparts in the org.w3c.dom package. This means that the SOAPPart of a SOAPMessage is also a DOM Level 2 Document, and can be manipulated as such by applications, tools and libraries that use DOM (see http://www.w3.org/DOM/ for more information). It is important to note that, while it is possible to use DOM APIs to add ordinary DOM nodes to a SAAJ tree, the SAAJ APIs are still required to return SAAJ types when examining or manipulating the tree. In order to accomplish this the SAAJ APIs (specifically SOAPElement.getChildElements()) are allowed to silently replace objects that are incorrectly typed relative to SAAJ requirements with equivalent objects of the required type. These replacements must never cause the logical structure of the tree to change, so from the perspective of the DOM APIs the tree will remain unchanged. However, the physical composition of the tree will have changed so that references to the nodes that were replaced will refer to nodes that are no longer a part of the tree. The SAAJ APIs are not allowed to make these replacements if they are not required so the replacement objects will never subsequently be silently replaced by future calls to the SAAJ API.

What this means in practical terms is that an application that starts to use SAAJ APIs on a tree after manipulating it using DOM APIs must assume that the tree has been translated into an all SAAJ tree and that any references to objects within the tree that were obtained using DOM APIs are no longer valid. Switching from SAAJ APIs to DOM APIs is not allowed to cause invalid references and neither is using SAAJ APIs exclusively. It is only switching from using DOM APIs on a particular SAAJ tree to using SAAJ APIs that causes the risk of invalid references.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


DetailEntry

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Interface DetailEntry

All Superinterfaces:
Element, Node, SOAPElement
public interface DetailEntry
extends SOAPElement

The content for a Detail object, giving details for a SOAPFault object. A DetailEntry object, which carries information about errors related to the SOAPBody object that contains it, is application-specific.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
Methods inherited from interface javax.xml.soap.SOAPElement
addAttribute, addAttribute, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addNamespaceDeclaration, addTextNode, createQName, getAllAttributes, getAllAttributesAsQNames, getAttributeValue, getAttributeValue, getChildElements, getChildElements, getChildElements, getElementName, getElementQName, getEncodingStyle, getNamespacePrefixes, getNamespaceURI, getVisibleNamespacePrefixes, removeAttribute, removeAttribute, removeContents, removeNamespaceDeclaration, setElementQName, setEncodingStyle
Methods inherited from interface javax.xml.soap.Node
detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue
Methods inherited from interface org.w3c.dom.Element
getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


javax.xml.soap Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.soap

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.soap.AttachmentPart
    • javax.xml.transform.dom.DOMResult (implements javax.xml.transform.Result)
      • javax.xml.soap.SAAJResult
    • javax.xml.soap.MessageFactory
    • javax.xml.soap.MimeHeader
    • javax.xml.soap.MimeHeaders
    • javax.xml.soap.SAAJMetaFactory
    • javax.xml.soap.SOAPConnection
    • javax.xml.soap.SOAPConnectionFactory
    • javax.xml.soap.SOAPElementFactory
    • javax.xml.soap.SOAPFactory
    • javax.xml.soap.SOAPMessage
    • javax.xml.soap.SOAPPart (implements org.w3c.dom.Document, javax.xml.soap.Node)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.xml.soap.SOAPException

Interface Hierarchy

  • javax.xml.soap.Name
  • org.w3c.dom.Node
    • org.w3c.dom.CharacterData
      • org.w3c.dom.Text
        • javax.xml.soap.Text (also extends javax.xml.soap.Node)
    • org.w3c.dom.Element
      • javax.xml.soap.SOAPElement (also extends javax.xml.soap.Node)
        • javax.xml.soap.DetailEntry
        • javax.xml.soap.SOAPBody
        • javax.xml.soap.SOAPBodyElement
          • javax.xml.soap.SOAPFault
        • javax.xml.soap.SOAPEnvelope
        • javax.xml.soap.SOAPFaultElement
          • javax.xml.soap.Detail
        • javax.xml.soap.SOAPHeader
        • javax.xml.soap.SOAPHeaderElement
    • javax.xml.soap.Node
      • javax.xml.soap.SOAPElement (also extends org.w3c.dom.Element)
        • javax.xml.soap.DetailEntry
        • javax.xml.soap.SOAPBody
        • javax.xml.soap.SOAPBodyElement
          • javax.xml.soap.SOAPFault
        • javax.xml.soap.SOAPEnvelope
        • javax.xml.soap.SOAPFaultElement
          • javax.xml.soap.Detail
        • javax.xml.soap.SOAPHeader
        • javax.xml.soap.SOAPHeaderElement
      • javax.xml.soap.Text (also extends org.w3c.dom.Text)
  • javax.xml.soap.SOAPConstants
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


SOAPBodyElement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Interface SOAPBodyElement

All Superinterfaces:
Element, Node, SOAPElement
All Known Subinterfaces:
SOAPFault
public interface SOAPBodyElement
extends SOAPElement

A SOAPBodyElement object represents the contents in a SOAPBody object. The SOAPFault interface is a SOAPBodyElement object that has been defined.

A new SOAPBodyElement object can be created and added to a SOAPBody object with the SOAPBody method addBodyElement. In the following line of code, sb is a SOAPBody object, and myName is a Name object.

    SOAPBodyElement sbe = sb.addBodyElement(myName);

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
Methods inherited from interface javax.xml.soap.SOAPElement
addAttribute, addAttribute, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addNamespaceDeclaration, addTextNode, createQName, getAllAttributes, getAllAttributesAsQNames, getAttributeValue, getAttributeValue, getChildElements, getChildElements, getChildElements, getElementName, getElementQName, getEncodingStyle, getNamespacePrefixes, getNamespaceURI, getVisibleNamespacePrefixes, removeAttribute, removeAttribute, removeContents, removeNamespaceDeclaration, setElementQName, setEncodingStyle
Methods inherited from interface javax.xml.soap.Node
detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue
Methods inherited from interface org.w3c.dom.Element
getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SOAPFaultElement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Interface SOAPFaultElement

All Superinterfaces:
Element, Node, SOAPElement
All Known Subinterfaces:
Detail
public interface SOAPFaultElement
extends SOAPElement

A representation of the contents in a SOAPFault object. The Detail interface is a SOAPFaultElement.

Content is added to a SOAPFaultElement using the SOAPElement method addTextNode.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
Methods inherited from interface javax.xml.soap.SOAPElement
addAttribute, addAttribute, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addNamespaceDeclaration, addTextNode, createQName, getAllAttributes, getAllAttributesAsQNames, getAttributeValue, getAttributeValue, getChildElements, getChildElements, getChildElements, getElementName, getElementQName, getEncodingStyle, getNamespacePrefixes, getNamespaceURI, getVisibleNamespacePrefixes, removeAttribute, removeAttribute, removeContents, removeNamespaceDeclaration, setElementQName, setEncodingStyle
Methods inherited from interface javax.xml.soap.Node
detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue
Methods inherited from interface org.w3c.dom.Element
getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Package javax.xml.soap

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.soap

Packages that use javax.xml.soap
javax.xml.soap | Provides the API for creating and building SOAP messages.
javax.xml.ws.handler.soap | This package defines APIs for SOAP message handlers.
javax.xml.ws.soap | This package defines APIs specific to the SOAP binding.

Classes in javax.xml.soap used by javax.xml.soap
AttachmentPart
A single attachment to a SOAPMessage object.
Detail
A container for DetailEntry objects.
DetailEntry
The content for a Detail object, giving details for a SOAPFault object.
MessageFactory
A factory for creating SOAPMessage objects.
MimeHeaders
A container for MimeHeader objects, which represent the MIME headers present in a MIME part of a message.
Name
A representation of an XML name.
Node
A representation of a node (element) in an XML document.
SOAPBody
An object that represents the contents of the SOAP body element in a SOAP message.
SOAPBodyElement
A SOAPBodyElement object represents the contents in a SOAPBody object.
SOAPConnection
A point-to-point connection that a client can use for sending messages directly to a remote party (represented by a URL, for instance).
SOAPConnectionFactory
A factory for creating SOAPConnection objects.
SOAPElement
An object representing an element of a SOAP message that is allowed but not specifically prescribed by a SOAP specification.
SOAPElementFactory
Deprecated. - Use javax.xml.soap.SOAPFactory for creating SOAPElements.
SOAPEnvelope
The container for the SOAPHeader and SOAPBody portions of a SOAPPart object.
SOAPException
An exception that signals that a SOAP exception has occurred.
SOAPFactory
SOAPFactory is a factory for creating various objects that exist in the SOAP XML tree.
SOAPFault
An element in the SOAPBody object that contains error and/or status information.
SOAPFaultElement
A representation of the contents in a SOAPFault object.
SOAPHeader
A representation of the SOAP header element.
SOAPHeaderElement
An object representing the contents in the SOAP header part of the SOAP envelope.
SOAPMessage
The root class for all SOAP messages.
SOAPPart
The container for the SOAP-specific portion of a SOAPMessage object.

Classes in javax.xml.soap used by javax.xml.ws.handler.soap
SOAPMessage
The root class for all SOAP messages.

Classes in javax.xml.soap used by javax.xml.ws.soap
MessageFactory
A factory for creating SOAPMessage objects.
SOAPFactory
SOAPFactory is a factory for creating various objects that exist in the SOAP XML tree.
SOAPFault
An element in the SOAPBody object that contains error and/or status information.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AttachmentPart

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Class AttachmentPart

java.lang.Object
    extended by  javax.xml.soap.AttachmentPart

public abstract class AttachmentPart
extends Object

A single attachment to a SOAPMessage object. A SOAPMessage object may contain zero, one, or many AttachmentPart objects. Each AttachmentPart object consists of two parts, application-specific content and associated MIME headers. The MIME headers consists of name/value pairs that can be used to identify and describe the content.

An AttachmentPart object must conform to certain standards.

  1. It must conform to MIME [RFC2045] standards
  2. It MUST contain content
  3. The header portion MUST include the following header:
    • Content-Type
      This header identifies the type of data in the content of an AttachmentPart object and MUST conform to [RFC2045]. The following is an example of a Content-Type header:
             Content-Type:  application/xml
      The following line of code, in which ap is an AttachmentPart object, sets the header shown in the previous example.
             ap.setMimeHeader("Content-Type", "application/xml");

There are no restrictions on the content portion of an AttachmentPart object. The content may be anything from a simple plain text object to a complex XML document or image file.

An AttachmentPart object is created with the method SOAPMessage.createAttachmentPart. After setting its MIME headers, the AttachmentPart object is added to the message that created it with the method SOAPMessage.addAttachmentPart.

The following code fragment, in which m is a SOAPMessage object and contentStringl is a String, creates an instance of AttachmentPart, sets the AttachmentPart object with some content and header information, and adds the AttachmentPart object to the SOAPMessage object.

     AttachmentPart ap1 = m.createAttachmentPart();
     ap1.setContent(contentString1, "text/plain");
     m.addAttachmentPart(ap1);

The following code fragment creates and adds a second AttachmentPart instance to the same message. jpegData is a binary byte buffer representing the jpeg file.

     AttachmentPart ap2 = m.createAttachmentPart();
     byte[] jpegData =  ...;
     ap2.setContent(new ByteArrayInputStream(jpegData), "image/jpeg");
     m.addAttachmentPart(ap2);

The getContent method retrieves the contents and header from an AttachmentPart object. Depending on the DataContentHandler objects present, the returned Object can either be a typed Java object corresponding to the MIME type or an InputStream object that contains the content as bytes.

     String content1 = ap1.getContent();
     java.io.InputStream content2 = ap2.getContent();
The method clearContent removes all the content from an AttachmentPart object but does not affect its header information.
     ap1.clearContent();

Constructor Summary
AttachmentPart()
Method Summary
abstract void | addMimeHeader(String name, String value) Adds a MIME header with the specified name and value to this AttachmentPart object.
abstract void | clearContent() Clears out the content of this AttachmentPart object.
abstract Iterator | getAllMimeHeaders() Retrieves all the headers for this AttachmentPart object as an iterator over the MimeHeader objects.
abstract InputStream | getBase64Content() Returns an InputStream which can be used to obtain the content of AttachmentPart as Base64 encoded character data, this method would base64 encode the raw bytes of the attachment and return.
abstract Object | getContent() Gets the content of this AttachmentPart object as a Java object.
String | getContentId() Gets the value of the MIME header whose name is "Content-ID".
String | getContentLocation() Gets the value of the MIME header whose name is "Content-Location".
String | getContentType() Gets the value of the MIME header whose name is "Content-Type".
abstract DataHandler | getDataHandler() Gets the DataHandler object for this AttachmentPart object.
abstract Iterator | getMatchingMimeHeaders(String[] names) Retrieves all MimeHeader objects that match a name in the given array.
abstract String[] | getMimeHeader(String name) Gets all the values of the header identified by the given String.
abstract Iterator | getNonMatchingMimeHeaders(String[] names) Retrieves all MimeHeader objects whose name does not match a name in the given array.
abstract InputStream | getRawContent() Gets the content of this AttachmentPart object as an InputStream as if a call had been made to getContent and no DataContentHandler had been registered for the content-type of this AttachmentPart.
abstract byte[] | getRawContentBytes() Gets the content of this AttachmentPart object as a byte[] array as if a call had been made to getContent and no DataContentHandler had been registered for the content-type of this AttachmentPart.
abstract int | getSize() Returns the number of bytes in this AttachmentPart object.
abstract void | removeAllMimeHeaders() Removes all the MIME header entries.
abstract void | removeMimeHeader(String header) Removes all MIME headers that match the given name.
abstract void | setBase64Content(InputStream content, String contentType) Sets the content of this attachment part from the Base64 source InputStream and sets the value of the Content-Type header to the value contained in contentType, This method would first decode the base64 input and write the resulting raw bytes to the attachment.
abstract void | setContent(Object object, String contentType) Sets the content of this attachment part to that of the given Object and sets the value of the Content-Type header to the given type.
void | setContentId(String contentId) Sets the MIME header whose name is "Content-ID" with the given value.
void | setContentLocation(String contentLocation) Sets the MIME header whose name is "Content-Location" with the given value.
void | setContentType(String contentType) Sets the MIME header whose name is "Content-Type" with the given value.
abstract void | setDataHandler(DataHandler dataHandler) Sets the given DataHandler object as the data handler for this AttachmentPart object.
abstract void | setMimeHeader(String name, String value) Changes the first header entry that matches the given name to the given value, adding a new header if no existing header matches.
abstract void | setRawContent(InputStream content, String contentType) Sets the content of this attachment part to that contained by the InputStream content and sets the value of the Content-Type header to the value contained in contentType.
abstract void | setRawContentBytes(byte[] content, int offset, int len, String contentType) Sets the content of this attachment part to that contained by the byte[] array content and sets the value of the Content-Type header to the value contained in contentType.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AttachmentPart

public AttachmentPart()
Method Detail

getSize

public abstract int getSize()
                     throws SOAPException
Returns the number of bytes in this AttachmentPart object.

Returns:
the size of this AttachmentPart object in bytes or -1 if the size cannot be determined
Throws:
SOAPException - if the content of this attachment is corrupted of if there was an exception while trying to determine the size.

clearContent

public abstract void clearContent()
Clears out the content of this AttachmentPart object. The MIME header portion is left untouched.

getContent

public abstract Object getContent()
                           throws SOAPException
Gets the content of this AttachmentPart object as a Java object. The type of the returned Java object depends on (1) the DataContentHandler object that is used to interpret the bytes and (2) the Content-Type given in the header.

For the MIME content types "text/plain", "text/html" and "text/xml", the DataContentHandler object does the conversions to and from the Java types corresponding to the MIME types. For other MIME types,the DataContentHandler object can return an InputStream object that contains the content data as raw bytes.

A SAAJ-compliant implementation must, as a minimum, return a java.lang.String object corresponding to any content stream with a Content-Type value of text/plain, a javax.xml.transform.stream.StreamSource object corresponding to a content stream with a Content-Type value of text/xml, a java.awt.Image object corresponding to a content stream with a Content-Type value of image/gif or image/jpeg. For those content types that an installed DataContentHandler object does not understand, the DataContentHandler object is required to return a java.io.InputStream object with the raw bytes.

Returns:
a Java object with the content of this AttachmentPart object
Throws:
SOAPException - if there is no content set into this AttachmentPart object or if there was a data transformation error

getRawContent

public abstract InputStream getRawContent()
                                   throws SOAPException
Gets the content of this AttachmentPart object as an InputStream as if a call had been made to getContent and no DataContentHandler had been registered for the content-type of this AttachmentPart.

Note that reading from the returned InputStream would result in consuming the data in the stream. It is the responsibility of the caller to reset the InputStream appropriately before calling a Subsequent API. If a copy of the raw attachment content is required then the getRawContentBytes() API should be used instead.

Returns:
an InputStream from which the raw data contained by the AttachmentPart can be accessed.
Throws:
SOAPException - if there is no content set into this AttachmentPart object or if there was a data transformation error.
Since:
SAAJ 1.3
See Also:
getRawContentBytes()

getRawContentBytes

public abstract byte[] getRawContentBytes()
                                   throws SOAPException
Gets the content of this AttachmentPart object as a byte[] array as if a call had been made to getContent and no DataContentHandler had been registered for the content-type of this AttachmentPart.

Returns:
a byte[] array containing the raw data of the AttachmentPart.
Throws:
SOAPException - if there is no content set into this AttachmentPart object or if there was a data transformation error.
Since:
SAAJ 1.3

getBase64Content

public abstract InputStream getBase64Content()
                                      throws SOAPException
Returns an InputStream which can be used to obtain the content of AttachmentPart as Base64 encoded character data, this method would base64 encode the raw bytes of the attachment and return.

Returns:
an InputStream from which the Base64 encoded AttachmentPart can be read.
Throws:
SOAPException - if there is no content set into this AttachmentPart object or if there was a data transformation error.
Since:
SAAJ 1.3

setContent

public abstract void setContent(Object object,
                                String contentType)
Sets the content of this attachment part to that of the given Object and sets the value of the Content-Type header to the given type. The type of the Object should correspond to the value given for the Content-Type. This depends on the particular set of DataContentHandler objects in use.

Parameters:
object - the Java object that makes up the content for this attachment part
contentType - the MIME string that specifies the type of the content
Throws:
IllegalArgumentException - may be thrown if the contentType does not match the type of the content object, or if there was no DataContentHandler object for this content object
See Also:
getContent()

setRawContent

public abstract void setRawContent(InputStream content,
                                   String contentType)
                            throws SOAPException
Sets the content of this attachment part to that contained by the InputStream content and sets the value of the Content-Type header to the value contained in contentType.

A subsequent call to getSize() may not be an exact measure of the content size.

Parameters:
content - the raw data to add to the attachment part
contentType - the value to set into the Content-Type header
Throws:
SOAPException - if an there is an error in setting the content
NullPointerException - if content is null
Since:
SAAJ 1.3

setRawContentBytes

public abstract void setRawContentBytes(byte[] content,
                                        int offset,
                                        int len,
                                        String contentType)
                                 throws SOAPException
Sets the content of this attachment part to that contained by the byte[] array content and sets the value of the Content-Type header to the value contained in contentType.

Parameters:
content - the raw data to add to the attachment part
contentType - the value to set into the Content-Type header
offset - the offset in the byte array of the content
len - the number of bytes that form the content
Throws:
SOAPException - if an there is an error in setting the content or content is null
Since:
SAAJ 1.3

setBase64Content

public abstract void setBase64Content(InputStream content,
                                      String contentType)
                               throws SOAPException
Sets the content of this attachment part from the Base64 source InputStream and sets the value of the Content-Type header to the value contained in contentType, This method would first decode the base64 input and write the resulting raw bytes to the attachment.

A subsequent call to getSize() may not be an exact measure of the content size.

Parameters:
content - the base64 encoded data to add to the attachment part
contentType - the value to set into the Content-Type header
Throws:
SOAPException - if an there is an error in setting the content
NullPointerException - if content is null
Since:
SAAJ 1.3

getDataHandler

public abstract DataHandler getDataHandler()
                                    throws SOAPException
Gets the DataHandler object for this AttachmentPart object.

Returns:
the DataHandler object associated with this AttachmentPart object
Throws:
SOAPException - if there is no data in this AttachmentPart object

setDataHandler

public abstract void setDataHandler(DataHandler dataHandler)
Sets the given DataHandler object as the data handler for this AttachmentPart object. Typically, on an incoming message, the data handler is automatically set. When a message is being created and populated with content, the setDataHandler method can be used to get data from various data sources into the message.

Parameters:
dataHandler - the DataHandler object to be set
Throws:
IllegalArgumentException - if there was a problem with the specified DataHandler object

getContentId

public String getContentId()
Gets the value of the MIME header whose name is "Content-ID".

Returns:
a String giving the value of the "Content-ID" header or null if there is none
See Also:
setContentId(java.lang.String)

getContentLocation

public String getContentLocation()
Gets the value of the MIME header whose name is "Content-Location".

Returns:
a String giving the value of the "Content-Location" header or null if there is none

getContentType

public String getContentType()
Gets the value of the MIME header whose name is "Content-Type".

Returns:
a String giving the value of the "Content-Type" header or null if there is none

setContentId

public void setContentId(String contentId)
Sets the MIME header whose name is "Content-ID" with the given value.

Parameters:
contentId - a String giving the value of the "Content-ID" header
Throws:
IllegalArgumentException - if there was a problem with the specified contentId value
See Also:
getContentId()

setContentLocation

public void setContentLocation(String contentLocation)
Sets the MIME header whose name is "Content-Location" with the given value.

Parameters:
contentLocation - a String giving the value of the "Content-Location" header
Throws:
IllegalArgumentException - if there was a problem with the specified content location

setContentType

public void setContentType(String contentType)
Sets the MIME header whose name is "Content-Type" with the given value.

Parameters:
contentType - a String giving the value of the "Content-Type" header
Throws:
IllegalArgumentException - if there was a problem with the specified content type

removeMimeHeader

public abstract void removeMimeHeader(String header)
Removes all MIME headers that match the given name.

Parameters:
header - the string name of the MIME header/s to be removed

removeAllMimeHeaders

public abstract void removeAllMimeHeaders()
Removes all the MIME header entries.

getMimeHeader

public abstract String[] getMimeHeader(String name)
Gets all the values of the header identified by the given String.

Parameters:
name - the name of the header; example: "Content-Type"
Returns:
a String array giving the value for the specified header
See Also:
setMimeHeader(java.lang.String, java.lang.String)

setMimeHeader

public abstract void setMimeHeader(String name,
                                   String value)
Changes the first header entry that matches the given name to the given value, adding a new header if no existing header matches. This method also removes all matching headers but the first.

Note that RFC822 headers can only contain US-ASCII characters.

Parameters:
name - a String giving the name of the header for which to search
value - a String giving the value to be set for the header whose name matches the given name
Throws:
IllegalArgumentException - if there was a problem with the specified mime header name or value

addMimeHeader

public abstract void addMimeHeader(String name,
                                   String value)
Adds a MIME header with the specified name and value to this AttachmentPart object.

Note that RFC822 headers can contain only US-ASCII characters.

Parameters:
name - a String giving the name of the header to be added
value - a String giving the value of the header to be added
Throws:
IllegalArgumentException - if there was a problem with the specified mime header name or value

getAllMimeHeaders

public abstract Iterator getAllMimeHeaders()
Retrieves all the headers for this AttachmentPart object as an iterator over the MimeHeader objects.

Returns:
an Iterator object with all of the Mime headers for this AttachmentPart object

getMatchingMimeHeaders

public abstract Iterator getMatchingMimeHeaders(String[] names)
Retrieves all MimeHeader objects that match a name in the given array.

Parameters:
names - a String array with the name(s) of the MIME headers to be returned
Returns:
all of the MIME headers that match one of the names in the given array as an Iterator object

getNonMatchingMimeHeaders

public abstract Iterator getNonMatchingMimeHeaders(String[] names)
Retrieves all MimeHeader objects whose name does not match a name in the given array.

Parameters:
names - a String array with the name(s) of the MIME headers not to be returned
Returns:
all of the MIME headers in this AttachmentPart object except those that match one of the names in the given array. The nonmatching MIME headers are returned as an Iterator object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class javax.xml.soap.AttachmentPart

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.soap.AttachmentPart

Packages that use AttachmentPart
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of AttachmentPart in javax.xml.soap

Methods in javax.xml.soap that return AttachmentPart
abstract AttachmentPart | SOAPMessage.createAttachmentPart() Creates a new empty AttachmentPart object.
AttachmentPart | SOAPMessage.createAttachmentPart(DataHandler dataHandler) Creates an AttachmentPart object and populates it using the given DataHandler object.
AttachmentPart | SOAPMessage.createAttachmentPart(Object content, String contentType) Creates an AttachmentPart object and populates it with the specified data of the specified content type.
abstract AttachmentPart | SOAPMessage.getAttachment(SOAPElement element) Returns an AttachmentPart object that is associated with an attachment that is referenced by this SOAPElement or null if no such attachment exists.

Methods in javax.xml.soap with parameters of type AttachmentPart
abstract  void SOAPMessage.addAttachmentPart(AttachmentPart AttachmentPart)
Adds the given AttachmentPart object to this SOAPMessage object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.soap.MessageFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.soap.MessageFactory

Packages that use MessageFactory
javax.xml.soap | Provides the API for creating and building SOAP messages.
javax.xml.ws.soap | This package defines APIs specific to the SOAP binding.

Uses of MessageFactory in javax.xml.soap

Methods in javax.xml.soap that return MessageFactory
static MessageFactory | MessageFactory.newInstance() Creates a new MessageFactory object that is an instance of the default implementation (SOAP 1.1), This method uses the following ordered lookup procedure to determine the MessageFactory implementation class to load: Use the javax.xml.soap.MessageFactory system property.
static MessageFactory | MessageFactory.newInstance(String protocol) Creates a new MessageFactory object that is an instance of the specified implementation.
protected abstract MessageFactory | SAAJMetaFactory.newMessageFactory(String protocol) Creates a MessageFactory object for the given String protocol.

Uses of MessageFactory in javax.xml.ws.soap

Methods in javax.xml.ws.soap that return MessageFactory
 MessageFactory SOAPBinding.getMessageFactory()
Gets the SAAJ MessageFactory instance used by this SOAP binding.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.soap.MimeHeader

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.soap.MimeHeader

No usage of javax.xml.soap.MimeHeader

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.soap.MimeHeaders

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.soap.MimeHeaders

Packages that use MimeHeaders
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of MimeHeaders in javax.xml.soap

Methods in javax.xml.soap that return MimeHeaders
abstract  MimeHeaders SOAPMessage.getMimeHeaders()
Returns all the transport-specific MIME headers for this SOAPMessage object in a transport-independent fashion.

Methods in javax.xml.soap with parameters of type MimeHeaders
abstract SOAPMessage | MessageFactory.createMessage(MimeHeaders headers, InputStream in) Internalizes the contents of the given InputStream object into a new SOAPMessage object and returns the SOAPMessage object.
abstract Iterator | SOAPMessage.getAttachments(MimeHeaders headers) Retrieves all the AttachmentPart objects that have header entries that match the specified headers.
abstract void | SOAPMessage.removeAttachments(MimeHeaders headers) Removes all the AttachmentPart objects that have header entries that match the specified headers.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.soap.SAAJMetaFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.soap.SAAJMetaFactory

No usage of javax.xml.soap.SAAJMetaFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.soap.SAAJResult

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.soap.SAAJResult

No usage of javax.xml.soap.SAAJResult

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.soap.SOAPConnection

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.soap.SOAPConnection

Packages that use SOAPConnection
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of SOAPConnection in javax.xml.soap

Methods in javax.xml.soap that return SOAPConnection
abstract  SOAPConnection SOAPConnectionFactory.createConnection()
Create a new SOAPConnection.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.soap.SOAPConnectionFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.soap.SOAPConnectionFactory

Packages that use SOAPConnectionFactory
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of SOAPConnectionFactory in javax.xml.soap

Methods in javax.xml.soap that return SOAPConnectionFactory
static SOAPConnectionFactory SOAPConnectionFactory.newInstance()
Creates an instance of the default SOAPConnectionFactory object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.soap.SOAPElementFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.soap.SOAPElementFactory

Packages that use SOAPElementFactory
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of SOAPElementFactory in javax.xml.soap

Methods in javax.xml.soap that return SOAPElementFactory
static SOAPElementFactory SOAPElementFactory.newInstance()
Deprecated. Creates a new instance of SOAPElementFactory.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.soap.SOAPException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.soap.SOAPException

Packages that use SOAPException
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of SOAPException in javax.xml.soap

Methods in javax.xml.soap that throw SOAPException
 SOAPElement SOAPElement.addAttribute(Name name, String value)
Adds an attribute with the specified name and value to this SOAPElement object.
 SOAPElement SOAPElement.addAttribute(QName qname, String value)
Adds an attribute with the specified name and value to this SOAPElement object.
 SOAPBody SOAPEnvelope.addBody()
Creates a SOAPBody object and sets it as the SOAPBody object for this SOAPEnvelope object.
 SOAPBodyElement SOAPBody.addBodyElement(Name name)
Creates a new SOAPBodyElement object with the specified name and adds it to this SOAPBody object.
 SOAPBodyElement SOAPBody.addBodyElement(QName qname)
Creates a new SOAPBodyElement object with the specified QName and adds it to this SOAPBody object.
 SOAPElement SOAPElement.addChildElement(Name name)
Creates a new SOAPElement object initialized with the given Name object and adds the new element to this SOAPElement object.
 SOAPElement SOAPElement.addChildElement(QName qname)
Creates a new SOAPElement object initialized with the given QName object and adds the new element to this SOAPElement object.
 SOAPElement SOAPElement.addChildElement(SOAPElement element)
Add a SOAPElement as a child of this SOAPElement instance.
 SOAPElement SOAPElement.addChildElement(String localName)
Creates a new SOAPElement object initialized with the specified local name and adds the new element to this SOAPElement object.
 SOAPElement SOAPElement.addChildElement(String localName, String prefix)
Creates a new SOAPElement object initialized with the specified local name and prefix and adds the new element to this SOAPElement object.
 SOAPElement SOAPElement.addChildElement(String localName, String prefix, String uri)
Creates a new SOAPElement object initialized with the specified local name, prefix, and URI and adds the new element to this SOAPElement object.
 Detail SOAPFault.addDetail()
Creates an optional Detail object and sets it as the Detail object for this SOAPFault object.
 DetailEntry Detail.addDetailEntry(Name name)
Creates a new DetailEntry object with the given name and adds it to this Detail object.
 DetailEntry Detail.addDetailEntry(QName qname)
Creates a new DetailEntry object with the given QName and adds it to this Detail object.
 SOAPBodyElement SOAPBody.addDocument(Document document)
Adds the root node of the DOM Document to this SOAPBody object.
 SOAPFault SOAPBody.addFault()
Creates a new SOAPFault object and adds it to this SOAPBody object.
 SOAPFault SOAPBody.addFault(Name faultCode, String faultString)
Creates a new SOAPFault object and adds it to this SOAPBody object.
 SOAPFault SOAPBody.addFault(Name faultCode, String faultString, Locale locale)
Creates a new SOAPFault object and adds it to this SOAPBody object.
 SOAPFault SOAPBody.addFault(QName faultCode, String faultString)
Creates a new SOAPFault object and adds it to this SOAPBody object.
 SOAPFault SOAPBody.addFault(QName faultCode, String faultString, Locale locale)
Creates a new SOAPFault object and adds it to this SOAPBody object.
 void SOAPFault.addFaultReasonText(String text, Locale locale)
Appends or replaces a Reason Text item containing the specified text message and an xml:lang derived from locale.
 SOAPHeader SOAPEnvelope.addHeader()
Creates a SOAPHeader object and sets it as the SOAPHeader object for this SOAPEnvelope object.
 SOAPHeaderElement SOAPHeader.addHeaderElement(Name name)
Creates a new SOAPHeaderElement object initialized with the specified name and adds it to this SOAPHeader object.
 SOAPHeaderElement SOAPHeader.addHeaderElement(QName qname)
Creates a new SOAPHeaderElement object initialized with the specified qname and adds it to this SOAPHeader object.
 SOAPElement SOAPElement.addNamespaceDeclaration(String prefix, String uri)
Adds a namespace declaration with the specified prefix and URI to this SOAPElement object.
 SOAPHeaderElement SOAPHeader.addNotUnderstoodHeaderElement(QName name)
Creates a new NotUnderstood SOAPHeaderElement object initialized with the specified name and adds it to this SOAPHeader object.
 SOAPElement SOAPElement.addTextNode(String text)
Creates a new Text object initialized with the given String and adds it to this SOAPElement object.
 SOAPHeaderElement SOAPHeader.addUpgradeHeaderElement(Iterator supportedSOAPURIs)
Creates a new Upgrade SOAPHeaderElement object initialized with the specified List of supported SOAP URIs and adds it to this SOAPHeader object.
 SOAPHeaderElement SOAPHeader.addUpgradeHeaderElement(String supportedSoapUri)
Creates a new Upgrade SOAPHeaderElement object initialized with the specified supported SOAP URI and adds it to this SOAPHeader object.
 SOAPHeaderElement SOAPHeader.addUpgradeHeaderElement(String[] supportedSoapUris)
Creates a new Upgrade SOAPHeaderElement object initialized with the specified array of supported SOAP URIs and adds it to this SOAPHeader object.
 void SOAPFault.appendFaultSubcode(QName subcode)
Adds a Subcode to the end of the sequence of Subcodes contained by this SOAPFault.
abstract  SOAPMessage SOAPConnection.call(SOAPMessage request, Object to)
Sends the given message to the specified endpoint and blocks until it has returned the response.
abstract  void SOAPConnection.close()
Closes this SOAPConnection object.
 SOAPElement SOAPElementFactory.create(Name name)
Deprecated. Use javax.xml.soap.SOAPFactory.createElement(javax.xml.soap.Name) instead
 SOAPElement SOAPElementFactory.create(String localName)
Deprecated. Use javax.xml.soap.SOAPFactory.createElement(String localName) instead
 SOAPElement SOAPElementFactory.create(String localName, String prefix, String uri)
Deprecated. Use javax.xml.soap.SOAPFactory.createElement(String localName, String prefix, String uri) instead
abstract  SOAPConnection SOAPConnectionFactory.createConnection()
Create a new SOAPConnection.
abstract  Detail SOAPFactory.createDetail()
Creates a new Detail object which serves as a container for DetailEntry objects.
 SOAPElement SOAPFactory.createElement(Element domElement)
Creates a SOAPElement object from an existing DOM Element.
abstract  SOAPElement SOAPFactory.createElement(Name name)
Creates a SOAPElement object initialized with the given Name object.
 SOAPElement SOAPFactory.createElement(QName qname)
Creates a SOAPElement object initialized with the given QName object.
abstract  SOAPElement SOAPFactory.createElement(String localName)
Creates a SOAPElement object initialized with the given local name.
abstract  SOAPElement SOAPFactory.createElement(String localName, String prefix, String uri)
Creates a new SOAPElement object with the given local name, prefix and uri.
abstract  SOAPFault SOAPFactory.createFault()
Creates a new default SOAPFault object
abstract  SOAPFault SOAPFactory.createFault(String reasonText, QName faultCode)
Creates a new SOAPFault object initialized with the given reasonText and faultCode
abstract  SOAPMessage MessageFactory.createMessage()
Creates a new SOAPMessage object with the default SOAPPart, SOAPEnvelope, SOAPBody, and SOAPHeader objects.
abstract  SOAPMessage MessageFactory.createMessage(MimeHeaders headers, InputStream in)
Internalizes the contents of the given InputStream object into a new SOAPMessage object and returns the SOAPMessage object.
abstract  Name SOAPFactory.createName(String localName)
Creates a new Name object initialized with the given local name.
 Name SOAPEnvelope.createName(String localName)
Creates a new Name object initialized with the given local name.
abstract  Name SOAPFactory.createName(String localName, String prefix, String uri)
Creates a new Name object initialized with the given local name, namespace prefix, and namespace URI.
 Name SOAPEnvelope.createName(String localName, String prefix, String uri)
Creates a new Name object initialized with the given local name, namespace prefix, and namespace URI.
 QName SOAPElement.createQName(String localName, String prefix)
Creates a QName whose namespace URI is the one associated with the parameter, prefix, in the context of this SOAPElement.
 Document SOAPBody.extractContentAsDocument()
Creates a new DOM Document and sets the first child of this SOAPBody as it's document element.
 SOAPMessage SOAPConnection.get(Object to)
Gets a message from a specific endpoint and blocks until it receives,
abstract  AttachmentPart SOAPMessage.getAttachment(SOAPElement element)
Returns an AttachmentPart object that is associated with an attachment that is referenced by this SOAPElement or null if no such attachment exists.
abstract  InputStream AttachmentPart.getBase64Content()
Returns an InputStream which can be used to obtain the content of AttachmentPart as Base64 encoded character data, this method would base64 encode the raw bytes of the attachment and return.
 SOAPBody SOAPEnvelope.getBody()
Returns the SOAPBody object associated with this SOAPEnvelope object.
abstract  Source SOAPPart.getContent()
Returns the content of the SOAPEnvelope as a JAXP Source object.
abstract  Object AttachmentPart.getContent()
Gets the content of this AttachmentPart object as a Java object.
abstract  DataHandler AttachmentPart.getDataHandler()
Gets the DataHandler object for this AttachmentPart object.
abstract  SOAPEnvelope SOAPPart.getEnvelope()
Gets the SOAPEnvelope object associated with this SOAPPart object.
 Iterator SOAPFault.getFaultReasonLocales()
Returns an Iterator over a distinct sequence of Locales for which there are associated Reason Text items.
 String SOAPFault.getFaultReasonText(Locale locale)
Returns the Reason Text associated with the given Locale.
 Iterator SOAPFault.getFaultReasonTexts()
Returns an Iterator over a sequence of String objects containing all of the Reason Text items for this SOAPFault.
 SOAPHeader SOAPEnvelope.getHeader()
Returns the SOAPHeader object for this SOAPEnvelope object.
 Object SOAPMessage.getProperty(String property)
Retrieves value of the specified property.
abstract  InputStream AttachmentPart.getRawContent()
Gets the content of this AttachmentPart object as an InputStream as if a call had been made to getContent and no DataContentHandler had been registered for the content-type of this AttachmentPart.
abstract  byte[] AttachmentPart.getRawContentBytes()
Gets the content of this AttachmentPart object as a byte[] array as if a call had been made to getContent and no DataContentHandler had been registered for the content-type of this AttachmentPart.
abstract  int AttachmentPart.getSize()
Returns the number of bytes in this AttachmentPart object.
 SOAPBody SOAPMessage.getSOAPBody()
Gets the SOAP Body contained in this SOAPMessage object.
 SOAPHeader SOAPMessage.getSOAPHeader()
Gets the SOAP Header contained in this SOAPMessage object.
static SOAPElementFactory SOAPElementFactory.newInstance()
Deprecated. Creates a new instance of SOAPElementFactory.
static SOAPConnectionFactory SOAPConnectionFactory.newInstance()
Creates an instance of the default SOAPConnectionFactory object.
static SOAPFactory SOAPFactory.newInstance()
Creates a new SOAPFactory object that is an instance of the default implementation (SOAP 1.1), This method uses the following ordered lookup procedure to determine the SOAPFactory implementation class to load: Use the javax.xml.soap.SOAPFactory system property.
static MessageFactory MessageFactory.newInstance()
Creates a new MessageFactory object that is an instance of the default implementation (SOAP 1.1), This method uses the following ordered lookup procedure to determine the MessageFactory implementation class to load: Use the javax.xml.soap.MessageFactory system property.
static SOAPFactory SOAPFactory.newInstance(String protocol)
Creates a new SOAPFactory object that is an instance of the specified implementation, this method uses the SAAJMetaFactory to locate the implementation class and create the SOAPFactory instance.
static MessageFactory MessageFactory.newInstance(String protocol)
Creates a new MessageFactory object that is an instance of the specified implementation.
protected abstract  MessageFactory SAAJMetaFactory.newMessageFactory(String protocol)
Creates a MessageFactory object for the given String protocol.
protected abstract  SOAPFactory SAAJMetaFactory.newSOAPFactory(String protocol)
Creates a SOAPFactory object for the given String protocol.
abstract  void SOAPMessage.saveChanges()
Updates this SOAPMessage object with all the changes that have been made to it.
abstract  void AttachmentPart.setBase64Content(InputStream content, String contentType)
Sets the content of this attachment part from the Base64 source InputStream and sets the value of the Content-Type header to the value contained in contentType, This method would first decode the base64 input and write the resulting raw bytes to the attachment.
abstract  void SOAPPart.setContent(Source source)
Sets the content of the SOAPEnvelope object with the data from the given Source object.
 SOAPElement SOAPElement.setElementQName(QName newName)
Changes the name of this Element to newName if possible.
 void SOAPElement.setEncodingStyle(String encodingStyle)
Sets the encoding style for this SOAPElement object to one specified.
 void SOAPFault.setFaultActor(String faultActor)
Sets this SOAPFault object with the given fault actor.
 void SOAPFault.setFaultCode(Name faultCodeQName)
Sets this SOAPFault object with the given fault code.
 void SOAPFault.setFaultCode(QName faultCodeQName)
Sets this SOAPFault object with the given fault code.
 void SOAPFault.setFaultCode(String faultCode)
Sets this SOAPFault object with the give fault code.
 void SOAPFault.setFaultNode(String uri)
Creates or replaces any existing Node element value for this SOAPFault object.
 void SOAPFault.setFaultRole(String uri)
Creates or replaces any existing Role element value for this SOAPFault object.
 void SOAPFault.setFaultString(String faultString)
Sets the fault string for this SOAPFault object to the given string.
 void SOAPFault.setFaultString(String faultString, Locale locale)
Sets the fault string for this SOAPFault object to the given string and localized to the given locale.
 void Node.setParentElement(SOAPElement parent)
Sets the parent of this Node object to the given SOAPElement object.
 void SOAPMessage.setProperty(String property, Object value)
Associates the specified value with the specified property.
abstract  void AttachmentPart.setRawContent(InputStream content, String contentType)
Sets the content of this attachment part to that contained by the InputStream content and sets the value of the Content-Type header to the value contained in contentType.
abstract  void AttachmentPart.setRawContentBytes(byte[] content, int offset, int len, String contentType)
Sets the content of this attachment part to that contained by the byte[] array content and sets the value of the Content-Type header to the value contained in contentType.
 void SOAPHeaderElement.setRelay(boolean relay)
Sets the relay attribute for this SOAPHeaderElement to be either true or false.
 void SOAPHeaderElement.setRole(String uri)
Sets the Role associated with this SOAPHeaderElement object to the specified Role.
abstract  void SOAPMessage.writeTo(OutputStream out)
Writes this SOAPMessage object to the given output stream.

Constructors in javax.xml.soap that throw SOAPException
SAAJResult()
Creates a SAAJResult that will present results in the form of a SAAJ tree that supports the default (SOAP 1.1) protocol.
SAAJResult(String protocol)
Creates a SAAJResult that will present results in the form of a SAAJ tree that supports the specified protocol.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.soap.SOAPFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.soap.SOAPFactory

Packages that use SOAPFactory
javax.xml.soap | Provides the API for creating and building SOAP messages.
javax.xml.ws.soap | This package defines APIs specific to the SOAP binding.

Uses of SOAPFactory in javax.xml.soap

Methods in javax.xml.soap that return SOAPFactory
static SOAPFactory | SOAPFactory.newInstance() Creates a new SOAPFactory object that is an instance of the default implementation (SOAP 1.1), This method uses the following ordered lookup procedure to determine the SOAPFactory implementation class to load: Use the javax.xml.soap.SOAPFactory system property.
static SOAPFactory | SOAPFactory.newInstance(String protocol) Creates a new SOAPFactory object that is an instance of the specified implementation, this method uses the SAAJMetaFactory to locate the implementation class and create the SOAPFactory instance.
protected abstract SOAPFactory | SAAJMetaFactory.newSOAPFactory(String protocol) Creates a SOAPFactory object for the given String protocol.

Uses of SOAPFactory in javax.xml.ws.soap

Methods in javax.xml.ws.soap that return SOAPFactory
 SOAPFactory SOAPBinding.getSOAPFactory()
Gets the SAAJ SOAPFactory instance used by this SOAP binding.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.soap.SOAPMessage

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.soap.SOAPMessage

Packages that use SOAPMessage
javax.xml.soap | Provides the API for creating and building SOAP messages.
javax.xml.ws.handler.soap | This package defines APIs for SOAP message handlers.

Uses of SOAPMessage in javax.xml.soap

Methods in javax.xml.soap that return SOAPMessage
abstract SOAPMessage | SOAPConnection.call(SOAPMessage request, Object to) Sends the given message to the specified endpoint and blocks until it has returned the response.
abstract SOAPMessage | MessageFactory.createMessage() Creates a new SOAPMessage object with the default SOAPPart, SOAPEnvelope, SOAPBody, and SOAPHeader objects.
abstract SOAPMessage | MessageFactory.createMessage(MimeHeaders headers, InputStream in) Internalizes the contents of the given InputStream object into a new SOAPMessage object and returns the SOAPMessage object.
SOAPMessage | SOAPConnection.get(Object to) Gets a message from a specific endpoint and blocks until it receives,

Methods in javax.xml.soap with parameters of type SOAPMessage
abstract  SOAPMessage SOAPConnection.call(SOAPMessage request, Object to)
Sends the given message to the specified endpoint and blocks until it has returned the response.

Constructors in javax.xml.soap with parameters of type SOAPMessage
SAAJResult(SOAPMessage message)
Creates a SAAJResult that will write the results into the SOAPPart of the supplied SOAPMessage.

Uses of SOAPMessage in javax.xml.ws.handler.soap

Methods in javax.xml.ws.handler.soap that return SOAPMessage
 SOAPMessage SOAPMessageContext.getMessage()
Gets the SOAPMessage from this message context.

Methods in javax.xml.ws.handler.soap with parameters of type SOAPMessage
 void SOAPMessageContext.setMessage(SOAPMessage message)
Sets the SOAPMessage in this message context

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.soap.SOAPPart

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.soap.SOAPPart

Packages that use SOAPPart
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of SOAPPart in javax.xml.soap

Methods in javax.xml.soap that return SOAPPart
abstract  SOAPPart SOAPMessage.getSOAPPart()
Gets the SOAP part of this SOAPMessage object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.soap.Detail

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.soap.Detail

Packages that use Detail
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of Detail in javax.xml.soap

Methods in javax.xml.soap that return Detail
Detail | SOAPFault.addDetail() Creates an optional Detail object and sets it as the Detail object for this SOAPFault object.
abstract Detail | SOAPFactory.createDetail() Creates a new Detail object which serves as a container for DetailEntry objects.
Detail | SOAPFault.getDetail() Returns the optional detail element for this SOAPFault object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.soap.DetailEntry

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.soap.DetailEntry

Packages that use DetailEntry
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of DetailEntry in javax.xml.soap

Methods in javax.xml.soap that return DetailEntry
DetailEntry | Detail.addDetailEntry(Name name) Creates a new DetailEntry object with the given name and adds it to this Detail object.
DetailEntry | Detail.addDetailEntry(QName qname) Creates a new DetailEntry object with the given QName and adds it to this Detail object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.soap.Name

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.soap.Name

Packages that use Name
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of Name in javax.xml.soap

Methods in javax.xml.soap that return Name
abstract Name | SOAPFactory.createName(String localName) Creates a new Name object initialized with the given local name.
Name | SOAPEnvelope.createName(String localName) Creates a new Name object initialized with the given local name.
abstract Name | SOAPFactory.createName(String localName, String prefix, String uri) Creates a new Name object initialized with the given local name, namespace prefix, and namespace URI.
Name | SOAPEnvelope.createName(String localName, String prefix, String uri) Creates a new Name object initialized with the given local name, namespace prefix, and namespace URI.
Name | SOAPElement.getElementName() Returns the name of this SOAPElement object.
Name | SOAPFault.getFaultCodeAsName() Gets the mandatory SOAP 1.1 fault code for this SOAPFault object as a SAAJ Name object.

Methods in javax.xml.soap with parameters of type Name
 SOAPElement SOAPElement.addAttribute(Name name, String value)
Adds an attribute with the specified name and value to this SOAPElement object.
 SOAPBodyElement SOAPBody.addBodyElement(Name name)
Creates a new SOAPBodyElement object with the specified name and adds it to this SOAPBody object.
 SOAPElement SOAPElement.addChildElement(Name name)
Creates a new SOAPElement object initialized with the given Name object and adds the new element to this SOAPElement object.
 DetailEntry Detail.addDetailEntry(Name name)
Creates a new DetailEntry object with the given name and adds it to this Detail object.
 SOAPFault SOAPBody.addFault(Name faultCode, String faultString)
Creates a new SOAPFault object and adds it to this SOAPBody object.
 SOAPFault SOAPBody.addFault(Name faultCode, String faultString, Locale locale)
Creates a new SOAPFault object and adds it to this SOAPBody object.
 SOAPHeaderElement SOAPHeader.addHeaderElement(Name name)
Creates a new SOAPHeaderElement object initialized with the specified name and adds it to this SOAPHeader object.
 SOAPElement SOAPElementFactory.create(Name name)
Deprecated. Use javax.xml.soap.SOAPFactory.createElement(javax.xml.soap.Name) instead
abstract  SOAPElement SOAPFactory.createElement(Name name)
Creates a SOAPElement object initialized with the given Name object.
 String SOAPElement.getAttributeValue(Name name)
Returns the value of the attribute with the specified name.
 Iterator SOAPElement.getChildElements(Name name)
Returns an Iterator over all the immediate child Nodes of this element with the specified name.
 boolean SOAPElement.removeAttribute(Name name)
Removes the attribute with the specified name.
 void SOAPFault.setFaultCode(Name faultCodeQName)
Sets this SOAPFault object with the given fault code.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.soap.Node

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.soap.Node

Packages that use Node
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of Node in javax.xml.soap

Subinterfaces of Node in javax.xml.soap
interface | Detail A container for DetailEntry objects.
interface | DetailEntry The content for a Detail object, giving details for a SOAPFault object.
interface | SOAPBody An object that represents the contents of the SOAP body element in a SOAP message.
interface | SOAPBodyElement A SOAPBodyElement object represents the contents in a SOAPBody object.
interface | SOAPElement An object representing an element of a SOAP message that is allowed but not specifically prescribed by a SOAP specification.
interface | SOAPEnvelope The container for the SOAPHeader and SOAPBody portions of a SOAPPart object.
interface | SOAPFault An element in the SOAPBody object that contains error and/or status information.
interface | SOAPFaultElement A representation of the contents in a SOAPFault object.
interface | SOAPHeader A representation of the SOAP header element.
interface | SOAPHeaderElement An object representing the contents in the SOAP header part of the SOAP envelope.
interface | Text A representation of a node whose value is text.

Methods in javax.xml.soap that return Node
 Node SAAJResult.getResult()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.soap.SOAPBody

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.soap.SOAPBody

Packages that use SOAPBody
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of SOAPBody in javax.xml.soap

Methods in javax.xml.soap that return SOAPBody
SOAPBody | SOAPEnvelope.addBody() Creates a SOAPBody object and sets it as the SOAPBody object for this SOAPEnvelope object.
SOAPBody | SOAPEnvelope.getBody() Returns the SOAPBody object associated with this SOAPEnvelope object.
SOAPBody | SOAPMessage.getSOAPBody() Gets the SOAP Body contained in this SOAPMessage object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.soap.SOAPBodyElement

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.soap.SOAPBodyElement

Packages that use SOAPBodyElement
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of SOAPBodyElement in javax.xml.soap

Subinterfaces of SOAPBodyElement in javax.xml.soap
 interface SOAPFault
An element in the SOAPBody object that contains error and/or status information.

Methods in javax.xml.soap that return SOAPBodyElement
SOAPBodyElement | SOAPBody.addBodyElement(Name name) Creates a new SOAPBodyElement object with the specified name and adds it to this SOAPBody object.
SOAPBodyElement | SOAPBody.addBodyElement(QName qname) Creates a new SOAPBodyElement object with the specified QName and adds it to this SOAPBody object.
SOAPBodyElement | SOAPBody.addDocument(Document document) Adds the root node of the DOM Document to this SOAPBody object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.soap.SOAPConstants

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.soap.SOAPConstants

No usage of javax.xml.soap.SOAPConstants

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.soap.SOAPElement

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.soap.SOAPElement

Packages that use SOAPElement
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of SOAPElement in javax.xml.soap

Subinterfaces of SOAPElement in javax.xml.soap
interface | Detail A container for DetailEntry objects.
interface | DetailEntry The content for a Detail object, giving details for a SOAPFault object.
interface | SOAPBody An object that represents the contents of the SOAP body element in a SOAP message.
interface | SOAPBodyElement A SOAPBodyElement object represents the contents in a SOAPBody object.
interface | SOAPEnvelope The container for the SOAPHeader and SOAPBody portions of a SOAPPart object.
interface | SOAPFault An element in the SOAPBody object that contains error and/or status information.
interface | SOAPFaultElement A representation of the contents in a SOAPFault object.
interface | SOAPHeader A representation of the SOAP header element.
interface | SOAPHeaderElement An object representing the contents in the SOAP header part of the SOAP envelope.

Methods in javax.xml.soap that return SOAPElement
 SOAPElement SOAPElement.addAttribute(Name name, String value)
Adds an attribute with the specified name and value to this SOAPElement object.
 SOAPElement SOAPElement.addAttribute(QName qname, String value)
Adds an attribute with the specified name and value to this SOAPElement object.
 SOAPElement SOAPElement.addChildElement(Name name)
Creates a new SOAPElement object initialized with the given Name object and adds the new element to this SOAPElement object.
 SOAPElement SOAPElement.addChildElement(QName qname)
Creates a new SOAPElement object initialized with the given QName object and adds the new element to this SOAPElement object.
 SOAPElement SOAPElement.addChildElement(SOAPElement element)
Add a SOAPElement as a child of this SOAPElement instance.
 SOAPElement SOAPElement.addChildElement(String localName)
Creates a new SOAPElement object initialized with the specified local name and adds the new element to this SOAPElement object.
 SOAPElement SOAPElement.addChildElement(String localName, String prefix)
Creates a new SOAPElement object initialized with the specified local name and prefix and adds the new element to this SOAPElement object.
 SOAPElement SOAPElement.addChildElement(String localName, String prefix, String uri)
Creates a new SOAPElement object initialized with the specified local name, prefix, and URI and adds the new element to this SOAPElement object.
 SOAPElement SOAPElement.addNamespaceDeclaration(String prefix, String uri)
Adds a namespace declaration with the specified prefix and URI to this SOAPElement object.
 SOAPElement SOAPElement.addTextNode(String text)
Creates a new Text object initialized with the given String and adds it to this SOAPElement object.
 SOAPElement SOAPElementFactory.create(Name name)
Deprecated. Use javax.xml.soap.SOAPFactory.createElement(javax.xml.soap.Name) instead
 SOAPElement SOAPElementFactory.create(String localName)
Deprecated. Use javax.xml.soap.SOAPFactory.createElement(String localName) instead
 SOAPElement SOAPElementFactory.create(String localName, String prefix, String uri)
Deprecated. Use javax.xml.soap.SOAPFactory.createElement(String localName, String prefix, String uri) instead
 SOAPElement SOAPFactory.createElement(Element domElement)
Creates a SOAPElement object from an existing DOM Element.
abstract  SOAPElement SOAPFactory.createElement(Name name)
Creates a SOAPElement object initialized with the given Name object.
 SOAPElement SOAPFactory.createElement(QName qname)
Creates a SOAPElement object initialized with the given QName object.
abstract  SOAPElement SOAPFactory.createElement(String localName)
Creates a SOAPElement object initialized with the given local name.
abstract  SOAPElement SOAPFactory.createElement(String localName, String prefix, String uri)
Creates a new SOAPElement object with the given local name, prefix and uri.
 SOAPElement Node.getParentElement()
Returns the parent element of this Node object.
 SOAPElement SOAPElement.setElementQName(QName newName)
Changes the name of this Element to newName if possible.

Methods in javax.xml.soap with parameters of type SOAPElement
SOAPElement | SOAPElement.addChildElement(SOAPElement element) Add a SOAPElement as a child of this SOAPElement instance.
abstract AttachmentPart | SOAPMessage.getAttachment(SOAPElement element) Returns an AttachmentPart object that is associated with an attachment that is referenced by this SOAPElement or null if no such attachment exists.
void | Node.setParentElement(SOAPElement parent) Sets the parent of this Node object to the given SOAPElement object.

Constructors in javax.xml.soap with parameters of type SOAPElement
SAAJResult(SOAPElement rootNode)
Creates a SAAJResult that will write the results as a child node of the SOAPElement specified.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.soap.SOAPEnvelope

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.soap.SOAPEnvelope

Packages that use SOAPEnvelope
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of SOAPEnvelope in javax.xml.soap

Methods in javax.xml.soap that return SOAPEnvelope
abstract  SOAPEnvelope SOAPPart.getEnvelope()
Gets the SOAPEnvelope object associated with this SOAPPart object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.soap.SOAPFault

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.soap.SOAPFault

Packages that use SOAPFault
javax.xml.soap | Provides the API for creating and building SOAP messages.
javax.xml.ws.soap | This package defines APIs specific to the SOAP binding.

Uses of SOAPFault in javax.xml.soap

Methods in javax.xml.soap that return SOAPFault
SOAPFault | SOAPBody.addFault() Creates a new SOAPFault object and adds it to this SOAPBody object.
SOAPFault | SOAPBody.addFault(Name faultCode, String faultString) Creates a new SOAPFault object and adds it to this SOAPBody object.
SOAPFault | SOAPBody.addFault(Name faultCode, String faultString, Locale locale) Creates a new SOAPFault object and adds it to this SOAPBody object.
SOAPFault | SOAPBody.addFault(QName faultCode, String faultString) Creates a new SOAPFault object and adds it to this SOAPBody object.
SOAPFault | SOAPBody.addFault(QName faultCode, String faultString, Locale locale) Creates a new SOAPFault object and adds it to this SOAPBody object.
abstract SOAPFault | SOAPFactory.createFault() Creates a new default SOAPFault object
abstract SOAPFault | SOAPFactory.createFault(String reasonText, QName faultCode) Creates a new SOAPFault object initialized with the given reasonText and faultCode
SOAPFault | SOAPBody.getFault() Returns the SOAPFault object in this SOAPBody object.

Uses of SOAPFault in javax.xml.ws.soap

Methods in javax.xml.ws.soap that return SOAPFault
 SOAPFault SOAPFaultException.getFault()
Gets the embedded SOAPFault instance.

Constructors in javax.xml.ws.soap with parameters of type SOAPFault
SOAPFaultException(SOAPFault fault)
Constructor for SOAPFaultException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.soap.SOAPFaultElement

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.soap.SOAPFaultElement

Packages that use SOAPFaultElement
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of SOAPFaultElement in javax.xml.soap

Subinterfaces of SOAPFaultElement in javax.xml.soap
 interface Detail
A container for DetailEntry objects.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.soap.SOAPHeader

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.soap.SOAPHeader

Packages that use SOAPHeader
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of SOAPHeader in javax.xml.soap

Methods in javax.xml.soap that return SOAPHeader
SOAPHeader | SOAPEnvelope.addHeader() Creates a SOAPHeader object and sets it as the SOAPHeader object for this SOAPEnvelope object.
SOAPHeader | SOAPEnvelope.getHeader() Returns the SOAPHeader object for this SOAPEnvelope object.
SOAPHeader | SOAPMessage.getSOAPHeader() Gets the SOAP Header contained in this SOAPMessage object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.soap.SOAPHeaderElement

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.soap.SOAPHeaderElement

Packages that use SOAPHeaderElement
javax.xml.soap Provides the API for creating and building SOAP messages.

Uses of SOAPHeaderElement in javax.xml.soap

Methods in javax.xml.soap that return SOAPHeaderElement
SOAPHeaderElement | SOAPHeader.addHeaderElement(Name name) Creates a new SOAPHeaderElement object initialized with the specified name and adds it to this SOAPHeader object.
SOAPHeaderElement | SOAPHeader.addHeaderElement(QName qname) Creates a new SOAPHeaderElement object initialized with the specified qname and adds it to this SOAPHeader object.
SOAPHeaderElement | SOAPHeader.addNotUnderstoodHeaderElement(QName name) Creates a new NotUnderstood SOAPHeaderElement object initialized with the specified name and adds it to this SOAPHeader object.
SOAPHeaderElement | SOAPHeader.addUpgradeHeaderElement(Iterator supportedSOAPURIs) Creates a new Upgrade SOAPHeaderElement object initialized with the specified List of supported SOAP URIs and adds it to this SOAPHeader object.
SOAPHeaderElement | SOAPHeader.addUpgradeHeaderElement(String supportedSoapUri) Creates a new Upgrade SOAPHeaderElement object initialized with the specified supported SOAP URI and adds it to this SOAPHeader object.
SOAPHeaderElement | SOAPHeader.addUpgradeHeaderElement(String[] supportedSoapUris) Creates a new Upgrade SOAPHeaderElement object initialized with the specified array of supported SOAP URIs and adds it to this SOAPHeader object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.soap.Text

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.soap.Text

No usage of javax.xml.soap.Text

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Detail

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Interface Detail

All Superinterfaces:
Element, Node, SOAPElement, SOAPFaultElement
public interface Detail
extends SOAPFaultElement

A container for DetailEntry objects. DetailEntry objects give detailed error information that is application-specific and related to the SOAPBody object that contains it.

A Detail object, which is part of a SOAPFault object, can be retrieved using the method SOAPFault.getDetail. The Detail interface provides two methods. One creates a new DetailEntry object and also automatically adds it to the Detail object. The second method gets a list of the DetailEntry objects contained in a Detail object.

The following code fragment, in which sf is a SOAPFault object, gets its Detail object (d), adds a new DetailEntry object to d, and then gets a list of all the DetailEntry objects in d. The code also creates a Name object to pass to the method addDetailEntry. The variable se, used to create the Name object, is a SOAPEnvelope object.

    Detail d = sf.getDetail();
    Name name = se.createName("GetLastTradePrice", "WOMBAT",
                                "http://www.wombat.org/trader");
    d.addDetailEntry(name);
    Iterator it = d.getDetailEntries();

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
DetailEntry | addDetailEntry(Name name) Creates a new DetailEntry object with the given name and adds it to this Detail object.
DetailEntry | addDetailEntry(QName qname) Creates a new DetailEntry object with the given QName and adds it to this Detail object.
Iterator | getDetailEntries() Gets an Iterator over all of the DetailEntrys in this Detail object.
Methods inherited from interface javax.xml.soap.SOAPElement
addAttribute, addAttribute, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addNamespaceDeclaration, addTextNode, createQName, getAllAttributes, getAllAttributesAsQNames, getAttributeValue, getAttributeValue, getChildElements, getChildElements, getChildElements, getElementName, getElementQName, getEncodingStyle, getNamespacePrefixes, getNamespaceURI, getVisibleNamespacePrefixes, removeAttribute, removeAttribute, removeContents, removeNamespaceDeclaration, setElementQName, setEncodingStyle
Methods inherited from interface javax.xml.soap.Node
detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue
Methods inherited from interface org.w3c.dom.Element
getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

addDetailEntry

DetailEntry addDetailEntry(Name name)
                           throws SOAPException
Creates a new DetailEntry object with the given name and adds it to this Detail object.

Parameters:
name - a Name object identifying the new DetailEntry object
Throws:
SOAPException - thrown when there is a problem in adding a DetailEntry object to this Detail object.
See Also:
addDetailEntry(QName qname)

addDetailEntry

DetailEntry addDetailEntry(QName qname)
                           throws SOAPException
Creates a new DetailEntry object with the given QName and adds it to this Detail object. This method is the preferred over the one using Name.

Parameters:
qname - a QName object identifying the new DetailEntry object
Throws:
SOAPException - thrown when there is a problem in adding a DetailEntry object to this Detail object.
Since:
SAAJ 1.3
See Also:
addDetailEntry(Name name)

getDetailEntries

Iterator getDetailEntries()
Gets an Iterator over all of the DetailEntrys in this Detail object.

Returns:
an Iterator object over the DetailEntry objects in this Detail object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MessageFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Class MessageFactory

java.lang.Object
    extended by  javax.xml.soap.MessageFactory

public abstract class MessageFactory
extends Object

A factory for creating SOAPMessage objects.

A SAAJ client can create a MessageFactory object using the method newInstance, as shown in the following lines of code.

       MessageFactory mf = MessageFactory.newInstance();
       MessageFactory mf12 = MessageFactory.newInstance(SOAPConstants.SOAP_1_2_PROTOCOL);

All MessageFactory objects, regardless of how they are created, will produce SOAPMessage objects that have the following elements by default:

  • A SOAPPart object
  • A SOAPEnvelope object
  • A SOAPBody object
  • A SOAPHeader object
In some cases, specialized MessageFactory objects may be obtained that produce messages prepopulated with additional entries in the SOAPHeader object and the SOAPBody object. The content of a new SOAPMessage object depends on which of the two MessageFactory methods is used to create it.
  • createMessage()
    This is the method clients would normally use to create a request message.
  • createMessage(MimeHeaders, java.io.InputStream) -- message has content from the InputStream object and headers from the MimeHeaders object
    This method can be used internally by a service implementation to create a message that is a response to a request.

Constructor Summary
MessageFactory()
Method Summary
abstract SOAPMessage | createMessage() Creates a new SOAPMessage object with the default SOAPPart, SOAPEnvelope, SOAPBody, and SOAPHeader objects.
abstract SOAPMessage | createMessage(MimeHeaders headers, InputStream in) Internalizes the contents of the given InputStream object into a new SOAPMessage object and returns the SOAPMessage object.
static MessageFactory | newInstance() Creates a new MessageFactory object that is an instance of the default implementation (SOAP 1.1), This method uses the following ordered lookup procedure to determine the MessageFactory implementation class to load: Use the javax.xml.soap.MessageFactory system property.
static MessageFactory | newInstance(String protocol) Creates a new MessageFactory object that is an instance of the specified implementation.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MessageFactory

public MessageFactory()
Method Detail

newInstance

public static MessageFactory newInstance()
                                  throws SOAPException
Creates a new MessageFactory object that is an instance of the default implementation (SOAP 1.1), This method uses the following ordered lookup procedure to determine the MessageFactory implementation class to load:
  • Use the javax.xml.soap.MessageFactory system property.
  • Use the properties file "lib/jaxm.properties" in the JRE directory. This configuration file is in standard java.util.Properties format and contains the fully qualified name of the implementation class with the key being the system property defined above.
  • Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for a classname in the file META-INF/services/javax.xml.soap.MessageFactory in jars available to the runtime.
  • Use the SAAJMetaFactory instance to locate the MessageFactory implementation class.

Returns:
a new instance of a MessageFactory
Throws:
SOAPException - if there was an error in creating the default implementation of the MessageFactory.
See Also:
SAAJMetaFactory

newInstance

public static MessageFactory newInstance(String protocol)
                                  throws SOAPException
Creates a new MessageFactory object that is an instance of the specified implementation. May be a dynamic message factory, a SOAP 1.1 message factory, or a SOAP 1.2 message factory. A dynamic message factory creates messages based on the MIME headers specified as arguments to the createMessage method. This method uses the SAAJMetaFactory to locate the implementation class and create the MessageFactory instance.

Parameters:
protocol - a string constant representing the class of the specified message factory implementation. May be either DYNAMIC_SOAP_PROTOCOL, DEFAULT_SOAP_PROTOCOL (which is the same as) SOAP_1_1_PROTOCOL, or SOAP_1_2_PROTOCOL.
Returns:
a new instance of a MessageFactory
Throws:
SOAPException - if there was an error in creating the specified implementation of MessageFactory.
Since:
SAAJ 1.3
See Also:
SAAJMetaFactory

createMessage

public abstract SOAPMessage createMessage()
                                   throws SOAPException
Creates a new SOAPMessage object with the default SOAPPart, SOAPEnvelope, SOAPBody, and SOAPHeader objects. Profile-specific message factories can choose to prepopulate the SOAPMessage object with profile-specific headers.

Content can be added to this message's SOAPPart object, and the message can be sent "as is" when a message containing only a SOAP part is sufficient. Otherwise, the SOAPMessage object needs to create one or more AttachmentPart objects and add them to itself. Any content that is not in XML format must be in an AttachmentPart object.

Returns:
a new SOAPMessage object
Throws:
SOAPException - if a SOAP error occurs
UnsupportedOperationException - if the protocol of this MessageFactory instance is DYNAMIC_SOAP_PROTOCOL

createMessage

public abstract SOAPMessage createMessage(MimeHeaders headers,
                                          InputStream in)
                                   throws IOException,
                                          SOAPException
Internalizes the contents of the given InputStream object into a new SOAPMessage object and returns the SOAPMessage object.

Parameters:
in - the InputStream object that contains the data for a message
headers - the transport-specific headers passed to the message in a transport-independent fashion for creation of the message
Returns:
a new SOAPMessage object containing the data from the given InputStream object
Throws:
IOException - if there is a problem in reading data from the input stream
SOAPException - may be thrown if the message is invalid
IllegalArgumentException - if the MessageFactory requires one or more MIME headers to be present in the headers parameter and they are missing. MessageFactory implementations for SOAP_1_1_PROTOCOL or SOAP_1_2_PROTOCOL must not throw IllegalArgumentException for this reason.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MimeHeader

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Class MimeHeader

java.lang.Object
    extended by  javax.xml.soap.MimeHeader

public class MimeHeader
extends Object

An object that stores a MIME header name and its value. One or more MimeHeader objects may be contained in a MimeHeaders object.

See Also:
MimeHeaders

Constructor Summary
MimeHeader(String name, String value)
Constructs a MimeHeader object initialized with the given name and value.
Method Summary
String | getName() Returns the name of this MimeHeader object.
String | getValue() Returns the value of this MimeHeader object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MimeHeader

public MimeHeader(String name,
                  String value)
Constructs a MimeHeader object initialized with the given name and value.

Parameters:
name - a String giving the name of the header
value - a String giving the value of the header
Method Detail

getName

public String getName()
Returns the name of this MimeHeader object.

Returns:
the name of the header as a String

getValue

public String getValue()
Returns the value of this MimeHeader object.

Returns:
the value of the header as a String
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MimeHeaders

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Class MimeHeaders

java.lang.Object
    extended by  javax.xml.soap.MimeHeaders

public class MimeHeaders
extends Object

A container for MimeHeader objects, which represent the MIME headers present in a MIME part of a message.

This class is used primarily when an application wants to retrieve specific attachments based on certain MIME headers and values. This class will most likely be used by implementations of AttachmentPart and other MIME dependent parts of the SAAJ API.

See Also:
SOAPMessage.getAttachments(), AttachmentPart

Constructor Summary
MimeHeaders()
Constructs a default MimeHeaders object initialized with an empty Vector object.
Method Summary
void | addHeader(String name, String value) Adds a MimeHeader object with the specified name and value to this MimeHeaders object's list of headers.
Iterator | getAllHeaders() Returns all the MimeHeaders in this MimeHeaders object.
String[] | getHeader(String name) Returns all of the values for the specified header as an array of String objects.
Iterator | getMatchingHeaders(String[] names) Returns all the MimeHeader objects whose name matches a name in the given array of names.
Iterator | getNonMatchingHeaders(String[] names) Returns all of the MimeHeader objects whose name does not match a name in the given array of names.
void | removeAllHeaders() Removes all the header entries from this MimeHeaders object.
void | removeHeader(String name) Remove all MimeHeader objects whose name matches the given name.
void | setHeader(String name, String value) Replaces the current value of the first header entry whose name matches the given name with the given value, adding a new header if no existing header name matches.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MimeHeaders

public MimeHeaders()
Constructs a default MimeHeaders object initialized with an empty Vector object.

Method Detail

getHeader

public String[] getHeader(String name)
Returns all of the values for the specified header as an array of String objects.

Parameters:
name - the name of the header for which values will be returned
Returns:
a String array with all of the values for the specified header
See Also:
setHeader(java.lang.String, java.lang.String)

setHeader

public void setHeader(String name,
                      String value)
Replaces the current value of the first header entry whose name matches the given name with the given value, adding a new header if no existing header name matches. This method also removes all matching headers after the first one.

Note that RFC822 headers can contain only US-ASCII characters.

Parameters:
name - a String with the name of the header for which to search
value - a String with the value that will replace the current value of the specified header
Throws:
IllegalArgumentException - if there was a problem in the mime header name or the value being set
See Also:
getHeader(java.lang.String)

addHeader

public void addHeader(String name,
                      String value)
Adds a MimeHeader object with the specified name and value to this MimeHeaders object's list of headers.

Note that RFC822 headers can contain only US-ASCII characters.

Parameters:
name - a String with the name of the header to be added
value - a String with the value of the header to be added
Throws:
IllegalArgumentException - if there was a problem in the mime header name or value being added

removeHeader

public void removeHeader(String name)
Remove all MimeHeader objects whose name matches the given name.

Parameters:
name - a String with the name of the header for which to search

removeAllHeaders

public void removeAllHeaders()
Removes all the header entries from this MimeHeaders object.

getAllHeaders

public Iterator getAllHeaders()
Returns all the MimeHeaders in this MimeHeaders object.

Returns:
an Iterator object over this MimeHeaders object's list of MimeHeader objects

getMatchingHeaders

public Iterator getMatchingHeaders(String[] names)
Returns all the MimeHeader objects whose name matches a name in the given array of names.

Parameters:
names - an array of String objects with the names for which to search
Returns:
an Iterator object over the MimeHeader objects whose name matches one of the names in the given list

getNonMatchingHeaders

public Iterator getNonMatchingHeaders(String[] names)
Returns all of the MimeHeader objects whose name does not match a name in the given array of names.

Parameters:
names - an array of String objects with the names for which to search
Returns:
an Iterator object over the MimeHeader objects whose name does not match one of the names in the given list
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Name

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Interface Name

public interface Name

A representation of an XML name. This interface provides methods for getting the local and namespace-qualified names and also for getting the prefix associated with the namespace for the name. It is also possible to get the URI of the namespace.

The following is an example of a namespace declaration in an element.

   <wombat:GetLastTradePrice xmlns:wombat="http://www.wombat.org/trader">
("xmlns" stands for "XML namespace".) The following shows what the methods in the Name interface will return.
  • getQualifiedName will return "prefix:LocalName" = "WOMBAT:GetLastTradePrice"
  • getURI will return "http://www.wombat.org/trader"
  • getLocalName will return "GetLastTracePrice"
  • getPrefix will return "WOMBAT"

XML namespaces are used to disambiguate SOAP identifiers from application-specific identifiers.

Name objects are created using the method SOAPEnvelope.createName, which has two versions. One method creates Name objects with a local name, a namespace prefix, and a namespace URI. and the second creates Name objects with just a local name. The following line of code, in which se is a SOAPEnvelope object, creates a new Name object with all three.

     Name name = se.createName("GetLastTradePrice", "WOMBAT",
                                "http://www.wombat.org/trader");
The following line of code gives an example of how a Name object can be used. The variable element is a SOAPElement object. This code creates a new SOAPElement object with the given name and adds it to element.
     element.addChildElement(name);

The Name interface may be deprecated in a future release of SAAJ in favor of javax.xml.namespace.QName

See Also:
SOAPEnvelope.createName, SOAPFactory.createName

Method Summary
String | getLocalName() Gets the local name part of the XML name that this Name object represents.
String | getPrefix() Returns the prefix that was specified when this Name object was initialized.
String | getQualifiedName() Gets the namespace-qualified name of the XML name that this Name object represents.
String | getURI() Returns the URI of the namespace for the XML name that this Name object represents.

Method Detail

getLocalName

String getLocalName()
Gets the local name part of the XML name that this Name object represents.

Returns:
a string giving the local name

getQualifiedName

String getQualifiedName()
Gets the namespace-qualified name of the XML name that this Name object represents.

Returns:
the namespace-qualified name as a string

getPrefix

String getPrefix()
Returns the prefix that was specified when this Name object was initialized. This prefix is associated with the namespace for the XML name that this Name object represents.

Returns:
the prefix as a string

getURI

String getURI()
Returns the URI of the namespace for the XML name that this Name object represents.

Returns:
the URI as a string
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Node

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Interface Node

All Superinterfaces:
Node
All Known Subinterfaces:
Detail, DetailEntry, SOAPBody, SOAPBodyElement, SOAPElement, SOAPEnvelope, SOAPFault, SOAPFaultElement, SOAPHeader, SOAPHeaderElement, Text
public interface Node
extends Node

A representation of a node (element) in an XML document. This interface extnends the standard DOM Node interface with methods for getting and setting the value of a node, for getting and setting the parent of a node, and for removing a node.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
void | detachNode() Removes this Node object from the tree.
SOAPElement | getParentElement() Returns the parent element of this Node object.
String | getValue() Returns the value of this node if this is a Text node or the value of the immediate child of this node otherwise.
void | recycleNode() Notifies the implementation that this Node object is no longer being used by the application and that the implementation is free to reuse this object for nodes that may be created later.
void | setParentElement(SOAPElement parent) Sets the parent of this Node object to the given SOAPElement object.
void | setValue(String value) If this is a Text node then this method will set its value, otherwise it sets the value of the immediate (Text) child of this node.
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

getValue

String getValue()
Returns the value of this node if this is a Text node or the value of the immediate child of this node otherwise. If there is an immediate child of this Node that it is a Text node then it's value will be returned. If there is more than one Text node then the value of the first Text Node will be returned. Otherwise null is returned.

Returns:
a String with the text of this node if this is a Text node or the text contained by the first immediate child of this Node object that is a Text object if such a child exists; null otherwise.

setValue

void setValue(String value)
If this is a Text node then this method will set its value, otherwise it sets the value of the immediate (Text) child of this node. The value of the immediate child of this node can be set only if, there is one child node and that node is a Text node, or if there are no children in which case a child Text node will be created.

Throws:
IllegalStateException - if the node is not a Text node and either has more than one child node or has a child node that is not a Text node.
Since:
SAAJ 1.2

setParentElement

void setParentElement(SOAPElement parent)
                      throws SOAPException
Sets the parent of this Node object to the given SOAPElement object.

Parameters:
parent - the SOAPElement object to be set as the parent of this Node object
Throws:
SOAPException - if there is a problem in setting the parent to the given element
See Also:
getParentElement()

getParentElement

SOAPElement getParentElement()
Returns the parent element of this Node object. This method can throw an UnsupportedOperationException if the tree is not kept in memory.

Returns:
the SOAPElement object that is the parent of this Node object or null if this Node object is root
Throws:
UnsupportedOperationException - if the whole tree is not kept in memory
See Also:
setParentElement(javax.xml.soap.SOAPElement)

detachNode

void detachNode()
Removes this Node object from the tree.

recycleNode

void recycleNode()
Notifies the implementation that this Node object is no longer being used by the application and that the implementation is free to reuse this object for nodes that may be created later.

Calling the method recycleNode implies that the method detachNode has been called previously.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SAAJMetaFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Class SAAJMetaFactory

java.lang.Object
    extended by  javax.xml.soap.SAAJMetaFactory

public abstract class SAAJMetaFactory
extends Object

The access point for the implementation classes of the factories defined in the SAAJ API. All of the newInstance methods defined on factories in SAAJ 1.3 defer to instances of this class to do the actual object creation. The implementations of newInstance() methods (in SOAPFactory and MessageFactory) that existed in SAAJ 1.2 have been updated to also delegate to the SAAJMetaFactory when the SAAJ 1.2 defined lookup fails to locate the Factory implementation class name.

SAAJMetaFactory is a service provider interface. There are no public methods on this class.

Since:
SAAJ 1.3

Constructor Summary
protected SAAJMetaFactory()
Method Summary
protected abstract MessageFactory | newMessageFactory(String protocol) Creates a MessageFactory object for the given String protocol.
protected abstract SOAPFactory | newSOAPFactory(String protocol) Creates a SOAPFactory object for the given String protocol.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SAAJMetaFactory

protected SAAJMetaFactory()
Method Detail

newMessageFactory

protected abstract MessageFactory newMessageFactory(String protocol)
                                             throws SOAPException
Creates a MessageFactory object for the given String protocol.

Parameters:
protocol - a String indicating the protocol
Throws:
SOAPException - if there is an error in creating the MessageFactory
See Also:
SOAPConstants.SOAP_1_1_PROTOCOL, SOAPConstants.SOAP_1_2_PROTOCOL, SOAPConstants.DYNAMIC_SOAP_PROTOCOL

newSOAPFactory

protected abstract SOAPFactory newSOAPFactory(String protocol)
                                       throws SOAPException
Creates a SOAPFactory object for the given String protocol.

Parameters:
protocol - a String indicating the protocol
Throws:
SOAPException - if there is an error in creating the SOAPFactory
See Also:
SOAPConstants.SOAP_1_1_PROTOCOL, SOAPConstants.SOAP_1_2_PROTOCOL, SOAPConstants.DYNAMIC_SOAP_PROTOCOL
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SAAJResult

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Class SAAJResult

java.lang.Object
    extended by  javax.xml.transform.dom.DOMResult
        extended by  javax.xml.soap.SAAJResult
All Implemented Interfaces:
Result
public class SAAJResult
extends DOMResult

Acts as a holder for the results of a JAXP transformation or a JAXB marshalling, in the form of a SAAJ tree. These results should be accessed by using the getResult() method. The DOMResult.getNode() method should be avoided in almost all cases.

Since:
SAAJ 1.3

Field Summary
Fields inherited from class javax.xml.transform.dom.DOMResult
FEATURE
Fields inherited from interface javax.xml.transform.Result
PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING
Constructor Summary
SAAJResult()
Creates a SAAJResult that will present results in the form of a SAAJ tree that supports the default (SOAP 1.1) protocol.
SAAJResult(SOAPElement rootNode)
Creates a SAAJResult that will write the results as a child node of the SOAPElement specified.
SAAJResult(SOAPMessage message)
Creates a SAAJResult that will write the results into the SOAPPart of the supplied SOAPMessage.
SAAJResult(String protocol)
Creates a SAAJResult that will present results in the form of a SAAJ tree that supports the specified protocol.
Method Summary
 Node getResult()
Methods inherited from class javax.xml.transform.dom.DOMResult
getNextSibling, getNode, getSystemId, setNextSibling, setNode, setSystemId
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SAAJResult

public SAAJResult()
           throws SOAPException
Creates a SAAJResult that will present results in the form of a SAAJ tree that supports the default (SOAP 1.1) protocol.

This kind of SAAJResult is meant for use in situations where the results will be used as a parameter to a method that takes a parameter whose type, such as SOAPElement, is drawn from the SAAJ API. When used in a transformation, the results are populated into the SOAPPart of a SOAPMessage that is created internally. The SOAPPart returned by DOMResult.getNode() is not guaranteed to be well-formed.

Throws:
SOAPException - if there is a problem creating a SOAPMessage
Since:
SAAJ 1.3

SAAJResult

public SAAJResult(String protocol)
           throws SOAPException
Creates a SAAJResult that will present results in the form of a SAAJ tree that supports the specified protocol. The DYNAMIC_SOAP_PROTOCOL is ambiguous in this context and will cause this constructor to throw an UnsupportedOperationException.

This kind of SAAJResult is meant for use in situations where the results will be used as a parameter to a method that takes a parameter whose type, such as SOAPElement, is drawn from the SAAJ API. When used in a transformation the results are populated into the SOAPPart of a SOAPMessage that is created internally. The SOAPPart returned by DOMResult.getNode() is not guaranteed to be well-formed.

Parameters:
protocol - - the name of the SOAP protocol that the resulting SAAJ tree should support
Throws:
SOAPException - if a SOAPMessage supporting the specified protocol cannot be created
Since:
SAAJ 1.3

SAAJResult

public SAAJResult(SOAPMessage message)
Creates a SAAJResult that will write the results into the SOAPPart of the supplied SOAPMessage. In the normal case these results will be written using DOM APIs and, as a result, the finished SOAPPart will not be guaranteed to be well-formed unless the data used to create it is also well formed. When used in a transformation the validity of the SOAPMessage after the transformation can be guaranteed only by means outside SAAJ specification.

Parameters:
message - - the message whose SOAPPart will be populated as a result of some transformation or marshalling operation
Since:
SAAJ 1.3

SAAJResult

public SAAJResult(SOAPElement rootNode)
Creates a SAAJResult that will write the results as a child node of the SOAPElement specified. In the normal case these results will be written using DOM APIs and as a result may invalidate the structure of the SAAJ tree. This kind of SAAJResult should only be used when the validity of the incoming data can be guaranteed by means outside of the SAAJ specification.

Parameters:
rootNode - - the root to which the results will be appended
Since:
SAAJ 1.3
Method Detail

getResult

public Node getResult()
Returns:
the resulting Tree that was created under the specified root Node.
Since:
SAAJ 1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SOAPBody

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Interface SOAPBody

All Superinterfaces:
Element, Node, SOAPElement
public interface SOAPBody
extends SOAPElement

An object that represents the contents of the SOAP body element in a SOAP message. A SOAP body element consists of XML data that affects the way the application-specific content is processed.

A SOAPBody object contains SOAPBodyElement objects, which have the content for the SOAP body. A SOAPFault object, which carries status and/or error information, is an example of a SOAPBodyElement object.

See Also:
SOAPFault

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
SOAPBodyElement | addBodyElement(Name name) Creates a new SOAPBodyElement object with the specified name and adds it to this SOAPBody object.
SOAPBodyElement | addBodyElement(QName qname) Creates a new SOAPBodyElement object with the specified QName and adds it to this SOAPBody object.
SOAPBodyElement | addDocument(Document document) Adds the root node of the DOM Document to this SOAPBody object.
SOAPFault | addFault() Creates a new SOAPFault object and adds it to this SOAPBody object.
SOAPFault | addFault(Name faultCode, String faultString) Creates a new SOAPFault object and adds it to this SOAPBody object.
SOAPFault | addFault(Name faultCode, String faultString, Locale locale) Creates a new SOAPFault object and adds it to this SOAPBody object.
SOAPFault | addFault(QName faultCode, String faultString) Creates a new SOAPFault object and adds it to this SOAPBody object.
SOAPFault | addFault(QName faultCode, String faultString, Locale locale) Creates a new SOAPFault object and adds it to this SOAPBody object.
Document | extractContentAsDocument() Creates a new DOM Document and sets the first child of this SOAPBody as it's document element.
SOAPFault | getFault() Returns the SOAPFault object in this SOAPBody object.
boolean | hasFault() Indicates whether a SOAPFault object exists in this SOAPBody object.
Methods inherited from interface javax.xml.soap.SOAPElement
addAttribute, addAttribute, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addNamespaceDeclaration, addTextNode, createQName, getAllAttributes, getAllAttributesAsQNames, getAttributeValue, getAttributeValue, getChildElements, getChildElements, getChildElements, getElementName, getElementQName, getEncodingStyle, getNamespacePrefixes, getNamespaceURI, getVisibleNamespacePrefixes, removeAttribute, removeAttribute, removeContents, removeNamespaceDeclaration, setElementQName, setEncodingStyle
Methods inherited from interface javax.xml.soap.Node
detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue
Methods inherited from interface org.w3c.dom.Element
getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

addFault

SOAPFault addFault()
                   throws SOAPException
Creates a new SOAPFault object and adds it to this SOAPBody object. The new SOAPFault will have default values set for the mandatory child elements. The type of the SOAPFault will be a SOAP 1.1 or a SOAP 1.2 SOAPFault depending on the protocol specified while creating the MessageFactory instance.

A SOAPBody may contain at most one SOAPFault child element.

Returns:
the new SOAPFault object
Throws:
SOAPException - if there is a SOAP error

addFault

SOAPFault addFault(Name faultCode,
                   String faultString,
                   Locale locale)
                   throws SOAPException
Creates a new SOAPFault object and adds it to this SOAPBody object. The type of the SOAPFault will be a SOAP 1.1 or a SOAP 1.2 SOAPFault depending on the protocol specified while creating the MessageFactory instance.

For SOAP 1.2 the faultCode parameter is the value of the Fault/Code/Value element and the faultString parameter is the value of the Fault/Reason/Text element. For SOAP 1.1 the faultCode parameter is the value of the faultcode element and the faultString parameter is the value of the faultstring element.

A SOAPBody may contain at most one SOAPFault child element.

Parameters:
faultCode - a Name object giving the fault code to be set; must be one of the fault codes defined in the Version of SOAP specification in use
faultString - a String giving an explanation of the fault
locale - a Locale object indicating the native language of the faultString
Returns:
the new SOAPFault object
Throws:
SOAPException - if there is a SOAP error
Since:
SAAJ 1.2
See Also:
SOAPFault.setFaultCode(javax.xml.soap.Name), SOAPFault.setFaultString(java.lang.String)

addFault

SOAPFault addFault(QName faultCode,
                   String faultString,
                   Locale locale)
                   throws SOAPException
Creates a new SOAPFault object and adds it to this SOAPBody object. The type of the SOAPFault will be a SOAP 1.1 or a SOAP 1.2 SOAPFault depending on the protocol specified while creating the MessageFactory instance.

For SOAP 1.2 the faultCode parameter is the value of the Fault/Code/Value element and the faultString parameter is the value of the Fault/Reason/Text element. For SOAP 1.1 the faultCode parameter is the value of the faultcode element and the faultString parameter is the value of the faultstring element.

A SOAPBody may contain at most one SOAPFault child element.

Parameters:
faultCode - a QName object giving the fault code to be set; must be one of the fault codes defined in the version of SOAP specification in use.
faultString - a String giving an explanation of the fault
locale - a Locale object indicating the native language of the faultString
Returns:
the new SOAPFault object
Throws:
SOAPException - if there is a SOAP error
Since:
SAAJ 1.3
See Also:
SOAPFault.setFaultCode(javax.xml.soap.Name),
SOAPFault.setFaultString(java.lang.String),
addFault(Name faultCode, String faultString, Locale locale)

addFault

SOAPFault addFault(Name faultCode,
                   String faultString)
                   throws SOAPException
Creates a new SOAPFault object and adds it to this SOAPBody object. The type of the SOAPFault will be a SOAP 1.1 or a SOAP 1.2 SOAPFault depending on the protocol specified while creating the MessageFactory instance.

For SOAP 1.2 the faultCode parameter is the value of the Fault/Code/Value element and the faultString parameter is the value of the Fault/Reason/Text element. For SOAP 1.1 the faultCode parameter is the value of the faultcode element and the faultString parameter is the value of the faultstring element.

In case of a SOAP 1.2 fault, the default value for the mandatory xml:lang attribute on the Fault/Reason/Text element will be set to java.util.Locale.getDefault()

A SOAPBody may contain at most one SOAPFault child element.

Parameters:
faultCode - a Name object giving the fault code to be set; must be one of the fault codes defined in the version of SOAP specification in use
faultString - a String giving an explanation of the fault
Returns:
the new SOAPFault object
Throws:
SOAPException - if there is a SOAP error
Since:
SAAJ 1.2
See Also:
SOAPFault.setFaultCode(javax.xml.soap.Name), SOAPFault.setFaultString(java.lang.String)

addFault

SOAPFault addFault(QName faultCode,
                   String faultString)
                   throws SOAPException
Creates a new SOAPFault object and adds it to this SOAPBody object. The type of the SOAPFault will be a SOAP 1.1 or a SOAP 1.2 SOAPFault depending on the protocol specified while creating the MessageFactory instance.

For SOAP 1.2 the faultCode parameter is the value of the Fault/Code/Value element and the faultString parameter is the value of the Fault/Reason/Text element. For SOAP 1.1 the faultCode parameter is the value of the faultcode element and the faultString parameter is the value of the faultstring element.

In case of a SOAP 1.2 fault, the default value for the mandatory xml:lang attribute on the Fault/Reason/Text element will be set to java.util.Locale.getDefault()

A SOAPBody may contain at most one SOAPFault child element

Parameters:
faultCode - a QName object giving the fault code to be set; must be one of the fault codes defined in the version of SOAP specification in use
faultString - a String giving an explanation of the fault
Returns:
the new SOAPFault object
Throws:
SOAPException - if there is a SOAP error
Since:
SAAJ 1.3
See Also:
SOAPFault.setFaultCode(javax.xml.soap.Name),
SOAPFault.setFaultString(java.lang.String),
addFault(Name faultCode, String faultString)

hasFault

boolean hasFault()
Indicates whether a SOAPFault object exists in this SOAPBody object.

Returns:
true if a SOAPFault object exists in this SOAPBody object; false otherwise

getFault

SOAPFault getFault()
Returns the SOAPFault object in this SOAPBody object.

Returns:
the SOAPFault object in this SOAPBody object if present, null otherwise.

addBodyElement

SOAPBodyElement addBodyElement(Name name)
                               throws SOAPException
Creates a new SOAPBodyElement object with the specified name and adds it to this SOAPBody object.

Parameters:
name - a Name object with the name for the new SOAPBodyElement object
Returns:
the new SOAPBodyElement object
Throws:
SOAPException - if a SOAP error occurs
See Also:
addBodyElement(javax.xml.namespace.QName)

addBodyElement

SOAPBodyElement addBodyElement(QName qname)
                               throws SOAPException
Creates a new SOAPBodyElement object with the specified QName and adds it to this SOAPBody object.

Parameters:
qname - a QName object with the qname for the new SOAPBodyElement object
Returns:
the new SOAPBodyElement object
Throws:
SOAPException - if a SOAP error occurs
Since:
SAAJ 1.3
See Also:
addBodyElement(Name)

addDocument

SOAPBodyElement addDocument(Document document)
                            throws SOAPException
Adds the root node of the DOM Document to this SOAPBody object.

Calling this method invalidates the document parameter. The client application should discard all references to this Document and its contents upon calling addDocument. The behavior of an application that continues to use such references is undefined.

Parameters:
document - the Document object whose root node will be added to this SOAPBody.
Returns:
the SOAPBodyElement that represents the root node that was added.
Throws:
SOAPException - if the Document cannot be added
Since:
SAAJ 1.2

extractContentAsDocument

Document extractContentAsDocument()
                                  throws SOAPException
Creates a new DOM Document and sets the first child of this SOAPBody as it's document element. The child SOAPElement is removed as part of the process.

Returns:
the Document representation of the SOAPBody content.
Throws:
SOAPException - if there is not exactly one child SOAPElement of the SOAPBody.
Since:
SAAJ 1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SOAPConnection

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Class SOAPConnection

java.lang.Object
    extended by  javax.xml.soap.SOAPConnection

public abstract class SOAPConnection
extends Object

A point-to-point connection that a client can use for sending messages directly to a remote party (represented by a URL, for instance).

The SOAPConnection class is optional. Some implementations may not implement this interface in which case the call to SOAPConnectionFactory.newInstance() (see below) will throw an UnsupportedOperationException.

A client can obtain a SOAPConnection object using a SOAPConnectionFactory object as in the following example:

      SOAPConnectionFactory factory = SOAPConnectionFactory.newInstance();
      SOAPConnection con = factory.createConnection();
A SOAPConnection object can be used to send messages directly to a URL following the request/response paradigm. That is, messages are sent using the method call, which sends the message and then waits until it gets a reply.

Constructor Summary
SOAPConnection()
Method Summary
abstract SOAPMessage | call(SOAPMessage request, Object to) Sends the given message to the specified endpoint and blocks until it has returned the response.
abstract void | close() Closes this SOAPConnection object.
SOAPMessage | get(Object to) Gets a message from a specific endpoint and blocks until it receives,
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SOAPConnection

public SOAPConnection()
Method Detail

call

public abstract SOAPMessage call(SOAPMessage request,
                                 Object to)
                          throws SOAPException
Sends the given message to the specified endpoint and blocks until it has returned the response.

Parameters:
request - the SOAPMessage object to be sent
to - an Object that identifies where the message should be sent. It is required to support Objects of type java.lang.String, java.net.URL, and when JAXM is present javax.xml.messaging.URLEndpoint
Returns:
the SOAPMessage object that is the response to the message that was sent
Throws:
SOAPException - if there is a SOAP error

get

public SOAPMessage get(Object to)
                throws SOAPException
Gets a message from a specific endpoint and blocks until it receives,

Parameters:
to - an Object that identifies where the request should be sent. Objects of type java.lang.String and java.net.URL must be supported.
Returns:
the SOAPMessage object that is the response to the get message request
Throws:
SOAPException - if there is a SOAP error
Since:
SAAJ 1.3

close

public abstract void close()
                    throws SOAPException
Closes this SOAPConnection object.

Throws:
SOAPException - if there is a SOAP error
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SOAPConnectionFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Class SOAPConnectionFactory

java.lang.Object
    extended by  javax.xml.soap.SOAPConnectionFactory

public abstract class SOAPConnectionFactory
extends Object

A factory for creating SOAPConnection objects. Implementation of this class is optional. If SOAPConnectionFactory.newInstance() throws an UnsupportedOperationException then the implementation does not support the SAAJ communication infrastructure. Otherwise SOAPConnection objects can be created by calling createConnection() on the newly created SOAPConnectionFactory object.

Constructor Summary
SOAPConnectionFactory()
Method Summary
abstract SOAPConnection | createConnection() Create a new SOAPConnection.
static SOAPConnectionFactory | newInstance() Creates an instance of the default SOAPConnectionFactory object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SOAPConnectionFactory

public SOAPConnectionFactory()
Method Detail

newInstance

public static SOAPConnectionFactory newInstance()
                                         throws SOAPException,
                                                UnsupportedOperationException
Creates an instance of the default SOAPConnectionFactory object.

Returns:
a new instance of a default SOAPConnectionFactory object
Throws:
SOAPException - if there was an error creating the SOAPConnectionFactory
UnsupportedOperationException - if newInstance is not supported.

createConnection

public abstract SOAPConnection createConnection()
                                         throws SOAPException
Create a new SOAPConnection.

Returns:
the new SOAPConnection object.
Throws:
SOAPException - if there was an exception creating the SOAPConnection object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SOAPConstants

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Interface SOAPConstants

public interface SOAPConstants

The definition of constants pertaining to the SOAP protocol.

Field Summary
static String | DEFAULT_SOAP_PROTOCOL The default protocol: SOAP 1.1 for backwards compatibility.
static String | DYNAMIC_SOAP_PROTOCOL Used to create MessageFactory instances that create SOAPMessages whose concrete type is based on the Content-Type MIME header passed to the createMessage method.
static String | SOAP_1_1_CONTENT_TYPE The media type of the Content-Type MIME header in SOAP 1.1.
static String | SOAP_1_1_PROTOCOL Used to create MessageFactory instances that create SOAPMessages whose behavior supports the SOAP 1.1 specification.
static String | SOAP_1_2_CONTENT_TYPE The media type of the Content-Type MIME header in SOAP 1.2.
static String | SOAP_1_2_PROTOCOL Used to create MessageFactory instances that create SOAPMessages whose behavior supports the SOAP 1.2 specification
static QName | SOAP_DATAENCODINGUNKNOWN_FAULT SOAP 1.2 DataEncodingUnknown Fault
static String | SOAP_ENV_PREFIX The default namespace prefix for http://www.w3.org/2003/05/soap-envelope
static QName | SOAP_MUSTUNDERSTAND_FAULT SOAP 1.2 MustUnderstand Fault
static QName | SOAP_RECEIVER_FAULT SOAP 1.2 Receiver Fault
static QName | SOAP_SENDER_FAULT SOAP 1.2 Sender Fault
static QName | SOAP_VERSIONMISMATCH_FAULT SOAP 1.2 VersionMismatch Fault
static String | URI_NS_SOAP_1_1_ENVELOPE The namespace identifier for the SOAP 1.1 envelope.
static String | URI_NS_SOAP_1_2_ENCODING The namespace identifier for the SOAP 1.2 encoding.
static String | URI_NS_SOAP_1_2_ENVELOPE The namespace identifier for the SOAP 1.2 envelope.
static String | URI_NS_SOAP_ENCODING The namespace identifier for the SOAP 1.1 encoding.
static String | URI_NS_SOAP_ENVELOPE The namespace identifier for the SOAP 1.1 envelope, All SOAPElements in this namespace are defined by the SOAP 1.1 specification.
static String | URI_SOAP_1_2_ROLE_NEXT The URI identifying the next application processing a SOAP request as the intended role for a SOAP 1.2 header entry (see section 2.2 of part 1 of the SOAP 1.2 specification).
static String | URI_SOAP_1_2_ROLE_NONE The URI specifying the role None in SOAP 1.2.
static String | URI_SOAP_1_2_ROLE_ULTIMATE_RECEIVER The URI identifying the ultimate receiver of the SOAP 1.2 message.
static String | URI_SOAP_ACTOR_NEXT The URI identifying the next application processing a SOAP request as the intended actor for a SOAP 1.1 header entry (see section 4.2.2 of the SOAP 1.1 specification).

Field Detail

DYNAMIC_SOAP_PROTOCOL

static final String DYNAMIC_SOAP_PROTOCOL
Used to create MessageFactory instances that create SOAPMessages whose concrete type is based on the Content-Type MIME header passed to the createMessage method. If no Content-Type header is passed then the createMessage may throw an IllegalArgumentException or, in the case of the no argument version of createMessage, an UnsupportedOperationException.

Since:
SAAJ 1.3
See Also:
Constant Field Values

SOAP_1_1_PROTOCOL

static final String SOAP_1_1_PROTOCOL
Used to create MessageFactory instances that create SOAPMessages whose behavior supports the SOAP 1.1 specification.

Since:
SAAJ 1.3
See Also:
Constant Field Values

SOAP_1_2_PROTOCOL

static final String SOAP_1_2_PROTOCOL
Used to create MessageFactory instances that create SOAPMessages whose behavior supports the SOAP 1.2 specification

Since:
SAAJ 1.3
See Also:
Constant Field Values

DEFAULT_SOAP_PROTOCOL

static final String DEFAULT_SOAP_PROTOCOL
The default protocol: SOAP 1.1 for backwards compatibility.

Since:
SAAJ 1.3
See Also:
Constant Field Values

URI_NS_SOAP_1_1_ENVELOPE

static final String URI_NS_SOAP_1_1_ENVELOPE
The namespace identifier for the SOAP 1.1 envelope.

Since:
SAAJ 1.3
See Also:
Constant Field Values

URI_NS_SOAP_1_2_ENVELOPE

static final String URI_NS_SOAP_1_2_ENVELOPE
The namespace identifier for the SOAP 1.2 envelope.

Since:
SAAJ 1.3
See Also:
Constant Field Values

URI_NS_SOAP_ENVELOPE

static final String URI_NS_SOAP_ENVELOPE
The namespace identifier for the SOAP 1.1 envelope, All SOAPElements in this namespace are defined by the SOAP 1.1 specification.

See Also:
Constant Field Values

URI_NS_SOAP_ENCODING

static final String URI_NS_SOAP_ENCODING
The namespace identifier for the SOAP 1.1 encoding. An attribute named encodingStyle in the URI_NS_SOAP_ENVELOPE namespace and set to the value URI_NS_SOAP_ENCODING can be added to an element to indicate that it is encoded using the rules in section 5 of the SOAP 1.1 specification.

See Also:
Constant Field Values

URI_NS_SOAP_1_2_ENCODING

static final String URI_NS_SOAP_1_2_ENCODING
The namespace identifier for the SOAP 1.2 encoding.

Since:
SAAJ 1.3
See Also:
Constant Field Values

SOAP_1_1_CONTENT_TYPE

static final String SOAP_1_1_CONTENT_TYPE
The media type of the Content-Type MIME header in SOAP 1.1.

Since:
SAAJ 1.3
See Also:
Constant Field Values

SOAP_1_2_CONTENT_TYPE

static final String SOAP_1_2_CONTENT_TYPE
The media type of the Content-Type MIME header in SOAP 1.2.

Since:
SAAJ 1.3
See Also:
Constant Field Values

URI_SOAP_ACTOR_NEXT

static final String URI_SOAP_ACTOR_NEXT
The URI identifying the next application processing a SOAP request as the intended actor for a SOAP 1.1 header entry (see section 4.2.2 of the SOAP 1.1 specification).

This value can be passed to
SOAPHeader.examineMustUnderstandHeaderElements(String),
SOAPHeader.examineHeaderElements(String) and
SOAPHeader.extractHeaderElements(String)

See Also:
Constant Field Values

URI_SOAP_1_2_ROLE_NEXT

static final String URI_SOAP_1_2_ROLE_NEXT
The URI identifying the next application processing a SOAP request as the intended role for a SOAP 1.2 header entry (see section 2.2 of part 1 of the SOAP 1.2 specification).

Since:
SAAJ 1.3
See Also:
Constant Field Values

URI_SOAP_1_2_ROLE_NONE

static final String URI_SOAP_1_2_ROLE_NONE
The URI specifying the role None in SOAP 1.2.

Since:
SAAJ 1.3
See Also:
Constant Field Values

URI_SOAP_1_2_ROLE_ULTIMATE_RECEIVER

static final String URI_SOAP_1_2_ROLE_ULTIMATE_RECEIVER
The URI identifying the ultimate receiver of the SOAP 1.2 message.

Since:
SAAJ 1.3
See Also:
Constant Field Values

SOAP_ENV_PREFIX

static final String SOAP_ENV_PREFIX
The default namespace prefix for http://www.w3.org/2003/05/soap-envelope

Since:
SAAJ 1.3
See Also:
Constant Field Values

SOAP_VERSIONMISMATCH_FAULT

static final QName SOAP_VERSIONMISMATCH_FAULT
SOAP 1.2 VersionMismatch Fault

Since:
SAAJ 1.3

SOAP_MUSTUNDERSTAND_FAULT

static final QName SOAP_MUSTUNDERSTAND_FAULT
SOAP 1.2 MustUnderstand Fault

Since:
SAAJ 1.3

SOAP_DATAENCODINGUNKNOWN_FAULT

static final QName SOAP_DATAENCODINGUNKNOWN_FAULT
SOAP 1.2 DataEncodingUnknown Fault

Since:
SAAJ 1.3

SOAP_SENDER_FAULT

static final QName SOAP_SENDER_FAULT
SOAP 1.2 Sender Fault

Since:
SAAJ 1.3

SOAP_RECEIVER_FAULT

static final QName SOAP_RECEIVER_FAULT
SOAP 1.2 Receiver Fault

Since:
SAAJ 1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SOAPElement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Interface SOAPElement

All Superinterfaces:
Element, Node
All Known Subinterfaces:
Detail, DetailEntry, SOAPBody, SOAPBodyElement, SOAPEnvelope, SOAPFault, SOAPFaultElement, SOAPHeader, SOAPHeaderElement
public interface SOAPElement
extends Node, Element

An object representing an element of a SOAP message that is allowed but not specifically prescribed by a SOAP specification. This interface serves as the base interface for those objects that are specifically prescribed by a SOAP specification.

Methods in this interface that are required to return SAAJ specific objects may "silently" replace nodes in the tree as required to successfully return objects of the correct type. See getChildElements() and javax.xml.soap for details.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
SOAPElement | addAttribute(Name name, String value) Adds an attribute with the specified name and value to this SOAPElement object.
SOAPElement | addAttribute(QName qname, String value) Adds an attribute with the specified name and value to this SOAPElement object.
SOAPElement | addChildElement(Name name) Creates a new SOAPElement object initialized with the given Name object and adds the new element to this SOAPElement object.
SOAPElement | addChildElement(QName qname) Creates a new SOAPElement object initialized with the given QName object and adds the new element to this SOAPElement object.
SOAPElement | addChildElement(SOAPElement element) Add a SOAPElement as a child of this SOAPElement instance.
SOAPElement | addChildElement(String localName) Creates a new SOAPElement object initialized with the specified local name and adds the new element to this SOAPElement object.
SOAPElement | addChildElement(String localName, String prefix) Creates a new SOAPElement object initialized with the specified local name and prefix and adds the new element to this SOAPElement object.
SOAPElement | addChildElement(String localName, String prefix, String uri) Creates a new SOAPElement object initialized with the specified local name, prefix, and URI and adds the new element to this SOAPElement object.
SOAPElement | addNamespaceDeclaration(String prefix, String uri) Adds a namespace declaration with the specified prefix and URI to this SOAPElement object.
SOAPElement | addTextNode(String text) Creates a new Text object initialized with the given String and adds it to this SOAPElement object.
QName | createQName(String localName, String prefix) Creates a QName whose namespace URI is the one associated with the parameter, prefix, in the context of this SOAPElement.
Iterator | getAllAttributes() Returns an Iterator over all of the attribute Name objects in this SOAPElement object.
Iterator | getAllAttributesAsQNames() Returns an Iterator over all of the attributes in this SOAPElement as QName objects.
String | getAttributeValue(Name name) Returns the value of the attribute with the specified name.
String | getAttributeValue(QName qname) Returns the value of the attribute with the specified qname.
Iterator | getChildElements() Returns an Iterator over all the immediate child Nodes of this element.
Iterator | getChildElements(Name name) Returns an Iterator over all the immediate child Nodes of this element with the specified name.
Iterator | getChildElements(QName qname) Returns an Iterator over all the immediate child Nodes of this element with the specified qname.
Name | getElementName() Returns the name of this SOAPElement object.
QName | getElementQName() Returns the qname of this SOAPElement object.
String | getEncodingStyle() Returns the encoding style for this SOAPElement object.
Iterator | getNamespacePrefixes() Returns an Iterator over the namespace prefix Strings declared by this element.
String | getNamespaceURI(String prefix) Returns the URI of the namespace that has the given prefix.
Iterator | getVisibleNamespacePrefixes() Returns an Iterator over the namespace prefix Strings visible to this element.
boolean | removeAttribute(Name name) Removes the attribute with the specified name.
boolean | removeAttribute(QName qname) Removes the attribute with the specified qname.
void | removeContents() Detaches all children of this SOAPElement.
boolean | removeNamespaceDeclaration(String prefix) Removes the namespace declaration corresponding to the given prefix.
SOAPElement | setElementQName(QName newName) Changes the name of this Element to newName if possible.
void | setEncodingStyle(String encodingStyle) Sets the encoding style for this SOAPElement object to one specified.
Methods inherited from interface javax.xml.soap.Node
detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue
Methods inherited from interface org.w3c.dom.Element
getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

addChildElement

SOAPElement addChildElement(Name name)
                            throws SOAPException
Creates a new SOAPElement object initialized with the given Name object and adds the new element to this SOAPElement object.

This method may be deprecated in a future release of SAAJ in favor of addChildElement(javax.xml.namespace.QName)

Parameters:
name - a Name object with the XML name for the new element
Returns:
the new SOAPElement object that was created
Throws:
SOAPException - if there is an error in creating the SOAPElement object
See Also:
addChildElement(javax.xml.namespace.QName)

addChildElement

SOAPElement addChildElement(QName qname)
                            throws SOAPException
Creates a new SOAPElement object initialized with the given QName object and adds the new element to this SOAPElement object. The namespace, localname and prefix of the new SOAPElement are all taken from the qname argument.

Parameters:
qname - a QName object with the XML name for the new element
Returns:
the new SOAPElement object that was created
Throws:
SOAPException - if there is an error in creating the SOAPElement object
Since:
SAAJ 1.3
See Also:
addChildElement(Name)

addChildElement

SOAPElement addChildElement(String localName)
                            throws SOAPException
Creates a new SOAPElement object initialized with the specified local name and adds the new element to this SOAPElement object. The new SOAPElement inherits any in-scope default namespace.

Parameters:
localName - a String giving the local name for the element
Returns:
the new SOAPElement object that was created
Throws:
SOAPException - if there is an error in creating the SOAPElement object

addChildElement

SOAPElement addChildElement(String localName,
                            String prefix)
                            throws SOAPException
Creates a new SOAPElement object initialized with the specified local name and prefix and adds the new element to this SOAPElement object.

Parameters:
localName - a String giving the local name for the new element
prefix - a String giving the namespace prefix for the new element
Returns:
the new SOAPElement object that was created
Throws:
SOAPException - if the prefix is not valid in the context of this SOAPElement or if there is an error in creating the SOAPElement object

addChildElement

SOAPElement addChildElement(String localName,
                            String prefix,
                            String uri)
                            throws SOAPException
Creates a new SOAPElement object initialized with the specified local name, prefix, and URI and adds the new element to this SOAPElement object.

Parameters:
localName - a String giving the local name for the new element
prefix - a String giving the namespace prefix for the new element
uri - a String giving the URI of the namespace to which the new element belongs
Returns:
the new SOAPElement object that was created
Throws:
SOAPException - if there is an error in creating the SOAPElement object

addChildElement

SOAPElement addChildElement(SOAPElement element)
                            throws SOAPException
Add a SOAPElement as a child of this SOAPElement instance. The SOAPElement is expected to be created by a SOAPFactory. Callers should not rely on the element instance being added as is into the XML tree. Implementations could end up copying the content of the SOAPElement passed into an instance of a different SOAPElement implementation. For instance if addChildElement() is called on a SOAPHeader, element will be copied into an instance of a SOAPHeaderElement.

The fragment rooted in element is either added as a whole or not at all, if there was an error.

The fragment rooted in element cannot contain elements named "Envelope", "Header" or "Body" and in the SOAP namespace. Any namespace prefixes present in the fragment should be fully resolved using appropriate namespace declarations within the fragment itself.

Parameters:
element - the SOAPElement to be added as a new child
Returns:
an instance representing the new SOAP element that was actually added to the tree.
Throws:
SOAPException - if there was an error in adding this element as a child

removeContents

void removeContents()
Detaches all children of this SOAPElement.

This method is useful for rolling back the construction of partially completed SOAPHeaders and SOAPBodys in preparation for sending a fault when an error condition is detected. It is also useful for recycling portions of a document within a SOAP message.

Since:
SAAJ 1.2

addTextNode

SOAPElement addTextNode(String text)
                        throws SOAPException
Creates a new Text object initialized with the given String and adds it to this SOAPElement object.

Parameters:
text - a String object with the textual content to be added
Returns:
the SOAPElement object into which the new Text object was inserted
Throws:
SOAPException - if there is an error in creating the new Text object or if it is not legal to attach it as a child to this SOAPElement

addAttribute

SOAPElement addAttribute(Name name,
                         String value)
                         throws SOAPException
Adds an attribute with the specified name and value to this SOAPElement object.

Parameters:
name - a Name object with the name of the attribute
value - a String giving the value of the attribute
Returns:
the SOAPElement object into which the attribute was inserted
Throws:
SOAPException - if there is an error in creating the Attribute, or it is invalid to set an attribute with Name name on this SOAPElement.
See Also:
addAttribute(javax.xml.namespace.QName, String)

addAttribute

SOAPElement addAttribute(QName qname,
                         String value)
                         throws SOAPException
Adds an attribute with the specified name and value to this SOAPElement object.

Parameters:
qname - a QName object with the name of the attribute
value - a String giving the value of the attribute
Returns:
the SOAPElement object into which the attribute was inserted
Throws:
SOAPException - if there is an error in creating the Attribute, or it is invalid to set an attribute with QName qname on this SOAPElement.
Since:
SAAJ 1.3
See Also:
addAttribute(Name, String)

addNamespaceDeclaration

SOAPElement addNamespaceDeclaration(String prefix,
                                    String uri)
                                    throws SOAPException
Adds a namespace declaration with the specified prefix and URI to this SOAPElement object.

Parameters:
prefix - a String giving the prefix of the namespace
uri - a String giving the uri of the namespace
Returns:
the SOAPElement object into which this namespace declaration was inserted.
Throws:
SOAPException - if there is an error in creating the namespace

getAttributeValue

String getAttributeValue(Name name)
Returns the value of the attribute with the specified name.

Parameters:
name - a Name object with the name of the attribute
Returns:
a String giving the value of the specified attribute, Null if there is no such attribute
See Also:
getAttributeValue(javax.xml.namespace.QName)

getAttributeValue

String getAttributeValue(QName qname)
Returns the value of the attribute with the specified qname.

Parameters:
qname - a QName object with the qname of the attribute
Returns:
a String giving the value of the specified attribute, Null if there is no such attribute
Since:
SAAJ 1.3
See Also:
getAttributeValue(Name)

getAllAttributes

Iterator getAllAttributes()
Returns an Iterator over all of the attribute Name objects in this SOAPElement object. The iterator can be used to get the attribute names, which can then be passed to the method getAttributeValue to retrieve the value of each attribute.

Returns:
an iterator over the names of the attributes
See Also:
getAllAttributesAsQNames()

getAllAttributesAsQNames

Iterator getAllAttributesAsQNames()
Returns an Iterator over all of the attributes in this SOAPElement as QName objects. The iterator can be used to get the attribute QName, which can then be passed to the method getAttributeValue to retrieve the value of each attribute.

Returns:
an iterator over the QNames of the attributes
Since:
SAAJ 1.3
See Also:
getAllAttributes()

getNamespaceURI

String getNamespaceURI(String prefix)
Returns the URI of the namespace that has the given prefix.

Parameters:
prefix - a String giving the prefix of the namespace for which to search
Returns:
a String with the uri of the namespace that has the given prefix

getNamespacePrefixes

Iterator getNamespacePrefixes()
Returns an Iterator over the namespace prefix Strings declared by this element. The prefixes returned by this iterator can be passed to the method getNamespaceURI to retrieve the URI of each namespace.

Returns:
an iterator over the namespace prefixes in this SOAPElement object

getVisibleNamespacePrefixes

Iterator getVisibleNamespacePrefixes()
Returns an Iterator over the namespace prefix Strings visible to this element. The prefixes returned by this iterator can be passed to the method getNamespaceURI to retrieve the URI of each namespace.

Returns:
an iterator over the namespace prefixes are within scope of this SOAPElement object
Since:
SAAJ 1.2

createQName

QName createQName(String localName,
                  String prefix)
                  throws SOAPException
Creates a QName whose namespace URI is the one associated with the parameter, prefix, in the context of this SOAPElement. The remaining elements of the new QName are taken directly from the parameters, localName and prefix.

Parameters:
localName - a String containing the local part of the name.
prefix - a String containing the prefix for the name.
Returns:
a QName with the specified localName and prefix, and with a namespace that is associated with the prefix in the context of this SOAPElement. This namespace will be the same as the one that would be returned by getNamespaceURI(String) if it were given prefix as it's parameter.
Throws:
SOAPException - if the QName cannot be created.
Since:
SAAJ 1.3

getElementName

Name getElementName()
Returns the name of this SOAPElement object.

Returns:
a Name object with the name of this SOAPElement object

getElementQName

QName getElementQName()
Returns the qname of this SOAPElement object.

Returns:
a QName object with the qname of this SOAPElement object
Since:
SAAJ 1.3
See Also:
getElementName()

setElementQName

SOAPElement setElementQName(QName newName)
                            throws SOAPException
Changes the name of this Element to newName if possible. SOAP Defined elements such as SOAPEnvelope, SOAPHeader, SOAPBody etc. cannot have their names changed using this method. Any attempt to do so will result in a SOAPException being thrown.

Callers should not rely on the element instance being renamed as is. Implementations could end up copying the content of the SOAPElement to a renamed instance.

Parameters:
newName - the new name for the Element.
Returns:
The renamed Node
Throws:
SOAPException - if changing the name of this Element is not allowed.
Since:
SAAJ 1.3

removeAttribute

boolean removeAttribute(Name name)
Removes the attribute with the specified name.

Parameters:
name - the Name object with the name of the attribute to be removed
Returns:
true if the attribute was removed successfully; false if it was not
See Also:
removeAttribute(javax.xml.namespace.QName)

removeAttribute

boolean removeAttribute(QName qname)
Removes the attribute with the specified qname.

Parameters:
qname - the QName object with the qname of the attribute to be removed
Returns:
true if the attribute was removed successfully; false if it was not
Since:
SAAJ 1.3
See Also:
removeAttribute(Name)

removeNamespaceDeclaration

boolean removeNamespaceDeclaration(String prefix)
Removes the namespace declaration corresponding to the given prefix.

Parameters:
prefix - a String giving the prefix for which to search
Returns:
true if the namespace declaration was removed successfully; false if it was not

getChildElements

Iterator getChildElements()
Returns an Iterator over all the immediate child Nodes of this element. This includes javax.xml.soap.Text objects as well as SOAPElement objects.

Calling this method may cause child Element, SOAPElement and org.w3c.dom.Text nodes to be replaced by SOAPElement, SOAPHeaderElement, SOAPBodyElement or javax.xml.soap.Text nodes as appropriate for the type of this parent node. As a result the calling application must treat any existing references to these child nodes that have been obtained through DOM APIs as invalid and either discard them or refresh them with the values returned by this Iterator. This behavior can be avoided by calling the equivalent DOM APIs. See javax.xml.soap for more details.

Returns:
an iterator with the content of this SOAPElement object

getChildElements

Iterator getChildElements(Name name)
Returns an Iterator over all the immediate child Nodes of this element with the specified name. All of these children will be SOAPElement nodes.

Calling this method may cause child Element, SOAPElement and org.w3c.dom.Text nodes to be replaced by SOAPElement, SOAPHeaderElement, SOAPBodyElement or javax.xml.soap.Text nodes as appropriate for the type of this parent node. As a result the calling application must treat any existing references to these child nodes that have been obtained through DOM APIs as invalid and either discard them or refresh them with the values returned by this Iterator. This behavior can be avoided by calling the equivalent DOM APIs. See javax.xml.soap for more details.

Parameters:
name - a Name object with the name of the child elements to be returned
Returns:
an Iterator object over all the elements in this SOAPElement object with the specified name
See Also:
getChildElements(javax.xml.namespace.QName)

getChildElements

Iterator getChildElements(QName qname)
Returns an Iterator over all the immediate child Nodes of this element with the specified qname. All of these children will be SOAPElement nodes.

Calling this method may cause child Element, SOAPElement and org.w3c.dom.Text nodes to be replaced by SOAPElement, SOAPHeaderElement, SOAPBodyElement or javax.xml.soap.Text nodes as appropriate for the type of this parent node. As a result the calling application must treat any existing references to these child nodes that have been obtained through DOM APIs as invalid and either discard them or refresh them with the values returned by this Iterator. This behavior can be avoided by calling the equivalent DOM APIs. See javax.xml.soap for more details.

Parameters:
qname - a QName object with the qname of the child elements to be returned
Returns:
an Iterator object over all the elements in this SOAPElement object with the specified qname
Since:
SAAJ 1.3
See Also:
getChildElements(Name)

setEncodingStyle

void setEncodingStyle(String encodingStyle)
                      throws SOAPException
Sets the encoding style for this SOAPElement object to one specified.

Parameters:
encodingStyle - a String giving the encoding style
Throws:
IllegalArgumentException - if there was a problem in the encoding style being set.
SOAPException - if setting the encodingStyle is invalid for this SOAPElement.
See Also:
getEncodingStyle()

getEncodingStyle

String getEncodingStyle()
Returns the encoding style for this SOAPElement object.

Returns:
a String giving the encoding style
See Also:
setEncodingStyle(java.lang.String)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SOAPElementFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Class SOAPElementFactory

java.lang.Object
    extended by  javax.xml.soap.SOAPElementFactory
Deprecated. - Use javax.xml.soap.SOAPFactory for creating SOAPElements.

public class SOAPElementFactory
extends Object

SOAPElementFactory is a factory for XML fragments that will eventually end up in the SOAP part. These fragments can be inserted as children of the SOAPHeader or SOAPBody or SOAPEnvelope.

Elements created using this factory do not have the properties of an element that lives inside a SOAP header document. These elements are copied into the XML document tree when they are inserted.

See Also:
SOAPFactory

Method Summary
 SOAPElement create(Name name)
Deprecated. Use javax.xml.soap.SOAPFactory.createElement(javax.xml.soap.Name) instead
 SOAPElement create(String localName)
Deprecated. Use javax.xml.soap.SOAPFactory.createElement(String localName) instead
 SOAPElement create(String localName, String prefix, String uri)
Deprecated. Use javax.xml.soap.SOAPFactory.createElement(String localName, String prefix, String uri) instead
static SOAPElementFactory newInstance()
Deprecated. Creates a new instance of SOAPElementFactory.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public SOAPElement create(Name name)
                   throws SOAPException
Deprecated. Use javax.xml.soap.SOAPFactory.createElement(javax.xml.soap.Name) instead

Create a SOAPElement object initialized with the given Name object.

Parameters:
name - a Name object with the XML name for the new element
Returns:
the new SOAPElement object that was created
Throws:
SOAPException - if there is an error in creating the SOAPElement object
See Also:
SOAPFactory.createElement(javax.xml.soap.Name), SOAPFactory.createElement(javax.xml.namespace.QName)

create

public SOAPElement create(String localName)
                   throws SOAPException
Deprecated. Use javax.xml.soap.SOAPFactory.createElement(String localName) instead

Create a SOAPElement object initialized with the given local name.

Parameters:
localName - a String giving the local name for the new element
Returns:
the new SOAPElement object that was created
Throws:
SOAPException - if there is an error in creating the SOAPElement object
See Also:
SOAPFactory.createElement(java.lang.String)

create

public SOAPElement create(String localName,
                          String prefix,
                          String uri)
                   throws SOAPException
Deprecated. Use javax.xml.soap.SOAPFactory.createElement(String localName, String prefix, String uri) instead

Create a new SOAPElement object with the given local name, prefix and uri.

Parameters:
localName - a String giving the local name for the new element
prefix - the prefix for this SOAPElement
uri - a String giving the URI of the namespace to which the new element belongs
Throws:
SOAPException - if there is an error in creating the SOAPElement object
See Also:
SOAPFactory.createElement(java.lang.String, java.lang.String, java.lang.String)

newInstance

public static SOAPElementFactory newInstance()
                                      throws SOAPException
Deprecated.
Creates a new instance of SOAPElementFactory.

Returns:
a new instance of a SOAPElementFactory
Throws:
SOAPException - if there was an error creating the default SOAPElementFactory
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SOAPEnvelope

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Interface SOAPEnvelope

All Superinterfaces:
Element, Node, SOAPElement
public interface SOAPEnvelope
extends SOAPElement

The container for the SOAPHeader and SOAPBody portions of a SOAPPart object. By default, a SOAPMessage object is created with a SOAPPart object that has a SOAPEnvelope object. The SOAPEnvelope object by default has an empty SOAPBody object and an empty SOAPHeader object. The SOAPBody object is required, and the SOAPHeader object, though optional, is used in the majority of cases. If the SOAPHeader object is not needed, it can be deleted, which is shown later.

A client can access the SOAPHeader and SOAPBody objects by calling the methods SOAPEnvelope.getHeader and SOAPEnvelope.getBody. The following lines of code use these two methods after starting with the SOAPMessage object message to get the SOAPPart object sp, which is then used to get the SOAPEnvelope object se.

     SOAPPart sp = message.getSOAPPart();
     SOAPEnvelope se = sp.getEnvelope();
     SOAPHeader sh = se.getHeader();
     SOAPBody sb = se.getBody();

It is possible to change the body or header of a SOAPEnvelope object by retrieving the current one, deleting it, and then adding a new body or header. The javax.xml.soap.Node method deleteNode deletes the XML element (node) on which it is called. For example, the following line of code deletes the SOAPBody object that is retrieved by the method getBody.

      se.getBody().detachNode();
To create a SOAPHeader object to replace the one that was removed, a client uses the method SOAPEnvelope.addHeader, which creates a new header and adds it to the SOAPEnvelope object. Similarly, the method addBody creates a new SOAPBody object and adds it to the SOAPEnvelope object. The following code fragment retrieves the current header, removes it, and adds a new one. Then it retrieves the current body, removes it, and adds a new one.
     SOAPPart sp = message.getSOAPPart();
     SOAPEnvelope se = sp.getEnvelope();
     se.getHeader().detachNode();
     SOAPHeader sh = se.addHeader();
     se.getBody().detachNode();
     SOAPBody sb = se.addBody();
It is an error to add a SOAPBody or SOAPHeader object if one already exists.

The SOAPEnvelope interface provides three methods for creating Name objects. One method creates Name objects with a local name, a namespace prefix, and a namesapce URI. The second method creates Name objects with a local name and a namespace prefix, and the third creates Name objects with just a local name. The following line of code, in which se is a SOAPEnvelope object, creates a new Name object with all three.

     Name name = se.createName("GetLastTradePrice", "WOMBAT",
                                "http://www.wombat.org/trader");

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
SOAPBody | addBody() Creates a SOAPBody object and sets it as the SOAPBody object for this SOAPEnvelope object.
SOAPHeader | addHeader() Creates a SOAPHeader object and sets it as the SOAPHeader object for this SOAPEnvelope object.
Name | createName(String localName) Creates a new Name object initialized with the given local name.
Name | createName(String localName, String prefix, String uri) Creates a new Name object initialized with the given local name, namespace prefix, and namespace URI.
SOAPBody | getBody() Returns the SOAPBody object associated with this SOAPEnvelope object.
SOAPHeader | getHeader() Returns the SOAPHeader object for this SOAPEnvelope object.
Methods inherited from interface javax.xml.soap.SOAPElement
addAttribute, addAttribute, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addNamespaceDeclaration, addTextNode, createQName, getAllAttributes, getAllAttributesAsQNames, getAttributeValue, getAttributeValue, getChildElements, getChildElements, getChildElements, getElementName, getElementQName, getEncodingStyle, getNamespacePrefixes, getNamespaceURI, getVisibleNamespacePrefixes, removeAttribute, removeAttribute, removeContents, removeNamespaceDeclaration, setElementQName, setEncodingStyle
Methods inherited from interface javax.xml.soap.Node
detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue
Methods inherited from interface org.w3c.dom.Element
getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

createName

Name createName(String localName,
                String prefix,
                String uri)
                throws SOAPException
Creates a new Name object initialized with the given local name, namespace prefix, and namespace URI.

This factory method creates Name objects for use in the SOAP/XML document.

Parameters:
localName - a String giving the local name
prefix - a String giving the prefix of the namespace
uri - a String giving the URI of the namespace
Returns:
a Name object initialized with the given local name, namespace prefix, and namespace URI
Throws:
SOAPException - if there is a SOAP error

createName

Name createName(String localName)
                throws SOAPException
Creates a new Name object initialized with the given local name.

This factory method creates Name objects for use in the SOAP/XML document.

Parameters:
localName - a String giving the local name
Returns:
a Name object initialized with the given local name
Throws:
SOAPException - if there is a SOAP error

getHeader

SOAPHeader getHeader()
                     throws SOAPException
Returns the SOAPHeader object for this SOAPEnvelope object.

A new SOAPMessage object is by default created with a SOAPEnvelope object that contains an empty SOAPHeader object. As a result, the method getHeader will always return a SOAPHeader object unless the header has been removed and a new one has not been added.

Returns:
the SOAPHeader object or null if there is none
Throws:
SOAPException - if there is a problem obtaining the SOAPHeader object

getBody

SOAPBody getBody()
                 throws SOAPException
Returns the SOAPBody object associated with this SOAPEnvelope object.

A new SOAPMessage object is by default created with a SOAPEnvelope object that contains an empty SOAPBody object. As a result, the method getBody will always return a SOAPBody object unless the body has been removed and a new one has not been added.

Returns:
the SOAPBody object for this SOAPEnvelope object or null if there is none
Throws:
SOAPException - if there is a problem obtaining the SOAPBody object

addHeader

SOAPHeader addHeader()
                     throws SOAPException
Creates a SOAPHeader object and sets it as the SOAPHeader object for this SOAPEnvelope object.

It is illegal to add a header when the envelope already contains a header. Therefore, this method should be called only after the existing header has been removed.

Returns:
the new SOAPHeader object
Throws:
SOAPException - if this SOAPEnvelope object already contains a valid SOAPHeader object

addBody

SOAPBody addBody()
                 throws SOAPException
Creates a SOAPBody object and sets it as the SOAPBody object for this SOAPEnvelope object.

It is illegal to add a body when the envelope already contains a body. Therefore, this method should be called only after the existing body has been removed.

Returns:
the new SOAPBody object
Throws:
SOAPException - if this SOAPEnvelope object already contains a valid SOAPBody object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SOAPException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Class SOAPException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.soap.SOAPException
All Implemented Interfaces:
Serializable
public class SOAPException
extends Exception

An exception that signals that a SOAP exception has occurred. A SOAPException object may contain a String that gives the reason for the exception, an embedded Throwable object, or both. This class provides methods for retrieving reason messages and for retrieving the embedded Throwable object.

Typical reasons for throwing a SOAPException object are problems such as difficulty setting a header, not being able to send a message, and not being able to get a connection with the provider. Reasons for embedding a Throwable object include problems such as input/output errors or a parsing problem, such as an error in parsing a header.

See Also:
Serialized Form

Constructor Summary
SOAPException()
Constructs a SOAPException object with no reason or embedded Throwable object.
SOAPException(String reason)
Constructs a SOAPException object with the given String as the reason for the exception being thrown.
SOAPException(String reason, Throwable cause)
Constructs a SOAPException object with the given String as the reason for the exception being thrown and the given Throwable object as an embedded exception.
SOAPException(Throwable cause)
Constructs a SOAPException object initialized with the given Throwable object.
Method Summary
Throwable | getCause() Returns the Throwable object embedded in this SOAPException if there is one.
String | getMessage() Returns the detail message for this SOAPException object.
Throwable | initCause(Throwable cause) Initializes the cause field of this SOAPException object with the given Throwable object.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SOAPException

public SOAPException()
Constructs a SOAPException object with no reason or embedded Throwable object.

SOAPException

public SOAPException(String reason)
Constructs a SOAPException object with the given String as the reason for the exception being thrown.

Parameters:
reason - a description of what caused the exception

SOAPException

public SOAPException(String reason,
                     Throwable cause)
Constructs a SOAPException object with the given String as the reason for the exception being thrown and the given Throwable object as an embedded exception.

Parameters:
reason - a description of what caused the exception
cause - a Throwable object that is to be embedded in this SOAPException object

SOAPException

public SOAPException(Throwable cause)
Constructs a SOAPException object initialized with the given Throwable object.

Method Detail

getMessage

public String getMessage()
Returns the detail message for this SOAPException object.

If there is an embedded Throwable object, and if the SOAPException object has no detail message of its own, this method will return the detail message from the embedded Throwable object.

Overrides:
getMessage in class Throwable
Returns:
the error or warning message for this SOAPException or, if it has none, the message of the embedded Throwable object, if there is one

getCause

public Throwable getCause()
Returns the Throwable object embedded in this SOAPException if there is one. Otherwise, this method returns null.

Overrides:
getCause in class Throwable
Returns:
the embedded Throwable object or null if there is none

initCause

public Throwable initCause(Throwable cause)
Initializes the cause field of this SOAPException object with the given Throwable object.

This method can be called at most once. It is generally called from within the constructor or immediately after the constructor has returned a new SOAPException object. If this SOAPException object was created with the constructor SOAPException(Throwable) or SOAPException(String,Throwable), meaning that its cause field already has a value, this method cannot be called even once.

Overrides:
initCause in class Throwable
Parameters:
cause - the Throwable object that caused this SOAPException object to be thrown. The value of this parameter is saved for later retrieval by the getCause() method. A null value is permitted and indicates that the cause is nonexistent or unknown.
Returns:
a reference to this SOAPException instance
Throws:
IllegalArgumentException - if cause is this Throwable object. (A Throwable object cannot be its own cause.)
IllegalStateException - if the cause for this SOAPException object has already been initialized
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SOAPFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Class SOAPFactory

java.lang.Object
    extended by  javax.xml.soap.SOAPFactory

public abstract class SOAPFactory
extends Object

SOAPFactory is a factory for creating various objects that exist in the SOAP XML tree. SOAPFactory can be used to create XML fragments that will eventually end up in the SOAP part. These fragments can be inserted as children of the SOAPHeaderElement or SOAPBodyElement or SOAPEnvelope or other SOAPElement objects. SOAPFactory also has methods to create javax.xml.soap.Detail objects as well as java.xml.soap.Name objects.

Constructor Summary
SOAPFactory()
Method Summary
abstract Detail | createDetail() Creates a new Detail object which serves as a container for DetailEntry objects.
SOAPElement | createElement(Element domElement) Creates a SOAPElement object from an existing DOM Element.
abstract SOAPElement | createElement(Name name) Creates a SOAPElement object initialized with the given Name object.
SOAPElement | createElement(QName qname) Creates a SOAPElement object initialized with the given QName object.
abstract SOAPElement | createElement(String localName) Creates a SOAPElement object initialized with the given local name.
abstract SOAPElement | createElement(String localName, String prefix, String uri) Creates a new SOAPElement object with the given local name, prefix and uri.
abstract SOAPFault | createFault() Creates a new default SOAPFault object
abstract SOAPFault | createFault(String reasonText, QName faultCode) Creates a new SOAPFault object initialized with the given reasonText and faultCode
abstract Name | createName(String localName) Creates a new Name object initialized with the given local name.
abstract Name | createName(String localName, String prefix, String uri) Creates a new Name object initialized with the given local name, namespace prefix, and namespace URI.
static SOAPFactory | newInstance() Creates a new SOAPFactory object that is an instance of the default implementation (SOAP 1.1), This method uses the following ordered lookup procedure to determine the SOAPFactory implementation class to load: Use the javax.xml.soap.SOAPFactory system property.
static SOAPFactory | newInstance(String protocol) Creates a new SOAPFactory object that is an instance of the specified implementation, this method uses the SAAJMetaFactory to locate the implementation class and create the SOAPFactory instance.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SOAPFactory

public SOAPFactory()
Method Detail

createElement

public SOAPElement createElement(Element domElement)
                          throws SOAPException
Creates a SOAPElement object from an existing DOM Element. If the DOM Element that is passed in as an argument is already a SOAPElement then this method must return it unmodified without any further work. Otherwise, a new SOAPElement is created and a deep copy is made of the domElement argument. The concrete type of the return value will depend on the name of the domElement argument. If any part of the tree rooted in domElement violates SOAP rules, a SOAPException will be thrown.

Parameters:
domElement - - the Element to be copied.
Returns:
a new SOAPElement that is a copy of domElement.
Throws:
SOAPException - if there is an error in creating the SOAPElement object
Since:
SAAJ 1.3

createElement

public abstract SOAPElement createElement(Name name)
                                   throws SOAPException
Creates a SOAPElement object initialized with the given Name object. The concrete type of the return value will depend on the name given to the new SOAPElement. For instance, a new SOAPElement with the name "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a SOAPEnvelope that supports SOAP 1.2 behavior to be created.

Parameters:
name - a Name object with the XML name for the new element
Returns:
the new SOAPElement object that was created
Throws:
SOAPException - if there is an error in creating the SOAPElement object
See Also:
createElement(javax.xml.namespace.QName)

createElement

public SOAPElement createElement(QName qname)
                          throws SOAPException
Creates a SOAPElement object initialized with the given QName object. The concrete type of the return value will depend on the name given to the new SOAPElement. For instance, a new SOAPElement with the name "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a SOAPEnvelope that supports SOAP 1.2 behavior to be created.

Parameters:
qname - a QName object with the XML name for the new element
Returns:
the new SOAPElement object that was created
Throws:
SOAPException - if there is an error in creating the SOAPElement object
Since:
SAAJ 1.3
See Also:
createElement(Name)

createElement

public abstract SOAPElement createElement(String localName)
                                   throws SOAPException
Creates a SOAPElement object initialized with the given local name.

Parameters:
localName - a String giving the local name for the new element
Returns:
the new SOAPElement object that was created
Throws:
SOAPException - if there is an error in creating the SOAPElement object

createElement

public abstract SOAPElement createElement(String localName,
                                          String prefix,
                                          String uri)
                                   throws SOAPException
Creates a new SOAPElement object with the given local name, prefix and uri. The concrete type of the return value will depend on the name given to the new SOAPElement. For instance, a new SOAPElement with the name "{http://www.w3.org/2003/05/soap-envelope}Envelope" would cause a SOAPEnvelope that supports SOAP 1.2 behavior to be created.

Parameters:
localName - a String giving the local name for the new element
prefix - the prefix for this SOAPElement
uri - a String giving the URI of the namespace to which the new element belongs
Throws:
SOAPException - if there is an error in creating the SOAPElement object

createDetail

public abstract Detail createDetail()
                             throws SOAPException
Creates a new Detail object which serves as a container for DetailEntry objects.

This factory method creates Detail objects for use in situations where it is not practical to use the SOAPFault abstraction.

Returns:
a Detail object
Throws:
SOAPException - if there is a SOAP error
UnsupportedOperationException - if the protocol specified for the SOAPFactory was DYNAMIC_SOAP_PROTOCOL

createFault

public abstract SOAPFault createFault(String reasonText,
                                      QName faultCode)
                               throws SOAPException
Creates a new SOAPFault object initialized with the given reasonText and faultCode

Parameters:
reasonText - the ReasonText/FaultString for the fault
faultCode - the FaultCode for the fault
Returns:
a SOAPFault object
Throws:
SOAPException - if there is a SOAP error
Since:
SAAJ 1.3

createFault

public abstract SOAPFault createFault()
                               throws SOAPException
Creates a new default SOAPFault object

Returns:
a SOAPFault object
Throws:
SOAPException - if there is a SOAP error
Since:
SAAJ 1.3

createName

public abstract Name createName(String localName,
                                String prefix,
                                String uri)
                         throws SOAPException
Creates a new Name object initialized with the given local name, namespace prefix, and namespace URI.

This factory method creates Name objects for use in situations where it is not practical to use the SOAPEnvelope abstraction.

Parameters:
localName - a String giving the local name
prefix - a String giving the prefix of the namespace
uri - a String giving the URI of the namespace
Returns:
a Name object initialized with the given local name, namespace prefix, and namespace URI
Throws:
SOAPException - if there is a SOAP error

createName

public abstract Name createName(String localName)
                         throws SOAPException
Creates a new Name object initialized with the given local name.

This factory method creates Name objects for use in situations where it is not practical to use the SOAPEnvelope abstraction.

Parameters:
localName - a String giving the local name
Returns:
a Name object initialized with the given local name
Throws:
SOAPException - if there is a SOAP error

newInstance

public static SOAPFactory newInstance()
                               throws SOAPException
Creates a new SOAPFactory object that is an instance of the default implementation (SOAP 1.1), This method uses the following ordered lookup procedure to determine the SOAPFactory implementation class to load:
  • Use the javax.xml.soap.SOAPFactory system property.
  • Use the properties file "lib/jaxm.properties" in the JRE directory. This configuration file is in standard java.util.Properties format and contains the fully qualified name of the implementation class with the key being the system property defined above.
  • Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for a classname in the file META-INF/services/javax.xml.soap.SOAPFactory in jars available to the runtime.
  • Use the SAAJMetaFactory instance to locate the SOAPFactory implementation class.

Returns:
a new instance of a SOAPFactory
Throws:
SOAPException - if there was an error creating the default SOAPFactory
See Also:
SAAJMetaFactory

newInstance

public static SOAPFactory newInstance(String protocol)
                               throws SOAPException
Creates a new SOAPFactory object that is an instance of the specified implementation, this method uses the SAAJMetaFactory to locate the implementation class and create the SOAPFactory instance.

Parameters:
protocol - a string constant representing the protocol of the specified SOAP factory implementation. May be either DYNAMIC_SOAP_PROTOCOL, DEFAULT_SOAP_PROTOCOL (which is the same as) SOAP_1_1_PROTOCOL, or SOAP_1_2_PROTOCOL.
Returns:
a new instance of a SOAPFactory
Throws:
SOAPException - if there was an error creating the specified SOAPFactory
Since:
SAAJ 1.3
See Also:
SAAJMetaFactory
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SOAPFault

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Interface SOAPFault

All Superinterfaces:
Element, Node, SOAPBodyElement, SOAPElement
public interface SOAPFault
extends SOAPBodyElement

An element in the SOAPBody object that contains error and/or status information. This information may relate to errors in the SOAPMessage object or to problems that are not related to the content in the message itself. Problems not related to the message itself are generally errors in processing, such as the inability to communicate with an upstream server.

Depending on the protocol specified while creating the MessageFactory instance, a SOAPFault has sub-elements as defined in the SOAP 1.1/SOAP 1.2 specification.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
Detail | addDetail() Creates an optional Detail object and sets it as the Detail object for this SOAPFault object.
void | addFaultReasonText(String text, Locale locale) Appends or replaces a Reason Text item containing the specified text message and an xml:lang derived from locale.
void | appendFaultSubcode(QName subcode) Adds a Subcode to the end of the sequence of Subcodes contained by this SOAPFault.
Detail | getDetail() Returns the optional detail element for this SOAPFault object.
String | getFaultActor() Gets the fault actor for this SOAPFault object.
String | getFaultCode() Gets the fault code for this SOAPFault object.
Name | getFaultCodeAsName() Gets the mandatory SOAP 1.1 fault code for this SOAPFault object as a SAAJ Name object.
QName | getFaultCodeAsQName() Gets the fault code for this SOAPFault object as a QName object.
String | getFaultNode() Returns the optional Node element value for this SOAPFault object.
Iterator | getFaultReasonLocales() Returns an Iterator over a distinct sequence of Locales for which there are associated Reason Text items.
String | getFaultReasonText(Locale locale) Returns the Reason Text associated with the given Locale.
Iterator | getFaultReasonTexts() Returns an Iterator over a sequence of String objects containing all of the Reason Text items for this SOAPFault.
String | getFaultRole() Returns the optional Role element value for this SOAPFault object.
String | getFaultString() Gets the fault string for this SOAPFault object.
Locale | getFaultStringLocale() Gets the locale of the fault string for this SOAPFault object.
Iterator | getFaultSubcodes() Gets the Subcodes for this SOAPFault as an iterator over QNames.
boolean | hasDetail() Returns true if this SOAPFault has a Detail subelement and false otherwise.
void | removeAllFaultSubcodes() Removes any Subcodes that may be contained by this SOAPFault.
void | setFaultActor(String faultActor) Sets this SOAPFault object with the given fault actor.
void | setFaultCode(Name faultCodeQName) Sets this SOAPFault object with the given fault code.
void | setFaultCode(QName faultCodeQName) Sets this SOAPFault object with the given fault code.
void | setFaultCode(String faultCode) Sets this SOAPFault object with the give fault code.
void | setFaultNode(String uri) Creates or replaces any existing Node element value for this SOAPFault object.
void | setFaultRole(String uri) Creates or replaces any existing Role element value for this SOAPFault object.
void | setFaultString(String faultString) Sets the fault string for this SOAPFault object to the given string.
void | setFaultString(String faultString, Locale locale) Sets the fault string for this SOAPFault object to the given string and localized to the given locale.
Methods inherited from interface javax.xml.soap.SOAPElement
addAttribute, addAttribute, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addNamespaceDeclaration, addTextNode, createQName, getAllAttributes, getAllAttributesAsQNames, getAttributeValue, getAttributeValue, getChildElements, getChildElements, getChildElements, getElementName, getElementQName, getEncodingStyle, getNamespacePrefixes, getNamespaceURI, getVisibleNamespacePrefixes, removeAttribute, removeAttribute, removeContents, removeNamespaceDeclaration, setElementQName, setEncodingStyle
Methods inherited from interface javax.xml.soap.Node
detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue
Methods inherited from interface org.w3c.dom.Element
getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

setFaultCode

void setFaultCode(Name faultCodeQName)
                  throws SOAPException
Sets this SOAPFault object with the given fault code.

Fault codes, which give information about the fault, are defined in the SOAP 1.1 specification. A fault code is mandatory and must be of type Name. This method provides a convenient way to set a fault code. For example,

 SOAPEnvelope se = ...;
 // Create a qualified name in the SOAP namespace with a localName
 // of "Client". Note that prefix parameter is optional and is null
 // here which causes the implementation to use an appropriate prefix.
 Name qname = se.createName("Client", null,
                            SOAPConstants.URI_NS_SOAP_ENVELOPE);
 SOAPFault fault = ...;
 fault.setFaultCode(qname);
It is preferable to use this method over setFaultCode(String).

Parameters:
faultCodeQName - a Name object giving the fault code to be set. It must be namespace qualified.
Throws:
SOAPException - if there was an error in adding the faultcode element to the underlying XML tree.
Since:
SAAJ 1.2
See Also:
getFaultCodeAsName()

setFaultCode

void setFaultCode(QName faultCodeQName)
                  throws SOAPException
Sets this SOAPFault object with the given fault code. It is preferable to use this method over setFaultCode(Name).

Parameters:
faultCodeQName - a QName object giving the fault code to be set. It must be namespace qualified.
Throws:
SOAPException - if there was an error in adding the faultcode element to the underlying XML tree.
Since:
SAAJ 1.3
See Also:
getFaultCodeAsQName(), setFaultCode(Name), getFaultCodeAsQName()

setFaultCode

void setFaultCode(String faultCode)
                  throws SOAPException
Sets this SOAPFault object with the give fault code.

Fault codes, which given information about the fault, are defined in the SOAP 1.1 specification. This element is mandatory in SOAP 1.1. Because the fault code is required to be a QName it is preferable to use the setFaultCode(Name) form of this method.

Parameters:
faultCode - a String giving the fault code to be set. It must be of the form "prefix:localName" where the prefix has been defined in a namespace declaration.
Throws:
SOAPException - if there was an error in adding the faultCode to the underlying XML tree.
See Also:
setFaultCode(Name), getFaultCode(), SOAPElement.addNamespaceDeclaration(java.lang.String, java.lang.String)

getFaultCodeAsName

Name getFaultCodeAsName()
Gets the mandatory SOAP 1.1 fault code for this SOAPFault object as a SAAJ Name object. The SOAP 1.1 specification requires the value of the "faultcode" element to be of type QName. This method returns the content of the element as a QName in the form of a SAAJ Name object. This method should be used instead of the getFaultCode method since it allows applications to easily access the namespace name without additional parsing.

Returns:
a Name representing the faultcode
Since:
SAAJ 1.2
See Also:
setFaultCode(Name)

getFaultCodeAsQName

QName getFaultCodeAsQName()
Gets the fault code for this SOAPFault object as a QName object.

Returns:
a QName representing the faultcode
Since:
SAAJ 1.3
See Also:
setFaultCode(QName)

getFaultSubcodes

Iterator getFaultSubcodes()
Gets the Subcodes for this SOAPFault as an iterator over QNames.

Returns:
an Iterator that accesses a sequence of QNames. This Iterator should not support the optional remove method. The order in which the Subcodes are returned reflects the hierarchy of Subcodes present in the fault from top to bottom.
Throws:
UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Subcode.
Since:
SAAJ 1.3

removeAllFaultSubcodes

void removeAllFaultSubcodes()
Removes any Subcodes that may be contained by this SOAPFault. Subsequent calls to getFaultSubcodes will return an empty iterator until a call to appendFaultSubcode is made.

Throws:
UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Subcode.
Since:
SAAJ 1.3

appendFaultSubcode

void appendFaultSubcode(QName subcode)
                        throws SOAPException
Adds a Subcode to the end of the sequence of Subcodes contained by this SOAPFault. Subcodes, which were introduced in SOAP 1.2, are represented by a recursive sequence of subelements rooted in the mandatory Code subelement of a SOAP Fault.

Parameters:
subcode - a QName containing the Value of the Subcode.
Throws:
SOAPException - if there was an error in setting the Subcode
UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Subcode.
Since:
SAAJ 1.3

getFaultCode

String getFaultCode()
Gets the fault code for this SOAPFault object.

Returns:
a String with the fault code
See Also:
getFaultCodeAsName(), setFaultCode(javax.xml.soap.Name)

setFaultActor

void setFaultActor(String faultActor)
                   throws SOAPException
Sets this SOAPFault object with the given fault actor.

The fault actor is the recipient in the message path who caused the fault to happen.

If this SOAPFault supports SOAP 1.2 then this call is equivalent to setFaultRole(String)

Parameters:
faultActor - a String identifying the actor that caused this SOAPFault object
Throws:
SOAPException - if there was an error in adding the faultActor to the underlying XML tree.
See Also:
getFaultActor()

getFaultActor

String getFaultActor()
Gets the fault actor for this SOAPFault object.

If this SOAPFault supports SOAP 1.2 then this call is equivalent to getFaultRole()

Returns:
a String giving the actor in the message path that caused this SOAPFault object
See Also:
setFaultActor(java.lang.String)

setFaultString

void setFaultString(String faultString)
                    throws SOAPException
Sets the fault string for this SOAPFault object to the given string.

If this SOAPFault is part of a message that supports SOAP 1.2 then this call is equivalent to:

      addFaultReasonText(faultString, Locale.getDefault());

Parameters:
faultString - a String giving an explanation of the fault
Throws:
SOAPException - if there was an error in adding the faultString to the underlying XML tree.
See Also:
getFaultString()

setFaultString

void setFaultString(String faultString,
                    Locale locale)
                    throws SOAPException
Sets the fault string for this SOAPFault object to the given string and localized to the given locale.

If this SOAPFault is part of a message that supports SOAP 1.2 then this call is equivalent to:

      addFaultReasonText(faultString, locale);

Parameters:
faultString - a String giving an explanation of the fault
locale - a Locale object indicating the native language of the faultString
Throws:
SOAPException - if there was an error in adding the faultString to the underlying XML tree.
Since:
SAAJ 1.2
See Also:
getFaultString()

getFaultString

String getFaultString()
Gets the fault string for this SOAPFault object.

If this SOAPFault is part of a message that supports SOAP 1.2 then this call is equivalent to:

    String reason = null;
    try {
        reason = (String) getFaultReasonTexts().next();
    } catch (SOAPException e) {}
    return reason;

Returns:
a String giving an explanation of the fault
See Also:
setFaultString(String), setFaultString(String, Locale)

getFaultStringLocale

Locale getFaultStringLocale()
Gets the locale of the fault string for this SOAPFault object.

If this SOAPFault is part of a message that supports SOAP 1.2 then this call is equivalent to:

    Locale locale = null;
    try {
        locale = (Locale) getFaultReasonLocales().next();
    } catch (SOAPException e) {}
    return locale;

Returns:
a Locale object indicating the native language of the fault string or null if no locale was specified
Since:
SAAJ 1.2
See Also:
setFaultString(String, Locale)

hasDetail

boolean hasDetail()
Returns true if this SOAPFault has a Detail subelement and false otherwise. Equivalent to (getDetail()!=null).

Returns:
true if this SOAPFault has a Detail subelement and false otherwise.
Since:
SAAJ 1.3

getDetail

Detail getDetail()
Returns the optional detail element for this SOAPFault object.

A Detail object carries application-specific error information, the scope of the error information is restricted to faults in the SOAPBodyElement objects if this is a SOAP 1.1 Fault.

Returns:
a Detail object with application-specific error information if present, null otherwise

addDetail

Detail addDetail()
                 throws SOAPException
Creates an optional Detail object and sets it as the Detail object for this SOAPFault object.

It is illegal to add a detail when the fault already contains a detail. Therefore, this method should be called only after the existing detail has been removed.

Returns:
the new Detail object
Throws:
SOAPException - if this SOAPFault object already contains a valid Detail object

getFaultReasonLocales

Iterator getFaultReasonLocales()
                               throws SOAPException
Returns an Iterator over a distinct sequence of Locales for which there are associated Reason Text items. Any of these Locales can be used in a call to getFaultReasonText in order to obtain a localized version of the Reason Text string.

Returns:
an Iterator over a sequence of Locale objects for which there are associated Reason Text items.
Throws:
SOAPException - if there was an error in retrieving the fault Reason locales.
UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Reason.
Since:
SAAJ 1.3

getFaultReasonTexts

Iterator getFaultReasonTexts()
                             throws SOAPException
Returns an Iterator over a sequence of String objects containing all of the Reason Text items for this SOAPFault.

Returns:
an Iterator over env:Fault/env:Reason/env:Text items.
Throws:
SOAPException - if there was an error in retrieving the fault Reason texts.
UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Reason.
Since:
SAAJ 1.3

getFaultReasonText

String getFaultReasonText(Locale locale)
                          throws SOAPException
Returns the Reason Text associated with the given Locale. If more than one such Reason Text exists the first matching Text is returned

Parameters:
locale - -- the Locale for which a localized Reason Text is desired
Returns:
the Reason Text associated with locale
Throws:
SOAPException - if there was an error in retrieving the fault Reason text for the specified locale .
UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Reason.
Since:
SAAJ 1.3
See Also:
getFaultString()

addFaultReasonText

void addFaultReasonText(String text,
                        Locale locale)
                        throws SOAPException
Appends or replaces a Reason Text item containing the specified text message and an xml:lang derived from locale. If a Reason Text item with this xml:lang already exists its text value will be replaced with text. The locale parameter should not be null

Code sample:

 SOAPFault fault = ...;
 fault.addFaultReasonText("Version Mismatch", Locale.ENGLISH);

Parameters:
text - -- reason message string
locale - -- Locale object representing the locale of the message
Throws:
SOAPException - if there was an error in adding the Reason text or the locale passed was null.
UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Reason.
Since:
SAAJ 1.3

getFaultNode

String getFaultNode()
Returns the optional Node element value for this SOAPFault object. The Node element is optional in SOAP 1.2.

Returns:
Content of the env:Fault/env:Node element as a String or null if none
Throws:
UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Node.
Since:
SAAJ 1.3

setFaultNode

void setFaultNode(String uri)
                  throws SOAPException
Creates or replaces any existing Node element value for this SOAPFault object. The Node element is optional in SOAP 1.2.

Throws:
SOAPException - if there was an error in setting the Node for this SOAPFault object.
UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Node.
Since:
SAAJ 1.3

getFaultRole

String getFaultRole()
Returns the optional Role element value for this SOAPFault object. The Role element is optional in SOAP 1.2.

Returns:
Content of the env:Fault/env:Role element as a String or null if none
Throws:
UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Role.
Since:
SAAJ 1.3

setFaultRole

void setFaultRole(String uri)
                  throws SOAPException
Creates or replaces any existing Role element value for this SOAPFault object. The Role element is optional in SOAP 1.2.

Parameters:
uri - - the URI of the Role
Throws:
SOAPException - if there was an error in setting the Role for this SOAPFault object.
UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Role.
Since:
SAAJ 1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SOAPHeader

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Interface SOAPHeader

All Superinterfaces:
Element, Node, SOAPElement
public interface SOAPHeader
extends SOAPElement

A representation of the SOAP header element. A SOAP header element consists of XML data that affects the way the application-specific content is processed by the message provider. For example, transaction semantics, authentication information, and so on, can be specified as the content of a SOAPHeader object.

A SOAPEnvelope object contains an empty SOAPHeader object by default. If the SOAPHeader object, which is optional, is not needed, it can be retrieved and deleted with the following line of code. The variable se is a SOAPEnvelope object.

      se.getHeader().detachNode();
A SOAPHeader object is created with the SOAPEnvelope method addHeader. This method, which creates a new header and adds it to the envelope, may be called only after the existing header has been removed.
      se.getHeader().detachNode();
      SOAPHeader sh = se.addHeader();

A SOAPHeader object can have only SOAPHeaderElement objects as its immediate children. The method addHeaderElement creates a new HeaderElement object and adds it to the SOAPHeader object. In the following line of code, the argument to the method addHeaderElement is a Name object that is the name for the new HeaderElement object.

      SOAPHeaderElement shElement = sh.addHeaderElement(name);

See Also:
SOAPHeaderElement

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
SOAPHeaderElement | addHeaderElement(Name name) Creates a new SOAPHeaderElement object initialized with the specified name and adds it to this SOAPHeader object.
SOAPHeaderElement | addHeaderElement(QName qname) Creates a new SOAPHeaderElement object initialized with the specified qname and adds it to this SOAPHeader object.
SOAPHeaderElement | addNotUnderstoodHeaderElement(QName name) Creates a new NotUnderstood SOAPHeaderElement object initialized with the specified name and adds it to this SOAPHeader object.
SOAPHeaderElement | addUpgradeHeaderElement(Iterator supportedSOAPURIs) Creates a new Upgrade SOAPHeaderElement object initialized with the specified List of supported SOAP URIs and adds it to this SOAPHeader object.
SOAPHeaderElement | addUpgradeHeaderElement(String supportedSoapUri) Creates a new Upgrade SOAPHeaderElement object initialized with the specified supported SOAP URI and adds it to this SOAPHeader object.
SOAPHeaderElement | addUpgradeHeaderElement(String[] supportedSoapUris) Creates a new Upgrade SOAPHeaderElement object initialized with the specified array of supported SOAP URIs and adds it to this SOAPHeader object.
Iterator | examineAllHeaderElements() Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object.
Iterator | examineHeaderElements(String actor) Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object that have the specified actor.
Iterator | examineMustUnderstandHeaderElements(String actor) Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object that have the specified actor and that have a MustUnderstand attribute whose value is equivalent to true.
Iterator | extractAllHeaderElements() Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object and detaches them from this SOAPHeader object.
Iterator | extractHeaderElements(String actor) Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object that have the specified actor and detaches them from this SOAPHeader object.
Methods inherited from interface javax.xml.soap.SOAPElement
addAttribute, addAttribute, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addNamespaceDeclaration, addTextNode, createQName, getAllAttributes, getAllAttributesAsQNames, getAttributeValue, getAttributeValue, getChildElements, getChildElements, getChildElements, getElementName, getElementQName, getEncodingStyle, getNamespacePrefixes, getNamespaceURI, getVisibleNamespacePrefixes, removeAttribute, removeAttribute, removeContents, removeNamespaceDeclaration, setElementQName, setEncodingStyle
Methods inherited from interface javax.xml.soap.Node
detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue
Methods inherited from interface org.w3c.dom.Element
getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

addHeaderElement

SOAPHeaderElement addHeaderElement(Name name)
                                   throws SOAPException
Creates a new SOAPHeaderElement object initialized with the specified name and adds it to this SOAPHeader object.

Parameters:
name - a Name object with the name of the new SOAPHeaderElement object
Returns:
the new SOAPHeaderElement object that was inserted into this SOAPHeader object
Throws:
SOAPException - if a SOAP error occurs
See Also:
addHeaderElement(javax.xml.namespace.QName)

addHeaderElement

SOAPHeaderElement addHeaderElement(QName qname)
                                   throws SOAPException
Creates a new SOAPHeaderElement object initialized with the specified qname and adds it to this SOAPHeader object.

Parameters:
qname - a QName object with the qname of the new SOAPHeaderElement object
Returns:
the new SOAPHeaderElement object that was inserted into this SOAPHeader object
Throws:
SOAPException - if a SOAP error occurs
Since:
SAAJ 1.3
See Also:
addHeaderElement(Name)

examineMustUnderstandHeaderElements

Iterator examineMustUnderstandHeaderElements(String actor)
Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object that have the specified actor and that have a MustUnderstand attribute whose value is equivalent to true.

In SOAP 1.2 the env:actor attribute is replaced by the env:role attribute, but with essentially the same semantics.

Parameters:
actor - a String giving the URI of the actor / role for which to search
Returns:
an Iterator object over all the SOAPHeaderElement objects that contain the specified actor / role and are marked as MustUnderstand
Since:
SAAJ 1.2
See Also:
examineHeaderElements(java.lang.String), extractHeaderElements(java.lang.String), SOAPConstants.URI_SOAP_ACTOR_NEXT

examineHeaderElements

Iterator examineHeaderElements(String actor)
Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object that have the specified actor. An actor is a global attribute that indicates the intermediate parties that should process a message before it reaches its ultimate receiver. An actor receives the message and processes it before sending it on to the next actor. The default actor is the ultimate intended recipient for the message, so if no actor attribute is included in a SOAPHeader object, it is sent to the ultimate receiver along with the message body.

In SOAP 1.2 the env:actor attribute is replaced by the env:role attribute, but with essentially the same semantics.

Parameters:
actor - a String giving the URI of the actor / role for which to search
Returns:
an Iterator object over all the SOAPHeaderElement objects that contain the specified actor / role
See Also:
extractHeaderElements(java.lang.String), SOAPConstants.URI_SOAP_ACTOR_NEXT

extractHeaderElements

Iterator extractHeaderElements(String actor)
Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object that have the specified actor and detaches them from this SOAPHeader object.

This method allows an actor to process the parts of the SOAPHeader object that apply to it and to remove them before passing the message on to the next actor.

In SOAP 1.2 the env:actor attribute is replaced by the env:role attribute, but with essentially the same semantics.

Parameters:
actor - a String giving the URI of the actor / role for which to search
Returns:
an Iterator object over all the SOAPHeaderElement objects that contain the specified actor / role
See Also:
examineHeaderElements(java.lang.String), SOAPConstants.URI_SOAP_ACTOR_NEXT

addNotUnderstoodHeaderElement

SOAPHeaderElement addNotUnderstoodHeaderElement(QName name)
                                                throws SOAPException
Creates a new NotUnderstood SOAPHeaderElement object initialized with the specified name and adds it to this SOAPHeader object. This operation is supported only by SOAP 1.2.

Parameters:
name - a QName object with the name of the SOAPHeaderElement object that was not understood.
Returns:
the new SOAPHeaderElement object that was inserted into this SOAPHeader object
Throws:
SOAPException - if a SOAP error occurs.
UnsupportedOperationException - if this is a SOAP 1.1 Header.
Since:
SAAJ 1.3

addUpgradeHeaderElement

SOAPHeaderElement addUpgradeHeaderElement(Iterator supportedSOAPURIs)
                                          throws SOAPException
Creates a new Upgrade SOAPHeaderElement object initialized with the specified List of supported SOAP URIs and adds it to this SOAPHeader object. This operation is supported on both SOAP 1.1 and SOAP 1.2 header.

Parameters:
supportedSOAPURIs - an Iterator object with the URIs of SOAP versions supported.
Returns:
the new SOAPHeaderElement object that was inserted into this SOAPHeader object
Throws:
SOAPException - if a SOAP error occurs.
Since:
SAAJ 1.3

addUpgradeHeaderElement

SOAPHeaderElement addUpgradeHeaderElement(String[] supportedSoapUris)
                                          throws SOAPException
Creates a new Upgrade SOAPHeaderElement object initialized with the specified array of supported SOAP URIs and adds it to this SOAPHeader object. This operation is supported on both SOAP 1.1 and SOAP 1.2 header.

Parameters:
supportedSoapUris - an array of the URIs of SOAP versions supported.
Returns:
the new SOAPHeaderElement object that was inserted into this SOAPHeader object
Throws:
SOAPException - if a SOAP error occurs.
Since:
SAAJ 1.3

addUpgradeHeaderElement

SOAPHeaderElement addUpgradeHeaderElement(String supportedSoapUri)
                                          throws SOAPException
Creates a new Upgrade SOAPHeaderElement object initialized with the specified supported SOAP URI and adds it to this SOAPHeader object. This operation is supported on both SOAP 1.1 and SOAP 1.2 header.

Parameters:
supportedSoapUri - the URI of SOAP the version that is supported.
Returns:
the new SOAPHeaderElement object that was inserted into this SOAPHeader object
Throws:
SOAPException - if a SOAP error occurs.
Since:
SAAJ 1.3

examineAllHeaderElements

Iterator examineAllHeaderElements()
Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object.

Returns:
an Iterator object over all the SOAPHeaderElement objects contained by this SOAPHeader
Since:
SAAJ 1.2
See Also:
extractAllHeaderElements()

extractAllHeaderElements

Iterator extractAllHeaderElements()
Returns an Iterator over all the SOAPHeaderElement objects in this SOAPHeader object and detaches them from this SOAPHeader object.

Returns:
an Iterator object over all the SOAPHeaderElement objects contained by this SOAPHeader
Since:
SAAJ 1.2
See Also:
examineAllHeaderElements()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SOAPHeaderElement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Interface SOAPHeaderElement

All Superinterfaces:
Element, Node, SOAPElement
public interface SOAPHeaderElement
extends SOAPElement

An object representing the contents in the SOAP header part of the SOAP envelope. The immediate children of a SOAPHeader object can be represented only as SOAPHeaderElement objects.

A SOAPHeaderElement object can have other SOAPElement objects as its children.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
String | getActor() Returns the uri of the actor attribute of this SOAPHeaderElement.
boolean | getMustUnderstand() Returns the boolean value of the mustUnderstand attribute for this SOAPHeaderElement.
boolean | getRelay() Returns the boolean value of the relay attribute for this SOAPHeaderElement
String | getRole() Returns the value of the Role attribute of this SOAPHeaderElement.
void | setActor(String actorURI) Sets the actor associated with this SOAPHeaderElement object to the specified actor.
void | setMustUnderstand(boolean mustUnderstand) Sets the mustUnderstand attribute for this SOAPHeaderElement object to be either true or false.
void | setRelay(boolean relay) Sets the relay attribute for this SOAPHeaderElement to be either true or false.
void | setRole(String uri) Sets the Role associated with this SOAPHeaderElement object to the specified Role.
Methods inherited from interface javax.xml.soap.SOAPElement
addAttribute, addAttribute, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addChildElement, addNamespaceDeclaration, addTextNode, createQName, getAllAttributes, getAllAttributesAsQNames, getAttributeValue, getAttributeValue, getChildElements, getChildElements, getChildElements, getElementName, getElementQName, getEncodingStyle, getNamespacePrefixes, getNamespaceURI, getVisibleNamespacePrefixes, removeAttribute, removeAttribute, removeContents, removeNamespaceDeclaration, setElementQName, setEncodingStyle
Methods inherited from interface javax.xml.soap.Node
detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue
Methods inherited from interface org.w3c.dom.Element
getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, getSchemaTypeInfo, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setIdAttribute, setIdAttributeNode, setIdAttributeNS
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

setActor

void setActor(String actorURI)
Sets the actor associated with this SOAPHeaderElement object to the specified actor. The default value of an actor is: SOAPConstants.URI_SOAP_ACTOR_NEXT

If this SOAPHeaderElement supports SOAP 1.2 then this call is equivalent to setRole(String)

Parameters:
actorURI - a String giving the URI of the actor to set
Throws:
IllegalArgumentException - if there is a problem in setting the actor.
See Also:
getActor()

setRole

void setRole(String uri)
             throws SOAPException
Sets the Role associated with this SOAPHeaderElement object to the specified Role.

Parameters:
uri - - the URI of the Role
Throws:
SOAPException - if there is an error in setting the role
UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Role.
Since:
SAAJ 1.3

getActor

String getActor()
Returns the uri of the actor attribute of this SOAPHeaderElement.

If this SOAPHeaderElement supports SOAP 1.2 then this call is equivalent to getRole()

Returns:
a String giving the URI of the actor
See Also:
setActor(java.lang.String)

getRole

String getRole()
Returns the value of the Role attribute of this SOAPHeaderElement.

Returns:
a String giving the URI of the Role
Throws:
UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Fault Role.
Since:
SAAJ 1.3

setMustUnderstand

void setMustUnderstand(boolean mustUnderstand)
Sets the mustUnderstand attribute for this SOAPHeaderElement object to be either true or false.

If the mustUnderstand attribute is on, the actor who receives the SOAPHeaderElement must process it correctly. This ensures, for example, that if the SOAPHeaderElement object modifies the message, that the message is being modified correctly.

Parameters:
mustUnderstand - true to set the mustUnderstand attribute to true; false to set it to false
Throws:
IllegalArgumentException - if there is a problem in setting the mustUnderstand attribute
See Also:
getMustUnderstand(), setRelay(boolean)

getMustUnderstand

boolean getMustUnderstand()
Returns the boolean value of the mustUnderstand attribute for this SOAPHeaderElement.

Returns:
true if the mustUnderstand attribute of this SOAPHeaderElement object is turned on; false otherwise

setRelay

void setRelay(boolean relay)
              throws SOAPException
Sets the relay attribute for this SOAPHeaderElement to be either true or false.

The SOAP relay attribute is set to true to indicate that the SOAP header block must be relayed by any node that is targeted by the header block but not actually process it. This attribute is ignored on header blocks whose mustUnderstand attribute is set to true or that are targeted at the ultimate reciever (which is the default). The default value of this attribute is false.

Parameters:
relay - the new value of the relay attribute
Throws:
SOAPException - if there is a problem in setting the relay attribute.
UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Relay attribute.
Since:
SAAJ 1.3
See Also:
setMustUnderstand(boolean), getRelay()

getRelay

boolean getRelay()
Returns the boolean value of the relay attribute for this SOAPHeaderElement

Returns:
true if the relay attribute is turned on; false otherwise
Throws:
UnsupportedOperationException - if this message does not support the SOAP 1.2 concept of Relay attribute.
Since:
SAAJ 1.3
See Also:
getMustUnderstand(), setRelay(boolean)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SOAPMessage

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Class SOAPMessage

java.lang.Object
    extended by  javax.xml.soap.SOAPMessage

public abstract class SOAPMessage
extends Object

The root class for all SOAP messages. As transmitted on the "wire", a SOAP message is an XML document or a MIME message whose first body part is an XML/SOAP document.

A SOAPMessage object consists of a SOAP part and optionally one or more attachment parts. The SOAP part for a SOAPMessage object is a SOAPPart object, which contains information used for message routing and identification, and which can contain application-specific content. All data in the SOAP Part of a message must be in XML format.

A new SOAPMessage object contains the following by default:

  • A SOAPPart object
  • A SOAPEnvelope object
  • A SOAPBody object
  • A SOAPHeader object
The SOAP part of a message can be retrieved by calling the method SOAPMessage.getSOAPPart(). The SOAPEnvelope object is retrieved from the SOAPPart object, and the SOAPEnvelope object is used to retrieve the SOAPBody and SOAPHeader objects.
     SOAPPart sp = message.getSOAPPart();
     SOAPEnvelope se = sp.getEnvelope();
     SOAPBody sb = se.getBody();
     SOAPHeader sh = se.getHeader();

In addition to the mandatory SOAPPart object, a SOAPMessage object may contain zero or more AttachmentPart objects, each of which contains application-specific data. The SOAPMessage interface provides methods for creating AttachmentPart objects and also for adding them to a SOAPMessage object. A party that has received a SOAPMessage object can examine its contents by retrieving individual attachment parts.

Unlike the rest of a SOAP message, an attachment is not required to be in XML format and can therefore be anything from simple text to an image file. Consequently, any message content that is not in XML format must be in an AttachmentPart object.

A MessageFactory object may create SOAPMessage objects with behavior that is specialized to a particular implementation or application of SAAJ. For instance, a MessageFactory object may produce SOAPMessage objects that conform to a particular Profile such as ebXML. In this case a MessageFactory object might produce SOAPMessage objects that are initialized with ebXML headers.

In order to ensure backward source compatibility, methods that are added to this class after version 1.1 of the SAAJ specification are all concrete instead of abstract and they all have default implementations. Unless otherwise noted in the JavaDocs for those methods the default implementations simply throw an UnsupportedOperationException and the SAAJ implementation code must override them with methods that provide the specified behavior. Legacy client code does not have this restriction, however, so long as there is no claim made that it conforms to some later version of the specification than it was originally written for. A legacy class that extends the SOAPMessage class can be compiled and/or run against succeeding versions of the SAAJ API without modification. If such a class was correctly implemented then it will continue to behave correctly relative to the version of the specification against which it was written.

See Also:
MessageFactory, AttachmentPart

Field Summary
static String | CHARACTER_SET_ENCODING Specifies the character type encoding for the SOAP Message.
static String | WRITE_XML_DECLARATION Specifies whether the SOAP Message will contain an XML declaration when it is sent.
Constructor Summary
SOAPMessage()
Method Summary
abstract void | addAttachmentPart(AttachmentPart AttachmentPart) Adds the given AttachmentPart object to this SOAPMessage object.
abstract int | countAttachments() Gets a count of the number of attachments in this message.
abstract AttachmentPart | createAttachmentPart() Creates a new empty AttachmentPart object.
AttachmentPart | createAttachmentPart(DataHandler dataHandler) Creates an AttachmentPart object and populates it using the given DataHandler object.
AttachmentPart | createAttachmentPart(Object content, String contentType) Creates an AttachmentPart object and populates it with the specified data of the specified content type.
abstract AttachmentPart | getAttachment(SOAPElement element) Returns an AttachmentPart object that is associated with an attachment that is referenced by this SOAPElement or null if no such attachment exists.
abstract Iterator | getAttachments() Retrieves all the AttachmentPart objects that are part of this SOAPMessage object.
abstract Iterator | getAttachments(MimeHeaders headers) Retrieves all the AttachmentPart objects that have header entries that match the specified headers.
abstract String | getContentDescription() Retrieves a description of this SOAPMessage object's content.
abstract MimeHeaders | getMimeHeaders() Returns all the transport-specific MIME headers for this SOAPMessage object in a transport-independent fashion.
Object | getProperty(String property) Retrieves value of the specified property.
SOAPBody | getSOAPBody() Gets the SOAP Body contained in this SOAPMessage object.
SOAPHeader | getSOAPHeader() Gets the SOAP Header contained in this SOAPMessage object.
abstract SOAPPart | getSOAPPart() Gets the SOAP part of this SOAPMessage object.
abstract void | removeAllAttachments() Removes all AttachmentPart objects that have been added to this SOAPMessage object.
abstract void | removeAttachments(MimeHeaders headers) Removes all the AttachmentPart objects that have header entries that match the specified headers.
abstract void | saveChanges() Updates this SOAPMessage object with all the changes that have been made to it.
abstract boolean | saveRequired() Indicates whether this SOAPMessage object needs to have the method saveChanges called on it.
abstract void | setContentDescription(String description) Sets the description of this SOAPMessage object's content with the given description.
void | setProperty(String property, Object value) Associates the specified value with the specified property.
abstract void | writeTo(OutputStream out) Writes this SOAPMessage object to the given output stream.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CHARACTER_SET_ENCODING

public static final String CHARACTER_SET_ENCODING
Specifies the character type encoding for the SOAP Message. Valid values include "utf-8" and "utf-16". See vendor documentation for additional supported values. The default is "utf-8".

Since:
SAAJ 1.2
See Also:
SOAPMessage.setProperty, Constant Field Values

WRITE_XML_DECLARATION

public static final String WRITE_XML_DECLARATION
Specifies whether the SOAP Message will contain an XML declaration when it is sent. The only valid values are "true" and "false". The default is "false".

Since:
SAAJ 1.2
See Also:
SOAPMessage.setProperty, Constant Field Values
Constructor Detail

SOAPMessage

public SOAPMessage()
Method Detail

setContentDescription

public abstract void setContentDescription(String description)
Sets the description of this SOAPMessage object's content with the given description.

Parameters:
description - a String describing the content of this message
See Also:
getContentDescription()

getContentDescription

public abstract String getContentDescription()
Retrieves a description of this SOAPMessage object's content.

Returns:
a String describing the content of this message or null if no description has been set
See Also:
setContentDescription(java.lang.String)

getSOAPPart

public abstract SOAPPart getSOAPPart()
Gets the SOAP part of this SOAPMessage object.

SOAPMessage object contains one or more attachments, the SOAP Part must be the first MIME body part in the message.

Returns:
the SOAPPart object for this SOAPMessage object

getSOAPBody

public SOAPBody getSOAPBody()
                     throws SOAPException
Gets the SOAP Body contained in this SOAPMessage object.

Returns:
the SOAPBody object contained by this SOAPMessage object
Throws:
SOAPException - if the SOAP Body does not exist or cannot be retrieved
Since:
SAAJ 1.2

getSOAPHeader

public SOAPHeader getSOAPHeader()
                         throws SOAPException
Gets the SOAP Header contained in this SOAPMessage object.

Returns:
the SOAPHeader object contained by this SOAPMessage object
Throws:
SOAPException - if the SOAP Header does not exist or cannot be retrieved
Since:
SAAJ 1.2

removeAllAttachments

public abstract void removeAllAttachments()
Removes all AttachmentPart objects that have been added to this SOAPMessage object.

This method does not touch the SOAP part.

countAttachments

public abstract int countAttachments()
Gets a count of the number of attachments in this message. This count does not include the SOAP part.

Returns:
the number of AttachmentPart objects that are part of this SOAPMessage object

getAttachments

public abstract Iterator getAttachments()
Retrieves all the AttachmentPart objects that are part of this SOAPMessage object.

Returns:
an iterator over all the attachments in this message

getAttachments

public abstract Iterator getAttachments(MimeHeaders headers)
Retrieves all the AttachmentPart objects that have header entries that match the specified headers. Note that a returned attachment could have headers in addition to those specified.

Parameters:
headers - a MimeHeaders object containing the MIME headers for which to search
Returns:
an iterator over all attachments that have a header that matches one of the given headers

removeAttachments

public abstract void removeAttachments(MimeHeaders headers)
Removes all the AttachmentPart objects that have header entries that match the specified headers. Note that the removed attachment could have headers in addition to those specified.

Parameters:
headers - a MimeHeaders object containing the MIME headers for which to search
Since:
SAAJ 1.3

getAttachment

public abstract AttachmentPart getAttachment(SOAPElement element)
                                      throws SOAPException
Returns an AttachmentPart object that is associated with an attachment that is referenced by this SOAPElement or null if no such attachment exists. References can be made via an href attribute as described in SOAP Messages with Attachments, or via a single Text child node containing a URI as described in the WS-I Attachments Profile 1.0 for elements of schema type ref:swaRef(ref:swaRef). These two mechanisms must be supported. The support for references via href attribute also implies that this method should also be supported on an element that is an xop:Include element ( XOP). other reference mechanisms may be supported by individual implementations of this standard. Contact your vendor for details.

Parameters:
element - The SOAPElement containing the reference to an Attachment
Returns:
the referenced AttachmentPart or null if no such AttachmentPart exists or no reference can be found in this SOAPElement.
Throws:
SOAPException - if there is an error in the attempt to access the attachment
Since:
SAAJ 1.3

addAttachmentPart

public abstract void addAttachmentPart(AttachmentPart AttachmentPart)
Adds the given AttachmentPart object to this SOAPMessage object. An AttachmentPart object must be created before it can be added to a message.

Parameters:
AttachmentPart - an AttachmentPart object that is to become part of this SOAPMessage object
Throws:
IllegalArgumentException

createAttachmentPart

public abstract AttachmentPart createAttachmentPart()
Creates a new empty AttachmentPart object. Note that the method addAttachmentPart must be called with this new AttachmentPart object as the parameter in order for it to become an attachment to this SOAPMessage object.

Returns:
a new AttachmentPart object that can be populated and added to this SOAPMessage object

createAttachmentPart

public AttachmentPart createAttachmentPart(DataHandler dataHandler)
Creates an AttachmentPart object and populates it using the given DataHandler object.

Parameters:
dataHandler - the javax.activation.DataHandler object that will generate the content for this SOAPMessage object
Returns:
a new AttachmentPart object that contains data generated by the given DataHandler object
Throws:
IllegalArgumentException - if there was a problem with the specified DataHandler object
See Also:
DataHandler, DataContentHandler

getMimeHeaders

public abstract MimeHeaders getMimeHeaders()
Returns all the transport-specific MIME headers for this SOAPMessage object in a transport-independent fashion.

Returns:
a MimeHeaders object containing the MimeHeader objects

createAttachmentPart

public AttachmentPart createAttachmentPart(Object content,
                                           String contentType)
Creates an AttachmentPart object and populates it with the specified data of the specified content type. The type of the Object should correspond to the value given for the Content-Type.

Parameters:
content - an Object containing the content for the AttachmentPart object to be created
contentType - a String object giving the type of content; examples are "text/xml", "text/plain", and "image/jpeg"
Returns:
a new AttachmentPart object that contains the given data
Throws:
IllegalArgumentException - may be thrown if the contentType does not match the type of the content object, or if there was no DataContentHandler object for the given content object
See Also:
DataHandler, DataContentHandler

saveChanges

public abstract void saveChanges()
                          throws SOAPException
Updates this SOAPMessage object with all the changes that have been made to it. This method is called automatically when writeTo(OutputStream) is called. However, if changes are made to a message that was received or to one that has already been sent, the method saveChanges needs to be called explicitly in order to save the changes. The method saveChanges also generates any changes that can be read back (for example, a MessageId in profiles that support a message id). All MIME headers in a message that is created for sending purposes are guaranteed to have valid values only after saveChanges has been called.

In addition, this method marks the point at which the data from all constituent AttachmentPart objects are pulled into the message.

Throws:
SOAPException - if there was a problem saving changes to this message.
SOAPException

saveRequired

public abstract boolean saveRequired()
Indicates whether this SOAPMessage object needs to have the method saveChanges called on it.

Returns:
true if saveChanges needs to be called; false otherwise.

writeTo

public abstract void writeTo(OutputStream out)
                      throws SOAPException,
                             IOException
Writes this SOAPMessage object to the given output stream. The externalization format is as defined by the SOAP 1.1 with Attachments specification.

If there are no attachments, just an XML stream is written out. For those messages that have attachments, writeTo writes a MIME-encoded byte stream.

Note that this method does not write the transport-specific MIME Headers of the Message

Parameters:
out - the OutputStream object to which this SOAPMessage object will be written
Throws:
IOException - if an I/O error occurs
SOAPException - if there was a problem in externalizing this SOAP message

setProperty

public void setProperty(String property,
                        Object value)
                 throws SOAPException
Associates the specified value with the specified property. If there was already a value associated with this property, the old value is replaced.

The valid property names include WRITE_XML_DECLARATION and CHARACTER_SET_ENCODING. All of these standard SAAJ properties are prefixed by "javax.xml.soap". Vendors may also add implementation specific properties. These properties must be prefixed with package names that are unique to the vendor.

Setting the property WRITE_XML_DECLARATION to "true" will cause an XML Declaration to be written out at the start of the SOAP message. The default value of "false" suppresses this declaration.

The property CHARACTER_SET_ENCODING defaults to the value "utf-8" which causes the SOAP message to be encoded using UTF-8. Setting CHARACTER_SET_ENCODING to "utf-16" causes the SOAP message to be encoded using UTF-16.

Some implementations may allow encodings in addition to UTF-8 and UTF-16. Refer to your vendor's documentation for details.

Parameters:
property - the property with which the specified value is to be associated.
value - the value to be associated with the specified property
Throws:
SOAPException - if the property name is not recognized.
Since:
SAAJ 1.2

getProperty

public Object getProperty(String property)
                   throws SOAPException
Retrieves value of the specified property.

Parameters:
property - the name of the property to retrieve
Returns:
the value associated with the named property or null if no such property exists.
Throws:
SOAPException - if the property name is not recognized.
Since:
SAAJ 1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SOAPPart

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Class SOAPPart

java.lang.Object
    extended by  javax.xml.soap.SOAPPart
All Implemented Interfaces:
Document, Node
public abstract class SOAPPart
extends Object
implements Document, Node

The container for the SOAP-specific portion of a SOAPMessage object. All messages are required to have a SOAP part, so when a SOAPMessage object is created, it will automatically have a SOAPPart object.

A SOAPPart object is a MIME part and has the MIME headers Content-Id, Content-Location, and Content-Type. Because the value of Content-Type must be "text/xml", a SOAPPart object automatically has a MIME header of Content-Type with its value set to "text/xml". The value must be "text/xml" because content in the SOAP part of a message must be in XML format. Content that is not of type "text/xml" must be in an AttachmentPart object rather than in the SOAPPart object.

When a message is sent, its SOAP part must have the MIME header Content-Type set to "text/xml". Or, from the other perspective, the SOAP part of any message that is received must have the MIME header Content-Type with a value of "text/xml".

A client can access the SOAPPart object of a SOAPMessage object by calling the method SOAPMessage.getSOAPPart. The following line of code, in which message is a SOAPMessage object, retrieves the SOAP part of a message.

   SOAPPart soapPart = message.getSOAPPart();

A SOAPPart object contains a SOAPEnvelope object, which in turn contains a SOAPBody object and a SOAPHeader object. The SOAPPart method getEnvelope can be used to retrieve the SOAPEnvelope object.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Constructor Summary
SOAPPart()
Method Summary
abstract void | addMimeHeader(String name, String value) Creates a MimeHeader object with the specified name and value and adds it to this SOAPPart object.
abstract Iterator | getAllMimeHeaders() Retrieves all the headers for this SOAPPart object as an iterator over the MimeHeader objects.
abstract Source | getContent() Returns the content of the SOAPEnvelope as a JAXP Source object.
String | getContentId() Retrieves the value of the MIME header whose name is "Content-Id".
String | getContentLocation() Retrieves the value of the MIME header whose name is "Content-Location".
abstract SOAPEnvelope | getEnvelope() Gets the SOAPEnvelope object associated with this SOAPPart object.
abstract Iterator | getMatchingMimeHeaders(String[] names) Retrieves all MimeHeader objects that match a name in the given array.
abstract String[] | getMimeHeader(String name) Gets all the values of the MimeHeader object in this SOAPPart object that is identified by the given String.
abstract Iterator | getNonMatchingMimeHeaders(String[] names) Retrieves all MimeHeader objects whose name does not match a name in the given array.
abstract void | removeAllMimeHeaders() Removes all the MimeHeader objects for this SOAPEnvelope object.
abstract void | removeMimeHeader(String header) Removes all MIME headers that match the given name.
abstract void | setContent(Source source) Sets the content of the SOAPEnvelope object with the data from the given Source object.
void | setContentId(String contentId) Sets the value of the MIME header named "Content-Id" to the given String.
void | setContentLocation(String contentLocation) Sets the value of the MIME header "Content-Location" to the given String.
abstract void | setMimeHeader(String name, String value) Changes the first header entry that matches the given header name so that its value is the given value, adding a new header with the given name and value if no existing header is a match.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.w3c.dom.Document
adoptNode, createAttribute, createAttributeNS, createCDATASection, createComment, createDocumentFragment, createElement, createElementNS, createEntityReference, createProcessingInstruction, createTextNode, getDoctype, getDocumentElement, getDocumentURI, getDomConfig, getElementById, getElementsByTagName, getElementsByTagNameNS, getImplementation, getInputEncoding, getStrictErrorChecking, getXmlEncoding, getXmlStandalone, getXmlVersion, importNode, normalizeDocument, renameNode, setDocumentURI, setStrictErrorChecking, setXmlStandalone, setXmlVersion
Methods inherited from interface javax.xml.soap.Node
detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Constructor Detail

SOAPPart

public SOAPPart()
Method Detail

getEnvelope

public abstract SOAPEnvelope getEnvelope()
                                  throws SOAPException
Gets the SOAPEnvelope object associated with this SOAPPart object. Once the SOAP envelope is obtained, it can be used to get its contents.

Returns:
the SOAPEnvelope object for this SOAPPart object
Throws:
SOAPException - if there is a SOAP error

getContentId

public String getContentId()
Retrieves the value of the MIME header whose name is "Content-Id".

Returns:
a String giving the value of the MIME header named "Content-Id"
See Also:
setContentId(java.lang.String)

getContentLocation

public String getContentLocation()
Retrieves the value of the MIME header whose name is "Content-Location".

Returns:
a String giving the value of the MIME header whose name is "Content-Location"
See Also:
setContentLocation(java.lang.String)

setContentId

public void setContentId(String contentId)
Sets the value of the MIME header named "Content-Id" to the given String.

Parameters:
contentId - a String giving the value of the MIME header "Content-Id"
Throws:
IllegalArgumentException - if there is a problem in setting the content id
See Also:
getContentId()

setContentLocation

public void setContentLocation(String contentLocation)
Sets the value of the MIME header "Content-Location" to the given String.

Parameters:
contentLocation - a String giving the value of the MIME header "Content-Location"
Throws:
IllegalArgumentException - if there is a problem in setting the content location.
See Also:
getContentLocation()

removeMimeHeader

public abstract void removeMimeHeader(String header)
Removes all MIME headers that match the given name.

Parameters:
header - a String giving the name of the MIME header(s) to be removed

removeAllMimeHeaders

public abstract void removeAllMimeHeaders()
Removes all the MimeHeader objects for this SOAPEnvelope object.

getMimeHeader

public abstract String[] getMimeHeader(String name)
Gets all the values of the MimeHeader object in this SOAPPart object that is identified by the given String.

Parameters:
name - the name of the header; example: "Content-Type"
Returns:
a String array giving all the values for the specified header
See Also:
setMimeHeader(java.lang.String, java.lang.String)

setMimeHeader

public abstract void setMimeHeader(String name,
                                   String value)
Changes the first header entry that matches the given header name so that its value is the given value, adding a new header with the given name and value if no existing header is a match. If there is a match, this method clears all existing values for the first header that matches and sets the given value instead. If more than one header has the given name, this method removes all of the matching headers after the first one.

Note that RFC822 headers can contain only US-ASCII characters.

Parameters:
name - a String giving the header name for which to search
value - a String giving the value to be set. This value will be substituted for the current value(s) of the first header that is a match if there is one. If there is no match, this value will be the value for a new MimeHeader object.
Throws:
IllegalArgumentException - if there was a problem with the specified mime header name or value
See Also:
getMimeHeader(java.lang.String)

addMimeHeader

public abstract void addMimeHeader(String name,
                                   String value)
Creates a MimeHeader object with the specified name and value and adds it to this SOAPPart object. If a MimeHeader with the specified name already exists, this method adds the specified value to the already existing value(s).

Note that RFC822 headers can contain only US-ASCII characters.

Parameters:
name - a String giving the header name
value - a String giving the value to be set or added
Throws:
IllegalArgumentException - if there was a problem with the specified mime header name or value

getAllMimeHeaders

public abstract Iterator getAllMimeHeaders()
Retrieves all the headers for this SOAPPart object as an iterator over the MimeHeader objects.

Returns:
an Iterator object with all of the Mime headers for this SOAPPart object

getMatchingMimeHeaders

public abstract Iterator getMatchingMimeHeaders(String[] names)
Retrieves all MimeHeader objects that match a name in the given array.

Parameters:
names - a String array with the name(s) of the MIME headers to be returned
Returns:
all of the MIME headers that match one of the names in the given array, returned as an Iterator object

getNonMatchingMimeHeaders

public abstract Iterator getNonMatchingMimeHeaders(String[] names)
Retrieves all MimeHeader objects whose name does not match a name in the given array.

Parameters:
names - a String array with the name(s) of the MIME headers not to be returned
Returns:
all of the MIME headers in this SOAPPart object except those that match one of the names in the given array. The nonmatching MIME headers are returned as an Iterator object.

setContent

public abstract void setContent(Source source)
                         throws SOAPException
Sets the content of the SOAPEnvelope object with the data from the given Source object. This Source must contain a valid SOAP document.

Parameters:
source - the javax.xml.transform.Source object with the data to be set
Throws:
SOAPException - if there is a problem in setting the source
See Also:
getContent()

getContent

public abstract Source getContent()
                           throws SOAPException
Returns the content of the SOAPEnvelope as a JAXP Source object.

Returns:
the content as a javax.xml.transform.Source object
Throws:
SOAPException - if the implementation cannot convert the specified Source object
See Also:
setContent(javax.xml.transform.Source)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Text

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.soap
Interface Text

All Superinterfaces:
CharacterData, Node, Text
public interface Text
extends Node, Text

A representation of a node whose value is text. A Text object may represent text that is content or text that is a comment.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
 boolean isComment()
Retrieves whether this Text object represents a comment.
Methods inherited from interface javax.xml.soap.Node
detachNode, getParentElement, getValue, recycleNode, setParentElement, setValue
Methods inherited from interface org.w3c.dom.Text
getWholeText, isElementContentWhitespace, replaceWholeText, splitText
Methods inherited from interface org.w3c.dom.CharacterData
appendData, deleteData, getData, getLength, insertData, replaceData, setData, substringData
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

isComment

boolean isComment()
Retrieves whether this Text object represents a comment.

Returns:
true if this Text object is a comment; false otherwise
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


stream

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.stream

Interface Summary
EventFilter | This interface declares a simple filter interface that one can create to filter XMLEventReaders
Location | Provides information on the location of an event.
StreamFilter | This interface declares a simple filter interface that one can create to filter XMLStreamReaders
XMLEventReader | This is the top level interface for parsing XML Events.
XMLEventWriter | This is the top level interface for writing XML documents.
XMLReporter | This interface is used to report non-fatal errors.
XMLResolver | This interface is used to resolve resources during an XML parse.
XMLStreamConstants | This interface declares the constants used in this API.
XMLStreamReader | The XMLStreamReader interface allows forward, read-only access to XML.
XMLStreamWriter | The XMLStreamWriter interface specifies how to write XML.

Class Summary
XMLEventFactory | This interface defines a utility class for creating instances of XMLEvents
XMLInputFactory | Defines an abstract implementation of a factory for getting streams.
XMLOutputFactory | Defines an abstract implementation of a factory for getting XMLEventWriters and XMLStreamWriters.

Exception Summary
XMLStreamException The base exception for unexpected processing errors.

Error Summary
FactoryConfigurationError An error class for reporting factory configuration errors.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.stream Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.stream

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Error
        • javax.xml.stream.FactoryConfigurationError
      • java.lang.Exception
        • javax.xml.stream.XMLStreamException
    • javax.xml.stream.XMLEventFactory
    • javax.xml.stream.XMLInputFactory
    • javax.xml.stream.XMLOutputFactory

Interface Hierarchy

  • javax.xml.stream.EventFilter
  • java.util.Iterator<E>
    • javax.xml.stream.XMLEventReader
  • javax.xml.stream.Location
  • javax.xml.stream.StreamFilter
  • javax.xml.stream.util.XMLEventConsumer
    • javax.xml.stream.XMLEventWriter
  • javax.xml.stream.XMLReporter
  • javax.xml.stream.XMLResolver
  • javax.xml.stream.XMLStreamConstants
    • javax.xml.stream.XMLStreamReader
  • javax.xml.stream.XMLStreamWriter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.stream

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.stream

Packages that use javax.xml.stream
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.stream |
javax.xml.stream.events |
javax.xml.stream.util |
javax.xml.transform.stax | Provides for StAX-specific transformation APIs.

Classes in javax.xml.stream used by javax.xml.bind
XMLEventReader
This is the top level interface for parsing XML Events.
XMLEventWriter
This is the top level interface for writing XML documents.
XMLStreamReader
The XMLStreamReader interface allows forward, read-only access to XML.
XMLStreamWriter
The XMLStreamWriter interface specifies how to write XML.

Classes in javax.xml.stream used by javax.xml.bind.helpers
XMLEventReader
This is the top level interface for parsing XML Events.
XMLEventWriter
This is the top level interface for writing XML documents.
XMLStreamReader
The XMLStreamReader interface allows forward, read-only access to XML.
XMLStreamWriter
The XMLStreamWriter interface specifies how to write XML.

Classes in javax.xml.stream used by javax.xml.stream
EventFilter
This interface declares a simple filter interface that one can create to filter XMLEventReaders
FactoryConfigurationError
An error class for reporting factory configuration errors.
Location
Provides information on the location of an event.
StreamFilter
This interface declares a simple filter interface that one can create to filter XMLStreamReaders
XMLEventFactory
This interface defines a utility class for creating instances of XMLEvents
XMLEventReader
This is the top level interface for parsing XML Events.
XMLEventWriter
This is the top level interface for writing XML documents.
XMLInputFactory
Defines an abstract implementation of a factory for getting streams.
XMLOutputFactory
Defines an abstract implementation of a factory for getting XMLEventWriters and XMLStreamWriters.
XMLReporter
This interface is used to report non-fatal errors.
XMLResolver
This interface is used to resolve resources during an XML parse.
XMLStreamConstants
This interface declares the constants used in this API.
XMLStreamException
The base exception for unexpected processing errors.
XMLStreamReader
The XMLStreamReader interface allows forward, read-only access to XML.
XMLStreamWriter
The XMLStreamWriter interface specifies how to write XML.

Classes in javax.xml.stream used by javax.xml.stream.events
Location
Provides information on the location of an event.
XMLStreamConstants
This interface declares the constants used in this API.
XMLStreamException
The base exception for unexpected processing errors.

Classes in javax.xml.stream used by javax.xml.stream.util
Location
Provides information on the location of an event.
XMLEventReader
This is the top level interface for parsing XML Events.
XMLStreamConstants
This interface declares the constants used in this API.
XMLStreamException
The base exception for unexpected processing errors.
XMLStreamReader
The XMLStreamReader interface allows forward, read-only access to XML.

Classes in javax.xml.stream used by javax.xml.transform.stax
XMLEventReader
This is the top level interface for parsing XML Events.
XMLEventWriter
This is the top level interface for writing XML documents.
XMLStreamException
The base exception for unexpected processing errors.
XMLStreamReader
The XMLStreamReader interface allows forward, read-only access to XML.
XMLStreamWriter
The XMLStreamWriter interface specifies how to write XML.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.stream.FactoryConfigurationError

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.stream.FactoryConfigurationError

Packages that use FactoryConfigurationError
javax.xml.stream

Uses of FactoryConfigurationError in javax.xml.stream

Methods in javax.xml.stream that throw FactoryConfigurationError
static XMLOutputFactory | XMLOutputFactory.newInstance() Create a new instance of the factory.
static XMLInputFactory | XMLInputFactory.newInstance() Create a new instance of the factory.
static XMLEventFactory | XMLEventFactory.newInstance() Create a new instance of the factory
static XMLInputFactory | XMLOutputFactory.newInstance(String factoryId, ClassLoader classLoader) Create a new instance of the factory.
static XMLInputFactory | XMLInputFactory.newInstance(String factoryId, ClassLoader classLoader) Create a new instance of the factory
static XMLEventFactory | XMLEventFactory.newInstance(String factoryId, ClassLoader classLoader) Create a new instance of the factory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.stream.XMLEventFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.stream.XMLEventFactory

Packages that use XMLEventFactory
javax.xml.stream

Uses of XMLEventFactory in javax.xml.stream

Methods in javax.xml.stream that return XMLEventFactory
static XMLEventFactory | XMLEventFactory.newInstance() Create a new instance of the factory
static XMLEventFactory | XMLEventFactory.newInstance(String factoryId, ClassLoader classLoader) Create a new instance of the factory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.stream.XMLInputFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.stream.XMLInputFactory

Packages that use XMLInputFactory
javax.xml.stream

Uses of XMLInputFactory in javax.xml.stream

Methods in javax.xml.stream that return XMLInputFactory
static XMLInputFactory | XMLInputFactory.newInstance() Create a new instance of the factory.
static XMLInputFactory | XMLOutputFactory.newInstance(String factoryId, ClassLoader classLoader) Create a new instance of the factory.
static XMLInputFactory | XMLInputFactory.newInstance(String factoryId, ClassLoader classLoader) Create a new instance of the factory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.stream.XMLOutputFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.stream.XMLOutputFactory

Packages that use XMLOutputFactory
javax.xml.stream

Uses of XMLOutputFactory in javax.xml.stream

Methods in javax.xml.stream that return XMLOutputFactory
static XMLOutputFactory XMLOutputFactory.newInstance()
Create a new instance of the factory.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.stream.XMLStreamException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.stream.XMLStreamException

Packages that use XMLStreamException
javax.xml.stream |
javax.xml.stream.events |
javax.xml.stream.util |
javax.xml.transform.stax | Provides for StAX-specific transformation APIs.

Uses of XMLStreamException in javax.xml.stream

Methods in javax.xml.stream that throw XMLStreamException
 void XMLEventWriter.add(XMLEvent event)
Add an event to the output stream Adding a START_ELEMENT will open a new namespace scope that will be closed when the corresponding END_ELEMENT is written.
 void XMLEventWriter.add(XMLEventReader reader)
Adds an entire stream to an output stream, calls next() on the inputStream argument until hasNext() returns false This should be treated as a convenience method that will perform the following loop over all the events in an event reader and call add on each event.
 void XMLEventWriter.close()
Frees any resources associated with this stream
 void XMLStreamWriter.close()
Close this writer and free any resources associated with the writer.
 void XMLEventReader.close()
Frees any resources associated with this Reader.
 void XMLStreamReader.close()
Frees any resources associated with this Reader.
abstract  XMLEventReader XMLInputFactory.createFilteredReader(XMLEventReader reader, EventFilter filter)
Create a filtered event reader that wraps the filter around the event reader
abstract  XMLStreamReader XMLInputFactory.createFilteredReader(XMLStreamReader reader, StreamFilter filter)
Create a filtered reader that wraps the filter around the reader
abstract  XMLEventReader XMLInputFactory.createXMLEventReader(InputStream stream)
Create a new XMLEventReader from a java.io.InputStream
abstract  XMLEventReader XMLInputFactory.createXMLEventReader(InputStream stream, String encoding)
Create a new XMLEventReader from a java.io.InputStream
abstract  XMLEventReader XMLInputFactory.createXMLEventReader(Reader reader)
Create a new XMLEventReader from a reader
abstract  XMLEventReader XMLInputFactory.createXMLEventReader(Source source)
Create a new XMLEventReader from a JAXP source.
abstract  XMLEventReader XMLInputFactory.createXMLEventReader(String systemId, InputStream stream)
Create a new XMLEventReader from a java.io.InputStream
abstract  XMLEventReader XMLInputFactory.createXMLEventReader(String systemId, Reader reader)
Create a new XMLEventReader from a reader
abstract  XMLEventReader XMLInputFactory.createXMLEventReader(XMLStreamReader reader)
Create a new XMLEventReader from an XMLStreamReader.
abstract  XMLEventWriter XMLOutputFactory.createXMLEventWriter(OutputStream stream)
Create a new XMLEventWriter that writes to a stream
abstract  XMLEventWriter XMLOutputFactory.createXMLEventWriter(OutputStream stream, String encoding)
Create a new XMLEventWriter that writes to a stream
abstract  XMLEventWriter XMLOutputFactory.createXMLEventWriter(Result result)
Create a new XMLEventWriter that writes to a JAXP result.
abstract  XMLEventWriter XMLOutputFactory.createXMLEventWriter(Writer stream)
Create a new XMLEventWriter that writes to a writer
abstract  XMLStreamReader XMLInputFactory.createXMLStreamReader(InputStream stream)
Create a new XMLStreamReader from a java.io.InputStream
abstract  XMLStreamReader XMLInputFactory.createXMLStreamReader(InputStream stream, String encoding)
Create a new XMLStreamReader from a java.io.InputStream
abstract  XMLStreamReader XMLInputFactory.createXMLStreamReader(Reader reader)
Create a new XMLStreamReader from a reader
abstract  XMLStreamReader XMLInputFactory.createXMLStreamReader(Source source)
Create a new XMLStreamReader from a JAXP source.
abstract  XMLStreamReader XMLInputFactory.createXMLStreamReader(String systemId, InputStream stream)
Create a new XMLStreamReader from a java.io.InputStream
abstract  XMLStreamReader XMLInputFactory.createXMLStreamReader(String systemId, Reader reader)
Create a new XMLStreamReader from a java.io.InputStream
abstract  XMLStreamWriter XMLOutputFactory.createXMLStreamWriter(OutputStream stream)
Create a new XMLStreamWriter that writes to a stream
abstract  XMLStreamWriter XMLOutputFactory.createXMLStreamWriter(OutputStream stream, String encoding)
Create a new XMLStreamWriter that writes to a stream
abstract  XMLStreamWriter XMLOutputFactory.createXMLStreamWriter(Result result)
Create a new XMLStreamWriter that writes to a JAXP result.
abstract  XMLStreamWriter XMLOutputFactory.createXMLStreamWriter(Writer stream)
Create a new XMLStreamWriter that writes to a writer
 void XMLEventWriter.flush()
Writes any cached events to the underlying output mechanism
 void XMLStreamWriter.flush()
Write any cached data to the underlying output mechanism.
 String XMLEventReader.getElementText()
Reads the content of a text-only element.
 String XMLStreamReader.getElementText()
Reads the content of a text-only element, an exception is thrown if this is not a text-only element.
 String XMLEventWriter.getPrefix(String uri)
Gets the prefix the uri is bound to
 String XMLStreamWriter.getPrefix(String uri)
Gets the prefix the uri is bound to
 int XMLStreamReader.getTextCharacters(int sourceStart, char[] target, int targetStart, int length)
Gets the the text associated with a CHARACTERS, SPACE or CDATA event.
 boolean XMLStreamReader.hasNext()
Returns true if there are more parsing events and false if there are no more events.
 int XMLStreamReader.next()
Get next parsing event - a processor may return all contiguous character data in a single chunk, or it may split it into several chunks.
 XMLEvent XMLEventReader.nextEvent()
Get the next XMLEvent
 XMLEvent XMLEventReader.nextTag()
Skips any insignificant space events until a START_ELEMENT or END_ELEMENT is reached.
 int XMLStreamReader.nextTag()
Skips any white space (isWhiteSpace() returns true), COMMENT, or PROCESSING_INSTRUCTION, until a START_ELEMENT or END_ELEMENT is reached.
 XMLEvent XMLEventReader.peek()
Check the next XMLEvent without reading it from the stream.
 void XMLReporter.report(String message, String errorType, Object relatedInformation, Location location)
Report the desired message in an application specific format.
 void XMLStreamReader.require(int type, String namespaceURI, String localName)
Test if the current event is of the given type and if the namespace and name match the current namespace and name of the current event.
 Object XMLResolver.resolveEntity(String publicID, String systemID, String baseURI, String namespace)
Retrieves a resource.
 void XMLEventWriter.setDefaultNamespace(String uri)
Binds a URI to the default namespace This URI is bound in the scope of the current START_ELEMENT / END_ELEMENT pair.
 void XMLStreamWriter.setDefaultNamespace(String uri)
Binds a URI to the default namespace This URI is bound in the scope of the current START_ELEMENT / END_ELEMENT pair.
 void XMLEventWriter.setNamespaceContext(NamespaceContext context)
Sets the current namespace context for prefix and uri bindings.
 void XMLStreamWriter.setNamespaceContext(NamespaceContext context)
Sets the current namespace context for prefix and uri bindings.
 void XMLEventWriter.setPrefix(String prefix, String uri)
Sets the prefix the uri is bound to.
 void XMLStreamWriter.setPrefix(String prefix, String uri)
Sets the prefix the uri is bound to.
 void XMLStreamWriter.writeAttribute(String localName, String value)
Writes an attribute to the output stream without a prefix.
 void XMLStreamWriter.writeAttribute(String namespaceURI, String localName, String value)
Writes an attribute to the output stream
 void XMLStreamWriter.writeAttribute(String prefix, String namespaceURI, String localName, String value)
Writes an attribute to the output stream
 void XMLStreamWriter.writeCData(String data)
Writes a CData section
 void XMLStreamWriter.writeCharacters(char[] text, int start, int len)
Write text to the output
 void XMLStreamWriter.writeCharacters(String text)
Write text to the output
 void XMLStreamWriter.writeComment(String data)
Writes an xml comment with the data enclosed
 void XMLStreamWriter.writeDefaultNamespace(String namespaceURI)
Writes the default namespace to the stream
 void XMLStreamWriter.writeDTD(String dtd)
Write a DTD section.
 void XMLStreamWriter.writeEmptyElement(String localName)
Writes an empty element tag to the output
 void XMLStreamWriter.writeEmptyElement(String namespaceURI, String localName)
Writes an empty element tag to the output
 void XMLStreamWriter.writeEmptyElement(String prefix, String localName, String namespaceURI)
Writes an empty element tag to the output
 void XMLStreamWriter.writeEndDocument()
Closes any start tags and writes corresponding end tags.
 void XMLStreamWriter.writeEndElement()
Writes an end tag to the output relying on the internal state of the writer to determine the prefix and local name of the event.
 void XMLStreamWriter.writeEntityRef(String name)
Writes an entity reference
 void XMLStreamWriter.writeNamespace(String prefix, String namespaceURI)
Writes a namespace to the output stream If the prefix argument to this method is the empty string, "xmlns", or null this method will delegate to writeDefaultNamespace
 void XMLStreamWriter.writeProcessingInstruction(String target)
Writes a processing instruction
 void XMLStreamWriter.writeProcessingInstruction(String target, String data)
Writes a processing instruction
 void XMLStreamWriter.writeStartDocument()
Write the XML Declaration.
 void XMLStreamWriter.writeStartDocument(String version)
Write the XML Declaration.
 void XMLStreamWriter.writeStartDocument(String encoding, String version)
Write the XML Declaration.
 void XMLStreamWriter.writeStartElement(String localName)
Writes a start tag to the output.
 void XMLStreamWriter.writeStartElement(String namespaceURI, String localName)
Writes a start tag to the output
 void XMLStreamWriter.writeStartElement(String prefix, String localName, String namespaceURI)
Writes a start tag to the output

Uses of XMLStreamException in javax.xml.stream.events

Methods in javax.xml.stream.events that throw XMLStreamException
 void XMLEvent.writeAsEncodedUnicode(Writer writer)
This method will write the XMLEvent as per the XML 1.0 specification as Unicode characters.

Uses of XMLStreamException in javax.xml.stream.util

Methods in javax.xml.stream.util that throw XMLStreamException
void | XMLEventConsumer.add(XMLEvent event) This method adds an event to the consumer.
XMLEvent | XMLEventAllocator.allocate(XMLStreamReader reader) This method allocates an event given the current state of the XMLStreamReader.
void | XMLEventAllocator.allocate(XMLStreamReader reader, XMLEventConsumer consumer) This method allocates an event or set of events given the current state of the XMLStreamReader and adds the event or set of events to the consumer that was passed in.
void | StreamReaderDelegate.close()
void | EventReaderDelegate.close()
String | StreamReaderDelegate.getElementText()
String | EventReaderDelegate.getElementText()
int | StreamReaderDelegate.getTextCharacters(int sourceStart, char[] target, int targetStart, int length)
boolean | StreamReaderDelegate.hasNext()
int | StreamReaderDelegate.next()
XMLEvent | EventReaderDelegate.nextEvent()
int | StreamReaderDelegate.nextTag()
XMLEvent | EventReaderDelegate.nextTag()
XMLEvent | EventReaderDelegate.peek()
void | StreamReaderDelegate.require(int type, String namespaceURI, String localName)

Uses of XMLStreamException in javax.xml.transform.stax

Constructors in javax.xml.transform.stax that throw XMLStreamException
StAXSource(XMLEventReader xmlEventReader)
Creates a new instance of a StAXSource by supplying an XMLEventReader.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.EventFilter

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.EventFilter

Packages that use EventFilter
javax.xml.stream

Uses of EventFilter in javax.xml.stream

Methods in javax.xml.stream with parameters of type EventFilter
abstract  XMLEventReader XMLInputFactory.createFilteredReader(XMLEventReader reader, EventFilter filter)
Create a filtered event reader that wraps the filter around the event reader

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.Location

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.Location

Packages that use Location
javax.xml.stream
javax.xml.stream.events
javax.xml.stream.util

Uses of Location in javax.xml.stream

Fields in javax.xml.stream declared as Location
protected  Location XMLStreamException.location

Methods in javax.xml.stream that return Location
Location | XMLStreamException.getLocation() Gets the location of the exception
Location | XMLStreamReader.getLocation() Return the current location of the processor.

Methods in javax.xml.stream with parameters of type Location
void | XMLReporter.report(String message, String errorType, Object relatedInformation, Location location) Report the desired message in an application specific format.
abstract void | XMLEventFactory.setLocation(Location location) This method allows setting of the Location on each event that is created by this factory.

Constructors in javax.xml.stream with parameters of type Location
XMLStreamException(String msg, Location location)
Construct an exception with the assocated message, exception and location.
XMLStreamException(String msg, Location location, Throwable th)
Construct an exception with the assocated message, exception and location.

Uses of Location in javax.xml.stream.events

Methods in javax.xml.stream.events that return Location
 Location XMLEvent.getLocation()
Return the location of this event.

Uses of Location in javax.xml.stream.util

Methods in javax.xml.stream.util that return Location
 Location StreamReaderDelegate.getLocation()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.StreamFilter

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.StreamFilter

Packages that use StreamFilter
javax.xml.stream

Uses of StreamFilter in javax.xml.stream

Methods in javax.xml.stream with parameters of type StreamFilter
abstract  XMLStreamReader XMLInputFactory.createFilteredReader(XMLStreamReader reader, StreamFilter filter)
Create a filtered reader that wraps the filter around the reader

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.XMLEventReader

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.XMLEventReader

Packages that use XMLEventReader
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.stream |
javax.xml.stream.util |
javax.xml.transform.stax | Provides for StAX-specific transformation APIs.

Uses of XMLEventReader in javax.xml.bind

Methods in javax.xml.bind with parameters of type XMLEventReader
 Object Unmarshaller.unmarshal(XMLEventReader reader)
Unmarshal XML data from the specified pull parser and return the resulting content tree.
<T> JAXBElement<T>
Unmarshaller.unmarshal(XMLEventReader reader, Class<T> declaredType)
Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.

Uses of XMLEventReader in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers with parameters of type XMLEventReader
 Object AbstractUnmarshallerImpl.unmarshal(XMLEventReader reader)
<T> JAXBElement<T>
AbstractUnmarshallerImpl.unmarshal(XMLEventReader reader, Class<T> expectedType)

Uses of XMLEventReader in javax.xml.stream

Methods in javax.xml.stream that return XMLEventReader
abstract XMLEventReader | XMLInputFactory.createFilteredReader(XMLEventReader reader, EventFilter filter) Create a filtered event reader that wraps the filter around the event reader
abstract XMLEventReader | XMLInputFactory.createXMLEventReader(InputStream stream) Create a new XMLEventReader from a java.io.InputStream
abstract XMLEventReader | XMLInputFactory.createXMLEventReader(InputStream stream, String encoding) Create a new XMLEventReader from a java.io.InputStream
abstract XMLEventReader | XMLInputFactory.createXMLEventReader(Reader reader) Create a new XMLEventReader from a reader
abstract XMLEventReader | XMLInputFactory.createXMLEventReader(Source source) Create a new XMLEventReader from a JAXP source.
abstract XMLEventReader | XMLInputFactory.createXMLEventReader(String systemId, InputStream stream) Create a new XMLEventReader from a java.io.InputStream
abstract XMLEventReader | XMLInputFactory.createXMLEventReader(String systemId, Reader reader) Create a new XMLEventReader from a reader
abstract XMLEventReader | XMLInputFactory.createXMLEventReader(XMLStreamReader reader) Create a new XMLEventReader from an XMLStreamReader.

Methods in javax.xml.stream with parameters of type XMLEventReader
 void XMLEventWriter.add(XMLEventReader reader)
Adds an entire stream to an output stream, calls next() on the inputStream argument until hasNext() returns false This should be treated as a convenience method that will perform the following loop over all the events in an event reader and call add on each event.
abstract  XMLEventReader XMLInputFactory.createFilteredReader(XMLEventReader reader, EventFilter filter)
Create a filtered event reader that wraps the filter around the event reader

Uses of XMLEventReader in javax.xml.stream.util

Classes in javax.xml.stream.util that implement XMLEventReader
 class EventReaderDelegate
This is the base class for deriving an XMLEventReader filter.

Methods in javax.xml.stream.util that return XMLEventReader
 XMLEventReader EventReaderDelegate.getParent()
Get the parent of this instance.

Methods in javax.xml.stream.util with parameters of type XMLEventReader
 void EventReaderDelegate.setParent(XMLEventReader reader)
Set the parent of this instance.

Constructors in javax.xml.stream.util with parameters of type XMLEventReader
EventReaderDelegate(XMLEventReader reader)
Construct an filter with the specified parent.

Uses of XMLEventReader in javax.xml.transform.stax

Methods in javax.xml.transform.stax that return XMLEventReader
 XMLEventReader StAXSource.getXMLEventReader()
Get the XMLEventReader used by this StAXSource.

Constructors in javax.xml.transform.stax with parameters of type XMLEventReader
StAXSource(XMLEventReader xmlEventReader)
Creates a new instance of a StAXSource by supplying an XMLEventReader.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.XMLEventWriter

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.XMLEventWriter

Packages that use XMLEventWriter
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.stream |
javax.xml.transform.stax | Provides for StAX-specific transformation APIs.

Uses of XMLEventWriter in javax.xml.bind

Methods in javax.xml.bind with parameters of type XMLEventWriter
 void Marshaller.marshal(Object jaxbElement, XMLEventWriter writer)
Marshal the content tree rooted at jaxbElement into a XMLEventWriter.

Uses of XMLEventWriter in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers with parameters of type XMLEventWriter
 void AbstractMarshallerImpl.marshal(Object obj, XMLEventWriter writer)

Uses of XMLEventWriter in javax.xml.stream

Methods in javax.xml.stream that return XMLEventWriter
abstract XMLEventWriter | XMLOutputFactory.createXMLEventWriter(OutputStream stream) Create a new XMLEventWriter that writes to a stream
abstract XMLEventWriter | XMLOutputFactory.createXMLEventWriter(OutputStream stream, String encoding) Create a new XMLEventWriter that writes to a stream
abstract XMLEventWriter | XMLOutputFactory.createXMLEventWriter(Result result) Create a new XMLEventWriter that writes to a JAXP result.
abstract XMLEventWriter | XMLOutputFactory.createXMLEventWriter(Writer stream) Create a new XMLEventWriter that writes to a writer

Uses of XMLEventWriter in javax.xml.transform.stax

Methods in javax.xml.transform.stax that return XMLEventWriter
 XMLEventWriter StAXResult.getXMLEventWriter()
Get the XMLEventWriter used by this StAXResult.

Constructors in javax.xml.transform.stax with parameters of type XMLEventWriter
StAXResult(XMLEventWriter xmlEventWriter)
Creates a new instance of a StAXResult by supplying an XMLEventWriter.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.XMLReporter

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.XMLReporter

Packages that use XMLReporter
javax.xml.stream

Uses of XMLReporter in javax.xml.stream

Methods in javax.xml.stream that return XMLReporter
abstract  XMLReporter XMLInputFactory.getXMLReporter()
The reporter that will be set on any XMLStreamReader or XMLEventReader created by this factory instance.

Methods in javax.xml.stream with parameters of type XMLReporter
abstract  void XMLInputFactory.setXMLReporter(XMLReporter reporter)
The reporter that will be set on any XMLStreamReader or XMLEventReader created by this factory instance.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.XMLResolver

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.XMLResolver

Packages that use XMLResolver
javax.xml.stream

Uses of XMLResolver in javax.xml.stream

Methods in javax.xml.stream that return XMLResolver
abstract  XMLResolver XMLInputFactory.getXMLResolver()
The resolver that will be set on any XMLStreamReader or XMLEventReader created by this factory instance.

Methods in javax.xml.stream with parameters of type XMLResolver
abstract  void XMLInputFactory.setXMLResolver(XMLResolver resolver)
The resolver that will be set on any XMLStreamReader or XMLEventReader created by this factory instance.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.XMLStreamConstants

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.XMLStreamConstants

Packages that use XMLStreamConstants
javax.xml.stream
javax.xml.stream.events
javax.xml.stream.util

Uses of XMLStreamConstants in javax.xml.stream

Subinterfaces of XMLStreamConstants in javax.xml.stream
 interface XMLStreamReader
The XMLStreamReader interface allows forward, read-only access to XML.

Uses of XMLStreamConstants in javax.xml.stream.events

Subinterfaces of XMLStreamConstants in javax.xml.stream.events
interface | Attribute An interface that contains information about an attribute.
interface | Characters This describes the interface to Characters events.
interface | Comment An interface for comment events
interface | DTD This is the top level interface for events dealing with DTDs
interface | EndDocument A marker interface for the end of the document
interface | EndElement An interface for the end element event.
interface | EntityDeclaration An interface for handling Entity Declarations This interface is used to record and report unparsed entity declarations.
interface | EntityReference An interface for handling Entity events.
interface | Namespace An interface that contains information about a namespace.
interface | NotationDeclaration An interface for handling Notation Declarations Receive notification of a notation declaration event.
interface | ProcessingInstruction An interface that describes the data found in processing instructions
interface | StartDocument An interface for the start document event
interface | StartElement The StartElement interface provides access to information about start elements.
interface | XMLEvent This is the base event interface for handling markup events.

Uses of XMLStreamConstants in javax.xml.stream.util

Classes in javax.xml.stream.util that implement XMLStreamConstants
 class StreamReaderDelegate
This is the base class for deriving an XMLStreamReader filter This class is designed to sit between an XMLStreamReader and an application's XMLStreamReader.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.XMLStreamReader

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.XMLStreamReader

Packages that use XMLStreamReader
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.stream |
javax.xml.stream.util |
javax.xml.transform.stax | Provides for StAX-specific transformation APIs.

Uses of XMLStreamReader in javax.xml.bind

Methods in javax.xml.bind with parameters of type XMLStreamReader
 Object Unmarshaller.unmarshal(XMLStreamReader reader)
Unmarshal XML data from the specified pull parser and return the resulting content tree.
<T> JAXBElement<T>
Unmarshaller.unmarshal(XMLStreamReader reader, Class<T> declaredType)
Unmarshal root element to JAXB mapped declaredType and return the resulting content tree.

Uses of XMLStreamReader in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers with parameters of type XMLStreamReader
 Object AbstractUnmarshallerImpl.unmarshal(XMLStreamReader reader)
<T> JAXBElement<T>
AbstractUnmarshallerImpl.unmarshal(XMLStreamReader reader, Class<T> expectedType)

Uses of XMLStreamReader in javax.xml.stream

Methods in javax.xml.stream that return XMLStreamReader
abstract XMLStreamReader | XMLInputFactory.createFilteredReader(XMLStreamReader reader, StreamFilter filter) Create a filtered reader that wraps the filter around the reader
abstract XMLStreamReader | XMLInputFactory.createXMLStreamReader(InputStream stream) Create a new XMLStreamReader from a java.io.InputStream
abstract XMLStreamReader | XMLInputFactory.createXMLStreamReader(InputStream stream, String encoding) Create a new XMLStreamReader from a java.io.InputStream
abstract XMLStreamReader | XMLInputFactory.createXMLStreamReader(Reader reader) Create a new XMLStreamReader from a reader
abstract XMLStreamReader | XMLInputFactory.createXMLStreamReader(Source source) Create a new XMLStreamReader from a JAXP source.
abstract XMLStreamReader | XMLInputFactory.createXMLStreamReader(String systemId, InputStream stream) Create a new XMLStreamReader from a java.io.InputStream
abstract XMLStreamReader | XMLInputFactory.createXMLStreamReader(String systemId, Reader reader) Create a new XMLStreamReader from a java.io.InputStream

Methods in javax.xml.stream with parameters of type XMLStreamReader
boolean | StreamFilter.accept(XMLStreamReader reader) Tests whether the current state is part of this stream.
abstract XMLStreamReader | XMLInputFactory.createFilteredReader(XMLStreamReader reader, StreamFilter filter) Create a filtered reader that wraps the filter around the reader
abstract XMLEventReader | XMLInputFactory.createXMLEventReader(XMLStreamReader reader) Create a new XMLEventReader from an XMLStreamReader.

Uses of XMLStreamReader in javax.xml.stream.util

Classes in javax.xml.stream.util that implement XMLStreamReader
 class StreamReaderDelegate
This is the base class for deriving an XMLStreamReader filter This class is designed to sit between an XMLStreamReader and an application's XMLStreamReader.

Methods in javax.xml.stream.util that return XMLStreamReader
 XMLStreamReader StreamReaderDelegate.getParent()
Get the parent of this instance.

Methods in javax.xml.stream.util with parameters of type XMLStreamReader
XMLEvent | XMLEventAllocator.allocate(XMLStreamReader reader) This method allocates an event given the current state of the XMLStreamReader.
void | XMLEventAllocator.allocate(XMLStreamReader reader, XMLEventConsumer consumer) This method allocates an event or set of events given the current state of the XMLStreamReader and adds the event or set of events to the consumer that was passed in.
void | StreamReaderDelegate.setParent(XMLStreamReader reader) Set the parent of this instance.

Constructors in javax.xml.stream.util with parameters of type XMLStreamReader
StreamReaderDelegate(XMLStreamReader reader)
Construct an filter with the specified parent.

Uses of XMLStreamReader in javax.xml.transform.stax

Methods in javax.xml.transform.stax that return XMLStreamReader
 XMLStreamReader StAXSource.getXMLStreamReader()
Get the XMLStreamReader used by this StAXSource.

Constructors in javax.xml.transform.stax with parameters of type XMLStreamReader
StAXSource(XMLStreamReader xmlStreamReader)
Creates a new instance of a StAXSource by supplying an XMLStreamReader.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.XMLStreamWriter

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.XMLStreamWriter

Packages that use XMLStreamWriter
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.stream |
javax.xml.transform.stax | Provides for StAX-specific transformation APIs.

Uses of XMLStreamWriter in javax.xml.bind

Methods in javax.xml.bind with parameters of type XMLStreamWriter
 void Marshaller.marshal(Object jaxbElement, XMLStreamWriter writer)
Marshal the content tree rooted at jaxbElement into a XMLStreamWriter.

Uses of XMLStreamWriter in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers with parameters of type XMLStreamWriter
 void AbstractMarshallerImpl.marshal(Object obj, XMLStreamWriter writer)

Uses of XMLStreamWriter in javax.xml.stream

Methods in javax.xml.stream that return XMLStreamWriter
abstract XMLStreamWriter | XMLOutputFactory.createXMLStreamWriter(OutputStream stream) Create a new XMLStreamWriter that writes to a stream
abstract XMLStreamWriter | XMLOutputFactory.createXMLStreamWriter(OutputStream stream, String encoding) Create a new XMLStreamWriter that writes to a stream
abstract XMLStreamWriter | XMLOutputFactory.createXMLStreamWriter(Result result) Create a new XMLStreamWriter that writes to a JAXP result.
abstract XMLStreamWriter | XMLOutputFactory.createXMLStreamWriter(Writer stream) Create a new XMLStreamWriter that writes to a writer

Uses of XMLStreamWriter in javax.xml.transform.stax

Methods in javax.xml.transform.stax that return XMLStreamWriter
 XMLStreamWriter StAXResult.getXMLStreamWriter()
Get the XMLStreamWriter used by this StAXResult.

Constructors in javax.xml.transform.stax with parameters of type XMLStreamWriter
StAXResult(XMLStreamWriter xmlStreamWriter)
Creates a new instance of a StAXResult by supplying an XMLStreamWriter.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


EventFilter

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream
Interface EventFilter

public interface EventFilter

This interface declares a simple filter interface that one can create to filter XMLEventReaders

Since:
1.6

Method Summary
 boolean accept(XMLEvent event)
Tests whether this event is part of this stream.

Method Detail

accept

boolean accept(XMLEvent event)
Tests whether this event is part of this stream. This method will return true if this filter accepts this event and false otherwise.

Parameters:
event - the event to test
Returns:
true if this filter accepts this event, false otherwise
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


events

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.stream.events

Interface Summary
Attribute | An interface that contains information about an attribute.
Characters | This describes the interface to Characters events.
Comment | An interface for comment events
DTD | This is the top level interface for events dealing with DTDs
EndDocument | A marker interface for the end of the document
EndElement | An interface for the end element event.
EntityDeclaration | An interface for handling Entity Declarations This interface is used to record and report unparsed entity declarations.
EntityReference | An interface for handling Entity events.
Namespace | An interface that contains information about a namespace.
NotationDeclaration | An interface for handling Notation Declarations Receive notification of a notation declaration event.
ProcessingInstruction | An interface that describes the data found in processing instructions
StartDocument | An interface for the start document event
StartElement | The StartElement interface provides access to information about start elements.
XMLEvent | This is the base event interface for handling markup events.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


EndDocument

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.events
Interface EndDocument

All Superinterfaces:
XMLEvent, XMLStreamConstants
public interface EndDocument
extends XMLEvent

A marker interface for the end of the document

Since:
1.6

Field Summary
Fields inherited from interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
Method Summary
Methods inherited from interface javax.xml.stream.events.XMLEvent
asCharacters, asEndElement, asStartElement, getEventType, getLocation, getSchemaType, isAttribute, isCharacters, isEndDocument, isEndElement, isEntityReference, isNamespace, isProcessingInstruction, isStartDocument, isStartElement, writeAsEncodedUnicode

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


javax.xml.stream.events Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.stream.events

Package Hierarchies:
All Packages

Interface Hierarchy

  • javax.xml.stream.XMLStreamConstants
    • javax.xml.stream.events.XMLEvent
      • javax.xml.stream.events.Attribute
        • javax.xml.stream.events.Namespace
      • javax.xml.stream.events.Characters
      • javax.xml.stream.events.Comment
      • javax.xml.stream.events.DTD
      • javax.xml.stream.events.EndDocument
      • javax.xml.stream.events.EndElement
      • javax.xml.stream.events.EntityDeclaration
      • javax.xml.stream.events.EntityReference
      • javax.xml.stream.events.NotationDeclaration
      • javax.xml.stream.events.ProcessingInstruction
      • javax.xml.stream.events.StartDocument
      • javax.xml.stream.events.StartElement
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.stream.events

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.stream.events

Packages that use javax.xml.stream.events
javax.xml.stream
javax.xml.stream.events
javax.xml.stream.util

Classes in javax.xml.stream.events used by javax.xml.stream
Attribute
An interface that contains information about an attribute.
Characters
This describes the interface to Characters events.
Comment
An interface for comment events
DTD
This is the top level interface for events dealing with DTDs
EndDocument
A marker interface for the end of the document
EndElement
An interface for the end element event.
EntityDeclaration
An interface for handling Entity Declarations This interface is used to record and report unparsed entity declarations.
EntityReference
An interface for handling Entity events.
Namespace
An interface that contains information about a namespace.
ProcessingInstruction
An interface that describes the data found in processing instructions
StartDocument
An interface for the start document event
StartElement
The StartElement interface provides access to information about start elements.
XMLEvent
This is the base event interface for handling markup events.

Classes in javax.xml.stream.events used by javax.xml.stream.events
Attribute
An interface that contains information about an attribute.
Characters
This describes the interface to Characters events.
EndElement
An interface for the end element event.
EntityDeclaration
An interface for handling Entity Declarations This interface is used to record and report unparsed entity declarations.
StartElement
The StartElement interface provides access to information about start elements.
XMLEvent
This is the base event interface for handling markup events.

Classes in javax.xml.stream.events used by javax.xml.stream.util
XMLEvent
This is the base event interface for handling markup events.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Attribute

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.events
Interface Attribute

All Superinterfaces:
XMLEvent, XMLStreamConstants
All Known Subinterfaces:
Namespace
public interface Attribute
extends XMLEvent

An interface that contains information about an attribute. Attributes are reported as a set of events accessible from a StartElement. Other applications may report Attributes as first-order events, for example as the results of an XPath expression.

Since:
1.6
See Also:
StartElement

Field Summary
Fields inherited from interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
Method Summary
String | getDTDType() Gets the type of this attribute, default is the String "CDATA"
QName | getName() Returns the QName for this attribute
String | getValue() Gets the normalized value of this attribute
boolean | isSpecified() A flag indicating whether this attribute was actually specified in the start-tag of its element, or was defaulted from the schema.
Methods inherited from interface javax.xml.stream.events.XMLEvent
asCharacters, asEndElement, asStartElement, getEventType, getLocation, getSchemaType, isAttribute, isCharacters, isEndDocument, isEndElement, isEntityReference, isNamespace, isProcessingInstruction, isStartDocument, isStartElement, writeAsEncodedUnicode

Method Detail

getName

QName getName()
Returns the QName for this attribute

getValue

String getValue()
Gets the normalized value of this attribute

getDTDType

String getDTDType()
Gets the type of this attribute, default is the String "CDATA"

Returns:
the type as a String, default is "CDATA"

isSpecified

boolean isSpecified()
A flag indicating whether this attribute was actually specified in the start-tag of its element, or was defaulted from the schema.

Returns:
returns true if this was specified in the start element
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Characters

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.events
Interface Characters

All Superinterfaces:
XMLEvent, XMLStreamConstants
public interface Characters
extends XMLEvent

This describes the interface to Characters events. All text events get reported as Characters events. Content, CData and whitespace are all reported as Characters events. IgnorableWhitespace, in most cases, will be set to false unless an element declaration of element content is present for the current element.

Since:
1.6

Field Summary
Fields inherited from interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
Method Summary
String | getData() Get the character data of this event
boolean | isCData() Returns true if this is a CData section.
boolean | isIgnorableWhiteSpace() Return true if this is ignorableWhiteSpace.
boolean | isWhiteSpace() Returns true if this set of Characters is all whitespace.
Methods inherited from interface javax.xml.stream.events.XMLEvent
asCharacters, asEndElement, asStartElement, getEventType, getLocation, getSchemaType, isAttribute, isCharacters, isEndDocument, isEndElement, isEntityReference, isNamespace, isProcessingInstruction, isStartDocument, isStartElement, writeAsEncodedUnicode

Method Detail

getData

String getData()
Get the character data of this event

isWhiteSpace

boolean isWhiteSpace()
Returns true if this set of Characters is all whitespace. Whitespace inside a document is reported as CHARACTERS. This method allows checking of CHARACTERS events to see if they are composed of only whitespace characters

isCData

boolean isCData()
Returns true if this is a CData section. If this event is CData its event type will be CDATA If javax.xml.stream.isCoalescing is set to true CDATA Sections that are surrounded by non CDATA characters will be reported as a single Characters event. This method will return false in this case.

isIgnorableWhiteSpace

boolean isIgnorableWhiteSpace()
Return true if this is ignorableWhiteSpace. If this event is ignorableWhiteSpace its event type will be SPACE.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Interface javax.xml.stream.events.Attribute

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.events.Attribute

Packages that use Attribute
javax.xml.stream
javax.xml.stream.events

Uses of Attribute in javax.xml.stream

Methods in javax.xml.stream that return Attribute
abstract Attribute | XMLEventFactory.createAttribute(QName name, String value) Create a new Attribute
abstract Attribute | XMLEventFactory.createAttribute(String localName, String value) Create a new Attribute
abstract Attribute | XMLEventFactory.createAttribute(String prefix, String namespaceURI, String localName, String value) Create a new Attribute

Uses of Attribute in javax.xml.stream.events

Subinterfaces of Attribute in javax.xml.stream.events
 interface Namespace
An interface that contains information about a namespace.

Methods in javax.xml.stream.events that return Attribute
 Attribute StartElement.getAttributeByName(QName name)
Returns the attribute referred to by this name

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.events.Characters

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.events.Characters

Packages that use Characters
javax.xml.stream
javax.xml.stream.events

Uses of Characters in javax.xml.stream

Methods in javax.xml.stream that return Characters
abstract Characters | XMLEventFactory.createCData(String content) Create a Characters event with the CData flag set to true
abstract Characters | XMLEventFactory.createCharacters(String content) Create a Characters event, this method does not check if the content is all whitespace.
abstract Characters | XMLEventFactory.createIgnorableSpace(String content) Create an ignorable space
abstract Characters | XMLEventFactory.createSpace(String content) Create a Characters event with the isSpace flag set to true

Uses of Characters in javax.xml.stream.events

Methods in javax.xml.stream.events that return Characters
 Characters XMLEvent.asCharacters()
Returns this event as Characters, may result in a class cast exception if this event is not Characters.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.events.Comment

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.events.Comment

Packages that use Comment
javax.xml.stream

Uses of Comment in javax.xml.stream

Methods in javax.xml.stream that return Comment
abstract  Comment XMLEventFactory.createComment(String text)
Create a comment

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.events.DTD

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.events.DTD

Packages that use DTD
javax.xml.stream

Uses of DTD in javax.xml.stream

Methods in javax.xml.stream that return DTD
abstract  DTD XMLEventFactory.createDTD(String dtd)
Create a document type definition event This string contains the entire document type declaration that matches the doctypedecl in the XML 1.0 specification

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.events.EndDocument

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.events.EndDocument

Packages that use EndDocument
javax.xml.stream

Uses of EndDocument in javax.xml.stream

Methods in javax.xml.stream that return EndDocument
abstract  EndDocument XMLEventFactory.createEndDocument()
Creates a new instance of an EndDocument event

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.events.EndElement

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.events.EndElement

Packages that use EndElement
javax.xml.stream
javax.xml.stream.events

Uses of EndElement in javax.xml.stream

Methods in javax.xml.stream that return EndElement
abstract EndElement | XMLEventFactory.createEndElement(QName name, Iterator namespaces) Create a new EndElement
abstract EndElement | XMLEventFactory.createEndElement(String prefix, String namespaceUri, String localName) Create a new EndElement
abstract EndElement | XMLEventFactory.createEndElement(String prefix, String namespaceUri, String localName, Iterator namespaces) Create a new EndElement

Uses of EndElement in javax.xml.stream.events

Methods in javax.xml.stream.events that return EndElement
 EndElement XMLEvent.asEndElement()
Returns this event as an end element event, may result in a class cast exception if this event is not a end element.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.events.EntityDeclaration

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.events.EntityDeclaration

Packages that use EntityDeclaration
javax.xml.stream
javax.xml.stream.events

Uses of EntityDeclaration in javax.xml.stream

Methods in javax.xml.stream with parameters of type EntityDeclaration
abstract  EntityReference XMLEventFactory.createEntityReference(String name, EntityDeclaration declaration)
Creates a new instance of a EntityReference event

Uses of EntityDeclaration in javax.xml.stream.events

Methods in javax.xml.stream.events that return EntityDeclaration
 EntityDeclaration EntityReference.getDeclaration()
Return the declaration of this entity.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.events.EntityReference

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.events.EntityReference

Packages that use EntityReference
javax.xml.stream

Uses of EntityReference in javax.xml.stream

Methods in javax.xml.stream that return EntityReference
abstract  EntityReference XMLEventFactory.createEntityReference(String name, EntityDeclaration declaration)
Creates a new instance of a EntityReference event

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.events.Namespace

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.events.Namespace

Packages that use Namespace
javax.xml.stream

Uses of Namespace in javax.xml.stream

Methods in javax.xml.stream that return Namespace
abstract Namespace | XMLEventFactory.createNamespace(String namespaceURI) Create a new default Namespace
abstract Namespace | XMLEventFactory.createNamespace(String prefix, String namespaceUri) Create a new Namespace

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.events.NotationDeclaration

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.events.NotationDeclaration

No usage of javax.xml.stream.events.NotationDeclaration

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.events.ProcessingInstruction

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.events.ProcessingInstruction

Packages that use ProcessingInstruction
javax.xml.stream

Uses of ProcessingInstruction in javax.xml.stream

Methods in javax.xml.stream that return ProcessingInstruction
abstract  ProcessingInstruction XMLEventFactory.createProcessingInstruction(String target, String data)
Create a processing instruction

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.events.StartDocument

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.events.StartDocument

Packages that use StartDocument
javax.xml.stream

Uses of StartDocument in javax.xml.stream

Methods in javax.xml.stream that return StartDocument
abstract StartDocument | XMLEventFactory.createStartDocument() Creates a new instance of a StartDocument event
abstract StartDocument | XMLEventFactory.createStartDocument(String encoding) Creates a new instance of a StartDocument event
abstract StartDocument | XMLEventFactory.createStartDocument(String encoding, String version) Creates a new instance of a StartDocument event
abstract StartDocument | XMLEventFactory.createStartDocument(String encoding, String version, boolean standalone) Creates a new instance of a StartDocument event

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.events.StartElement

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.events.StartElement

Packages that use StartElement
javax.xml.stream
javax.xml.stream.events

Uses of StartElement in javax.xml.stream

Methods in javax.xml.stream that return StartElement
abstract StartElement | XMLEventFactory.createStartElement(QName name, Iterator attributes, Iterator namespaces) Create a new StartElement.
abstract StartElement | XMLEventFactory.createStartElement(String prefix, String namespaceUri, String localName) Create a new StartElement.
abstract StartElement | XMLEventFactory.createStartElement(String prefix, String namespaceUri, String localName, Iterator attributes, Iterator namespaces) Create a new StartElement.
abstract StartElement | XMLEventFactory.createStartElement(String prefix, String namespaceUri, String localName, Iterator attributes, Iterator namespaces, NamespaceContext context) Create a new StartElement.

Uses of StartElement in javax.xml.stream.events

Methods in javax.xml.stream.events that return StartElement
 StartElement XMLEvent.asStartElement()
Returns this event as a start element event, may result in a class cast exception if this event is not a start element.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.events.XMLEvent

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.events.XMLEvent

Packages that use XMLEvent
javax.xml.stream
javax.xml.stream.events
javax.xml.stream.util

Uses of XMLEvent in javax.xml.stream

Methods in javax.xml.stream that return XMLEvent
XMLEvent | XMLEventReader.nextEvent() Get the next XMLEvent
XMLEvent | XMLEventReader.nextTag() Skips any insignificant space events until a START_ELEMENT or END_ELEMENT is reached.
XMLEvent | XMLEventReader.peek() Check the next XMLEvent without reading it from the stream.

Methods in javax.xml.stream with parameters of type XMLEvent
boolean | EventFilter.accept(XMLEvent event) Tests whether this event is part of this stream.
void | XMLEventWriter.add(XMLEvent event) Add an event to the output stream Adding a START_ELEMENT will open a new namespace scope that will be closed when the corresponding END_ELEMENT is written.

Uses of XMLEvent in javax.xml.stream.events

Subinterfaces of XMLEvent in javax.xml.stream.events
interface | Attribute An interface that contains information about an attribute.
interface | Characters This describes the interface to Characters events.
interface | Comment An interface for comment events
interface | DTD This is the top level interface for events dealing with DTDs
interface | EndDocument A marker interface for the end of the document
interface | EndElement An interface for the end element event.
interface | EntityDeclaration An interface for handling Entity Declarations This interface is used to record and report unparsed entity declarations.
interface | EntityReference An interface for handling Entity events.
interface | Namespace An interface that contains information about a namespace.
interface | NotationDeclaration An interface for handling Notation Declarations Receive notification of a notation declaration event.
interface | ProcessingInstruction An interface that describes the data found in processing instructions
interface | StartDocument An interface for the start document event
interface | StartElement The StartElement interface provides access to information about start elements.

Uses of XMLEvent in javax.xml.stream.util

Methods in javax.xml.stream.util that return XMLEvent
XMLEvent | XMLEventAllocator.allocate(XMLStreamReader reader) This method allocates an event given the current state of the XMLStreamReader.
XMLEvent | EventReaderDelegate.nextEvent()
XMLEvent | EventReaderDelegate.nextTag()
XMLEvent | EventReaderDelegate.peek()

Methods in javax.xml.stream.util with parameters of type XMLEvent
 void XMLEventConsumer.add(XMLEvent event)
This method adds an event to the consumer.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Comment

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.events
Interface Comment

All Superinterfaces:
XMLEvent, XMLStreamConstants
public interface Comment
extends XMLEvent

An interface for comment events

Since:
1.6

Field Summary
Fields inherited from interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
Method Summary
 String getText()
Return the string data of the comment, returns empty string if it does not exist
Methods inherited from interface javax.xml.stream.events.XMLEvent
asCharacters, asEndElement, asStartElement, getEventType, getLocation, getSchemaType, isAttribute, isCharacters, isEndDocument, isEndElement, isEntityReference, isNamespace, isProcessingInstruction, isStartDocument, isStartElement, writeAsEncodedUnicode

Method Detail

getText

String getText()
Return the string data of the comment, returns empty string if it does not exist

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DTD

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.events
Interface DTD

All Superinterfaces:
XMLEvent, XMLStreamConstants
public interface DTD
extends XMLEvent

This is the top level interface for events dealing with DTDs

Since:
1.6

Field Summary
Fields inherited from interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
Method Summary
String | getDocumentTypeDeclaration() Returns the entire Document Type Declaration as a string, including the internal DTD subset.
List | getEntities() Return a List containing the general entities, both external and internal, declared in the DTD.
List | getNotations() Return a List containing the notations declared in the DTD.
Object | getProcessedDTD() Returns an implementation defined representation of the DTD.
Methods inherited from interface javax.xml.stream.events.XMLEvent
asCharacters, asEndElement, asStartElement, getEventType, getLocation, getSchemaType, isAttribute, isCharacters, isEndDocument, isEndElement, isEntityReference, isNamespace, isProcessingInstruction, isStartDocument, isStartElement, writeAsEncodedUnicode

Method Detail

getDocumentTypeDeclaration

String getDocumentTypeDeclaration()
Returns the entire Document Type Declaration as a string, including the internal DTD subset. This may be null if there is not an internal subset. If it is not null it must return the entire Document Type Declaration which matches the doctypedecl production in the XML 1.0 specification

getProcessedDTD

Object getProcessedDTD()
Returns an implementation defined representation of the DTD. This method may return null if no representation is available.

getNotations

List getNotations()
Return a List containing the notations declared in the DTD. This list must contain NotationDeclaration events.

Returns:
an unordered list of NotationDeclaration events
See Also:
NotationDeclaration

getEntities

List getEntities()
Return a List containing the general entities, both external and internal, declared in the DTD. This list must contain EntityDeclaration events.

Returns:
an unordered list of EntityDeclaration events
See Also:
EntityDeclaration
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EndElement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.events
Interface EndElement

All Superinterfaces:
XMLEvent, XMLStreamConstants
public interface EndElement
extends XMLEvent

An interface for the end element event. An EndElement is reported for each End Tag in the document.

Since:
1.6
See Also:
XMLEvent

Field Summary
Fields inherited from interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
Method Summary
QName | getName() Get the name of this event
Iterator | getNamespaces() Returns an Iterator of namespaces that have gone out of scope.
Methods inherited from interface javax.xml.stream.events.XMLEvent
asCharacters, asEndElement, asStartElement, getEventType, getLocation, getSchemaType, isAttribute, isCharacters, isEndDocument, isEndElement, isEntityReference, isNamespace, isProcessingInstruction, isStartDocument, isStartElement, writeAsEncodedUnicode

Method Detail

getName

QName getName()
Get the name of this event

Returns:
the qualified name of this event

getNamespaces

Iterator getNamespaces()
Returns an Iterator of namespaces that have gone out of scope. Returns an empty iterator if no namespaces have gone out of scope.

Returns:
an Iterator over Namespace interfaces, or an empty iterator
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EntityDeclaration

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.events
Interface EntityDeclaration

All Superinterfaces:
XMLEvent, XMLStreamConstants
public interface EntityDeclaration
extends XMLEvent

An interface for handling Entity Declarations This interface is used to record and report unparsed entity declarations.

Since:
1.6

Field Summary
Fields inherited from interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
Method Summary
String | getBaseURI() Get the base URI for this reference or null if this information is not available
String | getName() The entity's name
String | getNotationName() The name of the associated notation.
String | getPublicId() The entity's public identifier, or null if none was given
String | getReplacementText() The replacement text of the entity.
String | getSystemId() The entity's system identifier.
Methods inherited from interface javax.xml.stream.events.XMLEvent
asCharacters, asEndElement, asStartElement, getEventType, getLocation, getSchemaType, isAttribute, isCharacters, isEndDocument, isEndElement, isEntityReference, isNamespace, isProcessingInstruction, isStartDocument, isStartElement, writeAsEncodedUnicode

Method Detail

getPublicId

String getPublicId()
The entity's public identifier, or null if none was given

Returns:
the public ID for this declaration or null

getSystemId

String getSystemId()
The entity's system identifier.

Returns:
the system ID for this declaration or null

getName

String getName()
The entity's name

Returns:
the name, may not be null

getNotationName

String getNotationName()
The name of the associated notation.

Returns:
the notation name

getReplacementText

String getReplacementText()
The replacement text of the entity. This method will only return non-null if this is an internal entity.

Returns:
null or the replacment text

getBaseURI

String getBaseURI()
Get the base URI for this reference or null if this information is not available

Returns:
the base URI or null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EntityReference

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.events
Interface EntityReference

All Superinterfaces:
XMLEvent, XMLStreamConstants
public interface EntityReference
extends XMLEvent

An interface for handling Entity events. This event reports entities that have not been resolved and reports their replacement text unprocessed (if available). This event will be reported if javax.xml.stream.isReplacingEntityReferences is set to false. If javax.xml.stream.isReplacingEntityReferences is set to true entity references will be resolved transparently. Entities are handled in two possible ways: (1) If javax.xml.stream.isReplacingEntityReferences is set to true all entity references are resolved and reported as markup transparently. (2) If javax.xml.stream.isReplacingEntityReferences is set to false Entity references are reported as an EntityReference Event.

Since:
1.6

Field Summary
Fields inherited from interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
Method Summary
EntityDeclaration | getDeclaration() Return the declaration of this entity.
String | getName() The name of the entity
Methods inherited from interface javax.xml.stream.events.XMLEvent
asCharacters, asEndElement, asStartElement, getEventType, getLocation, getSchemaType, isAttribute, isCharacters, isEndDocument, isEndElement, isEntityReference, isNamespace, isProcessingInstruction, isStartDocument, isStartElement, writeAsEncodedUnicode

Method Detail

getDeclaration

EntityDeclaration getDeclaration()
Return the declaration of this entity.

getName

String getName()
The name of the entity

Returns:
the entity's name, may not be null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Namespace

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.events
Interface Namespace

All Superinterfaces:
Attribute, XMLEvent, XMLStreamConstants
public interface Namespace
extends Attribute

An interface that contains information about a namespace. Namespaces are accessed from a StartElement.

Since:
1.6
See Also:
StartElement

Field Summary
Fields inherited from interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
Method Summary
String | getNamespaceURI() Gets the uri bound to the prefix of this namespace
String | getPrefix() Gets the prefix, returns "" if this is a default namespace declaration.
boolean | isDefaultNamespaceDeclaration() returns true if this attribute declares the default namespace
Methods inherited from interface javax.xml.stream.events.Attribute
getDTDType, getName, getValue, isSpecified
Methods inherited from interface javax.xml.stream.events.XMLEvent
asCharacters, asEndElement, asStartElement, getEventType, getLocation, getSchemaType, isAttribute, isCharacters, isEndDocument, isEndElement, isEntityReference, isNamespace, isProcessingInstruction, isStartDocument, isStartElement, writeAsEncodedUnicode

Method Detail

getPrefix

String getPrefix()
Gets the prefix, returns "" if this is a default namespace declaration.

getNamespaceURI

String getNamespaceURI()
Gets the uri bound to the prefix of this namespace

isDefaultNamespaceDeclaration

boolean isDefaultNamespaceDeclaration()
returns true if this attribute declares the default namespace

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotationDeclaration

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.events
Interface NotationDeclaration

All Superinterfaces:
XMLEvent, XMLStreamConstants
public interface NotationDeclaration
extends XMLEvent

An interface for handling Notation Declarations Receive notification of a notation declaration event. It is up to the application to record the notation for later reference, At least one of publicId and systemId must be non-null. There is no guarantee that the notation declaration will be reported before any unparsed entities that use it.

Since:
1.6

Field Summary
Fields inherited from interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
Method Summary
String | getName() The notation name.
String | getPublicId() The notation's public identifier, or null if none was given.
String | getSystemId() The notation's system identifier, or null if none was given.
Methods inherited from interface javax.xml.stream.events.XMLEvent
asCharacters, asEndElement, asStartElement, getEventType, getLocation, getSchemaType, isAttribute, isCharacters, isEndDocument, isEndElement, isEntityReference, isNamespace, isProcessingInstruction, isStartDocument, isStartElement, writeAsEncodedUnicode

Method Detail

getName

String getName()
The notation name.

getPublicId

String getPublicId()
The notation's public identifier, or null if none was given.

getSystemId

String getSystemId()
The notation's system identifier, or null if none was given.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ProcessingInstruction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.events
Interface ProcessingInstruction

All Superinterfaces:
XMLEvent, XMLStreamConstants
public interface ProcessingInstruction
extends XMLEvent

An interface that describes the data found in processing instructions

Since:
1.6

Field Summary
Fields inherited from interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
Method Summary
String | getData() The data section of the processing instruction
String | getTarget() The target section of the processing instruction
Methods inherited from interface javax.xml.stream.events.XMLEvent
asCharacters, asEndElement, asStartElement, getEventType, getLocation, getSchemaType, isAttribute, isCharacters, isEndDocument, isEndElement, isEntityReference, isNamespace, isProcessingInstruction, isStartDocument, isStartElement, writeAsEncodedUnicode

Method Detail

getTarget

String getTarget()
The target section of the processing instruction

Returns:
the String value of the PI or null

getData

String getData()
The data section of the processing instruction

Returns:
the String value of the PI's data or null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StartDocument

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.events
Interface StartDocument

All Superinterfaces:
XMLEvent, XMLStreamConstants
public interface StartDocument
extends XMLEvent

An interface for the start document event

Since:
1.6

Field Summary
Fields inherited from interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
Method Summary
boolean | encodingSet() Returns true if CharacterEncodingScheme was set in the encoding declaration of the document
String | getCharacterEncodingScheme() Returns the encoding style of the XML data
String | getSystemId() Returns the system ID of the XML data
String | getVersion() Returns the version of XML of this XML stream
boolean | isStandalone() Returns if this XML is standalone
boolean | standaloneSet() Returns true if the standalone attribute was set in the encoding declaration of the document.
Methods inherited from interface javax.xml.stream.events.XMLEvent
asCharacters, asEndElement, asStartElement, getEventType, getLocation, getSchemaType, isAttribute, isCharacters, isEndDocument, isEndElement, isEntityReference, isNamespace, isProcessingInstruction, isStartDocument, isStartElement, writeAsEncodedUnicode

Method Detail

getSystemId

String getSystemId()
Returns the system ID of the XML data

Returns:
the system ID, defaults to ""

getCharacterEncodingScheme

String getCharacterEncodingScheme()
Returns the encoding style of the XML data

Returns:
the character encoding, defaults to "UTF-8"

encodingSet

boolean encodingSet()
Returns true if CharacterEncodingScheme was set in the encoding declaration of the document

isStandalone

boolean isStandalone()
Returns if this XML is standalone

Returns:
the standalone state of XML, defaults to "no"

standaloneSet

boolean standaloneSet()
Returns true if the standalone attribute was set in the encoding declaration of the document.

getVersion

String getVersion()
Returns the version of XML of this XML stream

Returns:
the version of XML, defaults to "1.0"
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StartElement

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.events
Interface StartElement

All Superinterfaces:
XMLEvent, XMLStreamConstants
public interface StartElement
extends XMLEvent

The StartElement interface provides access to information about start elements. A StartElement is reported for each Start Tag in the document.

Since:
1.6

Field Summary
Fields inherited from interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
Method Summary
Attribute | getAttributeByName(QName name) Returns the attribute referred to by this name
Iterator | getAttributes() Returns an Iterator of non-namespace declared attributes declared on this START_ELEMENT, returns an empty iterator if there are no attributes.
QName | getName() Get the name of this event
NamespaceContext | getNamespaceContext() Gets a read-only namespace context.
Iterator | getNamespaces() Returns an Iterator of namespaces declared on this element.
String | getNamespaceURI(String prefix) Gets the value that the prefix is bound to in the context of this element.
Methods inherited from interface javax.xml.stream.events.XMLEvent
asCharacters, asEndElement, asStartElement, getEventType, getLocation, getSchemaType, isAttribute, isCharacters, isEndDocument, isEndElement, isEntityReference, isNamespace, isProcessingInstruction, isStartDocument, isStartElement, writeAsEncodedUnicode

Method Detail

getName

QName getName()
Get the name of this event

Returns:
the qualified name of this event

getAttributes

Iterator getAttributes()
Returns an Iterator of non-namespace declared attributes declared on this START_ELEMENT, returns an empty iterator if there are no attributes. The iterator must contain only implementations of the javax.xml.stream.Attribute interface. Attributes are fundamentally unordered and may not be reported in any order.

Returns:
a readonly Iterator over Attribute interfaces, or an empty iterator

getNamespaces

Iterator getNamespaces()
Returns an Iterator of namespaces declared on this element. This Iterator does not contain previously declared namespaces unless they appear on the current START_ELEMENT. Therefore this list may contain redeclared namespaces and duplicate namespace declarations. Use the getNamespaceContext() method to get the current context of namespace declarations.

The iterator must contain only implementations of the javax.xml.stream.Namespace interface.

A Namespace isA Attribute. One can iterate over a list of namespaces as a list of attributes. However this method returns only the list of namespaces declared on this START_ELEMENT and does not include the attributes declared on this START_ELEMENT. Returns an empty iterator if there are no namespaces.

Returns:
a readonly Iterator over Namespace interfaces, or an empty iterator

getAttributeByName

Attribute getAttributeByName(QName name)
Returns the attribute referred to by this name

Parameters:
name - the qname of the desired name
Returns:
the attribute corresponding to the name value or null

getNamespaceContext

NamespaceContext getNamespaceContext()
Gets a read-only namespace context. If no context is available this method will return an empty namespace context. The NamespaceContext contains information about all namespaces in scope for this StartElement.

Returns:
the current namespace context

getNamespaceURI

String getNamespaceURI(String prefix)
Gets the value that the prefix is bound to in the context of this element. Returns null if the prefix is not bound in this context

Parameters:
prefix - the prefix to lookup
Returns:
the uri bound to the prefix or null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLEvent

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.events
Interface XMLEvent

All Superinterfaces:
XMLStreamConstants
All Known Subinterfaces:
Attribute, Characters, Comment, DTD, EndDocument, EndElement, EntityDeclaration, EntityReference, Namespace, NotationDeclaration, ProcessingInstruction, StartDocument, StartElement
public interface XMLEvent
extends XMLStreamConstants

This is the base event interface for handling markup events. Events are value objects that are used to communicate the XML 1.0 InfoSet to the Application. Events may be cached and referenced after the parse has completed.

Since:
1.6
See Also:
XMLEventReader, Characters, ProcessingInstruction, StartElement, EndElement, StartDocument, EndDocument, EntityReference, EntityDeclaration, NotationDeclaration

Field Summary
Fields inherited from interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
Method Summary
Characters | asCharacters() Returns this event as Characters, may result in a class cast exception if this event is not Characters.
EndElement | asEndElement() Returns this event as an end element event, may result in a class cast exception if this event is not a end element.
StartElement | asStartElement() Returns this event as a start element event, may result in a class cast exception if this event is not a start element.
int | getEventType() Returns an integer code for this event.
Location | getLocation() Return the location of this event.
QName | getSchemaType() This method is provided for implementations to provide optional type information about the associated event.
boolean | isAttribute() A utility function to check if this event is an Attribute.
boolean | isCharacters() A utility function to check if this event is Characters.
boolean | isEndDocument() A utility function to check if this event is an EndDocument.
boolean | isEndElement() A utility function to check if this event is a EndElement.
boolean | isEntityReference() A utility function to check if this event is an EntityReference.
boolean | isNamespace() A utility function to check if this event is a Namespace.
boolean | isProcessingInstruction() A utility function to check if this event is a ProcessingInstruction.
boolean | isStartDocument() A utility function to check if this event is a StartDocument.
boolean | isStartElement() A utility function to check if this event is a StartElement.
void | writeAsEncodedUnicode(Writer writer) This method will write the XMLEvent as per the XML 1.0 specification as Unicode characters.

Method Detail

getEventType

int getEventType()
Returns an integer code for this event.

See Also:
XMLStreamConstants.START_ELEMENT, XMLStreamConstants.END_ELEMENT, XMLStreamConstants.CHARACTERS, XMLStreamConstants.ATTRIBUTE, XMLStreamConstants.NAMESPACE, XMLStreamConstants.PROCESSING_INSTRUCTION, XMLStreamConstants.COMMENT, XMLStreamConstants.START_DOCUMENT, XMLStreamConstants.END_DOCUMENT, XMLStreamConstants.DTD

getLocation

Location getLocation()
Return the location of this event. The Location returned from this method is non-volatile and will retain its information.

See Also:
Location

isStartElement

boolean isStartElement()
A utility function to check if this event is a StartElement.

See Also:
StartElement

isAttribute

boolean isAttribute()
A utility function to check if this event is an Attribute.

See Also:
Attribute

isNamespace

boolean isNamespace()
A utility function to check if this event is a Namespace.

See Also:
Namespace

isEndElement

boolean isEndElement()
A utility function to check if this event is a EndElement.

See Also:
EndElement

isEntityReference

boolean isEntityReference()
A utility function to check if this event is an EntityReference.

See Also:
EntityReference

isProcessingInstruction

boolean isProcessingInstruction()
A utility function to check if this event is a ProcessingInstruction.

See Also:
ProcessingInstruction

isCharacters

boolean isCharacters()
A utility function to check if this event is Characters.

See Also:
Characters

isStartDocument

boolean isStartDocument()
A utility function to check if this event is a StartDocument.

See Also:
StartDocument

isEndDocument

boolean isEndDocument()
A utility function to check if this event is an EndDocument.

See Also:
EndDocument

asStartElement

StartElement asStartElement()
Returns this event as a start element event, may result in a class cast exception if this event is not a start element.

asEndElement

EndElement asEndElement()
Returns this event as an end element event, may result in a class cast exception if this event is not a end element.

asCharacters

Characters asCharacters()
Returns this event as Characters, may result in a class cast exception if this event is not Characters.

getSchemaType

QName getSchemaType()
This method is provided for implementations to provide optional type information about the associated event. It is optional and will return null if no information is available.

writeAsEncodedUnicode

void writeAsEncodedUnicode(Writer writer)
                           throws XMLStreamException
This method will write the XMLEvent as per the XML 1.0 specification as Unicode characters. No indentation or whitespace should be outputted. Any user defined event type SHALL have this method called when being written to on an output stream. Built in Event types MUST implement this method, but implementations MAY choose not call these methods for optimizations reasons when writing out built in Events to an output stream. The output generated MUST be equivalent in terms of the infoset expressed.

Parameters:
writer - The writer that will output the data
Throws:
XMLStreamException - if there is a fatal error writing the event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


FactoryConfigurationError

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream
Class FactoryConfigurationError

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Error
            extended by  javax.xml.stream.FactoryConfigurationError
All Implemented Interfaces:
Serializable
public class FactoryConfigurationError
extends Error

An error class for reporting factory configuration errors.

Since:
1.6
See Also:
Serialized Form

Constructor Summary
FactoryConfigurationError()
Default constructor
FactoryConfigurationError(Exception e)
Construct an exception with a nested inner exception
FactoryConfigurationError(Exception e, String msg)
Construct an exception with a nested inner exception and a message
FactoryConfigurationError(String msg)
Construct an exception with associated message
FactoryConfigurationError(String msg, Exception e)
Construct an exception with a nested inner exception and a message
Method Summary
Exception | getException() Return the nested exception (if any)
String | getMessage() Report the message associated with this error
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

FactoryConfigurationError

public FactoryConfigurationError()
Default constructor

FactoryConfigurationError

public FactoryConfigurationError(Exception e)
Construct an exception with a nested inner exception

Parameters:
e - the exception to nest

FactoryConfigurationError

public FactoryConfigurationError(Exception e,
                                 String msg)
Construct an exception with a nested inner exception and a message

Parameters:
e - the exception to nest
msg - the message to report

FactoryConfigurationError

public FactoryConfigurationError(String msg,
                                 Exception e)
Construct an exception with a nested inner exception and a message

Parameters:
msg - the message to report
e - the exception to nest

FactoryConfigurationError

public FactoryConfigurationError(String msg)
Construct an exception with associated message

Parameters:
msg - the message to report
Method Detail

getException

public Exception getException()
Return the nested exception (if any)

Returns:
the nested exception or null

getMessage

public String getMessage()
Report the message associated with this error

Overrides:
getMessage in class Throwable
Returns:
the string value of the message
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Location

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream
Interface Location

public interface Location

Provides information on the location of an event. All the information provided by a Location is optional. For example an application may only report line numbers.

Since:
1.6

Method Summary
int | getCharacterOffset() Return the byte or character offset into the input source this location is pointing to.
int | getColumnNumber() Return the column number where the current event ends, returns -1 if none is available.
int | getLineNumber() Return the line number where the current event ends, returns -1 if none is available.
String | getPublicId() Returns the public ID of the XML
String | getSystemId() Returns the system ID of the XML

Method Detail

getLineNumber

int getLineNumber()
Return the line number where the current event ends, returns -1 if none is available.

Returns:
the current line number

getColumnNumber

int getColumnNumber()
Return the column number where the current event ends, returns -1 if none is available.

Returns:
the current column number

getCharacterOffset

int getCharacterOffset()
Return the byte or character offset into the input source this location is pointing to. If the input source is a file or a byte stream then this is the byte offset into that stream, but if the input source is a character media then the offset is the character offset. Returns -1 if there is no offset available.

Returns:
the current offset

getPublicId

String getPublicId()
Returns the public ID of the XML

Returns:
the public ID, or null if not available

getSystemId

String getSystemId()
Returns the system ID of the XML

Returns:
the system ID, or null if not available
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StreamFilter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream
Interface StreamFilter

public interface StreamFilter

This interface declares a simple filter interface that one can create to filter XMLStreamReaders

Since:
1.6

Method Summary
 boolean accept(XMLStreamReader reader)
Tests whether the current state is part of this stream.

Method Detail

accept

boolean accept(XMLStreamReader reader)
Tests whether the current state is part of this stream. This method will return true if this filter accepts this event and false otherwise. The method should not change the state of the reader when accepting a state.

Parameters:
reader - the event to test
Returns:
true if this filter accepts this event, false otherwise
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


util

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.stream.util

Interface Summary
XMLEventAllocator | This interface defines a class that allows a user to register a way to allocate events given an XMLStreamReader.
XMLEventConsumer | This interface defines an event consumer interface.

Class Summary
EventReaderDelegate | This is the base class for deriving an XMLEventReader filter.
StreamReaderDelegate | This is the base class for deriving an XMLStreamReader filter This class is designed to sit between an XMLStreamReader and an application's XMLStreamReader.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.stream.util Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.stream.util

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.stream.util.EventReaderDelegate (implements javax.xml.stream.XMLEventReader)
    • javax.xml.stream.util.StreamReaderDelegate (implements javax.xml.stream.XMLStreamReader)

Interface Hierarchy

  • javax.xml.stream.util.XMLEventAllocator
  • javax.xml.stream.util.XMLEventConsumer
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.stream.util

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.stream.util

Packages that use javax.xml.stream.util
javax.xml.stream
javax.xml.stream.util

Classes in javax.xml.stream.util used by javax.xml.stream
XMLEventAllocator
This interface defines a class that allows a user to register a way to allocate events given an XMLStreamReader.
XMLEventConsumer
This interface defines an event consumer interface.

Classes in javax.xml.stream.util used by javax.xml.stream.util
XMLEventAllocator
This interface defines a class that allows a user to register a way to allocate events given an XMLStreamReader.
XMLEventConsumer
This interface defines an event consumer interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.stream.util.EventReaderDelegate

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.stream.util.EventReaderDelegate

No usage of javax.xml.stream.util.EventReaderDelegate

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.stream.util.StreamReaderDelegate

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.stream.util.StreamReaderDelegate

No usage of javax.xml.stream.util.StreamReaderDelegate

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.util.XMLEventAllocator

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.util.XMLEventAllocator

Packages that use XMLEventAllocator
javax.xml.stream
javax.xml.stream.util

Uses of XMLEventAllocator in javax.xml.stream

Methods in javax.xml.stream that return XMLEventAllocator
abstract  XMLEventAllocator XMLInputFactory.getEventAllocator()
Gets the allocator used by streams created with this factory

Methods in javax.xml.stream with parameters of type XMLEventAllocator
abstract  void XMLInputFactory.setEventAllocator(XMLEventAllocator allocator)
Set a user defined event allocator for events

Uses of XMLEventAllocator in javax.xml.stream.util

Methods in javax.xml.stream.util that return XMLEventAllocator
 XMLEventAllocator XMLEventAllocator.newInstance()
This method creates an instance of the XMLEventAllocator.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.stream.util.XMLEventConsumer

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.stream.util.XMLEventConsumer

Packages that use XMLEventConsumer
javax.xml.stream
javax.xml.stream.util

Uses of XMLEventConsumer in javax.xml.stream

Subinterfaces of XMLEventConsumer in javax.xml.stream
 interface XMLEventWriter
This is the top level interface for writing XML documents.

Uses of XMLEventConsumer in javax.xml.stream.util

Methods in javax.xml.stream.util with parameters of type XMLEventConsumer
 void XMLEventAllocator.allocate(XMLStreamReader reader, XMLEventConsumer consumer)
This method allocates an event or set of events given the current state of the XMLStreamReader and adds the event or set of events to the consumer that was passed in.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


EventReaderDelegate

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.util
Class EventReaderDelegate

java.lang.Object
    extended by  javax.xml.stream.util.EventReaderDelegate
All Implemented Interfaces:
Iterator, XMLEventReader
public class EventReaderDelegate
extends Object
implements XMLEventReader

This is the base class for deriving an XMLEventReader filter. This class is designed to sit between an XMLEventReader and an application's XMLEventReader. By default each method does nothing but call the corresponding method on the parent interface.

Since:
1.6
See Also:
XMLEventReader, StreamReaderDelegate

Constructor Summary
EventReaderDelegate()
Construct an empty filter with no parent.
EventReaderDelegate(XMLEventReader reader)
Construct an filter with the specified parent.
Method Summary
void | close() Frees any resources associated with this Reader.
String | getElementText() Reads the content of a text-only element.
XMLEventReader | getParent() Get the parent of this instance.
Object | getProperty(String name) Get the value of a feature/property from the underlying implementation
boolean | hasNext() Check if there are more events.
Object | next() Returns the next element in the iteration.
XMLEvent | nextEvent() Get the next XMLEvent
XMLEvent | nextTag() Skips any insignificant space events until a START_ELEMENT or END_ELEMENT is reached.
XMLEvent | peek() Check the next XMLEvent without reading it from the stream.
void | remove() Removes from the underlying collection the last element returned by the iterator (optional operation).
void | setParent(XMLEventReader reader) Set the parent of this instance.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EventReaderDelegate

public EventReaderDelegate()
Construct an empty filter with no parent.

EventReaderDelegate

public EventReaderDelegate(XMLEventReader reader)
Construct an filter with the specified parent.

Parameters:
reader - the parent
Method Detail

setParent

public void setParent(XMLEventReader reader)
Set the parent of this instance.

Parameters:
reader - the new parent

getParent

public XMLEventReader getParent()
Get the parent of this instance.

Returns:
the parent or null if none is set

nextEvent

public XMLEvent nextEvent()
                   throws XMLStreamException
Description copied from interface: XMLEventReader
Get the next XMLEvent

Specified by:
nextEvent in interface XMLEventReader
Throws:
XMLStreamException - if there is an error with the underlying XML.
See Also:
XMLEvent

next

public Object next()
Description copied from interface: Iterator
Returns the next element in the iteration.

Specified by:
next in interface Iterator
Returns:
the next element in the iteration.

hasNext

public boolean hasNext()
Description copied from interface: XMLEventReader
Check if there are more events. Returns true if there are more events and false otherwise.

Specified by:
hasNext in interface Iterator
Specified by:
hasNext in interface XMLEventReader
Returns:
true if the event reader has more events, false otherwise

peek

public XMLEvent peek()
              throws XMLStreamException
Description copied from interface: XMLEventReader
Check the next XMLEvent without reading it from the stream. Returns null if the stream is at EOF or has no more XMLEvents. A call to peek() will be equal to the next return of next().

Specified by:
peek in interface XMLEventReader
Throws:
XMLStreamException
See Also:
XMLEvent

close

public void close()
           throws XMLStreamException
Description copied from interface: XMLEventReader
Frees any resources associated with this Reader. This method does not close the underlying input source.

Specified by:
close in interface XMLEventReader
Throws:
XMLStreamException - if there are errors freeing associated resources

getElementText

public String getElementText()
                      throws XMLStreamException
Description copied from interface: XMLEventReader
Reads the content of a text-only element. Precondition: the current event is START_ELEMENT. Postcondition: The current event is the corresponding END_ELEMENT.

Specified by:
getElementText in interface XMLEventReader
Throws:
XMLStreamException - if the current event is not a START_ELEMENT or if a non text element is encountered

nextTag

public XMLEvent nextTag()
                 throws XMLStreamException
Description copied from interface: XMLEventReader
Skips any insignificant space events until a START_ELEMENT or END_ELEMENT is reached. If anything other than space characters are encountered, an exception is thrown. This method should be used when processing element-only content because the parser is not able to recognize ignorable whitespace if the DTD is missing or not interpreted.

Specified by:
nextTag in interface XMLEventReader
Throws:
XMLStreamException - if anything other than space characters are encountered

getProperty

public Object getProperty(String name)
                   throws IllegalArgumentException
Description copied from interface: XMLEventReader
Get the value of a feature/property from the underlying implementation

Specified by:
getProperty in interface XMLEventReader
Parameters:
name - The name of the property
Returns:
The value of the property
Throws:
IllegalArgumentException - if the property is not supported

remove

public void remove()
Description copied from interface: Iterator
Removes from the underlying collection the last element returned by the iterator (optional operation). This method can be called only once per call to next. The behavior of an iterator is unspecified if the underlying collection is modified while the iteration is in progress in any way other than by calling this method.

Specified by:
remove in interface Iterator
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


StreamReaderDelegate

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.util
Class StreamReaderDelegate

java.lang.Object
    extended by  javax.xml.stream.util.StreamReaderDelegate
All Implemented Interfaces:
XMLStreamConstants, XMLStreamReader
public class StreamReaderDelegate
extends Object
implements XMLStreamReader

This is the base class for deriving an XMLStreamReader filter This class is designed to sit between an XMLStreamReader and an application's XMLStreamReader. By default each method does nothing but call the corresponding method on the parent interface.

Since:
1.6
See Also:
XMLStreamReader, EventReaderDelegate

Field Summary
Fields inherited from interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
Constructor Summary
StreamReaderDelegate()
Construct an empty filter with no parent.
StreamReaderDelegate(XMLStreamReader reader)
Construct an filter with the specified parent.
Method Summary
 void close()
Frees any resources associated with this Reader.
 int getAttributeCount()
Returns the count of attributes on this START_ELEMENT, this method is only valid on a START_ELEMENT or ATTRIBUTE.
 String getAttributeLocalName(int index)
Returns the localName of the attribute at the provided index
 QName getAttributeName(int index)
Returns the qname of the attribute at the provided index
 String getAttributeNamespace(int index)
Returns the namespace of the attribute at the provided index
 String getAttributePrefix(int index)
Returns the prefix of this attribute at the provided index
 String getAttributeType(int index)
Returns the XML type of the attribute at the provided index
 String getAttributeValue(int index)
Returns the value of the attribute at the index
 String getAttributeValue(String namespaceUri, String localName)
Returns the normalized attribute value of the attribute with the namespace and localName If the namespaceURI is null the namespace is not checked for equality
 String getCharacterEncodingScheme()
Returns the character encoding declared on the xml declaration Returns null if none was declared
 String getElementText()
Reads the content of a text-only element, an exception is thrown if this is not a text-only element.
 String getEncoding()
Return input encoding if known or null if unknown.
 int getEventType()
Returns an integer code that indicates the type of the event the cursor is pointing to.
 String getLocalName()
Returns the (local) name of the current event.
 Location getLocation()
Return the current location of the processor.
 QName getName()
Returns a QName for the current START_ELEMENT or END_ELEMENT event
 NamespaceContext getNamespaceContext()
Returns a read only namespace context for the current position.
 int getNamespaceCount()
Returns the count of namespaces declared on this START_ELEMENT or END_ELEMENT, this method is only valid on a START_ELEMENT, END_ELEMENT or NAMESPACE.
 String getNamespacePrefix(int index)
Returns the prefix for the namespace declared at the index.
 String getNamespaceURI()
If the current event is a START_ELEMENT or END_ELEMENT this method returns the URI of the prefix or the default namespace.
 String getNamespaceURI(int index)
Returns the uri for the namespace declared at the index.
 String getNamespaceURI(String prefix)
Return the uri for the given prefix.
 XMLStreamReader getParent()
Get the parent of this instance.
 String getPIData()
Get the data section of a processing instruction
 String getPITarget()
Get the target of a processing instruction
 String getPrefix()
Returns the prefix of the current event or null if the event does not have a prefix
 Object getProperty(String name)
Get the value of a feature/property from the underlying implementation
 String getText()
Returns the current value of the parse event as a string, this returns the string value of a CHARACTERS event, returns the value of a COMMENT, the replacement value for an ENTITY_REFERENCE, the string value of a CDATA section, the string value for a SPACE event, or the String value of the internal subset of the DTD.
 char[] getTextCharacters()
Returns an array which contains the characters from this event.
 int getTextCharacters(int sourceStart, char[] target, int targetStart, int length)
Gets the the text associated with a CHARACTERS, SPACE or CDATA event.
 int getTextLength()
Returns the length of the sequence of characters for this Text event within the text character array.
 int getTextStart()
Returns the offset into the text character array where the first character (of this text event) is stored.
 String getVersion()
Get the xml version declared on the xml declaration Returns null if none was declared
 boolean hasName()
returns true if the current event has a name (is a START_ELEMENT or END_ELEMENT) returns false otherwise
 boolean hasNext()
Returns true if there are more parsing events and false if there are no more events.
 boolean hasText()
Return true if the current event has text, false otherwise The following events have text: CHARACTERS,DTD ,ENTITY_REFERENCE, COMMENT, SPACE
 boolean isAttributeSpecified(int index)
Returns a boolean which indicates if this attribute was created by default
 boolean isCharacters()
Returns true if the cursor points to a character data event
 boolean isEndElement()
Returns true if the cursor points to an end tag (otherwise false)
 boolean isStandalone()
Get the standalone declaration from the xml declaration
 boolean isStartElement()
Returns true if the cursor points to a start tag (otherwise false)
 boolean isWhiteSpace()
Returns true if the cursor points to a character data event that consists of all whitespace
 int next()
Get next parsing event - a processor may return all contiguous character data in a single chunk, or it may split it into several chunks.
 int nextTag()
Skips any white space (isWhiteSpace() returns true), COMMENT, or PROCESSING_INSTRUCTION, until a START_ELEMENT or END_ELEMENT is reached.
 void require(int type, String namespaceURI, String localName)
Test if the current event is of the given type and if the namespace and name match the current namespace and name of the current event.
 void setParent(XMLStreamReader reader)
Set the parent of this instance.
 boolean standaloneSet()
Checks if standalone was set in the document
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StreamReaderDelegate

public StreamReaderDelegate()
Construct an empty filter with no parent.

StreamReaderDelegate

public StreamReaderDelegate(XMLStreamReader reader)
Construct an filter with the specified parent.

Parameters:
reader - the parent
Method Detail

setParent

public void setParent(XMLStreamReader reader)
Set the parent of this instance.

Parameters:
reader - the new parent

getParent

public XMLStreamReader getParent()
Get the parent of this instance.

Returns:
the parent or null if none is set

next

public int next()
         throws XMLStreamException
Description copied from interface: XMLStreamReader
Get next parsing event - a processor may return all contiguous character data in a single chunk, or it may split it into several chunks. If the property javax.xml.stream.isCoalescing is set to true element content must be coalesced and only one CHARACTERS event must be returned for contiguous element content or CDATA Sections. By default entity references must be expanded and reported transparently to the application. An exception will be thrown if an entity reference cannot be expanded. If element content is empty (i.e. content is "") then no CHARACTERS event will be reported.

Given the following XML:
<foo><!--description-->content text<![CDATA[<greeting>Hello</greeting>]]>other content</foo>
The behavior of calling next() when being on foo will be:
1- the comment (COMMENT)
2- then the characters section (CHARACTERS)
3- then the CDATA section (another CHARACTERS)
4- then the next characters section (another CHARACTERS)
5- then the END_ELEMENT

NOTE: empty element (such as <tag/>) will be reported with two separate events: START_ELEMENT, END_ELEMENT - This preserves parsing equivalency of empty element to <tag></tag>. This method will throw an IllegalStateException if it is called after hasNext() returns false.

Specified by:
next in interface XMLStreamReader
Returns:
the integer code corresponding to the current parse event
Throws:
XMLStreamException - if there is an error processing the underlying XML source
See Also:
XMLEvent

nextTag

public int nextTag()
            throws XMLStreamException
Description copied from interface: XMLStreamReader
Skips any white space (isWhiteSpace() returns true), COMMENT, or PROCESSING_INSTRUCTION, until a START_ELEMENT or END_ELEMENT is reached. If other than white space characters, COMMENT, PROCESSING_INSTRUCTION, START_ELEMENT, END_ELEMENT are encountered, an exception is thrown. This method should be used when processing element-only content seperated by white space.
Precondition: none
Postcondition: the current event is START_ELEMENT or END_ELEMENT and cursor may have moved over any whitespace event.
Essentially it does the following (implementations are free to optimized but must do equivalent processing):
 int eventType = next();
 while((eventType == XMLStreamConstants.CHARACTERS && isWhiteSpace()) // skip whitespace
 || (eventType == XMLStreamConstants.CDATA && isWhiteSpace())
 // skip whitespace
 || eventType == XMLStreamConstants.SPACE
 || eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
 || eventType == XMLStreamConstants.COMMENT
 ) {
 eventType = next();
 }
 if (eventType != XMLStreamConstants.START_ELEMENT && eventType != XMLStreamConstants.END_ELEMENT) {
 throw new String XMLStreamException("expected start or end tag", getLocation());
 }
 return eventType;

Specified by:
nextTag in interface XMLStreamReader
Returns:
the event type of the element read (START_ELEMENT or END_ELEMENT)
Throws:
XMLStreamException - if the current event is not white space, PROCESSING_INSTRUCTION, START_ELEMENT or END_ELEMENT

getElementText

public String getElementText()
                      throws XMLStreamException
Description copied from interface: XMLStreamReader
Reads the content of a text-only element, an exception is thrown if this is not a text-only element. Regardless of value of javax.xml.stream.isCoalescing this method always returns coalesced content.
Precondition: the current event is START_ELEMENT.
Postcondition: the current event is the corresponding END_ELEMENT.
The method does the following (implementations are free to optimized but must do equivalent processing):
 if(getEventType() != XMLStreamConstants.START_ELEMENT) {
 throw new XMLStreamException(
 "parser must be on START_ELEMENT to read next text", getLocation());
 }
 int eventType = next();
 StringBuffer content = new StringBuffer();
 while(eventType != XMLStreamConstants.END_ELEMENT ) {
 if(eventType == XMLStreamConstants.CHARACTERS
 || eventType == XMLStreamConstants.CDATA
 || eventType == XMLStreamConstants.SPACE
 || eventType == XMLStreamConstants.ENTITY_REFERENCE) {
 buf.append(getText());
 } else if(eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
 || eventType == XMLStreamConstants.COMMENT) {
 // skipping
 } else if(eventType == XMLStreamConstants.END_DOCUMENT) {
 throw new XMLStreamException(
 "unexpected end of document when reading element text content", this);
 } else if(eventType == XMLStreamConstants.START_ELEMENT) {
 throw new XMLStreamException(
 "element text content may not contain START_ELEMENT", getLocation());
 } else {
 throw new XMLStreamException(
 "Unexpected event type "+eventType, getLocation());
 }
 eventType = next();
 }
 return buf.toString();

Specified by:
getElementText in interface XMLStreamReader
Throws:
XMLStreamException - if the current event is not a START_ELEMENT or if a non text element is encountered

require

public void require(int type,
                    String namespaceURI,
                    String localName)
             throws XMLStreamException
Description copied from interface: XMLStreamReader
Test if the current event is of the given type and if the namespace and name match the current namespace and name of the current event. If the namespaceURI is null it is not checked for equality, if the localName is null it is not checked for equality.

Specified by:
require in interface XMLStreamReader
Parameters:
type - the event type
namespaceURI - the uri of the event, may be null
localName - the localName of the event, may be null
Throws:
XMLStreamException - if the required values are not matched.

hasNext

public boolean hasNext()
                throws XMLStreamException
Description copied from interface: XMLStreamReader
Returns true if there are more parsing events and false if there are no more events. This method will return false if the current state of the XMLStreamReader is END_DOCUMENT

Specified by:
hasNext in interface XMLStreamReader
Returns:
true if there are more events, false otherwise
Throws:
XMLStreamException - if there is a fatal error detecting the next state

close

public void close()
           throws XMLStreamException
Description copied from interface: XMLStreamReader
Frees any resources associated with this Reader. This method does not close the underlying input source.

Specified by:
close in interface XMLStreamReader
Throws:
XMLStreamException - if there are errors freeing associated resources

getNamespaceURI

public String getNamespaceURI(String prefix)
Description copied from interface: XMLStreamReader
Return the uri for the given prefix. The uri returned depends on the current state of the processor.

NOTE:The 'xml' prefix is bound as defined in Namespaces in XML specification to "http://www.w3.org/XML/1998/namespace".

NOTE: The 'xmlns' prefix must be resolved to following namespace http://www.w3.org/2000/xmlns/

Specified by:
getNamespaceURI in interface XMLStreamReader
Parameters:
prefix - The prefix to lookup, may not be null
Returns:
the uri bound to the given prefix or null if it is not bound

getNamespaceContext

public NamespaceContext getNamespaceContext()
Description copied from interface: XMLStreamReader
Returns a read only namespace context for the current position. The context is transient and only valid until a call to next() changes the state of the reader.

Specified by:
getNamespaceContext in interface XMLStreamReader
Returns:
return a namespace context

isStartElement

public boolean isStartElement()
Description copied from interface: XMLStreamReader
Returns true if the cursor points to a start tag (otherwise false)

Specified by:
isStartElement in interface XMLStreamReader
Returns:
true if the cursor points to a start tag, false otherwise

isEndElement

public boolean isEndElement()
Description copied from interface: XMLStreamReader
Returns true if the cursor points to an end tag (otherwise false)

Specified by:
isEndElement in interface XMLStreamReader
Returns:
true if the cursor points to an end tag, false otherwise

isCharacters

public boolean isCharacters()
Description copied from interface: XMLStreamReader
Returns true if the cursor points to a character data event

Specified by:
isCharacters in interface XMLStreamReader
Returns:
true if the cursor points to character data, false otherwise

isWhiteSpace

public boolean isWhiteSpace()
Description copied from interface: XMLStreamReader
Returns true if the cursor points to a character data event that consists of all whitespace

Specified by:
isWhiteSpace in interface XMLStreamReader
Returns:
true if the cursor points to all whitespace, false otherwise

getAttributeValue

public String getAttributeValue(String namespaceUri,
                                String localName)
Description copied from interface: XMLStreamReader
Returns the normalized attribute value of the attribute with the namespace and localName If the namespaceURI is null the namespace is not checked for equality

Specified by:
getAttributeValue in interface XMLStreamReader
Parameters:
namespaceUri - the namespace of the attribute
localName - the local name of the attribute, cannot be null
Returns:
returns the value of the attribute , returns null if not found

getAttributeCount

public int getAttributeCount()
Description copied from interface: XMLStreamReader
Returns the count of attributes on this START_ELEMENT, this method is only valid on a START_ELEMENT or ATTRIBUTE. This count excludes namespace definitions. Attribute indices are zero-based.

Specified by:
getAttributeCount in interface XMLStreamReader
Returns:
returns the number of attributes

getAttributeName

public QName getAttributeName(int index)
Description copied from interface: XMLStreamReader
Returns the qname of the attribute at the provided index

Specified by:
getAttributeName in interface XMLStreamReader
Parameters:
index - the position of the attribute
Returns:
the QName of the attribute

getAttributePrefix

public String getAttributePrefix(int index)
Description copied from interface: XMLStreamReader
Returns the prefix of this attribute at the provided index

Specified by:
getAttributePrefix in interface XMLStreamReader
Parameters:
index - the position of the attribute
Returns:
the prefix of the attribute

getAttributeNamespace

public String getAttributeNamespace(int index)
Description copied from interface: XMLStreamReader
Returns the namespace of the attribute at the provided index

Specified by:
getAttributeNamespace in interface XMLStreamReader
Parameters:
index - the position of the attribute
Returns:
the namespace URI (can be null)

getAttributeLocalName

public String getAttributeLocalName(int index)
Description copied from interface: XMLStreamReader
Returns the localName of the attribute at the provided index

Specified by:
getAttributeLocalName in interface XMLStreamReader
Parameters:
index - the position of the attribute
Returns:
the localName of the attribute

getAttributeType

public String getAttributeType(int index)
Description copied from interface: XMLStreamReader
Returns the XML type of the attribute at the provided index

Specified by:
getAttributeType in interface XMLStreamReader
Parameters:
index - the position of the attribute
Returns:
the XML type of the attribute

getAttributeValue

public String getAttributeValue(int index)
Description copied from interface: XMLStreamReader
Returns the value of the attribute at the index

Specified by:
getAttributeValue in interface XMLStreamReader
Parameters:
index - the position of the attribute
Returns:
the attribute value

isAttributeSpecified

public boolean isAttributeSpecified(int index)
Description copied from interface: XMLStreamReader
Returns a boolean which indicates if this attribute was created by default

Specified by:
isAttributeSpecified in interface XMLStreamReader
Parameters:
index - the position of the attribute
Returns:
true if this is a default attribute

getNamespaceCount

public int getNamespaceCount()
Description copied from interface: XMLStreamReader
Returns the count of namespaces declared on this START_ELEMENT or END_ELEMENT, this method is only valid on a START_ELEMENT, END_ELEMENT or NAMESPACE. On an END_ELEMENT the count is of the namespaces that are about to go out of scope. This is the equivalent of the information reported by SAX callback for an end element event.

Specified by:
getNamespaceCount in interface XMLStreamReader
Returns:
returns the number of namespace declarations on this specific element

getNamespacePrefix

public String getNamespacePrefix(int index)
Description copied from interface: XMLStreamReader
Returns the prefix for the namespace declared at the index. Returns null if this is the default namespace declaration

Specified by:
getNamespacePrefix in interface XMLStreamReader
Parameters:
index - the position of the namespace declaration
Returns:
returns the namespace prefix

getNamespaceURI

public String getNamespaceURI(int index)
Description copied from interface: XMLStreamReader
Returns the uri for the namespace declared at the index.

Specified by:
getNamespaceURI in interface XMLStreamReader
Parameters:
index - the position of the namespace declaration
Returns:
returns the namespace uri

getEventType

public int getEventType()
Description copied from interface: XMLStreamReader
Returns an integer code that indicates the type of the event the cursor is pointing to.

Specified by:
getEventType in interface XMLStreamReader

getText

public String getText()
Description copied from interface: XMLStreamReader
Returns the current value of the parse event as a string, this returns the string value of a CHARACTERS event, returns the value of a COMMENT, the replacement value for an ENTITY_REFERENCE, the string value of a CDATA section, the string value for a SPACE event, or the String value of the internal subset of the DTD. If an ENTITY_REFERENCE has been resolved, any character data will be reported as CHARACTERS events.

Specified by:
getText in interface XMLStreamReader
Returns:
the current text or null

getTextCharacters

public int getTextCharacters(int sourceStart,
                             char[] target,
                             int targetStart,
                             int length)
                      throws XMLStreamException
Description copied from interface: XMLStreamReader
Gets the the text associated with a CHARACTERS, SPACE or CDATA event. Text starting a "sourceStart" is copied into "target" starting at "targetStart". Up to "length" characters are copied. The number of characters actually copied is returned. The "sourceStart" argument must be greater or equal to 0 and less than or equal to the number of characters associated with the event. Usually, one requests text starting at a "sourceStart" of 0. If the number of characters actually copied is less than the "length", then there is no more text. Otherwise, subsequent calls need to be made until all text has been retrieved. For example:
int length = 1024;
char[] myBuffer = new char[ length ];

for ( int sourceStart = 0 ; ; sourceStart += length )
{
   int nCopied = stream.getTextCharacters( sourceStart, myBuffer, 0, length );

  if (nCopied < length)
      break;
}
 XMLStreamException may be thrown if there are any XML errors in the underlying source. The "targetStart" argument must be greater than or equal to 0 and less than the length of "target", Length must be greater than 0 and "targetStart + length" must be less than or equal to length of "target".

Specified by:
getTextCharacters in interface XMLStreamReader
Parameters:
sourceStart - the index of the first character in the source array to copy
target - the destination array
targetStart - the start offset in the target array
length - the number of characters to copy
Returns:
the number of characters actually copied
Throws:
XMLStreamException - if the underlying XML source is not well-formed

getTextCharacters

public char[] getTextCharacters()
Description copied from interface: XMLStreamReader
Returns an array which contains the characters from this event. This array should be treated as read-only and transient. I.e. the array will contain the text characters until the XMLStreamReader moves on to the next event. Attempts to hold onto the character array beyond that time or modify the contents of the array are breaches of the contract for this interface.

Specified by:
getTextCharacters in interface XMLStreamReader
Returns:
the current text or an empty array

getTextStart

public int getTextStart()
Description copied from interface: XMLStreamReader
Returns the offset into the text character array where the first character (of this text event) is stored.

Specified by:
getTextStart in interface XMLStreamReader

getTextLength

public int getTextLength()
Description copied from interface: XMLStreamReader
Returns the length of the sequence of characters for this Text event within the text character array.

Specified by:
getTextLength in interface XMLStreamReader

getEncoding

public String getEncoding()
Description copied from interface: XMLStreamReader
Return input encoding if known or null if unknown.

Specified by:
getEncoding in interface XMLStreamReader
Returns:
the encoding of this instance or null

hasText

public boolean hasText()
Description copied from interface: XMLStreamReader
Return true if the current event has text, false otherwise The following events have text: CHARACTERS,DTD ,ENTITY_REFERENCE, COMMENT, SPACE

Specified by:
hasText in interface XMLStreamReader

getLocation

public Location getLocation()
Description copied from interface: XMLStreamReader
Return the current location of the processor. If the Location is unknown the processor should return an implementation of Location that returns -1 for the location and null for the publicId and systemId. The location information is only valid until next() is called.

Specified by:
getLocation in interface XMLStreamReader

getName

public QName getName()
Description copied from interface: XMLStreamReader
Returns a QName for the current START_ELEMENT or END_ELEMENT event

Specified by:
getName in interface XMLStreamReader
Returns:
the QName for the current START_ELEMENT or END_ELEMENT event

getLocalName

public String getLocalName()
Description copied from interface: XMLStreamReader
Returns the (local) name of the current event. For START_ELEMENT or END_ELEMENT returns the (local) name of the current element. For ENTITY_REFERENCE it returns entity name. The current event must be START_ELEMENT or END_ELEMENT, or ENTITY_REFERENCE

Specified by:
getLocalName in interface XMLStreamReader
Returns:
the localName

hasName

public boolean hasName()
Description copied from interface: XMLStreamReader
returns true if the current event has a name (is a START_ELEMENT or END_ELEMENT) returns false otherwise

Specified by:
hasName in interface XMLStreamReader

getNamespaceURI

public String getNamespaceURI()
Description copied from interface: XMLStreamReader
If the current event is a START_ELEMENT or END_ELEMENT this method returns the URI of the prefix or the default namespace. Returns null if the event does not have a prefix.

Specified by:
getNamespaceURI in interface XMLStreamReader
Returns:
the URI bound to this elements prefix, the default namespace, or null

getPrefix

public String getPrefix()
Description copied from interface: XMLStreamReader
Returns the prefix of the current event or null if the event does not have a prefix

Specified by:
getPrefix in interface XMLStreamReader
Returns:
the prefix or null

getVersion

public String getVersion()
Description copied from interface: XMLStreamReader
Get the xml version declared on the xml declaration Returns null if none was declared

Specified by:
getVersion in interface XMLStreamReader
Returns:
the XML version or null

isStandalone

public boolean isStandalone()
Description copied from interface: XMLStreamReader
Get the standalone declaration from the xml declaration

Specified by:
isStandalone in interface XMLStreamReader
Returns:
true if this is standalone, or false otherwise

standaloneSet

public boolean standaloneSet()
Description copied from interface: XMLStreamReader
Checks if standalone was set in the document

Specified by:
standaloneSet in interface XMLStreamReader
Returns:
true if standalone was set in the document, or false otherwise

getCharacterEncodingScheme

public String getCharacterEncodingScheme()
Description copied from interface: XMLStreamReader
Returns the character encoding declared on the xml declaration Returns null if none was declared

Specified by:
getCharacterEncodingScheme in interface XMLStreamReader
Returns:
the encoding declared in the document or null

getPITarget

public String getPITarget()
Description copied from interface: XMLStreamReader
Get the target of a processing instruction

Specified by:
getPITarget in interface XMLStreamReader
Returns:
the target or null

getPIData

public String getPIData()
Description copied from interface: XMLStreamReader
Get the data section of a processing instruction

Specified by:
getPIData in interface XMLStreamReader
Returns:
the data or null

getProperty

public Object getProperty(String name)
Description copied from interface: XMLStreamReader
Get the value of a feature/property from the underlying implementation

Specified by:
getProperty in interface XMLStreamReader
Parameters:
name - The name of the property, may not be null
Returns:
The value of the property
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLEventAllocator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.util
Interface XMLEventAllocator

public interface XMLEventAllocator

This interface defines a class that allows a user to register a way to allocate events given an XMLStreamReader. An implementation is not required to use the XMLEventFactory implementation but this is recommended. The XMLEventAllocator can be set on an XMLInputFactory using the property "javax.xml.stream.allocator"

Since:
1.6
See Also:
XMLInputFactory, XMLEventFactory

Method Summary
XMLEvent | allocate(XMLStreamReader reader) This method allocates an event given the current state of the XMLStreamReader.
void | allocate(XMLStreamReader reader, XMLEventConsumer consumer) This method allocates an event or set of events given the current state of the XMLStreamReader and adds the event or set of events to the consumer that was passed in.
XMLEventAllocator | newInstance() This method creates an instance of the XMLEventAllocator.

Method Detail

newInstance

XMLEventAllocator newInstance()
This method creates an instance of the XMLEventAllocator. This allows the XMLInputFactory to allocate a new instance per reader.

allocate

XMLEvent allocate(XMLStreamReader reader)
                  throws XMLStreamException
This method allocates an event given the current state of the XMLStreamReader. If this XMLEventAllocator does not have a one-to-one mapping between reader states and events this method will return null. This method must not modify the state of the XMLStreamReader.

Parameters:
reader - The XMLStreamReader to allocate from
Returns:
the event corresponding to the current reader state
Throws:
XMLStreamException

allocate

void allocate(XMLStreamReader reader,
              XMLEventConsumer consumer)
              throws XMLStreamException
This method allocates an event or set of events given the current state of the XMLStreamReader and adds the event or set of events to the consumer that was passed in. This method can be used to expand or contract reader states into event states. This method may modify the state of the XMLStreamReader.

Parameters:
reader - The XMLStreamReader to allocate from
consumer - The XMLEventConsumer to add to.
Throws:
XMLStreamException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLEventConsumer

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream.util
Interface XMLEventConsumer

All Known Subinterfaces:
XMLEventWriter
public interface XMLEventConsumer

This interface defines an event consumer interface. The contract of the of a consumer is to accept the event. This interface can be used to mark an object as able to receive events. Add may be called several times in immediate succession so a consumer must be able to cache events it hasn't processed yet.

Since:
1.6

Method Summary
 void add(XMLEvent event)
This method adds an event to the consumer.

Method Detail

add

void add(XMLEvent event)
         throws XMLStreamException
This method adds an event to the consumer. Calling this method invalidates the event parameter. The client application should discard all references to this event upon calling add. The behavior of an application that continues to use such references is undefined.

Parameters:
event - the event to add, may not be null
Throws:
XMLStreamException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


XMLEventFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream
Class XMLEventFactory

java.lang.Object
    extended by  javax.xml.stream.XMLEventFactory

public abstract class XMLEventFactory
extends Object

This interface defines a utility class for creating instances of XMLEvents

Since:
1.6
See Also:
StartElement, EndElement, ProcessingInstruction, Comment, Characters, StartDocument, EndDocument, DTD

Constructor Summary
protected XMLEventFactory()
Method Summary
abstract Attribute | createAttribute(QName name, String value) Create a new Attribute
abstract Attribute | createAttribute(String localName, String value) Create a new Attribute
abstract Attribute | createAttribute(String prefix, String namespaceURI, String localName, String value) Create a new Attribute
abstract Characters | createCData(String content) Create a Characters event with the CData flag set to true
abstract Characters | createCharacters(String content) Create a Characters event, this method does not check if the content is all whitespace.
abstract Comment | createComment(String text) Create a comment
abstract DTD | createDTD(String dtd) Create a document type definition event This string contains the entire document type declaration that matches the doctypedecl in the XML 1.0 specification
abstract EndDocument | createEndDocument() Creates a new instance of an EndDocument event
abstract EndElement | createEndElement(QName name, Iterator namespaces) Create a new EndElement
abstract EndElement | createEndElement(String prefix, String namespaceUri, String localName) Create a new EndElement
abstract EndElement | createEndElement(String prefix, String namespaceUri, String localName, Iterator namespaces) Create a new EndElement
abstract EntityReference | createEntityReference(String name, EntityDeclaration declaration) Creates a new instance of a EntityReference event
abstract Characters | createIgnorableSpace(String content) Create an ignorable space
abstract Namespace | createNamespace(String namespaceURI) Create a new default Namespace
abstract Namespace | createNamespace(String prefix, String namespaceUri) Create a new Namespace
abstract ProcessingInstruction | createProcessingInstruction(String target, String data) Create a processing instruction
abstract Characters | createSpace(String content) Create a Characters event with the isSpace flag set to true
abstract StartDocument | createStartDocument() Creates a new instance of a StartDocument event
abstract StartDocument | createStartDocument(String encoding) Creates a new instance of a StartDocument event
abstract StartDocument | createStartDocument(String encoding, String version) Creates a new instance of a StartDocument event
abstract StartDocument | createStartDocument(String encoding, String version, boolean standalone) Creates a new instance of a StartDocument event
abstract StartElement | createStartElement(QName name, Iterator attributes, Iterator namespaces) Create a new StartElement.
abstract StartElement | createStartElement(String prefix, String namespaceUri, String localName) Create a new StartElement.
abstract StartElement | createStartElement(String prefix, String namespaceUri, String localName, Iterator attributes, Iterator namespaces) Create a new StartElement.
abstract StartElement | createStartElement(String prefix, String namespaceUri, String localName, Iterator attributes, Iterator namespaces, NamespaceContext context) Create a new StartElement.
static XMLEventFactory | newInstance() Create a new instance of the factory
static XMLEventFactory | newInstance(String factoryId, ClassLoader classLoader) Create a new instance of the factory
abstract void | setLocation(Location location) This method allows setting of the Location on each event that is created by this factory.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XMLEventFactory

protected XMLEventFactory()
Method Detail

newInstance

public static XMLEventFactory newInstance()
                                   throws FactoryConfigurationError
Create a new instance of the factory

Throws:
FactoryConfigurationError - if an instance of this factory cannot be loaded

newInstance

public static XMLEventFactory newInstance(String factoryId,
                                          ClassLoader classLoader)
                                   throws FactoryConfigurationError
Create a new instance of the factory

Parameters:
factoryId - Name of the factory to find, same as a property name
classLoader - classLoader to use
Returns:
the factory implementation
Throws:
FactoryConfigurationError - if an instance of this factory cannot be loaded

setLocation

public abstract void setLocation(Location location)
This method allows setting of the Location on each event that is created by this factory. The values are copied by value into the events created by this factory. To reset the location information set the location to null.

Parameters:
location - the location to set on each event created

createAttribute

public abstract Attribute createAttribute(String prefix,
                                          String namespaceURI,
                                          String localName,
                                          String value)
Create a new Attribute

Parameters:
prefix - the prefix of this attribute, may not be null
namespaceURI - the attribute value is set to this value, may not be null
localName - the local name of the XML name of the attribute, localName cannot be null
value - the attribute value to set, may not be null
Returns:
the Attribute with specified values

createAttribute

public abstract Attribute createAttribute(String localName,
                                          String value)
Create a new Attribute

Parameters:
localName - the local name of the XML name of the attribute, localName cannot be null
value - the attribute value to set, may not be null
Returns:
the Attribute with specified values

createAttribute

public abstract Attribute createAttribute(QName name,
                                          String value)
Create a new Attribute

Parameters:
name - the qualified name of the attribute, may not be null
value - the attribute value to set, may not be null
Returns:
the Attribute with specified values

createNamespace

public abstract Namespace createNamespace(String namespaceURI)
Create a new default Namespace

Parameters:
namespaceURI - the default namespace uri
Returns:
the Namespace with the specified value

createNamespace

public abstract Namespace createNamespace(String prefix,
                                          String namespaceUri)
Create a new Namespace

Parameters:
prefix - the prefix of this namespace, may not be null
namespaceUri - the attribute value is set to this value, may not be null
Returns:
the Namespace with the specified values

createStartElement

public abstract StartElement createStartElement(QName name,
                                                Iterator attributes,
                                                Iterator namespaces)
Create a new StartElement. Namespaces can be added to this StartElement by passing in an Iterator that walks over a set of Namespace interfaces. Attributes can be added to this StartElement by passing an iterator that walks over a set of Attribute interfaces.

Parameters:
name - the qualified name of the attribute, may not be null
attributes - an optional unordered set of objects that implement Attribute to add to the new StartElement, may be null
namespaces - an optional unordered set of objects that implement Namespace to add to the new StartElement, may be null
Returns:
an instance of the requested StartElement

createStartElement

public abstract StartElement createStartElement(String prefix,
                                                String namespaceUri,
                                                String localName)
Create a new StartElement. This defaults the NamespaceContext to an empty NamespaceContext. Querying this event for its namespaces or attributes will result in an empty iterator being returned.

Parameters:
namespaceUri - the uri of the QName of the new StartElement
localName - the local name of the QName of the new StartElement
prefix - the prefix of the QName of the new StartElement
Returns:
an instance of the requested StartElement

createStartElement

public abstract StartElement createStartElement(String prefix,
                                                String namespaceUri,
                                                String localName,
                                                Iterator attributes,
                                                Iterator namespaces)
Create a new StartElement. Namespaces can be added to this StartElement by passing in an Iterator that walks over a set of Namespace interfaces. Attributes can be added to this StartElement by passing an iterator that walks over a set of Attribute interfaces.

Parameters:
namespaceUri - the uri of the QName of the new StartElement
localName - the local name of the QName of the new StartElement
prefix - the prefix of the QName of the new StartElement
attributes - an unordered set of objects that implement Attribute to add to the new StartElement
namespaces - an unordered set of objects that implement Namespace to add to the new StartElement
Returns:
an instance of the requested StartElement

createStartElement

public abstract StartElement createStartElement(String prefix,
                                                String namespaceUri,
                                                String localName,
                                                Iterator attributes,
                                                Iterator namespaces,
                                                NamespaceContext context)
Create a new StartElement. Namespaces can be added to this StartElement by passing in an Iterator that walks over a set of Namespace interfaces. Attributes can be added to this StartElement by passing an iterator that walks over a set of Attribute interfaces.

Parameters:
namespaceUri - the uri of the QName of the new StartElement
localName - the local name of the QName of the new StartElement
prefix - the prefix of the QName of the new StartElement
attributes - an unordered set of objects that implement Attribute to add to the new StartElement, may be null
namespaces - an unordered set of objects that implement Namespace to add to the new StartElement, may be null
context - the namespace context of this element
Returns:
an instance of the requested StartElement

createEndElement

public abstract EndElement createEndElement(QName name,
                                            Iterator namespaces)
Create a new EndElement

Parameters:
name - the qualified name of the EndElement
namespaces - an optional unordered set of objects that implement Namespace that have gone out of scope, may be null
Returns:
an instance of the requested EndElement

createEndElement

public abstract EndElement createEndElement(String prefix,
                                            String namespaceUri,
                                            String localName)
Create a new EndElement

Parameters:
namespaceUri - the uri of the QName of the new StartElement
localName - the local name of the QName of the new StartElement
prefix - the prefix of the QName of the new StartElement
Returns:
an instance of the requested EndElement

createEndElement

public abstract EndElement createEndElement(String prefix,
                                            String namespaceUri,
                                            String localName,
                                            Iterator namespaces)
Create a new EndElement

Parameters:
namespaceUri - the uri of the QName of the new StartElement
localName - the local name of the QName of the new StartElement
prefix - the prefix of the QName of the new StartElement
namespaces - an unordered set of objects that implement Namespace that have gone out of scope, may be null
Returns:
an instance of the requested EndElement

createCharacters

public abstract Characters createCharacters(String content)
Create a Characters event, this method does not check if the content is all whitespace. To create a space event use #createSpace(String)

Parameters:
content - the string to create
Returns:
a Characters event

createCData

public abstract Characters createCData(String content)
Create a Characters event with the CData flag set to true

Parameters:
content - the string to create
Returns:
a Characters event

createSpace

public abstract Characters createSpace(String content)
Create a Characters event with the isSpace flag set to true

Parameters:
content - the content of the space to create
Returns:
a Characters event

createIgnorableSpace

public abstract Characters createIgnorableSpace(String content)
Create an ignorable space

Parameters:
content - the space to create
Returns:
a Characters event

createStartDocument

public abstract StartDocument createStartDocument()
Creates a new instance of a StartDocument event

Returns:
a StartDocument event

createStartDocument

public abstract StartDocument createStartDocument(String encoding,
                                                  String version,
                                                  boolean standalone)
Creates a new instance of a StartDocument event

Parameters:
encoding - the encoding style
version - the XML version
standalone - the status of standalone may be set to "true" or "false"
Returns:
a StartDocument event

createStartDocument

public abstract StartDocument createStartDocument(String encoding,
                                                  String version)
Creates a new instance of a StartDocument event

Parameters:
encoding - the encoding style
version - the XML version
Returns:
a StartDocument event

createStartDocument

public abstract StartDocument createStartDocument(String encoding)
Creates a new instance of a StartDocument event

Parameters:
encoding - the encoding style
Returns:
a StartDocument event

createEndDocument

public abstract EndDocument createEndDocument()
Creates a new instance of an EndDocument event

Returns:
an EndDocument event

createEntityReference

public abstract EntityReference createEntityReference(String name,
                                                      EntityDeclaration declaration)
Creates a new instance of a EntityReference event

Parameters:
name - The name of the reference
declaration - the declaration for the event
Returns:
an EntityReference event

createComment

public abstract Comment createComment(String text)
Create a comment

Parameters:
text - The text of the comment a Comment event

createProcessingInstruction

public abstract ProcessingInstruction createProcessingInstruction(String target,
                                                                  String data)
Create a processing instruction

Parameters:
target - The target of the processing instruction
data - The text of the processing instruction
Returns:
a ProcessingInstruction event

createDTD

public abstract DTD createDTD(String dtd)
Create a document type definition event This string contains the entire document type declaration that matches the doctypedecl in the XML 1.0 specification

Parameters:
dtd - the text of the document type definition
Returns:
a DTD event
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLEventReader

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream
Interface XMLEventReader

All Superinterfaces:
Iterator
All Known Implementing Classes:
EventReaderDelegate
public interface XMLEventReader
extends Iterator

This is the top level interface for parsing XML Events. It provides the ability to peek at the next event and returns configuration information through the property interface.

Since:
1.6
See Also:
XMLInputFactory, XMLEventWriter

Method Summary
void | close() Frees any resources associated with this Reader.
String | getElementText() Reads the content of a text-only element.
Object | getProperty(String name) Get the value of a feature/property from the underlying implementation
boolean | hasNext() Check if there are more events.
XMLEvent | nextEvent() Get the next XMLEvent
XMLEvent | nextTag() Skips any insignificant space events until a START_ELEMENT or END_ELEMENT is reached.
XMLEvent | peek() Check the next XMLEvent without reading it from the stream.
Methods inherited from interface java.util.Iterator
next, remove

Method Detail

nextEvent

XMLEvent nextEvent()
                   throws XMLStreamException
Get the next XMLEvent

Throws:
XMLStreamException - if there is an error with the underlying XML.
NoSuchElementException - iteration has no more elements.
See Also:
XMLEvent

hasNext

boolean hasNext()
Check if there are more events. Returns true if there are more events and false otherwise.

Specified by:
hasNext in interface Iterator
Returns:
true if the event reader has more events, false otherwise

peek

XMLEvent peek()
              throws XMLStreamException
Check the next XMLEvent without reading it from the stream. Returns null if the stream is at EOF or has no more XMLEvents. A call to peek() will be equal to the next return of next().

Throws:
XMLStreamException
See Also:
XMLEvent

getElementText

String getElementText()
                      throws XMLStreamException
Reads the content of a text-only element. Precondition: the current event is START_ELEMENT. Postcondition: The current event is the corresponding END_ELEMENT.

Throws:
XMLStreamException - if the current event is not a START_ELEMENT or if a non text element is encountered

nextTag

XMLEvent nextTag()
                 throws XMLStreamException
Skips any insignificant space events until a START_ELEMENT or END_ELEMENT is reached. If anything other than space characters are encountered, an exception is thrown. This method should be used when processing element-only content because the parser is not able to recognize ignorable whitespace if the DTD is missing or not interpreted.

Throws:
XMLStreamException - if anything other than space characters are encountered

getProperty

Object getProperty(String name)
                   throws IllegalArgumentException
Get the value of a feature/property from the underlying implementation

Parameters:
name - The name of the property
Returns:
The value of the property
Throws:
IllegalArgumentException - if the property is not supported

close

void close()
           throws XMLStreamException
Frees any resources associated with this Reader. This method does not close the underlying input source.

Throws:
XMLStreamException - if there are errors freeing associated resources
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLEventWriter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream
Interface XMLEventWriter

All Superinterfaces:
XMLEventConsumer
public interface XMLEventWriter
extends XMLEventConsumer

This is the top level interface for writing XML documents. Instances of this interface are not required to validate the form of the XML.

Since:
1.6
See Also:
XMLEventReader, XMLEvent, Characters, ProcessingInstruction, StartElement, EndElement

Method Summary
void | add(XMLEvent event) Add an event to the output stream Adding a START_ELEMENT will open a new namespace scope that will be closed when the corresponding END_ELEMENT is written.
void | add(XMLEventReader reader) Adds an entire stream to an output stream, calls next() on the inputStream argument until hasNext() returns false This should be treated as a convenience method that will perform the following loop over all the events in an event reader and call add on each event.
void | close() Frees any resources associated with this stream
void | flush() Writes any cached events to the underlying output mechanism
NamespaceContext | getNamespaceContext() Returns the current namespace context.
String | getPrefix(String uri) Gets the prefix the uri is bound to
void | setDefaultNamespace(String uri) Binds a URI to the default namespace This URI is bound in the scope of the current START_ELEMENT / END_ELEMENT pair.
void | setNamespaceContext(NamespaceContext context) Sets the current namespace context for prefix and uri bindings.
void | setPrefix(String prefix, String uri) Sets the prefix the uri is bound to.

Method Detail

flush

void flush()
           throws XMLStreamException
Writes any cached events to the underlying output mechanism

Throws:
XMLStreamException

close

void close()
           throws XMLStreamException
Frees any resources associated with this stream

Throws:
XMLStreamException

add

void add(XMLEvent event)
         throws XMLStreamException
Add an event to the output stream Adding a START_ELEMENT will open a new namespace scope that will be closed when the corresponding END_ELEMENT is written.
Required and optional fields for events added to the writer
Event Type | Required Fields | Optional Fields | Required Behavior
START_ELEMENT | QName name | namespaces , attributes | A START_ELEMENT will be written by writing the name, namespaces, and attributes of the event in XML 1.0 valid syntax for START_ELEMENTs. The name is written by looking up the prefix for the namespace uri. The writer can be configured to respect prefixes of QNames. If the writer is respecting prefixes it must use the prefix set on the QName. The default behavior is to lookup the value for the prefix on the EventWriter's internal namespace context. Each attribute (if any) is written using the behavior specified in the attribute section of this table. Each namespace (if any) is written using the behavior specified in the namespace section of this table.
END_ELEMENT | Qname name | None | A well formed END_ELEMENT tag is written. The name is written by looking up the prefix for the namespace uri. The writer can be configured to respect prefixes of QNames. If the writer is respecting prefixes it must use the prefix set on the QName. The default behavior is to lookup the value for the prefix on the EventWriter's internal namespace context. If the END_ELEMENT name does not match the START_ELEMENT name an XMLStreamException is thrown.
ATTRIBUTE | QName name , String value | QName type | An attribute is written using the same algorithm to find the lexical form as used in START_ELEMENT. The default is to use double quotes to wrap attribute values and to escape any double quotes found in the value. The type value is ignored.
NAMESPACE | String prefix, String namespaceURI, boolean isDefaultNamespaceDeclaration | None | A namespace declaration is written. If the namespace is a default namespace declaration (isDefault is true) then xmlns="$namespaceURI" is written and the prefix is optional. If isDefault is false, the prefix must be declared and the writer must prepend xmlns to the prefix and write out a standard prefix declaration.
PROCESSING_INSTRUCTION | None | String target, String data | The data does not need to be present and may be null. Target is required and many not be null. The writer will write data section directly after the target, enclosed in appropriate XML 1.0 syntax
COMMENT | None | String comment | If the comment is present (not null) it is written, otherwise an an empty comment is written
START_DOCUMENT | None | String encoding , boolean standalone, String version | A START_DOCUMENT event is not required to be written to the stream. If present the attributes are written inside the appropriate XML declaration syntax
END_DOCUMENT | None | None | Nothing is written to the output
DTD | String DocumentTypeDefinition | None | The DocumentTypeDefinition is written to the output

Specified by:
add in interface XMLEventConsumer
Parameters:
event - the event to be added
Throws:
XMLStreamException

add

void add(XMLEventReader reader)
         throws XMLStreamException
Adds an entire stream to an output stream, calls next() on the inputStream argument until hasNext() returns false This should be treated as a convenience method that will perform the following loop over all the events in an event reader and call add on each event.

Parameters:
reader - the event stream to add to the output
Throws:
XMLStreamException

getPrefix

String getPrefix(String uri)
                 throws XMLStreamException
Gets the prefix the uri is bound to

Parameters:
uri - the uri to look up
Throws:
XMLStreamException

setPrefix

void setPrefix(String prefix,
               String uri)
               throws XMLStreamException
Sets the prefix the uri is bound to. This prefix is bound in the scope of the current START_ELEMENT / END_ELEMENT pair. If this method is called before a START_ELEMENT has been written the prefix is bound in the root scope.

Parameters:
prefix - the prefix to bind to the uri
uri - the uri to bind to the prefix
Throws:
XMLStreamException

setDefaultNamespace

void setDefaultNamespace(String uri)
                         throws XMLStreamException
Binds a URI to the default namespace This URI is bound in the scope of the current START_ELEMENT / END_ELEMENT pair. If this method is called before a START_ELEMENT has been written the uri is bound in the root scope.

Parameters:
uri - the uri to bind to the default namespace
Throws:
XMLStreamException

setNamespaceContext

void setNamespaceContext(NamespaceContext context)
                         throws XMLStreamException
Sets the current namespace context for prefix and uri bindings. This context becomes the root namespace context for writing and will replace the current root namespace context. Subsequent calls to setPrefix and setDefaultNamespace will bind namespaces using the context passed to the method as the root context for resolving namespaces.

Parameters:
context - the namespace context to use for this writer
Throws:
XMLStreamException

getNamespaceContext

NamespaceContext getNamespaceContext()
Returns the current namespace context.

Returns:
the current namespace context
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLInputFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream
Class XMLInputFactory

java.lang.Object
    extended by  javax.xml.stream.XMLInputFactory

public abstract class XMLInputFactory
extends Object

Defines an abstract implementation of a factory for getting streams. The following table defines the standard properties of this specification. Each property varies in the level of support required by each implementation. The level of support required is described in the 'Required' column.
Configuration parameters
Property Name | Behavior | Return type | Default Value | Required
javax.xml.stream.isValidating | Turns on/off implementation specific DTD validation | Boolean | False | No
javax.xml.stream.isNamespaceAware | Turns on/off namespace processing for XML 1.0 support | Boolean | True | True (required) / False (optional)
javax.xml.stream.isCoalescing | Requires the processor to coalesce adjacent character data | Boolean | False | Yes
javax.xml.stream.isReplacingEntityReferences | replace internal entity references with their replacement text and report them as characters | Boolean | True | Yes
javax.xml.stream.isSupportingExternalEntities | Resolve external parsed entities | Boolean | Unspecified | Yes
javax.xml.stream.supportDTD | Use this property to request processors that do not support DTDs | Boolean | True | Yes
javax.xml.stream.reporter | sets/gets the impl of the XMLReporter | javax.xml.stream.XMLReporter | Null | Yes
javax.xml.stream.resolver | sets/gets the impl of the XMLResolver interface | javax.xml.stream.XMLResolver | Null | Yes
javax.xml.stream.allocator | sets/gets the impl of the XMLEventAllocator interface | javax.xml.stream.util.XMLEventAllocator | Null | Yes

Since:
1.6
See Also:
XMLOutputFactory, XMLEventReader, XMLStreamReader, EventFilter, XMLReporter, XMLResolver, XMLEventAllocator

Field Summary
static String | ALLOCATOR The property used to set/get the implementation of the allocator
static String | IS_COALESCING The property that requires the parser to coalesce adjacent character data sections
static String | IS_NAMESPACE_AWARE The property used to turn on/off namespace support, this is to support XML 1.0 documents, only the true setting must be supported
static String | IS_REPLACING_ENTITY_REFERENCES Requires the parser to replace internal entity references with their replacement text and report them as characters
static String | IS_SUPPORTING_EXTERNAL_ENTITIES The property that requires the parser to resolve external parsed entities
static String | IS_VALIDATING The property used to turn on/off implementation specific validation
static String | REPORTER The property used to set/get the implementation of the XMLReporter interface
static String | RESOLVER The property used to set/get the implementation of the XMLResolver
static String | SUPPORT_DTD The property that requires the parser to support DTDs
Constructor Summary
protected XMLInputFactory()
Method Summary
abstract XMLEventReader | createFilteredReader(XMLEventReader reader, EventFilter filter) Create a filtered event reader that wraps the filter around the event reader
abstract XMLStreamReader | createFilteredReader(XMLStreamReader reader, StreamFilter filter) Create a filtered reader that wraps the filter around the reader
abstract XMLEventReader | createXMLEventReader(InputStream stream) Create a new XMLEventReader from a java.io.InputStream
abstract XMLEventReader | createXMLEventReader(InputStream stream, String encoding) Create a new XMLEventReader from a java.io.InputStream
abstract XMLEventReader | createXMLEventReader(Reader reader) Create a new XMLEventReader from a reader
abstract XMLEventReader | createXMLEventReader(Source source) Create a new XMLEventReader from a JAXP source.
abstract XMLEventReader | createXMLEventReader(String systemId, InputStream stream) Create a new XMLEventReader from a java.io.InputStream
abstract XMLEventReader | createXMLEventReader(String systemId, Reader reader) Create a new XMLEventReader from a reader
abstract XMLEventReader | createXMLEventReader(XMLStreamReader reader) Create a new XMLEventReader from an XMLStreamReader.
abstract XMLStreamReader | createXMLStreamReader(InputStream stream) Create a new XMLStreamReader from a java.io.InputStream
abstract XMLStreamReader | createXMLStreamReader(InputStream stream, String encoding) Create a new XMLStreamReader from a java.io.InputStream
abstract XMLStreamReader | createXMLStreamReader(Reader reader) Create a new XMLStreamReader from a reader
abstract XMLStreamReader | createXMLStreamReader(Source source) Create a new XMLStreamReader from a JAXP source.
abstract XMLStreamReader | createXMLStreamReader(String systemId, InputStream stream) Create a new XMLStreamReader from a java.io.InputStream
abstract XMLStreamReader | createXMLStreamReader(String systemId, Reader reader) Create a new XMLStreamReader from a java.io.InputStream
abstract XMLEventAllocator | getEventAllocator() Gets the allocator used by streams created with this factory
abstract Object | getProperty(String name) Get the value of a feature/property from the underlying implementation
abstract XMLReporter | getXMLReporter() The reporter that will be set on any XMLStreamReader or XMLEventReader created by this factory instance.
abstract XMLResolver | getXMLResolver() The resolver that will be set on any XMLStreamReader or XMLEventReader created by this factory instance.
abstract boolean | isPropertySupported(String name) Query the set of properties that this factory supports.
static XMLInputFactory | newInstance() Create a new instance of the factory.
static XMLInputFactory | newInstance(String factoryId, ClassLoader classLoader) Create a new instance of the factory
abstract void | setEventAllocator(XMLEventAllocator allocator) Set a user defined event allocator for events
abstract void | setProperty(String name, Object value) Allows the user to set specific feature/property on the underlying implementation.
abstract void | setXMLReporter(XMLReporter reporter) The reporter that will be set on any XMLStreamReader or XMLEventReader created by this factory instance.
abstract void | setXMLResolver(XMLResolver resolver) The resolver that will be set on any XMLStreamReader or XMLEventReader created by this factory instance.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

IS_NAMESPACE_AWARE

public static final String IS_NAMESPACE_AWARE
The property used to turn on/off namespace support, this is to support XML 1.0 documents, only the true setting must be supported

See Also:
Constant Field Values

IS_VALIDATING

public static final String IS_VALIDATING
The property used to turn on/off implementation specific validation

See Also:
Constant Field Values

IS_COALESCING

public static final String IS_COALESCING
The property that requires the parser to coalesce adjacent character data sections

See Also:
Constant Field Values

IS_REPLACING_ENTITY_REFERENCES

public static final String IS_REPLACING_ENTITY_REFERENCES
Requires the parser to replace internal entity references with their replacement text and report them as characters

See Also:
Constant Field Values

IS_SUPPORTING_EXTERNAL_ENTITIES

public static final String IS_SUPPORTING_EXTERNAL_ENTITIES
The property that requires the parser to resolve external parsed entities

See Also:
Constant Field Values

SUPPORT_DTD

public static final String SUPPORT_DTD
The property that requires the parser to support DTDs

See Also:
Constant Field Values

REPORTER

public static final String REPORTER
The property used to set/get the implementation of the XMLReporter interface

See Also:
Constant Field Values

RESOLVER

public static final String RESOLVER
The property used to set/get the implementation of the XMLResolver

See Also:
Constant Field Values

ALLOCATOR

public static final String ALLOCATOR
The property used to set/get the implementation of the allocator

See Also:
Constant Field Values
Constructor Detail

XMLInputFactory

protected XMLInputFactory()
Method Detail

newInstance

public static XMLInputFactory newInstance()
                                   throws FactoryConfigurationError
Create a new instance of the factory. This static method creates a new factory instance. This method uses the following ordered lookup procedure to determine the XMLInputFactory implementation class to load: Use the javax.xml.stream.XMLInputFactory system property. Use the properties file "lib/stax.properties" in the JRE directory. This configuration file is in standard java.util.Properties format and contains the fully qualified name of the implementation class with the key being the system property defined above. Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for a classname in the file META-INF/services/javax.xml.stream.XMLInputFactory in jars available to the runtime. Platform default XMLInputFactory instance. Once an application has obtained a reference to a XMLInputFactory it can use the factory to configure and obtain stream instances.

Throws:
FactoryConfigurationError - if an instance of this factory cannot be loaded

newInstance

public static XMLInputFactory newInstance(String factoryId,
                                          ClassLoader classLoader)
                                   throws FactoryConfigurationError
Create a new instance of the factory

Parameters:
factoryId - Name of the factory to find, same as a property name
classLoader - classLoader to use
Returns:
the factory implementation
Throws:
FactoryConfigurationError - if an instance of this factory cannot be loaded

createXMLStreamReader

public abstract XMLStreamReader createXMLStreamReader(Reader reader)
                                               throws XMLStreamException
Create a new XMLStreamReader from a reader

Parameters:
reader - the XML data to read from
Throws:
XMLStreamException

createXMLStreamReader

public abstract XMLStreamReader createXMLStreamReader(Source source)
                                               throws XMLStreamException
Create a new XMLStreamReader from a JAXP source. This method is optional.

Parameters:
source - the source to read from
Throws:
UnsupportedOperationException - if this method is not supported by this XMLInputFactory
XMLStreamException

createXMLStreamReader

public abstract XMLStreamReader createXMLStreamReader(InputStream stream)
                                               throws XMLStreamException
Create a new XMLStreamReader from a java.io.InputStream

Parameters:
stream - the InputStream to read from
Throws:
XMLStreamException

createXMLStreamReader

public abstract XMLStreamReader createXMLStreamReader(InputStream stream,
                                                      String encoding)
                                               throws XMLStreamException
Create a new XMLStreamReader from a java.io.InputStream

Parameters:
stream - the InputStream to read from
encoding - the character encoding of the stream
Throws:
XMLStreamException

createXMLStreamReader

public abstract XMLStreamReader createXMLStreamReader(String systemId,
                                                      InputStream stream)
                                               throws XMLStreamException
Create a new XMLStreamReader from a java.io.InputStream

Parameters:
systemId - the system ID of the stream
stream - the InputStream to read from
Throws:
XMLStreamException

createXMLStreamReader

public abstract XMLStreamReader createXMLStreamReader(String systemId,
                                                      Reader reader)
                                               throws XMLStreamException
Create a new XMLStreamReader from a java.io.InputStream

Parameters:
systemId - the system ID of the stream
reader - the InputStream to read from
Throws:
XMLStreamException

createXMLEventReader

public abstract XMLEventReader createXMLEventReader(Reader reader)
                                             throws XMLStreamException
Create a new XMLEventReader from a reader

Parameters:
reader - the XML data to read from
Throws:
XMLStreamException

createXMLEventReader

public abstract XMLEventReader createXMLEventReader(String systemId,
                                                    Reader reader)
                                             throws XMLStreamException
Create a new XMLEventReader from a reader

Parameters:
systemId - the system ID of the input
reader - the XML data to read from
Throws:
XMLStreamException

createXMLEventReader

public abstract XMLEventReader createXMLEventReader(XMLStreamReader reader)
                                             throws XMLStreamException
Create a new XMLEventReader from an XMLStreamReader. After being used to construct the XMLEventReader instance returned from this method the XMLStreamReader must not be used.

Parameters:
reader - the XMLStreamReader to read from (may not be modified)
Returns:
a new XMLEventReader
Throws:
XMLStreamException

createXMLEventReader

public abstract XMLEventReader createXMLEventReader(Source source)
                                             throws XMLStreamException
Create a new XMLEventReader from a JAXP source. Support of this method is optional.

Parameters:
source - the source to read from
Throws:
UnsupportedOperationException - if this method is not supported by this XMLInputFactory
XMLStreamException

createXMLEventReader

public abstract XMLEventReader createXMLEventReader(InputStream stream)
                                             throws XMLStreamException
Create a new XMLEventReader from a java.io.InputStream

Parameters:
stream - the InputStream to read from
Throws:
XMLStreamException

createXMLEventReader

public abstract XMLEventReader createXMLEventReader(InputStream stream,
                                                    String encoding)
                                             throws XMLStreamException
Create a new XMLEventReader from a java.io.InputStream

Parameters:
stream - the InputStream to read from
encoding - the character encoding of the stream
Throws:
XMLStreamException

createXMLEventReader

public abstract XMLEventReader createXMLEventReader(String systemId,
                                                    InputStream stream)
                                             throws XMLStreamException
Create a new XMLEventReader from a java.io.InputStream

Parameters:
systemId - the system ID of the stream
stream - the InputStream to read from
Throws:
XMLStreamException

createFilteredReader

public abstract XMLStreamReader createFilteredReader(XMLStreamReader reader,
                                                     StreamFilter filter)
                                              throws XMLStreamException
Create a filtered reader that wraps the filter around the reader

Parameters:
reader - the reader to filter
filter - the filter to apply to the reader
Throws:
XMLStreamException

createFilteredReader

public abstract XMLEventReader createFilteredReader(XMLEventReader reader,
                                                    EventFilter filter)
                                             throws XMLStreamException
Create a filtered event reader that wraps the filter around the event reader

Parameters:
reader - the event reader to wrap
filter - the filter to apply to the event reader
Throws:
XMLStreamException

getXMLResolver

public abstract XMLResolver getXMLResolver()
The resolver that will be set on any XMLStreamReader or XMLEventReader created by this factory instance.

setXMLResolver

public abstract void setXMLResolver(XMLResolver resolver)
The resolver that will be set on any XMLStreamReader or XMLEventReader created by this factory instance.

Parameters:
resolver - the resolver to use to resolve references

getXMLReporter

public abstract XMLReporter getXMLReporter()
The reporter that will be set on any XMLStreamReader or XMLEventReader created by this factory instance.

setXMLReporter

public abstract void setXMLReporter(XMLReporter reporter)
The reporter that will be set on any XMLStreamReader or XMLEventReader created by this factory instance.

Parameters:
reporter - the resolver to use to report non fatal errors

setProperty

public abstract void setProperty(String name,
                                 Object value)
                          throws IllegalArgumentException
Allows the user to set specific feature/property on the underlying implementation. The underlying implementation is not required to support every setting of every property in the specification and may use IllegalArgumentException to signal that an unsupported property may not be set with the specified value.

Parameters:
name - The name of the property (may not be null)
value - The value of the property
Throws:
IllegalArgumentException - if the property is not supported

getProperty

public abstract Object getProperty(String name)
                            throws IllegalArgumentException
Get the value of a feature/property from the underlying implementation

Parameters:
name - The name of the property (may not be null)
Returns:
The value of the property
Throws:
IllegalArgumentException - if the property is not supported

isPropertySupported

public abstract boolean isPropertySupported(String name)
Query the set of properties that this factory supports.

Parameters:
name - The name of the property (may not be null)
Returns:
true if the property is supported and false otherwise

setEventAllocator

public abstract void setEventAllocator(XMLEventAllocator allocator)
Set a user defined event allocator for events

Parameters:
allocator - the user defined allocator

getEventAllocator

public abstract XMLEventAllocator getEventAllocator()
Gets the allocator used by streams created with this factory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLOutputFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream
Class XMLOutputFactory

java.lang.Object
    extended by  javax.xml.stream.XMLOutputFactory

public abstract class XMLOutputFactory
extends Object

Defines an abstract implementation of a factory for getting XMLEventWriters and XMLStreamWriters. The following table defines the standard properties of this specification. Each property varies in the level of support required by each implementation. The level of support required is described in the 'Required' column.
Configuration parameters
Property Name | Behavior | Return type | Default Value | Required
javax.xml.stream.isRepairingNamespaces | defaults prefixes on the output side | Boolean | False | Yes

The following paragraphs describe the namespace and prefix repair algorithm:

The property can be set with the following code line: setProperty("javax.xml.stream.isRepairingNamespaces",new Boolean(true|false));

This property specifies that the writer default namespace prefix declarations. The default value is false.

If a writer isRepairingNamespaces it will create a namespace declaration on the current StartElement for any attribute that does not currently have a namespace declaration in scope. If the StartElement has a uri but no prefix specified a prefix will be assigned, if the prefix has not been declared in a parent of the current StartElement it will be declared on the current StartElement. If the defaultNamespace is bound and in scope and the default namespace matches the URI of the attribute or StartElement QName no prefix will be assigned.

If an element or attribute name has a prefix, but is not bound to any namespace URI, then the prefix will be removed during serialization.

If element and/or attribute names in the same start or empty-element tag are bound to different namespace URIs and are using the same prefix then the element or the first occurring attribute retains the original prefix and the following attributes have their prefixes replaced with a new prefix that is bound to the namespace URIs of those attributes.

If an element or attribute name uses a prefix that is bound to a different URI than that inherited from the namespace context of the parent of that element and there is no namespace declaration in the context of the current element then such a namespace declaration is added.

If an element or attribute name is bound to a prefix and there is a namespace declaration that binds that prefix to a different URI then that namespace declaration is either removed if the correct mapping is inherited from the parent context of that element, or changed to the namespace URI of the element or attribute using that prefix.

Since:
1.6
See Also:
XMLInputFactory, XMLEventWriter, XMLStreamWriter

Field Summary
static String IS_REPAIRING_NAMESPACES
Property used to set prefix defaulting on the output side
Constructor Summary
protected XMLOutputFactory()
Method Summary
abstract XMLEventWriter | createXMLEventWriter(OutputStream stream) Create a new XMLEventWriter that writes to a stream
abstract XMLEventWriter | createXMLEventWriter(OutputStream stream, String encoding) Create a new XMLEventWriter that writes to a stream
abstract XMLEventWriter | createXMLEventWriter(Result result) Create a new XMLEventWriter that writes to a JAXP result.
abstract XMLEventWriter | createXMLEventWriter(Writer stream) Create a new XMLEventWriter that writes to a writer
abstract XMLStreamWriter | createXMLStreamWriter(OutputStream stream) Create a new XMLStreamWriter that writes to a stream
abstract XMLStreamWriter | createXMLStreamWriter(OutputStream stream, String encoding) Create a new XMLStreamWriter that writes to a stream
abstract XMLStreamWriter | createXMLStreamWriter(Result result) Create a new XMLStreamWriter that writes to a JAXP result.
abstract XMLStreamWriter | createXMLStreamWriter(Writer stream) Create a new XMLStreamWriter that writes to a writer
abstract Object | getProperty(String name) Get a feature/property on the underlying implementation
abstract boolean | isPropertySupported(String name) Query the set of properties that this factory supports.
static XMLOutputFactory | newInstance() Create a new instance of the factory.
static XMLInputFactory | newInstance(String factoryId, ClassLoader classLoader) Create a new instance of the factory.
abstract void | setProperty(String name, Object value) Allows the user to set specific features/properties on the underlying implementation.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

IS_REPAIRING_NAMESPACES

public static final String IS_REPAIRING_NAMESPACES
Property used to set prefix defaulting on the output side

See Also:
Constant Field Values
Constructor Detail

XMLOutputFactory

protected XMLOutputFactory()
Method Detail

newInstance

public static XMLOutputFactory newInstance()
                                    throws FactoryConfigurationError
Create a new instance of the factory.

Throws:
FactoryConfigurationError - if an instance of this factory cannot be loaded

newInstance

public static XMLInputFactory newInstance(String factoryId,
                                          ClassLoader classLoader)
                                   throws FactoryConfigurationError
Create a new instance of the factory.

Parameters:
factoryId - Name of the factory to find, same as a property name
classLoader - classLoader to use
Returns:
the factory implementation
Throws:
FactoryConfigurationError - if an instance of this factory cannot be loaded

createXMLStreamWriter

public abstract XMLStreamWriter createXMLStreamWriter(Writer stream)
                                               throws XMLStreamException
Create a new XMLStreamWriter that writes to a writer

Parameters:
stream - the writer to write to
Throws:
XMLStreamException

createXMLStreamWriter

public abstract XMLStreamWriter createXMLStreamWriter(OutputStream stream)
                                               throws XMLStreamException
Create a new XMLStreamWriter that writes to a stream

Parameters:
stream - the stream to write to
Throws:
XMLStreamException

createXMLStreamWriter

public abstract XMLStreamWriter createXMLStreamWriter(OutputStream stream,
                                                      String encoding)
                                               throws XMLStreamException
Create a new XMLStreamWriter that writes to a stream

Parameters:
stream - the stream to write to
encoding - the encoding to use
Throws:
XMLStreamException

createXMLStreamWriter

public abstract XMLStreamWriter createXMLStreamWriter(Result result)
                                               throws XMLStreamException
Create a new XMLStreamWriter that writes to a JAXP result. This method is optional.

Parameters:
result - the result to write to
Throws:
UnsupportedOperationException - if this method is not supported by this XMLOutputFactory
XMLStreamException

createXMLEventWriter

public abstract XMLEventWriter createXMLEventWriter(Result result)
                                             throws XMLStreamException
Create a new XMLEventWriter that writes to a JAXP result. This method is optional.

Parameters:
result - the result to write to
Throws:
UnsupportedOperationException - if this method is not supported by this XMLOutputFactory
XMLStreamException

createXMLEventWriter

public abstract XMLEventWriter createXMLEventWriter(OutputStream stream)
                                             throws XMLStreamException
Create a new XMLEventWriter that writes to a stream

Parameters:
stream - the stream to write to
Throws:
XMLStreamException

createXMLEventWriter

public abstract XMLEventWriter createXMLEventWriter(OutputStream stream,
                                                    String encoding)
                                             throws XMLStreamException
Create a new XMLEventWriter that writes to a stream

Parameters:
stream - the stream to write to
encoding - the encoding to use
Throws:
XMLStreamException

createXMLEventWriter

public abstract XMLEventWriter createXMLEventWriter(Writer stream)
                                             throws XMLStreamException
Create a new XMLEventWriter that writes to a writer

Parameters:
stream - the stream to write to
Throws:
XMLStreamException

setProperty

public abstract void setProperty(String name,
                                 Object value)
                          throws IllegalArgumentException
Allows the user to set specific features/properties on the underlying implementation.

Parameters:
name - The name of the property
value - The value of the property
Throws:
IllegalArgumentException - if the property is not supported

getProperty

public abstract Object getProperty(String name)
                            throws IllegalArgumentException
Get a feature/property on the underlying implementation

Parameters:
name - The name of the property
Returns:
The value of the property
Throws:
IllegalArgumentException - if the property is not supported

isPropertySupported

public abstract boolean isPropertySupported(String name)
Query the set of properties that this factory supports.

Parameters:
name - The name of the property (may not be null)
Returns:
true if the property is supported and false otherwise
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLReporter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream
Interface XMLReporter

public interface XMLReporter

This interface is used to report non-fatal errors. Only warnings should be echoed through this interface.

Since:
1.6

Method Summary
 void report(String message, String errorType, Object relatedInformation, Location location)
Report the desired message in an application specific format.

Method Detail

report

void report(String message,
            String errorType,
            Object relatedInformation,
            Location location)
            throws XMLStreamException
Report the desired message in an application specific format. Only warnings and non-fatal errors should be reported through this interface. Fatal errors should be thrown as XMLStreamException.

Parameters:
message - the error message
errorType - an implementation defined error type
relatedInformation - information related to the error, if available
location - the location of the error, if available
Throws:
XMLStreamException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLResolver

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream
Interface XMLResolver

public interface XMLResolver

This interface is used to resolve resources during an XML parse. If an application wishes to perform custom entity resolution it must register an instance of this interface with the XMLInputFactory using the setXMLResolver method.

Since:
1.6

Method Summary
 Object resolveEntity(String publicID, String systemID, String baseURI, String namespace)
Retrieves a resource.

Method Detail

resolveEntity

Object resolveEntity(String publicID,
                     String systemID,
                     String baseURI,
                     String namespace)
                     throws XMLStreamException
Retrieves a resource. This resource can be of the following three return types: (1) java.io.InputStream (2) javax.xml.stream.XMLStreamReader (3) java.xml.stream.XMLEventReader. If this method returns null the processor will attempt to resolve the entity using its default mechanism.

Parameters:
publicID - The public identifier of the external entity being referenced, or null if none was supplied.
systemID - The system identifier of the external entity being referenced.
baseURI - Absolute base URI associated with systemId.
namespace - The namespace of the entity to resolve.
Returns:
The resource requested or null.
Throws:
XMLStreamException - if there was a failure attempting to resolve the resource.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLStreamConstants

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream
Interface XMLStreamConstants

All Known Subinterfaces:
Attribute, Characters, Comment, DTD, EndDocument, EndElement, EntityDeclaration, EntityReference, Namespace, NotationDeclaration, ProcessingInstruction, StartDocument, StartElement, XMLEvent, XMLStreamReader
All Known Implementing Classes:
StreamReaderDelegate
public interface XMLStreamConstants

This interface declares the constants used in this API. Numbers in the range 0 to 256 are reserved for the specification, user defined events must use event codes outside that range.

Since:
1.6

Field Summary
static int | ATTRIBUTE Indicates an event is an attribute
static int | CDATA Indicates an event is a CDATA section
static int | CHARACTERS Indicates an event is characters
static int | COMMENT Indicates an event is a comment
static int | DTD Indicates an event is a DTD
static int | END_DOCUMENT Indicates an event is an end document
static int | END_ELEMENT Indicates an event is an end element
static int | ENTITY_DECLARATION Indicates a Entity Declaration
static int | ENTITY_REFERENCE Indicates an event is an entity reference
static int | NAMESPACE Indicates the event is a namespace declaration
static int | NOTATION_DECLARATION Indicates a Notation
static int | PROCESSING_INSTRUCTION Indicates an event is a processing instruction
static int | SPACE The characters are white space (see [XML], 2.10 "White Space Handling").
static int | START_DOCUMENT Indicates an event is a start document
static int | START_ELEMENT Indicates an event is a start element

Field Detail

START_ELEMENT

static final int START_ELEMENT
Indicates an event is a start element

See Also:
StartElement, Constant Field Values

END_ELEMENT

static final int END_ELEMENT
Indicates an event is an end element

See Also:
EndElement, Constant Field Values

PROCESSING_INSTRUCTION

static final int PROCESSING_INSTRUCTION
Indicates an event is a processing instruction

See Also:
ProcessingInstruction, Constant Field Values

CHARACTERS

static final int CHARACTERS
Indicates an event is characters

See Also:
Characters, Constant Field Values

COMMENT

static final int COMMENT
Indicates an event is a comment

See Also:
Comment, Constant Field Values

SPACE

static final int SPACE
The characters are white space (see [XML], 2.10 "White Space Handling"). Events are only reported as SPACE if they are ignorable white space. Otherwise they are reported as CHARACTERS.

See Also:
Characters, Constant Field Values

START_DOCUMENT

static final int START_DOCUMENT
Indicates an event is a start document

See Also:
StartDocument, Constant Field Values

END_DOCUMENT

static final int END_DOCUMENT
Indicates an event is an end document

See Also:
EndDocument, Constant Field Values

ENTITY_REFERENCE

static final int ENTITY_REFERENCE
Indicates an event is an entity reference

See Also:
EntityReference, Constant Field Values

ATTRIBUTE

static final int ATTRIBUTE
Indicates an event is an attribute

See Also:
Attribute, Constant Field Values

DTD

static final int DTD
Indicates an event is a DTD

See Also:
DTD, Constant Field Values

CDATA

static final int CDATA
Indicates an event is a CDATA section

See Also:
Characters, Constant Field Values

NAMESPACE

static final int NAMESPACE
Indicates the event is a namespace declaration

See Also:
Namespace, Constant Field Values

NOTATION_DECLARATION

static final int NOTATION_DECLARATION
Indicates a Notation

See Also:
NotationDeclaration, Constant Field Values

ENTITY_DECLARATION

static final int ENTITY_DECLARATION
Indicates a Entity Declaration

See Also:
NotationDeclaration, Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLStreamException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream
Class XMLStreamException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.stream.XMLStreamException
All Implemented Interfaces:
Serializable
public class XMLStreamException
extends Exception

The base exception for unexpected processing errors. This Exception class is used to report well-formedness errors as well as unexpected processing conditions.

Since:
1.6
See Also:
Serialized Form

Field Summary
protected Location | location
protected Throwable | nested
Constructor Summary
XMLStreamException()
Default constructor
XMLStreamException(String msg)
Construct an exception with the assocated message.
XMLStreamException(String msg, Location location)
Construct an exception with the assocated message, exception and location.
XMLStreamException(String msg, Location location, Throwable th)
Construct an exception with the assocated message, exception and location.
XMLStreamException(String msg, Throwable th)
Construct an exception with the assocated message and exception
XMLStreamException(Throwable th)
Construct an exception with the assocated exception
Method Summary
Location | getLocation() Gets the location of the exception
Throwable | getNestedException() Gets the nested exception.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

nested

protected Throwable nested

location

protected Location location
Constructor Detail

XMLStreamException

public XMLStreamException()
Default constructor

XMLStreamException

public XMLStreamException(String msg)
Construct an exception with the assocated message.

Parameters:
msg - the message to report

XMLStreamException

public XMLStreamException(Throwable th)
Construct an exception with the assocated exception

Parameters:
th - a nested exception

XMLStreamException

public XMLStreamException(String msg,
                          Throwable th)
Construct an exception with the assocated message and exception

Parameters:
th - a nested exception
msg - the message to report

XMLStreamException

public XMLStreamException(String msg,
                          Location location,
                          Throwable th)
Construct an exception with the assocated message, exception and location.

Parameters:
th - a nested exception
msg - the message to report
location - the location of the error

XMLStreamException

public XMLStreamException(String msg,
                          Location location)
Construct an exception with the assocated message, exception and location.

Parameters:
msg - the message to report
location - the location of the error
Method Detail

getNestedException

public Throwable getNestedException()
Gets the nested exception.

Returns:
Nested exception

getLocation

public Location getLocation()
Gets the location of the exception

Returns:
the location of the exception, may be null if none is available
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLStreamReader

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream
Interface XMLStreamReader

All Superinterfaces:
XMLStreamConstants
All Known Implementing Classes:
StreamReaderDelegate
public interface XMLStreamReader
extends XMLStreamConstants

The XMLStreamReader interface allows forward, read-only access to XML. It is designed to be the lowest level and most efficient way to read XML data.

The XMLStreamReader is designed to iterate over XML using next() and hasNext(). The data can be accessed using methods such as getEventType(), getNamespaceURI(), getLocalName() and getText();

The next() method causes the reader to read the next parse event. The next() method returns an integer which identifies the type of event just read.

The event type can be determined using getEventType().

Parsing events are defined as the XML Declaration, a DTD, start tag, character data, white space, end tag, comment, or processing instruction. An attribute or namespace event may be encountered at the root level of a document as the result of a query operation.

For XML 1.0 compliance an XML processor must pass the identifiers of declared unparsed entities, notation declarations and their associated identifiers to the application. This information is provided through the property API on this interface. The following two properties allow access to this information: javax.xml.stream.notations and javax.xml.stream.entities. When the current event is a DTD the following call will return a list of Notations List l = (List) getProperty("javax.xml.stream.notations"); The following call will return a list of entity declarations: List l = (List) getProperty("javax.xml.stream.entities"); These properties can only be accessed during a DTD event and are defined to return null if the information is not available.

The following table describes which methods are valid in what state. If a method is called in an invalid state the method will throw a java.lang.IllegalStateException.
Valid methods for each state
Event Type | Valid Methods
All States | getProperty(), hasNext(), require(), close(), getNamespaceURI(), isStartElement(), isEndElement(), isCharacters(), isWhiteSpace(), getNamespaceContext(), getEventType(),getLocation(), hasText(), hasName()
START_ELEMENT | next(), getName(), getLocalName(), hasName(), getPrefix(), getAttributeXXX(), isAttributeSpecified(), getNamespaceXXX(), getElementText(), nextTag()
ATTRIBUTE | next(), nextTag() getAttributeXXX(), isAttributeSpecified(),
NAMESPACE | next(), nextTag() getNamespaceXXX()
END_ELEMENT | next(), getName(), getLocalName(), hasName(), getPrefix(), getNamespaceXXX(), nextTag()
CHARACTERS | next(), getTextXXX(), nextTag()
CDATA | next(), getTextXXX(), nextTag()
COMMENT | next(), getTextXXX(), nextTag()
SPACE | next(), getTextXXX(), nextTag()
START_DOCUMENT | next(), getEncoding(), getVersion(), isStandalone(), standaloneSet(), getCharacterEncodingScheme(), nextTag()
END_DOCUMENT | close()
PROCESSING_INSTRUCTION | next(), getPITarget(), getPIData(), nextTag()
ENTITY_REFERENCE | next(), getLocalName(), getText(), nextTag()
DTD | next(), getText(), nextTag()

Since:
1.6
See Also:
XMLEvent, XMLInputFactory, XMLStreamWriter

Field Summary
Fields inherited from interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
Method Summary
 void close()
Frees any resources associated with this Reader.
 int getAttributeCount()
Returns the count of attributes on this START_ELEMENT, this method is only valid on a START_ELEMENT or ATTRIBUTE.
 String getAttributeLocalName(int index)
Returns the localName of the attribute at the provided index
 QName getAttributeName(int index)
Returns the qname of the attribute at the provided index
 String getAttributeNamespace(int index)
Returns the namespace of the attribute at the provided index
 String getAttributePrefix(int index)
Returns the prefix of this attribute at the provided index
 String getAttributeType(int index)
Returns the XML type of the attribute at the provided index
 String getAttributeValue(int index)
Returns the value of the attribute at the index
 String getAttributeValue(String namespaceURI, String localName)
Returns the normalized attribute value of the attribute with the namespace and localName If the namespaceURI is null the namespace is not checked for equality
 String getCharacterEncodingScheme()
Returns the character encoding declared on the xml declaration Returns null if none was declared
 String getElementText()
Reads the content of a text-only element, an exception is thrown if this is not a text-only element.
 String getEncoding()
Return input encoding if known or null if unknown.
 int getEventType()
Returns an integer code that indicates the type of the event the cursor is pointing to.
 String getLocalName()
Returns the (local) name of the current event.
 Location getLocation()
Return the current location of the processor.
 QName getName()
Returns a QName for the current START_ELEMENT or END_ELEMENT event
 NamespaceContext getNamespaceContext()
Returns a read only namespace context for the current position.
 int getNamespaceCount()
Returns the count of namespaces declared on this START_ELEMENT or END_ELEMENT, this method is only valid on a START_ELEMENT, END_ELEMENT or NAMESPACE.
 String getNamespacePrefix(int index)
Returns the prefix for the namespace declared at the index.
 String getNamespaceURI()
If the current event is a START_ELEMENT or END_ELEMENT this method returns the URI of the prefix or the default namespace.
 String getNamespaceURI(int index)
Returns the uri for the namespace declared at the index.
 String getNamespaceURI(String prefix)
Return the uri for the given prefix.
 String getPIData()
Get the data section of a processing instruction
 String getPITarget()
Get the target of a processing instruction
 String getPrefix()
Returns the prefix of the current event or null if the event does not have a prefix
 Object getProperty(String name)
Get the value of a feature/property from the underlying implementation
 String getText()
Returns the current value of the parse event as a string, this returns the string value of a CHARACTERS event, returns the value of a COMMENT, the replacement value for an ENTITY_REFERENCE, the string value of a CDATA section, the string value for a SPACE event, or the String value of the internal subset of the DTD.
 char[] getTextCharacters()
Returns an array which contains the characters from this event.
 int getTextCharacters(int sourceStart, char[] target, int targetStart, int length)
Gets the the text associated with a CHARACTERS, SPACE or CDATA event.
 int getTextLength()
Returns the length of the sequence of characters for this Text event within the text character array.
 int getTextStart()
Returns the offset into the text character array where the first character (of this text event) is stored.
 String getVersion()
Get the xml version declared on the xml declaration Returns null if none was declared
 boolean hasName()
returns true if the current event has a name (is a START_ELEMENT or END_ELEMENT) returns false otherwise
 boolean hasNext()
Returns true if there are more parsing events and false if there are no more events.
 boolean hasText()
Return true if the current event has text, false otherwise The following events have text: CHARACTERS,DTD ,ENTITY_REFERENCE, COMMENT, SPACE
 boolean isAttributeSpecified(int index)
Returns a boolean which indicates if this attribute was created by default
 boolean isCharacters()
Returns true if the cursor points to a character data event
 boolean isEndElement()
Returns true if the cursor points to an end tag (otherwise false)
 boolean isStandalone()
Get the standalone declaration from the xml declaration
 boolean isStartElement()
Returns true if the cursor points to a start tag (otherwise false)
 boolean isWhiteSpace()
Returns true if the cursor points to a character data event that consists of all whitespace
 int next()
Get next parsing event - a processor may return all contiguous character data in a single chunk, or it may split it into several chunks.
 int nextTag()
Skips any white space (isWhiteSpace() returns true), COMMENT, or PROCESSING_INSTRUCTION, until a START_ELEMENT or END_ELEMENT is reached.
 void require(int type, String namespaceURI, String localName)
Test if the current event is of the given type and if the namespace and name match the current namespace and name of the current event.
 boolean standaloneSet()
Checks if standalone was set in the document

Method Detail

getProperty

Object getProperty(String name)
                   throws IllegalArgumentException
Get the value of a feature/property from the underlying implementation

Parameters:
name - The name of the property, may not be null
Returns:
The value of the property
Throws:
IllegalArgumentException - if name is null

next

int next()
         throws XMLStreamException
Get next parsing event - a processor may return all contiguous character data in a single chunk, or it may split it into several chunks. If the property javax.xml.stream.isCoalescing is set to true element content must be coalesced and only one CHARACTERS event must be returned for contiguous element content or CDATA Sections. By default entity references must be expanded and reported transparently to the application. An exception will be thrown if an entity reference cannot be expanded. If element content is empty (i.e. content is "") then no CHARACTERS event will be reported.

Given the following XML:
<foo><!--description-->content text<![CDATA[<greeting>Hello</greeting>]]>other content</foo>
The behavior of calling next() when being on foo will be:
1- the comment (COMMENT)
2- then the characters section (CHARACTERS)
3- then the CDATA section (another CHARACTERS)
4- then the next characters section (another CHARACTERS)
5- then the END_ELEMENT

NOTE: empty element (such as <tag/>) will be reported with two separate events: START_ELEMENT, END_ELEMENT - This preserves parsing equivalency of empty element to <tag></tag>. This method will throw an IllegalStateException if it is called after hasNext() returns false.

Returns:
the integer code corresponding to the current parse event
Throws:
NoSuchElementException - if this is called when hasNext() returns false
XMLStreamException - if there is an error processing the underlying XML source
See Also:
XMLEvent

require

void require(int type,
             String namespaceURI,
             String localName)
             throws XMLStreamException
Test if the current event is of the given type and if the namespace and name match the current namespace and name of the current event. If the namespaceURI is null it is not checked for equality, if the localName is null it is not checked for equality.

Parameters:
type - the event type
namespaceURI - the uri of the event, may be null
localName - the localName of the event, may be null
Throws:
XMLStreamException - if the required values are not matched.

getElementText

String getElementText()
                      throws XMLStreamException
Reads the content of a text-only element, an exception is thrown if this is not a text-only element. Regardless of value of javax.xml.stream.isCoalescing this method always returns coalesced content.
Precondition: the current event is START_ELEMENT.
Postcondition: the current event is the corresponding END_ELEMENT.
The method does the following (implementations are free to optimized but must do equivalent processing):
 if(getEventType() != XMLStreamConstants.START_ELEMENT) {
 throw new XMLStreamException(
 "parser must be on START_ELEMENT to read next text", getLocation());
 }
 int eventType = next();
 StringBuffer content = new StringBuffer();
 while(eventType != XMLStreamConstants.END_ELEMENT ) {
 if(eventType == XMLStreamConstants.CHARACTERS
 || eventType == XMLStreamConstants.CDATA
 || eventType == XMLStreamConstants.SPACE
 || eventType == XMLStreamConstants.ENTITY_REFERENCE) {
 buf.append(getText());
 } else if(eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
 || eventType == XMLStreamConstants.COMMENT) {
 // skipping
 } else if(eventType == XMLStreamConstants.END_DOCUMENT) {
 throw new XMLStreamException(
 "unexpected end of document when reading element text content", this);
 } else if(eventType == XMLStreamConstants.START_ELEMENT) {
 throw new XMLStreamException(
 "element text content may not contain START_ELEMENT", getLocation());
 } else {
 throw new XMLStreamException(
 "Unexpected event type "+eventType, getLocation());
 }
 eventType = next();
 }
 return buf.toString();

Throws:
XMLStreamException - if the current event is not a START_ELEMENT or if a non text element is encountered

nextTag

int nextTag()
            throws XMLStreamException
Skips any white space (isWhiteSpace() returns true), COMMENT, or PROCESSING_INSTRUCTION, until a START_ELEMENT or END_ELEMENT is reached. If other than white space characters, COMMENT, PROCESSING_INSTRUCTION, START_ELEMENT, END_ELEMENT are encountered, an exception is thrown. This method should be used when processing element-only content seperated by white space.
Precondition: none
Postcondition: the current event is START_ELEMENT or END_ELEMENT and cursor may have moved over any whitespace event.
Essentially it does the following (implementations are free to optimized but must do equivalent processing):
 int eventType = next();
 while((eventType == XMLStreamConstants.CHARACTERS && isWhiteSpace()) // skip whitespace
 || (eventType == XMLStreamConstants.CDATA && isWhiteSpace())
 // skip whitespace
 || eventType == XMLStreamConstants.SPACE
 || eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
 || eventType == XMLStreamConstants.COMMENT
 ) {
 eventType = next();
 }
 if (eventType != XMLStreamConstants.START_ELEMENT && eventType != XMLStreamConstants.END_ELEMENT) {
 throw new String XMLStreamException("expected start or end tag", getLocation());
 }
 return eventType;

Returns:
the event type of the element read (START_ELEMENT or END_ELEMENT)
Throws:
XMLStreamException - if the current event is not white space, PROCESSING_INSTRUCTION, START_ELEMENT or END_ELEMENT
NoSuchElementException - if this is called when hasNext() returns false

hasNext

boolean hasNext()
                throws XMLStreamException
Returns true if there are more parsing events and false if there are no more events. This method will return false if the current state of the XMLStreamReader is END_DOCUMENT

Returns:
true if there are more events, false otherwise
Throws:
XMLStreamException - if there is a fatal error detecting the next state

close

void close()
           throws XMLStreamException
Frees any resources associated with this Reader. This method does not close the underlying input source.

Throws:
XMLStreamException - if there are errors freeing associated resources

getNamespaceURI

String getNamespaceURI(String prefix)
Return the uri for the given prefix. The uri returned depends on the current state of the processor.

NOTE:The 'xml' prefix is bound as defined in Namespaces in XML specification to "http://www.w3.org/XML/1998/namespace".

NOTE: The 'xmlns' prefix must be resolved to following namespace http://www.w3.org/2000/xmlns/

Parameters:
prefix - The prefix to lookup, may not be null
Returns:
the uri bound to the given prefix or null if it is not bound
Throws:
IllegalArgumentException - if the prefix is null

isStartElement

boolean isStartElement()
Returns true if the cursor points to a start tag (otherwise false)

Returns:
true if the cursor points to a start tag, false otherwise

isEndElement

boolean isEndElement()
Returns true if the cursor points to an end tag (otherwise false)

Returns:
true if the cursor points to an end tag, false otherwise

isCharacters

boolean isCharacters()
Returns true if the cursor points to a character data event

Returns:
true if the cursor points to character data, false otherwise

isWhiteSpace

boolean isWhiteSpace()
Returns true if the cursor points to a character data event that consists of all whitespace

Returns:
true if the cursor points to all whitespace, false otherwise

getAttributeValue

String getAttributeValue(String namespaceURI,
                         String localName)
Returns the normalized attribute value of the attribute with the namespace and localName If the namespaceURI is null the namespace is not checked for equality

Parameters:
namespaceURI - the namespace of the attribute
localName - the local name of the attribute, cannot be null
Returns:
returns the value of the attribute , returns null if not found
Throws:
IllegalStateException - if this is not a START_ELEMENT or ATTRIBUTE

getAttributeCount

int getAttributeCount()
Returns the count of attributes on this START_ELEMENT, this method is only valid on a START_ELEMENT or ATTRIBUTE. This count excludes namespace definitions. Attribute indices are zero-based.

Returns:
returns the number of attributes
Throws:
IllegalStateException - if this is not a START_ELEMENT or ATTRIBUTE

getAttributeName

QName getAttributeName(int index)
Returns the qname of the attribute at the provided index

Parameters:
index - the position of the attribute
Returns:
the QName of the attribute
Throws:
IllegalStateException - if this is not a START_ELEMENT or ATTRIBUTE

getAttributeNamespace

String getAttributeNamespace(int index)
Returns the namespace of the attribute at the provided index

Parameters:
index - the position of the attribute
Returns:
the namespace URI (can be null)
Throws:
IllegalStateException - if this is not a START_ELEMENT or ATTRIBUTE

getAttributeLocalName

String getAttributeLocalName(int index)
Returns the localName of the attribute at the provided index

Parameters:
index - the position of the attribute
Returns:
the localName of the attribute
Throws:
IllegalStateException - if this is not a START_ELEMENT or ATTRIBUTE

getAttributePrefix

String getAttributePrefix(int index)
Returns the prefix of this attribute at the provided index

Parameters:
index - the position of the attribute
Returns:
the prefix of the attribute
Throws:
IllegalStateException - if this is not a START_ELEMENT or ATTRIBUTE

getAttributeType

String getAttributeType(int index)
Returns the XML type of the attribute at the provided index

Parameters:
index - the position of the attribute
Returns:
the XML type of the attribute
Throws:
IllegalStateException - if this is not a START_ELEMENT or ATTRIBUTE

getAttributeValue

String getAttributeValue(int index)
Returns the value of the attribute at the index

Parameters:
index - the position of the attribute
Returns:
the attribute value
Throws:
IllegalStateException - if this is not a START_ELEMENT or ATTRIBUTE

isAttributeSpecified

boolean isAttributeSpecified(int index)
Returns a boolean which indicates if this attribute was created by default

Parameters:
index - the position of the attribute
Returns:
true if this is a default attribute
Throws:
IllegalStateException - if this is not a START_ELEMENT or ATTRIBUTE

getNamespaceCount

int getNamespaceCount()
Returns the count of namespaces declared on this START_ELEMENT or END_ELEMENT, this method is only valid on a START_ELEMENT, END_ELEMENT or NAMESPACE. On an END_ELEMENT the count is of the namespaces that are about to go out of scope. This is the equivalent of the information reported by SAX callback for an end element event.

Returns:
returns the number of namespace declarations on this specific element
Throws:
IllegalStateException - if this is not a START_ELEMENT, END_ELEMENT or NAMESPACE

getNamespacePrefix

String getNamespacePrefix(int index)
Returns the prefix for the namespace declared at the index. Returns null if this is the default namespace declaration

Parameters:
index - the position of the namespace declaration
Returns:
returns the namespace prefix
Throws:
IllegalStateException - if this is not a START_ELEMENT, END_ELEMENT or NAMESPACE

getNamespaceURI

String getNamespaceURI(int index)
Returns the uri for the namespace declared at the index.

Parameters:
index - the position of the namespace declaration
Returns:
returns the namespace uri
Throws:
IllegalStateException - if this is not a START_ELEMENT, END_ELEMENT or NAMESPACE

getNamespaceContext

NamespaceContext getNamespaceContext()
Returns a read only namespace context for the current position. The context is transient and only valid until a call to next() changes the state of the reader.

Returns:
return a namespace context

getEventType

int getEventType()
Returns an integer code that indicates the type of the event the cursor is pointing to.

getText

String getText()
Returns the current value of the parse event as a string, this returns the string value of a CHARACTERS event, returns the value of a COMMENT, the replacement value for an ENTITY_REFERENCE, the string value of a CDATA section, the string value for a SPACE event, or the String value of the internal subset of the DTD. If an ENTITY_REFERENCE has been resolved, any character data will be reported as CHARACTERS events.

Returns:
the current text or null
Throws:
IllegalStateException - if this state is not a valid text state.

getTextCharacters

char[] getTextCharacters()
Returns an array which contains the characters from this event. This array should be treated as read-only and transient. I.e. the array will contain the text characters until the XMLStreamReader moves on to the next event. Attempts to hold onto the character array beyond that time or modify the contents of the array are breaches of the contract for this interface.

Returns:
the current text or an empty array
Throws:
IllegalStateException - if this state is not a valid text state.

getTextCharacters

int getTextCharacters(int sourceStart,
                      char[] target,
                      int targetStart,
                      int length)
                      throws XMLStreamException
Gets the the text associated with a CHARACTERS, SPACE or CDATA event. Text starting a "sourceStart" is copied into "target" starting at "targetStart". Up to "length" characters are copied. The number of characters actually copied is returned. The "sourceStart" argument must be greater or equal to 0 and less than or equal to the number of characters associated with the event. Usually, one requests text starting at a "sourceStart" of 0. If the number of characters actually copied is less than the "length", then there is no more text. Otherwise, subsequent calls need to be made until all text has been retrieved. For example:
int length = 1024;
char[] myBuffer = new char[ length ];

for ( int sourceStart = 0 ; ; sourceStart += length )
{
   int nCopied = stream.getTextCharacters( sourceStart, myBuffer, 0, length );

  if (nCopied < length)
      break;
}
 XMLStreamException may be thrown if there are any XML errors in the underlying source. The "targetStart" argument must be greater than or equal to 0 and less than the length of "target", Length must be greater than 0 and "targetStart + length" must be less than or equal to length of "target".

Parameters:
sourceStart - the index of the first character in the source array to copy
target - the destination array
targetStart - the start offset in the target array
length - the number of characters to copy
Returns:
the number of characters actually copied
Throws:
XMLStreamException - if the underlying XML source is not well-formed
IndexOutOfBoundsException - if targetStart < 0 or > than the length of target
IndexOutOfBoundsException - if length < 0 or targetStart + length > length of target
UnsupportedOperationException - if this method is not supported
NullPointerException - is if target is null

getTextStart

int getTextStart()
Returns the offset into the text character array where the first character (of this text event) is stored.

Throws:
IllegalStateException - if this state is not a valid text state.

getTextLength

int getTextLength()
Returns the length of the sequence of characters for this Text event within the text character array.

Throws:
IllegalStateException - if this state is not a valid text state.

getEncoding

String getEncoding()
Return input encoding if known or null if unknown.

Returns:
the encoding of this instance or null

hasText

boolean hasText()
Return true if the current event has text, false otherwise The following events have text: CHARACTERS,DTD ,ENTITY_REFERENCE, COMMENT, SPACE

getLocation

Location getLocation()
Return the current location of the processor. If the Location is unknown the processor should return an implementation of Location that returns -1 for the location and null for the publicId and systemId. The location information is only valid until next() is called.

getName

QName getName()
Returns a QName for the current START_ELEMENT or END_ELEMENT event

Returns:
the QName for the current START_ELEMENT or END_ELEMENT event
Throws:
IllegalStateException - if this is not a START_ELEMENT or END_ELEMENT

getLocalName

String getLocalName()
Returns the (local) name of the current event. For START_ELEMENT or END_ELEMENT returns the (local) name of the current element. For ENTITY_REFERENCE it returns entity name. The current event must be START_ELEMENT or END_ELEMENT, or ENTITY_REFERENCE

Returns:
the localName
Throws:
IllegalStateException - if this not a START_ELEMENT, END_ELEMENT or ENTITY_REFERENCE

hasName

boolean hasName()
returns true if the current event has a name (is a START_ELEMENT or END_ELEMENT) returns false otherwise

getNamespaceURI

String getNamespaceURI()
If the current event is a START_ELEMENT or END_ELEMENT this method returns the URI of the prefix or the default namespace. Returns null if the event does not have a prefix.

Returns:
the URI bound to this elements prefix, the default namespace, or null

getPrefix

String getPrefix()
Returns the prefix of the current event or null if the event does not have a prefix

Returns:
the prefix or null

getVersion

String getVersion()
Get the xml version declared on the xml declaration Returns null if none was declared

Returns:
the XML version or null

isStandalone

boolean isStandalone()
Get the standalone declaration from the xml declaration

Returns:
true if this is standalone, or false otherwise

standaloneSet

boolean standaloneSet()
Checks if standalone was set in the document

Returns:
true if standalone was set in the document, or false otherwise

getCharacterEncodingScheme

String getCharacterEncodingScheme()
Returns the character encoding declared on the xml declaration Returns null if none was declared

Returns:
the encoding declared in the document or null

getPITarget

String getPITarget()
Get the target of a processing instruction

Returns:
the target or null

getPIData

String getPIData()
Get the data section of a processing instruction

Returns:
the data or null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLStreamWriter

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.stream
Interface XMLStreamWriter

public interface XMLStreamWriter

The XMLStreamWriter interface specifies how to write XML. The XMLStreamWriter does not perform well formedness checking on its input. However the writeCharacters method is required to escape & , < and > For attribute values the writeAttribute method will escape the above characters plus " to ensure that all character content and attribute values are well formed. Each NAMESPACE and ATTRIBUTE must be individually written.
XML Namespaces, javax.xml.stream.isRepairingNamespaces and write method behaviour
Method | isRepairingNamespaces == true | isRepairingNamespaces == false
namespaceURI bound | namespaceURI unbound | namespaceURI bound | namespaceURI unbound
writeAttribute(namespaceURI, localName, value) | prefix:localName="value" [1] | xmlns:{generated}="namespaceURI" {generated}:localName="value" | prefix:localName="value" [1] | XMLStreamException
writeAttribute(prefix, namespaceURI, localName, value) bound to same prefix:
prefix:localName="value" [1]

bound to different prefix:
xmlns:{generated}="namespaceURI" {generated}:localName="value" 		xmlns:prefix="namespaceURI" prefix:localName="value" [3] bound to same prefix:
prefix:localName="value" [1][2]

bound to different prefix:
XMLStreamException[2] 		xmlns:prefix="namespaceURI" prefix:localName="value" [2][5]
writeStartElement(namespaceURI, localName)

writeEmptyElement(namespaceURI, localName) 		<prefix:localName> [1] <{generated}:localName xmlns:{generated}="namespaceURI"> <prefix:localName> [1] XMLStreamException
writeStartElement(prefix, localName, namespaceURI)

writeEmptyElement(prefix, localName, namespaceURI) 		bound to same prefix:
<prefix:localName> [1]

bound to different prefix:
<{generated}:localName xmlns:{generated}="namespaceURI"> 		<prefix:localName xmlns:prefix="namespaceURI"> [4] bound to same prefix:
<prefix:localName> [1]

bound to different prefix:
XMLStreamException 		<prefix:localName>
Notes:
  • [1] if namespaceURI == default Namespace URI, then no prefix is written
  • [2] if prefix == "" || null && namespaceURI == "", then no prefix or Namespace declaration is generated or written
  • [3] if prefix == "" || null, then a prefix is randomly generated
  • [4] if prefix == "" || null, then it is treated as the default Namespace and no prefix is generated or written, an xmlns declaration is generated and written if the namespaceURI is unbound
  • [5] if prefix == "" || null, then it is treated as an invalid attempt to define the default Namespace and an XMLStreamException is thrown

Since:
1.6
See Also:
XMLOutputFactory, XMLStreamReader

Method Summary
void | close() Close this writer and free any resources associated with the writer.
void | flush() Write any cached data to the underlying output mechanism.
NamespaceContext | getNamespaceContext() Returns the current namespace context.
String | getPrefix(String uri) Gets the prefix the uri is bound to
Object | getProperty(String name) Get the value of a feature/property from the underlying implementation
void | setDefaultNamespace(String uri) Binds a URI to the default namespace This URI is bound in the scope of the current START_ELEMENT / END_ELEMENT pair.
void | setNamespaceContext(NamespaceContext context) Sets the current namespace context for prefix and uri bindings.
void | setPrefix(String prefix, String uri) Sets the prefix the uri is bound to.
void | writeAttribute(String localName, String value) Writes an attribute to the output stream without a prefix.
void | writeAttribute(String namespaceURI, String localName, String value) Writes an attribute to the output stream
void | writeAttribute(String prefix, String namespaceURI, String localName, String value) Writes an attribute to the output stream
void | writeCData(String data) Writes a CData section
void | writeCharacters(char[] text, int start, int len) Write text to the output
void | writeCharacters(String text) Write text to the output
void | writeComment(String data) Writes an xml comment with the data enclosed
void | writeDefaultNamespace(String namespaceURI) Writes the default namespace to the stream
void | writeDTD(String dtd) Write a DTD section.
void | writeEmptyElement(String localName) Writes an empty element tag to the output
void | writeEmptyElement(String namespaceURI, String localName) Writes an empty element tag to the output
void | writeEmptyElement(String prefix, String localName, String namespaceURI) Writes an empty element tag to the output
void | writeEndDocument() Closes any start tags and writes corresponding end tags.
void | writeEndElement() Writes an end tag to the output relying on the internal state of the writer to determine the prefix and local name of the event.
void | writeEntityRef(String name) Writes an entity reference
void | writeNamespace(String prefix, String namespaceURI) Writes a namespace to the output stream If the prefix argument to this method is the empty string, "xmlns", or null this method will delegate to writeDefaultNamespace
void | writeProcessingInstruction(String target) Writes a processing instruction
void | writeProcessingInstruction(String target, String data) Writes a processing instruction
void | writeStartDocument() Write the XML Declaration.
void | writeStartDocument(String version) Write the XML Declaration.
void | writeStartDocument(String encoding, String version) Write the XML Declaration.
void | writeStartElement(String localName) Writes a start tag to the output.
void | writeStartElement(String namespaceURI, String localName) Writes a start tag to the output
void | writeStartElement(String prefix, String localName, String namespaceURI) Writes a start tag to the output

Method Detail

writeStartElement

void writeStartElement(String localName)
                       throws XMLStreamException
Writes a start tag to the output. All writeStartElement methods open a new scope in the internal namespace context. Writing the corresponding EndElement causes the scope to be closed.

Parameters:
localName - local name of the tag, may not be null
Throws:
XMLStreamException

writeStartElement

void writeStartElement(String namespaceURI,
                       String localName)
                       throws XMLStreamException
Writes a start tag to the output

Parameters:
namespaceURI - the namespaceURI of the prefix to use, may not be null
localName - local name of the tag, may not be null
Throws:
XMLStreamException - if the namespace URI has not been bound to a prefix and javax.xml.stream.isRepairingNamespaces has not been set to true

writeStartElement

void writeStartElement(String prefix,
                       String localName,
                       String namespaceURI)
                       throws XMLStreamException
Writes a start tag to the output

Parameters:
localName - local name of the tag, may not be null
prefix - the prefix of the tag, may not be null
namespaceURI - the uri to bind the prefix to, may not be null
Throws:
XMLStreamException

writeEmptyElement

void writeEmptyElement(String namespaceURI,
                       String localName)
                       throws XMLStreamException
Writes an empty element tag to the output

Parameters:
namespaceURI - the uri to bind the tag to, may not be null
localName - local name of the tag, may not be null
Throws:
XMLStreamException - if the namespace URI has not been bound to a prefix and javax.xml.stream.isRepairingNamespaces has not been set to true

writeEmptyElement

void writeEmptyElement(String prefix,
                       String localName,
                       String namespaceURI)
                       throws XMLStreamException
Writes an empty element tag to the output

Parameters:
prefix - the prefix of the tag, may not be null
localName - local name of the tag, may not be null
namespaceURI - the uri to bind the tag to, may not be null
Throws:
XMLStreamException

writeEmptyElement

void writeEmptyElement(String localName)
                       throws XMLStreamException
Writes an empty element tag to the output

Parameters:
localName - local name of the tag, may not be null
Throws:
XMLStreamException

writeEndElement

void writeEndElement()
                     throws XMLStreamException
Writes an end tag to the output relying on the internal state of the writer to determine the prefix and local name of the event.

Throws:
XMLStreamException

writeEndDocument

void writeEndDocument()
                      throws XMLStreamException
Closes any start tags and writes corresponding end tags.

Throws:
XMLStreamException

close

void close()
           throws XMLStreamException
Close this writer and free any resources associated with the writer. This must not close the underlying output stream.

Throws:
XMLStreamException

flush

void flush()
           throws XMLStreamException
Write any cached data to the underlying output mechanism.

Throws:
XMLStreamException

writeAttribute

void writeAttribute(String localName,
                    String value)
                    throws XMLStreamException
Writes an attribute to the output stream without a prefix.

Parameters:
localName - the local name of the attribute
value - the value of the attribute
Throws:
IllegalStateException - if the current state does not allow Attribute writing
XMLStreamException

writeAttribute

void writeAttribute(String prefix,
                    String namespaceURI,
                    String localName,
                    String value)
                    throws XMLStreamException
Writes an attribute to the output stream

Parameters:
prefix - the prefix for this attribute
namespaceURI - the uri of the prefix for this attribute
localName - the local name of the attribute
value - the value of the attribute
Throws:
IllegalStateException - if the current state does not allow Attribute writing
XMLStreamException - if the namespace URI has not been bound to a prefix and javax.xml.stream.isRepairingNamespaces has not been set to true

writeAttribute

void writeAttribute(String namespaceURI,
                    String localName,
                    String value)
                    throws XMLStreamException
Writes an attribute to the output stream

Parameters:
namespaceURI - the uri of the prefix for this attribute
localName - the local name of the attribute
value - the value of the attribute
Throws:
IllegalStateException - if the current state does not allow Attribute writing
XMLStreamException - if the namespace URI has not been bound to a prefix and javax.xml.stream.isRepairingNamespaces has not been set to true

writeNamespace

void writeNamespace(String prefix,
                    String namespaceURI)
                    throws XMLStreamException
Writes a namespace to the output stream If the prefix argument to this method is the empty string, "xmlns", or null this method will delegate to writeDefaultNamespace

Parameters:
prefix - the prefix to bind this namespace to
namespaceURI - the uri to bind the prefix to
Throws:
IllegalStateException - if the current state does not allow Namespace writing
XMLStreamException

writeDefaultNamespace

void writeDefaultNamespace(String namespaceURI)
                           throws XMLStreamException
Writes the default namespace to the stream

Parameters:
namespaceURI - the uri to bind the default namespace to
Throws:
IllegalStateException - if the current state does not allow Namespace writing
XMLStreamException

writeComment

void writeComment(String data)
                  throws XMLStreamException
Writes an xml comment with the data enclosed

Parameters:
data - the data contained in the comment, may be null
Throws:
XMLStreamException

writeProcessingInstruction

void writeProcessingInstruction(String target)
                                throws XMLStreamException
Writes a processing instruction

Parameters:
target - the target of the processing instruction, may not be null
Throws:
XMLStreamException

writeProcessingInstruction

void writeProcessingInstruction(String target,
                                String data)
                                throws XMLStreamException
Writes a processing instruction

Parameters:
target - the target of the processing instruction, may not be null
data - the data contained in the processing instruction, may not be null
Throws:
XMLStreamException

writeCData

void writeCData(String data)
                throws XMLStreamException
Writes a CData section

Parameters:
data - the data contained in the CData Section, may not be null
Throws:
XMLStreamException

writeDTD

void writeDTD(String dtd)
              throws XMLStreamException
Write a DTD section. This string represents the entire doctypedecl production from the XML 1.0 specification.

Parameters:
dtd - the DTD to be written
Throws:
XMLStreamException

writeEntityRef

void writeEntityRef(String name)
                    throws XMLStreamException
Writes an entity reference

Parameters:
name - the name of the entity
Throws:
XMLStreamException

writeStartDocument

void writeStartDocument()
                        throws XMLStreamException
Write the XML Declaration. Defaults the XML version to 1.0, and the encoding to utf-8

Throws:
XMLStreamException

writeStartDocument

void writeStartDocument(String version)
                        throws XMLStreamException
Write the XML Declaration. Defaults the XML version to 1.0

Parameters:
version - version of the xml document
Throws:
XMLStreamException

writeStartDocument

void writeStartDocument(String encoding,
                        String version)
                        throws XMLStreamException
Write the XML Declaration. Note that the encoding parameter does not set the actual encoding of the underlying output. That must be set when the instance of the XMLStreamWriter is created using the XMLOutputFactory

Parameters:
encoding - encoding of the xml declaration
version - version of the xml document
Throws:
XMLStreamException - If given encoding does not match encoding of the underlying stream

writeCharacters

void writeCharacters(String text)
                     throws XMLStreamException
Write text to the output

Parameters:
text - the value to write
Throws:
XMLStreamException

writeCharacters

void writeCharacters(char[] text,
                     int start,
                     int len)
                     throws XMLStreamException
Write text to the output

Parameters:
text - the value to write
start - the starting position in the array
len - the number of characters to write
Throws:
XMLStreamException

getPrefix

String getPrefix(String uri)
                 throws XMLStreamException
Gets the prefix the uri is bound to

Returns:
the prefix or null
Throws:
XMLStreamException

setPrefix

void setPrefix(String prefix,
               String uri)
               throws XMLStreamException
Sets the prefix the uri is bound to. This prefix is bound in the scope of the current START_ELEMENT / END_ELEMENT pair. If this method is called before a START_ELEMENT has been written the prefix is bound in the root scope.

Parameters:
prefix - the prefix to bind to the uri, may not be null
uri - the uri to bind to the prefix, may be null
Throws:
XMLStreamException

setDefaultNamespace

void setDefaultNamespace(String uri)
                         throws XMLStreamException
Binds a URI to the default namespace This URI is bound in the scope of the current START_ELEMENT / END_ELEMENT pair. If this method is called before a START_ELEMENT has been written the uri is bound in the root scope.

Parameters:
uri - the uri to bind to the default namespace, may be null
Throws:
XMLStreamException

setNamespaceContext

void setNamespaceContext(NamespaceContext context)
                         throws XMLStreamException
Sets the current namespace context for prefix and uri bindings. This context becomes the root namespace context for writing and will replace the current root namespace context. Subsequent calls to setPrefix and setDefaultNamespace will bind namespaces using the context passed to the method as the root context for resolving namespaces. This method may only be called once at the start of the document. It does not cause the namespaces to be declared. If a namespace URI to prefix mapping is found in the namespace context it is treated as declared and the prefix may be used by the StreamWriter.

Parameters:
context - the namespace context to use for this writer, may not be null
Throws:
XMLStreamException

getNamespaceContext

NamespaceContext getNamespaceContext()
Returns the current namespace context.

Returns:
the current NamespaceContext

getProperty

Object getProperty(String name)
                   throws IllegalArgumentException
Get the value of a feature/property from the underlying implementation

Parameters:
name - The name of the property, may not be null
Returns:
The value of the property
Throws:
IllegalArgumentException - if the property is not supported
NullPointerException - if the name is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


transform

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.transform

This package defines the generic APIs for processing transformation instructions, and performing a transformation from source to result.

See:
Description

Interface Summary
ErrorListener | To provide customized error handling, implement this interface and use the setErrorListener method to register an instance of the implmentation with the Transformer.
Result | An object that implements this interface contains the information needed to build a transformation result tree.
Source | An object that implements this interface contains the information needed to act as source input (XML source or transformation instructions).
SourceLocator | This interface is primarily for the purposes of reporting where an error occurred in the XML source or transformation instructions.
Templates | An object that implements this interface is the runtime representation of processed transformation instructions.
URIResolver | An object that implements this interface that can be called by the processor to turn a URI used in document(), xsl:import, or xsl:include into a Source object.

Class Summary
OutputKeys | Provides string constants that can be used to set output properties for a Transformer, or to retrieve output properties from a Transformer or Templates object.
Transformer | An instance of this abstract class can transform a source tree into a result tree.
TransformerFactory | A TransformerFactory instance can be used to create Transformer and Templates objects.

Exception Summary
TransformerConfigurationException | Indicates a serious configuration error.
TransformerException | This class specifies an exceptional condition that occured during the transformation process.

Error Summary
TransformerFactoryConfigurationError Thrown when a problem with configuration with the Transformer Factories exists.

Package javax.xml.transform Description

This package defines the generic APIs for processing transformation instructions, and performing a transformation from source to result. These interfaces have no dependencies on SAX or the DOM standard, and try to make as few assumptions as possible about the details of the source and result of a transformation. It achieves this by defining Source and Result interfaces.

To define concrete classes for the user, the API defines specializations of the interfaces found at the root level. These interfaces are found in javax.xml.transform.sax, javax.xml.transform.dom, and javax.xml.transform.stream.

Creating Objects

The API allows a concrete TransformerFactory object to be created from the static function TransformerFactory.newInstance().

Specification of Inputs and Outputs

This API defines two interface objects called Source and Result. In order to pass Source and Result objects to the interfaces, concrete classes must be used. Three concrete representations are defined for each of these objects: StreamSource and StreamResult, SAXSource and SAXResult, and DOMSource and DOMResult. Each of these objects defines a FEATURE string (which is i the form of a URL), which can be passed into TransformerFactory.getFeature(java.lang.String) to see if the given type of Source or Result object is supported. For instance, to test if a DOMSource and a StreamResult is supported, you can apply the following test.

TransformerFactory tfactory = TransformerFactory.newInstance();
if (tfactory.getFeature(DOMSource.FEATURE) && tfactory.getFeature(StreamResult.FEATURE)) {
...
}

Qualified Name Representation

Namespaces present something of a problem area when dealing with XML objects. Qualified Names appear in XML markup as prefixed names. But the prefixes themselves do not hold identity. Rather, it is the URIs that they contextually map to that hold the identity. Therefore, when passing a Qualified Name like "xyz:foo" among Java programs, one must provide a means to map "xyz" to a namespace.

One solution has been to create a "QName" object that holds the namespace URI, as well as the prefix and local name, but this is not always an optimal solution, as when, for example, you want to use unique strings as keys in a dictionary object. Not having a string representation also makes it difficult to specify a namespaced identity outside the context of an XML document.

In order to pass namespaced values to transformations, for instance when setting a property or a parameter on a Transformer object, this specification defines that a String "qname" object parameter be passed as two-part string, the namespace URI enclosed in curly braces ({}), followed by the local name. If the qname has a null URI, then the String object only contains the local name. An application can safely check for a non-null URI by testing to see if the first character of the name is a '{' character.

For example, if a URI and local name were obtained from an element defined with <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>, then the Qualified Name would be "{http://xyz.foo.com/yada/baz.html}foo". Note that the prefix is lost.

Result Tree Serialization

Serialization of the result tree to a stream can be controlled with the Transformer.setOutputProperties(java.util.Properties) and the Transformer.setOutputProperty(java.lang.String, java.lang.String) methods. These properties only apply to stream results, they have no effect when the result is a DOM tree or SAX event stream.

Strings that match the XSLT specification for xsl:output attributes can be referenced from the OutputKeys class. Other strings can be specified as well. If the transformer does not recognize an output key, a IllegalArgumentException is thrown, unless the key name is namespace qualified. Output key names that are namespace qualified are always allowed, although they may be ignored by some implementations.

If all that is desired is the simple identity transformation of a source to a result, then TransformerFactory provides a TransformerFactory.newTransformer() method with no arguments. This method creates a Transformer that effectively copies the source to the result. This method may be used to create a DOM from SAX events or to create an XML or HTML stream from a DOM or SAX events.

Exceptions and Error Reporting

The transformation API throw three types of specialized exceptions. A TransformerFactoryConfigurationError is parallel to the FactoryConfigurationError, and is thrown when a configuration problem with the TransformerFactory exists. This error will typically be thrown when the transformation factory class specified with the "javax.xml.transform.TransformerFactory" system property cannot be found or instantiated.

A TransformerConfigurationException may be thrown if for any reason a Transformer can not be created. A TransformerConfigurationException may be thrown if there is a syntax error in the transformation instructions, for example when TransformerFactory.newTransformer(javax.xml.transform.Source) is called.

TransformerException is a general exception that occurs during the course of a transformation. A transformer exception may wrap another exception, and if any of the TransformerException.printStackTrace() methods are called on it, it will produce a list of stack dumps, starting from the most recent. The transformer exception also provides a SourceLocator object which indicates where in the source tree or transformation instructions the error occurred. TransformerException.getMessageAndLocation() may be called to get an error message with location info, and TransformerException.getLocationAsString() may be called to get just the location string.

Transformation warnings and errors are sent to an ErrorListener, at which point the application may decide to report the error or warning, and may decide to throw an Exception for a non-fatal error. The ErrorListener may be set via TransformerFactory.setErrorListener(javax.xml.transform.ErrorListener) for reporting errors that have to do with syntax errors in the transformation instructions, or via Transformer.setErrorListener(javax.xml.transform.ErrorListener) to report errors that occur during the transformation. The ErrorListener on both objects will always be valid and non-null, whether set by the application or a default implementation provided by the processor. The default implementation provided by the processor will report all warnings and errors to System.err and does not throw any Exceptions. Applications are strongly encouraged to register and use ErrorListeners that insure proper behavior for warnings and errors.

Resolution of URIs within a transformation

The API provides a way for URIs referenced from within the stylesheet instructions or within the transformation to be resolved by the calling application. This can be done by creating a class that implements the URIResolver interface, with its one method, URIResolver.resolve(java.lang.String, java.lang.String), and use this class to set the URI resolution for the transformation instructions or transformation with TransformerFactory.setURIResolver(javax.xml.transform.URIResolver) or Transformer.setURIResolver(javax.xml.transform.URIResolver). The URIResolver.resolve method takes two String arguments, the URI found in the stylesheet instructions or built as part of the transformation process, and the base URI against which the first argument will be made absolute if the absolute URI is required. The returned Source object must be usable by the transformer, as specified in its implemented features.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.transform Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.transform

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.transform.OutputKeys
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Error
        • javax.xml.transform.TransformerFactoryConfigurationError
      • java.lang.Exception
        • javax.xml.transform.TransformerException
          • javax.xml.transform.TransformerConfigurationException
    • javax.xml.transform.Transformer
    • javax.xml.transform.TransformerFactory

Interface Hierarchy

  • javax.xml.transform.ErrorListener
  • javax.xml.transform.Result
  • javax.xml.transform.Source
  • javax.xml.transform.SourceLocator
  • javax.xml.transform.Templates
  • javax.xml.transform.URIResolver
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.transform

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.transform

Packages that use javax.xml.transform
java.sql | Provides the API for accessing and processing data stored in a data source (usually a relational database) using the JavaTM programming language.
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.annotation | Defines annotations for customizing Java program elements to XML Schema mapping.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.bind.util | Useful client utility classes.
javax.xml.soap | Provides the API for creating and building SOAP messages.
javax.xml.stream |
javax.xml.transform | This package defines the generic APIs for processing transformation instructions, and performing a transformation from source to result.
javax.xml.transform.dom | This package implements DOM-specific transformation APIs.
javax.xml.transform.sax | This package implements SAX2-specific transformation APIs.
javax.xml.transform.stax | Provides for StAX-specific transformation APIs.
javax.xml.transform.stream | This package implements stream- and URI- specific transformation APIs.
javax.xml.validation | This package provides an API for validation of XML documents.
javax.xml.ws | This package contains the core JAX-WS APIs.

Classes in javax.xml.transform used by java.sql
Result
An object that implements this interface contains the information needed to build a transformation result tree.
Source
An object that implements this interface contains the information needed to act as source input (XML source or transformation instructions).

Classes in javax.xml.transform used by javax.xml.bind
Result
An object that implements this interface contains the information needed to build a transformation result tree.
Source
An object that implements this interface contains the information needed to act as source input (XML source or transformation instructions).

Classes in javax.xml.transform used by javax.xml.bind.annotation
Result
An object that implements this interface contains the information needed to build a transformation result tree.
Source
An object that implements this interface contains the information needed to act as source input (XML source or transformation instructions).

Classes in javax.xml.transform used by javax.xml.bind.helpers
Source
An object that implements this interface contains the information needed to act as source input (XML source or transformation instructions).

Classes in javax.xml.transform used by javax.xml.bind.util
Result
An object that implements this interface contains the information needed to build a transformation result tree.
Source
An object that implements this interface contains the information needed to act as source input (XML source or transformation instructions).

Classes in javax.xml.transform used by javax.xml.soap
Result
An object that implements this interface contains the information needed to build a transformation result tree.
Source
An object that implements this interface contains the information needed to act as source input (XML source or transformation instructions).

Classes in javax.xml.transform used by javax.xml.stream
Result
An object that implements this interface contains the information needed to build a transformation result tree.
Source
An object that implements this interface contains the information needed to act as source input (XML source or transformation instructions).

Classes in javax.xml.transform used by javax.xml.transform
ErrorListener
To provide customized error handling, implement this interface and use the setErrorListener method to register an instance of the implmentation with the Transformer.
Result
An object that implements this interface contains the information needed to build a transformation result tree.
Source
An object that implements this interface contains the information needed to act as source input (XML source or transformation instructions).
SourceLocator
This interface is primarily for the purposes of reporting where an error occurred in the XML source or transformation instructions.
Templates
An object that implements this interface is the runtime representation of processed transformation instructions.
Transformer
An instance of this abstract class can transform a source tree into a result tree.
TransformerConfigurationException
Indicates a serious configuration error.
TransformerException
This class specifies an exceptional condition that occured during the transformation process.
TransformerFactory
A TransformerFactory instance can be used to create Transformer and Templates objects.
TransformerFactoryConfigurationError
Thrown when a problem with configuration with the Transformer Factories exists.
URIResolver
An object that implements this interface that can be called by the processor to turn a URI used in document(), xsl:import, or xsl:include into a Source object.

Classes in javax.xml.transform used by javax.xml.transform.dom
Result
An object that implements this interface contains the information needed to build a transformation result tree.
Source
An object that implements this interface contains the information needed to act as source input (XML source or transformation instructions).
SourceLocator
This interface is primarily for the purposes of reporting where an error occurred in the XML source or transformation instructions.

Classes in javax.xml.transform used by javax.xml.transform.sax
Result
An object that implements this interface contains the information needed to build a transformation result tree.
Source
An object that implements this interface contains the information needed to act as source input (XML source or transformation instructions).
Templates
An object that implements this interface is the runtime representation of processed transformation instructions.
Transformer
An instance of this abstract class can transform a source tree into a result tree.
TransformerConfigurationException
Indicates a serious configuration error.
TransformerFactory
A TransformerFactory instance can be used to create Transformer and Templates objects.

Classes in javax.xml.transform used by javax.xml.transform.stax
Result
An object that implements this interface contains the information needed to build a transformation result tree.
Source
An object that implements this interface contains the information needed to act as source input (XML source or transformation instructions).

Classes in javax.xml.transform used by javax.xml.transform.stream
Result
An object that implements this interface contains the information needed to build a transformation result tree.
Source
An object that implements this interface contains the information needed to act as source input (XML source or transformation instructions).

Classes in javax.xml.transform used by javax.xml.validation
Result
An object that implements this interface contains the information needed to build a transformation result tree.
Source
An object that implements this interface contains the information needed to act as source input (XML source or transformation instructions).

Classes in javax.xml.transform used by javax.xml.ws
Source
An object that implements this interface contains the information needed to act as source input (XML source or transformation instructions).

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.transform.OutputKeys

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.transform.OutputKeys

No usage of javax.xml.transform.OutputKeys

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.transform.Transformer

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.transform.Transformer

Packages that use Transformer
javax.xml.transform | This package defines the generic APIs for processing transformation instructions, and performing a transformation from source to result.
javax.xml.transform.sax | This package implements SAX2-specific transformation APIs.

Uses of Transformer in javax.xml.transform

Methods in javax.xml.transform that return Transformer
Transformer | Templates.newTransformer() Create a new transformation context for this Templates object.
abstract Transformer | TransformerFactory.newTransformer() Create a new Transformer that performs a copy of the Source to the Result.
abstract Transformer | TransformerFactory.newTransformer(Source source) Process the Source into a Transformer Object.

Uses of Transformer in javax.xml.transform.sax

Methods in javax.xml.transform.sax that return Transformer
 Transformer TransformerHandler.getTransformer()
Get the Transformer associated with this handler, which is needed in order to set parameters and output properties.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.transform.TransformerConfigurationException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.transform.TransformerConfigurationException

Packages that use TransformerConfigurationException
javax.xml.transform | This package defines the generic APIs for processing transformation instructions, and performing a transformation from source to result.
javax.xml.transform.sax | This package implements SAX2-specific transformation APIs.

Uses of TransformerConfigurationException in javax.xml.transform

Methods in javax.xml.transform that throw TransformerConfigurationException
abstract Source | TransformerFactory.getAssociatedStylesheet(Source source, String media, String title, String charset) Get the stylesheet specification(s) associated with the XML Source document via the xml-stylesheet processing instruction that match the given criteria.
abstract Templates | TransformerFactory.newTemplates(Source source) Process the Source into a Templates object, which is a a compiled representation of the source.
Transformer | Templates.newTransformer() Create a new transformation context for this Templates object.
abstract Transformer | TransformerFactory.newTransformer() Create a new Transformer that performs a copy of the Source to the Result.
abstract Transformer | TransformerFactory.newTransformer(Source source) Process the Source into a Transformer Object.
abstract void | TransformerFactory.setFeature(String name, boolean value) Set a feature for this TransformerFactory and Transformers or Templates created by this factory.

Uses of TransformerConfigurationException in javax.xml.transform.sax

Methods in javax.xml.transform.sax that throw TransformerConfigurationException
abstract TemplatesHandler | SAXTransformerFactory.newTemplatesHandler() Get a TemplatesHandler object that can process SAX ContentHandler events into a Templates object.
abstract TransformerHandler | SAXTransformerFactory.newTransformerHandler() Get a TransformerHandler object that can process SAX ContentHandler events into a Result.
abstract TransformerHandler | SAXTransformerFactory.newTransformerHandler(Source src) Get a TransformerHandler object that can process SAX ContentHandler events into a Result, based on the transformation instructions specified by the argument.
abstract TransformerHandler | SAXTransformerFactory.newTransformerHandler(Templates templates) Get a TransformerHandler object that can process SAX ContentHandler events into a Result, based on the Templates argument.
abstract XMLFilter | SAXTransformerFactory.newXMLFilter(Source src) Create an XMLFilter that uses the given Source as the transformation instructions.
abstract XMLFilter | SAXTransformerFactory.newXMLFilter(Templates templates) Create an XMLFilter, based on the Templates argument..

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.transform.TransformerException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.transform.TransformerException

Packages that use TransformerException
javax.xml.transform This package defines the generic APIs for processing transformation instructions, and performing a transformation from source to result.

Uses of TransformerException in javax.xml.transform

Subclasses of TransformerException in javax.xml.transform
 class TransformerConfigurationException
Indicates a serious configuration error.

Methods in javax.xml.transform with parameters of type TransformerException
void | ErrorListener.error(TransformerException exception) Receive notification of a recoverable error.
void | ErrorListener.fatalError(TransformerException exception) Receive notification of a non-recoverable error.
void | ErrorListener.warning(TransformerException exception) Receive notification of a warning.

Methods in javax.xml.transform that throw TransformerException
 void ErrorListener.error(TransformerException exception)
Receive notification of a recoverable error.
 void ErrorListener.fatalError(TransformerException exception)
Receive notification of a non-recoverable error.
 Source URIResolver.resolve(String href, String base)
Called by the processor when it encounters an xsl:include, xsl:import, or document() function.
abstract  void Transformer.transform(Source xmlSource, Result outputTarget)
Transform the XML Source to a Result.
 void ErrorListener.warning(TransformerException exception)
Receive notification of a warning.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.transform.TransformerFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.transform.TransformerFactory

Packages that use TransformerFactory
javax.xml.transform | This package defines the generic APIs for processing transformation instructions, and performing a transformation from source to result.
javax.xml.transform.sax | This package implements SAX2-specific transformation APIs.

Uses of TransformerFactory in javax.xml.transform

Methods in javax.xml.transform that return TransformerFactory
static TransformerFactory | TransformerFactory.newInstance() Obtain a new instance of a TransformerFactory.
static TransformerFactory | TransformerFactory.newInstance(String factoryClassName, ClassLoader classLoader) Obtain a new instance of a TransformerFactory from factory class name.

Uses of TransformerFactory in javax.xml.transform.sax

Subclasses of TransformerFactory in javax.xml.transform.sax
 class SAXTransformerFactory
This class extends TransformerFactory to provide SAX-specific factory methods.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.transform.TransformerFactoryConfigurationError

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.transform.TransformerFactoryConfigurationError

Packages that use TransformerFactoryConfigurationError
javax.xml.transform This package defines the generic APIs for processing transformation instructions, and performing a transformation from source to result.

Uses of TransformerFactoryConfigurationError in javax.xml.transform

Methods in javax.xml.transform that throw TransformerFactoryConfigurationError
static TransformerFactory | TransformerFactory.newInstance() Obtain a new instance of a TransformerFactory.
static TransformerFactory | TransformerFactory.newInstance(String factoryClassName, ClassLoader classLoader) Obtain a new instance of a TransformerFactory from factory class name.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.transform.ErrorListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.transform.ErrorListener

Packages that use ErrorListener
javax.xml.transform This package defines the generic APIs for processing transformation instructions, and performing a transformation from source to result.

Uses of ErrorListener in javax.xml.transform

Methods in javax.xml.transform that return ErrorListener
abstract ErrorListener | Transformer.getErrorListener() Get the error event handler in effect for the transformation.
abstract ErrorListener | TransformerFactory.getErrorListener() Get the error event handler for the TransformerFactory.

Methods in javax.xml.transform with parameters of type ErrorListener
abstract void | Transformer.setErrorListener(ErrorListener listener) Set the error event listener in effect for the transformation.
abstract void | TransformerFactory.setErrorListener(ErrorListener listener) Set the error event listener for the TransformerFactory, which is used for the processing of transformation instructions, and not for the transformation itself.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.transform.Result

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.transform.Result

Packages that use Result
java.sql | Provides the API for accessing and processing data stored in a data source (usually a relational database) using the JavaTM programming language.
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.annotation | Defines annotations for customizing Java program elements to XML Schema mapping.
javax.xml.bind.util | Useful client utility classes.
javax.xml.soap | Provides the API for creating and building SOAP messages.
javax.xml.stream |
javax.xml.transform | This package defines the generic APIs for processing transformation instructions, and performing a transformation from source to result.
javax.xml.transform.dom | This package implements DOM-specific transformation APIs.
javax.xml.transform.sax | This package implements SAX2-specific transformation APIs.
javax.xml.transform.stax | Provides for StAX-specific transformation APIs.
javax.xml.transform.stream | This package implements stream- and URI- specific transformation APIs.
javax.xml.validation | This package provides an API for validation of XML documents.

Uses of Result in java.sql

Methods in java.sql with type parameters of type Result
<T extends Result>
T
SQLXML.setResult(Class<T> resultClass)
Returns a Result for setting the XML value designated by this SQLXML instance.

Uses of Result in javax.xml.bind

Methods in javax.xml.bind that return Result
abstract  Result SchemaOutputResolver.createOutput(String namespaceUri, String suggestedFileName)
Decides where the schema file (of the given namespace URI) will be written, and return it as a Result object.

Methods in javax.xml.bind with parameters of type Result
 void Marshaller.marshal(Object jaxbElement, Result result)
Marshal the content tree rooted at jaxbElement into the specified javax.xml.transform.Result.

Uses of Result in javax.xml.bind.annotation

Classes in javax.xml.bind.annotation with type parameters of type Result
 interface DomHandler<ElementT,ResultT extends Result>
Converts an element (and its descendants) from/to DOM (or similar) representation.

Uses of Result in javax.xml.bind.util

Classes in javax.xml.bind.util that implement Result
 class JAXBResult
JAXP Result implementation that unmarshals a JAXB object.

Uses of Result in javax.xml.soap

Classes in javax.xml.soap that implement Result
 class SAAJResult
Acts as a holder for the results of a JAXP transformation or a JAXB marshalling, in the form of a SAAJ tree.

Uses of Result in javax.xml.stream

Methods in javax.xml.stream with parameters of type Result
abstract XMLEventWriter | XMLOutputFactory.createXMLEventWriter(Result result) Create a new XMLEventWriter that writes to a JAXP result.
abstract XMLStreamWriter | XMLOutputFactory.createXMLStreamWriter(Result result) Create a new XMLStreamWriter that writes to a JAXP result.

Uses of Result in javax.xml.transform

Methods in javax.xml.transform with parameters of type Result
abstract  void Transformer.transform(Source xmlSource, Result outputTarget)
Transform the XML Source to a Result.

Uses of Result in javax.xml.transform.dom

Classes in javax.xml.transform.dom that implement Result
 class DOMResult
Acts as a holder for a transformation result tree in the form of a Document Object Model (DOM) tree.

Uses of Result in javax.xml.transform.sax

Classes in javax.xml.transform.sax that implement Result
 class SAXResult
Acts as an holder for a transformation Result.

Methods in javax.xml.transform.sax with parameters of type Result
 void TransformerHandler.setResult(Result result)
Set the Result associated with this TransformerHandler to be used for the transformation.

Uses of Result in javax.xml.transform.stax

Classes in javax.xml.transform.stax that implement Result
 class StAXResult
Acts as a holder for an XML Result in the form of a StAX writer,i.e.

Uses of Result in javax.xml.transform.stream

Classes in javax.xml.transform.stream that implement Result
 class StreamResult
Acts as an holder for a transformation result, which may be XML, plain Text, HTML, or some other form of markup.

Uses of Result in javax.xml.validation

Methods in javax.xml.validation with parameters of type Result
abstract  void Validator.validate(Source source, Result result)
Validates the specified input and send the augmented validation result to the specified output.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.transform.Source

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.transform.Source

Packages that use Source
java.sql | Provides the API for accessing and processing data stored in a data source (usually a relational database) using the JavaTM programming language.
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.annotation | Defines annotations for customizing Java program elements to XML Schema mapping.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.bind.util | Useful client utility classes.
javax.xml.soap | Provides the API for creating and building SOAP messages.
javax.xml.stream |
javax.xml.transform | This package defines the generic APIs for processing transformation instructions, and performing a transformation from source to result.
javax.xml.transform.dom | This package implements DOM-specific transformation APIs.
javax.xml.transform.sax | This package implements SAX2-specific transformation APIs.
javax.xml.transform.stax | Provides for StAX-specific transformation APIs.
javax.xml.transform.stream | This package implements stream- and URI- specific transformation APIs.
javax.xml.validation | This package provides an API for validation of XML documents.
javax.xml.ws | This package contains the core JAX-WS APIs.

Uses of Source in java.sql

Methods in java.sql with type parameters of type Source
<T extends Source>
T
SQLXML.getSource(Class<T> sourceClass)
Returns a Source for reading the XML value designated by this SQLXML instance.

Uses of Source in javax.xml.bind

Methods in javax.xml.bind with parameters of type Source
 Object Unmarshaller.unmarshal(Source source)
Unmarshal XML data from the specified XML Source and return the resulting content tree.
<T> JAXBElement<T>
Unmarshaller.unmarshal(Source source, Class<T> declaredType)
Unmarshal XML data from the specified XML Source by declaredType and return the resulting content tree.

Uses of Source in javax.xml.bind.annotation

Methods in javax.xml.bind.annotation that return Source
Source | DomHandler.marshal(ElementT n, ValidationEventHandler errorHandler) This method is called when a JAXB provider needs to marshal an element to XML.
Source | W3CDomHandler.marshal(Element element, ValidationEventHandler errorHandler)

Uses of Source in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers with parameters of type Source
 Object AbstractUnmarshallerImpl.unmarshal(Source source)
<T> JAXBElement<T>
AbstractUnmarshallerImpl.unmarshal(Source source, Class<T> expectedType)

Uses of Source in javax.xml.bind.util

Classes in javax.xml.bind.util that implement Source
 class JAXBSource
JAXP Source implementation that marshals a JAXB-generated object.

Uses of Source in javax.xml.soap

Methods in javax.xml.soap that return Source
abstract  Source SOAPPart.getContent()
Returns the content of the SOAPEnvelope as a JAXP Source object.

Methods in javax.xml.soap with parameters of type Source
abstract  void SOAPPart.setContent(Source source)
Sets the content of the SOAPEnvelope object with the data from the given Source object.

Uses of Source in javax.xml.stream

Methods in javax.xml.stream with parameters of type Source
abstract XMLEventReader | XMLInputFactory.createXMLEventReader(Source source) Create a new XMLEventReader from a JAXP source.
abstract XMLStreamReader | XMLInputFactory.createXMLStreamReader(Source source) Create a new XMLStreamReader from a JAXP source.

Uses of Source in javax.xml.transform

Methods in javax.xml.transform that return Source
abstract  Source TransformerFactory.getAssociatedStylesheet(Source source, String media, String title, String charset)
Get the stylesheet specification(s) associated with the XML Source document via the xml-stylesheet processing instruction that match the given criteria.
 Source URIResolver.resolve(String href, String base)
Called by the processor when it encounters an xsl:include, xsl:import, or document() function.

Methods in javax.xml.transform with parameters of type Source
abstract Source | TransformerFactory.getAssociatedStylesheet(Source source, String media, String title, String charset) Get the stylesheet specification(s) associated with the XML Source document via the xml-stylesheet processing instruction that match the given criteria.
abstract Templates | TransformerFactory.newTemplates(Source source) Process the Source into a Templates object, which is a a compiled representation of the source.
abstract Transformer | TransformerFactory.newTransformer(Source source) Process the Source into a Transformer Object.
abstract void | Transformer.transform(Source xmlSource, Result outputTarget) Transform the XML Source to a Result.

Uses of Source in javax.xml.transform.dom

Classes in javax.xml.transform.dom that implement Source
 class DOMSource
Acts as a holder for a transformation Source tree in the form of a Document Object Model (DOM) tree.

Uses of Source in javax.xml.transform.sax

Classes in javax.xml.transform.sax that implement Source
 class SAXSource
Acts as an holder for SAX-style Source.

Methods in javax.xml.transform.sax with parameters of type Source
abstract TransformerHandler | SAXTransformerFactory.newTransformerHandler(Source src) Get a TransformerHandler object that can process SAX ContentHandler events into a Result, based on the transformation instructions specified by the argument.
abstract XMLFilter | SAXTransformerFactory.newXMLFilter(Source src) Create an XMLFilter that uses the given Source as the transformation instructions.
static InputSource | SAXSource.sourceToInputSource(Source source) Attempt to obtain a SAX InputSource object from a Source object.

Uses of Source in javax.xml.transform.stax

Classes in javax.xml.transform.stax that implement Source
 class StAXSource
Acts as a holder for an XML Source in the form of a StAX reader,i.e.

Uses of Source in javax.xml.transform.stream

Classes in javax.xml.transform.stream that implement Source
 class StreamSource
Acts as an holder for a transformation Source in the form of a stream of XML markup.

Uses of Source in javax.xml.validation

Methods in javax.xml.validation with parameters of type Source
Schema | SchemaFactory.newSchema(Source schema) Parses the specified source as a schema and returns it as a schema.
abstract Schema | SchemaFactory.newSchema(Source[] schemas) Parses the specified source(s) as a schema and returns it as a schema.
void | Validator.validate(Source source) Validates the specified input.
abstract void | Validator.validate(Source source, Result result) Validates the specified input and send the augmented validation result to the specified output.

Uses of Source in javax.xml.ws

Methods in javax.xml.ws that return Source
 Source LogicalMessage.getPayload()
Gets the message payload as an XML source, may be called multiple times on the same LogicalMessage instance, always returns a new Source that may be used to retrieve the entire message payload.

Methods in javax.xml.ws that return types with arguments of type Source
abstract  List<Source> Endpoint.getMetadata()
Returns a list of metadata documents for the service.

Methods in javax.xml.ws with parameters of type Source
 void LogicalMessage.setPayload(Source payload)
Sets the message payload

Method parameters in javax.xml.ws with type arguments of type Source
abstract  void Endpoint.setMetadata(List<Source> metadata)
Sets the metadata for this endpoint.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.transform.SourceLocator

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.transform.SourceLocator

Packages that use SourceLocator
javax.xml.transform | This package defines the generic APIs for processing transformation instructions, and performing a transformation from source to result.
javax.xml.transform.dom | This package implements DOM-specific transformation APIs.

Uses of SourceLocator in javax.xml.transform

Methods in javax.xml.transform that return SourceLocator
 SourceLocator TransformerException.getLocator()
Method getLocator retrieves an instance of a SourceLocator object that specifies where an error occured.

Methods in javax.xml.transform with parameters of type SourceLocator
 void TransformerException.setLocator(SourceLocator location)
Method setLocator sets an instance of a SourceLocator object that specifies where an error occured.

Constructors in javax.xml.transform with parameters of type SourceLocator
TransformerConfigurationException(String message, SourceLocator locator)
Create a new TransformerConfigurationException from a message and a Locator.
TransformerConfigurationException(String message, SourceLocator locator, Throwable e)
Wrap an existing exception in a TransformerConfigurationException.
TransformerException(String message, SourceLocator locator)
Create a new TransformerException from a message and a Locator.
TransformerException(String message, SourceLocator locator, Throwable e)
Wrap an existing exception in a TransformerException.

Uses of SourceLocator in javax.xml.transform.dom

Subinterfaces of SourceLocator in javax.xml.transform.dom
 interface DOMLocator
Indicates the position of a node in a source DOM, intended primarily for error reporting.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.transform.Templates

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.transform.Templates

Packages that use Templates
javax.xml.transform | This package defines the generic APIs for processing transformation instructions, and performing a transformation from source to result.
javax.xml.transform.sax | This package implements SAX2-specific transformation APIs.

Uses of Templates in javax.xml.transform

Methods in javax.xml.transform that return Templates
abstract  Templates TransformerFactory.newTemplates(Source source)
Process the Source into a Templates object, which is a a compiled representation of the source.

Uses of Templates in javax.xml.transform.sax

Methods in javax.xml.transform.sax that return Templates
 Templates TemplatesHandler.getTemplates()
When a TemplatesHandler object is used as a ContentHandler for the parsing of transformation instructions, it creates a Templates object, which the caller can get once the SAX events have been completed.

Methods in javax.xml.transform.sax with parameters of type Templates
abstract TransformerHandler | SAXTransformerFactory.newTransformerHandler(Templates templates) Get a TransformerHandler object that can process SAX ContentHandler events into a Result, based on the Templates argument.
abstract XMLFilter | SAXTransformerFactory.newXMLFilter(Templates templates) Create an XMLFilter, based on the Templates argument..

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.transform.URIResolver

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.transform.URIResolver

Packages that use URIResolver
javax.xml.transform This package defines the generic APIs for processing transformation instructions, and performing a transformation from source to result.

Uses of URIResolver in javax.xml.transform

Methods in javax.xml.transform that return URIResolver
abstract  URIResolver Transformer.getURIResolver()
Get an object that will be used to resolve URIs used in document().
abstract  URIResolver TransformerFactory.getURIResolver()
Get the object that is used by default during the transformation to resolve URIs used in document(), xsl:import, or xsl:include.

Methods in javax.xml.transform with parameters of type URIResolver
abstract  void Transformer.setURIResolver(URIResolver resolver)
Set an object that will be used to resolve URIs used in document().
abstract  void TransformerFactory.setURIResolver(URIResolver resolver)
Set an object that is used by default during the transformation to resolve URIs used in document(), xsl:import, or xsl:include.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


dom

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.transform.dom

This package implements DOM-specific transformation APIs.

See:
Description

Interface Summary
DOMLocator Indicates the position of a node in a source DOM, intended primarily for error reporting.

Class Summary
DOMResult | Acts as a holder for a transformation result tree in the form of a Document Object Model (DOM) tree.
DOMSource | Acts as a holder for a transformation Source tree in the form of a Document Object Model (DOM) tree.

Package javax.xml.transform.dom Description

This package implements DOM-specific transformation APIs.

The DOMSource class allows the client of the implementation of this API to specify a DOM Node as the source of the input tree. The model of how the Transformer deals with the DOM tree in terms of mismatches with the XSLT data model or other data models is beyond the scope of this document. Any of the nodes derived from Node are legal input.

The DOMResult class allows a Node to be specified to which result DOM nodes will be appended. If an output node is not specified, the transformer will use DocumentBuilder.newDocument() to create an output Document node. If a node is specified, it should be one of the following: Document, Element, or DocumentFragment. Specification of any other node type is implementation dependent and undefined by this API. If the result is a Document, the output of the transformation must have a single element root to set as the document element.

The DOMLocator node may be passed to TransformerException objects, and retrieved by trying to cast the result of the TransformerException.getLocator() method. The implementation has no responsibility to use a DOMLocator instead of a SourceLocator (though line numbers and the like do not make much sense for a DOM), so the result of getLocator must always be tested with an instanceof.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.transform.dom Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.transform.dom

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.transform.dom.DOMResult (implements javax.xml.transform.Result)
    • javax.xml.transform.dom.DOMSource (implements javax.xml.transform.Source)

Interface Hierarchy

  • javax.xml.transform.SourceLocator
    • javax.xml.transform.dom.DOMLocator
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.transform.dom

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.transform.dom

Packages that use javax.xml.transform.dom
javax.xml.bind.annotation | Defines annotations for customizing Java program elements to XML Schema mapping.
javax.xml.soap | Provides the API for creating and building SOAP messages.

Classes in javax.xml.transform.dom used by javax.xml.bind.annotation
DOMResult
Acts as a holder for a transformation result tree in the form of a Document Object Model (DOM) tree.

Classes in javax.xml.transform.dom used by javax.xml.soap
DOMResult
Acts as a holder for a transformation result tree in the form of a Document Object Model (DOM) tree.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.transform.dom.DOMResult

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.transform.dom.DOMResult

Packages that use DOMResult
javax.xml.bind.annotation | Defines annotations for customizing Java program elements to XML Schema mapping.
javax.xml.soap | Provides the API for creating and building SOAP messages.

Uses of DOMResult in javax.xml.bind.annotation

Methods in javax.xml.bind.annotation that return DOMResult
 DOMResult W3CDomHandler.createUnmarshaller(ValidationEventHandler errorHandler)

Methods in javax.xml.bind.annotation with parameters of type DOMResult
 Element W3CDomHandler.getElement(DOMResult r)

Uses of DOMResult in javax.xml.soap

Subclasses of DOMResult in javax.xml.soap
 class SAAJResult
Acts as a holder for the results of a JAXP transformation or a JAXB marshalling, in the form of a SAAJ tree.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.transform.dom.DOMSource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.transform.dom.DOMSource

No usage of javax.xml.transform.dom.DOMSource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.transform.dom.DOMLocator

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.transform.dom.DOMLocator

No usage of javax.xml.transform.dom.DOMLocator

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DOMLocator

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform.dom
Interface DOMLocator

All Superinterfaces:
SourceLocator
public interface DOMLocator
extends SourceLocator

Indicates the position of a node in a source DOM, intended primarily for error reporting. To use a DOMLocator, the receiver of an error must downcast the SourceLocator object returned by an exception. A Transformer may use this object for purposes other than error reporting, for instance, to indicate the source node that originated a result node.

Method Summary
 Node getOriginatingNode()
Return the node where the event occurred.
Methods inherited from interface javax.xml.transform.SourceLocator
getColumnNumber, getLineNumber, getPublicId, getSystemId

Method Detail

getOriginatingNode

Node getOriginatingNode()
Return the node where the event occurred.

Returns:
The node that is the location for the event.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


DOMResult

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform.dom
Class DOMResult

java.lang.Object
    extended by  javax.xml.transform.dom.DOMResult
All Implemented Interfaces:
Result
Direct Known Subclasses:
SAAJResult
public class DOMResult
extends Object
implements Result

Acts as a holder for a transformation result tree in the form of a Document Object Model (DOM) tree.

If no output DOM source is set, the transformation will create a Document node as the holder for the result of the transformation, which may be retrieved with getNode().

Field Summary
static String FEATURE
If TransformerFactory.getFeature(java.lang.String) returns true when passed this value as an argument, the Transformer supports Result output of this type.
Fields inherited from interface javax.xml.transform.Result
PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING
Constructor Summary
DOMResult()
Zero-argument default constructor.
DOMResult(Node node)
Use a DOM node to create a new output target.
DOMResult(Node node, Node nextSibling)
Use a DOM node to create a new output target specifying the child node where the result nodes should be inserted before.
DOMResult(Node node, Node nextSibling, String systemId)
Use a DOM node to create a new output target specifying the child node where the result nodes should be inserted before and the specified System ID.
DOMResult(Node node, String systemId)
Use a DOM node to create a new output target with the specified System ID.
Method Summary
Node | getNextSibling() Get the child node before which the result nodes will be inserted.
Node | getNode() Get the node that will contain the result DOM tree.
String | getSystemId() Get the System Identifier.
void | setNextSibling(Node nextSibling) Set the child node before which the result nodes will be inserted.
void | setNode(Node node) Set the node that will contain the result DOM tree.
void | setSystemId(String systemId) Set the systemId that may be used in association with the node.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FEATURE

public static final String FEATURE

If TransformerFactory.getFeature(java.lang.String) returns true when passed this value as an argument, the Transformer supports Result output of this type.

See Also:
Constant Field Values
Constructor Detail

DOMResult

public DOMResult()

Zero-argument default constructor.

node, siblingNode and systemId will be set to null.

DOMResult

public DOMResult(Node node)

Use a DOM node to create a new output target.

In practice, the node should be a Document node, a DocumentFragment node, or a Element node. In other words, a node that accepts children.

siblingNode and systemId will be set to null.

Parameters:
node - The DOM node that will contain the result tree.

DOMResult

public DOMResult(Node node,
                 String systemId)

Use a DOM node to create a new output target with the specified System ID.

In practice, the node should be a Document node, a DocumentFragment node, or a Element node. In other words, a node that accepts children.

siblingNode will be set to null.

Parameters:
node - The DOM node that will contain the result tree.
systemId - The system identifier which may be used in association with this node.

DOMResult

public DOMResult(Node node,
                 Node nextSibling)

Use a DOM node to create a new output target specifying the child node where the result nodes should be inserted before.

In practice, node and nextSibling should be a Document node, a DocumentFragment node, or a Element node. In other words, a node that accepts children.

Use nextSibling to specify the child node where the result nodes should be inserted before. If nextSibling is not a sibling of node, then an IllegalArgumentException is thrown. If node is null and nextSibling is not null, then an IllegalArgumentException is thrown. If nextSibling is null, then the behavior is the same as calling DOMResult(Node node), i.e. append the result nodes as the last child of the specified node.

systemId will be set to null.

Parameters:
node - The DOM node that will contain the result tree.
nextSibling - The child node where the result nodes should be inserted before.
Throws:
IllegalArgumentException - If nextSibling is not a sibling of node or node is null and nextSibling is not null.
Since:
1.5

DOMResult

public DOMResult(Node node,
                 Node nextSibling,
                 String systemId)

Use a DOM node to create a new output target specifying the child node where the result nodes should be inserted before and the specified System ID.

In practice, node and nextSibling should be a Document node, a DocumentFragment node, or a Element node. In other words, a node that accepts children.

Use nextSibling to specify the child node where the result nodes should be inserted before. If nextSibling is not a sibling of node, then an IllegalArgumentException is thrown. If node is null and nextSibling is not null, then an IllegalArgumentException is thrown. If nextSibling is null, then the behavior is the same as calling DOMResult(Node node, String systemId), i.e. append the result nodes as the last child of the specified node and use the specified System ID.

Parameters:
node - The DOM node that will contain the result tree.
nextSibling - The child node where the result nodes should be inserted before.
systemId - The system identifier which may be used in association with this node.
Throws:
IllegalArgumentException - If nextSibling is not a sibling of node or node is null and nextSibling is not null.
Since:
1.5
Method Detail

setNode

public void setNode(Node node)

Set the node that will contain the result DOM tree.

In practice, the node should be a Document node, a DocumentFragment node, or a Element node. In other words, a node that accepts children.

An IllegalStateException is thrown if nextSibling is not null and node is not a parent of nextSibling. An IllegalStateException is thrown if node is null and nextSibling is not null.

Parameters:
node - The node to which the transformation will be appended.
Throws:
IllegalStateException - If nextSibling is not null and nextSibling is not a child of node or node is null and nextSibling is not null.

getNode

public Node getNode()

Get the node that will contain the result DOM tree.

If no node was set via DOMResult(Node node), DOMResult(Node node, String systeId), DOMResult(Node node, Node nextSibling), DOMResult(Node node, Node nextSibling, String systemId) or setNode(Node node), then the node will be set by the transformation, and may be obtained from this method once the transformation is complete. Calling this method before the transformation will return null.

Returns:
The node to which the transformation will be appended.

setNextSibling

public void setNextSibling(Node nextSibling)

Set the child node before which the result nodes will be inserted.

Use nextSibling to specify the child node before which the result nodes should be inserted. If nextSibling is not a descendant of node, then an IllegalArgumentException is thrown. If node is null and nextSibling is not null, then an IllegalStateException is thrown. If nextSibling is null, then the behavior is the same as calling DOMResult(Node node), i.e. append the result nodes as the last child of the specified node.

Parameters:
nextSibling - The child node before which the result nodes will be inserted.
Throws:
IllegalArgumentException - If nextSibling is not a descendant of node.
IllegalStateException - If node is null and nextSibling is not null.
Since:
1.5

getNextSibling

public Node getNextSibling()

Get the child node before which the result nodes will be inserted.

If no node was set via DOMResult(Node node, Node nextSibling), DOMResult(Node node, Node nextSibling, String systemId) or setNextSibling(Node nextSibling), then null will be returned.

Returns:
The child node before which the result nodes will be inserted.
Since:
1.5

setSystemId

public void setSystemId(String systemId)

Set the systemId that may be used in association with the node.

Specified by:
setSystemId in interface Result
Parameters:
systemId - The system identifier as a URI string.

getSystemId

public String getSystemId()

Get the System Identifier.

If no System ID was set via DOMResult(Node node, String systemId), DOMResult(Node node, Node nextSibling, String systemId) or setSystemId(String systemId), then null will be returned.

Specified by:
getSystemId in interface Result
Returns:
The system identifier.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DOMSource

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform.dom
Class DOMSource

java.lang.Object
    extended by  javax.xml.transform.dom.DOMSource
All Implemented Interfaces:
Source
public class DOMSource
extends Object
implements Source

Acts as a holder for a transformation Source tree in the form of a Document Object Model (DOM) tree.

Note that XSLT requires namespace support. Attempting to transform a DOM that was not contructed with a namespace-aware parser may result in errors. Parsers can be made namespace aware by calling DocumentBuilderFactory.setNamespaceAware(boolean awareness).

See Also:
Document Object Model (DOM) Level 2 Specification

Field Summary
static String FEATURE
If TransformerFactory.getFeature(java.lang.String) returns true when passed this value as an argument, the Transformer supports Source input of this type.
Constructor Summary
DOMSource()
Zero-argument default constructor.
DOMSource(Node n)
Create a new input source with a DOM node.
DOMSource(Node node, String systemID)
Create a new input source with a DOM node, and with the system ID also passed in as the base URI.
Method Summary
Node | getNode() Get the node that represents a Source DOM tree.
String | getSystemId() Get the base ID (URL or system ID) from where URLs will be resolved.
void | setNode(Node node) Set the node that will represents a Source DOM tree.
void | setSystemId(String systemID) Set the base ID (URL or system ID) from where URLs will be resolved.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FEATURE

public static final String FEATURE
If TransformerFactory.getFeature(java.lang.String) returns true when passed this value as an argument, the Transformer supports Source input of this type.

See Also:
Constant Field Values
Constructor Detail

DOMSource

public DOMSource()

Zero-argument default constructor. If this constructor is used, and no DOM source is set using setNode(Node node) , then the Transformer will create an empty source Document using DocumentBuilder.newDocument().

See Also:
Transformer.transform(Source xmlSource, Result outputTarget)

DOMSource

public DOMSource(Node n)
Create a new input source with a DOM node. The operation will be applied to the subtree rooted at this node. In XSLT, a "/" pattern still means the root of the tree (not the subtree), and the evaluation of global variables and parameters is done from the root node also.

Parameters:
n - The DOM node that will contain the Source tree.

DOMSource

public DOMSource(Node node,
                 String systemID)
Create a new input source with a DOM node, and with the system ID also passed in as the base URI.

Parameters:
node - The DOM node that will contain the Source tree.
systemID - Specifies the base URI associated with node.
Method Detail

setNode

public void setNode(Node node)
Set the node that will represents a Source DOM tree.

Parameters:
node - The node that is to be transformed.

getNode

public Node getNode()
Get the node that represents a Source DOM tree.

Returns:
The node that is to be transformed.

setSystemId

public void setSystemId(String systemID)
Set the base ID (URL or system ID) from where URLs will be resolved.

Specified by:
setSystemId in interface Source
Parameters:
systemID - Base URL for this DOM tree.

getSystemId

public String getSystemId()
Get the base ID (URL or system ID) from where URLs will be resolved.

Specified by:
getSystemId in interface Source
Returns:
Base URL for this DOM tree.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


ErrorListener

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform
Interface ErrorListener

public interface ErrorListener

To provide customized error handling, implement this interface and use the setErrorListener method to register an instance of the implmentation with the Transformer. The Transformer then reports all errors and warnings through this interface.

If an application does not register its own custom ErrorListener, the default ErrorListener is used which reports all warnings and errors to System.err and does not throw any Exceptions. Applications are strongly encouraged to register and use ErrorListeners that insure proper behavior for warnings and errors.

For transformation errors, a Transformer must use this interface instead of throwing an Exception: it is up to the application to decide whether to throw an Exception for different types of errors and warnings. Note however that the Transformer is not required to continue with the transformation after a call to fatalError(TransformerException exception).

Transformers may use this mechanism to report XML parsing errors as well as transformation errors.

Method Summary
void | error(TransformerException exception) Receive notification of a recoverable error.
void | fatalError(TransformerException exception) Receive notification of a non-recoverable error.
void | warning(TransformerException exception) Receive notification of a warning.

Method Detail

warning

void warning(TransformerException exception)
             throws TransformerException
Receive notification of a warning.

Transformer can use this method to report conditions that are not errors or fatal errors. The default behaviour is to take no action.

After invoking this method, the Transformer must continue with the transformation. It should still be possible for the application to process the document through to the end.

Parameters:
exception - The warning information encapsulated in a transformer exception.
Throws:
TransformerException - if the application chooses to discontinue the transformation.
See Also:
TransformerException

error

void error(TransformerException exception)
           throws TransformerException
Receive notification of a recoverable error.

The transformer must continue to try and provide normal transformation after invoking this method. It should still be possible for the application to process the document through to the end if no other errors are encountered.

Parameters:
exception - The error information encapsulated in a transformer exception.
Throws:
TransformerException - if the application chooses to discontinue the transformation.
See Also:
TransformerException

fatalError

void fatalError(TransformerException exception)
                throws TransformerException

Receive notification of a non-recoverable error.

The processor may choose to continue, but will not normally proceed to a successful completion.

The method should throw an exception if it is unable to process the error, or if it wishes execution to terminate immediately. The processor will not necessarily honor this request.

Parameters:
exception - The error information encapsulated in a TransformerException.
Throws:
TransformerException - if the application chooses to discontinue the transformation.
See Also:
TransformerException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


OutputKeys

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform
Class OutputKeys

java.lang.Object
    extended by  javax.xml.transform.OutputKeys

public class OutputKeys
extends Object

Provides string constants that can be used to set output properties for a Transformer, or to retrieve output properties from a Transformer or Templates object.

All the fields in this class are read-only.

See Also:
section 16 of the XSL Transformations (XSLT) W3C Recommendation

Field Summary
static String | CDATA_SECTION_ELEMENTS cdata-section-elements = expanded names.
static String | DOCTYPE_PUBLIC doctype-public = string.
static String | DOCTYPE_SYSTEM doctype-system = string.
static String | ENCODING encoding = string.
static String | INDENT indent = "yes" | "no".
static String | MEDIA_TYPE media-type = string.
static String | METHOD method = "xml" | "html" | "text" | expanded name.
static String | OMIT_XML_DECLARATION omit-xml-declaration = "yes" | "no".
static String | STANDALONE standalone = "yes" | "no".
static String | VERSION version = nmtoken.
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

METHOD

public static final String METHOD
method = "xml" | "html" | "text" | expanded name.

The value of the method property identifies the overall method that should be used for outputting the result tree. Other non-namespaced values may be used, such as "xhtml", but, if accepted, the handling of such values is implementation defined. If any of the method values are not accepted and are not namespace qualified, then Transformer.setOutputProperty(java.lang.String, java.lang.String) or Transformer.setOutputProperties(java.util.Properties) will throw a IllegalArgumentException.

See Also:
section 16 of the XSL Transformations (XSLT) W3C Recommendation, Constant Field Values

VERSION

public static final String VERSION
version = nmtoken.

version specifies the version of the output method.

When the output method is "xml", the version value specifies the version of XML to be used for outputting the result tree. The default value for the xml output method is 1.0. When the output method is "html", the version value indicates the version of the HTML. The default value for the xml output method is 4.0, which specifies that the result should be output as HTML conforming to the HTML 4.0 Recommendation [HTML]. If the output method is "text", the version property is ignored.

See Also:
section 16 of the XSL Transformations (XSLT) W3C Recommendation, Constant Field Values

ENCODING

public static final String ENCODING
encoding = string.

encoding specifies the preferred character encoding that the Transformer should use to encode sequences of characters as sequences of bytes. The value of the encoding property should be treated case-insensitively. The value must only contain characters in the range #x21 to #x7E (i.e., printable ASCII characters). The value should either be a charset registered with the Internet Assigned Numbers Authority [IANA], [RFC2278] or start with X-.

See Also:
section 16 of the XSL Transformations (XSLT) W3C Recommendation, Constant Field Values

OMIT_XML_DECLARATION

public static final String OMIT_XML_DECLARATION
omit-xml-declaration = "yes" | "no".

omit-xml-declaration specifies whether the XSLT processor should output an XML declaration; the value must be yes or no.

See Also:
section 16 of the XSL Transformations (XSLT) W3C Recommendation, Constant Field Values

STANDALONE

public static final String STANDALONE
standalone = "yes" | "no".

standalone specifies whether the Transformer should output a standalone document declaration; the value must be yes or no.

See Also:
section 16 of the XSL Transformations (XSLT) W3C Recommendation, Constant Field Values

DOCTYPE_PUBLIC

public static final String DOCTYPE_PUBLIC
doctype-public = string.

See the documentation for the DOCTYPE_SYSTEM property for a description of what the value of the key should be.

See Also:
section 16 of the XSL Transformations (XSLT) W3C Recommendation, Constant Field Values

DOCTYPE_SYSTEM

public static final String DOCTYPE_SYSTEM
doctype-system = string.

doctype-system specifies the system identifier to be used in the document type declaration.

If the doctype-system property is specified, the xml output method should output a document type declaration immediately before the first element. The name following <!DOCTYPE should be the name of the first element. If doctype-public property is also specified, then the xml output method should output PUBLIC followed by the public identifier and then the system identifier; otherwise, it should output SYSTEM followed by the system identifier. The internal subset should be empty. The value of the doctype-public property should be ignored unless the doctype-system property is specified.

If the doctype-public or doctype-system properties are specified, then the html output method should output a document type declaration immediately before the first element. The name following <!DOCTYPE should be HTML or html. If the doctype-public property is specified, then the output method should output PUBLIC followed by the specified public identifier; if the doctype-system property is also specified, it should also output the specified system identifier following the public identifier. If the doctype-system property is specified but the doctype-public property is not specified, then the output method should output SYSTEM followed by the specified system identifier.

doctype-system specifies the system identifier to be used in the document type declaration.

See Also:
section 16 of the XSL Transformations (XSLT) W3C Recommendation, Constant Field Values

CDATA_SECTION_ELEMENTS

public static final String CDATA_SECTION_ELEMENTS
cdata-section-elements = expanded names.

cdata-section-elements specifies a whitespace delimited list of the names of elements whose text node children should be output using CDATA sections. Note that these names must use the format described in the section Qualfied Name Representation in javax.xml.transform.

See Also:
section 16 of the XSL Transformations (XSLT) W3C Recommendation., Constant Field Values

INDENT

public static final String INDENT
indent = "yes" | "no".

indent specifies whether the Transformer may add additional whitespace when outputting the result tree; the value must be yes or no.

See Also:
section 16 of the XSL Transformations (XSLT) W3C Recommendation, Constant Field Values

MEDIA_TYPE

public static final String MEDIA_TYPE
media-type = string.

media-type specifies the media type (MIME content type) of the data that results from outputting the result tree. The charset parameter should not be specified explicitly; instead, when the top-level media type is text, a charset parameter should be added according to the character encoding actually used by the output method.

See Also:
s ection 16 of the XSL Transformations (XSLT) W3C Recommendation, Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Result

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform
Interface Result

All Known Implementing Classes:
DOMResult, JAXBResult, SAAJResult, SAXResult, StAXResult, StreamResult
public interface Result

An object that implements this interface contains the information needed to build a transformation result tree.

Field Summary
static String | PI_DISABLE_OUTPUT_ESCAPING The name of the processing instruction that is sent if the result tree disables output escaping.
static String | PI_ENABLE_OUTPUT_ESCAPING The name of the processing instruction that is sent if the result tree enables output escaping at some point after having received a PI_DISABLE_OUTPUT_ESCAPING processing instruction.
Method Summary
String | getSystemId() Get the system identifier that was set with setSystemId.
void | setSystemId(String systemId) Set the system identifier for this Result.

Field Detail

PI_DISABLE_OUTPUT_ESCAPING

static final String PI_DISABLE_OUTPUT_ESCAPING
The name of the processing instruction that is sent if the result tree disables output escaping.

Normally, result tree serialization escapes & and < (and possibly other characters) when outputting text nodes. This ensures that the output is well-formed XML. However, it is sometimes convenient to be able to produce output that is almost, but not quite well-formed XML; for example, the output may include ill-formed sections that will be transformed into well-formed XML by a subsequent non-XML aware process. If a processing instruction is sent with this name, serialization should be output without any escaping.

Result DOM trees may also have PI_DISABLE_OUTPUT_ESCAPING and PI_ENABLE_OUTPUT_ESCAPING inserted into the tree.

See Also:
disable-output-escaping in XSLT Specification, Constant Field Values

PI_ENABLE_OUTPUT_ESCAPING

static final String PI_ENABLE_OUTPUT_ESCAPING
The name of the processing instruction that is sent if the result tree enables output escaping at some point after having received a PI_DISABLE_OUTPUT_ESCAPING processing instruction.

See Also:
disable-output-escaping in XSLT Specification, Constant Field Values
Method Detail

setSystemId

void setSystemId(String systemId)
Set the system identifier for this Result.

If the Result is not to be written to a file, the system identifier is optional. The application may still want to provide one, however, for use in error messages and warnings, or to resolve relative output identifiers.

Parameters:
systemId - The system identifier as a URI string.

getSystemId

String getSystemId()
Get the system identifier that was set with setSystemId.

Returns:
The system identifier that was set with setSystemId, or null if setSystemId was not called.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


sax

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.transform.sax

This package implements SAX2-specific transformation APIs.

See:
Description

Interface Summary
TemplatesHandler | A SAX ContentHandler that may be used to process SAX parse events (parsing transformation instructions) into a Templates object.
TransformerHandler | A TransformerHandler listens for SAX ContentHandler parse events and transforms them to a Result.

Class Summary
SAXResult | Acts as an holder for a transformation Result.
SAXSource | Acts as an holder for SAX-style Source.
SAXTransformerFactory | This class extends TransformerFactory to provide SAX-specific factory methods.

Package javax.xml.transform.sax Description

This package implements SAX2-specific transformation APIs. It provides classes which allow input from ContentHandler events, and also classes that produce org.xml.sax.ContentHandler events. It also provides methods to set the input source as an XMLReader, or to use a InputSource as the source. It also allows the creation of a XMLFilter, which enables transformations to "pull" from other transformations, and lets the transformer to be used polymorphically as an XMLReader.

The SAXSource class allows the setting of an XMLReader to be used for "pulling" parse events, and an InputSource that may be used to specify the SAX source.

The SAXResult class allows the setting of a ContentHandler to be the receiver of SAX2 events from the transformation.

The SAXTransformerFactory extends TransformerFactory to provide factory methods for creating TemplatesHandler, TransformerHandler, and XMLReader instances.

To obtain a SAXTransformerFactory, the caller must cast the TransformerFactory instance returned from TransformerFactory.newInstance().

The TransformerHandler interface allows a transformation to be created from SAX2 parse events, which is a "push" model rather than the "pull" model that normally occurs for a transformation. Normal parse events are received through the ContentHandler interface, lexical events such as startCDATA and endCDATA are received through the LexicalHandler interface, and events that signal the start or end of disabling output escaping are received via ContentHandler.processingInstruction(java.lang.String, java.lang.String), with the target parameter being Result.PI_DISABLE_OUTPUT_ESCAPING and Result.PI_ENABLE_OUTPUT_ESCAPING. If parameters, output properties, or other features need to be set on the Transformer handler, a Transformer reference will need to be obtained from TransformerHandler.getTransformer(), and the methods invoked from that reference.

The TemplatesHandler interface allows the creation of Templates objects from SAX2 parse events. Once the ContentHandler events are complete, the Templates object may be obtained from TemplatesHandler.getTemplates(). Note that TemplatesHandler.setSystemId(java.lang.String) should normally be called in order to establish a base system ID from which relative URLs may be resolved.

The SAXTransformerFactory.newXMLFilter(javax.xml.transform.Source) method allows the creation of a XMLFilter, which encapsulates the SAX2 notion of a "pull" transformation. The following illustrates several transformations chained together. Each filter points to a parent XMLReader, and the final transformation is caused by invoking XMLReader.parse(org.xml.sax.InputSource) on the final reader in the chain.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.transform.sax Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.transform.sax

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.transform.sax.SAXResult (implements javax.xml.transform.Result)
    • javax.xml.transform.sax.SAXSource (implements javax.xml.transform.Source)
    • javax.xml.transform.TransformerFactory
      • javax.xml.transform.sax.SAXTransformerFactory

Interface Hierarchy

  • org.xml.sax.ContentHandler
    • javax.xml.transform.sax.TemplatesHandler
    • javax.xml.transform.sax.TransformerHandler (also extends org.xml.sax.DTDHandler, org.xml.sax.ext.LexicalHandler)
  • org.xml.sax.DTDHandler
    • javax.xml.transform.sax.TransformerHandler (also extends org.xml.sax.ContentHandler, org.xml.sax.ext.LexicalHandler)
  • org.xml.sax.ext.LexicalHandler
    • javax.xml.transform.sax.TransformerHandler (also extends org.xml.sax.ContentHandler, org.xml.sax.DTDHandler)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.transform.sax

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.transform.sax

Packages that use javax.xml.transform.sax
javax.xml.bind.util | Useful client utility classes.
javax.xml.transform.sax | This package implements SAX2-specific transformation APIs.

Classes in javax.xml.transform.sax used by javax.xml.bind.util
SAXResult
Acts as an holder for a transformation Result.
SAXSource
Acts as an holder for SAX-style Source.

Classes in javax.xml.transform.sax used by javax.xml.transform.sax
TemplatesHandler
A SAX ContentHandler that may be used to process SAX parse events (parsing transformation instructions) into a Templates object.
TransformerHandler
A TransformerHandler listens for SAX ContentHandler parse events and transforms them to a Result.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.transform.sax.SAXResult

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.transform.sax.SAXResult

Packages that use SAXResult
javax.xml.bind.util Useful client utility classes.

Uses of SAXResult in javax.xml.bind.util

Subclasses of SAXResult in javax.xml.bind.util
 class JAXBResult
JAXP Result implementation that unmarshals a JAXB object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.transform.sax.SAXSource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.transform.sax.SAXSource

Packages that use SAXSource
javax.xml.bind.util Useful client utility classes.

Uses of SAXSource in javax.xml.bind.util

Subclasses of SAXSource in javax.xml.bind.util
 class JAXBSource
JAXP Source implementation that marshals a JAXB-generated object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.transform.sax.SAXTransformerFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.transform.sax.SAXTransformerFactory

No usage of javax.xml.transform.sax.SAXTransformerFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.transform.sax.TemplatesHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.transform.sax.TemplatesHandler

Packages that use TemplatesHandler
javax.xml.transform.sax This package implements SAX2-specific transformation APIs.

Uses of TemplatesHandler in javax.xml.transform.sax

Methods in javax.xml.transform.sax that return TemplatesHandler
abstract  TemplatesHandler SAXTransformerFactory.newTemplatesHandler()
Get a TemplatesHandler object that can process SAX ContentHandler events into a Templates object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.transform.sax.TransformerHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.transform.sax.TransformerHandler

Packages that use TransformerHandler
javax.xml.transform.sax This package implements SAX2-specific transformation APIs.

Uses of TransformerHandler in javax.xml.transform.sax

Methods in javax.xml.transform.sax that return TransformerHandler
abstract TransformerHandler | SAXTransformerFactory.newTransformerHandler() Get a TransformerHandler object that can process SAX ContentHandler events into a Result.
abstract TransformerHandler | SAXTransformerFactory.newTransformerHandler(Source src) Get a TransformerHandler object that can process SAX ContentHandler events into a Result, based on the transformation instructions specified by the argument.
abstract TransformerHandler | SAXTransformerFactory.newTransformerHandler(Templates templates) Get a TransformerHandler object that can process SAX ContentHandler events into a Result, based on the Templates argument.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


SAXResult

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform.sax
Class SAXResult

java.lang.Object
    extended by  javax.xml.transform.sax.SAXResult
All Implemented Interfaces:
Result
Direct Known Subclasses:
JAXBResult
public class SAXResult
extends Object
implements Result

Acts as an holder for a transformation Result.

Field Summary
static String FEATURE
If TransformerFactory.getFeature(java.lang.String) returns true when passed this value as an argument, the Transformer supports Result output of this type.
Fields inherited from interface javax.xml.transform.Result
PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING
Constructor Summary
SAXResult()
Zero-argument default constructor.
SAXResult(ContentHandler handler)
Create a SAXResult that targets a SAX2 ContentHandler.
Method Summary
ContentHandler | getHandler() Get the ContentHandler that is the Result.
LexicalHandler | getLexicalHandler() Get a SAX2 LexicalHandler for the output.
String | getSystemId() Get the system identifier that was set with setSystemId.
void | setHandler(ContentHandler handler) Set the target to be a SAX2 ContentHandler.
void | setLexicalHandler(LexicalHandler handler) Set the SAX2 LexicalHandler for the output.
void | setSystemId(String systemId) Method setSystemId Set the systemID that may be used in association with the ContentHandler.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FEATURE

public static final String FEATURE
If TransformerFactory.getFeature(java.lang.String) returns true when passed this value as an argument, the Transformer supports Result output of this type.

See Also:
Constant Field Values
Constructor Detail

SAXResult

public SAXResult()
Zero-argument default constructor.

SAXResult

public SAXResult(ContentHandler handler)
Create a SAXResult that targets a SAX2 ContentHandler.

Parameters:
handler - Must be a non-null ContentHandler reference.
Method Detail

setHandler

public void setHandler(ContentHandler handler)
Set the target to be a SAX2 ContentHandler.

Parameters:
handler - Must be a non-null ContentHandler reference.

getHandler

public ContentHandler getHandler()
Get the ContentHandler that is the Result.

Returns:
The ContentHandler that is to be transformation output.

setLexicalHandler

public void setLexicalHandler(LexicalHandler handler)
Set the SAX2 LexicalHandler for the output.

This is needed to handle XML comments and the like. If the lexical handler is not set, an attempt should be made by the transformer to cast the ContentHandler to a LexicalHandler.

Parameters:
handler - A non-null LexicalHandler for handling lexical parse events.

getLexicalHandler

public LexicalHandler getLexicalHandler()
Get a SAX2 LexicalHandler for the output.

Returns:
A LexicalHandler, or null.

setSystemId

public void setSystemId(String systemId)
Method setSystemId Set the systemID that may be used in association with the ContentHandler.

Specified by:
setSystemId in interface Result
Parameters:
systemId - The system identifier as a URI string.

getSystemId

public String getSystemId()
Get the system identifier that was set with setSystemId.

Specified by:
getSystemId in interface Result
Returns:
The system identifier that was set with setSystemId, or null if setSystemId was not called.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


SAXSource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform.sax
Class SAXSource

java.lang.Object
    extended by  javax.xml.transform.sax.SAXSource
All Implemented Interfaces:
Source
Direct Known Subclasses:
JAXBSource
public class SAXSource
extends Object
implements Source

Acts as an holder for SAX-style Source.

Note that XSLT requires namespace support. Attempting to transform an input source that is not generated with a namespace-aware parser may result in errors. Parsers can be made namespace aware by calling the SAXParserFactory.setNamespaceAware(boolean awareness) method.

Field Summary
static String FEATURE
If TransformerFactory.getFeature(java.lang.String) returns true when passed this value as an argument, the Transformer supports Source input of this type.
Constructor Summary
SAXSource()
Zero-argument default constructor.
SAXSource(InputSource inputSource)
Create a SAXSource, using a SAX InputSource.
SAXSource(XMLReader reader, InputSource inputSource)
Create a SAXSource, using an XMLReader and a SAX InputSource.
Method Summary
InputSource | getInputSource() Get the SAX InputSource to be used for the Source.
String | getSystemId() Get the base ID (URI or system ID) from where URIs will be resolved.
XMLReader | getXMLReader() Get the XMLReader to be used for the Source.
void | setInputSource(InputSource inputSource) Set the SAX InputSource to be used for the Source.
void | setSystemId(String systemId) Set the system identifier for this Source.
void | setXMLReader(XMLReader reader) Set the XMLReader to be used for the Source.
static InputSource | sourceToInputSource(Source source) Attempt to obtain a SAX InputSource object from a Source object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FEATURE

public static final String FEATURE
If TransformerFactory.getFeature(java.lang.String) returns true when passed this value as an argument, the Transformer supports Source input of this type.

See Also:
Constant Field Values
Constructor Detail

SAXSource

public SAXSource()

Zero-argument default constructor. If this constructor is used, and no SAX source is set using setInputSource(InputSource inputSource) , then the Transformer will create an empty source InputSource using new InputSource().

See Also:
Transformer.transform(Source xmlSource, Result outputTarget)

SAXSource

public SAXSource(XMLReader reader,
                 InputSource inputSource)
Create a SAXSource, using an XMLReader and a SAX InputSource. The Transformer or SAXTransformerFactory will set itself to be the reader's ContentHandler, and then will call reader.parse(inputSource).

Parameters:
reader - An XMLReader to be used for the parse.
inputSource - A SAX input source reference that must be non-null and that will be passed to the reader parse method.

SAXSource

public SAXSource(InputSource inputSource)
Create a SAXSource, using a SAX InputSource. The Transformer or SAXTransformerFactory creates a reader via XMLReaderFactory (if setXMLReader is not used), sets itself as the reader's ContentHandler, and calls reader.parse(inputSource).

Parameters:
inputSource - An input source reference that must be non-null and that will be passed to the parse method of the reader.
Method Detail

setXMLReader

public void setXMLReader(XMLReader reader)
Set the XMLReader to be used for the Source.

Parameters:
reader - A valid XMLReader or XMLFilter reference.

getXMLReader

public XMLReader getXMLReader()
Get the XMLReader to be used for the Source.

Returns:
A valid XMLReader or XMLFilter reference, or null.

setInputSource

public void setInputSource(InputSource inputSource)
Set the SAX InputSource to be used for the Source.

Parameters:
inputSource - A valid InputSource reference.

getInputSource

public InputSource getInputSource()
Get the SAX InputSource to be used for the Source.

Returns:
A valid InputSource reference, or null.

setSystemId

public void setSystemId(String systemId)
Set the system identifier for this Source. If an input source has already been set, it will set the system ID or that input source, otherwise it will create a new input source.

The system identifier is optional if there is a byte stream or a character stream, but it is still useful to provide one, since the application can use it to resolve relative URIs and can include it in error messages and warnings (the parser will attempt to open a connection to the URI only if no byte stream or character stream is specified).

Specified by:
setSystemId in interface Source
Parameters:
systemId - The system identifier as a URI string.

getSystemId

public String getSystemId()

Get the base ID (URI or system ID) from where URIs will be resolved.

Specified by:
getSystemId in interface Source
Returns:
Base URL for the Source, or null.

sourceToInputSource

public static InputSource sourceToInputSource(Source source)
Attempt to obtain a SAX InputSource object from a Source object.

Parameters:
source - Must be a non-null Source reference.
Returns:
An InputSource, or null if Source can not be converted.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SAXTransformerFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform.sax
Class SAXTransformerFactory

java.lang.Object
    extended by  javax.xml.transform.TransformerFactory
        extended by  javax.xml.transform.sax.SAXTransformerFactory

public abstract class SAXTransformerFactory
extends TransformerFactory

This class extends TransformerFactory to provide SAX-specific factory methods. It provides two types of ContentHandlers, one for creating Transformers, the other for creating Templates objects.

If an application wants to set the ErrorHandler or EntityResolver for an XMLReader used during a transformation, it should use a URIResolver to return the SAXSource which provides (with getXMLReader) a reference to the XMLReader.

Field Summary
static String | FEATURE If TransformerFactory.getFeature(java.lang.String) returns true when passed this value as an argument, the TransformerFactory returned from TransformerFactory.newInstance() may be safely cast to a SAXTransformerFactory.
static String | FEATURE_XMLFILTER If TransformerFactory.getFeature(java.lang.String) returns true when passed this value as an argument, the newXMLFilter(Source src) and newXMLFilter(Templates templates) methods are supported.
Constructor Summary
protected SAXTransformerFactory()
The default constructor is protected on purpose.
Method Summary
abstract TemplatesHandler | newTemplatesHandler() Get a TemplatesHandler object that can process SAX ContentHandler events into a Templates object.
abstract TransformerHandler | newTransformerHandler() Get a TransformerHandler object that can process SAX ContentHandler events into a Result.
abstract TransformerHandler | newTransformerHandler(Source src) Get a TransformerHandler object that can process SAX ContentHandler events into a Result, based on the transformation instructions specified by the argument.
abstract TransformerHandler | newTransformerHandler(Templates templates) Get a TransformerHandler object that can process SAX ContentHandler events into a Result, based on the Templates argument.
abstract XMLFilter | newXMLFilter(Source src) Create an XMLFilter that uses the given Source as the transformation instructions.
abstract XMLFilter | newXMLFilter(Templates templates) Create an XMLFilter, based on the Templates argument..
Methods inherited from class javax.xml.transform.TransformerFactory
getAssociatedStylesheet, getAttribute, getErrorListener, getFeature, getURIResolver, newInstance, newInstance, newTemplates, newTransformer, newTransformer, setAttribute, setErrorListener, setFeature, setURIResolver
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FEATURE

public static final String FEATURE
If TransformerFactory.getFeature(java.lang.String) returns true when passed this value as an argument, the TransformerFactory returned from TransformerFactory.newInstance() may be safely cast to a SAXTransformerFactory.

See Also:
Constant Field Values

FEATURE_XMLFILTER

public static final String FEATURE_XMLFILTER
If TransformerFactory.getFeature(java.lang.String) returns true when passed this value as an argument, the newXMLFilter(Source src) and newXMLFilter(Templates templates) methods are supported.

See Also:
Constant Field Values
Constructor Detail

SAXTransformerFactory

protected SAXTransformerFactory()
The default constructor is protected on purpose.

Method Detail

newTransformerHandler

public abstract TransformerHandler newTransformerHandler(Source src)
                                                  throws TransformerConfigurationException
Get a TransformerHandler object that can process SAX ContentHandler events into a Result, based on the transformation instructions specified by the argument.

Parameters:
src - The Source of the transformation instructions.
Returns:
TransformerHandler ready to transform SAX events.
Throws:
TransformerConfigurationException - If for some reason the TransformerHandler can not be created.

newTransformerHandler

public abstract TransformerHandler newTransformerHandler(Templates templates)
                                                  throws TransformerConfigurationException
Get a TransformerHandler object that can process SAX ContentHandler events into a Result, based on the Templates argument.

Parameters:
templates - The compiled transformation instructions.
Returns:
TransformerHandler ready to transform SAX events.
Throws:
TransformerConfigurationException - If for some reason the TransformerHandler can not be created.

newTransformerHandler

public abstract TransformerHandler newTransformerHandler()
                                                  throws TransformerConfigurationException
Get a TransformerHandler object that can process SAX ContentHandler events into a Result. The transformation is defined as an identity (or copy) transformation, for example to copy a series of SAX parse events into a DOM tree.

Returns:
A non-null reference to a TransformerHandler, that may be used as a ContentHandler for SAX parse events.
Throws:
TransformerConfigurationException - If for some reason the TransformerHandler cannot be created.

newTemplatesHandler

public abstract TemplatesHandler newTemplatesHandler()
                                              throws TransformerConfigurationException
Get a TemplatesHandler object that can process SAX ContentHandler events into a Templates object.

Returns:
A non-null reference to a TransformerHandler, that may be used as a ContentHandler for SAX parse events.
Throws:
TransformerConfigurationException - If for some reason the TemplatesHandler cannot be created.

newXMLFilter

public abstract XMLFilter newXMLFilter(Source src)
                                throws TransformerConfigurationException
Create an XMLFilter that uses the given Source as the transformation instructions.

Parameters:
src - The Source of the transformation instructions.
Returns:
An XMLFilter object, or null if this feature is not supported.
Throws:
TransformerConfigurationException - If for some reason the TemplatesHandler cannot be created.

newXMLFilter

public abstract XMLFilter newXMLFilter(Templates templates)
                                throws TransformerConfigurationException
Create an XMLFilter, based on the Templates argument..

Parameters:
templates - The compiled transformation instructions.
Returns:
An XMLFilter object, or null if this feature is not supported.
Throws:
TransformerConfigurationException - If for some reason the TemplatesHandler cannot be created.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TemplatesHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform.sax
Interface TemplatesHandler

All Superinterfaces:
ContentHandler
public interface TemplatesHandler
extends ContentHandler

A SAX ContentHandler that may be used to process SAX parse events (parsing transformation instructions) into a Templates object.

Note that TemplatesHandler does not need to implement LexicalHandler.

Method Summary
String | getSystemId() Get the base ID (URI or system ID) from where relative URLs will be resolved.
Templates | getTemplates() When a TemplatesHandler object is used as a ContentHandler for the parsing of transformation instructions, it creates a Templates object, which the caller can get once the SAX events have been completed.
void | setSystemId(String systemID) Set the base ID (URI or system ID) for the Templates object created by this builder.
Methods inherited from interface org.xml.sax.ContentHandler
characters, endDocument, endElement, endPrefixMapping, ignorableWhitespace, processingInstruction, setDocumentLocator, skippedEntity, startDocument, startElement, startPrefixMapping

Method Detail

getTemplates

Templates getTemplates()
When a TemplatesHandler object is used as a ContentHandler for the parsing of transformation instructions, it creates a Templates object, which the caller can get once the SAX events have been completed.

Returns:
The Templates object that was created during the SAX event process, or null if no Templates object has been created.

setSystemId

void setSystemId(String systemID)
Set the base ID (URI or system ID) for the Templates object created by this builder. This must be set in order to resolve relative URIs in the stylesheet. This must be called before the startDocument event.

Parameters:
systemID - Base URI for this stylesheet.

getSystemId

String getSystemId()
Get the base ID (URI or system ID) from where relative URLs will be resolved.

Returns:
The systemID that was set with setSystemId(java.lang.String).
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TransformerHandler

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform.sax
Interface TransformerHandler

All Superinterfaces:
ContentHandler, DTDHandler, LexicalHandler
public interface TransformerHandler
extends ContentHandler, LexicalHandler, DTDHandler

A TransformerHandler listens for SAX ContentHandler parse events and transforms them to a Result.

Method Summary
String | getSystemId() Get the base ID (URI or system ID) from where relative URLs will be resolved.
Transformer | getTransformer() Get the Transformer associated with this handler, which is needed in order to set parameters and output properties.
void | setResult(Result result) Set the Result associated with this TransformerHandler to be used for the transformation.
void | setSystemId(String systemID) Set the base ID (URI or system ID) from where relative URLs will be resolved.
Methods inherited from interface org.xml.sax.ContentHandler
characters, endDocument, endElement, endPrefixMapping, ignorableWhitespace, processingInstruction, setDocumentLocator, skippedEntity, startDocument, startElement, startPrefixMapping
Methods inherited from interface org.xml.sax.ext.LexicalHandler
comment, endCDATA, endDTD, endEntity, startCDATA, startDTD, startEntity
Methods inherited from interface org.xml.sax.DTDHandler
notationDecl, unparsedEntityDecl

Method Detail

setResult

void setResult(Result result)
               throws IllegalArgumentException

Set the Result associated with this TransformerHandler to be used for the transformation.

Parameters:
result - A Result instance, should not be null.
Throws:
IllegalArgumentException - if result is invalid for some reason.

setSystemId

void setSystemId(String systemID)
Set the base ID (URI or system ID) from where relative URLs will be resolved.

Parameters:
systemID - Base URI for the source tree.

getSystemId

String getSystemId()
Get the base ID (URI or system ID) from where relative URLs will be resolved.

Returns:
The systemID that was set with setSystemId(java.lang.String).

getTransformer

Transformer getTransformer()

Get the Transformer associated with this handler, which is needed in order to set parameters and output properties.

Returns:
Transformer associated with this TransformerHandler.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Source

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform
Interface Source

All Known Implementing Classes:
DOMSource, JAXBSource, SAXSource, StAXSource, StreamSource
public interface Source

An object that implements this interface contains the information needed to act as source input (XML source or transformation instructions).

Method Summary
String | getSystemId() Get the system identifier that was set with setSystemId.
void | setSystemId(String systemId) Set the system identifier for this Source.

Method Detail

setSystemId

void setSystemId(String systemId)
Set the system identifier for this Source.

The system identifier is optional if the source does not get its data from a URL, but it may still be useful to provide one. The application can use a system identifier, for example, to resolve relative URIs and to include in error messages and warnings.

Parameters:
systemId - The system identifier as a URL string.

getSystemId

String getSystemId()
Get the system identifier that was set with setSystemId.

Returns:
The system identifier that was set with setSystemId, or null if setSystemId was not called.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SourceLocator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform
Interface SourceLocator

All Known Subinterfaces:
DOMLocator
public interface SourceLocator

This interface is primarily for the purposes of reporting where an error occurred in the XML source or transformation instructions.

Method Summary
int | getColumnNumber() Return the character position where the current document event ends.
int | getLineNumber() Return the line number where the current document event ends.
String | getPublicId() Return the public identifier for the current document event.
String | getSystemId() Return the system identifier for the current document event.

Method Detail

getPublicId

String getPublicId()
Return the public identifier for the current document event.

The return value is the public identifier of the document entity or of the external parsed entity in which the markup that triggered the event appears.

Returns:
A string containing the public identifier, or null if none is available.
See Also:
getSystemId()

getSystemId

String getSystemId()
Return the system identifier for the current document event.

The return value is the system identifier of the document entity or of the external parsed entity in which the markup that triggered the event appears.

If the system identifier is a URL, the parser must resolve it fully before passing it to the application.

Returns:
A string containing the system identifier, or null if none is available.
See Also:
getPublicId()

getLineNumber

int getLineNumber()
Return the line number where the current document event ends.

Warning: The return value from the method is intended only as an approximation for the sake of error reporting; it is not intended to provide sufficient information to edit the character content of the original XML document.

The return value is an approximation of the line number in the document entity or external parsed entity where the markup that triggered the event appears.

Returns:
The line number, or -1 if none is available.
See Also:
getColumnNumber()

getColumnNumber

int getColumnNumber()
Return the character position where the current document event ends.

Warning: The return value from the method is intended only as an approximation for the sake of error reporting; it is not intended to provide sufficient information to edit the character content of the original XML document.

The return value is an approximation of the column number in the document entity or external parsed entity where the markup that triggered the event appears.

Returns:
The column number, or -1 if none is available.
See Also:
getLineNumber()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


stax

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.transform.stax

Provides for StAX-specific transformation APIs.

See:
Description

Class Summary
StAXResult | Acts as a holder for an XML Result in the form of a StAX writer,i.e.
StAXSource | Acts as a holder for an XML Source in the form of a StAX reader,i.e.

Package javax.xml.transform.stax Description

Provides for StAX-specific transformation APIs. TODO: better description(s).

Package Specification

  • JSR 173: Streaming API for XML

Related Documentation

For overviews, tutorials, examples, guides, and tool documentation, please see:

  • TODO: Refer to non-spec documentation
  • @see XMLStreamReader
  • @see XMLEventReader

Since:
1.6

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.transform.stax Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.transform.stax

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.transform.stax.StAXResult (implements javax.xml.transform.Result)
    • javax.xml.transform.stax.StAXSource (implements javax.xml.transform.Source)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.transform.stax

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.transform.stax

No usage of javax.xml.transform.stax

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.transform.stax.StAXResult

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.transform.stax.StAXResult

No usage of javax.xml.transform.stax.StAXResult

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.transform.stax.StAXSource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.transform.stax.StAXSource

No usage of javax.xml.transform.stax.StAXSource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


StAXResult

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform.stax
Class StAXResult

java.lang.Object
    extended by  javax.xml.transform.stax.StAXResult
All Implemented Interfaces:
Result
public class StAXResult
extends Object
implements Result

Acts as a holder for an XML Result in the form of a StAX writer,i.e. XMLStreamWriter or XMLEventWriter. StAXResult can be used in all cases that accept a Result, e.g. Transformer, Validator which accept Result as input.

Since:
1.6
See Also:
JSR 173: Streaming API for XML, XMLStreamWriter, XMLEventWriter

Field Summary
static String FEATURE
If TransformerFactory.getFeature(String name) returns true when passed this value as an argument, the Transformer supports Result output of this type.
Fields inherited from interface javax.xml.transform.Result
PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING
Constructor Summary
StAXResult(XMLEventWriter xmlEventWriter)
Creates a new instance of a StAXResult by supplying an XMLEventWriter.
StAXResult(XMLStreamWriter xmlStreamWriter)
Creates a new instance of a StAXResult by supplying an XMLStreamWriter.
Method Summary
String | getSystemId() The returned system identifier is always null.
XMLEventWriter | getXMLEventWriter() Get the XMLEventWriter used by this StAXResult.
XMLStreamWriter | getXMLStreamWriter() Get the XMLStreamWriter used by this StAXResult.
void | setSystemId(String systemId) In the context of a StAXResult, it is not appropriate to explicitly set the system identifier.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FEATURE

public static final String FEATURE
If TransformerFactory.getFeature(String name) returns true when passed this value as an argument, the Transformer supports Result output of this type.

See Also:
Constant Field Values
Constructor Detail

StAXResult

public StAXResult(XMLEventWriter xmlEventWriter)

Creates a new instance of a StAXResult by supplying an XMLEventWriter.

XMLEventWriter must be a non-null reference.

Parameters:
xmlEventWriter - XMLEventWriter used to create this StAXResult.
Throws:
IllegalArgumentException - If xmlEventWriter == null.

StAXResult

public StAXResult(XMLStreamWriter xmlStreamWriter)

Creates a new instance of a StAXResult by supplying an XMLStreamWriter.

XMLStreamWriter must be a non-null reference.

Parameters:
xmlStreamWriter - XMLStreamWriter used to create this StAXResult.
Throws:
IllegalArgumentException - If xmlStreamWriter == null.
Method Detail

getXMLEventWriter

public XMLEventWriter getXMLEventWriter()

Get the XMLEventWriter used by this StAXResult.

XMLEventWriter will be null if this StAXResult was created with a XMLStreamWriter.

Returns:
XMLEventWriter used by this StAXResult.

getXMLStreamWriter

public XMLStreamWriter getXMLStreamWriter()

Get the XMLStreamWriter used by this StAXResult.

XMLStreamWriter will be null if this StAXResult was created with a XMLEventWriter.

Returns:
XMLStreamWriter used by this StAXResult.

setSystemId

public void setSystemId(String systemId)

In the context of a StAXResult, it is not appropriate to explicitly set the system identifier. The XMLEventWriter or XMLStreamWriter used to construct this StAXResult determines the system identifier of the XML result.

An UnsupportedOperationException is always thrown by this method.

Specified by:
setSystemId in interface Result
Parameters:
systemId - Ignored.
Throws:
UnsupportedOperationException - Is always thrown by this method.

getSystemId

public String getSystemId()

The returned system identifier is always null.

Specified by:
getSystemId in interface Result
Returns:
The returned system identifier is always null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


StAXSource

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform.stax
Class StAXSource

java.lang.Object
    extended by  javax.xml.transform.stax.StAXSource
All Implemented Interfaces:
Source
public class StAXSource
extends Object
implements Source

Acts as a holder for an XML Source in the form of a StAX reader,i.e. XMLStreamReader or XMLEventReader. StAXSource can be used in all cases that accept a Source, e.g. Transformer, Validator which accept Source as input.

StAXSources are consumed during processing and are not reusable.

Since:
1.6
See Also:
JSR 173: Streaming API for XML, XMLStreamReader, XMLEventReader

Field Summary
static String FEATURE
If TransformerFactory.getFeature(String name) returns true when passed this value as an argument, the Transformer supports Source input of this type.
Constructor Summary
StAXSource(XMLEventReader xmlEventReader)
Creates a new instance of a StAXSource by supplying an XMLEventReader.
StAXSource(XMLStreamReader xmlStreamReader)
Creates a new instance of a StAXSource by supplying an XMLStreamReader.
Method Summary
String | getSystemId() Get the system identifier used by this StAXSource.
XMLEventReader | getXMLEventReader() Get the XMLEventReader used by this StAXSource.
XMLStreamReader | getXMLStreamReader() Get the XMLStreamReader used by this StAXSource.
void | setSystemId(String systemId) In the context of a StAXSource, it is not appropriate to explicitly set the system identifier.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FEATURE

public static final String FEATURE
If TransformerFactory.getFeature(String name) returns true when passed this value as an argument, the Transformer supports Source input of this type.

See Also:
Constant Field Values
Constructor Detail

StAXSource

public StAXSource(XMLEventReader xmlEventReader)
           throws XMLStreamException

Creates a new instance of a StAXSource by supplying an XMLEventReader.

XMLEventReader must be a non-null reference.

XMLEventReader must be in XMLStreamConstants.START_DOCUMENT or XMLStreamConstants.START_ELEMENT state.

Parameters:
xmlEventReader - XMLEventReader used to create this StAXSource.
Throws:
XMLStreamException - If xmlEventReader access throws an Exception.
IllegalArgumentException - If xmlEventReader == null.
IllegalStateException - If xmlEventReader is not in XMLStreamConstants.START_DOCUMENT or XMLStreamConstants.START_ELEMENT state.

StAXSource

public StAXSource(XMLStreamReader xmlStreamReader)

Creates a new instance of a StAXSource by supplying an XMLStreamReader.

XMLStreamReader must be a non-null reference.

XMLStreamReader must be in XMLStreamConstants.START_DOCUMENT or XMLStreamConstants.START_ELEMENT state.

Parameters:
xmlStreamReader - XMLStreamReader used to create this StAXSource.
Throws:
IllegalArgumentException - If xmlStreamReader == null.
IllegalStateException - If xmlStreamReader is not in XMLStreamConstants.START_DOCUMENT or XMLStreamConstants.START_ELEMENT state.
Method Detail

getXMLEventReader

public XMLEventReader getXMLEventReader()

Get the XMLEventReader used by this StAXSource.

XMLEventReader will be null. if this StAXSource was created with a XMLStreamReader.

Returns:
XMLEventReader used by this StAXSource.

getXMLStreamReader

public XMLStreamReader getXMLStreamReader()

Get the XMLStreamReader used by this StAXSource.

XMLStreamReader will be null if this StAXSource was created with a XMLEventReader.

Returns:
XMLStreamReader used by this StAXSource.

setSystemId

public void setSystemId(String systemId)

In the context of a StAXSource, it is not appropriate to explicitly set the system identifier. The XMLStreamReader or XMLEventReader used to construct this StAXSource determines the system identifier of the XML source.

An UnsupportedOperationException is always thrown by this method.

Specified by:
setSystemId in interface Source
Parameters:
systemId - Ignored.
Throws:
UnsupportedOperationException - Is always thrown by this method.

getSystemId

public String getSystemId()

Get the system identifier used by this StAXSource.

The XMLStreamReader or XMLEventReader used to construct this StAXSource is queried to determine the system identifier of the XML source.

The system identifier may be null or an empty "" String.

Specified by:
getSystemId in interface Source
Returns:
System identifier used by this StAXSource.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


stream

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.transform.stream

This package implements stream- and URI- specific transformation APIs.

See:
Description

Class Summary
StreamResult | Acts as an holder for a transformation result, which may be XML, plain Text, HTML, or some other form of markup.
StreamSource | Acts as an holder for a transformation Source in the form of a stream of XML markup.

Package javax.xml.transform.stream Description

This package implements stream- and URI- specific transformation APIs.

The StreamSource class provides methods for specifying InputStream input, Reader input, and URL input in the form of strings. Even if an input stream or reader is specified as the source, StreamSource.setSystemId(java.lang.String) should still be called, so that the transformer can know from where it should resolve relative URIs. The public identifier is always optional: if the application writer includes one, it will be provided as part of the SourceLocator information.

The StreamResult class provides methods for specifying OutputStream, Writer, or an output system ID, as the output of the transformation result.

Normally streams should be used rather than readers or writers, for both the Source and Result, since readers and writers already have the encoding established to and from the internal Unicode format. However, there are times when it is useful to write to a character stream, such as when using a StringWriter in order to write to a String, or in the case of reading source XML from a StringReader.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.transform.stream Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.transform.stream

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.transform.stream.StreamResult (implements javax.xml.transform.Result)
    • javax.xml.transform.stream.StreamSource (implements javax.xml.transform.Source)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.transform.stream

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.transform.stream

No usage of javax.xml.transform.stream

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.transform.stream.StreamResult

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.transform.stream.StreamResult

No usage of javax.xml.transform.stream.StreamResult

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.transform.stream.StreamSource

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.transform.stream.StreamSource

No usage of javax.xml.transform.stream.StreamSource

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


StreamResult

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform.stream
Class StreamResult

java.lang.Object
    extended by  javax.xml.transform.stream.StreamResult
All Implemented Interfaces:
Result
public class StreamResult
extends Object
implements Result

Acts as an holder for a transformation result, which may be XML, plain Text, HTML, or some other form of markup.

Field Summary
static String FEATURE
If TransformerFactory.getFeature(java.lang.String) returns true when passed this value as an argument, the Transformer supports Result output of this type.
Fields inherited from interface javax.xml.transform.Result
PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING
Constructor Summary
StreamResult()
Zero-argument default constructor.
StreamResult(File f)
Construct a StreamResult from a File.
StreamResult(OutputStream outputStream)
Construct a StreamResult from a byte stream.
StreamResult(String systemId)
Construct a StreamResult from a URL.
StreamResult(Writer writer)
Construct a StreamResult from a character stream.
Method Summary
OutputStream | getOutputStream() Get the byte stream that was set with setOutputStream.
String | getSystemId() Get the system identifier that was set with setSystemId.
Writer | getWriter() Get the character stream that was set with setWriter.
void | setOutputStream(OutputStream outputStream) Set the ByteStream that is to be written to.
void | setSystemId(File f) Set the system ID from a File reference.
void | setSystemId(String systemId) Set the systemID that may be used in association with the byte or character stream, or, if neither is set, use this value as a writeable URI (probably a file name).
void | setWriter(Writer writer) Set the writer that is to receive the result.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FEATURE

public static final String FEATURE
If TransformerFactory.getFeature(java.lang.String) returns true when passed this value as an argument, the Transformer supports Result output of this type.

See Also:
Constant Field Values
Constructor Detail

StreamResult

public StreamResult()
Zero-argument default constructor.

StreamResult

public StreamResult(OutputStream outputStream)
Construct a StreamResult from a byte stream. Normally, a stream should be used rather than a reader, so that the transformer may use instructions contained in the transformation instructions to control the encoding.

Parameters:
outputStream - A valid OutputStream reference.

StreamResult

public StreamResult(Writer writer)
Construct a StreamResult from a character stream. Normally, a stream should be used rather than a reader, so that the transformer may use instructions contained in the transformation instructions to control the encoding. However, there are times when it is useful to write to a character stream, such as when using a StringWriter.

Parameters:
writer - A valid Writer reference.

StreamResult

public StreamResult(String systemId)
Construct a StreamResult from a URL.

Parameters:
systemId - Must be a String that conforms to the URI syntax.

StreamResult

public StreamResult(File f)
Construct a StreamResult from a File.

Parameters:
f - Must a non-null File reference.
Method Detail

setOutputStream

public void setOutputStream(OutputStream outputStream)
Set the ByteStream that is to be written to. Normally, a stream should be used rather than a reader, so that the transformer may use instructions contained in the transformation instructions to control the encoding.

Parameters:
outputStream - A valid OutputStream reference.

getOutputStream

public OutputStream getOutputStream()
Get the byte stream that was set with setOutputStream.

Returns:
The byte stream that was set with setOutputStream, or null if setOutputStream or the ByteStream constructor was not called.

setWriter

public void setWriter(Writer writer)
Set the writer that is to receive the result. Normally, a stream should be used rather than a writer, so that the transformer may use instructions contained in the transformation instructions to control the encoding. However, there are times when it is useful to write to a writer, such as when using a StringWriter.

Parameters:
writer - A valid Writer reference.

getWriter

public Writer getWriter()
Get the character stream that was set with setWriter.

Returns:
The character stream that was set with setWriter, or null if setWriter or the Writer constructor was not called.

setSystemId

public void setSystemId(String systemId)
Set the systemID that may be used in association with the byte or character stream, or, if neither is set, use this value as a writeable URI (probably a file name).

Specified by:
setSystemId in interface Result
Parameters:
systemId - The system identifier as a URI string.

setSystemId

public void setSystemId(File f)

Set the system ID from a File reference.

Parameters:
f - Must a non-null File reference.

getSystemId

public String getSystemId()
Get the system identifier that was set with setSystemId.

Specified by:
getSystemId in interface Result
Returns:
The system identifier that was set with setSystemId, or null if setSystemId was not called.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


StreamSource

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform.stream
Class StreamSource

java.lang.Object
    extended by  javax.xml.transform.stream.StreamSource
All Implemented Interfaces:
Source
public class StreamSource
extends Object
implements Source

Acts as an holder for a transformation Source in the form of a stream of XML markup.

Note: Due to their internal use of either a Reader or InputStream instance, StreamSource instances may only be used once.

Field Summary
static String FEATURE
If TransformerFactory.getFeature(java.lang.String) returns true when passed this value as an argument, the Transformer supports Source input of this type.
Constructor Summary
StreamSource()
Zero-argument default constructor.
StreamSource(File f)
Construct a StreamSource from a File.
StreamSource(InputStream inputStream)
Construct a StreamSource from a byte stream.
StreamSource(InputStream inputStream, String systemId)
Construct a StreamSource from a byte stream.
StreamSource(Reader reader)
Construct a StreamSource from a character reader.
StreamSource(Reader reader, String systemId)
Construct a StreamSource from a character reader.
StreamSource(String systemId)
Construct a StreamSource from a URL.
Method Summary
InputStream | getInputStream() Get the byte stream that was set with setByteStream.
String | getPublicId() Get the public identifier that was set with setPublicId.
Reader | getReader() Get the character stream that was set with setReader.
String | getSystemId() Get the system identifier that was set with setSystemId.
void | setInputStream(InputStream inputStream) Set the byte stream to be used as input.
void | setPublicId(String publicId) Set the public identifier for this Source.
void | setReader(Reader reader) Set the input to be a character reader.
void | setSystemId(File f) Set the system ID from a File reference.
void | setSystemId(String systemId) Set the system identifier for this Source.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FEATURE

public static final String FEATURE
If TransformerFactory.getFeature(java.lang.String) returns true when passed this value as an argument, the Transformer supports Source input of this type.

See Also:
Constant Field Values
Constructor Detail

StreamSource

public StreamSource()

Zero-argument default constructor. If this constructor is used, and no Stream source is set using setInputStream(java.io.InputStream inputStream) or setReader(java.io.Reader reader), then the Transformer will create an empty source InputStream using new InputStream().

See Also:
Transformer.transform(Source xmlSource, Result outputTarget)

StreamSource

public StreamSource(InputStream inputStream)
Construct a StreamSource from a byte stream. Normally, a stream should be used rather than a reader, so the XML parser can resolve character encoding specified by the XML declaration.

If this constructor is used to process a stylesheet, normally setSystemId should also be called, so that relative URI references can be resolved.

Parameters:
inputStream - A valid InputStream reference to an XML stream.

StreamSource

public StreamSource(InputStream inputStream,
                    String systemId)
Construct a StreamSource from a byte stream. Normally, a stream should be used rather than a reader, so that the XML parser can resolve character encoding specified by the XML declaration.

This constructor allows the systemID to be set in addition to the input stream, which allows relative URIs to be processed.

Parameters:
inputStream - A valid InputStream reference to an XML stream.
systemId - Must be a String that conforms to the URI syntax.

StreamSource

public StreamSource(Reader reader)
Construct a StreamSource from a character reader. Normally, a stream should be used rather than a reader, so that the XML parser can resolve character encoding specified by the XML declaration. However, in many cases the encoding of the input stream is already resolved, as in the case of reading XML from a StringReader.

Parameters:
reader - A valid Reader reference to an XML character stream.

StreamSource

public StreamSource(Reader reader,
                    String systemId)
Construct a StreamSource from a character reader. Normally, a stream should be used rather than a reader, so that the XML parser may resolve character encoding specified by the XML declaration. However, in many cases the encoding of the input stream is already resolved, as in the case of reading XML from a StringReader.

Parameters:
reader - A valid Reader reference to an XML character stream.
systemId - Must be a String that conforms to the URI syntax.

StreamSource

public StreamSource(String systemId)
Construct a StreamSource from a URL.

Parameters:
systemId - Must be a String that conforms to the URI syntax.

StreamSource

public StreamSource(File f)
Construct a StreamSource from a File.

Parameters:
f - Must a non-null File reference.
Method Detail

setInputStream

public void setInputStream(InputStream inputStream)
Set the byte stream to be used as input. Normally, a stream should be used rather than a reader, so that the XML parser can resolve character encoding specified by the XML declaration.

If this Source object is used to process a stylesheet, normally setSystemId should also be called, so that relative URL references can be resolved.

Parameters:
inputStream - A valid InputStream reference to an XML stream.

getInputStream

public InputStream getInputStream()
Get the byte stream that was set with setByteStream.

Returns:
The byte stream that was set with setByteStream, or null if setByteStream or the ByteStream constructor was not called.

setReader

public void setReader(Reader reader)
Set the input to be a character reader. Normally, a stream should be used rather than a reader, so that the XML parser can resolve character encoding specified by the XML declaration. However, in many cases the encoding of the input stream is already resolved, as in the case of reading XML from a StringReader.

Parameters:
reader - A valid Reader reference to an XML CharacterStream.

getReader

public Reader getReader()
Get the character stream that was set with setReader.

Returns:
The character stream that was set with setReader, or null if setReader or the Reader constructor was not called.

setPublicId

public void setPublicId(String publicId)
Set the public identifier for this Source.

The public identifier is always optional: if the application writer includes one, it will be provided as part of the location information.

Parameters:
publicId - The public identifier as a string.

getPublicId

public String getPublicId()
Get the public identifier that was set with setPublicId.

Returns:
The public identifier that was set with setPublicId, or null if setPublicId was not called.

setSystemId

public void setSystemId(String systemId)
Set the system identifier for this Source.

The system identifier is optional if there is a byte stream or a character stream, but it is still useful to provide one, since the application can use it to resolve relative URIs and can include it in error messages and warnings (the parser will attempt to open a connection to the URI only if there is no byte stream or character stream specified).

Specified by:
setSystemId in interface Source
Parameters:
systemId - The system identifier as a URL string.

getSystemId

public String getSystemId()
Get the system identifier that was set with setSystemId.

Specified by:
getSystemId in interface Source
Returns:
The system identifier that was set with setSystemId, or null if setSystemId was not called.

setSystemId

public void setSystemId(File f)
Set the system ID from a File reference.

Parameters:
f - Must a non-null File reference.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Templates

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform
Interface Templates

public interface Templates

An object that implements this interface is the runtime representation of processed transformation instructions.

Templates must be threadsafe for a given instance over multiple threads running concurrently, and may be used multiple times in a given session.

Method Summary
Properties | getOutputProperties() Get the properties corresponding to the effective xsl:output element.
Transformer | newTransformer() Create a new transformation context for this Templates object.

Method Detail

newTransformer

Transformer newTransformer()
                           throws TransformerConfigurationException
Create a new transformation context for this Templates object.

Returns:
A valid non-null instance of a Transformer.
Throws:
TransformerConfigurationException - if a Transformer can not be created.

getOutputProperties

Properties getOutputProperties()
Get the properties corresponding to the effective xsl:output element. The object returned will be a clone of the internal values. Accordingly, it can be mutated without mutating the Templates object, and then handed in to Transformer.setOutputProperties(java.util.Properties).

The properties returned should contain properties set by the stylesheet, and these properties are "defaulted" by default properties specified by section 16 of the XSL Transformations (XSLT) W3C Recommendation. The properties that were specifically set by the stylesheet should be in the base Properties list, while the XSLT default properties that were not specifically set should be in the "default" Properties list. Thus, getOutputProperties().getProperty(String key) will obtain any property in that was set by the stylesheet, or the default properties, while getOutputProperties().get(String key) will only retrieve properties that were explicitly set in the stylesheet.

For XSLT, Attribute Value Templates attribute values will be returned unexpanded (since there is no context at this point). The namespace prefixes inside Attribute Value Templates will be unexpanded, so that they remain valid XPath values.

Returns:
A Properties object, never null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Transformer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform
Class Transformer

java.lang.Object
    extended by  javax.xml.transform.Transformer

public abstract class Transformer
extends Object

An instance of this abstract class can transform a source tree into a result tree.

An instance of this class can be obtained with the TransformerFactory.newTransformer method. This instance may then be used to process XML from a variety of sources and write the transformation output to a variety of sinks.

An object of this class may not be used in multiple threads running concurrently. Different Transformers may be used concurrently by different threads.

A Transformer may be used multiple times. Parameters and output properties are preserved across transformations.

Constructor Summary
protected Transformer()
Default constructor is protected on purpose.
Method Summary
abstract  void clearParameters()
Clear all parameters set with setParameter.
abstract  ErrorListener getErrorListener()
Get the error event handler in effect for the transformation.
abstract  Properties getOutputProperties()
Get a copy of the output properties for the transformation.
abstract  String getOutputProperty(String name)
Get an output property that is in effect for the transformer.
abstract  Object getParameter(String name)
Get a parameter that was explicitly set with setParameter.
abstract  URIResolver getURIResolver()
Get an object that will be used to resolve URIs used in document().
 void reset()
Reset this Transformer to its original configuration.
abstract  void setErrorListener(ErrorListener listener)
Set the error event listener in effect for the transformation.
abstract  void setOutputProperties(Properties oformat)
Set the output properties for the transformation.
abstract  void setOutputProperty(String name, String value)
Set an output property that will be in effect for the transformation.
abstract  void setParameter(String name, Object value)
Add a parameter for the transformation.
abstract  void setURIResolver(URIResolver resolver)
Set an object that will be used to resolve URIs used in document().
abstract  void transform(Source xmlSource, Result outputTarget)
Transform the XML Source to a Result.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Transformer

protected Transformer()
Default constructor is protected on purpose.

Method Detail

reset

public void reset()

Reset this Transformer to its original configuration.

Transformer is reset to the same state as when it was created with TransformerFactory.newTransformer(), TransformerFactory.newTransformer(Source source) or Templates.newTransformer(). reset() is designed to allow the reuse of existing Transformers thus saving resources associated with the creation of new Transformers.

The reset Transformer is not guaranteed to have the same URIResolver or ErrorListener Objects, e.g. Object.equals(Object obj). It is guaranteed to have a functionally equal URIResolver and ErrorListener.

Throws:
UnsupportedOperationException - When implementation does not override this method.
Since:
1.5

transform

public abstract void transform(Source xmlSource,
                               Result outputTarget)
                        throws TransformerException

Transform the XML Source to a Result. Specific transformation behavior is determined by the settings of the TransformerFactory in effect when the Transformer was instantiated and any modifications made to the Transformer instance.

An empty Source is represented as an empty document as constructed by DocumentBuilder.newDocument(). The result of transforming an empty Source depends on the transformation behavior; it is not always an empty Result.

Parameters:
xmlSource - The XML input to transform.
outputTarget - The Result of transforming the xmlSource.
Throws:
TransformerException - If an unrecoverable error occurs during the course of the transformation.

setParameter

public abstract void setParameter(String name,
                                  Object value)
Add a parameter for the transformation.

Pass a qualified name as a two-part string, the namespace URI enclosed in curly braces ({}), followed by the local name. If the name has a null URL, the String only contain the local name. An application can safely check for a non-null URI by testing to see if the first character of the name is a '{' character.

For example, if a URI and local name were obtained from an element defined with <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>, then the qualified name would be "{http://xyz.foo.com/yada/baz.html}foo". Note that no prefix is used.

Parameters:
name - The name of the parameter, which may begin with a namespace URI in curly braces ({}).
value - The value object. This can be any valid Java object. It is up to the processor to provide the proper object coersion or to simply pass the object on for use in an extension.
Throws:
NullPointerException - If value is null.

getParameter

public abstract Object getParameter(String name)
Get a parameter that was explicitly set with setParameter.

This method does not return a default parameter value, which cannot be determined until the node context is evaluated during the transformation process.

Parameters:
name - of Object to get
Returns:
A parameter that has been set with setParameter.

clearParameters

public abstract void clearParameters()
Clear all parameters set with setParameter.

setURIResolver

public abstract void setURIResolver(URIResolver resolver)
Set an object that will be used to resolve URIs used in document().

If the resolver argument is null, the URIResolver value will be cleared and the transformer will no longer have a resolver.

Parameters:
resolver - An object that implements the URIResolver interface, or null.

getURIResolver

public abstract URIResolver getURIResolver()
Get an object that will be used to resolve URIs used in document().

Returns:
An object that implements the URIResolver interface, or null.

setOutputProperties

public abstract void setOutputProperties(Properties oformat)
Set the output properties for the transformation. These properties will override properties set in the Templates with xsl:output.

If argument to this function is null, any properties previously set are removed, and the value will revert to the value defined in the templates object.

Pass a qualified property key name as a two-part string, the namespace URI enclosed in curly braces ({}), followed by the local name. If the name has a null URL, the String only contain the local name. An application can safely check for a non-null URI by testing to see if the first character of the name is a '{' character.

For example, if a URI and local name were obtained from an element defined with <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>, then the qualified name would be "{http://xyz.foo.com/yada/baz.html}foo". Note that no prefix is used.

An IllegalArgumentException is thrown if any of the argument keys are not recognized and are not namespace qualified.

Parameters:
oformat - A set of output properties that will be used to override any of the same properties in affect for the transformation.
Throws:
IllegalArgumentException - When keys are not recognized and are not namespace qualified.
See Also:
OutputKeys, Properties

getOutputProperties

public abstract Properties getOutputProperties()

Get a copy of the output properties for the transformation.

The properties returned should contain properties set by the user, and properties set by the stylesheet, and these properties are "defaulted" by default properties specified by section 16 of the XSL Transformations (XSLT) W3C Recommendation. The properties that were specifically set by the user or the stylesheet should be in the base Properties list, while the XSLT default properties that were not specifically set should be the default Properties list. Thus, getOutputProperties().getProperty(String key) will obtain any property in that was set by setOutputProperty(java.lang.String, java.lang.String), setOutputProperties(java.util.Properties), in the stylesheet, or the default properties, while getOutputProperties().get(String key) will only retrieve properties that were explicitly set by setOutputProperty(java.lang.String, java.lang.String), setOutputProperties(java.util.Properties), or in the stylesheet.

Note that mutation of the Properties object returned will not effect the properties that the transformer contains.

If any of the argument keys are not recognized and are not namespace qualified, the property will be ignored and not returned. In other words the behaviour is not orthogonal with setOutputProperties.

Returns:
A copy of the set of output properties in effect for the next transformation.
See Also:
OutputKeys, Properties, XSL Transformations (XSLT) Version 1.0

setOutputProperty

public abstract void setOutputProperty(String name,
                                       String value)
                                throws IllegalArgumentException
Set an output property that will be in effect for the transformation.

Pass a qualified property name as a two-part string, the namespace URI enclosed in curly braces ({}), followed by the local name. If the name has a null URL, the String only contain the local name. An application can safely check for a non-null URI by testing to see if the first character of the name is a '{' character.

For example, if a URI and local name were obtained from an element defined with <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>, then the qualified name would be "{http://xyz.foo.com/yada/baz.html}foo". Note that no prefix is used.

The Properties object that was passed to setOutputProperties(java.util.Properties) won't be effected by calling this method.

Parameters:
name - A non-null String that specifies an output property name, which may be namespace qualified.
value - The non-null string value of the output property.
Throws:
IllegalArgumentException - If the property is not supported, and is not qualified with a namespace.
See Also:
OutputKeys

getOutputProperty

public abstract String getOutputProperty(String name)
                                  throws IllegalArgumentException

Get an output property that is in effect for the transformer.

If a property has been set using setOutputProperty(java.lang.String, java.lang.String), that value will be returned. Otherwise, if a property is explicitly specified in the stylesheet, that value will be returned. If the value of the property has been defaulted, that is, if no value has been set explicitly either with setOutputProperty(java.lang.String, java.lang.String) or in the stylesheet, the result may vary depending on implementation and input stylesheet.

Parameters:
name - A non-null String that specifies an output property name, which may be namespace qualified.
Returns:
The string value of the output property, or null if no property was found.
Throws:
IllegalArgumentException - If the property is not supported.
See Also:
OutputKeys

setErrorListener

public abstract void setErrorListener(ErrorListener listener)
                               throws IllegalArgumentException
Set the error event listener in effect for the transformation.

Parameters:
listener - The new error listener.
Throws:
IllegalArgumentException - if listener is null.

getErrorListener

public abstract ErrorListener getErrorListener()
Get the error event handler in effect for the transformation. Implementations must provide a default error listener.

Returns:
The current error handler, which should never be null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TransformerConfigurationException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform
Class TransformerConfigurationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.transform.TransformerException
                extended by  javax.xml.transform.TransformerConfigurationException
All Implemented Interfaces:
Serializable
public class TransformerConfigurationException
extends TransformerException

Indicates a serious configuration error.

See Also:
Serialized Form

Constructor Summary
TransformerConfigurationException()
Create a new TransformerConfigurationException with no detail mesage.
TransformerConfigurationException(String msg)
Create a new TransformerConfigurationException with the String specified as an error message.
TransformerConfigurationException(String message, SourceLocator locator)
Create a new TransformerConfigurationException from a message and a Locator.
TransformerConfigurationException(String message, SourceLocator locator, Throwable e)
Wrap an existing exception in a TransformerConfigurationException.
TransformerConfigurationException(String msg, Throwable e)
Create a new TransformerConfigurationException with the given Exception base cause and detail message.
TransformerConfigurationException(Throwable e)
Create a new TransformerConfigurationException with a given Exception base cause of the error.
Method Summary
Methods inherited from class javax.xml.transform.TransformerException
getCause, getException, getLocationAsString, getLocator, getMessageAndLocation, initCause, printStackTrace, printStackTrace, printStackTrace, setLocator
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TransformerConfigurationException

public TransformerConfigurationException()
Create a new TransformerConfigurationException with no detail mesage.

TransformerConfigurationException

public TransformerConfigurationException(String msg)
Create a new TransformerConfigurationException with the String specified as an error message.

Parameters:
msg - The error message for the exception.

TransformerConfigurationException

public TransformerConfigurationException(Throwable e)
Create a new TransformerConfigurationException with a given Exception base cause of the error.

Parameters:
e - The exception to be encapsulated in a TransformerConfigurationException.

TransformerConfigurationException

public TransformerConfigurationException(String msg,
                                         Throwable e)
Create a new TransformerConfigurationException with the given Exception base cause and detail message.

Parameters:
e - The exception to be encapsulated in a TransformerConfigurationException
msg - The detail message.

TransformerConfigurationException

public TransformerConfigurationException(String message,
                                         SourceLocator locator)
Create a new TransformerConfigurationException from a message and a Locator.

This constructor is especially useful when an application is creating its own exception from within a DocumentHandler callback.

Parameters:
message - The error or warning message.
locator - The locator object for the error or warning.

TransformerConfigurationException

public TransformerConfigurationException(String message,
                                         SourceLocator locator,
                                         Throwable e)
Wrap an existing exception in a TransformerConfigurationException.

Parameters:
message - The error or warning message, or null to use the message from the embedded exception.
locator - The locator object for the error or warning.
e - Any exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TransformerException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform
Class TransformerException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.transform.TransformerException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
TransformerConfigurationException
public class TransformerException
extends Exception

This class specifies an exceptional condition that occured during the transformation process.

See Also:
Serialized Form

Constructor Summary
TransformerException(String message)
Create a new TransformerException.
TransformerException(String message, SourceLocator locator)
Create a new TransformerException from a message and a Locator.
TransformerException(String message, SourceLocator locator, Throwable e)
Wrap an existing exception in a TransformerException.
TransformerException(String message, Throwable e)
Wrap an existing exception in a TransformerException.
TransformerException(Throwable e)
Create a new TransformerException wrapping an existing exception.
Method Summary
Throwable | getCause() Returns the cause of this throwable or null if the cause is nonexistent or unknown.
Throwable | getException() This method retrieves an exception that this exception wraps.
String | getLocationAsString() Get the location information as a string.
SourceLocator | getLocator() Method getLocator retrieves an instance of a SourceLocator object that specifies where an error occured.
String | getMessageAndLocation() Get the error message with location information appended.
Throwable | initCause(Throwable cause) Initializes the cause of this throwable to the specified value.
void | printStackTrace() Print the the trace of methods from where the error originated.
void | printStackTrace(PrintStream s) Print the the trace of methods from where the error originated.
void | printStackTrace(PrintWriter s) Print the the trace of methods from where the error originated.
void | setLocator(SourceLocator location) Method setLocator sets an instance of a SourceLocator object that specifies where an error occured.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TransformerException

public TransformerException(String message)
Create a new TransformerException.

Parameters:
message - The error or warning message.

TransformerException

public TransformerException(Throwable e)
Create a new TransformerException wrapping an existing exception.

Parameters:
e - The exception to be wrapped.

TransformerException

public TransformerException(String message,
                            Throwable e)
Wrap an existing exception in a TransformerException.

This is used for throwing processor exceptions before the processing has started.

Parameters:
message - The error or warning message, or null to use the message from the embedded exception.
e - Any exception

TransformerException

public TransformerException(String message,
                            SourceLocator locator)
Create a new TransformerException from a message and a Locator.

This constructor is especially useful when an application is creating its own exception from within a DocumentHandler callback.

Parameters:
message - The error or warning message.
locator - The locator object for the error or warning.

TransformerException

public TransformerException(String message,
                            SourceLocator locator,
                            Throwable e)
Wrap an existing exception in a TransformerException.

Parameters:
message - The error or warning message, or null to use the message from the embedded exception.
locator - The locator object for the error or warning.
e - Any exception
Method Detail

getLocator

public SourceLocator getLocator()
Method getLocator retrieves an instance of a SourceLocator object that specifies where an error occured.

Returns:
A SourceLocator object, or null if none was specified.

setLocator

public void setLocator(SourceLocator location)
Method setLocator sets an instance of a SourceLocator object that specifies where an error occured.

Parameters:
location - A SourceLocator object, or null to clear the location.

getException

public Throwable getException()
This method retrieves an exception that this exception wraps.

Returns:
An Throwable object, or null.
See Also:
getCause()

getCause

public Throwable getCause()
Returns the cause of this throwable or null if the cause is nonexistent or unknown. (The cause is the throwable that caused this throwable to get thrown.)

Overrides:
getCause in class Throwable
Returns:
the cause of this throwable or null if the cause is nonexistent or unknown.

initCause

public Throwable initCause(Throwable cause)
Initializes the cause of this throwable to the specified value. (The cause is the throwable that caused this throwable to get thrown.)

This method can be called at most once. It is generally called from within the constructor, or immediately after creating the throwable. If this throwable was created with TransformerException(Throwable) or TransformerException(String,Throwable), this method cannot be called even once.

Overrides:
initCause in class Throwable
Parameters:
cause - the cause (which is saved for later retrieval by the getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
Returns:
a reference to this Throwable instance.
Throws:
IllegalArgumentException - if cause is this throwable. (A throwable cannot be its own cause.)
IllegalStateException - if this throwable was created with TransformerException(Throwable) or TransformerException(String,Throwable), or this method has already been called on this throwable.

getMessageAndLocation

public String getMessageAndLocation()
Get the error message with location information appended.

Returns:
A String representing the error message with location information appended.

getLocationAsString

public String getLocationAsString()
Get the location information as a string.

Returns:
A string with location info, or null if there is no location information.

printStackTrace

public void printStackTrace()
Print the the trace of methods from where the error originated. This will trace all nested exception objects, as well as this object.

Overrides:
printStackTrace in class Throwable

printStackTrace

public void printStackTrace(PrintStream s)
Print the the trace of methods from where the error originated. This will trace all nested exception objects, as well as this object.

Overrides:
printStackTrace in class Throwable
Parameters:
s - The stream where the dump will be sent to.

printStackTrace

public void printStackTrace(PrintWriter s)
Print the the trace of methods from where the error originated. This will trace all nested exception objects, as well as this object.

Overrides:
printStackTrace in class Throwable
Parameters:
s - The writer where the dump will be sent to.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TransformerFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform
Class TransformerFactory

java.lang.Object
    extended by  javax.xml.transform.TransformerFactory
Direct Known Subclasses:
SAXTransformerFactory
public abstract class TransformerFactory
extends Object

A TransformerFactory instance can be used to create Transformer and Templates objects.

The system property that determines which Factory implementation to create is named "javax.xml.transform.TransformerFactory". This property names a concrete subclass of the TransformerFactory abstract class. If the property is not defined, a platform default is be used.

Constructor Summary
protected TransformerFactory()
Default constructor is protected on purpose.
Method Summary
abstract  Source getAssociatedStylesheet(Source source, String media, String title, String charset)
Get the stylesheet specification(s) associated with the XML Source document via the xml-stylesheet processing instruction that match the given criteria.
abstract  Object getAttribute(String name)
Allows the user to retrieve specific attributes on the underlying implementation.
abstract  ErrorListener getErrorListener()
Get the error event handler for the TransformerFactory.
abstract  boolean getFeature(String name)
Look up the value of a feature.
abstract  URIResolver getURIResolver()
Get the object that is used by default during the transformation to resolve URIs used in document(), xsl:import, or xsl:include.
static TransformerFactory newInstance()
Obtain a new instance of a TransformerFactory.
static TransformerFactory newInstance(String factoryClassName, ClassLoader classLoader)
Obtain a new instance of a TransformerFactory from factory class name.
abstract  Templates newTemplates(Source source)
Process the Source into a Templates object, which is a a compiled representation of the source.
abstract  Transformer newTransformer()
Create a new Transformer that performs a copy of the Source to the Result.
abstract  Transformer newTransformer(Source source)
Process the Source into a Transformer Object.
abstract  void setAttribute(String name, Object value)
Allows the user to set specific attributes on the underlying implementation.
abstract  void setErrorListener(ErrorListener listener)
Set the error event listener for the TransformerFactory, which is used for the processing of transformation instructions, and not for the transformation itself.
abstract  void setFeature(String name, boolean value)
Set a feature for this TransformerFactory and Transformers or Templates created by this factory.
abstract  void setURIResolver(URIResolver resolver)
Set an object that is used by default during the transformation to resolve URIs used in document(), xsl:import, or xsl:include.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TransformerFactory

protected TransformerFactory()
Default constructor is protected on purpose.

Method Detail

newInstance

public static TransformerFactory newInstance()
                                      throws TransformerFactoryConfigurationError

Obtain a new instance of a TransformerFactory. This static method creates a new factory instance This method uses the following ordered lookup procedure to determine the TransformerFactory implementation class to load:

  • Use the javax.xml.transform.TransformerFactory system property.
  • Use the properties file "lib/jaxp.properties" in the JRE directory. This configuration file is in standard java.util.Properties format and contains the fully qualified name of the implementation class with the key being the system property defined above. The jaxp.properties file is read only once by the JAXP implementation and it's values are then cached for future use. If the file does not exist when the first attempt is made to read from it, no further attempts are made to check for its existence. It is not possible to change the value of any property in jaxp.properties after it has been read for the first time.
  • Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for a classname in the file META-INF/services/javax.xml.transform.TransformerFactory in jars available to the runtime.
  • Platform default TransformerFactory instance.

Once an application has obtained a reference to a TransformerFactory it can use the factory to configure and obtain transformer instances.

Returns:
new TransformerFactory instance, never null.
Throws:
TransformerFactoryConfigurationError - Thrown if the implementation is not available or cannot be instantiated.

newInstance

public static TransformerFactory newInstance(String factoryClassName,
                                             ClassLoader classLoader)
                                      throws TransformerFactoryConfigurationError

Obtain a new instance of a TransformerFactory from factory class name. This function is useful when there are multiple providers in the classpath. It gives more control to the application as it can specify which provider should be loaded.

Once an application has obtained a reference to a TransformerFactory it can use the factory to configure and obtain transformer instances.

Tip for Trouble-shooting

Setting the jaxp.debug system property will cause this method to print a lot of debug messages to System.err about what it is doing and where it is looking at.

If you have problems try:

 java -Djaxp.debug=1 YourProgram ....

Parameters:
factoryClassName - fully qualified factory class name that provides implementation of javax.xml.transform.TransformerFactory.
classLoader - ClassLoader used to load the factory class. If null current Thread's context classLoader is used to load the factory class.
Returns:
new TransformerFactory instance, never null.
Throws:
TransformerFactoryConfigurationError - if factoryClassName is null, or the factory class cannot be loaded, instantiated.
Since:
1.6
See Also:
newInstance()

newTransformer

public abstract Transformer newTransformer(Source source)
                                    throws TransformerConfigurationException

Process the Source into a Transformer Object. The Source is an XSLT document that conforms to XSL Transformations (XSLT) Version 1.0. Care must be taken not to use this Transformer in multiple Threads running concurrently. Different TransformerFactories can be used concurrently by different Threads.

Parameters:
source - Source of XSLT document used to create Transformer. Examples of XML Sources include DOMSource, SAXSource, and StreamSource.
Returns:
A Transformer object that may be used to perform a transformation in a single Thread, never null.
Throws:
TransformerConfigurationException - Thrown if there are errors when parsing the Source or it is not possible to create a Transformer instance.
See Also:
XSL Transformations (XSLT) Version 1.0

newTransformer

public abstract Transformer newTransformer()
                                    throws TransformerConfigurationException

Create a new Transformer that performs a copy of the Source to the Result. i.e. the "identity transform".

Returns:
A Transformer object that may be used to perform a transformation in a single thread, never null.
Throws:
TransformerConfigurationException - When it is not possible to create a Transformer instance.

newTemplates

public abstract Templates newTemplates(Source source)
                                throws TransformerConfigurationException
Process the Source into a Templates object, which is a a compiled representation of the source. This Templates object may then be used concurrently across multiple threads. Creating a Templates object allows the TransformerFactory to do detailed performance optimization of transformation instructions, without penalizing runtime transformation.

Parameters:
source - An object that holds a URL, input stream, etc.
Returns:
A Templates object capable of being used for transformation purposes, never null.
Throws:
TransformerConfigurationException - When parsing to construct the Templates object fails.

getAssociatedStylesheet

public abstract Source getAssociatedStylesheet(Source source,
                                               String media,
                                               String title,
                                               String charset)
                                        throws TransformerConfigurationException

Get the stylesheet specification(s) associated with the XML Source document via the xml-stylesheet processing instruction that match the given criteria. Note that it is possible to return several stylesheets, in which case they are applied as if they were a list of imports or cascades in a single stylesheet.

Parameters:
source - The XML source document.
media - The media attribute to be matched. May be null, in which case the prefered templates will be used (i.e. alternate = no).
title - The value of the title attribute to match. May be null.
charset - The value of the charset attribute to match. May be null.
Returns:
A Source Object suitable for passing to the TransformerFactory.
Throws:
TransformerConfigurationException - An Exception is thrown if an error occurings during parsing of the source.
See Also:
Associating Style Sheets with XML documents Version 1.0

setURIResolver

public abstract void setURIResolver(URIResolver resolver)
Set an object that is used by default during the transformation to resolve URIs used in document(), xsl:import, or xsl:include.

Parameters:
resolver - An object that implements the URIResolver interface, or null.

getURIResolver

public abstract URIResolver getURIResolver()
Get the object that is used by default during the transformation to resolve URIs used in document(), xsl:import, or xsl:include.

Returns:
The URIResolver that was set with setURIResolver.

setFeature

public abstract void setFeature(String name,
                                boolean value)
                         throws TransformerConfigurationException

Set a feature for this TransformerFactory and Transformers or Templates created by this factory.

Feature names are fully qualified URIs. Implementations may define their own features. An TransformerConfigurationException is thrown if this TransformerFactory or the Transformers or Templates it creates cannot support the feature. It is possible for an TransformerFactory to expose a feature value but be unable to change its state.

All implementations are required to support the XMLConstants.FEATURE_SECURE_PROCESSING feature. When the feature is:

  • true: the implementation will limit XML processing to conform to implementation limits and behave in a secure fashion as defined by the implementation. Examples include resolving user defined style sheets and functions. If XML processing is limited for security reasons, it will be reported via a call to the registered ErrorListener.fatalError(TransformerException exception). See setErrorListener(ErrorListener listener).
  • false: the implementation will processing XML according to the XML specifications without regard to possible implementation limits.

Parameters:
name - Feature name.
value - Is feature state true or false.
Throws:
TransformerConfigurationException - if this TransformerFactory or the Transformers or Templates it creates cannot support this feature.
NullPointerException - If the name parameter is null.

getFeature

public abstract boolean getFeature(String name)
Look up the value of a feature.

Feature names are fully qualified URIs. Implementations may define their own features. false is returned if this TransformerFactory or the Transformers or Templates it creates cannot support the feature. It is possible for an TransformerFactory to expose a feature value but be unable to change its state.

Parameters:
name - Feature name.
Returns:
The current state of the feature, true or false.
Throws:
NullPointerException - If the name parameter is null.

setAttribute

public abstract void setAttribute(String name,
                                  Object value)
Allows the user to set specific attributes on the underlying implementation. An attribute in this context is defined to be an option that the implementation provides. An IllegalArgumentException is thrown if the underlying implementation doesn't recognize the attribute.

Parameters:
name - The name of the attribute.
value - The value of the attribute.
Throws:
IllegalArgumentException - When implementation does not recognize the attribute.

getAttribute

public abstract Object getAttribute(String name)
Allows the user to retrieve specific attributes on the underlying implementation. An IllegalArgumentException is thrown if the underlying implementation doesn't recognize the attribute.

Parameters:
name - The name of the attribute.
Returns:
value The value of the attribute.
Throws:
IllegalArgumentException - When implementation does not recognize the attribute.

setErrorListener

public abstract void setErrorListener(ErrorListener listener)
Set the error event listener for the TransformerFactory, which is used for the processing of transformation instructions, and not for the transformation itself. An IllegalArgumentException is thrown if the ErrorListener listener is null.

Parameters:
listener - The new error listener.
Throws:
IllegalArgumentException - When listener is null

getErrorListener

public abstract ErrorListener getErrorListener()
Get the error event handler for the TransformerFactory.

Returns:
The current error handler, which should never be null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TransformerFactoryConfigurationError

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform
Class TransformerFactoryConfigurationError

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Error
            extended by  javax.xml.transform.TransformerFactoryConfigurationError
All Implemented Interfaces:
Serializable
public class TransformerFactoryConfigurationError
extends Error

Thrown when a problem with configuration with the Transformer Factories exists. This error will typically be thrown when the class of a transformation factory specified in the system properties cannot be found or instantiated.

See Also:
Serialized Form

Constructor Summary
TransformerFactoryConfigurationError()
Create a new TransformerFactoryConfigurationError with no detail mesage.
TransformerFactoryConfigurationError(Exception e)
Create a new TransformerFactoryConfigurationError with a given Exception base cause of the error.
TransformerFactoryConfigurationError(Exception e, String msg)
Create a new TransformerFactoryConfigurationError with the given Exception base cause and detail message.
TransformerFactoryConfigurationError(String msg)
Create a new TransformerFactoryConfigurationError with the String specified as an error message.
Method Summary
Exception | getException() Return the actual exception (if any) that caused this exception to be raised.
String | getMessage() Return the message (if any) for this error .
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TransformerFactoryConfigurationError

public TransformerFactoryConfigurationError()
Create a new TransformerFactoryConfigurationError with no detail mesage.

TransformerFactoryConfigurationError

public TransformerFactoryConfigurationError(String msg)
Create a new TransformerFactoryConfigurationError with the String specified as an error message.

Parameters:
msg - The error message for the exception.

TransformerFactoryConfigurationError

public TransformerFactoryConfigurationError(Exception e)
Create a new TransformerFactoryConfigurationError with a given Exception base cause of the error.

Parameters:
e - The exception to be encapsulated in a TransformerFactoryConfigurationError.

TransformerFactoryConfigurationError

public TransformerFactoryConfigurationError(Exception e,
                                            String msg)
Create a new TransformerFactoryConfigurationError with the given Exception base cause and detail message.

Parameters:
e - The exception to be encapsulated in a TransformerFactoryConfigurationError
msg - The detail message.
Method Detail

getMessage

public String getMessage()
Return the message (if any) for this error . If there is no message for the exception and there is an encapsulated exception then the message of that exception will be returned.

Overrides:
getMessage in class Throwable
Returns:
The error message.

getException

public Exception getException()
Return the actual exception (if any) that caused this exception to be raised.

Returns:
The encapsulated exception, or null if there is none.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


URIResolver

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.transform
Interface URIResolver

public interface URIResolver

An object that implements this interface that can be called by the processor to turn a URI used in document(), xsl:import, or xsl:include into a Source object.

Method Summary
 Source resolve(String href, String base)
Called by the processor when it encounters an xsl:include, xsl:import, or document() function.

Method Detail

resolve

Source resolve(String href,
               String base)
               throws TransformerException
Called by the processor when it encounters an xsl:include, xsl:import, or document() function.

Parameters:
href - An href attribute, which may be relative or absolute.
base - The base URI against which the first argument will be made absolute if the absolute URI is required.
Returns:
A Source object, or null if the href cannot be resolved, and the processor should try to resolve the URI itself.
Throws:
TransformerException - if an error occurs when trying to resolve the URI.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


validation

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.validation

This package provides an API for validation of XML documents.

See:
Description

Class Summary
Schema | Immutable in-memory representation of grammar.
SchemaFactory | Factory that creates Schema objects. Entry-point to the validation API.
SchemaFactoryLoader | Factory that creates SchemaFactory.
TypeInfoProvider | This class provides access to the type information determined by ValidatorHandler.
Validator | A processor that checks an XML document against Schema.
ValidatorHandler | Streaming validator that works on SAX stream.

Package javax.xml.validation Description

This package provides an API for validation of XML documents. Validation is the process of verifying that an XML document is an instance of a specified XML schema. An XML schema defines the content model (also called a grammar or vocabulary) that its instance documents will represent.

There are a number of popular technologies available for creating an XML schema. Some of the most popular include:

  • Document Type Definition (DTD) - XML's built-in schema language.
  • W3C XML Schema (WXS) - an object-oriented XML schema language. WXS also provides a type system for constraining the character data of an XML document. WXS is maintained by the World Wide Web Consortium (W3C) and is a W3C Recommendation (that is, a ratified W3C standard specification).
  • RELAX NG (RNG) - a pattern-based, user-friendly XML schema language. RNG schemas may also use types to constrain XML character data. RNG is maintained by the Organization for the Advancement of Structured Information Standards (OASIS) and is both an OASIS and an ISO (International Organization for Standardization) standard.
  • Schematron - a rules-based XML schema language. Whereas DTD, WXS, and RNG are designed to express the structure of a content model, Schematron is designed to enforce individual rules that are difficult or impossible to express with other schema languages. Schematron is intended to supplement a schema written in structural schema language such as the aforementioned. Schematron is in the process of becoming an ISO standard.

Previous versions of JAXP supported validation as a feature of an XML parser, represented by either a SAXParser or DocumentBuilder instance.

The JAXP validation API decouples the validation of an instance document from the parsing of an XML document. This is advantageous for several reasons, some of which are:

  • Support for additional schema langauges. As of JDK 1.5, the two most popular JAXP parser implementations, Crimson and Xerces, only support a subset of the available XML schema languages. The Validation API provides a standard mechanism through which applications may take of advantage of specialization validation libraries which support additional schema languages.
  • Easy runtime coupling of an XML instance and schema. Specifying the location of a schema to use for validation with JAXP parsers can be confusing. The Validation API makes this process simple (see example below).

Usage example. The following example demonstrates validating an XML document with the Validation API (for readability, some exception handling is not shown):

    // parse an XML document into a DOM tree
    DocumentBuilder parser = DocumentBuilderFactory.newInstance().newDocumentBuilder();
    Document document = parser.parse(new File("instance.xml"));

    // create a SchemaFactory capable of understanding WXS schemas
    SchemaFactory factory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);

    // load a WXS schema, represented by a Schema instance
    Source schemaFile = new StreamSource(new File("mySchema.xsd"));
    Schema schema = factory.newSchema(schemaFile);

    // create a Validator instance, which can be used to validate an instance document
    Validator validator = schema.newValidator();

    // validate the DOM tree
    try {
        validator.validate(new DOMSource(document));
    } catch (SAXException e) {
        // instance document is invalid!
    }

The JAXP parsing API has been integrated with the Validation API. Applications may create a Schema with the validation API and associate it with a DocumentBuilderFactory or a SAXParserFactory instance by using the DocumentBuilderFactory.setSchema(Schema) and SAXParserFactory.setSchema(Schema) methods. You should not both set a schema and call setValidating(true) on a parser factory. The former technique will cause parsers to use the new validation API; the latter will cause parsers to use their own internal validation facilities. Turning on both of these options simultaneously will cause either redundant behavior or error conditions.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.validation Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.validation

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.validation.Schema
    • javax.xml.validation.SchemaFactory
    • javax.xml.validation.SchemaFactoryLoader
    • javax.xml.validation.TypeInfoProvider
    • javax.xml.validation.Validator
    • javax.xml.validation.ValidatorHandler (implements org.xml.sax.ContentHandler)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.validation

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.validation

Packages that use javax.xml.validation
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.parsers | Provides classes allowing the processing of XML documents.
javax.xml.validation | This package provides an API for validation of XML documents.

Classes in javax.xml.validation used by javax.xml.bind
Schema
Immutable in-memory representation of grammar.

Classes in javax.xml.validation used by javax.xml.bind.helpers
Schema
Immutable in-memory representation of grammar.

Classes in javax.xml.validation used by javax.xml.parsers
Schema
Immutable in-memory representation of grammar.

Classes in javax.xml.validation used by javax.xml.validation
Schema
Immutable in-memory representation of grammar.
SchemaFactory
Factory that creates Schema objects. Entry-point to the validation API.
TypeInfoProvider
This class provides access to the type information determined by ValidatorHandler.
Validator
A processor that checks an XML document against Schema.
ValidatorHandler
Streaming validator that works on SAX stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.validation.Schema

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.validation.Schema

Packages that use Schema
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.parsers | Provides classes allowing the processing of XML documents.
javax.xml.validation | This package provides an API for validation of XML documents.

Uses of Schema in javax.xml.bind

Methods in javax.xml.bind that return Schema
 Schema Marshaller.getSchema()
Get the JAXP 1.3 Schema object being used to perform marshal-time validation.
 Schema Unmarshaller.getSchema()
Get the JAXP 1.3 Schema object being used to perform unmarshal-time validation.
abstract  Schema Binder.getSchema()
Gets the last Schema object (including null) set by the Binder.setSchema(Schema) method.

Methods in javax.xml.bind with parameters of type Schema
void | Marshaller.setSchema(Schema schema) Specify the JAXP 1.3 Schema object that should be used to validate subsequent marshal operations against.
void | Unmarshaller.setSchema(Schema schema) Specify the JAXP 1.3 Schema object that should be used to validate subsequent unmarshal operations against.
abstract void | Binder.setSchema(Schema schema) Specifies whether marshal, unmarshal and update methods performs validation on their XML content.

Uses of Schema in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers that return Schema
Schema | AbstractUnmarshallerImpl.getSchema()
Schema | AbstractMarshallerImpl.getSchema()

Methods in javax.xml.bind.helpers with parameters of type Schema
void | AbstractUnmarshallerImpl.setSchema(Schema schema)
void | AbstractMarshallerImpl.setSchema(Schema schema)

Uses of Schema in javax.xml.parsers

Methods in javax.xml.parsers that return Schema
 Schema SAXParser.getSchema()
Get a reference to the the Schema being used by the XML processor.
 Schema SAXParserFactory.getSchema()
Gets the Schema object specified through the SAXParserFactory.setSchema(Schema schema) method.
 Schema DocumentBuilder.getSchema()
Get a reference to the the Schema being used by the XML processor.
 Schema DocumentBuilderFactory.getSchema()
Gets the Schema object specified through the DocumentBuilderFactory.setSchema(Schema schema) method.

Methods in javax.xml.parsers with parameters of type Schema
void | SAXParserFactory.setSchema(Schema schema) Set the Schema to be used by parsers created from this factory.
void | DocumentBuilderFactory.setSchema(Schema schema) Set the Schema to be used by parsers created from this factory.

Uses of Schema in javax.xml.validation

Methods in javax.xml.validation that return Schema
abstract Schema | SchemaFactory.newSchema() Creates a special Schema object.
Schema | SchemaFactory.newSchema(File schema) Parses the specified File as a schema and returns it as a Schema.
Schema | SchemaFactory.newSchema(Source schema) Parses the specified source as a schema and returns it as a schema.
abstract Schema | SchemaFactory.newSchema(Source[] schemas) Parses the specified source(s) as a schema and returns it as a schema.
Schema | SchemaFactory.newSchema(URL schema) Parses the specified URL as a schema and returns it as a Schema.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.validation.SchemaFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.validation.SchemaFactory

Packages that use SchemaFactory
javax.xml.validation This package provides an API for validation of XML documents.

Uses of SchemaFactory in javax.xml.validation

Methods in javax.xml.validation that return SchemaFactory
abstract SchemaFactory | SchemaFactoryLoader.newFactory(String schemaLanguage) Creates a new SchemaFactory object for the specified schema language.
static SchemaFactory | SchemaFactory.newInstance(String schemaLanguage) Lookup an implementation of the SchemaFactory that supports the specified schema language and return it.
static SchemaFactory | SchemaFactory.newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader) Obtain a new instance of a SchemaFactory from class name.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.validation.SchemaFactoryLoader

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.validation.SchemaFactoryLoader

No usage of javax.xml.validation.SchemaFactoryLoader

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.validation.TypeInfoProvider

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.validation.TypeInfoProvider

Packages that use TypeInfoProvider
javax.xml.validation This package provides an API for validation of XML documents.

Uses of TypeInfoProvider in javax.xml.validation

Methods in javax.xml.validation that return TypeInfoProvider
abstract  TypeInfoProvider ValidatorHandler.getTypeInfoProvider()
Obtains the TypeInfoProvider implementation of this ValidatorHandler.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.validation.Validator

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.validation.Validator

Packages that use Validator
javax.xml.validation This package provides an API for validation of XML documents.

Uses of Validator in javax.xml.validation

Methods in javax.xml.validation that return Validator
abstract  Validator Schema.newValidator()
Creates a new Validator for this Schema.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.validation.ValidatorHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.validation.ValidatorHandler

Packages that use ValidatorHandler
javax.xml.validation This package provides an API for validation of XML documents.

Uses of ValidatorHandler in javax.xml.validation

Methods in javax.xml.validation that return ValidatorHandler
abstract  ValidatorHandler Schema.newValidatorHandler()
Creates a new ValidatorHandler for this Schema.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Schema

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.validation
Class Schema

java.lang.Object
    extended by  javax.xml.validation.Schema

public abstract class Schema
extends Object

Immutable in-memory representation of grammar.

This object represents a set of constraints that can be checked/ enforced against an XML document.

A Schema object is thread safe and applications are encouraged to share it across many parsers in many threads.

A Schema object is immutable in the sense that it shouldn't change the set of constraints once it is created. In other words, if an application validates the same document twice against the same Schema, it must always produce the same result.

A Schema object is usually created from SchemaFactory.

Two kinds of validators can be created from a Schema object. One is Validator, which provides highly-level validation operations that cover typical use cases. The other is ValidatorHandler, which works on top of SAX for better modularity.

This specification does not refine the Object.equals(java.lang.Object) method. In other words, if you parse the same schema twice, you may still get !schemaA.equals(schemaB).

Since:
1.5
See Also:
XML Schema Part 1: Structures, Extensible Markup Language (XML) 1.1, Extensible Markup Language (XML) 1.0 (Second Edition)

Constructor Summary
protected Schema()
Constructor for the derived class.
Method Summary
abstract Validator | newValidator() Creates a new Validator for this Schema.
abstract ValidatorHandler | newValidatorHandler() Creates a new ValidatorHandler for this Schema.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Schema

protected Schema()
Constructor for the derived class.

The constructor does nothing.

Method Detail

newValidator

public abstract Validator newValidator()
Creates a new Validator for this Schema.

A validator enforces/checks the set of constraints this object represents.

Implementors should assure that the properties set on the SchemaFactory that created this Schema are also set on the Validator constructed.

Returns:
Always return a non-null valid object.

newValidatorHandler

public abstract ValidatorHandler newValidatorHandler()
Creates a new ValidatorHandler for this Schema.

Implementors should assure that the properties set on the SchemaFactory that created this Schema are also set on the ValidatorHandler constructed.

Returns:
Always return a non-null valid object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


SchemaFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.validation
Class SchemaFactory

java.lang.Object
    extended by  javax.xml.validation.SchemaFactory

public abstract class SchemaFactory
extends Object

Factory that creates Schema objects. Entry-point to the validation API.

SchemaFactory is a schema compiler. It reads external representations of schemas and prepares them for validation.

The SchemaFactory class is not thread-safe. In other words, it is the application's responsibility to ensure that at most one thread is using a SchemaFactory object at any given moment. Implementations are encouraged to mark methods as synchronized to protect themselves from broken clients.

SchemaFactory is not re-entrant. While one of the newSchema methods is being invoked, applications may not attempt to recursively invoke the newSchema method, even from the same thread.

Schema Language

This spec uses a namespace URI to designate a schema language. The following table shows the values defined by this specification.

To be compliant with the spec, the implementation is only required to support W3C XML Schema 1.0. However, if it chooses to support other schema languages listed here, it must conform to the relevant behaviors described in this spec.

Schema languages not listed here are expected to introduce their own URIs to represent themselves. The SchemaFactory class is capable of locating other implementations for other schema languages at run-time.

Note that because the XML DTD is strongly tied to the parsing process and has a significant effect on the parsing process, it is impossible to define the DTD validation as a process independent from parsing. For this reason, this specification does not define the semantics for the XML DTD. This doesn't prohibit implentors from implementing it in a way they see fit, but users are warned that any DTD validation implemented on this interface necessarily deviate from the XML DTD semantics as defined in the XML 1.0.
value | language
XMLConstants.W3C_XML_SCHEMA_NS_URI ("http://www.w3.org/2001/XMLSchema") | W3C XML Schema 1.0
XMLConstants.RELAXNG_NS_URI ("http://relaxng.org/ns/structure/1.0") | RELAX NG 1.0

Since:
1.5

Constructor Summary
protected SchemaFactory()
Constructor for derived classes.
Method Summary
abstract ErrorHandler | getErrorHandler() Gets the current ErrorHandler set to this SchemaFactory.
boolean | getFeature(String name) Look up the value of a feature flag.
Object | getProperty(String name) Look up the value of a property.
abstract LSResourceResolver | getResourceResolver() Gets the current LSResourceResolver set to this SchemaFactory.
abstract boolean | isSchemaLanguageSupported(String schemaLanguage) Is specified schema supported by this SchemaFactory?
static SchemaFactory | newInstance(String schemaLanguage) Lookup an implementation of the SchemaFactory that supports the specified schema language and return it.
static SchemaFactory | newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader) Obtain a new instance of a SchemaFactory from class name.
abstract Schema | newSchema() Creates a special Schema object.
Schema | newSchema(File schema) Parses the specified File as a schema and returns it as a Schema.
Schema | newSchema(Source schema) Parses the specified source as a schema and returns it as a schema.
abstract Schema | newSchema(Source[] schemas) Parses the specified source(s) as a schema and returns it as a schema.
Schema | newSchema(URL schema) Parses the specified URL as a schema and returns it as a Schema.
abstract void | setErrorHandler(ErrorHandler errorHandler) Sets the ErrorHandler to receive errors encountered during the newSchema method invocation.
void | setFeature(String name, boolean value) Set a feature for this SchemaFactory, Schemas created by this factory, and by extension, Validators and ValidatorHandlers created by those Schemas.
void | setProperty(String name, Object object) Set the value of a property.
abstract void | setResourceResolver(LSResourceResolver resourceResolver) Sets the LSResourceResolver to customize resource resolution when parsing schemas.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SchemaFactory

protected SchemaFactory()

Constructor for derived classes.

The constructor does nothing.

Derived classes must create SchemaFactory objects that have null ErrorHandler and null LSResourceResolver.

Method Detail

newInstance

public static final SchemaFactory newInstance(String schemaLanguage)

Lookup an implementation of the SchemaFactory that supports the specified schema language and return it.

To find a SchemaFactory object for a given schema language, this method looks the following places in the following order where "the class loader" refers to the context class loader:

  1. If the system property "javax.xml.validation.SchemaFactory:schemaLanguage" is present (where schemaLanguage is the parameter to this method), then its value is read as a class name. The method will try to create a new instance of this class by using the class loader, and returns it if it is successfully created.
  2. $java.home/lib/jaxp.properties is read and the value associated with the key being the system property above is looked for. If present, the value is processed just like above.

  3. The class loader is asked for service provider provider-configuration files matching javax.xml.validation.SchemaFactory in the resource directory META-INF/services. See the JAR File Specification for file format and parsing rules. Each potential service provider is required to implement the method:

            isSchemaLanguageSupported(String schemaLanguage)
    The first service provider found in class loader order that supports the specified schema language is returned.
  4. Platform default SchemaFactory is located in a implementation specific way. There must be a platform default SchemaFactory for W3C XML Schema.

If everything fails, IllegalArgumentException will be thrown.

Tip for Trouble-shooting:

See Properties.load(java.io.InputStream) for exactly how a property file is parsed. In particular, colons ':' need to be escaped in a property file, so make sure schema language URIs are properly escaped in it. For example:

 http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory

Parameters:
schemaLanguage - Specifies the schema language which the returned SchemaFactory will understand. See the list of available schema languages for the possible values.
Returns:
New instance of a SchemaFactory
Throws:
IllegalArgumentException - If no implementation of the schema language is available.
NullPointerException - If the schemaLanguage parameter is null.
See Also:
newInstance(String schemaLanguage, String factoryClassName, ClassLoader classLoader)

newInstance

public static SchemaFactory newInstance(String schemaLanguage,
                                        String factoryClassName,
                                        ClassLoader classLoader)

Obtain a new instance of a SchemaFactory from class name. SchemaFactory is returned if specified factory class name supports the specified schema language. This function is useful when there are multiple providers in the classpath. It gives more control to the application as it can specify which provider should be loaded.

Tip for Trouble-shooting

Setting the jaxp.debug system property will cause this method to print a lot of debug messages to System.err about what it is doing and where it is looking at.

If you have problems try:

 java -Djaxp.debug=1 YourProgram ....

Parameters:
schemaLanguage - Specifies the schema language which the returned SchemaFactory will understand. See the list of available schema languages for the possible values.
factoryClassName - fully qualified factory class name that provides implementation of javax.xml.validation.SchemaFactory.
classLoader - ClassLoader used to load the factory class. If null current Thread's context classLoader is used to load the factory class.
Returns:
New instance of a SchemaFactory
Throws:
IllegalArgumentException - if factoryClassName is null, or the factory class cannot be loaded, instantiated or doesn't support the schema language specified in schemLanguage parameter.
NullPointerException - If the schemaLanguage parameter is null.
Since:
1.6
See Also:
newInstance(String schemaLanguage)

isSchemaLanguageSupported

public abstract boolean isSchemaLanguageSupported(String schemaLanguage)

Is specified schema supported by this SchemaFactory?

Parameters:
schemaLanguage - Specifies the schema language which the returned SchemaFactory will understand. schemaLanguage must specify a valid schema language.
Returns:
true if SchemaFactory supports schemaLanguage, else false.
Throws:
NullPointerException - If schemaLanguage is null.
IllegalArgumentException - If schemaLanguage.length() == 0 or schemaLanguage does not specify a valid schema language.

getFeature

public boolean getFeature(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException
Look up the value of a feature flag.

The feature name is any fully-qualified URI. It is possible for a SchemaFactory to recognize a feature name but temporarily be unable to return its value.

Implementors are free (and encouraged) to invent their own features, using names built on their own URIs.

Parameters:
name - The feature name, which is a non-null fully-qualified URI.
Returns:
The current value of the feature (true or false).
Throws:
SAXNotRecognizedException - If the feature value can't be assigned or retrieved.
SAXNotSupportedException - When the SchemaFactory recognizes the feature name but cannot determine its value at this time.
NullPointerException - If name is null.
See Also:
setFeature(String, boolean)

setFeature

public void setFeature(String name,
                       boolean value)
                throws SAXNotRecognizedException,
                       SAXNotSupportedException

Set a feature for this SchemaFactory, Schemas created by this factory, and by extension, Validators and ValidatorHandlers created by those Schemas.

Implementors and developers should pay particular attention to how the special Schema object returned by newSchema() is processed. In some cases, for example, when the SchemaFactory and the class actually loading the schema come from different implementations, it may not be possible for SchemaFactory features to be inherited automatically. Developers should make sure that features, such as secure processing, are explicitly set in both places.

The feature name is any fully-qualified URI. It is possible for a SchemaFactory to expose a feature value but to be unable to change the current value.

All implementations are required to support the XMLConstants.FEATURE_SECURE_PROCESSING feature. When the feature is:

  • true: the implementation will limit XML processing to conform to implementation limits. Examples include enity expansion limits and XML Schema constructs that would consume large amounts of resources. If XML processing is limited for security reasons, it will be reported via a call to the registered ErrorHandler.fatalError(SAXParseException exception). See setErrorHandler(ErrorHandler errorHandler).
  • false: the implementation will processing XML according to the XML specifications without regard to possible implementation limits.

Parameters:
name - The feature name, which is a non-null fully-qualified URI.
value - The requested value of the feature (true or false).
Throws:
SAXNotRecognizedException - If the feature value can't be assigned or retrieved.
SAXNotSupportedException - When the SchemaFactory recognizes the feature name but cannot set the requested value.
NullPointerException - If name is null.
See Also:
getFeature(String)

setProperty

public void setProperty(String name,
                        Object object)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException
Set the value of a property.

The property name is any fully-qualified URI. It is possible for a SchemaFactory to recognize a property name but to be unable to change the current value.

SchemaFactorys are not required to recognize setting any specific property names.

Parameters:
name - The property name, which is a non-null fully-qualified URI.
object - The requested value for the property.
Throws:
SAXNotRecognizedException - If the property value can't be assigned or retrieved.
SAXNotSupportedException - When the SchemaFactory recognizes the property name but cannot set the requested value.
NullPointerException - If name is null.

getProperty

public Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException
Look up the value of a property.

The property name is any fully-qualified URI. It is possible for a SchemaFactory to recognize a property name but temporarily be unable to return its value.

SchemaFactorys are not required to recognize any specific property names.

Implementors are free (and encouraged) to invent their own properties, using names built on their own URIs.

Parameters:
name - The property name, which is a non-null fully-qualified URI.
Returns:
The current value of the property.
Throws:
SAXNotRecognizedException - If the property value can't be assigned or retrieved.
SAXNotSupportedException - When the XMLReader recognizes the property name but cannot determine its value at this time.
NullPointerException - If name is null.
See Also:
setProperty(String, Object)

setErrorHandler

public abstract void setErrorHandler(ErrorHandler errorHandler)
Sets the ErrorHandler to receive errors encountered during the newSchema method invocation.

Error handler can be used to customize the error handling process during schema parsing. When an ErrorHandler is set, errors found during the parsing of schemas will be first sent to the ErrorHandler.

The error handler can abort the parsing of a schema immediately by throwing SAXException from the handler. Or for example it can print an error to the screen and try to continue the processing by returning normally from the ErrorHandler

If any Throwable (or instances of its derived classes) is thrown from an ErrorHandler, the caller of the newSchema method will be thrown the same Throwable object.

SchemaFactory is not allowed to throw SAXException without first reporting it to ErrorHandler.

Applications can call this method even during a Schema is being parsed.

When the ErrorHandler is null, the implementation will behave as if the following ErrorHandler is set:

 class DraconianErrorHandler implements ErrorHandler {
     public void fatalError( SAXParseException e ) throws SAXException {
         throw e;
     }
     public void error( SAXParseException e ) throws SAXException {
         throw e;
     }
     public void warning( SAXParseException e ) throws SAXException {
         // noop
     }
 }

When a new SchemaFactory object is created, initially this field is set to null. This field will NOT be inherited to Schemas, Validators, or ValidatorHandlers that are created from this SchemaFactory.

Parameters:
errorHandler - A new error handler to be set. This parameter can be null.

getErrorHandler

public abstract ErrorHandler getErrorHandler()
Gets the current ErrorHandler set to this SchemaFactory.

Returns:
This method returns the object that was last set through the setErrorHandler(ErrorHandler) method, or null if that method has never been called since this SchemaFactory has created.
See Also:
setErrorHandler(ErrorHandler)

setResourceResolver

public abstract void setResourceResolver(LSResourceResolver resourceResolver)
Sets the LSResourceResolver to customize resource resolution when parsing schemas.

SchemaFactory uses a LSResourceResolver when it needs to locate external resources while parsing schemas, although exactly what constitutes "locating external resources" is up to each schema language. For example, for W3C XML Schema, this includes files <include>d or <import>ed, and DTD referenced from schema files, etc.

Applications can call this method even during a Schema is being parsed.

When the LSResourceResolver is null, the implementation will behave as if the following LSResourceResolver is set:

 class DumbDOMResourceResolver implements LSResourceResolver {
     public LSInput resolveResource(
         String publicId, String systemId, String baseURI) {

         return null; // always return null
     }
 }

If a LSResourceResolver throws a RuntimeException (or instances of its derived classes), then the SchemaFactory will abort the parsing and the caller of the newSchema method will receive the same RuntimeException.

When a new SchemaFactory object is created, initially this field is set to null. This field will NOT be inherited to Schemas, Validators, or ValidatorHandlers that are created from this SchemaFactory.

Parameters:
resourceResolver - A new resource resolver to be set. This parameter can be null.

getResourceResolver

public abstract LSResourceResolver getResourceResolver()
Gets the current LSResourceResolver set to this SchemaFactory.

Returns:
This method returns the object that was last set through the setResourceResolver(LSResourceResolver) method, or null if that method has never been called since this SchemaFactory has created.
See Also:
setErrorHandler(ErrorHandler)

newSchema

public Schema newSchema(Source schema)
                 throws SAXException

Parses the specified source as a schema and returns it as a schema.

This is a convenience method for newSchema(Source[] schemas).

Parameters:
schema - Source that represents a schema.
Returns:
New Schema from parsing schema.
Throws:
SAXException - If a SAX error occurs during parsing.
NullPointerException - if schema is null.

newSchema

public Schema newSchema(File schema)
                 throws SAXException

Parses the specified File as a schema and returns it as a Schema.

This is a convenience method for newSchema(Source schema).

Parameters:
schema - File that represents a schema.
Returns:
New Schema from parsing schema.
Throws:
SAXException - If a SAX error occurs during parsing.
NullPointerException - if schema is null.

newSchema

public Schema newSchema(URL schema)
                 throws SAXException

Parses the specified URL as a schema and returns it as a Schema.

This is a convenience method for newSchema(Source schema).

Parameters:
schema - URL that represents a schema.
Returns:
New Schema from parsing schema.
Throws:
SAXException - If a SAX error occurs during parsing.
NullPointerException - if schema is null.

newSchema

public abstract Schema newSchema(Source[] schemas)
                          throws SAXException
Parses the specified source(s) as a schema and returns it as a schema.

The callee will read all the Sources and combine them into a single schema. The exact semantics of the combination depends on the schema language that this SchemaFactory object is created for.

When an ErrorHandler is set, the callee will report all the errors found in sources to the handler. If the handler throws an exception, it will abort the schema compilation and the same exception will be thrown from this method. Also, after an error is reported to a handler, the callee is allowed to abort the further processing by throwing it. If an error handler is not set, the callee will throw the first error it finds in the sources.

W3C XML Schema 1.0

The resulting schema contains components from the specified sources. The same result would be achieved if all these sources were imported, using appropriate values for schemaLocation and namespace, into a single schema document with a different targetNamespace and no components of its own, if the import elements were given in the same order as the sources. Section 4.2.3 of the XML Schema recommendation describes the options processors have in this regard. While a processor should be consistent in its treatment of JAXP schema sources and XML Schema imports, the behaviour between JAXP-compliant parsers may vary; in particular, parsers may choose to ignore all but the first <import> for a given namespace, regardless of information provided in schemaLocation.

If the parsed set of schemas includes error(s) as specified in the section 5.1 of the XML Schema spec, then the error must be reported to the ErrorHandler.

RELAX NG

For RELAX NG, this method must throw UnsupportedOperationException if schemas.length!=1.

Parameters:
schemas - inputs to be parsed. SchemaFactory is required to recognize SAXSource, StreamSource, StAXSource, and DOMSource. Input schemas must be XML documents or XML elements and must not be null. For backwards compatibility, the results of passing anything other than a document or element are implementation-dependent. Implementations must either recognize and process the input or thrown an IllegalArgumentException.
Returns:
Always return a non-null valid Schema object. Note that when an error has been reported, there is no guarantee that the returned Schema object is meaningful.
Throws:
SAXException - If an error is found during processing the specified inputs. When an ErrorHandler is set, errors are reported to there first. See setErrorHandler(ErrorHandler).
NullPointerException - If the schemas parameter itself is null or any item in the array is null.
IllegalArgumentException - If any item in the array is not recognized by this method.
UnsupportedOperationException - If the schema language doesn't support this operation.

newSchema

public abstract Schema newSchema()
                          throws SAXException
Creates a special Schema object.

The exact semantics of the returned Schema object depend on the schema language for which this SchemaFactory is created.

Also, implementations are allowed to use implementation-specific property/feature to alter the semantics of this method.

Implementors and developers should pay particular attention to how the features set on this SchemaFactory are processed by this special Schema. In some cases, for example, when the SchemaFactory and the class actually loading the schema come from different implementations, it may not be possible for SchemaFactory features to be inherited automatically. Developers should make sure that features, such as secure processing, are explicitly set in both places.

W3C XML Schema 1.0

For XML Schema, this method creates a Schema object that performs validation by using location hints specified in documents.

The returned Schema object assumes that if documents refer to the same URL in the schema location hints, they will always resolve to the same schema document. This asusmption allows implementations to reuse parsed results of schema documents so that multiple validations against the same schema will run faster.

Note that the use of schema location hints introduces a vulnerability to denial-of-service attacks.

RELAX NG

RELAX NG does not support this operation.

Returns:
Always return non-null valid Schema object.
Throws:
UnsupportedOperationException - If this operation is not supported by the callee.
SAXException - If this operation is supported but failed for some reason.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SchemaFactoryLoader

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.validation
Class SchemaFactoryLoader

java.lang.Object
    extended by  javax.xml.validation.SchemaFactoryLoader

public abstract class SchemaFactoryLoader
extends Object

Factory that creates SchemaFactory.

DO NOT USE THIS CLASS

This class was introduced as a part of an early proposal during the JSR-206 standardization process. The proposal was eventually abandoned but this class accidentally remained in the source tree, and made its way into the final version.

This class does not participate in any JAXP 1.3 or JAXP 1.4 processing. It must not be used by users or JAXP implementations.

Since:
1.5

Constructor Summary
protected SchemaFactoryLoader()
A do-nothing constructor.
Method Summary
abstract  SchemaFactory newFactory(String schemaLanguage)
Creates a new SchemaFactory object for the specified schema language.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SchemaFactoryLoader

protected SchemaFactoryLoader()
A do-nothing constructor.

Method Detail

newFactory

public abstract SchemaFactory newFactory(String schemaLanguage)
Creates a new SchemaFactory object for the specified schema language.

Parameters:
schemaLanguage - See the list of available schema languages.
Returns:
null if the callee fails to create one.
Throws:
NullPointerException - If the schemaLanguage parameter is null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TypeInfoProvider

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.validation
Class TypeInfoProvider

java.lang.Object
    extended by  javax.xml.validation.TypeInfoProvider

public abstract class TypeInfoProvider
extends Object

This class provides access to the type information determined by ValidatorHandler.

Some schema languages, such as W3C XML Schema, encourages a validator to report the "type" it assigns to each attribute/element. Those applications who wish to access this type information can invoke methods defined on this "interface" to access such type information.

Implementation of this "interface" can be obtained through the ValidatorHandler.getTypeInfoProvider() method.

Since:
1.5
See Also:
TypeInfo

Constructor Summary
protected TypeInfoProvider()
Constructor for the derived class.
Method Summary
abstract TypeInfo | getAttributeTypeInfo(int index) Returns the immutable TypeInfo object for the specified attribute of the current element.
abstract TypeInfo | getElementTypeInfo() Returns the immutable TypeInfo object for the current element.
abstract boolean | isIdAttribute(int index) Returns true if the specified attribute is determined to be ID.
abstract boolean | isSpecified(int index) Returns false if the attribute was added by the validator.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TypeInfoProvider

protected TypeInfoProvider()
Constructor for the derived class.

The constructor does nothing.

Method Detail

getElementTypeInfo

public abstract TypeInfo getElementTypeInfo()

Returns the immutable TypeInfo object for the current element.

The method may only be called by the startElement event or the endElement event of the ContentHandler that the application sets to the ValidatorHandler.

When W3C XML Schema validation is being performed, in the case where an element has a union type, the TypeInfo returned by a call to getElementTypeInfo() from the startElement event will be the union type. The TypeInfo returned by a call from the endElement event will be the actual member type used to validate the element.

Returns:
An immutable TypeInfo object that represents the type of the current element. Note that the caller can keep references to the obtained TypeInfo longer than the callback scope. Otherwise, this method returns null if the validator is unable to determine the type of the current element for some reason (for example, if the validator is recovering from an earlier error.)
Throws:
IllegalStateException - If this method is called from other ContentHandler methods.

getAttributeTypeInfo

public abstract TypeInfo getAttributeTypeInfo(int index)
Returns the immutable TypeInfo object for the specified attribute of the current element.

The method may only be called by the startElement event of the ContentHandler that the application sets to the ValidatorHandler.

Parameters:
index - The index of the attribute. The same index for the Attributes object passed to the startElement callback.
Returns:
An immutable TypeInfo object that represents the type of the specified attribute. Note that the caller can keep references to the obtained TypeInfo longer than the callback scope. Otherwise, this method returns null if the validator is unable to determine the type.
Throws:
IndexOutOfBoundsException - If the index is invalid.
IllegalStateException - If this method is called from other ContentHandler methods.

isIdAttribute

public abstract boolean isIdAttribute(int index)
Returns true if the specified attribute is determined to be ID.

Exacly how an attribute is "determined to be ID" is up to the schema language. In case of W3C XML Schema, this means that the actual type of the attribute is the built-in ID type or its derived type.

A DocumentBuilder uses this information to properly implement Attr.isId().

The method may only be called by the startElement event of the ContentHandler that the application sets to the ValidatorHandler.

Parameters:
index - The index of the attribute. The same index for the Attributes object passed to the startElement callback.
Returns:
true if the type of the specified attribute is ID.
Throws:
IndexOutOfBoundsException - If the index is invalid.
IllegalStateException - If this method is called from other ContentHandler methods.

isSpecified

public abstract boolean isSpecified(int index)
Returns false if the attribute was added by the validator.

This method provides information necessary for a DocumentBuilder to determine what the DOM tree should return from the Attr.getSpecified() method.

The method may only be called by the startElement event of the ContentHandler that the application sets to the ValidatorHandler.

A general guideline for validators is to return true if the attribute was originally present in the pipeline, and false if it was added by the validator.

Parameters:
index - The index of the attribute. The same index for the Attributes object passed to the startElement callback.
Returns:
true if the attribute was present before the validator processes input. false if the attribute was added by the validator.
Throws:
IndexOutOfBoundsException - If the index is invalid.
IllegalStateException - If this method is called from other ContentHandler methods.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Validator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.validation
Class Validator

java.lang.Object
    extended by  javax.xml.validation.Validator

public abstract class Validator
extends Object

A processor that checks an XML document against Schema.

A validator object is not thread-safe and not reentrant. In other words, it is the application's responsibility to make sure that one Validator object is not used from more than one thread at any given time, and while the validate method is invoked, applications may not recursively call the validate method.

Since:
1.5

Constructor Summary
protected Validator()
Constructor for derived classes.
Method Summary
abstract ErrorHandler | getErrorHandler() Gets the current ErrorHandler set to this Validator.
boolean | getFeature(String name) Look up the value of a feature flag.
Object | getProperty(String name) Look up the value of a property.
abstract LSResourceResolver | getResourceResolver() Gets the current LSResourceResolver set to this Validator.
abstract void | reset() Reset this Validator to its original configuration.
abstract void | setErrorHandler(ErrorHandler errorHandler) Sets the ErrorHandler to receive errors encountered during the validate method invocation.
void | setFeature(String name, boolean value) Set the value of a feature flag.
void | setProperty(String name, Object object) Set the value of a property.
abstract void | setResourceResolver(LSResourceResolver resourceResolver) Sets the LSResourceResolver to customize resource resolution while in a validation episode.
void | validate(Source source) Validates the specified input.
abstract void | validate(Source source, Result result) Validates the specified input and send the augmented validation result to the specified output.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Validator

protected Validator()
Constructor for derived classes.

The constructor does nothing.

Derived classes must create Validator objects that have null ErrorHandler and null LSResourceResolver.

Method Detail

reset

public abstract void reset()

Reset this Validator to its original configuration.

Validator is reset to the same state as when it was created with Schema.newValidator(). reset() is designed to allow the reuse of existing Validators thus saving resources associated with the creation of new Validators.

The reset Validator is not guaranteed to have the same LSResourceResolver or ErrorHandler Objects, e.g. Object.equals(Object obj). It is guaranteed to have a functionally equal LSResourceResolver and ErrorHandler.

validate

public void validate(Source source)
              throws SAXException,
                     IOException
Validates the specified input.

This is just a convenience method for validate(Source source, Result result) with result of null.

Parameters:
source - XML to be validated. Must be an XML document or XML element and must not be null. For backwards compatibility, the results of attempting to validate anything other than a document or element are implementation-dependent. Implementations must either recognize and process the input or throw an IllegalArgumentException.
Throws:
IllegalArgumentException - If the Source is an XML artifact that the implementation cannot validate (for example, a processing instruction).
SAXException - If the ErrorHandler throws a SAXException or if a fatal error is found and the ErrorHandler returns normally.
IOException - If the validator is processing a SAXSource and the underlying XMLReader throws an IOException.
NullPointerException - If source is null.
See Also:
validate(Source source, Result result)

validate

public abstract void validate(Source source,
                              Result result)
                       throws SAXException,
                              IOException

Validates the specified input and send the augmented validation result to the specified output.

This method places the following restrictions on the types of the Source/Result accepted.

Source / Result Accepted
StreamSource SAXSource DOMSource StAXSource
null | OK | OK | OK | OK
StreamResult | OK | IllegalArgumentException | IllegalArgumentException | IllegalArgumentException
SAXResult | IllegalArgumentException | OK | IllegalArgumentException | IllegalArgumentException
DOMResult | IllegalArgumentException | IllegalArgumentException | OK | IllegalArgumentException
StAXResult | IllegalArgumentException | IllegalArgumentException | IllegalArgumentException | OK

To validate one Source into another kind of Result, use the identity transformer (see TransformerFactory.newTransformer()).

Errors found during the validation is sent to the specified ErrorHandler.

If a document is valid, or if a document contains some errors but none of them were fatal and the ErrorHandler didn't throw any exception, then the method returns normally.

Parameters:
source - XML to be validated. Must be an XML document or XML element and must not be null. For backwards compatibility, the results of attempting to validate anything other than a document or element are implementation-dependent. Implementations must either recognize and process the input or throw an IllegalArgumentException.
result - The Result object that receives (possibly augmented) XML. This parameter can be null if the caller is not interested in it. Note that when a DOMResult is used, a validator might just pass the same DOM node from DOMSource to DOMResult (in which case source.getNode()==result.getNode()), it might copy the entire DOM tree, or it might alter the node given by the source.
Throws:
IllegalArgumentException - If the Result type doesn't match the Source type of if the Source is an XML artifact that the implementation cannot validate (for example, a processing instruction).
SAXException - If the ErrorHandler throws a SAXException or if a fatal error is found and the ErrorHandler returns normally.
IOException - If the validator is processing a SAXSource and the underlying XMLReader throws an IOException.
NullPointerException - If the source parameter is null.
See Also:
validate(Source source)

setErrorHandler

public abstract void setErrorHandler(ErrorHandler errorHandler)
Sets the ErrorHandler to receive errors encountered during the validate method invocation.

Error handler can be used to customize the error handling process during a validation. When an ErrorHandler is set, errors found during the validation will be first sent to the ErrorHandler.

The error handler can abort further validation immediately by throwing SAXException from the handler. Or for example it can print an error to the screen and try to continue the validation by returning normally from the ErrorHandler

If any Throwable is thrown from an ErrorHandler, the caller of the validate method will be thrown the same Throwable object.

Validator is not allowed to throw SAXException without first reporting it to ErrorHandler.

When the ErrorHandler is null, the implementation will behave as if the following ErrorHandler is set:

 class DraconianErrorHandler implements ErrorHandler {
     public void fatalError( SAXParseException e ) throws SAXException {
         throw e;
     }
     public void error( SAXParseException e ) throws SAXException {
         throw e;
     }
     public void warning( SAXParseException e ) throws SAXException {
         // noop
     }
 }

When a new Validator object is created, initially this field is set to null.

Parameters:
errorHandler - A new error handler to be set. This parameter can be null.

getErrorHandler

public abstract ErrorHandler getErrorHandler()
Gets the current ErrorHandler set to this Validator.

Returns:
This method returns the object that was last set through the setErrorHandler(ErrorHandler) method, or null if that method has never been called since this Validator has created.
See Also:
setErrorHandler(ErrorHandler)

setResourceResolver

public abstract void setResourceResolver(LSResourceResolver resourceResolver)
Sets the LSResourceResolver to customize resource resolution while in a validation episode.

Validator uses a LSResourceResolver when it needs to locate external resources while a validation, although exactly what constitutes "locating external resources" is up to each schema language.

When the LSResourceResolver is null, the implementation will behave as if the following LSResourceResolver is set:

 class DumbLSResourceResolver implements LSResourceResolver {
     public LSInput resolveResource(
         String publicId, String systemId, String baseURI) {

         return null; // always return null
     }
 }

If a LSResourceResolver throws a RuntimeException (or instances of its derived classes), then the Validator will abort the parsing and the caller of the validate method will receive the same RuntimeException.

When a new Validator object is created, initially this field is set to null.

Parameters:
resourceResolver - A new resource resolver to be set. This parameter can be null.

getResourceResolver

public abstract LSResourceResolver getResourceResolver()
Gets the current LSResourceResolver set to this Validator.

Returns:
This method returns the object that was last set through the setResourceResolver(LSResourceResolver) method, or null if that method has never been called since this Validator has created.
See Also:
setErrorHandler(ErrorHandler)

getFeature

public boolean getFeature(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException
Look up the value of a feature flag.

The feature name is any fully-qualified URI. It is possible for a Validator to recognize a feature name but temporarily be unable to return its value. Some feature values may be available only in specific contexts, such as before, during, or after a validation.

Implementors are free (and encouraged) to invent their own features, using names built on their own URIs.

Parameters:
name - The feature name, which is a non-null fully-qualified URI.
Returns:
The current value of the feature (true or false).
Throws:
SAXNotRecognizedException - If the feature value can't be assigned or retrieved.
SAXNotSupportedException - When the Validator recognizes the feature name but cannot determine its value at this time.
NullPointerException - When the name parameter is null.
See Also:
setFeature(String, boolean)

setFeature

public void setFeature(String name,
                       boolean value)
                throws SAXNotRecognizedException,
                       SAXNotSupportedException
Set the value of a feature flag.

Feature can be used to control the way a Validator parses schemas, although Validators are not required to recognize any specific feature names.

The feature name is any fully-qualified URI. It is possible for a Validator to expose a feature value but to be unable to change the current value. Some feature values may be immutable or mutable only in specific contexts, such as before, during, or after a validation.

Parameters:
name - The feature name, which is a non-null fully-qualified URI.
value - The requested value of the feature (true or false).
Throws:
SAXNotRecognizedException - If the feature value can't be assigned or retrieved.
SAXNotSupportedException - When the Validator recognizes the feature name but cannot set the requested value.
NullPointerException - When the name parameter is null.
See Also:
getFeature(String)

setProperty

public void setProperty(String name,
                        Object object)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException
Set the value of a property.

The property name is any fully-qualified URI. It is possible for a Validator to recognize a property name but to be unable to change the current value. Some property values may be immutable or mutable only in specific contexts, such as before, during, or after a validation.

Validators are not required to recognize setting any specific property names.

Parameters:
name - The property name, which is a non-null fully-qualified URI.
object - The requested value for the property.
Throws:
SAXNotRecognizedException - If the property value can't be assigned or retrieved.
SAXNotSupportedException - When the Validator recognizes the property name but cannot set the requested value.
NullPointerException - When the name parameter is null.

getProperty

public Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException
Look up the value of a property.

The property name is any fully-qualified URI. It is possible for a Validator to recognize a property name but temporarily be unable to return its value. Some property values may be available only in specific contexts, such as before, during, or after a validation.

Validators are not required to recognize any specific property names.

Implementors are free (and encouraged) to invent their own properties, using names built on their own URIs.

Parameters:
name - The property name, which is a non-null fully-qualified URI.
Returns:
The current value of the property.
Throws:
SAXNotRecognizedException - If the property value can't be assigned or retrieved.
SAXNotSupportedException - When the XMLReader recognizes the property name but cannot determine its value at this time.
NullPointerException - When the name parameter is null.
See Also:
setProperty(String, Object)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ValidatorHandler

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.validation
Class ValidatorHandler

java.lang.Object
    extended by  javax.xml.validation.ValidatorHandler
All Implemented Interfaces:
ContentHandler
public abstract class ValidatorHandler
extends Object
implements ContentHandler

Streaming validator that works on SAX stream.

A ValidatorHandler object is not thread-safe and not reentrant. In other words, it is the application's responsibility to make sure that one ValidatorHandler object is not used from more than one thread at any given time.

ValidatorHandler checks if the SAX events follow the set of constraints described in the associated Schema, and additionally it may modify the SAX events (for example by adding default values, etc.)

ValidatorHandler extends from ContentHandler, but it refines the underlying ContentHandler in the following way:

  1. startElement/endElement events must receive non-null String for uri, localName, and qname, even though SAX allows some of them to be null. Similarly, the user-specified ContentHandler will receive non-null Strings for all three parameters.
  2. Applications must ensure that ValidatorHandler's ContentHandler.startPrefixMapping(String,String) and ContentHandler.endPrefixMapping(String) are invoked properly. Similarly, the user-specified ContentHandler will receive startPrefixMapping/endPrefixMapping events. If the ValidatorHandler introduces additional namespace bindings, the user-specified ContentHandler will receive additional startPrefixMapping/endPrefixMapping events.
  3. Attributes for the ContentHandler.startElement(String,String,String,Attributes) method may or may not include xmlns* attributes.

A ValidatorHandler is automatically reset every time the startDocument method is invoked.

Recognized Properties and Features

This spec defines the following feature that must be recognized by all ValidatorHandler implementations.

http://xml.org/sax/features/namespace-prefixes

This feature controls how a ValidatorHandler introduces namespace bindings that were not present in the original SAX event stream. When this feature is set to true, it must make sure that the user's ContentHandler will see the corresponding xmlns* attribute in the Attributes object of the ContentHandler.startElement(String,String,String,Attributes) callback. Otherwise, xmlns* attributes must not be added to Attributes that's passed to the user-specified ContentHandler.

(Note that regardless of this switch, namespace bindings are always notified to applications through ContentHandler.startPrefixMapping(String,String) and ContentHandler.endPrefixMapping(String) methods of the ContentHandler specified by the user.)

Note that this feature does NOT affect the way a ValidatorHandler receives SAX events. It merely changes the way it augments SAX events.

This feature is set to false by default.

Since:
1.5

Constructor Summary
protected ValidatorHandler()
Constructor for derived classes.
Method Summary
abstract ContentHandler | getContentHandler() Gets the ContentHandler which receives the augmented validation result.
abstract ErrorHandler | getErrorHandler() Gets the current ErrorHandler set to this ValidatorHandler.
boolean | getFeature(String name) Look up the value of a feature flag.
Object | getProperty(String name) Look up the value of a property.
abstract LSResourceResolver | getResourceResolver() Gets the current LSResourceResolver set to this ValidatorHandler.
abstract TypeInfoProvider | getTypeInfoProvider() Obtains the TypeInfoProvider implementation of this ValidatorHandler.
abstract void | setContentHandler(ContentHandler receiver) Sets the ContentHandler which receives the augmented validation result.
abstract void | setErrorHandler(ErrorHandler errorHandler) Sets the ErrorHandler to receive errors encountered during the validation.
void | setFeature(String name, boolean value) Set a feature for this ValidatorHandler.
void | setProperty(String name, Object object) Set the value of a property.
abstract void | setResourceResolver(LSResourceResolver resourceResolver) Sets the LSResourceResolver to customize resource resolution while in a validation episode.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.xml.sax.ContentHandler
characters, endDocument, endElement, endPrefixMapping, ignorableWhitespace, processingInstruction, setDocumentLocator, skippedEntity, startDocument, startElement, startPrefixMapping

Constructor Detail

ValidatorHandler

protected ValidatorHandler()

Constructor for derived classes.

The constructor does nothing.

Derived classes must create ValidatorHandler objects that have null ErrorHandler and null LSResourceResolver.

Method Detail

setContentHandler

public abstract void setContentHandler(ContentHandler receiver)
Sets the ContentHandler which receives the augmented validation result.

When a ContentHandler is specified, a ValidatorHandler will work as a filter and basically copy the incoming events to the specified ContentHandler.

In doing so, a ValidatorHandler may modify the events, for example by adding defaulted attributes.

A ValidatorHandler may buffer events to certain extent, but to allow ValidatorHandler to be used by a parser, the following requirement has to be met.

  1. When ContentHandler.startElement(String, String, String, Attributes), ContentHandler.endElement(String, String, String), ContentHandler.startDocument(), or ContentHandler.endDocument() are invoked on a ValidatorHandler, the same method on the user-specified ContentHandler must be invoked for the same event before the callback returns.
  2. ValidatorHandler may not introduce new elements that were not present in the input.
  3. ValidatorHandler may not remove attributes that were present in the input.

When a callback method on the specified ContentHandler throws an exception, the same exception object must be thrown from the ValidatorHandler. The ErrorHandler should not be notified of such an exception.

This method can be called even during a middle of a validation.

Parameters:
receiver - A ContentHandler or a null value.

getContentHandler

public abstract ContentHandler getContentHandler()
Gets the ContentHandler which receives the augmented validation result.

Returns:
This method returns the object that was last set through the getContentHandler() method, or null if that method has never been called since this ValidatorHandler has created.
See Also:
setContentHandler(ContentHandler)

setErrorHandler

public abstract void setErrorHandler(ErrorHandler errorHandler)
Sets the ErrorHandler to receive errors encountered during the validation.

Error handler can be used to customize the error handling process during a validation. When an ErrorHandler is set, errors found during the validation will be first sent to the ErrorHandler.

The error handler can abort further validation immediately by throwing SAXException from the handler. Or for example it can print an error to the screen and try to continue the validation by returning normally from the ErrorHandler

If any Throwable is thrown from an ErrorHandler, the same Throwable object will be thrown toward the root of the call stack.

ValidatorHandler is not allowed to throw SAXException without first reporting it to ErrorHandler.

When the ErrorHandler is null, the implementation will behave as if the following ErrorHandler is set:

 class DraconianErrorHandler implements ErrorHandler {
     public void fatalError( SAXParseException e ) throws SAXException {
         throw e;
     }
     public void error( SAXParseException e ) throws SAXException {
         throw e;
     }
     public void warning( SAXParseException e ) throws SAXException {
         // noop
     }
 }

When a new ValidatorHandler object is created, initially this field is set to null.

Parameters:
errorHandler - A new error handler to be set. This parameter can be null.

getErrorHandler

public abstract ErrorHandler getErrorHandler()
Gets the current ErrorHandler set to this ValidatorHandler.

Returns:
This method returns the object that was last set through the setErrorHandler(ErrorHandler) method, or null if that method has never been called since this ValidatorHandler has created.
See Also:
setErrorHandler(ErrorHandler)

setResourceResolver

public abstract void setResourceResolver(LSResourceResolver resourceResolver)
Sets the LSResourceResolver to customize resource resolution while in a validation episode.

ValidatorHandler uses a LSResourceResolver when it needs to locate external resources while a validation, although exactly what constitutes "locating external resources" is up to each schema language.

When the LSResourceResolver is null, the implementation will behave as if the following LSResourceResolver is set:

 class DumbLSResourceResolver implements LSResourceResolver {
     public LSInput resolveResource(
         String publicId, String systemId, String baseURI) {

         return null; // always return null
     }
 }

If a LSResourceResolver throws a RuntimeException (or instances of its derived classes), then the ValidatorHandler will abort the parsing and the caller of the validate method will receive the same RuntimeException.

When a new ValidatorHandler object is created, initially this field is set to null.

Parameters:
resourceResolver - A new resource resolver to be set. This parameter can be null.

getResourceResolver

public abstract LSResourceResolver getResourceResolver()
Gets the current LSResourceResolver set to this ValidatorHandler.

Returns:
This method returns the object that was last set through the setResourceResolver(LSResourceResolver) method, or null if that method has never been called since this ValidatorHandler has created.
See Also:
setErrorHandler(ErrorHandler)

getTypeInfoProvider

public abstract TypeInfoProvider getTypeInfoProvider()
Obtains the TypeInfoProvider implementation of this ValidatorHandler.

The obtained TypeInfoProvider can be queried during a parse to access the type information determined by the validator.

Some schema languages do not define the notion of type, for those languages, this method may not be supported. However, to be compliant with this specification, implementations for W3C XML Schema 1.0 must support this operation.

Returns:
null if the validator / schema language does not support the notion of TypeInfo. Otherwise a non-null valid TypeInfoProvider.

getFeature

public boolean getFeature(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException
Look up the value of a feature flag.

The feature name is any fully-qualified URI. It is possible for a ValidatorHandler to recognize a feature name but temporarily be unable to return its value. Some feature values may be available only in specific contexts, such as before, during, or after a validation.

Implementors are free (and encouraged) to invent their own features, using names built on their own URIs.

Parameters:
name - The feature name, which is a non-null fully-qualified URI.
Returns:
The current value of the feature (true or false).
Throws:
SAXNotRecognizedException - If the feature value can't be assigned or retrieved.
SAXNotSupportedException - When the ValidatorHandler recognizes the feature name but cannot determine its value at this time.
NullPointerException - When name is null.
See Also:
setFeature(String, boolean)

setFeature

public void setFeature(String name,
                       boolean value)
                throws SAXNotRecognizedException,
                       SAXNotSupportedException

Set a feature for this ValidatorHandler.

Feature can be used to control the way a ValidatorHandler parses schemas. The feature name is any fully-qualified URI. It is possible for a SchemaFactory to expose a feature value but to be unable to change the current value. Some feature values may be immutable or mutable only in specific contexts, such as before, during, or after a validation.

All implementations are required to support the XMLConstants.FEATURE_SECURE_PROCESSING feature. When the feature is:

  • true: the implementation will limit XML processing to conform to implementation limits. Examples include enity expansion limits and XML Schema constructs that would consume large amounts of resources. If XML processing is limited for security reasons, it will be reported via a call to the registered ErrorHandler.fatalError(SAXParseException exception). See setErrorHandler(ErrorHandler errorHandler).
  • false: the implementation will processing XML according to the XML specifications without regard to possible implementation limits.

Parameters:
name - The feature name, which is a non-null fully-qualified URI.
value - The requested value of the feature (true or false).
Throws:
SAXNotRecognizedException - If the feature value can't be assigned or retrieved.
SAXNotSupportedException - When the ValidatorHandler recognizes the feature name but cannot set the requested value.
NullPointerException - When name is null.
See Also:
getFeature(String)

setProperty

public void setProperty(String name,
                        Object object)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException
Set the value of a property.

The property name is any fully-qualified URI. It is possible for a ValidatorHandler to recognize a property name but to be unable to change the current value. Some property values may be immutable or mutable only in specific contexts, such as before, during, or after a validation.

ValidatorHandlers are not required to recognize setting any specific property names.

Parameters:
name - The property name, which is a non-null fully-qualified URI.
object - The requested value for the property.
Throws:
SAXNotRecognizedException - If the property value can't be assigned or retrieved.
SAXNotSupportedException - When the ValidatorHandler recognizes the property name but cannot set the requested value.
NullPointerException - When name is null.

getProperty

public Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException
Look up the value of a property.

The property name is any fully-qualified URI. It is possible for a ValidatorHandler to recognize a property name but temporarily be unable to return its value. Some property values may be available only in specific contexts, such as before, during, or after a validation.

ValidatorHandlers are not required to recognize any specific property names.

Implementors are free (and encouraged) to invent their own properties, using names built on their own URIs.

Parameters:
name - The property name, which is a non-null fully-qualified URI.
Returns:
The current value of the property.
Throws:
SAXNotRecognizedException - If the property value can't be assigned or retrieved.
SAXNotSupportedException - When the XMLReader recognizes the property name but cannot determine its value at this time.
NullPointerException - When name is null.
See Also:
setProperty(String, Object)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


ws

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.ws

This package contains the core JAX-WS APIs.

See:
Description

Interface Summary
AsyncHandler<T> | The AsyncHandler interface is implemented by clients that wish to receive callback notification of the completion of service endpoint operations invoked asynchronously.
Binding | The Binding interface is the base interface for JAX-WS protocol bindings.
BindingProvider | The BindingProvider interface provides access to the protocol binding and associated context objects for request and response message processing.
Dispatch<T> | The Dispatch interface provides support for the dynamic invocation of a service endpoint operations.
LogicalMessage | The LogicalMessage interface represents a protocol agnostic XML message and contains methods that provide access to the payload of the message.
Provider<T> | Service endpoints may implement the Provider interface as a dynamic alternative to an SEI.
Response<T> | The Response interface provides methods used to obtain the payload and context of a message sent in response to an operation invocation.
WebServiceContext | A WebServiceContext makes it possible for a web service endpoint implementation class to access message context and security information relative to a request being served.

Class Summary
Endpoint | A Web service endpoint.
Holder<T> | Holds a value of type T.
Service | Service objects provide the client view of a Web service.
WebServicePermission | This class defines web service permissions.

Enum Summary
Service.Mode The orientation of a dynamic client or service.

Exception Summary
ProtocolException | The ProtocolException class is a base class for exceptions related to a specific protocol binding.
WebServiceException | The WebServiceException class is the base exception class for all JAX-WS API runtime exceptions.

Annotation Types Summary
BindingType | The BindingType annotation is used to specify the binding to use for a web service endpoint implementation class.
RequestWrapper | Used to annotate methods in the Service Endpoint Interface with the request wrapper bean to be used at runtime.
ResponseWrapper | Used to annotate methods in the Service Endpoint Interface with the response wrapper bean to be used at runtime.
ServiceMode | Used to indicate whether a Provider implementation wishes to work with entire protocol messages or just with protocol message payloads.
WebEndpoint | Used to annotate the getPortName() methods of a generated service interface.
WebFault | Used to annotate service specific exception classes to customize to the local and namespace name of the fault element and the name of the fault bean.
WebServiceClient | Used to annotate a generated service interface.
WebServiceProvider | Used to annotate a Provider implementation class.
WebServiceRef | The WebServiceRef annotation is used to define a reference to a web service and (optionally) an injection target for it.
WebServiceRefs | The WebServiceRefs annotation allows multiple web service references to be declared at the class level.

Package javax.xml.ws Description

This package contains the core JAX-WS APIs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.ws Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.ws

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.ws.Endpoint
    • javax.xml.ws.Holder<T>
    • java.security.Permission (implements java.security.Guard, java.io.Serializable)
      • java.security.BasicPermission (implements java.io.Serializable)
        • javax.xml.ws.WebServicePermission
    • javax.xml.ws.Service
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.lang.RuntimeException
          • javax.xml.ws.WebServiceException
            • javax.xml.ws.ProtocolException

Interface Hierarchy

  • javax.xml.ws.AsyncHandler<T>
  • javax.xml.ws.Binding
  • javax.xml.ws.BindingProvider
    • javax.xml.ws.Dispatch<T>
  • java.util.concurrent.Future<V>
    • javax.xml.ws.Response<T>
  • javax.xml.ws.LogicalMessage
  • javax.xml.ws.Provider<T>
  • javax.xml.ws.WebServiceContext

Annotation Type Hierarchy

  • javax.xml.ws.WebServiceRefs (implements java.lang.annotation.Annotation)
  • javax.xml.ws.WebServiceRef (implements java.lang.annotation.Annotation)
  • javax.xml.ws.WebServiceProvider (implements java.lang.annotation.Annotation)
  • javax.xml.ws.WebServiceClient (implements java.lang.annotation.Annotation)
  • javax.xml.ws.WebFault (implements java.lang.annotation.Annotation)
  • javax.xml.ws.WebEndpoint (implements java.lang.annotation.Annotation)
  • javax.xml.ws.ServiceMode (implements java.lang.annotation.Annotation)
  • javax.xml.ws.ResponseWrapper (implements java.lang.annotation.Annotation)
  • javax.xml.ws.RequestWrapper (implements java.lang.annotation.Annotation)
  • javax.xml.ws.BindingType (implements java.lang.annotation.Annotation)

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • javax.xml.ws.Service.Mode
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.ws

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.ws

Packages that use javax.xml.ws
javax.xml.ws | This package contains the core JAX-WS APIs.
javax.xml.ws.handler | This package defines APIs for message handlers.
javax.xml.ws.http | This package defines APIs specific to the HTTP binding.
javax.xml.ws.soap | This package defines APIs specific to the SOAP binding.
javax.xml.ws.spi | This package defines SPIs for JAX-WS 2.0.

Classes in javax.xml.ws used by javax.xml.ws
AsyncHandler
The AsyncHandler interface is implemented by clients that wish to receive callback notification of the completion of service endpoint operations invoked asynchronously.
Binding
The Binding interface is the base interface for JAX-WS protocol bindings.
BindingProvider
The BindingProvider interface provides access to the protocol binding and associated context objects for request and response message processing.
Dispatch
The Dispatch interface provides support for the dynamic invocation of a service endpoint operations.
Endpoint
A Web service endpoint.
Response
The Response interface provides methods used to obtain the payload and context of a message sent in response to an operation invocation.
Service
Service objects provide the client view of a Web service.
Service.Mode
The orientation of a dynamic client or service.
WebServiceException
The WebServiceException class is the base exception class for all JAX-WS API runtime exceptions.

Classes in javax.xml.ws used by javax.xml.ws.handler
LogicalMessage
The LogicalMessage interface represents a protocol agnostic XML message and contains methods that provide access to the payload of the message.

Classes in javax.xml.ws used by javax.xml.ws.http
Binding
The Binding interface is the base interface for JAX-WS protocol bindings.
ProtocolException
The ProtocolException class is a base class for exceptions related to a specific protocol binding.
WebServiceException
The WebServiceException class is the base exception class for all JAX-WS API runtime exceptions.

Classes in javax.xml.ws used by javax.xml.ws.soap
Binding
The Binding interface is the base interface for JAX-WS protocol bindings.
ProtocolException
The ProtocolException class is a base class for exceptions related to a specific protocol binding.
WebServiceException
The WebServiceException class is the base exception class for all JAX-WS API runtime exceptions.

Classes in javax.xml.ws used by javax.xml.ws.spi
Dispatch
The Dispatch interface provides support for the dynamic invocation of a service endpoint operations.
Endpoint
A Web service endpoint.
Service.Mode
The orientation of a dynamic client or service.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AsyncHandler

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws
Interface AsyncHandler<T>

public interface AsyncHandler<T>

The AsyncHandler interface is implemented by clients that wish to receive callback notification of the completion of service endpoint operations invoked asynchronously.

Since:
JAX-WS 2.0

Method Summary
 void handleResponse(Response<T> res)
Called when the response to an asynchronous operation is available.

Method Detail

handleResponse

void handleResponse(Response<T> res)
Called when the response to an asynchronous operation is available.

Parameters:
res - The response to the operation invocation.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Binding

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws
Interface Binding

All Known Subinterfaces:
HTTPBinding, SOAPBinding
public interface Binding

The Binding interface is the base interface for JAX-WS protocol bindings.

Since:
JAX-WS 2.0

Method Summary
List<Handler> | getHandlerChain() Gets a copy of the handler chain for a protocol binding instance.
void | setHandlerChain(List<Handler> chain) Sets the handler chain for the protocol binding instance.

Method Detail

getHandlerChain

List<Handler> getHandlerChain()
Gets a copy of the handler chain for a protocol binding instance. If the returned chain is modified a call to setHandlerChain is required to configure the binding instance with the new chain.

Returns:
java.util.List Handler chain

setHandlerChain

void setHandlerChain(List<Handler> chain)
Sets the handler chain for the protocol binding instance.

Parameters:
chain - A List of handler configuration entries
Throws:
WebServiceException - On an error in the configuration of the handler chain
UnsupportedOperationException - If this operation is not supported. This may be done to avoid any overriding of a pre-configured handler chain.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BindingProvider

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws
Interface BindingProvider

All Known Subinterfaces:
Dispatch<T>
public interface BindingProvider

The BindingProvider interface provides access to the protocol binding and associated context objects for request and response message processing.

Since:
JAX-WS 2.0
See Also:
Binding

Field Summary
static String | ENDPOINT_ADDRESS_PROPERTY Standard property: Target service endpoint address.
static String | PASSWORD_PROPERTY Standard property: Password for authentication.
static String | SESSION_MAINTAIN_PROPERTY Standard property: This boolean property is used by a service client to indicate whether or not it wants to participate in a session with a service endpoint.
static String | SOAPACTION_URI_PROPERTY Standard property for SOAPAction.
static String | SOAPACTION_USE_PROPERTY Standard property for SOAPAction.
static String | USERNAME_PROPERTY Standard property: User name for authentication.
Method Summary
Binding | getBinding() Get the Binding for this binding provider.
Map<String,Object> | getRequestContext() Get the context that is used to initialize the message context for request messages.
Map<String,Object> | getResponseContext() Get the context that resulted from processing a response message.

Field Detail

USERNAME_PROPERTY

static final String USERNAME_PROPERTY
Standard property: User name for authentication.

Type: java.lang.String

See Also:
Constant Field Values

PASSWORD_PROPERTY

static final String PASSWORD_PROPERTY
Standard property: Password for authentication.

Type: java.lang.String

See Also:
Constant Field Values

ENDPOINT_ADDRESS_PROPERTY

static final String ENDPOINT_ADDRESS_PROPERTY
Standard property: Target service endpoint address. The URI scheme for the endpoint address specification must correspond to the protocol/transport binding for the binding in use.

Type: java.lang.String

See Also:
Constant Field Values

SESSION_MAINTAIN_PROPERTY

static final String SESSION_MAINTAIN_PROPERTY
Standard property: This boolean property is used by a service client to indicate whether or not it wants to participate in a session with a service endpoint. If this property is set to true, the service client indicates that it wants the session to be maintained. If set to false, the session is not maintained. The default value for this property is false.

Type: java.lang.Boolean

See Also:
Constant Field Values

SOAPACTION_USE_PROPERTY

static final String SOAPACTION_USE_PROPERTY
Standard property for SOAPAction. This boolean property indicates whether or not SOAPAction is to be used. The default value of this property is false indicating that the SOAPAction is not used.

Type: java.lang.Boolean

See Also:
Constant Field Values

SOAPACTION_URI_PROPERTY

static final String SOAPACTION_URI_PROPERTY
Standard property for SOAPAction. Indicates the SOAPAction URI if the javax.xml.ws.soap.http.soapaction.use property is set to true.

Type: java.lang.String

See Also:
Constant Field Values
Method Detail

getRequestContext

Map<String,Object> getRequestContext()
Get the context that is used to initialize the message context for request messages. Modifications to the request context do not affect the message context of either synchronous or asynchronous operations that have already been started.

Returns:
The context that is used in processing request messages.

getResponseContext

Map<String,Object> getResponseContext()
Get the context that resulted from processing a response message. The returned context is for the most recently completed synchronous operation. Subsequent synchronous operation invocations overwrite the response context. Asynchronous operations return their response context via the Response interface.

Returns:
The context that resulted from processing the latest response messages.

getBinding

Binding getBinding()
Get the Binding for this binding provider.

Returns:
The Binding for this binding provider.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BindingType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.ws
Annotation Type BindingType

@Target(value=TYPE)
@Retention(value=RUNTIME)
@Documented
public @interface BindingType

The BindingType annotation is used to specify the binding to use for a web service endpoint implementation class.

This annotation may be overriden programmatically or via deployment descriptors, depending on the platform in use.

Since:
JAX-WS 2.0

Optional Element Summary
 String value
A binding identifier (a URI).

value

public abstract String value
A binding identifier (a URI). If not specified, the default is the SOAP 1.1 / HTTP binding.

See the SOAPBinding and HTTPBinding for the definition of the standard binding identifiers.

See Also:
Binding, SOAPBinding.SOAP11HTTP_BINDING, SOAPBinding.SOAP12HTTP_BINDING, HTTPBinding.HTTP_BINDING
Default:
""
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


Uses of Class javax.xml.ws.BindingType

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.BindingType

No usage of javax.xml.ws.BindingType

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.Endpoint

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.Endpoint

Packages that use Endpoint
javax.xml.ws | This package contains the core JAX-WS APIs.
javax.xml.ws.spi | This package defines SPIs for JAX-WS 2.0.

Uses of Endpoint in javax.xml.ws

Methods in javax.xml.ws that return Endpoint
static Endpoint | Endpoint.create(Object implementor) Creates an endpoint with the specified implementor object.
static Endpoint | Endpoint.create(String bindingId, Object implementor) Creates an endpoint with the specified binding type and implementor object.
static Endpoint | Endpoint.publish(String address, Object implementor) Creates and publishes an endpoint for the specified implementor object at the given address.

Uses of Endpoint in javax.xml.ws.spi

Methods in javax.xml.ws.spi that return Endpoint
abstract Endpoint | Provider.createAndPublishEndpoint(String address, Object implementor) Creates and publishes an endpoint object with the specified address and implementation object.
abstract Endpoint | Provider.createEndpoint(String bindingId, Object implementor) Creates an endpoint object with the provided binding and implementation object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.Holder

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.Holder

No usage of javax.xml.ws.Holder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.ProtocolException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.ProtocolException

Packages that use ProtocolException
javax.xml.ws.http | This package defines APIs specific to the HTTP binding.
javax.xml.ws.soap | This package defines APIs specific to the SOAP binding.

Uses of ProtocolException in javax.xml.ws.http

Subclasses of ProtocolException in javax.xml.ws.http
 class HTTPException
The HTTPException exception represents a XML/HTTP fault.

Uses of ProtocolException in javax.xml.ws.soap

Subclasses of ProtocolException in javax.xml.ws.soap
 class SOAPFaultException
The SOAPFaultException exception represents a SOAP 1.1 or 1.2 fault.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.RequestWrapper

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.RequestWrapper

No usage of javax.xml.ws.RequestWrapper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.ResponseWrapper

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.ResponseWrapper

No usage of javax.xml.ws.ResponseWrapper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.Service

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.Service

Packages that use Service
javax.xml.ws This package contains the core JAX-WS APIs.

Uses of Service in javax.xml.ws

Methods in javax.xml.ws that return Service
static Service | Service.create(QName serviceName) Create a Service instance.
static Service | Service.create(URL wsdlDocumentLocation, QName serviceName) Create a Service instance.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.Service.Mode

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.Service.Mode

Packages that use Service.Mode
javax.xml.ws | This package contains the core JAX-WS APIs.
javax.xml.ws.spi | This package defines SPIs for JAX-WS 2.0.

Uses of Service.Mode in javax.xml.ws

Methods in javax.xml.ws that return Service.Mode
static Service.Mode | Service.Mode.valueOf(String name) Returns the enum constant of this type with the specified name.
static Service.Mode[] | Service.Mode.values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods in javax.xml.ws with parameters of type Service.Mode
<T> Dispatch<T>
Service.createDispatch(QName portName, Class<T> type, Service.Mode mode)
Creates a Dispatch instance for use with objects of the users choosing.
 Dispatch<Object> Service.createDispatch(QName portName, JAXBContext context, Service.Mode mode)
Creates a Dispatch instance for use with JAXB generated objects.

Uses of Service.Mode in javax.xml.ws.spi

Methods in javax.xml.ws.spi with parameters of type Service.Mode
abstract
<T> Dispatch<T>
ServiceDelegate.createDispatch(QName portName, Class<T> type, Service.Mode mode)
Creates a Dispatch instance for use with objects of the users choosing.
abstract  Dispatch<Object> ServiceDelegate.createDispatch(QName portName, JAXBContext context, Service.Mode mode)
Creates a Dispatch instance for use with JAXB generated objects.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.ServiceMode

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.ServiceMode

No usage of javax.xml.ws.ServiceMode

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.WebEndpoint

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.WebEndpoint

No usage of javax.xml.ws.WebEndpoint

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.WebFault

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.WebFault

No usage of javax.xml.ws.WebFault

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.WebServiceClient

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.WebServiceClient

No usage of javax.xml.ws.WebServiceClient

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.WebServiceException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.WebServiceException

Packages that use WebServiceException
javax.xml.ws | This package contains the core JAX-WS APIs.
javax.xml.ws.http | This package defines APIs specific to the HTTP binding.
javax.xml.ws.soap | This package defines APIs specific to the SOAP binding.

Uses of WebServiceException in javax.xml.ws

Subclasses of WebServiceException in javax.xml.ws
 class ProtocolException
The ProtocolException class is a base class for exceptions related to a specific protocol binding.

Uses of WebServiceException in javax.xml.ws.http

Subclasses of WebServiceException in javax.xml.ws.http
 class HTTPException
The HTTPException exception represents a XML/HTTP fault.

Uses of WebServiceException in javax.xml.ws.soap

Subclasses of WebServiceException in javax.xml.ws.soap
 class SOAPFaultException
The SOAPFaultException exception represents a SOAP 1.1 or 1.2 fault.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.WebServicePermission

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.WebServicePermission

No usage of javax.xml.ws.WebServicePermission

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.WebServiceProvider

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.WebServiceProvider

No usage of javax.xml.ws.WebServiceProvider

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.WebServiceRef

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.WebServiceRef

No usage of javax.xml.ws.WebServiceRef

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.WebServiceRefs

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.WebServiceRefs

No usage of javax.xml.ws.WebServiceRefs

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.AsyncHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.AsyncHandler

Packages that use AsyncHandler
javax.xml.ws This package contains the core JAX-WS APIs.

Uses of AsyncHandler in javax.xml.ws

Methods in javax.xml.ws with parameters of type AsyncHandler
 Future<?> Dispatch.invokeAsync(T msg, AsyncHandler<T> handler)
Invoke a service operation asynchronously.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.Binding

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.Binding

Packages that use Binding
javax.xml.ws | This package contains the core JAX-WS APIs.
javax.xml.ws.http | This package defines APIs specific to the HTTP binding.
javax.xml.ws.soap | This package defines APIs specific to the SOAP binding.

Uses of Binding in javax.xml.ws

Methods in javax.xml.ws that return Binding
abstract Binding | Endpoint.getBinding() Returns the binding for this endpoint.
Binding | BindingProvider.getBinding() Get the Binding for this binding provider.

Uses of Binding in javax.xml.ws.http

Subinterfaces of Binding in javax.xml.ws.http
 interface HTTPBinding
The HTTPBinding interface is an abstraction for the XML/HTTP binding.

Uses of Binding in javax.xml.ws.soap

Subinterfaces of Binding in javax.xml.ws.soap
 interface SOAPBinding
The SOAPBinding interface is an abstraction for the SOAP binding.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.BindingProvider

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.BindingProvider

Packages that use BindingProvider
javax.xml.ws This package contains the core JAX-WS APIs.

Uses of BindingProvider in javax.xml.ws

Subinterfaces of BindingProvider in javax.xml.ws
 interface Dispatch<T>
The Dispatch interface provides support for the dynamic invocation of a service endpoint operations.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.Dispatch

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.Dispatch

Packages that use Dispatch
javax.xml.ws | This package contains the core JAX-WS APIs.
javax.xml.ws.spi | This package defines SPIs for JAX-WS 2.0.

Uses of Dispatch in javax.xml.ws

Methods in javax.xml.ws that return Dispatch
<T> Dispatch<T>
Service.createDispatch(QName portName, Class<T> type, Service.Mode mode)
Creates a Dispatch instance for use with objects of the users choosing.
 Dispatch<Object> Service.createDispatch(QName portName, JAXBContext context, Service.Mode mode)
Creates a Dispatch instance for use with JAXB generated objects.

Uses of Dispatch in javax.xml.ws.spi

Methods in javax.xml.ws.spi that return Dispatch
abstract
<T> Dispatch<T>
ServiceDelegate.createDispatch(QName portName, Class<T> type, Service.Mode mode)
Creates a Dispatch instance for use with objects of the users choosing.
abstract  Dispatch<Object> ServiceDelegate.createDispatch(QName portName, JAXBContext context, Service.Mode mode)
Creates a Dispatch instance for use with JAXB generated objects.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.LogicalMessage

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.LogicalMessage

Packages that use LogicalMessage
javax.xml.ws.handler This package defines APIs for message handlers.

Uses of LogicalMessage in javax.xml.ws.handler

Methods in javax.xml.ws.handler that return LogicalMessage
 LogicalMessage LogicalMessageContext.getMessage()
Gets the message from this message context

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.Provider

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.Provider

No usage of javax.xml.ws.Provider

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.Response

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.Response

Packages that use Response
javax.xml.ws This package contains the core JAX-WS APIs.

Uses of Response in javax.xml.ws

Methods in javax.xml.ws that return Response
 Response<T> Dispatch.invokeAsync(T msg)
Invoke a service operation asynchronously.

Methods in javax.xml.ws with parameters of type Response
 void AsyncHandler.handleResponse(Response<T> res)
Called when the response to an asynchronous operation is available.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.WebServiceContext

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.WebServiceContext

No usage of javax.xml.ws.WebServiceContext

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Dispatch

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws
Interface Dispatch<T>

All Superinterfaces:
BindingProvider
public interface Dispatch<T>
extends BindingProvider

The Dispatch interface provides support for the dynamic invocation of a service endpoint operations. The javax.xml.ws.Service interface acts as a factory for the creation of Dispatch instances.

Since:
JAX-WS 2.0

Field Summary
Fields inherited from interface javax.xml.ws.BindingProvider
ENDPOINT_ADDRESS_PROPERTY, PASSWORD_PROPERTY, SESSION_MAINTAIN_PROPERTY, SOAPACTION_URI_PROPERTY, SOAPACTION_USE_PROPERTY, USERNAME_PROPERTY
Method Summary
T | invoke(T msg) Invoke a service operation synchronously.
Response<T> | invokeAsync(T msg) Invoke a service operation asynchronously.
Future<?> | invokeAsync(T msg, AsyncHandler<T> handler) Invoke a service operation asynchronously.
void | invokeOneWay(T msg) Invokes a service operation using the one-way interaction mode.
Methods inherited from interface javax.xml.ws.BindingProvider
getBinding, getRequestContext, getResponseContext

Method Detail

invoke

T invoke(T msg)
Invoke a service operation synchronously. The client is responsible for ensuring that the msg object when marshalled is formed according to the requirements of the protocol binding in use.

Parameters:
msg - An object that will form the message or payload of the message used to invoke the operation.
Returns:
The response message or message payload to the operation invocation.
Throws:
WebServiceException - If a fault occurs during communication with the service
WebServiceException - If there is any error in the configuration of the Dispatch instance

invokeAsync

Response<T> invokeAsync(T msg)
Invoke a service operation asynchronously. The method returns without waiting for the response to the operation invocation, the results of the operation are obtained by polling the returned Response. The client is responsible for ensuring that the msg object when marshalled is formed according to the requirements of the protocol binding in use.

Parameters:
msg - An object that will form the message or payload of the message used to invoke the operation.
Returns:
The response message or message payload to the operation invocation.
Throws:
WebServiceException - If there is any error in the configuration of the Dispatch instance

invokeAsync

Future<?> invokeAsync(T msg,
                      AsyncHandler<T> handler)
Invoke a service operation asynchronously. The method returns without waiting for the response to the operation invocation, the results of the operation are communicated to the client via the passed in handler. The client is responsible for ensuring that the msg object when marshalled is formed according to the requirements of the protocol binding in use.

Parameters:
msg - An object that will form the message or payload of the message used to invoke the operation.
handler - The handler object that will receive the response to the operation invocation.
Returns:
A Future object that may be used to check the status of the operation invocation. This object must not be used to try to obtain the results of the operation - the object returned from Future.get() is implementation dependent and any use of it will result in non-portable behaviour.
Throws:
WebServiceException - If there is any error in the configuration of the Dispatch instance

invokeOneWay

void invokeOneWay(T msg)
Invokes a service operation using the one-way interaction mode. The operation invocation is logically non-blocking, subject to the capabilities of the underlying protocol, no results are returned. When the protocol in use is SOAP/HTTP, this method must block until an HTTP response code has been received or an error occurs. The client is responsible for ensuring that the msg object when marshalled is formed according to the requirements of the protocol binding in use.

Parameters:
msg - An object that will form the message or payload of the message used to invoke the operation.
Throws:
WebServiceException - If there is any error in the configuration of the Dispatch instance or if an error occurs during the invocation.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Endpoint

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws
Class Endpoint

java.lang.Object
    extended by  javax.xml.ws.Endpoint

public abstract class Endpoint
extends Object

A Web service endpoint.

Endpoints are created using the static methods defined in this class. An endpoint is always tied to one Binding and one implementor, both set at endpoint creation time.

An endpoint is either in a published or an unpublished state. The publish methods can be used to start publishing an endpoint, at which point it starts accepting incoming requests. Conversely, the stop method can be used to stop accepting incoming requests and take the endpoint down. Once stopped, an endpoint cannot be published again.

An Executor may be set on the endpoint in order to gain better control over the threads used to dispatch incoming requests. For instance, thread pooling with certain parameters can be enabled by creating a ThreadPoolExecutor and registering it with the endpoint.

Handler chains can be set using the contained Binding.

An endpoint may have a list of metadata documents, such as WSDL and XMLSchema documents, bound to it. At publishing time, the JAX-WS implementation will try to reuse as much of that metadata as possible instead of generating new one based on the annotations present on the implementor.

Since:
JAX-WS 2.0
See Also:
Binding, BindingType, SOAPBinding, Executor

Field Summary
static String | WSDL_PORT Standard property: name of WSDL port.
static String | WSDL_SERVICE Standard property: name of WSDL service.
Constructor Summary
Endpoint()
Method Summary
static Endpoint | create(Object implementor) Creates an endpoint with the specified implementor object.
static Endpoint | create(String bindingId, Object implementor) Creates an endpoint with the specified binding type and implementor object.
abstract Binding | getBinding() Returns the binding for this endpoint.
abstract Executor | getExecutor() Returns the executor for this Endpointinstance.
abstract Object | getImplementor() Returns the implementation object for this endpoint.
abstract List<Source> | getMetadata() Returns a list of metadata documents for the service.
abstract Map<String,Object> | getProperties() Returns the property bag for this Endpoint instance.
abstract boolean | isPublished() Returns true if the endpoint is in the published state.
abstract void | publish(Object serverContext) Publishes this endpoint at the provided server context.
abstract void | publish(String address) Publishes this endpoint at the given address.
static Endpoint | publish(String address, Object implementor) Creates and publishes an endpoint for the specified implementor object at the given address.
abstract void | setExecutor(Executor executor) Sets the executor for this Endpoint instance.
abstract void | setMetadata(List<Source> metadata) Sets the metadata for this endpoint.
abstract void | setProperties(Map<String,Object> properties) Sets the property bag for this Endpoint instance.
abstract void | stop() Stops publishing this endpoint.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

WSDL_SERVICE

public static final String WSDL_SERVICE
Standard property: name of WSDL service.

Type: javax.xml.namespace.QName

See Also:
Constant Field Values

WSDL_PORT

public static final String WSDL_PORT
Standard property: name of WSDL port.

Type: javax.xml.namespace.QName

See Also:
Constant Field Values
Constructor Detail

Endpoint

public Endpoint()
Method Detail

create

public static Endpoint create(Object implementor)
Creates an endpoint with the specified implementor object. If there is a binding specified via a BindingType annotation then it MUST be used else a default of SOAP 1.1 / HTTP binding MUST be used.

The newly created endpoint may be published by calling one of the javax.xml.ws.Endpoint#publish(String) and javax.xml.ws.Endpoint#publish(Object) methods.

Parameters:
implementor - The endpoint implementor.
Returns:
The newly created endpoint.

create

public static Endpoint create(String bindingId,
                              Object implementor)
Creates an endpoint with the specified binding type and implementor object.

The newly created endpoint may be published by calling one of the javax.xml.ws.Endpoint#publish(String) and javax.xml.ws.Endpoint#publish(Object) methods.

Parameters:
bindingId - A URI specifying the binding to use. If the bindingID is null and no binding is specified via a BindingType annotation then a default SOAP 1.1 / HTTP binding MUST be used.
implementor - The endpoint implementor.
Returns:
The newly created endpoint.

getBinding

public abstract Binding getBinding()
Returns the binding for this endpoint.

Returns:
The binding for this endpoint

getImplementor

public abstract Object getImplementor()
Returns the implementation object for this endpoint.

Returns:
The implementor for this endpoint

publish

public abstract void publish(String address)
Publishes this endpoint at the given address. The necessary server infrastructure will be created and configured by the JAX-WS implementation using some default configuration. In order to get more control over the server configuration, please use the javax.xml.ws.Endpoint#publish(Object) method instead.

Parameters:
address - A URI specifying the address to use. The address must be compatible with the binding specified at the time the endpoint was created.
Throws:
IllegalArgumentException - If the provided address URI is not usable in conjunction with the endpoint's binding.
IllegalStateException - If the endpoint has been published already or it has been stopped.

publish

public static Endpoint publish(String address,
                               Object implementor)
Creates and publishes an endpoint for the specified implementor object at the given address.

The necessary server infrastructure will be created and configured by the JAX-WS implementation using some default configuration. In order to get more control over the server configuration, please use the javax.xml.ws.Endpoint#create(String,Object) and javax.xml.ws.Endpoint#publish(Object) method instead.

Parameters:
address - A URI specifying the address and transport/protocol to use. A http: URI must result in the SOAP 1.1/HTTP binding being used. Implementations may support other URI schemes.
implementor - The endpoint implementor.
Returns:
The newly created endpoint.

publish

public abstract void publish(Object serverContext)
Publishes this endpoint at the provided server context. A server context encapsulates the server infrastructure and addressing information for a particular transport. For a call to this method to succeed, the server context passed as an argument to it must be compatible with the endpoint's binding.

Parameters:
serverContext - An object representing a server context to be used for publishing the endpoint.
Throws:
IllegalArgumentException - If the provided server context is not supported by the implementation or turns out to be unusable in conjunction with the endpoint's binding.
IllegalStateException - If the endpoint has been published already or it has been stopped.

stop

public abstract void stop()
Stops publishing this endpoint. If the endpoint is not in a published state, this method has not effect.

isPublished

public abstract boolean isPublished()
Returns true if the endpoint is in the published state.

Returns:
true if the endpoint is in the published state.

getMetadata

public abstract List<Source> getMetadata()
Returns a list of metadata documents for the service.

Returns:
List<javax.xml.transform.Source> A list of metadata documents for the service

setMetadata

public abstract void setMetadata(List<Source> metadata)
Sets the metadata for this endpoint.

Parameters:
metadata - A list of XML document sources containing metadata information for the endpoint (e.g. WSDL or XML Schema documents)
Throws:
IllegalStateException - If the endpoint has already been published.

getExecutor

public abstract Executor getExecutor()
Returns the executor for this Endpointinstance. The executor is used to dispatch an incoming request to the implementor object.

Returns:
The java.util.concurrent.Executor to be used to dispatch a request.
See Also:
Executor

setExecutor

public abstract void setExecutor(Executor executor)
Sets the executor for this Endpoint instance. The executor is used to dispatch an incoming request to the implementor object. If this Endpoint is published using the publish(Object) method and the specified server context defines its own threading behavior, the executor may be ignored.

Parameters:
executor - The java.util.concurrent.Executor to be used to dispatch a request.
Throws:
SecurityException - If the instance does not support setting an executor for security reasons (e.g. the necessary permissions are missing).
See Also:
Executor

getProperties

public abstract Map<String,Object> getProperties()
Returns the property bag for this Endpoint instance.

Returns:
Map<String,Object> The property bag associated with this instance.

setProperties

public abstract void setProperties(Map<String,Object> properties)
Sets the property bag for this Endpoint instance.

Parameters:
properties - The property bag associated with this instance.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


handler

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.ws.handler

This package defines APIs for message handlers.

See:
Description

Interface Summary
Handler<C extends MessageContext> | The Handler interface is the base interface for JAX-WS handlers.
HandlerResolver | HandlerResolver is an interface implemented by an application to get control over the handler chain set on proxy/dispatch objects at the time of their creation.
LogicalHandler<C extends LogicalMessageContext> | The LogicalHandler extends Handler to provide typesafety for the message context parameter.
LogicalMessageContext | The LogicalMessageContext interface extends MessageContext to provide access to a the contained message as a protocol neutral LogicalMessage
MessageContext | The interface MessageContext abstracts the message context that is processed by a handler in the handle method.
PortInfo | The PortInfo interface is used by a HandlerResolver to query information about the port it is being asked to create a handler chain for.

Enum Summary
MessageContext.Scope Property scope.

Package javax.xml.ws.handler Description

This package defines APIs for message handlers.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.ws.handler Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.ws.handler

Package Hierarchies:
All Packages

Interface Hierarchy

  • javax.xml.ws.handler.Handler<C>
    • javax.xml.ws.handler.LogicalHandler<C>
  • javax.xml.ws.handler.HandlerResolver
  • java.util.Map<K,V>
    • javax.xml.ws.handler.MessageContext
      • javax.xml.ws.handler.LogicalMessageContext
  • javax.xml.ws.handler.PortInfo

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • javax.xml.ws.handler.MessageContext.Scope
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


LogicalHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws.handler
Interface LogicalHandler<C extends LogicalMessageContext>

All Superinterfaces:
Handler<C>
public interface LogicalHandler<C extends LogicalMessageContext>
extends Handler<C>

The LogicalHandler extends Handler to provide typesafety for the message context parameter.

Since:
JAX-WS 2.0

Method Summary
Methods inherited from interface javax.xml.ws.handler.Handler
close, handleFault, handleMessage

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Package javax.xml.ws.handler

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.ws.handler

Packages that use javax.xml.ws.handler
javax.xml.ws | This package contains the core JAX-WS APIs.
javax.xml.ws.handler | This package defines APIs for message handlers.
javax.xml.ws.handler.soap | This package defines APIs for SOAP message handlers.
javax.xml.ws.spi | This package defines SPIs for JAX-WS 2.0.

Classes in javax.xml.ws.handler used by javax.xml.ws
Handler
The Handler interface is the base interface for JAX-WS handlers.
HandlerResolver
HandlerResolver is an interface implemented by an application to get control over the handler chain set on proxy/dispatch objects at the time of their creation.
MessageContext
The interface MessageContext abstracts the message context that is processed by a handler in the handle method.

Classes in javax.xml.ws.handler used by javax.xml.ws.handler
Handler
The Handler interface is the base interface for JAX-WS handlers.
LogicalMessageContext
The LogicalMessageContext interface extends MessageContext to provide access to a the contained message as a protocol neutral LogicalMessage
MessageContext
The interface MessageContext abstracts the message context that is processed by a handler in the handle method.
MessageContext.Scope
Property scope.
PortInfo
The PortInfo interface is used by a HandlerResolver to query information about the port it is being asked to create a handler chain for.

Classes in javax.xml.ws.handler used by javax.xml.ws.handler.soap
Handler
The Handler interface is the base interface for JAX-WS handlers.
MessageContext
The interface MessageContext abstracts the message context that is processed by a handler in the handle method.

Classes in javax.xml.ws.handler used by javax.xml.ws.spi
HandlerResolver
HandlerResolver is an interface implemented by an application to get control over the handler chain set on proxy/dispatch objects at the time of their creation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.handler.MessageContext.Scope

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.handler.MessageContext.Scope

Packages that use MessageContext.Scope
javax.xml.ws.handler This package defines APIs for message handlers.

Uses of MessageContext.Scope in javax.xml.ws.handler

Methods in javax.xml.ws.handler that return MessageContext.Scope
MessageContext.Scope | MessageContext.getScope(String name) Gets the scope of a property.
static MessageContext.Scope | MessageContext.Scope.valueOf(String name) Returns the enum constant of this type with the specified name.
static MessageContext.Scope[] | MessageContext.Scope.values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods in javax.xml.ws.handler with parameters of type MessageContext.Scope
 void MessageContext.setScope(String name, MessageContext.Scope scope)
Sets the scope of a property.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.handler.Handler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.handler.Handler

Packages that use Handler
javax.xml.ws | This package contains the core JAX-WS APIs.
javax.xml.ws.handler | This package defines APIs for message handlers.
javax.xml.ws.handler.soap | This package defines APIs for SOAP message handlers.

Uses of Handler in javax.xml.ws

Methods in javax.xml.ws that return types with arguments of type Handler
 List<Handler> Binding.getHandlerChain()
Gets a copy of the handler chain for a protocol binding instance.

Method parameters in javax.xml.ws with type arguments of type Handler
 void Binding.setHandlerChain(List<Handler> chain)
Sets the handler chain for the protocol binding instance.

Uses of Handler in javax.xml.ws.handler

Subinterfaces of Handler in javax.xml.ws.handler
 interface LogicalHandler<C extends LogicalMessageContext>
The LogicalHandler extends Handler to provide typesafety for the message context parameter.

Methods in javax.xml.ws.handler that return types with arguments of type Handler
 List<Handler> HandlerResolver.getHandlerChain(PortInfo portInfo)
Gets the handler chain for the specified port.

Uses of Handler in javax.xml.ws.handler.soap

Subinterfaces of Handler in javax.xml.ws.handler.soap
 interface SOAPHandler<T extends SOAPMessageContext>
The SOAPHandler class extends Handler to provide typesafety for the message context parameter and add a method to obtain access to the headers that may be processed by the handler.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.handler.HandlerResolver

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.handler.HandlerResolver

Packages that use HandlerResolver
javax.xml.ws | This package contains the core JAX-WS APIs.
javax.xml.ws.spi | This package defines SPIs for JAX-WS 2.0.

Uses of HandlerResolver in javax.xml.ws

Methods in javax.xml.ws that return HandlerResolver
 HandlerResolver Service.getHandlerResolver()
Returns the configured handler resolver.

Methods in javax.xml.ws with parameters of type HandlerResolver
 void Service.setHandlerResolver(HandlerResolver handlerResolver)
Sets the HandlerResolver for this Service instance.

Uses of HandlerResolver in javax.xml.ws.spi

Methods in javax.xml.ws.spi that return HandlerResolver
abstract  HandlerResolver ServiceDelegate.getHandlerResolver()
Returns the configured handler resolver.

Methods in javax.xml.ws.spi with parameters of type HandlerResolver
abstract  void ServiceDelegate.setHandlerResolver(HandlerResolver handlerResolver)
Sets the HandlerResolver for this Service instance.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.handler.LogicalHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.handler.LogicalHandler

No usage of javax.xml.ws.handler.LogicalHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.handler.LogicalMessageContext

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.handler.LogicalMessageContext

Packages that use LogicalMessageContext
javax.xml.ws.handler This package defines APIs for message handlers.

Uses of LogicalMessageContext in javax.xml.ws.handler

Classes in javax.xml.ws.handler with type parameters of type LogicalMessageContext
 interface LogicalHandler<C extends LogicalMessageContext>
The LogicalHandler extends Handler to provide typesafety for the message context parameter.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.handler.MessageContext

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.handler.MessageContext

Packages that use MessageContext
javax.xml.ws | This package contains the core JAX-WS APIs.
javax.xml.ws.handler | This package defines APIs for message handlers.
javax.xml.ws.handler.soap | This package defines APIs for SOAP message handlers.

Uses of MessageContext in javax.xml.ws

Methods in javax.xml.ws that return MessageContext
 MessageContext WebServiceContext.getMessageContext()
Returns the MessageContext for the request being served at the time this method is called.

Uses of MessageContext in javax.xml.ws.handler

Classes in javax.xml.ws.handler with type parameters of type MessageContext
 interface Handler<C extends MessageContext>
The Handler interface is the base interface for JAX-WS handlers.

Subinterfaces of MessageContext in javax.xml.ws.handler
 interface LogicalMessageContext
The LogicalMessageContext interface extends MessageContext to provide access to a the contained message as a protocol neutral LogicalMessage

Methods in javax.xml.ws.handler with parameters of type MessageContext
 void Handler.close(MessageContext context)
Called at the conclusion of a message exchange pattern just prior to the JAX-WS runtime disptaching a message, fault or exception.

Uses of MessageContext in javax.xml.ws.handler.soap

Subinterfaces of MessageContext in javax.xml.ws.handler.soap
 interface SOAPMessageContext
The interface SOAPMessageContext provides access to the SOAP message for either RPC request or response.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.handler.PortInfo

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.handler.PortInfo

Packages that use PortInfo
javax.xml.ws.handler This package defines APIs for message handlers.

Uses of PortInfo in javax.xml.ws.handler

Methods in javax.xml.ws.handler with parameters of type PortInfo
 List<Handler> HandlerResolver.getHandlerChain(PortInfo portInfo)
Gets the handler chain for the specified port.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Handler

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws.handler
Interface Handler<C extends MessageContext>

All Known Subinterfaces:
LogicalHandler<C>, SOAPHandler<T>
public interface Handler<C extends MessageContext>

The Handler interface is the base interface for JAX-WS handlers.

Since:
JAX-WS 2.0

Method Summary
void | close(MessageContext context) Called at the conclusion of a message exchange pattern just prior to the JAX-WS runtime disptaching a message, fault or exception.
boolean | handleFault(C context) The handleFault method is invoked for fault message processing.
boolean | handleMessage(C context) The handleMessage method is invoked for normal processing of inbound and outbound messages.

Method Detail

handleMessage

boolean handleMessage(C context)
The handleMessage method is invoked for normal processing of inbound and outbound messages. Refer to the description of the handler framework in the JAX-WS specification for full details.

Parameters:
context - the message context.
Returns:
An indication of whether handler processing should continue for the current message
  • Return true to continue processing.
  • Return false to block processing.
Throws:
RuntimeException - Causes the JAX-WS runtime to cease handler processing and generate a fault.
ProtocolException - Causes the JAX-WS runtime to switch to fault message processing.

handleFault

boolean handleFault(C context)
The handleFault method is invoked for fault message processing. Refer to the description of the handler framework in the JAX-WS specification for full details.

Parameters:
context - the message context
Returns:
An indication of whether handler fault processing should continue for the current message
  • Return true to continue processing.
  • Return false to block processing.
Throws:
RuntimeException - Causes the JAX-WS runtime to cease handler fault processing and dispatch the fault.
ProtocolException - Causes the JAX-WS runtime to cease handler fault processing and dispatch the fault.

close

void close(MessageContext context)
Called at the conclusion of a message exchange pattern just prior to the JAX-WS runtime disptaching a message, fault or exception. Refer to the description of the handler framework in the JAX-WS specification for full details.

Parameters:
context - the message context
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


HandlerResolver

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws.handler
Interface HandlerResolver

public interface HandlerResolver

HandlerResolver is an interface implemented by an application to get control over the handler chain set on proxy/dispatch objects at the time of their creation.

A HandlerResolver may be set on a Service using the setHandlerResolver method.

When the runtime invokes a HandlerResolver, it will pass it a PortInfo object containing information about the port that the proxy/dispatch object will be accessing.

Since:
JAX-WS 2.0
See Also:
Service.setHandlerResolver(javax.xml.ws.handler.HandlerResolver)

Method Summary
 List<Handler> getHandlerChain(PortInfo portInfo)
Gets the handler chain for the specified port.

Method Detail

getHandlerChain

List<Handler> getHandlerChain(PortInfo portInfo)
Gets the handler chain for the specified port.

Parameters:
portInfo - Contains information about the port being accessed.
Returns:
java.util.List Handler chain
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LogicalMessageContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws.handler
Interface LogicalMessageContext

All Superinterfaces:
Map<String,Object>, MessageContext
public interface LogicalMessageContext
extends MessageContext

The LogicalMessageContext interface extends MessageContext to provide access to a the contained message as a protocol neutral LogicalMessage

Since:
JAX-WS 2.0

Nested Class Summary
Nested classes/interfaces inherited from interface javax.xml.ws.handler.MessageContext
MessageContext.Scope
Nested classes/interfaces inherited from interface java.util.Map
Map.Entry<K,V>
Field Summary
Fields inherited from interface javax.xml.ws.handler.MessageContext
HTTP_REQUEST_HEADERS, HTTP_REQUEST_METHOD, HTTP_RESPONSE_CODE, HTTP_RESPONSE_HEADERS, INBOUND_MESSAGE_ATTACHMENTS, MESSAGE_OUTBOUND_PROPERTY, OUTBOUND_MESSAGE_ATTACHMENTS, PATH_INFO, QUERY_STRING, SERVLET_CONTEXT, SERVLET_REQUEST, SERVLET_RESPONSE, WSDL_DESCRIPTION, WSDL_INTERFACE, WSDL_OPERATION, WSDL_PORT, WSDL_SERVICE
Method Summary
 LogicalMessage getMessage()
Gets the message from this message context
Methods inherited from interface javax.xml.ws.handler.MessageContext
getScope, setScope
Methods inherited from interface java.util.Map
clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values

Method Detail

getMessage

LogicalMessage getMessage()
Gets the message from this message context

Returns:
The contained message; returns null if no message is present in this message context
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MessageContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws.handler
Interface MessageContext

All Superinterfaces:
Map<String,Object>
All Known Subinterfaces:
LogicalMessageContext, SOAPMessageContext
public interface MessageContext
extends Map<String,Object>

The interface MessageContext abstracts the message context that is processed by a handler in the handle method.

The MessageContext interface provides methods to manage a property set. MessageContext properties enable handlers in a handler chain to share processing related state.

Since:
JAX-WS 2.0

Nested Class Summary
static class MessageContext.Scope
Property scope.
Nested classes/interfaces inherited from interface java.util.Map
Map.Entry<K,V>
Field Summary
static String | HTTP_REQUEST_HEADERS Standard property: HTTP request headers.
static String | HTTP_REQUEST_METHOD Standard property: HTTP request method.
static String | HTTP_RESPONSE_CODE Standard property: HTTP response status code.
static String | HTTP_RESPONSE_HEADERS Standard property: HTTP response headers.
static String | INBOUND_MESSAGE_ATTACHMENTS Standard property: Map of attachments to a message for the inbound message, key is the MIME Content-ID, value is a DataHandler.
static String | MESSAGE_OUTBOUND_PROPERTY Standard property: message direction, true for outbound messages, false for inbound.
static String | OUTBOUND_MESSAGE_ATTACHMENTS Standard property: Map of attachments to a message for the outbound message, key is the MIME Content-ID, value is a DataHandler.
static String | PATH_INFO Standard property: Request Path Info
static String | QUERY_STRING Standard property: Query string for request.
static String | SERVLET_CONTEXT Standard property: servlet context object.
static String | SERVLET_REQUEST Standard property: servlet request object.
static String | SERVLET_RESPONSE Standard property: servlet response object.
static String | WSDL_DESCRIPTION Standard property: input source for WSDL document.
static String | WSDL_INTERFACE Standard property: name of wsdl interface (2.0) or port type (1.1).
static String | WSDL_OPERATION Standard property: name of WSDL operation.
static String | WSDL_PORT Standard property: name of WSDL port.
static String | WSDL_SERVICE Standard property: name of WSDL service.
Method Summary
MessageContext.Scope | getScope(String name) Gets the scope of a property.
void | setScope(String name, MessageContext.Scope scope) Sets the scope of a property.
Methods inherited from interface java.util.Map
clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values

Field Detail

MESSAGE_OUTBOUND_PROPERTY

static final String MESSAGE_OUTBOUND_PROPERTY
Standard property: message direction, true for outbound messages, false for inbound.

Type: boolean

See Also:
Constant Field Values

INBOUND_MESSAGE_ATTACHMENTS

static final String INBOUND_MESSAGE_ATTACHMENTS
Standard property: Map of attachments to a message for the inbound message, key is the MIME Content-ID, value is a DataHandler.

Type: java.util.Map

See Also:
Constant Field Values

OUTBOUND_MESSAGE_ATTACHMENTS

static final String OUTBOUND_MESSAGE_ATTACHMENTS
Standard property: Map of attachments to a message for the outbound message, key is the MIME Content-ID, value is a DataHandler.

Type: java.util.Map

See Also:
Constant Field Values

WSDL_DESCRIPTION

static final String WSDL_DESCRIPTION
Standard property: input source for WSDL document.

Type: org.xml.sax.InputSource

See Also:
Constant Field Values

WSDL_SERVICE

static final String WSDL_SERVICE
Standard property: name of WSDL service.

Type: javax.xml.namespace.QName

See Also:
Constant Field Values

WSDL_PORT

static final String WSDL_PORT
Standard property: name of WSDL port.

Type: javax.xml.namespace.QName

See Also:
Constant Field Values

WSDL_INTERFACE

static final String WSDL_INTERFACE
Standard property: name of wsdl interface (2.0) or port type (1.1).

Type: javax.xml.namespace.QName

See Also:
Constant Field Values

WSDL_OPERATION

static final String WSDL_OPERATION
Standard property: name of WSDL operation.

Type: javax.xml.namespace.QName

See Also:
Constant Field Values

HTTP_RESPONSE_CODE

static final String HTTP_RESPONSE_CODE
Standard property: HTTP response status code.

Type: java.lang.Integer

See Also:
Constant Field Values

HTTP_REQUEST_HEADERS

static final String HTTP_REQUEST_HEADERS
Standard property: HTTP request headers.

Type: java.util.Map>

See Also:
Constant Field Values

HTTP_RESPONSE_HEADERS

static final String HTTP_RESPONSE_HEADERS
Standard property: HTTP response headers.

Type: java.util.Map>

See Also:
Constant Field Values

HTTP_REQUEST_METHOD

static final String HTTP_REQUEST_METHOD
Standard property: HTTP request method.

Type: java.lang.String

See Also:
Constant Field Values

SERVLET_REQUEST

static final String SERVLET_REQUEST
Standard property: servlet request object.

Type: javax.servlet.http.HttpServletRequest

See Also:
Constant Field Values

SERVLET_RESPONSE

static final String SERVLET_RESPONSE
Standard property: servlet response object.

Type: javax.servlet.http.HttpServletResponse

See Also:
Constant Field Values

SERVLET_CONTEXT

static final String SERVLET_CONTEXT
Standard property: servlet context object.

Type: javax.servlet.ServletContext

See Also:
Constant Field Values

QUERY_STRING

static final String QUERY_STRING
Standard property: Query string for request.

Type: String

See Also:
Constant Field Values

PATH_INFO

static final String PATH_INFO
Standard property: Request Path Info

Type: String

See Also:
Constant Field Values
Method Detail

setScope

void setScope(String name,
              MessageContext.Scope scope)
Sets the scope of a property.

Parameters:
name - Name of the property associated with the MessageContext
scope - Desired scope of the property
Throws:
IllegalArgumentException - if an illegal property name is specified

getScope

MessageContext.Scope getScope(String name)
Gets the scope of a property.

Parameters:
name - Name of the property
Returns:
Scope of the property
Throws:
IllegalArgumentException - if a non-existant property name is specified
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MessageContext.Scope

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.xml.ws.handler
Enum MessageContext.Scope

java.lang.Object
    extended by  java.lang.Enum<MessageContext.Scope>
        extended by  javax.xml.ws.handler.MessageContext.Scope
All Implemented Interfaces:
Serializable, Comparable<MessageContext.Scope>
Enclosing interface:
MessageContext
public static enum MessageContext.Scope
extends Enum<MessageContext.Scope>

Property scope. Properties scoped as APPLICATION are visible to handlers, client applications and service endpoints; properties scoped as HANDLER are only normally visible to handlers.

Enum Constant Summary
APPLICATION
HANDLER
Method Summary
static MessageContext.Scope | valueOf(String name) Returns the enum constant of this type with the specified name.
static MessageContext.Scope[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

APPLICATION

public static final MessageContext.Scope APPLICATION

HANDLER

public static final MessageContext.Scope HANDLER
Method Detail

values

public static MessageContext.Scope[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (MessageContext.Scope c : MessageContext.Scope.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static MessageContext.Scope valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


PortInfo

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws.handler
Interface PortInfo

public interface PortInfo

The PortInfo interface is used by a HandlerResolver to query information about the port it is being asked to create a handler chain for.

This interface is never implemented by an application, only by a JAX-WS implementation.

Since:
JAX-WS 2.0

Method Summary
String | getBindingID() Gets the URI identifying the binding used by the port being accessed.
QName | getPortName() Gets the qualified name of the WSDL port being accessed.
QName | getServiceName() Gets the qualified name of the WSDL service name containing the port being accessed.

Method Detail

getServiceName

QName getServiceName()
Gets the qualified name of the WSDL service name containing the port being accessed.

Returns:
javax.xml.namespace.QName The qualified name of the WSDL service.

getPortName

QName getPortName()
Gets the qualified name of the WSDL port being accessed.

Returns:
javax.xml.namespace.QName The qualified name of the WSDL port.

getBindingID

String getBindingID()
Gets the URI identifying the binding used by the port being accessed.

Returns:
String The binding identifier for the port.
See Also:
Binding
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


soap

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.ws.handler.soap

This package defines APIs for SOAP message handlers.

See:
Description

Interface Summary
SOAPHandler<T extends SOAPMessageContext> | The SOAPHandler class extends Handler to provide typesafety for the message context parameter and add a method to obtain access to the headers that may be processed by the handler.
SOAPMessageContext | The interface SOAPMessageContext provides access to the SOAP message for either RPC request or response.

Package javax.xml.ws.handler.soap Description

This package defines APIs for SOAP message handlers.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.ws.handler.soap Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.ws.handler.soap

Package Hierarchies:
All Packages

Interface Hierarchy

  • javax.xml.ws.handler.Handler<C>
    • javax.xml.ws.handler.soap.SOAPHandler<T>
  • java.util.Map<K,V>
    • javax.xml.ws.handler.MessageContext
      • javax.xml.ws.handler.soap.SOAPMessageContext
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.ws.handler.soap

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.ws.handler.soap

Packages that use javax.xml.ws.handler.soap
javax.xml.ws.handler.soap This package defines APIs for SOAP message handlers.

Classes in javax.xml.ws.handler.soap used by javax.xml.ws.handler.soap
SOAPMessageContext
The interface SOAPMessageContext provides access to the SOAP message for either RPC request or response.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.handler.soap.SOAPHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.handler.soap.SOAPHandler

No usage of javax.xml.ws.handler.soap.SOAPHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.handler.soap.SOAPMessageContext

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.handler.soap.SOAPMessageContext

Packages that use SOAPMessageContext
javax.xml.ws.handler.soap This package defines APIs for SOAP message handlers.

Uses of SOAPMessageContext in javax.xml.ws.handler.soap

Classes in javax.xml.ws.handler.soap with type parameters of type SOAPMessageContext
 interface SOAPHandler<T extends SOAPMessageContext>
The SOAPHandler class extends Handler to provide typesafety for the message context parameter and add a method to obtain access to the headers that may be processed by the handler.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


SOAPHandler

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws.handler.soap
Interface SOAPHandler<T extends SOAPMessageContext>

All Superinterfaces:
Handler<T>
public interface SOAPHandler<T extends SOAPMessageContext>
extends Handler<T>

The SOAPHandler class extends Handler to provide typesafety for the message context parameter and add a method to obtain access to the headers that may be processed by the handler.

Since:
JAX-WS 2.0

Method Summary
 Set<QName> getHeaders()
Gets the header blocks that can be processed by this Handler instance.
Methods inherited from interface javax.xml.ws.handler.Handler
close, handleFault, handleMessage

Method Detail

getHeaders

Set<QName> getHeaders()
Gets the header blocks that can be processed by this Handler instance.

Returns:
Set of QNames of header blocks processed by this handler instance. QName is the qualified name of the outermost element of the Header block.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


SOAPMessageContext

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws.handler.soap
Interface SOAPMessageContext

All Superinterfaces:
Map<String,Object>, MessageContext
public interface SOAPMessageContext
extends MessageContext

The interface SOAPMessageContext provides access to the SOAP message for either RPC request or response. The javax.xml.soap.SOAPMessage specifies the standard Java API for the representation of a SOAP 1.1 message with attachments.

Since:
JAX-WS 2.0
See Also:
SOAPMessage

Nested Class Summary
Nested classes/interfaces inherited from interface javax.xml.ws.handler.MessageContext
MessageContext.Scope
Nested classes/interfaces inherited from interface java.util.Map
Map.Entry<K,V>
Field Summary
Fields inherited from interface javax.xml.ws.handler.MessageContext
HTTP_REQUEST_HEADERS, HTTP_REQUEST_METHOD, HTTP_RESPONSE_CODE, HTTP_RESPONSE_HEADERS, INBOUND_MESSAGE_ATTACHMENTS, MESSAGE_OUTBOUND_PROPERTY, OUTBOUND_MESSAGE_ATTACHMENTS, PATH_INFO, QUERY_STRING, SERVLET_CONTEXT, SERVLET_REQUEST, SERVLET_RESPONSE, WSDL_DESCRIPTION, WSDL_INTERFACE, WSDL_OPERATION, WSDL_PORT, WSDL_SERVICE
Method Summary
Object[] | getHeaders(QName header, JAXBContext context, boolean allRoles) Gets headers that have a particular qualified name from the message in the message context.
SOAPMessage | getMessage() Gets the SOAPMessage from this message context.
Set<String> | getRoles() Gets the SOAP actor roles associated with an execution of the handler chain.
void | setMessage(SOAPMessage message) Sets the SOAPMessage in this message context
Methods inherited from interface javax.xml.ws.handler.MessageContext
getScope, setScope
Methods inherited from interface java.util.Map
clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values

Method Detail

getMessage

SOAPMessage getMessage()
Gets the SOAPMessage from this message context. Modifications to the returned SOAPMessage change the message in-place, there is no need to susequently call setMessage.

Returns:
Returns the SOAPMessage; returns null if no SOAPMessage is present in this message context

setMessage

void setMessage(SOAPMessage message)
Sets the SOAPMessage in this message context

Parameters:
message - SOAP message
Throws:
WebServiceException - If any error during the setting of the SOAPMessage in this message context
UnsupportedOperationException - If this operation is not supported

getHeaders

Object[] getHeaders(QName header,
                    JAXBContext context,
                    boolean allRoles)
Gets headers that have a particular qualified name from the message in the message context. Note that a SOAP message can contain multiple headers with the same qualified name.

Parameters:
header - The XML qualified name of the SOAP header(s).
context - The JAXBContext that should be used to unmarshall the header
allRoles - If true then returns headers for all SOAP roles, if false then only returns headers targetted at the roles currently being played by this SOAP node, see getRoles.
Returns:
An array of unmarshalled headers; returns an empty array if no message is present in this message context or no headers match the supplied qualified name.
Throws:
WebServiceException - If an error occurs when using the supplied JAXBContext to unmarshall. The cause of the WebServiceException is the original JAXBException.

getRoles

Set<String> getRoles()
Gets the SOAP actor roles associated with an execution of the handler chain. Note that SOAP actor roles apply to the SOAP node and are managed using SOAPBinding.setRoles and SOAPBinding.getRoles. Handler instances in the handler chain use this information about the SOAP actor roles to process the SOAP header blocks. Note that the SOAP actor roles are invariant during the processing of SOAP message through the handler chain.

Returns:
Array of String for SOAP actor roles
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Holder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws
Class Holder<T>

java.lang.Object
    extended by  javax.xml.ws.Holder<T>

public final class Holder<T>
extends Object

Holds a value of type T.

Since:
JAX-WS 2.0

Field Summary
 T value
The value contained in the holder.
Constructor Summary
Holder()
Creates a new holder with a null value.
Holder(T value)
Create a new holder with the specified value.
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public T value
The value contained in the holder.

Constructor Detail

Holder

public Holder()
Creates a new holder with a null value.

Holder

public Holder(T value)
Create a new holder with the specified value.

Parameters:
value - The value to be stored in the holder.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


http

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.ws.http

This package defines APIs specific to the HTTP binding.

See:
Description

Interface Summary
HTTPBinding The HTTPBinding interface is an abstraction for the XML/HTTP binding.

Exception Summary
HTTPException The HTTPException exception represents a XML/HTTP fault.

Package javax.xml.ws.http Description

This package defines APIs specific to the HTTP binding.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.ws.http Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.ws.http

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.lang.RuntimeException
          • javax.xml.ws.WebServiceException
            • javax.xml.ws.ProtocolException
              • javax.xml.ws.http.HTTPException

Interface Hierarchy

  • javax.xml.ws.Binding
    • javax.xml.ws.http.HTTPBinding
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.ws.http

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.ws.http

No usage of javax.xml.ws.http

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.http.HTTPException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.http.HTTPException

No usage of javax.xml.ws.http.HTTPException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.http.HTTPBinding

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.http.HTTPBinding

No usage of javax.xml.ws.http.HTTPBinding

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


HTTPBinding

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws.http
Interface HTTPBinding

All Superinterfaces:
Binding
public interface HTTPBinding
extends Binding

The HTTPBinding interface is an abstraction for the XML/HTTP binding.

Since:
JAX-WS 2.0

Field Summary
static String HTTP_BINDING
A constant representing the identity of the XML/HTTP binding.
Method Summary
Methods inherited from interface javax.xml.ws.Binding
getHandlerChain, setHandlerChain

Field Detail

HTTP_BINDING

static final String HTTP_BINDING
A constant representing the identity of the XML/HTTP binding.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


HTTPException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws.http
Class HTTPException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  javax.xml.ws.WebServiceException
                    extended by  javax.xml.ws.ProtocolException
                        extended by  javax.xml.ws.http.HTTPException
All Implemented Interfaces:
Serializable
public class HTTPException
extends ProtocolException

The HTTPException exception represents a XML/HTTP fault.

Since there is no standard format for faults or exceptions in XML/HTTP messaging, only the HTTP status code is captured.

Since:
JAX-WS 2.0
See Also:
Serialized Form

Constructor Summary
HTTPException(int statusCode)
Constructor for the HTTPException
Method Summary
 int getStatusCode()
Gets the HTTP status code.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

HTTPException

public HTTPException(int statusCode)
Constructor for the HTTPException

Parameters:
statusCode - int for the HTTP status code
Method Detail

getStatusCode

public int getStatusCode()
Gets the HTTP status code.

Returns:
HTTP status code
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


LogicalMessage

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws
Interface LogicalMessage

public interface LogicalMessage

The LogicalMessage interface represents a protocol agnostic XML message and contains methods that provide access to the payload of the message.

Since:
JAX-WS 2.0

Method Summary
Source | getPayload() Gets the message payload as an XML source, may be called multiple times on the same LogicalMessage instance, always returns a new Source that may be used to retrieve the entire message payload.
Object | getPayload(JAXBContext context) Gets the message payload as a JAXB object.
void | setPayload(Object payload, JAXBContext context) Sets the message payload
void | setPayload(Source payload) Sets the message payload

Method Detail

getPayload

Source getPayload()
Gets the message payload as an XML source, may be called multiple times on the same LogicalMessage instance, always returns a new Source that may be used to retrieve the entire message payload.

If the returned Source is an instance of DOMSource, then modifications to the encapsulated DOM tree change the message payload in-place, there is no need to susequently call setPayload. Other types of Source provide only read access to the message payload.

Returns:
The contained message payload; returns null if no payload is present in this message.

setPayload

void setPayload(Source payload)
Sets the message payload

Parameters:
payload - message payload
Throws:
WebServiceException - If any error during the setting of the payload in this message
UnsupportedOperationException - If this operation is not supported

getPayload

Object getPayload(JAXBContext context)
Gets the message payload as a JAXB object. Note that there is no connection between the returned object and the message payload, changes to the payload require calling setPayload.

Parameters:
context - The JAXBContext that should be used to unmarshall the message payload
Returns:
The contained message payload; returns null if no payload is present in this message
Throws:
WebServiceException - If an error occurs when using a supplied JAXBContext to unmarshall the payload. The cause of the WebServiceException is the original JAXBException.

setPayload

void setPayload(Object payload,
                JAXBContext context)
Sets the message payload

Parameters:
payload - message payload
context - The JAXBContext that should be used to marshall the payload
Throws:
UnsupportedOperationException - If this operation is not supported
WebServiceException - If an error occurs when using the supplied JAXBContext to marshall the payload. The cause of the WebServiceException is the original JAXBException.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ProtocolException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws
Class ProtocolException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  javax.xml.ws.WebServiceException
                    extended by  javax.xml.ws.ProtocolException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
HTTPException, SOAPFaultException
public class ProtocolException
extends WebServiceException

The ProtocolException class is a base class for exceptions related to a specific protocol binding. Subclasses are used to communicate protocol level fault information to clients and may be used on the server to control the protocol specific fault representation.

Since:
JAX-WS 2.0
See Also:
Serialized Form

Constructor Summary
ProtocolException()
Constructs a new protocol exception with null as its detail message.
ProtocolException(String message)
Constructs a new protocol exception with the specified detail message.
ProtocolException(String message, Throwable cause)
Constructs a new runtime exception with the specified detail message and cause.
ProtocolException(Throwable cause)
Constructs a new runtime exception with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ProtocolException

public ProtocolException()
Constructs a new protocol exception with null as its detail message. The cause is not initialized, and may subsequently be initialized by a call to Throwable.initCause(java.lang.Throwable).

ProtocolException

public ProtocolException(String message)
Constructs a new protocol exception with the specified detail message. The cause is not initialized, and may subsequently be initialized by a call to Throwable.initCause(java.lang.Throwable).

Parameters:
message - the detail message. The detail message is saved for later retrieval by the Throwable.getMessage() method.

ProtocolException

public ProtocolException(String message,
                         Throwable cause)
Constructs a new runtime exception with the specified detail message and cause. Note that the detail message associated with cause is not automatically incorporated in this runtime exception's detail message.

Parameters:
message - the detail message (which is saved for later retrieval by the Throwable.getMessage() method).
cause - the cause (which is saved for later retrieval by the Throwable.getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.)

ProtocolException

public ProtocolException(Throwable cause)
Constructs a new runtime exception with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause). This constructor is useful for runtime exceptions that are little more than wrappers for other throwables.

Parameters:
cause - the cause (which is saved for later retrieval by the Throwable.getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Provider

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws
Interface Provider<T>

public interface Provider<T>

Service endpoints may implement the Provider interface as a dynamic alternative to an SEI.

Implementations are required to support Provider<Source>, Provider<SOAPMessage> and Provider<DataSource>, depending on the binding in use and the service mode.

The ServiceMode annotation can be used to control whether the Provider instance will receive entire protocol messages or just message payloads.

Since:
JAX-WS 2.0
See Also:
Source, SOAPMessage, ServiceMode

Method Summary
 T invoke(T request)
Invokes an operation occording to the contents of the request message.

Method Detail

invoke

T invoke(T request)
Invokes an operation occording to the contents of the request message.

Parameters:
request - The request message or message payload.
Returns:
The response message or message payload. May be null if there is no response.
Throws:
WebServiceException - if there is an error processing request. The cause of the WebServiceException may be set to a subclass of ProtocolException to control the protocol level representation of the exception.
See Also:
MessageContext, ProtocolException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RequestWrapper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.ws
Annotation Type RequestWrapper

@Target(value=METHOD)
@Retention(value=RUNTIME)
@Documented
public @interface RequestWrapper

Used to annotate methods in the Service Endpoint Interface with the request wrapper bean to be used at runtime. The default value of the localName is the operationName, as defined in WebMethod annotation and the targetNamespace is the target namespace of the SEI.

When starting from Java this annotation is used resolve overloading conflicts in document literal mode. Only the className is required in this case.

Since:
JAX-WS 2.0

Optional Element Summary
String | className Request wrapper bean name.
String | localName Elements local name.
String | targetNamespace Elements namespace name.

localName

public abstract String localName
Elements local name.

Default:
""

targetNamespace

public abstract String targetNamespace
Elements namespace name.

Default:
""

className

public abstract String className
Request wrapper bean name.

Default:
""
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


Response

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws
Interface Response<T>

All Superinterfaces:
Future<T>
public interface Response<T>
extends Future<T>

The Response interface provides methods used to obtain the payload and context of a message sent in response to an operation invocation.

For asynchronous operation invocations it provides additional methods to check the status of the request. The get(...) methods may throw the standard set of exceptions and their cause may be a RemoteException or a WebServiceException that represents the error that occured during the asynchronous method invocation.

Since:
JAX-WS 2.0

Method Summary
 Map<String,Object> getContext()
Gets the contained response context.
Methods inherited from interface java.util.concurrent.Future
cancel, get, get, isCancelled, isDone

Method Detail

getContext

Map<String,Object> getContext()
Gets the contained response context.

Returns:
The contained response context. May be null if a response is not yet available.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ResponseWrapper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.ws
Annotation Type ResponseWrapper

@Target(value=METHOD)
@Retention(value=RUNTIME)
@Documented
public @interface ResponseWrapper

Used to annotate methods in the Service Endpoint Interface with the response wrapper bean to be used at runtime. The default value of the localName is the operationName as defined in WebMethod annotation appended with Response and the targetNamespace is the target namespace of the SEI.

When starting from Java this annotation is used resolve overloading conflicts in document literal mode. Only the className is required in this case.

Since:
JAX-WS 2.0

Optional Element Summary
String | className Response wrapper bean name.
String | localName Elements local name.
String | targetNamespace Elements namespace name.

localName

public abstract String localName
Elements local name.

Default:
""

targetNamespace

public abstract String targetNamespace
Elements namespace name.

Default:
""

className

public abstract String className
Response wrapper bean name.

Default:
""
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


Service

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws
Class Service

java.lang.Object
    extended by  javax.xml.ws.Service

public class Service
extends Object

Service objects provide the client view of a Web service.

Service acts as a factory of the following:

  • Proxies for a target service endpoint.
  • Instances of javax.xml.ws.Dispatch for dynamic message-oriented invocation of a remote operation.

    • The ports available on a service can be enumerated using the getPorts method. Alternatively, you can pass a service endpoint interface to the unary getPort method and let the runtime select a compatible port.

    Handler chains for all the objects created by a Service can be set by means of a HandlerResolver.

    An Executor may be set on the service in order to gain better control over the threads used to dispatch asynchronous callbacks. For instance, thread pooling with certain parameters can be enabled by creating a ThreadPoolExecutor and registering it with the service.

    Since:
    JAX-WS 2.0
    See Also:
    Provider, HandlerResolver, Executor

    Nested Class Summary
    static class Service.Mode
    The orientation of a dynamic client or service.
    Constructor Summary
    protected Service(URL wsdlDocumentLocation, QName serviceName)
    Method Summary
     void addPort(QName portName, String bindingId, String endpointAddress)
    Creates a new port for the service.
    static Service create(QName serviceName)
    Create a Service instance.
    static Service create(URL wsdlDocumentLocation, QName serviceName)
    Create a Service instance.
    <T> Dispatch<T>
            createDispatch(QName portName, Class<T> type, Service.Mode mode)
    Creates a Dispatch instance for use with objects of the users choosing.
     Dispatch<Object> createDispatch(QName portName, JAXBContext context, Service.Mode mode)
    Creates a Dispatch instance for use with JAXB generated objects.
     Executor getExecutor()
    Returns the executor for this Serviceinstance.
     HandlerResolver getHandlerResolver()
    Returns the configured handler resolver.
    <T> T
            getPort(Class<T> serviceEndpointInterface)
    The getPort method returns a stub.
    <T> T
            getPort(QName portName, Class<T> serviceEndpointInterface)
    The getPort method returns a stub.
     Iterator<QName> getPorts()
    Returns an Iterator for the list of QNames of service endpoints grouped by this service
     QName getServiceName()
    Gets the name of this service.
     URL getWSDLDocumentLocation()
    Gets the location of the WSDL document for this Service.
     void setExecutor(Executor executor)
    Sets the executor for this Service instance.
     void setHandlerResolver(HandlerResolver handlerResolver)
    Sets the HandlerResolver for this Service instance.
    Methods inherited from class java.lang.Object
    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Constructor Detail

    Service

    protected Service(URL wsdlDocumentLocation,
                  QName serviceName)
    Method Detail

    getPort

    public <T> T getPort(QName portName,
                     Class<T> serviceEndpointInterface)
    The getPort method returns a stub. A service client uses this stub to invoke operations on the target service endpoint. The serviceEndpointInterface specifies the service endpoint interface that is supported by the created dynamic proxy or stub instance.

    Parameters:
    portName - Qualified name of the service endpoint in the WSDL service description
    serviceEndpointInterface - Service endpoint interface supported by the dynamic proxy or stub instance
    Returns:
    Object Proxy instance that supports the specified service endpoint interface
    Throws:
    WebServiceException - This exception is thrown in the following cases:
    • If there is an error in creation of the proxy
    • If there is any missing WSDL metadata as required by this method
    • Optionally, if an illegal serviceEndpointInterface or portName is specified
    See Also:
    Proxy, InvocationHandler

    getPort

    public <T> T getPort(Class<T> serviceEndpointInterface)
    The getPort method returns a stub. The parameter serviceEndpointInterface specifies the service endpoint interface that is supported by the returned proxy. In the implementation of this method, the JAX-WS runtime system takes the responsibility of selecting a protocol binding (and a port) and configuring the proxy accordingly. The returned proxy should not be reconfigured by the client.

    Parameters:
    serviceEndpointInterface - Service endpoint interface
    Returns:
    Object instance that supports the specified service endpoint interface
    Throws:
    WebServiceException -
    • If there is an error during creation of the proxy
    • If there is any missing WSDL metadata as required by this method
    • Optionally, if an illegal serviceEndpointInterface is specified

    addPort

    public void addPort(QName portName,
                    String bindingId,
                    String endpointAddress)
    Creates a new port for the service. Ports created in this way contain no WSDL port type information and can only be used for creating Dispatchinstances.

    Parameters:
    portName - Qualified name for the target service endpoint
    bindingId - A String identifier of a binding.
    endpointAddress - Address of the target service endpoint as a URI
    Throws:
    WebServiceException - If any error in the creation of the port
    See Also:
    SOAPBinding.SOAP11HTTP_BINDING, SOAPBinding.SOAP12HTTP_BINDING, HTTPBinding.HTTP_BINDING

    createDispatch

    public <T> Dispatch<T> createDispatch(QName portName,
                                      Class<T> type,
                                      Service.Mode mode)
    Creates a Dispatch instance for use with objects of the users choosing.

    Parameters:
    portName - Qualified name for the target service endpoint
    type - The class of object used to messages or message payloads. Implementations are required to support javax.xml.transform.Source, javax.xml.soap.SOAPMessage and javax.activation.DataSource, depending on the binding in use.
    mode - Controls whether the created dispatch instance is message or payload oriented, i.e. whether the user will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the user will work with SOAP messages or the contents of a SOAP body. Mode must be MESSAGE when type is SOAPMessage.
    Returns:
    Dispatch instance
    Throws:
    WebServiceException - If any error in the creation of the Dispatch object
    See Also:
    Source, SOAPMessage

    createDispatch

    public Dispatch<Object> createDispatch(QName portName,
                                       JAXBContext context,
                                       Service.Mode mode)
    Creates a Dispatch instance for use with JAXB generated objects.

    Parameters:
    portName - Qualified name for the target service endpoint
    context - The JAXB context used to marshall and unmarshall messages or message payloads.
    mode - Controls whether the created dispatch instance is message or payload oriented, i.e. whether the user will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the user will work with SOAP messages or the contents of a SOAP body.
    Returns:
    Dispatch instance
    Throws:
    ServiceException - If any error in the creation of the Dispatch object
    See Also:
    JAXBContext

    getServiceName

    public QName getServiceName()
    Gets the name of this service.

    Returns:
    Qualified name of this service

    getPorts

    public Iterator<QName> getPorts()
    Returns an Iterator for the list of QNames of service endpoints grouped by this service

    Returns:
    Returns java.util.Iterator with elements of type javax.xml.namespace.QName
    Throws:
    WebServiceException - If this Service class does not have access to the required WSDL metadata

    getWSDLDocumentLocation

    public URL getWSDLDocumentLocation()
    Gets the location of the WSDL document for this Service.

    Returns:
    URL for the location of the WSDL document for this service

    getHandlerResolver

    public HandlerResolver getHandlerResolver()
    Returns the configured handler resolver.

    Returns:
    HandlerResolver The HandlerResolver being used by this Service instance, or null if there isn't one.

    setHandlerResolver

    public void setHandlerResolver(HandlerResolver handlerResolver)
    Sets the HandlerResolver for this Service instance.

    The handler resolver, if present, will be called once for each proxy or dispatch instance that is created, and the handler chain returned by the resolver will be set on the instance.

    Parameters:
    handlerResolver - The HandlerResolver to use for all subsequently created proxy/dispatch objects.
    See Also:
    HandlerResolver

    getExecutor

    public Executor getExecutor()
    Returns the executor for this Serviceinstance. The executor is used for all asynchronous invocations that require callbacks.

    Returns:
    The java.util.concurrent.Executor to be used to invoke a callback.
    See Also:
    Executor

    setExecutor

    public void setExecutor(Executor executor)
    Sets the executor for this Service instance. The executor is used for all asynchronous invocations that require callbacks.

    Parameters:
    executor - The java.util.concurrent.Executor to be used to invoke a callback.
    Throws:
    SecurityException - If the instance does not support setting an executor for security reasons (e.g. the necessary permissions are missing).
    See Also:
    Executor

    create

    public static Service create(URL wsdlDocumentLocation,
                             QName serviceName)
    Create a Service instance. The specified WSDL document location and service qualified name must uniquely identify a wsdl:service element.

    Parameters:
    wsdlDocumentLocation - URL for the WSDL document location for the service
    serviceName - QName for the service
    Throws:
    WebServiceException - If any error in creation of the specified service

    create

    public static Service create(QName serviceName)
    Create a Service instance.

    Parameters:
    serviceName - QName for the service
    Throws:
    WebServiceException - If any error in creation of the specified service
    Overview Package Class Use Tree Deprecated Index Help
            Java™ Platform
    Standard Ed. 6
    PREV CLASS NEXT CLASS FRAMES NO FRAMES
    SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Service.Mode

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

javax.xml.ws
Enum Service.Mode

java.lang.Object
    extended by  java.lang.Enum<Service.Mode>
        extended by  javax.xml.ws.Service.Mode
All Implemented Interfaces:
Serializable, Comparable<Service.Mode>
Enclosing class:
Service
public static enum Service.Mode
extends Enum<Service.Mode>

The orientation of a dynamic client or service. MESSAGE provides access to entire protocol message, PAYLOAD to protocol message payload only.

Enum Constant Summary
MESSAGE
PAYLOAD
Method Summary
static Service.Mode | valueOf(String name) Returns the enum constant of this type with the specified name.
static Service.Mode[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

MESSAGE

public static final Service.Mode MESSAGE

PAYLOAD

public static final Service.Mode PAYLOAD
Method Detail

values

public static Service.Mode[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (Service.Mode c : Service.Mode.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static Service.Mode valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


ServiceMode

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.ws
Annotation Type ServiceMode

@Target(value=TYPE)
@Retention(value=RUNTIME)
@Inherited
@Documented
public @interface ServiceMode

Used to indicate whether a Provider implementation wishes to work with entire protocol messages or just with protocol message payloads.

Since:
JAX-WS 2.0

Optional Element Summary
 Service.Mode value
Service mode.

value

public abstract Service.Mode value
Service mode. PAYLOAD indicates that the Provider implementation wishes to work with protocol message payloads only. MESSAGE indicates that the Provider implementation wishes to work with entire protocol messages.

Default:
javax.xml.ws.Service.Mode.PAYLOAD
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


soap

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.ws.soap

This package defines APIs specific to the SOAP binding.

See:
Description

Interface Summary
SOAPBinding The SOAPBinding interface is an abstraction for the SOAP binding.

Exception Summary
SOAPFaultException The SOAPFaultException exception represents a SOAP 1.1 or 1.2 fault.

Package javax.xml.ws.soap Description

This package defines APIs specific to the SOAP binding.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.ws.soap Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.ws.soap

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.lang.RuntimeException
          • javax.xml.ws.WebServiceException
            • javax.xml.ws.ProtocolException
              • javax.xml.ws.soap.SOAPFaultException

Interface Hierarchy

  • javax.xml.ws.Binding
    • javax.xml.ws.soap.SOAPBinding
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.ws.soap

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.ws.soap

No usage of javax.xml.ws.soap

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.soap.SOAPFaultException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.soap.SOAPFaultException

No usage of javax.xml.ws.soap.SOAPFaultException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.ws.soap.SOAPBinding

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.ws.soap.SOAPBinding

No usage of javax.xml.ws.soap.SOAPBinding

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


SOAPBinding

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws.soap
Interface SOAPBinding

All Superinterfaces:
Binding
public interface SOAPBinding
extends Binding

The SOAPBinding interface is an abstraction for the SOAP binding.

Since:
JAX-WS 2.0

Field Summary
static String | SOAP11HTTP_BINDING A constant representing the identity of the SOAP 1.1 over HTTP binding.
static String | SOAP11HTTP_MTOM_BINDING A constant representing the identity of the SOAP 1.1 over HTTP binding with MTOM enabled by default.
static String | SOAP12HTTP_BINDING A constant representing the identity of the SOAP 1.2 over HTTP binding.
static String | SOAP12HTTP_MTOM_BINDING A constant representing the identity of the SOAP 1.2 over HTTP binding with MTOM enabled by default.
Method Summary
MessageFactory | getMessageFactory() Gets the SAAJ MessageFactory instance used by this SOAP binding.
Set<String> | getRoles() Gets the roles played by the SOAP binding instance.
SOAPFactory | getSOAPFactory() Gets the SAAJ SOAPFactory instance used by this SOAP binding.
boolean | isMTOMEnabled() Returns true if the use of MTOM is enabled.
void | setMTOMEnabled(boolean flag) Enables or disables use of MTOM.
void | setRoles(Set<String> roles) Sets the roles played by the SOAP binding instance.
Methods inherited from interface javax.xml.ws.Binding
getHandlerChain, setHandlerChain

Field Detail

SOAP11HTTP_BINDING

static final String SOAP11HTTP_BINDING
A constant representing the identity of the SOAP 1.1 over HTTP binding.

See Also:
Constant Field Values

SOAP12HTTP_BINDING

static final String SOAP12HTTP_BINDING
A constant representing the identity of the SOAP 1.2 over HTTP binding.

See Also:
Constant Field Values

SOAP11HTTP_MTOM_BINDING

static final String SOAP11HTTP_MTOM_BINDING
A constant representing the identity of the SOAP 1.1 over HTTP binding with MTOM enabled by default.

See Also:
Constant Field Values

SOAP12HTTP_MTOM_BINDING

static final String SOAP12HTTP_MTOM_BINDING
A constant representing the identity of the SOAP 1.2 over HTTP binding with MTOM enabled by default.

See Also:
Constant Field Values
Method Detail

getRoles

Set<String> getRoles()
Gets the roles played by the SOAP binding instance.

Returns:
Set The set of roles played by the binding instance.

setRoles

void setRoles(Set<String> roles)
Sets the roles played by the SOAP binding instance.

Parameters:
roles - The set of roles played by the binding instance.
Throws:
WebServiceException - On an error in the configuration of the list of roles.

isMTOMEnabled

boolean isMTOMEnabled()
Returns true if the use of MTOM is enabled.

Returns:
true if and only if the use of MTOM is enabled.

setMTOMEnabled

void setMTOMEnabled(boolean flag)
Enables or disables use of MTOM.

Parameters:
flag - A boolean specifying whether the use of MTOM should be enabled or disabled.
Throws:
WebServiceException - If the specified setting is not supported by this binding instance.

getSOAPFactory

SOAPFactory getSOAPFactory()
Gets the SAAJ SOAPFactory instance used by this SOAP binding.

Returns:
SOAPFactory instance used by this SOAP binding.

getMessageFactory

MessageFactory getMessageFactory()
Gets the SAAJ MessageFactory instance used by this SOAP binding.

Returns:
MessageFactory instance used by this SOAP binding.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


SOAPFaultException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws.soap
Class SOAPFaultException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  javax.xml.ws.WebServiceException
                    extended by  javax.xml.ws.ProtocolException
                        extended by  javax.xml.ws.soap.SOAPFaultException
All Implemented Interfaces:
Serializable
public class SOAPFaultException
extends ProtocolException

The SOAPFaultException exception represents a SOAP 1.1 or 1.2 fault.

A SOAPFaultException wraps a SAAJ SOAPFault that manages the SOAP-specific representation of faults. The createFault method of javax.xml.soap.SOAPFactory may be used to create an instance of javax.xml.soap.SOAPFault for use with the constructor. SOAPBinding contains an accessor for the SOAPFactory used by the binding instance.

Note that the value of getFault is the only part of the exception used when searializing a SOAP fault.

Refer to the SOAP specification for a complete description of SOAP faults.

Since:
JAX-WS 2.0
See Also:
SOAPFault, SOAPBinding.getSOAPFactory(), ProtocolException, Serialized Form

Constructor Summary
SOAPFaultException(SOAPFault fault)
Constructor for SOAPFaultException
Method Summary
 SOAPFault getFault()
Gets the embedded SOAPFault instance.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SOAPFaultException

public SOAPFaultException(SOAPFault fault)
Constructor for SOAPFaultException

Parameters:
fault - SOAPFault representing the fault
See Also:
SOAPFactory.createFault(java.lang.String, javax.xml.namespace.QName)
Method Detail

getFault

public SOAPFault getFault()
Gets the embedded SOAPFault instance.

Returns:
javax.xml.soap.SOAPFault SOAP fault element
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


spi

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.ws.spi

This package defines SPIs for JAX-WS 2.0.

See:
Description

Class Summary
Provider | Service provider for ServiceDelegate and Endpoint objects.
ServiceDelegate | Service delegates are used internally by Service objects to allow pluggability of JAX-WS implementations.

Package javax.xml.ws.spi Description

This package defines SPIs for JAX-WS 2.0.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.ws.spi Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.ws.spi

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • javax.xml.ws.spi.Provider
    • javax.xml.ws.spi.ServiceDelegate
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.ws.spi

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.ws.spi

Packages that use javax.xml.ws.spi
javax.xml.ws.spi This package defines SPIs for JAX-WS 2.0.

Classes in javax.xml.ws.spi used by javax.xml.ws.spi
Provider
Service provider for ServiceDelegate and Endpoint objects.
ServiceDelegate
Service delegates are used internally by Service objects to allow pluggability of JAX-WS implementations.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.spi.Provider

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.spi.Provider

Packages that use Provider
javax.xml.ws.spi This package defines SPIs for JAX-WS 2.0.

Uses of Provider in javax.xml.ws.spi

Methods in javax.xml.ws.spi that return Provider
static Provider Provider.provider()
Creates a new provider object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.ws.spi.ServiceDelegate

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.ws.spi.ServiceDelegate

Packages that use ServiceDelegate
javax.xml.ws.spi This package defines SPIs for JAX-WS 2.0.

Uses of ServiceDelegate in javax.xml.ws.spi

Methods in javax.xml.ws.spi that return ServiceDelegate
abstract  ServiceDelegate Provider.createServiceDelegate(URL wsdlDocumentLocation, QName serviceName, Class serviceClass)
Creates a service delegate object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Provider

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws.spi
Class Provider

java.lang.Object
    extended by  javax.xml.ws.spi.Provider

public abstract class Provider
extends Object

Service provider for ServiceDelegate and Endpoint objects.

Since:
JAX-WS 2.0

Field Summary
static String JAXWSPROVIDER_PROPERTY
A constant representing the property used to lookup the name of a Provider implementation class.
Constructor Summary
protected Provider()
Creates a new instance of Provider
Method Summary
abstract Endpoint | createAndPublishEndpoint(String address, Object implementor) Creates and publishes an endpoint object with the specified address and implementation object.
abstract Endpoint | createEndpoint(String bindingId, Object implementor) Creates an endpoint object with the provided binding and implementation object.
abstract ServiceDelegate | createServiceDelegate(URL wsdlDocumentLocation, QName serviceName, Class serviceClass) Creates a service delegate object.
static Provider | provider() Creates a new provider object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

JAXWSPROVIDER_PROPERTY

public static final String JAXWSPROVIDER_PROPERTY
A constant representing the property used to lookup the name of a Provider implementation class.

See Also:
Constant Field Values
Constructor Detail

Provider

protected Provider()
Creates a new instance of Provider

Method Detail

provider

public static Provider provider()
Creates a new provider object.

The algorithm used to locate the provider subclass to use consists of the following steps:

  • If a resource with the name of META-INF/services/javax.xml.ws.spi.Provider exists, then its first line, if present, is used as the UTF-8 encoded name of the implementation class.
  • If the $java.home/lib/jaxws.properties file exists and it is readable by the java.util.Properties.load(InputStream) method and it contains an entry whose key is javax.xml.ws.spi.Provider, then the value of that entry is used as the name of the implementation class.
  • If a system property with the name javax.xml.ws.spi.Provider is defined, then its value is used as the name of the implementation class.
  • Finally, a default implementation class name is used.

createServiceDelegate

public abstract ServiceDelegate createServiceDelegate(URL wsdlDocumentLocation,
                                                      QName serviceName,
                                                      Class serviceClass)
Creates a service delegate object.

Parameters:
wsdlDocumentLocation - A URL pointing to the WSDL document for the service, or null if there isn't one.
serviceName - The qualified name of the service.
serviceClass - The service class, which must be either javax.xml.ws.Service or a subclass thereof.
Returns:
The newly created service delegate.

createEndpoint

public abstract Endpoint createEndpoint(String bindingId,
                                        Object implementor)
Creates an endpoint object with the provided binding and implementation object.

Parameters:
bindingId - A URI specifying the desired binding (e.g. SOAP/HTTP)
implementor - A service implementation object to which incoming requests will be dispatched. The corresponding class must be annotated with all the necessary Web service annotations.
Returns:
The newly created endpoint.

createAndPublishEndpoint

public abstract Endpoint createAndPublishEndpoint(String address,
                                                  Object implementor)
Creates and publishes an endpoint object with the specified address and implementation object.

Parameters:
address - A URI specifying the address and transport/protocol to use. A http: URI must result in the SOAP 1.1/HTTP binding being used. Implementations may support other URI schemes.
implementor - A service implementation object to which incoming requests will be dispatched. The corresponding class must be annotated with all the necessary Web service annotations.
Returns:
The newly created endpoint.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


ServiceDelegate

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws.spi
Class ServiceDelegate

java.lang.Object
    extended by  javax.xml.ws.spi.ServiceDelegate

public abstract class ServiceDelegate
extends Object

Service delegates are used internally by Service objects to allow pluggability of JAX-WS implementations.

Every Service object has its own delegate, created using the javax.xml.ws.Provider#createServiceDelegate method. A Service object delegates all of its instance methods to its delegate.

Since:
JAX-WS 2.0
See Also:
Service, Provider

Constructor Summary
protected ServiceDelegate()
Method Summary
abstract  void addPort(QName portName, String bindingId, String endpointAddress)
Creates a new port for the service.
abstract
<T> Dispatch<T>
createDispatch(QName portName, Class<T> type, Service.Mode mode)
Creates a Dispatch instance for use with objects of the users choosing.
abstract  Dispatch<Object> createDispatch(QName portName, JAXBContext context, Service.Mode mode)
Creates a Dispatch instance for use with JAXB generated objects.
abstract  Executor getExecutor()
Returns the executor for this Serviceinstance.
abstract  HandlerResolver getHandlerResolver()
Returns the configured handler resolver.
abstract
<T> T
getPort(Class<T> serviceEndpointInterface)
The getPort method returns a stub.
abstract
<T> T
getPort(QName portName, Class<T> serviceEndpointInterface)
The getPort method returns a stub.
abstract  Iterator<QName> getPorts()
Returns an Iterator for the list of QNames of service endpoints grouped by this service
abstract  QName getServiceName()
Gets the name of this service.
abstract  URL getWSDLDocumentLocation()
Gets the location of the WSDL document for this Service.
abstract  void setExecutor(Executor executor)
Sets the executor for this Service instance.
abstract  void setHandlerResolver(HandlerResolver handlerResolver)
Sets the HandlerResolver for this Service instance.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServiceDelegate

protected ServiceDelegate()
Method Detail

getPort

public abstract <T> T getPort(QName portName,
                              Class<T> serviceEndpointInterface)
The getPort method returns a stub. A service client uses this stub to invoke operations on the target service endpoint. The serviceEndpointInterface specifies the service endpoint interface that is supported by the created dynamic proxy or stub instance.

Parameters:
portName - Qualified name of the service endpoint in the WSDL service description
serviceEndpointInterface - Service endpoint interface supported by the dynamic proxy or stub instance
Returns:
Object Proxy instance that supports the specified service endpoint interface
Throws:
WebServiceException - This exception is thrown in the following cases:
  • If there is an error in creation of the proxy
  • If there is any missing WSDL metadata as required by this method
  • Optionally, if an illegal serviceEndpointInterface or portName is specified
See Also:
Proxy, InvocationHandler

getPort

public abstract <T> T getPort(Class<T> serviceEndpointInterface)
The getPort method returns a stub. The parameter serviceEndpointInterface specifies the service endpoint interface that is supported by the returned proxy. In the implementation of this method, the JAX-WS runtime system takes the responsibility of selecting a protocol binding (and a port) and configuring the proxy accordingly. The returned proxy should not be reconfigured by the client.

Parameters:
serviceEndpointInterface - Service endpoint interface
Returns:
Object instance that supports the specified service endpoint interface
Throws:
WebServiceException -
  • If there is an error during creation of the proxy
  • If there is any missing WSDL metadata as required by this method
  • Optionally, if an illegal serviceEndpointInterface is specified

addPort

public abstract void addPort(QName portName,
                             String bindingId,
                             String endpointAddress)
Creates a new port for the service. Ports created in this way contain no WSDL port type information and can only be used for creating Dispatchinstances.

Parameters:
portName - Qualified name for the target service endpoint
bindingId - A URI identifier of a binding.
endpointAddress - Address of the target service endpoint as a URI
Throws:
WebServiceException - If any error in the creation of the port
See Also:
SOAPBinding.SOAP11HTTP_BINDING, SOAPBinding.SOAP12HTTP_BINDING, HTTPBinding.HTTP_BINDING

createDispatch

public abstract <T> Dispatch<T> createDispatch(QName portName,
                                               Class<T> type,
                                               Service.Mode mode)
Creates a Dispatch instance for use with objects of the users choosing.

Parameters:
portName - Qualified name for the target service endpoint
type - The class of object used to messages or message payloads. Implementations are required to support javax.xml.transform.Source and javax.xml.soap.SOAPMessage.
mode - Controls whether the created dispatch instance is message or payload oriented, i.e. whether the user will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the user will work with SOAP messages or the contents of a SOAP body. Mode must be MESSAGE when type is SOAPMessage.
Returns:
Dispatch instance
Throws:
WebServiceException - If any error in the creation of the Dispatch object
See Also:
Source, SOAPMessage

createDispatch

public abstract Dispatch<Object> createDispatch(QName portName,
                                                JAXBContext context,
                                                Service.Mode mode)
Creates a Dispatch instance for use with JAXB generated objects.

Parameters:
portName - Qualified name for the target service endpoint
context - The JAXB context used to marshall and unmarshall messages or message payloads.
mode - Controls whether the created dispatch instance is message or payload oriented, i.e. whether the user will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the user will work with SOAP messages or the contents of a SOAP body.
Returns:
Dispatch instance
Throws:
ServiceException - If any error in the creation of the Dispatch object
See Also:
JAXBContext

getServiceName

public abstract QName getServiceName()
Gets the name of this service.

Returns:
Qualified name of this service

getPorts

public abstract Iterator<QName> getPorts()
Returns an Iterator for the list of QNames of service endpoints grouped by this service

Returns:
Returns java.util.Iterator with elements of type javax.xml.namespace.QName
Throws:
WebServiceException - If this Service class does not have access to the required WSDL metadata

getWSDLDocumentLocation

public abstract URL getWSDLDocumentLocation()
Gets the location of the WSDL document for this Service.

Returns:
URL for the location of the WSDL document for this service

getHandlerResolver

public abstract HandlerResolver getHandlerResolver()
Returns the configured handler resolver.

Returns:
HandlerResolver The HandlerResolver being used by this Service instance, or null if there isn't one.

setHandlerResolver

public abstract void setHandlerResolver(HandlerResolver handlerResolver)
Sets the HandlerResolver for this Service instance.

The handler resolver, if present, will be called once for each proxy or dispatch instance that is created, and the handler chain returned by the resolver will be set on the instance.

Parameters:
handlerResolver - The HandlerResolver to use for all subsequently created proxy/dispatch objects.
See Also:
HandlerResolver

getExecutor

public abstract Executor getExecutor()
Returns the executor for this Serviceinstance. The executor is used for all asynchronous invocations that require callbacks.

Returns:
The java.util.concurrent.Executor to be used to invoke a callback.
See Also:
Executor

setExecutor

public abstract void setExecutor(Executor executor)
Sets the executor for this Service instance. The executor is used for all asynchronous invocations that require callbacks.

Parameters:
executor - The java.util.concurrent.Executor to be used to invoke a callback.
Throws:
SecurityException - If the instance does not support setting an executor for security reasons (e.g. the necessary permissions are missing).
See Also:
Executor
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


WebEndpoint

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.ws
Annotation Type WebEndpoint

@Target(value=METHOD)
@Retention(value=RUNTIME)
@Documented
public @interface WebEndpoint

Used to annotate the getPortName() methods of a generated service interface.

The information specified in this annotation is sufficient to uniquely identify a wsdl:port element inside a wsdl:service. The latter is determined based on the value of the WebServiceClient annotation on the generated service interface itself.

Since:
JAX-WS 2.0
See Also:
WebServiceClient

Optional Element Summary
 String name
The local name of the endpoint.

name

public abstract String name
The local name of the endpoint.

Default:
""
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


WebFault

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.ws
Annotation Type WebFault

@Target(value=TYPE)
@Retention(value=RUNTIME)
@Documented
public @interface WebFault

Used to annotate service specific exception classes to customize to the local and namespace name of the fault element and the name of the fault bean.

Since:
JAX-WS 2.0

Optional Element Summary
String | faultBean Fault bean name.
String | name Elements local name.
String | targetNamespace Elements namespace name.

name

public abstract String name
Elements local name.

Default:
""

targetNamespace

public abstract String targetNamespace
Elements namespace name.

Default:
""

faultBean

public abstract String faultBean
Fault bean name.

Default:
""
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


WebServiceClient

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.ws
Annotation Type WebServiceClient

@Target(value=TYPE)
@Retention(value=RUNTIME)
@Documented
public @interface WebServiceClient

Used to annotate a generated service interface.

The information specified in this annotation is sufficient to uniquely identify a wsdl:service element inside a WSDL document. This wsdl:service element represents the Web service for which the generated service interface provides a client view.

Since:
JAX-WS 2.0

Optional Element Summary
String | name The local name of the Web service.
String | targetNamespace The namespace for the Web service.
String | wsdlLocation The location of the WSDL document for the service (a URL).

name

public abstract String name
The local name of the Web service.

Default:
""

targetNamespace

public abstract String targetNamespace
The namespace for the Web service.

Default:
""

wsdlLocation

public abstract String wsdlLocation
The location of the WSDL document for the service (a URL).

Default:
""
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


WebServiceContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws
Interface WebServiceContext

public interface WebServiceContext

A WebServiceContext makes it possible for a web service endpoint implementation class to access message context and security information relative to a request being served. Typically a WebServiceContext is injected into an endpoint implementation class using the Resource annotation.

Since:
JAX-WS 2.0
See Also:
Resource

Method Summary
MessageContext | getMessageContext() Returns the MessageContext for the request being served at the time this method is called.
Principal | getUserPrincipal() Returns the Principal that identifies the sender of the request currently being serviced.
boolean | isUserInRole(String role) Returns a boolean indicating whether the authenticated user is included in the specified logical role.

Method Detail

getMessageContext

MessageContext getMessageContext()
Returns the MessageContext for the request being served at the time this method is called. Only properties with APPLICATION scope will be visible to the application.

Returns:
MessageContext The message context.
Throws:
IllegalStateException - This exception is thrown if the method is called while no request is being serviced.
See Also:
MessageContext, MessageContext.Scope, IllegalStateException

getUserPrincipal

Principal getUserPrincipal()
Returns the Principal that identifies the sender of the request currently being serviced. If the sender has not been authenticated, the method returns null.

Returns:
Principal The principal object.
Throws:
IllegalStateException - This exception is thrown if the method is called while no request is being serviced.
See Also:
Principal, IllegalStateException

isUserInRole

boolean isUserInRole(String role)
Returns a boolean indicating whether the authenticated user is included in the specified logical role. If the user has not been authenticated, the method returns false.

Parameters:
role - A String specifying the name of the role
Returns:
a boolean indicating whether the sender of the request belongs to a given role
Throws:
IllegalStateException - This exception is thrown if the method is called while no request is being serviced.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WebServiceException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws
Class WebServiceException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  javax.xml.ws.WebServiceException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
ProtocolException
public class WebServiceException
extends RuntimeException

The WebServiceException class is the base exception class for all JAX-WS API runtime exceptions.

Since:
JAX-WS 2.0
See Also:
Serialized Form

Constructor Summary
WebServiceException()
Constructs a new exception with null as its detail message.
WebServiceException(String message)
Constructs a new exception with the specified detail message.
WebServiceException(String message, Throwable cause)
Constructs a new exception with the specified detail message and cause.
WebServiceException(Throwable cause)
Constructs a new WebServiceException with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

WebServiceException

public WebServiceException()
Constructs a new exception with null as its detail message. The cause is not initialized.

WebServiceException

public WebServiceException(String message)
Constructs a new exception with the specified detail message. The cause is not initialized.

Parameters:
message - The detail message which is later retrieved using the getMessage method

WebServiceException

public WebServiceException(String message,
                           Throwable cause)
Constructs a new exception with the specified detail message and cause.

Parameters:
message - The detail message which is later retrieved using the getMessage method
cause - The cause which is saved for the later retrieval throw by the getCause method

WebServiceException

public WebServiceException(Throwable cause)
Constructs a new WebServiceException with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).

Parameters:
cause - The cause which is saved for the later retrieval throw by the getCause method. (A null value is permitted, and indicates that the cause is nonexistent or unknown.)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WebServicePermission

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.ws
Class WebServicePermission

java.lang.Object
    extended by  java.security.Permission
        extended by  java.security.BasicPermission
            extended by  javax.xml.ws.WebServicePermission
All Implemented Interfaces:
Serializable, Guard
public final class WebServicePermission
extends BasicPermission

This class defines web service permissions.

Web service Permissions are identified by name (also referred to as a "target name") alone. There are no actions associated with them.

The following permission target name is defined:

publishEndpoint

The publishEndpoint permission allows publishing a web service endpoint using the publish methods defined by the javax.xml.ws.Endpoint class.

See Also:
Endpoint, BasicPermission, Permission, Permissions, SecurityManager, Serialized Form

Constructor Summary
WebServicePermission(String name)
Creates a new permission with the specified name.
WebServicePermission(String name, String actions)
Creates a new permission with the specified name and actions.
Method Summary
Methods inherited from class java.security.BasicPermission
equals, getActions, hashCode, implies, newPermissionCollection
Methods inherited from class java.security.Permission
checkGuard, getName, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

WebServicePermission

public WebServicePermission(String name)
Creates a new permission with the specified name.

Parameters:
name - the name of the WebServicePermission

WebServicePermission

public WebServicePermission(String name,
                            String actions)
Creates a new permission with the specified name and actions. The actions parameter is currently unused and it should be null.

Parameters:
name - the name of the WebServicePermission
actions - should be null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WebServiceProvider

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.ws
Annotation Type WebServiceProvider

@Target(value=TYPE)
@Retention(value=RUNTIME)
@Documented
public @interface WebServiceProvider

Used to annotate a Provider implementation class.

Since:
JAX-WS 2.0
See Also:
Provider

Optional Element Summary
String | portName Port name.
String | serviceName Service name.
String | targetNamespace Target namespace for the service
String | wsdlLocation Location of the WSDL description for the service.

wsdlLocation

public abstract String wsdlLocation
Location of the WSDL description for the service.

Default:
""

serviceName

public abstract String serviceName
Service name.

Default:
""

targetNamespace

public abstract String targetNamespace
Target namespace for the service

Default:
""

portName

public abstract String portName
Port name.

Default:
""
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


WebServiceRef

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT

javax.xml.ws
Annotation Type WebServiceRef

@Target(value={TYPE,METHOD,FIELD})
@Retention(value=RUNTIME)
@Documented
public @interface WebServiceRef

The WebServiceRef annotation is used to define a reference to a web service and (optionally) an injection target for it. Web service references are resources in the Java EE 5 sense.

Since:
JAX-WS 2.0
See Also:
Resource

Optional Element Summary
String | mappedName A product specific name that this resource should be mapped to.
String | name The JNDI name of the resource.
Class | type The Java type of the resource.
Class | value The service class, always a type extending javax.xml.ws.Service.
String | wsdlLocation A URL pointing to the WSDL document for the web service.

name

public abstract String name
The JNDI name of the resource. For field annotations, the default is the field name. For method annotations, the default is the JavaBeans property name corresponding to the method. For class annotations, there is no default and this must be specified.

Default:
""

type

public abstract Class type
The Java type of the resource. For field annotations, the default is the type of the field. For method annotations, the default is the type of the JavaBeans property. For class annotations, there is no default and this must be specified.

Default:
java.lang.Object.class

mappedName

public abstract String mappedName
A product specific name that this resource should be mapped to. The name of this resource, as defined by the name element or defaulted, is a name that is local to the application component using the resource. (It's a name in the JNDI java:comp/env namespace.) Many application servers provide a way to map these local names to names of resources known to the application server. This mapped name is often a global JNDI name, but may be a name of any form.

Application servers are not required to support any particular form or type of mapped name, nor the ability to use mapped names. The mapped name is product-dependent and often installation-dependent. No use of a mapped name is portable.

Default:
""

value

public abstract Class value
The service class, always a type extending javax.xml.ws.Service. This element must be specified whenever the type of the reference is a service endpoint interface.

Default:
java.lang.Object.class

wsdlLocation

public abstract String wsdlLocation
A URL pointing to the WSDL document for the web service. If not specified, the WSDL location specified by annotations on the resource type is used instead.

Default:
""
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL DETAIL: ELEMENT


WebServiceRefs

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL | DETAIL: ELEMENT

javax.xml.ws
Annotation Type WebServiceRefs

@Documented
@Retention(value=RUNTIME)
@Target(value=TYPE)
public @interface WebServiceRefs

The WebServiceRefs annotation allows multiple web service references to be declared at the class level.

Since:
2.0
See Also:
WebServiceRef

Required Element Summary
 WebServiceRef[] value
Array used for multiple web service reference declarations.

Element Detail

value

public abstract WebServiceRef[] value
Array used for multiple web service reference declarations.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: REQUIRED | OPTIONAL | DETAIL: ELEMENT


XMLConstants

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml
Class XMLConstants

java.lang.Object
    extended by  javax.xml.XMLConstants

public final class XMLConstants
extends Object

Utility class to contain basic XML values as constants.

Since:
1.5
See Also:
Extensible Markup Language (XML) 1.1, Extensible Markup Language (XML) 1.0 (Second Edition), XML 1.0 Second Edition Specification Errata, Namespaces in XML 1.1, Namespaces in XML, Namespaces in XML Errata, XML Schema Part 1: Structures

Field Summary
static String | DEFAULT_NS_PREFIX Prefix to use to represent the default XML Namespace.
static String | FEATURE_SECURE_PROCESSING Feature for secure processing.
static String | NULL_NS_URI Namespace URI to use to represent that there is no Namespace.
static String | RELAXNG_NS_URI RELAX NG Namespace URI.
static String | W3C_XML_SCHEMA_INSTANCE_NS_URI W3C XML Schema Instance Namespace URI.
static String | W3C_XML_SCHEMA_NS_URI W3C XML Schema Namespace URI.
static String | W3C_XPATH_DATATYPE_NS_URI W3C XPath Datatype Namespace URI.
static String | XML_DTD_NS_URI XML Document Type Declaration Namespace URI as an arbitrary value.
static String | XML_NS_PREFIX The official XML Namespace prefix.
static String | XML_NS_URI The official XML Namespace name URI.
static String | XMLNS_ATTRIBUTE The official XML attribute used for specifying XML Namespace declarations.
static String | XMLNS_ATTRIBUTE_NS_URI The official XML attribute used for specifying XML Namespace declarations, XMLConstants.XMLNS_ATTRIBUTE, Namespace name URI.
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NULL_NS_URI

public static final String NULL_NS_URI

Namespace URI to use to represent that there is no Namespace.

Defined by the Namespace specification to be "".

See Also:
Namespaces in XML, 5.2 Namespace Defaulting, Constant Field Values

DEFAULT_NS_PREFIX

public static final String DEFAULT_NS_PREFIX

Prefix to use to represent the default XML Namespace.

Defined by the XML specification to be "".

See Also:
Namespaces in XML, 3. Qualified Names, Constant Field Values

XML_NS_URI

public static final String XML_NS_URI

The official XML Namespace name URI.

Defined by the XML specification to be "http://www.w3.org/XML/1998/namespace".

See Also:
Namespaces in XML, 3. Qualified Names, Constant Field Values

XML_NS_PREFIX

public static final String XML_NS_PREFIX

The official XML Namespace prefix.

Defined by the XML specification to be "xml".

See Also:
Namespaces in XML, 3. Qualified Names<</a>, Constant Field Values

XMLNS_ATTRIBUTE_NS_URI

public static final String XMLNS_ATTRIBUTE_NS_URI

The official XML attribute used for specifying XML Namespace declarations, XMLConstants.XMLNS_ATTRIBUTE, Namespace name URI.

Defined by the XML specification to be "http://www.w3.org/2000/xmlns/".

See Also:
Namespaces in XML, 3. Qualified Names, Namespaces in XML Errata, Constant Field Values

XMLNS_ATTRIBUTE

public static final String XMLNS_ATTRIBUTE

The official XML attribute used for specifying XML Namespace declarations.

It is NOT valid to use as a prefix. Defined by the XML specification to be "xmlns".

See Also:
Namespaces in XML, 3. Qualified Names, Constant Field Values

W3C_XML_SCHEMA_NS_URI

public static final String W3C_XML_SCHEMA_NS_URI

W3C XML Schema Namespace URI.

Defined to be "http://www.w3.org/2001/XMLSchema".

See Also:
XML Schema Part 1: Structures, 2.6 Schema-Related Markup in Documents Being Validated, Constant Field Values

W3C_XML_SCHEMA_INSTANCE_NS_URI

public static final String W3C_XML_SCHEMA_INSTANCE_NS_URI

W3C XML Schema Instance Namespace URI.

Defined to be "http://www.w3.org/2001/XMLSchema-instance".

See Also:
XML Schema Part 1: Structures, 2.6 Schema-Related Markup in Documents Being Validated, Constant Field Values

W3C_XPATH_DATATYPE_NS_URI

public static final String W3C_XPATH_DATATYPE_NS_URI

W3C XPath Datatype Namespace URI.

Defined to be "http://www.w3.org/2003/11/xpath-datatypes".

See Also:
XQuery 1.0 and XPath 2.0 Data Model, Constant Field Values

XML_DTD_NS_URI

public static final String XML_DTD_NS_URI

XML Document Type Declaration Namespace URI as an arbitrary value.

Since not formally defined by any existing standard, arbitrarily define to be "http://www.w3.org/TR/REC-xml".

See Also:
Constant Field Values

RELAXNG_NS_URI

public static final String RELAXNG_NS_URI

RELAX NG Namespace URI.

Defined to be "http://relaxng.org/ns/structure/1.0".

See Also:
RELAX NG Specification, Constant Field Values

FEATURE_SECURE_PROCESSING

public static final String FEATURE_SECURE_PROCESSING

Feature for secure processing.

  • true instructs the implementation to process XML securely. This may set limits on XML constructs to avoid conditions such as denial of service attacks.
  • false instructs the implementation to process XML acording the letter of the XML specifications ingoring security issues such as limits on XML constructs to avoid conditions such as denial of service attacks.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


xpath

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package javax.xml.xpath

This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.

See:
Description

Interface Summary
XPath | XPath provides access to the XPath evaluation environment and expressions.
XPathExpression | XPathExpression provides access to compiled XPath expressions.
XPathFunction | XPathFunction provides access to XPath functions.
XPathFunctionResolver | XPathFunctionResolver provides access to the set of user defined XPathFunctions.
XPathVariableResolver | XPathVariableResolver provides access to the set of user defined XPath variables.

Class Summary
XPathConstants | XPath constants.
XPathFactory | An XPathFactory instance can be used to create XPath objects.

Exception Summary
XPathException | XPathException represents a generic XPath exception.
XPathExpressionException | XPathExpressionException represents an error in an XPath expression.
XPathFactoryConfigurationException | XPathFactoryConfigurationException represents a configuration error in a XPathFactory environment.
XPathFunctionException | XPathFunctionException represents an error with an XPath function.

Package javax.xml.xpath Description

This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.

The following XML standards apply:

  • XML Path Language (XPath) Version 1.0

XPath Overview

The XPath language provides a simple, concise syntax for selecting nodes from an XML document. XPath also provides rules for converting a node in an XML document object model (DOM) tree to a boolean, double, or string value. XPath is a W3C-defined language and an official W3C recommendation; the W3C hosts the XML Path Language (XPath) Version 1.0 specification.

XPath started in life in 1999 as a supplement to the XSLT and XPointer languages, but has more recently become popular as a stand-alone language, as a single XPath expression can be used to replace many lines of DOM API code.

XPath Expressions

An XPath expression is composed of a location path and one or more optional predicates. Expressions may also include XPath variables.

The following is an example of a simple XPath expression:

/foo/bar

This example would select the <bar> element in an XML document such as the following:

<foo>
<bar/>
</foo>

The expression /foo/bar is an example of a location path. While XPath location paths resemble Unix-style file system paths, an important distinction is that XPath expressions return all nodes that match the expression. Thus, all three <bar> elements in the following document would be selected by the /foo/bar expression:

<foo>
<bar/>
<bar/>
<bar/>
</foo>

A special location path operator, //, selects nodes at any depth in an XML document. The following example selects all <bar> elements regardless of their location in a document:

//bar

A wildcard operator, *, causes all element nodes to be selected. The following example selects all children elements of a <foo> element:

/foo/*

In addition to element nodes, XPath location paths may also address attribute nodes, text nodes, comment nodes, and processing instruction nodes. The following table gives examples of location paths for each of these node types:

Location Path | Description
/foo/bar/@id | Selects the attribute id of the <bar> element
/foo/bar/text() | Selects the text nodes of the <bar> element. No distinction is made between escaped and non-escaped character data.
/foo/bar/comment() | Selects all comment nodes contained in the <bar> element.
/foo/bar/processing-instruction() | Selects all processing-instruction nodes contained in the <bar> element.

Predicates allow for refining the nodes selected by an XPath location path. Predicates are of the form [expression]. The following example selects all <foo> elements that contain an include attribute with the value of true:

//foo[@include='true']

Predicates may be appended to each other to further refine an expression, such as:

//foo[@include='true'][@mode='bar']

Using the XPath API

The following example demonstrates using the XPath API to select one or more nodes from an XML document:

XPath xpath = XPathFactory.newInstance().newXPath();
String expression = "/widgets/widget";
InputSource inputSource = new InputSource("widgets.xml");
NodeList nodes = (NodeList) xpath.evaluate(expression, inputSource, XPathConstants.NODESET);

XPath Expressions and Types

While XPath expressions select nodes in the XML document, the XPath API allows the selected nodes to be coalesced into one of the following other data types:

  • Boolean
  • Number
  • String

The desired return type is specified by a QName parameter in method call used to evaluate the expression, which is either a call to XPathExpression.evalute(...) or to one of the XPath.evaluate(...) convenience methods. The allowed QName values are specified as constants in the XPathConstants class; they are:

  • XPathConstants.NODESET
  • XPathConstants.NODE
  • XPathConstants.STRING
  • XPathConstants.BOOLEAN
  • XPathConstants.NUMBER

When a Boolean return type is requested, Boolean.TRUE is returned if one or more nodes were selected; otherwise, Boolean.FALSE is returned.

The String return type is a convenience for retrieving the character data from a text node, attribute node, comment node, or processing-instruction node. When used on an element node, the value of the child text nodes is returned.

The Number return type attempts to coalesce the text of a node to a double data type.

XPath Context

XPath location paths may be relative to a particular node in the document, known as the context. Consider the following XML document:

<widgets>
<widget>
<manufacturer/>
<dimensions/>
</widget>
</widgets>

The <widget> element can be selected with the following XPath API code:

// parse the XML as a W3C Document
DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
Document document = builder.parse(new File("/widgets.xml"));

XPath xpath = XPathFactory.newInstance().newXPath();
String expression = "/widgets/widget";
Node widgetNode = (Node) xpath.evaluate(expression, document, XPathConstants.NODE);

With a reference to the <widget> element, a relative XPath expression can now written to select the <manufacturer> child element:

XPath xpath = XPathFactory.newInstance().newXPath();
String expression = "manufacturer";
Node manufacturerNode = (Node) xpath.evaluate(expression, widgetNode, XPathConstants.NODE);
  • Author Ben Galbraith
  • Author Norman Walsh
  • Author Jeff Suttor
  • See XML Path Language (XPath) Version 1.0
  • Since 1.5

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


javax.xml.xpath Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package javax.xml.xpath

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • javax.xml.xpath.XPathException
          • javax.xml.xpath.XPathExpressionException
            • javax.xml.xpath.XPathFunctionException
          • javax.xml.xpath.XPathFactoryConfigurationException
    • javax.xml.xpath.XPathConstants
    • javax.xml.xpath.XPathFactory

Interface Hierarchy

  • javax.xml.xpath.XPath
  • javax.xml.xpath.XPathExpression
  • javax.xml.xpath.XPathFunction
  • javax.xml.xpath.XPathFunctionResolver
  • javax.xml.xpath.XPathVariableResolver
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package javax.xml.xpath

PREV NEXT FRAMES NO FRAMES

Uses of Package
javax.xml.xpath

Packages that use javax.xml.xpath
javax.xml.xpath This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.

Classes in javax.xml.xpath used by javax.xml.xpath
XPath
XPath provides access to the XPath evaluation environment and expressions.
XPathException
XPathException represents a generic XPath exception.
XPathExpression
XPathExpression provides access to compiled XPath expressions.
XPathExpressionException
XPathExpressionException represents an error in an XPath expression.
XPathFactory
An XPathFactory instance can be used to create XPath objects.
XPathFactoryConfigurationException
XPathFactoryConfigurationException represents a configuration error in a XPathFactory environment.
XPathFunction
XPathFunction provides access to XPath functions.
XPathFunctionException
XPathFunctionException represents an error with an XPath function.
XPathFunctionResolver
XPathFunctionResolver provides access to the set of user defined XPathFunctions.
XPathVariableResolver
XPathVariableResolver provides access to the set of user defined XPath variables.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.xpath.XPathConstants

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.xpath.XPathConstants

No usage of javax.xml.xpath.XPathConstants

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.xpath.XPathException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.xpath.XPathException

Packages that use XPathException
javax.xml.xpath This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.

Uses of XPathException in javax.xml.xpath

Subclasses of XPathException in javax.xml.xpath
class | XPathExpressionException XPathExpressionException represents an error in an XPath expression.
class | XPathFactoryConfigurationException XPathFactoryConfigurationException represents a configuration error in a XPathFactory environment.
class | XPathFunctionException XPathFunctionException represents an error with an XPath function.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.xpath.XPathExpressionException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.xpath.XPathExpressionException

Packages that use XPathExpressionException
javax.xml.xpath This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.

Uses of XPathExpressionException in javax.xml.xpath

Subclasses of XPathExpressionException in javax.xml.xpath
 class XPathFunctionException
XPathFunctionException represents an error with an XPath function.

Methods in javax.xml.xpath that throw XPathExpressionException
XPathExpression | XPath.compile(String expression) Compile an XPath expression for later evaluation.
String | XPathExpression.evaluate(InputSource source) Evaluate the compiled XPath expression in the context of the specified InputSource and return the result as a String.
Object | XPathExpression.evaluate(InputSource source, QName returnType) Evaluate the compiled XPath expression in the context of the specified InputSource and return the result as the specified type.
String | XPathExpression.evaluate(Object item) Evaluate the compiled XPath expression in the specified context and return the result as a String.
Object | XPathExpression.evaluate(Object item, QName returnType) Evaluate the compiled XPath expression in the specified context and return the result as the specified type.
String | XPath.evaluate(String expression, InputSource source) Evaluate an XPath expression in the context of the specified InputSource and return the result as a String.
Object | XPath.evaluate(String expression, InputSource source, QName returnType) Evaluate an XPath expression in the context of the specified InputSource and return the result as the specified type.
String | XPath.evaluate(String expression, Object item) Evaluate an XPath expression in the specified context and return the result as a String.
Object | XPath.evaluate(String expression, Object item, QName returnType) Evaluate an XPath expression in the specified context and return the result as the specified type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.xpath.XPathFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.xpath.XPathFactory

Packages that use XPathFactory
javax.xml.xpath This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.

Uses of XPathFactory in javax.xml.xpath

Methods in javax.xml.xpath that return XPathFactory
static XPathFactory | XPathFactory.newInstance() Get a new XPathFactory instance using the default object model, DEFAULT_OBJECT_MODEL_URI, the W3C DOM.
static XPathFactory | XPathFactory.newInstance(String uri) Get a new XPathFactory instance using the specified object model.
static XPathFactory | XPathFactory.newInstance(String uri, String factoryClassName, ClassLoader classLoader) Obtain a new instance of a XPathFactory from a factory class name.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.xpath.XPathFactoryConfigurationException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.xpath.XPathFactoryConfigurationException

Packages that use XPathFactoryConfigurationException
javax.xml.xpath This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.

Uses of XPathFactoryConfigurationException in javax.xml.xpath

Methods in javax.xml.xpath that throw XPathFactoryConfigurationException
abstract boolean | XPathFactory.getFeature(String name) Get the state of the named feature.
static XPathFactory | XPathFactory.newInstance(String uri) Get a new XPathFactory instance using the specified object model.
static XPathFactory | XPathFactory.newInstance(String uri, String factoryClassName, ClassLoader classLoader) Obtain a new instance of a XPathFactory from a factory class name.
abstract void | XPathFactory.setFeature(String name, boolean value) Set a feature for this XPathFactory and XPaths created by this factory.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class javax.xml.xpath.XPathFunctionException

PREV NEXT FRAMES NO FRAMES

Uses of Class
javax.xml.xpath.XPathFunctionException

Packages that use XPathFunctionException
javax.xml.xpath This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.

Uses of XPathFunctionException in javax.xml.xpath

Methods in javax.xml.xpath that throw XPathFunctionException
 Object XPathFunction.evaluate(List args)
Evaluate the function with the specified arguments.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.xpath.XPath

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.xpath.XPath

Packages that use XPath
javax.xml.xpath This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.

Uses of XPath in javax.xml.xpath

Methods in javax.xml.xpath that return XPath
abstract  XPath XPathFactory.newXPath()
Return a new XPath using the underlying object model determined when the XPathFactory was instantiated.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.xpath.XPathExpression

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.xpath.XPathExpression

Packages that use XPathExpression
javax.xml.xpath This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.

Uses of XPathExpression in javax.xml.xpath

Methods in javax.xml.xpath that return XPathExpression
 XPathExpression XPath.compile(String expression)
Compile an XPath expression for later evaluation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.xpath.XPathFunction

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.xpath.XPathFunction

Packages that use XPathFunction
javax.xml.xpath This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.

Uses of XPathFunction in javax.xml.xpath

Methods in javax.xml.xpath that return XPathFunction
 XPathFunction XPathFunctionResolver.resolveFunction(QName functionName, int arity)
Find a function in the set of available functions.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.xpath.XPathFunctionResolver

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.xpath.XPathFunctionResolver

Packages that use XPathFunctionResolver
javax.xml.xpath This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.

Uses of XPathFunctionResolver in javax.xml.xpath

Methods in javax.xml.xpath that return XPathFunctionResolver
 XPathFunctionResolver XPath.getXPathFunctionResolver()
Return the current function resolver.

Methods in javax.xml.xpath with parameters of type XPathFunctionResolver
abstract void | XPathFactory.setXPathFunctionResolver(XPathFunctionResolver resolver) Establish a default function resolver.
void | XPath.setXPathFunctionResolver(XPathFunctionResolver resolver) Establish a function resolver.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface javax.xml.xpath.XPathVariableResolver

PREV NEXT FRAMES NO FRAMES

Uses of Interface
javax.xml.xpath.XPathVariableResolver

Packages that use XPathVariableResolver
javax.xml.xpath This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.

Uses of XPathVariableResolver in javax.xml.xpath

Methods in javax.xml.xpath that return XPathVariableResolver
 XPathVariableResolver XPath.getXPathVariableResolver()
Return the current variable resolver.

Methods in javax.xml.xpath with parameters of type XPathVariableResolver
abstract void | XPathFactory.setXPathVariableResolver(XPathVariableResolver resolver) Establish a default variable resolver.
void | XPath.setXPathVariableResolver(XPathVariableResolver resolver) Establish a variable resolver.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


XPath

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.xpath
Interface XPath

public interface XPath

XPath provides access to the XPath evaluation environment and expressions.

Evaluation of XPath Expressions.
context | If a request is made to evaluate the expression in the absence of a context item, an empty document node will be used for the context. For the purposes of evaluating XPath expressions, a DocumentFragment is treated like a Document node.
variables | If the expression contains a variable reference, its value will be found through the XPathVariableResolver set with setXPathVariableResolver(XPathVariableResolver resolver). An XPathExpressionException is raised if the variable resolver is undefined or the resolver returns null for the variable. The value of a variable must be immutable through the course of any single evaluation.
functions | If the expression contains a function reference, the function will be found through the XPathFunctionResolver set with setXPathFunctionResolver(XPathFunctionResolver resolver). An XPathExpressionException is raised if the function resolver is undefined or the function resolver returns null for the function.
QNames | QNames in the expression are resolved against the XPath namespace context set with setNamespaceContext(NamespaceContext nsContext).
result | This result of evaluating an expression is converted to an instance of the desired return type. Valid return types are defined in XPathConstants. Conversion to the return type follows XPath conversion rules.

An XPath object is not thread-safe and not reentrant. In other words, it is the application's responsibility to make sure that one XPath object is not used from more than one thread at any given time, and while the evaluate method is invoked, applications may not recursively call the evaluate method.

Since:
1.5
See Also:
XML Path Language (XPath) Version 1.0

Method Summary
XPathExpression | compile(String expression) Compile an XPath expression for later evaluation.
String | evaluate(String expression, InputSource source) Evaluate an XPath expression in the context of the specified InputSource and return the result as a String.
Object | evaluate(String expression, InputSource source, QName returnType) Evaluate an XPath expression in the context of the specified InputSource and return the result as the specified type.
String | evaluate(String expression, Object item) Evaluate an XPath expression in the specified context and return the result as a String.
Object | evaluate(String expression, Object item, QName returnType) Evaluate an XPath expression in the specified context and return the result as the specified type.
NamespaceContext | getNamespaceContext() Return the current namespace context.
XPathFunctionResolver | getXPathFunctionResolver() Return the current function resolver.
XPathVariableResolver | getXPathVariableResolver() Return the current variable resolver.
void | reset() Reset this XPath to its original configuration.
void | setNamespaceContext(NamespaceContext nsContext) Establish a namespace context.
void | setXPathFunctionResolver(XPathFunctionResolver resolver) Establish a function resolver.
void | setXPathVariableResolver(XPathVariableResolver resolver) Establish a variable resolver.

Method Detail

reset

void reset()

Reset this XPath to its original configuration.

XPath is reset to the same state as when it was created with XPathFactory.newXPath(). reset() is designed to allow the reuse of existing XPaths thus saving resources associated with the creation of new XPaths.

The reset XPath is not guaranteed to have the same XPathFunctionResolver, XPathVariableResolver or NamespaceContext Objects, e.g. Object.equals(Object obj). It is guaranteed to have a functionally equal XPathFunctionResolver, XPathVariableResolver and NamespaceContext.

setXPathVariableResolver

void setXPathVariableResolver(XPathVariableResolver resolver)

Establish a variable resolver.

A NullPointerException is thrown if resolver is null.

Parameters:
resolver - Variable resolver.
Throws:
NullPointerException - If resolver is null.

getXPathVariableResolver

XPathVariableResolver getXPathVariableResolver()

Return the current variable resolver.

null is returned in no variable resolver is in effect.

Returns:
Current variable resolver.

setXPathFunctionResolver

void setXPathFunctionResolver(XPathFunctionResolver resolver)

Establish a function resolver.

A NullPointerException is thrown if resolver is null.

Parameters:
resolver - XPath function resolver.
Throws:
NullPointerException - If resolver is null.

getXPathFunctionResolver

XPathFunctionResolver getXPathFunctionResolver()

Return the current function resolver.

null is returned in no function resolver is in effect.

Returns:
Current function resolver.

setNamespaceContext

void setNamespaceContext(NamespaceContext nsContext)

Establish a namespace context.

A NullPointerException is thrown if nsContext is null.

Parameters:
nsContext - Namespace context to use.
Throws:
NullPointerException - If nsContext is null.

getNamespaceContext

NamespaceContext getNamespaceContext()

Return the current namespace context.

null is returned in no namespace context is in effect.

Returns:
Current Namespace context.

compile

XPathExpression compile(String expression)
                        throws XPathExpressionException

Compile an XPath expression for later evaluation.

If expression contains any XPathFunctions, they must be available via the XPathFunctionResolver. An XPathExpressionException will be thrown if the XPathFunction cannot be resovled with the XPathFunctionResolver.

If expression contains any variables, the XPathVariableResolver in effect at compile time will be used to resolve them.

If expression is null, a NullPointerException is thrown.

Parameters:
expression - The XPath expression.
Returns:
Compiled XPath expression.
Throws:
XPathExpressionException - If expression cannot be compiled.
NullPointerException - If expression is null.

evaluate

Object evaluate(String expression,
                Object item,
                QName returnType)
                throws XPathExpressionException

Evaluate an XPath expression in the specified context and return the result as the specified type.

See Evaluation of XPath Expressions for context item evaluation, variable, function and QName resolution and return type conversion.

If returnType is not one of the types defined in XPathConstants ( NUMBER, STRING, BOOLEAN, NODE or NODESET) then an IllegalArgumentException is thrown.

If a null value is provided for item, an empty document will be used for the context. If expression or returnType is null, then a NullPointerException is thrown.

Parameters:
expression - The XPath expression.
item - The starting context (a node, for example).
returnType - The desired return type.
Returns:
Result of evaluating an XPath expression as an Object of returnType.
Throws:
XPathExpressionException - If expression cannot be evaluated.
IllegalArgumentException - If returnType is not one of the types defined in XPathConstants.
NullPointerException - If expression or returnType is null.

evaluate

String evaluate(String expression,
                Object item)
                throws XPathExpressionException

Evaluate an XPath expression in the specified context and return the result as a String.

This method calls evaluate(String expression, Object item, QName returnType) with a returnType of XPathConstants.STRING.

See Evaluation of XPath Expressions for context item evaluation, variable, function and QName resolution and return type conversion.

If a null value is provided for item, an empty document will be used for the context. If expression is null, then a NullPointerException is thrown.

Parameters:
expression - The XPath expression.
item - The starting context (a node, for example).
Returns:
The String that is the result of evaluating the expression and converting the result to a String.
Throws:
XPathExpressionException - If expression cannot be evaluated.
NullPointerException - If expression is null.

evaluate

Object evaluate(String expression,
                InputSource source,
                QName returnType)
                throws XPathExpressionException

Evaluate an XPath expression in the context of the specified InputSource and return the result as the specified type.

This method builds a data model for the InputSource and calls evaluate(String expression, Object item, QName returnType) on the resulting document object.

See Evaluation of XPath Expressions for context item evaluation, variable, function and QName resolution and return type conversion.

If returnType is not one of the types defined in XPathConstants, then an IllegalArgumentException is thrown.

If expression, source or returnType is null, then a NullPointerException is thrown.

Parameters:
expression - The XPath expression.
source - The input source of the document to evaluate over.
returnType - The desired return type.
Returns:
The Object that encapsulates the result of evaluating the expression.
Throws:
XPathExpressionException - If expression cannot be evaluated.
IllegalArgumentException - If returnType is not one of the types defined in XPathConstants.
NullPointerException - If expression, source or returnType is null.

evaluate

String evaluate(String expression,
                InputSource source)
                throws XPathExpressionException

Evaluate an XPath expression in the context of the specified InputSource and return the result as a String.

This method calls evaluate(String expression, InputSource source, QName returnType) with a returnType of XPathConstants.STRING.

See Evaluation of XPath Expressions for context item evaluation, variable, function and QName resolution and return type conversion.

If expression or source is null, then a NullPointerException is thrown.

Parameters:
expression - The XPath expression.
source - The InputSource of the document to evaluate over.
Returns:
The String that is the result of evaluating the expression and converting the result to a String.
Throws:
XPathExpressionException - If expression cannot be evaluated.
NullPointerException - If expression or source is null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


XPathConstants

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.xpath
Class XPathConstants

java.lang.Object
    extended by  javax.xml.xpath.XPathConstants

public class XPathConstants
extends Object

XPath constants.

Since:
1.5
See Also:
XML Path Language (XPath) Version 1.0

Field Summary
static QName | BOOLEAN The XPath 1.0 boolean data type.
static String | DOM_OBJECT_MODEL The URI for the DOM object model, "http://java.sun.com/jaxp/xpath/dom".
static QName | NODE The XPath 1.0 NodeSet data type.
static QName | NODESET The XPath 1.0 NodeSet data type.
static QName | NUMBER The XPath 1.0 number data type.
static QName | STRING The XPath 1.0 string data type.
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NUMBER

public static final QName NUMBER

The XPath 1.0 number data type.

Maps to Java Double.

STRING

public static final QName STRING

The XPath 1.0 string data type.

Maps to Java String.

BOOLEAN

public static final QName BOOLEAN

The XPath 1.0 boolean data type.

Maps to Java Boolean.

NODESET

public static final QName NODESET

The XPath 1.0 NodeSet data type.

Maps to Java NodeList.

NODE

public static final QName NODE

The XPath 1.0 NodeSet data type.

Maps to Java Node.

DOM_OBJECT_MODEL

public static final String DOM_OBJECT_MODEL

The URI for the DOM object model, "http://java.sun.com/jaxp/xpath/dom".

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XPathException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.xpath
Class XPathException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.xpath.XPathException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
XPathExpressionException, XPathFactoryConfigurationException
public class XPathException
extends Exception

XPathException represents a generic XPath exception.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
XPathException(String message)
Constructs a new XPathException with the specified detail message.
XPathException(Throwable cause)
Constructs a new XPathException with the specified cause.
Method Summary
Throwable | getCause() Get the cause of this XPathException.
void | printStackTrace() Print stack trace to System.err.
void | printStackTrace(PrintStream s) Print stack trace to specified PrintStream.
void | printStackTrace(PrintWriter s) Print stack trace to specified PrintWriter.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

XPathException

public XPathException(String message)

Constructs a new XPathException with the specified detail message.

The cause is not initialized.

If message is null, then a NullPointerException is thrown.

Parameters:
message - The detail message.
Throws:
NullPointerException - When message is null.

XPathException

public XPathException(Throwable cause)

Constructs a new XPathException with the specified cause.

If cause is null, then a NullPointerException is thrown.

Parameters:
cause - The cause.
Throws:
NullPointerException - if cause is null.
Method Detail

getCause

public Throwable getCause()

Get the cause of this XPathException.

Overrides:
getCause in class Throwable
Returns:
Cause of this XPathException.

printStackTrace

public void printStackTrace(PrintStream s)

Print stack trace to specified PrintStream.

Overrides:
printStackTrace in class Throwable
Parameters:
s - Print stack trace to this PrintStream.

printStackTrace

public void printStackTrace()

Print stack trace to System.err.

Overrides:
printStackTrace in class Throwable

printStackTrace

public void printStackTrace(PrintWriter s)

Print stack trace to specified PrintWriter.

Overrides:
printStackTrace in class Throwable
Parameters:
s - Print stack trace to this PrintWriter.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XPathExpression

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.xpath
Interface XPathExpression

public interface XPathExpression

XPathExpression provides access to compiled XPath expressions.

Evaluation of XPath Expressions.
context | If a request is made to evaluate the expression in the absence of a context item, an empty document node will be used for the context. For the purposes of evaluating XPath expressions, a DocumentFragment is treated like a Document node.
variables | If the expression contains a variable reference, its value will be found through the XPathVariableResolver. An XPathExpressionException is raised if the variable resolver is undefined or the resolver returns null for the variable. The value of a variable must be immutable through the course of any single evaluation.
functions | If the expression contains a function reference, the function will be found through the XPathFunctionResolver. An XPathExpressionException is raised if the function resolver is undefined or the function resolver returns null for the function.
QNames | QNames in the expression are resolved against the XPath namespace context.
result | This result of evaluating an expression is converted to an instance of the desired return type. Valid return types are defined in XPathConstants. Conversion to the return type follows XPath conversion rules.

An XPath expression is not thread-safe and not reentrant. In other words, it is the application's responsibility to make sure that one XPathExpression object is not used from more than one thread at any given time, and while the evaluate method is invoked, applications may not recursively call the evaluate method.

Since:
1.5
See Also:
XML Path Language (XPath) Version 1.0, Expressions

Method Summary
String | evaluate(InputSource source) Evaluate the compiled XPath expression in the context of the specified InputSource and return the result as a String.
Object | evaluate(InputSource source, QName returnType) Evaluate the compiled XPath expression in the context of the specified InputSource and return the result as the specified type.
String | evaluate(Object item) Evaluate the compiled XPath expression in the specified context and return the result as a String.
Object | evaluate(Object item, QName returnType) Evaluate the compiled XPath expression in the specified context and return the result as the specified type.

Method Detail

evaluate

Object evaluate(Object item,
                QName returnType)
                throws XPathExpressionException

Evaluate the compiled XPath expression in the specified context and return the result as the specified type.

See Evaluation of XPath Expressions for context item evaluation, variable, function and QName resolution and return type conversion.

If returnType is not one of the types defined in XPathConstants, then an IllegalArgumentException is thrown.

If a null value is provided for item, an empty document will be used for the context. If returnType is null, then a NullPointerException is thrown.

Parameters:
item - The starting context (a node, for example).
returnType - The desired return type.
Returns:
The Object that is the result of evaluating the expression and converting the result to returnType.
Throws:
XPathExpressionException - If the expression cannot be evaluated.
IllegalArgumentException - If returnType is not one of the types defined in XPathConstants.
NullPointerException - If returnType is null.

evaluate

String evaluate(Object item)
                throws XPathExpressionException

Evaluate the compiled XPath expression in the specified context and return the result as a String.

This method calls evaluate(Object item, QName returnType) with a returnType of XPathConstants.STRING.

See Evaluation of XPath Expressions for context item evaluation, variable, function and QName resolution and return type conversion.

If a null value is provided for item, an empty document will be used for the context.

Parameters:
item - The starting context (a node, for example).
Returns:
The String that is the result of evaluating the expression and converting the result to a String.
Throws:
XPathExpressionException - If the expression cannot be evaluated.

evaluate

Object evaluate(InputSource source,
                QName returnType)
                throws XPathExpressionException

Evaluate the compiled XPath expression in the context of the specified InputSource and return the result as the specified type.

This method builds a data model for the InputSource and calls evaluate(Object item, QName returnType) on the resulting document object.

See Evaluation of XPath Expressions for context item evaluation, variable, function and QName resolution and return type conversion.

If returnType is not one of the types defined in XPathConstants, then an IllegalArgumentException is thrown.

If source or returnType is null, then a NullPointerException is thrown.

Parameters:
source - The InputSource of the document to evaluate over.
returnType - The desired return type.
Returns:
The Object that is the result of evaluating the expression and converting the result to returnType.
Throws:
XPathExpressionException - If the expression cannot be evaluated.
IllegalArgumentException - If returnType is not one of the types defined in XPathConstants.
NullPointerException - If source or returnType is null.

evaluate

String evaluate(InputSource source)
                throws XPathExpressionException

Evaluate the compiled XPath expression in the context of the specified InputSource and return the result as a String.

This method calls evaluate(InputSource source, QName returnType) with a returnType of XPathConstants.STRING.

See Evaluation of XPath Expressions for context item evaluation, variable, function and QName resolution and return type conversion.

If source is null, then a NullPointerException is thrown.

Parameters:
source - The InputSource of the document to evaluate over.
Returns:
The String that is the result of evaluating the expression and converting the result to a String.
Throws:
XPathExpressionException - If the expression cannot be evaluated.
NullPointerException - If source is null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XPathExpressionException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.xpath
Class XPathExpressionException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.xpath.XPathException
                extended by  javax.xml.xpath.XPathExpressionException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
XPathFunctionException
public class XPathExpressionException
extends XPathException

XPathExpressionException represents an error in an XPath expression.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
XPathExpressionException(String message)
Constructs a new XPathExpressionException with the specified detail message.
XPathExpressionException(Throwable cause)
Constructs a new XPathExpressionException with the specified cause.
Method Summary
Methods inherited from class javax.xml.xpath.XPathException
getCause, printStackTrace, printStackTrace, printStackTrace
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

XPathExpressionException

public XPathExpressionException(String message)

Constructs a new XPathExpressionException with the specified detail message.

The cause is not initialized.

If message is null, then a NullPointerException is thrown.

Parameters:
message - The detail message.
Throws:
NullPointerException - When message is null.

XPathExpressionException

public XPathExpressionException(Throwable cause)

Constructs a new XPathExpressionException with the specified cause.

If cause is null, then a NullPointerException is thrown.

Parameters:
cause - The cause.
Throws:
NullPointerException - if cause is null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XPathFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.xpath
Class XPathFactory

java.lang.Object
    extended by  javax.xml.xpath.XPathFactory

public abstract class XPathFactory
extends Object

An XPathFactory instance can be used to create XPath objects.

See newInstance(String uri) for lookup mechanism.

The XPathFactory class is not thread-safe. In other words, it is the application's responsibility to ensure that at most one thread is using a XPathFactory object at any given moment. Implementations are encouraged to mark methods as synchronized to protect themselves from broken clients.

XPathFactory is not re-entrant. While one of the newInstance methods is being invoked, applications may not attempt to recursively invoke a newInstance method, even from the same thread.

Since:
1.5

Field Summary
static String | DEFAULT_OBJECT_MODEL_URI Default Object Model URI.
static String | DEFAULT_PROPERTY_NAME The default property name according to the JAXP spec.
Constructor Summary
protected XPathFactory()
Protected constructor as newInstance() or newInstance(String uri) or newInstance(String uri, String factoryClassName, ClassLoader classLoader) should be used to create a new instance of an XPathFactory.
Method Summary
abstract boolean | getFeature(String name) Get the state of the named feature.
abstract boolean | isObjectModelSupported(String objectModel) Is specified object model supported by this XPathFactory?
static XPathFactory | newInstance() Get a new XPathFactory instance using the default object model, DEFAULT_OBJECT_MODEL_URI, the W3C DOM.
static XPathFactory | newInstance(String uri) Get a new XPathFactory instance using the specified object model.
static XPathFactory | newInstance(String uri, String factoryClassName, ClassLoader classLoader) Obtain a new instance of a XPathFactory from a factory class name.
abstract XPath | newXPath() Return a new XPath using the underlying object model determined when the XPathFactory was instantiated.
abstract void | setFeature(String name, boolean value) Set a feature for this XPathFactory and XPaths created by this factory.
abstract void | setXPathFunctionResolver(XPathFunctionResolver resolver) Establish a default function resolver.
abstract void | setXPathVariableResolver(XPathVariableResolver resolver) Establish a default variable resolver.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_PROPERTY_NAME

public static final String DEFAULT_PROPERTY_NAME

The default property name according to the JAXP spec.

See Also:
Constant Field Values

DEFAULT_OBJECT_MODEL_URI

public static final String DEFAULT_OBJECT_MODEL_URI

Default Object Model URI.

See Also:
Constant Field Values
Constructor Detail

XPathFactory

protected XPathFactory()

Protected constructor as newInstance() or newInstance(String uri) or newInstance(String uri, String factoryClassName, ClassLoader classLoader) should be used to create a new instance of an XPathFactory.

Method Detail

newInstance

public static final XPathFactory newInstance()

Get a new XPathFactory instance using the default object model, DEFAULT_OBJECT_MODEL_URI, the W3C DOM.

This method is functionally equivalent to:

   newInstance(DEFAULT_OBJECT_MODEL_URI)

Since the implementation for the W3C DOM is always available, this method will never fail.

Returns:
Instance of an XPathFactory.
Throws:
RuntimeException - When there is a failure in creating an XPathFactory for the default object model.

newInstance

public static final XPathFactory newInstance(String uri)
                                      throws XPathFactoryConfigurationException

Get a new XPathFactory instance using the specified object model.

To find a XPathFactory object, this method looks the following places in the following order where "the class loader" refers to the context class loader:

  1. If the system property DEFAULT_PROPERTY_NAME + ":uri" is present, where uri is the parameter to this method, then its value is read as a class name. The method will try to create a new instance of this class by using the class loader, and returns it if it is successfully created.
  2. ${java.home}/lib/jaxp.properties is read and the value associated with the key being the system property above is looked for. If present, the value is processed just like above.
  3. The class loader is asked for service provider provider-configuration files matching javax.xml.xpath.XPathFactory in the resource directory META-INF/services. See the JAR File Specification for file format and parsing rules. Each potential service provider is required to implement the method:
           isObjectModelSupported(String objectModel)
    The first service provider found in class loader order that supports the specified object model is returned.
  4. Platform default XPathFactory is located in a platform specific way. There must be a platform default XPathFactory for the W3C DOM, i.e. DEFAULT_OBJECT_MODEL_URI.

If everything fails, an XPathFactoryConfigurationException will be thrown.

Tip for Trouble-shooting:

See Properties.load(java.io.InputStream) for exactly how a property file is parsed. In particular, colons ':' need to be escaped in a property file, so make sure the URIs are properly escaped in it. For example:

   http\://java.sun.com/jaxp/xpath/dom=org.acme.DomXPathFactory

Parameters:
uri - Identifies the underlying object model. The specification only defines the URI DEFAULT_OBJECT_MODEL_URI, http://java.sun.com/jaxp/xpath/dom for the W3C DOM, the org.w3c.dom package, and implementations are free to introduce other URIs for other object models.
Returns:
Instance of an XPathFactory.
Throws:
XPathFactoryConfigurationException - If the specified object model is unavailable.
NullPointerException - If uri is null.
IllegalArgumentException - If uri is null or uri.length() == 0.

newInstance

public static XPathFactory newInstance(String uri,
                                       String factoryClassName,
                                       ClassLoader classLoader)
                                throws XPathFactoryConfigurationException

Obtain a new instance of a XPathFactory from a factory class name. XPathFactory is returned if specified factory class supports the specified object model. This function is useful when there are multiple providers in the classpath. It gives more control to the application as it can specify which provider should be loaded.

Tip for Trouble-shooting

Setting the jaxp.debug system property will cause this method to print a lot of debug messages to System.err about what it is doing and where it is looking at.

If you have problems try:

 java -Djaxp.debug=1 YourProgram ....

Parameters:
uri - Identifies the underlying object model. The specification only defines the URI DEFAULT_OBJECT_MODEL_URI,http://java.sun.com/jaxp/xpath/dom for the W3C DOM, the org.w3c.dom package, and implementations are free to introduce other URIs for other object models.
factoryClassName - fully qualified factory class name that provides implementation of javax.xml.xpath.XPathFactory.
classLoader - ClassLoader used to load the factory class. If null current Thread's context classLoader is used to load the factory class.
Returns:
New instance of a XPathFactory
Throws:
XPathFactoryConfigurationException - if factoryClassName is null, or the factory class cannot be loaded, instantiated or the factory class does not support the object model specified in the uri parameter.
NullPointerException - If uri is null.
IllegalArgumentException - If uri is null or uri.length() == 0.
Since:
1.6
See Also:
newInstance(), newInstance(String uri)

isObjectModelSupported

public abstract boolean isObjectModelSupported(String objectModel)

Is specified object model supported by this XPathFactory?

Parameters:
objectModel - Specifies the object model which the returned XPathFactory will understand.
Returns:
true if XPathFactory supports objectModel, else false.
Throws:
NullPointerException - If objectModel is null.
IllegalArgumentException - If objectModel.length() == 0.

setFeature

public abstract void setFeature(String name,
                                boolean value)
                         throws XPathFactoryConfigurationException

Set a feature for this XPathFactory and XPaths created by this factory.

Feature names are fully qualified URIs. Implementations may define their own features. An XPathFactoryConfigurationException is thrown if this XPathFactory or the XPaths it creates cannot support the feature. It is possible for an XPathFactory to expose a feature value but be unable to change its state.

All implementations are required to support the XMLConstants.FEATURE_SECURE_PROCESSING feature. When the feature is true, any reference to an external function is an error. Under these conditions, the implementation must not call the XPathFunctionResolver and must throw an XPathFunctionException.

Parameters:
name - Feature name.
value - Is feature state true or false.
Throws:
XPathFactoryConfigurationException - if this XPathFactory or the XPaths it creates cannot support this feature.
NullPointerException - if name is null.

getFeature

public abstract boolean getFeature(String name)
                            throws XPathFactoryConfigurationException

Get the state of the named feature.

Feature names are fully qualified URIs. Implementations may define their own features. An XPathFactoryConfigurationException is thrown if this XPathFactory or the XPaths it creates cannot support the feature. It is possible for an XPathFactory to expose a feature value but be unable to change its state.

Parameters:
name - Feature name.
Returns:
State of the named feature.
Throws:
XPathFactoryConfigurationException - if this XPathFactory or the XPaths it creates cannot support this feature.
NullPointerException - if name is null.

setXPathVariableResolver

public abstract void setXPathVariableResolver(XPathVariableResolver resolver)

Establish a default variable resolver.

Any XPath objects constructed from this factory will use the specified resolver by default.

A NullPointerException is thrown if resolver is null.

Parameters:
resolver - Variable resolver.
Throws:
NullPointerException - If resolver is null.

setXPathFunctionResolver

public abstract void setXPathFunctionResolver(XPathFunctionResolver resolver)

Establish a default function resolver.

Any XPath objects constructed from this factory will use the specified resolver by default.

A NullPointerException is thrown if resolver is null.

Parameters:
resolver - XPath function resolver.
Throws:
NullPointerException - If resolver is null.

newXPath

public abstract XPath newXPath()

Return a new XPath using the underlying object model determined when the XPathFactory was instantiated.

Returns:
New instance of an XPath.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XPathFactoryConfigurationException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.xpath
Class XPathFactoryConfigurationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.xpath.XPathException
                extended by  javax.xml.xpath.XPathFactoryConfigurationException
All Implemented Interfaces:
Serializable
public class XPathFactoryConfigurationException
extends XPathException

XPathFactoryConfigurationException represents a configuration error in a XPathFactory environment.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
XPathFactoryConfigurationException(String message)
Constructs a new XPathFactoryConfigurationException with the specified detail message.
XPathFactoryConfigurationException(Throwable cause)
Constructs a new XPathFactoryConfigurationException with the specified cause.
Method Summary
Methods inherited from class javax.xml.xpath.XPathException
getCause, printStackTrace, printStackTrace, printStackTrace
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

XPathFactoryConfigurationException

public XPathFactoryConfigurationException(String message)

Constructs a new XPathFactoryConfigurationException with the specified detail message.

The cause is not initialized.

If message is null, then a NullPointerException is thrown.

Parameters:
message - The detail message.
Throws:
NullPointerException - When message is null.

XPathFactoryConfigurationException

public XPathFactoryConfigurationException(Throwable cause)

Constructs a new XPathFactoryConfigurationException with the specified cause.

If cause is null, then a NullPointerException is thrown.

Parameters:
cause - The cause.
Throws:
NullPointerException - if cause is null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XPathFunction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.xpath
Interface XPathFunction

public interface XPathFunction

XPathFunction provides access to XPath functions.

Functions are identified by QName and arity in XPath.

Since:
1.5

Method Summary
 Object evaluate(List args)
Evaluate the function with the specified arguments.

Method Detail

evaluate

Object evaluate(List args)
                throws XPathFunctionException

Evaluate the function with the specified arguments.

To the greatest extent possible, side-effects should be avoided in the definition of extension functions. The implementation evaluating an XPath expression is under no obligation to call extension functions in any particular order or any particular number of times.

Parameters:
args - The arguments, null is a valid value.
Returns:
The result of evaluating the XPath function as an Object.
Throws:
XPathFunctionException - If args cannot be evaluated with this XPath function.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XPathFunctionException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.xpath
Class XPathFunctionException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  javax.xml.xpath.XPathException
                extended by  javax.xml.xpath.XPathExpressionException
                    extended by  javax.xml.xpath.XPathFunctionException
All Implemented Interfaces:
Serializable
public class XPathFunctionException
extends XPathExpressionException

XPathFunctionException represents an error with an XPath function.

Since:
1.5
See Also:
Serialized Form

Constructor Summary
XPathFunctionException(String message)
Constructs a new XPathFunctionException with the specified detail message.
XPathFunctionException(Throwable cause)
Constructs a new XPathFunctionException with the specified cause.
Method Summary
Methods inherited from class javax.xml.xpath.XPathException
getCause, printStackTrace, printStackTrace, printStackTrace
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, initCause, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

XPathFunctionException

public XPathFunctionException(String message)

Constructs a new XPathFunctionException with the specified detail message.

The cause is not initialized.

If message is null, then a NullPointerException is thrown.

Parameters:
message - The detail message.
Throws:
NullPointerException - When message is null.

XPathFunctionException

public XPathFunctionException(Throwable cause)

Constructs a new XPathFunctionException with the specified cause.

If cause is null, then a NullPointerException is thrown.

Parameters:
cause - The cause.
Throws:
NullPointerException - if cause is null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XPathFunctionResolver

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.xml.xpath
Interface XPathFunctionResolver

public interface XPathFunctionResolver

XPathFunctionResolver provides access to the set of user defined XPathFunctions.

XPath functions are resolved by name and arity. The resolver is not needed for XPath built-in functions and the resolver cannot be used to override those functions.

In particular, the resolver is only called for functions in an another namespace (functions with an explicit prefix). This means that you cannot use the XPathFunctionResolver to implement specifications like XML-Signature Syntax and Processing which extend the function library of XPath 1.0 in the same namespace. This is a consequence of the design of the resolver.

If you wish to implement additional built-in functions, you will have to extend the underlying implementation directly.

Since:
1.5
See Also:
XML Path Language (XPath) Version 1.0, Core Function Library

Method Summary
 XPathFunction resolveFunction(QName functionName, int arity)
Find a function in the set of available functions.

Method Detail

resolveFunction

XPathFunction resolveFunction(QName functionName,
                              int arity)

Find a function in the set of available functions.

If functionName or arity is null, then a NullPointerException is thrown.

Parameters:
functionName - The function name.
arity - The number of arguments that the returned function must accept.
Returns:
The function or null if no function named functionName with arity arguments exists.
Throws:
NullPointerException - If functionName or arity is null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XPathVariableResolver

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

javax.xml.xpath
Interface XPathVariableResolver

public interface XPathVariableResolver

XPathVariableResolver provides access to the set of user defined XPath variables.

The XPathVariableResolver and the XPath evaluator must adhere to a contract that cannot be directly enforced by the API. Although variables may be mutable, that is, an application may wish to evaluate the same XPath expression more than once with different variable values, in the course of evaluating any single XPath expression, a variable's value must not change.

Since:
1.5

Method Summary
 Object resolveVariable(QName variableName)
Find a variable in the set of available variables.

Method Detail

resolveVariable

Object resolveVariable(QName variableName)

Find a variable in the set of available variables.

If variableName is null, then a NullPointerException is thrown.

Parameters:
variableName - The QName of the variable name.
Returns:
The variables value, or null if no variable named variableName exists. The value returned must be of a type appropriate for the underlying object model.
Throws:
NullPointerException - If variableName is null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


jgss

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.ietf.jgss

This package presents a framework that allows application developers to make use of security services like authentication, data integrity and data confidentiality from a variety of underlying security mechanisms like Kerberos, using a unified API.

See:
Description

Interface Summary
GSSContext | This interface encapsulates the GSS-API security context and provides the security services that are available over the context.
GSSCredential | This interface encapsulates the GSS-API credentials for an entity.
GSSName | This interface encapsulates a single GSS-API principal entity.

Class Summary
ChannelBinding | This class encapsulates the concept of caller-provided channel binding information.
GSSManager | This class serves as a factory for other important GSS-API classes and also provides information about the mechanisms that are supported.
MessageProp | This is a utility class used within the per-message GSSContext methods to convey per-message properties.
Oid | This class represents Universal Object Identifiers (Oids) and their associated operations.

Exception Summary
GSSException This exception is thrown whenever a GSS-API error occurs, including any mechanism specific error.

Package org.ietf.jgss Description

This package presents a framework that allows application developers to make use of security services like authentication, data integrity and data confidentiality from a variety of underlying security mechanisms like Kerberos, using a unified API. The security mechanisms that an application can chose to use are identified with unique object identifiers. One example of such a mechanism is the Kerberos v5 GSS-API mechanism (object identifier 1.2.840.113554.1.2.2). This mechanism is available through the default instance of the GSSManager class.

The GSS-API is defined in a language independent way in RFC 2743. The Java language bindings are defined in RFC 2853

An application starts out by instantiating a GSSManager which then serves as a factory for a security context. An application can use specific principal names and credentials that are also created using the GSSManager; or it can instantiate a context with system defaults. It then goes through a context establishment loop. Once a context is established with the peer, authentication is complete. Data protection such as integrity and confidentiality can then be obtained from this context.

The GSS-API does not perform any communication with the peer. It merely produces tokens that the application must somehow transport to the other end.

Credential Acquisition

The GSS-API itself does not dictate how an underlying mechanism obtains the credentials that are needed for authentication. It is assumed that prior to calling the GSS-API, these credentials are obtained and stored in a location that the mechanism provider is aware of. However, the default model in the Java platform will be that mechanism providers must obtain credentials only from the private or public credential sets associated with the Subject in the current access control context. The Kerberos v5 mechanism will search for the required INITIATE and ACCEPT credentials (KerberosTicket and KerberosKey) in the private credential set where as some other mechanism might look in the public set or in both. If the desired credential is not present in the appropriate sets of the current Subject, the GSS-API call must fail.

This model has the advantage that credential management is simple and predictable from the applications point of view. An application, given the right permissions, can purge the credentials in the Subject or renew them using standard Java API's. If it purged the credentials, it would be sure that the JGSS mechanism would fail, or if it renewed a time based credential it would be sure that a JGSS mechanism would succeed.

This model does require that a JAAS login be performed in order to authenticate and populate a Subject that the JGSS mechnanism can later utilize. However, applications have the ability to relax this restiction by means of a system property: javax.security.auth.useSubjectCredsOnly. By default this system property will be assumed to be true (even when it is unset) indicating that providers must only use the credentials that are present in the current Subject. However, if this property is explicitly set to false by the application, then it indicates that the provider is free to use any credentials cache of its choice. Such a credential cache might be a disk cache, an in-memory cache, or even just the current Subject itself.

Related Documentation

For an online tutorial on using Java GSS-API, please see Introduction to JAAS and Java GSS-API.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.ietf.jgss Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.ietf.jgss

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.ietf.jgss.ChannelBinding
    • org.ietf.jgss.GSSManager
    • org.ietf.jgss.MessageProp
    • org.ietf.jgss.Oid
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.ietf.jgss.GSSException

Interface Hierarchy

  • java.lang.Cloneable
    • org.ietf.jgss.GSSCredential
  • org.ietf.jgss.GSSContext
  • org.ietf.jgss.GSSName
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.ietf.jgss

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.ietf.jgss

Packages that use org.ietf.jgss
org.ietf.jgss This package presents a framework that allows application developers to make use of security services like authentication, data integrity and data confidentiality from a variety of underlying security mechanisms like Kerberos, using a unified API.

Classes in org.ietf.jgss used by org.ietf.jgss
ChannelBinding
This class encapsulates the concept of caller-provided channel binding information.
GSSContext
This interface encapsulates the GSS-API security context and provides the security services that are available over the context.
GSSCredential
This interface encapsulates the GSS-API credentials for an entity.
GSSException
This exception is thrown whenever a GSS-API error occurs, including any mechanism specific error.
GSSManager
This class serves as a factory for other important GSS-API classes and also provides information about the mechanisms that are supported.
GSSName
This interface encapsulates a single GSS-API principal entity.
MessageProp
This is a utility class used within the per-message GSSContext methods to convey per-message properties.
Oid
This class represents Universal Object Identifiers (Oids) and their associated operations.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ChannelBinding

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.ietf.jgss
Class ChannelBinding

java.lang.Object
    extended by  org.ietf.jgss.ChannelBinding

public class ChannelBinding
extends Object

This class encapsulates the concept of caller-provided channel binding information. Channel bindings are used to strengthen the quality with which peer entity authentication is provided during context establishment. They enable the GSS-API callers to bind the establishment of the security context to relevant characteristics like addresses or to application specific data.

The caller initiating the security context must determine the appropriate channel binding values to set in the GSSContext object. The acceptor must provide an identical binding in order to validate that received tokens possess correct channel-related characteristics.

Use of channel bindings is optional in GSS-API. ChannelBinding can be set for the GSSContext using the setChannelBinding method before the first call to initSecContext or acceptSecContext has been performed. Unless the setChannelBinding method has been used to set the ChannelBinding for a GSSContext object, null ChannelBinding will be assumed.

Conceptually, the GSS-API concatenates the initiator and acceptor address information, and the application supplied byte array to form an octet string. The mechanism calculates a MIC over this octet string and binds the MIC to the context establishment token emitted by initSecContext method of the GSSContext interface. The same bindings are set by the context acceptor for its GSSContext object and during processing of the acceptSecContext method a MIC is calculated in the same way. The calculated MIC is compared with that found in the token, and if the MICs differ, accept will throw a GSSException with the major code set to BAD_BINDINGS, and the context will not be established. Some mechanisms may include the actual channel binding data in the token (rather than just a MIC); applications should therefore not use confidential data as channel-binding components.

Individual mechanisms may impose additional constraints on addresses that may appear in channel bindings. For example, a mechanism may verify that the initiator address field of the channel binding contains the correct network address of the host system. Portable applications should therefore ensure that they either provide correct information for the address fields, or omit setting of the addressing information.

Since:
1.4

Constructor Summary
ChannelBinding(byte[] appData)
Creates a ChannelBinding object without any addressing information.
ChannelBinding(InetAddress initAddr, InetAddress acceptAddr, byte[] appData)
Create a ChannelBinding object with user supplied address information and data.
Method Summary
boolean | equals(Object obj) Compares two instances of ChannelBinding.
InetAddress | getAcceptorAddress() Get the acceptor's address for this channel binding.
byte[] | getApplicationData() Get the application specified data for this channel binding.
InetAddress | getInitiatorAddress() Get the initiator's address for this channel binding.
int | hashCode() Returns a hashcode value for this ChannelBinding object.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ChannelBinding

public ChannelBinding(InetAddress initAddr,
                      InetAddress acceptAddr,
                      byte[] appData)
Create a ChannelBinding object with user supplied address information and data. null values can be used for any fields which the application does not want to specify.

Parameters:
initAddr - the address of the context initiator. null value can be supplied to indicate that the application does not want to set this value.
acceptAddr - the address of the context acceptor. null value can be supplied to indicate that the application does not want to set this value.
appData - application supplied data to be used as part of the channel bindings. null value can be supplied to indicate that the application does not want to set this value.

ChannelBinding

public ChannelBinding(byte[] appData)
Creates a ChannelBinding object without any addressing information.

Parameters:
appData - application supplied data to be used as part of the channel bindings.
Method Detail

getInitiatorAddress

public InetAddress getInitiatorAddress()
Get the initiator's address for this channel binding.

Returns:
the initiator's address. null is returned if the address has not been set.

getAcceptorAddress

public InetAddress getAcceptorAddress()
Get the acceptor's address for this channel binding.

Returns:
the acceptor's address. null is returned if the address has not been set.

getApplicationData

public byte[] getApplicationData()
Get the application specified data for this channel binding.

Returns:
the application data being used as part of the ChannelBinding. null is returned if no application data has been specified for the channel binding.

equals

public boolean equals(Object obj)
Compares two instances of ChannelBinding.

Overrides:
equals in class Object
Parameters:
obj - another ChannelBinding to compare this one with
Returns:
true if the two ChannelBinding's contain the same values for the initiator and acceptor addresses and the application data.
See Also:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
Returns a hashcode value for this ChannelBinding object.

Overrides:
hashCode in class Object
Returns:
a hashCode value
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class org.ietf.jgss.ChannelBinding

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.ietf.jgss.ChannelBinding

Packages that use ChannelBinding
org.ietf.jgss This package presents a framework that allows application developers to make use of security services like authentication, data integrity and data confidentiality from a variety of underlying security mechanisms like Kerberos, using a unified API.

Uses of ChannelBinding in org.ietf.jgss

Methods in org.ietf.jgss with parameters of type ChannelBinding
 void GSSContext.setChannelBinding(ChannelBinding cb)
Sets the channel bindings to be used during context establishment.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.ietf.jgss.GSSException

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.ietf.jgss.GSSException

Packages that use GSSException
org.ietf.jgss This package presents a framework that allows application developers to make use of security services like authentication, data integrity and data confidentiality from a variety of underlying security mechanisms like Kerberos, using a unified API.

Uses of GSSException in org.ietf.jgss

Methods in org.ietf.jgss that throw GSSException
byte[] | GSSContext.acceptSecContext(byte[] inToken, int offset, int len) Called by the context acceptor upon receiving a token from the peer.
void | GSSContext.acceptSecContext(InputStream inStream, OutputStream outStream) Called by the context acceptor to process a token from the peer using streams.
void | GSSCredential.add(GSSName name, int initLifetime, int acceptLifetime, Oid mech, int usage) Adds a mechanism specific credential-element to an existing credential.
abstract void | GSSManager.addProviderAtEnd(Provider p, Oid mech) This method is used to indicate to the GSSManager that the application would like a particular provider to be used if no other provider can be found that supports the given mechanism.
abstract void | GSSManager.addProviderAtFront(Provider p, Oid mech) This method is used to indicate to the GSSManager that the application would like a particular provider to be used ahead of all others when support is desired for the given mechanism.
GSSName | GSSName.canonicalize(Oid mech) Creates a name that is canonicalized for some mechanism.
abstract GSSContext | GSSManager.createContext(byte[] interProcessToken) Factory method for creating a previously exported context.
abstract GSSContext | GSSManager.createContext(GSSCredential myCred) Factory method for creating a context on the acceptor' side.
abstract GSSContext | GSSManager.createContext(GSSName peer, Oid mech, GSSCredential myCred, int lifetime) Factory method for creating a context on the initiator's side.
abstract GSSCredential | GSSManager.createCredential(GSSName name, int lifetime, Oid[] mechs, int usage) Factory method for acquiring credentials over a set of mechanisms.
abstract GSSCredential | GSSManager.createCredential(GSSName name, int lifetime, Oid mech, int usage) Factory method for acquiring a single mechanism credential.
abstract GSSCredential | GSSManager.createCredential(int usage) Factory method for acquiring default credentials.
abstract GSSName | GSSManager.createName(byte[] name, Oid nameType) Factory method to convert a byte array containing a name from the specified namespace to a GSSName object.
abstract GSSName | GSSManager.createName(byte[] name, Oid nameType, Oid mech) Factory method to convert a byte array containing a name from the specified namespace to a GSSName object and canonicalize it at the same time for a mechanism.
abstract GSSName | GSSManager.createName(String nameStr, Oid nameType) Factory method to convert a string name from the specified namespace to a GSSName object.
abstract GSSName | GSSManager.createName(String nameStr, Oid nameType, Oid mech) Factory method to convert a string name from the specified namespace to a GSSName object and canonicalize it at the same time for a mechanism.
void | GSSContext.dispose() Releases any system resources and cryptographic information stored in the context object and invalidates the context.
void | GSSCredential.dispose() Releases any sensitive information that the GSSCredential object may be containing.
boolean | GSSName.equals(GSSName another) Compares two GSSName objects to determine if they refer to the same entity.
byte[] | GSSContext.export() Exports this context so that another process may import it..
byte[] | GSSName.export() Returns a canonical contiguous byte representation of a mechanism name (MN), suitable for direct, byte by byte comparison by authorization functions.
GSSCredential | GSSContext.getDelegCred() Obtains the credentials delegated by the context initiator to the context acceptor.
byte[] | Oid.getDER() Returns the full ASN.1 DER encoding for this oid object, which includes the tag and length.
Oid | GSSContext.getMech() Determines what mechanism is being used for this context.
Oid[] | GSSCredential.getMechs() Returns a list of mechanisms supported by this credential.
byte[] | GSSContext.getMIC(byte[] inMsg, int offset, int len, MessageProp msgProp) Returns a token containing a cryptographic Message Integrity Code (MIC) for the supplied message, for transfer to the peer application.
void | GSSContext.getMIC(InputStream inStream, OutputStream outStream, MessageProp msgProp) Uses streams to produce a token containing a cryptographic MIC for the supplied message, for transfer to the peer application.
GSSName | GSSCredential.getName() Retrieves the name of the entity that the credential asserts.
GSSName | GSSCredential.getName(Oid mech) Retrieves a Mechanism Name of the entity that the credential asserts.
abstract Oid[] | GSSManager.getNamesForMech(Oid mech) Returns then name types supported by the indicated mechanism.
int | GSSCredential.getRemainingAcceptLifetime(Oid mech) Returns the lifetime in seconds for the credential to remain capable of accepting security contexts using the specified mechanism.
int | GSSCredential.getRemainingInitLifetime(Oid mech) Returns the lifetime in seconds for the credential to remain capable of initiating security contexts using the specified mechanism.
int | GSSCredential.getRemainingLifetime() Returns the remaining lifetime in seconds for a credential.
GSSName | GSSContext.getSrcName() Returns the name of the context initiator.
Oid | GSSName.getStringNameType() Returns the name type of the printable representation of this name that can be obtained from the toString method.
GSSName | GSSContext.getTargName() Returns the name of the context acceptor.
int | GSSCredential.getUsage() Returns the credential usage mode.
int | GSSCredential.getUsage(Oid mech) Returns the credential usage mode for a specific mechanism.
int | GSSContext.getWrapSizeLimit(int qop, boolean confReq, int maxTokenSize) Used to determine limits on the size of the message that can be passed to wrap.
byte[] | GSSContext.initSecContext(byte[] inputBuf, int offset, int len) Called by the context initiator to start the context creation phase and process any tokens generated by the peer's acceptSecContext method.
int | GSSContext.initSecContext(InputStream inStream, OutputStream outStream) Called by the context initiator to start the context creation phase and process any tokens generated by the peer's acceptSecContext method using streams.
boolean | GSSContext.isInitiator() Determines if this is the context initiator.
boolean | GSSContext.isTransferable() Determines if the context is transferable to other processes through the use of the export method.
void | GSSContext.requestAnonymity(boolean state) Requests that the initiator's identity not be disclosed to the acceptor.
void | GSSContext.requestConf(boolean state) Requests that data confidentiality be enabled for the wrap method.
void | GSSContext.requestCredDeleg(boolean state) Requests that the initiator's credentials be delegated to the acceptor during context establishment.
void | GSSContext.requestInteg(boolean state) Requests that data integrity be enabled for the wrap and getMICmethods.
void | GSSContext.requestLifetime(int lifetime) Requests a lifetime in seconds for the context.
void | GSSContext.requestMutualAuth(boolean state) Requests that mutual authentication be done during context establishment.
void | GSSContext.requestReplayDet(boolean state) Requests that replay detection be enabled for the per-message security services after context establishemnt.
void | GSSContext.requestSequenceDet(boolean state) Requests that sequence checking be enabled for the per-message security services after context establishemnt.
void | GSSContext.setChannelBinding(ChannelBinding cb) Sets the channel bindings to be used during context establishment.
byte[] | GSSContext.unwrap(byte[] inBuf, int offset, int len, MessageProp msgProp) Used to process tokens generated by the wrap method on the other side of the context.
void | GSSContext.unwrap(InputStream inStream, OutputStream outStream, MessageProp msgProp) Uses streams to process tokens generated by the wrap method on the other side of the context.
void | GSSContext.verifyMIC(byte[] inToken, int tokOffset, int tokLen, byte[] inMsg, int msgOffset, int msgLen, MessageProp msgProp) Verifies the cryptographic MIC, contained in the token parameter, over the supplied message.
void | GSSContext.verifyMIC(InputStream tokStream, InputStream msgStream, MessageProp msgProp) Uses streams to verify the cryptographic MIC, contained in the token parameter, over the supplied message.
byte[] | GSSContext.wrap(byte[] inBuf, int offset, int len, MessageProp msgProp) Applies per-message security services over the established security context.
void | GSSContext.wrap(InputStream inStream, OutputStream outStream, MessageProp msgProp) Applies per-message security services over the established security context using streams.

Constructors in org.ietf.jgss that throw GSSException
Oid(byte[] data)
Creates an Oid object from its ASN.1 DER encoding.
Oid(InputStream derOid)
Creates an Oid object from its ASN.1 DER encoding.
Oid(String strOid)
Constructs an Oid object from a string representation of its integer components.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.ietf.jgss.GSSManager

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.ietf.jgss.GSSManager

Packages that use GSSManager
org.ietf.jgss This package presents a framework that allows application developers to make use of security services like authentication, data integrity and data confidentiality from a variety of underlying security mechanisms like Kerberos, using a unified API.

Uses of GSSManager in org.ietf.jgss

Methods in org.ietf.jgss that return GSSManager
static GSSManager GSSManager.getInstance()
Returns the default GSSManager implementation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.ietf.jgss.MessageProp

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.ietf.jgss.MessageProp

Packages that use MessageProp
org.ietf.jgss This package presents a framework that allows application developers to make use of security services like authentication, data integrity and data confidentiality from a variety of underlying security mechanisms like Kerberos, using a unified API.

Uses of MessageProp in org.ietf.jgss

Methods in org.ietf.jgss with parameters of type MessageProp
byte[] | GSSContext.getMIC(byte[] inMsg, int offset, int len, MessageProp msgProp) Returns a token containing a cryptographic Message Integrity Code (MIC) for the supplied message, for transfer to the peer application.
void | GSSContext.getMIC(InputStream inStream, OutputStream outStream, MessageProp msgProp) Uses streams to produce a token containing a cryptographic MIC for the supplied message, for transfer to the peer application.
byte[] | GSSContext.unwrap(byte[] inBuf, int offset, int len, MessageProp msgProp) Used to process tokens generated by the wrap method on the other side of the context.
void | GSSContext.unwrap(InputStream inStream, OutputStream outStream, MessageProp msgProp) Uses streams to process tokens generated by the wrap method on the other side of the context.
void | GSSContext.verifyMIC(byte[] inToken, int tokOffset, int tokLen, byte[] inMsg, int msgOffset, int msgLen, MessageProp msgProp) Verifies the cryptographic MIC, contained in the token parameter, over the supplied message.
void | GSSContext.verifyMIC(InputStream tokStream, InputStream msgStream, MessageProp msgProp) Uses streams to verify the cryptographic MIC, contained in the token parameter, over the supplied message.
byte[] | GSSContext.wrap(byte[] inBuf, int offset, int len, MessageProp msgProp) Applies per-message security services over the established security context.
void | GSSContext.wrap(InputStream inStream, OutputStream outStream, MessageProp msgProp) Applies per-message security services over the established security context using streams.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.ietf.jgss.Oid

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.ietf.jgss.Oid

Packages that use Oid
org.ietf.jgss This package presents a framework that allows application developers to make use of security services like authentication, data integrity and data confidentiality from a variety of underlying security mechanisms like Kerberos, using a unified API.

Uses of Oid in org.ietf.jgss

Fields in org.ietf.jgss declared as Oid
static Oid | GSSName.NT_ANONYMOUS Name type for representing an anonymous entity.
static Oid | GSSName.NT_EXPORT_NAME Name type used to indicate an exported name produced by the export method.
static Oid | GSSName.NT_HOSTBASED_SERVICE Oid indicating a host-based service name form.
static Oid | GSSName.NT_MACHINE_UID_NAME Name type to indicate a numeric user identifier corresponding to a user on a local system.
static Oid | GSSName.NT_STRING_UID_NAME Name type to indicate a string of digits representing the numeric user identifier of a user on a local system.
static Oid | GSSName.NT_USER_NAME Name type to indicate a named user on a local system.

Methods in org.ietf.jgss that return Oid
Oid | GSSContext.getMech() Determines what mechanism is being used for this context.
Oid[] | GSSCredential.getMechs() Returns a list of mechanisms supported by this credential.
abstract Oid[] | GSSManager.getMechs() Returns a list of mechanisms that are available to GSS-API callers through this GSSManager.
abstract Oid[] | GSSManager.getMechsForName(Oid nameType) Returns a list of mechanisms that support the indicated name type.
abstract Oid[] | GSSManager.getNamesForMech(Oid mech) Returns then name types supported by the indicated mechanism.
Oid | GSSName.getStringNameType() Returns the name type of the printable representation of this name that can be obtained from the toString method.

Methods in org.ietf.jgss with parameters of type Oid
void | GSSCredential.add(GSSName name, int initLifetime, int acceptLifetime, Oid mech, int usage) Adds a mechanism specific credential-element to an existing credential.
abstract void | GSSManager.addProviderAtEnd(Provider p, Oid mech) This method is used to indicate to the GSSManager that the application would like a particular provider to be used if no other provider can be found that supports the given mechanism.
abstract void | GSSManager.addProviderAtFront(Provider p, Oid mech) This method is used to indicate to the GSSManager that the application would like a particular provider to be used ahead of all others when support is desired for the given mechanism.
GSSName | GSSName.canonicalize(Oid mech) Creates a name that is canonicalized for some mechanism.
boolean | Oid.containedIn(Oid[] oids) A utility method to test if this Oid value is contained within the supplied Oid array.
abstract GSSContext | GSSManager.createContext(GSSName peer, Oid mech, GSSCredential myCred, int lifetime) Factory method for creating a context on the initiator's side.
abstract GSSCredential | GSSManager.createCredential(GSSName name, int lifetime, Oid[] mechs, int usage) Factory method for acquiring credentials over a set of mechanisms.
abstract GSSCredential | GSSManager.createCredential(GSSName name, int lifetime, Oid mech, int usage) Factory method for acquiring a single mechanism credential.
abstract GSSName | GSSManager.createName(byte[] name, Oid nameType) Factory method to convert a byte array containing a name from the specified namespace to a GSSName object.
abstract GSSName | GSSManager.createName(byte[] name, Oid nameType, Oid mech) Factory method to convert a byte array containing a name from the specified namespace to a GSSName object and canonicalize it at the same time for a mechanism.
abstract GSSName | GSSManager.createName(String nameStr, Oid nameType) Factory method to convert a string name from the specified namespace to a GSSName object.
abstract GSSName | GSSManager.createName(String nameStr, Oid nameType, Oid mech) Factory method to convert a string name from the specified namespace to a GSSName object and canonicalize it at the same time for a mechanism.
abstract Oid[] | GSSManager.getMechsForName(Oid nameType) Returns a list of mechanisms that support the indicated name type.
GSSName | GSSCredential.getName(Oid mech) Retrieves a Mechanism Name of the entity that the credential asserts.
abstract Oid[] | GSSManager.getNamesForMech(Oid mech) Returns then name types supported by the indicated mechanism.
int | GSSCredential.getRemainingAcceptLifetime(Oid mech) Returns the lifetime in seconds for the credential to remain capable of accepting security contexts using the specified mechanism.
int | GSSCredential.getRemainingInitLifetime(Oid mech) Returns the lifetime in seconds for the credential to remain capable of initiating security contexts using the specified mechanism.
int | GSSCredential.getUsage(Oid mech) Returns the credential usage mode for a specific mechanism.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.ietf.jgss.GSSContext

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.ietf.jgss.GSSContext

Packages that use GSSContext
org.ietf.jgss This package presents a framework that allows application developers to make use of security services like authentication, data integrity and data confidentiality from a variety of underlying security mechanisms like Kerberos, using a unified API.

Uses of GSSContext in org.ietf.jgss

Methods in org.ietf.jgss that return GSSContext
abstract GSSContext | GSSManager.createContext(byte[] interProcessToken) Factory method for creating a previously exported context.
abstract GSSContext | GSSManager.createContext(GSSCredential myCred) Factory method for creating a context on the acceptor' side.
abstract GSSContext | GSSManager.createContext(GSSName peer, Oid mech, GSSCredential myCred, int lifetime) Factory method for creating a context on the initiator's side.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.ietf.jgss.GSSCredential

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.ietf.jgss.GSSCredential

Packages that use GSSCredential
org.ietf.jgss This package presents a framework that allows application developers to make use of security services like authentication, data integrity and data confidentiality from a variety of underlying security mechanisms like Kerberos, using a unified API.

Uses of GSSCredential in org.ietf.jgss

Methods in org.ietf.jgss that return GSSCredential
abstract GSSCredential | GSSManager.createCredential(GSSName name, int lifetime, Oid[] mechs, int usage) Factory method for acquiring credentials over a set of mechanisms.
abstract GSSCredential | GSSManager.createCredential(GSSName name, int lifetime, Oid mech, int usage) Factory method for acquiring a single mechanism credential.
abstract GSSCredential | GSSManager.createCredential(int usage) Factory method for acquiring default credentials.
GSSCredential | GSSContext.getDelegCred() Obtains the credentials delegated by the context initiator to the context acceptor.

Methods in org.ietf.jgss with parameters of type GSSCredential
abstract GSSContext | GSSManager.createContext(GSSCredential myCred) Factory method for creating a context on the acceptor' side.
abstract GSSContext | GSSManager.createContext(GSSName peer, Oid mech, GSSCredential myCred, int lifetime) Factory method for creating a context on the initiator's side.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.ietf.jgss.GSSName

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.ietf.jgss.GSSName

Packages that use GSSName
org.ietf.jgss This package presents a framework that allows application developers to make use of security services like authentication, data integrity and data confidentiality from a variety of underlying security mechanisms like Kerberos, using a unified API.

Uses of GSSName in org.ietf.jgss

Methods in org.ietf.jgss that return GSSName
GSSName | GSSName.canonicalize(Oid mech) Creates a name that is canonicalized for some mechanism.
abstract GSSName | GSSManager.createName(byte[] name, Oid nameType) Factory method to convert a byte array containing a name from the specified namespace to a GSSName object.
abstract GSSName | GSSManager.createName(byte[] name, Oid nameType, Oid mech) Factory method to convert a byte array containing a name from the specified namespace to a GSSName object and canonicalize it at the same time for a mechanism.
abstract GSSName | GSSManager.createName(String nameStr, Oid nameType) Factory method to convert a string name from the specified namespace to a GSSName object.
abstract GSSName | GSSManager.createName(String nameStr, Oid nameType, Oid mech) Factory method to convert a string name from the specified namespace to a GSSName object and canonicalize it at the same time for a mechanism.
GSSName | GSSCredential.getName() Retrieves the name of the entity that the credential asserts.
GSSName | GSSCredential.getName(Oid mech) Retrieves a Mechanism Name of the entity that the credential asserts.
GSSName | GSSContext.getSrcName() Returns the name of the context initiator.
GSSName | GSSContext.getTargName() Returns the name of the context acceptor.

Methods in org.ietf.jgss with parameters of type GSSName
void | GSSCredential.add(GSSName name, int initLifetime, int acceptLifetime, Oid mech, int usage) Adds a mechanism specific credential-element to an existing credential.
abstract GSSContext | GSSManager.createContext(GSSName peer, Oid mech, GSSCredential myCred, int lifetime) Factory method for creating a context on the initiator's side.
abstract GSSCredential | GSSManager.createCredential(GSSName name, int lifetime, Oid[] mechs, int usage) Factory method for acquiring credentials over a set of mechanisms.
abstract GSSCredential | GSSManager.createCredential(GSSName name, int lifetime, Oid mech, int usage) Factory method for acquiring a single mechanism credential.
boolean | GSSName.equals(GSSName another) Compares two GSSName objects to determine if they refer to the same entity.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


GSSContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.ietf.jgss
Interface GSSContext

public interface GSSContext

This interface encapsulates the GSS-API security context and provides the security services that are available over the context. Security contexts are established between peers using locally acquired credentials. Multiple contexts may exist simultaneously between a pair of peers, using the same or different set of credentials. GSS-API functions in a manner independent of the underlying transport protocol and depends on its calling application to transport the tokens that are generated by the security context between the peers.

If the caller instantiates the context using the default GSSManager instance, then the Kerberos v5 GSS-API mechanism is guaranteed to be available for context establishment. This mechanism is identified by the Oid "1.2.840.113554.1.2.2" and is defined in RFC 1964.

Before the context establishment phase is initiated, the context initiator may request specific characteristics desired of the established context. Not all underlying mechanisms support all characteristics that a caller might desire. After the context is established, the caller can check the actual characteristics and services offered by that context by means of various query methods. When using the Kerberos v5 GSS-API mechanism offered by the default GSSManager instance, all optional services will be available locally. They are mutual authentication, credential delegation, confidentiality and integrity protection, and per-message replay detection and sequencing. Note that in the GSS-API, message integrity is a prerequisite for message confidentiality.

The context establishment occurs in a loop where the initiator calls initSecContext and the acceptor calls acceptSecContext until the context is established. While in this loop the initSecContext and acceptSecContext methods produce tokens that the application sends over to the peer. The peer passes any such token as input to its acceptSecContext or initSecContext as the case may be.

During the context establishment phase, the isProtReady method may be called to determine if the context can be used for the per-message operations of wrap and getMIC. This allows applications to use per-message operations on contexts which aren't yet fully established.

After the context has been established or the isProtReady method returns true, the query routines can be invoked to determine the actual characteristics and services of the established context. The application can also start using the per-message methods of wrap and getMIC to obtain cryptographic operations on application supplied data.

When the context is no longer needed, the application should call dispose to release any system resources the context may be using.

A security context typically maintains sequencing and replay detection information about the tokens it processes. Therefore, the sequence in which any tokens are presented to this context for processing can be important. Also note that none of the methods in this interface are synchronized. Therefore, it is not advisable to share a GSSContext among several threads unless some application level synchronization is in place.

Finally, different mechanism providers might place different security restrictions on using GSS-API contexts. These will be documented by the mechanism provider. The application will need to ensure that it has the appropriate permissions if such checks are made in the mechanism layer.

The example code presented below demonstrates the usage of the GSSContext interface for the initiating peer. Different operations on the GSSContext object are presented, including: object instantiation, setting of desired flags, context establishment, query of actual context flags, per-message operations on application data, and finally context deletion.

    // Create a context using default credentials
    // and the implementation specific default mechanism
    GSSManager manager ...
    GSSName targetName ...
    GSSContext context = manager.createContext(targetName, null, null,
                                           GSSContext.INDEFINITE_LIFETIME);

    // set desired context options prior to context establishment
    context.requestConf(true);
    context.requestMutualAuth(true);
    context.requestReplayDet(true);
    context.requestSequenceDet(true);

    // establish a context between peers

    byte []inToken = new byte[0];

    // Loop while there still is a token to be processed

    while (!context.isEstablished()) {

        byte[] outToken
            = context.initSecContext(inToken, 0, inToken.length);

        // send the output token if generated
        if (outToken != null)
            sendToken(outToken);

        if (!context.isEstablished()) {
            inToken = readToken();
    }

     // display context information
     System.out.println("Remaining lifetime in seconds = "
                                          + context.getLifetime());
     System.out.println("Context mechanism = " + context.getMech());
     System.out.println("Initiator = " + context.getSrcName());
     System.out.println("Acceptor = " + context.getTargName());

     if (context.getConfState())
             System.out.println("Confidentiality (i.e., privacy) is available");

     if (context.getIntegState())
             System.out.println("Integrity is available");

     // perform wrap on an application supplied message, appMsg,
     // using QOP = 0, and requesting privacy service
     byte [] appMsg ...

     MessageProp mProp = new MessageProp(0, true);

     byte []tok = context.wrap(appMsg, 0, appMsg.length, mProp);

     sendToken(tok);

     // release the local-end of the context
     context.dispose();

Since:
1.4

Field Summary
static int | DEFAULT_LIFETIME A lifetime constant representing the default context lifetime.
static int | INDEFINITE_LIFETIME A lifetime constant representing indefinite context lifetime.
Method Summary
byte[] | acceptSecContext(byte[] inToken, int offset, int len) Called by the context acceptor upon receiving a token from the peer.
void | acceptSecContext(InputStream inStream, OutputStream outStream) Called by the context acceptor to process a token from the peer using streams.
void | dispose() Releases any system resources and cryptographic information stored in the context object and invalidates the context.
byte[] | export() Exports this context so that another process may import it..
boolean | getAnonymityState() Determines if the context initiator is anonymously authenticated to the context acceptor.
boolean | getConfState() Determines if data confidentiality is available over the context.
boolean | getCredDelegState() Determines if credential delegation is enabled on this context.
GSSCredential | getDelegCred() Obtains the credentials delegated by the context initiator to the context acceptor.
boolean | getIntegState() Determines if data integrity is available over the context.
int | getLifetime() Determines what the remaining lifetime for this context is.
Oid | getMech() Determines what mechanism is being used for this context.
byte[] | getMIC(byte[] inMsg, int offset, int len, MessageProp msgProp) Returns a token containing a cryptographic Message Integrity Code (MIC) for the supplied message, for transfer to the peer application.
void | getMIC(InputStream inStream, OutputStream outStream, MessageProp msgProp) Uses streams to produce a token containing a cryptographic MIC for the supplied message, for transfer to the peer application.
boolean | getMutualAuthState() Determines if mutual authentication is enabled on this context.
boolean | getReplayDetState() Determines if replay detection is enabled for the per-message security services from this context.
boolean | getSequenceDetState() Determines if sequence checking is enabled for the per-message security services from this context.
GSSName | getSrcName() Returns the name of the context initiator.
GSSName | getTargName() Returns the name of the context acceptor.
int | getWrapSizeLimit(int qop, boolean confReq, int maxTokenSize) Used to determine limits on the size of the message that can be passed to wrap.
byte[] | initSecContext(byte[] inputBuf, int offset, int len) Called by the context initiator to start the context creation phase and process any tokens generated by the peer's acceptSecContext method.
int | initSecContext(InputStream inStream, OutputStream outStream) Called by the context initiator to start the context creation phase and process any tokens generated by the peer's acceptSecContext method using streams.
boolean | isEstablished() Used during context establishment to determine the state of the context.
boolean | isInitiator() Determines if this is the context initiator.
boolean | isProtReady() Determines if the context is ready for per message operations to be used over it.
boolean | isTransferable() Determines if the context is transferable to other processes through the use of the export method.
void | requestAnonymity(boolean state) Requests that the initiator's identity not be disclosed to the acceptor.
void | requestConf(boolean state) Requests that data confidentiality be enabled for the wrap method.
void | requestCredDeleg(boolean state) Requests that the initiator's credentials be delegated to the acceptor during context establishment.
void | requestInteg(boolean state) Requests that data integrity be enabled for the wrap and getMICmethods.
void | requestLifetime(int lifetime) Requests a lifetime in seconds for the context.
void | requestMutualAuth(boolean state) Requests that mutual authentication be done during context establishment.
void | requestReplayDet(boolean state) Requests that replay detection be enabled for the per-message security services after context establishemnt.
void | requestSequenceDet(boolean state) Requests that sequence checking be enabled for the per-message security services after context establishemnt.
void | setChannelBinding(ChannelBinding cb) Sets the channel bindings to be used during context establishment.
byte[] | unwrap(byte[] inBuf, int offset, int len, MessageProp msgProp) Used to process tokens generated by the wrap method on the other side of the context.
void | unwrap(InputStream inStream, OutputStream outStream, MessageProp msgProp) Uses streams to process tokens generated by the wrap method on the other side of the context.
void | verifyMIC(byte[] inToken, int tokOffset, int tokLen, byte[] inMsg, int msgOffset, int msgLen, MessageProp msgProp) Verifies the cryptographic MIC, contained in the token parameter, over the supplied message.
void | verifyMIC(InputStream tokStream, InputStream msgStream, MessageProp msgProp) Uses streams to verify the cryptographic MIC, contained in the token parameter, over the supplied message.
byte[] | wrap(byte[] inBuf, int offset, int len, MessageProp msgProp) Applies per-message security services over the established security context.
void | wrap(InputStream inStream, OutputStream outStream, MessageProp msgProp) Applies per-message security services over the established security context using streams.

Field Detail

DEFAULT_LIFETIME

static final int DEFAULT_LIFETIME
A lifetime constant representing the default context lifetime. This value is set to 0.

See Also:
Constant Field Values

INDEFINITE_LIFETIME

static final int INDEFINITE_LIFETIME
A lifetime constant representing indefinite context lifetime. This value must is set to the maximum integer value in Java - Integer.MAX_VALUE.

See Also:
Constant Field Values
Method Detail

initSecContext

byte[] initSecContext(byte[] inputBuf,
                      int offset,
                      int len)
                      throws GSSException
Called by the context initiator to start the context creation phase and process any tokens generated by the peer's acceptSecContext method. This method may return an output token which the application will need to send to the peer for processing by its acceptSecContext method. The application can call isEstablished to determine if the context establishment phase is complete on this side of the context. A return value of false from isEstablished indicates that more tokens are expected to be supplied to initSecContext. Upon completion of the context establishment, the available context options may be queried through the get methods.

Note that it is possible that the initSecContext method return a token for the peer, and isEstablished return true also. This indicates that the token needs to be sent to the peer, but the local end of the context is now fully established.

Some mechanism providers might require that the caller be granted permission to initiate a security context. A failed permission check might cause a SecurityException to be thrown from this method.

Parameters:
inputBuf - token generated by the peer. This parameter is ignored on the first call since no token has been received from the peer.
offset - the offset within the inputBuf where the token begins.
len - the length of the token.
Returns:
a byte[] containing the token to be sent to the peer. null indicates that no token is generated.
Throws:
GSSException - containing the following major error codes: GSSException.DEFECTIVE_TOKEN, GSSException.BAD_MIC, GSSException.NO_CRED, GSSException.CREDENTIALS_EXPIRED, GSSException.BAD_BINDINGS, GSSException.OLD_TOKEN, GSSException.DUPLICATE_TOKEN, GSSException.BAD_NAMETYPE, GSSException.BAD_MECH, GSSException.FAILURE

initSecContext

int initSecContext(InputStream inStream,
                   OutputStream outStream)
                   throws GSSException
Called by the context initiator to start the context creation phase and process any tokens generated by the peer's acceptSecContext method using streams. This method may write an output token to the OutpuStream, which the application will need to send to the peer for processing by its acceptSecContext call. Typically, the application would ensure this by calling the flush method on an OutputStream that encapsulates the connection between the two peers. The application can determine if a token is written to the OutputStream from the return value of this method. A return value of 0 indicates that no token was written. The application can call isEstablished to determine if the context establishment phase is complete on this side of the context. A return value of false from isEstablished indicates that more tokens are expected to be supplied to initSecContext. Upon completion of the context establishment, the available context options may be queried through the get methods.

Note that it is possible that the initSecContext method return a token for the peer, and isEstablished return true also. This indicates that the token needs to be sent to the peer, but the local end of the context is now fully established.

The GSS-API authentication tokens contain a definitive start and end. This method will attempt to read one of these tokens per invocation, and may block on the stream if only part of the token is available. In all other respects this method is equivalent to the byte array based initSecContext.

Some mechanism providers might require that the caller be granted permission to initiate a security context. A failed permission check might cause a SecurityException to be thrown from this method.

The following example code demonstrates how this method might be used:

     InputStream is ...
     OutputStream os ...
     GSSContext context ...

     // Loop while there is still a token to be processed

     while (!context.isEstablished()) {

         context.initSecContext(is, os);

         // send output token if generated
         os.flush();
     }

Parameters:
inStream - an InputStream that contains the token generated by the peer. This parameter is ignored on the first call since no token has been or will be received from the peer at that point.
outStream - an OutputStream where the output token will be written. During the final stage of context establishment, there may be no bytes written.
Returns:
the number of bytes written to the OutputStream as part of the token to be sent to the peer. A value of 0 indicates that no token needs to be sent.
Throws:
GSSException - containing the following major error codes: GSSException.DEFECTIVE_TOKEN, GSSException.BAD_MIC, GSSException.NO_CRED, GSSException.CREDENTIALS_EXPIRED, GSSException.BAD_BINDINGS, GSSException.OLD_TOKEN, GSSException.DUPLICATE_TOKEN, GSSException.BAD_NAMETYPE, GSSException.BAD_MECH, GSSException.FAILURE

acceptSecContext

byte[] acceptSecContext(byte[] inToken,
                        int offset,
                        int len)
                        throws GSSException
Called by the context acceptor upon receiving a token from the peer. This method may return an output token which the application will need to send to the peer for further processing by its initSecContext call.

The application can call isEstablished to determine if the context establishment phase is complete for this peer. A return value of false from isEstablished indicates that more tokens are expected to be supplied to this method. Upon completion of the context establishment, the available context options may be queried through the get methods.

Note that it is possible that acceptSecContext return a token for the peer, and isEstablished return true also. This indicates that the token needs to be sent to the peer, but the local end of the context is now fully established.

Some mechanism providers might require that the caller be granted permission to accept a security context. A failed permission check might cause a SecurityException to be thrown from this method.

The following example code demonstrates how this method might be used:

     byte[] inToken;
     byte[] outToken;
     GSSContext context ...

     // Loop while there is still a token to be processed

     while (!context.isEstablished()) {
         inToken = readToken();
         outToken = context.acceptSecContext(inToken, 0,
                                             inToken.length);
         // send output token if generated
         if (outToken != null)
             sendToken(outToken);
     }

Parameters:
inToken - token generated by the peer.
offset - the offset within the inToken where the token begins.
len - the length of the token.
Returns:
a byte[] containing the token to be sent to the peer. null indicates that no token is generated.
Throws:
GSSException - containing the following major error codes: GSSException.DEFECTIVE_TOKEN, GSSException.BAD_MIC, GSSException.NO_CRED, GSSException.CREDENTIALS_EXPIRED, GSSException.BAD_BINDINGS, GSSException.OLD_TOKEN, GSSException.DUPLICATE_TOKEN, GSSException.BAD_MECH, GSSException.FAILURE

acceptSecContext

void acceptSecContext(InputStream inStream,
                      OutputStream outStream)
                      throws GSSException
Called by the context acceptor to process a token from the peer using streams. It may write an output token to the OutputStream, which the application will need to send to the peer for processing by its initSecContext method. Typically, the application would ensure this by calling the flush method on an OutputStream that encapsulates the connection between the two peers. The application can call isEstablished to determine if the context establishment phase is complete on this side of the context. A return value of false from isEstablished indicates that more tokens are expected to be supplied to acceptSecContext. Upon completion of the context establishment, the available context options may be queried through the get methods.

Note that it is possible that acceptSecContext return a token for the peer, and isEstablished return true also. This indicates that the token needs to be sent to the peer, but the local end of the context is now fully established.

The GSS-API authentication tokens contain a definitive start and end. This method will attempt to read one of these tokens per invocation, and may block on the stream if only part of the token is available. In all other respects this method is equivalent to the byte array based acceptSecContext.

Some mechanism providers might require that the caller be granted permission to accept a security context. A failed permission check might cause a SecurityException to be thrown from this method.

The following example code demonstrates how this method might be used:

     InputStream is ...
     OutputStream os ...
     GSSContext context ...

     // Loop while there is still a token to be processed

     while (!context.isEstablished()) {

         context.acceptSecContext(is, os);

         // send output token if generated
         os.flush();
     }

Parameters:
inStream - an InputStream that contains the token generated by the peer.
outStream - an OutputStream where the output token will be written. During the final stage of context establishment, there may be no bytes written.
Throws:
GSSException - containing the following major error codes: GSSException.DEFECTIVE_TOKEN, GSSException.BAD_MIC, GSSException.NO_CRED, GSSException.CREDENTIALS_EXPIRED, GSSException.BAD_BINDINGS, GSSException.OLD_TOKEN, GSSException.DUPLICATE_TOKEN, GSSException.BAD_MECH, GSSException.FAILURE

isEstablished

boolean isEstablished()
Used during context establishment to determine the state of the context.

Returns:
true if this is a fully established context on the caller's side and no more tokens are needed from the peer.

dispose

void dispose()
             throws GSSException
Releases any system resources and cryptographic information stored in the context object and invalidates the context.

Throws:
GSSException - containing the following major error codes: GSSException.FAILURE

getWrapSizeLimit

int getWrapSizeLimit(int qop,
                     boolean confReq,
                     int maxTokenSize)
                     throws GSSException
Used to determine limits on the size of the message that can be passed to wrap. Returns the maximum message size that, if presented to the wrap method with the same confReq and qop parameters, will result in an output token containing no more than maxTokenSize bytes.

This call is intended for use by applications that communicate over protocols that impose a maximum message size. It enables the application to fragment messages prior to applying protection.

GSS-API implementations are recommended but not required to detect invalid QOP values when getWrapSizeLimit is called. This routine guarantees only a maximum message size, not the availability of specific QOP values for message protection.

Parameters:
qop - the level of protection wrap will be asked to provide.
confReq - true if wrap will be asked to provide privacy, false otherwise.
maxTokenSize - the desired maximum size of the token emitted by wrap.
Returns:
the maximum size of the input token for the given output token size
Throws:
GSSException - containing the following major error codes: GSSException.CONTEXT_EXPIRED, GSSException.BAD_QOP, GSSException.FAILURE

wrap

byte[] wrap(byte[] inBuf,
            int offset,
            int len,
            MessageProp msgProp)
            throws GSSException
Applies per-message security services over the established security context. The method will return a token with the application supplied data and a cryptographic MIC over it. The data may be encrypted if confidentiality (privacy) was requested.

The MessageProp object is instantiated by the application and used to specify a QOP value which selects cryptographic algorithms, and a privacy service to optionally encrypt the message. The underlying mechanism that is used in the call may not be able to provide the privacy service. It sets the actual privacy service that it does provide in this MessageProp object which the caller should then query upon return. If the mechanism is not able to provide the requested QOP, it throws a GSSException with the BAD_QOP code.

Since some application-level protocols may wish to use tokens emitted by wrap to provide "secure framing", implementations should support the wrapping of zero-length messages.

The application will be responsible for sending the token to the peer.

Parameters:
inBuf - application data to be protected.
offset - the offset within the inBuf where the data begins.
len - the length of the data
msgProp - instance of MessageProp that is used by the application to set the desired QOP and privacy state. Set the desired QOP to 0 to request the default QOP. Upon return from this method, this object will contain the the actual privacy state that was applied to the message by the underlying mechanism.
Returns:
a byte[] containing the token to be sent to the peer.
Throws:
GSSException - containing the following major error codes: GSSException.CONTEXT_EXPIRED, GSSException.BAD_QOP, GSSException.FAILURE

wrap

void wrap(InputStream inStream,
          OutputStream outStream,
          MessageProp msgProp)
          throws GSSException
Applies per-message security services over the established security context using streams. The method will return a token with the application supplied data and a cryptographic MIC over it. The data may be encrypted if confidentiality (privacy) was requested. This method is equivalent to the byte array based wrap method.

The application will be responsible for sending the token to the peer. Typically, the application would ensure this by calling the flush method on an OutputStream that encapsulates the connection between the two peers.

The MessageProp object is instantiated by the application and used to specify a QOP value which selects cryptographic algorithms, and a privacy service to optionally encrypt the message. The underlying mechanism that is used in the call may not be able to provide the privacy service. It sets the actual privacy service that it does provide in this MessageProp object which the caller should then query upon return. If the mechanism is not able to provide the requested QOP, it throws a GSSException with the BAD_QOP code.

Since some application-level protocols may wish to use tokens emitted by wrap to provide "secure framing", implementations should support the wrapping of zero-length messages.

Parameters:
inStream - an InputStream containing the application data to be protected. All of the data that is available in inStream is used.
outStream - an OutputStream to write the protected message to.
msgProp - instance of MessageProp that is used by the application to set the desired QOP and privacy state. Set the desired QOP to 0 to request the default QOP. Upon return from this method, this object will contain the the actual privacy state that was applied to the message by the underlying mechanism.
Throws:
GSSException - containing the following major error codes: GSSException.CONTEXT_EXPIRED, GSSException.BAD_QOP, GSSException.FAILURE

unwrap

byte[] unwrap(byte[] inBuf,
              int offset,
              int len,
              MessageProp msgProp)
              throws GSSException
Used to process tokens generated by the wrap method on the other side of the context. The method will return the message supplied by the peer application to its wrap call, while at the same time verifying the embedded MIC for that message.

The MessageProp object is instantiated by the application and is used by the underlying mechanism to return information to the caller such as the QOP, whether confidentiality was applied to the message, and other supplementary message state information.

Since some application-level protocols may wish to use tokens emitted by wrap to provide "secure framing", implementations should support the wrapping and unwrapping of zero-length messages.

Parameters:
inBuf - a byte array containing the wrap token received from peer.
offset - the offset where the token begins.
len - the length of the token
msgProp - upon return from the method, this object will contain the applied QOP, the privacy state of the message, and supplementary information stating if the token was a duplicate, old, out of sequence or arriving after a gap.
Returns:
a byte[] containing the message unwrapped from the input token.
Throws:
GSSException - containing the following major error codes: GSSException.DEFECTIVE_TOKEN, GSSException.BAD_MIC, GSSException.CONTEXT_EXPIRED, GSSException.FAILURE

unwrap

void unwrap(InputStream inStream,
            OutputStream outStream,
            MessageProp msgProp)
            throws GSSException
Uses streams to process tokens generated by the wrap method on the other side of the context. The method will return the message supplied by the peer application to its wrap call, while at the same time verifying the embedded MIC for that message.

The MessageProp object is instantiated by the application and is used by the underlying mechanism to return information to the caller such as the QOP, whether confidentiality was applied to the message, and other supplementary message state information.

Since some application-level protocols may wish to use tokens emitted by wrap to provide "secure framing", implementations should support the wrapping and unwrapping of zero-length messages.

The format of the input token that this method reads is defined in the specification for the underlying mechanism that will be used. This method will attempt to read one of these tokens per invocation. If the mechanism token contains a definitive start and end this method may block on the InputStream if only part of the token is available. If the start and end of the token are not definitive then the method will attempt to treat all available bytes as part of the token.

Other than the possible blocking behaviour described above, this method is equivalent to the byte array based unwrap method.

Parameters:
inStream - an InputStream that contains the wrap token generated by the peer.
outStream - an OutputStream to write the application message to.
msgProp - upon return from the method, this object will contain the applied QOP, the privacy state of the message, and supplementary information stating if the token was a duplicate, old, out of sequence or arriving after a gap.
Throws:
GSSException - containing the following major error codes: GSSException.DEFECTIVE_TOKEN, GSSException.BAD_MIC, GSSException.CONTEXT_EXPIRED, GSSException.FAILURE

getMIC

byte[] getMIC(byte[] inMsg,
              int offset,
              int len,
              MessageProp msgProp)
              throws GSSException
Returns a token containing a cryptographic Message Integrity Code (MIC) for the supplied message, for transfer to the peer application. Unlike wrap, which encapsulates the user message in the returned token, only the message MIC is returned in the output token.

Note that privacy can only be applied through the wrap call.

Since some application-level protocols may wish to use tokens emitted by getMIC to provide "secure framing", implementations should support derivation of MICs from zero-length messages.

Parameters:
inMsg - the message to generate the MIC over.
offset - offset within the inMsg where the message begins.
len - the length of the message
msgProp - an instance of MessageProp that is used by the application to set the desired QOP. Set the desired QOP to 0 in msgProp to request the default QOP. Alternatively pass in null for msgProp to request the default QOP.
Returns:
a byte[] containing the token to be sent to the peer.
Throws:
GSSException - containing the following major error codes: GSSException.CONTEXT_EXPIRED, GSSException.BAD_QOP, GSSException.FAILURE

getMIC

void getMIC(InputStream inStream,
            OutputStream outStream,
            MessageProp msgProp)
            throws GSSException
Uses streams to produce a token containing a cryptographic MIC for the supplied message, for transfer to the peer application. Unlike wrap, which encapsulates the user message in the returned token, only the message MIC is produced in the output token. This method is equivalent to the byte array based getMIC method. Note that privacy can only be applied through the wrap call.

Since some application-level protocols may wish to use tokens emitted by getMIC to provide "secure framing", implementations should support derivation of MICs from zero-length messages.

Parameters:
inStream - an InputStream containing the message to generate the MIC over. All of the data that is available in inStream is used.
outStream - an OutputStream to write the output token to.
msgProp - an instance of MessageProp that is used by the application to set the desired QOP. Set the desired QOP to 0 in msgProp to request the default QOP. Alternatively pass in null for msgProp to request the default QOP.
Throws:
GSSException - containing the following major error codes: GSSException.CONTEXT_EXPIRED, GSSException.BAD_QOP, GSSException.FAILURE

verifyMIC

void verifyMIC(byte[] inToken,
               int tokOffset,
               int tokLen,
               byte[] inMsg,
               int msgOffset,
               int msgLen,
               MessageProp msgProp)
               throws GSSException
Verifies the cryptographic MIC, contained in the token parameter, over the supplied message.

The MessageProp object is instantiated by the application and is used by the underlying mechanism to return information to the caller such as the QOP indicating the strength of protection that was applied to the message and other supplementary message state information.

Since some application-level protocols may wish to use tokens emitted by getMIC to provide "secure framing", implementations should support the calculation and verification of MICs over zero-length messages.

Parameters:
inToken - the token generated by peer's getMIC method.
tokOffset - the offset within the inToken where the token begins.
tokLen - the length of the token.
inMsg - the application message to verify the cryptographic MIC over.
msgOffset - the offset in inMsg where the message begins.
msgLen - the length of the message.
msgProp - upon return from the method, this object will contain the applied QOP and supplementary information stating if the token was a duplicate, old, out of sequence or arriving after a gap.
Throws:
GSSException - containing the following major error codes: GSSException.DEFECTIVE_TOKEN GSSException.BAD_MIC GSSException.CONTEXT_EXPIRED GSSException.FAILURE

verifyMIC

void verifyMIC(InputStream tokStream,
               InputStream msgStream,
               MessageProp msgProp)
               throws GSSException
Uses streams to verify the cryptographic MIC, contained in the token parameter, over the supplied message. This method is equivalent to the byte array based verifyMIC method. The MessageProp object is instantiated by the application and is used by the underlying mechanism to return information to the caller such as the QOP indicating the strength of protection that was applied to the message and other supplementary message state information.

Since some application-level protocols may wish to use tokens emitted by getMIC to provide "secure framing", implementations should support the calculation and verification of MICs over zero-length messages.

The format of the input token that this method reads is defined in the specification for the underlying mechanism that will be used. This method will attempt to read one of these tokens per invocation. If the mechanism token contains a definitive start and end this method may block on the InputStream if only part of the token is available. If the start and end of the token are not definitive then the method will attempt to treat all available bytes as part of the token.

Other than the possible blocking behaviour described above, this method is equivalent to the byte array based verifyMIC method.

Parameters:
tokStream - an InputStream containing the token generated by the peer's getMIC method.
msgStream - an InputStream containing the application message to verify the cryptographic MIC over. All of the data that is available in msgStream is used.
msgProp - upon return from the method, this object will contain the applied QOP and supplementary information stating if the token was a duplicate, old, out of sequence or arriving after a gap.
Throws:
GSSException - containing the following major error codes: GSSException.DEFECTIVE_TOKEN GSSException.BAD_MIC GSSException.CONTEXT_EXPIRED GSSException.FAILURE

export

byte[] export()
              throws GSSException
Exports this context so that another process may import it.. Provided to support the sharing of work between multiple processes. This routine will typically be used by the context-acceptor, in an application where a single process receives incoming connection requests and accepts security contexts over them, then passes the established context to one or more other processes for message exchange.

This method deactivates the security context and creates an interprocess token which, when passed to GSSManager.createContext in another process, will re-activate the context in the second process. Only a single instantiation of a given context may be active at any one time; a subsequent attempt by a context exporter to access the exported security context will fail.

The implementation may constrain the set of processes by which the interprocess token may be imported, either as a function of local security policy, or as a result of implementation decisions. For example, some implementations may constrain contexts to be passed only between processes that run under the same account, or which are part of the same process group.

The interprocess token may contain security-sensitive information (for example cryptographic keys). While mechanisms are encouraged to either avoid placing such sensitive information within interprocess tokens, or to encrypt the token before returning it to the application, in a typical GSS-API implementation this may not be possible. Thus the application must take care to protect the interprocess token, and ensure that any process to which the token is transferred is trustworthy.

Implementations are not required to support the inter-process transfer of security contexts. Calling the isTransferable method will indicate if the context object is transferable.

Calling this method on a context that is not exportable will result in this exception being thrown with the error code GSSException.UNAVAILABLE.

Returns:
a byte[] containing the exported context
Throws:
GSSException - containing the following major error codes: GSSException.UNAVAILABLE, GSSException.CONTEXT_EXPIRED, GSSException.NO_CONTEXT, GSSException.FAILURE
See Also:
GSSManager.createContext(byte[])

requestMutualAuth

void requestMutualAuth(boolean state)
                       throws GSSException
Requests that mutual authentication be done during context establishment. This request can only be made on the context initiator's side and it has to be done prior to the first call to initSecContext.

Not all mechanisms support mutual authentication and some mechanisms might require mutual authentication even if the application doesn't. Therefore, the application should check to see if the request was honored with the getMutualAuthState method.

Parameters:
state - a boolean value indicating whether mutual authentication shouls be used or not.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE
See Also:
getMutualAuthState()

requestReplayDet

void requestReplayDet(boolean state)
                      throws GSSException
Requests that replay detection be enabled for the per-message security services after context establishemnt. This request can only be made on the context initiator's side and it has to be done prior to the first call to initSecContext. During context establishment replay detection is not an option and is a function of the underlying mechanism's capabilities.

Not all mechanisms support replay detection and some mechanisms might require replay detection even if the application doesn't. Therefore, the application should check to see if the request was honored with the getReplayDetState method. If replay detection is enabled then the MessageProp.isDuplicateToken and MessageProp.isOldToken methods will return valid results for the MessageProp object that is passed in to the unwrap method or the verifyMIC method.

Parameters:
state - a boolean value indicating whether replay detection should be enabled over the established context or not.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE
See Also:
getReplayDetState()

requestSequenceDet

void requestSequenceDet(boolean state)
                        throws GSSException
Requests that sequence checking be enabled for the per-message security services after context establishemnt. This request can only be made on the context initiator's side and it has to be done prior to the first call to initSecContext. During context establishment sequence checking is not an option and is a function of the underlying mechanism's capabilities.

Not all mechanisms support sequence checking and some mechanisms might require sequence checking even if the application doesn't. Therefore, the application should check to see if the request was honored with the getSequenceDetState method. If sequence checking is enabled then the MessageProp.isDuplicateToken, MessageProp.isOldToken, MessageProp.isUnseqToken, and MessageProp.isGapToken methods will return valid results for the MessageProp object that is passed in to the unwrap method or the verifyMIC method.

Parameters:
state - a boolean value indicating whether sequence checking should be enabled over the established context or not.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE
See Also:
getSequenceDetState()

requestCredDeleg

void requestCredDeleg(boolean state)
                      throws GSSException
Requests that the initiator's credentials be delegated to the acceptor during context establishment. This request can only be made on the context initiator's side and it has to be done prior to the first call to initSecContext. Not all mechanisms support credential delegation. Therefore, an application that desires delegation should check to see if the request was honored with the getCredDelegState method. If the application indicates that delegation must not be used, then the mechanism will honor the request and delegation will not occur. This is an exception to the general rule that a mechanism may enable a service even if it is not requested.

Parameters:
state - a boolean value indicating whether the credentials should be delegated or not.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE
See Also:
getCredDelegState()

requestAnonymity

void requestAnonymity(boolean state)
                      throws GSSException
Requests that the initiator's identity not be disclosed to the acceptor. This request can only be made on the context initiator's side and it has to be done prior to the first call to initSecContext. Not all mechanisms support anonymity for the initiator. Therefore, the application should check to see if the request was honored with the getAnonymityState method.

Parameters:
state - a boolean value indicating if the initiator should be authenticated to the acceptor as an anonymous principal.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE
See Also:
getAnonymityState()

requestConf

void requestConf(boolean state)
                 throws GSSException
Requests that data confidentiality be enabled for the wrap method. This request can only be made on the context initiator's side and it has to be done prior to the first call to initSecContext. Not all mechanisms support confidentiality and other mechanisms might enable it even if the application doesn't request it. The application may check to see if the request was honored with the getConfState method. If confidentiality is enabled, only then will the mechanism honor a request for privacy in the MessageProp object that is passed in to the wrap method.

Enabling confidentiality will also automatically enable integrity.

Parameters:
state - a boolean value indicating whether confidentiality should be enabled or not.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE
See Also:
getConfState(), getIntegState(), requestInteg(boolean), MessageProp

requestInteg

void requestInteg(boolean state)
                  throws GSSException
Requests that data integrity be enabled for the wrap and getMICmethods. This request can only be made on the context initiator's side and it has to be done prior to the first call to initSecContext. Not all mechanisms support integrity and other mechanisms might enable it even if the application doesn't request it. The application may check to see if the request was honored with the getIntegState method.

Disabling integrity will also automatically disable confidentiality.

Parameters:
state - a boolean value indicating whether integrity should be enabled or not.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE
See Also:
getIntegState()

requestLifetime

void requestLifetime(int lifetime)
                     throws GSSException
Requests a lifetime in seconds for the context. This method can only be called on the context initiator's side and it has to be done prior to the first call to initSecContext.

The actual lifetime of the context will depend on the capabilites of the underlying mechanism and the application should call the getLifetime method to determine this.

Parameters:
lifetime - the desired context lifetime in seconds. Use INDEFINITE_LIFETIME to request an indefinite lifetime and DEFAULT_LIFETIME to request a default lifetime.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE
See Also:
getLifetime()

setChannelBinding

void setChannelBinding(ChannelBinding cb)
                       throws GSSException
Sets the channel bindings to be used during context establishment. This method can be called on both the context initiator's and the context acceptor's side, but it must be called before context establishment begins. This means that an initiator must call it before the first call to initSecContext and the acceptor must call it before the first call to acceptSecContext.

Parameters:
cb - the channel bindings to use.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE

getCredDelegState

boolean getCredDelegState()
Determines if credential delegation is enabled on this context. It can be called by both the context initiator and the context acceptor. For a definitive answer this method must be called only after context establishment is complete. Note that if an initiator requests that delegation not be allowed the requestCredDeleg method will honor that request and this method will return false on the initiator's side from that point onwards.

Returns:
true if delegation is enabled, false otherwise.
See Also:
requestCredDeleg(boolean)

getMutualAuthState

boolean getMutualAuthState()
Determines if mutual authentication is enabled on this context. It can be called by both the context initiator and the context acceptor. For a definitive answer this method must be called only after context establishment is complete. An initiator that requests mutual authentication can call this method after context completion and dispose the context if its request was not honored.

Returns:
true if mutual authentication is enabled, false otherwise.
See Also:
requestMutualAuth(boolean)

getReplayDetState

boolean getReplayDetState()
Determines if replay detection is enabled for the per-message security services from this context. It can be called by both the context initiator and the context acceptor. For a definitive answer this method must be called only after context establishment is complete. An initiator that requests replay detection can call this method after context completion and dispose the context if its request was not honored.

Returns:
true if replay detection is enabled, false otherwise.
See Also:
requestReplayDet(boolean)

getSequenceDetState

boolean getSequenceDetState()
Determines if sequence checking is enabled for the per-message security services from this context. It can be called by both the context initiator and the context acceptor. For a definitive answer this method must be called only after context establishment is complete. An initiator that requests sequence checking can call this method after context completion and dispose the context if its request was not honored.

Returns:
true if sequence checking is enabled, false otherwise.
See Also:
requestSequenceDet(boolean)

getAnonymityState

boolean getAnonymityState()
Determines if the context initiator is anonymously authenticated to the context acceptor. It can be called by both the context initiator and the context acceptor, and at any time. On the initiator side, a call to this method determines if the identity of the initiator has been disclosed in any of the context establishment tokens that might have been generated thus far by initSecContext. An initiator that absolutely must be authenticated anonymously should call this method after each call to initSecContext to determine if the generated token should be sent to the peer or the context aborted. On the acceptor side, a call to this method determines if any of the tokens processed by acceptSecContext thus far have divulged the identity of the initiator.

Returns:
true if the context initiator is still anonymous, false otherwise.
See Also:
requestAnonymity(boolean)

isTransferable

boolean isTransferable()
                       throws GSSException
Determines if the context is transferable to other processes through the use of the export method. This call is only valid on fully established contexts.

Returns:
true if this context can be exported, false otherwise.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE

isProtReady

boolean isProtReady()
Determines if the context is ready for per message operations to be used over it. Some mechanisms may allow the usage of the per-message operations before the context is fully established.

Returns:
true if methods like wrap, unwrap, getMIC, and verifyMIC can be used with this context at the current stage of context establishment, false otherwise.

getConfState

boolean getConfState()
Determines if data confidentiality is available over the context. This method can be called by both the context initiator and the context acceptor, but only after one of isProtReady or isEstablished return true. If this method returns true, so will getIntegState

Returns:
true if confidentiality services are available, false otherwise.
See Also:
requestConf(boolean)

getIntegState

boolean getIntegState()
Determines if data integrity is available over the context. This method can be called by both the context initiator and the context acceptor, but only after one of isProtReady or isEstablished return true. This method will always return true if getConfState returns true.

Returns:
true if integrity services are available, false otherwise.
See Also:
requestInteg(boolean)

getLifetime

int getLifetime()
Determines what the remaining lifetime for this context is. It can be called by both the context initiator and the context acceptor, but for a definitive answer it should be called only after isEstablished returns true.

Returns:
the remaining lifetime in seconds
See Also:
requestLifetime(int)

getSrcName

GSSName getSrcName()
                   throws GSSException
Returns the name of the context initiator. This call is valid only after one of isProtReady or isEstablished return true.

Returns:
a GSSName that is an MN containing the name of the context initiator.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE
See Also:
GSSName

getTargName

GSSName getTargName()
                    throws GSSException
Returns the name of the context acceptor. This call is valid only after one of isProtReady or isEstablished return true.

Returns:
a GSSName that is an MN containing the name of the context acceptor.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE

getMech

Oid getMech()
            throws GSSException
Determines what mechanism is being used for this context. This method may be called before the context is fully established, but the mechanism returned may change on successive calls in the negotiated mechanism case.

Returns:
the Oid of the mechanism being used
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE

getDelegCred

GSSCredential getDelegCred()
                           throws GSSException
Obtains the credentials delegated by the context initiator to the context acceptor. It should be called only on the context acceptor's side, and once the context is fully established. The caller can use the method getCredDelegState to determine if there are any delegated credentials.

Returns:
a GSSCredential containing the initiator's delegated credentials, or null is no credentials were delegated.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE

isInitiator

boolean isInitiator()
                    throws GSSException
Determines if this is the context initiator. This can be called on both the context initiator's and context acceptor's side.

Returns:
true if this is the context initiator, false if it is the context acceptor.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


GSSCredential

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.ietf.jgss
Interface GSSCredential

All Superinterfaces:
Cloneable
public interface GSSCredential
extends Cloneable

This interface encapsulates the GSS-API credentials for an entity. A credential contains all the necessary cryptographic information to enable the creation of a context on behalf of the entity that it represents. It may contain multiple, distinct, mechanism specific credential elements, each containing information for a specific security mechanism, but all referring to the same entity. A credential may be used to perform context initiation, acceptance, or both.

Credentials are instantiated using one of the createCredential methods in the GSSManager class. GSS-API credential creation is not intended to provide a "login to the network" function, as such a function would involve the creation of new credentials rather than merely acquiring a handle to existing credentials. The section on credential acquisition in the package level description describes how existing credentials are acquired in the Java platform. GSS-API implementations must impose a local access-control policy on callers to prevent unauthorized callers from acquiring credentials to which they are not entitled.

Applications will create a credential object passing the desired parameters. The application can then use the query methods to obtain specific information about the instantiated credential object. When the credential is no longer needed, the application should call the dispose method to release any resources held by the credential object and to destroy any cryptographically sensitive information.

This example code demonstrates the creation of a GSSCredential implementation for a specific entity, querying of its fields, and its release when it is no longer needed:

    GSSManager manager = GSSManager.getInstance();

    // start by creating a name object for the entity
    GSSName name = manager.createName("myusername", GSSName.NT_USER_NAME);

    // now acquire credentials for the entity
    GSSCredential cred = manager.createCredential(name,
                    GSSCredential.ACCEPT_ONLY);

    // display credential information - name, remaining lifetime,
    // and the mechanisms it has been acquired over
    System.out.println(cred.getName().toString());
    System.out.println(cred.getRemainingLifetime());

    Oid [] mechs = cred.getMechs();
    if (mechs != null) {
            for (int i = 0; i < mechs.length; i++)
                    System.out.println(mechs[i].toString());
    }

    // release system resources held by the credential
    cred.dispose();

Since:
1.4
See Also:
GSSManager.createCredential(int),
GSSManager.createCredential(GSSName, int, Oid, int),
GSSManager.createCredential(GSSName, int, Oid[], int),
dispose()

Field Summary
static int | ACCEPT_ONLY Credential usage flag requesting that it be usable for context acceptance only.
static int | DEFAULT_LIFETIME A lifetime constant representing the default credential lifetime.
static int | INDEFINITE_LIFETIME A lifetime constant representing indefinite credential lifetime.
static int | INITIATE_AND_ACCEPT Credential usage flag requesting that it be usable for both context initiation and acceptance.
static int | INITIATE_ONLY Credential usage flag requesting that it be usable for context initiation only.
Method Summary
void | add(GSSName name, int initLifetime, int acceptLifetime, Oid mech, int usage) Adds a mechanism specific credential-element to an existing credential.
void | dispose() Releases any sensitive information that the GSSCredential object may be containing.
boolean | equals(Object another) Tests if this GSSCredential asserts the same entity as the supplied object.
Oid[] | getMechs() Returns a list of mechanisms supported by this credential.
GSSName | getName() Retrieves the name of the entity that the credential asserts.
GSSName | getName(Oid mech) Retrieves a Mechanism Name of the entity that the credential asserts.
int | getRemainingAcceptLifetime(Oid mech) Returns the lifetime in seconds for the credential to remain capable of accepting security contexts using the specified mechanism.
int | getRemainingInitLifetime(Oid mech) Returns the lifetime in seconds for the credential to remain capable of initiating security contexts using the specified mechanism.
int | getRemainingLifetime() Returns the remaining lifetime in seconds for a credential.
int | getUsage() Returns the credential usage mode.
int | getUsage(Oid mech) Returns the credential usage mode for a specific mechanism.
int | hashCode() Returns a hashcode value for this GSSCredential.

Field Detail

INITIATE_AND_ACCEPT

static final int INITIATE_AND_ACCEPT
Credential usage flag requesting that it be usable for both context initiation and acceptance.

See Also:
Constant Field Values

INITIATE_ONLY

static final int INITIATE_ONLY
Credential usage flag requesting that it be usable for context initiation only.

See Also:
Constant Field Values

ACCEPT_ONLY

static final int ACCEPT_ONLY
Credential usage flag requesting that it be usable for context acceptance only.

See Also:
Constant Field Values

DEFAULT_LIFETIME

static final int DEFAULT_LIFETIME
A lifetime constant representing the default credential lifetime. This value it set to 0.

See Also:
Constant Field Values

INDEFINITE_LIFETIME

static final int INDEFINITE_LIFETIME
A lifetime constant representing indefinite credential lifetime. This value must is set to the maximum integer value in Java - Integer.MAX_VALUE.

See Also:
Constant Field Values
Method Detail

dispose

void dispose()
             throws GSSException
Releases any sensitive information that the GSSCredential object may be containing. Applications should call this method as soon as the credential is no longer needed to minimize the time any sensitive information is maintained.

Throws:
GSSException - containing the following major error codes: GSSException.FAILURE

getName

GSSName getName()
                throws GSSException
Retrieves the name of the entity that the credential asserts.

Returns:
a GSSName representing the entity
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE

getName

GSSName getName(Oid mech)
                throws GSSException
Retrieves a Mechanism Name of the entity that the credential asserts. This is equivalent to calling canonicalize on the value returned by the other form of getName.

Parameters:
mech - the Oid of the mechanism for which the Mechanism Name should be returned.
Returns:
a GSSName representing the entity canonicalized for the desired mechanism
Throws:
GSSException - containing the following major error codes: GSSException.BAD_MECH, GSSException.FAILURE

getRemainingLifetime

int getRemainingLifetime()
                         throws GSSException
Returns the remaining lifetime in seconds for a credential. The remaining lifetime is the minimum lifetime amongst all of the underlying mechanism specific credential elements.

Returns:
the minimum remaining lifetime in seconds for this credential. A return value of INDEFINITE_LIFETIME indicates that the credential does not expire. A return value of 0 indicates that the credential is already expired.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE
See Also:
getRemainingInitLifetime(Oid), getRemainingAcceptLifetime(Oid)

getRemainingInitLifetime

int getRemainingInitLifetime(Oid mech)
                             throws GSSException
Returns the lifetime in seconds for the credential to remain capable of initiating security contexts using the specified mechanism. This method queries the initiator credential element that belongs to the specified mechanism.

Parameters:
mech - the Oid of the mechanism whose intiator credential element should be queried.
Returns:
the number of seconds remaining in the life of this credential element. A return value of INDEFINITE_LIFETIME indicates that the credential element does not expire. A return value of 0 indicates that the credential element is already expired.
Throws:
GSSException - containing the following major error codes: GSSException.BAD_MECH, GSSException.FAILURE

getRemainingAcceptLifetime

int getRemainingAcceptLifetime(Oid mech)
                               throws GSSException
Returns the lifetime in seconds for the credential to remain capable of accepting security contexts using the specified mechanism. This method queries the acceptor credential element that belongs to the specified mechanism.

Parameters:
mech - the Oid of the mechanism whose acceptor credential element should be queried.
Returns:
the number of seconds remaining in the life of this credential element. A return value of INDEFINITE_LIFETIME indicates that the credential element does not expire. A return value of 0 indicates that the credential element is already expired.
Throws:
GSSException - containing the following major error codes: GSSException.BAD_MECH, GSSException.FAILURE

getUsage

int getUsage()
             throws GSSException
Returns the credential usage mode. In other words, it tells us if this credential can be used for initiating or accepting security contexts. It does not tell us which mechanism(s) has to be used in order to do so. It is expected that an application will allow the GSS-API to pick a default mechanism after calling this method.

Returns:
The return value will be one of INITIATE_ONLY, ACCEPT_ONLY, and INITIATE_AND_ACCEPT.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE

getUsage

int getUsage(Oid mech)
             throws GSSException
Returns the credential usage mode for a specific mechanism. In other words, it tells us if this credential can be used for initiating or accepting security contexts with a given underlying mechanism.

Parameters:
mech - the Oid of the mechanism whose credentials usage mode is to be determined.
Returns:
The return value will be one of INITIATE_ONLY, ACCEPT_ONLY, and INITIATE_AND_ACCEPT.
Throws:
GSSException - containing the following major error codes: GSSException.BAD_MECH, GSSException.FAILURE

getMechs

Oid[] getMechs()
               throws GSSException
Returns a list of mechanisms supported by this credential. It does not tell us which ones can be used to initiate contexts and which ones can be used to accept contexts. The application must call the getUsage method with each of the returned Oid's to determine the possible modes of usage.

Returns:
an array of Oid's corresponding to the supported mechanisms.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE

add

void add(GSSName name,
         int initLifetime,
         int acceptLifetime,
         Oid mech,
         int usage)
         throws GSSException
Adds a mechanism specific credential-element to an existing credential. This method allows the construction of credentials, one mechanism at a time.

This routine is envisioned to be used mainly by context acceptors during the creation of acceptor credentials which are to be used with a variety of clients using different security mechanisms.

This routine adds the new credential element "in-place". To add the element in a new credential, first call clone to obtain a copy of this credential, then call its add method.

As always, GSS-API implementations must impose a local access-control policy on callers to prevent unauthorized callers from acquiring credentials to which they are not entitled. Non-default values for initLifetime and acceptLifetime cannot always be honored by the underlying mechanisms, thus callers should be prepared to call getRemainingInitLifetime and getRemainingAcceptLifetime on the credential.

Parameters:
name - the name of the principal for whom this credential is to be acquired. Use null to specify the default principal.
initLifetime - the number of seconds that the credential element should remain valid for initiating of security contexts. Use GSSCredential.INDEFINITE_LIFETIME to request that the credentials have the maximum permitted lifetime for this. Use GSSCredential.DEFAULT_LIFETIME to request default credential lifetime for this.
acceptLifetime - the number of seconds that the credential element should remain valid for accepting security contexts. Use GSSCredential.INDEFINITE_LIFETIME to request that the credentials have the maximum permitted lifetime for this. Use GSSCredential.DEFAULT_LIFETIME to request default credential lifetime for this.
mech - the mechanism over which the credential is to be acquired.
usage - the usage mode that this credential element should add to the credential. The value of this parameter must be one of: INITIATE_AND_ACCEPT, ACCEPT_ONLY, and INITIATE_ONLY.
Throws:
GSSException - containing the following major error codes: GSSException.DUPLICATE_ELEMENT, GSSException.BAD_MECH, GSSException.BAD_NAMETYPE, GSSException.NO_CRED, GSSException.CREDENTIALS_EXPIRED, GSSException.FAILURE

equals

boolean equals(Object another)
Tests if this GSSCredential asserts the same entity as the supplied object. The two credentials must be acquired over the same mechanisms and must refer to the same principal.

Overrides:
equals in class Object
Parameters:
another - another GSSCredential for comparison to this one
Returns:
true if the two GSSCredentials assert the same entity; false otherwise.
See Also:
Object.hashCode(), Hashtable

hashCode

int hashCode()
Returns a hashcode value for this GSSCredential.

Overrides:
hashCode in class Object
Returns:
a hashCode value
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


GSSException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.ietf.jgss
Class GSSException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.ietf.jgss.GSSException
All Implemented Interfaces:
Serializable
public class GSSException
extends Exception

This exception is thrown whenever a GSS-API error occurs, including any mechanism specific error. It may contain both the major and the minor GSS-API status codes. Major error codes are those defined at the GSS-API level in this class. Minor error codes are mechanism specific error codes that can provide additional information. The underlying mechanism implementation is responsible for setting appropriate minor status codes when throwing this exception. Aside from delivering the numeric error codes to the caller, this class performs the mapping from their numeric values to textual representations.

Since:
1.4
See Also:
Serialized Form

Field Summary
static int | BAD_BINDINGS Channel bindings mismatch.
static int | BAD_MECH Unsupported mechanism requested.
static int | BAD_MIC Token had invalid integrity check.
static int | BAD_NAME Invalid name provided.
static int | BAD_NAMETYPE Name of unsupported type provided.
static int | BAD_QOP Unsupported QOP value.
static int | BAD_STATUS Invalid status code.
static int | CONTEXT_EXPIRED Security context expired.
static int | CREDENTIALS_EXPIRED Expired credentials.
static int | DEFECTIVE_CREDENTIAL Defective credentials.
static int | DEFECTIVE_TOKEN Defective token.
static int | DUPLICATE_ELEMENT Duplicate credential element requested.
static int | DUPLICATE_TOKEN The token was a duplicate of an earlier token.
static int | FAILURE General failure, unspecified at GSS-API level.
static int | GAP_TOKEN An expected per-message token was not received.
static int | NAME_NOT_MN Name contains multi-mechanism elements.
static int | NO_CONTEXT Invalid security context.
static int | NO_CRED Invalid credentials.
static int | OLD_TOKEN The token's validity period has expired.
static int | UNAUTHORIZED Operation unauthorized.
static int | UNAVAILABLE Operation unavailable.
static int | UNSEQ_TOKEN A later token has already been processed.
Constructor Summary
GSSException(int majorCode)
Creates a GSSException object with a specified major code.
GSSException(int majorCode, int minorCode, String minorString)
Creates a GSSException object with the specified major code, minor code, and minor code textual explanation.
Method Summary
int | getMajor() Returns the GSS-API level major error code for the problem causing this exception to be thrown.
String | getMajorString() Returns a string explaining the GSS-API level major error code in this exception.
String | getMessage() Returns a textual representation of both the major and the minor status codes.
int | getMinor() Returns the mechanism level error code for the problem causing this exception to be thrown.
String | getMinorString() Returns a string explaining the mechanism specific error code.
void | setMinor(int minorCode, String message) Used by the exception thrower to set the mechanism level minor error code and its string explanation.
String | toString() Returns a textual representation of both the major and the minor status codes.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

BAD_BINDINGS

public static final int BAD_BINDINGS
Channel bindings mismatch.

See Also:
Constant Field Values

BAD_MECH

public static final int BAD_MECH
Unsupported mechanism requested.

See Also:
Constant Field Values

BAD_NAME

public static final int BAD_NAME
Invalid name provided.

See Also:
Constant Field Values

BAD_NAMETYPE

public static final int BAD_NAMETYPE
Name of unsupported type provided.

See Also:
Constant Field Values

BAD_STATUS

public static final int BAD_STATUS
Invalid status code.

See Also:
Constant Field Values

BAD_MIC

public static final int BAD_MIC
Token had invalid integrity check.

See Also:
Constant Field Values

CONTEXT_EXPIRED

public static final int CONTEXT_EXPIRED
Security context expired.

See Also:
Constant Field Values

CREDENTIALS_EXPIRED

public static final int CREDENTIALS_EXPIRED
Expired credentials.

See Also:
Constant Field Values

DEFECTIVE_CREDENTIAL

public static final int DEFECTIVE_CREDENTIAL
Defective credentials.

See Also:
Constant Field Values

DEFECTIVE_TOKEN

public static final int DEFECTIVE_TOKEN
Defective token.

See Also:
Constant Field Values

FAILURE

public static final int FAILURE
General failure, unspecified at GSS-API level.

See Also:
Constant Field Values

NO_CONTEXT

public static final int NO_CONTEXT
Invalid security context.

See Also:
Constant Field Values

NO_CRED

public static final int NO_CRED
Invalid credentials.

See Also:
Constant Field Values

BAD_QOP

public static final int BAD_QOP
Unsupported QOP value.

See Also:
Constant Field Values

UNAUTHORIZED

public static final int UNAUTHORIZED
Operation unauthorized.

See Also:
Constant Field Values

UNAVAILABLE

public static final int UNAVAILABLE
Operation unavailable.

See Also:
Constant Field Values

DUPLICATE_ELEMENT

public static final int DUPLICATE_ELEMENT
Duplicate credential element requested.

See Also:
Constant Field Values

NAME_NOT_MN

public static final int NAME_NOT_MN
Name contains multi-mechanism elements.

See Also:
Constant Field Values

DUPLICATE_TOKEN

public static final int DUPLICATE_TOKEN
The token was a duplicate of an earlier token. This is a fatal error code that may occur during context establishment. It is not used to indicate supplementary status values. The MessageProp object is used for that purpose.

See Also:
Constant Field Values

OLD_TOKEN

public static final int OLD_TOKEN
The token's validity period has expired. This is a fatal error code that may occur during context establishment. It is not used to indicate supplementary status values. The MessageProp object is used for that purpose.

See Also:
Constant Field Values

UNSEQ_TOKEN

public static final int UNSEQ_TOKEN
A later token has already been processed. This is a fatal error code that may occur during context establishment. It is not used to indicate supplementary status values. The MessageProp object is used for that purpose.

See Also:
Constant Field Values

GAP_TOKEN

public static final int GAP_TOKEN
An expected per-message token was not received. This is a fatal error code that may occur during context establishment. It is not used to indicate supplementary status values. The MessageProp object is used for that purpose.

See Also:
Constant Field Values
Constructor Detail

GSSException

public GSSException(int majorCode)
Creates a GSSException object with a specified major code.

Parameters:
majorCode - the The GSS error code for the problem causing this exception to be thrown.

GSSException

public GSSException(int majorCode,
                    int minorCode,
                    String minorString)
Creates a GSSException object with the specified major code, minor code, and minor code textual explanation. This constructor is to be used when the exception is originating from the underlying mechanism level. It allows the setting of both the GSS code and the mechanism code.

Parameters:
majorCode - the GSS error code for the problem causing this exception to be thrown.
minorCode - the mechanism level error code for the problem causing this exception to be thrown.
minorString - the textual explanation of the mechanism error code.
Method Detail

getMajor

public int getMajor()
Returns the GSS-API level major error code for the problem causing this exception to be thrown. Major error codes are defined at the mechanism independent GSS-API level in this class. Mechanism specific error codes that might provide more information aer set as the minor error code.

Returns:
int the GSS-API level major error code causing this exception
See Also:
getMajorString(),
getMinor(),
getMinorString()

getMinor

public int getMinor()
Returns the mechanism level error code for the problem causing this exception to be thrown. The minor code is set by the underlying mechanism.

Returns:
int the mechanism error code; 0 indicates that it has not been set.
See Also:
getMinorString(), setMinor(int, java.lang.String)

getMajorString

public String getMajorString()
Returns a string explaining the GSS-API level major error code in this exception.

Returns:
String explanation string for the major error code
See Also:
getMajor(), toString()

getMinorString

public String getMinorString()
Returns a string explaining the mechanism specific error code. If the minor status code is 0, then no mechanism level error details will be available.

Returns:
String a textual explanation of mechanism error code
See Also:
getMinor(),
getMajorString(),
toString()

setMinor

public void setMinor(int minorCode,
                     String message)
Used by the exception thrower to set the mechanism level minor error code and its string explanation. This is used by mechanism providers to indicate error details.

Parameters:
minorCode - the mechanism specific error code
message - textual explanation of the mechanism error code
See Also:
getMinor()

toString

public String toString()
Returns a textual representation of both the major and the minor status codes.

Overrides:
toString in class Throwable
Returns:
a String with the error descriptions

getMessage

public String getMessage()
Returns a textual representation of both the major and the minor status codes.

Overrides:
getMessage in class Throwable
Returns:
a String with the error descriptions
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


GSSManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.ietf.jgss
Class GSSManager

java.lang.Object
    extended by  org.ietf.jgss.GSSManager

public abstract class GSSManager
extends Object

This class serves as a factory for other important GSS-API classes and also provides information about the mechanisms that are supported. It can create instances of classes implementing the following three GSS-API interfaces: GSSName, GSSCredential, and GSSContext. It also has methods to query for the list of available mechanisms and the nametypes that each mechanism supports.

An instance of the default GSSManager subclass may be obtained through the static method getInstance, but applications are free to instantiate other subclasses of GSSManager. The default GSSManager instance will support the Kerberos v5 GSS-API mechanism in addition to any others. This mechanism is identified by the Oid "1.2.840.113554.1.2.2" and is defined in RFC 1964.

A subclass extending the GSSManager abstract class may be implemented as a modular provider based layer that utilizes some well known service provider specification. The GSSManager API allows the application to set provider preferences on such an implementation. These methods also allow the implementation to throw a well-defined exception in case provider based configuration is not supported. Applications that expect to be portable should be aware of this and recover cleanly by catching the exception.

It is envisioned that there will be three most common ways in which providers will be used:

  1. The application does not care about what provider is used (the default case).
  2. The application wants a particular provider to be used preferentially, either for a particular mechanism or all the time, irrespective of mechanism.
  3. The application wants to use the locally configured providers as far as possible but if support is missing for one or more mechanisms then it wants to fall back on its own provider.

The GSSManager class has two methods that enable these modes of usage: addProviderAtFront and addProviderAtEnd. These methods have the effect of creating an ordered list of <provider, oid> pairs where each pair indicates a preference of provider for a given oid.

It is important to note that there are certain interactions between the different GSS-API objects that are created by a GSSManager, where the provider that is used for a particular mechanism might need to be consistent across all objects. For instance, if a GSSCredential contains elements from a provider p for a mechanism m, it should generally be passed in to a GSSContext that will use provider p for the mechanism m. A simple rule of thumb that will maximize portability is that objects created from different GSSManager's should not be mixed, and if possible, a different GSSManager instance should be created if the application wants to invoke the addProviderAtFront method on a GSSManager that has already created an object.

Here is some sample code showing how the GSSManager might be used:

     GSSManager manager = GSSManager.getInstance();

     Oid krb5Mechanism = new Oid("1.2.840.113554.1.2.2");
     Oid krb5PrincipalNameType = new Oid("1.2.840.113554.1.2.2.1");

     // Identify who the client wishes to be
     GSSName userName = manager.createName("duke", GSSName.NT_USER_NAME);

     // Identify the name of the server. This uses a Kerberos specific
     // name format.
     GSSName serverName = manager.createName("nfs/foo.sun.com",
                                             krb5PrincipalNameType);

     // Acquire credentials for the user
     GSSCredential userCreds = manager.createCredential(userName,
                                             GSSCredential.DEFAULT_LIFETIME,
                                             krb5Mechanism,
                                             GSSCredential.INITIATE_ONLY);

     // Instantiate and initialize a security context that will be
     // established with the server
     GSSContext context = manager.createContext(serverName,
                                                krb5Mechanism,
                                                userCreds,
                                                GSSContext.DEFAULT_LIFETIME);

The server side might use the following variation of this source:

     // Acquire credentials for the server
     GSSCredential serverCreds = manager.createCredential(serverName,
                                             GSSCredential.DEFAULT_LIFETIME,
                                             krb5Mechanism,
                                             GSSCredential.ACCEPT_ONLY);

     // Instantiate and initialize a security context that will
     // wait for an establishment request token from the client
     GSSContext context = manager.createContext(serverCreds);

Since:
1.4
See Also:
GSSName, GSSCredential, GSSContext

Constructor Summary
GSSManager()
Method Summary
abstract void | addProviderAtEnd(Provider p, Oid mech) This method is used to indicate to the GSSManager that the application would like a particular provider to be used if no other provider can be found that supports the given mechanism.
abstract void | addProviderAtFront(Provider p, Oid mech) This method is used to indicate to the GSSManager that the application would like a particular provider to be used ahead of all others when support is desired for the given mechanism.
abstract GSSContext | createContext(byte[] interProcessToken) Factory method for creating a previously exported context.
abstract GSSContext | createContext(GSSCredential myCred) Factory method for creating a context on the acceptor' side.
abstract GSSContext | createContext(GSSName peer, Oid mech, GSSCredential myCred, int lifetime) Factory method for creating a context on the initiator's side.
abstract GSSCredential | createCredential(GSSName name, int lifetime, Oid[] mechs, int usage) Factory method for acquiring credentials over a set of mechanisms.
abstract GSSCredential | createCredential(GSSName name, int lifetime, Oid mech, int usage) Factory method for acquiring a single mechanism credential.
abstract GSSCredential | createCredential(int usage) Factory method for acquiring default credentials.
abstract GSSName | createName(byte[] name, Oid nameType) Factory method to convert a byte array containing a name from the specified namespace to a GSSName object.
abstract GSSName | createName(byte[] name, Oid nameType, Oid mech) Factory method to convert a byte array containing a name from the specified namespace to a GSSName object and canonicalize it at the same time for a mechanism.
abstract GSSName | createName(String nameStr, Oid nameType) Factory method to convert a string name from the specified namespace to a GSSName object.
abstract GSSName | createName(String nameStr, Oid nameType, Oid mech) Factory method to convert a string name from the specified namespace to a GSSName object and canonicalize it at the same time for a mechanism.
static GSSManager | getInstance() Returns the default GSSManager implementation.
abstract Oid[] | getMechs() Returns a list of mechanisms that are available to GSS-API callers through this GSSManager.
abstract Oid[] | getMechsForName(Oid nameType) Returns a list of mechanisms that support the indicated name type.
abstract Oid[] | getNamesForMech(Oid mech) Returns then name types supported by the indicated mechanism.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GSSManager

public GSSManager()
Method Detail

getInstance

public static GSSManager getInstance()
Returns the default GSSManager implementation.

Returns:
a GSSManager implementation

getMechs

public abstract Oid[] getMechs()
Returns a list of mechanisms that are available to GSS-API callers through this GSSManager. The default GSSManager obtained from the getInstance() method includes the Oid "1.2.840.113554.1.2.2" in its list. This Oid identifies the Kerberos v5 GSS-API mechanism that is defined in RFC 1964.

Returns:
an array of Oid objects corresponding to the mechanisms that are available. A null value is returned when no mechanism are available (an example of this would be when mechanism are dynamically configured, and currently no mechanisms are installed).

getNamesForMech

public abstract Oid[] getNamesForMech(Oid mech)
                               throws GSSException
Returns then name types supported by the indicated mechanism.

The default GSSManager instance includes support for the Kerberos v5 mechanism. When this mechanism ("1.2.840.113554.1.2.2") is indicated, the returned list will contain at least the following nametypes: GSSName.NT_HOSTBASED_SERVICE, GSSName.NT_EXPORT_NAME, and the Kerberos v5 specific Oid "1.2.840.113554.1.2.2.1". The namespace for the Oid "1.2.840.113554.1.2.2.1" is defined in RFC 1964.

Parameters:
mech - the Oid of the mechanism to query
Returns:
an array of Oid objects corresponding to the name types that the mechanism supports.
Throws:
GSSException - containing the following major error codes: GSSException.BAD_MECH GSSException.FAILURE
See Also:
getMechsForName(Oid)

getMechsForName

public abstract Oid[] getMechsForName(Oid nameType)
Returns a list of mechanisms that support the indicated name type.

The Kerberos v5 mechanism ("1.2.840.113554.1.2.2") will always be returned in this list when the indicated nametype is one of GSSName.NT_HOSTBASED_SERVICE, GSSName.NT_EXPORT_NAME, or "1.2.840.113554.1.2.2.1".

Parameters:
nameType - the Oid of the name type to look for
Returns:
an array of Oid objects corresponding to the mechanisms that support the specified name type. null is returned when no mechanisms are found to support the specified name type.
See Also:
getNamesForMech(Oid)

createName

public abstract GSSName createName(String nameStr,
                                   Oid nameType)
                            throws GSSException
Factory method to convert a string name from the specified namespace to a GSSName object. In general, the GSSName object created will contain multiple representations of the name, one for each mechanism that is supported; two examples that are exceptions to this are when the namespace type parameter indicates NT_EXPORT_NAME or when the GSS-API implementation is not multi-mechanism. It is not recommended to use this method with a NT_EXPORT_NAME type because representing a previously exported name consisting of abitrary bytes as a String might cause problems with character encoding schemes. In such cases it is recommended that the bytes be passed in directly to the overloaded form of this method createName.

Parameters:
nameStr - the string representing a printable form of the name to create.
nameType - the Oid specifying the namespace of the printable name supplied. null can be used to specify that a mechanism specific default printable syntax should be assumed by each mechanism that examines nameStr. It is not advisable to use the nametype NT_EXPORT_NAME with this method.
Returns:
a GSSName representing the indicated principal
Throws:
GSSException - containing the following major error codes: GSSException.BAD_NAMETYPE, GSSException.BAD_NAME, GSSException.BAD_MECH, GSSException.FAILURE
See Also:
GSSName, GSSName.NT_EXPORT_NAME

createName

public abstract GSSName createName(byte[] name,
                                   Oid nameType)
                            throws GSSException
Factory method to convert a byte array containing a name from the specified namespace to a GSSName object. In general, the GSSName object created will contain multiple representations of the name, one for each mechanism that is supported; two examples that are exceptions to this are when the namespace type parameter indicates NT_EXPORT_NAME or when the GSS-API implementation is not multi-mechanism. The bytes that are passed in are interpreted by each underlying mechanism according to some encoding scheme of its choice for the given nametype.

Parameters:
name - the byte array containing the name to create
nameType - the Oid specifying the namespace of the name supplied in the byte array. null can be used to specify that a mechanism specific default syntax should be assumed by each mechanism that examines the byte array.
Returns:
a GSSName representing the indicated principal
Throws:
GSSException - containing the following major error codes: GSSException.BAD_NAMETYPE, GSSException.BAD_NAME, GSSException.BAD_MECH, GSSException.FAILURE
See Also:
GSSName, GSSName.NT_EXPORT_NAME

createName

public abstract GSSName createName(String nameStr,
                                   Oid nameType,
                                   Oid mech)
                            throws GSSException
Factory method to convert a string name from the specified namespace to a GSSName object and canonicalize it at the same time for a mechanism. In other words, this method is a utility that does the equivalent of two steps: the createName and then also the GSSName.canonicalize.

Parameters:
nameStr - the string representing a printable form of the name to create.
nameType - the Oid specifying the namespace of the printable name supplied. null can be used to specify that a mechanism specific default printable syntax should be assumed by each mechanism that examines nameStr. It is not advisable to use the nametype NT_EXPORT_NAME with this method.
mech - Oid specifying the mechanism for which the name should be canonicalized
Returns:
a GSSName representing the indicated principal
Throws:
GSSException - containing the following major error codes: GSSException.BAD_NAMETYPE, GSSException.BAD_NAME, GSSException.BAD_MECH, GSSException.FAILURE
See Also:
GSSName.canonicalize(Oid), GSSName.NT_EXPORT_NAME

createName

public abstract GSSName createName(byte[] name,
                                   Oid nameType,
                                   Oid mech)
                            throws GSSException
Factory method to convert a byte array containing a name from the specified namespace to a GSSName object and canonicalize it at the same time for a mechanism. In other words, this method is a utility that does the equivalent of two steps: the createName and then also GSSName.canonicalize.

Parameters:
name - the byte array containing the name to create
nameType - the Oid specifying the namespace of the name supplied in the byte array. null can be used to specify that a mechanism specific default syntax should be assumed by each mechanism that examines the byte array.
mech - Oid specifying the mechanism for which the name should be canonicalized
Returns:
a GSSName representing the indicated principal
Throws:
GSSException - containing the following major error codes: GSSException.BAD_NAMETYPE, GSSException.BAD_NAME, GSSException.BAD_MECH, GSSException.FAILURE
See Also:
GSSName.canonicalize(Oid), GSSName.NT_EXPORT_NAME

createCredential

public abstract GSSCredential createCredential(int usage)
                                        throws GSSException
Factory method for acquiring default credentials. This will cause the GSS-API to use system specific defaults for the set of mechanisms, name, and lifetime.

GSS-API mechanism providers must impose a local access-control policy on callers to prevent unauthorized callers from acquiring credentials to which they are not entitled. The kinds of permissions needed by different mechanism providers will be documented on a per-mechanism basis. A failed permission check might cause a SecurityException to be thrown from this method.

Parameters:
usage - The intended usage for this credential object. The value of this parameter must be one of: GSSCredential.INITIATE_AND_ACCEPT, GSSCredential.ACCEPT_ONLY, and GSSCredential.INITIATE_ONLY.
Returns:
a GSSCredential of the requested type.
Throws:
GSSException - containing the following major error codes: GSSException.BAD_MECH, GSSException.BAD_NAMETYPE, GSSException.BAD_NAME, GSSException.CREDENTIALS_EXPIRED, GSSException.NO_CRED, GSSException.FAILURE
See Also:
GSSCredential

createCredential

public abstract GSSCredential createCredential(GSSName name,
                                               int lifetime,
                                               Oid mech,
                                               int usage)
                                        throws GSSException
Factory method for acquiring a single mechanism credential.

GSS-API mechanism providers must impose a local access-control policy on callers to prevent unauthorized callers from acquiring credentials to which they are not entitled. The kinds of permissions needed by different mechanism providers will be documented on a per-mechanism basis. A failed permission check might cause a SecurityException to be thrown from this method.

Non-default values for lifetime cannot always be honored by the underlying mechanisms, thus applications should be prepared to call getRemainingLifetime on the returned credential.

Parameters:
name - the name of the principal for whom this credential is to be acquired. Use null to specify the default principal.
lifetime - The number of seconds that credentials should remain valid. Use GSSCredential.INDEFINITE_LIFETIME to request that the credentials have the maximum permitted lifetime. Use GSSCredential.DEFAULT_LIFETIME to request default credential lifetime.
mech - the Oid of the desired mechanism. Use (Oid) null to request the default mechanism.
usage - The intended usage for this credential object. The value of this parameter must be one of: GSSCredential.INITIATE_AND_ACCEPT, GSSCredential.ACCEPT_ONLY, and GSSCredential.INITIATE_ONLY.
Returns:
a GSSCredential of the requested type.
Throws:
GSSException - containing the following major error codes: GSSException.BAD_MECH, GSSException.BAD_NAMETYPE, GSSException.BAD_NAME, GSSException.CREDENTIALS_EXPIRED, GSSException.NO_CRED, GSSException.FAILURE
See Also:
GSSCredential

createCredential

public abstract GSSCredential createCredential(GSSName name,
                                               int lifetime,
                                               Oid[] mechs,
                                               int usage)
                                        throws GSSException
Factory method for acquiring credentials over a set of mechanisms. This method attempts to acquire credentials for each of the mechanisms specified in the array called mechs. To determine the list of mechanisms for which the acquisition of credentials succeeded, the caller should use the GSSCredential.getMechs method.

GSS-API mechanism providers must impose a local access-control policy on callers to prevent unauthorized callers from acquiring credentials to which they are not entitled. The kinds of permissions needed by different mechanism providers will be documented on a per-mechanism basis. A failed permission check might cause a SecurityException to be thrown from this method.

Non-default values for lifetime cannot always be honored by the underlying mechanisms, thus applications should be prepared to call getRemainingLifetime on the returned credential.

Parameters:
name - the name of the principal for whom this credential is to be acquired. Use null to specify the default principal.
lifetime - The number of seconds that credentials should remain valid. Use GSSCredential.INDEFINITE_LIFETIME to request that the credentials have the maximum permitted lifetime. Use GSSCredential.DEFAULT_LIFETIME to request default credential lifetime.
mechs - an array of Oid's indicating the mechanisms over which the credential is to be acquired. Use (Oid[]) null for requesting a system specific default set of mechanisms.
usage - The intended usage for this credential object. The value of this parameter must be one of: GSSCredential.INITIATE_AND_ACCEPT, GSSCredential.ACCEPT_ONLY, and GSSCredential.INITIATE_ONLY.
Returns:
a GSSCredential of the requested type.
Throws:
GSSException - containing the following major error codes: GSSException.BAD_MECH, GSSException.BAD_NAMETYPE, GSSException.BAD_NAME, GSSException.CREDENTIALS_EXPIRED, GSSException.NO_CRED, GSSException.FAILURE
See Also:
GSSCredential

createContext

public abstract GSSContext createContext(GSSName peer,
                                         Oid mech,
                                         GSSCredential myCred,
                                         int lifetime)
                                  throws GSSException
Factory method for creating a context on the initiator's side. Some mechanism providers might require that the caller be granted permission to initiate a security context. A failed permission check might cause a SecurityException to be thrown from this method.

Non-default values for lifetime cannot always be honored by the underlying mechanism, thus applications should be prepared to call getLifetime on the returned context.

Parameters:
peer - the name of the target peer.
mech - the Oid of the desired mechanism. Use null to request the default mechanism.
myCred - the credentials of the initiator. Use null to act as the default initiator principal.
lifetime - the lifetime, in seconds, requested for the context. Use GSSContext.INDEFINITE_LIFETIME to request that the context have the maximum permitted lifetime. Use GSSContext.DEFAULT_LIFETIME to request a default lifetime for the context.
Returns:
an unestablished GSSContext
Throws:
GSSException - containing the following major error codes: GSSException.NO_CRED GSSException.CREDENTIALS_EXPIRED GSSException.BAD_NAMETYPE GSSException.BAD_MECH GSSException.FAILURE
See Also:
GSSContext

createContext

public abstract GSSContext createContext(GSSCredential myCred)
                                  throws GSSException
Factory method for creating a context on the acceptor' side. The context's properties will be determined from the input token supplied to the accept method. Some mechanism providers might require that the caller be granted permission to accept a security context. A failed permission check might cause a SecurityException to be thrown from this method.

Parameters:
myCred - the credentials for the acceptor. Use null to act as a default acceptor principal.
Returns:
an unestablished GSSContext
Throws:
GSSException - containing the following major error codes: GSSException.NO_CRED GSSException.CREDENTIALS_EXPIRED GSSException.BAD_MECH GSSException.FAILURE
See Also:
GSSContext

createContext

public abstract GSSContext createContext(byte[] interProcessToken)
                                  throws GSSException
Factory method for creating a previously exported context. The context properties will be determined from the input token and cannot be modified through the set methods.

Implementations are not required to support the inter-process transfer of security contexts. Before exporting a context, calling the GSSContext.isTransferable will indicate if the context is transferable. Calling this method in an implementation that does not support it will result in a GSSException with the error code GSSException.UNAVAILABLE. Some mechanism providers might require that the caller be granted permission to initiate or accept a security context. A failed permission check might cause a SecurityException to be thrown from this method.

Parameters:
interProcessToken - the token previously emitted from the export method.
Returns:
the previously established GSSContext
Throws:
GSSException - containing the following major error codes: GSSException.NO_CONTEXT, GSSException.DEFECTIVE_TOKEN, GSSException.UNAVAILABLE, GSSException.UNAUTHORIZED, GSSException.FAILURE
See Also:
GSSContext

addProviderAtFront

public abstract void addProviderAtFront(Provider p,
                                        Oid mech)
                                 throws GSSException
This method is used to indicate to the GSSManager that the application would like a particular provider to be used ahead of all others when support is desired for the given mechanism. When a value of null is used instead of an Oid for the mechanism, the GSSManager must use the indicated provider ahead of all others no matter what the mechanism is. Only when the indicated provider does not support the needed mechanism should the GSSManager move on to a different provider.

Calling this method repeatedly preserves the older settings but lowers them in preference thus forming an ordered list of provider and Oid pairs that grows at the top.

Calling addProviderAtFront with a null Oid will remove all previous preferences that were set for this provider in the GSSManager instance. Calling addProviderAtFront with a non-null Oid will remove any previous preference that was set using this mechanism and this provider together.

If the GSSManager implementation does not support an SPI with a pluggable provider architecture it should throw a GSSException with the status code GSSException.UNAVAILABLE to indicate that the operation is unavailable.

Suppose an application desired that the provider A always be checked first when any mechanism is needed, it would call:

         GSSManager mgr = GSSManager.getInstance();
         // mgr may at this point have its own pre-configured list
         // of provider preferences. The following will prepend to
         // any such list:

         mgr.addProviderAtFront(A, null);
Now if it also desired that the mechanism of Oid m1 always be obtained from the provider B before the previously set A was checked, it would call:

         mgr.addProviderAtFront(B, m1);
The GSSManager would then first check with B if m1 was needed. In case B did not provide support for m1, the GSSManager would continue on to check with A. If any mechanism m2 is needed where m2 is different from m1 then the GSSManager would skip B and check with A directly.

Suppose at a later time the following call is made to the same GSSManager instance:

         mgr.addProviderAtFront(B, null)
then the previous setting with the pair (B, m1) is subsumed by this and should be removed. Effectively the list of preferences now becomes {(B, null), (A, null), ... //followed by the pre-configured list.

Please note, however, that the following call:

         mgr.addProviderAtFront(A, m3)
does not subsume the previous setting of (A, null) and the list will effectively become {(A, m3), (B, null), (A, null), ...}

Parameters:
p - the provider instance that should be used whenever support is needed for mech.
mech - the mechanism for which the provider is being set
Throws:
GSSException - containing the following major error codes: GSSException.UNAVAILABLE, GSSException.FAILURE

addProviderAtEnd

public abstract void addProviderAtEnd(Provider p,
                                      Oid mech)
                               throws GSSException
This method is used to indicate to the GSSManager that the application would like a particular provider to be used if no other provider can be found that supports the given mechanism. When a value of null is used instead of an Oid for the mechanism, the GSSManager must use the indicated provider for any mechanism.

Calling this method repeatedly preserves the older settings but raises them above newer ones in preference thus forming an ordered list of providers and Oid pairs that grows at the bottom. Thus the older provider settings will be utilized first before this one is.

If there are any previously existing preferences that conflict with the preference being set here, then the GSSManager should ignore this request.

If the GSSManager implementation does not support an SPI with a pluggable provider architecture it should throw a GSSException with the status code GSSException.UNAVAILABLE to indicate that the operation is unavailable.

Suppose an application desired that when a mechanism of Oid m1 is needed the system default providers always be checked first, and only when they do not support m1 should a provider A be checked. It would then make the call:

         GSSManager mgr = GSSManager.getInstance();
         mgr.addProviderAtEnd(A, m1);
Now, if it also desired that for all mechanisms the provider B be checked after all configured providers have been checked, it would then call:

         mgr.addProviderAtEnd(B, null);
Effectively the list of preferences now becomes {..., (A, m1), (B, null)}.

Suppose at a later time the following call is made to the same GSSManager instance:

         mgr.addProviderAtEnd(B, m2)
then the previous setting with the pair (B, null) subsumes this and therefore this request should be ignored. The same would happen if a request is made for the already existing pairs of (A, m1) or (B, null).

Please note, however, that the following call:

         mgr.addProviderAtEnd(A, null)
is not subsumed by the previous setting of (A, m1) and the list will effectively become {..., (A, m1), (B, null), (A, null)}

Parameters:
p - the provider instance that should be used whenever support is needed for mech.
mech - the mechanism for which the provider is being set
Throws:
GSSException - containing the following major error codes: GSSException.UNAVAILABLE, GSSException.FAILURE
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


GSSName

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.ietf.jgss
Interface GSSName

public interface GSSName

This interface encapsulates a single GSS-API principal entity. The application obtains an implementation of this interface through one of the createName methods that exist in the GSSManager class. Conceptually a GSSName contains many representations of the entity or many primitive name elements, one for each supported underlying mechanism. In GSS terminology, a GSSName that contains an element from just one mechanism is called a Mechanism Name (MN)

Since different authentication mechanisms may employ different namespaces for identifying their principals, GSS-API's naming support is necessarily complex in multi-mechanism environments (or even in some single-mechanism environments where the underlying mechanism supports multiple namespaces). Different name formats and their definitions are identified with Oid's and some standard types are defind in this interface. The format of the names can be derived based on the unique Oid of its name type.

Included below are code examples utilizing the GSSName interface. The code below creates a GSSName, converts it to an MN, performs a comparison, obtains a printable representation of the name, exports it to a byte array and then re-imports to obtain a new GSSName.

      GSSManager manager = GSSManager.getInstance();

      // create a host based service name
      GSSName name = manager.createName("service@host",
                   GSSName.NT_HOSTBASED_SERVICE);

      Oid krb5 = new Oid("1.2.840.113554.1.2.2");

      GSSName mechName = name.canonicalize(krb5);

      // the above two steps are equivalent to the following
      GSSName mechName = manager.createName("service@host",
                      GSSName.NT_HOSTBASED_SERVICE, krb5);

      // perform name comparison
      if (name.equals(mechName))
              print("Names are equals.");

      // obtain textual representation of name and its printable
      // name type
      print(mechName.toString() +
                      mechName.getStringNameType().toString());

      // export and re-import the name
      byte [] exportName = mechName.export();

      // create a new name object from the exported buffer
      GSSName newName = manager.createName(exportName,
                      GSSName.NT_EXPORT_NAME);

Since:
1.4
See Also:
export(),
equals(GSSName),
GSSManager.createName(String, Oid),
GSSManager.createName(String, Oid, Oid),
GSSManager.createName(byte[], Oid)

Field Summary
static Oid | NT_ANONYMOUS Name type for representing an anonymous entity.
static Oid | NT_EXPORT_NAME Name type used to indicate an exported name produced by the export method.
static Oid | NT_HOSTBASED_SERVICE Oid indicating a host-based service name form.
static Oid | NT_MACHINE_UID_NAME Name type to indicate a numeric user identifier corresponding to a user on a local system.
static Oid | NT_STRING_UID_NAME Name type to indicate a string of digits representing the numeric user identifier of a user on a local system.
static Oid | NT_USER_NAME Name type to indicate a named user on a local system.
Method Summary
GSSName | canonicalize(Oid mech) Creates a name that is canonicalized for some mechanism.
boolean | equals(GSSName another) Compares two GSSName objects to determine if they refer to the same entity.
boolean | equals(Object another) Compares this GSSName object to another Object that might be a GSSName.
byte[] | export() Returns a canonical contiguous byte representation of a mechanism name (MN), suitable for direct, byte by byte comparison by authorization functions.
Oid | getStringNameType() Returns the name type of the printable representation of this name that can be obtained from the toString method.
int | hashCode() Returns a hashcode value for this GSSName.
boolean | isAnonymous() Tests if this name object represents an anonymous entity.
boolean | isMN() Tests if this name object represents a Mechanism Name (MN).
String | toString() Returns a textual representation of the GSSName object.

Field Detail

NT_HOSTBASED_SERVICE

static final Oid NT_HOSTBASED_SERVICE
Oid indicating a host-based service name form. It is used to represent services associated with host computers. This name form is constructed using two elements, "service" and "hostname", as follows: service@hostname.

It represents the following Oid value:
{ 1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 2(gss-host-based-services) }

NT_USER_NAME

static final Oid NT_USER_NAME
Name type to indicate a named user on a local system.

 It represents the following Oid value:
{ iso(1) member-body(2) United
 States(840) mit(113554) infosys(1) gssapi(2) generic(1) user_name(1)
 }

NT_MACHINE_UID_NAME

static final Oid NT_MACHINE_UID_NAME
Name type to indicate a numeric user identifier corresponding to a user on a local system. (e.g. Uid).

It represents the following Oid value:
{ iso(1) member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) generic(1) machine_uid_name(2) }

NT_STRING_UID_NAME

static final Oid NT_STRING_UID_NAME
Name type to indicate a string of digits representing the numeric user identifier of a user on a local system.

 It represents the following Oid value:
{ iso(1) member-body(2) United
 States(840) mit(113554) infosys(1) gssapi(2) generic(1)
 string_uid_name(3) }

NT_ANONYMOUS

static final Oid NT_ANONYMOUS
Name type for representing an anonymous entity.

It represents the following Oid value:
{ 1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 3(gss-anonymous-name) }

NT_EXPORT_NAME

static final Oid NT_EXPORT_NAME
Name type used to indicate an exported name produced by the export method.

It represents the following Oid value:
{ 1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), 4(gss-api-exported-name) }

Method Detail

equals

boolean equals(GSSName another)
               throws GSSException
Compares two GSSName objects to determine if they refer to the same entity.

Parameters:
another - the GSSName to compare this name with
Returns:
true if the two names contain at least one primitive element in common. If either of the names represents an anonymous entity, the method will return false.
Throws:
GSSException - when the names cannot be compared, containing the following major error codes: GSSException.BAD_NAMETYPE, GSSException.FAILURE

equals

boolean equals(Object another)
Compares this GSSName object to another Object that might be a GSSName. The behaviour is exactly the same as in equals except that no GSSException is thrown; instead, false will be returned in the situation where an error occurs.

Overrides:
equals in class Object
Parameters:
another - the object to compare this name to
Returns:
true if the object to compare to is also a GSSName and the two names refer to the same entity.
See Also:
equals(GSSName)

hashCode

int hashCode()
Returns a hashcode value for this GSSName.

Overrides:
hashCode in class Object
Returns:
a hashCode value
See Also:
Object.equals(java.lang.Object), Hashtable

canonicalize

GSSName canonicalize(Oid mech)
                     throws GSSException
Creates a name that is canonicalized for some mechanism.

Parameters:
mech - the oid for the mechanism for which the canonical form of the name is requested.
Returns:
a GSSName that contains just one primitive element representing this name in a canonicalized form for the desired mechanism.
Throws:
GSSException - containing the following major error codes: GSSException.BAD_MECH, GSSException.BAD_NAMETYPE, GSSException.BAD_NAME, GSSException.FAILURE

export

byte[] export()
              throws GSSException
Returns a canonical contiguous byte representation of a mechanism name (MN), suitable for direct, byte by byte comparison by authorization functions. If the name is not an MN, implementations may throw a GSSException with the NAME_NOT_MN status code. If an implementation chooses not to throw an exception, it should use some system specific default mechanism to canonicalize the name and then export it. Structurally, an exported name object consists of a header containing an OID identifying the mechanism that authenticated the name, and a trailer containing the name itself, where the syntax of the trailer is defined by the individual mechanism specification. The format of the header of the output buffer is specified in RFC 2743.

The exported name is useful when used in large access control lists where the overhead of creating a GSSName object on each name and invoking the equals method on each name from the ACL may be prohibitive.

Exported names may be re-imported by using the byte array factory method GSSManager.createName and specifying the NT_EXPORT_NAME as the name type object identifier. The resulting GSSName name will also be a MN.

Returns:
a byte[] containing the exported name. RFC 2743 defines the "Mechanism-Independent Exported Name Object Format" for these bytes.
Throws:
GSSException - containing the following major error codes: GSSException.BAD_NAME, GSSException.BAD_NAMETYPE, GSSException.FAILURE

toString

String toString()
Returns a textual representation of the GSSName object. To retrieve the printed name format, which determines the syntax of the returned string, use the getStringNameType method.

Overrides:
toString in class Object
Returns:
a String representing this name in printable form.

getStringNameType

Oid getStringNameType()
                      throws GSSException
Returns the name type of the printable representation of this name that can be obtained from the toString method.

Returns:
an Oid representing the namespace of the name returned from the toString method.
Throws:
GSSException - containing the following major error codes: GSSException.FAILURE

isAnonymous

boolean isAnonymous()
Tests if this name object represents an anonymous entity.

Returns:
true if this is an anonymous name, false otherwise.

isMN

boolean isMN()
Tests if this name object represents a Mechanism Name (MN). An MN is a GSSName the contains exactly one mechanism's primitive name element.

Returns:
true if this is an MN, false otherwise.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MessageProp

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.ietf.jgss
Class MessageProp

java.lang.Object
    extended by  org.ietf.jgss.MessageProp

public class MessageProp
extends Object

This is a utility class used within the per-message GSSContext methods to convey per-message properties.

When used with the GSSContext interface's wrap and getMIC methods, an instance of this class is used to indicate the desired Quality-of-Protection (QOP) and to request if confidentiality services are to be applied to caller supplied data (wrap only). To request default QOP, the value of 0 should be used for QOP.

When used with the unwrap and verifyMIC methods of the GSSContext interface, an instance of this class will be used to indicate the applied QOP and confidentiality services over the supplied message. In the case of verifyMIC, the confidentiality state will always be false. Upon return from these methods, this object will also contain any supplementary status values applicable to the processed token. The supplementary status values can indicate old tokens, out of sequence tokens, gap tokens or duplicate tokens.

Since:
1.4
See Also:
GSSContext.wrap(byte[], int, int, org.ietf.jgss.MessageProp),
GSSContext.unwrap(byte[], int, int, org.ietf.jgss.MessageProp),
GSSContext.getMIC(byte[], int, int, org.ietf.jgss.MessageProp),
GSSContext.verifyMIC(byte[], int, int, byte[], int, int, org.ietf.jgss.MessageProp)

Constructor Summary
MessageProp(boolean privState)
Constructor which sets the desired privacy state.
MessageProp(int qop, boolean privState)
Constructor which sets the values for the qop and privacy state.
Method Summary
int | getMinorStatus() Retrieves the minor status code that the underlying mechanism might have set for this per-message operation.
String | getMinorString() Retrieves a string explaining the minor status code.
boolean | getPrivacy() Retrieves the privacy state.
int | getQOP() Retrieves the QOP value.
boolean | isDuplicateToken() Tests if this is a duplicate of an earlier token.
boolean | isGapToken() Tests if an expected token was not received, i.e., one or more predecessor tokens have not yet been successfully processed.
boolean | isOldToken() Tests if this token's validity period has expired, i.e., the token is too old to be checked for duplication.
boolean | isUnseqToken() Tests if a later token had already been processed.
void | setPrivacy(boolean privState) Sets the privacy state.
void | setQOP(int qop) Sets the QOP value.
void | setSupplementaryStates(boolean duplicate, boolean old, boolean unseq, boolean gap, int minorStatus, String minorString) This method sets the state for the supplementary information flags and the minor status in MessageProp.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MessageProp

public MessageProp(boolean privState)
Constructor which sets the desired privacy state. The QOP value used is 0.

Parameters:
privState - the privacy (i.e. confidentiality) state

MessageProp

public MessageProp(int qop,
                   boolean privState)
Constructor which sets the values for the qop and privacy state.

Parameters:
qop - the QOP value
privState - the privacy (i.e. confidentiality) state
Method Detail

getQOP

public int getQOP()
Retrieves the QOP value.

Returns:
an int representing the QOP value
See Also:
setQOP(int)

getPrivacy

public boolean getPrivacy()
Retrieves the privacy state.

Returns:
true if the privacy (i.e., confidentiality) state is true, false otherwise.
See Also:
setPrivacy(boolean)

setQOP

public void setQOP(int qop)
Sets the QOP value.

Parameters:
qop - the int value to set the QOP to
See Also:
getQOP()

setPrivacy

public void setPrivacy(boolean privState)
Sets the privacy state.

Parameters:
privState - true is the privacy (i.e., confidentiality) state is true, false otherwise.
See Also:
getPrivacy()

isDuplicateToken

public boolean isDuplicateToken()
Tests if this is a duplicate of an earlier token.

Returns:
true if this is a duplicate, false otherwise.

isOldToken

public boolean isOldToken()
Tests if this token's validity period has expired, i.e., the token is too old to be checked for duplication.

Returns:
true if the token's validity period has expired, false otherwise.

isUnseqToken

public boolean isUnseqToken()
Tests if a later token had already been processed.

Returns:
true if a later token had already been processed, false otherwise.

isGapToken

public boolean isGapToken()
Tests if an expected token was not received, i.e., one or more predecessor tokens have not yet been successfully processed.

Returns:
true if an expected per-message token was not received, false otherwise.

getMinorStatus

public int getMinorStatus()
Retrieves the minor status code that the underlying mechanism might have set for this per-message operation.

Returns:
the int minor status

getMinorString

public String getMinorString()
Retrieves a string explaining the minor status code.

Returns:
a String corresponding to the minor status code. null will be returned when no minor status code has been set.

setSupplementaryStates

public void setSupplementaryStates(boolean duplicate,
                                   boolean old,
                                   boolean unseq,
                                   boolean gap,
                                   int minorStatus,
                                   String minorString)
This method sets the state for the supplementary information flags and the minor status in MessageProp. It is not used by the application but by the GSS implementation to return this information to the caller of a per-message context method.

Parameters:
duplicate - true if the token was a duplicate of an earlier token, false otherwise
old - true if the token's validity period has expired, false otherwise
unseq - true if a later token has already been processed, false otherwise
gap - true if one or more predecessor tokens have not yet been successfully processed, false otherwise
minorStatus - the int minor status code for the per-message operation
minorString - the textual representation of the minorStatus value
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Oid

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.ietf.jgss
Class Oid

java.lang.Object
    extended by  org.ietf.jgss.Oid

public class Oid
extends Object

This class represents Universal Object Identifiers (Oids) and their associated operations.

Oids are hierarchically globally-interpretable identifiers used within the GSS-API framework to identify mechanisms and name formats.

The structure and encoding of Oids is defined in ISOIEC-8824 and ISOIEC-8825. For example the Oid representation of Kerberos V5 mechanism is "1.2.840.113554.1.2.2"

The GSSName name class contains public static Oid objects representing the standard name types defined in GSS-API.

Since:
1.4

Constructor Summary
Oid(byte[] data)
Creates an Oid object from its ASN.1 DER encoding.
Oid(InputStream derOid)
Creates an Oid object from its ASN.1 DER encoding.
Oid(String strOid)
Constructs an Oid object from a string representation of its integer components.
Method Summary
boolean | containedIn(Oid[] oids) A utility method to test if this Oid value is contained within the supplied Oid array.
boolean | equals(Object other) Tests if two Oid objects represent the same Object identifier value.
byte[] | getDER() Returns the full ASN.1 DER encoding for this oid object, which includes the tag and length.
int | hashCode() Returns a hashcode value for this Oid.
String | toString() Returns a string representation of the oid's integer components in dot separated notation.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Oid

public Oid(String strOid)
    throws GSSException
Constructs an Oid object from a string representation of its integer components.

Parameters:
strOid - the dot separated string representation of the oid. For instance, "1.2.840.113554.1.2.2".
Throws:
GSSException - may be thrown when the string is incorrectly formatted

Oid

public Oid(InputStream derOid)
    throws GSSException
Creates an Oid object from its ASN.1 DER encoding. This refers to the full encoding including tag and length. The structure and encoding of Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is identical in functionality to its byte array counterpart.

Parameters:
derOid - stream containing the DER encoded oid
Throws:
GSSException - may be thrown when the DER encoding does not follow the prescribed format.

Oid

public Oid(byte[] data)
    throws GSSException
Creates an Oid object from its ASN.1 DER encoding. This refers to the full encoding including tag and length. The structure and encoding of Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is identical in functionality to its InputStream conterpart.

Parameters:
data - byte array containing the DER encoded oid
Throws:
GSSException - may be thrown when the DER encoding does not follow the prescribed format.
Method Detail

toString

public String toString()
Returns a string representation of the oid's integer components in dot separated notation.

Overrides:
toString in class Object
Returns:
string representation in the following format: "1.2.3.4.5"

equals

public boolean equals(Object other)
Tests if two Oid objects represent the same Object identifier value.

Overrides:
equals in class Object
Parameters:
other - the Oid object that has to be compared to this one
Returns:
true if the two Oid objects represent the same value, false otherwise.
See Also:
Object.hashCode(), Hashtable

getDER

public byte[] getDER()
              throws GSSException
Returns the full ASN.1 DER encoding for this oid object, which includes the tag and length.

Returns:
byte array containing the DER encoding of this oid object.
Throws:
GSSException - may be thrown when the oid can't be encoded

containedIn

public boolean containedIn(Oid[] oids)
A utility method to test if this Oid value is contained within the supplied Oid array.

Parameters:
oids - the array of Oid's to search
Returns:
true if the array contains this Oid value, false otherwise

hashCode

public int hashCode()
Returns a hashcode value for this Oid.

Overrides:
hashCode in class Object
Returns:
a hashCode value
See Also:
Object.equals(java.lang.Object), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


CORBA

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.CORBA

Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

See:
Description

Interface Summary
ARG_IN | Signifies an "input" argument to an invocation, meaning that the argument is being passed from the client to the server.
ARG_INOUT | Signifies an argument used for both input and output in an invocation, meaning that the argument is being passed from the client to the server and then back from the server to the client.
ARG_OUT | A constant that signifies an "output" argument to an invocation, meaning that the argument is being passed from the server to the client.
BAD_POLICY | A PolicyErrorCode which would be filled in the PolicyError exception.
BAD_POLICY_TYPE | A PolicyErrorCode which would be filled in the PolicyError exception.
BAD_POLICY_VALUE | Contains the value used to indicate a policy value that is incorrect for a valid policy type in a call to the create_policy method defined in the ORB class.
CTX_RESTRICT_SCOPE | A flag that can be used as the second parameter to the method Context.get_values to restrict the search scope.
Current | Interfaces derived from the Current interface enable ORB and CORBA services to provide access to information (context) associated with the thread of execution in which they are running.
CurrentOperations | The interface for Current.
CustomMarshal | An abstract value type that is meant to be used by the ORB, not the user.
DataInputStream | Defines the methods used to read primitive data types from input streams for unmarshaling custom value types.
DataOutputStream | Defines the methods used to write primitive data types to output streams for marshalling custom value types.
DomainManager | Provides mechanisms for establishing and navigating relationships to superior and subordinate domains, as well as for creating and accessing policies.
DomainManagerOperations | Provides the DomainManager with the means to access policies.
DynAny | Deprecated. Use the new DynAny instead
DynArray | Deprecated. Use the new DynArray instead
DynEnum | Deprecated. Use the new DynEnum instead
DynFixed | Deprecated. Use the new DynFixed instead
DynSequence | Deprecated. Use the new DynSequence instead
DynStruct | Deprecated. Use the new DynStruct instead
DynUnion | Deprecated. Use the new DynUnion instead
DynValue | Deprecated. Use the new DynValue instead
IDLType | An abstract interface inherited by all Interface Repository (IR) objects that represent OMG IDL types.
IDLTypeOperations | This interface must be implemented by all IDLType objects.
IRObject | An IRObject IDL interface represents the most generic interface from which all other Interface Repository interfaces are derived, even the Repository itself.
IRObjectOperations | This is the Operations interface for the mapping from IRObject.
Object | The definition for a CORBA object reference.
OMGVMCID | The vendor minor code ID reserved for OMG.
Policy | Interfaces derived from the Policy interface allow an ORB or CORBA service access to certain choices that affect its operation.
PolicyOperations | Provides the operations for a Policy object.
PRIVATE_MEMBER | Constant to define a private member in the ValueMember class.
PUBLIC_MEMBER | Constant to define a public member in the ValueMember class.
UNSUPPORTED_POLICY | One of the PolicyErrorCodes which would be filled if the requested Policy is understood to be valid by the ORB, but is not currently supported.
UNSUPPORTED_POLICY_VALUE | A PolicyErrorCode which would be filled if the value requested for the Policy is of a valid type and within the valid range for that type, but this valid value is not currently supported.
VM_ABSTRACT | Defines the code used to represent an Abstract interface in a typecode.
VM_CUSTOM | Defines the code used to represent a custom marshalled value type in a typecode.
VM_NONE | Defines the code used to represent the one of the values of a value type in a typecode.
VM_TRUNCATABLE | Defines the code used to represent a truncatable value type in a typecode.

Class Summary
_IDLTypeStub | The Stub for IDLType.
_PolicyStub | The Stub for Policy.
Any | Serves as a container for any data that can be described in IDL or for any IDL primitive type.
AnyHolder | The Holder for Any.
AnySeqHelper | The Helper for AnySeq.
AnySeqHolder | The Holder for AnySeq.
BooleanHolder | The Holder for Boolean.
BooleanSeqHelper | The Helper for BooleanSeq.
BooleanSeqHolder | The Holder for BooleanSeq.
ByteHolder | The Holder for Byte.
CharHolder | The Holder for Char.
CharSeqHelper | The Helper for CharSeq.
CharSeqHolder | The Holder for CharSeq.
CompletionStatus | An object that indicates whether a method had completed running when a SystemException was thrown.
CompletionStatusHelper | The Helper for CompletionStatus.
Context | An object used in Request operations to specify the context object in which context strings must be resolved before being sent along with the request invocation.
ContextList | An object containing a modifiable list of String objects that represent property names.
CurrentHelper | The Helper for Current.
CurrentHolder | The Holder for Current.
DefinitionKind | The class that provides the constants used to identify the type of an Interface Repository object.
DefinitionKindHelper | The Helper for DefinitionKind.
DoubleHolder | The Holder for Double.
DoubleSeqHelper | The Helper for DoubleSeq.
DoubleSeqHolder | The Holder for DoubleSeq.
DynamicImplementation | Deprecated. org.omg.CORBA.DynamicImplementation
Environment | A container (holder) for an exception that is used in Request operations to make exceptions available to the client.
ExceptionList | An object used in Request operations to describe the exceptions that can be thrown by a method.
FieldNameHelper | The Helper for FieldName.
FixedHolder | The Holder for Fixed.
FloatHolder | The Holder for Float.
FloatSeqHelper | The Helper for FloatSeq.
FloatSeqHolder | The Holder for FloatSeq.
IdentifierHelper | The Helper for Identifier.
IDLTypeHelper | The Helper for IDLType.
IntHolder | The Holder for Int.
LocalObject | Used as a base class for implementation of a local IDL interface in the Java language mapping.
LongHolder | The Holder for Long.
LongLongSeqHelper | The Helper for LongLongSeq.
LongLongSeqHolder | The Holder for LongLongSeq.
LongSeqHelper | The Helper for LongSeqHelper.
LongSeqHolder | The Holder for LongSeq.
NamedValue | An object used in the DII and DSI to describe arguments and return values.
NameValuePair | Associates a name with a value that is an attribute of an IDL struct, and is used in the DynStruct APIs.
NameValuePairHelper | The Helper for NameValuePair.
NVList | A modifiable list containing NamedValue objects.
ObjectHelper |
ObjectHolder | The Holder for Object.
OctetSeqHelper | The Helper for OctetSeq.
OctetSeqHolder | The Holder for OctetSeq.
ORB | A class providing APIs for the CORBA Object Request Broker features.
ParameterMode | Enumeration of parameter modes for Parameter.
ParameterModeHelper | Enumeration of parameter modes for Parameter.
ParameterModeHolder | Enumeration of parameter modes for Parameter.
PolicyErrorCodeHelper | Encapsulates a reason a Policy may be invalid.
PolicyErrorHelper | Thrown to indicate problems with parameter values passed to the ORB.create_policy operation.
PolicyErrorHolder | Thrown to indicate problems with parameter values passed to the ORB.create_policy operation.
PolicyHelper | The Helper for Policy.
PolicyHolder | The Holder for Policy.
PolicyListHelper | The Helper for PolicyList.
PolicyListHolder | The Holder for PolicyList.
PolicyTypeHelper | The Helper for PolicyType.
Principal | Deprecated. Deprecated by CORBA 2.2.
PrincipalHolder | Deprecated. Deprecated by CORBA 2.2.
RepositoryIdHelper | The Helper for RepositoryId.
Request | An object containing the information necessary for invoking a method.
ServerRequest | An object that captures the explicit state of a request for the Dynamic Skeleton Interface (DSI).
ServiceDetail | An object that represents an ORB service: its service_detail_type field contains the type of the ORB service, and its service_detail field contains a description of the ORB service.
ServiceDetailHelper |
ServiceInformation | An IDL struct in the CORBA module that stores information about a CORBA service available in the ORB implementation and is obtained from the ORB.get_service_information method.
ServiceInformationHelper |
ServiceInformationHolder | The Holder for ServiceInformation.
SetOverrideType | The mapping of a CORBA enum tagging SET_OVERRIDE and ADD_OVERRIDE, which indicate whether policies should replace the existing policies of an Object or be added to them.
SetOverrideTypeHelper | The Helper for SetOverrideType.
ShortHolder | The Holder for Short.
ShortSeqHelper | The Helper for ShortSeqHelper.
ShortSeqHolder | The Holder for ShortSeq.
StringHolder | The Holder for String.
StringSeqHelper | An array of Strings
StringSeqHolder | An array of Strings
StringValueHelper | The Helper for StringValue.
StructMember | Describes a member of an IDL struct in the Interface Repository, including the name of the struct member, the type of the struct member, and the typedef that represents the IDL type of the struct member described the struct member object.
StructMemberHelper | The Helper for StructMember.
TCKind | The Java mapping of the IDL enum TCKind, which specifies the kind of a TypeCode object.
TypeCode | A container for information about a specific CORBA data type.
TypeCodeHolder | The Holder for TypeCode.
ULongLongSeqHelper | The Helper for ULongLongSeq.
ULongLongSeqHolder | The Holder for ULongLongSeq.
ULongSeqHelper | The Helper for ULongSeq.
ULongSeqHolder | The Holder for ULongSeq.
UnionMember | A description in the Interface Repository of a member of an IDL union.
UnionMemberHelper | The Helper for UnionMember.
UnknownUserExceptionHelper | The Helper for UnknownUserException.
UnknownUserExceptionHolder | The Holder for UnknownUserException.
UShortSeqHelper | The Helper for UShortSeq.
UShortSeqHolder | The Holder for UShortSeq.
ValueBaseHelper |
ValueBaseHolder | The Holder for ValueBase.
ValueMember | A description in the Interface Repository of a member of a value object.
ValueMemberHelper | The Helper for ValueMember.
VersionSpecHelper | The Helper for VersionSpec.
VisibilityHelper | The Helper for Visibility.
WCharSeqHelper | The Helper for WCharSeq.
WCharSeqHolder | The Holder for WCharSeq.
WrongTransactionHelper | The Helper for WrongTransaction.
WrongTransactionHolder | The Holder for WrongTransaction.
WStringSeqHelper | An array of WStrings
WStringSeqHolder | An array of WStrings
WStringValueHelper | org/omg/CORBA/WStringValueHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from orb.idl 31 May 1999 22:27:30 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications : ORB core as defined by CORBA 2.3.1 (formal/99-10-07) IDL/Java Language Mapping as defined in ptc/00-01-08

Exception Summary
ACTIVITY_COMPLETED | The ACTIVITY_COMPLETED system exception may be raised on any method for which Activity context is accessed.
ACTIVITY_REQUIRED | The ACTIVITY_REQUIRED system exception may be raised on any method for which an Activity context is required.
BAD_CONTEXT | Exception thrown when an operation is invoked by a client but the passed context does not contain the context values required by the operation.
BAD_INV_ORDER | This exception indicates that the caller has invoked operations in the wrong order.
BAD_OPERATION | Exception thrown when an object reference denotes an existing object, but that the object does not support the operation that was invoked.
BAD_PARAM | Exception thrown when a parameter passed to a call is out of range or otherwise considered illegal.
BAD_QOS | The BAD_QOS exception is raised whenever an object cannot support the quality of service required by an invocation parameter that has a quality of service semantics associated with it.
BAD_TYPECODE | Exception thrown when the ORB has encountered a malformed type code (for example, a type code with an invalid TCKind value).
Bounds | A user exception thrown when a parameter is not within the legal bounds for the object that a method is trying to access.
CODESET_INCOMPATIBLE | This exception is raised whenever meaningful communication is not possible between client and server native code sets.
COMM_FAILURE | This exception is raised if communication is lost while an operation is in progress, after the request was sent by the client, but before the reply from the server has been returned to the client.
DATA_CONVERSION | This exception is raised if an ORB cannot convert the representation of data as marshaled into its native representation or vice-versa.
FREE_MEM | Exception thrown when the ORB failed in an attempt to free dynamic memory, for example because of heap corruption or memory segments being locked.
IMP_LIMIT | This exception indicates that an implementation limit was exceeded in the ORB run time.
INITIALIZE | Exception thrown when an ORB has encountered a failure during its initialization, such as failure to acquire networking resources or detecting a configuration error.
INTERNAL | This exception indicates an internal failure in an ORB, for example, if an ORB has detected corruption of its internal data structures.
INTF_REPOS | Exception raised when an ORB cannot reach the interface repository, or some other failure relating to the interface repository is detected.
INV_FLAG | Exception thrown when an invalid flag was passed to an operation (for example, when creating a DII request).
INV_IDENT | This exception indicates that an IDL identifier is syntactically invalid.
INV_OBJREF | This exception indicates that an object reference is internally malformed.
INV_POLICY | Standard exception thrown when an invocation cannot be made because of an incompatibility between Policy overrides that apply to the particular invocation.
INVALID_ACTIVITY | The INVALID_ACTIVITY system exception may be raised on the Activity or Transaction services' resume methods if a transaction or Activity is resumed in a context different to that from which it was suspended.
INVALID_TRANSACTION | Exception thrown when the request carried an invalid transaction context.
MARSHAL | A request or reply from the network is structurally invalid.
NO_IMPLEMENT | This exception indicates that even though the operation that was invoked exists (it has an IDL definition), no implementation for that operation exists.
NO_MEMORY | Exception thrown when the ORB run time has run out of memory.
NO_PERMISSION | Exception thrown when an invocation failed because the caller has insufficient privileges.
NO_RESOURCES | Exception thrown when the ORB has encountered some general resource limitation.
NO_RESPONSE | This exception is raised if a client attempts to retrieve the result of a deferred synchronous call, but the response for the request is not yet available.
OBJ_ADAPTER | This exception typically indicates an administrative mismatch, for example, a server may have made an attempt to register itself with an implementation repository under a name that is already in use, or is unknown to the repository.
OBJECT_NOT_EXIST | Exception raised whenever an invocation on a deleted object was performed.
PERSIST_STORE | This exception indicates a persistent storage failure, for example, failure to establish a database connection or corruption of a database.
PolicyError | A user exception thrown when a policy error occurs.
REBIND | REBIND is raised when the current effective RebindPolicy, has a value of NO_REBIND or NO_RECONNECT and an invocation on a bound object reference results in a LocateReply message with status OBJECT_FORWARD or a Reply message with status LOCATION_FORWARD.
SystemException | The root class for all CORBA standard exceptions.
TIMEOUT | TIMEOUT is raised when no delivery has been made and the specified time-to-live period has been exceeded.
TRANSACTION_MODE | The CORBA TRANSACTION_MODE exception is thrown by the client ORB if it detects a mismatch between the InvocationPolicy in the IOR and the chosen invocation path (i.e, direct or routed invocation).
TRANSACTION_REQUIRED | Exception indicates that the request carried a null transaction context, but an active transaction is required.
TRANSACTION_ROLLEDBACK | Exception thrown when the transaction associated with the request has already been rolled back or marked to roll back.
TRANSACTION_UNAVAILABLE | The CORBA TRANSACTION_UNAVAILABLE exception is thrown by the ORB when it cannot process a transaction service context because its connection to the Transaction Service has been abnormally terminated.
TRANSIENT | Exception thrown when the ORB attempted to reach an object and failed.
UNKNOWN | This exception is raised if an operation implementation throws a non-CORBA exception (such as an exception specific to the implementation's programming language), or if an operation raises a user exception that does not appear in the operation's raises expression.
UnknownUserException | A class that contains user exceptions returned by the server.
UserException | The root class for CORBA IDL-defined user exceptions.
WrongTransaction | The CORBA WrongTransaction user-defined exception.

Package org.omg.CORBA Description

Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

For a precise list of supported sections of official CORBA specifications with which the Java[TM] Platform, Standard Edition 6 complies, see Official Specifications for CORBA support in Java[TM] SE 6.

General Information

The information in this section is information relevant to someone who compiles Interface Definition Language (IDL) files and uses the ORB to write clients and servers.

The classes and interfaces described in this section can be put into four groups: ORB classes, Exceptions, Helper classes, and Holder classes.

The ORB Class

An ORB handles (or brokers) method invocations between a client and the method's implementation on a server. Because the client and server may be anywhere on a network, and because the invocation and implementation may be written in different programming languages, an ORB does a great deal of work behind the scenes to accomplish this communication.

Most of what an ORB does is completely transparent to the user, and a major portion of the CORBA package consists of classes used by the ORB behind the scenes. The result is that most programmers will use only a small part of this package directly. In fact, most programmers will use only a few methods from the ORB class, some exceptions, and occasionally, a holder class.

ORB Methods

Before an application can enter the CORBA environment, it must first:

  • Be initialized into the ORB and possibly the object adapter (POA) environments.
  • Get references to ORB object (for use in future ORB operations) and perhaps other objects (including the root POA or some Object Adapter objects).

The following operations are provided to initialize applications and obtain the appropriate object references:

  • Operations providing access to the ORB, which are discussed in this section.
  • Operations providing access to Object Adapters, Interface Repository, Naming Service, and other Object Services. These operations are described in Other Classes.

When an application requires a CORBA environment it needs a mechanism to get an ORB object reference and possibly an OA object reference (such as the root POA). This serves two purposes. First, it initializes an application into the ORB and OA environments. Second, it returns the ORB object reference and the OA object reference to the application for use in future ORB and OA operations.

In order to obtain an ORB object reference, applications call the ORB.init operation. The parameters to the call can comprise an identifier for the ORB for which the object reference is required, and an arg_list, which is used to allow environment-specific data to be passed into the call.

These are the ORB methods that provide access to the ORB:

  • init()
  • init(String [] args, Properties props)
  • init(Applet app, Properties props)

Using the init() method without parameters initiates a singleton ORB, which can only give typecode creation anys needed in code generated in Helper classes by idlj.

Applications require a portable means by which to obtain their initial object references. References are required for the root POA, POA Current, Interface Repository, and various Object Services instances. The functionality required by the application is similar to that provided by the Naming Service. However, the OMG does not want to mandate that the Naming Service be made available to all applications in order that they may be portably initialized. Consequently, the operations shown in this section provide a simplified, local version of the Naming Service that applications can use to obtain a small, defined set of object references which are essential to its operation. Because only a small well-defined set of objects are expected with this mechanism, the naming context can be flattened to be a single-level name space. This simplification results in only two operations being defined to achieve the functionality required.

Initial references are obtained via two operations provided in the ORB object interface, providing facilities to list and resolve initial object references. These are:

  • resolve_initial_references(String name)
  • list_initial_services()
  • register_initial_reference(String id, org.omg.CORBA.Object obj)

An example that uses some of these methods is Getting Started with Java IDL.

Exceptions

Exceptions in Java IDL are similar to those in any code written in the Java programming language. If a method is defined to throw an exception, then any code using that method must have a try/catch block and handle that exception when it is thrown.

The documentation on Java IDL exceptions has more information and explains the difference between system exceptions and user-defined exceptions.

The following is a list of the system exceptions (which are unchecked exceptions inheriting through org.omg.CORBA.SystemException from java.lang.RuntimeException) that are defined in the package org.omg.CORBA:

        BAD_CONTEXT
        BAD_INV_ORDER
        BAD_OPERATION
        BAD_PARAM
        BAD_TYPECODE
        COMM_FAILURE
        DATA_CONVERSION
        FREE_MEM
        IMP_LIMIT
        INITIALIZE
        INTERNAL
        INTF_REPOS
        INVALID_TRANSACTION
        INV_FLAG
        INV_IDENT
        INV_OBJREF
        INV_POLICY
        MARSHAL
        NO_IMPLEMENT
        NO_MEMORY
        NO_PERMISSION
        NO_RESOURCES
        NO_RESPONSE
        OBJECT_NOT_EXIST
        OBJ_ADAPTER
        PERSIST_STORE
        TRANSACTION_REQUIRED
        TRANSACTION_ROLLEDBACK
        TRANSIENT
        UNKNOWN

The following is a list of user-defined exceptions defined in the package org.omg.CORBA.

        Bounds
        UnknownUserException
        WrongTransaction
        PolicyError

Subpackages

There are some packages inside the CORBA package with "Package" as part of their names. These packages are generally quite small because all they do is provide exceptions or classes for use by interfaces and classes in the CORBA package.

For example, the package org.omg.CORBA.TypeCodePackage contains two exceptions thrown by methods in the class TypeCode. These exceptions are:

  • BadKind
  • Bounds
The package org.omg.CORBA.ORBPackage contains two exceptions:
  • InvalidName
  • InconsistentTypeCode

Another package that is a subpackage of CORBA is the portable package. It provides a set of ORB APIs that makes it possible for code generated by one vendor's IDL compiler to run on another vendor's ORB.

Holder classes

Support for out and inout parameter passing modes requires the use of additional holder classes. Because the Java programming language does not support out or inout parameters, holder classes are needed as a means of passing a parameter that can be modified. To support portable stubs and skeletons, holder classes also implement the org.omg.CORBA.portable.Streamable interface.

Holder classes are named by appending "Holder" to the name of the type. The name of the type refers to its name in the Java programming language. For example, a holder class for the interface named Account in the Java programming language would be named AccountHolder.

Holder classes are available for all of the basic IDL datatypes in the org.omg.CORBA package. So, for example, there are already-defined classes for LongHolder, ShortHolder, FloatHolder, and so on. Classes are also generated for all named user-defined IDL types except those defined by typedefs. (Note that in this context user defined includes types that are defined in OMG specifications such as those for the Interface Repository, and other OMG services.)

Each holder class has:

  • a constructor from an instance
  • a default constructor
  • a public instance member, value which is the typed value.
  • a method for reading an input stream and assigning the contents to the type's value field
  • a method for writing the value of the value field to an output stream
  • a method for getting the typecode of the type

The default constructor sets the value field to the default value for the type as defined by the Java language:

  • false for boolean
  • 0 for numeric and char types
  • null for strings and object references

As an example, if the interface Account, defined in OMG IDL, were mapped to the Java programming language, the following holder class would be generated:

public final class AccountHolder implements
    org.omg.CORBA.portable.Streamable
{
  // field that holds an Account object
  public Account value = null;

  // default constructor
  public AccountHolder ()
  {
  }

  // creates a new AccountHolder from initialValue
  public AccountHolder (Account initialValue)
  {
    value = initialValue;
  }

  // reads the contents of i and assigns the contents to value
  public void _read (org.omg.CORBA.portable.InputStream i)
  {
    value = AccountHelper.read (i);
  }

  // writes value to o
  public void _write (org.omg.CORBA.portable.OutputStream o)
  {
    AccountHelper.write (o, value);
  }

  // returns the typecode for Account
  public org.omg.CORBA.TypeCode _type ()
  {
    return AccountHelper.type ();
  }

}

For more information on Holder classes, see Chapter 1.4, Mapping for Basic Types in the OMG IDL to Java Language Mapping. The Holder classes defined in the package org.omg.CORBA are:

     AnyHolder
     AnySeqHolder
     BooleanHolder
     BooleanSeqHolder
     ByteHolder
     CharHolder
     CharSeqHolder
     CurrentHolder
     DoubleHolder
     DoubleSeqHolder
     FixedHolder
     FloatHolder
     FloatSeqHolder
     IntHolder
     LongHolder
     LongLongSeqHolder
     LongSeqHolder
     ObjectHolder
     OctetSeqHolder
     ParameterModeHolder
     PolicyErrorHolder
     PolicyListHolder
     PrincipalHolder
     ServiceInformationHolder
     ShortHolder
     ShortSeqHolder
     StringHolder
     StringSeqHolder
     TypeCodeHolder
     ULongLongSeqHolder
     ULongSeqHolder
     UnknownUserExceptionHolder
     UShortSeqHolder
     ValueBaseHolder
     WCharSeqHolder
     WrongTransactionHolder
     WStringSeqHolder

Helper Classes

Helper files supply several static methods needed to manipulate the type. These include:

  • Any insert and extract operations for the type
  • getting the repository id
  • getting the typecode
  • reading and writing the type from and to a stream
  • implement the ValueHelper interface (if it is a user-defined value type)

The helper class for a mapped IDL interface or abstract interface also include narrow operation(s). The static narrow method allows an org.omg.CORBA.Object to be narrowed to the object reference of a more specific type. The IDL exception CORBA.BAD_PARAM is thrown if the narrow fails because the object reference does not support the requested type. A different system exception is raised to indicate other kinds of errors. Trying to narrow a null will always succeed with a return value of null. Generally, the only helper method an application programmer uses is the narrow method. The other methods are normally used behind the scenes and are transparent to the programmer.

Helper classes fall into two broad categories, helpers for value types and helpers for non value types. Because all of the helper classes in one category provide the same methods, one generic explanation of each category of helper classes is presented here.

When OMG IDL is mapped to the Java programming language, a "helper" class is generated for each user-defined type. This generated class will have the name of the user-defined type with the suffix Helper appended. For example, if the interface Account is defined in OMG IDL, the idlj compiler will automatically generate a class named AccountHelper. The AccountHelper class will contain the static methods needed for manipulating instances of the type, in this case, Account objects.

The narrow Method

When an object is the return value for a method, it is returned in the form of a generic object, either an org.omg.CORBA.Object object or a java.lang.Object object. This object must be cast to its more specific type before it can be operated on. For example, an Account object will be returned as a generic object and must be narrowed to an Account object so that Account methods may be called on it.

The narrow method has two forms, one that takes an org.omg.CORBA.Object object and one that takes a java.lang.Object object. Whether the interface is abstract or not determines which narrow method its helper class will provide. The helper class for an interface that is not abstract will have a narrow method that takes a CORBA object, whereas the narrow method for an interface that is abstract will take an object in the Java programming language. The helper class for a non-abstract interface that has at least one abstract base interface will provide both versions of the narrow method.

The Hello World tutorial uses a narrow method that looks like this:

        // create and initialize the ORB
        ORB orb = ORB.init(args, null);

        // get the root naming context
        org.omg.CORBA.Object objRef =
            orb.resolve_initial_references("NameService");
        // Use NamingContextExt instead of NamingContext. This is
        // part of latest Inter-Operable naming Service.
        NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef);

        // resolve the Object Reference in Naming
        String name = "Hello";
        helloImpl = HelloHelper.narrow(ncRef.resolve_str(name));

Example of a Basic Helper Class

A basic helper class, for purposes of this explanation, is one with the methods that are provided by every helper class, plus a narrow method if the type defined in OMG IDL maps to an interface in the Java programming language. Types that are not value types will have a basic helper class generated for them.

For example, assuming that the interface Account is not a value type IDL type and is also not an abstract interface and has no abstract base interfaces, its AccountHelper class will look like this:

abstract public class AccountHelper
{
  private static String  _id = "IDL:Account:1.0";

  // inserts an Account object into an Any object
  public static void insert (org.omg.CORBA.Any a, Account that)
  {
    org.omg.CORBA.portable.OutputStream out = a.create_output_stream ();
    a.type (type ());
    write (out, that);
    a.read_value (out.create_input_stream (), type ());
  }

  // extracts an Account object from an Any object
  public static Account extract (org.omg.CORBA.Any a)
  {
    return read (a.create_input_stream ());
  }

  private static org.omg.CORBA.TypeCode __typeCode = null;
  // gets the typecode for this type
  synchronized public static org.omg.CORBA.TypeCode type ()
  {
    if (__typeCode == null)
    {
      __typeCode = org.omg.CORBA.ORB.init ().create_interface_tc (AccountHelper.id (), "Account");
    }
    return __typeCode;
  }

  // gets the repository id for this type
  public static String id ()
  {
    return _id;
  }

  // reads an Account object from an input stream
  public static Account read (org.omg.CORBA.portable.InputStream istream)
  {
    return narrow (istream.read_Object (_AccountStub.class));
  }

  // writes an Account object to an outputstream
  public static void write (org.omg.CORBA.portable.OutputStream ostream, Account value)
  {
    ostream.write_Object ((org.omg.CORBA.Object) value);
  }

  // converts (narrows) an Object to an Account object
  public static Account narrow (org.omg.CORBA.Object obj)
  {
    if (obj == null)
      return null;
    else if (obj instanceof Account)
      return (Account)obj;
    else if (!obj._is_a (id ()))
      throw new org.omg.CORBA.BAD_PARAM ();
    else
    {
      org.omg.CORBA.portable.Delegate delegate = ((org.omg.CORBA.portable.ObjectImpl)obj)._get_delegate ();
      _AccountStub stub = new _AccountStub ();
      stub._set_delegate(delegate);
      return stub;
    }
  }

}

Value Type Helper Classes

A helper class for a value type includes different renderings of the same methods generated for non-value type methods. The main difference is that value types are types that can be passed by value as parameters or return values of a method, which means that they must be serializable.

Assuming that Address is a value type, the AddressHelper class will look like this:

abstract public class AddressHelper
{
  private static String  _id = "IDL:Address:1.0";

  // same as for non-value type
  public static void insert (org.omg.CORBA.Any a, Address that)
  {
    org.omg.CORBA.portable.OutputStream out = a.create_output_stream ();
    a.type (type ());
    write (out, that);
    a.read_value (out.create_input_stream (), type ());
  }

  // same as for non-value type
  public static Address extract (org.omg.CORBA.Any a)
  {
    return read (a.create_input_stream ());
  }

  private static org.omg.CORBA.TypeCode __typeCode = null;
  private static boolean __active = false;

  // getting the typecode for the type
  synchronized public static org.omg.CORBA.TypeCode type ()
  {
    if (__typeCode == null)
    {
      synchronized (org.omg.CORBA.TypeCode.class)
      {
        if (__typeCode == null)
        {
          if (__active)
          {
            return org.omg.CORBA.ORB.init().create_recursive_tc ( _id );
          }
          __active = true;
          org.omg.CORBA.ValueMember[] _members0 = new org.omg.CORBA.ValueMember[0];
          org.omg.CORBA.TypeCode _tcOf_members0 = null;
          __typeCode = org.omg.CORBA.ORB.init ().create_value_tc (_id, "Address", org.omg.CORBA.VM_NONE.value, null, _members0);
          __active = false;
        }
      }
    }
    return __typeCode;
  }

  // same as for non-value type
  public static String id ()
  {
    return _id;
  }

  // reads a serializable instance of Address from the given input stream
  public static Address read (org.omg.CORBA.portable.InputStream istream)
  {
    return (Address)((org.omg.CORBA_2_3.portable.InputStream) istream).read_value (id ());
  }

  // writes a serializable instance of Address to the given output stream
  public static void write (org.omg.CORBA.portable.OutputStream ostream, Address value)
  {
    ((org.omg.CORBA_2_3.portable.OutputStream) ostream).write_value (value, id ());
  }

}

The Helper classes defined in the package org.omg.CORBA are:

     AnySeqHelper
     BooleanSeqHelper
     CharSeqHelper
     CompletionStatusHelper
     CurrentHelper
     DefinitionKindHelper
     DoubleSeqHelper
     FieldNameHelper
     FloatSeqHelper
     IdentifierHelper
     IDLTypeHelper
     LongLongSeqHelper
     LongSeqHelper
     NameValuePairHelper
     ObjectHelper
     OctetSeqHelper
     ParameterModeHelper
     PolicyErrorCodeHelper
     PolicyErrorHelper
     PolicyHelper
     PolicyListHelper
     PolicyTypeHelper
     RepositoryIdHelper
     ServiceDetailHelper
     ServiceInformationHelper
     SetOverrideTypeHelper
     ShortSeqHelper
     StringSeqHelper
     StringValueHelper
     StructMemberHelper
     ULongLongSeqHelper
     ULongSeqHelper
     UnionMemberHelper
     UnknownUserExceptionHelper
     UShortSeqHelper
     ValueBaseHelper
     ValueMemberHelper
     VersionSpecHelper
     VisibilityHelper
     WCharSeqHelper
     WrongTransactionHelper
     WStringSeqHelper
     WStringValueHelper

Other Classes

The other classes and interfaces in the CORBA package, which are used behind the scenes, can be put into four groups. Three of the groups are used with requests in some capacity, and the fourth group, concerning the Interface Repository, is a category by itself.

Classes Created by an ORB

The first group contains classes that are created by an ORB and contain information used in request operations.
  • TCKind -- indicates the kind (datatype) for a TypeCode object
  • TypeCode -- indicates a datatype and possibly other information
  • Any -- contains a value and its typecode
  • NamedValue -- contains a name, an Any object, and an argument mode flag. NamedValue objects contain information about method arguments, method return values, or a context.
  • ContextList -- a list of strings that describe the contexts that need to be resolved and sent with an invocation
  • ExceptionList -- a list of TypeCodes for exceptions that may be thrown by a method
  • Environment -- a container for the exception thrown during a method invocation
  • Context -- a list of NamedValue objects used to pass auxiliary information from client to server
  • NVList -- a list of NamedValue objects, used to pass arguments or get results

Classes That Deal with Requests

The second group of classes deals with requests:
  • Object -- the base class for all CORBA object references
  • Request -- the main class in the DII, which contains methods for adding arguments to the request, for accessing information about the method being invoked (the method name, its arguments, exceptions it throws, and so on), and for making invocations on the request
  • DynamicImplementation -- the base class for server implementations using the DSI. It has the method invoke, which is used by an implementation of this class to determine the state of a ServerRequest object and to set its result or exception
  • ServerRequest -- captures the explicit state of a request for the Dynamic Skeleton Interface

Interfaces That Serve as Constants

The third group contains interfaces that serve as constants. The IDL-to-Java mapping mandates that IDL enums are mapped to a Java class with the enumerated values represented as public static final fields in that class (e.g. DefinitionKind). On the other hand IDL constants defined outside of an IDL interface are mapped to a Java interface for each constant.

This is why several interfaces in the org.omg.CORBA package consist of a single field, value, which is a short. This field is a constant used for such things as an error code or value modifier. For example, the value field of the interface BAD_POLICY is one of the possible reasons for the exception PolicyError to be thrown. To specify this error code, you would use BAD_POLICY.value.

The exception PolicyError uses the value field of the following interfaces as its possible error codes.

  • BAD_POLICY
  • BAD_POLICY_TYPE
  • BAD_POLICY_VALUE
  • UNSUPPORTED_POLICY
  • UNSUPPORTED_POLICY_VALUE
The method TypeCode.type_modifier returns the value field of one of the following interfaces. The VM in the names of these interfaces stands for "value modifier."
  • VM_NONE
  • VM_ABSTRACT
  • VM_CUSTOM
  • VM_TRUNCATABLE
The following constants are returned by a ValueMember object's access method to denote the visibility of the ValueMember object.
  • PRIVATE_MEMBER
  • PUBLIC_MEMBER
These flags, used in NamedValue objects or as parameters to methods, are defined in the following interfaces:
  • ARG_IN
  • ARG_INOUT
  • ARG_OUT
  • CTX_RESTRICT_SCOPE

Interface Repository Interfaces and Classes

A fourth group contains the Interface Repository interfaces and classes, which are generated by the idlj compiler from the OMG IDL interface ir.idl. The purpose of the Interface Repository is to identify the interfaces stored in it so that they can be accessed by an ORB. Each module, type, interface, attribute, operation, parameter, exception, constant, and so on is described completely by the Interface Repository API.

An ORB does not require that there be an interface repository, and Java IDL does not include one. Even though this release does not include an implementation of an interface repository, the following IR classes and interfaces have been included for the purpose of creating typecodes (see create_value_tc, create_struct_tc, create_union_tc and create_exception_tc methods in interface org.omg.CORBA.ORB):
&nbs

  • IRObject
  • IDLType
  • DefinitionKind
  • StructMember
  • UnionMember
  • ValueMember

Related Documentation

For overviews, guides, and a tutorial, please see:
  • Java IDL home page

CORBA Features Not Implemented in Java IDL

Some of the API included in org.omg subpackages is provided for conformance with the current OMG CORBA specification but is not implemented in Sun's release of the JDKTM. This enables other JDK licensees to provide implementations of this API in standard extensions and products.

Features That Throw NO_IMPLEMENT

Some of the API included in org.omg subpackages throw NO_IMPLEMENT exceptions for various reasons. Among these reasons are:

  • In some cases, for example LocalObject, the complete implementation according to the specification indicates that these API should throw NO_IMPLEMENT.

  • In most cases, for example methods in ORB.java, methods that throw NO_IMPLEMENT are actually implemented in subclasses elsewhere in the ORB code.

  • In some cases, for example _get_interface_def() and _get_interface, API are really not yet implemented.

General Summary of Features or API Not Implemented in This Release:

  • Interface Repository. An Interface Repository is not required for normal operation of Java IDL.
  • Java IDL does not support long double.
  • Policies (org.omg.CORBA.Policy) and methods for getting them are not implemented.
  • Domain managers (org.omg.CORBA.DomainManager) and methods for getting them are not implemented.
  • Service Information org.omg.CORBA.ServiceInformation and ORB method public boolean get_service_information(short service_type, ServiceInformationHolder service_info) are not implemented.
  • ORB methods for supporting single-threading (perform_work, work_pending) are not implemented.
  • IDL contexts.

Specific List of Unimplemented Features in Package org.omg.CORBA

Unimplemented Methods in package org.omg.CORBA:

  • ORB
    • public org.omg.CORBA.Policy create_policy(int type, org.omg.CORBA.Any val)
    • public void perform_work()
    • public boolean work_pending()
    • public org.omg.CORBA.Current get_current()
    • create_operation_list
    • get_default_context
    • get_service_information
    • obsolete DynAnys (deprecated in favor of DynamicAny package)

Since:
JDK1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


_PolicyStub

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class _PolicyStub

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.CORBA._PolicyStub
All Implemented Interfaces:
Serializable, Object, Policy, PolicyOperations, IDLEntity
public class _PolicyStub
extends ObjectImpl
implements Policy

The Stub for Policy. For more information on Stub files, see "Generated Files: Stubs".

org/omg/CORBA/_PolicyStub.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ../../../../../src/share/classes/org/omg/PortableServer/corba.idl. Saturday, July 17, 1999 12:26:20 AM PDT

Constructor Summary
_PolicyStub()
Constructors NOTE: If the default constructor is used, the object is useless until _set_delegate (...) is called.
_PolicyStub(Delegate delegate)
Constructs a _PolicyStub object initialized with the given Delegate object.
Method Summary
String[] | _ids() Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
Policy | copy() Copies the policy object.
void | destroy() Destroys the policy object.
int | policy_type() Returns the constant value that corresponds to the type of the policy object.
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Constructor Detail

_PolicyStub

public _PolicyStub()
Constructors NOTE: If the default constructor is used, the object is useless until _set_delegate (...) is called.

_PolicyStub

public _PolicyStub(Delegate delegate)
Constructs a _PolicyStub object initialized with the given Delegate object.

Parameters:
delegate - a Delegate Object
Method Detail

policy_type

public int policy_type()
Returns the constant value that corresponds to the type of the policy object. The values of the polivy objectys are allocated by the OMG. New values for PolicyType should be obtained from the OMG by sending mail to request@omg.org. In general the constant values that are allocated are defined in conjunction with the definition of the corresponding policy object.

Specified by:
policy_type in interface PolicyOperations
Returns:
the constant value that corresponds to the type of the policy object.

copy

public Policy copy()
Copies the policy object. The copy does not retain any relationships that the policy had with any domain or object.

Specified by:
copy in interface PolicyOperations
Returns:
the copy of the policy object.

destroy

public void destroy()
Destroys the policy object. It is the responsibility of the policy object to determine whether it can be destroyed.

Specified by:
destroy in interface PolicyOperations

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Specified by:
_ids in class ObjectImpl
Returns:
the array of all repository identifiers supported by this ObjectImpl instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Current

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface Current

All Superinterfaces:
CurrentOperations, IDLEntity, Object, Serializable
All Known Subinterfaces:
Current, Current
public interface Current
extends CurrentOperations, Object, IDLEntity

Interfaces derived from the Current interface enable ORB and CORBA services to provide access to information (context) associated with the thread of execution in which they are running. This information is accessed in a structured manner using interfaces derived from the Current interface defined in the CORBA module.

Each ORB or CORBA service that needs its own context derives an interface from the CORBA module's Current. Users of the service can obtain an instance of the appropriate Current interface by invoking ORB::resolve_initial_references.

org/omg/CORBA/Current.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ../../../../../src/share/classes/org/omg/PortableServer/corba.idl Saturday, July 17, 1999 12:26:21 AM PDT.

Method Summary
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CurrentOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface CurrentOperations

All Known Subinterfaces:
Current, Current, Current, CurrentOperations, CurrentOperations
public interface CurrentOperations

The interface for Current. For more information on Operations interfaces, see "Generated Files". org/omg/CORBA/CurrentOperations.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ../../../../../src/share/classes/org/omg/PortableServer/corba.idl Saturday, July 17, 1999 12:26:21 AM PDT.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


_IDLTypeStub

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class _IDLTypeStub

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.CORBA._IDLTypeStub
All Implemented Interfaces:
Serializable, IDLType, IDLTypeOperations, IRObject, IRObjectOperations, Object, IDLEntity
public class _IDLTypeStub
extends ObjectImpl
implements IDLType

The Stub for IDLType. For more information on Stub files, see "Generated Files: Stubs".

org/omg/CORBA/_IDLTypeStub.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ir.idl. 03 June 1999 11:33:44 o'clock GMT+00:00

Constructor Summary
_IDLTypeStub()
Constructs a default _IDLTypeStub object.
_IDLTypeStub(Delegate delegate)
Constructs an _IDLTypeStub object initialized with the given Delegate object.
Method Summary
String[] | _ids() Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
DefinitionKind | def_kind() Returns the DefinitionKind corresponding to this Interface Repository object.
void | destroy() Destroys this object.
TypeCode | type() The type attribute describes the type defined by an object derived from IDLType.
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Constructor Detail

_IDLTypeStub

public _IDLTypeStub()
Constructs a default _IDLTypeStub object. NOTE: If the default constructor is used, the object is useless until the method _set_delegate has been called.

_IDLTypeStub

public _IDLTypeStub(Delegate delegate)
Constructs an _IDLTypeStub object initialized with the given Delegate object.

Parameters:
delegate - a Delegate object
Method Detail

type

public TypeCode type()
Description copied from interface: IDLTypeOperations
The type attribute describes the type defined by an object derived from IDLType.

Specified by:
type in interface IDLTypeOperations
Returns:
the TypeCode defined by this object.

def_kind

public DefinitionKind def_kind()
Description copied from interface: IRObjectOperations
Returns the DefinitionKind corresponding to this Interface Repository object.

Specified by:
def_kind in interface IRObjectOperations
Returns:
the DefinitionKind corresponding to this Interface Repository object.

destroy

public void destroy()
Description copied from interface: IRObjectOperations
Destroys this object. If the object is a Container, this method is applied to all its contents. If the object contains an IDLType attribute for an anonymous type, that IDLType is destroyed. If the object is currently contained in some other object, it is removed. If the method is invoked on a Repository or on a PrimitiveDef then the BAD_INV_ORDER exception is raised with minor value 2. An attempt to destroy an object that would leave the repository in an incoherent state causes BAD_INV_ORDER exception to be raised with the minor code 1.

Specified by:
destroy in interface IRObjectOperations

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Specified by:
_ids in class ObjectImpl
Returns:
the array of all repository identifiers supported by this ObjectImpl instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


DomainManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface DomainManager

All Superinterfaces:
DomainManagerOperations, IDLEntity, Object, Serializable
public interface DomainManager
extends DomainManagerOperations, Object, IDLEntity

Provides mechanisms for establishing and navigating relationships to superior and subordinate domains, as well as for creating and accessing policies. The DomainManager has associated with it the policy objects for a particular domain. The domain manager also records the membership of the domain and provides the means to add and remove members. The domain manager is itself a member of a domain, possibly the domain it manages. The domain manager provides mechanisms for establishing and navigating relationships to superior and subordinate domains and creating and accessing policies.

Method Summary
Methods inherited from interface org.omg.CORBA.DomainManagerOperations
get_domain_policy
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IDLType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface IDLType

All Superinterfaces:
IDLEntity, IDLTypeOperations, IRObject, IRObjectOperations, Object, Serializable
All Known Implementing Classes:
_IDLTypeStub
public interface IDLType
extends IDLTypeOperations, IRObject, IDLEntity

An abstract interface inherited by all Interface Repository (IR) objects that represent OMG IDL types. It provides access to the TypeCode object describing the type and is used in defining the other interfaces wherever definitions of IDLType must be referenced.

Method Summary
Methods inherited from interface org.omg.CORBA.IDLTypeOperations
type
Methods inherited from interface org.omg.CORBA.IRObjectOperations
def_kind, destroy
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IRObject

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface IRObject

All Superinterfaces:
IDLEntity, IRObjectOperations, Object, Serializable
All Known Subinterfaces:
IDLType
All Known Implementing Classes:
_IDLTypeStub
public interface IRObject
extends IRObjectOperations, Object, IDLEntity

An IRObject IDL interface represents the most generic interface from which all other Interface Repository interfaces are derived, even the Repository itself.

Method Summary
Methods inherited from interface org.omg.CORBA.IRObjectOperations
def_kind, destroy
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Object

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface Object

All Known Subinterfaces:
AdapterActivator, BindingIterator, ClientRequestInfo, ClientRequestInterceptor, Codec, CodecFactory, Current, Current, Current, DomainManager, DynAny, DynAny, DynAnyFactory, DynArray, DynArray, DynEnum, DynEnum, DynFixed, DynFixed, DynSequence, DynSequence, DynStruct, DynStruct, DynUnion, DynUnion, DynValue, DynValue, DynValueBox, DynValueCommon, IdAssignmentPolicy, IDLType, IdUniquenessPolicy, ImplicitActivationPolicy, Interceptor, IORInfo, IORInterceptor, IORInterceptor_3_0, IRObject, LifespanPolicy, NamingContext, NamingContextExt, ORBInitializer, ORBInitInfo, POA, POAManager, Policy, PolicyFactory, RequestInfo, RequestProcessingPolicy, RunTime, ServantActivator, ServantLocator, ServantManager, ServantRetentionPolicy, ServerRequestInfo, ServerRequestInterceptor, ThreadPolicy
All Known Implementing Classes:
_BindingIteratorImplBase, _BindingIteratorStub, _DynAnyFactoryStub, _DynAnyStub, _DynArrayStub, _DynEnumStub, _DynFixedStub, _DynSequenceStub, _DynStructStub, _DynUnionStub, _DynValueStub, _IDLTypeStub, _NamingContextExtStub, _NamingContextImplBase, _NamingContextStub, _PolicyStub, _Remote_Stub, _ServantActivatorStub, _ServantLocatorStub, DynamicImplementation, LocalObject, ObjectImpl, ObjectImpl, Stub
public interface Object

The definition for a CORBA object reference.

A CORBA object reference is a handle for a particular CORBA object implemented by a server. A CORBA object reference identifies the same CORBA object each time the reference is used to invoke a method on the object. A CORBA object may have multiple, distinct object references.

The org.omg.CORBA.Object interface is the root of the inheritance hierarchy for all CORBA object references in the Java programming language, analogous to java.rmi.Remote for RMI remote objects.

A CORBA object may be either local or remote. If it is a local object (that is, running in the same VM as the client), invocations may be directly serviced by the object instance, and the object reference could point to the actual instance of the object implementation class. If a CORBA object is a remote object (that is, running in a different VM from the client), the object reference points to a stub (proxy) which uses the ORB machinery to make a remote invocation on the server where the object implementation resides.

Default implementations of the methods in the interface org.omg.CORBA.Object are provided in the class org.omg.CORBA.portable.ObjectImpl, which is the base class for stubs and object implementations.

See Also:
ObjectImpl

Method Summary
Request | _create_request(Context ctx, String operation, NVList arg_list, NamedValue result) Creates a Request instance initialized with the given context, method name, list of arguments, and container for the method's return value.
Request | _create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exclist, ContextList ctxlist) Creates a Request instance initialized with the given context, method name, list of arguments, container for the method's return value, list of possible exceptions, and list of context strings needing to be resolved.
Object | _duplicate() Returns a duplicate of this CORBA object reference.
DomainManager[] | _get_domain_managers() Retrieves the DomainManagers of this object.
Object | _get_interface_def() Obtains an InterfaceDef for the object implementation referenced by this object reference.
Policy | _get_policy(int policy_type) Returns the Policy object of the specified type which applies to this object.
int | _hash(int maximum) Returns an ORB-internal identifier for this object reference.
boolean | _is_a(String repositoryIdentifier) Checks whether this object is an instance of a class that implements the given interface.
boolean | _is_equivalent(Object other) Determines whether the two object references are equivalent, so far as the ORB can easily determine.
boolean | _non_existent() Determines whether the server object for this object reference has been destroyed.
void | _release() Signals that the caller is done using this object reference, so internal ORB resources associated with this object reference can be released.
Request | _request(String operation) Creates a Request instance for use in the Dynamic Invocation Interface.
Object | _set_policy_override(Policy[] policies, SetOverrideType set_add) Returns a new Object with the given policies either replacing any existing policies in this Object or with the given policies added to the existing ones, depending on the value of the given SetOverrideType object.

Method Detail

_is_a

boolean _is_a(String repositoryIdentifier)
Checks whether this object is an instance of a class that implements the given interface.

Parameters:
repositoryIdentifier - the interface to check against
Returns:
true if this object reference is an instance of a class that implements the interface; false otherwise

_is_equivalent

boolean _is_equivalent(Object other)
Determines whether the two object references are equivalent, so far as the ORB can easily determine. Two object references are equivalent if they are identical. Two distinct object references which in fact refer to the same object are also equivalent. However, ORBs are not required to attempt determination of whether two distinct object references refer to the same object, since such determination could be impractically expensive.

Parameters:
other - the other object reference with which to check for equivalence
Returns:
true if this object reference is known to be equivalent to the given object reference. Note that false indicates only that the two object references are distinct, not necessarily that they reference distinct objects.

_non_existent

boolean _non_existent()
Determines whether the server object for this object reference has been destroyed.

Returns:
true if the ORB knows authoritatively that the server object does not exist; false otherwise

_hash

int _hash(int maximum)
Returns an ORB-internal identifier for this object reference. This is a hash identifier, which does not change during the lifetime of the object reference, and so neither will any hash function of that identifier change. The value returned is not guaranteed to be unique; in other words, another object reference may have the same hash value. If two object references hash differently, then they are distinct object references; however, both may still refer to the same CORBA object.

Parameters:
maximum - the upper bound on the hash value returned by the ORB
Returns:
the ORB-internal hash identifier for this object reference

_duplicate

Object _duplicate()
Returns a duplicate of this CORBA object reference. The server object implementation is not involved in creating the duplicate, and the implementation cannot distinguish whether the original object reference or a duplicate was used to make a request.

Note that this method is not very useful in the Java platform, since memory management is handled by the VM. It is included for compliance with the CORBA APIs.

The method _duplicate may return this object reference itself.

Returns:
a duplicate of this object reference or this object reference itself

_release

void _release()
Signals that the caller is done using this object reference, so internal ORB resources associated with this object reference can be released. Note that the object implementation is not involved in this operation, and other references to the same object are not affected.

_get_interface_def

Object _get_interface_def()
Obtains an InterfaceDef for the object implementation referenced by this object reference. The InterfaceDef object may be used to introspect on the methods, attributes, and other type information for the object referred to by this object reference.

Returns:
the InterfaceDef object in the Interface Repository which provides type information about the object referred to by this object reference

_request

Request _request(String operation)
Creates a Request instance for use in the Dynamic Invocation Interface.

Parameters:
operation - the name of the method to be invoked using the Request instance
Returns:
the newly-created Request instance

_create_request

Request _create_request(Context ctx,
                        String operation,
                        NVList arg_list,
                        NamedValue result)
Creates a Request instance initialized with the given context, method name, list of arguments, and container for the method's return value.

Parameters:
ctx - a Context object containing a list of properties
operation - the name of the method to be invoked
arg_list - an NVList containing the actual arguments to the method being invoked
result - a NamedValue object to serve as a container for the method's return value
Returns:
the newly-created Request object
See Also:
Request, NVList, NamedValue

_create_request

Request _create_request(Context ctx,
                        String operation,
                        NVList arg_list,
                        NamedValue result,
                        ExceptionList exclist,
                        ContextList ctxlist)
Creates a Request instance initialized with the given context, method name, list of arguments, container for the method's return value, list of possible exceptions, and list of context strings needing to be resolved.

Parameters:
ctx - a Context object containing a list of properties
operation - the name of the method to be invoked
arg_list - an NVList containing the actual arguments to the method being invoked
result - a NamedValue object to serve as a container for the method's return value
exclist - an ExceptionList object containing a list of possible exceptions the method can throw
ctxlist - a ContextList object containing a list of context strings that need to be resolved and sent with the Request instance
Returns:
the newly-created Request object
See Also:
Request, NVList, NamedValue, ExceptionList, ContextList

_get_policy

Policy _get_policy(int policy_type)
Returns the Policy object of the specified type which applies to this object.

Parameters:
policy_type - the type of policy to be obtained
Returns:
A Policy object of the type specified by the policy_type parameter
Throws:
BAD_PARAM - when the value of policy type is not valid either because the specified type is not supported by this ORB or because a policy object of that type is not associated with this Object

_get_domain_managers

DomainManager[] _get_domain_managers()
Retrieves the DomainManagers of this object. This allows administration services (and applications) to retrieve the domain managers, and hence the security and other policies applicable to individual objects that are members of the domain.

Returns:
the list of immediately enclosing domain managers of this object. At least one domain manager is always returned in the list since by default each object is associated with at least one domain manager at creation.

_set_policy_override

Object _set_policy_override(Policy[] policies,
                            SetOverrideType set_add)
Returns a new Object with the given policies either replacing any existing policies in this Object or with the given policies added to the existing ones, depending on the value of the given SetOverrideType object.

Parameters:
policies - an array of Policy objects containing the policies to be added or to be used as replacements
set_add - either SetOverrideType.SET_OVERRIDE, indicating that the given policies will replace any existing ones, or SetOverrideType.ADD_OVERRIDE, indicating that the given policies should be added to any existing ones
Returns:
a new Object with the given policies replacing or added to those in this Object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


org.omg.CORBA Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.CORBA

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.CORBA.Any (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.CORBA.AnyHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.AnySeqHelper
    • org.omg.CORBA.AnySeqHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.BooleanHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.BooleanSeqHelper
    • org.omg.CORBA.BooleanSeqHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.ByteHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.CharHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.CharSeqHelper
    • org.omg.CORBA.CharSeqHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.CompletionStatus (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.CORBA.CompletionStatusHelper
    • org.omg.CORBA.Context
    • org.omg.CORBA.ContextList
    • org.omg.CORBA.CurrentHelper
    • org.omg.CORBA.CurrentHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.DefinitionKind (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.CORBA.DefinitionKindHelper
    • org.omg.CORBA.DoubleHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.DoubleSeqHelper
    • org.omg.CORBA.DoubleSeqHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.Environment
    • org.omg.CORBA.ExceptionList
    • org.omg.CORBA.FieldNameHelper
    • org.omg.CORBA.FixedHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.FloatHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.FloatSeqHelper
    • org.omg.CORBA.FloatSeqHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.IdentifierHelper
    • org.omg.CORBA.IDLTypeHelper
    • org.omg.CORBA.IntHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.LocalObject (implements org.omg.CORBA.Object)
    • org.omg.CORBA.LongHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.LongLongSeqHelper
    • org.omg.CORBA.LongLongSeqHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.LongSeqHelper
    • org.omg.CORBA.LongSeqHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.NamedValue
    • org.omg.CORBA.NameValuePair (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.CORBA.NameValuePairHelper
    • org.omg.CORBA.NVList
    • org.omg.CORBA.ObjectHelper
    • org.omg.CORBA.ObjectHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.portable.ObjectImpl (implements org.omg.CORBA.Object)
      • org.omg.CORBA._IDLTypeStub (implements org.omg.CORBA.IDLType)
      • org.omg.CORBA._PolicyStub (implements org.omg.CORBA.Policy)
      • org.omg.CORBA.DynamicImplementation
    • org.omg.CORBA.OctetSeqHelper
    • org.omg.CORBA.OctetSeqHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.ORB
    • org.omg.CORBA.ParameterMode (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.CORBA.ParameterModeHelper
    • org.omg.CORBA.ParameterModeHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.PolicyErrorCodeHelper
    • org.omg.CORBA.PolicyErrorHelper
    • org.omg.CORBA.PolicyErrorHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.PolicyHelper
    • org.omg.CORBA.PolicyHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.PolicyListHelper
    • org.omg.CORBA.PolicyListHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.PolicyTypeHelper
    • org.omg.CORBA.Principal
    • org.omg.CORBA.PrincipalHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.RepositoryIdHelper
    • org.omg.CORBA.Request
    • org.omg.CORBA.ServerRequest
    • org.omg.CORBA.ServiceDetail (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.CORBA.ServiceDetailHelper
    • org.omg.CORBA.ServiceInformation (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.CORBA.ServiceInformationHelper
    • org.omg.CORBA.ServiceInformationHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.SetOverrideType (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.CORBA.SetOverrideTypeHelper
    • org.omg.CORBA.ShortHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.ShortSeqHelper
    • org.omg.CORBA.ShortSeqHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.StringHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.StringSeqHelper
    • org.omg.CORBA.StringSeqHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.StringValueHelper (implements org.omg.CORBA.portable.BoxedValueHelper)
    • org.omg.CORBA.StructMember (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.CORBA.StructMemberHelper
    • org.omg.CORBA.TCKind
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.lang.RuntimeException
          • org.omg.CORBA.SystemException
            • org.omg.CORBA.ACTIVITY_COMPLETED
            • org.omg.CORBA.ACTIVITY_REQUIRED
            • org.omg.CORBA.BAD_CONTEXT
            • org.omg.CORBA.BAD_INV_ORDER
            • org.omg.CORBA.BAD_OPERATION
            • org.omg.CORBA.BAD_PARAM
            • org.omg.CORBA.BAD_QOS
            • org.omg.CORBA.BAD_TYPECODE
            • org.omg.CORBA.CODESET_INCOMPATIBLE
            • org.omg.CORBA.COMM_FAILURE
            • org.omg.CORBA.DATA_CONVERSION
            • org.omg.CORBA.FREE_MEM
            • org.omg.CORBA.IMP_LIMIT
            • org.omg.CORBA.INITIALIZE
            • org.omg.CORBA.INTERNAL
            • org.omg.CORBA.INTF_REPOS
            • org.omg.CORBA.INV_FLAG
            • org.omg.CORBA.INV_IDENT
            • org.omg.CORBA.INV_OBJREF
            • org.omg.CORBA.INV_POLICY
            • org.omg.CORBA.INVALID_ACTIVITY
            • org.omg.CORBA.INVALID_TRANSACTION
            • org.omg.CORBA.MARSHAL
            • org.omg.CORBA.NO_IMPLEMENT
            • org.omg.CORBA.NO_MEMORY
            • org.omg.CORBA.NO_PERMISSION
            • org.omg.CORBA.NO_RESOURCES
            • org.omg.CORBA.NO_RESPONSE
            • org.omg.CORBA.OBJ_ADAPTER
            • org.omg.CORBA.OBJECT_NOT_EXIST
            • org.omg.CORBA.PERSIST_STORE
            • org.omg.CORBA.REBIND
            • org.omg.CORBA.TIMEOUT
            • org.omg.CORBA.TRANSACTION_MODE
            • org.omg.CORBA.TRANSACTION_REQUIRED
            • org.omg.CORBA.TRANSACTION_ROLLEDBACK
            • org.omg.CORBA.TRANSACTION_UNAVAILABLE
            • org.omg.CORBA.TRANSIENT
            • org.omg.CORBA.UNKNOWN
        • org.omg.CORBA.UserException (implements org.omg.CORBA.portable.IDLEntity)
          • org.omg.CORBA.Bounds
          • org.omg.CORBA.PolicyError
          • org.omg.CORBA.UnknownUserException
          • org.omg.CORBA.WrongTransaction
    • org.omg.CORBA.TypeCode (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.CORBA.TypeCodeHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.ULongLongSeqHelper
    • org.omg.CORBA.ULongLongSeqHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.ULongSeqHelper
    • org.omg.CORBA.ULongSeqHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.UnionMember (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.CORBA.UnionMemberHelper
    • org.omg.CORBA.UnknownUserExceptionHelper
    • org.omg.CORBA.UnknownUserExceptionHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.UShortSeqHelper
    • org.omg.CORBA.UShortSeqHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.ValueBaseHelper
    • org.omg.CORBA.ValueBaseHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.ValueMember (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.CORBA.ValueMemberHelper
    • org.omg.CORBA.VersionSpecHelper
    • org.omg.CORBA.VisibilityHelper
    • org.omg.CORBA.WCharSeqHelper
    • org.omg.CORBA.WCharSeqHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.WrongTransactionHelper
    • org.omg.CORBA.WrongTransactionHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.WStringSeqHelper
    • org.omg.CORBA.WStringSeqHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.WStringValueHelper (implements org.omg.CORBA.portable.BoxedValueHelper)

Interface Hierarchy

  • org.omg.CORBA.ARG_IN
  • org.omg.CORBA.ARG_INOUT
  • org.omg.CORBA.ARG_OUT
  • org.omg.CORBA.BAD_POLICY
  • org.omg.CORBA.BAD_POLICY_TYPE
  • org.omg.CORBA.BAD_POLICY_VALUE
  • org.omg.CORBA.CTX_RESTRICT_SCOPE
  • org.omg.CORBA.CurrentOperations
    • org.omg.CORBA.Current (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
  • org.omg.CORBA.CustomMarshal
  • org.omg.CORBA.DomainManagerOperations
    • org.omg.CORBA.DomainManager (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
  • org.omg.CORBA.IRObjectOperations
    • org.omg.CORBA.IDLTypeOperations
      • org.omg.CORBA.IDLType (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.IRObject)
    • org.omg.CORBA.IRObject (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
      • org.omg.CORBA.IDLType (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.IDLTypeOperations)
  • org.omg.CORBA.Object
    • org.omg.CORBA.Current (also extends org.omg.CORBA.CurrentOperations, org.omg.CORBA.portable.IDLEntity)
    • org.omg.CORBA.DomainManager (also extends org.omg.CORBA.DomainManagerOperations, org.omg.CORBA.portable.IDLEntity)
    • org.omg.CORBA.DynAny
      • org.omg.CORBA.DynArray (also extends org.omg.CORBA.Object)
      • org.omg.CORBA.DynEnum (also extends org.omg.CORBA.Object)
      • org.omg.CORBA.DynFixed (also extends org.omg.CORBA.Object)
      • org.omg.CORBA.DynSequence (also extends org.omg.CORBA.Object)
      • org.omg.CORBA.DynStruct (also extends org.omg.CORBA.Object)
      • org.omg.CORBA.DynUnion (also extends org.omg.CORBA.Object)
      • org.omg.CORBA.DynValue (also extends org.omg.CORBA.Object)
    • org.omg.CORBA.DynArray (also extends org.omg.CORBA.DynAny)
    • org.omg.CORBA.DynEnum (also extends org.omg.CORBA.DynAny)
    • org.omg.CORBA.DynFixed (also extends org.omg.CORBA.DynAny)
    • org.omg.CORBA.DynSequence (also extends org.omg.CORBA.DynAny)
    • org.omg.CORBA.DynStruct (also extends org.omg.CORBA.DynAny)
    • org.omg.CORBA.DynUnion (also extends org.omg.CORBA.DynAny)
    • org.omg.CORBA.DynValue (also extends org.omg.CORBA.DynAny)
    • org.omg.CORBA.IRObject (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.IRObjectOperations)
      • org.omg.CORBA.IDLType (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.IDLTypeOperations)
    • org.omg.CORBA.Policy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.PolicyOperations)
  • org.omg.CORBA.OMGVMCID
  • org.omg.CORBA.PolicyOperations
    • org.omg.CORBA.Policy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
  • org.omg.CORBA.PRIVATE_MEMBER
  • org.omg.CORBA.PUBLIC_MEMBER
  • java.io.Serializable
    • org.omg.CORBA.portable.IDLEntity
      • org.omg.CORBA.Current (also extends org.omg.CORBA.CurrentOperations, org.omg.CORBA.Object)
      • org.omg.CORBA.DomainManager (also extends org.omg.CORBA.DomainManagerOperations, org.omg.CORBA.Object)
      • org.omg.CORBA.IDLType (also extends org.omg.CORBA.IDLTypeOperations, org.omg.CORBA.IRObject)
      • org.omg.CORBA.IRObject (also extends org.omg.CORBA.IRObjectOperations, org.omg.CORBA.Object)
        • org.omg.CORBA.IDLType (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.IDLTypeOperations)
      • org.omg.CORBA.Policy (also extends org.omg.CORBA.Object, org.omg.CORBA.PolicyOperations)
      • org.omg.CORBA.portable.ValueBase
        • org.omg.CORBA.DataInputStream
        • org.omg.CORBA.DataOutputStream
  • org.omg.CORBA.UNSUPPORTED_POLICY
  • org.omg.CORBA.UNSUPPORTED_POLICY_VALUE
  • org.omg.CORBA.VM_ABSTRACT
  • org.omg.CORBA.VM_CUSTOM
  • org.omg.CORBA.VM_NONE
  • org.omg.CORBA.VM_TRUNCATABLE
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Policy

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface Policy

All Superinterfaces:
IDLEntity, Object, PolicyOperations, Serializable
All Known Subinterfaces:
IdAssignmentPolicy, IdUniquenessPolicy, ImplicitActivationPolicy, LifespanPolicy, RequestProcessingPolicy, ServantRetentionPolicy, ThreadPolicy
All Known Implementing Classes:
_PolicyStub
public interface Policy
extends PolicyOperations, Object, IDLEntity

Interfaces derived from the Policy interface allow an ORB or CORBA service access to certain choices that affect its operation. This information is accessed in a structured manner using interfaces derived from the Policy interface defined in the CORBA module. A CORBA service does not have to use this method of accessing operating options, but may choose to do so. The Security Service in particular uses this technique for associating Security Policy with objects in the system. An interface generated by the IDL-to-Java compiler. org/omg/CORBA/Policy.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ../../../../../src/share/classes/org/omg/PortableServer/corba.idl Saturday, July 17, 1999 12:26:20 AM PDT

Method Summary
Methods inherited from interface org.omg.CORBA.PolicyOperations
copy, destroy, policy_type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Package org.omg.CORBA

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.CORBA

Packages that use org.omg.CORBA
javax.rmi.CORBA | Contains portability APIs for RMI-IIOP.
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.DynAnyPackage | Provides the exceptions used with the DynAny interface (InvalidValue, Invalid, InvalidSeq, and TypeMismatch).
org.omg.CORBA.ORBPackage | Provides the exception InvalidName, which is thrown by the method ORB.resolve_initial_references and the exception InconsistentTypeCode, which is thrown by the Dynamic Any creation methods in the ORB class.
org.omg.CORBA.TypeCodePackage | Provides the user-defined exceptions BadKind and Bounds, which are thrown by methods in in the class TypeCode.
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.
org.omg.CORBA_2_3 | The CORBA_2_3 package defines additions to existing CORBA interfaces in the Java[tm] Standard Edition 6. These changes occurred in recent revisions to the CORBA API defined by the OMG. The new methods were added to interfaces derived from the corresponding interfaces in the CORBA package. This provides backward compatibility and avoids breaking the JCK tests.
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextExtPackage | This package contains the following classes, which are used in org.omg.CosNaming.NamingContextExt:
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.
org.omg.Dynamic | This package contains the Dynamic module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.9.
org.omg.DynamicAny | Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.
org.omg.DynamicAny.DynAnyFactoryPackage | This package contains classes and exceptions from the DynAnyFactory interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.2.
org.omg.DynamicAny.DynAnyPackage | This package contains classes and exceptions from the DynAny interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.IOP.CodecFactoryPackage | This package contains the exceptions specified in the IOP::CodeFactory interface (as part of the Portable Interceptors spec).
org.omg.IOP.CodecPackage | This package is generated from the IOP::Codec IDL interface definition.
org.omg.Messaging | This package contains the Messaging module specified in the OMG CORBA Messaging specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07.
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.
org.omg.PortableInterceptor.ORBInitInfoPackage | This package contains the exceptions and typedefs from the ORBInitInfo local interface of the PortableInterceptor module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.7.2.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.CurrentPackage | Provides method implementations with access to the identity of the object on which the method was invoked.
org.omg.PortableServer.POAManagerPackage | Encapsulates the processing state of the POAs it is associated with.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.
org.omg.PortableServer.ServantLocatorPackage | Provides classes and interfaces for locating the servant.
org.omg.SendingContext | Provides support for the marshalling of value types.
org.omg.stub.java.rmi | Contains RMI-IIOP Stubs for the Remote types that occur in the java.rmi package.

Classes in org.omg.CORBA used by javax.rmi.CORBA
Object
The definition for a CORBA object reference.
ORB
A class providing APIs for the CORBA Object Request Broker features.
SystemException
The root class for all CORBA standard exceptions.

Classes in org.omg.CORBA used by org.omg.CORBA
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
AnySeqHolder
The Holder for AnySeq.
BAD_INV_ORDER
This exception indicates that the caller has invoked operations in the wrong order.
BAD_OPERATION
Exception thrown when an object reference denotes an existing object, but that the object does not support the operation that was invoked.
BAD_PARAM
Exception thrown when a parameter passed to a call is out of range or otherwise considered illegal.
BooleanSeqHolder
The Holder for BooleanSeq.
Bounds
A user exception thrown when a parameter is not within the legal bounds for the object that a method is trying to access.
CharSeqHolder
The Holder for CharSeq.
CompletionStatus
An object that indicates whether a method had completed running when a SystemException was thrown.
Context
An object used in Request operations to specify the context object in which context strings must be resolved before being sent along with the request invocation.
ContextList
An object containing a modifiable list of String objects that represent property names.
Current
Interfaces derived from the Current interface enable ORB and CORBA services to provide access to information (context) associated with the thread of execution in which they are running.
CurrentOperations
The interface for Current.
DATA_CONVERSION
This exception is raised if an ORB cannot convert the representation of data as marshaled into its native representation or vice-versa.
DataInputStream
Defines the methods used to read primitive data types from input streams for unmarshaling custom value types.
DataOutputStream
Defines the methods used to write primitive data types to output streams for marshalling custom value types.
DefinitionKind
The class that provides the constants used to identify the type of an Interface Repository object.
DomainManager
Provides mechanisms for establishing and navigating relationships to superior and subordinate domains, as well as for creating and accessing policies.
DomainManagerOperations
Provides the DomainManager with the means to access policies.
DoubleSeqHolder
The Holder for DoubleSeq.
DynAny
Deprecated. Use the new DynAny instead
DynArray
Deprecated. Use the new DynArray instead
DynEnum
Deprecated. Use the new DynEnum instead
DynSequence
Deprecated. Use the new DynSequence instead
DynStruct
Deprecated. Use the new DynStruct instead
DynUnion
Deprecated. Use the new DynUnion instead
Environment
A container (holder) for an exception that is used in Request operations to make exceptions available to the client.
ExceptionList
An object used in Request operations to describe the exceptions that can be thrown by a method.
FloatSeqHolder
The Holder for FloatSeq.
IDLType
An abstract interface inherited by all Interface Repository (IR) objects that represent OMG IDL types.
IDLTypeOperations
This interface must be implemented by all IDLType objects.
IRObject
An IRObject IDL interface represents the most generic interface from which all other Interface Repository interfaces are derived, even the Repository itself.
IRObjectOperations
This is the Operations interface for the mapping from IRObject.
LongLongSeqHolder
The Holder for LongLongSeq.
LongSeqHolder
The Holder for LongSeq.
MARSHAL
A request or reply from the network is structurally invalid.
NamedValue
An object used in the DII and DSI to describe arguments and return values.
NameValuePair
Associates a name with a value that is an attribute of an IDL struct, and is used in the DynStruct APIs.
NVList
A modifiable list containing NamedValue objects.
Object
The definition for a CORBA object reference.
OctetSeqHolder
The Holder for OctetSeq.
ORB
A class providing APIs for the CORBA Object Request Broker features.
ParameterMode
Enumeration of parameter modes for Parameter.
Policy
Interfaces derived from the Policy interface allow an ORB or CORBA service access to certain choices that affect its operation.
PolicyError
A user exception thrown when a policy error occurs.
PolicyOperations
Provides the operations for a Policy object.
Principal
Deprecated. Deprecated by CORBA 2.2.
Request
An object containing the information necessary for invoking a method.
ServerRequest
An object that captures the explicit state of a request for the Dynamic Skeleton Interface (DSI).
ServiceDetail
An object that represents an ORB service: its service_detail_type field contains the type of the ORB service, and its service_detail field contains a description of the ORB service.
ServiceInformation
An IDL struct in the CORBA module that stores information about a CORBA service available in the ORB implementation and is obtained from the ORB.get_service_information method.
ServiceInformationHolder
The Holder for ServiceInformation.
SetOverrideType
The mapping of a CORBA enum tagging SET_OVERRIDE and ADD_OVERRIDE, which indicate whether policies should replace the existing policies of an Object or be added to them.
ShortSeqHolder
The Holder for ShortSeq.
StructMember
Describes a member of an IDL struct in the Interface Repository, including the name of the struct member, the type of the struct member, and the typedef that represents the IDL type of the struct member described the struct member object.
SystemException
The root class for all CORBA standard exceptions.
TCKind
The Java mapping of the IDL enum TCKind, which specifies the kind of a TypeCode object.
TypeCode
A container for information about a specific CORBA data type.
ULongLongSeqHolder
The Holder for ULongLongSeq.
ULongSeqHolder
The Holder for ULongSeq.
UnionMember
A description in the Interface Repository of a member of an IDL union.
UnknownUserException
A class that contains user exceptions returned by the server.
UserException
The root class for CORBA IDL-defined user exceptions.
UShortSeqHolder
The Holder for UShortSeq.
ValueMember
A description in the Interface Repository of a member of a value object.
WCharSeqHolder
The Holder for WCharSeq.
WrongTransaction
The CORBA WrongTransaction user-defined exception.

Classes in org.omg.CORBA used by org.omg.CORBA.DynAnyPackage
UserException
The root class for CORBA IDL-defined user exceptions.

Classes in org.omg.CORBA used by org.omg.CORBA.ORBPackage
UserException
The root class for CORBA IDL-defined user exceptions.

Classes in org.omg.CORBA used by org.omg.CORBA.TypeCodePackage
UserException
The root class for CORBA IDL-defined user exceptions.

Classes in org.omg.CORBA used by org.omg.CORBA.portable
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
Context
An object used in Request operations to specify the context object in which context strings must be resolved before being sent along with the request invocation.
ContextList
An object containing a modifiable list of String objects that represent property names.
CustomMarshal
An abstract value type that is meant to be used by the ORB, not the user.
DomainManager
Provides mechanisms for establishing and navigating relationships to superior and subordinate domains, as well as for creating and accessing policies.
ExceptionList
An object used in Request operations to describe the exceptions that can be thrown by a method.
NamedValue
An object used in the DII and DSI to describe arguments and return values.
NVList
A modifiable list containing NamedValue objects.
Object
The definition for a CORBA object reference.
ORB
A class providing APIs for the CORBA Object Request Broker features.
Policy
Interfaces derived from the Policy interface allow an ORB or CORBA service access to certain choices that affect its operation.
Principal
Deprecated. Deprecated by CORBA 2.2.
Request
An object containing the information necessary for invoking a method.
SetOverrideType
The mapping of a CORBA enum tagging SET_OVERRIDE and ADD_OVERRIDE, which indicate whether policies should replace the existing policies of an Object or be added to them.
SystemException
The root class for all CORBA standard exceptions.
TypeCode
A container for information about a specific CORBA data type.

Classes in org.omg.CORBA used by org.omg.CORBA_2_3
BAD_PARAM
Exception thrown when a parameter passed to a call is out of range or otherwise considered illegal.
ORB
A class providing APIs for the CORBA Object Request Broker features.

Classes in org.omg.CORBA used by org.omg.CosNaming
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
DynamicImplementation
Deprecated. org.omg.CORBA.DynamicImplementation
Object
The definition for a CORBA object reference.
ORB
A class providing APIs for the CORBA Object Request Broker features.
ServerRequest
An object that captures the explicit state of a request for the Dynamic Skeleton Interface (DSI).
TypeCode
A container for information about a specific CORBA data type.

Classes in org.omg.CORBA used by org.omg.CosNaming.NamingContextExtPackage
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
TypeCode
A container for information about a specific CORBA data type.
UserException
The root class for CORBA IDL-defined user exceptions.

Classes in org.omg.CORBA used by org.omg.CosNaming.NamingContextPackage
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
TypeCode
A container for information about a specific CORBA data type.
UserException
The root class for CORBA IDL-defined user exceptions.

Classes in org.omg.CORBA used by org.omg.Dynamic
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
ParameterMode
Enumeration of parameter modes for Parameter.

Classes in org.omg.CORBA used by org.omg.DynamicAny
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
Object
The definition for a CORBA object reference.
TCKind
The Java mapping of the IDL enum TCKind, which specifies the kind of a TypeCode object.
TypeCode
A container for information about a specific CORBA data type.

Classes in org.omg.CORBA used by org.omg.DynamicAny.DynAnyFactoryPackage
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
TypeCode
A container for information about a specific CORBA data type.

Classes in org.omg.CORBA used by org.omg.DynamicAny.DynAnyPackage
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
TypeCode
A container for information about a specific CORBA data type.

Classes in org.omg.CORBA used by org.omg.IOP
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
Object
The definition for a CORBA object reference.
TypeCode
A container for information about a specific CORBA data type.

Classes in org.omg.CORBA used by org.omg.IOP.CodecFactoryPackage
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
TypeCode
A container for information about a specific CORBA data type.
UserException
The root class for CORBA IDL-defined user exceptions.

Classes in org.omg.CORBA used by org.omg.IOP.CodecPackage
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
TypeCode
A container for information about a specific CORBA data type.
UserException
The root class for CORBA IDL-defined user exceptions.

Classes in org.omg.CORBA used by org.omg.Messaging
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
TypeCode
A container for information about a specific CORBA data type.

Classes in org.omg.CORBA used by org.omg.PortableInterceptor
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
Object
The definition for a CORBA object reference.
Policy
Interfaces derived from the Policy interface allow an ORB or CORBA service access to certain choices that affect its operation.
PolicyError
A user exception thrown when a policy error occurs.
TypeCode
A container for information about a specific CORBA data type.
UserException
The root class for CORBA IDL-defined user exceptions.

Classes in org.omg.CORBA used by org.omg.PortableInterceptor.ORBInitInfoPackage
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
TypeCode
A container for information about a specific CORBA data type.
UserException
The root class for CORBA IDL-defined user exceptions.

Classes in org.omg.CORBA used by org.omg.PortableServer
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
Current
Interfaces derived from the Current interface enable ORB and CORBA services to provide access to information (context) associated with the thread of execution in which they are running.
CurrentOperations
The interface for Current.
Object
The definition for a CORBA object reference.
ORB
A class providing APIs for the CORBA Object Request Broker features.
Policy
Interfaces derived from the Policy interface allow an ORB or CORBA service access to certain choices that affect its operation.
PolicyOperations
Provides the operations for a Policy object.
TypeCode
A container for information about a specific CORBA data type.
UserException
The root class for CORBA IDL-defined user exceptions.

Classes in org.omg.CORBA used by org.omg.PortableServer.CurrentPackage
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
TypeCode
A container for information about a specific CORBA data type.
UserException
The root class for CORBA IDL-defined user exceptions.

Classes in org.omg.CORBA used by org.omg.PortableServer.POAManagerPackage
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
TypeCode
A container for information about a specific CORBA data type.
UserException
The root class for CORBA IDL-defined user exceptions.

Classes in org.omg.CORBA used by org.omg.PortableServer.POAPackage
Any
Serves as a container for any data that can be described in IDL or for any IDL primitive type.
TypeCode
A container for information about a specific CORBA data type.
UserException
The root class for CORBA IDL-defined user exceptions.

Classes in org.omg.CORBA used by org.omg.PortableServer.ServantLocatorPackage
TypeCode
A container for information about a specific CORBA data type.

Classes in org.omg.CORBA used by org.omg.SendingContext
Object
The definition for a CORBA object reference.

Classes in org.omg.CORBA used by org.omg.stub.java.rmi
Object
The definition for a CORBA object reference.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ACTIVITY_COMPLETED

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ACTIVITY_COMPLETED

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.ACTIVITY_COMPLETED
All Implemented Interfaces:
Serializable
public final class ACTIVITY_COMPLETED
extends SystemException

The ACTIVITY_COMPLETED system exception may be raised on any method for which Activity context is accessed. It indicates that the Activity context in which the method call was made has been completed due to a timeout of either the Activity itself or a transaction that encompasses the Activity, or that the Activity completed in a manner other than that originally requested.

Since:
J2SE 1.5
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
ACTIVITY_COMPLETED()
Constructs an ACTIVITY_COMPLETED exception with minor code set to 0 and CompletionStatus set to COMPLETED_NO.
ACTIVITY_COMPLETED(int minorCode, CompletionStatus completionStatus)
Constructs an ACTIVITY_COMPLETED exception with the specified minor code and completion status.
ACTIVITY_COMPLETED(String detailMessage)
Constructs an ACTIVITY_COMPLETED exception with the specified message.
ACTIVITY_COMPLETED(String detailMessage, int minorCode, CompletionStatus completionStatus)
Constructs an ACTIVITY_COMPLETED exception with the specified message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ACTIVITY_COMPLETED

public ACTIVITY_COMPLETED()
Constructs an ACTIVITY_COMPLETED exception with minor code set to 0 and CompletionStatus set to COMPLETED_NO.

ACTIVITY_COMPLETED

public ACTIVITY_COMPLETED(String detailMessage)
Constructs an ACTIVITY_COMPLETED exception with the specified message.

Parameters:
detailMessage - string containing a detailed message.

ACTIVITY_COMPLETED

public ACTIVITY_COMPLETED(int minorCode,
                          CompletionStatus completionStatus)
Constructs an ACTIVITY_COMPLETED exception with the specified minor code and completion status.

Parameters:
minorCode - minor code.
completionStatus - completion status.

ACTIVITY_COMPLETED

public ACTIVITY_COMPLETED(String detailMessage,
                          int minorCode,
                          CompletionStatus completionStatus)
Constructs an ACTIVITY_COMPLETED exception with the specified message, minor code, and completion status.

Parameters:
detailMessage - string containing a detailed message.
minorCode - minor code.
completionStatus - completion status.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ACTIVITY_REQUIRED

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ACTIVITY_REQUIRED

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.ACTIVITY_REQUIRED
All Implemented Interfaces:
Serializable
public final class ACTIVITY_REQUIRED
extends SystemException

The ACTIVITY_REQUIRED system exception may be raised on any method for which an Activity context is required. It indicates that an Activity context was necessary to perform the invoked operation, but one was not found associated with the calling thread.

Since:
J2SE 1.5
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
ACTIVITY_REQUIRED()
Constructs an ACTIVITY_REQUIRED exception with minor code set to 0 and CompletionStatus set to COMPLETED_NO.
ACTIVITY_REQUIRED(int minorCode, CompletionStatus completionStatus)
Constructs an ACTIVITY_REQUIRED exception with the specified minor code and completion status.
ACTIVITY_REQUIRED(String detailMessage)
Constructs an ACTIVITY_REQUIRED exception with the specified message.
ACTIVITY_REQUIRED(String detailMessage, int minorCode, CompletionStatus completionStatus)
Constructs an ACTIVITY_REQUIRED exception with the specified message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ACTIVITY_REQUIRED

public ACTIVITY_REQUIRED()
Constructs an ACTIVITY_REQUIRED exception with minor code set to 0 and CompletionStatus set to COMPLETED_NO.

ACTIVITY_REQUIRED

public ACTIVITY_REQUIRED(String detailMessage)
Constructs an ACTIVITY_REQUIRED exception with the specified message.

Parameters:
detailMessage - string containing a detailed message.

ACTIVITY_REQUIRED

public ACTIVITY_REQUIRED(int minorCode,
                         CompletionStatus completionStatus)
Constructs an ACTIVITY_REQUIRED exception with the specified minor code and completion status.

Parameters:
minorCode - minor code.
completionStatus - completion status.

ACTIVITY_REQUIRED

public ACTIVITY_REQUIRED(String detailMessage,
                         int minorCode,
                         CompletionStatus completionStatus)
Constructs an ACTIVITY_REQUIRED exception with the specified message, minor code, and completion status.

Parameters:
detailMessage - string containing a detailed message.
minorCode - minor code.
completionStatus - completion status.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Any

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class Any

java.lang.Object
    extended by  org.omg.CORBA.Any
All Implemented Interfaces:
Serializable, IDLEntity
public abstract class Any
extends Object
implements IDLEntity

Serves as a container for any data that can be described in IDL or for any IDL primitive type. An Any object is used as a component of a NamedValue object, which provides information about arguments or return values in requests, and which is used to define name/value pairs in Context objects.

An Any object consists of two parts:

  1. a data value
  2. a TypeCode object describing the type of the data value contained in the Any object. For example, a TypeCode object for an array contains a field for the length of the array and a field for the type of elements in the array. (Note that in this case, the second field of the TypeCode object is itself a TypeCode object.)

A large part of the Any class consists of pairs of methods for inserting values into and extracting values from an Any object.

For a given primitive type X, these methods are:

void insert_X(X x)
This method allows the insertion of an instance x of primitive type X into the value field of the Any object. Note that the method insert_X also resets the Any object's type field if necessary.
X extract_X()
This method allows the extraction of an instance of type X from the Any object.

This method throws the exception BAD_OPERATION under two conditions:

  1. the type of the element contained in the Any object is not X
  2. the method extract_X is called before the value field of the Any object has been set

There are distinct method pairs for each primitive IDL data type (insert_long and extract_long, insert_string and extract_string, and so on).

The class Any also has methods for getting and setting the type code, for testing two Any objects for equality, and for reading an Any object from a stream or writing it to a stream.

Since:
JDK1.2

Constructor Summary
Any()
Method Summary
abstract InputStream | create_input_stream() Creates an input stream from which this Any object's value can be unmarshalled.
abstract OutputStream | create_output_stream() Creates an output stream into which this Any object's value can be marshalled.
abstract boolean | equal(Any a) Checks for equality between this Any object and the given Any object.
abstract Any | extract_any() Extracts the Any object in this Any object's value field.
abstract boolean | extract_boolean() Extracts the boolean in this Any object's value field.
abstract char | extract_char() Extracts the char in this Any object's value field.
abstract double | extract_double() Extracts the double in this Any object's value field.
BigDecimal | extract_fixed() Extracts the java.math.BigDecimal object in this Any object's value field.
abstract float | extract_float() Extracts the float in this Any object's value field.
abstract int | extract_long() Extracts the int in this Any object's value field.
abstract long | extract_longlong() Extracts the long in this Any object's value field.
abstract Object | extract_Object() Extracts the org.omg.CORBA.Object in this Any object's value field.
abstract byte | extract_octet() Extracts the byte in this Any object's value field.
Principal | extract_Principal() Deprecated. Deprecated by CORBA 2.2.
abstract short | extract_short() Extracts the short in this Any object's value field.
Streamable | extract_Streamable() Extracts a Streamable from this Any object's value field.
abstract String | extract_string() Extracts the String object in this Any object's value field.
abstract TypeCode | extract_TypeCode() Extracts the TypeCode object in this Any object's value field.
abstract int | extract_ulong() Extracts the int in this Any object's value field.
abstract long | extract_ulonglong() Extracts the long in this Any object's value field.
abstract short | extract_ushort() Extracts the short in this Any object's value field.
abstract Serializable | extract_Value() Extracts the java.io.Serializable object in this Any object's value field.
abstract char | extract_wchar() Extracts the char in this Any object's value field.
abstract String | extract_wstring() Extracts the String object in this Any object's value field.
abstract void | insert_any(Any a) Inserts the given Any object into this Any object's value field.
abstract void | insert_boolean(boolean b) Inserts the given boolean into this Any object's value field.
abstract void | insert_char(char c) Inserts the given char into this Any object's value field.
abstract void | insert_double(double d) Inserts the given double into this Any object's value field.
void | insert_fixed(BigDecimal value) Throws an org.omg.CORBA.NO_IMPLEMENT exception.
void | insert_fixed(BigDecimal value, TypeCode type) Throws an org.omg.CORBA.NO_IMPLEMENT exception.
abstract void | insert_float(float f) Inserts the given float into this Any object's value field.
abstract void | insert_long(int l) Inserts the given int into this Any object's value field.
abstract void | insert_longlong(long l) Inserts the given long into this Any object's value field.
abstract void | insert_Object(Object o) Inserts the given org.omg.CORBA.Object object into this Any object's value field.
abstract void | insert_Object(Object o, TypeCode t) Inserts the given org.omg.CORBA.Object object into this Any object's value field.
abstract void | insert_octet(byte b) Inserts the given byte into this Any object's value field.
void | insert_Principal(Principal p) Deprecated. Deprecated by CORBA 2.2.
abstract void | insert_short(short s) Inserts the given short into this Any object's value field.
void | insert_Streamable(Streamable s) Inserts the given Streamable object into this Any object's value field.
abstract void | insert_string(String s) Inserts the given String object into this Any object's value field.
abstract void | insert_TypeCode(TypeCode t) Inserts the given TypeCode object into this Any object's value field.
abstract void | insert_ulong(int l) Inserts the given int into this Any object's value field.
abstract void | insert_ulonglong(long l) Inserts the given long into this Any object's value field.
abstract void | insert_ushort(short s) Inserts the given short into this Any object's value field.
abstract void | insert_Value(Serializable v) Inserts the given java.io.Serializable object into this Any object's value field.
abstract void | insert_Value(Serializable v, TypeCode t) Inserts the given java.io.Serializable object into this Any object's value field.
abstract void | insert_wchar(char c) Inserts the given char into this Any object's value field.
abstract void | insert_wstring(String s) Inserts the given String object into this Any object's value field.
abstract void | read_value(InputStream is, TypeCode t) Reads off (unmarshals) the value of an Any object from the given input stream using the given typecode.
abstract TypeCode | type() Returns type information for the element contained in this Any object.
abstract void | type(TypeCode t) Sets this Any object's type field to the given TypeCode object and clears its value.
abstract void | write_value(OutputStream os) Writes out the value of this Any object to the given output stream.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Any

public Any()
Method Detail

equal

public abstract boolean equal(Any a)
Checks for equality between this Any object and the given Any object. Two Any objects are equal if both their values and type codes are equal.

Parameters:
a - the Any object to test for equality
Returns:
true if the Any objects are equal; false otherwise
See Also:
CORBA package comments for unimplemented features

type

public abstract TypeCode type()
Returns type information for the element contained in this Any object.

Returns:
the TypeCode object containing type information about the value contained in this Any object

type

public abstract void type(TypeCode t)
Sets this Any object's type field to the given TypeCode object and clears its value.

Note that using this method to set the type code wipes out the value if there is one. The method is provided primarily so that the type may be set properly for IDL out parameters. Generally, setting the type is done by the insert_X methods, which will set the type to X if it is not already set to X.

Parameters:
t - the TypeCode object giving information for the value in this Any object

read_value

public abstract void read_value(InputStream is,
                                TypeCode t)
                         throws MARSHAL
Reads off (unmarshals) the value of an Any object from the given input stream using the given typecode.

Parameters:
is - the org.omg.CORBA.portable.InputStream object from which to read the value contained in this Any object
t - a TypeCode object containing type information about the value to be read
Throws:
MARSHAL - when the given TypeCode object is not consistent with the value that was contained in the input stream

write_value

public abstract void write_value(OutputStream os)
Writes out the value of this Any object to the given output stream. If both typecode and value need to be written, use create_output_stream() to create an OutputStream, then use write_any on the OutputStream.

If this method is called on an Any object that has not had a value inserted into its value field, it will throw the exception java.lang.NullPointerException.

Parameters:
os - the org.omg.CORBA.portable.OutputStream object into which to marshal the value of this Any object

create_output_stream

public abstract OutputStream create_output_stream()
Creates an output stream into which this Any object's value can be marshalled.

Returns:
the newly-created OutputStream

create_input_stream

public abstract InputStream create_input_stream()
Creates an input stream from which this Any object's value can be unmarshalled.

Returns:
the newly-created InputStream

extract_short

public abstract short extract_short()
                             throws BAD_OPERATION
Extracts the short in this Any object's value field.

Returns:
the short stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than a short or the value field has not yet been set

insert_short

public abstract void insert_short(short s)
Inserts the given short into this Any object's value field.

Parameters:
s - the short to insert into this Any object

extract_long

public abstract int extract_long()
                          throws BAD_OPERATION
Extracts the int in this Any object's value field.

Returns:
the int stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than an int or the value field has not yet been set

insert_long

public abstract void insert_long(int l)
Inserts the given int into this Any object's value field.

Parameters:
l - the int to insert into this Any object

extract_longlong

public abstract long extract_longlong()
                               throws BAD_OPERATION
Extracts the long in this Any object's value field.

Returns:
the long stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than a long or the value field has not yet been set

insert_longlong

public abstract void insert_longlong(long l)
Inserts the given long into this Any object's value field.

Parameters:
l - the long to insert into this Any object

extract_ushort

public abstract short extract_ushort()
                              throws BAD_OPERATION
Extracts the short in this Any object's value field.

Returns:
the short stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than a short or the value field has not yet been set

insert_ushort

public abstract void insert_ushort(short s)
Inserts the given short into this Any object's value field.

Parameters:
s - the short to insert into this Any object

extract_ulong

public abstract int extract_ulong()
                           throws BAD_OPERATION
Extracts the int in this Any object's value field.

Returns:
the int stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than an int or the value field has not yet been set

insert_ulong

public abstract void insert_ulong(int l)
Inserts the given int into this Any object's value field.

Parameters:
l - the int to insert into this Any object

extract_ulonglong

public abstract long extract_ulonglong()
                                throws BAD_OPERATION
Extracts the long in this Any object's value field.

Returns:
the long stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than a long or the value field has not yet been set

insert_ulonglong

public abstract void insert_ulonglong(long l)
Inserts the given long into this Any object's value field.

Parameters:
l - the long to insert into this Any object

extract_float

public abstract float extract_float()
                             throws BAD_OPERATION
Extracts the float in this Any object's value field.

Returns:
the float stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than a float or the value field has not yet been set

insert_float

public abstract void insert_float(float f)
Inserts the given float into this Any object's value field.

Parameters:
f - the float to insert into this Any object

extract_double

public abstract double extract_double()
                               throws BAD_OPERATION
Extracts the double in this Any object's value field.

Returns:
the double stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than a double or the value field has not yet been set

insert_double

public abstract void insert_double(double d)
Inserts the given double into this Any object's value field.

Parameters:
d - the double to insert into this Any object

extract_boolean

public abstract boolean extract_boolean()
                                 throws BAD_OPERATION
Extracts the boolean in this Any object's value field.

Returns:
the boolean stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than a boolean or the value field has not yet been set

insert_boolean

public abstract void insert_boolean(boolean b)
Inserts the given boolean into this Any object's value field.

Parameters:
b - the boolean to insert into this Any object

extract_char

public abstract char extract_char()
                           throws BAD_OPERATION
Extracts the char in this Any object's value field.

Returns:
the char stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than a char or the value field has not yet been set

insert_char

public abstract void insert_char(char c)
                          throws DATA_CONVERSION
Inserts the given char into this Any object's value field.

Parameters:
c - the char to insert into this Any object
Throws:
DATA_CONVERSION - if there is a data conversion error

extract_wchar

public abstract char extract_wchar()
                            throws BAD_OPERATION
Extracts the char in this Any object's value field.

Returns:
the char stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than a char or the value field has not yet been set

insert_wchar

public abstract void insert_wchar(char c)
Inserts the given char into this Any object's value field.

Parameters:
c - the char to insert into this Any object

extract_octet

public abstract byte extract_octet()
                            throws BAD_OPERATION
Extracts the byte in this Any object's value field.

Returns:
the byte stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than a byte or the value field has not yet been set

insert_octet

public abstract void insert_octet(byte b)
Inserts the given byte into this Any object's value field.

Parameters:
b - the byte to insert into this Any object

extract_any

public abstract Any extract_any()
                         throws BAD_OPERATION
Extracts the Any object in this Any object's value field.

Returns:
the Any object stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than an Any object or the value field has not yet been set

insert_any

public abstract void insert_any(Any a)
Inserts the given Any object into this Any object's value field.

Parameters:
a - the Any object to insert into this Any object

extract_Object

public abstract Object extract_Object()
                               throws BAD_OPERATION
Extracts the org.omg.CORBA.Object in this Any object's value field.

Returns:
the org.omg.CORBA.Object stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than an org.omg.CORBA.Object or the value field has not yet been set

insert_Object

public abstract void insert_Object(Object o)
Inserts the given org.omg.CORBA.Object object into this Any object's value field.

Parameters:
o - the org.omg.CORBA.Object object to insert into this Any object

extract_Value

public abstract Serializable extract_Value()
                                    throws BAD_OPERATION
Extracts the java.io.Serializable object in this Any object's value field.

Returns:
the java.io.Serializable object stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than a java.io.Serializable object or the value field has not yet been set

insert_Value

public abstract void insert_Value(Serializable v)
Inserts the given java.io.Serializable object into this Any object's value field.

Parameters:
v - the java.io.Serializable object to insert into this Any object

insert_Value

public abstract void insert_Value(Serializable v,
                                  TypeCode t)
                           throws MARSHAL
Inserts the given java.io.Serializable object into this Any object's value field.

Parameters:
v - the java.io.Serializable object to insert into this Any object
t - the TypeCode object that is to be inserted into this Any object's type field and that describes the java.io.Serializable object being inserted
Throws:
MARSHAL - if the ORB has a problem marshalling or unmarshalling parameters

insert_Object

public abstract void insert_Object(Object o,
                                   TypeCode t)
                            throws BAD_PARAM
Inserts the given org.omg.CORBA.Object object into this Any object's value field.

Parameters:
o - the org.omg.CORBA.Object instance to insert into this Any object
t - the TypeCode object that is to be inserted into this Any object and that describes the Object being inserted
Throws:
BAD_OPERATION - if this method is invalid for this Any object
BAD_PARAM

extract_string

public abstract String extract_string()
                               throws BAD_OPERATION
Extracts the String object in this Any object's value field.

Returns:
the String object stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than a String object or the value field has not yet been set

insert_string

public abstract void insert_string(String s)
                            throws DATA_CONVERSION,
                                   MARSHAL
Inserts the given String object into this Any object's value field.

Parameters:
s - the String object to insert into this Any object
Throws:
DATA_CONVERSION - if there is a data conversion error
MARSHAL - if the ORB has a problem marshalling or unmarshalling parameters

extract_wstring

public abstract String extract_wstring()
                                throws BAD_OPERATION
Extracts the String object in this Any object's value field.

Returns:
the String object stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than a String object or the value field has not yet been set

insert_wstring

public abstract void insert_wstring(String s)
                             throws MARSHAL
Inserts the given String object into this Any object's value field.

Parameters:
s - the String object to insert into this Any object
Throws:
MARSHAL - if the ORB has a problem marshalling or unmarshalling parameters

extract_TypeCode

public abstract TypeCode extract_TypeCode()
                                   throws BAD_OPERATION
Extracts the TypeCode object in this Any object's value field.

Returns:
the TypeCode object stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than a TypeCode object or the value field has not yet been set

insert_TypeCode

public abstract void insert_TypeCode(TypeCode t)
Inserts the given TypeCode object into this Any object's value field.

Parameters:
t - the TypeCode object to insert into this Any object

extract_Principal

@Deprecated
public Principal extract_Principal()
                            throws BAD_OPERATION
Deprecated. Deprecated by CORBA 2.2.

Extracts the Principal object in this Any object's value field. Note that the class Principal has been deprecated.

Returns:
the Principal object stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than a Principal object or the value field has not yet been set
See Also:
CORBA package comments for unimplemented features

insert_Principal

@Deprecated
public void insert_Principal(Principal p)
Deprecated. Deprecated by CORBA 2.2.

Inserts the given Principal object into this Any object's value field. Note that the class Principal has been deprecated.

Parameters:
p - the Principal object to insert into this Any object
See Also:
CORBA package comments for unimplemented features

extract_Streamable

public Streamable extract_Streamable()
                              throws BAD_INV_ORDER
Extracts a Streamable from this Any object's value field. This method allows the extraction of non-primitive IDL types.

Returns:
the Streamable stored in the Any object.
Throws:
BAD_INV_ORDER - if the caller has invoked operations in the wrong order
See Also:
CORBA package comments for unimplemented features

insert_Streamable

public void insert_Streamable(Streamable s)
Inserts the given Streamable object into this Any object's value field. This method allows the insertion of non-primitive IDL types.

Parameters:
s - the Streamable object to insert into this Any object; may be a non-primitive IDL type
See Also:
CORBA package comments for unimplemented features

extract_fixed

public BigDecimal extract_fixed()
Extracts the java.math.BigDecimal object in this Any object's value field.

Returns:
the java.math.BigDecimal object stored in this Any object
Throws:
BAD_OPERATION - if this Any object contains something other than a java.math.BigDecimal object or the value field has not yet been set
See Also:
CORBA package comments for unimplemented features

insert_fixed

public void insert_fixed(BigDecimal value)
Throws an org.omg.CORBA.NO_IMPLEMENT exception.

Inserts the given java.math.BigDecimal object into this Any object's value field.

Parameters:
value - the java.math.BigDecimal object to insert into this Any object
See Also:
CORBA package comments for unimplemented features

insert_fixed

public void insert_fixed(BigDecimal value,
                         TypeCode type)
                  throws BAD_INV_ORDER
Throws an org.omg.CORBA.NO_IMPLEMENT exception.

Inserts the given java.math.BigDecimal object into this Any object's value field.

Parameters:
value - the java.math.BigDecimal object to insert into this Any object
type - the TypeCode object that is to be inserted into this Any object's type field and that describes the java.math.BigDecimal object being inserted
Throws:
BAD_INV_ORDER - if this method is invoked improperly
See Also:
CORBA package comments for unimplemented features
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AnyHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class AnyHolder

java.lang.Object
    extended by  org.omg.CORBA.AnyHolder
All Implemented Interfaces:
Streamable
public final class AnyHolder
extends Object
implements Streamable

The Holder for Any. For more information on Holder files, see "Generated Files: Holder Files".

A Holder class for Any objects that is used to store "out" and "inout" parameters in IDL methods. If an IDL method signature has an IDL any as an "out" or "inout" parameter, the programmer must pass an instance of AnyHolder as the corresponding parameter in the method invocation; for "inout" parameters, the programmer must also fill the "in" value to be sent to the server. Before the method invocation returns, the ORB will fill in the value corresponding to the "out" value returned from the server.

If myAnyHolder is an instance of AnyHolder, the value stored in its value field can be accessed with myAnyHolder.value.

Since:
JDK1.2

Field Summary
 Any value
The Any value held by this AnyHolder object.
Constructor Summary
AnyHolder()
Constructs a new AnyHolder object with its value field initialized to null.
AnyHolder(Any initial)
Constructs a new AnyHolder object for the given Any object.
Method Summary
void | _read(InputStream input) Reads from input and initalizes the value in the Holder with the unmarshalled data.
TypeCode | _type() Returns the TypeCode object corresponding to the value held in this AnyHolder object.
void | _write(OutputStream output) Marshals to output the value in this AnyHolder object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public Any value
The Any value held by this AnyHolder object.

Constructor Detail

AnyHolder

public AnyHolder()
Constructs a new AnyHolder object with its value field initialized to null.

AnyHolder

public AnyHolder(Any initial)
Constructs a new AnyHolder object for the given Any object.

Parameters:
initial - the Any object with which to initialize the value field of the new AnyHolder object
Method Detail

_read

public void _read(InputStream input)
Reads from input and initalizes the value in the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
input - the InputStream containing CDR formatted data from the wire.

_write

public void _write(OutputStream output)
Marshals to output the value in this AnyHolder object.

Specified by:
_write in interface Streamable
Parameters:
output - the OutputStream which will contain the CDR formatted data.

_type

public TypeCode _type()
Returns the TypeCode object corresponding to the value held in this AnyHolder object.

Specified by:
_type in interface Streamable
Returns:
the TypeCode of the value held in this AnyHolder object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AnySeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class AnySeqHelper

java.lang.Object
    extended by  org.omg.CORBA.AnySeqHelper

public abstract class AnySeqHelper
extends Object

The Helper for AnySeq. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/AnySeqHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications :

  • ORB core as defined by CORBA 2.3.1 (formal/99-10-07)
  • IDL/Java Language Mapping as defined in ptc/00-01-08

Constructor Summary
AnySeqHelper()
Method Summary
static Any[] | extract(Any a)
static String | id()
static void | insert(Any a, Any[] that)
static Any[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, Any[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AnySeqHelper

public AnySeqHelper()
Method Detail

insert

public static void insert(Any a,
                          Any[] that)

extract

public static Any[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static Any[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         Any[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AnySeqHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class AnySeqHolder

java.lang.Object
    extended by  org.omg.CORBA.AnySeqHolder
All Implemented Interfaces:
Streamable
public final class AnySeqHolder
extends Object
implements Streamable

The Holder for AnySeq. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/AnySeqHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00

Field Summary
 Any[] value
Constructor Summary
AnySeqHolder()
AnySeqHolder(Any[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public Any[] value
Constructor Detail

AnySeqHolder

public AnySeqHolder()

AnySeqHolder

public AnySeqHolder(Any[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ARG_IN

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface ARG_IN

public interface ARG_IN

Signifies an "input" argument to an invocation, meaning that the argument is being passed from the client to the server. ARG_IN.value is one of the possible values used to indicate the direction in which a parameter is being passed during an invocation performed using the Dynamic Invocation Interface (DII).

The code fragment below shows a typical usage:

    ORB orb = ORB.init(args, null);
    org.omg.CORBA.NamedValue nv = orb.create_named_value(
         "IDLArgumentIdentifier", myAny, org.omg.CORBA.ARG_IN.value);

Since:
JDK1.2
See Also:
NamedValue

Field Summary
static int value
The value indicating an input argument.

Field Detail

value

static final int value
The value indicating an input argument.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ARG_INOUT

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface ARG_INOUT

public interface ARG_INOUT

Signifies an argument used for both input and output in an invocation, meaning that the argument is being passed from the client to the server and then back from the server to the client. ARG_INOUT.value is one of the possible values used to indicate the direction in which a parameter is being passed during a dynamic invocation using the Dynamic Invocation Interface (DII).

The code fragment below shows a typical usage:

  ORB orb = ORB.init(args, null);
  org.omg.CORBA.NamedValue nv = orb.create_named_value(
        "argumentIdentifier", myAny, org.omg.CORBA.ARG_INOUT.value);

Since:
JDK1.2
See Also:
NamedValue

Field Summary
static int value
The constant value indicating an argument used for both input and output.

Field Detail

value

static final int value
The constant value indicating an argument used for both input and output.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ARG_OUT

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface ARG_OUT

public interface ARG_OUT

A constant that signifies an "output" argument to an invocation, meaning that the argument is being passed from the server to the client. ARG_OUT.value is one of the possible values used to indicate the direction in which a parameter is being passed during a dynamic invocation using the Dynamic Invocation Interface (DII).

The code fragment below shows a typical usage:

  ORB orb = ORB.init(args, null);
  org.omg.CORBA.NamedValue nv = orb.create_named_value(
        "argumentIdentifier", myAny, org.omg.CORBA.ARG_OUT.value);

Since:
JDK1.2
See Also:
NamedValue

Field Summary
static int value
The constant value indicating an output argument.

Field Detail

value

static final int value
The constant value indicating an output argument.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BAD_CONTEXT

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class BAD_CONTEXT

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.BAD_CONTEXT
All Implemented Interfaces:
Serializable
public final class BAD_CONTEXT
extends SystemException

Exception thrown when an operation is invoked by a client but the passed context does not contain the context values required by the operation.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
BAD_CONTEXT()
Constructs a BAD_CONTEXT exception with a default minor code of 0 and a completion state of COMPLETED_NO.
BAD_CONTEXT(int minor, CompletionStatus completed)
Constructs a BAD_CONTEXT exception with the specified minor code and completion status.
BAD_CONTEXT(String s)
Constructs a BAD_CONTEXT exception with the specified detail message, a minor code of 0 and a completion state of COMPLETED_NO.
BAD_CONTEXT(String s, int minor, CompletionStatus completed)
Constructs a BAD_CONTEXT exception with the specified detail message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

BAD_CONTEXT

public BAD_CONTEXT()
Constructs a BAD_CONTEXT exception with a default minor code of 0 and a completion state of COMPLETED_NO.

BAD_CONTEXT

public BAD_CONTEXT(String s)
Constructs a BAD_CONTEXT exception with the specified detail message, a minor code of 0 and a completion state of COMPLETED_NO.

Parameters:
s - a String object containing a detail message

BAD_CONTEXT

public BAD_CONTEXT(int minor,
                   CompletionStatus completed)
Constructs a BAD_CONTEXT exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - an instance of CompletionStatus indicating the completion status

BAD_CONTEXT

public BAD_CONTEXT(String s,
                   int minor,
                   CompletionStatus completed)
Constructs a BAD_CONTEXT exception with the specified detail message, minor code, and completion status. A detail message is a String that describes this particular exception.

Parameters:
s - the String containing a detail message
minor - the minor code
completed - an instance of CompletionStatus indicating the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BAD_INV_ORDER

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class BAD_INV_ORDER

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.BAD_INV_ORDER
All Implemented Interfaces:
Serializable
public final class BAD_INV_ORDER
extends SystemException

This exception indicates that the caller has invoked operations in the wrong order. For example, it can be raised by an ORB if an application makes an ORB-related call without having correctly initialized the ORB first.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
BAD_INV_ORDER()
Constructs a BAD_INV_ORDER exception with a default minor code of 0 and a completion state of COMPLETED_NO.
BAD_INV_ORDER(int minor, CompletionStatus completed)
Constructs a BAD_INV_ORDER exceptionBAD_INV_ORDER with the specified minor code and completion status.
BAD_INV_ORDER(String s)
Constructs a BAD_INV_ORDER exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.
BAD_INV_ORDER(String s, int minor, CompletionStatus completed)
Constructs a BAD_INV_ORDER exception with the specified detail message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

BAD_INV_ORDER

public BAD_INV_ORDER()
Constructs a BAD_INV_ORDER exception with a default minor code of 0 and a completion state of COMPLETED_NO.

BAD_INV_ORDER

public BAD_INV_ORDER(String s)
Constructs a BAD_INV_ORDER exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message

BAD_INV_ORDER

public BAD_INV_ORDER(int minor,
                     CompletionStatus completed)
Constructs a BAD_INV_ORDER exceptionBAD_INV_ORDER with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - an instance of CompletionStatus indicating the completion status

BAD_INV_ORDER

public BAD_INV_ORDER(String s,
                     int minor,
                     CompletionStatus completed)
Constructs a BAD_INV_ORDER exception with the specified detail message, minor code, and completion status. A detail message is a String that describes this particular exception.

Parameters:
s - the String containing a detail message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BAD_OPERATION

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class BAD_OPERATION

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.BAD_OPERATION
All Implemented Interfaces:
Serializable
public final class BAD_OPERATION
extends SystemException

Exception thrown when an object reference denotes an existing object, but that the object does not support the operation that was invoked.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
BAD_OPERATION()
Constructs a BAD_OPERATION exception with a default minor code of 0 and a completion state of COMPLETED_NO.
BAD_OPERATION(int minor, CompletionStatus completed)
Constructs a BAD_OPERATION exception with the specified minor code and completion status.
BAD_OPERATION(String s)
Constructs a BAD_OPERATION exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.
BAD_OPERATION(String s, int minor, CompletionStatus completed)
Constructs a BAD_OPERATION exception with the specified detail message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

BAD_OPERATION

public BAD_OPERATION()
Constructs a BAD_OPERATION exception with a default minor code of 0 and a completion state of COMPLETED_NO.

BAD_OPERATION

public BAD_OPERATION(String s)
Constructs a BAD_OPERATION exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message

BAD_OPERATION

public BAD_OPERATION(int minor,
                     CompletionStatus completed)
Constructs a BAD_OPERATION exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - an instance of CompletionStatus indicating the completion status

BAD_OPERATION

public BAD_OPERATION(String s,
                     int minor,
                     CompletionStatus completed)
Constructs a BAD_OPERATION exception with the specified detail message, minor code, and completion status. A detail message is a String that describes this particular exception.

Parameters:
s - the String containing a detail message
minor - the minor code
completed - an instance of CompletionStatus indicating the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BAD_PARAM

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class BAD_PARAM

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.BAD_PARAM
All Implemented Interfaces:
Serializable
public final class BAD_PARAM
extends SystemException

Exception thrown when a parameter passed to a call is out of range or otherwise considered illegal. An ORB may raise this exception if null values or null pointers are passed to an operation (for language mappings where the concept of a null pointers or null values applies). BAD_PARAM can also be raised as a result of a client generating requests with incorrect parameters using the DII.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions, meaning of minor codes

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
BAD_PARAM()
Constructs a BAD_PARAM exception with a default minor code of 0 and a completion state of COMPLETED_NO.
BAD_PARAM(int minor, CompletionStatus completed)
Constructs a BAD_PARAM exception with the specified minor code and completion status.
BAD_PARAM(String s)
Constructs a BAD_PARAM exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.
BAD_PARAM(String s, int minor, CompletionStatus completed)
Constructs a BAD_PARAM exception with the specified detail message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

BAD_PARAM

public BAD_PARAM()
Constructs a BAD_PARAM exception with a default minor code of 0 and a completion state of COMPLETED_NO.

BAD_PARAM

public BAD_PARAM(String s)
Constructs a BAD_PARAM exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message describing this exception

BAD_PARAM

public BAD_PARAM(int minor,
                 CompletionStatus completed)
Constructs a BAD_PARAM exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

BAD_PARAM

public BAD_PARAM(String s,
                 int minor,
                 CompletionStatus completed)
Constructs a BAD_PARAM exception with the specified detail message, minor code, and completion status. A detail message is a String that describes this particular exception.

Parameters:
s - the String containing a detail message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BAD_POLICY

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface BAD_POLICY

public interface BAD_POLICY

A PolicyErrorCode which would be filled in the PolicyError exception.

Field Summary
static short value
The Error code in PolicyError exception.

Field Detail

value

static final short value
The Error code in PolicyError exception.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BAD_POLICY_TYPE

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface BAD_POLICY_TYPE

public interface BAD_POLICY_TYPE

A PolicyErrorCode which would be filled in the PolicyError exception.

Field Summary
static short value
The Error code in PolicyError exception.

Field Detail

value

static final short value
The Error code in PolicyError exception.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BAD_POLICY_VALUE

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface BAD_POLICY_VALUE

public interface BAD_POLICY_VALUE

Contains the value used to indicate a policy value that is incorrect for a valid policy type in a call to the create_policy method defined in the ORB class.

Field Summary
static short value
The value used to represent a bad policy value error in a PolicyError exception.

Field Detail

value

static final short value
The value used to represent a bad policy value error in a PolicyError exception.

See Also:
PolicyError, Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BAD_QOS

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class BAD_QOS

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.BAD_QOS
All Implemented Interfaces:
Serializable
public final class BAD_QOS
extends SystemException

The BAD_QOS exception is raised whenever an object cannot support the quality of service required by an invocation parameter that has a quality of service semantics associated with it.

Since:
J2SE 1.5
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
BAD_QOS()
Constructs an BAD_QOS exception with minor code set to 0 and CompletionStatus set to COMPLETED_NO.
BAD_QOS(int minorCode, CompletionStatus completionStatus)
Constructs an BAD_QOS exception with the specified minor code and completion status.
BAD_QOS(String detailMessage)
Constructs an BAD_QOS exception with the specified message.
BAD_QOS(String detailMessage, int minorCode, CompletionStatus completionStatus)
Constructs an BAD_QOS exception with the specified message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

BAD_QOS

public BAD_QOS()
Constructs an BAD_QOS exception with minor code set to 0 and CompletionStatus set to COMPLETED_NO.

BAD_QOS

public BAD_QOS(String detailMessage)
Constructs an BAD_QOS exception with the specified message.

Parameters:
detailMessage - string containing a detailed message.

BAD_QOS

public BAD_QOS(int minorCode,
               CompletionStatus completionStatus)
Constructs an BAD_QOS exception with the specified minor code and completion status.

Parameters:
minorCode - minor code.
completionStatus - completion status.

BAD_QOS

public BAD_QOS(String detailMessage,
               int minorCode,
               CompletionStatus completionStatus)
Constructs an BAD_QOS exception with the specified message, minor code, and completion status.

Parameters:
detailMessage - string containing a detailed message.
minorCode - minor code.
completionStatus - completion status.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BAD_TYPECODE

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class BAD_TYPECODE

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.BAD_TYPECODE
All Implemented Interfaces:
Serializable
public final class BAD_TYPECODE
extends SystemException

Exception thrown when the ORB has encountered a malformed type code (for example, a type code with an invalid TCKind value).

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
BAD_TYPECODE()
Constructs a BAD_TYPECODE exception with a default minor code of 0 and a completion state of COMPLETED_NO.
BAD_TYPECODE(int minor, CompletionStatus completed)
Constructs a BAD_TYPECODE exception with the specified minor code and completion status.
BAD_TYPECODE(String s)
Constructs a BAD_TYPECODE exception with the specified detail, a minor code of 0, and a completion state of COMPLETED_NO.
BAD_TYPECODE(String s, int minor, CompletionStatus completed)
Constructs a BAD_TYPECODE exception with the specified detail message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

BAD_TYPECODE

public BAD_TYPECODE()
Constructs a BAD_TYPECODE exception with a default minor code of 0 and a completion state of COMPLETED_NO.

BAD_TYPECODE

public BAD_TYPECODE(String s)
Constructs a BAD_TYPECODE exception with the specified detail, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message

BAD_TYPECODE

public BAD_TYPECODE(int minor,
                    CompletionStatus completed)
Constructs a BAD_TYPECODE exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - an instance of CompletionStatus indicating the completion status

BAD_TYPECODE

public BAD_TYPECODE(String s,
                    int minor,
                    CompletionStatus completed)
Constructs a BAD_TYPECODE exception with the specified detail message, minor code, and completion status. A detail message is a String that describes this particular exception.

Parameters:
s - the String containing a detail message
minor - the minor code
completed - an instance of CompletionStatus indicating the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BooleanHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class BooleanHolder

java.lang.Object
    extended by  org.omg.CORBA.BooleanHolder
All Implemented Interfaces:
Streamable
public final class BooleanHolder
extends Object
implements Streamable

The Holder for Boolean. For more information on Holder files, see "Generated Files: Holder Files".

A Holder class for a boolean that is used to store "out" and "inout" parameters in IDL methods. If an IDL method signature has an IDL boolean as an "out" or "inout" parameter, the programmer must pass an instance of BooleanHolder as the corresponding parameter in the method invocation; for "inout" parameters, the programmer must also fill the "in" value to be sent to the server. Before the method invocation returns, the ORB will fill in the value corresponding to the "out" value returned from the server.

If myBooleanHolder is an instance of BooleanHolder, the value stored in its value field can be accessed with myBooleanHolder.value.

Since:
JDK1.2

Field Summary
 boolean value
The boolean value held by this BooleanHolder object.
Constructor Summary
BooleanHolder()
Constructs a new BooleanHolder object with its value field initialized to false.
BooleanHolder(boolean initial)
Constructs a new BooleanHolder object with its value field initialized with the given boolean.
Method Summary
void | _read(InputStream input) Reads unmarshalled data from input and assigns it to this BooleanHolder object's value field.
TypeCode | _type() Retrieves the TypeCode object that corresponds to the value held in this BooleanHolder object.
void | _write(OutputStream output) Marshals the value in this BooleanHolder object's value field to the output stream output.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public boolean value
The boolean value held by this BooleanHolder object.

Constructor Detail

BooleanHolder

public BooleanHolder()
Constructs a new BooleanHolder object with its value field initialized to false.

BooleanHolder

public BooleanHolder(boolean initial)
Constructs a new BooleanHolder object with its value field initialized with the given boolean.

Parameters:
initial - the boolean with which to initialize the value field of the newly-created BooleanHolder object
Method Detail

_read

public void _read(InputStream input)
Reads unmarshalled data from input and assigns it to this BooleanHolder object's value field.

Specified by:
_read in interface Streamable
Parameters:
input - the InputStream object containing CDR formatted data from the wire

_write

public void _write(OutputStream output)
Marshals the value in this BooleanHolder object's value field to the output stream output.

Specified by:
_write in interface Streamable
Parameters:
output - the OutputStream which will contain the CDR formatted data

_type

public TypeCode _type()
Retrieves the TypeCode object that corresponds to the value held in this BooleanHolder object.

Specified by:
_type in interface Streamable
Returns:
the TypeCode for the value held in this BooleanHolder object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BooleanSeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class BooleanSeqHelper

java.lang.Object
    extended by  org.omg.CORBA.BooleanSeqHelper

public abstract class BooleanSeqHelper
extends Object

The Helper for BooleanSeq. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/BooleanSeqHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications :

  • ORB core as defined by CORBA 2.3.1 (formal/99-10-07)
  • IDL/Java Language Mapping as defined in ptc/00-01-08

Constructor Summary
BooleanSeqHelper()
Method Summary
static boolean[] | extract(Any a)
static String | id()
static void | insert(Any a, boolean[] that)
static boolean[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, boolean[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BooleanSeqHelper

public BooleanSeqHelper()
Method Detail

insert

public static void insert(Any a,
                          boolean[] that)

extract

public static boolean[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static boolean[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         boolean[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BooleanSeqHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class BooleanSeqHolder

java.lang.Object
    extended by  org.omg.CORBA.BooleanSeqHolder
All Implemented Interfaces:
Streamable
public final class BooleanSeqHolder
extends Object
implements Streamable

The Holder for BooleanSeq. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/BooleanSeqHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00

Field Summary
 boolean[] value
Constructor Summary
BooleanSeqHolder()
BooleanSeqHolder(boolean[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public boolean[] value
Constructor Detail

BooleanSeqHolder

public BooleanSeqHolder()

BooleanSeqHolder

public BooleanSeqHolder(boolean[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Bounds

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class Bounds

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CORBA.Bounds
All Implemented Interfaces:
Serializable, IDLEntity
public final class Bounds
extends UserException

A user exception thrown when a parameter is not within the legal bounds for the object that a method is trying to access.

See Also:
documentation on Java IDL exceptions

Constructor Summary
Bounds()
Constructs an Bounds with no specified detail message.
Bounds(String reason)
Constructs an Bounds with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Bounds

public Bounds()
Constructs an Bounds with no specified detail message.

Bounds

public Bounds(String reason)
Constructs an Bounds with the specified detail message.

Parameters:
reason - the detail message.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ByteHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ByteHolder

java.lang.Object
    extended by  org.omg.CORBA.ByteHolder
All Implemented Interfaces:
Streamable
public final class ByteHolder
extends Object
implements Streamable

The Holder for Byte. For more information on Holder files, see "Generated Files: Holder Files".

A Holder class for a byte that is used to store "out" and "inout" parameters in IDL methods. If an IDL method signature has an IDL octet as an "out" or "inout" parameter, the programmer must pass an instance of ByteHolder as the corresponding parameter in the method invocation; for "inout" parameters, the programmer must also fill the "in" value to be sent to the server. Before the method invocation returns, the ORB will fill in the value corresponding to the "out" value returned from the server.

If myByteHolder is an instance of ByteHolder, the value stored in its value field can be accessed with myByteHolder.value.

Since:
JDK1.2

Field Summary
 byte value
The byte value held by this ByteHolder object.
Constructor Summary
ByteHolder()
Constructs a new ByteHolder object with its value field initialized to 0.
ByteHolder(byte initial)
Constructs a new ByteHolder object for the given byte.
Method Summary
void | _read(InputStream input) Reads from input and initalizes the value in this ByteHolder object with the unmarshalled data.
TypeCode | _type() Returns the TypeCode corresponding to the value held in this ByteHolder object.
void | _write(OutputStream output) Marshals to output the value in this ByteHolder object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public byte value
The byte value held by this ByteHolder object.

Constructor Detail

ByteHolder

public ByteHolder()
Constructs a new ByteHolder object with its value field initialized to 0.

ByteHolder

public ByteHolder(byte initial)
Constructs a new ByteHolder object for the given byte.

Parameters:
initial - the byte with which to initialize the value field of the new ByteHolder object
Method Detail

_read

public void _read(InputStream input)
Reads from input and initalizes the value in this ByteHolder object with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
input - the InputStream containing CDR formatted data from the wire.

_write

public void _write(OutputStream output)
Marshals to output the value in this ByteHolder object.

Specified by:
_write in interface Streamable
Parameters:
output - the OutputStream which will contain the CDR formatted data.

_type

public TypeCode _type()
Returns the TypeCode corresponding to the value held in this ByteHolder object.

Specified by:
_type in interface Streamable
Returns:
the TypeCode of the value held in this ByteHolder object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CharHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class CharHolder

java.lang.Object
    extended by  org.omg.CORBA.CharHolder
All Implemented Interfaces:
Streamable
public final class CharHolder
extends Object
implements Streamable

The Holder for Char. For more information on Holder files, see "Generated Files: Holder Files".

A Holder class for a char that is used to store "out" and "inout" parameters in IDL methods. If an IDL method signature has an IDL char as an "out" or "inout" parameter, the programmer must pass an instance of CharHolder as the corresponding parameter in the method invocation; for "inout" parameters, the programmer must also fill the "in" value to be sent to the server. Before the method invocation returns, the ORB will fill in the value corresponding to the "out" value returned from the server.

If myCharHolder is an instance of CharHolder, the value stored in its value field can be accessed with myCharHolder.value.

Since:
JDK1.2

Field Summary
 char value
The char value held by this CharHolder object.
Constructor Summary
CharHolder()
Constructs a new CharHolder object with its value field initialized to 0.
CharHolder(char initial)
Constructs a new CharHolder object for the given char.
Method Summary
void | _read(InputStream input) Reads from input and initalizes the value in this CharHolder object with the unmarshalled data.
TypeCode | _type() Returns the TypeCode object corresponding to the value held in this CharHolder object.
void | _write(OutputStream output) Marshals to output the value in this CharHolder object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public char value
The char value held by this CharHolder object.

Constructor Detail

CharHolder

public CharHolder()
Constructs a new CharHolder object with its value field initialized to 0.

CharHolder

public CharHolder(char initial)
Constructs a new CharHolder object for the given char.

Parameters:
initial - the char with which to initialize the value field of the new CharHolder object
Method Detail

_read

public void _read(InputStream input)
Reads from input and initalizes the value in this CharHolder object with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
input - the InputStream containing CDR formatted data from the wire

_write

public void _write(OutputStream output)
Marshals to output the value in this CharHolder object.

Specified by:
_write in interface Streamable
Parameters:
output - the OutputStream which will contain the CDR formatted data

_type

public TypeCode _type()
Returns the TypeCode object corresponding to the value held in this CharHolder object.

Specified by:
_type in interface Streamable
Returns:
the TypeCode of the value held in this CharHolder object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CharSeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class CharSeqHelper

java.lang.Object
    extended by  org.omg.CORBA.CharSeqHelper

public abstract class CharSeqHelper
extends Object

The Helper for CharSeq. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/CharSeqHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications :

  • ORB core as defined by CORBA 2.3.1 (formal/99-10-07)
  • IDL/Java Language Mapping as defined in ptc/00-01-08

Constructor Summary
CharSeqHelper()
Method Summary
static char[] | extract(Any a)
static String | id()
static void | insert(Any a, char[] that)
static char[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, char[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CharSeqHelper

public CharSeqHelper()
Method Detail

insert

public static void insert(Any a,
                          char[] that)

extract

public static char[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static char[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         char[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CharSeqHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class CharSeqHolder

java.lang.Object
    extended by  org.omg.CORBA.CharSeqHolder
All Implemented Interfaces:
Streamable
public final class CharSeqHolder
extends Object
implements Streamable

The Holder for CharSeq. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/CharSeqHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00

Field Summary
 char[] value
Constructor Summary
CharSeqHolder()
CharSeqHolder(char[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public char[] value
Constructor Detail

CharSeqHolder

public CharSeqHolder()

CharSeqHolder

public CharSeqHolder(char[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class org.omg.CORBA.ACTIVITY_COMPLETED

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ACTIVITY_COMPLETED

No usage of org.omg.CORBA.ACTIVITY_COMPLETED

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ACTIVITY_REQUIRED

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ACTIVITY_REQUIRED

No usage of org.omg.CORBA.ACTIVITY_REQUIRED

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.Any

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.Any

Packages that use Any
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextExtPackage | This package contains the following classes, which are used in org.omg.CosNaming.NamingContextExt:
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.
org.omg.Dynamic | This package contains the Dynamic module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.9.
org.omg.DynamicAny | Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.
org.omg.DynamicAny.DynAnyFactoryPackage | This package contains classes and exceptions from the DynAnyFactory interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.2.
org.omg.DynamicAny.DynAnyPackage | This package contains classes and exceptions from the DynAny interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.IOP.CodecFactoryPackage | This package contains the exceptions specified in the IOP::CodeFactory interface (as part of the Portable Interceptors spec).
org.omg.IOP.CodecPackage | This package is generated from the IOP::Codec IDL interface definition.
org.omg.Messaging | This package contains the Messaging module specified in the OMG CORBA Messaging specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07.
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.
org.omg.PortableInterceptor.ORBInitInfoPackage | This package contains the exceptions and typedefs from the ORBInitInfo local interface of the PortableInterceptor module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.7.2.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.CurrentPackage | Provides method implementations with access to the identity of the object on which the method was invoked.
org.omg.PortableServer.POAManagerPackage | Encapsulates the processing state of the POAs it is associated with.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.

Uses of Any in org.omg.CORBA

Fields in org.omg.CORBA declared as Any
Any | UnknownUserException.except The Any instance that contains the actual user exception thrown by the server.
Any | UnionMember.label The label of the union member described by this UnionMember object.
Any[] | AnySeqHolder.value
Any | AnyHolder.value The Any value held by this AnyHolder object.
Any | NameValuePair.value The value to be associated with a name by this NameValuePair object.

Methods in org.omg.CORBA that return Any
abstract Any | Request.add_in_arg() Creates an input argument and adds it to this Request object.
abstract Any | Request.add_inout_arg() Adds an input/output argument to this Request object.
abstract Any | Request.add_named_in_arg(String name) Creates an input argument with the given name and adds it to this Request object.
abstract Any | Request.add_named_inout_arg(String name) Adds an input/output argument with the given name to this Request object.
abstract Any | Request.add_named_out_arg(String name) Adds an output argument with the given name to this Request object.
abstract Any | Request.add_out_arg() Adds an output argument to this Request object.
abstract Any | ORB.create_any() Creates an IDL Any object initialized to contain a Typecode object whose kind field is set to TCKind.tc_null.
abstract Any | Any.extract_any() Extracts the Any object in this Any object's value field.
static Any[] | AnySeqHelper.extract(Any a)
Any | DynAny.get_any() Deprecated. Retrieves the org.omg.CORBA.Any contained in this DynAny object.
Any[] | DynArray.get_elements() Deprecated. Returns the value of all the elements of this array.
Any[] | DynSequence.get_elements() Deprecated. Returns the value of every element in this sequence.
abstract Any | TypeCode.member_label(int index) Retrieves the label of the union member identified by the given index.
Any | DataInputStream.read_any() Reads an IDL Any value from the input stream.
static Any[] | AnySeqHelper.read(InputStream istream)
abstract Any | Request.return_value() Returns the Any object that contains the value for the result of the method.
Any | DynAny.to_any() Deprecated. Convert a DynAny object to an Any object.
abstract Any | NamedValue.value() Retrieves the value for this NamedValue object.

Methods in org.omg.CORBA with parameters of type Any
abstract  NamedValue NVList.add_value(String item_name, Any val, int flags)
Creates a new NamedValue object initialized with the given name, value, and flag, and adds it to the end of this NVList object.
 DynAny ORB.create_dyn_any(Any value)
Deprecated. Use the new DynAnyFactory API instead
abstract  NamedValue ORB.create_named_value(String s, Any any, int flags)
Creates a NamedValue object using the given name, value, and argument mode flags.
 Policy ORB.create_policy(int type, Any val)
Can be invoked to create new instances of policy objects of a specific type with specified initial state.
abstract  boolean Any.equal(Any a)
Checks for equality between this Any object and the given Any object.
 void ServerRequest.except(Any any)
Deprecated. use set_exception()
static String[] WStringSeqHelper.extract(Any a)
static UnknownUserException UnknownUserExceptionHelper.extract(Any a)
static String[] StringSeqHelper.extract(Any a)
static PolicyError PolicyErrorHelper.extract(Any a)
static short PolicyErrorCodeHelper.extract(Any a)
static ParameterMode ParameterModeHelper.extract(Any a)
static String WStringValueHelper.extract(Any a)
static char[] WCharSeqHelper.extract(Any a)
static short VisibilityHelper.extract(Any a)
static String VersionSpecHelper.extract(Any a)
static ValueMember ValueMemberHelper.extract(Any a)
static Serializable ValueBaseHelper.extract(Any a)
static UnionMember UnionMemberHelper.extract(Any a)
static short[] UShortSeqHelper.extract(Any a)
static int[] ULongSeqHelper.extract(Any a)
static long[] ULongLongSeqHelper.extract(Any a)
static StructMember StructMemberHelper.extract(Any a)
static String StringValueHelper.extract(Any a)
static short[] ShortSeqHelper.extract(Any a)
static SetOverrideType SetOverrideTypeHelper.extract(Any a)
static String RepositoryIdHelper.extract(Any a)
static Policy[] PolicyListHelper.extract(Any a)
static int PolicyTypeHelper.extract(Any a)
static Policy PolicyHelper.extract(Any a)
static byte[] OctetSeqHelper.extract(Any a)
static NameValuePair NameValuePairHelper.extract(Any a)
static int[] LongSeqHelper.extract(Any a)
static long[] LongLongSeqHelper.extract(Any a)
static String IdentifierHelper.extract(Any a)
static IDLType IDLTypeHelper.extract(Any a)
static float[] FloatSeqHelper.extract(Any a)
static String FieldNameHelper.extract(Any a)
static double[] DoubleSeqHelper.extract(Any a)
static DefinitionKind DefinitionKindHelper.extract(Any a)
static Current CurrentHelper.extract(Any a)
static CompletionStatus CompletionStatusHelper.extract(Any a)
static char[] CharSeqHelper.extract(Any a)
static boolean[] BooleanSeqHelper.extract(Any a)
static Any[] AnySeqHelper.extract(Any a)
static Object ObjectHelper.extract(Any a)
static ServiceDetail ServiceDetailHelper.extract(Any a)
static ServiceInformation ServiceInformationHelper.extract(Any a)
static WrongTransaction WrongTransactionHelper.extract(Any a)
 void DynAny.from_any(Any value)
Deprecated. Make a DynAny object from an Any object.
 void DynAny.insert_any(Any value)
Deprecated. Inserts the given org.omg.CORBA.Any object as the value for this DynAny object.
abstract  void Any.insert_any(Any a)
Inserts the given Any object into this Any object's value field.
static void AnySeqHelper.insert(Any a, Any[] that)
static void AnySeqHelper.insert(Any a, Any[] that)
static void BooleanSeqHelper.insert(Any a, boolean[] that)
static void OctetSeqHelper.insert(Any a, byte[] that)
static void WCharSeqHelper.insert(Any a, char[] that)
static void CharSeqHelper.insert(Any a, char[] that)
static void CompletionStatusHelper.insert(Any a, CompletionStatus that)
static void CurrentHelper.insert(Any a, Current that)
static void DefinitionKindHelper.insert(Any a, DefinitionKind that)
static void DoubleSeqHelper.insert(Any a, double[] that)
static void FloatSeqHelper.insert(Any a, float[] that)
static void IDLTypeHelper.insert(Any a, IDLType that)
static void PolicyTypeHelper.insert(Any a, int that)
static void ULongSeqHelper.insert(Any a, int[] that)
static void LongSeqHelper.insert(Any a, int[] that)
static void ULongLongSeqHelper.insert(Any a, long[] that)
static void LongLongSeqHelper.insert(Any a, long[] that)
static void NameValuePairHelper.insert(Any a, NameValuePair that)
static void ObjectHelper.insert(Any a, Object that)
static void ParameterModeHelper.insert(Any a, ParameterMode that)
static void PolicyHelper.insert(Any a, Policy that)
static void PolicyListHelper.insert(Any a, Policy[] that)
static void PolicyErrorHelper.insert(Any a, PolicyError that)
static void ValueBaseHelper.insert(Any a, Serializable that)
static void ServiceDetailHelper.insert(Any a, ServiceDetail that)
static void ServiceInformationHelper.insert(Any a, ServiceInformation that)
static void SetOverrideTypeHelper.insert(Any a, SetOverrideType that)
static void PolicyErrorCodeHelper.insert(Any a, short that)
static void VisibilityHelper.insert(Any a, short that)
static void UShortSeqHelper.insert(Any a, short[] that)
static void ShortSeqHelper.insert(Any a, short[] that)
static void WStringValueHelper.insert(Any a, String that)
static void VersionSpecHelper.insert(Any a, String that)
static void StringValueHelper.insert(Any a, String that)
static void RepositoryIdHelper.insert(Any a, String that)
static void IdentifierHelper.insert(Any a, String that)
static void FieldNameHelper.insert(Any a, String that)
static void WStringSeqHelper.insert(Any a, String[] that)
static void StringSeqHelper.insert(Any a, String[] that)
static void StructMemberHelper.insert(Any a, StructMember that)
static void UnionMemberHelper.insert(Any a, UnionMember that)
static void UnknownUserExceptionHelper.insert(Any a, UnknownUserException that)
static void ValueMemberHelper.insert(Any a, ValueMember that)
static void WrongTransactionHelper.insert(Any a, WrongTransaction that)
 void ServerRequest.result(Any any)
Deprecated. use the method set_result
 void DynArray.set_elements(Any[] value)
Deprecated. Sets the value of this DynArray object to the given array.
 void DynSequence.set_elements(Any[] value)
Deprecated. Sets the values of all elements in this sequence with the given array.
 void ServerRequest.set_exception(Any any)
Throws an org.omg.CORBA.NO_IMPLEMENT exception.
abstract  void Context.set_one_value(String propname, Any propvalue)
Creates a NamedValue object and adds it to this Context object.
 void ServerRequest.set_result(Any any)
Throws an org.omg.CORBA.NO_IMPLEMENT exception.
 void DataOutputStream.write_any_array(Any[] seq, int offset, int length)
Writes the array of IDL Anys from offset for length elements to the output stream.
 void DataOutputStream.write_any(Any value)
Writes the Any value to the output stream.
static void AnySeqHelper.write(OutputStream ostream, Any[] value)

Constructors in org.omg.CORBA with parameters of type Any
AnyHolder(Any initial)
Constructs a new AnyHolder object for the given Any object.
AnySeqHolder(Any[] initialValue)
NameValuePair(String __id, Any __value)
Constructs a NameValuePair object that associates the given name with the given org.omg.CORBA.Any object.
UnionMember(String __name, Any __label, TypeCode __type, IDLType __type_def)
Constructs a new UnionMember object with its fields initialized to the given values.
UnknownUserException(Any a)
Constructs an UnknownUserException object that contains the given Any object.

Uses of Any in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable that return Any
abstract  Any InputStream.read_any()
Reads an Any from this input stream.

Methods in org.omg.CORBA.portable with parameters of type Any
abstract  void OutputStream.write_any(Any value)
Writes an Any on this output stream.

Uses of Any in org.omg.CosNaming

Methods in org.omg.CosNaming with parameters of type Any
static NamingContextExt | NamingContextExtHelper.extract(Any a)
static NamingContext | NamingContextHelper.extract(Any a)
static NameComponent[] | NameHelper.extract(Any a)
static NameComponent | NameComponentHelper.extract(Any a)
static BindingType | BindingTypeHelper.extract(Any a)
static Binding[] | BindingListHelper.extract(Any a)
static BindingIterator | BindingIteratorHelper.extract(Any a)
static Binding | BindingHelper.extract(Any a)
static String | IstringHelper.extract(Any a)
static void | BindingHelper.insert(Any a, Binding that)
static void | BindingListHelper.insert(Any a, Binding[] that)
static void | BindingIteratorHelper.insert(Any a, BindingIterator that)
static void | BindingTypeHelper.insert(Any a, BindingType that)
static void | NameComponentHelper.insert(Any a, NameComponent that)
static void | NameHelper.insert(Any a, NameComponent[] that)
static void | NamingContextHelper.insert(Any a, NamingContext that)
static void | NamingContextExtHelper.insert(Any a, NamingContextExt that)
static void | IstringHelper.insert(Any a, String that)

Uses of Any in org.omg.CosNaming.NamingContextExtPackage

Methods in org.omg.CosNaming.NamingContextExtPackage with parameters of type Any
static String | URLStringHelper.extract(Any a)
static String | StringNameHelper.extract(Any a)
static InvalidAddress | InvalidAddressHelper.extract(Any a)
static String | AddressHelper.extract(Any a)
static void | InvalidAddressHelper.insert(Any a, InvalidAddress that)
static void | URLStringHelper.insert(Any a, String that)
static void | StringNameHelper.insert(Any a, String that)
static void | AddressHelper.insert(Any a, String that)

Uses of Any in org.omg.CosNaming.NamingContextPackage

Methods in org.omg.CosNaming.NamingContextPackage with parameters of type Any
static NotFoundReason | NotFoundReasonHelper.extract(Any a)
static NotFound | NotFoundHelper.extract(Any a)
static NotEmpty | NotEmptyHelper.extract(Any a)
static InvalidName | InvalidNameHelper.extract(Any a)
static CannotProceed | CannotProceedHelper.extract(Any a)
static AlreadyBound | AlreadyBoundHelper.extract(Any a)
static void | AlreadyBoundHelper.insert(Any a, AlreadyBound that)
static void | CannotProceedHelper.insert(Any a, CannotProceed that)
static void | InvalidNameHelper.insert(Any a, InvalidName that)
static void | NotEmptyHelper.insert(Any a, NotEmpty that)
static void | NotFoundHelper.insert(Any a, NotFound that)
static void | NotFoundReasonHelper.insert(Any a, NotFoundReason that)

Uses of Any in org.omg.Dynamic

Fields in org.omg.Dynamic declared as Any
 Any Parameter.argument

Constructors in org.omg.Dynamic with parameters of type Any
Parameter(Any _argument, ParameterMode _mode)

Uses of Any in org.omg.DynamicAny

Fields in org.omg.DynamicAny declared as Any
 Any NameValuePair.value
The Any value associated with the name.

Methods in org.omg.DynamicAny that return Any
static Any[] | AnySeqHelper.extract(Any a)
Any | _DynSequenceStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynFixedStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynEnumStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynArrayStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynValueStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynAnyStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynUnionStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynStructStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | DynAnyOperations.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | DynValueBoxOperations.get_boxed_value() Returns the boxed value as an Any.
Any[] | _DynSequenceStub.get_elements() Returns the elements of the sequence.
Any[] | _DynArrayStub.get_elements() Returns the elements of the DynArray.
Any[] | DynSequenceOperations.get_elements() Returns the elements of the sequence.
Any[] | DynArrayOperations.get_elements() Returns the elements of the DynArray.
static Any[] | AnySeqHelper.read(InputStream istream)
Any | _DynSequenceStub.to_any() Creates an any value from a DynAny object.
Any | _DynFixedStub.to_any() Creates an any value from a DynAny object.
Any | _DynEnumStub.to_any() Creates an any value from a DynAny object.
Any | _DynArrayStub.to_any() Creates an any value from a DynAny object.
Any | _DynValueStub.to_any() Creates an any value from a DynAny object.
Any | _DynAnyStub.to_any() Creates an any value from a DynAny object.
Any | _DynUnionStub.to_any() Creates an any value from a DynAny object.
Any | _DynStructStub.to_any() Creates an any value from a DynAny object.
Any | DynAnyOperations.to_any() Creates an any value from a DynAny object.

Methods in org.omg.DynamicAny with parameters of type Any
DynAny | _DynAnyFactoryStub.create_dyn_any(Any value) Creates a new DynAny object from an any value.
DynAny | DynAnyFactoryOperations.create_dyn_any(Any value) Creates a new DynAny object from an any value.
static NameValuePair[] | NameValuePairSeqHelper.extract(Any a)
static NameValuePair | NameValuePairHelper.extract(Any a)
static NameDynAnyPair[] | NameDynAnyPairSeqHelper.extract(Any a)
static DynSequence | DynSequenceHelper.extract(Any a)
static NameDynAnyPair | NameDynAnyPairHelper.extract(Any a)
static String | FieldNameHelper.extract(Any a)
static DynFixed | DynFixedHelper.extract(Any a)
static DynEnum | DynEnumHelper.extract(Any a)
static DynAny[] | DynAnySeqHelper.extract(Any a)
static DynArray | DynArrayHelper.extract(Any a)
static DynValue | DynValueHelper.extract(Any a)
static DynAny | DynAnyHelper.extract(Any a)
static DynUnion | DynUnionHelper.extract(Any a)
static DynAnyFactory | DynAnyFactoryHelper.extract(Any a)
static DynStruct | DynStructHelper.extract(Any a)
static Any[] | AnySeqHelper.extract(Any a)
void | _DynSequenceStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynFixedStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynEnumStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynArrayStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynValueStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynAnyStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynUnionStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynStructStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | DynAnyOperations.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynSequenceStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynFixedStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynEnumStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynArrayStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynValueStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynAnyStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynUnionStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynStructStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | DynAnyOperations.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
static void | AnySeqHelper.insert(Any a, Any[] that)
static void | AnySeqHelper.insert(Any a, Any[] that)
static void | DynAnyHelper.insert(Any a, DynAny that)
static void | DynAnySeqHelper.insert(Any a, DynAny[] that)
static void | DynAnyFactoryHelper.insert(Any a, DynAnyFactory that)
static void | DynArrayHelper.insert(Any a, DynArray that)
static void | DynEnumHelper.insert(Any a, DynEnum that)
static void | DynFixedHelper.insert(Any a, DynFixed that)
static void | DynSequenceHelper.insert(Any a, DynSequence that)
static void | DynStructHelper.insert(Any a, DynStruct that)
static void | DynUnionHelper.insert(Any a, DynUnion that)
static void | DynValueHelper.insert(Any a, DynValue that)
static void | NameDynAnyPairHelper.insert(Any a, NameDynAnyPair that)
static void | NameDynAnyPairSeqHelper.insert(Any a, NameDynAnyPair[] that)
static void | NameValuePairHelper.insert(Any a, NameValuePair that)
static void | NameValuePairSeqHelper.insert(Any a, NameValuePair[] that)
static void | FieldNameHelper.insert(Any a, String that)
void | DynValueBoxOperations.set_boxed_value(Any boxed) Replaces the boxed value with the specified value.
void | _DynSequenceStub.set_elements(Any[] value) Sets the elements of a sequence.
void | _DynArrayStub.set_elements(Any[] value) Sets the DynArray to contain the passed elements.
void | DynSequenceOperations.set_elements(Any[] value) Sets the elements of a sequence.
void | DynArrayOperations.set_elements(Any[] value) Sets the DynArray to contain the passed elements.
static void | AnySeqHelper.write(OutputStream ostream, Any[] value)

Constructors in org.omg.DynamicAny with parameters of type Any
NameValuePair(String _id, Any _value)

Uses of Any in org.omg.DynamicAny.DynAnyFactoryPackage

Methods in org.omg.DynamicAny.DynAnyFactoryPackage with parameters of type Any
static InconsistentTypeCode | InconsistentTypeCodeHelper.extract(Any a)
static void | InconsistentTypeCodeHelper.insert(Any a, InconsistentTypeCode that)

Uses of Any in org.omg.DynamicAny.DynAnyPackage

Methods in org.omg.DynamicAny.DynAnyPackage with parameters of type Any
static TypeMismatch | TypeMismatchHelper.extract(Any a)
static InvalidValue | InvalidValueHelper.extract(Any a)
static void | InvalidValueHelper.insert(Any a, InvalidValue that)
static void | TypeMismatchHelper.insert(Any a, TypeMismatch that)

Uses of Any in org.omg.IOP

Methods in org.omg.IOP that return Any
Any | CodecOperations.decode_value(byte[] data, TypeCode tc) Decodes the given byte array into an Any based on the given TypeCode and the encoding format effective for this Codec.
Any | CodecOperations.decode(byte[] data) Decodes the given byte array into an Any based on the encoding format effective for this Codec.

Methods in org.omg.IOP with parameters of type Any
byte[] | CodecOperations.encode_value(Any data) Converts the given any into a byte array based on the encoding format effective for this Codec.
byte[] | CodecOperations.encode(Any data) Converts the given any into a byte array based on the encoding format effective for this Codec.
static TaggedProfile | TaggedProfileHelper.extract(Any a)
static TaggedComponent | TaggedComponentHelper.extract(Any a)
static int | ServiceIdHelper.extract(Any a)
static ServiceContext[] | ServiceContextListHelper.extract(Any a)
static ServiceContext | ServiceContextHelper.extract(Any a)
static int | ProfileIdHelper.extract(Any a)
static TaggedComponent[] | MultipleComponentProfileHelper.extract(Any a)
static IOR | IORHelper.extract(Any a)
static int | ComponentIdHelper.extract(Any a)
static CodecFactory | CodecFactoryHelper.extract(Any a)
static void | CodecFactoryHelper.insert(Any a, CodecFactory that)
static void | ServiceIdHelper.insert(Any a, int that)
static void | ProfileIdHelper.insert(Any a, int that)
static void | ComponentIdHelper.insert(Any a, int that)
static void | IORHelper.insert(Any a, IOR that)
static void | ServiceContextHelper.insert(Any a, ServiceContext that)
static void | ServiceContextListHelper.insert(Any a, ServiceContext[] that)
static void | TaggedComponentHelper.insert(Any a, TaggedComponent that)
static void | MultipleComponentProfileHelper.insert(Any a, TaggedComponent[] that)
static void | TaggedProfileHelper.insert(Any a, TaggedProfile that)

Uses of Any in org.omg.IOP.CodecFactoryPackage

Methods in org.omg.IOP.CodecFactoryPackage with parameters of type Any
static UnknownEncoding | UnknownEncodingHelper.extract(Any a)
static void | UnknownEncodingHelper.insert(Any a, UnknownEncoding that)

Uses of Any in org.omg.IOP.CodecPackage

Methods in org.omg.IOP.CodecPackage with parameters of type Any
static TypeMismatch | TypeMismatchHelper.extract(Any a)
static InvalidTypeForEncoding | InvalidTypeForEncodingHelper.extract(Any a)
static FormatMismatch | FormatMismatchHelper.extract(Any a)
static void | FormatMismatchHelper.insert(Any a, FormatMismatch that)
static void | InvalidTypeForEncodingHelper.insert(Any a, InvalidTypeForEncoding that)
static void | TypeMismatchHelper.insert(Any a, TypeMismatch that)

Uses of Any in org.omg.Messaging

Methods in org.omg.Messaging with parameters of type Any
static short | SyncScopeHelper.extract(Any a)
static void | SyncScopeHelper.insert(Any a, short that)

Uses of Any in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor that return Any
Any | CurrentOperations.get_slot(int id) Retrieves the slot data the application set in PICurrent via get_slot.
Any | RequestInfoOperations.get_slot(int id) Returns the data from the given slot of the PortableInterceptor.Current that is in the scope of the request.
Any | ClientRequestInfoOperations.received_exception() Returns an any which contains the exception to be returned to the client.
Any | RequestInfoOperations.result() Returns an any containing the result of the operation invocation.
Any | ServerRequestInfoOperations.sending_exception() Returns an any which contains the exception to be returned to the client.

Methods in org.omg.PortableInterceptor with parameters of type Any
Policy | PolicyFactoryOperations.create_policy(int type, Any value) Returns an instance of the appropriate interface derived from CORBA.Policy whose value corresponds to the specified any.
static String | ServerIdHelper.extract(Any a)
static String | ORBIdHelper.extract(Any a)
static ObjectReferenceTemplate[] | ObjectReferenceTemplateSeqHelper.extract(Any a)
static ObjectReferenceTemplate | ObjectReferenceTemplateHelper.extract(Any a)
static ObjectReferenceFactory | ObjectReferenceFactoryHelper.extract(Any a)
static byte[] | ObjectIdHelper.extract(Any a)
static InvalidSlot | InvalidSlotHelper.extract(Any a)
static IORInterceptor_3_0 | IORInterceptor_3_0Helper.extract(Any a)
static ForwardRequest | ForwardRequestHelper.extract(Any a)
static Current | CurrentHelper.extract(Any a)
static short | AdapterStateHelper.extract(Any a)
static String[] | AdapterNameHelper.extract(Any a)
static int | AdapterManagerIdHelper.extract(Any a)
static void | ObjectIdHelper.insert(Any a, byte[] that)
static void | CurrentHelper.insert(Any a, Current that)
static void | ForwardRequestHelper.insert(Any a, ForwardRequest that)
static void | AdapterManagerIdHelper.insert(Any a, int that)
static void | InvalidSlotHelper.insert(Any a, InvalidSlot that)
static void | IORInterceptor_3_0Helper.insert(Any a, IORInterceptor_3_0 that)
static void | ObjectReferenceFactoryHelper.insert(Any a, ObjectReferenceFactory that)
static void | ObjectReferenceTemplateHelper.insert(Any a, ObjectReferenceTemplate that)
static void | ObjectReferenceTemplateSeqHelper.insert(Any a, ObjectReferenceTemplate[] that)
static void | AdapterStateHelper.insert(Any a, short that)
static void | ServerIdHelper.insert(Any a, String that)
static void | ORBIdHelper.insert(Any a, String that)
static void | AdapterNameHelper.insert(Any a, String[] that)
void | ServerRequestInfoOperations.set_slot(int id, Any data) Allows an Interceptor to set a slot in the PortableInterceptor.Current that is in the scope of the request.
void | CurrentOperations.set_slot(int id, Any data) Sets data in a slot.

Uses of Any in org.omg.PortableInterceptor.ORBInitInfoPackage

Methods in org.omg.PortableInterceptor.ORBInitInfoPackage with parameters of type Any
static String | ObjectIdHelper.extract(Any a)
static InvalidName | InvalidNameHelper.extract(Any a)
static DuplicateName | DuplicateNameHelper.extract(Any a)
static void | DuplicateNameHelper.insert(Any a, DuplicateName that)
static void | InvalidNameHelper.insert(Any a, InvalidName that)
static void | ObjectIdHelper.insert(Any a, String that)

Uses of Any in org.omg.PortableServer

Methods in org.omg.PortableServer with parameters of type Any
static ServantLocator | ServantLocatorHelper.extract(Any a)
static ServantActivator | ServantActivatorHelper.extract(Any a)
static POA | POAHelper.extract(Any a)
static ForwardRequest | ForwardRequestHelper.extract(Any a)
static Current | CurrentHelper.extract(Any a)
static void | CurrentHelper.insert(Any a, Current that)
static void | ForwardRequestHelper.insert(Any a, ForwardRequest that)
static void | POAHelper.insert(Any a, POA that)
static void | ServantActivatorHelper.insert(Any a, ServantActivator that)
static void | ServantLocatorHelper.insert(Any a, ServantLocator that)

Uses of Any in org.omg.PortableServer.CurrentPackage

Methods in org.omg.PortableServer.CurrentPackage with parameters of type Any
static NoContext | NoContextHelper.extract(Any a)
static void | NoContextHelper.insert(Any a, NoContext that)

Uses of Any in org.omg.PortableServer.POAManagerPackage

Methods in org.omg.PortableServer.POAManagerPackage with parameters of type Any
static AdapterInactive | AdapterInactiveHelper.extract(Any a)
static void | AdapterInactiveHelper.insert(Any a, AdapterInactive that)

Uses of Any in org.omg.PortableServer.POAPackage

Methods in org.omg.PortableServer.POAPackage with parameters of type Any
static WrongPolicy | WrongPolicyHelper.extract(Any a)
static WrongAdapter | WrongAdapterHelper.extract(Any a)
static ServantNotActive | ServantNotActiveHelper.extract(Any a)
static ServantAlreadyActive | ServantAlreadyActiveHelper.extract(Any a)
static ObjectNotActive | ObjectNotActiveHelper.extract(Any a)
static ObjectAlreadyActive | ObjectAlreadyActiveHelper.extract(Any a)
static NoServant | NoServantHelper.extract(Any a)
static InvalidPolicy | InvalidPolicyHelper.extract(Any a)
static AdapterNonExistent | AdapterNonExistentHelper.extract(Any a)
static AdapterAlreadyExists | AdapterAlreadyExistsHelper.extract(Any a)
static void | AdapterAlreadyExistsHelper.insert(Any a, AdapterAlreadyExists that)
static void | AdapterNonExistentHelper.insert(Any a, AdapterNonExistent that)
static void | InvalidPolicyHelper.insert(Any a, InvalidPolicy that)
static void | NoServantHelper.insert(Any a, NoServant that)
static void | ObjectAlreadyActiveHelper.insert(Any a, ObjectAlreadyActive that)
static void | ObjectNotActiveHelper.insert(Any a, ObjectNotActive that)
static void | ServantAlreadyActiveHelper.insert(Any a, ServantAlreadyActive that)
static void | ServantNotActiveHelper.insert(Any a, ServantNotActive that)
static void | WrongAdapterHelper.insert(Any a, WrongAdapter that)
static void | WrongPolicyHelper.insert(Any a, WrongPolicy that)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.AnyHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.AnyHolder

No usage of org.omg.CORBA.AnyHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.AnySeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.AnySeqHelper

No usage of org.omg.CORBA.AnySeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.AnySeqHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.AnySeqHolder

Packages that use AnySeqHolder
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of AnySeqHolder in org.omg.CORBA

Methods in org.omg.CORBA with parameters of type AnySeqHolder
 void DataInputStream.read_any_array(AnySeqHolder seq, int offset, int length)
Reads array of IDL Anys from offset for length elements from the input stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.BAD_CONTEXT

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.BAD_CONTEXT

No usage of org.omg.CORBA.BAD_CONTEXT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.BAD_INV_ORDER

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.BAD_INV_ORDER

Packages that use BAD_INV_ORDER
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of BAD_INV_ORDER in org.omg.CORBA

Methods in org.omg.CORBA that throw BAD_INV_ORDER
Streamable | Any.extract_Streamable() Extracts a Streamable from this Any object's value field.
void | Any.insert_fixed(BigDecimal value, TypeCode type) Throws an org.omg.CORBA.NO_IMPLEMENT exception.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.BAD_OPERATION

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.BAD_OPERATION

Packages that use BAD_OPERATION
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of BAD_OPERATION in org.omg.CORBA

Methods in org.omg.CORBA that throw BAD_OPERATION
abstract Any | Any.extract_any() Extracts the Any object in this Any object's value field.
abstract boolean | Any.extract_boolean() Extracts the boolean in this Any object's value field.
abstract char | Any.extract_char() Extracts the char in this Any object's value field.
abstract double | Any.extract_double() Extracts the double in this Any object's value field.
abstract float | Any.extract_float() Extracts the float in this Any object's value field.
abstract int | Any.extract_long() Extracts the int in this Any object's value field.
abstract long | Any.extract_longlong() Extracts the long in this Any object's value field.
abstract Object | Any.extract_Object() Extracts the org.omg.CORBA.Object in this Any object's value field.
abstract byte | Any.extract_octet() Extracts the byte in this Any object's value field.
Principal | Any.extract_Principal() Deprecated. Deprecated by CORBA 2.2.
abstract short | Any.extract_short() Extracts the short in this Any object's value field.
abstract String | Any.extract_string() Extracts the String object in this Any object's value field.
abstract TypeCode | Any.extract_TypeCode() Extracts the TypeCode object in this Any object's value field.
abstract int | Any.extract_ulong() Extracts the int in this Any object's value field.
abstract long | Any.extract_ulonglong() Extracts the long in this Any object's value field.
abstract short | Any.extract_ushort() Extracts the short in this Any object's value field.
abstract Serializable | Any.extract_Value() Extracts the java.io.Serializable object in this Any object's value field.
abstract char | Any.extract_wchar() Extracts the char in this Any object's value field.
abstract String | Any.extract_wstring() Extracts the String object in this Any object's value field.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.BAD_PARAM

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.BAD_PARAM

Packages that use BAD_PARAM
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA_2_3 | The CORBA_2_3 package defines additions to existing CORBA interfaces in the Java[tm] Standard Edition 6. These changes occurred in recent revisions to the CORBA API defined by the OMG. The new methods were added to interfaces derived from the corresponding interfaces in the CORBA package. This provides backward compatibility and avoids breaking the JCK tests.

Uses of BAD_PARAM in org.omg.CORBA

Methods in org.omg.CORBA that throw BAD_PARAM
abstract  void Any.insert_Object(Object o, TypeCode t)
Inserts the given org.omg.CORBA.Object object into this Any object's value field.

Uses of BAD_PARAM in org.omg.CORBA_2_3

Methods in org.omg.CORBA_2_3 that throw BAD_PARAM
 Object ORB.get_value_def(String repid)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.BAD_QOS

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.BAD_QOS

No usage of org.omg.CORBA.BAD_QOS

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.BAD_TYPECODE

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.BAD_TYPECODE

No usage of org.omg.CORBA.BAD_TYPECODE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.BooleanHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.BooleanHolder

No usage of org.omg.CORBA.BooleanHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.BooleanSeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.BooleanSeqHelper

No usage of org.omg.CORBA.BooleanSeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.BooleanSeqHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.BooleanSeqHolder

Packages that use BooleanSeqHolder
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of BooleanSeqHolder in org.omg.CORBA

Methods in org.omg.CORBA with parameters of type BooleanSeqHolder
 void DataInputStream.read_boolean_array(BooleanSeqHolder seq, int offset, int length)
Reads array of IDL booleans from offset for length elements from the input stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.Bounds

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.Bounds

Packages that use Bounds
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of Bounds in org.omg.CORBA

Methods in org.omg.CORBA that throw Bounds
abstract String | ContextList.item(int index) Returns the String object at the given index.
abstract TypeCode | ExceptionList.item(int index) Returns the TypeCode object at the given index.
abstract NamedValue | NVList.item(int index) Retrieves the NamedValue object at the given index.
abstract void | ContextList.remove(int index) Removes the String object at the given index.
abstract void | ExceptionList.remove(int index) Removes the TypeCode object at the given index.
abstract void | NVList.remove(int index) Removes the NamedValue object at the given index.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ByteHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ByteHolder

No usage of org.omg.CORBA.ByteHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.CharHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.CharHolder

No usage of org.omg.CORBA.CharHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.CharSeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.CharSeqHelper

No usage of org.omg.CORBA.CharSeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.CharSeqHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.CharSeqHolder

Packages that use CharSeqHolder
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of CharSeqHolder in org.omg.CORBA

Methods in org.omg.CORBA with parameters of type CharSeqHolder
 void DataInputStream.read_char_array(CharSeqHolder seq, int offset, int length)
Reads array of IDL characters from offset for length elements from the input stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.CODESET_INCOMPATIBLE

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.CODESET_INCOMPATIBLE

No usage of org.omg.CORBA.CODESET_INCOMPATIBLE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.COMM_FAILURE

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.COMM_FAILURE

No usage of org.omg.CORBA.COMM_FAILURE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.CompletionStatus

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.CompletionStatus

Packages that use CompletionStatus
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of CompletionStatus in org.omg.CORBA

Fields in org.omg.CORBA declared as CompletionStatus
CompletionStatus | SystemException.completed The status of the operation that threw this exception.
static CompletionStatus | CompletionStatus.COMPLETED_MAYBE An instance of CompletionStatus initialized with the constant _COMPLETED_MAYBE.
static CompletionStatus | CompletionStatus.COMPLETED_NO An instance of CompletionStatus initialized with the constant _COMPLETED_NO.
static CompletionStatus | CompletionStatus.COMPLETED_YES An instance of CompletionStatus initialized with the constant _COMPLETED_YES.

Methods in org.omg.CORBA that return CompletionStatus
static CompletionStatus | CompletionStatusHelper.extract(Any a)
static CompletionStatus | CompletionStatus.from_int(int i) Creates a CompletionStatus object from the given int.
static CompletionStatus | CompletionStatusHelper.read(InputStream istream)

Methods in org.omg.CORBA with parameters of type CompletionStatus
static void | CompletionStatusHelper.insert(Any a, CompletionStatus that)
static void | CompletionStatusHelper.write(OutputStream ostream, CompletionStatus value)

Constructors in org.omg.CORBA with parameters of type CompletionStatus
ACTIVITY_COMPLETED(int minorCode, CompletionStatus completionStatus)
Constructs an ACTIVITY_COMPLETED exception with the specified minor code and completion status.
ACTIVITY_COMPLETED(String detailMessage, int minorCode, CompletionStatus completionStatus)
Constructs an ACTIVITY_COMPLETED exception with the specified message, minor code, and completion status.
ACTIVITY_REQUIRED(int minorCode, CompletionStatus completionStatus)
Constructs an ACTIVITY_REQUIRED exception with the specified minor code and completion status.
ACTIVITY_REQUIRED(String detailMessage, int minorCode, CompletionStatus completionStatus)
Constructs an ACTIVITY_REQUIRED exception with the specified message, minor code, and completion status.
BAD_CONTEXT(int minor, CompletionStatus completed)
Constructs a BAD_CONTEXT exception with the specified minor code and completion status.
BAD_CONTEXT(String s, int minor, CompletionStatus completed)
Constructs a BAD_CONTEXT exception with the specified detail message, minor code, and completion status.
BAD_INV_ORDER(int minor, CompletionStatus completed)
Constructs a BAD_INV_ORDER exceptionBAD_INV_ORDER with the specified minor code and completion status.
BAD_INV_ORDER(String s, int minor, CompletionStatus completed)
Constructs a BAD_INV_ORDER exception with the specified detail message, minor code, and completion status.
BAD_OPERATION(int minor, CompletionStatus completed)
Constructs a BAD_OPERATION exception with the specified minor code and completion status.
BAD_OPERATION(String s, int minor, CompletionStatus completed)
Constructs a BAD_OPERATION exception with the specified detail message, minor code, and completion status.
BAD_PARAM(int minor, CompletionStatus completed)
Constructs a BAD_PARAM exception with the specified minor code and completion status.
BAD_PARAM(String s, int minor, CompletionStatus completed)
Constructs a BAD_PARAM exception with the specified detail message, minor code, and completion status.
BAD_QOS(int minorCode, CompletionStatus completionStatus)
Constructs an BAD_QOS exception with the specified minor code and completion status.
BAD_QOS(String detailMessage, int minorCode, CompletionStatus completionStatus)
Constructs an BAD_QOS exception with the specified message, minor code, and completion status.
BAD_TYPECODE(int minor, CompletionStatus completed)
Constructs a BAD_TYPECODE exception with the specified minor code and completion status.
BAD_TYPECODE(String s, int minor, CompletionStatus completed)
Constructs a BAD_TYPECODE exception with the specified detail message, minor code, and completion status.
CODESET_INCOMPATIBLE(int minorCode, CompletionStatus completionStatus)
Constructs an CODESET_INCOMPATIBLE exception with the specified minor code and completion status.
CODESET_INCOMPATIBLE(String detailMessage, int minorCode, CompletionStatus completionStatus)
Constructs an CODESET_INCOMPATIBLE exception with the specified message, minor code, and completion status.
COMM_FAILURE(int minor, CompletionStatus completed)
Constructs a COMM_FAILURE exception with the specified minor code and completion status.
COMM_FAILURE(String s, int minor, CompletionStatus completed)
Constructs a COMM_FAILURE exception with the specified detail message, minor code, and completion status.
DATA_CONVERSION(int minor, CompletionStatus completed)
Constructs a DATA_CONVERSION exception with the specified minor code and completion status.
DATA_CONVERSION(String s, int minor, CompletionStatus completed)
Constructs a DATA_CONVERSION exception with the specified detail message, minor code, and completion status.
FREE_MEM(int minor, CompletionStatus completed)
Constructs a FREE_MEM exception with the specified minor code and completion status.
FREE_MEM(String s, int minor, CompletionStatus completed)
Constructs a FREE_MEM exception with the specified detail message, minor code, and completion status.
IMP_LIMIT(int minor, CompletionStatus completed)
Constructs an IMP_LIMIT exception with the specified minor code and completion status.
IMP_LIMIT(String s, int minor, CompletionStatus completed)
Constructs an IMP_LIMIT exception with the specified detail message, minor code, and completion status.
INITIALIZE(int minor, CompletionStatus completed)
Constructs an INITIALIZE exception with the specified minor code and completion status.
INITIALIZE(String s, int minor, CompletionStatus completed)
Constructs an INITIALIZE exception with the specified detail message, minor code, and completion status.
INTERNAL(int minor, CompletionStatus completed)
Constructs an INTERNAL exception with the specified minor code and completion status.
INTERNAL(String s, int minor, CompletionStatus completed)
Constructs an INTERNAL exception with the specified detail message, minor code, and completion status.
INTF_REPOS(int minor, CompletionStatus completed)
Constructs an INTF_REPOS exception with the specified minor code and completion status.
INTF_REPOS(String s, int minor, CompletionStatus completed)
Constructs an INTF_REPOS exception with the specified detail message, minor code, and completion status.
INV_FLAG(int minor, CompletionStatus completed)
Constructs an INV_FLAG exception with the specified minor code and completion status.
INV_FLAG(String s, int minor, CompletionStatus completed)
Constructs an INV_FLAG exception with the specified detail message, minor code, and completion status.
INV_IDENT(int minor, CompletionStatus completed)
Constructs an INV_IDENT exception with the specified minor code and completion status.
INV_IDENT(String s, int minor, CompletionStatus completed)
Constructs an INV_IDENT exception with the specified detail message, minor code, and completion status.
INV_OBJREF(int minor, CompletionStatus completed)
Constructs an INV_OBJREF exception with the specified minor code and completion status.
INV_OBJREF(String s, int minor, CompletionStatus completed)
Constructs an INV_OBJREF exception with the specified detail message, minor code, and completion status.
INV_POLICY(int minor, CompletionStatus completed)
Constructs a INV_POLICY exception with the specified minor code and completion status.
INV_POLICY(String s, int minor, CompletionStatus completed)
Constructs a INV_POLICY exception with the specified description message, minor code, and completion status.
INVALID_ACTIVITY(int minorCode, CompletionStatus completionStatus)
Constructs an INVALID_ACTIVITY exception with the specified minor code and completion status.
INVALID_ACTIVITY(String detailMessage, int minorCode, CompletionStatus completionStatus)
Constructs an INVALID_ACTIVITY exception with the specified message, minor code, and completion status.
INVALID_TRANSACTION(int minor, CompletionStatus completed)
Constructs an INVALID_TRANSACTION exception with the specified minor code and completion status.
INVALID_TRANSACTION(String s, int minor, CompletionStatus completed)
Constructs an INVALID_TRANSACTION exception with the specified detail message, minor code, and completion status.
MARSHAL(int minor, CompletionStatus completed)
Constructs a MARSHAL exception with the specified minor code and completion status.
MARSHAL(String s, int minor, CompletionStatus completed)
Constructs a MARSHAL exception with the specified description message, minor code, and completion status.
NO_IMPLEMENT(int minor, CompletionStatus completed)
Constructs a NO_IMPLEMENT exception with the specified minor code and completion status.
NO_IMPLEMENT(String s, int minor, CompletionStatus completed)
Constructs a NO_IMPLEMENT exception with the specified description message, minor code, and completion status.
NO_MEMORY(int minor, CompletionStatus completed)
Constructs a NO_MEMORY exception with the specified minor code and completion status.
NO_MEMORY(String s, int minor, CompletionStatus completed)
Constructs a NO_MEMORY exception with the specified description message, minor code, and completion status.
NO_PERMISSION(int minor, CompletionStatus completed)
Constructs a NO_PERMISSION exception with the specified minor code and completion status.
NO_PERMISSION(String s, int minor, CompletionStatus completed)
Constructs a NO_PERMISSION exception with the specified description message, minor code, and completion status.
NO_RESOURCES(int minor, CompletionStatus completed)
Constructs a NO_RESOURCES exception with the specified minor code and completion status.
NO_RESOURCES(String s, int minor, CompletionStatus completed)
Constructs a NO_RESOURCES exception with the specified description message, minor code, and completion status.
NO_RESPONSE(int minor, CompletionStatus completed)
Constructs a NO_RESPONSE exception with the specified minor code and completion status.
NO_RESPONSE(String s, int minor, CompletionStatus completed)
Constructs a NO_RESPONSE exception with the specified description message, minor code, and completion status.
OBJ_ADAPTER(int minor, CompletionStatus completed)
Constructs an OBJ_ADAPTER exception with the specified minor code and completion status.
OBJ_ADAPTER(String s, int minor, CompletionStatus completed)
Constructs an OBJ_ADAPTER exception with the specified description message, minor code, and completion status.
OBJECT_NOT_EXIST(int minor, CompletionStatus completed)
Constructs an OBJECT_NOT_EXIST exception with the specified minor code and completion status.
OBJECT_NOT_EXIST(String s, int minor, CompletionStatus completed)
Constructs an OBJECT_NOT_EXIST exception with the specified description message, minor code, and completion status.
PERSIST_STORE(int minor, CompletionStatus completed)
Constructs a PERSIST_STORE exception with the specified minor code and completion status.
PERSIST_STORE(String s, int minor, CompletionStatus completed)
Constructs a PERSIST_STORE exception with the specified description message, minor code, and completion status.
REBIND(int minorCode, CompletionStatus completionStatus)
Constructs an REBIND exception with the specified minor code and completion status.
REBIND(String detailMessage, int minorCode, CompletionStatus completionStatus)
Constructs an REBIND exception with the specified message, minor code, and completion status.
SystemException(String reason, int minor, CompletionStatus completed)
Constructs a SystemException exception with the specified detail message, minor code, and completion status.
TIMEOUT(int minorCode, CompletionStatus completionStatus)
Constructs an TIMEOUT exception with the specified minor code and completion status.
TIMEOUT(String detailMessage, int minorCode, CompletionStatus completionStatus)
Constructs an TIMEOUT exception with the specified message, minor code, and completion status.
TRANSACTION_MODE(int minor, CompletionStatus completed)
Constructs a TRANSACTION_MODE exception with the specified minor code and completion status.
TRANSACTION_MODE(String s, int minor, CompletionStatus completed)
Constructs a TRANSACTION_MODE exception with the specified description message, minor code, and completion status.
TRANSACTION_REQUIRED(int minor, CompletionStatus completed)
Constructs a TRANSACTION_REQUIRED exception with the specified minor code and completion status.
TRANSACTION_REQUIRED(String s, int minor, CompletionStatus completed)
Constructs a TRANSACTION_REQUIRED exception with the specified description message, minor code, and completion status.
TRANSACTION_ROLLEDBACK(int minor, CompletionStatus completed)
Constructs a TRANSACTION_ROLLEDBACK exception with the specified minor code and completion status.
TRANSACTION_ROLLEDBACK(String s, int minor, CompletionStatus completed)
Constructs a TRANSACTION_ROLLEDBACK exception with the specified description message, minor code, and completion status.
TRANSACTION_UNAVAILABLE(int minor, CompletionStatus completed)
Constructs a TRANSACTION_UNAVAILABLE exception with the specified minor code and completion status.
TRANSACTION_UNAVAILABLE(String s, int minor, CompletionStatus completed)
Constructs a TRANSACTION_UNAVAILABLE exception with the specified description message, minor code, and completion status.
TRANSIENT(int minor, CompletionStatus completed)
Constructs a TRANSIENT exception with the specified minor code and completion status.
TRANSIENT(String s, int minor, CompletionStatus completed)
Constructs a TRANSIENT exception with the specified description message, minor code, and completion status.
UNKNOWN(int minor, CompletionStatus completed)
Constructs an UNKNOWN exception with the specified minor code and completion status.
UNKNOWN(String s, int minor, CompletionStatus completed)
Constructs an UNKNOWN exception with the specified description message, minor code, and completion status.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.CompletionStatusHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.CompletionStatusHelper

No usage of org.omg.CORBA.CompletionStatusHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.Context

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.Context

Packages that use Context
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.

Uses of Context in org.omg.CORBA

Methods in org.omg.CORBA that return Context
abstract Context | Context.create_child(String child_ctx_name) Creates a Context object with the given string as its name and with this Context object set as its parent.
abstract Context | ServerRequest.ctx() Returns the context information specified in IDL for the operation when the operation is not an attribute access and the operation's IDL definition contains a context expression; otherwise it returns a nil Context reference.
abstract Context | Request.ctx() Retrieves the Context object for this request.
abstract Context | ORB.get_default_context() Gets the default Context object.
abstract Context | Context.parent() Retrieves the parent of this Context object.

Methods in org.omg.CORBA with parameters of type Context
Request | LocalObject._create_request(Context ctx, String operation, NVList arg_list, NamedValue result) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
Request | Object._create_request(Context ctx, String operation, NVList arg_list, NamedValue result) Creates a Request instance initialized with the given context, method name, list of arguments, and container for the method's return value.
Request | LocalObject._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exceptions, ContextList contexts) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
Request | Object._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exclist, ContextList ctxlist) Creates a Request instance initialized with the given context, method name, list of arguments, container for the method's return value, list of possible exceptions, and list of context strings needing to be resolved.
abstract void | Request.ctx(Context c) Sets this request's Context object to the one given.

Uses of Context in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable that return Context
 Context InputStream.read_Context()
Reads a CORBA context from the stream.

Methods in org.omg.CORBA.portable with parameters of type Context
Request | ObjectImpl._create_request(Context ctx, String operation, NVList arg_list, NamedValue result) Creates a Request object that contains the given context, method, argument list, and container for the result.
Request | ObjectImpl._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exceptions, ContextList contexts) Creates a Request object that contains the given context, method, argument list, container for the result, exceptions, and list of property names to be used in resolving the context strings.
abstract Request | Delegate.create_request(Object obj, Context ctx, String operation, NVList arg_list, NamedValue result) Creates a Request instance for use in the Dynamic Invocation Interface.
abstract Request | Delegate.create_request(Object obj, Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exclist, ContextList ctxlist) Creates a Request instance for use in the Dynamic Invocation Interface.
void | OutputStream.write_Context(Context ctx, ContextList contexts) Writes a CORBA context on this stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ContextList

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ContextList

Packages that use ContextList
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.

Uses of ContextList in org.omg.CORBA

Methods in org.omg.CORBA that return ContextList
abstract ContextList | Request.contexts() Retrieves the ContextList object for this request.
abstract ContextList | ORB.create_context_list() Creates an empty ContextList object.

Methods in org.omg.CORBA with parameters of type ContextList
Request | LocalObject._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exceptions, ContextList contexts) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
Request | Object._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exclist, ContextList ctxlist) Creates a Request instance initialized with the given context, method name, list of arguments, container for the method's return value, list of possible exceptions, and list of context strings needing to be resolved.

Uses of ContextList in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable with parameters of type ContextList
Request | ObjectImpl._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exceptions, ContextList contexts) Creates a Request object that contains the given context, method, argument list, container for the result, exceptions, and list of property names to be used in resolving the context strings.
abstract Request | Delegate.create_request(Object obj, Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exclist, ContextList ctxlist) Creates a Request instance for use in the Dynamic Invocation Interface.
void | OutputStream.write_Context(Context ctx, ContextList contexts) Writes a CORBA context on this stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.CurrentHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.CurrentHelper

No usage of org.omg.CORBA.CurrentHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.CurrentHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.CurrentHolder

No usage of org.omg.CORBA.CurrentHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.DATA_CONVERSION

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.DATA_CONVERSION

Packages that use DATA_CONVERSION
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of DATA_CONVERSION in org.omg.CORBA

Methods in org.omg.CORBA that throw DATA_CONVERSION
abstract void | Any.insert_char(char c) Inserts the given char into this Any object's value field.
abstract void | Any.insert_string(String s) Inserts the given String object into this Any object's value field.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.DefinitionKind

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.DefinitionKind

Packages that use DefinitionKind
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of DefinitionKind in org.omg.CORBA

Fields in org.omg.CORBA declared as DefinitionKind
static DefinitionKind | DefinitionKind.dk_AbstractInterface The static instance of DefinitionKind indicating that an Interface Repository object represents an abstract interface.
static DefinitionKind | DefinitionKind.dk_Alias The static instance of DefinitionKind indicating that an Interface Repository object is an Alias.
static DefinitionKind | DefinitionKind.dk_all The wildcard DefinitionKind constant, useful in all occasions where any DefinitionKind is appropriate.
static DefinitionKind | DefinitionKind.dk_Array The static instance of DefinitionKind indicating that an Interface Repository object is an Array.
static DefinitionKind | DefinitionKind.dk_Attribute The static instance of DefinitionKind indicating that an Interface Repository object is an Attribute.
static DefinitionKind | DefinitionKind.dk_Constant The static instance of DefinitionKind indicating that an Interface Repository object is a constant.
static DefinitionKind | DefinitionKind.dk_Enum The static instance of DefinitionKind indicating that an Interface Repository object is an Enum.
static DefinitionKind | DefinitionKind.dk_Exception The static instance of DefinitionKind indicating that an Interface Repository object is an Exception.
static DefinitionKind | DefinitionKind.dk_Fixed The static instance of DefinitionKind indicating that an Interface Repository object is a Fixed value.
static DefinitionKind | DefinitionKind.dk_Interface The static instance of DefinitionKind indicating that an Interface Repository object is an Interface.
static DefinitionKind | DefinitionKind.dk_Module The static instance of DefinitionKind indicating that an Interface Repository object is a Module.
static DefinitionKind | DefinitionKind.dk_Native The static instance of DefinitionKind indicating that an Interface Repository object is a Native value.
static DefinitionKind | DefinitionKind.dk_none The static instance of DefinitionKind indicating that an Interface Repository object has no definition kind.
static DefinitionKind | DefinitionKind.dk_Operation The static instance of DefinitionKind indicating that an Interface Repository object is an Operation.
static DefinitionKind | DefinitionKind.dk_Primitive The static instance of DefinitionKind indicating that an Interface Repository object is a Primitive.
static DefinitionKind | DefinitionKind.dk_Repository The static instance of DefinitionKind indicating that an Interface Repository object is a Repository.
static DefinitionKind | DefinitionKind.dk_Sequence The static instance of DefinitionKind indicating that an Interface Repository object is a Sequence.
static DefinitionKind | DefinitionKind.dk_String The static instance of DefinitionKind indicating that an Interface Repository object is a String.
static DefinitionKind | DefinitionKind.dk_Struct The static instance of DefinitionKind indicating that an Interface Repository object is a Struct.
static DefinitionKind | DefinitionKind.dk_Typedef The static instance of DefinitionKind indicating that an Interface Repository object is a Typedef.
static DefinitionKind | DefinitionKind.dk_Union The static instance of DefinitionKind indicating that an Interface Repository object is a Union.
static DefinitionKind | DefinitionKind.dk_Value The static instance of DefinitionKind indicating that an Interface Repository object is a Value.
static DefinitionKind | DefinitionKind.dk_ValueBox The static instance of DefinitionKind indicating that an Interface Repository object is a ValueBox.
static DefinitionKind | DefinitionKind.dk_ValueMember The static instance of DefinitionKind indicating that an Interface Repository object is a ValueMember.
static DefinitionKind | DefinitionKind.dk_Wstring The static instance of DefinitionKind indicating that an Interface Repository object is a Wstring.

Methods in org.omg.CORBA that return DefinitionKind
DefinitionKind | _IDLTypeStub.def_kind()
DefinitionKind | IRObjectOperations.def_kind() Returns the DefinitionKind corresponding to this Interface Repository object.
static DefinitionKind | DefinitionKindHelper.extract(Any a)
static DefinitionKind | DefinitionKind.from_int(int i) Creates a DefinitionKind instance corresponding to the given code .
static DefinitionKind | DefinitionKindHelper.read(InputStream istream)

Methods in org.omg.CORBA with parameters of type DefinitionKind
static void | DefinitionKindHelper.insert(Any a, DefinitionKind that)
static void | DefinitionKindHelper.write(OutputStream ostream, DefinitionKind value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.DefinitionKindHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.DefinitionKindHelper

No usage of org.omg.CORBA.DefinitionKindHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.DoubleHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.DoubleHolder

No usage of org.omg.CORBA.DoubleHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.DoubleSeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.DoubleSeqHelper

No usage of org.omg.CORBA.DoubleSeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.DoubleSeqHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.DoubleSeqHolder

Packages that use DoubleSeqHolder
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of DoubleSeqHolder in org.omg.CORBA

Methods in org.omg.CORBA with parameters of type DoubleSeqHolder
 void DataInputStream.read_double_array(DoubleSeqHolder seq, int offset, int length)
Reads array of IDL doubles from offset for length elements from the input stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.DynamicImplementation

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.DynamicImplementation

Packages that use DynamicImplementation
org.omg.CosNaming Provides a naming service for Java IDL.

Uses of DynamicImplementation in org.omg.CosNaming

Subclasses of DynamicImplementation in org.omg.CosNaming
class | _BindingIteratorImplBase
class | _NamingContextImplBase

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.Environment

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.Environment

Packages that use Environment
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of Environment in org.omg.CORBA

Methods in org.omg.CORBA that return Environment
abstract Environment | ORB.create_environment() Creates an Environment object.
abstract Environment | Request.env() Retrieves the Environment object for this request.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ExceptionList

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ExceptionList

Packages that use ExceptionList
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.

Uses of ExceptionList in org.omg.CORBA

Methods in org.omg.CORBA that return ExceptionList
abstract ExceptionList | ORB.create_exception_list() Creates an empty ExceptionList object.
abstract ExceptionList | Request.exceptions() Retrieves the ExceptionList object for this request.

Methods in org.omg.CORBA with parameters of type ExceptionList
Request | LocalObject._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exceptions, ContextList contexts) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
Request | Object._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exclist, ContextList ctxlist) Creates a Request instance initialized with the given context, method name, list of arguments, container for the method's return value, list of possible exceptions, and list of context strings needing to be resolved.

Uses of ExceptionList in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable with parameters of type ExceptionList
Request | ObjectImpl._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exceptions, ContextList contexts) Creates a Request object that contains the given context, method, argument list, container for the result, exceptions, and list of property names to be used in resolving the context strings.
abstract Request | Delegate.create_request(Object obj, Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exclist, ContextList ctxlist) Creates a Request instance for use in the Dynamic Invocation Interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.FieldNameHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.FieldNameHelper

No usage of org.omg.CORBA.FieldNameHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.FixedHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.FixedHolder

No usage of org.omg.CORBA.FixedHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.FloatHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.FloatHolder

No usage of org.omg.CORBA.FloatHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.FloatSeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.FloatSeqHelper

No usage of org.omg.CORBA.FloatSeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.FloatSeqHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.FloatSeqHolder

Packages that use FloatSeqHolder
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of FloatSeqHolder in org.omg.CORBA

Methods in org.omg.CORBA with parameters of type FloatSeqHolder
 void DataInputStream.read_float_array(FloatSeqHolder seq, int offset, int length)
Reads array of IDL floats from offset for length elements from the input stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.FREE_MEM

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.FREE_MEM

No usage of org.omg.CORBA.FREE_MEM

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.IdentifierHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.IdentifierHelper

No usage of org.omg.CORBA.IdentifierHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.IDLTypeHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.IDLTypeHelper

No usage of org.omg.CORBA.IDLTypeHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.IMP_LIMIT

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.IMP_LIMIT

No usage of org.omg.CORBA.IMP_LIMIT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.INITIALIZE

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.INITIALIZE

No usage of org.omg.CORBA.INITIALIZE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.INTERNAL

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.INTERNAL

No usage of org.omg.CORBA.INTERNAL

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.INTF_REPOS

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.INTF_REPOS

No usage of org.omg.CORBA.INTF_REPOS

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.IntHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.IntHolder

No usage of org.omg.CORBA.IntHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.INVALID_ACTIVITY

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.INVALID_ACTIVITY

No usage of org.omg.CORBA.INVALID_ACTIVITY

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.INVALID_TRANSACTION

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.INVALID_TRANSACTION

No usage of org.omg.CORBA.INVALID_TRANSACTION

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.INV_FLAG

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.INV_FLAG

No usage of org.omg.CORBA.INV_FLAG

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.INV_IDENT

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.INV_IDENT

No usage of org.omg.CORBA.INV_IDENT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.INV_OBJREF

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.INV_OBJREF

No usage of org.omg.CORBA.INV_OBJREF

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.INV_POLICY

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.INV_POLICY

No usage of org.omg.CORBA.INV_POLICY

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.LocalObject

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.LocalObject

No usage of org.omg.CORBA.LocalObject

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.LongHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.LongHolder

No usage of org.omg.CORBA.LongHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.LongLongSeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.LongLongSeqHelper

No usage of org.omg.CORBA.LongLongSeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.LongLongSeqHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.LongLongSeqHolder

Packages that use LongLongSeqHolder
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of LongLongSeqHolder in org.omg.CORBA

Methods in org.omg.CORBA with parameters of type LongLongSeqHolder
 void DataInputStream.read_longlong_array(LongLongSeqHolder seq, int offset, int length)
Reads array of IDL long longs from offset for length elements from the input stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.LongSeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.LongSeqHelper

No usage of org.omg.CORBA.LongSeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.LongSeqHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.LongSeqHolder

Packages that use LongSeqHolder
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of LongSeqHolder in org.omg.CORBA

Methods in org.omg.CORBA with parameters of type LongSeqHolder
 void DataInputStream.read_long_array(LongSeqHolder seq, int offset, int length)
Reads array of IDL longs from offset for length elements from the input stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.MARSHAL

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.MARSHAL

Packages that use MARSHAL
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of MARSHAL in org.omg.CORBA

Methods in org.omg.CORBA that throw MARSHAL
abstract void | Any.insert_string(String s) Inserts the given String object into this Any object's value field.
abstract void | Any.insert_Value(Serializable v, TypeCode t) Inserts the given java.io.Serializable object into this Any object's value field.
abstract void | Any.insert_wstring(String s) Inserts the given String object into this Any object's value field.
abstract void | Any.read_value(InputStream is, TypeCode t) Reads off (unmarshals) the value of an Any object from the given input stream using the given typecode.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.NamedValue

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.NamedValue

Packages that use NamedValue
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.

Uses of NamedValue in org.omg.CORBA

Methods in org.omg.CORBA that return NamedValue
abstract NamedValue | NVList.add_item(String item_name, int flags) Creates a new NamedValue object initialized with the given name and flag, and adds it to the end of this NVList object.
abstract NamedValue | NVList.add_value(String item_name, Any val, int flags) Creates a new NamedValue object initialized with the given name, value, and flag, and adds it to the end of this NVList object.
abstract NamedValue | NVList.add(int flags) Creates a new NamedValue object initialized with the given flag and adds it to the end of this NVList object.
abstract NamedValue | ORB.create_named_value(String s, Any any, int flags) Creates a NamedValue object using the given name, value, and argument mode flags.
abstract NamedValue | NVList.item(int index) Retrieves the NamedValue object at the given index.
abstract NamedValue | Request.result() Retrieves the NamedValue object containing the return value for the method.

Methods in org.omg.CORBA with parameters of type NamedValue
Request | LocalObject._create_request(Context ctx, String operation, NVList arg_list, NamedValue result) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
Request | Object._create_request(Context ctx, String operation, NVList arg_list, NamedValue result) Creates a Request instance initialized with the given context, method name, list of arguments, and container for the method's return value.
Request | LocalObject._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exceptions, ContextList contexts) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
Request | Object._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exclist, ContextList ctxlist) Creates a Request instance initialized with the given context, method name, list of arguments, container for the method's return value, list of possible exceptions, and list of context strings needing to be resolved.

Uses of NamedValue in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable with parameters of type NamedValue
Request | ObjectImpl._create_request(Context ctx, String operation, NVList arg_list, NamedValue result) Creates a Request object that contains the given context, method, argument list, and container for the result.
Request | ObjectImpl._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exceptions, ContextList contexts) Creates a Request object that contains the given context, method, argument list, container for the result, exceptions, and list of property names to be used in resolving the context strings.
abstract Request | Delegate.create_request(Object obj, Context ctx, String operation, NVList arg_list, NamedValue result) Creates a Request instance for use in the Dynamic Invocation Interface.
abstract Request | Delegate.create_request(Object obj, Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exclist, ContextList ctxlist) Creates a Request instance for use in the Dynamic Invocation Interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.NameValuePair

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.NameValuePair

Packages that use NameValuePair
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of NameValuePair in org.omg.CORBA

Methods in org.omg.CORBA that return NameValuePair
static NameValuePair | NameValuePairHelper.extract(Any a)
NameValuePair[] | DynValue.get_members() Deprecated. Returns an array containing all the members of the value object stored in this DynValue.
NameValuePair[] | DynStruct.get_members() Deprecated. Returns an array containing all the members of the stored struct.
static NameValuePair | NameValuePairHelper.read(InputStream istream)

Methods in org.omg.CORBA with parameters of type NameValuePair
static void | NameValuePairHelper.insert(Any a, NameValuePair that)
void | DynValue.set_members(NameValuePair[] value) Deprecated. Sets the members of the value object this DynValue object represents to the given array of NameValuePair objects.
void | DynStruct.set_members(NameValuePair[] value) Deprecated. Set the members of the struct.
static void | NameValuePairHelper.write(OutputStream ostream, NameValuePair value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.NameValuePairHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.NameValuePairHelper

No usage of org.omg.CORBA.NameValuePairHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.NO_IMPLEMENT

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.NO_IMPLEMENT

No usage of org.omg.CORBA.NO_IMPLEMENT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.NO_MEMORY

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.NO_MEMORY

No usage of org.omg.CORBA.NO_MEMORY

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.NO_PERMISSION

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.NO_PERMISSION

No usage of org.omg.CORBA.NO_PERMISSION

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.NO_RESOURCES

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.NO_RESOURCES

No usage of org.omg.CORBA.NO_RESOURCES

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.NO_RESPONSE

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.NO_RESPONSE

No usage of org.omg.CORBA.NO_RESPONSE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.NVList

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.NVList

Packages that use NVList
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.

Uses of NVList in org.omg.CORBA

Methods in org.omg.CORBA that return NVList
abstract NVList | Request.arguments() Retrieves the NVList object containing the arguments to the method being invoked.
abstract NVList | ORB.create_list(int count) Allocates an NVList with (probably) enough space for the specified number of NamedValue objects.
NVList | ORB.create_operation_list(Object oper) Creates an NVList initialized with argument descriptions for the operation described in the given OperationDef object.
abstract NVList | Context.get_values(String start_scope, int op_flags, String pattern) Retrieves the NamedValue objects whose name field matches the given name or name pattern.

Methods in org.omg.CORBA with parameters of type NVList
Request | LocalObject._create_request(Context ctx, String operation, NVList arg_list, NamedValue result) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
Request | Object._create_request(Context ctx, String operation, NVList arg_list, NamedValue result) Creates a Request instance initialized with the given context, method name, list of arguments, and container for the method's return value.
Request | LocalObject._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exceptions, ContextList contexts) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
Request | Object._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exclist, ContextList ctxlist) Creates a Request instance initialized with the given context, method name, list of arguments, container for the method's return value, list of possible exceptions, and list of context strings needing to be resolved.
void | ServerRequest.arguments(NVList args) Specifies method parameter types and retrieves "in" and "inout" argument values.
void | ServerRequest.params(NVList params) Deprecated. use the method arguments
abstract void | Context.set_values(NVList values) I Sets one or more property values in this Context object.

Uses of NVList in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable with parameters of type NVList
Request | ObjectImpl._create_request(Context ctx, String operation, NVList arg_list, NamedValue result) Creates a Request object that contains the given context, method, argument list, and container for the result.
Request | ObjectImpl._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exceptions, ContextList contexts) Creates a Request object that contains the given context, method, argument list, container for the result, exceptions, and list of property names to be used in resolving the context strings.
abstract Request | Delegate.create_request(Object obj, Context ctx, String operation, NVList arg_list, NamedValue result) Creates a Request instance for use in the Dynamic Invocation Interface.
abstract Request | Delegate.create_request(Object obj, Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exclist, ContextList ctxlist) Creates a Request instance for use in the Dynamic Invocation Interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ObjectHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ObjectHelper

No usage of org.omg.CORBA.ObjectHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ObjectHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ObjectHolder

No usage of org.omg.CORBA.ObjectHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.OBJECT_NOT_EXIST

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.OBJECT_NOT_EXIST

No usage of org.omg.CORBA.OBJECT_NOT_EXIST

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.OBJ_ADAPTER

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.OBJ_ADAPTER

No usage of org.omg.CORBA.OBJ_ADAPTER

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.OctetSeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.OctetSeqHelper

No usage of org.omg.CORBA.OctetSeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.OctetSeqHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.OctetSeqHolder

Packages that use OctetSeqHolder
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of OctetSeqHolder in org.omg.CORBA

Methods in org.omg.CORBA with parameters of type OctetSeqHolder
 void DataInputStream.read_octet_array(OctetSeqHolder seq, int offset, int length)
Reads array of IDL octets from offset for length elements from the input stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ORB

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ORB

Packages that use ORB
javax.rmi.CORBA | Contains portability APIs for RMI-IIOP.
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA_2_3 | The CORBA_2_3 package defines additions to existing CORBA interfaces in the Java[tm] Standard Edition 6. These changes occurred in recent revisions to the CORBA API defined by the OMG. The new methods were added to interfaces derived from the corresponding interfaces in the CORBA package. This provides backward compatibility and avoids breaking the JCK tests.
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.portable | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ORB in javax.rmi.CORBA

Methods in javax.rmi.CORBA that return ORB
 ORB Tie.orb()
Returns the ORB for this tie.

Methods in javax.rmi.CORBA with parameters of type ORB
 void Stub.connect(ORB orb)
Connects this stub to an ORB.
 void StubDelegate.connect(Stub self, ORB orb)
Delegation call for Stub.connect(org.omg.CORBA.ORB).
 Object UtilDelegate.copyObject(Object obj, ORB orb)
Delegation call for Util.copyObject(java.lang.Object, org.omg.CORBA.ORB).
static Object Util.copyObject(Object obj, ORB orb)
Copies or connects an object.
 Object[] UtilDelegate.copyObjects(Object[] obj, ORB orb)
Delegation call for Util.copyObjects(java.lang.Object[], org.omg.CORBA.ORB).
static Object[] Util.copyObjects(Object[] obj, ORB orb)
Copies or connects an array of objects.
 void Tie.orb(ORB orb)
Sets the ORB for this tie.

Uses of ORB in org.omg.CORBA

Methods in org.omg.CORBA that return ORB
ORB | LocalObject._orb() Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
static ORB | ORB.init() Returns the ORB singleton object.
static ORB | ORB.init(Applet app, Properties props) Creates a new ORB instance for an applet.
static ORB | ORB.init(String[] args, Properties props) Creates a new ORB instance for a standalone application.

Uses of ORB in org.omg.CORBA_2_3

Subclasses of ORB in org.omg.CORBA_2_3
 class ORB
A class extending org.omg.CORBA.ORB to make the ORB portable under the OMG CORBA version 2.3 specification.

Uses of ORB in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable that return ORB
ORB | ObjectImpl._orb() Returns a reference to the ORB associated with this object and its delegate.
ORB | InputStream.orb() Returns the ORB that created this InputStream.
ORB | OutputStream.orb() Returns the ORB that created this OutputStream.
ORB | Delegate.orb(Object obj) Provides a reference to the orb associated with its parameter.

Uses of ORB in org.omg.CosNaming

Methods in org.omg.CosNaming with parameters of type ORB
NamingContextExt | NamingContextExtPOA._this(ORB orb)
NamingContext | NamingContextPOA._this(ORB orb)
BindingIterator | BindingIteratorPOA._this(ORB orb)

Uses of ORB in org.omg.PortableServer

Methods in org.omg.PortableServer that return ORB
 ORB Servant._orb()
Returns the instance of the ORB currently associated with the Servant (convenience method).

Methods in org.omg.PortableServer with parameters of type ORB
Object | Servant._this_object(ORB orb) Allows the servant to obtain the object reference for the target CORBA Object it is incarnating for that request.
ServantLocator | ServantLocatorPOA._this(ORB orb)
ServantActivator | ServantActivatorPOA._this(ORB orb)

Uses of ORB in org.omg.PortableServer.portable

Methods in org.omg.PortableServer.portable that return ORB
 ORB Delegate.orb(Servant Self)
Convenience method that returns the instance of the ORB currently associated with the Servant.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ParameterMode

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ParameterMode

Packages that use ParameterMode
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.Dynamic | This package contains the Dynamic module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.9.

Uses of ParameterMode in org.omg.CORBA

Fields in org.omg.CORBA declared as ParameterMode
static ParameterMode | ParameterMode.PARAM_IN
static ParameterMode | ParameterMode.PARAM_INOUT
static ParameterMode | ParameterMode.PARAM_OUT
ParameterMode | ParameterModeHolder.value

Methods in org.omg.CORBA that return ParameterMode
static ParameterMode | ParameterModeHelper.extract(Any a)
static ParameterMode | ParameterMode.from_int(int value)
static ParameterMode | ParameterModeHelper.read(InputStream istream)

Methods in org.omg.CORBA with parameters of type ParameterMode
static void | ParameterModeHelper.insert(Any a, ParameterMode that)
static void | ParameterModeHelper.write(OutputStream ostream, ParameterMode value)

Constructors in org.omg.CORBA with parameters of type ParameterMode
ParameterModeHolder(ParameterMode initialValue)

Uses of ParameterMode in org.omg.Dynamic

Fields in org.omg.Dynamic declared as ParameterMode
 ParameterMode Parameter.mode

Constructors in org.omg.Dynamic with parameters of type ParameterMode
Parameter(Any _argument, ParameterMode _mode)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ParameterModeHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ParameterModeHelper

No usage of org.omg.CORBA.ParameterModeHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ParameterModeHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ParameterModeHolder

No usage of org.omg.CORBA.ParameterModeHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.PERSIST_STORE

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.PERSIST_STORE

No usage of org.omg.CORBA.PERSIST_STORE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.PolicyError

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.PolicyError

Packages that use PolicyError
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of PolicyError in org.omg.CORBA

Fields in org.omg.CORBA declared as PolicyError
 PolicyError PolicyErrorHolder.value

Methods in org.omg.CORBA that return PolicyError
static PolicyError | PolicyErrorHelper.extract(Any a)
static PolicyError | PolicyErrorHelper.read(InputStream istream)

Methods in org.omg.CORBA with parameters of type PolicyError
static void | PolicyErrorHelper.insert(Any a, PolicyError that)
static void | PolicyErrorHelper.write(OutputStream ostream, PolicyError value)

Methods in org.omg.CORBA that throw PolicyError
 Policy ORB.create_policy(int type, Any val)
Can be invoked to create new instances of policy objects of a specific type with specified initial state.

Constructors in org.omg.CORBA with parameters of type PolicyError
PolicyErrorHolder(PolicyError initialValue)

Uses of PolicyError in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor that throw PolicyError
 Policy PolicyFactoryOperations.create_policy(int type, Any value)
Returns an instance of the appropriate interface derived from CORBA.Policy whose value corresponds to the specified any.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.PolicyErrorCodeHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.PolicyErrorCodeHelper

No usage of org.omg.CORBA.PolicyErrorCodeHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.PolicyErrorHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.PolicyErrorHelper

No usage of org.omg.CORBA.PolicyErrorHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.PolicyErrorHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.PolicyErrorHolder

No usage of org.omg.CORBA.PolicyErrorHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.PolicyHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.PolicyHelper

No usage of org.omg.CORBA.PolicyHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.PolicyHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.PolicyHolder

No usage of org.omg.CORBA.PolicyHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.PolicyListHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.PolicyListHelper

No usage of org.omg.CORBA.PolicyListHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.PolicyListHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.PolicyListHolder

No usage of org.omg.CORBA.PolicyListHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.PolicyTypeHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.PolicyTypeHelper

No usage of org.omg.CORBA.PolicyTypeHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.Principal

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.Principal

Packages that use Principal
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.

Uses of Principal in org.omg.CORBA

Fields in org.omg.CORBA declared as Principal
 Principal PrincipalHolder.value
Deprecated. The Principal value held by this PrincipalHolder object.

Methods in org.omg.CORBA that return Principal
 Principal Any.extract_Principal()
Deprecated. Deprecated by CORBA 2.2.

Methods in org.omg.CORBA with parameters of type Principal
 void Any.insert_Principal(Principal p)
Deprecated. Deprecated by CORBA 2.2.

Constructors in org.omg.CORBA with parameters of type Principal
PrincipalHolder(Principal initial)
Deprecated. Constructs a new PrincipalHolder object with its value field initialized to the given Principal object.

Uses of Principal in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable that return Principal
 Principal InputStream.read_Principal()
Deprecated. Deprecated by CORBA 2.2.

Methods in org.omg.CORBA.portable with parameters of type Principal
 void OutputStream.write_Principal(Principal value)
Deprecated. Deprecated by CORBA 2.2.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.PrincipalHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.PrincipalHolder

No usage of org.omg.CORBA.PrincipalHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.REBIND

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.REBIND

No usage of org.omg.CORBA.REBIND

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.RepositoryIdHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.RepositoryIdHelper

No usage of org.omg.CORBA.RepositoryIdHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.Request

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.Request

Packages that use Request
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.

Uses of Request in org.omg.CORBA

Methods in org.omg.CORBA that return Request
Request | LocalObject._create_request(Context ctx, String operation, NVList arg_list, NamedValue result) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
Request | Object._create_request(Context ctx, String operation, NVList arg_list, NamedValue result) Creates a Request instance initialized with the given context, method name, list of arguments, and container for the method's return value.
Request | LocalObject._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exceptions, ContextList contexts) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
Request | Object._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exclist, ContextList ctxlist) Creates a Request instance initialized with the given context, method name, list of arguments, container for the method's return value, list of possible exceptions, and list of context strings needing to be resolved.
Request | LocalObject._request(String operation) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
Request | Object._request(String operation) Creates a Request instance for use in the Dynamic Invocation Interface.
abstract Request | ORB.get_next_response() Gets the next Request instance for which a response has been received.

Methods in org.omg.CORBA with parameters of type Request
abstract void | ORB.send_multiple_requests_deferred(Request[] req) Sends multiple dynamic (DII) requests asynchronously.
abstract void | ORB.send_multiple_requests_oneway(Request[] req) Sends multiple dynamic (DII) requests asynchronously without expecting any responses.

Uses of Request in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable that return Request
Request | ObjectImpl._create_request(Context ctx, String operation, NVList arg_list, NamedValue result) Creates a Request object that contains the given context, method, argument list, and container for the result.
Request | ObjectImpl._create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exceptions, ContextList contexts) Creates a Request object that contains the given context, method, argument list, container for the result, exceptions, and list of property names to be used in resolving the context strings.
Request | ObjectImpl._request(String operation) Creates a Request object containing the given method that can be used with the Dynamic Invocation Interface.
abstract Request | Delegate.create_request(Object obj, Context ctx, String operation, NVList arg_list, NamedValue result) Creates a Request instance for use in the Dynamic Invocation Interface.
abstract Request | Delegate.create_request(Object obj, Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exclist, ContextList ctxlist) Creates a Request instance for use in the Dynamic Invocation Interface.
abstract Request | Delegate.request(Object obj, String operation) Creates a Request instance for use in the Dynamic Invocation Interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ServerRequest

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ServerRequest

Packages that use ServerRequest
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ServerRequest in org.omg.CORBA

Methods in org.omg.CORBA with parameters of type ServerRequest
 void DynamicImplementation.invoke(ServerRequest request)
Deprecated. Deprecated by Portable Object Adapter

Uses of ServerRequest in org.omg.CosNaming

Methods in org.omg.CosNaming with parameters of type ServerRequest
void | _BindingIteratorImplBase.invoke(ServerRequest r)
void | _NamingContextImplBase.invoke(ServerRequest r)

Uses of ServerRequest in org.omg.PortableServer

Methods in org.omg.PortableServer with parameters of type ServerRequest
abstract  void DynamicImplementation.invoke(ServerRequest request)
Receives requests issued to any CORBA object incarnated by the DSI servant and performs the processing necessary to execute the request.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ServiceDetail

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ServiceDetail

Packages that use ServiceDetail
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of ServiceDetail in org.omg.CORBA

Fields in org.omg.CORBA declared as ServiceDetail
 ServiceDetail[] ServiceInformation.service_details
Array of ServiceDetails giving more details about the service.

Methods in org.omg.CORBA that return ServiceDetail
static ServiceDetail | ServiceDetailHelper.extract(Any a)
static ServiceDetail | ServiceDetailHelper.read(InputStream in)

Methods in org.omg.CORBA with parameters of type ServiceDetail
static void | ServiceDetailHelper.insert(Any a, ServiceDetail that)
static void | ServiceDetailHelper.write(OutputStream out, ServiceDetail that)

Constructors in org.omg.CORBA with parameters of type ServiceDetail
ServiceInformation(int[] __service_options, ServiceDetail[] __service_details)
Constructs a ServiceInformation object with the given service_options and service_details.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ServiceDetailHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ServiceDetailHelper

No usage of org.omg.CORBA.ServiceDetailHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ServiceInformation

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ServiceInformation

Packages that use ServiceInformation
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of ServiceInformation in org.omg.CORBA

Fields in org.omg.CORBA declared as ServiceInformation
 ServiceInformation ServiceInformationHolder.value
The ServiceInformation value held by this ServiceInformationHolder object in its value field.

Methods in org.omg.CORBA that return ServiceInformation
static ServiceInformation | ServiceInformationHelper.extract(Any a)
static ServiceInformation | ServiceInformationHelper.read(InputStream in)

Methods in org.omg.CORBA with parameters of type ServiceInformation
static void | ServiceInformationHelper.insert(Any a, ServiceInformation that)
static void | ServiceInformationHelper.write(OutputStream out, ServiceInformation that)

Constructors in org.omg.CORBA with parameters of type ServiceInformation
ServiceInformationHolder(ServiceInformation arg)
Constructs a new ServiceInformationHolder object with its value field initialized to the given ServiceInformation object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ServiceInformationHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ServiceInformationHelper

No usage of org.omg.CORBA.ServiceInformationHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ServiceInformationHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ServiceInformationHolder

Packages that use ServiceInformationHolder
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of ServiceInformationHolder in org.omg.CORBA

Methods in org.omg.CORBA with parameters of type ServiceInformationHolder
 boolean ORB.get_service_information(short service_type, ServiceInformationHolder service_info)
Used to obtain information about CORBA facilities and services that are supported by this ORB.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.SetOverrideType

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.SetOverrideType

Packages that use SetOverrideType
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.

Uses of SetOverrideType in org.omg.CORBA

Fields in org.omg.CORBA declared as SetOverrideType
static SetOverrideType | SetOverrideType.ADD_OVERRIDE The SetOverrideType constant for the enum value ADD_OVERRIDE.
static SetOverrideType | SetOverrideType.SET_OVERRIDE The SetOverrideType constant for the enum value SET_OVERRIDE.

Methods in org.omg.CORBA that return SetOverrideType
static SetOverrideType | SetOverrideTypeHelper.extract(Any a)
static SetOverrideType | SetOverrideType.from_int(int i) Converts the given int to the corresponding SetOverrideType instance.
static SetOverrideType | SetOverrideTypeHelper.read(InputStream istream)

Methods in org.omg.CORBA with parameters of type SetOverrideType
Object | LocalObject._set_policy_override(Policy[] policies, SetOverrideType set_add) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented.
Object | Object._set_policy_override(Policy[] policies, SetOverrideType set_add) Returns a new Object with the given policies either replacing any existing policies in this Object or with the given policies added to the existing ones, depending on the value of the given SetOverrideType object.
static void | SetOverrideTypeHelper.insert(Any a, SetOverrideType that)
static void | SetOverrideTypeHelper.write(OutputStream ostream, SetOverrideType value)

Uses of SetOverrideType in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable with parameters of type SetOverrideType
Object | ObjectImpl._set_policy_override(Policy[] policies, SetOverrideType set_add) Sets this ObjectImpl object's override type for the given policies to the given instance of SetOverrideType.
Object | Delegate.set_policy_override(Object self, Policy[] policies, SetOverrideType set_add) Associates the policies passed in with a newly created object reference that it returns.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.SetOverrideTypeHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.SetOverrideTypeHelper

No usage of org.omg.CORBA.SetOverrideTypeHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ShortHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ShortHolder

No usage of org.omg.CORBA.ShortHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ShortSeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ShortSeqHelper

No usage of org.omg.CORBA.ShortSeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ShortSeqHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ShortSeqHolder

Packages that use ShortSeqHolder
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of ShortSeqHolder in org.omg.CORBA

Methods in org.omg.CORBA with parameters of type ShortSeqHolder
 void DataInputStream.read_short_array(ShortSeqHolder seq, int offset, int length)
Reads array of IDL shorts from offset for length elements from the input stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.StringHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.StringHolder

No usage of org.omg.CORBA.StringHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.StringSeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.StringSeqHelper

No usage of org.omg.CORBA.StringSeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.StringSeqHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.StringSeqHolder

No usage of org.omg.CORBA.StringSeqHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.StringValueHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.StringValueHelper

No usage of org.omg.CORBA.StringValueHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.StructMember

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.StructMember

Packages that use StructMember
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of StructMember in org.omg.CORBA

Methods in org.omg.CORBA that return StructMember
static StructMember | StructMemberHelper.extract(Any a)
static StructMember | StructMemberHelper.read(InputStream istream)

Methods in org.omg.CORBA with parameters of type StructMember
abstract TypeCode | ORB.create_exception_tc(String id, String name, StructMember[] members) Creates a TypeCode object representing an IDL exception.
abstract TypeCode | ORB.create_struct_tc(String id, String name, StructMember[] members) Creates a TypeCode object representing an IDL struct.
static void | StructMemberHelper.insert(Any a, StructMember that)
static void | StructMemberHelper.write(OutputStream ostream, StructMember value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.StructMemberHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.StructMemberHelper

No usage of org.omg.CORBA.StructMemberHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.SystemException

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.SystemException

Packages that use SystemException
javax.rmi.CORBA | Contains portability APIs for RMI-IIOP.
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.

Uses of SystemException in javax.rmi.CORBA

Methods in javax.rmi.CORBA with parameters of type SystemException
 RemoteException UtilDelegate.mapSystemException(SystemException ex)
Delegation call for Util.mapSystemException(org.omg.CORBA.SystemException).
static RemoteException Util.mapSystemException(SystemException ex)
Maps a SystemException to a RemoteException.

Uses of SystemException in org.omg.CORBA

Subclasses of SystemException in org.omg.CORBA
class | ACTIVITY_COMPLETED The ACTIVITY_COMPLETED system exception may be raised on any method for which Activity context is accessed.
class | ACTIVITY_REQUIRED The ACTIVITY_REQUIRED system exception may be raised on any method for which an Activity context is required.
class | BAD_CONTEXT Exception thrown when an operation is invoked by a client but the passed context does not contain the context values required by the operation.
class | BAD_INV_ORDER This exception indicates that the caller has invoked operations in the wrong order.
class | BAD_OPERATION Exception thrown when an object reference denotes an existing object, but that the object does not support the operation that was invoked.
class | BAD_PARAM Exception thrown when a parameter passed to a call is out of range or otherwise considered illegal.
class | BAD_QOS The BAD_QOS exception is raised whenever an object cannot support the quality of service required by an invocation parameter that has a quality of service semantics associated with it.
class | BAD_TYPECODE Exception thrown when the ORB has encountered a malformed type code (for example, a type code with an invalid TCKind value).
class | CODESET_INCOMPATIBLE This exception is raised whenever meaningful communication is not possible between client and server native code sets.
class | COMM_FAILURE This exception is raised if communication is lost while an operation is in progress, after the request was sent by the client, but before the reply from the server has been returned to the client.
class | DATA_CONVERSION This exception is raised if an ORB cannot convert the representation of data as marshaled into its native representation or vice-versa.
class | FREE_MEM Exception thrown when the ORB failed in an attempt to free dynamic memory, for example because of heap corruption or memory segments being locked.
class | IMP_LIMIT This exception indicates that an implementation limit was exceeded in the ORB run time.
class | INITIALIZE Exception thrown when an ORB has encountered a failure during its initialization, such as failure to acquire networking resources or detecting a configuration error.
class | INTERNAL This exception indicates an internal failure in an ORB, for example, if an ORB has detected corruption of its internal data structures.
class | INTF_REPOS Exception raised when an ORB cannot reach the interface repository, or some other failure relating to the interface repository is detected.
class | INV_FLAG Exception thrown when an invalid flag was passed to an operation (for example, when creating a DII request).
class | INV_IDENT This exception indicates that an IDL identifier is syntactically invalid.
class | INV_OBJREF This exception indicates that an object reference is internally malformed.
class | INV_POLICY Standard exception thrown when an invocation cannot be made because of an incompatibility between Policy overrides that apply to the particular invocation.
class | INVALID_ACTIVITY The INVALID_ACTIVITY system exception may be raised on the Activity or Transaction services' resume methods if a transaction or Activity is resumed in a context different to that from which it was suspended.
class | INVALID_TRANSACTION Exception thrown when the request carried an invalid transaction context.
class | MARSHAL A request or reply from the network is structurally invalid.
class | NO_IMPLEMENT This exception indicates that even though the operation that was invoked exists (it has an IDL definition), no implementation for that operation exists.
class | NO_MEMORY Exception thrown when the ORB run time has run out of memory.
class | NO_PERMISSION Exception thrown when an invocation failed because the caller has insufficient privileges.
class | NO_RESOURCES Exception thrown when the ORB has encountered some general resource limitation.
class | NO_RESPONSE This exception is raised if a client attempts to retrieve the result of a deferred synchronous call, but the response for the request is not yet available.
class | OBJ_ADAPTER This exception typically indicates an administrative mismatch, for example, a server may have made an attempt to register itself with an implementation repository under a name that is already in use, or is unknown to the repository.
class | OBJECT_NOT_EXIST Exception raised whenever an invocation on a deleted object was performed.
class | PERSIST_STORE This exception indicates a persistent storage failure, for example, failure to establish a database connection or corruption of a database.
class | REBIND REBIND is raised when the current effective RebindPolicy, has a value of NO_REBIND or NO_RECONNECT and an invocation on a bound object reference results in a LocateReply message with status OBJECT_FORWARD or a Reply message with status LOCATION_FORWARD.
class | TIMEOUT TIMEOUT is raised when no delivery has been made and the specified time-to-live period has been exceeded.
class | TRANSACTION_MODE The CORBA TRANSACTION_MODE exception is thrown by the client ORB if it detects a mismatch between the InvocationPolicy in the IOR and the chosen invocation path (i.e, direct or routed invocation).
class | TRANSACTION_REQUIRED Exception indicates that the request carried a null transaction context, but an active transaction is required.
class | TRANSACTION_ROLLEDBACK Exception thrown when the transaction associated with the request has already been rolled back or marked to roll back.
class | TRANSACTION_UNAVAILABLE The CORBA TRANSACTION_UNAVAILABLE exception is thrown by the ORB when it cannot process a transaction service context because its connection to the Transaction Service has been abnormally terminated.
class | TRANSIENT Exception thrown when the ORB attempted to reach an object and failed.
class | UNKNOWN This exception is raised if an operation implementation throws a non-CORBA exception (such as an exception specific to the implementation's programming language), or if an operation raises a user exception that does not appear in the operation's raises expression.

Uses of SystemException in org.omg.CORBA.portable

Subclasses of SystemException in org.omg.CORBA.portable
class | IndirectionException The Indirection exception is a Java specific system exception.
class | UnknownException The org.omg.CORBA.portable.UnknownException is used for reporting unknown exceptions between ties and ORBs and between ORBs and stubs.

Methods in org.omg.CORBA.portable that throw SystemException
 OutputStream InvokeHandler._invoke(String method, InputStream input, ResponseHandler handler)
Invoked by the ORB to dispatch a request to the servant.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.TCKind

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.TCKind

Packages that use TCKind
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.DynamicAny | Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of TCKind in org.omg.CORBA

Fields in org.omg.CORBA declared as TCKind
static TCKind | TCKind.tk_abstract_interface The TCKind constant whose value field is initialized with TCKind._tk_abstract_interface.
static TCKind | TCKind.tk_alias The TCKind constant whose value field is initialized with TCKind._tk_alias.
static TCKind | TCKind.tk_any The TCKind constant whose value field is initialized with TCKind._tk_any.
static TCKind | TCKind.tk_array The TCKind constant whose value field is initialized with TCKind._tk_array.
static TCKind | TCKind.tk_boolean The TCKind constant whose value field is initialized with TCKind._tk_boolean.
static TCKind | TCKind.tk_char The TCKind constant whose value field is initialized with TCKind._tk_char.
static TCKind | TCKind.tk_double The TCKind constant whose value field is initialized with TCKind._tk_double.
static TCKind | TCKind.tk_enum The TCKind constant whose value field is initialized with TCKind._tk_enum.
static TCKind | TCKind.tk_except The TCKind constant whose value field is initialized with TCKind._tk_except.
static TCKind | TCKind.tk_fixed The TCKind constant whose value field is initialized with TCKind._tk_fixed.
static TCKind | TCKind.tk_float The TCKind constant whose value field is initialized with TCKind._tk_float.
static TCKind | TCKind.tk_long The TCKind constant whose value field is initialized with TCKind._tk_long.
static TCKind | TCKind.tk_longdouble The TCKind constant whose value field is initialized with TCKind._tk_longdouble.
static TCKind | TCKind.tk_longlong The TCKind constant whose value field is initialized with TCKind._tk_longlong.
static TCKind | TCKind.tk_native The TCKind constant whose value field is initialized with TCKind._tk_native.
static TCKind | TCKind.tk_null The TCKind constant whose value field is initialized with TCKind._tk_null.
static TCKind | TCKind.tk_objref The TCKind constant whose value field is initialized with TCKind._tk_objref.
static TCKind | TCKind.tk_octet The TCKind constant whose value field is initialized with TCKind._tk_octet.
static TCKind | TCKind.tk_Principal The TCKind constant whose value field is initialized with TCKind._tk_Principal.
static TCKind | TCKind.tk_sequence The TCKind constant whose value field is initialized with TCKind._tk_sequence.
static TCKind | TCKind.tk_short The TCKind constant whose value field is initialized with TCKind._tk_short.
static TCKind | TCKind.tk_string The TCKind constant whose value field is initialized with TCKind._tk_string.
static TCKind | TCKind.tk_struct The TCKind constant whose value field is initialized with TCKind._tk_struct.
static TCKind | TCKind.tk_TypeCode The TCKind constant whose value field is initialized with TCKind._tk_TypeCode.
static TCKind | TCKind.tk_ulong The TCKind constant whose value field is initialized with TCKind._tk_ulong.
static TCKind | TCKind.tk_ulonglong The TCKind constant whose value field is initialized with TCKind._tk_ulonglong.
static TCKind | TCKind.tk_union The TCKind constant whose value field is initialized with TCKind._tk_union.
static TCKind | TCKind.tk_ushort The TCKind constant whose value field is initialized with TCKind._tk_ushort.
static TCKind | TCKind.tk_value The TCKind constant whose value field is initialized with TCKind._tk_value.
static TCKind | TCKind.tk_value_box The TCKind constant whose value field is initialized with TCKind._tk_value_box.
static TCKind | TCKind.tk_void The TCKind constant whose value field is initialized with TCKind._tk_void.
static TCKind | TCKind.tk_wchar The TCKind constant whose value field is initialized with TCKind._tk_wchar.
static TCKind | TCKind.tk_wstring The TCKind constant whose value field is initialized with TCKind._tk_wstring.

Methods in org.omg.CORBA that return TCKind
TCKind | DynValue.current_member_kind() Deprecated. Returns the TCKind object that describes the current member.
TCKind | DynStruct.current_member_kind() Deprecated. Returns the TCKind object that describes the kind of the current member.
TCKind | DynUnion.discriminator_kind() Deprecated. Returns the TCKind object associated with the discriminator of this union.
static TCKind | TCKind.from_int(int i) Converts the given int to the corresponding TCKind instance.
abstract TCKind | TypeCode.kind() Retrieves the kind of this TypeCode object.
TCKind | DynUnion.member_kind() Deprecated. Returns the TCKind associated with the member of this union.

Methods in org.omg.CORBA with parameters of type TCKind
abstract  TypeCode ORB.get_primitive_tc(TCKind tcKind)
Retrieves the TypeCode object that represents the given primitive IDL type.

Uses of TCKind in org.omg.DynamicAny

Methods in org.omg.DynamicAny that return TCKind
TCKind | _DynValueStub.current_member_kind() Returns the TCKind associated with the member at the current position.
TCKind | _DynStructStub.current_member_kind() Returns the TCKind associated with the member at the current position.
TCKind | DynValueOperations.current_member_kind() Returns the TCKind associated with the member at the current position.
TCKind | DynStructOperations.current_member_kind() Returns the TCKind associated with the member at the current position.
TCKind | _DynUnionStub.discriminator_kind() Returns the TCKind value of the discriminators TypeCode.
TCKind | DynUnionOperations.discriminator_kind() Returns the TCKind value of the discriminators TypeCode.
TCKind | _DynUnionStub.member_kind() Returns the TCKind value of the currently active members TypeCode.
TCKind | DynUnionOperations.member_kind() Returns the TCKind value of the currently active members TypeCode.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.TIMEOUT

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.TIMEOUT

No usage of org.omg.CORBA.TIMEOUT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.TRANSACTION_MODE

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.TRANSACTION_MODE

No usage of org.omg.CORBA.TRANSACTION_MODE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.TRANSACTION_REQUIRED

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.TRANSACTION_REQUIRED

No usage of org.omg.CORBA.TRANSACTION_REQUIRED

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.TRANSACTION_ROLLEDBACK

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.TRANSACTION_ROLLEDBACK

No usage of org.omg.CORBA.TRANSACTION_ROLLEDBACK

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.TRANSACTION_UNAVAILABLE

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.TRANSACTION_UNAVAILABLE

No usage of org.omg.CORBA.TRANSACTION_UNAVAILABLE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.TRANSIENT

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.TRANSIENT

No usage of org.omg.CORBA.TRANSIENT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.TypeCode

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.TypeCode

Packages that use TypeCode
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextExtPackage | This package contains the following classes, which are used in org.omg.CosNaming.NamingContextExt:
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.
org.omg.DynamicAny | Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.
org.omg.DynamicAny.DynAnyFactoryPackage | This package contains classes and exceptions from the DynAnyFactory interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.2.
org.omg.DynamicAny.DynAnyPackage | This package contains classes and exceptions from the DynAny interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.IOP.CodecFactoryPackage | This package contains the exceptions specified in the IOP::CodeFactory interface (as part of the Portable Interceptors spec).
org.omg.IOP.CodecPackage | This package is generated from the IOP::Codec IDL interface definition.
org.omg.Messaging | This package contains the Messaging module specified in the OMG CORBA Messaging specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07.
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.
org.omg.PortableInterceptor.ORBInitInfoPackage | This package contains the exceptions and typedefs from the ORBInitInfo local interface of the PortableInterceptor module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.7.2.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.CurrentPackage | Provides method implementations with access to the identity of the object on which the method was invoked.
org.omg.PortableServer.POAManagerPackage | Encapsulates the processing state of the POAs it is associated with.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.
org.omg.PortableServer.ServantLocatorPackage | Provides classes and interfaces for locating the servant.

Uses of TypeCode in org.omg.CORBA

Fields in org.omg.CORBA declared as TypeCode
TypeCode | ValueMember.type The type of of this value member.
TypeCode | UnionMember.type The type of the union member described by this UnionMember object.
TypeCode | StructMember.type The type of the struct member described by this StructMember object.
TypeCode | TypeCodeHolder.value The TypeCode value held by this TypeCodeHolder object.

Methods in org.omg.CORBA that return TypeCode
TypeCode | WrongTransactionHolder._type()
TypeCode | WStringSeqHolder._type()
TypeCode | UnknownUserExceptionHolder._type()
TypeCode | StringSeqHolder._type()
TypeCode | PolicyErrorHolder._type()
TypeCode | ParameterModeHolder._type()
TypeCode | ValueBaseHolder._type() Returns the TypeCode object corresponding to the value held in the Holder.
TypeCode | PolicyListHolder._type()
TypeCode | PolicyHolder._type()
TypeCode | DoubleSeqHolder._type()
TypeCode | FloatSeqHolder._type()
TypeCode | LongLongSeqHolder._type()
TypeCode | ULongLongSeqHolder._type()
TypeCode | ULongSeqHolder._type()
TypeCode | LongSeqHolder._type()
TypeCode | UShortSeqHolder._type()
TypeCode | ShortSeqHolder._type()
TypeCode | OctetSeqHolder._type()
TypeCode | WCharSeqHolder._type()
TypeCode | CurrentHolder._type()
TypeCode | CharSeqHolder._type()
TypeCode | BooleanSeqHolder._type()
TypeCode | AnySeqHolder._type()
TypeCode | TypeCodeHolder._type() Returns the TypeCode corresponding to the value held in this TypeCodeHolder object.
TypeCode | StringHolder._type() Retrieves the TypeCode object that corresponds to the value held in this StringHolder object.
TypeCode | ShortHolder._type() Returns the TypeCode corresponding to the value held in this ShortHolder object.
TypeCode | PrincipalHolder._type() Deprecated.
TypeCode | ObjectHolder._type() Returns the TypeCode corresponding to the value held in this ObjectHolder object
TypeCode | LongHolder._type() Returns the TypeCode object corresponding to the value held in the Holder.
TypeCode | IntHolder._type() Retrieves the TypeCode object that corresponds to the value held in this IntHolder object's value field.
TypeCode | FloatHolder._type() Return the TypeCode of this Streamable.
TypeCode | FixedHolder._type() Return the TypeCode of this holder object.
TypeCode | DoubleHolder._type() Return the TypeCode of this holder object.
TypeCode | CharHolder._type() Returns the TypeCode object corresponding to the value held in this CharHolder object.
TypeCode | ByteHolder._type() Returns the TypeCode corresponding to the value held in this ByteHolder object.
TypeCode | BooleanHolder._type() Retrieves the TypeCode object that corresponds to the value held in this BooleanHolder object.
TypeCode | AnyHolder._type() Returns the TypeCode object corresponding to the value held in this AnyHolder object.
TypeCode | ServiceInformationHolder._type() Retrieves the TypeCode object that corresponds to the value held in this ServiceInformationHolder object's value field.
abstract TypeCode | TypeCode.concrete_base_type() Returns the TypeCode object that describes the concrete base type of the value type that this TypeCode object describes.
abstract TypeCode | TypeCode.content_type() Returns the TypeCode object representing the IDL type for the members of the object described by this TypeCode object.
TypeCode | ORB.create_abstract_interface_tc(String id, String name) Create a TypeCode object for an IDL abstract interface.
abstract TypeCode | ORB.create_alias_tc(String id, String name, TypeCode original_type) Creates a TypeCode object representing an IDL alias (typedef).
abstract TypeCode | ORB.create_array_tc(int length, TypeCode element_type) Creates a TypeCode object representing an IDL array.
abstract TypeCode | ORB.create_enum_tc(String id, String name, String[] members) Creates a TypeCode object representing an IDL enum.
abstract TypeCode | ORB.create_exception_tc(String id, String name, StructMember[] members) Creates a TypeCode object representing an IDL exception.
TypeCode | ORB.create_fixed_tc(short digits, short scale) Create a TypeCode object for an IDL fixed type.
abstract TypeCode | ORB.create_interface_tc(String id, String name) Creates a TypeCode object representing an IDL interface.
TypeCode | ORB.create_native_tc(String id, String name) Create a TypeCode object for an IDL native type.
abstract TypeCode | ORB.create_recursive_sequence_tc(int bound, int offset) Deprecated. Use a combination of create_recursive_tc and create_sequence_tc instead
TypeCode | ORB.create_recursive_tc(String id) Create a recursive TypeCode object which serves as a placeholder for a concrete TypeCode during the process of creating TypeCodes which contain recursion.
abstract TypeCode | ORB.create_sequence_tc(int bound, TypeCode element_type) Creates a TypeCode object representing an IDL sequence.
abstract TypeCode | ORB.create_string_tc(int bound) Creates a TypeCode object representing a bounded IDL string.
abstract TypeCode | ORB.create_struct_tc(String id, String name, StructMember[] members) Creates a TypeCode object representing an IDL struct.
abstract TypeCode | ORB.create_union_tc(String id, String name, TypeCode discriminator_type, UnionMember[] members) Creates a TypeCode object representing an IDL union.
TypeCode | ORB.create_value_box_tc(String id, String name, TypeCode boxed_type) Creates a TypeCode object for an IDL value box.
TypeCode | ORB.create_value_tc(String id, String name, short type_modifier, TypeCode concrete_base, ValueMember[] members) Create a TypeCode object for an IDL value type.
abstract TypeCode | ORB.create_wstring_tc(int bound) Creates a TypeCode object representing a bounded IDL wstring (wide string).
abstract TypeCode | TypeCode.discriminator_type() Returns a TypeCode object describing all non-default member labels.
abstract TypeCode | Any.extract_TypeCode() Extracts the TypeCode object in this Any object's value field.
abstract TypeCode | TypeCode.get_compact_typecode() Strips out all optional name and member name fields, but leaves all alias typecodes intact.
abstract TypeCode | ORB.get_primitive_tc(TCKind tcKind) Retrieves the TypeCode object that represents the given primitive IDL type.
TypeCode | DynAny.get_typecode() Deprecated. Retrieves the org.omg.CORBA.TypeCode contained in this DynAny object.
abstract TypeCode | ExceptionList.item(int index) Returns the TypeCode object at the given index.
abstract TypeCode | TypeCode.member_type(int index) Retrieves the TypeCode object describing the type of the member identified by the given index.
TypeCode | DataInputStream.read_TypeCode() Reads an IDL typecode from the input stream.
static TypeCode | WStringSeqHelper.type()
static TypeCode | UnknownUserExceptionHelper.type()
static TypeCode | StringSeqHelper.type()
static TypeCode | PolicyErrorHelper.type()
static TypeCode | PolicyErrorCodeHelper.type()
static TypeCode | ParameterModeHelper.type()
TypeCode | _IDLTypeStub.type()
static TypeCode | WStringValueHelper.type()
static TypeCode | WCharSeqHelper.type()
static TypeCode | VisibilityHelper.type()
static TypeCode | VersionSpecHelper.type()
static TypeCode | ValueMemberHelper.type()
static TypeCode | ValueBaseHelper.type()
static TypeCode | UnionMemberHelper.type()
static TypeCode | UShortSeqHelper.type()
static TypeCode | ULongSeqHelper.type()
static TypeCode | ULongLongSeqHelper.type()
static TypeCode | StructMemberHelper.type()
static TypeCode | StringValueHelper.type()
static TypeCode | ShortSeqHelper.type()
static TypeCode | SetOverrideTypeHelper.type()
static TypeCode | RepositoryIdHelper.type()
static TypeCode | PolicyListHelper.type()
static TypeCode | PolicyTypeHelper.type()
static TypeCode | PolicyHelper.type()
static TypeCode | OctetSeqHelper.type()
static TypeCode | NameValuePairHelper.type()
static TypeCode | LongSeqHelper.type()
static TypeCode | LongLongSeqHelper.type()
static TypeCode | IdentifierHelper.type()
static TypeCode | IDLTypeHelper.type()
static TypeCode | FloatSeqHelper.type()
static TypeCode | FieldNameHelper.type()
static TypeCode | DoubleSeqHelper.type()
static TypeCode | DefinitionKindHelper.type()
static TypeCode | CurrentHelper.type()
static TypeCode | CompletionStatusHelper.type()
static TypeCode | CharSeqHelper.type()
static TypeCode | BooleanSeqHelper.type()
static TypeCode | AnySeqHelper.type()
static TypeCode | ObjectHelper.type()
static TypeCode | ServiceDetailHelper.type()
static TypeCode | ServiceInformationHelper.type()
static TypeCode | WrongTransactionHelper.type()
TypeCode | IDLTypeOperations.type() The type attribute describes the type defined by an object derived from IDLType.
TypeCode | DynAny.type() Deprecated. Returns the TypeCode of the object inserted into this DynAny.
abstract TypeCode | Any.type() Returns type information for the element contained in this Any object.

Methods in org.omg.CORBA with parameters of type TypeCode
abstract void | ExceptionList.add(TypeCode exc) Adds a TypeCode object describing an exception to this ExceptionList object.
abstract TypeCode | ORB.create_alias_tc(String id, String name, TypeCode original_type) Creates a TypeCode object representing an IDL alias (typedef).
abstract TypeCode | ORB.create_array_tc(int length, TypeCode element_type) Creates a TypeCode object representing an IDL array.
DynAny | ORB.create_basic_dyn_any(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
DynArray | ORB.create_dyn_array(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
DynEnum | ORB.create_dyn_enum(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
DynSequence | ORB.create_dyn_sequence(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
DynStruct | ORB.create_dyn_struct(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
DynUnion | ORB.create_dyn_union(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
abstract TypeCode | ORB.create_sequence_tc(int bound, TypeCode element_type) Creates a TypeCode object representing an IDL sequence.
abstract TypeCode | ORB.create_union_tc(String id, String name, TypeCode discriminator_type, UnionMember[] members) Creates a TypeCode object representing an IDL union.
TypeCode | ORB.create_value_box_tc(String id, String name, TypeCode boxed_type) Creates a TypeCode object for an IDL value box.
TypeCode | ORB.create_value_tc(String id, String name, short type_modifier, TypeCode concrete_base, ValueMember[] members) Create a TypeCode object for an IDL value type.
abstract boolean | TypeCode.equal(TypeCode tc) Compares this TypeCode object with the given one, testing for equality.
abstract boolean | TypeCode.equivalent(TypeCode tc) Tests to see if the given TypeCode object is equivalent to this TypeCode object.
void | Any.insert_fixed(BigDecimal value, TypeCode type) Throws an org.omg.CORBA.NO_IMPLEMENT exception.
abstract void | Any.insert_Object(Object o, TypeCode t) Inserts the given org.omg.CORBA.Object object into this Any object's value field.
void | DynAny.insert_typecode(TypeCode value) Deprecated. Inserts the given org.omg.CORBA.TypeCode as the value for this DynAny object.
abstract void | Any.insert_TypeCode(TypeCode t) Inserts the given TypeCode object into this Any object's value field.
abstract void | Any.insert_Value(Serializable v, TypeCode t) Inserts the given java.io.Serializable object into this Any object's value field.
abstract void | Any.read_value(InputStream is, TypeCode t) Reads off (unmarshals) the value of an Any object from the given input stream using the given typecode.
abstract void | Request.set_return_type(TypeCode tc) Sets the typecode for the return value of the method.
abstract void | Any.type(TypeCode t) Sets this Any object's type field to the given TypeCode object and clears its value.
void | DataOutputStream.write_TypeCode(TypeCode value) Writes the typecode to the output stream.

Constructors in org.omg.CORBA with parameters of type TypeCode
StructMember(String __name, TypeCode __type, IDLType __type_def)
Constructs a StructMember object initialized with the given values.
TypeCodeHolder(TypeCode initial)
Constructs a new TypeCodeHolder object with its value field initialized to the given TypeCode object.
UnionMember(String __name, Any __label, TypeCode __type, IDLType __type_def)
Constructs a new UnionMember object with its fields initialized to the given values.
ValueMember(String __name, String __id, String __defined_in, String __version, TypeCode __type, IDLType __type_def, short __access)
Constructs a ValueMember object initialized with the given values.

Uses of TypeCode in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable that return TypeCode
TypeCode | Streamable._type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
abstract TypeCode | InputStream.read_TypeCode() Reads a TypeCode from this input stream.

Methods in org.omg.CORBA.portable with parameters of type TypeCode
abstract  void OutputStream.write_TypeCode(TypeCode value)
Writes a TypeCode on this output stream.

Uses of TypeCode in org.omg.CosNaming

Methods in org.omg.CosNaming that return TypeCode
TypeCode | NamingContextExtHolder._type()
TypeCode | NamingContextHolder._type()
TypeCode | NameHolder._type()
TypeCode | NameComponentHolder._type()
TypeCode | BindingTypeHolder._type()
TypeCode | BindingIteratorHolder._type()
TypeCode | BindingListHolder._type()
TypeCode | BindingHolder._type()
static TypeCode | NamingContextExtHelper.type()
static TypeCode | NamingContextHelper.type()
static TypeCode | NameHelper.type()
static TypeCode | NameComponentHelper.type()
static TypeCode | BindingTypeHelper.type()
static TypeCode | BindingListHelper.type()
static TypeCode | BindingIteratorHelper.type()
static TypeCode | BindingHelper.type()
static TypeCode | IstringHelper.type()

Uses of TypeCode in org.omg.CosNaming.NamingContextExtPackage

Methods in org.omg.CosNaming.NamingContextExtPackage that return TypeCode
TypeCode | InvalidAddressHolder._type()
static TypeCode | URLStringHelper.type()
static TypeCode | StringNameHelper.type()
static TypeCode | InvalidAddressHelper.type()
static TypeCode | AddressHelper.type()

Uses of TypeCode in org.omg.CosNaming.NamingContextPackage

Methods in org.omg.CosNaming.NamingContextPackage that return TypeCode
TypeCode | NotFoundReasonHolder._type()
TypeCode | NotFoundHolder._type()
TypeCode | NotEmptyHolder._type()
TypeCode | InvalidNameHolder._type()
TypeCode | CannotProceedHolder._type()
TypeCode | AlreadyBoundHolder._type()
static TypeCode | NotFoundReasonHelper.type()
static TypeCode | NotFoundHelper.type()
static TypeCode | NotEmptyHelper.type()
static TypeCode | InvalidNameHelper.type()
static TypeCode | CannotProceedHelper.type()
static TypeCode | AlreadyBoundHelper.type()

Uses of TypeCode in org.omg.DynamicAny

Methods in org.omg.DynamicAny that return TypeCode
TypeCode | _DynSequenceStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynFixedStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynEnumStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynArrayStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynValueStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynAnyStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynUnionStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynStructStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | DynAnyOperations.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynSequenceStub.type() Returns the TypeCode associated with this DynAny object.
TypeCode | _DynFixedStub.type() Returns the TypeCode associated with this DynAny object.
TypeCode | _DynEnumStub.type() Returns the TypeCode associated with this DynAny object.
TypeCode | _DynArrayStub.type() Returns the TypeCode associated with this DynAny object.
TypeCode | _DynValueStub.type() Returns the TypeCode associated with this DynAny object.
TypeCode | _DynAnyStub.type() Returns the TypeCode associated with this DynAny object.
TypeCode | _DynUnionStub.type() Returns the TypeCode associated with this DynAny object.
TypeCode | _DynStructStub.type() Returns the TypeCode associated with this DynAny object.
static TypeCode | NameValuePairSeqHelper.type()
static TypeCode | NameValuePairHelper.type()
static TypeCode | NameDynAnyPairSeqHelper.type()
static TypeCode | DynSequenceHelper.type()
static TypeCode | NameDynAnyPairHelper.type()
static TypeCode | FieldNameHelper.type()
static TypeCode | DynFixedHelper.type()
static TypeCode | DynEnumHelper.type()
static TypeCode | DynAnySeqHelper.type()
static TypeCode | DynArrayHelper.type()
static TypeCode | DynValueHelper.type()
static TypeCode | DynAnyHelper.type()
static TypeCode | DynUnionHelper.type()
static TypeCode | DynAnyFactoryHelper.type()
static TypeCode | DynStructHelper.type()
static TypeCode | AnySeqHelper.type()
TypeCode | DynAnyOperations.type() Returns the TypeCode associated with this DynAny object.

Methods in org.omg.DynamicAny with parameters of type TypeCode
DynAny | _DynAnyFactoryStub.create_dyn_any_from_type_code(TypeCode type) Creates a DynAny from a TypeCode.
DynAny | DynAnyFactoryOperations.create_dyn_any_from_type_code(TypeCode type) Creates a DynAny from a TypeCode.
void | _DynSequenceStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynFixedStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynEnumStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynArrayStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynValueStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynAnyStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynUnionStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynStructStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | DynAnyOperations.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.

Uses of TypeCode in org.omg.DynamicAny.DynAnyFactoryPackage

Methods in org.omg.DynamicAny.DynAnyFactoryPackage that return TypeCode
static TypeCode InconsistentTypeCodeHelper.type()

Uses of TypeCode in org.omg.DynamicAny.DynAnyPackage

Methods in org.omg.DynamicAny.DynAnyPackage that return TypeCode
static TypeCode | TypeMismatchHelper.type()
static TypeCode | InvalidValueHelper.type()

Uses of TypeCode in org.omg.IOP

Methods in org.omg.IOP that return TypeCode
TypeCode | TaggedProfileHolder._type()
TypeCode | TaggedComponentHolder._type()
TypeCode | ServiceContextListHolder._type()
TypeCode | ServiceContextHolder._type()
TypeCode | MultipleComponentProfileHolder._type()
TypeCode | IORHolder._type()
static TypeCode | TaggedProfileHelper.type()
static TypeCode | TaggedComponentHelper.type()
static TypeCode | ServiceIdHelper.type()
static TypeCode | ServiceContextListHelper.type()
static TypeCode | ServiceContextHelper.type()
static TypeCode | ProfileIdHelper.type()
static TypeCode | MultipleComponentProfileHelper.type()
static TypeCode | IORHelper.type()
static TypeCode | ComponentIdHelper.type()
static TypeCode | CodecFactoryHelper.type()

Methods in org.omg.IOP with parameters of type TypeCode
 Any CodecOperations.decode_value(byte[] data, TypeCode tc)
Decodes the given byte array into an Any based on the given TypeCode and the encoding format effective for this Codec.

Uses of TypeCode in org.omg.IOP.CodecFactoryPackage

Methods in org.omg.IOP.CodecFactoryPackage that return TypeCode
static TypeCode UnknownEncodingHelper.type()

Uses of TypeCode in org.omg.IOP.CodecPackage

Methods in org.omg.IOP.CodecPackage that return TypeCode
static TypeCode | TypeMismatchHelper.type()
static TypeCode | InvalidTypeForEncodingHelper.type()
static TypeCode | FormatMismatchHelper.type()

Uses of TypeCode in org.omg.Messaging

Methods in org.omg.Messaging that return TypeCode
static TypeCode SyncScopeHelper.type()

Uses of TypeCode in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor that return TypeCode
TypeCode | ObjectReferenceTemplateSeqHolder._type()
TypeCode | ObjectReferenceTemplateHolder._type()
TypeCode | ObjectReferenceFactoryHolder._type()
TypeCode | IORInterceptor_3_0Holder._type()
TypeCode[] | RequestInfoOperations.exceptions() Returns an array of TypeCode objects describing the TypeCodes of the user exceptions that this operation invocation may throw.
static TypeCode | ServerIdHelper.type()
static TypeCode | ORBIdHelper.type()
static TypeCode | ObjectReferenceTemplateSeqHelper.type()
static TypeCode | ObjectReferenceTemplateHelper.type()
static TypeCode | ObjectReferenceFactoryHelper.type()
static TypeCode | ObjectIdHelper.type()
static TypeCode | InvalidSlotHelper.type()
static TypeCode | IORInterceptor_3_0Helper.type()
static TypeCode | ForwardRequestHelper.type()
static TypeCode | CurrentHelper.type()
static TypeCode | AdapterStateHelper.type()
static TypeCode | AdapterNameHelper.type()
static TypeCode | AdapterManagerIdHelper.type()

Uses of TypeCode in org.omg.PortableInterceptor.ORBInitInfoPackage

Methods in org.omg.PortableInterceptor.ORBInitInfoPackage that return TypeCode
static TypeCode | ObjectIdHelper.type()
static TypeCode | InvalidNameHelper.type()
static TypeCode | DuplicateNameHelper.type()

Uses of TypeCode in org.omg.PortableServer

Methods in org.omg.PortableServer that return TypeCode
static TypeCode | ServantLocatorHelper.type()
static TypeCode | ServantActivatorHelper.type()
static TypeCode | POAHelper.type()
static TypeCode | ForwardRequestHelper.type()
static TypeCode | CurrentHelper.type()

Uses of TypeCode in org.omg.PortableServer.CurrentPackage

Methods in org.omg.PortableServer.CurrentPackage that return TypeCode
static TypeCode NoContextHelper.type()

Uses of TypeCode in org.omg.PortableServer.POAManagerPackage

Methods in org.omg.PortableServer.POAManagerPackage that return TypeCode
static TypeCode AdapterInactiveHelper.type()

Uses of TypeCode in org.omg.PortableServer.POAPackage

Methods in org.omg.PortableServer.POAPackage that return TypeCode
static TypeCode | WrongPolicyHelper.type()
static TypeCode | WrongAdapterHelper.type()
static TypeCode | ServantNotActiveHelper.type()
static TypeCode | ServantAlreadyActiveHelper.type()
static TypeCode | ObjectNotActiveHelper.type()
static TypeCode | ObjectAlreadyActiveHelper.type()
static TypeCode | NoServantHelper.type()
static TypeCode | InvalidPolicyHelper.type()
static TypeCode | AdapterNonExistentHelper.type()
static TypeCode | AdapterAlreadyExistsHelper.type()

Uses of TypeCode in org.omg.PortableServer.ServantLocatorPackage

Methods in org.omg.PortableServer.ServantLocatorPackage that return TypeCode
 TypeCode CookieHolder._type()

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.TypeCodeHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.TypeCodeHolder

No usage of org.omg.CORBA.TypeCodeHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ULongLongSeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ULongLongSeqHelper

No usage of org.omg.CORBA.ULongLongSeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ULongLongSeqHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ULongLongSeqHolder

Packages that use ULongLongSeqHolder
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of ULongLongSeqHolder in org.omg.CORBA

Methods in org.omg.CORBA with parameters of type ULongLongSeqHolder
 void DataInputStream.read_ulonglong_array(ULongLongSeqHolder seq, int offset, int length)
Reads array of IDL unsigned long longs from offset for length elements from the input stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ULongSeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ULongSeqHelper

No usage of org.omg.CORBA.ULongSeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ULongSeqHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ULongSeqHolder

Packages that use ULongSeqHolder
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of ULongSeqHolder in org.omg.CORBA

Methods in org.omg.CORBA with parameters of type ULongSeqHolder
 void DataInputStream.read_ulong_array(ULongSeqHolder seq, int offset, int length)
Reads array of IDL unsigned longs from offset for length elements from the input stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.UnionMember

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.UnionMember

Packages that use UnionMember
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of UnionMember in org.omg.CORBA

Methods in org.omg.CORBA that return UnionMember
static UnionMember | UnionMemberHelper.extract(Any a)
static UnionMember | UnionMemberHelper.read(InputStream istream)

Methods in org.omg.CORBA with parameters of type UnionMember
abstract TypeCode | ORB.create_union_tc(String id, String name, TypeCode discriminator_type, UnionMember[] members) Creates a TypeCode object representing an IDL union.
static void | UnionMemberHelper.insert(Any a, UnionMember that)
static void | UnionMemberHelper.write(OutputStream ostream, UnionMember value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.UnionMemberHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.UnionMemberHelper

No usage of org.omg.CORBA.UnionMemberHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.UNKNOWN

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.UNKNOWN

No usage of org.omg.CORBA.UNKNOWN

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.UnknownUserException

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.UnknownUserException

Packages that use UnknownUserException
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of UnknownUserException in org.omg.CORBA

Fields in org.omg.CORBA declared as UnknownUserException
 UnknownUserException UnknownUserExceptionHolder.value

Methods in org.omg.CORBA that return UnknownUserException
static UnknownUserException | UnknownUserExceptionHelper.extract(Any a)
static UnknownUserException | UnknownUserExceptionHelper.read(InputStream istream)

Methods in org.omg.CORBA with parameters of type UnknownUserException
static void | UnknownUserExceptionHelper.insert(Any a, UnknownUserException that)
static void | UnknownUserExceptionHelper.write(OutputStream ostream, UnknownUserException value)

Constructors in org.omg.CORBA with parameters of type UnknownUserException
UnknownUserExceptionHolder(UnknownUserException initialValue)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.UnknownUserExceptionHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.UnknownUserExceptionHelper

No usage of org.omg.CORBA.UnknownUserExceptionHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.UnknownUserExceptionHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.UnknownUserExceptionHolder

No usage of org.omg.CORBA.UnknownUserExceptionHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.UserException

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.UserException

Packages that use UserException
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.DynAnyPackage | Provides the exceptions used with the DynAny interface (InvalidValue, Invalid, InvalidSeq, and TypeMismatch).
org.omg.CORBA.ORBPackage | Provides the exception InvalidName, which is thrown by the method ORB.resolve_initial_references and the exception InconsistentTypeCode, which is thrown by the Dynamic Any creation methods in the ORB class.
org.omg.CORBA.TypeCodePackage | Provides the user-defined exceptions BadKind and Bounds, which are thrown by methods in in the class TypeCode.
org.omg.CosNaming.NamingContextExtPackage | This package contains the following classes, which are used in org.omg.CosNaming.NamingContextExt:
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.
org.omg.IOP.CodecFactoryPackage | This package contains the exceptions specified in the IOP::CodeFactory interface (as part of the Portable Interceptors spec).
org.omg.IOP.CodecPackage | This package is generated from the IOP::Codec IDL interface definition.
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.
org.omg.PortableInterceptor.ORBInitInfoPackage | This package contains the exceptions and typedefs from the ORBInitInfo local interface of the PortableInterceptor module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.7.2.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.CurrentPackage | Provides method implementations with access to the identity of the object on which the method was invoked.
org.omg.PortableServer.POAManagerPackage | Encapsulates the processing state of the POAs it is associated with.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.

Uses of UserException in org.omg.CORBA

Subclasses of UserException in org.omg.CORBA
class | Bounds A user exception thrown when a parameter is not within the legal bounds for the object that a method is trying to access.
class | PolicyError A user exception thrown when a policy error occurs.
class | UnknownUserException A class that contains user exceptions returned by the server.
class | WrongTransaction The CORBA WrongTransaction user-defined exception.

Uses of UserException in org.omg.CORBA.DynAnyPackage

Subclasses of UserException in org.omg.CORBA.DynAnyPackage
class | Invalid Invalid is thrown by dynamic any operations when a bad DynAny or Any is passed as a parameter.
class | InvalidSeq The InvalidSeq exception is thrown by all operations on dynamic anys that take a sequence (Java array) as an argument, when that sequence is invalid.
class | InvalidValue
class | TypeMismatch TypeMismatch is thrown by dynamic any accessor methods when type of the actual contents do not match what is trying to be accessed.

Uses of UserException in org.omg.CORBA.ORBPackage

Subclasses of UserException in org.omg.CORBA.ORBPackage
class | InconsistentTypeCode InconsistentTypeCode is thrown when an attempt is made to create a dynamic any with a type code that does not match the particular subclass of DynAny.
class | InvalidName The InvalidName exception is raised when ORB.resolve_initial_references is passed a name for which there is no initial reference.

Uses of UserException in org.omg.CORBA.TypeCodePackage

Subclasses of UserException in org.omg.CORBA.TypeCodePackage
 class BadKind
The exception BadKind is thrown when an inappropriate operation is invoked on a TypeCode object.

Uses of UserException in org.omg.CosNaming.NamingContextExtPackage

Subclasses of UserException in org.omg.CosNaming.NamingContextExtPackage
 class InvalidAddress
org/omg/CosNaming/NamingContextExtPackage/InvalidAddress.java .

Uses of UserException in org.omg.CosNaming.NamingContextPackage

Subclasses of UserException in org.omg.CosNaming.NamingContextPackage
class | AlreadyBound org/omg/CosNaming/NamingContextPackage/AlreadyBound.java .
class | CannotProceed org/omg/CosNaming/NamingContextPackage/CannotProceed.java .
class | NotEmpty org/omg/CosNaming/NamingContextPackage/NotEmpty.java .
class | NotFound org/omg/CosNaming/NamingContextPackage/NotFound.java .

Uses of UserException in org.omg.IOP.CodecFactoryPackage

Subclasses of UserException in org.omg.IOP.CodecFactoryPackage
 class UnknownEncoding
org/omg/IOP/CodecFactoryPackage/UnknownEncoding.java .

Uses of UserException in org.omg.IOP.CodecPackage

Subclasses of UserException in org.omg.IOP.CodecPackage
class | FormatMismatch org/omg/IOP/CodecPackage/FormatMismatch.java .
class | InvalidTypeForEncoding org/omg/IOP/CodecPackage/InvalidTypeForEncoding.java .

Uses of UserException in org.omg.PortableInterceptor

Subclasses of UserException in org.omg.PortableInterceptor
 class InvalidSlot
org/omg/PortableInterceptor/InvalidSlot.java .

Uses of UserException in org.omg.PortableInterceptor.ORBInitInfoPackage

Subclasses of UserException in org.omg.PortableInterceptor.ORBInitInfoPackage
 class DuplicateName
org/omg/PortableInterceptor/ORBInitInfoPackage/DuplicateName.java .

Uses of UserException in org.omg.PortableServer

Subclasses of UserException in org.omg.PortableServer
 class ForwardRequest
org/omg/PortableServer/ForwardRequest.java .

Uses of UserException in org.omg.PortableServer.CurrentPackage

Subclasses of UserException in org.omg.PortableServer.CurrentPackage
 class NoContext
org/omg/PortableServer/CurrentPackage/NoContext.java .

Uses of UserException in org.omg.PortableServer.POAManagerPackage

Subclasses of UserException in org.omg.PortableServer.POAManagerPackage
 class AdapterInactive
org/omg/PortableServer/POAManagerPackage/AdapterInactive.java .

Uses of UserException in org.omg.PortableServer.POAPackage

Subclasses of UserException in org.omg.PortableServer.POAPackage
class | AdapterAlreadyExists org/omg/PortableServer/POAPackage/AdapterAlreadyExists.java .
class | AdapterNonExistent org/omg/PortableServer/POAPackage/AdapterNonExistent.java .
class | InvalidPolicy org/omg/PortableServer/POAPackage/InvalidPolicy.java .
class | NoServant org/omg/PortableServer/POAPackage/NoServant.java .
class | ObjectAlreadyActive org/omg/PortableServer/POAPackage/ObjectAlreadyActive.java .
class | ObjectNotActive org/omg/PortableServer/POAPackage/ObjectNotActive.java .
class | ServantAlreadyActive org/omg/PortableServer/POAPackage/ServantAlreadyActive.java .
class | ServantNotActive org/omg/PortableServer/POAPackage/ServantNotActive.java .
class | WrongAdapter org/omg/PortableServer/POAPackage/WrongAdapter.java .
class | WrongPolicy org/omg/PortableServer/POAPackage/WrongPolicy.java .

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.UShortSeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.UShortSeqHelper

No usage of org.omg.CORBA.UShortSeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.UShortSeqHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.UShortSeqHolder

Packages that use UShortSeqHolder
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of UShortSeqHolder in org.omg.CORBA

Methods in org.omg.CORBA with parameters of type UShortSeqHolder
 void DataInputStream.read_ushort_array(UShortSeqHolder seq, int offset, int length)
Reads array of IDL unsigned shorts from offset for length elements from the input stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ValueBaseHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ValueBaseHelper

No usage of org.omg.CORBA.ValueBaseHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ValueBaseHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ValueBaseHolder

No usage of org.omg.CORBA.ValueBaseHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ValueMember

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ValueMember

Packages that use ValueMember
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of ValueMember in org.omg.CORBA

Methods in org.omg.CORBA that return ValueMember
static ValueMember | ValueMemberHelper.extract(Any a)
static ValueMember | ValueMemberHelper.read(InputStream istream)

Methods in org.omg.CORBA with parameters of type ValueMember
TypeCode | ORB.create_value_tc(String id, String name, short type_modifier, TypeCode concrete_base, ValueMember[] members) Create a TypeCode object for an IDL value type.
static void | ValueMemberHelper.insert(Any a, ValueMember that)
static void | ValueMemberHelper.write(OutputStream ostream, ValueMember value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ValueMemberHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ValueMemberHelper

No usage of org.omg.CORBA.ValueMemberHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.VersionSpecHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.VersionSpecHelper

No usage of org.omg.CORBA.VersionSpecHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.VisibilityHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.VisibilityHelper

No usage of org.omg.CORBA.VisibilityHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.WCharSeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.WCharSeqHelper

No usage of org.omg.CORBA.WCharSeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.WCharSeqHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.WCharSeqHolder

Packages that use WCharSeqHolder
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of WCharSeqHolder in org.omg.CORBA

Methods in org.omg.CORBA with parameters of type WCharSeqHolder
 void DataInputStream.read_wchar_array(WCharSeqHolder seq, int offset, int length)
Reads array of IDL wide characters from offset for length elements from the input stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.WrongTransaction

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.WrongTransaction

Packages that use WrongTransaction
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of WrongTransaction in org.omg.CORBA

Fields in org.omg.CORBA declared as WrongTransaction
 WrongTransaction WrongTransactionHolder.value

Methods in org.omg.CORBA that return WrongTransaction
static WrongTransaction | WrongTransactionHelper.extract(Any a)
static WrongTransaction | WrongTransactionHelper.read(InputStream istream)

Methods in org.omg.CORBA with parameters of type WrongTransaction
static void | WrongTransactionHelper.insert(Any a, WrongTransaction that)
static void | WrongTransactionHelper.write(OutputStream ostream, WrongTransaction value)

Methods in org.omg.CORBA that throw WrongTransaction
abstract Request | ORB.get_next_response() Gets the next Request instance for which a response has been received.
abstract void | Request.get_response() Allows the user to access the response for the invocation triggered earlier with the send_deferred method.

Constructors in org.omg.CORBA with parameters of type WrongTransaction
WrongTransactionHolder(WrongTransaction initialValue)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.WrongTransactionHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.WrongTransactionHelper

No usage of org.omg.CORBA.WrongTransactionHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.WrongTransactionHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.WrongTransactionHolder

No usage of org.omg.CORBA.WrongTransactionHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.WStringSeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.WStringSeqHelper

No usage of org.omg.CORBA.WStringSeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.WStringSeqHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.WStringSeqHolder

No usage of org.omg.CORBA.WStringSeqHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.WStringValueHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.WStringValueHelper

No usage of org.omg.CORBA.WStringValueHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA._IDLTypeStub

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA._IDLTypeStub

No usage of org.omg.CORBA._IDLTypeStub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA._PolicyStub

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA._PolicyStub

No usage of org.omg.CORBA._PolicyStub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.ARG_IN

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.ARG_IN

No usage of org.omg.CORBA.ARG_IN

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.ARG_INOUT

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.ARG_INOUT

No usage of org.omg.CORBA.ARG_INOUT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.ARG_OUT

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.ARG_OUT

No usage of org.omg.CORBA.ARG_OUT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.BAD_POLICY

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.BAD_POLICY

No usage of org.omg.CORBA.BAD_POLICY

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.BAD_POLICY_TYPE

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.BAD_POLICY_TYPE

No usage of org.omg.CORBA.BAD_POLICY_TYPE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.BAD_POLICY_VALUE

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.BAD_POLICY_VALUE

No usage of org.omg.CORBA.BAD_POLICY_VALUE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.CTX_RESTRICT_SCOPE

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.CTX_RESTRICT_SCOPE

No usage of org.omg.CORBA.CTX_RESTRICT_SCOPE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.Current

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.Current

Packages that use Current
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of Current in org.omg.CORBA

Fields in org.omg.CORBA declared as Current
 Current CurrentHolder.value

Methods in org.omg.CORBA that return Current
static Current | CurrentHelper.extract(Any a)
Current | ORB.get_current() Deprecated. use resolve_initial_references.
static Current | CurrentHelper.narrow(Object obj)
static Current | CurrentHelper.read(InputStream istream)

Methods in org.omg.CORBA with parameters of type Current
static void | CurrentHelper.insert(Any a, Current that)
static void | CurrentHelper.write(OutputStream ostream, Current value)

Constructors in org.omg.CORBA with parameters of type Current
CurrentHolder(Current initialValue)

Uses of Current in org.omg.PortableServer

Subinterfaces of Current in org.omg.PortableServer
 interface Current
The PortableServer::Current interface, derived from CORBA::Current, provides method implementations with access to the identity of the object on which the method was invoked.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.CurrentOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.CurrentOperations

Packages that use CurrentOperations
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of CurrentOperations in org.omg.CORBA

Subinterfaces of CurrentOperations in org.omg.CORBA
 interface Current
Interfaces derived from the Current interface enable ORB and CORBA services to provide access to information (context) associated with the thread of execution in which they are running.

Uses of CurrentOperations in org.omg.PortableServer

Subinterfaces of CurrentOperations in org.omg.PortableServer
 interface CurrentOperations
The PortableServer::Current interface, derived from CORBA::Current, provides method implementations with access to the identity of the object on which the method was invoked.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.CustomMarshal

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.CustomMarshal

Packages that use CustomMarshal
org.omg.CORBA.portable Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.

Uses of CustomMarshal in org.omg.CORBA.portable

Subinterfaces of CustomMarshal in org.omg.CORBA.portable
 interface CustomValue
An extension of ValueBase that is implemented by custom value types.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.DataInputStream

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.DataInputStream

Packages that use DataInputStream
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of DataInputStream in org.omg.CORBA

Methods in org.omg.CORBA with parameters of type DataInputStream
 void CustomMarshal.unmarshal(DataInputStream is)
Unmarshal method has to be implemented by the Customized Marshal class.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.DataOutputStream

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.DataOutputStream

Packages that use DataOutputStream
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of DataOutputStream in org.omg.CORBA

Methods in org.omg.CORBA with parameters of type DataOutputStream
 void CustomMarshal.marshal(DataOutputStream os)
Marshal method has to be implemented by the Customized Marshal class.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.DomainManager

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.DomainManager

Packages that use DomainManager
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.

Uses of DomainManager in org.omg.CORBA

Methods in org.omg.CORBA that return DomainManager
DomainManager[] | LocalObject._get_domain_managers() Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented.
DomainManager[] | Object._get_domain_managers() Retrieves the DomainManagers of this object.

Uses of DomainManager in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable that return DomainManager
DomainManager[] | ObjectImpl._get_domain_managers() Retrieves a list of the domain managers for this ObjectImpl object.
DomainManager[] | Delegate.get_domain_managers(Object self) Retrieves the DomainManagers of this object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.DomainManagerOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.DomainManagerOperations

Packages that use DomainManagerOperations
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of DomainManagerOperations in org.omg.CORBA

Subinterfaces of DomainManagerOperations in org.omg.CORBA
 interface DomainManager
Provides mechanisms for establishing and navigating relationships to superior and subordinate domains, as well as for creating and accessing policies.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.DynAny

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.DynAny

Packages that use DynAny
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of DynAny in org.omg.CORBA

Subinterfaces of DynAny in org.omg.CORBA
interface | DynArray Deprecated. Use the new DynArray instead
interface | DynEnum Deprecated. Use the new DynEnum instead
interface | DynFixed Deprecated. Use the new DynFixed instead
interface | DynSequence Deprecated. Use the new DynSequence instead
interface | DynStruct Deprecated. Use the new DynStruct instead
interface | DynUnion Deprecated. Use the new DynUnion instead
interface | DynValue Deprecated. Use the new DynValue instead

Methods in org.omg.CORBA that return DynAny
DynAny | DynAny.copy() Deprecated. Clones this DynAny object.
DynAny | ORB.create_basic_dyn_any(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
DynAny | ORB.create_dyn_any(Any value) Deprecated. Use the new DynAnyFactory API instead
DynAny | DynAny.current_component() Deprecated. Returns a DynAny object reference that can be used to get/set the value of the component currently accessed.
DynAny | DynUnion.discriminator() Deprecated. Returns a DynAny object reference that must be narrowed to the type of the discriminator in order to insert/get the discriminator value.
DynAny | DynUnion.member() Deprecated. Returns a DynAny object reference that is used in order to insert/get a member of this union.

Methods in org.omg.CORBA with parameters of type DynAny
 void DynAny.assign(DynAny dyn_any)
Deprecated. Copy the contents from one Dynamic Any into another.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.DynArray

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.DynArray

Packages that use DynArray
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of DynArray in org.omg.CORBA

Methods in org.omg.CORBA that return DynArray
 DynArray ORB.create_dyn_array(TypeCode type)
Deprecated. Use the new DynAnyFactory API instead

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.DynEnum

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.DynEnum

Packages that use DynEnum
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of DynEnum in org.omg.CORBA

Methods in org.omg.CORBA that return DynEnum
 DynEnum ORB.create_dyn_enum(TypeCode type)
Deprecated. Use the new DynAnyFactory API instead

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.DynFixed

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.DynFixed

No usage of org.omg.CORBA.DynFixed

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.DynSequence

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.DynSequence

Packages that use DynSequence
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of DynSequence in org.omg.CORBA

Methods in org.omg.CORBA that return DynSequence
 DynSequence ORB.create_dyn_sequence(TypeCode type)
Deprecated. Use the new DynAnyFactory API instead

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.DynStruct

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.DynStruct

Packages that use DynStruct
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of DynStruct in org.omg.CORBA

Methods in org.omg.CORBA that return DynStruct
 DynStruct ORB.create_dyn_struct(TypeCode type)
Deprecated. Use the new DynAnyFactory API instead

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.DynUnion

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.DynUnion

Packages that use DynUnion
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of DynUnion in org.omg.CORBA

Methods in org.omg.CORBA that return DynUnion
 DynUnion ORB.create_dyn_union(TypeCode type)
Deprecated. Use the new DynAnyFactory API instead

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.DynValue

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.DynValue

No usage of org.omg.CORBA.DynValue

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.IDLType

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.IDLType

Packages that use IDLType
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of IDLType in org.omg.CORBA

Classes in org.omg.CORBA that implement IDLType
 class _IDLTypeStub
The Stub for IDLType.

Fields in org.omg.CORBA declared as IDLType
IDLType | ValueMember.type_def The typedef that represents the IDL type of the value member described by this ValueMember object.
IDLType | UnionMember.type_def The typedef that represents the IDL type of the union member described by this UnionMember object.
IDLType | StructMember.type_def The typedef that represents the IDL type of the struct member described by this StructMember object.

Methods in org.omg.CORBA that return IDLType
static IDLType | IDLTypeHelper.extract(Any a)
static IDLType | IDLTypeHelper.narrow(Object obj)
static IDLType | IDLTypeHelper.read(InputStream istream)

Methods in org.omg.CORBA with parameters of type IDLType
static void | IDLTypeHelper.insert(Any a, IDLType that)
static void | IDLTypeHelper.write(OutputStream ostream, IDLType value)

Constructors in org.omg.CORBA with parameters of type IDLType
StructMember(String __name, TypeCode __type, IDLType __type_def)
Constructs a StructMember object initialized with the given values.
UnionMember(String __name, Any __label, TypeCode __type, IDLType __type_def)
Constructs a new UnionMember object with its fields initialized to the given values.
ValueMember(String __name, String __id, String __defined_in, String __version, TypeCode __type, IDLType __type_def, short __access)
Constructs a ValueMember object initialized with the given values.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.IDLTypeOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.IDLTypeOperations

Packages that use IDLTypeOperations
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of IDLTypeOperations in org.omg.CORBA

Subinterfaces of IDLTypeOperations in org.omg.CORBA
 interface IDLType
An abstract interface inherited by all Interface Repository (IR) objects that represent OMG IDL types.

Classes in org.omg.CORBA that implement IDLTypeOperations
 class _IDLTypeStub
The Stub for IDLType.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.IRObject

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.IRObject

Packages that use IRObject
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of IRObject in org.omg.CORBA

Subinterfaces of IRObject in org.omg.CORBA
 interface IDLType
An abstract interface inherited by all Interface Repository (IR) objects that represent OMG IDL types.

Classes in org.omg.CORBA that implement IRObject
 class _IDLTypeStub
The Stub for IDLType.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.IRObjectOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.IRObjectOperations

Packages that use IRObjectOperations
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of IRObjectOperations in org.omg.CORBA

Subinterfaces of IRObjectOperations in org.omg.CORBA
interface | IDLType An abstract interface inherited by all Interface Repository (IR) objects that represent OMG IDL types.
interface | IDLTypeOperations This interface must be implemented by all IDLType objects.
interface | IRObject An IRObject IDL interface represents the most generic interface from which all other Interface Repository interfaces are derived, even the Repository itself.

Classes in org.omg.CORBA that implement IRObjectOperations
 class _IDLTypeStub
The Stub for IDLType.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.Object

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.Object

Packages that use Object
javax.rmi.CORBA | Contains portability APIs for RMI-IIOP.
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA_2_3 | The CORBA_2_3 package defines additions to existing CORBA interfaces in the Java[tm] Standard Edition 6. These changes occurred in recent revisions to the CORBA API defined by the OMG. The new methods were added to interfaces derived from the corresponding interfaces in the CORBA package. This provides backward compatibility and avoids breaking the JCK tests.
org.omg.CORBA_2_3.portable | Provides methods for the input and output of value types, and contains other updates to the org/omg/CORBA/portable package.
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.DynamicAny | Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.portable | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.SendingContext | Provides support for the marshalling of value types.
org.omg.stub.java.rmi | Contains RMI-IIOP Stubs for the Remote types that occur in the java.rmi package.

Uses of Object in javax.rmi.CORBA

Classes in javax.rmi.CORBA that implement Object
 class Stub
Base class from which all RMI-IIOP stubs must inherit.

Methods in javax.rmi.CORBA that return Object
 Object Tie.thisObject()
Returns an object reference for the target object represented by this tie.

Uses of Object in org.omg.CORBA

Subinterfaces of Object in org.omg.CORBA
interface | Current Interfaces derived from the Current interface enable ORB and CORBA services to provide access to information (context) associated with the thread of execution in which they are running.
interface | DomainManager Provides mechanisms for establishing and navigating relationships to superior and subordinate domains, as well as for creating and accessing policies.
interface | DynAny Deprecated. Use the new DynAny instead
interface | DynArray Deprecated. Use the new DynArray instead
interface | DynEnum Deprecated. Use the new DynEnum instead
interface | DynFixed Deprecated. Use the new DynFixed instead
interface | DynSequence Deprecated. Use the new DynSequence instead
interface | DynStruct Deprecated. Use the new DynStruct instead
interface | DynUnion Deprecated. Use the new DynUnion instead
interface | DynValue Deprecated. Use the new DynValue instead
interface | IDLType An abstract interface inherited by all Interface Repository (IR) objects that represent OMG IDL types.
interface | IRObject An IRObject IDL interface represents the most generic interface from which all other Interface Repository interfaces are derived, even the Repository itself.
interface | Policy Interfaces derived from the Policy interface allow an ORB or CORBA service access to certain choices that affect its operation.

Classes in org.omg.CORBA that implement Object
class | _IDLTypeStub The Stub for IDLType.
class | _PolicyStub The Stub for Policy.
class | DynamicImplementation Deprecated. org.omg.CORBA.DynamicImplementation
class | LocalObject Used as a base class for implementation of a local IDL interface in the Java language mapping.

Fields in org.omg.CORBA declared as Object
 Object ObjectHolder.value
The Object value held by this ObjectHolder object.

Methods in org.omg.CORBA that return Object
 Object LocalObject._duplicate()
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
 Object Object._duplicate()
Returns a duplicate of this CORBA object reference.
 Object LocalObject._get_interface_def()
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
 Object Object._get_interface_def()
Obtains an InterfaceDef for the object implementation referenced by this object reference.
 Object LocalObject._get_interface()
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented.
 Object LocalObject._set_policy_override(Policy[] policies, SetOverrideType set_add)
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented.
 Object Object._set_policy_override(Policy[] policies, SetOverrideType set_add)
Returns a new Object with the given policies either replacing any existing policies in this Object or with the given policies added to the existing ones, depending on the value of the given SetOverrideType object.
abstract  Object Any.extract_Object()
Extracts the org.omg.CORBA.Object in this Any object's value field.
static Object ObjectHelper.extract(Any a)
 Object DynAny.get_reference()
Deprecated. Retrieves the org.omg.CORBA.Other contained in this DynAny object.
 Object DataInputStream.read_Object()
Reads an IDL CORBA::Object from the input stream.
static Object ObjectHelper.read(InputStream istream)
abstract  Object ORB.resolve_initial_references(String object_name)
Resolves a specific object reference from the set of available initial service names.
abstract  Object ORB.string_to_object(String str)
Converts a string produced by the method object_to_string back to a CORBA object reference.
abstract  Object Request.target()
Retrieves the the target object reference.

Methods in org.omg.CORBA with parameters of type Object
 boolean LocalObject._is_equivalent(Object that)
Determines whether the two object references are equivalent, so far as the ORB can easily determine.
 boolean Object._is_equivalent(Object other)
Determines whether the two object references are equivalent, so far as the ORB can easily determine.
 void ORB.connect(Object obj)
Connects the given servant object (a Java object that is an instance of the server implementation class) to the ORB.
 NVList ORB.create_operation_list(Object oper)
Creates an NVList initialized with argument descriptions for the operation described in the given OperationDef object.
 void ORB.disconnect(Object obj)
Disconnects the given servant object from the ORB.
abstract  void Any.insert_Object(Object o)
Inserts the given org.omg.CORBA.Object object into this Any object's value field.
abstract  void Any.insert_Object(Object o, TypeCode t)
Inserts the given org.omg.CORBA.Object object into this Any object's value field.
 void DynAny.insert_reference(Object value)
Deprecated. Inserts the given org.omg.CORBA.Object as the value for this DynAny object.
static void ObjectHelper.insert(Any a, Object that)
static Policy PolicyHelper.narrow(Object obj)
static IDLType IDLTypeHelper.narrow(Object obj)
static Current CurrentHelper.narrow(Object obj)
abstract  String ORB.object_to_string(Object obj)
Converts the given CORBA object reference to a string.
 void DataOutputStream.write_Object(Object value)
Writes the IDL CORBA::Object value to the output stream.
static void ObjectHelper.write(OutputStream ostream, Object value)

Constructors in org.omg.CORBA with parameters of type Object
ObjectHolder(Object initial)
Constructs a new ObjectHolder object with its value field initialized to the given Object.

Uses of Object in org.omg.CORBA_2_3

Methods in org.omg.CORBA_2_3 that return Object
 Object ORB.get_value_def(String repid)

Uses of Object in org.omg.CORBA_2_3.portable

Methods in org.omg.CORBA_2_3.portable with parameters of type Object
 String Delegate.get_codebase(Object self)
Returns the codebase for object reference provided.

Uses of Object in org.omg.CORBA.portable

Classes in org.omg.CORBA.portable that implement Object
 class ObjectImpl
The common base class for all stub classes; provides default implementations of the org.omg.CORBA.Object methods.

Methods in org.omg.CORBA.portable that return Object
Object | ObjectImpl._duplicate() Returns a duplicate of this ObjectImpl object.
Object | ObjectImpl._get_interface_def() Retrieves the interface definition for this ObjectImpl object.
Object | ObjectImpl._set_policy_override(Policy[] policies, SetOverrideType set_add) Sets this ObjectImpl object's override type for the given policies to the given instance of SetOverrideType.
abstract Object | Delegate.duplicate(Object obj) Returns a duplicate of the object reference provided.
abstract Object | Delegate.get_interface_def(Object self) Return an InterfaceDef for the object reference provided.
abstract Object | InputStream.read_Object() Reads a CORBA object from this input stream.
Object | InputStream.read_Object(Class clz) Unmarshals an object and returns a CORBA Object, which is an instance of the class passed as its argument.
Object | Delegate.set_policy_override(Object self, Policy[] policies, SetOverrideType set_add) Associates the policies passed in with a newly created object reference that it returns.

Methods in org.omg.CORBA.portable with parameters of type Object
 boolean ObjectImpl._is_equivalent(Object that)
Checks whether the the given ObjectImpl object is equivalent to this ObjectImpl object.
abstract  Request Delegate.create_request(Object obj, Context ctx, String operation, NVList arg_list, NamedValue result)
Creates a Request instance for use in the Dynamic Invocation Interface.
abstract  Request Delegate.create_request(Object obj, Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exclist, ContextList ctxlist)
Creates a Request instance for use in the Dynamic Invocation Interface.
abstract  Object Delegate.duplicate(Object obj)
Returns a duplicate of the object reference provided.
 boolean Delegate.equals(Object self, Object obj)
Provides the implementation to override the equals(java.lang.Object obj) method of the delegating CORBA object.
 DomainManager[] Delegate.get_domain_managers(Object self)
Retrieves the DomainManagers of this object.
abstract  Object Delegate.get_interface_def(Object self)
Return an InterfaceDef for the object reference provided.
 Policy Delegate.get_policy(Object self, int policy_type)
Returns the Policy object of the specified type which applies to this object.
abstract  int Delegate.hash(Object obj, int max)
Returns an ORB-internal identifier (hashcode) for this object reference.
 int Delegate.hashCode(Object self)
Provides the implementation to override the hashCode() method of the delegating CORBA object.
 InputStream Delegate.invoke(Object self, OutputStream output)
invoke is called by a stub to invoke an operation.
abstract  boolean Delegate.is_a(Object obj, String repository_id)
Checks if the object reference is an instance of the given interface.
abstract  boolean Delegate.is_equivalent(Object obj, Object other)
Determines if the two object references are equivalent.
 boolean Delegate.is_local(Object self)
Returns true if this object is implemented by a local servant.
abstract  boolean Delegate.non_existent(Object obj)
Determines whether the server object for the object reference has been destroyed.
 ORB Delegate.orb(Object obj)
Provides a reference to the orb associated with its parameter.
abstract  void Delegate.release(Object obj)
Releases resources associated with the object reference provided.
 void Delegate.releaseReply(Object self, InputStream input)
releaseReply may optionally be called by a stub to release a reply stream back to the ORB when the unmarshaling has completed.
abstract  Request Delegate.request(Object obj, String operation)
Creates a Request instance for use in the Dynamic Invocation Interface.
 OutputStream Delegate.request(Object self, String operation, boolean responseExpected)
request is called by a stub to obtain an OutputStream for marshaling arguments.
 void Delegate.servant_postinvoke(Object self, ServantObject servant)
servant_postinvoke() is invoked by the local stub after the operation has been invoked on the local servant.
 ServantObject Delegate.servant_preinvoke(Object self, String operation, Class expectedType)
Returns a Java reference to the servant which should be used for this request.
 Object Delegate.set_policy_override(Object self, Policy[] policies, SetOverrideType set_add)
Associates the policies passed in with a newly created object reference that it returns.
 String Delegate.toString(Object self)
Provides the implementation to override the toString() method of the delegating CORBA object.
abstract  void OutputStream.write_Object(Object value)
Writes a CORBA Object on this output stream.

Uses of Object in org.omg.CosNaming

Subinterfaces of Object in org.omg.CosNaming
interface | BindingIterator The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
interface | NamingContext A naming context is an object that contains a set of name bindings in which each name is unique.
interface | NamingContextExt NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.

Classes in org.omg.CosNaming that implement Object
class | _BindingIteratorImplBase
class | _BindingIteratorStub The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
class | _NamingContextExtStub NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
class | _NamingContextImplBase
class | _NamingContextStub A naming context is an object that contains a set of name bindings in which each name is unique.

Methods in org.omg.CosNaming that return Object
Object | _NamingContextExtStub.resolve_str(String sn) This operation resolves the Stringified name into the object reference.
Object | NamingContextExtOperations.resolve_str(String sn) This operation resolves the Stringified name into the object reference.
Object | _NamingContextExtStub.resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.
Object | _NamingContextStub.resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.
Object | NamingContextOperations.resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.

Methods in org.omg.CosNaming with parameters of type Object
void | _NamingContextExtStub.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | _NamingContextStub.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | NamingContextOperations.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
static NamingContextExt | NamingContextExtHelper.narrow(Object obj)
static NamingContext | NamingContextHelper.narrow(Object obj)
static BindingIterator | BindingIteratorHelper.narrow(Object obj)
void | _NamingContextExtStub.rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
void | _NamingContextStub.rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
void | NamingContextOperations.rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
static NamingContextExt | NamingContextExtHelper.unchecked_narrow(Object obj)
static NamingContext | NamingContextHelper.unchecked_narrow(Object obj)
static BindingIterator | BindingIteratorHelper.unchecked_narrow(Object obj)

Uses of Object in org.omg.DynamicAny

Subinterfaces of Object in org.omg.DynamicAny
interface | DynAnyFactory DynAny objects can be created by invoking operations on the DynAnyFactory object.
interface | DynValueBox DynValueBox objects support the manipulation of IDL boxed value types.
interface | DynValueCommon DynValueCommon provides operations supported by both the DynValue and DynValueBox interfaces.

Classes in org.omg.DynamicAny that implement Object
class | _DynAnyFactoryStub DynAny objects can be created by invoking operations on the DynAnyFactory object.
class | _DynAnyStub Any values can be dynamically interpreted (traversed) and constructed through DynAny objects.
class | _DynArrayStub DynArray objects support the manipulation of IDL arrays.
class | _DynEnumStub DynEnum objects support the manipulation of IDL enumerated values.
class | _DynFixedStub DynFixed objects support the manipulation of IDL fixed values.
class | _DynSequenceStub DynSequence objects support the manipulation of IDL sequences.
class | _DynStructStub DynStruct objects support the manipulation of IDL struct and exception values.
class | _DynUnionStub DynUnion objects support the manipulation of IDL unions.
class | _DynValueStub DynValue objects support the manipulation of IDL non-boxed value types.

Methods in org.omg.DynamicAny that return Object
Object | _DynSequenceStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynFixedStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynEnumStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynArrayStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynValueStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynAnyStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynUnionStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynStructStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | DynAnyOperations.get_reference() Extracts the reference to a CORBA Object from this DynAny.

Methods in org.omg.DynamicAny with parameters of type Object
void | _DynSequenceStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynFixedStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynEnumStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynArrayStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynValueStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynAnyStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynUnionStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynStructStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | DynAnyOperations.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
static DynSequence | DynSequenceHelper.narrow(Object obj)
static DynFixed | DynFixedHelper.narrow(Object obj)
static DynEnum | DynEnumHelper.narrow(Object obj)
static DynArray | DynArrayHelper.narrow(Object obj)
static DynValue | DynValueHelper.narrow(Object obj)
static DynAny | DynAnyHelper.narrow(Object obj)
static DynUnion | DynUnionHelper.narrow(Object obj)
static DynAnyFactory | DynAnyFactoryHelper.narrow(Object obj)
static DynStruct | DynStructHelper.narrow(Object obj)
static DynSequence | DynSequenceHelper.unchecked_narrow(Object obj)
static DynFixed | DynFixedHelper.unchecked_narrow(Object obj)
static DynEnum | DynEnumHelper.unchecked_narrow(Object obj)
static DynArray | DynArrayHelper.unchecked_narrow(Object obj)
static DynValue | DynValueHelper.unchecked_narrow(Object obj)
static DynAny | DynAnyHelper.unchecked_narrow(Object obj)
static DynUnion | DynUnionHelper.unchecked_narrow(Object obj)
static DynAnyFactory | DynAnyFactoryHelper.unchecked_narrow(Object obj)
static DynStruct | DynStructHelper.unchecked_narrow(Object obj)

Uses of Object in org.omg.IOP

Subinterfaces of Object in org.omg.IOP
interface | Codec The formats of IOR components and service context data used by ORB services are often defined as CDR encapsulations encoding instances of IDL defined data types.
interface | CodecFactory Codecs are obtained from the CodecFactory.

Methods in org.omg.IOP with parameters of type Object
static CodecFactory | CodecFactoryHelper.narrow(Object obj)
static CodecFactory | CodecFactoryHelper.unchecked_narrow(Object obj)

Uses of Object in org.omg.PortableInterceptor

Subinterfaces of Object in org.omg.PortableInterceptor
interface | ClientRequestInfo Request Information, accessible to client-side request interceptors.
interface | ClientRequestInterceptor Client-side request interceptor.
interface | Interceptor All Portable Interceptors implement Interceptor.
interface | IORInfo Provides the server-side ORB service with access to the applicable policies during IOR construction and the ability to add components.
interface | IORInterceptor Interceptor used to establish tagged components in the profiles within an IOR.
interface | IORInterceptor_3_0 org/omg/PortableInterceptor/IORInterceptor_3_0.java .
interface | ORBInitializer Facilitates interceptor registration and ORB initialization.
interface | ORBInitInfo Passed to each ORBInitializer, allowing it to to register interceptors and perform other duties while the ORB is initializing.
interface | PolicyFactory Enables policy types to be constructed using CORBA.ORB.create_policy.
interface | RequestInfo Request Information, accessible to Interceptors.
interface | ServerRequestInfo Request Information, accessible to server-side request interceptors.
interface | ServerRequestInterceptor Server-side request interceptor.

Fields in org.omg.PortableInterceptor declared as Object
 Object ForwardRequest.forward
The new object to forward the request to.

Methods in org.omg.PortableInterceptor that return Object
Object | ClientRequestInfoOperations.effective_target() Returns the actual object on which the operation will be invoked.
Object | RequestInfoOperations.forward_reference() Contains the object to which the request will be forwarded, if the reply_status attribute is LOCATION_FORWARD.
Object | ObjectReferenceFactory.make_object(String repositoryId, byte[] object_id) make_object creates a CORBA object reference according to the data in this template, with the given repository ID and object ID.
Object | ORBInitInfoOperations.resolve_initial_references(String id) Identical to ORB.resolve_initial_references.
Object | ClientRequestInfoOperations.target() Returns the object which the client called to perform the operation.

Methods in org.omg.PortableInterceptor with parameters of type Object
static IORInterceptor_3_0 | IORInterceptor_3_0Helper.narrow(Object obj)
static Current | CurrentHelper.narrow(Object obj)
void | ORBInitInfoOperations.register_initial_reference(String id, Object obj) Identical to ORB.register_initial_reference.
static IORInterceptor_3_0 | IORInterceptor_3_0Helper.unchecked_narrow(Object obj)
static Current | CurrentHelper.unchecked_narrow(Object obj)

Constructors in org.omg.PortableInterceptor with parameters of type Object
ForwardRequest(Object _forward)
ForwardRequest(String $reason, Object _forward)

Uses of Object in org.omg.PortableServer

Subinterfaces of Object in org.omg.PortableServer
interface | AdapterActivator An adapter activator supplies a POA with the ability to create child POAs on demand, as a side-effect of receiving a request that names the child POA (or one of its children), or when find_POA is called with an activate parameter value of TRUE.
interface | IdAssignmentPolicy IdAssignmentPolicy specifies whether Object Ids in the created POA are generated by the application or by the ORB.
interface | IdUniquenessPolicy The IdUniquenessPolicy specifies whether the servants activated in the created POA must have unique object i identities.
interface | ImplicitActivationPolicy This policy specifies whether implicit activation of servants is supported in the created POA.
interface | LifespanPolicy The LifespanPolicy specifies the lifespan of the objects implemented in the created POA.
interface | POA A POA object manages the implementation of a collection of objects.
interface | POAManager Each POA object has an associated POAManager object.
interface | RequestProcessingPolicy This policy specifies how requests are processed by the created POA.
interface | ServantActivator When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
interface | ServantLocator When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.
interface | ServantManager A servant manager supplies a POA with the ability to activate objects on demand when the POA receives a request targeted at an inactive object.
interface | ServantRetentionPolicy This policy specifies whether the created POA retains active servants in an Active Object Map.
interface | ThreadPolicy The ThreadPolicy specifies the threading model used with the created POA.

Classes in org.omg.PortableServer that implement Object
class | _ServantActivatorStub When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
class | _ServantLocatorStub When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.

Fields in org.omg.PortableServer declared as Object
 Object ForwardRequest.forward_reference

Methods in org.omg.PortableServer that return Object
 Object Servant._get_interface_def()
Returns an InterfaceDef object as a CORBA::Object that defines the runtime type of the CORBA::Object implemented by the Servant.
 Object Servant._this_object()
Allows the servant to obtain the object reference for the target CORBA object it is incarnating for that request.
 Object Servant._this_object(ORB orb)
Allows the servant to obtain the object reference for the target CORBA Object it is incarnating for that request.
 Object POAOperations.create_reference_with_id(byte[] oid, String intf)
This operation creates an object reference that encapsulates the specified Object Id and interface repository Id values.
 Object POAOperations.create_reference(String intf)
This operation creates an object reference that encapsulates a POA-generated Object Id value and the specified interface repository id.
 Object POAOperations.id_to_reference(byte[] oid)
If an object with the specified Object Id value is currently active, a reference encapsulating the information used to activate the object is returned.
 Object POAOperations.servant_to_reference(Servant p_servant)
This operation requires the RETAIN policy and either the UNIQUE_ID or IMPLICIT_ACTIVATION policies if invoked outside the context of an operation dispatched by this POA.

Methods in org.omg.PortableServer with parameters of type Object
static ServantLocator | ServantLocatorHelper.narrow(Object obj)
static ServantActivator | ServantActivatorHelper.narrow(Object obj)
static POA | POAHelper.narrow(Object obj)
static Current | CurrentHelper.narrow(Object obj)
byte[] | POAOperations.reference_to_id(Object reference) This operation returns the Object Id value encapsulated by the specified reference.
Servant | POAOperations.reference_to_servant(Object reference) If the POA has the RETAIN policy and the specified object is present in the Active Object Map, this operation returns the servant associated with that object in the Active Object Map.
static ServantLocator | ServantLocatorHelper.unchecked_narrow(Object obj)
static ServantActivator | ServantActivatorHelper.unchecked_narrow(Object obj)

Constructors in org.omg.PortableServer with parameters of type Object
ForwardRequest(Object _forward_reference)
ForwardRequest(String $reason, Object _forward_reference)

Uses of Object in org.omg.PortableServer.portable

Methods in org.omg.PortableServer.portable that return Object
Object | Delegate.get_interface_def(Servant self) This operation returns an object in the Interface Repository which provides type information that may be useful to a program.
Object | Delegate.this_object(Servant Self) This allows the servant to obtain the object reference for the target CORBA Object it is incarnating for that request.

Uses of Object in org.omg.SendingContext

Subinterfaces of Object in org.omg.SendingContext
 interface RunTime
Defines the base class that represents the Sending Context of a request.

Uses of Object in org.omg.stub.java.rmi

Classes in org.omg.stub.java.rmi that implement Object
 class _Remote_Stub
This class provides the Stub for the Remote Type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.OMGVMCID

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.OMGVMCID

No usage of org.omg.CORBA.OMGVMCID

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.Policy

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.Policy

Packages that use Policy
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of Policy in org.omg.CORBA

Classes in org.omg.CORBA that implement Policy
 class _PolicyStub
The Stub for Policy.

Fields in org.omg.CORBA declared as Policy
Policy[] | PolicyListHolder.value
Policy | PolicyHolder.value

Methods in org.omg.CORBA that return Policy
Policy | LocalObject._get_policy(int policy_type) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented.
Policy | Object._get_policy(int policy_type) Returns the Policy object of the specified type which applies to this object.
Policy | _PolicyStub.copy() Copies the policy object.
Policy | PolicyOperations.copy() Returns a copy of the Policy object.
Policy | ORB.create_policy(int type, Any val) Can be invoked to create new instances of policy objects of a specific type with specified initial state.
static Policy[] | PolicyListHelper.extract(Any a)
static Policy | PolicyHelper.extract(Any a)
Policy | DomainManagerOperations.get_domain_policy(int policy_type) This returns the policy of the specified type for objects in this domain.
static Policy | PolicyHelper.narrow(Object obj)
static Policy[] | PolicyListHelper.read(InputStream istream)
static Policy | PolicyHelper.read(InputStream istream)

Methods in org.omg.CORBA with parameters of type Policy
Object | LocalObject._set_policy_override(Policy[] policies, SetOverrideType set_add) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented.
Object | Object._set_policy_override(Policy[] policies, SetOverrideType set_add) Returns a new Object with the given policies either replacing any existing policies in this Object or with the given policies added to the existing ones, depending on the value of the given SetOverrideType object.
static void | PolicyHelper.insert(Any a, Policy that)
static void | PolicyListHelper.insert(Any a, Policy[] that)
static void | PolicyHelper.write(OutputStream ostream, Policy value)
static void | PolicyListHelper.write(OutputStream ostream, Policy[] value)

Constructors in org.omg.CORBA with parameters of type Policy
PolicyHolder(Policy initialValue)
PolicyListHolder(Policy[] initialValue)

Uses of Policy in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable that return Policy
Policy | ObjectImpl._get_policy(int policy_type) Retrieves the Policy object for this ObjectImpl object that has the given policy type.
Policy | Delegate.get_policy(Object self, int policy_type) Returns the Policy object of the specified type which applies to this object.

Methods in org.omg.CORBA.portable with parameters of type Policy
Object | ObjectImpl._set_policy_override(Policy[] policies, SetOverrideType set_add) Sets this ObjectImpl object's override type for the given policies to the given instance of SetOverrideType.
Object | Delegate.set_policy_override(Object self, Policy[] policies, SetOverrideType set_add) Associates the policies passed in with a newly created object reference that it returns.

Uses of Policy in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor that return Policy
Policy | PolicyFactoryOperations.create_policy(int type, Any value) Returns an instance of the appropriate interface derived from CORBA.Policy whose value corresponds to the specified any.
Policy | IORInfoOperations.get_effective_policy(int type) Allows an ORB service implementation to determine what server side policy of a particular type is in effect for an IOR being constructed.
Policy | ClientRequestInfoOperations.get_request_policy(int type) Returns the given policy in effect for this operation.
Policy | ServerRequestInfoOperations.get_server_policy(int type) Returns the policy in effect for this operation for the given policy type.

Uses of Policy in org.omg.PortableServer

Subinterfaces of Policy in org.omg.PortableServer
interface | IdAssignmentPolicy IdAssignmentPolicy specifies whether Object Ids in the created POA are generated by the application or by the ORB.
interface | IdUniquenessPolicy The IdUniquenessPolicy specifies whether the servants activated in the created POA must have unique object i identities.
interface | ImplicitActivationPolicy This policy specifies whether implicit activation of servants is supported in the created POA.
interface | LifespanPolicy The LifespanPolicy specifies the lifespan of the objects implemented in the created POA.
interface | RequestProcessingPolicy This policy specifies how requests are processed by the created POA.
interface | ServantRetentionPolicy This policy specifies whether the created POA retains active servants in an Active Object Map.
interface | ThreadPolicy The ThreadPolicy specifies the threading model used with the created POA.

Methods in org.omg.PortableServer with parameters of type Policy
 POA POAOperations.create_POA(String adapter_name, POAManager a_POAManager, Policy[] policies)
This operation creates a new POA as a child of the target POA.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.PolicyOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.PolicyOperations

Packages that use PolicyOperations
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of PolicyOperations in org.omg.CORBA

Subinterfaces of PolicyOperations in org.omg.CORBA
 interface Policy
Interfaces derived from the Policy interface allow an ORB or CORBA service access to certain choices that affect its operation.

Classes in org.omg.CORBA that implement PolicyOperations
 class _PolicyStub
The Stub for Policy.

Uses of PolicyOperations in org.omg.PortableServer

Subinterfaces of PolicyOperations in org.omg.PortableServer
interface | IdAssignmentPolicy IdAssignmentPolicy specifies whether Object Ids in the created POA are generated by the application or by the ORB.
interface | IdAssignmentPolicyOperations IdAssignmentPolicy specifies whether Object Ids in the created POA are generated by the application or by the ORB.
interface | IdUniquenessPolicy The IdUniquenessPolicy specifies whether the servants activated in the created POA must have unique object i identities.
interface | IdUniquenessPolicyOperations The IdUniquenessPolicy specifies whether the servants activated in the created POA must have unique object i identities.
interface | ImplicitActivationPolicy This policy specifies whether implicit activation of servants is supported in the created POA.
interface | ImplicitActivationPolicyOperations This policy specifies whether implicit activation of servants is supported in the created POA.
interface | LifespanPolicy The LifespanPolicy specifies the lifespan of the objects implemented in the created POA.
interface | LifespanPolicyOperations The LifespanPolicy specifies the lifespan of the objects implemented in the created POA.
interface | RequestProcessingPolicy This policy specifies how requests are processed by the created POA.
interface | RequestProcessingPolicyOperations This policy specifies how requests are processed by the created POA.
interface | ServantRetentionPolicy This policy specifies whether the created POA retains active servants in an Active Object Map.
interface | ServantRetentionPolicyOperations This policy specifies whether the created POA retains active servants in an Active Object Map.
interface | ThreadPolicy The ThreadPolicy specifies the threading model used with the created POA.
interface | ThreadPolicyOperations The ThreadPolicy specifies the threading model used with the created POA.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.PRIVATE_MEMBER

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.PRIVATE_MEMBER

No usage of org.omg.CORBA.PRIVATE_MEMBER

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.PUBLIC_MEMBER

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.PUBLIC_MEMBER

No usage of org.omg.CORBA.PUBLIC_MEMBER

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.UNSUPPORTED_POLICY

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.UNSUPPORTED_POLICY

No usage of org.omg.CORBA.UNSUPPORTED_POLICY

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.UNSUPPORTED_POLICY_VALUE

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.UNSUPPORTED_POLICY_VALUE

No usage of org.omg.CORBA.UNSUPPORTED_POLICY_VALUE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.VM_ABSTRACT

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.VM_ABSTRACT

No usage of org.omg.CORBA.VM_ABSTRACT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.VM_CUSTOM

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.VM_CUSTOM

No usage of org.omg.CORBA.VM_CUSTOM

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.VM_NONE

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.VM_NONE

No usage of org.omg.CORBA.VM_NONE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.VM_TRUNCATABLE

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.VM_TRUNCATABLE

No usage of org.omg.CORBA.VM_TRUNCATABLE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


CODESET_INCOMPATIBLE

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class CODESET_INCOMPATIBLE

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.CODESET_INCOMPATIBLE
All Implemented Interfaces:
Serializable
public final class CODESET_INCOMPATIBLE
extends SystemException

This exception is raised whenever meaningful communication is not possible between client and server native code sets.

Since:
J2SE 1.5
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
CODESET_INCOMPATIBLE()
Constructs an CODESET_INCOMPATIBLE exception with minor code set to 0 and CompletionStatus set to COMPLETED_NO.
CODESET_INCOMPATIBLE(int minorCode, CompletionStatus completionStatus)
Constructs an CODESET_INCOMPATIBLE exception with the specified minor code and completion status.
CODESET_INCOMPATIBLE(String detailMessage)
Constructs an CODESET_INCOMPATIBLE exception with the specified message.
CODESET_INCOMPATIBLE(String detailMessage, int minorCode, CompletionStatus completionStatus)
Constructs an CODESET_INCOMPATIBLE exception with the specified message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CODESET_INCOMPATIBLE

public CODESET_INCOMPATIBLE()
Constructs an CODESET_INCOMPATIBLE exception with minor code set to 0 and CompletionStatus set to COMPLETED_NO.

CODESET_INCOMPATIBLE

public CODESET_INCOMPATIBLE(String detailMessage)
Constructs an CODESET_INCOMPATIBLE exception with the specified message.

Parameters:
detailMessage - string containing a detailed message.

CODESET_INCOMPATIBLE

public CODESET_INCOMPATIBLE(int minorCode,
                            CompletionStatus completionStatus)
Constructs an CODESET_INCOMPATIBLE exception with the specified minor code and completion status.

Parameters:
minorCode - minor code.
completionStatus - completion status.

CODESET_INCOMPATIBLE

public CODESET_INCOMPATIBLE(String detailMessage,
                            int minorCode,
                            CompletionStatus completionStatus)
Constructs an CODESET_INCOMPATIBLE exception with the specified message, minor code, and completion status.

Parameters:
detailMessage - string containing a detailed message.
minorCode - minor code.
completionStatus - completion status.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


COMM_FAILURE

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class COMM_FAILURE

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.COMM_FAILURE
All Implemented Interfaces:
Serializable
public final class COMM_FAILURE
extends SystemException

This exception is raised if communication is lost while an operation is in progress, after the request was sent by the client, but before the reply from the server has been returned to the client.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

See the section meaning of minor codes to see the minor codes for this exception.

Since:
JDK1.2
See Also:
meaning of minor codes

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
COMM_FAILURE()
Constructs a COMM_FAILURE exception with a default minor code of 0 and a completion state of COMPLETED_NO.
COMM_FAILURE(int minor, CompletionStatus completed)
Constructs a COMM_FAILURE exception with the specified minor code and completion status.
COMM_FAILURE(String s)
Constructs a COMM_FAILURE exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.
COMM_FAILURE(String s, int minor, CompletionStatus completed)
Constructs a COMM_FAILURE exception with the specified detail message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

COMM_FAILURE

public COMM_FAILURE()
Constructs a COMM_FAILURE exception with a default minor code of 0 and a completion state of COMPLETED_NO.

COMM_FAILURE

public COMM_FAILURE(String s)
Constructs a COMM_FAILURE exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message describing this exception

COMM_FAILURE

public COMM_FAILURE(int minor,
                    CompletionStatus completed)
Constructs a COMM_FAILURE exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status, which must be one of COMPLETED_YES, COMPLETED_NO, or COMPLETED_MAYBE.

COMM_FAILURE

public COMM_FAILURE(String s,
                    int minor,
                    CompletionStatus completed)
Constructs a COMM_FAILURE exception with the specified detail message, minor code, and completion status. A detail message is a String that describes this particular exception.

Parameters:
s - the String containing a detail message
minor - the minor code
completed - the completion status, which must be one of COMPLETED_YES, COMPLETED_NO, or COMPLETED_MAYBE.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CompletionStatus

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class CompletionStatus

java.lang.Object
    extended by  org.omg.CORBA.CompletionStatus
All Implemented Interfaces:
Serializable, IDLEntity
public final class CompletionStatus
extends Object
implements IDLEntity

An object that indicates whether a method had completed running when a SystemException was thrown.

The class CompletionStatus contains three CompletionStatus instances, which are constants representing each possible completion status: COMPLETED_MAYBE, COMPLETED_NO, and COMPLETED_YES. It also contains three int members, each a constant corresponding to one of the CompletionStatus instances. These int members make it possible to use a switch statement.

The class also contains two methods:

  • public int value() -- which accesses the value field of a CompletionStatus object
  • public static CompletionStatus from_int(int i) -- for creating an instance from one of the int members

Since:
JDK1.2
See Also:
SystemException

Field Summary
static int | _COMPLETED_MAYBE The constant indicating that a method completed running before a SystemException was thrown.
static int | _COMPLETED_NO The constant indicating that a method completed running before a SystemException was thrown.
static int | _COMPLETED_YES The constant indicating that a method completed running before a SystemException was thrown.
static CompletionStatus | COMPLETED_MAYBE An instance of CompletionStatus initialized with the constant _COMPLETED_MAYBE.
static CompletionStatus | COMPLETED_NO An instance of CompletionStatus initialized with the constant _COMPLETED_NO.
static CompletionStatus | COMPLETED_YES An instance of CompletionStatus initialized with the constant _COMPLETED_YES.
Method Summary
static CompletionStatus | from_int(int i) Creates a CompletionStatus object from the given int.
int | value() Retrieves the value of this CompletionStatus object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_COMPLETED_YES

public static final int _COMPLETED_YES
The constant indicating that a method completed running before a SystemException was thrown.

See Also:
Constant Field Values

_COMPLETED_NO

public static final int _COMPLETED_NO
The constant indicating that a method completed running before a SystemException was thrown.

See Also:
Constant Field Values

_COMPLETED_MAYBE

public static final int _COMPLETED_MAYBE
The constant indicating that a method completed running before a SystemException was thrown.

See Also:
Constant Field Values

COMPLETED_YES

public static final CompletionStatus COMPLETED_YES
An instance of CompletionStatus initialized with the constant _COMPLETED_YES.

COMPLETED_NO

public static final CompletionStatus COMPLETED_NO
An instance of CompletionStatus initialized with the constant _COMPLETED_NO.

COMPLETED_MAYBE

public static final CompletionStatus COMPLETED_MAYBE
An instance of CompletionStatus initialized with the constant _COMPLETED_MAYBE.

Method Detail

value

public int value()
Retrieves the value of this CompletionStatus object.

Returns:
one of the possible CompletionStatus values: _COMPLETED_YES, _COMPLETED_NO, or _COMPLETED_MAYBE

from_int

public static CompletionStatus from_int(int i)
Creates a CompletionStatus object from the given int.

Parameters:
i - one of _COMPLETED_YES, _COMPLETED_NO, or _COMPLETED_MAYBE
Returns:
one of the possible CompletionStatus objects with values: _COMPLETED_YES, _COMPLETED_NO, or _COMPLETED_MAYBE
Throws:
BAD_PARAM - if the argument given is not one of the int constants defined in CompletionStatus
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CompletionStatusHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class CompletionStatusHelper

java.lang.Object
    extended by  org.omg.CORBA.CompletionStatusHelper

public abstract class CompletionStatusHelper
extends Object

The Helper for CompletionStatus. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/CompletionStatusHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" 03 June 1999 11:52:03 o'clock GMT+00:00

Constructor Summary
CompletionStatusHelper()
Method Summary
static CompletionStatus | extract(Any a)
static String | id()
static void | insert(Any a, CompletionStatus that)
static CompletionStatus | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, CompletionStatus value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CompletionStatusHelper

public CompletionStatusHelper()
Method Detail

insert

public static void insert(Any a,
                          CompletionStatus that)

extract

public static CompletionStatus extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static CompletionStatus read(InputStream istream)

write

public static void write(OutputStream ostream,
                         CompletionStatus value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Context

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class Context

java.lang.Object
    extended by  org.omg.CORBA.Context

public abstract class Context
extends Object

An object used in Request operations to specify the context object in which context strings must be resolved before being sent along with the request invocation. A Context object contains a list of properties in the form of NamedValue objects. These properties represent information about the client, the environment, or the circumstances of a request and generally are properties that might be inconvenient to pass as parameters.

A Context object is created by first calling the ORB method get_default_context and then calling the method create_child on the default context.

Each property in a Context object is represented by a NamedValue object. The property name is contained in the NamedValue object's name field, and the value associated with the name is contained in the Any object that was assigned to the NamedValue object's value field.

Context properties can represent a portion of a client's or application's environment that is meant to be propagated to (and made implicitly part of) a server's environment. (Examples might be a window identifier or user preference information). Once a server has been invoked (that is, after the properties are propagated), the server may query its Context object for these properties using the method get_values.

When an operation declaration includes a context clause, the stubs and skeletons will have an additional argument added for the context. When an operation invocation occurs, the ORB causes the properties that were named in the operation definition in IDL and that are present in the client's Context object to be provided in the Context object parameter to the invoked method.

Context property names (which are strings) typically have the form of an OMG IDL identifier or a series of OMG IDL identifiers separated by periods. A context property name pattern is either a property name or a property name followed by a single "*". A property name pattern without a trailing "*" is said to match only itself. A property name pattern of the form "<name>*" matches any property name that starts with <name> and continues with zero or more additional characters.

Property name patterns are used in the context clause of an operation definition and as a parameter for the method Context.get_values.

Context objects may be "chained" together to achieve a particular defaulting behavior. A Context object created with the method create_child will be chained to its parent (the Context object that created it), and that means that the parent will be searched after the child in a search for property names.

Properties defined in a particular Context object effectively override those properties in the next higher level. The scope used in a search for properties may be restricted by specifying a starting scope and by using the flag CTX_RESTRICT_SCOPE when invoking the method get_values.

A Context object may be named for purposes of specifying a starting search scope.

Since:
JDK1.2

Constructor Summary
Context()
Method Summary
abstract String | context_name() Retrieves the name of this Context object.
abstract Context | create_child(String child_ctx_name) Creates a Context object with the given string as its name and with this Context object set as its parent.
abstract void | delete_values(String propname) Deletes from this Context object the NamedValue object(s) whose name field matches the given property name.
abstract NVList | get_values(String start_scope, int op_flags, String pattern) Retrieves the NamedValue objects whose name field matches the given name or name pattern.
abstract Context | parent() Retrieves the parent of this Context object.
abstract void | set_one_value(String propname, Any propvalue) Creates a NamedValue object and adds it to this Context object.
abstract void | set_values(NVList values) I Sets one or more property values in this Context object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Context

public Context()
Method Detail

context_name

public abstract String context_name()
Retrieves the name of this Context object.

Returns:
the name of this Context object

parent

public abstract Context parent()
Retrieves the parent of this Context object.

Returns:
the Context object that is the parent of this Context object

create_child

public abstract Context create_child(String child_ctx_name)
Creates a Context object with the given string as its name and with this Context object set as its parent.

The new Context object is chained into its parent Context object. This means that in a search for matching property names, if a match is not found in this context, the search will continue in the parent. If that is not successful, the search will continue in the grandparent, if there is one, and so on.

Parameters:
child_ctx_name - the String object to be set as the name of the new Context object
Returns:
the newly-created child Context object initialized with the specified name

set_one_value

public abstract void set_one_value(String propname,
                                   Any propvalue)
Creates a NamedValue object and adds it to this Context object. The name field of the new NamedValue object is set to the given string, the value field is set to the given Any object, and the flags field is set to zero.

Parameters:
propname - the name of the property to be set
propvalue - the Any object to which the value of the property will be set. The Any object's value field contains the value to be associated with the given propname; the kind field must be set to TCKind.tk_string.

set_values

public abstract void set_values(NVList values)
I Sets one or more property values in this Context object. The NVList supplied to this method contains one or more NamedValue objects. In each NamedValue object, the name field holds the name of the property, and the flags field must be set to zero. The NamedValue object's value field contains an Any object, which, in turn, contains the value for the property. Since the value is always a string, the Any object must have the kind field of its TypeCode set to TCKind.tk_string.

Parameters:
values - an NVList containing the property names and associated values to be set
See Also:
get_values(java.lang.String, int, java.lang.String), NamedValue, Any

delete_values

public abstract void delete_values(String propname)
Deletes from this Context object the NamedValue object(s) whose name field matches the given property name. If the String object supplied for propname has a trailing wildcard character ("*"), then all NamedValue objects whose name fields match will be deleted. The search scope is always limited to this Context object.

If no matching property is found, an exception is returned.

Parameters:
propname - name of the property to be deleted

get_values

public abstract NVList get_values(String start_scope,
                                  int op_flags,
                                  String pattern)
Retrieves the NamedValue objects whose name field matches the given name or name pattern. This method allows for wildcard searches, which means that there can be multiple matches and therefore multiple values returned. If the property is not found at the indicated level, the search continues up the context object tree until a match is found or all Context objects in the chain have been exhausted.

If no match is found, an error is returned and no property list is returned.

Parameters:
start_scope - a String object indicating the context object level at which to initiate the search for the specified properties (for example, "_USER", "_GROUP", "_SYSTEM"). Valid scope names are implementation-specific. If a scope name is omitted, the search begins with the specified context object. If the specified scope name is not found, an exception is returned.
op_flags - an operation flag. The one flag that may be specified is CTX_RESTRICT_SCOPE. If this flag is specified, searching is limited to the specified start_scope or this Context object.
pattern - the property name whose values are to be retrieved. pattern may be a name or a name with a trailing wildcard character ("*").
Returns:
an NVList containing all the property values (in the form of NamedValue objects) whose associated property name matches the given name or name pattern
See Also:
set_values(org.omg.CORBA.NVList), NamedValue
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ContextList

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ContextList

java.lang.Object
    extended by  org.omg.CORBA.ContextList

public abstract class ContextList
extends Object

An object containing a modifiable list of String objects that represent property names. This class is used in Request operations to describe the contexts that need to be resolved and sent with the invocation. (A context is resolved by giving a property name and getting back the value associated with it.) This is done by calling the Context method get_values and supplying a string from a ContextList object as the third parameter. The method get_values returns an NVList object containing the NamedValue objects that hold the value(s) identified by the given string.

A ContextList object is created by the ORB, as illustrated here:

   ORB orb = ORB.init(args, null);
   org.omg.CORBA.ContextList ctxList = orb.create_context_list();
The variable ctxList represents an empty ContextList object. Strings are added to the list with the method add, accessed with the method item, and removed with the method remove.

Since:
JDK1.2
See Also:
Context

Constructor Summary
ContextList()
Method Summary
abstract void | add(String ctx) Adds a String object to this ContextList object.
abstract int | count() Returns the number of String objects in this ContextList object.
abstract String | item(int index) Returns the String object at the given index.
abstract void | remove(int index) Removes the String object at the given index.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ContextList

public ContextList()
Method Detail

count

public abstract int count()
Returns the number of String objects in this ContextList object.

Returns:
an int representing the number of Strings in this ContextList object

add

public abstract void add(String ctx)
Adds a String object to this ContextList object.

Parameters:
ctx - the String object to be added

item

public abstract String item(int index)
                     throws Bounds
Returns the String object at the given index.

Parameters:
index - the index of the string desired, with 0 being the index of the first string
Returns:
the string at the given index
Throws:
Bounds - if the index is greater than or equal to the number of strings in this ContextList object

remove

public abstract void remove(int index)
                     throws Bounds
Removes the String object at the given index. Note that the indices of all strings following the one removed are shifted down by one.

Parameters:
index - the index of the String object to be removed, with 0 designating the first string
Throws:
Bounds - if the index is greater than or equal to the number of String objects in this ContextList object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CTX_RESTRICT_SCOPE

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface CTX_RESTRICT_SCOPE

public interface CTX_RESTRICT_SCOPE

A flag that can be used as the second parameter to the method Context.get_values to restrict the search scope. When this flag is used, it restricts the search for context values to this particular Context object or to the scope specified in the first parameter to Context.get_values.

Usage:

     NVList props = myContext.get_values("_USER",
                     CTX_RESTRICT_SCOPE.value, "id*");

Since:
JDK1.2
See Also:
Context.get_values(String, int, String)

Field Summary
static int value
The field containing the int value of a CTX_RESTRICT_SCOPE flag.

Field Detail

value

static final int value
The field containing the int value of a CTX_RESTRICT_SCOPE flag.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CurrentHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class CurrentHelper

java.lang.Object
    extended by  org.omg.CORBA.CurrentHelper

public abstract class CurrentHelper
extends Object

The Helper for Current. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/CurrentHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ../../../../../src/share/classes/org/omg/PortableServer/corba.idl Saturday, July 17, 1999 12:26:21 AM PDT

Constructor Summary
CurrentHelper()
Method Summary
static Current | extract(Any a)
static String | id()
static void | insert(Any a, Current that)
static Current | narrow(Object obj)
static Current | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, Current value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CurrentHelper

public CurrentHelper()
Method Detail

insert

public static void insert(Any a,
                          Current that)

extract

public static Current extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static Current read(InputStream istream)

write

public static void write(OutputStream ostream,
                         Current value)

narrow

public static Current narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CurrentHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class CurrentHolder

java.lang.Object
    extended by  org.omg.CORBA.CurrentHolder
All Implemented Interfaces:
Streamable
public final class CurrentHolder
extends Object
implements Streamable

The Holder for Current. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/CurrentHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ../../../../../src/share/classes/org/omg/PortableServer/corba.idl Saturday, July 17, 1999 12:26:21 AM PDT

Field Summary
 Current value
Constructor Summary
CurrentHolder()
CurrentHolder(Current initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public Current value
Constructor Detail

CurrentHolder

public CurrentHolder()

CurrentHolder

public CurrentHolder(Current initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CustomMarshal

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface CustomMarshal

All Known Subinterfaces:
CustomValue
public interface CustomMarshal

An abstract value type that is meant to be used by the ORB, not the user. Semantically it is treated as a custom value type's implicit base class, although the custom valuetype does not actually inherit it in IDL. The implementer of a custom value type shall provide an implementation of the CustomMarshal operations. The manner in which this is done is specified in the IDL to Java langauge mapping. Each custom marshaled value type shall have its own implementation.

See Also:
DataInputStream

Method Summary
void | marshal(DataOutputStream os) Marshal method has to be implemented by the Customized Marshal class.
void | unmarshal(DataInputStream is) Unmarshal method has to be implemented by the Customized Marshal class.

Method Detail

marshal

void marshal(DataOutputStream os)
Marshal method has to be implemented by the Customized Marshal class. This is the method invoked for Marshalling.

Parameters:
os - a DataOutputStream

unmarshal

void unmarshal(DataInputStream is)
Unmarshal method has to be implemented by the Customized Marshal class. This is the method invoked for Unmarshalling.

Parameters:
is - a DataInputStream
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DataInputStream

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface DataInputStream

All Superinterfaces:
IDLEntity, Serializable, ValueBase
public interface DataInputStream
extends ValueBase

Defines the methods used to read primitive data types from input streams for unmarshaling custom value types. This interface is used by user written custom unmarshaling code for custom value types.

See Also:
DataOutputStream, CustomMarshal

Method Summary
 Object read_Abstract()
Reads an IDL Abstract interface from the input stream.
 void read_any_array(AnySeqHolder seq, int offset, int length)
Reads array of IDL Anys from offset for length elements from the input stream.
 Any read_any()
Reads an IDL Any value from the input stream.
 void read_boolean_array(BooleanSeqHolder seq, int offset, int length)
Reads array of IDL booleans from offset for length elements from the input stream.
 boolean read_boolean()
Reads an IDL boolean value from the input stream.
 void read_char_array(CharSeqHolder seq, int offset, int length)
Reads array of IDL characters from offset for length elements from the input stream.
 char read_char()
Reads an IDL character value from the input stream.
 void read_double_array(DoubleSeqHolder seq, int offset, int length)
Reads array of IDL doubles from offset for length elements from the input stream.
 double read_double()
Reads an IDL double from the input stream.
 void read_float_array(FloatSeqHolder seq, int offset, int length)
Reads array of IDL floats from offset for length elements from the input stream.
 float read_float()
Reads an IDL float from the input stream.
 void read_long_array(LongSeqHolder seq, int offset, int length)
Reads array of IDL longs from offset for length elements from the input stream.
 int read_long()
Reads an IDL long from the input stream.
 void read_longlong_array(LongLongSeqHolder seq, int offset, int length)
Reads array of IDL long longs from offset for length elements from the input stream.
 long read_longlong()
Reads an IDL long long from the input stream.
 Object read_Object()
Reads an IDL CORBA::Object from the input stream.
 void read_octet_array(OctetSeqHolder seq, int offset, int length)
Reads array of IDL octets from offset for length elements from the input stream.
 byte read_octet()
Reads an IDL octet value from the input stream.
 void read_short_array(ShortSeqHolder seq, int offset, int length)
Reads array of IDL shorts from offset for length elements from the input stream.
 short read_short()
Reads an IDL short from the input stream.
 String read_string()
Reads an IDL string from the input stream.
 TypeCode read_TypeCode()
Reads an IDL typecode from the input stream.
 void read_ulong_array(ULongSeqHolder seq, int offset, int length)
Reads array of IDL unsigned longs from offset for length elements from the input stream.
 int read_ulong()
Reads an IDL unsigned long from the input stream.
 void read_ulonglong_array(ULongLongSeqHolder seq, int offset, int length)
Reads array of IDL unsigned long longs from offset for length elements from the input stream.
 long read_ulonglong()
Reads an unsigned IDL long long from the input stream.
 void read_ushort_array(UShortSeqHolder seq, int offset, int length)
Reads array of IDL unsigned shorts from offset for length elements from the input stream.
 short read_ushort()
Reads an IDL unsigned short from the input stream.
 Serializable read_Value()
Reads an IDL value type from the input stream.
 void read_wchar_array(WCharSeqHolder seq, int offset, int length)
Reads array of IDL wide characters from offset for length elements from the input stream.
 char read_wchar()
Reads an IDL wide character value from the input stream.
 String read_wstring()
Reads an IDL wide string from the input stream.
Methods inherited from interface org.omg.CORBA.portable.ValueBase
_truncatable_ids

Method Detail

read_any

Any read_any()
Reads an IDL Any value from the input stream.

Returns:
the Any read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_boolean

boolean read_boolean()
Reads an IDL boolean value from the input stream.

Returns:
the boolean read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_char

char read_char()
Reads an IDL character value from the input stream.

Returns:
the character read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_wchar

char read_wchar()
Reads an IDL wide character value from the input stream.

Returns:
the wide character read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_octet

byte read_octet()
Reads an IDL octet value from the input stream.

Returns:
the octet value read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_short

short read_short()
Reads an IDL short from the input stream.

Returns:
the short read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_ushort

short read_ushort()
Reads an IDL unsigned short from the input stream.

Returns:
the unsigned short read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_long

int read_long()
Reads an IDL long from the input stream.

Returns:
the long read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_ulong

int read_ulong()
Reads an IDL unsigned long from the input stream.

Returns:
the unsigned long read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_longlong

long read_longlong()
Reads an IDL long long from the input stream.

Returns:
the long long read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_ulonglong

long read_ulonglong()
Reads an unsigned IDL long long from the input stream.

Returns:
the unsigned long long read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_float

float read_float()
Reads an IDL float from the input stream.

Returns:
the float read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_double

double read_double()
Reads an IDL double from the input stream.

Returns:
the double read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_string

String read_string()
Reads an IDL string from the input stream.

Returns:
the string read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_wstring

String read_wstring()
Reads an IDL wide string from the input stream.

Returns:
the wide string read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_Object

Object read_Object()
Reads an IDL CORBA::Object from the input stream.

Returns:
the CORBA::Object read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_Abstract

Object read_Abstract()
Reads an IDL Abstract interface from the input stream.

Returns:
the Abstract interface read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_Value

Serializable read_Value()
Reads an IDL value type from the input stream.

Returns:
the value type read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_TypeCode

TypeCode read_TypeCode()
Reads an IDL typecode from the input stream.

Returns:
the typecode read.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_any_array

void read_any_array(AnySeqHolder seq,
                    int offset,
                    int length)
Reads array of IDL Anys from offset for length elements from the input stream.

Parameters:
seq - The out parameter holder for the array to be read.
offset - The index into seq of the first element to read from the input stream.
length - The number of elements to read from the input stream.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_boolean_array

void read_boolean_array(BooleanSeqHolder seq,
                        int offset,
                        int length)
Reads array of IDL booleans from offset for length elements from the input stream.

Parameters:
seq - The out parameter holder for the array to be read.
offset - The index into seq of the first element to read from the input stream.
length - The number of elements to read from the input stream.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_char_array

void read_char_array(CharSeqHolder seq,
                     int offset,
                     int length)
Reads array of IDL characters from offset for length elements from the input stream.

Parameters:
seq - The out parameter holder for the array to be read.
offset - The index into seq of the first element to read from the input stream.
length - The number of elements to read from the input stream.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_wchar_array

void read_wchar_array(WCharSeqHolder seq,
                      int offset,
                      int length)
Reads array of IDL wide characters from offset for length elements from the input stream.

Parameters:
seq - The out parameter holder for the array to be read.
offset - The index into seq of the first element to read from the input stream.
length - The number of elements to read from the input stream.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_octet_array

void read_octet_array(OctetSeqHolder seq,
                      int offset,
                      int length)
Reads array of IDL octets from offset for length elements from the input stream.

Parameters:
seq - The out parameter holder for the array to be read.
offset - The index into seq of the first element to read from the input stream.
length - The number of elements to read from the input stream.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_short_array

void read_short_array(ShortSeqHolder seq,
                      int offset,
                      int length)
Reads array of IDL shorts from offset for length elements from the input stream.

Parameters:
seq - The out parameter holder for the array to be read.
offset - The index into seq of the first element to read from the input stream.
length - The number of elements to read from the input stream.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_ushort_array

void read_ushort_array(UShortSeqHolder seq,
                       int offset,
                       int length)
Reads array of IDL unsigned shorts from offset for length elements from the input stream.

Parameters:
seq - The out parameter holder for the array to be read.
offset - The index into seq of the first element to read from the input stream.
length - The number of elements to read from the input stream.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_long_array

void read_long_array(LongSeqHolder seq,
                     int offset,
                     int length)
Reads array of IDL longs from offset for length elements from the input stream.

Parameters:
seq - The out parameter holder for the array to be read.
offset - The index into seq of the first element to read from the input stream.
length - The number of elements to read from the input stream.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_ulong_array

void read_ulong_array(ULongSeqHolder seq,
                      int offset,
                      int length)
Reads array of IDL unsigned longs from offset for length elements from the input stream.

Parameters:
seq - The out parameter holder for the array to be read.
offset - The index into seq of the first element to read from the input stream.
length - The number of elements to read from the input stream.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_ulonglong_array

void read_ulonglong_array(ULongLongSeqHolder seq,
                          int offset,
                          int length)
Reads array of IDL unsigned long longs from offset for length elements from the input stream.

Parameters:
seq - The out parameter holder for the array to be read.
offset - The index into seq of the first element to read from the input stream.
length - The number of elements to read from the input stream.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_longlong_array

void read_longlong_array(LongLongSeqHolder seq,
                         int offset,
                         int length)
Reads array of IDL long longs from offset for length elements from the input stream.

Parameters:
seq - The out parameter holder for the array to be read.
offset - The index into seq of the first element to read from the input stream.
length - The number of elements to read from the input stream.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_float_array

void read_float_array(FloatSeqHolder seq,
                      int offset,
                      int length)
Reads array of IDL floats from offset for length elements from the input stream.

Parameters:
seq - The out parameter holder for the array to be read.
offset - The index into seq of the first element to read from the input stream.
length - The number of elements to read from the input stream.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.

read_double_array

void read_double_array(DoubleSeqHolder seq,
                       int offset,
                       int length)
Reads array of IDL doubles from offset for length elements from the input stream.

Parameters:
seq - The out parameter holder for the array to be read.
offset - The index into seq of the first element to read from the input stream.
length - The number of elements to read from the input stream.
Throws:
org.omg.CORBA.MARSHAL - If an inconsistency is detected, including not having registered a streaming policy, then the standard system exception MARSHAL is raised.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DataOutputStream

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface DataOutputStream

All Superinterfaces:
IDLEntity, Serializable, ValueBase
public interface DataOutputStream
extends ValueBase

Defines the methods used to write primitive data types to output streams for marshalling custom value types. This interface is used by user written custom marshalling code for custom value types.

See Also:
DataInputStream, CustomMarshal

Method Summary
void | write_Abstract(Object value) Writes the IDL Abstract interface type to the output stream.
void | write_any_array(Any[] seq, int offset, int length) Writes the array of IDL Anys from offset for length elements to the output stream.
void | write_any(Any value) Writes the Any value to the output stream.
void | write_boolean_array(boolean[] seq, int offset, int length) Writes the array of IDL booleans from offset for length elements to the output stream.
void | write_boolean(boolean value) Writes the boolean value to the output stream.
void | write_char_array(char[] seq, int offset, int length) Writes the array of IDL characters from offset for length elements to the output stream.
void | write_char(char value) Writes the IDL character value to the output stream.
void | write_double_array(double[] seq, int offset, int length) Writes the array of IDL doubles from offset for length elements to the output stream.
void | write_double(double value) Writes the IDL double value to the output stream.
void | write_float_array(float[] seq, int offset, int length) Writes the array of IDL floats from offset for length elements to the output stream.
void | write_float(float value) Writes the IDL float value to the output stream.
void | write_long_array(int[] seq, int offset, int length) Writes the array of IDL longs from offset for length elements to the output stream.
void | write_long(int value) Writes the IDL long value (represented as a Java int) to the output stream.
void | write_longlong_array(long[] seq, int offset, int length) Writes the array of IDL long longs from offset for length elements to the output stream.
void | write_longlong(long value) Writes the IDL long long value (represented as a Java long) to the output stream.
void | write_Object(Object value) Writes the IDL CORBA::Object value to the output stream.
void | write_octet_array(byte[] seq, int offset, int length) Writes the array of IDL octets from offset for length elements to the output stream.
void | write_octet(byte value) Writes the IDL octet value (represented as a Java byte) to the output stream.
void | write_short_array(short[] seq, int offset, int length) Writes the array of IDL shorts from offset for length elements to the output stream.
void | write_short(short value) Writes the IDL short value to the output stream.
void | write_string(String value) Writes the IDL string value to the output stream.
void | write_TypeCode(TypeCode value) Writes the typecode to the output stream.
void | write_ulong_array(int[] seq, int offset, int length) Writes the array of IDL unsigned longs (represented as Java ints) from offset for length elements to the output stream.
void | write_ulong(int value) Writes the IDL unsigned long value (represented as a Java int) to the output stream.
void | write_ulonglong_array(long[] seq, int offset, int length) Writes the array of IDL unsigned long longs (represented as Java longs) from offset for length elements to the output stream.
void | write_ulonglong(long value) Writes the IDL unsigned long long value (represented as a Java long) to the output stream.
void | write_ushort_array(short[] seq, int offset, int length) Writes the array of IDL unsigned shorts (represented as Java shorts) from offset for length elements to the output stream.
void | write_ushort(short value) Writes the IDL unsigned short value (represented as a Java short value) to the output stream.
void | write_Value(Serializable value) Writes the IDL value type value to the output stream.
void | write_wchar_array(char[] seq, int offset, int length) Writes the array of IDL wide characters from offset for length elements to the output stream.
void | write_wchar(char value) Writes the IDL wide character value to the output stream.
void | write_wstring(String value) Writes the IDL wide string value (represented as a Java String) to the output stream.
Methods inherited from interface org.omg.CORBA.portable.ValueBase
_truncatable_ids

Method Detail

write_any

void write_any(Any value)
Writes the Any value to the output stream.

Parameters:
value - The value to be written.

write_boolean

void write_boolean(boolean value)
Writes the boolean value to the output stream.

Parameters:
value - The value to be written.

write_char

void write_char(char value)
Writes the IDL character value to the output stream.

Parameters:
value - The value to be written.

write_wchar

void write_wchar(char value)
Writes the IDL wide character value to the output stream.

Parameters:
value - The value to be written.

write_octet

void write_octet(byte value)
Writes the IDL octet value (represented as a Java byte) to the output stream.

Parameters:
value - The value to be written.

write_short

void write_short(short value)
Writes the IDL short value to the output stream.

Parameters:
value - The value to be written.

write_ushort

void write_ushort(short value)
Writes the IDL unsigned short value (represented as a Java short value) to the output stream.

Parameters:
value - The value to be written.

write_long

void write_long(int value)
Writes the IDL long value (represented as a Java int) to the output stream.

Parameters:
value - The value to be written.

write_ulong

void write_ulong(int value)
Writes the IDL unsigned long value (represented as a Java int) to the output stream.

Parameters:
value - The value to be written.

write_longlong

void write_longlong(long value)
Writes the IDL long long value (represented as a Java long) to the output stream.

Parameters:
value - The value to be written.

write_ulonglong

void write_ulonglong(long value)
Writes the IDL unsigned long long value (represented as a Java long) to the output stream.

Parameters:
value - The value to be written.

write_float

void write_float(float value)
Writes the IDL float value to the output stream.

Parameters:
value - The value to be written.

write_double

void write_double(double value)
Writes the IDL double value to the output stream.

Parameters:
value - The value to be written.

write_string

void write_string(String value)
Writes the IDL string value to the output stream.

Parameters:
value - The value to be written.

write_wstring

void write_wstring(String value)
Writes the IDL wide string value (represented as a Java String) to the output stream.

Parameters:
value - The value to be written.

write_Object

void write_Object(Object value)
Writes the IDL CORBA::Object value to the output stream.

Parameters:
value - The value to be written.

write_Abstract

void write_Abstract(Object value)
Writes the IDL Abstract interface type to the output stream.

Parameters:
value - The value to be written.

write_Value

void write_Value(Serializable value)
Writes the IDL value type value to the output stream.

Parameters:
value - The value to be written.

write_TypeCode

void write_TypeCode(TypeCode value)
Writes the typecode to the output stream.

Parameters:
value - The value to be written.

write_any_array

void write_any_array(Any[] seq,
                     int offset,
                     int length)
Writes the array of IDL Anys from offset for length elements to the output stream.

Parameters:
seq - The array to be written.
offset - The index into seq of the first element to write to the output stream.
length - The number of elements to write to the output stream.

write_boolean_array

void write_boolean_array(boolean[] seq,
                         int offset,
                         int length)
Writes the array of IDL booleans from offset for length elements to the output stream.

Parameters:
seq - The array to be written.
offset - The index into seq of the first element to write to the output stream.
length - The number of elements to write to the output stream.

write_char_array

void write_char_array(char[] seq,
                      int offset,
                      int length)
Writes the array of IDL characters from offset for length elements to the output stream.

Parameters:
seq - The array to be written.
offset - The index into seq of the first element to write to the output stream.
length - The number of elements to write to the output stream.

write_wchar_array

void write_wchar_array(char[] seq,
                       int offset,
                       int length)
Writes the array of IDL wide characters from offset for length elements to the output stream.

Parameters:
seq - The array to be written.
offset - The index into seq of the first element to write to the output stream.
length - The number of elements to write to the output stream.

write_octet_array

void write_octet_array(byte[] seq,
                       int offset,
                       int length)
Writes the array of IDL octets from offset for length elements to the output stream.

Parameters:
seq - The array to be written.
offset - The index into seq of the first element to write to the output stream.
length - The number of elements to write to the output stream.

write_short_array

void write_short_array(short[] seq,
                       int offset,
                       int length)
Writes the array of IDL shorts from offset for length elements to the output stream.

Parameters:
seq - The array to be written.
offset - The index into seq of the first element to write to the output stream.
length - The number of elements to write to the output stream.

write_ushort_array

void write_ushort_array(short[] seq,
                        int offset,
                        int length)
Writes the array of IDL unsigned shorts (represented as Java shorts) from offset for length elements to the output stream.

Parameters:
seq - The array to be written.
offset - The index into seq of the first element to write to the output stream.
length - The number of elements to write to the output stream.

write_long_array

void write_long_array(int[] seq,
                      int offset,
                      int length)
Writes the array of IDL longs from offset for length elements to the output stream.

Parameters:
seq - The array to be written.
offset - The index into seq of the first element to write to the output stream.
length - The number of elements to write to the output stream.

write_ulong_array

void write_ulong_array(int[] seq,
                       int offset,
                       int length)
Writes the array of IDL unsigned longs (represented as Java ints) from offset for length elements to the output stream.

Parameters:
seq - The array to be written.
offset - The index into seq of the first element to write to the output stream.
length - The number of elements to write to the output stream.

write_ulonglong_array

void write_ulonglong_array(long[] seq,
                           int offset,
                           int length)
Writes the array of IDL unsigned long longs (represented as Java longs) from offset for length elements to the output stream.

Parameters:
seq - The array to be written.
offset - The index into seq of the first element to write to the output stream.
length - The number of elements to write to the output stream.

write_longlong_array

void write_longlong_array(long[] seq,
                          int offset,
                          int length)
Writes the array of IDL long longs from offset for length elements to the output stream.

Parameters:
seq - The array to be written.
offset - The index into seq of the first element to write to the output stream.
length - The number of elements to write to the output stream.

write_float_array

void write_float_array(float[] seq,
                       int offset,
                       int length)
Writes the array of IDL floats from offset for length elements to the output stream.

Parameters:
seq - The array to be written.
offset - The index into seq of the first element to write to the output stream.
length - The number of elements to write to the output stream.

write_double_array

void write_double_array(double[] seq,
                        int offset,
                        int length)
Writes the array of IDL doubles from offset for length elements to the output stream.

Parameters:
seq - The array to be written.
offset - The index into seq of the first element to write to the output stream.
length - The number of elements to write to the output stream.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DATA_CONVERSION

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class DATA_CONVERSION

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.DATA_CONVERSION
All Implemented Interfaces:
Serializable
public final class DATA_CONVERSION
extends SystemException

This exception is raised if an ORB cannot convert the representation of data as marshaled into its native representation or vice-versa. For example, DATA_CONVERSION can be raised if wide character codeset conversion fails, or if an ORB cannot convert floating point values between different representations.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

See the section meaning of minor codes to see the minor codes for this exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
DATA_CONVERSION()
Constructs a DATA_CONVERSION exception with a default minor code of 0 and a completion state of COMPLETED_NO.
DATA_CONVERSION(int minor, CompletionStatus completed)
Constructs a DATA_CONVERSION exception with the specified minor code and completion status.
DATA_CONVERSION(String s)
Constructs a DATA_CONVERSION exception with the specified detail.
DATA_CONVERSION(String s, int minor, CompletionStatus completed)
Constructs a DATA_CONVERSION exception with the specified detail message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DATA_CONVERSION

public DATA_CONVERSION()
Constructs a DATA_CONVERSION exception with a default minor code of 0 and a completion state of COMPLETED_NO.

DATA_CONVERSION

public DATA_CONVERSION(String s)
Constructs a DATA_CONVERSION exception with the specified detail.

Parameters:
s - the String containing a detail message

DATA_CONVERSION

public DATA_CONVERSION(int minor,
                       CompletionStatus completed)
Constructs a DATA_CONVERSION exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

DATA_CONVERSION

public DATA_CONVERSION(String s,
                       int minor,
                       CompletionStatus completed)
Constructs a DATA_CONVERSION exception with the specified detail message, minor code, and completion status. A detail message is a String that describes this particular exception.

Parameters:
s - the String containing a detail message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefinitionKind

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class DefinitionKind

java.lang.Object
    extended by  org.omg.CORBA.DefinitionKind
All Implemented Interfaces:
Serializable, IDLEntity
public class DefinitionKind
extends Object
implements IDLEntity

The class that provides the constants used to identify the type of an Interface Repository object. This class contains two kinds of constants, those that are an int and those that are an instance of the class DefinitionKind. This class provides the method from_int, which given one of the int constants, creates the corresponding DefinitionKind instance. It also provides the method value, which returns the int constant that is the value for a DefinitionKind instance.

See Also:
IRObject

Field Summary
static int | _dk_AbstractInterface The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Alias The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_all The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Array The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Attribute The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Constant The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Enum The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Exception The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Fixed The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Interface The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Module The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Native The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_none The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Operation The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Primitive The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Repository The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Sequence The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_String The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Struct The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Typedef The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Union The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Value The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_ValueBox The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_ValueMember The constant that indicates that an Interface Repository object does not have a definition kind.
static int | _dk_Wstring The constant that indicates that an Interface Repository object does not have a definition kind.
static DefinitionKind | dk_AbstractInterface The static instance of DefinitionKind indicating that an Interface Repository object represents an abstract interface.
static DefinitionKind | dk_Alias The static instance of DefinitionKind indicating that an Interface Repository object is an Alias.
static DefinitionKind | dk_all The wildcard DefinitionKind constant, useful in all occasions where any DefinitionKind is appropriate.
static DefinitionKind | dk_Array The static instance of DefinitionKind indicating that an Interface Repository object is an Array.
static DefinitionKind | dk_Attribute The static instance of DefinitionKind indicating that an Interface Repository object is an Attribute.
static DefinitionKind | dk_Constant The static instance of DefinitionKind indicating that an Interface Repository object is a constant.
static DefinitionKind | dk_Enum The static instance of DefinitionKind indicating that an Interface Repository object is an Enum.
static DefinitionKind | dk_Exception The static instance of DefinitionKind indicating that an Interface Repository object is an Exception.
static DefinitionKind | dk_Fixed The static instance of DefinitionKind indicating that an Interface Repository object is a Fixed value.
static DefinitionKind | dk_Interface The static instance of DefinitionKind indicating that an Interface Repository object is an Interface.
static DefinitionKind | dk_Module The static instance of DefinitionKind indicating that an Interface Repository object is a Module.
static DefinitionKind | dk_Native The static instance of DefinitionKind indicating that an Interface Repository object is a Native value.
static DefinitionKind | dk_none The static instance of DefinitionKind indicating that an Interface Repository object has no definition kind.
static DefinitionKind | dk_Operation The static instance of DefinitionKind indicating that an Interface Repository object is an Operation.
static DefinitionKind | dk_Primitive The static instance of DefinitionKind indicating that an Interface Repository object is a Primitive.
static DefinitionKind | dk_Repository The static instance of DefinitionKind indicating that an Interface Repository object is a Repository.
static DefinitionKind | dk_Sequence The static instance of DefinitionKind indicating that an Interface Repository object is a Sequence.
static DefinitionKind | dk_String The static instance of DefinitionKind indicating that an Interface Repository object is a String.
static DefinitionKind | dk_Struct The static instance of DefinitionKind indicating that an Interface Repository object is a Struct.
static DefinitionKind | dk_Typedef The static instance of DefinitionKind indicating that an Interface Repository object is a Typedef.
static DefinitionKind | dk_Union The static instance of DefinitionKind indicating that an Interface Repository object is a Union.
static DefinitionKind | dk_Value The static instance of DefinitionKind indicating that an Interface Repository object is a Value.
static DefinitionKind | dk_ValueBox The static instance of DefinitionKind indicating that an Interface Repository object is a ValueBox.
static DefinitionKind | dk_ValueMember The static instance of DefinitionKind indicating that an Interface Repository object is a ValueMember.
static DefinitionKind | dk_Wstring The static instance of DefinitionKind indicating that an Interface Repository object is a Wstring.
Constructor Summary
protected DefinitionKind(int _value)
Constructs a DefinitionKind object with its _value field initialized with the given value.
Method Summary
static DefinitionKind | from_int(int i) Creates a DefinitionKind instance corresponding to the given code .
int | value() Returns the int constant identifying the type of an IR object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_dk_none

public static final int _dk_none
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_all

public static final int _dk_all
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Attribute

public static final int _dk_Attribute
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Constant

public static final int _dk_Constant
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Exception

public static final int _dk_Exception
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Interface

public static final int _dk_Interface
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Module

public static final int _dk_Module
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Operation

public static final int _dk_Operation
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Typedef

public static final int _dk_Typedef
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Alias

public static final int _dk_Alias
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Struct

public static final int _dk_Struct
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Union

public static final int _dk_Union
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Enum

public static final int _dk_Enum
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Primitive

public static final int _dk_Primitive
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_String

public static final int _dk_String
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Sequence

public static final int _dk_Sequence
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Array

public static final int _dk_Array
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Repository

public static final int _dk_Repository
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Wstring

public static final int _dk_Wstring
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Fixed

public static final int _dk_Fixed
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Value

public static final int _dk_Value
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_ValueBox

public static final int _dk_ValueBox
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_ValueMember

public static final int _dk_ValueMember
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_Native

public static final int _dk_Native
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

_dk_AbstractInterface

public static final int _dk_AbstractInterface
The constant that indicates that an Interface Repository object does not have a definition kind.

See Also:
Constant Field Values

dk_none

public static final DefinitionKind dk_none
The static instance of DefinitionKind indicating that an Interface Repository object has no definition kind.

dk_all

public static final DefinitionKind dk_all
The wildcard DefinitionKind constant, useful in all occasions where any DefinitionKind is appropriate. The Container's contents method makes use of this constant to return all contained definitions of any kind.

dk_Attribute

public static final DefinitionKind dk_Attribute
The static instance of DefinitionKind indicating that an Interface Repository object is an Attribute.

dk_Constant

public static final DefinitionKind dk_Constant
The static instance of DefinitionKind indicating that an Interface Repository object is a constant.

dk_Exception

public static final DefinitionKind dk_Exception
The static instance of DefinitionKind indicating that an Interface Repository object is an Exception.

dk_Interface

public static final DefinitionKind dk_Interface
The static instance of DefinitionKind indicating that an Interface Repository object is an Interface.

dk_Module

public static final DefinitionKind dk_Module
The static instance of DefinitionKind indicating that an Interface Repository object is a Module.

dk_Operation

public static final DefinitionKind dk_Operation
The static instance of DefinitionKind indicating that an Interface Repository object is an Operation.

dk_Typedef

public static final DefinitionKind dk_Typedef
The static instance of DefinitionKind indicating that an Interface Repository object is a Typedef.

dk_Alias

public static final DefinitionKind dk_Alias
The static instance of DefinitionKind indicating that an Interface Repository object is an Alias.

dk_Struct

public static final DefinitionKind dk_Struct
The static instance of DefinitionKind indicating that an Interface Repository object is a Struct.

dk_Union

public static final DefinitionKind dk_Union
The static instance of DefinitionKind indicating that an Interface Repository object is a Union.

dk_Enum

public static final DefinitionKind dk_Enum
The static instance of DefinitionKind indicating that an Interface Repository object is an Enum.

dk_Primitive

public static final DefinitionKind dk_Primitive
The static instance of DefinitionKind indicating that an Interface Repository object is a Primitive.

dk_String

public static final DefinitionKind dk_String
The static instance of DefinitionKind indicating that an Interface Repository object is a String.

dk_Sequence

public static final DefinitionKind dk_Sequence
The static instance of DefinitionKind indicating that an Interface Repository object is a Sequence.

dk_Array

public static final DefinitionKind dk_Array
The static instance of DefinitionKind indicating that an Interface Repository object is an Array.

dk_Repository

public static final DefinitionKind dk_Repository
The static instance of DefinitionKind indicating that an Interface Repository object is a Repository.

dk_Wstring

public static final DefinitionKind dk_Wstring
The static instance of DefinitionKind indicating that an Interface Repository object is a Wstring.

dk_Fixed

public static final DefinitionKind dk_Fixed
The static instance of DefinitionKind indicating that an Interface Repository object is a Fixed value.

dk_Value

public static final DefinitionKind dk_Value
The static instance of DefinitionKind indicating that an Interface Repository object is a Value.

dk_ValueBox

public static final DefinitionKind dk_ValueBox
The static instance of DefinitionKind indicating that an Interface Repository object is a ValueBox.

dk_ValueMember

public static final DefinitionKind dk_ValueMember
The static instance of DefinitionKind indicating that an Interface Repository object is a ValueMember.

dk_Native

public static final DefinitionKind dk_Native
The static instance of DefinitionKind indicating that an Interface Repository object is a Native value.

dk_AbstractInterface

public static final DefinitionKind dk_AbstractInterface
The static instance of DefinitionKind indicating that an Interface Repository object represents an abstract interface.

Constructor Detail

DefinitionKind

protected DefinitionKind(int _value)
Constructs a DefinitionKind object with its _value field initialized with the given value.

Parameters:
_value - one of the int constants defined in the class DefinitionKind
Method Detail

value

public int value()
Returns the int constant identifying the type of an IR object.

Returns:
the int constant from the class DefinitionKind that is the value of this DefinitionKind instance

from_int

public static DefinitionKind from_int(int i)
Creates a DefinitionKind instance corresponding to the given code .

Parameters:
i - one of the int constants from the class DefinitionKind
Returns:
the DefinitionKind instance corresponding to the given code
Throws:
BAD_PARAM - if the given parameter is not one of the int constants from the class DefinitionKind
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefinitionKindHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class DefinitionKindHelper

java.lang.Object
    extended by  org.omg.CORBA.DefinitionKindHelper

public abstract class DefinitionKindHelper
extends Object

The Helper for DefinitionKind. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/DefinitionKindHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ir.idl 03 June 1999 11:33:43 o'clock GMT+00:00

Constructor Summary
DefinitionKindHelper()
Method Summary
static DefinitionKind | extract(Any a)
static String | id()
static void | insert(Any a, DefinitionKind that)
static DefinitionKind | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, DefinitionKind value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefinitionKindHelper

public DefinitionKindHelper()
Method Detail

insert

public static void insert(Any a,
                          DefinitionKind that)

extract

public static DefinitionKind extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static DefinitionKind read(InputStream istream)

write

public static void write(OutputStream ostream,
                         DefinitionKind value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IDL-to-Java Generated Files

The files that are generated by the IDL-to-Java compiler, in accordance with the IDL-to-Java Language Mapping Specification, which is implemented in JavaTM SE 6 according the compliance document.

In general IDL names and identifiers are mapped to Java names and identifiers with no change. Because of the nature of the Java language, a single IDL construct may be mapped to several (differently named) Java constructs. The additional names are constructed by appending a descriptive suffix. For example, the IDL interface foo is mapped to the Java interfaces foo and fooOperations, and additional Java classes fooHelper, fooHolder, fooPOA, and optionally fooPOATie.

The mapping in effect reserves the use of several names for its own purposes. These are:

  • The Java class <type>Helper, where <type> is the name of an IDL defined type.
  • The Java class <type>Holder, where <type> is the name of an IDL defined type (with certain exceptions such as typedef aliases).
  • The Java classes <basicJavaType>Holder, where <basicJavaType> is one of the Java primitive datatypes that is used by one of the IDL basic datatypes.
  • The Java classes <interface>Operations, <interface>POA, and <interface>POATie, where <interface> is the name of an IDL interface type.
  • The nested scope Java package name <interface>Package, where <interface> is the name of an IDL interface.

    Helper Files

    Helper files supply several static methods needed to manipulate the type. These include Any insert and extract operations for the type, getting the repository id, getting the typecode, and reading and writing the type from and to a stream.

    The helper class for a mapped IDL interface or abstract interface also include narrow operation(s). The static narrow method allows an org.omg.CORBA.Object to be narrowed to the object reference of a more specific type. The IDL exception CORBA::BAD_PARAM is thrown if the narrow fails because the object reference does not support the requested type. A different system exception is raised to indicate other kinds of errors. Trying to narrow a null will always succeed with a return value of null.

    Holder Files

    Support for out and inout parameter passing modes requires the use of additional holder classes. These classes are available for all of the basic IDL datatypes in the org.omg.CORBA package and are generated for all named user defined IDL types except those defined by typedefs. (Note that in this context user defined includes types that are defined in OMG specifications such as those for the Interface Repository, and other OMG services.)

    Each holder class has a constructor from an instance, a default constructor, and has a public instance member, value which is the typed value. The default constructor sets the value field to the default value for the type as defined by the Java language: false for boolean, 0 for numeric and char types, null for strings, null for object references.

    To support portable stubs and skeletons, holder classes also implement the org.omg.CORBA.portable.Streamable interface.

    Operations Files

    A non abstract IDL interface is mapped to two public Java interfaces: a signature interface and an operations interface. The signature interface, which extends IDLEntity, has the same name as the IDL interface name and is used as the signature type in method declarations when interfaces of the specified type are used in other interfaces. The operations interface has the same name as the IDL interface with the suffix Operations appended to the end and is used in the server-side mapping and as a mechanism for providing optimized calls for collocated client and servers.

    The Java operations interface contains the mapped operation signatures. The Java signature interface extends the operations interface, the (mapped) base org.omg.CORBA.Object, as well as org.omg.portable.IDLEntity. Methods can be invoked on the signature interface. Interface inheritance expressed in IDL is reflected in both the Java signature interface and operations interface hierarchies.

    Stubs

    For the mapping of a non-object-oriented language, there will be a programming interface to the stubs for each interface type. Generally, the stubs will present access to the OMG IDL-defined operations on an object in a way that is easy for programmers to predict once they are familiar with OMG IDL and the language mapping for the particular programming language. The stubs make calls on the rest of the ORB using interfaces that are private to, and presumably optimized for, the particular ORB Core. If more than one ORB is available, there may be different stubs corresponding to the different ORBs. In this case, it is necessary for the ORB and language mapping to cooperate to associate the correct stubs with the particular object reference.

    Object-oriented programming languages, such as Java, C++, and Smalltalk, do not require stub interfaces.


Official Specifications for CORBA support in Java[tm] SE 6

Specification References

The specifications with which the Java[tm] Platform, Standard Edition (Java SE) v.1.6.0 ORB complies are as follows. If these links do not take you to the referenced specification, the OMG may have changed the URL, and you can link to www.omg.org to search for the correct specification.
  • CORBA 2.3.1 (formal/99-10-07)
  • IDL to Java language mapping (ptc/00-01-08)
  • Revised IDL to Java language mapping (ptc/00-11-03)
  • Java to IDL language mapping (ptc/00-01-06)
  • Interoperable Naming Service (ptc/00-08-07)
  • Portable Interceptors (ptc/2001-03-04)
These are the only specifications referenced by this document.

Supported Specification Details

Not all of the above specifications are currently implemented in the ORB in Java[tm] SE 6. The precise list of supported sections is as follows:
  • CORBA 2.3.1 chapters 1-3 and 6-9
  • Revised IDL to Java language mapping, section 1.21.8.2, the orb.properties file.
  • CORBA 2.3.1 chapter 4 with the following replacements from the Portable Interceptors specification:
    • section 4.2.3.5 destroy
    • section 4.5.2 CodeFactory and PICurrent are required
    • Section 4.5.3.4 as updated for register_initial_reference
  • CORBA 2.3.1 chapter 5 with the following update from the Portable Interceptors specification:
    • 5.5.2 StringSeq and WStringSeq are required. This adds the following classes to org.omg.CORBA:
      • StringSeqHolder
      • StringSeqHelper
      • WStringSeqHolder
      • WStringSeqHelper
  • CORBA 2.3.1 sections 10.6.1 and 10.6.2 are supported for repository IDs.
  • CORBA 2.3.1 section 10.7 for TypeCode APIs.
  • CORBA 2.3.1 chapter 11, Portable Object Adapter (POA), with the following updates from the Portable Interceptors specification:
    • Section 11.3.7 POAs must preserve all policies
    • Section 11.3.8.2 again states that POAs must preserve all policies
    • Section 11.3.8.26 POA::id is required.
  • CORBA 2.3.1 chapters 13 and 15 define GIOP 1.0, 1.1, and 1.2. The Java SE 6 ORB fully supports all versions of GIOP, with the exception that the bi-directional GIOP feature defined in sections 15.8 and 15.9 is not supported.
  • All of the Interoperable Naming Service is supported.
  • Portable Interceptors section 13.8 (the new Coder/Decoder interfaces) and all of chapter 21 (the interceptor specification).
  • Section 1.21.8 of the Revised IDL to Java Language Mapping Specification (ptc/00-11-03) has been changed from the version in the IDL to Java Language Mapping Specification (ptc/00-01-08).

Tools

  • The IDL to Java compiler (idlj) complies with:
    • CORBA 2.3.1 chapter 3 (IDL definition)
    • CORBA 2.3.1 chapters 5 and 6 (semantics of Value types)
    • CORBA 2.3.1 section 10.6.5 (pragmas)
    • The IDL to Java mapping specification
    • The Revised IDL to Java language mapping specification section 1.12.1 "local interfaces"
  • The Java to IDL compiler (the IIOP backend for rmic) complies with:
    • CORBA 2.3.1 chapters 5 and 6 (value types)
    • The Java to IDL language mapping. Note that this implicitly references section 1.21 of the IDL to Java language mapping
    • IDL generated by the -idl flag complies with CORBA 2.3.1 chapter 3.


DomainManagerOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface DomainManagerOperations

All Known Subinterfaces:
DomainManager
public interface DomainManagerOperations

Provides the DomainManager with the means to access policies.

The DomainManager has associated with it the policy objects for a particular domain. The domain manager also records the membership of the domain and provides the means to add and remove members. The domain manager is itself a member of a domain, possibly the domain it manages. The domain manager provides mechanisms for establishing and navigating relationships to superior and subordinate domains and creating and accessing policies.

Method Summary
 Policy get_domain_policy(int policy_type)
This returns the policy of the specified type for objects in this domain.

Method Detail

get_domain_policy

Policy get_domain_policy(int policy_type)
This returns the policy of the specified type for objects in this domain. The types of policies available are domain specific. See the CORBA specification for a list of standard ORB policies.

Parameters:
policy_type - Type of policy to request
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DoubleHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class DoubleHolder

java.lang.Object
    extended by  org.omg.CORBA.DoubleHolder
All Implemented Interfaces:
Streamable
public final class DoubleHolder
extends Object
implements Streamable

The Holder for Double. For more information on Holder files, see "Generated Files: Holder Files".

A Holder class for a double that is used to store "out" and "inout" parameters in IDL methods. If an IDL method signature has an IDL double as an "out" or "inout" parameter, the programmer must pass an instance of DoubleHolder as the corresponding parameter in the method invocation; for "inout" parameters, the programmer must also fill the "in" value to be sent to the server. Before the method invocation returns, the ORB will fill in the value corresponding to the "out" value returned from the server.

If myDoubleHolder is an instance of DoubleHolder, the value stored in its value field can be accessed with myDoubleHolder.value.

Since:
JDK1.2

Field Summary
 double value
The double value held by this DoubleHolder object.
Constructor Summary
DoubleHolder()
Constructs a new DoubleHolder object with its value field initialized to 0.0.
DoubleHolder(double initial)
Constructs a new DoubleHolder object for the given double.
Method Summary
void | _read(InputStream input) Read a double value from the input stream and store it in the value member.
TypeCode | _type() Return the TypeCode of this holder object.
void | _write(OutputStream output) Write the double value stored in this holder to an OutputStream.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public double value
The double value held by this DoubleHolder object.

Constructor Detail

DoubleHolder

public DoubleHolder()
Constructs a new DoubleHolder object with its value field initialized to 0.0.

DoubleHolder

public DoubleHolder(double initial)
Constructs a new DoubleHolder object for the given double.

Parameters:
initial - the double with which to initialize the value field of the new DoubleHolder object
Method Detail

_read

public void _read(InputStream input)
Read a double value from the input stream and store it in the value member.

Specified by:
_read in interface Streamable
Parameters:
input - the InputStream to read from.

_write

public void _write(OutputStream output)
Write the double value stored in this holder to an OutputStream.

Specified by:
_write in interface Streamable
Parameters:
output - the OutputStream to write into.

_type

public TypeCode _type()
Return the TypeCode of this holder object.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DoubleSeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class DoubleSeqHelper

java.lang.Object
    extended by  org.omg.CORBA.DoubleSeqHelper

public abstract class DoubleSeqHelper
extends Object

The Helper for DoubleSeq. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/DoubleSeqHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:37 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications :

  • ORB core as defined by CORBA 2.3.1 (formal/99-10-07)
  • IDL/Java Language Mapping as defined in ptc/00-01-08

Constructor Summary
DoubleSeqHelper()
Method Summary
static double[] | extract(Any a)
static String | id()
static void | insert(Any a, double[] that)
static double[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, double[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DoubleSeqHelper

public DoubleSeqHelper()
Method Detail

insert

public static void insert(Any a,
                          double[] that)

extract

public static double[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static double[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         double[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DoubleSeqHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class DoubleSeqHolder

java.lang.Object
    extended by  org.omg.CORBA.DoubleSeqHolder
All Implemented Interfaces:
Streamable
public final class DoubleSeqHolder
extends Object
implements Streamable

The Holder for DoubleSeq. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/DoubleSeqHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:37 o'clock GMT+00:00

Field Summary
 double[] value
Constructor Summary
DoubleSeqHolder()
DoubleSeqHolder(double[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public double[] value
Constructor Detail

DoubleSeqHolder

public DoubleSeqHolder()

DoubleSeqHolder

public DoubleSeqHolder(double[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynamicImplementation

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class DynamicImplementation

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.CORBA.DynamicImplementation
All Implemented Interfaces:
Object
Direct Known Subclasses:
_BindingIteratorImplBase, _NamingContextImplBase
Deprecated. org.omg.CORBA.DynamicImplementation

@Deprecated
public class DynamicImplementation
extends ObjectImpl

Constructor Summary
DynamicImplementation()
Deprecated.
Method Summary
String[] | _ids() Deprecated. Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
void | invoke(ServerRequest request) Deprecated. Deprecated by Portable Object Adapter
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DynamicImplementation

public DynamicImplementation()
Deprecated.
Method Detail

invoke

@Deprecated
public void invoke(ServerRequest request)
Deprecated. Deprecated by Portable Object Adapter

_ids

public String[] _ids()
Deprecated.
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Specified by:
_ids in class ObjectImpl
Returns:
the array of all repository identifiers supported by this ObjectImpl instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynAny

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface DynAny

All Superinterfaces:
Object
All Known Subinterfaces:
DynArray, DynEnum, DynFixed, DynSequence, DynStruct, DynUnion, DynValue
Deprecated. Use the new DynAny instead

@Deprecated
public interface DynAny
extends Object

Enables org.omg.CORBA.Any values to be dynamically interpreted (traversed) and constructed. A DynAny object is associated with a data value which may correspond to a copy of the value inserted into an Any. The DynAny APIs enable traversal of the data value associated with an Any at runtime and extraction of the primitive constituents of the data value.

Method Summary
void | assign(DynAny dyn_any) Deprecated. Copy the contents from one Dynamic Any into another.
DynAny | copy() Deprecated. Clones this DynAny object.
DynAny | current_component() Deprecated. Returns a DynAny object reference that can be used to get/set the value of the component currently accessed.
void | destroy() Deprecated. Destroys this DynAny object and frees any resources used to represent the data value associated with it.
void | from_any(Any value) Deprecated. Make a DynAny object from an Any object.
Any | get_any() Deprecated. Retrieves the org.omg.CORBA.Any contained in this DynAny object.
boolean | get_boolean() Deprecated. Retrieves the boolean contained in this DynAny object.
char | get_char() Deprecated. Retrieves the char contained in this DynAny object.
double | get_double() Deprecated. Retrieves the double contained in this DynAny object.
float | get_float() Deprecated. Retrieves the float contained in this DynAny object.
int | get_long() Deprecated. Retrieves the int contained in this DynAny object.
long | get_longlong() Deprecated. Retrieves the long contained in this DynAny object.
byte | get_octet() Deprecated. Retrieves the byte contained in this DynAny object.
Object | get_reference() Deprecated. Retrieves the org.omg.CORBA.Other contained in this DynAny object.
short | get_short() Deprecated. Retrieves the short contained in this DynAny object.
String | get_string() Deprecated. Retrieves the String contained in this DynAny object.
TypeCode | get_typecode() Deprecated. Retrieves the org.omg.CORBA.TypeCode contained in this DynAny object.
int | get_ulong() Deprecated. Retrieves the int contained in this DynAny object.
long | get_ulonglong() Deprecated. Retrieves the long contained in this DynAny object.
short | get_ushort() Deprecated. Retrieves the short contained in this DynAny object.
Serializable | get_val() Deprecated. Retrieves the java.io.Serializable object contained in this DynAny object.
char | get_wchar() Deprecated. Retrieves the char contained in this DynAny object.
String | get_wstring() Deprecated. Retrieves the String contained in this DynAny object.
void | insert_any(Any value) Deprecated. Inserts the given org.omg.CORBA.Any object as the value for this DynAny object.
void | insert_boolean(boolean value) Deprecated. Inserts the given boolean as the value for this DynAny object.
void | insert_char(char value) Deprecated. Inserts the given char as the value for this DynAny object.
void | insert_double(double value) Deprecated. Inserts the given double as the value for this DynAny object.
void | insert_float(float value) Deprecated. Inserts the given float as the value for this DynAny object.
void | insert_long(int value) Deprecated. Inserts the given int as the value for this DynAny object.
void | insert_longlong(long value) Deprecated. Inserts the given long as the value for this DynAny object.
void | insert_octet(byte value) Deprecated. Inserts the given byte as the value for this DynAny object.
void | insert_reference(Object value) Deprecated. Inserts the given org.omg.CORBA.Object as the value for this DynAny object.
void | insert_short(short value) Deprecated. Inserts the given short as the value for this DynAny object.
void | insert_string(String value) Deprecated. Inserts the given String object as the value for this DynAny object.
void | insert_typecode(TypeCode value) Deprecated. Inserts the given org.omg.CORBA.TypeCode as the value for this DynAny object.
void | insert_ulong(int value) Deprecated. Inserts the given int as the value for this DynAny object.
void | insert_ulonglong(long value) Deprecated. Inserts the given long as the value for this DynAny object.
void | insert_ushort(short value) Deprecated. Inserts the given short as the value for this DynAny object.
void | insert_val(Serializable value) Deprecated. Inserts the given java.io.Serializable object as the value for this DynAny object.
void | insert_wchar(char value) Deprecated. Inserts the given char as the value for this DynAny object.
void | insert_wstring(String value) Deprecated. Inserts the given String as the value for this DynAny object.
boolean | next() Deprecated. Moves to the next component of this DynAny object.
void | rewind() Deprecated. Moves the internal pointer to the first component.
boolean | seek(int index) Deprecated. Moves the internal pointer to the given index.
Any | to_any() Deprecated. Convert a DynAny object to an Any object.
TypeCode | type() Deprecated. Returns the TypeCode of the object inserted into this DynAny.
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Method Detail

type

TypeCode type()
Deprecated.
Returns the TypeCode of the object inserted into this DynAny.

Returns:
the TypeCode object.

assign

void assign(DynAny dyn_any)
            throws Invalid
Deprecated.
Copy the contents from one Dynamic Any into another.

Parameters:
dyn_any - the DynAny object whose contents are assigned to this DynAny.
Throws:
Invalid - if the source DynAny is invalid

from_any

void from_any(Any value)
              throws Invalid
Deprecated.
Make a DynAny object from an Any object.

Parameters:
value - the Any object.
Throws:
Invalid - if the source Any object is empty or bad

to_any

Any to_any()
           throws Invalid
Deprecated.
Convert a DynAny object to an Any object.

Returns:
the Any object.
Throws:
Invalid - if this DynAny is empty or bad. created or does not contain a meaningful value

destroy

void destroy()
Deprecated.
Destroys this DynAny object and frees any resources used to represent the data value associated with it. This method also destroys all DynAny objects obtained from it.

Destruction of DynAny objects should be handled with care, taking into account issues dealing with the representation of data values associated with DynAny objects. A programmer who wants to destroy a DynAny object but still be able to manipulate some component of the data value associated with it, should first create a DynAny object for the component and then make a copy of the created DynAny object.

copy

DynAny copy()
Deprecated.
Clones this DynAny object.

Returns:
a copy of this DynAny object

insert_boolean

void insert_boolean(boolean value)
                    throws InvalidValue
Deprecated.
Inserts the given boolean as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the boolean to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

insert_octet

void insert_octet(byte value)
                  throws InvalidValue
Deprecated.
Inserts the given byte as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the byte to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

insert_char

void insert_char(char value)
                 throws InvalidValue
Deprecated.
Inserts the given char as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the char to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

insert_short

void insert_short(short value)
                  throws InvalidValue
Deprecated.
Inserts the given short as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the short to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

insert_ushort

void insert_ushort(short value)
                   throws InvalidValue
Deprecated.
Inserts the given short as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the short to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

insert_long

void insert_long(int value)
                 throws InvalidValue
Deprecated.
Inserts the given int as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the int to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

insert_ulong

void insert_ulong(int value)
                  throws InvalidValue
Deprecated.
Inserts the given int as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the int to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

insert_float

void insert_float(float value)
                  throws InvalidValue
Deprecated.
Inserts the given float as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the float to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

insert_double

void insert_double(double value)
                   throws InvalidValue
Deprecated.
Inserts the given double as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the double to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

insert_string

void insert_string(String value)
                   throws InvalidValue
Deprecated.
Inserts the given String object as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the String to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

insert_reference

void insert_reference(Object value)
                      throws InvalidValue
Deprecated.
Inserts the given org.omg.CORBA.Object as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the org.omg.CORBA.Object to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

insert_typecode

void insert_typecode(TypeCode value)
                     throws InvalidValue
Deprecated.
Inserts the given org.omg.CORBA.TypeCode as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the org.omg.CORBA.TypeCode to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

insert_longlong

void insert_longlong(long value)
                     throws InvalidValue
Deprecated.
Inserts the given long as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the long to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

insert_ulonglong

void insert_ulonglong(long value)
                      throws InvalidValue
Deprecated.
Inserts the given long as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the long to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

insert_wchar

void insert_wchar(char value)
                  throws InvalidValue
Deprecated.
Inserts the given char as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the char to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

insert_wstring

void insert_wstring(String value)
                    throws InvalidValue
Deprecated.
Inserts the given String as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the String to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

insert_any

void insert_any(Any value)
                throws InvalidValue
Deprecated.
Inserts the given org.omg.CORBA.Any object as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the org.omg.CORBA.Any object to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

insert_val

void insert_val(Serializable value)
                throws InvalidValue
Deprecated.
Inserts the given java.io.Serializable object as the value for this DynAny object.

If this method is called on a constructed DynAny object, it initializes the next component of the constructed data value associated with this DynAny object.

Parameters:
value - the java.io.Serializable object to insert into this DynAny object
Throws:
InvalidValue - if the value inserted is not consistent with the type of the accessed component in this DynAny object

get_val

Serializable get_val()
                     throws TypeMismatch
Deprecated.
Retrieves the java.io.Serializable object contained in this DynAny object.

Returns:
the java.io.Serializable object that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for a java.io.Serializable object

get_boolean

boolean get_boolean()
                    throws TypeMismatch
Deprecated.
Retrieves the boolean contained in this DynAny object.

Returns:
the boolean that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for a boolean

get_octet

byte get_octet()
               throws TypeMismatch
Deprecated.
Retrieves the byte contained in this DynAny object.

Returns:
the byte that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for a byte

get_char

char get_char()
              throws TypeMismatch
Deprecated.
Retrieves the char contained in this DynAny object.

Returns:
the char that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for a char

get_short

short get_short()
                throws TypeMismatch
Deprecated.
Retrieves the short contained in this DynAny object.

Returns:
the short that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for a short

get_ushort

short get_ushort()
                 throws TypeMismatch
Deprecated.
Retrieves the short contained in this DynAny object.

Returns:
the short that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for a short

get_long

int get_long()
             throws TypeMismatch
Deprecated.
Retrieves the int contained in this DynAny object.

Returns:
the int that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for a int

get_ulong

int get_ulong()
              throws TypeMismatch
Deprecated.
Retrieves the int contained in this DynAny object.

Returns:
the int that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for a int

get_float

float get_float()
                throws TypeMismatch
Deprecated.
Retrieves the float contained in this DynAny object.

Returns:
the float that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for a float

get_double

double get_double()
                  throws TypeMismatch
Deprecated.
Retrieves the double contained in this DynAny object.

Returns:
the double that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for a double

get_string

String get_string()
                  throws TypeMismatch
Deprecated.
Retrieves the String contained in this DynAny object.

Returns:
the String that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for a String

get_reference

Object get_reference()
                     throws TypeMismatch
Deprecated.
Retrieves the org.omg.CORBA.Other contained in this DynAny object.

Returns:
the org.omg.CORBA.Other that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for an org.omg.CORBA.Other

get_typecode

TypeCode get_typecode()
                      throws TypeMismatch
Deprecated.
Retrieves the org.omg.CORBA.TypeCode contained in this DynAny object.

Returns:
the org.omg.CORBA.TypeCode that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for a org.omg.CORBA.TypeCode

get_longlong

long get_longlong()
                  throws TypeMismatch
Deprecated.
Retrieves the long contained in this DynAny object.

Returns:
the long that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for a long

get_ulonglong

long get_ulonglong()
                   throws TypeMismatch
Deprecated.
Retrieves the long contained in this DynAny object.

Returns:
the long that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for a long

get_wchar

char get_wchar()
               throws TypeMismatch
Deprecated.
Retrieves the char contained in this DynAny object.

Returns:
the char that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for a char

get_wstring

String get_wstring()
                   throws TypeMismatch
Deprecated.
Retrieves the String contained in this DynAny object.

Returns:
the String that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for a String

get_any

Any get_any()
            throws TypeMismatch
Deprecated.
Retrieves the org.omg.CORBA.Any contained in this DynAny object.

Returns:
the org.omg.CORBA.Any that is the value for this DynAny object
Throws:
TypeMismatch - if the type code of the accessed component in this DynAny object is not equivalent to the type code for an org.omg.CORBA.Any

current_component

DynAny current_component()
Deprecated.
Returns a DynAny object reference that can be used to get/set the value of the component currently accessed. The appropriate insert method can be called on the resulting DynAny object to initialize the component. The appropriate get method can be called on the resulting DynAny object to extract the value of the component.

Returns:
a DynAny object reference that can be used to retrieve or set the value of the component currently accessed

next

boolean next()
Deprecated.
Moves to the next component of this DynAny object. This method is used for iterating through the components of a constructed type, effectively moving a pointer from one component to the next. The pointer starts out on the first component when a DynAny object is created.

Returns:
true if the pointer points to a component; false if there are no more components or this DynAny is associated with a basic type rather than a constructed type

seek

boolean seek(int index)
Deprecated.
Moves the internal pointer to the given index. Logically, this method sets a new offset for this pointer.

Parameters:
index - an int indicating the position to which the pointer should move. The first position is 0.
Returns:
true if the pointer points to a component; false if there is no component at the designated index. If this DynAny object is associated with a basic type, this method returns false for any index other than 0.

rewind

void rewind()
Deprecated.
Moves the internal pointer to the first component.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynAnyPackage

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.CORBA.DynAnyPackage

Provides the exceptions used with the DynAny interface (InvalidValue, Invalid, InvalidSeq, and TypeMismatch).

See:
Description

Exception Summary
Invalid | Invalid is thrown by dynamic any operations when a bad DynAny or Any is passed as a parameter.
InvalidSeq | The InvalidSeq exception is thrown by all operations on dynamic anys that take a sequence (Java array) as an argument, when that sequence is invalid.
InvalidValue |
TypeMismatch | TypeMismatch is thrown by dynamic any accessor methods when type of the actual contents do not match what is trying to be accessed.

Package org.omg.CORBA.DynAnyPackage Description

Provides the exceptions used with the DynAny interface (InvalidValue, Invalid, InvalidSeq, and TypeMismatch).

Since:
JDK1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.CORBA.DynAnyPackage Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.CORBA.DynAnyPackage

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.omg.CORBA.UserException (implements org.omg.CORBA.portable.IDLEntity)
          • org.omg.CORBA.DynAnyPackage.Invalid
          • org.omg.CORBA.DynAnyPackage.InvalidSeq
          • org.omg.CORBA.DynAnyPackage.InvalidValue
          • org.omg.CORBA.DynAnyPackage.TypeMismatch
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.CORBA.DynAnyPackage

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.CORBA.DynAnyPackage

Packages that use org.omg.CORBA.DynAnyPackage
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Classes in org.omg.CORBA.DynAnyPackage used by org.omg.CORBA
Invalid
Invalid is thrown by dynamic any operations when a bad DynAny or Any is passed as a parameter.
InvalidSeq
The InvalidSeq exception is thrown by all operations on dynamic anys that take a sequence (Java array) as an argument, when that sequence is invalid.
InvalidValue
TypeMismatch
TypeMismatch is thrown by dynamic any accessor methods when type of the actual contents do not match what is trying to be accessed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.DynAnyPackage.Invalid

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.DynAnyPackage.Invalid

Packages that use Invalid
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of Invalid in org.omg.CORBA

Methods in org.omg.CORBA that throw Invalid
void | DynAny.assign(DynAny dyn_any) Deprecated. Copy the contents from one Dynamic Any into another.
void | DynAny.from_any(Any value) Deprecated. Make a DynAny object from an Any object.
Any | DynAny.to_any() Deprecated. Convert a DynAny object to an Any object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.DynAnyPackage.InvalidSeq

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.DynAnyPackage.InvalidSeq

Packages that use InvalidSeq
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of InvalidSeq in org.omg.CORBA

Methods in org.omg.CORBA that throw InvalidSeq
void | DynArray.set_elements(Any[] value) Deprecated. Sets the value of this DynArray object to the given array.
void | DynSequence.set_elements(Any[] value) Deprecated. Sets the values of all elements in this sequence with the given array.
void | DynValue.set_members(NameValuePair[] value) Deprecated. Sets the members of the value object this DynValue object represents to the given array of NameValuePair objects.
void | DynStruct.set_members(NameValuePair[] value) Deprecated. Set the members of the struct.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.DynAnyPackage.InvalidValue

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.DynAnyPackage.InvalidValue

Packages that use InvalidValue
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of InvalidValue in org.omg.CORBA

Methods in org.omg.CORBA that throw InvalidValue
void | DynAny.insert_any(Any value) Deprecated. Inserts the given org.omg.CORBA.Any object as the value for this DynAny object.
void | DynAny.insert_boolean(boolean value) Deprecated. Inserts the given boolean as the value for this DynAny object.
void | DynAny.insert_char(char value) Deprecated. Inserts the given char as the value for this DynAny object.
void | DynAny.insert_double(double value) Deprecated. Inserts the given double as the value for this DynAny object.
void | DynAny.insert_float(float value) Deprecated. Inserts the given float as the value for this DynAny object.
void | DynAny.insert_long(int value) Deprecated. Inserts the given int as the value for this DynAny object.
void | DynAny.insert_longlong(long value) Deprecated. Inserts the given long as the value for this DynAny object.
void | DynAny.insert_octet(byte value) Deprecated. Inserts the given byte as the value for this DynAny object.
void | DynAny.insert_reference(Object value) Deprecated. Inserts the given org.omg.CORBA.Object as the value for this DynAny object.
void | DynAny.insert_short(short value) Deprecated. Inserts the given short as the value for this DynAny object.
void | DynAny.insert_string(String value) Deprecated. Inserts the given String object as the value for this DynAny object.
void | DynAny.insert_typecode(TypeCode value) Deprecated. Inserts the given org.omg.CORBA.TypeCode as the value for this DynAny object.
void | DynAny.insert_ulong(int value) Deprecated. Inserts the given int as the value for this DynAny object.
void | DynAny.insert_ulonglong(long value) Deprecated. Inserts the given long as the value for this DynAny object.
void | DynAny.insert_ushort(short value) Deprecated. Inserts the given short as the value for this DynAny object.
void | DynAny.insert_val(Serializable value) Deprecated. Inserts the given java.io.Serializable object as the value for this DynAny object.
void | DynAny.insert_wchar(char value) Deprecated. Inserts the given char as the value for this DynAny object.
void | DynAny.insert_wstring(String value) Deprecated. Inserts the given String as the value for this DynAny object.
void | DynFixed.set_value(byte[] val) Deprecated. Sets the given fixed type instance as the value for this DynFixed object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.DynAnyPackage.TypeMismatch

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.DynAnyPackage.TypeMismatch

Packages that use TypeMismatch
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of TypeMismatch in org.omg.CORBA

Methods in org.omg.CORBA that throw TypeMismatch
Any | DynAny.get_any() Deprecated. Retrieves the org.omg.CORBA.Any contained in this DynAny object.
boolean | DynAny.get_boolean() Deprecated. Retrieves the boolean contained in this DynAny object.
char | DynAny.get_char() Deprecated. Retrieves the char contained in this DynAny object.
double | DynAny.get_double() Deprecated. Retrieves the double contained in this DynAny object.
float | DynAny.get_float() Deprecated. Retrieves the float contained in this DynAny object.
int | DynAny.get_long() Deprecated. Retrieves the int contained in this DynAny object.
long | DynAny.get_longlong() Deprecated. Retrieves the long contained in this DynAny object.
byte | DynAny.get_octet() Deprecated. Retrieves the byte contained in this DynAny object.
Object | DynAny.get_reference() Deprecated. Retrieves the org.omg.CORBA.Other contained in this DynAny object.
short | DynAny.get_short() Deprecated. Retrieves the short contained in this DynAny object.
String | DynAny.get_string() Deprecated. Retrieves the String contained in this DynAny object.
TypeCode | DynAny.get_typecode() Deprecated. Retrieves the org.omg.CORBA.TypeCode contained in this DynAny object.
int | DynAny.get_ulong() Deprecated. Retrieves the int contained in this DynAny object.
long | DynAny.get_ulonglong() Deprecated. Retrieves the long contained in this DynAny object.
short | DynAny.get_ushort() Deprecated. Retrieves the short contained in this DynAny object.
Serializable | DynAny.get_val() Deprecated. Retrieves the java.io.Serializable object contained in this DynAny object.
char | DynAny.get_wchar() Deprecated. Retrieves the char contained in this DynAny object.
String | DynAny.get_wstring() Deprecated. Retrieves the String contained in this DynAny object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Invalid

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.DynAnyPackage
Class Invalid

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CORBA.DynAnyPackage.Invalid
All Implemented Interfaces:
Serializable, IDLEntity
public final class Invalid
extends UserException

Invalid is thrown by dynamic any operations when a bad DynAny or Any is passed as a parameter.

Constructor Summary
Invalid()
Constructs an Invalid object.
Invalid(String reason)
Constructs an Invalid object.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Invalid

public Invalid()
Constructs an Invalid object.

Invalid

public Invalid(String reason)
Constructs an Invalid object.

Parameters:
reason - a String giving more information regarding the bad parameter passed to a dynamic any operation.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


InvalidSeq

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.DynAnyPackage
Class InvalidSeq

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CORBA.DynAnyPackage.InvalidSeq
All Implemented Interfaces:
Serializable, IDLEntity
public final class InvalidSeq
extends UserException

The InvalidSeq exception is thrown by all operations on dynamic anys that take a sequence (Java array) as an argument, when that sequence is invalid.

Constructor Summary
InvalidSeq()
Constructs an InvalidSeq object.
InvalidSeq(String reason)
Constructs an InvalidSeq object.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidSeq

public InvalidSeq()
Constructs an InvalidSeq object.

InvalidSeq

public InvalidSeq(String reason)
Constructs an InvalidSeq object.

Parameters:
reason - a String giving more information regarding the exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.DynAnyPackage
Class InvalidValue

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CORBA.DynAnyPackage.InvalidValue
All Implemented Interfaces:
Serializable, IDLEntity
public final class InvalidValue
extends UserException

Constructor Summary
InvalidValue()
Constructs an InvalidValue object.
InvalidValue(String reason)
Constructs an InvalidValue object.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidValue

public InvalidValue()
Constructs an InvalidValue object.

InvalidValue

public InvalidValue(String reason)
Constructs an InvalidValue object.

Parameters:
reason - a String giving more information regarding the exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TypeMismatch

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.DynAnyPackage
Class TypeMismatch

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CORBA.DynAnyPackage.TypeMismatch
All Implemented Interfaces:
Serializable, IDLEntity
public final class TypeMismatch
extends UserException

TypeMismatch is thrown by dynamic any accessor methods when type of the actual contents do not match what is trying to be accessed.

Constructor Summary
TypeMismatch()
Constructs a TypeMismatch object.
TypeMismatch(String reason)
Constructs a TypeMismatch object.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TypeMismatch

public TypeMismatch()
Constructs a TypeMismatch object.

TypeMismatch

public TypeMismatch(String reason)
Constructs a TypeMismatch object.

Parameters:
reason - a String giving more information regarding the exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


DynArray

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface DynArray

All Superinterfaces:
DynAny, Object
Deprecated. Use the new DynArray instead

@Deprecated
public interface DynArray
extends Object, DynAny

Represents a DynAny object associated with an array.

Method Summary
Any[] | get_elements() Deprecated. Returns the value of all the elements of this array.
void | set_elements(Any[] value) Deprecated. Sets the value of this DynArray object to the given array.
Methods inherited from interface org.omg.CORBA.DynAny
assign, copy, current_component, destroy, from_any, get_any, get_boolean, get_char, get_double, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Method Detail

get_elements

Any[] get_elements()
Deprecated.
Returns the value of all the elements of this array.

Returns:
the array of Any objects that is the value for this DynArray object
See Also:
set_elements(org.omg.CORBA.Any[])

set_elements

void set_elements(Any[] value)
                  throws InvalidSeq
Deprecated.
Sets the value of this DynArray object to the given array.

Parameters:
value - the array of Any objects
Throws:
InvalidSeq - if the sequence is bad
See Also:
get_elements()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynEnum

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface DynEnum

All Superinterfaces:
DynAny, Object
Deprecated. Use the new DynEnum instead

@Deprecated
public interface DynEnum
extends Object, DynAny

Represents a DynAny object associated with an IDL enum.

Method Summary
String | value_as_string() Deprecated. Return the value of the IDL enum stored in this DynEnum as a string.
void | value_as_string(String arg) Deprecated. Set a particular enum in this DynEnum.
int | value_as_ulong() Deprecated. Return the value of the IDL enum as a Java int.
void | value_as_ulong(int arg) Deprecated. Set the value of the IDL enum.
Methods inherited from interface org.omg.CORBA.DynAny
assign, copy, current_component, destroy, from_any, get_any, get_boolean, get_char, get_double, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Method Detail

value_as_string

String value_as_string()
Deprecated.
Return the value of the IDL enum stored in this DynEnum as a string.

Returns:
the stringified value.

value_as_string

void value_as_string(String arg)
Deprecated.
Set a particular enum in this DynEnum.

Parameters:
arg - the string corresponding to the value.

value_as_ulong

int value_as_ulong()
Deprecated.
Return the value of the IDL enum as a Java int.

Returns:
the integer value.

value_as_ulong

void value_as_ulong(int arg)
Deprecated.
Set the value of the IDL enum.

Parameters:
arg - the int value of the enum.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynFixed

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface DynFixed

All Superinterfaces:
DynAny, Object
Deprecated. Use the new DynFixed instead

@Deprecated
public interface DynFixed
extends Object, DynAny

Represents a DynAny object that is associated with an IDL fixed type.

Method Summary
byte[] | get_value() Deprecated. Returns the value of the fixed type represented in this DynFixed object.
void | set_value(byte[] val) Deprecated. Sets the given fixed type instance as the value for this DynFixed object.
Methods inherited from interface org.omg.CORBA.DynAny
assign, copy, current_component, destroy, from_any, get_any, get_boolean, get_char, get_double, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Method Detail

get_value

byte[] get_value()
Deprecated.
Returns the value of the fixed type represented in this DynFixed object.

Returns:
the value as a byte array
See Also:
set_value(byte[])

set_value

void set_value(byte[] val)
               throws InvalidValue
Deprecated.
Sets the given fixed type instance as the value for this DynFixed object.

Parameters:
val - the value of the fixed type as a byte array
Throws:
InvalidValue - if the given argument is bad
See Also:
get_value()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynSequence

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface DynSequence

All Superinterfaces:
DynAny, Object
Deprecated. Use the new DynSequence instead

@Deprecated
public interface DynSequence
extends Object, DynAny

The representation of a DynAny object that is associated with an IDL sequence.

Method Summary
Any[] | get_elements() Deprecated. Returns the value of every element in this sequence.
int | length() Deprecated. Returns the length of the sequence represented by this DynFixed object.
void | length(int arg) Deprecated. Sets the length of the sequence represented by this DynFixed object to the given argument.
void | set_elements(Any[] value) Deprecated. Sets the values of all elements in this sequence with the given array.
Methods inherited from interface org.omg.CORBA.DynAny
assign, copy, current_component, destroy, from_any, get_any, get_boolean, get_char, get_double, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Method Detail

length

int length()
Deprecated.
Returns the length of the sequence represented by this DynFixed object.

Returns:
the length of the sequence

length

void length(int arg)
Deprecated.
Sets the length of the sequence represented by this DynFixed object to the given argument.

Parameters:
arg - the length of the sequence

get_elements

Any[] get_elements()
Deprecated.
Returns the value of every element in this sequence.

Returns:
an array of Any objects containing the values in the sequence
See Also:
set_elements(org.omg.CORBA.Any[])

set_elements

void set_elements(Any[] value)
                  throws InvalidSeq
Deprecated.
Sets the values of all elements in this sequence with the given array.

Parameters:
value - the array of Any objects to be set
Throws:
InvalidSeq - if the array of values is bad
See Also:
get_elements()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynStruct

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface DynStruct

All Superinterfaces:
DynAny, Object
Deprecated. Use the new DynStruct instead

@Deprecated
public interface DynStruct
extends Object, DynAny

The representation of a DynAny object that is associated with an IDL struct.

Method Summary
TCKind | current_member_kind() Deprecated. Returns the TCKind object that describes the kind of the current member.
String | current_member_name() Deprecated. During a traversal, returns the name of the current member.
NameValuePair[] | get_members() Deprecated. Returns an array containing all the members of the stored struct.
void | set_members(NameValuePair[] value) Deprecated. Set the members of the struct.
Methods inherited from interface org.omg.CORBA.DynAny
assign, copy, current_component, destroy, from_any, get_any, get_boolean, get_char, get_double, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Method Detail

current_member_name

String current_member_name()
Deprecated.
During a traversal, returns the name of the current member.

Returns:
the string name of the current member

current_member_kind

TCKind current_member_kind()
Deprecated.
Returns the TCKind object that describes the kind of the current member.

Returns:
the TCKind object that describes the current member

get_members

NameValuePair[] get_members()
Deprecated.
Returns an array containing all the members of the stored struct.

Returns:
the array of name-value pairs
See Also:
set_members(org.omg.CORBA.NameValuePair[])

set_members

void set_members(NameValuePair[] value)
                 throws InvalidSeq
Deprecated.
Set the members of the struct.

Parameters:
value - the array of name-value pairs.
Throws:
InvalidSeq - if the given argument is invalid
See Also:
get_members()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynUnion

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface DynUnion

All Superinterfaces:
DynAny, Object
Deprecated. Use the new DynUnion instead

@Deprecated
public interface DynUnion
extends Object, DynAny

The DynUnion interface represents a DynAny object that is associated with an IDL union. Union values can be traversed using the operations defined in DynAny. The first component in the union corresponds to the discriminator; the second corresponds to the actual value of the union. Calling the method next() twice allows you to access both components.

Method Summary
TCKind | discriminator_kind() Deprecated. Returns the TCKind object associated with the discriminator of this union.
DynAny | discriminator() Deprecated. Returns a DynAny object reference that must be narrowed to the type of the discriminator in order to insert/get the discriminator value.
TCKind | member_kind() Deprecated. Returns the TCKind associated with the member of this union.
String | member_name() Deprecated. Allows for the inspection of the name of this union member without checking the value of the discriminator.
void | member_name(String arg) Deprecated. Allows for the assignment of the name of this union member.
DynAny | member() Deprecated. Returns a DynAny object reference that is used in order to insert/get a member of this union.
boolean | set_as_default() Deprecated. Determines whether the discriminator associated with this union has been assigned a valid default value.
void | set_as_default(boolean arg) Deprecated. Determines whether the discriminator associated with this union gets assigned a valid default value.
Methods inherited from interface org.omg.CORBA.DynAny
assign, copy, current_component, destroy, from_any, get_any, get_boolean, get_char, get_double, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Method Detail

set_as_default

boolean set_as_default()
Deprecated.
Determines whether the discriminator associated with this union has been assigned a valid default value.

Returns:
true if the discriminator has a default value; false otherwise

set_as_default

void set_as_default(boolean arg)
Deprecated.
Determines whether the discriminator associated with this union gets assigned a valid default value.

Parameters:
arg - true if the discriminator gets assigned a default value

discriminator

DynAny discriminator()
Deprecated.
Returns a DynAny object reference that must be narrowed to the type of the discriminator in order to insert/get the discriminator value.

Returns:
a DynAny object reference representing the discriminator value

discriminator_kind

TCKind discriminator_kind()
Deprecated.
Returns the TCKind object associated with the discriminator of this union.

Returns:
the TCKind object associated with the discriminator of this union

member

DynAny member()
Deprecated.
Returns a DynAny object reference that is used in order to insert/get a member of this union.

Returns:
the DynAny object representing a member of this union

member_name

String member_name()
Deprecated.
Allows for the inspection of the name of this union member without checking the value of the discriminator.

Returns:
the name of this union member

member_name

void member_name(String arg)
Deprecated.
Allows for the assignment of the name of this union member.

Parameters:
arg - the new name of this union member

member_kind

TCKind member_kind()
Deprecated.
Returns the TCKind associated with the member of this union.

Returns:
the TCKind object associated with the member of this union
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface DynValue

All Superinterfaces:
DynAny, Object
Deprecated. Use the new DynValue instead

@Deprecated
public interface DynValue
extends Object, DynAny

The representation of a DynAny object that is associated with an IDL value type.

Method Summary
TCKind | current_member_kind() Deprecated. Returns the TCKind object that describes the current member.
String | current_member_name() Deprecated. Returns the name of the current member while traversing a DynAny object that represents a Value object.
NameValuePair[] | get_members() Deprecated. Returns an array containing all the members of the value object stored in this DynValue.
void | set_members(NameValuePair[] value) Deprecated. Sets the members of the value object this DynValue object represents to the given array of NameValuePair objects.
Methods inherited from interface org.omg.CORBA.DynAny
assign, copy, current_component, destroy, from_any, get_any, get_boolean, get_char, get_double, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Method Detail

current_member_name

String current_member_name()
Deprecated.
Returns the name of the current member while traversing a DynAny object that represents a Value object.

Returns:
the name of the current member

current_member_kind

TCKind current_member_kind()
Deprecated.
Returns the TCKind object that describes the current member.

Returns:
the TCKind object corresponding to the current member

get_members

NameValuePair[] get_members()
Deprecated.
Returns an array containing all the members of the value object stored in this DynValue.

Returns:
an array of name-value pairs.
See Also:
set_members(org.omg.CORBA.NameValuePair[])

set_members

void set_members(NameValuePair[] value)
                 throws InvalidSeq
Deprecated.
Sets the members of the value object this DynValue object represents to the given array of NameValuePair objects.

Parameters:
value - the array of name-value pairs to be set
Throws:
InvalidSeq - if an inconsistent value is part of the given array
See Also:
get_members()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Environment

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class Environment

java.lang.Object
    extended by  org.omg.CORBA.Environment

public abstract class Environment
extends Object

A container (holder) for an exception that is used in Request operations to make exceptions available to the client. An Environment object is created with the ORB method create_environment.

Since:
JDK1.2

Constructor Summary
Environment()
Method Summary
abstract void | clear() Clears this Environment object of its exception.
abstract Exception | exception() Retrieves the exception in this Environment object.
abstract void | exception(Exception except) Inserts the given exception into this Environment object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Environment

public Environment()
Method Detail

exception

public abstract Exception exception()
Retrieves the exception in this Environment object.

Returns:
the exception in this Environment object

exception

public abstract void exception(Exception except)
Inserts the given exception into this Environment object.

Parameters:
except - the exception to be set

clear

public abstract void clear()
Clears this Environment object of its exception.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ExceptionList

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ExceptionList

java.lang.Object
    extended by  org.omg.CORBA.ExceptionList

public abstract class ExceptionList
extends Object

An object used in Request operations to describe the exceptions that can be thrown by a method. It maintains a modifiable list of TypeCodes of the exceptions.

The following code fragment demonstrates creating an ExceptionList object:

    ORB orb = ORB.init(args, null);
    org.omg.CORBA.ExceptionList excList = orb.create_exception_list();
The variable excList represents an ExceptionList object with no TypeCode objects in it.

To add items to the list, you first create a TypeCode object for the exception you want to include, using the ORB method create_exception_tc. Then you use the ExceptionList method add to add it to the list. The class ExceptionList has a method for getting the number of TypeCode objects in the list, and after items have been added, it is possible to call methods for accessing or deleting an item at a designated index.

Since:
JDK1.2

Constructor Summary
ExceptionList()
Method Summary
abstract void | add(TypeCode exc) Adds a TypeCode object describing an exception to this ExceptionList object.
abstract int | count() Retrieves the number of TypeCode objects in this ExceptionList object.
abstract TypeCode | item(int index) Returns the TypeCode object at the given index.
abstract void | remove(int index) Removes the TypeCode object at the given index.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ExceptionList

public ExceptionList()
Method Detail

count

public abstract int count()
Retrieves the number of TypeCode objects in this ExceptionList object.

Returns:
the number of TypeCode objects in this ExceptionList object

add

public abstract void add(TypeCode exc)
Adds a TypeCode object describing an exception to this ExceptionList object.

Parameters:
exc - the TypeCode object to be added

item

public abstract TypeCode item(int index)
                       throws Bounds
Returns the TypeCode object at the given index. The first item is at index 0.

Parameters:
index - the index of the TypeCode object desired. This must be an int between 0 and the number of TypeCode objects minus one, inclusive.
Returns:
the TypeCode object at the given index
Throws:
Bounds - if the index given is greater than or equal to the number of TypeCode objects in this ExceptionList object

remove

public abstract void remove(int index)
                     throws Bounds
Removes the TypeCode object at the given index. Note that the indices of all the TypeCoded objects following the one deleted are shifted down by one.

Parameters:
index - the index of the TypeCode object to be removed. This must be an int between 0 and the number of TypeCode objects minus one, inclusive.
Throws:
Bounds - if the index is greater than or equal to the number of TypeCode objects in this ExceptionList object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FieldNameHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class FieldNameHelper

java.lang.Object
    extended by  org.omg.CORBA.FieldNameHelper

public abstract class FieldNameHelper
extends Object

The Helper for FieldName. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/FieldNameHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" 03 June 1999 11:52:03 o'clock GMT+00:00

Constructor Summary
FieldNameHelper()
Method Summary
static String | extract(Any a)
static String | id()
static void | insert(Any a, String that)
static String | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, String value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FieldNameHelper

public FieldNameHelper()
Method Detail

insert

public static void insert(Any a,
                          String that)

extract

public static String extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static String read(InputStream istream)

write

public static void write(OutputStream ostream,
                         String value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FixedHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class FixedHolder

java.lang.Object
    extended by  org.omg.CORBA.FixedHolder
All Implemented Interfaces:
Streamable
public final class FixedHolder
extends Object
implements Streamable

The Holder for Fixed. For more information on Holder files, see "Generated Files: Holder Files".

FixedHolder is a container class for values of IDL type "fixed", which is mapped to the Java class java.math.BigDecimal. It is usually used to store "out" and "inout" IDL method parameters. If an IDL method signature has a fixed as an "out" or "inout" parameter, the programmer must pass an instance of FixedHolder as the corresponding parameter in the method invocation; for "inout" parameters, the programmer must also fill the "in" value to be sent to the server. Before the method invocation returns, the ORB will fill in the contained value corresponding to the "out" value returned from the server.

Field Summary
 BigDecimal value
The value held by the FixedHolder
Constructor Summary
FixedHolder()
Construct the FixedHolder without initializing the contained value.
FixedHolder(BigDecimal initial)
Construct the FixedHolder and initialize it with the given value.
Method Summary
void | _read(InputStream input) Read a fixed point value from the input stream and store it in the value member.
TypeCode | _type() Return the TypeCode of this holder object.
void | _write(OutputStream output) Write the fixed point value stored in this holder to an OutputStream.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public BigDecimal value
The value held by the FixedHolder

Constructor Detail

FixedHolder

public FixedHolder()
Construct the FixedHolder without initializing the contained value.

FixedHolder

public FixedHolder(BigDecimal initial)
Construct the FixedHolder and initialize it with the given value.

Parameters:
initial - the value used to initialize the FixedHolder
Method Detail

_read

public void _read(InputStream input)
Read a fixed point value from the input stream and store it in the value member.

Specified by:
_read in interface Streamable
Parameters:
input - the InputStream to read from.

_write

public void _write(OutputStream output)
Write the fixed point value stored in this holder to an OutputStream.

Specified by:
_write in interface Streamable
Parameters:
output - the OutputStream to write into.

_type

public TypeCode _type()
Return the TypeCode of this holder object.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FloatHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class FloatHolder

java.lang.Object
    extended by  org.omg.CORBA.FloatHolder
All Implemented Interfaces:
Streamable
public final class FloatHolder
extends Object
implements Streamable

The Holder for Float. For more information on Holder files, see "Generated Files: Holder Files".

A Holder class for a float that is used to store "out" and "inout" parameters in IDL methods. If an IDL method signature has an IDL float as an "out" or "inout" parameter, the programmer must pass an instance of FloatHolder as the corresponding parameter in the method invocation; for "inout" parameters, the programmer must also fill the "in" value to be sent to the server. Before the method invocation returns, the ORB will fill in the value corresponding to the "out" value returned from the server.

If myFloatHolder is an instance of FloatHolder, the value stored in its value field can be accessed with myFloatHolder.value.

Since:
JDK1.2

Field Summary
 float value
The float value held by this FloatHolder object.
Constructor Summary
FloatHolder()
Constructs a new FloatHolder object with its value field initialized to 0.0.
FloatHolder(float initial)
Constructs a new FloatHolder object for the given float.
Method Summary
void | _read(InputStream input) Read a float from an input stream and initialize the value member with the float value.
TypeCode | _type() Return the TypeCode of this Streamable.
void | _write(OutputStream output) Write the float value into an output stream.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public float value
The float value held by this FloatHolder object.

Constructor Detail

FloatHolder

public FloatHolder()
Constructs a new FloatHolder object with its value field initialized to 0.0.

FloatHolder

public FloatHolder(float initial)
Constructs a new FloatHolder object for the given float.

Parameters:
initial - the float with which to initialize the value field of the new FloatHolder object
Method Detail

_read

public void _read(InputStream input)
Read a float from an input stream and initialize the value member with the float value.

Specified by:
_read in interface Streamable
Parameters:
input - the InputStream to read from.

_write

public void _write(OutputStream output)
Write the float value into an output stream.

Specified by:
_write in interface Streamable
Parameters:
output - the OutputStream to write into.

_type

public TypeCode _type()
Return the TypeCode of this Streamable.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FloatSeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class FloatSeqHelper

java.lang.Object
    extended by  org.omg.CORBA.FloatSeqHelper

public abstract class FloatSeqHelper
extends Object

The Helper for FloatSeq. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/FloatSeqHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:37 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications :

  • ORB core as defined by CORBA 2.3.1 (formal/99-10-07)
  • IDL/Java Language Mapping as defined in ptc/00-01-08

Constructor Summary
FloatSeqHelper()
Method Summary
static float[] | extract(Any a)
static String | id()
static void | insert(Any a, float[] that)
static float[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, float[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FloatSeqHelper

public FloatSeqHelper()
Method Detail

insert

public static void insert(Any a,
                          float[] that)

extract

public static float[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static float[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         float[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FloatSeqHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class FloatSeqHolder

java.lang.Object
    extended by  org.omg.CORBA.FloatSeqHolder
All Implemented Interfaces:
Streamable
public final class FloatSeqHolder
extends Object
implements Streamable

The Holder for FloatSeq. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/FloatSeqHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:37 o'clock GMT+00:00

Field Summary
 float[] value
Constructor Summary
FloatSeqHolder()
FloatSeqHolder(float[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public float[] value
Constructor Detail

FloatSeqHolder

public FloatSeqHolder()

FloatSeqHolder

public FloatSeqHolder(float[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FREE_MEM

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class FREE_MEM

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.FREE_MEM
All Implemented Interfaces:
Serializable
public final class FREE_MEM
extends SystemException

Exception thrown when the ORB failed in an attempt to free dynamic memory, for example because of heap corruption or memory segments being locked.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
FREE_MEM()
Constructs a FREE_MEM exception with a default minor code of 0 and a completion state of COMPLETED_NO.
FREE_MEM(int minor, CompletionStatus completed)
Constructs a FREE_MEM exception with the specified minor code and completion status.
FREE_MEM(String s)
Constructs a FREE_MEM exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.
FREE_MEM(String s, int minor, CompletionStatus completed)
Constructs a FREE_MEM exception with the specified detail message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

FREE_MEM

public FREE_MEM()
Constructs a FREE_MEM exception with a default minor code of 0 and a completion state of COMPLETED_NO.

FREE_MEM

public FREE_MEM(String s)
Constructs a FREE_MEM exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message

FREE_MEM

public FREE_MEM(int minor,
                CompletionStatus completed)
Constructs a FREE_MEM exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

FREE_MEM

public FREE_MEM(String s,
                int minor,
                CompletionStatus completed)
Constructs a FREE_MEM exception with the specified detail message, minor code, and completion status. A detail message is a String that describes this particular exception.

Parameters:
s - the String containing a detail message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IdentifierHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class IdentifierHelper

java.lang.Object
    extended by  org.omg.CORBA.IdentifierHelper

public abstract class IdentifierHelper
extends Object

The Helper for Identifier. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/IdentifierHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ir.idl 03 June 1999 11:33:42 o'clock GMT+00:00

Constructor Summary
IdentifierHelper()
Method Summary
static String | extract(Any a)
static String | id()
static void | insert(Any a, String that)
static String | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, String value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IdentifierHelper

public IdentifierHelper()
Method Detail

insert

public static void insert(Any a,
                          String that)

extract

public static String extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static String read(InputStream istream)

write

public static void write(OutputStream ostream,
                         String value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IDLTypeHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class IDLTypeHelper

java.lang.Object
    extended by  org.omg.CORBA.IDLTypeHelper

public abstract class IDLTypeHelper
extends Object

The Helper for IDLType. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/IDLTypeHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ir.idl 03 June 1999 11:33:44 o'clock GMT+00:00

Constructor Summary
IDLTypeHelper()
Method Summary
static IDLType | extract(Any a)
static String | id()
static void | insert(Any a, IDLType that)
static IDLType | narrow(Object obj)
static IDLType | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, IDLType value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IDLTypeHelper

public IDLTypeHelper()
Method Detail

insert

public static void insert(Any a,
                          IDLType that)

extract

public static IDLType extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static IDLType read(InputStream istream)

write

public static void write(OutputStream ostream,
                         IDLType value)

narrow

public static IDLType narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IDLTypeOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface IDLTypeOperations

All Superinterfaces:
IRObjectOperations
All Known Subinterfaces:
IDLType
All Known Implementing Classes:
_IDLTypeStub
public interface IDLTypeOperations
extends IRObjectOperations

This interface must be implemented by all IDLType objects. The IDLType is inherited by all IR objects that represent IDL types, including interfaces, typedefs, and anonymous types.

See Also:
IDLType, IRObject, IRObjectOperations

Method Summary
 TypeCode type()
The type attribute describes the type defined by an object derived from IDLType.
Methods inherited from interface org.omg.CORBA.IRObjectOperations
def_kind, destroy

Method Detail

type

TypeCode type()
The type attribute describes the type defined by an object derived from IDLType.

Returns:
the TypeCode defined by this object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IMP_LIMIT

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class IMP_LIMIT

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.IMP_LIMIT
All Implemented Interfaces:
Serializable
public final class IMP_LIMIT
extends SystemException

This exception indicates that an implementation limit was exceeded in the ORB run time. For example, an ORB may reach the maximum number of references it can hold simultaneously in an address space, the size of a parameter may have exceeded the allowed maximum, or an ORB may impose a maximum on the number of clients or servers that can run simultaneously.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
IMP_LIMIT()
Constructs an IMP_LIMIT exception with a default minor code of 0 and a completion state of COMPLETED_NO.
IMP_LIMIT(int minor, CompletionStatus completed)
Constructs an IMP_LIMIT exception with the specified minor code and completion status.
IMP_LIMIT(String s)
Constructs an IMP_LIMIT exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.
IMP_LIMIT(String s, int minor, CompletionStatus completed)
Constructs an IMP_LIMIT exception with the specified detail message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

IMP_LIMIT

public IMP_LIMIT()
Constructs an IMP_LIMIT exception with a default minor code of 0 and a completion state of COMPLETED_NO.

IMP_LIMIT

public IMP_LIMIT(String s)
Constructs an IMP_LIMIT exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message

IMP_LIMIT

public IMP_LIMIT(int minor,
                 CompletionStatus completed)
Constructs an IMP_LIMIT exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

IMP_LIMIT

public IMP_LIMIT(String s,
                 int minor,
                 CompletionStatus completed)
Constructs an IMP_LIMIT exception with the specified detail message, minor code, and completion status. A detail message is a String that describes this particular exception.

Parameters:
s - the String containing a detail message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


INITIALIZE

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class INITIALIZE

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.INITIALIZE
All Implemented Interfaces:
Serializable
public final class INITIALIZE
extends SystemException

Exception thrown when an ORB has encountered a failure during its initialization, such as failure to acquire networking resources or detecting a configuration error.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
INITIALIZE()
Constructs an INITIALIZE exception with a default minor code of 0 and a completion state of CompletionStatus.COMPLETED_NO.
INITIALIZE(int minor, CompletionStatus completed)
Constructs an INITIALIZE exception with the specified minor code and completion status.
INITIALIZE(String s)
Constructs an INITIALIZE exception with the specified detail message, a minor code of 0, and a completion state of CompletionStatus.COMPLETED_NO.
INITIALIZE(String s, int minor, CompletionStatus completed)
Constructs an INITIALIZE exception with the specified detail message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

INITIALIZE

public INITIALIZE()
Constructs an INITIALIZE exception with a default minor code of 0 and a completion state of CompletionStatus.COMPLETED_NO.

INITIALIZE

public INITIALIZE(String s)
Constructs an INITIALIZE exception with the specified detail message, a minor code of 0, and a completion state of CompletionStatus.COMPLETED_NO.

Parameters:
s - the String containing a detail message

INITIALIZE

public INITIALIZE(int minor,
                  CompletionStatus completed)
Constructs an INITIALIZE exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - an instance of CompletionStatus indicating the completion status of the method that threw this exception

INITIALIZE

public INITIALIZE(String s,
                  int minor,
                  CompletionStatus completed)
Constructs an INITIALIZE exception with the specified detail message, minor code, and completion status. A detail message is a String that describes this particular exception.

Parameters:
s - the String containing a detail message
minor - the minor code
completed - an instance of CompletionStatus indicating the completion status of the method that threw this exception
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


INTERNAL

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class INTERNAL

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.INTERNAL
All Implemented Interfaces:
Serializable
public final class INTERNAL
extends SystemException

This exception indicates an internal failure in an ORB, for example, if an ORB has detected corruption of its internal data structures.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

See the section meaning of minor codes to see the minor codes for this exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
INTERNAL()
Constructs an INTERNAL exception with a default minor code of 0 and a completion state of COMPLETED_NO.
INTERNAL(int minor, CompletionStatus completed)
Constructs an INTERNAL exception with the specified minor code and completion status.
INTERNAL(String s)
Constructs an INTERNAL exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.
INTERNAL(String s, int minor, CompletionStatus completed)
Constructs an INTERNAL exception with the specified detail message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

INTERNAL

public INTERNAL()
Constructs an INTERNAL exception with a default minor code of 0 and a completion state of COMPLETED_NO.

INTERNAL

public INTERNAL(String s)
Constructs an INTERNAL exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message

INTERNAL

public INTERNAL(int minor,
                CompletionStatus completed)
Constructs an INTERNAL exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - an instance of CompletionStatus that indicates the completion status of the method that threw this exception

INTERNAL

public INTERNAL(String s,
                int minor,
                CompletionStatus completed)
Constructs an INTERNAL exception with the specified detail message, minor code, and completion status. A detail message is a String that describes this particular exception.

Parameters:
s - the String containing a detail message
minor - the minor code
completed - an instance of CompletionStatus that indicates the completion status of the method that threw this exception
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


INTF_REPOS

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class INTF_REPOS

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.INTF_REPOS
All Implemented Interfaces:
Serializable
public final class INTF_REPOS
extends SystemException

Exception raised when an ORB cannot reach the interface repository, or some other failure relating to the interface repository is detected.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
INTF_REPOS()
Constructs an INTF_REPOS exception with a default minor code of 0 and a completion state of COMPLETED_NO.
INTF_REPOS(int minor, CompletionStatus completed)
Constructs an INTF_REPOS exception with the specified minor code and completion status.
INTF_REPOS(String s)
Constructs an INTF_REPOS exception with the specified detail.
INTF_REPOS(String s, int minor, CompletionStatus completed)
Constructs an INTF_REPOS exception with the specified detail message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

INTF_REPOS

public INTF_REPOS()
Constructs an INTF_REPOS exception with a default minor code of 0 and a completion state of COMPLETED_NO.

INTF_REPOS

public INTF_REPOS(String s)
Constructs an INTF_REPOS exception with the specified detail.

Parameters:
s - the String containing a detail message

INTF_REPOS

public INTF_REPOS(int minor,
                  CompletionStatus completed)
Constructs an INTF_REPOS exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

INTF_REPOS

public INTF_REPOS(String s,
                  int minor,
                  CompletionStatus completed)
Constructs an INTF_REPOS exception with the specified detail message, minor code, and completion status. A detail message is a String that describes this particular exception.

Parameters:
s - the String containing a detail message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IntHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class IntHolder

java.lang.Object
    extended by  org.omg.CORBA.IntHolder
All Implemented Interfaces:
Streamable
public final class IntHolder
extends Object
implements Streamable

The Holder for Int. For more information on Holder files, see "Generated Files: Holder Files".

A Holder class for an int that is used to store "out" and "inout" parameters in IDL methods. If an IDL method signature has an IDL long as an "out" or "inout" parameter, the programmer must pass an instance of IntHolder as the corresponding parameter in the method invocation; for "inout" parameters, the programmer must also fill the "in" value to be sent to the server. Before the method invocation returns, the ORB will fill in the value corresponding to the "out" value returned from the server.

If myIntHolder is an instance of IntHolder, the value stored in its value field can be accessed with myIntHolder.value.

Since:
JDK1.2

Field Summary
 int value
The int value held by this IntHolder object in its value field.
Constructor Summary
IntHolder()
Constructs a new IntHolder object with its value field initialized to 0.
IntHolder(int initial)
Constructs a new IntHolder object with its value field initialized to the given int.
Method Summary
void | _read(InputStream input) Reads unmarshalled data from input and assigns it to the value field in this IntHolder object.
TypeCode | _type() Retrieves the TypeCode object that corresponds to the value held in this IntHolder object's value field.
void | _write(OutputStream output) Marshals the value in this IntHolder object's value field to the output stream output.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public int value
The int value held by this IntHolder object in its value field.

Constructor Detail

IntHolder

public IntHolder()
Constructs a new IntHolder object with its value field initialized to 0.

IntHolder

public IntHolder(int initial)
Constructs a new IntHolder object with its value field initialized to the given int.

Parameters:
initial - the int with which to initialize the value field of the newly-created IntHolder object
Method Detail

_read

public void _read(InputStream input)
Reads unmarshalled data from input and assigns it to the value field in this IntHolder object.

Specified by:
_read in interface Streamable
Parameters:
input - the InputStream object containing CDR formatted data from the wire

_write

public void _write(OutputStream output)
Marshals the value in this IntHolder object's value field to the output stream output.

Specified by:
_write in interface Streamable
Parameters:
output - the OutputStream object that will contain the CDR formatted data

_type

public TypeCode _type()
Retrieves the TypeCode object that corresponds to the value held in this IntHolder object's value field.

Specified by:
_type in interface Streamable
Returns:
the type code for the value held in this IntHolder object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


INVALID_ACTIVITY

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class INVALID_ACTIVITY

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.INVALID_ACTIVITY
All Implemented Interfaces:
Serializable
public final class INVALID_ACTIVITY
extends SystemException

The INVALID_ACTIVITY system exception may be raised on the Activity or Transaction services' resume methods if a transaction or Activity is resumed in a context different to that from which it was suspended. It is also raised when an attempted invocation is made that is incompatible with the Activity's current state.

Since:
J2SE 1.5
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
INVALID_ACTIVITY()
Constructs an INVALID_ACTIVITY exception with minor code set to 0 and CompletionStatus set to COMPLETED_NO.
INVALID_ACTIVITY(int minorCode, CompletionStatus completionStatus)
Constructs an INVALID_ACTIVITY exception with the specified minor code and completion status.
INVALID_ACTIVITY(String detailMessage)
Constructs an INVALID_ACTIVITY exception with the specified message.
INVALID_ACTIVITY(String detailMessage, int minorCode, CompletionStatus completionStatus)
Constructs an INVALID_ACTIVITY exception with the specified message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

INVALID_ACTIVITY

public INVALID_ACTIVITY()
Constructs an INVALID_ACTIVITY exception with minor code set to 0 and CompletionStatus set to COMPLETED_NO.

INVALID_ACTIVITY

public INVALID_ACTIVITY(String detailMessage)
Constructs an INVALID_ACTIVITY exception with the specified message.

Parameters:
detailMessage - string containing a detailed message.

INVALID_ACTIVITY

public INVALID_ACTIVITY(int minorCode,
                        CompletionStatus completionStatus)
Constructs an INVALID_ACTIVITY exception with the specified minor code and completion status.

Parameters:
minorCode - minor code.
completionStatus - completion status.

INVALID_ACTIVITY

public INVALID_ACTIVITY(String detailMessage,
                        int minorCode,
                        CompletionStatus completionStatus)
Constructs an INVALID_ACTIVITY exception with the specified message, minor code, and completion status.

Parameters:
detailMessage - string containing a detailed message.
minorCode - minor code.
completionStatus - completion status.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


INVALID_TRANSACTION

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class INVALID_TRANSACTION

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.INVALID_TRANSACTION
All Implemented Interfaces:
Serializable
public final class INVALID_TRANSACTION
extends SystemException

Exception thrown when the request carried an invalid transaction context. For example, this exception could be raised if an error occurred when trying to register a resource.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
INVALID_TRANSACTION()
Constructs an INVALID_TRANSACTION exception with a default minor code of 0 and a completion state of COMPLETED_NO.
INVALID_TRANSACTION(int minor, CompletionStatus completed)
Constructs an INVALID_TRANSACTION exception with the specified minor code and completion status.
INVALID_TRANSACTION(String s)
Constructs an INVALID_TRANSACTION exception with the specified detail message.
INVALID_TRANSACTION(String s, int minor, CompletionStatus completed)
Constructs an INVALID_TRANSACTION exception with the specified detail message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

INVALID_TRANSACTION

public INVALID_TRANSACTION()
Constructs an INVALID_TRANSACTION exception with a default minor code of 0 and a completion state of COMPLETED_NO.

INVALID_TRANSACTION

public INVALID_TRANSACTION(String s)
Constructs an INVALID_TRANSACTION exception with the specified detail message.

Parameters:
s - the String containing a detail message

INVALID_TRANSACTION

public INVALID_TRANSACTION(int minor,
                           CompletionStatus completed)
Constructs an INVALID_TRANSACTION exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

INVALID_TRANSACTION

public INVALID_TRANSACTION(String s,
                           int minor,
                           CompletionStatus completed)
Constructs an INVALID_TRANSACTION exception with the specified detail message, minor code, and completion status. A detail message is a String that describes this particular exception.

Parameters:
s - the String containing a detail message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


INV_FLAG

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class INV_FLAG

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.INV_FLAG
All Implemented Interfaces:
Serializable
public final class INV_FLAG
extends SystemException

Exception thrown when an invalid flag was passed to an operation (for example, when creating a DII request).

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
INV_FLAG()
Constructs an INV_FLAG exception with a default minor code of 0 and a completion state of COMPLETED_NO.
INV_FLAG(int minor, CompletionStatus completed)
Constructs an INV_FLAG exception with the specified minor code and completion status.
INV_FLAG(String s)
Constructs an INV_FLAG exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.
INV_FLAG(String s, int minor, CompletionStatus completed)
Constructs an INV_FLAG exception with the specified detail message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

INV_FLAG

public INV_FLAG()
Constructs an INV_FLAG exception with a default minor code of 0 and a completion state of COMPLETED_NO.

INV_FLAG

public INV_FLAG(String s)
Constructs an INV_FLAG exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message

INV_FLAG

public INV_FLAG(int minor,
                CompletionStatus completed)
Constructs an INV_FLAG exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - an instance of CompletionStatus indicating the completion status

INV_FLAG

public INV_FLAG(String s,
                int minor,
                CompletionStatus completed)
Constructs an INV_FLAG exception with the specified detail message, minor code, and completion status. A detail message is a String that describes this particular exception.

Parameters:
s - the String containing a detail message
minor - the minor code
completed - an instance of CompletionStatus indicating the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


INV_IDENT

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class INV_IDENT

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.INV_IDENT
All Implemented Interfaces:
Serializable
public final class INV_IDENT
extends SystemException

This exception indicates that an IDL identifier is syntactically invalid. It may be raised if, for example, an identifier passed to the interface repository does not conform to IDL identifier syntax, or if an illegal operation name is used with the DII.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
INV_IDENT()
Constructs an INV_IDENT exception with a default minor code of 0 and a completion state of COMPLETED_NO.
INV_IDENT(int minor, CompletionStatus completed)
Constructs an INV_IDENT exception with the specified minor code and completion status.
INV_IDENT(String s)
Constructs an INV_IDENT exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.
INV_IDENT(String s, int minor, CompletionStatus completed)
Constructs an INV_IDENT exception with the specified detail message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

INV_IDENT

public INV_IDENT()
Constructs an INV_IDENT exception with a default minor code of 0 and a completion state of COMPLETED_NO.

INV_IDENT

public INV_IDENT(String s)
Constructs an INV_IDENT exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message

INV_IDENT

public INV_IDENT(int minor,
                 CompletionStatus completed)
Constructs an INV_IDENT exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - a CompletionStatus object indicating the completion status

INV_IDENT

public INV_IDENT(String s,
                 int minor,
                 CompletionStatus completed)
Constructs an INV_IDENT exception with the specified detail message, minor code, and completion status. A detail message is a String that describes this particular exception.

Parameters:
s - the String containing a detail message
minor - the minor code
completed - a CompletionStatus object indicating the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


INV_OBJREF

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class INV_OBJREF

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.INV_OBJREF
All Implemented Interfaces:
Serializable
public final class INV_OBJREF
extends SystemException

This exception indicates that an object reference is internally malformed. For example, the repository ID may have incorrect syntax or the addressing information may be invalid. This exception is raised by ORB::string_to_object if the passed string does not decode correctly. An ORB may choose to detect calls via nil references (but is not obliged to do detect them). INV_OBJREF is used to indicate this.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

See the section Minor Code Meanings to see the minor codes for this exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
INV_OBJREF()
Constructs an INV_OBJREF exception with a default minor code of 0 and a completion state of COMPLETED_NO.
INV_OBJREF(int minor, CompletionStatus completed)
Constructs an INV_OBJREF exception with the specified minor code and completion status.
INV_OBJREF(String s)
Constructs an INV_OBJREF exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.
INV_OBJREF(String s, int minor, CompletionStatus completed)
Constructs an INV_OBJREF exception with the specified detail message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

INV_OBJREF

public INV_OBJREF()
Constructs an INV_OBJREF exception with a default minor code of 0 and a completion state of COMPLETED_NO.

INV_OBJREF

public INV_OBJREF(String s)
Constructs an INV_OBJREF exception with the specified detail message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message

INV_OBJREF

public INV_OBJREF(int minor,
                  CompletionStatus completed)
Constructs an INV_OBJREF exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - a CompletionStatus instance indicating the completion status

INV_OBJREF

public INV_OBJREF(String s,
                  int minor,
                  CompletionStatus completed)
Constructs an INV_OBJREF exception with the specified detail message, minor code, and completion status. A detail message is a String that describes this particular exception.

Parameters:
s - the String containing a detail message
minor - the minor code
completed - a CompletionStatus instance indicating the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


INV_POLICY

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class INV_POLICY

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.INV_POLICY
All Implemented Interfaces:
Serializable
public final class INV_POLICY
extends SystemException

Standard exception thrown when an invocation cannot be made because of an incompatibility between Policy overrides that apply to the particular invocation. It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
INV_POLICY()
Constructs a INV_POLICY exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.
INV_POLICY(int minor, CompletionStatus completed)
Constructs a INV_POLICY exception with the specified minor code and completion status.
INV_POLICY(String s)
Constructs a INV_POLICY exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.
INV_POLICY(String s, int minor, CompletionStatus completed)
Constructs a INV_POLICY exception with the specified description message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

INV_POLICY

public INV_POLICY()
Constructs a INV_POLICY exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.

INV_POLICY

public INV_POLICY(String s)
Constructs a INV_POLICY exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message

INV_POLICY

public INV_POLICY(int minor,
                  CompletionStatus completed)
Constructs a INV_POLICY exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

INV_POLICY

public INV_POLICY(String s,
                  int minor,
                  CompletionStatus completed)
Constructs a INV_POLICY exception with the specified description message, minor code, and completion status.

Parameters:
s - the String containing a description message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IRObjectOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface IRObjectOperations

All Known Subinterfaces:
IDLType, IDLTypeOperations, IRObject
All Known Implementing Classes:
_IDLTypeStub
public interface IRObjectOperations

This is the Operations interface for the mapping from IRObject. Several interfaces are used as base interfaces for objects in the Interface Repository (IR). These base interfaces are not instantiable. A common set of operations is used to locate objects within the Interface Repository. Some of these operations are defined in the IRObject. All IR objects inherit from the IRObject interface, which provides an operation for identifying the actual type of the object. (The IDL base interface IRObject represents the most generic interface from which all other Interface Repository interfaces are derived, even the Repository itself.) All java implementations of IR objects must implement the IRObjectOperations interface.

See Also:
IDLTypeOperations, IDLType, IRObject

Method Summary
DefinitionKind | def_kind() Returns the DefinitionKind corresponding to this Interface Repository object.
void | destroy() Destroys this object.

Method Detail

def_kind

DefinitionKind def_kind()
Returns the DefinitionKind corresponding to this Interface Repository object.

Returns:
the DefinitionKind corresponding to this Interface Repository object.

destroy

void destroy()
Destroys this object. If the object is a Container, this method is applied to all its contents. If the object contains an IDLType attribute for an anonymous type, that IDLType is destroyed. If the object is currently contained in some other object, it is removed. If the method is invoked on a Repository or on a PrimitiveDef then the BAD_INV_ORDER exception is raised with minor value 2. An attempt to destroy an object that would leave the repository in an incoherent state causes BAD_INV_ORDER exception to be raised with the minor code 1.

Throws:
BAD_INV_ORDER - if this method is invoked on a repository or PrimitiveDef, or if an attempt to destroy an object would leave the repository in an incoherent state
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LocalObject

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class LocalObject

java.lang.Object
    extended by  org.omg.CORBA.LocalObject
All Implemented Interfaces:
Object
public class LocalObject
extends Object
implements Object

Used as a base class for implementation of a local IDL interface in the Java language mapping. It is a class which implements all the operations in the org.omg.CORBA.Object interface.

Local interfaces are implemented by using CORBA::LocalObject to provide implementations of Object pseudo operations and any other ORB-specific support mechanisms that are appropriate for such objects. Object implementation techniques are inherently language-mapping specific. Therefore, the LocalObject type is not defined in IDL, but is specified in each language mapping.

Methods that do not apply to local objects throw an org.omg.CORBA.NO_IMPLEMENT exception with the message, "This is a locally contrained object." Attempting to use a LocalObject to create a DII request results in NO_IMPLEMENT system exception. Attempting to marshal or stringify a LocalObject results in a MARSHAL system exception. Narrowing and widening references to LocalObjects must work as for regular object references.

LocalObject is to be used as the base class of locally constrained objects, such as those in the PortableServer module. The specification here is based on the CORBA Components Volume I - orbos/99-07-01

See Also:
CORBA package comments for unimplemented features

Constructor Summary
LocalObject()
Constructs a default LocalObject instance.
Method Summary
Request | _create_request(Context ctx, String operation, NVList arg_list, NamedValue result) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
Request | _create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exceptions, ContextList contexts) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
Object | _duplicate() Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
DomainManager[] | _get_domain_managers() Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented.
Object | _get_interface_def() Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
Object | _get_interface() Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented.
Policy | _get_policy(int policy_type) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented.
int | _hash(int maximum) Returns a hash value that is consistent for the lifetime of the object, using the given number as the maximum.
InputStream | _invoke(OutputStream output) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
boolean | _is_a(String repository_id) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented.
boolean | _is_equivalent(Object that) Determines whether the two object references are equivalent, so far as the ORB can easily determine.
boolean | _is_local() Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
boolean | _non_existent() Always returns false.
ORB | _orb() Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
void | _release() Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
void | _releaseReply(InputStream input) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
Request | _request(String operation) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
OutputStream | _request(String operation, boolean responseExpected) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
void | _servant_postinvoke(ServantObject servant) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
ServantObject | _servant_preinvoke(String operation, Class expectedType) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
Object | _set_policy_override(Policy[] policies, SetOverrideType set_add) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented.
boolean | validate_connection() Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LocalObject

public LocalObject()
Constructs a default LocalObject instance.

Method Detail

_is_equivalent

public boolean _is_equivalent(Object that)

Determines whether the two object references are equivalent, so far as the ORB can easily determine. Two object references are equivalent if they are identical. Two distinct object references which in fact refer to the same object are also equivalent. However, ORBs are not required to attempt determination of whether two distinct object references refer to the same object, since such determination could be impractically expensive.

Default implementation of the org.omg.CORBA.Object method.

Specified by:
_is_equivalent in interface Object
Parameters:
that - the object reference with which to check for equivalence
Returns:
true if this object reference is known to be equivalent to the given object reference. Note that false indicates only that the two object references are distinct, not necessarily that they reference distinct objects.

_non_existent

public boolean _non_existent()
Always returns false. This method is the default implementation of the org.omg.CORBA.Object method.

Specified by:
_non_existent in interface Object
Returns:
false

_hash

public int _hash(int maximum)
Returns a hash value that is consistent for the lifetime of the object, using the given number as the maximum. This method is the default implementation of the org.omg.CORBA.Object method.

Specified by:
_hash in interface Object
Parameters:
maximum - an int identifying maximum value of the hashcode
Returns:
this instance's hashcode

_is_a

public boolean _is_a(String repository_id)
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented. This method is the default implementation of the org.omg.CORBA.Object method.

Specified by:
_is_a in interface Object
Parameters:
repository_id - a String
Returns:
NO_IMPLEMENT because this is a locally constrained object and this method does not apply to local objects
Throws:
NO_IMPLEMENT - because this is a locally constrained object and this method does not apply to local objects
See Also:
CORBA package comments for unimplemented features

_duplicate

public Object _duplicate()
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.

Specified by:
_duplicate in interface Object
Returns:
a duplicate of this LocalObject instance.
Throws:
NO_IMPLEMENT
See Also:
CORBA package comments for unimplemented features

_release

public void _release()
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.

Specified by:
_release in interface Object
Throws:
NO_IMPLEMENT
See Also:
CORBA package comments for unimplemented features

_request

public Request _request(String operation)
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.

Specified by:
_request in interface Object
Parameters:
operation - a String giving the name of an operation to be performed by the request that is returned
Returns:
a Request object with the given operation
Throws:
NO_IMPLEMENT
See Also:
CORBA package comments for unimplemented features

_create_request

public Request _create_request(Context ctx,
                               String operation,
                               NVList arg_list,
                               NamedValue result)
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.

Specified by:
_create_request in interface Object
Parameters:
ctx - a Context object containing a list of properties
operation - the String representing the name of the method to be invoked
arg_list - an NVList containing the actual arguments to the method being invoked
result - a NamedValue object to serve as a container for the method's return value
Returns:
a new Request object initialized with the given arguments
Throws:
NO_IMPLEMENT
See Also:
CORBA package comments for unimplemented features

_create_request

public Request _create_request(Context ctx,
                               String operation,
                               NVList arg_list,
                               NamedValue result,
                               ExceptionList exceptions,
                               ContextList contexts)
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.

Specified by:
_create_request in interface Object
Parameters:
ctx - a Context object containing a list of properties
operation - the name of the method to be invoked
arg_list - an NVList containing the actual arguments to the method being invoked
result - a NamedValue object to serve as a container for the method's return value
exceptions - an ExceptionList object containing a list of possible exceptions the method can throw
contexts - a ContextList object containing a list of context strings that need to be resolved and sent with the Request instance
Returns:
the new Request object initialized with the given arguments
Throws:
NO_IMPLEMENT
See Also:
CORBA package comments for unimplemented features

_get_interface

public Object _get_interface()
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented. This method is the default implementation of the org.omg.CORBA.Object method.

Returns:
NO_IMPLEMENT because this is a locally constrained object and this method does not apply to local objects
Throws:
NO_IMPLEMENT - because this is a locally constrained object and this method does not apply to local objects
See Also:
CORBA package comments for unimplemented features

_get_interface_def

public Object _get_interface_def()
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.

Specified by:
_get_interface_def in interface Object
Returns:
the InterfaceDef object in the Interface Repository which provides type information about the object referred to by this object reference
Throws:
NO_IMPLEMENT
See Also:
CORBA package comments for unimplemented features

_orb

public ORB _orb()
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.

Returns:
the ORB instance that created the Delegate contained in this ObjectImpl
Throws:
NO_IMPLEMENT
See Also:
CORBA package comments for unimplemented features

_get_policy

public Policy _get_policy(int policy_type)
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented. This method is the default implementation of the org.omg.CORBA.Object method.

Specified by:
_get_policy in interface Object
Parameters:
policy_type - an int
Returns:
NO_IMPLEMENT because this is a locally constrained object and this method does not apply to local objects
Throws:
NO_IMPLEMENT - because this is a locally constrained object and this method does not apply to local objects
See Also:
CORBA package comments for unimplemented features

_get_domain_managers

public DomainManager[] _get_domain_managers()
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented. This method is the default implementation of the org.omg.CORBA.Object method.

Specified by:
_get_domain_managers in interface Object
Returns:
the list of immediately enclosing domain managers of this object. At least one domain manager is always returned in the list since by default each object is associated with at least one domain manager at creation.
Throws:
NO_IMPLEMENT
See Also:
CORBA package comments for unimplemented features

_set_policy_override

public Object _set_policy_override(Policy[] policies,
                                   SetOverrideType set_add)
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented. This method is the default implementation of the org.omg.CORBA.Object method.

Specified by:
_set_policy_override in interface Object
Parameters:
policies - an array
set_add - a flag
Returns:
NO_IMPLEMENT because this is a locally constrained object and this method does not apply to local objects
Throws:
NO_IMPLEMENT - because this is a locally constrained object and this method does not apply to local objects
See Also:
CORBA package comments for unimplemented features

_is_local

public boolean _is_local()
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.

Returns true for this LocalObject instance.

Returns:
true always
Throws:
NO_IMPLEMENT
See Also:
CORBA package comments for unimplemented features

_servant_preinvoke

public ServantObject _servant_preinvoke(String operation,
                                        Class expectedType)
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.

Parameters:
operation - a String indicating which operation to preinvoke
expectedType - the class of the type of operation mentioned above
Returns:
NO_IMPLEMENT because this is a locally constrained object and this method does not apply to local objects
Throws:
NO_IMPLEMENT - because this is a locally constrained object and this method does not apply to local object
See Also:
CORBA package comments for unimplemented features

_servant_postinvoke

public void _servant_postinvoke(ServantObject servant)
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.

Parameters:
servant - the servant object on which to post-invoke
Throws:
NO_IMPLEMENT
See Also:
CORBA package comments for unimplemented features

_request

public OutputStream _request(String operation,
                             boolean responseExpected)
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.

Called by a stub to obtain an OutputStream for marshaling arguments. The stub must supply the operation name, and indicate if a response is expected (i.e is this a oneway call).

Parameters:
operation - the name of the operation being requested
responseExpected - true if a response is expected, false if it is a one-way call
Returns:
NO_IMPLEMENT because this is a locally constrained object and this method does not apply to local objects
Throws:
NO_IMPLEMENT - because this is a locally constrained object and this method does not apply to local objects
See Also:
CORBA package comments for unimplemented features

_invoke

public InputStream _invoke(OutputStream output)
                    throws ApplicationException,
                           RemarshalException
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.

Called to invoke an operation. The stub provides an OutputStream that was previously returned by a _request() call. _invoke returns an InputStream which contains the marshaled reply. If an exception occurs, _invoke may throw an ApplicationException object which contains an InputStream from which the user exception state may be unmarshaled.

Parameters:
output - the OutputStream to invoke
Returns:
NO_IMPLEMENT because this is a locally constrained object and this method does not apply to local objects
Throws:
ApplicationException - If an exception occurs, _invoke may throw an ApplicationException object which contains an InputStream from which the user exception state may be unmarshaled.
RemarshalException - If an exception occurs, _invoke may throw an ApplicationException object which contains an InputStream from which the user exception state may be unmarshaled.
NO_IMPLEMENT - because this is a locally constrained object and this method does not apply to local objects
See Also:
CORBA package comments for unimplemented features

_releaseReply

public void _releaseReply(InputStream input)
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.

May optionally be called by a stub to release a reply stream back to the ORB when the unmarshaling has completed. The stub passes the InputStream returned by _invoke() or ApplicationException.getInputStream(). A null value may also be passed to _releaseReply, in which case the method is a no-op.

Parameters:
input - the reply stream back to the ORB or null
Throws:
NO_IMPLEMENT
See Also:
CORBA package comments for unimplemented features

validate_connection

public boolean validate_connection()
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method does not apply to local objects and is therefore not implemented. This method is the default implementation of the org.omg.CORBA.Object method.

Returns:
NO_IMPLEMENT because this is a locally constrained object and this method does not apply to local objects
Throws:
NO_IMPLEMENT - because this is a locally constrained object and this method does not apply to local objects
See Also:
CORBA package comments for unimplemented features
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LongHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class LongHolder

java.lang.Object
    extended by  org.omg.CORBA.LongHolder
All Implemented Interfaces:
Streamable
public final class LongHolder
extends Object
implements Streamable

The Holder for Long. For more information on Holder files, see "Generated Files: Holder Files".

A Holder class for a long that is used to store "out" and "inout" parameters in IDL methods. If an IDL method signature has an IDL long long as an "out" or "inout" parameter, the programmer must pass an instance of LongHolder as the corresponding parameter in the method invocation; for "inout" parameters, the programmer must also fill the "in" value to be sent to the server. Before the method invocation returns, the ORB will fill in the value corresponding to the "out" value returned from the server.

If myLongHolder is an instance of LongHolder, the value stored in its value field can be accessed with myLongHolder.value.

Since:
JDK1.2

Field Summary
 long value
The long value held by this LongHolder object.
Constructor Summary
LongHolder()
Constructs a new LongHolder object with its value field initialized to 0.
LongHolder(long initial)
Constructs a new LongHolder object with its value field initialized to the given long.
Method Summary
void | _read(InputStream input) Reads from input and initalizes the value in the Holder with the unmarshalled data.
TypeCode | _type() Returns the TypeCode object corresponding to the value held in the Holder.
void | _write(OutputStream output) Marshals to output the value in the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public long value
The long value held by this LongHolder object.

Constructor Detail

LongHolder

public LongHolder()
Constructs a new LongHolder object with its value field initialized to 0.

LongHolder

public LongHolder(long initial)
Constructs a new LongHolder object with its value field initialized to the given long.

Parameters:
initial - the long with which to initialize the value field of the newly-created LongHolder object
Method Detail

_read

public void _read(InputStream input)
Reads from input and initalizes the value in the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
input - the InputStream containing CDR formatted data from the wire

_write

public void _write(OutputStream output)
Marshals to output the value in the Holder.

Specified by:
_write in interface Streamable
Parameters:
output - the OutputStream which will contain the CDR formatted data

_type

public TypeCode _type()
Returns the TypeCode object corresponding to the value held in the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode of the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LongLongSeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class LongLongSeqHelper

java.lang.Object
    extended by  org.omg.CORBA.LongLongSeqHelper

public abstract class LongLongSeqHelper
extends Object

The Helper for LongLongSeq. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/LongLongSeqHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:37 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications :

  • ORB core as defined by CORBA 2.3.1 (formal/99-10-07)
  • IDL/Java Language Mapping as defined in ptc/00-01-08

Constructor Summary
LongLongSeqHelper()
Method Summary
static long[] | extract(Any a)
static String | id()
static void | insert(Any a, long[] that)
static long[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, long[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LongLongSeqHelper

public LongLongSeqHelper()
Method Detail

insert

public static void insert(Any a,
                          long[] that)

extract

public static long[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static long[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         long[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LongLongSeqHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class LongLongSeqHolder

java.lang.Object
    extended by  org.omg.CORBA.LongLongSeqHolder
All Implemented Interfaces:
Streamable
public final class LongLongSeqHolder
extends Object
implements Streamable

The Holder for LongLongSeq. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/LongLongSeqHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00

Field Summary
 long[] value
Constructor Summary
LongLongSeqHolder()
LongLongSeqHolder(long[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public long[] value
Constructor Detail

LongLongSeqHolder

public LongLongSeqHolder()

LongLongSeqHolder

public LongLongSeqHolder(long[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LongSeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class LongSeqHelper

java.lang.Object
    extended by  org.omg.CORBA.LongSeqHelper

public abstract class LongSeqHelper
extends Object

The Helper for LongSeqHelper. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/LongSeqHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications :

  • ORB core as defined by CORBA 2.3.1 (formal/99-10-07)
  • IDL/Java Language Mapping as defined in ptc/00-01-08

Constructor Summary
LongSeqHelper()
Method Summary
static int[] | extract(Any a)
static String | id()
static void | insert(Any a, int[] that)
static int[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, int[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LongSeqHelper

public LongSeqHelper()
Method Detail

insert

public static void insert(Any a,
                          int[] that)

extract

public static int[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static int[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         int[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LongSeqHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class LongSeqHolder

java.lang.Object
    extended by  org.omg.CORBA.LongSeqHolder
All Implemented Interfaces:
Streamable
public final class LongSeqHolder
extends Object
implements Streamable

The Holder for LongSeq. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/LongSeqHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00

Field Summary
 int[] value
Constructor Summary
LongSeqHolder()
LongSeqHolder(int[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public int[] value
Constructor Detail

LongSeqHolder

public LongSeqHolder()

LongSeqHolder

public LongSeqHolder(int[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MARSHAL

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class MARSHAL

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.MARSHAL
All Implemented Interfaces:
Serializable
public final class MARSHAL
extends SystemException

A request or reply from the network is structurally invalid. This error typically indicates a bug in either the client-side or server-side run time. For example, if a reply from the server indicates that the message contains 1000 bytes, but the actual message is shorter or longer than 1000 bytes, the ORB raises this exception. MARSHAL can also be caused by using the DII or DSI incorrectly, for example, if the type of the actual parameters sent does not agree with IDL signature of an operation.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

See the section Minor Code Meanings to see the minor codes for this exception.

Since:
JDK1.2

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
MARSHAL()
Constructs a MARSHAL exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.
MARSHAL(int minor, CompletionStatus completed)
Constructs a MARSHAL exception with the specified minor code and completion status.
MARSHAL(String s)
Constructs a MARSHAL exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.
MARSHAL(String s, int minor, CompletionStatus completed)
Constructs a MARSHAL exception with the specified description message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MARSHAL

public MARSHAL()
Constructs a MARSHAL exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.

MARSHAL

public MARSHAL(String s)
Constructs a MARSHAL exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a description of the exception

MARSHAL

public MARSHAL(int minor,
               CompletionStatus completed)
Constructs a MARSHAL exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

MARSHAL

public MARSHAL(String s,
               int minor,
               CompletionStatus completed)
Constructs a MARSHAL exception with the specified description message, minor code, and completion status.

Parameters:
s - the String containing a description message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamedValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class NamedValue

java.lang.Object
    extended by  org.omg.CORBA.NamedValue

public abstract class NamedValue
extends Object

An object used in the DII and DSI to describe arguments and return values. NamedValue objects are also used in the Context object routines to pass lists of property names and values.

A NamedValue object contains:

  • a name -- If the NamedValue object is used to describe arguments to a request, the name will be an argument identifier specified in the OMG IDL interface definition for the operation being described.
  • a value -- an Any object
  • an argument mode flag -- one of the following:
    • ARG_IN.value
    • ARG_OUT.value
    • ARG_INOUT.value
    • zero -- if this NamedValue object represents a property in a Context object rather than a parameter or return value

The class NamedValue has three methods, which access its fields. The following code fragment demonstrates creating a NamedValue object and then accessing its fields:

    ORB orb = ORB.init(args, null);
    String s = "argument_1";
    org.omg.CORBA.Any myAny = orb.create_any();
    myAny.insert_long(12345);
    int in = org.omg.CORBA.ARG_IN.value;

    org.omg.CORBA.NamedValue nv = orb.create_named_value(
        s, myAny, in);
    System.out.println("This nv name is " + nv.name());
    try {
        System.out.println("This nv value is " + nv.value().extract_long());
        System.out.println("This nv flag is " + nv.flags());
    } catch (org.omg.CORBA.BAD_OPERATION b) {
      System.out.println("extract failed");
    }

If this code fragment were put into a main method, the output would be something like the following:

    This nv name is argument_1
    This nv value is 12345
    This nv flag is 1

Note that the method value returns an Any object. In order to access the long contained in the Any object, we used the method extract_long.

Since:
JDK1.2
See Also:
Any, ARG_IN, ARG_INOUT, ARG_OUT

Constructor Summary
NamedValue()
Method Summary
abstract int | flags() Retrieves the argument mode flag for this NamedValue object.
abstract String | name() Retrieves the name for this NamedValue object.
abstract Any | value() Retrieves the value for this NamedValue object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NamedValue

public NamedValue()
Method Detail

name

public abstract String name()
Retrieves the name for this NamedValue object.

Returns:
a String object representing the name of this NamedValue object

value

public abstract Any value()
Retrieves the value for this NamedValue object.

Returns:
an Any object containing the value of this NamedValue object

flags

public abstract int flags()
Retrieves the argument mode flag for this NamedValue object.

Returns:
an int representing the argument mode for this NamedValue object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameValuePair

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class NameValuePair

java.lang.Object
    extended by  org.omg.CORBA.NameValuePair
All Implemented Interfaces:
Serializable, IDLEntity
public final class NameValuePair
extends Object
implements IDLEntity

Associates a name with a value that is an attribute of an IDL struct, and is used in the DynStruct APIs.

Field Summary
String | id The name to be associated with a value by this NameValuePair object.
Any | value The value to be associated with a name by this NameValuePair object.
Constructor Summary
NameValuePair()
Constructs an empty NameValuePair object.
NameValuePair(String __id, Any __value)
Constructs a NameValuePair object that associates the given name with the given org.omg.CORBA.Any object.
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

id

public String id
The name to be associated with a value by this NameValuePair object.

value

public Any value
The value to be associated with a name by this NameValuePair object.

Constructor Detail

NameValuePair

public NameValuePair()
Constructs an empty NameValuePair object. To associate a name with a value after using this constructor, the fields of this object have to be accessed individually.

NameValuePair

public NameValuePair(String __id,
                     Any __value)
Constructs a NameValuePair object that associates the given name with the given org.omg.CORBA.Any object.

Parameters:
__id - the name to be associated with the given Any object
__value - the Any object to be associated with the given name
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameValuePairHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class NameValuePairHelper

java.lang.Object
    extended by  org.omg.CORBA.NameValuePairHelper

public abstract class NameValuePairHelper
extends Object

The Helper for NameValuePair. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/NameValuePairHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" 03 June 1999 11:52:03 o'clock GMT+00:00

Constructor Summary
NameValuePairHelper()
Method Summary
static NameValuePair | extract(Any a)
static String | id()
static void | insert(Any a, NameValuePair that)
static NameValuePair | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, NameValuePair value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NameValuePairHelper

public NameValuePairHelper()
Method Detail

insert

public static void insert(Any a,
                          NameValuePair that)

extract

public static NameValuePair extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static NameValuePair read(InputStream istream)

write

public static void write(OutputStream ostream,
                         NameValuePair value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NO_IMPLEMENT

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class NO_IMPLEMENT

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.NO_IMPLEMENT
All Implemented Interfaces:
Serializable
public final class NO_IMPLEMENT
extends SystemException

This exception indicates that even though the operation that was invoked exists (it has an IDL definition), no implementation for that operation exists. NO_IMPLEMENT can, for example, be raised by an ORB if a client asks for an object's type definition from the interface repository, but no interface repository is provided by the ORB.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

See the section Minor Code Meanings to see the minor codes for this exception.

Since:
JDK1.2

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
NO_IMPLEMENT()
Constructs a NO_IMPLEMENT exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.
NO_IMPLEMENT(int minor, CompletionStatus completed)
Constructs a NO_IMPLEMENT exception with the specified minor code and completion status.
NO_IMPLEMENT(String s)
Constructs a NO_IMPLEMENT exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.
NO_IMPLEMENT(String s, int minor, CompletionStatus completed)
Constructs a NO_IMPLEMENT exception with the specified description message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NO_IMPLEMENT

public NO_IMPLEMENT()
Constructs a NO_IMPLEMENT exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.

NO_IMPLEMENT

public NO_IMPLEMENT(String s)
Constructs a NO_IMPLEMENT exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a description of the exception

NO_IMPLEMENT

public NO_IMPLEMENT(int minor,
                    CompletionStatus completed)
Constructs a NO_IMPLEMENT exception with the specified minor code and completion status.

Parameters:
minor - an int specifying the minor code
completed - a CompletionStatus instance indicating the completion status

NO_IMPLEMENT

public NO_IMPLEMENT(String s,
                    int minor,
                    CompletionStatus completed)
Constructs a NO_IMPLEMENT exception with the specified description message, minor code, and completion status.

Parameters:
s - the String containing a description message
minor - an int specifying the minor code
completed - a CompletionStatus instance indicating the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NO_MEMORY

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class NO_MEMORY

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.NO_MEMORY
All Implemented Interfaces:
Serializable
public final class NO_MEMORY
extends SystemException

Exception thrown when the ORB run time has run out of memory.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
NO_MEMORY()
Constructs a NO_MEMORY exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.
NO_MEMORY(int minor, CompletionStatus completed)
Constructs a NO_MEMORY exception with the specified minor code and completion status.
NO_MEMORY(String s)
Constructs a NO_MEMORY exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.
NO_MEMORY(String s, int minor, CompletionStatus completed)
Constructs a NO_MEMORY exception with the specified description message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NO_MEMORY

public NO_MEMORY()
Constructs a NO_MEMORY exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.

NO_MEMORY

public NO_MEMORY(String s)
Constructs a NO_MEMORY exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a description message

NO_MEMORY

public NO_MEMORY(int minor,
                 CompletionStatus completed)
Constructs a NO_MEMORY exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

NO_MEMORY

public NO_MEMORY(String s,
                 int minor,
                 CompletionStatus completed)
Constructs a NO_MEMORY exception with the specified description message, minor code, and completion status.

Parameters:
s - the String containing a description message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NO_PERMISSION

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class NO_PERMISSION

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.NO_PERMISSION
All Implemented Interfaces:
Serializable
public final class NO_PERMISSION
extends SystemException

Exception thrown when an invocation failed because the caller has insufficient privileges.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
NO_PERMISSION()
Constructs a NO_PERMISSION exception with a default minor code of 0 and a completion state of CompletionStatus.COMPLETED_NO, and a null description.
NO_PERMISSION(int minor, CompletionStatus completed)
Constructs a NO_PERMISSION exception with the specified minor code and completion status.
NO_PERMISSION(String s)
Constructs a NO_PERMISSION exception with the specified description, a minor code of 0, and a completion state of COMPLETED_NO.
NO_PERMISSION(String s, int minor, CompletionStatus completed)
Constructs a NO_PERMISSION exception with the specified description message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NO_PERMISSION

public NO_PERMISSION()
Constructs a NO_PERMISSION exception with a default minor code of 0 and a completion state of CompletionStatus.COMPLETED_NO, and a null description.

NO_PERMISSION

public NO_PERMISSION(String s)
Constructs a NO_PERMISSION exception with the specified description, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a description message

NO_PERMISSION

public NO_PERMISSION(int minor,
                     CompletionStatus completed)
Constructs a NO_PERMISSION exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

NO_PERMISSION

public NO_PERMISSION(String s,
                     int minor,
                     CompletionStatus completed)
Constructs a NO_PERMISSION exception with the specified description message, minor code, and completion status.

Parameters:
s - the String containing a description message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NO_RESOURCES

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class NO_RESOURCES

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.NO_RESOURCES
All Implemented Interfaces:
Serializable
public final class NO_RESOURCES
extends SystemException

Exception thrown when the ORB has encountered some general resource limitation. For example, the run time may have reached the maximum permissible number of open connections.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
NO_RESOURCES()
Constructs a NO_RESOURCES exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.
NO_RESOURCES(int minor, CompletionStatus completed)
Constructs a NO_RESOURCES exception with the specified minor code and completion status.
NO_RESOURCES(String s)
Constructs a NO_RESOURCES exception with the specified description, a minor code of 0, and a completion state of COMPLETED_NO.
NO_RESOURCES(String s, int minor, CompletionStatus completed)
Constructs a NO_RESOURCES exception with the specified description message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NO_RESOURCES

public NO_RESOURCES()
Constructs a NO_RESOURCES exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.

NO_RESOURCES

public NO_RESOURCES(String s)
Constructs a NO_RESOURCES exception with the specified description, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a description message

NO_RESOURCES

public NO_RESOURCES(int minor,
                    CompletionStatus completed)
Constructs a NO_RESOURCES exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

NO_RESOURCES

public NO_RESOURCES(String s,
                    int minor,
                    CompletionStatus completed)
Constructs a NO_RESOURCES exception with the specified description message, minor code, and completion status.

Parameters:
s - the String containing a description message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NO_RESPONSE

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class NO_RESPONSE

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.NO_RESPONSE
All Implemented Interfaces:
Serializable
public final class NO_RESPONSE
extends SystemException

This exception is raised if a client attempts to retrieve the result of a deferred synchronous call, but the response for the request is not yet available.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
NO_RESPONSE()
Constructs a NO_RESPONSE exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.
NO_RESPONSE(int minor, CompletionStatus completed)
Constructs a NO_RESPONSE exception with the specified minor code and completion status.
NO_RESPONSE(String s)
Constructs a NO_RESPONSE exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.
NO_RESPONSE(String s, int minor, CompletionStatus completed)
Constructs a NO_RESPONSE exception with the specified description message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NO_RESPONSE

public NO_RESPONSE()
Constructs a NO_RESPONSE exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.

NO_RESPONSE

public NO_RESPONSE(String s)
Constructs a NO_RESPONSE exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a description message

NO_RESPONSE

public NO_RESPONSE(int minor,
                   CompletionStatus completed)
Constructs a NO_RESPONSE exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

NO_RESPONSE

public NO_RESPONSE(String s,
                   int minor,
                   CompletionStatus completed)
Constructs a NO_RESPONSE exception with the specified description message, minor code, and completion status.

Parameters:
s - the String containing a description message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NVList

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class NVList

java.lang.Object
    extended by  org.omg.CORBA.NVList

public abstract class NVList
extends Object

A modifiable list containing NamedValue objects.

The class NVList is used as follows:

  • to describe arguments for a Request object in the Dynamic Invocation Interface and the Dynamic Skeleton Interface
  • to describe context values in a Context object

Each NamedValue object consists of the following:

  • a name, which is a String object
  • a value, as an Any object
  • an argument mode flag

An NVList object may be created using one of the following ORB methods:

  1. org.omg.CORBA.ORB.create_list
        org.omg.CORBA.NVList nv = orb.create_list(3);
    The variable nv represents a newly-created NVList object. The argument is a memory-management hint to the orb and does not imply the actual length of the list. If, for example, you want to use an NVList object in a request, and the method being invoked takes three parameters, you might optimize by supplying 3 to the method create_list. Note that the new NVList will not necessarily have a length of 3; it could have a length of 2 or 4, for instance. Note also that you can add any number of NamedValue objects to this list regardless of its original length.

  2. org.omg.CORBA.ORB.create_operation_list
        org.omg.CORBA.NVList nv = orb.create_operation_list(myOperationDef);
    The variable nv represents a newly-created NVList object that contains descriptions of the arguments to the method described in the given OperationDef object.

The methods in the class NVList all deal with the NamedValue objects in the list. There are three methods for adding a NamedValue object, a method for getting the count of NamedValue objects in the list, a method for retrieving a NamedValue object at a given index, and a method for removing a NamedValue object at a given index.

Since:
JDK1.2
See Also:
Request, ServerRequest, NamedValue, Context

Constructor Summary
NVList()
Method Summary
abstract NamedValue | add_item(String item_name, int flags) Creates a new NamedValue object initialized with the given name and flag, and adds it to the end of this NVList object.
abstract NamedValue | add_value(String item_name, Any val, int flags) Creates a new NamedValue object initialized with the given name, value, and flag, and adds it to the end of this NVList object.
abstract NamedValue | add(int flags) Creates a new NamedValue object initialized with the given flag and adds it to the end of this NVList object.
abstract int | count() Returns the number of NamedValue objects that have been added to this NVList object.
abstract NamedValue | item(int index) Retrieves the NamedValue object at the given index.
abstract void | remove(int index) Removes the NamedValue object at the given index.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NVList

public NVList()
Method Detail

count

public abstract int count()
Returns the number of NamedValue objects that have been added to this NVList object.

Returns:
an int indicating the number of NamedValue objects in this NVList.

add

public abstract NamedValue add(int flags)
Creates a new NamedValue object initialized with the given flag and adds it to the end of this NVList object. The flag can be any one of the argument passing modes: ARG_IN.value, ARG_OUT.value, or ARG_INOUT.value.

Parameters:
flags - one of the argument mode flags
Returns:
the newly-created NamedValue object

add_item

public abstract NamedValue add_item(String item_name,
                                    int flags)
Creates a new NamedValue object initialized with the given name and flag, and adds it to the end of this NVList object. The flag can be any one of the argument passing modes: ARG_IN.value, ARG_OUT.value, or ARG_INOUT.value.

Parameters:
item_name - the name for the new NamedValue object
flags - one of the argument mode flags
Returns:
the newly-created NamedValue object

add_value

public abstract NamedValue add_value(String item_name,
                                     Any val,
                                     int flags)
Creates a new NamedValue object initialized with the given name, value, and flag, and adds it to the end of this NVList object.

Parameters:
item_name - the name for the new NamedValue object
val - an Any object containing the value for the new NamedValue object
flags - one of the following argument passing modes: ARG_IN.value, ARG_OUT.value, or ARG_INOUT.value
Returns:
the newly created NamedValue object

item

public abstract NamedValue item(int index)
                         throws Bounds
Retrieves the NamedValue object at the given index.

Parameters:
index - the index of the desired NamedValue object, which must be between zero and the length of the list minus one, inclusive. The first item is at index zero.
Returns:
the NamedValue object at the given index
Throws:
Bounds - if the index is greater than or equal to number of NamedValue objects

remove

public abstract void remove(int index)
                     throws Bounds
Removes the NamedValue object at the given index. Note that the indices of all NamedValue objects following the one removed are shifted down by one.

Parameters:
index - the index of the NamedValue object to be removed, which must be between zero and the length of the list minus one, inclusive. The first item is at index zero.
Throws:
Bounds - if the index is greater than or equal to number of NamedValue objects in the list
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ObjectHelper

java.lang.Object
    extended by  org.omg.CORBA.ObjectHelper

public abstract class ObjectHelper
extends Object

Constructor Summary
ObjectHelper()
Method Summary
static Object | extract(Any a)
static String | id()
static void | insert(Any a, Object that)
static Object | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, Object value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ObjectHelper

public ObjectHelper()
Method Detail

insert

public static void insert(Any a,
                          Object that)

extract

public static Object extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static Object read(InputStream istream)

write

public static void write(OutputStream ostream,
                         Object value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ObjectHolder

java.lang.Object
    extended by  org.omg.CORBA.ObjectHolder
All Implemented Interfaces:
Streamable
public final class ObjectHolder
extends Object
implements Streamable

The Holder for Object. For more information on Holder files, see "Generated Files: Holder Files".

A Holder class for a CORBA object reference (a value of type org.omg.CORBA.Object). It is usually used to store "out" and "inout" parameters in IDL methods. If an IDL method signature has a CORBA Object reference as an "out" or "inout" parameter, the programmer must pass an instance of ObjectHolder as the corresponding parameter in the method invocation; for "inout" parameters, the programmer must also fill the "in" value to be sent to the server. Before the method invocation returns, the ORB will fill in the value corresponding to the "out" value returned from the server.

If myObjectHolder is an instance of ObjectHolder, the value stored in its value field can be accessed with myObjectHolder.value.

Since:
JDK1.2

Field Summary
 Object value
The Object value held by this ObjectHolder object.
Constructor Summary
ObjectHolder()
Constructs a new ObjectHolder object with its value field initialized to null.
ObjectHolder(Object initial)
Constructs a new ObjectHolder object with its value field initialized to the given Object.
Method Summary
void | _read(InputStream input) Reads from input and initalizes the value in this ObjectHolder object with the unmarshalled data.
TypeCode | _type() Returns the TypeCode corresponding to the value held in this ObjectHolder object
void | _write(OutputStream output) Marshals to output the value in this ObjectHolder object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public Object value
The Object value held by this ObjectHolder object.

Constructor Detail

ObjectHolder

public ObjectHolder()
Constructs a new ObjectHolder object with its value field initialized to null.

ObjectHolder

public ObjectHolder(Object initial)
Constructs a new ObjectHolder object with its value field initialized to the given Object.

Parameters:
initial - the Object with which to initialize the value field of the newly-created ObjectHolder object
Method Detail

_read

public void _read(InputStream input)
Reads from input and initalizes the value in this ObjectHolder object with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
input - the InputStream containing CDR formatted data from the wire.

_write

public void _write(OutputStream output)
Marshals to output the value in this ObjectHolder object.

Specified by:
_write in interface Streamable
Parameters:
output - the OutputStream which will contain the CDR formatted data.

_type

public TypeCode _type()
Returns the TypeCode corresponding to the value held in this ObjectHolder object

Specified by:
_type in interface Streamable
Returns:
the TypeCode of the value held in this ObjectHolder object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OBJECT_NOT_EXIST

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class OBJECT_NOT_EXIST

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.OBJECT_NOT_EXIST
All Implemented Interfaces:
Serializable
public final class OBJECT_NOT_EXIST
extends SystemException

Exception raised whenever an invocation on a deleted object was performed. It is an authoritative "hard" fault report. Anyone receiving it is allowed (even expected) to delete all copies of this object reference and to perform other appropriate "final recovery" style procedures. Bridges forward this exception to clients, also destroying any records they may hold (for example, proxy objects used in reference translation). The clients could in turn purge any of their own data structures.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

See the section Minor Code Meanings to see the minor codes for this exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
OBJECT_NOT_EXIST()
Constructs an OBJECT_NOT_EXIST exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.
OBJECT_NOT_EXIST(int minor, CompletionStatus completed)
Constructs an OBJECT_NOT_EXIST exception with the specified minor code and completion status.
OBJECT_NOT_EXIST(String s)
Constructs an OBJECT_NOT_EXIST exception with the specified description, a minor code of 0, and a completion state of COMPLETED_NO.
OBJECT_NOT_EXIST(String s, int minor, CompletionStatus completed)
Constructs an OBJECT_NOT_EXIST exception with the specified description message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

OBJECT_NOT_EXIST

public OBJECT_NOT_EXIST()
Constructs an OBJECT_NOT_EXIST exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.

OBJECT_NOT_EXIST

public OBJECT_NOT_EXIST(String s)
Constructs an OBJECT_NOT_EXIST exception with the specified description, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a description message

OBJECT_NOT_EXIST

public OBJECT_NOT_EXIST(int minor,
                        CompletionStatus completed)
Constructs an OBJECT_NOT_EXIST exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

OBJECT_NOT_EXIST

public OBJECT_NOT_EXIST(String s,
                        int minor,
                        CompletionStatus completed)
Constructs an OBJECT_NOT_EXIST exception with the specified description message, minor code, and completion status.

Parameters:
s - the String containing a description message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OBJ_ADAPTER

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class OBJ_ADAPTER

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.OBJ_ADAPTER
All Implemented Interfaces:
Serializable
public final class OBJ_ADAPTER
extends SystemException

This exception typically indicates an administrative mismatch, for example, a server may have made an attempt to register itself with an implementation repository under a name that is already in use, or is unknown to the repository.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

See the section Minor Code Meanings to see the minor codes for this exception.

Since:
JDK1.2
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
OBJ_ADAPTER()
Constructs an OBJ_ADAPTER exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.
OBJ_ADAPTER(int minor, CompletionStatus completed)
Constructs an OBJ_ADAPTER exception with the specified minor code and completion status.
OBJ_ADAPTER(String s)
Constructs an OBJ_ADAPTER exception with the specified description, a minor code of 0, and a completion state of COMPLETED_NO.
OBJ_ADAPTER(String s, int minor, CompletionStatus completed)
Constructs an OBJ_ADAPTER exception with the specified description message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

OBJ_ADAPTER

public OBJ_ADAPTER()
Constructs an OBJ_ADAPTER exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.

OBJ_ADAPTER

public OBJ_ADAPTER(String s)
Constructs an OBJ_ADAPTER exception with the specified description, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a description message

OBJ_ADAPTER

public OBJ_ADAPTER(int minor,
                   CompletionStatus completed)
Constructs an OBJ_ADAPTER exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

OBJ_ADAPTER

public OBJ_ADAPTER(String s,
                   int minor,
                   CompletionStatus completed)
Constructs an OBJ_ADAPTER exception with the specified description message, minor code, and completion status.

Parameters:
s - the String containing a description message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OctetSeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class OctetSeqHelper

java.lang.Object
    extended by  org.omg.CORBA.OctetSeqHelper

public abstract class OctetSeqHelper
extends Object

The Helper for OctetSeq. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/OctetSeqHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications :

  • ORB core as defined by CORBA 2.3.1 (formal/99-10-07)
  • IDL/Java Language Mapping as defined in ptc/00-01-08

Constructor Summary
OctetSeqHelper()
Method Summary
static byte[] | extract(Any a)
static String | id()
static void | insert(Any a, byte[] that)
static byte[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, byte[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

OctetSeqHelper

public OctetSeqHelper()
Method Detail

insert

public static void insert(Any a,
                          byte[] that)

extract

public static byte[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static byte[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         byte[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OctetSeqHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class OctetSeqHolder

java.lang.Object
    extended by  org.omg.CORBA.OctetSeqHolder
All Implemented Interfaces:
Streamable
public final class OctetSeqHolder
extends Object
implements Streamable

The Holder for OctetSeq. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/OctetSeqHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00

Field Summary
 byte[] value
Constructor Summary
OctetSeqHolder()
OctetSeqHolder(byte[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public byte[] value
Constructor Detail

OctetSeqHolder

public OctetSeqHolder()

OctetSeqHolder

public OctetSeqHolder(byte[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OMGVMCID

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface OMGVMCID

public interface OMGVMCID

The vendor minor code ID reserved for OMG. Minor codes for the standard exceptions are prefaced by the VMCID assigned to OMG, defined as the constant OMGVMCID, which, like all VMCIDs, occupies the high order 20 bits.

Field Summary
static int value
The vendor minor code ID reserved for OMG.

Field Detail

value

static final int value
The vendor minor code ID reserved for OMG. This value is or'd with the high order 20 bits of the minor code to produce the minor value in a system exception.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ORB

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ORB

java.lang.Object
    extended by  org.omg.CORBA.ORB
Direct Known Subclasses:
ORB
public abstract class ORB
extends Object

A class providing APIs for the CORBA Object Request Broker features. The ORB class also provides "pluggable ORB implementation" APIs that allow another vendor's ORB implementation to be used.

An ORB makes it possible for CORBA objects to communicate with each other by connecting objects making requests (clients) with objects servicing requests (servers).

The ORB class, which encapsulates generic CORBA functionality, does the following: (Note that items 5 and 6, which include most of the methods in the class ORB, are typically used with the Dynamic Invocation Interface (DII) and the Dynamic Skeleton Interface (DSI). These interfaces may be used by a developer directly, but most commonly they are used by the ORB internally and are not seen by the general programmer.)

  1. initializes the ORB implementation by supplying values for predefined properties and environmental parameters
  2. obtains initial object references to services such as the NameService using the method resolve_initial_references
  3. converts object references to strings and back
  4. connects the ORB to a servant (an instance of a CORBA object implementation) and disconnects the ORB from a servant
  5. creates objects such as
    • TypeCode
    • Any
    • NamedValue
    • Context
    • Environment
    • lists (such as NVList) containing these objects
  6. sends multiple messages in the DII

The ORB class can be used to obtain references to objects implemented anywhere on the network.

An application or applet gains access to the CORBA environment by initializing itself into an ORB using one of three init methods. Two of the three methods use the properties (associations of a name with a value) shown in the table below.
Standard Java CORBA Properties:
Property Name | Property Value
org.omg.CORBA.ORBClass | class name of an ORB implementation
org.omg.CORBA.ORBSingletonClass | class name of the ORB returned by init()

These properties allow a different vendor's ORB implementation to be "plugged in."

When an ORB instance is being created, the class name of the ORB implementation is located using the following standard search order:

  1. check in Applet parameter or application string array, if any
  2. check in properties parameter, if any
  3. check in the System properties
  4. check in the orb.properties file located in the user.home directory (if any)
  5. check in the orb.properties file located in the java.home/lib directory (if any)
  6. fall back on a hardcoded default behavior (use the Java IDL implementation)

Note that Java IDL provides a default implementation for the fully-functional ORB and for the Singleton ORB. When the method init is given no parameters, the default Singleton ORB is returned. When the method init is given parameters but no ORB class is specified, the Java IDL ORB implementation is returned.

The following code fragment creates an ORB object initialized with the default ORB Singleton. This ORB has a restricted implementation to prevent malicious applets from doing anything beyond creating typecodes. It is called a singleton because there is only one instance for an entire virtual machine.

    ORB orb = ORB.init();

The following code fragment creates an ORB object for an application. The parameter args represents the arguments supplied to the application's main method. Since the property specifies the ORB class to be "SomeORBImplementation", the new ORB will be initialized with that ORB implementation. If p had been null, and the arguments had not specified an ORB class, the new ORB would have been initialized with the default Java IDL implementation.

    Properties p = new Properties();
    p.put("org.omg.CORBA.ORBClass", "SomeORBImplementation");
    ORB orb = ORB.init(args, p);

The following code fragment creates an ORB object for the applet supplied as the first parameter. If the given applet does not specify an ORB class, the new ORB will be initialized with the default Java IDL implementation.

    ORB orb = ORB.init(myApplet, null);

An application or applet can be initialized in one or more ORBs. ORB initialization is a bootstrap call into the CORBA world.

Since:
JDK1.2

Constructor Summary
ORB()
Method Summary
void | connect(Object obj) Connects the given servant object (a Java object that is an instance of the server implementation class) to the ORB.
TypeCode | create_abstract_interface_tc(String id, String name) Create a TypeCode object for an IDL abstract interface.
abstract TypeCode | create_alias_tc(String id, String name, TypeCode original_type) Creates a TypeCode object representing an IDL alias (typedef).
abstract Any | create_any() Creates an IDL Any object initialized to contain a Typecode object whose kind field is set to TCKind.tc_null.
abstract TypeCode | create_array_tc(int length, TypeCode element_type) Creates a TypeCode object representing an IDL array.
DynAny | create_basic_dyn_any(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
abstract ContextList | create_context_list() Creates an empty ContextList object.
DynAny | create_dyn_any(Any value) Deprecated. Use the new DynAnyFactory API instead
DynArray | create_dyn_array(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
DynEnum | create_dyn_enum(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
DynSequence | create_dyn_sequence(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
DynStruct | create_dyn_struct(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
DynUnion | create_dyn_union(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
abstract TypeCode | create_enum_tc(String id, String name, String[] members) Creates a TypeCode object representing an IDL enum.
abstract Environment | create_environment() Creates an Environment object.
abstract ExceptionList | create_exception_list() Creates an empty ExceptionList object.
abstract TypeCode | create_exception_tc(String id, String name, StructMember[] members) Creates a TypeCode object representing an IDL exception.
TypeCode | create_fixed_tc(short digits, short scale) Create a TypeCode object for an IDL fixed type.
abstract TypeCode | create_interface_tc(String id, String name) Creates a TypeCode object representing an IDL interface.
abstract NVList | create_list(int count) Allocates an NVList with (probably) enough space for the specified number of NamedValue objects.
abstract NamedValue | create_named_value(String s, Any any, int flags) Creates a NamedValue object using the given name, value, and argument mode flags.
TypeCode | create_native_tc(String id, String name) Create a TypeCode object for an IDL native type.
NVList | create_operation_list(Object oper) Creates an NVList initialized with argument descriptions for the operation described in the given OperationDef object.
abstract OutputStream | create_output_stream() Creates a new org.omg.CORBA.portable.OutputStream into which IDL method parameters can be marshalled during method invocation.
Policy | create_policy(int type, Any val) Can be invoked to create new instances of policy objects of a specific type with specified initial state.
abstract TypeCode | create_recursive_sequence_tc(int bound, int offset) Deprecated. Use a combination of create_recursive_tc and create_sequence_tc instead
TypeCode | create_recursive_tc(String id) Create a recursive TypeCode object which serves as a placeholder for a concrete TypeCode during the process of creating TypeCodes which contain recursion.
abstract TypeCode | create_sequence_tc(int bound, TypeCode element_type) Creates a TypeCode object representing an IDL sequence.
abstract TypeCode | create_string_tc(int bound) Creates a TypeCode object representing a bounded IDL string.
abstract TypeCode | create_struct_tc(String id, String name, StructMember[] members) Creates a TypeCode object representing an IDL struct.
abstract TypeCode | create_union_tc(String id, String name, TypeCode discriminator_type, UnionMember[] members) Creates a TypeCode object representing an IDL union.
TypeCode | create_value_box_tc(String id, String name, TypeCode boxed_type) Creates a TypeCode object for an IDL value box.
TypeCode | create_value_tc(String id, String name, short type_modifier, TypeCode concrete_base, ValueMember[] members) Create a TypeCode object for an IDL value type.
abstract TypeCode | create_wstring_tc(int bound) Creates a TypeCode object representing a bounded IDL wstring (wide string).
void | destroy() Destroys the ORB so that its resources can be reclaimed.
void | disconnect(Object obj) Disconnects the given servant object from the ORB.
Current | get_current() Deprecated. use resolve_initial_references.
abstract Context | get_default_context() Gets the default Context object.
abstract Request | get_next_response() Gets the next Request instance for which a response has been received.
abstract TypeCode | get_primitive_tc(TCKind tcKind) Retrieves the TypeCode object that represents the given primitive IDL type.
boolean | get_service_information(short service_type, ServiceInformationHolder service_info) Used to obtain information about CORBA facilities and services that are supported by this ORB.
static ORB | init() Returns the ORB singleton object.
static ORB | init(Applet app, Properties props) Creates a new ORB instance for an applet.
static ORB | init(String[] args, Properties props) Creates a new ORB instance for a standalone application.
abstract String[] | list_initial_services() Returns a list of the initially available CORBA object references, such as "NameService" and "InterfaceRepository".
abstract String | object_to_string(Object obj) Converts the given CORBA object reference to a string.
void | perform_work() Performs an implementation-dependent unit of work if called by the main thread.
abstract boolean | poll_next_response() Finds out if any of the deferred (asynchronous) invocations have a response yet.
abstract Object | resolve_initial_references(String object_name) Resolves a specific object reference from the set of available initial service names.
void | run() This operation blocks the current thread until the ORB has completed the shutdown process, initiated when some thread calls shutdown.
abstract void | send_multiple_requests_deferred(Request[] req) Sends multiple dynamic (DII) requests asynchronously.
abstract void | send_multiple_requests_oneway(Request[] req) Sends multiple dynamic (DII) requests asynchronously without expecting any responses.
protected abstract void | set_parameters(Applet app, Properties props) Allows the ORB implementation to be initialized with the given applet and parameters.
protected abstract void | set_parameters(String[] args, Properties props) Allows the ORB implementation to be initialized with the given parameters and properties.
void | shutdown(boolean wait_for_completion) Instructs the ORB to shut down, which causes all object adapters to shut down, in preparation for destruction. If the wait_for_completion parameter is true, this operation blocks until all ORB processing (including processing of currently executing requests, object deactivation, and other object adapter operations) has completed.
abstract Object | string_to_object(String str) Converts a string produced by the method object_to_string back to a CORBA object reference.
boolean | work_pending() Returns true if the ORB needs the main thread to perform some work, and false if the ORB does not need the main thread.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ORB

public ORB()
Method Detail

init

public static ORB init()
Returns the ORB singleton object. This method always returns the same ORB instance, which is an instance of the class described by the org.omg.CORBA.ORBSingletonClass system property.

This no-argument version of the method init is used primarily as a factory for TypeCode objects, which are used by Helper classes to implement the method type. It is also used to create Any objects that are used to describe union labels (as part of creating a TypeCode object for a union).

This method is not intended to be used by applets, and in the event that it is called in an applet environment, the ORB it returns is restricted so that it can be used only as a factory for TypeCode objects. Any TypeCode objects it produces can be safely shared among untrusted applets.

If an ORB is created using this method from an applet, a system exception will be thrown if methods other than those for creating TypeCode objects are invoked.

Returns:
the singleton ORB

init

public static ORB init(String[] args,
                       Properties props)
Creates a new ORB instance for a standalone application. This method may be called from applications only and returns a new fully functional ORB object each time it is called.

Parameters:
args - command-line arguments for the application's main method; may be null
props - application-specific properties; may be null
Returns:
the newly-created ORB instance

init

public static ORB init(Applet app,
                       Properties props)
Creates a new ORB instance for an applet. This method may be called from applets only and returns a new fully-functional ORB object each time it is called.

Parameters:
app - the applet; may be null
props - applet-specific properties; may be null
Returns:
the newly-created ORB instance

set_parameters

protected abstract void set_parameters(String[] args,
                                       Properties props)
Allows the ORB implementation to be initialized with the given parameters and properties. This method, used in applications only, is implemented by subclass ORB implementations and called by the appropriate init method to pass in its parameters.

Parameters:
args - command-line arguments for the application's main method; may be null
props - application-specific properties; may be null

set_parameters

protected abstract void set_parameters(Applet app,
                                       Properties props)
Allows the ORB implementation to be initialized with the given applet and parameters. This method, used in applets only, is implemented by subclass ORB implementations and called by the appropriate init method to pass in its parameters.

Parameters:
app - the applet; may be null
props - applet-specific properties; may be null

connect

public void connect(Object obj)
Connects the given servant object (a Java object that is an instance of the server implementation class) to the ORB. The servant class must extend the ImplBase class corresponding to the interface that is supported by the server. The servant must thus be a CORBA object reference, and inherit from org.omg.CORBA.Object. Servants created by the user can start receiving remote invocations after the method connect has been called. A servant may also be automatically and implicitly connected to the ORB if it is passed as an IDL parameter in an IDL method invocation on a non-local object, that is, if the servant object has to be marshalled and sent outside of the process address space.

Calling the method connect has no effect when the servant object is already connected to the ORB.

Deprecated by the OMG in favor of the Portable Object Adapter APIs.

Parameters:
obj - The servant object reference

destroy

public void destroy()
Destroys the ORB so that its resources can be reclaimed. Any operation invoked on a destroyed ORB reference will throw the OBJECT_NOT_EXIST exception. Once an ORB has been destroyed, another call to init with the same ORBid will return a reference to a newly constructed ORB.

If destroy is called on an ORB that has not been shut down, it will start the shut down process and block until the ORB has shut down before it destroys the ORB.
If an application calls destroy in a thread that is currently servicing an invocation, the BAD_INV_ORDER system exception will be thrown with the OMG minor code 3, since blocking would result in a deadlock.

For maximum portability and to avoid resource leaks, an application should always call shutdown and destroy on all ORB instances before exiting.

Throws:
BAD_INV_ORDER - if the current thread is servicing an invocation

disconnect

public void disconnect(Object obj)
Disconnects the given servant object from the ORB. After this method returns, the ORB will reject incoming remote requests for the disconnected servant and will send the exception org.omg.CORBA.OBJECT_NOT_EXIST back to the remote client. Thus the object appears to be destroyed from the point of view of remote clients. Note, however, that local requests issued using the servant directly do not pass through the ORB; hence, they will continue to be processed by the servant.

Calling the method disconnect has no effect if the servant is not connected to the ORB.

Deprecated by the OMG in favor of the Portable Object Adapter APIs.

Parameters:
obj - The servant object to be disconnected from the ORB

list_initial_services

public abstract String[] list_initial_services()
Returns a list of the initially available CORBA object references, such as "NameService" and "InterfaceRepository".

Returns:
an array of String objects that represent the object references for CORBA services that are initially available with this ORB

resolve_initial_references

public abstract Object resolve_initial_references(String object_name)
                                           throws InvalidName
Resolves a specific object reference from the set of available initial service names.

Parameters:
object_name - the name of the initial service as a string
Returns:
the object reference associated with the given name
Throws:
InvalidName - if the given name is not associated with a known service

object_to_string

public abstract String object_to_string(Object obj)
Converts the given CORBA object reference to a string. Note that the format of this string is predefined by IIOP, allowing strings generated by a different ORB to be converted back into an object reference.

The resulting String object may be stored or communicated in any way that a String object can be manipulated.

Parameters:
obj - the object reference to stringify
Returns:
the string representing the object reference

string_to_object

public abstract Object string_to_object(String str)
Converts a string produced by the method object_to_string back to a CORBA object reference.

Parameters:
str - the string to be converted back to an object reference. It must be the result of converting an object reference to a string using the method object_to_string.
Returns:
the object reference

create_list

public abstract NVList create_list(int count)
Allocates an NVList with (probably) enough space for the specified number of NamedValue objects. Note that the specified size is only a hint to help with storage allocation and does not imply the maximum size of the list.

Parameters:
count - suggested number of NamedValue objects for which to allocate space
Returns:
the newly-created NVList
See Also:
NVList

create_operation_list

public NVList create_operation_list(Object oper)
Creates an NVList initialized with argument descriptions for the operation described in the given OperationDef object. This OperationDef object is obtained from an Interface Repository. The arguments in the returned NVList object are in the same order as in the original IDL operation definition, which makes it possible for the list to be used in dynamic invocation requests.

Parameters:
oper - the OperationDef object to use to create the list
Returns:
a newly-created NVList object containing descriptions of the arguments to the method described in the given OperationDef object
See Also:
NVList

create_named_value

public abstract NamedValue create_named_value(String s,
                                              Any any,
                                              int flags)
Creates a NamedValue object using the given name, value, and argument mode flags.

A NamedValue object serves as (1) a parameter or return value or (2) a context property. It may be used by itself or as an element in an NVList object.

Parameters:
s - the name of the NamedValue object
any - the Any value to be inserted into the NamedValue object
flags - the argument mode flags for the NamedValue: one of ARG_IN.value, ARG_OUT.value, or ARG_INOUT.value.
Returns:
the newly-created NamedValue object
See Also:
NamedValue

create_exception_list

public abstract ExceptionList create_exception_list()
Creates an empty ExceptionList object.

Returns:
the newly-created ExceptionList object

create_context_list

public abstract ContextList create_context_list()
Creates an empty ContextList object.

Returns:
the newly-created ContextList object
See Also:
ContextList, Context

get_default_context

public abstract Context get_default_context()
Gets the default Context object.

Returns:
the default Context object
See Also:
Context

create_environment

public abstract Environment create_environment()
Creates an Environment object.

Returns:
the newly-created Environment object
See Also:
Environment

create_output_stream

public abstract OutputStream create_output_stream()
Creates a new org.omg.CORBA.portable.OutputStream into which IDL method parameters can be marshalled during method invocation.

Returns:
the newly-created org.omg.CORBA.portable.OutputStream object

send_multiple_requests_oneway

public abstract void send_multiple_requests_oneway(Request[] req)
Sends multiple dynamic (DII) requests asynchronously without expecting any responses. Note that oneway invocations are not guaranteed to reach the server.

Parameters:
req - an array of request objects

send_multiple_requests_deferred

public abstract void send_multiple_requests_deferred(Request[] req)
Sends multiple dynamic (DII) requests asynchronously.

Parameters:
req - an array of Request objects

poll_next_response

public abstract boolean poll_next_response()
Finds out if any of the deferred (asynchronous) invocations have a response yet.

Returns:
true if there is a response available; false otherwise

get_next_response

public abstract Request get_next_response()
                                   throws WrongTransaction
Gets the next Request instance for which a response has been received.

Returns:
the next Request object ready with a response
Throws:
WrongTransaction - if the method get_next_response is called from a transaction scope different from the one from which the original request was sent. See the OMG Transaction Service specification for details.

get_primitive_tc

public abstract TypeCode get_primitive_tc(TCKind tcKind)
Retrieves the TypeCode object that represents the given primitive IDL type.

Parameters:
tcKind - the TCKind instance corresponding to the desired primitive type
Returns:
the requested TypeCode object

create_struct_tc

public abstract TypeCode create_struct_tc(String id,
                                          String name,
                                          StructMember[] members)
Creates a TypeCode object representing an IDL struct. The TypeCode object is initialized with the given id, name, and members.

Parameters:
id - the repository id for the struct
name - the name of the struct
members - an array describing the members of the struct
Returns:
a newly-created TypeCode object describing an IDL struct

create_union_tc

public abstract TypeCode create_union_tc(String id,
                                         String name,
                                         TypeCode discriminator_type,
                                         UnionMember[] members)
Creates a TypeCode object representing an IDL union. The TypeCode object is initialized with the given id, name, discriminator type, and members.

Parameters:
id - the repository id of the union
name - the name of the union
discriminator_type - the type of the union discriminator
members - an array describing the members of the union
Returns:
a newly-created TypeCode object describing an IDL union

create_enum_tc

public abstract TypeCode create_enum_tc(String id,
                                        String name,
                                        String[] members)
Creates a TypeCode object representing an IDL enum. The TypeCode object is initialized with the given id, name, and members.

Parameters:
id - the repository id for the enum
name - the name for the enum
members - an array describing the members of the enum
Returns:
a newly-created TypeCode object describing an IDL enum

create_alias_tc

public abstract TypeCode create_alias_tc(String id,
                                         String name,
                                         TypeCode original_type)
Creates a TypeCode object representing an IDL alias (typedef). The TypeCode object is initialized with the given id, name, and original type.

Parameters:
id - the repository id for the alias
name - the name for the alias
original_type - the TypeCode object describing the original type for which this is an alias
Returns:
a newly-created TypeCode object describing an IDL alias

create_exception_tc

public abstract TypeCode create_exception_tc(String id,
                                             String name,
                                             StructMember[] members)
Creates a TypeCode object representing an IDL exception. The TypeCode object is initialized with the given id, name, and members.

Parameters:
id - the repository id for the exception
name - the name for the exception
members - an array describing the members of the exception
Returns:
a newly-created TypeCode object describing an IDL exception

create_interface_tc

public abstract TypeCode create_interface_tc(String id,
                                             String name)
Creates a TypeCode object representing an IDL interface. The TypeCode object is initialized with the given id and name.

Parameters:
id - the repository id for the interface
name - the name for the interface
Returns:
a newly-created TypeCode object describing an IDL interface

create_string_tc

public abstract TypeCode create_string_tc(int bound)
Creates a TypeCode object representing a bounded IDL string. The TypeCode object is initialized with the given bound, which represents the maximum length of the string. Zero indicates that the string described by this type code is unbounded.

Parameters:
bound - the bound for the string; cannot be negative
Returns:
a newly-created TypeCode object describing a bounded IDL string
Throws:
BAD_PARAM - if bound is a negative value

create_wstring_tc

public abstract TypeCode create_wstring_tc(int bound)
Creates a TypeCode object representing a bounded IDL wstring (wide string). The TypeCode object is initialized with the given bound, which represents the maximum length of the wide string. Zero indicates that the string described by this type code is unbounded.

Parameters:
bound - the bound for the wstring; cannot be negative
Returns:
a newly-created TypeCode object describing a bounded IDL wstring
Throws:
BAD_PARAM - if bound is a negative value

create_sequence_tc

public abstract TypeCode create_sequence_tc(int bound,
                                            TypeCode element_type)
Creates a TypeCode object representing an IDL sequence. The TypeCode object is initialized with the given bound and element type.

Parameters:
bound - the bound for the sequence, 0 if unbounded
element_type - the TypeCode object describing the elements contained in the sequence
Returns:
a newly-created TypeCode object describing an IDL sequence

create_recursive_sequence_tc

@Deprecated
public abstract TypeCode create_recursive_sequence_tc(int bound,
                                                                 int offset)
Deprecated. Use a combination of create_recursive_tc and create_sequence_tc instead

Creates a TypeCode object representing a a recursive IDL sequence.

For the IDL struct Node in following code fragment, the offset parameter for creating its sequence would be 1:

    Struct Node {
        long value;
        Sequence <Node> subnodes;
    };

Parameters:
bound - the bound for the sequence, 0 if unbounded
offset - the index to the enclosing TypeCode object that describes the elements of this sequence
Returns:
a newly-created TypeCode object describing a recursive sequence
See Also:
create_recursive_tc, create_sequence_tc

create_array_tc

public abstract TypeCode create_array_tc(int length,
                                         TypeCode element_type)
Creates a TypeCode object representing an IDL array. The TypeCode object is initialized with the given length and element type.

Parameters:
length - the length of the array
element_type - a TypeCode object describing the type of element contained in the array
Returns:
a newly-created TypeCode object describing an IDL array

create_native_tc

public TypeCode create_native_tc(String id,
                                 String name)
Create a TypeCode object for an IDL native type.

Parameters:
id - the logical id for the native type.
name - the name of the native type.
Returns:
the requested TypeCode.

create_abstract_interface_tc

public TypeCode create_abstract_interface_tc(String id,
                                             String name)
Create a TypeCode object for an IDL abstract interface.

Parameters:
id - the logical id for the abstract interface type.
name - the name of the abstract interface type.
Returns:
the requested TypeCode.

create_fixed_tc

public TypeCode create_fixed_tc(short digits,
                                short scale)
Create a TypeCode object for an IDL fixed type.

Parameters:
digits - specifies the total number of decimal digits in the number and must be from 1 to 31 inclusive.
scale - specifies the position of the decimal point.
Returns:
the requested TypeCode.

create_value_tc

public TypeCode create_value_tc(String id,
                                String name,
                                short type_modifier,
                                TypeCode concrete_base,
                                ValueMember[] members)
Create a TypeCode object for an IDL value type. The concrete_base parameter is the TypeCode for the immediate concrete valuetype base of the valuetype for which the TypeCode is being created. It may be null if the valuetype does not have a concrete base.

Parameters:
id - the logical id for the value type.
name - the name of the value type.
type_modifier - one of the value type modifier constants: VM_NONE, VM_CUSTOM, VM_ABSTRACT or VM_TRUNCATABLE
concrete_base - a TypeCode object describing the concrete valuetype base
members - an array containing the members of the value type
Returns:
the requested TypeCode

create_recursive_tc

public TypeCode create_recursive_tc(String id)
Create a recursive TypeCode object which serves as a placeholder for a concrete TypeCode during the process of creating TypeCodes which contain recursion. The id parameter specifies the repository id of the type for which the recursive TypeCode is serving as a placeholder. Once the recursive TypeCode has been properly embedded in the enclosing TypeCode which corresponds to the specified repository id, it will function as a normal TypeCode. Invoking operations on the recursive TypeCode before it has been embedded in the enclosing TypeCode will result in a BAD_TYPECODE exception.

For example, the following IDL type declaration contains recursion:

    Struct Node {
        Sequence<Node> subnodes;
    };

To create a TypeCode for struct Node, you would invoke the TypeCode creation operations as shown below:

 String nodeID = "IDL:Node:1.0";
 TypeCode recursiveSeqTC = orb.create_sequence_tc(0, orb.create_recursive_tc(nodeID));
 StructMember[] members = { new StructMember("subnodes", recursiveSeqTC, null) };
 TypeCode structNodeTC = orb.create_struct_tc(nodeID, "Node", members);

Also note that the following is an illegal IDL type declaration:

    Struct Node {
        Node next;
    };

Recursive types can only appear within sequences which can be empty. That way marshaling problems, when transmitting the struct in an Any, are avoided.

Parameters:
id - the logical id of the referenced type
Returns:
the requested TypeCode

create_value_box_tc

public TypeCode create_value_box_tc(String id,
                                    String name,
                                    TypeCode boxed_type)
Creates a TypeCode object for an IDL value box.

Parameters:
id - the logical id for the value type
name - the name of the value type
boxed_type - the TypeCode for the type
Returns:
the requested TypeCode

create_any

public abstract Any create_any()
Creates an IDL Any object initialized to contain a Typecode object whose kind field is set to TCKind.tc_null.

Returns:
a newly-created Any object

get_current

@Deprecated
public Current get_current()
Deprecated. use resolve_initial_references.

Retrieves a Current object. The Current interface is used to manage thread-specific information for use by services such as transactions and security.

Returns:
a newly-created Current object
See Also:
CORBA package comments for unimplemented features

run

public void run()
This operation blocks the current thread until the ORB has completed the shutdown process, initiated when some thread calls shutdown. It may be used by multiple threads which get all notified when the ORB shuts down.

shutdown

public void shutdown(boolean wait_for_completion)
Instructs the ORB to shut down, which causes all object adapters to shut down, in preparation for destruction.
If the wait_for_completion parameter is true, this operation blocks until all ORB processing (including processing of currently executing requests, object deactivation, and other object adapter operations) has completed. If an application does this in a thread that is currently servicing an invocation, the BAD_INV_ORDER system exception will be thrown with the OMG minor code 3, since blocking would result in a deadlock.
If the wait_for_completion parameter is FALSE, then shutdown may not have completed upon return.

While the ORB is in the process of shutting down, the ORB operates as normal, servicing incoming and outgoing requests until all requests have been completed. Once an ORB has shutdown, only object reference management operations may be invoked on the ORB or any object reference obtained from it. An application may also invoke the destroy operation on the ORB itself. Invoking any other operation will throw the BAD_INV_ORDER system exception with the OMG minor code 4.

The ORB.run method will return after shutdown has been called.

Parameters:
wait_for_completion - true if the call should block until the shutdown is complete; false if it should return immediately
Throws:
BAD_INV_ORDER - if the current thread is servicing an invocation

work_pending

public boolean work_pending()
Returns true if the ORB needs the main thread to perform some work, and false if the ORB does not need the main thread.

Returns:
true if there is work pending, meaning that the ORB needs the main thread to perform some work; false if there is no work pending and thus the ORB does not need the main thread

perform_work

public void perform_work()
Performs an implementation-dependent unit of work if called by the main thread. Otherwise it does nothing. The methods work_pending and perform_work can be used in conjunction to implement a simple polling loop that multiplexes the main thread among the ORB and other activities.

get_service_information

public boolean get_service_information(short service_type,
                                       ServiceInformationHolder service_info)
Used to obtain information about CORBA facilities and services that are supported by this ORB. The service type for which information is being requested is passed in as the in parameter service_type, the values defined by constants in the CORBA module. If service information is available for that type, that is returned in the out parameter service_info, and the operation returns the value true. If no information for the requested services type is available, the operation returns false (i.e., the service is not supported by this ORB).

Parameters:
service_type - a short indicating the service type for which information is being requested
service_info - a ServiceInformationHolder object that will hold the ServiceInformation object produced by this method
Returns:
true if service information is available for the service_type; false if no information for the requested services type is available
See Also:
CORBA package comments for unimplemented features

create_dyn_any

@Deprecated
public DynAny create_dyn_any(Any value)
Deprecated. Use the new DynAnyFactory API instead

Creates a new DynAny object from the given Any object.

Parameters:
value - the Any object from which to create a new DynAny object
Returns:
the new DynAny object created from the given Any object
See Also:
CORBA package comments for unimplemented features

create_basic_dyn_any

@Deprecated
public DynAny create_basic_dyn_any(TypeCode type)
                            throws InconsistentTypeCode
Deprecated. Use the new DynAnyFactory API instead

Creates a basic DynAny object from the given TypeCode object.

Parameters:
type - the TypeCode object from which to create a new DynAny object
Returns:
the new DynAny object created from the given TypeCode object
Throws:
InconsistentTypeCode - if the given TypeCode object is not consistent with the operation.
See Also:
CORBA package comments for unimplemented features

create_dyn_struct

@Deprecated
public DynStruct create_dyn_struct(TypeCode type)
                            throws InconsistentTypeCode
Deprecated. Use the new DynAnyFactory API instead

Creates a new DynStruct object from the given TypeCode object.

Parameters:
type - the TypeCode object from which to create a new DynStruct object
Returns:
the new DynStruct object created from the given TypeCode object
Throws:
InconsistentTypeCode - if the given TypeCode object is not consistent with the operation.
See Also:
CORBA package comments for unimplemented features

create_dyn_sequence

@Deprecated
public DynSequence create_dyn_sequence(TypeCode type)
                                throws InconsistentTypeCode
Deprecated. Use the new DynAnyFactory API instead

Creates a new DynSequence object from the given TypeCode object.

Parameters:
type - the TypeCode object from which to create a new DynSequence object
Returns:
the new DynSequence object created from the given TypeCode object
Throws:
InconsistentTypeCode - if the given TypeCode object is not consistent with the operation.
See Also:
CORBA package comments for unimplemented features

create_dyn_array

@Deprecated
public DynArray create_dyn_array(TypeCode type)
                          throws InconsistentTypeCode
Deprecated. Use the new DynAnyFactory API instead

Creates a new DynArray object from the given TypeCode object.

Parameters:
type - the TypeCode object from which to create a new DynArray object
Returns:
the new DynArray object created from the given TypeCode object
Throws:
InconsistentTypeCode - if the given TypeCode object is not consistent with the operation.
See Also:
CORBA package comments for unimplemented features

create_dyn_union

@Deprecated
public DynUnion create_dyn_union(TypeCode type)
                          throws InconsistentTypeCode
Deprecated. Use the new DynAnyFactory API instead

Creates a new DynUnion object from the given TypeCode object.

Parameters:
type - the TypeCode object from which to create a new DynUnion object
Returns:
the new DynUnion object created from the given TypeCode object
Throws:
InconsistentTypeCode - if the given TypeCode object is not consistent with the operation.
See Also:
CORBA package comments for unimplemented features

create_dyn_enum

@Deprecated
public DynEnum create_dyn_enum(TypeCode type)
                        throws InconsistentTypeCode
Deprecated. Use the new DynAnyFactory API instead

Creates a new DynEnum object from the given TypeCode object.

Parameters:
type - the TypeCode object from which to create a new DynEnum object
Returns:
the new DynEnum object created from the given TypeCode object
Throws:
InconsistentTypeCode - if the given TypeCode object is not consistent with the operation.
See Also:
CORBA package comments for unimplemented features

create_policy

public Policy create_policy(int type,
                            Any val)
                     throws PolicyError
Can be invoked to create new instances of policy objects of a specific type with specified initial state. If create_policy fails to instantiate a new Policy object due to its inability to interpret the requested type and content of the policy, it raises the PolicyError exception with the appropriate reason.

Parameters:
type - the PolicyType of the policy object to be created
val - the value that will be used to set the initial state of the Policy object that is created
Returns:
Reference to a newly created Policy object of type specified by the type parameter and initialized to a state specified by the val parameter
Throws:
org.omg.CORBA.PolicyError - when the requested policy is not supported or a requested initial state for the policy is not supported.
PolicyError
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ORBPackage

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.CORBA.ORBPackage

Provides the exception InvalidName, which is thrown by the method ORB.resolve_initial_references and the exception InconsistentTypeCode, which is thrown by the Dynamic Any creation methods in the ORB class.

See:
Description

Exception Summary
InconsistentTypeCode | InconsistentTypeCode is thrown when an attempt is made to create a dynamic any with a type code that does not match the particular subclass of DynAny.
InvalidName | The InvalidName exception is raised when ORB.resolve_initial_references is passed a name for which there is no initial reference.

Package org.omg.CORBA.ORBPackage Description

Provides the exception InvalidName, which is thrown by the method ORB.resolve_initial_references and the exception InconsistentTypeCode, which is thrown by the Dynamic Any creation methods in the ORB class.

Related Documentation

For an overview, please see:
  • comments on the CORBA package

Since:
JDK1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.CORBA.ORBPackage Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.CORBA.ORBPackage

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.omg.CORBA.UserException (implements org.omg.CORBA.portable.IDLEntity)
          • org.omg.CORBA.ORBPackage.InconsistentTypeCode
          • org.omg.CORBA.ORBPackage.InvalidName
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.CORBA.ORBPackage

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.CORBA.ORBPackage

Packages that use org.omg.CORBA.ORBPackage
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Classes in org.omg.CORBA.ORBPackage used by org.omg.CORBA
InconsistentTypeCode
InconsistentTypeCode is thrown when an attempt is made to create a dynamic any with a type code that does not match the particular subclass of DynAny.
InvalidName
The InvalidName exception is raised when ORB.resolve_initial_references is passed a name for which there is no initial reference.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ORBPackage.InconsistentTypeCode

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ORBPackage.InconsistentTypeCode

Packages that use InconsistentTypeCode
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of InconsistentTypeCode in org.omg.CORBA

Methods in org.omg.CORBA that throw InconsistentTypeCode
DynAny | ORB.create_basic_dyn_any(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
DynArray | ORB.create_dyn_array(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
DynEnum | ORB.create_dyn_enum(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
DynSequence | ORB.create_dyn_sequence(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
DynStruct | ORB.create_dyn_struct(TypeCode type) Deprecated. Use the new DynAnyFactory API instead
DynUnion | ORB.create_dyn_union(TypeCode type) Deprecated. Use the new DynAnyFactory API instead

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.ORBPackage.InvalidName

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.ORBPackage.InvalidName

Packages that use InvalidName
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of InvalidName in org.omg.CORBA

Methods in org.omg.CORBA that throw InvalidName
abstract  Object ORB.resolve_initial_references(String object_name)
Resolves a specific object reference from the set of available initial service names.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


InconsistentTypeCode

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.ORBPackage
Class InconsistentTypeCode

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CORBA.ORBPackage.InconsistentTypeCode
All Implemented Interfaces:
Serializable, IDLEntity
public final class InconsistentTypeCode
extends UserException

InconsistentTypeCode is thrown when an attempt is made to create a dynamic any with a type code that does not match the particular subclass of DynAny.

Constructor Summary
InconsistentTypeCode()
Constructs an InconsistentTypeCode user exception with no reason message.
InconsistentTypeCode(String reason)
Constructs an InconsistentTypeCode user exception with the specified reason message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InconsistentTypeCode

public InconsistentTypeCode()
Constructs an InconsistentTypeCode user exception with no reason message.

InconsistentTypeCode

public InconsistentTypeCode(String reason)
Constructs an InconsistentTypeCode user exception with the specified reason message.

Parameters:
reason - The String containing a reason message
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


InvalidName

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.ORBPackage
Class InvalidName

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CORBA.ORBPackage.InvalidName
All Implemented Interfaces:
Serializable, IDLEntity
public final class InvalidName
extends UserException

The InvalidName exception is raised when ORB.resolve_initial_references is passed a name for which there is no initial reference.

Since:
JDK1.2
See Also:
ORB.resolve_initial_references(String)

Constructor Summary
InvalidName()
Constructs an InvalidName exception with no reason message.
InvalidName(String reason)
Constructs an InvalidName exception with the specified reason message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidName

public InvalidName()
Constructs an InvalidName exception with no reason message.

InvalidName

public InvalidName(String reason)
Constructs an InvalidName exception with the specified reason message.

Parameters:
reason - the String containing a reason message
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


ParameterMode

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ParameterMode

java.lang.Object
    extended by  org.omg.CORBA.ParameterMode
All Implemented Interfaces:
Serializable, IDLEntity
public class ParameterMode
extends Object
implements IDLEntity

Enumeration of parameter modes for Parameter. Possible vaues:

  • PARAM_IN - Represents an "in" parameter.
  • PARAM_OUT - Represents an "out" parameter.
  • PARAM_INOUT - Represents an "inout" parameter.

Field Summary
static int | _PARAM_IN
static int | _PARAM_INOUT
static int | _PARAM_OUT
static ParameterMode | PARAM_IN
static ParameterMode | PARAM_INOUT
static ParameterMode | PARAM_OUT
Constructor Summary
protected ParameterMode(int value)
Method Summary
static ParameterMode | from_int(int value)
int | value()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_PARAM_IN

public static final int _PARAM_IN
See Also:
Constant Field Values

PARAM_IN

public static final ParameterMode PARAM_IN

_PARAM_OUT

public static final int _PARAM_OUT
See Also:
Constant Field Values

PARAM_OUT

public static final ParameterMode PARAM_OUT

_PARAM_INOUT

public static final int _PARAM_INOUT
See Also:
Constant Field Values

PARAM_INOUT

public static final ParameterMode PARAM_INOUT
Constructor Detail

ParameterMode

protected ParameterMode(int value)
Method Detail

value

public int value()

from_int

public static ParameterMode from_int(int value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ParameterModeHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ParameterModeHelper

java.lang.Object
    extended by  org.omg.CORBA.ParameterModeHelper

public abstract class ParameterModeHelper
extends Object

Enumeration of parameter modes for Parameter. Possible vaues:

  • PARAM_IN - Represents an "in" parameter.
  • PARAM_OUT - Represents an "out" parameter.
  • PARAM_INOUT - Represents an "inout" parameter.

Constructor Summary
ParameterModeHelper()
Method Summary
static ParameterMode | extract(Any a)
static String | id()
static void | insert(Any a, ParameterMode that)
static ParameterMode | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, ParameterMode value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ParameterModeHelper

public ParameterModeHelper()
Method Detail

insert

public static void insert(Any a,
                          ParameterMode that)

extract

public static ParameterMode extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static ParameterMode read(InputStream istream)

write

public static void write(OutputStream ostream,
                         ParameterMode value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ParameterModeHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ParameterModeHolder

java.lang.Object
    extended by  org.omg.CORBA.ParameterModeHolder
All Implemented Interfaces:
Streamable
public final class ParameterModeHolder
extends Object
implements Streamable

Enumeration of parameter modes for Parameter. Possible vaues:

  • PARAM_IN - Represents an "in" parameter.
  • PARAM_OUT - Represents an "out" parameter.
  • PARAM_INOUT - Represents an "inout" parameter.

Field Summary
 ParameterMode value
Constructor Summary
ParameterModeHolder()
ParameterModeHolder(ParameterMode initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public ParameterMode value
Constructor Detail

ParameterModeHolder

public ParameterModeHolder()

ParameterModeHolder

public ParameterModeHolder(ParameterMode initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PERSIST_STORE

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class PERSIST_STORE

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.PERSIST_STORE
All Implemented Interfaces:
Serializable
public final class PERSIST_STORE
extends SystemException

This exception indicates a persistent storage failure, for example, failure to establish a database connection or corruption of a database.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
PERSIST_STORE()
Constructs a PERSIST_STORE exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.
PERSIST_STORE(int minor, CompletionStatus completed)
Constructs a PERSIST_STORE exception with the specified minor code and completion status.
PERSIST_STORE(String s)
Constructs a PERSIST_STORE exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.
PERSIST_STORE(String s, int minor, CompletionStatus completed)
Constructs a PERSIST_STORE exception with the specified description message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PERSIST_STORE

public PERSIST_STORE()
Constructs a PERSIST_STORE exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.

PERSIST_STORE

public PERSIST_STORE(String s)
Constructs a PERSIST_STORE exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message

PERSIST_STORE

public PERSIST_STORE(int minor,
                     CompletionStatus completed)
Constructs a PERSIST_STORE exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

PERSIST_STORE

public PERSIST_STORE(String s,
                     int minor,
                     CompletionStatus completed)
Constructs a PERSIST_STORE exception with the specified description message, minor code, and completion status.

Parameters:
s - the String containing a description message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PolicyError

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class PolicyError

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CORBA.PolicyError
All Implemented Interfaces:
Serializable, IDLEntity
public final class PolicyError
extends UserException

A user exception thrown when a policy error occurs. A PolicyError exception may include one of the following policy error reason codes defined in the org.omg.CORBA package: BAD_POLICY, BAD_POLICY_TYPE, BAD_POLICY_VALUE, UNSUPPORTED_POLICY, UNSUPPORTED_POLICY_VALUE.

Field Summary
 short reason
The reason for the PolicyError exception being thrown.
Constructor Summary
PolicyError()
Constructs a default PolicyError user exception with no reason code and an empty reason detail message.
PolicyError(short __reason)
Constructs a PolicyError user exception initialized with the given reason code and an empty reason detail message.
PolicyError(String reason_string, short __reason)
Constructs a PolicyError user exception initialized with the given reason detail message and reason code.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

reason

public short reason
The reason for the PolicyError exception being thrown.

Constructor Detail

PolicyError

public PolicyError()
Constructs a default PolicyError user exception with no reason code and an empty reason detail message.

PolicyError

public PolicyError(short __reason)
Constructs a PolicyError user exception initialized with the given reason code and an empty reason detail message.

Parameters:
__reason - the reason code.

PolicyError

public PolicyError(String reason_string,
                   short __reason)
Constructs a PolicyError user exception initialized with the given reason detail message and reason code.

Parameters:
reason_string - the reason detail message.
__reason - the reason code.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PolicyErrorCodeHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class PolicyErrorCodeHelper

java.lang.Object
    extended by  org.omg.CORBA.PolicyErrorCodeHelper

public abstract class PolicyErrorCodeHelper
extends Object

Encapsulates a reason a Policy may be invalid.

See Also:
PolicyError

Constructor Summary
PolicyErrorCodeHelper()
Method Summary
static short | extract(Any a)
static String | id()
static void | insert(Any a, short that)
static short | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, short value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PolicyErrorCodeHelper

public PolicyErrorCodeHelper()
Method Detail

insert

public static void insert(Any a,
                          short that)

extract

public static short extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static short read(InputStream istream)

write

public static void write(OutputStream ostream,
                         short value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PolicyErrorHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class PolicyErrorHelper

java.lang.Object
    extended by  org.omg.CORBA.PolicyErrorHelper

public abstract class PolicyErrorHelper
extends Object

Thrown to indicate problems with parameter values passed to the ORB.create_policy operation.

Constructor Summary
PolicyErrorHelper()
Method Summary
static PolicyError | extract(Any a)
static String | id()
static void | insert(Any a, PolicyError that)
static PolicyError | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, PolicyError value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PolicyErrorHelper

public PolicyErrorHelper()
Method Detail

insert

public static void insert(Any a,
                          PolicyError that)

extract

public static PolicyError extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static PolicyError read(InputStream istream)

write

public static void write(OutputStream ostream,
                         PolicyError value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PolicyErrorHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class PolicyErrorHolder

java.lang.Object
    extended by  org.omg.CORBA.PolicyErrorHolder
All Implemented Interfaces:
Streamable
public final class PolicyErrorHolder
extends Object
implements Streamable

Thrown to indicate problems with parameter values passed to the ORB.create_policy operation.

Field Summary
 PolicyError value
Constructor Summary
PolicyErrorHolder()
PolicyErrorHolder(PolicyError initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public PolicyError value
Constructor Detail

PolicyErrorHolder

public PolicyErrorHolder()

PolicyErrorHolder

public PolicyErrorHolder(PolicyError initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PolicyHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class PolicyHelper

java.lang.Object
    extended by  org.omg.CORBA.PolicyHelper

public abstract class PolicyHelper
extends Object

The Helper for Policy. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/PolicyHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ../../../../../src/share/classes/org/omg/PortableServer/corba.idl Saturday, July 17, 1999 12:26:20 AM PDT

Constructor Summary
PolicyHelper()
Method Summary
static Policy | extract(Any a)
static String | id()
static void | insert(Any a, Policy that)
static Policy | narrow(Object obj)
static Policy | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, Policy value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PolicyHelper

public PolicyHelper()
Method Detail

insert

public static void insert(Any a,
                          Policy that)

extract

public static Policy extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static Policy read(InputStream istream)

write

public static void write(OutputStream ostream,
                         Policy value)

narrow

public static Policy narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PolicyHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class PolicyHolder

java.lang.Object
    extended by  org.omg.CORBA.PolicyHolder
All Implemented Interfaces:
Streamable
public final class PolicyHolder
extends Object
implements Streamable

The Holder for Policy. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/PolicyHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ../../../../../src/share/classes/org/omg/PortableServer/corba.idl Saturday, July 17, 1999 12:26:20 AM PDT

Field Summary
 Policy value
Constructor Summary
PolicyHolder()
PolicyHolder(Policy initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public Policy value
Constructor Detail

PolicyHolder

public PolicyHolder()

PolicyHolder

public PolicyHolder(Policy initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PolicyListHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class PolicyListHelper

java.lang.Object
    extended by  org.omg.CORBA.PolicyListHelper

public abstract class PolicyListHelper
extends Object

The Helper for PolicyList. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/PolicyListHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ../../../../../src/share/classes/org/omg/PortableServer/corba.idl Saturday, July 17, 1999 12:26:21 AM PDT

Constructor Summary
PolicyListHelper()
Method Summary
static Policy[] | extract(Any a)
static String | id()
static void | insert(Any a, Policy[] that)
static Policy[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, Policy[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PolicyListHelper

public PolicyListHelper()
Method Detail

insert

public static void insert(Any a,
                          Policy[] that)

extract

public static Policy[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static Policy[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         Policy[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PolicyListHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class PolicyListHolder

java.lang.Object
    extended by  org.omg.CORBA.PolicyListHolder
All Implemented Interfaces:
Streamable
public final class PolicyListHolder
extends Object
implements Streamable

The Holder for PolicyList. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/PolicyListHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ../../../../../src/share/classes/org/omg/PortableServer/corba.idl Saturday, July 17, 1999 12:26:21 AM PDT

Field Summary
 Policy[] value
Constructor Summary
PolicyListHolder()
PolicyListHolder(Policy[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public Policy[] value
Constructor Detail

PolicyListHolder

public PolicyListHolder()

PolicyListHolder

public PolicyListHolder(Policy[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PolicyOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface PolicyOperations

All Known Subinterfaces:
IdAssignmentPolicy, IdAssignmentPolicyOperations, IdUniquenessPolicy, IdUniquenessPolicyOperations, ImplicitActivationPolicy, ImplicitActivationPolicyOperations, LifespanPolicy, LifespanPolicyOperations, Policy, RequestProcessingPolicy, RequestProcessingPolicyOperations, ServantRetentionPolicy, ServantRetentionPolicyOperations, ThreadPolicy, ThreadPolicyOperations
All Known Implementing Classes:
_PolicyStub
public interface PolicyOperations

Provides the operations for a Policy object.

Method Summary
Policy | copy() Returns a copy of the Policy object.
void | destroy() Destroys the Policy object.
int | policy_type() Returns the constant value that corresponds to the type of the policy object.

Method Detail

policy_type

int policy_type()
Returns the constant value that corresponds to the type of the policy object. The values of the policy objects are allocated by the OMG. New values for PolicyType should be obtained from the OMG by sending mail to request@omg.org. In general the constant values that are allocated are defined in conjunction with the definition of the corresponding policy object.

Returns:
the constant value that corresponds to the type of the policy object

copy

Policy copy()
Returns a copy of the Policy object. The copy does not retain any relationships that the policy had with any domain or object.

Returns:
a copy of the Policy object

destroy

void destroy()
Destroys the Policy object. It is the responsibility of the Policy object to determine whether it can be destroyed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PolicyTypeHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class PolicyTypeHelper

java.lang.Object
    extended by  org.omg.CORBA.PolicyTypeHelper

public abstract class PolicyTypeHelper
extends Object

The Helper for PolicyType. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/PolicyTypeHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ../../../../../src/share/classes/org/omg/PortableServer/corba.idl Saturday, July 17, 1999 12:26:20 AM PDT

Constructor Summary
PolicyTypeHelper()
Method Summary
static int | extract(Any a)
static String | id()
static void | insert(Any a, int that)
static int | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, int value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PolicyTypeHelper

public PolicyTypeHelper()
Method Detail

insert

public static void insert(Any a,
                          int that)

extract

public static int extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static int read(InputStream istream)

write

public static void write(OutputStream ostream,
                         int value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


portable

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.CORBA.portable

Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.

See:
Description

Interface Summary
BoxedValueHelper |
CustomValue | An extension of ValueBase that is implemented by custom value types.
IDLEntity | An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.
InvokeHandler | This interface provides a dispatching mechanism for an incoming call.
ResponseHandler | This interface is supplied by an ORB to a servant at invocation time and allows the servant to later retrieve an OutputStream for returning the invocation results.
Streamable | The base class for the Holder classess of all complex IDL types.
StreamableValue | Defines the base type for all non-boxed IDL valuetypes that are not custom marshaled.
ValueBase | The generated Java classes corresponding to valuetype IDL types implement this interface.
ValueFactory | The ValueFactory interface is the native mapping for the IDL type CORBA::ValueFactory.
ValueInputStream | Java to IDL ptc 02-01-12 1.5.1.4 ValueInputStream is used for implementing RMI-IIOP stream format version 2.
ValueOutputStream | Java to IDL ptc 02-01-12 1.5.1.3 ValueOutputStream is used for implementing RMI-IIOP stream format version 2.

Class Summary
Delegate | Specifies a portable API for ORB-vendor-specific implementation of the org.omg.CORBA.Object methods.
InputStream | InputStream is the Java API for reading IDL types from CDR marshal streams.
ObjectImpl | The common base class for all stub classes; provides default implementations of the org.omg.CORBA.Object methods.
OutputStream | OuputStream is the Java API for writing IDL types to CDR marshal streams.
ServantObject | This class is part of the local stub API, the purpose of which is to provide high performance calls for collocated clients and servers (i.e.

Exception Summary
ApplicationException | This class is used for reporting application level exceptions between ORBs and stubs.
IndirectionException | The Indirection exception is a Java specific system exception.
RemarshalException | This class is used for reporting locate forward exceptions and object forward GIOP messages back to the ORB.
UnknownException | The org.omg.CORBA.portable.UnknownException is used for reporting unknown exceptions between ties and ORBs and between ORBs and stubs.

Package org.omg.CORBA.portable Description

Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB. Stubs and other code, generated either from IDL or interfaces written in the Java programming language, can call into these ORB APIs.

CORBA Features Throwing NO_IMPLEMENT() Exceptions

Some methods throw NO_IMPLEMENT() exceptions by default, but ORB vendors can override them to provide real implementations. The ORB included in Sun's release of the Java[tm] Platform, Standard Edition 6, includes implementations for the following methods.

List of Unimplemented Features in Package org.omg.CORBA.portable

Unimplemented Interfaces in package org.omg.CORBA.portable

  • InvokeHandler
  • ResponseHandler

Unimplemented Methods in package org.omg.CORBA.portable

  • InputStream
    • public int read()
    • public.math.BigDecimal read_fixed()
    • public org.omg.CORBA.Context read_Context()
    • public org.omg.CORBA.Object read_Object(java.lang.Class clz)
    • public org.omg.CORBA.ORB orb()
  • OutputStream
    • public org.omg.CORBA.ORB orb()
    • public void write_Context(org.omg.CORBA.Context ctx, org.omg.CORBA.ContextList contexts)
    • public void write_fixed(java.math.BigDecimal value)
    • public void write(int b)
  • Delegate
    • public void releaseReply(org.omg.CORBA.Object self, InputStream input)
    • public InputStream invoke(org.omg.CORBA.Object self, OutputStream output)
    • public OutputStream request(org.omg.CORBA.Object self, String operation, boolean responseExpected)
    • public org.omg.CORBA.Object set_policy_override(org.omg.CORBA.Object self, org.omg.CORBA.Policy[] policies, org.omg.CORBA.SetOverrideType set_add)
    • public org.omg.CORBA.DomainManager[] get_domain_managers( org.omg.CORBA.Object self)
    • public org.omg.CORBA.Policy get_policy(org.omg.CORBA.Object self, int policy_type)

Since:
JDK1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


CustomValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Interface CustomValue

All Superinterfaces:
CustomMarshal, IDLEntity, Serializable, ValueBase
public interface CustomValue
extends ValueBase, CustomMarshal

An extension of ValueBase that is implemented by custom value types.

Method Summary
Methods inherited from interface org.omg.CORBA.portable.ValueBase
_truncatable_ids
Methods inherited from interface org.omg.CORBA.CustomMarshal
marshal, unmarshal

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IDLEntity

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Interface IDLEntity

All Superinterfaces:
Serializable
All Known Subinterfaces:
AdapterActivator, BindingIterator, ClientRequestInfo, ClientRequestInterceptor, Codec, CodecFactory, Current, Current, Current, CustomValue, DataInputStream, DataOutputStream, DomainManager, DynAny, DynAnyFactory, DynArray, DynEnum, DynFixed, DynSequence, DynStruct, DynUnion, DynValue, DynValueBox, DynValueCommon, IdAssignmentPolicy, IDLType, IdUniquenessPolicy, ImplicitActivationPolicy, Interceptor, IORInfo, IORInterceptor, IORInterceptor_3_0, IRObject, LifespanPolicy, NamingContext, NamingContextExt, ObjectReferenceFactory, ObjectReferenceTemplate, ORBInitializer, ORBInitInfo, POA, POAManager, Policy, PolicyFactory, RequestInfo, RequestProcessingPolicy, RunTime, ServantActivator, ServantLocator, ServantManager, ServantRetentionPolicy, ServerRequestInfo, ServerRequestInterceptor, StreamableValue, ThreadPolicy, ValueBase
All Known Implementing Classes:
_BindingIteratorImplBase, _BindingIteratorStub, _DynAnyFactoryStub, _DynAnyStub, _DynArrayStub, _DynEnumStub, _DynFixedStub, _DynSequenceStub, _DynStructStub, _DynUnionStub, _DynValueStub, _IDLTypeStub, _NamingContextExtStub, _NamingContextImplBase, _NamingContextStub, _PolicyStub, _ServantActivatorStub, _ServantLocatorStub, AdapterAlreadyExists, AdapterInactive, AdapterNonExistent, AlreadyBound, Any, BadKind, Binding, BindingType, Bounds, Bounds, CannotProceed, CompletionStatus, DefinitionKind, DuplicateName, Encoding, FormatMismatch, ForwardRequest, ForwardRequest, IdAssignmentPolicyValue, IdUniquenessPolicyValue, ImplicitActivationPolicyValue, InconsistentTypeCode, InconsistentTypeCode, Invalid, InvalidAddress, InvalidName, InvalidName, InvalidName, InvalidPolicy, InvalidSeq, InvalidSlot, InvalidTypeForEncoding, InvalidValue, InvalidValue, IOR, LifespanPolicyValue, NameComponent, NameDynAnyPair, NameValuePair, NameValuePair, NoContext, NoServant, NotEmpty, NotFound, NotFoundReason, ObjectAlreadyActive, ObjectNotActive, Parameter, ParameterMode, PolicyError, RequestProcessingPolicyValue, ServantAlreadyActive, ServantNotActive, ServantRetentionPolicyValue, ServiceContext, ServiceDetail, ServiceInformation, SetOverrideType, State, StructMember, TaggedComponent, TaggedProfile, ThreadPolicyValue, TypeCode, TypeMismatch, TypeMismatch, TypeMismatch, UnionMember, UnknownEncoding, UnknownUserException, UserException, ValueMember, WrongAdapter, WrongPolicy, WrongTransaction
public interface IDLEntity
extends Serializable

An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class. RMI IIOP serialization looks for such a marker to perform marshalling/unmarshalling.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvokeHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Interface InvokeHandler

All Known Subinterfaces:
Tie
All Known Implementing Classes:
BindingIteratorPOA, NamingContextExtPOA, NamingContextPOA, ServantActivatorPOA, ServantLocatorPOA
public interface InvokeHandler

This interface provides a dispatching mechanism for an incoming call. It is invoked by the ORB to dispatch a request to a servant.

Method Summary
 OutputStream _invoke(String method, InputStream input, ResponseHandler handler)
Invoked by the ORB to dispatch a request to the servant.

Method Detail

_invoke

OutputStream _invoke(String method,
                     InputStream input,
                     ResponseHandler handler)
                     throws SystemException
Invoked by the ORB to dispatch a request to the servant. ORB passes the method name, an InputStream containing the marshalled arguments, and a ResponseHandler which the servant uses to construct a proper reply. Only CORBA SystemException may be thrown by this method. The method must return an OutputStream created by the ResponseHandler which contains the marshalled reply. A servant must not retain a reference to the ResponseHandler beyond the lifetime of a method invocation. Servant behaviour is defined as follows:

1. Determine correct method, and unmarshal parameters from InputStream.

2. Invoke method implementation.

3. If no user exception, create a normal reply using ResponseHandler.

4. If user exception occurred, create exception reply using ResponseHandler.

5. Marshal reply into OutputStream returned by ResponseHandler.

6. Return OutputStream to ORB.

Parameters:
method - The method name.
input - The InputStream containing the marshalled arguments.
handler - The ResponseHandler which the servant uses to construct a proper reply
Returns:
The OutputStream created by the ResponseHandler which contains the marshalled reply
Throws:
SystemException - is thrown when invocation fails due to a CORBA system exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


org.omg.CORBA.portable Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.CORBA.portable

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.CORBA.portable.Delegate
    • java.io.InputStream (implements java.io.Closeable)
      • org.omg.CORBA.portable.InputStream
    • org.omg.CORBA.portable.ObjectImpl (implements org.omg.CORBA.Object)
    • java.io.OutputStream (implements java.io.Closeable, java.io.Flushable)
      • org.omg.CORBA.portable.OutputStream
    • org.omg.CORBA.portable.ServantObject
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.omg.CORBA.portable.ApplicationException
        • org.omg.CORBA.portable.RemarshalException
        • java.lang.RuntimeException
          • org.omg.CORBA.SystemException
            • org.omg.CORBA.portable.IndirectionException
            • org.omg.CORBA.portable.UnknownException

Interface Hierarchy

  • org.omg.CORBA.portable.BoxedValueHelper
  • org.omg.CORBA.CustomMarshal
    • org.omg.CORBA.portable.CustomValue (also extends org.omg.CORBA.portable.ValueBase)
  • org.omg.CORBA.portable.InvokeHandler
  • org.omg.CORBA.portable.ResponseHandler
  • java.io.Serializable
    • org.omg.CORBA.portable.IDLEntity
      • org.omg.CORBA.portable.ValueBase
        • org.omg.CORBA.portable.CustomValue (also extends org.omg.CORBA.CustomMarshal)
        • org.omg.CORBA.portable.StreamableValue (also extends org.omg.CORBA.portable.Streamable)
  • org.omg.CORBA.portable.Streamable
    • org.omg.CORBA.portable.StreamableValue (also extends org.omg.CORBA.portable.ValueBase)
  • org.omg.CORBA.portable.ValueFactory
  • org.omg.CORBA.portable.ValueInputStream
  • org.omg.CORBA.portable.ValueOutputStream
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Streamable

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Interface Streamable

All Known Subinterfaces:
StreamableValue
All Known Implementing Classes:
AlreadyBoundHolder, AnyHolder, AnySeqHolder, BindingHolder, BindingIteratorHolder, BindingListHolder, BindingTypeHolder, BooleanHolder, BooleanSeqHolder, ByteHolder, CannotProceedHolder, CharHolder, CharSeqHolder, CookieHolder, CurrentHolder, DoubleHolder, DoubleSeqHolder, FixedHolder, FloatHolder, FloatSeqHolder, IntHolder, InvalidAddressHolder, InvalidNameHolder, IORHolder, IORInterceptor_3_0Holder, LongHolder, LongLongSeqHolder, LongSeqHolder, MultipleComponentProfileHolder, NameComponentHolder, NameHolder, NamingContextExtHolder, NamingContextHolder, NotEmptyHolder, NotFoundHolder, NotFoundReasonHolder, ObjectHolder, ObjectReferenceFactoryHolder, ObjectReferenceTemplateHolder, ObjectReferenceTemplateSeqHolder, OctetSeqHolder, ParameterModeHolder, PolicyErrorHolder, PolicyHolder, PolicyListHolder, PrincipalHolder, ServiceContextHolder, ServiceContextListHolder, ServiceInformationHolder, ShortHolder, ShortSeqHolder, StringHolder, StringSeqHolder, TaggedComponentHolder, TaggedProfileHolder, TypeCodeHolder, ULongLongSeqHolder, ULongSeqHolder, UnknownUserExceptionHolder, UShortSeqHolder, ValueBaseHolder, WCharSeqHolder, WrongTransactionHolder, WStringSeqHolder
public interface Streamable

The base class for the Holder classess of all complex IDL types. The ORB treats all generated Holders as Streamable to invoke the methods for marshalling and unmarshalling.

Since:
JDK1.2

Method Summary
void | _read(InputStream istream) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream ostream) Marshals to ostream the value in the value field of the Holder.

Method Detail

_read

void _read(InputStream istream)
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Parameters:
istream - the InputStream that represents the CDR data from the wire.

_write

void _write(OutputStream ostream)
Marshals to ostream the value in the value field of the Holder.

Parameters:
ostream - the CDR OutputStream

_type

TypeCode _type()
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StreamableValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Interface StreamableValue

All Superinterfaces:
IDLEntity, Serializable, Streamable, ValueBase
public interface StreamableValue
extends Streamable, ValueBase

Defines the base type for all non-boxed IDL valuetypes that are not custom marshaled. All value types implement ValueBase either directly or indirectly by implementing either the StreamableValue or CustomValue interface.

Method Summary
Methods inherited from interface org.omg.CORBA.portable.Streamable
_read, _type, _write
Methods inherited from interface org.omg.CORBA.portable.ValueBase
_truncatable_ids

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Package org.omg.CORBA.portable

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.CORBA.portable

Packages that use org.omg.CORBA.portable
javax.rmi.CORBA | Contains portability APIs for RMI-IIOP.
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.DynAnyPackage | Provides the exceptions used with the DynAny interface (InvalidValue, Invalid, InvalidSeq, and TypeMismatch).
org.omg.CORBA.ORBPackage | Provides the exception InvalidName, which is thrown by the method ORB.resolve_initial_references and the exception InconsistentTypeCode, which is thrown by the Dynamic Any creation methods in the ORB class.
org.omg.CORBA.TypeCodePackage | Provides the user-defined exceptions BadKind and Bounds, which are thrown by methods in in the class TypeCode.
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.
org.omg.CORBA_2_3 | The CORBA_2_3 package defines additions to existing CORBA interfaces in the Java[tm] Standard Edition 6. These changes occurred in recent revisions to the CORBA API defined by the OMG. The new methods were added to interfaces derived from the corresponding interfaces in the CORBA package. This provides backward compatibility and avoids breaking the JCK tests.
org.omg.CORBA_2_3.portable | Provides methods for the input and output of value types, and contains other updates to the org/omg/CORBA/portable package.
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextExtPackage | This package contains the following classes, which are used in org.omg.CosNaming.NamingContextExt:
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.
org.omg.Dynamic | This package contains the Dynamic module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.9.
org.omg.DynamicAny | Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.
org.omg.DynamicAny.DynAnyFactoryPackage | This package contains classes and exceptions from the DynAnyFactory interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.2.
org.omg.DynamicAny.DynAnyPackage | This package contains classes and exceptions from the DynAny interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.IOP.CodecFactoryPackage | This package contains the exceptions specified in the IOP::CodeFactory interface (as part of the Portable Interceptors spec).
org.omg.IOP.CodecPackage | This package is generated from the IOP::Codec IDL interface definition.
org.omg.Messaging | This package contains the Messaging module specified in the OMG CORBA Messaging specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07.
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.
org.omg.PortableInterceptor.ORBInitInfoPackage | This package contains the exceptions and typedefs from the ORBInitInfo local interface of the PortableInterceptor module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.7.2.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.CurrentPackage | Provides method implementations with access to the identity of the object on which the method was invoked.
org.omg.PortableServer.POAManagerPackage | Encapsulates the processing state of the POAs it is associated with.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.
org.omg.PortableServer.ServantLocatorPackage | Provides classes and interfaces for locating the servant.
org.omg.SendingContext | Provides support for the marshalling of value types.
org.omg.stub.java.rmi | Contains RMI-IIOP Stubs for the Remote types that occur in the java.rmi package.

Classes in org.omg.CORBA.portable used by javax.rmi.CORBA
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
InvokeHandler
This interface provides a dispatching mechanism for an incoming call.
ObjectImpl
The common base class for all stub classes; provides default implementations of the org.omg.CORBA.Object methods.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.

Classes in org.omg.CORBA.portable used by org.omg.CORBA
ApplicationException
This class is used for reporting application level exceptions between ORBs and stubs.
BoxedValueHelper
Delegate
Specifies a portable API for ORB-vendor-specific implementation of the org.omg.CORBA.Object methods.
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
ObjectImpl
The common base class for all stub classes; provides default implementations of the org.omg.CORBA.Object methods.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.
RemarshalException
This class is used for reporting locate forward exceptions and object forward GIOP messages back to the ORB.
ServantObject
This class is part of the local stub API, the purpose of which is to provide high performance calls for collocated clients and servers (i.e.
Streamable
The base class for the Holder classess of all complex IDL types.
ValueBase
The generated Java classes corresponding to valuetype IDL types implement this interface.

Classes in org.omg.CORBA.portable used by org.omg.CORBA.DynAnyPackage
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.

Classes in org.omg.CORBA.portable used by org.omg.CORBA.ORBPackage
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.

Classes in org.omg.CORBA.portable used by org.omg.CORBA.TypeCodePackage
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.

Classes in org.omg.CORBA.portable used by org.omg.CORBA.portable
ApplicationException
This class is used for reporting application level exceptions between ORBs and stubs.
Delegate
Specifies a portable API for ORB-vendor-specific implementation of the org.omg.CORBA.Object methods.
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.
RemarshalException
This class is used for reporting locate forward exceptions and object forward GIOP messages back to the ORB.
ResponseHandler
This interface is supplied by an ORB to a servant at invocation time and allows the servant to later retrieve an OutputStream for returning the invocation results.
ServantObject
This class is part of the local stub API, the purpose of which is to provide high performance calls for collocated clients and servers (i.e.
Streamable
The base class for the Holder classess of all complex IDL types.
ValueBase
The generated Java classes corresponding to valuetype IDL types implement this interface.

Classes in org.omg.CORBA.portable used by org.omg.CORBA_2_3
ValueFactory
The ValueFactory interface is the native mapping for the IDL type CORBA::ValueFactory.

Classes in org.omg.CORBA.portable used by org.omg.CORBA_2_3.portable
BoxedValueHelper
Delegate
Specifies a portable API for ORB-vendor-specific implementation of the org.omg.CORBA.Object methods.
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
ObjectImpl
The common base class for all stub classes; provides default implementations of the org.omg.CORBA.Object methods.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.

Classes in org.omg.CORBA.portable used by org.omg.CosNaming
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
InvokeHandler
This interface provides a dispatching mechanism for an incoming call.
ObjectImpl
The common base class for all stub classes; provides default implementations of the org.omg.CORBA.Object methods.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.
ResponseHandler
This interface is supplied by an ORB to a servant at invocation time and allows the servant to later retrieve an OutputStream for returning the invocation results.
Streamable
The base class for the Holder classess of all complex IDL types.

Classes in org.omg.CORBA.portable used by org.omg.CosNaming.NamingContextExtPackage
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.
Streamable
The base class for the Holder classess of all complex IDL types.

Classes in org.omg.CORBA.portable used by org.omg.CosNaming.NamingContextPackage
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.
Streamable
The base class for the Holder classess of all complex IDL types.

Classes in org.omg.CORBA.portable used by org.omg.Dynamic
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.

Classes in org.omg.CORBA.portable used by org.omg.DynamicAny
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
ObjectImpl
The common base class for all stub classes; provides default implementations of the org.omg.CORBA.Object methods.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.

Classes in org.omg.CORBA.portable used by org.omg.DynamicAny.DynAnyFactoryPackage
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.

Classes in org.omg.CORBA.portable used by org.omg.DynamicAny.DynAnyPackage
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.

Classes in org.omg.CORBA.portable used by org.omg.IOP
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.
Streamable
The base class for the Holder classess of all complex IDL types.

Classes in org.omg.CORBA.portable used by org.omg.IOP.CodecFactoryPackage
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.

Classes in org.omg.CORBA.portable used by org.omg.IOP.CodecPackage
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.

Classes in org.omg.CORBA.portable used by org.omg.Messaging
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.

Classes in org.omg.CORBA.portable used by org.omg.PortableInterceptor
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.
Streamable
The base class for the Holder classess of all complex IDL types.
ValueBase
The generated Java classes corresponding to valuetype IDL types implement this interface.

Classes in org.omg.CORBA.portable used by org.omg.PortableInterceptor.ORBInitInfoPackage
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.

Classes in org.omg.CORBA.portable used by org.omg.PortableServer
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
InvokeHandler
This interface provides a dispatching mechanism for an incoming call.
ObjectImpl
The common base class for all stub classes; provides default implementations of the org.omg.CORBA.Object methods.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.
ResponseHandler
This interface is supplied by an ORB to a servant at invocation time and allows the servant to later retrieve an OutputStream for returning the invocation results.

Classes in org.omg.CORBA.portable used by org.omg.PortableServer.CurrentPackage
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.

Classes in org.omg.CORBA.portable used by org.omg.PortableServer.POAManagerPackage
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.

Classes in org.omg.CORBA.portable used by org.omg.PortableServer.POAPackage
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.

Classes in org.omg.CORBA.portable used by org.omg.PortableServer.ServantLocatorPackage
InputStream
InputStream is the Java API for reading IDL types from CDR marshal streams.
OutputStream
OuputStream is the Java API for writing IDL types to CDR marshal streams.
Streamable
The base class for the Holder classess of all complex IDL types.

Classes in org.omg.CORBA.portable used by org.omg.SendingContext
IDLEntity
An interface with no members whose only purpose is to serve as a marker indicating that an implementing class is a Java value type from IDL that has a corresponding Helper class.

Classes in org.omg.CORBA.portable used by org.omg.stub.java.rmi
ObjectImpl
The common base class for all stub classes; provides default implementations of the org.omg.CORBA.Object methods.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ValueBase

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Interface ValueBase

All Superinterfaces:
IDLEntity, Serializable
All Known Subinterfaces:
CustomValue, DataInputStream, DataOutputStream, ObjectReferenceFactory, ObjectReferenceTemplate, StreamableValue
public interface ValueBase
extends IDLEntity

The generated Java classes corresponding to valuetype IDL types implement this interface. In other words, the Java mapping of valuetype objects implement the ValueBase interface. The generated Java class for valuetype's shall provide an implementation of the ValueBase interface for the corresponding value type. For value types that are streamable (i.e. non-custom), the generated Java class shall also provide an implementation for the org.omg.CORBA.portable.Streamable interface. (CORBA::ValueBase is mapped to java.io.Serializable.)

Method Summary
 String[] _truncatable_ids()
Provides truncatable repository ids.

Method Detail

_truncatable_ids

String[] _truncatable_ids()
Provides truncatable repository ids.

Returns:
a String array--list of truncatable repository ids.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ApplicationException

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Class ApplicationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.portable.ApplicationException
All Implemented Interfaces:
Serializable
public class ApplicationException
extends Exception

This class is used for reporting application level exceptions between ORBs and stubs.

Constructor Summary
ApplicationException(String id, InputStream ins)
Constructs an ApplicationException from the CORBA repository ID of the exception and an input stream from which the exception data can be read as its parameters.
Method Summary
String | getId() Returns the CORBA repository ID of the exception without removing it from the exceptions input stream.
InputStream | getInputStream() Returns the input stream from which the exception data can be read as its parameters.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ApplicationException

public ApplicationException(String id,
                            InputStream ins)
Constructs an ApplicationException from the CORBA repository ID of the exception and an input stream from which the exception data can be read as its parameters.

Parameters:
id - the repository id of the user exception
ins - the stream which contains the user exception data
Method Detail

getId

public String getId()
Returns the CORBA repository ID of the exception without removing it from the exceptions input stream.

Returns:
The CORBA repository ID of this exception

getInputStream

public InputStream getInputStream()
Returns the input stream from which the exception data can be read as its parameters.

Returns:
The stream which contains the user exception data
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


BoxedValueHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Interface BoxedValueHelper

All Known Implementing Classes:
StringValueHelper, WStringValueHelper
public interface BoxedValueHelper

Method Summary
String | get_id()
Serializable | read_value(InputStream is)
void | write_value(OutputStream os, Serializable value)

Method Detail

read_value

Serializable read_value(InputStream is)

write_value

void write_value(OutputStream os,
                 Serializable value)

get_id

String get_id()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class org.omg.CORBA.portable.ApplicationException

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.portable.ApplicationException

Packages that use ApplicationException
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.

Uses of ApplicationException in org.omg.CORBA

Methods in org.omg.CORBA that throw ApplicationException
 InputStream LocalObject._invoke(OutputStream output)
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.

Uses of ApplicationException in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable that throw ApplicationException
InputStream | ObjectImpl._invoke(OutputStream output) Invokes an operation and returns an InputStream object for reading the response.
InputStream | Delegate.invoke(Object self, OutputStream output) invoke is called by a stub to invoke an operation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.portable.Delegate

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.portable.Delegate

Packages that use Delegate
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA_2_3.portable | Provides methods for the input and output of value types, and contains other updates to the org/omg/CORBA/portable package.
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.

Uses of Delegate in org.omg.CORBA

Constructors in org.omg.CORBA with parameters of type Delegate
_IDLTypeStub(Delegate delegate)
Constructs an _IDLTypeStub object initialized with the given Delegate object.
_PolicyStub(Delegate delegate)
Constructs a _PolicyStub object initialized with the given Delegate object.

Uses of Delegate in org.omg.CORBA_2_3.portable

Subclasses of Delegate in org.omg.CORBA_2_3.portable
 class Delegate
Delegate class provides the ORB vendor specific implementation of CORBA object.

Uses of Delegate in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable that return Delegate
 Delegate ObjectImpl._get_delegate()
Retrieves the reference to the vendor-specific Delegate object to which this ObjectImpl object delegates all methods invoked on it.

Methods in org.omg.CORBA.portable with parameters of type Delegate
 void ObjectImpl._set_delegate(Delegate delegate)
Sets the Delegate for this ObjectImpl instance to the given Delegate object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.portable.IndirectionException

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.portable.IndirectionException

No usage of org.omg.CORBA.portable.IndirectionException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.portable.InputStream

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.portable.InputStream

Packages that use InputStream
javax.rmi.CORBA | Contains portability APIs for RMI-IIOP.
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA_2_3.portable | Provides methods for the input and output of value types, and contains other updates to the org/omg/CORBA/portable package.
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextExtPackage | This package contains the following classes, which are used in org.omg.CosNaming.NamingContextExt:
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.
org.omg.DynamicAny | Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.
org.omg.DynamicAny.DynAnyFactoryPackage | This package contains classes and exceptions from the DynAnyFactory interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.2.
org.omg.DynamicAny.DynAnyPackage | This package contains classes and exceptions from the DynAny interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.IOP.CodecFactoryPackage | This package contains the exceptions specified in the IOP::CodeFactory interface (as part of the Portable Interceptors spec).
org.omg.IOP.CodecPackage | This package is generated from the IOP::Codec IDL interface definition.
org.omg.Messaging | This package contains the Messaging module specified in the OMG CORBA Messaging specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07.
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.
org.omg.PortableInterceptor.ORBInitInfoPackage | This package contains the exceptions and typedefs from the ORBInitInfo local interface of the PortableInterceptor module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.7.2.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.CurrentPackage | Provides method implementations with access to the identity of the object on which the method was invoked.
org.omg.PortableServer.POAManagerPackage | Encapsulates the processing state of the POAs it is associated with.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.
org.omg.PortableServer.ServantLocatorPackage | Provides classes and interfaces for locating the servant.

Uses of InputStream in javax.rmi.CORBA

Methods in javax.rmi.CORBA with parameters of type InputStream
 Object UtilDelegate.readAny(InputStream in)
Delegation call for Util.readAny(org.omg.CORBA.portable.InputStream).
static Object Util.readAny(InputStream in)
Reads a java.lang.Object as a CORBA any.
 Serializable ValueHandler.readValue(InputStream in, int offset, Class clz, String repositoryID, RunTime sender)
Reads a value from the stream using Java semantics.

Uses of InputStream in org.omg.CORBA

Methods in org.omg.CORBA that return InputStream
InputStream | LocalObject._invoke(OutputStream output) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
abstract InputStream | Any.create_input_stream() Creates an input stream from which this Any object's value can be unmarshalled.

Methods in org.omg.CORBA with parameters of type InputStream
void | WrongTransactionHolder._read(InputStream i)
void | WStringSeqHolder._read(InputStream i)
void | UnknownUserExceptionHolder._read(InputStream i)
void | StringSeqHolder._read(InputStream i)
void | PolicyErrorHolder._read(InputStream i)
void | ParameterModeHolder._read(InputStream i)
void | ValueBaseHolder._read(InputStream input) Reads from input and initalizes the value in the Holder with the unmarshalled data.
void | PolicyListHolder._read(InputStream i)
void | PolicyHolder._read(InputStream i)
void | DoubleSeqHolder._read(InputStream i)
void | FloatSeqHolder._read(InputStream i)
void | LongLongSeqHolder._read(InputStream i)
void | ULongLongSeqHolder._read(InputStream i)
void | ULongSeqHolder._read(InputStream i)
void | LongSeqHolder._read(InputStream i)
void | UShortSeqHolder._read(InputStream i)
void | ShortSeqHolder._read(InputStream i)
void | OctetSeqHolder._read(InputStream i)
void | WCharSeqHolder._read(InputStream i)
void | CurrentHolder._read(InputStream i)
void | CharSeqHolder._read(InputStream i)
void | BooleanSeqHolder._read(InputStream i)
void | AnySeqHolder._read(InputStream i)
void | TypeCodeHolder._read(InputStream input) Reads from input and initalizes the value in this TypeCodeHolder object with the unmarshalled data.
void | StringHolder._read(InputStream input) Reads the unmarshalled data from input and assigns it to the value field of this StringHolder object.
void | ShortHolder._read(InputStream input) Reads from input and initalizes the value in this ShortHolder object with the unmarshalled data.
void | PrincipalHolder._read(InputStream input) Deprecated.
void | ObjectHolder._read(InputStream input) Reads from input and initalizes the value in this ObjectHolder object with the unmarshalled data.
void | LongHolder._read(InputStream input) Reads from input and initalizes the value in the Holder with the unmarshalled data.
void | IntHolder._read(InputStream input) Reads unmarshalled data from input and assigns it to the value field in this IntHolder object.
void | FloatHolder._read(InputStream input) Read a float from an input stream and initialize the value member with the float value.
void | FixedHolder._read(InputStream input) Read a fixed point value from the input stream and store it in the value member.
void | DoubleHolder._read(InputStream input) Read a double value from the input stream and store it in the value member.
void | CharHolder._read(InputStream input) Reads from input and initalizes the value in this CharHolder object with the unmarshalled data.
void | ByteHolder._read(InputStream input) Reads from input and initalizes the value in this ByteHolder object with the unmarshalled data.
void | BooleanHolder._read(InputStream input) Reads unmarshalled data from input and assigns it to this BooleanHolder object's value field.
void | AnyHolder._read(InputStream input) Reads from input and initalizes the value in the Holder with the unmarshalled data.
void | ServiceInformationHolder._read(InputStream in) Reads unmarshalled data from the input stream in and assigns it to the value field in this ServiceInformationHolder object.
void | LocalObject._releaseReply(InputStream input) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
Serializable | WStringValueHelper.read_value(InputStream istream)
Serializable | StringValueHelper.read_value(InputStream istream)
abstract void | Any.read_value(InputStream is, TypeCode t) Reads off (unmarshals) the value of an Any object from the given input stream using the given typecode.
static String[] | WStringSeqHelper.read(InputStream istream)
static UnknownUserException | UnknownUserExceptionHelper.read(InputStream istream)
static String[] | StringSeqHelper.read(InputStream istream)
static PolicyError | PolicyErrorHelper.read(InputStream istream)
static short | PolicyErrorCodeHelper.read(InputStream istream)
static ParameterMode | ParameterModeHelper.read(InputStream istream)
static String | WStringValueHelper.read(InputStream istream)
static char[] | WCharSeqHelper.read(InputStream istream)
static short | VisibilityHelper.read(InputStream istream)
static String | VersionSpecHelper.read(InputStream istream)
static ValueMember | ValueMemberHelper.read(InputStream istream)
static Serializable | ValueBaseHelper.read(InputStream istream)
static UnionMember | UnionMemberHelper.read(InputStream istream)
static short[] | UShortSeqHelper.read(InputStream istream)
static int[] | ULongSeqHelper.read(InputStream istream)
static long[] | ULongLongSeqHelper.read(InputStream istream)
static StructMember | StructMemberHelper.read(InputStream istream)
static String | StringValueHelper.read(InputStream istream)
static short[] | ShortSeqHelper.read(InputStream istream)
static SetOverrideType | SetOverrideTypeHelper.read(InputStream istream)
static String | RepositoryIdHelper.read(InputStream istream)
static Policy[] | PolicyListHelper.read(InputStream istream)
static int | PolicyTypeHelper.read(InputStream istream)
static Policy | PolicyHelper.read(InputStream istream)
static byte[] | OctetSeqHelper.read(InputStream istream)
static NameValuePair | NameValuePairHelper.read(InputStream istream)
static int[] | LongSeqHelper.read(InputStream istream)
static long[] | LongLongSeqHelper.read(InputStream istream)
static String | IdentifierHelper.read(InputStream istream)
static IDLType | IDLTypeHelper.read(InputStream istream)
static float[] | FloatSeqHelper.read(InputStream istream)
static String | FieldNameHelper.read(InputStream istream)
static double[] | DoubleSeqHelper.read(InputStream istream)
static DefinitionKind | DefinitionKindHelper.read(InputStream istream)
static Current | CurrentHelper.read(InputStream istream)
static CompletionStatus | CompletionStatusHelper.read(InputStream istream)
static char[] | CharSeqHelper.read(InputStream istream)
static boolean[] | BooleanSeqHelper.read(InputStream istream)
static Any[] | AnySeqHelper.read(InputStream istream)
static Object | ObjectHelper.read(InputStream istream)
static ServiceDetail | ServiceDetailHelper.read(InputStream in)
static ServiceInformation | ServiceInformationHelper.read(InputStream in)
static WrongTransaction | WrongTransactionHelper.read(InputStream istream)

Uses of InputStream in org.omg.CORBA_2_3.portable

Subclasses of InputStream in org.omg.CORBA_2_3.portable
 class InputStream
InputStream provides for the reading of all of the mapped IDL types from the stream.

Uses of InputStream in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable that return InputStream
InputStream | ObjectImpl._invoke(OutputStream output) Invokes an operation and returns an InputStream object for reading the response.
abstract InputStream | OutputStream.create_input_stream() Returns an input stream with the same buffer.
InputStream | ApplicationException.getInputStream() Returns the input stream from which the exception data can be read as its parameters.
InputStream | Delegate.invoke(Object self, OutputStream output) invoke is called by a stub to invoke an operation.

Methods in org.omg.CORBA.portable with parameters of type InputStream
OutputStream | InvokeHandler._invoke(String method, InputStream input, ResponseHandler handler) Invoked by the ORB to dispatch a request to the servant.
void | Streamable._read(InputStream istream) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
void | ObjectImpl._releaseReply(InputStream input) Releases the given reply stream back to the ORB when unmarshalling has completed after a call to the method _invoke.
Serializable | BoxedValueHelper.read_value(InputStream is)
void | Delegate.releaseReply(Object self, InputStream input) releaseReply may optionally be called by a stub to release a reply stream back to the ORB when the unmarshaling has completed.

Constructors in org.omg.CORBA.portable with parameters of type InputStream
ApplicationException(String id, InputStream ins)
Constructs an ApplicationException from the CORBA repository ID of the exception and an input stream from which the exception data can be read as its parameters.

Uses of InputStream in org.omg.CosNaming

Methods in org.omg.CosNaming with parameters of type InputStream
OutputStream | NamingContextExtPOA._invoke(String $method, InputStream in, ResponseHandler $rh)
OutputStream | NamingContextPOA._invoke(String $method, InputStream in, ResponseHandler $rh)
OutputStream | BindingIteratorPOA._invoke(String $method, InputStream in, ResponseHandler $rh)
void | NamingContextExtHolder._read(InputStream i)
void | NamingContextHolder._read(InputStream i)
void | NameHolder._read(InputStream i)
void | NameComponentHolder._read(InputStream i)
void | BindingTypeHolder._read(InputStream i)
void | BindingIteratorHolder._read(InputStream i)
void | BindingListHolder._read(InputStream i)
void | BindingHolder._read(InputStream i)
static NamingContextExt | NamingContextExtHelper.read(InputStream istream)
static NamingContext | NamingContextHelper.read(InputStream istream)
static NameComponent[] | NameHelper.read(InputStream istream)
static NameComponent | NameComponentHelper.read(InputStream istream)
static BindingType | BindingTypeHelper.read(InputStream istream)
static Binding[] | BindingListHelper.read(InputStream istream)
static BindingIterator | BindingIteratorHelper.read(InputStream istream)
static Binding | BindingHelper.read(InputStream istream)
static String | IstringHelper.read(InputStream istream)

Uses of InputStream in org.omg.CosNaming.NamingContextExtPackage

Methods in org.omg.CosNaming.NamingContextExtPackage with parameters of type InputStream
void | InvalidAddressHolder._read(InputStream i)
static String | URLStringHelper.read(InputStream istream)
static String | StringNameHelper.read(InputStream istream)
static InvalidAddress | InvalidAddressHelper.read(InputStream istream)
static String | AddressHelper.read(InputStream istream)

Uses of InputStream in org.omg.CosNaming.NamingContextPackage

Methods in org.omg.CosNaming.NamingContextPackage with parameters of type InputStream
void | NotFoundReasonHolder._read(InputStream i)
void | NotFoundHolder._read(InputStream i)
void | NotEmptyHolder._read(InputStream i)
void | InvalidNameHolder._read(InputStream i)
void | CannotProceedHolder._read(InputStream i)
void | AlreadyBoundHolder._read(InputStream i)
static NotFoundReason | NotFoundReasonHelper.read(InputStream istream)
static NotFound | NotFoundHelper.read(InputStream istream)
static NotEmpty | NotEmptyHelper.read(InputStream istream)
static InvalidName | InvalidNameHelper.read(InputStream istream)
static CannotProceed | CannotProceedHelper.read(InputStream istream)
static AlreadyBound | AlreadyBoundHelper.read(InputStream istream)

Uses of InputStream in org.omg.DynamicAny

Methods in org.omg.DynamicAny with parameters of type InputStream
static NameValuePair[] | NameValuePairSeqHelper.read(InputStream istream)
static NameValuePair | NameValuePairHelper.read(InputStream istream)
static NameDynAnyPair[] | NameDynAnyPairSeqHelper.read(InputStream istream)
static DynSequence | DynSequenceHelper.read(InputStream istream)
static NameDynAnyPair | NameDynAnyPairHelper.read(InputStream istream)
static String | FieldNameHelper.read(InputStream istream)
static DynFixed | DynFixedHelper.read(InputStream istream)
static DynEnum | DynEnumHelper.read(InputStream istream)
static DynAny[] | DynAnySeqHelper.read(InputStream istream)
static DynArray | DynArrayHelper.read(InputStream istream)
static DynValue | DynValueHelper.read(InputStream istream)
static DynAny | DynAnyHelper.read(InputStream istream)
static DynUnion | DynUnionHelper.read(InputStream istream)
static DynAnyFactory | DynAnyFactoryHelper.read(InputStream istream)
static DynStruct | DynStructHelper.read(InputStream istream)
static Any[] | AnySeqHelper.read(InputStream istream)

Uses of InputStream in org.omg.DynamicAny.DynAnyFactoryPackage

Methods in org.omg.DynamicAny.DynAnyFactoryPackage with parameters of type InputStream
static InconsistentTypeCode InconsistentTypeCodeHelper.read(InputStream istream)

Uses of InputStream in org.omg.DynamicAny.DynAnyPackage

Methods in org.omg.DynamicAny.DynAnyPackage with parameters of type InputStream
static TypeMismatch | TypeMismatchHelper.read(InputStream istream)
static InvalidValue | InvalidValueHelper.read(InputStream istream)

Uses of InputStream in org.omg.IOP

Methods in org.omg.IOP with parameters of type InputStream
void | TaggedProfileHolder._read(InputStream i)
void | TaggedComponentHolder._read(InputStream i)
void | ServiceContextListHolder._read(InputStream i)
void | ServiceContextHolder._read(InputStream i)
void | MultipleComponentProfileHolder._read(InputStream i)
void | IORHolder._read(InputStream i)
static TaggedProfile | TaggedProfileHelper.read(InputStream istream)
static TaggedComponent | TaggedComponentHelper.read(InputStream istream)
static int | ServiceIdHelper.read(InputStream istream)
static ServiceContext[] | ServiceContextListHelper.read(InputStream istream)
static ServiceContext | ServiceContextHelper.read(InputStream istream)
static int | ProfileIdHelper.read(InputStream istream)
static TaggedComponent[] | MultipleComponentProfileHelper.read(InputStream istream)
static IOR | IORHelper.read(InputStream istream)
static int | ComponentIdHelper.read(InputStream istream)
static CodecFactory | CodecFactoryHelper.read(InputStream istream)

Uses of InputStream in org.omg.IOP.CodecFactoryPackage

Methods in org.omg.IOP.CodecFactoryPackage with parameters of type InputStream
static UnknownEncoding UnknownEncodingHelper.read(InputStream istream)

Uses of InputStream in org.omg.IOP.CodecPackage

Methods in org.omg.IOP.CodecPackage with parameters of type InputStream
static TypeMismatch | TypeMismatchHelper.read(InputStream istream)
static InvalidTypeForEncoding | InvalidTypeForEncodingHelper.read(InputStream istream)
static FormatMismatch | FormatMismatchHelper.read(InputStream istream)

Uses of InputStream in org.omg.Messaging

Methods in org.omg.Messaging with parameters of type InputStream
static short SyncScopeHelper.read(InputStream istream)

Uses of InputStream in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor with parameters of type InputStream
void | ObjectReferenceTemplateSeqHolder._read(InputStream i)
void | ObjectReferenceTemplateHolder._read(InputStream i)
void | ObjectReferenceFactoryHolder._read(InputStream i)
void | IORInterceptor_3_0Holder._read(InputStream i)
static String | ServerIdHelper.read(InputStream istream)
static String | ORBIdHelper.read(InputStream istream)
static ObjectReferenceTemplate[] | ObjectReferenceTemplateSeqHelper.read(InputStream istream)
static ObjectReferenceTemplate | ObjectReferenceTemplateHelper.read(InputStream istream)
static ObjectReferenceFactory | ObjectReferenceFactoryHelper.read(InputStream istream)
static byte[] | ObjectIdHelper.read(InputStream istream)
static InvalidSlot | InvalidSlotHelper.read(InputStream istream)
static IORInterceptor_3_0 | IORInterceptor_3_0Helper.read(InputStream istream)
static ForwardRequest | ForwardRequestHelper.read(InputStream istream)
static Current | CurrentHelper.read(InputStream istream)
static short | AdapterStateHelper.read(InputStream istream)
static String[] | AdapterNameHelper.read(InputStream istream)
static int | AdapterManagerIdHelper.read(InputStream istream)

Uses of InputStream in org.omg.PortableInterceptor.ORBInitInfoPackage

Methods in org.omg.PortableInterceptor.ORBInitInfoPackage with parameters of type InputStream
static String | ObjectIdHelper.read(InputStream istream)
static InvalidName | InvalidNameHelper.read(InputStream istream)
static DuplicateName | DuplicateNameHelper.read(InputStream istream)

Uses of InputStream in org.omg.PortableServer

Methods in org.omg.PortableServer with parameters of type InputStream
OutputStream | ServantLocatorPOA._invoke(String $method, InputStream in, ResponseHandler $rh)
OutputStream | ServantActivatorPOA._invoke(String $method, InputStream in, ResponseHandler $rh)
static ServantLocator | ServantLocatorHelper.read(InputStream istream)
static ServantActivator | ServantActivatorHelper.read(InputStream istream)
static POA | POAHelper.read(InputStream istream)
static ForwardRequest | ForwardRequestHelper.read(InputStream istream)
static Current | CurrentHelper.read(InputStream istream)

Uses of InputStream in org.omg.PortableServer.CurrentPackage

Methods in org.omg.PortableServer.CurrentPackage with parameters of type InputStream
static NoContext NoContextHelper.read(InputStream istream)

Uses of InputStream in org.omg.PortableServer.POAManagerPackage

Methods in org.omg.PortableServer.POAManagerPackage with parameters of type InputStream
static AdapterInactive AdapterInactiveHelper.read(InputStream istream)

Uses of InputStream in org.omg.PortableServer.POAPackage

Methods in org.omg.PortableServer.POAPackage with parameters of type InputStream
static WrongPolicy | WrongPolicyHelper.read(InputStream istream)
static WrongAdapter | WrongAdapterHelper.read(InputStream istream)
static ServantNotActive | ServantNotActiveHelper.read(InputStream istream)
static ServantAlreadyActive | ServantAlreadyActiveHelper.read(InputStream istream)
static ObjectNotActive | ObjectNotActiveHelper.read(InputStream istream)
static ObjectAlreadyActive | ObjectAlreadyActiveHelper.read(InputStream istream)
static NoServant | NoServantHelper.read(InputStream istream)
static InvalidPolicy | InvalidPolicyHelper.read(InputStream istream)
static AdapterNonExistent | AdapterNonExistentHelper.read(InputStream istream)
static AdapterAlreadyExists | AdapterAlreadyExistsHelper.read(InputStream istream)

Uses of InputStream in org.omg.PortableServer.ServantLocatorPackage

Methods in org.omg.PortableServer.ServantLocatorPackage with parameters of type InputStream
 void CookieHolder._read(InputStream is)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.portable.ObjectImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.portable.ObjectImpl

Packages that use ObjectImpl
javax.rmi.CORBA | Contains portability APIs for RMI-IIOP.
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA_2_3.portable | Provides methods for the input and output of value types, and contains other updates to the org/omg/CORBA/portable package.
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.DynamicAny | Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.stub.java.rmi | Contains RMI-IIOP Stubs for the Remote types that occur in the java.rmi package.

Uses of ObjectImpl in javax.rmi.CORBA

Subclasses of ObjectImpl in javax.rmi.CORBA
 class Stub
Base class from which all RMI-IIOP stubs must inherit.

Uses of ObjectImpl in org.omg.CORBA

Subclasses of ObjectImpl in org.omg.CORBA
class | _IDLTypeStub The Stub for IDLType.
class | _PolicyStub The Stub for Policy.
class | DynamicImplementation Deprecated. org.omg.CORBA.DynamicImplementation

Uses of ObjectImpl in org.omg.CORBA_2_3.portable

Subclasses of ObjectImpl in org.omg.CORBA_2_3.portable
 class ObjectImpl
ObjectImpl class is the base class for all stubs.

Uses of ObjectImpl in org.omg.CosNaming

Subclasses of ObjectImpl in org.omg.CosNaming
class | _BindingIteratorImplBase
class | _BindingIteratorStub The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
class | _NamingContextExtStub NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
class | _NamingContextImplBase
class | _NamingContextStub A naming context is an object that contains a set of name bindings in which each name is unique.

Uses of ObjectImpl in org.omg.DynamicAny

Subclasses of ObjectImpl in org.omg.DynamicAny
class | _DynAnyFactoryStub DynAny objects can be created by invoking operations on the DynAnyFactory object.
class | _DynAnyStub Any values can be dynamically interpreted (traversed) and constructed through DynAny objects.
class | _DynArrayStub DynArray objects support the manipulation of IDL arrays.
class | _DynEnumStub DynEnum objects support the manipulation of IDL enumerated values.
class | _DynFixedStub DynFixed objects support the manipulation of IDL fixed values.
class | _DynSequenceStub DynSequence objects support the manipulation of IDL sequences.
class | _DynStructStub DynStruct objects support the manipulation of IDL struct and exception values.
class | _DynUnionStub DynUnion objects support the manipulation of IDL unions.
class | _DynValueStub DynValue objects support the manipulation of IDL non-boxed value types.

Uses of ObjectImpl in org.omg.PortableServer

Subclasses of ObjectImpl in org.omg.PortableServer
class | _ServantActivatorStub When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
class | _ServantLocatorStub When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.

Uses of ObjectImpl in org.omg.stub.java.rmi

Subclasses of ObjectImpl in org.omg.stub.java.rmi
 class _Remote_Stub
This class provides the Stub for the Remote Type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.portable.OutputStream

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.portable.OutputStream

Packages that use OutputStream
javax.rmi.CORBA | Contains portability APIs for RMI-IIOP.
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA_2_3.portable | Provides methods for the input and output of value types, and contains other updates to the org/omg/CORBA/portable package.
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextExtPackage | This package contains the following classes, which are used in org.omg.CosNaming.NamingContextExt:
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.
org.omg.DynamicAny | Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.
org.omg.DynamicAny.DynAnyFactoryPackage | This package contains classes and exceptions from the DynAnyFactory interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.2.
org.omg.DynamicAny.DynAnyPackage | This package contains classes and exceptions from the DynAny interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.IOP.CodecFactoryPackage | This package contains the exceptions specified in the IOP::CodeFactory interface (as part of the Portable Interceptors spec).
org.omg.IOP.CodecPackage | This package is generated from the IOP::Codec IDL interface definition.
org.omg.Messaging | This package contains the Messaging module specified in the OMG CORBA Messaging specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07.
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.
org.omg.PortableInterceptor.ORBInitInfoPackage | This package contains the exceptions and typedefs from the ORBInitInfo local interface of the PortableInterceptor module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.7.2.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.CurrentPackage | Provides method implementations with access to the identity of the object on which the method was invoked.
org.omg.PortableServer.POAManagerPackage | Encapsulates the processing state of the POAs it is associated with.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.
org.omg.PortableServer.ServantLocatorPackage | Provides classes and interfaces for locating the servant.

Uses of OutputStream in javax.rmi.CORBA

Methods in javax.rmi.CORBA with parameters of type OutputStream
 void UtilDelegate.writeAbstractObject(OutputStream out, Object obj)
Delegation call for Util.writeAbstractObject(org.omg.CORBA.portable.OutputStream, java.lang.Object).
static void Util.writeAbstractObject(OutputStream out, Object obj)
Writes a java.lang.Object as either a value or a CORBA Object.
 void UtilDelegate.writeAny(OutputStream out, Object obj)
Delegation call for Util.writeAny(org.omg.CORBA.portable.OutputStream, java.lang.Object).
static void Util.writeAny(OutputStream out, Object obj)
Writes any java.lang.Object as a CORBA any.
 void UtilDelegate.writeRemoteObject(OutputStream out, Object obj)
Delegation call for Util.writeRemoteObject(org.omg.CORBA.portable.OutputStream, java.lang.Object).
static void Util.writeRemoteObject(OutputStream out, Object obj)
Writes a java.lang.Object as a CORBA Object.
 void ValueHandler.writeValue(OutputStream out, Serializable value)
Writes a value to the stream using Java semantics.
 void ValueHandlerMultiFormat.writeValue(OutputStream out, Serializable value, byte streamFormatVersion)
Allows the ORB to pass the stream format version for RMI/IDL custom value types.

Uses of OutputStream in org.omg.CORBA

Methods in org.omg.CORBA that return OutputStream
OutputStream | LocalObject._request(String operation, boolean responseExpected) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
abstract OutputStream | Any.create_output_stream() Creates an output stream into which this Any object's value can be marshalled.
abstract OutputStream | ORB.create_output_stream() Creates a new org.omg.CORBA.portable.OutputStream into which IDL method parameters can be marshalled during method invocation.

Methods in org.omg.CORBA with parameters of type OutputStream
InputStream | LocalObject._invoke(OutputStream output) Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.
void | WrongTransactionHolder._write(OutputStream o)
void | WStringSeqHolder._write(OutputStream o)
void | UnknownUserExceptionHolder._write(OutputStream o)
void | StringSeqHolder._write(OutputStream o)
void | PolicyErrorHolder._write(OutputStream o)
void | ParameterModeHolder._write(OutputStream o)
void | ValueBaseHolder._write(OutputStream output) Marshals to output the value in the Holder.
void | PolicyListHolder._write(OutputStream o)
void | PolicyHolder._write(OutputStream o)
void | DoubleSeqHolder._write(OutputStream o)
void | FloatSeqHolder._write(OutputStream o)
void | LongLongSeqHolder._write(OutputStream o)
void | ULongLongSeqHolder._write(OutputStream o)
void | ULongSeqHolder._write(OutputStream o)
void | LongSeqHolder._write(OutputStream o)
void | UShortSeqHolder._write(OutputStream o)
void | ShortSeqHolder._write(OutputStream o)
void | OctetSeqHolder._write(OutputStream o)
void | WCharSeqHolder._write(OutputStream o)
void | CurrentHolder._write(OutputStream o)
void | CharSeqHolder._write(OutputStream o)
void | BooleanSeqHolder._write(OutputStream o)
void | AnySeqHolder._write(OutputStream o)
void | TypeCodeHolder._write(OutputStream output) Marshals to output the value in this TypeCodeHolder object.
void | StringHolder._write(OutputStream output) Marshals the value held by this StringHolder object to the output stream output.
void | ShortHolder._write(OutputStream output) Marshals to output the value in this ShortHolder object.
void | PrincipalHolder._write(OutputStream output) Deprecated.
void | ObjectHolder._write(OutputStream output) Marshals to output the value in this ObjectHolder object.
void | LongHolder._write(OutputStream output) Marshals to output the value in the Holder.
void | IntHolder._write(OutputStream output) Marshals the value in this IntHolder object's value field to the output stream output.
void | FloatHolder._write(OutputStream output) Write the float value into an output stream.
void | FixedHolder._write(OutputStream output) Write the fixed point value stored in this holder to an OutputStream.
void | DoubleHolder._write(OutputStream output) Write the double value stored in this holder to an OutputStream.
void | CharHolder._write(OutputStream output) Marshals to output the value in this CharHolder object.
void | ByteHolder._write(OutputStream output) Marshals to output the value in this ByteHolder object.
void | BooleanHolder._write(OutputStream output) Marshals the value in this BooleanHolder object's value field to the output stream output.
void | AnyHolder._write(OutputStream output) Marshals to output the value in this AnyHolder object.
void | ServiceInformationHolder._write(OutputStream out) Marshals the value in this ServiceInformationHolder object's value field to the output stream out.
abstract void | Any.write_value(OutputStream os) Writes out the value of this Any object to the given output stream.
void | WStringValueHelper.write_value(OutputStream ostream, Serializable value)
void | StringValueHelper.write_value(OutputStream ostream, Serializable value)
static void | AnySeqHelper.write(OutputStream ostream, Any[] value)
static void | BooleanSeqHelper.write(OutputStream ostream, boolean[] value)
static void | OctetSeqHelper.write(OutputStream ostream, byte[] value)
static void | WCharSeqHelper.write(OutputStream ostream, char[] value)
static void | CharSeqHelper.write(OutputStream ostream, char[] value)
static void | CompletionStatusHelper.write(OutputStream ostream, CompletionStatus value)
static void | CurrentHelper.write(OutputStream ostream, Current value)
static void | DefinitionKindHelper.write(OutputStream ostream, DefinitionKind value)
static void | DoubleSeqHelper.write(OutputStream ostream, double[] value)
static void | FloatSeqHelper.write(OutputStream ostream, float[] value)
static void | IDLTypeHelper.write(OutputStream ostream, IDLType value)
static void | PolicyTypeHelper.write(OutputStream ostream, int value)
static void | ULongSeqHelper.write(OutputStream ostream, int[] value)
static void | LongSeqHelper.write(OutputStream ostream, int[] value)
static void | ULongLongSeqHelper.write(OutputStream ostream, long[] value)
static void | LongLongSeqHelper.write(OutputStream ostream, long[] value)
static void | NameValuePairHelper.write(OutputStream ostream, NameValuePair value)
static void | ObjectHelper.write(OutputStream ostream, Object value)
static void | ParameterModeHelper.write(OutputStream ostream, ParameterMode value)
static void | PolicyHelper.write(OutputStream ostream, Policy value)
static void | PolicyListHelper.write(OutputStream ostream, Policy[] value)
static void | PolicyErrorHelper.write(OutputStream ostream, PolicyError value)
static void | ValueBaseHelper.write(OutputStream ostream, Serializable value)
static void | ServiceDetailHelper.write(OutputStream out, ServiceDetail that)
static void | ServiceInformationHelper.write(OutputStream out, ServiceInformation that)
static void | SetOverrideTypeHelper.write(OutputStream ostream, SetOverrideType value)
static void | PolicyErrorCodeHelper.write(OutputStream ostream, short value)
static void | VisibilityHelper.write(OutputStream ostream, short value)
static void | UShortSeqHelper.write(OutputStream ostream, short[] value)
static void | ShortSeqHelper.write(OutputStream ostream, short[] value)
static void | WStringValueHelper.write(OutputStream ostream, String value)
static void | VersionSpecHelper.write(OutputStream ostream, String value)
static void | StringValueHelper.write(OutputStream ostream, String value)
static void | RepositoryIdHelper.write(OutputStream ostream, String value)
static void | IdentifierHelper.write(OutputStream ostream, String value)
static void | FieldNameHelper.write(OutputStream ostream, String value)
static void | WStringSeqHelper.write(OutputStream ostream, String[] value)
static void | StringSeqHelper.write(OutputStream ostream, String[] value)
static void | StructMemberHelper.write(OutputStream ostream, StructMember value)
static void | UnionMemberHelper.write(OutputStream ostream, UnionMember value)
static void | UnknownUserExceptionHelper.write(OutputStream ostream, UnknownUserException value)
static void | ValueMemberHelper.write(OutputStream ostream, ValueMember value)
static void | WrongTransactionHelper.write(OutputStream ostream, WrongTransaction value)

Uses of OutputStream in org.omg.CORBA_2_3.portable

Subclasses of OutputStream in org.omg.CORBA_2_3.portable
 class OutputStream
OutputStream provides interface for writing of all of the mapped IDL type to the stream.

Uses of OutputStream in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable that return OutputStream
OutputStream | InvokeHandler._invoke(String method, InputStream input, ResponseHandler handler) Invoked by the ORB to dispatch a request to the servant.
OutputStream | ObjectImpl._request(String operation, boolean responseExpected) Returns an OutputStream object to use for marshalling the arguments of the given method.
OutputStream | ResponseHandler.createExceptionReply() Called by the servant during a method invocation.
OutputStream | ResponseHandler.createReply() Called by the servant during a method invocation.
OutputStream | Delegate.request(Object self, String operation, boolean responseExpected) request is called by a stub to obtain an OutputStream for marshaling arguments.

Methods in org.omg.CORBA.portable with parameters of type OutputStream
InputStream | ObjectImpl._invoke(OutputStream output) Invokes an operation and returns an InputStream object for reading the response.
void | Streamable._write(OutputStream ostream) Marshals to ostream the value in the value field of the Holder.
InputStream | Delegate.invoke(Object self, OutputStream output) invoke is called by a stub to invoke an operation.
void | BoxedValueHelper.write_value(OutputStream os, Serializable value)

Uses of OutputStream in org.omg.CosNaming

Methods in org.omg.CosNaming that return OutputStream
OutputStream | NamingContextExtPOA._invoke(String $method, InputStream in, ResponseHandler $rh)
OutputStream | NamingContextPOA._invoke(String $method, InputStream in, ResponseHandler $rh)
OutputStream | BindingIteratorPOA._invoke(String $method, InputStream in, ResponseHandler $rh)

Methods in org.omg.CosNaming with parameters of type OutputStream
void | NamingContextExtHolder._write(OutputStream o)
void | NamingContextHolder._write(OutputStream o)
void | NameHolder._write(OutputStream o)
void | NameComponentHolder._write(OutputStream o)
void | BindingTypeHolder._write(OutputStream o)
void | BindingIteratorHolder._write(OutputStream o)
void | BindingListHolder._write(OutputStream o)
void | BindingHolder._write(OutputStream o)
static void | BindingHelper.write(OutputStream ostream, Binding value)
static void | BindingListHelper.write(OutputStream ostream, Binding[] value)
static void | BindingIteratorHelper.write(OutputStream ostream, BindingIterator value)
static void | BindingTypeHelper.write(OutputStream ostream, BindingType value)
static void | NameComponentHelper.write(OutputStream ostream, NameComponent value)
static void | NameHelper.write(OutputStream ostream, NameComponent[] value)
static void | NamingContextHelper.write(OutputStream ostream, NamingContext value)
static void | NamingContextExtHelper.write(OutputStream ostream, NamingContextExt value)
static void | IstringHelper.write(OutputStream ostream, String value)

Uses of OutputStream in org.omg.CosNaming.NamingContextExtPackage

Methods in org.omg.CosNaming.NamingContextExtPackage with parameters of type OutputStream
void | InvalidAddressHolder._write(OutputStream o)
static void | InvalidAddressHelper.write(OutputStream ostream, InvalidAddress value)
static void | URLStringHelper.write(OutputStream ostream, String value)
static void | StringNameHelper.write(OutputStream ostream, String value)
static void | AddressHelper.write(OutputStream ostream, String value)

Uses of OutputStream in org.omg.CosNaming.NamingContextPackage

Methods in org.omg.CosNaming.NamingContextPackage with parameters of type OutputStream
void | NotFoundReasonHolder._write(OutputStream o)
void | NotFoundHolder._write(OutputStream o)
void | NotEmptyHolder._write(OutputStream o)
void | InvalidNameHolder._write(OutputStream o)
void | CannotProceedHolder._write(OutputStream o)
void | AlreadyBoundHolder._write(OutputStream o)
static void | AlreadyBoundHelper.write(OutputStream ostream, AlreadyBound value)
static void | CannotProceedHelper.write(OutputStream ostream, CannotProceed value)
static void | InvalidNameHelper.write(OutputStream ostream, InvalidName value)
static void | NotEmptyHelper.write(OutputStream ostream, NotEmpty value)
static void | NotFoundHelper.write(OutputStream ostream, NotFound value)
static void | NotFoundReasonHelper.write(OutputStream ostream, NotFoundReason value)

Uses of OutputStream in org.omg.DynamicAny

Methods in org.omg.DynamicAny with parameters of type OutputStream
static void | AnySeqHelper.write(OutputStream ostream, Any[] value)
static void | DynAnyHelper.write(OutputStream ostream, DynAny value)
static void | DynAnySeqHelper.write(OutputStream ostream, DynAny[] value)
static void | DynAnyFactoryHelper.write(OutputStream ostream, DynAnyFactory value)
static void | DynArrayHelper.write(OutputStream ostream, DynArray value)
static void | DynEnumHelper.write(OutputStream ostream, DynEnum value)
static void | DynFixedHelper.write(OutputStream ostream, DynFixed value)
static void | DynSequenceHelper.write(OutputStream ostream, DynSequence value)
static void | DynStructHelper.write(OutputStream ostream, DynStruct value)
static void | DynUnionHelper.write(OutputStream ostream, DynUnion value)
static void | DynValueHelper.write(OutputStream ostream, DynValue value)
static void | NameDynAnyPairHelper.write(OutputStream ostream, NameDynAnyPair value)
static void | NameDynAnyPairSeqHelper.write(OutputStream ostream, NameDynAnyPair[] value)
static void | NameValuePairHelper.write(OutputStream ostream, NameValuePair value)
static void | NameValuePairSeqHelper.write(OutputStream ostream, NameValuePair[] value)
static void | FieldNameHelper.write(OutputStream ostream, String value)

Uses of OutputStream in org.omg.DynamicAny.DynAnyFactoryPackage

Methods in org.omg.DynamicAny.DynAnyFactoryPackage with parameters of type OutputStream
static void InconsistentTypeCodeHelper.write(OutputStream ostream, InconsistentTypeCode value)

Uses of OutputStream in org.omg.DynamicAny.DynAnyPackage

Methods in org.omg.DynamicAny.DynAnyPackage with parameters of type OutputStream
static void | InvalidValueHelper.write(OutputStream ostream, InvalidValue value)
static void | TypeMismatchHelper.write(OutputStream ostream, TypeMismatch value)

Uses of OutputStream in org.omg.IOP

Methods in org.omg.IOP with parameters of type OutputStream
void | TaggedProfileHolder._write(OutputStream o)
void | TaggedComponentHolder._write(OutputStream o)
void | ServiceContextListHolder._write(OutputStream o)
void | ServiceContextHolder._write(OutputStream o)
void | MultipleComponentProfileHolder._write(OutputStream o)
void | IORHolder._write(OutputStream o)
static void | CodecFactoryHelper.write(OutputStream ostream, CodecFactory value)
static void | ServiceIdHelper.write(OutputStream ostream, int value)
static void | ProfileIdHelper.write(OutputStream ostream, int value)
static void | ComponentIdHelper.write(OutputStream ostream, int value)
static void | IORHelper.write(OutputStream ostream, IOR value)
static void | ServiceContextHelper.write(OutputStream ostream, ServiceContext value)
static void | ServiceContextListHelper.write(OutputStream ostream, ServiceContext[] value)
static void | TaggedComponentHelper.write(OutputStream ostream, TaggedComponent value)
static void | MultipleComponentProfileHelper.write(OutputStream ostream, TaggedComponent[] value)
static void | TaggedProfileHelper.write(OutputStream ostream, TaggedProfile value)

Uses of OutputStream in org.omg.IOP.CodecFactoryPackage

Methods in org.omg.IOP.CodecFactoryPackage with parameters of type OutputStream
static void UnknownEncodingHelper.write(OutputStream ostream, UnknownEncoding value)

Uses of OutputStream in org.omg.IOP.CodecPackage

Methods in org.omg.IOP.CodecPackage with parameters of type OutputStream
static void | FormatMismatchHelper.write(OutputStream ostream, FormatMismatch value)
static void | InvalidTypeForEncodingHelper.write(OutputStream ostream, InvalidTypeForEncoding value)
static void | TypeMismatchHelper.write(OutputStream ostream, TypeMismatch value)

Uses of OutputStream in org.omg.Messaging

Methods in org.omg.Messaging with parameters of type OutputStream
static void SyncScopeHelper.write(OutputStream ostream, short value)

Uses of OutputStream in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor with parameters of type OutputStream
void | ObjectReferenceTemplateSeqHolder._write(OutputStream o)
void | ObjectReferenceTemplateHolder._write(OutputStream o)
void | ObjectReferenceFactoryHolder._write(OutputStream o)
void | IORInterceptor_3_0Holder._write(OutputStream o)
static void | ObjectIdHelper.write(OutputStream ostream, byte[] value)
static void | CurrentHelper.write(OutputStream ostream, Current value)
static void | ForwardRequestHelper.write(OutputStream ostream, ForwardRequest value)
static void | AdapterManagerIdHelper.write(OutputStream ostream, int value)
static void | InvalidSlotHelper.write(OutputStream ostream, InvalidSlot value)
static void | IORInterceptor_3_0Helper.write(OutputStream ostream, IORInterceptor_3_0 value)
static void | ObjectReferenceFactoryHelper.write(OutputStream ostream, ObjectReferenceFactory value)
static void | ObjectReferenceTemplateHelper.write(OutputStream ostream, ObjectReferenceTemplate value)
static void | ObjectReferenceTemplateSeqHelper.write(OutputStream ostream, ObjectReferenceTemplate[] value)
static void | AdapterStateHelper.write(OutputStream ostream, short value)
static void | ServerIdHelper.write(OutputStream ostream, String value)
static void | ORBIdHelper.write(OutputStream ostream, String value)
static void | AdapterNameHelper.write(OutputStream ostream, String[] value)

Uses of OutputStream in org.omg.PortableInterceptor.ORBInitInfoPackage

Methods in org.omg.PortableInterceptor.ORBInitInfoPackage with parameters of type OutputStream
static void | DuplicateNameHelper.write(OutputStream ostream, DuplicateName value)
static void | InvalidNameHelper.write(OutputStream ostream, InvalidName value)
static void | ObjectIdHelper.write(OutputStream ostream, String value)

Uses of OutputStream in org.omg.PortableServer

Methods in org.omg.PortableServer that return OutputStream
OutputStream | ServantLocatorPOA._invoke(String $method, InputStream in, ResponseHandler $rh)
OutputStream | ServantActivatorPOA._invoke(String $method, InputStream in, ResponseHandler $rh)

Methods in org.omg.PortableServer with parameters of type OutputStream
static void | CurrentHelper.write(OutputStream ostream, Current value)
static void | ForwardRequestHelper.write(OutputStream ostream, ForwardRequest value)
static void | POAHelper.write(OutputStream ostream, POA value)
static void | ServantActivatorHelper.write(OutputStream ostream, ServantActivator value)
static void | ServantLocatorHelper.write(OutputStream ostream, ServantLocator value)

Uses of OutputStream in org.omg.PortableServer.CurrentPackage

Methods in org.omg.PortableServer.CurrentPackage with parameters of type OutputStream
static void NoContextHelper.write(OutputStream ostream, NoContext value)

Uses of OutputStream in org.omg.PortableServer.POAManagerPackage

Methods in org.omg.PortableServer.POAManagerPackage with parameters of type OutputStream
static void AdapterInactiveHelper.write(OutputStream ostream, AdapterInactive value)

Uses of OutputStream in org.omg.PortableServer.POAPackage

Methods in org.omg.PortableServer.POAPackage with parameters of type OutputStream
static void | AdapterAlreadyExistsHelper.write(OutputStream ostream, AdapterAlreadyExists value)
static void | AdapterNonExistentHelper.write(OutputStream ostream, AdapterNonExistent value)
static void | InvalidPolicyHelper.write(OutputStream ostream, InvalidPolicy value)
static void | NoServantHelper.write(OutputStream ostream, NoServant value)
static void | ObjectAlreadyActiveHelper.write(OutputStream ostream, ObjectAlreadyActive value)
static void | ObjectNotActiveHelper.write(OutputStream ostream, ObjectNotActive value)
static void | ServantAlreadyActiveHelper.write(OutputStream ostream, ServantAlreadyActive value)
static void | ServantNotActiveHelper.write(OutputStream ostream, ServantNotActive value)
static void | WrongAdapterHelper.write(OutputStream ostream, WrongAdapter value)
static void | WrongPolicyHelper.write(OutputStream ostream, WrongPolicy value)

Uses of OutputStream in org.omg.PortableServer.ServantLocatorPackage

Methods in org.omg.PortableServer.ServantLocatorPackage with parameters of type OutputStream
 void CookieHolder._write(OutputStream os)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.portable.RemarshalException

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.portable.RemarshalException

Packages that use RemarshalException
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.

Uses of RemarshalException in org.omg.CORBA

Methods in org.omg.CORBA that throw RemarshalException
 InputStream LocalObject._invoke(OutputStream output)
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.

Uses of RemarshalException in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable that throw RemarshalException
InputStream | ObjectImpl._invoke(OutputStream output) Invokes an operation and returns an InputStream object for reading the response.
InputStream | Delegate.invoke(Object self, OutputStream output) invoke is called by a stub to invoke an operation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.portable.ServantObject

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.portable.ServantObject

Packages that use ServantObject
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.

Uses of ServantObject in org.omg.CORBA

Methods in org.omg.CORBA that return ServantObject
 ServantObject LocalObject._servant_preinvoke(String operation, Class expectedType)
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.

Methods in org.omg.CORBA with parameters of type ServantObject
 void LocalObject._servant_postinvoke(ServantObject servant)
Throws an org.omg.CORBA.NO_IMPLEMENT exception with the message "This is a locally constrained object." This method is the default implementation of the org.omg.CORBA.Object method.

Uses of ServantObject in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable that return ServantObject
ServantObject | ObjectImpl._servant_preinvoke(String operation, Class expectedType) Returns a Java reference to the local servant that should be used for sending a request for the method specified.
ServantObject | Delegate.servant_preinvoke(Object self, String operation, Class expectedType) Returns a Java reference to the servant which should be used for this request.

Methods in org.omg.CORBA.portable with parameters of type ServantObject
 void ObjectImpl._servant_postinvoke(ServantObject servant)
Is called by the local stub after it has invoked an operation on the local servant that was previously retrieved from a call to the method _servant_preinvoke.
 void Delegate.servant_postinvoke(Object self, ServantObject servant)
servant_postinvoke() is invoked by the local stub after the operation has been invoked on the local servant.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.portable.UnknownException

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.portable.UnknownException

No usage of org.omg.CORBA.portable.UnknownException

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.portable.BoxedValueHelper

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.portable.BoxedValueHelper

Packages that use BoxedValueHelper
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA_2_3.portable | Provides methods for the input and output of value types, and contains other updates to the org/omg/CORBA/portable package.

Uses of BoxedValueHelper in org.omg.CORBA

Classes in org.omg.CORBA that implement BoxedValueHelper
class | StringValueHelper The Helper for StringValue.
class | WStringValueHelper org/omg/CORBA/WStringValueHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from orb.idl 31 May 1999 22:27:30 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications : ORB core as defined by CORBA 2.3.1 (formal/99-10-07) IDL/Java Language Mapping as defined in ptc/00-01-08

Uses of BoxedValueHelper in org.omg.CORBA_2_3.portable

Methods in org.omg.CORBA_2_3.portable with parameters of type BoxedValueHelper
Serializable | InputStream.read_value(BoxedValueHelper factory) Unmarshalls a value type from the input stream.
void | OutputStream.write_value(Serializable value, BoxedValueHelper factory) Marshals a value type to the output stream.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.portable.CustomValue

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.portable.CustomValue

No usage of org.omg.CORBA.portable.CustomValue

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.portable.IDLEntity

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.portable.IDLEntity

Packages that use IDLEntity
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.DynAnyPackage | Provides the exceptions used with the DynAny interface (InvalidValue, Invalid, InvalidSeq, and TypeMismatch).
org.omg.CORBA.ORBPackage | Provides the exception InvalidName, which is thrown by the method ORB.resolve_initial_references and the exception InconsistentTypeCode, which is thrown by the Dynamic Any creation methods in the ORB class.
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.
org.omg.CORBA.TypeCodePackage | Provides the user-defined exceptions BadKind and Bounds, which are thrown by methods in in the class TypeCode.
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextExtPackage | This package contains the following classes, which are used in org.omg.CosNaming.NamingContextExt:
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.
org.omg.Dynamic | This package contains the Dynamic module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.9.
org.omg.DynamicAny | Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.IOP.CodecFactoryPackage | This package contains the exceptions specified in the IOP::CodeFactory interface (as part of the Portable Interceptors spec).
org.omg.IOP.CodecPackage | This package is generated from the IOP::Codec IDL interface definition.
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.
org.omg.PortableInterceptor.ORBInitInfoPackage | This package contains the exceptions and typedefs from the ORBInitInfo local interface of the PortableInterceptor module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.7.2.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.CurrentPackage | Provides method implementations with access to the identity of the object on which the method was invoked.
org.omg.PortableServer.POAManagerPackage | Encapsulates the processing state of the POAs it is associated with.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.
org.omg.SendingContext | Provides support for the marshalling of value types.

Uses of IDLEntity in org.omg.CORBA

Subinterfaces of IDLEntity in org.omg.CORBA
interface | Current Interfaces derived from the Current interface enable ORB and CORBA services to provide access to information (context) associated with the thread of execution in which they are running.
interface | DataInputStream Defines the methods used to read primitive data types from input streams for unmarshaling custom value types.
interface | DataOutputStream Defines the methods used to write primitive data types to output streams for marshalling custom value types.
interface | DomainManager Provides mechanisms for establishing and navigating relationships to superior and subordinate domains, as well as for creating and accessing policies.
interface | IDLType An abstract interface inherited by all Interface Repository (IR) objects that represent OMG IDL types.
interface | IRObject An IRObject IDL interface represents the most generic interface from which all other Interface Repository interfaces are derived, even the Repository itself.
interface | Policy Interfaces derived from the Policy interface allow an ORB or CORBA service access to certain choices that affect its operation.

Classes in org.omg.CORBA that implement IDLEntity
class | _IDLTypeStub The Stub for IDLType.
class | _PolicyStub The Stub for Policy.
class | Any Serves as a container for any data that can be described in IDL or for any IDL primitive type.
class | Bounds A user exception thrown when a parameter is not within the legal bounds for the object that a method is trying to access.
class | CompletionStatus An object that indicates whether a method had completed running when a SystemException was thrown.
class | DefinitionKind The class that provides the constants used to identify the type of an Interface Repository object.
class | NameValuePair Associates a name with a value that is an attribute of an IDL struct, and is used in the DynStruct APIs.
class | ParameterMode Enumeration of parameter modes for Parameter.
class | PolicyError A user exception thrown when a policy error occurs.
class | ServiceDetail An object that represents an ORB service: its service_detail_type field contains the type of the ORB service, and its service_detail field contains a description of the ORB service.
class | ServiceInformation An IDL struct in the CORBA module that stores information about a CORBA service available in the ORB implementation and is obtained from the ORB.get_service_information method.
class | SetOverrideType The mapping of a CORBA enum tagging SET_OVERRIDE and ADD_OVERRIDE, which indicate whether policies should replace the existing policies of an Object or be added to them.
class | StructMember Describes a member of an IDL struct in the Interface Repository, including the name of the struct member, the type of the struct member, and the typedef that represents the IDL type of the struct member described the struct member object.
class | TypeCode A container for information about a specific CORBA data type.
class | UnionMember A description in the Interface Repository of a member of an IDL union.
class | UnknownUserException A class that contains user exceptions returned by the server.
class | UserException The root class for CORBA IDL-defined user exceptions.
class | ValueMember A description in the Interface Repository of a member of a value object.
class | WrongTransaction The CORBA WrongTransaction user-defined exception.

Uses of IDLEntity in org.omg.CORBA.DynAnyPackage

Classes in org.omg.CORBA.DynAnyPackage that implement IDLEntity
class | Invalid Invalid is thrown by dynamic any operations when a bad DynAny or Any is passed as a parameter.
class | InvalidSeq The InvalidSeq exception is thrown by all operations on dynamic anys that take a sequence (Java array) as an argument, when that sequence is invalid.
class | InvalidValue
class | TypeMismatch TypeMismatch is thrown by dynamic any accessor methods when type of the actual contents do not match what is trying to be accessed.

Uses of IDLEntity in org.omg.CORBA.ORBPackage

Classes in org.omg.CORBA.ORBPackage that implement IDLEntity
class | InconsistentTypeCode InconsistentTypeCode is thrown when an attempt is made to create a dynamic any with a type code that does not match the particular subclass of DynAny.
class | InvalidName The InvalidName exception is raised when ORB.resolve_initial_references is passed a name for which there is no initial reference.

Uses of IDLEntity in org.omg.CORBA.portable

Subinterfaces of IDLEntity in org.omg.CORBA.portable
interface | CustomValue An extension of ValueBase that is implemented by custom value types.
interface | StreamableValue Defines the base type for all non-boxed IDL valuetypes that are not custom marshaled.
interface | ValueBase The generated Java classes corresponding to valuetype IDL types implement this interface.

Uses of IDLEntity in org.omg.CORBA.TypeCodePackage

Classes in org.omg.CORBA.TypeCodePackage that implement IDLEntity
 class BadKind
The exception BadKind is thrown when an inappropriate operation is invoked on a TypeCode object.

Uses of IDLEntity in org.omg.CosNaming

Subinterfaces of IDLEntity in org.omg.CosNaming
interface | BindingIterator The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
interface | NamingContext A naming context is an object that contains a set of name bindings in which each name is unique.
interface | NamingContextExt NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.

Classes in org.omg.CosNaming that implement IDLEntity
class | _BindingIteratorImplBase
class | _BindingIteratorStub The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
class | _NamingContextExtStub NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
class | _NamingContextImplBase
class | _NamingContextStub A naming context is an object that contains a set of name bindings in which each name is unique.
class | Binding org/omg/CosNaming/Binding.java .
class | BindingType Specifies whether the given binding is for a object (that is not a naming context) or for a naming context.
class | NameComponent org/omg/CosNaming/NameComponent.java .

Uses of IDLEntity in org.omg.CosNaming.NamingContextExtPackage

Classes in org.omg.CosNaming.NamingContextExtPackage that implement IDLEntity
 class InvalidAddress
org/omg/CosNaming/NamingContextExtPackage/InvalidAddress.java .

Uses of IDLEntity in org.omg.CosNaming.NamingContextPackage

Classes in org.omg.CosNaming.NamingContextPackage that implement IDLEntity
class | AlreadyBound org/omg/CosNaming/NamingContextPackage/AlreadyBound.java .
class | CannotProceed org/omg/CosNaming/NamingContextPackage/CannotProceed.java .
class | NotEmpty org/omg/CosNaming/NamingContextPackage/NotEmpty.java .
class | NotFound org/omg/CosNaming/NamingContextPackage/NotFound.java .
class | NotFoundReason Indicates the reason for not able to resolve.

Uses of IDLEntity in org.omg.Dynamic

Classes in org.omg.Dynamic that implement IDLEntity
 class Parameter
org/omg/Dynamic/Parameter.java .

Uses of IDLEntity in org.omg.DynamicAny

Subinterfaces of IDLEntity in org.omg.DynamicAny
interface | DynAny Any values can be dynamically interpreted (traversed) and constructed through DynAny objects.
interface | DynAnyFactory DynAny objects can be created by invoking operations on the DynAnyFactory object.
interface | DynArray DynArray objects support the manipulation of IDL arrays.
interface | DynEnum DynEnum objects support the manipulation of IDL enumerated values.
interface | DynFixed DynFixed objects support the manipulation of IDL fixed values.
interface | DynSequence DynSequence objects support the manipulation of IDL sequences.
interface | DynStruct DynStruct objects support the manipulation of IDL struct and exception values.
interface | DynUnion DynUnion objects support the manipulation of IDL unions.
interface | DynValue DynValue objects support the manipulation of IDL non-boxed value types.
interface | DynValueBox DynValueBox objects support the manipulation of IDL boxed value types.
interface | DynValueCommon DynValueCommon provides operations supported by both the DynValue and DynValueBox interfaces.

Classes in org.omg.DynamicAny that implement IDLEntity
class | _DynAnyFactoryStub DynAny objects can be created by invoking operations on the DynAnyFactory object.
class | _DynAnyStub Any values can be dynamically interpreted (traversed) and constructed through DynAny objects.
class | _DynArrayStub DynArray objects support the manipulation of IDL arrays.
class | _DynEnumStub DynEnum objects support the manipulation of IDL enumerated values.
class | _DynFixedStub DynFixed objects support the manipulation of IDL fixed values.
class | _DynSequenceStub DynSequence objects support the manipulation of IDL sequences.
class | _DynStructStub DynStruct objects support the manipulation of IDL struct and exception values.
class | _DynUnionStub DynUnion objects support the manipulation of IDL unions.
class | _DynValueStub DynValue objects support the manipulation of IDL non-boxed value types.
class | NameDynAnyPair org/omg/DynamicAny/NameDynAnyPair.java .

Uses of IDLEntity in org.omg.IOP

Subinterfaces of IDLEntity in org.omg.IOP
interface | Codec The formats of IOR components and service context data used by ORB services are often defined as CDR encapsulations encoding instances of IDL defined data types.
interface | CodecFactory Codecs are obtained from the CodecFactory.

Classes in org.omg.IOP that implement IDLEntity
class | Encoding org/omg/IOP/Encoding.java .
class | IOR org/omg/IOP/IOR.java .
class | ServiceContext org/omg/IOP/ServiceContext.java .
class | TaggedComponent org/omg/IOP/TaggedComponent.java .
class | TaggedProfile org/omg/IOP/TaggedProfile.java .

Uses of IDLEntity in org.omg.IOP.CodecFactoryPackage

Classes in org.omg.IOP.CodecFactoryPackage that implement IDLEntity
 class UnknownEncoding
org/omg/IOP/CodecFactoryPackage/UnknownEncoding.java .

Uses of IDLEntity in org.omg.IOP.CodecPackage

Classes in org.omg.IOP.CodecPackage that implement IDLEntity
class | FormatMismatch org/omg/IOP/CodecPackage/FormatMismatch.java .
class | InvalidTypeForEncoding org/omg/IOP/CodecPackage/InvalidTypeForEncoding.java .

Uses of IDLEntity in org.omg.PortableInterceptor

Subinterfaces of IDLEntity in org.omg.PortableInterceptor
interface | ClientRequestInfo Request Information, accessible to client-side request interceptors.
interface | ClientRequestInterceptor Client-side request interceptor.
interface | Interceptor All Portable Interceptors implement Interceptor.
interface | IORInfo Provides the server-side ORB service with access to the applicable policies during IOR construction and the ability to add components.
interface | IORInterceptor Interceptor used to establish tagged components in the profiles within an IOR.
interface | IORInterceptor_3_0 org/omg/PortableInterceptor/IORInterceptor_3_0.java .
interface | ObjectReferenceFactory The object reference factory.
interface | ObjectReferenceTemplate The object reference template.
interface | ORBInitializer Facilitates interceptor registration and ORB initialization.
interface | ORBInitInfo Passed to each ORBInitializer, allowing it to to register interceptors and perform other duties while the ORB is initializing.
interface | PolicyFactory Enables policy types to be constructed using CORBA.ORB.create_policy.
interface | RequestInfo Request Information, accessible to Interceptors.
interface | ServerRequestInfo Request Information, accessible to server-side request interceptors.
interface | ServerRequestInterceptor Server-side request interceptor.

Classes in org.omg.PortableInterceptor that implement IDLEntity
 class InvalidSlot
org/omg/PortableInterceptor/InvalidSlot.java .

Uses of IDLEntity in org.omg.PortableInterceptor.ORBInitInfoPackage

Classes in org.omg.PortableInterceptor.ORBInitInfoPackage that implement IDLEntity
 class DuplicateName
org/omg/PortableInterceptor/ORBInitInfoPackage/DuplicateName.java .

Uses of IDLEntity in org.omg.PortableServer

Subinterfaces of IDLEntity in org.omg.PortableServer
interface | AdapterActivator An adapter activator supplies a POA with the ability to create child POAs on demand, as a side-effect of receiving a request that names the child POA (or one of its children), or when find_POA is called with an activate parameter value of TRUE.
interface | IdAssignmentPolicy IdAssignmentPolicy specifies whether Object Ids in the created POA are generated by the application or by the ORB.
interface | IdUniquenessPolicy The IdUniquenessPolicy specifies whether the servants activated in the created POA must have unique object i identities.
interface | ImplicitActivationPolicy This policy specifies whether implicit activation of servants is supported in the created POA.
interface | LifespanPolicy The LifespanPolicy specifies the lifespan of the objects implemented in the created POA.
interface | POA A POA object manages the implementation of a collection of objects.
interface | POAManager Each POA object has an associated POAManager object.
interface | RequestProcessingPolicy This policy specifies how requests are processed by the created POA.
interface | ServantActivator When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
interface | ServantLocator When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.
interface | ServantManager A servant manager supplies a POA with the ability to activate objects on demand when the POA receives a request targeted at an inactive object.
interface | ServantRetentionPolicy This policy specifies whether the created POA retains active servants in an Active Object Map.
interface | ThreadPolicy The ThreadPolicy specifies the threading model used with the created POA.

Classes in org.omg.PortableServer that implement IDLEntity
class | _ServantActivatorStub When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
class | _ServantLocatorStub When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.
class | ForwardRequest org/omg/PortableServer/ForwardRequest.java .
class | IdAssignmentPolicyValue The IdAssignmentPolicyValue can have the following values.
class | IdUniquenessPolicyValue IdUniquenessPolicyValue can have the following values.
class | ImplicitActivationPolicyValue ImplicitActivationPolicyValue has the following semantics.
class | LifespanPolicyValue The LifespanPolicyValue can have the following values.
class | RequestProcessingPolicyValue The RequestProcessingPolicyValue can have the following values.
class | ServantRetentionPolicyValue ServantRetentionPolicyValue can have the following values.
class | ThreadPolicyValue The ThreadPolicyValue can have the following values.

Uses of IDLEntity in org.omg.PortableServer.CurrentPackage

Classes in org.omg.PortableServer.CurrentPackage that implement IDLEntity
 class NoContext
org/omg/PortableServer/CurrentPackage/NoContext.java .

Uses of IDLEntity in org.omg.PortableServer.POAManagerPackage

Classes in org.omg.PortableServer.POAManagerPackage that implement IDLEntity
class | AdapterInactive org/omg/PortableServer/POAManagerPackage/AdapterInactive.java .
class | State Specifies the states for the POAManager

Uses of IDLEntity in org.omg.PortableServer.POAPackage

Classes in org.omg.PortableServer.POAPackage that implement IDLEntity
class | AdapterAlreadyExists org/omg/PortableServer/POAPackage/AdapterAlreadyExists.java .
class | AdapterNonExistent org/omg/PortableServer/POAPackage/AdapterNonExistent.java .
class | InvalidPolicy org/omg/PortableServer/POAPackage/InvalidPolicy.java .
class | NoServant org/omg/PortableServer/POAPackage/NoServant.java .
class | ObjectAlreadyActive org/omg/PortableServer/POAPackage/ObjectAlreadyActive.java .
class | ObjectNotActive org/omg/PortableServer/POAPackage/ObjectNotActive.java .
class | ServantAlreadyActive org/omg/PortableServer/POAPackage/ServantAlreadyActive.java .
class | ServantNotActive org/omg/PortableServer/POAPackage/ServantNotActive.java .
class | WrongAdapter org/omg/PortableServer/POAPackage/WrongAdapter.java .
class | WrongPolicy org/omg/PortableServer/POAPackage/WrongPolicy.java .

Uses of IDLEntity in org.omg.SendingContext

Subinterfaces of IDLEntity in org.omg.SendingContext
 interface RunTime
Defines the base class that represents the Sending Context of a request.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.portable.InvokeHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.portable.InvokeHandler

Packages that use InvokeHandler
javax.rmi.CORBA | Contains portability APIs for RMI-IIOP.
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of InvokeHandler in javax.rmi.CORBA

Subinterfaces of InvokeHandler in javax.rmi.CORBA
 interface Tie
Defines methods which all RMI-IIOP server side ties must implement.

Uses of InvokeHandler in org.omg.CosNaming

Classes in org.omg.CosNaming that implement InvokeHandler
class | BindingIteratorPOA The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
class | NamingContextExtPOA NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
class | NamingContextPOA A naming context is an object that contains a set of name bindings in which each name is unique.

Uses of InvokeHandler in org.omg.PortableServer

Classes in org.omg.PortableServer that implement InvokeHandler
class | ServantActivatorPOA When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
class | ServantLocatorPOA When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.portable.ResponseHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.portable.ResponseHandler

Packages that use ResponseHandler
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ResponseHandler in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable with parameters of type ResponseHandler
 OutputStream InvokeHandler._invoke(String method, InputStream input, ResponseHandler handler)
Invoked by the ORB to dispatch a request to the servant.

Uses of ResponseHandler in org.omg.CosNaming

Methods in org.omg.CosNaming with parameters of type ResponseHandler
OutputStream | NamingContextExtPOA._invoke(String $method, InputStream in, ResponseHandler $rh)
OutputStream | NamingContextPOA._invoke(String $method, InputStream in, ResponseHandler $rh)
OutputStream | BindingIteratorPOA._invoke(String $method, InputStream in, ResponseHandler $rh)

Uses of ResponseHandler in org.omg.PortableServer

Methods in org.omg.PortableServer with parameters of type ResponseHandler
OutputStream | ServantLocatorPOA._invoke(String $method, InputStream in, ResponseHandler $rh)
OutputStream | ServantActivatorPOA._invoke(String $method, InputStream in, ResponseHandler $rh)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.portable.Streamable

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.portable.Streamable

Packages that use Streamable
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextExtPackage | This package contains the following classes, which are used in org.omg.CosNaming.NamingContextExt:
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.
org.omg.PortableServer.ServantLocatorPackage | Provides classes and interfaces for locating the servant.

Uses of Streamable in org.omg.CORBA

Classes in org.omg.CORBA that implement Streamable
class | AnyHolder The Holder for Any.
class | AnySeqHolder The Holder for AnySeq.
class | BooleanHolder The Holder for Boolean.
class | BooleanSeqHolder The Holder for BooleanSeq.
class | ByteHolder The Holder for Byte.
class | CharHolder The Holder for Char.
class | CharSeqHolder The Holder for CharSeq.
class | CurrentHolder The Holder for Current.
class | DoubleHolder The Holder for Double.
class | DoubleSeqHolder The Holder for DoubleSeq.
class | FixedHolder The Holder for Fixed.
class | FloatHolder The Holder for Float.
class | FloatSeqHolder The Holder for FloatSeq.
class | IntHolder The Holder for Int.
class | LongHolder The Holder for Long.
class | LongLongSeqHolder The Holder for LongLongSeq.
class | LongSeqHolder The Holder for LongSeq.
class | ObjectHolder The Holder for Object.
class | OctetSeqHolder The Holder for OctetSeq.
class | ParameterModeHolder Enumeration of parameter modes for Parameter.
class | PolicyErrorHolder Thrown to indicate problems with parameter values passed to the ORB.create_policy operation.
class | PolicyHolder The Holder for Policy.
class | PolicyListHolder The Holder for PolicyList.
class | PrincipalHolder Deprecated. Deprecated by CORBA 2.2.
class | ServiceInformationHolder The Holder for ServiceInformation.
class | ShortHolder The Holder for Short.
class | ShortSeqHolder The Holder for ShortSeq.
class | StringHolder The Holder for String.
class | StringSeqHolder An array of Strings
class | TypeCodeHolder The Holder for TypeCode.
class | ULongLongSeqHolder The Holder for ULongLongSeq.
class | ULongSeqHolder The Holder for ULongSeq.
class | UnknownUserExceptionHolder The Holder for UnknownUserException.
class | UShortSeqHolder The Holder for UShortSeq.
class | ValueBaseHolder The Holder for ValueBase.
class | WCharSeqHolder The Holder for WCharSeq.
class | WrongTransactionHolder The Holder for WrongTransaction.
class | WStringSeqHolder An array of WStrings

Methods in org.omg.CORBA that return Streamable
 Streamable Any.extract_Streamable()
Extracts a Streamable from this Any object's value field.

Methods in org.omg.CORBA with parameters of type Streamable
 void Any.insert_Streamable(Streamable s)
Inserts the given Streamable object into this Any object's value field.

Uses of Streamable in org.omg.CORBA.portable

Subinterfaces of Streamable in org.omg.CORBA.portable
 interface StreamableValue
Defines the base type for all non-boxed IDL valuetypes that are not custom marshaled.

Uses of Streamable in org.omg.CosNaming

Classes in org.omg.CosNaming that implement Streamable
class | BindingHolder org/omg/CosNaming/BindingHolder.java .
class | BindingIteratorHolder The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
class | BindingListHolder List of Bindings.
class | BindingTypeHolder Specifies whether the given binding is for a object (that is not a naming context) or for a naming context.
class | NameComponentHolder org/omg/CosNaming/NameComponentHolder.java .
class | NameHolder A name is a sequence of name components.
class | NamingContextExtHolder NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
class | NamingContextHolder A naming context is an object that contains a set of name bindings in which each name is unique.

Uses of Streamable in org.omg.CosNaming.NamingContextExtPackage

Classes in org.omg.CosNaming.NamingContextExtPackage that implement Streamable
 class InvalidAddressHolder
org/omg/CosNaming/NamingContextExtPackage/InvalidAddressHolder.java .

Uses of Streamable in org.omg.CosNaming.NamingContextPackage

Classes in org.omg.CosNaming.NamingContextPackage that implement Streamable
class | AlreadyBoundHolder org/omg/CosNaming/NamingContextPackage/AlreadyBoundHolder.java .
class | CannotProceedHolder org/omg/CosNaming/NamingContextPackage/CannotProceedHolder.java .
class | InvalidNameHolder org/omg/CosNaming/NamingContextPackage/InvalidNameHolder.java .
class | NotEmptyHolder org/omg/CosNaming/NamingContextPackage/NotEmptyHolder.java .
class | NotFoundHolder org/omg/CosNaming/NamingContextPackage/NotFoundHolder.java .
class | NotFoundReasonHolder Indicates the reason for not able to resolve.

Uses of Streamable in org.omg.IOP

Classes in org.omg.IOP that implement Streamable
class | IORHolder org/omg/IOP/IORHolder.java .
class | MultipleComponentProfileHolder An array of tagged components, forming a multiple component profile.
class | ServiceContextHolder org/omg/IOP/ServiceContextHolder.java .
class | ServiceContextListHolder An array of service contexts, forming a service context list.
class | TaggedComponentHolder org/omg/IOP/TaggedComponentHolder.java .
class | TaggedProfileHolder org/omg/IOP/TaggedProfileHolder.java .

Uses of Streamable in org.omg.PortableInterceptor

Classes in org.omg.PortableInterceptor that implement Streamable
class | IORInterceptor_3_0Holder org/omg/PortableInterceptor/IORInterceptor_3_0Holder.java .
class | ObjectReferenceFactoryHolder The object reference factory.
class | ObjectReferenceTemplateHolder The object reference template.
class | ObjectReferenceTemplateSeqHolder Sequence of object reference templates is used for reporting state changes that do not occur on the adapter manager.

Uses of Streamable in org.omg.PortableServer.ServantLocatorPackage

Classes in org.omg.PortableServer.ServantLocatorPackage that implement Streamable
 class CookieHolder
The native type PortableServer::ServantLocator::Cookie is mapped to java.lang.Object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.portable.StreamableValue

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.portable.StreamableValue

No usage of org.omg.CORBA.portable.StreamableValue

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.portable.ValueBase

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.portable.ValueBase

Packages that use ValueBase
org.omg.CORBA | Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of ValueBase in org.omg.CORBA

Subinterfaces of ValueBase in org.omg.CORBA
interface | DataInputStream Defines the methods used to read primitive data types from input streams for unmarshaling custom value types.
interface | DataOutputStream Defines the methods used to write primitive data types to output streams for marshalling custom value types.

Uses of ValueBase in org.omg.CORBA.portable

Subinterfaces of ValueBase in org.omg.CORBA.portable
interface | CustomValue An extension of ValueBase that is implemented by custom value types.
interface | StreamableValue Defines the base type for all non-boxed IDL valuetypes that are not custom marshaled.

Uses of ValueBase in org.omg.PortableInterceptor

Subinterfaces of ValueBase in org.omg.PortableInterceptor
interface | ObjectReferenceFactory The object reference factory.
interface | ObjectReferenceTemplate The object reference template.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.portable.ValueFactory

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.portable.ValueFactory

Packages that use ValueFactory
org.omg.CORBA_2_3 The CORBA_2_3 package defines additions to existing CORBA interfaces in the Java[tm] Standard Edition 6. These changes occurred in recent revisions to the CORBA API defined by the OMG. The new methods were added to interfaces derived from the corresponding interfaces in the CORBA package. This provides backward compatibility and avoids breaking the JCK tests.

Uses of ValueFactory in org.omg.CORBA_2_3

Methods in org.omg.CORBA_2_3 that return ValueFactory
ValueFactory | ORB.lookup_value_factory(String id)
ValueFactory | ORB.register_value_factory(String id, ValueFactory factory)

Methods in org.omg.CORBA_2_3 with parameters of type ValueFactory
 ValueFactory ORB.register_value_factory(String id, ValueFactory factory)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.portable.ValueInputStream

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.portable.ValueInputStream

No usage of org.omg.CORBA.portable.ValueInputStream

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CORBA.portable.ValueOutputStream

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CORBA.portable.ValueOutputStream

No usage of org.omg.CORBA.portable.ValueOutputStream

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Delegate

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Class Delegate

java.lang.Object
    extended by  org.omg.CORBA.portable.Delegate
Direct Known Subclasses:
Delegate
public abstract class Delegate
extends Object

Specifies a portable API for ORB-vendor-specific implementation of the org.omg.CORBA.Object methods. Each stub (proxy) contains a delegate object, to which all org.omg.CORBA.Object methods are forwarded. This allows a stub generated by one vendor's ORB to work with the delegate from another vendor's ORB.

See Also:
Object

Constructor Summary
Delegate()
Method Summary
abstract  Request create_request(Object obj, Context ctx, String operation, NVList arg_list, NamedValue result)
Creates a Request instance for use in the Dynamic Invocation Interface.
abstract  Request create_request(Object obj, Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exclist, ContextList ctxlist)
Creates a Request instance for use in the Dynamic Invocation Interface.
abstract  Object duplicate(Object obj)
Returns a duplicate of the object reference provided.
 boolean equals(Object self, Object obj)
Provides the implementation to override the equals(java.lang.Object obj) method of the delegating CORBA object.
 DomainManager[] get_domain_managers(Object self)
Retrieves the DomainManagers of this object.
abstract  Object get_interface_def(Object self)
Return an InterfaceDef for the object reference provided.
 Policy get_policy(Object self, int policy_type)
Returns the Policy object of the specified type which applies to this object.
abstract  int hash(Object obj, int max)
Returns an ORB-internal identifier (hashcode) for this object reference.
 int hashCode(Object self)
Provides the implementation to override the hashCode() method of the delegating CORBA object.
 InputStream invoke(Object self, OutputStream output)
invoke is called by a stub to invoke an operation.
abstract  boolean is_a(Object obj, String repository_id)
Checks if the object reference is an instance of the given interface.
abstract  boolean is_equivalent(Object obj, Object other)
Determines if the two object references are equivalent.
 boolean is_local(Object self)
Returns true if this object is implemented by a local servant.
abstract  boolean non_existent(Object obj)
Determines whether the server object for the object reference has been destroyed.
 ORB orb(Object obj)
Provides a reference to the orb associated with its parameter.
abstract  void release(Object obj)
Releases resources associated with the object reference provided.
 void releaseReply(Object self, InputStream input)
releaseReply may optionally be called by a stub to release a reply stream back to the ORB when the unmarshaling has completed.
abstract  Request request(Object obj, String operation)
Creates a Request instance for use in the Dynamic Invocation Interface.
 OutputStream request(Object self, String operation, boolean responseExpected)
request is called by a stub to obtain an OutputStream for marshaling arguments.
 void servant_postinvoke(Object self, ServantObject servant)
servant_postinvoke() is invoked by the local stub after the operation has been invoked on the local servant.
 ServantObject servant_preinvoke(Object self, String operation, Class expectedType)
Returns a Java reference to the servant which should be used for this request.
 Object set_policy_override(Object self, Policy[] policies, SetOverrideType set_add)
Associates the policies passed in with a newly created object reference that it returns.
 String toString(Object self)
Provides the implementation to override the toString() method of the delegating CORBA object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Delegate

public Delegate()
Method Detail

get_interface_def

public abstract Object get_interface_def(Object self)
Return an InterfaceDef for the object reference provided.

Parameters:
self - The object reference whose InterfaceDef needs to be returned
Returns:
the InterfaceDef

duplicate

public abstract Object duplicate(Object obj)
Returns a duplicate of the object reference provided.

Parameters:
obj - The object reference whose duplicate needs to be returned
Returns:
the duplicate object reference

release

public abstract void release(Object obj)
Releases resources associated with the object reference provided.

Parameters:
obj - The object reference whose resources need to be released

is_a

public abstract boolean is_a(Object obj,
                             String repository_id)
Checks if the object reference is an instance of the given interface.

Parameters:
obj - The object reference to be checked.
repository_id - The repository identifier of the interface to check against.
Returns:
true if the object reference supports the interface

non_existent

public abstract boolean non_existent(Object obj)
Determines whether the server object for the object reference has been destroyed.

Parameters:
obj - The object reference which delegated to this delegate.
Returns:
true if the ORB knows authoritatively that the server object does not exist, false otherwise

is_equivalent

public abstract boolean is_equivalent(Object obj,
                                      Object other)
Determines if the two object references are equivalent.

Parameters:
obj - The object reference which delegated to this delegate.
other - The object reference to check equivalence against.
Returns:
true if the objects are CORBA-equivalent.

hash

public abstract int hash(Object obj,
                         int max)
Returns an ORB-internal identifier (hashcode) for this object reference.

Parameters:
obj - The object reference which delegated to this delegate.
max - specifies an upper bound on the hash value returned by the ORB.
Returns:
ORB-internal hash identifier for object reference

request

public abstract Request request(Object obj,
                                String operation)
Creates a Request instance for use in the Dynamic Invocation Interface.

Parameters:
obj - The object reference which delegated to this delegate.
operation - The name of the operation to be invoked using the Request instance.
Returns:
the created Request instance

create_request

public abstract Request create_request(Object obj,
                                       Context ctx,
                                       String operation,
                                       NVList arg_list,
                                       NamedValue result)
Creates a Request instance for use in the Dynamic Invocation Interface.

Parameters:
obj - The object reference which delegated to this delegate.
ctx - The context to be used.
operation - The name of the operation to be invoked.
arg_list - The arguments to the operation in the form of an NVList.
result - A container for the result as a NamedValue.
Returns:
The created Request object.

create_request

public abstract Request create_request(Object obj,
                                       Context ctx,
                                       String operation,
                                       NVList arg_list,
                                       NamedValue result,
                                       ExceptionList exclist,
                                       ContextList ctxlist)
Creates a Request instance for use in the Dynamic Invocation Interface.

Parameters:
obj - The object reference which delegated to this delegate.
ctx - The context to be used.
operation - The name of the operation to be invoked.
arg_list - The arguments to the operation in the form of an NVList.
result - A container for the result as a NamedValue.
exclist - A list of possible exceptions the operation can throw.
ctxlist - A list of context strings that need to be resolved and sent with the Request.
Returns:
The created Request object.

orb

public ORB orb(Object obj)
Provides a reference to the orb associated with its parameter.

Parameters:
obj - the object reference which delegated to this delegate.
Returns:
the associated orb.
See Also:
portable package comments for unimplemented features

get_policy

public Policy get_policy(Object self,
                         int policy_type)
Returns the Policy object of the specified type which applies to this object.

Parameters:
self - The object reference which delegated to this delegate.
policy_type - The type of policy to be obtained.
Returns:
A Policy object of the type specified by the policy_type parameter.
Throws:
BAD_PARAM - raised when the value of policy type is not valid either because the specified type is not supported by this ORB or because a policy object of that type is not associated with this Object.
See Also:
portable package comments for unimplemented features

get_domain_managers

public DomainManager[] get_domain_managers(Object self)
Retrieves the DomainManagers of this object. This allows administration services (and applications) to retrieve the domain managers, and hence the security and other policies applicable to individual objects that are members of the domain.

Parameters:
self - The object reference which delegated to this delegate.
Returns:
The list of immediately enclosing domain managers of this object. At least one domain manager is always returned in the list since by default each object is associated with at least one domain manager at creation.
See Also:
portable package comments for unimplemented features

set_policy_override

public Object set_policy_override(Object self,
                                  Policy[] policies,
                                  SetOverrideType set_add)
Associates the policies passed in with a newly created object reference that it returns. Only certain policies that pertain to the invocation of an operation at the client end can be overridden using this operation. Attempts to override any other policy will result in the raising of the CORBA::NO_PERMISSION exception.

Parameters:
self - The object reference which delegated to this delegate.
policies - A sequence of references to Policy objects.
set_add - Indicates whether these policies should be added onto any otheroverrides that already exist (ADD_OVERRIDE) in the object reference, or they should be added to a clean override free object reference (SET_OVERRIDE).
Returns:
A new object reference with the new policies associated with it.
See Also:
portable package comments for unimplemented features

is_local

public boolean is_local(Object self)
Returns true if this object is implemented by a local servant.

Parameters:
self - The object reference which delegated to this delegate.
Returns:
true only if the servant incarnating this object is located in this Java VM. Return false if the servant is not local or the ORB does not support local stubs for this particular servant. The default behavior of is_local() is to return false.

servant_preinvoke

public ServantObject servant_preinvoke(Object self,
                                       String operation,
                                       Class expectedType)
Returns a Java reference to the servant which should be used for this request. servant_preinvoke() is invoked by a local stub. If a ServantObject object is returned, then its servant field has been set to an object of the expected type (Note: the object may or may not be the actual servant instance). The local stub may cast the servant field to the expected type, and then invoke the operation directly. The ServantRequest object is valid for only one invocation, and cannot be used for more than one invocation.

Parameters:
self - The object reference which delegated to this delegate.
operation - a string containing the operation name. The operation name corresponds to the operation name as it would be encoded in a GIOP request.
expectedType - a Class object representing the expected type of the servant. The expected type is the Class object associated with the operations class of the stub's interface (e.g. A stub for an interface Foo, would pass the Class object for the FooOperations interface).
Returns:
a ServantObject object. The method may return a null value if it does not wish to support this optimization (e.g. due to security, transactions, etc). The method must return null if the servant is not of the expected type.

servant_postinvoke

public void servant_postinvoke(Object self,
                               ServantObject servant)
servant_postinvoke() is invoked by the local stub after the operation has been invoked on the local servant. This method must be called if servant_preinvoke() returned a non-null value, even if an exception was thrown by the servant's method. For this reason, the call to servant_postinvoke() should be placed in a Java finally clause.

Parameters:
self - The object reference which delegated to this delegate.
servant - the instance of the ServantObject returned from the servant_preinvoke() method.

request

public OutputStream request(Object self,
                            String operation,
                            boolean responseExpected)
request is called by a stub to obtain an OutputStream for marshaling arguments. The stub must supply the operation name, and indicate if a response is expected (i.e is this a oneway call).

Parameters:
self - The object reference which delegated to this delegate.
operation - a string containing the operation name. The operation name corresponds to the operation name as it would be encoded in a GIOP request.
responseExpected - false if the operation is a one way operation, and true otherwise.
Returns:
OutputStream the OutputStream into which request arguments can be marshaled.
See Also:
portable package comments for unimplemented features

invoke

public InputStream invoke(Object self,
                          OutputStream output)
                   throws ApplicationException,
                          RemarshalException
invoke is called by a stub to invoke an operation. The stub provides an OutputStream that was previously returned by a request() call. invoke returns an InputStream which contains the marshaled reply. If an exception occurs, invoke may throw an ApplicationException object which contains an InputStream from which the user exception state may be unmarshaled.

Parameters:
self - The object reference which delegated to this delegate.
output - the OutputStream which contains marshaled arguments
Returns:
input the InputStream from which reply parameters can be unmarshaled.
Throws:
ApplicationException - thrown when implementation throws (upon invocation) an exception defined as part of its remote method definition.
RemarshalException - thrown when remarshalling fails.
See Also:
portable package comments for unimplemented features

releaseReply

public void releaseReply(Object self,
                         InputStream input)
releaseReply may optionally be called by a stub to release a reply stream back to the ORB when the unmarshaling has completed. The stub passes the InputStream returned by invoke() or ApplicationException.getInputStream(). A null value may also be passed to releaseReply, in which case the method is a noop.

Parameters:
self - The object reference which delegated to this delegate.
input - the InputStream returned from invoke().
See Also:
portable package comments for unimplemented features

toString

public String toString(Object self)
Provides the implementation to override the toString() method of the delegating CORBA object.

Parameters:
self - the object reference that delegated to this delegate
Returns:
a String object that represents the object reference that delegated to this Delegate object

hashCode

public int hashCode(Object self)
Provides the implementation to override the hashCode() method of the delegating CORBA object.

Parameters:
self - the object reference that delegated to this delegate
Returns:
an int that represents the hashcode for the object reference that delegated to this Delegate object

equals

public boolean equals(Object self,
                      Object obj)
Provides the implementation to override the equals(java.lang.Object obj) method of the delegating CORBA object.

Parameters:
self - the object reference that delegated to this delegate
obj - the Object with which to compare
Returns:
true if obj equals self; false otherwise
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IndirectionException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Class IndirectionException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.portable.IndirectionException
All Implemented Interfaces:
Serializable
public class IndirectionException
extends SystemException

The Indirection exception is a Java specific system exception. It is thrown when the ORB's input stream is called to demarshal a value that is encoded as an indirection that is in the process of being demarshaled. This can occur when the ORB input stream calls the ValueHandler to demarshal an RMI value whose state contains a recursive reference to itself. Because the top-level ValueHandler.read_value() call has not yet returned a value, the ORB input stream's indirection table does not contain an entry for an object with the stream offset specified by the indirection tag. The stream offset is returned in the exception's offset field.

See Also:
InputStream, OutputStream

Field Summary
 int offset
Points to the stream's offset.
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
IndirectionException(int offset)
Creates an IndirectionException with the right offset value.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

offset

public int offset
Points to the stream's offset.

Constructor Detail

IndirectionException

public IndirectionException(int offset)
Creates an IndirectionException with the right offset value. The stream offset is returned in the exception's offset field. This exception is constructed and thrown during reading recursively defined values off of a stream.

Parameters:
offset - the stream offset where recursion is detected.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InputStream

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Class InputStream

java.lang.Object
    extended by  java.io.InputStream
        extended by  org.omg.CORBA.portable.InputStream
All Implemented Interfaces:
Closeable
Direct Known Subclasses:
InputStream
public abstract class InputStream
extends InputStream

InputStream is the Java API for reading IDL types from CDR marshal streams. These methods are used by the ORB to unmarshal IDL types as well as to extract IDL types out of Anys. The _array versions of the methods can be directly used to read sequences and arrays of IDL types.

Since:
JDK1.2

Constructor Summary
InputStream()
Method Summary
ORB | orb() Returns the ORB that created this InputStream.
abstract Any | read_any() Reads an Any from this input stream.
abstract void | read_boolean_array(boolean[] value, int offset, int length) Reads an array of booleans from this input stream.
abstract boolean | read_boolean() Reads a boolean value from this input stream.
abstract void | read_char_array(char[] value, int offset, int length) Reads an array of chars from this input stream.
abstract char | read_char() Reads a char value from this input stream.
Context | read_Context() Reads a CORBA context from the stream.
abstract void | read_double_array(double[] value, int offset, int length) Reads an array of doubles from this input stream.
abstract double | read_double() Reads a double value from this input stream.
BigDecimal | read_fixed() Reads a BigDecimal number.
abstract void | read_float_array(float[] value, int offset, int length) Reads an array of floats from this input stream.
abstract float | read_float() Reads a float value from this input stream.
abstract void | read_long_array(int[] value, int offset, int length) Reads an array of CORBA longs (that is, Java ints) from this input stream.
abstract int | read_long() Reads a CORBA long (that is, Java int) value from this input stream.
abstract void | read_longlong_array(long[] value, int offset, int length) Reads an array of CORBA longlongs (that is, Java longs) from this input stream.
abstract long | read_longlong() Reads a CORBA longlong (that is, Java long) value from this input stream.
abstract Object | read_Object() Reads a CORBA object from this input stream.
Object | read_Object(Class clz) Unmarshals an object and returns a CORBA Object, which is an instance of the class passed as its argument.
abstract void | read_octet_array(byte[] value, int offset, int length) Reads an array of octets (that is, bytes) from this input stream.
abstract byte | read_octet() Reads an octet (that is, a byte) value from this input stream.
Principal | read_Principal() Deprecated. Deprecated by CORBA 2.2.
abstract void | read_short_array(short[] value, int offset, int length) Reads an array of shorts from this input stream.
abstract short | read_short() Reads a short value from this input stream.
abstract String | read_string() Reads a string value from this input stream.
abstract TypeCode | read_TypeCode() Reads a TypeCode from this input stream.
abstract void | read_ulong_array(int[] value, int offset, int length) Reads an array of unsigned CORBA longs (that is, Java ints) from this input stream.
abstract int | read_ulong() Reads an unsigned CORBA long (that is, Java int) value from this input stream.
abstract void | read_ulonglong_array(long[] value, int offset, int length) Reads an array of unsigned CORBA longlongs (that is, Java longs) from this input stream.
abstract long | read_ulonglong() Reads a CORBA unsigned longlong (that is, Java long) value from this input stream.
abstract void | read_ushort_array(short[] value, int offset, int length) Reads an array of unsigned shorts from this input stream.
abstract short | read_ushort() Reads a unsigned short value from this input stream.
abstract void | read_wchar_array(char[] value, int offset, int length) Reads an array of wide chars from this input stream.
abstract char | read_wchar() Reads a wide char value from this input stream.
abstract String | read_wstring() Reads a wide string value from this input stream.
int | read() Reads the next byte of data from the input stream.
Methods inherited from class java.io.InputStream
available, close, mark, markSupported, read, read, reset, skip
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InputStream

public InputStream()
Method Detail

read_boolean

public abstract boolean read_boolean()
Reads a boolean value from this input stream.

Returns:
the boolean value read from this input stream

read_char

public abstract char read_char()
Reads a char value from this input stream.

Returns:
the char value read from this input stream

read_wchar

public abstract char read_wchar()
Reads a wide char value from this input stream.

Returns:
the char value read from this input stream

read_octet

public abstract byte read_octet()
Reads an octet (that is, a byte) value from this input stream.

Returns:
the byte value read from this input stream

read_short

public abstract short read_short()
Reads a short value from this input stream.

Returns:
the short value read from this input stream

read_ushort

public abstract short read_ushort()
Reads a unsigned short value from this input stream.

Returns:
the short value read from this input stream

read_long

public abstract int read_long()
Reads a CORBA long (that is, Java int) value from this input stream.

Returns:
the int value read from this input stream

read_ulong

public abstract int read_ulong()
Reads an unsigned CORBA long (that is, Java int) value from this input stream.

Returns:
the int value read from this input stream

read_longlong

public abstract long read_longlong()
Reads a CORBA longlong (that is, Java long) value from this input stream.

Returns:
the long value read from this input stream

read_ulonglong

public abstract long read_ulonglong()
Reads a CORBA unsigned longlong (that is, Java long) value from this input stream.

Returns:
the long value read from this input stream

read_float

public abstract float read_float()
Reads a float value from this input stream.

Returns:
the float value read from this input stream

read_double

public abstract double read_double()
Reads a double value from this input stream.

Returns:
the double value read from this input stream

read_string

public abstract String read_string()
Reads a string value from this input stream.

Returns:
the String value read from this input stream

read_wstring

public abstract String read_wstring()
Reads a wide string value from this input stream.

Returns:
the String value read from this input stream

read_boolean_array

public abstract void read_boolean_array(boolean[] value,
                                        int offset,
                                        int length)
Reads an array of booleans from this input stream.

Parameters:
value - returned array of booleans.
offset - offset on the stream.
length - length of buffer to read.

read_char_array

public abstract void read_char_array(char[] value,
                                     int offset,
                                     int length)
Reads an array of chars from this input stream.

Parameters:
value - returned array of chars.
offset - offset on the stream.
length - length of buffer to read.

read_wchar_array

public abstract void read_wchar_array(char[] value,
                                      int offset,
                                      int length)
Reads an array of wide chars from this input stream.

Parameters:
value - returned array of wide chars.
offset - offset on the stream.
length - length of buffer to read.

read_octet_array

public abstract void read_octet_array(byte[] value,
                                      int offset,
                                      int length)
Reads an array of octets (that is, bytes) from this input stream.

Parameters:
value - returned array of octets (that is, bytes).
offset - offset on the stream.
length - length of buffer to read.

read_short_array

public abstract void read_short_array(short[] value,
                                      int offset,
                                      int length)
Reads an array of shorts from this input stream.

Parameters:
value - returned array of shorts.
offset - offset on the stream.
length - length of buffer to read.

read_ushort_array

public abstract void read_ushort_array(short[] value,
                                       int offset,
                                       int length)
Reads an array of unsigned shorts from this input stream.

Parameters:
value - returned array of shorts.
offset - offset on the stream.
length - length of buffer to read.

read_long_array

public abstract void read_long_array(int[] value,
                                     int offset,
                                     int length)
Reads an array of CORBA longs (that is, Java ints) from this input stream.

Parameters:
value - returned array of CORBA longs (that is, Java ints).
offset - offset on the stream.
length - length of buffer to read.

read_ulong_array

public abstract void read_ulong_array(int[] value,
                                      int offset,
                                      int length)
Reads an array of unsigned CORBA longs (that is, Java ints) from this input stream.

Parameters:
value - returned array of CORBA longs (that is, Java ints).
offset - offset on the stream.
length - length of buffer to read.

read_longlong_array

public abstract void read_longlong_array(long[] value,
                                         int offset,
                                         int length)
Reads an array of CORBA longlongs (that is, Java longs) from this input stream.

Parameters:
value - returned array of CORBA longs (that is, Java longs).
offset - offset on the stream.
length - length of buffer to read.

read_ulonglong_array

public abstract void read_ulonglong_array(long[] value,
                                          int offset,
                                          int length)
Reads an array of unsigned CORBA longlongs (that is, Java longs) from this input stream.

Parameters:
value - returned array of CORBA longs (that is, Java longs).
offset - offset on the stream.
length - length of buffer to read.

read_float_array

public abstract void read_float_array(float[] value,
                                      int offset,
                                      int length)
Reads an array of floats from this input stream.

Parameters:
value - returned array of floats.
offset - offset on the stream.
length - length of buffer to read.

read_double_array

public abstract void read_double_array(double[] value,
                                       int offset,
                                       int length)
Reads an array of doubles from this input stream.

Parameters:
value - returned array of doubles.
offset - offset on the stream.
length - length of buffer to read.

read_Object

public abstract Object read_Object()
Reads a CORBA object from this input stream.

Returns:
the Object instance read from this input stream.

read_TypeCode

public abstract TypeCode read_TypeCode()
Reads a TypeCode from this input stream.

Returns:
the TypeCode instance read from this input stream.

read_any

public abstract Any read_any()
Reads an Any from this input stream.

Returns:
the Any instance read from this input stream.

read_Principal

@Deprecated
public Principal read_Principal()
Deprecated. Deprecated by CORBA 2.2.

Returns principal for invocation.

Returns:
Principal for invocation.

read

public int read()
         throws IOException
Description copied from class: InputStream
Reads the next byte of data from the input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.

A subclass must provide an implementation of this method.

Specified by:
read in class InputStream
Returns:
the next byte of data, or -1 if the end of the stream is reached.
Throws:
IOException - if an I/O error occurs.
See Also:
portable package comments for unimplemented features

read_fixed

public BigDecimal read_fixed()
Reads a BigDecimal number.

Returns:
a java.math.BigDecimal number

read_Context

public Context read_Context()
Reads a CORBA context from the stream.

Returns:
a CORBA context
See Also:
portable package comments for unimplemented features

read_Object

public Object read_Object(Class clz)
Unmarshals an object and returns a CORBA Object, which is an instance of the class passed as its argument. This class is the stub class of the expected type.

Parameters:
clz - The Class object for the stub class which corresponds to the type that is statistically expected, or the Class object for the RMI/IDL interface type that is statistically expected.
Returns:
an Object instance of clz read from this stream
See Also:
portable package comments for unimplemented features

orb

public ORB orb()
Returns the ORB that created this InputStream.

Returns:
the ORB object that created this stream
See Also:
portable package comments for unimplemented features
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectImpl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Class ObjectImpl

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
All Implemented Interfaces:
Object
Direct Known Subclasses:
_BindingIteratorStub, _DynAnyFactoryStub, _DynAnyStub, _DynArrayStub, _DynEnumStub, _DynFixedStub, _DynSequenceStub, _DynStructStub, _DynUnionStub, _DynValueStub, _IDLTypeStub, _NamingContextExtStub, _NamingContextStub, _PolicyStub, _ServantActivatorStub, _ServantLocatorStub, DynamicImplementation, ObjectImpl
public abstract class ObjectImpl
extends Object
implements Object

The common base class for all stub classes; provides default implementations of the org.omg.CORBA.Object methods. All method implementations are forwarded to a Delegate object stored in the ObjectImpl instance. ObjectImpl allows for portable stubs because the Delegate can be implemented by a different vendor-specific ORB.

Constructor Summary
ObjectImpl()
Method Summary
Request | _create_request(Context ctx, String operation, NVList arg_list, NamedValue result) Creates a Request object that contains the given context, method, argument list, and container for the result.
Request | _create_request(Context ctx, String operation, NVList arg_list, NamedValue result, ExceptionList exceptions, ContextList contexts) Creates a Request object that contains the given context, method, argument list, container for the result, exceptions, and list of property names to be used in resolving the context strings.
Object | _duplicate() Returns a duplicate of this ObjectImpl object.
Delegate | _get_delegate() Retrieves the reference to the vendor-specific Delegate object to which this ObjectImpl object delegates all methods invoked on it.
DomainManager[] | _get_domain_managers() Retrieves a list of the domain managers for this ObjectImpl object.
Object | _get_interface_def() Retrieves the interface definition for this ObjectImpl object.
Policy | _get_policy(int policy_type) Retrieves the Policy object for this ObjectImpl object that has the given policy type.
int | _hash(int maximum) Retrieves the hash code that serves as an ORB-internal identifier for this ObjectImpl object.
abstract String[] | _ids() Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
InputStream | _invoke(OutputStream output) Invokes an operation and returns an InputStream object for reading the response.
boolean | _is_a(String repository_id) Checks whether the object identified by the given repository identifier is an ObjectImpl object.
boolean | _is_equivalent(Object that) Checks whether the the given ObjectImpl object is equivalent to this ObjectImpl object.
boolean | _is_local() Checks whether this ObjectImpl object is implemented by a local servant.
boolean | _non_existent() Checks whether the server object for this ObjectImpl object has been destroyed.
ORB | _orb() Returns a reference to the ORB associated with this object and its delegate.
void | _release() Releases the resources associated with this ObjectImpl object.
void | _releaseReply(InputStream input) Releases the given reply stream back to the ORB when unmarshalling has completed after a call to the method _invoke.
Request | _request(String operation) Creates a Request object containing the given method that can be used with the Dynamic Invocation Interface.
OutputStream | _request(String operation, boolean responseExpected) Returns an OutputStream object to use for marshalling the arguments of the given method.
void | _servant_postinvoke(ServantObject servant) Is called by the local stub after it has invoked an operation on the local servant that was previously retrieved from a call to the method _servant_preinvoke.
ServantObject | _servant_preinvoke(String operation, Class expectedType) Returns a Java reference to the local servant that should be used for sending a request for the method specified.
void | _set_delegate(Delegate delegate) Sets the Delegate for this ObjectImpl instance to the given Delegate object.
Object | _set_policy_override(Policy[] policies, SetOverrideType set_add) Sets this ObjectImpl object's override type for the given policies to the given instance of SetOverrideType.
boolean | equals(Object obj) Compares this ObjectImpl object with the given one for equality.
int | hashCode() Returns the hash code for this ObjectImpl object.
String | toString() Returns a String object that represents this ObjectImpl object.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ObjectImpl

public ObjectImpl()
Method Detail

_get_delegate

public Delegate _get_delegate()
Retrieves the reference to the vendor-specific Delegate object to which this ObjectImpl object delegates all methods invoked on it.

Returns:
the Delegate contained in this ObjectImpl instance
Throws:
BAD_OPERATION - if the delegate has not been set
See Also:
_set_delegate(org.omg.CORBA.portable.Delegate)

_set_delegate

public void _set_delegate(Delegate delegate)
Sets the Delegate for this ObjectImpl instance to the given Delegate object. All method invocations on this ObjectImpl object will be forwarded to this delegate.

Parameters:
delegate - the Delegate instance to which all method calls on this ObjectImpl object will be delegated; may be implemented by a third-party ORB
See Also:
_get_delegate()

_ids

public abstract String[] _ids()
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Returns:
the array of all repository identifiers supported by this ObjectImpl instance

_duplicate

public Object _duplicate()
Returns a duplicate of this ObjectImpl object.

Specified by:
_duplicate in interface Object
Returns:
an orb.omg.CORBA.Object object that is a duplicate of this object

_release

public void _release()
Releases the resources associated with this ObjectImpl object.

Specified by:
_release in interface Object

_is_a

public boolean _is_a(String repository_id)
Checks whether the object identified by the given repository identifier is an ObjectImpl object.

Specified by:
_is_a in interface Object
Parameters:
repository_id - a String object with the repository identifier to check
Returns:
true if the object identified by the given repository id is an instance of ObjectImpl; false otherwise

_is_equivalent

public boolean _is_equivalent(Object that)
Checks whether the the given ObjectImpl object is equivalent to this ObjectImpl object.

Specified by:
_is_equivalent in interface Object
Parameters:
that - an instance of ObjectImpl to compare with this ObjectImpl object
Returns:
true if the given object is equivalent to this ObjectImpl object; false otherwise

_non_existent

public boolean _non_existent()
Checks whether the server object for this ObjectImpl object has been destroyed.

Specified by:
_non_existent in interface Object
Returns:
true if the ORB knows authoritatively that the server object does not exist; false otherwise

_hash

public int _hash(int maximum)
Retrieves the hash code that serves as an ORB-internal identifier for this ObjectImpl object.

Specified by:
_hash in interface Object
Parameters:
maximum - an int indicating the upper bound on the hash value returned by the ORB
Returns:
an int representing the hash code for this ObjectImpl object

_request

public Request _request(String operation)
Creates a Request object containing the given method that can be used with the Dynamic Invocation Interface.

Specified by:
_request in interface Object
Parameters:
operation - the method to be invoked by the new Request object
Returns:
a new Request object initialized with the given method

_create_request

public Request _create_request(Context ctx,
                               String operation,
                               NVList arg_list,
                               NamedValue result)
Creates a Request object that contains the given context, method, argument list, and container for the result.

Specified by:
_create_request in interface Object
Parameters:
ctx - the Context for the request
operation - the method that the new Request object will invoke
arg_list - the arguments for the method; an NVList in which each argument is a NamedValue object
result - a NamedValue object to be used for returning the result of executing the request's method
Returns:
a new Request object initialized with the given context, method, argument list, and container for the return value
See Also:
Request, NVList, NamedValue

_create_request

public Request _create_request(Context ctx,
                               String operation,
                               NVList arg_list,
                               NamedValue result,
                               ExceptionList exceptions,
                               ContextList contexts)
Creates a Request object that contains the given context, method, argument list, container for the result, exceptions, and list of property names to be used in resolving the context strings. This Request object is for use in the Dynamic Invocation Interface.

Specified by:
_create_request in interface Object
Parameters:
ctx - the Context object that contains the context strings that must be resolved before they are sent along with the request
operation - the method that the new Request object will invoke
arg_list - the arguments for the method; an NVList in which each argument is a NamedValue object
result - a NamedValue object to be used for returning the result of executing the request's method
exceptions - a list of the exceptions that the given method throws
contexts - a list of the properties that are needed to resolve the contexts in ctx; the strings in contexts are used as arguments to the method Context.get_values, which returns the value associated with the given property
Returns:
a new Request object initialized with the given context strings to resolve, method, argument list, container for the result, exceptions, and list of property names to be used in resolving the context strings
See Also:
Request, NVList, NamedValue, ExceptionList, ContextList

_get_interface_def

public Object _get_interface_def()
Retrieves the interface definition for this ObjectImpl object.

Specified by:
_get_interface_def in interface Object
Returns:
the org.omg.CORBA.Object instance that is the interface definition for this ObjectImpl object

_orb

public ORB _orb()
Returns a reference to the ORB associated with this object and its delegate. This is the ORB object that created the delegate.

Returns:
the ORB instance that created the Delegate object contained in this ObjectImpl object

_get_policy

public Policy _get_policy(int policy_type)
Retrieves the Policy object for this ObjectImpl object that has the given policy type.

Specified by:
_get_policy in interface Object
Parameters:
policy_type - an int indicating the policy type
Returns:
the Policy object that is the specified policy type and that applies to this ObjectImpl object
See Also:
PolicyOperations.policy_type()

_get_domain_managers

public DomainManager[] _get_domain_managers()
Retrieves a list of the domain managers for this ObjectImpl object.

Specified by:
_get_domain_managers in interface Object
Returns:
an array containing the DomainManager objects for this instance of ObjectImpl

_set_policy_override

public Object _set_policy_override(Policy[] policies,
                                   SetOverrideType set_add)
Sets this ObjectImpl object's override type for the given policies to the given instance of SetOverrideType.

Specified by:
_set_policy_override in interface Object
Parameters:
policies - an array of Policy objects with the policies that will replace the current policies or be added to the current policies
set_add - either SetOverrideType.SET_OVERRIDE, indicating that the given policies will replace any existing ones, or SetOverrideType.ADD_OVERRIDE, indicating that the given policies should be added to any existing ones
Returns:
an Object with the given policies replacing or added to its previous policies

_is_local

public boolean _is_local()
Checks whether this ObjectImpl object is implemented by a local servant. If so, local invocation API's may be used.

Returns:
true if this object is implemented by a local servant; false otherwise

_servant_preinvoke

public ServantObject _servant_preinvoke(String operation,
                                        Class expectedType)
Returns a Java reference to the local servant that should be used for sending a request for the method specified. If this ObjectImpl object is a local stub, it will invoke the _servant_preinvoke method before sending a request in order to obtain the ServantObject instance to use.

If a ServantObject object is returned, its servant field has been set to an object of the expected type (Note: the object may or may not be the actual servant instance). The local stub may cast the servant field to the expected type, and then invoke the operation directly. The ServantRequest object is valid for only one invocation and cannot be used for more than one invocation.

Parameters:
operation - a String containing the name of the method to be invoked. This name should correspond to the method name as it would be encoded in a GIOP request.
expectedType - a Class object representing the expected type of the servant that is returned. This expected type is the Class object associated with the operations class for the stub's interface. For example, a stub for an interface Foo would pass the Class object for the FooOperations interface.
Returns:
(1) a ServantObject object, which may or may not be the actual servant instance, or (2) null if (a) the servant is not local or (b) the servant has ceased to be local due to a ForwardRequest from a POA ServantManager
Throws:
BAD_PARAM - if the servant is not the expected type

_servant_postinvoke

public void _servant_postinvoke(ServantObject servant)
Is called by the local stub after it has invoked an operation on the local servant that was previously retrieved from a call to the method _servant_preinvoke. The _servant_postinvoke method must be called if the _servant_preinvoke method returned a non-null value, even if an exception was thrown by the method invoked by the servant. For this reason, the call to the method _servant_postinvoke should be placed in a Java finally clause.

Parameters:
servant - the instance of the ServantObject returned by the _servant_preinvoke method

_request

public OutputStream _request(String operation,
                             boolean responseExpected)
Returns an OutputStream object to use for marshalling the arguments of the given method. This method is called by a stub, which must indicate if a response is expected, that is, whether or not the call is oneway.

Parameters:
operation - a String giving the name of the method.
responseExpected - a boolean -- true if the request is not one way, that is, a response is expected
Returns:
an OutputStream object for dispatching the request

_invoke

public InputStream _invoke(OutputStream output)
                    throws ApplicationException,
                           RemarshalException
Invokes an operation and returns an InputStream object for reading the response. The stub provides the OutputStream object that was previously returned by a call to the _request method. The method specified as an argument to _request when it was called previously is the method that this method invokes.

If an exception occurs, the _invoke method may throw an ApplicationException object that contains an InputStream from which the user exception state may be unmarshalled.

Parameters:
output - an OutputStream object for dispatching the request
Returns:
an InputStream object containing the marshalled response to the method invoked
Throws:
ApplicationException - if the invocation meets application-defined exception
RemarshalException - if the invocation leads to a remarshalling error
See Also:
_request(java.lang.String)

_releaseReply

public void _releaseReply(InputStream input)
Releases the given reply stream back to the ORB when unmarshalling has completed after a call to the method _invoke. Calling this method is optional for the stub.

Parameters:
input - the InputStream object that was returned by the _invoke method or the ApplicationException.getInputStream method; may be null, in which case this method does nothing
See Also:
_invoke(org.omg.CORBA.portable.OutputStream)

toString

public String toString()
Returns a String object that represents this ObjectImpl object.

Overrides:
toString in class Object
Returns:
the String representation of this object

hashCode

public int hashCode()
Returns the hash code for this ObjectImpl object.

Overrides:
hashCode in class Object
Returns:
the hash code for this object
See Also:
Object.equals(java.lang.Object), Hashtable

equals

public boolean equals(Object obj)
Compares this ObjectImpl object with the given one for equality.

Overrides:
equals in class Object
Parameters:
obj - the object with which to compare this object
Returns:
true if the two objects are equal; false otherwise
See Also:
Object.hashCode(), Hashtable
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OutputStream

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Class OutputStream

java.lang.Object
    extended by  java.io.OutputStream
        extended by  org.omg.CORBA.portable.OutputStream
All Implemented Interfaces:
Closeable, Flushable
Direct Known Subclasses:
OutputStream
public abstract class OutputStream
extends OutputStream

OuputStream is the Java API for writing IDL types to CDR marshal streams. These methods are used by the ORB to marshal IDL types as well as to insert IDL types into Anys. The _array versions of the methods can be directly used to write sequences and arrays of IDL types.

Since:
JDK1.2

Constructor Summary
OutputStream()
Method Summary
abstract InputStream | create_input_stream() Returns an input stream with the same buffer.
ORB | orb() Returns the ORB that created this OutputStream.
abstract void | write_any(Any value) Writes an Any on this output stream.
abstract void | write_boolean_array(boolean[] value, int offset, int length) Writes an array of booleans on this output stream.
abstract void | write_boolean(boolean value) Writes a boolean value to this stream.
abstract void | write_char_array(char[] value, int offset, int length) Writes an array of chars on this output stream.
abstract void | write_char(char value) Writes a char value to this stream.
void | write_Context(Context ctx, ContextList contexts) Writes a CORBA context on this stream.
abstract void | write_double_array(double[] value, int offset, int length) Writes an array of doubles on this output stream.
abstract void | write_double(double value) Writes a double value to this stream.
void | write_fixed(BigDecimal value) Writes a BigDecimal number.
abstract void | write_float_array(float[] value, int offset, int length) Writes an array of floats on this output stream.
abstract void | write_float(float value) Writes a float value to this stream.
abstract void | write_long_array(int[] value, int offset, int length) Writes an array of CORBA longs (i.e.
abstract void | write_long(int value) Writes a CORBA long (i.e.
abstract void | write_longlong_array(long[] value, int offset, int length) Writes an array of CORBA longlongs (i.e.
abstract void | write_longlong(long value) Writes a CORBA longlong (i.e.
abstract void | write_Object(Object value) Writes a CORBA Object on this output stream.
abstract void | write_octet_array(byte[] value, int offset, int length) Writes an array of CORBA octets (bytes) on this output stream.
abstract void | write_octet(byte value) Writes a CORBA octet (i.e.
void | write_Principal(Principal value) Deprecated. Deprecated by CORBA 2.2.
abstract void | write_short_array(short[] value, int offset, int length) Writes an array of shorts on this output stream.
abstract void | write_short(short value) Writes a short value to this stream.
abstract void | write_string(String value) Writes a string value to this stream.
abstract void | write_TypeCode(TypeCode value) Writes a TypeCode on this output stream.
abstract void | write_ulong_array(int[] value, int offset, int length) Writes an array of unsigned CORBA longs (i.e.
abstract void | write_ulong(int value) Writes an unsigned CORBA long (i.e.
abstract void | write_ulonglong_array(long[] value, int offset, int length) Writes an array of unsigned CORBA longlongs (i.e.
abstract void | write_ulonglong(long value) Writes an unsigned CORBA longlong (i.e.
abstract void | write_ushort_array(short[] value, int offset, int length) Writes an array of unsigned shorts on this output stream.
abstract void | write_ushort(short value) Writes an unsigned short value to this stream.
abstract void | write_wchar_array(char[] value, int offset, int length) Writes an array of wide chars on this output stream.
abstract void | write_wchar(char value) Writes a wide char value to this stream.
abstract void | write_wstring(String value) Writes a wide string value to this stream.
void | write(int b) Writes an integer (length of arrays) onto this stream.
Methods inherited from class java.io.OutputStream
close, flush, write, write
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

OutputStream

public OutputStream()
Method Detail

create_input_stream

public abstract InputStream create_input_stream()
Returns an input stream with the same buffer.

Returns:
an input stream with the same buffer.

write_boolean

public abstract void write_boolean(boolean value)
Writes a boolean value to this stream.

Parameters:
value - the value to be written.

write_char

public abstract void write_char(char value)
Writes a char value to this stream.

Parameters:
value - the value to be written.

write_wchar

public abstract void write_wchar(char value)
Writes a wide char value to this stream.

Parameters:
value - the value to be written.

write_octet

public abstract void write_octet(byte value)
Writes a CORBA octet (i.e. byte) value to this stream.

Parameters:
value - the value to be written.

write_short

public abstract void write_short(short value)
Writes a short value to this stream.

Parameters:
value - the value to be written.

write_ushort

public abstract void write_ushort(short value)
Writes an unsigned short value to this stream.

Parameters:
value - the value to be written.

write_long

public abstract void write_long(int value)
Writes a CORBA long (i.e. Java int) value to this stream.

Parameters:
value - the value to be written.

write_ulong

public abstract void write_ulong(int value)
Writes an unsigned CORBA long (i.e. Java int) value to this stream.

Parameters:
value - the value to be written.

write_longlong

public abstract void write_longlong(long value)
Writes a CORBA longlong (i.e. Java long) value to this stream.

Parameters:
value - the value to be written.

write_ulonglong

public abstract void write_ulonglong(long value)
Writes an unsigned CORBA longlong (i.e. Java long) value to this stream.

Parameters:
value - the value to be written.

write_float

public abstract void write_float(float value)
Writes a float value to this stream.

Parameters:
value - the value to be written.

write_double

public abstract void write_double(double value)
Writes a double value to this stream.

Parameters:
value - the value to be written.

write_string

public abstract void write_string(String value)
Writes a string value to this stream.

Parameters:
value - the value to be written.

write_wstring

public abstract void write_wstring(String value)
Writes a wide string value to this stream.

Parameters:
value - the value to be written.

write_boolean_array

public abstract void write_boolean_array(boolean[] value,
                                         int offset,
                                         int length)
Writes an array of booleans on this output stream.

Parameters:
value - the array to be written.
offset - offset on the stream.
length - length of buffer to write.

write_char_array

public abstract void write_char_array(char[] value,
                                      int offset,
                                      int length)
Writes an array of chars on this output stream.

Parameters:
value - the array to be written.
offset - offset on the stream.
length - length of buffer to write.

write_wchar_array

public abstract void write_wchar_array(char[] value,
                                       int offset,
                                       int length)
Writes an array of wide chars on this output stream.

Parameters:
value - the array to be written.
offset - offset on the stream.
length - length of buffer to write.

write_octet_array

public abstract void write_octet_array(byte[] value,
                                       int offset,
                                       int length)
Writes an array of CORBA octets (bytes) on this output stream.

Parameters:
value - the array to be written.
offset - offset on the stream.
length - length of buffer to write.

write_short_array

public abstract void write_short_array(short[] value,
                                       int offset,
                                       int length)
Writes an array of shorts on this output stream.

Parameters:
value - the array to be written.
offset - offset on the stream.
length - length of buffer to write.

write_ushort_array

public abstract void write_ushort_array(short[] value,
                                        int offset,
                                        int length)
Writes an array of unsigned shorts on this output stream.

Parameters:
value - the array to be written.
offset - offset on the stream.
length - length of buffer to write.

write_long_array

public abstract void write_long_array(int[] value,
                                      int offset,
                                      int length)
Writes an array of CORBA longs (i.e. Java ints) on this output stream.

Parameters:
value - the array to be written.
offset - offset on the stream.
length - length of buffer to write.

write_ulong_array

public abstract void write_ulong_array(int[] value,
                                       int offset,
                                       int length)
Writes an array of unsigned CORBA longs (i.e. Java ints) on this output stream.

Parameters:
value - the array to be written.
offset - offset on the stream.
length - length of buffer to write.

write_longlong_array

public abstract void write_longlong_array(long[] value,
                                          int offset,
                                          int length)
Writes an array of CORBA longlongs (i.e. Java longs) on this output stream.

Parameters:
value - the array to be written.
offset - offset on the stream.
length - length of buffer to write.

write_ulonglong_array

public abstract void write_ulonglong_array(long[] value,
                                           int offset,
                                           int length)
Writes an array of unsigned CORBA longlongs (i.e. Java ints) on this output stream.

Parameters:
value - the array to be written.
offset - offset on the stream.
length - length of buffer to write.

write_float_array

public abstract void write_float_array(float[] value,
                                       int offset,
                                       int length)
Writes an array of floats on this output stream.

Parameters:
value - the array to be written.
offset - offset on the stream.
length - length of buffer to write.

write_double_array

public abstract void write_double_array(double[] value,
                                        int offset,
                                        int length)
Writes an array of doubles on this output stream.

Parameters:
value - the array to be written.
offset - offset on the stream.
length - length of buffer to write.

write_Object

public abstract void write_Object(Object value)
Writes a CORBA Object on this output stream.

Parameters:
value - the value to be written.

write_TypeCode

public abstract void write_TypeCode(TypeCode value)
Writes a TypeCode on this output stream.

Parameters:
value - the value to be written.

write_any

public abstract void write_any(Any value)
Writes an Any on this output stream.

Parameters:
value - the value to be written.

write_Principal

@Deprecated
public void write_Principal(Principal value)
Deprecated. Deprecated by CORBA 2.2.

Writes a Principle on this output stream.

Parameters:
value - the value to be written.

write

public void write(int b)
           throws IOException
Writes an integer (length of arrays) onto this stream.

Specified by:
write in class OutputStream
Parameters:
b - the value to be written.
Throws:
IOException - if there is an input/output error
See Also:
portable package comments for unimplemented features

write_fixed

public void write_fixed(BigDecimal value)
Writes a BigDecimal number.

Parameters:
value - a BidDecimal--value to be written.

write_Context

public void write_Context(Context ctx,
                          ContextList contexts)
Writes a CORBA context on this stream. The Context is marshaled as a sequence of strings. Only those Context values specified in the contexts parameter are actually written.

Parameters:
ctx - a CORBA context
contexts - a ContextList object containing the list of contexts to be written
See Also:
portable package comments for unimplemented features

orb

public ORB orb()
Returns the ORB that created this OutputStream.

Returns:
the ORB that created this OutputStream
See Also:
portable package comments for unimplemented features
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RemarshalException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Class RemarshalException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.portable.RemarshalException
All Implemented Interfaces:
Serializable
public final class RemarshalException
extends Exception

This class is used for reporting locate forward exceptions and object forward GIOP messages back to the ORB. In this case the ORB must remarshal the request before trying again. Stubs which use the stream-based model shall catch the RemarshalException which is potentially thrown from the _invoke() method of ObjectImpl. Upon catching the exception, the stub shall immediately remarshal the request by calling _request(), marshalling the arguments (if any), and then calling _invoke(). The stub shall repeat this process until _invoke() returns normally or raises some exception other than RemarshalException.

Constructor Summary
RemarshalException()
Constructs a RemarshalException.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RemarshalException

public RemarshalException()
Constructs a RemarshalException.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ResponseHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Interface ResponseHandler

public interface ResponseHandler

This interface is supplied by an ORB to a servant at invocation time and allows the servant to later retrieve an OutputStream for returning the invocation results.

Method Summary
OutputStream | createExceptionReply() Called by the servant during a method invocation.
OutputStream | createReply() Called by the servant during a method invocation.

Method Detail

createReply

OutputStream createReply()
Called by the servant during a method invocation. The servant should call this method to create a reply marshal buffer if no exception occurred.

Returns:
an OutputStream suitable for marshalling the reply.
See Also:
portable package comments for unimplemented features

createExceptionReply

OutputStream createExceptionReply()
Called by the servant during a method invocation. The servant should call this method to create a reply marshal buffer if a user exception occurred.

Returns:
an OutputStream suitable for marshalling the exception ID and the user exception body.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantObject

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Class ServantObject

java.lang.Object
    extended by  org.omg.CORBA.portable.ServantObject

public class ServantObject
extends Object

This class is part of the local stub API, the purpose of which is to provide high performance calls for collocated clients and servers (i.e. clients and servers residing in the same Java VM). The local stub API is supported via three additional methods on ObjectImpl and Delegate. ORB vendors may subclass this class to return additional request state that may be required by their implementations.

See Also:
ObjectImpl, Delegate

Field Summary
 Object servant
The real servant.
Constructor Summary
ServantObject()
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

servant

public Object servant
The real servant. The local stub may cast this field to the expected type, and then invoke the operation directly. Note, the object may or may not be the actual servant instance.

Constructor Detail

ServantObject

public ServantObject()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UnknownException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Class UnknownException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.portable.UnknownException
All Implemented Interfaces:
Serializable
public class UnknownException
extends SystemException

The org.omg.CORBA.portable.UnknownException is used for reporting unknown exceptions between ties and ORBs and between ORBs and stubs. It provides a Java representation of an UNKNOWN system exception that has an UnknownExceptionInfo service context. If the CORBA system exception org.omg.CORBA.portable.UnknownException is thrown, then the stub does one of the following: (1) Translates it to org.omg.CORBA.UNKNOWN. (2) Translates it to the nested exception that the UnknownException contains. (3) Passes it on directly to the user.

Field Summary
 Throwable originalEx
A throwable--the original exception that was wrapped in a CORBA UnknownException.
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
UnknownException(Throwable ex)
Constructs an UnknownException object.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

originalEx

public Throwable originalEx
A throwable--the original exception that was wrapped in a CORBA UnknownException.

Constructor Detail

UnknownException

public UnknownException(Throwable ex)
Constructs an UnknownException object.

Parameters:
ex - a Throwable object--to be wrapped in this exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ValueFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Interface ValueFactory

public interface ValueFactory

The ValueFactory interface is the native mapping for the IDL type CORBA::ValueFactory. The read_value() method is called by the ORB runtime while in the process of unmarshaling a value type. A user shall implement this method as part of implementing a type specific value factory. In the implementation, the user shall call is.read_value(java.io.Serializable) with a uninitialized valuetype to use for unmarshaling. The value returned by the stream is the same value passed in, with all the data unmarshaled.

See Also:
ORB

Method Summary
 Serializable read_value(InputStream is)
Is called by the ORB runtime while in the process of unmarshaling a value type.

Method Detail

read_value

Serializable read_value(InputStream is)
Is called by the ORB runtime while in the process of unmarshaling a value type. A user shall implement this method as part of implementing a type specific value factory.

Parameters:
is - an InputStream object--from which the value will be read.
Returns:
a Serializable object--the value read off of "is" Input stream.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ValueInputStream

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Interface ValueInputStream

public interface ValueInputStream

Java to IDL ptc 02-01-12 1.5.1.4 ValueInputStream is used for implementing RMI-IIOP stream format version 2.

Method Summary
void | end_value() The end_value method reads the end tag for the nested custom valuetype (after skipping any data that precedes the end tag) and decrements the valuetype nesting depth.
void | start_value() The start_value method reads a valuetype header for a nested custom valuetype and increments the valuetype nesting depth.

Method Detail

start_value

void start_value()
The start_value method reads a valuetype header for a nested custom valuetype and increments the valuetype nesting depth.

end_value

void end_value()
The end_value method reads the end tag for the nested custom valuetype (after skipping any data that precedes the end tag) and decrements the valuetype nesting depth.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ValueOutputStream

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.portable
Interface ValueOutputStream

public interface ValueOutputStream

Java to IDL ptc 02-01-12 1.5.1.3 ValueOutputStream is used for implementing RMI-IIOP stream format version 2.

Method Summary
void | end_value() The end_value method ends any currently open chunk, writes the end tag for the nested custom valuetype, and decrements the valuetype nesting depth.
void | start_value(String rep_id) The start_value method ends any currently open chunk, writes a valuetype header for a nested custom valuetype (with a null codebase and the specified repository ID), and increments the valuetype nesting depth.

Method Detail

start_value

void start_value(String rep_id)
The start_value method ends any currently open chunk, writes a valuetype header for a nested custom valuetype (with a null codebase and the specified repository ID), and increments the valuetype nesting depth.

end_value

void end_value()
The end_value method ends any currently open chunk, writes the end tag for the nested custom valuetype, and decrements the valuetype nesting depth.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Principal

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class Principal

java.lang.Object
    extended by  org.omg.CORBA.Principal
Deprecated. Deprecated by CORBA 2.2.

@Deprecated
public class Principal
extends Object

A class that contains information about the identity of the client, for access control and other purposes. It contains a single attribute, the name of the Principal, encoded as a sequence of bytes.

Constructor Summary
Principal()
Deprecated.
Method Summary
byte[] | name() Deprecated. Deprecated by CORBA 2.2.
void | name(byte[] value) Deprecated. Deprecated by CORBA 2.2.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Principal

public Principal()
Deprecated.
Method Detail

name

@Deprecated
public void name(byte[] value)
Deprecated. Deprecated by CORBA 2.2.

Sets the name of this Principal object to the given value.

Parameters:
value - the value to be set in the Principal

name

@Deprecated
public byte[] name()
Deprecated. Deprecated by CORBA 2.2.

Gets the name of this Principal object.

Returns:
the name of this Principal object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrincipalHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class PrincipalHolder

java.lang.Object
    extended by  org.omg.CORBA.PrincipalHolder
All Implemented Interfaces:
Streamable
Deprecated. Deprecated by CORBA 2.2.

@Deprecated
public final class PrincipalHolder
extends Object
implements Streamable

The Holder for Principal. For more information on Holder files, see "Generated Files: Holder Files".

A container class for values of type Principal that is used to store "out" and "inout" parameters in IDL methods. If an IDL method signature has an IDL Principal as an "out" or "inout" parameter, the programmer must pass an instance of PrincipalHolder as the corresponding parameter in the method invocation; for "inout" parameters, the programmer must also fill the "in" value to be sent to the server. Before the method invocation returns, the ORB will fill in the value corresponding to the "out" value returned from the server.

If myPrincipalHolder is an instance of PrincipalHolder, the value stored in its value field can be accessed with myPrincipalHolder.value.

Since:
JDK1.2

Field Summary
 Principal value
Deprecated. The Principal value held by this PrincipalHolder object.
Constructor Summary
PrincipalHolder()
Deprecated. Constructs a new PrincipalHolder object with its value field initialized to null.
PrincipalHolder(Principal initial)
Deprecated. Constructs a new PrincipalHolder object with its value field initialized to the given Principal object.
Method Summary
void | _read(InputStream input) Deprecated. Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Deprecated. Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream output) Deprecated. Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public Principal value
Deprecated.
The Principal value held by this PrincipalHolder object.

Constructor Detail

PrincipalHolder

public PrincipalHolder()
Deprecated.
Constructs a new PrincipalHolder object with its value field initialized to null.

PrincipalHolder

public PrincipalHolder(Principal initial)
Deprecated.
Constructs a new PrincipalHolder object with its value field initialized to the given Principal object.

Parameters:
initial - the Principal with which to initialize the value field of the newly-created PrincipalHolder object
Method Detail

_read

public void _read(InputStream input)
Deprecated.
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
input - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream output)
Deprecated.
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
output - the CDR OutputStream

_type

public TypeCode _type()
Deprecated.
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PRIVATE_MEMBER

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface PRIVATE_MEMBER

public interface PRIVATE_MEMBER

Constant to define a private member in the ValueMember class.

PRIVATE_MEMBER is one of the two constants of typedef Visibility used in the interface repository to identify visibility of a ValueMember type. The other constant is PUBLIC_MEMBER.

Field Summary
static short value

Field Detail

value

static final short value
See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PUBLIC_MEMBER

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface PUBLIC_MEMBER

public interface PUBLIC_MEMBER

Constant to define a public member in the ValueMember class.

PUBLIC_MEMBER is one of the two constants of typedef Visibility used in the interface repository to identify visibility of a ValueMember type. The other constant is PRIVATE_MEMBER.

Field Summary
static short value

Field Detail

value

static final short value
See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


REBIND

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class REBIND

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.REBIND
All Implemented Interfaces:
Serializable
public final class REBIND
extends SystemException

REBIND is raised when the current effective RebindPolicy, has a value of NO_REBIND or NO_RECONNECT and an invocation on a bound object reference results in a LocateReply message with status OBJECT_FORWARD or a Reply message with status LOCATION_FORWARD. This exception is also raised if the current effective RebindPolicy has a value of NO_RECONNECT and a connection must be reopened.

Since:
J2SE 1.5
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
REBIND()
Constructs an REBIND exception with minor code set to 0 and CompletionStatus set to COMPLETED_NO.
REBIND(int minorCode, CompletionStatus completionStatus)
Constructs an REBIND exception with the specified minor code and completion status.
REBIND(String detailMessage)
Constructs an REBIND exception with the specified message.
REBIND(String detailMessage, int minorCode, CompletionStatus completionStatus)
Constructs an REBIND exception with the specified message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

REBIND

public REBIND()
Constructs an REBIND exception with minor code set to 0 and CompletionStatus set to COMPLETED_NO.

REBIND

public REBIND(String detailMessage)
Constructs an REBIND exception with the specified message.

Parameters:
detailMessage - string containing a detailed message.

REBIND

public REBIND(int minorCode,
              CompletionStatus completionStatus)
Constructs an REBIND exception with the specified minor code and completion status.

Parameters:
minorCode - minor code.
completionStatus - completion status.

REBIND

public REBIND(String detailMessage,
              int minorCode,
              CompletionStatus completionStatus)
Constructs an REBIND exception with the specified message, minor code, and completion status.

Parameters:
detailMessage - string containing a detailed message.
minorCode - minor code.
completionStatus - completion status.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RepositoryIdHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class RepositoryIdHelper

java.lang.Object
    extended by  org.omg.CORBA.RepositoryIdHelper

public abstract class RepositoryIdHelper
extends Object

The Helper for RepositoryId. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/RepositoryIdHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ir.idl 03 June 1999 11:33:43 o'clock GMT+00:00

Constructor Summary
RepositoryIdHelper()
Method Summary
static String | extract(Any a)
static String | id()
static void | insert(Any a, String that)
static String | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, String value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RepositoryIdHelper

public RepositoryIdHelper()
Method Detail

insert

public static void insert(Any a,
                          String that)

extract

public static String extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static String read(InputStream istream)

write

public static void write(OutputStream ostream,
                         String value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Request

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class Request

java.lang.Object
    extended by  org.omg.CORBA.Request

public abstract class Request
extends Object

An object containing the information necessary for invoking a method. This class is the cornerstone of the ORB Dynamic Invocation Interface (DII), which allows dynamic creation and invocation of requests. A server cannot tell the difference between a client invocation using a client stub and a request using the DII.

A Request object consists of:

  • the name of the operation to be invoked
  • an NVList containing arguments for the operation.
    Each item in the list is a NamedValue object, which has three parts:
    1. the name of the argument
    2. the value of the argument (as an Any object)
    3. the argument mode flag indicating whether the argument is for input, output, or both

Request objects may also contain additional information, depending on how an operation was defined in the original IDL interface definition. For example, where appropriate, they may contain a NamedValue object to hold the return value or exception, a context, a list of possible exceptions, and a list of context strings that need to be resolved.

New Request objects are created using one of the create_request methods in the Object class. In other words, a create_request method is performed on the object which is to be invoked.

See Also:
NamedValue

Constructor Summary
Request()
Method Summary
abstract Any | add_in_arg() Creates an input argument and adds it to this Request object.
abstract Any | add_inout_arg() Adds an input/output argument to this Request object.
abstract Any | add_named_in_arg(String name) Creates an input argument with the given name and adds it to this Request object.
abstract Any | add_named_inout_arg(String name) Adds an input/output argument with the given name to this Request object.
abstract Any | add_named_out_arg(String name) Adds an output argument with the given name to this Request object.
abstract Any | add_out_arg() Adds an output argument to this Request object.
abstract NVList | arguments() Retrieves the NVList object containing the arguments to the method being invoked.
abstract ContextList | contexts() Retrieves the ContextList object for this request.
abstract Context | ctx() Retrieves the Context object for this request.
abstract void | ctx(Context c) Sets this request's Context object to the one given.
abstract Environment | env() Retrieves the Environment object for this request.
abstract ExceptionList | exceptions() Retrieves the ExceptionList object for this request.
abstract void | get_response() Allows the user to access the response for the invocation triggered earlier with the send_deferred method.
abstract void | invoke() Makes a synchronous invocation using the information in the Request object.
abstract String | operation() Retrieves the name of the method to be invoked.
abstract boolean | poll_response() Allows the user to determine whether a response has been received for the invocation triggered earlier with the send_deferred method.
abstract NamedValue | result() Retrieves the NamedValue object containing the return value for the method.
abstract Any | return_value() Returns the Any object that contains the value for the result of the method.
abstract void | send_deferred() Makes an asynchronous invocation on the request.
abstract void | send_oneway() Makes a oneway invocation on the request.
abstract void | set_return_type(TypeCode tc) Sets the typecode for the return value of the method.
abstract Object | target() Retrieves the the target object reference.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Request

public Request()
Method Detail

target

public abstract Object target()
Retrieves the the target object reference.

Returns:
the object reference that points to the object implementation for the method to be invoked

operation

public abstract String operation()
Retrieves the name of the method to be invoked.

Returns:
the name of the method to be invoked

arguments

public abstract NVList arguments()
Retrieves the NVList object containing the arguments to the method being invoked. The elements in the list are NamedValue objects, with each one describing an argument to the method.

Returns:
the NVList object containing the arguments for the method

result

public abstract NamedValue result()
Retrieves the NamedValue object containing the return value for the method.

Returns:
the NamedValue object containing the result of the method

env

public abstract Environment env()
Retrieves the Environment object for this request. It contains the exception that the method being invoked has thrown (after the invocation returns).

Returns:
the Environment object for this request

exceptions

public abstract ExceptionList exceptions()
Retrieves the ExceptionList object for this request. This list contains TypeCode objects describing the exceptions that may be thrown by the method being invoked.

Returns:
the ExceptionList object describing the exceptions that may be thrown by the method being invoked

contexts

public abstract ContextList contexts()
Retrieves the ContextList object for this request. This list contains context Strings that need to be resolved and sent with the invocation.

Returns:
the list of context strings whose values need to be resolved and sent with the invocation.

ctx

public abstract Context ctx()
Retrieves the Context object for this request. This is a list of properties giving information about the client, the environment, or the circumstances of this request.

Returns:
the Context object that is to be used to resolve any context strings whose values need to be sent with the invocation

ctx

public abstract void ctx(Context c)
Sets this request's Context object to the one given.

Parameters:
c - the new Context object to be used for resolving context strings

add_in_arg

public abstract Any add_in_arg()
Creates an input argument and adds it to this Request object.

Returns:
an Any object that contains the value and typecode for the input argument added

add_named_in_arg

public abstract Any add_named_in_arg(String name)
Creates an input argument with the given name and adds it to this Request object.

Parameters:
name - the name of the argument being added
Returns:
an Any object that contains the value and typecode for the input argument added

add_inout_arg

public abstract Any add_inout_arg()
Adds an input/output argument to this Request object.

Returns:
an Any object that contains the value and typecode for the input/output argument added

add_named_inout_arg

public abstract Any add_named_inout_arg(String name)
Adds an input/output argument with the given name to this Request object.

Parameters:
name - the name of the argument being added
Returns:
an Any object that contains the value and typecode for the input/output argument added

add_out_arg

public abstract Any add_out_arg()
Adds an output argument to this Request object.

Returns:
an Any object that contains the value and typecode for the output argument added

add_named_out_arg

public abstract Any add_named_out_arg(String name)
Adds an output argument with the given name to this Request object.

Parameters:
name - the name of the argument being added
Returns:
an Any object that contains the value and typecode for the output argument added

set_return_type

public abstract void set_return_type(TypeCode tc)
Sets the typecode for the return value of the method.

Parameters:
tc - the TypeCode object containing type information for the return value

return_value

public abstract Any return_value()
Returns the Any object that contains the value for the result of the method.

Returns:
an Any object containing the value and typecode for the return value

invoke

public abstract void invoke()
Makes a synchronous invocation using the information in the Request object. Exception information is placed into the Request object's environment object.

send_oneway

public abstract void send_oneway()
Makes a oneway invocation on the request. In other words, it does not expect or wait for a response. Note that this can be used even if the operation was not declared as oneway in the IDL declaration. No response or exception information is returned.

send_deferred

public abstract void send_deferred()
Makes an asynchronous invocation on the request. In other words, it does not wait for a response before it returns to the user. The user can then later use the methods poll_response and get_response to get the result or exception information for the invocation.

poll_response

public abstract boolean poll_response()
Allows the user to determine whether a response has been received for the invocation triggered earlier with the send_deferred method.

Returns:
true if the method response has been received; false otherwise

get_response

public abstract void get_response()
                           throws WrongTransaction
Allows the user to access the response for the invocation triggered earlier with the send_deferred method.

Throws:
WrongTransaction - if the method get_response was invoked from a different transaction's scope than the one from which the request was originally sent. See the OMG Transaction Service specification for details.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServerRequest

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ServerRequest

java.lang.Object
    extended by  org.omg.CORBA.ServerRequest

public abstract class ServerRequest
extends Object

An object that captures the explicit state of a request for the Dynamic Skeleton Interface (DSI). This class, the cornerstone of the DSI, is analogous to the Request object in the DII.

The ORB is responsible for creating this embodiment of a request, and delivering it to a Dynamic Implementation Routine (DIR). A dynamic servant (a DIR) is created by implementing the DynamicImplementation class, which has a single invoke method. This method accepts a ServerRequest object. The abstract class ServerRequest defines methods for accessing the method name, the arguments and the context of the request, as well as methods for setting the result of the request either as a return value or an exception.

A subtlety with accessing the arguments of the request is that the DIR needs to provide type information about the expected arguments, since there is no compiled information about these. This information is provided through an NVList, which is a list of NamedValue objects. Each NamedValue object contains an Any object, which in turn has a TypeCode object representing the type of the argument.

Similarly, type information needs to be provided for the response, for either the expected result or for an exception, so the methods result and except take an Any object as a parameter.

See Also:
DynamicImplementation, NVList, NamedValue

Constructor Summary
ServerRequest()
Method Summary
 void arguments(NVList args)
Specifies method parameter types and retrieves "in" and "inout" argument values.
abstract  Context ctx()
Returns the context information specified in IDL for the operation when the operation is not an attribute access and the operation's IDL definition contains a context expression; otherwise it returns a nil Context reference.
 void except(Any any)
Deprecated. use set_exception()
 String op_name()
Deprecated. use operation()
 String operation()
Throws an org.omg.CORBA.NO_IMPLEMENT exception.
 void params(NVList params)
Deprecated. use the method arguments
 void result(Any any)
Deprecated. use the method set_result
 void set_exception(Any any)
Throws an org.omg.CORBA.NO_IMPLEMENT exception.
 void set_result(Any any)
Throws an org.omg.CORBA.NO_IMPLEMENT exception.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServerRequest

public ServerRequest()
Method Detail

op_name

@Deprecated
public String op_name()
Deprecated. use operation()

Retrieves the name of the operation being invoked. According to OMG IDL's rules, these names must be unique among all operations supported by this object's "most-derived" interface. Note that the operation names for getting and setting attributes are _get_<attribute_name> and _set_<attribute_name>, respectively.

Returns:
the name of the operation to be invoked

operation

public String operation()
Throws an org.omg.CORBA.NO_IMPLEMENT exception.

Retrieves the name of the operation being invoked. According to OMG IDL's rules, these names must be unique among all operations supported by this object's "most-derived" interface. Note that the operation names for getting and setting attributes are _get_<attribute_name> and _set_<attribute_name>, respectively.

Returns:
the name of the operation to be invoked
See Also:
CORBA package comments for unimplemented features

params

@Deprecated
public void params(NVList params)
Deprecated. use the method arguments

Specifies method parameter types and retrieves "in" and "inout" argument values.

Note that this method is deprecated; use the method arguments in its place.

Unless it calls the method set_exception, the DIR must call this method exactly once, even if the method signature contains no parameters. Once the method arguments or set_exception has been called, calling arguments on the same ServerRequest object will result in a BAD_INV_ORDER system exception. The DIR must pass in to the method arguments an NVList initialized with TypeCodes and Flags describing the parameter types for the operation, in the order in which they appear in the IDL specification (left to right). A potentially-different NVList will be returned from arguments, with the "in" and "inout" argument values supplied. If it does not call the method set_exception, the DIR must supply the returned NVList with return values for any "out" arguments before returning, and may also change the return values for any "inout" arguments.

Parameters:
params - the arguments of the method, in the form of an NVList object

arguments

public void arguments(NVList args)
Specifies method parameter types and retrieves "in" and "inout" argument values. Unless it calls the method set_exception, the DIR must call this method exactly once, even if the method signature contains no parameters. Once the method arguments or set_exception has been called, calling arguments on the same ServerRequest object will result in a BAD_INV_ORDER system exception. The DIR must pass in to the method arguments an NVList initialized with TypeCodes and Flags describing the parameter types for the operation, in the order in which they appear in the IDL specification (left to right). A potentially-different NVList will be returned from arguments, with the "in" and "inout" argument values supplied. If it does not call the method set_exception, the DIR must supply the returned NVList with return values for any "out" arguments before returning, and it may also change the return values for any "inout" arguments.

Parameters:
args - the arguments of the method, in the form of an NVList
See Also:
CORBA package comments for unimplemented features

result

@Deprecated
public void result(Any any)
Deprecated. use the method set_result

Specifies any return value for the call.

Note that this method is deprecated; use the method set_result in its place.

Unless the method set_exception is called, if the invoked method has a non-void result type, the method set_result must be called exactly once before the DIR returns. If the operation has a void result type, the method set_result may optionally be called once with an Any object whose type is tk_void. Calling the method set_result before the method arguments has been called or after the method set_result or set_exception has been called will result in a BAD_INV_ORDER exception. Calling the method set_result without having previously called the method ctx when the IDL operation contains a context expression, or when the NVList passed to arguments did not describe all parameters passed by the client, may result in a MARSHAL system exception.

Parameters:
any - an Any object containing the return value to be set

set_result

public void set_result(Any any)
Throws an org.omg.CORBA.NO_IMPLEMENT exception.

Specifies any return value for the call. Unless the method set_exception is called, if the invoked method has a non-void result type, the method set_result must be called exactly once before the DIR returns. If the operation has a void result type, the method set_result may optionally be called once with an Any object whose type is tk_void. Calling the method set_result before the method arguments has been called or after the method set_result or set_exception has been called will result in a BAD_INV_ORDER exception. Calling the method set_result without having previously called the method ctx when the IDL operation contains a context expression, or when the NVList passed to arguments did not describe all parameters passed by the client, may result in a MARSHAL system exception.

Parameters:
any - an Any object containing the return value to be set
See Also:
CORBA package comments for unimplemented features

except

@Deprecated
public void except(Any any)
Deprecated. use set_exception()

The DIR may call set_exception at any time to return an exception to the client. The Any passed to set_exception must contain either a system exception or a user exception specified in the raises expression of the invoked operation's IDL definition. Passing in an Any that does not contain an exception will result in a BAD_PARAM system exception. Passing in an unlisted user exception will result in either the DIR receiving a BAD_PARAM system exception or in the client receiving an UNKNOWN_EXCEPTION system exception.

Parameters:
any - the Any object containing the exception

set_exception

public void set_exception(Any any)
Throws an org.omg.CORBA.NO_IMPLEMENT exception.

Returns the given exception to the client. This method is invoked by the DIR, which may call it at any time. The Any object passed to this method must contain either a system exception or one of the user exceptions specified in the invoked operation's IDL definition. Passing in an Any object that does not contain an exception will cause a BAD_PARAM system exception to be thrown. Passing in an unlisted user exception will result in either the DIR receiving a BAD_PARAM system exception or in the client receiving an UNKNOWN_EXCEPTION system exception.

Parameters:
any - the Any object containing the exception
Throws:
BAD_PARAM - if the given Any object does not contain an exception or the exception is an unlisted user exception
UNKNOWN_EXCEPTION - if the given exception is an unlisted user exception and the DIR did not receive a BAD_PARAM exception
See Also:
CORBA package comments for unimplemented features

ctx

public abstract Context ctx()
Returns the context information specified in IDL for the operation when the operation is not an attribute access and the operation's IDL definition contains a context expression; otherwise it returns a nil Context reference. Calling the method ctx before the method arguments has been called or after the method ctx, set_result, or set_exception has been called will result in a BAD_INV_ORDER system exception.

Returns:
the context object that is to be used to resolve any context strings whose values need to be sent with the invocation.
Throws:
BAD_INV_ORDER - if (1) the method ctx is called before the method arguments or (2) the method ctx is called after calling set_result or set_exception
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServiceDetail

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ServiceDetail

java.lang.Object
    extended by  org.omg.CORBA.ServiceDetail
All Implemented Interfaces:
Serializable, IDLEntity
public final class ServiceDetail
extends Object
implements IDLEntity

An object that represents an ORB service: its service_detail_type field contains the type of the ORB service, and its service_detail field contains a description of the ORB service.

Field Summary
byte[] | service_detail The data describing the ORB service that this ServiceDetail object represents.
int | service_detail_type The type of the ORB service that this ServiceDetail object represents.
Constructor Summary
ServiceDetail()
Constructs a ServiceDetail object with 0 for the type of ORB service and an empty description.
ServiceDetail(int service_detail_type, byte[] service_detail)
Constructs a ServiceDetail object with the given ORB service type and the given description.
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

service_detail_type

public int service_detail_type
The type of the ORB service that this ServiceDetail object represents.

service_detail

public byte[] service_detail
The data describing the ORB service that this ServiceDetail object represents.

Constructor Detail

ServiceDetail

public ServiceDetail()
Constructs a ServiceDetail object with 0 for the type of ORB service and an empty description.

ServiceDetail

public ServiceDetail(int service_detail_type,
                     byte[] service_detail)
Constructs a ServiceDetail object with the given ORB service type and the given description.

Parameters:
service_detail_type - an int specifying the type of ORB service
service_detail - a byte array describing the ORB service
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServiceDetailHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ServiceDetailHelper

java.lang.Object
    extended by  org.omg.CORBA.ServiceDetailHelper

public abstract class ServiceDetailHelper
extends Object

Constructor Summary
ServiceDetailHelper()
Method Summary
static ServiceDetail | extract(Any a)
static String | id()
static void | insert(Any a, ServiceDetail that)
static ServiceDetail | read(InputStream in)
static TypeCode | type()
static void | write(OutputStream out, ServiceDetail that)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServiceDetailHelper

public ServiceDetailHelper()
Method Detail

write

public static void write(OutputStream out,
                         ServiceDetail that)

read

public static ServiceDetail read(InputStream in)

extract

public static ServiceDetail extract(Any a)

insert

public static void insert(Any a,
                          ServiceDetail that)

type

public static TypeCode type()

id

public static String id()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServiceInformation

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ServiceInformation

java.lang.Object
    extended by  org.omg.CORBA.ServiceInformation
All Implemented Interfaces:
Serializable, IDLEntity
public final class ServiceInformation
extends Object
implements IDLEntity

An IDL struct in the CORBA module that stores information about a CORBA service available in the ORB implementation and is obtained from the ORB.get_service_information method.

Field Summary
ServiceDetail[] | service_details Array of ServiceDetails giving more details about the service.
int[] | service_options Array of ints representing service options.
Constructor Summary
ServiceInformation()
Constructs a ServiceInformation object with empty service_options and service_details.
ServiceInformation(int[] __service_options, ServiceDetail[] __service_details)
Constructs a ServiceInformation object with the given service_options and service_details.
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

service_options

public int[] service_options
Array of ints representing service options.

service_details

public ServiceDetail[] service_details
Array of ServiceDetails giving more details about the service.

Constructor Detail

ServiceInformation

public ServiceInformation()
Constructs a ServiceInformation object with empty service_options and service_details.

ServiceInformation

public ServiceInformation(int[] __service_options,
                          ServiceDetail[] __service_details)
Constructs a ServiceInformation object with the given service_options and service_details.

Parameters:
__service_options - An array of ints describing the service options.
__service_details - An array of ServiceDetails describing the service details.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServiceInformationHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ServiceInformationHelper

java.lang.Object
    extended by  org.omg.CORBA.ServiceInformationHelper

public abstract class ServiceInformationHelper
extends Object

Constructor Summary
ServiceInformationHelper()
Method Summary
static ServiceInformation | extract(Any a)
static String | id()
static void | insert(Any a, ServiceInformation that)
static ServiceInformation | read(InputStream in)
static TypeCode | type()
static void | write(OutputStream out, ServiceInformation that)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServiceInformationHelper

public ServiceInformationHelper()
Method Detail

write

public static void write(OutputStream out,
                         ServiceInformation that)

read

public static ServiceInformation read(InputStream in)

extract

public static ServiceInformation extract(Any a)

insert

public static void insert(Any a,
                          ServiceInformation that)

type

public static TypeCode type()

id

public static String id()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServiceInformationHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ServiceInformationHolder

java.lang.Object
    extended by  org.omg.CORBA.ServiceInformationHolder
All Implemented Interfaces:
Streamable
public final class ServiceInformationHolder
extends Object
implements Streamable

The Holder for ServiceInformation. For more information on Holder files, see "Generated Files: Holder Files".

A Holder class for a ServiceInformation object that is used to store "out" and "inout" parameters in IDL methods. If an IDL method signature has an IDL xxx as an "out" or "inout" parameter, the programmer must pass an instance of ServiceInformationHolder as the corresponding parameter in the method invocation; for "inout" parameters, the programmer must also fill the "in" value to be sent to the server. Before the method invocation returns, the ORB will fill in the value corresponding to the "out" value returned from the server.

If myServiceInformationHolder is an instance of ServiceInformationHolder, the value stored in its value field can be accessed with myServiceInformationHolder.value.

Field Summary
 ServiceInformation value
The ServiceInformation value held by this ServiceInformationHolder object in its value field.
Constructor Summary
ServiceInformationHolder()
Constructs a new ServiceInformationHolder object with its value field initialized to null.
ServiceInformationHolder(ServiceInformation arg)
Constructs a new ServiceInformationHolder object with its value field initialized to the given ServiceInformation object.
Method Summary
void | _read(InputStream in) Reads unmarshalled data from the input stream in and assigns it to the value field in this ServiceInformationHolder object.
TypeCode | _type() Retrieves the TypeCode object that corresponds to the value held in this ServiceInformationHolder object's value field.
void | _write(OutputStream out) Marshals the value in this ServiceInformationHolder object's value field to the output stream out.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public ServiceInformation value
The ServiceInformation value held by this ServiceInformationHolder object in its value field.

Constructor Detail

ServiceInformationHolder

public ServiceInformationHolder()
Constructs a new ServiceInformationHolder object with its value field initialized to null.

ServiceInformationHolder

public ServiceInformationHolder(ServiceInformation arg)
Constructs a new ServiceInformationHolder object with its value field initialized to the given ServiceInformation object.

Parameters:
arg - the ServiceInformation object with which to initialize the value field of the newly-created ServiceInformationHolder object
Method Detail

_write

public void _write(OutputStream out)
Marshals the value in this ServiceInformationHolder object's value field to the output stream out.

Specified by:
_write in interface Streamable
Parameters:
out - the OutputStream object that will contain the CDR formatted data

_read

public void _read(InputStream in)
Reads unmarshalled data from the input stream in and assigns it to the value field in this ServiceInformationHolder object.

Specified by:
_read in interface Streamable
Parameters:
in - the InputStream object containing CDR formatted data from the wire

_type

public TypeCode _type()
Retrieves the TypeCode object that corresponds to the value held in this ServiceInformationHolder object's value field.

Specified by:
_type in interface Streamable
Returns:
the type code for the value held in this ServiceInformationHolder object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SetOverrideType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class SetOverrideType

java.lang.Object
    extended by  org.omg.CORBA.SetOverrideType
All Implemented Interfaces:
Serializable, IDLEntity
public class SetOverrideType
extends Object
implements IDLEntity

The mapping of a CORBA enum tagging SET_OVERRIDE and ADD_OVERRIDE, which indicate whether policies should replace the existing policies of an Object or be added to them.

The method omg.org.CORBA.Object._set_policy_override takes either SetOverrideType.SET_OVERRIDE or SetOverrideType.ADD_OVERRIDE as its second argument. The method _set_policy_override creates a new Object initialized with the Policy objects supplied as the first argument. If the second argument is ADD_OVERRIDE, the new policies are added to those of the Object instance that is calling the _set_policy_override method. If SET_OVERRIDE is given instead, the existing policies are replaced with the given ones.

Since:
JDK1.2

Field Summary
static int | _ADD_OVERRIDE The int constant for the enum value ADD_OVERRIDE.
static int | _SET_OVERRIDE The int constant for the enum value SET_OVERRIDE.
static SetOverrideType | ADD_OVERRIDE The SetOverrideType constant for the enum value ADD_OVERRIDE.
static SetOverrideType | SET_OVERRIDE The SetOverrideType constant for the enum value SET_OVERRIDE.
Constructor Summary
protected SetOverrideType(int _value)
Constructs a SetOverrideType instance from an int.
Method Summary
static SetOverrideType | from_int(int i) Converts the given int to the corresponding SetOverrideType instance.
int | value() Retrieves the value of this SetOverrideType instance.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_SET_OVERRIDE

public static final int _SET_OVERRIDE
The int constant for the enum value SET_OVERRIDE.

See Also:
Constant Field Values

_ADD_OVERRIDE

public static final int _ADD_OVERRIDE
The int constant for the enum value ADD_OVERRIDE.

See Also:
Constant Field Values

SET_OVERRIDE

public static final SetOverrideType SET_OVERRIDE
The SetOverrideType constant for the enum value SET_OVERRIDE.

ADD_OVERRIDE

public static final SetOverrideType ADD_OVERRIDE
The SetOverrideType constant for the enum value ADD_OVERRIDE.

Constructor Detail

SetOverrideType

protected SetOverrideType(int _value)
Constructs a SetOverrideType instance from an int.

Parameters:
_value - must be either SET_OVERRIDE or ADD_OVERRIDE
Method Detail

value

public int value()
Retrieves the value of this SetOverrideType instance.

Returns:
the int for this SetOverrideType instance.

from_int

public static SetOverrideType from_int(int i)
Converts the given int to the corresponding SetOverrideType instance.

Parameters:
i - the int to convert; must be either SetOverrideType._SET_OVERRIDE or SetOverrideType._ADD_OVERRIDE
Returns:
the SetOverrideType instance whose value matches the given int
Throws:
BAD_PARAM - if the given int does not match the value of any SetOverrideType instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SetOverrideTypeHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class SetOverrideTypeHelper

java.lang.Object
    extended by  org.omg.CORBA.SetOverrideTypeHelper

public abstract class SetOverrideTypeHelper
extends Object

The Helper for SetOverrideType. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/SetOverrideTypeHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" 03 June 1999 11:52:03 o'clock GMT+00:00

Constructor Summary
SetOverrideTypeHelper()
Method Summary
static SetOverrideType | extract(Any a)
static String | id()
static void | insert(Any a, SetOverrideType that)
static SetOverrideType | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, SetOverrideType value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SetOverrideTypeHelper

public SetOverrideTypeHelper()
Method Detail

insert

public static void insert(Any a,
                          SetOverrideType that)

extract

public static SetOverrideType extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static SetOverrideType read(InputStream istream)

write

public static void write(OutputStream ostream,
                         SetOverrideType value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ShortHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ShortHolder

java.lang.Object
    extended by  org.omg.CORBA.ShortHolder
All Implemented Interfaces:
Streamable
public final class ShortHolder
extends Object
implements Streamable

The Holder for Short. For more information on Holder files, see "Generated Files: Holder Files".

short that is used to store "out" and "inout" parameters in IDL operations. If an IDL operation signature has an IDL short as an "out" or "inout" parameter, the programmer must pass an instance of ShortHolder as the corresponding parameter in the method invocation; for "inout" parameters, the programmer must also fill the "in" value to be sent to the server. Before the method invocation returns, the ORB will fill in the value corresponding to the "out" value returned from the server.

If myShortHolder is an instance of ShortHolder, the value stored in its value field can be accessed with myShortHolder.value.

Since:
JDK1.2

Field Summary
 short value
The short value held by this ShortHolder object.
Constructor Summary
ShortHolder()
Constructs a new ShortHolder object with its value field initialized to 0.
ShortHolder(short initial)
Constructs a new ShortHolder object with its value field initialized to the given short.
Method Summary
void | _read(InputStream input) Reads from input and initalizes the value in this ShortHolder object with the unmarshalled data.
TypeCode | _type() Returns the TypeCode corresponding to the value held in this ShortHolder object.
void | _write(OutputStream output) Marshals to output the value in this ShortHolder object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public short value
The short value held by this ShortHolder object.

Constructor Detail

ShortHolder

public ShortHolder()
Constructs a new ShortHolder object with its value field initialized to 0.

ShortHolder

public ShortHolder(short initial)
Constructs a new ShortHolder object with its value field initialized to the given short.

Parameters:
initial - the short with which to initialize the value field of the newly-created ShortHolder object
Method Detail

_read

public void _read(InputStream input)
Reads from input and initalizes the value in this ShortHolder object with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
input - the InputStream containing CDR formatted data from the wire.

_write

public void _write(OutputStream output)
Marshals to output the value in this ShortHolder object.

Specified by:
_write in interface Streamable
Parameters:
output - the OutputStream which will contain the CDR formatted data.

_type

public TypeCode _type()
Returns the TypeCode corresponding to the value held in this ShortHolder object.

Specified by:
_type in interface Streamable
Returns:
the TypeCode of the value held in this ShortHolder object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ShortSeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ShortSeqHelper

java.lang.Object
    extended by  org.omg.CORBA.ShortSeqHelper

public abstract class ShortSeqHelper
extends Object

The Helper for ShortSeqHelper. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/ShortSeqHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications :

  • ORB core as defined by CORBA 2.3.1 (formal/99-10-07)
  • IDL/Java Language Mapping as defined in ptc/00-01-08

Constructor Summary
ShortSeqHelper()
Method Summary
static short[] | extract(Any a)
static String | id()
static void | insert(Any a, short[] that)
static short[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, short[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ShortSeqHelper

public ShortSeqHelper()
Method Detail

insert

public static void insert(Any a,
                          short[] that)

extract

public static short[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static short[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         short[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ShortSeqHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ShortSeqHolder

java.lang.Object
    extended by  org.omg.CORBA.ShortSeqHolder
All Implemented Interfaces:
Streamable
public final class ShortSeqHolder
extends Object
implements Streamable

The Holder for ShortSeq. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/ShortSeqHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00

Field Summary
 short[] value
Constructor Summary
ShortSeqHolder()
ShortSeqHolder(short[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public short[] value
Constructor Detail

ShortSeqHolder

public ShortSeqHolder()

ShortSeqHolder

public ShortSeqHolder(short[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StringHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class StringHolder

java.lang.Object
    extended by  org.omg.CORBA.StringHolder
All Implemented Interfaces:
Streamable
public final class StringHolder
extends Object
implements Streamable

The Holder for String. For more information on Holder files, see "Generated Files: Holder Files".

A Holder class for a String that is used to store "out" and "inout" parameters in IDL operations. If an IDL operation signature has an IDL string as an "out" or "inout" parameter, the programmer must pass an instance of StringHolder as the corresponding parameter in the method invocation; for "inout" parameters, the programmer must also fill the "in" value to be sent to the server. Before the method invocation returns, the ORB will fill in the value corresponding to the "out" value returned from the server.

If myStringHolder is an instance of StringHolder, the value stored in its value field can be accessed with myStringHolder.value.

Since:
JDK1.2

Field Summary
 String value
The String value held by this StringHolder object.
Constructor Summary
StringHolder()
Constructs a new StringHolder object with its value field initialized to null.
StringHolder(String initial)
Constructs a new StringHolder object with its value field initialized to the given String.
Method Summary
void | _read(InputStream input) Reads the unmarshalled data from input and assigns it to the value field of this StringHolder object.
TypeCode | _type() Retrieves the TypeCode object that corresponds to the value held in this StringHolder object.
void | _write(OutputStream output) Marshals the value held by this StringHolder object to the output stream output.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public String value
The String value held by this StringHolder object.

Constructor Detail

StringHolder

public StringHolder()
Constructs a new StringHolder object with its value field initialized to null.

StringHolder

public StringHolder(String initial)
Constructs a new StringHolder object with its value field initialized to the given String.

Parameters:
initial - the String with which to initialize the value field of the newly-created StringHolder object
Method Detail

_read

public void _read(InputStream input)
Reads the unmarshalled data from input and assigns it to the value field of this StringHolder object.

Specified by:
_read in interface Streamable
Parameters:
input - the InputStream containing CDR formatted data from the wire.

_write

public void _write(OutputStream output)
Marshals the value held by this StringHolder object to the output stream output.

Specified by:
_write in interface Streamable
Parameters:
output - the OutputStream which will contain the CDR formatted data.

_type

public TypeCode _type()
Retrieves the TypeCode object that corresponds to the value held in this StringHolder object.

Specified by:
_type in interface Streamable
Returns:
the type code of the value held in this StringHolder object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StringSeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class StringSeqHelper

java.lang.Object
    extended by  org.omg.CORBA.StringSeqHelper

public abstract class StringSeqHelper
extends Object

An array of Strings

Constructor Summary
StringSeqHelper()
Method Summary
static String[] | extract(Any a)
static String | id()
static void | insert(Any a, String[] that)
static String[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, String[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StringSeqHelper

public StringSeqHelper()
Method Detail

insert

public static void insert(Any a,
                          String[] that)

extract

public static String[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static String[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         String[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StringSeqHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class StringSeqHolder

java.lang.Object
    extended by  org.omg.CORBA.StringSeqHolder
All Implemented Interfaces:
Streamable
public final class StringSeqHolder
extends Object
implements Streamable

An array of Strings

Field Summary
 String[] value
Constructor Summary
StringSeqHolder()
StringSeqHolder(String[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public String[] value
Constructor Detail

StringSeqHolder

public StringSeqHolder()

StringSeqHolder

public StringSeqHolder(String[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StringValueHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class StringValueHelper

java.lang.Object
    extended by  org.omg.CORBA.StringValueHelper
All Implemented Interfaces:
BoxedValueHelper
public class StringValueHelper
extends Object
implements BoxedValueHelper

The Helper for StringValue. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/StringValueHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from orb.idl 31 May 1999 22:27:30 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications :

  • ORB core as defined by CORBA 2.3.1 (formal/99-10-07)
  • IDL/Java Language Mapping as defined in ptc/00-01-08

Constructor Summary
StringValueHelper()
Method Summary
static String | extract(Any a)
String | get_id()
static String | id()
static void | insert(Any a, String that)
Serializable | read_value(InputStream istream)
static String | read(InputStream istream)
static TypeCode | type()
void | write_value(OutputStream ostream, Serializable value)
static void | write(OutputStream ostream, String value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StringValueHelper

public StringValueHelper()
Method Detail

insert

public static void insert(Any a,
                          String that)

extract

public static String extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static String read(InputStream istream)

read_value

public Serializable read_value(InputStream istream)
Specified by:
read_value in interface BoxedValueHelper

write

public static void write(OutputStream ostream,
                         String value)

write_value

public void write_value(OutputStream ostream,
                        Serializable value)
Specified by:
write_value in interface BoxedValueHelper

get_id

public String get_id()
Specified by:
get_id in interface BoxedValueHelper
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StructMember

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class StructMember

java.lang.Object
    extended by  org.omg.CORBA.StructMember
All Implemented Interfaces:
Serializable, IDLEntity
public final class StructMember
extends Object
implements IDLEntity

Describes a member of an IDL struct in the Interface Repository, including the name of the struct member, the type of the struct member, and the typedef that represents the IDL type of the struct member described the struct member object.

Field Summary
String | name The name of the struct member described by this StructMember object.
TypeCode | type The type of the struct member described by this StructMember object.
IDLType | type_def The typedef that represents the IDL type of the struct member described by this StructMember object.
Constructor Summary
StructMember()
Constructs a default StructMember object.
StructMember(String __name, TypeCode __type, IDLType __type_def)
Constructs a StructMember object initialized with the given values.
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

name

public String name
The name of the struct member described by this StructMember object.

type

public TypeCode type
The type of the struct member described by this StructMember object.

type_def

public IDLType type_def
The typedef that represents the IDL type of the struct member described by this StructMember object.

Constructor Detail

StructMember

public StructMember()
Constructs a default StructMember object.

StructMember

public StructMember(String __name,
                    TypeCode __type,
                    IDLType __type_def)
Constructs a StructMember object initialized with the given values.

Parameters:
__name - a String object with the name of the struct member
__type - a TypeCode object describing the type of the struct member
__type_def - an IDLType object representing the IDL type of the struct member
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StructMemberHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class StructMemberHelper

java.lang.Object
    extended by  org.omg.CORBA.StructMemberHelper

public abstract class StructMemberHelper
extends Object

The Helper for StructMember. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/StructMemberHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ir.idl 03 June 1999 11:33:43 o'clock GMT+00:00

Constructor Summary
StructMemberHelper()
Method Summary
static StructMember | extract(Any a)
static String | id()
static void | insert(Any a, StructMember that)
static StructMember | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, StructMember value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StructMemberHelper

public StructMemberHelper()
Method Detail

insert

public static void insert(Any a,
                          StructMember that)

extract

public static StructMember extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static StructMember read(InputStream istream)

write

public static void write(OutputStream ostream,
                         StructMember value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SystemException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class SystemException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
ACTIVITY_COMPLETED, ACTIVITY_REQUIRED, BAD_CONTEXT, BAD_INV_ORDER, BAD_OPERATION, BAD_PARAM, BAD_QOS, BAD_TYPECODE, CODESET_INCOMPATIBLE, COMM_FAILURE, DATA_CONVERSION, FREE_MEM, IMP_LIMIT, IndirectionException, INITIALIZE, INTERNAL, INTF_REPOS, INV_FLAG, INV_IDENT, INV_OBJREF, INV_POLICY, INVALID_ACTIVITY, INVALID_TRANSACTION, MARSHAL, NO_IMPLEMENT, NO_MEMORY, NO_PERMISSION, NO_RESOURCES, NO_RESPONSE, OBJ_ADAPTER, OBJECT_NOT_EXIST, PERSIST_STORE, REBIND, TIMEOUT, TRANSACTION_MODE, TRANSACTION_REQUIRED, TRANSACTION_ROLLEDBACK, TRANSACTION_UNAVAILABLE, TRANSIENT, UNKNOWN, UnknownException
public abstract class SystemException
extends RuntimeException

The root class for all CORBA standard exceptions. These exceptions may be thrown as a result of any CORBA operation invocation and may also be returned by many standard CORBA API methods. The standard exceptions contain a minor code, allowing more detailed specification, and a completion status. This class is subclassed to generate each one of the set of standard ORB exceptions. SystemException extends java.lang.RuntimeException; thus none of the SystemException exceptions need to be declared in signatures of the Java methods mapped from operations in IDL interfaces.

See Also:
documentation on Java IDL exceptions

Field Summary
CompletionStatus | completed The status of the operation that threw this exception.
int | minor The CORBA Exception minor code.
Constructor Summary
protected SystemException(String reason, int minor, CompletionStatus completed)
Constructs a SystemException exception with the specified detail message, minor code, and completion status.
Method Summary
 String toString()
Converts this exception to a representative string.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

minor

public int minor
The CORBA Exception minor code.

completed

public CompletionStatus completed
The status of the operation that threw this exception.

Constructor Detail

SystemException

protected SystemException(String reason,
                          int minor,
                          CompletionStatus completed)
Constructs a SystemException exception with the specified detail message, minor code, and completion status. A detail message is a String that describes this particular exception.

Parameters:
reason - the String containing a detail message
minor - the minor code
completed - the completion status
Method Detail

toString

public String toString()
Converts this exception to a representative string.

Overrides:
toString in class Throwable
Returns:
a string representation of this throwable.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TCKind

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class TCKind

java.lang.Object
    extended by  org.omg.CORBA.TCKind

public class TCKind
extends Object

The Java mapping of the IDL enum TCKind, which specifies the kind of a TypeCode object. There is one kind for each primitive and essential IDL data type.

The class TCKind consists of:

  • a set of int constants, one for each kind of IDL data type. These int constants make it possible to use a switch statement.
  • a set of TCKind constants, one for each kind of IDL data type. The value field for each TCKind instance is initialized with the int constant that corresponds with the IDL data type that the instance represents.
  • the method from_intfor converting an int to its corresponding TCKind instance

    Example:

          org.omg.CORBA.TCKind k = org.omg.CORBA.TCKind.from_int(
                         org.omg.CORBA.TCKind._tk_string);
    The variable k represents the TCKind instance for the IDL type string, which is tk_string.

  • the method value for accessing the _value field of a TCKind constant

    Example:

       int i = org.omg.CORBA.TCKind.tk_char.value();
    The variable i represents 9, the value for the IDL data type char.

The value field of a TCKind instance is the CDR encoding used for a TypeCode object in an IIOP message.

Field Summary
static int | _tk_abstract_interface The int constant for the IDL data type abstract interface.
static int | _tk_alias The int constant for the IDL data type alias.
static int | _tk_any The int constant for the IDL data type any.
static int | _tk_array The int constant for the IDL data type array.
static int | _tk_boolean The int constant for the IDL data type boolean.
static int | _tk_char The int constant for the IDL data type char.
static int | _tk_double The int constant for the IDL data type double.
static int | _tk_enum The int constant for the IDL data type enum.
static int | _tk_except The int constant for the IDL data type except.
static int | _tk_fixed The int constant for the IDL data type fixed.
static int | _tk_float The int constant for the IDL data type float.
static int | _tk_long The int constant for the IDL data type long.
static int | _tk_longdouble The int constant for the IDL data type longdouble.
static int | _tk_longlong The int constant for the IDL data type longlong.
static int | _tk_native The int constant for the IDL data type native.
static int | _tk_null The int constant for a null IDL data type.
static int | _tk_objref The int constant for the IDL data type objref.
static int | _tk_octet The int constant for the IDL data type octet.
static int | _tk_Principal The int constant for the IDL data type Principal.
static int | _tk_sequence The int constant for the IDL data type sequence.
static int | _tk_short The int constant for the IDL data type short.
static int | _tk_string The int constant for the IDL data type string.
static int | _tk_struct The int constant for the IDL data type struct.
static int | _tk_TypeCode The int constant for the IDL data type TypeCode.
static int | _tk_ulong The int constant for the IDL data type ulong.
static int | _tk_ulonglong The int constant for the IDL data type ulonglong.
static int | _tk_union The int constant for the IDL data type union.
static int | _tk_ushort The int constant for the IDL data type ushort.
static int | _tk_value The int constant for the IDL data type value.
static int | _tk_value_box The int constant for the IDL data type value_box.
static int | _tk_void The int constant for the IDL data type void.
static int | _tk_wchar The int constant for the IDL data type wchar.
static int | _tk_wstring The int constant for the IDL data type wstring.
static TCKind | tk_abstract_interface The TCKind constant whose value field is initialized with TCKind._tk_abstract_interface.
static TCKind | tk_alias The TCKind constant whose value field is initialized with TCKind._tk_alias.
static TCKind | tk_any The TCKind constant whose value field is initialized with TCKind._tk_any.
static TCKind | tk_array The TCKind constant whose value field is initialized with TCKind._tk_array.
static TCKind | tk_boolean The TCKind constant whose value field is initialized with TCKind._tk_boolean.
static TCKind | tk_char The TCKind constant whose value field is initialized with TCKind._tk_char.
static TCKind | tk_double The TCKind constant whose value field is initialized with TCKind._tk_double.
static TCKind | tk_enum The TCKind constant whose value field is initialized with TCKind._tk_enum.
static TCKind | tk_except The TCKind constant whose value field is initialized with TCKind._tk_except.
static TCKind | tk_fixed The TCKind constant whose value field is initialized with TCKind._tk_fixed.
static TCKind | tk_float The TCKind constant whose value field is initialized with TCKind._tk_float.
static TCKind | tk_long The TCKind constant whose value field is initialized with TCKind._tk_long.
static TCKind | tk_longdouble The TCKind constant whose value field is initialized with TCKind._tk_longdouble.
static TCKind | tk_longlong The TCKind constant whose value field is initialized with TCKind._tk_longlong.
static TCKind | tk_native The TCKind constant whose value field is initialized with TCKind._tk_native.
static TCKind | tk_null The TCKind constant whose value field is initialized with TCKind._tk_null.
static TCKind | tk_objref The TCKind constant whose value field is initialized with TCKind._tk_objref.
static TCKind | tk_octet The TCKind constant whose value field is initialized with TCKind._tk_octet.
static TCKind | tk_Principal The TCKind constant whose value field is initialized with TCKind._tk_Principal.
static TCKind | tk_sequence The TCKind constant whose value field is initialized with TCKind._tk_sequence.
static TCKind | tk_short The TCKind constant whose value field is initialized with TCKind._tk_short.
static TCKind | tk_string The TCKind constant whose value field is initialized with TCKind._tk_string.
static TCKind | tk_struct The TCKind constant whose value field is initialized with TCKind._tk_struct.
static TCKind | tk_TypeCode The TCKind constant whose value field is initialized with TCKind._tk_TypeCode.
static TCKind | tk_ulong The TCKind constant whose value field is initialized with TCKind._tk_ulong.
static TCKind | tk_ulonglong The TCKind constant whose value field is initialized with TCKind._tk_ulonglong.
static TCKind | tk_union The TCKind constant whose value field is initialized with TCKind._tk_union.
static TCKind | tk_ushort The TCKind constant whose value field is initialized with TCKind._tk_ushort.
static TCKind | tk_value The TCKind constant whose value field is initialized with TCKind._tk_value.
static TCKind | tk_value_box The TCKind constant whose value field is initialized with TCKind._tk_value_box.
static TCKind | tk_void The TCKind constant whose value field is initialized with TCKind._tk_void.
static TCKind | tk_wchar The TCKind constant whose value field is initialized with TCKind._tk_wchar.
static TCKind | tk_wstring The TCKind constant whose value field is initialized with TCKind._tk_wstring.
Constructor Summary
protected TCKind(int _value)
Deprecated. Do not use this constructor as this method should be private according to the OMG specification. Use from_int(int) instead.
Method Summary
static TCKind | from_int(int i) Converts the given int to the corresponding TCKind instance.
int | value() Retrieves the value of this TCKind instance.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_tk_null

public static final int _tk_null
The int constant for a null IDL data type.

See Also:
Constant Field Values

_tk_void

public static final int _tk_void
The int constant for the IDL data type void.

See Also:
Constant Field Values

_tk_short

public static final int _tk_short
The int constant for the IDL data type short.

See Also:
Constant Field Values

_tk_long

public static final int _tk_long
The int constant for the IDL data type long.

See Also:
Constant Field Values

_tk_ushort

public static final int _tk_ushort
The int constant for the IDL data type ushort.

See Also:
Constant Field Values

_tk_ulong

public static final int _tk_ulong
The int constant for the IDL data type ulong.

See Also:
Constant Field Values

_tk_float

public static final int _tk_float
The int constant for the IDL data type float.

See Also:
Constant Field Values

_tk_double

public static final int _tk_double
The int constant for the IDL data type double.

See Also:
Constant Field Values

_tk_boolean

public static final int _tk_boolean
The int constant for the IDL data type boolean.

See Also:
Constant Field Values

_tk_char

public static final int _tk_char
The int constant for the IDL data type char.

See Also:
Constant Field Values

_tk_octet

public static final int _tk_octet
The int constant for the IDL data type octet.

See Also:
Constant Field Values

_tk_any

public static final int _tk_any
The int constant for the IDL data type any.

See Also:
Constant Field Values

_tk_TypeCode

public static final int _tk_TypeCode
The int constant for the IDL data type TypeCode.

See Also:
Constant Field Values

_tk_Principal

public static final int _tk_Principal
The int constant for the IDL data type Principal.

See Also:
Constant Field Values

_tk_objref

public static final int _tk_objref
The int constant for the IDL data type objref.

See Also:
Constant Field Values

_tk_struct

public static final int _tk_struct
The int constant for the IDL data type struct.

See Also:
Constant Field Values

_tk_union

public static final int _tk_union
The int constant for the IDL data type union.

See Also:
Constant Field Values

_tk_enum

public static final int _tk_enum
The int constant for the IDL data type enum.

See Also:
Constant Field Values

_tk_string

public static final int _tk_string
The int constant for the IDL data type string.

See Also:
Constant Field Values

_tk_sequence

public static final int _tk_sequence
The int constant for the IDL data type sequence.

See Also:
Constant Field Values

_tk_array

public static final int _tk_array
The int constant for the IDL data type array.

See Also:
Constant Field Values

_tk_alias

public static final int _tk_alias
The int constant for the IDL data type alias.

See Also:
Constant Field Values

_tk_except

public static final int _tk_except
The int constant for the IDL data type except.

See Also:
Constant Field Values

_tk_longlong

public static final int _tk_longlong
The int constant for the IDL data type longlong.

See Also:
Constant Field Values

_tk_ulonglong

public static final int _tk_ulonglong
The int constant for the IDL data type ulonglong.

See Also:
Constant Field Values

_tk_longdouble

public static final int _tk_longdouble
The int constant for the IDL data type longdouble.

See Also:
Constant Field Values

_tk_wchar

public static final int _tk_wchar
The int constant for the IDL data type wchar.

See Also:
Constant Field Values

_tk_wstring

public static final int _tk_wstring
The int constant for the IDL data type wstring.

See Also:
Constant Field Values

_tk_fixed

public static final int _tk_fixed
The int constant for the IDL data type fixed.

See Also:
Constant Field Values

_tk_value

public static final int _tk_value
The int constant for the IDL data type value.

See Also:
Constant Field Values

_tk_value_box

public static final int _tk_value_box
The int constant for the IDL data type value_box.

See Also:
Constant Field Values

_tk_native

public static final int _tk_native
The int constant for the IDL data type native.

See Also:
Constant Field Values

_tk_abstract_interface

public static final int _tk_abstract_interface
The int constant for the IDL data type abstract interface.

See Also:
Constant Field Values

tk_null

public static final TCKind tk_null
The TCKind constant whose value field is initialized with TCKind._tk_null.

tk_void

public static final TCKind tk_void
The TCKind constant whose value field is initialized with TCKind._tk_void.

tk_short

public static final TCKind tk_short
The TCKind constant whose value field is initialized with TCKind._tk_short.

tk_long

public static final TCKind tk_long
The TCKind constant whose value field is initialized with TCKind._tk_long.

tk_ushort

public static final TCKind tk_ushort
The TCKind constant whose value field is initialized with TCKind._tk_ushort.

tk_ulong

public static final TCKind tk_ulong
The TCKind constant whose value field is initialized with TCKind._tk_ulong.

tk_float

public static final TCKind tk_float
The TCKind constant whose value field is initialized with TCKind._tk_float.

tk_double

public static final TCKind tk_double
The TCKind constant whose value field is initialized with TCKind._tk_double.

tk_boolean

public static final TCKind tk_boolean
The TCKind constant whose value field is initialized with TCKind._tk_boolean.

tk_char

public static final TCKind tk_char
The TCKind constant whose value field is initialized with TCKind._tk_char.

tk_octet

public static final TCKind tk_octet
The TCKind constant whose value field is initialized with TCKind._tk_octet.

tk_any

public static final TCKind tk_any
The TCKind constant whose value field is initialized with TCKind._tk_any.

tk_TypeCode

public static final TCKind tk_TypeCode
The TCKind constant whose value field is initialized with TCKind._tk_TypeCode.

tk_Principal

public static final TCKind tk_Principal
The TCKind constant whose value field is initialized with TCKind._tk_Principal.

tk_objref

public static final TCKind tk_objref
The TCKind constant whose value field is initialized with TCKind._tk_objref.

tk_struct

public static final TCKind tk_struct
The TCKind constant whose value field is initialized with TCKind._tk_struct.

tk_union

public static final TCKind tk_union
The TCKind constant whose value field is initialized with TCKind._tk_union.

tk_enum

public static final TCKind tk_enum
The TCKind constant whose value field is initialized with TCKind._tk_enum.

tk_string

public static final TCKind tk_string
The TCKind constant whose value field is initialized with TCKind._tk_string.

tk_sequence

public static final TCKind tk_sequence
The TCKind constant whose value field is initialized with TCKind._tk_sequence.

tk_array

public static final TCKind tk_array
The TCKind constant whose value field is initialized with TCKind._tk_array.

tk_alias

public static final TCKind tk_alias
The TCKind constant whose value field is initialized with TCKind._tk_alias.

tk_except

public static final TCKind tk_except
The TCKind constant whose value field is initialized with TCKind._tk_except.

tk_longlong

public static final TCKind tk_longlong
The TCKind constant whose value field is initialized with TCKind._tk_longlong.

tk_ulonglong

public static final TCKind tk_ulonglong
The TCKind constant whose value field is initialized with TCKind._tk_ulonglong.

tk_longdouble

public static final TCKind tk_longdouble
The TCKind constant whose value field is initialized with TCKind._tk_longdouble.

tk_wchar

public static final TCKind tk_wchar
The TCKind constant whose value field is initialized with TCKind._tk_wchar.

tk_wstring

public static final TCKind tk_wstring
The TCKind constant whose value field is initialized with TCKind._tk_wstring.

tk_fixed

public static final TCKind tk_fixed
The TCKind constant whose value field is initialized with TCKind._tk_fixed.

tk_value

public static final TCKind tk_value
The TCKind constant whose value field is initialized with TCKind._tk_value.

tk_value_box

public static final TCKind tk_value_box
The TCKind constant whose value field is initialized with TCKind._tk_value_box.

tk_native

public static final TCKind tk_native
The TCKind constant whose value field is initialized with TCKind._tk_native.

tk_abstract_interface

public static final TCKind tk_abstract_interface
The TCKind constant whose value field is initialized with TCKind._tk_abstract_interface.

Constructor Detail

TCKind

@Deprecated
protected TCKind(int _value)
Deprecated. Do not use this constructor as this method should be private according to the OMG specification. Use from_int(int) instead.

Creates a new TCKind instance initialized with the given int.

Parameters:
_value - the int to convert. It must be one of the int constants in the class TCKind.
Method Detail

value

public int value()
Retrieves the value of this TCKind instance.

Returns:
the int that represents the kind of IDL data type for this TCKind instance

from_int

public static TCKind from_int(int i)
Converts the given int to the corresponding TCKind instance.

Parameters:
i - the int to convert. It must be one of the int constants in the class TCKind.
Returns:
the TCKind instance whose value field matches the given int
Throws:
BAD_PARAM - if the given int does not match the _value field of any TCKind instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TIMEOUT

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class TIMEOUT

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.TIMEOUT
All Implemented Interfaces:
Serializable
public final class TIMEOUT
extends SystemException

TIMEOUT is raised when no delivery has been made and the specified time-to-live period has been exceeded. It is a standard system exception because time-to-live QoS can be applied to any invocation.

Since:
J2SE 1.5
See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
TIMEOUT()
Constructs an TIMEOUT exception with minor code set to 0 and CompletionStatus set to COMPLETED_NO.
TIMEOUT(int minorCode, CompletionStatus completionStatus)
Constructs an TIMEOUT exception with the specified minor code and completion status.
TIMEOUT(String detailMessage)
Constructs an TIMEOUT exception with the specified message.
TIMEOUT(String detailMessage, int minorCode, CompletionStatus completionStatus)
Constructs an TIMEOUT exception with the specified message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TIMEOUT

public TIMEOUT()
Constructs an TIMEOUT exception with minor code set to 0 and CompletionStatus set to COMPLETED_NO.

TIMEOUT

public TIMEOUT(String detailMessage)
Constructs an TIMEOUT exception with the specified message.

Parameters:
detailMessage - string containing a detailed message.

TIMEOUT

public TIMEOUT(int minorCode,
               CompletionStatus completionStatus)
Constructs an TIMEOUT exception with the specified minor code and completion status.

Parameters:
minorCode - minor code.
completionStatus - completion status.

TIMEOUT

public TIMEOUT(String detailMessage,
               int minorCode,
               CompletionStatus completionStatus)
Constructs an TIMEOUT exception with the specified message, minor code, and completion status.

Parameters:
detailMessage - string containing a detailed message.
minorCode - minor code.
completionStatus - completion status.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TRANSACTION_MODE

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class TRANSACTION_MODE

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.TRANSACTION_MODE
All Implemented Interfaces:
Serializable
public final class TRANSACTION_MODE
extends SystemException

The CORBA TRANSACTION_MODE exception is thrown by the client ORB if it detects a mismatch between the InvocationPolicy in the IOR and the chosen invocation path (i.e, direct or routed invocation). It contains a minor code, which gives information about what caused the exception, and a completion status. It may also contain a string describing the exception. The OMG CORBA core 2.4 specification has details.

See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
TRANSACTION_MODE()
Constructs a TRANSACTION_MODE exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.
TRANSACTION_MODE(int minor, CompletionStatus completed)
Constructs a TRANSACTION_MODE exception with the specified minor code and completion status.
TRANSACTION_MODE(String s)
Constructs a TRANSACTION_MODE exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.
TRANSACTION_MODE(String s, int minor, CompletionStatus completed)
Constructs a TRANSACTION_MODE exception with the specified description message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TRANSACTION_MODE

public TRANSACTION_MODE()
Constructs a TRANSACTION_MODE exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.

TRANSACTION_MODE

public TRANSACTION_MODE(String s)
Constructs a TRANSACTION_MODE exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message

TRANSACTION_MODE

public TRANSACTION_MODE(int minor,
                        CompletionStatus completed)
Constructs a TRANSACTION_MODE exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

TRANSACTION_MODE

public TRANSACTION_MODE(String s,
                        int minor,
                        CompletionStatus completed)
Constructs a TRANSACTION_MODE exception with the specified description message, minor code, and completion status.

Parameters:
s - the String containing a description message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TRANSACTION_REQUIRED

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class TRANSACTION_REQUIRED

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.TRANSACTION_REQUIRED
All Implemented Interfaces:
Serializable
public final class TRANSACTION_REQUIRED
extends SystemException

Exception indicates that the request carried a null transaction context, but an active transaction is required.

It contains a minor code, which gives information about what caused the exception, and a completion status. It may also contain a string describing the exception. The OMG Transaction Service specfication has details.

See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
TRANSACTION_REQUIRED()
Constructs a TRANSACTION_REQUIRED exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.
TRANSACTION_REQUIRED(int minor, CompletionStatus completed)
Constructs a TRANSACTION_REQUIRED exception with the specified minor code and completion status.
TRANSACTION_REQUIRED(String s)
Constructs a TRANSACTION_REQUIRED exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.
TRANSACTION_REQUIRED(String s, int minor, CompletionStatus completed)
Constructs a TRANSACTION_REQUIRED exception with the specified description message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TRANSACTION_REQUIRED

public TRANSACTION_REQUIRED()
Constructs a TRANSACTION_REQUIRED exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.

TRANSACTION_REQUIRED

public TRANSACTION_REQUIRED(String s)
Constructs a TRANSACTION_REQUIRED exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message

TRANSACTION_REQUIRED

public TRANSACTION_REQUIRED(int minor,
                            CompletionStatus completed)
Constructs a TRANSACTION_REQUIRED exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

TRANSACTION_REQUIRED

public TRANSACTION_REQUIRED(String s,
                            int minor,
                            CompletionStatus completed)
Constructs a TRANSACTION_REQUIRED exception with the specified description message, minor code, and completion status.

Parameters:
s - the String containing a description message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TRANSACTION_ROLLEDBACK

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class TRANSACTION_ROLLEDBACK

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.TRANSACTION_ROLLEDBACK
All Implemented Interfaces:
Serializable
public final class TRANSACTION_ROLLEDBACK
extends SystemException

Exception thrown when the transaction associated with the request has already been rolled back or marked to roll back. Thus, the requested operation either could not be performed or was not performed because further computation on behalf of the transaction would be fruitless.

See the OMG Transaction Service specification for details. It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
TRANSACTION_ROLLEDBACK()
Constructs a TRANSACTION_ROLLEDBACK exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.
TRANSACTION_ROLLEDBACK(int minor, CompletionStatus completed)
Constructs a TRANSACTION_ROLLEDBACK exception with the specified minor code and completion status.
TRANSACTION_ROLLEDBACK(String s)
Constructs a TRANSACTION_ROLLEDBACK exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.
TRANSACTION_ROLLEDBACK(String s, int minor, CompletionStatus completed)
Constructs a TRANSACTION_ROLLEDBACK exception with the specified description message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TRANSACTION_ROLLEDBACK

public TRANSACTION_ROLLEDBACK()
Constructs a TRANSACTION_ROLLEDBACK exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.

TRANSACTION_ROLLEDBACK

public TRANSACTION_ROLLEDBACK(String s)
Constructs a TRANSACTION_ROLLEDBACK exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message

TRANSACTION_ROLLEDBACK

public TRANSACTION_ROLLEDBACK(int minor,
                              CompletionStatus completed)
Constructs a TRANSACTION_ROLLEDBACK exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

TRANSACTION_ROLLEDBACK

public TRANSACTION_ROLLEDBACK(String s,
                              int minor,
                              CompletionStatus completed)
Constructs a TRANSACTION_ROLLEDBACK exception with the specified description message, minor code, and completion status.

Parameters:
s - the String containing a description message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TRANSACTION_UNAVAILABLE

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class TRANSACTION_UNAVAILABLE

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.TRANSACTION_UNAVAILABLE
All Implemented Interfaces:
Serializable
public final class TRANSACTION_UNAVAILABLE
extends SystemException

The CORBA TRANSACTION_UNAVAILABLE exception is thrown by the ORB when it cannot process a transaction service context because its connection to the Transaction Service has been abnormally terminated. It contains a minor code, which gives information about what caused the exception, and a completion status. It may also contain a string describing the exception. The OMG CORBA core 2.4 specification has details.

See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
TRANSACTION_UNAVAILABLE()
Constructs a TRANSACTION_UNAVAILABLE exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.
TRANSACTION_UNAVAILABLE(int minor, CompletionStatus completed)
Constructs a TRANSACTION_UNAVAILABLE exception with the specified minor code and completion status.
TRANSACTION_UNAVAILABLE(String s)
Constructs a TRANSACTION_UNAVAILABLE exception with the specifieddescription message, a minor code of 0, and a completion state of COMPLETED_NO.
TRANSACTION_UNAVAILABLE(String s, int minor, CompletionStatus completed)
Constructs a TRANSACTION_UNAVAILABLE exception with the specified description message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TRANSACTION_UNAVAILABLE

public TRANSACTION_UNAVAILABLE()
Constructs a TRANSACTION_UNAVAILABLE exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.

TRANSACTION_UNAVAILABLE

public TRANSACTION_UNAVAILABLE(String s)
Constructs a TRANSACTION_UNAVAILABLE exception with the specifieddescription message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message

TRANSACTION_UNAVAILABLE

public TRANSACTION_UNAVAILABLE(int minor,
                               CompletionStatus completed)
Constructs a TRANSACTION_UNAVAILABLE exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

TRANSACTION_UNAVAILABLE

public TRANSACTION_UNAVAILABLE(String s,
                               int minor,
                               CompletionStatus completed)
Constructs a TRANSACTION_UNAVAILABLE exception with the specified description message, minor code, and completion status.

Parameters:
s - the String containing a description message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TRANSIENT

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class TRANSIENT

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.TRANSIENT
All Implemented Interfaces:
Serializable
public final class TRANSIENT
extends SystemException

Exception thrown when the ORB attempted to reach an object and failed. It is not an indication that an object does not exist. Instead, it simply means that no further determination of an object's status was possible because it could not be reached. This exception is raised if an attempt to establish a connection fails, for example, because the server or the implementation repository is down.

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
TRANSIENT()
Constructs a TRANSIENT exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.
TRANSIENT(int minor, CompletionStatus completed)
Constructs a TRANSIENT exception with the specified minor code and completion status.
TRANSIENT(String s)
Constructs a TRANSIENT exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.
TRANSIENT(String s, int minor, CompletionStatus completed)
Constructs a TRANSIENT exception with the specified description message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TRANSIENT

public TRANSIENT()
Constructs a TRANSIENT exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.

TRANSIENT

public TRANSIENT(String s)
Constructs a TRANSIENT exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message

TRANSIENT

public TRANSIENT(int minor,
                 CompletionStatus completed)
Constructs a TRANSIENT exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

TRANSIENT

public TRANSIENT(String s,
                 int minor,
                 CompletionStatus completed)
Constructs a TRANSIENT exception with the specified description message, minor code, and completion status.

Parameters:
s - the String containing a description message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TypeCode

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class TypeCode

java.lang.Object
    extended by  org.omg.CORBA.TypeCode
All Implemented Interfaces:
Serializable, IDLEntity
public abstract class TypeCode
extends Object
implements IDLEntity

A container for information about a specific CORBA data type.

TypeCode objects are used:

  • in the Dynamic Invocation Interface -- to indicate the types of the actual arguments or the type of the return value.
    NamedValue objects are used to represent arguments and return values. One of their components is an Any object, which in turn has as one of its components a TypeCode object.
  • by an Interface Repository to represent the type specifications that are part of many OMG IDL declarations

The representation of a TypeCode object is opaque, but abstractly, a TypeCode object consists of:

  • a kind field, which is set to an instance of the class TCKind
  • zero or more additional fields appropriate for the particular kind. For example, the TypeCode object describing the OMG IDL type 1ong has kind TCKind.tk_long and no additional fields. The TypeCode describing OMG IDL type sequence<boolean, 10> has a kind field with the value TCKind.tk_sequence and also fields with the values boolean and 10 for the type of sequence elements and the length of the sequence.

TypeCode objects can be obtained in various ways:
  1. from a call to the method Any.insert_X, where X is a basic IDL type. This method creates a TypeCode object for type X and assigns it to the Any object's type field.
  2. from invocations of methods in the ORB class

    For example, the following creates a TypeCode object for a string with a maximum of 30 characters:

       org.omg.CORBA.TypeCode tcString = orb.create_string_tc(30);

    The following creates a TypeCode object for an array of five strings:

       org.omg.CORBA.TypeCode tcArray = orb.create_array_tc(
                                       5, TCKind.tk_string);

    The following creates a TypeCode object for an interface named "Account":

       org.omg.CORBA.TypeCode tcInterface = orb.create_interface_tc(
                                                 "thisId", "Account");
  3. as the return value from the _type method in Holder classes for user-defined IDL types. These Holder classes are generated by the idltojava compiler.
  4. from a CORBA Interface Repository

Most of the methods in the class TypeCode are accessors, and the information contained in a TypeCode object is specific to a particular type. Therefore, methods must be invoked only on the kind of type codes to which they apply. If an accessor method tries to access information from an inappropriate kind of type code, it will throw the exception TypeCodePackage.BadKind. For example, if the method discriminator_type is called on anything other than a union, it will throw BadKind because only unions have a discriminator. The following list shows which methods apply to which kinds of type codes:

These methods may be invoked on all TypeCode kinds:

  • equal
  • kind

These methods may be invoked on objref, struct, union, enum, alias, exception, value, value_box, native, and abstract_interface:

  • id
  • name

These methods may be invoked on struct, union, enum, and exception:

  • member_count
  • member_name

These methods may be invoked on struct, union, and exception:

  • member_type(int index)

These methods may be invoked on union:

  • member_label
  • discriminator_type
  • default_index

These methods may be invoked on string, sequence, and array:

  • length

These methods may be invoked on alias, sequence, array, and value_box:

  • content_type

Unlike other CORBA pseudo-objects, TypeCode objects can be passed as general IDL parameters.

The methods parameter and param_count, which are deprecated, are not mapped.

Java IDL extends the CORBA specification to allow all operations permitted on a struct TypeCode to be permitted on an exception TypeCode as well.

Constructor Summary
TypeCode()
Method Summary
abstract TypeCode | concrete_base_type() Returns the TypeCode object that describes the concrete base type of the value type that this TypeCode object describes.
abstract TypeCode | content_type() Returns the TypeCode object representing the IDL type for the members of the object described by this TypeCode object.
abstract int | default_index() Returns the index of the default member, or -1 if there is no default member.
abstract TypeCode | discriminator_type() Returns a TypeCode object describing all non-default member labels.
abstract boolean | equal(TypeCode tc) Compares this TypeCode object with the given one, testing for equality.
abstract boolean | equivalent(TypeCode tc) Tests to see if the given TypeCode object is equivalent to this TypeCode object.
abstract short | fixed_digits() Returns the number of digits in the fixed type described by this TypeCode object.
abstract short | fixed_scale() Returns the scale of the fixed type described by this TypeCode object.
abstract TypeCode | get_compact_typecode() Strips out all optional name and member name fields, but leaves all alias typecodes intact.
abstract String | id() Retrieves the RepositoryId globally identifying the type of this TypeCode object.
abstract TCKind | kind() Retrieves the kind of this TypeCode object.
abstract int | length() Returns the number of elements in the type described by this TypeCode object.
abstract int | member_count() Retrieves the number of members in the type described by this TypeCode object.
abstract Any | member_label(int index) Retrieves the label of the union member identified by the given index.
abstract String | member_name(int index) Retrieves the simple name of the member identified by the given index.
abstract TypeCode | member_type(int index) Retrieves the TypeCode object describing the type of the member identified by the given index.
abstract short | member_visibility(int index) Returns the constant that indicates the visibility of the member at the given index.
abstract String | name() Retrieves the simple name identifying this TypeCode object within its enclosing scope.
abstract short | type_modifier() Returns a constant indicating the modifier of the value type that this TypeCode object describes.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TypeCode

public TypeCode()
Method Detail

equal

public abstract boolean equal(TypeCode tc)
Compares this TypeCode object with the given one, testing for equality. TypeCode objects are equal if they are interchangeable and give identical results when TypeCode operations are applied to them.

Parameters:
tc - the TypeCode object to compare against
Returns:
true if the type codes are equal; false otherwise

equivalent

public abstract boolean equivalent(TypeCode tc)
Tests to see if the given TypeCode object is equivalent to this TypeCode object.

Parameters:
tc - the typecode to compare with this typecode
Returns:
true if the given typecode is equivalent to this typecode; false otherwise

get_compact_typecode

public abstract TypeCode get_compact_typecode()
Strips out all optional name and member name fields, but leaves all alias typecodes intact.

Returns:
a TypeCode object with optional name and member name fields stripped out, except for alias typecodes, which are left intact
See Also:
CORBA package comments for unimplemented features

kind

public abstract TCKind kind()
Retrieves the kind of this TypeCode object. The kind of a type code determines which TypeCode methods may legally be invoked on it.

The method kind may be invoked on any TypeCode object.

Returns:
the TCKind instance indicating the value of the kind field of this TypeCode object

id

public abstract String id()
                   throws BadKind
Retrieves the RepositoryId globally identifying the type of this TypeCode object.

The method id can be invoked on object reference, structure, union, enumeration, alias, exception, valuetype, boxed valuetype, native, and abstract interface type codes. Object reference, exception, valuetype, boxed valuetype, native, and abstract interface TypeCode objects always have a RepositoryId. Structure, union, enumeration, and alias TypeCode objects obtained from the Interface Repository or the method ORB.create_operation_list also always have a RepositoryId. If there is no RepositoryId, the method can return an empty string.

Returns:
the RepositoryId for this TypeCode object or an empty string if there is no RepositoryID
Throws:
BadKind - if the method is invoked on an inappropriate kind ofTypeCode object

name

public abstract String name()
                     throws BadKind
Retrieves the simple name identifying this TypeCode object within its enclosing scope. Since names are local to a Repository, the name returned from a TypeCode object may not match the name of the type in any particular Repository, and may even be an empty string.

The method name can be invoked on object reference, structure, union, enumeration, alias, exception, valuetype, boxed valuetype, native, and abstract interface TypeCode objects.

Returns:
the name identifying this TypeCode object or an empty string
Throws:
BadKind - if the method is invoked on an inappropriate kind ofTypeCode object

member_count

public abstract int member_count()
                          throws BadKind
Retrieves the number of members in the type described by this TypeCode object.

The method member_count can be invoked on structure, union, and enumeration TypeCode objects. Java IDL extends the CORBA specification to allow this method to operate on exceptions as well.

Returns:
the number of members constituting the type described by this TypeCode object
Throws:
BadKind - if the method is invoked on an inappropriate kind of TypeCode object

member_name

public abstract String member_name(int index)
                            throws BadKind,
                                   Bounds
Retrieves the simple name of the member identified by the given index. Since names are local to a Repository, the name returned from a TypeCode object may not match the name of the member in any particular Repository, and may even be an empty string.

The method member_name can be invoked on structure, union, and enumeration TypeCode objects. Java IDL extends the CORBA specification to allow this method to operate on exceptions as well.

Parameters:
index - index of the member for which a name is being reqested
Returns:
simple name of the member identified by the index or an empty string
Throws:
Bounds - if the index is equal to or greater than the number of members constituting the type
BadKind - if the method is invoked on an inappropriate kind of TypeCode object

member_type

public abstract TypeCode member_type(int index)
                              throws BadKind,
                                     Bounds
Retrieves the TypeCode object describing the type of the member identified by the given index.

The method member_type can be invoked on structure and union TypeCode objects. Java IDL extends the CORBA specification to allow this method to operate on exceptions as well.

Parameters:
index - index of the member for which type information is begin requested
Returns:
the TypeCode object describing the member at the given index
Throws:
Bounds - if the index is equal to or greater than the number of members constituting the type
BadKind - if the method is invoked on an inappropriate kind of TypeCode object

member_label

public abstract Any member_label(int index)
                          throws BadKind,
                                 Bounds
Retrieves the label of the union member identified by the given index. For the default member, the label is the zero octet.

The method member_label can only be invoked on union TypeCode objects.

Parameters:
index - index of the union member for which the label is being requested
Returns:
an Any object describing the label of the requested union member or the zero octet for the default member
Throws:
Bounds - if the index is equal to or greater than the number of members constituting the union
BadKind - if the method is invoked on a non-union TypeCode object

discriminator_type

public abstract TypeCode discriminator_type()
                                     throws BadKind
Returns a TypeCode object describing all non-default member labels. The method discriminator_type can be invoked only on union TypeCode objects.

Returns:
the TypeCode object describing the non-default member labels
Throws:
BadKind - if the method is invoked on a non-union TypeCode object

default_index

public abstract int default_index()
                           throws BadKind
Returns the index of the default member, or -1 if there is no default member.

The method default_index can be invoked only on union TypeCode objects.

Returns:
the index of the default member, or -1 if there is no default member
Throws:
BadKind - if the method is invoked on a non-union TypeCode object

length

public abstract int length()
                    throws BadKind
Returns the number of elements in the type described by this TypeCode object. For strings and sequences, it returns the bound, with zero indicating an unbounded string or sequence. For arrays, it returns the number of elements in the array.

The method length can be invoked on string, sequence, and array TypeCode objects.

Returns:
the bound for strings and sequences, or the number of elements for arrays
Throws:
BadKind - if the method is invoked on an inappropriate kind of TypeCode object

content_type

public abstract TypeCode content_type()
                               throws BadKind
Returns the TypeCode object representing the IDL type for the members of the object described by this TypeCode object. For sequences and arrays, it returns the element type. For aliases, it returns the original type. Note that multidimensional arrays are represented by nesting TypeCode objects, one per dimension. For boxed valuetypes, it returns the boxed type.

The method content_type can be invoked on sequence, array, alias, and boxed valuetype TypeCode objects.

Returns:
a TypeCode object representing the element type for sequences and arrays, the original type for aliases, or the boxed type for boxed valuetypes.
Throws:
BadKind - if the method is invoked on an inappropriate kind of TypeCode object

fixed_digits

public abstract short fixed_digits()
                            throws BadKind
Returns the number of digits in the fixed type described by this TypeCode object. For example, the typecode for the number 3000.275d could be fixed<7,3>, where 7 is the precision and 3 is the scale.

Returns:
the total number of digits
Throws:
BadKind - if this method is invoked on an inappropriate kind of TypeCode object

fixed_scale

public abstract short fixed_scale()
                           throws BadKind
Returns the scale of the fixed type described by this TypeCode object. A positive number indicates the number of digits to the right of the decimal point. For example, the number 3000d could have the typecode fixed<4,0>, where the first number is the precision and the second number is the scale. A negative number is also possible and adds zeroes to the left of the decimal point. In this case, fixed<1,-3>, could be the typecode for the number 3000d.

Returns:
the scale of the fixed type that this TypeCode object describes
Throws:
BadKind - if this method is invoked on an inappropriate kind of TypeCode object

member_visibility

public abstract short member_visibility(int index)
                                 throws BadKind,
                                        Bounds
Returns the constant that indicates the visibility of the member at the given index. This operation can only be invoked on non-boxed value TypeCode objects.

Parameters:
index - an int indicating the index into the value
Returns:
either PRIVATE_MEMBER.value or PUBLIC_MEMBER.value
Throws:
BadKind - if this method is invoked on a non-value type TypeCode object
Bounds - if the given index is out of bounds
See Also:
CORBA package comments for unimplemented features

type_modifier

public abstract short type_modifier()
                             throws BadKind
Returns a constant indicating the modifier of the value type that this TypeCode object describes. The constant returned must be one of the following: VM_NONE.value, VM_ABSTRACT.value, VM_CUSTOM.value, or VM_TRUNCATABLE.value,

Returns:
a constant describing the value type that this TypeCode object describes
Throws:
BadKind - if this method is invoked on a non-value type TypeCode object
See Also:
CORBA package comments for unimplemented features

concrete_base_type

public abstract TypeCode concrete_base_type()
                                     throws BadKind
Returns the TypeCode object that describes the concrete base type of the value type that this TypeCode object describes. Returns null if it doesn't have a concrete base type.

Returns:
the TypeCode object that describes the concrete base type of the value type that this TypeCode object describes
Throws:
BadKind - if this method is invoked on a non-boxed value type TypeCode object
See Also:
CORBA package comments for unimplemented features
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TypeCodeHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class TypeCodeHolder

java.lang.Object
    extended by  org.omg.CORBA.TypeCodeHolder
All Implemented Interfaces:
Streamable
public final class TypeCodeHolder
extends Object
implements Streamable

The Holder for TypeCode. For more information on Holder files, see "Generated Files: Holder Files".

A Holder class for a TypeCode object that is used to store "out" and "inout" parameters in IDL operations. If an IDL operation signature has an IDL TypeCode as an "out" or "inout" parameter, the programmer must pass an instance of TypeCodeHolder as the corresponding parameter in the method invocation; for "inout" parameters, the programmer must also fill the "in" value to be sent to the server. Before the method invocation returns, the ORB will fill in the value corresponding to the "out" value returned from the server.

If myTypeCodeHolder is an instance of TypeCodeHolder, the value stored in its value field can be accessed with myTypeCodeHolder.value.

Since:
JDK1.2

Field Summary
 TypeCode value
The TypeCode value held by this TypeCodeHolder object.
Constructor Summary
TypeCodeHolder()
Constructs a new TypeCodeHolder object with its value field initialized to null.
TypeCodeHolder(TypeCode initial)
Constructs a new TypeCodeHolder object with its value field initialized to the given TypeCode object.
Method Summary
void | _read(InputStream input) Reads from input and initalizes the value in this TypeCodeHolder object with the unmarshalled data.
TypeCode | _type() Returns the TypeCode corresponding to the value held in this TypeCodeHolder object.
void | _write(OutputStream output) Marshals to output the value in this TypeCodeHolder object.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public TypeCode value
The TypeCode value held by this TypeCodeHolder object.

Constructor Detail

TypeCodeHolder

public TypeCodeHolder()
Constructs a new TypeCodeHolder object with its value field initialized to null.

TypeCodeHolder

public TypeCodeHolder(TypeCode initial)
Constructs a new TypeCodeHolder object with its value field initialized to the given TypeCode object.

Parameters:
initial - the TypeCode object with which to initialize the value field of the newly-created TypeCodeHolder object
Method Detail

_read

public void _read(InputStream input)
Reads from input and initalizes the value in this TypeCodeHolder object with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
input - the InputStream containing CDR formatted data from the wire

_write

public void _write(OutputStream output)
Marshals to output the value in this TypeCodeHolder object.

Specified by:
_write in interface Streamable
Parameters:
output - the OutputStream which will contain the CDR formatted data

_type

public TypeCode _type()
Returns the TypeCode corresponding to the value held in this TypeCodeHolder object.

Specified by:
_type in interface Streamable
Returns:
the TypeCode of the value held in this TypeCodeHolder object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TypeCodePackage

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.CORBA.TypeCodePackage

Provides the user-defined exceptions BadKind and Bounds, which are thrown by methods in in the class TypeCode.

See:
Description

Exception Summary
BadKind | The exception BadKind is thrown when an inappropriate operation is invoked on a TypeCode object.
Bounds | Provides the TypeCode operations member_name(), member_type(), and member_label.

Package org.omg.CORBA.TypeCodePackage Description

Provides the user-defined exceptions BadKind and Bounds, which are thrown by methods in in the class TypeCode.

Related Documentation

For an overview, please see:
  • comments on the CORBA package

Since:
JDK1.2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.CORBA.TypeCodePackage Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.CORBA.TypeCodePackage

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.omg.CORBA.UserException (implements org.omg.CORBA.portable.IDLEntity)
          • org.omg.CORBA.TypeCodePackage.BadKind
          • org.omg.CORBA.TypeCodePackage.Bounds
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.CORBA.TypeCodePackage

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.CORBA.TypeCodePackage

Packages that use org.omg.CORBA.TypeCodePackage
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Classes in org.omg.CORBA.TypeCodePackage used by org.omg.CORBA
BadKind
The exception BadKind is thrown when an inappropriate operation is invoked on a TypeCode object.
Bounds
Provides the TypeCode operations member_name(), member_type(), and member_label.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


BadKind

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.TypeCodePackage
Class BadKind

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CORBA.TypeCodePackage.BadKind
All Implemented Interfaces:
Serializable, IDLEntity
public final class BadKind
extends UserException

The exception BadKind is thrown when an inappropriate operation is invoked on a TypeCode object. For example, invoking the method discriminator_type() on an instance of TypeCode that does not represent an IDL union will cause the exception BadKind to be thrown.

Since:
JDK1.2
See Also:
TypeCode

Constructor Summary
BadKind()
Constructs a BadKind exception with no reason message.
BadKind(String reason)
Constructs a BadKind exception with the specified reason message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

BadKind

public BadKind()
Constructs a BadKind exception with no reason message.

BadKind

public BadKind(String reason)
Constructs a BadKind exception with the specified reason message.

Parameters:
reason - the String containing a reason message
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Bounds

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA.TypeCodePackage
Class Bounds

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CORBA.TypeCodePackage.Bounds
All Implemented Interfaces:
Serializable, IDLEntity
public final class Bounds
extends UserException

Provides the TypeCode operations member_name(), member_type(), and member_label. These methods raise Bounds when the index parameter is greater than or equal to the number of members constituting the type.

Since:
JDK1.2

Constructor Summary
Bounds()
Constructs a Bounds exception with no reason message.
Bounds(String reason)
Constructs a Bounds exception with the specified reason message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Bounds

public Bounds()
Constructs a Bounds exception with no reason message.

Bounds

public Bounds(String reason)
Constructs a Bounds exception with the specified reason message.

Parameters:
reason - the String containing a reason message
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class org.omg.CORBA.TypeCodePackage.BadKind

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.TypeCodePackage.BadKind

Packages that use BadKind
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of BadKind in org.omg.CORBA

Methods in org.omg.CORBA that throw BadKind
abstract TypeCode | TypeCode.concrete_base_type() Returns the TypeCode object that describes the concrete base type of the value type that this TypeCode object describes.
abstract TypeCode | TypeCode.content_type() Returns the TypeCode object representing the IDL type for the members of the object described by this TypeCode object.
abstract int | TypeCode.default_index() Returns the index of the default member, or -1 if there is no default member.
abstract TypeCode | TypeCode.discriminator_type() Returns a TypeCode object describing all non-default member labels.
abstract short | TypeCode.fixed_digits() Returns the number of digits in the fixed type described by this TypeCode object.
abstract short | TypeCode.fixed_scale() Returns the scale of the fixed type described by this TypeCode object.
abstract String | TypeCode.id() Retrieves the RepositoryId globally identifying the type of this TypeCode object.
abstract int | TypeCode.length() Returns the number of elements in the type described by this TypeCode object.
abstract int | TypeCode.member_count() Retrieves the number of members in the type described by this TypeCode object.
abstract Any | TypeCode.member_label(int index) Retrieves the label of the union member identified by the given index.
abstract String | TypeCode.member_name(int index) Retrieves the simple name of the member identified by the given index.
abstract TypeCode | TypeCode.member_type(int index) Retrieves the TypeCode object describing the type of the member identified by the given index.
abstract short | TypeCode.member_visibility(int index) Returns the constant that indicates the visibility of the member at the given index.
abstract String | TypeCode.name() Retrieves the simple name identifying this TypeCode object within its enclosing scope.
abstract short | TypeCode.type_modifier() Returns a constant indicating the modifier of the value type that this TypeCode object describes.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA.TypeCodePackage.Bounds

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA.TypeCodePackage.Bounds

Packages that use Bounds
org.omg.CORBA Provides the mapping of the OMG CORBA APIs to the JavaTM programming language, including the class ORB, which is implemented so that a programmer can use it as a fully-functional Object Request Broker (ORB).

Uses of Bounds in org.omg.CORBA

Methods in org.omg.CORBA that throw Bounds
abstract Any | TypeCode.member_label(int index) Retrieves the label of the union member identified by the given index.
abstract String | TypeCode.member_name(int index) Retrieves the simple name of the member identified by the given index.
abstract TypeCode | TypeCode.member_type(int index) Retrieves the TypeCode object describing the type of the member identified by the given index.
abstract short | TypeCode.member_visibility(int index) Returns the constant that indicates the visibility of the member at the given index.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ULongLongSeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ULongLongSeqHelper

java.lang.Object
    extended by  org.omg.CORBA.ULongLongSeqHelper

public abstract class ULongLongSeqHelper
extends Object

The Helper for ULongLongSeq. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/ULongLongSeqHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:37 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications :

  • ORB core as defined by CORBA 2.3.1 (formal/99-10-07)
  • IDL/Java Language Mapping as defined in ptc/00-01-08

Constructor Summary
ULongLongSeqHelper()
Method Summary
static long[] | extract(Any a)
static String | id()
static void | insert(Any a, long[] that)
static long[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, long[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ULongLongSeqHelper

public ULongLongSeqHelper()
Method Detail

insert

public static void insert(Any a,
                          long[] that)

extract

public static long[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static long[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         long[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ULongLongSeqHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ULongLongSeqHolder

java.lang.Object
    extended by  org.omg.CORBA.ULongLongSeqHolder
All Implemented Interfaces:
Streamable
public final class ULongLongSeqHolder
extends Object
implements Streamable

The Holder for ULongLongSeq. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/ULongLongSeqHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:37 o'clock GMT+00:00

Field Summary
 long[] value
Constructor Summary
ULongLongSeqHolder()
ULongLongSeqHolder(long[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public long[] value
Constructor Detail

ULongLongSeqHolder

public ULongLongSeqHolder()

ULongLongSeqHolder

public ULongLongSeqHolder(long[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ULongSeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ULongSeqHelper

java.lang.Object
    extended by  org.omg.CORBA.ULongSeqHelper

public abstract class ULongSeqHelper
extends Object

The Helper for ULongSeq. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/ULongSeqHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications :

  • ORB core as defined by CORBA 2.3.1 (formal/99-10-07)
  • IDL/Java Language Mapping as defined in ptc/00-01-08

Constructor Summary
ULongSeqHelper()
Method Summary
static int[] | extract(Any a)
static String | id()
static void | insert(Any a, int[] that)
static int[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, int[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ULongSeqHelper

public ULongSeqHelper()
Method Detail

insert

public static void insert(Any a,
                          int[] that)

extract

public static int[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static int[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         int[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ULongSeqHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ULongSeqHolder

java.lang.Object
    extended by  org.omg.CORBA.ULongSeqHolder
All Implemented Interfaces:
Streamable
public final class ULongSeqHolder
extends Object
implements Streamable

The Holder for ULongSeq. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/ULongSeqHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00

Field Summary
 int[] value
Constructor Summary
ULongSeqHolder()
ULongSeqHolder(int[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public int[] value
Constructor Detail

ULongSeqHolder

public ULongSeqHolder()

ULongSeqHolder

public ULongSeqHolder(int[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UnionMember

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class UnionMember

java.lang.Object
    extended by  org.omg.CORBA.UnionMember
All Implemented Interfaces:
Serializable, IDLEntity
public final class UnionMember
extends Object
implements IDLEntity

A description in the Interface Repository of a member of an IDL union.

Field Summary
Any | label The label of the union member described by this UnionMember object.
String | name The name of the union member described by this UnionMember object.
TypeCode | type The type of the union member described by this UnionMember object.
IDLType | type_def The typedef that represents the IDL type of the union member described by this UnionMember object.
Constructor Summary
UnionMember()
Constructs a new UnionMember object with its fields initialized to null.
UnionMember(String __name, Any __label, TypeCode __type, IDLType __type_def)
Constructs a new UnionMember object with its fields initialized to the given values.
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

name

public String name
The name of the union member described by this UnionMember object.

label

public Any label
The label of the union member described by this UnionMember object.

type

public TypeCode type
The type of the union member described by this UnionMember object.

type_def

public IDLType type_def
The typedef that represents the IDL type of the union member described by this UnionMember object.

Constructor Detail

UnionMember

public UnionMember()
Constructs a new UnionMember object with its fields initialized to null.

UnionMember

public UnionMember(String __name,
                   Any __label,
                   TypeCode __type,
                   IDLType __type_def)
Constructs a new UnionMember object with its fields initialized to the given values.

Parameters:
__name - a String object with the name of this UnionMember object
__label - an Any object with the label of this UnionMember object
__type - a TypeCode object describing the type of this UnionMember object
__type_def - an IDLType object that represents the IDL type of this UnionMember object
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UnionMemberHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class UnionMemberHelper

java.lang.Object
    extended by  org.omg.CORBA.UnionMemberHelper

public abstract class UnionMemberHelper
extends Object

The Helper for UnionMember. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/UnionMemberHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ir.idl 03 June 1999 11:33:43 o'clock GMT+00:00

Constructor Summary
UnionMemberHelper()
Method Summary
static UnionMember | extract(Any a)
static String | id()
static void | insert(Any a, UnionMember that)
static UnionMember | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, UnionMember value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UnionMemberHelper

public UnionMemberHelper()
Method Detail

insert

public static void insert(Any a,
                          UnionMember that)

extract

public static UnionMember extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static UnionMember read(InputStream istream)

write

public static void write(OutputStream ostream,
                         UnionMember value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UNKNOWN

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class UNKNOWN

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.omg.CORBA.SystemException
                    extended by  org.omg.CORBA.UNKNOWN
All Implemented Interfaces:
Serializable
public final class UNKNOWN
extends SystemException

This exception is raised if an operation implementation throws a non-CORBA exception (such as an exception specific to the implementation's programming language), or if an operation raises a user exception that does not appear in the operation's raises expression. UNKNOWN is also raised if the server returns a system exception that is unknown to the client. (This can happen if the server uses a later version of CORBA than the client and new system exceptions have been added to the later version.)

It contains a minor code, which gives more detailed information about what caused the exception, and a completion status. It may also contain a string describing the exception.

See the section Minor Code Meanings to see the minor codes for this exception.

See Also:
documentation on Java IDL exceptions

Field Summary
Fields inherited from class org.omg.CORBA.SystemException
completed, minor
Constructor Summary
UNKNOWN()
Constructs an UNKNOWN exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.
UNKNOWN(int minor, CompletionStatus completed)
Constructs an UNKNOWN exception with the specified minor code and completion status.
UNKNOWN(String s)
Constructs an UNKNOWN exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.
UNKNOWN(String s, int minor, CompletionStatus completed)
Constructs an UNKNOWN exception with the specified description message, minor code, and completion status.
Method Summary
Methods inherited from class org.omg.CORBA.SystemException
toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UNKNOWN

public UNKNOWN()
Constructs an UNKNOWN exception with a default minor code of 0, a completion state of CompletionStatus.COMPLETED_NO, and a null description.

UNKNOWN

public UNKNOWN(String s)
Constructs an UNKNOWN exception with the specified description message, a minor code of 0, and a completion state of COMPLETED_NO.

Parameters:
s - the String containing a detail message

UNKNOWN

public UNKNOWN(int minor,
               CompletionStatus completed)
Constructs an UNKNOWN exception with the specified minor code and completion status.

Parameters:
minor - the minor code
completed - the completion status

UNKNOWN

public UNKNOWN(String s,
               int minor,
               CompletionStatus completed)
Constructs an UNKNOWN exception with the specified description message, minor code, and completion status.

Parameters:
s - the String containing a description message
minor - the minor code
completed - the completion status
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UnknownUserException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class UnknownUserException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CORBA.UnknownUserException
All Implemented Interfaces:
Serializable, IDLEntity
public final class UnknownUserException
extends UserException

A class that contains user exceptions returned by the server. When the client uses the DII to make an invocation, any user exception returned from the server is enclosed in an Any object contained in the UnknownUserException object. This is available from the Environment object returned by the method Request.env.

See Also:
documentation on Java IDL exceptions, Request

Field Summary
 Any except
The Any instance that contains the actual user exception thrown by the server.
Constructor Summary
UnknownUserException()
Constructs an UnknownUserException object.
UnknownUserException(Any a)
Constructs an UnknownUserException object that contains the given Any object.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

except

public Any except
The Any instance that contains the actual user exception thrown by the server.

Constructor Detail

UnknownUserException

public UnknownUserException()
Constructs an UnknownUserException object.

UnknownUserException

public UnknownUserException(Any a)
Constructs an UnknownUserException object that contains the given Any object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UnknownUserExceptionHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class UnknownUserExceptionHelper

java.lang.Object
    extended by  org.omg.CORBA.UnknownUserExceptionHelper

public abstract class UnknownUserExceptionHelper
extends Object

The Helper for UnknownUserException. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/UnknownUserExceptionHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from CORBA.idl Thursday, August 24, 2000 5:52:22 PM PDT

Constructor Summary
UnknownUserExceptionHelper()
Method Summary
static UnknownUserException | extract(Any a)
static String | id()
static void | insert(Any a, UnknownUserException that)
static UnknownUserException | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, UnknownUserException value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UnknownUserExceptionHelper

public UnknownUserExceptionHelper()
Method Detail

insert

public static void insert(Any a,
                          UnknownUserException that)

extract

public static UnknownUserException extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static UnknownUserException read(InputStream istream)

write

public static void write(OutputStream ostream,
                         UnknownUserException value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UnknownUserExceptionHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class UnknownUserExceptionHolder

java.lang.Object
    extended by  org.omg.CORBA.UnknownUserExceptionHolder
All Implemented Interfaces:
Streamable
public final class UnknownUserExceptionHolder
extends Object
implements Streamable

The Holder for UnknownUserException. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/UnknownUserExceptionHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from CORBA.idl Thursday, August 24, 2000 5:52:22 PM PDT

Field Summary
 UnknownUserException value
Constructor Summary
UnknownUserExceptionHolder()
UnknownUserExceptionHolder(UnknownUserException initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public UnknownUserException value
Constructor Detail

UnknownUserExceptionHolder

public UnknownUserExceptionHolder()

UnknownUserExceptionHolder

public UnknownUserExceptionHolder(UnknownUserException initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UNSUPPORTED_POLICY

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface UNSUPPORTED_POLICY

public interface UNSUPPORTED_POLICY

One of the PolicyErrorCodes which would be filled if the requested Policy is understood to be valid by the ORB, but is not currently supported.

Field Summary
static short value
The Error code for PolicyError exception.

Field Detail

value

static final short value
The Error code for PolicyError exception.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UNSUPPORTED_POLICY_VALUE

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface UNSUPPORTED_POLICY_VALUE

public interface UNSUPPORTED_POLICY_VALUE

A PolicyErrorCode which would be filled if the value requested for the Policy is of a valid type and within the valid range for that type, but this valid value is not currently supported.

Field Summary
static short value
The Error code for PolicyError exception.

Field Detail

value

static final short value
The Error code for PolicyError exception.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UserException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class UserException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
All Implemented Interfaces:
Serializable, IDLEntity
Direct Known Subclasses:
AdapterAlreadyExists, AdapterInactive, AdapterNonExistent, AlreadyBound, BadKind, Bounds, Bounds, CannotProceed, DuplicateName, FormatMismatch, ForwardRequest, ForwardRequest, InconsistentTypeCode, InconsistentTypeCode, Invalid, InvalidAddress, InvalidName, InvalidName, InvalidName, InvalidPolicy, InvalidSeq, InvalidSlot, InvalidTypeForEncoding, InvalidValue, InvalidValue, NoContext, NoServant, NotEmpty, NotFound, ObjectAlreadyActive, ObjectNotActive, PolicyError, ServantAlreadyActive, ServantNotActive, TypeMismatch, TypeMismatch, TypeMismatch, UnknownEncoding, UnknownUserException, WrongAdapter, WrongPolicy, WrongTransaction
public abstract class UserException
extends Exception
implements IDLEntity

The root class for CORBA IDL-defined user exceptions. All CORBA user exceptions are checked exceptions, which means that they need to be declared in method signatures.

See Also:
documentation on Java IDL exceptions

Constructor Summary
protected | UserException() Constructs a UserException object.
protected | UserException(String reason) Constructs a UserException object with a detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UserException

protected UserException()
Constructs a UserException object. This method is called only by subclasses.

UserException

protected UserException(String reason)
Constructs a UserException object with a detail message. This method is called only by subclasses.

Parameters:
reason - a String object giving the reason for this exception
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UShortSeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class UShortSeqHelper

java.lang.Object
    extended by  org.omg.CORBA.UShortSeqHelper

public abstract class UShortSeqHelper
extends Object

The Helper for UShortSeq. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/UShortSeqHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications :

  • ORB core as defined by CORBA 2.3.1 (formal/99-10-07)
  • IDL/Java Language Mapping as defined in ptc/00-01-08

Constructor Summary
UShortSeqHelper()
Method Summary
static short[] | extract(Any a)
static String | id()
static void | insert(Any a, short[] that)
static short[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, short[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UShortSeqHelper

public UShortSeqHelper()
Method Detail

insert

public static void insert(Any a,
                          short[] that)

extract

public static short[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static short[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         short[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UShortSeqHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class UShortSeqHolder

java.lang.Object
    extended by  org.omg.CORBA.UShortSeqHolder
All Implemented Interfaces:
Streamable
public final class UShortSeqHolder
extends Object
implements Streamable

The Holder for UShortSeq. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/UShortSeqHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00

Field Summary
 short[] value
Constructor Summary
UShortSeqHolder()
UShortSeqHolder(short[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public short[] value
Constructor Detail

UShortSeqHolder

public UShortSeqHolder()

UShortSeqHolder

public UShortSeqHolder(short[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ValueBaseHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ValueBaseHelper

java.lang.Object
    extended by  org.omg.CORBA.ValueBaseHelper

public abstract class ValueBaseHelper
extends Object

Constructor Summary
ValueBaseHelper()
Method Summary
static Serializable | extract(Any a)
static String | id()
static void | insert(Any a, Serializable that)
static Serializable | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, Serializable value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ValueBaseHelper

public ValueBaseHelper()
Method Detail

insert

public static void insert(Any a,
                          Serializable that)

extract

public static Serializable extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static Serializable read(InputStream istream)

write

public static void write(OutputStream ostream,
                         Serializable value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ValueBaseHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ValueBaseHolder

java.lang.Object
    extended by  org.omg.CORBA.ValueBaseHolder
All Implemented Interfaces:
Streamable
public final class ValueBaseHolder
extends Object
implements Streamable

The Holder for ValueBase. For more information on Holder files, see "Generated Files: Holder Files".

A Holder class for a java.io.Serializable that is used to store "out" and "inout" parameters in IDL methods. If an IDL method signature has an IDL ValueBase as an "out" or "inout" parameter, the programmer must pass an instance of ValueBaseHolder as the corresponding parameter in the method invocation; for "inout" parameters, the programmer must also fill the "in" value to be sent to the server. Before the method invocation returns, the ORB will fill in the value corresponding to the "out" value returned from the server.

If myValueBaseHolder is an instance of ValueBaseHolder, the value stored in its value field can be accessed with myValueBaseHolder.value.

Field Summary
 Serializable value
The java.io.Serializable value held by this ValueBaseHolder object.
Constructor Summary
ValueBaseHolder()
Constructs a new ValueBaseHolder object with its value field initialized to 0.
ValueBaseHolder(Serializable initial)
Constructs a new ValueBaseHolder object with its value field initialized to the given java.io.Serializable.
Method Summary
void | _read(InputStream input) Reads from input and initalizes the value in the Holder with the unmarshalled data.
TypeCode | _type() Returns the TypeCode object corresponding to the value held in the Holder.
void | _write(OutputStream output) Marshals to output the value in the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public Serializable value
The java.io.Serializable value held by this ValueBaseHolder object.

Constructor Detail

ValueBaseHolder

public ValueBaseHolder()
Constructs a new ValueBaseHolder object with its value field initialized to 0.

ValueBaseHolder

public ValueBaseHolder(Serializable initial)
Constructs a new ValueBaseHolder object with its value field initialized to the given java.io.Serializable.

Parameters:
initial - the java.io.Serializable with which to initialize the value field of the newly-created ValueBaseHolder object
Method Detail

_read

public void _read(InputStream input)
Reads from input and initalizes the value in the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
input - the InputStream containing CDR formatted data from the wire

_write

public void _write(OutputStream output)
Marshals to output the value in the Holder.

Specified by:
_write in interface Streamable
Parameters:
output - the OutputStream which will contain the CDR formatted data

_type

public TypeCode _type()
Returns the TypeCode object corresponding to the value held in the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode of the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ValueMember

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ValueMember

java.lang.Object
    extended by  org.omg.CORBA.ValueMember
All Implemented Interfaces:
Serializable, IDLEntity
public final class ValueMember
extends Object
implements IDLEntity

A description in the Interface Repository of a member of a value object.

Field Summary
short | access The type of access (public, private) for the value member described by this ValueMember object.
String | defined_in The repository ID of the value in which this member is defined.
String | id The repository ID of the value member described by this ValueMember object;
String | name The name of the value member described by this ValueMember object.
TypeCode | type The type of of this value member.
IDLType | type_def The typedef that represents the IDL type of the value member described by this ValueMember object.
String | version The version of the value in which this member is defined.
Constructor Summary
ValueMember()
Constructs a default ValueMember object.
ValueMember(String __name, String __id, String __defined_in, String __version, TypeCode __type, IDLType __type_def, short __access)
Constructs a ValueMember object initialized with the given values.
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

name

public String name
The name of the value member described by this ValueMember object.

id

public String id
The repository ID of the value member described by this ValueMember object;

defined_in

public String defined_in
The repository ID of the value in which this member is defined.

version

public String version
The version of the value in which this member is defined.

type

public TypeCode type
The type of of this value member.

type_def

public IDLType type_def
The typedef that represents the IDL type of the value member described by this ValueMember object.

access

public short access
The type of access (public, private) for the value member described by this ValueMember object.

Constructor Detail

ValueMember

public ValueMember()
Constructs a default ValueMember object.

ValueMember

public ValueMember(String __name,
                   String __id,
                   String __defined_in,
                   String __version,
                   TypeCode __type,
                   IDLType __type_def,
                   short __access)
Constructs a ValueMember object initialized with the given values.

Parameters:
__name - The name of the value member described by this ValueMember object.
__id - The repository ID of the value member described by this ValueMember object;
__defined_in - The repository ID of the value in which this member is defined.
__version - The version of the value in which this member is defined.
__type - The type of of this value member.
__type_def - The typedef that represents the IDL type of the value member described by this ValueMember object.
__access - The type of access (public, private) for the value member described by this ValueMember object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ValueMemberHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class ValueMemberHelper

java.lang.Object
    extended by  org.omg.CORBA.ValueMemberHelper

public abstract class ValueMemberHelper
extends Object

The Helper for ValueMember. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/ValueMemberHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ir.idl 03 June 1999 11:33:44 o'clock GMT+00:00

Constructor Summary
ValueMemberHelper()
Method Summary
static ValueMember | extract(Any a)
static String | id()
static void | insert(Any a, ValueMember that)
static ValueMember | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, ValueMember value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ValueMemberHelper

public ValueMemberHelper()
Method Detail

insert

public static void insert(Any a,
                          ValueMember that)

extract

public static ValueMember extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static ValueMember read(InputStream istream)

write

public static void write(OutputStream ostream,
                         ValueMember value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VersionSpecHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class VersionSpecHelper

java.lang.Object
    extended by  org.omg.CORBA.VersionSpecHelper

public abstract class VersionSpecHelper
extends Object

The Helper for VersionSpec. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/VersionSpecHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ir.idl 03 June 1999 11:33:43 o'clock GMT+00:00

Constructor Summary
VersionSpecHelper()
Method Summary
static String | extract(Any a)
static String | id()
static void | insert(Any a, String that)
static String | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, String value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

VersionSpecHelper

public VersionSpecHelper()
Method Detail

insert

public static void insert(Any a,
                          String that)

extract

public static String extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static String read(InputStream istream)

write

public static void write(OutputStream ostream,
                         String value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VisibilityHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class VisibilityHelper

java.lang.Object
    extended by  org.omg.CORBA.VisibilityHelper

public abstract class VisibilityHelper
extends Object

The Helper for Visibility. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/VisibilityHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from ir.idl 03 June 1999 11:33:44 o'clock GMT+00:00

Constructor Summary
VisibilityHelper()
Method Summary
static short | extract(Any a)
static String | id()
static void | insert(Any a, short that)
static short | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, short value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

VisibilityHelper

public VisibilityHelper()
Method Detail

insert

public static void insert(Any a,
                          short that)

extract

public static short extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static short read(InputStream istream)

write

public static void write(OutputStream ostream,
                         short value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VM_ABSTRACT

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface VM_ABSTRACT

public interface VM_ABSTRACT

Defines the code used to represent an Abstract interface in a typecode. This is one of the possible results of the type_modified method on the TypeCode interface.

See Also:
TypeCode

Field Summary
static short value
The value representing an abstract interface value type in a typecode.

Field Detail

value

static final short value
The value representing an abstract interface value type in a typecode.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VM_CUSTOM

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface VM_CUSTOM

public interface VM_CUSTOM

Defines the code used to represent a custom marshalled value type in a typecode. This is one of the possible results of the type_modifier method on the TypeCode interface.

See Also:
TypeCode

Field Summary
static short value
The value representing a custom marshalled value type in a typecode.

Field Detail

value

static final short value
The value representing a custom marshalled value type in a typecode.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VM_NONE

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface VM_NONE

public interface VM_NONE

Defines the code used to represent the one of the values of a value type in a typecode.

Since:
JDK1.2
See Also:
TypeCode

Field Summary
static short value
The value representing the value type in a typecode as per CORBA 2.3 spec.

Field Detail

value

static final short value
The value representing the value type in a typecode as per CORBA 2.3 spec.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VM_TRUNCATABLE

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Interface VM_TRUNCATABLE

public interface VM_TRUNCATABLE

Defines the code used to represent a truncatable value type in a typecode. A value type is truncatable if it inherits "safely" from another value type, which means it can be cast to a more general inherited type. This is one of the possible results of the type_modifier method on the TypeCode interface.

See Also:
TypeCode

Field Summary
static short value
The value representing a truncatable value type in a typecode.

Field Detail

value

static final short value
The value representing a truncatable value type in a typecode.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WCharSeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class WCharSeqHelper

java.lang.Object
    extended by  org.omg.CORBA.WCharSeqHelper

public abstract class WCharSeqHelper
extends Object

The Helper for WCharSeq. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/WCharSeqHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications :

  • ORB core as defined by CORBA 2.3.1 (formal/99-10-07)
  • IDL/Java Language Mapping as defined in ptc/00-01-08

Constructor Summary
WCharSeqHelper()
Method Summary
static char[] | extract(Any a)
static String | id()
static void | insert(Any a, char[] that)
static char[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, char[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WCharSeqHelper

public WCharSeqHelper()
Method Detail

insert

public static void insert(Any a,
                          char[] that)

extract

public static char[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static char[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         char[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WCharSeqHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class WCharSeqHolder

java.lang.Object
    extended by  org.omg.CORBA.WCharSeqHolder
All Implemented Interfaces:
Streamable
public final class WCharSeqHolder
extends Object
implements Streamable

The Holder for WCharSeq. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/WCharSeqHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from streams.idl 13 May 1999 22:41:36 o'clock GMT+00:00

Field Summary
 char[] value
Constructor Summary
WCharSeqHolder()
WCharSeqHolder(char[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public char[] value
Constructor Detail

WCharSeqHolder

public WCharSeqHolder()

WCharSeqHolder

public WCharSeqHolder(char[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WrongTransaction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class WrongTransaction

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CORBA.WrongTransaction
All Implemented Interfaces:
Serializable, IDLEntity
public final class WrongTransaction
extends UserException

The CORBA WrongTransaction user-defined exception. This exception is thrown only by the methods Request.get_response and ORB.get_next_response when they are invoked from a transaction scope that is different from the one in which the client originally sent the request. See the OMG Transaction Service Specification for details.

See Also:
documentation on Java IDL exceptions

Constructor Summary
WrongTransaction()
Constructs a WrongTransaction object with an empty detail message.
WrongTransaction(String reason)
Constructs a WrongTransaction object with the given detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

WrongTransaction

public WrongTransaction()
Constructs a WrongTransaction object with an empty detail message.

WrongTransaction

public WrongTransaction(String reason)
Constructs a WrongTransaction object with the given detail message.

Parameters:
reason - The detail message explaining what caused this exception to be thrown.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WrongTransactionHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class WrongTransactionHelper

java.lang.Object
    extended by  org.omg.CORBA.WrongTransactionHelper

public abstract class WrongTransactionHelper
extends Object

The Helper for WrongTransaction. For more information on Helper files, see "Generated Files: Helper Files".

org/omg/CORBA/WrongTransactionHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from CORBA.idl Thursday, August 24, 2000 5:32:50 PM PDT

Constructor Summary
WrongTransactionHelper()
Method Summary
static WrongTransaction | extract(Any a)
static String | id()
static void | insert(Any a, WrongTransaction that)
static WrongTransaction | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, WrongTransaction value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WrongTransactionHelper

public WrongTransactionHelper()
Method Detail

insert

public static void insert(Any a,
                          WrongTransaction that)

extract

public static WrongTransaction extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static WrongTransaction read(InputStream istream)

write

public static void write(OutputStream ostream,
                         WrongTransaction value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WrongTransactionHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class WrongTransactionHolder

java.lang.Object
    extended by  org.omg.CORBA.WrongTransactionHolder
All Implemented Interfaces:
Streamable
public final class WrongTransactionHolder
extends Object
implements Streamable

The Holder for WrongTransaction. For more information on Holder files, see "Generated Files: Holder Files".

org/omg/CORBA/WrongTransactionHolder.java Generated by the IDL-to-Java compiler (portable), version "3.0" from CORBA.idl Thursday, August 24, 2000 5:32:50 PM PDT

Field Summary
 WrongTransaction value
Constructor Summary
WrongTransactionHolder()
WrongTransactionHolder(WrongTransaction initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public WrongTransaction value
Constructor Detail

WrongTransactionHolder

public WrongTransactionHolder()

WrongTransactionHolder

public WrongTransactionHolder(WrongTransaction initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WStringSeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class WStringSeqHelper

java.lang.Object
    extended by  org.omg.CORBA.WStringSeqHelper

public abstract class WStringSeqHelper
extends Object

An array of WStrings

Constructor Summary
WStringSeqHelper()
Method Summary
static String[] | extract(Any a)
static String | id()
static void | insert(Any a, String[] that)
static String[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, String[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WStringSeqHelper

public WStringSeqHelper()
Method Detail

insert

public static void insert(Any a,
                          String[] that)

extract

public static String[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static String[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         String[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WStringSeqHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class WStringSeqHolder

java.lang.Object
    extended by  org.omg.CORBA.WStringSeqHolder
All Implemented Interfaces:
Streamable
public final class WStringSeqHolder
extends Object
implements Streamable

An array of WStrings

Field Summary
 String[] value
Constructor Summary
WStringSeqHolder()
WStringSeqHolder(String[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public String[] value
Constructor Detail

WStringSeqHolder

public WStringSeqHolder()

WStringSeqHolder

public WStringSeqHolder(String[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WStringValueHelper

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA
Class WStringValueHelper

java.lang.Object
    extended by  org.omg.CORBA.WStringValueHelper
All Implemented Interfaces:
BoxedValueHelper
public class WStringValueHelper
extends Object
implements BoxedValueHelper

org/omg/CORBA/WStringValueHelper.java Generated by the IDL-to-Java compiler (portable), version "3.0" from orb.idl 31 May 1999 22:27:30 o'clock GMT+00:00 The class definition has been modified to conform to the following OMG specifications :

  • ORB core as defined by CORBA 2.3.1 (formal/99-10-07)
  • IDL/Java Language Mapping as defined in ptc/00-01-08

Constructor Summary
WStringValueHelper()
Method Summary
static String | extract(Any a)
String | get_id()
static String | id()
static void | insert(Any a, String that)
Serializable | read_value(InputStream istream)
static String | read(InputStream istream)
static TypeCode | type()
void | write_value(OutputStream ostream, Serializable value)
static void | write(OutputStream ostream, String value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WStringValueHelper

public WStringValueHelper()
Method Detail

insert

public static void insert(Any a,
                          String that)

extract

public static String extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static String read(InputStream istream)

read_value

public Serializable read_value(InputStream istream)
Specified by:
read_value in interface BoxedValueHelper

write

public static void write(OutputStream ostream,
                         String value)

write_value

public void write_value(OutputStream ostream,
                        Serializable value)
Specified by:
write_value in interface BoxedValueHelper

get_id

public String get_id()
Specified by:
get_id in interface BoxedValueHelper
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


CORBA_2_3

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.CORBA_2_3

The CORBA_2_3 package defines additions to existing CORBA interfaces in the Java[tm] Standard Edition 6. These changes occurred in recent revisions to the CORBA API defined by the OMG. The new methods were added to interfaces derived from the corresponding interfaces in the CORBA package. This provides backward compatibility and avoids breaking the JCK tests.

See:
Description

Class Summary
ORB A class extending org.omg.CORBA.ORB to make the ORB portable under the OMG CORBA version 2.3 specification.

Package org.omg.CORBA_2_3 Description

The CORBA_2_3 package defines additions to existing CORBA interfaces in the Java[tm] Standard Edition 6. These changes occurred in recent revisions to the CORBA API defined by the OMG. The new methods were added to interfaces derived from the corresponding interfaces in the CORBA package. This provides backward compatibility and avoids breaking the JCK tests.

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6, ORB complies, see Official Specifications for CORBA support in Java[tm] SE 6.

The following methods in the abstract class org.omg.CORBA_2_3.ORB are unimplemented:

  • public org.omg.CORBA.portable.ValueFactory register_value_factory(String id, org.omg.CORBA.portable.ValueFactory factory)
  • public void unregister_value_factory(String id)
  • public org.omg.CORBA.portable.ValueFactory lookup_value_factory(String id)
  • public org.omg.CORBA.Object get_value_def(String repid)
  • public void set_delegate(java.lang.Object wrapper)

Since:
JDK 1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.CORBA_2_3 Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.CORBA_2_3

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.CORBA.ORB
      • org.omg.CORBA_2_3.ORB
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.CORBA_2_3

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.CORBA_2_3

No usage of org.omg.CORBA_2_3

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA_2_3.ORB

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA_2_3.ORB

No usage of org.omg.CORBA_2_3.ORB

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ORB

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA_2_3
Class ORB

java.lang.Object
    extended by  org.omg.CORBA.ORB
        extended by  org.omg.CORBA_2_3.ORB

public abstract class ORB
extends ORB

A class extending org.omg.CORBA.ORB to make the ORB portable under the OMG CORBA version 2.3 specification.

Constructor Summary
ORB()
Method Summary
Object | get_value_def(String repid)
ValueFactory | lookup_value_factory(String id)
ValueFactory | register_value_factory(String id, ValueFactory factory)
void | set_delegate(Object wrapper)
void | unregister_value_factory(String id)
Methods inherited from class org.omg.CORBA.ORB
connect, create_abstract_interface_tc, create_alias_tc, create_any, create_array_tc, create_basic_dyn_any, create_context_list, create_dyn_any, create_dyn_array, create_dyn_enum, create_dyn_sequence, create_dyn_struct, create_dyn_union, create_enum_tc, create_environment, create_exception_list, create_exception_tc, create_fixed_tc, create_interface_tc, create_list, create_named_value, create_native_tc, create_operation_list, create_output_stream, create_policy, create_recursive_sequence_tc, create_recursive_tc, create_sequence_tc, create_string_tc, create_struct_tc, create_union_tc, create_value_box_tc, create_value_tc, create_wstring_tc, destroy, disconnect, get_current, get_default_context, get_next_response, get_primitive_tc, get_service_information, init, init, init, list_initial_services, object_to_string, perform_work, poll_next_response, resolve_initial_references, run, send_multiple_requests_deferred, send_multiple_requests_oneway, set_parameters, set_parameters, shutdown, string_to_object, work_pending
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ORB

public ORB()
Method Detail

register_value_factory

public ValueFactory register_value_factory(String id,
                                           ValueFactory factory)

unregister_value_factory

public void unregister_value_factory(String id)

lookup_value_factory

public ValueFactory lookup_value_factory(String id)

get_value_def

public Object get_value_def(String repid)
                     throws BAD_PARAM
Throws:
BAD_PARAM
See Also:
CORBA_2_3 package comments for unimplemented features

set_delegate

public void set_delegate(Object wrapper)
See Also:
CORBA_2_3 package comments for unimplemented features
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


portable

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.CORBA_2_3.portable

Provides methods for the input and output of value types, and contains other updates to the org/omg/CORBA/portable package.

See:
Description

Class Summary
Delegate | Delegate class provides the ORB vendor specific implementation of CORBA object.
InputStream | InputStream provides for the reading of all of the mapped IDL types from the stream.
ObjectImpl | ObjectImpl class is the base class for all stubs.
OutputStream | OutputStream provides interface for writing of all of the mapped IDL type to the stream.

Package org.omg.CORBA_2_3.portable Description

Provides methods for the input and output of value types, and contains other updates to the org/omg/CORBA/portable package.

Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.CORBA_2_3.portable Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.CORBA_2_3.portable

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.CORBA.portable.Delegate
      • org.omg.CORBA_2_3.portable.Delegate
    • java.io.InputStream (implements java.io.Closeable)
      • org.omg.CORBA.portable.InputStream
        • org.omg.CORBA_2_3.portable.InputStream
    • org.omg.CORBA.portable.ObjectImpl (implements org.omg.CORBA.Object)
      • org.omg.CORBA_2_3.portable.ObjectImpl
    • java.io.OutputStream (implements java.io.Closeable, java.io.Flushable)
      • org.omg.CORBA.portable.OutputStream
        • org.omg.CORBA_2_3.portable.OutputStream
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.CORBA_2_3.portable

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.CORBA_2_3.portable

Packages that use org.omg.CORBA_2_3.portable
javax.rmi.CORBA | Contains portability APIs for RMI-IIOP.
org.omg.CORBA.portable | Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.
org.omg.stub.java.rmi | Contains RMI-IIOP Stubs for the Remote types that occur in the java.rmi package.

Classes in org.omg.CORBA_2_3.portable used by javax.rmi.CORBA
ObjectImpl
ObjectImpl class is the base class for all stubs.

Classes in org.omg.CORBA_2_3.portable used by org.omg.CORBA.portable
InputStream
InputStream provides for the reading of all of the mapped IDL types from the stream.

Classes in org.omg.CORBA_2_3.portable used by org.omg.stub.java.rmi
ObjectImpl
ObjectImpl class is the base class for all stubs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA_2_3.portable.Delegate

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA_2_3.portable.Delegate

No usage of org.omg.CORBA_2_3.portable.Delegate

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA_2_3.portable.InputStream

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA_2_3.portable.InputStream

Packages that use InputStream
org.omg.CORBA.portable Provides a portability layer, that is, a set of ORB APIs that makes it possible for code generated by one vendor to run on another vendor's ORB.

Uses of InputStream in org.omg.CORBA.portable

Methods in org.omg.CORBA.portable with parameters of type InputStream
 Serializable ValueFactory.read_value(InputStream is)
Is called by the ORB runtime while in the process of unmarshaling a value type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA_2_3.portable.ObjectImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA_2_3.portable.ObjectImpl

Packages that use ObjectImpl
javax.rmi.CORBA | Contains portability APIs for RMI-IIOP.
org.omg.stub.java.rmi | Contains RMI-IIOP Stubs for the Remote types that occur in the java.rmi package.

Uses of ObjectImpl in javax.rmi.CORBA

Subclasses of ObjectImpl in javax.rmi.CORBA
 class Stub
Base class from which all RMI-IIOP stubs must inherit.

Uses of ObjectImpl in org.omg.stub.java.rmi

Subclasses of ObjectImpl in org.omg.stub.java.rmi
 class _Remote_Stub
This class provides the Stub for the Remote Type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CORBA_2_3.portable.OutputStream

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CORBA_2_3.portable.OutputStream

No usage of org.omg.CORBA_2_3.portable.OutputStream

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Delegate

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA_2_3.portable
Class Delegate

java.lang.Object
    extended by  org.omg.CORBA.portable.Delegate
        extended by  org.omg.CORBA_2_3.portable.Delegate

public abstract class Delegate
extends Delegate

Delegate class provides the ORB vendor specific implementation of CORBA object. It extends org.omg.CORBA.portable.Delegate and provides new methods that were defined by CORBA 2.3.

Since:
JDK1.2
See Also:
Delegate

Constructor Summary
Delegate()
Method Summary
 String get_codebase(Object self)
Returns the codebase for object reference provided.
Methods inherited from class org.omg.CORBA.portable.Delegate
create_request, create_request, duplicate, equals, get_domain_managers, get_interface_def, get_policy, hash, hashCode, invoke, is_a, is_equivalent, is_local, non_existent, orb, release, releaseReply, request, request, servant_postinvoke, servant_preinvoke, set_policy_override, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Delegate

public Delegate()
Method Detail

get_codebase

public String get_codebase(Object self)
Returns the codebase for object reference provided.

Parameters:
self - the object reference whose codebase needs to be returned.
Returns:
the codebase as a space delimited list of url strings or null if none.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


InputStream

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA_2_3.portable
Class InputStream

java.lang.Object
    extended by  java.io.InputStream
        extended by  org.omg.CORBA.portable.InputStream
            extended by  org.omg.CORBA_2_3.portable.InputStream
All Implemented Interfaces:
Closeable
public abstract class InputStream
extends InputStream

InputStream provides for the reading of all of the mapped IDL types from the stream. It extends org.omg.CORBA.portable.InputStream. This class defines new methods that were added for CORBA 2.3.

Since:
JDK1.2
See Also:
InputStream

Constructor Summary
InputStream()
Method Summary
Object | read_abstract_interface() Unmarshal the value object or a suitable stub object.
Object | read_abstract_interface(Class clz) Unmarshal the class object or the stub class corresponding to the passed type.
Serializable | read_value() Unmarshalls a value type from the input stream.
Serializable | read_value(BoxedValueHelper factory) Unmarshalls a value type from the input stream.
Serializable | read_value(Class clz) Unmarshalls a value type from the input stream.
Serializable | read_value(Serializable value) Unmarshalls a value type from the input stream.
Serializable | read_value(String rep_id) Unmarshalls a value type from the input stream.
Methods inherited from class org.omg.CORBA.portable.InputStream
orb, read_any, read_boolean_array, read_boolean, read_char_array, read_char, read_Context, read_double_array, read_double, read_fixed, read_float_array, read_float, read_long_array, read_long, read_longlong_array, read_longlong, read_Object, read_Object, read_octet_array, read_octet, read_Principal, read_short_array, read_short, read_string, read_TypeCode, read_ulong_array, read_ulong, read_ulonglong_array, read_ulonglong, read_ushort_array, read_ushort, read_wchar_array, read_wchar, read_wstring, read
Methods inherited from class java.io.InputStream
available, close, mark, markSupported, read, read, reset, skip
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InputStream

public InputStream()
Method Detail

read_value

public Serializable read_value()
Unmarshalls a value type from the input stream.

Returns:
the value type unmarshalled from the input stream

read_value

public Serializable read_value(Class clz)
Unmarshalls a value type from the input stream.

Parameters:
clz - is the declared type of the value to be unmarshalled
Returns:
the value unmarshalled from the input stream

read_value

public Serializable read_value(BoxedValueHelper factory)
Unmarshalls a value type from the input stream.

Parameters:
factory - is the instance fo the helper to be used for unmarshalling the value type
Returns:
the value unmarshalled from the input stream

read_value

public Serializable read_value(String rep_id)
Unmarshalls a value type from the input stream.

Parameters:
rep_id - identifies the type of the value to be unmarshalled
Returns:
value type unmarshalled from the input stream

read_value

public Serializable read_value(Serializable value)
Unmarshalls a value type from the input stream.

Parameters:
value - is an uninitialized value which is added to the orb's indirection table before calling Streamable._read() or CustomMarshal.unmarshal() to unmarshal the value.
Returns:
value type unmarshalled from the input stream

read_abstract_interface

public Object read_abstract_interface()
Unmarshal the value object or a suitable stub object.

Returns:
ORB runtime returns the value object or a suitable stub object.

read_abstract_interface

public Object read_abstract_interface(Class clz)
Unmarshal the class object or the stub class corresponding to the passed type.

Parameters:
clz - is the Class object for the stub class which corresponds to the type that is statically expected.
Returns:
ORB runtime returns the value object or a suitable stub object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectImpl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA_2_3.portable
Class ObjectImpl

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.CORBA_2_3.portable.ObjectImpl
All Implemented Interfaces:
Object
Direct Known Subclasses:
Stub
public abstract class ObjectImpl
extends ObjectImpl

ObjectImpl class is the base class for all stubs. It provides the basic delegation mechanism. It extends org.omg.CORBA.portable.ObjectImpl and provides new methods defined by CORBA 2.3.

Since:
JDK1.2
See Also:
ObjectImpl

Constructor Summary
ObjectImpl()
Method Summary
 String _get_codebase()
Returns the codebase for this object reference.
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _ids, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ObjectImpl

public ObjectImpl()
Method Detail

_get_codebase

public String _get_codebase()
Returns the codebase for this object reference.

Returns:
the codebase as a space delimited list of url strings or null if none.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


OutputStream

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CORBA_2_3.portable
Class OutputStream

java.lang.Object
    extended by  java.io.OutputStream
        extended by  org.omg.CORBA.portable.OutputStream
            extended by  org.omg.CORBA_2_3.portable.OutputStream
All Implemented Interfaces:
Closeable, Flushable
public abstract class OutputStream
extends OutputStream

OutputStream provides interface for writing of all of the mapped IDL type to the stream. It extends org.omg.CORBA.portable.OutputStream, and defines new methods defined by CORBA 2.3.

Since:
JDK1.2
See Also:
OutputStream

Constructor Summary
OutputStream()
Method Summary
void | write_abstract_interface(Object obj) Marshals a value object or a stub object.
void | write_value(Serializable value) Marshals a value type to the output stream.
void | write_value(Serializable value, BoxedValueHelper factory) Marshals a value type to the output stream.
void | write_value(Serializable value, Class clz) Marshals a value type to the output stream.
void | write_value(Serializable value, String repository_id) Marshals a value type to the output stream.
Methods inherited from class org.omg.CORBA.portable.OutputStream
create_input_stream, orb, write_any, write_boolean_array, write_boolean, write_char_array, write_char, write_Context, write_double_array, write_double, write_fixed, write_float_array, write_float, write_long_array, write_long, write_longlong_array, write_longlong, write_Object, write_octet_array, write_octet, write_Principal, write_short_array, write_short, write_string, write_TypeCode, write_ulong_array, write_ulong, write_ulonglong_array, write_ulonglong, write_ushort_array, write_ushort, write_wchar_array, write_wchar, write_wstring, write
Methods inherited from class java.io.OutputStream
close, flush, write, write
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

OutputStream

public OutputStream()
Method Detail

write_value

public void write_value(Serializable value)
Marshals a value type to the output stream.

Parameters:
value - is the acutal value to write

write_value

public void write_value(Serializable value,
                        Class clz)
Marshals a value type to the output stream.

Parameters:
value - is the acutal value to write
clz - is the declared type of the value to be marshaled

write_value

public void write_value(Serializable value,
                        String repository_id)
Marshals a value type to the output stream.

Parameters:
value - is the acutal value to write
repository_id - identifies the type of the value type to be marshaled

write_value

public void write_value(Serializable value,
                        BoxedValueHelper factory)
Marshals a value type to the output stream.

Parameters:
value - is the acutal value to write
factory - is the instance of the helper to be used for marshaling the boxed value

write_abstract_interface

public void write_abstract_interface(Object obj)
Marshals a value object or a stub object.

Parameters:
obj - the actual value object to marshal or the stub to be marshalled
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


CosNaming

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.CosNaming

Provides a naming service for Java IDL.

See:
Description

Interface Summary
BindingIterator | The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
BindingIteratorOperations | The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
NamingContext | A naming context is an object that contains a set of name bindings in which each name is unique.
NamingContextExt | NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
NamingContextExtOperations | NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
NamingContextOperations | A naming context is an object that contains a set of name bindings in which each name is unique.

Class Summary
_BindingIteratorImplBase |
_BindingIteratorStub | The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
_NamingContextExtStub | NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
_NamingContextImplBase |
_NamingContextStub | A naming context is an object that contains a set of name bindings in which each name is unique.
Binding | org/omg/CosNaming/Binding.java .
BindingHelper | org/omg/CosNaming/BindingHelper.java .
BindingHolder | org/omg/CosNaming/BindingHolder.java .
BindingIteratorHelper | The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
BindingIteratorHolder | The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
BindingIteratorPOA | The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
BindingListHelper | List of Bindings.
BindingListHolder | List of Bindings.
BindingType | Specifies whether the given binding is for a object (that is not a naming context) or for a naming context.
BindingTypeHelper | Specifies whether the given binding is for a object (that is not a naming context) or for a naming context.
BindingTypeHolder | Specifies whether the given binding is for a object (that is not a naming context) or for a naming context.
IstringHelper | org/omg/CosNaming/IstringHelper.java .
NameComponent | org/omg/CosNaming/NameComponent.java .
NameComponentHelper | org/omg/CosNaming/NameComponentHelper.java .
NameComponentHolder | org/omg/CosNaming/NameComponentHolder.java .
NameHelper | A name is a sequence of name components.
NameHolder | A name is a sequence of name components.
NamingContextExtHelper | NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
NamingContextExtHolder | NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
NamingContextExtPOA | NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
NamingContextHelper | A naming context is an object that contains a set of name bindings in which each name is unique.
NamingContextHolder | A naming context is an object that contains a set of name bindings in which each name is unique.
NamingContextPOA | A naming context is an object that contains a set of name bindings in which each name is unique.

Package org.omg.CosNaming Description

Provides a naming service for Java IDL. The Object Request Broker Daemon (ORBD) also includes both a transient and persistent naming service.

The package and all its classes and interfaces were generated by running the tool idlj on the file nameservice.idl, which is a module written in OMG IDL.

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6, ORB complies, see Official Specifications for CORBA support in Java[tm] SE 6.

Interfaces

The package org.omg.CosNaming contains two public interfaces and several auxiliary classes.

The interfaces are:

  • NamingContext
  • BindingIterator

These two interfaces provide the means to bind/unbind names and object references, to retrieve bound object references, and to iterate through a list of bindings. The NamingContext interface supplies the main functionality for the naming service, and BindingIterator provides a means of iterating through a list of name/object reference bindings.

Auxiliary Classes

In order to map an OMG IDL interface to the Java programming language, the idlj compiler creates Java classes that can be thought of as auxiliary classes. Comments for the generated auxiliary classes used by the interfaces NamingContext and BindingIterator are included here.

Classes Used by NamingContext and BindingIterator

The following are classes used by the naming service. (Helper and holder classes, which are generated for each of the classes listed here, are discussed below.)
  • public final class NameComponent -- a building block for names. (Names are bound to object references in a naming context.)

    A name is an array of one or more NameComponent objects. A name with a single NameComponent is called a simple name; a name with multiple NameComponent objects is called a compound name.

    A NameComponent object consists of two fields:

    1. id -- a String used as an identifier
    2. kind -- a String that can be used for any descriptive purpose. Its importance is that it can be used to describe an object without affecting syntax. The C programming language, for example, uses the the syntactic convention of appending the extension ".c" to a file name to indicate that it is a source code file. In a NameComponent object, the kind field can be used to describe the type of object rather than a file extension or some other syntactic convention. Examples of the value of the kind field include the strings "c_source", "object_code", "executable", "postscript", and "". It is not unusual for the kind field to be the empty string.

    In a name, each NameComponent object except the last denotes a NamingContext object; the last NameComponent object denotes the bound object reference. This is similar to a path name, in which the last name is the file name, and all names before it are directory names.

  • public final class Binding -- an object that associates a name with an object reference or a naming context. A Binding object has two fields:
    1. binding_name - an array of one or more NameComponent objects that represents the bound name
    2. binding_type - a BindingType object indicating whether the binding is between a name and an object reference or between a name and a naming context

    The interface NamingContext has methods for binding/unbinding names with object references or naming contexts, for listing bindings, and for resolving bindings (given a name, the method resolve returns the object reference bound to it).

  • public final class BindingType -- an object that specifies whether the given Binding object is a binding between a name and an object reference (that is, not a naming context) or between a name and a naming context.

    The classBindingType consists of two methods and four constants. Two of these constants are BindingType objects, and two are ints.

    The BindingType objects can be passed to the constructor for the class Binding or used as parameters or return values. These BindingType objects are:

    • public static final BindingType nobject -- to indicate that the binding is with an object reference
    • public static final BindingType ncontext -- to indicate that the binding is with a naming context

    The int constants can be supplied to the method from_int to create BindingType objects, or they can be return values for the method value. These constants are:

    • public static final int _nobject
    • public static final int _ncontext
    If the method from_int is supplied with anything other than _nobject or _ncontext, it will throw the exception org.omg.CORBA.BAD_PARAM.

    Usage is as follows:

           BindingType btObject = from_int(_nobject);
       BindingType btContext = from_int(_ncontext);
    The variable btObject refers to a BindingType object initialized to represent a binding with an object reference. The variable btContext refers to a BindingType object initialized to represent a binding with a NamingContex object.

    The method value returns either _nobject or _ncontext, so in the following line of code, the variable bt will contain _nobject or _ncontext:

           int bt = BindingType.value();

Holder Classes

OMG IDL uses OUT and INOUT parameters for returning values from operations. The mapping to the Java programming language, which does not have OUT and INOUT parameters, creates a special class for each type, called a holder class. An instance of a holder class can be passed to a Java method as a parameter, and a value can be assigned to its value field. This allows it to perform the function of an OUT or INOUT parameter.

The following holder classes are generated for the package org.omg.CosNaming:

  • NamingContextHolder
  • BindingIteratorHolder
  • BindingHolder
  • BindingListHolder
  • BindingTypeHolder
  • NameComponentHolder
  • NameHolder

Note that in the org.omg.CORBA package, there is a holder class for each of the basic Java types: IntHolder, ShortHolder, StringHolder, and so on.

Note also that there is a NameHolder class even though there is no Name class; similarly, there is a BindingListHolder class even though there is no BindingList class. This is true because in the OMG IDL interface, Name and BindingList are typedefs. There is no mapping from an IDL typedef to a Java construct, but holder classes are generated if the typedef is for a sequence or an array. As mapped to the Java programming language, Name is an array of NameComponent objects, and a BindingList is an array of Binding objects. All holder classes have at least two constructors and one field:

  • value field -- an instance of the type being used as an OUT or INOUT parameter. For example, the value field of a NamingContextHolder will be a NamingContext object.
  • default constructor -- a constructor that creates a new holder object initialized with the default value for the type. For example, a new BindingHolder object created with the default constructor will have its value field set to null because that is the default value for an object. Other defaults are false for boolean, 0 for numeric and char types, and null for object references.
  • constructor from an instance -- a constructor that creates a new holder object whose value field is initialized with the instance supplied

A holder class for a user-defined type (a Java class) has three more methods, but application developers do not use them directly.

Helper Classes

Helper classes, which are generated for all user-defined types in an OMG IDL interface, supply static methods needed to manipulate those types.

There is only one method in a helper class that an application programmer uses: the method narrow. Only Java interfaces mapped from IDL interfaces will have a helper class that includes a narrow method, so in the CosNaming package, only the classes NamingContextHelper and BindingIteratorHelper have a narrow method.

  • public static NamingContext narrow(org.omg.CORBA.Object obj) -- converts the given CORBA object to a NamingContext object
  • public static BindingIterator narrow(org.omg.CORBA.Object obj) -- converts the given CORBA object to a BindingIterator object

Package org.omg.CosNaming.NamingContextPackage

This package supplies Helper and Holder classes for the exceptions used in the package org.omg.CosNaming and also for the class NotFoundReason, which supplies a reason for the exception NotFound.

There are Helper and Holder classes for the following exceptions:

  • AlreadyBound
  • CannotProceed
  • InvalidName
  • NotEmpty
  • NotFound

Naming Service Compatibility

Sun's implementation of the CosNaming package complies with the OMG COSNaming specification. In other words, the APIs in Sun's naming service are implemented according to the guidelines for a naming service provided by OMG. Therefore, if a third-party vendor has implemented a naming service that is OMG compliant, it is possible to switch between Sun's implementation of CosNaming and the third-party vendor's implementation. However, it is important to understand that there can be minor variations in the way different vendors implement the naming service, such as differences in the exception strings.

Instructions for Using a Third Party's Naming Service

Although we encourage using an ORB and ORB services that are both from one vendor, it is possible to plug in a third party's COSNaming implementation with Sun's RMI-IIOP ORB. Here are the steps to follow:
  1. Create a properties file for the Bootstrap server and give it two entries. For example, you could call this properties file /tmp/services and put the following in it: NameService, <Stringified IOR of the Root Naming Context>.

    This associates NameService with the Root Naming Context of the CosNaming implementation that you want to use.

  2. Start the standalone Bootstrap server using the following command:

      java -classpath $(CLASSPATH)
      com.sun.corba.ee.internal.CosNaming.BootstrapServer -InitialServicesFile
      "/tmp/services" [-ORBInitialPort port]

    Note that the square brackets at the end of the command indicate that specifying a port number is optional.

Now when an application calls the method org.omg.CORBA.ORB.resolve_initial_references, CORBA processes will contact the Bootstrap Server to get the Root Naming Context.

Package Specification

  • Interoperable Naming Service (ptc/00-08-07)

Related Documentation

For an overview and examples of how to use the CosNaming API, please see:
  • Naming Service

For an overview of Java IDL, please see:

  • Java IDL home page

Since:
JDK1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


_NamingContextExtStub

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class _NamingContextExtStub

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.CosNaming._NamingContextExtStub
All Implemented Interfaces:
Serializable, Object, IDLEntity, NamingContext, NamingContextExt, NamingContextExtOperations, NamingContextOperations
public class _NamingContextExtStub
extends ObjectImpl
implements NamingContextExt

NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service. Different names can be bound to an object in the same or different contexts at the same time. Using NamingContextExt, you can use URL-based names to bind and resolve.

See CORBA COS Naming Specification.

See Also:
Serialized Form

Constructor Summary
_NamingContextExtStub()
Method Summary
String[] | _ids() Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
void | bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
NamingContext | bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
void | bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | destroy() The destroy operation deletes a naming context.
void | list(int how_many, BindingListHolder bl, BindingIteratorHolder bi) The list operation allows a client to iterate through a set of bindings in a naming context.
NamingContext | new_context() This operation returns a naming context implemented by the same naming server as the context on which the operation was invoked.
void | rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
void | rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
Object | resolve_str(String sn) This operation resolves the Stringified name into the object reference.
Object | resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.
NameComponent[] | to_name(String sn) This operation converts a Stringified Name into an equivalent array of Name Components.
String | to_string(NameComponent[] n) This operation creates a stringified name from the array of Name components.
String | to_url(String addr, String sn) This operation creates a URL based "iiopname://" format name from the Stringified Name of the object.
void | unbind(NameComponent[] n) The unbind operation removes a name binding from a context.
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Constructor Detail

_NamingContextExtStub

public _NamingContextExtStub()
Method Detail

to_string

public String to_string(NameComponent[] n)
                 throws InvalidName
This operation creates a stringified name from the array of Name components.

Specified by:
to_string in interface NamingContextExtOperations
Parameters:
n - Name of the object

Throws:
org.omg.CosNaming.NamingContextExtPackage.InvalidName - Indicates the name does not identify a binding.

InvalidName

to_name

public NameComponent[] to_name(String sn)
                        throws InvalidName
This operation converts a Stringified Name into an equivalent array of Name Components.

Specified by:
to_name in interface NamingContextExtOperations
Parameters:
sn - Stringified Name of the object

Throws:
org.omg.CosNaming.NamingContextExtPackage.InvalidName - Indicates the name does not identify a binding.

InvalidName

to_url

public String to_url(String addr,
                     String sn)
              throws InvalidAddress,
                     InvalidName
This operation creates a URL based "iiopname://" format name from the Stringified Name of the object.

Specified by:
to_url in interface NamingContextExtOperations
Parameters:
addr - internet based address of the host machine where Name Service is running

sn - Stringified Name of the object

Throws:
org.omg.CosNaming.NamingContextExtPackage.InvalidName - Indicates the name does not identify a binding.

org.omg.CosNaming.NamingContextPackage.InvalidAddress - Indicates the internet based address of the host machine is incorrect

InvalidAddress
InvalidName

resolve_str

public Object resolve_str(String sn)
                   throws NotFound,
                          CannotProceed,
                          InvalidName
This operation resolves the Stringified name into the object reference.

Specified by:
resolve_str in interface NamingContextExtOperations
Parameters:
sn - Stringified Name of the object

Throws:
NotFound - Indicates there is no object reference for the given name.

CannotProceed - Indicates that the given compound name is incorrect

org.omg.CosNaming.NamingContextExtPackage.InvalidName - Indicates the name does not identify a binding.

InvalidName

bind

public void bind(NameComponent[] n,
                 Object obj)
          throws NotFound,
                 CannotProceed,
                 InvalidName,
                 AlreadyBound
Creates a binding of a name and an object in the naming context. Naming contexts that are bound using bind do not participate in name resolution when compound names are passed to be resolved.

Specified by:
bind in interface NamingContextOperations
Parameters:
n - Name of the object

obj - The Object to bind with the given name

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

AlreadyBound - Indicates an object is already bound to the specified name.

bind_context

public void bind_context(NameComponent[] n,
                         NamingContext nc)
                  throws NotFound,
                         CannotProceed,
                         InvalidName,
                         AlreadyBound
Names an object that is a naming context. Naming contexts that are bound using bind_context() participate in name resolution when compound names are passed to be resolved.

Specified by:
bind_context in interface NamingContextOperations
Parameters:
n - Name of the object

nc - NamingContect object to bind with the given name

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

AlreadyBound - Indicates an object is already bound to the specified name.

rebind

public void rebind(NameComponent[] n,
                   Object obj)
            throws NotFound,
                   CannotProceed,
                   InvalidName
Creates a binding of a name and an object in the naming context even if the name is already bound in the context. Naming contexts that are bound using rebind do not participate in name resolution when compound names are passed to be resolved.

Specified by:
rebind in interface NamingContextOperations
Parameters:
n - Name of the object

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

rebind_context

public void rebind_context(NameComponent[] n,
                           NamingContext nc)
                    throws NotFound,
                           CannotProceed,
                           InvalidName
Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context. Naming contexts that are bound using rebind_context() participate in name resolution when compound names are passed to be resolved.

Specified by:
rebind_context in interface NamingContextOperations
Parameters:
n - Name of the object

nc - NamingContect object to rebind with the given name

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

resolve

public Object resolve(NameComponent[] n)
               throws NotFound,
                      CannotProceed,
                      InvalidName
The resolve operation is the process of retrieving an object bound to a name in a given context. The given name must exactly match the bound name. The naming service does not return the type of the object. Clients are responsible for "narrowing" the object to the appropriate type. That is, clients typically cast the returned object from Object to a more specialized interface.

Specified by:
resolve in interface NamingContextOperations
Parameters:
n - Name of the object

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

unbind

public void unbind(NameComponent[] n)
            throws NotFound,
                   CannotProceed,
                   InvalidName
The unbind operation removes a name binding from a context.

Specified by:
unbind in interface NamingContextOperations
Parameters:
n - Name of the object

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

list

public void list(int how_many,
                 BindingListHolder bl,
                 BindingIteratorHolder bi)
The list operation allows a client to iterate through a set of bindings in a naming context.

The list operation returns at most the requested number of bindings in BindingList bl.

  • If the naming context contains additional bindings, the list operation returns a BindingIterator with the additional bindings.
  • If the naming context does not contain additional bindings, the binding iterator is a nil object reference.

Specified by:
list in interface NamingContextOperations
Parameters:
how_many - the maximum number of bindings to return

bl - the returned list of bindings

bi - the returned binding iterator

new_context

public NamingContext new_context()
This operation returns a naming context implemented by the same naming server as the context on which the operation was invoked. The new context is not bound to any name.

Specified by:
new_context in interface NamingContextOperations

bind_new_context

public NamingContext bind_new_context(NameComponent[] n)
                               throws NotFound,
                                      AlreadyBound,
                                      CannotProceed,
                                      InvalidName
This operation creates a new context and binds it to the name supplied as an argument. The newly-created context is implemented by the same naming server as the context in which it was bound (that is, the naming server that implements the context denoted by the name argument excluding the last component).

Specified by:
bind_new_context in interface NamingContextOperations
Parameters:
n - Name of the object

Throws:
NotFound - Indicates the name does not identify a binding.

AlreadyBound - Indicates an object is already bound to the specified name.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

destroy

public void destroy()
             throws NotEmpty
The destroy operation deletes a naming context. If the naming context contains bindings, the NotEmpty exception is raised.

Specified by:
destroy in interface NamingContextOperations
Throws:
NotEmpty - Indicates that the Naming Context contains bindings.

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Specified by:
_ids in class ObjectImpl
Returns:
the array of all repository identifiers supported by this ObjectImpl instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


_NamingContextStub

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class _NamingContextStub

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.CosNaming._NamingContextStub
All Implemented Interfaces:
Serializable, Object, IDLEntity, NamingContext, NamingContextOperations
public class _NamingContextStub
extends ObjectImpl
implements NamingContext

A naming context is an object that contains a set of name bindings in which each name is unique. Different names can be bound to an object in the same or different contexts at the same time.

See CORBA COS Naming Specification.

See Also:
Serialized Form

Constructor Summary
_NamingContextStub()
Method Summary
String[] | _ids() Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
void | bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
NamingContext | bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
void | bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | destroy() The destroy operation deletes a naming context.
void | list(int how_many, BindingListHolder bl, BindingIteratorHolder bi) The list operation allows a client to iterate through a set of bindings in a naming context.
NamingContext | new_context() This operation returns a naming context implemented by the same naming server as the context on which the operation was invoked.
void | rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
void | rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
Object | resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.
void | unbind(NameComponent[] n) The unbind operation removes a name binding from a context.
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Constructor Detail

_NamingContextStub

public _NamingContextStub()
Method Detail

bind

public void bind(NameComponent[] n,
                 Object obj)
          throws NotFound,
                 CannotProceed,
                 InvalidName,
                 AlreadyBound
Creates a binding of a name and an object in the naming context. Naming contexts that are bound using bind do not participate in name resolution when compound names are passed to be resolved.

Specified by:
bind in interface NamingContextOperations
Parameters:
n - Name of the object

obj - The Object to bind with the given name

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

AlreadyBound - Indicates an object is already bound to the specified name.

bind_context

public void bind_context(NameComponent[] n,
                         NamingContext nc)
                  throws NotFound,
                         CannotProceed,
                         InvalidName,
                         AlreadyBound
Names an object that is a naming context. Naming contexts that are bound using bind_context() participate in name resolution when compound names are passed to be resolved.

Specified by:
bind_context in interface NamingContextOperations
Parameters:
n - Name of the object

nc - NamingContect object to bind with the given name

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

AlreadyBound - Indicates an object is already bound to the specified name.

rebind

public void rebind(NameComponent[] n,
                   Object obj)
            throws NotFound,
                   CannotProceed,
                   InvalidName
Creates a binding of a name and an object in the naming context even if the name is already bound in the context. Naming contexts that are bound using rebind do not participate in name resolution when compound names are passed to be resolved.

Specified by:
rebind in interface NamingContextOperations
Parameters:
n - Name of the object

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

rebind_context

public void rebind_context(NameComponent[] n,
                           NamingContext nc)
                    throws NotFound,
                           CannotProceed,
                           InvalidName
Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context. Naming contexts that are bound using rebind_context() participate in name resolution when compound names are passed to be resolved.

Specified by:
rebind_context in interface NamingContextOperations
Parameters:
n - Name of the object

nc - NamingContect object to rebind with the given name

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

resolve

public Object resolve(NameComponent[] n)
               throws NotFound,
                      CannotProceed,
                      InvalidName
The resolve operation is the process of retrieving an object bound to a name in a given context. The given name must exactly match the bound name. The naming service does not return the type of the object. Clients are responsible for "narrowing" the object to the appropriate type. That is, clients typically cast the returned object from Object to a more specialized interface.

Specified by:
resolve in interface NamingContextOperations
Parameters:
n - Name of the object

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

unbind

public void unbind(NameComponent[] n)
            throws NotFound,
                   CannotProceed,
                   InvalidName
The unbind operation removes a name binding from a context.

Specified by:
unbind in interface NamingContextOperations
Parameters:
n - Name of the object

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

list

public void list(int how_many,
                 BindingListHolder bl,
                 BindingIteratorHolder bi)
The list operation allows a client to iterate through a set of bindings in a naming context.

The list operation returns at most the requested number of bindings in BindingList bl.

  • If the naming context contains additional bindings, the list operation returns a BindingIterator with the additional bindings.
  • If the naming context does not contain additional bindings, the binding iterator is a nil object reference.

Specified by:
list in interface NamingContextOperations
Parameters:
how_many - the maximum number of bindings to return

bl - the returned list of bindings

bi - the returned binding iterator

new_context

public NamingContext new_context()
This operation returns a naming context implemented by the same naming server as the context on which the operation was invoked. The new context is not bound to any name.

Specified by:
new_context in interface NamingContextOperations

bind_new_context

public NamingContext bind_new_context(NameComponent[] n)
                               throws NotFound,
                                      AlreadyBound,
                                      CannotProceed,
                                      InvalidName
This operation creates a new context and binds it to the name supplied as an argument. The newly-created context is implemented by the same naming server as the context in which it was bound (that is, the naming server that implements the context denoted by the name argument excluding the last component).

Specified by:
bind_new_context in interface NamingContextOperations
Parameters:
n - Name of the object

Throws:
NotFound - Indicates the name does not identify a binding.

AlreadyBound - Indicates an object is already bound to the specified name.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

destroy

public void destroy()
             throws NotEmpty
The destroy operation deletes a naming context. If the naming context contains bindings, the NotEmpty exception is raised.

Specified by:
destroy in interface NamingContextOperations
Throws:
NotEmpty - Indicates that the Naming Context contains bindings.

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Specified by:
_ids in class ObjectImpl
Returns:
the array of all repository identifiers supported by this ObjectImpl instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BindingIterator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Interface BindingIterator

All Superinterfaces:
BindingIteratorOperations, IDLEntity, Object, Serializable
All Known Implementing Classes:
_BindingIteratorImplBase, _BindingIteratorStub
public interface BindingIterator
extends BindingIteratorOperations, Object, IDLEntity

The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations. The bindings iterator is obtained by using the list method on the NamingContext.

See Also:
NamingContextOperations.list(int, org.omg.CosNaming.BindingListHolder, org.omg.CosNaming.BindingIteratorHolder)

Method Summary
Methods inherited from interface org.omg.CosNaming.BindingIteratorOperations
destroy, next_n, next_one
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


_BindingIteratorStub

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class _BindingIteratorStub

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.CosNaming._BindingIteratorStub
All Implemented Interfaces:
Serializable, Object, IDLEntity, BindingIterator, BindingIteratorOperations
public class _BindingIteratorStub
extends ObjectImpl
implements BindingIterator

The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations. The bindings iterator is obtained by using the list method on the NamingContext.

See Also:
NamingContextOperations.list(int, org.omg.CosNaming.BindingListHolder, org.omg.CosNaming.BindingIteratorHolder), Serialized Form

Constructor Summary
_BindingIteratorStub()
Method Summary
String[] | _ids() Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
void | destroy() This operation destroys the iterator.
boolean | next_n(int how_many, BindingListHolder bl) This operation returns at most the requested number of bindings.
boolean | next_one(BindingHolder b) This operation returns the next binding.
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Constructor Detail

_BindingIteratorStub

public _BindingIteratorStub()
Method Detail

next_one

public boolean next_one(BindingHolder b)
This operation returns the next binding. If there are no more bindings, false is returned.

Specified by:
next_one in interface BindingIteratorOperations
Parameters:
b - the returned binding

next_n

public boolean next_n(int how_many,
                      BindingListHolder bl)
This operation returns at most the requested number of bindings.

Specified by:
next_n in interface BindingIteratorOperations
Parameters:
how_many - the maximum number of bindings tro return

bl - the returned bindings

destroy

public void destroy()
This operation destroys the iterator.

Specified by:
destroy in interface BindingIteratorOperations

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Specified by:
_ids in class ObjectImpl
Returns:
the array of all repository identifiers supported by this ObjectImpl instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


_BindingIteratorImplBase

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class _BindingIteratorImplBase

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.CORBA.DynamicImplementation
            extended by  org.omg.CosNaming._BindingIteratorImplBase
All Implemented Interfaces:
Serializable, Object, IDLEntity, BindingIterator, BindingIteratorOperations
public abstract class _BindingIteratorImplBase
extends DynamicImplementation
implements BindingIterator

See Also:
Serialized Form

Constructor Summary
_BindingIteratorImplBase()
Method Summary
String[] | _ids() Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
void | invoke(ServerRequest r)
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CosNaming.BindingIteratorOperations
destroy, next_n, next_one
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Constructor Detail

_BindingIteratorImplBase

public _BindingIteratorImplBase()
Method Detail

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Overrides:
_ids in class DynamicImplementation
Returns:
the array of all repository identifiers supported by this ObjectImpl instance

invoke

public void invoke(ServerRequest r)
Overrides:
invoke in class DynamicImplementation
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


_NamingContextImplBase

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class _NamingContextImplBase

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.CORBA.DynamicImplementation
            extended by  org.omg.CosNaming._NamingContextImplBase
All Implemented Interfaces:
Serializable, Object, IDLEntity, NamingContext, NamingContextOperations
public abstract class _NamingContextImplBase
extends DynamicImplementation
implements NamingContext

See Also:
Serialized Form

Constructor Summary
_NamingContextImplBase()
Method Summary
String[] | _ids() Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
void | invoke(ServerRequest r)
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CosNaming.NamingContextOperations
bind_context, bind_new_context, bind, destroy, list, new_context, rebind_context, rebind, resolve, unbind
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Constructor Detail

_NamingContextImplBase

public _NamingContextImplBase()
Method Detail

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Overrides:
_ids in class DynamicImplementation
Returns:
the array of all repository identifiers supported by this ObjectImpl instance

invoke

public void invoke(ServerRequest r)
Overrides:
invoke in class DynamicImplementation
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamingContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Interface NamingContext

All Superinterfaces:
IDLEntity, NamingContextOperations, Object, Serializable
All Known Subinterfaces:
NamingContextExt
All Known Implementing Classes:
_NamingContextExtStub, _NamingContextImplBase, _NamingContextStub
public interface NamingContext
extends NamingContextOperations, Object, IDLEntity

A naming context is an object that contains a set of name bindings in which each name is unique. Different names can be bound to an object in the same or different contexts at the same time.

See CORBA COS Naming Specification.

Method Summary
Methods inherited from interface org.omg.CosNaming.NamingContextOperations
bind_context, bind_new_context, bind, destroy, list, new_context, rebind_context, rebind, resolve, unbind
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamingContextExt

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Interface NamingContextExt

All Superinterfaces:
IDLEntity, NamingContext, NamingContextExtOperations, NamingContextOperations, Object, Serializable
All Known Implementing Classes:
_NamingContextExtStub
public interface NamingContextExt
extends NamingContextExtOperations, NamingContext, IDLEntity

NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service. Different names can be bound to an object in the same or different contexts at the same time. Using NamingContextExt, you can use URL-based names to bind and resolve.

See CORBA COS Naming Specification.

Method Summary
Methods inherited from interface org.omg.CosNaming.NamingContextExtOperations
resolve_str, to_name, to_string, to_url
Methods inherited from interface org.omg.CosNaming.NamingContextOperations
bind_context, bind_new_context, bind, destroy, list, new_context, rebind_context, rebind, resolve, unbind
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


org.omg.CosNaming Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.CosNaming

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.CosNaming.Binding (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.CosNaming.BindingHelper
    • org.omg.CosNaming.BindingHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CosNaming.BindingIteratorHelper
    • org.omg.CosNaming.BindingIteratorHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CosNaming.BindingListHelper
    • org.omg.CosNaming.BindingListHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CosNaming.BindingType (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.CosNaming.BindingTypeHelper
    • org.omg.CosNaming.BindingTypeHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CosNaming.IstringHelper
    • org.omg.CosNaming.NameComponent (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.CosNaming.NameComponentHelper
    • org.omg.CosNaming.NameComponentHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CosNaming.NameHelper
    • org.omg.CosNaming.NameHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CosNaming.NamingContextExtHelper
    • org.omg.CosNaming.NamingContextExtHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CosNaming.NamingContextHelper
    • org.omg.CosNaming.NamingContextHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CORBA.portable.ObjectImpl (implements org.omg.CORBA.Object)
      • org.omg.CosNaming._BindingIteratorStub (implements org.omg.CosNaming.BindingIterator)
      • org.omg.CosNaming._NamingContextExtStub (implements org.omg.CosNaming.NamingContextExt)
      • org.omg.CosNaming._NamingContextStub (implements org.omg.CosNaming.NamingContext)
      • org.omg.CORBA.DynamicImplementation
        • org.omg.CosNaming._BindingIteratorImplBase (implements org.omg.CosNaming.BindingIterator)
        • org.omg.CosNaming._NamingContextImplBase (implements org.omg.CosNaming.NamingContext)
    • org.omg.PortableServer.Servant
      • org.omg.CosNaming.BindingIteratorPOA (implements org.omg.CosNaming.BindingIteratorOperations, org.omg.CORBA.portable.InvokeHandler)
      • org.omg.CosNaming.NamingContextExtPOA (implements org.omg.CORBA.portable.InvokeHandler, org.omg.CosNaming.NamingContextExtOperations)
      • org.omg.CosNaming.NamingContextPOA (implements org.omg.CORBA.portable.InvokeHandler, org.omg.CosNaming.NamingContextOperations)

Interface Hierarchy

  • org.omg.CosNaming.BindingIteratorOperations
    • org.omg.CosNaming.BindingIterator (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
  • org.omg.CosNaming.NamingContextOperations
    • org.omg.CosNaming.NamingContext (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
      • org.omg.CosNaming.NamingContextExt (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CosNaming.NamingContextExtOperations)
    • org.omg.CosNaming.NamingContextExtOperations
      • org.omg.CosNaming.NamingContextExt (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CosNaming.NamingContext)
  • org.omg.CORBA.Object
    • org.omg.CosNaming.BindingIterator (also extends org.omg.CosNaming.BindingIteratorOperations, org.omg.CORBA.portable.IDLEntity)
    • org.omg.CosNaming.NamingContext (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CosNaming.NamingContextOperations)
      • org.omg.CosNaming.NamingContextExt (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CosNaming.NamingContextExtOperations)
  • java.io.Serializable
    • org.omg.CORBA.portable.IDLEntity
      • org.omg.CosNaming.BindingIterator (also extends org.omg.CosNaming.BindingIteratorOperations, org.omg.CORBA.Object)
      • org.omg.CosNaming.NamingContext (also extends org.omg.CosNaming.NamingContextOperations, org.omg.CORBA.Object)
        • org.omg.CosNaming.NamingContextExt (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CosNaming.NamingContextExtOperations)
      • org.omg.CosNaming.NamingContextExt (also extends org.omg.CosNaming.NamingContext, org.omg.CosNaming.NamingContextExtOperations)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.CosNaming

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.CosNaming

Packages that use org.omg.CosNaming
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.

Classes in org.omg.CosNaming used by org.omg.CosNaming
Binding
org/omg/CosNaming/Binding.java .
BindingHolder
org/omg/CosNaming/BindingHolder.java .
BindingIterator
The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
BindingIteratorHolder
The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
BindingIteratorOperations
The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
BindingListHolder
List of Bindings.
BindingType
Specifies whether the given binding is for a object (that is not a naming context) or for a naming context.
NameComponent
org/omg/CosNaming/NameComponent.java .
NamingContext
A naming context is an object that contains a set of name bindings in which each name is unique.
NamingContextExt
NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
NamingContextExtOperations
NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
NamingContextOperations
A naming context is an object that contains a set of name bindings in which each name is unique.

Classes in org.omg.CosNaming used by org.omg.CosNaming.NamingContextPackage
NameComponent
org/omg/CosNaming/NameComponent.java .
NamingContext
A naming context is an object that contains a set of name bindings in which each name is unique.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Binding

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class Binding

java.lang.Object
    extended by  org.omg.CosNaming.Binding
All Implemented Interfaces:
Serializable, IDLEntity
public final class Binding
extends Object
implements IDLEntity

org/omg/CosNaming/Binding.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:27 AM GMT-08:00

See Also:
Serialized Form

Field Summary
NameComponent[] | binding_name
BindingType | binding_type
Constructor Summary
Binding()
Binding(NameComponent[] _binding_name, BindingType _binding_type)
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

binding_name

public NameComponent[] binding_name

binding_type

public BindingType binding_type
Constructor Detail

Binding

public Binding()

Binding

public Binding(NameComponent[] _binding_name,
               BindingType _binding_type)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BindingHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class BindingHelper

java.lang.Object
    extended by  org.omg.CosNaming.BindingHelper

public abstract class BindingHelper
extends Object

org/omg/CosNaming/BindingHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:27 AM GMT-08:00

Constructor Summary
BindingHelper()
Method Summary
static Binding | extract(Any a)
static String | id()
static void | insert(Any a, Binding that)
static Binding | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, Binding value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BindingHelper

public BindingHelper()
Method Detail

insert

public static void insert(Any a,
                          Binding that)

extract

public static Binding extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static Binding read(InputStream istream)

write

public static void write(OutputStream ostream,
                         Binding value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BindingHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class BindingHolder

java.lang.Object
    extended by  org.omg.CosNaming.BindingHolder
All Implemented Interfaces:
Streamable
public final class BindingHolder
extends Object
implements Streamable

org/omg/CosNaming/BindingHolder.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:27 AM GMT-08:00

Field Summary
 Binding value
Constructor Summary
BindingHolder()
BindingHolder(Binding initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public Binding value
Constructor Detail

BindingHolder

public BindingHolder()

BindingHolder

public BindingHolder(Binding initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BindingIteratorHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class BindingIteratorHelper

java.lang.Object
    extended by  org.omg.CosNaming.BindingIteratorHelper

public abstract class BindingIteratorHelper
extends Object

The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations. The bindings iterator is obtained by using the list method on the NamingContext.

See Also:
NamingContextOperations.list(int, org.omg.CosNaming.BindingListHolder, org.omg.CosNaming.BindingIteratorHolder)

Constructor Summary
BindingIteratorHelper()
Method Summary
static BindingIterator | extract(Any a)
static String | id()
static void | insert(Any a, BindingIterator that)
static BindingIterator | narrow(Object obj)
static BindingIterator | read(InputStream istream)
static TypeCode | type()
static BindingIterator | unchecked_narrow(Object obj)
static void | write(OutputStream ostream, BindingIterator value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BindingIteratorHelper

public BindingIteratorHelper()
Method Detail

insert

public static void insert(Any a,
                          BindingIterator that)

extract

public static BindingIterator extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static BindingIterator read(InputStream istream)

write

public static void write(OutputStream ostream,
                         BindingIterator value)

narrow

public static BindingIterator narrow(Object obj)

unchecked_narrow

public static BindingIterator unchecked_narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BindingIteratorHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class BindingIteratorHolder

java.lang.Object
    extended by  org.omg.CosNaming.BindingIteratorHolder
All Implemented Interfaces:
Streamable
public final class BindingIteratorHolder
extends Object
implements Streamable

The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations. The bindings iterator is obtained by using the list method on the NamingContext.

See Also:
NamingContextOperations.list(int, org.omg.CosNaming.BindingListHolder, org.omg.CosNaming.BindingIteratorHolder)

Field Summary
 BindingIterator value
Constructor Summary
BindingIteratorHolder()
BindingIteratorHolder(BindingIterator initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public BindingIterator value
Constructor Detail

BindingIteratorHolder

public BindingIteratorHolder()

BindingIteratorHolder

public BindingIteratorHolder(BindingIterator initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BindingIteratorOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Interface BindingIteratorOperations

All Known Subinterfaces:
BindingIterator
All Known Implementing Classes:
_BindingIteratorImplBase, _BindingIteratorStub, BindingIteratorPOA
public interface BindingIteratorOperations

The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations. The bindings iterator is obtained by using the list method on the NamingContext.

See Also:
NamingContextOperations.list(int, org.omg.CosNaming.BindingListHolder, org.omg.CosNaming.BindingIteratorHolder)

Method Summary
void | destroy() This operation destroys the iterator.
boolean | next_n(int how_many, BindingListHolder bl) This operation returns at most the requested number of bindings.
boolean | next_one(BindingHolder b) This operation returns the next binding.

Method Detail

next_one

boolean next_one(BindingHolder b)
This operation returns the next binding. If there are no more bindings, false is returned.

Parameters:
b - the returned binding

next_n

boolean next_n(int how_many,
               BindingListHolder bl)
This operation returns at most the requested number of bindings.

Parameters:
how_many - the maximum number of bindings tro return

bl - the returned bindings

destroy

void destroy()
This operation destroys the iterator.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BindingIteratorPOA

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class BindingIteratorPOA

java.lang.Object
    extended by  org.omg.PortableServer.Servant
        extended by  org.omg.CosNaming.BindingIteratorPOA
All Implemented Interfaces:
InvokeHandler, BindingIteratorOperations
public abstract class BindingIteratorPOA
extends Servant
implements BindingIteratorOperations, InvokeHandler

The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations. The bindings iterator is obtained by using the list method on the NamingContext.

See Also:
NamingContextOperations.list(int, org.omg.CosNaming.BindingListHolder, org.omg.CosNaming.BindingIteratorHolder)

Constructor Summary
BindingIteratorPOA()
Method Summary
String[] | _all_interfaces(POA poa, byte[] objectId) Used by the ORB to obtain complete type information from the servant.
OutputStream | _invoke(String $method, InputStream in, ResponseHandler $rh) Invoked by the ORB to dispatch a request to the servant.
BindingIterator | _this()
BindingIterator | _this(ORB orb)
Methods inherited from class org.omg.PortableServer.Servant
_default_POA, _get_delegate, _get_interface_def, _is_a, _non_existent, _object_id, _orb, _poa, _set_delegate, _this_object, _this_object
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.omg.CosNaming.BindingIteratorOperations
destroy, next_n, next_one

Constructor Detail

BindingIteratorPOA

public BindingIteratorPOA()
Method Detail

_invoke

public OutputStream _invoke(String $method,
                            InputStream in,
                            ResponseHandler $rh)
Description copied from interface: InvokeHandler
Invoked by the ORB to dispatch a request to the servant. ORB passes the method name, an InputStream containing the marshalled arguments, and a ResponseHandler which the servant uses to construct a proper reply. Only CORBA SystemException may be thrown by this method. The method must return an OutputStream created by the ResponseHandler which contains the marshalled reply. A servant must not retain a reference to the ResponseHandler beyond the lifetime of a method invocation. Servant behaviour is defined as follows:

1. Determine correct method, and unmarshal parameters from InputStream.

2. Invoke method implementation.

3. If no user exception, create a normal reply using ResponseHandler.

4. If user exception occurred, create exception reply using ResponseHandler.

5. Marshal reply into OutputStream returned by ResponseHandler.

6. Return OutputStream to ORB.

Specified by:
_invoke in interface InvokeHandler
Parameters:
$method - The method name.
in - The InputStream containing the marshalled arguments.
$rh - The ResponseHandler which the servant uses to construct a proper reply
Returns:
The OutputStream created by the ResponseHandler which contains the marshalled reply

_all_interfaces

public String[] _all_interfaces(POA poa,
                                byte[] objectId)
Description copied from class: Servant
Used by the ORB to obtain complete type information from the servant.

Specified by:
_all_interfaces in class Servant
Parameters:
poa - POA with which the servant is associated.
objectId - is the id corresponding to the object associated with this servant.
Returns:
list of type information for the object.

_this

public BindingIterator _this()

_this

public BindingIterator _this(ORB orb)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BindingListHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class BindingListHelper

java.lang.Object
    extended by  org.omg.CosNaming.BindingListHelper

public abstract class BindingListHelper
extends Object

List of Bindings.

Constructor Summary
BindingListHelper()
Method Summary
static Binding[] | extract(Any a)
static String | id()
static void | insert(Any a, Binding[] that)
static Binding[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, Binding[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BindingListHelper

public BindingListHelper()
Method Detail

insert

public static void insert(Any a,
                          Binding[] that)

extract

public static Binding[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static Binding[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         Binding[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BindingListHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class BindingListHolder

java.lang.Object
    extended by  org.omg.CosNaming.BindingListHolder
All Implemented Interfaces:
Streamable
public final class BindingListHolder
extends Object
implements Streamable

List of Bindings.

Field Summary
 Binding[] value
Constructor Summary
BindingListHolder()
BindingListHolder(Binding[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public Binding[] value
Constructor Detail

BindingListHolder

public BindingListHolder()

BindingListHolder

public BindingListHolder(Binding[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BindingType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class BindingType

java.lang.Object
    extended by  org.omg.CosNaming.BindingType
All Implemented Interfaces:
Serializable, IDLEntity
public class BindingType
extends Object
implements IDLEntity

Specifies whether the given binding is for a object (that is not a naming context) or for a naming context.

See Also:
Serialized Form

Field Summary
static int | _ncontext
static int | _nobject
static BindingType | ncontext
static BindingType | nobject
Constructor Summary
protected BindingType(int value)
Method Summary
static BindingType | from_int(int value)
int | value()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_nobject

public static final int _nobject
See Also:
Constant Field Values

nobject

public static final BindingType nobject

_ncontext

public static final int _ncontext
See Also:
Constant Field Values

ncontext

public static final BindingType ncontext
Constructor Detail

BindingType

protected BindingType(int value)
Method Detail

value

public int value()

from_int

public static BindingType from_int(int value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BindingTypeHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class BindingTypeHelper

java.lang.Object
    extended by  org.omg.CosNaming.BindingTypeHelper

public abstract class BindingTypeHelper
extends Object

Specifies whether the given binding is for a object (that is not a naming context) or for a naming context.

Constructor Summary
BindingTypeHelper()
Method Summary
static BindingType | extract(Any a)
static String | id()
static void | insert(Any a, BindingType that)
static BindingType | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, BindingType value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BindingTypeHelper

public BindingTypeHelper()
Method Detail

insert

public static void insert(Any a,
                          BindingType that)

extract

public static BindingType extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static BindingType read(InputStream istream)

write

public static void write(OutputStream ostream,
                         BindingType value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BindingTypeHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class BindingTypeHolder

java.lang.Object
    extended by  org.omg.CosNaming.BindingTypeHolder
All Implemented Interfaces:
Streamable
public final class BindingTypeHolder
extends Object
implements Streamable

Specifies whether the given binding is for a object (that is not a naming context) or for a naming context.

Field Summary
 BindingType value
Constructor Summary
BindingTypeHolder()
BindingTypeHolder(BindingType initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public BindingType value
Constructor Detail

BindingTypeHolder

public BindingTypeHolder()

BindingTypeHolder

public BindingTypeHolder(BindingType initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class org.omg.CosNaming.Binding

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.Binding

Packages that use Binding
org.omg.CosNaming Provides a naming service for Java IDL.

Uses of Binding in org.omg.CosNaming

Fields in org.omg.CosNaming declared as Binding
Binding[] | BindingListHolder.value
Binding | BindingHolder.value

Methods in org.omg.CosNaming that return Binding
static Binding[] | BindingListHelper.extract(Any a)
static Binding | BindingHelper.extract(Any a)
static Binding[] | BindingListHelper.read(InputStream istream)
static Binding | BindingHelper.read(InputStream istream)

Methods in org.omg.CosNaming with parameters of type Binding
static void | BindingHelper.insert(Any a, Binding that)
static void | BindingListHelper.insert(Any a, Binding[] that)
static void | BindingHelper.write(OutputStream ostream, Binding value)
static void | BindingListHelper.write(OutputStream ostream, Binding[] value)

Constructors in org.omg.CosNaming with parameters of type Binding
BindingHolder(Binding initialValue)
BindingListHolder(Binding[] initialValue)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.BindingHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.BindingHelper

No usage of org.omg.CosNaming.BindingHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.BindingHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.BindingHolder

Packages that use BindingHolder
org.omg.CosNaming Provides a naming service for Java IDL.

Uses of BindingHolder in org.omg.CosNaming

Methods in org.omg.CosNaming with parameters of type BindingHolder
boolean | _BindingIteratorStub.next_one(BindingHolder b) This operation returns the next binding.
boolean | BindingIteratorOperations.next_one(BindingHolder b) This operation returns the next binding.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.BindingIteratorHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.BindingIteratorHelper

No usage of org.omg.CosNaming.BindingIteratorHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.BindingIteratorHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.BindingIteratorHolder

Packages that use BindingIteratorHolder
org.omg.CosNaming Provides a naming service for Java IDL.

Uses of BindingIteratorHolder in org.omg.CosNaming

Methods in org.omg.CosNaming with parameters of type BindingIteratorHolder
void | _NamingContextExtStub.list(int how_many, BindingListHolder bl, BindingIteratorHolder bi) The list operation allows a client to iterate through a set of bindings in a naming context.
void | _NamingContextStub.list(int how_many, BindingListHolder bl, BindingIteratorHolder bi) The list operation allows a client to iterate through a set of bindings in a naming context.
void | NamingContextOperations.list(int how_many, BindingListHolder bl, BindingIteratorHolder bi) The list operation allows a client to iterate through a set of bindings in a naming context.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.BindingIteratorPOA

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.BindingIteratorPOA

No usage of org.omg.CosNaming.BindingIteratorPOA

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.BindingListHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.BindingListHelper

No usage of org.omg.CosNaming.BindingListHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.BindingListHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.BindingListHolder

Packages that use BindingListHolder
org.omg.CosNaming Provides a naming service for Java IDL.

Uses of BindingListHolder in org.omg.CosNaming

Methods in org.omg.CosNaming with parameters of type BindingListHolder
void | _NamingContextExtStub.list(int how_many, BindingListHolder bl, BindingIteratorHolder bi) The list operation allows a client to iterate through a set of bindings in a naming context.
void | _NamingContextStub.list(int how_many, BindingListHolder bl, BindingIteratorHolder bi) The list operation allows a client to iterate through a set of bindings in a naming context.
void | NamingContextOperations.list(int how_many, BindingListHolder bl, BindingIteratorHolder bi) The list operation allows a client to iterate through a set of bindings in a naming context.
boolean | _BindingIteratorStub.next_n(int how_many, BindingListHolder bl) This operation returns at most the requested number of bindings.
boolean | BindingIteratorOperations.next_n(int how_many, BindingListHolder bl) This operation returns at most the requested number of bindings.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.BindingType

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.BindingType

Packages that use BindingType
org.omg.CosNaming Provides a naming service for Java IDL.

Uses of BindingType in org.omg.CosNaming

Fields in org.omg.CosNaming declared as BindingType
BindingType | Binding.binding_type
static BindingType | BindingType.ncontext
static BindingType | BindingType.nobject
BindingType | BindingTypeHolder.value

Methods in org.omg.CosNaming that return BindingType
static BindingType | BindingTypeHelper.extract(Any a)
static BindingType | BindingType.from_int(int value)
static BindingType | BindingTypeHelper.read(InputStream istream)

Methods in org.omg.CosNaming with parameters of type BindingType
static void | BindingTypeHelper.insert(Any a, BindingType that)
static void | BindingTypeHelper.write(OutputStream ostream, BindingType value)

Constructors in org.omg.CosNaming with parameters of type BindingType
Binding(NameComponent[] _binding_name, BindingType _binding_type)
BindingTypeHolder(BindingType initialValue)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.BindingTypeHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.BindingTypeHelper

No usage of org.omg.CosNaming.BindingTypeHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.BindingTypeHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.BindingTypeHolder

No usage of org.omg.CosNaming.BindingTypeHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.IstringHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.IstringHelper

No usage of org.omg.CosNaming.IstringHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NameComponent

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NameComponent

Packages that use NameComponent
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.

Uses of NameComponent in org.omg.CosNaming

Fields in org.omg.CosNaming declared as NameComponent
NameComponent[] | Binding.binding_name
NameComponent[] | NameHolder.value
NameComponent | NameComponentHolder.value

Methods in org.omg.CosNaming that return NameComponent
static NameComponent[] | NameHelper.extract(Any a)
static NameComponent | NameComponentHelper.extract(Any a)
static NameComponent[] | NameHelper.read(InputStream istream)
static NameComponent | NameComponentHelper.read(InputStream istream)
NameComponent[] | _NamingContextExtStub.to_name(String sn) This operation converts a Stringified Name into an equivalent array of Name Components.
NameComponent[] | NamingContextExtOperations.to_name(String sn) This operation converts a Stringified Name into an equivalent array of Name Components.

Methods in org.omg.CosNaming with parameters of type NameComponent
void | _NamingContextExtStub.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
void | _NamingContextStub.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
void | NamingContextOperations.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
NamingContext | _NamingContextExtStub.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
NamingContext | _NamingContextStub.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
NamingContext | NamingContextOperations.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
void | _NamingContextExtStub.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | _NamingContextStub.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | NamingContextOperations.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
static void | NameComponentHelper.insert(Any a, NameComponent that)
static void | NameHelper.insert(Any a, NameComponent[] that)
void | _NamingContextExtStub.rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
void | _NamingContextStub.rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
void | NamingContextOperations.rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
void | _NamingContextExtStub.rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
void | _NamingContextStub.rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
void | NamingContextOperations.rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
Object | _NamingContextExtStub.resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.
Object | _NamingContextStub.resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.
Object | NamingContextOperations.resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.
String | _NamingContextExtStub.to_string(NameComponent[] n) This operation creates a stringified name from the array of Name components.
String | NamingContextExtOperations.to_string(NameComponent[] n) This operation creates a stringified name from the array of Name components.
void | _NamingContextExtStub.unbind(NameComponent[] n) The unbind operation removes a name binding from a context.
void | _NamingContextStub.unbind(NameComponent[] n) The unbind operation removes a name binding from a context.
void | NamingContextOperations.unbind(NameComponent[] n) The unbind operation removes a name binding from a context.
static void | NameComponentHelper.write(OutputStream ostream, NameComponent value)
static void | NameHelper.write(OutputStream ostream, NameComponent[] value)

Constructors in org.omg.CosNaming with parameters of type NameComponent
Binding(NameComponent[] _binding_name, BindingType _binding_type)
NameComponentHolder(NameComponent initialValue)
NameHolder(NameComponent[] initialValue)

Uses of NameComponent in org.omg.CosNaming.NamingContextPackage

Fields in org.omg.CosNaming.NamingContextPackage declared as NameComponent
NameComponent[] | CannotProceed.rest_of_name
NameComponent[] | NotFound.rest_of_name

Constructors in org.omg.CosNaming.NamingContextPackage with parameters of type NameComponent
CannotProceed(NamingContext _cxt, NameComponent[] _rest_of_name)
CannotProceed(String $reason, NamingContext _cxt, NameComponent[] _rest_of_name)
NotFound(NotFoundReason _why, NameComponent[] _rest_of_name)
NotFound(String $reason, NotFoundReason _why, NameComponent[] _rest_of_name)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NameComponentHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NameComponentHelper

No usage of org.omg.CosNaming.NameComponentHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NameComponentHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NameComponentHolder

No usage of org.omg.CosNaming.NameComponentHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NameHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NameHelper

No usage of org.omg.CosNaming.NameHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NameHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NameHolder

No usage of org.omg.CosNaming.NameHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextExtHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextExtHelper

No usage of org.omg.CosNaming.NamingContextExtHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextExtHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextExtHolder

No usage of org.omg.CosNaming.NamingContextExtHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextExtPOA

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextExtPOA

No usage of org.omg.CosNaming.NamingContextExtPOA

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextHelper

No usage of org.omg.CosNaming.NamingContextHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextHolder

No usage of org.omg.CosNaming.NamingContextHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPOA

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPOA

No usage of org.omg.CosNaming.NamingContextPOA

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming._BindingIteratorImplBase

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming._BindingIteratorImplBase

No usage of org.omg.CosNaming._BindingIteratorImplBase

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming._BindingIteratorStub

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming._BindingIteratorStub

No usage of org.omg.CosNaming._BindingIteratorStub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming._NamingContextExtStub

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming._NamingContextExtStub

No usage of org.omg.CosNaming._NamingContextExtStub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming._NamingContextImplBase

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming._NamingContextImplBase

No usage of org.omg.CosNaming._NamingContextImplBase

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming._NamingContextStub

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming._NamingContextStub

No usage of org.omg.CosNaming._NamingContextStub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CosNaming.BindingIterator

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CosNaming.BindingIterator

Packages that use BindingIterator
org.omg.CosNaming Provides a naming service for Java IDL.

Uses of BindingIterator in org.omg.CosNaming

Classes in org.omg.CosNaming that implement BindingIterator
class | _BindingIteratorImplBase
class | _BindingIteratorStub The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.

Fields in org.omg.CosNaming declared as BindingIterator
 BindingIterator BindingIteratorHolder.value

Methods in org.omg.CosNaming that return BindingIterator
BindingIterator | BindingIteratorPOA._this()
BindingIterator | BindingIteratorPOA._this(ORB orb)
static BindingIterator | BindingIteratorHelper.extract(Any a)
static BindingIterator | BindingIteratorHelper.narrow(Object obj)
static BindingIterator | BindingIteratorHelper.read(InputStream istream)
static BindingIterator | BindingIteratorHelper.unchecked_narrow(Object obj)

Methods in org.omg.CosNaming with parameters of type BindingIterator
static void | BindingIteratorHelper.insert(Any a, BindingIterator that)
static void | BindingIteratorHelper.write(OutputStream ostream, BindingIterator value)

Constructors in org.omg.CosNaming with parameters of type BindingIterator
BindingIteratorHolder(BindingIterator initialValue)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CosNaming.BindingIteratorOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CosNaming.BindingIteratorOperations

Packages that use BindingIteratorOperations
org.omg.CosNaming Provides a naming service for Java IDL.

Uses of BindingIteratorOperations in org.omg.CosNaming

Subinterfaces of BindingIteratorOperations in org.omg.CosNaming
 interface BindingIterator
The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.

Classes in org.omg.CosNaming that implement BindingIteratorOperations
class | _BindingIteratorImplBase
class | _BindingIteratorStub The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
class | BindingIteratorPOA The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CosNaming.NamingContext

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CosNaming.NamingContext

Packages that use NamingContext
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.

Uses of NamingContext in org.omg.CosNaming

Subinterfaces of NamingContext in org.omg.CosNaming
 interface NamingContextExt
NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.

Classes in org.omg.CosNaming that implement NamingContext
class | _NamingContextExtStub NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
class | _NamingContextImplBase
class | _NamingContextStub A naming context is an object that contains a set of name bindings in which each name is unique.

Fields in org.omg.CosNaming declared as NamingContext
 NamingContext NamingContextHolder.value

Methods in org.omg.CosNaming that return NamingContext
NamingContext | NamingContextPOA._this()
NamingContext | NamingContextPOA._this(ORB orb)
NamingContext | _NamingContextExtStub.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
NamingContext | _NamingContextStub.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
NamingContext | NamingContextOperations.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
static NamingContext | NamingContextHelper.extract(Any a)
static NamingContext | NamingContextHelper.narrow(Object obj)
NamingContext | _NamingContextExtStub.new_context() This operation returns a naming context implemented by the same naming server as the context on which the operation was invoked.
NamingContext | _NamingContextStub.new_context() This operation returns a naming context implemented by the same naming server as the context on which the operation was invoked.
NamingContext | NamingContextOperations.new_context() This operation returns a naming context implemented by the same naming server as the context on which the operation was invoked.
static NamingContext | NamingContextHelper.read(InputStream istream)
static NamingContext | NamingContextHelper.unchecked_narrow(Object obj)

Methods in org.omg.CosNaming with parameters of type NamingContext
void | _NamingContextExtStub.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
void | _NamingContextStub.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
void | NamingContextOperations.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
static void | NamingContextHelper.insert(Any a, NamingContext that)
void | _NamingContextExtStub.rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
void | _NamingContextStub.rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
void | NamingContextOperations.rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
static void | NamingContextHelper.write(OutputStream ostream, NamingContext value)

Constructors in org.omg.CosNaming with parameters of type NamingContext
NamingContextHolder(NamingContext initialValue)

Uses of NamingContext in org.omg.CosNaming.NamingContextPackage

Fields in org.omg.CosNaming.NamingContextPackage declared as NamingContext
 NamingContext CannotProceed.cxt

Constructors in org.omg.CosNaming.NamingContextPackage with parameters of type NamingContext
CannotProceed(NamingContext _cxt, NameComponent[] _rest_of_name)
CannotProceed(String $reason, NamingContext _cxt, NameComponent[] _rest_of_name)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CosNaming.NamingContextExt

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CosNaming.NamingContextExt

Packages that use NamingContextExt
org.omg.CosNaming Provides a naming service for Java IDL.

Uses of NamingContextExt in org.omg.CosNaming

Classes in org.omg.CosNaming that implement NamingContextExt
 class _NamingContextExtStub
NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.

Fields in org.omg.CosNaming declared as NamingContextExt
 NamingContextExt NamingContextExtHolder.value

Methods in org.omg.CosNaming that return NamingContextExt
NamingContextExt | NamingContextExtPOA._this()
NamingContextExt | NamingContextExtPOA._this(ORB orb)
static NamingContextExt | NamingContextExtHelper.extract(Any a)
static NamingContextExt | NamingContextExtHelper.narrow(Object obj)
static NamingContextExt | NamingContextExtHelper.read(InputStream istream)
static NamingContextExt | NamingContextExtHelper.unchecked_narrow(Object obj)

Methods in org.omg.CosNaming with parameters of type NamingContextExt
static void | NamingContextExtHelper.insert(Any a, NamingContextExt that)
static void | NamingContextExtHelper.write(OutputStream ostream, NamingContextExt value)

Constructors in org.omg.CosNaming with parameters of type NamingContextExt
NamingContextExtHolder(NamingContextExt initialValue)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CosNaming.NamingContextExtOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CosNaming.NamingContextExtOperations

Packages that use NamingContextExtOperations
org.omg.CosNaming Provides a naming service for Java IDL.

Uses of NamingContextExtOperations in org.omg.CosNaming

Subinterfaces of NamingContextExtOperations in org.omg.CosNaming
 interface NamingContextExt
NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.

Classes in org.omg.CosNaming that implement NamingContextExtOperations
class | _NamingContextExtStub NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
class | NamingContextExtPOA NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.CosNaming.NamingContextOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.CosNaming.NamingContextOperations

Packages that use NamingContextOperations
org.omg.CosNaming Provides a naming service for Java IDL.

Uses of NamingContextOperations in org.omg.CosNaming

Subinterfaces of NamingContextOperations in org.omg.CosNaming
interface | NamingContext A naming context is an object that contains a set of name bindings in which each name is unique.
interface | NamingContextExt NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
interface | NamingContextExtOperations NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.

Classes in org.omg.CosNaming that implement NamingContextOperations
class | _NamingContextExtStub NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
class | _NamingContextImplBase
class | _NamingContextStub A naming context is an object that contains a set of name bindings in which each name is unique.
class | NamingContextExtPOA NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
class | NamingContextPOA A naming context is an object that contains a set of name bindings in which each name is unique.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


IstringHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class IstringHelper

java.lang.Object
    extended by  org.omg.CosNaming.IstringHelper

public abstract class IstringHelper
extends Object

org/omg/CosNaming/IstringHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:27 AM GMT-08:00

Constructor Summary
IstringHelper()
Method Summary
static String | extract(Any a)
static String | id()
static void | insert(Any a, String that)
static String | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, String value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IstringHelper

public IstringHelper()
Method Detail

insert

public static void insert(Any a,
                          String that)

extract

public static String extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static String read(InputStream istream)

write

public static void write(OutputStream ostream,
                         String value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameComponent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class NameComponent

java.lang.Object
    extended by  org.omg.CosNaming.NameComponent
All Implemented Interfaces:
Serializable, IDLEntity
public final class NameComponent
extends Object
implements IDLEntity

org/omg/CosNaming/NameComponent.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:27 AM GMT-08:00

See Also:
Serialized Form

Field Summary
String | id
String | kind
Constructor Summary
NameComponent()
NameComponent(String _id, String _kind)
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

id

public String id

kind

public String kind
Constructor Detail

NameComponent

public NameComponent()

NameComponent

public NameComponent(String _id,
                     String _kind)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameComponentHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class NameComponentHelper

java.lang.Object
    extended by  org.omg.CosNaming.NameComponentHelper

public abstract class NameComponentHelper
extends Object

org/omg/CosNaming/NameComponentHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:27 AM GMT-08:00

Constructor Summary
NameComponentHelper()
Method Summary
static NameComponent | extract(Any a)
static String | id()
static void | insert(Any a, NameComponent that)
static NameComponent | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, NameComponent value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NameComponentHelper

public NameComponentHelper()
Method Detail

insert

public static void insert(Any a,
                          NameComponent that)

extract

public static NameComponent extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static NameComponent read(InputStream istream)

write

public static void write(OutputStream ostream,
                         NameComponent value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameComponentHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class NameComponentHolder

java.lang.Object
    extended by  org.omg.CosNaming.NameComponentHolder
All Implemented Interfaces:
Streamable
public final class NameComponentHolder
extends Object
implements Streamable

org/omg/CosNaming/NameComponentHolder.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:27 AM GMT-08:00

Field Summary
 NameComponent value
Constructor Summary
NameComponentHolder()
NameComponentHolder(NameComponent initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public NameComponent value
Constructor Detail

NameComponentHolder

public NameComponentHolder()

NameComponentHolder

public NameComponentHolder(NameComponent initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class NameHelper

java.lang.Object
    extended by  org.omg.CosNaming.NameHelper

public abstract class NameHelper
extends Object

A name is a sequence of name components.

Constructor Summary
NameHelper()
Method Summary
static NameComponent[] | extract(Any a)
static String | id()
static void | insert(Any a, NameComponent[] that)
static NameComponent[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, NameComponent[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NameHelper

public NameHelper()
Method Detail

insert

public static void insert(Any a,
                          NameComponent[] that)

extract

public static NameComponent[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static NameComponent[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         NameComponent[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class NameHolder

java.lang.Object
    extended by  org.omg.CosNaming.NameHolder
All Implemented Interfaces:
Streamable
public final class NameHolder
extends Object
implements Streamable

A name is a sequence of name components.

Field Summary
 NameComponent[] value
Constructor Summary
NameHolder()
NameHolder(NameComponent[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public NameComponent[] value
Constructor Detail

NameHolder

public NameHolder()

NameHolder

public NameHolder(NameComponent[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamingContextExtHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class NamingContextExtHelper

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextExtHelper

public abstract class NamingContextExtHelper
extends Object

NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service. Different names can be bound to an object in the same or different contexts at the same time. Using NamingContextExt, you can use URL-based names to bind and resolve.

See CORBA COS Naming Specification.

Constructor Summary
NamingContextExtHelper()
Method Summary
static NamingContextExt | extract(Any a)
static String | id()
static void | insert(Any a, NamingContextExt that)
static NamingContextExt | narrow(Object obj)
static NamingContextExt | read(InputStream istream)
static TypeCode | type()
static NamingContextExt | unchecked_narrow(Object obj)
static void | write(OutputStream ostream, NamingContextExt value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NamingContextExtHelper

public NamingContextExtHelper()
Method Detail

insert

public static void insert(Any a,
                          NamingContextExt that)

extract

public static NamingContextExt extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static NamingContextExt read(InputStream istream)

write

public static void write(OutputStream ostream,
                         NamingContextExt value)

narrow

public static NamingContextExt narrow(Object obj)

unchecked_narrow

public static NamingContextExt unchecked_narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamingContextExtHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class NamingContextExtHolder

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextExtHolder
All Implemented Interfaces:
Streamable
public final class NamingContextExtHolder
extends Object
implements Streamable

NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service. Different names can be bound to an object in the same or different contexts at the same time. Using NamingContextExt, you can use URL-based names to bind and resolve.

See CORBA COS Naming Specification.

Field Summary
 NamingContextExt value
Constructor Summary
NamingContextExtHolder()
NamingContextExtHolder(NamingContextExt initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public NamingContextExt value
Constructor Detail

NamingContextExtHolder

public NamingContextExtHolder()

NamingContextExtHolder

public NamingContextExtHolder(NamingContextExt initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamingContextExtOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Interface NamingContextExtOperations

All Superinterfaces:
NamingContextOperations
All Known Subinterfaces:
NamingContextExt
All Known Implementing Classes:
_NamingContextExtStub, NamingContextExtPOA
public interface NamingContextExtOperations
extends NamingContextOperations

NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service. Different names can be bound to an object in the same or different contexts at the same time. Using NamingContextExt, you can use URL-based names to bind and resolve.

See CORBA COS Naming Specification.

Method Summary
Object | resolve_str(String sn) This operation resolves the Stringified name into the object reference.
NameComponent[] | to_name(String sn) This operation converts a Stringified Name into an equivalent array of Name Components.
String | to_string(NameComponent[] n) This operation creates a stringified name from the array of Name components.
String | to_url(String addr, String sn) This operation creates a URL based "iiopname://" format name from the Stringified Name of the object.
Methods inherited from interface org.omg.CosNaming.NamingContextOperations
bind_context, bind_new_context, bind, destroy, list, new_context, rebind_context, rebind, resolve, unbind

Method Detail

to_string

String to_string(NameComponent[] n)
                 throws InvalidName
This operation creates a stringified name from the array of Name components.

Parameters:
n - Name of the object

Throws:
org.omg.CosNaming.NamingContextExtPackage.InvalidName - Indicates the name does not identify a binding.

InvalidName

to_name

NameComponent[] to_name(String sn)
                        throws InvalidName
This operation converts a Stringified Name into an equivalent array of Name Components.

Parameters:
sn - Stringified Name of the object

Throws:
org.omg.CosNaming.NamingContextExtPackage.InvalidName - Indicates the name does not identify a binding.

InvalidName

to_url

String to_url(String addr,
              String sn)
              throws InvalidAddress,
                     InvalidName
This operation creates a URL based "iiopname://" format name from the Stringified Name of the object.

Parameters:
addr - internet based address of the host machine where Name Service is running

sn - Stringified Name of the object

Throws:
org.omg.CosNaming.NamingContextExtPackage.InvalidName - Indicates the name does not identify a binding.

org.omg.CosNaming.NamingContextPackage.InvalidAddress - Indicates the internet based address of the host machine is incorrect

InvalidAddress
InvalidName

resolve_str

Object resolve_str(String sn)
                   throws NotFound,
                          CannotProceed,
                          InvalidName
This operation resolves the Stringified name into the object reference.

Parameters:
sn - Stringified Name of the object

Throws:
NotFound - Indicates there is no object reference for the given name.

CannotProceed - Indicates that the given compound name is incorrect

org.omg.CosNaming.NamingContextExtPackage.InvalidName - Indicates the name does not identify a binding.

InvalidName
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamingContextExtPackage

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.CosNaming.NamingContextExtPackage

This package contains the following classes, which are used in org.omg.CosNaming.NamingContextExt:

See:
Description

Class Summary
AddressHelper | Address is the Host and Port information represented as a String.
InvalidAddressHelper | org/omg/CosNaming/NamingContextExtPackage/InvalidAddressHelper.java .
InvalidAddressHolder | org/omg/CosNaming/NamingContextExtPackage/InvalidAddressHolder.java .
StringNameHelper | StringName is the Stringified Name, Array of Name Components represented as a String.
URLStringHelper | URLString is the URL address (corbaloc: or corbaname:) represented as a String.

Exception Summary
InvalidAddress org/omg/CosNaming/NamingContextExtPackage/InvalidAddress.java .

Package org.omg.CosNaming.NamingContextExtPackage Description

This package contains the following classes, which are used in org.omg.CosNaming.NamingContextExt:

  • AddressHelper
  • StringNameHelper
  • URLStringHelper
  • InvalidAddress

    Package Specification

    For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6 ORB complies, see Official Specifications for CORBA support in Java[tm] SE 6.

    Since:
    1.4
    Overview Package Class Use Tree Deprecated Index Help
            Java™ Platform
    Standard Ed. 6
    PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.CosNaming.NamingContextExtPackage Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.CosNaming.NamingContextExtPackage

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.CosNaming.NamingContextExtPackage.AddressHelper
    • org.omg.CosNaming.NamingContextExtPackage.InvalidAddressHelper
    • org.omg.CosNaming.NamingContextExtPackage.InvalidAddressHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CosNaming.NamingContextExtPackage.StringNameHelper
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.omg.CORBA.UserException (implements org.omg.CORBA.portable.IDLEntity)
          • org.omg.CosNaming.NamingContextExtPackage.InvalidAddress
    • org.omg.CosNaming.NamingContextExtPackage.URLStringHelper
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.CosNaming.NamingContextExtPackage

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.CosNaming.NamingContextExtPackage

Packages that use org.omg.CosNaming.NamingContextExtPackage
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextExtPackage | This package contains the following classes, which are used in org.omg.CosNaming.NamingContextExt:

Classes in org.omg.CosNaming.NamingContextExtPackage used by org.omg.CosNaming
InvalidAddress
org/omg/CosNaming/NamingContextExtPackage/InvalidAddress.java .

Classes in org.omg.CosNaming.NamingContextExtPackage used by org.omg.CosNaming.NamingContextExtPackage
InvalidAddress
org/omg/CosNaming/NamingContextExtPackage/InvalidAddress.java .

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AddressHelper

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextExtPackage
Class AddressHelper

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextExtPackage.AddressHelper

public abstract class AddressHelper
extends Object

Address is the Host and Port information represented as a String.

Constructor Summary
AddressHelper()
Method Summary
static String | extract(Any a)
static String | id()
static void | insert(Any a, String that)
static String | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, String value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AddressHelper

public AddressHelper()
Method Detail

insert

public static void insert(Any a,
                          String that)

extract

public static String extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static String read(InputStream istream)

write

public static void write(OutputStream ostream,
                         String value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class org.omg.CosNaming.NamingContextExtPackage.AddressHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextExtPackage.AddressHelper

No usage of org.omg.CosNaming.NamingContextExtPackage.AddressHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextExtPackage.InvalidAddress

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextExtPackage.InvalidAddress

Packages that use InvalidAddress
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextExtPackage | This package contains the following classes, which are used in org.omg.CosNaming.NamingContextExt:

Uses of InvalidAddress in org.omg.CosNaming

Methods in org.omg.CosNaming that throw InvalidAddress
String | _NamingContextExtStub.to_url(String addr, String sn) This operation creates a URL based "iiopname://" format name from the Stringified Name of the object.
String | NamingContextExtOperations.to_url(String addr, String sn) This operation creates a URL based "iiopname://" format name from the Stringified Name of the object.

Uses of InvalidAddress in org.omg.CosNaming.NamingContextExtPackage

Fields in org.omg.CosNaming.NamingContextExtPackage declared as InvalidAddress
 InvalidAddress InvalidAddressHolder.value

Methods in org.omg.CosNaming.NamingContextExtPackage that return InvalidAddress
static InvalidAddress | InvalidAddressHelper.extract(Any a)
static InvalidAddress | InvalidAddressHelper.read(InputStream istream)

Methods in org.omg.CosNaming.NamingContextExtPackage with parameters of type InvalidAddress
static void | InvalidAddressHelper.insert(Any a, InvalidAddress that)
static void | InvalidAddressHelper.write(OutputStream ostream, InvalidAddress value)

Constructors in org.omg.CosNaming.NamingContextExtPackage with parameters of type InvalidAddress
InvalidAddressHolder(InvalidAddress initialValue)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextExtPackage.InvalidAddressHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextExtPackage.InvalidAddressHelper

No usage of org.omg.CosNaming.NamingContextExtPackage.InvalidAddressHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextExtPackage.InvalidAddressHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextExtPackage.InvalidAddressHolder

No usage of org.omg.CosNaming.NamingContextExtPackage.InvalidAddressHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextExtPackage.StringNameHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextExtPackage.StringNameHelper

No usage of org.omg.CosNaming.NamingContextExtPackage.StringNameHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextExtPackage.URLStringHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextExtPackage.URLStringHelper

No usage of org.omg.CosNaming.NamingContextExtPackage.URLStringHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


InvalidAddress

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextExtPackage
Class InvalidAddress

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CosNaming.NamingContextExtPackage.InvalidAddress
All Implemented Interfaces:
Serializable, IDLEntity
public final class InvalidAddress
extends UserException

org/omg/CosNaming/NamingContextExtPackage/InvalidAddress.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:28 AM GMT-08:00

Constructor Summary
InvalidAddress()
InvalidAddress(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidAddress

public InvalidAddress()

InvalidAddress

public InvalidAddress(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidAddressHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextExtPackage
Class InvalidAddressHelper

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextExtPackage.InvalidAddressHelper

public abstract class InvalidAddressHelper
extends Object

org/omg/CosNaming/NamingContextExtPackage/InvalidAddressHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:28 AM GMT-08:00

Constructor Summary
InvalidAddressHelper()
Method Summary
static InvalidAddress | extract(Any a)
static String | id()
static void | insert(Any a, InvalidAddress that)
static InvalidAddress | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, InvalidAddress value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InvalidAddressHelper

public InvalidAddressHelper()
Method Detail

insert

public static void insert(Any a,
                          InvalidAddress that)

extract

public static InvalidAddress extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static InvalidAddress read(InputStream istream)

write

public static void write(OutputStream ostream,
                         InvalidAddress value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidAddressHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextExtPackage
Class InvalidAddressHolder

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextExtPackage.InvalidAddressHolder
All Implemented Interfaces:
Streamable
public final class InvalidAddressHolder
extends Object
implements Streamable

org/omg/CosNaming/NamingContextExtPackage/InvalidAddressHolder.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:28 AM GMT-08:00

Field Summary
 InvalidAddress value
Constructor Summary
InvalidAddressHolder()
InvalidAddressHolder(InvalidAddress initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public InvalidAddress value
Constructor Detail

InvalidAddressHolder

public InvalidAddressHolder()

InvalidAddressHolder

public InvalidAddressHolder(InvalidAddress initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StringNameHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextExtPackage
Class StringNameHelper

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextExtPackage.StringNameHelper

public abstract class StringNameHelper
extends Object

StringName is the Stringified Name, Array of Name Components represented as a String.

Constructor Summary
StringNameHelper()
Method Summary
static String | extract(Any a)
static String | id()
static void | insert(Any a, String that)
static String | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, String value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StringNameHelper

public StringNameHelper()
Method Detail

insert

public static void insert(Any a,
                          String that)

extract

public static String extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static String read(InputStream istream)

write

public static void write(OutputStream ostream,
                         String value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


URLStringHelper

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextExtPackage
Class URLStringHelper

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextExtPackage.URLStringHelper

public abstract class URLStringHelper
extends Object

URLString is the URL address (corbaloc: or corbaname:) represented as a String.

Constructor Summary
URLStringHelper()
Method Summary
static String | extract(Any a)
static String | id()
static void | insert(Any a, String that)
static String | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, String value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

URLStringHelper

public URLStringHelper()
Method Detail

insert

public static void insert(Any a,
                          String that)

extract

public static String extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static String read(InputStream istream)

write

public static void write(OutputStream ostream,
                         String value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


NamingContextExtPOA

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class NamingContextExtPOA

java.lang.Object
    extended by  org.omg.PortableServer.Servant
        extended by  org.omg.CosNaming.NamingContextExtPOA
All Implemented Interfaces:
InvokeHandler, NamingContextExtOperations, NamingContextOperations
public abstract class NamingContextExtPOA
extends Servant
implements NamingContextExtOperations, InvokeHandler

NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service. Different names can be bound to an object in the same or different contexts at the same time. Using NamingContextExt, you can use URL-based names to bind and resolve.

See CORBA COS Naming Specification.

Constructor Summary
NamingContextExtPOA()
Method Summary
String[] | _all_interfaces(POA poa, byte[] objectId) Used by the ORB to obtain complete type information from the servant.
OutputStream | _invoke(String $method, InputStream in, ResponseHandler $rh) Invoked by the ORB to dispatch a request to the servant.
NamingContextExt | _this()
NamingContextExt | _this(ORB orb)
Methods inherited from class org.omg.PortableServer.Servant
_default_POA, _get_delegate, _get_interface_def, _is_a, _non_existent, _object_id, _orb, _poa, _set_delegate, _this_object, _this_object
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.omg.CosNaming.NamingContextExtOperations
resolve_str, to_name, to_string, to_url
Methods inherited from interface org.omg.CosNaming.NamingContextOperations
bind_context, bind_new_context, bind, destroy, list, new_context, rebind_context, rebind, resolve, unbind

Constructor Detail

NamingContextExtPOA

public NamingContextExtPOA()
Method Detail

_invoke

public OutputStream _invoke(String $method,
                            InputStream in,
                            ResponseHandler $rh)
Description copied from interface: InvokeHandler
Invoked by the ORB to dispatch a request to the servant. ORB passes the method name, an InputStream containing the marshalled arguments, and a ResponseHandler which the servant uses to construct a proper reply. Only CORBA SystemException may be thrown by this method. The method must return an OutputStream created by the ResponseHandler which contains the marshalled reply. A servant must not retain a reference to the ResponseHandler beyond the lifetime of a method invocation. Servant behaviour is defined as follows:

1. Determine correct method, and unmarshal parameters from InputStream.

2. Invoke method implementation.

3. If no user exception, create a normal reply using ResponseHandler.

4. If user exception occurred, create exception reply using ResponseHandler.

5. Marshal reply into OutputStream returned by ResponseHandler.

6. Return OutputStream to ORB.

Specified by:
_invoke in interface InvokeHandler
Parameters:
$method - The method name.
in - The InputStream containing the marshalled arguments.
$rh - The ResponseHandler which the servant uses to construct a proper reply
Returns:
The OutputStream created by the ResponseHandler which contains the marshalled reply

_all_interfaces

public String[] _all_interfaces(POA poa,
                                byte[] objectId)
Description copied from class: Servant
Used by the ORB to obtain complete type information from the servant.

Specified by:
_all_interfaces in class Servant
Parameters:
poa - POA with which the servant is associated.
objectId - is the id corresponding to the object associated with this servant.
Returns:
list of type information for the object.

_this

public NamingContextExt _this()

_this

public NamingContextExt _this(ORB orb)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamingContextHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class NamingContextHelper

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextHelper

public abstract class NamingContextHelper
extends Object

A naming context is an object that contains a set of name bindings in which each name is unique. Different names can be bound to an object in the same or different contexts at the same time.

See CORBA COS Naming Specification.

Constructor Summary
NamingContextHelper()
Method Summary
static NamingContext | extract(Any a)
static String | id()
static void | insert(Any a, NamingContext that)
static NamingContext | narrow(Object obj)
static NamingContext | read(InputStream istream)
static TypeCode | type()
static NamingContext | unchecked_narrow(Object obj)
static void | write(OutputStream ostream, NamingContext value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NamingContextHelper

public NamingContextHelper()
Method Detail

insert

public static void insert(Any a,
                          NamingContext that)

extract

public static NamingContext extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static NamingContext read(InputStream istream)

write

public static void write(OutputStream ostream,
                         NamingContext value)

narrow

public static NamingContext narrow(Object obj)

unchecked_narrow

public static NamingContext unchecked_narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamingContextHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class NamingContextHolder

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextHolder
All Implemented Interfaces:
Streamable
public final class NamingContextHolder
extends Object
implements Streamable

A naming context is an object that contains a set of name bindings in which each name is unique. Different names can be bound to an object in the same or different contexts at the same time.

See CORBA COS Naming Specification.

Field Summary
 NamingContext value
Constructor Summary
NamingContextHolder()
NamingContextHolder(NamingContext initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public NamingContext value
Constructor Detail

NamingContextHolder

public NamingContextHolder()

NamingContextHolder

public NamingContextHolder(NamingContext initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamingContextOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Interface NamingContextOperations

All Known Subinterfaces:
NamingContext, NamingContextExt, NamingContextExtOperations
All Known Implementing Classes:
_NamingContextExtStub, _NamingContextImplBase, _NamingContextStub, NamingContextExtPOA, NamingContextPOA
public interface NamingContextOperations

A naming context is an object that contains a set of name bindings in which each name is unique. Different names can be bound to an object in the same or different contexts at the same time.

See CORBA COS Naming Specification.

Method Summary
void | bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
NamingContext | bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
void | bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | destroy() The destroy operation deletes a naming context.
void | list(int how_many, BindingListHolder bl, BindingIteratorHolder bi) The list operation allows a client to iterate through a set of bindings in a naming context.
NamingContext | new_context() This operation returns a naming context implemented by the same naming server as the context on which the operation was invoked.
void | rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
void | rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
Object | resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.
void | unbind(NameComponent[] n) The unbind operation removes a name binding from a context.

Method Detail

bind

void bind(NameComponent[] n,
          Object obj)
          throws NotFound,
                 CannotProceed,
                 InvalidName,
                 AlreadyBound
Creates a binding of a name and an object in the naming context. Naming contexts that are bound using bind do not participate in name resolution when compound names are passed to be resolved.

Parameters:
n - Name of the object

obj - The Object to bind with the given name

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

AlreadyBound - Indicates an object is already bound to the specified name.

bind_context

void bind_context(NameComponent[] n,
                  NamingContext nc)
                  throws NotFound,
                         CannotProceed,
                         InvalidName,
                         AlreadyBound
Names an object that is a naming context. Naming contexts that are bound using bind_context() participate in name resolution when compound names are passed to be resolved.

Parameters:
n - Name of the object

nc - NamingContect object to bind with the given name

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

AlreadyBound - Indicates an object is already bound to the specified name.

rebind

void rebind(NameComponent[] n,
            Object obj)
            throws NotFound,
                   CannotProceed,
                   InvalidName
Creates a binding of a name and an object in the naming context even if the name is already bound in the context. Naming contexts that are bound using rebind do not participate in name resolution when compound names are passed to be resolved.

Parameters:
n - Name of the object

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

rebind_context

void rebind_context(NameComponent[] n,
                    NamingContext nc)
                    throws NotFound,
                           CannotProceed,
                           InvalidName
Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context. Naming contexts that are bound using rebind_context() participate in name resolution when compound names are passed to be resolved.

Parameters:
n - Name of the object

nc - NamingContect object to rebind with the given name

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

resolve

Object resolve(NameComponent[] n)
               throws NotFound,
                      CannotProceed,
                      InvalidName
The resolve operation is the process of retrieving an object bound to a name in a given context. The given name must exactly match the bound name. The naming service does not return the type of the object. Clients are responsible for "narrowing" the object to the appropriate type. That is, clients typically cast the returned object from Object to a more specialized interface.

Parameters:
n - Name of the object

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

unbind

void unbind(NameComponent[] n)
            throws NotFound,
                   CannotProceed,
                   InvalidName
The unbind operation removes a name binding from a context.

Parameters:
n - Name of the object

Throws:
NotFound - Indicates the name does not identify a binding.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

list

void list(int how_many,
          BindingListHolder bl,
          BindingIteratorHolder bi)
The list operation allows a client to iterate through a set of bindings in a naming context.

The list operation returns at most the requested number of bindings in BindingList bl.

  • If the naming context contains additional bindings, the list operation returns a BindingIterator with the additional bindings.
  • If the naming context does not contain additional bindings, the binding iterator is a nil object reference.

Parameters:
how_many - the maximum number of bindings to return

bl - the returned list of bindings

bi - the returned binding iterator

new_context

NamingContext new_context()
This operation returns a naming context implemented by the same naming server as the context on which the operation was invoked. The new context is not bound to any name.

bind_new_context

NamingContext bind_new_context(NameComponent[] n)
                               throws NotFound,
                                      AlreadyBound,
                                      CannotProceed,
                                      InvalidName
This operation creates a new context and binds it to the name supplied as an argument. The newly-created context is implemented by the same naming server as the context in which it was bound (that is, the naming server that implements the context denoted by the name argument excluding the last component).

Parameters:
n - Name of the object

Throws:
NotFound - Indicates the name does not identify a binding.

AlreadyBound - Indicates an object is already bound to the specified name.

CannotProceed - Indicates that the implementation has given up for some reason. The client, however, may be able to continue the operation at the returned naming context.

InvalidName - Indicates that the name is invalid.

destroy

void destroy()
             throws NotEmpty
The destroy operation deletes a naming context. If the naming context contains bindings, the NotEmpty exception is raised.

Throws:
NotEmpty - Indicates that the Naming Context contains bindings.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamingContextPackage

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.CosNaming.NamingContextPackage

This package contains Exception classes for the org.omg.CosNaming package.

See:
Description

Class Summary
AlreadyBoundHelper | org/omg/CosNaming/NamingContextPackage/AlreadyBoundHelper.java .
AlreadyBoundHolder | org/omg/CosNaming/NamingContextPackage/AlreadyBoundHolder.java .
CannotProceedHelper | org/omg/CosNaming/NamingContextPackage/CannotProceedHelper.java .
CannotProceedHolder | org/omg/CosNaming/NamingContextPackage/CannotProceedHolder.java .
InvalidNameHelper | org/omg/CosNaming/NamingContextPackage/InvalidNameHelper.java .
InvalidNameHolder | org/omg/CosNaming/NamingContextPackage/InvalidNameHolder.java .
NotEmptyHelper | org/omg/CosNaming/NamingContextPackage/NotEmptyHelper.java .
NotEmptyHolder | org/omg/CosNaming/NamingContextPackage/NotEmptyHolder.java .
NotFoundHelper | org/omg/CosNaming/NamingContextPackage/NotFoundHelper.java .
NotFoundHolder | org/omg/CosNaming/NamingContextPackage/NotFoundHolder.java .
NotFoundReason | Indicates the reason for not able to resolve.
NotFoundReasonHelper | Indicates the reason for not able to resolve.
NotFoundReasonHolder | Indicates the reason for not able to resolve.

Exception Summary
AlreadyBound | org/omg/CosNaming/NamingContextPackage/AlreadyBound.java .
CannotProceed | org/omg/CosNaming/NamingContextPackage/CannotProceed.java .
InvalidName | org/omg/CosNaming/NamingContextPackage/InvalidName.java .
NotEmpty | org/omg/CosNaming/NamingContextPackage/NotEmpty.java .
NotFound | org/omg/CosNaming/NamingContextPackage/NotFound.java .

Package org.omg.CosNaming.NamingContextPackage Description

This package contains Exception classes for the org.omg.CosNaming package. The list of exception classes are:

  • AlreadyBound
  • CannotProceed
  • InvalidName
  • NotEmpty
  • NotFound
  • NotFoundReason

    Package Specification

    For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6 ORB complies, see Official Specifications for CORBA support in Java SE 6.

    Since:
    1.4
    Overview Package Class Use Tree Deprecated Index Help
            Java™ Platform
    Standard Ed. 6
    PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.CosNaming.NamingContextPackage Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.CosNaming.NamingContextPackage

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.CosNaming.NamingContextPackage.AlreadyBoundHelper
    • org.omg.CosNaming.NamingContextPackage.AlreadyBoundHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CosNaming.NamingContextPackage.CannotProceedHelper
    • org.omg.CosNaming.NamingContextPackage.CannotProceedHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CosNaming.NamingContextPackage.InvalidNameHelper
    • org.omg.CosNaming.NamingContextPackage.InvalidNameHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CosNaming.NamingContextPackage.NotEmptyHelper
    • org.omg.CosNaming.NamingContextPackage.NotEmptyHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CosNaming.NamingContextPackage.NotFoundHelper
    • org.omg.CosNaming.NamingContextPackage.NotFoundHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.CosNaming.NamingContextPackage.NotFoundReason (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.CosNaming.NamingContextPackage.NotFoundReasonHelper
    • org.omg.CosNaming.NamingContextPackage.NotFoundReasonHolder (implements org.omg.CORBA.portable.Streamable)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.omg.CORBA.UserException (implements org.omg.CORBA.portable.IDLEntity)
          • org.omg.CosNaming.NamingContextPackage.AlreadyBound
          • org.omg.CosNaming.NamingContextPackage.CannotProceed
          • org.omg.CosNaming.NamingContextPackage.InvalidName
          • org.omg.CosNaming.NamingContextPackage.NotEmpty
          • org.omg.CosNaming.NamingContextPackage.NotFound
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.CosNaming.NamingContextPackage

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.CosNaming.NamingContextPackage

Packages that use org.omg.CosNaming.NamingContextPackage
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.

Classes in org.omg.CosNaming.NamingContextPackage used by org.omg.CosNaming
AlreadyBound
org/omg/CosNaming/NamingContextPackage/AlreadyBound.java .
CannotProceed
org/omg/CosNaming/NamingContextPackage/CannotProceed.java .
InvalidName
org/omg/CosNaming/NamingContextPackage/InvalidName.java .
NotEmpty
org/omg/CosNaming/NamingContextPackage/NotEmpty.java .
NotFound
org/omg/CosNaming/NamingContextPackage/NotFound.java .

Classes in org.omg.CosNaming.NamingContextPackage used by org.omg.CosNaming.NamingContextPackage
AlreadyBound
org/omg/CosNaming/NamingContextPackage/AlreadyBound.java .
CannotProceed
org/omg/CosNaming/NamingContextPackage/CannotProceed.java .
InvalidName
org/omg/CosNaming/NamingContextPackage/InvalidName.java .
NotEmpty
org/omg/CosNaming/NamingContextPackage/NotEmpty.java .
NotFound
org/omg/CosNaming/NamingContextPackage/NotFound.java .
NotFoundReason
Indicates the reason for not able to resolve.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AlreadyBound

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class AlreadyBound

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CosNaming.NamingContextPackage.AlreadyBound
All Implemented Interfaces:
Serializable, IDLEntity
public final class AlreadyBound
extends UserException

org/omg/CosNaming/NamingContextPackage/AlreadyBound.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:28 AM GMT-08:00

Constructor Summary
AlreadyBound()
AlreadyBound(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AlreadyBound

public AlreadyBound()

AlreadyBound

public AlreadyBound(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AlreadyBoundHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class AlreadyBoundHelper

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextPackage.AlreadyBoundHelper

public abstract class AlreadyBoundHelper
extends Object

org/omg/CosNaming/NamingContextPackage/AlreadyBoundHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:28 AM GMT-08:00

Constructor Summary
AlreadyBoundHelper()
Method Summary
static AlreadyBound | extract(Any a)
static String | id()
static void | insert(Any a, AlreadyBound that)
static AlreadyBound | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, AlreadyBound value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AlreadyBoundHelper

public AlreadyBoundHelper()
Method Detail

insert

public static void insert(Any a,
                          AlreadyBound that)

extract

public static AlreadyBound extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static AlreadyBound read(InputStream istream)

write

public static void write(OutputStream ostream,
                         AlreadyBound value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AlreadyBoundHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class AlreadyBoundHolder

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextPackage.AlreadyBoundHolder
All Implemented Interfaces:
Streamable
public final class AlreadyBoundHolder
extends Object
implements Streamable

org/omg/CosNaming/NamingContextPackage/AlreadyBoundHolder.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:28 AM GMT-08:00

Field Summary
 AlreadyBound value
Constructor Summary
AlreadyBoundHolder()
AlreadyBoundHolder(AlreadyBound initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public AlreadyBound value
Constructor Detail

AlreadyBoundHolder

public AlreadyBoundHolder()

AlreadyBoundHolder

public AlreadyBoundHolder(AlreadyBound initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CannotProceed

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class CannotProceed

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CosNaming.NamingContextPackage.CannotProceed
All Implemented Interfaces:
Serializable, IDLEntity
public final class CannotProceed
extends UserException

org/omg/CosNaming/NamingContextPackage/CannotProceed.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:28 AM GMT-08:00

Field Summary
NamingContext | cxt
NameComponent[] | rest_of_name
Constructor Summary
CannotProceed()
CannotProceed(NamingContext _cxt, NameComponent[] _rest_of_name)
CannotProceed(String $reason, NamingContext _cxt, NameComponent[] _rest_of_name)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

cxt

public NamingContext cxt

rest_of_name

public NameComponent[] rest_of_name
Constructor Detail

CannotProceed

public CannotProceed()

CannotProceed

public CannotProceed(NamingContext _cxt,
                     NameComponent[] _rest_of_name)

CannotProceed

public CannotProceed(String $reason,
                     NamingContext _cxt,
                     NameComponent[] _rest_of_name)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CannotProceedHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class CannotProceedHelper

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextPackage.CannotProceedHelper

public abstract class CannotProceedHelper
extends Object

org/omg/CosNaming/NamingContextPackage/CannotProceedHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:28 AM GMT-08:00

Constructor Summary
CannotProceedHelper()
Method Summary
static CannotProceed | extract(Any a)
static String | id()
static void | insert(Any a, CannotProceed that)
static CannotProceed | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, CannotProceed value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CannotProceedHelper

public CannotProceedHelper()
Method Detail

insert

public static void insert(Any a,
                          CannotProceed that)

extract

public static CannotProceed extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static CannotProceed read(InputStream istream)

write

public static void write(OutputStream ostream,
                         CannotProceed value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CannotProceedHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class CannotProceedHolder

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextPackage.CannotProceedHolder
All Implemented Interfaces:
Streamable
public final class CannotProceedHolder
extends Object
implements Streamable

org/omg/CosNaming/NamingContextPackage/CannotProceedHolder.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:28 AM GMT-08:00

Field Summary
 CannotProceed value
Constructor Summary
CannotProceedHolder()
CannotProceedHolder(CannotProceed initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public CannotProceed value
Constructor Detail

CannotProceedHolder

public CannotProceedHolder()

CannotProceedHolder

public CannotProceedHolder(CannotProceed initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class org.omg.CosNaming.NamingContextPackage.AlreadyBound

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.AlreadyBound

Packages that use AlreadyBound
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.

Uses of AlreadyBound in org.omg.CosNaming

Methods in org.omg.CosNaming that throw AlreadyBound
void | _NamingContextExtStub.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
void | _NamingContextStub.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
void | NamingContextOperations.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
NamingContext | _NamingContextExtStub.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
NamingContext | _NamingContextStub.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
NamingContext | NamingContextOperations.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
void | _NamingContextExtStub.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | _NamingContextStub.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | NamingContextOperations.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.

Uses of AlreadyBound in org.omg.CosNaming.NamingContextPackage

Fields in org.omg.CosNaming.NamingContextPackage declared as AlreadyBound
 AlreadyBound AlreadyBoundHolder.value

Methods in org.omg.CosNaming.NamingContextPackage that return AlreadyBound
static AlreadyBound | AlreadyBoundHelper.extract(Any a)
static AlreadyBound | AlreadyBoundHelper.read(InputStream istream)

Methods in org.omg.CosNaming.NamingContextPackage with parameters of type AlreadyBound
static void | AlreadyBoundHelper.insert(Any a, AlreadyBound that)
static void | AlreadyBoundHelper.write(OutputStream ostream, AlreadyBound value)

Constructors in org.omg.CosNaming.NamingContextPackage with parameters of type AlreadyBound
AlreadyBoundHolder(AlreadyBound initialValue)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPackage.AlreadyBoundHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.AlreadyBoundHelper

No usage of org.omg.CosNaming.NamingContextPackage.AlreadyBoundHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPackage.AlreadyBoundHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.AlreadyBoundHolder

No usage of org.omg.CosNaming.NamingContextPackage.AlreadyBoundHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPackage.CannotProceed

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.CannotProceed

Packages that use CannotProceed
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.

Uses of CannotProceed in org.omg.CosNaming

Methods in org.omg.CosNaming that throw CannotProceed
void | _NamingContextExtStub.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
void | _NamingContextStub.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
void | NamingContextOperations.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
NamingContext | _NamingContextExtStub.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
NamingContext | _NamingContextStub.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
NamingContext | NamingContextOperations.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
void | _NamingContextExtStub.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | _NamingContextStub.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | NamingContextOperations.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | _NamingContextExtStub.rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
void | _NamingContextStub.rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
void | NamingContextOperations.rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
void | _NamingContextExtStub.rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
void | _NamingContextStub.rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
void | NamingContextOperations.rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
Object | _NamingContextExtStub.resolve_str(String sn) This operation resolves the Stringified name into the object reference.
Object | NamingContextExtOperations.resolve_str(String sn) This operation resolves the Stringified name into the object reference.
Object | _NamingContextExtStub.resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.
Object | _NamingContextStub.resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.
Object | NamingContextOperations.resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.
void | _NamingContextExtStub.unbind(NameComponent[] n) The unbind operation removes a name binding from a context.
void | _NamingContextStub.unbind(NameComponent[] n) The unbind operation removes a name binding from a context.
void | NamingContextOperations.unbind(NameComponent[] n) The unbind operation removes a name binding from a context.

Uses of CannotProceed in org.omg.CosNaming.NamingContextPackage

Fields in org.omg.CosNaming.NamingContextPackage declared as CannotProceed
 CannotProceed CannotProceedHolder.value

Methods in org.omg.CosNaming.NamingContextPackage that return CannotProceed
static CannotProceed | CannotProceedHelper.extract(Any a)
static CannotProceed | CannotProceedHelper.read(InputStream istream)

Methods in org.omg.CosNaming.NamingContextPackage with parameters of type CannotProceed
static void | CannotProceedHelper.insert(Any a, CannotProceed that)
static void | CannotProceedHelper.write(OutputStream ostream, CannotProceed value)

Constructors in org.omg.CosNaming.NamingContextPackage with parameters of type CannotProceed
CannotProceedHolder(CannotProceed initialValue)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPackage.CannotProceedHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.CannotProceedHelper

No usage of org.omg.CosNaming.NamingContextPackage.CannotProceedHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPackage.CannotProceedHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.CannotProceedHolder

No usage of org.omg.CosNaming.NamingContextPackage.CannotProceedHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPackage.InvalidName

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.InvalidName

Packages that use InvalidName
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.

Uses of InvalidName in org.omg.CosNaming

Methods in org.omg.CosNaming that throw InvalidName
void | _NamingContextExtStub.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
void | _NamingContextStub.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
void | NamingContextOperations.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
NamingContext | _NamingContextExtStub.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
NamingContext | _NamingContextStub.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
NamingContext | NamingContextOperations.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
void | _NamingContextExtStub.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | _NamingContextStub.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | NamingContextOperations.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | _NamingContextExtStub.rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
void | _NamingContextStub.rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
void | NamingContextOperations.rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
void | _NamingContextExtStub.rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
void | _NamingContextStub.rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
void | NamingContextOperations.rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
Object | _NamingContextExtStub.resolve_str(String sn) This operation resolves the Stringified name into the object reference.
Object | NamingContextExtOperations.resolve_str(String sn) This operation resolves the Stringified name into the object reference.
Object | _NamingContextExtStub.resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.
Object | _NamingContextStub.resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.
Object | NamingContextOperations.resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.
NameComponent[] | _NamingContextExtStub.to_name(String sn) This operation converts a Stringified Name into an equivalent array of Name Components.
NameComponent[] | NamingContextExtOperations.to_name(String sn) This operation converts a Stringified Name into an equivalent array of Name Components.
String | _NamingContextExtStub.to_string(NameComponent[] n) This operation creates a stringified name from the array of Name components.
String | NamingContextExtOperations.to_string(NameComponent[] n) This operation creates a stringified name from the array of Name components.
String | _NamingContextExtStub.to_url(String addr, String sn) This operation creates a URL based "iiopname://" format name from the Stringified Name of the object.
String | NamingContextExtOperations.to_url(String addr, String sn) This operation creates a URL based "iiopname://" format name from the Stringified Name of the object.
void | _NamingContextExtStub.unbind(NameComponent[] n) The unbind operation removes a name binding from a context.
void | _NamingContextStub.unbind(NameComponent[] n) The unbind operation removes a name binding from a context.
void | NamingContextOperations.unbind(NameComponent[] n) The unbind operation removes a name binding from a context.

Uses of InvalidName in org.omg.CosNaming.NamingContextPackage

Fields in org.omg.CosNaming.NamingContextPackage declared as InvalidName
 InvalidName InvalidNameHolder.value

Methods in org.omg.CosNaming.NamingContextPackage that return InvalidName
static InvalidName | InvalidNameHelper.extract(Any a)
static InvalidName | InvalidNameHelper.read(InputStream istream)

Methods in org.omg.CosNaming.NamingContextPackage with parameters of type InvalidName
static void | InvalidNameHelper.insert(Any a, InvalidName that)
static void | InvalidNameHelper.write(OutputStream ostream, InvalidName value)

Constructors in org.omg.CosNaming.NamingContextPackage with parameters of type InvalidName
InvalidNameHolder(InvalidName initialValue)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPackage.InvalidNameHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.InvalidNameHelper

No usage of org.omg.CosNaming.NamingContextPackage.InvalidNameHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPackage.InvalidNameHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.InvalidNameHolder

No usage of org.omg.CosNaming.NamingContextPackage.InvalidNameHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPackage.NotEmpty

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.NotEmpty

Packages that use NotEmpty
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.

Uses of NotEmpty in org.omg.CosNaming

Methods in org.omg.CosNaming that throw NotEmpty
void | _NamingContextExtStub.destroy() The destroy operation deletes a naming context.
void | _NamingContextStub.destroy() The destroy operation deletes a naming context.
void | NamingContextOperations.destroy() The destroy operation deletes a naming context.

Uses of NotEmpty in org.omg.CosNaming.NamingContextPackage

Fields in org.omg.CosNaming.NamingContextPackage declared as NotEmpty
 NotEmpty NotEmptyHolder.value

Methods in org.omg.CosNaming.NamingContextPackage that return NotEmpty
static NotEmpty | NotEmptyHelper.extract(Any a)
static NotEmpty | NotEmptyHelper.read(InputStream istream)

Methods in org.omg.CosNaming.NamingContextPackage with parameters of type NotEmpty
static void | NotEmptyHelper.insert(Any a, NotEmpty that)
static void | NotEmptyHelper.write(OutputStream ostream, NotEmpty value)

Constructors in org.omg.CosNaming.NamingContextPackage with parameters of type NotEmpty
NotEmptyHolder(NotEmpty initialValue)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPackage.NotEmptyHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.NotEmptyHelper

No usage of org.omg.CosNaming.NamingContextPackage.NotEmptyHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPackage.NotEmptyHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.NotEmptyHolder

No usage of org.omg.CosNaming.NamingContextPackage.NotEmptyHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPackage.NotFound

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.NotFound

Packages that use NotFound
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.CosNaming.NamingContextPackage | This package contains Exception classes for the org.omg.CosNaming package.

Uses of NotFound in org.omg.CosNaming

Methods in org.omg.CosNaming that throw NotFound
void | _NamingContextExtStub.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
void | _NamingContextStub.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
void | NamingContextOperations.bind_context(NameComponent[] n, NamingContext nc) Names an object that is a naming context.
NamingContext | _NamingContextExtStub.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
NamingContext | _NamingContextStub.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
NamingContext | NamingContextOperations.bind_new_context(NameComponent[] n) This operation creates a new context and binds it to the name supplied as an argument.
void | _NamingContextExtStub.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | _NamingContextStub.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | NamingContextOperations.bind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context.
void | _NamingContextExtStub.rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
void | _NamingContextStub.rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
void | NamingContextOperations.rebind_context(NameComponent[] n, NamingContext nc) Creates a binding of a name and a naming context in the naming context even if the name is already bound in the context.
void | _NamingContextExtStub.rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
void | _NamingContextStub.rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
void | NamingContextOperations.rebind(NameComponent[] n, Object obj) Creates a binding of a name and an object in the naming context even if the name is already bound in the context.
Object | _NamingContextExtStub.resolve_str(String sn) This operation resolves the Stringified name into the object reference.
Object | NamingContextExtOperations.resolve_str(String sn) This operation resolves the Stringified name into the object reference.
Object | _NamingContextExtStub.resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.
Object | _NamingContextStub.resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.
Object | NamingContextOperations.resolve(NameComponent[] n) The resolve operation is the process of retrieving an object bound to a name in a given context.
void | _NamingContextExtStub.unbind(NameComponent[] n) The unbind operation removes a name binding from a context.
void | _NamingContextStub.unbind(NameComponent[] n) The unbind operation removes a name binding from a context.
void | NamingContextOperations.unbind(NameComponent[] n) The unbind operation removes a name binding from a context.

Uses of NotFound in org.omg.CosNaming.NamingContextPackage

Fields in org.omg.CosNaming.NamingContextPackage declared as NotFound
 NotFound NotFoundHolder.value

Methods in org.omg.CosNaming.NamingContextPackage that return NotFound
static NotFound | NotFoundHelper.extract(Any a)
static NotFound | NotFoundHelper.read(InputStream istream)

Methods in org.omg.CosNaming.NamingContextPackage with parameters of type NotFound
static void | NotFoundHelper.insert(Any a, NotFound that)
static void | NotFoundHelper.write(OutputStream ostream, NotFound value)

Constructors in org.omg.CosNaming.NamingContextPackage with parameters of type NotFound
NotFoundHolder(NotFound initialValue)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPackage.NotFoundHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.NotFoundHelper

No usage of org.omg.CosNaming.NamingContextPackage.NotFoundHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPackage.NotFoundHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.NotFoundHolder

No usage of org.omg.CosNaming.NamingContextPackage.NotFoundHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPackage.NotFoundReason

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.NotFoundReason

Packages that use NotFoundReason
org.omg.CosNaming.NamingContextPackage This package contains Exception classes for the org.omg.CosNaming package.

Uses of NotFoundReason in org.omg.CosNaming.NamingContextPackage

Fields in org.omg.CosNaming.NamingContextPackage declared as NotFoundReason
static NotFoundReason | NotFoundReason.missing_node
static NotFoundReason | NotFoundReason.not_context
static NotFoundReason | NotFoundReason.not_object
NotFoundReason | NotFoundReasonHolder.value
NotFoundReason | NotFound.why

Methods in org.omg.CosNaming.NamingContextPackage that return NotFoundReason
static NotFoundReason | NotFoundReasonHelper.extract(Any a)
static NotFoundReason | NotFoundReason.from_int(int value)
static NotFoundReason | NotFoundReasonHelper.read(InputStream istream)

Methods in org.omg.CosNaming.NamingContextPackage with parameters of type NotFoundReason
static void | NotFoundReasonHelper.insert(Any a, NotFoundReason that)
static void | NotFoundReasonHelper.write(OutputStream ostream, NotFoundReason value)

Constructors in org.omg.CosNaming.NamingContextPackage with parameters of type NotFoundReason
NotFound(NotFoundReason _why, NameComponent[] _rest_of_name)
NotFound(String $reason, NotFoundReason _why, NameComponent[] _rest_of_name)
NotFoundReasonHolder(NotFoundReason initialValue)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPackage.NotFoundReasonHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.NotFoundReasonHelper

No usage of org.omg.CosNaming.NamingContextPackage.NotFoundReasonHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.CosNaming.NamingContextPackage.NotFoundReasonHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.CosNaming.NamingContextPackage.NotFoundReasonHolder

No usage of org.omg.CosNaming.NamingContextPackage.NotFoundReasonHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


InvalidName

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class InvalidName

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CosNaming.NamingContextPackage.InvalidName
All Implemented Interfaces:
Serializable, IDLEntity
public final class InvalidName
extends UserException

org/omg/CosNaming/NamingContextPackage/InvalidName.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:28 AM GMT-08:00

Constructor Summary
InvalidName()
InvalidName(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidName

public InvalidName()

InvalidName

public InvalidName(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidNameHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class InvalidNameHelper

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextPackage.InvalidNameHelper

public abstract class InvalidNameHelper
extends Object

org/omg/CosNaming/NamingContextPackage/InvalidNameHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:28 AM GMT-08:00

Constructor Summary
InvalidNameHelper()
Method Summary
static InvalidName | extract(Any a)
static String | id()
static void | insert(Any a, InvalidName that)
static InvalidName | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, InvalidName value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InvalidNameHelper

public InvalidNameHelper()
Method Detail

insert

public static void insert(Any a,
                          InvalidName that)

extract

public static InvalidName extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static InvalidName read(InputStream istream)

write

public static void write(OutputStream ostream,
                         InvalidName value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidNameHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class InvalidNameHolder

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextPackage.InvalidNameHolder
All Implemented Interfaces:
Streamable
public final class InvalidNameHolder
extends Object
implements Streamable

org/omg/CosNaming/NamingContextPackage/InvalidNameHolder.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:28 AM GMT-08:00

Field Summary
 InvalidName value
Constructor Summary
InvalidNameHolder()
InvalidNameHolder(InvalidName initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public InvalidName value
Constructor Detail

InvalidNameHolder

public InvalidNameHolder()

InvalidNameHolder

public InvalidNameHolder(InvalidName initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotEmpty

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class NotEmpty

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CosNaming.NamingContextPackage.NotEmpty
All Implemented Interfaces:
Serializable, IDLEntity
public final class NotEmpty
extends UserException

org/omg/CosNaming/NamingContextPackage/NotEmpty.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:28 AM GMT-08:00

Constructor Summary
NotEmpty()
NotEmpty(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NotEmpty

public NotEmpty()

NotEmpty

public NotEmpty(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotEmptyHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class NotEmptyHelper

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextPackage.NotEmptyHelper

public abstract class NotEmptyHelper
extends Object

org/omg/CosNaming/NamingContextPackage/NotEmptyHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:28 AM GMT-08:00

Constructor Summary
NotEmptyHelper()
Method Summary
static NotEmpty | extract(Any a)
static String | id()
static void | insert(Any a, NotEmpty that)
static NotEmpty | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, NotEmpty value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NotEmptyHelper

public NotEmptyHelper()
Method Detail

insert

public static void insert(Any a,
                          NotEmpty that)

extract

public static NotEmpty extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static NotEmpty read(InputStream istream)

write

public static void write(OutputStream ostream,
                         NotEmpty value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotEmptyHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class NotEmptyHolder

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextPackage.NotEmptyHolder
All Implemented Interfaces:
Streamable
public final class NotEmptyHolder
extends Object
implements Streamable

org/omg/CosNaming/NamingContextPackage/NotEmptyHolder.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:28 AM GMT-08:00

Field Summary
 NotEmpty value
Constructor Summary
NotEmptyHolder()
NotEmptyHolder(NotEmpty initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public NotEmpty value
Constructor Detail

NotEmptyHolder

public NotEmptyHolder()

NotEmptyHolder

public NotEmptyHolder(NotEmpty initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotFound

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class NotFound

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.CosNaming.NamingContextPackage.NotFound
All Implemented Interfaces:
Serializable, IDLEntity
public final class NotFound
extends UserException

org/omg/CosNaming/NamingContextPackage/NotFound.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:28 AM GMT-08:00

Field Summary
NameComponent[] | rest_of_name
NotFoundReason | why
Constructor Summary
NotFound()
NotFound(NotFoundReason _why, NameComponent[] _rest_of_name)
NotFound(String $reason, NotFoundReason _why, NameComponent[] _rest_of_name)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

why

public NotFoundReason why

rest_of_name

public NameComponent[] rest_of_name
Constructor Detail

NotFound

public NotFound()

NotFound

public NotFound(NotFoundReason _why,
                NameComponent[] _rest_of_name)

NotFound

public NotFound(String $reason,
                NotFoundReason _why,
                NameComponent[] _rest_of_name)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotFoundHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class NotFoundHelper

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextPackage.NotFoundHelper

public abstract class NotFoundHelper
extends Object

org/omg/CosNaming/NamingContextPackage/NotFoundHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:27 AM GMT-08:00

Constructor Summary
NotFoundHelper()
Method Summary
static NotFound | extract(Any a)
static String | id()
static void | insert(Any a, NotFound that)
static NotFound | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, NotFound value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NotFoundHelper

public NotFoundHelper()
Method Detail

insert

public static void insert(Any a,
                          NotFound that)

extract

public static NotFound extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static NotFound read(InputStream istream)

write

public static void write(OutputStream ostream,
                         NotFound value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotFoundHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class NotFoundHolder

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextPackage.NotFoundHolder
All Implemented Interfaces:
Streamable
public final class NotFoundHolder
extends Object
implements Streamable

org/omg/CosNaming/NamingContextPackage/NotFoundHolder.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/CosNaming/nameservice.idl Wednesday, November 29, 2006 1:57:28 AM GMT-08:00

Field Summary
 NotFound value
Constructor Summary
NotFoundHolder()
NotFoundHolder(NotFound initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public NotFound value
Constructor Detail

NotFoundHolder

public NotFoundHolder()

NotFoundHolder

public NotFoundHolder(NotFound initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotFoundReason

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class NotFoundReason

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextPackage.NotFoundReason
All Implemented Interfaces:
Serializable, IDLEntity
public class NotFoundReason
extends Object
implements IDLEntity

Indicates the reason for not able to resolve.

Field Summary
static int | _missing_node
static int | _not_context
static int | _not_object
static NotFoundReason | missing_node
static NotFoundReason | not_context
static NotFoundReason | not_object
Constructor Summary
protected NotFoundReason(int value)
Method Summary
static NotFoundReason | from_int(int value)
int | value()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_missing_node

public static final int _missing_node
See Also:
Constant Field Values

missing_node

public static final NotFoundReason missing_node

_not_context

public static final int _not_context
See Also:
Constant Field Values

not_context

public static final NotFoundReason not_context

_not_object

public static final int _not_object
See Also:
Constant Field Values

not_object

public static final NotFoundReason not_object
Constructor Detail

NotFoundReason

protected NotFoundReason(int value)
Method Detail

value

public int value()

from_int

public static NotFoundReason from_int(int value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotFoundReasonHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class NotFoundReasonHelper

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextPackage.NotFoundReasonHelper

public abstract class NotFoundReasonHelper
extends Object

Indicates the reason for not able to resolve.

Constructor Summary
NotFoundReasonHelper()
Method Summary
static NotFoundReason | extract(Any a)
static String | id()
static void | insert(Any a, NotFoundReason that)
static NotFoundReason | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, NotFoundReason value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NotFoundReasonHelper

public NotFoundReasonHelper()
Method Detail

insert

public static void insert(Any a,
                          NotFoundReason that)

extract

public static NotFoundReason extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static NotFoundReason read(InputStream istream)

write

public static void write(OutputStream ostream,
                         NotFoundReason value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NotFoundReasonHolder

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming.NamingContextPackage
Class NotFoundReasonHolder

java.lang.Object
    extended by  org.omg.CosNaming.NamingContextPackage.NotFoundReasonHolder
All Implemented Interfaces:
Streamable
public final class NotFoundReasonHolder
extends Object
implements Streamable

Indicates the reason for not able to resolve.

Field Summary
 NotFoundReason value
Constructor Summary
NotFoundReasonHolder()
NotFoundReasonHolder(NotFoundReason initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public NotFoundReason value
Constructor Detail

NotFoundReasonHolder

public NotFoundReasonHolder()

NotFoundReasonHolder

public NotFoundReasonHolder(NotFoundReason initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


NamingContextPOA

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.CosNaming
Class NamingContextPOA

java.lang.Object
    extended by  org.omg.PortableServer.Servant
        extended by  org.omg.CosNaming.NamingContextPOA
All Implemented Interfaces:
InvokeHandler, NamingContextOperations
public abstract class NamingContextPOA
extends Servant
implements NamingContextOperations, InvokeHandler

A naming context is an object that contains a set of name bindings in which each name is unique. Different names can be bound to an object in the same or different contexts at the same time.

See CORBA COS Naming Specification.

Constructor Summary
NamingContextPOA()
Method Summary
String[] | _all_interfaces(POA poa, byte[] objectId) Used by the ORB to obtain complete type information from the servant.
OutputStream | _invoke(String $method, InputStream in, ResponseHandler $rh) Invoked by the ORB to dispatch a request to the servant.
NamingContext | _this()
NamingContext | _this(ORB orb)
Methods inherited from class org.omg.PortableServer.Servant
_default_POA, _get_delegate, _get_interface_def, _is_a, _non_existent, _object_id, _orb, _poa, _set_delegate, _this_object, _this_object
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.omg.CosNaming.NamingContextOperations
bind_context, bind_new_context, bind, destroy, list, new_context, rebind_context, rebind, resolve, unbind

Constructor Detail

NamingContextPOA

public NamingContextPOA()
Method Detail

_invoke

public OutputStream _invoke(String $method,
                            InputStream in,
                            ResponseHandler $rh)
Description copied from interface: InvokeHandler
Invoked by the ORB to dispatch a request to the servant. ORB passes the method name, an InputStream containing the marshalled arguments, and a ResponseHandler which the servant uses to construct a proper reply. Only CORBA SystemException may be thrown by this method. The method must return an OutputStream created by the ResponseHandler which contains the marshalled reply. A servant must not retain a reference to the ResponseHandler beyond the lifetime of a method invocation. Servant behaviour is defined as follows:

1. Determine correct method, and unmarshal parameters from InputStream.

2. Invoke method implementation.

3. If no user exception, create a normal reply using ResponseHandler.

4. If user exception occurred, create exception reply using ResponseHandler.

5. Marshal reply into OutputStream returned by ResponseHandler.

6. Return OutputStream to ORB.

Specified by:
_invoke in interface InvokeHandler
Parameters:
$method - The method name.
in - The InputStream containing the marshalled arguments.
$rh - The ResponseHandler which the servant uses to construct a proper reply
Returns:
The OutputStream created by the ResponseHandler which contains the marshalled reply

_all_interfaces

public String[] _all_interfaces(POA poa,
                                byte[] objectId)
Description copied from class: Servant
Used by the ORB to obtain complete type information from the servant.

Specified by:
_all_interfaces in class Servant
Parameters:
poa - POA with which the servant is associated.
objectId - is the id corresponding to the object associated with this servant.
Returns:
list of type information for the object.

_this

public NamingContext _this()

_this

public NamingContext _this(ORB orb)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Dynamic

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.Dynamic

This package contains the Dynamic module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.9.

See:
Description

Class Summary
Parameter org/omg/Dynamic/Parameter.java .

Package org.omg.Dynamic Description

This package contains the Dynamic module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.9. Please refer to that OMG specification for further details.

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6 ORB complies, see Official Specifications for CORBA support in Java[tm] SE 6.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.Dynamic Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.Dynamic

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.Dynamic.Parameter (implements org.omg.CORBA.portable.IDLEntity)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.Dynamic

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.Dynamic

Packages that use org.omg.Dynamic
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Classes in org.omg.Dynamic used by org.omg.PortableInterceptor
Parameter
org/omg/Dynamic/Parameter.java .

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.Dynamic.Parameter

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.Dynamic.Parameter

Packages that use Parameter
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of Parameter in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor that return Parameter
 Parameter[] RequestInfoOperations.arguments()
Returns an array of Parameter objects, containing the arguments on the operation being invoked.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Parameter

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.Dynamic
Class Parameter

java.lang.Object
    extended by  org.omg.Dynamic.Parameter
All Implemented Interfaces:
Serializable, IDLEntity
public final class Parameter
extends Object
implements IDLEntity

org/omg/Dynamic/Parameter.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:25 AM GMT-08:00

Field Summary
Any | argument
ParameterMode | mode
Constructor Summary
Parameter()
Parameter(Any _argument, ParameterMode _mode)
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

argument

public Any argument

mode

public ParameterMode mode
Constructor Detail

Parameter

public Parameter()

Parameter

public Parameter(Any _argument,
                 ParameterMode _mode)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


DynamicAny

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.DynamicAny

Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

See:
Description

Interface Summary
DynAny | Any values can be dynamically interpreted (traversed) and constructed through DynAny objects.
DynAnyFactory | DynAny objects can be created by invoking operations on the DynAnyFactory object.
DynAnyFactoryOperations | DynAny objects can be created by invoking operations on the DynAnyFactory object.
DynAnyOperations | Any values can be dynamically interpreted (traversed) and constructed through DynAny objects.
DynArray | DynArray objects support the manipulation of IDL arrays.
DynArrayOperations | DynArray objects support the manipulation of IDL arrays.
DynEnum | DynEnum objects support the manipulation of IDL enumerated values.
DynEnumOperations | DynEnum objects support the manipulation of IDL enumerated values.
DynFixed | DynFixed objects support the manipulation of IDL fixed values.
DynFixedOperations | DynFixed objects support the manipulation of IDL fixed values.
DynSequence | DynSequence objects support the manipulation of IDL sequences.
DynSequenceOperations | DynSequence objects support the manipulation of IDL sequences.
DynStruct | DynStruct objects support the manipulation of IDL struct and exception values.
DynStructOperations | DynStruct objects support the manipulation of IDL struct and exception values.
DynUnion | DynUnion objects support the manipulation of IDL unions.
DynUnionOperations | DynUnion objects support the manipulation of IDL unions.
DynValue | DynValue objects support the manipulation of IDL non-boxed value types.
DynValueBox | DynValueBox objects support the manipulation of IDL boxed value types.
DynValueBoxOperations | DynValueBox objects support the manipulation of IDL boxed value types.
DynValueCommon | DynValueCommon provides operations supported by both the DynValue and DynValueBox interfaces.
DynValueCommonOperations | DynValueCommon provides operations supported by both the DynValue and DynValueBox interfaces.
DynValueOperations | DynValue objects support the manipulation of IDL non-boxed value types.

Class Summary
_DynAnyFactoryStub | DynAny objects can be created by invoking operations on the DynAnyFactory object.
_DynAnyStub | Any values can be dynamically interpreted (traversed) and constructed through DynAny objects.
_DynArrayStub | DynArray objects support the manipulation of IDL arrays.
_DynEnumStub | DynEnum objects support the manipulation of IDL enumerated values.
_DynFixedStub | DynFixed objects support the manipulation of IDL fixed values.
_DynSequenceStub | DynSequence objects support the manipulation of IDL sequences.
_DynStructStub | DynStruct objects support the manipulation of IDL struct and exception values.
_DynUnionStub | DynUnion objects support the manipulation of IDL unions.
_DynValueStub | DynValue objects support the manipulation of IDL non-boxed value types.
AnySeqHelper | org/omg/DynamicAny/AnySeqHelper.java .
DynAnyFactoryHelper | DynAny objects can be created by invoking operations on the DynAnyFactory object.
DynAnyHelper | Any values can be dynamically interpreted (traversed) and constructed through DynAny objects.
DynAnySeqHelper | org/omg/DynamicAny/DynAnySeqHelper.java .
DynArrayHelper | DynArray objects support the manipulation of IDL arrays.
DynEnumHelper | DynEnum objects support the manipulation of IDL enumerated values.
DynFixedHelper | DynFixed objects support the manipulation of IDL fixed values.
DynSequenceHelper | DynSequence objects support the manipulation of IDL sequences.
DynStructHelper | DynStruct objects support the manipulation of IDL struct and exception values.
DynUnionHelper | DynUnion objects support the manipulation of IDL unions.
DynValueHelper | DynValue objects support the manipulation of IDL non-boxed value types.
FieldNameHelper | org/omg/DynamicAny/FieldNameHelper.java .
NameDynAnyPair | org/omg/DynamicAny/NameDynAnyPair.java .
NameDynAnyPairHelper | org/omg/DynamicAny/NameDynAnyPairHelper.java .
NameDynAnyPairSeqHelper | org/omg/DynamicAny/NameDynAnyPairSeqHelper.java .
NameValuePair | org/omg/DynamicAny/NameValuePair.java .
NameValuePairHelper | org/omg/DynamicAny/NameValuePairHelper.java .
NameValuePairSeqHelper | org/omg/DynamicAny/NameValuePairSeqHelper.java .

Package org.omg.DynamicAny Description

Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

An any can be passed to a program that doesn't have any static information for the type of the any (code generated for the type by an IDL compiler has not been compiled with the object implementation). As a result, the object receiving the any does not have a portable method of using it.

DynAnys enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value. This is especially helpful for writing powerful generic servers (bridges, event channels supporting filtering). Similarly, this facility enables the construction of an any at runtime, without having static knowledge of its type. This is especially helpful for writing generic clients (bridges, browsers, debuggers, user interface tools).

Any values can be dynamically interpreted (traversed) and constructed through DynAny objects. A DynAny object is associated with a data value which corresponds to a copy of the value inserted into an Any. A DynAny object may be viewed as an ordered collection of component DynAnys. For DynAnys representing a basic type, such as long, or a type without components, such as an empty exception, the ordered collection of components is empty.

Each DynAny object maintains the notion of a current position into its collection of component DynAnys. The current position is identified by an index value that runs from 0 to n-1, where n is the number of components. The special index value -1 indicates a current position that points nowhere. For values that cannot have a current position (such as an empty exception), the index value is fixed at -1. If a DynAny is initialized with a value that has components, the index is initialized to 0. After creation of an uninitialized DynAny (that is, a DynAny that has no value but a TypeCode that permits components), the current position depends on the type of value represented by the DynAny. (The current position is set to 0 or -1, depending on whether the new DynAny gets default values for its components.)

The iteration operations rewind, seek, and next can be used to change the current position and the current_component operation returns the component at the current position. The component_count operation returns the number of components of a DynAny. Collectively, these operations enable iteration over the components of a DynAny, for example, to (recursively) examine its contents.

A constructed DynAny object is a DynAny object associated with a constructed type. There is a different interface, inheriting from the DynAny interface, associated with each kind of constructed type in IDL (fixed, enum, struct, sequence, union, array, exception, and value type). A constructed DynAny object exports operations that enable the creation of new DynAny objects, each of them associated with a component of the constructed data value. As an example, a DynStruct is associated with a struct value. This means that the DynStruct may be seen as owning an ordered collection of components, one for each structure member. The DynStruct object exports operations that enable the creation of new DynAny objects, each of them associated with a member of the struct.

If a DynAny object has been obtained from another (constructed) DynAny object, such as a DynAny representing a structure member that was created from a DynStruct, the member DynAny is logically contained in the DynStruct. Calling an insert or get operation leaves the current position unchanged. Destroying a top-level DynAny object (one that was not obtained as a component of another DynAny) also destroys any component DynAny objects obtained from it. Destroying a non-top level DynAny object does nothing. Invoking operations on a destroyed top-level DynAny or any of its descendants raises OBJECT_NOT_EXIST. If the programmer wants to destroy a DynAny object but still wants to manipulate some component of the data value associated with it, then he or she should first create a DynAny for the component and, after that, make a copy of the created DynAny object.

The behavior of DynAny objects has been defined in order to enable efficient implementations in terms of allocated memory space and speed of access. DynAny objects are intended to be used for traversing values extracted from anys or constructing values of anys at runtime. Their use for other purposes is not recommended.

Handling DynAny objects

Insert and get operations are necessary to handle basic DynAny objects but are also helpful to handle constructed DynAny objects. Inserting a basic data type value into a constructed DynAny object implies initializing the current component of the constructed data value associated with the DynAny object. For example, invoking insert_boolean on a DynStruct implies inserting a boolean data value at the current position of the associated struct data value. A type is consistent for inserting or extracting a value if its TypeCode is equivalent to the TypeCode contained in the DynAny or, if the DynAny has components, is equivalent to the TypeCode of the DynAny at the current position.

Basic operations include:

  • insert_boolean, get_boolean
  • insert_char, get_char
  • insert_short, get_short
  • insert_ushort, get_ushort
  • insert_long, get_long
  • insert_ulong, get_ulong
  • insert_double, get_double
  • insert_string, get_string
  • insert_reference, get_reference
  • insert_typecode, get_typecode
  • insert_longlong, get_longlong
  • insert_ulonglong, get_ulonglong
  • insert_longdouble, get_longdouble
  • insert_wchar, get_wchar
  • insert_wstring, get_wstring
  • insert_any, get_any
  • insert_dyn_any, get_dyn_any
  • insert_val, get_val
  • insert_octet, get_octet
  • insert_float, get_float
  • get_value
  • get_as_string
  • get_as_ulong
  • get_members
  • get_members_as_dyn_any
  • get_discriminator
  • get_length
  • get_elements
  • get_elements_as_dyn_any
  • get_boxed_value
  • get_boxed_value_as_dyn_any

DynAny and DynAnyFactory objects are intended to be local to the process in which they are created and used. This means that references to DynAny and DynAnyFactory objects cannot be exported to other processes, or externalized with ORB.object_to_string(). If any attempt is made to do so, the offending operation will raise a MARSHAL system exception. Since their interfaces are specified in IDL, DynAny objects export operations defined in the standard org.omg.CORBA.Object interface. However, any attempt to invoke operations exported through the Object interface may raise the standard NO_IMPLEMENT exception. An attempt to use a DynAny object with the DII may raise the NO_IMPLEMENT exception.

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6 ORB complies, see Official Specifications for CORBA support in Java[tm] SE 6.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


_DynFixedStub

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class _DynFixedStub

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.DynamicAny._DynFixedStub
All Implemented Interfaces:
Serializable, Object, IDLEntity, DynAny, DynAnyOperations, DynFixed, DynFixedOperations
public class _DynFixedStub
extends ObjectImpl
implements DynFixed

DynFixed objects support the manipulation of IDL fixed values. Because IDL does not have a generic type that can represent fixed types with arbitrary number of digits and arbitrary scale, the operations use the IDL string type.

Field Summary
static Class _opsClass
Constructor Summary
_DynFixedStub()
Method Summary
 String[] _ids()
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
 void assign(DynAny dyn_any)
Initializes the value associated with a DynAny object with the value associated with another DynAny object.
 int component_count()
Returns the number of components of a DynAny.
 DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
 DynAny current_component()
Returns the DynAny for the component at the current position.
 void destroy()
Destroys a DynAny object.
 boolean equal(DynAny dyn_any)
Compares two DynAny values for equality.
 void from_any(Any value)
Initializes the value associated with a DynAny object with the value contained in an any.
 Any get_any()
Extracts an Any value contained in the Any represented by this DynAny.
 boolean get_boolean()
Extracts the boolean value from this DynAny.
 char get_char()
Extracts the char value from this DynAny.
 double get_double()
Extracts the double value from this DynAny.
 DynAny get_dyn_any()
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
 float get_float()
Extracts the float value from this DynAny.
 int get_long()
Extracts the integer value from this DynAny.
 long get_longlong()
Extracts the long value from this DynAny.
 byte get_octet()
Extracts the byte value from this DynAny.
 Object get_reference()
Extracts the reference to a CORBA Object from this DynAny.
 short get_short()
Extracts the short value from this DynAny.
 String get_string()
Extracts the string value from this DynAny.
 TypeCode get_typecode()
Extracts the TypeCode object from this DynAny.
 int get_ulong()
Extracts the integer value from this DynAny.
 long get_ulonglong()
Extracts the long value from this DynAny.
 short get_ushort()
Extracts the short value from this DynAny.
 Serializable get_val()
Extracts a Serializable object from this DynAny.
 String get_value()
Returns the value of a DynFixed.
 char get_wchar()
Extracts the long value from this DynAny.
 String get_wstring()
Extracts the string value from this DynAny.
 void insert_any(Any value)
Inserts an Any value into the Any represented by this DynAny.
 void insert_boolean(boolean value)
Inserts a boolean value into the DynAny.
 void insert_char(char value)
Inserts a char value into the DynAny.
 void insert_double(double value)
Inserts a double value into the DynAny.
 void insert_dyn_any(DynAny value)
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
 void insert_float(float value)
Inserts a float value into the DynAny.
 void insert_long(int value)
Inserts an integer value into the DynAny.
 void insert_longlong(long value)
Inserts a long value into the DynAny.
 void insert_octet(byte value)
Inserts a byte value into the DynAny.
 void insert_reference(Object value)
Inserts a reference to a CORBA object into the DynAny.
 void insert_short(short value)
Inserts a short value into the DynAny.
 void insert_string(String value)
Inserts a string value into the DynAny.
 void insert_typecode(TypeCode value)
Inserts a TypeCode object into the DynAny.
 void insert_ulong(int value)
Inserts an integer value into the DynAny.
 void insert_ulonglong(long value)
Inserts a long value into the DynAny.
 void insert_ushort(short value)
Inserts a short value into the DynAny.
 void insert_val(Serializable value)
Inserts a reference to a Serializable object into this DynAny.
 void insert_wchar(char value)
Inserts a char value into the DynAny.
 void insert_wstring(String value)
Inserts a string value into the DynAny.
 boolean next()
Advances the current position to the next component.
 void rewind()
Is equivalent to seek(0).
 boolean seek(int index)
Sets the current position to index.
 boolean set_value(String val)
Sets the value of the DynFixed.
 Any to_any()
Creates an any value from a DynAny object.
 TypeCode type()
Returns the TypeCode associated with this DynAny object.
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Field Detail

_opsClass

public static final Class _opsClass
Constructor Detail

_DynFixedStub

public _DynFixedStub()
Method Detail

get_value

public String get_value()
Returns the value of a DynFixed.

Specified by:
get_value in interface DynFixedOperations

set_value

public boolean set_value(String val)
                  throws TypeMismatch,
                         InvalidValue
Sets the value of the DynFixed. The val string must contain a fixed string constant in the same format as used for IDL fixed-point literals. However, the trailing d or D is optional. The return value is true if val can be represented as the DynFixed without loss of precision. If val has more fractional digits than can be represented in the DynFixed, fractional digits are truncated and the return value is false.

Specified by:
set_value in interface DynFixedOperations
Throws:
TypeMismatch - If val does not contain a valid fixed-point literal or contains extraneous characters other than leading or trailing white space
InvalidValue - If val contains a value whose scale exceeds that of the DynFixed or is not initialized

type

public TypeCode type()
Returns the TypeCode associated with this DynAny object. A DynAny object is created with a TypeCode value assigned to it. This TypeCode value determines the type of the value handled through the DynAny object. Note that the TypeCode associated with a DynAny object is initialized at the time the DynAny is created and cannot be changed during lifetime of the DynAny object.

Specified by:
type in interface DynAnyOperations
Returns:
The TypeCode associated with this DynAny object

assign

public void assign(DynAny dyn_any)
            throws TypeMismatch
Initializes the value associated with a DynAny object with the value associated with another DynAny object. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Specified by:
assign in interface DynAnyOperations
Parameters:
dyn_any -
Throws:
TypeMismatch - if the type of the passed DynAny is not equivalent to the type of target DynAny

from_any

public void from_any(Any value)
              throws TypeMismatch,
                     InvalidValue
Initializes the value associated with a DynAny object with the value contained in an any. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Specified by:
from_any in interface DynAnyOperations
Throws:
TypeMismatch - if the type of the passed Any is not equivalent to the type of target DynAny
InvalidValue - if the passed Any does not contain a legal value (such as a null string)

to_any

public Any to_any()
Creates an any value from a DynAny object. A copy of the TypeCode associated with the DynAny object is assigned to the resulting any. The value associated with the DynAny object is copied into the any.

Specified by:
to_any in interface DynAnyOperations
Returns:
a new Any object with the same value and TypeCode

equal

public boolean equal(DynAny dyn_any)
Compares two DynAny values for equality. Two DynAny values are equal if their TypeCodes are equivalent and, recursively, all component DynAnys have equal values. The current position of the two DynAnys being compared has no effect on the result of equal.

Specified by:
equal in interface DynAnyOperations
Returns:
true of the DynAnys are equal, false otherwise

destroy

public void destroy()
Destroys a DynAny object. This operation frees any resources used to represent the data value associated with a DynAny object. It must be invoked on references obtained from one of the creation operations on the ORB interface or on a reference returned by DynAny.copy() to avoid resource leaks. Invoking destroy on component DynAny objects (for example, on objects returned by the current_component operation) does nothing. Destruction of a DynAny object implies destruction of all DynAny objects obtained from it. That is, references to components of a destroyed DynAny become invalid. Invocations on such references raise OBJECT_NOT_EXIST. It is possible to manipulate a component of a DynAny beyond the life time of the DynAny from which the component was obtained by making a copy of the component with the copy operation before destroying the DynAny from which the component was obtained.

Specified by:
destroy in interface DynAnyOperations

copy

public DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked. The operation is polymorphic, that is, invoking it on one of the types derived from DynAny, such as DynStruct, creates the derived type but returns its reference as the DynAny base type.

Specified by:
copy in interface DynAnyOperations
Returns:
a deep copy of the DynAny object

insert_boolean

public void insert_boolean(boolean value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a boolean value into the DynAny.

Specified by:
insert_boolean in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_octet

public void insert_octet(byte value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a byte value into the DynAny. The IDL octet data type is mapped to the Java byte data type.

Specified by:
insert_octet in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_char

public void insert_char(char value)
                 throws TypeMismatch,
                        InvalidValue
Inserts a char value into the DynAny.

Specified by:
insert_char in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_short

public void insert_short(short value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a short value into the DynAny.

Specified by:
insert_short in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ushort

public void insert_ushort(short value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a short value into the DynAny. The IDL ushort data type is mapped to the Java short data type.

Specified by:
insert_ushort in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_long

public void insert_long(int value)
                 throws TypeMismatch,
                        InvalidValue
Inserts an integer value into the DynAny. The IDL long data type is mapped to the Java int data type.

Specified by:
insert_long in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulong

public void insert_ulong(int value)
                  throws TypeMismatch,
                         InvalidValue
Inserts an integer value into the DynAny. The IDL ulong data type is mapped to the Java int data type.

Specified by:
insert_ulong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_float

public void insert_float(float value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a float value into the DynAny.

Specified by:
insert_float in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_double

public void insert_double(double value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a double value into the DynAny.

Specified by:
insert_double in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_string

public void insert_string(String value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Specified by:
insert_string in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch - if called on a DynAny whose current component itself has components

insert_reference

public void insert_reference(Object value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a reference to a CORBA object into the DynAny.

Specified by:
insert_reference in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_typecode

public void insert_typecode(TypeCode value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a TypeCode object into the DynAny.

Specified by:
insert_typecode in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_longlong

public void insert_longlong(long value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a long value into the DynAny. The IDL long long data type is mapped to the Java long data type.

Specified by:
insert_longlong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulonglong

public void insert_ulonglong(long value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a long value into the DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Specified by:
insert_ulonglong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wchar

public void insert_wchar(char value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a char value into the DynAny. The IDL wchar data type is mapped to the Java char data type.

Specified by:
insert_wchar in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wstring

public void insert_wstring(String value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Specified by:
insert_wstring in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch

insert_any

public void insert_any(Any value)
                throws TypeMismatch,
                       InvalidValue
Inserts an Any value into the Any represented by this DynAny.

Specified by:
insert_any in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_dyn_any

public void insert_dyn_any(DynAny value)
                    throws TypeMismatch,
                           InvalidValue
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.

Specified by:
insert_dyn_any in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_val

public void insert_val(Serializable value)
                throws TypeMismatch,
                       InvalidValue
Inserts a reference to a Serializable object into this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Specified by:
insert_val in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

get_boolean

public boolean get_boolean()
                    throws TypeMismatch,
                           InvalidValue
Extracts the boolean value from this DynAny.

Specified by:
get_boolean in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_octet

public byte get_octet()
               throws TypeMismatch,
                      InvalidValue
Extracts the byte value from this DynAny. The IDL octet data type is mapped to the Java byte data type.

Specified by:
get_octet in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_char

public char get_char()
              throws TypeMismatch,
                     InvalidValue
Extracts the char value from this DynAny.

Specified by:
get_char in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_short

public short get_short()
                throws TypeMismatch,
                       InvalidValue
Extracts the short value from this DynAny.

Specified by:
get_short in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ushort

public short get_ushort()
                 throws TypeMismatch,
                        InvalidValue
Extracts the short value from this DynAny. The IDL ushort data type is mapped to the Java short data type.

Specified by:
get_ushort in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_long

public int get_long()
             throws TypeMismatch,
                    InvalidValue
Extracts the integer value from this DynAny. The IDL long data type is mapped to the Java int data type.

Specified by:
get_long in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulong

public int get_ulong()
              throws TypeMismatch,
                     InvalidValue
Extracts the integer value from this DynAny. The IDL ulong data type is mapped to the Java int data type.

Specified by:
get_ulong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_float

public float get_float()
                throws TypeMismatch,
                       InvalidValue
Extracts the float value from this DynAny.

Specified by:
get_float in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_double

public double get_double()
                  throws TypeMismatch,
                         InvalidValue
Extracts the double value from this DynAny.

Specified by:
get_double in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_string

public String get_string()
                  throws TypeMismatch,
                         InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Specified by:
get_string in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_reference

public Object get_reference()
                     throws TypeMismatch,
                            InvalidValue
Extracts the reference to a CORBA Object from this DynAny.

Specified by:
get_reference in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_typecode

public TypeCode get_typecode()
                      throws TypeMismatch,
                             InvalidValue
Extracts the TypeCode object from this DynAny.

Specified by:
get_typecode in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_longlong

public long get_longlong()
                  throws TypeMismatch,
                         InvalidValue
Extracts the long value from this DynAny. The IDL long long data type is mapped to the Java long data type.

Specified by:
get_longlong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulonglong

public long get_ulonglong()
                   throws TypeMismatch,
                          InvalidValue
Extracts the long value from this DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Specified by:
get_ulonglong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wchar

public char get_wchar()
               throws TypeMismatch,
                      InvalidValue
Extracts the long value from this DynAny. The IDL wchar data type is mapped to the Java char data type.

Specified by:
get_wchar in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wstring

public String get_wstring()
                   throws TypeMismatch,
                          InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Specified by:
get_wstring in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue

get_any

public Any get_any()
            throws TypeMismatch,
                   InvalidValue
Extracts an Any value contained in the Any represented by this DynAny.

Specified by:
get_any in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_dyn_any

public DynAny get_dyn_any()
                   throws TypeMismatch,
                          InvalidValue
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.

Specified by:
get_dyn_any in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_val

public Serializable get_val()
                     throws TypeMismatch,
                            InvalidValue
Extracts a Serializable object from this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Specified by:
get_val in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

seek

public boolean seek(int index)
Sets the current position to index. The current position is indexed 0 to n-1, that is, index zero corresponds to the first component. The operation returns true if the resulting current position indicates a component of the DynAny and false if index indicates a position that does not correspond to a component. Calling seek with a negative index is legal. It sets the current position to -1 to indicate no component and returns false. Passing a non-negative index value for a DynAny that does not have a component at the corresponding position sets the current position to -1 and returns false.

Specified by:
seek in interface DynAnyOperations

rewind

public void rewind()
Is equivalent to seek(0).

Specified by:
rewind in interface DynAnyOperations

next

public boolean next()
Advances the current position to the next component. The operation returns true while the resulting current position indicates a component, false otherwise. A false return value leaves the current position at -1. Invoking next on a DynAny without components leaves the current position at -1 and returns false.

Specified by:
next in interface DynAnyOperations

component_count

public int component_count()
Returns the number of components of a DynAny. For a DynAny without components, it returns zero. The operation only counts the components at the top level. For example, if component_count is invoked on a DynStruct with a single member, the return value is 1, irrespective of the type of the member.
  • For sequences, the operation returns the current number of elements.
  • For structures, exceptions, and value types, the operation returns the number of members.
  • For arrays, the operation returns the number of elements.
  • For unions, the operation returns 2 if the discriminator indicates that a named member is active, otherwise, it returns 1.
  • For DynFixed and DynEnum, the operation returns zero.

Specified by:
component_count in interface DynAnyOperations

current_component

public DynAny current_component()
                         throws TypeMismatch
Returns the DynAny for the component at the current position. It does not advance the current position, so repeated calls to current_component without an intervening call to rewind, next, or seek return the same component. The returned DynAny object reference can be used to get/set the value of the current component. If the current component represents a complex type, the returned reference can be narrowed based on the TypeCode to get the interface corresponding to the to the complex type. Calling current_component on a DynAny that cannot have components, such as a DynEnum or an empty exception, raises TypeMismatch. Calling current_component on a DynAny whose current position is -1 returns a nil reference. The iteration operations, together with current_component, can be used to dynamically compose an any value. After creating a dynamic any, such as a DynStruct, current_component and next can be used to initialize all the components of the value. Once the dynamic value is completely initialized, to_any creates the corresponding any value.

Specified by:
current_component in interface DynAnyOperations
Throws:
TypeMismatch - If called on a DynAny that cannot have components, such as a DynEnum or an empty exception

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Specified by:
_ids in class ObjectImpl
Returns:
the array of all repository identifiers supported by this ObjectImpl instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


_DynEnumStub

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class _DynEnumStub

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.DynamicAny._DynEnumStub
All Implemented Interfaces:
Serializable, Object, IDLEntity, DynAny, DynAnyOperations, DynEnum, DynEnumOperations
public class _DynEnumStub
extends ObjectImpl
implements DynEnum

DynEnum objects support the manipulation of IDL enumerated values. The current position of a DynEnum is always -1.

Field Summary
static Class _opsClass
Constructor Summary
_DynEnumStub()
Method Summary
 String[] _ids()
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
 void assign(DynAny dyn_any)
Initializes the value associated with a DynAny object with the value associated with another DynAny object.
 int component_count()
Returns the number of components of a DynAny.
 DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
 DynAny current_component()
Returns the DynAny for the component at the current position.
 void destroy()
Destroys a DynAny object.
 boolean equal(DynAny dyn_any)
Compares two DynAny values for equality.
 void from_any(Any value)
Initializes the value associated with a DynAny object with the value contained in an any.
 Any get_any()
Extracts an Any value contained in the Any represented by this DynAny.
 String get_as_string()
Returns the value of the DynEnum as an IDL identifier.
 int get_as_ulong()
Returns the value of the DynEnum as the enumerated value's ordinal value.
 boolean get_boolean()
Extracts the boolean value from this DynAny.
 char get_char()
Extracts the char value from this DynAny.
 double get_double()
Extracts the double value from this DynAny.
 DynAny get_dyn_any()
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
 float get_float()
Extracts the float value from this DynAny.
 int get_long()
Extracts the integer value from this DynAny.
 long get_longlong()
Extracts the long value from this DynAny.
 byte get_octet()
Extracts the byte value from this DynAny.
 Object get_reference()
Extracts the reference to a CORBA Object from this DynAny.
 short get_short()
Extracts the short value from this DynAny.
 String get_string()
Extracts the string value from this DynAny.
 TypeCode get_typecode()
Extracts the TypeCode object from this DynAny.
 int get_ulong()
Extracts the integer value from this DynAny.
 long get_ulonglong()
Extracts the long value from this DynAny.
 short get_ushort()
Extracts the short value from this DynAny.
 Serializable get_val()
Extracts a Serializable object from this DynAny.
 char get_wchar()
Extracts the long value from this DynAny.
 String get_wstring()
Extracts the string value from this DynAny.
 void insert_any(Any value)
Inserts an Any value into the Any represented by this DynAny.
 void insert_boolean(boolean value)
Inserts a boolean value into the DynAny.
 void insert_char(char value)
Inserts a char value into the DynAny.
 void insert_double(double value)
Inserts a double value into the DynAny.
 void insert_dyn_any(DynAny value)
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
 void insert_float(float value)
Inserts a float value into the DynAny.
 void insert_long(int value)
Inserts an integer value into the DynAny.
 void insert_longlong(long value)
Inserts a long value into the DynAny.
 void insert_octet(byte value)
Inserts a byte value into the DynAny.
 void insert_reference(Object value)
Inserts a reference to a CORBA object into the DynAny.
 void insert_short(short value)
Inserts a short value into the DynAny.
 void insert_string(String value)
Inserts a string value into the DynAny.
 void insert_typecode(TypeCode value)
Inserts a TypeCode object into the DynAny.
 void insert_ulong(int value)
Inserts an integer value into the DynAny.
 void insert_ulonglong(long value)
Inserts a long value into the DynAny.
 void insert_ushort(short value)
Inserts a short value into the DynAny.
 void insert_val(Serializable value)
Inserts a reference to a Serializable object into this DynAny.
 void insert_wchar(char value)
Inserts a char value into the DynAny.
 void insert_wstring(String value)
Inserts a string value into the DynAny.
 boolean next()
Advances the current position to the next component.
 void rewind()
Is equivalent to seek(0).
 boolean seek(int index)
Sets the current position to index.
 void set_as_string(String value)
Sets the value of the DynEnum to the enumerated value whose IDL identifier is passed in the value parameter.
 void set_as_ulong(int value)
Sets the value of the DynEnum as the enumerated value's ordinal value.
 Any to_any()
Creates an any value from a DynAny object.
 TypeCode type()
Returns the TypeCode associated with this DynAny object.
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Field Detail

_opsClass

public static final Class _opsClass
Constructor Detail

_DynEnumStub

public _DynEnumStub()
Method Detail

get_as_string

public String get_as_string()
Returns the value of the DynEnum as an IDL identifier.

Specified by:
get_as_string in interface DynEnumOperations

set_as_string

public void set_as_string(String value)
                   throws InvalidValue
Sets the value of the DynEnum to the enumerated value whose IDL identifier is passed in the value parameter.

Specified by:
set_as_string in interface DynEnumOperations
Throws:
InvalidValue - If value contains a string that is not a valid IDL identifier for the corresponding enumerated type

get_as_ulong

public int get_as_ulong()
Returns the value of the DynEnum as the enumerated value's ordinal value. Enumerators have ordinal values 0 to n-1, as they appear from left to right in the corresponding IDL definition.

Specified by:
get_as_ulong in interface DynEnumOperations

set_as_ulong

public void set_as_ulong(int value)
                  throws InvalidValue
Sets the value of the DynEnum as the enumerated value's ordinal value.

Specified by:
set_as_ulong in interface DynEnumOperations
Throws:
InvalidValue - If value contains a value that is outside the range of ordinal values for the corresponding enumerated type

type

public TypeCode type()
Returns the TypeCode associated with this DynAny object. A DynAny object is created with a TypeCode value assigned to it. This TypeCode value determines the type of the value handled through the DynAny object. Note that the TypeCode associated with a DynAny object is initialized at the time the DynAny is created and cannot be changed during lifetime of the DynAny object.

Specified by:
type in interface DynAnyOperations
Returns:
The TypeCode associated with this DynAny object

assign

public void assign(DynAny dyn_any)
            throws TypeMismatch
Initializes the value associated with a DynAny object with the value associated with another DynAny object. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Specified by:
assign in interface DynAnyOperations
Parameters:
dyn_any -
Throws:
TypeMismatch - if the type of the passed DynAny is not equivalent to the type of target DynAny

from_any

public void from_any(Any value)
              throws TypeMismatch,
                     InvalidValue
Initializes the value associated with a DynAny object with the value contained in an any. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Specified by:
from_any in interface DynAnyOperations
Throws:
TypeMismatch - if the type of the passed Any is not equivalent to the type of target DynAny
InvalidValue - if the passed Any does not contain a legal value (such as a null string)

to_any

public Any to_any()
Creates an any value from a DynAny object. A copy of the TypeCode associated with the DynAny object is assigned to the resulting any. The value associated with the DynAny object is copied into the any.

Specified by:
to_any in interface DynAnyOperations
Returns:
a new Any object with the same value and TypeCode

equal

public boolean equal(DynAny dyn_any)
Compares two DynAny values for equality. Two DynAny values are equal if their TypeCodes are equivalent and, recursively, all component DynAnys have equal values. The current position of the two DynAnys being compared has no effect on the result of equal.

Specified by:
equal in interface DynAnyOperations
Returns:
true of the DynAnys are equal, false otherwise

destroy

public void destroy()
Destroys a DynAny object. This operation frees any resources used to represent the data value associated with a DynAny object. It must be invoked on references obtained from one of the creation operations on the ORB interface or on a reference returned by DynAny.copy() to avoid resource leaks. Invoking destroy on component DynAny objects (for example, on objects returned by the current_component operation) does nothing. Destruction of a DynAny object implies destruction of all DynAny objects obtained from it. That is, references to components of a destroyed DynAny become invalid. Invocations on such references raise OBJECT_NOT_EXIST. It is possible to manipulate a component of a DynAny beyond the life time of the DynAny from which the component was obtained by making a copy of the component with the copy operation before destroying the DynAny from which the component was obtained.

Specified by:
destroy in interface DynAnyOperations

copy

public DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked. The operation is polymorphic, that is, invoking it on one of the types derived from DynAny, such as DynStruct, creates the derived type but returns its reference as the DynAny base type.

Specified by:
copy in interface DynAnyOperations
Returns:
a deep copy of the DynAny object

insert_boolean

public void insert_boolean(boolean value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a boolean value into the DynAny.

Specified by:
insert_boolean in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_octet

public void insert_octet(byte value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a byte value into the DynAny. The IDL octet data type is mapped to the Java byte data type.

Specified by:
insert_octet in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_char

public void insert_char(char value)
                 throws TypeMismatch,
                        InvalidValue
Inserts a char value into the DynAny.

Specified by:
insert_char in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_short

public void insert_short(short value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a short value into the DynAny.

Specified by:
insert_short in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ushort

public void insert_ushort(short value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a short value into the DynAny. The IDL ushort data type is mapped to the Java short data type.

Specified by:
insert_ushort in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_long

public void insert_long(int value)
                 throws TypeMismatch,
                        InvalidValue
Inserts an integer value into the DynAny. The IDL long data type is mapped to the Java int data type.

Specified by:
insert_long in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulong

public void insert_ulong(int value)
                  throws TypeMismatch,
                         InvalidValue
Inserts an integer value into the DynAny. The IDL ulong data type is mapped to the Java int data type.

Specified by:
insert_ulong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_float

public void insert_float(float value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a float value into the DynAny.

Specified by:
insert_float in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_double

public void insert_double(double value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a double value into the DynAny.

Specified by:
insert_double in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_string

public void insert_string(String value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Specified by:
insert_string in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch - if called on a DynAny whose current component itself has components

insert_reference

public void insert_reference(Object value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a reference to a CORBA object into the DynAny.

Specified by:
insert_reference in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_typecode

public void insert_typecode(TypeCode value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a TypeCode object into the DynAny.

Specified by:
insert_typecode in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_longlong

public void insert_longlong(long value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a long value into the DynAny. The IDL long long data type is mapped to the Java long data type.

Specified by:
insert_longlong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulonglong

public void insert_ulonglong(long value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a long value into the DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Specified by:
insert_ulonglong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wchar

public void insert_wchar(char value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a char value into the DynAny. The IDL wchar data type is mapped to the Java char data type.

Specified by:
insert_wchar in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wstring

public void insert_wstring(String value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Specified by:
insert_wstring in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch

insert_any

public void insert_any(Any value)
                throws TypeMismatch,
                       InvalidValue
Inserts an Any value into the Any represented by this DynAny.

Specified by:
insert_any in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_dyn_any

public void insert_dyn_any(DynAny value)
                    throws TypeMismatch,
                           InvalidValue
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.

Specified by:
insert_dyn_any in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_val

public void insert_val(Serializable value)
                throws TypeMismatch,
                       InvalidValue
Inserts a reference to a Serializable object into this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Specified by:
insert_val in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

get_boolean

public boolean get_boolean()
                    throws TypeMismatch,
                           InvalidValue
Extracts the boolean value from this DynAny.

Specified by:
get_boolean in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_octet

public byte get_octet()
               throws TypeMismatch,
                      InvalidValue
Extracts the byte value from this DynAny. The IDL octet data type is mapped to the Java byte data type.

Specified by:
get_octet in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_char

public char get_char()
              throws TypeMismatch,
                     InvalidValue
Extracts the char value from this DynAny.

Specified by:
get_char in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_short

public short get_short()
                throws TypeMismatch,
                       InvalidValue
Extracts the short value from this DynAny.

Specified by:
get_short in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ushort

public short get_ushort()
                 throws TypeMismatch,
                        InvalidValue
Extracts the short value from this DynAny. The IDL ushort data type is mapped to the Java short data type.

Specified by:
get_ushort in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_long

public int get_long()
             throws TypeMismatch,
                    InvalidValue
Extracts the integer value from this DynAny. The IDL long data type is mapped to the Java int data type.

Specified by:
get_long in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulong

public int get_ulong()
              throws TypeMismatch,
                     InvalidValue
Extracts the integer value from this DynAny. The IDL ulong data type is mapped to the Java int data type.

Specified by:
get_ulong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_float

public float get_float()
                throws TypeMismatch,
                       InvalidValue
Extracts the float value from this DynAny.

Specified by:
get_float in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_double

public double get_double()
                  throws TypeMismatch,
                         InvalidValue
Extracts the double value from this DynAny.

Specified by:
get_double in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_string

public String get_string()
                  throws TypeMismatch,
                         InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Specified by:
get_string in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_reference

public Object get_reference()
                     throws TypeMismatch,
                            InvalidValue
Extracts the reference to a CORBA Object from this DynAny.

Specified by:
get_reference in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_typecode

public TypeCode get_typecode()
                      throws TypeMismatch,
                             InvalidValue
Extracts the TypeCode object from this DynAny.

Specified by:
get_typecode in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_longlong

public long get_longlong()
                  throws TypeMismatch,
                         InvalidValue
Extracts the long value from this DynAny. The IDL long long data type is mapped to the Java long data type.

Specified by:
get_longlong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulonglong

public long get_ulonglong()
                   throws TypeMismatch,
                          InvalidValue
Extracts the long value from this DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Specified by:
get_ulonglong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wchar

public char get_wchar()
               throws TypeMismatch,
                      InvalidValue
Extracts the long value from this DynAny. The IDL wchar data type is mapped to the Java char data type.

Specified by:
get_wchar in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wstring

public String get_wstring()
                   throws TypeMismatch,
                          InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Specified by:
get_wstring in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue

get_any

public Any get_any()
            throws TypeMismatch,
                   InvalidValue
Extracts an Any value contained in the Any represented by this DynAny.

Specified by:
get_any in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_dyn_any

public DynAny get_dyn_any()
                   throws TypeMismatch,
                          InvalidValue
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.

Specified by:
get_dyn_any in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_val

public Serializable get_val()
                     throws TypeMismatch,
                            InvalidValue
Extracts a Serializable object from this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Specified by:
get_val in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

seek

public boolean seek(int index)
Sets the current position to index. The current position is indexed 0 to n-1, that is, index zero corresponds to the first component. The operation returns true if the resulting current position indicates a component of the DynAny and false if index indicates a position that does not correspond to a component. Calling seek with a negative index is legal. It sets the current position to -1 to indicate no component and returns false. Passing a non-negative index value for a DynAny that does not have a component at the corresponding position sets the current position to -1 and returns false.

Specified by:
seek in interface DynAnyOperations

rewind

public void rewind()
Is equivalent to seek(0).

Specified by:
rewind in interface DynAnyOperations

next

public boolean next()
Advances the current position to the next component. The operation returns true while the resulting current position indicates a component, false otherwise. A false return value leaves the current position at -1. Invoking next on a DynAny without components leaves the current position at -1 and returns false.

Specified by:
next in interface DynAnyOperations

component_count

public int component_count()
Returns the number of components of a DynAny. For a DynAny without components, it returns zero. The operation only counts the components at the top level. For example, if component_count is invoked on a DynStruct with a single member, the return value is 1, irrespective of the type of the member.
  • For sequences, the operation returns the current number of elements.
  • For structures, exceptions, and value types, the operation returns the number of members.
  • For arrays, the operation returns the number of elements.
  • For unions, the operation returns 2 if the discriminator indicates that a named member is active, otherwise, it returns 1.
  • For DynFixed and DynEnum, the operation returns zero.

Specified by:
component_count in interface DynAnyOperations

current_component

public DynAny current_component()
                         throws TypeMismatch
Returns the DynAny for the component at the current position. It does not advance the current position, so repeated calls to current_component without an intervening call to rewind, next, or seek return the same component. The returned DynAny object reference can be used to get/set the value of the current component. If the current component represents a complex type, the returned reference can be narrowed based on the TypeCode to get the interface corresponding to the to the complex type. Calling current_component on a DynAny that cannot have components, such as a DynEnum or an empty exception, raises TypeMismatch. Calling current_component on a DynAny whose current position is -1 returns a nil reference. The iteration operations, together with current_component, can be used to dynamically compose an any value. After creating a dynamic any, such as a DynStruct, current_component and next can be used to initialize all the components of the value. Once the dynamic value is completely initialized, to_any creates the corresponding any value.

Specified by:
current_component in interface DynAnyOperations
Throws:
TypeMismatch - If called on a DynAny that cannot have components, such as a DynEnum or an empty exception

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Specified by:
_ids in class ObjectImpl
Returns:
the array of all repository identifiers supported by this ObjectImpl instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


_DynValueStub

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class _DynValueStub

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.DynamicAny._DynValueStub
All Implemented Interfaces:
Serializable, Object, IDLEntity, DynAny, DynAnyOperations, DynValue, DynValueCommon, DynValueCommonOperations, DynValueOperations
public class _DynValueStub
extends ObjectImpl
implements DynValue

DynValue objects support the manipulation of IDL non-boxed value types. The DynValue interface can represent both null and non-null value types. For a DynValue representing a non-null value type, the DynValue's components comprise the public and private members of the value type, including those inherited from concrete base value types, in the order of definition. A DynValue representing a null value type has no components and a current position of -1.

Warning: Indiscriminantly changing the contents of private value type members can cause the value type implementation to break by violating internal constraints. Access to private members is provided to support such activities as ORB bridging and debugging and should not be used to arbitrarily violate the encapsulation of the value type.

Field Summary
static Class _opsClass
Constructor Summary
_DynValueStub()
Method Summary
 String[] _ids()
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
 void assign(DynAny dyn_any)
Initializes the value associated with a DynAny object with the value associated with another DynAny object.
 int component_count()
Returns the number of components of a DynAny.
 DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
 DynAny current_component()
Returns the DynAny for the component at the current position.
 TCKind current_member_kind()
Returns the TCKind associated with the member at the current position.
 String current_member_name()
Returns the name of the member at the current position.
 void destroy()
Destroys a DynAny object.
 boolean equal(DynAny dyn_any)
Compares two DynAny values for equality.
 void from_any(Any value)
Initializes the value associated with a DynAny object with the value contained in an any.
 Any get_any()
Extracts an Any value contained in the Any represented by this DynAny.
 boolean get_boolean()
Extracts the boolean value from this DynAny.
 char get_char()
Extracts the char value from this DynAny.
 double get_double()
Extracts the double value from this DynAny.
 DynAny get_dyn_any()
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
 float get_float()
Extracts the float value from this DynAny.
 int get_long()
Extracts the integer value from this DynAny.
 long get_longlong()
Extracts the long value from this DynAny.
 NameDynAnyPair[] get_members_as_dyn_any()
Returns a sequence of NameDynAnyPairs describing the name and the value of each member in the value type.
 NameValuePair[] get_members()
Returns a sequence of NameValuePairs describing the name and the value of each member in the value type.
 byte get_octet()
Extracts the byte value from this DynAny.
 Object get_reference()
Extracts the reference to a CORBA Object from this DynAny.
 short get_short()
Extracts the short value from this DynAny.
 String get_string()
Extracts the string value from this DynAny.
 TypeCode get_typecode()
Extracts the TypeCode object from this DynAny.
 int get_ulong()
Extracts the integer value from this DynAny.
 long get_ulonglong()
Extracts the long value from this DynAny.
 short get_ushort()
Extracts the short value from this DynAny.
 Serializable get_val()
Extracts a Serializable object from this DynAny.
 char get_wchar()
Extracts the long value from this DynAny.
 String get_wstring()
Extracts the string value from this DynAny.
 void insert_any(Any value)
Inserts an Any value into the Any represented by this DynAny.
 void insert_boolean(boolean value)
Inserts a boolean value into the DynAny.
 void insert_char(char value)
Inserts a char value into the DynAny.
 void insert_double(double value)
Inserts a double value into the DynAny.
 void insert_dyn_any(DynAny value)
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
 void insert_float(float value)
Inserts a float value into the DynAny.
 void insert_long(int value)
Inserts an integer value into the DynAny.
 void insert_longlong(long value)
Inserts a long value into the DynAny.
 void insert_octet(byte value)
Inserts a byte value into the DynAny.
 void insert_reference(Object value)
Inserts a reference to a CORBA object into the DynAny.
 void insert_short(short value)
Inserts a short value into the DynAny.
 void insert_string(String value)
Inserts a string value into the DynAny.
 void insert_typecode(TypeCode value)
Inserts a TypeCode object into the DynAny.
 void insert_ulong(int value)
Inserts an integer value into the DynAny.
 void insert_ulonglong(long value)
Inserts a long value into the DynAny.
 void insert_ushort(short value)
Inserts a short value into the DynAny.
 void insert_val(Serializable value)
Inserts a reference to a Serializable object into this DynAny.
 void insert_wchar(char value)
Inserts a char value into the DynAny.
 void insert_wstring(String value)
Inserts a string value into the DynAny.
 boolean is_null()
Returns true if the DynValueCommon represents a null value type.
 boolean next()
Advances the current position to the next component.
 void rewind()
Is equivalent to seek(0).
 boolean seek(int index)
Sets the current position to index.
 void set_members_as_dyn_any(NameDynAnyPair[] value)
Initializes the value type's members from a sequence of NameDynAnyPairs.
 void set_members(NameValuePair[] value)
Initializes the value type's members from a sequence of NameValuePairs.
 void set_to_null()
Changes the representation of a DynValueCommon to a null value type.
 void set_to_value()
Replaces a null value type with a newly constructed value.
 Any to_any()
Creates an any value from a DynAny object.
 TypeCode type()
Returns the TypeCode associated with this DynAny object.
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Field Detail

_opsClass

public static final Class _opsClass
Constructor Detail

_DynValueStub

public _DynValueStub()
Method Detail

current_member_name

public String current_member_name()
                           throws TypeMismatch,
                                  InvalidValue
Returns the name of the member at the current position. This operation may return an empty string since the TypeCode of the value being manipulated may not contain the names of members.

Specified by:
current_member_name in interface DynValueOperations
Throws:
TypeMismatch - if the DynValue represents a null value type.
InvalidValue - if the current position does not indicate a member

current_member_kind

public TCKind current_member_kind()
                           throws TypeMismatch,
                                  InvalidValue
Returns the TCKind associated with the member at the current position.

Specified by:
current_member_kind in interface DynValueOperations
Throws:
TypeMismatch - if the DynValue represents a null value type.
InvalidValue - if the current position does not indicate a member

get_members

public NameValuePair[] get_members()
                            throws InvalidValue
Returns a sequence of NameValuePairs describing the name and the value of each member in the value type. The sequence contains members in the same order as the declaration order of members as indicated by the DynValue's TypeCode. The current position is not affected. The member names in the returned sequence will be empty strings if the DynValue's TypeCode does not contain member names.

Specified by:
get_members in interface DynValueOperations
Throws:
InvalidValue - if this object represents a null value type

set_members

public void set_members(NameValuePair[] value)
                 throws TypeMismatch,
                        InvalidValue
Initializes the value type's members from a sequence of NameValuePairs. The operation sets the current position to zero if the passed sequences has non-zero length. Otherwise, if an empty sequence is passed, the current position is set to -1. A null value type can be initialized to a non-null value type using this method.

Members must appear in the NameValuePairs in the order in which they appear in the IDL specification of the value type as indicated by the DynValue's TypeCode or they must be empty strings. The operation makes no attempt to assign member values based on member names.

Specified by:
set_members in interface DynValueOperations
Throws:
TypeMismatch - if the member names supplied in the passed sequence do not match the corresponding member name in the DynValue's TypeCode and they are not empty strings
InvalidValue - if the passed sequence has a number of elements that disagrees with the number of members as indicated by the DynValue's TypeCode

get_members_as_dyn_any

public NameDynAnyPair[] get_members_as_dyn_any()
                                        throws InvalidValue
Returns a sequence of NameDynAnyPairs describing the name and the value of each member in the value type. The sequence contains members in the same order as the declaration order of members as indicated by the DynValue's TypeCode. The current position is not affected. The member names in the returned sequence will be empty strings if the DynValue's TypeCode does not contain member names.

Specified by:
get_members_as_dyn_any in interface DynValueOperations
Throws:
InvalidValue - if this object represents a null value type

set_members_as_dyn_any

public void set_members_as_dyn_any(NameDynAnyPair[] value)
                            throws TypeMismatch,
                                   InvalidValue
Initializes the value type's members from a sequence of NameDynAnyPairs. The operation sets the current position to zero if the passed sequences has non-zero length. Otherwise, if an empty sequence is passed, the current position is set to -1. A null value type can be initialized to a non-null value type using this method.

Members must appear in the NameDynAnyPairs in the order in which they appear in the IDL specification of the value type as indicated by the DynValue's TypeCode or they must be empty strings. The operation makes no attempt to assign member values based on member names.

Specified by:
set_members_as_dyn_any in interface DynValueOperations
Throws:
TypeMismatch - if the member names supplied in the passed sequence do not match the corresponding member name in the DynValue's TypeCode and they are not empty strings
InvalidValue - if the passed sequence has a number of elements that disagrees with the number of members as indicated by the DynValue's TypeCode

is_null

public boolean is_null()
Returns true if the DynValueCommon represents a null value type.

Specified by:
is_null in interface DynValueCommonOperations

set_to_null

public void set_to_null()
Changes the representation of a DynValueCommon to a null value type.

Specified by:
set_to_null in interface DynValueCommonOperations

set_to_value

public void set_to_value()
Replaces a null value type with a newly constructed value. Its components are initialized to default values as in DynAnyFactory.create_dyn_any_from_type_code. If the DynValueCommon represents a non-null value type, then this operation has no effect.

Specified by:
set_to_value in interface DynValueCommonOperations

type

public TypeCode type()
Returns the TypeCode associated with this DynAny object. A DynAny object is created with a TypeCode value assigned to it. This TypeCode value determines the type of the value handled through the DynAny object. Note that the TypeCode associated with a DynAny object is initialized at the time the DynAny is created and cannot be changed during lifetime of the DynAny object.

Specified by:
type in interface DynAnyOperations
Returns:
The TypeCode associated with this DynAny object

assign

public void assign(DynAny dyn_any)
            throws TypeMismatch
Initializes the value associated with a DynAny object with the value associated with another DynAny object. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Specified by:
assign in interface DynAnyOperations
Parameters:
dyn_any -
Throws:
TypeMismatch - if the type of the passed DynAny is not equivalent to the type of target DynAny

from_any

public void from_any(Any value)
              throws TypeMismatch,
                     InvalidValue
Initializes the value associated with a DynAny object with the value contained in an any. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Specified by:
from_any in interface DynAnyOperations
Throws:
TypeMismatch - if the type of the passed Any is not equivalent to the type of target DynAny
InvalidValue - if the passed Any does not contain a legal value (such as a null string)

to_any

public Any to_any()
Creates an any value from a DynAny object. A copy of the TypeCode associated with the DynAny object is assigned to the resulting any. The value associated with the DynAny object is copied into the any.

Specified by:
to_any in interface DynAnyOperations
Returns:
a new Any object with the same value and TypeCode

equal

public boolean equal(DynAny dyn_any)
Compares two DynAny values for equality. Two DynAny values are equal if their TypeCodes are equivalent and, recursively, all component DynAnys have equal values. The current position of the two DynAnys being compared has no effect on the result of equal.

Specified by:
equal in interface DynAnyOperations
Returns:
true of the DynAnys are equal, false otherwise

destroy

public void destroy()
Destroys a DynAny object. This operation frees any resources used to represent the data value associated with a DynAny object. It must be invoked on references obtained from one of the creation operations on the ORB interface or on a reference returned by DynAny.copy() to avoid resource leaks. Invoking destroy on component DynAny objects (for example, on objects returned by the current_component operation) does nothing. Destruction of a DynAny object implies destruction of all DynAny objects obtained from it. That is, references to components of a destroyed DynAny become invalid. Invocations on such references raise OBJECT_NOT_EXIST. It is possible to manipulate a component of a DynAny beyond the life time of the DynAny from which the component was obtained by making a copy of the component with the copy operation before destroying the DynAny from which the component was obtained.

Specified by:
destroy in interface DynAnyOperations

copy

public DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked. The operation is polymorphic, that is, invoking it on one of the types derived from DynAny, such as DynStruct, creates the derived type but returns its reference as the DynAny base type.

Specified by:
copy in interface DynAnyOperations
Returns:
a deep copy of the DynAny object

insert_boolean

public void insert_boolean(boolean value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a boolean value into the DynAny.

Specified by:
insert_boolean in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_octet

public void insert_octet(byte value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a byte value into the DynAny. The IDL octet data type is mapped to the Java byte data type.

Specified by:
insert_octet in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_char

public void insert_char(char value)
                 throws TypeMismatch,
                        InvalidValue
Inserts a char value into the DynAny.

Specified by:
insert_char in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_short

public void insert_short(short value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a short value into the DynAny.

Specified by:
insert_short in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ushort

public void insert_ushort(short value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a short value into the DynAny. The IDL ushort data type is mapped to the Java short data type.

Specified by:
insert_ushort in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_long

public void insert_long(int value)
                 throws TypeMismatch,
                        InvalidValue
Inserts an integer value into the DynAny. The IDL long data type is mapped to the Java int data type.

Specified by:
insert_long in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulong

public void insert_ulong(int value)
                  throws TypeMismatch,
                         InvalidValue
Inserts an integer value into the DynAny. The IDL ulong data type is mapped to the Java int data type.

Specified by:
insert_ulong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_float

public void insert_float(float value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a float value into the DynAny.

Specified by:
insert_float in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_double

public void insert_double(double value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a double value into the DynAny.

Specified by:
insert_double in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_string

public void insert_string(String value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Specified by:
insert_string in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch - if called on a DynAny whose current component itself has components

insert_reference

public void insert_reference(Object value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a reference to a CORBA object into the DynAny.

Specified by:
insert_reference in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_typecode

public void insert_typecode(TypeCode value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a TypeCode object into the DynAny.

Specified by:
insert_typecode in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_longlong

public void insert_longlong(long value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a long value into the DynAny. The IDL long long data type is mapped to the Java long data type.

Specified by:
insert_longlong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulonglong

public void insert_ulonglong(long value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a long value into the DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Specified by:
insert_ulonglong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wchar

public void insert_wchar(char value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a char value into the DynAny. The IDL wchar data type is mapped to the Java char data type.

Specified by:
insert_wchar in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wstring

public void insert_wstring(String value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Specified by:
insert_wstring in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch

insert_any

public void insert_any(Any value)
                throws TypeMismatch,
                       InvalidValue
Inserts an Any value into the Any represented by this DynAny.

Specified by:
insert_any in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_dyn_any

public void insert_dyn_any(DynAny value)
                    throws TypeMismatch,
                           InvalidValue
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.

Specified by:
insert_dyn_any in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_val

public void insert_val(Serializable value)
                throws TypeMismatch,
                       InvalidValue
Inserts a reference to a Serializable object into this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Specified by:
insert_val in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

get_boolean

public boolean get_boolean()
                    throws TypeMismatch,
                           InvalidValue
Extracts the boolean value from this DynAny.

Specified by:
get_boolean in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_octet

public byte get_octet()
               throws TypeMismatch,
                      InvalidValue
Extracts the byte value from this DynAny. The IDL octet data type is mapped to the Java byte data type.

Specified by:
get_octet in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_char

public char get_char()
              throws TypeMismatch,
                     InvalidValue
Extracts the char value from this DynAny.

Specified by:
get_char in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_short

public short get_short()
                throws TypeMismatch,
                       InvalidValue
Extracts the short value from this DynAny.

Specified by:
get_short in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ushort

public short get_ushort()
                 throws TypeMismatch,
                        InvalidValue
Extracts the short value from this DynAny. The IDL ushort data type is mapped to the Java short data type.

Specified by:
get_ushort in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_long

public int get_long()
             throws TypeMismatch,
                    InvalidValue
Extracts the integer value from this DynAny. The IDL long data type is mapped to the Java int data type.

Specified by:
get_long in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulong

public int get_ulong()
              throws TypeMismatch,
                     InvalidValue
Extracts the integer value from this DynAny. The IDL ulong data type is mapped to the Java int data type.

Specified by:
get_ulong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_float

public float get_float()
                throws TypeMismatch,
                       InvalidValue
Extracts the float value from this DynAny.

Specified by:
get_float in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_double

public double get_double()
                  throws TypeMismatch,
                         InvalidValue
Extracts the double value from this DynAny.

Specified by:
get_double in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_string

public String get_string()
                  throws TypeMismatch,
                         InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Specified by:
get_string in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_reference

public Object get_reference()
                     throws TypeMismatch,
                            InvalidValue
Extracts the reference to a CORBA Object from this DynAny.

Specified by:
get_reference in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_typecode

public TypeCode get_typecode()
                      throws TypeMismatch,
                             InvalidValue
Extracts the TypeCode object from this DynAny.

Specified by:
get_typecode in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_longlong

public long get_longlong()
                  throws TypeMismatch,
                         InvalidValue
Extracts the long value from this DynAny. The IDL long long data type is mapped to the Java long data type.

Specified by:
get_longlong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulonglong

public long get_ulonglong()
                   throws TypeMismatch,
                          InvalidValue
Extracts the long value from this DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Specified by:
get_ulonglong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wchar

public char get_wchar()
               throws TypeMismatch,
                      InvalidValue
Extracts the long value from this DynAny. The IDL wchar data type is mapped to the Java char data type.

Specified by:
get_wchar in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wstring

public String get_wstring()
                   throws TypeMismatch,
                          InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Specified by:
get_wstring in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue

get_any

public Any get_any()
            throws TypeMismatch,
                   InvalidValue
Extracts an Any value contained in the Any represented by this DynAny.

Specified by:
get_any in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_dyn_any

public DynAny get_dyn_any()
                   throws TypeMismatch,
                          InvalidValue
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.

Specified by:
get_dyn_any in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_val

public Serializable get_val()
                     throws TypeMismatch,
                            InvalidValue
Extracts a Serializable object from this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Specified by:
get_val in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

seek

public boolean seek(int index)
Sets the current position to index. The current position is indexed 0 to n-1, that is, index zero corresponds to the first component. The operation returns true if the resulting current position indicates a component of the DynAny and false if index indicates a position that does not correspond to a component. Calling seek with a negative index is legal. It sets the current position to -1 to indicate no component and returns false. Passing a non-negative index value for a DynAny that does not have a component at the corresponding position sets the current position to -1 and returns false.

Specified by:
seek in interface DynAnyOperations

rewind

public void rewind()
Is equivalent to seek(0).

Specified by:
rewind in interface DynAnyOperations

next

public boolean next()
Advances the current position to the next component. The operation returns true while the resulting current position indicates a component, false otherwise. A false return value leaves the current position at -1. Invoking next on a DynAny without components leaves the current position at -1 and returns false.

Specified by:
next in interface DynAnyOperations

component_count

public int component_count()
Returns the number of components of a DynAny. For a DynAny without components, it returns zero. The operation only counts the components at the top level. For example, if component_count is invoked on a DynStruct with a single member, the return value is 1, irrespective of the type of the member.
  • For sequences, the operation returns the current number of elements.
  • For structures, exceptions, and value types, the operation returns the number of members.
  • For arrays, the operation returns the number of elements.
  • For unions, the operation returns 2 if the discriminator indicates that a named member is active, otherwise, it returns 1.
  • For DynFixed and DynEnum, the operation returns zero.

Specified by:
component_count in interface DynAnyOperations

current_component

public DynAny current_component()
                         throws TypeMismatch
Returns the DynAny for the component at the current position. It does not advance the current position, so repeated calls to current_component without an intervening call to rewind, next, or seek return the same component. The returned DynAny object reference can be used to get/set the value of the current component. If the current component represents a complex type, the returned reference can be narrowed based on the TypeCode to get the interface corresponding to the to the complex type. Calling current_component on a DynAny that cannot have components, such as a DynEnum or an empty exception, raises TypeMismatch. Calling current_component on a DynAny whose current position is -1 returns a nil reference. The iteration operations, together with current_component, can be used to dynamically compose an any value. After creating a dynamic any, such as a DynStruct, current_component and next can be used to initialize all the components of the value. Once the dynamic value is completely initialized, to_any creates the corresponding any value.

Specified by:
current_component in interface DynAnyOperations
Throws:
TypeMismatch - If called on a DynAny that cannot have components, such as a DynEnum or an empty exception

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Specified by:
_ids in class ObjectImpl
Returns:
the array of all repository identifiers supported by this ObjectImpl instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


_DynAnyStub

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class _DynAnyStub

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.DynamicAny._DynAnyStub
All Implemented Interfaces:
Serializable, Object, IDLEntity, DynAny, DynAnyOperations
public class _DynAnyStub
extends ObjectImpl
implements DynAny

Any values can be dynamically interpreted (traversed) and constructed through DynAny objects. A DynAny object is associated with a data value which corresponds to a copy of the value inserted into an any.

A DynAny object may be viewed as an ordered collection of component DynAnys. For DynAnys representing a basic type, such as long, or a type without components, such as an empty exception, the ordered collection of components is empty. Each DynAny object maintains the notion of a current position into its collection of component DynAnys. The current position is identified by an index value that runs from 0 to n-1, where n is the number of components. The special index value -1 indicates a current position that points nowhere. For values that cannot have a current position (such as an empty exception), the index value is fixed at -1. If a DynAny is initialized with a value that has components, the index is initialized to 0. After creation of an uninitialized DynAny (that is, a DynAny that has no value but a TypeCode that permits components), the current position depends on the type of value represented by the DynAny. (The current position is set to 0 or -1, depending on whether the new DynAny gets default values for its components.)

The iteration operations rewind, seek, and next can be used to change the current position and the current_component operation returns the component at the current position. The component_count operation returns the number of components of a DynAny. Collectively, these operations enable iteration over the components of a DynAny, for example, to (recursively) examine its contents.

A constructed DynAny object is a DynAny object associated with a constructed type. There is a different interface, inheriting from the DynAny interface, associated with each kind of constructed type in IDL (fixed, enum, struct, sequence, union, array, exception, and value type).

A constructed DynAny object exports operations that enable the creation of new DynAny objects, each of them associated with a component of the constructed data value. As an example, a DynStruct is associated with a struct value. This means that the DynStruct may be seen as owning an ordered collection of components, one for each structure member. The DynStruct object exports operations that enable the creation of new DynAny objects, each of them associated with a member of the struct.

If a DynAny object has been obtained from another (constructed) DynAny object, such as a DynAny representing a structure member that was created from a DynStruct, the member DynAny is logically contained in the DynStruct. Calling an insert or get operation leaves the current position unchanged. Destroying a top-level DynAny object (one that was not obtained as a component of another DynAny) also destroys any component DynAny objects obtained from it. Destroying a non-top level DynAny object does nothing. Invoking operations on a destroyed top-level DynAny or any of its descendants raises OBJECT_NOT_EXIST. If the programmer wants to destroy a DynAny object but still wants to manipulate some component of the data value associated with it, then he or she should first create a DynAny for the component and, after that, make a copy of the created DynAny object.

The behavior of DynAny objects has been defined in order to enable efficient implementations in terms of allocated memory space and speed of access. DynAny objects are intended to be used for traversing values extracted from anys or constructing values of anys at runtime. Their use for other purposes is not recommended.

Insert and get operations are necessary to handle basic DynAny objects but are also helpful to handle constructed DynAny objects. Inserting a basic data type value into a constructed DynAny object implies initializing the current component of the constructed data value associated with the DynAny object. For example, invoking insert_boolean on a DynStruct implies inserting a boolean data value at the current position of the associated struct data value. A type is consistent for inserting or extracting a value if its TypeCode is equivalent to the TypeCode contained in the DynAny or, if the DynAny has components, is equivalent to the TypeCode of the DynAny at the current position.

DynAny and DynAnyFactory objects are intended to be local to the process in which they are created and used. This means that references to DynAny and DynAnyFactory objects cannot be exported to other processes, or externalized with ORB.object_to_string(). If any attempt is made to do so, the offending operation will raise a MARSHAL system exception. Since their interfaces are specified in IDL, DynAny objects export operations defined in the standard org.omg.CORBA.Object interface. However, any attempt to invoke operations exported through the Object interface may raise the standard NO_IMPLEMENT exception. An attempt to use a DynAny object with the DII may raise the NO_IMPLEMENT exception.

Field Summary
static Class _opsClass
Constructor Summary
_DynAnyStub()
Method Summary
 String[] _ids()
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
 void assign(DynAny dyn_any)
Initializes the value associated with a DynAny object with the value associated with another DynAny object.
 int component_count()
Returns the number of components of a DynAny.
 DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
 DynAny current_component()
Returns the DynAny for the component at the current position.
 void destroy()
Destroys a DynAny object.
 boolean equal(DynAny dyn_any)
Compares two DynAny values for equality.
 void from_any(Any value)
Initializes the value associated with a DynAny object with the value contained in an any.
 Any get_any()
Extracts an Any value contained in the Any represented by this DynAny.
 boolean get_boolean()
Extracts the boolean value from this DynAny.
 char get_char()
Extracts the char value from this DynAny.
 double get_double()
Extracts the double value from this DynAny.
 DynAny get_dyn_any()
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
 float get_float()
Extracts the float value from this DynAny.
 int get_long()
Extracts the integer value from this DynAny.
 long get_longlong()
Extracts the long value from this DynAny.
 byte get_octet()
Extracts the byte value from this DynAny.
 Object get_reference()
Extracts the reference to a CORBA Object from this DynAny.
 short get_short()
Extracts the short value from this DynAny.
 String get_string()
Extracts the string value from this DynAny.
 TypeCode get_typecode()
Extracts the TypeCode object from this DynAny.
 int get_ulong()
Extracts the integer value from this DynAny.
 long get_ulonglong()
Extracts the long value from this DynAny.
 short get_ushort()
Extracts the short value from this DynAny.
 Serializable get_val()
Extracts a Serializable object from this DynAny.
 char get_wchar()
Extracts the long value from this DynAny.
 String get_wstring()
Extracts the string value from this DynAny.
 void insert_any(Any value)
Inserts an Any value into the Any represented by this DynAny.
 void insert_boolean(boolean value)
Inserts a boolean value into the DynAny.
 void insert_char(char value)
Inserts a char value into the DynAny.
 void insert_double(double value)
Inserts a double value into the DynAny.
 void insert_dyn_any(DynAny value)
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
 void insert_float(float value)
Inserts a float value into the DynAny.
 void insert_long(int value)
Inserts an integer value into the DynAny.
 void insert_longlong(long value)
Inserts a long value into the DynAny.
 void insert_octet(byte value)
Inserts a byte value into the DynAny.
 void insert_reference(Object value)
Inserts a reference to a CORBA object into the DynAny.
 void insert_short(short value)
Inserts a short value into the DynAny.
 void insert_string(String value)
Inserts a string value into the DynAny.
 void insert_typecode(TypeCode value)
Inserts a TypeCode object into the DynAny.
 void insert_ulong(int value)
Inserts an integer value into the DynAny.
 void insert_ulonglong(long value)
Inserts a long value into the DynAny.
 void insert_ushort(short value)
Inserts a short value into the DynAny.
 void insert_val(Serializable value)
Inserts a reference to a Serializable object into this DynAny.
 void insert_wchar(char value)
Inserts a char value into the DynAny.
 void insert_wstring(String value)
Inserts a string value into the DynAny.
 boolean next()
Advances the current position to the next component.
 void rewind()
Is equivalent to seek(0).
 boolean seek(int index)
Sets the current position to index.
 Any to_any()
Creates an any value from a DynAny object.
 TypeCode type()
Returns the TypeCode associated with this DynAny object.
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Field Detail

_opsClass

public static final Class _opsClass
Constructor Detail

_DynAnyStub

public _DynAnyStub()
Method Detail

type

public TypeCode type()
Returns the TypeCode associated with this DynAny object. A DynAny object is created with a TypeCode value assigned to it. This TypeCode value determines the type of the value handled through the DynAny object. Note that the TypeCode associated with a DynAny object is initialized at the time the DynAny is created and cannot be changed during lifetime of the DynAny object.

Specified by:
type in interface DynAnyOperations
Returns:
The TypeCode associated with this DynAny object

assign

public void assign(DynAny dyn_any)
            throws TypeMismatch
Initializes the value associated with a DynAny object with the value associated with another DynAny object. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Specified by:
assign in interface DynAnyOperations
Parameters:
dyn_any -
Throws:
TypeMismatch - if the type of the passed DynAny is not equivalent to the type of target DynAny

from_any

public void from_any(Any value)
              throws TypeMismatch,
                     InvalidValue
Initializes the value associated with a DynAny object with the value contained in an any. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Specified by:
from_any in interface DynAnyOperations
Throws:
TypeMismatch - if the type of the passed Any is not equivalent to the type of target DynAny
InvalidValue - if the passed Any does not contain a legal value (such as a null string)

to_any

public Any to_any()
Creates an any value from a DynAny object. A copy of the TypeCode associated with the DynAny object is assigned to the resulting any. The value associated with the DynAny object is copied into the any.

Specified by:
to_any in interface DynAnyOperations
Returns:
a new Any object with the same value and TypeCode

equal

public boolean equal(DynAny dyn_any)
Compares two DynAny values for equality. Two DynAny values are equal if their TypeCodes are equivalent and, recursively, all component DynAnys have equal values. The current position of the two DynAnys being compared has no effect on the result of equal.

Specified by:
equal in interface DynAnyOperations
Returns:
true of the DynAnys are equal, false otherwise

destroy

public void destroy()
Destroys a DynAny object. This operation frees any resources used to represent the data value associated with a DynAny object. It must be invoked on references obtained from one of the creation operations on the ORB interface or on a reference returned by DynAny.copy() to avoid resource leaks. Invoking destroy on component DynAny objects (for example, on objects returned by the current_component operation) does nothing. Destruction of a DynAny object implies destruction of all DynAny objects obtained from it. That is, references to components of a destroyed DynAny become invalid. Invocations on such references raise OBJECT_NOT_EXIST. It is possible to manipulate a component of a DynAny beyond the life time of the DynAny from which the component was obtained by making a copy of the component with the copy operation before destroying the DynAny from which the component was obtained.

Specified by:
destroy in interface DynAnyOperations

copy

public DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked. The operation is polymorphic, that is, invoking it on one of the types derived from DynAny, such as DynStruct, creates the derived type but returns its reference as the DynAny base type.

Specified by:
copy in interface DynAnyOperations
Returns:
a deep copy of the DynAny object

insert_boolean

public void insert_boolean(boolean value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a boolean value into the DynAny.

Specified by:
insert_boolean in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_octet

public void insert_octet(byte value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a byte value into the DynAny. The IDL octet data type is mapped to the Java byte data type.

Specified by:
insert_octet in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_char

public void insert_char(char value)
                 throws TypeMismatch,
                        InvalidValue
Inserts a char value into the DynAny.

Specified by:
insert_char in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_short

public void insert_short(short value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a short value into the DynAny.

Specified by:
insert_short in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ushort

public void insert_ushort(short value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a short value into the DynAny. The IDL ushort data type is mapped to the Java short data type.

Specified by:
insert_ushort in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_long

public void insert_long(int value)
                 throws TypeMismatch,
                        InvalidValue
Inserts an integer value into the DynAny. The IDL long data type is mapped to the Java int data type.

Specified by:
insert_long in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulong

public void insert_ulong(int value)
                  throws TypeMismatch,
                         InvalidValue
Inserts an integer value into the DynAny. The IDL ulong data type is mapped to the Java int data type.

Specified by:
insert_ulong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_float

public void insert_float(float value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a float value into the DynAny.

Specified by:
insert_float in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_double

public void insert_double(double value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a double value into the DynAny.

Specified by:
insert_double in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_string

public void insert_string(String value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Specified by:
insert_string in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch - if called on a DynAny whose current component itself has components

insert_reference

public void insert_reference(Object value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a reference to a CORBA object into the DynAny.

Specified by:
insert_reference in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_typecode

public void insert_typecode(TypeCode value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a TypeCode object into the DynAny.

Specified by:
insert_typecode in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_longlong

public void insert_longlong(long value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a long value into the DynAny. The IDL long long data type is mapped to the Java long data type.

Specified by:
insert_longlong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulonglong

public void insert_ulonglong(long value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a long value into the DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Specified by:
insert_ulonglong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wchar

public void insert_wchar(char value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a char value into the DynAny. The IDL wchar data type is mapped to the Java char data type.

Specified by:
insert_wchar in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wstring

public void insert_wstring(String value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Specified by:
insert_wstring in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch

insert_any

public void insert_any(Any value)
                throws TypeMismatch,
                       InvalidValue
Inserts an Any value into the Any represented by this DynAny.

Specified by:
insert_any in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_dyn_any

public void insert_dyn_any(DynAny value)
                    throws TypeMismatch,
                           InvalidValue
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.

Specified by:
insert_dyn_any in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_val

public void insert_val(Serializable value)
                throws TypeMismatch,
                       InvalidValue
Inserts a reference to a Serializable object into this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Specified by:
insert_val in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

get_boolean

public boolean get_boolean()
                    throws TypeMismatch,
                           InvalidValue
Extracts the boolean value from this DynAny.

Specified by:
get_boolean in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_octet

public byte get_octet()
               throws TypeMismatch,
                      InvalidValue
Extracts the byte value from this DynAny. The IDL octet data type is mapped to the Java byte data type.

Specified by:
get_octet in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_char

public char get_char()
              throws TypeMismatch,
                     InvalidValue
Extracts the char value from this DynAny.

Specified by:
get_char in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_short

public short get_short()
                throws TypeMismatch,
                       InvalidValue
Extracts the short value from this DynAny.

Specified by:
get_short in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ushort

public short get_ushort()
                 throws TypeMismatch,
                        InvalidValue
Extracts the short value from this DynAny. The IDL ushort data type is mapped to the Java short data type.

Specified by:
get_ushort in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_long

public int get_long()
             throws TypeMismatch,
                    InvalidValue
Extracts the integer value from this DynAny. The IDL long data type is mapped to the Java int data type.

Specified by:
get_long in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulong

public int get_ulong()
              throws TypeMismatch,
                     InvalidValue
Extracts the integer value from this DynAny. The IDL ulong data type is mapped to the Java int data type.

Specified by:
get_ulong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_float

public float get_float()
                throws TypeMismatch,
                       InvalidValue
Extracts the float value from this DynAny.

Specified by:
get_float in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_double

public double get_double()
                  throws TypeMismatch,
                         InvalidValue
Extracts the double value from this DynAny.

Specified by:
get_double in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_string

public String get_string()
                  throws TypeMismatch,
                         InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Specified by:
get_string in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_reference

public Object get_reference()
                     throws TypeMismatch,
                            InvalidValue
Extracts the reference to a CORBA Object from this DynAny.

Specified by:
get_reference in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_typecode

public TypeCode get_typecode()
                      throws TypeMismatch,
                             InvalidValue
Extracts the TypeCode object from this DynAny.

Specified by:
get_typecode in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_longlong

public long get_longlong()
                  throws TypeMismatch,
                         InvalidValue
Extracts the long value from this DynAny. The IDL long long data type is mapped to the Java long data type.

Specified by:
get_longlong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulonglong

public long get_ulonglong()
                   throws TypeMismatch,
                          InvalidValue
Extracts the long value from this DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Specified by:
get_ulonglong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wchar

public char get_wchar()
               throws TypeMismatch,
                      InvalidValue
Extracts the long value from this DynAny. The IDL wchar data type is mapped to the Java char data type.

Specified by:
get_wchar in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wstring

public String get_wstring()
                   throws TypeMismatch,
                          InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Specified by:
get_wstring in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue

get_any

public Any get_any()
            throws TypeMismatch,
                   InvalidValue
Extracts an Any value contained in the Any represented by this DynAny.

Specified by:
get_any in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_dyn_any

public DynAny get_dyn_any()
                   throws TypeMismatch,
                          InvalidValue
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.

Specified by:
get_dyn_any in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_val

public Serializable get_val()
                     throws TypeMismatch,
                            InvalidValue
Extracts a Serializable object from this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Specified by:
get_val in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

seek

public boolean seek(int index)
Sets the current position to index. The current position is indexed 0 to n-1, that is, index zero corresponds to the first component. The operation returns true if the resulting current position indicates a component of the DynAny and false if index indicates a position that does not correspond to a component. Calling seek with a negative index is legal. It sets the current position to -1 to indicate no component and returns false. Passing a non-negative index value for a DynAny that does not have a component at the corresponding position sets the current position to -1 and returns false.

Specified by:
seek in interface DynAnyOperations

rewind

public void rewind()
Is equivalent to seek(0).

Specified by:
rewind in interface DynAnyOperations

next

public boolean next()
Advances the current position to the next component. The operation returns true while the resulting current position indicates a component, false otherwise. A false return value leaves the current position at -1. Invoking next on a DynAny without components leaves the current position at -1 and returns false.

Specified by:
next in interface DynAnyOperations

component_count

public int component_count()
Returns the number of components of a DynAny. For a DynAny without components, it returns zero. The operation only counts the components at the top level. For example, if component_count is invoked on a DynStruct with a single member, the return value is 1, irrespective of the type of the member.
  • For sequences, the operation returns the current number of elements.
  • For structures, exceptions, and value types, the operation returns the number of members.
  • For arrays, the operation returns the number of elements.
  • For unions, the operation returns 2 if the discriminator indicates that a named member is active, otherwise, it returns 1.
  • For DynFixed and DynEnum, the operation returns zero.

Specified by:
component_count in interface DynAnyOperations

current_component

public DynAny current_component()
                         throws TypeMismatch
Returns the DynAny for the component at the current position. It does not advance the current position, so repeated calls to current_component without an intervening call to rewind, next, or seek return the same component. The returned DynAny object reference can be used to get/set the value of the current component. If the current component represents a complex type, the returned reference can be narrowed based on the TypeCode to get the interface corresponding to the to the complex type. Calling current_component on a DynAny that cannot have components, such as a DynEnum or an empty exception, raises TypeMismatch. Calling current_component on a DynAny whose current position is -1 returns a nil reference. The iteration operations, together with current_component, can be used to dynamically compose an any value. After creating a dynamic any, such as a DynStruct, current_component and next can be used to initialize all the components of the value. Once the dynamic value is completely initialized, to_any creates the corresponding any value.

Specified by:
current_component in interface DynAnyOperations
Throws:
TypeMismatch - If called on a DynAny that cannot have components, such as a DynEnum or an empty exception

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Specified by:
_ids in class ObjectImpl
Returns:
the array of all repository identifiers supported by this ObjectImpl instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


_DynSequenceStub

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class _DynSequenceStub

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.DynamicAny._DynSequenceStub
All Implemented Interfaces:
Serializable, Object, IDLEntity, DynAny, DynAnyOperations, DynSequence, DynSequenceOperations
public class _DynSequenceStub
extends ObjectImpl
implements DynSequence

DynSequence objects support the manipulation of IDL sequences.

Field Summary
static Class _opsClass
Constructor Summary
_DynSequenceStub()
Method Summary
 String[] _ids()
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
 void assign(DynAny dyn_any)
Initializes the value associated with a DynAny object with the value associated with another DynAny object.
 int component_count()
Returns the number of components of a DynAny.
 DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
 DynAny current_component()
Returns the DynAny for the component at the current position.
 void destroy()
Destroys a DynAny object.
 boolean equal(DynAny dyn_any)
Compares two DynAny values for equality.
 void from_any(Any value)
Initializes the value associated with a DynAny object with the value contained in an any.
 Any get_any()
Extracts an Any value contained in the Any represented by this DynAny.
 boolean get_boolean()
Extracts the boolean value from this DynAny.
 char get_char()
Extracts the char value from this DynAny.
 double get_double()
Extracts the double value from this DynAny.
 DynAny get_dyn_any()
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
 DynAny[] get_elements_as_dyn_any()
Returns the DynAnys representing the elements of the sequence.
 Any[] get_elements()
Returns the elements of the sequence.
 float get_float()
Extracts the float value from this DynAny.
 int get_length()
Returns the current length of the sequence.
 int get_long()
Extracts the integer value from this DynAny.
 long get_longlong()
Extracts the long value from this DynAny.
 byte get_octet()
Extracts the byte value from this DynAny.
 Object get_reference()
Extracts the reference to a CORBA Object from this DynAny.
 short get_short()
Extracts the short value from this DynAny.
 String get_string()
Extracts the string value from this DynAny.
 TypeCode get_typecode()
Extracts the TypeCode object from this DynAny.
 int get_ulong()
Extracts the integer value from this DynAny.
 long get_ulonglong()
Extracts the long value from this DynAny.
 short get_ushort()
Extracts the short value from this DynAny.
 Serializable get_val()
Extracts a Serializable object from this DynAny.
 char get_wchar()
Extracts the long value from this DynAny.
 String get_wstring()
Extracts the string value from this DynAny.
 void insert_any(Any value)
Inserts an Any value into the Any represented by this DynAny.
 void insert_boolean(boolean value)
Inserts a boolean value into the DynAny.
 void insert_char(char value)
Inserts a char value into the DynAny.
 void insert_double(double value)
Inserts a double value into the DynAny.
 void insert_dyn_any(DynAny value)
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
 void insert_float(float value)
Inserts a float value into the DynAny.
 void insert_long(int value)
Inserts an integer value into the DynAny.
 void insert_longlong(long value)
Inserts a long value into the DynAny.
 void insert_octet(byte value)
Inserts a byte value into the DynAny.
 void insert_reference(Object value)
Inserts a reference to a CORBA object into the DynAny.
 void insert_short(short value)
Inserts a short value into the DynAny.
 void insert_string(String value)
Inserts a string value into the DynAny.
 void insert_typecode(TypeCode value)
Inserts a TypeCode object into the DynAny.
 void insert_ulong(int value)
Inserts an integer value into the DynAny.
 void insert_ulonglong(long value)
Inserts a long value into the DynAny.
 void insert_ushort(short value)
Inserts a short value into the DynAny.
 void insert_val(Serializable value)
Inserts a reference to a Serializable object into this DynAny.
 void insert_wchar(char value)
Inserts a char value into the DynAny.
 void insert_wstring(String value)
Inserts a string value into the DynAny.
 boolean next()
Advances the current position to the next component.
 void rewind()
Is equivalent to seek(0).
 boolean seek(int index)
Sets the current position to index.
 void set_elements_as_dyn_any(DynAny[] value)
Sets the elements of a sequence using DynAnys.
 void set_elements(Any[] value)
Sets the elements of a sequence.
 void set_length(int len)
Sets the length of the sequence.
 Any to_any()
Creates an any value from a DynAny object.
 TypeCode type()
Returns the TypeCode associated with this DynAny object.
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Field Detail

_opsClass

public static final Class _opsClass
Constructor Detail

_DynSequenceStub

public _DynSequenceStub()
Method Detail

get_length

public int get_length()
Returns the current length of the sequence.

Specified by:
get_length in interface DynSequenceOperations

set_length

public void set_length(int len)
                throws InvalidValue
Sets the length of the sequence. Increasing the length of a sequence adds new elements at the tail without affecting the values of already existing elements. Newly added elements are default-initialized. Increasing the length of a sequence sets the current position to the first newly-added element if the previous current position was -1. Otherwise, if the previous current position was not -1, the current position is not affected. Decreasing the length of a sequence removes elements from the tail without affecting the value of those elements that remain. The new current position after decreasing the length of a sequence is determined as follows:
  • If the length of the sequence is set to zero, the current position is set to -1.
  • If the current position is -1 before decreasing the length, it remains at -1.
  • If the current position indicates a valid element and that element is not removed when the length is decreased, the current position remains unaffected.
  • If the current position indicates a valid element and that element is removed, the current position is set to -1.

Specified by:
set_length in interface DynSequenceOperations
Throws:
InvalidValue - if this is a bounded sequence and len is larger than the bound

get_elements

public Any[] get_elements()
Returns the elements of the sequence.

Specified by:
get_elements in interface DynSequenceOperations

set_elements

public void set_elements(Any[] value)
                  throws TypeMismatch,
                         InvalidValue
Sets the elements of a sequence. The length of the DynSequence is set to the length of value. The current position is set to zero if value has non-zero length and to -1 if value is a zero-length sequence.

Specified by:
set_elements in interface DynSequenceOperations
Throws:
TypeMismatch - if value contains one or more elements whose TypeCode is not equivalent to the element TypeCode of the DynSequence
InvalidValue - if the length of value exceeds the bound of a bounded sequence

get_elements_as_dyn_any

public DynAny[] get_elements_as_dyn_any()
Returns the DynAnys representing the elements of the sequence.

Specified by:
get_elements_as_dyn_any in interface DynSequenceOperations

set_elements_as_dyn_any

public void set_elements_as_dyn_any(DynAny[] value)
                             throws TypeMismatch,
                                    InvalidValue
Sets the elements of a sequence using DynAnys. The length of the DynSequence is set to the length of value. The current position is set to zero if value has non-zero length and to -1 if value is a zero-length sequence.

Specified by:
set_elements_as_dyn_any in interface DynSequenceOperations
Throws:
TypeMismatch - if value contains one or more elements whose TypeCode is not equivalent to the element TypeCode of the DynSequence
InvalidValue - if the length of value exceeds the bound of a bounded sequence

type

public TypeCode type()
Returns the TypeCode associated with this DynAny object. A DynAny object is created with a TypeCode value assigned to it. This TypeCode value determines the type of the value handled through the DynAny object. Note that the TypeCode associated with a DynAny object is initialized at the time the DynAny is created and cannot be changed during lifetime of the DynAny object.

Specified by:
type in interface DynAnyOperations
Returns:
The TypeCode associated with this DynAny object

assign

public void assign(DynAny dyn_any)
            throws TypeMismatch
Initializes the value associated with a DynAny object with the value associated with another DynAny object. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Specified by:
assign in interface DynAnyOperations
Parameters:
dyn_any -
Throws:
TypeMismatch - if the type of the passed DynAny is not equivalent to the type of target DynAny

from_any

public void from_any(Any value)
              throws TypeMismatch,
                     InvalidValue
Initializes the value associated with a DynAny object with the value contained in an any. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Specified by:
from_any in interface DynAnyOperations
Throws:
TypeMismatch - if the type of the passed Any is not equivalent to the type of target DynAny
InvalidValue - if the passed Any does not contain a legal value (such as a null string)

to_any

public Any to_any()
Creates an any value from a DynAny object. A copy of the TypeCode associated with the DynAny object is assigned to the resulting any. The value associated with the DynAny object is copied into the any.

Specified by:
to_any in interface DynAnyOperations
Returns:
a new Any object with the same value and TypeCode

equal

public boolean equal(DynAny dyn_any)
Compares two DynAny values for equality. Two DynAny values are equal if their TypeCodes are equivalent and, recursively, all component DynAnys have equal values. The current position of the two DynAnys being compared has no effect on the result of equal.

Specified by:
equal in interface DynAnyOperations
Returns:
true of the DynAnys are equal, false otherwise

destroy

public void destroy()
Destroys a DynAny object. This operation frees any resources used to represent the data value associated with a DynAny object. It must be invoked on references obtained from one of the creation operations on the ORB interface or on a reference returned by DynAny.copy() to avoid resource leaks. Invoking destroy on component DynAny objects (for example, on objects returned by the current_component operation) does nothing. Destruction of a DynAny object implies destruction of all DynAny objects obtained from it. That is, references to components of a destroyed DynAny become invalid. Invocations on such references raise OBJECT_NOT_EXIST. It is possible to manipulate a component of a DynAny beyond the life time of the DynAny from which the component was obtained by making a copy of the component with the copy operation before destroying the DynAny from which the component was obtained.

Specified by:
destroy in interface DynAnyOperations

copy

public DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked. The operation is polymorphic, that is, invoking it on one of the types derived from DynAny, such as DynStruct, creates the derived type but returns its reference as the DynAny base type.

Specified by:
copy in interface DynAnyOperations
Returns:
a deep copy of the DynAny object

insert_boolean

public void insert_boolean(boolean value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a boolean value into the DynAny.

Specified by:
insert_boolean in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_octet

public void insert_octet(byte value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a byte value into the DynAny. The IDL octet data type is mapped to the Java byte data type.

Specified by:
insert_octet in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_char

public void insert_char(char value)
                 throws TypeMismatch,
                        InvalidValue
Inserts a char value into the DynAny.

Specified by:
insert_char in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_short

public void insert_short(short value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a short value into the DynAny.

Specified by:
insert_short in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ushort

public void insert_ushort(short value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a short value into the DynAny. The IDL ushort data type is mapped to the Java short data type.

Specified by:
insert_ushort in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_long

public void insert_long(int value)
                 throws TypeMismatch,
                        InvalidValue
Inserts an integer value into the DynAny. The IDL long data type is mapped to the Java int data type.

Specified by:
insert_long in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulong

public void insert_ulong(int value)
                  throws TypeMismatch,
                         InvalidValue
Inserts an integer value into the DynAny. The IDL ulong data type is mapped to the Java int data type.

Specified by:
insert_ulong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_float

public void insert_float(float value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a float value into the DynAny.

Specified by:
insert_float in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_double

public void insert_double(double value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a double value into the DynAny.

Specified by:
insert_double in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_string

public void insert_string(String value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Specified by:
insert_string in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch - if called on a DynAny whose current component itself has components

insert_reference

public void insert_reference(Object value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a reference to a CORBA object into the DynAny.

Specified by:
insert_reference in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_typecode

public void insert_typecode(TypeCode value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a TypeCode object into the DynAny.

Specified by:
insert_typecode in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_longlong

public void insert_longlong(long value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a long value into the DynAny. The IDL long long data type is mapped to the Java long data type.

Specified by:
insert_longlong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulonglong

public void insert_ulonglong(long value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a long value into the DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Specified by:
insert_ulonglong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wchar

public void insert_wchar(char value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a char value into the DynAny. The IDL wchar data type is mapped to the Java char data type.

Specified by:
insert_wchar in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wstring

public void insert_wstring(String value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Specified by:
insert_wstring in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch

insert_any

public void insert_any(Any value)
                throws TypeMismatch,
                       InvalidValue
Inserts an Any value into the Any represented by this DynAny.

Specified by:
insert_any in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_dyn_any

public void insert_dyn_any(DynAny value)
                    throws TypeMismatch,
                           InvalidValue
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.

Specified by:
insert_dyn_any in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_val

public void insert_val(Serializable value)
                throws TypeMismatch,
                       InvalidValue
Inserts a reference to a Serializable object into this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Specified by:
insert_val in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

get_boolean

public boolean get_boolean()
                    throws TypeMismatch,
                           InvalidValue
Extracts the boolean value from this DynAny.

Specified by:
get_boolean in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_octet

public byte get_octet()
               throws TypeMismatch,
                      InvalidValue
Extracts the byte value from this DynAny. The IDL octet data type is mapped to the Java byte data type.

Specified by:
get_octet in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_char

public char get_char()
              throws TypeMismatch,
                     InvalidValue
Extracts the char value from this DynAny.

Specified by:
get_char in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_short

public short get_short()
                throws TypeMismatch,
                       InvalidValue
Extracts the short value from this DynAny.

Specified by:
get_short in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ushort

public short get_ushort()
                 throws TypeMismatch,
                        InvalidValue
Extracts the short value from this DynAny. The IDL ushort data type is mapped to the Java short data type.

Specified by:
get_ushort in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_long

public int get_long()
             throws TypeMismatch,
                    InvalidValue
Extracts the integer value from this DynAny. The IDL long data type is mapped to the Java int data type.

Specified by:
get_long in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulong

public int get_ulong()
              throws TypeMismatch,
                     InvalidValue
Extracts the integer value from this DynAny. The IDL ulong data type is mapped to the Java int data type.

Specified by:
get_ulong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_float

public float get_float()
                throws TypeMismatch,
                       InvalidValue
Extracts the float value from this DynAny.

Specified by:
get_float in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_double

public double get_double()
                  throws TypeMismatch,
                         InvalidValue
Extracts the double value from this DynAny.

Specified by:
get_double in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_string

public String get_string()
                  throws TypeMismatch,
                         InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Specified by:
get_string in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_reference

public Object get_reference()
                     throws TypeMismatch,
                            InvalidValue
Extracts the reference to a CORBA Object from this DynAny.

Specified by:
get_reference in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_typecode

public TypeCode get_typecode()
                      throws TypeMismatch,
                             InvalidValue
Extracts the TypeCode object from this DynAny.

Specified by:
get_typecode in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_longlong

public long get_longlong()
                  throws TypeMismatch,
                         InvalidValue
Extracts the long value from this DynAny. The IDL long long data type is mapped to the Java long data type.

Specified by:
get_longlong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulonglong

public long get_ulonglong()
                   throws TypeMismatch,
                          InvalidValue
Extracts the long value from this DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Specified by:
get_ulonglong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wchar

public char get_wchar()
               throws TypeMismatch,
                      InvalidValue
Extracts the long value from this DynAny. The IDL wchar data type is mapped to the Java char data type.

Specified by:
get_wchar in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wstring

public String get_wstring()
                   throws TypeMismatch,
                          InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Specified by:
get_wstring in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue

get_any

public Any get_any()
            throws TypeMismatch,
                   InvalidValue
Extracts an Any value contained in the Any represented by this DynAny.

Specified by:
get_any in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_dyn_any

public DynAny get_dyn_any()
                   throws TypeMismatch,
                          InvalidValue
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.

Specified by:
get_dyn_any in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_val

public Serializable get_val()
                     throws TypeMismatch,
                            InvalidValue
Extracts a Serializable object from this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Specified by:
get_val in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

seek

public boolean seek(int index)
Sets the current position to index. The current position is indexed 0 to n-1, that is, index zero corresponds to the first component. The operation returns true if the resulting current position indicates a component of the DynAny and false if index indicates a position that does not correspond to a component. Calling seek with a negative index is legal. It sets the current position to -1 to indicate no component and returns false. Passing a non-negative index value for a DynAny that does not have a component at the corresponding position sets the current position to -1 and returns false.

Specified by:
seek in interface DynAnyOperations

rewind

public void rewind()
Is equivalent to seek(0).

Specified by:
rewind in interface DynAnyOperations

next

public boolean next()
Advances the current position to the next component. The operation returns true while the resulting current position indicates a component, false otherwise. A false return value leaves the current position at -1. Invoking next on a DynAny without components leaves the current position at -1 and returns false.

Specified by:
next in interface DynAnyOperations

component_count

public int component_count()
Returns the number of components of a DynAny. For a DynAny without components, it returns zero. The operation only counts the components at the top level. For example, if component_count is invoked on a DynStruct with a single member, the return value is 1, irrespective of the type of the member.
  • For sequences, the operation returns the current number of elements.
  • For structures, exceptions, and value types, the operation returns the number of members.
  • For arrays, the operation returns the number of elements.
  • For unions, the operation returns 2 if the discriminator indicates that a named member is active, otherwise, it returns 1.
  • For DynFixed and DynEnum, the operation returns zero.

Specified by:
component_count in interface DynAnyOperations

current_component

public DynAny current_component()
                         throws TypeMismatch
Returns the DynAny for the component at the current position. It does not advance the current position, so repeated calls to current_component without an intervening call to rewind, next, or seek return the same component. The returned DynAny object reference can be used to get/set the value of the current component. If the current component represents a complex type, the returned reference can be narrowed based on the TypeCode to get the interface corresponding to the to the complex type. Calling current_component on a DynAny that cannot have components, such as a DynEnum or an empty exception, raises TypeMismatch. Calling current_component on a DynAny whose current position is -1 returns a nil reference. The iteration operations, together with current_component, can be used to dynamically compose an any value. After creating a dynamic any, such as a DynStruct, current_component and next can be used to initialize all the components of the value. Once the dynamic value is completely initialized, to_any creates the corresponding any value.

Specified by:
current_component in interface DynAnyOperations
Throws:
TypeMismatch - If called on a DynAny that cannot have components, such as a DynEnum or an empty exception

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Specified by:
_ids in class ObjectImpl
Returns:
the array of all repository identifiers supported by this ObjectImpl instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


_DynUnionStub

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class _DynUnionStub

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.DynamicAny._DynUnionStub
All Implemented Interfaces:
Serializable, Object, IDLEntity, DynAny, DynAnyOperations, DynUnion, DynUnionOperations
public class _DynUnionStub
extends ObjectImpl
implements DynUnion

DynUnion objects support the manipulation of IDL unions. A union can have only two valid current positions:

  • zero, which denotes the discriminator
  • one, which denotes the active member
The component_count value for a union depends on the current discriminator: it is 2 for a union whose discriminator indicates a named member, and 1 otherwise.

Field Summary
static Class _opsClass
Constructor Summary
_DynUnionStub()
Method Summary
 String[] _ids()
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
 void assign(DynAny dyn_any)
Initializes the value associated with a DynAny object with the value associated with another DynAny object.
 int component_count()
Returns the number of components of a DynAny.
 DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
 DynAny current_component()
Returns the DynAny for the component at the current position.
 void destroy()
Destroys a DynAny object.
 TCKind discriminator_kind()
Returns the TCKind value of the discriminators TypeCode.
 boolean equal(DynAny dyn_any)
Compares two DynAny values for equality.
 void from_any(Any value)
Initializes the value associated with a DynAny object with the value contained in an any.
 Any get_any()
Extracts an Any value contained in the Any represented by this DynAny.
 boolean get_boolean()
Extracts the boolean value from this DynAny.
 char get_char()
Extracts the char value from this DynAny.
 DynAny get_discriminator()
Returns the current discriminator value.
 double get_double()
Extracts the double value from this DynAny.
 DynAny get_dyn_any()
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
 float get_float()
Extracts the float value from this DynAny.
 int get_long()
Extracts the integer value from this DynAny.
 long get_longlong()
Extracts the long value from this DynAny.
 byte get_octet()
Extracts the byte value from this DynAny.
 Object get_reference()
Extracts the reference to a CORBA Object from this DynAny.
 short get_short()
Extracts the short value from this DynAny.
 String get_string()
Extracts the string value from this DynAny.
 TypeCode get_typecode()
Extracts the TypeCode object from this DynAny.
 int get_ulong()
Extracts the integer value from this DynAny.
 long get_ulonglong()
Extracts the long value from this DynAny.
 short get_ushort()
Extracts the short value from this DynAny.
 Serializable get_val()
Extracts a Serializable object from this DynAny.
 char get_wchar()
Extracts the long value from this DynAny.
 String get_wstring()
Extracts the string value from this DynAny.
 boolean has_no_active_member()
Returns true if the union has no active member, that is, the unions value consists solely of its discriminator because the discriminator has a value that is not listed as an explicit case label.
 void insert_any(Any value)
Inserts an Any value into the Any represented by this DynAny.
 void insert_boolean(boolean value)
Inserts a boolean value into the DynAny.
 void insert_char(char value)
Inserts a char value into the DynAny.
 void insert_double(double value)
Inserts a double value into the DynAny.
 void insert_dyn_any(DynAny value)
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
 void insert_float(float value)
Inserts a float value into the DynAny.
 void insert_long(int value)
Inserts an integer value into the DynAny.
 void insert_longlong(long value)
Inserts a long value into the DynAny.
 void insert_octet(byte value)
Inserts a byte value into the DynAny.
 void insert_reference(Object value)
Inserts a reference to a CORBA object into the DynAny.
 void insert_short(short value)
Inserts a short value into the DynAny.
 void insert_string(String value)
Inserts a string value into the DynAny.
 void insert_typecode(TypeCode value)
Inserts a TypeCode object into the DynAny.
 void insert_ulong(int value)
Inserts an integer value into the DynAny.
 void insert_ulonglong(long value)
Inserts a long value into the DynAny.
 void insert_ushort(short value)
Inserts a short value into the DynAny.
 void insert_val(Serializable value)
Inserts a reference to a Serializable object into this DynAny.
 void insert_wchar(char value)
Inserts a char value into the DynAny.
 void insert_wstring(String value)
Inserts a string value into the DynAny.
 TCKind member_kind()
Returns the TCKind value of the currently active members TypeCode.
 String member_name()
Returns the name of the currently active member.
 DynAny member()
Returns the currently active member.
 boolean next()
Advances the current position to the next component.
 void rewind()
Is equivalent to seek(0).
 boolean seek(int index)
Sets the current position to index.
 void set_discriminator(DynAny d)
Sets the discriminator of the DynUnion to the specified value.
 void set_to_default_member()
Sets the discriminator to a value that is consistent with the value of the default case of a union.
 void set_to_no_active_member()
Sets the discriminator to a value that does not correspond to any of the unions case labels.
 Any to_any()
Creates an any value from a DynAny object.
 TypeCode type()
Returns the TypeCode associated with this DynAny object.
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Field Detail

_opsClass

public static final Class _opsClass
Constructor Detail

_DynUnionStub

public _DynUnionStub()
Method Detail

get_discriminator

public DynAny get_discriminator()
Returns the current discriminator value.

Specified by:
get_discriminator in interface DynUnionOperations

set_discriminator

public void set_discriminator(DynAny d)
                       throws TypeMismatch
Sets the discriminator of the DynUnion to the specified value. Setting the discriminator to a value that is consistent with the currently active union member does not affect the currently active member. Setting the discriminator to a value that is inconsistent with the currently active member deactivates the member and activates the member that is consistent with the new discriminator value (if there is a member for that value) by initializing the member to its default value. Setting the discriminator of a union sets the current position to 0 if the discriminator value indicates a non-existent union member (has_no_active_member returns true in this case). Otherwise, if the discriminator value indicates a named union member, the current position is set to 1 (has_no_active_member returns false and component_count returns 2 in this case).

Specified by:
set_discriminator in interface DynUnionOperations
Throws:
TypeMismatch - if the TypeCode of the parameter is not equivalent to the TypeCode of the union's discriminator

set_to_default_member

public void set_to_default_member()
                           throws TypeMismatch
Sets the discriminator to a value that is consistent with the value of the default case of a union. It sets the current position to zero and causes component_count to return 2.

Specified by:
set_to_default_member in interface DynUnionOperations
Throws:
TypeMismatch - if the union does not have an explicit default case

set_to_no_active_member

public void set_to_no_active_member()
                             throws TypeMismatch
Sets the discriminator to a value that does not correspond to any of the unions case labels. It sets the current position to zero and causes component_count to return 1.

Specified by:
set_to_no_active_member in interface DynUnionOperations
Throws:
TypeMismatch - if the union has an explicit default case or if it uses the entire range of discriminator values for explicit case labels

has_no_active_member

public boolean has_no_active_member()
Returns true if the union has no active member, that is, the unions value consists solely of its discriminator because the discriminator has a value that is not listed as an explicit case label. Calling this operation on a union that has a default case returns false. Calling this operation on a union that uses the entire range of discriminator values for explicit case labels returns false.

Specified by:
has_no_active_member in interface DynUnionOperations

discriminator_kind

public TCKind discriminator_kind()
Returns the TCKind value of the discriminators TypeCode.

Specified by:
discriminator_kind in interface DynUnionOperations

member_kind

public TCKind member_kind()
                   throws InvalidValue
Returns the TCKind value of the currently active members TypeCode.

Specified by:
member_kind in interface DynUnionOperations
Throws:
InvalidValue - if the union does not have a currently active member

member

public DynAny member()
              throws InvalidValue
Returns the currently active member. Note that the returned reference remains valid only for as long as the currently active member does not change. Using the returned reference beyond the life time of the currently active member raises OBJECT_NOT_EXIST.

Specified by:
member in interface DynUnionOperations
Throws:
InvalidValue - if the union has no active member

member_name

public String member_name()
                   throws InvalidValue
Returns the name of the currently active member. If the unions TypeCode does not contain a member name for the currently active member, the operation returns an empty string.

Specified by:
member_name in interface DynUnionOperations
Throws:
InvalidValue - if the union has no active member

type

public TypeCode type()
Returns the TypeCode associated with this DynAny object. A DynAny object is created with a TypeCode value assigned to it. This TypeCode value determines the type of the value handled through the DynAny object. Note that the TypeCode associated with a DynAny object is initialized at the time the DynAny is created and cannot be changed during lifetime of the DynAny object.

Specified by:
type in interface DynAnyOperations
Returns:
The TypeCode associated with this DynAny object

assign

public void assign(DynAny dyn_any)
            throws TypeMismatch
Initializes the value associated with a DynAny object with the value associated with another DynAny object. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Specified by:
assign in interface DynAnyOperations
Parameters:
dyn_any -
Throws:
TypeMismatch - if the type of the passed DynAny is not equivalent to the type of target DynAny

from_any

public void from_any(Any value)
              throws TypeMismatch,
                     InvalidValue
Initializes the value associated with a DynAny object with the value contained in an any. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Specified by:
from_any in interface DynAnyOperations
Throws:
TypeMismatch - if the type of the passed Any is not equivalent to the type of target DynAny
InvalidValue - if the passed Any does not contain a legal value (such as a null string)

to_any

public Any to_any()
Creates an any value from a DynAny object. A copy of the TypeCode associated with the DynAny object is assigned to the resulting any. The value associated with the DynAny object is copied into the any.

Specified by:
to_any in interface DynAnyOperations
Returns:
a new Any object with the same value and TypeCode

equal

public boolean equal(DynAny dyn_any)
Compares two DynAny values for equality. Two DynAny values are equal if their TypeCodes are equivalent and, recursively, all component DynAnys have equal values. The current position of the two DynAnys being compared has no effect on the result of equal.

Specified by:
equal in interface DynAnyOperations
Returns:
true of the DynAnys are equal, false otherwise

destroy

public void destroy()
Destroys a DynAny object. This operation frees any resources used to represent the data value associated with a DynAny object. It must be invoked on references obtained from one of the creation operations on the ORB interface or on a reference returned by DynAny.copy() to avoid resource leaks. Invoking destroy on component DynAny objects (for example, on objects returned by the current_component operation) does nothing. Destruction of a DynAny object implies destruction of all DynAny objects obtained from it. That is, references to components of a destroyed DynAny become invalid. Invocations on such references raise OBJECT_NOT_EXIST. It is possible to manipulate a component of a DynAny beyond the life time of the DynAny from which the component was obtained by making a copy of the component with the copy operation before destroying the DynAny from which the component was obtained.

Specified by:
destroy in interface DynAnyOperations

copy

public DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked. The operation is polymorphic, that is, invoking it on one of the types derived from DynAny, such as DynStruct, creates the derived type but returns its reference as the DynAny base type.

Specified by:
copy in interface DynAnyOperations
Returns:
a deep copy of the DynAny object

insert_boolean

public void insert_boolean(boolean value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a boolean value into the DynAny.

Specified by:
insert_boolean in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_octet

public void insert_octet(byte value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a byte value into the DynAny. The IDL octet data type is mapped to the Java byte data type.

Specified by:
insert_octet in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_char

public void insert_char(char value)
                 throws TypeMismatch,
                        InvalidValue
Inserts a char value into the DynAny.

Specified by:
insert_char in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_short

public void insert_short(short value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a short value into the DynAny.

Specified by:
insert_short in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ushort

public void insert_ushort(short value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a short value into the DynAny. The IDL ushort data type is mapped to the Java short data type.

Specified by:
insert_ushort in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_long

public void insert_long(int value)
                 throws TypeMismatch,
                        InvalidValue
Inserts an integer value into the DynAny. The IDL long data type is mapped to the Java int data type.

Specified by:
insert_long in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulong

public void insert_ulong(int value)
                  throws TypeMismatch,
                         InvalidValue
Inserts an integer value into the DynAny. The IDL ulong data type is mapped to the Java int data type.

Specified by:
insert_ulong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_float

public void insert_float(float value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a float value into the DynAny.

Specified by:
insert_float in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_double

public void insert_double(double value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a double value into the DynAny.

Specified by:
insert_double in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_string

public void insert_string(String value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Specified by:
insert_string in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch - if called on a DynAny whose current component itself has components

insert_reference

public void insert_reference(Object value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a reference to a CORBA object into the DynAny.

Specified by:
insert_reference in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_typecode

public void insert_typecode(TypeCode value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a TypeCode object into the DynAny.

Specified by:
insert_typecode in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_longlong

public void insert_longlong(long value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a long value into the DynAny. The IDL long long data type is mapped to the Java long data type.

Specified by:
insert_longlong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulonglong

public void insert_ulonglong(long value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a long value into the DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Specified by:
insert_ulonglong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wchar

public void insert_wchar(char value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a char value into the DynAny. The IDL wchar data type is mapped to the Java char data type.

Specified by:
insert_wchar in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wstring

public void insert_wstring(String value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Specified by:
insert_wstring in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch

insert_any

public void insert_any(Any value)
                throws TypeMismatch,
                       InvalidValue
Inserts an Any value into the Any represented by this DynAny.

Specified by:
insert_any in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_dyn_any

public void insert_dyn_any(DynAny value)
                    throws TypeMismatch,
                           InvalidValue
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.

Specified by:
insert_dyn_any in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_val

public void insert_val(Serializable value)
                throws TypeMismatch,
                       InvalidValue
Inserts a reference to a Serializable object into this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Specified by:
insert_val in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

get_boolean

public boolean get_boolean()
                    throws TypeMismatch,
                           InvalidValue
Extracts the boolean value from this DynAny.

Specified by:
get_boolean in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_octet

public byte get_octet()
               throws TypeMismatch,
                      InvalidValue
Extracts the byte value from this DynAny. The IDL octet data type is mapped to the Java byte data type.

Specified by:
get_octet in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_char

public char get_char()
              throws TypeMismatch,
                     InvalidValue
Extracts the char value from this DynAny.

Specified by:
get_char in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_short

public short get_short()
                throws TypeMismatch,
                       InvalidValue
Extracts the short value from this DynAny.

Specified by:
get_short in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ushort

public short get_ushort()
                 throws TypeMismatch,
                        InvalidValue
Extracts the short value from this DynAny. The IDL ushort data type is mapped to the Java short data type.

Specified by:
get_ushort in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_long

public int get_long()
             throws TypeMismatch,
                    InvalidValue
Extracts the integer value from this DynAny. The IDL long data type is mapped to the Java int data type.

Specified by:
get_long in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulong

public int get_ulong()
              throws TypeMismatch,
                     InvalidValue
Extracts the integer value from this DynAny. The IDL ulong data type is mapped to the Java int data type.

Specified by:
get_ulong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_float

public float get_float()
                throws TypeMismatch,
                       InvalidValue
Extracts the float value from this DynAny.

Specified by:
get_float in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_double

public double get_double()
                  throws TypeMismatch,
                         InvalidValue
Extracts the double value from this DynAny.

Specified by:
get_double in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_string

public String get_string()
                  throws TypeMismatch,
                         InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Specified by:
get_string in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_reference

public Object get_reference()
                     throws TypeMismatch,
                            InvalidValue
Extracts the reference to a CORBA Object from this DynAny.

Specified by:
get_reference in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_typecode

public TypeCode get_typecode()
                      throws TypeMismatch,
                             InvalidValue
Extracts the TypeCode object from this DynAny.

Specified by:
get_typecode in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_longlong

public long get_longlong()
                  throws TypeMismatch,
                         InvalidValue
Extracts the long value from this DynAny. The IDL long long data type is mapped to the Java long data type.

Specified by:
get_longlong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulonglong

public long get_ulonglong()
                   throws TypeMismatch,
                          InvalidValue
Extracts the long value from this DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Specified by:
get_ulonglong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wchar

public char get_wchar()
               throws TypeMismatch,
                      InvalidValue
Extracts the long value from this DynAny. The IDL wchar data type is mapped to the Java char data type.

Specified by:
get_wchar in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wstring

public String get_wstring()
                   throws TypeMismatch,
                          InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Specified by:
get_wstring in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue

get_any

public Any get_any()
            throws TypeMismatch,
                   InvalidValue
Extracts an Any value contained in the Any represented by this DynAny.

Specified by:
get_any in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_dyn_any

public DynAny get_dyn_any()
                   throws TypeMismatch,
                          InvalidValue
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.

Specified by:
get_dyn_any in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_val

public Serializable get_val()
                     throws TypeMismatch,
                            InvalidValue
Extracts a Serializable object from this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Specified by:
get_val in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

seek

public boolean seek(int index)
Sets the current position to index. The current position is indexed 0 to n-1, that is, index zero corresponds to the first component. The operation returns true if the resulting current position indicates a component of the DynAny and false if index indicates a position that does not correspond to a component. Calling seek with a negative index is legal. It sets the current position to -1 to indicate no component and returns false. Passing a non-negative index value for a DynAny that does not have a component at the corresponding position sets the current position to -1 and returns false.

Specified by:
seek in interface DynAnyOperations

rewind

public void rewind()
Is equivalent to seek(0).

Specified by:
rewind in interface DynAnyOperations

next

public boolean next()
Advances the current position to the next component. The operation returns true while the resulting current position indicates a component, false otherwise. A false return value leaves the current position at -1. Invoking next on a DynAny without components leaves the current position at -1 and returns false.

Specified by:
next in interface DynAnyOperations

component_count

public int component_count()
Returns the number of components of a DynAny. For a DynAny without components, it returns zero. The operation only counts the components at the top level. For example, if component_count is invoked on a DynStruct with a single member, the return value is 1, irrespective of the type of the member.
  • For sequences, the operation returns the current number of elements.
  • For structures, exceptions, and value types, the operation returns the number of members.
  • For arrays, the operation returns the number of elements.
  • For unions, the operation returns 2 if the discriminator indicates that a named member is active, otherwise, it returns 1.
  • For DynFixed and DynEnum, the operation returns zero.

Specified by:
component_count in interface DynAnyOperations

current_component

public DynAny current_component()
                         throws TypeMismatch
Returns the DynAny for the component at the current position. It does not advance the current position, so repeated calls to current_component without an intervening call to rewind, next, or seek return the same component. The returned DynAny object reference can be used to get/set the value of the current component. If the current component represents a complex type, the returned reference can be narrowed based on the TypeCode to get the interface corresponding to the to the complex type. Calling current_component on a DynAny that cannot have components, such as a DynEnum or an empty exception, raises TypeMismatch. Calling current_component on a DynAny whose current position is -1 returns a nil reference. The iteration operations, together with current_component, can be used to dynamically compose an any value. After creating a dynamic any, such as a DynStruct, current_component and next can be used to initialize all the components of the value. Once the dynamic value is completely initialized, to_any creates the corresponding any value.

Specified by:
current_component in interface DynAnyOperations
Throws:
TypeMismatch - If called on a DynAny that cannot have components, such as a DynEnum or an empty exception

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Specified by:
_ids in class ObjectImpl
Returns:
the array of all repository identifiers supported by this ObjectImpl instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


_DynStructStub

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class _DynStructStub

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.DynamicAny._DynStructStub
All Implemented Interfaces:
Serializable, Object, IDLEntity, DynAny, DynAnyOperations, DynStruct, DynStructOperations
public class _DynStructStub
extends ObjectImpl
implements DynStruct

DynStruct objects support the manipulation of IDL struct and exception values. Members of the exceptions are handled in the same way as members of a struct.

Field Summary
static Class _opsClass
Constructor Summary
_DynStructStub()
Method Summary
 String[] _ids()
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
 void assign(DynAny dyn_any)
Initializes the value associated with a DynAny object with the value associated with another DynAny object.
 int component_count()
Returns the number of components of a DynAny.
 DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
 DynAny current_component()
Returns the DynAny for the component at the current position.
 TCKind current_member_kind()
Returns the TCKind associated with the member at the current position.
 String current_member_name()
Returns the name of the member at the current position.
 void destroy()
Destroys a DynAny object.
 boolean equal(DynAny dyn_any)
Compares two DynAny values for equality.
 void from_any(Any value)
Initializes the value associated with a DynAny object with the value contained in an any.
 Any get_any()
Extracts an Any value contained in the Any represented by this DynAny.
 boolean get_boolean()
Extracts the boolean value from this DynAny.
 char get_char()
Extracts the char value from this DynAny.
 double get_double()
Extracts the double value from this DynAny.
 DynAny get_dyn_any()
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
 float get_float()
Extracts the float value from this DynAny.
 int get_long()
Extracts the integer value from this DynAny.
 long get_longlong()
Extracts the long value from this DynAny.
 NameDynAnyPair[] get_members_as_dyn_any()
Returns a sequence of NameDynAnyPairs describing the name and the value of each member in the struct associated with a DynStruct object.
 NameValuePair[] get_members()
Returns a sequence of NameValuePairs describing the name and the value of each member in the struct associated with a DynStruct object.
 byte get_octet()
Extracts the byte value from this DynAny.
 Object get_reference()
Extracts the reference to a CORBA Object from this DynAny.
 short get_short()
Extracts the short value from this DynAny.
 String get_string()
Extracts the string value from this DynAny.
 TypeCode get_typecode()
Extracts the TypeCode object from this DynAny.
 int get_ulong()
Extracts the integer value from this DynAny.
 long get_ulonglong()
Extracts the long value from this DynAny.
 short get_ushort()
Extracts the short value from this DynAny.
 Serializable get_val()
Extracts a Serializable object from this DynAny.
 char get_wchar()
Extracts the long value from this DynAny.
 String get_wstring()
Extracts the string value from this DynAny.
 void insert_any(Any value)
Inserts an Any value into the Any represented by this DynAny.
 void insert_boolean(boolean value)
Inserts a boolean value into the DynAny.
 void insert_char(char value)
Inserts a char value into the DynAny.
 void insert_double(double value)
Inserts a double value into the DynAny.
 void insert_dyn_any(DynAny value)
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
 void insert_float(float value)
Inserts a float value into the DynAny.
 void insert_long(int value)
Inserts an integer value into the DynAny.
 void insert_longlong(long value)
Inserts a long value into the DynAny.
 void insert_octet(byte value)
Inserts a byte value into the DynAny.
 void insert_reference(Object value)
Inserts a reference to a CORBA object into the DynAny.
 void insert_short(short value)
Inserts a short value into the DynAny.
 void insert_string(String value)
Inserts a string value into the DynAny.
 void insert_typecode(TypeCode value)
Inserts a TypeCode object into the DynAny.
 void insert_ulong(int value)
Inserts an integer value into the DynAny.
 void insert_ulonglong(long value)
Inserts a long value into the DynAny.
 void insert_ushort(short value)
Inserts a short value into the DynAny.
 void insert_val(Serializable value)
Inserts a reference to a Serializable object into this DynAny.
 void insert_wchar(char value)
Inserts a char value into the DynAny.
 void insert_wstring(String value)
Inserts a string value into the DynAny.
 boolean next()
Advances the current position to the next component.
 void rewind()
Is equivalent to seek(0).
 boolean seek(int index)
Sets the current position to index.
 void set_members_as_dyn_any(NameDynAnyPair[] value)
Initializes the struct data value associated with a DynStruct object from a sequence of NameDynAnyPairs.
 void set_members(NameValuePair[] value)
Initializes the struct data value associated with a DynStruct object from a sequence of NameValuePairs.
 Any to_any()
Creates an any value from a DynAny object.
 TypeCode type()
Returns the TypeCode associated with this DynAny object.
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Field Detail

_opsClass

public static final Class _opsClass
Constructor Detail

_DynStructStub

public _DynStructStub()
Method Detail

current_member_name

public String current_member_name()
                           throws TypeMismatch,
                                  InvalidValue
Returns the name of the member at the current position. This operation may return an empty string since the TypeCode of the value being manipulated may not contain the names of members.

Specified by:
current_member_name in interface DynStructOperations
Throws:
TypeMismatch - if the DynStruct represents an empty exception.
InvalidValue - if the current position does not indicate a member

current_member_kind

public TCKind current_member_kind()
                           throws TypeMismatch,
                                  InvalidValue
Returns the TCKind associated with the member at the current position.

Specified by:
current_member_kind in interface DynStructOperations
Throws:
TypeMismatch - if the DynStruct represents an empty exception.
InvalidValue - if the current position does not indicate a member

get_members

public NameValuePair[] get_members()
Returns a sequence of NameValuePairs describing the name and the value of each member in the struct associated with a DynStruct object. The sequence contains members in the same order as the declaration order of members as indicated by the DynStruct's TypeCode. The current position is not affected. The member names in the returned sequence will be empty strings if the DynStruct's TypeCode does not contain member names.

Specified by:
get_members in interface DynStructOperations

set_members

public void set_members(NameValuePair[] value)
                 throws TypeMismatch,
                        InvalidValue
Initializes the struct data value associated with a DynStruct object from a sequence of NameValuePairs. The operation sets the current position to zero if the passed sequences has non-zero length. Otherwise, if an empty sequence is passed, the current position is set to -1.

Members must appear in the NameValuePairs in the order in which they appear in the IDL specification of the struct as indicated by the DynStruct's TypeCode or they must be empty strings. The operation makes no attempt to assign member values based on member names.

Specified by:
set_members in interface DynStructOperations
Throws:
TypeMismatch - if the member names supplied in the passed sequence do not match the corresponding member name in the DynStruct's TypeCode and they are not empty strings
InvalidValue - if the passed sequence has a number of elements that disagrees with the number of members as indicated by the DynStruct's TypeCode

get_members_as_dyn_any

public NameDynAnyPair[] get_members_as_dyn_any()
Returns a sequence of NameDynAnyPairs describing the name and the value of each member in the struct associated with a DynStruct object. The sequence contains members in the same order as the declaration order of members as indicated by the DynStruct's TypeCode. The current position is not affected. The member names in the returned sequence will be empty strings if the DynStruct's TypeCode does not contain member names.

Specified by:
get_members_as_dyn_any in interface DynStructOperations

set_members_as_dyn_any

public void set_members_as_dyn_any(NameDynAnyPair[] value)
                            throws TypeMismatch,
                                   InvalidValue
Initializes the struct data value associated with a DynStruct object from a sequence of NameDynAnyPairs. The operation sets the current position to zero if the passed sequences has non-zero length. Otherwise, if an empty sequence is passed, the current position is set to -1.

Members must appear in the NameDynAnyPairs in the order in which they appear in the IDL specification of the struct as indicated by the DynStruct's TypeCode or they must be empty strings. The operation makes no attempt to assign member values based on member names.

Specified by:
set_members_as_dyn_any in interface DynStructOperations
Throws:
TypeMismatch - if the member names supplied in the passed sequence do not match the corresponding member name in the DynStruct's TypeCode and they are not empty strings
InvalidValue - if the passed sequence has a number of elements that disagrees with the number of members as indicated by the DynStruct's TypeCode

type

public TypeCode type()
Returns the TypeCode associated with this DynAny object. A DynAny object is created with a TypeCode value assigned to it. This TypeCode value determines the type of the value handled through the DynAny object. Note that the TypeCode associated with a DynAny object is initialized at the time the DynAny is created and cannot be changed during lifetime of the DynAny object.

Specified by:
type in interface DynAnyOperations
Returns:
The TypeCode associated with this DynAny object

assign

public void assign(DynAny dyn_any)
            throws TypeMismatch
Initializes the value associated with a DynAny object with the value associated with another DynAny object. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Specified by:
assign in interface DynAnyOperations
Parameters:
dyn_any -
Throws:
TypeMismatch - if the type of the passed DynAny is not equivalent to the type of target DynAny

from_any

public void from_any(Any value)
              throws TypeMismatch,
                     InvalidValue
Initializes the value associated with a DynAny object with the value contained in an any. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Specified by:
from_any in interface DynAnyOperations
Throws:
TypeMismatch - if the type of the passed Any is not equivalent to the type of target DynAny
InvalidValue - if the passed Any does not contain a legal value (such as a null string)

to_any

public Any to_any()
Creates an any value from a DynAny object. A copy of the TypeCode associated with the DynAny object is assigned to the resulting any. The value associated with the DynAny object is copied into the any.

Specified by:
to_any in interface DynAnyOperations
Returns:
a new Any object with the same value and TypeCode

equal

public boolean equal(DynAny dyn_any)
Compares two DynAny values for equality. Two DynAny values are equal if their TypeCodes are equivalent and, recursively, all component DynAnys have equal values. The current position of the two DynAnys being compared has no effect on the result of equal.

Specified by:
equal in interface DynAnyOperations
Returns:
true of the DynAnys are equal, false otherwise

destroy

public void destroy()
Destroys a DynAny object. This operation frees any resources used to represent the data value associated with a DynAny object. It must be invoked on references obtained from one of the creation operations on the ORB interface or on a reference returned by DynAny.copy() to avoid resource leaks. Invoking destroy on component DynAny objects (for example, on objects returned by the current_component operation) does nothing. Destruction of a DynAny object implies destruction of all DynAny objects obtained from it. That is, references to components of a destroyed DynAny become invalid. Invocations on such references raise OBJECT_NOT_EXIST. It is possible to manipulate a component of a DynAny beyond the life time of the DynAny from which the component was obtained by making a copy of the component with the copy operation before destroying the DynAny from which the component was obtained.

Specified by:
destroy in interface DynAnyOperations

copy

public DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked. The operation is polymorphic, that is, invoking it on one of the types derived from DynAny, such as DynStruct, creates the derived type but returns its reference as the DynAny base type.

Specified by:
copy in interface DynAnyOperations
Returns:
a deep copy of the DynAny object

insert_boolean

public void insert_boolean(boolean value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a boolean value into the DynAny.

Specified by:
insert_boolean in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_octet

public void insert_octet(byte value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a byte value into the DynAny. The IDL octet data type is mapped to the Java byte data type.

Specified by:
insert_octet in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_char

public void insert_char(char value)
                 throws TypeMismatch,
                        InvalidValue
Inserts a char value into the DynAny.

Specified by:
insert_char in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_short

public void insert_short(short value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a short value into the DynAny.

Specified by:
insert_short in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ushort

public void insert_ushort(short value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a short value into the DynAny. The IDL ushort data type is mapped to the Java short data type.

Specified by:
insert_ushort in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_long

public void insert_long(int value)
                 throws TypeMismatch,
                        InvalidValue
Inserts an integer value into the DynAny. The IDL long data type is mapped to the Java int data type.

Specified by:
insert_long in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulong

public void insert_ulong(int value)
                  throws TypeMismatch,
                         InvalidValue
Inserts an integer value into the DynAny. The IDL ulong data type is mapped to the Java int data type.

Specified by:
insert_ulong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_float

public void insert_float(float value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a float value into the DynAny.

Specified by:
insert_float in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_double

public void insert_double(double value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a double value into the DynAny.

Specified by:
insert_double in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_string

public void insert_string(String value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Specified by:
insert_string in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch - if called on a DynAny whose current component itself has components

insert_reference

public void insert_reference(Object value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a reference to a CORBA object into the DynAny.

Specified by:
insert_reference in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_typecode

public void insert_typecode(TypeCode value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a TypeCode object into the DynAny.

Specified by:
insert_typecode in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_longlong

public void insert_longlong(long value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a long value into the DynAny. The IDL long long data type is mapped to the Java long data type.

Specified by:
insert_longlong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulonglong

public void insert_ulonglong(long value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a long value into the DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Specified by:
insert_ulonglong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wchar

public void insert_wchar(char value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a char value into the DynAny. The IDL wchar data type is mapped to the Java char data type.

Specified by:
insert_wchar in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wstring

public void insert_wstring(String value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Specified by:
insert_wstring in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch

insert_any

public void insert_any(Any value)
                throws TypeMismatch,
                       InvalidValue
Inserts an Any value into the Any represented by this DynAny.

Specified by:
insert_any in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_dyn_any

public void insert_dyn_any(DynAny value)
                    throws TypeMismatch,
                           InvalidValue
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.

Specified by:
insert_dyn_any in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_val

public void insert_val(Serializable value)
                throws TypeMismatch,
                       InvalidValue
Inserts a reference to a Serializable object into this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Specified by:
insert_val in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

get_boolean

public boolean get_boolean()
                    throws TypeMismatch,
                           InvalidValue
Extracts the boolean value from this DynAny.

Specified by:
get_boolean in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_octet

public byte get_octet()
               throws TypeMismatch,
                      InvalidValue
Extracts the byte value from this DynAny. The IDL octet data type is mapped to the Java byte data type.

Specified by:
get_octet in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_char

public char get_char()
              throws TypeMismatch,
                     InvalidValue
Extracts the char value from this DynAny.

Specified by:
get_char in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_short

public short get_short()
                throws TypeMismatch,
                       InvalidValue
Extracts the short value from this DynAny.

Specified by:
get_short in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ushort

public short get_ushort()
                 throws TypeMismatch,
                        InvalidValue
Extracts the short value from this DynAny. The IDL ushort data type is mapped to the Java short data type.

Specified by:
get_ushort in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_long

public int get_long()
             throws TypeMismatch,
                    InvalidValue
Extracts the integer value from this DynAny. The IDL long data type is mapped to the Java int data type.

Specified by:
get_long in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulong

public int get_ulong()
              throws TypeMismatch,
                     InvalidValue
Extracts the integer value from this DynAny. The IDL ulong data type is mapped to the Java int data type.

Specified by:
get_ulong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_float

public float get_float()
                throws TypeMismatch,
                       InvalidValue
Extracts the float value from this DynAny.

Specified by:
get_float in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_double

public double get_double()
                  throws TypeMismatch,
                         InvalidValue
Extracts the double value from this DynAny.

Specified by:
get_double in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_string

public String get_string()
                  throws TypeMismatch,
                         InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Specified by:
get_string in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_reference

public Object get_reference()
                     throws TypeMismatch,
                            InvalidValue
Extracts the reference to a CORBA Object from this DynAny.

Specified by:
get_reference in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_typecode

public TypeCode get_typecode()
                      throws TypeMismatch,
                             InvalidValue
Extracts the TypeCode object from this DynAny.

Specified by:
get_typecode in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_longlong

public long get_longlong()
                  throws TypeMismatch,
                         InvalidValue
Extracts the long value from this DynAny. The IDL long long data type is mapped to the Java long data type.

Specified by:
get_longlong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulonglong

public long get_ulonglong()
                   throws TypeMismatch,
                          InvalidValue
Extracts the long value from this DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Specified by:
get_ulonglong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wchar

public char get_wchar()
               throws TypeMismatch,
                      InvalidValue
Extracts the long value from this DynAny. The IDL wchar data type is mapped to the Java char data type.

Specified by:
get_wchar in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wstring

public String get_wstring()
                   throws TypeMismatch,
                          InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Specified by:
get_wstring in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue

get_any

public Any get_any()
            throws TypeMismatch,
                   InvalidValue
Extracts an Any value contained in the Any represented by this DynAny.

Specified by:
get_any in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_dyn_any

public DynAny get_dyn_any()
                   throws TypeMismatch,
                          InvalidValue
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.

Specified by:
get_dyn_any in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_val

public Serializable get_val()
                     throws TypeMismatch,
                            InvalidValue
Extracts a Serializable object from this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Specified by:
get_val in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

seek

public boolean seek(int index)
Sets the current position to index. The current position is indexed 0 to n-1, that is, index zero corresponds to the first component. The operation returns true if the resulting current position indicates a component of the DynAny and false if index indicates a position that does not correspond to a component. Calling seek with a negative index is legal. It sets the current position to -1 to indicate no component and returns false. Passing a non-negative index value for a DynAny that does not have a component at the corresponding position sets the current position to -1 and returns false.

Specified by:
seek in interface DynAnyOperations

rewind

public void rewind()
Is equivalent to seek(0).

Specified by:
rewind in interface DynAnyOperations

next

public boolean next()
Advances the current position to the next component. The operation returns true while the resulting current position indicates a component, false otherwise. A false return value leaves the current position at -1. Invoking next on a DynAny without components leaves the current position at -1 and returns false.

Specified by:
next in interface DynAnyOperations

component_count

public int component_count()
Returns the number of components of a DynAny. For a DynAny without components, it returns zero. The operation only counts the components at the top level. For example, if component_count is invoked on a DynStruct with a single member, the return value is 1, irrespective of the type of the member.
  • For sequences, the operation returns the current number of elements.
  • For structures, exceptions, and value types, the operation returns the number of members.
  • For arrays, the operation returns the number of elements.
  • For unions, the operation returns 2 if the discriminator indicates that a named member is active, otherwise, it returns 1.
  • For DynFixed and DynEnum, the operation returns zero.

Specified by:
component_count in interface DynAnyOperations

current_component

public DynAny current_component()
                         throws TypeMismatch
Returns the DynAny for the component at the current position. It does not advance the current position, so repeated calls to current_component without an intervening call to rewind, next, or seek return the same component. The returned DynAny object reference can be used to get/set the value of the current component. If the current component represents a complex type, the returned reference can be narrowed based on the TypeCode to get the interface corresponding to the to the complex type. Calling current_component on a DynAny that cannot have components, such as a DynEnum or an empty exception, raises TypeMismatch. Calling current_component on a DynAny whose current position is -1 returns a nil reference. The iteration operations, together with current_component, can be used to dynamically compose an any value. After creating a dynamic any, such as a DynStruct, current_component and next can be used to initialize all the components of the value. Once the dynamic value is completely initialized, to_any creates the corresponding any value.

Specified by:
current_component in interface DynAnyOperations
Throws:
TypeMismatch - If called on a DynAny that cannot have components, such as a DynEnum or an empty exception

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Specified by:
_ids in class ObjectImpl
Returns:
the array of all repository identifiers supported by this ObjectImpl instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


_DynArrayStub

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class _DynArrayStub

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.DynamicAny._DynArrayStub
All Implemented Interfaces:
Serializable, Object, IDLEntity, DynAny, DynAnyOperations, DynArray, DynArrayOperations
public class _DynArrayStub
extends ObjectImpl
implements DynArray

DynArray objects support the manipulation of IDL arrays. Note that the dimension of the array is contained in the TypeCode which is accessible through the type attribute. It can also be obtained by calling the component_count operation.

Field Summary
static Class _opsClass
Constructor Summary
_DynArrayStub()
Method Summary
 String[] _ids()
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
 void assign(DynAny dyn_any)
Initializes the value associated with a DynAny object with the value associated with another DynAny object.
 int component_count()
Returns the number of components of a DynAny.
 DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
 DynAny current_component()
Returns the DynAny for the component at the current position.
 void destroy()
Destroys a DynAny object.
 boolean equal(DynAny dyn_any)
Compares two DynAny values for equality.
 void from_any(Any value)
Initializes the value associated with a DynAny object with the value contained in an any.
 Any get_any()
Extracts an Any value contained in the Any represented by this DynAny.
 boolean get_boolean()
Extracts the boolean value from this DynAny.
 char get_char()
Extracts the char value from this DynAny.
 double get_double()
Extracts the double value from this DynAny.
 DynAny get_dyn_any()
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
 DynAny[] get_elements_as_dyn_any()
Returns the elements of the DynArray as DynAnys.
 Any[] get_elements()
Returns the elements of the DynArray.
 float get_float()
Extracts the float value from this DynAny.
 int get_long()
Extracts the integer value from this DynAny.
 long get_longlong()
Extracts the long value from this DynAny.
 byte get_octet()
Extracts the byte value from this DynAny.
 Object get_reference()
Extracts the reference to a CORBA Object from this DynAny.
 short get_short()
Extracts the short value from this DynAny.
 String get_string()
Extracts the string value from this DynAny.
 TypeCode get_typecode()
Extracts the TypeCode object from this DynAny.
 int get_ulong()
Extracts the integer value from this DynAny.
 long get_ulonglong()
Extracts the long value from this DynAny.
 short get_ushort()
Extracts the short value from this DynAny.
 Serializable get_val()
Extracts a Serializable object from this DynAny.
 char get_wchar()
Extracts the long value from this DynAny.
 String get_wstring()
Extracts the string value from this DynAny.
 void insert_any(Any value)
Inserts an Any value into the Any represented by this DynAny.
 void insert_boolean(boolean value)
Inserts a boolean value into the DynAny.
 void insert_char(char value)
Inserts a char value into the DynAny.
 void insert_double(double value)
Inserts a double value into the DynAny.
 void insert_dyn_any(DynAny value)
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
 void insert_float(float value)
Inserts a float value into the DynAny.
 void insert_long(int value)
Inserts an integer value into the DynAny.
 void insert_longlong(long value)
Inserts a long value into the DynAny.
 void insert_octet(byte value)
Inserts a byte value into the DynAny.
 void insert_reference(Object value)
Inserts a reference to a CORBA object into the DynAny.
 void insert_short(short value)
Inserts a short value into the DynAny.
 void insert_string(String value)
Inserts a string value into the DynAny.
 void insert_typecode(TypeCode value)
Inserts a TypeCode object into the DynAny.
 void insert_ulong(int value)
Inserts an integer value into the DynAny.
 void insert_ulonglong(long value)
Inserts a long value into the DynAny.
 void insert_ushort(short value)
Inserts a short value into the DynAny.
 void insert_val(Serializable value)
Inserts a reference to a Serializable object into this DynAny.
 void insert_wchar(char value)
Inserts a char value into the DynAny.
 void insert_wstring(String value)
Inserts a string value into the DynAny.
 boolean next()
Advances the current position to the next component.
 void rewind()
Is equivalent to seek(0).
 boolean seek(int index)
Sets the current position to index.
 void set_elements_as_dyn_any(DynAny[] value)
Sets the DynArray to contain the passed elements.
 void set_elements(Any[] value)
Sets the DynArray to contain the passed elements.
 Any to_any()
Creates an any value from a DynAny object.
 TypeCode type()
Returns the TypeCode associated with this DynAny object.
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Field Detail

_opsClass

public static final Class _opsClass
Constructor Detail

_DynArrayStub

public _DynArrayStub()
Method Detail

get_elements

public Any[] get_elements()
Returns the elements of the DynArray.

Specified by:
get_elements in interface DynArrayOperations

set_elements

public void set_elements(Any[] value)
                  throws TypeMismatch,
                         InvalidValue
Sets the DynArray to contain the passed elements.

Specified by:
set_elements in interface DynArrayOperations
Throws:
TypeMismatch - if one or more elements have a type that is inconsistent with the DynArrays TypeCode
InvalidValue - if the sequence does not contain the same number of elements as the array dimension

get_elements_as_dyn_any

public DynAny[] get_elements_as_dyn_any()
Returns the elements of the DynArray as DynAnys.

Specified by:
get_elements_as_dyn_any in interface DynArrayOperations

set_elements_as_dyn_any

public void set_elements_as_dyn_any(DynAny[] value)
                             throws TypeMismatch,
                                    InvalidValue
Sets the DynArray to contain the passed elements.

Specified by:
set_elements_as_dyn_any in interface DynArrayOperations
Throws:
TypeMismatch - if one or more elements have a type that is inconsistent with the DynArrays TypeCode
InvalidValue - if the sequence does not contain the same number of elements as the array dimension

type

public TypeCode type()
Returns the TypeCode associated with this DynAny object. A DynAny object is created with a TypeCode value assigned to it. This TypeCode value determines the type of the value handled through the DynAny object. Note that the TypeCode associated with a DynAny object is initialized at the time the DynAny is created and cannot be changed during lifetime of the DynAny object.

Specified by:
type in interface DynAnyOperations
Returns:
The TypeCode associated with this DynAny object

assign

public void assign(DynAny dyn_any)
            throws TypeMismatch
Initializes the value associated with a DynAny object with the value associated with another DynAny object. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Specified by:
assign in interface DynAnyOperations
Parameters:
dyn_any -
Throws:
TypeMismatch - if the type of the passed DynAny is not equivalent to the type of target DynAny

from_any

public void from_any(Any value)
              throws TypeMismatch,
                     InvalidValue
Initializes the value associated with a DynAny object with the value contained in an any. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Specified by:
from_any in interface DynAnyOperations
Throws:
TypeMismatch - if the type of the passed Any is not equivalent to the type of target DynAny
InvalidValue - if the passed Any does not contain a legal value (such as a null string)

to_any

public Any to_any()
Creates an any value from a DynAny object. A copy of the TypeCode associated with the DynAny object is assigned to the resulting any. The value associated with the DynAny object is copied into the any.

Specified by:
to_any in interface DynAnyOperations
Returns:
a new Any object with the same value and TypeCode

equal

public boolean equal(DynAny dyn_any)
Compares two DynAny values for equality. Two DynAny values are equal if their TypeCodes are equivalent and, recursively, all component DynAnys have equal values. The current position of the two DynAnys being compared has no effect on the result of equal.

Specified by:
equal in interface DynAnyOperations
Returns:
true of the DynAnys are equal, false otherwise

destroy

public void destroy()
Destroys a DynAny object. This operation frees any resources used to represent the data value associated with a DynAny object. It must be invoked on references obtained from one of the creation operations on the ORB interface or on a reference returned by DynAny.copy() to avoid resource leaks. Invoking destroy on component DynAny objects (for example, on objects returned by the current_component operation) does nothing. Destruction of a DynAny object implies destruction of all DynAny objects obtained from it. That is, references to components of a destroyed DynAny become invalid. Invocations on such references raise OBJECT_NOT_EXIST. It is possible to manipulate a component of a DynAny beyond the life time of the DynAny from which the component was obtained by making a copy of the component with the copy operation before destroying the DynAny from which the component was obtained.

Specified by:
destroy in interface DynAnyOperations

copy

public DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked. The operation is polymorphic, that is, invoking it on one of the types derived from DynAny, such as DynStruct, creates the derived type but returns its reference as the DynAny base type.

Specified by:
copy in interface DynAnyOperations
Returns:
a deep copy of the DynAny object

insert_boolean

public void insert_boolean(boolean value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a boolean value into the DynAny.

Specified by:
insert_boolean in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_octet

public void insert_octet(byte value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a byte value into the DynAny. The IDL octet data type is mapped to the Java byte data type.

Specified by:
insert_octet in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_char

public void insert_char(char value)
                 throws TypeMismatch,
                        InvalidValue
Inserts a char value into the DynAny.

Specified by:
insert_char in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_short

public void insert_short(short value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a short value into the DynAny.

Specified by:
insert_short in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ushort

public void insert_ushort(short value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a short value into the DynAny. The IDL ushort data type is mapped to the Java short data type.

Specified by:
insert_ushort in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_long

public void insert_long(int value)
                 throws TypeMismatch,
                        InvalidValue
Inserts an integer value into the DynAny. The IDL long data type is mapped to the Java int data type.

Specified by:
insert_long in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulong

public void insert_ulong(int value)
                  throws TypeMismatch,
                         InvalidValue
Inserts an integer value into the DynAny. The IDL ulong data type is mapped to the Java int data type.

Specified by:
insert_ulong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_float

public void insert_float(float value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a float value into the DynAny.

Specified by:
insert_float in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_double

public void insert_double(double value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a double value into the DynAny.

Specified by:
insert_double in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_string

public void insert_string(String value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Specified by:
insert_string in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch - if called on a DynAny whose current component itself has components

insert_reference

public void insert_reference(Object value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a reference to a CORBA object into the DynAny.

Specified by:
insert_reference in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_typecode

public void insert_typecode(TypeCode value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a TypeCode object into the DynAny.

Specified by:
insert_typecode in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_longlong

public void insert_longlong(long value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a long value into the DynAny. The IDL long long data type is mapped to the Java long data type.

Specified by:
insert_longlong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulonglong

public void insert_ulonglong(long value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a long value into the DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Specified by:
insert_ulonglong in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wchar

public void insert_wchar(char value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a char value into the DynAny. The IDL wchar data type is mapped to the Java char data type.

Specified by:
insert_wchar in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wstring

public void insert_wstring(String value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Specified by:
insert_wstring in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch

insert_any

public void insert_any(Any value)
                throws TypeMismatch,
                       InvalidValue
Inserts an Any value into the Any represented by this DynAny.

Specified by:
insert_any in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_dyn_any

public void insert_dyn_any(DynAny value)
                    throws TypeMismatch,
                           InvalidValue
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.

Specified by:
insert_dyn_any in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_val

public void insert_val(Serializable value)
                throws TypeMismatch,
                       InvalidValue
Inserts a reference to a Serializable object into this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Specified by:
insert_val in interface DynAnyOperations
Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

get_boolean

public boolean get_boolean()
                    throws TypeMismatch,
                           InvalidValue
Extracts the boolean value from this DynAny.

Specified by:
get_boolean in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_octet

public byte get_octet()
               throws TypeMismatch,
                      InvalidValue
Extracts the byte value from this DynAny. The IDL octet data type is mapped to the Java byte data type.

Specified by:
get_octet in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_char

public char get_char()
              throws TypeMismatch,
                     InvalidValue
Extracts the char value from this DynAny.

Specified by:
get_char in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_short

public short get_short()
                throws TypeMismatch,
                       InvalidValue
Extracts the short value from this DynAny.

Specified by:
get_short in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ushort

public short get_ushort()
                 throws TypeMismatch,
                        InvalidValue
Extracts the short value from this DynAny. The IDL ushort data type is mapped to the Java short data type.

Specified by:
get_ushort in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_long

public int get_long()
             throws TypeMismatch,
                    InvalidValue
Extracts the integer value from this DynAny. The IDL long data type is mapped to the Java int data type.

Specified by:
get_long in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulong

public int get_ulong()
              throws TypeMismatch,
                     InvalidValue
Extracts the integer value from this DynAny. The IDL ulong data type is mapped to the Java int data type.

Specified by:
get_ulong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_float

public float get_float()
                throws TypeMismatch,
                       InvalidValue
Extracts the float value from this DynAny.

Specified by:
get_float in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_double

public double get_double()
                  throws TypeMismatch,
                         InvalidValue
Extracts the double value from this DynAny.

Specified by:
get_double in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_string

public String get_string()
                  throws TypeMismatch,
                         InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Specified by:
get_string in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_reference

public Object get_reference()
                     throws TypeMismatch,
                            InvalidValue
Extracts the reference to a CORBA Object from this DynAny.

Specified by:
get_reference in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_typecode

public TypeCode get_typecode()
                      throws TypeMismatch,
                             InvalidValue
Extracts the TypeCode object from this DynAny.

Specified by:
get_typecode in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_longlong

public long get_longlong()
                  throws TypeMismatch,
                         InvalidValue
Extracts the long value from this DynAny. The IDL long long data type is mapped to the Java long data type.

Specified by:
get_longlong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulonglong

public long get_ulonglong()
                   throws TypeMismatch,
                          InvalidValue
Extracts the long value from this DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Specified by:
get_ulonglong in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wchar

public char get_wchar()
               throws TypeMismatch,
                      InvalidValue
Extracts the long value from this DynAny. The IDL wchar data type is mapped to the Java char data type.

Specified by:
get_wchar in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wstring

public String get_wstring()
                   throws TypeMismatch,
                          InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Specified by:
get_wstring in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue

get_any

public Any get_any()
            throws TypeMismatch,
                   InvalidValue
Extracts an Any value contained in the Any represented by this DynAny.

Specified by:
get_any in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_dyn_any

public DynAny get_dyn_any()
                   throws TypeMismatch,
                          InvalidValue
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.

Specified by:
get_dyn_any in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_val

public Serializable get_val()
                     throws TypeMismatch,
                            InvalidValue
Extracts a Serializable object from this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Specified by:
get_val in interface DynAnyOperations
Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

seek

public boolean seek(int index)
Sets the current position to index. The current position is indexed 0 to n-1, that is, index zero corresponds to the first component. The operation returns true if the resulting current position indicates a component of the DynAny and false if index indicates a position that does not correspond to a component. Calling seek with a negative index is legal. It sets the current position to -1 to indicate no component and returns false. Passing a non-negative index value for a DynAny that does not have a component at the corresponding position sets the current position to -1 and returns false.

Specified by:
seek in interface DynAnyOperations

rewind

public void rewind()
Is equivalent to seek(0).

Specified by:
rewind in interface DynAnyOperations

next

public boolean next()
Advances the current position to the next component. The operation returns true while the resulting current position indicates a component, false otherwise. A false return value leaves the current position at -1. Invoking next on a DynAny without components leaves the current position at -1 and returns false.

Specified by:
next in interface DynAnyOperations

component_count

public int component_count()
Returns the number of components of a DynAny. For a DynAny without components, it returns zero. The operation only counts the components at the top level. For example, if component_count is invoked on a DynStruct with a single member, the return value is 1, irrespective of the type of the member.
  • For sequences, the operation returns the current number of elements.
  • For structures, exceptions, and value types, the operation returns the number of members.
  • For arrays, the operation returns the number of elements.
  • For unions, the operation returns 2 if the discriminator indicates that a named member is active, otherwise, it returns 1.
  • For DynFixed and DynEnum, the operation returns zero.

Specified by:
component_count in interface DynAnyOperations

current_component

public DynAny current_component()
                         throws TypeMismatch
Returns the DynAny for the component at the current position. It does not advance the current position, so repeated calls to current_component without an intervening call to rewind, next, or seek return the same component. The returned DynAny object reference can be used to get/set the value of the current component. If the current component represents a complex type, the returned reference can be narrowed based on the TypeCode to get the interface corresponding to the to the complex type. Calling current_component on a DynAny that cannot have components, such as a DynEnum or an empty exception, raises TypeMismatch. Calling current_component on a DynAny whose current position is -1 returns a nil reference. The iteration operations, together with current_component, can be used to dynamically compose an any value. After creating a dynamic any, such as a DynStruct, current_component and next can be used to initialize all the components of the value. Once the dynamic value is completely initialized, to_any creates the corresponding any value.

Specified by:
current_component in interface DynAnyOperations
Throws:
TypeMismatch - If called on a DynAny that cannot have components, such as a DynEnum or an empty exception

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Specified by:
_ids in class ObjectImpl
Returns:
the array of all repository identifiers supported by this ObjectImpl instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


_DynAnyFactoryStub

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class _DynAnyFactoryStub

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.DynamicAny._DynAnyFactoryStub
All Implemented Interfaces:
Serializable, Object, IDLEntity, DynAnyFactory, DynAnyFactoryOperations
public class _DynAnyFactoryStub
extends ObjectImpl
implements DynAnyFactory

DynAny objects can be created by invoking operations on the DynAnyFactory object. Generally there are only two ways to create a DynAny object:

  • invoking an operation on an existing DynAny object
  • invoking an operation on a DynAnyFactory object
A constructed DynAny object supports operations that enable the creation of new DynAny objects encapsulating access to the value of some constituent. DynAny objects also support the copy operation for creating new DynAny objects. A reference to the DynAnyFactory object is obtained by calling ORB.resolve_initial_references() with the identifier parameter set to the string constant "DynAnyFactory".

Dynamic interpretation of an any usually involves creating a DynAny object using create_dyn_any() as the first step. Depending on the type of the any, the resulting DynAny object reference can be narrowed to a DynFixed, DynStruct, DynSequence, DynArray, DynUnion, DynEnum, or DynValue object reference.

Dynamic creation of an any involves creating a DynAny object using create_dyn_any_from_type_code(), passing the TypeCode associated with the value to be created. The returned reference is narrowed to one of the complex types, such as DynStruct, if appropriate. Then, the value can be initialized by means of invoking operations on the resulting object. Finally, the to_any operation can be invoked to create an any value from the constructed DynAny.

Field Summary
static Class _opsClass
Constructor Summary
_DynAnyFactoryStub()
Method Summary
String[] | _ids() Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
DynAny | create_dyn_any_from_type_code(TypeCode type) Creates a DynAny from a TypeCode.
DynAny | create_dyn_any(Any value) Creates a new DynAny object from an any value.
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Field Detail

_opsClass

public static final Class _opsClass
Constructor Detail

_DynAnyFactoryStub

public _DynAnyFactoryStub()
Method Detail

create_dyn_any

public DynAny create_dyn_any(Any value)
                      throws InconsistentTypeCode
Creates a new DynAny object from an any value. A copy of the TypeCode associated with the any value is assigned to the resulting DynAny object. The value associated with the DynAny object is a copy of the value in the original any. The current position of the created DynAny is set to zero if the passed value has components, to -1 otherwise

Specified by:
create_dyn_any in interface DynAnyFactoryOperations
Throws:
InconsistentTypeCode - if value has a TypeCode with a TCKind of tk_Principal, tk_native, or tk_abstract_interface

create_dyn_any_from_type_code

public DynAny create_dyn_any_from_type_code(TypeCode type)
                                     throws InconsistentTypeCode
Creates a DynAny from a TypeCode. Depending on the TypeCode, the created object may be of type DynAny, or one of its derived types, such as DynStruct. The returned reference can be narrowed to the derived type. In all cases, a DynAny constructed from a TypeCode has an initial default value. The default values of basic types are:
  • false for boolean
  • zero for numeric types
  • zero for types octet, char, and wchar
  • the empty string for string and wstring
  • null for object references
  • a type code with a TCKind value of tk_null for type codes
  • for any values, an any containing a type code with a TCKind value of tk_null type and no value
For complex types, creation of the corresponding DynAny assigns a default value as follows:
  • For DynSequence it sets the current position to -1 and creates an empty sequence.
  • For DynEnum it sets the current position to -1 and sets the value of the enumerator to the first enumerator value indicated by the TypeCode.
  • For DynFixed it sets the current position to -1 and sets the value zero.
  • For DynStruct it sets the current position to -1 for empty exceptions and to zero for all other TypeCodes. The members (if any) are (recursively) initialized to their default values.
  • For DynArray sets the current position to zero and (recursively) initializes elements to their default value.
  • For DynUnion sets the current position to zero. The discriminator value is set to a value consistent with the first named member of the union. That member is activated and (recursively) initialized to its default value.
  • For DynValue and DynValueBox it initializes to a null value.

Specified by:
create_dyn_any_from_type_code in interface DynAnyFactoryOperations
Throws:
InconsistentTypeCode

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Specified by:
_ids in class ObjectImpl
Returns:
the array of all repository identifiers supported by this ObjectImpl instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


DynAny

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynAny

All Superinterfaces:
DynAnyOperations, IDLEntity, Object, Serializable
All Known Subinterfaces:
DynArray, DynEnum, DynFixed, DynSequence, DynStruct, DynUnion, DynValue, DynValueBox, DynValueCommon
All Known Implementing Classes:
_DynAnyStub, _DynArrayStub, _DynEnumStub, _DynFixedStub, _DynSequenceStub, _DynStructStub, _DynUnionStub, _DynValueStub
public interface DynAny
extends DynAnyOperations, Object, IDLEntity

Any values can be dynamically interpreted (traversed) and constructed through DynAny objects. A DynAny object is associated with a data value which corresponds to a copy of the value inserted into an any.

A DynAny object may be viewed as an ordered collection of component DynAnys. For DynAnys representing a basic type, such as long, or a type without components, such as an empty exception, the ordered collection of components is empty. Each DynAny object maintains the notion of a current position into its collection of component DynAnys. The current position is identified by an index value that runs from 0 to n-1, where n is the number of components. The special index value -1 indicates a current position that points nowhere. For values that cannot have a current position (such as an empty exception), the index value is fixed at -1. If a DynAny is initialized with a value that has components, the index is initialized to 0. After creation of an uninitialized DynAny (that is, a DynAny that has no value but a TypeCode that permits components), the current position depends on the type of value represented by the DynAny. (The current position is set to 0 or -1, depending on whether the new DynAny gets default values for its components.)

The iteration operations rewind, seek, and next can be used to change the current position and the current_component operation returns the component at the current position. The component_count operation returns the number of components of a DynAny. Collectively, these operations enable iteration over the components of a DynAny, for example, to (recursively) examine its contents.

A constructed DynAny object is a DynAny object associated with a constructed type. There is a different interface, inheriting from the DynAny interface, associated with each kind of constructed type in IDL (fixed, enum, struct, sequence, union, array, exception, and value type).

A constructed DynAny object exports operations that enable the creation of new DynAny objects, each of them associated with a component of the constructed data value. As an example, a DynStruct is associated with a struct value. This means that the DynStruct may be seen as owning an ordered collection of components, one for each structure member. The DynStruct object exports operations that enable the creation of new DynAny objects, each of them associated with a member of the struct.

If a DynAny object has been obtained from another (constructed) DynAny object, such as a DynAny representing a structure member that was created from a DynStruct, the member DynAny is logically contained in the DynStruct. Calling an insert or get operation leaves the current position unchanged. Destroying a top-level DynAny object (one that was not obtained as a component of another DynAny) also destroys any component DynAny objects obtained from it. Destroying a non-top level DynAny object does nothing. Invoking operations on a destroyed top-level DynAny or any of its descendants raises OBJECT_NOT_EXIST. If the programmer wants to destroy a DynAny object but still wants to manipulate some component of the data value associated with it, then he or she should first create a DynAny for the component and, after that, make a copy of the created DynAny object.

The behavior of DynAny objects has been defined in order to enable efficient implementations in terms of allocated memory space and speed of access. DynAny objects are intended to be used for traversing values extracted from anys or constructing values of anys at runtime. Their use for other purposes is not recommended.

Insert and get operations are necessary to handle basic DynAny objects but are also helpful to handle constructed DynAny objects. Inserting a basic data type value into a constructed DynAny object implies initializing the current component of the constructed data value associated with the DynAny object. For example, invoking insert_boolean on a DynStruct implies inserting a boolean data value at the current position of the associated struct data value. A type is consistent for inserting or extracting a value if its TypeCode is equivalent to the TypeCode contained in the DynAny or, if the DynAny has components, is equivalent to the TypeCode of the DynAny at the current position.

DynAny and DynAnyFactory objects are intended to be local to the process in which they are created and used. This means that references to DynAny and DynAnyFactory objects cannot be exported to other processes, or externalized with ORB.object_to_string(). If any attempt is made to do so, the offending operation will raise a MARSHAL system exception. Since their interfaces are specified in IDL, DynAny objects export operations defined in the standard org.omg.CORBA.Object interface. However, any attempt to invoke operations exported through the Object interface may raise the standard NO_IMPLEMENT exception. An attempt to use a DynAny object with the DII may raise the NO_IMPLEMENT exception.

Method Summary
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynAnyFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynAnyFactory

All Superinterfaces:
DynAnyFactoryOperations, IDLEntity, Object, Serializable
All Known Implementing Classes:
_DynAnyFactoryStub
public interface DynAnyFactory
extends DynAnyFactoryOperations, Object, IDLEntity

DynAny objects can be created by invoking operations on the DynAnyFactory object. Generally there are only two ways to create a DynAny object:

  • invoking an operation on an existing DynAny object
  • invoking an operation on a DynAnyFactory object
A constructed DynAny object supports operations that enable the creation of new DynAny objects encapsulating access to the value of some constituent. DynAny objects also support the copy operation for creating new DynAny objects. A reference to the DynAnyFactory object is obtained by calling ORB.resolve_initial_references() with the identifier parameter set to the string constant "DynAnyFactory".

Dynamic interpretation of an any usually involves creating a DynAny object using create_dyn_any() as the first step. Depending on the type of the any, the resulting DynAny object reference can be narrowed to a DynFixed, DynStruct, DynSequence, DynArray, DynUnion, DynEnum, or DynValue object reference.

Dynamic creation of an any involves creating a DynAny object using create_dyn_any_from_type_code(), passing the TypeCode associated with the value to be created. The returned reference is narrowed to one of the complex types, such as DynStruct, if appropriate. Then, the value can be initialized by means of invoking operations on the resulting object. Finally, the to_any operation can be invoked to create an any value from the constructed DynAny.

Method Summary
Methods inherited from interface org.omg.DynamicAny.DynAnyFactoryOperations
create_dyn_any_from_type_code, create_dyn_any
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynArray

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynArray

All Superinterfaces:
DynAny, DynAnyOperations, DynArrayOperations, IDLEntity, Object, Serializable
All Known Implementing Classes:
_DynArrayStub
public interface DynArray
extends DynArrayOperations, DynAny, IDLEntity

DynArray objects support the manipulation of IDL arrays. Note that the dimension of the array is contained in the TypeCode which is accessible through the type attribute. It can also be obtained by calling the component_count operation.

Method Summary
Methods inherited from interface org.omg.DynamicAny.DynArrayOperations
get_elements_as_dyn_any, get_elements, set_elements_as_dyn_any, set_elements
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynEnum

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynEnum

All Superinterfaces:
DynAny, DynAnyOperations, DynEnumOperations, IDLEntity, Object, Serializable
All Known Implementing Classes:
_DynEnumStub
public interface DynEnum
extends DynEnumOperations, DynAny, IDLEntity

DynEnum objects support the manipulation of IDL enumerated values. The current position of a DynEnum is always -1.

Method Summary
Methods inherited from interface org.omg.DynamicAny.DynEnumOperations
get_as_string, get_as_ulong, set_as_string, set_as_ulong
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynFixed

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynFixed

All Superinterfaces:
DynAny, DynAnyOperations, DynFixedOperations, IDLEntity, Object, Serializable
All Known Implementing Classes:
_DynFixedStub
public interface DynFixed
extends DynFixedOperations, DynAny, IDLEntity

DynFixed objects support the manipulation of IDL fixed values. Because IDL does not have a generic type that can represent fixed types with arbitrary number of digits and arbitrary scale, the operations use the IDL string type.

Method Summary
Methods inherited from interface org.omg.DynamicAny.DynFixedOperations
get_value, set_value
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynSequence

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynSequence

All Superinterfaces:
DynAny, DynAnyOperations, DynSequenceOperations, IDLEntity, Object, Serializable
All Known Implementing Classes:
_DynSequenceStub
public interface DynSequence
extends DynSequenceOperations, DynAny, IDLEntity

DynSequence objects support the manipulation of IDL sequences.

Method Summary
Methods inherited from interface org.omg.DynamicAny.DynSequenceOperations
get_elements_as_dyn_any, get_elements, get_length, set_elements_as_dyn_any, set_elements, set_length
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynStruct

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynStruct

All Superinterfaces:
DynAny, DynAnyOperations, DynStructOperations, IDLEntity, Object, Serializable
All Known Implementing Classes:
_DynStructStub
public interface DynStruct
extends DynStructOperations, DynAny, IDLEntity

DynStruct objects support the manipulation of IDL struct and exception values. Members of the exceptions are handled in the same way as members of a struct.

Method Summary
Methods inherited from interface org.omg.DynamicAny.DynStructOperations
current_member_kind, current_member_name, get_members_as_dyn_any, get_members, set_members_as_dyn_any, set_members
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynUnion

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynUnion

All Superinterfaces:
DynAny, DynAnyOperations, DynUnionOperations, IDLEntity, Object, Serializable
All Known Implementing Classes:
_DynUnionStub
public interface DynUnion
extends DynUnionOperations, DynAny, IDLEntity

DynUnion objects support the manipulation of IDL unions. A union can have only two valid current positions:

  • zero, which denotes the discriminator
  • one, which denotes the active member
The component_count value for a union depends on the current discriminator: it is 2 for a union whose discriminator indicates a named member, and 1 otherwise.

Method Summary
Methods inherited from interface org.omg.DynamicAny.DynUnionOperations
discriminator_kind, get_discriminator, has_no_active_member, member_kind, member_name, member, set_discriminator, set_to_default_member, set_to_no_active_member
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynValue

All Superinterfaces:
DynAny, DynAnyOperations, DynValueCommon, DynValueCommonOperations, DynValueOperations, IDLEntity, Object, Serializable
All Known Implementing Classes:
_DynValueStub
public interface DynValue
extends DynValueOperations, DynValueCommon, IDLEntity

DynValue objects support the manipulation of IDL non-boxed value types. The DynValue interface can represent both null and non-null value types. For a DynValue representing a non-null value type, the DynValue's components comprise the public and private members of the value type, including those inherited from concrete base value types, in the order of definition. A DynValue representing a null value type has no components and a current position of -1.

Warning: Indiscriminantly changing the contents of private value type members can cause the value type implementation to break by violating internal constraints. Access to private members is provided to support such activities as ORB bridging and debugging and should not be used to arbitrarily violate the encapsulation of the value type.

Method Summary
Methods inherited from interface org.omg.DynamicAny.DynValueOperations
current_member_kind, current_member_name, get_members_as_dyn_any, get_members, set_members_as_dyn_any, set_members
Methods inherited from interface org.omg.DynamicAny.DynValueCommonOperations
is_null, set_to_null, set_to_value
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynValueBox

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynValueBox

All Superinterfaces:
DynAny, DynAnyOperations, DynValueBoxOperations, DynValueCommon, DynValueCommonOperations, IDLEntity, Object, Serializable
public interface DynValueBox
extends DynValueBoxOperations, DynValueCommon, IDLEntity

DynValueBox objects support the manipulation of IDL boxed value types. The DynValueBox interface can represent both null and non-null value types. For a DynValueBox representing a non-null value type, the DynValueBox has a single component of the boxed type. A DynValueBox representing a null value type has no components and a current position of -1.

Method Summary
Methods inherited from interface org.omg.DynamicAny.DynValueBoxOperations
get_boxed_value_as_dyn_any, get_boxed_value, set_boxed_value_as_dyn_any, set_boxed_value
Methods inherited from interface org.omg.DynamicAny.DynValueCommonOperations
is_null, set_to_null, set_to_value
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynValueCommon

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynValueCommon

All Superinterfaces:
DynAny, DynAnyOperations, DynValueCommonOperations, IDLEntity, Object, Serializable
All Known Subinterfaces:
DynValue, DynValueBox
All Known Implementing Classes:
_DynValueStub
public interface DynValueCommon
extends DynValueCommonOperations, DynAny, IDLEntity

DynValueCommon provides operations supported by both the DynValue and DynValueBox interfaces.

Method Summary
Methods inherited from interface org.omg.DynamicAny.DynValueCommonOperations
is_null, set_to_null, set_to_value
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


org.omg.DynamicAny Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.DynamicAny

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.DynamicAny.AnySeqHelper
    • org.omg.DynamicAny.DynAnyFactoryHelper
    • org.omg.DynamicAny.DynAnyHelper
    • org.omg.DynamicAny.DynAnySeqHelper
    • org.omg.DynamicAny.DynArrayHelper
    • org.omg.DynamicAny.DynEnumHelper
    • org.omg.DynamicAny.DynFixedHelper
    • org.omg.DynamicAny.DynSequenceHelper
    • org.omg.DynamicAny.DynStructHelper
    • org.omg.DynamicAny.DynUnionHelper
    • org.omg.DynamicAny.DynValueHelper
    • org.omg.DynamicAny.FieldNameHelper
    • org.omg.DynamicAny.NameDynAnyPair (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.DynamicAny.NameDynAnyPairHelper
    • org.omg.DynamicAny.NameDynAnyPairSeqHelper
    • org.omg.DynamicAny.NameValuePair (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.DynamicAny.NameValuePairHelper
    • org.omg.DynamicAny.NameValuePairSeqHelper
    • org.omg.CORBA.portable.ObjectImpl (implements org.omg.CORBA.Object)
      • org.omg.DynamicAny._DynAnyFactoryStub (implements org.omg.DynamicAny.DynAnyFactory)
      • org.omg.DynamicAny._DynAnyStub (implements org.omg.DynamicAny.DynAny)
      • org.omg.DynamicAny._DynArrayStub (implements org.omg.DynamicAny.DynArray)
      • org.omg.DynamicAny._DynEnumStub (implements org.omg.DynamicAny.DynEnum)
      • org.omg.DynamicAny._DynFixedStub (implements org.omg.DynamicAny.DynFixed)
      • org.omg.DynamicAny._DynSequenceStub (implements org.omg.DynamicAny.DynSequence)
      • org.omg.DynamicAny._DynStructStub (implements org.omg.DynamicAny.DynStruct)
      • org.omg.DynamicAny._DynUnionStub (implements org.omg.DynamicAny.DynUnion)
      • org.omg.DynamicAny._DynValueStub (implements org.omg.DynamicAny.DynValue)

Interface Hierarchy

  • org.omg.DynamicAny.DynAnyFactoryOperations
    • org.omg.DynamicAny.DynAnyFactory (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
  • org.omg.DynamicAny.DynAnyOperations
    • org.omg.DynamicAny.DynAny (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
      • org.omg.DynamicAny.DynArray (also extends org.omg.DynamicAny.DynArrayOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.DynamicAny.DynEnum (also extends org.omg.DynamicAny.DynEnumOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.DynamicAny.DynFixed (also extends org.omg.DynamicAny.DynFixedOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.DynamicAny.DynSequence (also extends org.omg.DynamicAny.DynSequenceOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.DynamicAny.DynStruct (also extends org.omg.DynamicAny.DynStructOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.DynamicAny.DynUnion (also extends org.omg.DynamicAny.DynUnionOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.DynamicAny.DynValueCommon (also extends org.omg.DynamicAny.DynValueCommonOperations, org.omg.CORBA.portable.IDLEntity)
        • org.omg.DynamicAny.DynValue (also extends org.omg.DynamicAny.DynValueOperations, org.omg.CORBA.portable.IDLEntity)
        • org.omg.DynamicAny.DynValueBox (also extends org.omg.DynamicAny.DynValueBoxOperations, org.omg.CORBA.portable.IDLEntity)
    • org.omg.DynamicAny.DynArrayOperations
      • org.omg.DynamicAny.DynArray (also extends org.omg.DynamicAny.DynAny, org.omg.CORBA.portable.IDLEntity)
    • org.omg.DynamicAny.DynEnumOperations
      • org.omg.DynamicAny.DynEnum (also extends org.omg.DynamicAny.DynAny, org.omg.CORBA.portable.IDLEntity)
    • org.omg.DynamicAny.DynFixedOperations
      • org.omg.DynamicAny.DynFixed (also extends org.omg.DynamicAny.DynAny, org.omg.CORBA.portable.IDLEntity)
    • org.omg.DynamicAny.DynSequenceOperations
      • org.omg.DynamicAny.DynSequence (also extends org.omg.DynamicAny.DynAny, org.omg.CORBA.portable.IDLEntity)
    • org.omg.DynamicAny.DynStructOperations
      • org.omg.DynamicAny.DynStruct (also extends org.omg.DynamicAny.DynAny, org.omg.CORBA.portable.IDLEntity)
    • org.omg.DynamicAny.DynUnionOperations
      • org.omg.DynamicAny.DynUnion (also extends org.omg.DynamicAny.DynAny, org.omg.CORBA.portable.IDLEntity)
    • org.omg.DynamicAny.DynValueCommonOperations
      • org.omg.DynamicAny.DynValueBoxOperations
        • org.omg.DynamicAny.DynValueBox (also extends org.omg.DynamicAny.DynValueCommon, org.omg.CORBA.portable.IDLEntity)
      • org.omg.DynamicAny.DynValueCommon (also extends org.omg.DynamicAny.DynAny, org.omg.CORBA.portable.IDLEntity)
        • org.omg.DynamicAny.DynValue (also extends org.omg.DynamicAny.DynValueOperations, org.omg.CORBA.portable.IDLEntity)
        • org.omg.DynamicAny.DynValueBox (also extends org.omg.DynamicAny.DynValueBoxOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.DynamicAny.DynValueOperations
        • org.omg.DynamicAny.DynValue (also extends org.omg.DynamicAny.DynValueCommon, org.omg.CORBA.portable.IDLEntity)
  • org.omg.CORBA.Object
    • org.omg.DynamicAny.DynAny (also extends org.omg.DynamicAny.DynAnyOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.DynamicAny.DynArray (also extends org.omg.DynamicAny.DynArrayOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.DynamicAny.DynEnum (also extends org.omg.DynamicAny.DynEnumOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.DynamicAny.DynFixed (also extends org.omg.DynamicAny.DynFixedOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.DynamicAny.DynSequence (also extends org.omg.DynamicAny.DynSequenceOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.DynamicAny.DynStruct (also extends org.omg.DynamicAny.DynStructOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.DynamicAny.DynUnion (also extends org.omg.DynamicAny.DynUnionOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.DynamicAny.DynValueCommon (also extends org.omg.DynamicAny.DynValueCommonOperations, org.omg.CORBA.portable.IDLEntity)
        • org.omg.DynamicAny.DynValue (also extends org.omg.DynamicAny.DynValueOperations, org.omg.CORBA.portable.IDLEntity)
        • org.omg.DynamicAny.DynValueBox (also extends org.omg.DynamicAny.DynValueBoxOperations, org.omg.CORBA.portable.IDLEntity)
    • org.omg.DynamicAny.DynAnyFactory (also extends org.omg.DynamicAny.DynAnyFactoryOperations, org.omg.CORBA.portable.IDLEntity)
  • java.io.Serializable
    • org.omg.CORBA.portable.IDLEntity
      • org.omg.DynamicAny.DynAny (also extends org.omg.DynamicAny.DynAnyOperations, org.omg.CORBA.Object)
        • org.omg.DynamicAny.DynArray (also extends org.omg.DynamicAny.DynArrayOperations, org.omg.CORBA.portable.IDLEntity)
        • org.omg.DynamicAny.DynEnum (also extends org.omg.DynamicAny.DynEnumOperations, org.omg.CORBA.portable.IDLEntity)
        • org.omg.DynamicAny.DynFixed (also extends org.omg.DynamicAny.DynFixedOperations, org.omg.CORBA.portable.IDLEntity)
        • org.omg.DynamicAny.DynSequence (also extends org.omg.DynamicAny.DynSequenceOperations, org.omg.CORBA.portable.IDLEntity)
        • org.omg.DynamicAny.DynStruct (also extends org.omg.DynamicAny.DynStructOperations, org.omg.CORBA.portable.IDLEntity)
        • org.omg.DynamicAny.DynUnion (also extends org.omg.DynamicAny.DynUnionOperations, org.omg.CORBA.portable.IDLEntity)
        • org.omg.DynamicAny.DynValueCommon (also extends org.omg.DynamicAny.DynValueCommonOperations, org.omg.CORBA.portable.IDLEntity)
          • org.omg.DynamicAny.DynValue (also extends org.omg.DynamicAny.DynValueOperations, org.omg.CORBA.portable.IDLEntity)
          • org.omg.DynamicAny.DynValueBox (also extends org.omg.DynamicAny.DynValueBoxOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.DynamicAny.DynAnyFactory (also extends org.omg.DynamicAny.DynAnyFactoryOperations, org.omg.CORBA.Object)
      • org.omg.DynamicAny.DynArray (also extends org.omg.DynamicAny.DynAny, org.omg.DynamicAny.DynArrayOperations)
      • org.omg.DynamicAny.DynEnum (also extends org.omg.DynamicAny.DynAny, org.omg.DynamicAny.DynEnumOperations)
      • org.omg.DynamicAny.DynFixed (also extends org.omg.DynamicAny.DynAny, org.omg.DynamicAny.DynFixedOperations)
      • org.omg.DynamicAny.DynSequence (also extends org.omg.DynamicAny.DynAny, org.omg.DynamicAny.DynSequenceOperations)
      • org.omg.DynamicAny.DynStruct (also extends org.omg.DynamicAny.DynAny, org.omg.DynamicAny.DynStructOperations)
      • org.omg.DynamicAny.DynUnion (also extends org.omg.DynamicAny.DynAny, org.omg.DynamicAny.DynUnionOperations)
      • org.omg.DynamicAny.DynValue (also extends org.omg.DynamicAny.DynValueCommon, org.omg.DynamicAny.DynValueOperations)
      • org.omg.DynamicAny.DynValueBox (also extends org.omg.DynamicAny.DynValueBoxOperations, org.omg.DynamicAny.DynValueCommon)
      • org.omg.DynamicAny.DynValueCommon (also extends org.omg.DynamicAny.DynAny, org.omg.DynamicAny.DynValueCommonOperations)
        • org.omg.DynamicAny.DynValue (also extends org.omg.DynamicAny.DynValueOperations, org.omg.CORBA.portable.IDLEntity)
        • org.omg.DynamicAny.DynValueBox (also extends org.omg.DynamicAny.DynValueBoxOperations, org.omg.CORBA.portable.IDLEntity)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.DynamicAny

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.DynamicAny

Packages that use org.omg.DynamicAny
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Classes in org.omg.DynamicAny used by org.omg.DynamicAny
DynAny
Any values can be dynamically interpreted (traversed) and constructed through DynAny objects.
DynAnyFactory
DynAny objects can be created by invoking operations on the DynAnyFactory object.
DynAnyFactoryOperations
DynAny objects can be created by invoking operations on the DynAnyFactory object.
DynAnyOperations
Any values can be dynamically interpreted (traversed) and constructed through DynAny objects.
DynArray
DynArray objects support the manipulation of IDL arrays.
DynArrayOperations
DynArray objects support the manipulation of IDL arrays.
DynEnum
DynEnum objects support the manipulation of IDL enumerated values.
DynEnumOperations
DynEnum objects support the manipulation of IDL enumerated values.
DynFixed
DynFixed objects support the manipulation of IDL fixed values.
DynFixedOperations
DynFixed objects support the manipulation of IDL fixed values.
DynSequence
DynSequence objects support the manipulation of IDL sequences.
DynSequenceOperations
DynSequence objects support the manipulation of IDL sequences.
DynStruct
DynStruct objects support the manipulation of IDL struct and exception values.
DynStructOperations
DynStruct objects support the manipulation of IDL struct and exception values.
DynUnion
DynUnion objects support the manipulation of IDL unions.
DynUnionOperations
DynUnion objects support the manipulation of IDL unions.
DynValue
DynValue objects support the manipulation of IDL non-boxed value types.
DynValueBoxOperations
DynValueBox objects support the manipulation of IDL boxed value types.
DynValueCommon
DynValueCommon provides operations supported by both the DynValue and DynValueBox interfaces.
DynValueCommonOperations
DynValueCommon provides operations supported by both the DynValue and DynValueBox interfaces.
DynValueOperations
DynValue objects support the manipulation of IDL non-boxed value types.
NameDynAnyPair
org/omg/DynamicAny/NameDynAnyPair.java .
NameValuePair
org/omg/DynamicAny/NameValuePair.java .

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AnySeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class AnySeqHelper

java.lang.Object
    extended by  org.omg.DynamicAny.AnySeqHelper

public abstract class AnySeqHelper
extends Object

org/omg/DynamicAny/AnySeqHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/DynamicAny/DynamicAny.idl Wednesday, November 29, 2006 1:57:29 AM GMT-08:00

Constructor Summary
AnySeqHelper()
Method Summary
static Any[] | extract(Any a)
static String | id()
static void | insert(Any a, Any[] that)
static Any[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, Any[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AnySeqHelper

public AnySeqHelper()
Method Detail

insert

public static void insert(Any a,
                          Any[] that)

extract

public static Any[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static Any[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         Any[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class org.omg.DynamicAny.AnySeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.AnySeqHelper

No usage of org.omg.DynamicAny.AnySeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.DynAnyFactoryHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.DynAnyFactoryHelper

No usage of org.omg.DynamicAny.DynAnyFactoryHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.DynAnyHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.DynAnyHelper

No usage of org.omg.DynamicAny.DynAnyHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.DynAnySeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.DynAnySeqHelper

No usage of org.omg.DynamicAny.DynAnySeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.DynArrayHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.DynArrayHelper

No usage of org.omg.DynamicAny.DynArrayHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.DynEnumHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.DynEnumHelper

No usage of org.omg.DynamicAny.DynEnumHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.DynFixedHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.DynFixedHelper

No usage of org.omg.DynamicAny.DynFixedHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.DynSequenceHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.DynSequenceHelper

No usage of org.omg.DynamicAny.DynSequenceHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.DynStructHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.DynStructHelper

No usage of org.omg.DynamicAny.DynStructHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.DynUnionHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.DynUnionHelper

No usage of org.omg.DynamicAny.DynUnionHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.DynValueHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.DynValueHelper

No usage of org.omg.DynamicAny.DynValueHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.FieldNameHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.FieldNameHelper

No usage of org.omg.DynamicAny.FieldNameHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.NameDynAnyPair

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.NameDynAnyPair

Packages that use NameDynAnyPair
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of NameDynAnyPair in org.omg.DynamicAny

Methods in org.omg.DynamicAny that return NameDynAnyPair
static NameDynAnyPair[] | NameDynAnyPairSeqHelper.extract(Any a)
static NameDynAnyPair | NameDynAnyPairHelper.extract(Any a)
NameDynAnyPair[] | _DynValueStub.get_members_as_dyn_any() Returns a sequence of NameDynAnyPairs describing the name and the value of each member in the value type.
NameDynAnyPair[] | _DynStructStub.get_members_as_dyn_any() Returns a sequence of NameDynAnyPairs describing the name and the value of each member in the struct associated with a DynStruct object.
NameDynAnyPair[] | DynValueOperations.get_members_as_dyn_any() Returns a sequence of NameDynAnyPairs describing the name and the value of each member in the value type.
NameDynAnyPair[] | DynStructOperations.get_members_as_dyn_any() Returns a sequence of NameDynAnyPairs describing the name and the value of each member in the struct associated with a DynStruct object.
static NameDynAnyPair[] | NameDynAnyPairSeqHelper.read(InputStream istream)
static NameDynAnyPair | NameDynAnyPairHelper.read(InputStream istream)

Methods in org.omg.DynamicAny with parameters of type NameDynAnyPair
static void | NameDynAnyPairHelper.insert(Any a, NameDynAnyPair that)
static void | NameDynAnyPairSeqHelper.insert(Any a, NameDynAnyPair[] that)
void | _DynValueStub.set_members_as_dyn_any(NameDynAnyPair[] value) Initializes the value type's members from a sequence of NameDynAnyPairs.
void | _DynStructStub.set_members_as_dyn_any(NameDynAnyPair[] value) Initializes the struct data value associated with a DynStruct object from a sequence of NameDynAnyPairs.
void | DynValueOperations.set_members_as_dyn_any(NameDynAnyPair[] value) Initializes the value type's members from a sequence of NameDynAnyPairs.
void | DynStructOperations.set_members_as_dyn_any(NameDynAnyPair[] value) Initializes the struct data value associated with a DynStruct object from a sequence of NameDynAnyPairs.
static void | NameDynAnyPairHelper.write(OutputStream ostream, NameDynAnyPair value)
static void | NameDynAnyPairSeqHelper.write(OutputStream ostream, NameDynAnyPair[] value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.NameDynAnyPairHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.NameDynAnyPairHelper

No usage of org.omg.DynamicAny.NameDynAnyPairHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.NameDynAnyPairSeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.NameDynAnyPairSeqHelper

No usage of org.omg.DynamicAny.NameDynAnyPairSeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.NameValuePair

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.NameValuePair

Packages that use NameValuePair
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of NameValuePair in org.omg.DynamicAny

Methods in org.omg.DynamicAny that return NameValuePair
static NameValuePair[] | NameValuePairSeqHelper.extract(Any a)
static NameValuePair | NameValuePairHelper.extract(Any a)
NameValuePair[] | _DynValueStub.get_members() Returns a sequence of NameValuePairs describing the name and the value of each member in the value type.
NameValuePair[] | _DynStructStub.get_members() Returns a sequence of NameValuePairs describing the name and the value of each member in the struct associated with a DynStruct object.
NameValuePair[] | DynValueOperations.get_members() Returns a sequence of NameValuePairs describing the name and the value of each member in the value type.
NameValuePair[] | DynStructOperations.get_members() Returns a sequence of NameValuePairs describing the name and the value of each member in the struct associated with a DynStruct object.
static NameValuePair[] | NameValuePairSeqHelper.read(InputStream istream)
static NameValuePair | NameValuePairHelper.read(InputStream istream)

Methods in org.omg.DynamicAny with parameters of type NameValuePair
static void | NameValuePairHelper.insert(Any a, NameValuePair that)
static void | NameValuePairSeqHelper.insert(Any a, NameValuePair[] that)
void | _DynValueStub.set_members(NameValuePair[] value) Initializes the value type's members from a sequence of NameValuePairs.
void | _DynStructStub.set_members(NameValuePair[] value) Initializes the struct data value associated with a DynStruct object from a sequence of NameValuePairs.
void | DynValueOperations.set_members(NameValuePair[] value) Initializes the value type's members from a sequence of NameValuePairs.
void | DynStructOperations.set_members(NameValuePair[] value) Initializes the struct data value associated with a DynStruct object from a sequence of NameValuePairs.
static void | NameValuePairHelper.write(OutputStream ostream, NameValuePair value)
static void | NameValuePairSeqHelper.write(OutputStream ostream, NameValuePair[] value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.NameValuePairHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.NameValuePairHelper

No usage of org.omg.DynamicAny.NameValuePairHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.NameValuePairSeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.NameValuePairSeqHelper

No usage of org.omg.DynamicAny.NameValuePairSeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny._DynAnyFactoryStub

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny._DynAnyFactoryStub

No usage of org.omg.DynamicAny._DynAnyFactoryStub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny._DynAnyStub

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny._DynAnyStub

No usage of org.omg.DynamicAny._DynAnyStub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny._DynArrayStub

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny._DynArrayStub

No usage of org.omg.DynamicAny._DynArrayStub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny._DynEnumStub

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny._DynEnumStub

No usage of org.omg.DynamicAny._DynEnumStub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny._DynFixedStub

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny._DynFixedStub

No usage of org.omg.DynamicAny._DynFixedStub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny._DynSequenceStub

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny._DynSequenceStub

No usage of org.omg.DynamicAny._DynSequenceStub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny._DynStructStub

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny._DynStructStub

No usage of org.omg.DynamicAny._DynStructStub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny._DynUnionStub

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny._DynUnionStub

No usage of org.omg.DynamicAny._DynUnionStub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny._DynValueStub

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny._DynValueStub

No usage of org.omg.DynamicAny._DynValueStub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynAny

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynAny

Packages that use DynAny
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynAny in org.omg.DynamicAny

Subinterfaces of DynAny in org.omg.DynamicAny
interface | DynArray DynArray objects support the manipulation of IDL arrays.
interface | DynEnum DynEnum objects support the manipulation of IDL enumerated values.
interface | DynFixed DynFixed objects support the manipulation of IDL fixed values.
interface | DynSequence DynSequence objects support the manipulation of IDL sequences.
interface | DynStruct DynStruct objects support the manipulation of IDL struct and exception values.
interface | DynUnion DynUnion objects support the manipulation of IDL unions.
interface | DynValue DynValue objects support the manipulation of IDL non-boxed value types.
interface | DynValueBox DynValueBox objects support the manipulation of IDL boxed value types.
interface | DynValueCommon DynValueCommon provides operations supported by both the DynValue and DynValueBox interfaces.

Classes in org.omg.DynamicAny that implement DynAny
class | _DynAnyStub Any values can be dynamically interpreted (traversed) and constructed through DynAny objects.
class | _DynArrayStub DynArray objects support the manipulation of IDL arrays.
class | _DynEnumStub DynEnum objects support the manipulation of IDL enumerated values.
class | _DynFixedStub DynFixed objects support the manipulation of IDL fixed values.
class | _DynSequenceStub DynSequence objects support the manipulation of IDL sequences.
class | _DynStructStub DynStruct objects support the manipulation of IDL struct and exception values.
class | _DynUnionStub DynUnion objects support the manipulation of IDL unions.
class | _DynValueStub DynValue objects support the manipulation of IDL non-boxed value types.

Fields in org.omg.DynamicAny declared as DynAny
 DynAny NameDynAnyPair.value
The DynAny value associated with the name.

Methods in org.omg.DynamicAny that return DynAny
DynAny | _DynSequenceStub.copy() Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
DynAny | _DynFixedStub.copy() Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
DynAny | _DynEnumStub.copy() Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
DynAny | _DynArrayStub.copy() Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
DynAny | _DynValueStub.copy() Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
DynAny | _DynAnyStub.copy() Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
DynAny | _DynUnionStub.copy() Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
DynAny | _DynStructStub.copy() Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
DynAny | DynAnyOperations.copy() Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
DynAny | _DynAnyFactoryStub.create_dyn_any_from_type_code(TypeCode type) Creates a DynAny from a TypeCode.
DynAny | DynAnyFactoryOperations.create_dyn_any_from_type_code(TypeCode type) Creates a DynAny from a TypeCode.
DynAny | _DynAnyFactoryStub.create_dyn_any(Any value) Creates a new DynAny object from an any value.
DynAny | DynAnyFactoryOperations.create_dyn_any(Any value) Creates a new DynAny object from an any value.
DynAny | _DynSequenceStub.current_component() Returns the DynAny for the component at the current position.
DynAny | _DynFixedStub.current_component() Returns the DynAny for the component at the current position.
DynAny | _DynEnumStub.current_component() Returns the DynAny for the component at the current position.
DynAny | _DynArrayStub.current_component() Returns the DynAny for the component at the current position.
DynAny | _DynValueStub.current_component() Returns the DynAny for the component at the current position.
DynAny | _DynAnyStub.current_component() Returns the DynAny for the component at the current position.
DynAny | _DynUnionStub.current_component() Returns the DynAny for the component at the current position.
DynAny | _DynStructStub.current_component() Returns the DynAny for the component at the current position.
DynAny | DynAnyOperations.current_component() Returns the DynAny for the component at the current position.
static DynAny[] | DynAnySeqHelper.extract(Any a)
static DynAny | DynAnyHelper.extract(Any a)
DynAny | DynValueBoxOperations.get_boxed_value_as_dyn_any() Returns the boxed value as a DynAny.
DynAny | _DynUnionStub.get_discriminator() Returns the current discriminator value.
DynAny | DynUnionOperations.get_discriminator() Returns the current discriminator value.
DynAny | _DynSequenceStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynFixedStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynEnumStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynArrayStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynValueStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynAnyStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynUnionStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynStructStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | DynAnyOperations.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny[] | _DynSequenceStub.get_elements_as_dyn_any() Returns the DynAnys representing the elements of the sequence.
DynAny[] | _DynArrayStub.get_elements_as_dyn_any() Returns the elements of the DynArray as DynAnys.
DynAny[] | DynSequenceOperations.get_elements_as_dyn_any() Returns the DynAnys representing the elements of the sequence.
DynAny[] | DynArrayOperations.get_elements_as_dyn_any() Returns the elements of the DynArray as DynAnys.
DynAny | _DynUnionStub.member() Returns the currently active member.
DynAny | DynUnionOperations.member() Returns the currently active member.
static DynAny | DynAnyHelper.narrow(Object obj)
static DynAny[] | DynAnySeqHelper.read(InputStream istream)
static DynAny | DynAnyHelper.read(InputStream istream)
static DynAny | DynAnyHelper.unchecked_narrow(Object obj)

Methods in org.omg.DynamicAny with parameters of type DynAny
void | _DynSequenceStub.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
void | _DynFixedStub.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
void | _DynEnumStub.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
void | _DynArrayStub.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
void | _DynValueStub.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
void | _DynAnyStub.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
void | _DynUnionStub.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
void | _DynStructStub.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
void | DynAnyOperations.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
boolean | _DynSequenceStub.equal(DynAny dyn_any) Compares two DynAny values for equality.
boolean | _DynFixedStub.equal(DynAny dyn_any) Compares two DynAny values for equality.
boolean | _DynEnumStub.equal(DynAny dyn_any) Compares two DynAny values for equality.
boolean | _DynArrayStub.equal(DynAny dyn_any) Compares two DynAny values for equality.
boolean | _DynValueStub.equal(DynAny dyn_any) Compares two DynAny values for equality.
boolean | _DynAnyStub.equal(DynAny dyn_any) Compares two DynAny values for equality.
boolean | _DynUnionStub.equal(DynAny dyn_any) Compares two DynAny values for equality.
boolean | _DynStructStub.equal(DynAny dyn_any) Compares two DynAny values for equality.
boolean | DynAnyOperations.equal(DynAny dyn_any) Compares two DynAny values for equality.
void | _DynSequenceStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynFixedStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynEnumStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynArrayStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynValueStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynAnyStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynUnionStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynStructStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | DynAnyOperations.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
static void | DynAnyHelper.insert(Any a, DynAny that)
static void | DynAnySeqHelper.insert(Any a, DynAny[] that)
void | DynValueBoxOperations.set_boxed_value_as_dyn_any(DynAny boxed) Replaces the boxed value with the value contained in the parameter.
void | _DynUnionStub.set_discriminator(DynAny d) Sets the discriminator of the DynUnion to the specified value.
void | DynUnionOperations.set_discriminator(DynAny d) Sets the discriminator of the DynUnion to the specified value.
void | _DynSequenceStub.set_elements_as_dyn_any(DynAny[] value) Sets the elements of a sequence using DynAnys.
void | _DynArrayStub.set_elements_as_dyn_any(DynAny[] value) Sets the DynArray to contain the passed elements.
void | DynSequenceOperations.set_elements_as_dyn_any(DynAny[] value) Sets the elements of a sequence using DynAnys.
void | DynArrayOperations.set_elements_as_dyn_any(DynAny[] value) Sets the DynArray to contain the passed elements.
static void | DynAnyHelper.write(OutputStream ostream, DynAny value)
static void | DynAnySeqHelper.write(OutputStream ostream, DynAny[] value)

Constructors in org.omg.DynamicAny with parameters of type DynAny
NameDynAnyPair(String _id, DynAny _value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynAnyFactory

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynAnyFactory

Packages that use DynAnyFactory
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynAnyFactory in org.omg.DynamicAny

Classes in org.omg.DynamicAny that implement DynAnyFactory
 class _DynAnyFactoryStub
DynAny objects can be created by invoking operations on the DynAnyFactory object.

Methods in org.omg.DynamicAny that return DynAnyFactory
static DynAnyFactory | DynAnyFactoryHelper.extract(Any a)
static DynAnyFactory | DynAnyFactoryHelper.narrow(Object obj)
static DynAnyFactory | DynAnyFactoryHelper.read(InputStream istream)
static DynAnyFactory | DynAnyFactoryHelper.unchecked_narrow(Object obj)

Methods in org.omg.DynamicAny with parameters of type DynAnyFactory
static void | DynAnyFactoryHelper.insert(Any a, DynAnyFactory that)
static void | DynAnyFactoryHelper.write(OutputStream ostream, DynAnyFactory value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynAnyFactoryOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynAnyFactoryOperations

Packages that use DynAnyFactoryOperations
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynAnyFactoryOperations in org.omg.DynamicAny

Subinterfaces of DynAnyFactoryOperations in org.omg.DynamicAny
 interface DynAnyFactory
DynAny objects can be created by invoking operations on the DynAnyFactory object.

Classes in org.omg.DynamicAny that implement DynAnyFactoryOperations
 class _DynAnyFactoryStub
DynAny objects can be created by invoking operations on the DynAnyFactory object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynAnyOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynAnyOperations

Packages that use DynAnyOperations
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynAnyOperations in org.omg.DynamicAny

Subinterfaces of DynAnyOperations in org.omg.DynamicAny
interface | DynAny Any values can be dynamically interpreted (traversed) and constructed through DynAny objects.
interface | DynArray DynArray objects support the manipulation of IDL arrays.
interface | DynArrayOperations DynArray objects support the manipulation of IDL arrays.
interface | DynEnum DynEnum objects support the manipulation of IDL enumerated values.
interface | DynEnumOperations DynEnum objects support the manipulation of IDL enumerated values.
interface | DynFixed DynFixed objects support the manipulation of IDL fixed values.
interface | DynFixedOperations DynFixed objects support the manipulation of IDL fixed values.
interface | DynSequence DynSequence objects support the manipulation of IDL sequences.
interface | DynSequenceOperations DynSequence objects support the manipulation of IDL sequences.
interface | DynStruct DynStruct objects support the manipulation of IDL struct and exception values.
interface | DynStructOperations DynStruct objects support the manipulation of IDL struct and exception values.
interface | DynUnion DynUnion objects support the manipulation of IDL unions.
interface | DynUnionOperations DynUnion objects support the manipulation of IDL unions.
interface | DynValue DynValue objects support the manipulation of IDL non-boxed value types.
interface | DynValueBox DynValueBox objects support the manipulation of IDL boxed value types.
interface | DynValueBoxOperations DynValueBox objects support the manipulation of IDL boxed value types.
interface | DynValueCommon DynValueCommon provides operations supported by both the DynValue and DynValueBox interfaces.
interface | DynValueCommonOperations DynValueCommon provides operations supported by both the DynValue and DynValueBox interfaces.
interface | DynValueOperations DynValue objects support the manipulation of IDL non-boxed value types.

Classes in org.omg.DynamicAny that implement DynAnyOperations
class | _DynAnyStub Any values can be dynamically interpreted (traversed) and constructed through DynAny objects.
class | _DynArrayStub DynArray objects support the manipulation of IDL arrays.
class | _DynEnumStub DynEnum objects support the manipulation of IDL enumerated values.
class | _DynFixedStub DynFixed objects support the manipulation of IDL fixed values.
class | _DynSequenceStub DynSequence objects support the manipulation of IDL sequences.
class | _DynStructStub DynStruct objects support the manipulation of IDL struct and exception values.
class | _DynUnionStub DynUnion objects support the manipulation of IDL unions.
class | _DynValueStub DynValue objects support the manipulation of IDL non-boxed value types.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynArray

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynArray

Packages that use DynArray
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynArray in org.omg.DynamicAny

Classes in org.omg.DynamicAny that implement DynArray
 class _DynArrayStub
DynArray objects support the manipulation of IDL arrays.

Methods in org.omg.DynamicAny that return DynArray
static DynArray | DynArrayHelper.extract(Any a)
static DynArray | DynArrayHelper.narrow(Object obj)
static DynArray | DynArrayHelper.read(InputStream istream)
static DynArray | DynArrayHelper.unchecked_narrow(Object obj)

Methods in org.omg.DynamicAny with parameters of type DynArray
static void | DynArrayHelper.insert(Any a, DynArray that)
static void | DynArrayHelper.write(OutputStream ostream, DynArray value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynArrayOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynArrayOperations

Packages that use DynArrayOperations
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynArrayOperations in org.omg.DynamicAny

Subinterfaces of DynArrayOperations in org.omg.DynamicAny
 interface DynArray
DynArray objects support the manipulation of IDL arrays.

Classes in org.omg.DynamicAny that implement DynArrayOperations
 class _DynArrayStub
DynArray objects support the manipulation of IDL arrays.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynEnum

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynEnum

Packages that use DynEnum
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynEnum in org.omg.DynamicAny

Classes in org.omg.DynamicAny that implement DynEnum
 class _DynEnumStub
DynEnum objects support the manipulation of IDL enumerated values.

Methods in org.omg.DynamicAny that return DynEnum
static DynEnum | DynEnumHelper.extract(Any a)
static DynEnum | DynEnumHelper.narrow(Object obj)
static DynEnum | DynEnumHelper.read(InputStream istream)
static DynEnum | DynEnumHelper.unchecked_narrow(Object obj)

Methods in org.omg.DynamicAny with parameters of type DynEnum
static void | DynEnumHelper.insert(Any a, DynEnum that)
static void | DynEnumHelper.write(OutputStream ostream, DynEnum value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynEnumOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynEnumOperations

Packages that use DynEnumOperations
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynEnumOperations in org.omg.DynamicAny

Subinterfaces of DynEnumOperations in org.omg.DynamicAny
 interface DynEnum
DynEnum objects support the manipulation of IDL enumerated values.

Classes in org.omg.DynamicAny that implement DynEnumOperations
 class _DynEnumStub
DynEnum objects support the manipulation of IDL enumerated values.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynFixed

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynFixed

Packages that use DynFixed
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynFixed in org.omg.DynamicAny

Classes in org.omg.DynamicAny that implement DynFixed
 class _DynFixedStub
DynFixed objects support the manipulation of IDL fixed values.

Methods in org.omg.DynamicAny that return DynFixed
static DynFixed | DynFixedHelper.extract(Any a)
static DynFixed | DynFixedHelper.narrow(Object obj)
static DynFixed | DynFixedHelper.read(InputStream istream)
static DynFixed | DynFixedHelper.unchecked_narrow(Object obj)

Methods in org.omg.DynamicAny with parameters of type DynFixed
static void | DynFixedHelper.insert(Any a, DynFixed that)
static void | DynFixedHelper.write(OutputStream ostream, DynFixed value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynFixedOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynFixedOperations

Packages that use DynFixedOperations
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynFixedOperations in org.omg.DynamicAny

Subinterfaces of DynFixedOperations in org.omg.DynamicAny
 interface DynFixed
DynFixed objects support the manipulation of IDL fixed values.

Classes in org.omg.DynamicAny that implement DynFixedOperations
 class _DynFixedStub
DynFixed objects support the manipulation of IDL fixed values.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynSequence

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynSequence

Packages that use DynSequence
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynSequence in org.omg.DynamicAny

Classes in org.omg.DynamicAny that implement DynSequence
 class _DynSequenceStub
DynSequence objects support the manipulation of IDL sequences.

Methods in org.omg.DynamicAny that return DynSequence
static DynSequence | DynSequenceHelper.extract(Any a)
static DynSequence | DynSequenceHelper.narrow(Object obj)
static DynSequence | DynSequenceHelper.read(InputStream istream)
static DynSequence | DynSequenceHelper.unchecked_narrow(Object obj)

Methods in org.omg.DynamicAny with parameters of type DynSequence
static void | DynSequenceHelper.insert(Any a, DynSequence that)
static void | DynSequenceHelper.write(OutputStream ostream, DynSequence value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynSequenceOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynSequenceOperations

Packages that use DynSequenceOperations
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynSequenceOperations in org.omg.DynamicAny

Subinterfaces of DynSequenceOperations in org.omg.DynamicAny
 interface DynSequence
DynSequence objects support the manipulation of IDL sequences.

Classes in org.omg.DynamicAny that implement DynSequenceOperations
 class _DynSequenceStub
DynSequence objects support the manipulation of IDL sequences.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynStruct

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynStruct

Packages that use DynStruct
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynStruct in org.omg.DynamicAny

Classes in org.omg.DynamicAny that implement DynStruct
 class _DynStructStub
DynStruct objects support the manipulation of IDL struct and exception values.

Methods in org.omg.DynamicAny that return DynStruct
static DynStruct | DynStructHelper.extract(Any a)
static DynStruct | DynStructHelper.narrow(Object obj)
static DynStruct | DynStructHelper.read(InputStream istream)
static DynStruct | DynStructHelper.unchecked_narrow(Object obj)

Methods in org.omg.DynamicAny with parameters of type DynStruct
static void | DynStructHelper.insert(Any a, DynStruct that)
static void | DynStructHelper.write(OutputStream ostream, DynStruct value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynStructOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynStructOperations

Packages that use DynStructOperations
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynStructOperations in org.omg.DynamicAny

Subinterfaces of DynStructOperations in org.omg.DynamicAny
 interface DynStruct
DynStruct objects support the manipulation of IDL struct and exception values.

Classes in org.omg.DynamicAny that implement DynStructOperations
 class _DynStructStub
DynStruct objects support the manipulation of IDL struct and exception values.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynUnion

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynUnion

Packages that use DynUnion
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynUnion in org.omg.DynamicAny

Classes in org.omg.DynamicAny that implement DynUnion
 class _DynUnionStub
DynUnion objects support the manipulation of IDL unions.

Methods in org.omg.DynamicAny that return DynUnion
static DynUnion | DynUnionHelper.extract(Any a)
static DynUnion | DynUnionHelper.narrow(Object obj)
static DynUnion | DynUnionHelper.read(InputStream istream)
static DynUnion | DynUnionHelper.unchecked_narrow(Object obj)

Methods in org.omg.DynamicAny with parameters of type DynUnion
static void | DynUnionHelper.insert(Any a, DynUnion that)
static void | DynUnionHelper.write(OutputStream ostream, DynUnion value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynUnionOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynUnionOperations

Packages that use DynUnionOperations
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynUnionOperations in org.omg.DynamicAny

Subinterfaces of DynUnionOperations in org.omg.DynamicAny
 interface DynUnion
DynUnion objects support the manipulation of IDL unions.

Classes in org.omg.DynamicAny that implement DynUnionOperations
 class _DynUnionStub
DynUnion objects support the manipulation of IDL unions.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynValue

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynValue

Packages that use DynValue
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynValue in org.omg.DynamicAny

Classes in org.omg.DynamicAny that implement DynValue
 class _DynValueStub
DynValue objects support the manipulation of IDL non-boxed value types.

Methods in org.omg.DynamicAny that return DynValue
static DynValue | DynValueHelper.extract(Any a)
static DynValue | DynValueHelper.narrow(Object obj)
static DynValue | DynValueHelper.read(InputStream istream)
static DynValue | DynValueHelper.unchecked_narrow(Object obj)

Methods in org.omg.DynamicAny with parameters of type DynValue
static void | DynValueHelper.insert(Any a, DynValue that)
static void | DynValueHelper.write(OutputStream ostream, DynValue value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynValueBox

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynValueBox

No usage of org.omg.DynamicAny.DynValueBox

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynValueBoxOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynValueBoxOperations

Packages that use DynValueBoxOperations
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynValueBoxOperations in org.omg.DynamicAny

Subinterfaces of DynValueBoxOperations in org.omg.DynamicAny
 interface DynValueBox
DynValueBox objects support the manipulation of IDL boxed value types.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynValueCommon

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynValueCommon

Packages that use DynValueCommon
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynValueCommon in org.omg.DynamicAny

Subinterfaces of DynValueCommon in org.omg.DynamicAny
interface | DynValue DynValue objects support the manipulation of IDL non-boxed value types.
interface | DynValueBox DynValueBox objects support the manipulation of IDL boxed value types.

Classes in org.omg.DynamicAny that implement DynValueCommon
 class _DynValueStub
DynValue objects support the manipulation of IDL non-boxed value types.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynValueCommonOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynValueCommonOperations

Packages that use DynValueCommonOperations
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynValueCommonOperations in org.omg.DynamicAny

Subinterfaces of DynValueCommonOperations in org.omg.DynamicAny
interface | DynValue DynValue objects support the manipulation of IDL non-boxed value types.
interface | DynValueBox DynValueBox objects support the manipulation of IDL boxed value types.
interface | DynValueBoxOperations DynValueBox objects support the manipulation of IDL boxed value types.
interface | DynValueCommon DynValueCommon provides operations supported by both the DynValue and DynValueBox interfaces.
interface | DynValueOperations DynValue objects support the manipulation of IDL non-boxed value types.

Classes in org.omg.DynamicAny that implement DynValueCommonOperations
 class _DynValueStub
DynValue objects support the manipulation of IDL non-boxed value types.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.DynamicAny.DynValueOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.DynamicAny.DynValueOperations

Packages that use DynValueOperations
org.omg.DynamicAny Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.

Uses of DynValueOperations in org.omg.DynamicAny

Subinterfaces of DynValueOperations in org.omg.DynamicAny
 interface DynValue
DynValue objects support the manipulation of IDL non-boxed value types.

Classes in org.omg.DynamicAny that implement DynValueOperations
 class _DynValueStub
DynValue objects support the manipulation of IDL non-boxed value types.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DynAnyFactoryHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class DynAnyFactoryHelper

java.lang.Object
    extended by  org.omg.DynamicAny.DynAnyFactoryHelper

public abstract class DynAnyFactoryHelper
extends Object

DynAny objects can be created by invoking operations on the DynAnyFactory object. Generally there are only two ways to create a DynAny object:

  • invoking an operation on an existing DynAny object
  • invoking an operation on a DynAnyFactory object
A constructed DynAny object supports operations that enable the creation of new DynAny objects encapsulating access to the value of some constituent. DynAny objects also support the copy operation for creating new DynAny objects. A reference to the DynAnyFactory object is obtained by calling ORB.resolve_initial_references() with the identifier parameter set to the string constant "DynAnyFactory".

Dynamic interpretation of an any usually involves creating a DynAny object using create_dyn_any() as the first step. Depending on the type of the any, the resulting DynAny object reference can be narrowed to a DynFixed, DynStruct, DynSequence, DynArray, DynUnion, DynEnum, or DynValue object reference.

Dynamic creation of an any involves creating a DynAny object using create_dyn_any_from_type_code(), passing the TypeCode associated with the value to be created. The returned reference is narrowed to one of the complex types, such as DynStruct, if appropriate. Then, the value can be initialized by means of invoking operations on the resulting object. Finally, the to_any operation can be invoked to create an any value from the constructed DynAny.

Constructor Summary
DynAnyFactoryHelper()
Method Summary
static DynAnyFactory | extract(Any a)
static String | id()
static void | insert(Any a, DynAnyFactory that)
static DynAnyFactory | narrow(Object obj)
static DynAnyFactory | read(InputStream istream)
static TypeCode | type()
static DynAnyFactory | unchecked_narrow(Object obj)
static void | write(OutputStream ostream, DynAnyFactory value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DynAnyFactoryHelper

public DynAnyFactoryHelper()
Method Detail

insert

public static void insert(Any a,
                          DynAnyFactory that)

extract

public static DynAnyFactory extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static DynAnyFactory read(InputStream istream)

write

public static void write(OutputStream ostream,
                         DynAnyFactory value)

narrow

public static DynAnyFactory narrow(Object obj)

unchecked_narrow

public static DynAnyFactory unchecked_narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynAnyFactoryOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynAnyFactoryOperations

All Known Subinterfaces:
DynAnyFactory
All Known Implementing Classes:
_DynAnyFactoryStub
public interface DynAnyFactoryOperations

DynAny objects can be created by invoking operations on the DynAnyFactory object. Generally there are only two ways to create a DynAny object:

  • invoking an operation on an existing DynAny object
  • invoking an operation on a DynAnyFactory object
A constructed DynAny object supports operations that enable the creation of new DynAny objects encapsulating access to the value of some constituent. DynAny objects also support the copy operation for creating new DynAny objects. A reference to the DynAnyFactory object is obtained by calling ORB.resolve_initial_references() with the identifier parameter set to the string constant "DynAnyFactory".

Dynamic interpretation of an any usually involves creating a DynAny object using create_dyn_any() as the first step. Depending on the type of the any, the resulting DynAny object reference can be narrowed to a DynFixed, DynStruct, DynSequence, DynArray, DynUnion, DynEnum, or DynValue object reference.

Dynamic creation of an any involves creating a DynAny object using create_dyn_any_from_type_code(), passing the TypeCode associated with the value to be created. The returned reference is narrowed to one of the complex types, such as DynStruct, if appropriate. Then, the value can be initialized by means of invoking operations on the resulting object. Finally, the to_any operation can be invoked to create an any value from the constructed DynAny.

Method Summary
DynAny | create_dyn_any_from_type_code(TypeCode type) Creates a DynAny from a TypeCode.
DynAny | create_dyn_any(Any value) Creates a new DynAny object from an any value.

Method Detail

create_dyn_any

DynAny create_dyn_any(Any value)
                      throws InconsistentTypeCode
Creates a new DynAny object from an any value. A copy of the TypeCode associated with the any value is assigned to the resulting DynAny object. The value associated with the DynAny object is a copy of the value in the original any. The current position of the created DynAny is set to zero if the passed value has components, to -1 otherwise

Throws:
InconsistentTypeCode - if value has a TypeCode with a TCKind of tk_Principal, tk_native, or tk_abstract_interface

create_dyn_any_from_type_code

DynAny create_dyn_any_from_type_code(TypeCode type)
                                     throws InconsistentTypeCode
Creates a DynAny from a TypeCode. Depending on the TypeCode, the created object may be of type DynAny, or one of its derived types, such as DynStruct. The returned reference can be narrowed to the derived type. In all cases, a DynAny constructed from a TypeCode has an initial default value. The default values of basic types are:
  • false for boolean
  • zero for numeric types
  • zero for types octet, char, and wchar
  • the empty string for string and wstring
  • null for object references
  • a type code with a TCKind value of tk_null for type codes
  • for any values, an any containing a type code with a TCKind value of tk_null type and no value
For complex types, creation of the corresponding DynAny assigns a default value as follows:
  • For DynSequence it sets the current position to -1 and creates an empty sequence.
  • For DynEnum it sets the current position to -1 and sets the value of the enumerator to the first enumerator value indicated by the TypeCode.
  • For DynFixed it sets the current position to -1 and sets the value zero.
  • For DynStruct it sets the current position to -1 for empty exceptions and to zero for all other TypeCodes. The members (if any) are (recursively) initialized to their default values.
  • For DynArray sets the current position to zero and (recursively) initializes elements to their default value.
  • For DynUnion sets the current position to zero. The discriminator value is set to a value consistent with the first named member of the union. That member is activated and (recursively) initialized to its default value.
  • For DynValue and DynValueBox it initializes to a null value.

Throws:
InconsistentTypeCode
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynAnyFactoryPackage

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.DynamicAny.DynAnyFactoryPackage

This package contains classes and exceptions from the DynAnyFactory interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.2.

See:
Description

Class Summary
InconsistentTypeCodeHelper org/omg/DynamicAny/DynAnyFactoryPackage/InconsistentTypeCodeHelper.java .

Exception Summary
InconsistentTypeCode org/omg/DynamicAny/DynAnyFactoryPackage/InconsistentTypeCode.java .

Package org.omg.DynamicAny.DynAnyFactoryPackage Description

This package contains classes and exceptions from the DynAnyFactory interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.2. Please refer to that OMG specification for further details.

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6 ORB complies, see Official Specifications for CORBA support in Java SE 6.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.DynamicAny.DynAnyFactoryPackage Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.DynamicAny.DynAnyFactoryPackage

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.DynamicAny.DynAnyFactoryPackage.InconsistentTypeCodeHelper
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.omg.CORBA.UserException (implements org.omg.CORBA.portable.IDLEntity)
          • org.omg.DynamicAny.DynAnyFactoryPackage.InconsistentTypeCode
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.DynamicAny.DynAnyFactoryPackage

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.DynamicAny.DynAnyFactoryPackage

Packages that use org.omg.DynamicAny.DynAnyFactoryPackage
org.omg.DynamicAny | Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.
org.omg.DynamicAny.DynAnyFactoryPackage | This package contains classes and exceptions from the DynAnyFactory interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.2.

Classes in org.omg.DynamicAny.DynAnyFactoryPackage used by org.omg.DynamicAny
InconsistentTypeCode
org/omg/DynamicAny/DynAnyFactoryPackage/InconsistentTypeCode.java .

Classes in org.omg.DynamicAny.DynAnyFactoryPackage used by org.omg.DynamicAny.DynAnyFactoryPackage
InconsistentTypeCode
org/omg/DynamicAny/DynAnyFactoryPackage/InconsistentTypeCode.java .

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.DynAnyFactoryPackage.InconsistentTypeCode

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.DynAnyFactoryPackage.InconsistentTypeCode

Packages that use InconsistentTypeCode
org.omg.DynamicAny | Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.
org.omg.DynamicAny.DynAnyFactoryPackage | This package contains classes and exceptions from the DynAnyFactory interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.2.

Uses of InconsistentTypeCode in org.omg.DynamicAny

Methods in org.omg.DynamicAny that throw InconsistentTypeCode
DynAny | _DynAnyFactoryStub.create_dyn_any_from_type_code(TypeCode type) Creates a DynAny from a TypeCode.
DynAny | DynAnyFactoryOperations.create_dyn_any_from_type_code(TypeCode type) Creates a DynAny from a TypeCode.
DynAny | _DynAnyFactoryStub.create_dyn_any(Any value) Creates a new DynAny object from an any value.
DynAny | DynAnyFactoryOperations.create_dyn_any(Any value) Creates a new DynAny object from an any value.

Uses of InconsistentTypeCode in org.omg.DynamicAny.DynAnyFactoryPackage

Methods in org.omg.DynamicAny.DynAnyFactoryPackage that return InconsistentTypeCode
static InconsistentTypeCode | InconsistentTypeCodeHelper.extract(Any a)
static InconsistentTypeCode | InconsistentTypeCodeHelper.read(InputStream istream)

Methods in org.omg.DynamicAny.DynAnyFactoryPackage with parameters of type InconsistentTypeCode
static void | InconsistentTypeCodeHelper.insert(Any a, InconsistentTypeCode that)
static void | InconsistentTypeCodeHelper.write(OutputStream ostream, InconsistentTypeCode value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.DynAnyFactoryPackage.InconsistentTypeCodeHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.DynAnyFactoryPackage.InconsistentTypeCodeHelper

No usage of org.omg.DynamicAny.DynAnyFactoryPackage.InconsistentTypeCodeHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


InconsistentTypeCode

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny.DynAnyFactoryPackage
Class InconsistentTypeCode

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.DynamicAny.DynAnyFactoryPackage.InconsistentTypeCode
All Implemented Interfaces:
Serializable, IDLEntity
public final class InconsistentTypeCode
extends UserException

org/omg/DynamicAny/DynAnyFactoryPackage/InconsistentTypeCode.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/DynamicAny/DynamicAny.idl Wednesday, November 29, 2006 1:57:30 AM GMT-08:00

Constructor Summary
InconsistentTypeCode()
InconsistentTypeCode(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InconsistentTypeCode

public InconsistentTypeCode()

InconsistentTypeCode

public InconsistentTypeCode(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


InconsistentTypeCodeHelper

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny.DynAnyFactoryPackage
Class InconsistentTypeCodeHelper

java.lang.Object
    extended by  org.omg.DynamicAny.DynAnyFactoryPackage.InconsistentTypeCodeHelper

public abstract class InconsistentTypeCodeHelper
extends Object

org/omg/DynamicAny/DynAnyFactoryPackage/InconsistentTypeCodeHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/DynamicAny/DynamicAny.idl Wednesday, November 29, 2006 1:57:30 AM GMT-08:00

Constructor Summary
InconsistentTypeCodeHelper()
Method Summary
static InconsistentTypeCode | extract(Any a)
static String | id()
static void | insert(Any a, InconsistentTypeCode that)
static InconsistentTypeCode | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, InconsistentTypeCode value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InconsistentTypeCodeHelper

public InconsistentTypeCodeHelper()
Method Detail

insert

public static void insert(Any a,
                          InconsistentTypeCode that)

extract

public static InconsistentTypeCode extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static InconsistentTypeCode read(InputStream istream)

write

public static void write(OutputStream ostream,
                         InconsistentTypeCode value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


DynAnyHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class DynAnyHelper

java.lang.Object
    extended by  org.omg.DynamicAny.DynAnyHelper

public abstract class DynAnyHelper
extends Object

Any values can be dynamically interpreted (traversed) and constructed through DynAny objects. A DynAny object is associated with a data value which corresponds to a copy of the value inserted into an any.

A DynAny object may be viewed as an ordered collection of component DynAnys. For DynAnys representing a basic type, such as long, or a type without components, such as an empty exception, the ordered collection of components is empty. Each DynAny object maintains the notion of a current position into its collection of component DynAnys. The current position is identified by an index value that runs from 0 to n-1, where n is the number of components. The special index value -1 indicates a current position that points nowhere. For values that cannot have a current position (such as an empty exception), the index value is fixed at -1. If a DynAny is initialized with a value that has components, the index is initialized to 0. After creation of an uninitialized DynAny (that is, a DynAny that has no value but a TypeCode that permits components), the current position depends on the type of value represented by the DynAny. (The current position is set to 0 or -1, depending on whether the new DynAny gets default values for its components.)

The iteration operations rewind, seek, and next can be used to change the current position and the current_component operation returns the component at the current position. The component_count operation returns the number of components of a DynAny. Collectively, these operations enable iteration over the components of a DynAny, for example, to (recursively) examine its contents.

A constructed DynAny object is a DynAny object associated with a constructed type. There is a different interface, inheriting from the DynAny interface, associated with each kind of constructed type in IDL (fixed, enum, struct, sequence, union, array, exception, and value type).

A constructed DynAny object exports operations that enable the creation of new DynAny objects, each of them associated with a component of the constructed data value. As an example, a DynStruct is associated with a struct value. This means that the DynStruct may be seen as owning an ordered collection of components, one for each structure member. The DynStruct object exports operations that enable the creation of new DynAny objects, each of them associated with a member of the struct.

If a DynAny object has been obtained from another (constructed) DynAny object, such as a DynAny representing a structure member that was created from a DynStruct, the member DynAny is logically contained in the DynStruct. Calling an insert or get operation leaves the current position unchanged. Destroying a top-level DynAny object (one that was not obtained as a component of another DynAny) also destroys any component DynAny objects obtained from it. Destroying a non-top level DynAny object does nothing. Invoking operations on a destroyed top-level DynAny or any of its descendants raises OBJECT_NOT_EXIST. If the programmer wants to destroy a DynAny object but still wants to manipulate some component of the data value associated with it, then he or she should first create a DynAny for the component and, after that, make a copy of the created DynAny object.

The behavior of DynAny objects has been defined in order to enable efficient implementations in terms of allocated memory space and speed of access. DynAny objects are intended to be used for traversing values extracted from anys or constructing values of anys at runtime. Their use for other purposes is not recommended.

Insert and get operations are necessary to handle basic DynAny objects but are also helpful to handle constructed DynAny objects. Inserting a basic data type value into a constructed DynAny object implies initializing the current component of the constructed data value associated with the DynAny object. For example, invoking insert_boolean on a DynStruct implies inserting a boolean data value at the current position of the associated struct data value. A type is consistent for inserting or extracting a value if its TypeCode is equivalent to the TypeCode contained in the DynAny or, if the DynAny has components, is equivalent to the TypeCode of the DynAny at the current position.

DynAny and DynAnyFactory objects are intended to be local to the process in which they are created and used. This means that references to DynAny and DynAnyFactory objects cannot be exported to other processes, or externalized with ORB.object_to_string(). If any attempt is made to do so, the offending operation will raise a MARSHAL system exception. Since their interfaces are specified in IDL, DynAny objects export operations defined in the standard org.omg.CORBA.Object interface. However, any attempt to invoke operations exported through the Object interface may raise the standard NO_IMPLEMENT exception. An attempt to use a DynAny object with the DII may raise the NO_IMPLEMENT exception.

Constructor Summary
DynAnyHelper()
Method Summary
static DynAny | extract(Any a)
static String | id()
static void | insert(Any a, DynAny that)
static DynAny | narrow(Object obj)
static DynAny | read(InputStream istream)
static TypeCode | type()
static DynAny | unchecked_narrow(Object obj)
static void | write(OutputStream ostream, DynAny value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DynAnyHelper

public DynAnyHelper()
Method Detail

insert

public static void insert(Any a,
                          DynAny that)

extract

public static DynAny extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static DynAny read(InputStream istream)

write

public static void write(OutputStream ostream,
                         DynAny value)

narrow

public static DynAny narrow(Object obj)

unchecked_narrow

public static DynAny unchecked_narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynAnyOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynAnyOperations

All Known Subinterfaces:
DynAny, DynArray, DynArrayOperations, DynEnum, DynEnumOperations, DynFixed, DynFixedOperations, DynSequence, DynSequenceOperations, DynStruct, DynStructOperations, DynUnion, DynUnionOperations, DynValue, DynValueBox, DynValueBoxOperations, DynValueCommon, DynValueCommonOperations, DynValueOperations
All Known Implementing Classes:
_DynAnyStub, _DynArrayStub, _DynEnumStub, _DynFixedStub, _DynSequenceStub, _DynStructStub, _DynUnionStub, _DynValueStub
public interface DynAnyOperations

Any values can be dynamically interpreted (traversed) and constructed through DynAny objects. A DynAny object is associated with a data value which corresponds to a copy of the value inserted into an any.

A DynAny object may be viewed as an ordered collection of component DynAnys. For DynAnys representing a basic type, such as long, or a type without components, such as an empty exception, the ordered collection of components is empty. Each DynAny object maintains the notion of a current position into its collection of component DynAnys. The current position is identified by an index value that runs from 0 to n-1, where n is the number of components. The special index value -1 indicates a current position that points nowhere. For values that cannot have a current position (such as an empty exception), the index value is fixed at -1. If a DynAny is initialized with a value that has components, the index is initialized to 0. After creation of an uninitialized DynAny (that is, a DynAny that has no value but a TypeCode that permits components), the current position depends on the type of value represented by the DynAny. (The current position is set to 0 or -1, depending on whether the new DynAny gets default values for its components.)

The iteration operations rewind, seek, and next can be used to change the current position and the current_component operation returns the component at the current position. The component_count operation returns the number of components of a DynAny. Collectively, these operations enable iteration over the components of a DynAny, for example, to (recursively) examine its contents.

A constructed DynAny object is a DynAny object associated with a constructed type. There is a different interface, inheriting from the DynAny interface, associated with each kind of constructed type in IDL (fixed, enum, struct, sequence, union, array, exception, and value type).

A constructed DynAny object exports operations that enable the creation of new DynAny objects, each of them associated with a component of the constructed data value. As an example, a DynStruct is associated with a struct value. This means that the DynStruct may be seen as owning an ordered collection of components, one for each structure member. The DynStruct object exports operations that enable the creation of new DynAny objects, each of them associated with a member of the struct.

If a DynAny object has been obtained from another (constructed) DynAny object, such as a DynAny representing a structure member that was created from a DynStruct, the member DynAny is logically contained in the DynStruct. Calling an insert or get operation leaves the current position unchanged. Destroying a top-level DynAny object (one that was not obtained as a component of another DynAny) also destroys any component DynAny objects obtained from it. Destroying a non-top level DynAny object does nothing. Invoking operations on a destroyed top-level DynAny or any of its descendants raises OBJECT_NOT_EXIST. If the programmer wants to destroy a DynAny object but still wants to manipulate some component of the data value associated with it, then he or she should first create a DynAny for the component and, after that, make a copy of the created DynAny object.

The behavior of DynAny objects has been defined in order to enable efficient implementations in terms of allocated memory space and speed of access. DynAny objects are intended to be used for traversing values extracted from anys or constructing values of anys at runtime. Their use for other purposes is not recommended.

Insert and get operations are necessary to handle basic DynAny objects but are also helpful to handle constructed DynAny objects. Inserting a basic data type value into a constructed DynAny object implies initializing the current component of the constructed data value associated with the DynAny object. For example, invoking insert_boolean on a DynStruct implies inserting a boolean data value at the current position of the associated struct data value. A type is consistent for inserting or extracting a value if its TypeCode is equivalent to the TypeCode contained in the DynAny or, if the DynAny has components, is equivalent to the TypeCode of the DynAny at the current position.

DynAny and DynAnyFactory objects are intended to be local to the process in which they are created and used. This means that references to DynAny and DynAnyFactory objects cannot be exported to other processes, or externalized with ORB.object_to_string(). If any attempt is made to do so, the offending operation will raise a MARSHAL system exception. Since their interfaces are specified in IDL, DynAny objects export operations defined in the standard org.omg.CORBA.Object interface. However, any attempt to invoke operations exported through the Object interface may raise the standard NO_IMPLEMENT exception. An attempt to use a DynAny object with the DII may raise the NO_IMPLEMENT exception.

Method Summary
 void assign(DynAny dyn_any)
Initializes the value associated with a DynAny object with the value associated with another DynAny object.
 int component_count()
Returns the number of components of a DynAny.
 DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked.
 DynAny current_component()
Returns the DynAny for the component at the current position.
 void destroy()
Destroys a DynAny object.
 boolean equal(DynAny dyn_any)
Compares two DynAny values for equality.
 void from_any(Any value)
Initializes the value associated with a DynAny object with the value contained in an any.
 Any get_any()
Extracts an Any value contained in the Any represented by this DynAny.
 boolean get_boolean()
Extracts the boolean value from this DynAny.
 char get_char()
Extracts the char value from this DynAny.
 double get_double()
Extracts the double value from this DynAny.
 DynAny get_dyn_any()
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
 float get_float()
Extracts the float value from this DynAny.
 int get_long()
Extracts the integer value from this DynAny.
 long get_longlong()
Extracts the long value from this DynAny.
 byte get_octet()
Extracts the byte value from this DynAny.
 Object get_reference()
Extracts the reference to a CORBA Object from this DynAny.
 short get_short()
Extracts the short value from this DynAny.
 String get_string()
Extracts the string value from this DynAny.
 TypeCode get_typecode()
Extracts the TypeCode object from this DynAny.
 int get_ulong()
Extracts the integer value from this DynAny.
 long get_ulonglong()
Extracts the long value from this DynAny.
 short get_ushort()
Extracts the short value from this DynAny.
 Serializable get_val()
Extracts a Serializable object from this DynAny.
 char get_wchar()
Extracts the long value from this DynAny.
 String get_wstring()
Extracts the string value from this DynAny.
 void insert_any(Any value)
Inserts an Any value into the Any represented by this DynAny.
 void insert_boolean(boolean value)
Inserts a boolean value into the DynAny.
 void insert_char(char value)
Inserts a char value into the DynAny.
 void insert_double(double value)
Inserts a double value into the DynAny.
 void insert_dyn_any(DynAny value)
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
 void insert_float(float value)
Inserts a float value into the DynAny.
 void insert_long(int value)
Inserts an integer value into the DynAny.
 void insert_longlong(long value)
Inserts a long value into the DynAny.
 void insert_octet(byte value)
Inserts a byte value into the DynAny.
 void insert_reference(Object value)
Inserts a reference to a CORBA object into the DynAny.
 void insert_short(short value)
Inserts a short value into the DynAny.
 void insert_string(String value)
Inserts a string value into the DynAny.
 void insert_typecode(TypeCode value)
Inserts a TypeCode object into the DynAny.
 void insert_ulong(int value)
Inserts an integer value into the DynAny.
 void insert_ulonglong(long value)
Inserts a long value into the DynAny.
 void insert_ushort(short value)
Inserts a short value into the DynAny.
 void insert_val(Serializable value)
Inserts a reference to a Serializable object into this DynAny.
 void insert_wchar(char value)
Inserts a char value into the DynAny.
 void insert_wstring(String value)
Inserts a string value into the DynAny.
 boolean next()
Advances the current position to the next component.
 void rewind()
Is equivalent to seek(0).
 boolean seek(int index)
Sets the current position to index.
 Any to_any()
Creates an any value from a DynAny object.
 TypeCode type()
Returns the TypeCode associated with this DynAny object.

Method Detail

type

TypeCode type()
Returns the TypeCode associated with this DynAny object. A DynAny object is created with a TypeCode value assigned to it. This TypeCode value determines the type of the value handled through the DynAny object. Note that the TypeCode associated with a DynAny object is initialized at the time the DynAny is created and cannot be changed during lifetime of the DynAny object.

Returns:
The TypeCode associated with this DynAny object

assign

void assign(DynAny dyn_any)
            throws TypeMismatch
Initializes the value associated with a DynAny object with the value associated with another DynAny object. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Parameters:
dyn_any -
Throws:
TypeMismatch - if the type of the passed DynAny is not equivalent to the type of target DynAny

from_any

void from_any(Any value)
              throws TypeMismatch,
                     InvalidValue
Initializes the value associated with a DynAny object with the value contained in an any. The current position of the target DynAny is set to zero for values that have components and to -1 for values that do not have components.

Throws:
TypeMismatch - if the type of the passed Any is not equivalent to the type of target DynAny
InvalidValue - if the passed Any does not contain a legal value (such as a null string)

to_any

Any to_any()
Creates an any value from a DynAny object. A copy of the TypeCode associated with the DynAny object is assigned to the resulting any. The value associated with the DynAny object is copied into the any.

Returns:
a new Any object with the same value and TypeCode

equal

boolean equal(DynAny dyn_any)
Compares two DynAny values for equality. Two DynAny values are equal if their TypeCodes are equivalent and, recursively, all component DynAnys have equal values. The current position of the two DynAnys being compared has no effect on the result of equal.

Returns:
true of the DynAnys are equal, false otherwise

destroy

void destroy()
Destroys a DynAny object. This operation frees any resources used to represent the data value associated with a DynAny object. It must be invoked on references obtained from one of the creation operations on the ORB interface or on a reference returned by DynAny.copy() to avoid resource leaks. Invoking destroy on component DynAny objects (for example, on objects returned by the current_component operation) does nothing. Destruction of a DynAny object implies destruction of all DynAny objects obtained from it. That is, references to components of a destroyed DynAny become invalid. Invocations on such references raise OBJECT_NOT_EXIST. It is possible to manipulate a component of a DynAny beyond the life time of the DynAny from which the component was obtained by making a copy of the component with the copy operation before destroying the DynAny from which the component was obtained.

copy

DynAny copy()
Creates a new DynAny object whose value is a deep copy of the DynAny on which it is invoked. The operation is polymorphic, that is, invoking it on one of the types derived from DynAny, such as DynStruct, creates the derived type but returns its reference as the DynAny base type.

Returns:
a deep copy of the DynAny object

insert_boolean

void insert_boolean(boolean value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a boolean value into the DynAny.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_octet

void insert_octet(byte value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a byte value into the DynAny. The IDL octet data type is mapped to the Java byte data type.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_char

void insert_char(char value)
                 throws TypeMismatch,
                        InvalidValue
Inserts a char value into the DynAny.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_short

void insert_short(short value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a short value into the DynAny.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ushort

void insert_ushort(short value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a short value into the DynAny. The IDL ushort data type is mapped to the Java short data type.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_long

void insert_long(int value)
                 throws TypeMismatch,
                        InvalidValue
Inserts an integer value into the DynAny. The IDL long data type is mapped to the Java int data type.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulong

void insert_ulong(int value)
                  throws TypeMismatch,
                         InvalidValue
Inserts an integer value into the DynAny. The IDL ulong data type is mapped to the Java int data type.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_float

void insert_float(float value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a float value into the DynAny.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_double

void insert_double(double value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a double value into the DynAny.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_string

void insert_string(String value)
                   throws TypeMismatch,
                          InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch - if called on a DynAny whose current component itself has components

insert_reference

void insert_reference(Object value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a reference to a CORBA object into the DynAny.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_typecode

void insert_typecode(TypeCode value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a TypeCode object into the DynAny.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_longlong

void insert_longlong(long value)
                     throws TypeMismatch,
                            InvalidValue
Inserts a long value into the DynAny. The IDL long long data type is mapped to the Java long data type.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_ulonglong

void insert_ulonglong(long value)
                      throws TypeMismatch,
                             InvalidValue
Inserts a long value into the DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wchar

void insert_wchar(char value)
                  throws TypeMismatch,
                         InvalidValue
Inserts a char value into the DynAny. The IDL wchar data type is mapped to the Java char data type.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_wstring

void insert_wstring(String value)
                    throws TypeMismatch,
                           InvalidValue
Inserts a string value into the DynAny. Both bounded and unbounded strings are inserted using this method.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
InvalidValue - if the string inserted is longer than the bound of a bounded string
TypeMismatch

insert_any

void insert_any(Any value)
                throws TypeMismatch,
                       InvalidValue
Inserts an Any value into the Any represented by this DynAny.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_dyn_any

void insert_dyn_any(DynAny value)
                    throws TypeMismatch,
                           InvalidValue
Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

insert_val

void insert_val(Serializable value)
                throws TypeMismatch,
                       InvalidValue
Inserts a reference to a Serializable object into this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Throws:
InvalidValue - if this DynAny has components but has a current position of -1
TypeMismatch - if called on a DynAny whose current component itself has components

get_boolean

boolean get_boolean()
                    throws TypeMismatch,
                           InvalidValue
Extracts the boolean value from this DynAny.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_octet

byte get_octet()
               throws TypeMismatch,
                      InvalidValue
Extracts the byte value from this DynAny. The IDL octet data type is mapped to the Java byte data type.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_char

char get_char()
              throws TypeMismatch,
                     InvalidValue
Extracts the char value from this DynAny.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_short

short get_short()
                throws TypeMismatch,
                       InvalidValue
Extracts the short value from this DynAny.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ushort

short get_ushort()
                 throws TypeMismatch,
                        InvalidValue
Extracts the short value from this DynAny. The IDL ushort data type is mapped to the Java short data type.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_long

int get_long()
             throws TypeMismatch,
                    InvalidValue
Extracts the integer value from this DynAny. The IDL long data type is mapped to the Java int data type.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulong

int get_ulong()
              throws TypeMismatch,
                     InvalidValue
Extracts the integer value from this DynAny. The IDL ulong data type is mapped to the Java int data type.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_float

float get_float()
                throws TypeMismatch,
                       InvalidValue
Extracts the float value from this DynAny.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_double

double get_double()
                  throws TypeMismatch,
                         InvalidValue
Extracts the double value from this DynAny.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_string

String get_string()
                  throws TypeMismatch,
                         InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_reference

Object get_reference()
                     throws TypeMismatch,
                            InvalidValue
Extracts the reference to a CORBA Object from this DynAny.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_typecode

TypeCode get_typecode()
                      throws TypeMismatch,
                             InvalidValue
Extracts the TypeCode object from this DynAny.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_longlong

long get_longlong()
                  throws TypeMismatch,
                         InvalidValue
Extracts the long value from this DynAny. The IDL long long data type is mapped to the Java long data type.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_ulonglong

long get_ulonglong()
                   throws TypeMismatch,
                          InvalidValue
Extracts the long value from this DynAny. The IDL unsigned long long data type is mapped to the Java long data type.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wchar

char get_wchar()
               throws TypeMismatch,
                      InvalidValue
Extracts the long value from this DynAny. The IDL wchar data type is mapped to the Java char data type.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_wstring

String get_wstring()
                   throws TypeMismatch,
                          InvalidValue
Extracts the string value from this DynAny. Both bounded and unbounded strings are extracted using this method.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue

get_any

Any get_any()
            throws TypeMismatch,
                   InvalidValue
Extracts an Any value contained in the Any represented by this DynAny.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_dyn_any

DynAny get_dyn_any()
                   throws TypeMismatch,
                          InvalidValue
Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

get_val

Serializable get_val()
                     throws TypeMismatch,
                            InvalidValue
Extracts a Serializable object from this DynAny. The IDL ValueBase type is mapped to the Java Serializable type.

Throws:
TypeMismatch - if the accessed component in the DynAny is of a type that is not equivalent to the requested type.
TypeMismatch - if called on a DynAny whose current component itself has components
InvalidValue - if this DynAny has components but has a current position of -1

seek

boolean seek(int index)
Sets the current position to index. The current position is indexed 0 to n-1, that is, index zero corresponds to the first component. The operation returns true if the resulting current position indicates a component of the DynAny and false if index indicates a position that does not correspond to a component. Calling seek with a negative index is legal. It sets the current position to -1 to indicate no component and returns false. Passing a non-negative index value for a DynAny that does not have a component at the corresponding position sets the current position to -1 and returns false.

rewind

void rewind()
Is equivalent to seek(0).

next

boolean next()
Advances the current position to the next component. The operation returns true while the resulting current position indicates a component, false otherwise. A false return value leaves the current position at -1. Invoking next on a DynAny without components leaves the current position at -1 and returns false.

component_count

int component_count()
Returns the number of components of a DynAny. For a DynAny without components, it returns zero. The operation only counts the components at the top level. For example, if component_count is invoked on a DynStruct with a single member, the return value is 1, irrespective of the type of the member.
  • For sequences, the operation returns the current number of elements.
  • For structures, exceptions, and value types, the operation returns the number of members.
  • For arrays, the operation returns the number of elements.
  • For unions, the operation returns 2 if the discriminator indicates that a named member is active, otherwise, it returns 1.
  • For DynFixed and DynEnum, the operation returns zero.

current_component

DynAny current_component()
                         throws TypeMismatch
Returns the DynAny for the component at the current position. It does not advance the current position, so repeated calls to current_component without an intervening call to rewind, next, or seek return the same component. The returned DynAny object reference can be used to get/set the value of the current component. If the current component represents a complex type, the returned reference can be narrowed based on the TypeCode to get the interface corresponding to the to the complex type. Calling current_component on a DynAny that cannot have components, such as a DynEnum or an empty exception, raises TypeMismatch. Calling current_component on a DynAny whose current position is -1 returns a nil reference. The iteration operations, together with current_component, can be used to dynamically compose an any value. After creating a dynamic any, such as a DynStruct, current_component and next can be used to initialize all the components of the value. Once the dynamic value is completely initialized, to_any creates the corresponding any value.

Throws:
TypeMismatch - If called on a DynAny that cannot have components, such as a DynEnum or an empty exception
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynAnyPackage

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.DynamicAny.DynAnyPackage

This package contains classes and exceptions from the DynAny interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.

See:
Description

Class Summary
InvalidValueHelper | org/omg/DynamicAny/DynAnyPackage/InvalidValueHelper.java .
TypeMismatchHelper | org/omg/DynamicAny/DynAnyPackage/TypeMismatchHelper.java .

Exception Summary
InvalidValue | org/omg/DynamicAny/DynAnyPackage/InvalidValue.java .
TypeMismatch | org/omg/DynamicAny/DynAnyPackage/TypeMismatch.java .

Package org.omg.DynamicAny.DynAnyPackage Description

This package contains classes and exceptions from the DynAny interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2. Please refer to that OMG specification for further details.

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6 ORB complies, see Official Specifications for CORBA support in Java[tm] SE 6.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.DynamicAny.DynAnyPackage Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.DynamicAny.DynAnyPackage

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.DynamicAny.DynAnyPackage.InvalidValueHelper
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.omg.CORBA.UserException (implements org.omg.CORBA.portable.IDLEntity)
          • org.omg.DynamicAny.DynAnyPackage.InvalidValue
          • org.omg.DynamicAny.DynAnyPackage.TypeMismatch
    • org.omg.DynamicAny.DynAnyPackage.TypeMismatchHelper
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.DynamicAny.DynAnyPackage

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.DynamicAny.DynAnyPackage

Packages that use org.omg.DynamicAny.DynAnyPackage
org.omg.DynamicAny | Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.
org.omg.DynamicAny.DynAnyPackage | This package contains classes and exceptions from the DynAny interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.

Classes in org.omg.DynamicAny.DynAnyPackage used by org.omg.DynamicAny
InvalidValue
org/omg/DynamicAny/DynAnyPackage/InvalidValue.java .
TypeMismatch
org/omg/DynamicAny/DynAnyPackage/TypeMismatch.java .

Classes in org.omg.DynamicAny.DynAnyPackage used by org.omg.DynamicAny.DynAnyPackage
InvalidValue
org/omg/DynamicAny/DynAnyPackage/InvalidValue.java .
TypeMismatch
org/omg/DynamicAny/DynAnyPackage/TypeMismatch.java .

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.DynAnyPackage.InvalidValue

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.DynAnyPackage.InvalidValue

Packages that use InvalidValue
org.omg.DynamicAny | Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.
org.omg.DynamicAny.DynAnyPackage | This package contains classes and exceptions from the DynAny interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.

Uses of InvalidValue in org.omg.DynamicAny

Methods in org.omg.DynamicAny that throw InvalidValue
TCKind | _DynValueStub.current_member_kind() Returns the TCKind associated with the member at the current position.
TCKind | _DynStructStub.current_member_kind() Returns the TCKind associated with the member at the current position.
TCKind | DynValueOperations.current_member_kind() Returns the TCKind associated with the member at the current position.
TCKind | DynStructOperations.current_member_kind() Returns the TCKind associated with the member at the current position.
String | _DynValueStub.current_member_name() Returns the name of the member at the current position.
String | _DynStructStub.current_member_name() Returns the name of the member at the current position.
String | DynValueOperations.current_member_name() Returns the name of the member at the current position.
String | DynStructOperations.current_member_name() Returns the name of the member at the current position.
void | _DynSequenceStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynFixedStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynEnumStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynArrayStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynValueStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynAnyStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynUnionStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynStructStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | DynAnyOperations.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
Any | _DynSequenceStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynFixedStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynEnumStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynArrayStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynValueStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynAnyStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynUnionStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynStructStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | DynAnyOperations.get_any() Extracts an Any value contained in the Any represented by this DynAny.
boolean | _DynSequenceStub.get_boolean() Extracts the boolean value from this DynAny.
boolean | _DynFixedStub.get_boolean() Extracts the boolean value from this DynAny.
boolean | _DynEnumStub.get_boolean() Extracts the boolean value from this DynAny.
boolean | _DynArrayStub.get_boolean() Extracts the boolean value from this DynAny.
boolean | _DynValueStub.get_boolean() Extracts the boolean value from this DynAny.
boolean | _DynAnyStub.get_boolean() Extracts the boolean value from this DynAny.
boolean | _DynUnionStub.get_boolean() Extracts the boolean value from this DynAny.
boolean | _DynStructStub.get_boolean() Extracts the boolean value from this DynAny.
boolean | DynAnyOperations.get_boolean() Extracts the boolean value from this DynAny.
DynAny | DynValueBoxOperations.get_boxed_value_as_dyn_any() Returns the boxed value as a DynAny.
Any | DynValueBoxOperations.get_boxed_value() Returns the boxed value as an Any.
char | _DynSequenceStub.get_char() Extracts the char value from this DynAny.
char | _DynFixedStub.get_char() Extracts the char value from this DynAny.
char | _DynEnumStub.get_char() Extracts the char value from this DynAny.
char | _DynArrayStub.get_char() Extracts the char value from this DynAny.
char | _DynValueStub.get_char() Extracts the char value from this DynAny.
char | _DynAnyStub.get_char() Extracts the char value from this DynAny.
char | _DynUnionStub.get_char() Extracts the char value from this DynAny.
char | _DynStructStub.get_char() Extracts the char value from this DynAny.
char | DynAnyOperations.get_char() Extracts the char value from this DynAny.
double | _DynSequenceStub.get_double() Extracts the double value from this DynAny.
double | _DynFixedStub.get_double() Extracts the double value from this DynAny.
double | _DynEnumStub.get_double() Extracts the double value from this DynAny.
double | _DynArrayStub.get_double() Extracts the double value from this DynAny.
double | _DynValueStub.get_double() Extracts the double value from this DynAny.
double | _DynAnyStub.get_double() Extracts the double value from this DynAny.
double | _DynUnionStub.get_double() Extracts the double value from this DynAny.
double | _DynStructStub.get_double() Extracts the double value from this DynAny.
double | DynAnyOperations.get_double() Extracts the double value from this DynAny.
DynAny | _DynSequenceStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynFixedStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynEnumStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynArrayStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynValueStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynAnyStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynUnionStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynStructStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | DynAnyOperations.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
float | _DynSequenceStub.get_float() Extracts the float value from this DynAny.
float | _DynFixedStub.get_float() Extracts the float value from this DynAny.
float | _DynEnumStub.get_float() Extracts the float value from this DynAny.
float | _DynArrayStub.get_float() Extracts the float value from this DynAny.
float | _DynValueStub.get_float() Extracts the float value from this DynAny.
float | _DynAnyStub.get_float() Extracts the float value from this DynAny.
float | _DynUnionStub.get_float() Extracts the float value from this DynAny.
float | _DynStructStub.get_float() Extracts the float value from this DynAny.
float | DynAnyOperations.get_float() Extracts the float value from this DynAny.
int | _DynSequenceStub.get_long() Extracts the integer value from this DynAny.
int | _DynFixedStub.get_long() Extracts the integer value from this DynAny.
int | _DynEnumStub.get_long() Extracts the integer value from this DynAny.
int | _DynArrayStub.get_long() Extracts the integer value from this DynAny.
int | _DynValueStub.get_long() Extracts the integer value from this DynAny.
int | _DynAnyStub.get_long() Extracts the integer value from this DynAny.
int | _DynUnionStub.get_long() Extracts the integer value from this DynAny.
int | _DynStructStub.get_long() Extracts the integer value from this DynAny.
int | DynAnyOperations.get_long() Extracts the integer value from this DynAny.
long | _DynSequenceStub.get_longlong() Extracts the long value from this DynAny.
long | _DynFixedStub.get_longlong() Extracts the long value from this DynAny.
long | _DynEnumStub.get_longlong() Extracts the long value from this DynAny.
long | _DynArrayStub.get_longlong() Extracts the long value from this DynAny.
long | _DynValueStub.get_longlong() Extracts the long value from this DynAny.
long | _DynAnyStub.get_longlong() Extracts the long value from this DynAny.
long | _DynUnionStub.get_longlong() Extracts the long value from this DynAny.
long | _DynStructStub.get_longlong() Extracts the long value from this DynAny.
long | DynAnyOperations.get_longlong() Extracts the long value from this DynAny.
NameDynAnyPair[] | _DynValueStub.get_members_as_dyn_any() Returns a sequence of NameDynAnyPairs describing the name and the value of each member in the value type.
NameDynAnyPair[] | DynValueOperations.get_members_as_dyn_any() Returns a sequence of NameDynAnyPairs describing the name and the value of each member in the value type.
NameValuePair[] | _DynValueStub.get_members() Returns a sequence of NameValuePairs describing the name and the value of each member in the value type.
NameValuePair[] | DynValueOperations.get_members() Returns a sequence of NameValuePairs describing the name and the value of each member in the value type.
byte | _DynSequenceStub.get_octet() Extracts the byte value from this DynAny.
byte | _DynFixedStub.get_octet() Extracts the byte value from this DynAny.
byte | _DynEnumStub.get_octet() Extracts the byte value from this DynAny.
byte | _DynArrayStub.get_octet() Extracts the byte value from this DynAny.
byte | _DynValueStub.get_octet() Extracts the byte value from this DynAny.
byte | _DynAnyStub.get_octet() Extracts the byte value from this DynAny.
byte | _DynUnionStub.get_octet() Extracts the byte value from this DynAny.
byte | _DynStructStub.get_octet() Extracts the byte value from this DynAny.
byte | DynAnyOperations.get_octet() Extracts the byte value from this DynAny.
Object | _DynSequenceStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynFixedStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynEnumStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynArrayStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynValueStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynAnyStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynUnionStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynStructStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | DynAnyOperations.get_reference() Extracts the reference to a CORBA Object from this DynAny.
short | _DynSequenceStub.get_short() Extracts the short value from this DynAny.
short | _DynFixedStub.get_short() Extracts the short value from this DynAny.
short | _DynEnumStub.get_short() Extracts the short value from this DynAny.
short | _DynArrayStub.get_short() Extracts the short value from this DynAny.
short | _DynValueStub.get_short() Extracts the short value from this DynAny.
short | _DynAnyStub.get_short() Extracts the short value from this DynAny.
short | _DynUnionStub.get_short() Extracts the short value from this DynAny.
short | _DynStructStub.get_short() Extracts the short value from this DynAny.
short | DynAnyOperations.get_short() Extracts the short value from this DynAny.
String | _DynSequenceStub.get_string() Extracts the string value from this DynAny.
String | _DynFixedStub.get_string() Extracts the string value from this DynAny.
String | _DynEnumStub.get_string() Extracts the string value from this DynAny.
String | _DynArrayStub.get_string() Extracts the string value from this DynAny.
String | _DynValueStub.get_string() Extracts the string value from this DynAny.
String | _DynAnyStub.get_string() Extracts the string value from this DynAny.
String | _DynUnionStub.get_string() Extracts the string value from this DynAny.
String | _DynStructStub.get_string() Extracts the string value from this DynAny.
String | DynAnyOperations.get_string() Extracts the string value from this DynAny.
TypeCode | _DynSequenceStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynFixedStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynEnumStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynArrayStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynValueStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynAnyStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynUnionStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynStructStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | DynAnyOperations.get_typecode() Extracts the TypeCode object from this DynAny.
int | _DynSequenceStub.get_ulong() Extracts the integer value from this DynAny.
int | _DynFixedStub.get_ulong() Extracts the integer value from this DynAny.
int | _DynEnumStub.get_ulong() Extracts the integer value from this DynAny.
int | _DynArrayStub.get_ulong() Extracts the integer value from this DynAny.
int | _DynValueStub.get_ulong() Extracts the integer value from this DynAny.
int | _DynAnyStub.get_ulong() Extracts the integer value from this DynAny.
int | _DynUnionStub.get_ulong() Extracts the integer value from this DynAny.
int | _DynStructStub.get_ulong() Extracts the integer value from this DynAny.
int | DynAnyOperations.get_ulong() Extracts the integer value from this DynAny.
long | _DynSequenceStub.get_ulonglong() Extracts the long value from this DynAny.
long | _DynFixedStub.get_ulonglong() Extracts the long value from this DynAny.
long | _DynEnumStub.get_ulonglong() Extracts the long value from this DynAny.
long | _DynArrayStub.get_ulonglong() Extracts the long value from this DynAny.
long | _DynValueStub.get_ulonglong() Extracts the long value from this DynAny.
long | _DynAnyStub.get_ulonglong() Extracts the long value from this DynAny.
long | _DynUnionStub.get_ulonglong() Extracts the long value from this DynAny.
long | _DynStructStub.get_ulonglong() Extracts the long value from this DynAny.
long | DynAnyOperations.get_ulonglong() Extracts the long value from this DynAny.
short | _DynSequenceStub.get_ushort() Extracts the short value from this DynAny.
short | _DynFixedStub.get_ushort() Extracts the short value from this DynAny.
short | _DynEnumStub.get_ushort() Extracts the short value from this DynAny.
short | _DynArrayStub.get_ushort() Extracts the short value from this DynAny.
short | _DynValueStub.get_ushort() Extracts the short value from this DynAny.
short | _DynAnyStub.get_ushort() Extracts the short value from this DynAny.
short | _DynUnionStub.get_ushort() Extracts the short value from this DynAny.
short | _DynStructStub.get_ushort() Extracts the short value from this DynAny.
short | DynAnyOperations.get_ushort() Extracts the short value from this DynAny.
Serializable | _DynSequenceStub.get_val() Extracts a Serializable object from this DynAny.
Serializable | _DynFixedStub.get_val() Extracts a Serializable object from this DynAny.
Serializable | _DynEnumStub.get_val() Extracts a Serializable object from this DynAny.
Serializable | _DynArrayStub.get_val() Extracts a Serializable object from this DynAny.
Serializable | _DynValueStub.get_val() Extracts a Serializable object from this DynAny.
Serializable | _DynAnyStub.get_val() Extracts a Serializable object from this DynAny.
Serializable | _DynUnionStub.get_val() Extracts a Serializable object from this DynAny.
Serializable | _DynStructStub.get_val() Extracts a Serializable object from this DynAny.
Serializable | DynAnyOperations.get_val() Extracts a Serializable object from this DynAny.
char | _DynSequenceStub.get_wchar() Extracts the long value from this DynAny.
char | _DynFixedStub.get_wchar() Extracts the long value from this DynAny.
char | _DynEnumStub.get_wchar() Extracts the long value from this DynAny.
char | _DynArrayStub.get_wchar() Extracts the long value from this DynAny.
char | _DynValueStub.get_wchar() Extracts the long value from this DynAny.
char | _DynAnyStub.get_wchar() Extracts the long value from this DynAny.
char | _DynUnionStub.get_wchar() Extracts the long value from this DynAny.
char | _DynStructStub.get_wchar() Extracts the long value from this DynAny.
char | DynAnyOperations.get_wchar() Extracts the long value from this DynAny.
String | _DynSequenceStub.get_wstring() Extracts the string value from this DynAny.
String | _DynFixedStub.get_wstring() Extracts the string value from this DynAny.
String | _DynEnumStub.get_wstring() Extracts the string value from this DynAny.
String | _DynArrayStub.get_wstring() Extracts the string value from this DynAny.
String | _DynValueStub.get_wstring() Extracts the string value from this DynAny.
String | _DynAnyStub.get_wstring() Extracts the string value from this DynAny.
String | _DynUnionStub.get_wstring() Extracts the string value from this DynAny.
String | _DynStructStub.get_wstring() Extracts the string value from this DynAny.
String | DynAnyOperations.get_wstring() Extracts the string value from this DynAny.
void | _DynSequenceStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynFixedStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynEnumStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynArrayStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynValueStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynAnyStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynUnionStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynStructStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | DynAnyOperations.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynSequenceStub.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | _DynFixedStub.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | _DynEnumStub.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | _DynArrayStub.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | _DynValueStub.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | _DynAnyStub.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | _DynUnionStub.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | _DynStructStub.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | DynAnyOperations.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | _DynSequenceStub.insert_char(char value) Inserts a char value into the DynAny.
void | _DynFixedStub.insert_char(char value) Inserts a char value into the DynAny.
void | _DynEnumStub.insert_char(char value) Inserts a char value into the DynAny.
void | _DynArrayStub.insert_char(char value) Inserts a char value into the DynAny.
void | _DynValueStub.insert_char(char value) Inserts a char value into the DynAny.
void | _DynAnyStub.insert_char(char value) Inserts a char value into the DynAny.
void | _DynUnionStub.insert_char(char value) Inserts a char value into the DynAny.
void | _DynStructStub.insert_char(char value) Inserts a char value into the DynAny.
void | DynAnyOperations.insert_char(char value) Inserts a char value into the DynAny.
void | _DynSequenceStub.insert_double(double value) Inserts a double value into the DynAny.
void | _DynFixedStub.insert_double(double value) Inserts a double value into the DynAny.
void | _DynEnumStub.insert_double(double value) Inserts a double value into the DynAny.
void | _DynArrayStub.insert_double(double value) Inserts a double value into the DynAny.
void | _DynValueStub.insert_double(double value) Inserts a double value into the DynAny.
void | _DynAnyStub.insert_double(double value) Inserts a double value into the DynAny.
void | _DynUnionStub.insert_double(double value) Inserts a double value into the DynAny.
void | _DynStructStub.insert_double(double value) Inserts a double value into the DynAny.
void | DynAnyOperations.insert_double(double value) Inserts a double value into the DynAny.
void | _DynSequenceStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynFixedStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynEnumStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynArrayStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynValueStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynAnyStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynUnionStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynStructStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | DynAnyOperations.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynSequenceStub.insert_float(float value) Inserts a float value into the DynAny.
void | _DynFixedStub.insert_float(float value) Inserts a float value into the DynAny.
void | _DynEnumStub.insert_float(float value) Inserts a float value into the DynAny.
void | _DynArrayStub.insert_float(float value) Inserts a float value into the DynAny.
void | _DynValueStub.insert_float(float value) Inserts a float value into the DynAny.
void | _DynAnyStub.insert_float(float value) Inserts a float value into the DynAny.
void | _DynUnionStub.insert_float(float value) Inserts a float value into the DynAny.
void | _DynStructStub.insert_float(float value) Inserts a float value into the DynAny.
void | DynAnyOperations.insert_float(float value) Inserts a float value into the DynAny.
void | _DynSequenceStub.insert_long(int value) Inserts an integer value into the DynAny.
void | _DynFixedStub.insert_long(int value) Inserts an integer value into the DynAny.
void | _DynEnumStub.insert_long(int value) Inserts an integer value into the DynAny.
void | _DynArrayStub.insert_long(int value) Inserts an integer value into the DynAny.
void | _DynValueStub.insert_long(int value) Inserts an integer value into the DynAny.
void | _DynAnyStub.insert_long(int value) Inserts an integer value into the DynAny.
void | _DynUnionStub.insert_long(int value) Inserts an integer value into the DynAny.
void | _DynStructStub.insert_long(int value) Inserts an integer value into the DynAny.
void | DynAnyOperations.insert_long(int value) Inserts an integer value into the DynAny.
void | _DynSequenceStub.insert_longlong(long value) Inserts a long value into the DynAny.
void | _DynFixedStub.insert_longlong(long value) Inserts a long value into the DynAny.
void | _DynEnumStub.insert_longlong(long value) Inserts a long value into the DynAny.
void | _DynArrayStub.insert_longlong(long value) Inserts a long value into the DynAny.
void | _DynValueStub.insert_longlong(long value) Inserts a long value into the DynAny.
void | _DynAnyStub.insert_longlong(long value) Inserts a long value into the DynAny.
void | _DynUnionStub.insert_longlong(long value) Inserts a long value into the DynAny.
void | _DynStructStub.insert_longlong(long value) Inserts a long value into the DynAny.
void | DynAnyOperations.insert_longlong(long value) Inserts a long value into the DynAny.
void | _DynSequenceStub.insert_octet(byte value) Inserts a byte value into the DynAny.
void | _DynFixedStub.insert_octet(byte value) Inserts a byte value into the DynAny.
void | _DynEnumStub.insert_octet(byte value) Inserts a byte value into the DynAny.
void | _DynArrayStub.insert_octet(byte value) Inserts a byte value into the DynAny.
void | _DynValueStub.insert_octet(byte value) Inserts a byte value into the DynAny.
void | _DynAnyStub.insert_octet(byte value) Inserts a byte value into the DynAny.
void | _DynUnionStub.insert_octet(byte value) Inserts a byte value into the DynAny.
void | _DynStructStub.insert_octet(byte value) Inserts a byte value into the DynAny.
void | DynAnyOperations.insert_octet(byte value) Inserts a byte value into the DynAny.
void | _DynSequenceStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynFixedStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynEnumStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynArrayStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynValueStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynAnyStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynUnionStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynStructStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | DynAnyOperations.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynSequenceStub.insert_short(short value) Inserts a short value into the DynAny.
void | _DynFixedStub.insert_short(short value) Inserts a short value into the DynAny.
void | _DynEnumStub.insert_short(short value) Inserts a short value into the DynAny.
void | _DynArrayStub.insert_short(short value) Inserts a short value into the DynAny.
void | _DynValueStub.insert_short(short value) Inserts a short value into the DynAny.
void | _DynAnyStub.insert_short(short value) Inserts a short value into the DynAny.
void | _DynUnionStub.insert_short(short value) Inserts a short value into the DynAny.
void | _DynStructStub.insert_short(short value) Inserts a short value into the DynAny.
void | DynAnyOperations.insert_short(short value) Inserts a short value into the DynAny.
void | _DynSequenceStub.insert_string(String value) Inserts a string value into the DynAny.
void | _DynFixedStub.insert_string(String value) Inserts a string value into the DynAny.
void | _DynEnumStub.insert_string(String value) Inserts a string value into the DynAny.
void | _DynArrayStub.insert_string(String value) Inserts a string value into the DynAny.
void | _DynValueStub.insert_string(String value) Inserts a string value into the DynAny.
void | _DynAnyStub.insert_string(String value) Inserts a string value into the DynAny.
void | _DynUnionStub.insert_string(String value) Inserts a string value into the DynAny.
void | _DynStructStub.insert_string(String value) Inserts a string value into the DynAny.
void | DynAnyOperations.insert_string(String value) Inserts a string value into the DynAny.
void | _DynSequenceStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynFixedStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynEnumStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynArrayStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynValueStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynAnyStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynUnionStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynStructStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | DynAnyOperations.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynSequenceStub.insert_ulong(int value) Inserts an integer value into the DynAny.
void | _DynFixedStub.insert_ulong(int value) Inserts an integer value into the DynAny.
void | _DynEnumStub.insert_ulong(int value) Inserts an integer value into the DynAny.
void | _DynArrayStub.insert_ulong(int value) Inserts an integer value into the DynAny.
void | _DynValueStub.insert_ulong(int value) Inserts an integer value into the DynAny.
void | _DynAnyStub.insert_ulong(int value) Inserts an integer value into the DynAny.
void | _DynUnionStub.insert_ulong(int value) Inserts an integer value into the DynAny.
void | _DynStructStub.insert_ulong(int value) Inserts an integer value into the DynAny.
void | DynAnyOperations.insert_ulong(int value) Inserts an integer value into the DynAny.
void | _DynSequenceStub.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | _DynFixedStub.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | _DynEnumStub.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | _DynArrayStub.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | _DynValueStub.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | _DynAnyStub.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | _DynUnionStub.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | _DynStructStub.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | DynAnyOperations.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | _DynSequenceStub.insert_ushort(short value) Inserts a short value into the DynAny.
void | _DynFixedStub.insert_ushort(short value) Inserts a short value into the DynAny.
void | _DynEnumStub.insert_ushort(short value) Inserts a short value into the DynAny.
void | _DynArrayStub.insert_ushort(short value) Inserts a short value into the DynAny.
void | _DynValueStub.insert_ushort(short value) Inserts a short value into the DynAny.
void | _DynAnyStub.insert_ushort(short value) Inserts a short value into the DynAny.
void | _DynUnionStub.insert_ushort(short value) Inserts a short value into the DynAny.
void | _DynStructStub.insert_ushort(short value) Inserts a short value into the DynAny.
void | DynAnyOperations.insert_ushort(short value) Inserts a short value into the DynAny.
void | _DynSequenceStub.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | _DynFixedStub.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | _DynEnumStub.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | _DynArrayStub.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | _DynValueStub.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | _DynAnyStub.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | _DynUnionStub.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | _DynStructStub.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | DynAnyOperations.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | _DynSequenceStub.insert_wchar(char value) Inserts a char value into the DynAny.
void | _DynFixedStub.insert_wchar(char value) Inserts a char value into the DynAny.
void | _DynEnumStub.insert_wchar(char value) Inserts a char value into the DynAny.
void | _DynArrayStub.insert_wchar(char value) Inserts a char value into the DynAny.
void | _DynValueStub.insert_wchar(char value) Inserts a char value into the DynAny.
void | _DynAnyStub.insert_wchar(char value) Inserts a char value into the DynAny.
void | _DynUnionStub.insert_wchar(char value) Inserts a char value into the DynAny.
void | _DynStructStub.insert_wchar(char value) Inserts a char value into the DynAny.
void | DynAnyOperations.insert_wchar(char value) Inserts a char value into the DynAny.
void | _DynSequenceStub.insert_wstring(String value) Inserts a string value into the DynAny.
void | _DynFixedStub.insert_wstring(String value) Inserts a string value into the DynAny.
void | _DynEnumStub.insert_wstring(String value) Inserts a string value into the DynAny.
void | _DynArrayStub.insert_wstring(String value) Inserts a string value into the DynAny.
void | _DynValueStub.insert_wstring(String value) Inserts a string value into the DynAny.
void | _DynAnyStub.insert_wstring(String value) Inserts a string value into the DynAny.
void | _DynUnionStub.insert_wstring(String value) Inserts a string value into the DynAny.
void | _DynStructStub.insert_wstring(String value) Inserts a string value into the DynAny.
void | DynAnyOperations.insert_wstring(String value) Inserts a string value into the DynAny.
TCKind | _DynUnionStub.member_kind() Returns the TCKind value of the currently active members TypeCode.
TCKind | DynUnionOperations.member_kind() Returns the TCKind value of the currently active members TypeCode.
String | _DynUnionStub.member_name() Returns the name of the currently active member.
String | DynUnionOperations.member_name() Returns the name of the currently active member.
DynAny | _DynUnionStub.member() Returns the currently active member.
DynAny | DynUnionOperations.member() Returns the currently active member.
void | _DynEnumStub.set_as_string(String value) Sets the value of the DynEnum to the enumerated value whose IDL identifier is passed in the value parameter.
void | DynEnumOperations.set_as_string(String value) Sets the value of the DynEnum to the enumerated value whose IDL identifier is passed in the value parameter.
void | _DynEnumStub.set_as_ulong(int value) Sets the value of the DynEnum as the enumerated value's ordinal value.
void | DynEnumOperations.set_as_ulong(int value) Sets the value of the DynEnum as the enumerated value's ordinal value.
void | _DynSequenceStub.set_elements_as_dyn_any(DynAny[] value) Sets the elements of a sequence using DynAnys.
void | _DynArrayStub.set_elements_as_dyn_any(DynAny[] value) Sets the DynArray to contain the passed elements.
void | DynSequenceOperations.set_elements_as_dyn_any(DynAny[] value) Sets the elements of a sequence using DynAnys.
void | DynArrayOperations.set_elements_as_dyn_any(DynAny[] value) Sets the DynArray to contain the passed elements.
void | _DynSequenceStub.set_elements(Any[] value) Sets the elements of a sequence.
void | _DynArrayStub.set_elements(Any[] value) Sets the DynArray to contain the passed elements.
void | DynSequenceOperations.set_elements(Any[] value) Sets the elements of a sequence.
void | DynArrayOperations.set_elements(Any[] value) Sets the DynArray to contain the passed elements.
void | _DynSequenceStub.set_length(int len) Sets the length of the sequence.
void | DynSequenceOperations.set_length(int len) Sets the length of the sequence.
void | _DynValueStub.set_members_as_dyn_any(NameDynAnyPair[] value) Initializes the value type's members from a sequence of NameDynAnyPairs.
void | _DynStructStub.set_members_as_dyn_any(NameDynAnyPair[] value) Initializes the struct data value associated with a DynStruct object from a sequence of NameDynAnyPairs.
void | DynValueOperations.set_members_as_dyn_any(NameDynAnyPair[] value) Initializes the value type's members from a sequence of NameDynAnyPairs.
void | DynStructOperations.set_members_as_dyn_any(NameDynAnyPair[] value) Initializes the struct data value associated with a DynStruct object from a sequence of NameDynAnyPairs.
void | _DynValueStub.set_members(NameValuePair[] value) Initializes the value type's members from a sequence of NameValuePairs.
void | _DynStructStub.set_members(NameValuePair[] value) Initializes the struct data value associated with a DynStruct object from a sequence of NameValuePairs.
void | DynValueOperations.set_members(NameValuePair[] value) Initializes the value type's members from a sequence of NameValuePairs.
void | DynStructOperations.set_members(NameValuePair[] value) Initializes the struct data value associated with a DynStruct object from a sequence of NameValuePairs.
boolean | _DynFixedStub.set_value(String val) Sets the value of the DynFixed.
boolean | DynFixedOperations.set_value(String val) Sets the value of the DynFixed.

Uses of InvalidValue in org.omg.DynamicAny.DynAnyPackage

Methods in org.omg.DynamicAny.DynAnyPackage that return InvalidValue
static InvalidValue | InvalidValueHelper.extract(Any a)
static InvalidValue | InvalidValueHelper.read(InputStream istream)

Methods in org.omg.DynamicAny.DynAnyPackage with parameters of type InvalidValue
static void | InvalidValueHelper.insert(Any a, InvalidValue that)
static void | InvalidValueHelper.write(OutputStream ostream, InvalidValue value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.DynAnyPackage.InvalidValueHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.DynAnyPackage.InvalidValueHelper

No usage of org.omg.DynamicAny.DynAnyPackage.InvalidValueHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.DynAnyPackage.TypeMismatch

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.DynAnyPackage.TypeMismatch

Packages that use TypeMismatch
org.omg.DynamicAny | Provides classes and interfaces that enable traversal of the data value associated with an any at runtime, and extraction of the primitive constituents of the data value.
org.omg.DynamicAny.DynAnyPackage | This package contains classes and exceptions from the DynAny interface of the DynamicAny module specified in the OMG The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 9.2.

Uses of TypeMismatch in org.omg.DynamicAny

Methods in org.omg.DynamicAny that throw TypeMismatch
void | _DynSequenceStub.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
void | _DynFixedStub.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
void | _DynEnumStub.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
void | _DynArrayStub.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
void | _DynValueStub.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
void | _DynAnyStub.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
void | _DynUnionStub.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
void | _DynStructStub.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
void | DynAnyOperations.assign(DynAny dyn_any) Initializes the value associated with a DynAny object with the value associated with another DynAny object.
DynAny | _DynSequenceStub.current_component() Returns the DynAny for the component at the current position.
DynAny | _DynFixedStub.current_component() Returns the DynAny for the component at the current position.
DynAny | _DynEnumStub.current_component() Returns the DynAny for the component at the current position.
DynAny | _DynArrayStub.current_component() Returns the DynAny for the component at the current position.
DynAny | _DynValueStub.current_component() Returns the DynAny for the component at the current position.
DynAny | _DynAnyStub.current_component() Returns the DynAny for the component at the current position.
DynAny | _DynUnionStub.current_component() Returns the DynAny for the component at the current position.
DynAny | _DynStructStub.current_component() Returns the DynAny for the component at the current position.
DynAny | DynAnyOperations.current_component() Returns the DynAny for the component at the current position.
TCKind | _DynValueStub.current_member_kind() Returns the TCKind associated with the member at the current position.
TCKind | _DynStructStub.current_member_kind() Returns the TCKind associated with the member at the current position.
TCKind | DynValueOperations.current_member_kind() Returns the TCKind associated with the member at the current position.
TCKind | DynStructOperations.current_member_kind() Returns the TCKind associated with the member at the current position.
String | _DynValueStub.current_member_name() Returns the name of the member at the current position.
String | _DynStructStub.current_member_name() Returns the name of the member at the current position.
String | DynValueOperations.current_member_name() Returns the name of the member at the current position.
String | DynStructOperations.current_member_name() Returns the name of the member at the current position.
void | _DynSequenceStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynFixedStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynEnumStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynArrayStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynValueStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynAnyStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynUnionStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | _DynStructStub.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
void | DynAnyOperations.from_any(Any value) Initializes the value associated with a DynAny object with the value contained in an any.
Any | _DynSequenceStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynFixedStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynEnumStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynArrayStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynValueStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynAnyStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynUnionStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | _DynStructStub.get_any() Extracts an Any value contained in the Any represented by this DynAny.
Any | DynAnyOperations.get_any() Extracts an Any value contained in the Any represented by this DynAny.
boolean | _DynSequenceStub.get_boolean() Extracts the boolean value from this DynAny.
boolean | _DynFixedStub.get_boolean() Extracts the boolean value from this DynAny.
boolean | _DynEnumStub.get_boolean() Extracts the boolean value from this DynAny.
boolean | _DynArrayStub.get_boolean() Extracts the boolean value from this DynAny.
boolean | _DynValueStub.get_boolean() Extracts the boolean value from this DynAny.
boolean | _DynAnyStub.get_boolean() Extracts the boolean value from this DynAny.
boolean | _DynUnionStub.get_boolean() Extracts the boolean value from this DynAny.
boolean | _DynStructStub.get_boolean() Extracts the boolean value from this DynAny.
boolean | DynAnyOperations.get_boolean() Extracts the boolean value from this DynAny.
char | _DynSequenceStub.get_char() Extracts the char value from this DynAny.
char | _DynFixedStub.get_char() Extracts the char value from this DynAny.
char | _DynEnumStub.get_char() Extracts the char value from this DynAny.
char | _DynArrayStub.get_char() Extracts the char value from this DynAny.
char | _DynValueStub.get_char() Extracts the char value from this DynAny.
char | _DynAnyStub.get_char() Extracts the char value from this DynAny.
char | _DynUnionStub.get_char() Extracts the char value from this DynAny.
char | _DynStructStub.get_char() Extracts the char value from this DynAny.
char | DynAnyOperations.get_char() Extracts the char value from this DynAny.
double | _DynSequenceStub.get_double() Extracts the double value from this DynAny.
double | _DynFixedStub.get_double() Extracts the double value from this DynAny.
double | _DynEnumStub.get_double() Extracts the double value from this DynAny.
double | _DynArrayStub.get_double() Extracts the double value from this DynAny.
double | _DynValueStub.get_double() Extracts the double value from this DynAny.
double | _DynAnyStub.get_double() Extracts the double value from this DynAny.
double | _DynUnionStub.get_double() Extracts the double value from this DynAny.
double | _DynStructStub.get_double() Extracts the double value from this DynAny.
double | DynAnyOperations.get_double() Extracts the double value from this DynAny.
DynAny | _DynSequenceStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynFixedStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynEnumStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynArrayStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynValueStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynAnyStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynUnionStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | _DynStructStub.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
DynAny | DynAnyOperations.get_dyn_any() Extracts the Any value contained in the Any represented by this DynAny and returns it wrapped into a new DynAny.
float | _DynSequenceStub.get_float() Extracts the float value from this DynAny.
float | _DynFixedStub.get_float() Extracts the float value from this DynAny.
float | _DynEnumStub.get_float() Extracts the float value from this DynAny.
float | _DynArrayStub.get_float() Extracts the float value from this DynAny.
float | _DynValueStub.get_float() Extracts the float value from this DynAny.
float | _DynAnyStub.get_float() Extracts the float value from this DynAny.
float | _DynUnionStub.get_float() Extracts the float value from this DynAny.
float | _DynStructStub.get_float() Extracts the float value from this DynAny.
float | DynAnyOperations.get_float() Extracts the float value from this DynAny.
int | _DynSequenceStub.get_long() Extracts the integer value from this DynAny.
int | _DynFixedStub.get_long() Extracts the integer value from this DynAny.
int | _DynEnumStub.get_long() Extracts the integer value from this DynAny.
int | _DynArrayStub.get_long() Extracts the integer value from this DynAny.
int | _DynValueStub.get_long() Extracts the integer value from this DynAny.
int | _DynAnyStub.get_long() Extracts the integer value from this DynAny.
int | _DynUnionStub.get_long() Extracts the integer value from this DynAny.
int | _DynStructStub.get_long() Extracts the integer value from this DynAny.
int | DynAnyOperations.get_long() Extracts the integer value from this DynAny.
long | _DynSequenceStub.get_longlong() Extracts the long value from this DynAny.
long | _DynFixedStub.get_longlong() Extracts the long value from this DynAny.
long | _DynEnumStub.get_longlong() Extracts the long value from this DynAny.
long | _DynArrayStub.get_longlong() Extracts the long value from this DynAny.
long | _DynValueStub.get_longlong() Extracts the long value from this DynAny.
long | _DynAnyStub.get_longlong() Extracts the long value from this DynAny.
long | _DynUnionStub.get_longlong() Extracts the long value from this DynAny.
long | _DynStructStub.get_longlong() Extracts the long value from this DynAny.
long | DynAnyOperations.get_longlong() Extracts the long value from this DynAny.
byte | _DynSequenceStub.get_octet() Extracts the byte value from this DynAny.
byte | _DynFixedStub.get_octet() Extracts the byte value from this DynAny.
byte | _DynEnumStub.get_octet() Extracts the byte value from this DynAny.
byte | _DynArrayStub.get_octet() Extracts the byte value from this DynAny.
byte | _DynValueStub.get_octet() Extracts the byte value from this DynAny.
byte | _DynAnyStub.get_octet() Extracts the byte value from this DynAny.
byte | _DynUnionStub.get_octet() Extracts the byte value from this DynAny.
byte | _DynStructStub.get_octet() Extracts the byte value from this DynAny.
byte | DynAnyOperations.get_octet() Extracts the byte value from this DynAny.
Object | _DynSequenceStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynFixedStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynEnumStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynArrayStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynValueStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynAnyStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynUnionStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | _DynStructStub.get_reference() Extracts the reference to a CORBA Object from this DynAny.
Object | DynAnyOperations.get_reference() Extracts the reference to a CORBA Object from this DynAny.
short | _DynSequenceStub.get_short() Extracts the short value from this DynAny.
short | _DynFixedStub.get_short() Extracts the short value from this DynAny.
short | _DynEnumStub.get_short() Extracts the short value from this DynAny.
short | _DynArrayStub.get_short() Extracts the short value from this DynAny.
short | _DynValueStub.get_short() Extracts the short value from this DynAny.
short | _DynAnyStub.get_short() Extracts the short value from this DynAny.
short | _DynUnionStub.get_short() Extracts the short value from this DynAny.
short | _DynStructStub.get_short() Extracts the short value from this DynAny.
short | DynAnyOperations.get_short() Extracts the short value from this DynAny.
String | _DynSequenceStub.get_string() Extracts the string value from this DynAny.
String | _DynFixedStub.get_string() Extracts the string value from this DynAny.
String | _DynEnumStub.get_string() Extracts the string value from this DynAny.
String | _DynArrayStub.get_string() Extracts the string value from this DynAny.
String | _DynValueStub.get_string() Extracts the string value from this DynAny.
String | _DynAnyStub.get_string() Extracts the string value from this DynAny.
String | _DynUnionStub.get_string() Extracts the string value from this DynAny.
String | _DynStructStub.get_string() Extracts the string value from this DynAny.
String | DynAnyOperations.get_string() Extracts the string value from this DynAny.
TypeCode | _DynSequenceStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynFixedStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynEnumStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynArrayStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynValueStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynAnyStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynUnionStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | _DynStructStub.get_typecode() Extracts the TypeCode object from this DynAny.
TypeCode | DynAnyOperations.get_typecode() Extracts the TypeCode object from this DynAny.
int | _DynSequenceStub.get_ulong() Extracts the integer value from this DynAny.
int | _DynFixedStub.get_ulong() Extracts the integer value from this DynAny.
int | _DynEnumStub.get_ulong() Extracts the integer value from this DynAny.
int | _DynArrayStub.get_ulong() Extracts the integer value from this DynAny.
int | _DynValueStub.get_ulong() Extracts the integer value from this DynAny.
int | _DynAnyStub.get_ulong() Extracts the integer value from this DynAny.
int | _DynUnionStub.get_ulong() Extracts the integer value from this DynAny.
int | _DynStructStub.get_ulong() Extracts the integer value from this DynAny.
int | DynAnyOperations.get_ulong() Extracts the integer value from this DynAny.
long | _DynSequenceStub.get_ulonglong() Extracts the long value from this DynAny.
long | _DynFixedStub.get_ulonglong() Extracts the long value from this DynAny.
long | _DynEnumStub.get_ulonglong() Extracts the long value from this DynAny.
long | _DynArrayStub.get_ulonglong() Extracts the long value from this DynAny.
long | _DynValueStub.get_ulonglong() Extracts the long value from this DynAny.
long | _DynAnyStub.get_ulonglong() Extracts the long value from this DynAny.
long | _DynUnionStub.get_ulonglong() Extracts the long value from this DynAny.
long | _DynStructStub.get_ulonglong() Extracts the long value from this DynAny.
long | DynAnyOperations.get_ulonglong() Extracts the long value from this DynAny.
short | _DynSequenceStub.get_ushort() Extracts the short value from this DynAny.
short | _DynFixedStub.get_ushort() Extracts the short value from this DynAny.
short | _DynEnumStub.get_ushort() Extracts the short value from this DynAny.
short | _DynArrayStub.get_ushort() Extracts the short value from this DynAny.
short | _DynValueStub.get_ushort() Extracts the short value from this DynAny.
short | _DynAnyStub.get_ushort() Extracts the short value from this DynAny.
short | _DynUnionStub.get_ushort() Extracts the short value from this DynAny.
short | _DynStructStub.get_ushort() Extracts the short value from this DynAny.
short | DynAnyOperations.get_ushort() Extracts the short value from this DynAny.
Serializable | _DynSequenceStub.get_val() Extracts a Serializable object from this DynAny.
Serializable | _DynFixedStub.get_val() Extracts a Serializable object from this DynAny.
Serializable | _DynEnumStub.get_val() Extracts a Serializable object from this DynAny.
Serializable | _DynArrayStub.get_val() Extracts a Serializable object from this DynAny.
Serializable | _DynValueStub.get_val() Extracts a Serializable object from this DynAny.
Serializable | _DynAnyStub.get_val() Extracts a Serializable object from this DynAny.
Serializable | _DynUnionStub.get_val() Extracts a Serializable object from this DynAny.
Serializable | _DynStructStub.get_val() Extracts a Serializable object from this DynAny.
Serializable | DynAnyOperations.get_val() Extracts a Serializable object from this DynAny.
char | _DynSequenceStub.get_wchar() Extracts the long value from this DynAny.
char | _DynFixedStub.get_wchar() Extracts the long value from this DynAny.
char | _DynEnumStub.get_wchar() Extracts the long value from this DynAny.
char | _DynArrayStub.get_wchar() Extracts the long value from this DynAny.
char | _DynValueStub.get_wchar() Extracts the long value from this DynAny.
char | _DynAnyStub.get_wchar() Extracts the long value from this DynAny.
char | _DynUnionStub.get_wchar() Extracts the long value from this DynAny.
char | _DynStructStub.get_wchar() Extracts the long value from this DynAny.
char | DynAnyOperations.get_wchar() Extracts the long value from this DynAny.
String | _DynSequenceStub.get_wstring() Extracts the string value from this DynAny.
String | _DynFixedStub.get_wstring() Extracts the string value from this DynAny.
String | _DynEnumStub.get_wstring() Extracts the string value from this DynAny.
String | _DynArrayStub.get_wstring() Extracts the string value from this DynAny.
String | _DynValueStub.get_wstring() Extracts the string value from this DynAny.
String | _DynAnyStub.get_wstring() Extracts the string value from this DynAny.
String | _DynUnionStub.get_wstring() Extracts the string value from this DynAny.
String | _DynStructStub.get_wstring() Extracts the string value from this DynAny.
String | DynAnyOperations.get_wstring() Extracts the string value from this DynAny.
void | _DynSequenceStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynFixedStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynEnumStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynArrayStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynValueStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynAnyStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynUnionStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynStructStub.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | DynAnyOperations.insert_any(Any value) Inserts an Any value into the Any represented by this DynAny.
void | _DynSequenceStub.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | _DynFixedStub.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | _DynEnumStub.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | _DynArrayStub.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | _DynValueStub.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | _DynAnyStub.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | _DynUnionStub.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | _DynStructStub.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | DynAnyOperations.insert_boolean(boolean value) Inserts a boolean value into the DynAny.
void | _DynSequenceStub.insert_char(char value) Inserts a char value into the DynAny.
void | _DynFixedStub.insert_char(char value) Inserts a char value into the DynAny.
void | _DynEnumStub.insert_char(char value) Inserts a char value into the DynAny.
void | _DynArrayStub.insert_char(char value) Inserts a char value into the DynAny.
void | _DynValueStub.insert_char(char value) Inserts a char value into the DynAny.
void | _DynAnyStub.insert_char(char value) Inserts a char value into the DynAny.
void | _DynUnionStub.insert_char(char value) Inserts a char value into the DynAny.
void | _DynStructStub.insert_char(char value) Inserts a char value into the DynAny.
void | DynAnyOperations.insert_char(char value) Inserts a char value into the DynAny.
void | _DynSequenceStub.insert_double(double value) Inserts a double value into the DynAny.
void | _DynFixedStub.insert_double(double value) Inserts a double value into the DynAny.
void | _DynEnumStub.insert_double(double value) Inserts a double value into the DynAny.
void | _DynArrayStub.insert_double(double value) Inserts a double value into the DynAny.
void | _DynValueStub.insert_double(double value) Inserts a double value into the DynAny.
void | _DynAnyStub.insert_double(double value) Inserts a double value into the DynAny.
void | _DynUnionStub.insert_double(double value) Inserts a double value into the DynAny.
void | _DynStructStub.insert_double(double value) Inserts a double value into the DynAny.
void | DynAnyOperations.insert_double(double value) Inserts a double value into the DynAny.
void | _DynSequenceStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynFixedStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynEnumStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynArrayStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynValueStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynAnyStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynUnionStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynStructStub.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | DynAnyOperations.insert_dyn_any(DynAny value) Inserts the Any value contained in the parameter DynAny into the Any represented by this DynAny.
void | _DynSequenceStub.insert_float(float value) Inserts a float value into the DynAny.
void | _DynFixedStub.insert_float(float value) Inserts a float value into the DynAny.
void | _DynEnumStub.insert_float(float value) Inserts a float value into the DynAny.
void | _DynArrayStub.insert_float(float value) Inserts a float value into the DynAny.
void | _DynValueStub.insert_float(float value) Inserts a float value into the DynAny.
void | _DynAnyStub.insert_float(float value) Inserts a float value into the DynAny.
void | _DynUnionStub.insert_float(float value) Inserts a float value into the DynAny.
void | _DynStructStub.insert_float(float value) Inserts a float value into the DynAny.
void | DynAnyOperations.insert_float(float value) Inserts a float value into the DynAny.
void | _DynSequenceStub.insert_long(int value) Inserts an integer value into the DynAny.
void | _DynFixedStub.insert_long(int value) Inserts an integer value into the DynAny.
void | _DynEnumStub.insert_long(int value) Inserts an integer value into the DynAny.
void | _DynArrayStub.insert_long(int value) Inserts an integer value into the DynAny.
void | _DynValueStub.insert_long(int value) Inserts an integer value into the DynAny.
void | _DynAnyStub.insert_long(int value) Inserts an integer value into the DynAny.
void | _DynUnionStub.insert_long(int value) Inserts an integer value into the DynAny.
void | _DynStructStub.insert_long(int value) Inserts an integer value into the DynAny.
void | DynAnyOperations.insert_long(int value) Inserts an integer value into the DynAny.
void | _DynSequenceStub.insert_longlong(long value) Inserts a long value into the DynAny.
void | _DynFixedStub.insert_longlong(long value) Inserts a long value into the DynAny.
void | _DynEnumStub.insert_longlong(long value) Inserts a long value into the DynAny.
void | _DynArrayStub.insert_longlong(long value) Inserts a long value into the DynAny.
void | _DynValueStub.insert_longlong(long value) Inserts a long value into the DynAny.
void | _DynAnyStub.insert_longlong(long value) Inserts a long value into the DynAny.
void | _DynUnionStub.insert_longlong(long value) Inserts a long value into the DynAny.
void | _DynStructStub.insert_longlong(long value) Inserts a long value into the DynAny.
void | DynAnyOperations.insert_longlong(long value) Inserts a long value into the DynAny.
void | _DynSequenceStub.insert_octet(byte value) Inserts a byte value into the DynAny.
void | _DynFixedStub.insert_octet(byte value) Inserts a byte value into the DynAny.
void | _DynEnumStub.insert_octet(byte value) Inserts a byte value into the DynAny.
void | _DynArrayStub.insert_octet(byte value) Inserts a byte value into the DynAny.
void | _DynValueStub.insert_octet(byte value) Inserts a byte value into the DynAny.
void | _DynAnyStub.insert_octet(byte value) Inserts a byte value into the DynAny.
void | _DynUnionStub.insert_octet(byte value) Inserts a byte value into the DynAny.
void | _DynStructStub.insert_octet(byte value) Inserts a byte value into the DynAny.
void | DynAnyOperations.insert_octet(byte value) Inserts a byte value into the DynAny.
void | _DynSequenceStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynFixedStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynEnumStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynArrayStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynValueStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynAnyStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynUnionStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynStructStub.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | DynAnyOperations.insert_reference(Object value) Inserts a reference to a CORBA object into the DynAny.
void | _DynSequenceStub.insert_short(short value) Inserts a short value into the DynAny.
void | _DynFixedStub.insert_short(short value) Inserts a short value into the DynAny.
void | _DynEnumStub.insert_short(short value) Inserts a short value into the DynAny.
void | _DynArrayStub.insert_short(short value) Inserts a short value into the DynAny.
void | _DynValueStub.insert_short(short value) Inserts a short value into the DynAny.
void | _DynAnyStub.insert_short(short value) Inserts a short value into the DynAny.
void | _DynUnionStub.insert_short(short value) Inserts a short value into the DynAny.
void | _DynStructStub.insert_short(short value) Inserts a short value into the DynAny.
void | DynAnyOperations.insert_short(short value) Inserts a short value into the DynAny.
void | _DynSequenceStub.insert_string(String value) Inserts a string value into the DynAny.
void | _DynFixedStub.insert_string(String value) Inserts a string value into the DynAny.
void | _DynEnumStub.insert_string(String value) Inserts a string value into the DynAny.
void | _DynArrayStub.insert_string(String value) Inserts a string value into the DynAny.
void | _DynValueStub.insert_string(String value) Inserts a string value into the DynAny.
void | _DynAnyStub.insert_string(String value) Inserts a string value into the DynAny.
void | _DynUnionStub.insert_string(String value) Inserts a string value into the DynAny.
void | _DynStructStub.insert_string(String value) Inserts a string value into the DynAny.
void | DynAnyOperations.insert_string(String value) Inserts a string value into the DynAny.
void | _DynSequenceStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynFixedStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynEnumStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynArrayStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynValueStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynAnyStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynUnionStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynStructStub.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | DynAnyOperations.insert_typecode(TypeCode value) Inserts a TypeCode object into the DynAny.
void | _DynSequenceStub.insert_ulong(int value) Inserts an integer value into the DynAny.
void | _DynFixedStub.insert_ulong(int value) Inserts an integer value into the DynAny.
void | _DynEnumStub.insert_ulong(int value) Inserts an integer value into the DynAny.
void | _DynArrayStub.insert_ulong(int value) Inserts an integer value into the DynAny.
void | _DynValueStub.insert_ulong(int value) Inserts an integer value into the DynAny.
void | _DynAnyStub.insert_ulong(int value) Inserts an integer value into the DynAny.
void | _DynUnionStub.insert_ulong(int value) Inserts an integer value into the DynAny.
void | _DynStructStub.insert_ulong(int value) Inserts an integer value into the DynAny.
void | DynAnyOperations.insert_ulong(int value) Inserts an integer value into the DynAny.
void | _DynSequenceStub.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | _DynFixedStub.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | _DynEnumStub.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | _DynArrayStub.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | _DynValueStub.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | _DynAnyStub.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | _DynUnionStub.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | _DynStructStub.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | DynAnyOperations.insert_ulonglong(long value) Inserts a long value into the DynAny.
void | _DynSequenceStub.insert_ushort(short value) Inserts a short value into the DynAny.
void | _DynFixedStub.insert_ushort(short value) Inserts a short value into the DynAny.
void | _DynEnumStub.insert_ushort(short value) Inserts a short value into the DynAny.
void | _DynArrayStub.insert_ushort(short value) Inserts a short value into the DynAny.
void | _DynValueStub.insert_ushort(short value) Inserts a short value into the DynAny.
void | _DynAnyStub.insert_ushort(short value) Inserts a short value into the DynAny.
void | _DynUnionStub.insert_ushort(short value) Inserts a short value into the DynAny.
void | _DynStructStub.insert_ushort(short value) Inserts a short value into the DynAny.
void | DynAnyOperations.insert_ushort(short value) Inserts a short value into the DynAny.
void | _DynSequenceStub.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | _DynFixedStub.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | _DynEnumStub.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | _DynArrayStub.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | _DynValueStub.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | _DynAnyStub.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | _DynUnionStub.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | _DynStructStub.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | DynAnyOperations.insert_val(Serializable value) Inserts a reference to a Serializable object into this DynAny.
void | _DynSequenceStub.insert_wchar(char value) Inserts a char value into the DynAny.
void | _DynFixedStub.insert_wchar(char value) Inserts a char value into the DynAny.
void | _DynEnumStub.insert_wchar(char value) Inserts a char value into the DynAny.
void | _DynArrayStub.insert_wchar(char value) Inserts a char value into the DynAny.
void | _DynValueStub.insert_wchar(char value) Inserts a char value into the DynAny.
void | _DynAnyStub.insert_wchar(char value) Inserts a char value into the DynAny.
void | _DynUnionStub.insert_wchar(char value) Inserts a char value into the DynAny.
void | _DynStructStub.insert_wchar(char value) Inserts a char value into the DynAny.
void | DynAnyOperations.insert_wchar(char value) Inserts a char value into the DynAny.
void | _DynSequenceStub.insert_wstring(String value) Inserts a string value into the DynAny.
void | _DynFixedStub.insert_wstring(String value) Inserts a string value into the DynAny.
void | _DynEnumStub.insert_wstring(String value) Inserts a string value into the DynAny.
void | _DynArrayStub.insert_wstring(String value) Inserts a string value into the DynAny.
void | _DynValueStub.insert_wstring(String value) Inserts a string value into the DynAny.
void | _DynAnyStub.insert_wstring(String value) Inserts a string value into the DynAny.
void | _DynUnionStub.insert_wstring(String value) Inserts a string value into the DynAny.
void | _DynStructStub.insert_wstring(String value) Inserts a string value into the DynAny.
void | DynAnyOperations.insert_wstring(String value) Inserts a string value into the DynAny.
void | DynValueBoxOperations.set_boxed_value_as_dyn_any(DynAny boxed) Replaces the boxed value with the value contained in the parameter.
void | DynValueBoxOperations.set_boxed_value(Any boxed) Replaces the boxed value with the specified value.
void | _DynUnionStub.set_discriminator(DynAny d) Sets the discriminator of the DynUnion to the specified value.
void | DynUnionOperations.set_discriminator(DynAny d) Sets the discriminator of the DynUnion to the specified value.
void | _DynSequenceStub.set_elements_as_dyn_any(DynAny[] value) Sets the elements of a sequence using DynAnys.
void | _DynArrayStub.set_elements_as_dyn_any(DynAny[] value) Sets the DynArray to contain the passed elements.
void | DynSequenceOperations.set_elements_as_dyn_any(DynAny[] value) Sets the elements of a sequence using DynAnys.
void | DynArrayOperations.set_elements_as_dyn_any(DynAny[] value) Sets the DynArray to contain the passed elements.
void | _DynSequenceStub.set_elements(Any[] value) Sets the elements of a sequence.
void | _DynArrayStub.set_elements(Any[] value) Sets the DynArray to contain the passed elements.
void | DynSequenceOperations.set_elements(Any[] value) Sets the elements of a sequence.
void | DynArrayOperations.set_elements(Any[] value) Sets the DynArray to contain the passed elements.
void | _DynValueStub.set_members_as_dyn_any(NameDynAnyPair[] value) Initializes the value type's members from a sequence of NameDynAnyPairs.
void | _DynStructStub.set_members_as_dyn_any(NameDynAnyPair[] value) Initializes the struct data value associated with a DynStruct object from a sequence of NameDynAnyPairs.
void | DynValueOperations.set_members_as_dyn_any(NameDynAnyPair[] value) Initializes the value type's members from a sequence of NameDynAnyPairs.
void | DynStructOperations.set_members_as_dyn_any(NameDynAnyPair[] value) Initializes the struct data value associated with a DynStruct object from a sequence of NameDynAnyPairs.
void | _DynValueStub.set_members(NameValuePair[] value) Initializes the value type's members from a sequence of NameValuePairs.
void | _DynStructStub.set_members(NameValuePair[] value) Initializes the struct data value associated with a DynStruct object from a sequence of NameValuePairs.
void | DynValueOperations.set_members(NameValuePair[] value) Initializes the value type's members from a sequence of NameValuePairs.
void | DynStructOperations.set_members(NameValuePair[] value) Initializes the struct data value associated with a DynStruct object from a sequence of NameValuePairs.
void | _DynUnionStub.set_to_default_member() Sets the discriminator to a value that is consistent with the value of the default case of a union.
void | DynUnionOperations.set_to_default_member() Sets the discriminator to a value that is consistent with the value of the default case of a union.
void | _DynUnionStub.set_to_no_active_member() Sets the discriminator to a value that does not correspond to any of the unions case labels.
void | DynUnionOperations.set_to_no_active_member() Sets the discriminator to a value that does not correspond to any of the unions case labels.
boolean | _DynFixedStub.set_value(String val) Sets the value of the DynFixed.
boolean | DynFixedOperations.set_value(String val) Sets the value of the DynFixed.

Uses of TypeMismatch in org.omg.DynamicAny.DynAnyPackage

Methods in org.omg.DynamicAny.DynAnyPackage that return TypeMismatch
static TypeMismatch | TypeMismatchHelper.extract(Any a)
static TypeMismatch | TypeMismatchHelper.read(InputStream istream)

Methods in org.omg.DynamicAny.DynAnyPackage with parameters of type TypeMismatch
static void | TypeMismatchHelper.insert(Any a, TypeMismatch that)
static void | TypeMismatchHelper.write(OutputStream ostream, TypeMismatch value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.DynamicAny.DynAnyPackage.TypeMismatchHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.DynamicAny.DynAnyPackage.TypeMismatchHelper

No usage of org.omg.DynamicAny.DynAnyPackage.TypeMismatchHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


InvalidValue

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny.DynAnyPackage
Class InvalidValue

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.DynamicAny.DynAnyPackage.InvalidValue
All Implemented Interfaces:
Serializable, IDLEntity
public final class InvalidValue
extends UserException

org/omg/DynamicAny/DynAnyPackage/InvalidValue.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/DynamicAny/DynamicAny.idl Wednesday, November 29, 2006 1:57:29 AM GMT-08:00

Constructor Summary
InvalidValue()
InvalidValue(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidValue

public InvalidValue()

InvalidValue

public InvalidValue(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


InvalidValueHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny.DynAnyPackage
Class InvalidValueHelper

java.lang.Object
    extended by  org.omg.DynamicAny.DynAnyPackage.InvalidValueHelper

public abstract class InvalidValueHelper
extends Object

org/omg/DynamicAny/DynAnyPackage/InvalidValueHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/DynamicAny/DynamicAny.idl Wednesday, November 29, 2006 1:57:29 AM GMT-08:00

Constructor Summary
InvalidValueHelper()
Method Summary
static InvalidValue | extract(Any a)
static String | id()
static void | insert(Any a, InvalidValue that)
static InvalidValue | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, InvalidValue value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InvalidValueHelper

public InvalidValueHelper()
Method Detail

insert

public static void insert(Any a,
                          InvalidValue that)

extract

public static InvalidValue extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static InvalidValue read(InputStream istream)

write

public static void write(OutputStream ostream,
                         InvalidValue value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TypeMismatch

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny.DynAnyPackage
Class TypeMismatch

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.DynamicAny.DynAnyPackage.TypeMismatch
All Implemented Interfaces:
Serializable, IDLEntity
public final class TypeMismatch
extends UserException

org/omg/DynamicAny/DynAnyPackage/TypeMismatch.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/DynamicAny/DynamicAny.idl Wednesday, November 29, 2006 1:57:29 AM GMT-08:00

Constructor Summary
TypeMismatch()
TypeMismatch(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TypeMismatch

public TypeMismatch()

TypeMismatch

public TypeMismatch(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TypeMismatchHelper

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny.DynAnyPackage
Class TypeMismatchHelper

java.lang.Object
    extended by  org.omg.DynamicAny.DynAnyPackage.TypeMismatchHelper

public abstract class TypeMismatchHelper
extends Object

org/omg/DynamicAny/DynAnyPackage/TypeMismatchHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/DynamicAny/DynamicAny.idl Wednesday, November 29, 2006 1:57:29 AM GMT-08:00

Constructor Summary
TypeMismatchHelper()
Method Summary
static TypeMismatch | extract(Any a)
static String | id()
static void | insert(Any a, TypeMismatch that)
static TypeMismatch | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, TypeMismatch value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TypeMismatchHelper

public TypeMismatchHelper()
Method Detail

insert

public static void insert(Any a,
                          TypeMismatch that)

extract

public static TypeMismatch extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static TypeMismatch read(InputStream istream)

write

public static void write(OutputStream ostream,
                         TypeMismatch value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


DynAnySeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class DynAnySeqHelper

java.lang.Object
    extended by  org.omg.DynamicAny.DynAnySeqHelper

public abstract class DynAnySeqHelper
extends Object

org/omg/DynamicAny/DynAnySeqHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/DynamicAny/DynamicAny.idl Wednesday, November 29, 2006 1:57:29 AM GMT-08:00

Constructor Summary
DynAnySeqHelper()
Method Summary
static DynAny[] | extract(Any a)
static String | id()
static void | insert(Any a, DynAny[] that)
static DynAny[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, DynAny[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DynAnySeqHelper

public DynAnySeqHelper()
Method Detail

insert

public static void insert(Any a,
                          DynAny[] that)

extract

public static DynAny[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static DynAny[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         DynAny[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynArrayHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class DynArrayHelper

java.lang.Object
    extended by  org.omg.DynamicAny.DynArrayHelper

public abstract class DynArrayHelper
extends Object

DynArray objects support the manipulation of IDL arrays. Note that the dimension of the array is contained in the TypeCode which is accessible through the type attribute. It can also be obtained by calling the component_count operation.

Constructor Summary
DynArrayHelper()
Method Summary
static DynArray | extract(Any a)
static String | id()
static void | insert(Any a, DynArray that)
static DynArray | narrow(Object obj)
static DynArray | read(InputStream istream)
static TypeCode | type()
static DynArray | unchecked_narrow(Object obj)
static void | write(OutputStream ostream, DynArray value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DynArrayHelper

public DynArrayHelper()
Method Detail

insert

public static void insert(Any a,
                          DynArray that)

extract

public static DynArray extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static DynArray read(InputStream istream)

write

public static void write(OutputStream ostream,
                         DynArray value)

narrow

public static DynArray narrow(Object obj)

unchecked_narrow

public static DynArray unchecked_narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynArrayOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynArrayOperations

All Superinterfaces:
DynAnyOperations
All Known Subinterfaces:
DynArray
All Known Implementing Classes:
_DynArrayStub
public interface DynArrayOperations
extends DynAnyOperations

DynArray objects support the manipulation of IDL arrays. Note that the dimension of the array is contained in the TypeCode which is accessible through the type attribute. It can also be obtained by calling the component_count operation.

Method Summary
DynAny[] | get_elements_as_dyn_any() Returns the elements of the DynArray as DynAnys.
Any[] | get_elements() Returns the elements of the DynArray.
void | set_elements_as_dyn_any(DynAny[] value) Sets the DynArray to contain the passed elements.
void | set_elements(Any[] value) Sets the DynArray to contain the passed elements.
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type

Method Detail

get_elements

Any[] get_elements()
Returns the elements of the DynArray.

set_elements

void set_elements(Any[] value)
                  throws TypeMismatch,
                         InvalidValue
Sets the DynArray to contain the passed elements.

Throws:
TypeMismatch - if one or more elements have a type that is inconsistent with the DynArrays TypeCode
InvalidValue - if the sequence does not contain the same number of elements as the array dimension

get_elements_as_dyn_any

DynAny[] get_elements_as_dyn_any()
Returns the elements of the DynArray as DynAnys.

set_elements_as_dyn_any

void set_elements_as_dyn_any(DynAny[] value)
                             throws TypeMismatch,
                                    InvalidValue
Sets the DynArray to contain the passed elements.

Throws:
TypeMismatch - if one or more elements have a type that is inconsistent with the DynArrays TypeCode
InvalidValue - if the sequence does not contain the same number of elements as the array dimension
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynEnumHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class DynEnumHelper

java.lang.Object
    extended by  org.omg.DynamicAny.DynEnumHelper

public abstract class DynEnumHelper
extends Object

DynEnum objects support the manipulation of IDL enumerated values. The current position of a DynEnum is always -1.

Constructor Summary
DynEnumHelper()
Method Summary
static DynEnum | extract(Any a)
static String | id()
static void | insert(Any a, DynEnum that)
static DynEnum | narrow(Object obj)
static DynEnum | read(InputStream istream)
static TypeCode | type()
static DynEnum | unchecked_narrow(Object obj)
static void | write(OutputStream ostream, DynEnum value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DynEnumHelper

public DynEnumHelper()
Method Detail

insert

public static void insert(Any a,
                          DynEnum that)

extract

public static DynEnum extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static DynEnum read(InputStream istream)

write

public static void write(OutputStream ostream,
                         DynEnum value)

narrow

public static DynEnum narrow(Object obj)

unchecked_narrow

public static DynEnum unchecked_narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynEnumOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynEnumOperations

All Superinterfaces:
DynAnyOperations
All Known Subinterfaces:
DynEnum
All Known Implementing Classes:
_DynEnumStub
public interface DynEnumOperations
extends DynAnyOperations

DynEnum objects support the manipulation of IDL enumerated values. The current position of a DynEnum is always -1.

Method Summary
String | get_as_string() Returns the value of the DynEnum as an IDL identifier.
int | get_as_ulong() Returns the value of the DynEnum as the enumerated value's ordinal value.
void | set_as_string(String value) Sets the value of the DynEnum to the enumerated value whose IDL identifier is passed in the value parameter.
void | set_as_ulong(int value) Sets the value of the DynEnum as the enumerated value's ordinal value.
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type

Method Detail

get_as_string

String get_as_string()
Returns the value of the DynEnum as an IDL identifier.

set_as_string

void set_as_string(String value)
                   throws InvalidValue
Sets the value of the DynEnum to the enumerated value whose IDL identifier is passed in the value parameter.

Throws:
InvalidValue - If value contains a string that is not a valid IDL identifier for the corresponding enumerated type

get_as_ulong

int get_as_ulong()
Returns the value of the DynEnum as the enumerated value's ordinal value. Enumerators have ordinal values 0 to n-1, as they appear from left to right in the corresponding IDL definition.

set_as_ulong

void set_as_ulong(int value)
                  throws InvalidValue
Sets the value of the DynEnum as the enumerated value's ordinal value.

Throws:
InvalidValue - If value contains a value that is outside the range of ordinal values for the corresponding enumerated type
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynFixedHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class DynFixedHelper

java.lang.Object
    extended by  org.omg.DynamicAny.DynFixedHelper

public abstract class DynFixedHelper
extends Object

DynFixed objects support the manipulation of IDL fixed values. Because IDL does not have a generic type that can represent fixed types with arbitrary number of digits and arbitrary scale, the operations use the IDL string type.

Constructor Summary
DynFixedHelper()
Method Summary
static DynFixed | extract(Any a)
static String | id()
static void | insert(Any a, DynFixed that)
static DynFixed | narrow(Object obj)
static DynFixed | read(InputStream istream)
static TypeCode | type()
static DynFixed | unchecked_narrow(Object obj)
static void | write(OutputStream ostream, DynFixed value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DynFixedHelper

public DynFixedHelper()
Method Detail

insert

public static void insert(Any a,
                          DynFixed that)

extract

public static DynFixed extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static DynFixed read(InputStream istream)

write

public static void write(OutputStream ostream,
                         DynFixed value)

narrow

public static DynFixed narrow(Object obj)

unchecked_narrow

public static DynFixed unchecked_narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynFixedOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynFixedOperations

All Superinterfaces:
DynAnyOperations
All Known Subinterfaces:
DynFixed
All Known Implementing Classes:
_DynFixedStub
public interface DynFixedOperations
extends DynAnyOperations

DynFixed objects support the manipulation of IDL fixed values. Because IDL does not have a generic type that can represent fixed types with arbitrary number of digits and arbitrary scale, the operations use the IDL string type.

Method Summary
String | get_value() Returns the value of a DynFixed.
boolean | set_value(String val) Sets the value of the DynFixed.
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type

Method Detail

get_value

String get_value()
Returns the value of a DynFixed.

set_value

boolean set_value(String val)
                  throws TypeMismatch,
                         InvalidValue
Sets the value of the DynFixed. The val string must contain a fixed string constant in the same format as used for IDL fixed-point literals. However, the trailing d or D is optional. The return value is true if val can be represented as the DynFixed without loss of precision. If val has more fractional digits than can be represented in the DynFixed, fractional digits are truncated and the return value is false.

Throws:
TypeMismatch - If val does not contain a valid fixed-point literal or contains extraneous characters other than leading or trailing white space
InvalidValue - If val contains a value whose scale exceeds that of the DynFixed or is not initialized
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynSequenceHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class DynSequenceHelper

java.lang.Object
    extended by  org.omg.DynamicAny.DynSequenceHelper

public abstract class DynSequenceHelper
extends Object

DynSequence objects support the manipulation of IDL sequences.

Constructor Summary
DynSequenceHelper()
Method Summary
static DynSequence | extract(Any a)
static String | id()
static void | insert(Any a, DynSequence that)
static DynSequence | narrow(Object obj)
static DynSequence | read(InputStream istream)
static TypeCode | type()
static DynSequence | unchecked_narrow(Object obj)
static void | write(OutputStream ostream, DynSequence value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DynSequenceHelper

public DynSequenceHelper()
Method Detail

insert

public static void insert(Any a,
                          DynSequence that)

extract

public static DynSequence extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static DynSequence read(InputStream istream)

write

public static void write(OutputStream ostream,
                         DynSequence value)

narrow

public static DynSequence narrow(Object obj)

unchecked_narrow

public static DynSequence unchecked_narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynSequenceOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynSequenceOperations

All Superinterfaces:
DynAnyOperations
All Known Subinterfaces:
DynSequence
All Known Implementing Classes:
_DynSequenceStub
public interface DynSequenceOperations
extends DynAnyOperations

DynSequence objects support the manipulation of IDL sequences.

Method Summary
DynAny[] | get_elements_as_dyn_any() Returns the DynAnys representing the elements of the sequence.
Any[] | get_elements() Returns the elements of the sequence.
int | get_length() Returns the current length of the sequence.
void | set_elements_as_dyn_any(DynAny[] value) Sets the elements of a sequence using DynAnys.
void | set_elements(Any[] value) Sets the elements of a sequence.
void | set_length(int len) Sets the length of the sequence.
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type

Method Detail

get_length

int get_length()
Returns the current length of the sequence.

set_length

void set_length(int len)
                throws InvalidValue
Sets the length of the sequence. Increasing the length of a sequence adds new elements at the tail without affecting the values of already existing elements. Newly added elements are default-initialized. Increasing the length of a sequence sets the current position to the first newly-added element if the previous current position was -1. Otherwise, if the previous current position was not -1, the current position is not affected. Decreasing the length of a sequence removes elements from the tail without affecting the value of those elements that remain. The new current position after decreasing the length of a sequence is determined as follows:
  • If the length of the sequence is set to zero, the current position is set to -1.
  • If the current position is -1 before decreasing the length, it remains at -1.
  • If the current position indicates a valid element and that element is not removed when the length is decreased, the current position remains unaffected.
  • If the current position indicates a valid element and that element is removed, the current position is set to -1.

Throws:
InvalidValue - if this is a bounded sequence and len is larger than the bound

get_elements

Any[] get_elements()
Returns the elements of the sequence.

set_elements

void set_elements(Any[] value)
                  throws TypeMismatch,
                         InvalidValue
Sets the elements of a sequence. The length of the DynSequence is set to the length of value. The current position is set to zero if value has non-zero length and to -1 if value is a zero-length sequence.

Throws:
TypeMismatch - if value contains one or more elements whose TypeCode is not equivalent to the element TypeCode of the DynSequence
InvalidValue - if the length of value exceeds the bound of a bounded sequence

get_elements_as_dyn_any

DynAny[] get_elements_as_dyn_any()
Returns the DynAnys representing the elements of the sequence.

set_elements_as_dyn_any

void set_elements_as_dyn_any(DynAny[] value)
                             throws TypeMismatch,
                                    InvalidValue
Sets the elements of a sequence using DynAnys. The length of the DynSequence is set to the length of value. The current position is set to zero if value has non-zero length and to -1 if value is a zero-length sequence.

Throws:
TypeMismatch - if value contains one or more elements whose TypeCode is not equivalent to the element TypeCode of the DynSequence
InvalidValue - if the length of value exceeds the bound of a bounded sequence
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynStructHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class DynStructHelper

java.lang.Object
    extended by  org.omg.DynamicAny.DynStructHelper

public abstract class DynStructHelper
extends Object

DynStruct objects support the manipulation of IDL struct and exception values. Members of the exceptions are handled in the same way as members of a struct.

Constructor Summary
DynStructHelper()
Method Summary
static DynStruct | extract(Any a)
static String | id()
static void | insert(Any a, DynStruct that)
static DynStruct | narrow(Object obj)
static DynStruct | read(InputStream istream)
static TypeCode | type()
static DynStruct | unchecked_narrow(Object obj)
static void | write(OutputStream ostream, DynStruct value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DynStructHelper

public DynStructHelper()
Method Detail

insert

public static void insert(Any a,
                          DynStruct that)

extract

public static DynStruct extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static DynStruct read(InputStream istream)

write

public static void write(OutputStream ostream,
                         DynStruct value)

narrow

public static DynStruct narrow(Object obj)

unchecked_narrow

public static DynStruct unchecked_narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynStructOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynStructOperations

All Superinterfaces:
DynAnyOperations
All Known Subinterfaces:
DynStruct
All Known Implementing Classes:
_DynStructStub
public interface DynStructOperations
extends DynAnyOperations

DynStruct objects support the manipulation of IDL struct and exception values. Members of the exceptions are handled in the same way as members of a struct.

Method Summary
TCKind | current_member_kind() Returns the TCKind associated with the member at the current position.
String | current_member_name() Returns the name of the member at the current position.
NameDynAnyPair[] | get_members_as_dyn_any() Returns a sequence of NameDynAnyPairs describing the name and the value of each member in the struct associated with a DynStruct object.
NameValuePair[] | get_members() Returns a sequence of NameValuePairs describing the name and the value of each member in the struct associated with a DynStruct object.
void | set_members_as_dyn_any(NameDynAnyPair[] value) Initializes the struct data value associated with a DynStruct object from a sequence of NameDynAnyPairs.
void | set_members(NameValuePair[] value) Initializes the struct data value associated with a DynStruct object from a sequence of NameValuePairs.
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type

Method Detail

current_member_name

String current_member_name()
                           throws TypeMismatch,
                                  InvalidValue
Returns the name of the member at the current position. This operation may return an empty string since the TypeCode of the value being manipulated may not contain the names of members.

Throws:
TypeMismatch - if the DynStruct represents an empty exception.
InvalidValue - if the current position does not indicate a member

current_member_kind

TCKind current_member_kind()
                           throws TypeMismatch,
                                  InvalidValue
Returns the TCKind associated with the member at the current position.

Throws:
TypeMismatch - if the DynStruct represents an empty exception.
InvalidValue - if the current position does not indicate a member

get_members

NameValuePair[] get_members()
Returns a sequence of NameValuePairs describing the name and the value of each member in the struct associated with a DynStruct object. The sequence contains members in the same order as the declaration order of members as indicated by the DynStruct's TypeCode. The current position is not affected. The member names in the returned sequence will be empty strings if the DynStruct's TypeCode does not contain member names.

set_members

void set_members(NameValuePair[] value)
                 throws TypeMismatch,
                        InvalidValue
Initializes the struct data value associated with a DynStruct object from a sequence of NameValuePairs. The operation sets the current position to zero if the passed sequences has non-zero length. Otherwise, if an empty sequence is passed, the current position is set to -1.

Members must appear in the NameValuePairs in the order in which they appear in the IDL specification of the struct as indicated by the DynStruct's TypeCode or they must be empty strings. The operation makes no attempt to assign member values based on member names.

Throws:
TypeMismatch - if the member names supplied in the passed sequence do not match the corresponding member name in the DynStruct's TypeCode and they are not empty strings
InvalidValue - if the passed sequence has a number of elements that disagrees with the number of members as indicated by the DynStruct's TypeCode

get_members_as_dyn_any

NameDynAnyPair[] get_members_as_dyn_any()
Returns a sequence of NameDynAnyPairs describing the name and the value of each member in the struct associated with a DynStruct object. The sequence contains members in the same order as the declaration order of members as indicated by the DynStruct's TypeCode. The current position is not affected. The member names in the returned sequence will be empty strings if the DynStruct's TypeCode does not contain member names.

set_members_as_dyn_any

void set_members_as_dyn_any(NameDynAnyPair[] value)
                            throws TypeMismatch,
                                   InvalidValue
Initializes the struct data value associated with a DynStruct object from a sequence of NameDynAnyPairs. The operation sets the current position to zero if the passed sequences has non-zero length. Otherwise, if an empty sequence is passed, the current position is set to -1.

Members must appear in the NameDynAnyPairs in the order in which they appear in the IDL specification of the struct as indicated by the DynStruct's TypeCode or they must be empty strings. The operation makes no attempt to assign member values based on member names.

Throws:
TypeMismatch - if the member names supplied in the passed sequence do not match the corresponding member name in the DynStruct's TypeCode and they are not empty strings
InvalidValue - if the passed sequence has a number of elements that disagrees with the number of members as indicated by the DynStruct's TypeCode
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynUnionHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class DynUnionHelper

java.lang.Object
    extended by  org.omg.DynamicAny.DynUnionHelper

public abstract class DynUnionHelper
extends Object

DynUnion objects support the manipulation of IDL unions. A union can have only two valid current positions:

  • zero, which denotes the discriminator
  • one, which denotes the active member
The component_count value for a union depends on the current discriminator: it is 2 for a union whose discriminator indicates a named member, and 1 otherwise.

Constructor Summary
DynUnionHelper()
Method Summary
static DynUnion | extract(Any a)
static String | id()
static void | insert(Any a, DynUnion that)
static DynUnion | narrow(Object obj)
static DynUnion | read(InputStream istream)
static TypeCode | type()
static DynUnion | unchecked_narrow(Object obj)
static void | write(OutputStream ostream, DynUnion value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DynUnionHelper

public DynUnionHelper()
Method Detail

insert

public static void insert(Any a,
                          DynUnion that)

extract

public static DynUnion extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static DynUnion read(InputStream istream)

write

public static void write(OutputStream ostream,
                         DynUnion value)

narrow

public static DynUnion narrow(Object obj)

unchecked_narrow

public static DynUnion unchecked_narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynUnionOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynUnionOperations

All Superinterfaces:
DynAnyOperations
All Known Subinterfaces:
DynUnion
All Known Implementing Classes:
_DynUnionStub
public interface DynUnionOperations
extends DynAnyOperations

DynUnion objects support the manipulation of IDL unions. A union can have only two valid current positions:

  • zero, which denotes the discriminator
  • one, which denotes the active member
The component_count value for a union depends on the current discriminator: it is 2 for a union whose discriminator indicates a named member, and 1 otherwise.

Method Summary
TCKind | discriminator_kind() Returns the TCKind value of the discriminators TypeCode.
DynAny | get_discriminator() Returns the current discriminator value.
boolean | has_no_active_member() Returns true if the union has no active member, that is, the unions value consists solely of its discriminator because the discriminator has a value that is not listed as an explicit case label.
TCKind | member_kind() Returns the TCKind value of the currently active members TypeCode.
String | member_name() Returns the name of the currently active member.
DynAny | member() Returns the currently active member.
void | set_discriminator(DynAny d) Sets the discriminator of the DynUnion to the specified value.
void | set_to_default_member() Sets the discriminator to a value that is consistent with the value of the default case of a union.
void | set_to_no_active_member() Sets the discriminator to a value that does not correspond to any of the unions case labels.
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type

Method Detail

get_discriminator

DynAny get_discriminator()
Returns the current discriminator value.

set_discriminator

void set_discriminator(DynAny d)
                       throws TypeMismatch
Sets the discriminator of the DynUnion to the specified value. Setting the discriminator to a value that is consistent with the currently active union member does not affect the currently active member. Setting the discriminator to a value that is inconsistent with the currently active member deactivates the member and activates the member that is consistent with the new discriminator value (if there is a member for that value) by initializing the member to its default value. Setting the discriminator of a union sets the current position to 0 if the discriminator value indicates a non-existent union member (has_no_active_member returns true in this case). Otherwise, if the discriminator value indicates a named union member, the current position is set to 1 (has_no_active_member returns false and component_count returns 2 in this case).

Throws:
TypeMismatch - if the TypeCode of the parameter is not equivalent to the TypeCode of the union's discriminator

set_to_default_member

void set_to_default_member()
                           throws TypeMismatch
Sets the discriminator to a value that is consistent with the value of the default case of a union. It sets the current position to zero and causes component_count to return 2.

Throws:
TypeMismatch - if the union does not have an explicit default case

set_to_no_active_member

void set_to_no_active_member()
                             throws TypeMismatch
Sets the discriminator to a value that does not correspond to any of the unions case labels. It sets the current position to zero and causes component_count to return 1.

Throws:
TypeMismatch - if the union has an explicit default case or if it uses the entire range of discriminator values for explicit case labels

has_no_active_member

boolean has_no_active_member()
Returns true if the union has no active member, that is, the unions value consists solely of its discriminator because the discriminator has a value that is not listed as an explicit case label. Calling this operation on a union that has a default case returns false. Calling this operation on a union that uses the entire range of discriminator values for explicit case labels returns false.

discriminator_kind

TCKind discriminator_kind()
Returns the TCKind value of the discriminators TypeCode.

member_kind

TCKind member_kind()
                   throws InvalidValue
Returns the TCKind value of the currently active members TypeCode.

Throws:
InvalidValue - if the union does not have a currently active member

member

DynAny member()
              throws InvalidValue
Returns the currently active member. Note that the returned reference remains valid only for as long as the currently active member does not change. Using the returned reference beyond the life time of the currently active member raises OBJECT_NOT_EXIST.

Throws:
InvalidValue - if the union has no active member

member_name

String member_name()
                   throws InvalidValue
Returns the name of the currently active member. If the unions TypeCode does not contain a member name for the currently active member, the operation returns an empty string.

Throws:
InvalidValue - if the union has no active member
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynValueBoxOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynValueBoxOperations

All Superinterfaces:
DynAnyOperations, DynValueCommonOperations
All Known Subinterfaces:
DynValueBox
public interface DynValueBoxOperations
extends DynValueCommonOperations

DynValueBox objects support the manipulation of IDL boxed value types. The DynValueBox interface can represent both null and non-null value types. For a DynValueBox representing a non-null value type, the DynValueBox has a single component of the boxed type. A DynValueBox representing a null value type has no components and a current position of -1.

Method Summary
DynAny | get_boxed_value_as_dyn_any() Returns the boxed value as a DynAny.
Any | get_boxed_value() Returns the boxed value as an Any.
void | set_boxed_value_as_dyn_any(DynAny boxed) Replaces the boxed value with the value contained in the parameter.
void | set_boxed_value(Any boxed) Replaces the boxed value with the specified value.
Methods inherited from interface org.omg.DynamicAny.DynValueCommonOperations
is_null, set_to_null, set_to_value
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type

Method Detail

get_boxed_value

Any get_boxed_value()
                    throws InvalidValue
Returns the boxed value as an Any.

Throws:
InvalidValue - if this object represents a null value box type

set_boxed_value

void set_boxed_value(Any boxed)
                     throws TypeMismatch
Replaces the boxed value with the specified value. If the DynBoxedValue represents a null valuetype, it is converted to a non-null value.

Throws:
TypeMismatch - if this object represents a non-null value box type and the type of the parameter is not matching the current boxed value type.

get_boxed_value_as_dyn_any

DynAny get_boxed_value_as_dyn_any()
                                  throws InvalidValue
Returns the boxed value as a DynAny.

Throws:
InvalidValue - if this object represents a null value box type

set_boxed_value_as_dyn_any

void set_boxed_value_as_dyn_any(DynAny boxed)
                                throws TypeMismatch
Replaces the boxed value with the value contained in the parameter. If the DynBoxedValue represents a null valuetype, it is converted to a non-null value.

Throws:
TypeMismatch - if this object represents a non-null value box type and the type of the parameter is not matching the current boxed value type.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynValueCommonOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynValueCommonOperations

All Superinterfaces:
DynAnyOperations
All Known Subinterfaces:
DynValue, DynValueBox, DynValueBoxOperations, DynValueCommon, DynValueOperations
All Known Implementing Classes:
_DynValueStub
public interface DynValueCommonOperations
extends DynAnyOperations

DynValueCommon provides operations supported by both the DynValue and DynValueBox interfaces.

Method Summary
boolean | is_null() Returns true if the DynValueCommon represents a null value type.
void | set_to_null() Changes the representation of a DynValueCommon to a null value type.
void | set_to_value() Replaces a null value type with a newly constructed value.
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type

Method Detail

is_null

boolean is_null()
Returns true if the DynValueCommon represents a null value type.

set_to_null

void set_to_null()
Changes the representation of a DynValueCommon to a null value type.

set_to_value

void set_to_value()
Replaces a null value type with a newly constructed value. Its components are initialized to default values as in DynAnyFactory.create_dyn_any_from_type_code. If the DynValueCommon represents a non-null value type, then this operation has no effect.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynValueHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class DynValueHelper

java.lang.Object
    extended by  org.omg.DynamicAny.DynValueHelper

public abstract class DynValueHelper
extends Object

DynValue objects support the manipulation of IDL non-boxed value types. The DynValue interface can represent both null and non-null value types. For a DynValue representing a non-null value type, the DynValue's components comprise the public and private members of the value type, including those inherited from concrete base value types, in the order of definition. A DynValue representing a null value type has no components and a current position of -1.

Warning: Indiscriminantly changing the contents of private value type members can cause the value type implementation to break by violating internal constraints. Access to private members is provided to support such activities as ORB bridging and debugging and should not be used to arbitrarily violate the encapsulation of the value type.

Constructor Summary
DynValueHelper()
Method Summary
static DynValue | extract(Any a)
static String | id()
static void | insert(Any a, DynValue that)
static DynValue | narrow(Object obj)
static DynValue | read(InputStream istream)
static TypeCode | type()
static DynValue | unchecked_narrow(Object obj)
static void | write(OutputStream ostream, DynValue value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DynValueHelper

public DynValueHelper()
Method Detail

insert

public static void insert(Any a,
                          DynValue that)

extract

public static DynValue extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static DynValue read(InputStream istream)

write

public static void write(OutputStream ostream,
                         DynValue value)

narrow

public static DynValue narrow(Object obj)

unchecked_narrow

public static DynValue unchecked_narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DynValueOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Interface DynValueOperations

All Superinterfaces:
DynAnyOperations, DynValueCommonOperations
All Known Subinterfaces:
DynValue
All Known Implementing Classes:
_DynValueStub
public interface DynValueOperations
extends DynValueCommonOperations

DynValue objects support the manipulation of IDL non-boxed value types. The DynValue interface can represent both null and non-null value types. For a DynValue representing a non-null value type, the DynValue's components comprise the public and private members of the value type, including those inherited from concrete base value types, in the order of definition. A DynValue representing a null value type has no components and a current position of -1.

Warning: Indiscriminantly changing the contents of private value type members can cause the value type implementation to break by violating internal constraints. Access to private members is provided to support such activities as ORB bridging and debugging and should not be used to arbitrarily violate the encapsulation of the value type.

Method Summary
TCKind | current_member_kind() Returns the TCKind associated with the member at the current position.
String | current_member_name() Returns the name of the member at the current position.
NameDynAnyPair[] | get_members_as_dyn_any() Returns a sequence of NameDynAnyPairs describing the name and the value of each member in the value type.
NameValuePair[] | get_members() Returns a sequence of NameValuePairs describing the name and the value of each member in the value type.
void | set_members_as_dyn_any(NameDynAnyPair[] value) Initializes the value type's members from a sequence of NameDynAnyPairs.
void | set_members(NameValuePair[] value) Initializes the value type's members from a sequence of NameValuePairs.
Methods inherited from interface org.omg.DynamicAny.DynValueCommonOperations
is_null, set_to_null, set_to_value
Methods inherited from interface org.omg.DynamicAny.DynAnyOperations
assign, component_count, copy, current_component, destroy, equal, from_any, get_any, get_boolean, get_char, get_double, get_dyn_any, get_float, get_long, get_longlong, get_octet, get_reference, get_short, get_string, get_typecode, get_ulong, get_ulonglong, get_ushort, get_val, get_wchar, get_wstring, insert_any, insert_boolean, insert_char, insert_double, insert_dyn_any, insert_float, insert_long, insert_longlong, insert_octet, insert_reference, insert_short, insert_string, insert_typecode, insert_ulong, insert_ulonglong, insert_ushort, insert_val, insert_wchar, insert_wstring, next, rewind, seek, to_any, type

Method Detail

current_member_name

String current_member_name()
                           throws TypeMismatch,
                                  InvalidValue
Returns the name of the member at the current position. This operation may return an empty string since the TypeCode of the value being manipulated may not contain the names of members.

Throws:
TypeMismatch - if the DynValue represents a null value type.
InvalidValue - if the current position does not indicate a member

current_member_kind

TCKind current_member_kind()
                           throws TypeMismatch,
                                  InvalidValue
Returns the TCKind associated with the member at the current position.

Throws:
TypeMismatch - if the DynValue represents a null value type.
InvalidValue - if the current position does not indicate a member

get_members

NameValuePair[] get_members()
                            throws InvalidValue
Returns a sequence of NameValuePairs describing the name and the value of each member in the value type. The sequence contains members in the same order as the declaration order of members as indicated by the DynValue's TypeCode. The current position is not affected. The member names in the returned sequence will be empty strings if the DynValue's TypeCode does not contain member names.

Throws:
InvalidValue - if this object represents a null value type

set_members

void set_members(NameValuePair[] value)
                 throws TypeMismatch,
                        InvalidValue
Initializes the value type's members from a sequence of NameValuePairs. The operation sets the current position to zero if the passed sequences has non-zero length. Otherwise, if an empty sequence is passed, the current position is set to -1. A null value type can be initialized to a non-null value type using this method.

Members must appear in the NameValuePairs in the order in which they appear in the IDL specification of the value type as indicated by the DynValue's TypeCode or they must be empty strings. The operation makes no attempt to assign member values based on member names.

Throws:
TypeMismatch - if the member names supplied in the passed sequence do not match the corresponding member name in the DynValue's TypeCode and they are not empty strings
InvalidValue - if the passed sequence has a number of elements that disagrees with the number of members as indicated by the DynValue's TypeCode

get_members_as_dyn_any

NameDynAnyPair[] get_members_as_dyn_any()
                                        throws InvalidValue
Returns a sequence of NameDynAnyPairs describing the name and the value of each member in the value type. The sequence contains members in the same order as the declaration order of members as indicated by the DynValue's TypeCode. The current position is not affected. The member names in the returned sequence will be empty strings if the DynValue's TypeCode does not contain member names.

Throws:
InvalidValue - if this object represents a null value type

set_members_as_dyn_any

void set_members_as_dyn_any(NameDynAnyPair[] value)
                            throws TypeMismatch,
                                   InvalidValue
Initializes the value type's members from a sequence of NameDynAnyPairs. The operation sets the current position to zero if the passed sequences has non-zero length. Otherwise, if an empty sequence is passed, the current position is set to -1. A null value type can be initialized to a non-null value type using this method.

Members must appear in the NameDynAnyPairs in the order in which they appear in the IDL specification of the value type as indicated by the DynValue's TypeCode or they must be empty strings. The operation makes no attempt to assign member values based on member names.

Throws:
TypeMismatch - if the member names supplied in the passed sequence do not match the corresponding member name in the DynValue's TypeCode and they are not empty strings
InvalidValue - if the passed sequence has a number of elements that disagrees with the number of members as indicated by the DynValue's TypeCode
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FieldNameHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class FieldNameHelper

java.lang.Object
    extended by  org.omg.DynamicAny.FieldNameHelper

public abstract class FieldNameHelper
extends Object

org/omg/DynamicAny/FieldNameHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/DynamicAny/DynamicAny.idl Wednesday, November 29, 2006 1:57:29 AM GMT-08:00

Constructor Summary
FieldNameHelper()
Method Summary
static String | extract(Any a)
static String | id()
static void | insert(Any a, String that)
static String | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, String value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FieldNameHelper

public FieldNameHelper()
Method Detail

insert

public static void insert(Any a,
                          String that)

extract

public static String extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static String read(InputStream istream)

write

public static void write(OutputStream ostream,
                         String value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameDynAnyPair

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class NameDynAnyPair

java.lang.Object
    extended by  org.omg.DynamicAny.NameDynAnyPair
All Implemented Interfaces:
Serializable, IDLEntity
public final class NameDynAnyPair
extends Object
implements IDLEntity

org/omg/DynamicAny/NameDynAnyPair.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/DynamicAny/DynamicAny.idl Wednesday, November 29, 2006 1:57:29 AM GMT-08:00

Field Summary
String | id The name associated with the DynAny.
DynAny | value The DynAny value associated with the name.
Constructor Summary
NameDynAnyPair()
NameDynAnyPair(String _id, DynAny _value)
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

id

public String id
The name associated with the DynAny.

value

public DynAny value
The DynAny value associated with the name.

Constructor Detail

NameDynAnyPair

public NameDynAnyPair()

NameDynAnyPair

public NameDynAnyPair(String _id,
                      DynAny _value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameDynAnyPairHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class NameDynAnyPairHelper

java.lang.Object
    extended by  org.omg.DynamicAny.NameDynAnyPairHelper

public abstract class NameDynAnyPairHelper
extends Object

org/omg/DynamicAny/NameDynAnyPairHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/DynamicAny/DynamicAny.idl Wednesday, November 29, 2006 1:57:29 AM GMT-08:00

Constructor Summary
NameDynAnyPairHelper()
Method Summary
static NameDynAnyPair | extract(Any a)
static String | id()
static void | insert(Any a, NameDynAnyPair that)
static NameDynAnyPair | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, NameDynAnyPair value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NameDynAnyPairHelper

public NameDynAnyPairHelper()
Method Detail

insert

public static void insert(Any a,
                          NameDynAnyPair that)

extract

public static NameDynAnyPair extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static NameDynAnyPair read(InputStream istream)

write

public static void write(OutputStream ostream,
                         NameDynAnyPair value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameDynAnyPairSeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class NameDynAnyPairSeqHelper

java.lang.Object
    extended by  org.omg.DynamicAny.NameDynAnyPairSeqHelper

public abstract class NameDynAnyPairSeqHelper
extends Object

org/omg/DynamicAny/NameDynAnyPairSeqHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/DynamicAny/DynamicAny.idl Wednesday, November 29, 2006 1:57:29 AM GMT-08:00

Constructor Summary
NameDynAnyPairSeqHelper()
Method Summary
static NameDynAnyPair[] | extract(Any a)
static String | id()
static void | insert(Any a, NameDynAnyPair[] that)
static NameDynAnyPair[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, NameDynAnyPair[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NameDynAnyPairSeqHelper

public NameDynAnyPairSeqHelper()
Method Detail

insert

public static void insert(Any a,
                          NameDynAnyPair[] that)

extract

public static NameDynAnyPair[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static NameDynAnyPair[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         NameDynAnyPair[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameValuePair

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class NameValuePair

java.lang.Object
    extended by  org.omg.DynamicAny.NameValuePair
All Implemented Interfaces:
Serializable, IDLEntity
public final class NameValuePair
extends Object
implements IDLEntity

org/omg/DynamicAny/NameValuePair.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/DynamicAny/DynamicAny.idl Wednesday, November 29, 2006 1:57:29 AM GMT-08:00

Field Summary
String | id The name associated with the Any.
Any | value The Any value associated with the name.
Constructor Summary
NameValuePair()
NameValuePair(String _id, Any _value)
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

id

public String id
The name associated with the Any.

value

public Any value
The Any value associated with the name.

Constructor Detail

NameValuePair

public NameValuePair()

NameValuePair

public NameValuePair(String _id,
                     Any _value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameValuePairHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class NameValuePairHelper

java.lang.Object
    extended by  org.omg.DynamicAny.NameValuePairHelper

public abstract class NameValuePairHelper
extends Object

org/omg/DynamicAny/NameValuePairHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/DynamicAny/DynamicAny.idl Wednesday, November 29, 2006 1:57:29 AM GMT-08:00

Constructor Summary
NameValuePairHelper()
Method Summary
static NameValuePair | extract(Any a)
static String | id()
static void | insert(Any a, NameValuePair that)
static NameValuePair | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, NameValuePair value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NameValuePairHelper

public NameValuePairHelper()
Method Detail

insert

public static void insert(Any a,
                          NameValuePair that)

extract

public static NameValuePair extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static NameValuePair read(InputStream istream)

write

public static void write(OutputStream ostream,
                         NameValuePair value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameValuePairSeqHelper

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.DynamicAny
Class NameValuePairSeqHelper

java.lang.Object
    extended by  org.omg.DynamicAny.NameValuePairSeqHelper

public abstract class NameValuePairSeqHelper
extends Object

org/omg/DynamicAny/NameValuePairSeqHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/DynamicAny/DynamicAny.idl Wednesday, November 29, 2006 1:57:29 AM GMT-08:00

Constructor Summary
NameValuePairSeqHelper()
Method Summary
static NameValuePair[] | extract(Any a)
static String | id()
static void | insert(Any a, NameValuePair[] that)
static NameValuePair[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, NameValuePair[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NameValuePairSeqHelper

public NameValuePairSeqHelper()
Method Detail

insert

public static void insert(Any a,
                          NameValuePair[] that)

extract

public static NameValuePair[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static NameValuePair[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         NameValuePair[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


IOP

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.IOP

This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.

See:
Description

Interface Summary
Codec | The formats of IOR components and service context data used by ORB services are often defined as CDR encapsulations encoding instances of IDL defined data types.
CodecFactory | Codecs are obtained from the CodecFactory.
CodecFactoryOperations | Codecs are obtained from the CodecFactory.
CodecOperations | The formats of IOR components and service context data used by ORB services are often defined as CDR encapsulations encoding instances of IDL defined data types.
CodeSets | org/omg/IOP/CodeSets.java .
ENCODING_CDR_ENCAPS | org/omg/IOP/ENCODING_CDR_ENCAPS.java .
ExceptionDetailMessage | org/omg/IOP/ExceptionDetailMessage.java .
RMICustomMaxStreamFormat | org/omg/IOP/RMICustomMaxStreamFormat.java .
TAG_ALTERNATE_IIOP_ADDRESS | org/omg/IOP/TAG_ALTERNATE_IIOP_ADDRESS.java .
TAG_CODE_SETS | org/omg/IOP/TAG_CODE_SETS.java .
TAG_INTERNET_IOP | org/omg/IOP/TAG_INTERNET_IOP.java .
TAG_JAVA_CODEBASE | org/omg/IOP/TAG_JAVA_CODEBASE.java .
TAG_MULTIPLE_COMPONENTS | org/omg/IOP/TAG_MULTIPLE_COMPONENTS.java .
TAG_ORB_TYPE | org/omg/IOP/TAG_ORB_TYPE.java .
TAG_POLICIES | org/omg/IOP/TAG_POLICIES.java .
TAG_RMI_CUSTOM_MAX_STREAM_FORMAT | org/omg/IOP/TAG_RMI_CUSTOM_MAX_STREAM_FORMAT.java .
TransactionService | org/omg/IOP/TransactionService.java .

Class Summary
CodecFactoryHelper | Codecs are obtained from the CodecFactory.
ComponentIdHelper | Standard way of representing multicomponent profiles.
Encoding | org/omg/IOP/Encoding.java .
IOR | org/omg/IOP/IOR.java .
IORHelper | org/omg/IOP/IORHelper.java .
IORHolder | org/omg/IOP/IORHolder.java .
MultipleComponentProfileHelper | An array of tagged components, forming a multiple component profile.
MultipleComponentProfileHolder | An array of tagged components, forming a multiple component profile.
ProfileIdHelper | Profile ID
ServiceContext | org/omg/IOP/ServiceContext.java .
ServiceContextHelper | org/omg/IOP/ServiceContextHelper.java .
ServiceContextHolder | org/omg/IOP/ServiceContextHolder.java .
ServiceContextListHelper | An array of service contexts, forming a service context list.
ServiceContextListHolder | An array of service contexts, forming a service context list.
ServiceIdHelper | A service id, represented as an int
TaggedComponent | org/omg/IOP/TaggedComponent.java .
TaggedComponentHelper | org/omg/IOP/TaggedComponentHelper.java .
TaggedComponentHolder | org/omg/IOP/TaggedComponentHolder.java .
TaggedProfile | org/omg/IOP/TaggedProfile.java .
TaggedProfileHelper | org/omg/IOP/TaggedProfileHelper.java .
TaggedProfileHolder | org/omg/IOP/TaggedProfileHolder.java .

Package org.omg.IOP Description

This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6. Please refer to that OMG specification for further details.

Please note that we do not provide all parts of the IOP module from the specification. We only provide those parts that are referenced as return values or parameter types in public APIs, most notably, Portable Interceptors.

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6 ORB complies, see Official Specifications for CORBA support in Java[tm] SE 6.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


Codec

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Interface Codec

All Superinterfaces:
CodecOperations, IDLEntity, Object, Serializable
public interface Codec
extends CodecOperations, Object, IDLEntity

The formats of IOR components and service context data used by ORB services are often defined as CDR encapsulations encoding instances of IDL defined data types. The Codec provides a mechanism to transfer these components between their IDL data types and their CDR encapsulation representations.

A Codec is obtained from the CodecFactory. The CodecFactory is obtained through a call to ORB.resolve_initial_references( "CodecFactory" ).

Method Summary
Methods inherited from interface org.omg.IOP.CodecOperations
decode_value, decode, encode_value, encode
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


CodecFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Interface CodecFactory

All Superinterfaces:
CodecFactoryOperations, IDLEntity, Object, Serializable
public interface CodecFactory
extends CodecFactoryOperations, Object, IDLEntity

Codecs are obtained from the CodecFactory. The CodecFactory is obtained through a call to ORB.resolve_initial_references( "CodecFactory" ).

Method Summary
Methods inherited from interface org.omg.IOP.CodecFactoryOperations
create_codec
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


org.omg.IOP Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.IOP

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.IOP.CodecFactoryHelper
    • org.omg.IOP.ComponentIdHelper
    • org.omg.IOP.Encoding (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.IOP.IOR (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.IOP.IORHelper
    • org.omg.IOP.IORHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.IOP.MultipleComponentProfileHelper
    • org.omg.IOP.MultipleComponentProfileHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.IOP.ProfileIdHelper
    • org.omg.IOP.ServiceContext (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.IOP.ServiceContextHelper
    • org.omg.IOP.ServiceContextHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.IOP.ServiceContextListHelper
    • org.omg.IOP.ServiceContextListHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.IOP.ServiceIdHelper
    • org.omg.IOP.TaggedComponent (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.IOP.TaggedComponentHelper
    • org.omg.IOP.TaggedComponentHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.IOP.TaggedProfile (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.IOP.TaggedProfileHelper
    • org.omg.IOP.TaggedProfileHolder (implements org.omg.CORBA.portable.Streamable)

Interface Hierarchy

  • org.omg.IOP.CodecFactoryOperations
    • org.omg.IOP.CodecFactory (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
  • org.omg.IOP.CodecOperations
    • org.omg.IOP.Codec (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
  • org.omg.IOP.CodeSets
  • org.omg.IOP.ENCODING_CDR_ENCAPS
  • org.omg.IOP.ExceptionDetailMessage
  • org.omg.CORBA.Object
    • org.omg.IOP.Codec (also extends org.omg.IOP.CodecOperations, org.omg.CORBA.portable.IDLEntity)
    • org.omg.IOP.CodecFactory (also extends org.omg.IOP.CodecFactoryOperations, org.omg.CORBA.portable.IDLEntity)
  • org.omg.IOP.RMICustomMaxStreamFormat
  • java.io.Serializable
    • org.omg.CORBA.portable.IDLEntity
      • org.omg.IOP.Codec (also extends org.omg.IOP.CodecOperations, org.omg.CORBA.Object)
      • org.omg.IOP.CodecFactory (also extends org.omg.IOP.CodecFactoryOperations, org.omg.CORBA.Object)
  • org.omg.IOP.TAG_ALTERNATE_IIOP_ADDRESS
  • org.omg.IOP.TAG_CODE_SETS
  • org.omg.IOP.TAG_INTERNET_IOP
  • org.omg.IOP.TAG_JAVA_CODEBASE
  • org.omg.IOP.TAG_MULTIPLE_COMPONENTS
  • org.omg.IOP.TAG_ORB_TYPE
  • org.omg.IOP.TAG_POLICIES
  • org.omg.IOP.TAG_RMI_CUSTOM_MAX_STREAM_FORMAT
  • org.omg.IOP.TransactionService
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.IOP

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.IOP

Packages that use org.omg.IOP
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Classes in org.omg.IOP used by org.omg.IOP
Codec
The formats of IOR components and service context data used by ORB services are often defined as CDR encapsulations encoding instances of IDL defined data types.
CodecFactory
Codecs are obtained from the CodecFactory.
CodecFactoryOperations
Codecs are obtained from the CodecFactory.
CodecOperations
The formats of IOR components and service context data used by ORB services are often defined as CDR encapsulations encoding instances of IDL defined data types.
Encoding
org/omg/IOP/Encoding.java .
IOR
org/omg/IOP/IOR.java .
ServiceContext
org/omg/IOP/ServiceContext.java .
TaggedComponent
org/omg/IOP/TaggedComponent.java .
TaggedProfile
org/omg/IOP/TaggedProfile.java .

Classes in org.omg.IOP used by org.omg.PortableInterceptor
CodecFactory
Codecs are obtained from the CodecFactory.
ServiceContext
org/omg/IOP/ServiceContext.java .
TaggedComponent
org/omg/IOP/TaggedComponent.java .
TaggedProfile
org/omg/IOP/TaggedProfile.java .

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.CodecFactoryHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.CodecFactoryHelper

No usage of org.omg.IOP.CodecFactoryHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.ComponentIdHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.ComponentIdHelper

No usage of org.omg.IOP.ComponentIdHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.Encoding

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.Encoding

Packages that use Encoding
org.omg.IOP This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.

Uses of Encoding in org.omg.IOP

Methods in org.omg.IOP with parameters of type Encoding
 Codec CodecFactoryOperations.create_codec(Encoding enc)
Create a Codec of the given encoding.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.IOR

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.IOR

Packages that use IOR
org.omg.IOP This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.

Uses of IOR in org.omg.IOP

Fields in org.omg.IOP declared as IOR
 IOR IORHolder.value

Methods in org.omg.IOP that return IOR
static IOR | IORHelper.extract(Any a)
static IOR | IORHelper.read(InputStream istream)

Methods in org.omg.IOP with parameters of type IOR
static void | IORHelper.insert(Any a, IOR that)
static void | IORHelper.write(OutputStream ostream, IOR value)

Constructors in org.omg.IOP with parameters of type IOR
IORHolder(IOR initialValue)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.IORHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.IORHelper

No usage of org.omg.IOP.IORHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.IORHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.IORHolder

No usage of org.omg.IOP.IORHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.MultipleComponentProfileHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.MultipleComponentProfileHelper

No usage of org.omg.IOP.MultipleComponentProfileHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.MultipleComponentProfileHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.MultipleComponentProfileHolder

No usage of org.omg.IOP.MultipleComponentProfileHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.ProfileIdHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.ProfileIdHelper

No usage of org.omg.IOP.ProfileIdHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.ServiceContext

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.ServiceContext

Packages that use ServiceContext
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of ServiceContext in org.omg.IOP

Fields in org.omg.IOP declared as ServiceContext
ServiceContext[] | ServiceContextListHolder.value
ServiceContext | ServiceContextHolder.value

Methods in org.omg.IOP that return ServiceContext
static ServiceContext[] | ServiceContextListHelper.extract(Any a)
static ServiceContext | ServiceContextHelper.extract(Any a)
static ServiceContext[] | ServiceContextListHelper.read(InputStream istream)
static ServiceContext | ServiceContextHelper.read(InputStream istream)

Methods in org.omg.IOP with parameters of type ServiceContext
static void | ServiceContextHelper.insert(Any a, ServiceContext that)
static void | ServiceContextListHelper.insert(Any a, ServiceContext[] that)
static void | ServiceContextHelper.write(OutputStream ostream, ServiceContext value)
static void | ServiceContextListHelper.write(OutputStream ostream, ServiceContext[] value)

Constructors in org.omg.IOP with parameters of type ServiceContext
ServiceContextHolder(ServiceContext initialValue)
ServiceContextListHolder(ServiceContext[] initialValue)

Uses of ServiceContext in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor that return ServiceContext
ServiceContext | RequestInfoOperations.get_reply_service_context(int id) Returns a copy of the service context with the given ID that is associated with the reply.
ServiceContext | RequestInfoOperations.get_request_service_context(int id) Returns a copy of the service context with the given ID that is associated with the request.

Methods in org.omg.PortableInterceptor with parameters of type ServiceContext
void | ServerRequestInfoOperations.add_reply_service_context(ServiceContext service_context, boolean replace) Allows Interceptors to add service contexts to the request.
void | ClientRequestInfoOperations.add_request_service_context(ServiceContext service_context, boolean replace) Allows Interceptors to add service contexts to the request.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.ServiceContextHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.ServiceContextHelper

No usage of org.omg.IOP.ServiceContextHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.ServiceContextHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.ServiceContextHolder

No usage of org.omg.IOP.ServiceContextHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.ServiceContextListHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.ServiceContextListHelper

No usage of org.omg.IOP.ServiceContextListHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.ServiceContextListHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.ServiceContextListHolder

No usage of org.omg.IOP.ServiceContextListHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.ServiceIdHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.ServiceIdHelper

No usage of org.omg.IOP.ServiceIdHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.TaggedComponent

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.TaggedComponent

Packages that use TaggedComponent
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of TaggedComponent in org.omg.IOP

Fields in org.omg.IOP declared as TaggedComponent
TaggedComponent | TaggedComponentHolder.value
TaggedComponent[] | MultipleComponentProfileHolder.value

Methods in org.omg.IOP that return TaggedComponent
static TaggedComponent | TaggedComponentHelper.extract(Any a)
static TaggedComponent[] | MultipleComponentProfileHelper.extract(Any a)
static TaggedComponent | TaggedComponentHelper.read(InputStream istream)
static TaggedComponent[] | MultipleComponentProfileHelper.read(InputStream istream)

Methods in org.omg.IOP with parameters of type TaggedComponent
static void | TaggedComponentHelper.insert(Any a, TaggedComponent that)
static void | MultipleComponentProfileHelper.insert(Any a, TaggedComponent[] that)
static void | TaggedComponentHelper.write(OutputStream ostream, TaggedComponent value)
static void | MultipleComponentProfileHelper.write(OutputStream ostream, TaggedComponent[] value)

Constructors in org.omg.IOP with parameters of type TaggedComponent
MultipleComponentProfileHolder(TaggedComponent[] initialValue)
TaggedComponentHolder(TaggedComponent initialValue)

Uses of TaggedComponent in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor that return TaggedComponent
TaggedComponent | ClientRequestInfoOperations.get_effective_component(int id) Returns the IOP.TaggedComponent with the given ID from the profile selected for this request.
TaggedComponent[] | ClientRequestInfoOperations.get_effective_components(int id) Returns an array of all tagged components with the given ID from the profile selected for this request.

Methods in org.omg.PortableInterceptor with parameters of type TaggedComponent
void | IORInfoOperations.add_ior_component_to_profile(TaggedComponent tagged_component, int profile_id) A portable ORB service implementation calls add_ior_component_to_profile from its implementation of establish_components to add a tagged component to the set which will be included when constructing IORs.
void | IORInfoOperations.add_ior_component(TaggedComponent tagged_component) A portable ORB service implementation calls add_ior_component from its implementation of establish_components to add a tagged component to the set which will be included when constructing IORs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.TaggedComponentHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.TaggedComponentHelper

No usage of org.omg.IOP.TaggedComponentHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.TaggedComponentHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.TaggedComponentHolder

No usage of org.omg.IOP.TaggedComponentHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.TaggedProfile

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.TaggedProfile

Packages that use TaggedProfile
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of TaggedProfile in org.omg.IOP

Fields in org.omg.IOP declared as TaggedProfile
TaggedProfile[] | IOR.profiles An array of tagged profiles associated with this object reference.
TaggedProfile | TaggedProfileHolder.value

Methods in org.omg.IOP that return TaggedProfile
static TaggedProfile | TaggedProfileHelper.extract(Any a)
static TaggedProfile | TaggedProfileHelper.read(InputStream istream)

Methods in org.omg.IOP with parameters of type TaggedProfile
static void | TaggedProfileHelper.insert(Any a, TaggedProfile that)
static void | TaggedProfileHelper.write(OutputStream ostream, TaggedProfile value)

Constructors in org.omg.IOP with parameters of type TaggedProfile
IOR(String _type_id, TaggedProfile[] _profiles)
TaggedProfileHolder(TaggedProfile initialValue)

Uses of TaggedProfile in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor that return TaggedProfile
 TaggedProfile ClientRequestInfoOperations.effective_profile()
Returns the profile that will be used to send the request.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.TaggedProfileHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.TaggedProfileHelper

No usage of org.omg.IOP.TaggedProfileHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.TaggedProfileHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.TaggedProfileHolder

No usage of org.omg.IOP.TaggedProfileHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.IOP.Codec

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.IOP.Codec

Packages that use Codec
org.omg.IOP This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.

Uses of Codec in org.omg.IOP

Methods in org.omg.IOP that return Codec
 Codec CodecFactoryOperations.create_codec(Encoding enc)
Create a Codec of the given encoding.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.IOP.CodecFactory

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.IOP.CodecFactory

Packages that use CodecFactory
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of CodecFactory in org.omg.IOP

Methods in org.omg.IOP that return CodecFactory
static CodecFactory | CodecFactoryHelper.extract(Any a)
static CodecFactory | CodecFactoryHelper.narrow(Object obj)
static CodecFactory | CodecFactoryHelper.read(InputStream istream)
static CodecFactory | CodecFactoryHelper.unchecked_narrow(Object obj)

Methods in org.omg.IOP with parameters of type CodecFactory
static void | CodecFactoryHelper.insert(Any a, CodecFactory that)
static void | CodecFactoryHelper.write(OutputStream ostream, CodecFactory value)

Uses of CodecFactory in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor that return CodecFactory
 CodecFactory ORBInitInfoOperations.codec_factory()
Returns the IOP.CodecFactory.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.IOP.CodecFactoryOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.IOP.CodecFactoryOperations

Packages that use CodecFactoryOperations
org.omg.IOP This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.

Uses of CodecFactoryOperations in org.omg.IOP

Subinterfaces of CodecFactoryOperations in org.omg.IOP
 interface CodecFactory
Codecs are obtained from the CodecFactory.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.IOP.CodecOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.IOP.CodecOperations

Packages that use CodecOperations
org.omg.IOP This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.

Uses of CodecOperations in org.omg.IOP

Subinterfaces of CodecOperations in org.omg.IOP
 interface Codec
The formats of IOR components and service context data used by ORB services are often defined as CDR encapsulations encoding instances of IDL defined data types.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.IOP.CodeSets

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.IOP.CodeSets

No usage of org.omg.IOP.CodeSets

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.IOP.ENCODING_CDR_ENCAPS

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.IOP.ENCODING_CDR_ENCAPS

No usage of org.omg.IOP.ENCODING_CDR_ENCAPS

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.IOP.ExceptionDetailMessage

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.IOP.ExceptionDetailMessage

No usage of org.omg.IOP.ExceptionDetailMessage

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.IOP.RMICustomMaxStreamFormat

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.IOP.RMICustomMaxStreamFormat

No usage of org.omg.IOP.RMICustomMaxStreamFormat

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.IOP.TAG_ALTERNATE_IIOP_ADDRESS

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.IOP.TAG_ALTERNATE_IIOP_ADDRESS

No usage of org.omg.IOP.TAG_ALTERNATE_IIOP_ADDRESS

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.IOP.TAG_CODE_SETS

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.IOP.TAG_CODE_SETS

No usage of org.omg.IOP.TAG_CODE_SETS

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.IOP.TAG_INTERNET_IOP

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.IOP.TAG_INTERNET_IOP

No usage of org.omg.IOP.TAG_INTERNET_IOP

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.IOP.TAG_JAVA_CODEBASE

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.IOP.TAG_JAVA_CODEBASE

No usage of org.omg.IOP.TAG_JAVA_CODEBASE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.IOP.TAG_MULTIPLE_COMPONENTS

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.IOP.TAG_MULTIPLE_COMPONENTS

No usage of org.omg.IOP.TAG_MULTIPLE_COMPONENTS

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.IOP.TAG_ORB_TYPE

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.IOP.TAG_ORB_TYPE

No usage of org.omg.IOP.TAG_ORB_TYPE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.IOP.TAG_POLICIES

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.IOP.TAG_POLICIES

No usage of org.omg.IOP.TAG_POLICIES

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.IOP.TAG_RMI_CUSTOM_MAX_STREAM_FORMAT

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.IOP.TAG_RMI_CUSTOM_MAX_STREAM_FORMAT

No usage of org.omg.IOP.TAG_RMI_CUSTOM_MAX_STREAM_FORMAT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.IOP.TransactionService

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.IOP.TransactionService

No usage of org.omg.IOP.TransactionService

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


CodecFactoryHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class CodecFactoryHelper

java.lang.Object
    extended by  org.omg.IOP.CodecFactoryHelper

public abstract class CodecFactoryHelper
extends Object

Codecs are obtained from the CodecFactory. The CodecFactory is obtained through a call to ORB.resolve_initial_references( "CodecFactory" ).

Constructor Summary
CodecFactoryHelper()
Method Summary
static CodecFactory | extract(Any a)
static String | id()
static void | insert(Any a, CodecFactory that)
static CodecFactory | narrow(Object obj)
static CodecFactory | read(InputStream istream)
static TypeCode | type()
static CodecFactory | unchecked_narrow(Object obj)
static void | write(OutputStream ostream, CodecFactory value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CodecFactoryHelper

public CodecFactoryHelper()
Method Detail

insert

public static void insert(Any a,
                          CodecFactory that)

extract

public static CodecFactory extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static CodecFactory read(InputStream istream)

write

public static void write(OutputStream ostream,
                         CodecFactory value)

narrow

public static CodecFactory narrow(Object obj)

unchecked_narrow

public static CodecFactory unchecked_narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CodecFactoryOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Interface CodecFactoryOperations

All Known Subinterfaces:
CodecFactory
public interface CodecFactoryOperations

Codecs are obtained from the CodecFactory. The CodecFactory is obtained through a call to ORB.resolve_initial_references( "CodecFactory" ).

Method Summary
 Codec create_codec(Encoding enc)
Create a Codec of the given encoding.

Method Detail

create_codec

Codec create_codec(Encoding enc)
                   throws UnknownEncoding
Create a Codec of the given encoding.

Parameters:
enc - The encoding for which to create a Codec.
Returns:
A Codec obtained with the given encoding.
Throws:
UnknownEncoding - thrown if this factory cannot create a Codec of the given encoding.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CodecFactoryPackage

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.IOP.CodecFactoryPackage

This package contains the exceptions specified in the IOP::CodeFactory interface (as part of the Portable Interceptors spec).

See:
Description

Class Summary
UnknownEncodingHelper org/omg/IOP/CodecFactoryPackage/UnknownEncodingHelper.java .

Exception Summary
UnknownEncoding org/omg/IOP/CodecFactoryPackage/UnknownEncoding.java .

Package org.omg.IOP.CodecFactoryPackage Description

This package contains the exceptions specified in the IOP::CodeFactory interface (as part of the Portable Interceptors spec).

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6 ORB complies, see Official Specifications for CORBA support in Java SE 6.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.IOP.CodecFactoryPackage Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.IOP.CodecFactoryPackage

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.omg.CORBA.UserException (implements org.omg.CORBA.portable.IDLEntity)
          • org.omg.IOP.CodecFactoryPackage.UnknownEncoding
    • org.omg.IOP.CodecFactoryPackage.UnknownEncodingHelper
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.IOP.CodecFactoryPackage

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.IOP.CodecFactoryPackage

Packages that use org.omg.IOP.CodecFactoryPackage
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.IOP.CodecFactoryPackage | This package contains the exceptions specified in the IOP::CodeFactory interface (as part of the Portable Interceptors spec).

Classes in org.omg.IOP.CodecFactoryPackage used by org.omg.IOP
UnknownEncoding
org/omg/IOP/CodecFactoryPackage/UnknownEncoding.java .

Classes in org.omg.IOP.CodecFactoryPackage used by org.omg.IOP.CodecFactoryPackage
UnknownEncoding
org/omg/IOP/CodecFactoryPackage/UnknownEncoding.java .

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.CodecFactoryPackage.UnknownEncoding

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.CodecFactoryPackage.UnknownEncoding

Packages that use UnknownEncoding
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.IOP.CodecFactoryPackage | This package contains the exceptions specified in the IOP::CodeFactory interface (as part of the Portable Interceptors spec).

Uses of UnknownEncoding in org.omg.IOP

Methods in org.omg.IOP that throw UnknownEncoding
 Codec CodecFactoryOperations.create_codec(Encoding enc)
Create a Codec of the given encoding.

Uses of UnknownEncoding in org.omg.IOP.CodecFactoryPackage

Methods in org.omg.IOP.CodecFactoryPackage that return UnknownEncoding
static UnknownEncoding | UnknownEncodingHelper.extract(Any a)
static UnknownEncoding | UnknownEncodingHelper.read(InputStream istream)

Methods in org.omg.IOP.CodecFactoryPackage with parameters of type UnknownEncoding
static void | UnknownEncodingHelper.insert(Any a, UnknownEncoding that)
static void | UnknownEncodingHelper.write(OutputStream ostream, UnknownEncoding value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.CodecFactoryPackage.UnknownEncodingHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.CodecFactoryPackage.UnknownEncodingHelper

No usage of org.omg.IOP.CodecFactoryPackage.UnknownEncodingHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


UnknownEncoding

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP.CodecFactoryPackage
Class UnknownEncoding

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.IOP.CodecFactoryPackage.UnknownEncoding
All Implemented Interfaces:
Serializable, IDLEntity
public final class UnknownEncoding
extends UserException

org/omg/IOP/CodecFactoryPackage/UnknownEncoding.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:23 AM GMT-08:00

Constructor Summary
UnknownEncoding()
UnknownEncoding(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

UnknownEncoding

public UnknownEncoding()

UnknownEncoding

public UnknownEncoding(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


UnknownEncodingHelper

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP.CodecFactoryPackage
Class UnknownEncodingHelper

java.lang.Object
    extended by  org.omg.IOP.CodecFactoryPackage.UnknownEncodingHelper

public abstract class UnknownEncodingHelper
extends Object

org/omg/IOP/CodecFactoryPackage/UnknownEncodingHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:23 AM GMT-08:00

Constructor Summary
UnknownEncodingHelper()
Method Summary
static UnknownEncoding | extract(Any a)
static String | id()
static void | insert(Any a, UnknownEncoding that)
static UnknownEncoding | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, UnknownEncoding value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UnknownEncodingHelper

public UnknownEncodingHelper()
Method Detail

insert

public static void insert(Any a,
                          UnknownEncoding that)

extract

public static UnknownEncoding extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static UnknownEncoding read(InputStream istream)

write

public static void write(OutputStream ostream,
                         UnknownEncoding value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


CodecOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Interface CodecOperations

All Known Subinterfaces:
Codec
public interface CodecOperations

The formats of IOR components and service context data used by ORB services are often defined as CDR encapsulations encoding instances of IDL defined data types. The Codec provides a mechanism to transfer these components between their IDL data types and their CDR encapsulation representations.

A Codec is obtained from the CodecFactory. The CodecFactory is obtained through a call to ORB.resolve_initial_references( "CodecFactory" ).

Method Summary
Any | decode_value(byte[] data, TypeCode tc) Decodes the given byte array into an Any based on the given TypeCode and the encoding format effective for this Codec.
Any | decode(byte[] data) Decodes the given byte array into an Any based on the encoding format effective for this Codec.
byte[] | encode_value(Any data) Converts the given any into a byte array based on the encoding format effective for this Codec.
byte[] | encode(Any data) Converts the given any into a byte array based on the encoding format effective for this Codec.

Method Detail

encode

byte[] encode(Any data)
              throws InvalidTypeForEncoding
Converts the given any into a byte array based on the encoding format effective for this Codec.

Parameters:
data - The data, in the form of an any, to be encoded into a byte array.
Returns:
A byte array containing the encoded Any. This byte array contains both the TypeCode and the data of the type.
Throws:
InvalidTypeForEncoding - thrown if the type is not valid for the encoding format effective for this Codec.

decode

Any decode(byte[] data)
           throws FormatMismatch
Decodes the given byte array into an Any based on the encoding format effective for this Codec.

Parameters:
data - The data, in the form of a byte array, to be decoded into an Any.
Returns:
An Any containing the data from the decoded byte array.
Throws:
FormatMismatch - is thrown if the byte array cannot be decoded into an Any.

encode_value

byte[] encode_value(Any data)
                    throws InvalidTypeForEncoding
Converts the given any into a byte array based on the encoding format effective for this Codec. Only the data from the Any is encoded, not the TypeCode.

Parameters:
data - The data, in the form of an Any, to be encoded into a byte array.
Returns:
A byte array containing the data from the encoded any.
Throws:
InvalidTypeForEncoding - thrown if the type is not valid for the encoding format effective for this Codec.

decode_value

Any decode_value(byte[] data,
                 TypeCode tc)
                 throws FormatMismatch,
                        TypeMismatch
Decodes the given byte array into an Any based on the given TypeCode and the encoding format effective for this Codec.

Parameters:
data - The data, in the form of a byte array, to be decoded into an Any.
tc - The TypeCode to be used to decode the data.
Returns:
An Any containing the data from the decoded byte array.
Throws:
FormatMismatch - thrown if the byte array cannot be decoded into an Any.
TypeMismatch
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CodecPackage

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.IOP.CodecPackage

This package is generated from the IOP::Codec IDL interface definition.

See:
Description

Class Summary
FormatMismatchHelper | org/omg/IOP/CodecPackage/FormatMismatchHelper.java .
InvalidTypeForEncodingHelper | org/omg/IOP/CodecPackage/InvalidTypeForEncodingHelper.java .
TypeMismatchHelper | org/omg/IOP/CodecPackage/TypeMismatchHelper.java .

Exception Summary
FormatMismatch | org/omg/IOP/CodecPackage/FormatMismatch.java .
InvalidTypeForEncoding | org/omg/IOP/CodecPackage/InvalidTypeForEncoding.java .
TypeMismatch | org/omg/IOP/CodecPackage/TypeMismatch.java .

Package org.omg.IOP.CodecPackage Description

This package is generated from the IOP::Codec IDL interface definition. It contains the Java representations of the IDL exceptions specified in IOP::Codec (as part of the Portable Interceptors specification). Please refer to that OMG specification for further details.

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6 ORB complies, see Official Specifications for CORBA support in Java[tm] SE 6.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.IOP.CodecPackage Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.IOP.CodecPackage

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.IOP.CodecPackage.FormatMismatchHelper
    • org.omg.IOP.CodecPackage.InvalidTypeForEncodingHelper
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.omg.CORBA.UserException (implements org.omg.CORBA.portable.IDLEntity)
          • org.omg.IOP.CodecPackage.FormatMismatch
          • org.omg.IOP.CodecPackage.InvalidTypeForEncoding
          • org.omg.IOP.CodecPackage.TypeMismatch
    • org.omg.IOP.CodecPackage.TypeMismatchHelper
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.IOP.CodecPackage

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.IOP.CodecPackage

Packages that use org.omg.IOP.CodecPackage
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.IOP.CodecPackage | This package is generated from the IOP::Codec IDL interface definition.

Classes in org.omg.IOP.CodecPackage used by org.omg.IOP
FormatMismatch
org/omg/IOP/CodecPackage/FormatMismatch.java .
InvalidTypeForEncoding
org/omg/IOP/CodecPackage/InvalidTypeForEncoding.java .
TypeMismatch
org/omg/IOP/CodecPackage/TypeMismatch.java .

Classes in org.omg.IOP.CodecPackage used by org.omg.IOP.CodecPackage
FormatMismatch
org/omg/IOP/CodecPackage/FormatMismatch.java .
InvalidTypeForEncoding
org/omg/IOP/CodecPackage/InvalidTypeForEncoding.java .
TypeMismatch
org/omg/IOP/CodecPackage/TypeMismatch.java .

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.CodecPackage.FormatMismatch

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.CodecPackage.FormatMismatch

Packages that use FormatMismatch
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.IOP.CodecPackage | This package is generated from the IOP::Codec IDL interface definition.

Uses of FormatMismatch in org.omg.IOP

Methods in org.omg.IOP that throw FormatMismatch
Any | CodecOperations.decode_value(byte[] data, TypeCode tc) Decodes the given byte array into an Any based on the given TypeCode and the encoding format effective for this Codec.
Any | CodecOperations.decode(byte[] data) Decodes the given byte array into an Any based on the encoding format effective for this Codec.

Uses of FormatMismatch in org.omg.IOP.CodecPackage

Methods in org.omg.IOP.CodecPackage that return FormatMismatch
static FormatMismatch | FormatMismatchHelper.extract(Any a)
static FormatMismatch | FormatMismatchHelper.read(InputStream istream)

Methods in org.omg.IOP.CodecPackage with parameters of type FormatMismatch
static void | FormatMismatchHelper.insert(Any a, FormatMismatch that)
static void | FormatMismatchHelper.write(OutputStream ostream, FormatMismatch value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.CodecPackage.FormatMismatchHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.CodecPackage.FormatMismatchHelper

No usage of org.omg.IOP.CodecPackage.FormatMismatchHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.CodecPackage.InvalidTypeForEncoding

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.CodecPackage.InvalidTypeForEncoding

Packages that use InvalidTypeForEncoding
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.IOP.CodecPackage | This package is generated from the IOP::Codec IDL interface definition.

Uses of InvalidTypeForEncoding in org.omg.IOP

Methods in org.omg.IOP that throw InvalidTypeForEncoding
byte[] | CodecOperations.encode_value(Any data) Converts the given any into a byte array based on the encoding format effective for this Codec.
byte[] | CodecOperations.encode(Any data) Converts the given any into a byte array based on the encoding format effective for this Codec.

Uses of InvalidTypeForEncoding in org.omg.IOP.CodecPackage

Methods in org.omg.IOP.CodecPackage that return InvalidTypeForEncoding
static InvalidTypeForEncoding | InvalidTypeForEncodingHelper.extract(Any a)
static InvalidTypeForEncoding | InvalidTypeForEncodingHelper.read(InputStream istream)

Methods in org.omg.IOP.CodecPackage with parameters of type InvalidTypeForEncoding
static void | InvalidTypeForEncodingHelper.insert(Any a, InvalidTypeForEncoding that)
static void | InvalidTypeForEncodingHelper.write(OutputStream ostream, InvalidTypeForEncoding value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.CodecPackage.InvalidTypeForEncodingHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.CodecPackage.InvalidTypeForEncodingHelper

No usage of org.omg.IOP.CodecPackage.InvalidTypeForEncodingHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.CodecPackage.TypeMismatch

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.CodecPackage.TypeMismatch

Packages that use TypeMismatch
org.omg.IOP | This package contains the IOP module specified in the OMG document The Common Object Request Broker: Architecture and Specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07, section 13.6.
org.omg.IOP.CodecPackage | This package is generated from the IOP::Codec IDL interface definition.

Uses of TypeMismatch in org.omg.IOP

Methods in org.omg.IOP that throw TypeMismatch
 Any CodecOperations.decode_value(byte[] data, TypeCode tc)
Decodes the given byte array into an Any based on the given TypeCode and the encoding format effective for this Codec.

Uses of TypeMismatch in org.omg.IOP.CodecPackage

Methods in org.omg.IOP.CodecPackage that return TypeMismatch
static TypeMismatch | TypeMismatchHelper.extract(Any a)
static TypeMismatch | TypeMismatchHelper.read(InputStream istream)

Methods in org.omg.IOP.CodecPackage with parameters of type TypeMismatch
static void | TypeMismatchHelper.insert(Any a, TypeMismatch that)
static void | TypeMismatchHelper.write(OutputStream ostream, TypeMismatch value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.IOP.CodecPackage.TypeMismatchHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.IOP.CodecPackage.TypeMismatchHelper

No usage of org.omg.IOP.CodecPackage.TypeMismatchHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


FormatMismatch

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP.CodecPackage
Class FormatMismatch

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.IOP.CodecPackage.FormatMismatch
All Implemented Interfaces:
Serializable, IDLEntity
public final class FormatMismatch
extends UserException

org/omg/IOP/CodecPackage/FormatMismatch.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:23 AM GMT-08:00

Constructor Summary
FormatMismatch()
FormatMismatch(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

FormatMismatch

public FormatMismatch()

FormatMismatch

public FormatMismatch(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


FormatMismatchHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP.CodecPackage
Class FormatMismatchHelper

java.lang.Object
    extended by  org.omg.IOP.CodecPackage.FormatMismatchHelper

public abstract class FormatMismatchHelper
extends Object

org/omg/IOP/CodecPackage/FormatMismatchHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:23 AM GMT-08:00

Constructor Summary
FormatMismatchHelper()
Method Summary
static FormatMismatch | extract(Any a)
static String | id()
static void | insert(Any a, FormatMismatch that)
static FormatMismatch | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, FormatMismatch value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FormatMismatchHelper

public FormatMismatchHelper()
Method Detail

insert

public static void insert(Any a,
                          FormatMismatch that)

extract

public static FormatMismatch extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static FormatMismatch read(InputStream istream)

write

public static void write(OutputStream ostream,
                         FormatMismatch value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidTypeForEncoding

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP.CodecPackage
Class InvalidTypeForEncoding

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.IOP.CodecPackage.InvalidTypeForEncoding
All Implemented Interfaces:
Serializable, IDLEntity
public final class InvalidTypeForEncoding
extends UserException

org/omg/IOP/CodecPackage/InvalidTypeForEncoding.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:23 AM GMT-08:00

Constructor Summary
InvalidTypeForEncoding()
InvalidTypeForEncoding(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidTypeForEncoding

public InvalidTypeForEncoding()

InvalidTypeForEncoding

public InvalidTypeForEncoding(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidTypeForEncodingHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP.CodecPackage
Class InvalidTypeForEncodingHelper

java.lang.Object
    extended by  org.omg.IOP.CodecPackage.InvalidTypeForEncodingHelper

public abstract class InvalidTypeForEncodingHelper
extends Object

org/omg/IOP/CodecPackage/InvalidTypeForEncodingHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:23 AM GMT-08:00

Constructor Summary
InvalidTypeForEncodingHelper()
Method Summary
static InvalidTypeForEncoding | extract(Any a)
static String | id()
static void | insert(Any a, InvalidTypeForEncoding that)
static InvalidTypeForEncoding | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, InvalidTypeForEncoding value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InvalidTypeForEncodingHelper

public InvalidTypeForEncodingHelper()
Method Detail

insert

public static void insert(Any a,
                          InvalidTypeForEncoding that)

extract

public static InvalidTypeForEncoding extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static InvalidTypeForEncoding read(InputStream istream)

write

public static void write(OutputStream ostream,
                         InvalidTypeForEncoding value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TypeMismatch

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP.CodecPackage
Class TypeMismatch

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.IOP.CodecPackage.TypeMismatch
All Implemented Interfaces:
Serializable, IDLEntity
public final class TypeMismatch
extends UserException

org/omg/IOP/CodecPackage/TypeMismatch.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:23 AM GMT-08:00

Constructor Summary
TypeMismatch()
TypeMismatch(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TypeMismatch

public TypeMismatch()

TypeMismatch

public TypeMismatch(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TypeMismatchHelper

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP.CodecPackage
Class TypeMismatchHelper

java.lang.Object
    extended by  org.omg.IOP.CodecPackage.TypeMismatchHelper

public abstract class TypeMismatchHelper
extends Object

org/omg/IOP/CodecPackage/TypeMismatchHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:23 AM GMT-08:00

Constructor Summary
TypeMismatchHelper()
Method Summary
static TypeMismatch | extract(Any a)
static String | id()
static void | insert(Any a, TypeMismatch that)
static TypeMismatch | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, TypeMismatch value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TypeMismatchHelper

public TypeMismatchHelper()
Method Detail

insert

public static void insert(Any a,
                          TypeMismatch that)

extract

public static TypeMismatch extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static TypeMismatch read(InputStream istream)

write

public static void write(OutputStream ostream,
                         TypeMismatch value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


CodeSets

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Interface CodeSets

public interface CodeSets

org/omg/IOP/CodeSets.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:23 AM GMT-08:00

Field Summary
static int value
Identifies a CDR encapsulation of the CONV_FRAME.CodeSetContext defined in Section 13.10.2.5, "GIOP Code Set Service Context," on page 13-43.

Field Detail

value

static final int value
Identifies a CDR encapsulation of the CONV_FRAME.CodeSetContext defined in Section 13.10.2.5, "GIOP Code Set Service Context," on page 13-43.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ComponentIdHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class ComponentIdHelper

java.lang.Object
    extended by  org.omg.IOP.ComponentIdHelper

public abstract class ComponentIdHelper
extends Object

Standard way of representing multicomponent profiles. This would be encapsulated in a TaggedProfile.

Constructor Summary
ComponentIdHelper()
Method Summary
static int | extract(Any a)
static String | id()
static void | insert(Any a, int that)
static int | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, int value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ComponentIdHelper

public ComponentIdHelper()
Method Detail

insert

public static void insert(Any a,
                          int that)

extract

public static int extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static int read(InputStream istream)

write

public static void write(OutputStream ostream,
                         int value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Encoding

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class Encoding

java.lang.Object
    extended by  org.omg.IOP.Encoding
All Implemented Interfaces:
Serializable, IDLEntity
public final class Encoding
extends Object
implements IDLEntity

org/omg/IOP/Encoding.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:23 AM GMT-08:00

Field Summary
short | format The encoding format.
byte | major_version The major version of this Encoding format.
byte | minor_version The minor version of this Encoding format.
Constructor Summary
Encoding()
Encoding(short _format, byte _major_version, byte _minor_version)
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

format

public short format
The encoding format.

major_version

public byte major_version
The major version of this Encoding format.

minor_version

public byte minor_version
The minor version of this Encoding format.

Constructor Detail

Encoding

public Encoding()

Encoding

public Encoding(short _format,
                byte _major_version,
                byte _minor_version)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ENCODING_CDR_ENCAPS

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Interface ENCODING_CDR_ENCAPS

public interface ENCODING_CDR_ENCAPS

org/omg/IOP/ENCODING_CDR_ENCAPS.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:23 AM GMT-08:00

Field Summary
static short value
The CDR Encapsulation encoding.

Field Detail

value

static final short value
The CDR Encapsulation encoding.

See Also:
CodecFactory, Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ExceptionDetailMessage

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Interface ExceptionDetailMessage

public interface ExceptionDetailMessage

org/omg/IOP/ExceptionDetailMessage.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:23 AM GMT-08:00

Field Summary
static int value
CORBA formal/02-06-01: 13.7.1: ExceptionDetailMessage identifies a CDR encapsulation of a wstring, encoded using GIOP 1.2 with a TCS-W of UTF-16.

Field Detail

value

static final int value
CORBA formal/02-06-01: 13.7.1: ExceptionDetailMessage identifies a CDR encapsulation of a wstring, encoded using GIOP 1.2 with a TCS-W of UTF-16. This service context may be sent on Reply messages with a reply_status of SYSTEM_EXCEPTION or USER_EXCEPTION. The usage of this service context is defined by language mappings.

IDL/Java: ptc/02-01-22: 1.15.2: When a System Exception is marshaled, its GIOP Reply message shall include an associated ExceptionDetailMessage service context. The callee's stack trace is often very valuable debugging information but may contain sensitive or unwanted information. The wstring within the service context will therefore contain additional information relating to the exception, for example the result of calling either printStackTrace(PrintWriter) or getMessage() on the exception. When unmarshaling a System Exception on the client side, the wstring from any ExceptionDetailMessage service context shall become the Java error message in the unmarshaled exception object.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IOR

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class IOR

java.lang.Object
    extended by  org.omg.IOP.IOR
All Implemented Interfaces:
Serializable, IDLEntity
public final class IOR
extends Object
implements IDLEntity

org/omg/IOP/IOR.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:22 AM GMT-08:00

Field Summary
TaggedProfile[] | profiles An array of tagged profiles associated with this object reference.
String | type_id The type id, represented as a String.
Constructor Summary
IOR()
IOR(String _type_id, TaggedProfile[] _profiles)
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

type_id

public String type_id
The type id, represented as a String.

profiles

public TaggedProfile[] profiles
An array of tagged profiles associated with this object reference.

Constructor Detail

IOR

public IOR()

IOR

public IOR(String _type_id,
           TaggedProfile[] _profiles)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IORHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class IORHelper

java.lang.Object
    extended by  org.omg.IOP.IORHelper

public abstract class IORHelper
extends Object

org/omg/IOP/IORHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:22 AM GMT-08:00

Constructor Summary
IORHelper()
Method Summary
static IOR | extract(Any a)
static String | id()
static void | insert(Any a, IOR that)
static IOR | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, IOR value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IORHelper

public IORHelper()
Method Detail

insert

public static void insert(Any a,
                          IOR that)

extract

public static IOR extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static IOR read(InputStream istream)

write

public static void write(OutputStream ostream,
                         IOR value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IORHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class IORHolder

java.lang.Object
    extended by  org.omg.IOP.IORHolder
All Implemented Interfaces:
Streamable
public final class IORHolder
extends Object
implements Streamable

org/omg/IOP/IORHolder.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:22 AM GMT-08:00

Field Summary
 IOR value
Constructor Summary
IORHolder()
IORHolder(IOR initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public IOR value
Constructor Detail

IORHolder

public IORHolder()

IORHolder

public IORHolder(IOR initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultipleComponentProfileHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class MultipleComponentProfileHelper

java.lang.Object
    extended by  org.omg.IOP.MultipleComponentProfileHelper

public abstract class MultipleComponentProfileHelper
extends Object

An array of tagged components, forming a multiple component profile.

Constructor Summary
MultipleComponentProfileHelper()
Method Summary
static TaggedComponent[] | extract(Any a)
static String | id()
static void | insert(Any a, TaggedComponent[] that)
static TaggedComponent[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, TaggedComponent[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MultipleComponentProfileHelper

public MultipleComponentProfileHelper()
Method Detail

insert

public static void insert(Any a,
                          TaggedComponent[] that)

extract

public static TaggedComponent[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static TaggedComponent[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         TaggedComponent[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MultipleComponentProfileHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class MultipleComponentProfileHolder

java.lang.Object
    extended by  org.omg.IOP.MultipleComponentProfileHolder
All Implemented Interfaces:
Streamable
public final class MultipleComponentProfileHolder
extends Object
implements Streamable

An array of tagged components, forming a multiple component profile.

Field Summary
 TaggedComponent[] value
Constructor Summary
MultipleComponentProfileHolder()
MultipleComponentProfileHolder(TaggedComponent[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public TaggedComponent[] value
Constructor Detail

MultipleComponentProfileHolder

public MultipleComponentProfileHolder()

MultipleComponentProfileHolder

public MultipleComponentProfileHolder(TaggedComponent[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ProfileIdHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class ProfileIdHelper

java.lang.Object
    extended by  org.omg.IOP.ProfileIdHelper

public abstract class ProfileIdHelper
extends Object

Profile ID

Constructor Summary
ProfileIdHelper()
Method Summary
static int | extract(Any a)
static String | id()
static void | insert(Any a, int that)
static int | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, int value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ProfileIdHelper

public ProfileIdHelper()
Method Detail

insert

public static void insert(Any a,
                          int that)

extract

public static int extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static int read(InputStream istream)

write

public static void write(OutputStream ostream,
                         int value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RMICustomMaxStreamFormat

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Interface RMICustomMaxStreamFormat

public interface RMICustomMaxStreamFormat

org/omg/IOP/RMICustomMaxStreamFormat.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:23 AM GMT-08:00

Field Summary
static int value
Identifies a CDR encapsulation of the RMICustomMaxStreamFormat service context which contains a single byte specifying the client's maximum RMI-IIOP stream format version.

Field Detail

value

static final int value
Identifies a CDR encapsulation of the RMICustomMaxStreamFormat service context which contains a single byte specifying the client's maximum RMI-IIOP stream format version. See Java to IDL ptc/02-01-12 1.4.12.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServiceContext

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class ServiceContext

java.lang.Object
    extended by  org.omg.IOP.ServiceContext
All Implemented Interfaces:
Serializable, IDLEntity
public final class ServiceContext
extends Object
implements IDLEntity

org/omg/IOP/ServiceContext.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:23 AM GMT-08:00

Field Summary
byte[] | context_data The data associated with this service context
int | context_id The service context id
Constructor Summary
ServiceContext()
ServiceContext(int _context_id, byte[] _context_data)
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

context_id

public int context_id
The service context id

context_data

public byte[] context_data
The data associated with this service context

Constructor Detail

ServiceContext

public ServiceContext()

ServiceContext

public ServiceContext(int _context_id,
                      byte[] _context_data)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServiceContextHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class ServiceContextHelper

java.lang.Object
    extended by  org.omg.IOP.ServiceContextHelper

public abstract class ServiceContextHelper
extends Object

org/omg/IOP/ServiceContextHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:23 AM GMT-08:00

Constructor Summary
ServiceContextHelper()
Method Summary
static ServiceContext | extract(Any a)
static String | id()
static void | insert(Any a, ServiceContext that)
static ServiceContext | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, ServiceContext value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServiceContextHelper

public ServiceContextHelper()
Method Detail

insert

public static void insert(Any a,
                          ServiceContext that)

extract

public static ServiceContext extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static ServiceContext read(InputStream istream)

write

public static void write(OutputStream ostream,
                         ServiceContext value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServiceContextHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class ServiceContextHolder

java.lang.Object
    extended by  org.omg.IOP.ServiceContextHolder
All Implemented Interfaces:
Streamable
public final class ServiceContextHolder
extends Object
implements Streamable

org/omg/IOP/ServiceContextHolder.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:23 AM GMT-08:00

Field Summary
 ServiceContext value
Constructor Summary
ServiceContextHolder()
ServiceContextHolder(ServiceContext initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public ServiceContext value
Constructor Detail

ServiceContextHolder

public ServiceContextHolder()

ServiceContextHolder

public ServiceContextHolder(ServiceContext initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServiceContextListHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class ServiceContextListHelper

java.lang.Object
    extended by  org.omg.IOP.ServiceContextListHelper

public abstract class ServiceContextListHelper
extends Object

An array of service contexts, forming a service context list.

Constructor Summary
ServiceContextListHelper()
Method Summary
static ServiceContext[] | extract(Any a)
static String | id()
static void | insert(Any a, ServiceContext[] that)
static ServiceContext[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, ServiceContext[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServiceContextListHelper

public ServiceContextListHelper()
Method Detail

insert

public static void insert(Any a,
                          ServiceContext[] that)

extract

public static ServiceContext[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static ServiceContext[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         ServiceContext[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServiceContextListHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class ServiceContextListHolder

java.lang.Object
    extended by  org.omg.IOP.ServiceContextListHolder
All Implemented Interfaces:
Streamable
public final class ServiceContextListHolder
extends Object
implements Streamable

An array of service contexts, forming a service context list.

Field Summary
 ServiceContext[] value
Constructor Summary
ServiceContextListHolder()
ServiceContextListHolder(ServiceContext[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public ServiceContext[] value
Constructor Detail

ServiceContextListHolder

public ServiceContextListHolder()

ServiceContextListHolder

public ServiceContextListHolder(ServiceContext[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServiceIdHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class ServiceIdHelper

java.lang.Object
    extended by  org.omg.IOP.ServiceIdHelper

public abstract class ServiceIdHelper
extends Object

A service id, represented as an int

Constructor Summary
ServiceIdHelper()
Method Summary
static int | extract(Any a)
static String | id()
static void | insert(Any a, int that)
static int | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, int value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServiceIdHelper

public ServiceIdHelper()
Method Detail

insert

public static void insert(Any a,
                          int that)

extract

public static int extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static int read(InputStream istream)

write

public static void write(OutputStream ostream,
                         int value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TaggedComponent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class TaggedComponent

java.lang.Object
    extended by  org.omg.IOP.TaggedComponent
All Implemented Interfaces:
Serializable, IDLEntity
public final class TaggedComponent
extends Object
implements IDLEntity

org/omg/IOP/TaggedComponent.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:22 AM GMT-08:00

Field Summary
byte[] | component_data The component data associated with the component id.
int | tag The tag, represented as a component id.
Constructor Summary
TaggedComponent()
TaggedComponent(int _tag, byte[] _component_data)
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

tag

public int tag
The tag, represented as a component id.

component_data

public byte[] component_data
The component data associated with the component id.

Constructor Detail

TaggedComponent

public TaggedComponent()

TaggedComponent

public TaggedComponent(int _tag,
                       byte[] _component_data)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TaggedComponentHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class TaggedComponentHelper

java.lang.Object
    extended by  org.omg.IOP.TaggedComponentHelper

public abstract class TaggedComponentHelper
extends Object

org/omg/IOP/TaggedComponentHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:22 AM GMT-08:00

Constructor Summary
TaggedComponentHelper()
Method Summary
static TaggedComponent | extract(Any a)
static String | id()
static void | insert(Any a, TaggedComponent that)
static TaggedComponent | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, TaggedComponent value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TaggedComponentHelper

public TaggedComponentHelper()
Method Detail

insert

public static void insert(Any a,
                          TaggedComponent that)

extract

public static TaggedComponent extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static TaggedComponent read(InputStream istream)

write

public static void write(OutputStream ostream,
                         TaggedComponent value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TaggedComponentHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class TaggedComponentHolder

java.lang.Object
    extended by  org.omg.IOP.TaggedComponentHolder
All Implemented Interfaces:
Streamable
public final class TaggedComponentHolder
extends Object
implements Streamable

org/omg/IOP/TaggedComponentHolder.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:22 AM GMT-08:00

Field Summary
 TaggedComponent value
Constructor Summary
TaggedComponentHolder()
TaggedComponentHolder(TaggedComponent initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public TaggedComponent value
Constructor Detail

TaggedComponentHolder

public TaggedComponentHolder()

TaggedComponentHolder

public TaggedComponentHolder(TaggedComponent initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TaggedProfile

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class TaggedProfile

java.lang.Object
    extended by  org.omg.IOP.TaggedProfile
All Implemented Interfaces:
Serializable, IDLEntity
public final class TaggedProfile
extends Object
implements IDLEntity

org/omg/IOP/TaggedProfile.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:22 AM GMT-08:00

Field Summary
byte[] | profile_data The associated profile data.
int | tag The tag, represented as a profile id.
Constructor Summary
TaggedProfile()
TaggedProfile(int _tag, byte[] _profile_data)
Method Summary
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

tag

public int tag
The tag, represented as a profile id.

profile_data

public byte[] profile_data
The associated profile data.

Constructor Detail

TaggedProfile

public TaggedProfile()

TaggedProfile

public TaggedProfile(int _tag,
                     byte[] _profile_data)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TaggedProfileHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class TaggedProfileHelper

java.lang.Object
    extended by  org.omg.IOP.TaggedProfileHelper

public abstract class TaggedProfileHelper
extends Object

org/omg/IOP/TaggedProfileHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:22 AM GMT-08:00

Constructor Summary
TaggedProfileHelper()
Method Summary
static TaggedProfile | extract(Any a)
static String | id()
static void | insert(Any a, TaggedProfile that)
static TaggedProfile | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, TaggedProfile value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TaggedProfileHelper

public TaggedProfileHelper()
Method Detail

insert

public static void insert(Any a,
                          TaggedProfile that)

extract

public static TaggedProfile extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static TaggedProfile read(InputStream istream)

write

public static void write(OutputStream ostream,
                         TaggedProfile value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TaggedProfileHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Class TaggedProfileHolder

java.lang.Object
    extended by  org.omg.IOP.TaggedProfileHolder
All Implemented Interfaces:
Streamable
public final class TaggedProfileHolder
extends Object
implements Streamable

org/omg/IOP/TaggedProfileHolder.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:22 AM GMT-08:00

Field Summary
 TaggedProfile value
Constructor Summary
TaggedProfileHolder()
TaggedProfileHolder(TaggedProfile initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public TaggedProfile value
Constructor Detail

TaggedProfileHolder

public TaggedProfileHolder()

TaggedProfileHolder

public TaggedProfileHolder(TaggedProfile initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TAG_ALTERNATE_IIOP_ADDRESS

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Interface TAG_ALTERNATE_IIOP_ADDRESS

public interface TAG_ALTERNATE_IIOP_ADDRESS

org/omg/IOP/TAG_ALTERNATE_IIOP_ADDRESS.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:22 AM GMT-08:00

Field Summary
static int value
In cases where the same object key is used for more than one internet location, the following standard IOR Component is defined for support in IIOP version 1.2.

Field Detail

value

static final int value
In cases where the same object key is used for more than one internet location, the following standard IOR Component is defined for support in IIOP version 1.2.

The TAG_ALTERNATE_IIOP_ADDRESS component has an associated value of type:

     struct {
         string HostID,
         short Port
     };
encoded as a CDR encapsulation.

Zero or more instances of the TAG_ALTERNATE_IIOP_ADDRESS component type may be included in a version 1.2 TAG_INTERNET_IOP Profile. Each of these alternative addresses may be used by the client orb, in addition to the host and port address expressed in the body of the Profile. In cases where one or more TAG_ALTERNATE_IIOP_ADDRESS components are present in a TAG_INTERNET_IOP Profile, no order of use is prescribed by Version 1.2 of IIOP.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TAG_CODE_SETS

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Interface TAG_CODE_SETS

public interface TAG_CODE_SETS

org/omg/IOP/TAG_CODE_SETS.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:22 AM GMT-08:00

Field Summary
static int value
The code set component of the IOR multi-component profile structure contains: server's native char code set and conversion code sets, and server's native wchar code set and conversion code sets. Both char and wchar conversion code sets are listed in order of preference.

Field Detail

value

static final int value
The code set component of the IOR multi-component profile structure contains:
  • server's native char code set and conversion code sets, and
  • server's native wchar code set and conversion code sets.
Both char and wchar conversion code sets are listed in order of preference.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TAG_INTERNET_IOP

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Interface TAG_INTERNET_IOP

public interface TAG_INTERNET_IOP

org/omg/IOP/TAG_INTERNET_IOP.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:22 AM GMT-08:00

Field Summary
static int value
Identifies profiles that support the Internet Inter-ORB Protocol.

Field Detail

value

static final int value
Identifies profiles that support the Internet Inter-ORB Protocol. The ProfileBody of this profile contains a CDR encapsulation of a structure containing addressing and object identification information used by IIOP. Version 1.1 of the TAG_INTERNET_IOP profile also includes an array of TaggedComponent objects that can contain additional information supporting optional IIOP features, ORB services such as security, and future protocol extensions.

Protocols other than IIOP (such as ESIOPs and other GIOPs) can share profile information (such as object identity or security information) with IIOP by encoding their additional profile information as components in the TAG_INTERNET_IOP profile. All TAG_INTERNET_IOP profiles support IIOP, regardless of whether they also support additional protocols. Interoperable ORBs are not required to create or understand any other profile, nor are they required to create or understand any of the components defined for other protocols that might share the TAG_INTERNET_IOP profile with IIOP.

The profile_data for the TAG_INTERNET_IOP profile is a CDR encapsulation of the IIOP.ProfileBody_1_1 type.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TAG_JAVA_CODEBASE

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Interface TAG_JAVA_CODEBASE

public interface TAG_JAVA_CODEBASE

org/omg/IOP/TAG_JAVA_CODEBASE.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:22 AM GMT-08:00

Field Summary
static int value
Class downloading is supported for stubs, ties, values, and value helpers.

Field Detail

value

static final int value
Class downloading is supported for stubs, ties, values, and value helpers. The specification allows transmission of codebase information on the wire for stubs and ties, and enables usage of pre-existing ClassLoaders when relevant.

For values and value helpers, the codebase is transmitted after the value tag. For stubs and ties, the codebase is transmitted as the TaggedComponent TAG_JAVA_CODEBASE in the IOR profile, where the component_data is a CDR encapsulation of the codebase written as an IDL string. The codebase is a space-separated list of one or more URLs.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TAG_MULTIPLE_COMPONENTS

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Interface TAG_MULTIPLE_COMPONENTS

public interface TAG_MULTIPLE_COMPONENTS

org/omg/IOP/TAG_MULTIPLE_COMPONENTS.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:22 AM GMT-08:00

Field Summary
static int value
Indicates that the value encapsulated is of type MultipleComponentProfile.

Field Detail

value

static final int value
Indicates that the value encapsulated is of type MultipleComponentProfile. In this case, the profile consists of a list of protocol components, the use of which must be specified by the protocol using this profile. This profile may be used to carry IOR components.

The profile_data for the TAG_MULTIPLE_COMPONENTS profile is a CDR encapsulation of the MultipleComponentProfile type shown above.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TAG_ORB_TYPE

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Interface TAG_ORB_TYPE

public interface TAG_ORB_TYPE

org/omg/IOP/TAG_ORB_TYPE.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:22 AM GMT-08:00

Field Summary
static int value
It is often useful in the real world to be able to identify the particular kind of ORB an object reference is coming from, to work around problems with that particular ORB, or exploit shared efficiencies.

Field Detail

value

static final int value
It is often useful in the real world to be able to identify the particular kind of ORB an object reference is coming from, to work around problems with that particular ORB, or exploit shared efficiencies.

The TAG_ORB_TYPE component has an associated value of type unsigned long (Java long), encoded as a CDR encapsulation, designating an ORB type ID allocated by the OMG for the ORB type of the originating ORB. Anyone may register any ORB types by submitting a short (one-paragraph) description of the ORB type to the OMG, and will receive a new ORB type ID in return. A list of ORB type descriptions and values will be made available on the OMG web server.

The TAG_ORB_TYPE component can appear at most once in any IOR profile. For profiles supporting IIOP 1.1 or greater, it is optionally present.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TAG_POLICIES

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Interface TAG_POLICIES

public interface TAG_POLICIES

org/omg/IOP/TAG_POLICIES.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:22 AM GMT-08:00

Field Summary
static int value
A profile component containing the sequence of QoS policies exported with the object reference by an object adapter.

Field Detail

value

static final int value
A profile component containing the sequence of QoS policies exported with the object reference by an object adapter.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TAG_RMI_CUSTOM_MAX_STREAM_FORMAT

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Interface TAG_RMI_CUSTOM_MAX_STREAM_FORMAT

public interface TAG_RMI_CUSTOM_MAX_STREAM_FORMAT

org/omg/IOP/TAG_RMI_CUSTOM_MAX_STREAM_FORMAT.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:22 AM GMT-08:00

Field Summary
static int value
RMI-IIOP has multiple stream format versions.

Field Detail

value

static final int value
RMI-IIOP has multiple stream format versions. A server can specify its maximum version by including the TAG_RMI_CUSTOM_MAX_STREAM_FORMAT tagged component or rely on the default of version 1 for GIOP 1.2 and less and version 2 for GIOP 1.3 and higher. See Java to IDL ptc/02-01-12 1.4.11.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TransactionService

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.IOP
Interface TransactionService

public interface TransactionService

org/omg/IOP/TransactionService.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/IOP.idl Wednesday, November 29, 2006 1:57:23 AM GMT-08:00

Field Summary
static int value
Identifies a CDR encapsulation of the CosTSInteroperation.PropogationContext defined in CORBAservices: Common Object Services Specifications.

Field Detail

value

static final int value
Identifies a CDR encapsulation of the CosTSInteroperation.PropogationContext defined in CORBAservices: Common Object Services Specifications.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Messaging

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.Messaging

This package contains the Messaging module specified in the OMG CORBA Messaging specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07.

See:
Description

Interface Summary
SYNC_WITH_TRANSPORT org/omg/Messaging/SYNC_WITH_TRANSPORT.java .

Class Summary
SyncScopeHelper Synchronization scope

Package org.omg.Messaging Description

This package contains the Messaging module specified in the OMG CORBA Messaging specification, http://cgi.omg.org/cgi-bin/doc?formal/99-10-07. Please refer to that OMG specification for further details.

Please note that we do not provide all parts of the Messaging module from the specification. We only provide those parts that are referenced as return values or parameter types in public APIs, most notably, Portable Interceptors.

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6 ORB complies, see Official Specifications for CORBA support in Java[tm] SE 6.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.Messaging Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.Messaging

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.Messaging.SyncScopeHelper

Interface Hierarchy

  • org.omg.Messaging.SYNC_WITH_TRANSPORT
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.Messaging

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.Messaging

No usage of org.omg.Messaging

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.Messaging.SyncScopeHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.Messaging.SyncScopeHelper

No usage of org.omg.Messaging.SyncScopeHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.Messaging.SYNC_WITH_TRANSPORT

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.Messaging.SYNC_WITH_TRANSPORT

No usage of org.omg.Messaging.SYNC_WITH_TRANSPORT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


SyncScopeHelper

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.Messaging
Class SyncScopeHelper

java.lang.Object
    extended by  org.omg.Messaging.SyncScopeHelper

public abstract class SyncScopeHelper
extends Object

Synchronization scope

Constructor Summary
SyncScopeHelper()
Method Summary
static short | extract(Any a)
static String | id()
static void | insert(Any a, short that)
static short | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, short value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SyncScopeHelper

public SyncScopeHelper()
Method Detail

insert

public static void insert(Any a,
                          short that)

extract

public static short extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static short read(InputStream istream)

write

public static void write(OutputStream ostream,
                         short value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


SYNC_WITH_TRANSPORT

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.Messaging
Interface SYNC_WITH_TRANSPORT

public interface SYNC_WITH_TRANSPORT

org/omg/Messaging/SYNC_WITH_TRANSPORT.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Messaging.idl Wednesday, November 29, 2006 1:57:24 AM GMT-08:00

Field Summary
static short value
Constant, defined in the Messaging spec, to define how far the request shall progress before control is returned to the client.

Field Detail

value

static final short value
Constant, defined in the Messaging spec, to define how far the request shall progress before control is returned to the client.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


PortableInterceptor

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.PortableInterceptor

Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

See:
Description

Interface Summary
ACTIVE | org/omg/PortableInterceptor/ACTIVE.java .
ClientRequestInfo | Request Information, accessible to client-side request interceptors.
ClientRequestInfoOperations | Request Information, accessible to client-side request interceptors.
ClientRequestInterceptor | Client-side request interceptor.
ClientRequestInterceptorOperations | Client-side request interceptor.
Current | Portable Interceptors Current (also known as PICurrent) is merely a slot table, the slots of which are used by each service to transfer their context data between their context and the request's or reply's service context.
CurrentOperations | Portable Interceptors Current (also known as PICurrent) is merely a slot table, the slots of which are used by each service to transfer their context data between their context and the request's or reply's service context.
DISCARDING | org/omg/PortableInterceptor/DISCARDING.java .
HOLDING | org/omg/PortableInterceptor/HOLDING.java .
INACTIVE | org/omg/PortableInterceptor/INACTIVE.java .
Interceptor | All Portable Interceptors implement Interceptor.
InterceptorOperations | All Portable Interceptors implement Interceptor.
IORInfo | Provides the server-side ORB service with access to the applicable policies during IOR construction and the ability to add components.
IORInfoOperations | Provides the server-side ORB service with access to the applicable policies during IOR construction and the ability to add components.
IORInterceptor | Interceptor used to establish tagged components in the profiles within an IOR.
IORInterceptor_3_0 | org/omg/PortableInterceptor/IORInterceptor_3_0.java .
IORInterceptor_3_0Operations | org/omg/PortableInterceptor/IORInterceptor_3_0Operations.java .
IORInterceptorOperations | Interceptor used to establish tagged components in the profiles within an IOR.
LOCATION_FORWARD | org/omg/PortableInterceptor/LOCATION_FORWARD.java .
NON_EXISTENT | org/omg/PortableInterceptor/NON_EXISTENT.java .
ObjectReferenceFactory | The object reference factory.
ObjectReferenceTemplate | The object reference template.
ORBInitializer | Facilitates interceptor registration and ORB initialization.
ORBInitializerOperations | Facilitates interceptor registration and ORB initialization.
ORBInitInfo | Passed to each ORBInitializer, allowing it to to register interceptors and perform other duties while the ORB is initializing.
ORBInitInfoOperations | Passed to each ORBInitializer, allowing it to to register interceptors and perform other duties while the ORB is initializing.
PolicyFactory | Enables policy types to be constructed using CORBA.ORB.create_policy.
PolicyFactoryOperations | Enables policy types to be constructed using CORBA.ORB.create_policy.
RequestInfo | Request Information, accessible to Interceptors.
RequestInfoOperations | Request Information, accessible to Interceptors.
ServerRequestInfo | Request Information, accessible to server-side request interceptors.
ServerRequestInfoOperations | Request Information, accessible to server-side request interceptors.
ServerRequestInterceptor | Server-side request interceptor.
ServerRequestInterceptorOperations | Server-side request interceptor.
SUCCESSFUL | org/omg/PortableInterceptor/SUCCESSFUL.java .
SYSTEM_EXCEPTION | org/omg/PortableInterceptor/SYSTEM_EXCEPTION.java .
TRANSPORT_RETRY | org/omg/PortableInterceptor/TRANSPORT_RETRY.java .
UNKNOWN | org/omg/PortableInterceptor/UNKNOWN.java .
USER_EXCEPTION | org/omg/PortableInterceptor/USER_EXCEPTION.java .

Class Summary
AdapterManagerIdHelper | Adapter manager identifier.
AdapterNameHelper | The name of an object adapter.
AdapterStateHelper | Type of object adapter state.
CurrentHelper | Portable Interceptors Current (also known as PICurrent) is merely a slot table, the slots of which are used by each service to transfer their context data between their context and the request's or reply's service context.
ForwardRequestHelper | org/omg/PortableInterceptor/ForwardRequestHelper.java .
InvalidSlotHelper | org/omg/PortableInterceptor/InvalidSlotHelper.java .
IORInterceptor_3_0Helper | org/omg/PortableInterceptor/IORInterceptor_3_0Helper.java .
IORInterceptor_3_0Holder | org/omg/PortableInterceptor/IORInterceptor_3_0Holder.java .
ObjectIdHelper | Type of an object id.
ObjectReferenceFactoryHelper | The object reference factory.
ObjectReferenceFactoryHolder | The object reference factory.
ObjectReferenceTemplateHelper | The object reference template.
ObjectReferenceTemplateHolder | The object reference template.
ObjectReferenceTemplateSeqHelper | Sequence of object reference templates is used for reporting state changes that do not occur on the adapter manager.
ObjectReferenceTemplateSeqHolder | Sequence of object reference templates is used for reporting state changes that do not occur on the adapter manager.
ORBIdHelper | org/omg/PortableInterceptor/ORBIdHelper.java .
ServerIdHelper | org/omg/PortableInterceptor/ServerIdHelper.java .

Exception Summary
ForwardRequest | org/omg/PortableInterceptor/ForwardRequest.java .
InvalidSlot | org/omg/PortableInterceptor/InvalidSlot.java .

Package org.omg.PortableInterceptor Description

Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Interceptor Types

There are currently three types of interceptors that can be registered:
  • IORInterceptor - Used to establish tagged components in the profiles within an IOR.
  • ClientRequestInterceptor - Intercepts the flow of a request/reply sequence through the ORB on the client side.
  • ServerRequestInterceptor - Intercepts the flow of a request/reply sequence through the ORB on the server side.
See the javadocs for class ORBInitializer for how to go about registering interceptors.

Known limitations / unimplemented methods in package org.omg.PortableInterceptor

  • RequestInfo
    • sync_scope(): Always returns SYNC_WITH_TRANSPORT
    • arguments(): Only supported for DII/DSI calls
    • exceptions(): Only supported for DII calls on client side. Not supported on server-side.
    • contexts(): Only supported for DII calls on client side. Not supported on server-side since our ORB does not send contexts.
    • operation_context(): Only supported for DII calls on client side. Not supported on server-side since ORB does not send contexts.
    • result(): Only supported for DII/DSI calls
  • ClientRequestInfo
    • received_exception_id(): Always returns null in the DII case
    • get_request_policy(int type): Not implemented.
  • ServerRequestInfo
    • sending_exception(): Does not support user exceptions on the server side in non-DSI case.

Package Specification

For a precise list of supported sections of official OMG specifications with which the Java[tm] Platform, Standard Edition 6 complies, see Official Specifications for CORBA support in Java SE 6.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


ClientRequestInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface ClientRequestInfo

All Superinterfaces:
ClientRequestInfoOperations, IDLEntity, Object, RequestInfo, RequestInfoOperations, Serializable
public interface ClientRequestInfo
extends ClientRequestInfoOperations, RequestInfo, IDLEntity

Request Information, accessible to client-side request interceptors.

Some attributes and operations on ClientRequestInfo are not valid at all interception points. The following table shows the validity of each attribute or operation. If it is not valid, attempting to access it will result in a BAD_INV_ORDER being thrown with a standard minor code of 14.

 | send_request | send_poll | receive_reply | receive_exception | receive_other
Inherited from RequestInfo:
request_id | yes | yes | yes | yes | yes
operation | yes | yes | yes | yes | yes
arguments | yes1 | no | yes | no | no
exceptions | yes | no | yes | yes | yes
contexts | yes | no | yes | yes | yes
operation_context | yes | no | yes | yes | yes
result | no | no | yes | no | no
response_expected | yes | yes | yes | yes | yes
sync_scope | yes | no | yes | yes | yes
reply_status | no | no | yes | yes | yes
forward_reference | no | no | no | no | yes2
get_slot | yes | yes | yes | yes | yes
get_request_service_context | yes | no | yes | yes | yes
get_reply_service_context | no | no | yes | yes | yes
ClientRequestInfo-specific:
target | yes | yes | yes | yes | yes
effective_target | yes | yes | yes | yes | yes
effective_profile | yes | yes | yes | yes | yes
received_exception | no | no | no | yes | no
received_exception_id | no | no | no | yes | no
get_effective_component | yes | no | yes | yes | yes
get_effective_components | yes | no | yes | yes | yes
get_request_policy | yes | no | yes | yes | yes
add_request_service_context | yes | no | no | no | no

  1. When ClientRequestInfo is passed to send_request, there is an entry in the list for every argument, whether in, inout, or out. But only the in and inout arguments will be available.
  2. If the reply_status atribute is not LOCATION_FORWARD, accessing this attribute will throw BAD_INV_ORDER with a standard minor code of 14.

See Also:
ClientRequestInterceptor

Method Summary
Methods inherited from interface org.omg.PortableInterceptor.ClientRequestInfoOperations
add_request_service_context, effective_profile, effective_target, get_effective_component, get_effective_components, get_request_policy, received_exception_id, received_exception, target
Methods inherited from interface org.omg.PortableInterceptor.RequestInfoOperations
arguments, contexts, exceptions, forward_reference, get_reply_service_context, get_request_service_context, get_slot, operation_context, operation, reply_status, request_id, response_expected, result, sync_scope
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ClientRequestInterceptor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface ClientRequestInterceptor

All Superinterfaces:
ClientRequestInterceptorOperations, IDLEntity, Interceptor, InterceptorOperations, Object, Serializable
public interface ClientRequestInterceptor
extends ClientRequestInterceptorOperations, Interceptor, IDLEntity

Client-side request interceptor.

A request Interceptor is designed to intercept the flow of a request/reply sequence through the ORB at specific points so that services can query the request information and manipulate the service contexts which are propagated between clients and servers. The primary use of request Interceptors is to enable ORB services to transfer context information between clients and servers. There are two types of request Interceptors: client-side and server-side.

To write a client-side Interceptor, implement the ClientRequestInterceptor interface.

See Also:
ClientRequestInfo

Method Summary
Methods inherited from interface org.omg.PortableInterceptor.ClientRequestInterceptorOperations
receive_exception, receive_other, receive_reply, send_poll, send_request
Methods inherited from interface org.omg.PortableInterceptor.InterceptorOperations
destroy, name
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Current

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface Current

All Superinterfaces:
Current, CurrentOperations, IDLEntity, Object, Serializable
public interface Current
extends CurrentOperations, Current, IDLEntity

Portable Interceptors Current (also known as PICurrent) is merely a slot table, the slots of which are used by each service to transfer their context data between their context and the request's or reply's service context. Each service which wishes to use PICurrent reserves a slot or slots at initialization time and uses those slots during the processing of requests and replies.

Before an invocation is made, PICurrent is obtained via a call to ORB.resolve_initial_references( "PICurrent" ). From within the interception points, the data on PICurrent that has moved from the thread scope to the request scope is available via the get_slot operation on the RequestInfo object. A PICurrent can still be obtained via resolve_initial_references, but that is the Interceptor's thread scope PICurrent.

Method Summary
Methods inherited from interface org.omg.PortableInterceptor.CurrentOperations
get_slot, set_slot
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Interceptor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface Interceptor

All Superinterfaces:
IDLEntity, InterceptorOperations, Object, Serializable
All Known Subinterfaces:
ClientRequestInterceptor, IORInterceptor, IORInterceptor_3_0, ServerRequestInterceptor
public interface Interceptor
extends InterceptorOperations, Object, IDLEntity

All Portable Interceptors implement Interceptor.

Method Summary
Methods inherited from interface org.omg.PortableInterceptor.InterceptorOperations
destroy, name
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IORInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface IORInfo

All Superinterfaces:
IDLEntity, IORInfoOperations, Object, Serializable
public interface IORInfo
extends IORInfoOperations, Object, IDLEntity

Provides the server-side ORB service with access to the applicable policies during IOR construction and the ability to add components. The ORB passes an instance of its implementation of this interface as a parameter to IORInterceptor.establish_components.

See Also:
IORInterceptor

Method Summary
Methods inherited from interface org.omg.PortableInterceptor.IORInfoOperations
adapter_template, add_ior_component_to_profile, add_ior_component, current_factory, current_factory, get_effective_policy, manager_id, state
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IORInterceptor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface IORInterceptor

All Superinterfaces:
IDLEntity, Interceptor, InterceptorOperations, IORInterceptorOperations, Object, Serializable
All Known Subinterfaces:
IORInterceptor_3_0
public interface IORInterceptor
extends IORInterceptorOperations, Interceptor, IDLEntity

Interceptor used to establish tagged components in the profiles within an IOR.

In some cases, a portable ORB service implementation may need to add information describing the server's or object's ORB service related capabilities to object references in order to enable the ORB service implementation in the client to function properly.

This is supported through the IORInterceptor and IORInfo interfaces.

See Also:
IORInfo

Method Summary
Methods inherited from interface org.omg.PortableInterceptor.IORInterceptorOperations
establish_components
Methods inherited from interface org.omg.PortableInterceptor.InterceptorOperations
destroy, name
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IORInterceptor_3_0

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface IORInterceptor_3_0

All Superinterfaces:
IDLEntity, Interceptor, InterceptorOperations, IORInterceptor, IORInterceptor_3_0Operations, IORInterceptorOperations, Object, Serializable
public interface IORInterceptor_3_0
extends IORInterceptor_3_0Operations, IORInterceptor, IDLEntity

org/omg/PortableInterceptor/IORInterceptor_3_0.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:26 AM GMT-08:00

Method Summary
Methods inherited from interface org.omg.PortableInterceptor.IORInterceptor_3_0Operations
adapter_manager_state_changed, adapter_state_changed, components_established
Methods inherited from interface org.omg.PortableInterceptor.IORInterceptorOperations
establish_components
Methods inherited from interface org.omg.PortableInterceptor.InterceptorOperations
destroy, name
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ORBInitializer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface ORBInitializer

All Superinterfaces:
IDLEntity, Object, ORBInitializerOperations, Serializable
public interface ORBInitializer
extends ORBInitializerOperations, Object, IDLEntity

Facilitates interceptor registration and ORB initialization.

Interceptors are intended to be a means by which ORB services gain access to ORB processing, effectively becoming part of the ORB. Since Interceptors are part of the ORB, when ORB.init returns an ORB, the Interceptors shall have been registered. Interceptors cannot be registered on an ORB after it has been returned by a call to ORB.init.

An Interceptor is registered by registering an associated ORBInitializer object which implements the ORBInitializer interface. When an ORB is initializing, it shall call each registered ORBInitializer, passing it an ORBInitInfo object which is used to register its Interceptor.

Registering ORB Initializers in Java

ORBInitializers are registered via Java ORB properties.

The property names are of the form:

org.omg.PortableInterceptor.ORBInitializerClass.<Service>
where <Service> is the string name of a class which implements
org.omg.PortableInterceptor.ORBInitializer
To avoid name collisions, the reverse DNS name convention should be used. For example, if company X has three initializers, it could define the following properties:
  • org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init1
  • org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init2
  • org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init3
During ORB.init, these ORB properties which begin with org.omg.PortableInterceptor.ORBInitializerClass shall be collected, the <Service> portion of each property shall be extracted, an object shall be instantiated with the <Service> string as its class name, and the pre_init and post_init methods shall be called on that object. If there are any exceptions, the ORB shall ignore them and proceed.

Example

A client-side logging service written by company X, for example, may have the following ORBInitializer implementation:

 package com.x.logging;

 import org.omg.PortableInterceptor.Interceptor;
 import org.omg.PortableInterceptor.ORBInitializer;
 import org.omg.PortableInterceptor.ORBInitInfo;

 public class LoggingService implements ORBInitializer {
     void pre_init( ORBInitInfo info ) {
         // Instantiate the Logging Service s Interceptor.
         Interceptor interceptor = new LoggingInterceptor();

         // Register the Logging Service s Interceptor.
         info.add_client_request_interceptor( interceptor );
     }

     void post_init( ORBInitInfo info ) {
         // This service does not need two init points.
     }
 }
To run a program called MyApp using this logging service, the user could type:
java -Dorg.omg.PortableInterceptor.ORBInitializerClass.com.x.Logging.LoggingService MyApp

Notes about Registering Interceptors

Request Interceptors are registered on a per-ORB basis.

To achieve virtual per-object Interceptors, query the policies on the target from within the interception points to determine whether they should do any work.

To achieve virtual per-POA Interceptors, instantiate each POA with a different ORB. While Interceptors may be ordered administratively, there is no concept of order with respect to the registration of Interceptors. Request Interceptors are concerned with service contexts. Service contexts have no order, so there is no purpose for request Interceptors to have an order. IOR Interceptors are concerned with tagged components. Tagged components also have no order, so there is no purpose for IOR Interceptors to have an order.

Registration code should avoid using the ORB (i.e., calling ORB.init with the provided orb_id). Since registration occurs during ORB initialization, results of invocations on this ORB while it is in this state are undefined.

See Also:
ORBInitInfo

Method Summary
Methods inherited from interface org.omg.PortableInterceptor.ORBInitializerOperations
post_init, pre_init
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ORBInitInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface ORBInitInfo

All Superinterfaces:
IDLEntity, Object, ORBInitInfoOperations, Serializable
public interface ORBInitInfo
extends ORBInitInfoOperations, Object, IDLEntity

Passed to each ORBInitializer, allowing it to to register interceptors and perform other duties while the ORB is initializing.

The ORBInitInfo object is only valid during ORB.init. If a service keeps a reference to its ORBInitInfo object and tries to use it after ORB.init returns, the object no longer exists and an OBJECT_NOT_EXIST exception shall be thrown.

See Also:
ORBInitializer

Method Summary
Methods inherited from interface org.omg.PortableInterceptor.ORBInitInfoOperations
add_client_request_interceptor, add_ior_interceptor, add_server_request_interceptor, allocate_slot_id, arguments, codec_factory, orb_id, register_initial_reference, register_policy_factory, resolve_initial_references
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


org.omg.PortableInterceptor Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.PortableInterceptor

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.PortableInterceptor.AdapterManagerIdHelper
    • org.omg.PortableInterceptor.AdapterNameHelper
    • org.omg.PortableInterceptor.AdapterStateHelper
    • org.omg.PortableInterceptor.CurrentHelper
    • org.omg.PortableInterceptor.ForwardRequestHelper
    • org.omg.PortableInterceptor.InvalidSlotHelper
    • org.omg.PortableInterceptor.IORInterceptor_3_0Helper
    • org.omg.PortableInterceptor.IORInterceptor_3_0Holder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.PortableInterceptor.ObjectIdHelper
    • org.omg.PortableInterceptor.ObjectReferenceFactoryHelper
    • org.omg.PortableInterceptor.ObjectReferenceFactoryHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.PortableInterceptor.ObjectReferenceTemplateHelper
    • org.omg.PortableInterceptor.ObjectReferenceTemplateHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.PortableInterceptor.ObjectReferenceTemplateSeqHelper
    • org.omg.PortableInterceptor.ObjectReferenceTemplateSeqHolder (implements org.omg.CORBA.portable.Streamable)
    • org.omg.PortableInterceptor.ORBIdHelper
    • org.omg.PortableInterceptor.ServerIdHelper
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.omg.CORBA.UserException (implements org.omg.CORBA.portable.IDLEntity)
          • org.omg.PortableInterceptor.ForwardRequest
          • org.omg.PortableInterceptor.InvalidSlot

Interface Hierarchy

  • org.omg.PortableInterceptor.ACTIVE
  • org.omg.CORBA.CurrentOperations
    • org.omg.CORBA.Current (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
      • org.omg.PortableInterceptor.Current (also extends org.omg.PortableInterceptor.CurrentOperations, org.omg.CORBA.portable.IDLEntity)
    • org.omg.PortableInterceptor.CurrentOperations
      • org.omg.PortableInterceptor.Current (also extends org.omg.CORBA.Current, org.omg.CORBA.portable.IDLEntity)
  • org.omg.PortableInterceptor.DISCARDING
  • org.omg.PortableInterceptor.HOLDING
  • org.omg.PortableInterceptor.INACTIVE
  • org.omg.PortableInterceptor.InterceptorOperations
    • org.omg.PortableInterceptor.ClientRequestInterceptorOperations
      • org.omg.PortableInterceptor.ClientRequestInterceptor (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.Interceptor)
    • org.omg.PortableInterceptor.Interceptor (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
      • org.omg.PortableInterceptor.ClientRequestInterceptor (also extends org.omg.PortableInterceptor.ClientRequestInterceptorOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.PortableInterceptor.IORInterceptor (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.IORInterceptorOperations)
        • org.omg.PortableInterceptor.IORInterceptor_3_0 (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.IORInterceptor_3_0Operations)
      • org.omg.PortableInterceptor.ServerRequestInterceptor (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.ServerRequestInterceptorOperations)
    • org.omg.PortableInterceptor.IORInterceptorOperations
      • org.omg.PortableInterceptor.IORInterceptor (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.Interceptor)
        • org.omg.PortableInterceptor.IORInterceptor_3_0 (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.IORInterceptor_3_0Operations)
      • org.omg.PortableInterceptor.IORInterceptor_3_0Operations
        • org.omg.PortableInterceptor.IORInterceptor_3_0 (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.IORInterceptor)
    • org.omg.PortableInterceptor.ServerRequestInterceptorOperations
      • org.omg.PortableInterceptor.ServerRequestInterceptor (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.Interceptor)
  • org.omg.PortableInterceptor.IORInfoOperations
    • org.omg.PortableInterceptor.IORInfo (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
  • org.omg.PortableInterceptor.LOCATION_FORWARD
  • org.omg.PortableInterceptor.NON_EXISTENT
  • org.omg.CORBA.Object
    • org.omg.CORBA.Current (also extends org.omg.CORBA.CurrentOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.PortableInterceptor.Current (also extends org.omg.PortableInterceptor.CurrentOperations, org.omg.CORBA.portable.IDLEntity)
    • org.omg.PortableInterceptor.Interceptor (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.InterceptorOperations)
      • org.omg.PortableInterceptor.ClientRequestInterceptor (also extends org.omg.PortableInterceptor.ClientRequestInterceptorOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.PortableInterceptor.IORInterceptor (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.IORInterceptorOperations)
        • org.omg.PortableInterceptor.IORInterceptor_3_0 (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.IORInterceptor_3_0Operations)
      • org.omg.PortableInterceptor.ServerRequestInterceptor (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.ServerRequestInterceptorOperations)
    • org.omg.PortableInterceptor.IORInfo (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.IORInfoOperations)
    • org.omg.PortableInterceptor.ORBInitializer (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.ORBInitializerOperations)
    • org.omg.PortableInterceptor.ORBInitInfo (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.ORBInitInfoOperations)
    • org.omg.PortableInterceptor.PolicyFactory (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.PolicyFactoryOperations)
    • org.omg.PortableInterceptor.RequestInfo (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.RequestInfoOperations)
      • org.omg.PortableInterceptor.ClientRequestInfo (also extends org.omg.PortableInterceptor.ClientRequestInfoOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.PortableInterceptor.ServerRequestInfo (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.ServerRequestInfoOperations)
  • org.omg.PortableInterceptor.ORBInitializerOperations
    • org.omg.PortableInterceptor.ORBInitializer (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
  • org.omg.PortableInterceptor.ORBInitInfoOperations
    • org.omg.PortableInterceptor.ORBInitInfo (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
  • org.omg.PortableInterceptor.PolicyFactoryOperations
    • org.omg.PortableInterceptor.PolicyFactory (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
  • org.omg.PortableInterceptor.RequestInfoOperations
    • org.omg.PortableInterceptor.ClientRequestInfoOperations
      • org.omg.PortableInterceptor.ClientRequestInfo (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.RequestInfo)
    • org.omg.PortableInterceptor.RequestInfo (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
      • org.omg.PortableInterceptor.ClientRequestInfo (also extends org.omg.PortableInterceptor.ClientRequestInfoOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.PortableInterceptor.ServerRequestInfo (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.ServerRequestInfoOperations)
    • org.omg.PortableInterceptor.ServerRequestInfoOperations
      • org.omg.PortableInterceptor.ServerRequestInfo (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.RequestInfo)
  • java.io.Serializable
    • org.omg.CORBA.portable.IDLEntity
      • org.omg.PortableInterceptor.ClientRequestInfo (also extends org.omg.PortableInterceptor.ClientRequestInfoOperations, org.omg.PortableInterceptor.RequestInfo)
      • org.omg.PortableInterceptor.ClientRequestInterceptor (also extends org.omg.PortableInterceptor.ClientRequestInterceptorOperations, org.omg.PortableInterceptor.Interceptor)
      • org.omg.CORBA.Current (also extends org.omg.CORBA.CurrentOperations, org.omg.CORBA.Object)
        • org.omg.PortableInterceptor.Current (also extends org.omg.PortableInterceptor.CurrentOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.PortableInterceptor.Current (also extends org.omg.CORBA.Current, org.omg.PortableInterceptor.CurrentOperations)
      • org.omg.PortableInterceptor.Interceptor (also extends org.omg.PortableInterceptor.InterceptorOperations, org.omg.CORBA.Object)
        • org.omg.PortableInterceptor.ClientRequestInterceptor (also extends org.omg.PortableInterceptor.ClientRequestInterceptorOperations, org.omg.CORBA.portable.IDLEntity)
        • org.omg.PortableInterceptor.IORInterceptor (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.IORInterceptorOperations)
          • org.omg.PortableInterceptor.IORInterceptor_3_0 (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.IORInterceptor_3_0Operations)
        • org.omg.PortableInterceptor.ServerRequestInterceptor (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.ServerRequestInterceptorOperations)
      • org.omg.PortableInterceptor.IORInfo (also extends org.omg.PortableInterceptor.IORInfoOperations, org.omg.CORBA.Object)
      • org.omg.PortableInterceptor.IORInterceptor (also extends org.omg.PortableInterceptor.Interceptor, org.omg.PortableInterceptor.IORInterceptorOperations)
        • org.omg.PortableInterceptor.IORInterceptor_3_0 (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.IORInterceptor_3_0Operations)
      • org.omg.PortableInterceptor.IORInterceptor_3_0 (also extends org.omg.PortableInterceptor.IORInterceptor, org.omg.PortableInterceptor.IORInterceptor_3_0Operations)
      • org.omg.PortableInterceptor.ORBInitializer (also extends org.omg.CORBA.Object, org.omg.PortableInterceptor.ORBInitializerOperations)
      • org.omg.PortableInterceptor.ORBInitInfo (also extends org.omg.CORBA.Object, org.omg.PortableInterceptor.ORBInitInfoOperations)
      • org.omg.PortableInterceptor.PolicyFactory (also extends org.omg.CORBA.Object, org.omg.PortableInterceptor.PolicyFactoryOperations)
      • org.omg.PortableInterceptor.RequestInfo (also extends org.omg.CORBA.Object, org.omg.PortableInterceptor.RequestInfoOperations)
        • org.omg.PortableInterceptor.ClientRequestInfo (also extends org.omg.PortableInterceptor.ClientRequestInfoOperations, org.omg.CORBA.portable.IDLEntity)
        • org.omg.PortableInterceptor.ServerRequestInfo (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableInterceptor.ServerRequestInfoOperations)
      • org.omg.PortableInterceptor.ServerRequestInfo (also extends org.omg.PortableInterceptor.RequestInfo, org.omg.PortableInterceptor.ServerRequestInfoOperations)
      • org.omg.PortableInterceptor.ServerRequestInterceptor (also extends org.omg.PortableInterceptor.Interceptor, org.omg.PortableInterceptor.ServerRequestInterceptorOperations)
      • org.omg.CORBA.portable.ValueBase
        • org.omg.PortableInterceptor.ObjectReferenceFactory
          • org.omg.PortableInterceptor.ObjectReferenceTemplate
  • org.omg.PortableInterceptor.SUCCESSFUL
  • org.omg.PortableInterceptor.SYSTEM_EXCEPTION
  • org.omg.PortableInterceptor.TRANSPORT_RETRY
  • org.omg.PortableInterceptor.UNKNOWN
  • org.omg.PortableInterceptor.USER_EXCEPTION
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


PolicyFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface PolicyFactory

All Superinterfaces:
IDLEntity, Object, PolicyFactoryOperations, Serializable
public interface PolicyFactory
extends PolicyFactoryOperations, Object, IDLEntity

Enables policy types to be constructed using CORBA.ORB.create_policy.

A portable ORB service implementation registers an instance of the PolicyFactory interface during ORB initialization in order to enable its policy types to be constructed using CORBA.ORB.create_policy. The POA is required to preserve any policy which is registered with ORBInitInfo in this manner.

See Also:
ORBInitInfoOperations.register_policy_factory(int, org.omg.PortableInterceptor.PolicyFactory)

Method Summary
Methods inherited from interface org.omg.PortableInterceptor.PolicyFactoryOperations
create_policy
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RequestInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface RequestInfo

All Superinterfaces:
IDLEntity, Object, RequestInfoOperations, Serializable
All Known Subinterfaces:
ClientRequestInfo, ServerRequestInfo
public interface RequestInfo
extends RequestInfoOperations, Object, IDLEntity

Request Information, accessible to Interceptors.

Each interception point is given an object through which the Interceptor can access request information. Client-side and server-side interception points are concerned with different information, so there are two information objects: ClientRequestInfo is passed to the client-side interception points and ServerRequestInfo is passed to the server-side interception points. But there is information that is common to both, so they both inherit from a common interface: RequestInfo.

See Also:
ClientRequestInfo, ServerRequestInfo

Method Summary
Methods inherited from interface org.omg.PortableInterceptor.RequestInfoOperations
arguments, contexts, exceptions, forward_reference, get_reply_service_context, get_request_service_context, get_slot, operation_context, operation, reply_status, request_id, response_expected, result, sync_scope
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServerRequestInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface ServerRequestInfo

All Superinterfaces:
IDLEntity, Object, RequestInfo, RequestInfoOperations, Serializable, ServerRequestInfoOperations
public interface ServerRequestInfo
extends ServerRequestInfoOperations, RequestInfo, IDLEntity

Request Information, accessible to server-side request interceptors.

Some attributes and operations on ServerRequestInfo are not valid at all interception points. The following table shows the validity of each attribute or operation. If it is not valid, attempting to access it will result in a BAD_INV_ORDER being thrown with a standard minor code of 14.

 | receive_request_ service_contexts | receive_request | send_reply | send_exception | send_other
Inherited from RequestInfo:
request_id | yes | yes | yes | yes | yes
operation | yes | yes | yes | yes | yes
arguments | no | yes1 | yes | no2 | no2
exceptions | no | yes | yes | yes | yes
contexts | no | yes | yes | yes | yes
operation_context | no | yes | yes | no | no
result | no | no | yes | no | no
response_expected | yes | yes | yes | yes | yes
sync_scope | yes | yes | yes | yes | yes
request_id | yes | yes | yes | yes | yes
operation | yes | yes | yes | yes | yes
arguments | no | yes1 | yes | no2 | no2
exceptions | no | yes | yes | yes | yes
contexts | no | yes | yes | yes | yes
operation_context | no | yes | yes | no | no
result | no | no | yes | no | no
response_expected | yes | yes | yes | yes | yes
sync_scope | yes | yes | yes | yes | yes
reply_status | no | no | yes | yes | yes
forward_reference | no | no | no | no | yes2
get_slot | yes | yes | yes | yes | yes
get_request_service_context | yes | no | yes | yes | yes
get_reply_service_context | no | no | yes | yes | yes
ServerRequestInfo-specific:
sending_exception | no | no | no | yes | no
object_id | no | yes | yes | yes3 | yes3
adapter_id | no | yes | yes | yes3 | yes3
server_id | no | yes | yes | yes | yes
orb_id | no | yes | yes | yes | yes
adapter_name | no | yes | yes | yes | yes
target_most_derived_interface | no | yes | no4 | no4 | no4
get_server_policy | yes | yes | yes | yes | yes
set_slot | yes | yes | yes | yes | yes
target_is_a | no | yes | no4 | no4 | no4
add_reply_service_context | yes | yes | yes | yes | yes

  1. When ServerRequestInfo is passed to receive_request, there is an entry in the list for every argument, whether in, inout, or out. But only the in and inout arguments will be available.
  2. If the reply_status attribute is not LOCATION_FORWARD, accessing this attribute will throw BAD_INV_ORDER with a standard minor code of 14.
  3. If the servant locator caused a location forward, or thrown an exception, this attribute/operation may not be available in this interception point. NO_RESOURCES with a standard minor code of 1 will be thrown if it is not available.
  4. The operation is not available in this interception point because the necessary information requires access to the target object's servant, which may no longer be available to the ORB. For example, if the object's adapter is a POA that uses a ServantLocator, then the ORB invokes the interception point after it calls ServantLocator.postinvoke()
    5. .

See Also:
ServerRequestInterceptor

Method Summary
Methods inherited from interface org.omg.PortableInterceptor.ServerRequestInfoOperations
adapter_id, adapter_name, add_reply_service_context, get_server_policy, object_id, orb_id, sending_exception, server_id, set_slot, target_is_a, target_most_derived_interface
Methods inherited from interface org.omg.PortableInterceptor.RequestInfoOperations
arguments, contexts, exceptions, forward_reference, get_reply_service_context, get_request_service_context, get_slot, operation_context, operation, reply_status, request_id, response_expected, result, sync_scope
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServerRequestInterceptor

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface ServerRequestInterceptor

All Superinterfaces:
IDLEntity, Interceptor, InterceptorOperations, Object, Serializable, ServerRequestInterceptorOperations
public interface ServerRequestInterceptor
extends ServerRequestInterceptorOperations, Interceptor, IDLEntity

Server-side request interceptor.

A request Interceptor is designed to intercept the flow of a request/reply sequence through the ORB at specific points so that services can query the request information and manipulate the service contexts which are propagated between clients and servers. The primary use of request Interceptors is to enable ORB services to transfer context information between clients and servers. There are two types of request Interceptors: client-side and server-side.

To write a server-side Interceptor, implement the ServerRequestInterceptor interface.

See Also:
ServerRequestInfo

Method Summary
Methods inherited from interface org.omg.PortableInterceptor.ServerRequestInterceptorOperations
receive_request_service_contexts, receive_request, send_exception, send_other, send_reply
Methods inherited from interface org.omg.PortableInterceptor.InterceptorOperations
destroy, name
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Package org.omg.PortableInterceptor

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.PortableInterceptor

Packages that use org.omg.PortableInterceptor
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Classes in org.omg.PortableInterceptor used by org.omg.PortableInterceptor
ClientRequestInfo
Request Information, accessible to client-side request interceptors.
ClientRequestInfoOperations
Request Information, accessible to client-side request interceptors.
ClientRequestInterceptor
Client-side request interceptor.
ClientRequestInterceptorOperations
Client-side request interceptor.
Current
Portable Interceptors Current (also known as PICurrent) is merely a slot table, the slots of which are used by each service to transfer their context data between their context and the request's or reply's service context.
CurrentOperations
Portable Interceptors Current (also known as PICurrent) is merely a slot table, the slots of which are used by each service to transfer their context data between their context and the request's or reply's service context.
ForwardRequest
org/omg/PortableInterceptor/ForwardRequest.java .
Interceptor
All Portable Interceptors implement Interceptor.
InterceptorOperations
All Portable Interceptors implement Interceptor.
InvalidSlot
org/omg/PortableInterceptor/InvalidSlot.java .
IORInfo
Provides the server-side ORB service with access to the applicable policies during IOR construction and the ability to add components.
IORInfoOperations
Provides the server-side ORB service with access to the applicable policies during IOR construction and the ability to add components.
IORInterceptor
Interceptor used to establish tagged components in the profiles within an IOR.
IORInterceptor_3_0
org/omg/PortableInterceptor/IORInterceptor_3_0.java .
IORInterceptor_3_0Operations
org/omg/PortableInterceptor/IORInterceptor_3_0Operations.java .
IORInterceptorOperations
Interceptor used to establish tagged components in the profiles within an IOR.
ObjectReferenceFactory
The object reference factory.
ObjectReferenceTemplate
The object reference template.
ORBInitializerOperations
Facilitates interceptor registration and ORB initialization.
ORBInitInfo
Passed to each ORBInitializer, allowing it to to register interceptors and perform other duties while the ORB is initializing.
ORBInitInfoOperations
Passed to each ORBInitializer, allowing it to to register interceptors and perform other duties while the ORB is initializing.
PolicyFactory
Enables policy types to be constructed using CORBA.ORB.create_policy.
PolicyFactoryOperations
Enables policy types to be constructed using CORBA.ORB.create_policy.
RequestInfo
Request Information, accessible to Interceptors.
RequestInfoOperations
Request Information, accessible to Interceptors.
ServerRequestInfo
Request Information, accessible to server-side request interceptors.
ServerRequestInfoOperations
Request Information, accessible to server-side request interceptors.
ServerRequestInterceptor
Server-side request interceptor.
ServerRequestInterceptorOperations
Server-side request interceptor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ACTIVE

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface ACTIVE

public interface ACTIVE

org/omg/PortableInterceptor/ACTIVE.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:26 AM GMT-08:00

Field Summary
static short value
Object adapter state that indicates normal request processing.

Field Detail

value

static final short value
Object adapter state that indicates normal request processing.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AdapterManagerIdHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class AdapterManagerIdHelper

java.lang.Object
    extended by  org.omg.PortableInterceptor.AdapterManagerIdHelper

public abstract class AdapterManagerIdHelper
extends Object

Adapter manager identifier. Every object adapter has an adapter manager, indicated in this API only through the ID. A group of object adapter instances may share the same adapter manager, in which case state transitions reported for the adapter manager are observed by all object adapters with the same adapter manager ID.

Constructor Summary
AdapterManagerIdHelper()
Method Summary
static int | extract(Any a)
static String | id()
static void | insert(Any a, int that)
static int | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, int value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AdapterManagerIdHelper

public AdapterManagerIdHelper()
Method Detail

insert

public static void insert(Any a,
                          int that)

extract

public static int extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static int read(InputStream istream)

write

public static void write(OutputStream ostream,
                         int value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AdapterNameHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class AdapterNameHelper

java.lang.Object
    extended by  org.omg.PortableInterceptor.AdapterNameHelper

public abstract class AdapterNameHelper
extends Object

The name of an object adapter. This is unique only within the scope of the ORB that created the object adapter.

Constructor Summary
AdapterNameHelper()
Method Summary
static String[] | extract(Any a)
static String | id()
static void | insert(Any a, String[] that)
static String[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, String[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AdapterNameHelper

public AdapterNameHelper()
Method Detail

insert

public static void insert(Any a,
                          String[] that)

extract

public static String[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static String[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         String[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AdapterStateHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class AdapterStateHelper

java.lang.Object
    extended by  org.omg.PortableInterceptor.AdapterStateHelper

public abstract class AdapterStateHelper
extends Object

Type of object adapter state. State changes are reported either to the object adapter or to the adapter manager.

Constructor Summary
AdapterStateHelper()
Method Summary
static short | extract(Any a)
static String | id()
static void | insert(Any a, short that)
static short | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, short value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AdapterStateHelper

public AdapterStateHelper()
Method Detail

insert

public static void insert(Any a,
                          short that)

extract

public static short extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static short read(InputStream istream)

write

public static void write(OutputStream ostream,
                         short value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class org.omg.PortableInterceptor.AdapterManagerIdHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.AdapterManagerIdHelper

No usage of org.omg.PortableInterceptor.AdapterManagerIdHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.AdapterNameHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.AdapterNameHelper

No usage of org.omg.PortableInterceptor.AdapterNameHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.AdapterStateHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.AdapterStateHelper

No usage of org.omg.PortableInterceptor.AdapterStateHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.CurrentHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.CurrentHelper

No usage of org.omg.PortableInterceptor.CurrentHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.ForwardRequest

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.ForwardRequest

Packages that use ForwardRequest
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of ForwardRequest in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor that return ForwardRequest
static ForwardRequest | ForwardRequestHelper.extract(Any a)
static ForwardRequest | ForwardRequestHelper.read(InputStream istream)

Methods in org.omg.PortableInterceptor with parameters of type ForwardRequest
static void | ForwardRequestHelper.insert(Any a, ForwardRequest that)
static void | ForwardRequestHelper.write(OutputStream ostream, ForwardRequest value)

Methods in org.omg.PortableInterceptor that throw ForwardRequest
void | ClientRequestInterceptorOperations.receive_exception(ClientRequestInfo ri) Indicates to the interceptor that an exception occurred.
void | ClientRequestInterceptorOperations.receive_other(ClientRequestInfo ri) Allows an Interceptor to query the information available when a request results in something other than a normal reply or an exception.
void | ServerRequestInterceptorOperations.receive_request_service_contexts(ServerRequestInfo ri) Allows the interceptor to process service context information.
void | ServerRequestInterceptorOperations.receive_request(ServerRequestInfo ri) Allows an Interceptor to query request information after all the information, including operation parameters, are available.
void | ServerRequestInterceptorOperations.send_exception(ServerRequestInfo ri) Allows an Interceptor to query the exception information and modify the reply service context before the exception is thrown to the client.
void | ServerRequestInterceptorOperations.send_other(ServerRequestInfo ri) Allows an Interceptor to query the information available when a request results in something other than a normal reply or an exception.
void | ClientRequestInterceptorOperations.send_request(ClientRequestInfo ri) Allows an Interceptor to query request information and modify the service context before the request is sent to the server.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.ForwardRequestHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.ForwardRequestHelper

No usage of org.omg.PortableInterceptor.ForwardRequestHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.InvalidSlot

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.InvalidSlot

Packages that use InvalidSlot
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of InvalidSlot in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor that return InvalidSlot
static InvalidSlot | InvalidSlotHelper.extract(Any a)
static InvalidSlot | InvalidSlotHelper.read(InputStream istream)

Methods in org.omg.PortableInterceptor with parameters of type InvalidSlot
static void | InvalidSlotHelper.insert(Any a, InvalidSlot that)
static void | InvalidSlotHelper.write(OutputStream ostream, InvalidSlot value)

Methods in org.omg.PortableInterceptor that throw InvalidSlot
Any | CurrentOperations.get_slot(int id) Retrieves the slot data the application set in PICurrent via get_slot.
Any | RequestInfoOperations.get_slot(int id) Returns the data from the given slot of the PortableInterceptor.Current that is in the scope of the request.
void | ServerRequestInfoOperations.set_slot(int id, Any data) Allows an Interceptor to set a slot in the PortableInterceptor.Current that is in the scope of the request.
void | CurrentOperations.set_slot(int id, Any data) Sets data in a slot.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.InvalidSlotHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.InvalidSlotHelper

No usage of org.omg.PortableInterceptor.InvalidSlotHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.IORInterceptor_3_0Helper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.IORInterceptor_3_0Helper

No usage of org.omg.PortableInterceptor.IORInterceptor_3_0Helper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.IORInterceptor_3_0Holder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.IORInterceptor_3_0Holder

No usage of org.omg.PortableInterceptor.IORInterceptor_3_0Holder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.ObjectIdHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.ObjectIdHelper

No usage of org.omg.PortableInterceptor.ObjectIdHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.ObjectReferenceFactoryHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.ObjectReferenceFactoryHelper

No usage of org.omg.PortableInterceptor.ObjectReferenceFactoryHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.ObjectReferenceFactoryHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.ObjectReferenceFactoryHolder

No usage of org.omg.PortableInterceptor.ObjectReferenceFactoryHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.ObjectReferenceTemplateHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.ObjectReferenceTemplateHelper

No usage of org.omg.PortableInterceptor.ObjectReferenceTemplateHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.ObjectReferenceTemplateHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.ObjectReferenceTemplateHolder

No usage of org.omg.PortableInterceptor.ObjectReferenceTemplateHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.ObjectReferenceTemplateSeqHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.ObjectReferenceTemplateSeqHelper

No usage of org.omg.PortableInterceptor.ObjectReferenceTemplateSeqHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.ObjectReferenceTemplateSeqHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.ObjectReferenceTemplateSeqHolder

No usage of org.omg.PortableInterceptor.ObjectReferenceTemplateSeqHolder

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.ORBIdHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.ORBIdHelper

No usage of org.omg.PortableInterceptor.ORBIdHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.ServerIdHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.ServerIdHelper

No usage of org.omg.PortableInterceptor.ServerIdHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.ACTIVE

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.ACTIVE

No usage of org.omg.PortableInterceptor.ACTIVE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.ClientRequestInfo

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.ClientRequestInfo

Packages that use ClientRequestInfo
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of ClientRequestInfo in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor with parameters of type ClientRequestInfo
void | ClientRequestInterceptorOperations.receive_exception(ClientRequestInfo ri) Indicates to the interceptor that an exception occurred.
void | ClientRequestInterceptorOperations.receive_other(ClientRequestInfo ri) Allows an Interceptor to query the information available when a request results in something other than a normal reply or an exception.
void | ClientRequestInterceptorOperations.receive_reply(ClientRequestInfo ri) Allows an Interceptor to query the information on a reply after it is returned from the server and before control is returned to the client.
void | ClientRequestInterceptorOperations.send_poll(ClientRequestInfo ri) Allows an Interceptor to query information during a Time-Independent Invocation (TII) polling get reply sequence.
void | ClientRequestInterceptorOperations.send_request(ClientRequestInfo ri) Allows an Interceptor to query request information and modify the service context before the request is sent to the server.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.ClientRequestInfoOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.ClientRequestInfoOperations

Packages that use ClientRequestInfoOperations
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of ClientRequestInfoOperations in org.omg.PortableInterceptor

Subinterfaces of ClientRequestInfoOperations in org.omg.PortableInterceptor
 interface ClientRequestInfo
Request Information, accessible to client-side request interceptors.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.ClientRequestInterceptor

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.ClientRequestInterceptor

Packages that use ClientRequestInterceptor
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of ClientRequestInterceptor in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor with parameters of type ClientRequestInterceptor
 void ORBInitInfoOperations.add_client_request_interceptor(ClientRequestInterceptor interceptor)
Used to add a client-side request Interceptor to the list of client-side request Interceptors.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.ClientRequestInterceptorOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.ClientRequestInterceptorOperations

Packages that use ClientRequestInterceptorOperations
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of ClientRequestInterceptorOperations in org.omg.PortableInterceptor

Subinterfaces of ClientRequestInterceptorOperations in org.omg.PortableInterceptor
 interface ClientRequestInterceptor
Client-side request interceptor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.Current

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.Current

Packages that use Current
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of Current in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor that return Current
static Current | CurrentHelper.extract(Any a)
static Current | CurrentHelper.narrow(Object obj)
static Current | CurrentHelper.read(InputStream istream)
static Current | CurrentHelper.unchecked_narrow(Object obj)

Methods in org.omg.PortableInterceptor with parameters of type Current
static void | CurrentHelper.insert(Any a, Current that)
static void | CurrentHelper.write(OutputStream ostream, Current value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.CurrentOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.CurrentOperations

Packages that use CurrentOperations
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of CurrentOperations in org.omg.PortableInterceptor

Subinterfaces of CurrentOperations in org.omg.PortableInterceptor
 interface Current
Portable Interceptors Current (also known as PICurrent) is merely a slot table, the slots of which are used by each service to transfer their context data between their context and the request's or reply's service context.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.DISCARDING

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.DISCARDING

No usage of org.omg.PortableInterceptor.DISCARDING

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.HOLDING

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.HOLDING

No usage of org.omg.PortableInterceptor.HOLDING

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.INACTIVE

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.INACTIVE

No usage of org.omg.PortableInterceptor.INACTIVE

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.Interceptor

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.Interceptor

Packages that use Interceptor
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of Interceptor in org.omg.PortableInterceptor

Subinterfaces of Interceptor in org.omg.PortableInterceptor
interface | ClientRequestInterceptor Client-side request interceptor.
interface | IORInterceptor Interceptor used to establish tagged components in the profiles within an IOR.
interface | IORInterceptor_3_0 org/omg/PortableInterceptor/IORInterceptor_3_0.java .
interface | ServerRequestInterceptor Server-side request interceptor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.InterceptorOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.InterceptorOperations

Packages that use InterceptorOperations
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of InterceptorOperations in org.omg.PortableInterceptor

Subinterfaces of InterceptorOperations in org.omg.PortableInterceptor
interface | ClientRequestInterceptor Client-side request interceptor.
interface | ClientRequestInterceptorOperations Client-side request interceptor.
interface | Interceptor All Portable Interceptors implement Interceptor.
interface | IORInterceptor Interceptor used to establish tagged components in the profiles within an IOR.
interface | IORInterceptor_3_0 org/omg/PortableInterceptor/IORInterceptor_3_0.java .
interface | IORInterceptor_3_0Operations org/omg/PortableInterceptor/IORInterceptor_3_0Operations.java .
interface | IORInterceptorOperations Interceptor used to establish tagged components in the profiles within an IOR.
interface | ServerRequestInterceptor Server-side request interceptor.
interface | ServerRequestInterceptorOperations Server-side request interceptor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.IORInfo

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.IORInfo

Packages that use IORInfo
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of IORInfo in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor with parameters of type IORInfo
void | IORInterceptor_3_0Operations.components_established(IORInfo info) The components_established method is invoked on all registered IORInterceptor_3_0 instances after establish_components has been invoked on all registered IORInterceptor instances.
void | IORInterceptorOperations.establish_components(IORInfo info) A server side ORB calls the establish_components operation on all registered IORInterceptor instances when it is assembling the list of components that will be included in the profile or profiles of an object reference.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.IORInfoOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.IORInfoOperations

Packages that use IORInfoOperations
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of IORInfoOperations in org.omg.PortableInterceptor

Subinterfaces of IORInfoOperations in org.omg.PortableInterceptor
 interface IORInfo
Provides the server-side ORB service with access to the applicable policies during IOR construction and the ability to add components.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.IORInterceptor

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.IORInterceptor

Packages that use IORInterceptor
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of IORInterceptor in org.omg.PortableInterceptor

Subinterfaces of IORInterceptor in org.omg.PortableInterceptor
 interface IORInterceptor_3_0
org/omg/PortableInterceptor/IORInterceptor_3_0.java .

Methods in org.omg.PortableInterceptor with parameters of type IORInterceptor
 void ORBInitInfoOperations.add_ior_interceptor(IORInterceptor interceptor)
Used to add an IOR Interceptor to the list of IOR Interceptors.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.IORInterceptorOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.IORInterceptorOperations

Packages that use IORInterceptorOperations
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of IORInterceptorOperations in org.omg.PortableInterceptor

Subinterfaces of IORInterceptorOperations in org.omg.PortableInterceptor
interface | IORInterceptor Interceptor used to establish tagged components in the profiles within an IOR.
interface | IORInterceptor_3_0 org/omg/PortableInterceptor/IORInterceptor_3_0.java .
interface | IORInterceptor_3_0Operations org/omg/PortableInterceptor/IORInterceptor_3_0Operations.java .

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.IORInterceptor_3_0

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.IORInterceptor_3_0

Packages that use IORInterceptor_3_0
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of IORInterceptor_3_0 in org.omg.PortableInterceptor

Fields in org.omg.PortableInterceptor declared as IORInterceptor_3_0
 IORInterceptor_3_0 IORInterceptor_3_0Holder.value

Methods in org.omg.PortableInterceptor that return IORInterceptor_3_0
static IORInterceptor_3_0 | IORInterceptor_3_0Helper.extract(Any a)
static IORInterceptor_3_0 | IORInterceptor_3_0Helper.narrow(Object obj)
static IORInterceptor_3_0 | IORInterceptor_3_0Helper.read(InputStream istream)
static IORInterceptor_3_0 | IORInterceptor_3_0Helper.unchecked_narrow(Object obj)

Methods in org.omg.PortableInterceptor with parameters of type IORInterceptor_3_0
static void | IORInterceptor_3_0Helper.insert(Any a, IORInterceptor_3_0 that)
static void | IORInterceptor_3_0Helper.write(OutputStream ostream, IORInterceptor_3_0 value)

Constructors in org.omg.PortableInterceptor with parameters of type IORInterceptor_3_0
IORInterceptor_3_0Holder(IORInterceptor_3_0 initialValue)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.IORInterceptor_3_0Operations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.IORInterceptor_3_0Operations

Packages that use IORInterceptor_3_0Operations
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of IORInterceptor_3_0Operations in org.omg.PortableInterceptor

Subinterfaces of IORInterceptor_3_0Operations in org.omg.PortableInterceptor
 interface IORInterceptor_3_0
org/omg/PortableInterceptor/IORInterceptor_3_0.java .

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.LOCATION_FORWARD

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.LOCATION_FORWARD

No usage of org.omg.PortableInterceptor.LOCATION_FORWARD

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.NON_EXISTENT

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.NON_EXISTENT

No usage of org.omg.PortableInterceptor.NON_EXISTENT

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.ObjectReferenceFactory

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.ObjectReferenceFactory

Packages that use ObjectReferenceFactory
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of ObjectReferenceFactory in org.omg.PortableInterceptor

Subinterfaces of ObjectReferenceFactory in org.omg.PortableInterceptor
 interface ObjectReferenceTemplate
The object reference template.

Fields in org.omg.PortableInterceptor declared as ObjectReferenceFactory
 ObjectReferenceFactory ObjectReferenceFactoryHolder.value

Methods in org.omg.PortableInterceptor that return ObjectReferenceFactory
ObjectReferenceFactory | IORInfoOperations.current_factory() On read, returns the current factory that will be used to create object references for the object adapter that was just created and is running IOR interceptors.
static ObjectReferenceFactory | ObjectReferenceFactoryHelper.extract(Any a)
static ObjectReferenceFactory | ObjectReferenceFactoryHelper.read(InputStream istream)

Methods in org.omg.PortableInterceptor with parameters of type ObjectReferenceFactory
void | IORInfoOperations.current_factory(ObjectReferenceFactory newCurrent_factory) On read, returns the current factory that will be used to create object references for the object adapter that was just created and is running IOR interceptors.
static void | ObjectReferenceFactoryHelper.insert(Any a, ObjectReferenceFactory that)
static void | ObjectReferenceFactoryHelper.write(OutputStream ostream, ObjectReferenceFactory value)

Constructors in org.omg.PortableInterceptor with parameters of type ObjectReferenceFactory
ObjectReferenceFactoryHolder(ObjectReferenceFactory initialValue)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.ObjectReferenceTemplate

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.ObjectReferenceTemplate

Packages that use ObjectReferenceTemplate
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of ObjectReferenceTemplate in org.omg.PortableInterceptor

Fields in org.omg.PortableInterceptor declared as ObjectReferenceTemplate
ObjectReferenceTemplate[] | ObjectReferenceTemplateSeqHolder.value
ObjectReferenceTemplate | ObjectReferenceTemplateHolder.value

Methods in org.omg.PortableInterceptor that return ObjectReferenceTemplate
ObjectReferenceTemplate | IORInfoOperations.adapter_template() Return the object reference template of the object adapter that was just created and is running IOR interceptors.
static ObjectReferenceTemplate[] | ObjectReferenceTemplateSeqHelper.extract(Any a)
static ObjectReferenceTemplate | ObjectReferenceTemplateHelper.extract(Any a)
static ObjectReferenceTemplate[] | ObjectReferenceTemplateSeqHelper.read(InputStream istream)
static ObjectReferenceTemplate | ObjectReferenceTemplateHelper.read(InputStream istream)

Methods in org.omg.PortableInterceptor with parameters of type ObjectReferenceTemplate
void | IORInterceptor_3_0Operations.adapter_state_changed(ObjectReferenceTemplate[] templates, short state) Called whenever the state of an object adapter changes, and the state change is not caused by an adapter manager.
static void | ObjectReferenceTemplateHelper.insert(Any a, ObjectReferenceTemplate that)
static void | ObjectReferenceTemplateSeqHelper.insert(Any a, ObjectReferenceTemplate[] that)
static void | ObjectReferenceTemplateHelper.write(OutputStream ostream, ObjectReferenceTemplate value)
static void | ObjectReferenceTemplateSeqHelper.write(OutputStream ostream, ObjectReferenceTemplate[] value)

Constructors in org.omg.PortableInterceptor with parameters of type ObjectReferenceTemplate
ObjectReferenceTemplateHolder(ObjectReferenceTemplate initialValue)
ObjectReferenceTemplateSeqHolder(ObjectReferenceTemplate[] initialValue)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.ORBInitializer

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.ORBInitializer

No usage of org.omg.PortableInterceptor.ORBInitializer

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.ORBInitializerOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.ORBInitializerOperations

Packages that use ORBInitializerOperations
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of ORBInitializerOperations in org.omg.PortableInterceptor

Subinterfaces of ORBInitializerOperations in org.omg.PortableInterceptor
 interface ORBInitializer
Facilitates interceptor registration and ORB initialization.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.ORBInitInfo

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.ORBInitInfo

Packages that use ORBInitInfo
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of ORBInitInfo in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor with parameters of type ORBInitInfo
void | ORBInitializerOperations.post_init(ORBInitInfo info) Called during ORB initialization.
void | ORBInitializerOperations.pre_init(ORBInitInfo info) Called during ORB initialization.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.ORBInitInfoOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.ORBInitInfoOperations

Packages that use ORBInitInfoOperations
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of ORBInitInfoOperations in org.omg.PortableInterceptor

Subinterfaces of ORBInitInfoOperations in org.omg.PortableInterceptor
 interface ORBInitInfo
Passed to each ORBInitializer, allowing it to to register interceptors and perform other duties while the ORB is initializing.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.PolicyFactory

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.PolicyFactory

Packages that use PolicyFactory
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of PolicyFactory in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor with parameters of type PolicyFactory
 void ORBInitInfoOperations.register_policy_factory(int type, PolicyFactory policy_factory)
Registers a PolicyFactory for the given PolicyType.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.PolicyFactoryOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.PolicyFactoryOperations

Packages that use PolicyFactoryOperations
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of PolicyFactoryOperations in org.omg.PortableInterceptor

Subinterfaces of PolicyFactoryOperations in org.omg.PortableInterceptor
 interface PolicyFactory
Enables policy types to be constructed using CORBA.ORB.create_policy.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.RequestInfo

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.RequestInfo

Packages that use RequestInfo
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of RequestInfo in org.omg.PortableInterceptor

Subinterfaces of RequestInfo in org.omg.PortableInterceptor
interface | ClientRequestInfo Request Information, accessible to client-side request interceptors.
interface | ServerRequestInfo Request Information, accessible to server-side request interceptors.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.RequestInfoOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.RequestInfoOperations

Packages that use RequestInfoOperations
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of RequestInfoOperations in org.omg.PortableInterceptor

Subinterfaces of RequestInfoOperations in org.omg.PortableInterceptor
interface | ClientRequestInfo Request Information, accessible to client-side request interceptors.
interface | ClientRequestInfoOperations Request Information, accessible to client-side request interceptors.
interface | RequestInfo Request Information, accessible to Interceptors.
interface | ServerRequestInfo Request Information, accessible to server-side request interceptors.
interface | ServerRequestInfoOperations Request Information, accessible to server-side request interceptors.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.ServerRequestInfo

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.ServerRequestInfo

Packages that use ServerRequestInfo
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of ServerRequestInfo in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor with parameters of type ServerRequestInfo
void | ServerRequestInterceptorOperations.receive_request_service_contexts(ServerRequestInfo ri) Allows the interceptor to process service context information.
void | ServerRequestInterceptorOperations.receive_request(ServerRequestInfo ri) Allows an Interceptor to query request information after all the information, including operation parameters, are available.
void | ServerRequestInterceptorOperations.send_exception(ServerRequestInfo ri) Allows an Interceptor to query the exception information and modify the reply service context before the exception is thrown to the client.
void | ServerRequestInterceptorOperations.send_other(ServerRequestInfo ri) Allows an Interceptor to query the information available when a request results in something other than a normal reply or an exception.
void | ServerRequestInterceptorOperations.send_reply(ServerRequestInfo ri) Allows an Interceptor to query reply information and modify the reply service context after the target operation has been invoked and before the reply is returned to the client.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.ServerRequestInfoOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.ServerRequestInfoOperations

Packages that use ServerRequestInfoOperations
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of ServerRequestInfoOperations in org.omg.PortableInterceptor

Subinterfaces of ServerRequestInfoOperations in org.omg.PortableInterceptor
 interface ServerRequestInfo
Request Information, accessible to server-side request interceptors.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.ServerRequestInterceptor

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.ServerRequestInterceptor

Packages that use ServerRequestInterceptor
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of ServerRequestInterceptor in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor with parameters of type ServerRequestInterceptor
 void ORBInitInfoOperations.add_server_request_interceptor(ServerRequestInterceptor interceptor)
Used to add a server-side request Interceptor to the list of server-side request Interceptors.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.ServerRequestInterceptorOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.ServerRequestInterceptorOperations

Packages that use ServerRequestInterceptorOperations
org.omg.PortableInterceptor Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.

Uses of ServerRequestInterceptorOperations in org.omg.PortableInterceptor

Subinterfaces of ServerRequestInterceptorOperations in org.omg.PortableInterceptor
 interface ServerRequestInterceptor
Server-side request interceptor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.SUCCESSFUL

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.SUCCESSFUL

No usage of org.omg.PortableInterceptor.SUCCESSFUL

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.SYSTEM_EXCEPTION

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.SYSTEM_EXCEPTION

No usage of org.omg.PortableInterceptor.SYSTEM_EXCEPTION

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.TRANSPORT_RETRY

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.TRANSPORT_RETRY

No usage of org.omg.PortableInterceptor.TRANSPORT_RETRY

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.UNKNOWN

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.UNKNOWN

No usage of org.omg.PortableInterceptor.UNKNOWN

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableInterceptor.USER_EXCEPTION

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableInterceptor.USER_EXCEPTION

No usage of org.omg.PortableInterceptor.USER_EXCEPTION

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ClientRequestInfoOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface ClientRequestInfoOperations

All Superinterfaces:
RequestInfoOperations
All Known Subinterfaces:
ClientRequestInfo
public interface ClientRequestInfoOperations
extends RequestInfoOperations

Request Information, accessible to client-side request interceptors.

Some attributes and operations on ClientRequestInfo are not valid at all interception points. The following table shows the validity of each attribute or operation. If it is not valid, attempting to access it will result in a BAD_INV_ORDER being thrown with a standard minor code of 14.

 | send_request | send_poll | receive_reply | receive_exception | receive_other
Inherited from RequestInfo:
request_id | yes | yes | yes | yes | yes
operation | yes | yes | yes | yes | yes
arguments | yes1 | no | yes | no | no
exceptions | yes | no | yes | yes | yes
contexts | yes | no | yes | yes | yes
operation_context | yes | no | yes | yes | yes
result | no | no | yes | no | no
response_expected | yes | yes | yes | yes | yes
sync_scope | yes | no | yes | yes | yes
reply_status | no | no | yes | yes | yes
forward_reference | no | no | no | no | yes2
get_slot | yes | yes | yes | yes | yes
get_request_service_context | yes | no | yes | yes | yes
get_reply_service_context | no | no | yes | yes | yes
ClientRequestInfo-specific:
target | yes | yes | yes | yes | yes
effective_target | yes | yes | yes | yes | yes
effective_profile | yes | yes | yes | yes | yes
received_exception | no | no | no | yes | no
received_exception_id | no | no | no | yes | no
get_effective_component | yes | no | yes | yes | yes
get_effective_components | yes | no | yes | yes | yes
get_request_policy | yes | no | yes | yes | yes
add_request_service_context | yes | no | no | no | no

  1. When ClientRequestInfo is passed to send_request, there is an entry in the list for every argument, whether in, inout, or out. But only the in and inout arguments will be available.
  2. If the reply_status atribute is not LOCATION_FORWARD, accessing this attribute will throw BAD_INV_ORDER with a standard minor code of 14.

See Also:
ClientRequestInterceptor

Method Summary
void | add_request_service_context(ServiceContext service_context, boolean replace) Allows Interceptors to add service contexts to the request.
TaggedProfile | effective_profile() Returns the profile that will be used to send the request.
Object | effective_target() Returns the actual object on which the operation will be invoked.
TaggedComponent | get_effective_component(int id) Returns the IOP.TaggedComponent with the given ID from the profile selected for this request.
TaggedComponent[] | get_effective_components(int id) Returns an array of all tagged components with the given ID from the profile selected for this request.
Policy | get_request_policy(int type) Returns the given policy in effect for this operation.
String | received_exception_id() Returns the repository id of the exception to be returned to the client.
Any | received_exception() Returns an any which contains the exception to be returned to the client.
Object | target() Returns the object which the client called to perform the operation.
Methods inherited from interface org.omg.PortableInterceptor.RequestInfoOperations
arguments, contexts, exceptions, forward_reference, get_reply_service_context, get_request_service_context, get_slot, operation_context, operation, reply_status, request_id, response_expected, result, sync_scope

Method Detail

target

Object target()
Returns the object which the client called to perform the operation.

See Also:
effective_target()

effective_target

Object effective_target()
Returns the actual object on which the operation will be invoked. If the reply_status is LOCATION_FORWARD, then on subsequent requests, effective_target will contain the forwarded IOR while target will remain unchanged.

See Also:
target()

effective_profile

TaggedProfile effective_profile()
Returns the profile that will be used to send the request. If a location forward has occurred for this operation's object and that object's profile changed accordingly, then this profile will be that located profile.

received_exception

Any received_exception()
Returns an any which contains the exception to be returned to the client.

If the exception is a user exception which cannot be inserted into an any (e.g., it is unknown or the bindings don t provide the TypeCode), then this attribute will be an any containing the system exception UNKNOWN with a standard minor code of 1. However, the repository id of the exception is available in the received_exception_id attribute.

See Also:
received_exception_id()

received_exception_id

String received_exception_id()
Returns the repository id of the exception to be returned to the client.

See Also:
received_exception(), PortableInterceptor package comments for limitations / unimplemented features

get_effective_component

TaggedComponent get_effective_component(int id)
Returns the IOP.TaggedComponent with the given ID from the profile selected for this request.

If there is more than one component for a given component ID, it is undefined which component this operation returns. If there is more than one component for a given component ID, get_effective_components should be called instead.

Parameters:
id - The component id of the component which is to be returned.
Returns:
The IOP.TaggedComponent obtained with the given identifier.
Throws:
BAD_PARAM - thrown, with a standard minor code of 28, if no component exists for the given component ID.
See Also:
get_effective_components(int)

get_effective_components

TaggedComponent[] get_effective_components(int id)
Returns an array of all tagged components with the given ID from the profile selected for this request.

Parameters:
id - The component id of the components which are to be returned.
Returns:
An array of TaggedComponent objects, each of which contains the given identifier.
Throws:
BAD_PARAM - thrown, with a standard minor code of 28, if no component exists for the given component ID.
See Also:
get_effective_component(int)

get_request_policy

Policy get_request_policy(int type)
Returns the given policy in effect for this operation.

Parameters:
type - The policy type which specifies the policy to be returned.
Returns:
The CORBA.Policy obtained with the given type.
Throws:
INV_POLICY - thrown, with a standard minor code of 1, if the policy type is not valid either because the specified type is not supported by this ORB or because a policy object of that type is not associated with this Object
See Also:
PortableInterceptor package comments for limitations / unimplemented features

add_request_service_context

void add_request_service_context(ServiceContext service_context,
                                 boolean replace)
Allows Interceptors to add service contexts to the request.

There is no declaration of the order of the service contexts. They may or may not appear in the order that they are added.

Parameters:
service_context - The IOP.ServiceContext to be added to the request.
replace - Indicates the behavior of this operation when a service context already exists with the given ID. If false, then BAD_INV_ORDER with a standard minor code of 15 is thrown. If true, then the existing service context is replaced by the new one.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ClientRequestInterceptorOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface ClientRequestInterceptorOperations

All Superinterfaces:
InterceptorOperations
All Known Subinterfaces:
ClientRequestInterceptor
public interface ClientRequestInterceptorOperations
extends InterceptorOperations

Client-side request interceptor.

A request Interceptor is designed to intercept the flow of a request/reply sequence through the ORB at specific points so that services can query the request information and manipulate the service contexts which are propagated between clients and servers. The primary use of request Interceptors is to enable ORB services to transfer context information between clients and servers. There are two types of request Interceptors: client-side and server-side.

To write a client-side Interceptor, implement the ClientRequestInterceptor interface.

See Also:
ClientRequestInfo

Method Summary
void | receive_exception(ClientRequestInfo ri) Indicates to the interceptor that an exception occurred.
void | receive_other(ClientRequestInfo ri) Allows an Interceptor to query the information available when a request results in something other than a normal reply or an exception.
void | receive_reply(ClientRequestInfo ri) Allows an Interceptor to query the information on a reply after it is returned from the server and before control is returned to the client.
void | send_poll(ClientRequestInfo ri) Allows an Interceptor to query information during a Time-Independent Invocation (TII) polling get reply sequence.
void | send_request(ClientRequestInfo ri) Allows an Interceptor to query request information and modify the service context before the request is sent to the server.
Methods inherited from interface org.omg.PortableInterceptor.InterceptorOperations
destroy, name

Method Detail

send_request

void send_request(ClientRequestInfo ri)
                  throws ForwardRequest
Allows an Interceptor to query request information and modify the service context before the request is sent to the server.

This interception point may throw a system exception. If it does, no other Interceptors' send_request operations are called. Those Interceptors on the Flow Stack are popped and their receive_exception interception points are called. This interception point may also throw a ForwardRequest exception. If an Interceptor throws this exception, no other Interceptors' send_request operations are called. Those Interceptors on the Flow Stack are popped and their receive_other interception points are called.

Compliant Interceptors shall properly follow completion_status semantics if they throw a system exception from this interception point. The completion_status shall be COMPLETED_NO.

Parameters:
ri - Information about the current request being intercepted.
Throws:
ForwardRequest - If thrown, indicates to the ORB that a retry of the request should occur with the new object given in the exception.

send_poll

void send_poll(ClientRequestInfo ri)
Allows an Interceptor to query information during a Time-Independent Invocation (TII) polling get reply sequence.

With TII, an application may poll for a response to a request sent previously by the polling client or some other client. This poll is reported to Interceptors through the send_poll interception point and the response is returned through the receive_reply or receive_exception interception points. If the response is not available before the poll time-out expires, the system exception TIMEOUT is thrown and receive_exception is called with this exception.

This interception point may throw a system exception. If it does, no other Interceptors' send_poll operations are called. Those Interceptors on the Flow Stack are popped and their receive_exception interception points are called.

Compliant Interceptors shall properly follow completion_status semantics if they throw a system exception from this interception point. The completion_status shall be COMPLETED_NO.

Parameters:
ri - Information about the current request being intercepted.
Throws:
TIMEOUT - thrown if the response is not available before the poll time-out expires

receive_reply

void receive_reply(ClientRequestInfo ri)
Allows an Interceptor to query the information on a reply after it is returned from the server and before control is returned to the client.

This interception point may throw a system exception. If it does, no other Interceptors' receive_reply operations are called. The remaining Interceptors in the Flow Stack shall have their receive_exception interception point called.

Compliant Interceptors shall properly follow completion_status semantics if they throw a system exception from this interception point. The completion_status shall be COMPLETED_YES.

Parameters:
ri - Information about the current request being intercepted.

receive_exception

void receive_exception(ClientRequestInfo ri)
                       throws ForwardRequest
Indicates to the interceptor that an exception occurred. Allows an Interceptor to query the exception's information before it is thrown to the client.

This interception point may throw a system exception. This has the effect of changing the exception which successive Interceptors popped from the Flow Stack receive on their calls to receive_exception. The exception thrown to the client will be the last exception thrown by an Interceptor, or the original exception if no Interceptor changes the exception.

This interception point may also throw a ForwardRequest exception. If an Interceptor throws this exception, no other Interceptors' receive_exception operations are called. The remaining Interceptors in the Flow Stack are popped and have their receive_other interception point called.

If the completion_status of the exception is not COMPLETED_NO, then it is inappropriate for this interception point to throw a ForwardRequest exception. The request s at-most-once semantics would be lost.

Compliant Interceptors shall properly follow completion_status semantics if they throw a system exception from this interception point. If the original exception is a system exception, the completion_status of the new exception shall be the same as on the original. If the original exception is a user exception, then the completion_status of the new exception shall be COMPLETED_YES.

Under some conditions, depending on what policies are in effect, an exception (such as COMM_FAILURE) may result in a retry of the request. While this retry is a new request with respect to Interceptors, there is one point of correlation between the original request and the retry: because control has not returned to the client, the PortableInterceptor.Current for both the original request and the retrying request is the same.

Parameters:
ri - Information about the current request being intercepted.
Throws:
ForwardRequest - If thrown, indicates to the ORB that a retry of the request should occur with the new object given in the exception.

receive_other

void receive_other(ClientRequestInfo ri)
                   throws ForwardRequest
Allows an Interceptor to query the information available when a request results in something other than a normal reply or an exception. For example, a request could result in a retry (e.g., a GIOP Reply with a LOCATION_FORWARD status was received); or on asynchronous calls, the reply does not immediately follow the request, but control shall return to the client and an ending interception point shall be called.

For retries, depending on the policies in effect, a new request may or may not follow when a retry has been indicated. If a new request does follow, while this request is a new request, with respect to Interceptors, there is one point of correlation between the original request and the retry: because control has not returned to the client, the request scoped PortableInterceptor.Current for both the original request and the retrying request is the same.

This interception point may throw a system exception. If it does, no other Interceptors' receive_other operations are called. The remaining Interceptors in the Flow Stack are popped and have their receive_exception interception point called.

This interception point may also throw a ForwardRequest exception. If an Interceptor throws this exception, successive Interceptors' receive_other operations are called with the new information provided by the ForwardRequest exception.

Compliant Interceptors shall properly follow completion_status semantics if they throw a system exception from this interception point. The completion_status shall be COMPLETED_NO. If the target invocation had completed, this interception point would not be called.

Parameters:
ri - Information about the current request being intercepted.
Throws:
ForwardRequest - If thrown, indicates to the ORB that a retry of the request should occur with the new object given in the exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CurrentHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class CurrentHelper

java.lang.Object
    extended by  org.omg.PortableInterceptor.CurrentHelper

public abstract class CurrentHelper
extends Object

Portable Interceptors Current (also known as PICurrent) is merely a slot table, the slots of which are used by each service to transfer their context data between their context and the request's or reply's service context. Each service which wishes to use PICurrent reserves a slot or slots at initialization time and uses those slots during the processing of requests and replies.

Before an invocation is made, PICurrent is obtained via a call to ORB.resolve_initial_references( "PICurrent" ). From within the interception points, the data on PICurrent that has moved from the thread scope to the request scope is available via the get_slot operation on the RequestInfo object. A PICurrent can still be obtained via resolve_initial_references, but that is the Interceptor's thread scope PICurrent.

Constructor Summary
CurrentHelper()
Method Summary
static Current | extract(Any a)
static String | id()
static void | insert(Any a, Current that)
static Current | narrow(Object obj)
static Current | read(InputStream istream)
static TypeCode | type()
static Current | unchecked_narrow(Object obj)
static void | write(OutputStream ostream, Current value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CurrentHelper

public CurrentHelper()
Method Detail

insert

public static void insert(Any a,
                          Current that)

extract

public static Current extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static Current read(InputStream istream)

write

public static void write(OutputStream ostream,
                         Current value)

narrow

public static Current narrow(Object obj)

unchecked_narrow

public static Current unchecked_narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CurrentOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface CurrentOperations

All Superinterfaces:
CurrentOperations
All Known Subinterfaces:
Current
public interface CurrentOperations
extends CurrentOperations

Portable Interceptors Current (also known as PICurrent) is merely a slot table, the slots of which are used by each service to transfer their context data between their context and the request's or reply's service context. Each service which wishes to use PICurrent reserves a slot or slots at initialization time and uses those slots during the processing of requests and replies.

Before an invocation is made, PICurrent is obtained via a call to ORB.resolve_initial_references( "PICurrent" ). From within the interception points, the data on PICurrent that has moved from the thread scope to the request scope is available via the get_slot operation on the RequestInfo object. A PICurrent can still be obtained via resolve_initial_references, but that is the Interceptor's thread scope PICurrent.

Method Summary
Any | get_slot(int id) Retrieves the slot data the application set in PICurrent via get_slot.
void | set_slot(int id, Any data) Sets data in a slot.

Method Detail

get_slot

Any get_slot(int id)
             throws InvalidSlot
Retrieves the slot data the application set in PICurrent via get_slot. The data is in the form of an Any.

If the given slot has not been set, an Any containing a type code with a TCKind value of tk_null and no value is returned.

Parameters:
id - The SlotId of the slot from which the data will be returned.
Returns:
The data, in the form of an Any, of the given slot identifier.
Throws:
InvalidSlot - thrown if get_slot is called on a slot that has not been allocated.
BAD_INV_ORDER - thrown if get_slot is called from within an ORB initializer

set_slot

void set_slot(int id,
              Any data)
              throws InvalidSlot
Sets data in a slot. The data is in the form of an Any. If data already exists in that slot, it is overridden.

Parameters:
id - The SlotId of the slot to which the data will be set.
data - The data, in the form of an Any, which will be set to the identified slot.
Throws:
InvalidSlot - thrown if set_slot is called on a slot that has not been allocated.
BAD_INV_ORDER - thrown if set_slot is called from within an ORB initializer.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DISCARDING

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface DISCARDING

public interface DISCARDING

org/omg/PortableInterceptor/DISCARDING.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:26 AM GMT-08:00

Field Summary
static short value
Object adapter state that causes all requests to be discarded.

Field Detail

value

static final short value
Object adapter state that causes all requests to be discarded.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ForwardRequest

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class ForwardRequest

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.PortableInterceptor.ForwardRequest
All Implemented Interfaces:
Serializable, IDLEntity
public final class ForwardRequest
extends UserException

org/omg/PortableInterceptor/ForwardRequest.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:25 AM GMT-08:00

Field Summary
 Object forward
The new object to forward the request to.
Constructor Summary
ForwardRequest()
ForwardRequest(Object _forward)
ForwardRequest(String $reason, Object _forward)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

forward

public Object forward
The new object to forward the request to.

Constructor Detail

ForwardRequest

public ForwardRequest()

ForwardRequest

public ForwardRequest(Object _forward)

ForwardRequest

public ForwardRequest(String $reason,
                      Object _forward)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ForwardRequestHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class ForwardRequestHelper

java.lang.Object
    extended by  org.omg.PortableInterceptor.ForwardRequestHelper

public abstract class ForwardRequestHelper
extends Object

org/omg/PortableInterceptor/ForwardRequestHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:25 AM GMT-08:00

Constructor Summary
ForwardRequestHelper()
Method Summary
static ForwardRequest | extract(Any a)
static String | id()
static void | insert(Any a, ForwardRequest that)
static ForwardRequest | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, ForwardRequest value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ForwardRequestHelper

public ForwardRequestHelper()
Method Detail

insert

public static void insert(Any a,
                          ForwardRequest that)

extract

public static ForwardRequest extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static ForwardRequest read(InputStream istream)

write

public static void write(OutputStream ostream,
                         ForwardRequest value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


HOLDING

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface HOLDING

public interface HOLDING

org/omg/PortableInterceptor/HOLDING.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:26 AM GMT-08:00

Field Summary
static short value
Object adapter state that holds requests temporarily until the state is changed.

Field Detail

value

static final short value
Object adapter state that holds requests temporarily until the state is changed.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


INACTIVE

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface INACTIVE

public interface INACTIVE

org/omg/PortableInterceptor/INACTIVE.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:26 AM GMT-08:00

Field Summary
static short value
Object adapter state that causes all requests to be discarded.

Field Detail

value

static final short value
Object adapter state that causes all requests to be discarded. This state indicates that the adapter is shutting down.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InterceptorOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface InterceptorOperations

All Known Subinterfaces:
ClientRequestInterceptor, ClientRequestInterceptorOperations, Interceptor, IORInterceptor, IORInterceptor_3_0, IORInterceptor_3_0Operations, IORInterceptorOperations, ServerRequestInterceptor, ServerRequestInterceptorOperations
public interface InterceptorOperations

All Portable Interceptors implement Interceptor.

Method Summary
void | destroy() Provides an opportunity to destroy this interceptor.
String | name() Returns the name of the interceptor.

Method Detail

name

String name()
Returns the name of the interceptor.

Each Interceptor may have a name that may be used administratively to order the lists of Interceptors. Only one Interceptor of a given name can be registered with the ORB for each Interceptor type. An Interceptor may be anonymous, i.e., have an empty string as the name attribute. Any number of anonymous Interceptors may be registered with the ORB.

Returns:
the name of the interceptor.

destroy

void destroy()
Provides an opportunity to destroy this interceptor. The destroy method is called during ORB.destroy. When an application calls ORB.destroy, the ORB:
  1. waits for all requests in progress to complete
  2. calls the Interceptor.destroy operation for each interceptor
  3. completes destruction of the ORB
Method invocations from within Interceptor.destroy on object references for objects implemented on the ORB being destroyed result in undefined behavior. However, method invocations on objects implemented on an ORB other than the one being destroyed are permitted. (This means that the ORB being destroyed is still capable of acting as a client, but not as a server.)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidSlot

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class InvalidSlot

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.PortableInterceptor.InvalidSlot
All Implemented Interfaces:
Serializable, IDLEntity
public final class InvalidSlot
extends UserException

org/omg/PortableInterceptor/InvalidSlot.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:25 AM GMT-08:00

Constructor Summary
InvalidSlot()
InvalidSlot(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidSlot

public InvalidSlot()

InvalidSlot

public InvalidSlot(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidSlotHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class InvalidSlotHelper

java.lang.Object
    extended by  org.omg.PortableInterceptor.InvalidSlotHelper

public abstract class InvalidSlotHelper
extends Object

org/omg/PortableInterceptor/InvalidSlotHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:25 AM GMT-08:00

Constructor Summary
InvalidSlotHelper()
Method Summary
static InvalidSlot | extract(Any a)
static String | id()
static void | insert(Any a, InvalidSlot that)
static InvalidSlot | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, InvalidSlot value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InvalidSlotHelper

public InvalidSlotHelper()
Method Detail

insert

public static void insert(Any a,
                          InvalidSlot that)

extract

public static InvalidSlot extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static InvalidSlot read(InputStream istream)

write

public static void write(OutputStream ostream,
                         InvalidSlot value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IORInfoOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface IORInfoOperations

All Known Subinterfaces:
IORInfo
public interface IORInfoOperations

Provides the server-side ORB service with access to the applicable policies during IOR construction and the ability to add components. The ORB passes an instance of its implementation of this interface as a parameter to IORInterceptor.establish_components.

See Also:
IORInterceptor

Method Summary
ObjectReferenceTemplate | adapter_template() Return the object reference template of the object adapter that was just created and is running IOR interceptors.
void | add_ior_component_to_profile(TaggedComponent tagged_component, int profile_id) A portable ORB service implementation calls add_ior_component_to_profile from its implementation of establish_components to add a tagged component to the set which will be included when constructing IORs.
void | add_ior_component(TaggedComponent tagged_component) A portable ORB service implementation calls add_ior_component from its implementation of establish_components to add a tagged component to the set which will be included when constructing IORs.
ObjectReferenceFactory | current_factory() On read, returns the current factory that will be used to create object references for the object adapter that was just created and is running IOR interceptors.
void | current_factory(ObjectReferenceFactory newCurrent_factory) On read, returns the current factory that will be used to create object references for the object adapter that was just created and is running IOR interceptors.
Policy | get_effective_policy(int type) Allows an ORB service implementation to determine what server side policy of a particular type is in effect for an IOR being constructed.
int | manager_id() Return the adapter manager id of the object adapter that was just created and is running IOR interceptors.
short | state() Return the adapter state of the object adapter that was just created and is running IOR interceptors.

Method Detail

get_effective_policy

Policy get_effective_policy(int type)
Allows an ORB service implementation to determine what server side policy of a particular type is in effect for an IOR being constructed. When the IOR being constructed is for an object implemented using a POA, all Policy objects passed to the PortableServer.POA.create_POA call that created that POA are accessable via get_effective_policy.

If a policy for the given type is not known to the ORB, then this operation will throw INV_POLICY with a standard minor code of 2.

Parameters:
type - an int specifying the type of policy to return.
Returns:
The effective CORBA.Policy object of the requested type. If the given policy type is known, but no policy of that type is in effect, then this operation will return a nil object reference.

add_ior_component

void add_ior_component(TaggedComponent tagged_component)
A portable ORB service implementation calls add_ior_component from its implementation of establish_components to add a tagged component to the set which will be included when constructing IORs. The components in this set will be included in all profiles.

Any number of components may exist with the same component ID.

Parameters:
a_component - The IOP.TaggedComponent to add.

add_ior_component_to_profile

void add_ior_component_to_profile(TaggedComponent tagged_component,
                                  int profile_id)
A portable ORB service implementation calls add_ior_component_to_profile from its implementation of establish_components to add a tagged component to the set which will be included when constructing IORs. The components in this set will be included in the specified profile.

Any number of components may exist with the same component ID.

Parameters:
a_component - The IOP.TaggedComponent to add.
profile_id - The profile id of the profile to which this component will be added.
Throws:
BAD_PARAM - thrown, with a standard minor code of 29, if the given profile ID does not define a known profile or it is impossible to add components to that profile.

manager_id

int manager_id()
Return the adapter manager id of the object adapter that was just created and is running IOR interceptors.

state

short state()
Return the adapter state of the object adapter that was just created and is running IOR interceptors.

adapter_template

ObjectReferenceTemplate adapter_template()
Return the object reference template of the object adapter that was just created and is running IOR interceptors.

current_factory

ObjectReferenceFactory current_factory()
On read, returns the current factory that will be used to create object references for the object adapter that was just created and is running IOR interceptors. By default, this factory is the same as the value of the adapter_template attribute. The current_factory may also be set to another object reference template inside an IORInterceptor_3_0.

current_factory

void current_factory(ObjectReferenceFactory newCurrent_factory)
On read, returns the current factory that will be used to create object references for the object adapter that was just created and is running IOR interceptors. By default, this factory is the same as the value of the adapter_template attribute. The current_factory may also be set to another object reference template inside an IORInterceptor_3_0.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IORInterceptorOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface IORInterceptorOperations

All Superinterfaces:
InterceptorOperations
All Known Subinterfaces:
IORInterceptor, IORInterceptor_3_0, IORInterceptor_3_0Operations
public interface IORInterceptorOperations
extends InterceptorOperations

Interceptor used to establish tagged components in the profiles within an IOR.

In some cases, a portable ORB service implementation may need to add information describing the server's or object's ORB service related capabilities to object references in order to enable the ORB service implementation in the client to function properly.

This is supported through the IORInterceptor and IORInfo interfaces.

See Also:
IORInfo

Method Summary
 void establish_components(IORInfo info)
A server side ORB calls the establish_components operation on all registered IORInterceptor instances when it is assembling the list of components that will be included in the profile or profiles of an object reference.
Methods inherited from interface org.omg.PortableInterceptor.InterceptorOperations
destroy, name

Method Detail

establish_components

void establish_components(IORInfo info)
A server side ORB calls the establish_components operation on all registered IORInterceptor instances when it is assembling the list of components that will be included in the profile or profiles of an object reference. This operation is not necessarily called for each individual object reference. In the case of the POA, this operation is called each time POA::create_POA is called. In any case, establish_components is guaranteed to be called at least once for each distinct set of server policies.

An implementation of establish_components must not throw exceptions. If it does, the ORB shall ignore the exception and proceed to call the next IOR Interceptor's establish_components operation.

Parameters:
info - The IORInfo instance used by the ORB service to query applicable policies and add components to be included in the generated IORs.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IORInterceptor_3_0Helper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class IORInterceptor_3_0Helper

java.lang.Object
    extended by  org.omg.PortableInterceptor.IORInterceptor_3_0Helper

public abstract class IORInterceptor_3_0Helper
extends Object

org/omg/PortableInterceptor/IORInterceptor_3_0Helper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:26 AM GMT-08:00

Constructor Summary
IORInterceptor_3_0Helper()
Method Summary
static IORInterceptor_3_0 | extract(Any a)
static String | id()
static void | insert(Any a, IORInterceptor_3_0 that)
static IORInterceptor_3_0 | narrow(Object obj)
static IORInterceptor_3_0 | read(InputStream istream)
static TypeCode | type()
static IORInterceptor_3_0 | unchecked_narrow(Object obj)
static void | write(OutputStream ostream, IORInterceptor_3_0 value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IORInterceptor_3_0Helper

public IORInterceptor_3_0Helper()
Method Detail

insert

public static void insert(Any a,
                          IORInterceptor_3_0 that)

extract

public static IORInterceptor_3_0 extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static IORInterceptor_3_0 read(InputStream istream)

write

public static void write(OutputStream ostream,
                         IORInterceptor_3_0 value)

narrow

public static IORInterceptor_3_0 narrow(Object obj)

unchecked_narrow

public static IORInterceptor_3_0 unchecked_narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IORInterceptor_3_0Holder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class IORInterceptor_3_0Holder

java.lang.Object
    extended by  org.omg.PortableInterceptor.IORInterceptor_3_0Holder
All Implemented Interfaces:
Streamable
public final class IORInterceptor_3_0Holder
extends Object
implements Streamable

org/omg/PortableInterceptor/IORInterceptor_3_0Holder.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:26 AM GMT-08:00

Field Summary
 IORInterceptor_3_0 value
Constructor Summary
IORInterceptor_3_0Holder()
IORInterceptor_3_0Holder(IORInterceptor_3_0 initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public IORInterceptor_3_0 value
Constructor Detail

IORInterceptor_3_0Holder

public IORInterceptor_3_0Holder()

IORInterceptor_3_0Holder

public IORInterceptor_3_0Holder(IORInterceptor_3_0 initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IORInterceptor_3_0Operations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface IORInterceptor_3_0Operations

All Superinterfaces:
InterceptorOperations, IORInterceptorOperations
All Known Subinterfaces:
IORInterceptor_3_0
public interface IORInterceptor_3_0Operations
extends IORInterceptorOperations

org/omg/PortableInterceptor/IORInterceptor_3_0Operations.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:26 AM GMT-08:00

Method Summary
void | adapter_manager_state_changed(int id, short state) Called whenever the state of an adapter manager changes.
void | adapter_state_changed(ObjectReferenceTemplate[] templates, short state) Called whenever the state of an object adapter changes, and the state change is not caused by an adapter manager.
void | components_established(IORInfo info) The components_established method is invoked on all registered IORInterceptor_3_0 instances after establish_components has been invoked on all registered IORInterceptor instances.
Methods inherited from interface org.omg.PortableInterceptor.IORInterceptorOperations
establish_components
Methods inherited from interface org.omg.PortableInterceptor.InterceptorOperations
destroy, name

Method Detail

components_established

void components_established(IORInfo info)
The components_established method is invoked on all registered IORInterceptor_3_0 instances after establish_components has been invoked on all registered IORInterceptor instances. The adapter_template is available in info during this call. The current_factory may be get or set in info during this call.

Any exception thrown from this method is handled by the Object Adapter that called this interceptor. In the case of the POA, an exception results in a OBJ_ADAPTER exception with an OMG standard minor code of 6.

Parameters:
info - The IORInfo for the object adapter being created.

adapter_manager_state_changed

void adapter_manager_state_changed(int id,
                                   short state)
Called whenever the state of an adapter manager changes. For the POA, that is the POAManager. If the state change is reported through adapter_manager_state_changed, it is not reported through adapter_state_changed.

Parameters:
id - the adapter manager id of the adapter manager that changed state
state - the new state of the adapter manager

adapter_state_changed

void adapter_state_changed(ObjectReferenceTemplate[] templates,
                           short state)
Called whenever the state of an object adapter changes, and the state change is not caused by an adapter manager. Such changes are reported to all registered IORInterceptor_3_0 instances.

Parameters:
templates - the sequence of ObjectReferenceTemplate instances on which this state change occurred.
state - the new AdapterState shared by all of the templates.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LOCATION_FORWARD

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface LOCATION_FORWARD

public interface LOCATION_FORWARD

org/omg/PortableInterceptor/LOCATION_FORWARD.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:25 AM GMT-08:00

Field Summary
static short value
Indicates a LocationForward reply status.

Field Detail

value

static final short value
Indicates a LocationForward reply status. One possible value for RequestInfo.reply_status.

See Also:
RequestInfoOperations.reply_status(), SUCCESSFUL, SYSTEM_EXCEPTION, USER_EXCEPTION, TRANSPORT_RETRY, Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NON_EXISTENT

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface NON_EXISTENT

public interface NON_EXISTENT

org/omg/PortableInterceptor/NON_EXISTENT.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:26 AM GMT-08:00

Field Summary
static short value
Object adapter state indicating that the adapter has been destroyed.

Field Detail

value

static final short value
Object adapter state indicating that the adapter has been destroyed.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectIdHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class ObjectIdHelper

java.lang.Object
    extended by  org.omg.PortableInterceptor.ObjectIdHelper

public abstract class ObjectIdHelper
extends Object

Type of an object id. This provides the identity of a particular object that was created by an object adapter.

Constructor Summary
ObjectIdHelper()
Method Summary
static byte[] | extract(Any a)
static String | id()
static void | insert(Any a, byte[] that)
static byte[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, byte[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ObjectIdHelper

public ObjectIdHelper()
Method Detail

insert

public static void insert(Any a,
                          byte[] that)

extract

public static byte[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static byte[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         byte[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectReferenceFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface ObjectReferenceFactory

All Superinterfaces:
IDLEntity, Serializable, ValueBase
All Known Subinterfaces:
ObjectReferenceTemplate
public interface ObjectReferenceFactory
extends ValueBase

The object reference factory. This provides the capability of creating an object reference.

Method Summary
 Object make_object(String repositoryId, byte[] object_id)
make_object creates a CORBA object reference according to the data in this template, with the given repository ID and object ID.
Methods inherited from interface org.omg.CORBA.portable.ValueBase
_truncatable_ids

Method Detail

make_object

Object make_object(String repositoryId,
                   byte[] object_id)
make_object creates a CORBA object reference according to the data in this template, with the given repository ID and object ID.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectReferenceFactoryHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class ObjectReferenceFactoryHelper

java.lang.Object
    extended by  org.omg.PortableInterceptor.ObjectReferenceFactoryHelper

public abstract class ObjectReferenceFactoryHelper
extends Object

The object reference factory. This provides the capability of creating an object reference.

Constructor Summary
ObjectReferenceFactoryHelper()
Method Summary
static ObjectReferenceFactory | extract(Any a)
static String | id()
static void | insert(Any a, ObjectReferenceFactory that)
static ObjectReferenceFactory | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, ObjectReferenceFactory value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ObjectReferenceFactoryHelper

public ObjectReferenceFactoryHelper()
Method Detail

insert

public static void insert(Any a,
                          ObjectReferenceFactory that)

extract

public static ObjectReferenceFactory extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static ObjectReferenceFactory read(InputStream istream)

write

public static void write(OutputStream ostream,
                         ObjectReferenceFactory value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectReferenceFactoryHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class ObjectReferenceFactoryHolder

java.lang.Object
    extended by  org.omg.PortableInterceptor.ObjectReferenceFactoryHolder
All Implemented Interfaces:
Streamable
public final class ObjectReferenceFactoryHolder
extends Object
implements Streamable

The object reference factory. This provides the capability of creating an object reference.

Field Summary
 ObjectReferenceFactory value
Constructor Summary
ObjectReferenceFactoryHolder()
ObjectReferenceFactoryHolder(ObjectReferenceFactory initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public ObjectReferenceFactory value
Constructor Detail

ObjectReferenceFactoryHolder

public ObjectReferenceFactoryHolder()

ObjectReferenceFactoryHolder

public ObjectReferenceFactoryHolder(ObjectReferenceFactory initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectReferenceTemplate

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface ObjectReferenceTemplate

All Superinterfaces:
IDLEntity, ObjectReferenceFactory, Serializable, ValueBase
public interface ObjectReferenceTemplate
extends ObjectReferenceFactory

The object reference template. An instance of this must exist for each object adapter created in an ORB. The server_id, orb_id, and adapter_name attributes uniquely identify this template within the scope of an IMR. Note that adapter_id is similarly unique within the same scope, but it is opaque, and less useful in many cases.

Method Summary
String[] | adapter_name()
String | orb_id()
String | server_id()
Methods inherited from interface org.omg.PortableInterceptor.ObjectReferenceFactory
make_object
Methods inherited from interface org.omg.CORBA.portable.ValueBase
_truncatable_ids

Method Detail

server_id

String server_id()

orb_id

String orb_id()

adapter_name

String[] adapter_name()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectReferenceTemplateHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class ObjectReferenceTemplateHelper

java.lang.Object
    extended by  org.omg.PortableInterceptor.ObjectReferenceTemplateHelper

public abstract class ObjectReferenceTemplateHelper
extends Object

The object reference template. An instance of this must exist for each object adapter created in an ORB. The server_id, orb_id, and adapter_name attributes uniquely identify this template within the scope of an IMR. Note that adapter_id is similarly unique within the same scope, but it is opaque, and less useful in many cases.

Constructor Summary
ObjectReferenceTemplateHelper()
Method Summary
static ObjectReferenceTemplate | extract(Any a)
static String | id()
static void | insert(Any a, ObjectReferenceTemplate that)
static ObjectReferenceTemplate | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, ObjectReferenceTemplate value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ObjectReferenceTemplateHelper

public ObjectReferenceTemplateHelper()
Method Detail

insert

public static void insert(Any a,
                          ObjectReferenceTemplate that)

extract

public static ObjectReferenceTemplate extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static ObjectReferenceTemplate read(InputStream istream)

write

public static void write(OutputStream ostream,
                         ObjectReferenceTemplate value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectReferenceTemplateHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class ObjectReferenceTemplateHolder

java.lang.Object
    extended by  org.omg.PortableInterceptor.ObjectReferenceTemplateHolder
All Implemented Interfaces:
Streamable
public final class ObjectReferenceTemplateHolder
extends Object
implements Streamable

The object reference template. An instance of this must exist for each object adapter created in an ORB. The server_id, orb_id, and adapter_name attributes uniquely identify this template within the scope of an IMR. Note that adapter_id is similarly unique within the same scope, but it is opaque, and less useful in many cases.

Field Summary
 ObjectReferenceTemplate value
Constructor Summary
ObjectReferenceTemplateHolder()
ObjectReferenceTemplateHolder(ObjectReferenceTemplate initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public ObjectReferenceTemplate value
Constructor Detail

ObjectReferenceTemplateHolder

public ObjectReferenceTemplateHolder()

ObjectReferenceTemplateHolder

public ObjectReferenceTemplateHolder(ObjectReferenceTemplate initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectReferenceTemplateSeqHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class ObjectReferenceTemplateSeqHelper

java.lang.Object
    extended by  org.omg.PortableInterceptor.ObjectReferenceTemplateSeqHelper

public abstract class ObjectReferenceTemplateSeqHelper
extends Object

Sequence of object reference templates is used for reporting state changes that do not occur on the adapter manager.

Constructor Summary
ObjectReferenceTemplateSeqHelper()
Method Summary
static ObjectReferenceTemplate[] | extract(Any a)
static String | id()
static void | insert(Any a, ObjectReferenceTemplate[] that)
static ObjectReferenceTemplate[] | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, ObjectReferenceTemplate[] value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ObjectReferenceTemplateSeqHelper

public ObjectReferenceTemplateSeqHelper()
Method Detail

insert

public static void insert(Any a,
                          ObjectReferenceTemplate[] that)

extract

public static ObjectReferenceTemplate[] extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static ObjectReferenceTemplate[] read(InputStream istream)

write

public static void write(OutputStream ostream,
                         ObjectReferenceTemplate[] value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectReferenceTemplateSeqHolder

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class ObjectReferenceTemplateSeqHolder

java.lang.Object
    extended by  org.omg.PortableInterceptor.ObjectReferenceTemplateSeqHolder
All Implemented Interfaces:
Streamable
public final class ObjectReferenceTemplateSeqHolder
extends Object
implements Streamable

Sequence of object reference templates is used for reporting state changes that do not occur on the adapter manager.

Field Summary
 ObjectReferenceTemplate[] value
Constructor Summary
ObjectReferenceTemplateSeqHolder()
ObjectReferenceTemplateSeqHolder(ObjectReferenceTemplate[] initialValue)
Method Summary
void | _read(InputStream i) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream o) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public ObjectReferenceTemplate[] value
Constructor Detail

ObjectReferenceTemplateSeqHolder

public ObjectReferenceTemplateSeqHolder()

ObjectReferenceTemplateSeqHolder

public ObjectReferenceTemplateSeqHolder(ObjectReferenceTemplate[] initialValue)
Method Detail

_read

public void _read(InputStream i)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
i - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream o)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
o - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ORBIdHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class ORBIdHelper

java.lang.Object
    extended by  org.omg.PortableInterceptor.ORBIdHelper

public abstract class ORBIdHelper
extends Object

org/omg/PortableInterceptor/ORBIdHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:25 AM GMT-08:00

Constructor Summary
ORBIdHelper()
Method Summary
static String | extract(Any a)
static String | id()
static void | insert(Any a, String that)
static String | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, String value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ORBIdHelper

public ORBIdHelper()
Method Detail

insert

public static void insert(Any a,
                          String that)

extract

public static String extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static String read(InputStream istream)

write

public static void write(OutputStream ostream,
                         String value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ORBInitializerOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface ORBInitializerOperations

All Known Subinterfaces:
ORBInitializer
public interface ORBInitializerOperations

Facilitates interceptor registration and ORB initialization.

Interceptors are intended to be a means by which ORB services gain access to ORB processing, effectively becoming part of the ORB. Since Interceptors are part of the ORB, when ORB.init returns an ORB, the Interceptors shall have been registered. Interceptors cannot be registered on an ORB after it has been returned by a call to ORB.init.

An Interceptor is registered by registering an associated ORBInitializer object which implements the ORBInitializer interface. When an ORB is initializing, it shall call each registered ORBInitializer, passing it an ORBInitInfo object which is used to register its Interceptor.

Registering ORB Initializers in Java

ORBInitializers are registered via Java ORB properties.

The property names are of the form:

org.omg.PortableInterceptor.ORBInitializerClass.<Service>
where <Service> is the string name of a class which implements
org.omg.PortableInterceptor.ORBInitializer
To avoid name collisions, the reverse DNS name convention should be used. For example, if company X has three initializers, it could define the following properties:
  • org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init1
  • org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init2
  • org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init3
During ORB.init, these ORB properties which begin with org.omg.PortableInterceptor.ORBInitializerClass shall be collected, the <Service> portion of each property shall be extracted, an object shall be instantiated with the <Service> string as its class name, and the pre_init and post_init methods shall be called on that object. If there are any exceptions, the ORB shall ignore them and proceed.

Example

A client-side logging service written by company X, for example, may have the following ORBInitializer implementation:

 package com.x.logging;

 import org.omg.PortableInterceptor.Interceptor;
 import org.omg.PortableInterceptor.ORBInitializer;
 import org.omg.PortableInterceptor.ORBInitInfo;

 public class LoggingService implements ORBInitializer {
     void pre_init( ORBInitInfo info ) {
         // Instantiate the Logging Service s Interceptor.
         Interceptor interceptor = new LoggingInterceptor();

         // Register the Logging Service s Interceptor.
         info.add_client_request_interceptor( interceptor );
     }

     void post_init( ORBInitInfo info ) {
         // This service does not need two init points.
     }
 }
To run a program called MyApp using this logging service, the user could type:
java -Dorg.omg.PortableInterceptor.ORBInitializerClass.com.x.Logging.LoggingService MyApp

Notes about Registering Interceptors

Request Interceptors are registered on a per-ORB basis.

To achieve virtual per-object Interceptors, query the policies on the target from within the interception points to determine whether they should do any work.

To achieve virtual per-POA Interceptors, instantiate each POA with a different ORB. While Interceptors may be ordered administratively, there is no concept of order with respect to the registration of Interceptors. Request Interceptors are concerned with service contexts. Service contexts have no order, so there is no purpose for request Interceptors to have an order. IOR Interceptors are concerned with tagged components. Tagged components also have no order, so there is no purpose for IOR Interceptors to have an order.

Registration code should avoid using the ORB (i.e., calling ORB.init with the provided orb_id). Since registration occurs during ORB initialization, results of invocations on this ORB while it is in this state are undefined.

See Also:
ORBInitInfo

Method Summary
void | post_init(ORBInitInfo info) Called during ORB initialization.
void | pre_init(ORBInitInfo info) Called during ORB initialization.

Method Detail

pre_init

void pre_init(ORBInitInfo info)
Called during ORB initialization. If it is expected that initial services registered by an interceptor will be used by other interceptors, then those initial services shall be registered at this point via calls to ORBInitInfo.register_initial_reference.

Parameters:
info - provides initialization attributes and operations by which Interceptors can be registered.

post_init

void post_init(ORBInitInfo info)
Called during ORB initialization. If a service must resolve initial references as part of its initialization, it can assume that all initial references will be available at this point.

Calling the post_init operations is not the final task of ORB initialization. The final task, following the post_init calls, is attaching the lists of registered interceptors to the ORB. Therefore, the ORB does not contain the interceptors during calls to post_init. If an ORB-mediated call is made from within post_init, no request interceptors will be invoked on that call. Likewise, if an operation is performed which causes an IOR to be created, no IOR interceptors will be invoked.

Parameters:
info - provides initialization attributes and operations by which Interceptors can be registered.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ORBInitInfoOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface ORBInitInfoOperations

All Known Subinterfaces:
ORBInitInfo
public interface ORBInitInfoOperations

Passed to each ORBInitializer, allowing it to to register interceptors and perform other duties while the ORB is initializing.

The ORBInitInfo object is only valid during ORB.init. If a service keeps a reference to its ORBInitInfo object and tries to use it after ORB.init returns, the object no longer exists and an OBJECT_NOT_EXIST exception shall be thrown.

See Also:
ORBInitializer

Method Summary
void | add_client_request_interceptor(ClientRequestInterceptor interceptor) Used to add a client-side request Interceptor to the list of client-side request Interceptors.
void | add_ior_interceptor(IORInterceptor interceptor) Used to add an IOR Interceptor to the list of IOR Interceptors.
void | add_server_request_interceptor(ServerRequestInterceptor interceptor) Used to add a server-side request Interceptor to the list of server-side request Interceptors.
int | allocate_slot_id() Called to allocate a slot on PortableInterceptor.Current.
String[] | arguments() Returns the arguments passed to ORB.init.
CodecFactory | codec_factory() Returns the IOP.CodecFactory.
String | orb_id() Returns the ID of the ORB being initialized.
void | register_initial_reference(String id, Object obj) Identical to ORB.register_initial_reference.
void | register_policy_factory(int type, PolicyFactory policy_factory) Registers a PolicyFactory for the given PolicyType.
Object | resolve_initial_references(String id) Identical to ORB.resolve_initial_references.

Method Detail

arguments

String[] arguments()
Returns the arguments passed to ORB.init. They may or may not contain the ORB's arguments.

orb_id

String orb_id()
Returns the ID of the ORB being initialized.

codec_factory

CodecFactory codec_factory()
Returns the IOP.CodecFactory. The CodecFactory is normally obtained via a call to ORB.resolve_initial_references( "CodecFactory" ), but since the ORB is not yet available and Interceptors, particularly when processing service contexts, will require a Codec, a means of obtaining a Codec is necessary during ORB initialization.

register_initial_reference

void register_initial_reference(String id,
                                Object obj)
                                throws InvalidName
Identical to ORB.register_initial_reference. This same functionality exists here because the ORB, not yet fully initialized, is not yet available but initial references may need to be registered as part of Interceptor registration. The only difference is that the version of this operation on the ORB uses PIDL (CORBA.ORB.ObjectId) and (CORBA.ORB.InvalidName) whereas the version in this interface uses IDL defined in this interface; the semantics are identical.

Throws:
InvalidName

resolve_initial_references

Object resolve_initial_references(String id)
                                  throws InvalidName
Identical to ORB.resolve_initial_references. This same functionality exists here because the ORB, not yet fully initialized, is not yet available but initial references may be required from the ORB as part of Interceptor registration. The only difference is that the version of this operation on the ORB uses PIDL (CORBA::ORB::ObjectId and CORBA::ORB::InvalidName) whereas the version in this interface uses IDL defined in this interface; the semantics are identical.

This operation is only valid during post_init.

Throws:
InvalidName

add_client_request_interceptor

void add_client_request_interceptor(ClientRequestInterceptor interceptor)
                                    throws DuplicateName
Used to add a client-side request Interceptor to the list of client-side request Interceptors.

Parameters:
interceptor - The ClientRequestInterceptor to be added.
Throws:
DuplicateName - thrown if a client-side request Interceptor has already been registered with this Interceptor's name.

add_server_request_interceptor

void add_server_request_interceptor(ServerRequestInterceptor interceptor)
                                    throws DuplicateName
Used to add a server-side request Interceptor to the list of server-side request Interceptors.

Parameters:
interceptor - The ServerRequestInterceptor to be added.
Throws:
DuplicateName - thrown if a server-side request Interceptor has already been registered with this Interceptor's name

add_ior_interceptor

void add_ior_interceptor(IORInterceptor interceptor)
                         throws DuplicateName
Used to add an IOR Interceptor to the list of IOR Interceptors.

Parameters:
interceptor - The IORInterceptor to be added.
Throws:
DuplicateName - thrown if an IOR Interceptor has already been registered with this Interceptor's name.

allocate_slot_id

int allocate_slot_id()
Called to allocate a slot on PortableInterceptor.Current.

Note that while slot id's can be allocated within an ORB initializer, the slots themselves cannot be initialized.

Returns:
The index to the slot which has been allocated.
Throws:
BAD_INV_ORDER - thrown, with a standard minor code of 14, if set_slot or get_slot is called on the PICurrent within an ORB initializer.
See Also:
Current

register_policy_factory

void register_policy_factory(int type,
                             PolicyFactory policy_factory)
Registers a PolicyFactory for the given PolicyType.

Parameters:
type - The policy type that the given PolicyFactory serves.
policy_factory - The factory for the given policy type.
Throws:
BAD_INV_ORDER - thrown, with a standard minor code of 16, if a PolicyFactory already exists for the given PolicyType.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ORBInitInfoPackage

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.PortableInterceptor.ORBInitInfoPackage

This package contains the exceptions and typedefs from the ORBInitInfo local interface of the PortableInterceptor module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.7.2.

See:
Description

Class Summary
DuplicateNameHelper | org/omg/PortableInterceptor/ORBInitInfoPackage/DuplicateNameHelper.java .
InvalidNameHelper | org/omg/PortableInterceptor/ORBInitInfoPackage/InvalidNameHelper.java .
ObjectIdHelper | Object id, represented as a String

Exception Summary
DuplicateName | org/omg/PortableInterceptor/ORBInitInfoPackage/DuplicateName.java .
InvalidName | org/omg/PortableInterceptor/ORBInitInfoPackage/InvalidName.java .

Package org.omg.PortableInterceptor.ORBInitInfoPackage Description

This package contains the exceptions and typedefs from the ORBInitInfo local interface of the PortableInterceptor module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.7.2. Please refer to that OMG specification for further details.

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6 ORB complies, see Official Specifications for CORBA support in Java SE 6.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.PortableInterceptor.ORBInitInfoPackage Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.PortableInterceptor.ORBInitInfoPackage

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.PortableInterceptor.ORBInitInfoPackage.DuplicateNameHelper
    • org.omg.PortableInterceptor.ORBInitInfoPackage.InvalidNameHelper
    • org.omg.PortableInterceptor.ORBInitInfoPackage.ObjectIdHelper
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.omg.CORBA.UserException (implements org.omg.CORBA.portable.IDLEntity)
          • org.omg.PortableInterceptor.ORBInitInfoPackage.DuplicateName
          • org.omg.PortableInterceptor.ORBInitInfoPackage.InvalidName
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.PortableInterceptor.ORBInitInfoPackage

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.PortableInterceptor.ORBInitInfoPackage

Packages that use org.omg.PortableInterceptor.ORBInitInfoPackage
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.
org.omg.PortableInterceptor.ORBInitInfoPackage | This package contains the exceptions and typedefs from the ORBInitInfo local interface of the PortableInterceptor module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.7.2.

Classes in org.omg.PortableInterceptor.ORBInitInfoPackage used by org.omg.PortableInterceptor
DuplicateName
org/omg/PortableInterceptor/ORBInitInfoPackage/DuplicateName.java .
InvalidName
org/omg/PortableInterceptor/ORBInitInfoPackage/InvalidName.java .

Classes in org.omg.PortableInterceptor.ORBInitInfoPackage used by org.omg.PortableInterceptor.ORBInitInfoPackage
DuplicateName
org/omg/PortableInterceptor/ORBInitInfoPackage/DuplicateName.java .
InvalidName
org/omg/PortableInterceptor/ORBInitInfoPackage/InvalidName.java .

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.ORBInitInfoPackage.DuplicateName

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.ORBInitInfoPackage.DuplicateName

Packages that use DuplicateName
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.
org.omg.PortableInterceptor.ORBInitInfoPackage | This package contains the exceptions and typedefs from the ORBInitInfo local interface of the PortableInterceptor module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.7.2.

Uses of DuplicateName in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor that throw DuplicateName
void | ORBInitInfoOperations.add_client_request_interceptor(ClientRequestInterceptor interceptor) Used to add a client-side request Interceptor to the list of client-side request Interceptors.
void | ORBInitInfoOperations.add_ior_interceptor(IORInterceptor interceptor) Used to add an IOR Interceptor to the list of IOR Interceptors.
void | ORBInitInfoOperations.add_server_request_interceptor(ServerRequestInterceptor interceptor) Used to add a server-side request Interceptor to the list of server-side request Interceptors.

Uses of DuplicateName in org.omg.PortableInterceptor.ORBInitInfoPackage

Methods in org.omg.PortableInterceptor.ORBInitInfoPackage that return DuplicateName
static DuplicateName | DuplicateNameHelper.extract(Any a)
static DuplicateName | DuplicateNameHelper.read(InputStream istream)

Methods in org.omg.PortableInterceptor.ORBInitInfoPackage with parameters of type DuplicateName
static void | DuplicateNameHelper.insert(Any a, DuplicateName that)
static void | DuplicateNameHelper.write(OutputStream ostream, DuplicateName value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.ORBInitInfoPackage.DuplicateNameHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.ORBInitInfoPackage.DuplicateNameHelper

No usage of org.omg.PortableInterceptor.ORBInitInfoPackage.DuplicateNameHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.ORBInitInfoPackage.InvalidName

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.ORBInitInfoPackage.InvalidName

Packages that use InvalidName
org.omg.PortableInterceptor | Provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB.
org.omg.PortableInterceptor.ORBInitInfoPackage | This package contains the exceptions and typedefs from the ORBInitInfo local interface of the PortableInterceptor module specified in the OMG Portable Interceptor specification, http://cgi.omg.org/cgi-bin/doc?ptc/2000-08-06, section 21.7.2.

Uses of InvalidName in org.omg.PortableInterceptor

Methods in org.omg.PortableInterceptor that throw InvalidName
void | ORBInitInfoOperations.register_initial_reference(String id, Object obj) Identical to ORB.register_initial_reference.
Object | ORBInitInfoOperations.resolve_initial_references(String id) Identical to ORB.resolve_initial_references.

Uses of InvalidName in org.omg.PortableInterceptor.ORBInitInfoPackage

Methods in org.omg.PortableInterceptor.ORBInitInfoPackage that return InvalidName
static InvalidName | InvalidNameHelper.extract(Any a)
static InvalidName | InvalidNameHelper.read(InputStream istream)

Methods in org.omg.PortableInterceptor.ORBInitInfoPackage with parameters of type InvalidName
static void | InvalidNameHelper.insert(Any a, InvalidName that)
static void | InvalidNameHelper.write(OutputStream ostream, InvalidName value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.ORBInitInfoPackage.InvalidNameHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.ORBInitInfoPackage.InvalidNameHelper

No usage of org.omg.PortableInterceptor.ORBInitInfoPackage.InvalidNameHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableInterceptor.ORBInitInfoPackage.ObjectIdHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableInterceptor.ORBInitInfoPackage.ObjectIdHelper

No usage of org.omg.PortableInterceptor.ORBInitInfoPackage.ObjectIdHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DuplicateName

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor.ORBInitInfoPackage
Class DuplicateName

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.PortableInterceptor.ORBInitInfoPackage.DuplicateName
All Implemented Interfaces:
Serializable, IDLEntity
public final class DuplicateName
extends UserException

org/omg/PortableInterceptor/ORBInitInfoPackage/DuplicateName.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:26 AM GMT-08:00

Field Summary
 String name
The name for which there was already an interceptor registered.
Constructor Summary
DuplicateName()
DuplicateName(String _name)
DuplicateName(String $reason, String _name)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

name

public String name
The name for which there was already an interceptor registered.

Constructor Detail

DuplicateName

public DuplicateName()

DuplicateName

public DuplicateName(String _name)

DuplicateName

public DuplicateName(String $reason,
                     String _name)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


DuplicateNameHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor.ORBInitInfoPackage
Class DuplicateNameHelper

java.lang.Object
    extended by  org.omg.PortableInterceptor.ORBInitInfoPackage.DuplicateNameHelper

public abstract class DuplicateNameHelper
extends Object

org/omg/PortableInterceptor/ORBInitInfoPackage/DuplicateNameHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:26 AM GMT-08:00

Constructor Summary
DuplicateNameHelper()
Method Summary
static DuplicateName | extract(Any a)
static String | id()
static void | insert(Any a, DuplicateName that)
static DuplicateName | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, DuplicateName value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DuplicateNameHelper

public DuplicateNameHelper()
Method Detail

insert

public static void insert(Any a,
                          DuplicateName that)

extract

public static DuplicateName extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static DuplicateName read(InputStream istream)

write

public static void write(OutputStream ostream,
                         DuplicateName value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidName

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor.ORBInitInfoPackage
Class InvalidName

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.PortableInterceptor.ORBInitInfoPackage.InvalidName
All Implemented Interfaces:
Serializable, IDLEntity
public final class InvalidName
extends UserException

org/omg/PortableInterceptor/ORBInitInfoPackage/InvalidName.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:26 AM GMT-08:00

Constructor Summary
InvalidName()
InvalidName(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidName

public InvalidName()

InvalidName

public InvalidName(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidNameHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor.ORBInitInfoPackage
Class InvalidNameHelper

java.lang.Object
    extended by  org.omg.PortableInterceptor.ORBInitInfoPackage.InvalidNameHelper

public abstract class InvalidNameHelper
extends Object

org/omg/PortableInterceptor/ORBInitInfoPackage/InvalidNameHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:26 AM GMT-08:00

Constructor Summary
InvalidNameHelper()
Method Summary
static InvalidName | extract(Any a)
static String | id()
static void | insert(Any a, InvalidName that)
static InvalidName | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, InvalidName value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InvalidNameHelper

public InvalidNameHelper()
Method Detail

insert

public static void insert(Any a,
                          InvalidName that)

extract

public static InvalidName extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static InvalidName read(InputStream istream)

write

public static void write(OutputStream ostream,
                         InvalidName value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectIdHelper

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor.ORBInitInfoPackage
Class ObjectIdHelper

java.lang.Object
    extended by  org.omg.PortableInterceptor.ORBInitInfoPackage.ObjectIdHelper

public abstract class ObjectIdHelper
extends Object

Object id, represented as a String

Constructor Summary
ObjectIdHelper()
Method Summary
static String | extract(Any a)
static String | id()
static void | insert(Any a, String that)
static String | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, String value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ObjectIdHelper

public ObjectIdHelper()
Method Detail

insert

public static void insert(Any a,
                          String that)

extract

public static String extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static String read(InputStream istream)

write

public static void write(OutputStream ostream,
                         String value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


PolicyFactoryOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface PolicyFactoryOperations

All Known Subinterfaces:
PolicyFactory
public interface PolicyFactoryOperations

Enables policy types to be constructed using CORBA.ORB.create_policy.

A portable ORB service implementation registers an instance of the PolicyFactory interface during ORB initialization in order to enable its policy types to be constructed using CORBA.ORB.create_policy. The POA is required to preserve any policy which is registered with ORBInitInfo in this manner.

See Also:
ORBInitInfoOperations.register_policy_factory(int, org.omg.PortableInterceptor.PolicyFactory)

Method Summary
 Policy create_policy(int type, Any value)
Returns an instance of the appropriate interface derived from CORBA.Policy whose value corresponds to the specified any.

Method Detail

create_policy

Policy create_policy(int type,
                     Any value)
                     throws PolicyError
Returns an instance of the appropriate interface derived from CORBA.Policy whose value corresponds to the specified any.

The ORB calls create_policy on a registered PolicyFactory instance when CORBA.ORB.create_policy is called for the PolicyType under which the PolicyFactory has been registered. The create_policy operation then returns an instance of the appropriate interface derived from CORBA.Policy whose value corresponds to the specified any. If it cannot, it shall throw an exception as described for CORBA.ORB.create_policy.

Parameters:
type - An int specifying the type of policy being created.
value - An any containing data with which to construct the CORBA.Policy.
Returns:
A CORBA.Policy object of the specified type and value.
Throws:
PolicyError
Overview  Package   Class  Use  Tree  Deprecated  Index  Help
Java™ Platform
Standard Ed. 6
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RequestInfoOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface RequestInfoOperations

All Known Subinterfaces:
ClientRequestInfo, ClientRequestInfoOperations, RequestInfo, ServerRequestInfo, ServerRequestInfoOperations
public interface RequestInfoOperations

Request Information, accessible to Interceptors.

Each interception point is given an object through which the Interceptor can access request information. Client-side and server-side interception points are concerned with different information, so there are two information objects: ClientRequestInfo is passed to the client-side interception points and ServerRequestInfo is passed to the server-side interception points. But there is information that is common to both, so they both inherit from a common interface: RequestInfo.

See Also:
ClientRequestInfo, ServerRequestInfo

Method Summary
Parameter[] | arguments() Returns an array of Parameter objects, containing the arguments on the operation being invoked.
String[] | contexts() Returns an array of String objects describing the contexts that may be passed on this operation invocation.
TypeCode[] | exceptions() Returns an array of TypeCode objects describing the TypeCodes of the user exceptions that this operation invocation may throw.
Object | forward_reference() Contains the object to which the request will be forwarded, if the reply_status attribute is LOCATION_FORWARD.
ServiceContext | get_reply_service_context(int id) Returns a copy of the service context with the given ID that is associated with the reply.
ServiceContext | get_request_service_context(int id) Returns a copy of the service context with the given ID that is associated with the request.
Any | get_slot(int id) Returns the data from the given slot of the PortableInterceptor.Current that is in the scope of the request.
String[] | operation_context() Returns an array of String objects containing the contexts being sent on the request.
String | operation() Returns the name of the operation being invoked.
short | reply_status() Describes the state of the result of the operation invocation.
int | request_id() Returns an id that uniquely identifies an active request/reply sequence.
boolean | response_expected() Indicates whether a response is expected.
Any | result() Returns an any containing the result of the operation invocation.
short | sync_scope() Defines how far the request shall progress before control is returned to the client.

Method Detail

request_id

int request_id()
Returns an id that uniquely identifies an active request/reply sequence. Once a request/reply sequence is concluded this ID may be reused. Note that this id is not the same as the GIOP request_id. If GIOP is the transport mechanism used, then these IDs may very well be the same, but this is not guaranteed nor required.

operation

String operation()
Returns the name of the operation being invoked.

arguments

Parameter[] arguments()
Returns an array of Parameter objects, containing the arguments on the operation being invoked. If there are no arguments, this attribute will be a zero length array.

Not all environments provide access to the arguments. With the Java portable bindings, for example, the arguments are not available. In these environments, when this attribute is accessed, NO_RESOURCES will be thrown with a standard minor code of 1.

Note: Arguments are available for DSI/DII calls.

Throws:
NO_RESOURCES - thrown if arguments are not available.
See Also:
PortableInterceptor package comments for limitations / unimplemented features

exceptions

TypeCode[] exceptions()
Returns an array of TypeCode objects describing the TypeCodes of the user exceptions that this operation invocation may throw. If there are no user exceptions, this will return a zero length array.

Not all environments provide access to the exception list. With the Java portable bindings, for example, the exception list is not available. In these environments, when this attribute is accessed, NO_RESOURCES will be thrown with a standard minor code of 1.

Note: Exceptions are available for DSI/DII calls.

Throws:
NO_RESOURCES - thrown if exceptions are not available.
See Also:
PortableInterceptor package comments for limitations / unimplemented features

contexts

String[] contexts()
Returns an array of String objects describing the contexts that may be passed on this operation invocation. If there are no contexts, this will return a zero length array.

Not all environments provide access to the context list. With the Java portable bindings, for example, the context list is not available. In these environments, when this attribute is accessed, NO_RESOURCES will be thrown with a standard minor code of 1.

Note: Contexts are available for DSI/DII calls.

Throws:
NO_RESOURCES - thrown if contexts are not available.
See Also:
PortableInterceptor package comments for limitations / unimplemented features

operation_context

String[] operation_context()
Returns an array of String objects containing the contexts being sent on the request.

Not all environments provide access to the context. With the Java portable bindings, for example, the context is not available. In these environments, when this attribute is accessed, NO_RESOURCES will be thrown with standard minor code of 1.

Note: operation_context is available for DSI/DII calls.

Throws:
NO_RESOURCES - thrown if operation context is not available.
See Also:
PortableInterceptor package comments for limitations / unimplemented features

result

Any result()
Returns an any containing the result of the operation invocation. If the operation return type is void, this attribute will be an any containing a type code with a TCKind value of tk_void and no value.

Not all environments provide access to the result. With the Java portable bindings, for example, the result is not available. In these environments, when this attribute is accessed, NO_RESOURCES will be thrown with a standard minor code of 1.

Note: Result is available for DSI/DII calls.

Throws:
NO_RESOURCES - thrown if result is not available.
See Also:
PortableInterceptor package comments for limitations / unimplemented features

response_expected

boolean response_expected()
Indicates whether a response is expected.

On the client, a reply is not returned when response_expected is false, so receive_reply cannot be called. receive_other is called unless an exception occurs, in which case receive_exception is called.

On the client, within send_poll, this attribute is true.

sync_scope

short sync_scope()
Defines how far the request shall progress before control is returned to the client. This is defined in the Messaging specification, and is pertinent only when response_expected is false. If response_expected is true, the value of sync_scope is undefined. This attribute may have one of the following values:
  • Messaging.SYNC_NONE
  • Messaging.SYNC_WITH_TRANSPORT
  • Messaging.SYNC_WITH_SERVER
  • Messaging.SYNC_WITH_TARGET
On the server, for all scopes, a reply will be created from the return of the target operation call, but the reply will not return to the client. Although it does not return to the client, it does occur, so the normal server-side interception points are followed (i.e., receive_request_service_contexts, receive_request, send_reply or send_exception).

For SYNC_WITH_SERVER and SYNC_WITH_TARGET, the server does send an empty reply back to the client before the target is invoked. This reply is not intercepted by server-side Interceptors.

See Also:
PortableInterceptor package comments for limitations / unimplemented features

reply_status

short reply_status()
Describes the state of the result of the operation invocation. The return value can be one of the following:
  • PortableInterceptor.SUCCESSFUL
  • PortableInterceptor.SYSTEM_EXCEPTION
  • PortableInterceptor.USER_EXCEPTION
  • PortableInterceptor.LOCATION_FORWARD
  • PortableInterceptor.TRANSPORT_RETRY
On the client:
  • Within the receive_reply interception point, this will only return SUCCESSFUL
    • .
  • Within the receive_exception interception point, this will be either SYSTEM_EXCEPTION or USER_EXCEPTION.
  • Within the receive_other interception point, this will be any of: SUCCESSFUL, LOCATION_FORWARD, or TRANSPORT_RETRY. SUCCESSFUL means an asynchronous request returned successfully. LOCATION_FORWARD means that a reply came back with LOCATION_FORWARD as its status. TRANSPORT_RETRY means that the transport mechanism indicated a retry - a GIOP reply with a status of NEEDS_ADDRESSING_MODE, for instance.
On the server:
  • Within the send_reply interception point, this will only be SUCCESSFUL.
  • Within the send_exception interception point, this will be either SYSTEM_EXCEPTION or USER_EXCEPTION.
  • Within the send_other interception point, this attribute will be any of: SUCCESSFUL, or LOCATION_FORWARD. SUCCESSFUL means an asynchronous request returned successfully. LOCATION_FORWARD means that a reply came back with LOCATION_FORWARD as its status.

See Also:
SUCCESSFUL, SYSTEM_EXCEPTION, USER_EXCEPTION, LOCATION_FORWARD, TRANSPORT_RETRY

forward_reference

Object forward_reference()
Contains the object to which the request will be forwarded, if the reply_status attribute is LOCATION_FORWARD. It is indeterminate whether a forwarded request will actually occur.

get_slot

Any get_slot(int id)
             throws InvalidSlot
Returns the data from the given slot of the PortableInterceptor.Current that is in the scope of the request.

If the given slot has not been set, then an any containing a type code with a TCKind value of tk_null is returned.

Parameters:
id - The SlotId of the slot which is to be returned.
Returns:
The slot data, in the form of an any, obtained with the given identifier.
Throws:
InvalidSlot - thrown if the ID does not define an allocated slot.
See Also:
Current

get_request_service_context

ServiceContext get_request_service_context(int id)
Returns a copy of the service context with the given ID that is associated with the request.

Parameters:
id - The IOP.ServiceId of the service context which is to be returned.
Returns:
The IOP.ServiceContext obtained with the given identifier.
Throws:
BAD_PARAM - thrown with a standard minor code of 26, if the request's service context does not contain an entry for that ID.

get_reply_service_context

ServiceContext get_reply_service_context(int id)
Returns a copy of the service context with the given ID that is associated with the reply.

Parameters:
id - The IOP.ServiceId of the service context which is to be returned.
Returns:
The IOP.ServiceContext obtained with the given identifier.
Throws:
BAD_PARAM - thrown with a standard minor code of 26 if the request's service context does not contain an entry for that ID.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServerIdHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Class ServerIdHelper

java.lang.Object
    extended by  org.omg.PortableInterceptor.ServerIdHelper

public abstract class ServerIdHelper
extends Object

org/omg/PortableInterceptor/ServerIdHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:25 AM GMT-08:00

Constructor Summary
ServerIdHelper()
Method Summary
static String | extract(Any a)
static String | id()
static void | insert(Any a, String that)
static String | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, String value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServerIdHelper

public ServerIdHelper()
Method Detail

insert

public static void insert(Any a,
                          String that)

extract

public static String extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static String read(InputStream istream)

write

public static void write(OutputStream ostream,
                         String value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServerRequestInfoOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface ServerRequestInfoOperations

All Superinterfaces:
RequestInfoOperations
All Known Subinterfaces:
ServerRequestInfo
public interface ServerRequestInfoOperations
extends RequestInfoOperations

Request Information, accessible to server-side request interceptors.

Some attributes and operations on ServerRequestInfo are not valid at all interception points. The following table shows the validity of each attribute or operation. If it is not valid, attempting to access it will result in a BAD_INV_ORDER being thrown with a standard minor code of 14.

 | receive_request_ service_contexts | receive_request | send_reply | send_exception | send_other
Inherited from RequestInfo:
request_id | yes | yes | yes | yes | yes
operation | yes | yes | yes | yes | yes
arguments | no | yes1 | yes | no2 | no2
exceptions | no | yes | yes | yes | yes
contexts | no | yes | yes | yes | yes
operation_context | no | yes | yes | no | no
result | no | no | yes | no | no
response_expected | yes | yes | yes | yes | yes
sync_scope | yes | yes | yes | yes | yes
request_id | yes | yes | yes | yes | yes
operation | yes | yes | yes | yes | yes
arguments | no | yes1 | yes | no2 | no2
exceptions | no | yes | yes | yes | yes
contexts | no | yes | yes | yes | yes
operation_context | no | yes | yes | no | no
result | no | no | yes | no | no
response_expected | yes | yes | yes | yes | yes
sync_scope | yes | yes | yes | yes | yes
reply_status | no | no | yes | yes | yes
forward_reference | no | no | no | no | yes2
get_slot | yes | yes | yes | yes | yes
get_request_service_context | yes | no | yes | yes | yes
get_reply_service_context | no | no | yes | yes | yes
ServerRequestInfo-specific:
sending_exception | no | no | no | yes | no
object_id | no | yes | yes | yes3 | yes3
adapter_id | no | yes | yes | yes3 | yes3
server_id | no | yes | yes | yes | yes
orb_id | no | yes | yes | yes | yes
adapter_name | no | yes | yes | yes | yes
target_most_derived_interface | no | yes | no4 | no4 | no4
get_server_policy | yes | yes | yes | yes | yes
set_slot | yes | yes | yes | yes | yes
target_is_a | no | yes | no4 | no4 | no4
add_reply_service_context | yes | yes | yes | yes | yes

  1. When ServerRequestInfo is passed to receive_request, there is an entry in the list for every argument, whether in, inout, or out. But only the in and inout arguments will be available.
  2. If the reply_status attribute is not LOCATION_FORWARD, accessing this attribute will throw BAD_INV_ORDER with a standard minor code of 14.
  3. If the servant locator caused a location forward, or thrown an exception, this attribute/operation may not be available in this interception point. NO_RESOURCES with a standard minor code of 1 will be thrown if it is not available.
  4. The operation is not available in this interception point because the necessary information requires access to the target object's servant, which may no longer be available to the ORB. For example, if the object's adapter is a POA that uses a ServantLocator, then the ORB invokes the interception point after it calls ServantLocator.postinvoke()
    5. .

See Also:
ServerRequestInterceptor

Method Summary
 byte[] adapter_id()
Returns the opaque identifier for the object adapter.
 String[] adapter_name()
Returns the sequence of strings that identifies the object adapter instance that is handling this request.
 void add_reply_service_context(ServiceContext service_context, boolean replace)
Allows Interceptors to add service contexts to the request.
 Policy get_server_policy(int type)
Returns the policy in effect for this operation for the given policy type.
 byte[] object_id()
Returns the opaque object_id describing the target of the operation invocation.
 String orb_id()
Returns the ID that was used to create the ORB.
 Any sending_exception()
Returns an any which contains the exception to be returned to the client.
 String server_id()
Returns the server ID that was specified on ORB::init using the -ORBServerId argument.
 void set_slot(int id, Any data)
Allows an Interceptor to set a slot in the PortableInterceptor.Current that is in the scope of the request.
 boolean target_is_a(String id)
Returns true if the servant is the given repository id, false if it is not.
 String target_most_derived_interface()
Returns the repository id for the most derived interface of the servant.
Methods inherited from interface org.omg.PortableInterceptor.RequestInfoOperations
arguments, contexts, exceptions, forward_reference, get_reply_service_context, get_request_service_context, get_slot, operation_context, operation, reply_status, request_id, response_expected, result, sync_scope

Method Detail

sending_exception

Any sending_exception()
Returns an any which contains the exception to be returned to the client.

If the exception is a user exception which cannot be inserted into an any (e.g., it is unknown or the bindings don't provide the TypeCode), then this attribute will be an any containing the system exception UNKNOWN with a standard minor code of 1.

See Also:
PortableInterceptor package comments for limitations / unimplemented features

object_id

byte[] object_id()
Returns the opaque object_id describing the target of the operation invocation.

adapter_id

byte[] adapter_id()
Returns the opaque identifier for the object adapter.

server_id

String server_id()
Returns the server ID that was specified on ORB::init using the -ORBServerId argument.

orb_id

String orb_id()
Returns the ID that was used to create the ORB.

adapter_name

String[] adapter_name()
Returns the sequence of strings that identifies the object adapter instance that is handling this request.

target_most_derived_interface

String target_most_derived_interface()
Returns the repository id for the most derived interface of the servant.

get_server_policy

Policy get_server_policy(int type)
Returns the policy in effect for this operation for the given policy type. The returned CORBA.Policy object shall only be a policy whose type was registered via register_policy_factory.

Parameters:
type - The CORBA.PolicyType which specifies the policy to be returned.
Returns:
The CORBA.Policy obtained with the given policy type.
Throws:
INV_POLICY - thrown, with a standard minor code of 2, if a policy for the given type was not registered via register_policy_factory.
See Also:
ORBInitInfoOperations.register_policy_factory(int, org.omg.PortableInterceptor.PolicyFactory)

set_slot

void set_slot(int id,
              Any data)
              throws InvalidSlot
Allows an Interceptor to set a slot in the PortableInterceptor.Current that is in the scope of the request. If data already exists in that slot, it will be overwritten.

Parameters:
id - The id of the slot.
data - The data, in the form of an any, to store in that slot.
Throws:
InvalidSlot - thrown if the ID does not define an allocated slot.
See Also:
Current

target_is_a

boolean target_is_a(String id)
Returns true if the servant is the given repository id, false if it is not.

Parameters:
id - The caller wants to know if the servant is this repository id.
Returns:
Is the servant the given RepositoryId?

add_reply_service_context

void add_reply_service_context(ServiceContext service_context,
                               boolean replace)
Allows Interceptors to add service contexts to the request.

There is no declaration of the order of the service contexts. They may or may not appear in the order that they are added.

Parameters:
service_context - The IOP.ServiceContext to add to the reply.
replace - Indicates the behavior of this operation when a service context already exists with the given ID. If false, then BAD_INV_ORDER with a standard minor code of 15 is thrown. If true, then the existing service context is replaced by the new one.
Throws:
BAD_INV_ORDER - thrown, with a standard minor code of 15, if replace is false and a service context already exists with the given ID.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServerRequestInterceptorOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface ServerRequestInterceptorOperations

All Superinterfaces:
InterceptorOperations
All Known Subinterfaces:
ServerRequestInterceptor
public interface ServerRequestInterceptorOperations
extends InterceptorOperations

Server-side request interceptor.

A request Interceptor is designed to intercept the flow of a request/reply sequence through the ORB at specific points so that services can query the request information and manipulate the service contexts which are propagated between clients and servers. The primary use of request Interceptors is to enable ORB services to transfer context information between clients and servers. There are two types of request Interceptors: client-side and server-side.

To write a server-side Interceptor, implement the ServerRequestInterceptor interface.

See Also:
ServerRequestInfo

Method Summary
void | receive_request_service_contexts(ServerRequestInfo ri) Allows the interceptor to process service context information.
void | receive_request(ServerRequestInfo ri) Allows an Interceptor to query request information after all the information, including operation parameters, are available.
void | send_exception(ServerRequestInfo ri) Allows an Interceptor to query the exception information and modify the reply service context before the exception is thrown to the client.
void | send_other(ServerRequestInfo ri) Allows an Interceptor to query the information available when a request results in something other than a normal reply or an exception.
void | send_reply(ServerRequestInfo ri) Allows an Interceptor to query reply information and modify the reply service context after the target operation has been invoked and before the reply is returned to the client.
Methods inherited from interface org.omg.PortableInterceptor.InterceptorOperations
destroy, name

Method Detail

receive_request_service_contexts

void receive_request_service_contexts(ServerRequestInfo ri)
                                      throws ForwardRequest
Allows the interceptor to process service context information.

At this interception point, Interceptors must get their service context information from the incoming request transfer it to PortableInterceptor.Current's slots.

This interception point is called before the servant manager is called. Operation parameters are not yet available at this point. This interception point may or may not execute in the same thread as the target invocation.

This interception point may throw a system exception. If it does, no other Interceptors' receive_request_service_contexts operations are called. Those Interceptors on the Flow Stack are popped and their send_exception interception points are called.

This interception point may also throw a ForwardRequest exception. If an Interceptor throws this exception, no other Interceptors' receive_request_service_contexts operations are called. Those Interceptors on the Flow Stack are popped and their send_other interception points are called.

Compliant Interceptors shall properly follow completion_status semantics if they throw a system exception from this interception point. The completion_status shall be COMPLETED_NO.

Parameters:
ri - Information about the current request being intercepted.
Throws:
ForwardRequest - If thrown, indicates to the ORB that a retry of the request should occur with the new object given in the exception.

receive_request

void receive_request(ServerRequestInfo ri)
                     throws ForwardRequest
Allows an Interceptor to query request information after all the information, including operation parameters, are available. This interception point shall execute in the same thread as the target invocation.

In the DSI model, since the parameters are first available when the user code calls arguments, receive_request is called from within arguments. It is possible that arguments is not called in the DSI model. The target may call set_exception before calling arguments. The ORB shall guarantee that receive_request is called once, either through arguments or through set_exception. If it is called through set_exception, requesting the arguments will result in NO_RESOURCES being thrown with a standard minor code of 1.

This interception point may throw a system exception. If it does, no other Interceptors' receive_request operations are called. Those Interceptors on the Flow Stack are popped and their send_exception interception points are called.

This interception point may also throw a ForwardRequest exception. If an Interceptor throws this exception, no other Interceptors' receive_request operations are called. Those Interceptors on the Flow Stack are popped and their send_other interception points are called.

Compliant Interceptors shall properly follow completion_status semantics if they throw a system exception from this interception point. The completion_status shall be COMPLETED_NO.

Parameters:
ri - Information about the current request being intercepted.
Throws:
ForwardRequest - If thrown, indicates to the ORB that a retry of the request should occur with the new object given in the exception.

send_reply

void send_reply(ServerRequestInfo ri)
Allows an Interceptor to query reply information and modify the reply service context after the target operation has been invoked and before the reply is returned to the client. This interception point shall execute in the same thread as the target invocation.

This interception point may throw a system exception. If it does, no other Interceptors' send_reply operations are called. The remaining Interceptors in the Flow Stack shall have their send_exception interception point called.

Compliant Interceptors shall properly follow completion_status semantics if they throw a system exception from this interception point. The completion_status shall be COMPLETED_YES.

Parameters:
ri - Information about the current request being intercepted.

send_exception

void send_exception(ServerRequestInfo ri)
                    throws ForwardRequest
Allows an Interceptor to query the exception information and modify the reply service context before the exception is thrown to the client. When an exception occurs, this interception point is called. This interception point shall execute in the same thread as the target invocation.

This interception point may throw a system exception. This has the effect of changing the exception which successive Interceptors popped from the Flow Stack receive on their calls to send_exception. The exception thrown to the client will be the last exception thrown by an Interceptor, or the original exception if no Interceptor changes the exception.

This interception point may also throw a ForwardRequest exception. If an Interceptor throws this exception, no other Interceptors' send_exception operations are called. The remaining Interceptors in the Flow Stack shall have their send_other interception points called.

If the completion_status of the exception is not COMPLETED_NO, then it is inappropriate for this interception point to throw a ForwardRequest exception. The request's at-most-once semantics would be lost.

Compliant Interceptors shall properly follow completion_status semantics if they throw a system exception from this interception point. If the original exception is a system exception, the completion_status of the new exception shall be the same as on the original. If the original exception is a user exception, then the completion_status of the new exception shall be COMPLETED_YES.

Parameters:
ri - Information about the current request being intercepted.
Throws:
ForwardRequest - If thrown, indicates to the ORB that a retry of the request should occur with the new object given in the exception.

send_other

void send_other(ServerRequestInfo ri)
                throws ForwardRequest
Allows an Interceptor to query the information available when a request results in something other than a normal reply or an exception. For example, a request could result in a retry (e.g., a GIOP Reply with a LOCATION_FORWARD status was received). This interception point shall execute in the same thread as the target invocation.

This interception point may throw a system exception. If it does, no other Interceptors' send_other operations are called. The remaining Interceptors in the Flow Stack shall have their send_exception interception points called.

This interception point may also throw a ForwardRequest exception. If an Interceptor throws this exception, successive Interceptors' send_other operations are called with the new information provided by the ForwardRequest exception.

Compliant Interceptors shall properly follow completion_status semantics if they throw a system exception from this interception point. The completion_status shall be COMPLETED_NO.

Parameters:
ri - Information about the current request being intercepted.
Throws:
ForwardRequest - If thrown, indicates to the ORB that a retry of the request should occur with the new object given in the exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SUCCESSFUL

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface SUCCESSFUL

public interface SUCCESSFUL

org/omg/PortableInterceptor/SUCCESSFUL.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:25 AM GMT-08:00

Field Summary
static short value
Indicates a successful Reply Status.

Field Detail

value

static final short value
Indicates a successful Reply Status. One possible value for RequestInfo.reply_status.

See Also:
RequestInfoOperations.reply_status(), SYSTEM_EXCEPTION, USER_EXCEPTION, LOCATION_FORWARD, TRANSPORT_RETRY, Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SYSTEM_EXCEPTION

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface SYSTEM_EXCEPTION

public interface SYSTEM_EXCEPTION

org/omg/PortableInterceptor/SYSTEM_EXCEPTION.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:25 AM GMT-08:00

Field Summary
static short value
Indicates a SystemException reply status.

Field Detail

value

static final short value
Indicates a SystemException reply status. One possible value for RequestInfo.reply_status.

See Also:
RequestInfoOperations.reply_status(), SUCCESSFUL, USER_EXCEPTION, LOCATION_FORWARD, TRANSPORT_RETRY, Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TRANSPORT_RETRY

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface TRANSPORT_RETRY

public interface TRANSPORT_RETRY

org/omg/PortableInterceptor/TRANSPORT_RETRY.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:25 AM GMT-08:00

Field Summary
static short value
Indicates a Transport Retry reply status.

Field Detail

value

static final short value
Indicates a Transport Retry reply status. One possible value for RequestInfo.reply_status.

See Also:
RequestInfoOperations.reply_status(), SUCCESSFUL, SYSTEM_EXCEPTION, USER_EXCEPTION, LOCATION_FORWARD, Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UNKNOWN

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface UNKNOWN

public interface UNKNOWN

org/omg/PortableInterceptor/UNKNOWN.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:25 AM GMT-08:00

Field Summary
static short value
XXX

Field Detail

value

static final short value
XXX

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


USER_EXCEPTION

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableInterceptor
Interface USER_EXCEPTION

public interface USER_EXCEPTION

org/omg/PortableInterceptor/USER_EXCEPTION.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableInterceptor/Interceptors.idl Wednesday, November 29, 2006 1:57:25 AM GMT-08:00

Field Summary
static short value
Indicates a UserException reply status.

Field Detail

value

static final short value
Indicates a UserException reply status. One possible value for RequestInfo.reply_status.

See Also:
RequestInfoOperations.reply_status(), SUCCESSFUL, SYSTEM_EXCEPTION, LOCATION_FORWARD, TRANSPORT_RETRY, Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


PortableServer

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.PortableServer

Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

See:
Description

Interface Summary
AdapterActivator | An adapter activator supplies a POA with the ability to create child POAs on demand, as a side-effect of receiving a request that names the child POA (or one of its children), or when find_POA is called with an activate parameter value of TRUE.
AdapterActivatorOperations | An adapter activator supplies a POA with the ability to create child POAs on demand, as a side-effect of receiving a request that names the child POA (or one of its children), or when find_POA is called with an activate parameter value of TRUE.
Current | The PortableServer::Current interface, derived from CORBA::Current, provides method implementations with access to the identity of the object on which the method was invoked.
CurrentOperations | The PortableServer::Current interface, derived from CORBA::Current, provides method implementations with access to the identity of the object on which the method was invoked.
ID_ASSIGNMENT_POLICY_ID | org/omg/PortableServer/ID_ASSIGNMENT_POLICY_ID.java .
ID_UNIQUENESS_POLICY_ID | org/omg/PortableServer/ID_UNIQUENESS_POLICY_ID.java .
IdAssignmentPolicy | IdAssignmentPolicy specifies whether Object Ids in the created POA are generated by the application or by the ORB.
IdAssignmentPolicyOperations | IdAssignmentPolicy specifies whether Object Ids in the created POA are generated by the application or by the ORB.
IdUniquenessPolicy | The IdUniquenessPolicy specifies whether the servants activated in the created POA must have unique object i identities.
IdUniquenessPolicyOperations | The IdUniquenessPolicy specifies whether the servants activated in the created POA must have unique object i identities.
IMPLICIT_ACTIVATION_POLICY_ID | org/omg/PortableServer/IMPLICIT_ACTIVATION_POLICY_ID.java .
ImplicitActivationPolicy | This policy specifies whether implicit activation of servants is supported in the created POA.
ImplicitActivationPolicyOperations | This policy specifies whether implicit activation of servants is supported in the created POA.
LIFESPAN_POLICY_ID | org/omg/PortableServer/LIFESPAN_POLICY_ID.java .
LifespanPolicy | The LifespanPolicy specifies the lifespan of the objects implemented in the created POA.
LifespanPolicyOperations | The LifespanPolicy specifies the lifespan of the objects implemented in the created POA.
POA | A POA object manages the implementation of a collection of objects.
POAManager | Each POA object has an associated POAManager object.
POAManagerOperations | Each POA object has an associated POAManager object.
POAOperations | A POA object manages the implementation of a collection of objects.
REQUEST_PROCESSING_POLICY_ID | org/omg/PortableServer/REQUEST_PROCESSING_POLICY_ID.java .
RequestProcessingPolicy | This policy specifies how requests are processed by the created POA.
RequestProcessingPolicyOperations | This policy specifies how requests are processed by the created POA.
SERVANT_RETENTION_POLICY_ID | org/omg/PortableServer/SERVANT_RETENTION_POLICY_ID.java .
ServantActivator | When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
ServantActivatorOperations | When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
ServantLocator | When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.
ServantLocatorOperations | When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.
ServantManager | A servant manager supplies a POA with the ability to activate objects on demand when the POA receives a request targeted at an inactive object.
ServantManagerOperations | A servant manager supplies a POA with the ability to activate objects on demand when the POA receives a request targeted at an inactive object.
ServantRetentionPolicy | This policy specifies whether the created POA retains active servants in an Active Object Map.
ServantRetentionPolicyOperations | This policy specifies whether the created POA retains active servants in an Active Object Map.
THREAD_POLICY_ID | org/omg/PortableServer/THREAD_POLICY_ID.java .
ThreadPolicy | The ThreadPolicy specifies the threading model used with the created POA.
ThreadPolicyOperations | The ThreadPolicy specifies the threading model used with the created POA.

Class Summary
_ServantActivatorStub | When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
_ServantLocatorStub | When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.
CurrentHelper | The PortableServer::Current interface, derived from CORBA::Current, provides method implementations with access to the identity of the object on which the method was invoked.
DynamicImplementation | Allows dynamic handling of object invocations.
ForwardRequestHelper | org/omg/PortableServer/ForwardRequestHelper.java .
IdAssignmentPolicyValue | The IdAssignmentPolicyValue can have the following values.
IdUniquenessPolicyValue | IdUniquenessPolicyValue can have the following values.
ImplicitActivationPolicyValue | ImplicitActivationPolicyValue has the following semantics.
LifespanPolicyValue | The LifespanPolicyValue can have the following values.
POAHelper | A POA object manages the implementation of a collection of objects.
RequestProcessingPolicyValue | The RequestProcessingPolicyValue can have the following values.
Servant | Defines the native Servant type.
ServantActivatorHelper | When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
ServantActivatorPOA | When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
ServantLocatorHelper | When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.
ServantLocatorPOA | When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.
ServantRetentionPolicyValue | ServantRetentionPolicyValue can have the following values.
ThreadPolicyValue | The ThreadPolicyValue can have the following values.

Exception Summary
ForwardRequest org/omg/PortableServer/ForwardRequest.java .

Package org.omg.PortableServer Description

Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

In Java, Portable Object Adaptor (POA)-based Dynamic Skeleton Interface (DSI) servants inherit from the standard DynamicImplementation class, which inherits from the Servant class. The native Servant type is defined by the PortableServer module for the POA. In Java, the Servant type is mapped to the Java org.omg.PortableServer.Servant class. It serves as the base class for all POA servant implementations and provides a number of methods that may be invoked by the application programmer, as well as methods which are invoked by the POA itself and may be overridden by the user to control aspects of servant behavior.

Package Specification

For a precise list of supported sections of official OMG specifications with which the Java[tm] Platform, Standard Edition 6 complies, see Official Specifications for CORBA support in Java[tm] SE 6.

POA-related Interfaces

The PortableServer module defines the following POA-related interfaces:

  • POA
  • POAManager
  • ServantManager
  • ServantActivator
  • ServantLocator
  • AdapterActivator
  • ThreadPolicy
  • LifespanPolicy
  • IdUniquenessPolicy
  • IdAssignmentPolicy
  • ImplicitActivationPolicy
  • ServantRetentionPolicy
  • RequestProcessingPolicy
  • Current

In addition, the POA defines the Servant native type.

Operations classes

Each of the interfaces listed above has an associated Operations interface. The Operations interface is generated by the idlj compiler and contains the method signatures for methods defined in its associated interface. The Operations interface can be accessed by both the client and the server, while its associated interface can only be called by the client.

Value Classes

Classes ending in the suffix PolicyValue provide the values used for the create_POA call, which sets the policy for the POA. See the sample code below for a demonstration. PolicyValue files include the following:

  • IdAssignmentPolicyValue
  • IdUniquenessPolicyValue
  • ImplicitActivationPolicyValue
  • LifespanPolicyValue
  • RequestProcessingPolicyValue
  • ServantRetentionPolicyValue
  • ThreadPolicyValue

Helper Classes

Helper classes, which are generated for all user-defined types in an OMG IDL interface, supply static methods needed to manipulate those types. There is only one method in a helper class that an application programmer uses: the narrow method. Only Java interfaces mapped from IDL interfaces will have a helper class that includes a narrow method, so in the PortableServer package, only the following classes have a narrow method:

  • ForwardRequestHelper
  • ServantActivatorHelper
  • ServantLocatorHelper

POA Classes

POA classes are used to implement the ServantActivator or ServantLocator.

Exceptions

The ForwardRequest exception indicates to the ORB that it is responsible for delivering the current request and subsequent ForwardRequest requests to the object denoted in the forward_reference member of the exception.

Interfaces Implemented by the Application Programmer

Most of what PortableServer does is transparent to the user. The result is that programmers will use only a few of the interfaces mentioned above. The remaining interfaces will be provided by the ORB implementation. The interfaces of interest to application programmers are the following:

  • AdapterActivator

    Adapter activators are associated with POAs. An adapter activator supplies a POA with the ability to create child POAs on demand, as a side-effect of receiving a request that names the child POA (or one of its children), or when find_POA is called with an activate parameter value of TRUE. An application server that creates all its needed POAs at the beginning of execution does not need to use or provide an adapter activator; it is necessary only for the case in which POAs need to be created during request processing.

  • ServantLocator

    When the POA has the NON_RETAIN policy, it uses servant managers that are ServantLocators.

  • ServantActivator

    When the POA has the RETAIN policy, it uses servant managers that are ServantActivators.

Package org.omg.PortableServer.ServantLocatorPackage

This package supplies a CookieHolder class for passing the Cookie type as an out parameter. The CookieHolder class follows exactly the same pattern as the other holder classes for basic types.

Related Documentation

For an overview of Java IDL, please see:

  • Java IDL home page.

    Example Code

    Example Server Code

    import javax.naming.InitialContext;
import javax.naming.Context;
import javax.rmi.PortableRemoteObject ;
import com.sun.corba.se.impl.poa.POAORB;
import org.omg.PortableServer.*;
import java.util.*;
import org.omg.CORBA.*;
import javax.rmi.CORBA.Stub;
import javax.rmi.CORBA.Util;

public class HelloServer {
    public HelloServer(String[] args) {
        try {
            Properties p = System.getProperties();
         //   p.put("org.omg.CORBA.ORBClass", "com.sun.corba.ee.internal.POA.POAORB");
            ORB orb = ORB.init( args, p );

            POA rootPOA = (POA)orb.resolve_initial_references("RootPOA");

            Policy[] tpolicy = new Policy[3];
            tpolicy[0] = rootPOA.create_lifespan_policy(
                LifespanPolicyValue.TRANSIENT );
            tpolicy[1] = rootPOA.create_request_processing_policy(
                RequestProcessingPolicyValue.USE_ACTIVE_OBJECT_MAP_ONLY );
            tpolicy[2] = rootPOA.create_servant_retention_policy(
                ServantRetentionPolicyValue.RETAIN);
            POA tpoa = rootPOA.create_POA("MyTransientPOA", null, tpolicy);

            String  ObjectId = "MyObjectId";
            byte[] oid = ObjectId.getBytes();

            org.omg.CORBA.Object obj = tpoa.create_reference_with_id(oid,
                new _HelloImpl_Tie()._all_interfaces(tpoa, oid)[0]);
            HelloInterface helloRef = (HelloInterface)PortableRemoteObject.narrow(
                obj, HelloInterface.class );

            Context initialNamingContext = new InitialContext();
            initialNamingContext.rebind("HelloService", helloRef);
            System.out.println("Hello Server: Ready...");
            orb.run();
         } catch (Exception e) {
            System.out.println("Trouble: " + e);
            e.printStackTrace();
         }
     }

     public static void main(String args[]) {
         new HelloServer( args );
     }
}

    Since:
    1.4
    Overview Package Class Use Tree Deprecated Index Help
            Java™ Platform
    Standard Ed. 6
    PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


AdapterActivator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface AdapterActivator

All Superinterfaces:
AdapterActivatorOperations, IDLEntity, Object, Serializable
public interface AdapterActivator
extends AdapterActivatorOperations, Object, IDLEntity

An adapter activator supplies a POA with the ability to create child POAs on demand, as a side-effect of receiving a request that names the child POA (or one of its children), or when find_POA is called with an activate parameter value of TRUE.

Method Summary
Methods inherited from interface org.omg.PortableServer.AdapterActivatorOperations
unknown_adapter
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Current

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface Current

All Superinterfaces:
Current, CurrentOperations, IDLEntity, Object, Serializable
public interface Current
extends CurrentOperations, Current, IDLEntity

The PortableServer::Current interface, derived from CORBA::Current, provides method implementations with access to the identity of the object on which the method was invoked. The Current interface is provided to support servants that implement multiple objects, but can be used within the context of POA-dispatched method invocations on any servant. To provide location transparency, ORBs are required to support use of Current in the context of both locally and remotely invoked operations. An instance of Current can be obtained by the application by issuing the CORBA::ORB::resolve_initial_references("POACurrent") operation. Thereafter, it can be used within the context of a method dispatched by the POA to obtain the POA and ObjectId that identify the object on which that operation was invoked.

Method Summary
Methods inherited from interface org.omg.PortableServer.CurrentOperations
get_object_id, get_POA
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


_ServantActivatorStub

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class _ServantActivatorStub

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.PortableServer._ServantActivatorStub
All Implemented Interfaces:
Serializable, Object, IDLEntity, ServantActivator, ServantActivatorOperations, ServantManager, ServantManagerOperations
public class _ServantActivatorStub
extends ObjectImpl
implements ServantActivator

When the POA has the RETAIN policy it uses servant managers that are ServantActivators.

Field Summary
static Class _opsClass
Constructor Summary
_ServantActivatorStub()
Method Summary
String[] | _ids() Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
void | etherealize(byte[] oid, POA adapter, Servant serv, boolean cleanup_in_progress, boolean remaining_activations) This operation is invoked whenever a servant for an object is deactivated, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.
Servant | incarnate(byte[] oid, POA adapter) This operation is invoked by the POA whenever the POA receives a request for an object that is not currently active, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Field Detail

_opsClass

public static final Class _opsClass
Constructor Detail

_ServantActivatorStub

public _ServantActivatorStub()
Method Detail

incarnate

public Servant incarnate(byte[] oid,
                         POA adapter)
                  throws ForwardRequest
This operation is invoked by the POA whenever the POA receives a request for an object that is not currently active, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.

Specified by:
incarnate in interface ServantActivatorOperations
Parameters:
oid - object Id associated with the object on the request was made.
adapter - object reference for the POA in which the object is being activated.
Returns:
Servant corresponding to oid is created or located by the user supplied servant manager.
Throws:
ForwardRequest - to indicate to the ORB that it is responsible for delivering the current request and subsequent requests to the object denoted in the forward_reference member of the exception.

etherealize

public void etherealize(byte[] oid,
                        POA adapter,
                        Servant serv,
                        boolean cleanup_in_progress,
                        boolean remaining_activations)
This operation is invoked whenever a servant for an object is deactivated, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.

Specified by:
etherealize in interface ServantActivatorOperations
Parameters:
oid - object Id associated with the object being deactivated.
adapter - object reference for the POA in which the object was active.
serv - contains reference to the servant associated with the object being deactivated.
cleanup_in_progress - if TRUE indicates that destroy or deactivate is called with etherealize_objects param of TRUE. FALSE indicates that etherealize was called due to other reasons.
remaining_activations - indicates whether the Servant Manager can destroy a servant. If set to TRUE, the Servant Manager should wait until all invocations in progress have completed.

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Specified by:
_ids in class ObjectImpl
Returns:
the array of all repository identifiers supported by this ObjectImpl instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


IdAssignmentPolicy

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface IdAssignmentPolicy

All Superinterfaces:
IdAssignmentPolicyOperations, IDLEntity, Object, Policy, PolicyOperations, Serializable
public interface IdAssignmentPolicy
extends IdAssignmentPolicyOperations, Policy, IDLEntity

IdAssignmentPolicy specifies whether Object Ids in the created POA are generated by the application or by the ORB. The default is SYSTEM_ID.

Method Summary
Methods inherited from interface org.omg.PortableServer.IdAssignmentPolicyOperations
value
Methods inherited from interface org.omg.CORBA.PolicyOperations
copy, destroy, policy_type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IdUniquenessPolicy

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface IdUniquenessPolicy

All Superinterfaces:
IDLEntity, IdUniquenessPolicyOperations, Object, Policy, PolicyOperations, Serializable
public interface IdUniquenessPolicy
extends IdUniquenessPolicyOperations, Policy, IDLEntity

The IdUniquenessPolicy specifies whether the servants activated in the created POA must have unique object i identities. The default is UNIQUE_ID.

Method Summary
Methods inherited from interface org.omg.PortableServer.IdUniquenessPolicyOperations
value
Methods inherited from interface org.omg.CORBA.PolicyOperations
copy, destroy, policy_type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ImplicitActivationPolicy

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface ImplicitActivationPolicy

All Superinterfaces:
IDLEntity, ImplicitActivationPolicyOperations, Object, Policy, PolicyOperations, Serializable
public interface ImplicitActivationPolicy
extends ImplicitActivationPolicyOperations, Policy, IDLEntity

This policy specifies whether implicit activation of servants is supported in the created POA.

Method Summary
Methods inherited from interface org.omg.PortableServer.ImplicitActivationPolicyOperations
value
Methods inherited from interface org.omg.CORBA.PolicyOperations
copy, destroy, policy_type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LifespanPolicy

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface LifespanPolicy

All Superinterfaces:
IDLEntity, LifespanPolicyOperations, Object, Policy, PolicyOperations, Serializable
public interface LifespanPolicy
extends LifespanPolicyOperations, Policy, IDLEntity

The LifespanPolicy specifies the lifespan of the objects implemented in the created POA. The default is TRANSIENT.

Method Summary
Methods inherited from interface org.omg.PortableServer.LifespanPolicyOperations
value
Methods inherited from interface org.omg.CORBA.PolicyOperations
copy, destroy, policy_type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


org.omg.PortableServer Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.PortableServer

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.PortableServer.CurrentHelper
    • org.omg.PortableServer.ForwardRequestHelper
    • org.omg.PortableServer.IdAssignmentPolicyValue (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.PortableServer.IdUniquenessPolicyValue (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.PortableServer.ImplicitActivationPolicyValue (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.PortableServer.LifespanPolicyValue (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.CORBA.portable.ObjectImpl (implements org.omg.CORBA.Object)
      • org.omg.PortableServer._ServantActivatorStub (implements org.omg.PortableServer.ServantActivator)
      • org.omg.PortableServer._ServantLocatorStub (implements org.omg.PortableServer.ServantLocator)
    • org.omg.PortableServer.POAHelper
    • org.omg.PortableServer.RequestProcessingPolicyValue (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.PortableServer.Servant
      • org.omg.PortableServer.DynamicImplementation
      • org.omg.PortableServer.ServantActivatorPOA (implements org.omg.CORBA.portable.InvokeHandler, org.omg.PortableServer.ServantActivatorOperations)
      • org.omg.PortableServer.ServantLocatorPOA (implements org.omg.CORBA.portable.InvokeHandler, org.omg.PortableServer.ServantLocatorOperations)
    • org.omg.PortableServer.ServantActivatorHelper
    • org.omg.PortableServer.ServantLocatorHelper
    • org.omg.PortableServer.ServantRetentionPolicyValue (implements org.omg.CORBA.portable.IDLEntity)
    • org.omg.PortableServer.ThreadPolicyValue (implements org.omg.CORBA.portable.IDLEntity)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.omg.CORBA.UserException (implements org.omg.CORBA.portable.IDLEntity)
          • org.omg.PortableServer.ForwardRequest

Interface Hierarchy

  • org.omg.PortableServer.AdapterActivatorOperations
    • org.omg.PortableServer.AdapterActivator (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
  • org.omg.CORBA.CurrentOperations
    • org.omg.CORBA.Current (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
      • org.omg.PortableServer.Current (also extends org.omg.PortableServer.CurrentOperations, org.omg.CORBA.portable.IDLEntity)
    • org.omg.PortableServer.CurrentOperations
      • org.omg.PortableServer.Current (also extends org.omg.CORBA.Current, org.omg.CORBA.portable.IDLEntity)
  • org.omg.PortableServer.ID_ASSIGNMENT_POLICY_ID
  • org.omg.PortableServer.ID_UNIQUENESS_POLICY_ID
  • org.omg.PortableServer.IMPLICIT_ACTIVATION_POLICY_ID
  • org.omg.PortableServer.LIFESPAN_POLICY_ID
  • org.omg.CORBA.Object
    • org.omg.PortableServer.AdapterActivator (also extends org.omg.PortableServer.AdapterActivatorOperations, org.omg.CORBA.portable.IDLEntity)
    • org.omg.CORBA.Current (also extends org.omg.CORBA.CurrentOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.PortableServer.Current (also extends org.omg.PortableServer.CurrentOperations, org.omg.CORBA.portable.IDLEntity)
    • org.omg.PortableServer.POA (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.POAOperations)
    • org.omg.PortableServer.POAManager (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.POAManagerOperations)
    • org.omg.CORBA.Policy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.PolicyOperations)
      • org.omg.PortableServer.IdAssignmentPolicy (also extends org.omg.PortableServer.IdAssignmentPolicyOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.PortableServer.IdUniquenessPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.IdUniquenessPolicyOperations)
      • org.omg.PortableServer.ImplicitActivationPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ImplicitActivationPolicyOperations)
      • org.omg.PortableServer.LifespanPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.LifespanPolicyOperations)
      • org.omg.PortableServer.RequestProcessingPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.RequestProcessingPolicyOperations)
      • org.omg.PortableServer.ServantRetentionPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ServantRetentionPolicyOperations)
      • org.omg.PortableServer.ThreadPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ThreadPolicyOperations)
    • org.omg.PortableServer.ServantManager (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ServantManagerOperations)
      • org.omg.PortableServer.ServantActivator (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ServantActivatorOperations)
      • org.omg.PortableServer.ServantLocator (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ServantLocatorOperations)
  • org.omg.PortableServer.POAManagerOperations
    • org.omg.PortableServer.POAManager (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
  • org.omg.PortableServer.POAOperations
    • org.omg.PortableServer.POA (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
  • org.omg.CORBA.PolicyOperations
    • org.omg.PortableServer.IdAssignmentPolicyOperations
      • org.omg.PortableServer.IdAssignmentPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Policy)
    • org.omg.PortableServer.IdUniquenessPolicyOperations
      • org.omg.PortableServer.IdUniquenessPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Policy)
    • org.omg.PortableServer.ImplicitActivationPolicyOperations
      • org.omg.PortableServer.ImplicitActivationPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Policy)
    • org.omg.PortableServer.LifespanPolicyOperations
      • org.omg.PortableServer.LifespanPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Policy)
    • org.omg.CORBA.Policy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
      • org.omg.PortableServer.IdAssignmentPolicy (also extends org.omg.PortableServer.IdAssignmentPolicyOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.PortableServer.IdUniquenessPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.IdUniquenessPolicyOperations)
      • org.omg.PortableServer.ImplicitActivationPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ImplicitActivationPolicyOperations)
      • org.omg.PortableServer.LifespanPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.LifespanPolicyOperations)
      • org.omg.PortableServer.RequestProcessingPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.RequestProcessingPolicyOperations)
      • org.omg.PortableServer.ServantRetentionPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ServantRetentionPolicyOperations)
      • org.omg.PortableServer.ThreadPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ThreadPolicyOperations)
    • org.omg.PortableServer.RequestProcessingPolicyOperations
      • org.omg.PortableServer.RequestProcessingPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Policy)
    • org.omg.PortableServer.ServantRetentionPolicyOperations
      • org.omg.PortableServer.ServantRetentionPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Policy)
    • org.omg.PortableServer.ThreadPolicyOperations
      • org.omg.PortableServer.ThreadPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Policy)
  • org.omg.PortableServer.REQUEST_PROCESSING_POLICY_ID
  • java.io.Serializable
    • org.omg.CORBA.portable.IDLEntity
      • org.omg.PortableServer.AdapterActivator (also extends org.omg.PortableServer.AdapterActivatorOperations, org.omg.CORBA.Object)
      • org.omg.CORBA.Current (also extends org.omg.CORBA.CurrentOperations, org.omg.CORBA.Object)
        • org.omg.PortableServer.Current (also extends org.omg.PortableServer.CurrentOperations, org.omg.CORBA.portable.IDLEntity)
      • org.omg.PortableServer.Current (also extends org.omg.CORBA.Current, org.omg.PortableServer.CurrentOperations)
      • org.omg.PortableServer.IdAssignmentPolicy (also extends org.omg.PortableServer.IdAssignmentPolicyOperations, org.omg.CORBA.Policy)
      • org.omg.PortableServer.IdUniquenessPolicy (also extends org.omg.PortableServer.IdUniquenessPolicyOperations, org.omg.CORBA.Policy)
      • org.omg.PortableServer.ImplicitActivationPolicy (also extends org.omg.PortableServer.ImplicitActivationPolicyOperations, org.omg.CORBA.Policy)
      • org.omg.PortableServer.LifespanPolicy (also extends org.omg.PortableServer.LifespanPolicyOperations, org.omg.CORBA.Policy)
      • org.omg.PortableServer.POA (also extends org.omg.CORBA.Object, org.omg.PortableServer.POAOperations)
      • org.omg.PortableServer.POAManager (also extends org.omg.CORBA.Object, org.omg.PortableServer.POAManagerOperations)
      • org.omg.CORBA.Policy (also extends org.omg.CORBA.Object, org.omg.CORBA.PolicyOperations)
        • org.omg.PortableServer.IdAssignmentPolicy (also extends org.omg.PortableServer.IdAssignmentPolicyOperations, org.omg.CORBA.portable.IDLEntity)
        • org.omg.PortableServer.IdUniquenessPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.IdUniquenessPolicyOperations)
        • org.omg.PortableServer.ImplicitActivationPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ImplicitActivationPolicyOperations)
        • org.omg.PortableServer.LifespanPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.LifespanPolicyOperations)
        • org.omg.PortableServer.RequestProcessingPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.RequestProcessingPolicyOperations)
        • org.omg.PortableServer.ServantRetentionPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ServantRetentionPolicyOperations)
        • org.omg.PortableServer.ThreadPolicy (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ThreadPolicyOperations)
      • org.omg.PortableServer.RequestProcessingPolicy (also extends org.omg.CORBA.Policy, org.omg.PortableServer.RequestProcessingPolicyOperations)
      • org.omg.PortableServer.ServantActivator (also extends org.omg.PortableServer.ServantActivatorOperations, org.omg.PortableServer.ServantManager)
      • org.omg.PortableServer.ServantLocator (also extends org.omg.PortableServer.ServantLocatorOperations, org.omg.PortableServer.ServantManager)
      • org.omg.PortableServer.ServantManager (also extends org.omg.CORBA.Object, org.omg.PortableServer.ServantManagerOperations)
        • org.omg.PortableServer.ServantActivator (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ServantActivatorOperations)
        • org.omg.PortableServer.ServantLocator (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ServantLocatorOperations)
      • org.omg.PortableServer.ServantRetentionPolicy (also extends org.omg.CORBA.Policy, org.omg.PortableServer.ServantRetentionPolicyOperations)
      • org.omg.PortableServer.ThreadPolicy (also extends org.omg.CORBA.Policy, org.omg.PortableServer.ThreadPolicyOperations)
  • org.omg.PortableServer.SERVANT_RETENTION_POLICY_ID
  • org.omg.PortableServer.ServantManagerOperations
    • org.omg.PortableServer.ServantActivatorOperations
      • org.omg.PortableServer.ServantActivator (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ServantManager)
    • org.omg.PortableServer.ServantLocatorOperations
      • org.omg.PortableServer.ServantLocator (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ServantManager)
    • org.omg.PortableServer.ServantManager (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
      • org.omg.PortableServer.ServantActivator (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ServantActivatorOperations)
      • org.omg.PortableServer.ServantLocator (also extends org.omg.CORBA.portable.IDLEntity, org.omg.PortableServer.ServantLocatorOperations)
  • org.omg.PortableServer.THREAD_POLICY_ID
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


POA

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface POA

All Superinterfaces:
IDLEntity, Object, POAOperations, Serializable
public interface POA
extends POAOperations, Object, IDLEntity

A POA object manages the implementation of a collection of objects. The POA supports a name space for the objects, which are identified by Object Ids. A POA also provides a name space for POAs. A POA is created as a child of an existing POA, which forms a hierarchy starting with the root POA. A POA object must not be exported to other processes, or externalized with ORB::object_to_string.

Method Summary
Methods inherited from interface org.omg.PortableServer.POAOperations
activate_object_with_id, activate_object, create_id_assignment_policy, create_id_uniqueness_policy, create_implicit_activation_policy, create_lifespan_policy, create_POA, create_reference_with_id, create_reference, create_request_processing_policy, create_servant_retention_policy, create_thread_policy, deactivate_object, destroy, find_POA, get_servant_manager, get_servant, id_to_reference, id_to_servant, id, reference_to_id, reference_to_servant, servant_to_id, servant_to_reference, set_servant_manager, set_servant, the_activator, the_activator, the_children, the_name, the_parent, the_POAManager
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


POAManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface POAManager

All Superinterfaces:
IDLEntity, Object, POAManagerOperations, Serializable
public interface POAManager
extends POAManagerOperations, Object, IDLEntity

Each POA object has an associated POAManager object. A POA manager may be associated with one or more POA objects. A POA manager encapsulates the processing state of the POAs it is associated with.

Method Summary
Methods inherited from interface org.omg.PortableServer.POAManagerOperations
activate, deactivate, discard_requests, get_state, hold_requests
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


_ServantLocatorStub

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class _ServantLocatorStub

java.lang.Object
    extended by  org.omg.CORBA.portable.ObjectImpl
        extended by  org.omg.PortableServer._ServantLocatorStub
All Implemented Interfaces:
Serializable, Object, IDLEntity, ServantLocator, ServantLocatorOperations, ServantManager, ServantManagerOperations
public class _ServantLocatorStub
extends ObjectImpl
implements ServantLocator

When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators. Because the POA knows that the servant returned by this servant manager will be used only for a single request, it can supply extra information to the servant manager's operations and the servant manager's pair of operations may be able to cooperate to do something different than a ServantActivator. When the POA uses the ServantLocator interface, immediately after performing the operation invocation on the servant returned by preinvoke, the POA will invoke postinvoke on the servant manager, passing the ObjectId value and the Servant value as parameters (among others). This feature may be used to force every request for objects associated with a POA to be mediated by the servant manager.

Field Summary
static Class _opsClass
Constructor Summary
_ServantLocatorStub()
Method Summary
String[] | _ids() Retrieves a string array containing the repository identifiers supported by this ObjectImpl object.
void | postinvoke(byte[] oid, POA adapter, String operation, Object the_cookie, Servant the_servant) This operation is invoked whenener a servant completes a request.
Servant | preinvoke(byte[] oid, POA adapter, String operation, CookieHolder the_cookie) This operations is used to get a servant that will be used to process the request that caused preinvoke to be called.
Methods inherited from class org.omg.CORBA.portable.ObjectImpl
_create_request, _create_request, _duplicate, _get_delegate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _invoke, _is_a, _is_equivalent, _is_local, _non_existent, _orb, _release, _releaseReply, _request, _request, _servant_postinvoke, _servant_preinvoke, _set_delegate, _set_policy_override, equals, hashCode, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Field Detail

_opsClass

public static final Class _opsClass
Constructor Detail

_ServantLocatorStub

public _ServantLocatorStub()
Method Detail

preinvoke

public Servant preinvoke(byte[] oid,
                         POA adapter,
                         String operation,
                         CookieHolder the_cookie)
                  throws ForwardRequest
This operations is used to get a servant that will be used to process the request that caused preinvoke to be called.

Specified by:
preinvoke in interface ServantLocatorOperations
Parameters:
oid - the object id associated with object on which the request was made.
adapter - the reference for POA in which the object is being activated.
operation - the operation name.
the_cookie - an opaque value that can be set by the servant manager to be used during postinvoke.
Returns:
Servant used to process incoming request.
Throws:
ForwardRequest - to indicate to the ORB that it is responsible for delivering the current request and subsequent requests to the object denoted in the forward_reference member of the exception.

postinvoke

public void postinvoke(byte[] oid,
                       POA adapter,
                       String operation,
                       Object the_cookie,
                       Servant the_servant)
This operation is invoked whenener a servant completes a request.

Specified by:
postinvoke in interface ServantLocatorOperations
Parameters:
oid - the object id ssociated with object on which the request was made.
adapter - the reference for POA in which the object was active.
the_cookie - an opaque value that contains the data set by preinvoke.
the_servant - reference to the servant that is associated with the object.

_ids

public String[] _ids()
Description copied from class: ObjectImpl
Retrieves a string array containing the repository identifiers supported by this ObjectImpl object. For example, for a stub, this method returns information about all the interfaces supported by the stub.

Specified by:
_ids in class ObjectImpl
Returns:
the array of all repository identifiers supported by this ObjectImpl instance
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RequestProcessingPolicy

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface RequestProcessingPolicy

All Superinterfaces:
IDLEntity, Object, Policy, PolicyOperations, RequestProcessingPolicyOperations, Serializable
public interface RequestProcessingPolicy
extends RequestProcessingPolicyOperations, Policy, IDLEntity

This policy specifies how requests are processed by the created POA. The default is USE_ACTIVE_OBJECT_MAP_ONLY.

Method Summary
Methods inherited from interface org.omg.PortableServer.RequestProcessingPolicyOperations
value
Methods inherited from interface org.omg.CORBA.PolicyOperations
copy, destroy, policy_type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantActivator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface ServantActivator

All Superinterfaces:
IDLEntity, Object, Serializable, ServantActivatorOperations, ServantManager, ServantManagerOperations
All Known Implementing Classes:
_ServantActivatorStub
public interface ServantActivator
extends ServantActivatorOperations, ServantManager, IDLEntity

When the POA has the RETAIN policy it uses servant managers that are ServantActivators.

Method Summary
Methods inherited from interface org.omg.PortableServer.ServantActivatorOperations
etherealize, incarnate
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantLocator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface ServantLocator

All Superinterfaces:
IDLEntity, Object, Serializable, ServantLocatorOperations, ServantManager, ServantManagerOperations
All Known Implementing Classes:
_ServantLocatorStub
public interface ServantLocator
extends ServantLocatorOperations, ServantManager, IDLEntity

When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators. Because the POA knows that the servant returned by this servant manager will be used only for a single request, it can supply extra information to the servant manager's operations and the servant manager's pair of operations may be able to cooperate to do something different than a ServantActivator. When the POA uses the ServantLocator interface, immediately after performing the operation invocation on the servant returned by preinvoke, the POA will invoke postinvoke on the servant manager, passing the ObjectId value and the Servant value as parameters (among others). This feature may be used to force every request for objects associated with a POA to be mediated by the servant manager.

Method Summary
Methods inherited from interface org.omg.PortableServer.ServantLocatorOperations
postinvoke, preinvoke
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantManager

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface ServantManager

All Superinterfaces:
IDLEntity, Object, Serializable, ServantManagerOperations
All Known Subinterfaces:
ServantActivator, ServantLocator
All Known Implementing Classes:
_ServantActivatorStub, _ServantLocatorStub
public interface ServantManager
extends ServantManagerOperations, Object, IDLEntity

A servant manager supplies a POA with the ability to activate objects on demand when the POA receives a request targeted at an inactive object. A servant manager is registered with a POA as a callback object, to be invoked by the POA when necessary. ServantManagers can either be ServantActivators or ServantLocators. A ServantManager object must be local to the process containing the POA objects it is registered with.

Method Summary
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantManagerOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface ServantManagerOperations

All Known Subinterfaces:
ServantActivator, ServantActivatorOperations, ServantLocator, ServantLocatorOperations, ServantManager
All Known Implementing Classes:
_ServantActivatorStub, _ServantLocatorStub, ServantActivatorPOA, ServantLocatorPOA
public interface ServantManagerOperations

A servant manager supplies a POA with the ability to activate objects on demand when the POA receives a request targeted at an inactive object. A servant manager is registered with a POA as a callback object, to be invoked by the POA when necessary. ServantManagers can either be ServantActivators or ServantLocators. A ServantManager object must be local to the process containing the POA objects it is registered with.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantRetentionPolicy

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface ServantRetentionPolicy

All Superinterfaces:
IDLEntity, Object, Policy, PolicyOperations, Serializable, ServantRetentionPolicyOperations
public interface ServantRetentionPolicy
extends ServantRetentionPolicyOperations, Policy, IDLEntity

This policy specifies whether the created POA retains active servants in an Active Object Map.

Method Summary
Methods inherited from interface org.omg.PortableServer.ServantRetentionPolicyOperations
value
Methods inherited from interface org.omg.CORBA.PolicyOperations
copy, destroy, policy_type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ThreadPolicy

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface ThreadPolicy

All Superinterfaces:
IDLEntity, Object, Policy, PolicyOperations, Serializable, ThreadPolicyOperations
public interface ThreadPolicy
extends ThreadPolicyOperations, Policy, IDLEntity

The ThreadPolicy specifies the threading model used with the created POA. The default is ORB_CTRL_MODEL.

Method Summary
Methods inherited from interface org.omg.PortableServer.ThreadPolicyOperations
value
Methods inherited from interface org.omg.CORBA.PolicyOperations
copy, destroy, policy_type
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Package org.omg.PortableServer

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.PortableServer

Packages that use org.omg.PortableServer
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.portable | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Classes in org.omg.PortableServer used by org.omg.CosNaming
POA
A POA object manages the implementation of a collection of objects.
Servant
Defines the native Servant type.

Classes in org.omg.PortableServer used by org.omg.PortableServer
AdapterActivator
An adapter activator supplies a POA with the ability to create child POAs on demand, as a side-effect of receiving a request that names the child POA (or one of its children), or when find_POA is called with an activate parameter value of TRUE.
AdapterActivatorOperations
An adapter activator supplies a POA with the ability to create child POAs on demand, as a side-effect of receiving a request that names the child POA (or one of its children), or when find_POA is called with an activate parameter value of TRUE.
Current
The PortableServer::Current interface, derived from CORBA::Current, provides method implementations with access to the identity of the object on which the method was invoked.
CurrentOperations
The PortableServer::Current interface, derived from CORBA::Current, provides method implementations with access to the identity of the object on which the method was invoked.
ForwardRequest
org/omg/PortableServer/ForwardRequest.java .
IdAssignmentPolicy
IdAssignmentPolicy specifies whether Object Ids in the created POA are generated by the application or by the ORB.
IdAssignmentPolicyOperations
IdAssignmentPolicy specifies whether Object Ids in the created POA are generated by the application or by the ORB.
IdAssignmentPolicyValue
The IdAssignmentPolicyValue can have the following values.
IdUniquenessPolicy
The IdUniquenessPolicy specifies whether the servants activated in the created POA must have unique object i identities.
IdUniquenessPolicyOperations
The IdUniquenessPolicy specifies whether the servants activated in the created POA must have unique object i identities.
IdUniquenessPolicyValue
IdUniquenessPolicyValue can have the following values.
ImplicitActivationPolicy
This policy specifies whether implicit activation of servants is supported in the created POA.
ImplicitActivationPolicyOperations
This policy specifies whether implicit activation of servants is supported in the created POA.
ImplicitActivationPolicyValue
ImplicitActivationPolicyValue has the following semantics.
LifespanPolicy
The LifespanPolicy specifies the lifespan of the objects implemented in the created POA.
LifespanPolicyOperations
The LifespanPolicy specifies the lifespan of the objects implemented in the created POA.
LifespanPolicyValue
The LifespanPolicyValue can have the following values.
POA
A POA object manages the implementation of a collection of objects.
POAManager
Each POA object has an associated POAManager object.
POAManagerOperations
Each POA object has an associated POAManager object.
POAOperations
A POA object manages the implementation of a collection of objects.
RequestProcessingPolicy
This policy specifies how requests are processed by the created POA.
RequestProcessingPolicyOperations
This policy specifies how requests are processed by the created POA.
RequestProcessingPolicyValue
The RequestProcessingPolicyValue can have the following values.
Servant
Defines the native Servant type.
ServantActivator
When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
ServantActivatorOperations
When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
ServantLocator
When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.
ServantLocatorOperations
When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.
ServantManager
A servant manager supplies a POA with the ability to activate objects on demand when the POA receives a request targeted at an inactive object.
ServantManagerOperations
A servant manager supplies a POA with the ability to activate objects on demand when the POA receives a request targeted at an inactive object.
ServantRetentionPolicy
This policy specifies whether the created POA retains active servants in an Active Object Map.
ServantRetentionPolicyOperations
This policy specifies whether the created POA retains active servants in an Active Object Map.
ServantRetentionPolicyValue
ServantRetentionPolicyValue can have the following values.
ThreadPolicy
The ThreadPolicy specifies the threading model used with the created POA.
ThreadPolicyOperations
The ThreadPolicy specifies the threading model used with the created POA.
ThreadPolicyValue
The ThreadPolicyValue can have the following values.

Classes in org.omg.PortableServer used by org.omg.PortableServer.portable
POA
A POA object manages the implementation of a collection of objects.
Servant
Defines the native Servant type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AdapterActivatorOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface AdapterActivatorOperations

All Known Subinterfaces:
AdapterActivator
public interface AdapterActivatorOperations

An adapter activator supplies a POA with the ability to create child POAs on demand, as a side-effect of receiving a request that names the child POA (or one of its children), or when find_POA is called with an activate parameter value of TRUE.

Method Summary
 boolean unknown_adapter(POA parent, String name)
This operation is invoked when the ORB receives a request for an object reference that identifies a target POA that does not exist.

Method Detail

unknown_adapter

boolean unknown_adapter(POA parent,
                        String name)
This operation is invoked when the ORB receives a request for an object reference that identifies a target POA that does not exist. The ORB invokes this operation once for each POA that must be created in order for the target POA to exist.

Parameters:
parent - indicates the parent POA for the POA that needs to be created.
name - identifies the name of the POA relative to the parent.
Returns:
returns TRUE if the POA was created or FALSE otherwise.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class org.omg.PortableServer.CurrentHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.CurrentHelper

No usage of org.omg.PortableServer.CurrentHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.DynamicImplementation

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.DynamicImplementation

No usage of org.omg.PortableServer.DynamicImplementation

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.ForwardRequest

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.ForwardRequest

Packages that use ForwardRequest
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ForwardRequest in org.omg.PortableServer

Methods in org.omg.PortableServer that return ForwardRequest
static ForwardRequest | ForwardRequestHelper.extract(Any a)
static ForwardRequest | ForwardRequestHelper.read(InputStream istream)

Methods in org.omg.PortableServer with parameters of type ForwardRequest
static void | ForwardRequestHelper.insert(Any a, ForwardRequest that)
static void | ForwardRequestHelper.write(OutputStream ostream, ForwardRequest value)

Methods in org.omg.PortableServer that throw ForwardRequest
Servant | _ServantActivatorStub.incarnate(byte[] oid, POA adapter) This operation is invoked by the POA whenever the POA receives a request for an object that is not currently active, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.
Servant | ServantActivatorOperations.incarnate(byte[] oid, POA adapter) This operation is invoked by the POA whenever the POA receives a request for an object that is not currently active, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.
Servant | _ServantLocatorStub.preinvoke(byte[] oid, POA adapter, String operation, CookieHolder the_cookie) This operations is used to get a servant that will be used to process the request that caused preinvoke to be called.
Servant | ServantLocatorOperations.preinvoke(byte[] oid, POA adapter, String operation, CookieHolder the_cookie) This operations is used to get a servant that will be used to process the request that caused preinvoke to be called.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.ForwardRequestHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.ForwardRequestHelper

No usage of org.omg.PortableServer.ForwardRequestHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.IdAssignmentPolicyValue

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.IdAssignmentPolicyValue

Packages that use IdAssignmentPolicyValue
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of IdAssignmentPolicyValue in org.omg.PortableServer

Fields in org.omg.PortableServer declared as IdAssignmentPolicyValue
static IdAssignmentPolicyValue | IdAssignmentPolicyValue.SYSTEM_ID
static IdAssignmentPolicyValue | IdAssignmentPolicyValue.USER_ID

Methods in org.omg.PortableServer that return IdAssignmentPolicyValue
static IdAssignmentPolicyValue | IdAssignmentPolicyValue.from_int(int value)
IdAssignmentPolicyValue | IdAssignmentPolicyOperations.value() specifies the policy value

Methods in org.omg.PortableServer with parameters of type IdAssignmentPolicyValue
 IdAssignmentPolicy POAOperations.create_id_assignment_policy(IdAssignmentPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.IdUniquenessPolicyValue

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.IdUniquenessPolicyValue

Packages that use IdUniquenessPolicyValue
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of IdUniquenessPolicyValue in org.omg.PortableServer

Fields in org.omg.PortableServer declared as IdUniquenessPolicyValue
static IdUniquenessPolicyValue | IdUniquenessPolicyValue.MULTIPLE_ID
static IdUniquenessPolicyValue | IdUniquenessPolicyValue.UNIQUE_ID

Methods in org.omg.PortableServer that return IdUniquenessPolicyValue
static IdUniquenessPolicyValue | IdUniquenessPolicyValue.from_int(int value)
IdUniquenessPolicyValue | IdUniquenessPolicyOperations.value() specifies the policy value

Methods in org.omg.PortableServer with parameters of type IdUniquenessPolicyValue
 IdUniquenessPolicy POAOperations.create_id_uniqueness_policy(IdUniquenessPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.ImplicitActivationPolicyValue

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.ImplicitActivationPolicyValue

Packages that use ImplicitActivationPolicyValue
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ImplicitActivationPolicyValue in org.omg.PortableServer

Fields in org.omg.PortableServer declared as ImplicitActivationPolicyValue
static ImplicitActivationPolicyValue | ImplicitActivationPolicyValue.IMPLICIT_ACTIVATION
static ImplicitActivationPolicyValue | ImplicitActivationPolicyValue.NO_IMPLICIT_ACTIVATION

Methods in org.omg.PortableServer that return ImplicitActivationPolicyValue
static ImplicitActivationPolicyValue | ImplicitActivationPolicyValue.from_int(int value)
ImplicitActivationPolicyValue | ImplicitActivationPolicyOperations.value() specifies the policy value

Methods in org.omg.PortableServer with parameters of type ImplicitActivationPolicyValue
 ImplicitActivationPolicy POAOperations.create_implicit_activation_policy(ImplicitActivationPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.LifespanPolicyValue

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.LifespanPolicyValue

Packages that use LifespanPolicyValue
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of LifespanPolicyValue in org.omg.PortableServer

Fields in org.omg.PortableServer declared as LifespanPolicyValue
static LifespanPolicyValue | LifespanPolicyValue.PERSISTENT
static LifespanPolicyValue | LifespanPolicyValue.TRANSIENT

Methods in org.omg.PortableServer that return LifespanPolicyValue
static LifespanPolicyValue | LifespanPolicyValue.from_int(int value)
LifespanPolicyValue | LifespanPolicyOperations.value() specifies the policy value

Methods in org.omg.PortableServer with parameters of type LifespanPolicyValue
 LifespanPolicy POAOperations.create_lifespan_policy(LifespanPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAHelper

No usage of org.omg.PortableServer.POAHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.RequestProcessingPolicyValue

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.RequestProcessingPolicyValue

Packages that use RequestProcessingPolicyValue
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of RequestProcessingPolicyValue in org.omg.PortableServer

Fields in org.omg.PortableServer declared as RequestProcessingPolicyValue
static RequestProcessingPolicyValue | RequestProcessingPolicyValue.USE_ACTIVE_OBJECT_MAP_ONLY
static RequestProcessingPolicyValue | RequestProcessingPolicyValue.USE_DEFAULT_SERVANT
static RequestProcessingPolicyValue | RequestProcessingPolicyValue.USE_SERVANT_MANAGER

Methods in org.omg.PortableServer that return RequestProcessingPolicyValue
static RequestProcessingPolicyValue | RequestProcessingPolicyValue.from_int(int value)
RequestProcessingPolicyValue | RequestProcessingPolicyOperations.value() specifies the policy value

Methods in org.omg.PortableServer with parameters of type RequestProcessingPolicyValue
 RequestProcessingPolicy POAOperations.create_request_processing_policy(RequestProcessingPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.Servant

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.Servant

Packages that use Servant
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.portable | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of Servant in org.omg.CosNaming

Subclasses of Servant in org.omg.CosNaming
class | BindingIteratorPOA The BindingIterator interface allows a client to iterate through the bindings using the next_one or next_n operations.
class | NamingContextExtPOA NamingContextExt is the extension of NamingContext which contains a set of name bindings in which each name is unique and is part of Interoperable Naming Service.
class | NamingContextPOA A naming context is an object that contains a set of name bindings in which each name is unique.

Uses of Servant in org.omg.PortableServer

Subclasses of Servant in org.omg.PortableServer
class | DynamicImplementation Allows dynamic handling of object invocations.
class | ServantActivatorPOA When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
class | ServantLocatorPOA When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.

Methods in org.omg.PortableServer that return Servant
Servant | POAOperations.get_servant() This operation returns the default servant associated with the POA.
Servant | POAOperations.id_to_servant(byte[] oid) If the POA has the RETAIN policy and the specified ObjectId is in the Active Object Map, this operation returns the servant associated with that object in the Active Object Map.
Servant | _ServantActivatorStub.incarnate(byte[] oid, POA adapter) This operation is invoked by the POA whenever the POA receives a request for an object that is not currently active, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.
Servant | ServantActivatorOperations.incarnate(byte[] oid, POA adapter) This operation is invoked by the POA whenever the POA receives a request for an object that is not currently active, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.
Servant | _ServantLocatorStub.preinvoke(byte[] oid, POA adapter, String operation, CookieHolder the_cookie) This operations is used to get a servant that will be used to process the request that caused preinvoke to be called.
Servant | ServantLocatorOperations.preinvoke(byte[] oid, POA adapter, String operation, CookieHolder the_cookie) This operations is used to get a servant that will be used to process the request that caused preinvoke to be called.
Servant | POAOperations.reference_to_servant(Object reference) If the POA has the RETAIN policy and the specified object is present in the Active Object Map, this operation returns the servant associated with that object in the Active Object Map.

Methods in org.omg.PortableServer with parameters of type Servant
void | POAOperations.activate_object_with_id(byte[] id, Servant p_servant) This operation enters an association between the specified Object Id and the specified servant in the Active Object Map.
byte[] | POAOperations.activate_object(Servant p_servant) This operation generates an Object Id and enters the Object Id and the specified servant in the Active Object Map.
void | _ServantActivatorStub.etherealize(byte[] oid, POA adapter, Servant serv, boolean cleanup_in_progress, boolean remaining_activations) This operation is invoked whenever a servant for an object is deactivated, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.
void | ServantActivatorOperations.etherealize(byte[] oid, POA adapter, Servant serv, boolean cleanup_in_progress, boolean remaining_activations) This operation is invoked whenever a servant for an object is deactivated, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.
void | _ServantLocatorStub.postinvoke(byte[] oid, POA adapter, String operation, Object the_cookie, Servant the_servant) This operation is invoked whenener a servant completes a request.
void | ServantLocatorOperations.postinvoke(byte[] oid, POA adapter, String operation, Object the_cookie, Servant the_servant) This operation is invoked whenener a servant completes a request.
byte[] | POAOperations.servant_to_id(Servant p_servant) This operation has four possible behaviors.
Object | POAOperations.servant_to_reference(Servant p_servant) This operation requires the RETAIN policy and either the UNIQUE_ID or IMPLICIT_ACTIVATION policies if invoked outside the context of an operation dispatched by this POA.
void | POAOperations.set_servant(Servant p_servant) This operation registers the specified servant with the POA as the default servant.

Uses of Servant in org.omg.PortableServer.portable

Methods in org.omg.PortableServer.portable with parameters of type Servant
 POA Delegate.default_POA(Servant Self)
The default behavior of this function is to return the root POA from the ORB instance associated with the servant.
 Object Delegate.get_interface_def(Servant self)
This operation returns an object in the Interface Repository which provides type information that may be useful to a program.
 boolean Delegate.is_a(Servant Self, String Repository_Id)
This method checks to see if the specified repid is present on the list returned by _all_interfaces() or is the repository id for the generic CORBA Object.
 boolean Delegate.non_existent(Servant Self)
This operation is used to check for the existence of the Object.
 byte[] Delegate.object_id(Servant Self)
The method _object_id() is equivalent to calling PortableServer::Current::get_object_id.
 ORB Delegate.orb(Servant Self)
Convenience method that returns the instance of the ORB currently associated with the Servant.
 POA Delegate.poa(Servant Self)
The method _poa() is equivalent to calling PortableServer::Current:get_POA.
 Object Delegate.this_object(Servant Self)
This allows the servant to obtain the object reference for the target CORBA Object it is incarnating for that request.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.ServantActivatorHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.ServantActivatorHelper

No usage of org.omg.PortableServer.ServantActivatorHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.ServantActivatorPOA

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.ServantActivatorPOA

No usage of org.omg.PortableServer.ServantActivatorPOA

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.ServantLocatorHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.ServantLocatorHelper

No usage of org.omg.PortableServer.ServantLocatorHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.ServantLocatorPOA

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.ServantLocatorPOA

No usage of org.omg.PortableServer.ServantLocatorPOA

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.ServantRetentionPolicyValue

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.ServantRetentionPolicyValue

Packages that use ServantRetentionPolicyValue
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ServantRetentionPolicyValue in org.omg.PortableServer

Fields in org.omg.PortableServer declared as ServantRetentionPolicyValue
static ServantRetentionPolicyValue | ServantRetentionPolicyValue.NON_RETAIN
static ServantRetentionPolicyValue | ServantRetentionPolicyValue.RETAIN

Methods in org.omg.PortableServer that return ServantRetentionPolicyValue
static ServantRetentionPolicyValue | ServantRetentionPolicyValue.from_int(int value)
ServantRetentionPolicyValue | ServantRetentionPolicyOperations.value() specifies the policy value

Methods in org.omg.PortableServer with parameters of type ServantRetentionPolicyValue
 ServantRetentionPolicy POAOperations.create_servant_retention_policy(ServantRetentionPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.ThreadPolicyValue

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.ThreadPolicyValue

Packages that use ThreadPolicyValue
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ThreadPolicyValue in org.omg.PortableServer

Fields in org.omg.PortableServer declared as ThreadPolicyValue
static ThreadPolicyValue | ThreadPolicyValue.ORB_CTRL_MODEL
static ThreadPolicyValue | ThreadPolicyValue.SINGLE_THREAD_MODEL

Methods in org.omg.PortableServer that return ThreadPolicyValue
static ThreadPolicyValue | ThreadPolicyValue.from_int(int value)
ThreadPolicyValue | ThreadPolicyOperations.value() specifies the policy value

Methods in org.omg.PortableServer with parameters of type ThreadPolicyValue
 ThreadPolicy POAOperations.create_thread_policy(ThreadPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer._ServantActivatorStub

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer._ServantActivatorStub

No usage of org.omg.PortableServer._ServantActivatorStub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer._ServantLocatorStub

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer._ServantLocatorStub

No usage of org.omg.PortableServer._ServantLocatorStub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.AdapterActivator

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.AdapterActivator

Packages that use AdapterActivator
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of AdapterActivator in org.omg.PortableServer

Methods in org.omg.PortableServer that return AdapterActivator
 AdapterActivator POAOperations.the_activator()
This attribute identifies the adapter activator associated with the POA.

Methods in org.omg.PortableServer with parameters of type AdapterActivator
 void POAOperations.the_activator(AdapterActivator newThe_activator)
This attribute identifies the adapter activator associated with the POA.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.AdapterActivatorOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.AdapterActivatorOperations

Packages that use AdapterActivatorOperations
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of AdapterActivatorOperations in org.omg.PortableServer

Subinterfaces of AdapterActivatorOperations in org.omg.PortableServer
 interface AdapterActivator
An adapter activator supplies a POA with the ability to create child POAs on demand, as a side-effect of receiving a request that names the child POA (or one of its children), or when find_POA is called with an activate parameter value of TRUE.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.Current

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.Current

Packages that use Current
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of Current in org.omg.PortableServer

Methods in org.omg.PortableServer that return Current
static Current | CurrentHelper.extract(Any a)
static Current | CurrentHelper.narrow(Object obj)
static Current | CurrentHelper.read(InputStream istream)

Methods in org.omg.PortableServer with parameters of type Current
static void | CurrentHelper.insert(Any a, Current that)
static void | CurrentHelper.write(OutputStream ostream, Current value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.CurrentOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.CurrentOperations

Packages that use CurrentOperations
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of CurrentOperations in org.omg.PortableServer

Subinterfaces of CurrentOperations in org.omg.PortableServer
 interface Current
The PortableServer::Current interface, derived from CORBA::Current, provides method implementations with access to the identity of the object on which the method was invoked.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.IdAssignmentPolicy

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.IdAssignmentPolicy

Packages that use IdAssignmentPolicy
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of IdAssignmentPolicy in org.omg.PortableServer

Methods in org.omg.PortableServer that return IdAssignmentPolicy
 IdAssignmentPolicy POAOperations.create_id_assignment_policy(IdAssignmentPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.IdAssignmentPolicyOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.IdAssignmentPolicyOperations

Packages that use IdAssignmentPolicyOperations
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of IdAssignmentPolicyOperations in org.omg.PortableServer

Subinterfaces of IdAssignmentPolicyOperations in org.omg.PortableServer
 interface IdAssignmentPolicy
IdAssignmentPolicy specifies whether Object Ids in the created POA are generated by the application or by the ORB.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.IdUniquenessPolicy

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.IdUniquenessPolicy

Packages that use IdUniquenessPolicy
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of IdUniquenessPolicy in org.omg.PortableServer

Methods in org.omg.PortableServer that return IdUniquenessPolicy
 IdUniquenessPolicy POAOperations.create_id_uniqueness_policy(IdUniquenessPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.IdUniquenessPolicyOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.IdUniquenessPolicyOperations

Packages that use IdUniquenessPolicyOperations
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of IdUniquenessPolicyOperations in org.omg.PortableServer

Subinterfaces of IdUniquenessPolicyOperations in org.omg.PortableServer
 interface IdUniquenessPolicy
The IdUniquenessPolicy specifies whether the servants activated in the created POA must have unique object i identities.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.ID_ASSIGNMENT_POLICY_ID

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.ID_ASSIGNMENT_POLICY_ID

No usage of org.omg.PortableServer.ID_ASSIGNMENT_POLICY_ID

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.ID_UNIQUENESS_POLICY_ID

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.ID_UNIQUENESS_POLICY_ID

No usage of org.omg.PortableServer.ID_UNIQUENESS_POLICY_ID

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.ImplicitActivationPolicy

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.ImplicitActivationPolicy

Packages that use ImplicitActivationPolicy
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ImplicitActivationPolicy in org.omg.PortableServer

Methods in org.omg.PortableServer that return ImplicitActivationPolicy
 ImplicitActivationPolicy POAOperations.create_implicit_activation_policy(ImplicitActivationPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.ImplicitActivationPolicyOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.ImplicitActivationPolicyOperations

Packages that use ImplicitActivationPolicyOperations
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ImplicitActivationPolicyOperations in org.omg.PortableServer

Subinterfaces of ImplicitActivationPolicyOperations in org.omg.PortableServer
 interface ImplicitActivationPolicy
This policy specifies whether implicit activation of servants is supported in the created POA.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.IMPLICIT_ACTIVATION_POLICY_ID

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.IMPLICIT_ACTIVATION_POLICY_ID

No usage of org.omg.PortableServer.IMPLICIT_ACTIVATION_POLICY_ID

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.LifespanPolicy

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.LifespanPolicy

Packages that use LifespanPolicy
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of LifespanPolicy in org.omg.PortableServer

Methods in org.omg.PortableServer that return LifespanPolicy
 LifespanPolicy POAOperations.create_lifespan_policy(LifespanPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.LifespanPolicyOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.LifespanPolicyOperations

Packages that use LifespanPolicyOperations
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of LifespanPolicyOperations in org.omg.PortableServer

Subinterfaces of LifespanPolicyOperations in org.omg.PortableServer
 interface LifespanPolicy
The LifespanPolicy specifies the lifespan of the objects implemented in the created POA.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.LIFESPAN_POLICY_ID

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.LIFESPAN_POLICY_ID

No usage of org.omg.PortableServer.LIFESPAN_POLICY_ID

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.POA

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.POA

Packages that use POA
org.omg.CosNaming | Provides a naming service for Java IDL.
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.portable | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of POA in org.omg.CosNaming

Methods in org.omg.CosNaming with parameters of type POA
String[] | NamingContextExtPOA._all_interfaces(POA poa, byte[] objectId)
String[] | NamingContextPOA._all_interfaces(POA poa, byte[] objectId)
String[] | BindingIteratorPOA._all_interfaces(POA poa, byte[] objectId)

Uses of POA in org.omg.PortableServer

Methods in org.omg.PortableServer that return POA
 POA Servant._default_POA()
Returns the root POA from the ORB instance associated with the servant.
 POA Servant._poa()
Allows easy execution of common methods, equivalent to PortableServer::Current:get_POA.
 POA POAOperations.create_POA(String adapter_name, POAManager a_POAManager, Policy[] policies)
This operation creates a new POA as a child of the target POA.
static POA POAHelper.extract(Any a)
 POA POAOperations.find_POA(String adapter_name, boolean activate_it)
If the target POA is the parent of a child POA with the specified name (relative to the target POA), that child POA is returned.
 POA CurrentOperations.get_POA()
Returns reference to the POA implementing the object in whose context it is called.
static POA POAHelper.narrow(Object obj)
static POA POAHelper.read(InputStream istream)
 POA[] POAOperations.the_children()
This attribute identifies the current set of all child POAs of the POA.
 POA POAOperations.the_parent()
This attribute identifies the parent of the POA.

Methods in org.omg.PortableServer with parameters of type POA
String[] | ServantLocatorPOA._all_interfaces(POA poa, byte[] objectId)
String[] | ServantActivatorPOA._all_interfaces(POA poa, byte[] objectId)
abstract String[] | Servant._all_interfaces(POA poa, byte[] objectId) Used by the ORB to obtain complete type information from the servant.
void | _ServantActivatorStub.etherealize(byte[] oid, POA adapter, Servant serv, boolean cleanup_in_progress, boolean remaining_activations) This operation is invoked whenever a servant for an object is deactivated, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.
void | ServantActivatorOperations.etherealize(byte[] oid, POA adapter, Servant serv, boolean cleanup_in_progress, boolean remaining_activations) This operation is invoked whenever a servant for an object is deactivated, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.
Servant | _ServantActivatorStub.incarnate(byte[] oid, POA adapter) This operation is invoked by the POA whenever the POA receives a request for an object that is not currently active, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.
Servant | ServantActivatorOperations.incarnate(byte[] oid, POA adapter) This operation is invoked by the POA whenever the POA receives a request for an object that is not currently active, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.
static void | POAHelper.insert(Any a, POA that)
void | _ServantLocatorStub.postinvoke(byte[] oid, POA adapter, String operation, Object the_cookie, Servant the_servant) This operation is invoked whenener a servant completes a request.
void | ServantLocatorOperations.postinvoke(byte[] oid, POA adapter, String operation, Object the_cookie, Servant the_servant) This operation is invoked whenener a servant completes a request.
Servant | _ServantLocatorStub.preinvoke(byte[] oid, POA adapter, String operation, CookieHolder the_cookie) This operations is used to get a servant that will be used to process the request that caused preinvoke to be called.
Servant | ServantLocatorOperations.preinvoke(byte[] oid, POA adapter, String operation, CookieHolder the_cookie) This operations is used to get a servant that will be used to process the request that caused preinvoke to be called.
boolean | AdapterActivatorOperations.unknown_adapter(POA parent, String name) This operation is invoked when the ORB receives a request for an object reference that identifies a target POA that does not exist.
static void | POAHelper.write(OutputStream ostream, POA value)

Uses of POA in org.omg.PortableServer.portable

Methods in org.omg.PortableServer.portable that return POA
 POA Delegate.default_POA(Servant Self)
The default behavior of this function is to return the root POA from the ORB instance associated with the servant.
 POA Delegate.poa(Servant Self)
The method _poa() is equivalent to calling PortableServer::Current:get_POA.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.POAManager

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.POAManager

Packages that use POAManager
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of POAManager in org.omg.PortableServer

Methods in org.omg.PortableServer that return POAManager
 POAManager POAOperations.the_POAManager()
This attribute identifies the POA manager associated with the POA.

Methods in org.omg.PortableServer with parameters of type POAManager
 POA POAOperations.create_POA(String adapter_name, POAManager a_POAManager, Policy[] policies)
This operation creates a new POA as a child of the target POA.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.POAManagerOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.POAManagerOperations

Packages that use POAManagerOperations
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of POAManagerOperations in org.omg.PortableServer

Subinterfaces of POAManagerOperations in org.omg.PortableServer
 interface POAManager
Each POA object has an associated POAManager object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.POAOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.POAOperations

Packages that use POAOperations
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of POAOperations in org.omg.PortableServer

Subinterfaces of POAOperations in org.omg.PortableServer
 interface POA
A POA object manages the implementation of a collection of objects.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.RequestProcessingPolicy

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.RequestProcessingPolicy

Packages that use RequestProcessingPolicy
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of RequestProcessingPolicy in org.omg.PortableServer

Methods in org.omg.PortableServer that return RequestProcessingPolicy
 RequestProcessingPolicy POAOperations.create_request_processing_policy(RequestProcessingPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.RequestProcessingPolicyOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.RequestProcessingPolicyOperations

Packages that use RequestProcessingPolicyOperations
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of RequestProcessingPolicyOperations in org.omg.PortableServer

Subinterfaces of RequestProcessingPolicyOperations in org.omg.PortableServer
 interface RequestProcessingPolicy
This policy specifies how requests are processed by the created POA.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.REQUEST_PROCESSING_POLICY_ID

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.REQUEST_PROCESSING_POLICY_ID

No usage of org.omg.PortableServer.REQUEST_PROCESSING_POLICY_ID

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.ServantActivator

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.ServantActivator

Packages that use ServantActivator
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ServantActivator in org.omg.PortableServer

Classes in org.omg.PortableServer that implement ServantActivator
 class _ServantActivatorStub
When the POA has the RETAIN policy it uses servant managers that are ServantActivators.

Methods in org.omg.PortableServer that return ServantActivator
ServantActivator | ServantActivatorPOA._this()
ServantActivator | ServantActivatorPOA._this(ORB orb)
static ServantActivator | ServantActivatorHelper.extract(Any a)
static ServantActivator | ServantActivatorHelper.narrow(Object obj)
static ServantActivator | ServantActivatorHelper.read(InputStream istream)
static ServantActivator | ServantActivatorHelper.unchecked_narrow(Object obj)

Methods in org.omg.PortableServer with parameters of type ServantActivator
static void | ServantActivatorHelper.insert(Any a, ServantActivator that)
static void | ServantActivatorHelper.write(OutputStream ostream, ServantActivator value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.ServantActivatorOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.ServantActivatorOperations

Packages that use ServantActivatorOperations
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ServantActivatorOperations in org.omg.PortableServer

Subinterfaces of ServantActivatorOperations in org.omg.PortableServer
 interface ServantActivator
When the POA has the RETAIN policy it uses servant managers that are ServantActivators.

Classes in org.omg.PortableServer that implement ServantActivatorOperations
class | _ServantActivatorStub When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
class | ServantActivatorPOA When the POA has the RETAIN policy it uses servant managers that are ServantActivators.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.ServantLocator

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.ServantLocator

Packages that use ServantLocator
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ServantLocator in org.omg.PortableServer

Classes in org.omg.PortableServer that implement ServantLocator
 class _ServantLocatorStub
When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.

Methods in org.omg.PortableServer that return ServantLocator
ServantLocator | ServantLocatorPOA._this()
ServantLocator | ServantLocatorPOA._this(ORB orb)
static ServantLocator | ServantLocatorHelper.extract(Any a)
static ServantLocator | ServantLocatorHelper.narrow(Object obj)
static ServantLocator | ServantLocatorHelper.read(InputStream istream)
static ServantLocator | ServantLocatorHelper.unchecked_narrow(Object obj)

Methods in org.omg.PortableServer with parameters of type ServantLocator
static void | ServantLocatorHelper.insert(Any a, ServantLocator that)
static void | ServantLocatorHelper.write(OutputStream ostream, ServantLocator value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.ServantLocatorOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.ServantLocatorOperations

Packages that use ServantLocatorOperations
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ServantLocatorOperations in org.omg.PortableServer

Subinterfaces of ServantLocatorOperations in org.omg.PortableServer
 interface ServantLocator
When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.

Classes in org.omg.PortableServer that implement ServantLocatorOperations
class | _ServantLocatorStub When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.
class | ServantLocatorPOA When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.ServantManager

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.ServantManager

Packages that use ServantManager
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ServantManager in org.omg.PortableServer

Subinterfaces of ServantManager in org.omg.PortableServer
interface | ServantActivator When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
interface | ServantLocator When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.

Classes in org.omg.PortableServer that implement ServantManager
class | _ServantActivatorStub When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
class | _ServantLocatorStub When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.

Methods in org.omg.PortableServer that return ServantManager
 ServantManager POAOperations.get_servant_manager()
If the ServantRetentionPolicy of the POA is RETAIN, then the ServantManager argument (imgr) shall support the ServantActivator interface.

Methods in org.omg.PortableServer with parameters of type ServantManager
 void POAOperations.set_servant_manager(ServantManager imgr)
This operation sets the default servant manager associated with the POA.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.ServantManagerOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.ServantManagerOperations

Packages that use ServantManagerOperations
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ServantManagerOperations in org.omg.PortableServer

Subinterfaces of ServantManagerOperations in org.omg.PortableServer
interface | ServantActivator When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
interface | ServantActivatorOperations When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
interface | ServantLocator When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.
interface | ServantLocatorOperations When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.
interface | ServantManager A servant manager supplies a POA with the ability to activate objects on demand when the POA receives a request targeted at an inactive object.

Classes in org.omg.PortableServer that implement ServantManagerOperations
class | _ServantActivatorStub When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
class | _ServantLocatorStub When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.
class | ServantActivatorPOA When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
class | ServantLocatorPOA When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.ServantRetentionPolicy

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.ServantRetentionPolicy

Packages that use ServantRetentionPolicy
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ServantRetentionPolicy in org.omg.PortableServer

Methods in org.omg.PortableServer that return ServantRetentionPolicy
 ServantRetentionPolicy POAOperations.create_servant_retention_policy(ServantRetentionPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.ServantRetentionPolicyOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.ServantRetentionPolicyOperations

Packages that use ServantRetentionPolicyOperations
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ServantRetentionPolicyOperations in org.omg.PortableServer

Subinterfaces of ServantRetentionPolicyOperations in org.omg.PortableServer
 interface ServantRetentionPolicy
This policy specifies whether the created POA retains active servants in an Active Object Map.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.SERVANT_RETENTION_POLICY_ID

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.SERVANT_RETENTION_POLICY_ID

No usage of org.omg.PortableServer.SERVANT_RETENTION_POLICY_ID

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.ThreadPolicy

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.ThreadPolicy

Packages that use ThreadPolicy
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ThreadPolicy in org.omg.PortableServer

Methods in org.omg.PortableServer that return ThreadPolicy
 ThreadPolicy POAOperations.create_thread_policy(ThreadPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.ThreadPolicyOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.ThreadPolicyOperations

Packages that use ThreadPolicyOperations
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of ThreadPolicyOperations in org.omg.PortableServer

Subinterfaces of ThreadPolicyOperations in org.omg.PortableServer
 interface ThreadPolicy
The ThreadPolicy specifies the threading model used with the created POA.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.THREAD_POLICY_ID

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.THREAD_POLICY_ID

No usage of org.omg.PortableServer.THREAD_POLICY_ID

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


CurrentHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class CurrentHelper

java.lang.Object
    extended by  org.omg.PortableServer.CurrentHelper

public abstract class CurrentHelper
extends Object

The PortableServer::Current interface, derived from CORBA::Current, provides method implementations with access to the identity of the object on which the method was invoked. The Current interface is provided to support servants that implement multiple objects, but can be used within the context of POA-dispatched method invocations on any servant. To provide location transparency, ORBs are required to support use of Current in the context of both locally and remotely invoked operations. An instance of Current can be obtained by the application by issuing the CORBA::ORB::resolve_initial_references("POACurrent") operation. Thereafter, it can be used within the context of a method dispatched by the POA to obtain the POA and ObjectId that identify the object on which that operation was invoked.

Constructor Summary
CurrentHelper()
Method Summary
static Current | extract(Any a)
static String | id()
static void | insert(Any a, Current that)
static Current | narrow(Object obj)
static Current | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, Current value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CurrentHelper

public CurrentHelper()
Method Detail

insert

public static void insert(Any a,
                          Current that)

extract

public static Current extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static Current read(InputStream istream)

write

public static void write(OutputStream ostream,
                         Current value)

narrow

public static Current narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CurrentOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface CurrentOperations

All Superinterfaces:
CurrentOperations
All Known Subinterfaces:
Current
public interface CurrentOperations
extends CurrentOperations

The PortableServer::Current interface, derived from CORBA::Current, provides method implementations with access to the identity of the object on which the method was invoked. The Current interface is provided to support servants that implement multiple objects, but can be used within the context of POA-dispatched method invocations on any servant. To provide location transparency, ORBs are required to support use of Current in the context of both locally and remotely invoked operations. An instance of Current can be obtained by the application by issuing the CORBA::ORB::resolve_initial_references("POACurrent") operation. Thereafter, it can be used within the context of a method dispatched by the POA to obtain the POA and ObjectId that identify the object on which that operation was invoked.

Method Summary
byte[] | get_object_id() Returns the ObjectId identifying the object in whose context it is called.
POA | get_POA() Returns reference to the POA implementing the object in whose context it is called.

Method Detail

get_POA

POA get_POA()
            throws NoContext
Returns reference to the POA implementing the object in whose context it is called.

Returns:
The poa implementing the object
Throws:
NoContext - is raised when the operation is outside the context of a POA-dispatched operation

get_object_id

byte[] get_object_id()
                     throws NoContext
Returns the ObjectId identifying the object in whose context it is called.

Returns:
the ObjectId of the object
Throws:
NoContext - is raised when the operation is called outside the context of a POA-dispatched operation.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CurrentPackage

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.PortableServer.CurrentPackage

Provides method implementations with access to the identity of the object on which the method was invoked.

See:
Description

Class Summary
NoContextHelper org/omg/PortableServer/CurrentPackage/NoContextHelper.java .

Exception Summary
NoContext org/omg/PortableServer/CurrentPackage/NoContext.java .

Package org.omg.PortableServer.CurrentPackage Description

Provides method implementations with access to the identity of the object on which the method was invoked. The Current package supports servants that implement multiple objects, but can be used within the context of POA-dispatched method invocations on any servant. To provide location transparency, ORBs are required to support use of Current in the context of both locally and remotely invoked operations. An instance of Current can be obtained by the application by issuing the CORBA::ORB::resolve_initial_references("POACurrent") operation. Thereafter, it can be used within the context of a method dispatched by the POA to obtain the POA and ObjectId that identify the object on which that operation was invoked.

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6 ORB complies, see Official Specifications for CORBA support in Java[tm] SE 6.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.PortableServer.CurrentPackage Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.PortableServer.CurrentPackage

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.PortableServer.CurrentPackage.NoContextHelper
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.omg.CORBA.UserException (implements org.omg.CORBA.portable.IDLEntity)
          • org.omg.PortableServer.CurrentPackage.NoContext
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.PortableServer.CurrentPackage

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.PortableServer.CurrentPackage

Packages that use org.omg.PortableServer.CurrentPackage
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.CurrentPackage | Provides method implementations with access to the identity of the object on which the method was invoked.

Classes in org.omg.PortableServer.CurrentPackage used by org.omg.PortableServer
NoContext
org/omg/PortableServer/CurrentPackage/NoContext.java .

Classes in org.omg.PortableServer.CurrentPackage used by org.omg.PortableServer.CurrentPackage
NoContext
org/omg/PortableServer/CurrentPackage/NoContext.java .

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.CurrentPackage.NoContext

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.CurrentPackage.NoContext

Packages that use NoContext
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.CurrentPackage | Provides method implementations with access to the identity of the object on which the method was invoked.

Uses of NoContext in org.omg.PortableServer

Methods in org.omg.PortableServer that throw NoContext
byte[] | CurrentOperations.get_object_id() Returns the ObjectId identifying the object in whose context it is called.
POA | CurrentOperations.get_POA() Returns reference to the POA implementing the object in whose context it is called.

Uses of NoContext in org.omg.PortableServer.CurrentPackage

Methods in org.omg.PortableServer.CurrentPackage that return NoContext
static NoContext | NoContextHelper.extract(Any a)
static NoContext | NoContextHelper.read(InputStream istream)

Methods in org.omg.PortableServer.CurrentPackage with parameters of type NoContext
static void | NoContextHelper.insert(Any a, NoContext that)
static void | NoContextHelper.write(OutputStream ostream, NoContext value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.CurrentPackage.NoContextHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.CurrentPackage.NoContextHelper

No usage of org.omg.PortableServer.CurrentPackage.NoContextHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


NoContext

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.CurrentPackage
Class NoContext

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.PortableServer.CurrentPackage.NoContext
All Implemented Interfaces:
Serializable, IDLEntity
public final class NoContext
extends UserException

org/omg/PortableServer/CurrentPackage/NoContext.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
NoContext()
NoContext(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NoContext

public NoContext()

NoContext

public NoContext(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


NoContextHelper

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.CurrentPackage
Class NoContextHelper

java.lang.Object
    extended by  org.omg.PortableServer.CurrentPackage.NoContextHelper

public abstract class NoContextHelper
extends Object

org/omg/PortableServer/CurrentPackage/NoContextHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
NoContextHelper()
Method Summary
static NoContext | extract(Any a)
static String | id()
static void | insert(Any a, NoContext that)
static NoContext | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, NoContext value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NoContextHelper

public NoContextHelper()
Method Detail

insert

public static void insert(Any a,
                          NoContext that)

extract

public static NoContext extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static NoContext read(InputStream istream)

write

public static void write(OutputStream ostream,
                         NoContext value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


DynamicImplementation

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class DynamicImplementation

java.lang.Object
    extended by  org.omg.PortableServer.Servant
        extended by  org.omg.PortableServer.DynamicImplementation

public abstract class DynamicImplementation
extends Servant

Allows dynamic handling of object invocations. POA-based DSI servants inherit from the standard DynamicImplementation class, this class inherits from the Servant class. Based on IDL to Java spec. CORBA V 2.3.1 ptc/00-01-08.pdf.

Constructor Summary
DynamicImplementation()
Method Summary
abstract  void invoke(ServerRequest request)
Receives requests issued to any CORBA object incarnated by the DSI servant and performs the processing necessary to execute the request.
Methods inherited from class org.omg.PortableServer.Servant
_all_interfaces, _default_POA, _get_delegate, _get_interface_def, _is_a, _non_existent, _object_id, _orb, _poa, _set_delegate, _this_object, _this_object
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DynamicImplementation

public DynamicImplementation()
Method Detail

invoke

public abstract void invoke(ServerRequest request)
Receives requests issued to any CORBA object incarnated by the DSI servant and performs the processing necessary to execute the request.

Parameters:
request - the request issued to the CORBA object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ForwardRequest

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class ForwardRequest

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.PortableServer.ForwardRequest
All Implemented Interfaces:
Serializable, IDLEntity
public final class ForwardRequest
extends UserException

org/omg/PortableServer/ForwardRequest.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Field Summary
 Object forward_reference
Constructor Summary
ForwardRequest()
ForwardRequest(Object _forward_reference)
ForwardRequest(String $reason, Object _forward_reference)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

forward_reference

public Object forward_reference
Constructor Detail

ForwardRequest

public ForwardRequest()

ForwardRequest

public ForwardRequest(Object _forward_reference)

ForwardRequest

public ForwardRequest(String $reason,
                      Object _forward_reference)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ForwardRequestHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class ForwardRequestHelper

java.lang.Object
    extended by  org.omg.PortableServer.ForwardRequestHelper

public abstract class ForwardRequestHelper
extends Object

org/omg/PortableServer/ForwardRequestHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
ForwardRequestHelper()
Method Summary
static ForwardRequest | extract(Any a)
static String | id()
static void | insert(Any a, ForwardRequest that)
static ForwardRequest | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, ForwardRequest value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ForwardRequestHelper

public ForwardRequestHelper()
Method Detail

insert

public static void insert(Any a,
                          ForwardRequest that)

extract

public static ForwardRequest extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static ForwardRequest read(InputStream istream)

write

public static void write(OutputStream ostream,
                         ForwardRequest value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IdAssignmentPolicyOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface IdAssignmentPolicyOperations

All Superinterfaces:
PolicyOperations
All Known Subinterfaces:
IdAssignmentPolicy
public interface IdAssignmentPolicyOperations
extends PolicyOperations

IdAssignmentPolicy specifies whether Object Ids in the created POA are generated by the application or by the ORB. The default is SYSTEM_ID.

Method Summary
 IdAssignmentPolicyValue value()
specifies the policy value
Methods inherited from interface org.omg.CORBA.PolicyOperations
copy, destroy, policy_type

Method Detail

value

IdAssignmentPolicyValue value()
specifies the policy value

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IdAssignmentPolicyValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class IdAssignmentPolicyValue

java.lang.Object
    extended by  org.omg.PortableServer.IdAssignmentPolicyValue
All Implemented Interfaces:
Serializable, IDLEntity
public class IdAssignmentPolicyValue
extends Object
implements IDLEntity

The IdAssignmentPolicyValue can have the following values. USER_ID - Objects created with that POA are assigned Object Ids only by the application. SYSTEM_ID - Objects created with that POA are assigned Object Ids only by the POA. If the POA also has the PERSISTENT policy, assigned Object Ids must be unique across all instantiations of the same POA.

Field Summary
static int | _SYSTEM_ID
static int | _USER_ID
static IdAssignmentPolicyValue | SYSTEM_ID
static IdAssignmentPolicyValue | USER_ID
Constructor Summary
protected IdAssignmentPolicyValue(int value)
Method Summary
static IdAssignmentPolicyValue | from_int(int value)
int | value()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_USER_ID

public static final int _USER_ID
See Also:
Constant Field Values

USER_ID

public static final IdAssignmentPolicyValue USER_ID

_SYSTEM_ID

public static final int _SYSTEM_ID
See Also:
Constant Field Values

SYSTEM_ID

public static final IdAssignmentPolicyValue SYSTEM_ID
Constructor Detail

IdAssignmentPolicyValue

protected IdAssignmentPolicyValue(int value)
Method Detail

value

public int value()

from_int

public static IdAssignmentPolicyValue from_int(int value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IdUniquenessPolicyOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface IdUniquenessPolicyOperations

All Superinterfaces:
PolicyOperations
All Known Subinterfaces:
IdUniquenessPolicy
public interface IdUniquenessPolicyOperations
extends PolicyOperations

The IdUniquenessPolicy specifies whether the servants activated in the created POA must have unique object i identities. The default is UNIQUE_ID.

Method Summary
 IdUniquenessPolicyValue value()
specifies the policy value
Methods inherited from interface org.omg.CORBA.PolicyOperations
copy, destroy, policy_type

Method Detail

value

IdUniquenessPolicyValue value()
specifies the policy value

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IdUniquenessPolicyValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class IdUniquenessPolicyValue

java.lang.Object
    extended by  org.omg.PortableServer.IdUniquenessPolicyValue
All Implemented Interfaces:
Serializable, IDLEntity
public class IdUniquenessPolicyValue
extends Object
implements IDLEntity

IdUniquenessPolicyValue can have the following values. UNIQUE_ID - Servants activated with that POA support exactly one Object Id. MULTIPLE_ID - a servant activated with that POA may support one or more Object Ids.

Field Summary
static int | _MULTIPLE_ID
static int | _UNIQUE_ID
static IdUniquenessPolicyValue | MULTIPLE_ID
static IdUniquenessPolicyValue | UNIQUE_ID
Constructor Summary
protected IdUniquenessPolicyValue(int value)
Method Summary
static IdUniquenessPolicyValue | from_int(int value)
int | value()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_UNIQUE_ID

public static final int _UNIQUE_ID
See Also:
Constant Field Values

UNIQUE_ID

public static final IdUniquenessPolicyValue UNIQUE_ID

_MULTIPLE_ID

public static final int _MULTIPLE_ID
See Also:
Constant Field Values

MULTIPLE_ID

public static final IdUniquenessPolicyValue MULTIPLE_ID
Constructor Detail

IdUniquenessPolicyValue

protected IdUniquenessPolicyValue(int value)
Method Detail

value

public int value()

from_int

public static IdUniquenessPolicyValue from_int(int value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ID_ASSIGNMENT_POLICY_ID

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface ID_ASSIGNMENT_POLICY_ID

public interface ID_ASSIGNMENT_POLICY_ID

org/omg/PortableServer/ID_ASSIGNMENT_POLICY_ID.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Field Summary
static int value
The value representing ID_ASSIGNMENT_POLICY_ID.

Field Detail

value

static final int value
The value representing ID_ASSIGNMENT_POLICY_ID.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ID_UNIQUENESS_POLICY_ID

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface ID_UNIQUENESS_POLICY_ID

public interface ID_UNIQUENESS_POLICY_ID

org/omg/PortableServer/ID_UNIQUENESS_POLICY_ID.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Field Summary
static int value
The value representing ID_UNIQUENESS_POLICY_ID.

Field Detail

value

static final int value
The value representing ID_UNIQUENESS_POLICY_ID.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ImplicitActivationPolicyOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface ImplicitActivationPolicyOperations

All Superinterfaces:
PolicyOperations
All Known Subinterfaces:
ImplicitActivationPolicy
public interface ImplicitActivationPolicyOperations
extends PolicyOperations

This policy specifies whether implicit activation of servants is supported in the created POA.

Method Summary
 ImplicitActivationPolicyValue value()
specifies the policy value
Methods inherited from interface org.omg.CORBA.PolicyOperations
copy, destroy, policy_type

Method Detail

value

ImplicitActivationPolicyValue value()
specifies the policy value

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ImplicitActivationPolicyValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class ImplicitActivationPolicyValue

java.lang.Object
    extended by  org.omg.PortableServer.ImplicitActivationPolicyValue
All Implemented Interfaces:
Serializable, IDLEntity
public class ImplicitActivationPolicyValue
extends Object
implements IDLEntity

ImplicitActivationPolicyValue has the following semantics. IMPLICIT_ACTIVATION to indicate implicit activation of servants. This requires SYSTEM_ID and RETAIN policies to be set. NO_IMPLICIT_ACTIVATION to indicate no implicit servant activation.

Field Summary
static int | _IMPLICIT_ACTIVATION
static int | _NO_IMPLICIT_ACTIVATION
static ImplicitActivationPolicyValue | IMPLICIT_ACTIVATION
static ImplicitActivationPolicyValue | NO_IMPLICIT_ACTIVATION
Constructor Summary
protected ImplicitActivationPolicyValue(int value)
Method Summary
static ImplicitActivationPolicyValue | from_int(int value)
int | value()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_IMPLICIT_ACTIVATION

public static final int _IMPLICIT_ACTIVATION
See Also:
Constant Field Values

IMPLICIT_ACTIVATION

public static final ImplicitActivationPolicyValue IMPLICIT_ACTIVATION

_NO_IMPLICIT_ACTIVATION

public static final int _NO_IMPLICIT_ACTIVATION
See Also:
Constant Field Values

NO_IMPLICIT_ACTIVATION

public static final ImplicitActivationPolicyValue NO_IMPLICIT_ACTIVATION
Constructor Detail

ImplicitActivationPolicyValue

protected ImplicitActivationPolicyValue(int value)
Method Detail

value

public int value()

from_int

public static ImplicitActivationPolicyValue from_int(int value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IMPLICIT_ACTIVATION_POLICY_ID

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface IMPLICIT_ACTIVATION_POLICY_ID

public interface IMPLICIT_ACTIVATION_POLICY_ID

org/omg/PortableServer/IMPLICIT_ACTIVATION_POLICY_ID.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Field Summary
static int value
The value representing IMPLICIT_ACTIVATION_POLICY_ID.

Field Detail

value

static final int value
The value representing IMPLICIT_ACTIVATION_POLICY_ID.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LifespanPolicyOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface LifespanPolicyOperations

All Superinterfaces:
PolicyOperations
All Known Subinterfaces:
LifespanPolicy
public interface LifespanPolicyOperations
extends PolicyOperations

The LifespanPolicy specifies the lifespan of the objects implemented in the created POA. The default is TRANSIENT.

Method Summary
 LifespanPolicyValue value()
specifies the policy value
Methods inherited from interface org.omg.CORBA.PolicyOperations
copy, destroy, policy_type

Method Detail

value

LifespanPolicyValue value()
specifies the policy value

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LifespanPolicyValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class LifespanPolicyValue

java.lang.Object
    extended by  org.omg.PortableServer.LifespanPolicyValue
All Implemented Interfaces:
Serializable, IDLEntity
public class LifespanPolicyValue
extends Object
implements IDLEntity

The LifespanPolicyValue can have the following values. TRANSIENT - The objects implemented in the POA cannot outlive the POA instance in which they are first created. PERSISTENT - The objects implemented in the POA can outlive the process in which they are first created.

Field Summary
static int | _PERSISTENT
static int | _TRANSIENT
static LifespanPolicyValue | PERSISTENT
static LifespanPolicyValue | TRANSIENT
Constructor Summary
protected LifespanPolicyValue(int value)
Method Summary
static LifespanPolicyValue | from_int(int value)
int | value()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_TRANSIENT

public static final int _TRANSIENT
See Also:
Constant Field Values

TRANSIENT

public static final LifespanPolicyValue TRANSIENT

_PERSISTENT

public static final int _PERSISTENT
See Also:
Constant Field Values

PERSISTENT

public static final LifespanPolicyValue PERSISTENT
Constructor Detail

LifespanPolicyValue

protected LifespanPolicyValue(int value)
Method Detail

value

public int value()

from_int

public static LifespanPolicyValue from_int(int value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LIFESPAN_POLICY_ID

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface LIFESPAN_POLICY_ID

public interface LIFESPAN_POLICY_ID

org/omg/PortableServer/LIFESPAN_POLICY_ID.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Field Summary
static int value
The value representing LIFESPAN_POLICY_ID.

Field Detail

value

static final int value
The value representing LIFESPAN_POLICY_ID.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


POAHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class POAHelper

java.lang.Object
    extended by  org.omg.PortableServer.POAHelper

public abstract class POAHelper
extends Object

A POA object manages the implementation of a collection of objects. The POA supports a name space for the objects, which are identified by Object Ids. A POA also provides a name space for POAs. A POA is created as a child of an existing POA, which forms a hierarchy starting with the root POA. A POA object must not be exported to other processes, or externalized with ORB::object_to_string.

Constructor Summary
POAHelper()
Method Summary
static POA | extract(Any a)
static String | id()
static void | insert(Any a, POA that)
static POA | narrow(Object obj)
static POA | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, POA value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

POAHelper

public POAHelper()
Method Detail

insert

public static void insert(Any a,
                          POA that)

extract

public static POA extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static POA read(InputStream istream)

write

public static void write(OutputStream ostream,
                         POA value)

narrow

public static POA narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


POAManagerOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface POAManagerOperations

All Known Subinterfaces:
POAManager
public interface POAManagerOperations

Each POA object has an associated POAManager object. A POA manager may be associated with one or more POA objects. A POA manager encapsulates the processing state of the POAs it is associated with.

Method Summary
void | activate() This operation changes the state of the POA manager to active, causing associated POAs to start processing requests.
void | deactivate(boolean etherealize_objects, boolean wait_for_completion) This operation changes the state of the POA manager to inactive, causing associated POAs to reject the requests that have not begun executing as well as as any new requests.
void | discard_requests(boolean wait_for_completion) This operation changes the state of the POA manager to discarding.
State | get_state() This operation returns the state of the POA manager.
void | hold_requests(boolean wait_for_completion) This operation changes the state of the POA manager to holding, causing associated POAs to queue incoming requests.

Method Detail

activate

void activate()
              throws AdapterInactive
This operation changes the state of the POA manager to active, causing associated POAs to start processing requests.

Throws:
AdapterInactive - is raised if the operation is invoked on the POAManager in inactive state.

hold_requests

void hold_requests(boolean wait_for_completion)
                   throws AdapterInactive
This operation changes the state of the POA manager to holding, causing associated POAs to queue incoming requests.

Parameters:
wait_for_completion - if FALSE, the operation returns immediately after changing state. If TRUE, it waits for all active requests to complete.
Throws:
AdapterInactive - is raised if the operation is invoked on the POAManager in inactive state.

discard_requests

void discard_requests(boolean wait_for_completion)
                      throws AdapterInactive
This operation changes the state of the POA manager to discarding. This causes associated POAs to discard incoming requests.

Parameters:
wait_for_completion - if FALSE, the operation returns immediately after changing state. If TRUE, it waits for all active requests to complete.
Throws:
AdapterInactive - is raised if the operation is invoked on the POAManager in inactive state.

deactivate

void deactivate(boolean etherealize_objects,
                boolean wait_for_completion)
                throws AdapterInactive
This operation changes the state of the POA manager to inactive, causing associated POAs to reject the requests that have not begun executing as well as as any new requests.

Parameters:
etherealize_objects - a flag to indicate whether to invoke the etherealize operation of the associated servant manager for all active objects.
wait_for_completion - if FALSE, the operation returns immediately after changing state. If TRUE, it waits for all active requests to complete.
Throws:
AdapterInactive - is raised if the operation is invoked on the POAManager in inactive state.

get_state

State get_state()
This operation returns the state of the POA manager.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


POAManagerPackage

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.PortableServer.POAManagerPackage

Encapsulates the processing state of the POAs it is associated with.

See:
Description

Class Summary
AdapterInactiveHelper | org/omg/PortableServer/POAManagerPackage/AdapterInactiveHelper.java .
State | Specifies the states for the POAManager

Exception Summary
AdapterInactive org/omg/PortableServer/POAManagerPackage/AdapterInactive.java .

Package org.omg.PortableServer.POAManagerPackage Description

Encapsulates the processing state of the POAs it is associated with. Each POA object has an associated POAManager object. A POA manager may be associated with one or more POA objects.

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6 ORB complies, see Official Specifications for CORBA support in Java[tm] SE 6.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.PortableServer.POAManagerPackage Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.PortableServer.POAManagerPackage

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.PortableServer.POAManagerPackage.AdapterInactiveHelper
    • org.omg.PortableServer.POAManagerPackage.State (implements org.omg.CORBA.portable.IDLEntity)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.omg.CORBA.UserException (implements org.omg.CORBA.portable.IDLEntity)
          • org.omg.PortableServer.POAManagerPackage.AdapterInactive
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.PortableServer.POAManagerPackage

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.PortableServer.POAManagerPackage

Packages that use org.omg.PortableServer.POAManagerPackage
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.POAManagerPackage | Encapsulates the processing state of the POAs it is associated with.

Classes in org.omg.PortableServer.POAManagerPackage used by org.omg.PortableServer
AdapterInactive
org/omg/PortableServer/POAManagerPackage/AdapterInactive.java .
State
Specifies the states for the POAManager

Classes in org.omg.PortableServer.POAManagerPackage used by org.omg.PortableServer.POAManagerPackage
AdapterInactive
org/omg/PortableServer/POAManagerPackage/AdapterInactive.java .
State
Specifies the states for the POAManager

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AdapterInactive

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAManagerPackage
Class AdapterInactive

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.PortableServer.POAManagerPackage.AdapterInactive
All Implemented Interfaces:
Serializable, IDLEntity
public final class AdapterInactive
extends UserException

org/omg/PortableServer/POAManagerPackage/AdapterInactive.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
AdapterInactive()
AdapterInactive(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AdapterInactive

public AdapterInactive()

AdapterInactive

public AdapterInactive(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AdapterInactiveHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAManagerPackage
Class AdapterInactiveHelper

java.lang.Object
    extended by  org.omg.PortableServer.POAManagerPackage.AdapterInactiveHelper

public abstract class AdapterInactiveHelper
extends Object

org/omg/PortableServer/POAManagerPackage/AdapterInactiveHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
AdapterInactiveHelper()
Method Summary
static AdapterInactive | extract(Any a)
static String | id()
static void | insert(Any a, AdapterInactive that)
static AdapterInactive | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, AdapterInactive value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AdapterInactiveHelper

public AdapterInactiveHelper()
Method Detail

insert

public static void insert(Any a,
                          AdapterInactive that)

extract

public static AdapterInactive extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static AdapterInactive read(InputStream istream)

write

public static void write(OutputStream ostream,
                         AdapterInactive value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class org.omg.PortableServer.POAManagerPackage.AdapterInactive

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAManagerPackage.AdapterInactive

Packages that use AdapterInactive
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.POAManagerPackage | Encapsulates the processing state of the POAs it is associated with.

Uses of AdapterInactive in org.omg.PortableServer

Methods in org.omg.PortableServer that throw AdapterInactive
void | POAManagerOperations.activate() This operation changes the state of the POA manager to active, causing associated POAs to start processing requests.
void | POAManagerOperations.deactivate(boolean etherealize_objects, boolean wait_for_completion) This operation changes the state of the POA manager to inactive, causing associated POAs to reject the requests that have not begun executing as well as as any new requests.
void | POAManagerOperations.discard_requests(boolean wait_for_completion) This operation changes the state of the POA manager to discarding.
void | POAManagerOperations.hold_requests(boolean wait_for_completion) This operation changes the state of the POA manager to holding, causing associated POAs to queue incoming requests.

Uses of AdapterInactive in org.omg.PortableServer.POAManagerPackage

Methods in org.omg.PortableServer.POAManagerPackage that return AdapterInactive
static AdapterInactive | AdapterInactiveHelper.extract(Any a)
static AdapterInactive | AdapterInactiveHelper.read(InputStream istream)

Methods in org.omg.PortableServer.POAManagerPackage with parameters of type AdapterInactive
static void | AdapterInactiveHelper.insert(Any a, AdapterInactive that)
static void | AdapterInactiveHelper.write(OutputStream ostream, AdapterInactive value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAManagerPackage.AdapterInactiveHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAManagerPackage.AdapterInactiveHelper

No usage of org.omg.PortableServer.POAManagerPackage.AdapterInactiveHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAManagerPackage.State

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAManagerPackage.State

Packages that use State
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.POAManagerPackage | Encapsulates the processing state of the POAs it is associated with.

Uses of State in org.omg.PortableServer

Methods in org.omg.PortableServer that return State
 State POAManagerOperations.get_state()
This operation returns the state of the POA manager.

Uses of State in org.omg.PortableServer.POAManagerPackage

Fields in org.omg.PortableServer.POAManagerPackage declared as State
static State | State.ACTIVE
static State | State.DISCARDING
static State | State.HOLDING
static State | State.INACTIVE

Methods in org.omg.PortableServer.POAManagerPackage that return State
static State State.from_int(int value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


State

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAManagerPackage
Class State

java.lang.Object
    extended by  org.omg.PortableServer.POAManagerPackage.State
All Implemented Interfaces:
Serializable, IDLEntity
public class State
extends Object
implements IDLEntity

Specifies the states for the POAManager

Field Summary
static int | _ACTIVE
static int | _DISCARDING
static int | _HOLDING
static int | _INACTIVE
static State | ACTIVE
static State | DISCARDING
static State | HOLDING
static State | INACTIVE
Constructor Summary
protected State(int value)
Method Summary
static State | from_int(int value)
int | value()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_HOLDING

public static final int _HOLDING
See Also:
Constant Field Values

HOLDING

public static final State HOLDING

_ACTIVE

public static final int _ACTIVE
See Also:
Constant Field Values

ACTIVE

public static final State ACTIVE

_DISCARDING

public static final int _DISCARDING
See Also:
Constant Field Values

DISCARDING

public static final State DISCARDING

_INACTIVE

public static final int _INACTIVE
See Also:
Constant Field Values

INACTIVE

public static final State INACTIVE
Constructor Detail

State

protected State(int value)
Method Detail

value

public int value()

from_int

public static State from_int(int value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


POAOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface POAOperations

All Known Subinterfaces:
POA
public interface POAOperations

A POA object manages the implementation of a collection of objects. The POA supports a name space for the objects, which are identified by Object Ids. A POA also provides a name space for POAs. A POA is created as a child of an existing POA, which forms a hierarchy starting with the root POA. A POA object must not be exported to other processes, or externalized with ORB::object_to_string.

Method Summary
void | activate_object_with_id(byte[] id, Servant p_servant) This operation enters an association between the specified Object Id and the specified servant in the Active Object Map.
byte[] | activate_object(Servant p_servant) This operation generates an Object Id and enters the Object Id and the specified servant in the Active Object Map.
IdAssignmentPolicy | create_id_assignment_policy(IdAssignmentPolicyValue value) These operations each return a reference to a policy object with the specified value.
IdUniquenessPolicy | create_id_uniqueness_policy(IdUniquenessPolicyValue value) These operations each return a reference to a policy object with the specified value.
ImplicitActivationPolicy | create_implicit_activation_policy(ImplicitActivationPolicyValue value) These operations each return a reference to a policy object with the specified value.
LifespanPolicy | create_lifespan_policy(LifespanPolicyValue value) These operations each return a reference to a policy object with the specified value.
POA | create_POA(String adapter_name, POAManager a_POAManager, Policy[] policies) This operation creates a new POA as a child of the target POA.
Object | create_reference_with_id(byte[] oid, String intf) This operation creates an object reference that encapsulates the specified Object Id and interface repository Id values.
Object | create_reference(String intf) This operation creates an object reference that encapsulates a POA-generated Object Id value and the specified interface repository id.
RequestProcessingPolicy | create_request_processing_policy(RequestProcessingPolicyValue value) These operations each return a reference to a policy object with the specified value.
ServantRetentionPolicy | create_servant_retention_policy(ServantRetentionPolicyValue value) These operations each return a reference to a policy object with the specified value.
ThreadPolicy | create_thread_policy(ThreadPolicyValue value) These operations each return a reference to a policy object with the specified value.
void | deactivate_object(byte[] oid) This operation causes the ObjectId specified in the oid parameter to be deactivated.
void | destroy(boolean etherealize_objects, boolean wait_for_completion) This operation destroys the POA and all descendant POAs.
POA | find_POA(String adapter_name, boolean activate_it) If the target POA is the parent of a child POA with the specified name (relative to the target POA), that child POA is returned.
ServantManager | get_servant_manager() If the ServantRetentionPolicy of the POA is RETAIN, then the ServantManager argument (imgr) shall support the ServantActivator interface.
Servant | get_servant() This operation returns the default servant associated with the POA.
Object | id_to_reference(byte[] oid) If an object with the specified Object Id value is currently active, a reference encapsulating the information used to activate the object is returned.
Servant | id_to_servant(byte[] oid) If the POA has the RETAIN policy and the specified ObjectId is in the Active Object Map, this operation returns the servant associated with that object in the Active Object Map.
byte[] | id() This returns the unique id of the POA in the process in which it is created.
byte[] | reference_to_id(Object reference) This operation returns the Object Id value encapsulated by the specified reference.
Servant | reference_to_servant(Object reference) If the POA has the RETAIN policy and the specified object is present in the Active Object Map, this operation returns the servant associated with that object in the Active Object Map.
byte[] | servant_to_id(Servant p_servant) This operation has four possible behaviors.
Object | servant_to_reference(Servant p_servant) This operation requires the RETAIN policy and either the UNIQUE_ID or IMPLICIT_ACTIVATION policies if invoked outside the context of an operation dispatched by this POA.
void | set_servant_manager(ServantManager imgr) This operation sets the default servant manager associated with the POA.
void | set_servant(Servant p_servant) This operation registers the specified servant with the POA as the default servant.
AdapterActivator | the_activator() This attribute identifies the adapter activator associated with the POA.
void | the_activator(AdapterActivator newThe_activator) This attribute identifies the adapter activator associated with the POA.
POA[] | the_children() This attribute identifies the current set of all child POAs of the POA.
String | the_name() This attribute identifies the POA relative to its parent.
POA | the_parent() This attribute identifies the parent of the POA.
POAManager | the_POAManager() This attribute identifies the POA manager associated with the POA.

Method Detail

create_POA

POA create_POA(String adapter_name,
               POAManager a_POAManager,
               Policy[] policies)
               throws AdapterAlreadyExists,
                      InvalidPolicy
This operation creates a new POA as a child of the target POA.

Parameters:
adapter_name - identifies the new POA with respect to other POAs with the same parent POA.
a_POAManager - specifies the POA Manager to be associated with the new POA.
policies - specifies policy objects to be associated with the POA to control its behavior.
Throws:
AdapterAlreadyExists - specifies that the target POA already has a child POA with the specified name.
InvalidPolicy - is raised if any of the policy objects are not valid for the ORB, or are in conflict, or require an administrative action that has not been performed.

find_POA

POA find_POA(String adapter_name,
             boolean activate_it)
             throws AdapterNonExistent
If the target POA is the parent of a child POA with the specified name (relative to the target POA), that child POA is returned.

Parameters:
adapter_name - POA name to be found.
activate_it - if a POA with the specified name does not exist and the value of the activate_it parameter is TRUE, the target POA's AdapterActivator, if one exists, is invoked.
Returns:
POA if one exists or is activated by the AdapterActivator.
Throws:
AdapterNonExistent

destroy

void destroy(boolean etherealize_objects,
             boolean wait_for_completion)
This operation destroys the POA and all descendant POAs. All descendant POAs are destroyed (recursively) before the destruction of the containing POA. The POA so destroyed (that is, the POA with its name) may be re-created later in the same process.

Parameters:
etherealize_objects - flag to indicate whether etherealize operation on servant manager needs to be called.
wait_for_completion - flag to indicate whether POA and its children need to wait for active requests and the etherealization to complete.

create_thread_policy

ThreadPolicy create_thread_policy(ThreadPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Parameters:
value - policy type
Returns:
ThreadPolcy Object

create_lifespan_policy

LifespanPolicy create_lifespan_policy(LifespanPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Parameters:
value - policy type
Returns:
LifespanPolicy Object.

create_id_uniqueness_policy

IdUniquenessPolicy create_id_uniqueness_policy(IdUniquenessPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Parameters:
value - policy type
Returns:
IdUniquenessPolicy Object.

create_id_assignment_policy

IdAssignmentPolicy create_id_assignment_policy(IdAssignmentPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Parameters:
value - policy type
Returns:
IdAssignmentPolicy Object.

create_implicit_activation_policy

ImplicitActivationPolicy create_implicit_activation_policy(ImplicitActivationPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Parameters:
value - policy type
Returns:
ImplicitActivationPolicy Object.

create_servant_retention_policy

ServantRetentionPolicy create_servant_retention_policy(ServantRetentionPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Parameters:
value - policy type
Returns:
ServantRetentionPolicy Object.

create_request_processing_policy

RequestProcessingPolicy create_request_processing_policy(RequestProcessingPolicyValue value)
These operations each return a reference to a policy object with the specified value.

Parameters:
value - policy type
Returns:
RequestProcessingPolicy Object.

the_name

String the_name()
This attribute identifies the POA relative to its parent. This name is assigned when the POA is created.

the_parent

POA the_parent()
This attribute identifies the parent of the POA. The parent of the root POA is null.

the_children

POA[] the_children()
This attribute identifies the current set of all child POAs of the POA. The set of child POAs includes only the POA's immediate children, and not their descendants.

the_POAManager

POAManager the_POAManager()
This attribute identifies the POA manager associated with the POA.

the_activator

AdapterActivator the_activator()
This attribute identifies the adapter activator associated with the POA.

the_activator

void the_activator(AdapterActivator newThe_activator)
This attribute identifies the adapter activator associated with the POA.

get_servant_manager

ServantManager get_servant_manager()
                                   throws WrongPolicy
If the ServantRetentionPolicy of the POA is RETAIN, then the ServantManager argument (imgr) shall support the ServantActivator interface. For a NON_RETAIN policy, the ServantManager shall support the ServantLocator interface. If the argument is nil, or does not support the required interface, then the OBJ_ADAPTER exception is raised.

Returns:
ServantManager associated with a POA or null if none exists.
Throws:
WrongPolicy - raised if the USE_SERVANT_MANAGER policy is not specified.

set_servant_manager

void set_servant_manager(ServantManager imgr)
                         throws WrongPolicy
This operation sets the default servant manager associated with the POA. This operation may only be invoked once after a POA has been created. Attempting to set the servant manager after one has already been set will result in the BAD_INV_ORDER exception being raised.

Parameters:
imgr - servant manager to be used as a default.
Throws:
WrongPolicy - raised if the USE_SERVANT_MANAGER policy is not specified.

get_servant

Servant get_servant()
                    throws NoServant,
                           WrongPolicy
This operation returns the default servant associated with the POA.

Returns:
p_servant default servant associated with a POA.
Throws:
NoServant - raised if no default servant is associated with the POA.
WrongPolicy - raised if the USE_DEFAULT_SERVANT policy is not specified.

set_servant

void set_servant(Servant p_servant)
                 throws WrongPolicy
This operation registers the specified servant with the POA as the default servant. This servant will be used for all requests for which no servant is found in the Active Object Map.

Parameters:
p_servant - servant to be used as a default.
Throws:
WrongPolicy - raised if the USE_DEFAULT_SERVANT policy is not specified.

activate_object

byte[] activate_object(Servant p_servant)
                       throws ServantAlreadyActive,
                              WrongPolicy
This operation generates an Object Id and enters the Object Id and the specified servant in the Active Object Map.

Parameters:
p_servant - servant to be associated with an object to be activated.
Returns:
POA generated object id.
Throws:
ServantAlreadyActive - is raised if the POA has UNIQUE_ID policy and servant is is already in the Active Object Map.
WrongPolicy - raised if the SYSTEM_ID and RETAIN policies are not specified.

activate_object_with_id

void activate_object_with_id(byte[] id,
                             Servant p_servant)
                             throws ServantAlreadyActive,
                                    ObjectAlreadyActive,
                                    WrongPolicy
This operation enters an association between the specified Object Id and the specified servant in the Active Object Map.

Parameters:
id - object id for the object to be activated.
p_servant - servant to be associated with the object.
Throws:
ServantAlreadyActive - raised if the POA has the UNIQUE_ID policy and the servant is already in the Active Object Map.
ObjectAlreadyActive - raised if the object is already active in the POA.
WrongPolicy - raised if the RETAIN policy is is not specified.

deactivate_object

void deactivate_object(byte[] oid)
                       throws ObjectNotActive,
                              WrongPolicy
This operation causes the ObjectId specified in the oid parameter to be deactivated. An ObjectId which has been deactivated continues to process requests until there are no active requests for that ObjectId. A deactivated ObjectId is removed from the Active Object Map when all requests executing for that ObjectId have completed.

Parameters:
oid - Object Id for the object to be deactivated.
Throws:
ObjectNotActive - if the object with the specified oid is not in the Active Object Map.
WrongPolicy - raised if the RETAIN policy is is not specified.

create_reference

Object create_reference(String intf)
                        throws WrongPolicy
This operation creates an object reference that encapsulates a POA-generated Object Id value and the specified interface repository id.

Parameters:
intf - rep id for creating an object reference.
Returns:
object reference created using intf.
Throws:
WrongPolicy - if SYSTEM_ID policy is not specified.

create_reference_with_id

Object create_reference_with_id(byte[] oid,
                                String intf)
This operation creates an object reference that encapsulates the specified Object Id and interface repository Id values. It does not cause an activation to take place. The resulting reference may be passed to clients, so that subsequent requests on those references will cause the object to be activated if necessary, or the default servant used, depending on the applicable policies.

Parameters:
oid - object id for creating an objref
intf - rep id for creating an objref
Returns:
object reference created using oid and intf
Throws:
BAD_PARAM - is raised if the POA has the SYSTEM_ID policy and it detects that the Object Id value was not generated by the system or for this POA.

servant_to_id

byte[] servant_to_id(Servant p_servant)
                     throws ServantNotActive,
                            WrongPolicy
This operation has four possible behaviors. 1. If the POA has the UNIQUE_ID policy and the specified servant is active, the Object Id associated with that servant is returned. 2. If the POA has the IMPLICIT_ACTIVATION policy and either the POA has the MULTIPLE_ID policy or the specified servant is not active, the servant is activated using a POA-generated Object Id and the Interface Id associated with the servant, and that Object Id is returned. 3. If the POA has the USE_DEFAULT_SERVANT policy, the servant specified is the default servant, and the operation is being invoked in the context of executing a request on the default servant, then the ObjectId associated with the current invocation is returned. 4. Otherwise, the ServantNotActive exception is raised.

Parameters:
p_servant - servant for which the object disi returned.
Returns:
object id associated with the servant.
Throws:
ServantNotActive - if the above rules and policy combination is not met.
WrongPolicy - if the USE_DEFAULT_SERVANT policy or a combination of the RETAIN policy and either the UNIQUE_ID or IMPLICIT_ACTIVATION policies are not present.

servant_to_reference

Object servant_to_reference(Servant p_servant)
                            throws ServantNotActive,
                                   WrongPolicy
This operation requires the RETAIN policy and either the UNIQUE_ID or IMPLICIT_ACTIVATION policies if invoked outside the context of an operation dispatched by this POA. It has four possible behaviors. 1. If the POA has both the RETAIN and the UNIQUE_ID policy and the specified servant is active, an object reference encapsulating the information used to activate the servant is returned. 2. If the POA has both the RETAIN and the IMPLICIT_ACTIVATION policy and either the POA has the MULTIPLE_ID policy or the specified servant is not active, the servant is activated using a POA-generated Object Id and the Interface Id associated with the servant, and a corresponding object reference is returned. 3. If the operation was invoked in the context of executing a request on the specified servant, the reference associated with the current invocation is returned. 4. Otherwise, the ServantNotActive exception is raised.

Parameters:
p_servant - servant for which the object reference needs to be obtained.
Returns:
object reference associated with the servant.
Throws:
WrongPolicy - if the operation is not invoked in the context of executing a request on the specified servant and the required policies are not present.
ServantNotActive - if the above specified policies and rules are not met.

reference_to_servant

Servant reference_to_servant(Object reference)
                             throws ObjectNotActive,
                                    WrongPolicy,
                                    WrongAdapter
If the POA has the RETAIN policy and the specified object is present in the Active Object Map, this operation returns the servant associated with that object in the Active Object Map. Otherwise, if the POA has the USE_DEFAULT_SERVANT policy and a default servant has been registered with the POA, this operation returns the default servant. If the object reference was not created by this POA, the WrongAdapter exception is raised. (OMG Issue on inconsistency with the POA.IDL.

Parameters:
reference - object reference for which the servant is returned.
Returns:
servant associated with the reference.
Throws:
WrongPolicy - if neither the RETAIN policy or the USE_DEFAULT_SERVANT policy is present.
ObjectNotActive - if the servant is not present in the Active Object Map (for RETAIN) or no default servant is registered (for USE_DEFAULT_POLICY).
WrongAdapter - if reference was not created by this POA instance.

reference_to_id

byte[] reference_to_id(Object reference)
                       throws WrongAdapter,
                              WrongPolicy
This operation returns the Object Id value encapsulated by the specified reference. This operation is valid only if the reference was created by the POA on which the operation is being performed. The object denoted by the reference does not have to be active for this operation to succeed.

Parameters:
reference - the object reference from which the object id needs to be returned.
Returns:
object id encapsulated in the reference.
Throws:
WrongAdapter - if the reference was not created by the POA specified in the reference.
WrongPolicy - declared to allow future extensions.

id_to_servant

Servant id_to_servant(byte[] oid)
                      throws ObjectNotActive,
                             WrongPolicy
If the POA has the RETAIN policy and the specified ObjectId is in the Active Object Map, this operation returns the servant associated with that object in the Active Object Map. Otherwise, if the POA has the USE_DEFAULT_SERVANT policy and a default servant has been registered with the POA, this operation returns the default servant.

Parameters:
oid - object id for the which the servant is returned.
Returns:
servant associated with oid.
Throws:
ObjectNotActive - is raised if ObjectId is is not in the Active Object Map (for RETAIN policy), or no default servant is registered (for USE_DEFAULT_SERVANT policy).
WrongPolicy - is raised if the RETAIN policy or the USE_DEFAULT_SERVANT policy is not present.

id_to_reference

Object id_to_reference(byte[] oid)
                       throws ObjectNotActive,
                              WrongPolicy
If an object with the specified Object Id value is currently active, a reference encapsulating the information used to activate the object is returned.

Parameters:
oid - id of the object for which the reference is returned.
Returns:
the object reference
Throws:
ObjectNotActive - if the Object Id value is not active in the POA.
WrongPolicy - if the RETAIN policy is not present.

id

byte[] id()
This returns the unique id of the POA in the process in which it is created. It is for use by portable interceptors.

This id is guaranteed unique for the life span of the POA in the process. For persistent POAs, this means that if a POA is created in the same path with the same name as another POA, these POAs are identical and, therefore, have the same id. For transient POAs, each POA is unique.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


POAPackage

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.PortableServer.POAPackage

Allows programmers to construct object implementations that are portable between different ORB products.

See:
Description

Class Summary
AdapterAlreadyExistsHelper | org/omg/PortableServer/POAPackage/AdapterAlreadyExistsHelper.java .
AdapterNonExistentHelper | org/omg/PortableServer/POAPackage/AdapterNonExistentHelper.java .
InvalidPolicyHelper | org/omg/PortableServer/POAPackage/InvalidPolicyHelper.java .
NoServantHelper | org/omg/PortableServer/POAPackage/NoServantHelper.java .
ObjectAlreadyActiveHelper | org/omg/PortableServer/POAPackage/ObjectAlreadyActiveHelper.java .
ObjectNotActiveHelper | org/omg/PortableServer/POAPackage/ObjectNotActiveHelper.java .
ServantAlreadyActiveHelper | org/omg/PortableServer/POAPackage/ServantAlreadyActiveHelper.java .
ServantNotActiveHelper | org/omg/PortableServer/POAPackage/ServantNotActiveHelper.java .
WrongAdapterHelper | org/omg/PortableServer/POAPackage/WrongAdapterHelper.java .
WrongPolicyHelper | org/omg/PortableServer/POAPackage/WrongPolicyHelper.java .

Exception Summary
AdapterAlreadyExists | org/omg/PortableServer/POAPackage/AdapterAlreadyExists.java .
AdapterNonExistent | org/omg/PortableServer/POAPackage/AdapterNonExistent.java .
InvalidPolicy | org/omg/PortableServer/POAPackage/InvalidPolicy.java .
NoServant | org/omg/PortableServer/POAPackage/NoServant.java .
ObjectAlreadyActive | org/omg/PortableServer/POAPackage/ObjectAlreadyActive.java .
ObjectNotActive | org/omg/PortableServer/POAPackage/ObjectNotActive.java .
ServantAlreadyActive | org/omg/PortableServer/POAPackage/ServantAlreadyActive.java .
ServantNotActive | org/omg/PortableServer/POAPackage/ServantNotActive.java .
WrongAdapter | org/omg/PortableServer/POAPackage/WrongAdapter.java .
WrongPolicy | org/omg/PortableServer/POAPackage/WrongPolicy.java .

Package org.omg.PortableServer.POAPackage Description

Allows programmers to construct object implementations that are portable between different ORB products.

The Portable Object Adaptor (POA) is designed to meet the following goals:

  • Allow programmers to construct object implementations that are portable between different ORB products.
  • Provide support for objects with persistent identities.
  • Provide support for transparent activation of objects.
  • Allow a single servant to support multiple object identities simultaneously.

Given an interface My defined in My.idl, the file MyPOA.java is generated by the idlj compiler. You must provide the implementation for My and it must inherit from MyPOA.

MyPOA.java is a stream-based skeleton that extends org.omg.PortableServer.Servant and implements the InvokeHandler interface and the operations interface associated with the IDL interface the skeleton implements.

The PortableServer module for the Portable Object Adapter (POA) defines the native Servant type. In the Java programming language, the Servant type is mapped to the Java org.omg.PortableServer.Servant class. It serves as the base class for all POA servant implementations and provides a number of methods that may be invoked by the application programmer, as well as methods which are invoked by the POA itself and may be overridden by the user to control aspects of servant behavior.

All Mapping corresponds to the Chapter 11 of CORBA V2.3.1 specified by OMG document formal/99-10-07.pdf. The exception to this is the id attribute, which is added in ptc/00-08-06, section 11.3.8.26.

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6, ORB complies, see Official Specifications for CORBA support in Java[tm] SE 6.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.PortableServer.POAPackage Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.PortableServer.POAPackage

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.PortableServer.POAPackage.AdapterAlreadyExistsHelper
    • org.omg.PortableServer.POAPackage.AdapterNonExistentHelper
    • org.omg.PortableServer.POAPackage.InvalidPolicyHelper
    • org.omg.PortableServer.POAPackage.NoServantHelper
    • org.omg.PortableServer.POAPackage.ObjectAlreadyActiveHelper
    • org.omg.PortableServer.POAPackage.ObjectNotActiveHelper
    • org.omg.PortableServer.POAPackage.ServantAlreadyActiveHelper
    • org.omg.PortableServer.POAPackage.ServantNotActiveHelper
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.omg.CORBA.UserException (implements org.omg.CORBA.portable.IDLEntity)
          • org.omg.PortableServer.POAPackage.AdapterAlreadyExists
          • org.omg.PortableServer.POAPackage.AdapterNonExistent
          • org.omg.PortableServer.POAPackage.InvalidPolicy
          • org.omg.PortableServer.POAPackage.NoServant
          • org.omg.PortableServer.POAPackage.ObjectAlreadyActive
          • org.omg.PortableServer.POAPackage.ObjectNotActive
          • org.omg.PortableServer.POAPackage.ServantAlreadyActive
          • org.omg.PortableServer.POAPackage.ServantNotActive
          • org.omg.PortableServer.POAPackage.WrongAdapter
          • org.omg.PortableServer.POAPackage.WrongPolicy
    • org.omg.PortableServer.POAPackage.WrongAdapterHelper
    • org.omg.PortableServer.POAPackage.WrongPolicyHelper
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.PortableServer.POAPackage

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.PortableServer.POAPackage

Packages that use org.omg.PortableServer.POAPackage
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.

Classes in org.omg.PortableServer.POAPackage used by org.omg.PortableServer
AdapterAlreadyExists
org/omg/PortableServer/POAPackage/AdapterAlreadyExists.java .
AdapterNonExistent
org/omg/PortableServer/POAPackage/AdapterNonExistent.java .
InvalidPolicy
org/omg/PortableServer/POAPackage/InvalidPolicy.java .
NoServant
org/omg/PortableServer/POAPackage/NoServant.java .
ObjectAlreadyActive
org/omg/PortableServer/POAPackage/ObjectAlreadyActive.java .
ObjectNotActive
org/omg/PortableServer/POAPackage/ObjectNotActive.java .
ServantAlreadyActive
org/omg/PortableServer/POAPackage/ServantAlreadyActive.java .
ServantNotActive
org/omg/PortableServer/POAPackage/ServantNotActive.java .
WrongAdapter
org/omg/PortableServer/POAPackage/WrongAdapter.java .
WrongPolicy
org/omg/PortableServer/POAPackage/WrongPolicy.java .

Classes in org.omg.PortableServer.POAPackage used by org.omg.PortableServer.POAPackage
AdapterAlreadyExists
org/omg/PortableServer/POAPackage/AdapterAlreadyExists.java .
AdapterNonExistent
org/omg/PortableServer/POAPackage/AdapterNonExistent.java .
InvalidPolicy
org/omg/PortableServer/POAPackage/InvalidPolicy.java .
NoServant
org/omg/PortableServer/POAPackage/NoServant.java .
ObjectAlreadyActive
org/omg/PortableServer/POAPackage/ObjectAlreadyActive.java .
ObjectNotActive
org/omg/PortableServer/POAPackage/ObjectNotActive.java .
ServantAlreadyActive
org/omg/PortableServer/POAPackage/ServantAlreadyActive.java .
ServantNotActive
org/omg/PortableServer/POAPackage/ServantNotActive.java .
WrongAdapter
org/omg/PortableServer/POAPackage/WrongAdapter.java .
WrongPolicy
org/omg/PortableServer/POAPackage/WrongPolicy.java .

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AdapterAlreadyExists

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class AdapterAlreadyExists

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.PortableServer.POAPackage.AdapterAlreadyExists
All Implemented Interfaces:
Serializable, IDLEntity
public final class AdapterAlreadyExists
extends UserException

org/omg/PortableServer/POAPackage/AdapterAlreadyExists.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
AdapterAlreadyExists()
AdapterAlreadyExists(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AdapterAlreadyExists

public AdapterAlreadyExists()

AdapterAlreadyExists

public AdapterAlreadyExists(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AdapterAlreadyExistsHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class AdapterAlreadyExistsHelper

java.lang.Object
    extended by  org.omg.PortableServer.POAPackage.AdapterAlreadyExistsHelper

public abstract class AdapterAlreadyExistsHelper
extends Object

org/omg/PortableServer/POAPackage/AdapterAlreadyExistsHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
AdapterAlreadyExistsHelper()
Method Summary
static AdapterAlreadyExists | extract(Any a)
static String | id()
static void | insert(Any a, AdapterAlreadyExists that)
static AdapterAlreadyExists | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, AdapterAlreadyExists value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AdapterAlreadyExistsHelper

public AdapterAlreadyExistsHelper()
Method Detail

insert

public static void insert(Any a,
                          AdapterAlreadyExists that)

extract

public static AdapterAlreadyExists extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static AdapterAlreadyExists read(InputStream istream)

write

public static void write(OutputStream ostream,
                         AdapterAlreadyExists value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AdapterNonExistent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class AdapterNonExistent

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.PortableServer.POAPackage.AdapterNonExistent
All Implemented Interfaces:
Serializable, IDLEntity
public final class AdapterNonExistent
extends UserException

org/omg/PortableServer/POAPackage/AdapterNonExistent.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
AdapterNonExistent()
AdapterNonExistent(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AdapterNonExistent

public AdapterNonExistent()

AdapterNonExistent

public AdapterNonExistent(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AdapterNonExistentHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class AdapterNonExistentHelper

java.lang.Object
    extended by  org.omg.PortableServer.POAPackage.AdapterNonExistentHelper

public abstract class AdapterNonExistentHelper
extends Object

org/omg/PortableServer/POAPackage/AdapterNonExistentHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
AdapterNonExistentHelper()
Method Summary
static AdapterNonExistent | extract(Any a)
static String | id()
static void | insert(Any a, AdapterNonExistent that)
static AdapterNonExistent | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, AdapterNonExistent value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AdapterNonExistentHelper

public AdapterNonExistentHelper()
Method Detail

insert

public static void insert(Any a,
                          AdapterNonExistent that)

extract

public static AdapterNonExistent extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static AdapterNonExistent read(InputStream istream)

write

public static void write(OutputStream ostream,
                         AdapterNonExistent value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class org.omg.PortableServer.POAPackage.AdapterAlreadyExists

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.AdapterAlreadyExists

Packages that use AdapterAlreadyExists
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.

Uses of AdapterAlreadyExists in org.omg.PortableServer

Methods in org.omg.PortableServer that throw AdapterAlreadyExists
 POA POAOperations.create_POA(String adapter_name, POAManager a_POAManager, Policy[] policies)
This operation creates a new POA as a child of the target POA.

Uses of AdapterAlreadyExists in org.omg.PortableServer.POAPackage

Methods in org.omg.PortableServer.POAPackage that return AdapterAlreadyExists
static AdapterAlreadyExists | AdapterAlreadyExistsHelper.extract(Any a)
static AdapterAlreadyExists | AdapterAlreadyExistsHelper.read(InputStream istream)

Methods in org.omg.PortableServer.POAPackage with parameters of type AdapterAlreadyExists
static void | AdapterAlreadyExistsHelper.insert(Any a, AdapterAlreadyExists that)
static void | AdapterAlreadyExistsHelper.write(OutputStream ostream, AdapterAlreadyExists value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.AdapterAlreadyExistsHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.AdapterAlreadyExistsHelper

No usage of org.omg.PortableServer.POAPackage.AdapterAlreadyExistsHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.AdapterNonExistent

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.AdapterNonExistent

Packages that use AdapterNonExistent
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.

Uses of AdapterNonExistent in org.omg.PortableServer

Methods in org.omg.PortableServer that throw AdapterNonExistent
 POA POAOperations.find_POA(String adapter_name, boolean activate_it)
If the target POA is the parent of a child POA with the specified name (relative to the target POA), that child POA is returned.

Uses of AdapterNonExistent in org.omg.PortableServer.POAPackage

Methods in org.omg.PortableServer.POAPackage that return AdapterNonExistent
static AdapterNonExistent | AdapterNonExistentHelper.extract(Any a)
static AdapterNonExistent | AdapterNonExistentHelper.read(InputStream istream)

Methods in org.omg.PortableServer.POAPackage with parameters of type AdapterNonExistent
static void | AdapterNonExistentHelper.insert(Any a, AdapterNonExistent that)
static void | AdapterNonExistentHelper.write(OutputStream ostream, AdapterNonExistent value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.AdapterNonExistentHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.AdapterNonExistentHelper

No usage of org.omg.PortableServer.POAPackage.AdapterNonExistentHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.InvalidPolicy

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.InvalidPolicy

Packages that use InvalidPolicy
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.

Uses of InvalidPolicy in org.omg.PortableServer

Methods in org.omg.PortableServer that throw InvalidPolicy
 POA POAOperations.create_POA(String adapter_name, POAManager a_POAManager, Policy[] policies)
This operation creates a new POA as a child of the target POA.

Uses of InvalidPolicy in org.omg.PortableServer.POAPackage

Methods in org.omg.PortableServer.POAPackage that return InvalidPolicy
static InvalidPolicy | InvalidPolicyHelper.extract(Any a)
static InvalidPolicy | InvalidPolicyHelper.read(InputStream istream)

Methods in org.omg.PortableServer.POAPackage with parameters of type InvalidPolicy
static void | InvalidPolicyHelper.insert(Any a, InvalidPolicy that)
static void | InvalidPolicyHelper.write(OutputStream ostream, InvalidPolicy value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.InvalidPolicyHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.InvalidPolicyHelper

No usage of org.omg.PortableServer.POAPackage.InvalidPolicyHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.NoServant

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.NoServant

Packages that use NoServant
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.

Uses of NoServant in org.omg.PortableServer

Methods in org.omg.PortableServer that throw NoServant
 Servant POAOperations.get_servant()
This operation returns the default servant associated with the POA.

Uses of NoServant in org.omg.PortableServer.POAPackage

Methods in org.omg.PortableServer.POAPackage that return NoServant
static NoServant | NoServantHelper.extract(Any a)
static NoServant | NoServantHelper.read(InputStream istream)

Methods in org.omg.PortableServer.POAPackage with parameters of type NoServant
static void | NoServantHelper.insert(Any a, NoServant that)
static void | NoServantHelper.write(OutputStream ostream, NoServant value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.NoServantHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.NoServantHelper

No usage of org.omg.PortableServer.POAPackage.NoServantHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.ObjectAlreadyActive

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.ObjectAlreadyActive

Packages that use ObjectAlreadyActive
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.

Uses of ObjectAlreadyActive in org.omg.PortableServer

Methods in org.omg.PortableServer that throw ObjectAlreadyActive
 void POAOperations.activate_object_with_id(byte[] id, Servant p_servant)
This operation enters an association between the specified Object Id and the specified servant in the Active Object Map.

Uses of ObjectAlreadyActive in org.omg.PortableServer.POAPackage

Methods in org.omg.PortableServer.POAPackage that return ObjectAlreadyActive
static ObjectAlreadyActive | ObjectAlreadyActiveHelper.extract(Any a)
static ObjectAlreadyActive | ObjectAlreadyActiveHelper.read(InputStream istream)

Methods in org.omg.PortableServer.POAPackage with parameters of type ObjectAlreadyActive
static void | ObjectAlreadyActiveHelper.insert(Any a, ObjectAlreadyActive that)
static void | ObjectAlreadyActiveHelper.write(OutputStream ostream, ObjectAlreadyActive value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.ObjectAlreadyActiveHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.ObjectAlreadyActiveHelper

No usage of org.omg.PortableServer.POAPackage.ObjectAlreadyActiveHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.ObjectNotActive

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.ObjectNotActive

Packages that use ObjectNotActive
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.

Uses of ObjectNotActive in org.omg.PortableServer

Methods in org.omg.PortableServer that throw ObjectNotActive
void | POAOperations.deactivate_object(byte[] oid) This operation causes the ObjectId specified in the oid parameter to be deactivated.
Object | POAOperations.id_to_reference(byte[] oid) If an object with the specified Object Id value is currently active, a reference encapsulating the information used to activate the object is returned.
Servant | POAOperations.id_to_servant(byte[] oid) If the POA has the RETAIN policy and the specified ObjectId is in the Active Object Map, this operation returns the servant associated with that object in the Active Object Map.
Servant | POAOperations.reference_to_servant(Object reference) If the POA has the RETAIN policy and the specified object is present in the Active Object Map, this operation returns the servant associated with that object in the Active Object Map.

Uses of ObjectNotActive in org.omg.PortableServer.POAPackage

Methods in org.omg.PortableServer.POAPackage that return ObjectNotActive
static ObjectNotActive | ObjectNotActiveHelper.extract(Any a)
static ObjectNotActive | ObjectNotActiveHelper.read(InputStream istream)

Methods in org.omg.PortableServer.POAPackage with parameters of type ObjectNotActive
static void | ObjectNotActiveHelper.insert(Any a, ObjectNotActive that)
static void | ObjectNotActiveHelper.write(OutputStream ostream, ObjectNotActive value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.ObjectNotActiveHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.ObjectNotActiveHelper

No usage of org.omg.PortableServer.POAPackage.ObjectNotActiveHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.ServantAlreadyActive

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.ServantAlreadyActive

Packages that use ServantAlreadyActive
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.

Uses of ServantAlreadyActive in org.omg.PortableServer

Methods in org.omg.PortableServer that throw ServantAlreadyActive
void | POAOperations.activate_object_with_id(byte[] id, Servant p_servant) This operation enters an association between the specified Object Id and the specified servant in the Active Object Map.
byte[] | POAOperations.activate_object(Servant p_servant) This operation generates an Object Id and enters the Object Id and the specified servant in the Active Object Map.

Uses of ServantAlreadyActive in org.omg.PortableServer.POAPackage

Methods in org.omg.PortableServer.POAPackage that return ServantAlreadyActive
static ServantAlreadyActive | ServantAlreadyActiveHelper.extract(Any a)
static ServantAlreadyActive | ServantAlreadyActiveHelper.read(InputStream istream)

Methods in org.omg.PortableServer.POAPackage with parameters of type ServantAlreadyActive
static void | ServantAlreadyActiveHelper.insert(Any a, ServantAlreadyActive that)
static void | ServantAlreadyActiveHelper.write(OutputStream ostream, ServantAlreadyActive value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.ServantAlreadyActiveHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.ServantAlreadyActiveHelper

No usage of org.omg.PortableServer.POAPackage.ServantAlreadyActiveHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.ServantNotActive

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.ServantNotActive

Packages that use ServantNotActive
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.

Uses of ServantNotActive in org.omg.PortableServer

Methods in org.omg.PortableServer that throw ServantNotActive
byte[] | POAOperations.servant_to_id(Servant p_servant) This operation has four possible behaviors.
Object | POAOperations.servant_to_reference(Servant p_servant) This operation requires the RETAIN policy and either the UNIQUE_ID or IMPLICIT_ACTIVATION policies if invoked outside the context of an operation dispatched by this POA.

Uses of ServantNotActive in org.omg.PortableServer.POAPackage

Methods in org.omg.PortableServer.POAPackage that return ServantNotActive
static ServantNotActive | ServantNotActiveHelper.extract(Any a)
static ServantNotActive | ServantNotActiveHelper.read(InputStream istream)

Methods in org.omg.PortableServer.POAPackage with parameters of type ServantNotActive
static void | ServantNotActiveHelper.insert(Any a, ServantNotActive that)
static void | ServantNotActiveHelper.write(OutputStream ostream, ServantNotActive value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.ServantNotActiveHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.ServantNotActiveHelper

No usage of org.omg.PortableServer.POAPackage.ServantNotActiveHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.WrongAdapter

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.WrongAdapter

Packages that use WrongAdapter
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.

Uses of WrongAdapter in org.omg.PortableServer

Methods in org.omg.PortableServer that throw WrongAdapter
byte[] | POAOperations.reference_to_id(Object reference) This operation returns the Object Id value encapsulated by the specified reference.
Servant | POAOperations.reference_to_servant(Object reference) If the POA has the RETAIN policy and the specified object is present in the Active Object Map, this operation returns the servant associated with that object in the Active Object Map.

Uses of WrongAdapter in org.omg.PortableServer.POAPackage

Methods in org.omg.PortableServer.POAPackage that return WrongAdapter
static WrongAdapter | WrongAdapterHelper.extract(Any a)
static WrongAdapter | WrongAdapterHelper.read(InputStream istream)

Methods in org.omg.PortableServer.POAPackage with parameters of type WrongAdapter
static void | WrongAdapterHelper.insert(Any a, WrongAdapter that)
static void | WrongAdapterHelper.write(OutputStream ostream, WrongAdapter value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.WrongAdapterHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.WrongAdapterHelper

No usage of org.omg.PortableServer.POAPackage.WrongAdapterHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.WrongPolicy

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.WrongPolicy

Packages that use WrongPolicy
org.omg.PortableServer | Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.
org.omg.PortableServer.POAPackage | Allows programmers to construct object implementations that are portable between different ORB products.

Uses of WrongPolicy in org.omg.PortableServer

Methods in org.omg.PortableServer that throw WrongPolicy
void | POAOperations.activate_object_with_id(byte[] id, Servant p_servant) This operation enters an association between the specified Object Id and the specified servant in the Active Object Map.
byte[] | POAOperations.activate_object(Servant p_servant) This operation generates an Object Id and enters the Object Id and the specified servant in the Active Object Map.
Object | POAOperations.create_reference(String intf) This operation creates an object reference that encapsulates a POA-generated Object Id value and the specified interface repository id.
void | POAOperations.deactivate_object(byte[] oid) This operation causes the ObjectId specified in the oid parameter to be deactivated.
ServantManager | POAOperations.get_servant_manager() If the ServantRetentionPolicy of the POA is RETAIN, then the ServantManager argument (imgr) shall support the ServantActivator interface.
Servant | POAOperations.get_servant() This operation returns the default servant associated with the POA.
Object | POAOperations.id_to_reference(byte[] oid) If an object with the specified Object Id value is currently active, a reference encapsulating the information used to activate the object is returned.
Servant | POAOperations.id_to_servant(byte[] oid) If the POA has the RETAIN policy and the specified ObjectId is in the Active Object Map, this operation returns the servant associated with that object in the Active Object Map.
byte[] | POAOperations.reference_to_id(Object reference) This operation returns the Object Id value encapsulated by the specified reference.
Servant | POAOperations.reference_to_servant(Object reference) If the POA has the RETAIN policy and the specified object is present in the Active Object Map, this operation returns the servant associated with that object in the Active Object Map.
byte[] | POAOperations.servant_to_id(Servant p_servant) This operation has four possible behaviors.
Object | POAOperations.servant_to_reference(Servant p_servant) This operation requires the RETAIN policy and either the UNIQUE_ID or IMPLICIT_ACTIVATION policies if invoked outside the context of an operation dispatched by this POA.
void | POAOperations.set_servant_manager(ServantManager imgr) This operation sets the default servant manager associated with the POA.
void | POAOperations.set_servant(Servant p_servant) This operation registers the specified servant with the POA as the default servant.

Uses of WrongPolicy in org.omg.PortableServer.POAPackage

Methods in org.omg.PortableServer.POAPackage that return WrongPolicy
static WrongPolicy | WrongPolicyHelper.extract(Any a)
static WrongPolicy | WrongPolicyHelper.read(InputStream istream)

Methods in org.omg.PortableServer.POAPackage with parameters of type WrongPolicy
static void | WrongPolicyHelper.insert(Any a, WrongPolicy that)
static void | WrongPolicyHelper.write(OutputStream ostream, WrongPolicy value)

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.POAPackage.WrongPolicyHelper

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.POAPackage.WrongPolicyHelper

No usage of org.omg.PortableServer.POAPackage.WrongPolicyHelper

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


InvalidPolicy

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class InvalidPolicy

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.PortableServer.POAPackage.InvalidPolicy
All Implemented Interfaces:
Serializable, IDLEntity
public final class InvalidPolicy
extends UserException

org/omg/PortableServer/POAPackage/InvalidPolicy.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Field Summary
 short index
Constructor Summary
InvalidPolicy()
InvalidPolicy(short _index)
InvalidPolicy(String $reason, short _index)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

index

public short index
Constructor Detail

InvalidPolicy

public InvalidPolicy()

InvalidPolicy

public InvalidPolicy(short _index)

InvalidPolicy

public InvalidPolicy(String $reason,
                     short _index)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidPolicyHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class InvalidPolicyHelper

java.lang.Object
    extended by  org.omg.PortableServer.POAPackage.InvalidPolicyHelper

public abstract class InvalidPolicyHelper
extends Object

org/omg/PortableServer/POAPackage/InvalidPolicyHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
InvalidPolicyHelper()
Method Summary
static InvalidPolicy | extract(Any a)
static String | id()
static void | insert(Any a, InvalidPolicy that)
static InvalidPolicy | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, InvalidPolicy value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InvalidPolicyHelper

public InvalidPolicyHelper()
Method Detail

insert

public static void insert(Any a,
                          InvalidPolicy that)

extract

public static InvalidPolicy extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static InvalidPolicy read(InputStream istream)

write

public static void write(OutputStream ostream,
                         InvalidPolicy value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NoServant

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class NoServant

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.PortableServer.POAPackage.NoServant
All Implemented Interfaces:
Serializable, IDLEntity
public final class NoServant
extends UserException

org/omg/PortableServer/POAPackage/NoServant.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
NoServant()
NoServant(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NoServant

public NoServant()

NoServant

public NoServant(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NoServantHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class NoServantHelper

java.lang.Object
    extended by  org.omg.PortableServer.POAPackage.NoServantHelper

public abstract class NoServantHelper
extends Object

org/omg/PortableServer/POAPackage/NoServantHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
NoServantHelper()
Method Summary
static NoServant | extract(Any a)
static String | id()
static void | insert(Any a, NoServant that)
static NoServant | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, NoServant value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NoServantHelper

public NoServantHelper()
Method Detail

insert

public static void insert(Any a,
                          NoServant that)

extract

public static NoServant extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static NoServant read(InputStream istream)

write

public static void write(OutputStream ostream,
                         NoServant value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectAlreadyActive

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class ObjectAlreadyActive

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.PortableServer.POAPackage.ObjectAlreadyActive
All Implemented Interfaces:
Serializable, IDLEntity
public final class ObjectAlreadyActive
extends UserException

org/omg/PortableServer/POAPackage/ObjectAlreadyActive.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
ObjectAlreadyActive()
ObjectAlreadyActive(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ObjectAlreadyActive

public ObjectAlreadyActive()

ObjectAlreadyActive

public ObjectAlreadyActive(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectAlreadyActiveHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class ObjectAlreadyActiveHelper

java.lang.Object
    extended by  org.omg.PortableServer.POAPackage.ObjectAlreadyActiveHelper

public abstract class ObjectAlreadyActiveHelper
extends Object

org/omg/PortableServer/POAPackage/ObjectAlreadyActiveHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
ObjectAlreadyActiveHelper()
Method Summary
static ObjectAlreadyActive | extract(Any a)
static String | id()
static void | insert(Any a, ObjectAlreadyActive that)
static ObjectAlreadyActive | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, ObjectAlreadyActive value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ObjectAlreadyActiveHelper

public ObjectAlreadyActiveHelper()
Method Detail

insert

public static void insert(Any a,
                          ObjectAlreadyActive that)

extract

public static ObjectAlreadyActive extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static ObjectAlreadyActive read(InputStream istream)

write

public static void write(OutputStream ostream,
                         ObjectAlreadyActive value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectNotActive

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class ObjectNotActive

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.PortableServer.POAPackage.ObjectNotActive
All Implemented Interfaces:
Serializable, IDLEntity
public final class ObjectNotActive
extends UserException

org/omg/PortableServer/POAPackage/ObjectNotActive.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
ObjectNotActive()
ObjectNotActive(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ObjectNotActive

public ObjectNotActive()

ObjectNotActive

public ObjectNotActive(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectNotActiveHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class ObjectNotActiveHelper

java.lang.Object
    extended by  org.omg.PortableServer.POAPackage.ObjectNotActiveHelper

public abstract class ObjectNotActiveHelper
extends Object

org/omg/PortableServer/POAPackage/ObjectNotActiveHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
ObjectNotActiveHelper()
Method Summary
static ObjectNotActive | extract(Any a)
static String | id()
static void | insert(Any a, ObjectNotActive that)
static ObjectNotActive | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, ObjectNotActive value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ObjectNotActiveHelper

public ObjectNotActiveHelper()
Method Detail

insert

public static void insert(Any a,
                          ObjectNotActive that)

extract

public static ObjectNotActive extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static ObjectNotActive read(InputStream istream)

write

public static void write(OutputStream ostream,
                         ObjectNotActive value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantAlreadyActive

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class ServantAlreadyActive

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.PortableServer.POAPackage.ServantAlreadyActive
All Implemented Interfaces:
Serializable, IDLEntity
public final class ServantAlreadyActive
extends UserException

org/omg/PortableServer/POAPackage/ServantAlreadyActive.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
ServantAlreadyActive()
ServantAlreadyActive(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ServantAlreadyActive

public ServantAlreadyActive()

ServantAlreadyActive

public ServantAlreadyActive(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantAlreadyActiveHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class ServantAlreadyActiveHelper

java.lang.Object
    extended by  org.omg.PortableServer.POAPackage.ServantAlreadyActiveHelper

public abstract class ServantAlreadyActiveHelper
extends Object

org/omg/PortableServer/POAPackage/ServantAlreadyActiveHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
ServantAlreadyActiveHelper()
Method Summary
static ServantAlreadyActive | extract(Any a)
static String | id()
static void | insert(Any a, ServantAlreadyActive that)
static ServantAlreadyActive | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, ServantAlreadyActive value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServantAlreadyActiveHelper

public ServantAlreadyActiveHelper()
Method Detail

insert

public static void insert(Any a,
                          ServantAlreadyActive that)

extract

public static ServantAlreadyActive extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static ServantAlreadyActive read(InputStream istream)

write

public static void write(OutputStream ostream,
                         ServantAlreadyActive value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantNotActive

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class ServantNotActive

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.PortableServer.POAPackage.ServantNotActive
All Implemented Interfaces:
Serializable, IDLEntity
public final class ServantNotActive
extends UserException

org/omg/PortableServer/POAPackage/ServantNotActive.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
ServantNotActive()
ServantNotActive(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ServantNotActive

public ServantNotActive()

ServantNotActive

public ServantNotActive(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantNotActiveHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class ServantNotActiveHelper

java.lang.Object
    extended by  org.omg.PortableServer.POAPackage.ServantNotActiveHelper

public abstract class ServantNotActiveHelper
extends Object

org/omg/PortableServer/POAPackage/ServantNotActiveHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
ServantNotActiveHelper()
Method Summary
static ServantNotActive | extract(Any a)
static String | id()
static void | insert(Any a, ServantNotActive that)
static ServantNotActive | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, ServantNotActive value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServantNotActiveHelper

public ServantNotActiveHelper()
Method Detail

insert

public static void insert(Any a,
                          ServantNotActive that)

extract

public static ServantNotActive extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static ServantNotActive read(InputStream istream)

write

public static void write(OutputStream ostream,
                         ServantNotActive value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WrongAdapter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class WrongAdapter

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.PortableServer.POAPackage.WrongAdapter
All Implemented Interfaces:
Serializable, IDLEntity
public final class WrongAdapter
extends UserException

org/omg/PortableServer/POAPackage/WrongAdapter.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
WrongAdapter()
WrongAdapter(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

WrongAdapter

public WrongAdapter()

WrongAdapter

public WrongAdapter(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WrongAdapterHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class WrongAdapterHelper

java.lang.Object
    extended by  org.omg.PortableServer.POAPackage.WrongAdapterHelper

public abstract class WrongAdapterHelper
extends Object

org/omg/PortableServer/POAPackage/WrongAdapterHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
WrongAdapterHelper()
Method Summary
static WrongAdapter | extract(Any a)
static String | id()
static void | insert(Any a, WrongAdapter that)
static WrongAdapter | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, WrongAdapter value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WrongAdapterHelper

public WrongAdapterHelper()
Method Detail

insert

public static void insert(Any a,
                          WrongAdapter that)

extract

public static WrongAdapter extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static WrongAdapter read(InputStream istream)

write

public static void write(OutputStream ostream,
                         WrongAdapter value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WrongPolicy

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class WrongPolicy

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.omg.CORBA.UserException
                extended by  org.omg.PortableServer.POAPackage.WrongPolicy
All Implemented Interfaces:
Serializable, IDLEntity
public final class WrongPolicy
extends UserException

org/omg/PortableServer/POAPackage/WrongPolicy.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
WrongPolicy()
WrongPolicy(String $reason)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

WrongPolicy

public WrongPolicy()

WrongPolicy

public WrongPolicy(String $reason)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WrongPolicyHelper

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.POAPackage
Class WrongPolicyHelper

java.lang.Object
    extended by  org.omg.PortableServer.POAPackage.WrongPolicyHelper

public abstract class WrongPolicyHelper
extends Object

org/omg/PortableServer/POAPackage/WrongPolicyHelper.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Constructor Summary
WrongPolicyHelper()
Method Summary
static WrongPolicy | extract(Any a)
static String | id()
static void | insert(Any a, WrongPolicy that)
static WrongPolicy | read(InputStream istream)
static TypeCode | type()
static void | write(OutputStream ostream, WrongPolicy value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WrongPolicyHelper

public WrongPolicyHelper()
Method Detail

insert

public static void insert(Any a,
                          WrongPolicy that)

extract

public static WrongPolicy extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static WrongPolicy read(InputStream istream)

write

public static void write(OutputStream ostream,
                         WrongPolicy value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


portable

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.PortableServer.portable

Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

See:
Description

Interface Summary
Delegate The portability package contains interfaces and classes that are designed for and intended to be used by ORB implementor.

Package org.omg.PortableServer.portable Description

Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

The portable package contains interfaces and classes that are designed for and intended to be used by an ORB implementor. It exposes the publicly defined APIs that are used to connect stubs and skeletons to the ORB. The Delegate interface provides the ORB-vendor-specific implementation of PortableServer::Servant. This package conforms CORBA Specification V2.3.1, ptc/00-01-08.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.PortableServer.portable Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.PortableServer.portable

Package Hierarchies:
All Packages

Interface Hierarchy

  • org.omg.PortableServer.portable.Delegate
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.PortableServer.portable

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.PortableServer.portable

Packages that use org.omg.PortableServer.portable
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Classes in org.omg.PortableServer.portable used by org.omg.PortableServer
Delegate
The portability package contains interfaces and classes that are designed for and intended to be used by ORB implementor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.PortableServer.portable.Delegate

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.PortableServer.portable.Delegate

Packages that use Delegate
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of Delegate in org.omg.PortableServer

Methods in org.omg.PortableServer that return Delegate
 Delegate Servant._get_delegate()
Gets the ORB vendor-specific implementation of PortableServer::Servant.

Methods in org.omg.PortableServer with parameters of type Delegate
 void Servant._set_delegate(Delegate delegate)
Supports the Java ORB portability interfaces by providing a method for classes that support ORB portability through delegation to set their delegate.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Delegate

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.portable
Interface Delegate

public interface Delegate

The portability package contains interfaces and classes that are designed for and intended to be used by ORB implementor. It exposes the publicly defined APIs that are used to connect stubs and skeletons to the ORB. The Delegate interface provides the ORB vendor specific implementation of PortableServer::Servant. Conformant to spec CORBA V2.3.1, ptc/00-01-08.pdf

Method Summary
 POA default_POA(Servant Self)
The default behavior of this function is to return the root POA from the ORB instance associated with the servant.
 Object get_interface_def(Servant self)
This operation returns an object in the Interface Repository which provides type information that may be useful to a program.
 boolean is_a(Servant Self, String Repository_Id)
This method checks to see if the specified repid is present on the list returned by _all_interfaces() or is the repository id for the generic CORBA Object.
 boolean non_existent(Servant Self)
This operation is used to check for the existence of the Object.
 byte[] object_id(Servant Self)
The method _object_id() is equivalent to calling PortableServer::Current::get_object_id.
 ORB orb(Servant Self)
Convenience method that returns the instance of the ORB currently associated with the Servant.
 POA poa(Servant Self)
The method _poa() is equivalent to calling PortableServer::Current:get_POA.
 Object this_object(Servant Self)
This allows the servant to obtain the object reference for the target CORBA Object it is incarnating for that request.

Method Detail

orb

ORB orb(Servant Self)
Convenience method that returns the instance of the ORB currently associated with the Servant.

Parameters:
Self - the servant.
Returns:
ORB associated with the Servant.

this_object

Object this_object(Servant Self)
This allows the servant to obtain the object reference for the target CORBA Object it is incarnating for that request.

Parameters:
Self - the servant.
Returns:
Object reference associated with the request.

poa

POA poa(Servant Self)
The method _poa() is equivalent to calling PortableServer::Current:get_POA.

Parameters:
Self - the servant.
Returns:
POA associated with the servant.

object_id

byte[] object_id(Servant Self)
The method _object_id() is equivalent to calling PortableServer::Current::get_object_id.

Parameters:
Self - the servant.
Returns:
ObjectId associated with this servant.

default_POA

POA default_POA(Servant Self)
The default behavior of this function is to return the root POA from the ORB instance associated with the servant.

Parameters:
Self - the servant.
Returns:
POA associated with the servant class.

is_a

boolean is_a(Servant Self,
             String Repository_Id)
This method checks to see if the specified repid is present on the list returned by _all_interfaces() or is the repository id for the generic CORBA Object.

Parameters:
Self - the servant.
Repository_Id - the repository_id to be checked in the repository list or against the id of generic CORBA object.
Returns:
boolean indicating whether the specified repid is in the list or is same as that got generic CORBA object.

non_existent

boolean non_existent(Servant Self)
This operation is used to check for the existence of the Object.

Parameters:
Self - the servant.
Returns:
boolean true to indicate that object does not exist, and false otherwise.

get_interface_def

Object get_interface_def(Servant self)
This operation returns an object in the Interface Repository which provides type information that may be useful to a program.

Parameters:
self - the servant.
Returns:
type information corresponding to the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


RequestProcessingPolicyOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface RequestProcessingPolicyOperations

All Superinterfaces:
PolicyOperations
All Known Subinterfaces:
RequestProcessingPolicy
public interface RequestProcessingPolicyOperations
extends PolicyOperations

This policy specifies how requests are processed by the created POA. The default is USE_ACTIVE_OBJECT_MAP_ONLY.

Method Summary
 RequestProcessingPolicyValue value()
specifies the policy value
Methods inherited from interface org.omg.CORBA.PolicyOperations
copy, destroy, policy_type

Method Detail

value

RequestProcessingPolicyValue value()
specifies the policy value

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


RequestProcessingPolicyValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class RequestProcessingPolicyValue

java.lang.Object
    extended by  org.omg.PortableServer.RequestProcessingPolicyValue
All Implemented Interfaces:
Serializable, IDLEntity
public class RequestProcessingPolicyValue
extends Object
implements IDLEntity

The RequestProcessingPolicyValue can have the following values. USE_ACTIVE_OBJECT_MAP_ONLY - If the Object Id is not found in the Active Object Map, an OBJECT_NOT_EXIST exception is returned to the client. The RETAIN policy is also required. USE_DEFAULT_SERVANT - If the Object Id is not found in the Active Object Map or the NON_RETAIN policy is present, and a default servant has been registered with the POA using the set_servant operation, the request is dispatched to the default servant. USE_SERVANT_MANAGER - If the Object Id is not found in the Active Object Map or the NON_RETAIN policy is present, and a servant manager has been registered with the POA using the set_servant_manager operation, the servant manager is given the opportunity to locate a servant or raise an exception.

Field Summary
static int | _USE_ACTIVE_OBJECT_MAP_ONLY
static int | _USE_DEFAULT_SERVANT
static int | _USE_SERVANT_MANAGER
static RequestProcessingPolicyValue | USE_ACTIVE_OBJECT_MAP_ONLY
static RequestProcessingPolicyValue | USE_DEFAULT_SERVANT
static RequestProcessingPolicyValue | USE_SERVANT_MANAGER
Constructor Summary
protected RequestProcessingPolicyValue(int value)
Method Summary
static RequestProcessingPolicyValue | from_int(int value)
int | value()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_USE_ACTIVE_OBJECT_MAP_ONLY

public static final int _USE_ACTIVE_OBJECT_MAP_ONLY
See Also:
Constant Field Values

USE_ACTIVE_OBJECT_MAP_ONLY

public static final RequestProcessingPolicyValue USE_ACTIVE_OBJECT_MAP_ONLY

_USE_DEFAULT_SERVANT

public static final int _USE_DEFAULT_SERVANT
See Also:
Constant Field Values

USE_DEFAULT_SERVANT

public static final RequestProcessingPolicyValue USE_DEFAULT_SERVANT

_USE_SERVANT_MANAGER

public static final int _USE_SERVANT_MANAGER
See Also:
Constant Field Values

USE_SERVANT_MANAGER

public static final RequestProcessingPolicyValue USE_SERVANT_MANAGER
Constructor Detail

RequestProcessingPolicyValue

protected RequestProcessingPolicyValue(int value)
Method Detail

value

public int value()

from_int

public static RequestProcessingPolicyValue from_int(int value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


REQUEST_PROCESSING_POLICY_ID

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface REQUEST_PROCESSING_POLICY_ID

public interface REQUEST_PROCESSING_POLICY_ID

org/omg/PortableServer/REQUEST_PROCESSING_POLICY_ID.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Field Summary
static int value
The value representing REQUEST_PROCESSING_POLICY_ID.

Field Detail

value

static final int value
The value representing REQUEST_PROCESSING_POLICY_ID.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Servant

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class Servant

java.lang.Object
    extended by  org.omg.PortableServer.Servant
Direct Known Subclasses:
BindingIteratorPOA, DynamicImplementation, NamingContextExtPOA, NamingContextPOA, ServantActivatorPOA, ServantLocatorPOA
public abstract class Servant
extends Object

Defines the native Servant type. In Java, the Servant type is mapped to the Java org.omg.PortableServer.Servant class. It serves as the base class for all POA servant implementations and provides a number of methods that may be invoked by the application programmer, as well as methods which are invoked by the POA itself and may be overridden by the user to control aspects of servant behavior. Based on IDL to Java spec. (CORBA V2.3.1) ptc/00-01-08.pdf.

Constructor Summary
Servant()
Method Summary
abstract  String[] _all_interfaces(POA poa, byte[] objectId)
Used by the ORB to obtain complete type information from the servant.
 POA _default_POA()
Returns the root POA from the ORB instance associated with the servant.
 Delegate _get_delegate()
Gets the ORB vendor-specific implementation of PortableServer::Servant.
 Object _get_interface_def()
Returns an InterfaceDef object as a CORBA::Object that defines the runtime type of the CORBA::Object implemented by the Servant.
 boolean _is_a(String repository_id)
Checks to see if the specified repository_id is present on the list returned by _all_interfaces() or is the repository_id for the generic CORBA Object.
 boolean _non_existent()
Checks for the existence of an Object.
 byte[] _object_id()
Allows easy execution of common methods, equivalent to calling PortableServer::Current::get_object_id.
 ORB _orb()
Returns the instance of the ORB currently associated with the Servant (convenience method).
 POA _poa()
Allows easy execution of common methods, equivalent to PortableServer::Current:get_POA.
 void _set_delegate(Delegate delegate)
Supports the Java ORB portability interfaces by providing a method for classes that support ORB portability through delegation to set their delegate.
 Object _this_object()
Allows the servant to obtain the object reference for the target CORBA object it is incarnating for that request.
 Object _this_object(ORB orb)
Allows the servant to obtain the object reference for the target CORBA Object it is incarnating for that request.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Servant

public Servant()
Method Detail

_get_delegate

public final Delegate _get_delegate()
Gets the ORB vendor-specific implementation of PortableServer::Servant.

Returns:
_delegate the ORB vendor-specific implementation of PortableServer::Servant.

_set_delegate

public final void _set_delegate(Delegate delegate)
Supports the Java ORB portability interfaces by providing a method for classes that support ORB portability through delegation to set their delegate.

Parameters:
delegate - ORB vendor-specific implementation of the PortableServer::Servant.

_this_object

public final Object _this_object()
Allows the servant to obtain the object reference for the target CORBA object it is incarnating for that request.

Returns:
this_object Object reference associated with the request.

_this_object

public final Object _this_object(ORB orb)
Allows the servant to obtain the object reference for the target CORBA Object it is incarnating for that request.

Parameters:
orb - ORB with which the servant is associated.
Returns:
_this_object reference associated with the request.

_orb

public final ORB _orb()
Returns the instance of the ORB currently associated with the Servant (convenience method).

Returns:
orb the instance of the ORB currently associated with the Servant.

_poa

public final POA _poa()
Allows easy execution of common methods, equivalent to PortableServer::Current:get_POA.

Returns:
poa POA associated with the servant.

_object_id

public final byte[] _object_id()
Allows easy execution of common methods, equivalent to calling PortableServer::Current::get_object_id.

Returns:
object_id the Object ID associated with this servant.

_default_POA

public POA _default_POA()
Returns the root POA from the ORB instance associated with the servant. Subclasses may override this method to return a different POA.

Returns:
default_POA the POA associated with the Servant.

_is_a

public boolean _is_a(String repository_id)
Checks to see if the specified repository_id is present on the list returned by _all_interfaces() or is the repository_id for the generic CORBA Object.

Parameters:
repository_id - the repository_id to be checked in the repository list or against the id of generic CORBA objects.
Returns:
is_a boolean indicating whether the specified repository_id is in the repository list or is same as a generic CORBA object.

_non_existent

public boolean _non_existent()
Checks for the existence of an Object. The Servant provides a default implementation of _non_existent() that can be overridden by derived servants.

Returns:
non_existent true if that object does not exist, false otherwise.

_get_interface_def

public Object _get_interface_def()
Returns an InterfaceDef object as a CORBA::Object that defines the runtime type of the CORBA::Object implemented by the Servant. The invoker of _get_interface_def must narrow the result to an InterfaceDef in order to use it.

This default implementation of _get_interface_def() can be overridden by derived servants if the default behavior is not adequate. As defined in the CORBA 2.3.1 specification, section 11.3.1, the default behavior of _get_interface_def() is to use the most derived interface of a static servant or the most derived interface retrieved from a dynamic servant to obtain the InterfaceDef. This behavior must be supported by the Delegate that implements the Servant.

Returns:
get_interface_def an InterfaceDef object as a CORBA::Object that defines the runtime type of the CORBA::Object implemented by the Servant.

_all_interfaces

public abstract String[] _all_interfaces(POA poa,
                                         byte[] objectId)
Used by the ORB to obtain complete type information from the servant.

Parameters:
poa - POA with which the servant is associated.
objectId - is the id corresponding to the object associated with this servant.
Returns:
list of type information for the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantActivatorHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class ServantActivatorHelper

java.lang.Object
    extended by  org.omg.PortableServer.ServantActivatorHelper

public abstract class ServantActivatorHelper
extends Object

When the POA has the RETAIN policy it uses servant managers that are ServantActivators.

Constructor Summary
ServantActivatorHelper()
Method Summary
static ServantActivator | extract(Any a)
static String | id()
static void | insert(Any a, ServantActivator that)
static ServantActivator | narrow(Object obj)
static ServantActivator | read(InputStream istream)
static TypeCode | type()
static ServantActivator | unchecked_narrow(Object obj)
static void | write(OutputStream ostream, ServantActivator value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServantActivatorHelper

public ServantActivatorHelper()
Method Detail

insert

public static void insert(Any a,
                          ServantActivator that)

extract

public static ServantActivator extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static ServantActivator read(InputStream istream)

write

public static void write(OutputStream ostream,
                         ServantActivator value)

narrow

public static ServantActivator narrow(Object obj)

unchecked_narrow

public static ServantActivator unchecked_narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantActivatorOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface ServantActivatorOperations

All Superinterfaces:
ServantManagerOperations
All Known Subinterfaces:
ServantActivator
All Known Implementing Classes:
_ServantActivatorStub, ServantActivatorPOA
public interface ServantActivatorOperations
extends ServantManagerOperations

When the POA has the RETAIN policy it uses servant managers that are ServantActivators.

Method Summary
void | etherealize(byte[] oid, POA adapter, Servant serv, boolean cleanup_in_progress, boolean remaining_activations) This operation is invoked whenever a servant for an object is deactivated, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.
Servant | incarnate(byte[] oid, POA adapter) This operation is invoked by the POA whenever the POA receives a request for an object that is not currently active, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.

Method Detail

incarnate

Servant incarnate(byte[] oid,
                  POA adapter)
                  throws ForwardRequest
This operation is invoked by the POA whenever the POA receives a request for an object that is not currently active, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.

Parameters:
oid - object Id associated with the object on the request was made.
adapter - object reference for the POA in which the object is being activated.
Returns:
Servant corresponding to oid is created or located by the user supplied servant manager.
Throws:
ForwardRequest - to indicate to the ORB that it is responsible for delivering the current request and subsequent requests to the object denoted in the forward_reference member of the exception.

etherealize

void etherealize(byte[] oid,
                 POA adapter,
                 Servant serv,
                 boolean cleanup_in_progress,
                 boolean remaining_activations)
This operation is invoked whenever a servant for an object is deactivated, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.

Parameters:
oid - object Id associated with the object being deactivated.
adapter - object reference for the POA in which the object was active.
serv - contains reference to the servant associated with the object being deactivated.
cleanup_in_progress - if TRUE indicates that destroy or deactivate is called with etherealize_objects param of TRUE. FALSE indicates that etherealize was called due to other reasons.
remaining_activations - indicates whether the Servant Manager can destroy a servant. If set to TRUE, the Servant Manager should wait until all invocations in progress have completed.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantActivatorPOA

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class ServantActivatorPOA

java.lang.Object
    extended by  org.omg.PortableServer.Servant
        extended by  org.omg.PortableServer.ServantActivatorPOA
All Implemented Interfaces:
InvokeHandler, ServantActivatorOperations, ServantManagerOperations
public abstract class ServantActivatorPOA
extends Servant
implements ServantActivatorOperations, InvokeHandler

When the POA has the RETAIN policy it uses servant managers that are ServantActivators.

Constructor Summary
ServantActivatorPOA()
Method Summary
String[] | _all_interfaces(POA poa, byte[] objectId) Used by the ORB to obtain complete type information from the servant.
OutputStream | _invoke(String $method, InputStream in, ResponseHandler $rh) Invoked by the ORB to dispatch a request to the servant.
ServantActivator | _this()
ServantActivator | _this(ORB orb)
Methods inherited from class org.omg.PortableServer.Servant
_default_POA, _get_delegate, _get_interface_def, _is_a, _non_existent, _object_id, _orb, _poa, _set_delegate, _this_object, _this_object
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.omg.PortableServer.ServantActivatorOperations
etherealize, incarnate

Constructor Detail

ServantActivatorPOA

public ServantActivatorPOA()
Method Detail

_invoke

public OutputStream _invoke(String $method,
                            InputStream in,
                            ResponseHandler $rh)
Description copied from interface: InvokeHandler
Invoked by the ORB to dispatch a request to the servant. ORB passes the method name, an InputStream containing the marshalled arguments, and a ResponseHandler which the servant uses to construct a proper reply. Only CORBA SystemException may be thrown by this method. The method must return an OutputStream created by the ResponseHandler which contains the marshalled reply. A servant must not retain a reference to the ResponseHandler beyond the lifetime of a method invocation. Servant behaviour is defined as follows:

1. Determine correct method, and unmarshal parameters from InputStream.

2. Invoke method implementation.

3. If no user exception, create a normal reply using ResponseHandler.

4. If user exception occurred, create exception reply using ResponseHandler.

5. Marshal reply into OutputStream returned by ResponseHandler.

6. Return OutputStream to ORB.

Specified by:
_invoke in interface InvokeHandler
Parameters:
$method - The method name.
in - The InputStream containing the marshalled arguments.
$rh - The ResponseHandler which the servant uses to construct a proper reply
Returns:
The OutputStream created by the ResponseHandler which contains the marshalled reply

_all_interfaces

public String[] _all_interfaces(POA poa,
                                byte[] objectId)
Description copied from class: Servant
Used by the ORB to obtain complete type information from the servant.

Specified by:
_all_interfaces in class Servant
Parameters:
poa - POA with which the servant is associated.
objectId - is the id corresponding to the object associated with this servant.
Returns:
list of type information for the object.

_this

public ServantActivator _this()

_this

public ServantActivator _this(ORB orb)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantLocatorHelper

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class ServantLocatorHelper

java.lang.Object
    extended by  org.omg.PortableServer.ServantLocatorHelper

public abstract class ServantLocatorHelper
extends Object

When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators. Because the POA knows that the servant returned by this servant manager will be used only for a single request, it can supply extra information to the servant manager's operations and the servant manager's pair of operations may be able to cooperate to do something different than a ServantActivator. When the POA uses the ServantLocator interface, immediately after performing the operation invocation on the servant returned by preinvoke, the POA will invoke postinvoke on the servant manager, passing the ObjectId value and the Servant value as parameters (among others). This feature may be used to force every request for objects associated with a POA to be mediated by the servant manager.

Constructor Summary
ServantLocatorHelper()
Method Summary
static ServantLocator | extract(Any a)
static String | id()
static void | insert(Any a, ServantLocator that)
static ServantLocator | narrow(Object obj)
static ServantLocator | read(InputStream istream)
static TypeCode | type()
static ServantLocator | unchecked_narrow(Object obj)
static void | write(OutputStream ostream, ServantLocator value)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServantLocatorHelper

public ServantLocatorHelper()
Method Detail

insert

public static void insert(Any a,
                          ServantLocator that)

extract

public static ServantLocator extract(Any a)

type

public static TypeCode type()

id

public static String id()

read

public static ServantLocator read(InputStream istream)

write

public static void write(OutputStream ostream,
                         ServantLocator value)

narrow

public static ServantLocator narrow(Object obj)

unchecked_narrow

public static ServantLocator unchecked_narrow(Object obj)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantLocatorOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface ServantLocatorOperations

All Superinterfaces:
ServantManagerOperations
All Known Subinterfaces:
ServantLocator
All Known Implementing Classes:
_ServantLocatorStub, ServantLocatorPOA
public interface ServantLocatorOperations
extends ServantManagerOperations

When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators. Because the POA knows that the servant returned by this servant manager will be used only for a single request, it can supply extra information to the servant manager's operations and the servant manager's pair of operations may be able to cooperate to do something different than a ServantActivator. When the POA uses the ServantLocator interface, immediately after performing the operation invocation on the servant returned by preinvoke, the POA will invoke postinvoke on the servant manager, passing the ObjectId value and the Servant value as parameters (among others). This feature may be used to force every request for objects associated with a POA to be mediated by the servant manager.

Method Summary
void | postinvoke(byte[] oid, POA adapter, String operation, Object the_cookie, Servant the_servant) This operation is invoked whenener a servant completes a request.
Servant | preinvoke(byte[] oid, POA adapter, String operation, CookieHolder the_cookie) This operations is used to get a servant that will be used to process the request that caused preinvoke to be called.

Method Detail

preinvoke

Servant preinvoke(byte[] oid,
                  POA adapter,
                  String operation,
                  CookieHolder the_cookie)
                  throws ForwardRequest
This operations is used to get a servant that will be used to process the request that caused preinvoke to be called.

Parameters:
oid - the object id associated with object on which the request was made.
adapter - the reference for POA in which the object is being activated.
operation - the operation name.
the_cookie - an opaque value that can be set by the servant manager to be used during postinvoke.
Returns:
Servant used to process incoming request.
Throws:
ForwardRequest - to indicate to the ORB that it is responsible for delivering the current request and subsequent requests to the object denoted in the forward_reference member of the exception.

postinvoke

void postinvoke(byte[] oid,
                POA adapter,
                String operation,
                Object the_cookie,
                Servant the_servant)
This operation is invoked whenener a servant completes a request.

Parameters:
oid - the object id ssociated with object on which the request was made.
adapter - the reference for POA in which the object was active.
the_cookie - an opaque value that contains the data set by preinvoke.
the_servant - reference to the servant that is associated with the object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantLocatorPackage

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.PortableServer.ServantLocatorPackage

Provides classes and interfaces for locating the servant.

See:
Description

Class Summary
CookieHolder The native type PortableServer::ServantLocator::Cookie is mapped to java.lang.Object.

Package org.omg.PortableServer.ServantLocatorPackage Description

Provides classes and interfaces for locating the servant.

This package supplies a CookieHolder class for passing the Cookie type as an out parameter. The CookieHolder class follows exactly the same pattern as the other holder classes for basic types.

Package Specification

For a precise list of supported sections of official OMG specifications with which the Java[tm] Platform, Standard Edition 6 complies, see Official Specifications for CORBA support in Java[tm] SE 6.

Since:
1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.PortableServer.ServantLocatorPackage Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.PortableServer.ServantLocatorPackage

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.PortableServer.ServantLocatorPackage.CookieHolder (implements org.omg.CORBA.portable.Streamable)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.PortableServer.ServantLocatorPackage

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.PortableServer.ServantLocatorPackage

Packages that use org.omg.PortableServer.ServantLocatorPackage
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Classes in org.omg.PortableServer.ServantLocatorPackage used by org.omg.PortableServer
CookieHolder
The native type PortableServer::ServantLocator::Cookie is mapped to java.lang.Object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.PortableServer.ServantLocatorPackage.CookieHolder

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.PortableServer.ServantLocatorPackage.CookieHolder

Packages that use CookieHolder
org.omg.PortableServer Provides classes and interfaces for making the server side of your applications portable across multivendor ORBs.

Uses of CookieHolder in org.omg.PortableServer

Methods in org.omg.PortableServer with parameters of type CookieHolder
Servant | _ServantLocatorStub.preinvoke(byte[] oid, POA adapter, String operation, CookieHolder the_cookie) This operations is used to get a servant that will be used to process the request that caused preinvoke to be called.
Servant | ServantLocatorOperations.preinvoke(byte[] oid, POA adapter, String operation, CookieHolder the_cookie) This operations is used to get a servant that will be used to process the request that caused preinvoke to be called.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


CookieHolder

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer.ServantLocatorPackage
Class CookieHolder

java.lang.Object
    extended by  org.omg.PortableServer.ServantLocatorPackage.CookieHolder
All Implemented Interfaces:
Streamable
public final class CookieHolder
extends Object
implements Streamable

The native type PortableServer::ServantLocator::Cookie is mapped to java.lang.Object. A CookieHolder class is provided for passing the Cookie type as an out parameter. The CookieHolder class follows exactly the same pattern as the other holder classes for basic types.

Field Summary
 Object value
Constructor Summary
CookieHolder()
CookieHolder(Object initial)
Method Summary
void | _read(InputStream is) Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.
TypeCode | _type() Retrieves the TypeCode object corresponding to the value in the value field of the Holder.
void | _write(OutputStream os) Marshals to ostream the value in the value field of the Holder.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

value

public Object value
Constructor Detail

CookieHolder

public CookieHolder()

CookieHolder

public CookieHolder(Object initial)
Method Detail

_read

public void _read(InputStream is)
Description copied from interface: Streamable
Reads data from istream and initalizes the value field of the Holder with the unmarshalled data.

Specified by:
_read in interface Streamable
Parameters:
is - the InputStream that represents the CDR data from the wire.

_write

public void _write(OutputStream os)
Description copied from interface: Streamable
Marshals to ostream the value in the value field of the Holder.

Specified by:
_write in interface Streamable
Parameters:
os - the CDR OutputStream

_type

public TypeCode _type()
Description copied from interface: Streamable
Retrieves the TypeCode object corresponding to the value in the value field of the Holder.

Specified by:
_type in interface Streamable
Returns:
the TypeCode object for the value held in the holder
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


ServantLocatorPOA

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class ServantLocatorPOA

java.lang.Object
    extended by  org.omg.PortableServer.Servant
        extended by  org.omg.PortableServer.ServantLocatorPOA
All Implemented Interfaces:
InvokeHandler, ServantLocatorOperations, ServantManagerOperations
public abstract class ServantLocatorPOA
extends Servant
implements ServantLocatorOperations, InvokeHandler

When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators. Because the POA knows that the servant returned by this servant manager will be used only for a single request, it can supply extra information to the servant manager's operations and the servant manager's pair of operations may be able to cooperate to do something different than a ServantActivator. When the POA uses the ServantLocator interface, immediately after performing the operation invocation on the servant returned by preinvoke, the POA will invoke postinvoke on the servant manager, passing the ObjectId value and the Servant value as parameters (among others). This feature may be used to force every request for objects associated with a POA to be mediated by the servant manager.

Constructor Summary
ServantLocatorPOA()
Method Summary
String[] | _all_interfaces(POA poa, byte[] objectId) Used by the ORB to obtain complete type information from the servant.
OutputStream | _invoke(String $method, InputStream in, ResponseHandler $rh) Invoked by the ORB to dispatch a request to the servant.
ServantLocator | _this()
ServantLocator | _this(ORB orb)
Methods inherited from class org.omg.PortableServer.Servant
_default_POA, _get_delegate, _get_interface_def, _is_a, _non_existent, _object_id, _orb, _poa, _set_delegate, _this_object, _this_object
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.omg.PortableServer.ServantLocatorOperations
postinvoke, preinvoke

Constructor Detail

ServantLocatorPOA

public ServantLocatorPOA()
Method Detail

_invoke

public OutputStream _invoke(String $method,
                            InputStream in,
                            ResponseHandler $rh)
Description copied from interface: InvokeHandler
Invoked by the ORB to dispatch a request to the servant. ORB passes the method name, an InputStream containing the marshalled arguments, and a ResponseHandler which the servant uses to construct a proper reply. Only CORBA SystemException may be thrown by this method. The method must return an OutputStream created by the ResponseHandler which contains the marshalled reply. A servant must not retain a reference to the ResponseHandler beyond the lifetime of a method invocation. Servant behaviour is defined as follows:

1. Determine correct method, and unmarshal parameters from InputStream.

2. Invoke method implementation.

3. If no user exception, create a normal reply using ResponseHandler.

4. If user exception occurred, create exception reply using ResponseHandler.

5. Marshal reply into OutputStream returned by ResponseHandler.

6. Return OutputStream to ORB.

Specified by:
_invoke in interface InvokeHandler
Parameters:
$method - The method name.
in - The InputStream containing the marshalled arguments.
$rh - The ResponseHandler which the servant uses to construct a proper reply
Returns:
The OutputStream created by the ResponseHandler which contains the marshalled reply

_all_interfaces

public String[] _all_interfaces(POA poa,
                                byte[] objectId)
Description copied from class: Servant
Used by the ORB to obtain complete type information from the servant.

Specified by:
_all_interfaces in class Servant
Parameters:
poa - POA with which the servant is associated.
objectId - is the id corresponding to the object associated with this servant.
Returns:
list of type information for the object.

_this

public ServantLocator _this()

_this

public ServantLocator _this(ORB orb)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantRetentionPolicyOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface ServantRetentionPolicyOperations

All Superinterfaces:
PolicyOperations
All Known Subinterfaces:
ServantRetentionPolicy
public interface ServantRetentionPolicyOperations
extends PolicyOperations

This policy specifies whether the created POA retains active servants in an Active Object Map.

Method Summary
 ServantRetentionPolicyValue value()
specifies the policy value
Methods inherited from interface org.omg.CORBA.PolicyOperations
copy, destroy, policy_type

Method Detail

value

ServantRetentionPolicyValue value()
specifies the policy value

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ServantRetentionPolicyValue

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class ServantRetentionPolicyValue

java.lang.Object
    extended by  org.omg.PortableServer.ServantRetentionPolicyValue
All Implemented Interfaces:
Serializable, IDLEntity
public class ServantRetentionPolicyValue
extends Object
implements IDLEntity

ServantRetentionPolicyValue can have the following values. RETAIN - to indicate that the POA will retain active servants in its Active Object Map. NON_RETAIN - to indicate Servants are not retained by the POA. If no ServantRetentionPolicy is specified at POA creation, the default is RETAIN.

Field Summary
static int | _NON_RETAIN
static int | _RETAIN
static ServantRetentionPolicyValue | NON_RETAIN
static ServantRetentionPolicyValue | RETAIN
Constructor Summary
protected ServantRetentionPolicyValue(int value)
Method Summary
static ServantRetentionPolicyValue | from_int(int value)
int | value()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_RETAIN

public static final int _RETAIN
See Also:
Constant Field Values

RETAIN

public static final ServantRetentionPolicyValue RETAIN

_NON_RETAIN

public static final int _NON_RETAIN
See Also:
Constant Field Values

NON_RETAIN

public static final ServantRetentionPolicyValue NON_RETAIN
Constructor Detail

ServantRetentionPolicyValue

protected ServantRetentionPolicyValue(int value)
Method Detail

value

public int value()

from_int

public static ServantRetentionPolicyValue from_int(int value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SERVANT_RETENTION_POLICY_ID

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface SERVANT_RETENTION_POLICY_ID

public interface SERVANT_RETENTION_POLICY_ID

org/omg/PortableServer/SERVANT_RETENTION_POLICY_ID.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Field Summary
static int value
The value representing SERVANT_RETENTION_POLICY_ID.

Field Detail

value

static final int value
The value representing SERVANT_RETENTION_POLICY_ID.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ThreadPolicyOperations

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface ThreadPolicyOperations

All Superinterfaces:
PolicyOperations
All Known Subinterfaces:
ThreadPolicy
public interface ThreadPolicyOperations
extends PolicyOperations

The ThreadPolicy specifies the threading model used with the created POA. The default is ORB_CTRL_MODEL.

Method Summary
 ThreadPolicyValue value()
specifies the policy value
Methods inherited from interface org.omg.CORBA.PolicyOperations
copy, destroy, policy_type

Method Detail

value

ThreadPolicyValue value()
specifies the policy value

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ThreadPolicyValue

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Class ThreadPolicyValue

java.lang.Object
    extended by  org.omg.PortableServer.ThreadPolicyValue
All Implemented Interfaces:
Serializable, IDLEntity
public class ThreadPolicyValue
extends Object
implements IDLEntity

The ThreadPolicyValue can have the following values. ORB_CTRL_MODEL - The ORB is responsible for assigning requests for an ORB- controlled POA to threads. SINGLE_THREAD_MODEL - Requests for a single-threaded POA are processed sequentially.

Field Summary
static int | _ORB_CTRL_MODEL
static int | _SINGLE_THREAD_MODEL
static ThreadPolicyValue | ORB_CTRL_MODEL
static ThreadPolicyValue | SINGLE_THREAD_MODEL
Constructor Summary
protected ThreadPolicyValue(int value)
Method Summary
static ThreadPolicyValue | from_int(int value)
int | value()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_ORB_CTRL_MODEL

public static final int _ORB_CTRL_MODEL
See Also:
Constant Field Values

ORB_CTRL_MODEL

public static final ThreadPolicyValue ORB_CTRL_MODEL

_SINGLE_THREAD_MODEL

public static final int _SINGLE_THREAD_MODEL
See Also:
Constant Field Values

SINGLE_THREAD_MODEL

public static final ThreadPolicyValue SINGLE_THREAD_MODEL
Constructor Detail

ThreadPolicyValue

protected ThreadPolicyValue(int value)
Method Detail

value

public int value()

from_int

public static ThreadPolicyValue from_int(int value)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


THREAD_POLICY_ID

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.omg.PortableServer
Interface THREAD_POLICY_ID

public interface THREAD_POLICY_ID

org/omg/PortableServer/THREAD_POLICY_ID.java . Generated by the IDL-to-Java compiler (portable), version "3.2" from ../../../../src/share/classes/org/omg/PortableServer/poa.idl Wednesday, November 29, 2006 1:57:21 AM GMT-08:00

Field Summary
static int value
The value representing THREAD_POLICY_ID.

Field Detail

value

static final int value
The value representing THREAD_POLICY_ID.

See Also:
Constant Field Values
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SendingContext

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.SendingContext

Provides support for the marshalling of value types.

See:
Description

Interface Summary
RunTime | Defines the base class that represents the Sending Context of a request.
RunTimeOperations | Defines operations on the base class that represents the Sending Context of a request.

Package org.omg.SendingContext Description

Provides support for the marshalling of value types. Value type marshalling may require access to an implementation of the value type or to meta information about the value type. This information is passed between the sending context and the receiving context using a particular service context containing an instance of the SendingContext.RunTime interface.

A sending context may be either the client side or the server side of an invocation, depending on which contains a value type. The sending context is the client side of an invocation if the request contains a value type. It is the server side if the reply contains a value type. The other party in the communication is the receiving context.

The service context marshalled for SendingContext consists of an encapsulated IOR for the SendingContext.RunTime interface. RunTime is just a marker interface defined to allow extensibility in the future. There is currently only one subinterface of RunTime defined: the SendingContext.CodeBase interface. The interface CodeBase defines operations to obtain code URLs and meta-information about a value type received from the sending context.

Note that these classes are currently defined in the com.sun.org.omg.SendingContext package rather than in the package org.omg.SendingContext. This has been done to avoid including large parts of the interface repository in the JDK core, since the interface repository is still evolving in response to the needs of the CORBA Components work.

Package Specification

For a precise list of supported sections of official specifications with which the Java[tm] Platform, Standard Edition 6 ORB complies, see Official Specifications for CORBA support in Java[tm] SE 6.

Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.SendingContext Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.SendingContext

Package Hierarchies:
All Packages

Interface Hierarchy

  • org.omg.CORBA.Object
    • org.omg.SendingContext.RunTime (also extends org.omg.CORBA.portable.IDLEntity, org.omg.SendingContext.RunTimeOperations)
  • org.omg.SendingContext.RunTimeOperations
    • org.omg.SendingContext.RunTime (also extends org.omg.CORBA.portable.IDLEntity, org.omg.CORBA.Object)
  • java.io.Serializable
    • org.omg.CORBA.portable.IDLEntity
      • org.omg.SendingContext.RunTime (also extends org.omg.CORBA.Object, org.omg.SendingContext.RunTimeOperations)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


RunTime

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.SendingContext
Interface RunTime

All Superinterfaces:
IDLEntity, Object, RunTimeOperations, Serializable
public interface RunTime
extends RunTimeOperations, Object, IDLEntity

Defines the base class that represents the Sending Context of a request. The sending context provides access to information about the runtime environment of the originator of a GIOP message. For example, when a value type is marshalled on a GIOP Request message, the receiver of the value type may need to ask the sender about the CodeBase for the implementation of the value type.

Method Summary
Methods inherited from interface org.omg.CORBA.Object
_create_request, _create_request, _duplicate, _get_domain_managers, _get_interface_def, _get_policy, _hash, _is_a, _is_equivalent, _non_existent, _release, _request, _set_policy_override

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


RunTimeOperations

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.omg.SendingContext
Interface RunTimeOperations

All Known Subinterfaces:
RunTime
public interface RunTimeOperations

Defines operations on the base class that represents the Sending Context of a request. The sending context provides access to information about the runtime environment of the originator of a GIOP message. For example, when a value type is marshalled on a GIOP Request message, the receiver of the value type may need to ask the sender about the CodeBase for the implementation of the value type.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Package org.omg.SendingContext

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.SendingContext

Packages that use org.omg.SendingContext
javax.rmi.CORBA | Contains portability APIs for RMI-IIOP.
org.omg.SendingContext | Provides support for the marshalling of value types.

Classes in org.omg.SendingContext used by javax.rmi.CORBA
RunTime
Defines the base class that represents the Sending Context of a request.

Classes in org.omg.SendingContext used by org.omg.SendingContext
RunTimeOperations
Defines operations on the base class that represents the Sending Context of a request.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.SendingContext.RunTime

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.SendingContext.RunTime

Packages that use RunTime
javax.rmi.CORBA Contains portability APIs for RMI-IIOP.

Uses of RunTime in javax.rmi.CORBA

Methods in javax.rmi.CORBA that return RunTime
 RunTime ValueHandler.getRunTimeCodeBase()
Returns the CodeBase for this ValueHandler.

Methods in javax.rmi.CORBA with parameters of type RunTime
 Serializable ValueHandler.readValue(InputStream in, int offset, Class clz, String repositoryID, RunTime sender)
Reads a value from the stream using Java semantics.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.omg.SendingContext.RunTimeOperations

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.omg.SendingContext.RunTimeOperations

Packages that use RunTimeOperations
org.omg.SendingContext Provides support for the marshalling of value types.

Uses of RunTimeOperations in org.omg.SendingContext

Subinterfaces of RunTimeOperations in org.omg.SendingContext
 interface RunTime
Defines the base class that represents the Sending Context of a request.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


rmi

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.omg.stub.java.rmi

Contains RMI-IIOP Stubs for the Remote types that occur in the java.rmi package.

See:
Description

Class Summary
_Remote_Stub This class provides the Stub for the Remote Type.

Package org.omg.stub.java.rmi Description

Contains RMI-IIOP Stubs for the Remote types that occur in the java.rmi package.

Since:
1.3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.omg.stub.java.rmi Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.omg.stub.java.rmi

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.omg.CORBA.portable.ObjectImpl (implements org.omg.CORBA.Object)
      • org.omg.CORBA_2_3.portable.ObjectImpl
        • javax.rmi.CORBA.Stub (implements java.io.Serializable)
          • org.omg.stub.java.rmi._Remote_Stub (implements java.rmi.Remote)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.omg.stub.java.rmi

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.omg.stub.java.rmi

No usage of org.omg.stub.java.rmi

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.omg.stub.java.rmi._Remote_Stub

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.omg.stub.java.rmi._Remote_Stub

No usage of org.omg.stub.java.rmi._Remote_Stub

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


dom

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.w3c.dom

Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.

See:
Description

Interface Summary
Attr | The Attr interface represents an attribute in an Element object.
CDATASection | CDATA sections are used to escape blocks of text containing characters that would otherwise be regarded as markup.
CharacterData | The CharacterData interface extends Node with a set of attributes and methods for accessing character data in the DOM.
Comment | This interface inherits from CharacterData and represents the content of a comment, i.e., all the characters between the starting ' <!--' and ending '-->'.
Document | The Document interface represents the entire HTML or XML document.
DocumentFragment | DocumentFragment is a "lightweight" or "minimal" Document object.
DocumentType | Each Document has a doctype attribute whose value is either null or a DocumentType object.
DOMConfiguration | The DOMConfiguration interface represents the configuration of a document and maintains a table of recognized parameters.
DOMError | DOMError is an interface that describes an error.
DOMErrorHandler | DOMErrorHandler is a callback interface that the DOM implementation can call when reporting errors that happens while processing XML data, or when doing some other processing (e.g.
DOMImplementation | The DOMImplementation interface provides a number of methods for performing operations that are independent of any particular instance of the document object model.
DOMImplementationList | The DOMImplementationList interface provides the abstraction of an ordered collection of DOM implementations, without defining or constraining how this collection is implemented.
DOMImplementationSource | This interface permits a DOM implementer to supply one or more implementations, based upon requested features and versions, as specified in .
DOMLocator | DOMLocator is an interface that describes a location (e.g.
DOMStringList | The DOMStringList interface provides the abstraction of an ordered collection of DOMString values, without defining or constraining how this collection is implemented.
Element | The Element interface represents an element in an HTML or XML document.
Entity | This interface represents a known entity, either parsed or unparsed, in an XML document.
EntityReference | EntityReference nodes may be used to represent an entity reference in the tree.
NamedNodeMap | Objects implementing the NamedNodeMap interface are used to represent collections of nodes that can be accessed by name.
NameList | The NameList interface provides the abstraction of an ordered collection of parallel pairs of name and namespace values (which could be null values), without defining or constraining how this collection is implemented.
Node | The Node interface is the primary datatype for the entire Document Object Model.
NodeList | The NodeList interface provides the abstraction of an ordered collection of nodes, without defining or constraining how this collection is implemented.
Notation | This interface represents a notation declared in the DTD.
ProcessingInstruction | The ProcessingInstruction interface represents a "processing instruction", used in XML as a way to keep processor-specific information in the text of the document.
Text | The Text interface inherits from CharacterData and represents the textual content (termed character data in XML) of an Element or Attr.
TypeInfo | The TypeInfo interface represents a type referenced from Element or Attr nodes, specified in the schemas associated with the document.
UserDataHandler | When associating an object to a key on a node using Node.setUserData() the application can provide a handler that gets called when the node the object is associated to is being cloned, imported, or renamed.

Exception Summary
DOMException DOM operations only raise exceptions in "exceptional" circumstances, i.e., when an operation is impossible to perform (either for logical reasons, because data is lost, or because the implementation has become unstable).

Package org.w3c.dom Description

Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing. The Document Object Model Level 2 Core API allows programs to dynamically access and update the content and structure of documents. See the specification for more information.

Since:
JDK1.4
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


CDATASection

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface CDATASection

All Superinterfaces:
CharacterData, Node, Text
public interface CDATASection
extends Text

CDATA sections are used to escape blocks of text containing characters that would otherwise be regarded as markup. The only delimiter that is recognized in a CDATA section is the "]]>" string that ends the CDATA section. CDATA sections cannot be nested. Their primary purpose is for including material such as XML fragments, without needing to escape all the delimiters.

The CharacterData.data attribute holds the text that is contained by the CDATA section. Note that this may contain characters that need to be escaped outside of CDATA sections and that, depending on the character encoding ("charset") chosen for serialization, it may be impossible to write out some characters as part of a CDATA section.

The CDATASection interface inherits from the CharacterData interface through the Text interface. Adjacent CDATASection nodes are not merged by use of the normalize method of the Node interface.

No lexical check is done on the content of a CDATA section and it is therefore possible to have the character sequence "]]>" in the content, which is illegal in a CDATA section per section 2.7 of [XML 1.0]. The presence of this character sequence must generate a fatal error during serialization or the cdata section must be splitted before the serialization (see also the parameter "split-cdata-sections" in the DOMConfiguration interface).

Note: Because no markup is recognized within a CDATASection, character numeric references cannot be used as an escape mechanism when serializing. Therefore, action needs to be taken when serializing a CDATASection with a character encoding where some of the contained characters cannot be represented. Failure to do so would not produce well-formed XML.

Note: One potential solution in the serialization process is to end the CDATA section before the character, output the character using a character reference or entity reference, and open a new CDATA section for any further characters in the text node. Note, however, that some code conversion libraries at the time of writing do not return an error or exception when a character is missing from the encoding, making the task of ensuring that data is not corrupted on serialization more difficult.

See also the Document Object Model (DOM) Level 3 Core Specification.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
Methods inherited from interface org.w3c.dom.Text
getWholeText, isElementContentWhitespace, replaceWholeText, splitText
Methods inherited from interface org.w3c.dom.CharacterData
appendData, deleteData, getData, getLength, insertData, replaceData, setData, substringData
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Comment

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface Comment

All Superinterfaces:
CharacterData, Node
public interface Comment
extends CharacterData

This interface inherits from CharacterData and represents the content of a comment, i.e., all the characters between the starting ' <!--' and ending '-->'. Note that this is the definition of a comment in XML, and, in practice, HTML, although some HTML tools may implement the full SGML comment structure.

No lexical check is done on the content of a comment and it is therefore possible to have the character sequence "--" (double-hyphen) in the content, which is illegal in a comment per section 2.5 of [XML 1.0]. The presence of this character sequence must generate a fatal error during serialization.

See also the Document Object Model (DOM) Level 3 Core Specification.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
Methods inherited from interface org.w3c.dom.CharacterData
appendData, deleteData, getData, getLength, insertData, replaceData, setData, substringData
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocumentFragment

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface DocumentFragment

All Superinterfaces:
Node
public interface DocumentFragment
extends Node

DocumentFragment is a "lightweight" or "minimal" Document object. It is very common to want to be able to extract a portion of a document's tree or to create a new fragment of a document. Imagine implementing a user command like cut or rearranging a document by moving fragments around. It is desirable to have an object which can hold such fragments and it is quite natural to use a Node for this purpose. While it is true that a Document object could fulfill this role, a Document object can potentially be a heavyweight object, depending on the underlying implementation. What is really needed for this is a very lightweight object. DocumentFragment is such an object.

Furthermore, various operations -- such as inserting nodes as children of another Node -- may take DocumentFragment objects as arguments; this results in all the child nodes of the DocumentFragment being moved to the child list of this node.

The children of a DocumentFragment node are zero or more nodes representing the tops of any sub-trees defining the structure of the document. DocumentFragment nodes do not need to be well-formed XML documents (although they do need to follow the rules imposed upon well-formed XML parsed entities, which can have multiple top nodes). For example, a DocumentFragment might have only one child and that child node could be a Text node. Such a structure model represents neither an HTML document nor a well-formed XML document.

When a DocumentFragment is inserted into a Document (or indeed any other Node that may take children) the children of the DocumentFragment and not the DocumentFragment itself are inserted into the Node. This makes the DocumentFragment very useful when the user wishes to create nodes that are siblings; the DocumentFragment acts as the parent of these nodes so that the user can use the standard methods from the Node interface, such as Node.insertBefore and Node.appendChild.

See also the Document Object Model (DOM) Level 3 Core Specification.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EntityReference

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface EntityReference

All Superinterfaces:
Node
public interface EntityReference
extends Node

EntityReference nodes may be used to represent an entity reference in the tree. Note that character references and references to predefined entities are considered to be expanded by the HTML or XML processor so that characters are represented by their Unicode equivalent rather than by an entity reference. Moreover, the XML processor may completely expand references to entities while building the Document, instead of providing EntityReference nodes. If it does provide such nodes, then for an EntityReference node that represents a reference to a known entity an Entity exists, and the subtree of the EntityReference node is a copy of the Entity node subtree. However, the latter may not be true when an entity contains an unbound namespace prefix. In such a case, because the namespace prefix resolution depends on where the entity reference is, the descendants of the EntityReference node may be bound to different namespace URIs. When an EntityReference node represents a reference to an unknown entity, the node has no children and its replacement value, when used by Attr.value for example, is empty.

As for Entity nodes, EntityReference nodes and all their descendants are readonly.

Note: EntityReference nodes may cause element content and attribute value normalization problems when, such as in XML 1.0 and XML Schema, the normalization is performed after entity reference are expanded.

See also the Document Object Model (DOM) Level 3 Core Specification.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


org.w3c.dom Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.w3c.dom

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.lang.RuntimeException
          • org.w3c.dom.DOMException

Interface Hierarchy

  • org.w3c.dom.DOMConfiguration
  • org.w3c.dom.DOMError
  • org.w3c.dom.DOMErrorHandler
  • org.w3c.dom.DOMImplementation
  • org.w3c.dom.DOMImplementationList
  • org.w3c.dom.DOMImplementationSource
  • org.w3c.dom.DOMLocator
  • org.w3c.dom.DOMStringList
  • org.w3c.dom.NamedNodeMap
  • org.w3c.dom.NameList
  • org.w3c.dom.Node
    • org.w3c.dom.Attr
    • org.w3c.dom.CharacterData
      • org.w3c.dom.Comment
      • org.w3c.dom.Text
        • org.w3c.dom.CDATASection
    • org.w3c.dom.Document
    • org.w3c.dom.DocumentFragment
    • org.w3c.dom.DocumentType
    • org.w3c.dom.Element
    • org.w3c.dom.Entity
    • org.w3c.dom.EntityReference
    • org.w3c.dom.Notation
    • org.w3c.dom.ProcessingInstruction
  • org.w3c.dom.NodeList
  • org.w3c.dom.TypeInfo
  • org.w3c.dom.UserDataHandler
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.w3c.dom

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.w3c.dom

Packages that use org.w3c.dom
javax.imageio.metadata | A package of the Java Image I/O API dealing with reading and writing metadata.
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.annotation | Defines annotations for customizing Java program elements to XML Schema mapping.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.crypto.dom | DOM-specific classes for the javax.xml.crypto package.
javax.xml.crypto.dsig.dom | DOM-specific classes for the javax.xml.crypto.dsig package.
javax.xml.parsers | Provides classes allowing the processing of XML documents.
javax.xml.soap | Provides the API for creating and building SOAP messages.
javax.xml.transform.dom | This package implements DOM-specific transformation APIs.
javax.xml.validation | This package provides an API for validation of XML documents.
org.w3c.dom | Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.
org.w3c.dom.bootstrap |
org.w3c.dom.events |
org.w3c.dom.ls |

Classes in org.w3c.dom used by javax.imageio.metadata
Attr
The Attr interface represents an attribute in an Element object.
Document
The Document interface represents the entire HTML or XML document.
DOMException
DOM operations only raise exceptions in "exceptional" circumstances, i.e., when an operation is impossible to perform (either for logical reasons, because data is lost, or because the implementation has become unstable).
Element
The Element interface represents an element in an HTML or XML document.
NamedNodeMap
Objects implementing the NamedNodeMap interface are used to represent collections of nodes that can be accessed by name.
Node
The Node interface is the primary datatype for the entire Document Object Model.
NodeList
The NodeList interface provides the abstraction of an ordered collection of nodes, without defining or constraining how this collection is implemented.
TypeInfo
The TypeInfo interface represents a type referenced from Element or Attr nodes, specified in the schemas associated with the document.
UserDataHandler
When associating an object to a key on a node using Node.setUserData() the application can provide a handler that gets called when the node the object is associated to is being cloned, imported, or renamed.

Classes in org.w3c.dom used by javax.xml.bind
Node
The Node interface is the primary datatype for the entire Document Object Model.

Classes in org.w3c.dom used by javax.xml.bind.annotation
Element
The Element interface represents an element in an HTML or XML document.

Classes in org.w3c.dom used by javax.xml.bind.helpers
Node
The Node interface is the primary datatype for the entire Document Object Model.

Classes in org.w3c.dom used by javax.xml.crypto.dom
Element
The Element interface represents an element in an HTML or XML document.
Node
The Node interface is the primary datatype for the entire Document Object Model.

Classes in org.w3c.dom used by javax.xml.crypto.dsig.dom
Node
The Node interface is the primary datatype for the entire Document Object Model.

Classes in org.w3c.dom used by javax.xml.parsers
Document
The Document interface represents the entire HTML or XML document.
DOMImplementation
The DOMImplementation interface provides a number of methods for performing operations that are independent of any particular instance of the document object model.

Classes in org.w3c.dom used by javax.xml.soap
Document
The Document interface represents the entire HTML or XML document.
Element
The Element interface represents an element in an HTML or XML document.
Node
The Node interface is the primary datatype for the entire Document Object Model.
Text
The Text interface inherits from CharacterData and represents the textual content (termed character data in XML) of an Element or Attr.

Classes in org.w3c.dom used by javax.xml.transform.dom
Node
The Node interface is the primary datatype for the entire Document Object Model.

Classes in org.w3c.dom used by javax.xml.validation
TypeInfo
The TypeInfo interface represents a type referenced from Element or Attr nodes, specified in the schemas associated with the document.

Classes in org.w3c.dom used by org.w3c.dom
Attr
The Attr interface represents an attribute in an Element object.
CDATASection
CDATA sections are used to escape blocks of text containing characters that would otherwise be regarded as markup.
CharacterData
The CharacterData interface extends Node with a set of attributes and methods for accessing character data in the DOM.
Comment
This interface inherits from CharacterData and represents the content of a comment, i.e., all the characters between the starting ' <!--' and ending '-->'.
Document
The Document interface represents the entire HTML or XML document.
DocumentFragment
DocumentFragment is a "lightweight" or "minimal" Document object.
DocumentType
Each Document has a doctype attribute whose value is either null or a DocumentType object.
DOMConfiguration
The DOMConfiguration interface represents the configuration of a document and maintains a table of recognized parameters.
DOMError
DOMError is an interface that describes an error.
DOMException
DOM operations only raise exceptions in "exceptional" circumstances, i.e., when an operation is impossible to perform (either for logical reasons, because data is lost, or because the implementation has become unstable).
DOMImplementation
The DOMImplementation interface provides a number of methods for performing operations that are independent of any particular instance of the document object model.
DOMImplementationList
The DOMImplementationList interface provides the abstraction of an ordered collection of DOM implementations, without defining or constraining how this collection is implemented.
DOMLocator
DOMLocator is an interface that describes a location (e.g.
DOMStringList
The DOMStringList interface provides the abstraction of an ordered collection of DOMString values, without defining or constraining how this collection is implemented.
Element
The Element interface represents an element in an HTML or XML document.
EntityReference
EntityReference nodes may be used to represent an entity reference in the tree.
NamedNodeMap
Objects implementing the NamedNodeMap interface are used to represent collections of nodes that can be accessed by name.
Node
The Node interface is the primary datatype for the entire Document Object Model.
NodeList
The NodeList interface provides the abstraction of an ordered collection of nodes, without defining or constraining how this collection is implemented.
ProcessingInstruction
The ProcessingInstruction interface represents a "processing instruction", used in XML as a way to keep processor-specific information in the text of the document.
Text
The Text interface inherits from CharacterData and represents the textual content (termed character data in XML) of an Element or Attr.
TypeInfo
The TypeInfo interface represents a type referenced from Element or Attr nodes, specified in the schemas associated with the document.
UserDataHandler
When associating an object to a key on a node using Node.setUserData() the application can provide a handler that gets called when the node the object is associated to is being cloned, imported, or renamed.

Classes in org.w3c.dom used by org.w3c.dom.bootstrap
DOMImplementation
The DOMImplementation interface provides a number of methods for performing operations that are independent of any particular instance of the document object model.
DOMImplementationList
The DOMImplementationList interface provides the abstraction of an ordered collection of DOM implementations, without defining or constraining how this collection is implemented.
DOMImplementationSource
This interface permits a DOM implementer to supply one or more implementations, based upon requested features and versions, as specified in .

Classes in org.w3c.dom used by org.w3c.dom.events
DOMException
DOM operations only raise exceptions in "exceptional" circumstances, i.e., when an operation is impossible to perform (either for logical reasons, because data is lost, or because the implementation has become unstable).
Node
The Node interface is the primary datatype for the entire Document Object Model.

Classes in org.w3c.dom used by org.w3c.dom.ls
Document
The Document interface represents the entire HTML or XML document.
DOMConfiguration
The DOMConfiguration interface represents the configuration of a document and maintains a table of recognized parameters.
DOMException
DOM operations only raise exceptions in "exceptional" circumstances, i.e., when an operation is impossible to perform (either for logical reasons, because data is lost, or because the implementation has become unstable).
Element
The Element interface represents an element in an HTML or XML document.
Node
The Node interface is the primary datatype for the entire Document Object Model.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Attr

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface Attr

All Superinterfaces:
Node
public interface Attr
extends Node

The Attr interface represents an attribute in an Element object. Typically the allowable values for the attribute are defined in a schema associated with the document.

Attr objects inherit the Node interface, but since they are not actually child nodes of the element they describe, the DOM does not consider them part of the document tree. Thus, the Node attributes parentNode, previousSibling, and nextSibling have a null value for Attr objects. The DOM takes the view that attributes are properties of elements rather than having a separate identity from the elements they are associated with; this should make it more efficient to implement such features as default attributes associated with all elements of a given type. Furthermore, Attr nodes may not be immediate children of a DocumentFragment. However, they can be associated with Element nodes contained within a DocumentFragment. In short, users and implementors of the DOM need to be aware that Attr nodes have some things in common with other objects inheriting the Node interface, but they also are quite distinct.

The attribute's effective value is determined as follows: if this attribute has been explicitly assigned any value, that value is the attribute's effective value; otherwise, if there is a declaration for this attribute, and that declaration includes a default value, then that default value is the attribute's effective value; otherwise, the attribute does not exist on this element in the structure model until it has been explicitly added. Note that the Node.nodeValue attribute on the Attr instance can also be used to retrieve the string version of the attribute's value(s).

If the attribute was not explicitly given a value in the instance document but has a default value provided by the schema associated with the document, an attribute node will be created with specified set to false. Removing attribute nodes for which a default value is defined in the schema generates a new attribute node with the default value and specified set to false. If validation occurred while invoking Document.normalizeDocument(), attribute nodes with specified equals to false are recomputed according to the default attribute values provided by the schema. If no default value is associate with this attribute in the schema, the attribute node is discarded.

In XML, where the value of an attribute can contain entity references, the child nodes of the Attr node may be either Text or EntityReference nodes (when these are in use; see the description of EntityReference for discussion).

The DOM Core represents all attribute values as simple strings, even if the DTD or schema associated with the document declares them of some specific type such as tokenized.

The way attribute value normalization is performed by the DOM implementation depends on how much the implementation knows about the schema in use. Typically, the value and nodeValue attributes of an Attr node initially returns the normalized value given by the parser. It is also the case after Document.normalizeDocument() is called (assuming the right options have been set). But this may not be the case after mutation, independently of whether the mutation is performed by setting the string value directly or by changing the Attr child nodes. In particular, this is true when character references are involved, given that they are not represented in the DOM and they impact attribute value normalization. On the other hand, if the implementation knows about the schema in use when the attribute value is changed, and it is of a different type than CDATA, it may normalize it again at that time. This is especially true of specialized DOM implementations, such as SVG DOM implementations, which store attribute values in an internal form different from a string.

The following table gives some examples of the relations between the attribute value in the original document (parsed attribute), the value as exposed in the DOM, and the serialization of the value:
Examples Parsed attribute value Initial Attr.value Serialized attribute value
Character reference
"x&#178;=5"

"x²=5"

"x&#178;=5"
Built-in character entity
"y&lt;6"

"y<6"

"y&lt;6"
Literal newline between
 "x=5&#10;y=6"

"x=5 y=6"

"x=5&#10;y=6"
Normalized newline between
"x=5
 y=6"

"x=5 y=6"

"x=5 y=6"
Entity e with literal newline
 <!ENTITY e '...&#10;...'> [...]> "x=5&e;y=6"
 Dependent on Implementation and Load Options Dependent on Implementation and Load/Save Options

See also the Document Object Model (DOM) Level 3 Core Specification.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
String | getName() Returns the name of this attribute.
Element | getOwnerElement() The Element node this attribute is attached to or null if this attribute is not in use.
TypeInfo | getSchemaTypeInfo() The type information associated with this attribute.
boolean | getSpecified() True if this attribute was explicitly given a value in the instance document, false otherwise.
String | getValue() On retrieval, the value of the attribute is returned as a string.
boolean | isId() Returns whether this attribute is known to be of type ID (i.e.
void | setValue(String value) On retrieval, the value of the attribute is returned as a string.
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

getName

String getName()
Returns the name of this attribute. If Node.localName is different from null, this attribute is a qualified name.

getSpecified

boolean getSpecified()
True if this attribute was explicitly given a value in the instance document, false otherwise. If the application changed the value of this attribute node (even if it ends up having the same value as the default value) then it is set to true. The implementation may handle attributes with default values from other schemas similarly but applications should use Document.normalizeDocument() to guarantee this information is up-to-date.

getValue

String getValue()
On retrieval, the value of the attribute is returned as a string. Character and general entity references are replaced with their values. See also the method getAttribute on the Element interface.
On setting, this creates a Text node with the unparsed contents of the string, i.e. any characters that an XML processor would recognize as markup are instead treated as literal text. See also the method Element.setAttribute().
Some specialized implementations, such as some [SVG 1.1] implementations, may do normalization automatically, even after mutation; in such case, the value on retrieval may differ from the value on setting.

setValue

void setValue(String value)
              throws DOMException
On retrieval, the value of the attribute is returned as a string. Character and general entity references are replaced with their values. See also the method getAttribute on the Element interface.
On setting, this creates a Text node with the unparsed contents of the string, i.e. any characters that an XML processor would recognize as markup are instead treated as literal text. See also the method Element.setAttribute().
Some specialized implementations, such as some [SVG 1.1] implementations, may do normalization automatically, even after mutation; in such case, the value on retrieval may differ from the value on setting.

Throws:
DOMException - NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.

getOwnerElement

Element getOwnerElement()
The Element node this attribute is attached to or null if this attribute is not in use.

Since:
DOM Level 2

getSchemaTypeInfo

TypeInfo getSchemaTypeInfo()
The type information associated with this attribute. While the type information contained in this attribute is guarantee to be correct after loading the document or invoking Document.normalizeDocument(), schemaTypeInfo may not be reliable if the node was moved.

Since:
DOM Level 3

isId

boolean isId()
Returns whether this attribute is known to be of type ID (i.e. to contain an identifier for its owner element) or not. When it is and its value is unique, the ownerElement of this attribute can be retrieved using the method Document.getElementById . The implementation could use several ways to determine if an attribute node is known to contain an identifier:
  • If validation occurred using an XML Schema [XML Schema Part 1] while loading the document or while invoking Document.normalizeDocument(), the post-schema-validation infoset contributions (PSVI contributions) values are used to determine if this attribute is a schema-determined ID attribute using the schema-determined ID definition in [XPointer] .
  • If validation occurred using a DTD while loading the document or while invoking Document.normalizeDocument(), the infoset [type definition] value is used to determine if this attribute is a DTD-determined ID attribute using the DTD-determined ID definition in [XPointer] .
  • from the use of the methods Element.setIdAttribute(), Element.setIdAttributeNS(), or Element.setIdAttributeNode(), i.e. it is an user-determined ID attribute;

    Note: XPointer framework (see section 3.2 in [XPointer] ) consider the DOM user-determined ID attribute as being part of the XPointer externally-determined ID definition.

  • using mechanisms that are outside the scope of this specification, it is then an externally-determined ID attribute. This includes using schema languages different from XML schema and DTD.

If validation occurred while invoking Document.normalizeDocument(), all user-determined ID attributes are reset and all attribute nodes ID information are then reevaluated in accordance to the schema used. As a consequence, if the Attr.schemaTypeInfo attribute contains an ID type, isId will always return true.

Since:
DOM Level 3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


bootstrap

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.w3c.dom.bootstrap

Class Summary
DOMImplementationRegistry A factory that enables applications to obtain instances of DOMImplementation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.w3c.dom.bootstrap Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.w3c.dom.bootstrap

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.w3c.dom.bootstrap.DOMImplementationRegistry
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.w3c.dom.bootstrap

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.w3c.dom.bootstrap

Packages that use org.w3c.dom.bootstrap
org.w3c.dom.bootstrap

Classes in org.w3c.dom.bootstrap used by org.w3c.dom.bootstrap
DOMImplementationRegistry
A factory that enables applications to obtain instances of DOMImplementation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.w3c.dom.bootstrap.DOMImplementationRegistry

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.w3c.dom.bootstrap.DOMImplementationRegistry

Packages that use DOMImplementationRegistry
org.w3c.dom.bootstrap

Uses of DOMImplementationRegistry in org.w3c.dom.bootstrap

Methods in org.w3c.dom.bootstrap that return DOMImplementationRegistry
static DOMImplementationRegistry DOMImplementationRegistry.newInstance()
Obtain a new instance of a DOMImplementationRegistry.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DOMImplementationRegistry

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.bootstrap
Class DOMImplementationRegistry

java.lang.Object
    extended by  org.w3c.dom.bootstrap.DOMImplementationRegistry

public final class DOMImplementationRegistry
extends Object

A factory that enables applications to obtain instances of DOMImplementation.

Example:

  // get an instance of the DOMImplementation registry
  DOMImplementationRegistry registry =
       DOMImplementationRegistry.newInstance();
  // get a DOM implementation the Level 3 XML module
  DOMImplementation domImpl =
       registry.getDOMImplementation("XML 3.0");

This provides an application with an implementation-independent starting point. DOM implementations may modify this class to meet new security standards or to provide *additional* fallbacks for the list of DOMImplementationSources.

Since:
DOM Level 3
See Also:
DOMImplementation, DOMImplementationSource

Field Summary
static String PROPERTY
The system property to specify the DOMImplementationSource class names.
Method Summary
void | addSource(DOMImplementationSource s) Register an implementation.
DOMImplementation | getDOMImplementation(String features) Return the first implementation that has the desired features, or null if none is found.
DOMImplementationList | getDOMImplementationList(String features) Return a list of implementations that support the desired features.
static DOMImplementationRegistry | newInstance() Obtain a new instance of a DOMImplementationRegistry.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROPERTY

public static final String PROPERTY
The system property to specify the DOMImplementationSource class names.

See Also:
Constant Field Values
Method Detail

newInstance

public static DOMImplementationRegistry newInstance()
                                             throws ClassNotFoundException,
                                                    InstantiationException,
                                                    IllegalAccessException,
                                                    ClassCastException
Obtain a new instance of a DOMImplementationRegistry. The DOMImplementationRegistry is initialized by the application or the implementation, depending on the context, by first checking the value of the Java system property org.w3c.dom.DOMImplementationSourceList and the the service provider whose contents are at "META_INF/services/org.w3c.dom.DOMImplementationSourceList" The value of this property is a white-space separated list of names of availables classes implementing the DOMImplementationSource interface. Each class listed in the class name list is instantiated and any exceptions encountered are thrown to the application.

Returns:
an initialized instance of DOMImplementationRegistry
Throws:
ClassNotFoundException - If any specified class can not be found
InstantiationException - If any specified class is an interface or abstract class
IllegalAccessException - If the default constructor of a specified class is not accessible
ClassCastException - If any specified class does not implement DOMImplementationSource

getDOMImplementation

public DOMImplementation getDOMImplementation(String features)
Return the first implementation that has the desired features, or null if none is found.

Parameters:
features - A string that specifies which features are required. This is a space separated list in which each feature is specified by its name optionally followed by a space and a version number. This is something like: "XML 1.0 Traversal +Events 2.0"
Returns:
An implementation that has the desired features, or null if none found.

getDOMImplementationList

public DOMImplementationList getDOMImplementationList(String features)
Return a list of implementations that support the desired features.

Parameters:
features - A string that specifies which features are required. This is a space separated list in which each feature is specified by its name optionally followed by a space and a version number. This is something like: "XML 1.0 Traversal +Events 2.0"
Returns:
A list of DOMImplementations that support the desired features.

addSource

public void addSource(DOMImplementationSource s)
Register an implementation.

Parameters:
s - The source to be registered, may not be null
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


CharacterData

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface CharacterData

All Superinterfaces:
Node
All Known Subinterfaces:
CDATASection, Comment, Text, Text
public interface CharacterData
extends Node

The CharacterData interface extends Node with a set of attributes and methods for accessing character data in the DOM. For clarity this set is defined here rather than on each object that uses these attributes and methods. No DOM objects correspond directly to CharacterData, though Text and others do inherit the interface from it. All offsets in this interface start from 0.

As explained in the DOMString interface, text strings in the DOM are represented in UTF-16, i.e. as a sequence of 16-bit units. In the following, the term 16-bit units is used whenever necessary to indicate that indexing on CharacterData is done in 16-bit units.

See also the Document Object Model (DOM) Level 3 Core Specification.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
void | appendData(String arg) Append the string to the end of the character data of the node.
void | deleteData(int offset, int count) Remove a range of 16-bit units from the node.
String | getData() The character data of the node that implements this interface.
int | getLength() The number of 16-bit units that are available through data and the substringData method below.
void | insertData(int offset, String arg) Insert a string at the specified 16-bit unit offset.
void | replaceData(int offset, int count, String arg) Replace the characters starting at the specified 16-bit unit offset with the specified string.
void | setData(String data) The character data of the node that implements this interface.
String | substringData(int offset, int count) Extracts a range of data from the node.
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

getData

String getData()
               throws DOMException
The character data of the node that implements this interface. The DOM implementation may not put arbitrary limits on the amount of data that may be stored in a CharacterData node. However, implementation limits may mean that the entirety of a node's data may not fit into a single DOMString. In such cases, the user may call substringData to retrieve the data in appropriately sized pieces.

Throws:
DOMException - DOMSTRING_SIZE_ERR: Raised when it would return more characters than fit in a DOMString variable on the implementation platform.

setData

void setData(String data)
             throws DOMException
The character data of the node that implements this interface. The DOM implementation may not put arbitrary limits on the amount of data that may be stored in a CharacterData node. However, implementation limits may mean that the entirety of a node's data may not fit into a single DOMString. In such cases, the user may call substringData to retrieve the data in appropriately sized pieces.

Throws:
DOMException - NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.

getLength

int getLength()
The number of 16-bit units that are available through data and the substringData method below. This may have the value zero, i.e., CharacterData nodes may be empty.

substringData

String substringData(int offset,
                     int count)
                     throws DOMException
Extracts a range of data from the node.

Parameters:
offset - Start offset of substring to extract.
count - The number of 16-bit units to extract.
Returns:
The specified substring. If the sum of offset and count exceeds the length, then all 16-bit units to the end of the data are returned.
Throws:
DOMException - INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data, or if the specified count is negative.
DOMSTRING_SIZE_ERR: Raised if the specified range of text does not fit into a DOMString.

appendData

void appendData(String arg)
                throws DOMException
Append the string to the end of the character data of the node. Upon success, data provides access to the concatenation of data and the DOMString specified.

Parameters:
arg - The DOMString to append.
Throws:
DOMException - NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

insertData

void insertData(int offset,
                String arg)
                throws DOMException
Insert a string at the specified 16-bit unit offset.

Parameters:
offset - The character offset at which to insert.
arg - The DOMString to insert.
Throws:
DOMException - INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data.
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

deleteData

void deleteData(int offset,
                int count)
                throws DOMException
Remove a range of 16-bit units from the node. Upon success, data and length reflect the change.

Parameters:
offset - The offset from which to start removing.
count - The number of 16-bit units to delete. If the sum of offset and count exceeds length then all 16-bit units from offset to the end of the data are deleted.
Throws:
DOMException - INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data, or if the specified count is negative.
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

replaceData

void replaceData(int offset,
                 int count,
                 String arg)
                 throws DOMException
Replace the characters starting at the specified 16-bit unit offset with the specified string.

Parameters:
offset - The offset from which to start replacing.
count - The number of 16-bit units to replace. If the sum of offset and count exceeds length, then all 16-bit units to the end of the data are replaced; (i.e., the effect is the same as a remove method call with the same range, followed by an append method invocation).
arg - The DOMString with which the range must be replaced.
Throws:
DOMException - INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data, or if the specified count is negative.
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class org.w3c.dom.DOMException

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.w3c.dom.DOMException

Packages that use DOMException
javax.imageio.metadata | A package of the Java Image I/O API dealing with reading and writing metadata.
org.w3c.dom | Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.
org.w3c.dom.events |
org.w3c.dom.ls |

Uses of DOMException in javax.imageio.metadata

Methods in javax.imageio.metadata that throw DOMException
short | IIOMetadataNode.compareDocumentPosition(Node other)
String | IIOMetadataNode.getNamespaceURI() Returns null, since namespaces are not supported.
String | IIOMetadataNode.getNodeValue()
String | IIOMetadataNode.getTextContent()
Attr | IIOMetadataNode.setAttributeNode(Attr newAttr)
void | IIOMetadataNode.setIdAttribute(String name, boolean isId)
void | IIOMetadataNode.setIdAttributeNode(Attr idAttr, boolean isId)
void | IIOMetadataNode.setIdAttributeNS(String namespaceURI, String localName, boolean isId)
void | IIOMetadataNode.setNodeValue(String nodeValue)
void | IIOMetadataNode.setTextContent(String textContent)

Uses of DOMException in org.w3c.dom

Methods in org.w3c.dom that throw DOMException
Node | Document.adoptNode(Node source) Attempts to adopt a node from another document to this document.
Node | Node.appendChild(Node newChild) Adds the node newChild to the end of the list of children of this node.
void | CharacterData.appendData(String arg) Append the string to the end of the character data of the node.
short | Node.compareDocumentPosition(Node other) Compares the reference node, i.e.
Attr | Document.createAttribute(String name) Creates an Attr of the given name.
Attr | Document.createAttributeNS(String namespaceURI, String qualifiedName) Creates an attribute of the given qualified name and namespace URI.
CDATASection | Document.createCDATASection(String data) Creates a CDATASection node whose value is the specified string.
Document | DOMImplementation.createDocument(String namespaceURI, String qualifiedName, DocumentType doctype) Creates a DOM Document object of the specified type with its document element.
DocumentType | DOMImplementation.createDocumentType(String qualifiedName, String publicId, String systemId) Creates an empty DocumentType node.
Element | Document.createElement(String tagName) Creates an element of the type specified.
Element | Document.createElementNS(String namespaceURI, String qualifiedName) Creates an element of the given qualified name and namespace URI.
EntityReference | Document.createEntityReference(String name) Creates an EntityReference object.
ProcessingInstruction | Document.createProcessingInstruction(String target, String data) Creates a ProcessingInstruction node given the specified name and data strings.
void | CharacterData.deleteData(int offset, int count) Remove a range of 16-bit units from the node.
Attr | Element.getAttributeNodeNS(String namespaceURI, String localName) Retrieves an Attr node by local name and namespace URI.
String | Element.getAttributeNS(String namespaceURI, String localName) Retrieves an attribute value by local name and namespace URI.
String | CharacterData.getData() The character data of the node that implements this interface.
NodeList | Element.getElementsByTagNameNS(String namespaceURI, String localName) Returns a NodeList of all the descendant Elements with a given local name and namespace URI in document order.
Node | NamedNodeMap.getNamedItemNS(String namespaceURI, String localName) Retrieves a node specified by local name and namespace URI.
String | Node.getNodeValue() The value of this node, depending on its type; see the table above.
Object | DOMConfiguration.getParameter(String name) Return the value of a parameter if known.
String | Node.getTextContent() This attribute returns the text content of this node and its descendants.
boolean | Element.hasAttributeNS(String namespaceURI, String localName) Returns true when an attribute with a given local name and namespace URI is specified on this element or has a default value, false otherwise.
Node | Document.importNode(Node importedNode, boolean deep) Imports a node from another document to this document, without altering or removing the source node from the original document; this method creates a new copy of the source node.
Node | Node.insertBefore(Node newChild, Node refChild) Inserts the node newChild before the existing child node refChild.
void | CharacterData.insertData(int offset, String arg) Insert a string at the specified 16-bit unit offset.
void | Element.removeAttribute(String name) Removes an attribute by name.
Attr | Element.removeAttributeNode(Attr oldAttr) Removes the specified attribute node.
void | Element.removeAttributeNS(String namespaceURI, String localName) Removes an attribute by local name and namespace URI.
Node | Node.removeChild(Node oldChild) Removes the child node indicated by oldChild from the list of children, and returns it.
Node | NamedNodeMap.removeNamedItem(String name) Removes a node specified by name.
Node | NamedNodeMap.removeNamedItemNS(String namespaceURI, String localName) Removes a node specified by local name and namespace URI.
Node | Document.renameNode(Node n, String namespaceURI, String qualifiedName) Rename an existing node of type ELEMENT_NODE or ATTRIBUTE_NODE.
Node | Node.replaceChild(Node newChild, Node oldChild) Replaces the child node oldChild with newChild in the list of children, and returns the oldChild node.
void | CharacterData.replaceData(int offset, int count, String arg) Replace the characters starting at the specified 16-bit unit offset with the specified string.
Text | Text.replaceWholeText(String content) Replaces the text of the current node and all logically-adjacent text nodes with the specified text.
void | Element.setAttribute(String name, String value) Adds a new attribute.
Attr | Element.setAttributeNode(Attr newAttr) Adds a new attribute node.
Attr | Element.setAttributeNodeNS(Attr newAttr) Adds a new attribute.
void | Element.setAttributeNS(String namespaceURI, String qualifiedName, String value) Adds a new attribute.
void | ProcessingInstruction.setData(String data) The content of this processing instruction.
void | CharacterData.setData(String data) The character data of the node that implements this interface.
void | Element.setIdAttribute(String name, boolean isId) If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute .
void | Element.setIdAttributeNode(Attr idAttr, boolean isId) If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute .
void | Element.setIdAttributeNS(String namespaceURI, String localName, boolean isId) If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute .
Node | NamedNodeMap.setNamedItem(Node arg) Adds a node using its nodeName attribute.
Node | NamedNodeMap.setNamedItemNS(Node arg) Adds a node using its namespaceURI and localName.
void | Node.setNodeValue(String nodeValue) The value of this node, depending on its type; see the table above.
void | DOMConfiguration.setParameter(String name, Object value) Set the value of a parameter.
void | Node.setPrefix(String prefix) The namespace prefix of this node, or null if it is unspecified.
void | Node.setTextContent(String textContent) This attribute returns the text content of this node and its descendants.
void | Attr.setValue(String value) On retrieval, the value of the attribute is returned as a string.
void | Document.setXmlStandalone(boolean xmlStandalone) An attribute specifying, as part of the XML declaration, whether this document is standalone.
void | Document.setXmlVersion(String xmlVersion) An attribute specifying, as part of the XML declaration, the version number of this document.
Text | Text.splitText(int offset) Breaks this node into two nodes at the specified offset, keeping both in the tree as siblings.
String | CharacterData.substringData(int offset, int count) Extracts a range of data from the node.

Uses of DOMException in org.w3c.dom.events

Methods in org.w3c.dom.events that throw DOMException
 Event DocumentEvent.createEvent(String eventType)

Uses of DOMException in org.w3c.dom.ls

Methods in org.w3c.dom.ls that throw DOMException
LSParser | DOMImplementationLS.createLSParser(short mode, String schemaType) Create a new LSParser.
Document | LSParser.parse(LSInput input) Parse an XML document from a resource identified by a LSInput.
Document | LSParser.parseURI(String uri) Parse an XML document from a location identified by a URI reference [IETF RFC 2396].
Node | LSParser.parseWithContext(LSInput input, Node contextArg, short action) Parse an XML fragment from a resource identified by a LSInput and insert the content into an existing document at the position specified with the context and action arguments.
String | LSSerializer.writeToString(Node nodeArg) Serialize the specified node as described above in the general description of the LSSerializer interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.Attr

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.Attr

Packages that use Attr
javax.imageio.metadata | A package of the Java Image I/O API dealing with reading and writing metadata.
org.w3c.dom | Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.

Uses of Attr in javax.imageio.metadata

Methods in javax.imageio.metadata that return Attr
Attr | IIOMetadataNode.getAttributeNode(String name)
Attr | IIOMetadataNode.getAttributeNodeNS(String namespaceURI, String localName) Equivalent to getAttributeNode(localName).
Attr | IIOMetadataNode.removeAttributeNode(Attr oldAttr)
Attr | IIOMetadataNode.setAttributeNode(Attr newAttr)
Attr | IIOMetadataNode.setAttributeNodeNS(Attr newAttr) Equivalent to setAttributeNode(newAttr).

Methods in javax.imageio.metadata with parameters of type Attr
Attr | IIOMetadataNode.removeAttributeNode(Attr oldAttr)
Attr | IIOMetadataNode.setAttributeNode(Attr newAttr)
Attr | IIOMetadataNode.setAttributeNodeNS(Attr newAttr) Equivalent to setAttributeNode(newAttr).
void | IIOMetadataNode.setIdAttributeNode(Attr idAttr, boolean isId)

Uses of Attr in org.w3c.dom

Methods in org.w3c.dom that return Attr
Attr | Document.createAttribute(String name) Creates an Attr of the given name.
Attr | Document.createAttributeNS(String namespaceURI, String qualifiedName) Creates an attribute of the given qualified name and namespace URI.
Attr | Element.getAttributeNode(String name) Retrieves an attribute node by name.
Attr | Element.getAttributeNodeNS(String namespaceURI, String localName) Retrieves an Attr node by local name and namespace URI.
Attr | Element.removeAttributeNode(Attr oldAttr) Removes the specified attribute node.
Attr | Element.setAttributeNode(Attr newAttr) Adds a new attribute node.
Attr | Element.setAttributeNodeNS(Attr newAttr) Adds a new attribute.

Methods in org.w3c.dom with parameters of type Attr
Attr | Element.removeAttributeNode(Attr oldAttr) Removes the specified attribute node.
Attr | Element.setAttributeNode(Attr newAttr) Adds a new attribute node.
Attr | Element.setAttributeNodeNS(Attr newAttr) Adds a new attribute.
void | Element.setIdAttributeNode(Attr idAttr, boolean isId) If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute .

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.CDATASection

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.CDATASection

Packages that use CDATASection
org.w3c.dom Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.

Uses of CDATASection in org.w3c.dom

Methods in org.w3c.dom that return CDATASection
 CDATASection Document.createCDATASection(String data)
Creates a CDATASection node whose value is the specified string.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.CharacterData

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.CharacterData

Packages that use CharacterData
org.w3c.dom Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.

Uses of CharacterData in org.w3c.dom

Subinterfaces of CharacterData in org.w3c.dom
interface | CDATASection CDATA sections are used to escape blocks of text containing characters that would otherwise be regarded as markup.
interface | Comment This interface inherits from CharacterData and represents the content of a comment, i.e., all the characters between the starting ' <!--' and ending '-->'.
interface | Text The Text interface inherits from CharacterData and represents the textual content (termed character data in XML) of an Element or Attr.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.Comment

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.Comment

Packages that use Comment
org.w3c.dom Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.

Uses of Comment in org.w3c.dom

Methods in org.w3c.dom that return Comment
 Comment Document.createComment(String data)
Creates a Comment node given the specified string.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.Document

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.Document

Packages that use Document
javax.imageio.metadata | A package of the Java Image I/O API dealing with reading and writing metadata.
javax.xml.parsers | Provides classes allowing the processing of XML documents.
javax.xml.soap | Provides the API for creating and building SOAP messages.
org.w3c.dom | Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.
org.w3c.dom.ls |

Uses of Document in javax.imageio.metadata

Methods in javax.imageio.metadata that return Document
 Document IIOMetadataNode.getOwnerDocument()
Returns null, since IIOMetadataNodes do not belong to any Document.

Uses of Document in javax.xml.parsers

Methods in javax.xml.parsers that return Document
abstract Document | DocumentBuilder.newDocument() Obtain a new instance of a DOM Document object to build a DOM tree with.
Document | DocumentBuilder.parse(File f) Parse the content of the given file as an XML document and return a new DOM Document object.
abstract Document | DocumentBuilder.parse(InputSource is) Parse the content of the given input source as an XML document and return a new DOM Document object.
Document | DocumentBuilder.parse(InputStream is) Parse the content of the given InputStream as an XML document and return a new DOM Document object.
Document | DocumentBuilder.parse(InputStream is, String systemId) Parse the content of the given InputStream as an XML document and return a new DOM Document object.
Document | DocumentBuilder.parse(String uri) Parse the content of the given URI as an XML document and return a new DOM Document object.

Uses of Document in javax.xml.soap

Classes in javax.xml.soap that implement Document
 class SOAPPart
The container for the SOAP-specific portion of a SOAPMessage object.

Methods in javax.xml.soap that return Document
 Document SOAPBody.extractContentAsDocument()
Creates a new DOM Document and sets the first child of this SOAPBody as it's document element.

Methods in javax.xml.soap with parameters of type Document
 SOAPBodyElement SOAPBody.addDocument(Document document)
Adds the root node of the DOM Document to this SOAPBody object.

Uses of Document in org.w3c.dom

Methods in org.w3c.dom that return Document
Document | DOMImplementation.createDocument(String namespaceURI, String qualifiedName, DocumentType doctype) Creates a DOM Document object of the specified type with its document element.
Document | Node.getOwnerDocument() The Document object associated with this node.

Uses of Document in org.w3c.dom.ls

Methods in org.w3c.dom.ls that return Document
Document | LSLoadEvent.getNewDocument() The document that finished loading.
Document | LSParser.parse(LSInput input) Parse an XML document from a resource identified by a LSInput.
Document | LSParser.parseURI(String uri) Parse an XML document from a location identified by a URI reference [IETF RFC 2396].

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.DocumentFragment

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.DocumentFragment

Packages that use DocumentFragment
org.w3c.dom Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.

Uses of DocumentFragment in org.w3c.dom

Methods in org.w3c.dom that return DocumentFragment
 DocumentFragment Document.createDocumentFragment()
Creates an empty DocumentFragment object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.DocumentType

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.DocumentType

Packages that use DocumentType
org.w3c.dom Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.

Uses of DocumentType in org.w3c.dom

Methods in org.w3c.dom that return DocumentType
DocumentType | DOMImplementation.createDocumentType(String qualifiedName, String publicId, String systemId) Creates an empty DocumentType node.
DocumentType | Document.getDoctype() The Document Type Declaration (see DocumentType) associated with this document.

Methods in org.w3c.dom with parameters of type DocumentType
 Document DOMImplementation.createDocument(String namespaceURI, String qualifiedName, DocumentType doctype)
Creates a DOM Document object of the specified type with its document element.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.DOMConfiguration

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.DOMConfiguration

Packages that use DOMConfiguration
org.w3c.dom | Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.
org.w3c.dom.ls |

Uses of DOMConfiguration in org.w3c.dom

Methods in org.w3c.dom that return DOMConfiguration
 DOMConfiguration Document.getDomConfig()
The configuration used when Document.normalizeDocument() is invoked.

Uses of DOMConfiguration in org.w3c.dom.ls

Methods in org.w3c.dom.ls that return DOMConfiguration
DOMConfiguration | LSSerializer.getDomConfig() The DOMConfiguration object used by the LSSerializer when serializing a DOM node.
DOMConfiguration | LSParser.getDomConfig() The DOMConfiguration object used when parsing an input source.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.DOMError

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.DOMError

Packages that use DOMError
org.w3c.dom Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.

Uses of DOMError in org.w3c.dom

Methods in org.w3c.dom with parameters of type DOMError
 boolean DOMErrorHandler.handleError(DOMError error)
This method is called on the error handler when an error occurs.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.DOMErrorHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.DOMErrorHandler

No usage of org.w3c.dom.DOMErrorHandler

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.DOMImplementation

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.DOMImplementation

Packages that use DOMImplementation
javax.xml.parsers | Provides classes allowing the processing of XML documents.
org.w3c.dom | Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.
org.w3c.dom.bootstrap |

Uses of DOMImplementation in javax.xml.parsers

Methods in javax.xml.parsers that return DOMImplementation
abstract  DOMImplementation DocumentBuilder.getDOMImplementation()
Obtain an instance of a DOMImplementation object.

Uses of DOMImplementation in org.w3c.dom

Methods in org.w3c.dom that return DOMImplementation
DOMImplementation | DOMImplementationSource.getDOMImplementation(String features) A method to request the first DOM implementation that supports the specified features.
DOMImplementation | Document.getImplementation() The DOMImplementation object that handles this document.
DOMImplementation | DOMImplementationList.item(int index) Returns the indexth item in the collection.

Uses of DOMImplementation in org.w3c.dom.bootstrap

Methods in org.w3c.dom.bootstrap that return DOMImplementation
 DOMImplementation DOMImplementationRegistry.getDOMImplementation(String features)
Return the first implementation that has the desired features, or null if none is found.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.DOMImplementationList

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.DOMImplementationList

Packages that use DOMImplementationList
org.w3c.dom | Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.
org.w3c.dom.bootstrap |

Uses of DOMImplementationList in org.w3c.dom

Methods in org.w3c.dom that return DOMImplementationList
 DOMImplementationList DOMImplementationSource.getDOMImplementationList(String features)
A method to request a list of DOM implementations that support the specified features and versions, as specified in .

Uses of DOMImplementationList in org.w3c.dom.bootstrap

Methods in org.w3c.dom.bootstrap that return DOMImplementationList
 DOMImplementationList DOMImplementationRegistry.getDOMImplementationList(String features)
Return a list of implementations that support the desired features.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.DOMImplementationSource

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.DOMImplementationSource

Packages that use DOMImplementationSource
org.w3c.dom.bootstrap

Uses of DOMImplementationSource in org.w3c.dom.bootstrap

Methods in org.w3c.dom.bootstrap with parameters of type DOMImplementationSource
 void DOMImplementationRegistry.addSource(DOMImplementationSource s)
Register an implementation.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.DOMLocator

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.DOMLocator

Packages that use DOMLocator
org.w3c.dom Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.

Uses of DOMLocator in org.w3c.dom

Methods in org.w3c.dom that return DOMLocator
 DOMLocator DOMError.getLocation()
The location of the error.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.DOMStringList

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.DOMStringList

Packages that use DOMStringList
org.w3c.dom Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.

Uses of DOMStringList in org.w3c.dom

Methods in org.w3c.dom that return DOMStringList
 DOMStringList DOMConfiguration.getParameterNames()
The list of the parameters supported by this DOMConfiguration object and for which at least one value can be set by the application.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.Element

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.Element

Packages that use Element
javax.imageio.metadata | A package of the Java Image I/O API dealing with reading and writing metadata.
javax.xml.bind.annotation | Defines annotations for customizing Java program elements to XML Schema mapping.
javax.xml.crypto.dom | DOM-specific classes for the javax.xml.crypto package.
javax.xml.soap | Provides the API for creating and building SOAP messages.
org.w3c.dom | Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.
org.w3c.dom.ls |

Uses of Element in javax.imageio.metadata

Classes in javax.imageio.metadata that implement Element
 class IIOMetadataNode
A class representing a node in a meta-data tree, which implements the org.w3c.dom.Element interface and additionally allows for the storage of non-textual objects via the getUserObject and setUserObject methods.

Uses of Element in javax.xml.bind.annotation

Methods in javax.xml.bind.annotation that return Element
 Element W3CDomHandler.getElement(DOMResult r)

Methods in javax.xml.bind.annotation with parameters of type Element
 Source W3CDomHandler.marshal(Element element, ValidationEventHandler errorHandler)

Uses of Element in javax.xml.crypto.dom

Methods in javax.xml.crypto.dom that return Element
 Element DOMCryptoContext.getElementById(String idValue)
Returns the Element with the specified ID attribute value.

Methods in javax.xml.crypto.dom with parameters of type Element
 void DOMCryptoContext.setIdAttributeNS(Element element, String namespaceURI, String localName)
Registers the element's attribute specified by the namespace URI and local name to be of type ID.

Uses of Element in javax.xml.soap

Subinterfaces of Element in javax.xml.soap
interface | Detail A container for DetailEntry objects.
interface | DetailEntry The content for a Detail object, giving details for a SOAPFault object.
interface | SOAPBody An object that represents the contents of the SOAP body element in a SOAP message.
interface | SOAPBodyElement A SOAPBodyElement object represents the contents in a SOAPBody object.
interface | SOAPElement An object representing an element of a SOAP message that is allowed but not specifically prescribed by a SOAP specification.
interface | SOAPEnvelope The container for the SOAPHeader and SOAPBody portions of a SOAPPart object.
interface | SOAPFault An element in the SOAPBody object that contains error and/or status information.
interface | SOAPFaultElement A representation of the contents in a SOAPFault object.
interface | SOAPHeader A representation of the SOAP header element.
interface | SOAPHeaderElement An object representing the contents in the SOAP header part of the SOAP envelope.

Methods in javax.xml.soap with parameters of type Element
 SOAPElement SOAPFactory.createElement(Element domElement)
Creates a SOAPElement object from an existing DOM Element.

Uses of Element in org.w3c.dom

Methods in org.w3c.dom that return Element
Element | Document.createElement(String tagName) Creates an element of the type specified.
Element | Document.createElementNS(String namespaceURI, String qualifiedName) Creates an element of the given qualified name and namespace URI.
Element | Document.getDocumentElement() This is a convenience attribute that allows direct access to the child node that is the document element of the document.
Element | Document.getElementById(String elementId) Returns the Element that has an ID attribute with the given value.
Element | Attr.getOwnerElement() The Element node this attribute is attached to or null if this attribute is not in use.

Uses of Element in org.w3c.dom.ls

Methods in org.w3c.dom.ls with parameters of type Element
 short LSParserFilter.startElement(Element elementArg)
The parser will call this method after each Element start tag has been scanned, but before the remainder of the Element is processed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.Entity

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.Entity

No usage of org.w3c.dom.Entity

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.EntityReference

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.EntityReference

Packages that use EntityReference
org.w3c.dom Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.

Uses of EntityReference in org.w3c.dom

Methods in org.w3c.dom that return EntityReference
 EntityReference Document.createEntityReference(String name)
Creates an EntityReference object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.NamedNodeMap

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.NamedNodeMap

Packages that use NamedNodeMap
javax.imageio.metadata | A package of the Java Image I/O API dealing with reading and writing metadata.
org.w3c.dom | Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.

Uses of NamedNodeMap in javax.imageio.metadata

Methods in javax.imageio.metadata that return NamedNodeMap
 NamedNodeMap IIOMetadataNode.getAttributes()

Uses of NamedNodeMap in org.w3c.dom

Methods in org.w3c.dom that return NamedNodeMap
NamedNodeMap | Node.getAttributes() A NamedNodeMap containing the attributes of this node (if it is an Element) or null otherwise.
NamedNodeMap | DocumentType.getEntities() A NamedNodeMap containing the general entities, both external and internal, declared in the DTD.
NamedNodeMap | DocumentType.getNotations() A NamedNodeMap containing the notations declared in the DTD.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.NameList

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.NameList

No usage of org.w3c.dom.NameList

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.Node

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.Node

Packages that use Node
javax.imageio.metadata | A package of the Java Image I/O API dealing with reading and writing metadata.
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.crypto.dom | DOM-specific classes for the javax.xml.crypto package.
javax.xml.crypto.dsig.dom | DOM-specific classes for the javax.xml.crypto.dsig package.
javax.xml.soap | Provides the API for creating and building SOAP messages.
javax.xml.transform.dom | This package implements DOM-specific transformation APIs.
org.w3c.dom | Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.
org.w3c.dom.events |
org.w3c.dom.ls |

Uses of Node in javax.imageio.metadata

Classes in javax.imageio.metadata that implement Node
 class IIOMetadataNode
A class representing a node in a meta-data tree, which implements the org.w3c.dom.Element interface and additionally allows for the storage of non-textual objects via the getUserObject and setUserObject methods.

Fields in javax.imageio.metadata declared as Node
protected  Node IIOInvalidTreeException.offendingNode
The Node that led to the parsing error, or null.

Methods in javax.imageio.metadata that return Node
Node | IIOMetadataNode.appendChild(Node newChild) Adds the node newChild to the end of the list of children of this node.
Node | IIOMetadataNode.cloneNode(boolean deep) Returns a duplicate of this node.
abstract Node | IIOMetadata.getAsTree(String formatName) Returns an XML DOM Node object that represents the root of a tree of metadata contained within this object according to the conventions defined by a given metadata format.
Node | IIOMetadataNode.getFirstChild() Returns the first child of this node, or null if the node has no children.
Node | IIOMetadataNode.getLastChild() Returns the last child of this node, or null if the node has no children.
Node | IIOMetadataNode.getNextSibling() Returns the next sibling of this node, or null if the node has no next sibling.
Node | IIOInvalidTreeException.getOffendingNode() Returns the Node that caused the error in parsing.
Node | IIOMetadataNode.getParentNode() Returns the parent of this node.
Node | IIOMetadataNode.getPreviousSibling() Returns the previous sibling of this node, or null if this node has no previous sibling.
Node | IIOMetadataNode.insertBefore(Node newChild, Node refChild) Inserts the node newChild before the existing child node refChild.
Node | IIOMetadataNode.item(int index)
Node | IIOMetadataNode.removeChild(Node oldChild) Removes the child node indicated by oldChild from the list of children, and returns it.
Node | IIOMetadataNode.replaceChild(Node newChild, Node oldChild) Replaces the child node oldChild with newChild in the list of children, and returns the oldChild node.

Methods in javax.imageio.metadata with parameters of type Node
Node | IIOMetadataNode.appendChild(Node newChild) Adds the node newChild to the end of the list of children of this node.
short | IIOMetadataNode.compareDocumentPosition(Node other)
Node | IIOMetadataNode.insertBefore(Node newChild, Node refChild) Inserts the node newChild before the existing child node refChild.
boolean | IIOMetadataNode.isEqualNode(Node node)
boolean | IIOMetadataNode.isSameNode(Node node)
abstract void | IIOMetadata.mergeTree(String formatName, Node root) Alters the internal state of this IIOMetadata object from a tree of XML DOM Nodes whose syntax is defined by the given metadata format.
Node | IIOMetadataNode.removeChild(Node oldChild) Removes the child node indicated by oldChild from the list of children, and returns it.
Node | IIOMetadataNode.replaceChild(Node newChild, Node oldChild) Replaces the child node oldChild with newChild in the list of children, and returns the oldChild node.
void | IIOMetadata.setFromTree(String formatName, Node root) Sets the internal state of this IIOMetadata object from a tree of XML DOM Nodes whose syntax is defined by the given metadata format.

Constructors in javax.imageio.metadata with parameters of type Node
IIOInvalidTreeException(String message, Node offendingNode)
Constructs an IIOInvalidTreeException with a message string and a reference to the Node that caused the parsing error.
IIOInvalidTreeException(String message, Throwable cause, Node offendingNode)
Constructs an IIOInvalidTreeException with a message string, a reference to an exception that caused this exception, and a reference to the Node that caused the parsing error.

Uses of Node in javax.xml.bind

Methods in javax.xml.bind that return Node
Node | ValidationEventLocator.getNode() Return a reference to the DOM Node if available
Node | Marshaller.getNode(Object contentTree) Get a DOM tree view of the content tree(Optional).

Methods in javax.xml.bind that return types with arguments of type Node
 Binder<Node> JAXBContext.createBinder()
Creates a Binder for W3C DOM.

Methods in javax.xml.bind with parameters of type Node
 void Marshaller.marshal(Object jaxbElement, Node node)
Marshal the content tree rooted at jaxbElement into a DOM tree.
 Object Unmarshaller.unmarshal(Node node)
Unmarshal global XML data from the specified DOM tree and return the resulting content tree.
<T> JAXBElement<T>
Unmarshaller.unmarshal(Node node, Class<T> declaredType)
Unmarshal XML data by JAXB mapped declaredType and return the resulting content tree.

Uses of Node in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers that return Node
Node | ValidationEventLocatorImpl.getNode()
Node | AbstractMarshallerImpl.getNode(Object obj) By default, the getNode method is unsupported and throw an UnsupportedOperationException.

Methods in javax.xml.bind.helpers with parameters of type Node
 void AbstractMarshallerImpl.marshal(Object obj, Node node)
 void ValidationEventLocatorImpl.setNode(Node _node)
Set the Node field on this event locator.
<T> JAXBElement<T>
AbstractUnmarshallerImpl.unmarshal(Node node, Class<T> expectedType)

Constructors in javax.xml.bind.helpers with parameters of type Node
ValidationEventLocatorImpl(Node _node)
Constructs an object that points to a DOM Node.

Uses of Node in javax.xml.crypto.dom

Methods in javax.xml.crypto.dom that return Node
Node | DOMURIReference.getHere() Returns the here node.
Node | DOMStructure.getNode() Returns the node contained in this DOMStructure.

Constructors in javax.xml.crypto.dom with parameters of type Node
DOMStructure(Node node)
Creates a DOMStructure containing the specified node.

Uses of Node in javax.xml.crypto.dsig.dom

Methods in javax.xml.crypto.dsig.dom that return Node
Node | DOMSignContext.getNextSibling() Returns the nextSibling node.
Node | DOMValidateContext.getNode() Returns the node.
Node | DOMSignContext.getParent() Returns the parent node.

Methods in javax.xml.crypto.dsig.dom with parameters of type Node
void | DOMSignContext.setNextSibling(Node nextSibling) Sets the next sibling node.
void | DOMValidateContext.setNode(Node node) Sets the node.
void | DOMSignContext.setParent(Node parent) Sets the parent node.

Constructors in javax.xml.crypto.dsig.dom with parameters of type Node
DOMSignContext(Key signingKey, Node parent)
Creates a DOMSignContext with the specified signing key and parent node.
DOMSignContext(Key signingKey, Node parent, Node nextSibling)
Creates a DOMSignContext with the specified signing key, parent and next sibling nodes.
DOMSignContext(KeySelector ks, Node parent)
Creates a DOMSignContext with the specified key selector and parent node.
DOMSignContext(KeySelector ks, Node parent, Node nextSibling)
Creates a DOMSignContext with the specified key selector, parent and next sibling nodes.
DOMValidateContext(Key validatingKey, Node node)
Creates a DOMValidateContext containing the specified key and node.
DOMValidateContext(KeySelector ks, Node node)
Creates a DOMValidateContext containing the specified key selector and node.

Uses of Node in javax.xml.soap

Subinterfaces of Node in javax.xml.soap
interface | Detail A container for DetailEntry objects.
interface | DetailEntry The content for a Detail object, giving details for a SOAPFault object.
interface | Node A representation of a node (element) in an XML document.
interface | SOAPBody An object that represents the contents of the SOAP body element in a SOAP message.
interface | SOAPBodyElement A SOAPBodyElement object represents the contents in a SOAPBody object.
interface | SOAPElement An object representing an element of a SOAP message that is allowed but not specifically prescribed by a SOAP specification.
interface | SOAPEnvelope The container for the SOAPHeader and SOAPBody portions of a SOAPPart object.
interface | SOAPFault An element in the SOAPBody object that contains error and/or status information.
interface | SOAPFaultElement A representation of the contents in a SOAPFault object.
interface | SOAPHeader A representation of the SOAP header element.
interface | SOAPHeaderElement An object representing the contents in the SOAP header part of the SOAP envelope.

Classes in javax.xml.soap that implement Node
 class SOAPPart
The container for the SOAP-specific portion of a SOAPMessage object.

Uses of Node in javax.xml.transform.dom

Methods in javax.xml.transform.dom that return Node
Node | DOMResult.getNextSibling() Get the child node before which the result nodes will be inserted.
Node | DOMResult.getNode() Get the node that will contain the result DOM tree.
Node | DOMSource.getNode() Get the node that represents a Source DOM tree.
Node | DOMLocator.getOriginatingNode() Return the node where the event occurred.

Methods in javax.xml.transform.dom with parameters of type Node
void | DOMResult.setNextSibling(Node nextSibling) Set the child node before which the result nodes will be inserted.
void | DOMResult.setNode(Node node) Set the node that will contain the result DOM tree.
void | DOMSource.setNode(Node node) Set the node that will represents a Source DOM tree.

Constructors in javax.xml.transform.dom with parameters of type Node
DOMResult(Node node)
Use a DOM node to create a new output target.
DOMResult(Node node, Node nextSibling)
Use a DOM node to create a new output target specifying the child node where the result nodes should be inserted before.
DOMResult(Node node, Node nextSibling, String systemId)
Use a DOM node to create a new output target specifying the child node where the result nodes should be inserted before and the specified System ID.
DOMResult(Node node, String systemId)
Use a DOM node to create a new output target with the specified System ID.
DOMSource(Node n)
Create a new input source with a DOM node.
DOMSource(Node node, String systemID)
Create a new input source with a DOM node, and with the system ID also passed in as the base URI.

Uses of Node in org.w3c.dom

Subinterfaces of Node in org.w3c.dom
interface | Attr The Attr interface represents an attribute in an Element object.
interface | CDATASection CDATA sections are used to escape blocks of text containing characters that would otherwise be regarded as markup.
interface | CharacterData The CharacterData interface extends Node with a set of attributes and methods for accessing character data in the DOM.
interface | Comment This interface inherits from CharacterData and represents the content of a comment, i.e., all the characters between the starting ' <!--' and ending '-->'.
interface | Document The Document interface represents the entire HTML or XML document.
interface | DocumentFragment DocumentFragment is a "lightweight" or "minimal" Document object.
interface | DocumentType Each Document has a doctype attribute whose value is either null or a DocumentType object.
interface | Element The Element interface represents an element in an HTML or XML document.
interface | Entity This interface represents a known entity, either parsed or unparsed, in an XML document.
interface | EntityReference EntityReference nodes may be used to represent an entity reference in the tree.
interface | Notation This interface represents a notation declared in the DTD.
interface | ProcessingInstruction The ProcessingInstruction interface represents a "processing instruction", used in XML as a way to keep processor-specific information in the text of the document.
interface | Text The Text interface inherits from CharacterData and represents the textual content (termed character data in XML) of an Element or Attr.

Methods in org.w3c.dom that return Node
Node | Document.adoptNode(Node source) Attempts to adopt a node from another document to this document.
Node | Node.appendChild(Node newChild) Adds the node newChild to the end of the list of children of this node.
Node | Node.cloneNode(boolean deep) Returns a duplicate of this node, i.e., serves as a generic copy constructor for nodes.
Node | Node.getFirstChild() The first child of this node.
Node | Node.getLastChild() The last child of this node.
Node | NamedNodeMap.getNamedItem(String name) Retrieves a node specified by name.
Node | NamedNodeMap.getNamedItemNS(String namespaceURI, String localName) Retrieves a node specified by local name and namespace URI.
Node | Node.getNextSibling() The node immediately following this node.
Node | Node.getParentNode() The parent of this node.
Node | Node.getPreviousSibling() The node immediately preceding this node.
Node | DOMLocator.getRelatedNode() The node this locator is pointing to, or null if no node is available.
Node | Document.importNode(Node importedNode, boolean deep) Imports a node from another document to this document, without altering or removing the source node from the original document; this method creates a new copy of the source node.
Node | Node.insertBefore(Node newChild, Node refChild) Inserts the node newChild before the existing child node refChild.
Node | NamedNodeMap.item(int index) Returns the indexth item in the map.
Node | NodeList.item(int index) Returns the indexth item in the collection.
Node | Node.removeChild(Node oldChild) Removes the child node indicated by oldChild from the list of children, and returns it.
Node | NamedNodeMap.removeNamedItem(String name) Removes a node specified by name.
Node | NamedNodeMap.removeNamedItemNS(String namespaceURI, String localName) Removes a node specified by local name and namespace URI.
Node | Document.renameNode(Node n, String namespaceURI, String qualifiedName) Rename an existing node of type ELEMENT_NODE or ATTRIBUTE_NODE.
Node | Node.replaceChild(Node newChild, Node oldChild) Replaces the child node oldChild with newChild in the list of children, and returns the oldChild node.
Node | NamedNodeMap.setNamedItem(Node arg) Adds a node using its nodeName attribute.
Node | NamedNodeMap.setNamedItemNS(Node arg) Adds a node using its namespaceURI and localName.

Methods in org.w3c.dom with parameters of type Node
Node | Document.adoptNode(Node source) Attempts to adopt a node from another document to this document.
Node | Node.appendChild(Node newChild) Adds the node newChild to the end of the list of children of this node.
short | Node.compareDocumentPosition(Node other) Compares the reference node, i.e.
void | UserDataHandler.handle(short operation, String key, Object data, Node src, Node dst) This method is called whenever the node for which this handler is registered is imported or cloned.
Node | Document.importNode(Node importedNode, boolean deep) Imports a node from another document to this document, without altering or removing the source node from the original document; this method creates a new copy of the source node.
Node | Node.insertBefore(Node newChild, Node refChild) Inserts the node newChild before the existing child node refChild.
boolean | Node.isEqualNode(Node arg) Tests whether two nodes are equal.
boolean | Node.isSameNode(Node other) Returns whether this node is the same node as the given one.
Node | Node.removeChild(Node oldChild) Removes the child node indicated by oldChild from the list of children, and returns it.
Node | Document.renameNode(Node n, String namespaceURI, String qualifiedName) Rename an existing node of type ELEMENT_NODE or ATTRIBUTE_NODE.
Node | Node.replaceChild(Node newChild, Node oldChild) Replaces the child node oldChild with newChild in the list of children, and returns the oldChild node.
Node | NamedNodeMap.setNamedItem(Node arg) Adds a node using its nodeName attribute.
Node | NamedNodeMap.setNamedItemNS(Node arg) Adds a node using its namespaceURI and localName.

Uses of Node in org.w3c.dom.events

Methods in org.w3c.dom.events that return Node
 Node MutationEvent.getRelatedNode()
relatedNode is used to identify a secondary node related to a mutation event.

Methods in org.w3c.dom.events with parameters of type Node
 void MutationEvent.initMutationEvent(String typeArg, boolean canBubbleArg, boolean cancelableArg, Node relatedNodeArg, String prevValueArg, String newValueArg, String attrNameArg, short attrChangeArg)
The initMutationEvent method is used to initialize the value of a MutationEvent created through the DocumentEvent interface.

Uses of Node in org.w3c.dom.ls

Methods in org.w3c.dom.ls that return Node
 Node LSParser.parseWithContext(LSInput input, Node contextArg, short action)
Parse an XML fragment from a resource identified by a LSInput and insert the content into an existing document at the position specified with the context and action arguments.

Methods in org.w3c.dom.ls with parameters of type Node
short | LSParserFilter.acceptNode(Node nodeArg) This method will be called by the parser at the completion of the parsing of each node.
Node | LSParser.parseWithContext(LSInput input, Node contextArg, short action) Parse an XML fragment from a resource identified by a LSInput and insert the content into an existing document at the position specified with the context and action arguments.
boolean | LSSerializer.write(Node nodeArg, LSOutput destination) Serialize the specified node as described above in the general description of the LSSerializer interface.
String | LSSerializer.writeToString(Node nodeArg) Serialize the specified node as described above in the general description of the LSSerializer interface.
boolean | LSSerializer.writeToURI(Node nodeArg, String uri) A convenience method that acts as if LSSerializer.write was called with a LSOutput with no encoding specified and LSOutput.systemId set to the uri argument.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.NodeList

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.NodeList

Packages that use NodeList
javax.imageio.metadata | A package of the Java Image I/O API dealing with reading and writing metadata.
org.w3c.dom | Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.

Uses of NodeList in javax.imageio.metadata

Classes in javax.imageio.metadata that implement NodeList
 class IIOMetadataNode
A class representing a node in a meta-data tree, which implements the org.w3c.dom.Element interface and additionally allows for the storage of non-textual objects via the getUserObject and setUserObject methods.

Methods in javax.imageio.metadata that return NodeList
NodeList | IIOMetadataNode.getChildNodes()
NodeList | IIOMetadataNode.getElementsByTagName(String name)
NodeList | IIOMetadataNode.getElementsByTagNameNS(String namespaceURI, String localName) Equivalent to getElementsByTagName(localName).

Uses of NodeList in org.w3c.dom

Methods in org.w3c.dom that return NodeList
NodeList | Node.getChildNodes() A NodeList that contains all children of this node.
NodeList | Element.getElementsByTagName(String name) Returns a NodeList of all descendant Elements with a given tag name, in document order.
NodeList | Document.getElementsByTagName(String tagname) Returns a NodeList of all the Elements in document order with a given tag name and are contained in the document.
NodeList | Element.getElementsByTagNameNS(String namespaceURI, String localName) Returns a NodeList of all the descendant Elements with a given local name and namespace URI in document order.
NodeList | Document.getElementsByTagNameNS(String namespaceURI, String localName) Returns a NodeList of all the Elements with a given local name and namespace URI in document order.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.Notation

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.Notation

No usage of org.w3c.dom.Notation

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.ProcessingInstruction

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.ProcessingInstruction

Packages that use ProcessingInstruction
org.w3c.dom Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.

Uses of ProcessingInstruction in org.w3c.dom

Methods in org.w3c.dom that return ProcessingInstruction
 ProcessingInstruction Document.createProcessingInstruction(String target, String data)
Creates a ProcessingInstruction node given the specified name and data strings.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.Text

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.Text

Packages that use Text
javax.xml.soap | Provides the API for creating and building SOAP messages.
org.w3c.dom | Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.

Uses of Text in javax.xml.soap

Subinterfaces of Text in javax.xml.soap
 interface Text
A representation of a node whose value is text.

Uses of Text in org.w3c.dom

Subinterfaces of Text in org.w3c.dom
 interface CDATASection
CDATA sections are used to escape blocks of text containing characters that would otherwise be regarded as markup.

Methods in org.w3c.dom that return Text
Text | Document.createTextNode(String data) Creates a Text node given the specified string.
Text | Text.replaceWholeText(String content) Replaces the text of the current node and all logically-adjacent text nodes with the specified text.
Text | Text.splitText(int offset) Breaks this node into two nodes at the specified offset, keeping both in the tree as siblings.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.TypeInfo

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.TypeInfo

Packages that use TypeInfo
javax.imageio.metadata | A package of the Java Image I/O API dealing with reading and writing metadata.
javax.xml.validation | This package provides an API for validation of XML documents.
org.w3c.dom | Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.

Uses of TypeInfo in javax.imageio.metadata

Methods in javax.imageio.metadata that return TypeInfo
 TypeInfo IIOMetadataNode.getSchemaTypeInfo()

Uses of TypeInfo in javax.xml.validation

Methods in javax.xml.validation that return TypeInfo
abstract TypeInfo | TypeInfoProvider.getAttributeTypeInfo(int index) Returns the immutable TypeInfo object for the specified attribute of the current element.
abstract TypeInfo | TypeInfoProvider.getElementTypeInfo() Returns the immutable TypeInfo object for the current element.

Uses of TypeInfo in org.w3c.dom

Methods in org.w3c.dom that return TypeInfo
TypeInfo | Attr.getSchemaTypeInfo() The type information associated with this attribute.
TypeInfo | Element.getSchemaTypeInfo() The type information associated with this element.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.UserDataHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.UserDataHandler

Packages that use UserDataHandler
javax.imageio.metadata | A package of the Java Image I/O API dealing with reading and writing metadata.
org.w3c.dom | Provides the interfaces for the Document Object Model (DOM) which is a component API of the Java API for XML Processing.

Uses of UserDataHandler in javax.imageio.metadata

Methods in javax.imageio.metadata with parameters of type UserDataHandler
 Object IIOMetadataNode.setUserData(String key, Object data, UserDataHandler handler)

Uses of UserDataHandler in org.w3c.dom

Methods in org.w3c.dom with parameters of type UserDataHandler
 Object Node.setUserData(String key, Object data, UserDataHandler handler)
Associate an object to a key on this node.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Document

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface Document

All Superinterfaces:
Node
All Known Implementing Classes:
SOAPPart
public interface Document
extends Node

The Document interface represents the entire HTML or XML document. Conceptually, it is the root of the document tree, and provides the primary access to the document's data.

Since elements, text nodes, comments, processing instructions, etc. cannot exist outside the context of a Document, the Document interface also contains the factory methods needed to create these objects. The Node objects created have a ownerDocument attribute which associates them with the Document within whose context they were created.

See also the Document Object Model (DOM) Level 3 Core Specification.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
 Node adoptNode(Node source)
Attempts to adopt a node from another document to this document.
 Attr createAttribute(String name)
Creates an Attr of the given name.
 Attr createAttributeNS(String namespaceURI, String qualifiedName)
Creates an attribute of the given qualified name and namespace URI.
 CDATASection createCDATASection(String data)
Creates a CDATASection node whose value is the specified string.
 Comment createComment(String data)
Creates a Comment node given the specified string.
 DocumentFragment createDocumentFragment()
Creates an empty DocumentFragment object.
 Element createElement(String tagName)
Creates an element of the type specified.
 Element createElementNS(String namespaceURI, String qualifiedName)
Creates an element of the given qualified name and namespace URI.
 EntityReference createEntityReference(String name)
Creates an EntityReference object.
 ProcessingInstruction createProcessingInstruction(String target, String data)
Creates a ProcessingInstruction node given the specified name and data strings.
 Text createTextNode(String data)
Creates a Text node given the specified string.
 DocumentType getDoctype()
The Document Type Declaration (see DocumentType) associated with this document.
 Element getDocumentElement()
This is a convenience attribute that allows direct access to the child node that is the document element of the document.
 String getDocumentURI()
The location of the document or null if undefined or if the Document was created using DOMImplementation.createDocument.
 DOMConfiguration getDomConfig()
The configuration used when Document.normalizeDocument() is invoked.
 Element getElementById(String elementId)
Returns the Element that has an ID attribute with the given value.
 NodeList getElementsByTagName(String tagname)
Returns a NodeList of all the Elements in document order with a given tag name and are contained in the document.
 NodeList getElementsByTagNameNS(String namespaceURI, String localName)
Returns a NodeList of all the Elements with a given local name and namespace URI in document order.
 DOMImplementation getImplementation()
The DOMImplementation object that handles this document.
 String getInputEncoding()
An attribute specifying the encoding used for this document at the time of the parsing.
 boolean getStrictErrorChecking()
An attribute specifying whether error checking is enforced or not.
 String getXmlEncoding()
An attribute specifying, as part of the XML declaration, the encoding of this document.
 boolean getXmlStandalone()
An attribute specifying, as part of the XML declaration, whether this document is standalone.
 String getXmlVersion()
An attribute specifying, as part of the XML declaration, the version number of this document.
 Node importNode(Node importedNode, boolean deep)
Imports a node from another document to this document, without altering or removing the source node from the original document; this method creates a new copy of the source node.
 void normalizeDocument()
This method acts as if the document was going through a save and load cycle, putting the document in a "normal" form.
 Node renameNode(Node n, String namespaceURI, String qualifiedName)
Rename an existing node of type ELEMENT_NODE or ATTRIBUTE_NODE.
 void setDocumentURI(String documentURI)
The location of the document or null if undefined or if the Document was created using DOMImplementation.createDocument.
 void setStrictErrorChecking(boolean strictErrorChecking)
An attribute specifying whether error checking is enforced or not.
 void setXmlStandalone(boolean xmlStandalone)
An attribute specifying, as part of the XML declaration, whether this document is standalone.
 void setXmlVersion(String xmlVersion)
An attribute specifying, as part of the XML declaration, the version number of this document.
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

getDoctype

DocumentType getDoctype()
The Document Type Declaration (see DocumentType) associated with this document. For XML documents without a document type declaration this returns null. For HTML documents, a DocumentType object may be returned, independently of the presence or absence of document type declaration in the HTML document.
This provides direct access to the DocumentType node, child node of this Document. This node can be set at document creation time and later changed through the use of child nodes manipulation methods, such as Node.insertBefore, or Node.replaceChild. Note, however, that while some implementations may instantiate different types of Document objects supporting additional features than the "Core", such as "HTML" [DOM Level 2 HTML] , based on the DocumentType specified at creation time, changing it afterwards is very unlikely to result in a change of the features supported.

Since:
DOM Level 3

getImplementation

DOMImplementation getImplementation()
The DOMImplementation object that handles this document. A DOM application may use objects from multiple implementations.

getDocumentElement

Element getDocumentElement()
This is a convenience attribute that allows direct access to the child node that is the document element of the document.

createElement

Element createElement(String tagName)
                      throws DOMException
Creates an element of the type specified. Note that the instance returned implements the Element interface, so attributes can be specified directly on the returned object.
In addition, if there are known attributes with default values, Attr nodes representing them are automatically created and attached to the element.
To create an element with a qualified name and namespace URI, use the createElementNS method.

Parameters:
tagName - The name of the element type to instantiate. For XML, this is case-sensitive, otherwise it depends on the case-sensitivity of the markup language in use. In that case, the name is mapped to the canonical form of that markup by the DOM implementation.
Returns:
A new Element object with the nodeName attribute set to tagName, and localName, prefix, and namespaceURI set to null.
Throws:
DOMException - INVALID_CHARACTER_ERR: Raised if the specified name is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.

createDocumentFragment

DocumentFragment createDocumentFragment()
Creates an empty DocumentFragment object.

Returns:
A new DocumentFragment.

createTextNode

Text createTextNode(String data)
Creates a Text node given the specified string.

Parameters:
data - The data for the node.
Returns:
The new Text object.

createComment

Comment createComment(String data)
Creates a Comment node given the specified string.

Parameters:
data - The data for the node.
Returns:
The new Comment object.

createCDATASection

CDATASection createCDATASection(String data)
                                throws DOMException
Creates a CDATASection node whose value is the specified string.

Parameters:
data - The data for the CDATASection contents.
Returns:
The new CDATASection object.
Throws:
DOMException - NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

createProcessingInstruction

ProcessingInstruction createProcessingInstruction(String target,
                                                  String data)
                                                  throws DOMException
Creates a ProcessingInstruction node given the specified name and data strings.

Parameters:
target - The target part of the processing instruction.Unlike Document.createElementNS or Document.createAttributeNS, no namespace well-formed checking is done on the target name. Applications should invoke Document.normalizeDocument() with the parameter " namespaces" set to true in order to ensure that the target name is namespace well-formed.
data - The data for the node.
Returns:
The new ProcessingInstruction object.
Throws:
DOMException - INVALID_CHARACTER_ERR: Raised if the specified target is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.
NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

createAttribute

Attr createAttribute(String name)
                     throws DOMException
Creates an Attr of the given name. Note that the Attr instance can then be set on an Element using the setAttributeNode method.
To create an attribute with a qualified name and namespace URI, use the createAttributeNS method.

Parameters:
name - The name of the attribute.
Returns:
A new Attr object with the nodeName attribute set to name, and localName, prefix, and namespaceURI set to null. The value of the attribute is the empty string.
Throws:
DOMException - INVALID_CHARACTER_ERR: Raised if the specified name is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.

createEntityReference

EntityReference createEntityReference(String name)
                                      throws DOMException
Creates an EntityReference object. In addition, if the referenced entity is known, the child list of the EntityReference node is made the same as that of the corresponding Entity node.

Note: If any descendant of the Entity node has an unbound namespace prefix, the corresponding descendant of the created EntityReference node is also unbound; (its namespaceURI is null). The DOM Level 2 and 3 do not support any mechanism to resolve namespace prefixes in this case.

Parameters:
name - The name of the entity to reference.Unlike Document.createElementNS or Document.createAttributeNS, no namespace well-formed checking is done on the entity name. Applications should invoke Document.normalizeDocument() with the parameter " namespaces" set to true in order to ensure that the entity name is namespace well-formed.
Returns:
The new EntityReference object.
Throws:
DOMException - INVALID_CHARACTER_ERR: Raised if the specified name is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.
NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

getElementsByTagName

NodeList getElementsByTagName(String tagname)
Returns a NodeList of all the Elements in document order with a given tag name and are contained in the document.

Parameters:
tagname - The name of the tag to match on. The special value "*" matches all tags. For XML, the tagname parameter is case-sensitive, otherwise it depends on the case-sensitivity of the markup language in use.
Returns:
A new NodeList object containing all the matched Elements.

importNode

Node importNode(Node importedNode,
                boolean deep)
                throws DOMException
Imports a node from another document to this document, without altering or removing the source node from the original document; this method creates a new copy of the source node. The returned node has no parent; (parentNode is null).
For all nodes, importing a node creates a node object owned by the importing document, with attribute values identical to the source node's nodeName and nodeType, plus the attributes related to namespaces (prefix, localName, and namespaceURI). As in the cloneNode operation, the source node is not altered. User data associated to the imported node is not carried over. However, if any UserDataHandlers has been specified along with the associated data these handlers will be called with the appropriate parameters before this method returns.
Additional information is copied as appropriate to the nodeType, attempting to mirror the behavior expected if a fragment of XML or HTML source was copied from one document to another, recognizing that the two documents may have different DTDs in the XML case. The following list describes the specifics for each type of node.
ATTRIBUTE_NODE
The ownerElement attribute is set to null and the specified flag is set to true on the generated Attr. The descendants of the source Attr are recursively imported and the resulting nodes reassembled to form the corresponding subtree. Note that the deep parameter has no effect on Attr nodes; they always carry their children with them when imported.
DOCUMENT_FRAGMENT_NODE
If the deep option was set to true, the descendants of the source DocumentFragment are recursively imported and the resulting nodes reassembled under the imported DocumentFragment to form the corresponding subtree. Otherwise, this simply generates an empty DocumentFragment.
DOCUMENT_NODE
Document nodes cannot be imported.
DOCUMENT_TYPE_NODE
DocumentType nodes cannot be imported.
ELEMENT_NODE
Specified attribute nodes of the source element are imported, and the generated Attr nodes are attached to the generated Element. Default attributes are not copied, though if the document being imported into defines default attributes for this element name, those are assigned. If the importNode deep parameter was set to true, the descendants of the source element are recursively imported and the resulting nodes reassembled to form the corresponding subtree.
ENTITY_NODE
Entity nodes can be imported, however in the current release of the DOM the DocumentType is readonly. Ability to add these imported nodes to a DocumentType will be considered for addition to a future release of the DOM.On import, the publicId, systemId, and notationName attributes are copied. If a deep import is requested, the descendants of the the source Entity are recursively imported and the resulting nodes reassembled to form the corresponding subtree.
ENTITY_REFERENCE_NODE
Only the EntityReference itself is copied, even if a deep import is requested, since the source and destination documents might have defined the entity differently. If the document being imported into provides a definition for this entity name, its value is assigned.
NOTATION_NODE
Notation nodes can be imported, however in the current release of the DOM the DocumentType is readonly. Ability to add these imported nodes to a DocumentType will be considered for addition to a future release of the DOM.On import, the publicId and systemId attributes are copied. Note that the deep parameter has no effect on this type of nodes since they cannot have any children.
PROCESSING_INSTRUCTION_NODE
The imported node copies its target and data values from those of the source node.Note that the deep parameter has no effect on this type of nodes since they cannot have any children.
TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE
These three types of nodes inheriting from CharacterData copy their data and length attributes from those of the source node.Note that the deep parameter has no effect on these types of nodes since they cannot have any children.

Parameters:
importedNode - The node to import.
deep - If true, recursively import the subtree under the specified node; if false, import only the node itself, as explained above. This has no effect on nodes that cannot have any children, and on Attr, and EntityReference nodes.
Returns:
The imported node that belongs to this Document.
Throws:
DOMException - NOT_SUPPORTED_ERR: Raised if the type of node being imported is not supported.
INVALID_CHARACTER_ERR: Raised if one of the imported names is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute. This may happen when importing an XML 1.1 [XML 1.1] element into an XML 1.0 document, for instance.
Since:
DOM Level 2

createElementNS

Element createElementNS(String namespaceURI,
                        String qualifiedName)
                        throws DOMException
Creates an element of the given qualified name and namespace URI.
Per [XML Namespaces] , applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.

Parameters:
namespaceURI - The namespace URI of the element to create.
qualifiedName - The qualified name of the element type to instantiate.
Returns:
A new Element object with the following attributes:
Attribute | Value
Node.nodeName | qualifiedName
Node.namespaceURI | namespaceURI
Node.prefix | prefix, extracted from qualifiedName, or null if there is no prefix
Node.localName | local name, extracted from qualifiedName
Element.tagName | qualifiedName
Throws:
DOMException - INVALID_CHARACTER_ERR: Raised if the specified qualifiedName is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.
NAMESPACE_ERR: Raised if the qualifiedName is a malformed qualified name, if the qualifiedName has a prefix and the namespaceURI is null, or if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from " http://www.w3.org/XML/1998/namespace" [XML Namespaces] , or if the qualifiedName or its prefix is "xmlns" and the namespaceURI is different from "http://www.w3.org/2000/xmlns/", or if the namespaceURI is "http://www.w3.org/2000/xmlns/" and neither the qualifiedName nor its prefix is "xmlns".
NOT_SUPPORTED_ERR: Always thrown if the current document does not support the "XML" feature, since namespaces were defined by XML.
Since:
DOM Level 2

createAttributeNS

Attr createAttributeNS(String namespaceURI,
                       String qualifiedName)
                       throws DOMException
Creates an attribute of the given qualified name and namespace URI.
Per [XML Namespaces] , applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.

Parameters:
namespaceURI - The namespace URI of the attribute to create.
qualifiedName - The qualified name of the attribute to instantiate.
Returns:
A new Attr object with the following attributes:
Attribute | Value
Node.nodeName | qualifiedName
Node.namespaceURI | namespaceURI
Node.prefix | prefix, extracted from qualifiedName, or null if there is no prefix
Node.localName | local name, extracted from qualifiedName
Attr.name | qualifiedName
Node.nodeValue | the empty string
Throws:
DOMException - INVALID_CHARACTER_ERR: Raised if the specified qualifiedName is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.
NAMESPACE_ERR: Raised if the qualifiedName is a malformed qualified name, if the qualifiedName has a prefix and the namespaceURI is null, if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from " http://www.w3.org/XML/1998/namespace", if the qualifiedName or its prefix is "xmlns" and the namespaceURI is different from "http://www.w3.org/2000/xmlns/", or if the namespaceURI is "http://www.w3.org/2000/xmlns/" and neither the qualifiedName nor its prefix is "xmlns".
NOT_SUPPORTED_ERR: Always thrown if the current document does not support the "XML" feature, since namespaces were defined by XML.
Since:
DOM Level 2

getElementsByTagNameNS

NodeList getElementsByTagNameNS(String namespaceURI,
                                String localName)
Returns a NodeList of all the Elements with a given local name and namespace URI in document order.

Parameters:
namespaceURI - The namespace URI of the elements to match on. The special value "*" matches all namespaces.
localName - The local name of the elements to match on. The special value "*" matches all local names.
Returns:
A new NodeList object containing all the matched Elements.
Since:
DOM Level 2

getElementById

Element getElementById(String elementId)
Returns the Element that has an ID attribute with the given value. If no such element exists, this returns null . If more than one element has an ID attribute with that value, what is returned is undefined.
The DOM implementation is expected to use the attribute Attr.isId to determine if an attribute is of type ID.

Note: Attributes with the name "ID" or "id" are not of type ID unless so defined.

Parameters:
elementId - The unique id value for an element.
Returns:
The matching element or null if there is none.
Since:
DOM Level 2

getInputEncoding

String getInputEncoding()
An attribute specifying the encoding used for this document at the time of the parsing. This is null when it is not known, such as when the Document was created in memory.

Since:
DOM Level 3

getXmlEncoding

String getXmlEncoding()
An attribute specifying, as part of the XML declaration, the encoding of this document. This is null when unspecified or when it is not known, such as when the Document was created in memory.

Since:
DOM Level 3

getXmlStandalone

boolean getXmlStandalone()
An attribute specifying, as part of the XML declaration, whether this document is standalone. This is false when unspecified.

Note: No verification is done on the value when setting this attribute. Applications should use Document.normalizeDocument() with the "validate" parameter to verify if the value matches the validity constraint for standalone document declaration as defined in [XML 1.0].

Since:
DOM Level 3

setXmlStandalone

void setXmlStandalone(boolean xmlStandalone)
                      throws DOMException
An attribute specifying, as part of the XML declaration, whether this document is standalone. This is false when unspecified.

Note: No verification is done on the value when setting this attribute. Applications should use Document.normalizeDocument() with the "validate" parameter to verify if the value matches the validity constraint for standalone document declaration as defined in [XML 1.0].

Throws:
DOMException - NOT_SUPPORTED_ERR: Raised if this document does not support the "XML" feature.
Since:
DOM Level 3

getXmlVersion

String getXmlVersion()
An attribute specifying, as part of the XML declaration, the version number of this document. If there is no declaration and if this document supports the "XML" feature, the value is "1.0". If this document does not support the "XML" feature, the value is always null. Changing this attribute will affect methods that check for invalid characters in XML names. Application should invoke Document.normalizeDocument() in order to check for invalid characters in the Nodes that are already part of this Document.
DOM applications may use the DOMImplementation.hasFeature(feature, version) method with parameter values "XMLVersion" and "1.0" (respectively) to determine if an implementation supports [XML 1.0]. DOM applications may use the same method with parameter values "XMLVersion" and "1.1" (respectively) to determine if an implementation supports [XML 1.1]. In both cases, in order to support XML, an implementation must also support the "XML" feature defined in this specification. Document objects supporting a version of the "XMLVersion" feature must not raise a NOT_SUPPORTED_ERR exception for the same version number when using Document.xmlVersion.

Since:
DOM Level 3

setXmlVersion

void setXmlVersion(String xmlVersion)
                   throws DOMException
An attribute specifying, as part of the XML declaration, the version number of this document. If there is no declaration and if this document supports the "XML" feature, the value is "1.0". If this document does not support the "XML" feature, the value is always null. Changing this attribute will affect methods that check for invalid characters in XML names. Application should invoke Document.normalizeDocument() in order to check for invalid characters in the Nodes that are already part of this Document.
DOM applications may use the DOMImplementation.hasFeature(feature, version) method with parameter values "XMLVersion" and "1.0" (respectively) to determine if an implementation supports [XML 1.0]. DOM applications may use the same method with parameter values "XMLVersion" and "1.1" (respectively) to determine if an implementation supports [XML 1.1]. In both cases, in order to support XML, an implementation must also support the "XML" feature defined in this specification. Document objects supporting a version of the "XMLVersion" feature must not raise a NOT_SUPPORTED_ERR exception for the same version number when using Document.xmlVersion.

Throws:
DOMException - NOT_SUPPORTED_ERR: Raised if the version is set to a value that is not supported by this Document or if this document does not support the "XML" feature.
Since:
DOM Level 3

getStrictErrorChecking

boolean getStrictErrorChecking()
An attribute specifying whether error checking is enforced or not. When set to false, the implementation is free to not test every possible error case normally defined on DOM operations, and not raise any DOMException on DOM operations or report errors while using Document.normalizeDocument(). In case of error, the behavior is undefined. This attribute is true by default.

Since:
DOM Level 3

setStrictErrorChecking

void setStrictErrorChecking(boolean strictErrorChecking)
An attribute specifying whether error checking is enforced or not. When set to false, the implementation is free to not test every possible error case normally defined on DOM operations, and not raise any DOMException on DOM operations or report errors while using Document.normalizeDocument(). In case of error, the behavior is undefined. This attribute is true by default.

Since:
DOM Level 3

getDocumentURI

String getDocumentURI()
The location of the document or null if undefined or if the Document was created using DOMImplementation.createDocument. No lexical checking is performed when setting this attribute; this could result in a null value returned when using Node.baseURI .
Beware that when the Document supports the feature "HTML" [DOM Level 2 HTML] , the href attribute of the HTML BASE element takes precedence over this attribute when computing Node.baseURI.

Since:
DOM Level 3

setDocumentURI

void setDocumentURI(String documentURI)
The location of the document or null if undefined or if the Document was created using DOMImplementation.createDocument. No lexical checking is performed when setting this attribute; this could result in a null value returned when using Node.baseURI .
Beware that when the Document supports the feature "HTML" [DOM Level 2 HTML] , the href attribute of the HTML BASE element takes precedence over this attribute when computing Node.baseURI.

Since:
DOM Level 3

adoptNode

Node adoptNode(Node source)
               throws DOMException
Attempts to adopt a node from another document to this document. If supported, it changes the ownerDocument of the source node, its children, as well as the attached attribute nodes if there are any. If the source node has a parent it is first removed from the child list of its parent. This effectively allows moving a subtree from one document to another (unlike importNode() which create a copy of the source node instead of moving it). When it fails, applications should use Document.importNode() instead. Note that if the adopted node is already part of this document (i.e. the source and target document are the same), this method still has the effect of removing the source node from the child list of its parent, if any. The following list describes the specifics for each type of node.
ATTRIBUTE_NODE
The ownerElement attribute is set to null and the specified flag is set to true on the adopted Attr. The descendants of the source Attr are recursively adopted.
DOCUMENT_FRAGMENT_NODE
The descendants of the source node are recursively adopted.
DOCUMENT_NODE
Document nodes cannot be adopted.
DOCUMENT_TYPE_NODE
DocumentType nodes cannot be adopted.
ELEMENT_NODE
Specified attribute nodes of the source element are adopted. Default attributes are discarded, though if the document being adopted into defines default attributes for this element name, those are assigned. The descendants of the source element are recursively adopted.
ENTITY_NODE
Entity nodes cannot be adopted.
ENTITY_REFERENCE_NODE
Only the EntityReference node itself is adopted, the descendants are discarded, since the source and destination documents might have defined the entity differently. If the document being imported into provides a definition for this entity name, its value is assigned.
NOTATION_NODE
Notation nodes cannot be adopted.
PROCESSING_INSTRUCTION_NODE, TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE
These nodes can all be adopted. No specifics.

Note: Since it does not create new nodes unlike the Document.importNode() method, this method does not raise an INVALID_CHARACTER_ERR exception, and applications should use the Document.normalizeDocument() method to check if an imported name is not an XML name according to the XML version in use.

Parameters:
source - The node to move into this document.
Returns:
The adopted node, or null if this operation fails, such as when the source node comes from a different implementation.
Throws:
DOMException - NOT_SUPPORTED_ERR: Raised if the source node is of type DOCUMENT, DOCUMENT_TYPE.
NO_MODIFICATION_ALLOWED_ERR: Raised when the source node is readonly.
Since:
DOM Level 3

getDomConfig

DOMConfiguration getDomConfig()
The configuration used when Document.normalizeDocument() is invoked.

Since:
DOM Level 3

normalizeDocument

void normalizeDocument()
This method acts as if the document was going through a save and load cycle, putting the document in a "normal" form. As a consequence, this method updates the replacement tree of EntityReference nodes and normalizes Text nodes, as defined in the method Node.normalize().
Otherwise, the actual result depends on the features being set on the Document.domConfig object and governing what operations actually take place. Noticeably this method could also make the document namespace well-formed according to the algorithm described in , check the character normalization, remove the CDATASection nodes, etc. See DOMConfiguration for details.
// Keep in the document
 the information defined // in the XML Information Set (Java example)
 DOMConfiguration docConfig = myDocument.getDomConfig();
 docConfig.setParameter("infoset", Boolean.TRUE);
 myDocument.normalizeDocument();

Mutation events, when supported, are generated to reflect the changes occurring on the document.
If errors occur during the invocation of this method, such as an attempt to update a read-only node or a Node.nodeName contains an invalid character according to the XML version in use, errors or warnings (DOMError.SEVERITY_ERROR or DOMError.SEVERITY_WARNING) will be reported using the DOMErrorHandler object associated with the "error-handler " parameter. Note this method might also report fatal errors ( DOMError.SEVERITY_FATAL_ERROR) if an implementation cannot recover from an error.

Since:
DOM Level 3

renameNode

Node renameNode(Node n,
                String namespaceURI,
                String qualifiedName)
                throws DOMException
Rename an existing node of type ELEMENT_NODE or ATTRIBUTE_NODE.
When possible this simply changes the name of the given node, otherwise this creates a new node with the specified name and replaces the existing node with the new node as described below.
If simply changing the name of the given node is not possible, the following operations are performed: a new node is created, any registered event listener is registered on the new node, any user data attached to the old node is removed from that node, the old node is removed from its parent if it has one, the children are moved to the new node, if the renamed node is an Element its attributes are moved to the new node, the new node is inserted at the position the old node used to have in its parent's child nodes list if it has one, the user data that was attached to the old node is attached to the new node.
When the node being renamed is an Element only the specified attributes are moved, default attributes originated from the DTD are updated according to the new element name. In addition, the implementation may update default attributes from other schemas. Applications should use Document.normalizeDocument() to guarantee these attributes are up-to-date.
When the node being renamed is an Attr that is attached to an Element, the node is first removed from the Element attributes map. Then, once renamed, either by modifying the existing node or creating a new one as described above, it is put back.
In addition,
  • a user data event NODE_RENAMED is fired,
  • when the implementation supports the feature "MutationNameEvents", each mutation operation involved in this method fires the appropriate event, and in the end the event { http://www.w3.org/2001/xml-events, DOMElementNameChanged} or { http://www.w3.org/2001/xml-events, DOMAttributeNameChanged} is fired.

Parameters:
n - The node to rename.
namespaceURI - The new namespace URI.
qualifiedName - The new qualified name.
Returns:
The renamed node. This is either the specified node or the new node that was created to replace the specified node.
Throws:
DOMException - NOT_SUPPORTED_ERR: Raised when the type of the specified node is neither ELEMENT_NODE nor ATTRIBUTE_NODE, or if the implementation does not support the renaming of the document element.
INVALID_CHARACTER_ERR: Raised if the new qualified name is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.
WRONG_DOCUMENT_ERR: Raised when the specified node was created from a different document than this document.
NAMESPACE_ERR: Raised if the qualifiedName is a malformed qualified name, if the qualifiedName has a prefix and the namespaceURI is null, or if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from " http://www.w3.org/XML/1998/namespace" [XML Namespaces] . Also raised, when the node being renamed is an attribute, if the qualifiedName, or its prefix, is "xmlns" and the namespaceURI is different from "http://www.w3.org/2000/xmlns/".
Since:
DOM Level 3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocumentType

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface DocumentType

All Superinterfaces:
Node
public interface DocumentType
extends Node

Each Document has a doctype attribute whose value is either null or a DocumentType object. The DocumentType interface in the DOM Core provides an interface to the list of entities that are defined for the document, and little else because the effect of namespaces and the various XML schema efforts on DTD representation are not clearly understood as of this writing.

DOM Level 3 doesn't support editing DocumentType nodes. DocumentType nodes are read-only.

See also the Document Object Model (DOM) Level 3 Core Specification.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
NamedNodeMap | getEntities() A NamedNodeMap containing the general entities, both external and internal, declared in the DTD.
String | getInternalSubset() The internal subset as a string, or null if there is none.
String | getName() The name of DTD; i.e., the name immediately following the DOCTYPE keyword.
NamedNodeMap | getNotations() A NamedNodeMap containing the notations declared in the DTD.
String | getPublicId() The public identifier of the external subset.
String | getSystemId() The system identifier of the external subset.
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

getName

String getName()
The name of DTD; i.e., the name immediately following the DOCTYPE keyword.

getEntities

NamedNodeMap getEntities()
A NamedNodeMap containing the general entities, both external and internal, declared in the DTD. Parameter entities are not contained. Duplicates are discarded. For example in:
<!DOCTYPE
 ex SYSTEM "ex.dtd" [ <!ENTITY foo "foo"> <!ENTITY bar
 "bar"> <!ENTITY bar "bar2"> <!ENTITY % baz "baz">
 ]> <ex/>
the interface provides access to foo and the first declaration of bar but not the second declaration of bar or baz. Every node in this map also implements the Entity interface.
The DOM Level 2 does not support editing entities, therefore entities cannot be altered in any way.

getNotations

NamedNodeMap getNotations()
A NamedNodeMap containing the notations declared in the DTD. Duplicates are discarded. Every node in this map also implements the Notation interface.
The DOM Level 2 does not support editing notations, therefore notations cannot be altered in any way.

getPublicId

String getPublicId()
The public identifier of the external subset.

Since:
DOM Level 2

getSystemId

String getSystemId()
The system identifier of the external subset. This may be an absolute URI or not.

Since:
DOM Level 2

getInternalSubset

String getInternalSubset()
The internal subset as a string, or null if there is none. This is does not contain the delimiting square brackets.

Note: The actual content returned depends on how much information is available to the implementation. This may vary depending on various parameters, including the XML processor used to build the document.

Since:
DOM Level 2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DOMConfiguration

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface DOMConfiguration

public interface DOMConfiguration

The DOMConfiguration interface represents the configuration of a document and maintains a table of recognized parameters. Using the configuration, it is possible to change Document.normalizeDocument() behavior, such as replacing the CDATASection nodes with Text nodes or specifying the type of the schema that must be used when the validation of the Document is requested. DOMConfiguration objects are also used in [DOM Level 3 Load and Save] in the DOMParser and DOMSerializer interfaces.

The parameter names used by the DOMConfiguration object are defined throughout the DOM Level 3 specifications. Names are case-insensitive. To avoid possible conflicts, as a convention, names referring to parameters defined outside the DOM specification should be made unique. Because parameters are exposed as properties in names are recommended to follow the section 5.16 Identifiers of [Unicode] with the addition of the character '-' (HYPHEN-MINUS) but it is not enforced by the DOM implementation. DOM Level 3 Core Implementations are required to recognize all parameters defined in this specification. Some parameter values may also be required to be supported by the implementation. Refer to the definition of the parameter to know if a value must be supported or not.

Note: Parameters are similar to features and properties used in SAX2 [SAX].

The following list of parameters defined in the DOM:

"canonical-form"
true
[optional] Canonicalize the document according to the rules specified in [Canonical XML], such as removing the DocumentType node (if any) from the tree, or removing superfluous namespace declarations from each element. Note that this is limited to what can be represented in the DOM; in particular, there is no way to specify the order of the attributes in the DOM. In addition, Setting this parameter to true will also set the state of the parameters listed below. Later changes to the state of one of those parameters will revert "canonical-form" back to false. Parameters set to false: "entities", " normalize-characters", "cdata-sections". Parameters set to true: "namespaces", "namespace-declarations", "well-formed", "element-content-whitespace". Other parameters are not changed unless explicitly specified in the description of the parameters.
false
[required] (default)Do not canonicalize the document.
"cdata-sections"
true
[required] (default)Keep CDATASection nodes in the document.
false
[required]Transform CDATASection nodes in the document into Text nodes. The new Text node is then combined with any adjacent Text node.
"check-character-normalization"
true
[optional] Check if the characters in the document are fully normalized, as defined in appendix B of [XML 1.1]. When a sequence of characters is encountered that fails normalization checking, an error with the DOMError.type equals to "check-character-normalization-failure" is issued.
false
[required] (default)Do not check if characters are normalized.
"comments"
true
[required] (default)Keep Comment nodes in the document.
false
[required]Discard Comment nodes in the document.
"datatype-normalization"
true
[optional] Expose schema normalized values in the tree, such as XML Schema normalized values in the case of XML Schema. Since this parameter requires to have schema information, the "validate" parameter will also be set to true. Having this parameter activated when "validate" is false has no effect and no schema-normalization will happen.

Note: Since the document contains the result of the XML 1.0 processing, this parameter does not apply to attribute value normalization as defined in section 3.3.3 of [XML 1.0] and is only meant for schema languages other than Document Type Definition (DTD).

false
[required] (default) Do not perform schema normalization on the tree.
"element-content-whitespace"
true
[required] (default)Keep all whitespaces in the document.
false
[optional] Discard all Text nodes that contain whitespaces in element content, as described in [element content whitespace]. The implementation is expected to use the attribute Text.isElementContentWhitespace to determine if a Text node should be discarded or not.
"entities"
true
[required] (default)Keep EntityReference nodes in the document.
false
[required] Remove all EntityReference nodes from the document, putting the entity expansions directly in their place. Text nodes are normalized, as defined in Node.normalize. Only unexpanded entity references are kept in the document.

Note: This parameter does not affect Entity nodes.

"error-handler"
[required] Contains a DOMErrorHandler object. If an error is encountered in the document, the implementation will call back the DOMErrorHandler registered using this parameter. The implementation may provide a default DOMErrorHandler object. When called, DOMError.relatedData will contain the closest node to where the error occurred. If the implementation is unable to determine the node where the error occurs, DOMError.relatedData will contain the Document node. Mutations to the document from within an error handler will result in implementation dependent behavior.
"infoset"
true
[required]Keep in the document the information defined in the XML Information Set [XML Information Set] .This forces the following parameters to false: " validate-if-schema", "entities", "datatype-normalization", "cdata-sections ".This forces the following parameters to true: " namespace-declarations", "well-formed", "element-content-whitespace", " comments", "namespaces".Other parameters are not changed unless explicitly specified in the description of the parameters. Note that querying this parameter with getParameter returns true only if the individual parameters specified above are appropriately set.
false
Setting infoset to false has no effect.
"namespaces"
true
[required] (default) Perform the namespace processing as defined in .
false
[optional] Do not perform the namespace processing.
"namespace-declarations"
This parameter has no effect if the parameter "namespaces" is set to false.
true
[required] (default) Include namespace declaration attributes, specified or defaulted from the schema, in the document. See also the sections "Declaring Namespaces" in [XML Namespaces] and [XML Namespaces 1.1] .
false
[required]Discard all namespace declaration attributes. The namespace prefixes ( Node.prefix) are retained even if this parameter is set to false.
"normalize-characters"
true
[optional] Fully normalized the characters in the document as defined in appendix B of [XML 1.1].
false
[required] (default)Do not perform character normalization.
"schema-location"
[optional] Represent a DOMString object containing a list of URIs, separated by whitespaces (characters matching the nonterminal production S defined in section 2.3 [XML 1.0]), that represents the schemas against which validation should occur, i.e. the current schema. The types of schemas referenced in this list must match the type specified with schema-type, otherwise the behavior of an implementation is undefined. The schemas specified using this property take precedence to the schema information specified in the document itself. For namespace aware schema, if a schema specified using this property and a schema specified in the document instance (i.e. using the schemaLocation attribute) in a schema document (i.e. using schema import mechanisms) share the same targetNamespace, the schema specified by the user using this property will be used. If two schemas specified using this property share the same targetNamespace or have no namespace, the behavior is implementation dependent. If no location has been provided, this parameter is null.

Note: The "schema-location" parameter is ignored unless the "schema-type" parameter value is set. It is strongly recommended that Document.documentURI will be set so that an implementation can successfully resolve any external entities referenced.

"schema-type"
[optional] Represent a DOMString object containing an absolute URI and representing the type of the schema language used to validate a document against. Note that no lexical checking is done on the absolute URI. If this parameter is not set, a default value may be provided by the implementation, based on the schema languages supported and on the schema language used at load time. If no value is provided, this parameter is null.

Note: For XML Schema [XML Schema Part 1] , applications must use the value "http://www.w3.org/2001/XMLSchema". For XML DTD [XML 1.0], applications must use the value "http://www.w3.org/TR/REC-xml". Other schema languages are outside the scope of the W3C and therefore should recommend an absolute URI in order to use this method.

"split-cdata-sections"
true
[required] (default)Split CDATA sections containing the CDATA section termination marker ']]>'. When a CDATA section is split a warning is issued with a DOMError.type equals to "cdata-sections-splitted" and DOMError.relatedData equals to the first CDATASection node in document order resulting from the split.
false
[required]Signal an error if a CDATASection contains an unrepresentable character.
"validate"
true
[optional] Require the validation against a schema (i.e. XML schema, DTD, any other type or representation of schema) of the document as it is being normalized as defined by [XML 1.0]. If validation errors are found, or no schema was found, the error handler is notified. Schema-normalized values will not be exposed according to the schema in used unless the parameter "datatype-normalization" is true. This parameter will reevaluate:
  • Attribute nodes with Attr.specified equals to false, as specified in the description of the Attr interface;
  • The value of the attribute Text.isElementContentWhitespace for all Text nodes;
  • The value of the attribute Attr.isId for all Attr nodes;
  • The attributes Element.schemaTypeInfo and Attr.schemaTypeInfo.

Note: "validate-if-schema" and "validate" are mutually exclusive, setting one of them to true will set the other one to false. Applications should also consider setting the parameter "well-formed" to true, which is the default for that option, when validating the document.

false
[required] (default) Do not accomplish schema processing, including the internal subset processing. Default attribute values information are kept. Note that validation might still happen if "validate-if-schema" is true .
"validate-if-schema"
true
[optional]Enable validation only if a declaration for the document element can be found in a schema (independently of where it is found, i.e. XML schema, DTD, or any other type or representation of schema). If validation is enabled, this parameter has the same behavior as the parameter "validate" set to true.

Note: "validate-if-schema" and "validate" are mutually exclusive, setting one of them to true will set the other one to false.

false
[required] (default) No schema processing should be performed if the document has a schema, including internal subset processing. Default attribute values information are kept. Note that validation must still happen if "validate " is true.
"well-formed"
true
[required] (default) Check if all nodes are XML well formed according to the XML version in use in Document.xmlVersion:
  • check if the attribute Node.nodeName contains invalid characters according to its node type and generate a DOMError of type "wf-invalid-character-in-node-name", with a DOMError.SEVERITY_ERROR severity, if necessary;
  • check if the text content inside Attr, Element, Comment, Text, CDATASection nodes for invalid characters and generate a DOMError of type "wf-invalid-character", with a DOMError.SEVERITY_ERROR severity, if necessary;
  • check if the data inside ProcessingInstruction nodes for invalid characters and generate a DOMError of type "wf-invalid-character", with a DOMError.SEVERITY_ERROR severity, if necessary;
false
[optional] Do not check for XML well-formedness.

The resolution of the system identifiers associated with entities is done using Document.documentURI. However, when the feature "LS" defined in [DOM Level 3 Load and Save] is supported by the DOM implementation, the parameter "resource-resolver" can also be used on DOMConfiguration objects attached to Document nodes. If this parameter is set, Document.normalizeDocument() will invoke the resource resolver instead of using Document.documentURI.

See also the Document Object Model (DOM) Level 3 Core Specification.

Since:
DOM Level 3

Method Summary
boolean | canSetParameter(String name, Object value) Check if setting a parameter to a specific value is supported.
Object | getParameter(String name) Return the value of a parameter if known.
DOMStringList | getParameterNames() The list of the parameters supported by this DOMConfiguration object and for which at least one value can be set by the application.
void | setParameter(String name, Object value) Set the value of a parameter.

Method Detail

setParameter

void setParameter(String name,
                  Object value)
                  throws DOMException
Set the value of a parameter.

Parameters:
name - The name of the parameter to set.
value - The new value or null if the user wishes to unset the parameter. While the type of the value parameter is defined as DOMUserData, the object type must match the type defined by the definition of the parameter. For example, if the parameter is "error-handler", the value must be of type DOMErrorHandler.
Throws:
DOMException - NOT_FOUND_ERR: Raised when the parameter name is not recognized.
NOT_SUPPORTED_ERR: Raised when the parameter name is recognized but the requested value cannot be set.
TYPE_MISMATCH_ERR: Raised if the value type for this parameter name is incompatible with the expected value type.

getParameter

Object getParameter(String name)
                    throws DOMException
Return the value of a parameter if known.

Parameters:
name - The name of the parameter.
Returns:
The current object associated with the specified parameter or null if no object has been associated or if the parameter is not supported.
Throws:
DOMException - NOT_FOUND_ERR: Raised when the parameter name is not recognized.

canSetParameter

boolean canSetParameter(String name,
                        Object value)
Check if setting a parameter to a specific value is supported.

Parameters:
name - The name of the parameter to check.
value - An object. if null, the returned value is true.
Returns:
true if the parameter could be successfully set to the specified value, or false if the parameter is not recognized or the requested value is not supported. This does not change the current value of the parameter itself.

getParameterNames

DOMStringList getParameterNames()
The list of the parameters supported by this DOMConfiguration object and for which at least one value can be set by the application. Note that this list can also contain parameter names defined outside this specification.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DOMError

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface DOMError

public interface DOMError

DOMError is an interface that describes an error.

See also the Document Object Model (DOM) Level 3 Core Specification.

Since:
DOM Level 3

Field Summary
static short | SEVERITY_ERROR The severity of the error described by the DOMError is error.
static short | SEVERITY_FATAL_ERROR The severity of the error described by the DOMError is fatal error.
static short | SEVERITY_WARNING The severity of the error described by the DOMError is warning.
Method Summary
DOMLocator | getLocation() The location of the error.
String | getMessage() An implementation specific string describing the error that occurred.
Object | getRelatedData() The related DOMError.type dependent data if any.
Object | getRelatedException() The related platform dependent exception if any.
short | getSeverity() The severity of the error, either SEVERITY_WARNING, SEVERITY_ERROR, or SEVERITY_FATAL_ERROR.
String | getType() A DOMString indicating which related data is expected in relatedData.

Field Detail

SEVERITY_WARNING

static final short SEVERITY_WARNING
The severity of the error described by the DOMError is warning. A SEVERITY_WARNING will not cause the processing to stop, unless DOMErrorHandler.handleError() returns false.

See Also:
Constant Field Values

SEVERITY_ERROR

static final short SEVERITY_ERROR
The severity of the error described by the DOMError is error. A SEVERITY_ERROR may not cause the processing to stop if the error can be recovered, unless DOMErrorHandler.handleError() returns false.

See Also:
Constant Field Values

SEVERITY_FATAL_ERROR

static final short SEVERITY_FATAL_ERROR
The severity of the error described by the DOMError is fatal error. A SEVERITY_FATAL_ERROR will cause the normal processing to stop. The return value of DOMErrorHandler.handleError() is ignored unless the implementation chooses to continue, in which case the behavior becomes undefined.

See Also:
Constant Field Values
Method Detail

getSeverity

short getSeverity()
The severity of the error, either SEVERITY_WARNING, SEVERITY_ERROR, or SEVERITY_FATAL_ERROR.

getMessage

String getMessage()
An implementation specific string describing the error that occurred.

getType

String getType()
A DOMString indicating which related data is expected in relatedData. Users should refer to the specification of the error in order to find its DOMString type and relatedData definitions if any.

Note: As an example, Document.normalizeDocument() does generate warnings when the "split-cdata-sections" parameter is in use. Therefore, the method generates a SEVERITY_WARNING with type "cdata-sections-splitted" and the first CDATASection node in document order resulting from the split is returned by the relatedData attribute.

getRelatedException

Object getRelatedException()
The related platform dependent exception if any.

getRelatedData

Object getRelatedData()
The related DOMError.type dependent data if any.

getLocation

DOMLocator getLocation()
The location of the error.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DOMErrorHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface DOMErrorHandler

public interface DOMErrorHandler

DOMErrorHandler is a callback interface that the DOM implementation can call when reporting errors that happens while processing XML data, or when doing some other processing (e.g. validating a document). A DOMErrorHandler object can be attached to a Document using the "error-handler" on the DOMConfiguration interface. If more than one error needs to be reported during an operation, the sequence and numbers of the errors passed to the error handler are implementation dependent.

The application that is using the DOM implementation is expected to implement this interface.

See also the Document Object Model (DOM) Level 3 Core Specification.

Since:
DOM Level 3

Method Summary
 boolean handleError(DOMError error)
This method is called on the error handler when an error occurs.

Method Detail

handleError

boolean handleError(DOMError error)
This method is called on the error handler when an error occurs.
If an exception is thrown from this method, it is considered to be equivalent of returning true.

Parameters:
error - The error object that describes the error. This object may be reused by the DOM implementation across multiple calls to the handleError method.
Returns:
If the handleError method returns false, the DOM implementation should stop the current processing when possible. If the method returns true, the processing may continue depending on DOMError.severity.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DOMException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Class DOMException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.w3c.dom.DOMException
All Implemented Interfaces:
Serializable
public class DOMException
extends RuntimeException

DOM operations only raise exceptions in "exceptional" circumstances, i.e., when an operation is impossible to perform (either for logical reasons, because data is lost, or because the implementation has become unstable). In general, DOM methods return specific error values in ordinary processing situations, such as out-of-bound errors when using NodeList.

Implementations should raise other exceptions under other circumstances. For example, implementations should raise an implementation-dependent exception if a null argument is passed when null was not expected.

Some languages and object systems do not support the concept of exceptions. For such systems, error conditions may be indicated using native error reporting mechanisms. For some bindings, for example, methods may return error codes similar to those listed in the corresponding method descriptions.

See also the Document Object Model (DOM) Level 3 Core Specification.

See Also:
Serialized Form

Field Summary
short | code
static short | DOMSTRING_SIZE_ERR If the specified range of text does not fit into a DOMString.
static short | HIERARCHY_REQUEST_ERR If any Node is inserted somewhere it doesn't belong.
static short | INDEX_SIZE_ERR If index or size is negative, or greater than the allowed value.
static short | INUSE_ATTRIBUTE_ERR If an attempt is made to add an attribute that is already in use elsewhere.
static short | INVALID_ACCESS_ERR If a parameter or an operation is not supported by the underlying object.
static short | INVALID_CHARACTER_ERR If an invalid or illegal character is specified, such as in an XML name.
static short | INVALID_MODIFICATION_ERR If an attempt is made to modify the type of the underlying object.
static short | INVALID_STATE_ERR If an attempt is made to use an object that is not, or is no longer, usable.
static short | NAMESPACE_ERR If an attempt is made to create or change an object in a way which is incorrect with regard to namespaces.
static short | NO_DATA_ALLOWED_ERR If data is specified for a Node which does not support data.
static short | NO_MODIFICATION_ALLOWED_ERR If an attempt is made to modify an object where modifications are not allowed.
static short | NOT_FOUND_ERR If an attempt is made to reference a Node in a context where it does not exist.
static short | NOT_SUPPORTED_ERR If the implementation does not support the requested type of object or operation.
static short | SYNTAX_ERR If an invalid or illegal string is specified.
static short | TYPE_MISMATCH_ERR If the type of an object is incompatible with the expected type of the parameter associated to the object.
static short | VALIDATION_ERR If a call to a method such as insertBefore or removeChild would make the Node invalid with respect to "partial validity", this exception would be raised and the operation would not be done.
static short | WRONG_DOCUMENT_ERR If a Node is used in a different document than the one that created it (that doesn't support it).
Constructor Summary
DOMException(short code, String message)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

code

public short code

INDEX_SIZE_ERR

public static final short INDEX_SIZE_ERR
If index or size is negative, or greater than the allowed value.

See Also:
Constant Field Values

DOMSTRING_SIZE_ERR

public static final short DOMSTRING_SIZE_ERR
If the specified range of text does not fit into a DOMString.

See Also:
Constant Field Values

HIERARCHY_REQUEST_ERR

public static final short HIERARCHY_REQUEST_ERR
If any Node is inserted somewhere it doesn't belong.

See Also:
Constant Field Values

WRONG_DOCUMENT_ERR

public static final short WRONG_DOCUMENT_ERR
If a Node is used in a different document than the one that created it (that doesn't support it).

See Also:
Constant Field Values

INVALID_CHARACTER_ERR

public static final short INVALID_CHARACTER_ERR
If an invalid or illegal character is specified, such as in an XML name.

See Also:
Constant Field Values

NO_DATA_ALLOWED_ERR

public static final short NO_DATA_ALLOWED_ERR
If data is specified for a Node which does not support data.

See Also:
Constant Field Values

NO_MODIFICATION_ALLOWED_ERR

public static final short NO_MODIFICATION_ALLOWED_ERR
If an attempt is made to modify an object where modifications are not allowed.

See Also:
Constant Field Values

NOT_FOUND_ERR

public static final short NOT_FOUND_ERR
If an attempt is made to reference a Node in a context where it does not exist.

See Also:
Constant Field Values

NOT_SUPPORTED_ERR

public static final short NOT_SUPPORTED_ERR
If the implementation does not support the requested type of object or operation.

See Also:
Constant Field Values

INUSE_ATTRIBUTE_ERR

public static final short INUSE_ATTRIBUTE_ERR
If an attempt is made to add an attribute that is already in use elsewhere.

See Also:
Constant Field Values

INVALID_STATE_ERR

public static final short INVALID_STATE_ERR
If an attempt is made to use an object that is not, or is no longer, usable.

Since:
DOM Level 2
See Also:
Constant Field Values

SYNTAX_ERR

public static final short SYNTAX_ERR
If an invalid or illegal string is specified.

Since:
DOM Level 2
See Also:
Constant Field Values

INVALID_MODIFICATION_ERR

public static final short INVALID_MODIFICATION_ERR
If an attempt is made to modify the type of the underlying object.

Since:
DOM Level 2
See Also:
Constant Field Values

NAMESPACE_ERR

public static final short NAMESPACE_ERR
If an attempt is made to create or change an object in a way which is incorrect with regard to namespaces.

Since:
DOM Level 2
See Also:
Constant Field Values

INVALID_ACCESS_ERR

public static final short INVALID_ACCESS_ERR
If a parameter or an operation is not supported by the underlying object.

Since:
DOM Level 2
See Also:
Constant Field Values

VALIDATION_ERR

public static final short VALIDATION_ERR
If a call to a method such as insertBefore or removeChild would make the Node invalid with respect to "partial validity", this exception would be raised and the operation would not be done. This code is used in [DOM Level 3 Validation] . Refer to this specification for further information.

Since:
DOM Level 3
See Also:
Constant Field Values

TYPE_MISMATCH_ERR

public static final short TYPE_MISMATCH_ERR
If the type of an object is incompatible with the expected type of the parameter associated to the object.

Since:
DOM Level 3
See Also:
Constant Field Values
Constructor Detail

DOMException

public DOMException(short code,
                    String message)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DOMImplementation

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface DOMImplementation

public interface DOMImplementation

The DOMImplementation interface provides a number of methods for performing operations that are independent of any particular instance of the document object model.

See also the Document Object Model (DOM) Level 3 Core Specification.

Method Summary
Document | createDocument(String namespaceURI, String qualifiedName, DocumentType doctype) Creates a DOM Document object of the specified type with its document element.
DocumentType | createDocumentType(String qualifiedName, String publicId, String systemId) Creates an empty DocumentType node.
Object | getFeature(String feature, String version) This method returns a specialized object which implements the specialized APIs of the specified feature and version, as specified in DOM Features.
boolean | hasFeature(String feature, String version) Test if the DOM implementation implements a specific feature and version, as specified in DOM Features.

Method Detail

hasFeature

boolean hasFeature(String feature,
                   String version)
Test if the DOM implementation implements a specific feature and version, as specified in DOM Features.

Parameters:
feature - The name of the feature to test.
version - This is the version number of the feature to test.
Returns:
true if the feature is implemented in the specified version, false otherwise.

createDocumentType

DocumentType createDocumentType(String qualifiedName,
                                String publicId,
                                String systemId)
                                throws DOMException
Creates an empty DocumentType node. Entity declarations and notations are not made available. Entity reference expansions and default attribute additions do not occur..

Parameters:
qualifiedName - The qualified name of the document type to be created.
publicId - The external subset public identifier.
systemId - The external subset system identifier.
Returns:
A new DocumentType node with Node.ownerDocument set to null.
Throws:
DOMException - INVALID_CHARACTER_ERR: Raised if the specified qualified name is not an XML name according to [XML 1.0].
NAMESPACE_ERR: Raised if the qualifiedName is malformed.
NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).
Since:
DOM Level 2

createDocument

Document createDocument(String namespaceURI,
                        String qualifiedName,
                        DocumentType doctype)
                        throws DOMException
Creates a DOM Document object of the specified type with its document element.
Note that based on the DocumentType given to create the document, the implementation may instantiate specialized Document objects that support additional features than the "Core", such as "HTML" [DOM Level 2 HTML] . On the other hand, setting the DocumentType after the document was created makes this very unlikely to happen. Alternatively, specialized Document creation methods, such as createHTMLDocument [DOM Level 2 HTML] , can be used to obtain specific types of Document objects.

Parameters:
namespaceURI - The namespace URI of the document element to create or null.
qualifiedName - The qualified name of the document element to be created or null.
doctype - The type of document to be created or null. When doctype is not null, its Node.ownerDocument attribute is set to the document being created.
Returns:
A new Document object with its document element. If the NamespaceURI, qualifiedName, and doctype are null, the returned Document is empty with no document element.
Throws:
DOMException - INVALID_CHARACTER_ERR: Raised if the specified qualified name is not an XML name according to [XML 1.0].
NAMESPACE_ERR: Raised if the qualifiedName is malformed, if the qualifiedName has a prefix and the namespaceURI is null, or if the qualifiedName is null and the namespaceURI is different from null, or if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from " http://www.w3.org/XML/1998/namespace" [XML Namespaces] , or if the DOM implementation does not support the "XML" feature but a non-null namespace URI was provided, since namespaces were defined by XML.
WRONG_DOCUMENT_ERR: Raised if doctype has already been used with a different document or was created from a different implementation.
NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).
Since:
DOM Level 2

getFeature

Object getFeature(String feature,
                  String version)
This method returns a specialized object which implements the specialized APIs of the specified feature and version, as specified in DOM Features. The specialized object may also be obtained by using binding-specific casting methods but is not necessarily expected to, as discussed in . This method also allow the implementation to provide specialized objects which do not support the DOMImplementation interface.

Parameters:
feature - The name of the feature requested. Note that any plus sign "+" prepended to the name of the feature will be ignored since it is not significant in the context of this method.
version - This is the version number of the feature to test.
Returns:
Returns an object which implements the specialized APIs of the specified feature and version, if any, or null if there is no object which implements interfaces associated with that feature. If the DOMObject returned by this method implements the DOMImplementation interface, it must delegate to the primary core DOMImplementation and not return results inconsistent with the primary core DOMImplementation such as hasFeature, getFeature, etc.
Since:
DOM Level 3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DOMImplementationList

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface DOMImplementationList

public interface DOMImplementationList

The DOMImplementationList interface provides the abstraction of an ordered collection of DOM implementations, without defining or constraining how this collection is implemented. The items in the DOMImplementationList are accessible via an integral index, starting from 0.

See also the Document Object Model (DOM) Level 3 Core Specification.

Since:
DOM Level 3

Method Summary
int | getLength() The number of DOMImplementations in the list.
DOMImplementation | item(int index) Returns the indexth item in the collection.

Method Detail

item

DOMImplementation item(int index)
Returns the indexth item in the collection. If index is greater than or equal to the number of DOMImplementations in the list, this returns null.

Parameters:
index - Index into the collection.
Returns:
The DOMImplementation at the index th position in the DOMImplementationList, or null if that is not a valid index.

getLength

int getLength()
The number of DOMImplementations in the list. The range of valid child node indices is 0 to length-1 inclusive.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DOMImplementationSource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface DOMImplementationSource

public interface DOMImplementationSource

This interface permits a DOM implementer to supply one or more implementations, based upon requested features and versions, as specified in . Each implemented DOMImplementationSource object is listed in the binding-specific list of available sources so that its DOMImplementation objects are made available.

See also the Document Object Model (DOM) Level 3 Core Specification.

Since:
DOM Level 3

Method Summary
DOMImplementation | getDOMImplementation(String features) A method to request the first DOM implementation that supports the specified features.
DOMImplementationList | getDOMImplementationList(String features) A method to request a list of DOM implementations that support the specified features and versions, as specified in .

Method Detail

getDOMImplementation

DOMImplementation getDOMImplementation(String features)
A method to request the first DOM implementation that supports the specified features.

Parameters:
features - A string that specifies which features and versions are required. This is a space separated list in which each feature is specified by its name optionally followed by a space and a version number. This method returns the first item of the list returned by getDOMImplementationList. As an example, the string "XML 3.0 Traversal +Events 2.0" will request a DOM implementation that supports the module "XML" for its 3.0 version, a module that support of the "Traversal" module for any version, and the module "Events" for its 2.0 version. The module "Events" must be accessible using the method Node.getFeature() and DOMImplementation.getFeature().
Returns:
The first DOM implementation that support the desired features, or null if this source has none.

getDOMImplementationList

DOMImplementationList getDOMImplementationList(String features)
A method to request a list of DOM implementations that support the specified features and versions, as specified in .

Parameters:
features - A string that specifies which features and versions are required. This is a space separated list in which each feature is specified by its name optionally followed by a space and a version number. This is something like: "XML 3.0 Traversal +Events 2.0"
Returns:
A list of DOM implementations that support the desired features.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DOMLocator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface DOMLocator

public interface DOMLocator

DOMLocator is an interface that describes a location (e.g. where an error occurred).

See also the Document Object Model (DOM) Level 3 Core Specification.

Since:
DOM Level 3

Method Summary
int | getByteOffset() The byte offset into the input source this locator is pointing to or -1 if there is no byte offset available.
int | getColumnNumber() The column number this locator is pointing to, or -1 if there is no column number available.
int | getLineNumber() The line number this locator is pointing to, or -1 if there is no column number available.
Node | getRelatedNode() The node this locator is pointing to, or null if no node is available.
String | getUri() The URI this locator is pointing to, or null if no URI is available.
int | getUtf16Offset() The UTF-16, as defined in [Unicode] and Amendment 1 of [ISO/IEC 10646], offset into the input source this locator is pointing to or -1 if there is no UTF-16 offset available.

Method Detail

getLineNumber

int getLineNumber()
The line number this locator is pointing to, or -1 if there is no column number available.

getColumnNumber

int getColumnNumber()
The column number this locator is pointing to, or -1 if there is no column number available.

getByteOffset

int getByteOffset()
The byte offset into the input source this locator is pointing to or -1 if there is no byte offset available.

getUtf16Offset

int getUtf16Offset()
The UTF-16, as defined in [Unicode] and Amendment 1 of [ISO/IEC 10646], offset into the input source this locator is pointing to or -1 if there is no UTF-16 offset available.

getRelatedNode

Node getRelatedNode()
The node this locator is pointing to, or null if no node is available.

getUri

String getUri()
The URI this locator is pointing to, or null if no URI is available.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DOMStringList

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface DOMStringList

public interface DOMStringList

The DOMStringList interface provides the abstraction of an ordered collection of DOMString values, without defining or constraining how this collection is implemented. The items in the DOMStringList are accessible via an integral index, starting from 0.

See also the Document Object Model (DOM) Level 3 Core Specification.

Since:
DOM Level 3

Method Summary
boolean | contains(String str) Test if a string is part of this DOMStringList.
int | getLength() The number of DOMStrings in the list.
String | item(int index) Returns the indexth item in the collection.

Method Detail

item

String item(int index)
Returns the indexth item in the collection. If index is greater than or equal to the number of DOMStrings in the list, this returns null.

Parameters:
index - Index into the collection.
Returns:
The DOMString at the indexth position in the DOMStringList, or null if that is not a valid index.

getLength

int getLength()
The number of DOMStrings in the list. The range of valid child node indices is 0 to length-1 inclusive.

contains

boolean contains(String str)
Test if a string is part of this DOMStringList.

Parameters:
str - The string to look for.
Returns:
true if the string has been found, false otherwise.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Element

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface Element

All Superinterfaces:
Node
All Known Subinterfaces:
Detail, DetailEntry, SOAPBody, SOAPBodyElement, SOAPElement, SOAPEnvelope, SOAPFault, SOAPFaultElement, SOAPHeader, SOAPHeaderElement
All Known Implementing Classes:
IIOMetadataNode
public interface Element
extends Node

The Element interface represents an element in an HTML or XML document. Elements may have attributes associated with them; since the Element interface inherits from Node, the generic Node interface attribute attributes may be used to retrieve the set of all attributes for an element. There are methods on the Element interface to retrieve either an Attr object by name or an attribute value by name. In XML, where an attribute value may contain entity references, an Attr object should be retrieved to examine the possibly fairly complex sub-tree representing the attribute value. On the other hand, in HTML, where all attributes have simple string values, methods to directly access an attribute value can safely be used as a convenience.

Note: In DOM Level 2, the method normalize is inherited from the Node interface where it was moved.

See also the Document Object Model (DOM) Level 3 Core Specification.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
String | getAttribute(String name) Retrieves an attribute value by name.
Attr | getAttributeNode(String name) Retrieves an attribute node by name.
Attr | getAttributeNodeNS(String namespaceURI, String localName) Retrieves an Attr node by local name and namespace URI.
String | getAttributeNS(String namespaceURI, String localName) Retrieves an attribute value by local name and namespace URI.
NodeList | getElementsByTagName(String name) Returns a NodeList of all descendant Elements with a given tag name, in document order.
NodeList | getElementsByTagNameNS(String namespaceURI, String localName) Returns a NodeList of all the descendant Elements with a given local name and namespace URI in document order.
TypeInfo | getSchemaTypeInfo() The type information associated with this element.
String | getTagName() The name of the element.
boolean | hasAttribute(String name) Returns true when an attribute with a given name is specified on this element or has a default value, false otherwise.
boolean | hasAttributeNS(String namespaceURI, String localName) Returns true when an attribute with a given local name and namespace URI is specified on this element or has a default value, false otherwise.
void | removeAttribute(String name) Removes an attribute by name.
Attr | removeAttributeNode(Attr oldAttr) Removes the specified attribute node.
void | removeAttributeNS(String namespaceURI, String localName) Removes an attribute by local name and namespace URI.
void | setAttribute(String name, String value) Adds a new attribute.
Attr | setAttributeNode(Attr newAttr) Adds a new attribute node.
Attr | setAttributeNodeNS(Attr newAttr) Adds a new attribute.
void | setAttributeNS(String namespaceURI, String qualifiedName, String value) Adds a new attribute.
void | setIdAttribute(String name, boolean isId) If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute .
void | setIdAttributeNode(Attr idAttr, boolean isId) If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute .
void | setIdAttributeNS(String namespaceURI, String localName, boolean isId) If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute .
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

getTagName

String getTagName()
The name of the element. If Node.localName is different from null, this attribute is a qualified name. For example, in:
 <elementExample id="demo"> ...
 </elementExample> ,
tagName has the value "elementExample". Note that this is case-preserving in XML, as are all of the operations of the DOM. The HTML DOM returns the tagName of an HTML element in the canonical uppercase form, regardless of the case in the source HTML document.

getAttribute

String getAttribute(String name)
Retrieves an attribute value by name.

Parameters:
name - The name of the attribute to retrieve.
Returns:
The Attr value as a string, or the empty string if that attribute does not have a specified or default value.

setAttribute

void setAttribute(String name,
                  String value)
                  throws DOMException
Adds a new attribute. If an attribute with that name is already present in the element, its value is changed to be that of the value parameter. This value is a simple string; it is not parsed as it is being set. So any markup (such as syntax to be recognized as an entity reference) is treated as literal text, and needs to be appropriately escaped by the implementation when it is written out. In order to assign an attribute value that contains entity references, the user must create an Attr node plus any Text and EntityReference nodes, build the appropriate subtree, and use setAttributeNode to assign it as the value of an attribute.
To set an attribute with a qualified name and namespace URI, use the setAttributeNS method.

Parameters:
name - The name of the attribute to create or alter.
value - Value to set in string form.
Throws:
DOMException - INVALID_CHARACTER_ERR: Raised if the specified name is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

removeAttribute

void removeAttribute(String name)
                     throws DOMException
Removes an attribute by name. If a default value for the removed attribute is defined in the DTD, a new attribute immediately appears with the default value as well as the corresponding namespace URI, local name, and prefix when applicable. The implementation may handle default values from other schemas similarly but applications should use Document.normalizeDocument() to guarantee this information is up-to-date.
If no attribute with this name is found, this method has no effect.
To remove an attribute by local name and namespace URI, use the removeAttributeNS method.

Parameters:
name - The name of the attribute to remove.
Throws:
DOMException - NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

getAttributeNode

Attr getAttributeNode(String name)
Retrieves an attribute node by name.
To retrieve an attribute node by qualified name and namespace URI, use the getAttributeNodeNS method.

Parameters:
name - The name (nodeName) of the attribute to retrieve.
Returns:
The Attr node with the specified name ( nodeName) or null if there is no such attribute.

setAttributeNode

Attr setAttributeNode(Attr newAttr)
                      throws DOMException
Adds a new attribute node. If an attribute with that name ( nodeName) is already present in the element, it is replaced by the new one. Replacing an attribute node by itself has no effect.
To add a new attribute node with a qualified name and namespace URI, use the setAttributeNodeNS method.

Parameters:
newAttr - The Attr node to add to the attribute list.
Returns:
If the newAttr attribute replaces an existing attribute, the replaced Attr node is returned, otherwise null is returned.
Throws:
DOMException - WRONG_DOCUMENT_ERR: Raised if newAttr was created from a different document than the one that created the element.
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
INUSE_ATTRIBUTE_ERR: Raised if newAttr is already an attribute of another Element object. The DOM user must explicitly clone Attr nodes to re-use them in other elements.

removeAttributeNode

Attr removeAttributeNode(Attr oldAttr)
                         throws DOMException
Removes the specified attribute node. If a default value for the removed Attr node is defined in the DTD, a new node immediately appears with the default value as well as the corresponding namespace URI, local name, and prefix when applicable. The implementation may handle default values from other schemas similarly but applications should use Document.normalizeDocument() to guarantee this information is up-to-date.

Parameters:
oldAttr - The Attr node to remove from the attribute list.
Returns:
The Attr node that was removed.
Throws:
DOMException - NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
NOT_FOUND_ERR: Raised if oldAttr is not an attribute of the element.

getElementsByTagName

NodeList getElementsByTagName(String name)
Returns a NodeList of all descendant Elements with a given tag name, in document order.

Parameters:
name - The name of the tag to match on. The special value "*" matches all tags.
Returns:
A list of matching Element nodes.

getAttributeNS

String getAttributeNS(String namespaceURI,
                      String localName)
                      throws DOMException
Retrieves an attribute value by local name and namespace URI.
Per [XML Namespaces] , applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.

Parameters:
namespaceURI - The namespace URI of the attribute to retrieve.
localName - The local name of the attribute to retrieve.
Returns:
The Attr value as a string, or the empty string if that attribute does not have a specified or default value.
Throws:
DOMException - NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).
Since:
DOM Level 2

setAttributeNS

void setAttributeNS(String namespaceURI,
                    String qualifiedName,
                    String value)
                    throws DOMException
Adds a new attribute. If an attribute with the same local name and namespace URI is already present on the element, its prefix is changed to be the prefix part of the qualifiedName, and its value is changed to be the value parameter. This value is a simple string; it is not parsed as it is being set. So any markup (such as syntax to be recognized as an entity reference) is treated as literal text, and needs to be appropriately escaped by the implementation when it is written out. In order to assign an attribute value that contains entity references, the user must create an Attr node plus any Text and EntityReference nodes, build the appropriate subtree, and use setAttributeNodeNS or setAttributeNode to assign it as the value of an attribute.
Per [XML Namespaces] , applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.

Parameters:
namespaceURI - The namespace URI of the attribute to create or alter.
qualifiedName - The qualified name of the attribute to create or alter.
value - The value to set in string form.
Throws:
DOMException - INVALID_CHARACTER_ERR: Raised if the specified qualified name is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
NAMESPACE_ERR: Raised if the qualifiedName is malformed per the Namespaces in XML specification, if the qualifiedName has a prefix and the namespaceURI is null, if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from " http://www.w3.org/XML/1998/namespace", if the qualifiedName or its prefix is "xmlns" and the namespaceURI is different from "http://www.w3.org/2000/xmlns/", or if the namespaceURI is "http://www.w3.org/2000/xmlns/" and neither the qualifiedName nor its prefix is "xmlns".
NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).
Since:
DOM Level 2

removeAttributeNS

void removeAttributeNS(String namespaceURI,
                       String localName)
                       throws DOMException
Removes an attribute by local name and namespace URI. If a default value for the removed attribute is defined in the DTD, a new attribute immediately appears with the default value as well as the corresponding namespace URI, local name, and prefix when applicable. The implementation may handle default values from other schemas similarly but applications should use Document.normalizeDocument() to guarantee this information is up-to-date.
If no attribute with this local name and namespace URI is found, this method has no effect.
Per [XML Namespaces] , applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.

Parameters:
namespaceURI - The namespace URI of the attribute to remove.
localName - The local name of the attribute to remove.
Throws:
DOMException - NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).
Since:
DOM Level 2

getAttributeNodeNS

Attr getAttributeNodeNS(String namespaceURI,
                        String localName)
                        throws DOMException
Retrieves an Attr node by local name and namespace URI.
Per [XML Namespaces] , applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.

Parameters:
namespaceURI - The namespace URI of the attribute to retrieve.
localName - The local name of the attribute to retrieve.
Returns:
The Attr node with the specified attribute local name and namespace URI or null if there is no such attribute.
Throws:
DOMException - NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).
Since:
DOM Level 2

setAttributeNodeNS

Attr setAttributeNodeNS(Attr newAttr)
                        throws DOMException
Adds a new attribute. If an attribute with that local name and that namespace URI is already present in the element, it is replaced by the new one. Replacing an attribute node by itself has no effect.
Per [XML Namespaces] , applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.

Parameters:
newAttr - The Attr node to add to the attribute list.
Returns:
If the newAttr attribute replaces an existing attribute with the same local name and namespace URI, the replaced Attr node is returned, otherwise null is returned.
Throws:
DOMException - WRONG_DOCUMENT_ERR: Raised if newAttr was created from a different document than the one that created the element.
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
INUSE_ATTRIBUTE_ERR: Raised if newAttr is already an attribute of another Element object. The DOM user must explicitly clone Attr nodes to re-use them in other elements.
NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).
Since:
DOM Level 2

getElementsByTagNameNS

NodeList getElementsByTagNameNS(String namespaceURI,
                                String localName)
                                throws DOMException
Returns a NodeList of all the descendant Elements with a given local name and namespace URI in document order.

Parameters:
namespaceURI - The namespace URI of the elements to match on. The special value "*" matches all namespaces.
localName - The local name of the elements to match on. The special value "*" matches all local names.
Returns:
A new NodeList object containing all the matched Elements.
Throws:
DOMException - NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).
Since:
DOM Level 2

hasAttribute

boolean hasAttribute(String name)
Returns true when an attribute with a given name is specified on this element or has a default value, false otherwise.

Parameters:
name - The name of the attribute to look for.
Returns:
true if an attribute with the given name is specified on this element or has a default value, false otherwise.
Since:
DOM Level 2

hasAttributeNS

boolean hasAttributeNS(String namespaceURI,
                       String localName)
                       throws DOMException
Returns true when an attribute with a given local name and namespace URI is specified on this element or has a default value, false otherwise.
Per [XML Namespaces] , applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.

Parameters:
namespaceURI - The namespace URI of the attribute to look for.
localName - The local name of the attribute to look for.
Returns:
true if an attribute with the given local name and namespace URI is specified or has a default value on this element, false otherwise.
Throws:
DOMException - NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).
Since:
DOM Level 2

getSchemaTypeInfo

TypeInfo getSchemaTypeInfo()
The type information associated with this element.

Since:
DOM Level 3

setIdAttribute

void setIdAttribute(String name,
                    boolean isId)
                    throws DOMException
If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute . This affects the value of Attr.isId and the behavior of Document.getElementById, but does not change any schema that may be in use, in particular this does not affect the Attr.schemaTypeInfo of the specified Attr node. Use the value false for the parameter isId to undeclare an attribute for being a user-determined ID attribute.
To specify an attribute by local name and namespace URI, use the setIdAttributeNS method.

Parameters:
name - The name of the attribute.
isId - Whether the attribute is a of type ID.
Throws:
DOMException - NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
NOT_FOUND_ERR: Raised if the specified node is not an attribute of this element.
Since:
DOM Level 3

setIdAttributeNS

void setIdAttributeNS(String namespaceURI,
                      String localName,
                      boolean isId)
                      throws DOMException
If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute . This affects the value of Attr.isId and the behavior of Document.getElementById, but does not change any schema that may be in use, in particular this does not affect the Attr.schemaTypeInfo of the specified Attr node. Use the value false for the parameter isId to undeclare an attribute for being a user-determined ID attribute.

Parameters:
namespaceURI - The namespace URI of the attribute.
localName - The local name of the attribute.
isId - Whether the attribute is a of type ID.
Throws:
DOMException - NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
NOT_FOUND_ERR: Raised if the specified node is not an attribute of this element.
Since:
DOM Level 3

setIdAttributeNode

void setIdAttributeNode(Attr idAttr,
                        boolean isId)
                        throws DOMException
If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute . This affects the value of Attr.isId and the behavior of Document.getElementById, but does not change any schema that may be in use, in particular this does not affect the Attr.schemaTypeInfo of the specified Attr node. Use the value false for the parameter isId to undeclare an attribute for being a user-determined ID attribute.

Parameters:
idAttr - The attribute node.
isId - Whether the attribute is a of type ID.
Throws:
DOMException - NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
NOT_FOUND_ERR: Raised if the specified node is not an attribute of this element.
Since:
DOM Level 3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Entity

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface Entity

All Superinterfaces:
Node
public interface Entity
extends Node

This interface represents a known entity, either parsed or unparsed, in an XML document. Note that this models the entity itself not the entity declaration.

The nodeName attribute that is inherited from Node contains the name of the entity.

An XML processor may choose to completely expand entities before the structure model is passed to the DOM; in this case there will be no EntityReference nodes in the document tree.

XML does not mandate that a non-validating XML processor read and process entity declarations made in the external subset or declared in parameter entities. This means that parsed entities declared in the external subset need not be expanded by some classes of applications, and that the replacement text of the entity may not be available. When the replacement text is available, the corresponding Entity node's child list represents the structure of that replacement value. Otherwise, the child list is empty.

DOM Level 3 does not support editing Entity nodes; if a user wants to make changes to the contents of an Entity, every related EntityReference node has to be replaced in the structure model by a clone of the Entity's contents, and then the desired changes must be made to each of those clones instead. Entity nodes and all their descendants are readonly.

An Entity node does not have any parent.

Note: If the entity contains an unbound namespace prefix, the namespaceURI of the corresponding node in the Entity node subtree is null. The same is true for EntityReference nodes that refer to this entity, when they are created using the createEntityReference method of the Document interface.

See also the Document Object Model (DOM) Level 3 Core Specification.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
String | getInputEncoding() An attribute specifying the encoding used for this entity at the time of parsing, when it is an external parsed entity.
String | getNotationName() For unparsed entities, the name of the notation for the entity.
String | getPublicId() The public identifier associated with the entity if specified, and null otherwise.
String | getSystemId() The system identifier associated with the entity if specified, and null otherwise.
String | getXmlEncoding() An attribute specifying, as part of the text declaration, the encoding of this entity, when it is an external parsed entity.
String | getXmlVersion() An attribute specifying, as part of the text declaration, the version number of this entity, when it is an external parsed entity.
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

getPublicId

String getPublicId()
The public identifier associated with the entity if specified, and null otherwise.

getSystemId

String getSystemId()
The system identifier associated with the entity if specified, and null otherwise. This may be an absolute URI or not.

getNotationName

String getNotationName()
For unparsed entities, the name of the notation for the entity. For parsed entities, this is null.

getInputEncoding

String getInputEncoding()
An attribute specifying the encoding used for this entity at the time of parsing, when it is an external parsed entity. This is null if it an entity from the internal subset or if it is not known.

Since:
DOM Level 3

getXmlEncoding

String getXmlEncoding()
An attribute specifying, as part of the text declaration, the encoding of this entity, when it is an external parsed entity. This is null otherwise.

Since:
DOM Level 3

getXmlVersion

String getXmlVersion()
An attribute specifying, as part of the text declaration, the version number of this entity, when it is an external parsed entity. This is null otherwise.

Since:
DOM Level 3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


events

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.w3c.dom.events

Interface Summary
DocumentEvent | The DocumentEvent interface provides a mechanism by which the user can create an Event of a type supported by the implementation.
Event | The Event interface is used to provide contextual information about an event to the handler processing the event.
EventListener | The EventListener interface is the primary method for handling events.
EventTarget | The EventTarget interface is implemented by all Nodes in an implementation which supports the DOM Event Model.
MouseEvent | The MouseEvent interface provides specific contextual information associated with Mouse events.
MutationEvent | The MutationEvent interface provides specific contextual information associated with Mutation events.
UIEvent | The UIEvent interface provides specific contextual information associated with User Interface events.

Exception Summary
EventException Event operations may throw an EventException as specified in their method descriptions.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.w3c.dom.events Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.w3c.dom.events

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.lang.RuntimeException
          • org.w3c.dom.events.EventException

Interface Hierarchy

  • org.w3c.dom.events.DocumentEvent
  • org.w3c.dom.events.Event
    • org.w3c.dom.events.MutationEvent
    • org.w3c.dom.events.UIEvent
      • org.w3c.dom.events.MouseEvent
  • org.w3c.dom.events.EventListener
  • org.w3c.dom.events.EventTarget
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.w3c.dom.events

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.w3c.dom.events

Packages that use org.w3c.dom.events
org.w3c.dom.events
org.w3c.dom.ls

Classes in org.w3c.dom.events used by org.w3c.dom.events
Event
The Event interface is used to provide contextual information about an event to the handler processing the event.
EventException
Event operations may throw an EventException as specified in their method descriptions.
EventListener
The EventListener interface is the primary method for handling events.
EventTarget
The EventTarget interface is implemented by all Nodes in an implementation which supports the DOM Event Model.
UIEvent
The UIEvent interface provides specific contextual information associated with User Interface events.

Classes in org.w3c.dom.events used by org.w3c.dom.ls
Event
The Event interface is used to provide contextual information about an event to the handler processing the event.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.w3c.dom.events.EventException

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.w3c.dom.events.EventException

Packages that use EventException
org.w3c.dom.events

Uses of EventException in org.w3c.dom.events

Methods in org.w3c.dom.events that throw EventException
 boolean EventTarget.dispatchEvent(Event evt)
This method allows the dispatch of events into the implementations event model.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.events.DocumentEvent

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.events.DocumentEvent

No usage of org.w3c.dom.events.DocumentEvent

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.events.Event

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.events.Event

Packages that use Event
org.w3c.dom.events
org.w3c.dom.ls

Uses of Event in org.w3c.dom.events

Subinterfaces of Event in org.w3c.dom.events
interface | MouseEvent The MouseEvent interface provides specific contextual information associated with Mouse events.
interface | MutationEvent The MutationEvent interface provides specific contextual information associated with Mutation events.
interface | UIEvent The UIEvent interface provides specific contextual information associated with User Interface events.

Methods in org.w3c.dom.events that return Event
 Event DocumentEvent.createEvent(String eventType)

Methods in org.w3c.dom.events with parameters of type Event
boolean | EventTarget.dispatchEvent(Event evt) This method allows the dispatch of events into the implementations event model.
void | EventListener.handleEvent(Event evt) This method is called whenever an event occurs of the type for which the EventListener interface was registered.

Uses of Event in org.w3c.dom.ls

Subinterfaces of Event in org.w3c.dom.ls
interface | LSLoadEvent This interface represents a load event object that signals the completion of a document load.
interface | LSProgressEvent This interface represents a progress event object that notifies the application about progress as a document is parsed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.events.EventListener

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.events.EventListener

Packages that use EventListener
org.w3c.dom.events

Uses of EventListener in org.w3c.dom.events

Methods in org.w3c.dom.events with parameters of type EventListener
void | EventTarget.addEventListener(String type, EventListener listener, boolean useCapture) This method allows the registration of event listeners on the event target.
void | EventTarget.removeEventListener(String type, EventListener listener, boolean useCapture) This method allows the removal of event listeners from the event target.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.events.EventTarget

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.events.EventTarget

Packages that use EventTarget
org.w3c.dom.events

Uses of EventTarget in org.w3c.dom.events

Methods in org.w3c.dom.events that return EventTarget
EventTarget | Event.getCurrentTarget() Used to indicate the EventTarget whose EventListeners are currently being processed.
EventTarget | MouseEvent.getRelatedTarget() Used to identify a secondary EventTarget related to a UI event.
EventTarget | Event.getTarget() Used to indicate the EventTarget to which the event was originally dispatched.

Methods in org.w3c.dom.events with parameters of type EventTarget
 void MouseEvent.initMouseEvent(String typeArg, boolean canBubbleArg, boolean cancelableArg, org.w3c.dom.views.AbstractView viewArg, int detailArg, int screenXArg, int screenYArg, int clientXArg, int clientYArg, boolean ctrlKeyArg, boolean altKeyArg, boolean shiftKeyArg, boolean metaKeyArg, short buttonArg, EventTarget relatedTargetArg)
The initMouseEvent method is used to initialize the value of a MouseEvent created through the DocumentEvent interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.events.MouseEvent

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.events.MouseEvent

No usage of org.w3c.dom.events.MouseEvent

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.events.MutationEvent

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.events.MutationEvent

No usage of org.w3c.dom.events.MutationEvent

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.events.UIEvent

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.events.UIEvent

Packages that use UIEvent
org.w3c.dom.events

Uses of UIEvent in org.w3c.dom.events

Subinterfaces of UIEvent in org.w3c.dom.events
 interface MouseEvent
The MouseEvent interface provides specific contextual information associated with Mouse events.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DocumentEvent

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.events
Interface DocumentEvent

public interface DocumentEvent

The DocumentEvent interface provides a mechanism by which the user can create an Event of a type supported by the implementation. It is expected that the DocumentEvent interface will be implemented on the same object which implements the Document interface in an implementation which supports the Event model.

See also the Document Object Model (DOM) Level 2 Events Specification.

Since:
DOM Level 2

Method Summary
 Event createEvent(String eventType)

Method Detail

createEvent

Event createEvent(String eventType)
                  throws DOMException
Parameters:
eventType - The eventType parameter specifies the type of Event interface to be created. If the Event interface specified is supported by the implementation this method will return a new Event of the interface type requested. If the Event is to be dispatched via the dispatchEvent method the appropriate event init method must be called after creation in order to initialize the Event's values. As an example, a user wishing to synthesize some kind of UIEvent would call createEvent with the parameter "UIEvents". The initUIEvent method could then be called on the newly created UIEvent to set the specific type of UIEvent to be dispatched and set its context information.The createEvent method is used in creating Events when it is either inconvenient or unnecessary for the user to create an Event themselves. In cases where the implementation provided Event is insufficient, users may supply their own Event implementations for use with the dispatchEvent method.
Returns:
The newly created Event
Throws:
DOMException - NOT_SUPPORTED_ERR: Raised if the implementation does not support the type of Event interface requested
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Event

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.events
Interface Event

All Known Subinterfaces:
LSLoadEvent, LSProgressEvent, MouseEvent, MutationEvent, UIEvent
public interface Event

The Event interface is used to provide contextual information about an event to the handler processing the event. An object which implements the Event interface is generally passed as the first parameter to an event handler. More specific context information is passed to event handlers by deriving additional interfaces from Event which contain information directly relating to the type of event they accompany. These derived interfaces are also implemented by the object passed to the event listener.

See also the Document Object Model (DOM) Level 2 Events Specification.

Since:
DOM Level 2

Field Summary
static short | AT_TARGET The event is currently being evaluated at the target EventTarget.
static short | BUBBLING_PHASE The current event phase is the bubbling phase.
static short | CAPTURING_PHASE The current event phase is the capturing phase.
Method Summary
boolean | getBubbles() Used to indicate whether or not an event is a bubbling event.
boolean | getCancelable() Used to indicate whether or not an event can have its default action prevented.
EventTarget | getCurrentTarget() Used to indicate the EventTarget whose EventListeners are currently being processed.
short | getEventPhase() Used to indicate which phase of event flow is currently being evaluated.
EventTarget | getTarget() Used to indicate the EventTarget to which the event was originally dispatched.
long | getTimeStamp() Used to specify the time (in milliseconds relative to the epoch) at which the event was created.
String | getType() The name of the event (case-insensitive).
void | initEvent(String eventTypeArg, boolean canBubbleArg, boolean cancelableArg) The initEvent method is used to initialize the value of an Event created through the DocumentEvent interface.
void | preventDefault() If an event is cancelable, the preventDefault method is used to signify that the event is to be canceled, meaning any default action normally taken by the implementation as a result of the event will not occur.
void | stopPropagation() The stopPropagation method is used prevent further propagation of an event during event flow.

Field Detail

CAPTURING_PHASE

static final short CAPTURING_PHASE
The current event phase is the capturing phase.

See Also:
Constant Field Values

AT_TARGET

static final short AT_TARGET
The event is currently being evaluated at the target EventTarget.

See Also:
Constant Field Values

BUBBLING_PHASE

static final short BUBBLING_PHASE
The current event phase is the bubbling phase.

See Also:
Constant Field Values
Method Detail

getType

String getType()
The name of the event (case-insensitive). The name must be an XML name.

getTarget

EventTarget getTarget()
Used to indicate the EventTarget to which the event was originally dispatched.

getCurrentTarget

EventTarget getCurrentTarget()
Used to indicate the EventTarget whose EventListeners are currently being processed. This is particularly useful during capturing and bubbling.

getEventPhase

short getEventPhase()
Used to indicate which phase of event flow is currently being evaluated.

getBubbles

boolean getBubbles()
Used to indicate whether or not an event is a bubbling event. If the event can bubble the value is true, else the value is false.

getCancelable

boolean getCancelable()
Used to indicate whether or not an event can have its default action prevented. If the default action can be prevented the value is true, else the value is false.

getTimeStamp

long getTimeStamp()
Used to specify the time (in milliseconds relative to the epoch) at which the event was created. Due to the fact that some systems may not provide this information the value of timeStamp may be not available for all events. When not available, a value of 0 will be returned. Examples of epoch time are the time of the system start or 0:0:0 UTC 1st January 1970.

stopPropagation

void stopPropagation()
The stopPropagation method is used prevent further propagation of an event during event flow. If this method is called by any EventListener the event will cease propagating through the tree. The event will complete dispatch to all listeners on the current EventTarget before event flow stops. This method may be used during any stage of event flow.

preventDefault

void preventDefault()
If an event is cancelable, the preventDefault method is used to signify that the event is to be canceled, meaning any default action normally taken by the implementation as a result of the event will not occur. If, during any stage of event flow, the preventDefault method is called the event is canceled. Any default action associated with the event will not occur. Calling this method for a non-cancelable event has no effect. Once preventDefault has been called it will remain in effect throughout the remainder of the event's propagation. This method may be used during any stage of event flow.

initEvent

void initEvent(String eventTypeArg,
               boolean canBubbleArg,
               boolean cancelableArg)
The initEvent method is used to initialize the value of an Event created through the DocumentEvent interface. This method may only be called before the Event has been dispatched via the dispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times the final invocation takes precedence. If called from a subclass of Event interface only the values specified in the initEvent method are modified, all other attributes are left unchanged.

Parameters:
eventTypeArg - Specifies the event type. This type may be any event type currently defined in this specification or a new event type.. The string must be an XML name. Any new event type must not begin with any upper, lower, or mixed case version of the string "DOM". This prefix is reserved for future DOM event sets. It is also strongly recommended that third parties adding their own events use their own prefix to avoid confusion and lessen the probability of conflicts with other new events.
canBubbleArg - Specifies whether or not the event can bubble.
cancelableArg - Specifies whether or not the event's default action can be prevented.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EventException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.events
Class EventException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.w3c.dom.events.EventException
All Implemented Interfaces:
Serializable
public class EventException
extends RuntimeException

Event operations may throw an EventException as specified in their method descriptions.

See also the Document Object Model (DOM) Level 2 Events Specification.

Since:
DOM Level 2
See Also:
Serialized Form

Field Summary
short | code
static short | UNSPECIFIED_EVENT_TYPE_ERR If the Event's type was not specified by initializing the event before the method was called.
Constructor Summary
EventException(short code, String message)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

code

public short code

UNSPECIFIED_EVENT_TYPE_ERR

public static final short UNSPECIFIED_EVENT_TYPE_ERR
If the Event's type was not specified by initializing the event before the method was called. Specification of the Event's type as null or an empty string will also trigger this exception.

See Also:
Constant Field Values
Constructor Detail

EventException

public EventException(short code,
                      String message)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EventListener

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.events
Interface EventListener

public interface EventListener

The EventListener interface is the primary method for handling events. Users implement the EventListener interface and register their listener on an EventTarget using the AddEventListener method. The users should also remove their EventListener from its EventTarget after they have completed using the listener.

When a Node is copied using the cloneNode method the EventListeners attached to the source Node are not attached to the copied Node. If the user wishes the same EventListeners to be added to the newly created copy the user must add them manually.

See also the Document Object Model (DOM) Level 2 Events Specification.

Since:
DOM Level 2

Method Summary
 void handleEvent(Event evt)
This method is called whenever an event occurs of the type for which the EventListener interface was registered.

Method Detail

handleEvent

void handleEvent(Event evt)
This method is called whenever an event occurs of the type for which the EventListener interface was registered.

Parameters:
evt - The Event contains contextual information about the event. It also contains the stopPropagation and preventDefault methods which are used in determining the event's flow and default action.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EventTarget

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.events
Interface EventTarget

public interface EventTarget

The EventTarget interface is implemented by all Nodes in an implementation which supports the DOM Event Model. Therefore, this interface can be obtained by using binding-specific casting methods on an instance of the Node interface. The interface allows registration and removal of EventListeners on an EventTarget and dispatch of events to that EventTarget.

See also the Document Object Model (DOM) Level 2 Events Specification.

Since:
DOM Level 2

Method Summary
void | addEventListener(String type, EventListener listener, boolean useCapture) This method allows the registration of event listeners on the event target.
boolean | dispatchEvent(Event evt) This method allows the dispatch of events into the implementations event model.
void | removeEventListener(String type, EventListener listener, boolean useCapture) This method allows the removal of event listeners from the event target.

Method Detail

addEventListener

void addEventListener(String type,
                      EventListener listener,
                      boolean useCapture)
This method allows the registration of event listeners on the event target. If an EventListener is added to an EventTarget while it is processing an event, it will not be triggered by the current actions but may be triggered during a later stage of event flow, such as the bubbling phase.
If multiple identical EventListeners are registered on the same EventTarget with the same parameters the duplicate instances are discarded. They do not cause the EventListener to be called twice and since they are discarded they do not need to be removed with the removeEventListener method.

Parameters:
type - The event type for which the user is registering
listener - The listener parameter takes an interface implemented by the user which contains the methods to be called when the event occurs.
useCapture - If true, useCapture indicates that the user wishes to initiate capture. After initiating capture, all events of the specified type will be dispatched to the registered EventListener before being dispatched to any EventTargets beneath them in the tree. Events which are bubbling upward through the tree will not trigger an EventListener designated to use capture.

removeEventListener

void removeEventListener(String type,
                         EventListener listener,
                         boolean useCapture)
This method allows the removal of event listeners from the event target. If an EventListener is removed from an EventTarget while it is processing an event, it will not be triggered by the current actions. EventListeners can never be invoked after being removed.
Calling removeEventListener with arguments which do not identify any currently registered EventListener on the EventTarget has no effect.

Parameters:
type - Specifies the event type of the EventListener being removed.
listener - The EventListener parameter indicates the EventListener to be removed.
useCapture - Specifies whether the EventListener being removed was registered as a capturing listener or not. If a listener was registered twice, one with capture and one without, each must be removed separately. Removal of a capturing listener does not affect a non-capturing version of the same listener, and vice versa.

dispatchEvent

boolean dispatchEvent(Event evt)
                      throws EventException
This method allows the dispatch of events into the implementations event model. Events dispatched in this manner will have the same capturing and bubbling behavior as events dispatched directly by the implementation. The target of the event is the EventTarget on which dispatchEvent is called.

Parameters:
evt - Specifies the event type, behavior, and contextual information to be used in processing the event.
Returns:
The return value of dispatchEvent indicates whether any of the listeners which handled the event called preventDefault. If preventDefault was called the value is false, else the value is true.
Throws:
EventException - UNSPECIFIED_EVENT_TYPE_ERR: Raised if the Event's type was not specified by initializing the event before dispatchEvent was called. Specification of the Event's type as null or an empty string will also trigger this exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MouseEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.events
Interface MouseEvent

All Superinterfaces:
Event, UIEvent
public interface MouseEvent
extends UIEvent

The MouseEvent interface provides specific contextual information associated with Mouse events.

The detail attribute inherited from UIEvent indicates the number of times a mouse button has been pressed and released over the same screen location during a user action. The attribute value is 1 when the user begins this action and increments by 1 for each full sequence of pressing and releasing. If the user moves the mouse between the mousedown and mouseup the value will be set to 0, indicating that no click is occurring.

In the case of nested elements mouse events are always targeted at the most deeply nested element. Ancestors of the targeted element may use bubbling to obtain notification of mouse events which occur within its descendent elements.

See also the Document Object Model (DOM) Level 2 Events Specification.

Since:
DOM Level 2

Field Summary
Fields inherited from interface org.w3c.dom.events.Event
AT_TARGET, BUBBLING_PHASE, CAPTURING_PHASE
Method Summary
boolean | getAltKey() Used to indicate whether the 'alt' key was depressed during the firing of the event.
short | getButton() During mouse events caused by the depression or release of a mouse button, button is used to indicate which mouse button changed state.
int | getClientX() The horizontal coordinate at which the event occurred relative to the DOM implementation's client area.
int | getClientY() The vertical coordinate at which the event occurred relative to the DOM implementation's client area.
boolean | getCtrlKey() Used to indicate whether the 'ctrl' key was depressed during the firing of the event.
boolean | getMetaKey() Used to indicate whether the 'meta' key was depressed during the firing of the event.
EventTarget | getRelatedTarget() Used to identify a secondary EventTarget related to a UI event.
int | getScreenX() The horizontal coordinate at which the event occurred relative to the origin of the screen coordinate system.
int | getScreenY() The vertical coordinate at which the event occurred relative to the origin of the screen coordinate system.
boolean | getShiftKey() Used to indicate whether the 'shift' key was depressed during the firing of the event.
void | initMouseEvent(String typeArg, boolean canBubbleArg, boolean cancelableArg, org.w3c.dom.views.AbstractView viewArg, int detailArg, int screenXArg, int screenYArg, int clientXArg, int clientYArg, boolean ctrlKeyArg, boolean altKeyArg, boolean shiftKeyArg, boolean metaKeyArg, short buttonArg, EventTarget relatedTargetArg) The initMouseEvent method is used to initialize the value of a MouseEvent created through the DocumentEvent interface.
Methods inherited from interface org.w3c.dom.events.UIEvent
getDetail, getView, initUIEvent
Methods inherited from interface org.w3c.dom.events.Event
getBubbles, getCancelable, getCurrentTarget, getEventPhase, getTarget, getTimeStamp, getType, initEvent, preventDefault, stopPropagation

Method Detail

getScreenX

int getScreenX()
The horizontal coordinate at which the event occurred relative to the origin of the screen coordinate system.

getScreenY

int getScreenY()
The vertical coordinate at which the event occurred relative to the origin of the screen coordinate system.

getClientX

int getClientX()
The horizontal coordinate at which the event occurred relative to the DOM implementation's client area.

getClientY

int getClientY()
The vertical coordinate at which the event occurred relative to the DOM implementation's client area.

getCtrlKey

boolean getCtrlKey()
Used to indicate whether the 'ctrl' key was depressed during the firing of the event.

getShiftKey

boolean getShiftKey()
Used to indicate whether the 'shift' key was depressed during the firing of the event.

getAltKey

boolean getAltKey()
Used to indicate whether the 'alt' key was depressed during the firing of the event. On some platforms this key may map to an alternative key name.

getMetaKey

boolean getMetaKey()
Used to indicate whether the 'meta' key was depressed during the firing of the event. On some platforms this key may map to an alternative key name.

getButton

short getButton()
During mouse events caused by the depression or release of a mouse button, button is used to indicate which mouse button changed state. The values for button range from zero to indicate the left button of the mouse, one to indicate the middle button if present, and two to indicate the right button. For mice configured for left handed use in which the button actions are reversed the values are instead read from right to left.

getRelatedTarget

EventTarget getRelatedTarget()
Used to identify a secondary EventTarget related to a UI event. Currently this attribute is used with the mouseover event to indicate the EventTarget which the pointing device exited and with the mouseout event to indicate the EventTarget which the pointing device entered.

initMouseEvent

void initMouseEvent(String typeArg,
                    boolean canBubbleArg,
                    boolean cancelableArg,
                    org.w3c.dom.views.AbstractView viewArg,
                    int detailArg,
                    int screenXArg,
                    int screenYArg,
                    int clientXArg,
                    int clientYArg,
                    boolean ctrlKeyArg,
                    boolean altKeyArg,
                    boolean shiftKeyArg,
                    boolean metaKeyArg,
                    short buttonArg,
                    EventTarget relatedTargetArg)
The initMouseEvent method is used to initialize the value of a MouseEvent created through the DocumentEvent interface. This method may only be called before the MouseEvent has been dispatched via the dispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence.

Parameters:
typeArg - Specifies the event type.
canBubbleArg - Specifies whether or not the event can bubble.
cancelableArg - Specifies whether or not the event's default action can be prevented.
viewArg - Specifies the Event's AbstractView.
detailArg - Specifies the Event's mouse click count.
screenXArg - Specifies the Event's screen x coordinate
screenYArg - Specifies the Event's screen y coordinate
clientXArg - Specifies the Event's client x coordinate
clientYArg - Specifies the Event's client y coordinate
ctrlKeyArg - Specifies whether or not control key was depressed during the Event.
altKeyArg - Specifies whether or not alt key was depressed during the Event.
shiftKeyArg - Specifies whether or not shift key was depressed during the Event.
metaKeyArg - Specifies whether or not meta key was depressed during the Event.
buttonArg - Specifies the Event's mouse button.
relatedTargetArg - Specifies the Event's related EventTarget.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MutationEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.events
Interface MutationEvent

All Superinterfaces:
Event
public interface MutationEvent
extends Event

The MutationEvent interface provides specific contextual information associated with Mutation events.

See also the Document Object Model (DOM) Level 2 Events Specification.

Since:
DOM Level 2

Field Summary
static short | ADDITION The Attr was just added.
static short | MODIFICATION The Attr was modified in place.
static short | REMOVAL The Attr was just removed.
Fields inherited from interface org.w3c.dom.events.Event
AT_TARGET, BUBBLING_PHASE, CAPTURING_PHASE
Method Summary
short | getAttrChange() attrChange indicates the type of change which triggered the DOMAttrModified event.
String | getAttrName() attrName indicates the name of the changed Attr node in a DOMAttrModified event.
String | getNewValue() newValue indicates the new value of the Attr node in DOMAttrModified events, and of the CharacterData node in DOMCharacterDataModified events.
String | getPrevValue() prevValue indicates the previous value of the Attr node in DOMAttrModified events, and of the CharacterData node in DOMCharacterDataModified events.
Node | getRelatedNode() relatedNode is used to identify a secondary node related to a mutation event.
void | initMutationEvent(String typeArg, boolean canBubbleArg, boolean cancelableArg, Node relatedNodeArg, String prevValueArg, String newValueArg, String attrNameArg, short attrChangeArg) The initMutationEvent method is used to initialize the value of a MutationEvent created through the DocumentEvent interface.
Methods inherited from interface org.w3c.dom.events.Event
getBubbles, getCancelable, getCurrentTarget, getEventPhase, getTarget, getTimeStamp, getType, initEvent, preventDefault, stopPropagation

Field Detail

MODIFICATION

static final short MODIFICATION
The Attr was modified in place.

See Also:
Constant Field Values

ADDITION

static final short ADDITION
The Attr was just added.

See Also:
Constant Field Values

REMOVAL

static final short REMOVAL
The Attr was just removed.

See Also:
Constant Field Values
Method Detail

getRelatedNode

Node getRelatedNode()
relatedNode is used to identify a secondary node related to a mutation event. For example, if a mutation event is dispatched to a node indicating that its parent has changed, the relatedNode is the changed parent. If an event is instead dispatched to a subtree indicating a node was changed within it, the relatedNode is the changed node. In the case of the DOMAttrModified event it indicates the Attr node which was modified, added, or removed.

getPrevValue

String getPrevValue()
prevValue indicates the previous value of the Attr node in DOMAttrModified events, and of the CharacterData node in DOMCharacterDataModified events.

getNewValue

String getNewValue()
newValue indicates the new value of the Attr node in DOMAttrModified events, and of the CharacterData node in DOMCharacterDataModified events.

getAttrName

String getAttrName()
attrName indicates the name of the changed Attr node in a DOMAttrModified event.

getAttrChange

short getAttrChange()
attrChange indicates the type of change which triggered the DOMAttrModified event. The values can be MODIFICATION , ADDITION, or REMOVAL.

initMutationEvent

void initMutationEvent(String typeArg,
                       boolean canBubbleArg,
                       boolean cancelableArg,
                       Node relatedNodeArg,
                       String prevValueArg,
                       String newValueArg,
                       String attrNameArg,
                       short attrChangeArg)
The initMutationEvent method is used to initialize the value of a MutationEvent created through the DocumentEvent interface. This method may only be called before the MutationEvent has been dispatched via the dispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence.

Parameters:
typeArg - Specifies the event type.
canBubbleArg - Specifies whether or not the event can bubble.
cancelableArg - Specifies whether or not the event's default action can be prevented.
relatedNodeArg - Specifies the Event's related Node.
prevValueArg - Specifies the Event's prevValue attribute. This value may be null.
newValueArg - Specifies the Event's newValue attribute. This value may be null.
attrNameArg - Specifies the Event's attrName attribute. This value may be null.
attrChangeArg - Specifies the Event's attrChange attribute
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UIEvent

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.events
Interface UIEvent

All Superinterfaces:
Event
All Known Subinterfaces:
MouseEvent
public interface UIEvent
extends Event

The UIEvent interface provides specific contextual information associated with User Interface events.

See also the Document Object Model (DOM) Level 2 Events Specification.

Since:
DOM Level 2

Field Summary
Fields inherited from interface org.w3c.dom.events.Event
AT_TARGET, BUBBLING_PHASE, CAPTURING_PHASE
Method Summary
int | getDetail() Specifies some detail information about the Event, depending on the type of event.
org.w3c.dom.views.AbstractView | getView() The view attribute identifies the AbstractView from which the event was generated.
void | initUIEvent(String typeArg, boolean canBubbleArg, boolean cancelableArg, org.w3c.dom.views.AbstractView viewArg, int detailArg) The initUIEvent method is used to initialize the value of a UIEvent created through the DocumentEvent interface.
Methods inherited from interface org.w3c.dom.events.Event
getBubbles, getCancelable, getCurrentTarget, getEventPhase, getTarget, getTimeStamp, getType, initEvent, preventDefault, stopPropagation

Method Detail

getView

org.w3c.dom.views.AbstractView getView()
The view attribute identifies the AbstractView from which the event was generated.

getDetail

int getDetail()
Specifies some detail information about the Event, depending on the type of event.

initUIEvent

void initUIEvent(String typeArg,
                 boolean canBubbleArg,
                 boolean cancelableArg,
                 org.w3c.dom.views.AbstractView viewArg,
                 int detailArg)
The initUIEvent method is used to initialize the value of a UIEvent created through the DocumentEvent interface. This method may only be called before the UIEvent has been dispatched via the dispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence.

Parameters:
typeArg - Specifies the event type.
canBubbleArg - Specifies whether or not the event can bubble.
cancelableArg - Specifies whether or not the event's default action can be prevented.
viewArg - Specifies the Event's AbstractView.
detailArg - Specifies the Event's detail.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


ls

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.w3c.dom.ls

Interface Summary
DOMImplementationLS | DOMImplementationLS contains the factory methods for creating Load and Save objects.
LSInput | This interface represents an input source for data.
LSLoadEvent | This interface represents a load event object that signals the completion of a document load.
LSOutput | This interface represents an output destination for data.
LSParser | An interface to an object that is able to build, or augment, a DOM tree from various input sources.
LSParserFilter | LSParserFilters provide applications the ability to examine nodes as they are being constructed while parsing.
LSProgressEvent | This interface represents a progress event object that notifies the application about progress as a document is parsed.
LSResourceResolver | LSResourceResolver provides a way for applications to redirect references to external resources.
LSSerializer | A LSSerializer provides an API for serializing (writing) a DOM document out into XML.
LSSerializerFilter | LSSerializerFilters provide applications the ability to examine nodes as they are being serialized and decide what nodes should be serialized or not.

Exception Summary
LSException Parser or write operations may throw an LSException if the processing is stopped.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.w3c.dom.ls Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.w3c.dom.ls

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.lang.RuntimeException
          • org.w3c.dom.ls.LSException

Interface Hierarchy

  • org.w3c.dom.ls.DOMImplementationLS
  • org.w3c.dom.events.Event
    • org.w3c.dom.ls.LSLoadEvent
    • org.w3c.dom.ls.LSProgressEvent
  • org.w3c.dom.ls.LSInput
  • org.w3c.dom.ls.LSOutput
  • org.w3c.dom.ls.LSParser
  • org.w3c.dom.ls.LSParserFilter
  • org.w3c.dom.ls.LSResourceResolver
  • org.w3c.dom.ls.LSSerializer
  • org.w3c.dom.traversal.NodeFilter
    • org.w3c.dom.ls.LSSerializerFilter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.w3c.dom.ls

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.w3c.dom.ls

Packages that use org.w3c.dom.ls
javax.xml.validation | This package provides an API for validation of XML documents.
org.w3c.dom.ls |

Classes in org.w3c.dom.ls used by javax.xml.validation
LSResourceResolver
LSResourceResolver provides a way for applications to redirect references to external resources.

Classes in org.w3c.dom.ls used by org.w3c.dom.ls
LSException
Parser or write operations may throw an LSException if the processing is stopped.
LSInput
This interface represents an input source for data.
LSOutput
This interface represents an output destination for data.
LSParser
An interface to an object that is able to build, or augment, a DOM tree from various input sources.
LSParserFilter
LSParserFilters provide applications the ability to examine nodes as they are being constructed while parsing.
LSSerializer
A LSSerializer provides an API for serializing (writing) a DOM document out into XML.
LSSerializerFilter
LSSerializerFilters provide applications the ability to examine nodes as they are being serialized and decide what nodes should be serialized or not.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.w3c.dom.ls.LSException

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.w3c.dom.ls.LSException

Packages that use LSException
org.w3c.dom.ls

Uses of LSException in org.w3c.dom.ls

Methods in org.w3c.dom.ls that throw LSException
Document | LSParser.parse(LSInput input) Parse an XML document from a resource identified by a LSInput.
Document | LSParser.parseURI(String uri) Parse an XML document from a location identified by a URI reference [IETF RFC 2396].
Node | LSParser.parseWithContext(LSInput input, Node contextArg, short action) Parse an XML fragment from a resource identified by a LSInput and insert the content into an existing document at the position specified with the context and action arguments.
boolean | LSSerializer.write(Node nodeArg, LSOutput destination) Serialize the specified node as described above in the general description of the LSSerializer interface.
String | LSSerializer.writeToString(Node nodeArg) Serialize the specified node as described above in the general description of the LSSerializer interface.
boolean | LSSerializer.writeToURI(Node nodeArg, String uri) A convenience method that acts as if LSSerializer.write was called with a LSOutput with no encoding specified and LSOutput.systemId set to the uri argument.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.ls.DOMImplementationLS

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.ls.DOMImplementationLS

No usage of org.w3c.dom.ls.DOMImplementationLS

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.ls.LSInput

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.ls.LSInput

Packages that use LSInput
org.w3c.dom.ls

Uses of LSInput in org.w3c.dom.ls

Methods in org.w3c.dom.ls that return LSInput
LSInput | DOMImplementationLS.createLSInput() Create a new empty input source object where LSInput.characterStream, LSInput.byteStream , LSInput.stringData LSInput.systemId, LSInput.publicId, LSInput.baseURI, and LSInput.encoding are null, and LSInput.certifiedText is false.
LSInput | LSProgressEvent.getInput() The input source that is being parsed.
LSInput | LSLoadEvent.getInput() The input source that was parsed.
LSInput | LSResourceResolver.resolveResource(String type, String namespaceURI, String publicId, String systemId, String baseURI) Allow the application to resolve external resources.

Methods in org.w3c.dom.ls with parameters of type LSInput
Document | LSParser.parse(LSInput input) Parse an XML document from a resource identified by a LSInput.
Node | LSParser.parseWithContext(LSInput input, Node contextArg, short action) Parse an XML fragment from a resource identified by a LSInput and insert the content into an existing document at the position specified with the context and action arguments.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.ls.LSLoadEvent

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.ls.LSLoadEvent

No usage of org.w3c.dom.ls.LSLoadEvent

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.ls.LSOutput

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.ls.LSOutput

Packages that use LSOutput
org.w3c.dom.ls

Uses of LSOutput in org.w3c.dom.ls

Methods in org.w3c.dom.ls that return LSOutput
 LSOutput DOMImplementationLS.createLSOutput()
Create a new empty output destination object where LSOutput.characterStream, LSOutput.byteStream, LSOutput.systemId, LSOutput.encoding are null.

Methods in org.w3c.dom.ls with parameters of type LSOutput
 boolean LSSerializer.write(Node nodeArg, LSOutput destination)
Serialize the specified node as described above in the general description of the LSSerializer interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.ls.LSParser

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.ls.LSParser

Packages that use LSParser
org.w3c.dom.ls

Uses of LSParser in org.w3c.dom.ls

Methods in org.w3c.dom.ls that return LSParser
 LSParser DOMImplementationLS.createLSParser(short mode, String schemaType)
Create a new LSParser.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.ls.LSParserFilter

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.ls.LSParserFilter

Packages that use LSParserFilter
org.w3c.dom.ls

Uses of LSParserFilter in org.w3c.dom.ls

Methods in org.w3c.dom.ls that return LSParserFilter
 LSParserFilter LSParser.getFilter()
When a filter is provided, the implementation will call out to the filter as it is constructing the DOM tree structure.

Methods in org.w3c.dom.ls with parameters of type LSParserFilter
 void LSParser.setFilter(LSParserFilter filter)
When a filter is provided, the implementation will call out to the filter as it is constructing the DOM tree structure.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.ls.LSProgressEvent

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.ls.LSProgressEvent

No usage of org.w3c.dom.ls.LSProgressEvent

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.ls.LSResourceResolver

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.ls.LSResourceResolver

Packages that use LSResourceResolver
javax.xml.validation This package provides an API for validation of XML documents.

Uses of LSResourceResolver in javax.xml.validation

Methods in javax.xml.validation that return LSResourceResolver
abstract LSResourceResolver | SchemaFactory.getResourceResolver() Gets the current LSResourceResolver set to this SchemaFactory.
abstract LSResourceResolver | ValidatorHandler.getResourceResolver() Gets the current LSResourceResolver set to this ValidatorHandler.
abstract LSResourceResolver | Validator.getResourceResolver() Gets the current LSResourceResolver set to this Validator.

Methods in javax.xml.validation with parameters of type LSResourceResolver
abstract void | SchemaFactory.setResourceResolver(LSResourceResolver resourceResolver) Sets the LSResourceResolver to customize resource resolution when parsing schemas.
abstract void | ValidatorHandler.setResourceResolver(LSResourceResolver resourceResolver) Sets the LSResourceResolver to customize resource resolution while in a validation episode.
abstract void | Validator.setResourceResolver(LSResourceResolver resourceResolver) Sets the LSResourceResolver to customize resource resolution while in a validation episode.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.ls.LSSerializer

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.ls.LSSerializer

Packages that use LSSerializer
org.w3c.dom.ls

Uses of LSSerializer in org.w3c.dom.ls

Methods in org.w3c.dom.ls that return LSSerializer
 LSSerializer DOMImplementationLS.createLSSerializer()
Create a new LSSerializer object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.w3c.dom.ls.LSSerializerFilter

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.w3c.dom.ls.LSSerializerFilter

Packages that use LSSerializerFilter
org.w3c.dom.ls

Uses of LSSerializerFilter in org.w3c.dom.ls

Methods in org.w3c.dom.ls that return LSSerializerFilter
 LSSerializerFilter LSSerializer.getFilter()
When the application provides a filter, the serializer will call out to the filter before serializing each Node.

Methods in org.w3c.dom.ls with parameters of type LSSerializerFilter
 void LSSerializer.setFilter(LSSerializerFilter filter)
When the application provides a filter, the serializer will call out to the filter before serializing each Node.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DOMImplementationLS

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.ls
Interface DOMImplementationLS

public interface DOMImplementationLS

DOMImplementationLS contains the factory methods for creating Load and Save objects.

The expectation is that an instance of the DOMImplementationLS interface can be obtained by using binding-specific casting methods on an instance of the DOMImplementation interface or, if the Document supports the feature "Core" version "3.0" defined in [DOM Level 3 Core] , by using the method DOMImplementation.getFeature with parameter values "LS" (or "LS-Async") and "3.0" (respectively).

See also the Document Object Model (DOM) Level 3 Load and Save Specification.

Field Summary
static short | MODE_ASYNCHRONOUS Create an asynchronous LSParser.
static short | MODE_SYNCHRONOUS Create a synchronous LSParser.
Method Summary
LSInput | createLSInput() Create a new empty input source object where LSInput.characterStream, LSInput.byteStream , LSInput.stringData LSInput.systemId, LSInput.publicId, LSInput.baseURI, and LSInput.encoding are null, and LSInput.certifiedText is false.
LSOutput | createLSOutput() Create a new empty output destination object where LSOutput.characterStream, LSOutput.byteStream, LSOutput.systemId, LSOutput.encoding are null.
LSParser | createLSParser(short mode, String schemaType) Create a new LSParser.
LSSerializer | createLSSerializer() Create a new LSSerializer object.

Field Detail

MODE_SYNCHRONOUS

static final short MODE_SYNCHRONOUS
Create a synchronous LSParser.

See Also:
Constant Field Values

MODE_ASYNCHRONOUS

static final short MODE_ASYNCHRONOUS
Create an asynchronous LSParser.

See Also:
Constant Field Values
Method Detail

createLSParser

LSParser createLSParser(short mode,
                        String schemaType)
                        throws DOMException
Create a new LSParser. The newly constructed parser may then be configured by means of its DOMConfiguration object, and used to parse documents by means of its parse method.

Parameters:
mode - The mode argument is either MODE_SYNCHRONOUS or MODE_ASYNCHRONOUS, if mode is MODE_SYNCHRONOUS then the LSParser that is created will operate in synchronous mode, if it's MODE_ASYNCHRONOUS then the LSParser that is created will operate in asynchronous mode.
schemaType - An absolute URI representing the type of the schema language used during the load of a Document using the newly created LSParser. Note that no lexical checking is done on the absolute URI. In order to create a LSParser for any kind of schema types (i.e. the LSParser will be free to use any schema found), use the value null.

Note: For W3C XML Schema [XML Schema Part 1] , applications must use the value "http://www.w3.org/2001/XMLSchema". For XML DTD [XML 1.0], applications must use the value "http://www.w3.org/TR/REC-xml". Other Schema languages are outside the scope of the W3C and therefore should recommend an absolute URI in order to use this method.

Returns:
The newly created LSParser object. This LSParser is either synchronous or asynchronous depending on the value of the mode argument.

Note: By default, the newly created LSParser does not contain a DOMErrorHandler, i.e. the value of the " error-handler" configuration parameter is null. However, implementations may provide a default error handler at creation time. In that case, the initial value of the "error-handler" configuration parameter on the new LSParser object contains a reference to the default error handler.

Throws:
DOMException - NOT_SUPPORTED_ERR: Raised if the requested mode or schema type is not supported.

createLSSerializer

LSSerializer createLSSerializer()
Create a new LSSerializer object.

Returns:
The newly created LSSerializer object.

Note: By default, the newly created LSSerializer has no DOMErrorHandler, i.e. the value of the "error-handler" configuration parameter is null. However, implementations may provide a default error handler at creation time. In that case, the initial value of the "error-handler" configuration parameter on the new LSSerializer object contains a reference to the default error handler.

createLSInput

LSInput createLSInput()
Create a new empty input source object where LSInput.characterStream, LSInput.byteStream , LSInput.stringData LSInput.systemId, LSInput.publicId, LSInput.baseURI, and LSInput.encoding are null, and LSInput.certifiedText is false.

Returns:
The newly created input object.

createLSOutput

LSOutput createLSOutput()
Create a new empty output destination object where LSOutput.characterStream, LSOutput.byteStream, LSOutput.systemId, LSOutput.encoding are null.

Returns:
The newly created output object.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


LSException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.ls
Class LSException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  org.w3c.dom.ls.LSException
All Implemented Interfaces:
Serializable
public class LSException
extends RuntimeException

Parser or write operations may throw an LSException if the processing is stopped. The processing can be stopped due to a DOMError with a severity of DOMError.SEVERITY_FATAL_ERROR or a non recovered DOMError.SEVERITY_ERROR, or if DOMErrorHandler.handleError() returned false.

Note: As suggested in the definition of the constants in the DOMError interface, a DOM implementation may choose to continue after a fatal error, but the resulting DOM tree is then implementation dependent.

See also the Document Object Model (DOM) Level 3 Load and Save Specification.

See Also:
Serialized Form

Field Summary
short | code
static short | PARSE_ERR If an attempt was made to load a document, or an XML Fragment, using LSParser and the processing has been stopped.
static short | SERIALIZE_ERR If an attempt was made to serialize a Node using LSSerializer and the processing has been stopped.
Constructor Summary
LSException(short code, String message)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

code

public short code

PARSE_ERR

public static final short PARSE_ERR
If an attempt was made to load a document, or an XML Fragment, using LSParser and the processing has been stopped.

See Also:
Constant Field Values

SERIALIZE_ERR

public static final short SERIALIZE_ERR
If an attempt was made to serialize a Node using LSSerializer and the processing has been stopped.

See Also:
Constant Field Values
Constructor Detail

LSException

public LSException(short code,
                   String message)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LSInput

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.ls
Interface LSInput

public interface LSInput

This interface represents an input source for data.

This interface allows an application to encapsulate information about an input source in a single object, which may include a public identifier, a system identifier, a byte stream (possibly with a specified encoding), a base URI, and/or a character stream.

The exact definitions of a byte stream and a character stream are binding dependent.

The application is expected to provide objects that implement this interface whenever such objects are needed. The application can either provide its own objects that implement this interface, or it can use the generic factory method DOMImplementationLS.createLSInput() to create objects that implement this interface.

The LSParser will use the LSInput object to determine how to read data. The LSParser will look at the different inputs specified in the LSInput in the following order to know which one to read from, the first one that is not null and not an empty string will be used:

  1. LSInput.characterStream
  2. LSInput.byteStream
  3. LSInput.stringData
  4. LSInput.systemId
  5. LSInput.publicId

If all inputs are null, the LSParser will report a DOMError with its DOMError.type set to "no-input-specified" and its DOMError.severity set to DOMError.SEVERITY_FATAL_ERROR.

LSInput objects belong to the application. The DOM implementation will never modify them (though it may make copies and modify the copies, if necessary).

See also the Document Object Model (DOM) Level 3 Load and Save Specification.

Method Summary
String | getBaseURI() The base URI to be used (see section 5.1.4 in [IETF RFC 2396]) for resolving a relative systemId to an absolute URI.
InputStream | getByteStream() An attribute of a language and binding dependent type that represents a stream of bytes.
boolean | getCertifiedText() If set to true, assume that the input is certified (see section 2.13 in [XML 1.1]) when parsing [XML 1.1].
Reader | getCharacterStream() An attribute of a language and binding dependent type that represents a stream of 16-bit units.
String | getEncoding() The character encoding, if known.
String | getPublicId() The public identifier for this input source.
String | getStringData() String data to parse.
String | getSystemId() The system identifier, a URI reference [IETF RFC 2396], for this input source.
void | setBaseURI(String baseURI) The base URI to be used (see section 5.1.4 in [IETF RFC 2396]) for resolving a relative systemId to an absolute URI.
void | setByteStream(InputStream byteStream) An attribute of a language and binding dependent type that represents a stream of bytes.
void | setCertifiedText(boolean certifiedText) If set to true, assume that the input is certified (see section 2.13 in [XML 1.1]) when parsing [XML 1.1].
void | setCharacterStream(Reader characterStream) An attribute of a language and binding dependent type that represents a stream of 16-bit units.
void | setEncoding(String encoding) The character encoding, if known.
void | setPublicId(String publicId) The public identifier for this input source.
void | setStringData(String stringData) String data to parse.
void | setSystemId(String systemId) The system identifier, a URI reference [IETF RFC 2396], for this input source.

Method Detail

getCharacterStream

Reader getCharacterStream()
An attribute of a language and binding dependent type that represents a stream of 16-bit units. The application must encode the stream using UTF-16 (defined in [Unicode] and in [ISO/IEC 10646]). It is not a requirement to have an XML declaration when using character streams. If an XML declaration is present, the value of the encoding attribute will be ignored.

setCharacterStream

void setCharacterStream(Reader characterStream)
An attribute of a language and binding dependent type that represents a stream of 16-bit units. The application must encode the stream using UTF-16 (defined in [Unicode] and in [ISO/IEC 10646]). It is not a requirement to have an XML declaration when using character streams. If an XML declaration is present, the value of the encoding attribute will be ignored.

getByteStream

InputStream getByteStream()
An attribute of a language and binding dependent type that represents a stream of bytes.
If the application knows the character encoding of the byte stream, it should set the encoding attribute. Setting the encoding in this way will override any encoding specified in an XML declaration in the data.

setByteStream

void setByteStream(InputStream byteStream)
An attribute of a language and binding dependent type that represents a stream of bytes.
If the application knows the character encoding of the byte stream, it should set the encoding attribute. Setting the encoding in this way will override any encoding specified in an XML declaration in the data.

getStringData

String getStringData()
String data to parse. If provided, this will always be treated as a sequence of 16-bit units (UTF-16 encoded characters). It is not a requirement to have an XML declaration when using stringData. If an XML declaration is present, the value of the encoding attribute will be ignored.

setStringData

void setStringData(String stringData)
String data to parse. If provided, this will always be treated as a sequence of 16-bit units (UTF-16 encoded characters). It is not a requirement to have an XML declaration when using stringData. If an XML declaration is present, the value of the encoding attribute will be ignored.

getSystemId

String getSystemId()
The system identifier, a URI reference [IETF RFC 2396], for this input source. The system identifier is optional if there is a byte stream, a character stream, or string data. It is still useful to provide one, since the application will use it to resolve any relative URIs and can include it in error messages and warnings. (The LSParser will only attempt to fetch the resource identified by the URI reference if there is no other input available in the input source.)
If the application knows the character encoding of the object pointed to by the system identifier, it can set the encoding using the encoding attribute.
If the specified system ID is a relative URI reference (see section 5 in [IETF RFC 2396]), the DOM implementation will attempt to resolve the relative URI with the baseURI as the base, if that fails, the behavior is implementation dependent.

setSystemId

void setSystemId(String systemId)
The system identifier, a URI reference [IETF RFC 2396], for this input source. The system identifier is optional if there is a byte stream, a character stream, or string data. It is still useful to provide one, since the application will use it to resolve any relative URIs and can include it in error messages and warnings. (The LSParser will only attempt to fetch the resource identified by the URI reference if there is no other input available in the input source.)
If the application knows the character encoding of the object pointed to by the system identifier, it can set the encoding using the encoding attribute.
If the specified system ID is a relative URI reference (see section 5 in [IETF RFC 2396]), the DOM implementation will attempt to resolve the relative URI with the baseURI as the base, if that fails, the behavior is implementation dependent.

getPublicId

String getPublicId()
The public identifier for this input source. This may be mapped to an input source using an implementation dependent mechanism (such as catalogues or other mappings). The public identifier, if specified, may also be reported as part of the location information when errors are reported.

setPublicId

void setPublicId(String publicId)
The public identifier for this input source. This may be mapped to an input source using an implementation dependent mechanism (such as catalogues or other mappings). The public identifier, if specified, may also be reported as part of the location information when errors are reported.

getBaseURI

String getBaseURI()
The base URI to be used (see section 5.1.4 in [IETF RFC 2396]) for resolving a relative systemId to an absolute URI.
If, when used, the base URI is itself a relative URI, an empty string, or null, the behavior is implementation dependent.

setBaseURI

void setBaseURI(String baseURI)
The base URI to be used (see section 5.1.4 in [IETF RFC 2396]) for resolving a relative systemId to an absolute URI.
If, when used, the base URI is itself a relative URI, an empty string, or null, the behavior is implementation dependent.

getEncoding

String getEncoding()
The character encoding, if known. The encoding must be a string acceptable for an XML encoding declaration ([XML 1.0] section 4.3.3 "Character Encoding in Entities").
This attribute has no effect when the application provides a character stream or string data. For other sources of input, an encoding specified by means of this attribute will override any encoding specified in the XML declaration or the Text declaration, or an encoding obtained from a higher level protocol, such as HTTP [IETF RFC 2616].

setEncoding

void setEncoding(String encoding)
The character encoding, if known. The encoding must be a string acceptable for an XML encoding declaration ([XML 1.0] section 4.3.3 "Character Encoding in Entities").
This attribute has no effect when the application provides a character stream or string data. For other sources of input, an encoding specified by means of this attribute will override any encoding specified in the XML declaration or the Text declaration, or an encoding obtained from a higher level protocol, such as HTTP [IETF RFC 2616].

getCertifiedText

boolean getCertifiedText()
If set to true, assume that the input is certified (see section 2.13 in [XML 1.1]) when parsing [XML 1.1].

setCertifiedText

void setCertifiedText(boolean certifiedText)
If set to true, assume that the input is certified (see section 2.13 in [XML 1.1]) when parsing [XML 1.1].

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LSLoadEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.ls
Interface LSLoadEvent

All Superinterfaces:
Event
public interface LSLoadEvent
extends Event

This interface represents a load event object that signals the completion of a document load.

See also the Document Object Model (DOM) Level 3 Load and Save Specification.

Field Summary
Fields inherited from interface org.w3c.dom.events.Event
AT_TARGET, BUBBLING_PHASE, CAPTURING_PHASE
Method Summary
LSInput | getInput() The input source that was parsed.
Document | getNewDocument() The document that finished loading.
Methods inherited from interface org.w3c.dom.events.Event
getBubbles, getCancelable, getCurrentTarget, getEventPhase, getTarget, getTimeStamp, getType, initEvent, preventDefault, stopPropagation

Method Detail

getNewDocument

Document getNewDocument()
The document that finished loading.

getInput

LSInput getInput()
The input source that was parsed.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LSOutput

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.ls
Interface LSOutput

public interface LSOutput

This interface represents an output destination for data.

This interface allows an application to encapsulate information about an output destination in a single object, which may include a URI, a byte stream (possibly with a specified encoding), a base URI, and/or a character stream.

The exact definitions of a byte stream and a character stream are binding dependent.

The application is expected to provide objects that implement this interface whenever such objects are needed. The application can either provide its own objects that implement this interface, or it can use the generic factory method DOMImplementationLS.createLSOutput() to create objects that implement this interface.

The LSSerializer will use the LSOutput object to determine where to serialize the output to. The LSSerializer will look at the different outputs specified in the LSOutput in the following order to know which one to output to, the first one that is not null and not an empty string will be used:

  1. LSOutput.characterStream
  2. LSOutput.byteStream
  3. LSOutput.systemId

LSOutput objects belong to the application. The DOM implementation will never modify them (though it may make copies and modify the copies, if necessary).

See also the Document Object Model (DOM) Level 3 Load and Save Specification.

Method Summary
OutputStream | getByteStream() An attribute of a language and binding dependent type that represents a writable stream of bytes.
Writer | getCharacterStream() An attribute of a language and binding dependent type that represents a writable stream to which 16-bit units can be output.
String | getEncoding() The character encoding to use for the output.
String | getSystemId() The system identifier, a URI reference [IETF RFC 2396], for this output destination.
void | setByteStream(OutputStream byteStream) An attribute of a language and binding dependent type that represents a writable stream of bytes.
void | setCharacterStream(Writer characterStream) An attribute of a language and binding dependent type that represents a writable stream to which 16-bit units can be output.
void | setEncoding(String encoding) The character encoding to use for the output.
void | setSystemId(String systemId) The system identifier, a URI reference [IETF RFC 2396], for this output destination.

Method Detail

getCharacterStream

Writer getCharacterStream()
An attribute of a language and binding dependent type that represents a writable stream to which 16-bit units can be output.

setCharacterStream

void setCharacterStream(Writer characterStream)
An attribute of a language and binding dependent type that represents a writable stream to which 16-bit units can be output.

getByteStream

OutputStream getByteStream()
An attribute of a language and binding dependent type that represents a writable stream of bytes.

setByteStream

void setByteStream(OutputStream byteStream)
An attribute of a language and binding dependent type that represents a writable stream of bytes.

getSystemId

String getSystemId()
The system identifier, a URI reference [IETF RFC 2396], for this output destination.
If the system ID is a relative URI reference (see section 5 in [IETF RFC 2396]), the behavior is implementation dependent.

setSystemId

void setSystemId(String systemId)
The system identifier, a URI reference [IETF RFC 2396], for this output destination.
If the system ID is a relative URI reference (see section 5 in [IETF RFC 2396]), the behavior is implementation dependent.

getEncoding

String getEncoding()
The character encoding to use for the output. The encoding must be a string acceptable for an XML encoding declaration ([XML 1.0] section 4.3.3 "Character Encoding in Entities"), it is recommended that character encodings registered (as charsets) with the Internet Assigned Numbers Authority [IANA-CHARSETS] should be referred to using their registered names.

setEncoding

void setEncoding(String encoding)
The character encoding to use for the output. The encoding must be a string acceptable for an XML encoding declaration ([XML 1.0] section 4.3.3 "Character Encoding in Entities"), it is recommended that character encodings registered (as charsets) with the Internet Assigned Numbers Authority [IANA-CHARSETS] should be referred to using their registered names.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LSParser

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.ls
Interface LSParser

public interface LSParser

An interface to an object that is able to build, or augment, a DOM tree from various input sources.

LSParser provides an API for parsing XML and building the corresponding DOM document structure. A LSParser instance can be obtained by invoking the DOMImplementationLS.createLSParser() method.

As specified in [DOM Level 3 Core] , when a document is first made available via the LSParser:

  • there will never be two adjacent nodes of type NODE_TEXT, and there will never be empty text nodes.
  • it is expected that the value and nodeValue attributes of an Attr node initially return the XML 1.0 normalized value. However, if the parameters " validate-if-schema" and " datatype-normalization" are set to true, depending on the attribute normalization used, the attribute values may differ from the ones obtained by the XML 1.0 attribute normalization. If the parameters " datatype-normalization" is set to false, the XML 1.0 attribute normalization is guaranteed to occur, and if the attributes list does not contain namespace declarations, the attributes attribute on Element node represents the property [attributes] defined in [XML Information Set] .

Asynchronous LSParser objects are expected to also implement the events::EventTarget interface so that event listeners can be registered on asynchronous LSParser objects.

Events supported by asynchronous LSParser objects are:

load
The LSParser finishes to load the document. See also the definition of the LSLoadEvent interface.
progress
The LSParser signals progress as data is parsed. This specification does not attempt to define exactly when progress events should be dispatched. That is intentionally left as implementation-dependent. Here is one example of how an application might dispatch progress events: Once the parser starts receiving data, a progress event is dispatched to indicate that the parsing starts. From there on, a progress event is dispatched for every 4096 bytes of data that is received and processed. This is only one example, though, and implementations can choose to dispatch progress events at any time while parsing, or not dispatch them at all. See also the definition of the LSProgressEvent interface.

Note: All events defined in this specification use the namespace URI "http://www.w3.org/2002/DOMLS".

While parsing an input source, errors are reported to the application through the error handler (LSParser.domConfig's " error-handler" parameter). This specification does in no way try to define all possible errors that can occur while parsing XML, or any other markup, but some common error cases are defined. The types (DOMError.type) of errors and warnings defined by this specification are:

"check-character-normalization-failure" [error]
Raised if the parameter " check-character-normalization" is set to true and a string is encountered that fails normalization checking.
"doctype-not-allowed" [fatal]
Raised if the configuration parameter "disallow-doctype" is set to true and a doctype is encountered.
"no-input-specified" [fatal]
Raised when loading a document and no input is specified in the LSInput object.
"pi-base-uri-not-preserved" [warning]
Raised if a processing instruction is encountered in a location where the base URI of the processing instruction can not be preserved. One example of a case where this warning will be raised is if the configuration parameter " entities" is set to false and the following XML file is parsed:
 <!DOCTYPE root [ <!ENTITY e SYSTEM 'subdir/myentity.ent' ]>
 <root> &e; </root>
And subdir/myentity.ent contains:
<one> <two/> </one> <?pi 3.14159?>
 <more/>
"unbound-prefix-in-entity" [warning]
An implementation dependent warning that may be raised if the configuration parameter " namespaces" is set to true and an unbound namespace prefix is encountered in an entity's replacement text. Raising this warning is not enforced since some existing parsers may not recognize unbound namespace prefixes in the replacement text of entities.
"unknown-character-denormalization" [fatal]
Raised if the configuration parameter "ignore-unknown-character-denormalizations" is set to false and a character is encountered for which the processor cannot determine the normalization properties.
"unsupported-encoding" [fatal]
Raised if an unsupported encoding is encountered.
"unsupported-media-type" [fatal]
Raised if the configuration parameter "supported-media-types-only" is set to true and an unsupported media type is encountered.

In addition to raising the defined errors and warnings, implementations are expected to raise implementation specific errors and warnings for any other error and warning cases such as IO errors (file not found, permission denied,...), XML well-formedness errors, and so on.

See also the Document Object Model (DOM) Level 3 Load and Save Specification.

Field Summary
static short | ACTION_APPEND_AS_CHILDREN Append the result of the parse operation as children of the context node.
static short | ACTION_INSERT_AFTER Insert the result of the parse operation as the immediately following sibling of the context node.
static short | ACTION_INSERT_BEFORE Insert the result of the parse operation as the immediately preceding sibling of the context node.
static short | ACTION_REPLACE Replace the context node with the result of the parse operation.
static short | ACTION_REPLACE_CHILDREN Replace all the children of the context node with the result of the parse operation.
Method Summary
void | abort() Abort the loading of the document that is currently being loaded by the LSParser.
boolean | getAsync() true if the LSParser is asynchronous, false if it is synchronous.
boolean | getBusy() true if the LSParser is currently busy loading a document, otherwise false.
DOMConfiguration | getDomConfig() The DOMConfiguration object used when parsing an input source.
LSParserFilter | getFilter() When a filter is provided, the implementation will call out to the filter as it is constructing the DOM tree structure.
Document | parse(LSInput input) Parse an XML document from a resource identified by a LSInput.
Document | parseURI(String uri) Parse an XML document from a location identified by a URI reference [IETF RFC 2396].
Node | parseWithContext(LSInput input, Node contextArg, short action) Parse an XML fragment from a resource identified by a LSInput and insert the content into an existing document at the position specified with the context and action arguments.
void | setFilter(LSParserFilter filter) When a filter is provided, the implementation will call out to the filter as it is constructing the DOM tree structure.

Field Detail

ACTION_APPEND_AS_CHILDREN

static final short ACTION_APPEND_AS_CHILDREN
Append the result of the parse operation as children of the context node. For this action to work, the context node must be an Element or a DocumentFragment.

See Also:
Constant Field Values

ACTION_REPLACE_CHILDREN

static final short ACTION_REPLACE_CHILDREN
Replace all the children of the context node with the result of the parse operation. For this action to work, the context node must be an Element, a Document, or a DocumentFragment.

See Also:
Constant Field Values

ACTION_INSERT_BEFORE

static final short ACTION_INSERT_BEFORE
Insert the result of the parse operation as the immediately preceding sibling of the context node. For this action to work the context node's parent must be an Element or a DocumentFragment.

See Also:
Constant Field Values

ACTION_INSERT_AFTER

static final short ACTION_INSERT_AFTER
Insert the result of the parse operation as the immediately following sibling of the context node. For this action to work the context node's parent must be an Element or a DocumentFragment.

See Also:
Constant Field Values

ACTION_REPLACE

static final short ACTION_REPLACE
Replace the context node with the result of the parse operation. For this action to work, the context node must have a parent, and the parent must be an Element or a DocumentFragment.

See Also:
Constant Field Values
Method Detail

getDomConfig

DOMConfiguration getDomConfig()
The DOMConfiguration object used when parsing an input source. This DOMConfiguration is specific to the parse operation. No parameter values from this DOMConfiguration object are passed automatically to the DOMConfiguration object on the Document that is created, or used, by the parse operation. The DOM application is responsible for passing any needed parameter values from this DOMConfiguration object to the DOMConfiguration object referenced by the Document object.
In addition to the parameters recognized in on the DOMConfiguration interface defined in [DOM Level 3 Core] , the DOMConfiguration objects for LSParser add or modify the following parameters:
"charset-overrides-xml-encoding"
true
[optional] (default) If a higher level protocol such as HTTP [IETF RFC 2616] provides an indication of the character encoding of the input stream being processed, that will override any encoding specified in the XML declaration or the Text declaration (see also section 4.3.3, "Character Encoding in Entities", in [XML 1.0]). Explicitly setting an encoding in the LSInput overrides any encoding from the protocol.
false
[required] The parser ignores any character set encoding information from higher-level protocols.
"disallow-doctype"
true
[optional] Throw a fatal "doctype-not-allowed" error if a doctype node is found while parsing the document. This is useful when dealing with things like SOAP envelopes where doctype nodes are not allowed.
false
[required] (default) Allow doctype nodes in the document.
"ignore-unknown-character-denormalizations"
true
[required] (default) If, while verifying full normalization when [XML 1.1] is supported, a processor encounters characters for which it cannot determine the normalization properties, then the processor will ignore any possible denormalizations caused by these characters. This parameter is ignored for [XML 1.0].
false
[optional] Report an fatal "unknown-character-denormalization" error if a character is encountered for which the processor cannot determine the normalization properties.
"infoset"
See the definition of DOMConfiguration for a description of this parameter. Unlike in [DOM Level 3 Core] , this parameter will default to true for LSParser.
"namespaces"
true
[required] (default) Perform the namespace processing as defined in [XML Namespaces] and [XML Namespaces 1.1] .
false
[optional] Do not perform the namespace processing.
"resource-resolver"
[required] A reference to a LSResourceResolver object, or null. If the value of this parameter is not null when an external resource (such as an external XML entity or an XML schema location) is encountered, the implementation will request that the LSResourceResolver referenced in this parameter resolves the resource.
"supported-media-types-only"
true
[optional] Check that the media type of the parsed resource is a supported media type. If an unsupported media type is encountered, a fatal error of type "unsupported-media-type" will be raised. The media types defined in [IETF RFC 3023] must always be accepted.
false
[required] (default) Accept any media type.
"validate"
See the definition of DOMConfiguration for a description of this parameter. Unlike in [DOM Level 3 Core] , the processing of the internal subset is always accomplished, even if this parameter is set to false.
"validate-if-schema"
See the definition of DOMConfiguration for a description of this parameter. Unlike in [DOM Level 3 Core] , the processing of the internal subset is always accomplished, even if this parameter is set to false.
"well-formed"
See the definition of DOMConfiguration for a description of this parameter. Unlike in [DOM Level 3 Core] , this parameter cannot be set to false.

getFilter

LSParserFilter getFilter()
When a filter is provided, the implementation will call out to the filter as it is constructing the DOM tree structure. The filter can choose to remove elements from the document being constructed, or to terminate the parsing early.
The filter is invoked after the operations requested by the DOMConfiguration parameters have been applied. For example, if " validate" is set to true, the validation is done before invoking the filter.

setFilter

void setFilter(LSParserFilter filter)
When a filter is provided, the implementation will call out to the filter as it is constructing the DOM tree structure. The filter can choose to remove elements from the document being constructed, or to terminate the parsing early.
The filter is invoked after the operations requested by the DOMConfiguration parameters have been applied. For example, if " validate" is set to true, the validation is done before invoking the filter.

getAsync

boolean getAsync()
true if the LSParser is asynchronous, false if it is synchronous.

getBusy

boolean getBusy()
true if the LSParser is currently busy loading a document, otherwise false.

parse

Document parse(LSInput input)
               throws DOMException,
                      LSException
Parse an XML document from a resource identified by a LSInput.

Parameters:
input - The LSInput from which the source of the document is to be read.
Returns:
If the LSParser is a synchronous LSParser, the newly created and populated Document is returned. If the LSParser is asynchronous, null is returned since the document object may not yet be constructed when this method returns.
Throws:
DOMException - INVALID_STATE_ERR: Raised if the LSParser's LSParser.busy attribute is true.
LSException - PARSE_ERR: Raised if the LSParser was unable to load the XML document. DOM applications should attach a DOMErrorHandler using the parameter " error-handler" if they wish to get details on the error.

parseURI

Document parseURI(String uri)
                  throws DOMException,
                         LSException
Parse an XML document from a location identified by a URI reference [IETF RFC 2396]. If the URI contains a fragment identifier (see section 4.1 in [IETF RFC 2396]), the behavior is not defined by this specification, future versions of this specification may define the behavior.

Parameters:
uri - The location of the XML document to be read.
Returns:
If the LSParser is a synchronous LSParser, the newly created and populated Document is returned, or null if an error occured. If the LSParser is asynchronous, null is returned since the document object may not yet be constructed when this method returns.
Throws:
DOMException - INVALID_STATE_ERR: Raised if the LSParser.busy attribute is true.
LSException - PARSE_ERR: Raised if the LSParser was unable to load the XML document. DOM applications should attach a DOMErrorHandler using the parameter " error-handler" if they wish to get details on the error.

parseWithContext

Node parseWithContext(LSInput input,
                      Node contextArg,
                      short action)
                      throws DOMException,
                             LSException
Parse an XML fragment from a resource identified by a LSInput and insert the content into an existing document at the position specified with the context and action arguments. When parsing the input stream, the context node (or its parent, depending on where the result will be inserted) is used for resolving unbound namespace prefixes. The context node's ownerDocument node (or the node itself if the node of type DOCUMENT_NODE) is used to resolve default attributes and entity references.
As the new data is inserted into the document, at least one mutation event is fired per new immediate child or sibling of the context node.
If the context node is a Document node and the action is ACTION_REPLACE_CHILDREN, then the document that is passed as the context node will be changed such that its xmlEncoding, documentURI, xmlVersion, inputEncoding, xmlStandalone, and all other such attributes are set to what they would be set to if the input source was parsed using LSParser.parse().
This method is always synchronous, even if the LSParser is asynchronous (LSParser.async is true).
If an error occurs while parsing, the caller is notified through the ErrorHandler instance associated with the " error-handler" parameter of the DOMConfiguration.
When calling parseWithContext, the values of the following configuration parameters will be ignored and their default values will always be used instead: " validate", " validate-if-schema", and " element-content-whitespace". Other parameters will be treated normally, and the parser is expected to call the LSParserFilter just as if a whole document was parsed.

Parameters:
input - The LSInput from which the source document is to be read. The source document must be an XML fragment, i.e. anything except a complete XML document (except in the case where the context node of type DOCUMENT_NODE, and the action is ACTION_REPLACE_CHILDREN), a DOCTYPE (internal subset), entity declaration(s), notation declaration(s), or XML or text declaration(s).
contextArg - The node that is used as the context for the data that is being parsed. This node must be a Document node, a DocumentFragment node, or a node of a type that is allowed as a child of an Element node, e.g. it cannot be an Attribute node.
action - This parameter describes which action should be taken between the new set of nodes being inserted and the existing children of the context node. The set of possible actions is defined in ACTION_TYPES above.
Returns:
Return the node that is the result of the parse operation. If the result is more than one top-level node, the first one is returned.
Throws:
DOMException - HIERARCHY_REQUEST_ERR: Raised if the content cannot replace, be inserted before, after, or as a child of the context node (see also Node.insertBefore or Node.replaceChild in [DOM Level 3 Core] ).
NOT_SUPPORTED_ERR: Raised if the LSParser doesn't support this method, or if the context node is of type Document and the DOM implementation doesn't support the replacement of the DocumentType child or Element child.
NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is a read only node and the content is being appended to its child list, or if the parent node of the context node is read only node and the content is being inserted in its child list.
INVALID_STATE_ERR: Raised if the LSParser.busy attribute is true.
LSException - PARSE_ERR: Raised if the LSParser was unable to load the XML fragment. DOM applications should attach a DOMErrorHandler using the parameter " error-handler" if they wish to get details on the error.

abort

void abort()
Abort the loading of the document that is currently being loaded by the LSParser. If the LSParser is currently not busy, a call to this method does nothing.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LSParserFilter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.ls
Interface LSParserFilter

public interface LSParserFilter

LSParserFilters provide applications the ability to examine nodes as they are being constructed while parsing. As each node is examined, it may be modified or removed, or the entire parse may be terminated early.

At the time any of the filter methods are called by the parser, the owner Document and DOMImplementation objects exist and are accessible. The document element is never passed to the LSParserFilter methods, i.e. it is not possible to filter out the document element. Document, DocumentType, Notation, Entity, and Attr nodes are never passed to the acceptNode method on the filter. The child nodes of an EntityReference node are passed to the filter if the parameter " entities" is set to false. Note that, as described by the parameter " entities", unexpanded entity reference nodes are never discarded and are always passed to the filter.

All validity checking while parsing a document occurs on the source document as it appears on the input stream, not on the DOM document as it is built in memory. With filters, the document in memory may be a subset of the document on the stream, and its validity may have been affected by the filtering.

All default attributes must be present on elements when the elements are passed to the filter methods. All other default content must be passed to the filter methods.

DOM applications must not raise exceptions in a filter. The effect of throwing exceptions from a filter is DOM implementation dependent.

See also the Document Object Model (DOM) Level 3 Load and Save Specification.

Field Summary
static short | FILTER_ACCEPT Accept the node.
static short | FILTER_INTERRUPT Interrupt the normal processing of the document.
static short | FILTER_REJECT Reject the node and its children.
static short | FILTER_SKIP Skip this single node.
Method Summary
short | acceptNode(Node nodeArg) This method will be called by the parser at the completion of the parsing of each node.
int | getWhatToShow() Tells the LSParser what types of nodes to show to the method LSParserFilter.acceptNode.
short | startElement(Element elementArg) The parser will call this method after each Element start tag has been scanned, but before the remainder of the Element is processed.

Field Detail

FILTER_ACCEPT

static final short FILTER_ACCEPT
Accept the node.

See Also:
Constant Field Values

FILTER_REJECT

static final short FILTER_REJECT
Reject the node and its children.

See Also:
Constant Field Values

FILTER_SKIP

static final short FILTER_SKIP
Skip this single node. The children of this node will still be considered.

See Also:
Constant Field Values

FILTER_INTERRUPT

static final short FILTER_INTERRUPT
Interrupt the normal processing of the document.

See Also:
Constant Field Values
Method Detail

startElement

short startElement(Element elementArg)
The parser will call this method after each Element start tag has been scanned, but before the remainder of the Element is processed. The intent is to allow the element, including any children, to be efficiently skipped. Note that only element nodes are passed to the startElement function.
The element node passed to startElement for filtering will include all of the Element's attributes, but none of the children nodes. The Element may not yet be in place in the document being constructed (it may not have a parent node.)
A startElement filter function may access or change the attributes for the Element. Changing Namespace declarations will have no effect on namespace resolution by the parser.
For efficiency, the Element node passed to the filter may not be the same one as is actually placed in the tree if the node is accepted. And the actual node (node object identity) may be reused during the process of reading in and filtering a document.

Parameters:
elementArg - The newly encountered element. At the time this method is called, the element is incomplete - it will have its attributes, but no children.
Returns:
  • FILTER_ACCEPT if the Element should be included in the DOM document being built.
  • FILTER_REJECT if the Element and all of its children should be rejected.
  • FILTER_SKIP if the Element should be skipped. All of its children are inserted in place of the skipped Element node.
  • FILTER_INTERRUPT if the filter wants to stop the processing of the document. Interrupting the processing of the document does no longer guarantee that the resulting DOM tree is XML well-formed. The Element is rejected.
Returning any other values will result in unspecified behavior.

acceptNode

short acceptNode(Node nodeArg)
This method will be called by the parser at the completion of the parsing of each node. The node and all of its descendants will exist and be complete. The parent node will also exist, although it may be incomplete, i.e. it may have additional children that have not yet been parsed. Attribute nodes are never passed to this function.
From within this method, the new node may be freely modified - children may be added or removed, text nodes modified, etc. The state of the rest of the document outside this node is not defined, and the affect of any attempt to navigate to, or to modify any other part of the document is undefined.
For validating parsers, the checks are made on the original document, before any modification by the filter. No validity checks are made on any document modifications made by the filter.
If this new node is rejected, the parser might reuse the new node and any of its descendants.

Parameters:
nodeArg - The newly constructed element. At the time this method is called, the element is complete - it has all of its children (and their children, recursively) and attributes, and is attached as a child to its parent.
Returns:
  • FILTER_ACCEPT if this Node should be included in the DOM document being built.
  • FILTER_REJECT if the Node and all of its children should be rejected.
  • FILTER_SKIP if the Node should be skipped and the Node should be replaced by all the children of the Node.
  • FILTER_INTERRUPT if the filter wants to stop the processing of the document. Interrupting the processing of the document does no longer guarantee that the resulting DOM tree is XML well-formed. The Node is accepted and will be the last completely parsed node.

getWhatToShow

int getWhatToShow()
Tells the LSParser what types of nodes to show to the method LSParserFilter.acceptNode. If a node is not shown to the filter using this attribute, it is automatically included in the DOM document being built. See NodeFilter for definition of the constants. The constants SHOW_ATTRIBUTE , SHOW_DOCUMENT, SHOW_DOCUMENT_TYPE, SHOW_NOTATION, SHOW_ENTITY, and SHOW_DOCUMENT_FRAGMENT are meaningless here. Those nodes will never be passed to LSParserFilter.acceptNode.
The constants used here are defined in [DOM Level 2 Traversal and Range] .

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LSProgressEvent

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.ls
Interface LSProgressEvent

All Superinterfaces:
Event
public interface LSProgressEvent
extends Event

This interface represents a progress event object that notifies the application about progress as a document is parsed. It extends the Event interface defined in [DOM Level 3 Events] .

The units used for the attributes position and totalSize are not specified and can be implementation and input dependent.

See also the Document Object Model (DOM) Level 3 Load and Save Specification.

Field Summary
Fields inherited from interface org.w3c.dom.events.Event
AT_TARGET, BUBBLING_PHASE, CAPTURING_PHASE
Method Summary
LSInput | getInput() The input source that is being parsed.
int | getPosition() The current position in the input source, including all external entities and other resources that have been read.
int | getTotalSize() The total size of the document including all external resources, this number might change as a document is being parsed if references to more external resources are seen.
Methods inherited from interface org.w3c.dom.events.Event
getBubbles, getCancelable, getCurrentTarget, getEventPhase, getTarget, getTimeStamp, getType, initEvent, preventDefault, stopPropagation

Method Detail

getInput

LSInput getInput()
The input source that is being parsed.

getPosition

int getPosition()
The current position in the input source, including all external entities and other resources that have been read.

getTotalSize

int getTotalSize()
The total size of the document including all external resources, this number might change as a document is being parsed if references to more external resources are seen. A value of 0 is returned if the total size cannot be determined or estimated.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LSResourceResolver

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.ls
Interface LSResourceResolver

public interface LSResourceResolver

LSResourceResolver provides a way for applications to redirect references to external resources.

Applications needing to implement custom handling for external resources can implement this interface and register their implementation by setting the "resource-resolver" parameter of DOMConfiguration objects attached to LSParser and LSSerializer. It can also be register on DOMConfiguration objects attached to Document if the "LS" feature is supported.

The LSParser will then allow the application to intercept any external entities, including the external DTD subset and external parameter entities, before including them. The top-level document entity is never passed to the resolveResource method.

Many DOM applications will not need to implement this interface, but it will be especially useful for applications that build XML documents from databases or other specialized input sources, or for applications that use URNs.

Note: LSResourceResolver is based on the SAX2 [SAX] EntityResolver interface.

See also the Document Object Model (DOM) Level 3 Load and Save Specification.

Method Summary
 LSInput resolveResource(String type, String namespaceURI, String publicId, String systemId, String baseURI)
Allow the application to resolve external resources.

Method Detail

resolveResource

LSInput resolveResource(String type,
                        String namespaceURI,
                        String publicId,
                        String systemId,
                        String baseURI)
Allow the application to resolve external resources.
The LSParser will call this method before opening any external resource, including the external DTD subset, external entities referenced within the DTD, and external entities referenced within the document element (however, the top-level document entity is not passed to this method). The application may then request that the LSParser resolve the external resource itself, that it use an alternative URI, or that it use an entirely different input source.
Application writers can use this method to redirect external system identifiers to secure and/or local URI, to look up public identifiers in a catalogue, or to read an entity from a database or other input source (including, for example, a dialog box).

Parameters:
type - The type of the resource being resolved. For XML [XML 1.0] resources (i.e. entities), applications must use the value "http://www.w3.org/TR/REC-xml". For XML Schema [XML Schema Part 1] , applications must use the value "http://www.w3.org/2001/XMLSchema". Other types of resources are outside the scope of this specification and therefore should recommend an absolute URI in order to use this method.
namespaceURI - The namespace of the resource being resolved, e.g. the target namespace of the XML Schema [XML Schema Part 1] when resolving XML Schema resources.
publicId - The public identifier of the external entity being referenced, or null if no public identifier was supplied or if the resource is not an entity.
systemId - The system identifier, a URI reference [IETF RFC 2396], of the external resource being referenced, or null if no system identifier was supplied.
baseURI - The absolute base URI of the resource being parsed, or null if there is no base URI.
Returns:
A LSInput object describing the new input source, or null to request that the parser open a regular URI connection to the resource.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LSSerializer

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.ls
Interface LSSerializer

public interface LSSerializer

A LSSerializer provides an API for serializing (writing) a DOM document out into XML. The XML data is written to a string or an output stream. Any changes or fixups made during the serialization affect only the serialized data. The Document object and its children are never altered by the serialization operation.

During serialization of XML data, namespace fixup is done as defined in [DOM Level 3 Core] , Appendix B. [DOM Level 2 Core] allows empty strings as a real namespace URI. If the namespaceURI of a Node is empty string, the serialization will treat them as null, ignoring the prefix if any.

LSSerializer accepts any node type for serialization. For nodes of type Document or Entity, well-formed XML will be created when possible (well-formedness is guaranteed if the document or entity comes from a parse operation and is unchanged since it was created). The serialized output for these node types is either as a XML document or an External XML Entity, respectively, and is acceptable input for an XML parser. For all other types of nodes the serialized form is implementation dependent.

Within a Document, DocumentFragment, or Entity being serialized, Nodes are processed as follows

  • Document nodes are written, including the XML declaration (unless the parameter "xml-declaration" is set to false) and a DTD subset, if one exists in the DOM. Writing a Document node serializes the entire document.
  • Entity nodes, when written directly by LSSerializer.write, outputs the entity expansion but no namespace fixup is done. The resulting output will be valid as an external entity.
  • If the parameter " entities" is set to true, EntityReference nodes are serialized as an entity reference of the form " &entityName;" in the output. Child nodes (the expansion) of the entity reference are ignored. If the parameter " entities" is set to false, only the children of the entity reference are serialized. EntityReference nodes with no children (no corresponding Entity node or the corresponding Entity nodes have no children) are always serialized.
  • CDATAsections containing content characters that cannot be represented in the specified output encoding are handled according to the " split-cdata-sections" parameter. If the parameter is set to true, CDATAsections are split, and the unrepresentable characters are serialized as numeric character references in ordinary content. The exact position and number of splits is not specified. If the parameter is set to false, unrepresentable characters in a CDATAsection are reported as "wf-invalid-character" errors if the parameter " well-formed" is set to true. The error is not recoverable - there is no mechanism for supplying alternative characters and continuing with the serialization.
  • DocumentFragment nodes are serialized by serializing the children of the document fragment in the order they appear in the document fragment.
  • All other node types (Element, Text, etc.) are serialized to their corresponding XML source form.

Note: The serialization of a Node does not always generate a well-formed XML document, i.e. a LSParser might throw fatal errors when parsing the resulting serialization.

Within the character data of a document (outside of markup), any characters that cannot be represented directly are replaced with character references. Occurrences of '<' and '&' are replaced by the predefined entities &lt; and &amp;. The other predefined entities (&gt;, &apos;, and &quot;) might not be used, except where needed (e.g. using &gt; in cases such as ']]>'). Any characters that cannot be represented directly in the output character encoding are serialized as numeric character references (and since character encoding standards commonly use hexadecimal representations of characters, using the hexadecimal representation when serializing character references is encouraged).

To allow attribute values to contain both single and double quotes, the apostrophe or single-quote character (') may be represented as "&apos;", and the double-quote character (") as "&quot;". New line characters and other characters that cannot be represented directly in attribute values in the output character encoding are serialized as a numeric character reference.

Within markup, but outside of attributes, any occurrence of a character that cannot be represented in the output character encoding is reported as a DOMError fatal error. An example would be serializing the element <LaCañada/> with encoding="us-ascii". This will result with a generation of a DOMError "wf-invalid-character-in-node-name" (as proposed in " well-formed").

When requested by setting the parameter " normalize-characters" on LSSerializer to true, character normalization is performed according to the definition of fully normalized characters included in appendix E of [XML 1.1] on all data to be serialized, both markup and character data. The character normalization process affects only the data as it is being written; it does not alter the DOM's view of the document after serialization has completed.

Implementations are required to support the encodings "UTF-8", "UTF-16", "UTF-16BE", and "UTF-16LE" to guarantee that data is serializable in all encodings that are required to be supported by all XML parsers. When the encoding is UTF-8, whether or not a byte order mark is serialized, or if the output is big-endian or little-endian, is implementation dependent. When the encoding is UTF-16, whether or not the output is big-endian or little-endian is implementation dependent, but a Byte Order Mark must be generated for non-character outputs, such as LSOutput.byteStream or LSOutput.systemId. If the Byte Order Mark is not generated, a "byte-order-mark-needed" warning is reported. When the encoding is UTF-16LE or UTF-16BE, the output is big-endian (UTF-16BE) or little-endian (UTF-16LE) and the Byte Order Mark is not be generated. In all cases, the encoding declaration, if generated, will correspond to the encoding used during the serialization (e.g. encoding="UTF-16" will appear if UTF-16 was requested).

Namespaces are fixed up during serialization, the serialization process will verify that namespace declarations, namespace prefixes and the namespace URI associated with elements and attributes are consistent. If inconsistencies are found, the serialized form of the document will be altered to remove them. The method used for doing the namespace fixup while serializing a document is the algorithm defined in Appendix B.1, "Namespace normalization", of [DOM Level 3 Core] .

While serializing a document, the parameter "discard-default-content" controls whether or not non-specified data is serialized.

While serializing, errors and warnings are reported to the application through the error handler (LSSerializer.domConfig's " error-handler" parameter). This specification does in no way try to define all possible errors and warnings that can occur while serializing a DOM node, but some common error and warning cases are defined. The types ( DOMError.type) of errors and warnings defined by this specification are:

"no-output-specified" [fatal]
Raised when writing to a LSOutput if no output is specified in the LSOutput.
"unbound-prefix-in-entity-reference" [fatal]
Raised if the configuration parameter " namespaces" is set to true and an entity whose replacement text contains unbound namespace prefixes is referenced in a location where there are no bindings for the namespace prefixes.
"unsupported-encoding" [fatal]
Raised if an unsupported encoding is encountered.

In addition to raising the defined errors and warnings, implementations are expected to raise implementation specific errors and warnings for any other error and warning cases such as IO errors (file not found, permission denied,...) and so on.

See also the Document Object Model (DOM) Level 3 Load and Save Specification.

Method Summary
DOMConfiguration | getDomConfig() The DOMConfiguration object used by the LSSerializer when serializing a DOM node.
LSSerializerFilter | getFilter() When the application provides a filter, the serializer will call out to the filter before serializing each Node.
String | getNewLine() The end-of-line sequence of characters to be used in the XML being written out.
void | setFilter(LSSerializerFilter filter) When the application provides a filter, the serializer will call out to the filter before serializing each Node.
void | setNewLine(String newLine) The end-of-line sequence of characters to be used in the XML being written out.
boolean | write(Node nodeArg, LSOutput destination) Serialize the specified node as described above in the general description of the LSSerializer interface.
String | writeToString(Node nodeArg) Serialize the specified node as described above in the general description of the LSSerializer interface.
boolean | writeToURI(Node nodeArg, String uri) A convenience method that acts as if LSSerializer.write was called with a LSOutput with no encoding specified and LSOutput.systemId set to the uri argument.

Method Detail

getDomConfig

DOMConfiguration getDomConfig()
The DOMConfiguration object used by the LSSerializer when serializing a DOM node.
In addition to the parameters recognized by the DOMConfiguration interface defined in [DOM Level 3 Core] , the DOMConfiguration objects for LSSerializer adds, or modifies, the following parameters:
"canonical-form"
true
[optional] Writes the document according to the rules specified in [Canonical XML]. In addition to the behavior described in " canonical-form" [DOM Level 3 Core] , setting this parameter to true will set the parameters "format-pretty-print", "discard-default-content", and "xml-declaration ", to false. Setting one of those parameters to true will set this parameter to false. Serializing an XML 1.1 document when "canonical-form" is true will generate a fatal error.
false
[required] (default) Do not canonicalize the output.
"discard-default-content"
true
[required] (default) Use the Attr.specified attribute to decide what attributes should be discarded. Note that some implementations might use whatever information available to the implementation (i.e. XML schema, DTD, the Attr.specified attribute, and so on) to determine what attributes and content to discard if this parameter is set to true.
false
[required]Keep all attributes and all content.
"format-pretty-print"
true
[optional] Formatting the output by adding whitespace to produce a pretty-printed, indented, human-readable form. The exact form of the transformations is not specified by this specification. Pretty-printing changes the content of the document and may affect the validity of the document, validating implementations should preserve validity.
false
[required] (default) Don't pretty-print the result.
"ignore-unknown-character-denormalizations"
true
[required] (default) If, while verifying full normalization when [XML 1.1] is supported, a character is encountered for which the normalization properties cannot be determined, then raise a "unknown-character-denormalization" warning (instead of raising an error, if this parameter is not set) and ignore any possible denormalizations caused by these characters.
false
[optional] Report a fatal error if a character is encountered for which the processor cannot determine the normalization properties.
"normalize-characters"
This parameter is equivalent to the one defined by DOMConfiguration in [DOM Level 3 Core] . Unlike in the Core, the default value for this parameter is true. While DOM implementations are not required to support fully normalizing the characters in the document according to appendix E of [XML 1.1], this parameter must be activated by default if supported.
"xml-declaration"
true
[required] (default) If a Document, Element, or Entity node is serialized, the XML declaration, or text declaration, should be included. The version (Document.xmlVersion if the document is a Level 3 document and the version is non-null, otherwise use the value "1.0"), and the output encoding (see LSSerializer.write for details on how to find the output encoding) are specified in the serialized XML declaration.
false
[required] Do not serialize the XML and text declarations. Report a "xml-declaration-needed" warning if this will cause problems (i.e. the serialized data is of an XML version other than [XML 1.0], or an encoding would be needed to be able to re-parse the serialized data).

getNewLine

String getNewLine()
The end-of-line sequence of characters to be used in the XML being written out. Any string is supported, but XML treats only a certain set of characters sequence as end-of-line (See section 2.11, "End-of-Line Handling" in [XML 1.0], if the serialized content is XML 1.0 or section 2.11, "End-of-Line Handling" in [XML 1.1], if the serialized content is XML 1.1). Using other character sequences than the recommended ones can result in a document that is either not serializable or not well-formed).
On retrieval, the default value of this attribute is the implementation specific default end-of-line sequence. DOM implementations should choose the default to match the usual convention for text files in the environment being used. Implementations must choose a default sequence that matches one of those allowed by XML 1.0 or XML 1.1, depending on the serialized content. Setting this attribute to null will reset its value to the default value.

setNewLine

void setNewLine(String newLine)
The end-of-line sequence of characters to be used in the XML being written out. Any string is supported, but XML treats only a certain set of characters sequence as end-of-line (See section 2.11, "End-of-Line Handling" in [XML 1.0], if the serialized content is XML 1.0 or section 2.11, "End-of-Line Handling" in [XML 1.1], if the serialized content is XML 1.1). Using other character sequences than the recommended ones can result in a document that is either not serializable or not well-formed).
On retrieval, the default value of this attribute is the implementation specific default end-of-line sequence. DOM implementations should choose the default to match the usual convention for text files in the environment being used. Implementations must choose a default sequence that matches one of those allowed by XML 1.0 or XML 1.1, depending on the serialized content. Setting this attribute to null will reset its value to the default value.

getFilter

LSSerializerFilter getFilter()
When the application provides a filter, the serializer will call out to the filter before serializing each Node. The filter implementation can choose to remove the node from the stream or to terminate the serialization early.
The filter is invoked after the operations requested by the DOMConfiguration parameters have been applied. For example, CDATA sections won't be passed to the filter if " cdata-sections" is set to false.

setFilter

void setFilter(LSSerializerFilter filter)
When the application provides a filter, the serializer will call out to the filter before serializing each Node. The filter implementation can choose to remove the node from the stream or to terminate the serialization early.
The filter is invoked after the operations requested by the DOMConfiguration parameters have been applied. For example, CDATA sections won't be passed to the filter if " cdata-sections" is set to false.

write

boolean write(Node nodeArg,
              LSOutput destination)
              throws LSException
Serialize the specified node as described above in the general description of the LSSerializer interface. The output is written to the supplied LSOutput.
When writing to a LSOutput, the encoding is found by looking at the encoding information that is reachable through the LSOutput and the item to be written (or its owner document) in this order:
  1. LSOutput.encoding,
  2. Document.inputEncoding,
  3. Document.xmlEncoding.

If no encoding is reachable through the above properties, a default encoding of "UTF-8" will be used. If the specified encoding is not supported an "unsupported-encoding" fatal error is raised.
If no output is specified in the LSOutput, a "no-output-specified" fatal error is raised.
The implementation is responsible of associating the appropriate media type with the serialized data.
When writing to a HTTP URI, a HTTP PUT is performed. When writing to other types of URIs, the mechanism for writing the data to the URI is implementation dependent.

Parameters:
nodeArg - The node to serialize.
destination - The destination for the serialized DOM.
Returns:
Returns true if node was successfully serialized. Return false in case the normal processing stopped but the implementation kept serializing the document; the result of the serialization being implementation dependent then.
Throws:
LSException - SERIALIZE_ERR: Raised if the LSSerializer was unable to serialize the node. DOM applications should attach a DOMErrorHandler using the parameter " error-handler" if they wish to get details on the error.

writeToURI

boolean writeToURI(Node nodeArg,
                   String uri)
                   throws LSException
A convenience method that acts as if LSSerializer.write was called with a LSOutput with no encoding specified and LSOutput.systemId set to the uri argument.

Parameters:
nodeArg - The node to serialize.
uri - The URI to write to.
Returns:
Returns true if node was successfully serialized. Return false in case the normal processing stopped but the implementation kept serializing the document; the result of the serialization being implementation dependent then.
Throws:
LSException - SERIALIZE_ERR: Raised if the LSSerializer was unable to serialize the node. DOM applications should attach a DOMErrorHandler using the parameter " error-handler" if they wish to get details on the error.

writeToString

String writeToString(Node nodeArg)
                     throws DOMException,
                            LSException
Serialize the specified node as described above in the general description of the LSSerializer interface. The output is written to a DOMString that is returned to the caller. The encoding used is the encoding of the DOMString type, i.e. UTF-16. Note that no Byte Order Mark is generated in a DOMString object.

Parameters:
nodeArg - The node to serialize.
Returns:
Returns the serialized data.
Throws:
DOMException - DOMSTRING_SIZE_ERR: Raised if the resulting string is too long to fit in a DOMString.
LSException - SERIALIZE_ERR: Raised if the LSSerializer was unable to serialize the node. DOM applications should attach a DOMErrorHandler using the parameter " error-handler" if they wish to get details on the error.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LSSerializerFilter

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom.ls
Interface LSSerializerFilter

All Superinterfaces:
org.w3c.dom.traversal.NodeFilter
public interface LSSerializerFilter
extends org.w3c.dom.traversal.NodeFilter

LSSerializerFilters provide applications the ability to examine nodes as they are being serialized and decide what nodes should be serialized or not. The LSSerializerFilter interface is based on the NodeFilter interface defined in [DOM Level 2 Traversal and Range] .

Document, DocumentType, DocumentFragment, Notation, Entity , and children of Attr nodes are not passed to the filter. The child nodes of an EntityReference node are only passed to the filter if the EntityReference node is skipped by the method LSParserFilter.acceptNode().

When serializing an Element, the element is passed to the filter before any of its attributes are passed to the filter. Namespace declaration attributes, and default attributes (except in the case when " discard-default-content" is set to false), are never passed to the filter.

The result of any attempt to modify a node passed to a LSSerializerFilter is implementation dependent.

DOM applications must not raise exceptions in a filter. The effect of throwing exceptions from a filter is DOM implementation dependent.

For efficiency, a node passed to the filter may not be the same as the one that is actually in the tree. And the actual node (node object identity) may be reused during the process of filtering and serializing a document.

See also the Document Object Model (DOM) Level 3 Load and Save Specification.

Field Summary
Fields inherited from interface org.w3c.dom.traversal.NodeFilter
FILTER_ACCEPT, FILTER_REJECT, FILTER_SKIP, SHOW_ALL, SHOW_ATTRIBUTE, SHOW_CDATA_SECTION, SHOW_COMMENT, SHOW_DOCUMENT, SHOW_DOCUMENT_FRAGMENT, SHOW_DOCUMENT_TYPE, SHOW_ELEMENT, SHOW_ENTITY, SHOW_ENTITY_REFERENCE, SHOW_NOTATION, SHOW_PROCESSING_INSTRUCTION, SHOW_TEXT
Method Summary
 int getWhatToShow()
Tells the LSSerializer what types of nodes to show to the filter.
Methods inherited from interface org.w3c.dom.traversal.NodeFilter
acceptNode

Method Detail

getWhatToShow

int getWhatToShow()
Tells the LSSerializer what types of nodes to show to the filter. If a node is not shown to the filter using this attribute, it is automatically serialized. See NodeFilter for definition of the constants. The constants SHOW_DOCUMENT , SHOW_DOCUMENT_TYPE, SHOW_DOCUMENT_FRAGMENT , SHOW_NOTATION, and SHOW_ENTITY are meaningless here, such nodes will never be passed to a LSSerializerFilter.
Unlike [DOM Level 2 Traversal and Range] , the SHOW_ATTRIBUTE constant indicates that the Attr nodes are shown and passed to the filter.
The constants used here are defined in [DOM Level 2 Traversal and Range] .

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


NamedNodeMap

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface NamedNodeMap

public interface NamedNodeMap

Objects implementing the NamedNodeMap interface are used to represent collections of nodes that can be accessed by name. Note that NamedNodeMap does not inherit from NodeList; NamedNodeMaps are not maintained in any particular order. Objects contained in an object implementing NamedNodeMap may also be accessed by an ordinal index, but this is simply to allow convenient enumeration of the contents of a NamedNodeMap, and does not imply that the DOM specifies an order to these Nodes.

NamedNodeMap objects in the DOM are live.

See also the Document Object Model (DOM) Level 3 Core Specification.

Method Summary
int | getLength() The number of nodes in this map.
Node | getNamedItem(String name) Retrieves a node specified by name.
Node | getNamedItemNS(String namespaceURI, String localName) Retrieves a node specified by local name and namespace URI.
Node | item(int index) Returns the indexth item in the map.
Node | removeNamedItem(String name) Removes a node specified by name.
Node | removeNamedItemNS(String namespaceURI, String localName) Removes a node specified by local name and namespace URI.
Node | setNamedItem(Node arg) Adds a node using its nodeName attribute.
Node | setNamedItemNS(Node arg) Adds a node using its namespaceURI and localName.

Method Detail

getNamedItem

Node getNamedItem(String name)
Retrieves a node specified by name.

Parameters:
name - The nodeName of a node to retrieve.
Returns:
A Node (of any type) with the specified nodeName, or null if it does not identify any node in this map.

setNamedItem

Node setNamedItem(Node arg)
                  throws DOMException
Adds a node using its nodeName attribute. If a node with that name is already present in this map, it is replaced by the new one. Replacing a node by itself has no effect.
As the nodeName attribute is used to derive the name which the node must be stored under, multiple nodes of certain types (those that have a "special" string value) cannot be stored as the names would clash. This is seen as preferable to allowing nodes to be aliased.

Parameters:
arg - A node to store in this map. The node will later be accessible using the value of its nodeName attribute.
Returns:
If the new Node replaces an existing node the replaced Node is returned, otherwise null is returned.
Throws:
DOMException - WRONG_DOCUMENT_ERR: Raised if arg was created from a different document than the one that created this map.
NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.
INUSE_ATTRIBUTE_ERR: Raised if arg is an Attr that is already an attribute of another Element object. The DOM user must explicitly clone Attr nodes to re-use them in other elements.
HIERARCHY_REQUEST_ERR: Raised if an attempt is made to add a node doesn't belong in this NamedNodeMap. Examples would include trying to insert something other than an Attr node into an Element's map of attributes, or a non-Entity node into the DocumentType's map of Entities.

removeNamedItem

Node removeNamedItem(String name)
                     throws DOMException
Removes a node specified by name. When this map contains the attributes attached to an element, if the removed attribute is known to have a default value, an attribute immediately appears containing the default value as well as the corresponding namespace URI, local name, and prefix when applicable.

Parameters:
name - The nodeName of the node to remove.
Returns:
The node removed from this map if a node with such a name exists.
Throws:
DOMException - NOT_FOUND_ERR: Raised if there is no node named name in this map.
NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.

item

Node item(int index)
Returns the indexth item in the map. If index is greater than or equal to the number of nodes in this map, this returns null.

Parameters:
index - Index into this map.
Returns:
The node at the indexth position in the map, or null if that is not a valid index.

getLength

int getLength()
The number of nodes in this map. The range of valid child node indices is 0 to length-1 inclusive.

getNamedItemNS

Node getNamedItemNS(String namespaceURI,
                    String localName)
                    throws DOMException
Retrieves a node specified by local name and namespace URI.
Per [XML Namespaces] , applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.

Parameters:
namespaceURI - The namespace URI of the node to retrieve.
localName - The local name of the node to retrieve.
Returns:
A Node (of any type) with the specified local name and namespace URI, or null if they do not identify any node in this map.
Throws:
DOMException - NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).
Since:
DOM Level 2

setNamedItemNS

Node setNamedItemNS(Node arg)
                    throws DOMException
Adds a node using its namespaceURI and localName. If a node with that namespace URI and that local name is already present in this map, it is replaced by the new one. Replacing a node by itself has no effect.
Per [XML Namespaces] , applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.

Parameters:
arg - A node to store in this map. The node will later be accessible using the value of its namespaceURI and localName attributes.
Returns:
If the new Node replaces an existing node the replaced Node is returned, otherwise null is returned.
Throws:
DOMException - WRONG_DOCUMENT_ERR: Raised if arg was created from a different document than the one that created this map.
NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.
INUSE_ATTRIBUTE_ERR: Raised if arg is an Attr that is already an attribute of another Element object. The DOM user must explicitly clone Attr nodes to re-use them in other elements.
HIERARCHY_REQUEST_ERR: Raised if an attempt is made to add a node doesn't belong in this NamedNodeMap. Examples would include trying to insert something other than an Attr node into an Element's map of attributes, or a non-Entity node into the DocumentType's map of Entities.
NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).
Since:
DOM Level 2

removeNamedItemNS

Node removeNamedItemNS(String namespaceURI,
                       String localName)
                       throws DOMException
Removes a node specified by local name and namespace URI. A removed attribute may be known to have a default value when this map contains the attributes attached to an element, as returned by the attributes attribute of the Node interface. If so, an attribute immediately appears containing the default value as well as the corresponding namespace URI, local name, and prefix when applicable.
Per [XML Namespaces] , applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.

Parameters:
namespaceURI - The namespace URI of the node to remove.
localName - The local name of the node to remove.
Returns:
The node removed from this map if a node with such a local name and namespace URI exists.
Throws:
DOMException - NOT_FOUND_ERR: Raised if there is no node with the specified namespaceURI and localName in this map.
NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.
NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).
Since:
DOM Level 2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NameList

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface NameList

public interface NameList

The NameList interface provides the abstraction of an ordered collection of parallel pairs of name and namespace values (which could be null values), without defining or constraining how this collection is implemented. The items in the NameList are accessible via an integral index, starting from 0.

See also the Document Object Model (DOM) Level 3 Core Specification.

Since:
DOM Level 3

Method Summary
boolean | contains(String str) Test if a name is part of this NameList.
boolean | containsNS(String namespaceURI, String name) Test if the pair namespaceURI/name is part of this NameList.
int | getLength() The number of pairs (name and namespaceURI) in the list.
String | getName(int index) Returns the indexth name item in the collection.
String | getNamespaceURI(int index) Returns the indexth namespaceURI item in the collection.

Method Detail

getName

String getName(int index)
Returns the indexth name item in the collection.

Parameters:
index - Index into the collection.
Returns:
The name at the indexth position in the NameList, or null if there is no name for the specified index or if the index is out of range.

getNamespaceURI

String getNamespaceURI(int index)
Returns the indexth namespaceURI item in the collection.

Parameters:
index - Index into the collection.
Returns:
The namespace URI at the indexth position in the NameList, or null if there is no name for the specified index or if the index is out of range.

getLength

int getLength()
The number of pairs (name and namespaceURI) in the list. The range of valid child node indices is 0 to length-1 inclusive.

contains

boolean contains(String str)
Test if a name is part of this NameList.

Parameters:
str - The name to look for.
Returns:
true if the name has been found, false otherwise.

containsNS

boolean containsNS(String namespaceURI,
                   String name)
Test if the pair namespaceURI/name is part of this NameList.

Parameters:
namespaceURI - The namespace URI to look for.
name - The name to look for.
Returns:
true if the pair namespaceURI/name has been found, false otherwise.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Node

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface Node

All Known Subinterfaces:
Attr, CDATASection, CharacterData, Comment, Detail, DetailEntry, Document, DocumentFragment, DocumentType, Element, Entity, EntityReference, Node, Notation, ProcessingInstruction, SOAPBody, SOAPBodyElement, SOAPElement, SOAPEnvelope, SOAPFault, SOAPFaultElement, SOAPHeader, SOAPHeaderElement, Text, Text
All Known Implementing Classes:
IIOMetadataNode, SOAPPart
public interface Node

The Node interface is the primary datatype for the entire Document Object Model. It represents a single node in the document tree. While all objects implementing the Node interface expose methods for dealing with children, not all objects implementing the Node interface may have children. For example, Text nodes may not have children, and adding children to such nodes results in a DOMException being raised.

The attributes nodeName, nodeValue and attributes are included as a mechanism to get at node information without casting down to the specific derived interface. In cases where there is no obvious mapping of these attributes for a specific nodeType (e.g., nodeValue for an Element or attributes for a Comment ), this returns null. Note that the specialized interfaces may contain additional and more convenient mechanisms to get and set the relevant information.

The values of nodeName, nodeValue, and attributes vary according to the node type as follows:
Interface | nodeName | nodeValue | attributes
Attr | same as Attr.name | same as Attr.value | null
CDATASection | "#cdata-section" | same as CharacterData.data, the content of the CDATA Section | null
Comment | "#comment" | same as CharacterData.data, the content of the comment | null
Document | "#document" | null | null
DocumentFragment | "#document-fragment" | null | null
DocumentType | same as DocumentType.name | null | null
Element | same as Element.tagName | null | NamedNodeMap
Entity | entity name | null | null
EntityReference | name of entity referenced | null | null
Notation | notation name | null | null
ProcessingInstruction | same as ProcessingInstruction.target | same as ProcessingInstruction.data | null
Text | "#text" | same as CharacterData.data, the content of the text node | null

See also the Document Object Model (DOM) Level 3 Core Specification.

Field Summary
static short | ATTRIBUTE_NODE The node is an Attr.
static short | CDATA_SECTION_NODE The node is a CDATASection.
static short | COMMENT_NODE The node is a Comment.
static short | DOCUMENT_FRAGMENT_NODE The node is a DocumentFragment.
static short | DOCUMENT_NODE The node is a Document.
static short | DOCUMENT_POSITION_CONTAINED_BY The node is contained by the reference node.
static short | DOCUMENT_POSITION_CONTAINS The node contains the reference node.
static short | DOCUMENT_POSITION_DISCONNECTED The two nodes are disconnected.
static short | DOCUMENT_POSITION_FOLLOWING The node follows the reference node.
static short | DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC The determination of preceding versus following is implementation-specific.
static short | DOCUMENT_POSITION_PRECEDING The second node precedes the reference node.
static short | DOCUMENT_TYPE_NODE The node is a DocumentType.
static short | ELEMENT_NODE The node is an Element.
static short | ENTITY_NODE The node is an Entity.
static short | ENTITY_REFERENCE_NODE The node is an EntityReference.
static short | NOTATION_NODE The node is a Notation.
static short | PROCESSING_INSTRUCTION_NODE The node is a ProcessingInstruction.
static short | TEXT_NODE The node is a Text node.
Method Summary
Node | appendChild(Node newChild) Adds the node newChild to the end of the list of children of this node.
Node | cloneNode(boolean deep) Returns a duplicate of this node, i.e., serves as a generic copy constructor for nodes.
short | compareDocumentPosition(Node other) Compares the reference node, i.e.
NamedNodeMap | getAttributes() A NamedNodeMap containing the attributes of this node (if it is an Element) or null otherwise.
String | getBaseURI() The absolute base URI of this node or null if the implementation wasn't able to obtain an absolute URI.
NodeList | getChildNodes() A NodeList that contains all children of this node.
Object | getFeature(String feature, String version) This method returns a specialized object which implements the specialized APIs of the specified feature and version, as specified in .
Node | getFirstChild() The first child of this node.
Node | getLastChild() The last child of this node.
String | getLocalName() Returns the local part of the qualified name of this node.
String | getNamespaceURI() The namespace URI of this node, or null if it is unspecified (see ).
Node | getNextSibling() The node immediately following this node.
String | getNodeName() The name of this node, depending on its type; see the table above.
short | getNodeType() A code representing the type of the underlying object, as defined above.
String | getNodeValue() The value of this node, depending on its type; see the table above.
Document | getOwnerDocument() The Document object associated with this node.
Node | getParentNode() The parent of this node.
String | getPrefix() The namespace prefix of this node, or null if it is unspecified.
Node | getPreviousSibling() The node immediately preceding this node.
String | getTextContent() This attribute returns the text content of this node and its descendants.
Object | getUserData(String key) Retrieves the object associated to a key on a this node.
boolean | hasAttributes() Returns whether this node (if it is an element) has any attributes.
boolean | hasChildNodes() Returns whether this node has any children.
Node | insertBefore(Node newChild, Node refChild) Inserts the node newChild before the existing child node refChild.
boolean | isDefaultNamespace(String namespaceURI) This method checks if the specified namespaceURI is the default namespace or not.
boolean | isEqualNode(Node arg) Tests whether two nodes are equal.
boolean | isSameNode(Node other) Returns whether this node is the same node as the given one.
boolean | isSupported(String feature, String version) Tests whether the DOM implementation implements a specific feature and that feature is supported by this node, as specified in .
String | lookupNamespaceURI(String prefix) Look up the namespace URI associated to the given prefix, starting from this node.
String | lookupPrefix(String namespaceURI) Look up the prefix associated to the given namespace URI, starting from this node.
void | normalize() Puts all Text nodes in the full depth of the sub-tree underneath this Node, including attribute nodes, into a "normal" form where only structure (e.g., elements, comments, processing instructions, CDATA sections, and entity references) separates Text nodes, i.e., there are neither adjacent Text nodes nor empty Text nodes.
Node | removeChild(Node oldChild) Removes the child node indicated by oldChild from the list of children, and returns it.
Node | replaceChild(Node newChild, Node oldChild) Replaces the child node oldChild with newChild in the list of children, and returns the oldChild node.
void | setNodeValue(String nodeValue) The value of this node, depending on its type; see the table above.
void | setPrefix(String prefix) The namespace prefix of this node, or null if it is unspecified.
void | setTextContent(String textContent) This attribute returns the text content of this node and its descendants.
Object | setUserData(String key, Object data, UserDataHandler handler) Associate an object to a key on this node.

Field Detail

ELEMENT_NODE

static final short ELEMENT_NODE
The node is an Element.

See Also:
Constant Field Values

ATTRIBUTE_NODE

static final short ATTRIBUTE_NODE
The node is an Attr.

See Also:
Constant Field Values

TEXT_NODE

static final short TEXT_NODE
The node is a Text node.

See Also:
Constant Field Values

CDATA_SECTION_NODE

static final short CDATA_SECTION_NODE
The node is a CDATASection.

See Also:
Constant Field Values

ENTITY_REFERENCE_NODE

static final short ENTITY_REFERENCE_NODE
The node is an EntityReference.

See Also:
Constant Field Values

ENTITY_NODE

static final short ENTITY_NODE
The node is an Entity.

See Also:
Constant Field Values

PROCESSING_INSTRUCTION_NODE

static final short PROCESSING_INSTRUCTION_NODE
The node is a ProcessingInstruction.

See Also:
Constant Field Values

COMMENT_NODE

static final short COMMENT_NODE
The node is a Comment.

See Also:
Constant Field Values

DOCUMENT_NODE

static final short DOCUMENT_NODE
The node is a Document.

See Also:
Constant Field Values

DOCUMENT_TYPE_NODE

static final short DOCUMENT_TYPE_NODE
The node is a DocumentType.

See Also:
Constant Field Values

DOCUMENT_FRAGMENT_NODE

static final short DOCUMENT_FRAGMENT_NODE
The node is a DocumentFragment.

See Also:
Constant Field Values

NOTATION_NODE

static final short NOTATION_NODE
The node is a Notation.

See Also:
Constant Field Values

DOCUMENT_POSITION_DISCONNECTED

static final short DOCUMENT_POSITION_DISCONNECTED
The two nodes are disconnected. Order between disconnected nodes is always implementation-specific.

See Also:
Constant Field Values

DOCUMENT_POSITION_PRECEDING

static final short DOCUMENT_POSITION_PRECEDING
The second node precedes the reference node.

See Also:
Constant Field Values

DOCUMENT_POSITION_FOLLOWING

static final short DOCUMENT_POSITION_FOLLOWING
The node follows the reference node.

See Also:
Constant Field Values

DOCUMENT_POSITION_CONTAINS

static final short DOCUMENT_POSITION_CONTAINS
The node contains the reference node. A node which contains is always preceding, too.

See Also:
Constant Field Values

DOCUMENT_POSITION_CONTAINED_BY

static final short DOCUMENT_POSITION_CONTAINED_BY
The node is contained by the reference node. A node which is contained is always following, too.

See Also:
Constant Field Values

DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC

static final short DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC
The determination of preceding versus following is implementation-specific.

See Also:
Constant Field Values
Method Detail

getNodeName

String getNodeName()
The name of this node, depending on its type; see the table above.

getNodeValue

String getNodeValue()
                    throws DOMException
The value of this node, depending on its type; see the table above. When it is defined to be null, setting it has no effect, including if the node is read-only.

Throws:
DOMException - DOMSTRING_SIZE_ERR: Raised when it would return more characters than fit in a DOMString variable on the implementation platform.

setNodeValue

void setNodeValue(String nodeValue)
                  throws DOMException
The value of this node, depending on its type; see the table above. When it is defined to be null, setting it has no effect, including if the node is read-only.

Throws:
DOMException - NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly and if it is not defined to be null.

getNodeType

short getNodeType()
A code representing the type of the underlying object, as defined above.

getParentNode

Node getParentNode()
The parent of this node. All nodes, except Attr, Document, DocumentFragment, Entity, and Notation may have a parent. However, if a node has just been created and not yet added to the tree, or if it has been removed from the tree, this is null.

getChildNodes

NodeList getChildNodes()
A NodeList that contains all children of this node. If there are no children, this is a NodeList containing no nodes.

getFirstChild

Node getFirstChild()
The first child of this node. If there is no such node, this returns null.

getLastChild

Node getLastChild()
The last child of this node. If there is no such node, this returns null.

getPreviousSibling

Node getPreviousSibling()
The node immediately preceding this node. If there is no such node, this returns null.

getNextSibling

Node getNextSibling()
The node immediately following this node. If there is no such node, this returns null.

getAttributes

NamedNodeMap getAttributes()
A NamedNodeMap containing the attributes of this node (if it is an Element) or null otherwise.

getOwnerDocument

Document getOwnerDocument()
The Document object associated with this node. This is also the Document object used to create new nodes. When this node is a Document or a DocumentType which is not used with any Document yet, this is null.

Since:
DOM Level 2

insertBefore

Node insertBefore(Node newChild,
                  Node refChild)
                  throws DOMException
Inserts the node newChild before the existing child node refChild. If refChild is null, insert newChild at the end of the list of children.
If newChild is a DocumentFragment object, all of its children are inserted, in the same order, before refChild. If the newChild is already in the tree, it is first removed.

Note: Inserting a node before itself is implementation dependent.

Parameters:
newChild - The node to insert.
refChild - The reference node, i.e., the node before which the new node must be inserted.
Returns:
The node being inserted.
Throws:
DOMException - HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to insert is one of this node's ancestors or this node itself, or if this node is of type Document and the DOM application attempts to insert a second DocumentType or Element node.
WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node.
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or if the parent of the node being inserted is readonly.
NOT_FOUND_ERR: Raised if refChild is not a child of this node.
NOT_SUPPORTED_ERR: if this node is of type Document, this exception might be raised if the DOM implementation doesn't support the insertion of a DocumentType or Element node.
Since:
DOM Level 3

replaceChild

Node replaceChild(Node newChild,
                  Node oldChild)
                  throws DOMException
Replaces the child node oldChild with newChild in the list of children, and returns the oldChild node.
If newChild is a DocumentFragment object, oldChild is replaced by all of the DocumentFragment children, which are inserted in the same order. If the newChild is already in the tree, it is first removed.

Note: Replacing a node with itself is implementation dependent.

Parameters:
newChild - The new node to put in the child list.
oldChild - The node being replaced in the list.
Returns:
The node replaced.
Throws:
DOMException - HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to put in is one of this node's ancestors or this node itself, or if this node is of type Document and the result of the replacement operation would add a second DocumentType or Element on the Document node.
WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node.
NO_MODIFICATION_ALLOWED_ERR: Raised if this node or the parent of the new node is readonly.
NOT_FOUND_ERR: Raised if oldChild is not a child of this node.
NOT_SUPPORTED_ERR: if this node is of type Document, this exception might be raised if the DOM implementation doesn't support the replacement of the DocumentType child or Element child.
Since:
DOM Level 3

removeChild

Node removeChild(Node oldChild)
                 throws DOMException
Removes the child node indicated by oldChild from the list of children, and returns it.

Parameters:
oldChild - The node being removed.
Returns:
The node removed.
Throws:
DOMException - NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
NOT_FOUND_ERR: Raised if oldChild is not a child of this node.
NOT_SUPPORTED_ERR: if this node is of type Document, this exception might be raised if the DOM implementation doesn't support the removal of the DocumentType child or the Element child.
Since:
DOM Level 3

appendChild

Node appendChild(Node newChild)
                 throws DOMException
Adds the node newChild to the end of the list of children of this node. If the newChild is already in the tree, it is first removed.

Parameters:
newChild - The node to add.If it is a DocumentFragment object, the entire contents of the document fragment are moved into the child list of this node
Returns:
The node added.
Throws:
DOMException - HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to append is one of this node's ancestors or this node itself, or if this node is of type Document and the DOM application attempts to append a second DocumentType or Element node.
WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node.
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or if the previous parent of the node being inserted is readonly.
NOT_SUPPORTED_ERR: if the newChild node is a child of the Document node, this exception might be raised if the DOM implementation doesn't support the removal of the DocumentType child or Element child.
Since:
DOM Level 3

hasChildNodes

boolean hasChildNodes()
Returns whether this node has any children.

Returns:
Returns true if this node has any children, false otherwise.

cloneNode

Node cloneNode(boolean deep)
Returns a duplicate of this node, i.e., serves as a generic copy constructor for nodes. The duplicate node has no parent ( parentNode is null) and no user data. User data associated to the imported node is not carried over. However, if any UserDataHandlers has been specified along with the associated data these handlers will be called with the appropriate parameters before this method returns.
Cloning an Element copies all attributes and their values, including those generated by the XML processor to represent defaulted attributes, but this method does not copy any children it contains unless it is a deep clone. This includes text contained in an the Element since the text is contained in a child Text node. Cloning an Attr directly, as opposed to be cloned as part of an Element cloning operation, returns a specified attribute (specified is true). Cloning an Attr always clones its children, since they represent its value, no matter whether this is a deep clone or not. Cloning an EntityReference automatically constructs its subtree if a corresponding Entity is available, no matter whether this is a deep clone or not. Cloning any other type of node simply returns a copy of this node.
Note that cloning an immutable subtree results in a mutable copy, but the children of an EntityReference clone are readonly . In addition, clones of unspecified Attr nodes are specified. And, cloning Document, DocumentType, Entity, and Notation nodes is implementation dependent.

Parameters:
deep - If true, recursively clone the subtree under the specified node; if false, clone only the node itself (and its attributes, if it is an Element).
Returns:
The duplicate node.

normalize

void normalize()
Puts all Text nodes in the full depth of the sub-tree underneath this Node, including attribute nodes, into a "normal" form where only structure (e.g., elements, comments, processing instructions, CDATA sections, and entity references) separates Text nodes, i.e., there are neither adjacent Text nodes nor empty Text nodes. This can be used to ensure that the DOM view of a document is the same as if it were saved and re-loaded, and is useful when operations (such as XPointer [XPointer] lookups) that depend on a particular document tree structure are to be used. If the parameter "normalize-characters" of the DOMConfiguration object attached to the Node.ownerDocument is true, this method will also fully normalize the characters of the Text nodes.

Note: In cases where the document contains CDATASections, the normalize operation alone may not be sufficient, since XPointers do not differentiate between Text nodes and CDATASection nodes.

Since:
DOM Level 3

isSupported

boolean isSupported(String feature,
                    String version)
Tests whether the DOM implementation implements a specific feature and that feature is supported by this node, as specified in .

Parameters:
feature - The name of the feature to test.
version - This is the version number of the feature to test.
Returns:
Returns true if the specified feature is supported on this node, false otherwise.
Since:
DOM Level 2

getNamespaceURI

String getNamespaceURI()
The namespace URI of this node, or null if it is unspecified (see ).
This is not a computed value that is the result of a namespace lookup based on an examination of the namespace declarations in scope. It is merely the namespace URI given at creation time.
For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a DOM Level 1 method, such as Document.createElement(), this is always null.

Note: Per the Namespaces in XML Specification [XML Namespaces] an attribute does not inherit its namespace from the element it is attached to. If an attribute is not explicitly given a namespace, it simply has no namespace.

Since:
DOM Level 2

getPrefix

String getPrefix()
The namespace prefix of this node, or null if it is unspecified. When it is defined to be null, setting it has no effect, including if the node is read-only.
Note that setting this attribute, when permitted, changes the nodeName attribute, which holds the qualified name, as well as the tagName and name attributes of the Element and Attr interfaces, when applicable.
Setting the prefix to null makes it unspecified, setting it to an empty string is implementation dependent.
Note also that changing the prefix of an attribute that is known to have a default value, does not make a new attribute with the default value and the original prefix appear, since the namespaceURI and localName do not change.
For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a DOM Level 1 method, such as createElement from the Document interface, this is always null.

Since:
DOM Level 2

setPrefix

void setPrefix(String prefix)
               throws DOMException
The namespace prefix of this node, or null if it is unspecified. When it is defined to be null, setting it has no effect, including if the node is read-only.
Note that setting this attribute, when permitted, changes the nodeName attribute, which holds the qualified name, as well as the tagName and name attributes of the Element and Attr interfaces, when applicable.
Setting the prefix to null makes it unspecified, setting it to an empty string is implementation dependent.
Note also that changing the prefix of an attribute that is known to have a default value, does not make a new attribute with the default value and the original prefix appear, since the namespaceURI and localName do not change.
For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a DOM Level 1 method, such as createElement from the Document interface, this is always null.

Throws:
DOMException - INVALID_CHARACTER_ERR: Raised if the specified prefix contains an illegal character according to the XML version in use specified in the Document.xmlVersion attribute.
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
NAMESPACE_ERR: Raised if the specified prefix is malformed per the Namespaces in XML specification, if the namespaceURI of this node is null, if the specified prefix is "xml" and the namespaceURI of this node is different from " http://www.w3.org/XML/1998/namespace", if this node is an attribute and the specified prefix is "xmlns" and the namespaceURI of this node is different from "http://www.w3.org/2000/xmlns/", or if this node is an attribute and the qualifiedName of this node is "xmlns" [XML Namespaces] .
Since:
DOM Level 2

getLocalName

String getLocalName()
Returns the local part of the qualified name of this node.
For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a DOM Level 1 method, such as Document.createElement(), this is always null.

Since:
DOM Level 2

hasAttributes

boolean hasAttributes()
Returns whether this node (if it is an element) has any attributes.

Returns:
Returns true if this node has any attributes, false otherwise.
Since:
DOM Level 2

getBaseURI

String getBaseURI()
The absolute base URI of this node or null if the implementation wasn't able to obtain an absolute URI. This value is computed as described in . However, when the Document supports the feature "HTML" [DOM Level 2 HTML] , the base URI is computed using first the value of the href attribute of the HTML BASE element if any, and the value of the documentURI attribute from the Document interface otherwise.

Since:
DOM Level 3

compareDocumentPosition

short compareDocumentPosition(Node other)
                              throws DOMException
Compares the reference node, i.e. the node on which this method is being called, with a node, i.e. the one passed as a parameter, with regard to their position in the document and according to the document order.

Parameters:
other - The node to compare against the reference node.
Returns:
Returns how the node is positioned relatively to the reference node.
Throws:
DOMException - NOT_SUPPORTED_ERR: when the compared nodes are from different DOM implementations that do not coordinate to return consistent implementation-specific results.
Since:
DOM Level 3

getTextContent

String getTextContent()
                      throws DOMException
This attribute returns the text content of this node and its descendants. When it is defined to be null, setting it has no effect. On setting, any possible children this node may have are removed and, if it the new string is not empty or null, replaced by a single Text node containing the string this attribute is set to.
On getting, no serialization is performed, the returned string does not contain any markup. No whitespace normalization is performed and the returned string does not contain the white spaces in element content (see the attribute Text.isElementContentWhitespace). Similarly, on setting, no parsing is performed either, the input string is taken as pure textual content.
The string returned is made of the text content of this node depending on its type, as defined below:
Node type | Content
ELEMENT_NODE, ATTRIBUTE_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, DOCUMENT_FRAGMENT_NODE | concatenation of the textContent attribute value of every child node, excluding COMMENT_NODE and PROCESSING_INSTRUCTION_NODE nodes. This is the empty string if the node has no children.
TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE, PROCESSING_INSTRUCTION_NODE | nodeValue
DOCUMENT_NODE, DOCUMENT_TYPE_NODE, NOTATION_NODE | null

Throws:
DOMException - DOMSTRING_SIZE_ERR: Raised when it would return more characters than fit in a DOMString variable on the implementation platform.
Since:
DOM Level 3

setTextContent

void setTextContent(String textContent)
                    throws DOMException
This attribute returns the text content of this node and its descendants. When it is defined to be null, setting it has no effect. On setting, any possible children this node may have are removed and, if it the new string is not empty or null, replaced by a single Text node containing the string this attribute is set to.
On getting, no serialization is performed, the returned string does not contain any markup. No whitespace normalization is performed and the returned string does not contain the white spaces in element content (see the attribute Text.isElementContentWhitespace). Similarly, on setting, no parsing is performed either, the input string is taken as pure textual content.
The string returned is made of the text content of this node depending on its type, as defined below:
Node type | Content
ELEMENT_NODE, ATTRIBUTE_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, DOCUMENT_FRAGMENT_NODE | concatenation of the textContent attribute value of every child node, excluding COMMENT_NODE and PROCESSING_INSTRUCTION_NODE nodes. This is the empty string if the node has no children.
TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE, PROCESSING_INSTRUCTION_NODE | nodeValue
DOCUMENT_NODE, DOCUMENT_TYPE_NODE, NOTATION_NODE | null

Throws:
DOMException - NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
Since:
DOM Level 3

isSameNode

boolean isSameNode(Node other)
Returns whether this node is the same node as the given one.
This method provides a way to determine whether two Node references returned by the implementation reference the same object. When two Node references are references to the same object, even if through a proxy, the references may be used completely interchangeably, such that all attributes have the same values and calling the same DOM method on either reference always has exactly the same effect.

Parameters:
other - The node to test against.
Returns:
Returns true if the nodes are the same, false otherwise.
Since:
DOM Level 3

lookupPrefix

String lookupPrefix(String namespaceURI)
Look up the prefix associated to the given namespace URI, starting from this node. The default namespace declarations are ignored by this method.
See for details on the algorithm used by this method.

Parameters:
namespaceURI - The namespace URI to look for.
Returns:
Returns an associated namespace prefix if found or null if none is found. If more than one prefix are associated to the namespace prefix, the returned namespace prefix is implementation dependent.
Since:
DOM Level 3

isDefaultNamespace

boolean isDefaultNamespace(String namespaceURI)
This method checks if the specified namespaceURI is the default namespace or not.

Parameters:
namespaceURI - The namespace URI to look for.
Returns:
Returns true if the specified namespaceURI is the default namespace, false otherwise.
Since:
DOM Level 3

lookupNamespaceURI

String lookupNamespaceURI(String prefix)
Look up the namespace URI associated to the given prefix, starting from this node.
See for details on the algorithm used by this method.

Parameters:
prefix - The prefix to look for. If this parameter is null, the method will return the default namespace URI if any.
Returns:
Returns the associated namespace URI or null if none is found.
Since:
DOM Level 3

isEqualNode

boolean isEqualNode(Node arg)
Tests whether two nodes are equal.
This method tests for equality of nodes, not sameness (i.e., whether the two nodes are references to the same object) which can be tested with Node.isSameNode(). All nodes that are the same will also be equal, though the reverse may not be true.
Two nodes are equal if and only if the following conditions are satisfied:
  • The two nodes are of the same type.
  • The following string attributes are equal: nodeName, localName, namespaceURI, prefix, nodeValue . This is: they are both null, or they have the same length and are character for character identical.
  • The attributes NamedNodeMaps are equal. This is: they are both null, or they have the same length and for each node that exists in one map there is a node that exists in the other map and is equal, although not necessarily at the same index.
  • The childNodes NodeLists are equal. This is: they are both null, or they have the same length and contain equal nodes at the same index. Note that normalization can affect equality; to avoid this, nodes should be normalized before being compared.

For two DocumentType nodes to be equal, the following conditions must also be satisfied:
  • The following string attributes are equal: publicId, systemId, internalSubset.
  • The entities NamedNodeMaps are equal.
  • The notations NamedNodeMaps are equal.

On the other hand, the following do not affect equality: the ownerDocument, baseURI, and parentNode attributes, the specified attribute for Attr nodes, the schemaTypeInfo attribute for Attr and Element nodes, the Text.isElementContentWhitespace attribute for Text nodes, as well as any user data or event listeners registered on the nodes.

Note: As a general rule, anything not mentioned in the description above is not significant in consideration of equality checking. Note that future versions of this specification may take into account more attributes and implementations conform to this specification are expected to be updated accordingly.

Parameters:
arg - The node to compare equality with.
Returns:
Returns true if the nodes are equal, false otherwise.
Since:
DOM Level 3

getFeature

Object getFeature(String feature,
                  String version)
This method returns a specialized object which implements the specialized APIs of the specified feature and version, as specified in . The specialized object may also be obtained by using binding-specific casting methods but is not necessarily expected to, as discussed in . This method also allow the implementation to provide specialized objects which do not support the Node interface.

Parameters:
feature - The name of the feature requested. Note that any plus sign "+" prepended to the name of the feature will be ignored since it is not significant in the context of this method.
version - This is the version number of the feature to test.
Returns:
Returns an object which implements the specialized APIs of the specified feature and version, if any, or null if there is no object which implements interfaces associated with that feature. If the DOMObject returned by this method implements the Node interface, it must delegate to the primary core Node and not return results inconsistent with the primary core Node such as attributes, childNodes, etc.
Since:
DOM Level 3

setUserData

Object setUserData(String key,
                   Object data,
                   UserDataHandler handler)
Associate an object to a key on this node. The object can later be retrieved from this node by calling getUserData with the same key.

Parameters:
key - The key to associate the object to.
data - The object to associate to the given key, or null to remove any existing association to that key.
handler - The handler to associate to that key, or null.
Returns:
Returns the DOMUserData previously associated to the given key on this node, or null if there was none.
Since:
DOM Level 3

getUserData

Object getUserData(String key)
Retrieves the object associated to a key on a this node. The object must first have been set to this node by calling setUserData with the same key.

Parameters:
key - The key the object is associated to.
Returns:
Returns the DOMUserData associated to the given key on this node, or null if there was none.
Since:
DOM Level 3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NodeList

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface NodeList

All Known Implementing Classes:
IIOMetadataNode
public interface NodeList

The NodeList interface provides the abstraction of an ordered collection of nodes, without defining or constraining how this collection is implemented. NodeList objects in the DOM are live.

The items in the NodeList are accessible via an integral index, starting from 0.

See also the Document Object Model (DOM) Level 3 Core Specification.

Method Summary
int | getLength() The number of nodes in the list.
Node | item(int index) Returns the indexth item in the collection.

Method Detail

item

Node item(int index)
Returns the indexth item in the collection. If index is greater than or equal to the number of nodes in the list, this returns null.

Parameters:
index - Index into the collection.
Returns:
The node at the indexth position in the NodeList, or null if that is not a valid index.

getLength

int getLength()
The number of nodes in the list. The range of valid child node indices is 0 to length-1 inclusive.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Notation

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface Notation

All Superinterfaces:
Node
public interface Notation
extends Node

This interface represents a notation declared in the DTD. A notation either declares, by name, the format of an unparsed entity (see section 4.7 of the XML 1.0 specification [XML 1.0]), or is used for formal declaration of processing instruction targets (see section 2.6 of the XML 1.0 specification [XML 1.0]). The nodeName attribute inherited from Node is set to the declared name of the notation.

The DOM Core does not support editing Notation nodes; they are therefore readonly.

A Notation node does not have any parent.

See also the Document Object Model (DOM) Level 3 Core Specification.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
String | getPublicId() The public identifier of this notation.
String | getSystemId() The system identifier of this notation.
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

getPublicId

String getPublicId()
The public identifier of this notation. If the public identifier was not specified, this is null.

getSystemId

String getSystemId()
The system identifier of this notation. If the system identifier was not specified, this is null. This may be an absolute URI or not.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ProcessingInstruction

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface ProcessingInstruction

All Superinterfaces:
Node
public interface ProcessingInstruction
extends Node

The ProcessingInstruction interface represents a "processing instruction", used in XML as a way to keep processor-specific information in the text of the document.

No lexical check is done on the content of a processing instruction and it is therefore possible to have the character sequence "?>" in the content, which is illegal a processing instruction per section 2.6 of [XML 1.0]. The presence of this character sequence must generate a fatal error during serialization.

See also the Document Object Model (DOM) Level 3 Core Specification.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
String | getData() The content of this processing instruction.
String | getTarget() The target of this processing instruction.
void | setData(String data) The content of this processing instruction.
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

getTarget

String getTarget()
The target of this processing instruction. XML defines this as being the first token following the markup that begins the processing instruction.

getData

String getData()
The content of this processing instruction. This is from the first non white space character after the target to the character immediately preceding the ?>.

setData

void setData(String data)
             throws DOMException
The content of this processing instruction. This is from the first non white space character after the target to the character immediately preceding the ?>.

Throws:
DOMException - NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Text

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface Text

All Superinterfaces:
CharacterData, Node
All Known Subinterfaces:
CDATASection, Text
public interface Text
extends CharacterData

The Text interface inherits from CharacterData and represents the textual content (termed character data in XML) of an Element or Attr. If there is no markup inside an element's content, the text is contained in a single object implementing the Text interface that is the only child of the element. If there is markup, it is parsed into the information items (elements, comments, etc.) and Text nodes that form the list of children of the element.

When a document is first made available via the DOM, there is only one Text node for each block of text. Users may create adjacent Text nodes that represent the contents of a given element without any intervening markup, but should be aware that there is no way to represent the separations between these nodes in XML or HTML, so they will not (in general) persist between DOM editing sessions. The Node.normalize() method merges any such adjacent Text objects into a single node for each block of text.

No lexical check is done on the content of a Text node and, depending on its position in the document, some characters must be escaped during serialization using character references; e.g. the characters "<&" if the textual content is part of an element or of an attribute, the character sequence "]]>" when part of an element, the quotation mark character " or the apostrophe character ' when part of an attribute.

See also the Document Object Model (DOM) Level 3 Core Specification.

Field Summary
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
Method Summary
String | getWholeText() Returns all text of Text nodes logically-adjacent text nodes to this node, concatenated in document order.
boolean | isElementContentWhitespace() Returns whether this text node contains element content whitespace, often abusively called "ignorable whitespace".
Text | replaceWholeText(String content) Replaces the text of the current node and all logically-adjacent text nodes with the specified text.
Text | splitText(int offset) Breaks this node into two nodes at the specified offset, keeping both in the tree as siblings.
Methods inherited from interface org.w3c.dom.CharacterData
appendData, deleteData, getData, getLength, insertData, replaceData, setData, substringData
Methods inherited from interface org.w3c.dom.Node
appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData

Method Detail

splitText

Text splitText(int offset)
               throws DOMException
Breaks this node into two nodes at the specified offset, keeping both in the tree as siblings. After being split, this node will contain all the content up to the offset point. A new node of the same type, which contains all the content at and after the offset point, is returned. If the original node had a parent node, the new node is inserted as the next sibling of the original node. When the offset is equal to the length of this node, the new node has no data.

Parameters:
offset - The 16-bit unit offset at which to split, starting from 0.
Returns:
The new node, of the same type as this node.
Throws:
DOMException - INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data.
NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

isElementContentWhitespace

boolean isElementContentWhitespace()
Returns whether this text node contains element content whitespace, often abusively called "ignorable whitespace". The text node is determined to contain whitespace in element content during the load of the document or if validation occurs while using Document.normalizeDocument().

Since:
DOM Level 3

getWholeText

String getWholeText()
Returns all text of Text nodes logically-adjacent text nodes to this node, concatenated in document order.
For instance, in the example below wholeText on the Text node that contains "bar" returns "barfoo", while on the Text node that contains "foo" it returns "barfoo".
                     +-----+
                     | <p> |
                     +-----+
                       /\
                      /  \
               /-----\    +-------+
               | bar |    | &ent; |
               \-----/    +-------+
                              |
                              |
                           /-----\
                           | foo |
                           \-----/
Figure: barTextNode.wholeText value is "barfoo"

Since:
DOM Level 3

replaceWholeText

Text replaceWholeText(String content)
                      throws DOMException
Replaces the text of the current node and all logically-adjacent text nodes with the specified text. All logically-adjacent text nodes are removed including the current node unless it was the recipient of the replacement text.

This method returns the node which received the replacement text. The returned node is:

  • null, when the replacement text is the empty string;
  • the current node, except when the current node is read-only;
  • a new Text node of the same type ( Text or CDATASection) as the current node inserted at the location of the replacement.

For instance, in the above example calling replaceWholeText on the Text node that contains "bar" with "yo" in argument results in the following:

                     +-----+
                     | <p> |
                     +-----+
                        |
                        |
                     /-----\
                     | yo  |
                     \-----/
Figure: barTextNode.replaceWholeText("yo") modifies the textual content of barTextNode with "yo"

Where the nodes to be removed are read-only descendants of an EntityReference, the EntityReference must be removed instead of the read-only nodes. If any EntityReference to be removed has descendants that are not EntityReference, Text, or CDATASection nodes, the replaceWholeText method must fail before performing any modification of the document, raising a DOMException with the code NO_MODIFICATION_ALLOWED_ERR.

For instance, in the example below calling replaceWholeText on the Text node that contains "bar" fails, because the EntityReference node "ent" contains an Element node which cannot be removed.

Parameters:
content - The content of the replacing Text node.
Returns:
The Text node created with the specified content.
Throws:
DOMException - NO_MODIFICATION_ALLOWED_ERR: Raised if one of the Text nodes being replaced is readonly.
Since:
DOM Level 3
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TypeInfo

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface TypeInfo

public interface TypeInfo

The TypeInfo interface represents a type referenced from Element or Attr nodes, specified in the schemas associated with the document. The type is a pair of a namespace URI and name properties, and depends on the document's schema.

If the document's schema is an XML DTD [XML 1.0], the values are computed as follows:

  • If this type is referenced from an Attr node, typeNamespace is "http://www.w3.org/TR/REC-xml" and typeName represents the [attribute type] property in the [XML Information Set] . If there is no declaration for the attribute, typeNamespace and typeName are null.
  • If this type is referenced from an Element node, typeNamespace and typeName are null.

If the document's schema is an XML Schema [XML Schema Part 1] , the values are computed as follows using the post-schema-validation infoset contributions (also called PSVI contributions):

  • If the [validity] property exists AND is "invalid" or "notKnown": the {target namespace} and {name} properties of the declared type if available, otherwise null.

    Note: At the time of writing, the XML Schema specification does not require exposing the declared type. Thus, DOM implementations might choose not to provide type information if validity is not valid.

  • If the [validity] property exists and is "valid":
    1. If [member type definition] exists:
      1. If {name} is not absent, then expose {name} and {target namespace} properties of the [member type definition] property;
      2. Otherwise, expose the namespace and local name of the corresponding anonymous type name.
    2. If the [type definition] property exists:
      1. If {name} is not absent, then expose {name} and {target namespace} properties of the [type definition] property;
      2. Otherwise, expose the namespace and local name of the corresponding anonymous type name.
    3. If the [member type definition anonymous] exists:
      1. If it is false, then expose [member type definition name] and [member type definition namespace] properties;
      2. Otherwise, expose the namespace and local name of the corresponding anonymous type name.
    4. If the [type definition anonymous] exists:
      1. If it is false, then expose [type definition name] and [type definition namespace] properties;
      2. Otherwise, expose the namespace and local name of the corresponding anonymous type name.

Note: Other schema languages are outside the scope of the W3C and therefore should define how to represent their type systems using TypeInfo.

See also the Document Object Model (DOM) Level 3 Core Specification.

Since:
DOM Level 3

Field Summary
static int | DERIVATION_EXTENSION If the document's schema is an XML Schema [XML Schema Part 1] , this constant represents the derivation by extension.
static int | DERIVATION_LIST If the document's schema is an XML Schema [XML Schema Part 1] , this constant represents the list.
static int | DERIVATION_RESTRICTION If the document's schema is an XML Schema [XML Schema Part 1] , this constant represents the derivation by restriction if complex types are involved, or a restriction if simple types are involved.
static int | DERIVATION_UNION If the document's schema is an XML Schema [XML Schema Part 1] , this constant represents the union if simple types are involved.
Method Summary
String | getTypeName() The name of a type declared for the associated element or attribute, or null if unknown.
String | getTypeNamespace() The namespace of the type declared for the associated element or attribute or null if the element does not have declaration or if no namespace information is available.
boolean | isDerivedFrom(String typeNamespaceArg, String typeNameArg, int derivationMethod) This method returns if there is a derivation between the reference type definition, i.e.

Field Detail

DERIVATION_RESTRICTION

static final int DERIVATION_RESTRICTION
If the document's schema is an XML Schema [XML Schema Part 1] , this constant represents the derivation by restriction if complex types are involved, or a restriction if simple types are involved.
The reference type definition is derived by restriction from the other type definition if the other type definition is the same as the reference type definition, or if the other type definition can be reached recursively following the {base type definition} property from the reference type definition, and all the derivation methods involved are restriction.

See Also:
Constant Field Values

DERIVATION_EXTENSION

static final int DERIVATION_EXTENSION
If the document's schema is an XML Schema [XML Schema Part 1] , this constant represents the derivation by extension.
The reference type definition is derived by extension from the other type definition if the other type definition can be reached recursively following the {base type definition} property from the reference type definition, and at least one of the derivation methods involved is an extension.

See Also:
Constant Field Values

DERIVATION_UNION

static final int DERIVATION_UNION
If the document's schema is an XML Schema [XML Schema Part 1] , this constant represents the union if simple types are involved.
The reference type definition is derived by union from the other type definition if there exists two type definitions T1 and T2 such as the reference type definition is derived from T1 by DERIVATION_RESTRICTION or DERIVATION_EXTENSION, T2 is derived from the other type definition by DERIVATION_RESTRICTION, T1 has {variety} union, and one of the {member type definitions} is T2. Note that T1 could be the same as the reference type definition, and T2 could be the same as the other type definition.

See Also:
Constant Field Values

DERIVATION_LIST

static final int DERIVATION_LIST
If the document's schema is an XML Schema [XML Schema Part 1] , this constant represents the list.
The reference type definition is derived by list from the other type definition if there exists two type definitions T1 and T2 such as the reference type definition is derived from T1 by DERIVATION_RESTRICTION or DERIVATION_EXTENSION, T2 is derived from the other type definition by DERIVATION_RESTRICTION, T1 has {variety} list, and T2 is the {item type definition}. Note that T1 could be the same as the reference type definition, and T2 could be the same as the other type definition.

See Also:
Constant Field Values
Method Detail

getTypeName

String getTypeName()
The name of a type declared for the associated element or attribute, or null if unknown.

getTypeNamespace

String getTypeNamespace()
The namespace of the type declared for the associated element or attribute or null if the element does not have declaration or if no namespace information is available.

isDerivedFrom

boolean isDerivedFrom(String typeNamespaceArg,
                      String typeNameArg,
                      int derivationMethod)
This method returns if there is a derivation between the reference type definition, i.e. the TypeInfo on which the method is being called, and the other type definition, i.e. the one passed as parameters.

Parameters:
typeNamespaceArg - the namespace of the other type definition.
typeNameArg - the name of the other type definition.
derivationMethod - the type of derivation and conditions applied between two types, as described in the list of constants provided in this interface.
Returns:
If the document's schema is a DTD or no schema is associated with the document, this method will always return false . If the document's schema is an XML Schema, the method will true if the reference type definition is derived from the other type definition according to the derivation parameter. If the value of the parameter is 0 (no bit is set to 1 for the derivationMethod parameter), the method will return true if the other type definition can be reached by recursing any combination of {base type definition}, {item type definition}, or {member type definitions} from the reference type definition.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


UserDataHandler

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.w3c.dom
Interface UserDataHandler

public interface UserDataHandler

When associating an object to a key on a node using Node.setUserData() the application can provide a handler that gets called when the node the object is associated to is being cloned, imported, or renamed. This can be used by the application to implement various behaviors regarding the data it associates to the DOM nodes. This interface defines that handler.

See also the Document Object Model (DOM) Level 3 Core Specification.

Since:
DOM Level 3

Field Summary
static short | NODE_ADOPTED The node is adopted, using Document.adoptNode().
static short | NODE_CLONED The node is cloned, using Node.cloneNode().
static short | NODE_DELETED The node is deleted.
static short | NODE_IMPORTED The node is imported, using Document.importNode().
static short | NODE_RENAMED The node is renamed, using Document.renameNode().
Method Summary
 void handle(short operation, String key, Object data, Node src, Node dst)
This method is called whenever the node for which this handler is registered is imported or cloned.

Field Detail

NODE_CLONED

static final short NODE_CLONED
The node is cloned, using Node.cloneNode().

See Also:
Constant Field Values

NODE_IMPORTED

static final short NODE_IMPORTED
The node is imported, using Document.importNode().

See Also:
Constant Field Values

NODE_DELETED

static final short NODE_DELETED
The node is deleted.

Note: This may not be supported or may not be reliable in certain environments, such as Java, where the implementation has no real control over when objects are actually deleted.

See Also:
Constant Field Values

NODE_RENAMED

static final short NODE_RENAMED
The node is renamed, using Document.renameNode().

See Also:
Constant Field Values

NODE_ADOPTED

static final short NODE_ADOPTED
The node is adopted, using Document.adoptNode().

See Also:
Constant Field Values
Method Detail

handle

void handle(short operation,
            String key,
            Object data,
            Node src,
            Node dst)
This method is called whenever the node for which this handler is registered is imported or cloned.
DOM applications must not raise exceptions in a UserDataHandler. The effect of throwing exceptions from the handler is DOM implementation dependent.

Parameters:
operation - Specifies the type of operation that is being performed on the node.
key - Specifies the key for which this handler is being called.
data - Specifies the data for which this handler is being called.
src - Specifies the node being cloned, adopted, imported, or renamed. This is null when the node is being deleted.
dst - Specifies the node newly created if any, or null.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


sax

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.xml.sax

This package provides the core SAX APIs.

See:
Description

Interface Summary
AttributeList | Deprecated. This interface has been replaced by the SAX2 Attributes interface, which includes Namespace support.
Attributes | Interface for a list of XML attributes.
ContentHandler | Receive notification of the logical content of a document.
DocumentHandler | Deprecated. This interface has been replaced by the SAX2 ContentHandler interface, which includes Namespace support.
DTDHandler | Receive notification of basic DTD-related events.
EntityResolver | Basic interface for resolving entities.
ErrorHandler | Basic interface for SAX error handlers.
Locator | Interface for associating a SAX event with a document location.
Parser | Deprecated. This interface has been replaced by the SAX2 XMLReader interface, which includes Namespace support.
XMLFilter | Interface for an XML filter.
XMLReader | Interface for reading an XML document using callbacks.

Class Summary
HandlerBase | Deprecated. This class works with the deprecated DocumentHandler interface.
InputSource | A single input source for an XML entity.

Exception Summary
SAXException | Encapsulate a general SAX error or warning.
SAXNotRecognizedException | Exception class for an unrecognized identifier.
SAXNotSupportedException | Exception class for an unsupported operation.
SAXParseException | Encapsulate an XML parse error or warning.

Package org.xml.sax Description

This package provides the core SAX APIs. Some SAX1 APIs are deprecated to encourage integration of namespace-awareness into designs of new applications and into maintenance of existing infrastructure.

See http://www.saxproject.org for more information about SAX.

SAX2 Standard Feature Flags

One of the essential characteristics of SAX2 is that it added feature flags which can be used to examine and perhaps modify parser modes, in particular modes such as validation. Since features are identified by (absolute) URIs, anyone can define such features. Currently defined standard feature URIs have the prefix http://xml.org/sax/features/ before an identifier such as validation. Turn features on or off using setFeature. Those standard identifiers are:

Feature ID | Access | Default | Description
external-general-entities | read/write | unspecified | Reports whether this parser processes external general entities; always true if validating.
external-parameter-entities | read/write | unspecified | Reports whether this parser processes external parameter entities; always true if validating.
is-standalone | (parsing) read-only, (not parsing) none | not applicable | May be examined only during a parse, after the startDocument() callback has been completed; read-only. The value is true if the document specified standalone="yes" in its XML declaration, and otherwise is false.
lexical-handler/parameter-entities | read/write | unspecified | A value of "true" indicates that the LexicalHandler will report the beginning and end of parameter entities.
namespaces | read/write | true | A value of "true" indicates namespace URIs and unprefixed local names for element and attribute names will be available.
namespace-prefixes | read/write | false | A value of "true" indicates that XML qualified names (with prefixes) and attributes (including xmlns* attributes) will be available.
resolve-dtd-uris read/write true A value of "true" indicates that system IDs in declarations will be absolutized (relative to their base URIs) before reporting. (That is the default behavior for all SAX2 XML parsers.) A value of "false" indicates those IDs will not be absolutized; parsers will provide the base URI from Locator.getSystemId(). This applies to system IDs passed in
  • DTDHandler.notationDecl(),
  • DTDHandler.unparsedEntityDecl(), and
  • DeclHandler.externalEntityDecl().
It does not apply to EntityResolver.resolveEntity(), which is not used to report declarations, or to LexicalHandler.startDTD(), which already provides the non-absolutized URI.
string-interning | read/write | unspecified | Has a value of "true" if all XML names (for elements, prefixes, attributes, entities, notations, and local names), as well as Namespace URIs, will have been interned using java.lang.String.intern. This supports fast testing of equality/inequality against string constants, rather than forcing slower calls to String.equals().
unicode-normalization-checking | read/write | false | Controls whether the parser reports Unicode normalization errors as described in section 2.13 and Appendix B of the XML 1.1 Recommendation. If true, Unicode normalization errors are reported using the ErrorHandler.error() callback. Such errors are not fatal in themselves (though, obviously, other Unicode-related encoding errors may be).
use-attributes2 | read-only | not applicable | Returns "true" if the Attributes objects passed by this parser in ContentHandler.startElement() implement the org.xml.sax.ext.Attributes2 interface. That interface exposes additional DTD-related information, such as whether the attribute was specified in the source text rather than defaulted.
use-locator2 | read-only | not applicable | Returns "true" if the Locator objects passed by this parser in ContentHandler.setDocumentLocator() implement the org.xml.sax.ext.Locator2 interface. That interface exposes additional entity information, such as the character encoding and XML version used.
use-entity-resolver2 | read/write | true | Returns "true" if, when setEntityResolver is given an object implementing the org.xml.sax.ext.EntityResolver2 interface, those new methods will be used. Returns "false" to indicate that those methods will not be used.
validation | read/write | unspecified | Controls whether the parser is reporting all validity errors; if true, all external entities will be read.
xmlns-uris | read/write | false | Controls whether, when the namespace-prefixes feature is set, the parser treats namespace declaration attributes as being in the http://www.w3.org/2000/xmlns/ namespace. By default, SAX2 conforms to the original "Namespaces in XML" Recommendation, which explicitly states that such attributes are not in any namespace. Setting this optional flag to "true" makes the SAX2 events conform to a later backwards-incompatible revision of that recommendation, placing those attributes in a namespace.
xml-1.1 | read-only | not applicable | Returns "true" if the parser supports both XML 1.1 and XML 1.0. Returns "false" if the parser supports only XML 1.0.

Support for the default values of the namespaces and namespace-prefixes properties is required. Support for any other feature flags is entirely optional.

For default values not specified by SAX2, each XMLReader implementation specifies its default, or may choose not to expose the feature flag. Unless otherwise specified here, implementations may support changing current values of these standard feature flags, but not while parsing.

SAX2 Standard Handler and Property IDs

For parser interface characteristics that are described as objects, a separate namespace is defined. The objects in this namespace are again identified by URI, and the standard property URIs have the prefix http://xml.org/sax/properties/ before an identifier such as lexical-handler or dom-node. Manage those properties using setProperty(). Those identifiers are:

Property ID | Description
declaration-handler | Used to see most DTD declarations except those treated as lexical ("document element name is ...") or which are mandatory for all SAX parsers (DTDHandler). The Object must implement org.xml.sax.ext.DeclHandler.
document-xml-version | May be examined only during a parse, after the startDocument() callback has been completed; read-only. This property is a literal string describing the actual XML version of the document, such as "1.0" or "1.1".
dom-node | For "DOM Walker" style parsers, which ignore their parser.parse() parameters, this is used to specify the DOM (sub)tree being walked by the parser. The Object must implement the org.w3c.dom.Node interface.
lexical-handler | Used to see some syntax events that are essential in some applications: comments, CDATA delimiters, selected general entity inclusions, and the start and end of the DTD (and declaration of document element name). The Object must implement org.xml.sax.ext.LexicalHandler.
xml-string | Readable only during a parser callback, this exposes a TBS chunk of characters responsible for the current event.

All of these standard properties are optional; XMLReader implementations need not support them.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.xml.sax Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.xml.sax

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.xml.sax.HandlerBase (implements org.xml.sax.DocumentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler)
    • org.xml.sax.InputSource
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • org.xml.sax.SAXException
          • org.xml.sax.SAXNotRecognizedException
          • org.xml.sax.SAXNotSupportedException
          • org.xml.sax.SAXParseException

Interface Hierarchy

  • org.xml.sax.AttributeList
  • org.xml.sax.Attributes
  • org.xml.sax.ContentHandler
  • org.xml.sax.DocumentHandler
  • org.xml.sax.DTDHandler
  • org.xml.sax.EntityResolver
  • org.xml.sax.ErrorHandler
  • org.xml.sax.Locator
  • org.xml.sax.Parser
  • org.xml.sax.XMLReader
    • org.xml.sax.XMLFilter
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.xml.sax

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.xml.sax

Packages that use org.xml.sax
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.parsers | Provides classes allowing the processing of XML documents.
javax.xml.transform.sax | This package implements SAX2-specific transformation APIs.
javax.xml.validation | This package provides an API for validation of XML documents.
javax.xml.xpath | This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.
org.xml.sax | This package provides the core SAX APIs.
org.xml.sax.ext | This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.
org.xml.sax.helpers | This package contains "helper" classes, including support for bootstrapping SAX-based applications.

Classes in org.xml.sax used by javax.xml.bind
ContentHandler
Receive notification of the logical content of a document.
InputSource
A single input source for an XML entity.

Classes in org.xml.sax used by javax.xml.bind.helpers
ContentHandler
Receive notification of the logical content of a document.
InputSource
A single input source for an XML entity.
Locator
Interface for associating a SAX event with a document location.
SAXException
Encapsulate a general SAX error or warning.
SAXParseException
Encapsulate an XML parse error or warning.
XMLReader
Interface for reading an XML document using callbacks.

Classes in org.xml.sax used by javax.xml.parsers
EntityResolver
Basic interface for resolving entities.
ErrorHandler
Basic interface for SAX error handlers.
HandlerBase
Deprecated. This class works with the deprecated DocumentHandler interface. It has been replaced by the SAX2 DefaultHandler class.
InputSource
A single input source for an XML entity.
Parser
Deprecated. This interface has been replaced by the SAX2 XMLReader interface, which includes Namespace support.
SAXException
Encapsulate a general SAX error or warning.
SAXNotRecognizedException
Exception class for an unrecognized identifier.
SAXNotSupportedException
Exception class for an unsupported operation.
XMLReader
Interface for reading an XML document using callbacks.

Classes in org.xml.sax used by javax.xml.transform.sax
ContentHandler
Receive notification of the logical content of a document.
DTDHandler
Receive notification of basic DTD-related events.
InputSource
A single input source for an XML entity.
XMLFilter
Interface for an XML filter.
XMLReader
Interface for reading an XML document using callbacks.

Classes in org.xml.sax used by javax.xml.validation
ContentHandler
Receive notification of the logical content of a document.
ErrorHandler
Basic interface for SAX error handlers.
SAXException
Encapsulate a general SAX error or warning.
SAXNotRecognizedException
Exception class for an unrecognized identifier.
SAXNotSupportedException
Exception class for an unsupported operation.

Classes in org.xml.sax used by javax.xml.xpath
InputSource
A single input source for an XML entity.

Classes in org.xml.sax used by org.xml.sax
AttributeList
Deprecated. This interface has been replaced by the SAX2 Attributes interface, which includes Namespace support.
Attributes
Interface for a list of XML attributes.
ContentHandler
Receive notification of the logical content of a document.
DocumentHandler
Deprecated. This interface has been replaced by the SAX2 ContentHandler interface, which includes Namespace support.
DTDHandler
Receive notification of basic DTD-related events.
EntityResolver
Basic interface for resolving entities.
ErrorHandler
Basic interface for SAX error handlers.
InputSource
A single input source for an XML entity.
Locator
Interface for associating a SAX event with a document location.
SAXException
Encapsulate a general SAX error or warning.
SAXNotRecognizedException
Exception class for an unrecognized identifier.
SAXNotSupportedException
Exception class for an unsupported operation.
SAXParseException
Encapsulate an XML parse error or warning.
XMLReader
Interface for reading an XML document using callbacks.

Classes in org.xml.sax used by org.xml.sax.ext
Attributes
Interface for a list of XML attributes.
ContentHandler
Receive notification of the logical content of a document.
DTDHandler
Receive notification of basic DTD-related events.
EntityResolver
Basic interface for resolving entities.
ErrorHandler
Basic interface for SAX error handlers.
InputSource
A single input source for an XML entity.
Locator
Interface for associating a SAX event with a document location.
SAXException
Encapsulate a general SAX error or warning.

Classes in org.xml.sax used by org.xml.sax.helpers
AttributeList
Deprecated. This interface has been replaced by the SAX2 Attributes interface, which includes Namespace support.
Attributes
Interface for a list of XML attributes.
ContentHandler
Receive notification of the logical content of a document.
DocumentHandler
Deprecated. This interface has been replaced by the SAX2 ContentHandler interface, which includes Namespace support.
DTDHandler
Receive notification of basic DTD-related events.
EntityResolver
Basic interface for resolving entities.
ErrorHandler
Basic interface for SAX error handlers.
InputSource
A single input source for an XML entity.
Locator
Interface for associating a SAX event with a document location.
Parser
Deprecated. This interface has been replaced by the SAX2 XMLReader interface, which includes Namespace support.
SAXException
Encapsulate a general SAX error or warning.
SAXNotRecognizedException
Exception class for an unrecognized identifier.
SAXNotSupportedException
Exception class for an unsupported operation.
SAXParseException
Encapsulate an XML parse error or warning.
XMLFilter
Interface for an XML filter.
XMLReader
Interface for reading an XML document using callbacks.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AttributeList

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.xml.sax
Interface AttributeList

All Known Implementing Classes:
AttributeListImpl
Deprecated. This interface has been replaced by the SAX2 Attributes interface, which includes Namespace support.

public interface AttributeList

Interface for an element's attribute specifications.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This is the original SAX1 interface for reporting an element's attributes. Unlike the new Attributes interface, it does not support Namespace-related information.

When an attribute list is supplied as part of a startElement event, the list will return valid results only during the scope of the event; once the event handler returns control to the parser, the attribute list is invalid. To save a persistent copy of the attribute list, use the SAX1 AttributeListImpl helper class.

An attribute list includes only attributes that have been specified or defaulted: #IMPLIED attributes will not be included.

There are two ways for the SAX application to obtain information from the AttributeList. First, it can iterate through the entire list:

 public void startElement (String name, AttributeList atts) {
   for (int i = 0; i < atts.getLength(); i++) {
     String name = atts.getName(i);
     String type = atts.getType(i);
     String value = atts.getValue(i);
     [...]
   }
 }

(Note that the result of getLength() will be zero if there are no attributes.)

As an alternative, the application can request the value or type of specific attributes:

 public void startElement (String name, AttributeList atts) {
   String identifier = atts.getValue("id");
   String label = atts.getValue("label");
   [...]
 }

Since:
SAX 1.0
See Also:
startElement, AttributeListImpl

Method Summary
int | getLength() Deprecated. Return the number of attributes in this list.
String | getName(int i) Deprecated. Return the name of an attribute in this list (by position).
String | getType(int i) Deprecated. Return the type of an attribute in the list (by position).
String | getType(String name) Deprecated. Return the type of an attribute in the list (by name).
String | getValue(int i) Deprecated. Return the value of an attribute in the list (by position).
String | getValue(String name) Deprecated. Return the value of an attribute in the list (by name).

Method Detail

getLength

int getLength()
Deprecated.
Return the number of attributes in this list.

The SAX parser may provide attributes in any arbitrary order, regardless of the order in which they were declared or specified. The number of attributes may be zero.

Returns:
The number of attributes in the list.

getName

String getName(int i)
Deprecated.
Return the name of an attribute in this list (by position).

The names must be unique: the SAX parser shall not include the same attribute twice. Attributes without values (those declared #IMPLIED without a value specified in the start tag) will be omitted from the list.

If the attribute name has a namespace prefix, the prefix will still be attached.

Parameters:
i - The index of the attribute in the list (starting at 0).
Returns:
The name of the indexed attribute, or null if the index is out of range.
See Also:
getLength()

getType

String getType(int i)
Deprecated.
Return the type of an attribute in the list (by position).

The attribute type is one of the strings "CDATA", "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", or "NOTATION" (always in upper case).

If the parser has not read a declaration for the attribute, or if the parser does not report attribute types, then it must return the value "CDATA" as stated in the XML 1.0 Recommentation (clause 3.3.3, "Attribute-Value Normalization").

For an enumerated attribute that is not a notation, the parser will report the type as "NMTOKEN".

Parameters:
i - The index of the attribute in the list (starting at 0).
Returns:
The attribute type as a string, or null if the index is out of range.
See Also:
getLength(), getType(java.lang.String)

getValue

String getValue(int i)
Deprecated.
Return the value of an attribute in the list (by position).

If the attribute value is a list of tokens (IDREFS, ENTITIES, or NMTOKENS), the tokens will be concatenated into a single string separated by whitespace.

Parameters:
i - The index of the attribute in the list (starting at 0).
Returns:
The attribute value as a string, or null if the index is out of range.
See Also:
getLength(), getValue(java.lang.String)

getType

String getType(String name)
Deprecated.
Return the type of an attribute in the list (by name).

The return value is the same as the return value for getType(int).

If the attribute name has a namespace prefix in the document, the application must include the prefix here.

Parameters:
name - The name of the attribute.
Returns:
The attribute type as a string, or null if no such attribute exists.
See Also:
getType(int)

getValue

String getValue(String name)
Deprecated.
Return the value of an attribute in the list (by name).

The return value is the same as the return value for getValue(int).

If the attribute name has a namespace prefix in the document, the application must include the prefix here.

Parameters:
name - the name of the attribute to return
Returns:
The attribute value as a string, or null if no such attribute exists.
See Also:
getValue(int)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Attributes

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax
Interface Attributes

All Known Subinterfaces:
Attributes2
All Known Implementing Classes:
Attributes2Impl, AttributesImpl
public interface Attributes

Interface for a list of XML attributes.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This interface allows access to a list of attributes in three different ways:

  1. by attribute index;
  2. by Namespace-qualified name; or
  3. by qualified (prefixed) name.

The list will not contain attributes that were declared #IMPLIED but not specified in the start tag. It will also not contain attributes used as Namespace declarations (xmlns*) unless the http://xml.org/sax/features/namespace-prefixes feature is set to true (it is false by default). Because SAX2 conforms to the original "Namespaces in XML" recommendation, it normally does not give namespace declaration attributes a namespace URI.

Some SAX2 parsers may support using an optional feature flag (http://xml.org/sax/features/xmlns-uris) to request that those attributes be given URIs, conforming to a later backwards-incompatible revision of that recommendation. (The attribute's "local name" will be the prefix, or "xmlns" when defining a default element namespace.) For portability, handler code should always resolve that conflict, rather than requiring parsers that can change the setting of that feature flag.

If the namespace-prefixes feature (see above) is false, access by qualified name may not be available; if the http://xml.org/sax/features/namespaces feature is false, access by Namespace-qualified names may not be available.

This interface replaces the now-deprecated SAX1 AttributeList interface, which does not contain Namespace support. In addition to Namespace support, it adds the getIndex methods (below).

The order of attributes in the list is unspecified, and will vary from implementation to implementation.

Since:
SAX 2.0
See Also:
AttributesImpl, DeclHandler.attributeDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String)

Method Summary
int | getIndex(String qName) Look up the index of an attribute by XML qualified (prefixed) name.
int | getIndex(String uri, String localName) Look up the index of an attribute by Namespace name.
int | getLength() Return the number of attributes in the list.
String | getLocalName(int index) Look up an attribute's local name by index.
String | getQName(int index) Look up an attribute's XML qualified (prefixed) name by index.
String | getType(int index) Look up an attribute's type by index.
String | getType(String qName) Look up an attribute's type by XML qualified (prefixed) name.
String | getType(String uri, String localName) Look up an attribute's type by Namespace name.
String | getURI(int index) Look up an attribute's Namespace URI by index.
String | getValue(int index) Look up an attribute's value by index.
String | getValue(String qName) Look up an attribute's value by XML qualified (prefixed) name.
String | getValue(String uri, String localName) Look up an attribute's value by Namespace name.

Method Detail

getLength

int getLength()
Return the number of attributes in the list.

Once you know the number of attributes, you can iterate through the list.

Returns:
The number of attributes in the list.
See Also:
getURI(int), getLocalName(int), getQName(int), getType(int), getValue(int)

getURI

String getURI(int index)
Look up an attribute's Namespace URI by index.

Parameters:
index - The attribute index (zero-based).
Returns:
The Namespace URI, or the empty string if none is available, or null if the index is out of range.
See Also:
getLength()

getLocalName

String getLocalName(int index)
Look up an attribute's local name by index.

Parameters:
index - The attribute index (zero-based).
Returns:
The local name, or the empty string if Namespace processing is not being performed, or null if the index is out of range.
See Also:
getLength()

getQName

String getQName(int index)
Look up an attribute's XML qualified (prefixed) name by index.

Parameters:
index - The attribute index (zero-based).
Returns:
The XML qualified name, or the empty string if none is available, or null if the index is out of range.
See Also:
getLength()

getType

String getType(int index)
Look up an attribute's type by index.

The attribute type is one of the strings "CDATA", "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", or "NOTATION" (always in upper case).

If the parser has not read a declaration for the attribute, or if the parser does not report attribute types, then it must return the value "CDATA" as stated in the XML 1.0 Recommendation (clause 3.3.3, "Attribute-Value Normalization").

For an enumerated attribute that is not a notation, the parser will report the type as "NMTOKEN".

Parameters:
index - The attribute index (zero-based).
Returns:
The attribute's type as a string, or null if the index is out of range.
See Also:
getLength()

getValue

String getValue(int index)
Look up an attribute's value by index.

If the attribute value is a list of tokens (IDREFS, ENTITIES, or NMTOKENS), the tokens will be concatenated into a single string with each token separated by a single space.

Parameters:
index - The attribute index (zero-based).
Returns:
The attribute's value as a string, or null if the index is out of range.
See Also:
getLength()

getIndex

int getIndex(String uri,
             String localName)
Look up the index of an attribute by Namespace name.

Parameters:
uri - The Namespace URI, or the empty string if the name has no Namespace URI.
localName - The attribute's local name.
Returns:
The index of the attribute, or -1 if it does not appear in the list.

getIndex

int getIndex(String qName)
Look up the index of an attribute by XML qualified (prefixed) name.

Parameters:
qName - The qualified (prefixed) name.
Returns:
The index of the attribute, or -1 if it does not appear in the list.

getType

String getType(String uri,
               String localName)
Look up an attribute's type by Namespace name.

See getType(int) for a description of the possible types.

Parameters:
uri - The Namespace URI, or the empty String if the name has no Namespace URI.
localName - The local name of the attribute.
Returns:
The attribute type as a string, or null if the attribute is not in the list or if Namespace processing is not being performed.

getType

String getType(String qName)
Look up an attribute's type by XML qualified (prefixed) name.

See getType(int) for a description of the possible types.

Parameters:
qName - The XML qualified name.
Returns:
The attribute type as a string, or null if the attribute is not in the list or if qualified names are not available.

getValue

String getValue(String uri,
                String localName)
Look up an attribute's value by Namespace name.

See getValue(int) for a description of the possible values.

Parameters:
uri - The Namespace URI, or the empty String if the name has no Namespace URI.
localName - The local name of the attribute.
Returns:
The attribute value as a string, or null if the attribute is not in the list.

getValue

String getValue(String qName)
Look up an attribute's value by XML qualified (prefixed) name.

See getValue(int) for a description of the possible values.

Parameters:
qName - The XML qualified name.
Returns:
The attribute value as a string, or null if the attribute is not in the list or if qualified names are not available.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class org.xml.sax.HandlerBase

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.HandlerBase

Packages that use HandlerBase
javax.xml.parsers Provides classes allowing the processing of XML documents.

Uses of HandlerBase in javax.xml.parsers

Methods in javax.xml.parsers with parameters of type HandlerBase
void | SAXParser.parse(File f, HandlerBase hb) Parse the content of the file specified as XML using the specified HandlerBase.
void | SAXParser.parse(InputSource is, HandlerBase hb) Parse the content given InputSource as XML using the specified HandlerBase.
void | SAXParser.parse(InputStream is, HandlerBase hb) Parse the content of the given InputStream instance as XML using the specified HandlerBase.
void | SAXParser.parse(InputStream is, HandlerBase hb, String systemId) Parse the content of the given InputStream instance as XML using the specified HandlerBase.
void | SAXParser.parse(String uri, HandlerBase hb) Parse the content described by the giving Uniform Resource Identifier (URI) as XML using the specified HandlerBase.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.xml.sax.InputSource

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.InputSource

Packages that use InputSource
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.parsers | Provides classes allowing the processing of XML documents.
javax.xml.transform.sax | This package implements SAX2-specific transformation APIs.
javax.xml.xpath | This package provides an object-model neutral API for the evaluation of XPath expressions and access to the evaluation environment.
org.xml.sax | This package provides the core SAX APIs.
org.xml.sax.ext | This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.
org.xml.sax.helpers | This package contains "helper" classes, including support for bootstrapping SAX-based applications.

Uses of InputSource in javax.xml.bind

Methods in javax.xml.bind with parameters of type InputSource
 Object Unmarshaller.unmarshal(InputSource source)
Unmarshal XML data from the specified SAX InputSource and return the resulting content tree.

Uses of InputSource in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers with parameters of type InputSource
Object | AbstractUnmarshallerImpl.unmarshal(InputSource source)
protected abstract Object | AbstractUnmarshallerImpl.unmarshal(XMLReader reader, InputSource source) Unmarshals an object by using the specified XMLReader and the InputSource.

Uses of InputSource in javax.xml.parsers

Methods in javax.xml.parsers with parameters of type InputSource
abstract Document | DocumentBuilder.parse(InputSource is) Parse the content of the given input source as an XML document and return a new DOM Document object.
void | SAXParser.parse(InputSource is, DefaultHandler dh) Parse the content given InputSource as XML using the specified DefaultHandler.
void | SAXParser.parse(InputSource is, HandlerBase hb) Parse the content given InputSource as XML using the specified HandlerBase.

Uses of InputSource in javax.xml.transform.sax

Methods in javax.xml.transform.sax that return InputSource
InputSource | SAXSource.getInputSource() Get the SAX InputSource to be used for the Source.
static InputSource | SAXSource.sourceToInputSource(Source source) Attempt to obtain a SAX InputSource object from a Source object.

Methods in javax.xml.transform.sax with parameters of type InputSource
 void SAXSource.setInputSource(InputSource inputSource)
Set the SAX InputSource to be used for the Source.

Constructors in javax.xml.transform.sax with parameters of type InputSource
SAXSource(InputSource inputSource)
Create a SAXSource, using a SAX InputSource.
SAXSource(XMLReader reader, InputSource inputSource)
Create a SAXSource, using an XMLReader and a SAX InputSource.

Uses of InputSource in javax.xml.xpath

Methods in javax.xml.xpath with parameters of type InputSource
String | XPathExpression.evaluate(InputSource source) Evaluate the compiled XPath expression in the context of the specified InputSource and return the result as a String.
Object | XPathExpression.evaluate(InputSource source, QName returnType) Evaluate the compiled XPath expression in the context of the specified InputSource and return the result as the specified type.
String | XPath.evaluate(String expression, InputSource source) Evaluate an XPath expression in the context of the specified InputSource and return the result as a String.
Object | XPath.evaluate(String expression, InputSource source, QName returnType) Evaluate an XPath expression in the context of the specified InputSource and return the result as the specified type.

Uses of InputSource in org.xml.sax

Methods in org.xml.sax that return InputSource
InputSource | HandlerBase.resolveEntity(String publicId, String systemId) Deprecated. Resolve an external entity.
InputSource | EntityResolver.resolveEntity(String publicId, String systemId) Allow the application to resolve external entities.

Methods in org.xml.sax with parameters of type InputSource
void | XMLReader.parse(InputSource input) Parse an XML document.
void | Parser.parse(InputSource source) Deprecated. Parse an XML document.

Uses of InputSource in org.xml.sax.ext

Methods in org.xml.sax.ext that return InputSource
 InputSource EntityResolver2.getExternalSubset(String name, String baseURI)
Allows applications to provide an external subset for documents that don't explicitly define one.
 InputSource DefaultHandler2.getExternalSubset(String name, String baseURI)
Tells the parser that if no external subset has been declared in the document text, none should be used.
 InputSource DefaultHandler2.resolveEntity(String publicId, String systemId)
Invokes EntityResolver2.resolveEntity() with null entity name and base URI.
 InputSource EntityResolver2.resolveEntity(String name, String publicId, String baseURI, String systemId)
Allows applications to map references to external entities into input sources, or tell the parser it should use conventional URI resolution.
 InputSource DefaultHandler2.resolveEntity(String name, String publicId, String baseURI, String systemId)
Tells the parser to resolve the systemId against the baseURI and read the entity text from that resulting absolute URI.

Uses of InputSource in org.xml.sax.helpers

Methods in org.xml.sax.helpers that return InputSource
InputSource | XMLFilterImpl.resolveEntity(String publicId, String systemId) Filter an external entity resolution.
InputSource | DefaultHandler.resolveEntity(String publicId, String systemId) Resolve an external entity.

Methods in org.xml.sax.helpers with parameters of type InputSource
void | XMLReaderAdapter.parse(InputSource input) Parse the document.
void | ParserAdapter.parse(InputSource input) Parse an XML document.
void | XMLFilterImpl.parse(InputSource input) Parse a document.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.xml.sax.SAXException

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.SAXException

Packages that use SAXException
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.parsers | Provides classes allowing the processing of XML documents.
javax.xml.validation | This package provides an API for validation of XML documents.
org.xml.sax | This package provides the core SAX APIs.
org.xml.sax.ext | This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.
org.xml.sax.helpers | This package contains "helper" classes, including support for bootstrapping SAX-based applications.

Uses of SAXException in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers with parameters of type SAXException
protected  UnmarshalException AbstractUnmarshallerImpl.createUnmarshalException(SAXException e)
Creates an UnmarshalException from a SAXException.

Uses of SAXException in javax.xml.parsers

Methods in javax.xml.parsers that throw SAXException
abstract Parser | SAXParser.getParser() Returns the SAX parser that is encapsultated by the implementation of this class.
abstract XMLReader | SAXParser.getXMLReader() Returns the XMLReader that is encapsulated by the implementation of this class.
abstract SAXParser | SAXParserFactory.newSAXParser() Creates a new instance of a SAXParser using the currently configured factory parameters.
Document | DocumentBuilder.parse(File f) Parse the content of the given file as an XML document and return a new DOM Document object.
void | SAXParser.parse(File f, DefaultHandler dh) Parse the content of the file specified as XML using the specified DefaultHandler.
void | SAXParser.parse(File f, HandlerBase hb) Parse the content of the file specified as XML using the specified HandlerBase.
abstract Document | DocumentBuilder.parse(InputSource is) Parse the content of the given input source as an XML document and return a new DOM Document object.
void | SAXParser.parse(InputSource is, DefaultHandler dh) Parse the content given InputSource as XML using the specified DefaultHandler.
void | SAXParser.parse(InputSource is, HandlerBase hb) Parse the content given InputSource as XML using the specified HandlerBase.
Document | DocumentBuilder.parse(InputStream is) Parse the content of the given InputStream as an XML document and return a new DOM Document object.
void | SAXParser.parse(InputStream is, DefaultHandler dh) Parse the content of the given InputStream instance as XML using the specified DefaultHandler.
void | SAXParser.parse(InputStream is, DefaultHandler dh, String systemId) Parse the content of the given InputStream instance as XML using the specified DefaultHandler.
void | SAXParser.parse(InputStream is, HandlerBase hb) Parse the content of the given InputStream instance as XML using the specified HandlerBase.
void | SAXParser.parse(InputStream is, HandlerBase hb, String systemId) Parse the content of the given InputStream instance as XML using the specified HandlerBase.
Document | DocumentBuilder.parse(InputStream is, String systemId) Parse the content of the given InputStream as an XML document and return a new DOM Document object.
Document | DocumentBuilder.parse(String uri) Parse the content of the given URI as an XML document and return a new DOM Document object.
void | SAXParser.parse(String uri, DefaultHandler dh) Parse the content described by the giving Uniform Resource Identifier (URI) as XML using the specified DefaultHandler.
void | SAXParser.parse(String uri, HandlerBase hb) Parse the content described by the giving Uniform Resource Identifier (URI) as XML using the specified HandlerBase.

Uses of SAXException in javax.xml.validation

Methods in javax.xml.validation that throw SAXException
abstract Schema | SchemaFactory.newSchema() Creates a special Schema object.
Schema | SchemaFactory.newSchema(File schema) Parses the specified File as a schema and returns it as a Schema.
Schema | SchemaFactory.newSchema(Source schema) Parses the specified source as a schema and returns it as a schema.
abstract Schema | SchemaFactory.newSchema(Source[] schemas) Parses the specified source(s) as a schema and returns it as a schema.
Schema | SchemaFactory.newSchema(URL schema) Parses the specified URL as a schema and returns it as a Schema.
void | Validator.validate(Source source) Validates the specified input.
abstract void | Validator.validate(Source source, Result result) Validates the specified input and send the augmented validation result to the specified output.

Uses of SAXException in org.xml.sax

Subclasses of SAXException in org.xml.sax
class | SAXNotRecognizedException Exception class for an unrecognized identifier.
class | SAXNotSupportedException Exception class for an unsupported operation.
class | SAXParseException Encapsulate an XML parse error or warning.

Methods in org.xml.sax that throw SAXException
void | DocumentHandler.characters(char[] ch, int start, int length) Deprecated. Receive notification of character data.
void | HandlerBase.characters(char[] ch, int start, int length) Deprecated. Receive notification of character data inside an element.
void | ContentHandler.characters(char[] ch, int start, int length) Receive notification of character data.
void | DocumentHandler.endDocument() Deprecated. Receive notification of the end of a document.
void | HandlerBase.endDocument() Deprecated. Receive notification of the end of the document.
void | ContentHandler.endDocument() Receive notification of the end of a document.
void | DocumentHandler.endElement(String name) Deprecated. Receive notification of the end of an element.
void | HandlerBase.endElement(String name) Deprecated. Receive notification of the end of an element.
void | ContentHandler.endElement(String uri, String localName, String qName) Receive notification of the end of an element.
void | ContentHandler.endPrefixMapping(String prefix) End the scope of a prefix-URI mapping.
void | HandlerBase.error(SAXParseException e) Deprecated. Receive notification of a recoverable parser error.
void | ErrorHandler.error(SAXParseException exception) Receive notification of a recoverable error.
void | HandlerBase.fatalError(SAXParseException e) Deprecated. Report a fatal XML parsing error.
void | ErrorHandler.fatalError(SAXParseException exception) Receive notification of a non-recoverable error.
void | DocumentHandler.ignorableWhitespace(char[] ch, int start, int length) Deprecated. Receive notification of ignorable whitespace in element content.
void | HandlerBase.ignorableWhitespace(char[] ch, int start, int length) Deprecated. Receive notification of ignorable whitespace in element content.
void | ContentHandler.ignorableWhitespace(char[] ch, int start, int length) Receive notification of ignorable whitespace in element content.
void | DTDHandler.notationDecl(String name, String publicId, String systemId) Receive notification of a notation declaration event.
void | XMLReader.parse(InputSource input) Parse an XML document.
void | Parser.parse(InputSource source) Deprecated. Parse an XML document.
void | XMLReader.parse(String systemId) Parse an XML document from a system identifier (URI).
void | Parser.parse(String systemId) Deprecated. Parse an XML document from a system identifier (URI).
void | DocumentHandler.processingInstruction(String target, String data) Deprecated. Receive notification of a processing instruction.
void | HandlerBase.processingInstruction(String target, String data) Deprecated. Receive notification of a processing instruction.
void | ContentHandler.processingInstruction(String target, String data) Receive notification of a processing instruction.
InputSource | HandlerBase.resolveEntity(String publicId, String systemId) Deprecated. Resolve an external entity.
InputSource | EntityResolver.resolveEntity(String publicId, String systemId) Allow the application to resolve external entities.
void | Parser.setLocale(Locale locale) Deprecated. Allow an application to request a locale for errors and warnings.
void | ContentHandler.skippedEntity(String name) Receive notification of a skipped entity.
void | DocumentHandler.startDocument() Deprecated. Receive notification of the beginning of a document.
void | HandlerBase.startDocument() Deprecated. Receive notification of the beginning of the document.
void | ContentHandler.startDocument() Receive notification of the beginning of a document.
void | DocumentHandler.startElement(String name, AttributeList atts) Deprecated. Receive notification of the beginning of an element.
void | HandlerBase.startElement(String name, AttributeList attributes) Deprecated. Receive notification of the start of an element.
void | ContentHandler.startElement(String uri, String localName, String qName, Attributes atts) Receive notification of the beginning of an element.
void | ContentHandler.startPrefixMapping(String prefix, String uri) Begin the scope of a prefix-URI Namespace mapping.
void | DTDHandler.unparsedEntityDecl(String name, String publicId, String systemId, String notationName) Receive notification of an unparsed entity declaration event.
void | HandlerBase.warning(SAXParseException e) Deprecated. Receive notification of a parser warning.
void | ErrorHandler.warning(SAXParseException exception) Receive notification of a warning.

Uses of SAXException in org.xml.sax.ext

Methods in org.xml.sax.ext that throw SAXException
 void DefaultHandler2.attributeDecl(String eName, String aName, String type, String mode, String value)
 void DeclHandler.attributeDecl(String eName, String aName, String type, String mode, String value)
Report an attribute type declaration.
 void DefaultHandler2.comment(char[] ch, int start, int length)
 void LexicalHandler.comment(char[] ch, int start, int length)
Report an XML comment anywhere in the document.
 void DefaultHandler2.elementDecl(String name, String model)
 void DeclHandler.elementDecl(String name, String model)
Report an element type declaration.
 void DefaultHandler2.endCDATA()
 void LexicalHandler.endCDATA()
Report the end of a CDATA section.
 void DefaultHandler2.endDTD()
 void LexicalHandler.endDTD()
Report the end of DTD declarations.
 void DefaultHandler2.endEntity(String name)
 void LexicalHandler.endEntity(String name)
Report the end of an entity.
 void DefaultHandler2.externalEntityDecl(String name, String publicId, String systemId)
 void DeclHandler.externalEntityDecl(String name, String publicId, String systemId)
Report a parsed external entity declaration.
 InputSource EntityResolver2.getExternalSubset(String name, String baseURI)
Allows applications to provide an external subset for documents that don't explicitly define one.
 InputSource DefaultHandler2.getExternalSubset(String name, String baseURI)
Tells the parser that if no external subset has been declared in the document text, none should be used.
 void DefaultHandler2.internalEntityDecl(String name, String value)
 void DeclHandler.internalEntityDecl(String name, String value)
Report an internal entity declaration.
 InputSource DefaultHandler2.resolveEntity(String publicId, String systemId)
Invokes EntityResolver2.resolveEntity() with null entity name and base URI.
 InputSource EntityResolver2.resolveEntity(String name, String publicId, String baseURI, String systemId)
Allows applications to map references to external entities into input sources, or tell the parser it should use conventional URI resolution.
 InputSource DefaultHandler2.resolveEntity(String name, String publicId, String baseURI, String systemId)
Tells the parser to resolve the systemId against the baseURI and read the entity text from that resulting absolute URI.
 void DefaultHandler2.startCDATA()
 void LexicalHandler.startCDATA()
Report the start of a CDATA section.
 void DefaultHandler2.startDTD(String name, String publicId, String systemId)
 void LexicalHandler.startDTD(String name, String publicId, String systemId)
Report the start of DTD declarations, if any.
 void DefaultHandler2.startEntity(String name)
 void LexicalHandler.startEntity(String name)
Report the beginning of some internal and external XML entities.

Uses of SAXException in org.xml.sax.helpers

Methods in org.xml.sax.helpers that throw SAXException
void | XMLReaderAdapter.characters(char[] ch, int start, int length) Adapt a SAX2 characters event.
void | ParserAdapter.characters(char[] ch, int start, int length) Adapter implementation method; do not call.
void | XMLFilterImpl.characters(char[] ch, int start, int length) Filter a character data event.
void | DefaultHandler.characters(char[] ch, int start, int length) Receive notification of character data inside an element.
static XMLReader | XMLReaderFactory.createXMLReader() Attempt to create an XMLReader from system defaults.
static XMLReader | XMLReaderFactory.createXMLReader(String className) Attempt to create an XML reader from a class name.
void | XMLReaderAdapter.endDocument() End document event.
void | ParserAdapter.endDocument() Adapter implementation method; do not call.
void | XMLFilterImpl.endDocument() Filter an end document event.
void | DefaultHandler.endDocument() Receive notification of the end of the document.
void | ParserAdapter.endElement(String qName) Adapter implementation method; do not call.
void | XMLReaderAdapter.endElement(String uri, String localName, String qName) Adapt a SAX2 end element event.
void | XMLFilterImpl.endElement(String uri, String localName, String qName) Filter an end element event.
void | DefaultHandler.endElement(String uri, String localName, String qName) Receive notification of the end of an element.
void | XMLFilterImpl.endPrefixMapping(String prefix) Filter an end Namespace prefix mapping event.
void | DefaultHandler.endPrefixMapping(String prefix) Receive notification of the end of a Namespace mapping.
void | XMLFilterImpl.error(SAXParseException e) Filter an error event.
void | DefaultHandler.error(SAXParseException e) Receive notification of a recoverable parser error.
void | XMLFilterImpl.fatalError(SAXParseException e) Filter a fatal error event.
void | DefaultHandler.fatalError(SAXParseException e) Report a fatal XML parsing error.
void | XMLReaderAdapter.ignorableWhitespace(char[] ch, int start, int length) Adapt a SAX2 ignorable whitespace event.
void | ParserAdapter.ignorableWhitespace(char[] ch, int start, int length) Adapter implementation method; do not call.
void | XMLFilterImpl.ignorableWhitespace(char[] ch, int start, int length) Filter an ignorable whitespace event.
void | DefaultHandler.ignorableWhitespace(char[] ch, int start, int length) Receive notification of ignorable whitespace in element content.
void | XMLFilterImpl.notationDecl(String name, String publicId, String systemId) Filter a notation declaration event.
void | DefaultHandler.notationDecl(String name, String publicId, String systemId) Receive notification of a notation declaration.
void | XMLReaderAdapter.parse(InputSource input) Parse the document.
void | ParserAdapter.parse(InputSource input) Parse an XML document.
void | XMLFilterImpl.parse(InputSource input) Parse a document.
void | XMLReaderAdapter.parse(String systemId) Parse the document.
void | ParserAdapter.parse(String systemId) Parse an XML document.
void | XMLFilterImpl.parse(String systemId) Parse a document.
void | XMLReaderAdapter.processingInstruction(String target, String data) Adapt a SAX2 processing instruction event.
void | ParserAdapter.processingInstruction(String target, String data) Adapter implementation method; do not call.
void | XMLFilterImpl.processingInstruction(String target, String data) Filter a processing instruction event.
void | DefaultHandler.processingInstruction(String target, String data) Receive notification of a processing instruction.
InputSource | XMLFilterImpl.resolveEntity(String publicId, String systemId) Filter an external entity resolution.
InputSource | DefaultHandler.resolveEntity(String publicId, String systemId) Resolve an external entity.
void | XMLReaderAdapter.setLocale(Locale locale) Set the locale for error reporting.
void | XMLReaderAdapter.skippedEntity(String name) Adapt a SAX2 skipped entity event.
void | XMLFilterImpl.skippedEntity(String name) Filter a skipped entity event.
void | DefaultHandler.skippedEntity(String name) Receive notification of a skipped entity.
void | XMLReaderAdapter.startDocument() Start document event.
void | ParserAdapter.startDocument() Adapter implementation method; do not call.
void | XMLFilterImpl.startDocument() Filter a start document event.
void | DefaultHandler.startDocument() Receive notification of the beginning of the document.
void | ParserAdapter.startElement(String qName, AttributeList qAtts) Adapter implementation method; do not call.
void | XMLReaderAdapter.startElement(String uri, String localName, String qName, Attributes atts) Adapt a SAX2 start element event.
void | XMLFilterImpl.startElement(String uri, String localName, String qName, Attributes atts) Filter a start element event.
void | DefaultHandler.startElement(String uri, String localName, String qName, Attributes attributes) Receive notification of the start of an element.
void | XMLFilterImpl.startPrefixMapping(String prefix, String uri) Filter a start Namespace prefix mapping event.
void | DefaultHandler.startPrefixMapping(String prefix, String uri) Receive notification of the start of a Namespace mapping.
void | XMLFilterImpl.unparsedEntityDecl(String name, String publicId, String systemId, String notationName) Filter an unparsed entity declaration event.
void | DefaultHandler.unparsedEntityDecl(String name, String publicId, String systemId, String notationName) Receive notification of an unparsed entity declaration.
void | XMLFilterImpl.warning(SAXParseException e) Filter a warning event.
void | DefaultHandler.warning(SAXParseException e) Receive notification of a parser warning.

Constructors in org.xml.sax.helpers that throw SAXException
ParserAdapter()
Construct a new parser adapter.
XMLReaderAdapter()
Create a new adapter.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.xml.sax.SAXNotRecognizedException

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.SAXNotRecognizedException

Packages that use SAXNotRecognizedException
javax.xml.parsers | Provides classes allowing the processing of XML documents.
javax.xml.validation | This package provides an API for validation of XML documents.
org.xml.sax | This package provides the core SAX APIs.
org.xml.sax.helpers | This package contains "helper" classes, including support for bootstrapping SAX-based applications.

Uses of SAXNotRecognizedException in javax.xml.parsers

Methods in javax.xml.parsers that throw SAXNotRecognizedException
abstract boolean | SAXParserFactory.getFeature(String name) Returns the particular property requested for in the underlying implementation of org.xml.sax.XMLReader.
abstract Object | SAXParser.getProperty(String name) Returns the particular property requested for in the underlying implementation of XMLReader.
abstract void | SAXParserFactory.setFeature(String name, boolean value) Sets the particular feature in the underlying implementation of org.xml.sax.XMLReader.
abstract void | SAXParser.setProperty(String name, Object value) Sets the particular property in the underlying implementation of XMLReader.

Uses of SAXNotRecognizedException in javax.xml.validation

Methods in javax.xml.validation that throw SAXNotRecognizedException
boolean | SchemaFactory.getFeature(String name) Look up the value of a feature flag.
boolean | ValidatorHandler.getFeature(String name) Look up the value of a feature flag.
boolean | Validator.getFeature(String name) Look up the value of a feature flag.
Object | SchemaFactory.getProperty(String name) Look up the value of a property.
Object | ValidatorHandler.getProperty(String name) Look up the value of a property.
Object | Validator.getProperty(String name) Look up the value of a property.
void | SchemaFactory.setFeature(String name, boolean value) Set a feature for this SchemaFactory, Schemas created by this factory, and by extension, Validators and ValidatorHandlers created by those Schemas.
void | ValidatorHandler.setFeature(String name, boolean value) Set a feature for this ValidatorHandler.
void | Validator.setFeature(String name, boolean value) Set the value of a feature flag.
void | SchemaFactory.setProperty(String name, Object object) Set the value of a property.
void | ValidatorHandler.setProperty(String name, Object object) Set the value of a property.
void | Validator.setProperty(String name, Object object) Set the value of a property.

Uses of SAXNotRecognizedException in org.xml.sax

Methods in org.xml.sax that throw SAXNotRecognizedException
boolean | XMLReader.getFeature(String name) Look up the value of a feature flag.
Object | XMLReader.getProperty(String name) Look up the value of a property.
void | XMLReader.setFeature(String name, boolean value) Set the value of a feature flag.
void | XMLReader.setProperty(String name, Object value) Set the value of a property.

Uses of SAXNotRecognizedException in org.xml.sax.helpers

Methods in org.xml.sax.helpers that throw SAXNotRecognizedException
boolean | ParserAdapter.getFeature(String name) Check a parser feature flag.
boolean | XMLFilterImpl.getFeature(String name) Look up the value of a feature.
Object | ParserAdapter.getProperty(String name) Get a parser property.
Object | XMLFilterImpl.getProperty(String name) Look up the value of a property.
void | ParserAdapter.setFeature(String name, boolean value) Set a feature flag for the parser.
void | XMLFilterImpl.setFeature(String name, boolean value) Set the value of a feature.
void | ParserAdapter.setProperty(String name, Object value) Set a parser property.
void | XMLFilterImpl.setProperty(String name, Object value) Set the value of a property.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.xml.sax.SAXNotSupportedException

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.SAXNotSupportedException

Packages that use SAXNotSupportedException
javax.xml.parsers | Provides classes allowing the processing of XML documents.
javax.xml.validation | This package provides an API for validation of XML documents.
org.xml.sax | This package provides the core SAX APIs.
org.xml.sax.helpers | This package contains "helper" classes, including support for bootstrapping SAX-based applications.

Uses of SAXNotSupportedException in javax.xml.parsers

Methods in javax.xml.parsers that throw SAXNotSupportedException
abstract boolean | SAXParserFactory.getFeature(String name) Returns the particular property requested for in the underlying implementation of org.xml.sax.XMLReader.
abstract Object | SAXParser.getProperty(String name) Returns the particular property requested for in the underlying implementation of XMLReader.
abstract void | SAXParserFactory.setFeature(String name, boolean value) Sets the particular feature in the underlying implementation of org.xml.sax.XMLReader.
abstract void | SAXParser.setProperty(String name, Object value) Sets the particular property in the underlying implementation of XMLReader.

Uses of SAXNotSupportedException in javax.xml.validation

Methods in javax.xml.validation that throw SAXNotSupportedException
boolean | SchemaFactory.getFeature(String name) Look up the value of a feature flag.
boolean | ValidatorHandler.getFeature(String name) Look up the value of a feature flag.
boolean | Validator.getFeature(String name) Look up the value of a feature flag.
Object | SchemaFactory.getProperty(String name) Look up the value of a property.
Object | ValidatorHandler.getProperty(String name) Look up the value of a property.
Object | Validator.getProperty(String name) Look up the value of a property.
void | SchemaFactory.setFeature(String name, boolean value) Set a feature for this SchemaFactory, Schemas created by this factory, and by extension, Validators and ValidatorHandlers created by those Schemas.
void | ValidatorHandler.setFeature(String name, boolean value) Set a feature for this ValidatorHandler.
void | Validator.setFeature(String name, boolean value) Set the value of a feature flag.
void | SchemaFactory.setProperty(String name, Object object) Set the value of a property.
void | ValidatorHandler.setProperty(String name, Object object) Set the value of a property.
void | Validator.setProperty(String name, Object object) Set the value of a property.

Uses of SAXNotSupportedException in org.xml.sax

Methods in org.xml.sax that throw SAXNotSupportedException
boolean | XMLReader.getFeature(String name) Look up the value of a feature flag.
Object | XMLReader.getProperty(String name) Look up the value of a property.
void | XMLReader.setFeature(String name, boolean value) Set the value of a feature flag.
void | XMLReader.setProperty(String name, Object value) Set the value of a property.

Uses of SAXNotSupportedException in org.xml.sax.helpers

Methods in org.xml.sax.helpers that throw SAXNotSupportedException
boolean | ParserAdapter.getFeature(String name) Check a parser feature flag.
boolean | XMLFilterImpl.getFeature(String name) Look up the value of a feature.
Object | ParserAdapter.getProperty(String name) Get a parser property.
Object | XMLFilterImpl.getProperty(String name) Look up the value of a property.
void | ParserAdapter.setFeature(String name, boolean value) Set a feature flag for the parser.
void | XMLFilterImpl.setFeature(String name, boolean value) Set the value of a feature.
void | ParserAdapter.setProperty(String name, Object value) Set a parser property.
void | XMLFilterImpl.setProperty(String name, Object value) Set the value of a property.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.xml.sax.SAXParseException

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.SAXParseException

Packages that use SAXParseException
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
org.xml.sax | This package provides the core SAX APIs.
org.xml.sax.helpers | This package contains "helper" classes, including support for bootstrapping SAX-based applications.

Uses of SAXParseException in javax.xml.bind.helpers

Constructors in javax.xml.bind.helpers with parameters of type SAXParseException
ValidationEventLocatorImpl(SAXParseException e)
Constructs an object from the location information of a SAXParseException.

Uses of SAXParseException in org.xml.sax

Methods in org.xml.sax with parameters of type SAXParseException
void | HandlerBase.error(SAXParseException e) Deprecated. Receive notification of a recoverable parser error.
void | ErrorHandler.error(SAXParseException exception) Receive notification of a recoverable error.
void | HandlerBase.fatalError(SAXParseException e) Deprecated. Report a fatal XML parsing error.
void | ErrorHandler.fatalError(SAXParseException exception) Receive notification of a non-recoverable error.
void | HandlerBase.warning(SAXParseException e) Deprecated. Receive notification of a parser warning.
void | ErrorHandler.warning(SAXParseException exception) Receive notification of a warning.

Uses of SAXParseException in org.xml.sax.helpers

Methods in org.xml.sax.helpers with parameters of type SAXParseException
void | XMLFilterImpl.error(SAXParseException e) Filter an error event.
void | DefaultHandler.error(SAXParseException e) Receive notification of a recoverable parser error.
void | XMLFilterImpl.fatalError(SAXParseException e) Filter a fatal error event.
void | DefaultHandler.fatalError(SAXParseException e) Report a fatal XML parsing error.
void | XMLFilterImpl.warning(SAXParseException e) Filter a warning event.
void | DefaultHandler.warning(SAXParseException e) Receive notification of a parser warning.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.xml.sax.AttributeList

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.xml.sax.AttributeList

Packages that use AttributeList
org.xml.sax | This package provides the core SAX APIs.
org.xml.sax.helpers | This package contains "helper" classes, including support for bootstrapping SAX-based applications.

Uses of AttributeList in org.xml.sax

Methods in org.xml.sax with parameters of type AttributeList
void | DocumentHandler.startElement(String name, AttributeList atts) Deprecated. Receive notification of the beginning of an element.
void | HandlerBase.startElement(String name, AttributeList attributes) Deprecated. Receive notification of the start of an element.

Uses of AttributeList in org.xml.sax.helpers

Classes in org.xml.sax.helpers that implement AttributeList
 class AttributeListImpl
Deprecated. This class implements a deprecated interface, AttributeList; that interface has been replaced by Attributes, which is implemented in the AttributesImpl helper class.

Methods in org.xml.sax.helpers with parameters of type AttributeList
void | AttributeListImpl.setAttributeList(AttributeList atts) Deprecated. Set the attribute list, discarding previous contents.
void | ParserAdapter.startElement(String qName, AttributeList qAtts) Adapter implementation method; do not call.

Constructors in org.xml.sax.helpers with parameters of type AttributeList
AttributeListImpl(AttributeList atts)
Deprecated. Construct a persistent copy of an existing attribute list.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.xml.sax.Attributes

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.xml.sax.Attributes

Packages that use Attributes
org.xml.sax | This package provides the core SAX APIs.
org.xml.sax.ext | This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.
org.xml.sax.helpers | This package contains "helper" classes, including support for bootstrapping SAX-based applications.

Uses of Attributes in org.xml.sax

Methods in org.xml.sax with parameters of type Attributes
 void ContentHandler.startElement(String uri, String localName, String qName, Attributes atts)
Receive notification of the beginning of an element.

Uses of Attributes in org.xml.sax.ext

Subinterfaces of Attributes in org.xml.sax.ext
 interface Attributes2
SAX2 extension to augment the per-attribute information provided though Attributes.

Classes in org.xml.sax.ext that implement Attributes
 class Attributes2Impl
SAX2 extension helper for additional Attributes information, implementing the Attributes2 interface.

Methods in org.xml.sax.ext with parameters of type Attributes
 void Attributes2Impl.setAttributes(Attributes atts)
Copy an entire Attributes object.

Constructors in org.xml.sax.ext with parameters of type Attributes
Attributes2Impl(Attributes atts)
Copy an existing Attributes or Attributes2 object.

Uses of Attributes in org.xml.sax.helpers

Classes in org.xml.sax.helpers that implement Attributes
 class AttributesImpl
Default implementation of the Attributes interface.

Methods in org.xml.sax.helpers with parameters of type Attributes
void | AttributesImpl.setAttributes(Attributes atts) Copy an entire Attributes object.
void | XMLReaderAdapter.startElement(String uri, String localName, String qName, Attributes atts) Adapt a SAX2 start element event.
void | XMLFilterImpl.startElement(String uri, String localName, String qName, Attributes atts) Filter a start element event.
void | DefaultHandler.startElement(String uri, String localName, String qName, Attributes attributes) Receive notification of the start of an element.

Constructors in org.xml.sax.helpers with parameters of type Attributes
AttributesImpl(Attributes atts)
Copy an existing Attributes object.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.xml.sax.ContentHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.xml.sax.ContentHandler

Packages that use ContentHandler
javax.xml.bind | Provides a runtime binding framework for client applications including unmarshalling, marshalling, and validation capabilities.
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.transform.sax | This package implements SAX2-specific transformation APIs.
javax.xml.validation | This package provides an API for validation of XML documents.
org.xml.sax | This package provides the core SAX APIs.
org.xml.sax.ext | This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.
org.xml.sax.helpers | This package contains "helper" classes, including support for bootstrapping SAX-based applications.

Uses of ContentHandler in javax.xml.bind

Subinterfaces of ContentHandler in javax.xml.bind
 interface UnmarshallerHandler
Unmarshaller implemented as SAX ContentHandler.

Methods in javax.xml.bind with parameters of type ContentHandler
 void Marshaller.marshal(Object jaxbElement, ContentHandler handler)
Marshal the content tree rooted at jaxbElement into SAX2 events.

Uses of ContentHandler in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers with parameters of type ContentHandler
 void AbstractMarshallerImpl.marshal(Object obj, ContentHandler handler)

Uses of ContentHandler in javax.xml.transform.sax

Subinterfaces of ContentHandler in javax.xml.transform.sax
interface | TemplatesHandler A SAX ContentHandler that may be used to process SAX parse events (parsing transformation instructions) into a Templates object.
interface | TransformerHandler A TransformerHandler listens for SAX ContentHandler parse events and transforms them to a Result.

Methods in javax.xml.transform.sax that return ContentHandler
 ContentHandler SAXResult.getHandler()
Get the ContentHandler that is the Result.

Methods in javax.xml.transform.sax with parameters of type ContentHandler
 void SAXResult.setHandler(ContentHandler handler)
Set the target to be a SAX2 ContentHandler.

Constructors in javax.xml.transform.sax with parameters of type ContentHandler
SAXResult(ContentHandler handler)
Create a SAXResult that targets a SAX2 ContentHandler.

Uses of ContentHandler in javax.xml.validation

Classes in javax.xml.validation that implement ContentHandler
 class ValidatorHandler
Streaming validator that works on SAX stream.

Methods in javax.xml.validation that return ContentHandler
abstract  ContentHandler ValidatorHandler.getContentHandler()
Gets the ContentHandler which receives the augmented validation result.

Methods in javax.xml.validation with parameters of type ContentHandler
abstract  void ValidatorHandler.setContentHandler(ContentHandler receiver)
Sets the ContentHandler which receives the augmented validation result.

Uses of ContentHandler in org.xml.sax

Methods in org.xml.sax that return ContentHandler
 ContentHandler XMLReader.getContentHandler()
Return the current content handler.

Methods in org.xml.sax with parameters of type ContentHandler
 void XMLReader.setContentHandler(ContentHandler handler)
Allow an application to register a content event handler.

Uses of ContentHandler in org.xml.sax.ext

Classes in org.xml.sax.ext that implement ContentHandler
 class DefaultHandler2
This class extends the SAX2 base handler class to support the SAX2 LexicalHandler, DeclHandler, and EntityResolver2 extensions.

Uses of ContentHandler in org.xml.sax.helpers

Classes in org.xml.sax.helpers that implement ContentHandler
class | DefaultHandler Default base class for SAX2 event handlers.
class | XMLFilterImpl Base class for deriving an XML filter.
class | XMLReaderAdapter Adapt a SAX2 XMLReader as a SAX1 Parser.

Methods in org.xml.sax.helpers that return ContentHandler
ContentHandler | ParserAdapter.getContentHandler() Return the current content handler.
ContentHandler | XMLFilterImpl.getContentHandler() Get the content event handler.

Methods in org.xml.sax.helpers with parameters of type ContentHandler
void | ParserAdapter.setContentHandler(ContentHandler handler) Set the content handler.
void | XMLFilterImpl.setContentHandler(ContentHandler handler) Set the content event handler.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.xml.sax.DocumentHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.xml.sax.DocumentHandler

Packages that use DocumentHandler
org.xml.sax | This package provides the core SAX APIs.
org.xml.sax.helpers | This package contains "helper" classes, including support for bootstrapping SAX-based applications.

Uses of DocumentHandler in org.xml.sax

Classes in org.xml.sax that implement DocumentHandler
 class HandlerBase
Deprecated. This class works with the deprecated DocumentHandler interface. It has been replaced by the SAX2 DefaultHandler class.

Methods in org.xml.sax with parameters of type DocumentHandler
 void Parser.setDocumentHandler(DocumentHandler handler)
Deprecated. Allow an application to register a document event handler.

Uses of DocumentHandler in org.xml.sax.helpers

Classes in org.xml.sax.helpers that implement DocumentHandler
 class ParserAdapter
Adapt a SAX1 Parser as a SAX2 XMLReader.

Methods in org.xml.sax.helpers with parameters of type DocumentHandler
 void XMLReaderAdapter.setDocumentHandler(DocumentHandler handler)
Register the SAX1 document event handler.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.xml.sax.DTDHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.xml.sax.DTDHandler

Packages that use DTDHandler
javax.xml.transform.sax | This package implements SAX2-specific transformation APIs.
org.xml.sax | This package provides the core SAX APIs.
org.xml.sax.ext | This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.
org.xml.sax.helpers | This package contains "helper" classes, including support for bootstrapping SAX-based applications.

Uses of DTDHandler in javax.xml.transform.sax

Subinterfaces of DTDHandler in javax.xml.transform.sax
 interface TransformerHandler
A TransformerHandler listens for SAX ContentHandler parse events and transforms them to a Result.

Uses of DTDHandler in org.xml.sax

Classes in org.xml.sax that implement DTDHandler
 class HandlerBase
Deprecated. This class works with the deprecated DocumentHandler interface. It has been replaced by the SAX2 DefaultHandler class.

Methods in org.xml.sax that return DTDHandler
 DTDHandler XMLReader.getDTDHandler()
Return the current DTD handler.

Methods in org.xml.sax with parameters of type DTDHandler
void | XMLReader.setDTDHandler(DTDHandler handler) Allow an application to register a DTD event handler.
void | Parser.setDTDHandler(DTDHandler handler) Deprecated. Allow an application to register a DTD event handler.

Uses of DTDHandler in org.xml.sax.ext

Classes in org.xml.sax.ext that implement DTDHandler
 class DefaultHandler2
This class extends the SAX2 base handler class to support the SAX2 LexicalHandler, DeclHandler, and EntityResolver2 extensions.

Uses of DTDHandler in org.xml.sax.helpers

Classes in org.xml.sax.helpers that implement DTDHandler
class | DefaultHandler Default base class for SAX2 event handlers.
class | XMLFilterImpl Base class for deriving an XML filter.

Methods in org.xml.sax.helpers that return DTDHandler
DTDHandler | ParserAdapter.getDTDHandler() Return the current DTD handler.
DTDHandler | XMLFilterImpl.getDTDHandler() Get the current DTD event handler.

Methods in org.xml.sax.helpers with parameters of type DTDHandler
void | XMLReaderAdapter.setDTDHandler(DTDHandler handler) Register the DTD event handler.
void | ParserAdapter.setDTDHandler(DTDHandler handler) Set the DTD handler.
void | XMLFilterImpl.setDTDHandler(DTDHandler handler) Set the DTD event handler.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.xml.sax.EntityResolver

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.xml.sax.EntityResolver

Packages that use EntityResolver
javax.xml.parsers | Provides classes allowing the processing of XML documents.
org.xml.sax | This package provides the core SAX APIs.
org.xml.sax.ext | This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.
org.xml.sax.helpers | This package contains "helper" classes, including support for bootstrapping SAX-based applications.

Uses of EntityResolver in javax.xml.parsers

Methods in javax.xml.parsers with parameters of type EntityResolver
abstract  void DocumentBuilder.setEntityResolver(EntityResolver er)
Specify the EntityResolver to be used to resolve entities present in the XML document to be parsed.

Uses of EntityResolver in org.xml.sax

Classes in org.xml.sax that implement EntityResolver
 class HandlerBase
Deprecated. This class works with the deprecated DocumentHandler interface. It has been replaced by the SAX2 DefaultHandler class.

Methods in org.xml.sax that return EntityResolver
 EntityResolver XMLReader.getEntityResolver()
Return the current entity resolver.

Methods in org.xml.sax with parameters of type EntityResolver
void | XMLReader.setEntityResolver(EntityResolver resolver) Allow an application to register an entity resolver.
void | Parser.setEntityResolver(EntityResolver resolver) Deprecated. Allow an application to register a custom entity resolver.

Uses of EntityResolver in org.xml.sax.ext

Subinterfaces of EntityResolver in org.xml.sax.ext
 interface EntityResolver2
Extended interface for mapping external entity references to input sources, or providing a missing external subset.

Classes in org.xml.sax.ext that implement EntityResolver
 class DefaultHandler2
This class extends the SAX2 base handler class to support the SAX2 LexicalHandler, DeclHandler, and EntityResolver2 extensions.

Uses of EntityResolver in org.xml.sax.helpers

Classes in org.xml.sax.helpers that implement EntityResolver
class | DefaultHandler Default base class for SAX2 event handlers.
class | XMLFilterImpl Base class for deriving an XML filter.

Methods in org.xml.sax.helpers that return EntityResolver
EntityResolver | ParserAdapter.getEntityResolver() Return the current entity resolver.
EntityResolver | XMLFilterImpl.getEntityResolver() Get the current entity resolver.

Methods in org.xml.sax.helpers with parameters of type EntityResolver
void | XMLReaderAdapter.setEntityResolver(EntityResolver resolver) Register the entity resolver.
void | ParserAdapter.setEntityResolver(EntityResolver resolver) Set the entity resolver.
void | XMLFilterImpl.setEntityResolver(EntityResolver resolver) Set the entity resolver.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.xml.sax.ErrorHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.xml.sax.ErrorHandler

Packages that use ErrorHandler
javax.xml.parsers | Provides classes allowing the processing of XML documents.
javax.xml.validation | This package provides an API for validation of XML documents.
org.xml.sax | This package provides the core SAX APIs.
org.xml.sax.ext | This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.
org.xml.sax.helpers | This package contains "helper" classes, including support for bootstrapping SAX-based applications.

Uses of ErrorHandler in javax.xml.parsers

Methods in javax.xml.parsers with parameters of type ErrorHandler
abstract  void DocumentBuilder.setErrorHandler(ErrorHandler eh)
Specify the ErrorHandler to be used by the parser.

Uses of ErrorHandler in javax.xml.validation

Methods in javax.xml.validation that return ErrorHandler
abstract ErrorHandler | SchemaFactory.getErrorHandler() Gets the current ErrorHandler set to this SchemaFactory.
abstract ErrorHandler | ValidatorHandler.getErrorHandler() Gets the current ErrorHandler set to this ValidatorHandler.
abstract ErrorHandler | Validator.getErrorHandler() Gets the current ErrorHandler set to this Validator.

Methods in javax.xml.validation with parameters of type ErrorHandler
abstract void | SchemaFactory.setErrorHandler(ErrorHandler errorHandler) Sets the ErrorHandler to receive errors encountered during the newSchema method invocation.
abstract void | ValidatorHandler.setErrorHandler(ErrorHandler errorHandler) Sets the ErrorHandler to receive errors encountered during the validation.
abstract void | Validator.setErrorHandler(ErrorHandler errorHandler) Sets the ErrorHandler to receive errors encountered during the validate method invocation.

Uses of ErrorHandler in org.xml.sax

Classes in org.xml.sax that implement ErrorHandler
 class HandlerBase
Deprecated. This class works with the deprecated DocumentHandler interface. It has been replaced by the SAX2 DefaultHandler class.

Methods in org.xml.sax that return ErrorHandler
 ErrorHandler XMLReader.getErrorHandler()
Return the current error handler.

Methods in org.xml.sax with parameters of type ErrorHandler
void | XMLReader.setErrorHandler(ErrorHandler handler) Allow an application to register an error event handler.
void | Parser.setErrorHandler(ErrorHandler handler) Deprecated. Allow an application to register an error event handler.

Uses of ErrorHandler in org.xml.sax.ext

Classes in org.xml.sax.ext that implement ErrorHandler
 class DefaultHandler2
This class extends the SAX2 base handler class to support the SAX2 LexicalHandler, DeclHandler, and EntityResolver2 extensions.

Uses of ErrorHandler in org.xml.sax.helpers

Classes in org.xml.sax.helpers that implement ErrorHandler
class | DefaultHandler Default base class for SAX2 event handlers.
class | XMLFilterImpl Base class for deriving an XML filter.

Methods in org.xml.sax.helpers that return ErrorHandler
ErrorHandler | ParserAdapter.getErrorHandler() Return the current error handler.
ErrorHandler | XMLFilterImpl.getErrorHandler() Get the current error event handler.

Methods in org.xml.sax.helpers with parameters of type ErrorHandler
void | XMLReaderAdapter.setErrorHandler(ErrorHandler handler) Register the error event handler.
void | ParserAdapter.setErrorHandler(ErrorHandler handler) Set the error handler.
void | XMLFilterImpl.setErrorHandler(ErrorHandler handler) Set the error event handler.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.xml.sax.Locator

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.xml.sax.Locator

Packages that use Locator
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
org.xml.sax | This package provides the core SAX APIs.
org.xml.sax.ext | This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.
org.xml.sax.helpers | This package contains "helper" classes, including support for bootstrapping SAX-based applications.

Uses of Locator in javax.xml.bind.helpers

Constructors in javax.xml.bind.helpers with parameters of type Locator
ValidationEventLocatorImpl(Locator loc)
Constructs an object from an org.xml.sax.Locator.

Uses of Locator in org.xml.sax

Methods in org.xml.sax with parameters of type Locator
void | DocumentHandler.setDocumentLocator(Locator locator) Deprecated. Receive an object for locating the origin of SAX document events.
void | HandlerBase.setDocumentLocator(Locator locator) Deprecated. Receive a Locator object for document events.
void | ContentHandler.setDocumentLocator(Locator locator) Receive an object for locating the origin of SAX document events.

Constructors in org.xml.sax with parameters of type Locator
SAXParseException(String message, Locator locator)
Create a new SAXParseException from a message and a Locator.
SAXParseException(String message, Locator locator, Exception e)
Wrap an existing exception in a SAXParseException.

Uses of Locator in org.xml.sax.ext

Subinterfaces of Locator in org.xml.sax.ext
 interface Locator2
SAX2 extension to augment the entity information provided though a Locator.

Classes in org.xml.sax.ext that implement Locator
 class Locator2Impl
SAX2 extension helper for holding additional Entity information, implementing the Locator2 interface.

Constructors in org.xml.sax.ext with parameters of type Locator
Locator2Impl(Locator locator)
Copy an existing Locator or Locator2 object.

Uses of Locator in org.xml.sax.helpers

Classes in org.xml.sax.helpers that implement Locator
 class LocatorImpl
Provide an optional convenience implementation of Locator.

Methods in org.xml.sax.helpers with parameters of type Locator
void | XMLReaderAdapter.setDocumentLocator(Locator locator) Set a document locator.
void | ParserAdapter.setDocumentLocator(Locator locator) Adapter implementation method; do not call.
void | XMLFilterImpl.setDocumentLocator(Locator locator) Filter a new document locator event.
void | DefaultHandler.setDocumentLocator(Locator locator) Receive a Locator object for document events.

Constructors in org.xml.sax.helpers with parameters of type Locator
LocatorImpl(Locator locator)
Copy constructor.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.xml.sax.Parser

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.xml.sax.Parser

Packages that use Parser
javax.xml.parsers | Provides classes allowing the processing of XML documents.
org.xml.sax.helpers | This package contains "helper" classes, including support for bootstrapping SAX-based applications.

Uses of Parser in javax.xml.parsers

Methods in javax.xml.parsers that return Parser
abstract  Parser SAXParser.getParser()
Returns the SAX parser that is encapsultated by the implementation of this class.

Uses of Parser in org.xml.sax.helpers

Classes in org.xml.sax.helpers that implement Parser
 class XMLReaderAdapter
Adapt a SAX2 XMLReader as a SAX1 Parser.

Methods in org.xml.sax.helpers that return Parser
static Parser | ParserFactory.makeParser() Deprecated. Create a new SAX parser using the `org.xml.sax.parser' system property.
static Parser | ParserFactory.makeParser(String className) Deprecated. Create a new SAX parser object using the class name provided.

Constructors in org.xml.sax.helpers with parameters of type Parser
ParserAdapter(Parser parser)
Construct a new parser adapter.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.xml.sax.XMLFilter

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.xml.sax.XMLFilter

Packages that use XMLFilter
javax.xml.transform.sax | This package implements SAX2-specific transformation APIs.
org.xml.sax.helpers | This package contains "helper" classes, including support for bootstrapping SAX-based applications.

Uses of XMLFilter in javax.xml.transform.sax

Methods in javax.xml.transform.sax that return XMLFilter
abstract XMLFilter | SAXTransformerFactory.newXMLFilter(Source src) Create an XMLFilter that uses the given Source as the transformation instructions.
abstract XMLFilter | SAXTransformerFactory.newXMLFilter(Templates templates) Create an XMLFilter, based on the Templates argument..

Uses of XMLFilter in org.xml.sax.helpers

Classes in org.xml.sax.helpers that implement XMLFilter
 class XMLFilterImpl
Base class for deriving an XML filter.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.xml.sax.XMLReader

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.xml.sax.XMLReader

Packages that use XMLReader
javax.xml.bind.helpers | JAXB Provider Use Only: Provides partial default implementations for some of the javax.xml.bind interfaces.
javax.xml.parsers | Provides classes allowing the processing of XML documents.
javax.xml.transform.sax | This package implements SAX2-specific transformation APIs.
org.xml.sax | This package provides the core SAX APIs.
org.xml.sax.helpers | This package contains "helper" classes, including support for bootstrapping SAX-based applications.

Uses of XMLReader in javax.xml.bind.helpers

Methods in javax.xml.bind.helpers that return XMLReader
protected  XMLReader AbstractUnmarshallerImpl.getXMLReader()
Obtains a configured XMLReader.

Methods in javax.xml.bind.helpers with parameters of type XMLReader
protected abstract  Object AbstractUnmarshallerImpl.unmarshal(XMLReader reader, InputSource source)
Unmarshals an object by using the specified XMLReader and the InputSource.

Uses of XMLReader in javax.xml.parsers

Methods in javax.xml.parsers that return XMLReader
abstract  XMLReader SAXParser.getXMLReader()
Returns the XMLReader that is encapsulated by the implementation of this class.

Uses of XMLReader in javax.xml.transform.sax

Methods in javax.xml.transform.sax that return XMLReader
 XMLReader SAXSource.getXMLReader()
Get the XMLReader to be used for the Source.

Methods in javax.xml.transform.sax with parameters of type XMLReader
 void SAXSource.setXMLReader(XMLReader reader)
Set the XMLReader to be used for the Source.

Constructors in javax.xml.transform.sax with parameters of type XMLReader
SAXSource(XMLReader reader, InputSource inputSource)
Create a SAXSource, using an XMLReader and a SAX InputSource.

Uses of XMLReader in org.xml.sax

Subinterfaces of XMLReader in org.xml.sax
 interface XMLFilter
Interface for an XML filter.

Methods in org.xml.sax that return XMLReader
 XMLReader XMLFilter.getParent()
Get the parent reader.

Methods in org.xml.sax with parameters of type XMLReader
 void XMLFilter.setParent(XMLReader parent)
Set the parent reader.

Uses of XMLReader in org.xml.sax.helpers

Classes in org.xml.sax.helpers that implement XMLReader
class | ParserAdapter Adapt a SAX1 Parser as a SAX2 XMLReader.
class | XMLFilterImpl Base class for deriving an XML filter.

Methods in org.xml.sax.helpers that return XMLReader
static XMLReader | XMLReaderFactory.createXMLReader() Attempt to create an XMLReader from system defaults.
static XMLReader | XMLReaderFactory.createXMLReader(String className) Attempt to create an XML reader from a class name.
XMLReader | XMLFilterImpl.getParent() Get the parent reader.

Methods in org.xml.sax.helpers with parameters of type XMLReader
 void XMLFilterImpl.setParent(XMLReader parent)
Set the parent reader.

Constructors in org.xml.sax.helpers with parameters of type XMLReader
XMLFilterImpl(XMLReader parent)
Construct an XML filter with the specified parent.
XMLReaderAdapter(XMLReader xmlReader)
Create a new adapter.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


ContentHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax
Interface ContentHandler

All Known Subinterfaces:
TemplatesHandler, TransformerHandler, UnmarshallerHandler
All Known Implementing Classes:
DefaultHandler, DefaultHandler2, ValidatorHandler, XMLFilterImpl, XMLReaderAdapter
public interface ContentHandler

Receive notification of the logical content of a document.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This is the main interface that most SAX applications implement: if the application needs to be informed of basic parsing events, it implements this interface and registers an instance with the SAX parser using the setContentHandler method. The parser uses the instance to report basic document-related events like the start and end of elements and character data.

The order of events in this interface is very important, and mirrors the order of information in the document itself. For example, all of an element's content (character data, processing instructions, and/or subelements) will appear, in order, between the startElement event and the corresponding endElement event.

This interface is similar to the now-deprecated SAX 1.0 DocumentHandler interface, but it adds support for Namespaces and for reporting skipped entities (in non-validating XML processors).

Implementors should note that there is also a ContentHandler class in the java.net package; that means that it's probably a bad idea to do

import java.net.*;
 import org.xml.sax.*;

In fact, "import ...*" is usually a sign of sloppy programming anyway, so the user should consider this a feature rather than a bug.

Since:
SAX 2.0
See Also:
XMLReader, DTDHandler, ErrorHandler

Method Summary
void | characters(char[] ch, int start, int length) Receive notification of character data.
void | endDocument() Receive notification of the end of a document.
void | endElement(String uri, String localName, String qName) Receive notification of the end of an element.
void | endPrefixMapping(String prefix) End the scope of a prefix-URI mapping.
void | ignorableWhitespace(char[] ch, int start, int length) Receive notification of ignorable whitespace in element content.
void | processingInstruction(String target, String data) Receive notification of a processing instruction.
void | setDocumentLocator(Locator locator) Receive an object for locating the origin of SAX document events.
void | skippedEntity(String name) Receive notification of a skipped entity.
void | startDocument() Receive notification of the beginning of a document.
void | startElement(String uri, String localName, String qName, Attributes atts) Receive notification of the beginning of an element.
void | startPrefixMapping(String prefix, String uri) Begin the scope of a prefix-URI Namespace mapping.

Method Detail

setDocumentLocator

void setDocumentLocator(Locator locator)
Receive an object for locating the origin of SAX document events.

SAX parsers are strongly encouraged (though not absolutely required) to supply a locator: if it does so, it must supply the locator to the application by invoking this method before invoking any of the other methods in the ContentHandler interface.

The locator allows the application to determine the end position of any document-related event, even if the parser is not reporting an error. Typically, the application will use this information for reporting its own errors (such as character content that does not match an application's business rules). The information returned by the locator is probably not sufficient for use with a search engine.

Note that the locator will return correct information only during the invocation SAX event callbacks after startDocument returns and before endDocument is called. The application should not attempt to use it at any other time.

Parameters:
locator - an object that can return the location of any SAX document event
See Also:
Locator

startDocument

void startDocument()
                   throws SAXException
Receive notification of the beginning of a document.

The SAX parser will invoke this method only once, before any other event callbacks (except for setDocumentLocator).

Throws:
SAXException - any SAX exception, possibly wrapping another exception
See Also:
endDocument()

endDocument

void endDocument()
                 throws SAXException
Receive notification of the end of a document.

There is an apparent contradiction between the documentation for this method and the documentation for ErrorHandler.fatalError(org.xml.sax.SAXParseException). Until this ambiguity is resolved in a future major release, clients should make no assumptions about whether endDocument() will or will not be invoked when the parser has reported a fatalError() or thrown an exception.

The SAX parser will invoke this method only once, and it will be the last method invoked during the parse. The parser shall not invoke this method until it has either abandoned parsing (because of an unrecoverable error) or reached the end of input.

Throws:
SAXException - any SAX exception, possibly wrapping another exception
See Also:
startDocument()

startPrefixMapping

void startPrefixMapping(String prefix,
                        String uri)
                        throws SAXException
Begin the scope of a prefix-URI Namespace mapping.

The information from this event is not necessary for normal Namespace processing: the SAX XML reader will automatically replace prefixes for element and attribute names when the http://xml.org/sax/features/namespaces feature is true (the default).

There are cases, however, when applications need to use prefixes in character data or in attribute values, where they cannot safely be expanded automatically; the start/endPrefixMapping event supplies the information to the application to expand prefixes in those contexts itself, if necessary.

Note that start/endPrefixMapping events are not guaranteed to be properly nested relative to each other: all startPrefixMapping events will occur immediately before the corresponding startElement event, and all endPrefixMapping events will occur immediately after the corresponding endElement event, but their order is not otherwise guaranteed.

There should never be start/endPrefixMapping events for the "xml" prefix, since it is predeclared and immutable.

Parameters:
prefix - the Namespace prefix being declared. An empty string is used for the default element namespace, which has no prefix.
uri - the Namespace URI the prefix is mapped to
Throws:
SAXException - the client may throw an exception during processing
See Also:
endPrefixMapping(java.lang.String), startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)

endPrefixMapping

void endPrefixMapping(String prefix)
                      throws SAXException
End the scope of a prefix-URI mapping.

See startPrefixMapping for details. These events will always occur immediately after the corresponding endElement event, but the order of endPrefixMapping events is not otherwise guaranteed.

Parameters:
prefix - the prefix that was being mapped. This is the empty string when a default mapping scope ends.
Throws:
SAXException - the client may throw an exception during processing
See Also:
startPrefixMapping(java.lang.String, java.lang.String), endElement(java.lang.String, java.lang.String, java.lang.String)

startElement

void startElement(String uri,
                  String localName,
                  String qName,
                  Attributes atts)
                  throws SAXException
Receive notification of the beginning of an element.

The Parser will invoke this method at the beginning of every element in the XML document; there will be a corresponding endElement event for every startElement event (even when the element is empty). All of the element's content will be reported, in order, before the corresponding endElement event.

This event allows up to three name components for each element:

  1. the Namespace URI;
  2. the local name; and
  3. the qualified (prefixed) name.

Any or all of these may be provided, depending on the values of the http://xml.org/sax/features/namespaces and the http://xml.org/sax/features/namespace-prefixes properties:

  • the Namespace URI and local name are required when the namespaces property is true (the default), and are optional when the namespaces property is false (if one is specified, both must be);
  • the qualified name is required when the namespace-prefixes property is true, and is optional when the namespace-prefixes property is false (the default).

Note that the attribute list provided will contain only attributes with explicit values (specified or defaulted): #IMPLIED attributes will be omitted. The attribute list will contain attributes used for Namespace declarations (xmlns* attributes) only if the http://xml.org/sax/features/namespace-prefixes property is true (it is false by default, and support for a true value is optional).

Like characters(), attribute values may have characters that need more than one char value.

Parameters:
uri - the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed
localName - the local name (without prefix), or the empty string if Namespace processing is not being performed
qName - the qualified name (with prefix), or the empty string if qualified names are not available
atts - the attributes attached to the element. If there are no attributes, it shall be an empty Attributes object. The value of this object after startElement returns is undefined
Throws:
SAXException - any SAX exception, possibly wrapping another exception
See Also:
endElement(java.lang.String, java.lang.String, java.lang.String), Attributes, AttributesImpl

endElement

void endElement(String uri,
                String localName,
                String qName)
                throws SAXException
Receive notification of the end of an element.

The SAX parser will invoke this method at the end of every element in the XML document; there will be a corresponding startElement event for every endElement event (even when the element is empty).

For information on the names, see startElement.

Parameters:
uri - the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed
localName - the local name (without prefix), or the empty string if Namespace processing is not being performed
qName - the qualified XML name (with prefix), or the empty string if qualified names are not available
Throws:
SAXException - any SAX exception, possibly wrapping another exception

characters

void characters(char[] ch,
                int start,
                int length)
                throws SAXException
Receive notification of character data.

The Parser will call this method to report each chunk of character data. SAX parsers may return all contiguous character data in a single chunk, or they may split it into several chunks; however, all of the characters in any single event must come from the same external entity so that the Locator provides useful information.

The application must not attempt to read from the array outside of the specified range.

Individual characters may consist of more than one Java char value. There are two important cases where this happens, because characters can't be represented in just sixteen bits. In one case, characters are represented in a Surrogate Pair, using two special Unicode values. Such characters are in the so-called "Astral Planes", with a code point above U+FFFF. A second case involves composite characters, such as a base character combining with one or more accent characters.

Your code should not assume that algorithms using char-at-a-time idioms will be working in character units; in some cases they will split characters. This is relevant wherever XML permits arbitrary characters, such as attribute values, processing instruction data, and comments as well as in data reported from this method. It's also generally relevant whenever Java code manipulates internationalized text; the issue isn't unique to XML.

Note that some parsers will report whitespace in element content using the ignorableWhitespace method rather than this one (validating parsers must do so).

Parameters:
ch - the characters from the XML document
start - the start position in the array
length - the number of characters to read from the array
Throws:
SAXException - any SAX exception, possibly wrapping another exception
See Also:
ignorableWhitespace(char[], int, int), Locator

ignorableWhitespace

void ignorableWhitespace(char[] ch,
                         int start,
                         int length)
                         throws SAXException
Receive notification of ignorable whitespace in element content.

Validating Parsers must use this method to report each chunk of whitespace in element content (see the W3C XML 1.0 recommendation, section 2.10): non-validating parsers may also use this method if they are capable of parsing and using content models.

SAX parsers may return all contiguous whitespace in a single chunk, or they may split it into several chunks; however, all of the characters in any single event must come from the same external entity, so that the Locator provides useful information.

The application must not attempt to read from the array outside of the specified range.

Parameters:
ch - the characters from the XML document
start - the start position in the array
length - the number of characters to read from the array
Throws:
SAXException - any SAX exception, possibly wrapping another exception
See Also:
characters(char[], int, int)

processingInstruction

void processingInstruction(String target,
                           String data)
                           throws SAXException
Receive notification of a processing instruction.

The Parser will invoke this method once for each processing instruction found: note that processing instructions may occur before or after the main document element.

A SAX parser must never report an XML declaration (XML 1.0, section 2.8) or a text declaration (XML 1.0, section 4.3.1) using this method.

Like characters(), processing instruction data may have characters that need more than one char value.

Parameters:
target - the processing instruction target
data - the processing instruction data, or null if none was supplied. The data does not include any whitespace separating it from the target
Throws:
SAXException - any SAX exception, possibly wrapping another exception

skippedEntity

void skippedEntity(String name)
                   throws SAXException
Receive notification of a skipped entity. This is not called for entity references within markup constructs such as element start tags or markup declarations. (The XML recommendation requires reporting skipped external entities. SAX also reports internal entity expansion/non-expansion, except within markup constructs.)

The Parser will invoke this method each time the entity is skipped. Non-validating processors may skip entities if they have not seen the declarations (because, for example, the entity was declared in an external DTD subset). All processors may skip external entities, depending on the values of the http://xml.org/sax/features/external-general-entities and the http://xml.org/sax/features/external-parameter-entities properties.

Parameters:
name - the name of the skipped entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be the string "[dtd]"
Throws:
SAXException - any SAX exception, possibly wrapping another exception
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DocumentHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax
Interface DocumentHandler

All Known Implementing Classes:
HandlerBase, ParserAdapter
Deprecated. This interface has been replaced by the SAX2 ContentHandler interface, which includes Namespace support.

public interface DocumentHandler

Receive notification of general document events.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This was the main event-handling interface for SAX1; in SAX2, it has been replaced by ContentHandler, which provides Namespace support and reporting of skipped entities. This interface is included in SAX2 only to support legacy SAX1 applications.

The order of events in this interface is very important, and mirrors the order of information in the document itself. For example, all of an element's content (character data, processing instructions, and/or subelements) will appear, in order, between the startElement event and the corresponding endElement event.

Application writers who do not want to implement the entire interface can derive a class from HandlerBase, which implements the default functionality; parser writers can instantiate HandlerBase to obtain a default handler. The application can find the location of any document event using the Locator interface supplied by the Parser through the setDocumentLocator method.

Since:
SAX 1.0
See Also:
Parser.setDocumentHandler(org.xml.sax.DocumentHandler), Locator, HandlerBase

Method Summary
void | characters(char[] ch, int start, int length) Deprecated. Receive notification of character data.
void | endDocument() Deprecated. Receive notification of the end of a document.
void | endElement(String name) Deprecated. Receive notification of the end of an element.
void | ignorableWhitespace(char[] ch, int start, int length) Deprecated. Receive notification of ignorable whitespace in element content.
void | processingInstruction(String target, String data) Deprecated. Receive notification of a processing instruction.
void | setDocumentLocator(Locator locator) Deprecated. Receive an object for locating the origin of SAX document events.
void | startDocument() Deprecated. Receive notification of the beginning of a document.
void | startElement(String name, AttributeList atts) Deprecated. Receive notification of the beginning of an element.

Method Detail

setDocumentLocator

void setDocumentLocator(Locator locator)
Deprecated.
Receive an object for locating the origin of SAX document events.

SAX parsers are strongly encouraged (though not absolutely required) to supply a locator: if it does so, it must supply the locator to the application by invoking this method before invoking any of the other methods in the DocumentHandler interface.

The locator allows the application to determine the end position of any document-related event, even if the parser is not reporting an error. Typically, the application will use this information for reporting its own errors (such as character content that does not match an application's business rules). The information returned by the locator is probably not sufficient for use with a search engine.

Note that the locator will return correct information only during the invocation of the events in this interface. The application should not attempt to use it at any other time.

Parameters:
locator - An object that can return the location of any SAX document event.
See Also:
Locator

startDocument

void startDocument()
                   throws SAXException
Deprecated.
Receive notification of the beginning of a document.

The SAX parser will invoke this method only once, before any other methods in this interface or in DTDHandler (except for setDocumentLocator).

Throws:
SAXException - Any SAX exception, possibly wrapping another exception.

endDocument

void endDocument()
                 throws SAXException
Deprecated.
Receive notification of the end of a document.

The SAX parser will invoke this method only once, and it will be the last method invoked during the parse. The parser shall not invoke this method until it has either abandoned parsing (because of an unrecoverable error) or reached the end of input.

Throws:
SAXException - Any SAX exception, possibly wrapping another exception.

startElement

void startElement(String name,
                  AttributeList atts)
                  throws SAXException
Deprecated.
Receive notification of the beginning of an element.

The Parser will invoke this method at the beginning of every element in the XML document; there will be a corresponding endElement() event for every startElement() event (even when the element is empty). All of the element's content will be reported, in order, before the corresponding endElement() event.

If the element name has a namespace prefix, the prefix will still be attached. Note that the attribute list provided will contain only attributes with explicit values (specified or defaulted): #IMPLIED attributes will be omitted.

Parameters:
name - The element type name.
atts - The attributes attached to the element, if any.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
endElement(java.lang.String), AttributeList

endElement

void endElement(String name)
                throws SAXException
Deprecated.
Receive notification of the end of an element.

The SAX parser will invoke this method at the end of every element in the XML document; there will be a corresponding startElement() event for every endElement() event (even when the element is empty).

If the element name has a namespace prefix, the prefix will still be attached to the name.

Parameters:
name - The element type name
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.

characters

void characters(char[] ch,
                int start,
                int length)
                throws SAXException
Deprecated.
Receive notification of character data.

The Parser will call this method to report each chunk of character data. SAX parsers may return all contiguous character data in a single chunk, or they may split it into several chunks; however, all of the characters in any single event must come from the same external entity, so that the Locator provides useful information.

The application must not attempt to read from the array outside of the specified range.

Note that some parsers will report whitespace using the ignorableWhitespace() method rather than this one (validating parsers must do so).

Parameters:
ch - The characters from the XML document.
start - The start position in the array.
length - The number of characters to read from the array.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ignorableWhitespace(char[], int, int), Locator

ignorableWhitespace

void ignorableWhitespace(char[] ch,
                         int start,
                         int length)
                         throws SAXException
Deprecated.
Receive notification of ignorable whitespace in element content.

Validating Parsers must use this method to report each chunk of ignorable whitespace (see the W3C XML 1.0 recommendation, section 2.10): non-validating parsers may also use this method if they are capable of parsing and using content models.

SAX parsers may return all contiguous whitespace in a single chunk, or they may split it into several chunks; however, all of the characters in any single event must come from the same external entity, so that the Locator provides useful information.

The application must not attempt to read from the array outside of the specified range.

Parameters:
ch - The characters from the XML document.
start - The start position in the array.
length - The number of characters to read from the array.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
characters(char[], int, int)

processingInstruction

void processingInstruction(String target,
                           String data)
                           throws SAXException
Deprecated.
Receive notification of a processing instruction.

The Parser will invoke this method once for each processing instruction found: note that processing instructions may occur before or after the main document element.

A SAX parser should never report an XML declaration (XML 1.0, section 2.8) or a text declaration (XML 1.0, section 4.3.1) using this method.

Parameters:
target - The processing instruction target.
data - The processing instruction data, or null if none was supplied.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DTDHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax
Interface DTDHandler

All Known Subinterfaces:
TransformerHandler
All Known Implementing Classes:
DefaultHandler, DefaultHandler2, HandlerBase, XMLFilterImpl
public interface DTDHandler

Receive notification of basic DTD-related events.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

If a SAX application needs information about notations and unparsed entities, then the application implements this interface and registers an instance with the SAX parser using the parser's setDTDHandler method. The parser uses the instance to report notation and unparsed entity declarations to the application.

Note that this interface includes only those DTD events that the XML recommendation requires processors to report: notation and unparsed entity declarations.

The SAX parser may report these events in any order, regardless of the order in which the notations and unparsed entities were declared; however, all DTD events must be reported after the document handler's startDocument event, and before the first startElement event. (If the LexicalHandler is used, these events must also be reported before the endDTD event.)

It is up to the application to store the information for future use (perhaps in a hash table or object tree). If the application encounters attributes of type "NOTATION", "ENTITY", or "ENTITIES", it can use the information that it obtained through this interface to find the entity and/or notation corresponding with the attribute value.

Since:
SAX 1.0
See Also:
XMLReader.setDTDHandler(org.xml.sax.DTDHandler)

Method Summary
void | notationDecl(String name, String publicId, String systemId) Receive notification of a notation declaration event.
void | unparsedEntityDecl(String name, String publicId, String systemId, String notationName) Receive notification of an unparsed entity declaration event.

Method Detail

notationDecl

void notationDecl(String name,
                  String publicId,
                  String systemId)
                  throws SAXException
Receive notification of a notation declaration event.

It is up to the application to record the notation for later reference, if necessary; notations may appear as attribute values and in unparsed entity declarations, and are sometime used with processing instruction target names.

At least one of publicId and systemId must be non-null. If a system identifier is present, and it is a URL, the SAX parser must resolve it fully before passing it to the application through this event.

There is no guarantee that the notation declaration will be reported before any unparsed entities that use it.

Parameters:
name - The notation name.
publicId - The notation's public identifier, or null if none was given.
systemId - The notation's system identifier, or null if none was given.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String), Attributes

unparsedEntityDecl

void unparsedEntityDecl(String name,
                        String publicId,
                        String systemId,
                        String notationName)
                        throws SAXException
Receive notification of an unparsed entity declaration event.

Note that the notation name corresponds to a notation reported by the notationDecl event. It is up to the application to record the entity for later reference, if necessary; unparsed entities may appear as attribute values.

If the system identifier is a URL, the parser must resolve it fully before passing it to the application.

Parameters:
name - The unparsed entity's name.
publicId - The entity's public identifier, or null if none was given.
systemId - The entity's system identifier.
notationName - The name of the associated notation.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
notationDecl(java.lang.String, java.lang.String, java.lang.String), Attributes
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EntityResolver

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax
Interface EntityResolver

All Known Subinterfaces:
EntityResolver2
All Known Implementing Classes:
DefaultHandler, DefaultHandler2, HandlerBase, XMLFilterImpl
public interface EntityResolver

Basic interface for resolving entities.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

If a SAX application needs to implement customized handling for external entities, it must implement this interface and register an instance with the SAX driver using the setEntityResolver method.

The XML reader will then allow the application to intercept any external entities (including the external DTD subset and external parameter entities, if any) before including them.

Many SAX applications will not need to implement this interface, but it will be especially useful for applications that build XML documents from databases or other specialised input sources, or for applications that use URI types other than URLs.

The following resolver would provide the application with a special character stream for the entity with the system identifier "http://www.myhost.com/today":

 import org.xml.sax.EntityResolver;
 import org.xml.sax.InputSource;

 public class MyResolver implements EntityResolver {
   public InputSource resolveEntity (String publicId, String systemId)
   {
     if (systemId.equals("http://www.myhost.com/today")) {
              // return a special input source
       MyReader reader = new MyReader();
       return new InputSource(reader);
     } else {
              // use the default behaviour
       return null;
     }
   }
 }

The application can also use this interface to redirect system identifiers to local URIs or to look up replacements in a catalog (possibly by using the public identifier).

Since:
SAX 1.0
See Also:
XMLReader.setEntityResolver(org.xml.sax.EntityResolver), InputSource

Method Summary
 InputSource resolveEntity(String publicId, String systemId)
Allow the application to resolve external entities.

Method Detail

resolveEntity

InputSource resolveEntity(String publicId,
                          String systemId)
                          throws SAXException,
                                 IOException
Allow the application to resolve external entities.

The parser will call this method before opening any external entity except the top-level document entity. Such entities include the external DTD subset and external parameter entities referenced within the DTD (in either case, only if the parser reads external parameter entities), and external general entities referenced within the document element (if the parser reads external general entities). The application may request that the parser locate the entity itself, that it use an alternative URI, or that it use data provided by the application (as a character or byte input stream).

Application writers can use this method to redirect external system identifiers to secure and/or local URIs, to look up public identifiers in a catalogue, or to read an entity from a database or other input source (including, for example, a dialog box). Neither XML nor SAX specifies a preferred policy for using public or system IDs to resolve resources. However, SAX specifies how to interpret any InputSource returned by this method, and that if none is returned, then the system ID will be dereferenced as a URL.

If the system identifier is a URL, the SAX parser must resolve it fully before reporting it to the application.

Parameters:
publicId - The public identifier of the external entity being referenced, or null if none was supplied.
systemId - The system identifier of the external entity being referenced.
Returns:
An InputSource object describing the new input source, or null to request that the parser open a regular URI connection to the system identifier.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
IOException - A Java-specific IO exception, possibly the result of creating a new InputStream or Reader for the InputSource.
See Also:
InputSource
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ErrorHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax
Interface ErrorHandler

All Known Implementing Classes:
DefaultHandler, DefaultHandler2, HandlerBase, XMLFilterImpl
public interface ErrorHandler

Basic interface for SAX error handlers.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

If a SAX application needs to implement customized error handling, it must implement this interface and then register an instance with the XML reader using the setErrorHandler method. The parser will then report all errors and warnings through this interface.

WARNING: If an application does not register an ErrorHandler, XML parsing errors will go unreported, except that SAXParseExceptions will be thrown for fatal errors. In order to detect validity errors, an ErrorHandler that does something with error() calls must be registered.

For XML processing errors, a SAX driver must use this interface in preference to throwing an exception: it is up to the application to decide whether to throw an exception for different types of errors and warnings. Note, however, that there is no requirement that the parser continue to report additional errors after a call to fatalError. In other words, a SAX driver class may throw an exception after reporting any fatalError. Also parsers may throw appropriate exceptions for non-XML errors. For example, XMLReader.parse() would throw an IOException for errors accessing entities or the document.

Since:
SAX 1.0
See Also:
XMLReader.setErrorHandler(org.xml.sax.ErrorHandler), SAXParseException

Method Summary
void | error(SAXParseException exception) Receive notification of a recoverable error.
void | fatalError(SAXParseException exception) Receive notification of a non-recoverable error.
void | warning(SAXParseException exception) Receive notification of a warning.

Method Detail

warning

void warning(SAXParseException exception)
             throws SAXException
Receive notification of a warning.

SAX parsers will use this method to report conditions that are not errors or fatal errors as defined by the XML recommendation. The default behaviour is to take no action.

The SAX parser must continue to provide normal parsing events after invoking this method: it should still be possible for the application to process the document through to the end.

Filters may use this method to report other, non-XML warnings as well.

Parameters:
exception - The warning information encapsulated in a SAX parse exception.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
SAXParseException

error

void error(SAXParseException exception)
           throws SAXException
Receive notification of a recoverable error.

This corresponds to the definition of "error" in section 1.2 of the W3C XML 1.0 Recommendation. For example, a validating parser would use this callback to report the violation of a validity constraint. The default behaviour is to take no action.

The SAX parser must continue to provide normal parsing events after invoking this method: it should still be possible for the application to process the document through to the end. If the application cannot do so, then the parser should report a fatal error even if the XML recommendation does not require it to do so.

Filters may use this method to report other, non-XML errors as well.

Parameters:
exception - The error information encapsulated in a SAX parse exception.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
SAXParseException

fatalError

void fatalError(SAXParseException exception)
                throws SAXException
Receive notification of a non-recoverable error.

There is an apparent contradiction between the documentation for this method and the documentation for ContentHandler.endDocument(). Until this ambiguity is resolved in a future major release, clients should make no assumptions about whether endDocument() will or will not be invoked when the parser has reported a fatalError() or thrown an exception.

This corresponds to the definition of "fatal error" in section 1.2 of the W3C XML 1.0 Recommendation. For example, a parser would use this callback to report the violation of a well-formedness constraint.

The application must assume that the document is unusable after the parser has invoked this method, and should continue (if at all) only for the sake of collecting additional error messages: in fact, SAX parsers are free to stop reporting any other events once this method has been invoked.

Parameters:
exception - The error information encapsulated in a SAX parse exception.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
SAXParseException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ext

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.xml.sax.ext

This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.

See:
Description

Interface Summary
Attributes2 | SAX2 extension to augment the per-attribute information provided though Attributes.
DeclHandler | SAX2 extension handler for DTD declaration events.
EntityResolver2 | Extended interface for mapping external entity references to input sources, or providing a missing external subset.
LexicalHandler | SAX2 extension handler for lexical events.
Locator2 | SAX2 extension to augment the entity information provided though a Locator.

Class Summary
Attributes2Impl | SAX2 extension helper for additional Attributes information, implementing the Attributes2 interface.
DefaultHandler2 | This class extends the SAX2 base handler class to support the SAX2 LexicalHandler, DeclHandler, and EntityResolver2 extensions.
Locator2Impl | SAX2 extension helper for holding additional Entity information, implementing the Locator2 interface.

Package org.xml.sax.ext Description

This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.

See http://www.saxproject.org for more information about SAX.

This package is independent of the SAX2 core, though the functionality exposed generally needs to be implemented within a parser core. That independence has several consequences:

  • SAX2 drivers are not required to recognize these handlers.
  • You cannot assume that the class files will be present in every SAX2 installation.
  • This package may be updated independently of SAX2 (i.e. new handlers and classes may be added without updating SAX2 itself).
  • The new handlers are not implemented by the SAX2 org.xml.sax.helpers.DefaultHandler or org.xml.sax.helpers.XMLFilterImpl classes. You can subclass these if you need such behavior, or use the helper classes found here.
  • The handlers need to be registered differently than core SAX2 handlers.

This package, SAX2-ext, is a standardized extension to SAX2. It is designed both to allow SAX parsers to pass certain types of information to applications, and to serve as a simple model for other SAX2 parser extension packages. Not all such extension packages should need to be recognized directly by parsers, however. As an example, most validation systems can be cleanly layered on top of parsers supporting the standardized SAX2 interfaces.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.xml.sax.ext Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.xml.sax.ext

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.xml.sax.helpers.AttributesImpl (implements org.xml.sax.Attributes)
      • org.xml.sax.ext.Attributes2Impl (implements org.xml.sax.ext.Attributes2)
    • org.xml.sax.helpers.DefaultHandler (implements org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler)
      • org.xml.sax.ext.DefaultHandler2 (implements org.xml.sax.ext.DeclHandler, org.xml.sax.ext.EntityResolver2, org.xml.sax.ext.LexicalHandler)
    • org.xml.sax.helpers.LocatorImpl (implements org.xml.sax.Locator)
      • org.xml.sax.ext.Locator2Impl (implements org.xml.sax.ext.Locator2)

Interface Hierarchy

  • org.xml.sax.Attributes
    • org.xml.sax.ext.Attributes2
  • org.xml.sax.ext.DeclHandler
  • org.xml.sax.EntityResolver
    • org.xml.sax.ext.EntityResolver2
  • org.xml.sax.ext.LexicalHandler
  • org.xml.sax.Locator
    • org.xml.sax.ext.Locator2
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.xml.sax.ext

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.xml.sax.ext

Packages that use org.xml.sax.ext
javax.xml.transform.sax | This package implements SAX2-specific transformation APIs.
org.xml.sax.ext | This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.

Classes in org.xml.sax.ext used by javax.xml.transform.sax
LexicalHandler
SAX2 extension handler for lexical events.

Classes in org.xml.sax.ext used by org.xml.sax.ext
Attributes2
SAX2 extension to augment the per-attribute information provided though Attributes.
DeclHandler
SAX2 extension handler for DTD declaration events.
EntityResolver2
Extended interface for mapping external entity references to input sources, or providing a missing external subset.
LexicalHandler
SAX2 extension handler for lexical events.
Locator2
SAX2 extension to augment the entity information provided though a Locator.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Attributes2

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.ext
Interface Attributes2

All Superinterfaces:
Attributes
All Known Implementing Classes:
Attributes2Impl
public interface Attributes2
extends Attributes

SAX2 extension to augment the per-attribute information provided though Attributes. If an implementation supports this extension, the attributes provided in ContentHandler.startElement() will implement this interface, and the http://xml.org/sax/features/use-attributes2 feature flag will have the value true.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY.

XMLReader implementations are not required to support this information, and it is not part of core-only SAX2 distributions.

Note that if an attribute was defaulted (!isSpecified()) it will of necessity also have been declared (isDeclared()) in the DTD. Similarly if an attribute's type is anything except CDATA, then it must have been declared.

Since:
SAX 2.0 (extensions 1.1 alpha)

Method Summary
boolean | isDeclared(int index) Returns false unless the attribute was declared in the DTD.
boolean | isDeclared(String qName) Returns false unless the attribute was declared in the DTD.
boolean | isDeclared(String uri, String localName) Returns false unless the attribute was declared in the DTD.
boolean | isSpecified(int index) Returns true unless the attribute value was provided by DTD defaulting.
boolean | isSpecified(String qName) Returns true unless the attribute value was provided by DTD defaulting.
boolean | isSpecified(String uri, String localName) Returns true unless the attribute value was provided by DTD defaulting.
Methods inherited from interface org.xml.sax.Attributes
getIndex, getIndex, getLength, getLocalName, getQName, getType, getType, getType, getURI, getValue, getValue, getValue

Method Detail

isDeclared

boolean isDeclared(int index)
Returns false unless the attribute was declared in the DTD. This helps distinguish two kinds of attributes that SAX reports as CDATA: ones that were declared (and hence are usually valid), and those that were not (and which are never valid).

Parameters:
index - The attribute index (zero-based).
Returns:
true if the attribute was declared in the DTD, false otherwise.
Throws:
ArrayIndexOutOfBoundsException - When the supplied index does not identify an attribute.

isDeclared

boolean isDeclared(String qName)
Returns false unless the attribute was declared in the DTD. This helps distinguish two kinds of attributes that SAX reports as CDATA: ones that were declared (and hence are usually valid), and those that were not (and which are never valid).

Parameters:
qName - The XML qualified (prefixed) name.
Returns:
true if the attribute was declared in the DTD, false otherwise.
Throws:
IllegalArgumentException - When the supplied name does not identify an attribute.

isDeclared

boolean isDeclared(String uri,
                   String localName)
Returns false unless the attribute was declared in the DTD. This helps distinguish two kinds of attributes that SAX reports as CDATA: ones that were declared (and hence are usually valid), and those that were not (and which are never valid).

Remember that since DTDs do not "understand" namespaces, the namespace URI associated with an attribute may not have come from the DTD. The declaration will have applied to the attribute's qName.

Parameters:
uri - The Namespace URI, or the empty string if the name has no Namespace URI.
localName - The attribute's local name.
Returns:
true if the attribute was declared in the DTD, false otherwise.
Throws:
IllegalArgumentException - When the supplied names do not identify an attribute.

isSpecified

boolean isSpecified(int index)
Returns true unless the attribute value was provided by DTD defaulting.

Parameters:
index - The attribute index (zero-based).
Returns:
true if the value was found in the XML text, false if the value was provided by DTD defaulting.
Throws:
ArrayIndexOutOfBoundsException - When the supplied index does not identify an attribute.

isSpecified

boolean isSpecified(String uri,
                    String localName)
Returns true unless the attribute value was provided by DTD defaulting.

Remember that since DTDs do not "understand" namespaces, the namespace URI associated with an attribute may not have come from the DTD. The declaration will have applied to the attribute's qName.

Parameters:
uri - The Namespace URI, or the empty string if the name has no Namespace URI.
localName - The attribute's local name.
Returns:
true if the value was found in the XML text, false if the value was provided by DTD defaulting.
Throws:
IllegalArgumentException - When the supplied names do not identify an attribute.

isSpecified

boolean isSpecified(String qName)
Returns true unless the attribute value was provided by DTD defaulting.

Parameters:
qName - The XML qualified (prefixed) name.
Returns:
true if the value was found in the XML text, false if the value was provided by DTD defaulting.
Throws:
IllegalArgumentException - When the supplied name does not identify an attribute.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Attributes2Impl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.ext
Class Attributes2Impl

java.lang.Object
    extended by  org.xml.sax.helpers.AttributesImpl
        extended by  org.xml.sax.ext.Attributes2Impl
All Implemented Interfaces:
Attributes, Attributes2
public class Attributes2Impl
extends AttributesImpl
implements Attributes2

SAX2 extension helper for additional Attributes information, implementing the Attributes2 interface.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY.

This is not part of core-only SAX2 distributions.

The specified flag for each attribute will always be true, unless it has been set to false in the copy constructor or using setSpecified(int, boolean). Similarly, the declared flag for each attribute will always be false, except for defaulted attributes (specified is false), non-CDATA attributes, or when it is set to true using setDeclared(int, boolean). If you change an attribute's type by hand, you may need to modify its declared flag to match.

Since:
SAX 2.0 (extensions 1.1 alpha)

Constructor Summary
Attributes2Impl()
Construct a new, empty Attributes2Impl object.
Attributes2Impl(Attributes atts)
Copy an existing Attributes or Attributes2 object.
Method Summary
void | addAttribute(String uri, String localName, String qName, String type, String value) Add an attribute to the end of the list, setting its "specified" flag to true.
boolean | isDeclared(int index) Returns the current value of the attribute's "declared" flag.
boolean | isDeclared(String qName) Returns the current value of the attribute's "declared" flag.
boolean | isDeclared(String uri, String localName) Returns the current value of the attribute's "declared" flag.
boolean | isSpecified(int index) Returns the current value of an attribute's "specified" flag.
boolean | isSpecified(String qName) Returns the current value of an attribute's "specified" flag.
boolean | isSpecified(String uri, String localName) Returns the current value of an attribute's "specified" flag.
void | removeAttribute(int index) Remove an attribute from the list.
void | setAttributes(Attributes atts) Copy an entire Attributes object.
void | setDeclared(int index, boolean value) Assign a value to the "declared" flag of a specific attribute.
void | setSpecified(int index, boolean value) Assign a value to the "specified" flag of a specific attribute.
Methods inherited from class org.xml.sax.helpers.AttributesImpl
clear, getIndex, getIndex, getLength, getLocalName, getQName, getType, getType, getType, getURI, getValue, getValue, getValue, setAttribute, setLocalName, setQName, setType, setURI, setValue
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.xml.sax.Attributes
getIndex, getIndex, getLength, getLocalName, getQName, getType, getType, getType, getURI, getValue, getValue, getValue

Constructor Detail

Attributes2Impl

public Attributes2Impl()
Construct a new, empty Attributes2Impl object.

Attributes2Impl

public Attributes2Impl(Attributes atts)
Copy an existing Attributes or Attributes2 object. If the object implements Attributes2, values of the specified and declared flags for each attribute are copied. Otherwise the flag values are defaulted to assume no DTD was used, unless there is evidence to the contrary (such as attributes with type other than CDATA, which must have been declared).

This constructor is especially useful inside a startElement event.

Parameters:
atts - The existing Attributes object.
Method Detail

isDeclared

public boolean isDeclared(int index)
Returns the current value of the attribute's "declared" flag.

Specified by:
isDeclared in interface Attributes2
Parameters:
index - The attribute index (zero-based).
Returns:
true if the attribute was declared in the DTD, false otherwise.

isDeclared

public boolean isDeclared(String uri,
                          String localName)
Returns the current value of the attribute's "declared" flag.

Specified by:
isDeclared in interface Attributes2
Parameters:
uri - The Namespace URI, or the empty string if the name has no Namespace URI.
localName - The attribute's local name.
Returns:
true if the attribute was declared in the DTD, false otherwise.

isDeclared

public boolean isDeclared(String qName)
Returns the current value of the attribute's "declared" flag.

Specified by:
isDeclared in interface Attributes2
Parameters:
qName - The XML qualified (prefixed) name.
Returns:
true if the attribute was declared in the DTD, false otherwise.

isSpecified

public boolean isSpecified(int index)
Returns the current value of an attribute's "specified" flag.

Specified by:
isSpecified in interface Attributes2
Parameters:
index - The attribute index (zero-based).
Returns:
current flag value
Throws:
ArrayIndexOutOfBoundsException - When the supplied index does not identify an attribute.

isSpecified

public boolean isSpecified(String uri,
                           String localName)
Returns the current value of an attribute's "specified" flag.

Specified by:
isSpecified in interface Attributes2
Parameters:
uri - The Namespace URI, or the empty string if the name has no Namespace URI.
localName - The attribute's local name.
Returns:
current flag value
Throws:
IllegalArgumentException - When the supplied names do not identify an attribute.

isSpecified

public boolean isSpecified(String qName)
Returns the current value of an attribute's "specified" flag.

Specified by:
isSpecified in interface Attributes2
Parameters:
qName - The XML qualified (prefixed) name.
Returns:
current flag value
Throws:
IllegalArgumentException - When the supplied name does not identify an attribute.

setAttributes

public void setAttributes(Attributes atts)
Copy an entire Attributes object. The "specified" flags are assigned as true, and "declared" flags as false (except when an attribute's type is not CDATA), unless the object is an Attributes2 object. In that case those flag values are all copied.

Overrides:
setAttributes in class AttributesImpl
Parameters:
atts - The attributes to copy.
See Also:
AttributesImpl.setAttributes(org.xml.sax.Attributes)

addAttribute

public void addAttribute(String uri,
                         String localName,
                         String qName,
                         String type,
                         String value)
Add an attribute to the end of the list, setting its "specified" flag to true. To set that flag's value to false, use setSpecified(int, boolean).

Unless the attribute type is CDATA, this attribute is marked as being declared in the DTD. To set that flag's value to true for CDATA attributes, use setDeclared(int, boolean).

Overrides:
addAttribute in class AttributesImpl
Parameters:
uri - The Namespace URI, or the empty string if none is available or Namespace processing is not being performed.
localName - The local name, or the empty string if Namespace processing is not being performed.
qName - The qualified (prefixed) name, or the empty string if qualified names are not available.
type - The attribute type as a string.
value - The attribute value.
See Also:
AttributesImpl.addAttribute(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String)

removeAttribute

public void removeAttribute(int index)
Description copied from class: AttributesImpl
Remove an attribute from the list.

Overrides:
removeAttribute in class AttributesImpl
Parameters:
index - The index of the attribute (zero-based).

setDeclared

public void setDeclared(int index,
                        boolean value)
Assign a value to the "declared" flag of a specific attribute. This is normally needed only for attributes of type CDATA, including attributes whose type is changed to or from CDATA.

Parameters:
index - The index of the attribute (zero-based).
value - The desired flag value.
Throws:
ArrayIndexOutOfBoundsException - When the supplied index does not identify an attribute.
See Also:
AttributesImpl.setType(int, java.lang.String)

setSpecified

public void setSpecified(int index,
                         boolean value)
Assign a value to the "specified" flag of a specific attribute. This is the only way this flag can be cleared, except clearing by initialization with the copy constructor.

Parameters:
index - The index of the attribute (zero-based).
value - The desired flag value.
Throws:
ArrayIndexOutOfBoundsException - When the supplied index does not identify an attribute.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class org.xml.sax.ext.Attributes2Impl

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.ext.Attributes2Impl

No usage of org.xml.sax.ext.Attributes2Impl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.xml.sax.ext.DefaultHandler2

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.ext.DefaultHandler2

No usage of org.xml.sax.ext.DefaultHandler2

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.xml.sax.ext.Locator2Impl

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.ext.Locator2Impl

No usage of org.xml.sax.ext.Locator2Impl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.xml.sax.ext.Attributes2

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.xml.sax.ext.Attributes2

Packages that use Attributes2
org.xml.sax.ext This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.

Uses of Attributes2 in org.xml.sax.ext

Classes in org.xml.sax.ext that implement Attributes2
 class Attributes2Impl
SAX2 extension helper for additional Attributes information, implementing the Attributes2 interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.xml.sax.ext.DeclHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.xml.sax.ext.DeclHandler

Packages that use DeclHandler
org.xml.sax.ext This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.

Uses of DeclHandler in org.xml.sax.ext

Classes in org.xml.sax.ext that implement DeclHandler
 class DefaultHandler2
This class extends the SAX2 base handler class to support the SAX2 LexicalHandler, DeclHandler, and EntityResolver2 extensions.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.xml.sax.ext.EntityResolver2

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.xml.sax.ext.EntityResolver2

Packages that use EntityResolver2
org.xml.sax.ext This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.

Uses of EntityResolver2 in org.xml.sax.ext

Classes in org.xml.sax.ext that implement EntityResolver2
 class DefaultHandler2
This class extends the SAX2 base handler class to support the SAX2 LexicalHandler, DeclHandler, and EntityResolver2 extensions.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.xml.sax.ext.LexicalHandler

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.xml.sax.ext.LexicalHandler

Packages that use LexicalHandler
javax.xml.transform.sax | This package implements SAX2-specific transformation APIs.
org.xml.sax.ext | This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.

Uses of LexicalHandler in javax.xml.transform.sax

Subinterfaces of LexicalHandler in javax.xml.transform.sax
 interface TransformerHandler
A TransformerHandler listens for SAX ContentHandler parse events and transforms them to a Result.

Methods in javax.xml.transform.sax that return LexicalHandler
 LexicalHandler SAXResult.getLexicalHandler()
Get a SAX2 LexicalHandler for the output.

Methods in javax.xml.transform.sax with parameters of type LexicalHandler
 void SAXResult.setLexicalHandler(LexicalHandler handler)
Set the SAX2 LexicalHandler for the output.

Uses of LexicalHandler in org.xml.sax.ext

Classes in org.xml.sax.ext that implement LexicalHandler
 class DefaultHandler2
This class extends the SAX2 base handler class to support the SAX2 LexicalHandler, DeclHandler, and EntityResolver2 extensions.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Interface org.xml.sax.ext.Locator2

PREV NEXT FRAMES NO FRAMES

Uses of Interface
org.xml.sax.ext.Locator2

Packages that use Locator2
org.xml.sax.ext This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.

Uses of Locator2 in org.xml.sax.ext

Classes in org.xml.sax.ext that implement Locator2
 class Locator2Impl
SAX2 extension helper for holding additional Entity information, implementing the Locator2 interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DeclHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.ext
Interface DeclHandler

All Known Implementing Classes:
DefaultHandler2
public interface DeclHandler

SAX2 extension handler for DTD declaration events.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This is an optional extension handler for SAX2 to provide more complete information about DTD declarations in an XML document. XML readers are not required to recognize this handler, and it is not part of core-only SAX2 distributions.

Note that data-related DTD declarations (unparsed entities and notations) are already reported through the DTDHandler interface.

If you are using the declaration handler together with a lexical handler, all of the events will occur between the startDTD and the endDTD events.

To set the DeclHandler for an XML reader, use the setProperty method with the property name http://xml.org/sax/properties/declaration-handler and an object implementing this interface (or null) as the value. If the reader does not report declaration events, it will throw a SAXNotRecognizedException when you attempt to register the handler.

Since:
SAX 2.0 (extensions 1.0)

Method Summary
void | attributeDecl(String eName, String aName, String type, String mode, String value) Report an attribute type declaration.
void | elementDecl(String name, String model) Report an element type declaration.
void | externalEntityDecl(String name, String publicId, String systemId) Report a parsed external entity declaration.
void | internalEntityDecl(String name, String value) Report an internal entity declaration.

Method Detail

elementDecl

void elementDecl(String name,
                 String model)
                 throws SAXException
Report an element type declaration.

The content model will consist of the string "EMPTY", the string "ANY", or a parenthesised group, optionally followed by an occurrence indicator. The model will be normalized so that all parameter entities are fully resolved and all whitespace is removed,and will include the enclosing parentheses. Other normalization (such as removing redundant parentheses or simplifying occurrence indicators) is at the discretion of the parser.

Parameters:
name - The element type name.
model - The content model as a normalized string.
Throws:
SAXException - The application may raise an exception.

attributeDecl

void attributeDecl(String eName,
                   String aName,
                   String type,
                   String mode,
                   String value)
                   throws SAXException
Report an attribute type declaration.

Only the effective (first) declaration for an attribute will be reported. The type will be one of the strings "CDATA", "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", a parenthesized token group with the separator "|" and all whitespace removed, or the word "NOTATION" followed by a space followed by a parenthesized token group with all whitespace removed.

The value will be the value as reported to applications, appropriately normalized and with entity and character references expanded.

Parameters:
eName - The name of the associated element.
aName - The name of the attribute.
type - A string representing the attribute type.
mode - A string representing the attribute defaulting mode ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if none of these applies.
value - A string representing the attribute's default value, or null if there is none.
Throws:
SAXException - The application may raise an exception.

internalEntityDecl

void internalEntityDecl(String name,
                        String value)
                        throws SAXException
Report an internal entity declaration.

Only the effective (first) declaration for each entity will be reported. All parameter entities in the value will be expanded, but general entities will not.

Parameters:
name - The name of the entity. If it is a parameter entity, the name will begin with '%'.
value - The replacement text of the entity.
Throws:
SAXException - The application may raise an exception.
See Also:
externalEntityDecl(java.lang.String, java.lang.String, java.lang.String), DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String)

externalEntityDecl

void externalEntityDecl(String name,
                        String publicId,
                        String systemId)
                        throws SAXException
Report a parsed external entity declaration.

Only the effective (first) declaration for each entity will be reported.

If the system identifier is a URL, the parser must resolve it fully before passing it to the application.

Parameters:
name - The name of the entity. If it is a parameter entity, the name will begin with '%'.
publicId - The entity's public identifier, or null if none was given.
systemId - The entity's system identifier.
Throws:
SAXException - The application may raise an exception.
See Also:
internalEntityDecl(java.lang.String, java.lang.String), DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DefaultHandler2

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.ext
Class DefaultHandler2

java.lang.Object
    extended by  org.xml.sax.helpers.DefaultHandler
        extended by  org.xml.sax.ext.DefaultHandler2
All Implemented Interfaces:
ContentHandler, DTDHandler, EntityResolver, ErrorHandler, DeclHandler, EntityResolver2, LexicalHandler
public class DefaultHandler2
extends DefaultHandler
implements LexicalHandler, DeclHandler, EntityResolver2

This class extends the SAX2 base handler class to support the SAX2 LexicalHandler, DeclHandler, and EntityResolver2 extensions. Except for overriding the original SAX1 resolveEntity() method the added handler methods just return. Subclassers may override everything on a method-by-method basis.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY.

Note: this class might yet learn that the ContentHandler.setDocumentLocator() call might be passed a Locator2 object, and that the ContentHandler.startElement() call might be passed a Attributes2 object.

Since:
SAX 2.0 (extensions 1.1 alpha)

Constructor Summary
DefaultHandler2()
Constructs a handler which ignores all parsing events.
Method Summary
 void attributeDecl(String eName, String aName, String type, String mode, String value)
Report an attribute type declaration.
 void comment(char[] ch, int start, int length)
Report an XML comment anywhere in the document.
 void elementDecl(String name, String model)
Report an element type declaration.
 void endCDATA()
Report the end of a CDATA section.
 void endDTD()
Report the end of DTD declarations.
 void endEntity(String name)
Report the end of an entity.
 void externalEntityDecl(String name, String publicId, String systemId)
Report a parsed external entity declaration.
 InputSource getExternalSubset(String name, String baseURI)
Tells the parser that if no external subset has been declared in the document text, none should be used.
 void internalEntityDecl(String name, String value)
Report an internal entity declaration.
 InputSource resolveEntity(String publicId, String systemId)
Invokes EntityResolver2.resolveEntity() with null entity name and base URI.
 InputSource resolveEntity(String name, String publicId, String baseURI, String systemId)
Tells the parser to resolve the systemId against the baseURI and read the entity text from that resulting absolute URI.
 void startCDATA()
Report the start of a CDATA section.
 void startDTD(String name, String publicId, String systemId)
Report the start of DTD declarations, if any.
 void startEntity(String name)
Report the beginning of some internal and external XML entities.
Methods inherited from class org.xml.sax.helpers.DefaultHandler
characters, endDocument, endElement, endPrefixMapping, error, fatalError, ignorableWhitespace, notationDecl, processingInstruction, setDocumentLocator, skippedEntity, startDocument, startElement, startPrefixMapping, unparsedEntityDecl, warning
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultHandler2

public DefaultHandler2()
Constructs a handler which ignores all parsing events.

Method Detail

startCDATA

public void startCDATA()
                throws SAXException
Description copied from interface: LexicalHandler
Report the start of a CDATA section.

The contents of the CDATA section will be reported through the regular characters event; this event is intended only to report the boundary.

Specified by:
startCDATA in interface LexicalHandler
Throws:
SAXException - The application may raise an exception.
See Also:
LexicalHandler.endCDATA()

endCDATA

public void endCDATA()
              throws SAXException
Description copied from interface: LexicalHandler
Report the end of a CDATA section.

Specified by:
endCDATA in interface LexicalHandler
Throws:
SAXException - The application may raise an exception.
See Also:
LexicalHandler.startCDATA()

startDTD

public void startDTD(String name,
                     String publicId,
                     String systemId)
              throws SAXException
Description copied from interface: LexicalHandler
Report the start of DTD declarations, if any.

This method is intended to report the beginning of the DOCTYPE declaration; if the document has no DOCTYPE declaration, this method will not be invoked.

All declarations reported through DTDHandler or DeclHandler events must appear between the startDTD and endDTD events. Declarations are assumed to belong to the internal DTD subset unless they appear between startEntity and endEntity events. Comments and processing instructions from the DTD should also be reported between the startDTD and endDTD events, in their original order of (logical) occurrence; they are not required to appear in their correct locations relative to DTDHandler or DeclHandler events, however.

Note that the start/endDTD events will appear within the start/endDocument events from ContentHandler and before the first startElement event.

Specified by:
startDTD in interface LexicalHandler
Parameters:
name - The document type name.
publicId - The declared public identifier for the external DTD subset, or null if none was declared.
systemId - The declared system identifier for the external DTD subset, or null if none was declared. (Note that this is not resolved against the document base URI.)
Throws:
SAXException - The application may raise an exception.
See Also:
LexicalHandler.endDTD(), LexicalHandler.startEntity(java.lang.String)

endDTD

public void endDTD()
            throws SAXException
Description copied from interface: LexicalHandler
Report the end of DTD declarations.

This method is intended to report the end of the DOCTYPE declaration; if the document has no DOCTYPE declaration, this method will not be invoked.

Specified by:
endDTD in interface LexicalHandler
Throws:
SAXException - The application may raise an exception.
See Also:
LexicalHandler.startDTD(java.lang.String, java.lang.String, java.lang.String)

startEntity

public void startEntity(String name)
                 throws SAXException
Description copied from interface: LexicalHandler
Report the beginning of some internal and external XML entities.

The reporting of parameter entities (including the external DTD subset) is optional, and SAX2 drivers that report LexicalHandler events may not implement it; you can use the http://xml.org/sax/features/lexical-handler/parameter-entities feature to query or control the reporting of parameter entities.

General entities are reported with their regular names, parameter entities have '%' prepended to their names, and the external DTD subset has the pseudo-entity name "[dtd]".

When a SAX2 driver is providing these events, all other events must be properly nested within start/end entity events. There is no additional requirement that events from DeclHandler or DTDHandler be properly ordered.

Note that skipped entities will be reported through the skippedEntity event, which is part of the ContentHandler interface.

Because of the streaming event model that SAX uses, some entity boundaries cannot be reported under any circumstances:

  • general entities within attribute values
  • parameter entities within declarations

These will be silently expanded, with no indication of where the original entity boundaries were.

Note also that the boundaries of character references (which are not really entities anyway) are not reported.

All start/endEntity events must be properly nested.

Specified by:
startEntity in interface LexicalHandler
Parameters:
name - The name of the entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be "[dtd]".
Throws:
SAXException - The application may raise an exception.
See Also:
LexicalHandler.endEntity(java.lang.String),
DeclHandler.internalEntityDecl(java.lang.String, java.lang.String),
DeclHandler.externalEntityDecl(java.lang.String, java.lang.String, java.lang.String)

endEntity

public void endEntity(String name)
               throws SAXException
Description copied from interface: LexicalHandler
Report the end of an entity.

Specified by:
endEntity in interface LexicalHandler
Parameters:
name - The name of the entity that is ending.
Throws:
SAXException - The application may raise an exception.
See Also:
LexicalHandler.startEntity(java.lang.String)

comment

public void comment(char[] ch,
                    int start,
                    int length)
             throws SAXException
Description copied from interface: LexicalHandler
Report an XML comment anywhere in the document.

This callback will be used for comments inside or outside the document element, including comments in the external DTD subset (if read). Comments in the DTD must be properly nested inside start/endDTD and start/endEntity events (if used).

Specified by:
comment in interface LexicalHandler
Parameters:
ch - An array holding the characters in the comment.
start - The starting position in the array.
length - The number of characters to use from the array.
Throws:
SAXException - The application may raise an exception.

attributeDecl

public void attributeDecl(String eName,
                          String aName,
                          String type,
                          String mode,
                          String value)
                   throws SAXException
Description copied from interface: DeclHandler
Report an attribute type declaration.

Only the effective (first) declaration for an attribute will be reported. The type will be one of the strings "CDATA", "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", a parenthesized token group with the separator "|" and all whitespace removed, or the word "NOTATION" followed by a space followed by a parenthesized token group with all whitespace removed.

The value will be the value as reported to applications, appropriately normalized and with entity and character references expanded.

Specified by:
attributeDecl in interface DeclHandler
Parameters:
eName - The name of the associated element.
aName - The name of the attribute.
type - A string representing the attribute type.
mode - A string representing the attribute defaulting mode ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if none of these applies.
value - A string representing the attribute's default value, or null if there is none.
Throws:
SAXException - The application may raise an exception.

elementDecl

public void elementDecl(String name,
                        String model)
                 throws SAXException
Description copied from interface: DeclHandler
Report an element type declaration.

The content model will consist of the string "EMPTY", the string "ANY", or a parenthesised group, optionally followed by an occurrence indicator. The model will be normalized so that all parameter entities are fully resolved and all whitespace is removed,and will include the enclosing parentheses. Other normalization (such as removing redundant parentheses or simplifying occurrence indicators) is at the discretion of the parser.

Specified by:
elementDecl in interface DeclHandler
Parameters:
name - The element type name.
model - The content model as a normalized string.
Throws:
SAXException - The application may raise an exception.

externalEntityDecl

public void externalEntityDecl(String name,
                               String publicId,
                               String systemId)
                        throws SAXException
Description copied from interface: DeclHandler
Report a parsed external entity declaration.

Only the effective (first) declaration for each entity will be reported.

If the system identifier is a URL, the parser must resolve it fully before passing it to the application.

Specified by:
externalEntityDecl in interface DeclHandler
Parameters:
name - The name of the entity. If it is a parameter entity, the name will begin with '%'.
publicId - The entity's public identifier, or null if none was given.
systemId - The entity's system identifier.
Throws:
SAXException - The application may raise an exception.
See Also:
DeclHandler.internalEntityDecl(java.lang.String, java.lang.String), DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String)

internalEntityDecl

public void internalEntityDecl(String name,
                               String value)
                        throws SAXException
Description copied from interface: DeclHandler
Report an internal entity declaration.

Only the effective (first) declaration for each entity will be reported. All parameter entities in the value will be expanded, but general entities will not.

Specified by:
internalEntityDecl in interface DeclHandler
Parameters:
name - The name of the entity. If it is a parameter entity, the name will begin with '%'.
value - The replacement text of the entity.
Throws:
SAXException - The application may raise an exception.
See Also:
DeclHandler.externalEntityDecl(java.lang.String, java.lang.String, java.lang.String), DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String)

getExternalSubset

public InputSource getExternalSubset(String name,
                                     String baseURI)
                              throws SAXException,
                                     IOException
Tells the parser that if no external subset has been declared in the document text, none should be used.

Specified by:
getExternalSubset in interface EntityResolver2
Parameters:
name - Identifies the document root element. This name comes from a DOCTYPE declaration (where available) or from the actual root element.
baseURI - The document's base URI, serving as an additional hint for selecting the external subset. This is always an absolute URI, unless it is null because the XMLReader was given an InputSource without one.
Returns:
An InputSource object describing the new external subset to be used by the parser, or null to indicate that no external subset is provided.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
IOException - Probably indicating a failure to create a new InputStream or Reader, or an illegal URL.

resolveEntity

public InputSource resolveEntity(String name,
                                 String publicId,
                                 String baseURI,
                                 String systemId)
                          throws SAXException,
                                 IOException
Tells the parser to resolve the systemId against the baseURI and read the entity text from that resulting absolute URI. Note that because the older DefaultHandler.resolveEntity(), method is overridden to call this one, this method may sometimes be invoked with null name and baseURI, and with the systemId already absolutized.

Specified by:
resolveEntity in interface EntityResolver2
Parameters:
name - Identifies the external entity being resolved. Either "[dtd]" for the external subset, or a name starting with "%" to indicate a parameter entity, or else the name of a general entity. This is never null when invoked by a SAX2 parser.
publicId - The public identifier of the external entity being referenced (normalized as required by the XML specification), or null if none was supplied.
baseURI - The URI with respect to which relative systemIDs are interpreted. This is always an absolute URI, unless it is null (likely because the XMLReader was given an InputSource without one). This URI is defined by the XML specification to be the one associated with the "<" starting the relevant declaration.
systemId - The system identifier of the external entity being referenced; either a relative or absolute URI. This is never null when invoked by a SAX2 parser; only declared entities, and any external subset, are resolved by such parsers.
Returns:
An InputSource object describing the new input source to be used by the parser. Returning null directs the parser to resolve the system ID against the base URI and open a connection to resulting URI.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
IOException - Probably indicating a failure to create a new InputStream or Reader, or an illegal URL.

resolveEntity

public InputSource resolveEntity(String publicId,
                                 String systemId)
                          throws SAXException,
                                 IOException
Invokes EntityResolver2.resolveEntity() with null entity name and base URI. You only need to override that method to use this class.

Specified by:
resolveEntity in interface EntityResolver
Overrides:
resolveEntity in class DefaultHandler
Parameters:
publicId - The public identifier, or null if none is available.
systemId - The system identifier provided in the XML document.
Returns:
The new input source, or null to require the default behaviour.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
IOException - A Java-specific IO exception, possibly the result of creating a new InputStream or Reader for the InputSource.
See Also:
EntityResolver.resolveEntity(java.lang.String, java.lang.String)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EntityResolver2

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.ext
Interface EntityResolver2

All Superinterfaces:
EntityResolver
All Known Implementing Classes:
DefaultHandler2
public interface EntityResolver2
extends EntityResolver

Extended interface for mapping external entity references to input sources, or providing a missing external subset. The XMLReader.setEntityResolver() method is used to provide implementations of this interface to parsers. When a parser uses the methods in this interface, the EntityResolver2.resolveEntity() method (in this interface) is used instead of the older (SAX 1.0) EntityResolver.resolveEntity() method.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY.

If a SAX application requires the customized handling which this interface defines for external entities, it must ensure that it uses an XMLReader with the http://xml.org/sax/features/use-entity-resolver2 feature flag set to true (which is its default value when the feature is recognized). If that flag is unrecognized, or its value is false, or the resolver does not implement this interface, then only the EntityResolver method will be used.

That supports three categories of application that modify entity resolution. Old Style applications won't know about this interface; they will provide an EntityResolver. Transitional Mode provide an EntityResolver2 and automatically get the benefit of its methods in any systems (parsers or other tools) supporting it, due to polymorphism. Both Old Style and Transitional Mode applications will work with any SAX2 parser. New style applications will fail to run except on SAX2 parsers that support this particular feature. They will insist that feature flag have a value of "true", and the EntityResolver2 implementation they provide might throw an exception if the original SAX 1.0 style entity resolution method is invoked.

Since:
SAX 2.0 (extensions 1.1 alpha)
See Also:
XMLReader.setEntityResolver(org.xml.sax.EntityResolver)

Method Summary
InputSource | getExternalSubset(String name, String baseURI) Allows applications to provide an external subset for documents that don't explicitly define one.
InputSource | resolveEntity(String name, String publicId, String baseURI, String systemId) Allows applications to map references to external entities into input sources, or tell the parser it should use conventional URI resolution.
Methods inherited from interface org.xml.sax.EntityResolver
resolveEntity

Method Detail

getExternalSubset

InputSource getExternalSubset(String name,
                              String baseURI)
                              throws SAXException,
                                     IOException
Allows applications to provide an external subset for documents that don't explicitly define one. Documents with DOCTYPE declarations that omit an external subset can thus augment the declarations available for validation, entity processing, and attribute processing (normalization, defaulting, and reporting types including ID). This augmentation is reported through the startDTD() method as if the document text had originally included the external subset; this callback is made before any internal subset data or errors are reported.

This method can also be used with documents that have no DOCTYPE declaration. When the root element is encountered, but no DOCTYPE declaration has been seen, this method is invoked. If it returns a value for the external subset, that root element is declared to be the root element, giving the effect of splicing a DOCTYPE declaration at the end the prolog of a document that could not otherwise be valid. The sequence of parser callbacks in that case logically resembles this:

 ... comments and PIs from the prolog (as usual)
 startDTD ("rootName", source.getPublicId (), source.getSystemId ());
 startEntity ("[dtd]");
 ... declarations, comments, and PIs from the external subset
 endEntity ("[dtd]");
 endDTD ();
 ... then the rest of the document (as usual)
 startElement (..., "rootName", ...);

Note that the InputSource gets no further resolution. Implementations of this method may wish to invoke resolveEntity() to gain benefits such as use of local caches of DTD entities. Also, this method will never be used by a (non-validating) processor that is not including external parameter entities.

Uses for this method include facilitating data validation when interoperating with XML processors that would always require undesirable network accesses for external entities, or which for other reasons adopt a "no DTDs" policy. Non-validation motives include forcing documents to include DTDs so that attributes are handled consistently. For example, an XPath processor needs to know which attibutes have type "ID" before it can process a widely used type of reference.

Warning: Returning an external subset modifies the input document. By providing definitions for general entities, it can make a malformed document appear to be well formed.

Parameters:
name - Identifies the document root element. This name comes from a DOCTYPE declaration (where available) or from the actual root element.
baseURI - The document's base URI, serving as an additional hint for selecting the external subset. This is always an absolute URI, unless it is null because the XMLReader was given an InputSource without one.
Returns:
An InputSource object describing the new external subset to be used by the parser, or null to indicate that no external subset is provided.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
IOException - Probably indicating a failure to create a new InputStream or Reader, or an illegal URL.

resolveEntity

InputSource resolveEntity(String name,
                          String publicId,
                          String baseURI,
                          String systemId)
                          throws SAXException,
                                 IOException
Allows applications to map references to external entities into input sources, or tell the parser it should use conventional URI resolution. This method is only called for external entities which have been properly declared. This method provides more flexibility than the EntityResolver interface, supporting implementations of more complex catalogue schemes such as the one defined by the OASIS XML Catalogs specification.

Parsers configured to use this resolver method will call it to determine the input source to use for any external entity being included because of a reference in the XML text. That excludes the document entity, and any external entity returned by getExternalSubset(). When a (non-validating) processor is configured not to include a class of entities (parameter or general) through use of feature flags, this method is not invoked for such entities.

Note that the entity naming scheme used here is the same one used in the LexicalHandler, or in the ContentHandler.skippedEntity() method.

Parameters:
name - Identifies the external entity being resolved. Either "[dtd]" for the external subset, or a name starting with "%" to indicate a parameter entity, or else the name of a general entity. This is never null when invoked by a SAX2 parser.
publicId - The public identifier of the external entity being referenced (normalized as required by the XML specification), or null if none was supplied.
baseURI - The URI with respect to which relative systemIDs are interpreted. This is always an absolute URI, unless it is null (likely because the XMLReader was given an InputSource without one). This URI is defined by the XML specification to be the one associated with the "<" starting the relevant declaration.
systemId - The system identifier of the external entity being referenced; either a relative or absolute URI. This is never null when invoked by a SAX2 parser; only declared entities, and any external subset, are resolved by such parsers.
Returns:
An InputSource object describing the new input source to be used by the parser. Returning null directs the parser to resolve the system ID against the base URI and open a connection to resulting URI.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
IOException - Probably indicating a failure to create a new InputStream or Reader, or an illegal URL.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LexicalHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.ext
Interface LexicalHandler

All Known Subinterfaces:
TransformerHandler
All Known Implementing Classes:
DefaultHandler2
public interface LexicalHandler

SAX2 extension handler for lexical events.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This is an optional extension handler for SAX2 to provide lexical information about an XML document, such as comments and CDATA section boundaries. XML readers are not required to recognize this handler, and it is not part of core-only SAX2 distributions.

The events in the lexical handler apply to the entire document, not just to the document element, and all lexical handler events must appear between the content handler's startDocument and endDocument events.

To set the LexicalHandler for an XML reader, use the setProperty method with the property name http://xml.org/sax/properties/lexical-handler and an object implementing this interface (or null) as the value. If the reader does not report lexical events, it will throw a SAXNotRecognizedException when you attempt to register the handler.

Since:
SAX 2.0 (extensions 1.0)

Method Summary
void | comment(char[] ch, int start, int length) Report an XML comment anywhere in the document.
void | endCDATA() Report the end of a CDATA section.
void | endDTD() Report the end of DTD declarations.
void | endEntity(String name) Report the end of an entity.
void | startCDATA() Report the start of a CDATA section.
void | startDTD(String name, String publicId, String systemId) Report the start of DTD declarations, if any.
void | startEntity(String name) Report the beginning of some internal and external XML entities.

Method Detail

startDTD

void startDTD(String name,
              String publicId,
              String systemId)
              throws SAXException
Report the start of DTD declarations, if any.

This method is intended to report the beginning of the DOCTYPE declaration; if the document has no DOCTYPE declaration, this method will not be invoked.

All declarations reported through DTDHandler or DeclHandler events must appear between the startDTD and endDTD events. Declarations are assumed to belong to the internal DTD subset unless they appear between startEntity and endEntity events. Comments and processing instructions from the DTD should also be reported between the startDTD and endDTD events, in their original order of (logical) occurrence; they are not required to appear in their correct locations relative to DTDHandler or DeclHandler events, however.

Note that the start/endDTD events will appear within the start/endDocument events from ContentHandler and before the first startElement event.

Parameters:
name - The document type name.
publicId - The declared public identifier for the external DTD subset, or null if none was declared.
systemId - The declared system identifier for the external DTD subset, or null if none was declared. (Note that this is not resolved against the document base URI.)
Throws:
SAXException - The application may raise an exception.
See Also:
endDTD(), startEntity(java.lang.String)

endDTD

void endDTD()
            throws SAXException
Report the end of DTD declarations.

This method is intended to report the end of the DOCTYPE declaration; if the document has no DOCTYPE declaration, this method will not be invoked.

Throws:
SAXException - The application may raise an exception.
See Also:
startDTD(java.lang.String, java.lang.String, java.lang.String)

startEntity

void startEntity(String name)
                 throws SAXException
Report the beginning of some internal and external XML entities.

The reporting of parameter entities (including the external DTD subset) is optional, and SAX2 drivers that report LexicalHandler events may not implement it; you can use the http://xml.org/sax/features/lexical-handler/parameter-entities feature to query or control the reporting of parameter entities.

General entities are reported with their regular names, parameter entities have '%' prepended to their names, and the external DTD subset has the pseudo-entity name "[dtd]".

When a SAX2 driver is providing these events, all other events must be properly nested within start/end entity events. There is no additional requirement that events from DeclHandler or DTDHandler be properly ordered.

Note that skipped entities will be reported through the skippedEntity event, which is part of the ContentHandler interface.

Because of the streaming event model that SAX uses, some entity boundaries cannot be reported under any circumstances:

  • general entities within attribute values
  • parameter entities within declarations

These will be silently expanded, with no indication of where the original entity boundaries were.

Note also that the boundaries of character references (which are not really entities anyway) are not reported.

All start/endEntity events must be properly nested.

Parameters:
name - The name of the entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be "[dtd]".
Throws:
SAXException - The application may raise an exception.
See Also:
endEntity(java.lang.String),
DeclHandler.internalEntityDecl(java.lang.String, java.lang.String),
DeclHandler.externalEntityDecl(java.lang.String, java.lang.String, java.lang.String)

endEntity

void endEntity(String name)
               throws SAXException
Report the end of an entity.

Parameters:
name - The name of the entity that is ending.
Throws:
SAXException - The application may raise an exception.
See Also:
startEntity(java.lang.String)

startCDATA

void startCDATA()
                throws SAXException
Report the start of a CDATA section.

The contents of the CDATA section will be reported through the regular characters event; this event is intended only to report the boundary.

Throws:
SAXException - The application may raise an exception.
See Also:
endCDATA()

endCDATA

void endCDATA()
              throws SAXException
Report the end of a CDATA section.

Throws:
SAXException - The application may raise an exception.
See Also:
startCDATA()

comment

void comment(char[] ch,
             int start,
             int length)
             throws SAXException
Report an XML comment anywhere in the document.

This callback will be used for comments inside or outside the document element, including comments in the external DTD subset (if read). Comments in the DTD must be properly nested inside start/endDTD and start/endEntity events (if used).

Parameters:
ch - An array holding the characters in the comment.
start - The starting position in the array.
length - The number of characters to use from the array.
Throws:
SAXException - The application may raise an exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Locator2

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.ext
Interface Locator2

All Superinterfaces:
Locator
All Known Implementing Classes:
Locator2Impl
public interface Locator2
extends Locator

SAX2 extension to augment the entity information provided though a Locator. If an implementation supports this extension, the Locator provided in ContentHandler.setDocumentLocator() will implement this interface, and the http://xml.org/sax/features/use-locator2 feature flag will have the value true.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY.

XMLReader implementations are not required to support this information, and it is not part of core-only SAX2 distributions.

Since:
SAX 2.0 (extensions 1.1 alpha)

Method Summary
String | getEncoding() Returns the name of the character encoding for the entity.
String | getXMLVersion() Returns the version of XML used for the entity.
Methods inherited from interface org.xml.sax.Locator
getColumnNumber, getLineNumber, getPublicId, getSystemId

Method Detail

getXMLVersion

String getXMLVersion()
Returns the version of XML used for the entity. This will normally be the identifier from the current entity's <?xml version='...' ...?> declaration, or be defaulted by the parser.

Returns:
Identifier for the XML version being used to interpret the entity's text, or null if that information is not yet available in the current parsing state.

getEncoding

String getEncoding()
Returns the name of the character encoding for the entity. If the encoding was declared externally (for example, in a MIME Content-Type header), that will be the name returned. Else if there was an <?xml ...encoding='...'?> declaration at the start of the document, that encoding name will be returned. Otherwise the encoding will been inferred (normally to be UTF-8, or some UTF-16 variant), and that inferred name will be returned.

When an InputSource is used to provide an entity's character stream, this method returns the encoding provided in that input stream.

Note that some recent W3C specifications require that text in some encodings be normalized, using Unicode Normalization Form C, before processing. Such normalization must be performed by applications, and would normally be triggered based on the value returned by this method.

Encoding names may be those used by the underlying JVM, and comparisons should be case-insensitive.

Returns:
Name of the character encoding being used to interpret * the entity's text, or null if this was not provided for a * character stream passed through an InputSource or is otherwise not yet available in the current parsing state.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Locator2Impl

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.ext
Class Locator2Impl

java.lang.Object
    extended by  org.xml.sax.helpers.LocatorImpl
        extended by  org.xml.sax.ext.Locator2Impl
All Implemented Interfaces:
Locator2, Locator
public class Locator2Impl
extends LocatorImpl
implements Locator2

SAX2 extension helper for holding additional Entity information, implementing the Locator2 interface.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY.

This is not part of core-only SAX2 distributions.

Since:
SAX 2.0.2

Constructor Summary
Locator2Impl()
Construct a new, empty Locator2Impl object.
Locator2Impl(Locator locator)
Copy an existing Locator or Locator2 object.
Method Summary
String | getEncoding() Returns the current value of the encoding property.
String | getXMLVersion() Returns the current value of the version property.
void | setEncoding(String encoding) Assigns the current value of the encoding property.
void | setXMLVersion(String version) Assigns the current value of the version property.
Methods inherited from class org.xml.sax.helpers.LocatorImpl
getColumnNumber, getLineNumber, getPublicId, getSystemId, setColumnNumber, setLineNumber, setPublicId, setSystemId
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.xml.sax.Locator
getColumnNumber, getLineNumber, getPublicId, getSystemId

Constructor Detail

Locator2Impl

public Locator2Impl()
Construct a new, empty Locator2Impl object. This will not normally be useful, since the main purpose of this class is to make a snapshot of an existing Locator.

Locator2Impl

public Locator2Impl(Locator locator)
Copy an existing Locator or Locator2 object. If the object implements Locator2, values of the encoding and versionstrings are copied, otherwise they set to null.

Parameters:
locator - The existing Locator object.
Method Detail

getXMLVersion

public String getXMLVersion()
Returns the current value of the version property.

Specified by:
getXMLVersion in interface Locator2
Returns:
Identifier for the XML version being used to interpret the entity's text, or null if that information is not yet available in the current parsing state.
See Also:
setXMLVersion(java.lang.String)

getEncoding

public String getEncoding()
Returns the current value of the encoding property.

Specified by:
getEncoding in interface Locator2
Returns:
Name of the character encoding being used to interpret * the entity's text, or null if this was not provided for a * character stream passed through an InputSource or is otherwise not yet available in the current parsing state.
See Also:
setEncoding(java.lang.String)

setXMLVersion

public void setXMLVersion(String version)
Assigns the current value of the version property.

Parameters:
version - the new "version" value
See Also:
getXMLVersion()

setEncoding

public void setEncoding(String encoding)
Assigns the current value of the encoding property.

Parameters:
encoding - the new "encoding" value
See Also:
getEncoding()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


HandlerBase

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax
Class HandlerBase

java.lang.Object
    extended by  org.xml.sax.HandlerBase
All Implemented Interfaces:
DocumentHandler, DTDHandler, EntityResolver, ErrorHandler
Deprecated. This class works with the deprecated DocumentHandler interface. It has been replaced by the SAX2 DefaultHandler class.

public class HandlerBase
extends Object
implements EntityResolver, DTDHandler, DocumentHandler, ErrorHandler

Default base class for handlers.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This class implements the default behaviour for four SAX1 interfaces: EntityResolver, DTDHandler, DocumentHandler, and ErrorHandler. It is now obsolete, but is included in SAX2 to support legacy SAX1 applications. SAX2 applications should use the DefaultHandler class instead.

Application writers can extend this class when they need to implement only part of an interface; parser writers can instantiate this class to provide default handlers when the application has not supplied its own.

Note that the use of this class is optional.

Since:
SAX 1.0
See Also:
EntityResolver, DTDHandler, DocumentHandler, ErrorHandler

Constructor Summary
HandlerBase()
Deprecated.
Method Summary
void | characters(char[] ch, int start, int length) Deprecated. Receive notification of character data inside an element.
void | endDocument() Deprecated. Receive notification of the end of the document.
void | endElement(String name) Deprecated. Receive notification of the end of an element.
void | error(SAXParseException e) Deprecated. Receive notification of a recoverable parser error.
void | fatalError(SAXParseException e) Deprecated. Report a fatal XML parsing error.
void | ignorableWhitespace(char[] ch, int start, int length) Deprecated. Receive notification of ignorable whitespace in element content.
void | notationDecl(String name, String publicId, String systemId) Deprecated. Receive notification of a notation declaration.
void | processingInstruction(String target, String data) Deprecated. Receive notification of a processing instruction.
InputSource | resolveEntity(String publicId, String systemId) Deprecated. Resolve an external entity.
void | setDocumentLocator(Locator locator) Deprecated. Receive a Locator object for document events.
void | startDocument() Deprecated. Receive notification of the beginning of the document.
void | startElement(String name, AttributeList attributes) Deprecated. Receive notification of the start of an element.
void | unparsedEntityDecl(String name, String publicId, String systemId, String notationName) Deprecated. Receive notification of an unparsed entity declaration.
void | warning(SAXParseException e) Deprecated. Receive notification of a parser warning.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HandlerBase

public HandlerBase()
Deprecated.
Method Detail

resolveEntity

public InputSource resolveEntity(String publicId,
                                 String systemId)
                          throws SAXException
Deprecated.
Resolve an external entity.

Always return null, so that the parser will use the system identifier provided in the XML document. This method implements the SAX default behaviour: application writers can override it in a subclass to do special translations such as catalog lookups or URI redirection.

Specified by:
resolveEntity in interface EntityResolver
Parameters:
publicId - The public identifer, or null if none is available.
systemId - The system identifier provided in the XML document.
Returns:
The new input source, or null to require the default behaviour.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
EntityResolver.resolveEntity(java.lang.String, java.lang.String)

notationDecl

public void notationDecl(String name,
                         String publicId,
                         String systemId)
Deprecated.
Receive notification of a notation declaration.

By default, do nothing. Application writers may override this method in a subclass if they wish to keep track of the notations declared in a document.

Specified by:
notationDecl in interface DTDHandler
Parameters:
name - The notation name.
publicId - The notation public identifier, or null if not available.
systemId - The notation system identifier.
See Also:
DTDHandler.notationDecl(java.lang.String, java.lang.String, java.lang.String)

unparsedEntityDecl

public void unparsedEntityDecl(String name,
                               String publicId,
                               String systemId,
                               String notationName)
Deprecated.
Receive notification of an unparsed entity declaration.

By default, do nothing. Application writers may override this method in a subclass to keep track of the unparsed entities declared in a document.

Specified by:
unparsedEntityDecl in interface DTDHandler
Parameters:
name - The entity name.
publicId - The entity public identifier, or null if not available.
systemId - The entity system identifier.
notationName - The name of the associated notation.
See Also:
DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String)

setDocumentLocator

public void setDocumentLocator(Locator locator)
Deprecated.
Receive a Locator object for document events.

By default, do nothing. Application writers may override this method in a subclass if they wish to store the locator for use with other document events.

Specified by:
setDocumentLocator in interface DocumentHandler
Parameters:
locator - A locator for all SAX document events.
See Also:
DocumentHandler.setDocumentLocator(org.xml.sax.Locator), Locator

startDocument

public void startDocument()
                   throws SAXException
Deprecated.
Receive notification of the beginning of the document.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the beginning of a document (such as allocating the root node of a tree or creating an output file).

Specified by:
startDocument in interface DocumentHandler
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
DocumentHandler.startDocument()

endDocument

public void endDocument()
                 throws SAXException
Deprecated.
Receive notification of the end of the document.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the end of a document (such as finalising a tree or closing an output file).

Specified by:
endDocument in interface DocumentHandler
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
DocumentHandler.endDocument()

startElement

public void startElement(String name,
                         AttributeList attributes)
                  throws SAXException
Deprecated.
Receive notification of the start of an element.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the start of each element (such as allocating a new tree node or writing output to a file).

Specified by:
startElement in interface DocumentHandler
Parameters:
name - The element type name.
attributes - The specified or defaulted attributes.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
DocumentHandler.startElement(java.lang.String, org.xml.sax.AttributeList)

endElement

public void endElement(String name)
                throws SAXException
Deprecated.
Receive notification of the end of an element.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the end of each element (such as finalising a tree node or writing output to a file).

Specified by:
endElement in interface DocumentHandler
Parameters:
name - the element name
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
DocumentHandler.endElement(java.lang.String)

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws SAXException
Deprecated.
Receive notification of character data inside an element.

By default, do nothing. Application writers may override this method to take specific actions for each chunk of character data (such as adding the data to a node or buffer, or printing it to a file).

Specified by:
characters in interface DocumentHandler
Parameters:
ch - The characters.
start - The start position in the character array.
length - The number of characters to use from the character array.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
DocumentHandler.characters(char[], int, int)

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws SAXException
Deprecated.
Receive notification of ignorable whitespace in element content.

By default, do nothing. Application writers may override this method to take specific actions for each chunk of ignorable whitespace (such as adding data to a node or buffer, or printing it to a file).

Specified by:
ignorableWhitespace in interface DocumentHandler
Parameters:
ch - The whitespace characters.
start - The start position in the character array.
length - The number of characters to use from the character array.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
DocumentHandler.ignorableWhitespace(char[], int, int)

processingInstruction

public void processingInstruction(String target,
                                  String data)
                           throws SAXException
Deprecated.
Receive notification of a processing instruction.

By default, do nothing. Application writers may override this method in a subclass to take specific actions for each processing instruction, such as setting status variables or invoking other methods.

Specified by:
processingInstruction in interface DocumentHandler
Parameters:
target - The processing instruction target.
data - The processing instruction data, or null if none is supplied.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
DocumentHandler.processingInstruction(java.lang.String, java.lang.String)

warning

public void warning(SAXParseException e)
             throws SAXException
Deprecated.
Receive notification of a parser warning.

The default implementation does nothing. Application writers may override this method in a subclass to take specific actions for each warning, such as inserting the message in a log file or printing it to the console.

Specified by:
warning in interface ErrorHandler
Parameters:
e - The warning information encoded as an exception.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ErrorHandler.warning(org.xml.sax.SAXParseException), SAXParseException

error

public void error(SAXParseException e)
           throws SAXException
Deprecated.
Receive notification of a recoverable parser error.

The default implementation does nothing. Application writers may override this method in a subclass to take specific actions for each error, such as inserting the message in a log file or printing it to the console.

Specified by:
error in interface ErrorHandler
Parameters:
e - The warning information encoded as an exception.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ErrorHandler.warning(org.xml.sax.SAXParseException), SAXParseException

fatalError

public void fatalError(SAXParseException e)
                throws SAXException
Deprecated.
Report a fatal XML parsing error.

The default implementation throws a SAXParseException. Application writers may override this method in a subclass if they need to take specific actions for each fatal error (such as collecting all of the errors into a single report): in any case, the application must stop all regular processing when this method is invoked, since the document is no longer reliable, and the parser may no longer report parsing events.

Specified by:
fatalError in interface ErrorHandler
Parameters:
e - The error information encoded as an exception.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ErrorHandler.fatalError(org.xml.sax.SAXParseException), SAXParseException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


helpers

PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package org.xml.sax.helpers

This package contains "helper" classes, including support for bootstrapping SAX-based applications.

See:
Description

Class Summary
AttributeListImpl | Deprecated. This class implements a deprecated interface, AttributeList; that interface has been replaced by Attributes, which is implemented in the AttributesImpl helper class.
AttributesImpl | Default implementation of the Attributes interface.
DefaultHandler | Default base class for SAX2 event handlers.
LocatorImpl | Provide an optional convenience implementation of Locator.
NamespaceSupport | Encapsulate Namespace logic for use by applications using SAX, or internally by SAX drivers.
ParserAdapter | Adapt a SAX1 Parser as a SAX2 XMLReader.
ParserFactory | Deprecated. This class works with the deprecated Parser interface.
XMLFilterImpl | Base class for deriving an XML filter.
XMLReaderAdapter | Adapt a SAX2 XMLReader as a SAX1 Parser.
XMLReaderFactory | Factory for creating an XML reader.

Package org.xml.sax.helpers Description

This package contains "helper" classes, including support for bootstrapping SAX-based applications.

See http://www.saxproject.org for more information about SAX.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


org.xml.sax.helpers Class Hierarchy

PREV NEXT FRAMES NO FRAMES

Hierarchy For Package org.xml.sax.helpers

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • org.xml.sax.helpers.AttributeListImpl (implements org.xml.sax.AttributeList)
    • org.xml.sax.helpers.AttributesImpl (implements org.xml.sax.Attributes)
    • org.xml.sax.helpers.DefaultHandler (implements org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler)
    • org.xml.sax.helpers.LocatorImpl (implements org.xml.sax.Locator)
    • org.xml.sax.helpers.NamespaceSupport
    • org.xml.sax.helpers.ParserAdapter (implements org.xml.sax.DocumentHandler, org.xml.sax.XMLReader)
    • org.xml.sax.helpers.ParserFactory
    • org.xml.sax.helpers.XMLFilterImpl (implements org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler, org.xml.sax.XMLFilter)
    • org.xml.sax.helpers.XMLReaderAdapter (implements org.xml.sax.ContentHandler, org.xml.sax.Parser)
    • org.xml.sax.helpers.XMLReaderFactory
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Package org.xml.sax.helpers

PREV NEXT FRAMES NO FRAMES

Uses of Package
org.xml.sax.helpers

Packages that use org.xml.sax.helpers
javax.xml.parsers | Provides classes allowing the processing of XML documents.
org.xml.sax.ext | This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.

Classes in org.xml.sax.helpers used by javax.xml.parsers
DefaultHandler
Default base class for SAX2 event handlers.

Classes in org.xml.sax.helpers used by org.xml.sax.ext
AttributesImpl
Default implementation of the Attributes interface.
DefaultHandler
Default base class for SAX2 event handlers.
LocatorImpl
Provide an optional convenience implementation of Locator.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


AttributeListImpl

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.helpers
Class AttributeListImpl

java.lang.Object
    extended by  org.xml.sax.helpers.AttributeListImpl
All Implemented Interfaces:
AttributeList
Deprecated. This class implements a deprecated interface, AttributeList; that interface has been replaced by Attributes, which is implemented in the AttributesImpl helper class.

public class AttributeListImpl
extends Object
implements AttributeList

Default implementation for AttributeList.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

AttributeList implements the deprecated SAX1 AttributeList interface, and has been replaced by the new SAX2 AttributesImpl interface.

This class provides a convenience implementation of the SAX AttributeList interface. This implementation is useful both for SAX parser writers, who can use it to provide attributes to the application, and for SAX application writers, who can use it to create a persistent copy of an element's attribute specifications:

 private AttributeList myatts;

 public void startElement (String name, AttributeList atts)
 {
              // create a persistent copy of the attribute list
              // for use outside this method
   myatts = new AttributeListImpl(atts);
   [...]
 }

Please note that SAX parsers are not required to use this class to provide an implementation of AttributeList; it is supplied only as an optional convenience. In particular, parser writers are encouraged to invent more efficient implementations.

Since:
SAX 1.0
See Also:
AttributeList, DocumentHandler.startElement(java.lang.String, org.xml.sax.AttributeList)

Constructor Summary
AttributeListImpl()
Deprecated. Create an empty attribute list.
AttributeListImpl(AttributeList atts)
Deprecated. Construct a persistent copy of an existing attribute list.
Method Summary
void | addAttribute(String name, String type, String value) Deprecated. Add an attribute to an attribute list.
void | clear() Deprecated. Clear the attribute list.
int | getLength() Deprecated. Return the number of attributes in the list.
String | getName(int i) Deprecated. Get the name of an attribute (by position).
String | getType(int i) Deprecated. Get the type of an attribute (by position).
String | getType(String name) Deprecated. Get the type of an attribute (by name).
String | getValue(int i) Deprecated. Get the value of an attribute (by position).
String | getValue(String name) Deprecated. Get the value of an attribute (by name).
void | removeAttribute(String name) Deprecated. Remove an attribute from the list.
void | setAttributeList(AttributeList atts) Deprecated. Set the attribute list, discarding previous contents.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AttributeListImpl

public AttributeListImpl()
Deprecated.
Create an empty attribute list.

This constructor is most useful for parser writers, who will use it to create a single, reusable attribute list that can be reset with the clear method between elements.

See Also:
addAttribute(java.lang.String, java.lang.String, java.lang.String), clear()

AttributeListImpl

public AttributeListImpl(AttributeList atts)
Deprecated.
Construct a persistent copy of an existing attribute list.

This constructor is most useful for application writers, who will use it to create a persistent copy of an existing attribute list.

Parameters:
atts - The attribute list to copy
See Also:
DocumentHandler.startElement(java.lang.String, org.xml.sax.AttributeList)
Method Detail

setAttributeList

public void setAttributeList(AttributeList atts)
Deprecated.
Set the attribute list, discarding previous contents.

This method allows an application writer to reuse an attribute list easily.

Parameters:
atts - The attribute list to copy.

addAttribute

public void addAttribute(String name,
                         String type,
                         String value)
Deprecated.
Add an attribute to an attribute list.

This method is provided for SAX parser writers, to allow them to build up an attribute list incrementally before delivering it to the application.

Parameters:
name - The attribute name.
type - The attribute type ("NMTOKEN" for an enumeration).
value - The attribute value (must not be null).
See Also:
removeAttribute(java.lang.String), DocumentHandler.startElement(java.lang.String, org.xml.sax.AttributeList)

removeAttribute

public void removeAttribute(String name)
Deprecated.
Remove an attribute from the list.

SAX application writers can use this method to filter an attribute out of an AttributeList. Note that invoking this method will change the length of the attribute list and some of the attribute's indices.

If the requested attribute is not in the list, this is a no-op.

Parameters:
name - The attribute name.
See Also:
addAttribute(java.lang.String, java.lang.String, java.lang.String)

clear

public void clear()
Deprecated.
Clear the attribute list.

SAX parser writers can use this method to reset the attribute list between DocumentHandler.startElement events. Normally, it will make sense to reuse the same AttributeListImpl object rather than allocating a new one each time.

See Also:
DocumentHandler.startElement(java.lang.String, org.xml.sax.AttributeList)

getLength

public int getLength()
Deprecated.
Return the number of attributes in the list.

Specified by:
getLength in interface AttributeList
Returns:
The number of attributes in the list.
See Also:
AttributeList.getLength()

getName

public String getName(int i)
Deprecated.
Get the name of an attribute (by position).

Specified by:
getName in interface AttributeList
Parameters:
i - The position of the attribute in the list.
Returns:
The attribute name as a string, or null if there is no attribute at that position.
See Also:
AttributeList.getName(int)

getType

public String getType(int i)
Deprecated.
Get the type of an attribute (by position).

Specified by:
getType in interface AttributeList
Parameters:
i - The position of the attribute in the list.
Returns:
The attribute type as a string ("NMTOKEN" for an enumeration, and "CDATA" if no declaration was read), or null if there is no attribute at that position.
See Also:
AttributeList.getType(int)

getValue

public String getValue(int i)
Deprecated.
Get the value of an attribute (by position).

Specified by:
getValue in interface AttributeList
Parameters:
i - The position of the attribute in the list.
Returns:
The attribute value as a string, or null if there is no attribute at that position.
See Also:
AttributeList.getValue(int)

getType

public String getType(String name)
Deprecated.
Get the type of an attribute (by name).

Specified by:
getType in interface AttributeList
Parameters:
name - The attribute name.
Returns:
The attribute type as a string ("NMTOKEN" for an enumeration, and "CDATA" if no declaration was read).
See Also:
AttributeList.getType(java.lang.String)

getValue

public String getValue(String name)
Deprecated.
Get the value of an attribute (by name).

Specified by:
getValue in interface AttributeList
Parameters:
name - The attribute name.
Returns:
The attribute value as a string, or null if no such attribute exists.
See Also:
AttributeList.getValue(java.lang.String)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AttributesImpl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.helpers
Class AttributesImpl

java.lang.Object
    extended by  org.xml.sax.helpers.AttributesImpl
All Implemented Interfaces:
Attributes
Direct Known Subclasses:
Attributes2Impl
public class AttributesImpl
extends Object
implements Attributes

Default implementation of the Attributes interface.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This class provides a default implementation of the SAX2 Attributes interface, with the addition of manipulators so that the list can be modified or reused.

There are two typical uses of this class:

  1. to take a persistent snapshot of an Attributes object in a startElement event; or
  2. to construct or modify an Attributes object in a SAX2 driver or filter.

This class replaces the now-deprecated SAX1 AttributeListImpl class; in addition to supporting the updated Attributes interface rather than the deprecated AttributeList interface, it also includes a much more efficient implementation using a single array rather than a set of Vectors.

Since:
SAX 2.0

Constructor Summary
AttributesImpl()
Construct a new, empty AttributesImpl object.
AttributesImpl(Attributes atts)
Copy an existing Attributes object.
Method Summary
void | addAttribute(String uri, String localName, String qName, String type, String value) Add an attribute to the end of the list.
void | clear() Clear the attribute list for reuse.
int | getIndex(String qName) Look up an attribute's index by qualified (prefixed) name.
int | getIndex(String uri, String localName) Look up an attribute's index by Namespace name.
int | getLength() Return the number of attributes in the list.
String | getLocalName(int index) Return an attribute's local name.
String | getQName(int index) Return an attribute's qualified (prefixed) name.
String | getType(int index) Return an attribute's type by index.
String | getType(String qName) Look up an attribute's type by qualified (prefixed) name.
String | getType(String uri, String localName) Look up an attribute's type by Namespace-qualified name.
String | getURI(int index) Return an attribute's Namespace URI.
String | getValue(int index) Return an attribute's value by index.
String | getValue(String qName) Look up an attribute's value by qualified (prefixed) name.
String | getValue(String uri, String localName) Look up an attribute's value by Namespace-qualified name.
void | removeAttribute(int index) Remove an attribute from the list.
void | setAttribute(int index, String uri, String localName, String qName, String type, String value) Set an attribute in the list.
void | setAttributes(Attributes atts) Copy an entire Attributes object.
void | setLocalName(int index, String localName) Set the local name of a specific attribute.
void | setQName(int index, String qName) Set the qualified name of a specific attribute.
void | setType(int index, String type) Set the type of a specific attribute.
void | setURI(int index, String uri) Set the Namespace URI of a specific attribute.
void | setValue(int index, String value) Set the value of a specific attribute.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AttributesImpl

public AttributesImpl()
Construct a new, empty AttributesImpl object.

AttributesImpl

public AttributesImpl(Attributes atts)
Copy an existing Attributes object.

This constructor is especially useful inside a startElement event.

Parameters:
atts - The existing Attributes object.
Method Detail

getLength

public int getLength()
Return the number of attributes in the list.

Specified by:
getLength in interface Attributes
Returns:
The number of attributes in the list.
See Also:
Attributes.getLength()

getURI

public String getURI(int index)
Return an attribute's Namespace URI.

Specified by:
getURI in interface Attributes
Parameters:
index - The attribute's index (zero-based).
Returns:
The Namespace URI, the empty string if none is available, or null if the index is out of range.
See Also:
Attributes.getURI(int)

getLocalName

public String getLocalName(int index)
Return an attribute's local name.

Specified by:
getLocalName in interface Attributes
Parameters:
index - The attribute's index (zero-based).
Returns:
The attribute's local name, the empty string if none is available, or null if the index if out of range.
See Also:
Attributes.getLocalName(int)

getQName

public String getQName(int index)
Return an attribute's qualified (prefixed) name.

Specified by:
getQName in interface Attributes
Parameters:
index - The attribute's index (zero-based).
Returns:
The attribute's qualified name, the empty string if none is available, or null if the index is out of bounds.
See Also:
Attributes.getQName(int)

getType

public String getType(int index)
Return an attribute's type by index.

Specified by:
getType in interface Attributes
Parameters:
index - The attribute's index (zero-based).
Returns:
The attribute's type, "CDATA" if the type is unknown, or null if the index is out of bounds.
See Also:
Attributes.getType(int)

getValue

public String getValue(int index)
Return an attribute's value by index.

Specified by:
getValue in interface Attributes
Parameters:
index - The attribute's index (zero-based).
Returns:
The attribute's value or null if the index is out of bounds.
See Also:
Attributes.getValue(int)

getIndex

public int getIndex(String uri,
                    String localName)
Look up an attribute's index by Namespace name.

In many cases, it will be more efficient to look up the name once and use the index query methods rather than using the name query methods repeatedly.

Specified by:
getIndex in interface Attributes
Parameters:
uri - The attribute's Namespace URI, or the empty string if none is available.
localName - The attribute's local name.
Returns:
The attribute's index, or -1 if none matches.
See Also:
Attributes.getIndex(java.lang.String,java.lang.String)

getIndex

public int getIndex(String qName)
Look up an attribute's index by qualified (prefixed) name.

Specified by:
getIndex in interface Attributes
Parameters:
qName - The qualified name.
Returns:
The attribute's index, or -1 if none matches.
See Also:
Attributes.getIndex(java.lang.String)

getType

public String getType(String uri,
                      String localName)
Look up an attribute's type by Namespace-qualified name.

Specified by:
getType in interface Attributes
Parameters:
uri - The Namespace URI, or the empty string for a name with no explicit Namespace URI.
localName - The local name.
Returns:
The attribute's type, or null if there is no matching attribute.
See Also:
Attributes.getType(java.lang.String,java.lang.String)

getType

public String getType(String qName)
Look up an attribute's type by qualified (prefixed) name.

Specified by:
getType in interface Attributes
Parameters:
qName - The qualified name.
Returns:
The attribute's type, or null if there is no matching attribute.
See Also:
Attributes.getType(java.lang.String)

getValue

public String getValue(String uri,
                       String localName)
Look up an attribute's value by Namespace-qualified name.

Specified by:
getValue in interface Attributes
Parameters:
uri - The Namespace URI, or the empty string for a name with no explicit Namespace URI.
localName - The local name.
Returns:
The attribute's value, or null if there is no matching attribute.
See Also:
Attributes.getValue(java.lang.String,java.lang.String)

getValue

public String getValue(String qName)
Look up an attribute's value by qualified (prefixed) name.

Specified by:
getValue in interface Attributes
Parameters:
qName - The qualified name.
Returns:
The attribute's value, or null if there is no matching attribute.
See Also:
Attributes.getValue(java.lang.String)

clear

public void clear()
Clear the attribute list for reuse.

Note that little memory is freed by this call: the current array is kept so it can be reused.

setAttributes

public void setAttributes(Attributes atts)
Copy an entire Attributes object.

It may be more efficient to reuse an existing object rather than constantly allocating new ones.

Parameters:
atts - The attributes to copy.

addAttribute

public void addAttribute(String uri,
                         String localName,
                         String qName,
                         String type,
                         String value)
Add an attribute to the end of the list.

For the sake of speed, this method does no checking to see if the attribute is already in the list: that is the responsibility of the application.

Parameters:
uri - The Namespace URI, or the empty string if none is available or Namespace processing is not being performed.
localName - The local name, or the empty string if Namespace processing is not being performed.
qName - The qualified (prefixed) name, or the empty string if qualified names are not available.
type - The attribute type as a string.
value - The attribute value.

setAttribute

public void setAttribute(int index,
                         String uri,
                         String localName,
                         String qName,
                         String type,
                         String value)
Set an attribute in the list.

For the sake of speed, this method does no checking for name conflicts or well-formedness: such checks are the responsibility of the application.

Parameters:
index - The index of the attribute (zero-based).
uri - The Namespace URI, or the empty string if none is available or Namespace processing is not being performed.
localName - The local name, or the empty string if Namespace processing is not being performed.
qName - The qualified name, or the empty string if qualified names are not available.
type - The attribute type as a string.
value - The attribute value.
Throws:
ArrayIndexOutOfBoundsException - When the supplied index does not point to an attribute in the list.

removeAttribute

public void removeAttribute(int index)
Remove an attribute from the list.

Parameters:
index - The index of the attribute (zero-based).
Throws:
ArrayIndexOutOfBoundsException - When the supplied index does not point to an attribute in the list.

setURI

public void setURI(int index,
                   String uri)
Set the Namespace URI of a specific attribute.

Parameters:
index - The index of the attribute (zero-based).
uri - The attribute's Namespace URI, or the empty string for none.
Throws:
ArrayIndexOutOfBoundsException - When the supplied index does not point to an attribute in the list.

setLocalName

public void setLocalName(int index,
                         String localName)
Set the local name of a specific attribute.

Parameters:
index - The index of the attribute (zero-based).
localName - The attribute's local name, or the empty string for none.
Throws:
ArrayIndexOutOfBoundsException - When the supplied index does not point to an attribute in the list.

setQName

public void setQName(int index,
                     String qName)
Set the qualified name of a specific attribute.

Parameters:
index - The index of the attribute (zero-based).
qName - The attribute's qualified name, or the empty string for none.
Throws:
ArrayIndexOutOfBoundsException - When the supplied index does not point to an attribute in the list.

setType

public void setType(int index,
                    String type)
Set the type of a specific attribute.

Parameters:
index - The index of the attribute (zero-based).
type - The attribute's type.
Throws:
ArrayIndexOutOfBoundsException - When the supplied index does not point to an attribute in the list.

setValue

public void setValue(int index,
                     String value)
Set the value of a specific attribute.

Parameters:
index - The index of the attribute (zero-based).
value - The attribute's value.
Throws:
ArrayIndexOutOfBoundsException - When the supplied index does not point to an attribute in the list.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class org.xml.sax.helpers.AttributeListImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.helpers.AttributeListImpl

No usage of org.xml.sax.helpers.AttributeListImpl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.xml.sax.helpers.AttributesImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.helpers.AttributesImpl

Packages that use AttributesImpl
org.xml.sax.ext This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.

Uses of AttributesImpl in org.xml.sax.ext

Subclasses of AttributesImpl in org.xml.sax.ext
 class Attributes2Impl
SAX2 extension helper for additional Attributes information, implementing the Attributes2 interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.xml.sax.helpers.DefaultHandler

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.helpers.DefaultHandler

Packages that use DefaultHandler
javax.xml.parsers | Provides classes allowing the processing of XML documents.
org.xml.sax.ext | This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.

Uses of DefaultHandler in javax.xml.parsers

Methods in javax.xml.parsers with parameters of type DefaultHandler
void | SAXParser.parse(File f, DefaultHandler dh) Parse the content of the file specified as XML using the specified DefaultHandler.
void | SAXParser.parse(InputSource is, DefaultHandler dh) Parse the content given InputSource as XML using the specified DefaultHandler.
void | SAXParser.parse(InputStream is, DefaultHandler dh) Parse the content of the given InputStream instance as XML using the specified DefaultHandler.
void | SAXParser.parse(InputStream is, DefaultHandler dh, String systemId) Parse the content of the given InputStream instance as XML using the specified DefaultHandler.
void | SAXParser.parse(String uri, DefaultHandler dh) Parse the content described by the giving Uniform Resource Identifier (URI) as XML using the specified DefaultHandler.

Uses of DefaultHandler in org.xml.sax.ext

Subclasses of DefaultHandler in org.xml.sax.ext
 class DefaultHandler2
This class extends the SAX2 base handler class to support the SAX2 LexicalHandler, DeclHandler, and EntityResolver2 extensions.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.xml.sax.helpers.LocatorImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.helpers.LocatorImpl

Packages that use LocatorImpl
org.xml.sax.ext This package contains interfaces to SAX2 facilities that conformant SAX drivers won't necessarily support.

Uses of LocatorImpl in org.xml.sax.ext

Subclasses of LocatorImpl in org.xml.sax.ext
 class Locator2Impl
SAX2 extension helper for holding additional Entity information, implementing the Locator2 interface.

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.xml.sax.helpers.NamespaceSupport

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.helpers.NamespaceSupport

No usage of org.xml.sax.helpers.NamespaceSupport

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.xml.sax.helpers.ParserAdapter

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.helpers.ParserAdapter

No usage of org.xml.sax.helpers.ParserAdapter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.xml.sax.helpers.ParserFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.helpers.ParserFactory

No usage of org.xml.sax.helpers.ParserFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.xml.sax.helpers.XMLFilterImpl

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.helpers.XMLFilterImpl

No usage of org.xml.sax.helpers.XMLFilterImpl

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.xml.sax.helpers.XMLReaderAdapter

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.helpers.XMLReaderAdapter

No usage of org.xml.sax.helpers.XMLReaderAdapter

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


Uses of Class org.xml.sax.helpers.XMLReaderFactory

PREV NEXT FRAMES NO FRAMES

Uses of Class
org.xml.sax.helpers.XMLReaderFactory

No usage of org.xml.sax.helpers.XMLReaderFactory

Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV NEXT FRAMES NO FRAMES


DefaultHandler

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.helpers
Class DefaultHandler

java.lang.Object
    extended by  org.xml.sax.helpers.DefaultHandler
All Implemented Interfaces:
ContentHandler, DTDHandler, EntityResolver, ErrorHandler
Direct Known Subclasses:
DefaultHandler2
public class DefaultHandler
extends Object
implements EntityResolver, DTDHandler, ContentHandler, ErrorHandler

Default base class for SAX2 event handlers.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This class is available as a convenience base class for SAX2 applications: it provides default implementations for all of the callbacks in the four core SAX2 handler classes:

  • EntityResolver
  • DTDHandler
  • ContentHandler
  • ErrorHandler

Application writers can extend this class when they need to implement only part of an interface; parser writers can instantiate this class to provide default handlers when the application has not supplied its own.

This class replaces the deprecated SAX1 HandlerBase class.

Since:
SAX 2.0
See Also:
EntityResolver, DTDHandler, ContentHandler, ErrorHandler

Constructor Summary
DefaultHandler()
Method Summary
void | characters(char[] ch, int start, int length) Receive notification of character data inside an element.
void | endDocument() Receive notification of the end of the document.
void | endElement(String uri, String localName, String qName) Receive notification of the end of an element.
void | endPrefixMapping(String prefix) Receive notification of the end of a Namespace mapping.
void | error(SAXParseException e) Receive notification of a recoverable parser error.
void | fatalError(SAXParseException e) Report a fatal XML parsing error.
void | ignorableWhitespace(char[] ch, int start, int length) Receive notification of ignorable whitespace in element content.
void | notationDecl(String name, String publicId, String systemId) Receive notification of a notation declaration.
void | processingInstruction(String target, String data) Receive notification of a processing instruction.
InputSource | resolveEntity(String publicId, String systemId) Resolve an external entity.
void | setDocumentLocator(Locator locator) Receive a Locator object for document events.
void | skippedEntity(String name) Receive notification of a skipped entity.
void | startDocument() Receive notification of the beginning of the document.
void | startElement(String uri, String localName, String qName, Attributes attributes) Receive notification of the start of an element.
void | startPrefixMapping(String prefix, String uri) Receive notification of the start of a Namespace mapping.
void | unparsedEntityDecl(String name, String publicId, String systemId, String notationName) Receive notification of an unparsed entity declaration.
void | warning(SAXParseException e) Receive notification of a parser warning.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultHandler

public DefaultHandler()
Method Detail

resolveEntity

public InputSource resolveEntity(String publicId,
                                 String systemId)
                          throws IOException,
                                 SAXException
Resolve an external entity.

Always return null, so that the parser will use the system identifier provided in the XML document. This method implements the SAX default behaviour: application writers can override it in a subclass to do special translations such as catalog lookups or URI redirection.

Specified by:
resolveEntity in interface EntityResolver
Parameters:
publicId - The public identifier, or null if none is available.
systemId - The system identifier provided in the XML document.
Returns:
The new input source, or null to require the default behaviour.
Throws:
IOException - If there is an error setting up the new input source.
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
EntityResolver.resolveEntity(java.lang.String, java.lang.String)

notationDecl

public void notationDecl(String name,
                         String publicId,
                         String systemId)
                  throws SAXException
Receive notification of a notation declaration.

By default, do nothing. Application writers may override this method in a subclass if they wish to keep track of the notations declared in a document.

Specified by:
notationDecl in interface DTDHandler
Parameters:
name - The notation name.
publicId - The notation public identifier, or null if not available.
systemId - The notation system identifier.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
DTDHandler.notationDecl(java.lang.String, java.lang.String, java.lang.String)

unparsedEntityDecl

public void unparsedEntityDecl(String name,
                               String publicId,
                               String systemId,
                               String notationName)
                        throws SAXException
Receive notification of an unparsed entity declaration.

By default, do nothing. Application writers may override this method in a subclass to keep track of the unparsed entities declared in a document.

Specified by:
unparsedEntityDecl in interface DTDHandler
Parameters:
name - The entity name.
publicId - The entity public identifier, or null if not available.
systemId - The entity system identifier.
notationName - The name of the associated notation.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String)

setDocumentLocator

public void setDocumentLocator(Locator locator)
Receive a Locator object for document events.

By default, do nothing. Application writers may override this method in a subclass if they wish to store the locator for use with other document events.

Specified by:
setDocumentLocator in interface ContentHandler
Parameters:
locator - A locator for all SAX document events.
See Also:
ContentHandler.setDocumentLocator(org.xml.sax.Locator), Locator

startDocument

public void startDocument()
                   throws SAXException
Receive notification of the beginning of the document.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the beginning of a document (such as allocating the root node of a tree or creating an output file).

Specified by:
startDocument in interface ContentHandler
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ContentHandler.startDocument()

endDocument

public void endDocument()
                 throws SAXException
Receive notification of the end of the document.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the end of a document (such as finalising a tree or closing an output file).

Specified by:
endDocument in interface ContentHandler
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ContentHandler.endDocument()

startPrefixMapping

public void startPrefixMapping(String prefix,
                               String uri)
                        throws SAXException
Receive notification of the start of a Namespace mapping.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the start of each Namespace prefix scope (such as storing the prefix mapping).

Specified by:
startPrefixMapping in interface ContentHandler
Parameters:
prefix - The Namespace prefix being declared.
uri - The Namespace URI mapped to the prefix.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ContentHandler.startPrefixMapping(java.lang.String, java.lang.String)

endPrefixMapping

public void endPrefixMapping(String prefix)
                      throws SAXException
Receive notification of the end of a Namespace mapping.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the end of each prefix mapping.

Specified by:
endPrefixMapping in interface ContentHandler
Parameters:
prefix - The Namespace prefix being declared.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ContentHandler.endPrefixMapping(java.lang.String)

startElement

public void startElement(String uri,
                         String localName,
                         String qName,
                         Attributes attributes)
                  throws SAXException
Receive notification of the start of an element.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the start of each element (such as allocating a new tree node or writing output to a file).

Specified by:
startElement in interface ContentHandler
Parameters:
uri - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
localName - The local name (without prefix), or the empty string if Namespace processing is not being performed.
qName - The qualified name (with prefix), or the empty string if qualified names are not available.
attributes - The attributes attached to the element. If there are no attributes, it shall be an empty Attributes object.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ContentHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)

endElement

public void endElement(String uri,
                       String localName,
                       String qName)
                throws SAXException
Receive notification of the end of an element.

By default, do nothing. Application writers may override this method in a subclass to take specific actions at the end of each element (such as finalising a tree node or writing output to a file).

Specified by:
endElement in interface ContentHandler
Parameters:
uri - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
localName - The local name (without prefix), or the empty string if Namespace processing is not being performed.
qName - The qualified name (with prefix), or the empty string if qualified names are not available.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String)

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws SAXException
Receive notification of character data inside an element.

By default, do nothing. Application writers may override this method to take specific actions for each chunk of character data (such as adding the data to a node or buffer, or printing it to a file).

Specified by:
characters in interface ContentHandler
Parameters:
ch - The characters.
start - The start position in the character array.
length - The number of characters to use from the character array.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ContentHandler.characters(char[], int, int)

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws SAXException
Receive notification of ignorable whitespace in element content.

By default, do nothing. Application writers may override this method to take specific actions for each chunk of ignorable whitespace (such as adding data to a node or buffer, or printing it to a file).

Specified by:
ignorableWhitespace in interface ContentHandler
Parameters:
ch - The whitespace characters.
start - The start position in the character array.
length - The number of characters to use from the character array.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ContentHandler.ignorableWhitespace(char[], int, int)

processingInstruction

public void processingInstruction(String target,
                                  String data)
                           throws SAXException
Receive notification of a processing instruction.

By default, do nothing. Application writers may override this method in a subclass to take specific actions for each processing instruction, such as setting status variables or invoking other methods.

Specified by:
processingInstruction in interface ContentHandler
Parameters:
target - The processing instruction target.
data - The processing instruction data, or null if none is supplied.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ContentHandler.processingInstruction(java.lang.String, java.lang.String)

skippedEntity

public void skippedEntity(String name)
                   throws SAXException
Receive notification of a skipped entity.

By default, do nothing. Application writers may override this method in a subclass to take specific actions for each processing instruction, such as setting status variables or invoking other methods.

Specified by:
skippedEntity in interface ContentHandler
Parameters:
name - The name of the skipped entity.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ContentHandler.processingInstruction(java.lang.String, java.lang.String)

warning

public void warning(SAXParseException e)
             throws SAXException
Receive notification of a parser warning.

The default implementation does nothing. Application writers may override this method in a subclass to take specific actions for each warning, such as inserting the message in a log file or printing it to the console.

Specified by:
warning in interface ErrorHandler
Parameters:
e - The warning information encoded as an exception.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ErrorHandler.warning(org.xml.sax.SAXParseException), SAXParseException

error

public void error(SAXParseException e)
           throws SAXException
Receive notification of a recoverable parser error.

The default implementation does nothing. Application writers may override this method in a subclass to take specific actions for each error, such as inserting the message in a log file or printing it to the console.

Specified by:
error in interface ErrorHandler
Parameters:
e - The error information encoded as an exception.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ErrorHandler.warning(org.xml.sax.SAXParseException), SAXParseException

fatalError

public void fatalError(SAXParseException e)
                throws SAXException
Report a fatal XML parsing error.

The default implementation throws a SAXParseException. Application writers may override this method in a subclass if they need to take specific actions for each fatal error (such as collecting all of the errors into a single report): in any case, the application must stop all regular processing when this method is invoked, since the document is no longer reliable, and the parser may no longer report parsing events.

Specified by:
fatalError in interface ErrorHandler
Parameters:
e - The error information encoded as an exception.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
See Also:
ErrorHandler.fatalError(org.xml.sax.SAXParseException), SAXParseException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LocatorImpl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.helpers
Class LocatorImpl

java.lang.Object
    extended by  org.xml.sax.helpers.LocatorImpl
All Implemented Interfaces:
Locator
Direct Known Subclasses:
Locator2Impl
public class LocatorImpl
extends Object
implements Locator

Provide an optional convenience implementation of Locator.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This class is available mainly for application writers, who can use it to make a persistent snapshot of a locator at any point during a document parse:

 Locator locator;
 Locator startloc;

 public void setLocator (Locator locator)
 {
         // note the locator
   this.locator = locator;
 }

 public void startDocument ()
 {
         // save the location of the start of the document
         // for future use.
   Locator startloc = new LocatorImpl(locator);
 }

Normally, parser writers will not use this class, since it is more efficient to provide location information only when requested, rather than constantly updating a Locator object.

Since:
SAX 1.0
See Also:
Locator

Constructor Summary
LocatorImpl()
Zero-argument constructor.
LocatorImpl(Locator locator)
Copy constructor.
Method Summary
int | getColumnNumber() Return the saved column number (1-based).
int | getLineNumber() Return the saved line number (1-based).
String | getPublicId() Return the saved public identifier.
String | getSystemId() Return the saved system identifier.
void | setColumnNumber(int columnNumber) Set the column number for this locator (1-based).
void | setLineNumber(int lineNumber) Set the line number for this locator (1-based).
void | setPublicId(String publicId) Set the public identifier for this locator.
void | setSystemId(String systemId) Set the system identifier for this locator.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LocatorImpl

public LocatorImpl()
Zero-argument constructor.

This will not normally be useful, since the main purpose of this class is to make a snapshot of an existing Locator.

LocatorImpl

public LocatorImpl(Locator locator)
Copy constructor.

Create a persistent copy of the current state of a locator. When the original locator changes, this copy will still keep the original values (and it can be used outside the scope of DocumentHandler methods).

Parameters:
locator - The locator to copy.
Method Detail

getPublicId

public String getPublicId()
Return the saved public identifier.

Specified by:
getPublicId in interface Locator
Returns:
The public identifier as a string, or null if none is available.
See Also:
Locator.getPublicId(), setPublicId(java.lang.String)

getSystemId

public String getSystemId()
Return the saved system identifier.

Specified by:
getSystemId in interface Locator
Returns:
The system identifier as a string, or null if none is available.
See Also:
Locator.getSystemId(), setSystemId(java.lang.String)

getLineNumber

public int getLineNumber()
Return the saved line number (1-based).

Specified by:
getLineNumber in interface Locator
Returns:
The line number as an integer, or -1 if none is available.
See Also:
Locator.getLineNumber(), setLineNumber(int)

getColumnNumber

public int getColumnNumber()
Return the saved column number (1-based).

Specified by:
getColumnNumber in interface Locator
Returns:
The column number as an integer, or -1 if none is available.
See Also:
Locator.getColumnNumber(), setColumnNumber(int)

setPublicId

public void setPublicId(String publicId)
Set the public identifier for this locator.

Parameters:
publicId - The new public identifier, or null if none is available.
See Also:
getPublicId()

setSystemId

public void setSystemId(String systemId)
Set the system identifier for this locator.

Parameters:
systemId - The new system identifier, or null if none is available.
See Also:
getSystemId()

setLineNumber

public void setLineNumber(int lineNumber)
Set the line number for this locator (1-based).

Parameters:
lineNumber - The line number, or -1 if none is available.
See Also:
getLineNumber()

setColumnNumber

public void setColumnNumber(int columnNumber)
Set the column number for this locator (1-based).

Parameters:
columnNumber - The column number, or -1 if none is available.
See Also:
getColumnNumber()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NamespaceSupport

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.helpers
Class NamespaceSupport

java.lang.Object
    extended by  org.xml.sax.helpers.NamespaceSupport

public class NamespaceSupport
extends Object

Encapsulate Namespace logic for use by applications using SAX, or internally by SAX drivers.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This class encapsulates the logic of Namespace processing: it tracks the declarations currently in force for each context and automatically processes qualified XML names into their Namespace parts; it can also be used in reverse for generating XML qnames from Namespaces.

Namespace support objects are reusable, but the reset method must be invoked between each session.

Here is a simple session:

 String parts[] = new String[3];
 NamespaceSupport support = new NamespaceSupport();

 support.pushContext();
 support.declarePrefix("", "http://www.w3.org/1999/xhtml");
 support.declarePrefix("dc", "http://www.purl.org/dc#");

 parts = support.processName("p", parts, false);
 System.out.println("Namespace URI: " + parts[0]);
 System.out.println("Local name: " + parts[1]);
 System.out.println("Raw name: " + parts[2]);

 parts = support.processName("dc:title", parts, false);
 System.out.println("Namespace URI: " + parts[0]);
 System.out.println("Local name: " + parts[1]);
 System.out.println("Raw name: " + parts[2]);

 support.popContext();

Note that this class is optimized for the use case where most elements do not contain Namespace declarations: if the same prefix/URI mapping is repeated for each context (for example), this class will be somewhat less efficient.

Although SAX drivers (parsers) may choose to use this class to implement namespace handling, they are not required to do so. Applications must track namespace information themselves if they want to use namespace information.

Since:
SAX 2.0

Field Summary
static String | NSDECL The namespace declaration URI as a constant.
static String | XMLNS The XML Namespace URI as a constant.
Constructor Summary
NamespaceSupport()
Create a new Namespace support object.
Method Summary
 boolean declarePrefix(String prefix, String uri)
Declare a Namespace prefix.
 Enumeration getDeclaredPrefixes()
Return an enumeration of all prefixes declared in this context.
 String getPrefix(String uri)
Return one of the prefixes mapped to a Namespace URI.
 Enumeration getPrefixes()
Return an enumeration of all prefixes whose declarations are active in the current context.
 Enumeration getPrefixes(String uri)
Return an enumeration of all prefixes for a given URI whose declarations are active in the current context.
 String getURI(String prefix)
Look up a prefix and get the currently-mapped Namespace URI.
 boolean isNamespaceDeclUris()
Returns true if namespace declaration attributes are placed into a namespace.
 void popContext()
Revert to the previous Namespace context.
 String[] processName(String qName, String[] parts, boolean isAttribute)
Process a raw XML qualified name, after all declarations in the current context have been handled by declarePrefix().
 void pushContext()
Start a new Namespace context.
 void reset()
Reset this Namespace support object for reuse.
 void setNamespaceDeclUris(boolean value)
Controls whether namespace declaration attributes are placed into the NSDECL namespace by processName().
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

XMLNS

public static final String XMLNS
The XML Namespace URI as a constant. The value is http://www.w3.org/XML/1998/namespace as defined in the "Namespaces in XML" * recommendation.

This is the Namespace URI that is automatically mapped to the "xml" prefix.

See Also:
Constant Field Values

NSDECL

public static final String NSDECL
The namespace declaration URI as a constant. The value is http://www.w3.org/xmlns/2000/, as defined in a backwards-incompatible erratum to the "Namespaces in XML" recommendation. Because that erratum postdated SAX2, SAX2 defaults to the original recommendation, and does not normally use this URI.

This is the Namespace URI that is optionally applied to xmlns and xmlns:* attributes, which are used to declare namespaces.

Since:
SAX 2.1alpha
See Also:
setNamespaceDeclUris(boolean), isNamespaceDeclUris(), Constant Field Values
Constructor Detail

NamespaceSupport

public NamespaceSupport()
Create a new Namespace support object.

Method Detail

reset

public void reset()
Reset this Namespace support object for reuse.

It is necessary to invoke this method before reusing the Namespace support object for a new session. If namespace declaration URIs are to be supported, that flag must also be set to a non-default value.

See Also:
setNamespaceDeclUris(boolean)

pushContext

public void pushContext()
Start a new Namespace context. The new context will automatically inherit the declarations of its parent context, but it will also keep track of which declarations were made within this context.

Event callback code should start a new context once per element. This means being ready to call this in either of two places. For elements that don't include namespace declarations, the ContentHandler.startElement() callback is the right place. For elements with such a declaration, it'd done in the first ContentHandler.startPrefixMapping() callback. A boolean flag can be used to track whether a context has been started yet. When either of those methods is called, it checks the flag to see if a new context needs to be started. If so, it starts the context and sets the flag. After ContentHandler.startElement() does that, it always clears the flag.

Normally, SAX drivers would push a new context at the beginning of each XML element. Then they perform a first pass over the attributes to process all namespace declarations, making ContentHandler.startPrefixMapping() callbacks. Then a second pass is made, to determine the namespace-qualified names for all attributes and for the element name. Finally all the information for the ContentHandler.startElement() callback is available, so it can then be made.

The Namespace support object always starts with a base context already in force: in this context, only the "xml" prefix is declared.

See Also:
ContentHandler, popContext()

popContext

public void popContext()
Revert to the previous Namespace context.

Normally, you should pop the context at the end of each XML element. After popping the context, all Namespace prefix mappings that were previously in force are restored.

You must not attempt to declare additional Namespace prefixes after popping a context, unless you push another context first.

See Also:
pushContext()

declarePrefix

public boolean declarePrefix(String prefix,
                             String uri)
Declare a Namespace prefix. All prefixes must be declared before they are referenced. For example, a SAX driver (parser) would scan an element's attributes in two passes: first for namespace declarations, then a second pass using processName() to interpret prefixes against (potentially redefined) prefixes.

This method declares a prefix in the current Namespace context; the prefix will remain in force until this context is popped, unless it is shadowed in a descendant context.

To declare the default element Namespace, use the empty string as the prefix.

Note that there is an asymmetry in this library: getPrefix will not return the "" prefix, even if you have declared a default element namespace. To check for a default namespace, you have to look it up explicitly using getURI. This asymmetry exists to make it easier to look up prefixes for attribute names, where the default prefix is not allowed.

Parameters:
prefix - The prefix to declare, or the empty string to indicate the default element namespace. This may never have the value "xml" or "xmlns".
uri - The Namespace URI to associate with the prefix.
Returns:
true if the prefix was legal, false otherwise
See Also:
processName(java.lang.String, java.lang.String[], boolean),
getURI(java.lang.String),
getPrefix(java.lang.String)

processName

public String[] processName(String qName,
                            String[] parts,
                            boolean isAttribute)
Process a raw XML qualified name, after all declarations in the current context have been handled by declarePrefix().

This method processes a raw XML qualified name in the current context by removing the prefix and looking it up among the prefixes currently declared. The return value will be the array supplied by the caller, filled in as follows:

parts[0]
The Namespace URI, or an empty string if none is in use.
parts[1]
The local name (without prefix).
parts[2]
The original raw name.

All of the strings in the array will be internalized. If the raw name has a prefix that has not been declared, then the return value will be null.

Note that attribute names are processed differently than element names: an unprefixed element name will receive the default Namespace (if any), while an unprefixed attribute name will not.

Parameters:
qName - The XML qualified name to be processed.
parts - An array supplied by the caller, capable of holding at least three members.
isAttribute - A flag indicating whether this is an attribute name (true) or an element name (false).
Returns:
The supplied array holding three internalized strings representing the Namespace URI (or empty string), the local name, and the XML qualified name; or null if there is an undeclared prefix.
See Also:
declarePrefix(java.lang.String, java.lang.String), String.intern()

getURI

public String getURI(String prefix)
Look up a prefix and get the currently-mapped Namespace URI.

This method looks up the prefix in the current context. Use the empty string ("") for the default Namespace.

Parameters:
prefix - The prefix to look up.
Returns:
The associated Namespace URI, or null if the prefix is undeclared in this context.
See Also:
getPrefix(java.lang.String), getPrefixes()

getPrefixes

public Enumeration getPrefixes()
Return an enumeration of all prefixes whose declarations are active in the current context. This includes declarations from parent contexts that have not been overridden.

Note: if there is a default prefix, it will not be returned in this enumeration; check for the default prefix using the getURI with an argument of "".

Returns:
An enumeration of prefixes (never empty).
See Also:
getDeclaredPrefixes(), getURI(java.lang.String)

getPrefix

public String getPrefix(String uri)
Return one of the prefixes mapped to a Namespace URI.

If more than one prefix is currently mapped to the same URI, this method will make an arbitrary selection; if you want all of the prefixes, use the getPrefixes() method instead.

Note: this will never return the empty (default) prefix; to check for a default prefix, use the getURI method with an argument of "".

Parameters:
uri - the namespace URI
Returns:
one of the prefixes currently mapped to the URI supplied, or null if none is mapped or if the URI is assigned to the default namespace
See Also:
getPrefixes(java.lang.String), getURI(java.lang.String)

getPrefixes

public Enumeration getPrefixes(String uri)
Return an enumeration of all prefixes for a given URI whose declarations are active in the current context. This includes declarations from parent contexts that have not been overridden.

This method returns prefixes mapped to a specific Namespace URI. The xml: prefix will be included. If you want only one prefix that's mapped to the Namespace URI, and you don't care which one you get, use the getPrefix method instead.

Note: the empty (default) prefix is never included in this enumeration; to check for the presence of a default Namespace, use the getURI method with an argument of "".

Parameters:
uri - The Namespace URI.
Returns:
An enumeration of prefixes (never empty).
See Also:
getPrefix(java.lang.String),
getDeclaredPrefixes(),
getURI(java.lang.String)

getDeclaredPrefixes

public Enumeration getDeclaredPrefixes()
Return an enumeration of all prefixes declared in this context.

The empty (default) prefix will be included in this enumeration; note that this behaviour differs from that of getPrefix(java.lang.String) and getPrefixes().

Returns:
An enumeration of all prefixes declared in this context.
See Also:
getPrefixes(), getURI(java.lang.String)

setNamespaceDeclUris

public void setNamespaceDeclUris(boolean value)
Controls whether namespace declaration attributes are placed into the NSDECL namespace by processName(). This may only be changed before any contexts have been pushed.

Throws:
IllegalStateException - when attempting to set this after any context has been pushed.
Since:
SAX 2.1alpha

isNamespaceDeclUris

public boolean isNamespaceDeclUris()
Returns true if namespace declaration attributes are placed into a namespace. This behavior is not the default.

Since:
SAX 2.1alpha
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ParserAdapter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.helpers
Class ParserAdapter

java.lang.Object
    extended by  org.xml.sax.helpers.ParserAdapter
All Implemented Interfaces:
DocumentHandler, XMLReader
public class ParserAdapter
extends Object
implements XMLReader, DocumentHandler

Adapt a SAX1 Parser as a SAX2 XMLReader.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This class wraps a SAX1 Parser and makes it act as a SAX2 XMLReader, with feature, property, and Namespace support. Note that it is not possible to report skippedEntity events, since SAX1 does not make that information available.

This adapter does not test for duplicate Namespace-qualified attribute names.

Since:
SAX 2.0
See Also:
XMLReaderAdapter, XMLReader, Parser

Constructor Summary
ParserAdapter()
Construct a new parser adapter.
ParserAdapter(Parser parser)
Construct a new parser adapter.
Method Summary
void | characters(char[] ch, int start, int length) Adapter implementation method; do not call.
void | endDocument() Adapter implementation method; do not call.
void | endElement(String qName) Adapter implementation method; do not call.
ContentHandler | getContentHandler() Return the current content handler.
DTDHandler | getDTDHandler() Return the current DTD handler.
EntityResolver | getEntityResolver() Return the current entity resolver.
ErrorHandler | getErrorHandler() Return the current error handler.
boolean | getFeature(String name) Check a parser feature flag.
Object | getProperty(String name) Get a parser property.
void | ignorableWhitespace(char[] ch, int start, int length) Adapter implementation method; do not call.
void | parse(InputSource input) Parse an XML document.
void | parse(String systemId) Parse an XML document.
void | processingInstruction(String target, String data) Adapter implementation method; do not call.
void | setContentHandler(ContentHandler handler) Set the content handler.
void | setDocumentLocator(Locator locator) Adapter implementation method; do not call.
void | setDTDHandler(DTDHandler handler) Set the DTD handler.
void | setEntityResolver(EntityResolver resolver) Set the entity resolver.
void | setErrorHandler(ErrorHandler handler) Set the error handler.
void | setFeature(String name, boolean value) Set a feature flag for the parser.
void | setProperty(String name, Object value) Set a parser property.
void | startDocument() Adapter implementation method; do not call.
void | startElement(String qName, AttributeList qAtts) Adapter implementation method; do not call.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ParserAdapter

public ParserAdapter()
              throws SAXException
Construct a new parser adapter.

Use the "org.xml.sax.parser" property to locate the embedded SAX1 driver.

Throws:
SAXException - If the embedded driver cannot be instantiated or if the org.xml.sax.parser property is not specified.

ParserAdapter

public ParserAdapter(Parser parser)
Construct a new parser adapter.

Note that the embedded parser cannot be changed once the adapter is created; to embed a different parser, allocate a new ParserAdapter.

Parameters:
parser - The SAX1 parser to embed.
Throws:
NullPointerException - If the parser parameter is null.
Method Detail

setFeature

public void setFeature(String name,
                       boolean value)
                throws SAXNotRecognizedException,
                       SAXNotSupportedException
Set a feature flag for the parser.

The only features recognized are namespaces and namespace-prefixes.

Specified by:
setFeature in interface XMLReader
Parameters:
name - The feature name, as a complete URI.
value - The requested feature value.
Throws:
SAXNotRecognizedException - If the feature can't be assigned or retrieved.
SAXNotSupportedException - If the feature can't be assigned that value.
See Also:
XMLReader.setFeature(java.lang.String, boolean)

getFeature

public boolean getFeature(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException
Check a parser feature flag.

The only features recognized are namespaces and namespace-prefixes.

Specified by:
getFeature in interface XMLReader
Parameters:
name - The feature name, as a complete URI.
Returns:
The current feature value.
Throws:
SAXNotRecognizedException - If the feature value can't be assigned or retrieved.
SAXNotSupportedException - If the feature is not currently readable.
See Also:
XMLReader.setFeature(java.lang.String, boolean)

setProperty

public void setProperty(String name,
                        Object value)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException
Set a parser property.

No properties are currently recognized.

Specified by:
setProperty in interface XMLReader
Parameters:
name - The property name.
value - The property value.
Throws:
SAXNotRecognizedException - If the property value can't be assigned or retrieved.
SAXNotSupportedException - If the property can't be assigned that value.
See Also:
XMLReader.setProperty(java.lang.String, java.lang.Object)

getProperty

public Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException
Get a parser property.

No properties are currently recognized.

Specified by:
getProperty in interface XMLReader
Parameters:
name - The property name.
Returns:
The property value.
Throws:
SAXNotRecognizedException - If the property value can't be assigned or retrieved.
SAXNotSupportedException - If the property value is not currently readable.
See Also:
XMLReader.getProperty(java.lang.String)

setEntityResolver

public void setEntityResolver(EntityResolver resolver)
Set the entity resolver.

Specified by:
setEntityResolver in interface XMLReader
Parameters:
resolver - The new entity resolver.
See Also:
XMLReader.setEntityResolver(org.xml.sax.EntityResolver)

getEntityResolver

public EntityResolver getEntityResolver()
Return the current entity resolver.

Specified by:
getEntityResolver in interface XMLReader
Returns:
The current entity resolver, or null if none was supplied.
See Also:
XMLReader.getEntityResolver()

setDTDHandler

public void setDTDHandler(DTDHandler handler)
Set the DTD handler.

Specified by:
setDTDHandler in interface XMLReader
Parameters:
handler - the new DTD handler
See Also:
XMLReader.setEntityResolver(org.xml.sax.EntityResolver)

getDTDHandler

public DTDHandler getDTDHandler()
Return the current DTD handler.

Specified by:
getDTDHandler in interface XMLReader
Returns:
the current DTD handler, or null if none was supplied
See Also:
XMLReader.getEntityResolver()

setContentHandler

public void setContentHandler(ContentHandler handler)
Set the content handler.

Specified by:
setContentHandler in interface XMLReader
Parameters:
handler - the new content handler
See Also:
XMLReader.setEntityResolver(org.xml.sax.EntityResolver)

getContentHandler

public ContentHandler getContentHandler()
Return the current content handler.

Specified by:
getContentHandler in interface XMLReader
Returns:
The current content handler, or null if none was supplied.
See Also:
XMLReader.getEntityResolver()

setErrorHandler

public void setErrorHandler(ErrorHandler handler)
Set the error handler.

Specified by:
setErrorHandler in interface XMLReader
Parameters:
handler - The new error handler.
See Also:
XMLReader.setEntityResolver(org.xml.sax.EntityResolver)

getErrorHandler

public ErrorHandler getErrorHandler()
Return the current error handler.

Specified by:
getErrorHandler in interface XMLReader
Returns:
The current error handler, or null if none was supplied.
See Also:
XMLReader.getEntityResolver()

parse

public void parse(String systemId)
           throws IOException,
                  SAXException
Parse an XML document.

Specified by:
parse in interface XMLReader
Parameters:
systemId - The absolute URL of the document.
Throws:
IOException - If there is a problem reading the raw content of the document.
SAXException - If there is a problem processing the document.
See Also:
parse(org.xml.sax.InputSource), Parser.parse(java.lang.String)

parse

public void parse(InputSource input)
           throws IOException,
                  SAXException
Parse an XML document.

Specified by:
parse in interface XMLReader
Parameters:
input - An input source for the document.
Throws:
IOException - If there is a problem reading the raw content of the document.
SAXException - If there is a problem processing the document.
See Also:
parse(java.lang.String), Parser.parse(org.xml.sax.InputSource)

setDocumentLocator

public void setDocumentLocator(Locator locator)
Adapter implementation method; do not call. Adapt a SAX1 document locator event.

Specified by:
setDocumentLocator in interface DocumentHandler
Parameters:
locator - A document locator.
See Also:
ContentHandler.setDocumentLocator(org.xml.sax.Locator)

startDocument

public void startDocument()
                   throws SAXException
Adapter implementation method; do not call. Adapt a SAX1 start document event.

Specified by:
startDocument in interface DocumentHandler
Throws:
SAXException - The client may raise a processing exception.
See Also:
DocumentHandler.startDocument()

endDocument

public void endDocument()
                 throws SAXException
Adapter implementation method; do not call. Adapt a SAX1 end document event.

Specified by:
endDocument in interface DocumentHandler
Throws:
SAXException - The client may raise a processing exception.
See Also:
DocumentHandler.endDocument()

startElement

public void startElement(String qName,
                         AttributeList qAtts)
                  throws SAXException
Adapter implementation method; do not call. Adapt a SAX1 startElement event.

If necessary, perform Namespace processing.

Specified by:
startElement in interface DocumentHandler
Parameters:
qName - The qualified (prefixed) name.
qAtts - The XML attribute list (with qnames).
Throws:
SAXException - The client may raise a processing exception.
See Also:
DocumentHandler.endElement(java.lang.String), AttributeList

endElement

public void endElement(String qName)
                throws SAXException
Adapter implementation method; do not call. Adapt a SAX1 end element event.

Specified by:
endElement in interface DocumentHandler
Parameters:
qName - The qualified (prefixed) name.
Throws:
SAXException - The client may raise a processing exception.
See Also:
DocumentHandler.endElement(java.lang.String)

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws SAXException
Adapter implementation method; do not call. Adapt a SAX1 characters event.

Specified by:
characters in interface DocumentHandler
Parameters:
ch - An array of characters.
start - The starting position in the array.
length - The number of characters to use.
Throws:
SAXException - The client may raise a processing exception.
See Also:
DocumentHandler.characters(char[], int, int)

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws SAXException
Adapter implementation method; do not call. Adapt a SAX1 ignorable whitespace event.

Specified by:
ignorableWhitespace in interface DocumentHandler
Parameters:
ch - An array of characters.
start - The starting position in the array.
length - The number of characters to use.
Throws:
SAXException - The client may raise a processing exception.
See Also:
DocumentHandler.ignorableWhitespace(char[], int, int)

processingInstruction

public void processingInstruction(String target,
                                  String data)
                           throws SAXException
Adapter implementation method; do not call. Adapt a SAX1 processing instruction event.

Specified by:
processingInstruction in interface DocumentHandler
Parameters:
target - The processing instruction target.
data - The remainder of the processing instruction
Throws:
SAXException - The client may raise a processing exception.
See Also:
DocumentHandler.processingInstruction(java.lang.String, java.lang.String)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ParserFactory

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.helpers
Class ParserFactory

java.lang.Object
    extended by  org.xml.sax.helpers.ParserFactory
Deprecated. This class works with the deprecated Parser interface.

public class ParserFactory
extends Object

Java-specific class for dynamically loading SAX parsers.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

Note: This class is designed to work with the now-deprecated SAX1 Parser class. SAX2 applications should use XMLReaderFactory instead.

ParserFactory is not part of the platform-independent definition of SAX; it is an additional convenience class designed specifically for Java XML application writers. SAX applications can use the static methods in this class to allocate a SAX parser dynamically at run-time based either on the value of the `org.xml.sax.parser' system property or on a string containing the class name.

Note that the application still requires an XML parser that implements SAX1.

Since:
SAX 1.0

Method Summary
static Parser | makeParser() Deprecated. Create a new SAX parser using the `org.xml.sax.parser' system property.
static Parser | makeParser(String className) Deprecated. Create a new SAX parser object using the class name provided.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

makeParser

public static Parser makeParser()
                         throws ClassNotFoundException,
                                IllegalAccessException,
                                InstantiationException,
                                NullPointerException,
                                ClassCastException
Deprecated.
Create a new SAX parser using the `org.xml.sax.parser' system property.

The named class must exist and must implement the Parser interface.

Throws:
NullPointerException - There is no value for the `org.xml.sax.parser' system property.
ClassNotFoundException - The SAX parser class was not found (check your CLASSPATH).
IllegalAccessException - The SAX parser class was found, but you do not have permission to load it.
InstantiationException - The SAX parser class was found but could not be instantiated.
ClassCastException - The SAX parser class was found and instantiated, but does not implement org.xml.sax.Parser.
See Also:
makeParser(java.lang.String), Parser

makeParser

public static Parser makeParser(String className)
                         throws ClassNotFoundException,
                                IllegalAccessException,
                                InstantiationException,
                                ClassCastException
Deprecated.
Create a new SAX parser object using the class name provided.

The named class must exist and must implement the Parser interface.

Parameters:
className - A string containing the name of the SAX parser class.
Throws:
ClassNotFoundException - The SAX parser class was not found (check your CLASSPATH).
IllegalAccessException - The SAX parser class was found, but you do not have permission to load it.
InstantiationException - The SAX parser class was found but could not be instantiated.
ClassCastException - The SAX parser class was found and instantiated, but does not implement org.xml.sax.Parser.
See Also:
makeParser(), Parser
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLFilterImpl

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.helpers
Class XMLFilterImpl

java.lang.Object
    extended by  org.xml.sax.helpers.XMLFilterImpl
All Implemented Interfaces:
ContentHandler, DTDHandler, EntityResolver, ErrorHandler, XMLFilter, XMLReader
public class XMLFilterImpl
extends Object
implements XMLFilter, EntityResolver, DTDHandler, ContentHandler, ErrorHandler

Base class for deriving an XML filter.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This class is designed to sit between an XMLReader and the client application's event handlers. By default, it does nothing but pass requests up to the reader and events on to the handlers unmodified, but subclasses can override specific methods to modify the event stream or the configuration requests as they pass through.

Since:
SAX 2.0
See Also:
XMLFilter, XMLReader, EntityResolver, DTDHandler, ContentHandler, ErrorHandler

Constructor Summary
XMLFilterImpl()
Construct an empty XML filter, with no parent.
XMLFilterImpl(XMLReader parent)
Construct an XML filter with the specified parent.
Method Summary
void | characters(char[] ch, int start, int length) Filter a character data event.
void | endDocument() Filter an end document event.
void | endElement(String uri, String localName, String qName) Filter an end element event.
void | endPrefixMapping(String prefix) Filter an end Namespace prefix mapping event.
void | error(SAXParseException e) Filter an error event.
void | fatalError(SAXParseException e) Filter a fatal error event.
ContentHandler | getContentHandler() Get the content event handler.
DTDHandler | getDTDHandler() Get the current DTD event handler.
EntityResolver | getEntityResolver() Get the current entity resolver.
ErrorHandler | getErrorHandler() Get the current error event handler.
boolean | getFeature(String name) Look up the value of a feature.
XMLReader | getParent() Get the parent reader.
Object | getProperty(String name) Look up the value of a property.
void | ignorableWhitespace(char[] ch, int start, int length) Filter an ignorable whitespace event.
void | notationDecl(String name, String publicId, String systemId) Filter a notation declaration event.
void | parse(InputSource input) Parse a document.
void | parse(String systemId) Parse a document.
void | processingInstruction(String target, String data) Filter a processing instruction event.
InputSource | resolveEntity(String publicId, String systemId) Filter an external entity resolution.
void | setContentHandler(ContentHandler handler) Set the content event handler.
void | setDocumentLocator(Locator locator) Filter a new document locator event.
void | setDTDHandler(DTDHandler handler) Set the DTD event handler.
void | setEntityResolver(EntityResolver resolver) Set the entity resolver.
void | setErrorHandler(ErrorHandler handler) Set the error event handler.
void | setFeature(String name, boolean value) Set the value of a feature.
void | setParent(XMLReader parent) Set the parent reader.
void | setProperty(String name, Object value) Set the value of a property.
void | skippedEntity(String name) Filter a skipped entity event.
void | startDocument() Filter a start document event.
void | startElement(String uri, String localName, String qName, Attributes atts) Filter a start element event.
void | startPrefixMapping(String prefix, String uri) Filter a start Namespace prefix mapping event.
void | unparsedEntityDecl(String name, String publicId, String systemId, String notationName) Filter an unparsed entity declaration event.
void | warning(SAXParseException e) Filter a warning event.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XMLFilterImpl

public XMLFilterImpl()
Construct an empty XML filter, with no parent.

This filter will have no parent: you must assign a parent before you start a parse or do any configuration with setFeature or setProperty, unless you use this as a pure event consumer rather than as an XMLReader.

See Also:
XMLReader.setFeature(java.lang.String, boolean),
XMLReader.setProperty(java.lang.String, java.lang.Object),
setParent(org.xml.sax.XMLReader)

XMLFilterImpl

public XMLFilterImpl(XMLReader parent)
Construct an XML filter with the specified parent.

See Also:
setParent(org.xml.sax.XMLReader), getParent()
Method Detail

setParent

public void setParent(XMLReader parent)
Set the parent reader.

This is the XMLReader from which this filter will obtain its events and to which it will pass its configuration requests. The parent may itself be another filter.

If there is no parent reader set, any attempt to parse or to set or get a feature or property will fail.

Specified by:
setParent in interface XMLFilter
Parameters:
parent - The parent XML reader.
See Also:
getParent()

getParent

public XMLReader getParent()
Get the parent reader.

Specified by:
getParent in interface XMLFilter
Returns:
The parent XML reader, or null if none is set.
See Also:
setParent(org.xml.sax.XMLReader)

setFeature

public void setFeature(String name,
                       boolean value)
                throws SAXNotRecognizedException,
                       SAXNotSupportedException
Set the value of a feature.

This will always fail if the parent is null.

Specified by:
setFeature in interface XMLReader
Parameters:
name - The feature name.
value - The requested feature value.
Throws:
SAXNotRecognizedException - If the feature value can't be assigned or retrieved from the parent.
SAXNotSupportedException - When the parent recognizes the feature name but cannot set the requested value.
See Also:
XMLReader.getFeature(java.lang.String)

getFeature

public boolean getFeature(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException
Look up the value of a feature.

This will always fail if the parent is null.

Specified by:
getFeature in interface XMLReader
Parameters:
name - The feature name.
Returns:
The current value of the feature.
Throws:
SAXNotRecognizedException - If the feature value can't be assigned or retrieved from the parent.
SAXNotSupportedException - When the parent recognizes the feature name but cannot determine its value at this time.
See Also:
XMLReader.setFeature(java.lang.String, boolean)

setProperty

public void setProperty(String name,
                        Object value)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException
Set the value of a property.

This will always fail if the parent is null.

Specified by:
setProperty in interface XMLReader
Parameters:
name - The property name.
value - The requested property value.
Throws:
SAXNotRecognizedException - If the property value can't be assigned or retrieved from the parent.
SAXNotSupportedException - When the parent recognizes the property name but cannot set the requested value.

getProperty

public Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException
Look up the value of a property.

Specified by:
getProperty in interface XMLReader
Parameters:
name - The property name.
Returns:
The current value of the property.
Throws:
SAXNotRecognizedException - If the property value can't be assigned or retrieved from the parent.
SAXNotSupportedException - When the parent recognizes the property name but cannot determine its value at this time.
See Also:
XMLReader.setProperty(java.lang.String, java.lang.Object)

setEntityResolver

public void setEntityResolver(EntityResolver resolver)
Set the entity resolver.

Specified by:
setEntityResolver in interface XMLReader
Parameters:
resolver - The new entity resolver.
See Also:
XMLReader.getEntityResolver()

getEntityResolver

public EntityResolver getEntityResolver()
Get the current entity resolver.

Specified by:
getEntityResolver in interface XMLReader
Returns:
The current entity resolver, or null if none was set.
See Also:
XMLReader.setEntityResolver(org.xml.sax.EntityResolver)

setDTDHandler

public void setDTDHandler(DTDHandler handler)
Set the DTD event handler.

Specified by:
setDTDHandler in interface XMLReader
Parameters:
handler - the new DTD handler
See Also:
XMLReader.getDTDHandler()

getDTDHandler

public DTDHandler getDTDHandler()
Get the current DTD event handler.

Specified by:
getDTDHandler in interface XMLReader
Returns:
The current DTD handler, or null if none was set.
See Also:
XMLReader.setDTDHandler(org.xml.sax.DTDHandler)

setContentHandler

public void setContentHandler(ContentHandler handler)
Set the content event handler.

Specified by:
setContentHandler in interface XMLReader
Parameters:
handler - the new content handler
See Also:
XMLReader.getContentHandler()

getContentHandler

public ContentHandler getContentHandler()
Get the content event handler.

Specified by:
getContentHandler in interface XMLReader
Returns:
The current content handler, or null if none was set.
See Also:
XMLReader.setContentHandler(org.xml.sax.ContentHandler)

setErrorHandler

public void setErrorHandler(ErrorHandler handler)
Set the error event handler.

Specified by:
setErrorHandler in interface XMLReader
Parameters:
handler - the new error handler
See Also:
XMLReader.getErrorHandler()

getErrorHandler

public ErrorHandler getErrorHandler()
Get the current error event handler.

Specified by:
getErrorHandler in interface XMLReader
Returns:
The current error handler, or null if none was set.
See Also:
XMLReader.setErrorHandler(org.xml.sax.ErrorHandler)

parse

public void parse(InputSource input)
           throws SAXException,
                  IOException
Parse a document.

Specified by:
parse in interface XMLReader
Parameters:
input - The input source for the document entity.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
IOException - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
See Also:
InputSource,
XMLReader.parse(java.lang.String),
XMLReader.setEntityResolver(org.xml.sax.EntityResolver),
XMLReader.setDTDHandler(org.xml.sax.DTDHandler),
XMLReader.setContentHandler(org.xml.sax.ContentHandler),
XMLReader.setErrorHandler(org.xml.sax.ErrorHandler)

parse

public void parse(String systemId)
           throws SAXException,
                  IOException
Parse a document.

Specified by:
parse in interface XMLReader
Parameters:
systemId - The system identifier as a fully-qualified URI.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
IOException - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
See Also:
XMLReader.parse(org.xml.sax.InputSource)

resolveEntity

public InputSource resolveEntity(String publicId,
                                 String systemId)
                          throws SAXException,
                                 IOException
Filter an external entity resolution.

Specified by:
resolveEntity in interface EntityResolver
Parameters:
publicId - The entity's public identifier, or null.
systemId - The entity's system identifier.
Returns:
A new InputSource or null for the default.
Throws:
SAXException - The client may throw an exception during processing.
IOException - The client may throw an I/O-related exception while obtaining the new InputSource.
See Also:
InputSource

notationDecl

public void notationDecl(String name,
                         String publicId,
                         String systemId)
                  throws SAXException
Filter a notation declaration event.

Specified by:
notationDecl in interface DTDHandler
Parameters:
name - The notation name.
publicId - The notation's public identifier, or null.
systemId - The notation's system identifier, or null.
Throws:
SAXException - The client may throw an exception during processing.
See Also:
DTDHandler.unparsedEntityDecl(java.lang.String, java.lang.String, java.lang.String, java.lang.String), Attributes

unparsedEntityDecl

public void unparsedEntityDecl(String name,
                               String publicId,
                               String systemId,
                               String notationName)
                        throws SAXException
Filter an unparsed entity declaration event.

Specified by:
unparsedEntityDecl in interface DTDHandler
Parameters:
name - The entity name.
publicId - The entity's public identifier, or null.
systemId - The entity's system identifier, or null.
notationName - The name of the associated notation.
Throws:
SAXException - The client may throw an exception during processing.
See Also:
DTDHandler.notationDecl(java.lang.String, java.lang.String, java.lang.String), Attributes

setDocumentLocator

public void setDocumentLocator(Locator locator)
Filter a new document locator event.

Specified by:
setDocumentLocator in interface ContentHandler
Parameters:
locator - The document locator.
See Also:
Locator

startDocument

public void startDocument()
                   throws SAXException
Filter a start document event.

Specified by:
startDocument in interface ContentHandler
Throws:
SAXException - The client may throw an exception during processing.
See Also:
ContentHandler.endDocument()

endDocument

public void endDocument()
                 throws SAXException
Filter an end document event.

Specified by:
endDocument in interface ContentHandler
Throws:
SAXException - The client may throw an exception during processing.
See Also:
ContentHandler.startDocument()

startPrefixMapping

public void startPrefixMapping(String prefix,
                               String uri)
                        throws SAXException
Filter a start Namespace prefix mapping event.

Specified by:
startPrefixMapping in interface ContentHandler
Parameters:
prefix - The Namespace prefix.
uri - The Namespace URI.
Throws:
SAXException - The client may throw an exception during processing.
See Also:
ContentHandler.endPrefixMapping(java.lang.String), ContentHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)

endPrefixMapping

public void endPrefixMapping(String prefix)
                      throws SAXException
Filter an end Namespace prefix mapping event.

Specified by:
endPrefixMapping in interface ContentHandler
Parameters:
prefix - The Namespace prefix.
Throws:
SAXException - The client may throw an exception during processing.
See Also:
ContentHandler.startPrefixMapping(java.lang.String, java.lang.String), ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String)

startElement

public void startElement(String uri,
                         String localName,
                         String qName,
                         Attributes atts)
                  throws SAXException
Filter a start element event.

Specified by:
startElement in interface ContentHandler
Parameters:
uri - The element's Namespace URI, or the empty string.
localName - The element's local name, or the empty string.
qName - The element's qualified (prefixed) name, or the empty string.
atts - The element's attributes.
Throws:
SAXException - The client may throw an exception during processing.
See Also:
ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String), Attributes, AttributesImpl

endElement

public void endElement(String uri,
                       String localName,
                       String qName)
                throws SAXException
Filter an end element event.

Specified by:
endElement in interface ContentHandler
Parameters:
uri - The element's Namespace URI, or the empty string.
localName - The element's local name, or the empty string.
qName - The element's qualified (prefixed) name, or the empty string.
Throws:
SAXException - The client may throw an exception during processing.

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws SAXException
Filter a character data event.

Specified by:
characters in interface ContentHandler
Parameters:
ch - An array of characters.
start - The starting position in the array.
length - The number of characters to use from the array.
Throws:
SAXException - The client may throw an exception during processing.
See Also:
ContentHandler.ignorableWhitespace(char[], int, int), Locator

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws SAXException
Filter an ignorable whitespace event.

Specified by:
ignorableWhitespace in interface ContentHandler
Parameters:
ch - An array of characters.
start - The starting position in the array.
length - The number of characters to use from the array.
Throws:
SAXException - The client may throw an exception during processing.
See Also:
ContentHandler.characters(char[], int, int)

processingInstruction

public void processingInstruction(String target,
                                  String data)
                           throws SAXException
Filter a processing instruction event.

Specified by:
processingInstruction in interface ContentHandler
Parameters:
target - The processing instruction target.
data - The text following the target.
Throws:
SAXException - The client may throw an exception during processing.

skippedEntity

public void skippedEntity(String name)
                   throws SAXException
Filter a skipped entity event.

Specified by:
skippedEntity in interface ContentHandler
Parameters:
name - The name of the skipped entity.
Throws:
SAXException - The client may throw an exception during processing.

warning

public void warning(SAXParseException e)
             throws SAXException
Filter a warning event.

Specified by:
warning in interface ErrorHandler
Parameters:
e - The warning as an exception.
Throws:
SAXException - The client may throw an exception during processing.
See Also:
SAXParseException

error

public void error(SAXParseException e)
           throws SAXException
Filter an error event.

Specified by:
error in interface ErrorHandler
Parameters:
e - The error as an exception.
Throws:
SAXException - The client may throw an exception during processing.
See Also:
SAXParseException

fatalError

public void fatalError(SAXParseException e)
                throws SAXException
Filter a fatal error event.

Specified by:
fatalError in interface ErrorHandler
Parameters:
e - The error as an exception.
Throws:
SAXException - The client may throw an exception during processing.
See Also:
SAXParseException
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLReaderAdapter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.helpers
Class XMLReaderAdapter

java.lang.Object
    extended by  org.xml.sax.helpers.XMLReaderAdapter
All Implemented Interfaces:
ContentHandler, Parser
public class XMLReaderAdapter
extends Object
implements Parser, ContentHandler

Adapt a SAX2 XMLReader as a SAX1 Parser.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This class wraps a SAX2 XMLReader and makes it act as a SAX1 Parser. The XMLReader must support a true value for the http://xml.org/sax/features/namespace-prefixes property or parsing will fail with a SAXException; if the XMLReader supports a false value for the http://xml.org/sax/features/namespaces property, that will also be used to improve efficiency.

Since:
SAX 2.0
See Also:
Parser, XMLReader

Constructor Summary
XMLReaderAdapter()
Create a new adapter.
XMLReaderAdapter(XMLReader xmlReader)
Create a new adapter.
Method Summary
void | characters(char[] ch, int start, int length) Adapt a SAX2 characters event.
void | endDocument() End document event.
void | endElement(String uri, String localName, String qName) Adapt a SAX2 end element event.
void | endPrefixMapping(String prefix) Adapt a SAX2 end prefix mapping event.
void | ignorableWhitespace(char[] ch, int start, int length) Adapt a SAX2 ignorable whitespace event.
void | parse(InputSource input) Parse the document.
void | parse(String systemId) Parse the document.
void | processingInstruction(String target, String data) Adapt a SAX2 processing instruction event.
void | setDocumentHandler(DocumentHandler handler) Register the SAX1 document event handler.
void | setDocumentLocator(Locator locator) Set a document locator.
void | setDTDHandler(DTDHandler handler) Register the DTD event handler.
void | setEntityResolver(EntityResolver resolver) Register the entity resolver.
void | setErrorHandler(ErrorHandler handler) Register the error event handler.
void | setLocale(Locale locale) Set the locale for error reporting.
void | skippedEntity(String name) Adapt a SAX2 skipped entity event.
void | startDocument() Start document event.
void | startElement(String uri, String localName, String qName, Attributes atts) Adapt a SAX2 start element event.
void | startPrefixMapping(String prefix, String uri) Adapt a SAX2 start prefix mapping event.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XMLReaderAdapter

public XMLReaderAdapter()
                 throws SAXException
Create a new adapter.

Use the "org.xml.sax.driver" property to locate the SAX2 driver to embed.

Throws:
SAXException - If the embedded driver cannot be instantiated or if the org.xml.sax.driver property is not specified.

XMLReaderAdapter

public XMLReaderAdapter(XMLReader xmlReader)
Create a new adapter.

Create a new adapter, wrapped around a SAX2 XMLReader. The adapter will make the XMLReader act like a SAX1 Parser.

Parameters:
xmlReader - The SAX2 XMLReader to wrap.
Throws:
NullPointerException - If the argument is null.
Method Detail

setLocale

public void setLocale(Locale locale)
               throws SAXException
Set the locale for error reporting.

This is not supported in SAX2, and will always throw an exception.

Specified by:
setLocale in interface Parser
Parameters:
locale - the locale for error reporting.
Throws:
SAXException - Thrown unless overridden.
See Also:
Parser.setLocale(java.util.Locale)

setEntityResolver

public void setEntityResolver(EntityResolver resolver)
Register the entity resolver.

Specified by:
setEntityResolver in interface Parser
Parameters:
resolver - The new resolver.
See Also:
Parser.setEntityResolver(org.xml.sax.EntityResolver)

setDTDHandler

public void setDTDHandler(DTDHandler handler)
Register the DTD event handler.

Specified by:
setDTDHandler in interface Parser
Parameters:
handler - The new DTD event handler.
See Also:
Parser.setDTDHandler(org.xml.sax.DTDHandler)

setDocumentHandler

public void setDocumentHandler(DocumentHandler handler)
Register the SAX1 document event handler.

Note that the SAX1 document handler has no Namespace support.

Specified by:
setDocumentHandler in interface Parser
Parameters:
handler - The new SAX1 document event handler.
See Also:
Parser.setDocumentHandler(org.xml.sax.DocumentHandler)

setErrorHandler

public void setErrorHandler(ErrorHandler handler)
Register the error event handler.

Specified by:
setErrorHandler in interface Parser
Parameters:
handler - The new error event handler.
See Also:
Parser.setErrorHandler(org.xml.sax.ErrorHandler)

parse

public void parse(String systemId)
           throws IOException,
                  SAXException
Parse the document.

This method will throw an exception if the embedded XMLReader does not support the http://xml.org/sax/features/namespace-prefixes property.

Specified by:
parse in interface Parser
Parameters:
systemId - The absolute URL of the document.
Throws:
IOException - If there is a problem reading the raw content of the document.
SAXException - If there is a problem processing the document.
See Also:
parse(org.xml.sax.InputSource), Parser.parse(java.lang.String)

parse

public void parse(InputSource input)
           throws IOException,
                  SAXException
Parse the document.

This method will throw an exception if the embedded XMLReader does not support the http://xml.org/sax/features/namespace-prefixes property.

Specified by:
parse in interface Parser
Parameters:
input - An input source for the document.
Throws:
IOException - If there is a problem reading the raw content of the document.
SAXException - If there is a problem processing the document.
See Also:
parse(java.lang.String), Parser.parse(org.xml.sax.InputSource)

setDocumentLocator

public void setDocumentLocator(Locator locator)
Set a document locator.

Specified by:
setDocumentLocator in interface ContentHandler
Parameters:
locator - The document locator.
See Also:
ContentHandler.setDocumentLocator(org.xml.sax.Locator)

startDocument

public void startDocument()
                   throws SAXException
Start document event.

Specified by:
startDocument in interface ContentHandler
Throws:
SAXException - The client may raise a processing exception.
See Also:
ContentHandler.startDocument()

endDocument

public void endDocument()
                 throws SAXException
End document event.

Specified by:
endDocument in interface ContentHandler
Throws:
SAXException - The client may raise a processing exception.
See Also:
ContentHandler.endDocument()

startPrefixMapping

public void startPrefixMapping(String prefix,
                               String uri)
Adapt a SAX2 start prefix mapping event.

Specified by:
startPrefixMapping in interface ContentHandler
Parameters:
prefix - The prefix being mapped.
uri - The Namespace URI being mapped to.
See Also:
ContentHandler.startPrefixMapping(java.lang.String, java.lang.String)

endPrefixMapping

public void endPrefixMapping(String prefix)
Adapt a SAX2 end prefix mapping event.

Specified by:
endPrefixMapping in interface ContentHandler
Parameters:
prefix - The prefix being mapped.
See Also:
ContentHandler.endPrefixMapping(java.lang.String)

startElement

public void startElement(String uri,
                         String localName,
                         String qName,
                         Attributes atts)
                  throws SAXException
Adapt a SAX2 start element event.

Specified by:
startElement in interface ContentHandler
Parameters:
uri - The Namespace URI.
localName - The Namespace local name.
qName - The qualified (prefixed) name.
atts - The SAX2 attributes.
Throws:
SAXException - The client may raise a processing exception.
See Also:
ContentHandler.endDocument()

endElement

public void endElement(String uri,
                       String localName,
                       String qName)
                throws SAXException
Adapt a SAX2 end element event.

Specified by:
endElement in interface ContentHandler
Parameters:
uri - The Namespace URI.
localName - The Namespace local name.
qName - The qualified (prefixed) name.
Throws:
SAXException - The client may raise a processing exception.
See Also:
ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String)

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws SAXException
Adapt a SAX2 characters event.

Specified by:
characters in interface ContentHandler
Parameters:
ch - An array of characters.
start - The starting position in the array.
length - The number of characters to use.
Throws:
SAXException - The client may raise a processing exception.
See Also:
ContentHandler.characters(char[], int, int)

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws SAXException
Adapt a SAX2 ignorable whitespace event.

Specified by:
ignorableWhitespace in interface ContentHandler
Parameters:
ch - An array of characters.
start - The starting position in the array.
length - The number of characters to use.
Throws:
SAXException - The client may raise a processing exception.
See Also:
ContentHandler.ignorableWhitespace(char[], int, int)

processingInstruction

public void processingInstruction(String target,
                                  String data)
                           throws SAXException
Adapt a SAX2 processing instruction event.

Specified by:
processingInstruction in interface ContentHandler
Parameters:
target - The processing instruction target.
data - The remainder of the processing instruction
Throws:
SAXException - The client may raise a processing exception.
See Also:
ContentHandler.processingInstruction(java.lang.String, java.lang.String)

skippedEntity

public void skippedEntity(String name)
                   throws SAXException
Adapt a SAX2 skipped entity event.

Specified by:
skippedEntity in interface ContentHandler
Parameters:
name - The name of the skipped entity.
Throws:
SAXException - Throwable by subclasses.
See Also:
ContentHandler.skippedEntity(java.lang.String)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLReaderFactory

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.xml.sax.helpers
Class XMLReaderFactory

java.lang.Object
    extended by  org.xml.sax.helpers.XMLReaderFactory

public final class XMLReaderFactory
extends Object

Factory for creating an XML reader.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This class contains static methods for creating an XML reader from an explicit class name, or based on runtime defaults:

 try {
   XMLReader myReader = XMLReaderFactory.createXMLReader();
 } catch (SAXException e) {
   System.err.println(e.getMessage());
 }

Note to Distributions bundled with parsers: You should modify the implementation of the no-arguments createXMLReader to handle cases where the external configuration mechanisms aren't set up. That method should do its best to return a parser when one is in the class path, even when nothing bound its class name to org.xml.sax.driver so those configuration mechanisms would see it.

Since:
SAX 2.0

Method Summary
static XMLReader | createXMLReader() Attempt to create an XMLReader from system defaults.
static XMLReader | createXMLReader(String className) Attempt to create an XML reader from a class name.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createXMLReader

public static XMLReader createXMLReader()
                                 throws SAXException
Attempt to create an XMLReader from system defaults. In environments which can support it, the name of the XMLReader class is determined by trying each these options in order, and using the first one which succeeds:

  • If the system property org.xml.sax.driver has a value, that is used as an XMLReader class name.
  • The JAR "Services API" is used to look for a class name in the META-INF/services/org.xml.sax.driver file in jarfiles available to the runtime.
  • SAX parser distributions are strongly encouraged to provide a default XMLReader class name that will take effect only when previous options (on this list) are not successful.
  • Finally, if ParserFactory.makeParser() can return a system default SAX1 parser, that parser is wrapped in a ParserAdapter. (This is a migration aid for SAX1 environments, where the org.xml.sax.parser system property will often be usable.)

In environments such as small embedded systems, which can not support that flexibility, other mechanisms to determine the default may be used.

Note that many Java environments allow system properties to be initialized on a command line. This means that in most cases setting a good value for that property ensures that calls to this method will succeed, except when security policies intervene. This will also maximize application portability to older SAX environments, with less robust implementations of this method.

Returns:
A new XMLReader.
Throws:
SAXException - If no default XMLReader class can be identified and instantiated.
See Also:
createXMLReader(java.lang.String)

createXMLReader

public static XMLReader createXMLReader(String className)
                                 throws SAXException
Attempt to create an XML reader from a class name.

Given a class name, this method attempts to load and instantiate the class as an XML reader.

Note that this method will not be usable in environments where the caller (perhaps an applet) is not permitted to load classes dynamically.

Returns:
A new XML reader.
Throws:
SAXException - If the class cannot be loaded, instantiated, and cast to XMLReader.
See Also:
createXMLReader()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


InputSource

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax
Class InputSource

java.lang.Object
    extended by  org.xml.sax.InputSource

public class InputSource
extends Object

A single input source for an XML entity.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This class allows a SAX application to encapsulate information about an input source in a single object, which may include a public identifier, a system identifier, a byte stream (possibly with a specified encoding), and/or a character stream.

There are two places that the application can deliver an input source to the parser: as the argument to the Parser.parse method, or as the return value of the EntityResolver.resolveEntity method.

The SAX parser will use the InputSource object to determine how to read XML input. If there is a character stream available, the parser will read that stream directly, disregarding any text encoding declaration found in that stream. If there is no character stream, but there is a byte stream, the parser will use that byte stream, using the encoding specified in the InputSource or else (if no encoding is specified) autodetecting the character encoding using an algorithm such as the one in the XML specification. If neither a character stream nor a byte stream is available, the parser will attempt to open a URI connection to the resource identified by the system identifier.

An InputSource object belongs to the application: the SAX parser shall never modify it in any way (it may modify a copy if necessary). However, standard processing of both byte and character streams is to close them on as part of end-of-parse cleanup, so applications should not attempt to re-use such streams after they have been handed to a parser.

Since:
SAX 1.0
See Also:
XMLReader.parse(org.xml.sax.InputSource), EntityResolver.resolveEntity(java.lang.String, java.lang.String), InputStream, Reader

Constructor Summary
InputSource()
Zero-argument default constructor.
InputSource(InputStream byteStream)
Create a new input source with a byte stream.
InputSource(Reader characterStream)
Create a new input source with a character stream.
InputSource(String systemId)
Create a new input source with a system identifier.
Method Summary
InputStream | getByteStream() Get the byte stream for this input source.
Reader | getCharacterStream() Get the character stream for this input source.
String | getEncoding() Get the character encoding for a byte stream or URI.
String | getPublicId() Get the public identifier for this input source.
String | getSystemId() Get the system identifier for this input source.
void | setByteStream(InputStream byteStream) Set the byte stream for this input source.
void | setCharacterStream(Reader characterStream) Set the character stream for this input source.
void | setEncoding(String encoding) Set the character encoding, if known.
void | setPublicId(String publicId) Set the public identifier for this input source.
void | setSystemId(String systemId) Set the system identifier for this input source.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InputSource

public InputSource()
Zero-argument default constructor.

See Also:
setPublicId(java.lang.String),
setSystemId(java.lang.String),
setByteStream(java.io.InputStream),
setCharacterStream(java.io.Reader),
setEncoding(java.lang.String)

InputSource

public InputSource(String systemId)
Create a new input source with a system identifier.

Applications may use setPublicId to include a public identifier as well, or setEncoding to specify the character encoding, if known.

If the system identifier is a URL, it must be fully resolved (it may not be a relative URL).

Parameters:
systemId - The system identifier (URI).
See Also:
setPublicId(java.lang.String),
setSystemId(java.lang.String),
setByteStream(java.io.InputStream),
setEncoding(java.lang.String),
setCharacterStream(java.io.Reader)

InputSource

public InputSource(InputStream byteStream)
Create a new input source with a byte stream.

Application writers should use setSystemId() to provide a base for resolving relative URIs, may use setPublicId to include a public identifier, and may use setEncoding to specify the object's character encoding.

Parameters:
byteStream - The raw byte stream containing the document.
See Also:
setPublicId(java.lang.String),
setSystemId(java.lang.String),
setEncoding(java.lang.String),
setByteStream(java.io.InputStream),
setCharacterStream(java.io.Reader)

InputSource

public InputSource(Reader characterStream)
Create a new input source with a character stream.

Application writers should use setSystemId() to provide a base for resolving relative URIs, and may use setPublicId to include a public identifier.

The character stream shall not include a byte order mark.

See Also:
setPublicId(java.lang.String),
setSystemId(java.lang.String),
setByteStream(java.io.InputStream),
setCharacterStream(java.io.Reader)
Method Detail

setPublicId

public void setPublicId(String publicId)
Set the public identifier for this input source.

The public identifier is always optional: if the application writer includes one, it will be provided as part of the location information.

Parameters:
publicId - The public identifier as a string.
See Also:
getPublicId(),
Locator.getPublicId(),
SAXParseException.getPublicId()

getPublicId

public String getPublicId()
Get the public identifier for this input source.

Returns:
The public identifier, or null if none was supplied.
See Also:
setPublicId(java.lang.String)

setSystemId

public void setSystemId(String systemId)
Set the system identifier for this input source.

The system identifier is optional if there is a byte stream or a character stream, but it is still useful to provide one, since the application can use it to resolve relative URIs and can include it in error messages and warnings (the parser will attempt to open a connection to the URI only if there is no byte stream or character stream specified).

If the application knows the character encoding of the object pointed to by the system identifier, it can register the encoding using the setEncoding method.

If the system identifier is a URL, it must be fully resolved (it may not be a relative URL).

Parameters:
systemId - The system identifier as a string.
See Also:
setEncoding(java.lang.String),
getSystemId(),
Locator.getSystemId(),
SAXParseException.getSystemId()

getSystemId

public String getSystemId()
Get the system identifier for this input source.

The getEncoding method will return the character encoding of the object pointed to, or null if unknown.

If the system ID is a URL, it will be fully resolved.

Returns:
The system identifier, or null if none was supplied.
See Also:
setSystemId(java.lang.String), getEncoding()

setByteStream

public void setByteStream(InputStream byteStream)
Set the byte stream for this input source.

The SAX parser will ignore this if there is also a character stream specified, but it will use a byte stream in preference to opening a URI connection itself.

If the application knows the character encoding of the byte stream, it should set it with the setEncoding method.

Parameters:
byteStream - A byte stream containing an XML document or other entity.
See Also:
setEncoding(java.lang.String),
getByteStream(),
getEncoding(),
InputStream

getByteStream

public InputStream getByteStream()
Get the byte stream for this input source.

The getEncoding method will return the character encoding for this byte stream, or null if unknown.

Returns:
The byte stream, or null if none was supplied.
See Also:
getEncoding(), setByteStream(java.io.InputStream)

setEncoding

public void setEncoding(String encoding)
Set the character encoding, if known.

The encoding must be a string acceptable for an XML encoding declaration (see section 4.3.3 of the XML 1.0 recommendation).

This method has no effect when the application provides a character stream.

Parameters:
encoding - A string describing the character encoding.
See Also:
setSystemId(java.lang.String),
setByteStream(java.io.InputStream),
getEncoding()

getEncoding

public String getEncoding()
Get the character encoding for a byte stream or URI. This value will be ignored when the application provides a character stream.

Returns:
The encoding, or null if none was supplied.
See Also:
setByteStream(java.io.InputStream),
getSystemId(),
getByteStream()

setCharacterStream

public void setCharacterStream(Reader characterStream)
Set the character stream for this input source.

If there is a character stream specified, the SAX parser will ignore any byte stream and will not attempt to open a URI connection to the system identifier.

Parameters:
characterStream - The character stream containing the XML document or other entity.
See Also:
getCharacterStream(), Reader

getCharacterStream

public Reader getCharacterStream()
Get the character stream for this input source.

Returns:
The character stream, or null if none was supplied.
See Also:
setCharacterStream(java.io.Reader)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Locator

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax
Interface Locator

All Known Subinterfaces:
Locator2
All Known Implementing Classes:
Locator2Impl, LocatorImpl
public interface Locator

Interface for associating a SAX event with a document location.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

If a SAX parser provides location information to the SAX application, it does so by implementing this interface and then passing an instance to the application using the content handler's setDocumentLocator method. The application can use the object to obtain the location of any other SAX event in the XML source document.

Note that the results returned by the object will be valid only during the scope of each callback method: the application will receive unpredictable results if it attempts to use the locator at any other time, or after parsing completes.

SAX parsers are not required to supply a locator, but they are very strongly encouraged to do so. If the parser supplies a locator, it must do so before reporting any other document events. If no locator has been set by the time the application receives the startDocument event, the application should assume that a locator is not available.

Since:
SAX 1.0
See Also:
ContentHandler.setDocumentLocator(org.xml.sax.Locator)

Method Summary
int | getColumnNumber() Return the column number where the current document event ends.
int | getLineNumber() Return the line number where the current document event ends.
String | getPublicId() Return the public identifier for the current document event.
String | getSystemId() Return the system identifier for the current document event.

Method Detail

getPublicId

String getPublicId()
Return the public identifier for the current document event.

The return value is the public identifier of the document entity or of the external parsed entity in which the markup triggering the event appears.

Returns:
A string containing the public identifier, or null if none is available.
See Also:
getSystemId()

getSystemId

String getSystemId()
Return the system identifier for the current document event.

The return value is the system identifier of the document entity or of the external parsed entity in which the markup triggering the event appears.

If the system identifier is a URL, the parser must resolve it fully before passing it to the application. For example, a file name must always be provided as a file:... URL, and other kinds of relative URI are also resolved against their bases.

Returns:
A string containing the system identifier, or null if none is available.
See Also:
getPublicId()

getLineNumber

int getLineNumber()
Return the line number where the current document event ends. Lines are delimited by line ends, which are defined in the XML specification.

Warning: The return value from the method is intended only as an approximation for the sake of diagnostics; it is not intended to provide sufficient information to edit the character content of the original XML document. In some cases, these "line" numbers match what would be displayed as columns, and in others they may not match the source text due to internal entity expansion.

The return value is an approximation of the line number in the document entity or external parsed entity where the markup triggering the event appears.

If possible, the SAX driver should provide the line position of the first character after the text associated with the document event. The first line is line 1.

Returns:
The line number, or -1 if none is available.
See Also:
getColumnNumber()

getColumnNumber

int getColumnNumber()
Return the column number where the current document event ends. This is one-based number of Java char values since the last line end.

Warning: The return value from the method is intended only as an approximation for the sake of diagnostics; it is not intended to provide sufficient information to edit the character content of the original XML document. For example, when lines contain combining character sequences, wide characters, surrogate pairs, or bi-directional text, the value may not correspond to the column in a text editor's display.

The return value is an approximation of the column number in the document entity or external parsed entity where the markup triggering the event appears.

If possible, the SAX driver should provide the line position of the first character after the text associated with the document event. The first column in each line is column 1.

Returns:
The column number, or -1 if none is available.
See Also:
getLineNumber()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Parser

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax
Interface Parser

All Known Implementing Classes:
XMLReaderAdapter
Deprecated. This interface has been replaced by the SAX2 XMLReader interface, which includes Namespace support.

public interface Parser

Basic interface for SAX (Simple API for XML) parsers.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This was the main event supplier interface for SAX1; it has been replaced in SAX2 by XMLReader, which includes Namespace support and sophisticated configurability and extensibility.

All SAX1 parsers must implement this basic interface: it allows applications to register handlers for different types of events and to initiate a parse from a URI, or a character stream.

All SAX1 parsers must also implement a zero-argument constructor (though other constructors are also allowed).

SAX1 parsers are reusable but not re-entrant: the application may reuse a parser object (possibly with a different input source) once the first parse has completed successfully, but it may not invoke the parse() methods recursively within a parse.

Since:
SAX 1.0
See Also:
EntityResolver, DTDHandler, DocumentHandler, ErrorHandler, HandlerBase, InputSource

Method Summary
void | parse(InputSource source) Deprecated. Parse an XML document.
void | parse(String systemId) Deprecated. Parse an XML document from a system identifier (URI).
void | setDocumentHandler(DocumentHandler handler) Deprecated. Allow an application to register a document event handler.
void | setDTDHandler(DTDHandler handler) Deprecated. Allow an application to register a DTD event handler.
void | setEntityResolver(EntityResolver resolver) Deprecated. Allow an application to register a custom entity resolver.
void | setErrorHandler(ErrorHandler handler) Deprecated. Allow an application to register an error event handler.
void | setLocale(Locale locale) Deprecated. Allow an application to request a locale for errors and warnings.

Method Detail

setLocale

void setLocale(Locale locale)
               throws SAXException
Deprecated.
Allow an application to request a locale for errors and warnings.

SAX parsers are not required to provide localisation for errors and warnings; if they cannot support the requested locale, however, they must throw a SAX exception. Applications may not request a locale change in the middle of a parse.

Parameters:
locale - A Java Locale object.
Throws:
SAXException - Throws an exception (using the previous or default locale) if the requested locale is not supported.
See Also:
SAXException, SAXParseException

setEntityResolver

void setEntityResolver(EntityResolver resolver)
Deprecated.
Allow an application to register a custom entity resolver.

If the application does not register an entity resolver, the SAX parser will resolve system identifiers and open connections to entities itself (this is the default behaviour implemented in HandlerBase).

Applications may register a new or different entity resolver in the middle of a parse, and the SAX parser must begin using the new resolver immediately.

Parameters:
resolver - The object for resolving entities.
See Also:
EntityResolver, HandlerBase

setDTDHandler

void setDTDHandler(DTDHandler handler)
Deprecated.
Allow an application to register a DTD event handler.

If the application does not register a DTD handler, all DTD events reported by the SAX parser will be silently ignored (this is the default behaviour implemented by HandlerBase).

Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately.

Parameters:
handler - The DTD handler.
See Also:
DTDHandler, HandlerBase

setDocumentHandler

void setDocumentHandler(DocumentHandler handler)
Deprecated.
Allow an application to register a document event handler.

If the application does not register a document handler, all document events reported by the SAX parser will be silently ignored (this is the default behaviour implemented by HandlerBase).

Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately.

Parameters:
handler - The document handler.
See Also:
DocumentHandler, HandlerBase

setErrorHandler

void setErrorHandler(ErrorHandler handler)
Deprecated.
Allow an application to register an error event handler.

If the application does not register an error event handler, all error events reported by the SAX parser will be silently ignored, except for fatalError, which will throw a SAXException (this is the default behaviour implemented by HandlerBase).

Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately.

Parameters:
handler - The error handler.
See Also:
ErrorHandler, SAXException, HandlerBase

parse

void parse(InputSource source)
           throws SAXException,
                  IOException
Deprecated.
Parse an XML document.

The application can use this method to instruct the SAX parser to begin parsing an XML document from any valid input source (a character stream, a byte stream, or a URI).

Applications may not invoke this method while a parse is in progress (they should create a new Parser instead for each additional XML document). Once a parse is complete, an application may reuse the same Parser object, possibly with a different input source.

Parameters:
source - The input source for the top-level of the XML document.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
IOException - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
See Also:
InputSource,
parse(java.lang.String),
setEntityResolver(org.xml.sax.EntityResolver),
setDTDHandler(org.xml.sax.DTDHandler),
setDocumentHandler(org.xml.sax.DocumentHandler),
setErrorHandler(org.xml.sax.ErrorHandler)

parse

void parse(String systemId)
           throws SAXException,
                  IOException
Deprecated.
Parse an XML document from a system identifier (URI).

This method is a shortcut for the common case of reading a document from a system identifier. It is the exact equivalent of the following:

 parse(new InputSource(systemId));

If the system identifier is a URL, it must be fully resolved by the application before it is passed to the parser.

Parameters:
systemId - The system identifier (URI).
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
IOException - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
See Also:
parse(org.xml.sax.InputSource)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SAXException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax
Class SAXException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.xml.sax.SAXException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
SAXNotRecognizedException, SAXNotSupportedException, SAXParseException
public class SAXException
extends Exception

Encapsulate a general SAX error or warning.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This class can contain basic error or warning information from either the XML parser or the application: a parser writer or application writer can subclass it to provide additional functionality. SAX handlers may throw this exception or any exception subclassed from it.

If the application needs to pass through other types of exceptions, it must wrap those exceptions in a SAXException or an exception derived from a SAXException.

If the parser or application needs to include information about a specific location in an XML document, it should use the SAXParseException subclass.

Since:
SAX 1.0
See Also:
SAXParseException, Serialized Form

Constructor Summary
SAXException()
Create a new SAXException.
SAXException(Exception e)
Create a new SAXException wrapping an existing exception.
SAXException(String message)
Create a new SAXException.
SAXException(String message, Exception e)
Create a new SAXException from an existing exception.
Method Summary
Exception | getException() Return the embedded exception, if any.
String | getMessage() Return a detail message for this exception.
String | toString() Override toString to pick up any embedded exception.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SAXException

public SAXException()
Create a new SAXException.

SAXException

public SAXException(String message)
Create a new SAXException.

Parameters:
message - The error or warning message.

SAXException

public SAXException(Exception e)
Create a new SAXException wrapping an existing exception.

The existing exception will be embedded in the new one, and its message will become the default message for the SAXException.

Parameters:
e - The exception to be wrapped in a SAXException.

SAXException

public SAXException(String message,
                    Exception e)
Create a new SAXException from an existing exception.

The existing exception will be embedded in the new one, but the new exception will have its own message.

Parameters:
message - The detail message.
e - The exception to be wrapped in a SAXException.
Method Detail

getMessage

public String getMessage()
Return a detail message for this exception.

If there is an embedded exception, and if the SAXException has no detail message of its own, this method will return the detail message from the embedded exception.

Overrides:
getMessage in class Throwable
Returns:
The error or warning message.

getException

public Exception getException()
Return the embedded exception, if any.

Returns:
The embedded exception, or null if there is none.

toString

public String toString()
Override toString to pick up any embedded exception.

Overrides:
toString in class Throwable
Returns:
A string representation of this exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SAXNotRecognizedException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax
Class SAXNotRecognizedException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.xml.sax.SAXException
                extended by  org.xml.sax.SAXNotRecognizedException
All Implemented Interfaces:
Serializable
public class SAXNotRecognizedException
extends SAXException

Exception class for an unrecognized identifier.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

An XMLReader will throw this exception when it finds an unrecognized feature or property identifier; SAX applications and extensions may use this class for other, similar purposes.

Since:
SAX 2.0
See Also:
SAXNotSupportedException, Serialized Form

Constructor Summary
SAXNotRecognizedException()
Default constructor.
SAXNotRecognizedException(String message)
Construct a new exception with the given message.
Method Summary
Methods inherited from class org.xml.sax.SAXException
getException, getMessage, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SAXNotRecognizedException

public SAXNotRecognizedException()
Default constructor.

SAXNotRecognizedException

public SAXNotRecognizedException(String message)
Construct a new exception with the given message.

Parameters:
message - The text message of the exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SAXNotSupportedException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax
Class SAXNotSupportedException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.xml.sax.SAXException
                extended by  org.xml.sax.SAXNotSupportedException
All Implemented Interfaces:
Serializable
public class SAXNotSupportedException
extends SAXException

Exception class for an unsupported operation.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

An XMLReader will throw this exception when it recognizes a feature or property identifier, but cannot perform the requested operation (setting a state or value). Other SAX2 applications and extensions may use this class for similar purposes.

Since:
SAX 2.0
See Also:
SAXNotRecognizedException, Serialized Form

Constructor Summary
SAXNotSupportedException()
Construct a new exception with no message.
SAXNotSupportedException(String message)
Construct a new exception with the given message.
Method Summary
Methods inherited from class org.xml.sax.SAXException
getException, getMessage, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SAXNotSupportedException

public SAXNotSupportedException()
Construct a new exception with no message.

SAXNotSupportedException

public SAXNotSupportedException(String message)
Construct a new exception with the given message.

Parameters:
message - The text message of the exception.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


SAXParseException

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax
Class SAXParseException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  org.xml.sax.SAXException
                extended by  org.xml.sax.SAXParseException
All Implemented Interfaces:
Serializable
public class SAXParseException
extends SAXException

Encapsulate an XML parse error or warning.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

This exception may include information for locating the error in the original XML document, as if it came from a Locator object. Note that although the application will receive a SAXParseException as the argument to the handlers in the ErrorHandler interface, the application is not actually required to throw the exception; instead, it can simply read the information in it and take a different action.

Since this exception is a subclass of SAXException, it inherits the ability to wrap another exception.

Since:
SAX 1.0
See Also:
SAXException, Locator, ErrorHandler, Serialized Form

Constructor Summary
SAXParseException(String message, Locator locator)
Create a new SAXParseException from a message and a Locator.
SAXParseException(String message, Locator locator, Exception e)
Wrap an existing exception in a SAXParseException.
SAXParseException(String message, String publicId, String systemId, int lineNumber, int columnNumber)
Create a new SAXParseException.
SAXParseException(String message, String publicId, String systemId, int lineNumber, int columnNumber, Exception e)
Create a new SAXParseException with an embedded exception.
Method Summary
int | getColumnNumber() The column number of the end of the text where the exception occurred.
int | getLineNumber() The line number of the end of the text where the exception occurred.
String | getPublicId() Get the public identifier of the entity where the exception occurred.
String | getSystemId() Get the system identifier of the entity where the exception occurred.
Methods inherited from class org.xml.sax.SAXException
getException, getMessage, toString
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SAXParseException

public SAXParseException(String message,
                         Locator locator)
Create a new SAXParseException from a message and a Locator.

This constructor is especially useful when an application is creating its own exception from within a ContentHandler callback.

Parameters:
message - The error or warning message.
locator - The locator object for the error or warning (may be null).
See Also:
Locator

SAXParseException

public SAXParseException(String message,
                         Locator locator,
                         Exception e)
Wrap an existing exception in a SAXParseException.

This constructor is especially useful when an application is creating its own exception from within a ContentHandler callback, and needs to wrap an existing exception that is not a subclass of SAXException.

Parameters:
message - The error or warning message, or null to use the message from the embedded exception.
locator - The locator object for the error or warning (may be null).
e - Any exception.
See Also:
Locator

SAXParseException

public SAXParseException(String message,
                         String publicId,
                         String systemId,
                         int lineNumber,
                         int columnNumber)
Create a new SAXParseException.

This constructor is most useful for parser writers.

All parameters except the message are as if they were provided by a Locator. For example, if the system identifier is a URL (including relative filename), the caller must resolve it fully before creating the exception.

Parameters:
message - The error or warning message.
publicId - The public identifier of the entity that generated the error or warning.
systemId - The system identifier of the entity that generated the error or warning.
lineNumber - The line number of the end of the text that caused the error or warning.
columnNumber - The column number of the end of the text that cause the error or warning.

SAXParseException

public SAXParseException(String message,
                         String publicId,
                         String systemId,
                         int lineNumber,
                         int columnNumber,
                         Exception e)
Create a new SAXParseException with an embedded exception.

This constructor is most useful for parser writers who need to wrap an exception that is not a subclass of SAXException.

All parameters except the message and exception are as if they were provided by a Locator. For example, if the system identifier is a URL (including relative filename), the caller must resolve it fully before creating the exception.

Parameters:
message - The error or warning message, or null to use the message from the embedded exception.
publicId - The public identifier of the entity that generated the error or warning.
systemId - The system identifier of the entity that generated the error or warning.
lineNumber - The line number of the end of the text that caused the error or warning.
columnNumber - The column number of the end of the text that cause the error or warning.
e - Another exception to embed in this one.
Method Detail

getPublicId

public String getPublicId()
Get the public identifier of the entity where the exception occurred.

Returns:
A string containing the public identifier, or null if none is available.
See Also:
Locator.getPublicId()

getSystemId

public String getSystemId()
Get the system identifier of the entity where the exception occurred.

If the system identifier is a URL, it will have been resolved fully.

Returns:
A string containing the system identifier, or null if none is available.
See Also:
Locator.getSystemId()

getLineNumber

public int getLineNumber()
The line number of the end of the text where the exception occurred.

The first line is line 1.

Returns:
An integer representing the line number, or -1 if none is available.
See Also:
Locator.getLineNumber()

getColumnNumber

public int getColumnNumber()
The column number of the end of the text where the exception occurred.

The first column in a line is position 1.

Returns:
An integer representing the column number, or -1 if none is available.
See Also:
Locator.getColumnNumber()
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLFilter

PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.xml.sax
Interface XMLFilter

All Superinterfaces:
XMLReader
All Known Implementing Classes:
XMLFilterImpl
public interface XMLFilter
extends XMLReader

Interface for an XML filter.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

An XML filter is like an XML reader, except that it obtains its events from another XML reader rather than a primary source like an XML document or database. Filters can modify a stream of events as they pass on to the final application.

The XMLFilterImpl helper class provides a convenient base for creating SAX2 filters, by passing on all EntityResolver, DTDHandler, ContentHandler and ErrorHandler events automatically.

Since:
SAX 2.0
See Also:
XMLFilterImpl

Method Summary
XMLReader | getParent() Get the parent reader.
void | setParent(XMLReader parent) Set the parent reader.
Methods inherited from interface org.xml.sax.XMLReader
getContentHandler, getDTDHandler, getEntityResolver, getErrorHandler, getFeature, getProperty, parse, parse, setContentHandler, setDTDHandler, setEntityResolver, setErrorHandler, setFeature, setProperty

Method Detail

setParent

void setParent(XMLReader parent)
Set the parent reader.

This method allows the application to link the filter to a parent reader (which may be another filter). The argument may not be null.

Parameters:
parent - The parent reader.

getParent

XMLReader getParent()
Get the parent reader.

This method allows the application to query the parent reader (which may be another filter). It is generally a bad idea to perform any operations on the parent reader directly: they should all pass through this filter.

Returns:
The parent filter, or null if none has been set.
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


XMLReader

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

org.xml.sax
Interface XMLReader

All Known Subinterfaces:
XMLFilter
All Known Implementing Classes:
ParserAdapter, XMLFilterImpl
public interface XMLReader

Interface for reading an XML document using callbacks.

This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

Note: despite its name, this interface does not extend the standard Java Reader interface, because reading XML is a fundamentally different activity than reading character data.

XMLReader is the interface that an XML parser's SAX2 driver must implement. This interface allows an application to set and query features and properties in the parser, to register event handlers for document processing, and to initiate a document parse.

All SAX interfaces are assumed to be synchronous: the parse methods must not return until parsing is complete, and readers must wait for an event-handler callback to return before reporting the next event.

This interface replaces the (now deprecated) SAX 1.0 Parser interface. The XMLReader interface contains two important enhancements over the old Parser interface (as well as some minor ones):

  1. it adds a standard way to query and set features and properties; and
  2. it adds Namespace support, which is required for many higher-level XML standards.

There are adapters available to convert a SAX1 Parser to a SAX2 XMLReader and vice-versa.

Since:
SAX 2.0
See Also:
XMLFilter, ParserAdapter, XMLReaderAdapter

Method Summary
ContentHandler | getContentHandler() Return the current content handler.
DTDHandler | getDTDHandler() Return the current DTD handler.
EntityResolver | getEntityResolver() Return the current entity resolver.
ErrorHandler | getErrorHandler() Return the current error handler.
boolean | getFeature(String name) Look up the value of a feature flag.
Object | getProperty(String name) Look up the value of a property.
void | parse(InputSource input) Parse an XML document.
void | parse(String systemId) Parse an XML document from a system identifier (URI).
void | setContentHandler(ContentHandler handler) Allow an application to register a content event handler.
void | setDTDHandler(DTDHandler handler) Allow an application to register a DTD event handler.
void | setEntityResolver(EntityResolver resolver) Allow an application to register an entity resolver.
void | setErrorHandler(ErrorHandler handler) Allow an application to register an error event handler.
void | setFeature(String name, boolean value) Set the value of a feature flag.
void | setProperty(String name, Object value) Set the value of a property.

Method Detail

getFeature

boolean getFeature(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException
Look up the value of a feature flag.

The feature name is any fully-qualified URI. It is possible for an XMLReader to recognize a feature name but temporarily be unable to return its value. Some feature values may be available only in specific contexts, such as before, during, or after a parse. Also, some feature values may not be programmatically accessible. (In the case of an adapter for SAX1 Parser, there is no implementation-independent way to expose whether the underlying parser is performing validation, expanding external entities, and so forth.)

All XMLReaders are required to recognize the http://xml.org/sax/features/namespaces and the http://xml.org/sax/features/namespace-prefixes feature names.

Typical usage is something like this:

 XMLReader r = new MySAXDriver();

                         // try to activate validation
 try {
   r.setFeature("http://xml.org/sax/features/validation", true);
 } catch (SAXException e) {
   System.err.println("Cannot activate validation.");
 }

                         // register event handlers
 r.setContentHandler(new MyContentHandler());
 r.setErrorHandler(new MyErrorHandler());

                         // parse the first document
 try {
   r.parse("http://www.foo.com/mydoc.xml");
 } catch (IOException e) {
   System.err.println("I/O exception reading XML document");
 } catch (SAXException e) {
   System.err.println("XML exception reading document.");
 }

Implementors are free (and encouraged) to invent their own features, using names built on their own URIs.

Parameters:
name - The feature name, which is a fully-qualified URI.
Returns:
The current value of the feature (true or false).
Throws:
SAXNotRecognizedException - If the feature value can't be assigned or retrieved.
SAXNotSupportedException - When the XMLReader recognizes the feature name but cannot determine its value at this time.
See Also:
setFeature(java.lang.String, boolean)

setFeature

void setFeature(String name,
                boolean value)
                throws SAXNotRecognizedException,
                       SAXNotSupportedException
Set the value of a feature flag.

The feature name is any fully-qualified URI. It is possible for an XMLReader to expose a feature value but to be unable to change the current value. Some feature values may be immutable or mutable only in specific contexts, such as before, during, or after a parse.

All XMLReaders are required to support setting http://xml.org/sax/features/namespaces to true and http://xml.org/sax/features/namespace-prefixes to false.

Parameters:
name - The feature name, which is a fully-qualified URI.
value - The requested value of the feature (true or false).
Throws:
SAXNotRecognizedException - If the feature value can't be assigned or retrieved.
SAXNotSupportedException - When the XMLReader recognizes the feature name but cannot set the requested value.
See Also:
getFeature(java.lang.String)

getProperty

Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException
Look up the value of a property.

The property name is any fully-qualified URI. It is possible for an XMLReader to recognize a property name but temporarily be unable to return its value. Some property values may be available only in specific contexts, such as before, during, or after a parse.

XMLReaders are not required to recognize any specific property names, though an initial core set is documented for SAX2.

Implementors are free (and encouraged) to invent their own properties, using names built on their own URIs.

Parameters:
name - The property name, which is a fully-qualified URI.
Returns:
The current value of the property.
Throws:
SAXNotRecognizedException - If the property value can't be assigned or retrieved.
SAXNotSupportedException - When the XMLReader recognizes the property name but cannot determine its value at this time.
See Also:
setProperty(java.lang.String, java.lang.Object)

setProperty

void setProperty(String name,
                 Object value)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException
Set the value of a property.

The property name is any fully-qualified URI. It is possible for an XMLReader to recognize a property name but to be unable to change the current value. Some property values may be immutable or mutable only in specific contexts, such as before, during, or after a parse.

XMLReaders are not required to recognize setting any specific property names, though a core set is defined by SAX2.

This method is also the standard mechanism for setting extended handlers.

Parameters:
name - The property name, which is a fully-qualified URI.
value - The requested value for the property.
Throws:
SAXNotRecognizedException - If the property value can't be assigned or retrieved.
SAXNotSupportedException - When the XMLReader recognizes the property name but cannot set the requested value.

setEntityResolver

void setEntityResolver(EntityResolver resolver)
Allow an application to register an entity resolver.

If the application does not register an entity resolver, the XMLReader will perform its own default resolution.

Applications may register a new or different resolver in the middle of a parse, and the SAX parser must begin using the new resolver immediately.

Parameters:
resolver - The entity resolver.
See Also:
getEntityResolver()

getEntityResolver

EntityResolver getEntityResolver()
Return the current entity resolver.

Returns:
The current entity resolver, or null if none has been registered.
See Also:
setEntityResolver(org.xml.sax.EntityResolver)

setDTDHandler

void setDTDHandler(DTDHandler handler)
Allow an application to register a DTD event handler.

If the application does not register a DTD handler, all DTD events reported by the SAX parser will be silently ignored.

Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately.

Parameters:
handler - The DTD handler.
See Also:
getDTDHandler()

getDTDHandler

DTDHandler getDTDHandler()
Return the current DTD handler.

Returns:
The current DTD handler, or null if none has been registered.
See Also:
setDTDHandler(org.xml.sax.DTDHandler)

setContentHandler

void setContentHandler(ContentHandler handler)
Allow an application to register a content event handler.

If the application does not register a content handler, all content events reported by the SAX parser will be silently ignored.

Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately.

Parameters:
handler - The content handler.
See Also:
getContentHandler()

getContentHandler

ContentHandler getContentHandler()
Return the current content handler.

Returns:
The current content handler, or null if none has been registered.
See Also:
setContentHandler(org.xml.sax.ContentHandler)

setErrorHandler

void setErrorHandler(ErrorHandler handler)
Allow an application to register an error event handler.

If the application does not register an error handler, all error events reported by the SAX parser will be silently ignored; however, normal processing may not continue. It is highly recommended that all SAX applications implement an error handler to avoid unexpected bugs.

Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately.

Parameters:
handler - The error handler.
See Also:
getErrorHandler()

getErrorHandler

ErrorHandler getErrorHandler()
Return the current error handler.

Returns:
The current error handler, or null if none has been registered.
See Also:
setErrorHandler(org.xml.sax.ErrorHandler)

parse

void parse(InputSource input)
           throws IOException,
                  SAXException
Parse an XML document.

The application can use this method to instruct the XML reader to begin parsing an XML document from any valid input source (a character stream, a byte stream, or a URI).

Applications may not invoke this method while a parse is in progress (they should create a new XMLReader instead for each nested XML document). Once a parse is complete, an application may reuse the same XMLReader object, possibly with a different input source. Configuration of the XMLReader object (such as handler bindings and values established for feature flags and properties) is unchanged by completion of a parse, unless the definition of that aspect of the configuration explicitly specifies other behavior. (For example, feature flags or properties exposing characteristics of the document being parsed.)

During the parse, the XMLReader will provide information about the XML document through the registered event handlers.

This method is synchronous: it will not return until parsing has ended. If a client application wants to terminate parsing early, it should throw an exception.

Parameters:
input - The input source for the top-level of the XML document.
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
IOException - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
See Also:
InputSource,
parse(java.lang.String),
setEntityResolver(org.xml.sax.EntityResolver),
setDTDHandler(org.xml.sax.DTDHandler),
setContentHandler(org.xml.sax.ContentHandler),
setErrorHandler(org.xml.sax.ErrorHandler)

parse

void parse(String systemId)
           throws IOException,
                  SAXException
Parse an XML document from a system identifier (URI).

This method is a shortcut for the common case of reading a document from a system identifier. It is the exact equivalent of the following:

 parse(new InputSource(systemId));

If the system identifier is a URL, it must be fully resolved by the application before it is passed to the parser.

Parameters:
systemId - The system identifier (URI).
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
IOException - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
See Also:
parse(org.xml.sax.InputSource)
Overview Package Class Use Tree Deprecated Index Help
Java™ Platform
Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


mirror

Mirror API
PREV NEXT FRAMES NO FRAMES

Mirror API

The Mirror API is used to model the semantic structure of a program.

See:
Description

Packages
com.sun.mirror.apt | Classes used to communicate information between annotation processors and an annotation processing tool.
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.type | Interfaces used to model types.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

The Mirror API is used to model the semantic structure of a program. It provides representations of the entities declared in a program, such as classes, methods, and fields. Constructs below the method level, such as individual statements and expressions, are not represented.

Also included is support for writing annotation processors to examine and process the annotations of program elements. An annotation processor may, as an example, create new source files and XML documents to be used in conjunction with the original code.

Characteristics of the API

A program is represented at the language level, rather than at the level of the virtual machine. Nested classes, for example, are handled as first-class constructs, rather than in the translated form understood by the VM. Both source code and compiled code (class files) may be modeled in this way.

Programs are modeled in their static, or build-time, form. This differs from the reflection API, which provides run-time information about classes and objects.

The API does not provide direct support for generating new code.

Declarations and Types

The mirror API represents program constructs principally through the Declaration interface and its hierarchy of subinterfaces in the package com.sun.mirror.declaration. A Declaration represents a program element such as a package, class, or method. The interface hierarchy is depicted here.

Types are represented by the TypeMirror interface and its hierarchy of subinterfaces in the package com.sun.mirror.type. Types include primitive types, class and interface types, array types, type variables, and wildcards. The interface hierarchy is depicted here.

The API makes a clear distinction between declarations and types. This is most significant for generic types, where a single declaration can define an infinite family of types. For example, the declaration of java.util.Set defines the raw type java.util.Set, the parameterized type java.util.Set<String>, and much more. Only the declaration can be annotated, for example, and only a type can appear in a method signature.

A program being modeled may be incomplete, in that it may depend on an unknown class or interface type. This may be the result of a processing error such as a missing class file, or perhaps the missing type is to be created by an annotation processor. See DeclaredType for information on how such unknown types are handled.

Utilities and Tool Support

The com.sun.mirror.util package provides utilities to assist in the processing of declarations and types. Included is support for using the visitor design pattern when operating on declaration and type objects.

The com.sun.mirror.apt package supports the writing of annotation processors. It provides the mechanism for them to interact with an annotation processing tool.

Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


 All Classes
AnnotationMirror
AnnotationProcessor
AnnotationProcessorEnvironment
AnnotationProcessorFactory
AnnotationProcessorListener
AnnotationProcessors
AnnotationType
AnnotationTypeDeclaration
AnnotationTypeElementDeclaration
AnnotationValue
ArrayType
ClassDeclaration
ClassType
ConstructorDeclaration
Declaration
DeclarationFilter
Declarations
DeclarationVisitor
DeclarationVisitors
DeclaredType
EnumConstantDeclaration
EnumDeclaration
EnumType
ExecutableDeclaration
FieldDeclaration
Filer
Filer.Location
InterfaceDeclaration
InterfaceType
MemberDeclaration
Messager
MethodDeclaration
MirroredTypeException
MirroredTypesException
Modifier
PackageDeclaration
ParameterDeclaration
PrimitiveType
PrimitiveType.Kind
ReferenceType
RoundCompleteEvent
RoundCompleteListener
RoundState
SimpleDeclarationVisitor
SimpleTypeVisitor
SourcePosition
TypeDeclaration
TypeMirror
TypeParameterDeclaration
Types
TypeVariable
TypeVisitor
VoidType
WildcardType


API Help

Mirror API
PREV NEXT FRAMES NO FRAMES

How This API Document Is Organized

This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.

Overview

The Overview page is the front page of this API document and provides a list of all packages with a summary for each. This page can also contain an overall description of the set of packages.

Package

Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain four categories:

  • Interfaces (italic)
  • Classes
  • Enums
  • Exceptions
  • Errors
  • Annotation Types

Class/Interface

Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:

  • Class inheritance diagram
  • Direct Subclasses
  • All Known Subinterfaces
  • All Known Implementing Classes
  • Class/interface declaration
  • Class/interface description

  • Nested Class Summary
  • Field Summary
  • Constructor Summary
  • Method Summary

  • Field Detail
  • Constructor Detail
  • Method Detail
Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.

Annotation Type

Each annotation type has its own separate page with the following sections:

  • Annotation Type declaration
  • Annotation Type description
  • Required Element Summary
  • Optional Element Summary
  • Element Detail

Enum

Each enum has its own separate page with the following sections:

  • Enum declaration
  • Enum description
  • Enum Constant Summary
  • Enum Constant Detail

Use

Each documented package, class and interface has its own Use page. This page describes what packages, classes, methods, constructors and fields use any part of the given class or package. Given a class or interface A, its Use page includes subclasses of A, fields declared as A, methods that return A, and methods and constructors with parameters of type A. You can access this page by first going to the package, class or interface, then clicking on the "Use" link in the navigation bar.

Tree (Class Hierarchy)

There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with java.lang.Object. The interfaces do not inherit from java.lang.Object.
  • When viewing the Overview page, clicking on "Tree" displays the hierarchy for all packages.
  • When viewing a particular package, class or interface page, clicking "Tree" displays the hierarchy for only that package.

Deprecated API

The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.

Index

The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.

Prev/Next

These links take you to the next or previous class, interface, package, or related page.

Frames/No Frames

These links show and hide the HTML frames. All pages are available with or without frames.

Serialized Form

Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.

Constant Field Values

The Constant Field Values page lists the static final fields and their values.

This help file applies to API documentation generated using the standard doclet.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Constant Field Values

Contents
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Deprecated List

Mirror API
PREV NEXT FRAMES NO FRAMES

Deprecated API

Contents
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Hierarchy

Mirror API
PREV NEXT FRAMES NO FRAMES

Hierarchy For All Packages

Package Hierarchies:
com.sun.mirror.apt, com.sun.mirror.declaration, com.sun.mirror.type, com.sun.mirror.util

Class Hierarchy

  • java.lang.Object
    • com.sun.mirror.apt.AnnotationProcessors
    • com.sun.mirror.util.DeclarationFilter
    • com.sun.mirror.util.DeclarationVisitors
    • java.util.EventObject (implements java.io.Serializable)
      • com.sun.mirror.apt.RoundCompleteEvent
    • com.sun.mirror.util.SimpleDeclarationVisitor (implements com.sun.mirror.util.DeclarationVisitor)
    • com.sun.mirror.util.SimpleTypeVisitor (implements com.sun.mirror.util.TypeVisitor)
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.lang.RuntimeException
          • com.sun.mirror.type.MirroredTypeException
          • com.sun.mirror.type.MirroredTypesException

Interface Hierarchy

  • com.sun.mirror.declaration.AnnotationMirror
  • com.sun.mirror.apt.AnnotationProcessor
  • com.sun.mirror.apt.AnnotationProcessorEnvironment
  • com.sun.mirror.apt.AnnotationProcessorFactory
  • com.sun.mirror.declaration.AnnotationValue
  • com.sun.mirror.declaration.Declaration
    • com.sun.mirror.declaration.AnnotationTypeDeclaration
    • com.sun.mirror.declaration.AnnotationTypeElementDeclaration
    • com.sun.mirror.declaration.ClassDeclaration
      • com.sun.mirror.declaration.EnumDeclaration
    • com.sun.mirror.declaration.ConstructorDeclaration
    • com.sun.mirror.declaration.EnumConstantDeclaration
    • com.sun.mirror.declaration.EnumDeclaration
    • com.sun.mirror.declaration.ExecutableDeclaration
      • com.sun.mirror.declaration.AnnotationTypeElementDeclaration
      • com.sun.mirror.declaration.ConstructorDeclaration
      • com.sun.mirror.declaration.MethodDeclaration
        • com.sun.mirror.declaration.AnnotationTypeElementDeclaration
    • com.sun.mirror.declaration.FieldDeclaration
      • com.sun.mirror.declaration.EnumConstantDeclaration
    • com.sun.mirror.declaration.InterfaceDeclaration
      • com.sun.mirror.declaration.AnnotationTypeDeclaration
    • com.sun.mirror.declaration.MemberDeclaration
      • com.sun.mirror.declaration.AnnotationTypeDeclaration
      • com.sun.mirror.declaration.AnnotationTypeElementDeclaration
      • com.sun.mirror.declaration.ClassDeclaration
        • com.sun.mirror.declaration.EnumDeclaration
      • com.sun.mirror.declaration.ConstructorDeclaration
      • com.sun.mirror.declaration.EnumConstantDeclaration
      • com.sun.mirror.declaration.EnumDeclaration
      • com.sun.mirror.declaration.ExecutableDeclaration
        • com.sun.mirror.declaration.AnnotationTypeElementDeclaration
        • com.sun.mirror.declaration.ConstructorDeclaration
        • com.sun.mirror.declaration.MethodDeclaration
          • com.sun.mirror.declaration.AnnotationTypeElementDeclaration
      • com.sun.mirror.declaration.FieldDeclaration
        • com.sun.mirror.declaration.EnumConstantDeclaration
      • com.sun.mirror.declaration.InterfaceDeclaration
        • com.sun.mirror.declaration.AnnotationTypeDeclaration
      • com.sun.mirror.declaration.MethodDeclaration
        • com.sun.mirror.declaration.AnnotationTypeElementDeclaration
      • com.sun.mirror.declaration.TypeDeclaration
        • com.sun.mirror.declaration.AnnotationTypeDeclaration
        • com.sun.mirror.declaration.ClassDeclaration
          • com.sun.mirror.declaration.EnumDeclaration
        • com.sun.mirror.declaration.EnumDeclaration
        • com.sun.mirror.declaration.InterfaceDeclaration
          • com.sun.mirror.declaration.AnnotationTypeDeclaration
    • com.sun.mirror.declaration.MethodDeclaration
      • com.sun.mirror.declaration.AnnotationTypeElementDeclaration
    • com.sun.mirror.declaration.PackageDeclaration
    • com.sun.mirror.declaration.ParameterDeclaration
    • com.sun.mirror.declaration.TypeDeclaration
      • com.sun.mirror.declaration.AnnotationTypeDeclaration
      • com.sun.mirror.declaration.ClassDeclaration
        • com.sun.mirror.declaration.EnumDeclaration
      • com.sun.mirror.declaration.EnumDeclaration
      • com.sun.mirror.declaration.InterfaceDeclaration
        • com.sun.mirror.declaration.AnnotationTypeDeclaration
    • com.sun.mirror.declaration.TypeParameterDeclaration
  • com.sun.mirror.util.Declarations
  • com.sun.mirror.util.DeclarationVisitor
  • java.util.EventListener
    • com.sun.mirror.apt.AnnotationProcessorListener
      • com.sun.mirror.apt.RoundCompleteListener
    • com.sun.mirror.apt.RoundCompleteListener
  • com.sun.mirror.apt.Filer
  • com.sun.mirror.apt.Messager
  • com.sun.mirror.apt.RoundState
  • com.sun.mirror.util.SourcePosition
  • com.sun.mirror.type.TypeMirror
    • com.sun.mirror.type.AnnotationType
    • com.sun.mirror.type.ArrayType
    • com.sun.mirror.type.ClassType
      • com.sun.mirror.type.EnumType
    • com.sun.mirror.type.DeclaredType
      • com.sun.mirror.type.AnnotationType
      • com.sun.mirror.type.ClassType
        • com.sun.mirror.type.EnumType
      • com.sun.mirror.type.EnumType
      • com.sun.mirror.type.InterfaceType
        • com.sun.mirror.type.AnnotationType
    • com.sun.mirror.type.EnumType
    • com.sun.mirror.type.InterfaceType
      • com.sun.mirror.type.AnnotationType
    • com.sun.mirror.type.PrimitiveType
    • com.sun.mirror.type.ReferenceType
      • com.sun.mirror.type.AnnotationType
      • com.sun.mirror.type.ArrayType
      • com.sun.mirror.type.ClassType
        • com.sun.mirror.type.EnumType
      • com.sun.mirror.type.DeclaredType
        • com.sun.mirror.type.AnnotationType
        • com.sun.mirror.type.ClassType
          • com.sun.mirror.type.EnumType
        • com.sun.mirror.type.EnumType
        • com.sun.mirror.type.InterfaceType
          • com.sun.mirror.type.AnnotationType
      • com.sun.mirror.type.EnumType
      • com.sun.mirror.type.InterfaceType
        • com.sun.mirror.type.AnnotationType
      • com.sun.mirror.type.TypeVariable
    • com.sun.mirror.type.TypeVariable
    • com.sun.mirror.type.VoidType
    • com.sun.mirror.type.WildcardType
  • com.sun.mirror.util.Types
  • com.sun.mirror.util.TypeVisitor

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • com.sun.mirror.apt.Filer.Location
      • com.sun.mirror.declaration.Modifier
      • com.sun.mirror.type.PrimitiveType.Kind
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Index

Mirror API
PREV NEXT FRAMES NO FRAMES
A C D E F G H I L M N O P R S T V W

A

accept(DeclarationVisitor) - Method in interface com.sun.mirror.declaration.Declaration
Applies a visitor to this declaration.
accept(TypeVisitor) - Method in interface com.sun.mirror.type.TypeMirror
Applies a visitor to this type.
addListener(AnnotationProcessorListener) - Method in interface com.sun.mirror.apt.AnnotationProcessorEnvironment
Add a listener.
and(DeclarationFilter) - Method in class com.sun.mirror.util.DeclarationFilter
Returns a filter that selects those declarations selected by both this filter and another.
AnnotationMirror - Interface in com.sun.mirror.declaration
Represents an annotation.
AnnotationProcessor - Interface in com.sun.mirror.apt
An annotation processor, used to examine and process the annotations of program elements.
AnnotationProcessorEnvironment - Interface in com.sun.mirror.apt
The environment encapsulating the state needed by an annotation processor.
AnnotationProcessorFactory - Interface in com.sun.mirror.apt
A factory for creating annotation processors.
AnnotationProcessorListener - Interface in com.sun.mirror.apt
Superinterface for all annotation processor event listeners.
AnnotationProcessors - Class in com.sun.mirror.apt
Utilities to create specialized annotation processors.
AnnotationProcessors() - Constructor for class com.sun.mirror.apt.AnnotationProcessors
AnnotationType - Interface in com.sun.mirror.type
Represents an annotation type.
AnnotationTypeDeclaration - Interface in com.sun.mirror.declaration
Represents the declaration of an annotation type.
AnnotationTypeElementDeclaration - Interface in com.sun.mirror.declaration
Represents an element of an annotation type.
AnnotationValue - Interface in com.sun.mirror.declaration
Represents a value of an annotation type element.
ArrayType - Interface in com.sun.mirror.type
Represents an array type.

C

ClassDeclaration - Interface in com.sun.mirror.declaration
Represents the declaration of a class.
classFilesCreated() - Method in interface com.sun.mirror.apt.RoundState
Returns true if new class files were created in this round of processing; returns false otherwise.
ClassType - Interface in com.sun.mirror.type
Represents a class type.
column() - Method in interface com.sun.mirror.util.SourcePosition
Returns the column number of this position.
com.sun.mirror.apt - package com.sun.mirror.apt
Classes used to communicate information between annotation processors and an annotation processing tool.
com.sun.mirror.declaration - package com.sun.mirror.declaration
Interfaces used to model program element declarations.
com.sun.mirror.type - package com.sun.mirror.type
Interfaces used to model types.
com.sun.mirror.util - package com.sun.mirror.util
Utilities to assist in the processing of declarations and types.
ConstructorDeclaration - Interface in com.sun.mirror.declaration
Represents a constructor of a class or interface.
createBinaryFile(Filer.Location, String, File) - Method in interface com.sun.mirror.apt.Filer
Creates a new binary file, and returns a stream for writing to it.
createClassFile(String) - Method in interface com.sun.mirror.apt.Filer
Creates a new class file, and returns a stream for writing to it.
createSourceFile(String) - Method in interface com.sun.mirror.apt.Filer
Creates a new source file and returns a writer for it.
createTextFile(Filer.Location, String, File, String) - Method in interface com.sun.mirror.apt.Filer
Creates a new text file, and returns a writer for it.

D

Declaration - Interface in com.sun.mirror.declaration
Represents the declaration of a program element such as a package, class, or method.
DeclarationFilter - Class in com.sun.mirror.util
A filter for selecting just the items of interest from a collection of declarations.
DeclarationFilter() - Constructor for class com.sun.mirror.util.DeclarationFilter
Constructs an identity filter: one that selects all declarations.
Declarations - Interface in com.sun.mirror.util
Utility methods for operating on declarations.
DeclarationVisitor - Interface in com.sun.mirror.util
A visitor for declarations, in the style of the standard visitor design pattern.
DeclarationVisitors - Class in com.sun.mirror.util
Utilities to create specialized DeclarationVisitor instances.
DeclaredType - Interface in com.sun.mirror.type
Represents a declared type, either a class type or an interface type.

E

EnumConstantDeclaration - Interface in com.sun.mirror.declaration
Represents an enum constant declaration.
EnumDeclaration - Interface in com.sun.mirror.declaration
Represents the declaration of an enum type.
EnumType - Interface in com.sun.mirror.type
Represents an enum type.
equals(Object) - Method in interface com.sun.mirror.declaration.Declaration
Tests whether an object represents the same declaration as this.
equals(Object) - Method in interface com.sun.mirror.type.TypeMirror
Tests whether two types represent the same type.
errorRaised() - Method in interface com.sun.mirror.apt.RoundState
Returns true if an error was raised in this round of processing; returns false otherwise.
ExecutableDeclaration - Interface in com.sun.mirror.declaration
Represents a method or constructor of a class or interface.

F

FieldDeclaration - Interface in com.sun.mirror.declaration
Represents a field of a type declaration.
file() - Method in interface com.sun.mirror.util.SourcePosition
Returns the source file containing this position.
Filer - Interface in com.sun.mirror.apt
This interface supports the creation of new files by an annotation processor.
Filer.Location - Enum in com.sun.mirror.apt
Locations (subtrees within the file system) where new files are created.
filter(Collection<D>) - Method in class com.sun.mirror.util.DeclarationFilter
Returns the declarations matched by this filter.
filter(Collection<? extends Declaration>, Class<D>) - Method in class com.sun.mirror.util.DeclarationFilter
Returns the declarations matched by this filter, with the result being restricted to declarations of a given kind.
FILTER_PACKAGE - Static variable in class com.sun.mirror.util.DeclarationFilter
A filter that selects only package-private (default) declarations.
FILTER_PRIVATE - Static variable in class com.sun.mirror.util.DeclarationFilter
A filter that selects only private declarations.
FILTER_PROTECTED - Static variable in class com.sun.mirror.util.DeclarationFilter
A filter that selects only protected declarations.
FILTER_PUBLIC - Static variable in class com.sun.mirror.util.DeclarationFilter
A filter that selects only public declarations.
FILTER_PUBLIC_OR_PROTECTED - Static variable in class com.sun.mirror.util.DeclarationFilter
A filter that selects only public or protected declarations.
finalRound() - Method in interface com.sun.mirror.apt.RoundState
Returns true if this was the last round of annotation processing; returns false if there will be a subsequent round.

G

getActualTypeArguments() - Method in interface com.sun.mirror.type.DeclaredType
Returns (in order) the actual type arguments of this type.
getAnnotation(Class<A>) - Method in interface com.sun.mirror.declaration.Declaration
Returns the annotation of this declaration having the specified type.
getAnnotationMirrors() - Method in interface com.sun.mirror.declaration.Declaration
Returns the annotations that are directly present on this declaration.
getAnnotationType() - Method in interface com.sun.mirror.declaration.AnnotationMirror
Returns the annotation type of this annotation.
getAnnotationTypes() - Method in interface com.sun.mirror.declaration.PackageDeclaration
Returns the declarations of the top-level annotation types in this package.
getArrayType(TypeMirror) - Method in interface com.sun.mirror.util.Types
Returns an array type with the specified component type.
getBounds() - Method in interface com.sun.mirror.declaration.TypeParameterDeclaration
Returns the bounds of this type parameter.
getClasses() - Method in interface com.sun.mirror.declaration.PackageDeclaration
Returns the declarations of the top-level classes in this package.
getComponentType() - Method in interface com.sun.mirror.type.ArrayType
Returns the component type of this array type.
getCompositeAnnotationProcessor(AnnotationProcessor...) - Static method in class com.sun.mirror.apt.AnnotationProcessors
Constructs a new composite annotation processor.
getCompositeAnnotationProcessor(Collection<AnnotationProcessor>) - Static method in class com.sun.mirror.apt.AnnotationProcessors
Constructs a new composite annotation processor.
getConstantExpression() - Method in interface com.sun.mirror.declaration.FieldDeclaration
Returns the text of a constant expression representing the value of this field if this field is a compile-time constant.
getConstantValue() - Method in interface com.sun.mirror.declaration.FieldDeclaration
Returns the value of this field if this field is a compile-time constant.
getConstructors() - Method in interface com.sun.mirror.declaration.ClassDeclaration
Returns the constructors of this class.
getContainingType() - Method in interface com.sun.mirror.type.DeclaredType
Returns the type that contains this type as a member.
getDeclaration() - Method in interface com.sun.mirror.type.AnnotationType
Returns the declaration of this type.
getDeclaration() - Method in interface com.sun.mirror.type.ClassType
Returns the declaration of this type.
getDeclaration() - Method in interface com.sun.mirror.type.DeclaredType
Returns the declaration of this type.
getDeclaration() - Method in interface com.sun.mirror.type.EnumType
Returns the declaration of this type.
getDeclaration() - Method in interface com.sun.mirror.type.InterfaceType
Returns the declaration of this type.
getDeclaration() - Method in interface com.sun.mirror.type.TypeVariable
Returns the type parameter that declared this type variable.
getDeclarationsAnnotatedWith(AnnotationTypeDeclaration) - Method in interface com.sun.mirror.apt.AnnotationProcessorEnvironment
Returns the declarations annotated with the given annotation type.
getDeclarationScanner(DeclarationVisitor, DeclarationVisitor) - Static method in class com.sun.mirror.util.DeclarationVisitors
Return a DeclarationVisitor that will scan the declaration structure, visiting declarations contained in another declaration.
getDeclarationUtils() - Method in interface com.sun.mirror.apt.AnnotationProcessorEnvironment
Returns an implementation of some utility methods for operating on declarations.
getDeclaredType(TypeDeclaration, TypeMirror...) - Method in interface com.sun.mirror.util.Types
Returns the type corresponding to a type declaration and actual type arguments.
getDeclaredType(DeclaredType, TypeDeclaration, TypeMirror...) - Method in interface com.sun.mirror.util.Types
Returns the type corresponding to a type declaration and actual arguments, given a containing type of which it is a member.
getDeclaringType() - Method in interface com.sun.mirror.declaration.AnnotationTypeElementDeclaration
Returns the type declaration within which this member or constructor is declared.
getDeclaringType() - Method in interface com.sun.mirror.declaration.EnumConstantDeclaration
Returns the type declaration within which this member or constructor is declared.
getDeclaringType() - Method in interface com.sun.mirror.declaration.MemberDeclaration
Returns the type declaration within which this member or constructor is declared.
getDefaultValue() - Method in interface com.sun.mirror.declaration.AnnotationTypeElementDeclaration
Returns the default value of this element.
getDocComment() - Method in interface com.sun.mirror.declaration.Declaration
Returns the text of the documentation ("javadoc") comment of this declaration.
getElementValues() - Method in interface com.sun.mirror.declaration.AnnotationMirror
Returns this annotation's elements and their values.
getEnumConstants() - Method in interface com.sun.mirror.declaration.EnumDeclaration
Returns the enum constants defined for this enum.
getEnums() - Method in interface com.sun.mirror.declaration.PackageDeclaration
Returns the declarations of the top-level enum types in this package.
getErasure(TypeMirror) - Method in interface com.sun.mirror.util.Types
Returns the erasure of a type.
getFields() - Method in interface com.sun.mirror.declaration.TypeDeclaration
Returns the fields that are directly declared by this class or interface.
getFiler() - Method in interface com.sun.mirror.apt.AnnotationProcessorEnvironment
Returns the filer used to create new source, class, or auxiliary files.
getFilter(Collection<Modifier>) - Static method in class com.sun.mirror.util.DeclarationFilter
Returns a filter that selects declarations containing all of a collection of modifiers.
getFilter(Class<? extends Declaration>) - Static method in class com.sun.mirror.util.DeclarationFilter
Returns a filter that selects declarations of a particular kind.
getFormalTypeParameters() - Method in interface com.sun.mirror.declaration.ExecutableDeclaration
Returns the formal type parameters of this method or constructor.
getFormalTypeParameters() - Method in interface com.sun.mirror.declaration.TypeDeclaration
Returns the formal type parameters of this class or interface.
getInterfaces() - Method in interface com.sun.mirror.declaration.PackageDeclaration
Returns the declarations of the top-level interfaces in this package.
getKind() - Method in interface com.sun.mirror.type.PrimitiveType
Returns the kind of primitive type that this object represents.
getLowerBounds() - Method in interface com.sun.mirror.type.WildcardType
Returns the lower bounds of this wildcard.
getMessager() - Method in interface com.sun.mirror.apt.AnnotationProcessorEnvironment
Returns the messager used to report errors, warnings, and other notices.
getMethods() - Method in interface com.sun.mirror.declaration.AnnotationTypeDeclaration
Returns the annotation type elements of this annotation type.
getMethods() - Method in interface com.sun.mirror.declaration.ClassDeclaration
Returns the methods that are directly declared by this class or interface.
getMethods() - Method in interface com.sun.mirror.declaration.TypeDeclaration
Returns the methods that are directly declared by this class or interface.
getModifiers() - Method in interface com.sun.mirror.declaration.Declaration
Returns the modifiers of this declaration, excluding annotations.
getNestedTypes() - Method in interface com.sun.mirror.declaration.TypeDeclaration
Returns the declarations of the nested classes and interfaces that are directly declared by this class or interface.
getOptions() - Method in interface com.sun.mirror.apt.AnnotationProcessorEnvironment
Returns the options passed to the annotation processing tool.
getOwner() - Method in interface com.sun.mirror.declaration.TypeParameterDeclaration
Returns the type, method, or constructor declaration within which this type parameter is declared.
getPackage(String) - Method in interface com.sun.mirror.apt.AnnotationProcessorEnvironment
Returns the declaration of a package given its fully qualified name.
getPackage() - Method in interface com.sun.mirror.declaration.TypeDeclaration
Returns the package within which this type is declared.
getParameters() - Method in interface com.sun.mirror.declaration.ExecutableDeclaration
Returns the formal parameters of this method or constructor.
getPosition() - Method in interface com.sun.mirror.declaration.AnnotationMirror
Returns the source position of the beginning of this annotation.
getPosition() - Method in interface com.sun.mirror.declaration.AnnotationValue
Returns the source position of the beginning of this annotation value.
getPosition() - Method in interface com.sun.mirror.declaration.Declaration
Returns the source position of the beginning of this declaration.
getPrimitiveType(PrimitiveType.Kind) - Method in interface com.sun.mirror.util.Types
Returns a primitive type.
getProcessorFor(Set<AnnotationTypeDeclaration>, AnnotationProcessorEnvironment) - Method in interface com.sun.mirror.apt.AnnotationProcessorFactory
Returns an annotation processor for a set of annotation types.
getQualifiedName() - Method in interface com.sun.mirror.declaration.PackageDeclaration
Returns the fully qualified name of this package.
getQualifiedName() - Method in interface com.sun.mirror.declaration.TypeDeclaration
Returns the fully qualified name of this class or interface declaration.
getQualifiedName() - Method in exception com.sun.mirror.type.MirroredTypeException
Returns the fully qualified name of the type being accessed.
getQualifiedNames() - Method in exception com.sun.mirror.type.MirroredTypesException
Returns the fully qualified names of the types being accessed.
getReturnType() - Method in interface com.sun.mirror.declaration.MethodDeclaration
Returns the formal return type of this method.
getRoundState() - Method in class com.sun.mirror.apt.RoundCompleteEvent
Return round state.
getSimpleName() - Method in interface com.sun.mirror.declaration.Declaration
Returns the simple (unqualified) name of this declaration.
getSource() - Method in class com.sun.mirror.apt.RoundCompleteEvent
Return source.
getSourceOrderDeclarationScanner(DeclarationVisitor, DeclarationVisitor) - Static method in class com.sun.mirror.util.DeclarationVisitors
Return a DeclarationVisitor that will scan the declaration structure, visiting declarations contained in another declaration in source code order.
getSpecifiedTypeDeclarations() - Method in interface com.sun.mirror.apt.AnnotationProcessorEnvironment
Returns the declarations of the types specified when the annotation processing tool was invoked.
getSuperclass() - Method in interface com.sun.mirror.declaration.ClassDeclaration
Returns the class type directly extended by this class.
getSuperclass() - Method in interface com.sun.mirror.type.ClassType
Returns the class type that is a direct supertype of this one.
getSuperinterfaces() - Method in interface com.sun.mirror.declaration.TypeDeclaration
Returns the interface types directly implemented by this class or extended by this interface.
getSuperinterfaces() - Method in interface com.sun.mirror.type.DeclaredType
Returns the interface types that are direct supertypes of this type.
getThrownTypes() - Method in interface com.sun.mirror.declaration.ExecutableDeclaration
Returns the exceptions and other throwables listed in this method or constructor's throws clause.
getType() - Method in interface com.sun.mirror.declaration.FieldDeclaration
Returns the type of this field.
getType() - Method in interface com.sun.mirror.declaration.ParameterDeclaration
Returns the type of this parameter.
getTypeDeclaration(String) - Method in interface com.sun.mirror.apt.AnnotationProcessorEnvironment
Returns the declaration of a type given its fully qualified name.
getTypeDeclarations() - Method in interface com.sun.mirror.apt.AnnotationProcessorEnvironment
A convenience method that returns the declarations of the types included in this invocation of the annotation processing tool.
getTypeMirror() - Method in exception com.sun.mirror.type.MirroredTypeException
Returns the type mirror corresponding to the type being accessed.
getTypeMirrors() - Method in exception com.sun.mirror.type.MirroredTypesException
Returns the type mirrors corresponding to the types being accessed.
getTypeUtils() - Method in interface com.sun.mirror.apt.AnnotationProcessorEnvironment
Returns an implementation of some utility methods for operating on types.
getTypeVariable(TypeParameterDeclaration) - Method in interface com.sun.mirror.util.Types
Returns the type variable declared by a type parameter.
getUpperBounds() - Method in interface com.sun.mirror.type.WildcardType
Returns the upper bounds of this wildcard.
getValue() - Method in interface com.sun.mirror.declaration.AnnotationValue
Returns the value.
getVoidType() - Method in interface com.sun.mirror.util.Types
Returns the pseudo-type representing the type of void.
getWildcardType(Collection<ReferenceType>, Collection<ReferenceType>) - Method in interface com.sun.mirror.util.Types
Returns a new wildcard.

H

hides(MemberDeclaration, MemberDeclaration) - Method in interface com.sun.mirror.util.Declarations
Tests whether one type, method, or field declaration hides another.

I

InterfaceDeclaration - Interface in com.sun.mirror.declaration
Represents the declaration of an interface.
InterfaceType - Interface in com.sun.mirror.type
Represents an interface type.
isAssignable(TypeMirror, TypeMirror) - Method in interface com.sun.mirror.util.Types
Tests whether one type is assignable to another.
isSubtype(TypeMirror, TypeMirror) - Method in interface com.sun.mirror.util.Types
Tests whether one type is a subtype of the another.
isVarArgs() - Method in interface com.sun.mirror.declaration.ExecutableDeclaration
Returns true if this method or constructor accepts a variable number of arguments.

L

line() - Method in interface com.sun.mirror.util.SourcePosition
Returns the line number of this position.

M

matches(Declaration) - Method in class com.sun.mirror.util.DeclarationFilter
Tests whether this filter matches a given declaration.
MemberDeclaration - Interface in com.sun.mirror.declaration
Represents a declaration that may be a member or constructor of a declared type.
Messager - Interface in com.sun.mirror.apt
A Messager provides the way for an annotation processor to report error messages, warnings, and other notices.
MethodDeclaration - Interface in com.sun.mirror.declaration
Represents a method of a class or interface.
MirroredTypeException - Exception in com.sun.mirror.type
Thrown when an application attempts to access the Class object corresponding to a TypeMirror.
MirroredTypeException(TypeMirror) - Constructor for exception com.sun.mirror.type.MirroredTypeException
Constructs a new MirroredTypeException for the specified type.
MirroredTypesException - Exception in com.sun.mirror.type
Thrown when an application attempts to access a sequence of Class objects each corresponding to a TypeMirror.
MirroredTypesException(Collection<TypeMirror>) - Constructor for exception com.sun.mirror.type.MirroredTypesException
Constructs a new MirroredTypesException for the specified types.
Modifier - Enum in com.sun.mirror.declaration
Represents a modifier on the declaration of a program element such as a class, method, or field.

N

NO_OP - Static variable in class com.sun.mirror.apt.AnnotationProcessors
An annotation processor that does nothing and has no state.
NO_OP - Static variable in class com.sun.mirror.util.DeclarationVisitors
A visitor that has no side effects and keeps no state.
not() - Method in class com.sun.mirror.util.DeclarationFilter
Returns a filter that selects those declarations not selected by this filter.

O

or(DeclarationFilter) - Method in class com.sun.mirror.util.DeclarationFilter
Returns a filter that selects those declarations selected by either this filter or another.
overrides(MethodDeclaration, MethodDeclaration) - Method in interface com.sun.mirror.util.Declarations
Tests whether one method overrides another.

P

PackageDeclaration - Interface in com.sun.mirror.declaration
Represents the declaration of a package.
ParameterDeclaration - Interface in com.sun.mirror.declaration
Represents a formal parameter of a method or constructor.
PrimitiveType - Interface in com.sun.mirror.type
Represents a primitive type.
PrimitiveType.Kind - Enum in com.sun.mirror.type
An enumeration of the different kinds of primitive types.
printError(String) - Method in interface com.sun.mirror.apt.Messager
Prints an error message.
printError(SourcePosition, String) - Method in interface com.sun.mirror.apt.Messager
Prints an error message.
printNotice(String) - Method in interface com.sun.mirror.apt.Messager
Prints a notice.
printNotice(SourcePosition, String) - Method in interface com.sun.mirror.apt.Messager
Prints a notice.
printWarning(String) - Method in interface com.sun.mirror.apt.Messager
Prints a warning message.
printWarning(SourcePosition, String) - Method in interface com.sun.mirror.apt.Messager
Prints a warning message.
process() - Method in interface com.sun.mirror.apt.AnnotationProcessor
Process all program elements supported by this annotation processor.

R

ReferenceType - Interface in com.sun.mirror.type
Represents a reference type.
removeListener(AnnotationProcessorListener) - Method in interface com.sun.mirror.apt.AnnotationProcessorEnvironment
Remove a listener.
roundComplete(RoundCompleteEvent) - Method in interface com.sun.mirror.apt.RoundCompleteListener
Invoked after all processors for a round have run to completion.
RoundCompleteEvent - Class in com.sun.mirror.apt
Event for the completion of a round of annotation processing.
RoundCompleteEvent(AnnotationProcessorEnvironment, RoundState) - Constructor for class com.sun.mirror.apt.RoundCompleteEvent
The current AnnotationProcessorEnvironment is regarded as the source of events.
RoundCompleteListener - Interface in com.sun.mirror.apt
Listener for the completion of a round of annotation processing.
RoundState - Interface in com.sun.mirror.apt
Represents the status of a completed round of annotation processing.

S

SimpleDeclarationVisitor - Class in com.sun.mirror.util
A simple visitor for declarations.
SimpleDeclarationVisitor() - Constructor for class com.sun.mirror.util.SimpleDeclarationVisitor
Creates a new SimpleDeclarationVisitor.
SimpleTypeVisitor - Class in com.sun.mirror.util
A simple visitor for types.
SimpleTypeVisitor() - Constructor for class com.sun.mirror.util.SimpleTypeVisitor
Creates a new SimpleTypeVisitor.
sourceFilesCreated() - Method in interface com.sun.mirror.apt.RoundState
Returns true if new source files were created in this round of processing; returns false otherwise.
SourcePosition - Interface in com.sun.mirror.util
Represents a position in a source file.
supportedAnnotationTypes() - Method in interface com.sun.mirror.apt.AnnotationProcessorFactory
Returns the names of the annotation types supported by this factory.
supportedOptions() - Method in interface com.sun.mirror.apt.AnnotationProcessorFactory
Returns the options recognized by this factory or by any of the processors it may create.

T

toString() - Method in interface com.sun.mirror.declaration.AnnotationValue
Returns a string representation of this value.
toString() - Method in enum com.sun.mirror.declaration.Modifier
Returns this modifier's name in lowercase.
toString() - Method in interface com.sun.mirror.type.TypeMirror
Returns a string representation of this type.
TypeDeclaration - Interface in com.sun.mirror.declaration
Represents the declaration of a class or interface.
TypeMirror - Interface in com.sun.mirror.type
Represents a type in the Java programming language.
TypeParameterDeclaration - Interface in com.sun.mirror.declaration
Represents a formal type parameter of a generic type, method, or constructor declaration.
Types - Interface in com.sun.mirror.util
Utility methods for operating on types.
TypeVariable - Interface in com.sun.mirror.type
Represents a type variable.
TypeVisitor - Interface in com.sun.mirror.util
A visitor for types, in the style of the standard visitor design pattern.

V

valueOf(String) - Static method in enum com.sun.mirror.apt.Filer.Location
Returns the enum constant of this type with the specified name.
valueOf(String) - Static method in enum com.sun.mirror.declaration.Modifier
Returns the enum constant of this type with the specified name.
valueOf(String) - Static method in enum com.sun.mirror.type.PrimitiveType.Kind
Returns the enum constant of this type with the specified name.
values() - Static method in enum com.sun.mirror.apt.Filer.Location
Returns an array containing the constants of this enum type, in the order they are declared.
values() - Static method in enum com.sun.mirror.declaration.Modifier
Returns an array containing the constants of this enum type, in the order they are declared.
values() - Static method in enum com.sun.mirror.type.PrimitiveType.Kind
Returns an array containing the constants of this enum type, in the order they are declared.
visitAnnotationType(AnnotationType) - Method in class com.sun.mirror.util.SimpleTypeVisitor
Visits an annotation type.
visitAnnotationType(AnnotationType) - Method in interface com.sun.mirror.util.TypeVisitor
Visits an annotation type.
visitAnnotationTypeDeclaration(AnnotationTypeDeclaration) - Method in interface com.sun.mirror.util.DeclarationVisitor
Visits an annotation type declaration.
visitAnnotationTypeDeclaration(AnnotationTypeDeclaration) - Method in class com.sun.mirror.util.SimpleDeclarationVisitor
Visits an annotation type declaration.
visitAnnotationTypeElementDeclaration(AnnotationTypeElementDeclaration) - Method in interface com.sun.mirror.util.DeclarationVisitor
Visits an annotation type element declaration.
visitAnnotationTypeElementDeclaration(AnnotationTypeElementDeclaration) - Method in class com.sun.mirror.util.SimpleDeclarationVisitor
Visits an annotation type element declaration.
visitArrayType(ArrayType) - Method in class com.sun.mirror.util.SimpleTypeVisitor
Visits an array type.
visitArrayType(ArrayType) - Method in interface com.sun.mirror.util.TypeVisitor
Visits an array type.
visitClassDeclaration(ClassDeclaration) - Method in interface com.sun.mirror.util.DeclarationVisitor
Visits a class declaration.
visitClassDeclaration(ClassDeclaration) - Method in class com.sun.mirror.util.SimpleDeclarationVisitor
Visits a class declaration.
visitClassType(ClassType) - Method in class com.sun.mirror.util.SimpleTypeVisitor
Visits a class type.
visitClassType(ClassType) - Method in interface com.sun.mirror.util.TypeVisitor
Visits a class type.
visitConstructorDeclaration(ConstructorDeclaration) - Method in interface com.sun.mirror.util.DeclarationVisitor
Visits a constructor declaration.
visitConstructorDeclaration(ConstructorDeclaration) - Method in class com.sun.mirror.util.SimpleDeclarationVisitor
Visits a constructor declaration.
visitDeclaration(Declaration) - Method in interface com.sun.mirror.util.DeclarationVisitor
Visits a declaration.
visitDeclaration(Declaration) - Method in class com.sun.mirror.util.SimpleDeclarationVisitor
Visits a declaration.
visitDeclaredType(DeclaredType) - Method in class com.sun.mirror.util.SimpleTypeVisitor
Visits a declared type.
visitDeclaredType(DeclaredType) - Method in interface com.sun.mirror.util.TypeVisitor
Visits a declared type.
visitEnumConstantDeclaration(EnumConstantDeclaration) - Method in interface com.sun.mirror.util.DeclarationVisitor
Visits an enum constant declaration.
visitEnumConstantDeclaration(EnumConstantDeclaration) - Method in class com.sun.mirror.util.SimpleDeclarationVisitor
Visits an enum constant declaration.
visitEnumDeclaration(EnumDeclaration) - Method in interface com.sun.mirror.util.DeclarationVisitor
Visits an enum declaration.
visitEnumDeclaration(EnumDeclaration) - Method in class com.sun.mirror.util.SimpleDeclarationVisitor
Visits an enum declaration.
visitEnumType(EnumType) - Method in class com.sun.mirror.util.SimpleTypeVisitor
Visits an enum type.
visitEnumType(EnumType) - Method in interface com.sun.mirror.util.TypeVisitor
Visits an enum type.
visitExecutableDeclaration(ExecutableDeclaration) - Method in interface com.sun.mirror.util.DeclarationVisitor
Visits a method or constructor declaration.
visitExecutableDeclaration(ExecutableDeclaration) - Method in class com.sun.mirror.util.SimpleDeclarationVisitor
Visits a method or constructor declaration.
visitFieldDeclaration(FieldDeclaration) - Method in interface com.sun.mirror.util.DeclarationVisitor
Visits a field declaration.
visitFieldDeclaration(FieldDeclaration) - Method in class com.sun.mirror.util.SimpleDeclarationVisitor
Visits a field declaration.
visitInterfaceDeclaration(InterfaceDeclaration) - Method in interface com.sun.mirror.util.DeclarationVisitor
Visits an interface declaration.
visitInterfaceDeclaration(InterfaceDeclaration) - Method in class com.sun.mirror.util.SimpleDeclarationVisitor
Visits an interface declaration.
visitInterfaceType(InterfaceType) - Method in class com.sun.mirror.util.SimpleTypeVisitor
Visits an interface type.
visitInterfaceType(InterfaceType) - Method in interface com.sun.mirror.util.TypeVisitor
Visits an interface type.
visitMemberDeclaration(MemberDeclaration) - Method in interface com.sun.mirror.util.DeclarationVisitor
Visits a member or constructor declaration.
visitMemberDeclaration(MemberDeclaration) - Method in class com.sun.mirror.util.SimpleDeclarationVisitor
Visits a member or constructor declaration.
visitMethodDeclaration(MethodDeclaration) - Method in interface com.sun.mirror.util.DeclarationVisitor
Visits a method declaration.
visitMethodDeclaration(MethodDeclaration) - Method in class com.sun.mirror.util.SimpleDeclarationVisitor
Visits a method declaration.
visitPackageDeclaration(PackageDeclaration) - Method in interface com.sun.mirror.util.DeclarationVisitor
Visits a package declaration.
visitPackageDeclaration(PackageDeclaration) - Method in class com.sun.mirror.util.SimpleDeclarationVisitor
Visits a package declaration.
visitParameterDeclaration(ParameterDeclaration) - Method in interface com.sun.mirror.util.DeclarationVisitor
Visits a parameter declaration.
visitParameterDeclaration(ParameterDeclaration) - Method in class com.sun.mirror.util.SimpleDeclarationVisitor
Visits a parameter declaration.
visitPrimitiveType(PrimitiveType) - Method in class com.sun.mirror.util.SimpleTypeVisitor
Visits a primitive type.
visitPrimitiveType(PrimitiveType) - Method in interface com.sun.mirror.util.TypeVisitor
Visits a primitive type.
visitReferenceType(ReferenceType) - Method in class com.sun.mirror.util.SimpleTypeVisitor
Visits a reference type.
visitReferenceType(ReferenceType) - Method in interface com.sun.mirror.util.TypeVisitor
Visits a reference type.
visitTypeDeclaration(TypeDeclaration) - Method in interface com.sun.mirror.util.DeclarationVisitor
Visits a type declaration.
visitTypeDeclaration(TypeDeclaration) - Method in class com.sun.mirror.util.SimpleDeclarationVisitor
Visits a type declaration.
visitTypeMirror(TypeMirror) - Method in class com.sun.mirror.util.SimpleTypeVisitor
Visits a type mirror.
visitTypeMirror(TypeMirror) - Method in interface com.sun.mirror.util.TypeVisitor
Visits a type mirror.
visitTypeParameterDeclaration(TypeParameterDeclaration) - Method in interface com.sun.mirror.util.DeclarationVisitor
Visits a type parameter declaration.
visitTypeParameterDeclaration(TypeParameterDeclaration) - Method in class com.sun.mirror.util.SimpleDeclarationVisitor
Visits a type parameter declaration.
visitTypeVariable(TypeVariable) - Method in class com.sun.mirror.util.SimpleTypeVisitor
Visits a type variable.
visitTypeVariable(TypeVariable) - Method in interface com.sun.mirror.util.TypeVisitor
Visits a type variable.
visitVoidType(VoidType) - Method in class com.sun.mirror.util.SimpleTypeVisitor
Visits a void type.
visitVoidType(VoidType) - Method in interface com.sun.mirror.util.TypeVisitor
Visits a void type.
visitWildcardType(WildcardType) - Method in class com.sun.mirror.util.SimpleTypeVisitor
Visits a wildcard.
visitWildcardType(WildcardType) - Method in interface com.sun.mirror.util.TypeVisitor
Visits a wildcard.
VoidType - Interface in com.sun.mirror.type
A pseudo-type representing the type of void.

W

WildcardType - Interface in com.sun.mirror.type
Represents a wildcard type argument.
A C D E F G H I L M N O P R S T V W
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Mirror API

Frame Alert

This document is designed to be viewed using the frames feature. If you see this message, you are using a non-frame-capable web client.
Link toNon-frame version.


Serialized Form

Package com.sun.mirror.apt

Class com.sun.mirror.apt.RoundCompleteEvent extends EventObject implements Serializable

Serialized Fields

rs

RoundState rs
Package com.sun.mirror.type

Class com.sun.mirror.type.MirroredTypeException extends RuntimeException implements Serializable

serialVersionUID: 1L

Serialized Fields

name

String name

Class com.sun.mirror.type.MirroredTypesException extends RuntimeException implements Serializable

serialVersionUID: 1L

Serialized Fields

names

Collection<E> names

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


apt

Mirror API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package com.sun.mirror.apt

Classes used to communicate information between annotation processors and an annotation processing tool.

See:
Description

Interface Summary
AnnotationProcessor | An annotation processor, used to examine and process the annotations of program elements.
AnnotationProcessorEnvironment | The environment encapsulating the state needed by an annotation processor.
AnnotationProcessorFactory | A factory for creating annotation processors.
AnnotationProcessorListener | Superinterface for all annotation processor event listeners.
Filer | This interface supports the creation of new files by an annotation processor.
Messager | A Messager provides the way for an annotation processor to report error messages, warnings, and other notices.
RoundCompleteListener | Listener for the completion of a round of annotation processing.
RoundState | Represents the status of a completed round of annotation processing.

Class Summary
AnnotationProcessors | Utilities to create specialized annotation processors.
RoundCompleteEvent | Event for the completion of a round of annotation processing.

Enum Summary
Filer.Location Locations (subtrees within the file system) where new files are created.

Package com.sun.mirror.apt Description

Classes used to communicate information between annotation processors and an annotation processing tool.

Note that the apt tool and its associated APIs may be changed or superseded in future j2se releases.

Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


AnnotationProcessorListener

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.apt
Interface AnnotationProcessorListener

All Superinterfaces:
EventListener
All Known Subinterfaces:
RoundCompleteListener
public interface AnnotationProcessorListener
extends EventListener

Superinterface for all annotation processor event listeners.

Since:
1.5

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


com.sun.mirror.apt Class Hierarchy

Mirror API
PREV NEXT FRAMES NO FRAMES

Hierarchy For Package com.sun.mirror.apt

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • com.sun.mirror.apt.AnnotationProcessors
    • java.util.EventObject (implements java.io.Serializable)
      • com.sun.mirror.apt.RoundCompleteEvent

Interface Hierarchy

  • com.sun.mirror.apt.AnnotationProcessor
  • com.sun.mirror.apt.AnnotationProcessorEnvironment
  • com.sun.mirror.apt.AnnotationProcessorFactory
  • java.util.EventListener
    • com.sun.mirror.apt.AnnotationProcessorListener
      • com.sun.mirror.apt.RoundCompleteListener
  • com.sun.mirror.apt.Filer
  • com.sun.mirror.apt.Messager
  • com.sun.mirror.apt.RoundState

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • com.sun.mirror.apt.Filer.Location
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Package com.sun.mirror.apt

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Package
com.sun.mirror.apt

Packages that use com.sun.mirror.apt
com.sun.mirror.apt Classes used to communicate information between annotation processors and an annotation processing tool.

Classes in com.sun.mirror.apt used by com.sun.mirror.apt
AnnotationProcessor
An annotation processor, used to examine and process the annotations of program elements.
AnnotationProcessorEnvironment
The environment encapsulating the state needed by an annotation processor.
AnnotationProcessorListener
Superinterface for all annotation processor event listeners.
Filer
This interface supports the creation of new files by an annotation processor.
Filer.Location
Locations (subtrees within the file system) where new files are created.
Messager
A Messager provides the way for an annotation processor to report error messages, warnings, and other notices.
RoundCompleteEvent
Event for the completion of a round of annotation processing.
RoundState
Represents the status of a completed round of annotation processing.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


AnnotationProcessor

Mirror API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.apt
Interface AnnotationProcessor

public interface AnnotationProcessor

An annotation processor, used to examine and process the annotations of program elements. An annotation processor may, for example, create new source files and XML documents to be used in conjunction with the original code.

An annotation processor is constructed by a factory, which provides it with an environment that encapsulates the state it needs. Messages regarding warnings and errors encountered during processing should be directed to the environment's Messager, and new files may be created using the environment's Filer.

Each annotation processor is created to process annotations of a particular annotation type or set of annotation types. It may use its environment to find the program elements with annotations of those types. It may freely examine any other program elements in the course of its processing.

Since:
1.5

Method Summary
 void process()
Process all program elements supported by this annotation processor.

Method Detail

process

void process()
Process all program elements supported by this annotation processor.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


AnnotationProcessorEnvironment

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.apt
Interface AnnotationProcessorEnvironment

public interface AnnotationProcessorEnvironment

The environment encapsulating the state needed by an annotation processor. An annotation processing tool makes this environment available to all annotation processors.

When an annotation processing tool is invoked, it is given a set of type declarations on which to operate. These are refered to as the specified types. The type declarations said to be included in this invocation consist of the specified types and any types nested within them.

DeclarationFilter provides a simple way to select just the items of interest when a method returns a collection of declarations.

Since:
1.5

Method Summary
void | addListener(AnnotationProcessorListener listener) Add a listener.
Collection<Declaration> | getDeclarationsAnnotatedWith(AnnotationTypeDeclaration a) Returns the declarations annotated with the given annotation type.
Declarations | getDeclarationUtils() Returns an implementation of some utility methods for operating on declarations.
Filer | getFiler() Returns the filer used to create new source, class, or auxiliary files.
Messager | getMessager() Returns the messager used to report errors, warnings, and other notices.
Map<String,String> | getOptions() Returns the options passed to the annotation processing tool.
PackageDeclaration | getPackage(String name) Returns the declaration of a package given its fully qualified name.
Collection<TypeDeclaration> | getSpecifiedTypeDeclarations() Returns the declarations of the types specified when the annotation processing tool was invoked.
TypeDeclaration | getTypeDeclaration(String name) Returns the declaration of a type given its fully qualified name.
Collection<TypeDeclaration> | getTypeDeclarations() A convenience method that returns the declarations of the types included in this invocation of the annotation processing tool.
Types | getTypeUtils() Returns an implementation of some utility methods for operating on types.
void | removeListener(AnnotationProcessorListener listener) Remove a listener.

Method Detail

getOptions

Map<String,String> getOptions()
Returns the options passed to the annotation processing tool. Options are returned in the form of a map from option name (such as "-encoding") to option value. For an option with no value (such as "-help"), the corresponding value in the map is null.

Options beginning with "-A" are processor-specific. Such options are unrecognized by the tool, but intended to be used by some annotation processor.

Returns:
the options passed to the tool

getMessager

Messager getMessager()
Returns the messager used to report errors, warnings, and other notices.

Returns:
the messager

getFiler

Filer getFiler()
Returns the filer used to create new source, class, or auxiliary files.

Returns:
the filer

getSpecifiedTypeDeclarations

Collection<TypeDeclaration> getSpecifiedTypeDeclarations()
Returns the declarations of the types specified when the annotation processing tool was invoked.

Returns:
the types specified when the tool was invoked, or an empty collection if there were none

getPackage

PackageDeclaration getPackage(String name)
Returns the declaration of a package given its fully qualified name.

Parameters:
name - fully qualified package name, or "" for the unnamed package
Returns:
the declaration of the named package, or null if it cannot be found

getTypeDeclaration

TypeDeclaration getTypeDeclaration(String name)
Returns the declaration of a type given its fully qualified name.

Parameters:
name - fully qualified type name
Returns:
the declaration of the named type, or null if it cannot be found

getTypeDeclarations

Collection<TypeDeclaration> getTypeDeclarations()
A convenience method that returns the declarations of the types included in this invocation of the annotation processing tool.

Returns:
the declarations of the types included in this invocation of the tool, or an empty collection if there are none

getDeclarationsAnnotatedWith

Collection<Declaration> getDeclarationsAnnotatedWith(AnnotationTypeDeclaration a)
Returns the declarations annotated with the given annotation type. Only declarations of the types included in this invocation of the annotation processing tool, or declarations of members, parameters, or type parameters declared within those, are returned.

Parameters:
a - annotation type being requested
Returns:
the declarations annotated with the given annotation type, or an empty collection if there are none

getDeclarationUtils

Declarations getDeclarationUtils()
Returns an implementation of some utility methods for operating on declarations.

Returns:
declaration utilities

getTypeUtils

Types getTypeUtils()
Returns an implementation of some utility methods for operating on types.

Returns:
type utilities

addListener

void addListener(AnnotationProcessorListener listener)
Add a listener. If the listener is currently registered to listen, adding it again will have no effect.

Parameters:
listener - The listener to add.
Throws:
NullPointerException - if the listener is null

removeListener

void removeListener(AnnotationProcessorListener listener)
Remove a listener. If the listener is not currently listening, the method call does nothing.

Parameters:
listener - The listener to remove.
Throws:
NullPointerException - if the listener is null
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


AnnotationProcessorFactory

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.apt
Interface AnnotationProcessorFactory

public interface AnnotationProcessorFactory

A factory for creating annotation processors. Each factory is responsible for creating processors for one or more annotation types. The factory is said to support these types.

Each implementation of an AnnotationProcessorFactory must provide a public no-argument constructor to be used by tools to instantiate the factory.

Since:
1.5

Method Summary
AnnotationProcessor | getProcessorFor(Set<AnnotationTypeDeclaration> atds, AnnotationProcessorEnvironment env) Returns an annotation processor for a set of annotation types.
Collection<String> | supportedAnnotationTypes() Returns the names of the annotation types supported by this factory.
Collection<String> | supportedOptions() Returns the options recognized by this factory or by any of the processors it may create.

Method Detail

supportedOptions

Collection<String> supportedOptions()
Returns the options recognized by this factory or by any of the processors it may create. Only processor-specific options are included, each of which begins with "-A". For example, if this factory recognizes options such as -Adebug -Aloglevel=3, it will return the strings "-Adebug" and "-Aloglevel".

A tool might use this information to determine if any options provided by a user are unrecognized by any processor, in which case it may wish to report an error.

Returns:
the options recognized by this factory or by any of the processors it may create, or an empty collection if none

supportedAnnotationTypes

Collection<String> supportedAnnotationTypes()
Returns the names of the annotation types supported by this factory. An element of the result may be the canonical (fully qualified) name of a supported annotation type. Alternately it may be of the form "name.*" representing the set of all annotation types with canonical names beginning with "name." Finally, "*" by itself represents the set of all annotation types.

Returns:
the names of the annotation types supported by this factory

getProcessorFor

AnnotationProcessor getProcessorFor(Set<AnnotationTypeDeclaration> atds,
                                    AnnotationProcessorEnvironment env)
Returns an annotation processor for a set of annotation types. The set will be empty if the factory supports "*" and the specified type declarations have no annotations. Note that the set of annotation types may be empty for other reasons, such as giving the factory an opportunity to register a listener. An AnnotationProcessorFactory must gracefully handle an empty set of annotations; an appropriate response to an empty set will often be returning AnnotationProcessors.NO_OP.

Parameters:
atds - type declarations of the annotation types to be processed
env - environment to use during processing
Returns:
an annotation processor for the given annotation types, or null if the types are not supported or the processor cannot be created
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


AnnotationProcessors

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.apt
Class AnnotationProcessors

java.lang.Object
    extended by  com.sun.mirror.apt.AnnotationProcessors

public class AnnotationProcessors
extends Object

Utilities to create specialized annotation processors.

Since:
1.5

Field Summary
static AnnotationProcessor NO_OP
An annotation processor that does nothing and has no state.
Constructor Summary
AnnotationProcessors()
Method Summary
static AnnotationProcessor | getCompositeAnnotationProcessor(AnnotationProcessor... aps) Constructs a new composite annotation processor.
static AnnotationProcessor | getCompositeAnnotationProcessor(Collection<AnnotationProcessor> aps) Constructs a new composite annotation processor.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_OP

public static final AnnotationProcessor NO_OP
An annotation processor that does nothing and has no state. May be used multiple times.

Since:
1.5
Constructor Detail

AnnotationProcessors

public AnnotationProcessors()
Method Detail

getCompositeAnnotationProcessor

public static AnnotationProcessor getCompositeAnnotationProcessor(AnnotationProcessor... aps)
Constructs a new composite annotation processor. A composite annotation processor combines multiple annotation processors into one and functions by invoking each of its component processors' process methods in sequence.

Parameters:
aps - The processors to create a composite of
Since:
1.5

getCompositeAnnotationProcessor

public static AnnotationProcessor getCompositeAnnotationProcessor(Collection<AnnotationProcessor> aps)
Constructs a new composite annotation processor. A composite annotation processor combines multiple annotation processors into one and functions by invoking each of its component processors' process methods in the sequence the processors are returned by the collection's iterator.

Parameters:
aps - A collection of processors to create a composite of
Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.mirror.apt.AnnotationProcessors

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.mirror.apt.AnnotationProcessors

No usage of com.sun.mirror.apt.AnnotationProcessors

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.mirror.apt.Filer.Location

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.mirror.apt.Filer.Location

Packages that use Filer.Location
com.sun.mirror.apt Classes used to communicate information between annotation processors and an annotation processing tool.

Uses of Filer.Location in com.sun.mirror.apt

Methods in com.sun.mirror.apt that return Filer.Location
static Filer.Location | Filer.Location.valueOf(String name) Returns the enum constant of this type with the specified name.
static Filer.Location[] | Filer.Location.values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods in com.sun.mirror.apt with parameters of type Filer.Location
OutputStream | Filer.createBinaryFile(Filer.Location loc, String pkg, File relPath) Creates a new binary file, and returns a stream for writing to it.
PrintWriter | Filer.createTextFile(Filer.Location loc, String pkg, File relPath, String charsetName) Creates a new text file, and returns a writer for it.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.mirror.apt.RoundCompleteEvent

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.mirror.apt.RoundCompleteEvent

Packages that use RoundCompleteEvent
com.sun.mirror.apt Classes used to communicate information between annotation processors and an annotation processing tool.

Uses of RoundCompleteEvent in com.sun.mirror.apt

Methods in com.sun.mirror.apt with parameters of type RoundCompleteEvent
 void RoundCompleteListener.roundComplete(RoundCompleteEvent event)
Invoked after all processors for a round have run to completion.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.apt.AnnotationProcessor

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.apt.AnnotationProcessor

Packages that use AnnotationProcessor
com.sun.mirror.apt Classes used to communicate information between annotation processors and an annotation processing tool.

Uses of AnnotationProcessor in com.sun.mirror.apt

Fields in com.sun.mirror.apt declared as AnnotationProcessor
static AnnotationProcessor AnnotationProcessors.NO_OP
An annotation processor that does nothing and has no state.

Methods in com.sun.mirror.apt that return AnnotationProcessor
static AnnotationProcessor | AnnotationProcessors.getCompositeAnnotationProcessor(AnnotationProcessor... aps) Constructs a new composite annotation processor.
static AnnotationProcessor | AnnotationProcessors.getCompositeAnnotationProcessor(Collection<AnnotationProcessor> aps) Constructs a new composite annotation processor.
AnnotationProcessor | AnnotationProcessorFactory.getProcessorFor(Set<AnnotationTypeDeclaration> atds, AnnotationProcessorEnvironment env) Returns an annotation processor for a set of annotation types.

Methods in com.sun.mirror.apt with parameters of type AnnotationProcessor
static AnnotationProcessor AnnotationProcessors.getCompositeAnnotationProcessor(AnnotationProcessor... aps)
Constructs a new composite annotation processor.

Method parameters in com.sun.mirror.apt with type arguments of type AnnotationProcessor
static AnnotationProcessor AnnotationProcessors.getCompositeAnnotationProcessor(Collection<AnnotationProcessor> aps)
Constructs a new composite annotation processor.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.apt.AnnotationProcessorEnvironment

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.apt.AnnotationProcessorEnvironment

Packages that use AnnotationProcessorEnvironment
com.sun.mirror.apt Classes used to communicate information between annotation processors and an annotation processing tool.

Uses of AnnotationProcessorEnvironment in com.sun.mirror.apt

Methods in com.sun.mirror.apt that return AnnotationProcessorEnvironment
 AnnotationProcessorEnvironment RoundCompleteEvent.getSource()
Return source.

Methods in com.sun.mirror.apt with parameters of type AnnotationProcessorEnvironment
 AnnotationProcessor AnnotationProcessorFactory.getProcessorFor(Set<AnnotationTypeDeclaration> atds, AnnotationProcessorEnvironment env)
Returns an annotation processor for a set of annotation types.

Constructors in com.sun.mirror.apt with parameters of type AnnotationProcessorEnvironment
RoundCompleteEvent(AnnotationProcessorEnvironment source, RoundState rs)
The current AnnotationProcessorEnvironment is regarded as the source of events.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.apt.AnnotationProcessorFactory

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.apt.AnnotationProcessorFactory

No usage of com.sun.mirror.apt.AnnotationProcessorFactory

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.apt.AnnotationProcessorListener

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.apt.AnnotationProcessorListener

Packages that use AnnotationProcessorListener
com.sun.mirror.apt Classes used to communicate information between annotation processors and an annotation processing tool.

Uses of AnnotationProcessorListener in com.sun.mirror.apt

Subinterfaces of AnnotationProcessorListener in com.sun.mirror.apt
 interface RoundCompleteListener
Listener for the completion of a round of annotation processing.

Methods in com.sun.mirror.apt with parameters of type AnnotationProcessorListener
void | AnnotationProcessorEnvironment.addListener(AnnotationProcessorListener listener) Add a listener.
void | AnnotationProcessorEnvironment.removeListener(AnnotationProcessorListener listener) Remove a listener.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.apt.Filer

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.apt.Filer

Packages that use Filer
com.sun.mirror.apt Classes used to communicate information between annotation processors and an annotation processing tool.

Uses of Filer in com.sun.mirror.apt

Methods in com.sun.mirror.apt that return Filer
 Filer AnnotationProcessorEnvironment.getFiler()
Returns the filer used to create new source, class, or auxiliary files.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.apt.Messager

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.apt.Messager

Packages that use Messager
com.sun.mirror.apt Classes used to communicate information between annotation processors and an annotation processing tool.

Uses of Messager in com.sun.mirror.apt

Methods in com.sun.mirror.apt that return Messager
 Messager AnnotationProcessorEnvironment.getMessager()
Returns the messager used to report errors, warnings, and other notices.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.apt.RoundCompleteListener

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.apt.RoundCompleteListener

No usage of com.sun.mirror.apt.RoundCompleteListener

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.apt.RoundState

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.apt.RoundState

Packages that use RoundState
com.sun.mirror.apt Classes used to communicate information between annotation processors and an annotation processing tool.

Uses of RoundState in com.sun.mirror.apt

Methods in com.sun.mirror.apt that return RoundState
 RoundState RoundCompleteEvent.getRoundState()
Return round state.

Constructors in com.sun.mirror.apt with parameters of type RoundState
RoundCompleteEvent(AnnotationProcessorEnvironment source, RoundState rs)
The current AnnotationProcessorEnvironment is regarded as the source of events.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Filer

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.apt
Interface Filer

public interface Filer

This interface supports the creation of new files by an annotation processor. Files created in this way will be known to the annotation processing tool implementing this interface, better enabling the tool to manage them. Four kinds of files are distinguished: source files, class files, other text files, and other binary files. The latter two are collectively referred to as auxiliary files.

There are two distinguished locations (subtrees within the file system) where newly created files are placed: one for new source files, and one for new class files. (These might be specified on a tool's command line, for example, using flags such as -s and -d.) Auxiliary files may be created in either location.

During each run of an annotation processing tool, a file with a given pathname may be created only once. If that file already exists before the first attempt to create it, the old contents will be deleted. Any subsequent attempt to create the same file during a run will fail.

Since:
1.5

Nested Class Summary
static class Filer.Location
Locations (subtrees within the file system) where new files are created.
Method Summary
OutputStream | createBinaryFile(Filer.Location loc, String pkg, File relPath) Creates a new binary file, and returns a stream for writing to it.
OutputStream | createClassFile(String name) Creates a new class file, and returns a stream for writing to it.
PrintWriter | createSourceFile(String name) Creates a new source file and returns a writer for it.
PrintWriter | createTextFile(Filer.Location loc, String pkg, File relPath, String charsetName) Creates a new text file, and returns a writer for it.

Method Detail

createSourceFile

PrintWriter createSourceFile(String name)
                             throws IOException
Creates a new source file and returns a writer for it. The file's name and path (relative to the root of all newly created source files) is based on the type to be declared in that file. If more than one type is being declared, the name of the principal top-level type (the public one, for example) should be used.

The charset used to encode the file is determined by the implementation. An annotation processing tool may have an -encoding flag or the like for specifying this. It will typically use the platform's default encoding if none is specified.

Parameters:
name - canonical (fully qualified) name of the principal type being declared in this file
Returns:
a writer for the new file
Throws:
IOException - if the file cannot be created

createClassFile

OutputStream createClassFile(String name)
                             throws IOException
Creates a new class file, and returns a stream for writing to it. The file's name and path (relative to the root of all newly created class files) is based on the name of the type being written.

Parameters:
name - canonical (fully qualified) name of the type being written
Returns:
a stream for writing to the new file
Throws:
IOException - if the file cannot be created

createTextFile

PrintWriter createTextFile(Filer.Location loc,
                           String pkg,
                           File relPath,
                           String charsetName)
                           throws IOException
Creates a new text file, and returns a writer for it. The file is located along with either the newly created source or newly created binary files. It may be named relative to some package (as are source and binary files), and from there by an arbitrary pathname. In a loose sense, the pathname of the new file will be the concatenation of loc, pkg, and relPath.

A charset for encoding the file may be provided. If none is given, the charset used to encode source files (see createSourceFile(String)) will be used.

Parameters:
loc - location of the new file
pkg - package relative to which the file should be named, or the empty string if none
relPath - final pathname components of the file
charsetName - the name of the charset to use, or null if none is being explicitly specified
Returns:
a writer for the new file
Throws:
IOException - if the file cannot be created

createBinaryFile

OutputStream createBinaryFile(Filer.Location loc,
                              String pkg,
                              File relPath)
                              throws IOException
Creates a new binary file, and returns a stream for writing to it. The file is located along with either the newly created source or newly created binary files. It may be named relative to some package (as are source and binary files), and from there by an arbitrary pathname. In a loose sense, the pathname of the new file will be the concatenation of loc, pkg, and relPath.

Parameters:
loc - location of the new file
pkg - package relative to which the file should be named, or the empty string if none
relPath - final pathname components of the file
Returns:
a stream for writing to the new file
Throws:
IOException - if the file cannot be created
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Filer.Location

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

com.sun.mirror.apt
Enum Filer.Location

java.lang.Object
    extended by  java.lang.Enum<Filer.Location>
        extended by  com.sun.mirror.apt.Filer.Location
All Implemented Interfaces:
Serializable, Comparable<Filer.Location>
Enclosing interface:
Filer
public static enum Filer.Location
extends Enum<Filer.Location>

Locations (subtrees within the file system) where new files are created.

Enum Constant Summary
CLASS_TREE
The location of new class files.
SOURCE_TREE
The location of new source files.
Method Summary
static Filer.Location | valueOf(String name) Returns the enum constant of this type with the specified name.
static Filer.Location[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

SOURCE_TREE

public static final Filer.Location SOURCE_TREE
The location of new source files.

CLASS_TREE

public static final Filer.Location CLASS_TREE
The location of new class files.

Method Detail

values

public static Filer.Location[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (Filer.Location c : Filer.Location.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static Filer.Location valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Messager

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.apt
Interface Messager

public interface Messager

A Messager provides the way for an annotation processor to report error messages, warnings, and other notices.

Since:
1.5

Method Summary
void | printError(SourcePosition pos, String msg) Prints an error message.
void | printError(String msg) Prints an error message.
void | printNotice(SourcePosition pos, String msg) Prints a notice.
void | printNotice(String msg) Prints a notice.
void | printWarning(SourcePosition pos, String msg) Prints a warning message.
void | printWarning(String msg) Prints a warning message.

Method Detail

printError

void printError(String msg)
Prints an error message. Equivalent to printError(null, msg).

Parameters:
msg - the message, or an empty string if none

printError

void printError(SourcePosition pos,
                String msg)
Prints an error message.

Parameters:
pos - the position where the error occured, or null if it is unknown or not applicable
msg - the message, or an empty string if none

printWarning

void printWarning(String msg)
Prints a warning message. Equivalent to printWarning(null, msg).

Parameters:
msg - the message, or an empty string if none

printWarning

void printWarning(SourcePosition pos,
                  String msg)
Prints a warning message.

Parameters:
pos - the position where the warning occured, or null if it is unknown or not applicable
msg - the message, or an empty string if none

printNotice

void printNotice(String msg)
Prints a notice. Equivalent to printNotice(null, msg).

Parameters:
msg - the message, or an empty string if none

printNotice

void printNotice(SourcePosition pos,
                 String msg)
Prints a notice.

Parameters:
pos - the position where the noticed occured, or null if it is unknown or not applicable
msg - the message, or an empty string if none
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


RoundCompleteEvent

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.apt
Class RoundCompleteEvent

java.lang.Object
    extended by  java.util.EventObject
        extended by  com.sun.mirror.apt.RoundCompleteEvent
All Implemented Interfaces:
Serializable
public abstract class RoundCompleteEvent
extends EventObject

Event for the completion of a round of annotation processing.

While this class extends the serializable EventObject, it cannot meaningfully be serialized because all of the annotation processing tool's internal state would potentially be needed.

Since:
1.5
See Also:
Serialized Form

Field Summary
Fields inherited from class java.util.EventObject
source
Constructor Summary
protected RoundCompleteEvent(AnnotationProcessorEnvironment source, RoundState rs)
The current AnnotationProcessorEnvironment is regarded as the source of events.
Method Summary
RoundState | getRoundState() Return round state.
AnnotationProcessorEnvironment | getSource() Return source.
Methods inherited from class java.util.EventObject
toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

RoundCompleteEvent

protected RoundCompleteEvent(AnnotationProcessorEnvironment source,
                             RoundState rs)
The current AnnotationProcessorEnvironment is regarded as the source of events.

Parameters:
source - The source of events
rs - The state of the round
Method Detail

getRoundState

public RoundState getRoundState()
Return round state.

getSource

public AnnotationProcessorEnvironment getSource()
Return source.

Overrides:
getSource in class EventObject
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


RoundCompleteListener

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.apt
Interface RoundCompleteListener

All Superinterfaces:
AnnotationProcessorListener, EventListener
public interface RoundCompleteListener
extends AnnotationProcessorListener

Listener for the completion of a round of annotation processing.

Since:
1.5

Method Summary
 void roundComplete(RoundCompleteEvent event)
Invoked after all processors for a round have run to completion.

Method Detail

roundComplete

void roundComplete(RoundCompleteEvent event)
Invoked after all processors for a round have run to completion.

Parameters:
event - An event for round completion
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


RoundState

Mirror API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.apt
Interface RoundState

public interface RoundState

Represents the status of a completed round of annotation processing.

Since:
1.5

Method Summary
boolean | classFilesCreated() Returns true if new class files were created in this round of processing; returns false otherwise.
boolean | errorRaised() Returns true if an error was raised in this round of processing; returns false otherwise.
boolean | finalRound() Returns true if this was the last round of annotation processing; returns false if there will be a subsequent round.
boolean | sourceFilesCreated() Returns true if new source files were created in this round of processing; returns false otherwise.

Method Detail

finalRound

boolean finalRound()
Returns true if this was the last round of annotation processing; returns false if there will be a subsequent round.

errorRaised

boolean errorRaised()
Returns true if an error was raised in this round of processing; returns false otherwise.

sourceFilesCreated

boolean sourceFilesCreated()
Returns true if new source files were created in this round of processing; returns false otherwise.

classFilesCreated

boolean classFilesCreated()
Returns true if new class files were created in this round of processing; returns false otherwise.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


declaration

Mirror API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package com.sun.mirror.declaration

Interfaces used to model program element declarations.

See:
Description

Interface Summary
AnnotationMirror | Represents an annotation.
AnnotationTypeDeclaration | Represents the declaration of an annotation type.
AnnotationTypeElementDeclaration | Represents an element of an annotation type.
AnnotationValue | Represents a value of an annotation type element.
ClassDeclaration | Represents the declaration of a class.
ConstructorDeclaration | Represents a constructor of a class or interface.
Declaration | Represents the declaration of a program element such as a package, class, or method.
EnumConstantDeclaration | Represents an enum constant declaration.
EnumDeclaration | Represents the declaration of an enum type.
ExecutableDeclaration | Represents a method or constructor of a class or interface.
FieldDeclaration | Represents a field of a type declaration.
InterfaceDeclaration | Represents the declaration of an interface.
MemberDeclaration | Represents a declaration that may be a member or constructor of a declared type.
MethodDeclaration | Represents a method of a class or interface.
PackageDeclaration | Represents the declaration of a package.
ParameterDeclaration | Represents a formal parameter of a method or constructor.
TypeDeclaration | Represents the declaration of a class or interface.
TypeParameterDeclaration | Represents a formal type parameter of a generic type, method, or constructor declaration.

Enum Summary
Modifier Represents a modifier on the declaration of a program element such as a class, method, or field.

Package com.sun.mirror.declaration Description

Interfaces used to model program element declarations. A declaration is represented by the appropriate subinterface of Declaration, and an annotation is represented as an AnnotationMirror.

Note that the apt tool and its associated APIs may be changed or superseded in future j2se releases.

Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Mirror API
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


com.sun.mirror.declaration Class Hierarchy

Mirror API
PREV NEXT FRAMES NO FRAMES

Hierarchy For Package com.sun.mirror.declaration

Package Hierarchies:
All Packages

Interface Hierarchy

  • com.sun.mirror.declaration.AnnotationMirror
  • com.sun.mirror.declaration.AnnotationValue
  • com.sun.mirror.declaration.Declaration
    • com.sun.mirror.declaration.MemberDeclaration
      • com.sun.mirror.declaration.ExecutableDeclaration
        • com.sun.mirror.declaration.ConstructorDeclaration
        • com.sun.mirror.declaration.MethodDeclaration
          • com.sun.mirror.declaration.AnnotationTypeElementDeclaration
      • com.sun.mirror.declaration.FieldDeclaration
        • com.sun.mirror.declaration.EnumConstantDeclaration
      • com.sun.mirror.declaration.TypeDeclaration
        • com.sun.mirror.declaration.ClassDeclaration
          • com.sun.mirror.declaration.EnumDeclaration
        • com.sun.mirror.declaration.InterfaceDeclaration
          • com.sun.mirror.declaration.AnnotationTypeDeclaration
    • com.sun.mirror.declaration.PackageDeclaration
    • com.sun.mirror.declaration.ParameterDeclaration
    • com.sun.mirror.declaration.TypeParameterDeclaration

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • com.sun.mirror.declaration.Modifier
Overview Package Class Use Tree Deprecated Index Help
Mirror API
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ConstructorDeclaration

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface ConstructorDeclaration

All Superinterfaces:
Declaration, ExecutableDeclaration, MemberDeclaration
public interface ConstructorDeclaration
extends ExecutableDeclaration

Represents a constructor of a class or interface.

Since:
1.5

Method Summary
Methods inherited from interface com.sun.mirror.declaration.ExecutableDeclaration
getFormalTypeParameters, getParameters, getThrownTypes, isVarArgs
Methods inherited from interface com.sun.mirror.declaration.MemberDeclaration
getDeclaringType
Methods inherited from interface com.sun.mirror.declaration.Declaration
accept, equals, getAnnotation, getAnnotationMirrors, getDocComment, getModifiers, getPosition, getSimpleName

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


InterfaceDeclaration

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface InterfaceDeclaration

All Superinterfaces:
Declaration, MemberDeclaration, TypeDeclaration
All Known Subinterfaces:
AnnotationTypeDeclaration
public interface InterfaceDeclaration
extends TypeDeclaration

Represents the declaration of an interface. Provides access to information about the interface and its members. Note that an annotation type is a kind of interface.

While an InterfaceDeclaration represents the declaration of an interface, an InterfaceType represents an interface type. See TypeDeclaration for more on this distinction.

Since:
1.5
See Also:
InterfaceType

Method Summary
Methods inherited from interface com.sun.mirror.declaration.TypeDeclaration
getFields, getFormalTypeParameters, getMethods, getNestedTypes, getPackage, getQualifiedName, getSuperinterfaces
Methods inherited from interface com.sun.mirror.declaration.MemberDeclaration
getDeclaringType
Methods inherited from interface com.sun.mirror.declaration.Declaration
accept, equals, getAnnotation, getAnnotationMirrors, getDocComment, getModifiers, getPosition, getSimpleName

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Package com.sun.mirror.declaration

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Package
com.sun.mirror.declaration

Packages that use com.sun.mirror.declaration
com.sun.mirror.apt | Classes used to communicate information between annotation processors and an annotation processing tool.
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.type | Interfaces used to model types.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Classes in com.sun.mirror.declaration used by com.sun.mirror.apt
AnnotationTypeDeclaration
Represents the declaration of an annotation type.
Declaration
Represents the declaration of a program element such as a package, class, or method.
PackageDeclaration
Represents the declaration of a package.
TypeDeclaration
Represents the declaration of a class or interface.

Classes in com.sun.mirror.declaration used by com.sun.mirror.declaration
AnnotationMirror
Represents an annotation.
AnnotationTypeDeclaration
Represents the declaration of an annotation type.
AnnotationTypeElementDeclaration
Represents an element of an annotation type.
AnnotationValue
Represents a value of an annotation type element.
ClassDeclaration
Represents the declaration of a class.
ConstructorDeclaration
Represents a constructor of a class or interface.
Declaration
Represents the declaration of a program element such as a package, class, or method.
EnumConstantDeclaration
Represents an enum constant declaration.
EnumDeclaration
Represents the declaration of an enum type.
ExecutableDeclaration
Represents a method or constructor of a class or interface.
FieldDeclaration
Represents a field of a type declaration.
InterfaceDeclaration
Represents the declaration of an interface.
MemberDeclaration
Represents a declaration that may be a member or constructor of a declared type.
MethodDeclaration
Represents a method of a class or interface.
Modifier
Represents a modifier on the declaration of a program element such as a class, method, or field.
PackageDeclaration
Represents the declaration of a package.
ParameterDeclaration
Represents a formal parameter of a method or constructor.
TypeDeclaration
Represents the declaration of a class or interface.
TypeParameterDeclaration
Represents a formal type parameter of a generic type, method, or constructor declaration.

Classes in com.sun.mirror.declaration used by com.sun.mirror.type
AnnotationTypeDeclaration
Represents the declaration of an annotation type.
ClassDeclaration
Represents the declaration of a class.
EnumDeclaration
Represents the declaration of an enum type.
InterfaceDeclaration
Represents the declaration of an interface.
TypeDeclaration
Represents the declaration of a class or interface.
TypeParameterDeclaration
Represents a formal type parameter of a generic type, method, or constructor declaration.

Classes in com.sun.mirror.declaration used by com.sun.mirror.util
AnnotationTypeDeclaration
Represents the declaration of an annotation type.
AnnotationTypeElementDeclaration
Represents an element of an annotation type.
ClassDeclaration
Represents the declaration of a class.
ConstructorDeclaration
Represents a constructor of a class or interface.
Declaration
Represents the declaration of a program element such as a package, class, or method.
EnumConstantDeclaration
Represents an enum constant declaration.
EnumDeclaration
Represents the declaration of an enum type.
ExecutableDeclaration
Represents a method or constructor of a class or interface.
FieldDeclaration
Represents a field of a type declaration.
InterfaceDeclaration
Represents the declaration of an interface.
MemberDeclaration
Represents a declaration that may be a member or constructor of a declared type.
MethodDeclaration
Represents a method of a class or interface.
Modifier
Represents a modifier on the declaration of a program element such as a class, method, or field.
PackageDeclaration
Represents the declaration of a package.
ParameterDeclaration
Represents a formal parameter of a method or constructor.
TypeDeclaration
Represents the declaration of a class or interface.
TypeParameterDeclaration
Represents a formal type parameter of a generic type, method, or constructor declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


AnnotationMirror

Mirror API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface AnnotationMirror

public interface AnnotationMirror

Represents an annotation. An annotation associates a value with each element of an annotation type.

Annotations should not be compared using reference-equality ("=="). There is no guarantee that any particular annotation will always be represented by the same object.

Since:
1.5

Method Summary
AnnotationType | getAnnotationType() Returns the annotation type of this annotation.
Map<AnnotationTypeElementDeclaration,AnnotationValue> | getElementValues() Returns this annotation's elements and their values.
SourcePosition | getPosition() Returns the source position of the beginning of this annotation.

Method Detail

getAnnotationType

AnnotationType getAnnotationType()
Returns the annotation type of this annotation.

Returns:
the annotation type of this annotation

getPosition

SourcePosition getPosition()
Returns the source position of the beginning of this annotation. Returns null if the position is unknown or not applicable.

This source position is intended for use in providing diagnostics, and indicates only approximately where an annotation begins.

Returns:
the source position of the beginning of this annotation or null if the position is unknown or not applicable

getElementValues

Map<AnnotationTypeElementDeclaration,AnnotationValue> getElementValues()
Returns this annotation's elements and their values. This is returned in the form of a map that associates elements with their corresponding values. Only those elements and values explicitly present in the annotation are included, not those that are implicitly assuming their default values. The order of the map matches the order in which the elements appear in the annotation's source.

Returns:
this annotation's elements and their values, or an empty map if there are none
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


AnnotationTypeDeclaration

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface AnnotationTypeDeclaration

All Superinterfaces:
Declaration, InterfaceDeclaration, MemberDeclaration, TypeDeclaration
public interface AnnotationTypeDeclaration
extends InterfaceDeclaration

Represents the declaration of an annotation type.

Since:
1.5

Method Summary
 Collection<AnnotationTypeElementDeclaration> getMethods()
Returns the annotation type elements of this annotation type.
Methods inherited from interface com.sun.mirror.declaration.TypeDeclaration
getFields, getFormalTypeParameters, getNestedTypes, getPackage, getQualifiedName, getSuperinterfaces
Methods inherited from interface com.sun.mirror.declaration.MemberDeclaration
getDeclaringType
Methods inherited from interface com.sun.mirror.declaration.Declaration
accept, equals, getAnnotation, getAnnotationMirrors, getDocComment, getModifiers, getPosition, getSimpleName

Method Detail

getMethods

Collection<AnnotationTypeElementDeclaration> getMethods()
Returns the annotation type elements of this annotation type. These are the methods that are directly declared in the type's declaration.

Specified by:
getMethods in interface TypeDeclaration
Returns:
the annotation type elements of this annotation type, or an empty collection if there are none
See Also:
DeclarationFilter
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


AnnotationTypeElementDeclaration

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface AnnotationTypeElementDeclaration

All Superinterfaces:
Declaration, ExecutableDeclaration, MemberDeclaration, MethodDeclaration
public interface AnnotationTypeElementDeclaration
extends MethodDeclaration

Represents an element of an annotation type.

Since:
1.5

Method Summary
AnnotationTypeDeclaration | getDeclaringType() Returns the type declaration within which this member or constructor is declared.
AnnotationValue | getDefaultValue() Returns the default value of this element.
Methods inherited from interface com.sun.mirror.declaration.MethodDeclaration
getReturnType
Methods inherited from interface com.sun.mirror.declaration.ExecutableDeclaration
getFormalTypeParameters, getParameters, getThrownTypes, isVarArgs
Methods inherited from interface com.sun.mirror.declaration.Declaration
accept, equals, getAnnotation, getAnnotationMirrors, getDocComment, getModifiers, getPosition, getSimpleName

Method Detail

getDefaultValue

AnnotationValue getDefaultValue()
Returns the default value of this element.

Returns:
the default value of this element, or null if this element has no default.

getDeclaringType

AnnotationTypeDeclaration getDeclaringType()
Returns the type declaration within which this member or constructor is declared. If this is the declaration of a top-level type (a non-nested class or interface), returns null.

Specified by:
getDeclaringType in interface MemberDeclaration
Returns:
the type declaration within which this member or constructor is declared, or null if there is none
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


AnnotationValue

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface AnnotationValue

public interface AnnotationValue

Represents a value of an annotation type element.

Since:
1.5

Method Summary
SourcePosition | getPosition() Returns the source position of the beginning of this annotation value.
Object | getValue() Returns the value.
String | toString() Returns a string representation of this value.

Method Detail

getValue

Object getValue()
Returns the value. The result has one of the following types:
  • a wrapper class (such as Integer) for a primitive type
  • String
  • TypeMirror
  • EnumConstantDeclaration
  • AnnotationMirror
  • Collection<AnnotationValue> (representing the elements, in order, if the value is an array)

Returns:
the value

getPosition

SourcePosition getPosition()
Returns the source position of the beginning of this annotation value. Returns null if the position is unknown or not applicable.

This source position is intended for use in providing diagnostics, and indicates only approximately where an annotation value begins.

Returns:
the source position of the beginning of this annotation value or null if the position is unknown or not applicable

toString

String toString()
Returns a string representation of this value. This is returned in a form suitable for representing this value in the source code of an annotation.

Overrides:
toString in class Object
Returns:
a string representation of this value
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.mirror.declaration.Modifier

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.mirror.declaration.Modifier

Packages that use Modifier
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of Modifier in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration that return Modifier
static Modifier | Modifier.valueOf(String name) Returns the enum constant of this type with the specified name.
static Modifier[] | Modifier.values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods in com.sun.mirror.declaration that return types with arguments of type Modifier
 Collection<Modifier> Declaration.getModifiers()
Returns the modifiers of this declaration, excluding annotations.

Uses of Modifier in com.sun.mirror.util

Method parameters in com.sun.mirror.util with type arguments of type Modifier
static DeclarationFilter DeclarationFilter.getFilter(Collection<Modifier> mods)
Returns a filter that selects declarations containing all of a collection of modifiers.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.AnnotationMirror

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.AnnotationMirror

Packages that use AnnotationMirror
com.sun.mirror.declaration Interfaces used to model program element declarations.

Uses of AnnotationMirror in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration that return types with arguments of type AnnotationMirror
 Collection<AnnotationMirror> Declaration.getAnnotationMirrors()
Returns the annotations that are directly present on this declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.AnnotationTypeDeclaration

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.AnnotationTypeDeclaration

Packages that use AnnotationTypeDeclaration
com.sun.mirror.apt | Classes used to communicate information between annotation processors and an annotation processing tool.
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.type | Interfaces used to model types.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of AnnotationTypeDeclaration in com.sun.mirror.apt

Methods in com.sun.mirror.apt with parameters of type AnnotationTypeDeclaration
 Collection<Declaration> AnnotationProcessorEnvironment.getDeclarationsAnnotatedWith(AnnotationTypeDeclaration a)
Returns the declarations annotated with the given annotation type.

Method parameters in com.sun.mirror.apt with type arguments of type AnnotationTypeDeclaration
 AnnotationProcessor AnnotationProcessorFactory.getProcessorFor(Set<AnnotationTypeDeclaration> atds, AnnotationProcessorEnvironment env)
Returns an annotation processor for a set of annotation types.

Uses of AnnotationTypeDeclaration in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration that return AnnotationTypeDeclaration
 AnnotationTypeDeclaration AnnotationTypeElementDeclaration.getDeclaringType()
Returns the type declaration within which this member or constructor is declared.

Methods in com.sun.mirror.declaration that return types with arguments of type AnnotationTypeDeclaration
 Collection<AnnotationTypeDeclaration> PackageDeclaration.getAnnotationTypes()
Returns the declarations of the top-level annotation types in this package.

Uses of AnnotationTypeDeclaration in com.sun.mirror.type

Methods in com.sun.mirror.type that return AnnotationTypeDeclaration
 AnnotationTypeDeclaration AnnotationType.getDeclaration()
Returns the declaration of this type.

Uses of AnnotationTypeDeclaration in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type AnnotationTypeDeclaration
void | SimpleDeclarationVisitor.visitAnnotationTypeDeclaration(AnnotationTypeDeclaration d) Visits an annotation type declaration.
void | DeclarationVisitor.visitAnnotationTypeDeclaration(AnnotationTypeDeclaration d) Visits an annotation type declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.AnnotationTypeElementDeclaration

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.AnnotationTypeElementDeclaration

Packages that use AnnotationTypeElementDeclaration
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of AnnotationTypeElementDeclaration in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration that return types with arguments of type AnnotationTypeElementDeclaration
Map<AnnotationTypeElementDeclaration,AnnotationValue> | AnnotationMirror.getElementValues() Returns this annotation's elements and their values.
Collection<AnnotationTypeElementDeclaration> | AnnotationTypeDeclaration.getMethods() Returns the annotation type elements of this annotation type.

Uses of AnnotationTypeElementDeclaration in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type AnnotationTypeElementDeclaration
void | SimpleDeclarationVisitor.visitAnnotationTypeElementDeclaration(AnnotationTypeElementDeclaration d) Visits an annotation type element declaration.
void | DeclarationVisitor.visitAnnotationTypeElementDeclaration(AnnotationTypeElementDeclaration d) Visits an annotation type element declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.AnnotationValue

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.AnnotationValue

Packages that use AnnotationValue
com.sun.mirror.declaration Interfaces used to model program element declarations.

Uses of AnnotationValue in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration that return AnnotationValue
 AnnotationValue AnnotationTypeElementDeclaration.getDefaultValue()
Returns the default value of this element.

Methods in com.sun.mirror.declaration that return types with arguments of type AnnotationValue
 Map<AnnotationTypeElementDeclaration,AnnotationValue> AnnotationMirror.getElementValues()
Returns this annotation's elements and their values.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.ClassDeclaration

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.ClassDeclaration

Packages that use ClassDeclaration
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.type | Interfaces used to model types.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of ClassDeclaration in com.sun.mirror.declaration

Subinterfaces of ClassDeclaration in com.sun.mirror.declaration
 interface EnumDeclaration
Represents the declaration of an enum type.

Methods in com.sun.mirror.declaration that return types with arguments of type ClassDeclaration
 Collection<ClassDeclaration> PackageDeclaration.getClasses()
Returns the declarations of the top-level classes in this package.

Uses of ClassDeclaration in com.sun.mirror.type

Methods in com.sun.mirror.type that return ClassDeclaration
 ClassDeclaration ClassType.getDeclaration()
Returns the declaration of this type.

Uses of ClassDeclaration in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type ClassDeclaration
void | SimpleDeclarationVisitor.visitClassDeclaration(ClassDeclaration d) Visits a class declaration.
void | DeclarationVisitor.visitClassDeclaration(ClassDeclaration d) Visits a class declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.ConstructorDeclaration

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.ConstructorDeclaration

Packages that use ConstructorDeclaration
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of ConstructorDeclaration in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration that return types with arguments of type ConstructorDeclaration
 Collection<ConstructorDeclaration> ClassDeclaration.getConstructors()
Returns the constructors of this class.

Uses of ConstructorDeclaration in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type ConstructorDeclaration
void | SimpleDeclarationVisitor.visitConstructorDeclaration(ConstructorDeclaration d) Visits a constructor declaration.
void | DeclarationVisitor.visitConstructorDeclaration(ConstructorDeclaration d) Visits a constructor declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.Declaration

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.Declaration

Packages that use Declaration
com.sun.mirror.apt | Classes used to communicate information between annotation processors and an annotation processing tool.
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of Declaration in com.sun.mirror.apt

Methods in com.sun.mirror.apt that return types with arguments of type Declaration
 Collection<Declaration> AnnotationProcessorEnvironment.getDeclarationsAnnotatedWith(AnnotationTypeDeclaration a)
Returns the declarations annotated with the given annotation type.

Uses of Declaration in com.sun.mirror.declaration

Subinterfaces of Declaration in com.sun.mirror.declaration
interface | AnnotationTypeDeclaration Represents the declaration of an annotation type.
interface | AnnotationTypeElementDeclaration Represents an element of an annotation type.
interface | ClassDeclaration Represents the declaration of a class.
interface | ConstructorDeclaration Represents a constructor of a class or interface.
interface | EnumConstantDeclaration Represents an enum constant declaration.
interface | EnumDeclaration Represents the declaration of an enum type.
interface | ExecutableDeclaration Represents a method or constructor of a class or interface.
interface | FieldDeclaration Represents a field of a type declaration.
interface | InterfaceDeclaration Represents the declaration of an interface.
interface | MemberDeclaration Represents a declaration that may be a member or constructor of a declared type.
interface | MethodDeclaration Represents a method of a class or interface.
interface | PackageDeclaration Represents the declaration of a package.
interface | ParameterDeclaration Represents a formal parameter of a method or constructor.
interface | TypeDeclaration Represents the declaration of a class or interface.
interface | TypeParameterDeclaration Represents a formal type parameter of a generic type, method, or constructor declaration.

Methods in com.sun.mirror.declaration that return Declaration
 Declaration TypeParameterDeclaration.getOwner()
Returns the type, method, or constructor declaration within which this type parameter is declared.

Uses of Declaration in com.sun.mirror.util

Methods in com.sun.mirror.util with type parameters of type Declaration
<D extends Declaration>
Collection<D>
DeclarationFilter.filter(Collection<? extends Declaration> decls, Class<D> resType)
Returns the declarations matched by this filter, with the result being restricted to declarations of a given kind.
<D extends Declaration>
Collection<D>
DeclarationFilter.filter(Collection<D> decls)
Returns the declarations matched by this filter.

Methods in com.sun.mirror.util with parameters of type Declaration
boolean | DeclarationFilter.matches(Declaration decl) Tests whether this filter matches a given declaration.
void | SimpleDeclarationVisitor.visitDeclaration(Declaration d) Visits a declaration.
void | DeclarationVisitor.visitDeclaration(Declaration d) Visits a declaration.

Method parameters in com.sun.mirror.util with type arguments of type Declaration
<D extends Declaration>
Collection<D>
DeclarationFilter.filter(Collection<? extends Declaration> decls, Class<D> resType)
Returns the declarations matched by this filter, with the result being restricted to declarations of a given kind.
static DeclarationFilter DeclarationFilter.getFilter(Class<? extends Declaration> kind)
Returns a filter that selects declarations of a particular kind.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.EnumConstantDeclaration

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.EnumConstantDeclaration

Packages that use EnumConstantDeclaration
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of EnumConstantDeclaration in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration that return types with arguments of type EnumConstantDeclaration
 Collection<EnumConstantDeclaration> EnumDeclaration.getEnumConstants()
Returns the enum constants defined for this enum.

Uses of EnumConstantDeclaration in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type EnumConstantDeclaration
void | SimpleDeclarationVisitor.visitEnumConstantDeclaration(EnumConstantDeclaration d) Visits an enum constant declaration.
void | DeclarationVisitor.visitEnumConstantDeclaration(EnumConstantDeclaration d) Visits an enum constant declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.EnumDeclaration

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.EnumDeclaration

Packages that use EnumDeclaration
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.type | Interfaces used to model types.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of EnumDeclaration in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration that return EnumDeclaration
 EnumDeclaration EnumConstantDeclaration.getDeclaringType()
Returns the type declaration within which this member or constructor is declared.

Methods in com.sun.mirror.declaration that return types with arguments of type EnumDeclaration
 Collection<EnumDeclaration> PackageDeclaration.getEnums()
Returns the declarations of the top-level enum types in this package.

Uses of EnumDeclaration in com.sun.mirror.type

Methods in com.sun.mirror.type that return EnumDeclaration
 EnumDeclaration EnumType.getDeclaration()
Returns the declaration of this type.

Uses of EnumDeclaration in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type EnumDeclaration
void | SimpleDeclarationVisitor.visitEnumDeclaration(EnumDeclaration d) Visits an enum declaration.
void | DeclarationVisitor.visitEnumDeclaration(EnumDeclaration d) Visits an enum declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.ExecutableDeclaration

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.ExecutableDeclaration

Packages that use ExecutableDeclaration
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of ExecutableDeclaration in com.sun.mirror.declaration

Subinterfaces of ExecutableDeclaration in com.sun.mirror.declaration
interface | AnnotationTypeElementDeclaration Represents an element of an annotation type.
interface | ConstructorDeclaration Represents a constructor of a class or interface.
interface | MethodDeclaration Represents a method of a class or interface.

Uses of ExecutableDeclaration in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type ExecutableDeclaration
void | SimpleDeclarationVisitor.visitExecutableDeclaration(ExecutableDeclaration d) Visits a method or constructor declaration.
void | DeclarationVisitor.visitExecutableDeclaration(ExecutableDeclaration d) Visits a method or constructor declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.FieldDeclaration

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.FieldDeclaration

Packages that use FieldDeclaration
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of FieldDeclaration in com.sun.mirror.declaration

Subinterfaces of FieldDeclaration in com.sun.mirror.declaration
 interface EnumConstantDeclaration
Represents an enum constant declaration.

Methods in com.sun.mirror.declaration that return types with arguments of type FieldDeclaration
 Collection<FieldDeclaration> TypeDeclaration.getFields()
Returns the fields that are directly declared by this class or interface.

Uses of FieldDeclaration in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type FieldDeclaration
void | SimpleDeclarationVisitor.visitFieldDeclaration(FieldDeclaration d) Visits a field declaration.
void | DeclarationVisitor.visitFieldDeclaration(FieldDeclaration d) Visits a field declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.InterfaceDeclaration

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.InterfaceDeclaration

Packages that use InterfaceDeclaration
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.type | Interfaces used to model types.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of InterfaceDeclaration in com.sun.mirror.declaration

Subinterfaces of InterfaceDeclaration in com.sun.mirror.declaration
 interface AnnotationTypeDeclaration
Represents the declaration of an annotation type.

Methods in com.sun.mirror.declaration that return types with arguments of type InterfaceDeclaration
 Collection<InterfaceDeclaration> PackageDeclaration.getInterfaces()
Returns the declarations of the top-level interfaces in this package.

Uses of InterfaceDeclaration in com.sun.mirror.type

Methods in com.sun.mirror.type that return InterfaceDeclaration
 InterfaceDeclaration InterfaceType.getDeclaration()
Returns the declaration of this type.

Uses of InterfaceDeclaration in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type InterfaceDeclaration
void | SimpleDeclarationVisitor.visitInterfaceDeclaration(InterfaceDeclaration d) Visits an interface declaration.
void | DeclarationVisitor.visitInterfaceDeclaration(InterfaceDeclaration d) Visits an interface declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.MemberDeclaration

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.MemberDeclaration

Packages that use MemberDeclaration
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of MemberDeclaration in com.sun.mirror.declaration

Subinterfaces of MemberDeclaration in com.sun.mirror.declaration
interface | AnnotationTypeDeclaration Represents the declaration of an annotation type.
interface | AnnotationTypeElementDeclaration Represents an element of an annotation type.
interface | ClassDeclaration Represents the declaration of a class.
interface | ConstructorDeclaration Represents a constructor of a class or interface.
interface | EnumConstantDeclaration Represents an enum constant declaration.
interface | EnumDeclaration Represents the declaration of an enum type.
interface | ExecutableDeclaration Represents a method or constructor of a class or interface.
interface | FieldDeclaration Represents a field of a type declaration.
interface | InterfaceDeclaration Represents the declaration of an interface.
interface | MethodDeclaration Represents a method of a class or interface.
interface | TypeDeclaration Represents the declaration of a class or interface.

Uses of MemberDeclaration in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type MemberDeclaration
boolean | Declarations.hides(MemberDeclaration sub, MemberDeclaration sup) Tests whether one type, method, or field declaration hides another.
void | SimpleDeclarationVisitor.visitMemberDeclaration(MemberDeclaration d) Visits a member or constructor declaration.
void | DeclarationVisitor.visitMemberDeclaration(MemberDeclaration d) Visits a member or constructor declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.MethodDeclaration

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.MethodDeclaration

Packages that use MethodDeclaration
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of MethodDeclaration in com.sun.mirror.declaration

Subinterfaces of MethodDeclaration in com.sun.mirror.declaration
 interface AnnotationTypeElementDeclaration
Represents an element of an annotation type.

Methods in com.sun.mirror.declaration that return types with arguments of type MethodDeclaration
Collection<MethodDeclaration> | ClassDeclaration.getMethods() Returns the methods that are directly declared by this class or interface.
Collection<? extends MethodDeclaration> | TypeDeclaration.getMethods() Returns the methods that are directly declared by this class or interface.

Uses of MethodDeclaration in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type MethodDeclaration
boolean | Declarations.overrides(MethodDeclaration sub, MethodDeclaration sup) Tests whether one method overrides another.
void | SimpleDeclarationVisitor.visitMethodDeclaration(MethodDeclaration d) Visits a method declaration.
void | DeclarationVisitor.visitMethodDeclaration(MethodDeclaration d) Visits a method declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.PackageDeclaration

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.PackageDeclaration

Packages that use PackageDeclaration
com.sun.mirror.apt | Classes used to communicate information between annotation processors and an annotation processing tool.
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of PackageDeclaration in com.sun.mirror.apt

Methods in com.sun.mirror.apt that return PackageDeclaration
 PackageDeclaration AnnotationProcessorEnvironment.getPackage(String name)
Returns the declaration of a package given its fully qualified name.

Uses of PackageDeclaration in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration that return PackageDeclaration
 PackageDeclaration TypeDeclaration.getPackage()
Returns the package within which this type is declared.

Uses of PackageDeclaration in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type PackageDeclaration
void | SimpleDeclarationVisitor.visitPackageDeclaration(PackageDeclaration d) Visits a package declaration.
void | DeclarationVisitor.visitPackageDeclaration(PackageDeclaration d) Visits a package declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.ParameterDeclaration

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.ParameterDeclaration

Packages that use ParameterDeclaration
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of ParameterDeclaration in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration that return types with arguments of type ParameterDeclaration
 Collection<ParameterDeclaration> ExecutableDeclaration.getParameters()
Returns the formal parameters of this method or constructor.

Uses of ParameterDeclaration in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type ParameterDeclaration
void | SimpleDeclarationVisitor.visitParameterDeclaration(ParameterDeclaration d) Visits a parameter declaration.
void | DeclarationVisitor.visitParameterDeclaration(ParameterDeclaration d) Visits a parameter declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.TypeDeclaration

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.TypeDeclaration

Packages that use TypeDeclaration
com.sun.mirror.apt | Classes used to communicate information between annotation processors and an annotation processing tool.
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.type | Interfaces used to model types.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of TypeDeclaration in com.sun.mirror.apt

Methods in com.sun.mirror.apt that return TypeDeclaration
 TypeDeclaration AnnotationProcessorEnvironment.getTypeDeclaration(String name)
Returns the declaration of a type given its fully qualified name.

Methods in com.sun.mirror.apt that return types with arguments of type TypeDeclaration
Collection<TypeDeclaration> | AnnotationProcessorEnvironment.getSpecifiedTypeDeclarations() Returns the declarations of the types specified when the annotation processing tool was invoked.
Collection<TypeDeclaration> | AnnotationProcessorEnvironment.getTypeDeclarations() A convenience method that returns the declarations of the types included in this invocation of the annotation processing tool.

Uses of TypeDeclaration in com.sun.mirror.declaration

Subinterfaces of TypeDeclaration in com.sun.mirror.declaration
interface | AnnotationTypeDeclaration Represents the declaration of an annotation type.
interface | ClassDeclaration Represents the declaration of a class.
interface | EnumDeclaration Represents the declaration of an enum type.
interface | InterfaceDeclaration Represents the declaration of an interface.

Methods in com.sun.mirror.declaration that return TypeDeclaration
 TypeDeclaration MemberDeclaration.getDeclaringType()
Returns the type declaration within which this member or constructor is declared.

Methods in com.sun.mirror.declaration that return types with arguments of type TypeDeclaration
 Collection<TypeDeclaration> TypeDeclaration.getNestedTypes()
Returns the declarations of the nested classes and interfaces that are directly declared by this class or interface.

Uses of TypeDeclaration in com.sun.mirror.type

Methods in com.sun.mirror.type that return TypeDeclaration
 TypeDeclaration DeclaredType.getDeclaration()
Returns the declaration of this type.

Uses of TypeDeclaration in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type TypeDeclaration
DeclaredType | Types.getDeclaredType(DeclaredType containing, TypeDeclaration decl, TypeMirror... typeArgs) Returns the type corresponding to a type declaration and actual arguments, given a containing type of which it is a member.
DeclaredType | Types.getDeclaredType(TypeDeclaration decl, TypeMirror... typeArgs) Returns the type corresponding to a type declaration and actual type arguments.
void | SimpleDeclarationVisitor.visitTypeDeclaration(TypeDeclaration d) Visits a type declaration.
void | DeclarationVisitor.visitTypeDeclaration(TypeDeclaration d) Visits a type declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.declaration.TypeParameterDeclaration

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.declaration.TypeParameterDeclaration

Packages that use TypeParameterDeclaration
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.type | Interfaces used to model types.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of TypeParameterDeclaration in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration that return types with arguments of type TypeParameterDeclaration
Collection<TypeParameterDeclaration> | ExecutableDeclaration.getFormalTypeParameters() Returns the formal type parameters of this method or constructor.
Collection<TypeParameterDeclaration> | TypeDeclaration.getFormalTypeParameters() Returns the formal type parameters of this class or interface.

Uses of TypeParameterDeclaration in com.sun.mirror.type

Methods in com.sun.mirror.type that return TypeParameterDeclaration
 TypeParameterDeclaration TypeVariable.getDeclaration()
Returns the type parameter that declared this type variable.

Uses of TypeParameterDeclaration in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type TypeParameterDeclaration
TypeVariable | Types.getTypeVariable(TypeParameterDeclaration tparam) Returns the type variable declared by a type parameter.
void | SimpleDeclarationVisitor.visitTypeParameterDeclaration(TypeParameterDeclaration d) Visits a type parameter declaration.
void | DeclarationVisitor.visitTypeParameterDeclaration(TypeParameterDeclaration d) Visits a type parameter declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ClassDeclaration

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface ClassDeclaration

All Superinterfaces:
Declaration, MemberDeclaration, TypeDeclaration
All Known Subinterfaces:
EnumDeclaration
public interface ClassDeclaration
extends TypeDeclaration

Represents the declaration of a class. For the declaration of an interface, see InterfaceDeclaration. Provides access to information about the class, its members, and its constructors. Note that an enum is a kind of class.

While a ClassDeclaration represents the declaration of a class, a ClassType represents a class type. See TypeDeclaration for more on this distinction.

DeclarationFilter provides a simple way to select just the items of interest when a method returns a collection of declarations.

Since:
1.5
See Also:
ClassType

Method Summary
Collection<ConstructorDeclaration> | getConstructors() Returns the constructors of this class.
Collection<MethodDeclaration> | getMethods() Returns the methods that are directly declared by this class or interface.
ClassType | getSuperclass() Returns the class type directly extended by this class.
Methods inherited from interface com.sun.mirror.declaration.TypeDeclaration
getFields, getFormalTypeParameters, getNestedTypes, getPackage, getQualifiedName, getSuperinterfaces
Methods inherited from interface com.sun.mirror.declaration.MemberDeclaration
getDeclaringType
Methods inherited from interface com.sun.mirror.declaration.Declaration
accept, equals, getAnnotation, getAnnotationMirrors, getDocComment, getModifiers, getPosition, getSimpleName

Method Detail

getSuperclass

ClassType getSuperclass()
Returns the class type directly extended by this class. The only class with no superclass is java.lang.Object, for which this method returns null.

Returns:
the class type directly extended by this class, or null if there is none

getConstructors

Collection<ConstructorDeclaration> getConstructors()
Returns the constructors of this class. This includes the default constructor if this class has no constructors explicitly declared.

Returns:
the constructors of this class
See Also:
DeclarationFilter

getMethods

Collection<MethodDeclaration> getMethods()
Returns the methods that are directly declared by this class or interface. Includes annotation type elements. Excludes implicitly declared methods of an interface, such as toString, that correspond to the methods of java.lang.Object.

Specified by:
getMethods in interface TypeDeclaration
Returns:
the methods that are directly declared, or an empty collection if there are none
See Also:
DeclarationFilter
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Declaration

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface Declaration

All Known Subinterfaces:
AnnotationTypeDeclaration, AnnotationTypeElementDeclaration, ClassDeclaration, ConstructorDeclaration, EnumConstantDeclaration, EnumDeclaration, ExecutableDeclaration, FieldDeclaration, InterfaceDeclaration, MemberDeclaration, MethodDeclaration, PackageDeclaration, ParameterDeclaration, TypeDeclaration, TypeParameterDeclaration
public interface Declaration

Represents the declaration of a program element such as a package, class, or method. Each declaration represents a static, language-level construct (and not, for example, a runtime construct of the virtual machine), and typically corresponds one-to-one with a particular fragment of source code.

Declarations should be compared using the equals(Object) method. There is no guarantee that any particular declaration will always be represented by the same object.

Since:
1.5
See Also:
Declarations, TypeMirror

Method Summary
 void accept(DeclarationVisitor v)
Applies a visitor to this declaration.
 boolean equals(Object obj)
Tests whether an object represents the same declaration as this.
<A extends Annotation>
A
getAnnotation(Class<A> annotationType)
Returns the annotation of this declaration having the specified type.
 Collection<AnnotationMirror> getAnnotationMirrors()
Returns the annotations that are directly present on this declaration.
 String getDocComment()
Returns the text of the documentation ("javadoc") comment of this declaration.
 Collection<Modifier> getModifiers()
Returns the modifiers of this declaration, excluding annotations.
 SourcePosition getPosition()
Returns the source position of the beginning of this declaration.
 String getSimpleName()
Returns the simple (unqualified) name of this declaration.

Method Detail

equals

boolean equals(Object obj)
Tests whether an object represents the same declaration as this.

Overrides:
equals in class Object
Parameters:
obj - the object to be compared with this declaration
Returns:
true if the specified object represents the same declaration as this

getDocComment

String getDocComment()
Returns the text of the documentation ("javadoc") comment of this declaration.

Returns:
the documentation comment of this declaration, or null if there is none

getAnnotationMirrors

Collection<AnnotationMirror> getAnnotationMirrors()
Returns the annotations that are directly present on this declaration.

Returns:
the annotations directly present on this declaration; an empty collection if there are none

getAnnotation

<A extends Annotation> A getAnnotation(Class<A> annotationType)
Returns the annotation of this declaration having the specified type. The annotation may be either inherited or directly present on this declaration.

The annotation returned by this method could contain an element whose value is of type Class. This value cannot be returned directly: information necessary to locate and load a class (such as the class loader to use) is not available, and the class might not be loadable at all. Attempting to read a Class object by invoking the relevant method on the returned annotation will result in a MirroredTypeException, from which the corresponding TypeMirror may be extracted. Similarly, attempting to read a Class[]-valued element will result in a MirroredTypesException.

Note: This method is unlike others in this and related interfaces. It operates on run-time reflective information -- representations of annotation types currently loaded into the VM -- rather than on the mirrored representations defined by and used throughout these interfaces. It is intended for callers that are written to operate on a known, fixed set of annotation types.

Type Parameters:
A - the annotation type
Parameters:
annotationType - the Class object corresponding to the annotation type
Returns:
the annotation of this declaration having the specified type
See Also:
getAnnotationMirrors()

getModifiers

Collection<Modifier> getModifiers()
Returns the modifiers of this declaration, excluding annotations. Implicit modifiers, such as the public and static modifiers of interface members, are included.

Returns:
the modifiers of this declaration in undefined order; an empty collection if there are none

getSimpleName

String getSimpleName()
Returns the simple (unqualified) name of this declaration. The name of a generic type does not include any reference to its formal type parameters. For example, the simple name of the interface declaration java.util.Set<E> is "Set". If this declaration represents the empty package, an empty string is returned. If it represents a constructor, the simple name of its declaring class is returned.

Returns:
the simple name of this declaration

getPosition

SourcePosition getPosition()
Returns the source position of the beginning of this declaration. Returns null if the position is unknown or not applicable.

This source position is intended for use in providing diagnostics, and indicates only approximately where a declaration begins.

Returns:
the source position of the beginning of this declaration, or null if the position is unknown or not applicable

accept

void accept(DeclarationVisitor v)
Applies a visitor to this declaration.

Parameters:
v - the visitor operating on this declaration
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


EnumConstantDeclaration

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface EnumConstantDeclaration

All Superinterfaces:
Declaration, FieldDeclaration, MemberDeclaration
public interface EnumConstantDeclaration
extends FieldDeclaration

Represents an enum constant declaration.

Since:
1.5

Method Summary
 EnumDeclaration getDeclaringType()
Returns the type declaration within which this member or constructor is declared.
Methods inherited from interface com.sun.mirror.declaration.FieldDeclaration
getConstantExpression, getConstantValue, getType
Methods inherited from interface com.sun.mirror.declaration.Declaration
accept, equals, getAnnotation, getAnnotationMirrors, getDocComment, getModifiers, getPosition, getSimpleName

Method Detail

getDeclaringType

EnumDeclaration getDeclaringType()
Returns the type declaration within which this member or constructor is declared. If this is the declaration of a top-level type (a non-nested class or interface), returns null.

Specified by:
getDeclaringType in interface MemberDeclaration
Returns:
the type declaration within which this member or constructor is declared, or null if there is none
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


EnumDeclaration

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface EnumDeclaration

All Superinterfaces:
ClassDeclaration, Declaration, MemberDeclaration, TypeDeclaration
public interface EnumDeclaration
extends ClassDeclaration

Represents the declaration of an enum type.

Since:
1.5

Method Summary
 Collection<EnumConstantDeclaration> getEnumConstants()
Returns the enum constants defined for this enum.
Methods inherited from interface com.sun.mirror.declaration.ClassDeclaration
getConstructors, getMethods, getSuperclass
Methods inherited from interface com.sun.mirror.declaration.TypeDeclaration
getFields, getFormalTypeParameters, getNestedTypes, getPackage, getQualifiedName, getSuperinterfaces
Methods inherited from interface com.sun.mirror.declaration.MemberDeclaration
getDeclaringType
Methods inherited from interface com.sun.mirror.declaration.Declaration
accept, equals, getAnnotation, getAnnotationMirrors, getDocComment, getModifiers, getPosition, getSimpleName

Method Detail

getEnumConstants

Collection<EnumConstantDeclaration> getEnumConstants()
Returns the enum constants defined for this enum.

Returns:
the enum constants defined for this enum, or an empty collection if there are none
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ExecutableDeclaration

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface ExecutableDeclaration

All Superinterfaces:
Declaration, MemberDeclaration
All Known Subinterfaces:
AnnotationTypeElementDeclaration, ConstructorDeclaration, MethodDeclaration
public interface ExecutableDeclaration
extends MemberDeclaration

Represents a method or constructor of a class or interface.

Since:
1.5

Method Summary
Collection<TypeParameterDeclaration> | getFormalTypeParameters() Returns the formal type parameters of this method or constructor.
Collection<ParameterDeclaration> | getParameters() Returns the formal parameters of this method or constructor.
Collection<ReferenceType> | getThrownTypes() Returns the exceptions and other throwables listed in this method or constructor's throws clause.
boolean | isVarArgs() Returns true if this method or constructor accepts a variable number of arguments.
Methods inherited from interface com.sun.mirror.declaration.MemberDeclaration
getDeclaringType
Methods inherited from interface com.sun.mirror.declaration.Declaration
accept, equals, getAnnotation, getAnnotationMirrors, getDocComment, getModifiers, getPosition, getSimpleName

Method Detail

isVarArgs

boolean isVarArgs()
Returns true if this method or constructor accepts a variable number of arguments.

Returns:
true if this method or constructor accepts a variable number of arguments

getFormalTypeParameters

Collection<TypeParameterDeclaration> getFormalTypeParameters()
Returns the formal type parameters of this method or constructor. They are returned in declaration order.

Returns:
the formal type parameters of this method or constructor, or an empty collection if there are none

getParameters

Collection<ParameterDeclaration> getParameters()
Returns the formal parameters of this method or constructor. They are returned in declaration order.

Returns:
the formal parameters of this method or constructor, or an empty collection if there are none

getThrownTypes

Collection<ReferenceType> getThrownTypes()
Returns the exceptions and other throwables listed in this method or constructor's throws clause.

Returns:
the exceptions and other throwables listed in the throws clause, or an empty collection if there are none
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


FieldDeclaration

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface FieldDeclaration

All Superinterfaces:
Declaration, MemberDeclaration
All Known Subinterfaces:
EnumConstantDeclaration
public interface FieldDeclaration
extends MemberDeclaration

Represents a field of a type declaration.

Since:
1.5

Method Summary
String | getConstantExpression() Returns the text of a constant expression representing the value of this field if this field is a compile-time constant.
Object | getConstantValue() Returns the value of this field if this field is a compile-time constant.
TypeMirror | getType() Returns the type of this field.
Methods inherited from interface com.sun.mirror.declaration.MemberDeclaration
getDeclaringType
Methods inherited from interface com.sun.mirror.declaration.Declaration
accept, equals, getAnnotation, getAnnotationMirrors, getDocComment, getModifiers, getPosition, getSimpleName

Method Detail

getType

TypeMirror getType()
Returns the type of this field.

Returns:
the type of this field

getConstantValue

Object getConstantValue()
Returns the value of this field if this field is a compile-time constant. Returns null otherwise. The value will be of a primitive type or String. If the value is of a primitive type, it is wrapped in the appropriate wrapper class (such as Integer).

Returns:
the value of this field if this field is a compile-time constant, or null otherwise

getConstantExpression

String getConstantExpression()
Returns the text of a constant expression representing the value of this field if this field is a compile-time constant. Returns null otherwise. The value will be of a primitive type or String. The text returned is in a form suitable for representing the value in source code.

Returns:
the text of a constant expression if this field is a compile-time constant, or null otherwise
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


MemberDeclaration

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface MemberDeclaration

All Superinterfaces:
Declaration
All Known Subinterfaces:
AnnotationTypeDeclaration, AnnotationTypeElementDeclaration, ClassDeclaration, ConstructorDeclaration, EnumConstantDeclaration, EnumDeclaration, ExecutableDeclaration, FieldDeclaration, InterfaceDeclaration, MethodDeclaration, TypeDeclaration
public interface MemberDeclaration
extends Declaration

Represents a declaration that may be a member or constructor of a declared type. This includes fields, constructors, methods, and (since they may be nested) declared types themselves.

Since:
1.5

Method Summary
 TypeDeclaration getDeclaringType()
Returns the type declaration within which this member or constructor is declared.
Methods inherited from interface com.sun.mirror.declaration.Declaration
accept, equals, getAnnotation, getAnnotationMirrors, getDocComment, getModifiers, getPosition, getSimpleName

Method Detail

getDeclaringType

TypeDeclaration getDeclaringType()
Returns the type declaration within which this member or constructor is declared. If this is the declaration of a top-level type (a non-nested class or interface), returns null.

Returns:
the type declaration within which this member or constructor is declared, or null if there is none
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


MethodDeclaration

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface MethodDeclaration

All Superinterfaces:
Declaration, ExecutableDeclaration, MemberDeclaration
All Known Subinterfaces:
AnnotationTypeElementDeclaration
public interface MethodDeclaration
extends ExecutableDeclaration

Represents a method of a class or interface. Note that an annotation type element is a kind of method.

Since:
1.5

Method Summary
 TypeMirror getReturnType()
Returns the formal return type of this method.
Methods inherited from interface com.sun.mirror.declaration.ExecutableDeclaration
getFormalTypeParameters, getParameters, getThrownTypes, isVarArgs
Methods inherited from interface com.sun.mirror.declaration.MemberDeclaration
getDeclaringType
Methods inherited from interface com.sun.mirror.declaration.Declaration
accept, equals, getAnnotation, getAnnotationMirrors, getDocComment, getModifiers, getPosition, getSimpleName

Method Detail

getReturnType

TypeMirror getReturnType()
Returns the formal return type of this method. Returns VoidType if this method does not return a value.

Returns:
the formal return type of this method
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Modifier

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

com.sun.mirror.declaration
Enum Modifier

java.lang.Object
    extended by  java.lang.Enum<Modifier>
        extended by  com.sun.mirror.declaration.Modifier
All Implemented Interfaces:
Serializable, Comparable<Modifier>
public enum Modifier
extends Enum<Modifier>

Represents a modifier on the declaration of a program element such as a class, method, or field.

Not all modifiers are applicable to all kinds of declarations. When two or more modifiers appear in the source code of a declaration, then it is customary, though not required, that they appear in the same order as the constants listed in the detail section below.

Since:
1.5

Enum Constant Summary
ABSTRACT
The modifier abstract
FINAL
The modifier final
NATIVE
The modifier native
PRIVATE
The modifier private
PROTECTED
The modifier protected
PUBLIC
The modifier public
STATIC
The modifier static
STRICTFP
The modifier strictfp
SYNCHRONIZED
The modifier synchronized
TRANSIENT
The modifier transient
VOLATILE
The modifier volatile
Method Summary
String | toString() Returns this modifier's name in lowercase.
static Modifier | valueOf(String name) Returns the enum constant of this type with the specified name.
static Modifier[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

PUBLIC

public static final Modifier PUBLIC
The modifier public

PROTECTED

public static final Modifier PROTECTED
The modifier protected

PRIVATE

public static final Modifier PRIVATE
The modifier private

ABSTRACT

public static final Modifier ABSTRACT
The modifier abstract

STATIC

public static final Modifier STATIC
The modifier static

FINAL

public static final Modifier FINAL
The modifier final

TRANSIENT

public static final Modifier TRANSIENT
The modifier transient

VOLATILE

public static final Modifier VOLATILE
The modifier volatile

SYNCHRONIZED

public static final Modifier SYNCHRONIZED
The modifier synchronized

NATIVE

public static final Modifier NATIVE
The modifier native

STRICTFP

public static final Modifier STRICTFP
The modifier strictfp

Method Detail

values

public static Modifier[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (Modifier c : Modifier.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static Modifier valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null

toString

public String toString()
Returns this modifier's name in lowercase.

Overrides:
toString in class Enum<Modifier>
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


PackageDeclaration

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface PackageDeclaration

All Superinterfaces:
Declaration
public interface PackageDeclaration
extends Declaration

Represents the declaration of a package. Provides access to information about the package and its members.

DeclarationFilter provides a simple way to select just the items of interest when a method returns a collection of declarations.

Since:
1.5

Method Summary
Collection<AnnotationTypeDeclaration> | getAnnotationTypes() Returns the declarations of the top-level annotation types in this package.
Collection<ClassDeclaration> | getClasses() Returns the declarations of the top-level classes in this package.
Collection<EnumDeclaration> | getEnums() Returns the declarations of the top-level enum types in this package.
Collection<InterfaceDeclaration> | getInterfaces() Returns the declarations of the top-level interfaces in this package.
String | getQualifiedName() Returns the fully qualified name of this package.
Methods inherited from interface com.sun.mirror.declaration.Declaration
accept, equals, getAnnotation, getAnnotationMirrors, getDocComment, getModifiers, getPosition, getSimpleName

Method Detail

getQualifiedName

String getQualifiedName()
Returns the fully qualified name of this package. This is also known as the package's canonical name.

Returns:
the fully qualified name of this package, or the empty string if this is the unnamed package

getClasses

Collection<ClassDeclaration> getClasses()
Returns the declarations of the top-level classes in this package. Interfaces are not included, but enum types are.

Returns:
the declarations of the top-level classes in this package
See Also:
DeclarationFilter

getEnums

Collection<EnumDeclaration> getEnums()
Returns the declarations of the top-level enum types in this package.

Returns:
the declarations of the top-level enum types in this package
See Also:
DeclarationFilter

getInterfaces

Collection<InterfaceDeclaration> getInterfaces()
Returns the declarations of the top-level interfaces in this package. Annotation types are included.

Returns:
the declarations of the top-level interfaces in this package
See Also:
DeclarationFilter

getAnnotationTypes

Collection<AnnotationTypeDeclaration> getAnnotationTypes()
Returns the declarations of the top-level annotation types in this package.

Returns:
the declarations of the top-level annotation types in this package
See Also:
DeclarationFilter
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ParameterDeclaration

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface ParameterDeclaration

All Superinterfaces:
Declaration
public interface ParameterDeclaration
extends Declaration

Represents a formal parameter of a method or constructor.

Since:
1.5

Method Summary
 TypeMirror getType()
Returns the type of this parameter.
Methods inherited from interface com.sun.mirror.declaration.Declaration
accept, equals, getAnnotation, getAnnotationMirrors, getDocComment, getModifiers, getPosition, getSimpleName

Method Detail

getType

TypeMirror getType()
Returns the type of this parameter.

Returns:
the type of this parameter
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


TypeDeclaration

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface TypeDeclaration

All Superinterfaces:
Declaration, MemberDeclaration
All Known Subinterfaces:
AnnotationTypeDeclaration, ClassDeclaration, EnumDeclaration, InterfaceDeclaration
public interface TypeDeclaration
extends MemberDeclaration

Represents the declaration of a class or interface. Provides access to information about the type and its members. Note that an enum is a kind of class, and an annotation type is a kind of interface.

While a TypeDeclaration represents the declaration of a class or interface, a DeclaredType represents a class or interface type, the latter being a use (or invocation) of the former. The distinction is most apparent with generic types, for which a single declaration can define a whole family of types. For example, the declaration of java.util.Set corresponds to the parameterized types java.util.Set<String> and java.util.Set<Number> (and many others), and to the raw type java.util.Set.

DeclarationFilter provides a simple way to select just the items of interest when a method returns a collection of declarations.

Since:
1.5
See Also:
DeclaredType

Method Summary
Collection<FieldDeclaration> | getFields() Returns the fields that are directly declared by this class or interface.
Collection<TypeParameterDeclaration> | getFormalTypeParameters() Returns the formal type parameters of this class or interface.
Collection<? extends MethodDeclaration> | getMethods() Returns the methods that are directly declared by this class or interface.
Collection<TypeDeclaration> | getNestedTypes() Returns the declarations of the nested classes and interfaces that are directly declared by this class or interface.
PackageDeclaration | getPackage() Returns the package within which this type is declared.
String | getQualifiedName() Returns the fully qualified name of this class or interface declaration.
Collection<InterfaceType> | getSuperinterfaces() Returns the interface types directly implemented by this class or extended by this interface.
Methods inherited from interface com.sun.mirror.declaration.MemberDeclaration
getDeclaringType
Methods inherited from interface com.sun.mirror.declaration.Declaration
accept, equals, getAnnotation, getAnnotationMirrors, getDocComment, getModifiers, getPosition, getSimpleName

Method Detail

getPackage

PackageDeclaration getPackage()
Returns the package within which this type is declared.

Returns:
the package within which this type is declared

getQualifiedName

String getQualifiedName()
Returns the fully qualified name of this class or interface declaration. More precisely, it returns the canonical name. The name of a generic type does not include any reference to its formal type parameters. For example, the the fully qualified name of the interface declaration java.util.Set<E> is "java.util.Set".

Returns:
the fully qualified name of this class or interface declaration

getFormalTypeParameters

Collection<TypeParameterDeclaration> getFormalTypeParameters()
Returns the formal type parameters of this class or interface.

Returns:
the formal type parameters, or an empty collection if there are none

getSuperinterfaces

Collection<InterfaceType> getSuperinterfaces()
Returns the interface types directly implemented by this class or extended by this interface.

Returns:
the interface types directly implemented by this class or extended by this interface, or an empty collection if there are none
See Also:
DeclarationFilter

getFields

Collection<FieldDeclaration> getFields()
Returns the fields that are directly declared by this class or interface. Includes enum constants.

Returns:
the fields that are directly declared, or an empty collection if there are none
See Also:
DeclarationFilter

getMethods

Collection<? extends MethodDeclaration> getMethods()
Returns the methods that are directly declared by this class or interface. Includes annotation type elements. Excludes implicitly declared methods of an interface, such as toString, that correspond to the methods of java.lang.Object.

Returns:
the methods that are directly declared, or an empty collection if there are none
See Also:
DeclarationFilter

getNestedTypes

Collection<TypeDeclaration> getNestedTypes()
Returns the declarations of the nested classes and interfaces that are directly declared by this class or interface.

Returns:
the declarations of the nested classes and interfaces, or an empty collection if there are none
See Also:
DeclarationFilter
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


TypeParameterDeclaration

Mirror API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.declaration
Interface TypeParameterDeclaration

All Superinterfaces:
Declaration
public interface TypeParameterDeclaration
extends Declaration

Represents a formal type parameter of a generic type, method, or constructor declaration. A type parameter declares a TypeVariable.

Since:
1.5

Method Summary
Collection<ReferenceType> | getBounds() Returns the bounds of this type parameter.
Declaration | getOwner() Returns the type, method, or constructor declaration within which this type parameter is declared.
Methods inherited from interface com.sun.mirror.declaration.Declaration
accept, equals, getAnnotation, getAnnotationMirrors, getDocComment, getModifiers, getPosition, getSimpleName

Method Detail

getBounds

Collection<ReferenceType> getBounds()
Returns the bounds of this type parameter. These are the types given by the extends clause. If there is no explicit extends clause, then java.lang.Object is considered to be the sole bound.

Returns:
the bounds of this type parameter

getOwner

Declaration getOwner()
Returns the type, method, or constructor declaration within which this type parameter is declared.

Returns:
the declaration within which this type parameter is declared
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


type

Mirror API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package com.sun.mirror.type

Interfaces used to model types.

See:
Description

Interface Summary
AnnotationType | Represents an annotation type.
ArrayType | Represents an array type.
ClassType | Represents a class type.
DeclaredType | Represents a declared type, either a class type or an interface type.
EnumType | Represents an enum type.
InterfaceType | Represents an interface type.
PrimitiveType | Represents a primitive type.
ReferenceType | Represents a reference type.
TypeMirror | Represents a type in the Java programming language.
TypeVariable | Represents a type variable.
VoidType | A pseudo-type representing the type of void.
WildcardType | Represents a wildcard type argument.

Enum Summary
PrimitiveType.Kind An enumeration of the different kinds of primitive types.

Exception Summary
MirroredTypeException | Thrown when an application attempts to access the Class object corresponding to a TypeMirror.
MirroredTypesException | Thrown when an application attempts to access a sequence of Class objects each corresponding to a TypeMirror.

Package com.sun.mirror.type Description

Interfaces used to model types. A type is represented by the appropriate subinterface of TypeMirror.

Note that the apt tool and its associated APIs may be changed or superseded in future j2se releases.

Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Mirror API
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


com.sun.mirror.type Class Hierarchy

Mirror API
PREV NEXT FRAMES NO FRAMES

Hierarchy For Package com.sun.mirror.type

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.lang.RuntimeException
          • com.sun.mirror.type.MirroredTypeException
          • com.sun.mirror.type.MirroredTypesException

Interface Hierarchy

  • com.sun.mirror.type.TypeMirror
    • com.sun.mirror.type.PrimitiveType
    • com.sun.mirror.type.ReferenceType
      • com.sun.mirror.type.ArrayType
      • com.sun.mirror.type.DeclaredType
        • com.sun.mirror.type.ClassType
          • com.sun.mirror.type.EnumType
        • com.sun.mirror.type.InterfaceType
          • com.sun.mirror.type.AnnotationType
      • com.sun.mirror.type.TypeVariable
    • com.sun.mirror.type.VoidType
    • com.sun.mirror.type.WildcardType

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • com.sun.mirror.type.PrimitiveType.Kind
Overview Package Class Use Tree Deprecated Index Help
Mirror API
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ReferenceType

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.type
Interface ReferenceType

All Superinterfaces:
TypeMirror
All Known Subinterfaces:
AnnotationType, ArrayType, ClassType, DeclaredType, EnumType, InterfaceType, TypeVariable
public interface ReferenceType
extends TypeMirror

Represents a reference type. These include class and interface types, array types, and type variables.

Since:
1.5

Method Summary
Methods inherited from interface com.sun.mirror.type.TypeMirror
accept, equals, toString

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Package com.sun.mirror.type

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Package
com.sun.mirror.type

Packages that use com.sun.mirror.type
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.type | Interfaces used to model types.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Classes in com.sun.mirror.type used by com.sun.mirror.declaration
AnnotationType
Represents an annotation type.
ClassType
Represents a class type.
InterfaceType
Represents an interface type.
ReferenceType
Represents a reference type.
TypeMirror
Represents a type in the Java programming language.

Classes in com.sun.mirror.type used by com.sun.mirror.type
ClassType
Represents a class type.
DeclaredType
Represents a declared type, either a class type or an interface type.
InterfaceType
Represents an interface type.
PrimitiveType.Kind
An enumeration of the different kinds of primitive types.
ReferenceType
Represents a reference type.
TypeMirror
Represents a type in the Java programming language.

Classes in com.sun.mirror.type used by com.sun.mirror.util
AnnotationType
Represents an annotation type.
ArrayType
Represents an array type.
ClassType
Represents a class type.
DeclaredType
Represents a declared type, either a class type or an interface type.
EnumType
Represents an enum type.
InterfaceType
Represents an interface type.
PrimitiveType
Represents a primitive type.
PrimitiveType.Kind
An enumeration of the different kinds of primitive types.
ReferenceType
Represents a reference type.
TypeMirror
Represents a type in the Java programming language.
TypeVariable
Represents a type variable.
VoidType
A pseudo-type representing the type of void.
WildcardType
Represents a wildcard type argument.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


VoidType

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.type
Interface VoidType

All Superinterfaces:
TypeMirror
public interface VoidType
extends TypeMirror

A pseudo-type representing the type of void.

Since:
1.5
See Also:
MethodDeclaration.getReturnType()

Method Summary
Methods inherited from interface com.sun.mirror.type.TypeMirror
accept, equals, toString

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


AnnotationType

Mirror API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.type
Interface AnnotationType

All Superinterfaces:
DeclaredType, InterfaceType, ReferenceType, TypeMirror
public interface AnnotationType
extends InterfaceType

Represents an annotation type.

Since:
1.5

Method Summary
 AnnotationTypeDeclaration getDeclaration()
Returns the declaration of this type.
Methods inherited from interface com.sun.mirror.type.DeclaredType
getActualTypeArguments, getContainingType, getSuperinterfaces
Methods inherited from interface com.sun.mirror.type.TypeMirror
accept, equals, toString

Method Detail

getDeclaration

AnnotationTypeDeclaration getDeclaration()
Returns the declaration of this type.

Returns null if this type's declaration is unknown. This may be the result of a processing error, such as a missing class file.

Specified by:
getDeclaration in interface DeclaredType
Specified by:
getDeclaration in interface InterfaceType
Returns:
the declaration of this type, or null if unknown
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ArrayType

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.type
Interface ArrayType

All Superinterfaces:
ReferenceType, TypeMirror
public interface ArrayType
extends ReferenceType

Represents an array type. A multidimensional array type is represented as an array type whose component type is also an array type.

Since:
1.5

Method Summary
 TypeMirror getComponentType()
Returns the component type of this array type.
Methods inherited from interface com.sun.mirror.type.TypeMirror
accept, equals, toString

Method Detail

getComponentType

TypeMirror getComponentType()
Returns the component type of this array type.

Returns:
the component type of this array type
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.mirror.type.MirroredTypeException

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.mirror.type.MirroredTypeException

No usage of com.sun.mirror.type.MirroredTypeException

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.mirror.type.MirroredTypesException

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.mirror.type.MirroredTypesException

No usage of com.sun.mirror.type.MirroredTypesException

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.mirror.type.PrimitiveType.Kind

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.mirror.type.PrimitiveType.Kind

Packages that use PrimitiveType.Kind
com.sun.mirror.type | Interfaces used to model types.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of PrimitiveType.Kind in com.sun.mirror.type

Methods in com.sun.mirror.type that return PrimitiveType.Kind
PrimitiveType.Kind | PrimitiveType.getKind() Returns the kind of primitive type that this object represents.
static PrimitiveType.Kind | PrimitiveType.Kind.valueOf(String name) Returns the enum constant of this type with the specified name.
static PrimitiveType.Kind[] | PrimitiveType.Kind.values() Returns an array containing the constants of this enum type, in the order they are declared.

Uses of PrimitiveType.Kind in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type PrimitiveType.Kind
 PrimitiveType Types.getPrimitiveType(PrimitiveType.Kind kind)
Returns a primitive type.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.type.AnnotationType

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.type.AnnotationType

Packages that use AnnotationType
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of AnnotationType in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration that return AnnotationType
 AnnotationType AnnotationMirror.getAnnotationType()
Returns the annotation type of this annotation.

Uses of AnnotationType in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type AnnotationType
void | SimpleTypeVisitor.visitAnnotationType(AnnotationType t) Visits an annotation type.
void | TypeVisitor.visitAnnotationType(AnnotationType t) Visits an annotation type.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.type.ArrayType

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.type.ArrayType

Packages that use ArrayType
com.sun.mirror.util Utilities to assist in the processing of declarations and types.

Uses of ArrayType in com.sun.mirror.util

Methods in com.sun.mirror.util that return ArrayType
 ArrayType Types.getArrayType(TypeMirror componentType)
Returns an array type with the specified component type.

Methods in com.sun.mirror.util with parameters of type ArrayType
void | SimpleTypeVisitor.visitArrayType(ArrayType t) Visits an array type.
void | TypeVisitor.visitArrayType(ArrayType t) Visits an array type.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.type.ClassType

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.type.ClassType

Packages that use ClassType
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.type | Interfaces used to model types.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of ClassType in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration that return ClassType
 ClassType ClassDeclaration.getSuperclass()
Returns the class type directly extended by this class.

Uses of ClassType in com.sun.mirror.type

Subinterfaces of ClassType in com.sun.mirror.type
 interface EnumType
Represents an enum type.

Methods in com.sun.mirror.type that return ClassType
 ClassType ClassType.getSuperclass()
Returns the class type that is a direct supertype of this one.

Uses of ClassType in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type ClassType
void | SimpleTypeVisitor.visitClassType(ClassType t) Visits a class type.
void | TypeVisitor.visitClassType(ClassType t) Visits a class type.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.type.DeclaredType

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.type.DeclaredType

Packages that use DeclaredType
com.sun.mirror.type | Interfaces used to model types.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of DeclaredType in com.sun.mirror.type

Subinterfaces of DeclaredType in com.sun.mirror.type
interface | AnnotationType Represents an annotation type.
interface | ClassType Represents a class type.
interface | EnumType Represents an enum type.
interface | InterfaceType Represents an interface type.

Methods in com.sun.mirror.type that return DeclaredType
 DeclaredType DeclaredType.getContainingType()
Returns the type that contains this type as a member.

Uses of DeclaredType in com.sun.mirror.util

Methods in com.sun.mirror.util that return DeclaredType
DeclaredType | Types.getDeclaredType(DeclaredType containing, TypeDeclaration decl, TypeMirror... typeArgs) Returns the type corresponding to a type declaration and actual arguments, given a containing type of which it is a member.
DeclaredType | Types.getDeclaredType(TypeDeclaration decl, TypeMirror... typeArgs) Returns the type corresponding to a type declaration and actual type arguments.

Methods in com.sun.mirror.util with parameters of type DeclaredType
DeclaredType | Types.getDeclaredType(DeclaredType containing, TypeDeclaration decl, TypeMirror... typeArgs) Returns the type corresponding to a type declaration and actual arguments, given a containing type of which it is a member.
void | SimpleTypeVisitor.visitDeclaredType(DeclaredType t) Visits a declared type.
void | TypeVisitor.visitDeclaredType(DeclaredType t) Visits a declared type.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.type.EnumType

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.type.EnumType

Packages that use EnumType
com.sun.mirror.util Utilities to assist in the processing of declarations and types.

Uses of EnumType in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type EnumType
void | SimpleTypeVisitor.visitEnumType(EnumType t) Visits an enum type.
void | TypeVisitor.visitEnumType(EnumType t) Visits an enum type.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.type.InterfaceType

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.type.InterfaceType

Packages that use InterfaceType
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.type | Interfaces used to model types.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of InterfaceType in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration that return types with arguments of type InterfaceType
 Collection<InterfaceType> TypeDeclaration.getSuperinterfaces()
Returns the interface types directly implemented by this class or extended by this interface.

Uses of InterfaceType in com.sun.mirror.type

Subinterfaces of InterfaceType in com.sun.mirror.type
 interface AnnotationType
Represents an annotation type.

Methods in com.sun.mirror.type that return types with arguments of type InterfaceType
 Collection<InterfaceType> DeclaredType.getSuperinterfaces()
Returns the interface types that are direct supertypes of this type.

Uses of InterfaceType in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type InterfaceType
void | SimpleTypeVisitor.visitInterfaceType(InterfaceType t) Visits an interface type.
void | TypeVisitor.visitInterfaceType(InterfaceType t) Visits an interface type.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.type.PrimitiveType

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.type.PrimitiveType

Packages that use PrimitiveType
com.sun.mirror.util Utilities to assist in the processing of declarations and types.

Uses of PrimitiveType in com.sun.mirror.util

Methods in com.sun.mirror.util that return PrimitiveType
 PrimitiveType Types.getPrimitiveType(PrimitiveType.Kind kind)
Returns a primitive type.

Methods in com.sun.mirror.util with parameters of type PrimitiveType
void | SimpleTypeVisitor.visitPrimitiveType(PrimitiveType t) Visits a primitive type.
void | TypeVisitor.visitPrimitiveType(PrimitiveType t) Visits a primitive type.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.type.ReferenceType

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.type.ReferenceType

Packages that use ReferenceType
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.type | Interfaces used to model types.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of ReferenceType in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration that return types with arguments of type ReferenceType
Collection<ReferenceType> | TypeParameterDeclaration.getBounds() Returns the bounds of this type parameter.
Collection<ReferenceType> | ExecutableDeclaration.getThrownTypes() Returns the exceptions and other throwables listed in this method or constructor's throws clause.

Uses of ReferenceType in com.sun.mirror.type

Subinterfaces of ReferenceType in com.sun.mirror.type
interface | AnnotationType Represents an annotation type.
interface | ArrayType Represents an array type.
interface | ClassType Represents a class type.
interface | DeclaredType Represents a declared type, either a class type or an interface type.
interface | EnumType Represents an enum type.
interface | InterfaceType Represents an interface type.
interface | TypeVariable Represents a type variable.

Methods in com.sun.mirror.type that return types with arguments of type ReferenceType
Collection<ReferenceType> | WildcardType.getLowerBounds() Returns the lower bounds of this wildcard.
Collection<ReferenceType> | WildcardType.getUpperBounds() Returns the upper bounds of this wildcard.

Uses of ReferenceType in com.sun.mirror.util

Methods in com.sun.mirror.util with parameters of type ReferenceType
void | SimpleTypeVisitor.visitReferenceType(ReferenceType t) Visits a reference type.
void | TypeVisitor.visitReferenceType(ReferenceType t) Visits a reference type.

Method parameters in com.sun.mirror.util with type arguments of type ReferenceType
WildcardType | Types.getWildcardType(Collection<ReferenceType> upperBounds, Collection<ReferenceType> lowerBounds) Returns a new wildcard.
WildcardType | Types.getWildcardType(Collection<ReferenceType> upperBounds, Collection<ReferenceType> lowerBounds) Returns a new wildcard.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.type.TypeMirror

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.type.TypeMirror

Packages that use TypeMirror
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.type | Interfaces used to model types.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of TypeMirror in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration that return TypeMirror
TypeMirror | MethodDeclaration.getReturnType() Returns the formal return type of this method.
TypeMirror | ParameterDeclaration.getType() Returns the type of this parameter.
TypeMirror | FieldDeclaration.getType() Returns the type of this field.

Uses of TypeMirror in com.sun.mirror.type

Subinterfaces of TypeMirror in com.sun.mirror.type
interface | AnnotationType Represents an annotation type.
interface | ArrayType Represents an array type.
interface | ClassType Represents a class type.
interface | DeclaredType Represents a declared type, either a class type or an interface type.
interface | EnumType Represents an enum type.
interface | InterfaceType Represents an interface type.
interface | PrimitiveType Represents a primitive type.
interface | ReferenceType Represents a reference type.
interface | TypeVariable Represents a type variable.
interface | VoidType A pseudo-type representing the type of void.
interface | WildcardType Represents a wildcard type argument.

Methods in com.sun.mirror.type that return TypeMirror
TypeMirror | ArrayType.getComponentType() Returns the component type of this array type.
TypeMirror | MirroredTypeException.getTypeMirror() Returns the type mirror corresponding to the type being accessed.

Methods in com.sun.mirror.type that return types with arguments of type TypeMirror
Collection<TypeMirror> | DeclaredType.getActualTypeArguments() Returns (in order) the actual type arguments of this type.
Collection<TypeMirror> | MirroredTypesException.getTypeMirrors() Returns the type mirrors corresponding to the types being accessed.

Constructors in com.sun.mirror.type with parameters of type TypeMirror
MirroredTypeException(TypeMirror type)
Constructs a new MirroredTypeException for the specified type.

Constructor parameters in com.sun.mirror.type with type arguments of type TypeMirror
MirroredTypesException(Collection<TypeMirror> types)
Constructs a new MirroredTypesException for the specified types.

Uses of TypeMirror in com.sun.mirror.util

Methods in com.sun.mirror.util that return TypeMirror
 TypeMirror Types.getErasure(TypeMirror t)
Returns the erasure of a type.

Methods in com.sun.mirror.util with parameters of type TypeMirror
ArrayType | Types.getArrayType(TypeMirror componentType) Returns an array type with the specified component type.
DeclaredType | Types.getDeclaredType(DeclaredType containing, TypeDeclaration decl, TypeMirror... typeArgs) Returns the type corresponding to a type declaration and actual arguments, given a containing type of which it is a member.
DeclaredType | Types.getDeclaredType(TypeDeclaration decl, TypeMirror... typeArgs) Returns the type corresponding to a type declaration and actual type arguments.
TypeMirror | Types.getErasure(TypeMirror t) Returns the erasure of a type.
boolean | Types.isAssignable(TypeMirror t1, TypeMirror t2) Tests whether one type is assignable to another.
boolean | Types.isSubtype(TypeMirror t1, TypeMirror t2) Tests whether one type is a subtype of the another.
void | SimpleTypeVisitor.visitTypeMirror(TypeMirror t) Visits a type mirror.
void | TypeVisitor.visitTypeMirror(TypeMirror t) Visits a type mirror.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.type.TypeVariable

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.type.TypeVariable

Packages that use TypeVariable
com.sun.mirror.util Utilities to assist in the processing of declarations and types.

Uses of TypeVariable in com.sun.mirror.util

Methods in com.sun.mirror.util that return TypeVariable
 TypeVariable Types.getTypeVariable(TypeParameterDeclaration tparam)
Returns the type variable declared by a type parameter.

Methods in com.sun.mirror.util with parameters of type TypeVariable
void | SimpleTypeVisitor.visitTypeVariable(TypeVariable t) Visits a type variable.
void | TypeVisitor.visitTypeVariable(TypeVariable t) Visits a type variable.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.type.VoidType

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.type.VoidType

Packages that use VoidType
com.sun.mirror.util Utilities to assist in the processing of declarations and types.

Uses of VoidType in com.sun.mirror.util

Methods in com.sun.mirror.util that return VoidType
 VoidType Types.getVoidType()
Returns the pseudo-type representing the type of void.

Methods in com.sun.mirror.util with parameters of type VoidType
void | SimpleTypeVisitor.visitVoidType(VoidType t) Visits a void type.
void | TypeVisitor.visitVoidType(VoidType t) Visits a void type.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.type.WildcardType

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.type.WildcardType

Packages that use WildcardType
com.sun.mirror.util Utilities to assist in the processing of declarations and types.

Uses of WildcardType in com.sun.mirror.util

Methods in com.sun.mirror.util that return WildcardType
 WildcardType Types.getWildcardType(Collection<ReferenceType> upperBounds, Collection<ReferenceType> lowerBounds)
Returns a new wildcard.

Methods in com.sun.mirror.util with parameters of type WildcardType
void | SimpleTypeVisitor.visitWildcardType(WildcardType t) Visits a wildcard.
void | TypeVisitor.visitWildcardType(WildcardType t) Visits a wildcard.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ClassType

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.type
Interface ClassType

All Superinterfaces:
DeclaredType, ReferenceType, TypeMirror
All Known Subinterfaces:
EnumType
public interface ClassType
extends DeclaredType

Represents a class type. Interface types are represented separately by InterfaceType. Note that an enum is a kind of class.

While a ClassDeclaration represents the declaration of a class, a ClassType represents a class type. See TypeDeclaration for more on this distinction.

Since:
1.5

Method Summary
ClassDeclaration | getDeclaration() Returns the declaration of this type.
ClassType | getSuperclass() Returns the class type that is a direct supertype of this one.
Methods inherited from interface com.sun.mirror.type.DeclaredType
getActualTypeArguments, getContainingType, getSuperinterfaces
Methods inherited from interface com.sun.mirror.type.TypeMirror
accept, equals, toString

Method Detail

getDeclaration

ClassDeclaration getDeclaration()
Returns the declaration of this type.

Returns null if this type's declaration is unknown. This may be the result of a processing error, such as a missing class file.

Specified by:
getDeclaration in interface DeclaredType
Returns:
the declaration of this type, or null if unknown

getSuperclass

ClassType getSuperclass()
Returns the class type that is a direct supertype of this one. This is the superclass of this type's declaring class, with any type arguments substituted in. The only class with no superclass is java.lang.Object, for which this method returns null.

For example, the class type extended by java.util.TreeSet<String> is java.util.AbstractSet<String>.

Returns:
the class type that is a direct supertype of this one, or null if there is none
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


DeclaredType

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.type
Interface DeclaredType

All Superinterfaces:
ReferenceType, TypeMirror
All Known Subinterfaces:
AnnotationType, ClassType, EnumType, InterfaceType
public interface DeclaredType
extends ReferenceType

Represents a declared type, either a class type or an interface type. This includes parameterized types such as java.util.Set<String> as well as raw types.

While a TypeDeclaration represents the declaration of a class or interface, a DeclaredType represents a class or interface type, the latter being a use of the former. See TypeDeclaration for more on this distinction.

A DeclaredType may represent a type for which details (declaration, supertypes, etc.) are unknown. This may be the result of a processing error, such as a missing class file, and is indicated by getDeclaration() returning null. Other method invocations on such an unknown type will not, in general, return meaningful results.

Since:
1.5

Method Summary
Collection<TypeMirror> | getActualTypeArguments() Returns (in order) the actual type arguments of this type.
DeclaredType | getContainingType() Returns the type that contains this type as a member.
TypeDeclaration | getDeclaration() Returns the declaration of this type.
Collection<InterfaceType> | getSuperinterfaces() Returns the interface types that are direct supertypes of this type.
Methods inherited from interface com.sun.mirror.type.TypeMirror
accept, equals, toString

Method Detail

getDeclaration

TypeDeclaration getDeclaration()
Returns the declaration of this type.

Returns null if this type's declaration is unknown. This may be the result of a processing error, such as a missing class file.

Returns:
the declaration of this type, or null if unknown

getContainingType

DeclaredType getContainingType()
Returns the type that contains this type as a member. Returns null if this is a top-level type.

For example, the containing type of O.I<S> is the type O, and the containing type of O<T>.I<S> is the type O<T>.

Returns:
the type that contains this type, or null if this is a top-level type

getActualTypeArguments

Collection<TypeMirror> getActualTypeArguments()
Returns (in order) the actual type arguments of this type. For a generic type nested within another generic type (such as Outer<String>.Inner<Number>), only the type arguments of the innermost type are included.

Returns:
the actual type arguments of this type, or an empty collection if there are none

getSuperinterfaces

Collection<InterfaceType> getSuperinterfaces()
Returns the interface types that are direct supertypes of this type. These are the interface types implemented or extended by this type's declaration, with any type arguments substituted in.

For example, the interface type extended by java.util.Set<String> is java.util.Collection<String>.

Returns:
the interface types that are direct supertypes of this type, or an empty collection if there are none
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


EnumType

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.type
Interface EnumType

All Superinterfaces:
ClassType, DeclaredType, ReferenceType, TypeMirror
public interface EnumType
extends ClassType

Represents an enum type.

Since:
1.5

Method Summary
 EnumDeclaration getDeclaration()
Returns the declaration of this type.
Methods inherited from interface com.sun.mirror.type.ClassType
getSuperclass
Methods inherited from interface com.sun.mirror.type.DeclaredType
getActualTypeArguments, getContainingType, getSuperinterfaces
Methods inherited from interface com.sun.mirror.type.TypeMirror
accept, equals, toString

Method Detail

getDeclaration

EnumDeclaration getDeclaration()
Returns the declaration of this type.

Returns null if this type's declaration is unknown. This may be the result of a processing error, such as a missing class file.

Specified by:
getDeclaration in interface ClassType
Specified by:
getDeclaration in interface DeclaredType
Returns:
the declaration of this type, or null if unknown
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


InterfaceType

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.type
Interface InterfaceType

All Superinterfaces:
DeclaredType, ReferenceType, TypeMirror
All Known Subinterfaces:
AnnotationType
public interface InterfaceType
extends DeclaredType

Represents an interface type. Note that an annotation type is a kind of interface.

While an InterfaceDeclaration represents the declaration of an interface, an InterfaceType represents an interface type. See TypeDeclaration for more on this distinction.

Since:
1.5

Method Summary
 InterfaceDeclaration getDeclaration()
Returns the declaration of this type.
Methods inherited from interface com.sun.mirror.type.DeclaredType
getActualTypeArguments, getContainingType, getSuperinterfaces
Methods inherited from interface com.sun.mirror.type.TypeMirror
accept, equals, toString

Method Detail

getDeclaration

InterfaceDeclaration getDeclaration()
Returns the declaration of this type.

Returns null if this type's declaration is unknown. This may be the result of a processing error, such as a missing class file.

Specified by:
getDeclaration in interface DeclaredType
Returns:
the declaration of this type, or null if unknown
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


MirroredTypeException

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.type
Class MirroredTypeException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  com.sun.mirror.type.MirroredTypeException
All Implemented Interfaces:
Serializable
public class MirroredTypeException
extends RuntimeException

Thrown when an application attempts to access the Class object corresponding to a TypeMirror.

See Also:
MirroredTypesException, Declaration.getAnnotation(Class), Serialized Form

Constructor Summary
MirroredTypeException(TypeMirror type)
Constructs a new MirroredTypeException for the specified type.
Method Summary
String | getQualifiedName() Returns the fully qualified name of the type being accessed.
TypeMirror | getTypeMirror() Returns the type mirror corresponding to the type being accessed.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MirroredTypeException

public MirroredTypeException(TypeMirror type)
Constructs a new MirroredTypeException for the specified type.

Parameters:
type - the type being accessed
Method Detail

getTypeMirror

public TypeMirror getTypeMirror()
Returns the type mirror corresponding to the type being accessed. The type mirror may be unavailable if this exception has been serialized and then read back in.

Returns:
the type mirror, or null if unavailable

getQualifiedName

public String getQualifiedName()
Returns the fully qualified name of the type being accessed. More precisely, returns the canonical name of a class, interface, array, or primitive, and returns "void" for the pseudo-type representing the type of void.

Returns:
the fully qualified name of the type being accessed
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


MirroredTypesException

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.type
Class MirroredTypesException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  com.sun.mirror.type.MirroredTypesException
All Implemented Interfaces:
Serializable
public class MirroredTypesException
extends RuntimeException

Thrown when an application attempts to access a sequence of Class objects each corresponding to a TypeMirror.

See Also:
MirroredTypeException, Declaration.getAnnotation(Class), Serialized Form

Constructor Summary
MirroredTypesException(Collection<TypeMirror> types)
Constructs a new MirroredTypesException for the specified types.
Method Summary
Collection<String> | getQualifiedNames() Returns the fully qualified names of the types being accessed.
Collection<TypeMirror> | getTypeMirrors() Returns the type mirrors corresponding to the types being accessed.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MirroredTypesException

public MirroredTypesException(Collection<TypeMirror> types)
Constructs a new MirroredTypesException for the specified types.

Parameters:
types - an ordered collection of the types being accessed
Method Detail

getTypeMirrors

public Collection<TypeMirror> getTypeMirrors()
Returns the type mirrors corresponding to the types being accessed. The type mirrors may be unavailable if this exception has been serialized and then read back in.

Returns:
the type mirrors in order, or null if unavailable

getQualifiedNames

public Collection<String> getQualifiedNames()
Returns the fully qualified names of the types being accessed. More precisely, returns the canonical names of each class, interface, array, or primitive, and "void" for the pseudo-type representing the type of void.

Returns:
the fully qualified names, in order, of the types being accessed
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


PrimitiveType

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.type
Interface PrimitiveType

All Superinterfaces:
TypeMirror
public interface PrimitiveType
extends TypeMirror

Represents a primitive type. These include boolean, byte, short, int, long, char, float, and double.

Since:
1.5

Nested Class Summary
static class PrimitiveType.Kind
An enumeration of the different kinds of primitive types.
Method Summary
 PrimitiveType.Kind getKind()
Returns the kind of primitive type that this object represents.
Methods inherited from interface com.sun.mirror.type.TypeMirror
accept, equals, toString

Method Detail

getKind

PrimitiveType.Kind getKind()
Returns the kind of primitive type that this object represents.

Returns:
the kind of primitive type that this object represents
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


PrimitiveType.Kind

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

com.sun.mirror.type
Enum PrimitiveType.Kind

java.lang.Object
    extended by  java.lang.Enum<PrimitiveType.Kind>
        extended by  com.sun.mirror.type.PrimitiveType.Kind
All Implemented Interfaces:
Serializable, Comparable<PrimitiveType.Kind>
Enclosing interface:
PrimitiveType
public static enum PrimitiveType.Kind
extends Enum<PrimitiveType.Kind>

An enumeration of the different kinds of primitive types.

Enum Constant Summary
BOOLEAN
The primitive type boolean
BYTE
The primitive type byte
CHAR
The primitive type char
DOUBLE
The primitive type double
FLOAT
The primitive type float
INT
The primitive type int
LONG
The primitive type long
SHORT
The primitive type short
Method Summary
static PrimitiveType.Kind | valueOf(String name) Returns the enum constant of this type with the specified name.
static PrimitiveType.Kind[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

BOOLEAN

public static final PrimitiveType.Kind BOOLEAN
The primitive type boolean

BYTE

public static final PrimitiveType.Kind BYTE
The primitive type byte

SHORT

public static final PrimitiveType.Kind SHORT
The primitive type short

INT

public static final PrimitiveType.Kind INT
The primitive type int

LONG

public static final PrimitiveType.Kind LONG
The primitive type long

CHAR

public static final PrimitiveType.Kind CHAR
The primitive type char

FLOAT

public static final PrimitiveType.Kind FLOAT
The primitive type float

DOUBLE

public static final PrimitiveType.Kind DOUBLE
The primitive type double

Method Detail

values

public static PrimitiveType.Kind[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (PrimitiveType.Kind c : PrimitiveType.Kind.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static PrimitiveType.Kind valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


TypeMirror

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.type
Interface TypeMirror

All Known Subinterfaces:
AnnotationType, ArrayType, ClassType, DeclaredType, EnumType, InterfaceType, PrimitiveType, ReferenceType, TypeVariable, VoidType, WildcardType
public interface TypeMirror

Represents a type in the Java programming language. Types include primitive types, class and interface types, array types, and type variables. Wildcard type arguments, and the pseudo-type representing the type of void, are represented by type mirrors as well.

Types may be compared using the utility methods in Types. There is no guarantee that any particular type will always be represented by the same object.

Since:
1.5
See Also:
Declaration, Types

Method Summary
void | accept(TypeVisitor v) Applies a visitor to this type.
boolean | equals(Object obj) Tests whether two types represent the same type.
String | toString() Returns a string representation of this type.

Method Detail

toString

String toString()
Returns a string representation of this type. Any names embedded in the expression are qualified.

Overrides:
toString in class Object
Returns:
a string representation of this type

equals

boolean equals(Object obj)
Tests whether two types represent the same type.

Overrides:
equals in class Object
Parameters:
obj - the object to be compared with this type
Returns:
true if the specified object represents the same type as this.

accept

void accept(TypeVisitor v)
Applies a visitor to this type.

Parameters:
v - the visitor operating on this type
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


TypeVariable

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.type
Interface TypeVariable

All Superinterfaces:
ReferenceType, TypeMirror
public interface TypeVariable
extends ReferenceType

Represents a type variable. A type variable is declared by a type parameter of a type, method, or constructor.

Since:
1.5

Method Summary
 TypeParameterDeclaration getDeclaration()
Returns the type parameter that declared this type variable.
Methods inherited from interface com.sun.mirror.type.TypeMirror
accept, equals, toString

Method Detail

getDeclaration

TypeParameterDeclaration getDeclaration()
Returns the type parameter that declared this type variable.

Returns:
the type parameter that declared this type variable
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


WildcardType

Mirror API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.type
Interface WildcardType

All Superinterfaces:
TypeMirror
public interface WildcardType
extends TypeMirror

Represents a wildcard type argument. Examples include:

   ?
   ? extends Number
   ? super T

A wildcard may have its upper bound explicitly set by an extends clause, its lower bound explicitly set by a super clause, or neither (but not both).

Since:
1.5

Method Summary
Collection<ReferenceType> | getLowerBounds() Returns the lower bounds of this wildcard.
Collection<ReferenceType> | getUpperBounds() Returns the upper bounds of this wildcard.
Methods inherited from interface com.sun.mirror.type.TypeMirror
accept, equals, toString

Method Detail

getUpperBounds

Collection<ReferenceType> getUpperBounds()
Returns the upper bounds of this wildcard. If no upper bound is explicitly declared, then an empty collection is returned.

Returns:
the upper bounds of this wildcard

getLowerBounds

Collection<ReferenceType> getLowerBounds()
Returns the lower bounds of this wildcard. If no lower bound is explicitly declared, then an empty collection is returned.

Returns:
the lower bounds of this wildcard
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


util

Mirror API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package com.sun.mirror.util

Utilities to assist in the processing of declarations and types.

See:
Description

Interface Summary
Declarations | Utility methods for operating on declarations.
DeclarationVisitor | A visitor for declarations, in the style of the standard visitor design pattern.
SourcePosition | Represents a position in a source file.
Types | Utility methods for operating on types.
TypeVisitor | A visitor for types, in the style of the standard visitor design pattern.

Class Summary
DeclarationFilter | A filter for selecting just the items of interest from a collection of declarations.
DeclarationVisitors | Utilities to create specialized DeclarationVisitor instances.
SimpleDeclarationVisitor | A simple visitor for declarations.
SimpleTypeVisitor | A simple visitor for types.

Package com.sun.mirror.util Description

Utilities to assist in the processing of declarations and types.

Note that the apt tool and its associated APIs may be changed or superseded in future j2se releases.

Since:
1.5
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


com.sun.mirror.util Class Hierarchy

Mirror API
PREV NEXT FRAMES NO FRAMES

Hierarchy For Package com.sun.mirror.util

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • com.sun.mirror.util.DeclarationFilter
    • com.sun.mirror.util.DeclarationVisitors
    • com.sun.mirror.util.SimpleDeclarationVisitor (implements com.sun.mirror.util.DeclarationVisitor)
    • com.sun.mirror.util.SimpleTypeVisitor (implements com.sun.mirror.util.TypeVisitor)

Interface Hierarchy

  • com.sun.mirror.util.Declarations
  • com.sun.mirror.util.DeclarationVisitor
  • com.sun.mirror.util.SourcePosition
  • com.sun.mirror.util.Types
  • com.sun.mirror.util.TypeVisitor
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Package com.sun.mirror.util

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Package
com.sun.mirror.util

Packages that use com.sun.mirror.util
com.sun.mirror.apt | Classes used to communicate information between annotation processors and an annotation processing tool.
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.type | Interfaces used to model types.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Classes in com.sun.mirror.util used by com.sun.mirror.apt
Declarations
Utility methods for operating on declarations.
SourcePosition
Represents a position in a source file.
Types
Utility methods for operating on types.

Classes in com.sun.mirror.util used by com.sun.mirror.declaration
DeclarationVisitor
A visitor for declarations, in the style of the standard visitor design pattern.
SourcePosition
Represents a position in a source file.

Classes in com.sun.mirror.util used by com.sun.mirror.type
TypeVisitor
A visitor for types, in the style of the standard visitor design pattern.

Classes in com.sun.mirror.util used by com.sun.mirror.util
DeclarationFilter
A filter for selecting just the items of interest from a collection of declarations.
DeclarationVisitor
A visitor for declarations, in the style of the standard visitor design pattern.
TypeVisitor
A visitor for types, in the style of the standard visitor design pattern.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.mirror.util.DeclarationFilter

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.mirror.util.DeclarationFilter

Packages that use DeclarationFilter
com.sun.mirror.util Utilities to assist in the processing of declarations and types.

Uses of DeclarationFilter in com.sun.mirror.util

Fields in com.sun.mirror.util declared as DeclarationFilter
static DeclarationFilter | DeclarationFilter.FILTER_PACKAGE A filter that selects only package-private (default) declarations.
static DeclarationFilter | DeclarationFilter.FILTER_PRIVATE A filter that selects only private declarations.
static DeclarationFilter | DeclarationFilter.FILTER_PROTECTED A filter that selects only protected declarations.
static DeclarationFilter | DeclarationFilter.FILTER_PUBLIC A filter that selects only public declarations.
static DeclarationFilter | DeclarationFilter.FILTER_PUBLIC_OR_PROTECTED A filter that selects only public or protected declarations.

Methods in com.sun.mirror.util that return DeclarationFilter
DeclarationFilter | DeclarationFilter.and(DeclarationFilter f) Returns a filter that selects those declarations selected by both this filter and another.
static DeclarationFilter | DeclarationFilter.getFilter(Class<? extends Declaration> kind) Returns a filter that selects declarations of a particular kind.
static DeclarationFilter | DeclarationFilter.getFilter(Collection<Modifier> mods) Returns a filter that selects declarations containing all of a collection of modifiers.
DeclarationFilter | DeclarationFilter.not() Returns a filter that selects those declarations not selected by this filter.
DeclarationFilter | DeclarationFilter.or(DeclarationFilter f) Returns a filter that selects those declarations selected by either this filter or another.

Methods in com.sun.mirror.util with parameters of type DeclarationFilter
DeclarationFilter | DeclarationFilter.and(DeclarationFilter f) Returns a filter that selects those declarations selected by both this filter and another.
DeclarationFilter | DeclarationFilter.or(DeclarationFilter f) Returns a filter that selects those declarations selected by either this filter or another.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.mirror.util.DeclarationVisitors

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.mirror.util.DeclarationVisitors

No usage of com.sun.mirror.util.DeclarationVisitors

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.mirror.util.SimpleDeclarationVisitor

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.mirror.util.SimpleDeclarationVisitor

No usage of com.sun.mirror.util.SimpleDeclarationVisitor

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.mirror.util.SimpleTypeVisitor

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.mirror.util.SimpleTypeVisitor

No usage of com.sun.mirror.util.SimpleTypeVisitor

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.util.Declarations

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.util.Declarations

Packages that use Declarations
com.sun.mirror.apt Classes used to communicate information between annotation processors and an annotation processing tool.

Uses of Declarations in com.sun.mirror.apt

Methods in com.sun.mirror.apt that return Declarations
 Declarations AnnotationProcessorEnvironment.getDeclarationUtils()
Returns an implementation of some utility methods for operating on declarations.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.util.DeclarationVisitor

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.util.DeclarationVisitor

Packages that use DeclarationVisitor
com.sun.mirror.declaration | Interfaces used to model program element declarations.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of DeclarationVisitor in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration with parameters of type DeclarationVisitor
 void Declaration.accept(DeclarationVisitor v)
Applies a visitor to this declaration.

Uses of DeclarationVisitor in com.sun.mirror.util

Classes in com.sun.mirror.util that implement DeclarationVisitor
 class SimpleDeclarationVisitor
A simple visitor for declarations.

Fields in com.sun.mirror.util declared as DeclarationVisitor
static DeclarationVisitor DeclarationVisitors.NO_OP
A visitor that has no side effects and keeps no state.

Methods in com.sun.mirror.util that return DeclarationVisitor
static DeclarationVisitor | DeclarationVisitors.getDeclarationScanner(DeclarationVisitor pre, DeclarationVisitor post) Return a DeclarationVisitor that will scan the declaration structure, visiting declarations contained in another declaration.
static DeclarationVisitor | DeclarationVisitors.getSourceOrderDeclarationScanner(DeclarationVisitor pre, DeclarationVisitor post) Return a DeclarationVisitor that will scan the declaration structure, visiting declarations contained in another declaration in source code order.

Methods in com.sun.mirror.util with parameters of type DeclarationVisitor
static DeclarationVisitor | DeclarationVisitors.getDeclarationScanner(DeclarationVisitor pre, DeclarationVisitor post) Return a DeclarationVisitor that will scan the declaration structure, visiting declarations contained in another declaration.
static DeclarationVisitor | DeclarationVisitors.getSourceOrderDeclarationScanner(DeclarationVisitor pre, DeclarationVisitor post) Return a DeclarationVisitor that will scan the declaration structure, visiting declarations contained in another declaration in source code order.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.util.SourcePosition

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.util.SourcePosition

Packages that use SourcePosition
com.sun.mirror.apt | Classes used to communicate information between annotation processors and an annotation processing tool.
com.sun.mirror.declaration | Interfaces used to model program element declarations.

Uses of SourcePosition in com.sun.mirror.apt

Methods in com.sun.mirror.apt with parameters of type SourcePosition
void | Messager.printError(SourcePosition pos, String msg) Prints an error message.
void | Messager.printNotice(SourcePosition pos, String msg) Prints a notice.
void | Messager.printWarning(SourcePosition pos, String msg) Prints a warning message.

Uses of SourcePosition in com.sun.mirror.declaration

Methods in com.sun.mirror.declaration that return SourcePosition
SourcePosition | AnnotationValue.getPosition() Returns the source position of the beginning of this annotation value.
SourcePosition | AnnotationMirror.getPosition() Returns the source position of the beginning of this annotation.
SourcePosition | Declaration.getPosition() Returns the source position of the beginning of this declaration.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.util.Types

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.util.Types

Packages that use Types
com.sun.mirror.apt Classes used to communicate information between annotation processors and an annotation processing tool.

Uses of Types in com.sun.mirror.apt

Methods in com.sun.mirror.apt that return Types
 Types AnnotationProcessorEnvironment.getTypeUtils()
Returns an implementation of some utility methods for operating on types.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.mirror.util.TypeVisitor

Mirror API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.mirror.util.TypeVisitor

Packages that use TypeVisitor
com.sun.mirror.type | Interfaces used to model types.
com.sun.mirror.util | Utilities to assist in the processing of declarations and types.

Uses of TypeVisitor in com.sun.mirror.type

Methods in com.sun.mirror.type with parameters of type TypeVisitor
 void TypeMirror.accept(TypeVisitor v)
Applies a visitor to this type.

Uses of TypeVisitor in com.sun.mirror.util

Classes in com.sun.mirror.util that implement TypeVisitor
 class SimpleTypeVisitor
A simple visitor for types.

Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


DeclarationFilter

Mirror API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.util
Class DeclarationFilter

java.lang.Object
    extended by  com.sun.mirror.util.DeclarationFilter

public class DeclarationFilter
extends Object

A filter for selecting just the items of interest from a collection of declarations. The filter is said to select or to match those declarations. Filters can be created in several ways: by the static methods described below, by negating or composing existing filters, or by subclasses that implement arbitrary matching rules.

A subclass can create an arbitrary filter simply by implementing the matches(Declaration) method.

Examples.

Selecting the public declarations from a collection:

     result = FILTER_PUBLIC.filter(decls);
Selecting class declarations (including enums):
     classFilter = DeclarationFilter.getFilter(ClassDeclaration.class);
     result = classFilter.filter(decls);
Selecting class declarations but excluding enums:
     enumFilter = DeclarationFilter.getFilter(EnumDeclaration.class);
     compoundFilter = classFilter.and(enumFilter.not());
     result = compoundFilter.filter(decls);
Selecting declarations named "Bob":
     nameFilter = new DeclarationFilter() {
                      public boolean matches(Declaration d) {
                          return d.getSimpleName().equals("Bob");
                      }
                  };
     result = nameFilter.filter(decls);

Since:
1.5

Field Summary
static DeclarationFilter | FILTER_PACKAGE A filter that selects only package-private (default) declarations.
static DeclarationFilter | FILTER_PRIVATE A filter that selects only private declarations.
static DeclarationFilter | FILTER_PROTECTED A filter that selects only protected declarations.
static DeclarationFilter | FILTER_PUBLIC A filter that selects only public declarations.
static DeclarationFilter | FILTER_PUBLIC_OR_PROTECTED A filter that selects only public or protected declarations.
Constructor Summary
DeclarationFilter()
Constructs an identity filter: one that selects all declarations.
Method Summary
 DeclarationFilter and(DeclarationFilter f)
Returns a filter that selects those declarations selected by both this filter and another.
<D extends Declaration>
Collection<D>
filter(Collection<? extends Declaration> decls, Class<D> resType)
Returns the declarations matched by this filter, with the result being restricted to declarations of a given kind.
<D extends Declaration>
Collection<D>
filter(Collection<D> decls)
Returns the declarations matched by this filter.
static DeclarationFilter getFilter(Class<? extends Declaration> kind)
Returns a filter that selects declarations of a particular kind.
static DeclarationFilter getFilter(Collection<Modifier> mods)
Returns a filter that selects declarations containing all of a collection of modifiers.
 boolean matches(Declaration decl)
Tests whether this filter matches a given declaration.
 DeclarationFilter not()
Returns a filter that selects those declarations not selected by this filter.
 DeclarationFilter or(DeclarationFilter f)
Returns a filter that selects those declarations selected by either this filter or another.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FILTER_PUBLIC

public static final DeclarationFilter FILTER_PUBLIC
A filter that selects only public declarations.

FILTER_PROTECTED

public static final DeclarationFilter FILTER_PROTECTED
A filter that selects only protected declarations.

FILTER_PUBLIC_OR_PROTECTED

public static final DeclarationFilter FILTER_PUBLIC_OR_PROTECTED
A filter that selects only public or protected declarations.

FILTER_PACKAGE

public static final DeclarationFilter FILTER_PACKAGE
A filter that selects only package-private (default) declarations.

FILTER_PRIVATE

public static final DeclarationFilter FILTER_PRIVATE
A filter that selects only private declarations.

Constructor Detail

DeclarationFilter

public DeclarationFilter()
Constructs an identity filter: one that selects all declarations.

Method Detail

getFilter

public static DeclarationFilter getFilter(Collection<Modifier> mods)
Returns a filter that selects declarations containing all of a collection of modifiers.

Parameters:
mods - the modifiers to match (non-null)
Returns:
a filter that matches declarations containing mods

getFilter

public static DeclarationFilter getFilter(Class<? extends Declaration> kind)
Returns a filter that selects declarations of a particular kind. For example, there may be a filter that selects only class declarations, or only fields. The filter will select declarations of the specified kind, and also any subtypes of that kind; for example, a field filter will also select enum constants.

Parameters:
kind - the kind of declarations to select
Returns:
a filter that selects declarations of a particular kind

and

public DeclarationFilter and(DeclarationFilter f)
Returns a filter that selects those declarations selected by both this filter and another.

Parameters:
f - filter to be composed with this one
Returns:
a filter that selects those declarations selected by both this filter and another

or

public DeclarationFilter or(DeclarationFilter f)
Returns a filter that selects those declarations selected by either this filter or another.

Parameters:
f - filter to be composed with this one
Returns:
a filter that selects those declarations selected by either this filter or another

not

public DeclarationFilter not()
Returns a filter that selects those declarations not selected by this filter.

Returns:
a filter that selects those declarations not selected by this filter

matches

public boolean matches(Declaration decl)
Tests whether this filter matches a given declaration. The default implementation always returns true; subclasses should override this.

Parameters:
decl - the declaration to match
Returns:
true if this filter matches the given declaration

filter

public <D extends Declaration> Collection<D> filter(Collection<D> decls)
Returns the declarations matched by this filter. The result is a collection of the same type as the argument; the two-parameter version of filter offers control over the result type.

Type Parameters:
D - type of the declarations being filtered
Parameters:
decls - declarations being filtered
Returns:
the declarations matched by this filter

filter

public <D extends Declaration> Collection<D> filter(Collection<? extends Declaration> decls,
                                                    Class<D> resType)
Returns the declarations matched by this filter, with the result being restricted to declarations of a given kind. Similar to the simpler single-parameter version of filter, but the result type is specified explicitly.

Type Parameters:
D - type of the declarations being returned
Parameters:
decls - declarations being filtered
resType - type of the declarations being returned -- the reflective view of D
Returns:
the declarations matched by this filter, restricted to those of the specified type
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Declarations

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.util
Interface Declarations

public interface Declarations

Utility methods for operating on declarations.

Since:
1.5

Method Summary
boolean | hides(MemberDeclaration sub, MemberDeclaration sup) Tests whether one type, method, or field declaration hides another.
boolean | overrides(MethodDeclaration sub, MethodDeclaration sup) Tests whether one method overrides another.

Method Detail

hides

boolean hides(MemberDeclaration sub,
              MemberDeclaration sup)
Tests whether one type, method, or field declaration hides another.

Parameters:
sub - the first member
sup - the second member
Returns:
true if and only if the first member hides the second

overrides

boolean overrides(MethodDeclaration sub,
                  MethodDeclaration sup)
Tests whether one method overrides another. When a non-abstract method overrides an abstract one, the former is also said to implement the latter.

Parameters:
sub - the first method
sup - the second method
Returns:
true if and only if the first method overrides the second
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


DeclarationVisitor

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.util
Interface DeclarationVisitor

All Known Implementing Classes:
SimpleDeclarationVisitor
public interface DeclarationVisitor

A visitor for declarations, in the style of the standard visitor design pattern. Classes implementing this interface are used to operate on a declaration when the kind of declaration is unknown at compile time. When a visitor is passed to a declaration's accept method, the most specific visitXxx method applicable to that declaration is invoked.

Since:
1.5

Method Summary
void | visitAnnotationTypeDeclaration(AnnotationTypeDeclaration d) Visits an annotation type declaration.
void | visitAnnotationTypeElementDeclaration(AnnotationTypeElementDeclaration d) Visits an annotation type element declaration.
void | visitClassDeclaration(ClassDeclaration d) Visits a class declaration.
void | visitConstructorDeclaration(ConstructorDeclaration d) Visits a constructor declaration.
void | visitDeclaration(Declaration d) Visits a declaration.
void | visitEnumConstantDeclaration(EnumConstantDeclaration d) Visits an enum constant declaration.
void | visitEnumDeclaration(EnumDeclaration d) Visits an enum declaration.
void | visitExecutableDeclaration(ExecutableDeclaration d) Visits a method or constructor declaration.
void | visitFieldDeclaration(FieldDeclaration d) Visits a field declaration.
void | visitInterfaceDeclaration(InterfaceDeclaration d) Visits an interface declaration.
void | visitMemberDeclaration(MemberDeclaration d) Visits a member or constructor declaration.
void | visitMethodDeclaration(MethodDeclaration d) Visits a method declaration.
void | visitPackageDeclaration(PackageDeclaration d) Visits a package declaration.
void | visitParameterDeclaration(ParameterDeclaration d) Visits a parameter declaration.
void | visitTypeDeclaration(TypeDeclaration d) Visits a type declaration.
void | visitTypeParameterDeclaration(TypeParameterDeclaration d) Visits a type parameter declaration.

Method Detail

visitDeclaration

void visitDeclaration(Declaration d)
Visits a declaration.

Parameters:
d - the declaration to visit

visitPackageDeclaration

void visitPackageDeclaration(PackageDeclaration d)
Visits a package declaration.

Parameters:
d - the declaration to visit

visitMemberDeclaration

void visitMemberDeclaration(MemberDeclaration d)
Visits a member or constructor declaration.

Parameters:
d - the declaration to visit

visitTypeDeclaration

void visitTypeDeclaration(TypeDeclaration d)
Visits a type declaration.

Parameters:
d - the declaration to visit

visitClassDeclaration

void visitClassDeclaration(ClassDeclaration d)
Visits a class declaration.

Parameters:
d - the declaration to visit

visitEnumDeclaration

void visitEnumDeclaration(EnumDeclaration d)
Visits an enum declaration.

Parameters:
d - the declaration to visit

visitInterfaceDeclaration

void visitInterfaceDeclaration(InterfaceDeclaration d)
Visits an interface declaration.

Parameters:
d - the declaration to visit

visitAnnotationTypeDeclaration

void visitAnnotationTypeDeclaration(AnnotationTypeDeclaration d)
Visits an annotation type declaration.

Parameters:
d - the declaration to visit

visitFieldDeclaration

void visitFieldDeclaration(FieldDeclaration d)
Visits a field declaration.

Parameters:
d - the declaration to visit

visitEnumConstantDeclaration

void visitEnumConstantDeclaration(EnumConstantDeclaration d)
Visits an enum constant declaration.

Parameters:
d - the declaration to visit

visitExecutableDeclaration

void visitExecutableDeclaration(ExecutableDeclaration d)
Visits a method or constructor declaration.

Parameters:
d - the declaration to visit

visitConstructorDeclaration

void visitConstructorDeclaration(ConstructorDeclaration d)
Visits a constructor declaration.

Parameters:
d - the declaration to visit

visitMethodDeclaration

void visitMethodDeclaration(MethodDeclaration d)
Visits a method declaration.

Parameters:
d - the declaration to visit

visitAnnotationTypeElementDeclaration

void visitAnnotationTypeElementDeclaration(AnnotationTypeElementDeclaration d)
Visits an annotation type element declaration.

Parameters:
d - the declaration to visit

visitParameterDeclaration

void visitParameterDeclaration(ParameterDeclaration d)
Visits a parameter declaration.

Parameters:
d - the declaration to visit

visitTypeParameterDeclaration

void visitTypeParameterDeclaration(TypeParameterDeclaration d)
Visits a type parameter declaration.

Parameters:
d - the declaration to visit
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


DeclarationVisitors

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.util
Class DeclarationVisitors

java.lang.Object
    extended by  com.sun.mirror.util.DeclarationVisitors

public class DeclarationVisitors
extends Object

Utilities to create specialized DeclarationVisitor instances.

Since:
1.5

Field Summary
static DeclarationVisitor NO_OP
A visitor that has no side effects and keeps no state.
Method Summary
static DeclarationVisitor | getDeclarationScanner(DeclarationVisitor pre, DeclarationVisitor post) Return a DeclarationVisitor that will scan the declaration structure, visiting declarations contained in another declaration.
static DeclarationVisitor | getSourceOrderDeclarationScanner(DeclarationVisitor pre, DeclarationVisitor post) Return a DeclarationVisitor that will scan the declaration structure, visiting declarations contained in another declaration in source code order.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_OP

public static final DeclarationVisitor NO_OP
A visitor that has no side effects and keeps no state.

Method Detail

getDeclarationScanner

public static DeclarationVisitor getDeclarationScanner(DeclarationVisitor pre,
                                                       DeclarationVisitor post)
Return a DeclarationVisitor that will scan the declaration structure, visiting declarations contained in another declaration. For example, when visiting a class, the fields, methods, constructors, etc. of the class are also visited. The order in which the contained declarations are scanned is not specified.

The pre and post DeclarationVisitor parameters specify, respectively, the processing the scanner will do before or after visiting the contained declarations. If only one of pre and post processing is needed, use DeclarationVisitors.NO_OP for the other parameter.

Parameters:
pre - visitor representing processing to do before visiting contained declarations.
post - visitor representing processing to do after visiting contained declarations.

getSourceOrderDeclarationScanner

public static DeclarationVisitor getSourceOrderDeclarationScanner(DeclarationVisitor pre,
                                                                  DeclarationVisitor post)
Return a DeclarationVisitor that will scan the declaration structure, visiting declarations contained in another declaration in source code order. For example, when visiting a class, the fields, methods, constructors, etc. of the class are also visited. The order in which the contained declarations are visited is as close to source code order as possible; declaration mirrors created from class files instead of source code will not have source position information.

The pre and post DeclarationVisitor parameters specify, respectively, the processing the scanner will do before or after visiting the contained declarations. If only one of pre and post processing is needed, use DeclarationVisitors.NO_OP for the other parameter.

Parameters:
pre - visitor representing processing to do before visiting contained declarations.
post - visitor representing processing to do after visiting contained declarations.
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


SimpleDeclarationVisitor

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.util
Class SimpleDeclarationVisitor

java.lang.Object
    extended by  com.sun.mirror.util.SimpleDeclarationVisitor
All Implemented Interfaces:
DeclarationVisitor
public class SimpleDeclarationVisitor
extends Object
implements DeclarationVisitor

A simple visitor for declarations.

The implementations of the methods of this class do nothing but delegate up the declaration hierarchy. A subclass should override the methods that correspond to the kinds of declarations on which it will operate.

Since:
1.5

Constructor Summary
SimpleDeclarationVisitor()
Creates a new SimpleDeclarationVisitor.
Method Summary
void | visitAnnotationTypeDeclaration(AnnotationTypeDeclaration d) Visits an annotation type declaration.
void | visitAnnotationTypeElementDeclaration(AnnotationTypeElementDeclaration d) Visits an annotation type element declaration.
void | visitClassDeclaration(ClassDeclaration d) Visits a class declaration.
void | visitConstructorDeclaration(ConstructorDeclaration d) Visits a constructor declaration.
void | visitDeclaration(Declaration d) Visits a declaration.
void | visitEnumConstantDeclaration(EnumConstantDeclaration d) Visits an enum constant declaration.
void | visitEnumDeclaration(EnumDeclaration d) Visits an enum declaration.
void | visitExecutableDeclaration(ExecutableDeclaration d) Visits a method or constructor declaration.
void | visitFieldDeclaration(FieldDeclaration d) Visits a field declaration.
void | visitInterfaceDeclaration(InterfaceDeclaration d) Visits an interface declaration.
void | visitMemberDeclaration(MemberDeclaration d) Visits a member or constructor declaration.
void | visitMethodDeclaration(MethodDeclaration d) Visits a method declaration.
void | visitPackageDeclaration(PackageDeclaration d) Visits a package declaration.
void | visitParameterDeclaration(ParameterDeclaration d) Visits a parameter declaration.
void | visitTypeDeclaration(TypeDeclaration d) Visits a type declaration.
void | visitTypeParameterDeclaration(TypeParameterDeclaration d) Visits a type parameter declaration.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SimpleDeclarationVisitor

public SimpleDeclarationVisitor()
Creates a new SimpleDeclarationVisitor.

Method Detail

visitDeclaration

public void visitDeclaration(Declaration d)
Visits a declaration. The implementation does nothing.

Specified by:
visitDeclaration in interface DeclarationVisitor
Parameters:
d - the declaration to visit

visitPackageDeclaration

public void visitPackageDeclaration(PackageDeclaration d)
Visits a package declaration. The implementation simply invokes visitDeclaration.

Specified by:
visitPackageDeclaration in interface DeclarationVisitor
Parameters:
d - the declaration to visit

visitMemberDeclaration

public void visitMemberDeclaration(MemberDeclaration d)
Visits a member or constructor declaration. The implementation simply invokes visitDeclaration.

Specified by:
visitMemberDeclaration in interface DeclarationVisitor
Parameters:
d - the declaration to visit

visitTypeDeclaration

public void visitTypeDeclaration(TypeDeclaration d)
Visits a type declaration. The implementation simply invokes visitMemberDeclaration.

Specified by:
visitTypeDeclaration in interface DeclarationVisitor
Parameters:
d - the declaration to visit

visitClassDeclaration

public void visitClassDeclaration(ClassDeclaration d)
Visits a class declaration. The implementation simply invokes visitTypeDeclaration.

Specified by:
visitClassDeclaration in interface DeclarationVisitor
Parameters:
d - the declaration to visit

visitEnumDeclaration

public void visitEnumDeclaration(EnumDeclaration d)
Visits an enum declaration. The implementation simply invokes visitClassDeclaration.

Specified by:
visitEnumDeclaration in interface DeclarationVisitor
Parameters:
d - the declaration to visit

visitInterfaceDeclaration

public void visitInterfaceDeclaration(InterfaceDeclaration d)
Visits an interface declaration. The implementation simply invokes visitTypeDeclaration.

Specified by:
visitInterfaceDeclaration in interface DeclarationVisitor
Parameters:
d - the declaration to visit

visitAnnotationTypeDeclaration

public void visitAnnotationTypeDeclaration(AnnotationTypeDeclaration d)
Visits an annotation type declaration. The implementation simply invokes visitInterfaceDeclaration.

Specified by:
visitAnnotationTypeDeclaration in interface DeclarationVisitor
Parameters:
d - the declaration to visit

visitFieldDeclaration

public void visitFieldDeclaration(FieldDeclaration d)
Visits a field declaration. The implementation simply invokes visitMemberDeclaration.

Specified by:
visitFieldDeclaration in interface DeclarationVisitor
Parameters:
d - the declaration to visit

visitEnumConstantDeclaration

public void visitEnumConstantDeclaration(EnumConstantDeclaration d)
Visits an enum constant declaration. The implementation simply invokes visitFieldDeclaration.

Specified by:
visitEnumConstantDeclaration in interface DeclarationVisitor
Parameters:
d - the declaration to visit

visitExecutableDeclaration

public void visitExecutableDeclaration(ExecutableDeclaration d)
Visits a method or constructor declaration. The implementation simply invokes visitMemberDeclaration.

Specified by:
visitExecutableDeclaration in interface DeclarationVisitor
Parameters:
d - the declaration to visit

visitConstructorDeclaration

public void visitConstructorDeclaration(ConstructorDeclaration d)
Visits a constructor declaration. The implementation simply invokes visitExecutableDeclaration.

Specified by:
visitConstructorDeclaration in interface DeclarationVisitor
Parameters:
d - the declaration to visit

visitMethodDeclaration

public void visitMethodDeclaration(MethodDeclaration d)
Visits a method declaration. The implementation simply invokes visitExecutableDeclaration.

Specified by:
visitMethodDeclaration in interface DeclarationVisitor
Parameters:
d - the declaration to visit

visitAnnotationTypeElementDeclaration

public void visitAnnotationTypeElementDeclaration(AnnotationTypeElementDeclaration d)
Visits an annotation type element declaration. The implementation simply invokes visitMethodDeclaration.

Specified by:
visitAnnotationTypeElementDeclaration in interface DeclarationVisitor
Parameters:
d - the declaration to visit

visitParameterDeclaration

public void visitParameterDeclaration(ParameterDeclaration d)
Visits a parameter declaration. The implementation simply invokes visitDeclaration.

Specified by:
visitParameterDeclaration in interface DeclarationVisitor
Parameters:
d - the declaration to visit

visitTypeParameterDeclaration

public void visitTypeParameterDeclaration(TypeParameterDeclaration d)
Visits a type parameter declaration. The implementation simply invokes visitDeclaration.

Specified by:
visitTypeParameterDeclaration in interface DeclarationVisitor
Parameters:
d - the declaration to visit
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


SimpleTypeVisitor

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.util
Class SimpleTypeVisitor

java.lang.Object
    extended by  com.sun.mirror.util.SimpleTypeVisitor
All Implemented Interfaces:
TypeVisitor
public class SimpleTypeVisitor
extends Object
implements TypeVisitor

A simple visitor for types.

The implementations of the methods of this class do nothing but delegate up the type hierarchy. A subclass should override the methods that correspond to the kinds of types on which it will operate.

Since:
1.5

Constructor Summary
SimpleTypeVisitor()
Creates a new SimpleTypeVisitor.
Method Summary
void | visitAnnotationType(AnnotationType t) Visits an annotation type.
void | visitArrayType(ArrayType t) Visits an array type.
void | visitClassType(ClassType t) Visits a class type.
void | visitDeclaredType(DeclaredType t) Visits a declared type.
void | visitEnumType(EnumType t) Visits an enum type.
void | visitInterfaceType(InterfaceType t) Visits an interface type.
void | visitPrimitiveType(PrimitiveType t) Visits a primitive type.
void | visitReferenceType(ReferenceType t) Visits a reference type.
void | visitTypeMirror(TypeMirror t) Visits a type mirror.
void | visitTypeVariable(TypeVariable t) Visits a type variable.
void | visitVoidType(VoidType t) Visits a void type.
void | visitWildcardType(WildcardType t) Visits a wildcard.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SimpleTypeVisitor

public SimpleTypeVisitor()
Creates a new SimpleTypeVisitor.

Method Detail

visitTypeMirror

public void visitTypeMirror(TypeMirror t)
Visits a type mirror. The implementation does nothing.

Specified by:
visitTypeMirror in interface TypeVisitor
Parameters:
t - the type to visit

visitPrimitiveType

public void visitPrimitiveType(PrimitiveType t)
Visits a primitive type. The implementation simply invokes visitTypeMirror.

Specified by:
visitPrimitiveType in interface TypeVisitor
Parameters:
t - the type to visit

visitVoidType

public void visitVoidType(VoidType t)
Visits a void type. The implementation simply invokes visitTypeMirror.

Specified by:
visitVoidType in interface TypeVisitor
Parameters:
t - the type to visit

visitReferenceType

public void visitReferenceType(ReferenceType t)
Visits a reference type. The implementation simply invokes visitTypeMirror.

Specified by:
visitReferenceType in interface TypeVisitor
Parameters:
t - the type to visit

visitDeclaredType

public void visitDeclaredType(DeclaredType t)
Visits a declared type. The implementation simply invokes visitReferenceType.

Specified by:
visitDeclaredType in interface TypeVisitor
Parameters:
t - the type to visit

visitClassType

public void visitClassType(ClassType t)
Visits a class type. The implementation simply invokes visitDeclaredType.

Specified by:
visitClassType in interface TypeVisitor
Parameters:
t - the type to visit

visitEnumType

public void visitEnumType(EnumType t)
Visits an enum type. The implementation simply invokes visitClassType.

Specified by:
visitEnumType in interface TypeVisitor
Parameters:
t - the type to visit

visitInterfaceType

public void visitInterfaceType(InterfaceType t)
Visits an interface type. The implementation simply invokes visitDeclaredType.

Specified by:
visitInterfaceType in interface TypeVisitor
Parameters:
t - the type to visit

visitAnnotationType

public void visitAnnotationType(AnnotationType t)
Visits an annotation type. The implementation simply invokes visitInterfaceType.

Specified by:
visitAnnotationType in interface TypeVisitor
Parameters:
t - the type to visit

visitArrayType

public void visitArrayType(ArrayType t)
Visits an array type. The implementation simply invokes visitReferenceType.

Specified by:
visitArrayType in interface TypeVisitor
Parameters:
t - the type to visit

visitTypeVariable

public void visitTypeVariable(TypeVariable t)
Visits a type variable. The implementation simply invokes visitReferenceType.

Specified by:
visitTypeVariable in interface TypeVisitor
Parameters:
t - the type to visit

visitWildcardType

public void visitWildcardType(WildcardType t)
Visits a wildcard. The implementation simply invokes visitTypeMirror.

Specified by:
visitWildcardType in interface TypeVisitor
Parameters:
t - the type to visit
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


SourcePosition

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.util
Interface SourcePosition

public interface SourcePosition

Represents a position in a source file.

Since:
1.5

Method Summary
int | column() Returns the column number of this position.
File | file() Returns the source file containing this position.
int | line() Returns the line number of this position.

Method Detail

file

File file()
Returns the source file containing this position.

Returns:
the source file containing this position; never null

line

int line()
Returns the line number of this position. Lines are numbered starting with 1.

Returns:
the line number of this position, or 0 if the line number is unknown or not applicable

column

int column()
Returns the column number of this position. Columns are numbered starting with 1.

Returns:
the column number of this position, or 0 if the column number is unknown or not applicable
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Types

Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.util
Interface Types

public interface Types

Utility methods for operating on types.

Since:
1.5

Method Summary
ArrayType | getArrayType(TypeMirror componentType) Returns an array type with the specified component type.
DeclaredType | getDeclaredType(DeclaredType containing, TypeDeclaration decl, TypeMirror... typeArgs) Returns the type corresponding to a type declaration and actual arguments, given a containing type of which it is a member.
DeclaredType | getDeclaredType(TypeDeclaration decl, TypeMirror... typeArgs) Returns the type corresponding to a type declaration and actual type arguments.
TypeMirror | getErasure(TypeMirror t) Returns the erasure of a type.
PrimitiveType | getPrimitiveType(PrimitiveType.Kind kind) Returns a primitive type.
TypeVariable | getTypeVariable(TypeParameterDeclaration tparam) Returns the type variable declared by a type parameter.
VoidType | getVoidType() Returns the pseudo-type representing the type of void.
WildcardType | getWildcardType(Collection<ReferenceType> upperBounds, Collection<ReferenceType> lowerBounds) Returns a new wildcard.
boolean | isAssignable(TypeMirror t1, TypeMirror t2) Tests whether one type is assignable to another.
boolean | isSubtype(TypeMirror t1, TypeMirror t2) Tests whether one type is a subtype of the another.

Method Detail

isSubtype

boolean isSubtype(TypeMirror t1,
                  TypeMirror t2)
Tests whether one type is a subtype of the another. Any type is considered to be a subtype of itself.

Parameters:
t1 - the first type
t2 - the second type
Returns:
true if and only if the first type is a subtype of the second

isAssignable

boolean isAssignable(TypeMirror t1,
                     TypeMirror t2)
Tests whether one type is assignable to another.

Parameters:
t1 - the first type
t2 - the second type
Returns:
true if and only if the first type is assignable to the second

getErasure

TypeMirror getErasure(TypeMirror t)
Returns the erasure of a type.

Parameters:
t - the type to be erased
Returns:
the erasure of the given type

getPrimitiveType

PrimitiveType getPrimitiveType(PrimitiveType.Kind kind)
Returns a primitive type.

Parameters:
kind - the kind of primitive type to return
Returns:
a primitive type

getVoidType

VoidType getVoidType()
Returns the pseudo-type representing the type of void.

Returns:
the pseudo-type representing the type of void

getArrayType

ArrayType getArrayType(TypeMirror componentType)
Returns an array type with the specified component type.

Parameters:
componentType - the component type
Returns:
an array type with the specified component type.
Throws:
IllegalArgumentException - if the component type is not valid for an array

getTypeVariable

TypeVariable getTypeVariable(TypeParameterDeclaration tparam)
Returns the type variable declared by a type parameter.

Parameters:
tparam - the type parameter
Returns:
the type variable declared by the type parameter

getWildcardType

WildcardType getWildcardType(Collection<ReferenceType> upperBounds,
                             Collection<ReferenceType> lowerBounds)
Returns a new wildcard. Either the wildcards's upper bounds or lower bounds may be specified, or neither, but not both.

Parameters:
upperBounds - the upper bounds of this wildcard, or an empty collection if none
lowerBounds - the lower bounds of this wildcard, or an empty collection if none
Returns:
a new wildcard
Throws:
IllegalArgumentException - if bounds are not valid

getDeclaredType

DeclaredType getDeclaredType(TypeDeclaration decl,
                             TypeMirror... typeArgs)
Returns the type corresponding to a type declaration and actual type arguments. Given the declaration for String, for example, this method may be used to get the String type. It may then be invoked a second time, with the declaration for Set, to make the parameterized type Set<String>.

The number of type arguments must either equal the number of the declaration's formal type parameters, or must be zero. If zero, and if the declaration is generic, then the declaration's raw type is returned.

If a parameterized type is being returned, its declaration must not be contained within a generic outer class. The parameterized type Outer<String>.Inner<Number>, for example, may be constructed by first using this method to get the type Outer<String>, and then invoking getDeclaredType(DeclaredType, TypeDeclaration, TypeMirror...).

Parameters:
decl - the type declaration
typeArgs - the actual type arguments
Returns:
the type corresponding to the type declaration and actual type arguments
Throws:
IllegalArgumentException - if too many or too few type arguments are given, or if an inappropriate type argument or declaration is provided

getDeclaredType

DeclaredType getDeclaredType(DeclaredType containing,
                             TypeDeclaration decl,
                             TypeMirror... typeArgs)
Returns the type corresponding to a type declaration and actual arguments, given a containing type of which it is a member. The parameterized type Outer<String>.Inner<Number>, for example, may be constructed by first using getDeclaredType(TypeDeclaration, TypeMirror...) to get the type Outer<String>, and then invoking this method.

If the containing type is a parameterized type, the number of type arguments must equal the number of the declaration's formal type parameters. If it is not parameterized or if it is null, this method is equivalent to getDeclaredType(decl, typeArgs).

Parameters:
containing - the containing type, or null if none
decl - the type declaration
typeArgs - the actual type arguments
Returns:
the type corresponding to the type declaration and actual type arguments, contained within the given type
Throws:
IllegalArgumentException - if too many or too few type arguments are given, or if an inappropriate type argument, declaration, or containing type is provided
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


TypeVisitor

Mirror API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.mirror.util
Interface TypeVisitor

All Known Implementing Classes:
SimpleTypeVisitor
public interface TypeVisitor

A visitor for types, in the style of the standard visitor design pattern. This is used to operate on a type when the kind of type is unknown at compile time. When a visitor is passed to a type's accept method, the most specific visitXxx method applicable to that type is invoked.

Since:
1.5

Method Summary
void | visitAnnotationType(AnnotationType t) Visits an annotation type.
void | visitArrayType(ArrayType t) Visits an array type.
void | visitClassType(ClassType t) Visits a class type.
void | visitDeclaredType(DeclaredType t) Visits a declared type.
void | visitEnumType(EnumType t) Visits an enum type.
void | visitInterfaceType(InterfaceType t) Visits an interface type.
void | visitPrimitiveType(PrimitiveType t) Visits a primitive type.
void | visitReferenceType(ReferenceType t) Visits a reference type.
void | visitTypeMirror(TypeMirror t) Visits a type mirror.
void | visitTypeVariable(TypeVariable t) Visits a type variable.
void | visitVoidType(VoidType t) Visits a void type.
void | visitWildcardType(WildcardType t) Visits a wildcard.

Method Detail

visitTypeMirror

void visitTypeMirror(TypeMirror t)
Visits a type mirror.

Parameters:
t - the type to visit

visitPrimitiveType

void visitPrimitiveType(PrimitiveType t)
Visits a primitive type.

Parameters:
t - the type to visit

visitVoidType

void visitVoidType(VoidType t)
Visits a void type.

Parameters:
t - the type to visit

visitReferenceType

void visitReferenceType(ReferenceType t)
Visits a reference type.

Parameters:
t - the type to visit

visitDeclaredType

void visitDeclaredType(DeclaredType t)
Visits a declared type.

Parameters:
t - the type to visit

visitClassType

void visitClassType(ClassType t)
Visits a class type.

Parameters:
t - the type to visit

visitEnumType

void visitEnumType(EnumType t)
Visits an enum type.

Parameters:
t - the type to visit

visitInterfaceType

void visitInterfaceType(InterfaceType t)
Visits an interface type.

Parameters:
t - the type to visit

visitAnnotationType

void visitAnnotationType(AnnotationType t)
Visits an annotation type.

Parameters:
t - the type to visit

visitArrayType

void visitArrayType(ArrayType t)
Visits an array type.

Parameters:
t - the type to visit

visitTypeVariable

void visitTypeVariable(TypeVariable t)
Visits a type variable.

Parameters:
t - the type to visit

visitWildcardType

void visitWildcardType(WildcardType t)
Visits a wildcard.

Parameters:
t - the type to visit
Overview Package Class Use Tree Deprecated Index Help
Mirror API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


spec

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES

Attach API

Packages
com.sun.tools.attach | Provides the API to attach to a JavaTM virtual machine.
com.sun.tools.attach.spi | Provider classes for the com.sun.tools.attach package.

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES


 All Classes
AgentInitializationException
AgentLoadException
AttachNotSupportedException
AttachPermission
AttachProvider
VirtualMachine
VirtualMachineDescriptor


API Help

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES

How This API Document Is Organized

This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.

Overview

The Overview page is the front page of this API document and provides a list of all packages with a summary for each. This page can also contain an overall description of the set of packages.

Package

Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain four categories:

  • Interfaces (italic)
  • Classes
  • Enums
  • Exceptions
  • Errors
  • Annotation Types

Class/Interface

Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:

  • Class inheritance diagram
  • Direct Subclasses
  • All Known Subinterfaces
  • All Known Implementing Classes
  • Class/interface declaration
  • Class/interface description

  • Nested Class Summary
  • Field Summary
  • Constructor Summary
  • Method Summary

  • Field Detail
  • Constructor Detail
  • Method Detail
Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.

Annotation Type

Each annotation type has its own separate page with the following sections:

  • Annotation Type declaration
  • Annotation Type description
  • Required Element Summary
  • Optional Element Summary
  • Element Detail

Enum

Each enum has its own separate page with the following sections:

  • Enum declaration
  • Enum description
  • Enum Constant Summary
  • Enum Constant Detail

Use

Each documented package, class and interface has its own Use page. This page describes what packages, classes, methods, constructors and fields use any part of the given class or package. Given a class or interface A, its Use page includes subclasses of A, fields declared as A, methods that return A, and methods and constructors with parameters of type A. You can access this page by first going to the package, class or interface, then clicking on the "Use" link in the navigation bar.

Tree (Class Hierarchy)

There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with java.lang.Object. The interfaces do not inherit from java.lang.Object.
  • When viewing the Overview page, clicking on "Tree" displays the hierarchy for all packages.
  • When viewing a particular package, class or interface page, clicking "Tree" displays the hierarchy for only that package.

Index

The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.

Prev/Next

These links take you to the next or previous class, interface, package, or related page.

Frames/No Frames

These links show and hide the HTML frames. All pages are available with or without frames.

Serialized Form

Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.

Constant Field Values

The Constant Field Values page lists the static final fields and their values.

This help file applies to API documentation generated using the standard doclet.

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES


Attach API

Frame Alert

This document is designed to be viewed using the frames feature. If you see this message, you are using a non-frame-capable web client.
Link toNon-frame version.


Constant Field Values

Contents
Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES


Hierarchy

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES

Hierarchy For All Packages

Package Hierarchies:
com.sun.tools.attach, com.sun.tools.attach.spi

Class Hierarchy

  • java.lang.Object
    • com.sun.tools.attach.spi.AttachProvider
    • java.security.Permission (implements java.security.Guard, java.io.Serializable)
      • java.security.BasicPermission (implements java.io.Serializable)
        • com.sun.tools.attach.AttachPermission
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • com.sun.tools.attach.AgentInitializationException
        • com.sun.tools.attach.AgentLoadException
        • com.sun.tools.attach.AttachNotSupportedException
    • com.sun.tools.attach.VirtualMachine
    • com.sun.tools.attach.VirtualMachineDescriptor
Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES


Index

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES
A C D E G H I L N P R T V

A

AgentInitializationException - Exception in com.sun.tools.attach
The exception thrown when an agent fails to initialize in the target Java virtual machine.
AgentInitializationException() - Constructor for exception com.sun.tools.attach.AgentInitializationException
Constructs an AgentInitializationException with no detail message.
AgentInitializationException(String) - Constructor for exception com.sun.tools.attach.AgentInitializationException
Constructs an AgentInitializationException with the specified detail message.
AgentInitializationException(String, int) - Constructor for exception com.sun.tools.attach.AgentInitializationException
Constructs an AgentInitializationException with the specified detail message and the return value from the execution of the agent's Agent_OnAttach function.
AgentLoadException - Exception in com.sun.tools.attach
The exception thrown when an agent cannot be loaded into the target Java virtual machine.
AgentLoadException() - Constructor for exception com.sun.tools.attach.AgentLoadException
Constructs an AgentLoadException with no detail message.
AgentLoadException(String) - Constructor for exception com.sun.tools.attach.AgentLoadException
Constructs an AgentLoadException with the specified detail message.
attach(String) - Static method in class com.sun.tools.attach.VirtualMachine
Attaches to a Java virtual machine.
attach(VirtualMachineDescriptor) - Static method in class com.sun.tools.attach.VirtualMachine
Attaches to a Java virtual machine.
AttachNotSupportedException - Exception in com.sun.tools.attach
Thrown by VirtalMachine.attach when attempting to attach to a Java virtual machine for which a compatible AttachProvider does not exist.
AttachNotSupportedException() - Constructor for exception com.sun.tools.attach.AttachNotSupportedException
Constructs an AttachNotSupportedException with no detail message.
AttachNotSupportedException(String) - Constructor for exception com.sun.tools.attach.AttachNotSupportedException
Constructs an AttachNotSupportedException with the specified detail message.
AttachPermission - Class in com.sun.tools.attach
When a SecurityManager set, this is the permission which will be checked when code invokes VirtalMachine.attach to attach to a target virtual machine.
AttachPermission(String) - Constructor for class com.sun.tools.attach.AttachPermission
Constructs a new AttachPermission object.
AttachPermission(String, String) - Constructor for class com.sun.tools.attach.AttachPermission
Constructs a new AttachPermission object.
AttachProvider - Class in com.sun.tools.attach.spi
Attach provider class for attaching to a Java virtual machine.
AttachProvider() - Constructor for class com.sun.tools.attach.spi.AttachProvider
Initializes a new instance of this class.
attachVirtualMachine(String) - Method in class com.sun.tools.attach.spi.AttachProvider
Attaches to a Java virtual machine.
attachVirtualMachine(VirtualMachineDescriptor) - Method in class com.sun.tools.attach.spi.AttachProvider
Attaches to a Java virtual machine.

C

com.sun.tools.attach - package com.sun.tools.attach
Provides the API to attach to a JavaTM virtual machine.
com.sun.tools.attach.spi - package com.sun.tools.attach.spi
Provider classes for the com.sun.tools.attach package.

D

detach() - Method in class com.sun.tools.attach.VirtualMachine
Detach from the virtual machine.
displayName() - Method in class com.sun.tools.attach.VirtualMachineDescriptor
Return the display name component of this descriptor.

E

equals(Object) - Method in class com.sun.tools.attach.VirtualMachine
Tests this VirtualMachine for equality with another object.
equals(Object) - Method in class com.sun.tools.attach.VirtualMachineDescriptor
Tests this VirtualMachineDescriptor for equality with another object.

G

getAgentProperties() - Method in class com.sun.tools.attach.VirtualMachine
Returns the current agent properties in the target virtual machine.
getSystemProperties() - Method in class com.sun.tools.attach.VirtualMachine
Returns the current system properties in the target virtual machine.

H

hashCode() - Method in class com.sun.tools.attach.VirtualMachine
Returns a hash-code value for this VirtualMachine.
hashCode() - Method in class com.sun.tools.attach.VirtualMachineDescriptor
Returns a hash-code value for this VirtualMachineDescriptor.

I

id() - Method in class com.sun.tools.attach.VirtualMachine
Returns the identifier for this Java virtual machine.
id() - Method in class com.sun.tools.attach.VirtualMachineDescriptor
Return the identifier component of this descriptor.

L

list() - Static method in class com.sun.tools.attach.VirtualMachine
Return a list of Java virtual machines.
listVirtualMachines() - Method in class com.sun.tools.attach.spi.AttachProvider
Lists the Java virtual machines known to this provider.
loadAgent(String, String) - Method in class com.sun.tools.attach.VirtualMachine
Loads an agent.
loadAgent(String) - Method in class com.sun.tools.attach.VirtualMachine
Loads an agent.
loadAgentLibrary(String, String) - Method in class com.sun.tools.attach.VirtualMachine
Loads an agent library.
loadAgentLibrary(String) - Method in class com.sun.tools.attach.VirtualMachine
Loads an agent library.
loadAgentPath(String, String) - Method in class com.sun.tools.attach.VirtualMachine
Load a native agent library by full pathname.
loadAgentPath(String) - Method in class com.sun.tools.attach.VirtualMachine
Load a native agent library by full pathname.

N

name() - Method in class com.sun.tools.attach.spi.AttachProvider
Return this provider's name.

P

provider() - Method in class com.sun.tools.attach.VirtualMachine
Returns the provider that created this virtual machine.
provider() - Method in class com.sun.tools.attach.VirtualMachineDescriptor
Return the AttachProvider that this descriptor references.
providers() - Static method in class com.sun.tools.attach.spi.AttachProvider
Returns a list of the installed attach providers.

R

returnValue() - Method in exception com.sun.tools.attach.AgentInitializationException
If the exception was created with the return value from the agent Agent_OnAttach function then this returns that value, otherwise returns 0.

T

toString() - Method in class com.sun.tools.attach.VirtualMachine
Returns the string representation of the VirtualMachine.
toString() - Method in class com.sun.tools.attach.VirtualMachineDescriptor
Returns the string representation of the VirtualMachineDescriptor.
type() - Method in class com.sun.tools.attach.spi.AttachProvider
Return this provider's type.

V

VirtualMachine - Class in com.sun.tools.attach
A Java virtual machine.
VirtualMachine(AttachProvider, String) - Constructor for class com.sun.tools.attach.VirtualMachine
Initializes a new instance of this class.
VirtualMachineDescriptor - Class in com.sun.tools.attach
Describes a Java virtual machine.
VirtualMachineDescriptor(AttachProvider, String, String) - Constructor for class com.sun.tools.attach.VirtualMachineDescriptor
Creates a virtual machine descriptor from the given components.
VirtualMachineDescriptor(AttachProvider, String) - Constructor for class com.sun.tools.attach.VirtualMachineDescriptor
Creates a virtual machine descriptor from the given components.
A C D E G H I L N P R T V
Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES


Serialized Form

Package com.sun.tools.attach

Class com.sun.tools.attach.AgentInitializationException extends Exception implements Serializable

serialVersionUID: -1508756333332806353L

Serialized Fields

returnValue

int returnValue

Class com.sun.tools.attach.AgentLoadException extends Exception implements Serializable

serialVersionUID: 688047862952114238L

Class com.sun.tools.attach.AttachNotSupportedException extends Exception implements Serializable

serialVersionUID: 3391824968260177264L

Class com.sun.tools.attach.AttachPermission extends BasicPermission implements Serializable

serialVersionUID: -4619447669752976181L

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES


attach

Overview Package Class Use Tree Index Help
Attach API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package com.sun.tools.attach

Provides the API to attach to a JavaTM virtual machine.

See:
Description

Class Summary
AttachPermission | When a SecurityManager set, this is the permission which will be checked when code invokes VirtalMachine.attach to attach to a target virtual machine.
VirtualMachine | A Java virtual machine.
VirtualMachineDescriptor | Describes a Java virtual machine.

Exception Summary
AgentInitializationException | The exception thrown when an agent fails to initialize in the target Java virtual machine.
AgentLoadException | The exception thrown when an agent cannot be loaded into the target Java virtual machine.
AttachNotSupportedException | Thrown by VirtalMachine.attach when attempting to attach to a Java virtual machine for which a compatible AttachProvider does not exist.

Package com.sun.tools.attach Description

Provides the API to attach to a JavaTM virtual machine. A tool, written in the Java Language, uses this API to attach to a target virtual machine (VM) and load its tool agent into the target VM. For example, a management console might have a management agent which it uses to obtain management information from instrumented objects in a Java virtual machine. If the management console is required to manage an application that is running in a virtual machine that does not include the management agent, then this API can be used to attach to the target VM and load the agent.

Since:
1.6
Overview Package Class Use Tree Index Help
Attach API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


com.sun.tools.attach Class Hierarchy

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES

Hierarchy For Package com.sun.tools.attach

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.security.Permission (implements java.security.Guard, java.io.Serializable)
      • java.security.BasicPermission (implements java.io.Serializable)
        • com.sun.tools.attach.AttachPermission
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • com.sun.tools.attach.AgentInitializationException
        • com.sun.tools.attach.AgentLoadException
        • com.sun.tools.attach.AttachNotSupportedException
    • com.sun.tools.attach.VirtualMachine
    • com.sun.tools.attach.VirtualMachineDescriptor
Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES


Uses of Package com.sun.tools.attach

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES

Uses of Package
com.sun.tools.attach

Packages that use com.sun.tools.attach
com.sun.tools.attach | Provides the API to attach to a JavaTM virtual machine.
com.sun.tools.attach.spi | Provider classes for the com.sun.tools.attach package.

Classes in com.sun.tools.attach used by com.sun.tools.attach
AgentInitializationException
The exception thrown when an agent fails to initialize in the target Java virtual machine.
AgentLoadException
The exception thrown when an agent cannot be loaded into the target Java virtual machine.
AttachNotSupportedException
Thrown by VirtalMachine.attach when attempting to attach to a Java virtual machine for which a compatible AttachProvider does not exist.
VirtualMachine
A Java virtual machine.
VirtualMachineDescriptor
Describes a Java virtual machine.

Classes in com.sun.tools.attach used by com.sun.tools.attach.spi
AttachNotSupportedException
Thrown by VirtalMachine.attach when attempting to attach to a Java virtual machine for which a compatible AttachProvider does not exist.
VirtualMachine
A Java virtual machine.
VirtualMachineDescriptor
Describes a Java virtual machine.

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES


AgentInitializationException

Overview Package Class Use Tree Index Help
Attach API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.tools.attach
Class AgentInitializationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  com.sun.tools.attach.AgentInitializationException
All Implemented Interfaces:
Serializable
public class AgentInitializationException
extends Exception

The exception thrown when an agent fails to initialize in the target Java virtual machine.

This exception is thrown by VirtualMachine.loadAgent, VirtualMachine.loadAgentLibrary, VirtualMachine.loadAgentPath methods if an agent, or agent library, cannot be initialized. When thrown by VirtualMachine.loadAgentLibrary, or VirtualMachine.loadAgentPath then the exception encapsulates the error returned by the agent's Agent_OnAttach function. This error code can be obtained by invoking the returnValue method.

See Also:
Serialized Form

Constructor Summary
AgentInitializationException()
Constructs an AgentInitializationException with no detail message.
AgentInitializationException(String s)
Constructs an AgentInitializationException with the specified detail message.
AgentInitializationException(String s, int returnValue)
Constructs an AgentInitializationException with the specified detail message and the return value from the execution of the agent's Agent_OnAttach function.
Method Summary
 int returnValue()
If the exception was created with the return value from the agent Agent_OnAttach function then this returns that value, otherwise returns 0.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AgentInitializationException

public AgentInitializationException()
Constructs an AgentInitializationException with no detail message.

AgentInitializationException

public AgentInitializationException(String s)
Constructs an AgentInitializationException with the specified detail message.

Parameters:
s - the detail message.

AgentInitializationException

public AgentInitializationException(String s,
                                    int returnValue)
Constructs an AgentInitializationException with the specified detail message and the return value from the execution of the agent's Agent_OnAttach function.

Parameters:
s - the detail message.
returnValue - the return value
Method Detail

returnValue

public int returnValue()
If the exception was created with the return value from the agent Agent_OnAttach function then this returns that value, otherwise returns 0.

Returns:
the return value
Overview Package Class Use Tree Index Help
Attach API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


AgentLoadException

Overview Package Class Use Tree Index Help
Attach API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.tools.attach
Class AgentLoadException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  com.sun.tools.attach.AgentLoadException
All Implemented Interfaces:
Serializable
public class AgentLoadException
extends Exception

The exception thrown when an agent cannot be loaded into the target Java virtual machine.

This exception is thrown by VirtualMachine.loadAgent or VirtualMachine.loadAgentLibrary, loadAgentPath methods if the agent, or agent library, cannot be loaded.

See Also:
Serialized Form

Constructor Summary
AgentLoadException()
Constructs an AgentLoadException with no detail message.
AgentLoadException(String s)
Constructs an AgentLoadException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AgentLoadException

public AgentLoadException()
Constructs an AgentLoadException with no detail message.

AgentLoadException

public AgentLoadException(String s)
Constructs an AgentLoadException with the specified detail message.

Parameters:
s - the detail message.
Overview Package Class Use Tree Index Help
Attach API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AttachNotSupportedException

Overview Package Class Use Tree Index Help
Attach API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.tools.attach
Class AttachNotSupportedException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  com.sun.tools.attach.AttachNotSupportedException
All Implemented Interfaces:
Serializable
public class AttachNotSupportedException
extends Exception

Thrown by VirtalMachine.attach when attempting to attach to a Java virtual machine for which a compatible AttachProvider does not exist. It is also thrown by AttachProvider.attachVirtualMachine if the provider attempts to attach to a Java virtual machine with which it not comptatible.

See Also:
Serialized Form

Constructor Summary
AttachNotSupportedException()
Constructs an AttachNotSupportedException with no detail message.
AttachNotSupportedException(String s)
Constructs an AttachNotSupportedException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AttachNotSupportedException

public AttachNotSupportedException()
Constructs an AttachNotSupportedException with no detail message.

AttachNotSupportedException

public AttachNotSupportedException(String s)
Constructs an AttachNotSupportedException with the specified detail message.

Parameters:
s - the detail message.
Overview Package Class Use Tree Index Help
Attach API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AttachPermission

Overview Package Class Use Tree Index Help
Attach API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.tools.attach
Class AttachPermission

java.lang.Object
    extended by  java.security.Permission
        extended by  java.security.BasicPermission
            extended by  com.sun.tools.attach.AttachPermission
All Implemented Interfaces:
Serializable, Guard
public final class AttachPermission
extends BasicPermission

When a SecurityManager set, this is the permission which will be checked when code invokes VirtalMachine.attach to attach to a target virtual machine. This permission is also checked when an AttachProvider is created.

An AttachPermission object contains a name (also referred to as a "target name") but no actions list; you either have the named permission or you don't. The following table provides a summary description of what the permission allows, and discusses the risks of granting code the permission.

Permission Target Name | What the Permission Allows | Risks of Allowing this Permission
attachVirtualMachine | Ability to attach to another Java virtual machine and load agents into that VM. | This allows an attacker to control the target VM which can potentially cause it to misbehave.
createAttachProvider | Ability to create an AttachProvider instance. | This allows an attacker to create an AttachProvider which can potentially be used to attach to other Java virtual machines.

Programmers do not normally create AttachPermission objects directly. Instead they are created by the security policy code based on reading the security policy file.

See Also:
VirtualMachine, AttachProvider, Serialized Form

Constructor Summary
AttachPermission(String name)
Constructs a new AttachPermission object.
AttachPermission(String name, String actions)
Constructs a new AttachPermission object.
Method Summary
Methods inherited from class java.security.BasicPermission
equals, getActions, hashCode, implies, newPermissionCollection
Methods inherited from class java.security.Permission
checkGuard, getName, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

AttachPermission

public AttachPermission(String name)
Constructs a new AttachPermission object.

Parameters:
name - Permission name. Must be either "attachVirtualMachine", or "createAttachProvider".
Throws:
NullPointerException - if name is null.
IllegalArgumentException - if the name is invalid.

AttachPermission

public AttachPermission(String name,
                        String actions)
Constructs a new AttachPermission object.

Parameters:
name - Permission name. Must be either "attachVirtualMachine", or "createAttachProvider".
actions - Not used and should be null, or the empty string.
Throws:
NullPointerException - if name is null.
IllegalArgumentException - if arguments are invalid.
Overview Package Class Use Tree Index Help
Attach API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class com.sun.tools.attach.AgentInitializationException

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.tools.attach.AgentInitializationException

Packages that use AgentInitializationException
com.sun.tools.attach Provides the API to attach to a JavaTM virtual machine.

Uses of AgentInitializationException in com.sun.tools.attach

Methods in com.sun.tools.attach that throw AgentInitializationException
void | VirtualMachine.loadAgent(String agent) Loads an agent.
abstract void | VirtualMachine.loadAgent(String agent, String options) Loads an agent.
void | VirtualMachine.loadAgentLibrary(String agentLibrary) Loads an agent library.
abstract void | VirtualMachine.loadAgentLibrary(String agentLibrary, String options) Loads an agent library.
void | VirtualMachine.loadAgentPath(String agentPath) Load a native agent library by full pathname.
abstract void | VirtualMachine.loadAgentPath(String agentPath, String options) Load a native agent library by full pathname.

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.tools.attach.AgentLoadException

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.tools.attach.AgentLoadException

Packages that use AgentLoadException
com.sun.tools.attach Provides the API to attach to a JavaTM virtual machine.

Uses of AgentLoadException in com.sun.tools.attach

Methods in com.sun.tools.attach that throw AgentLoadException
void | VirtualMachine.loadAgent(String agent) Loads an agent.
abstract void | VirtualMachine.loadAgent(String agent, String options) Loads an agent.
void | VirtualMachine.loadAgentLibrary(String agentLibrary) Loads an agent library.
abstract void | VirtualMachine.loadAgentLibrary(String agentLibrary, String options) Loads an agent library.
void | VirtualMachine.loadAgentPath(String agentPath) Load a native agent library by full pathname.
abstract void | VirtualMachine.loadAgentPath(String agentPath, String options) Load a native agent library by full pathname.

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.tools.attach.AttachNotSupportedException

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.tools.attach.AttachNotSupportedException

Packages that use AttachNotSupportedException
com.sun.tools.attach | Provides the API to attach to a JavaTM virtual machine.
com.sun.tools.attach.spi | Provider classes for the com.sun.tools.attach package.

Uses of AttachNotSupportedException in com.sun.tools.attach

Methods in com.sun.tools.attach that throw AttachNotSupportedException
static VirtualMachine | VirtualMachine.attach(String id) Attaches to a Java virtual machine.
static VirtualMachine | VirtualMachine.attach(VirtualMachineDescriptor vmd) Attaches to a Java virtual machine.

Uses of AttachNotSupportedException in com.sun.tools.attach.spi

Methods in com.sun.tools.attach.spi that throw AttachNotSupportedException
abstract VirtualMachine | AttachProvider.attachVirtualMachine(String id) Attaches to a Java virtual machine.
VirtualMachine | AttachProvider.attachVirtualMachine(VirtualMachineDescriptor vmd) Attaches to a Java virtual machine.

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.tools.attach.AttachPermission

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.tools.attach.AttachPermission

No usage of com.sun.tools.attach.AttachPermission

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.tools.attach.VirtualMachine

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.tools.attach.VirtualMachine

Packages that use VirtualMachine
com.sun.tools.attach | Provides the API to attach to a JavaTM virtual machine.
com.sun.tools.attach.spi | Provider classes for the com.sun.tools.attach package.

Uses of VirtualMachine in com.sun.tools.attach

Methods in com.sun.tools.attach that return VirtualMachine
static VirtualMachine | VirtualMachine.attach(String id) Attaches to a Java virtual machine.
static VirtualMachine | VirtualMachine.attach(VirtualMachineDescriptor vmd) Attaches to a Java virtual machine.

Uses of VirtualMachine in com.sun.tools.attach.spi

Methods in com.sun.tools.attach.spi that return VirtualMachine
abstract VirtualMachine | AttachProvider.attachVirtualMachine(String id) Attaches to a Java virtual machine.
VirtualMachine | AttachProvider.attachVirtualMachine(VirtualMachineDescriptor vmd) Attaches to a Java virtual machine.

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.tools.attach.VirtualMachineDescriptor

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.tools.attach.VirtualMachineDescriptor

Packages that use VirtualMachineDescriptor
com.sun.tools.attach | Provides the API to attach to a JavaTM virtual machine.
com.sun.tools.attach.spi | Provider classes for the com.sun.tools.attach package.

Uses of VirtualMachineDescriptor in com.sun.tools.attach

Methods in com.sun.tools.attach that return types with arguments of type VirtualMachineDescriptor
static List<VirtualMachineDescriptor> VirtualMachine.list()
Return a list of Java virtual machines.

Methods in com.sun.tools.attach with parameters of type VirtualMachineDescriptor
static VirtualMachine VirtualMachine.attach(VirtualMachineDescriptor vmd)
Attaches to a Java virtual machine.

Uses of VirtualMachineDescriptor in com.sun.tools.attach.spi

Methods in com.sun.tools.attach.spi that return types with arguments of type VirtualMachineDescriptor
abstract  List<VirtualMachineDescriptor> AttachProvider.listVirtualMachines()
Lists the Java virtual machines known to this provider.

Methods in com.sun.tools.attach.spi with parameters of type VirtualMachineDescriptor
 VirtualMachine AttachProvider.attachVirtualMachine(VirtualMachineDescriptor vmd)
Attaches to a Java virtual machine.

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES


spi

Overview Package Class Use Tree Index Help
Attach API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package com.sun.tools.attach.spi

Provider classes for the com.sun.tools.attach package.

See:
Description

Class Summary
AttachProvider Attach provider class for attaching to a Java virtual machine.

Package com.sun.tools.attach.spi Description

Provider classes for the com.sun.tools.attach package.

Only developers who are defining new attach providers should need to make direct use of this package.

Since:
1.6
Overview Package Class Use Tree Index Help
Attach API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


com.sun.tools.attach.spi Class Hierarchy

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES

Hierarchy For Package com.sun.tools.attach.spi

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • com.sun.tools.attach.spi.AttachProvider
Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES


Uses of Package com.sun.tools.attach.spi

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES

Uses of Package
com.sun.tools.attach.spi

Packages that use com.sun.tools.attach.spi
com.sun.tools.attach | Provides the API to attach to a JavaTM virtual machine.
com.sun.tools.attach.spi | Provider classes for the com.sun.tools.attach package.

Classes in com.sun.tools.attach.spi used by com.sun.tools.attach
AttachProvider
Attach provider class for attaching to a Java virtual machine.

Classes in com.sun.tools.attach.spi used by com.sun.tools.attach.spi
AttachProvider
Attach provider class for attaching to a Java virtual machine.

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES


AttachProvider

Overview Package Class Use Tree Index Help
Attach API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.tools.attach.spi
Class AttachProvider

java.lang.Object
    extended by  com.sun.tools.attach.spi.AttachProvider

public abstract class AttachProvider
extends Object

Attach provider class for attaching to a Java virtual machine.

An attach provider is a concrete subclass of this class that has a zero-argument constructor and implements the abstract methods specified below.

An attach provider implementation is typically tied to a Java virtual machine implementation, version, or even mode of operation. That is, a specific provider implementation will typically only be capable of attaching to a specific Java virtual machine implementation or version. For example, Sun's JDK implementation ships with provider implementations that can only attach to Sun's HotSpot virtual machine. In general, if an environment consists of Java virtual machines of different versions and from different vendors then there will be an attach provider implementation for each family of implementations or versions.

An attach provider is identified by its name and type. The name is typically, but not required to be, a name that corresponds to the VM vendor. The Sun JDK implementation, for example, ships with attach providers that use the name "sun". The type typically corresponds to the attach mechanism. For example, an implementation that uses the Doors inter-process communication mechanism might use the type "doors". The purpose of the name and type is to identify providers in environments where there are multiple providers installed.

AttachProvider implementations are loaded and instantiated at the first invocation of the providers method. This method attempts to load all provider implementations that are installed on the platform.

All of the methods in this class are safe for use by multiple concurrent threads.

Since:
1.6

Constructor Summary
protected AttachProvider()
Initializes a new instance of this class.
Method Summary
abstract VirtualMachine | attachVirtualMachine(String id) Attaches to a Java virtual machine.
VirtualMachine | attachVirtualMachine(VirtualMachineDescriptor vmd) Attaches to a Java virtual machine.
abstract List<VirtualMachineDescriptor> | listVirtualMachines() Lists the Java virtual machines known to this provider.
abstract String | name() Return this provider's name.
static List<AttachProvider> | providers() Returns a list of the installed attach providers.
abstract String | type() Return this provider's type.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AttachProvider

protected AttachProvider()
Initializes a new instance of this class.

Throws:
SecurityException - If a security manager has been installed and it denies AttachPermission ("createAttachProvider")
Method Detail

name

public abstract String name()
Return this provider's name.

Returns:
The name of this provider

type

public abstract String type()
Return this provider's type.

Returns:
The type of this provider

attachVirtualMachine

public abstract VirtualMachine attachVirtualMachine(String id)
                                             throws AttachNotSupportedException,
                                                    IOException
Attaches to a Java virtual machine.

A Java virtual machine is identified by an abstract identifier. The nature of this identifier is platform dependent but in many cases it will be the string representation of the process identifier (or pid).

This method parses the identifier and maps the identifier to a Java virtual machine (in an implementation dependent manner). If the identifier cannot be parsed by the provider then an AttachNotSupportedException is thrown. Once parsed this method attempts to attach to the Java virtual machine. If the provider detects that the identifier corresponds to a Java virtual machine that does not exist, or it corresponds to a Java virtual machine that does not support the attach mechanism implemented by this provider, or it detects that the Java virtual machine is a version to which this provider cannot attach, then an AttachNotSupportedException is thrown.

Parameters:
id - The abstract identifier that identifies the Java virtual machine.
Returns:
VirtualMachine representing the target virtual machine.
Throws:
SecurityException - If a security manager has been installed and it denies AttachPermission ("attachVirtualMachine"), or other permission required by the implementation.
AttachNotSupportedException - If the identifier cannot be parsed, or it corresponds to to a Java virtual machine that does not exist, or it corresponds to a Java virtual machine which this provider cannot attach.
IOException - If some other I/O error occurs
NullPointerException - If id is null

attachVirtualMachine

public VirtualMachine attachVirtualMachine(VirtualMachineDescriptor vmd)
                                    throws AttachNotSupportedException,
                                           IOException
Attaches to a Java virtual machine.

A Java virtual machine can be described using a VirtualMachineDescriptor. This method invokes the descriptor's provider() method to check that it is equal to this provider. It then attempts to attach to the Java virtual machine.

Parameters:
vmd - The virtual machine descriptor
Returns:
VirtualMachine representing the target virtual machine.
Throws:
SecurityException - If a security manager has been installed and it denies AttachPermission ("attachVirtualMachine"), or other permission required by the implementation.
AttachNotSupportedException - If the descriptor's provider() method returns a provider that is not this provider, or it does not correspond to a Java virtual machine to which this provider can attach.
IOException - If some other I/O error occurs
NullPointerException - If vmd is null

listVirtualMachines

public abstract List<VirtualMachineDescriptor> listVirtualMachines()
Lists the Java virtual machines known to this provider.

This method returns a list of VirtualMachineDescriptor elements. Each VirtualMachineDescriptor describes a Java virtual machine to which this provider can potentially attach. There isn't any guarantee that invoking attachVirtualMachine on each descriptor in the list will succeed.

Returns:
The list of virtual machine descriptors which describe the Java virtual machines known to this provider (may be empty).

providers

public static List<AttachProvider> providers()
Returns a list of the installed attach providers.

An AttachProvider is installed on the platform if:

  • It is installed in a JAR file that is visible to the defining class loader of the AttachProvider type (usually, but not required to be, the system class loader).

  • The JAR file contains a provider configuration named com.sun.tools.attach.spi.AttachProvider in the resource directory META-INF/services.

  • The provider configuration file lists the full-qualified class name of the AttachProvider implementation.

The format of the provider configuration file is one fully-qualified class name per line. Space and tab characters surrounding each class name, as well as blank lines are ignored. The comment character is '#' (0x23), and on each line all characters following the first comment character are ignored. The file must be encoded in UTF-8.

AttachProvider implementations are loaded and instantiated (using the zero-arg constructor) at the first invocation of this method. The list returned by the first invocation of this method is the list of providers. Subsequent invocations of this method return a list of the same providers. The list is unmodifable.

Returns:
A list of the installed attach providers.
Overview Package Class Use Tree Index Help
Attach API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class com.sun.tools.attach.spi.AttachProvider

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.tools.attach.spi.AttachProvider

Packages that use AttachProvider
com.sun.tools.attach | Provides the API to attach to a JavaTM virtual machine.
com.sun.tools.attach.spi | Provider classes for the com.sun.tools.attach package.

Uses of AttachProvider in com.sun.tools.attach

Methods in com.sun.tools.attach that return AttachProvider
AttachProvider | VirtualMachineDescriptor.provider() Return the AttachProvider that this descriptor references.
AttachProvider | VirtualMachine.provider() Returns the provider that created this virtual machine.

Constructors in com.sun.tools.attach with parameters of type AttachProvider
VirtualMachine(AttachProvider provider, String id)
Initializes a new instance of this class.
VirtualMachineDescriptor(AttachProvider provider, String id)
Creates a virtual machine descriptor from the given components.
VirtualMachineDescriptor(AttachProvider provider, String id, String displayName)
Creates a virtual machine descriptor from the given components.

Uses of AttachProvider in com.sun.tools.attach.spi

Methods in com.sun.tools.attach.spi that return types with arguments of type AttachProvider
static List<AttachProvider> AttachProvider.providers()
Returns a list of the installed attach providers.

Overview Package Class Use Tree Index Help
Attach API
PREV NEXT FRAMES NO FRAMES


VirtualMachine

Overview Package Class Use Tree Index Help
Attach API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.tools.attach
Class VirtualMachine

java.lang.Object
    extended by  com.sun.tools.attach.VirtualMachine

public abstract class VirtualMachine
extends Object

A Java virtual machine.

A VirtualMachine represents a Java virtual machine to which this Java virtual machine has attached. The Java virtual machine to which it is attached is sometimes called the target virtual machine, or target VM. An application (typically a tool such as a managemet console or profiler) uses a VirtualMachine to load an agent into the target VM. For example, a profiler tool written in the Java Language might attach to a running application and load its profiler agent to profile the running application.

A VirtualMachine is obtained by invoking the attach method with an identifier that identifies the target virtual machine. The identifier is implementation-dependent but is typically the process identifier (or pid) in environments where each Java virtual machine runs in its own operating system process. Alternatively, a VirtualMachine instance is obtained by invoking the attach method with a VirtualMachineDescriptor obtained from the list of virtual machine descriptors returned by the list method. Once a reference to a virtual machine is obtained, the loadAgent, loadAgentLibrary, and loadAgentPath methods are used to load agents into target virtual machine. The loadAgent method is used to load agents that are written in the Java Language and deployed in a JAR file. (See java.lang.instrument for a detailed description on how these agents are loaded and started). The loadAgentLibrary and loadAgentPath methods are used to load agents that are deployed in a dynamic library and make use of the JVM Tools Interface.

In addition to loading agents a VirtualMachine provides read access to the system properties in the target VM. This can be useful in some environments where properties such as java.home, os.name, or os.arch are used to construct the path to agent that will be loaded into the target VM.

The following example demonstrates how VirtualMachine may be used:

        // attach to target VM
        VirtualMachine vm = VirtualMachine.attach("2177");

        // get system properties in target VM
        Properties props = vm.getSystemProperties();

        // construct path to management agent
        String home = props.getProperty("java.home");
        String agent = home + File.separator + "lib" + File.separator
            + "management-agent.jar";

        // load agent into target VM
        vm.loadAgent(agent, "com.sun.management.jmxremote.port=5000");

        // detach
        vm.detach();

In this example we attach to a Java virtual machine that is identified by the process identifier 2177. The system properties from the target VM are then used to construct the path to a management agent which is then loaded into the target VM. Once loaded the client detaches from the target VM.

A VirtualMachine is safe for use by multiple concurrent threads.

Since:
1.6

Constructor Summary
protected VirtualMachine(AttachProvider provider, String id)
Initializes a new instance of this class.
Method Summary
static VirtualMachine | attach(String id) Attaches to a Java virtual machine.
static VirtualMachine | attach(VirtualMachineDescriptor vmd) Attaches to a Java virtual machine.
abstract void | detach() Detach from the virtual machine.
boolean | equals(Object ob) Tests this VirtualMachine for equality with another object.
abstract Properties | getAgentProperties() Returns the current agent properties in the target virtual machine.
abstract Properties | getSystemProperties() Returns the current system properties in the target virtual machine.
int | hashCode() Returns a hash-code value for this VirtualMachine.
String | id() Returns the identifier for this Java virtual machine.
static List<VirtualMachineDescriptor> | list() Return a list of Java virtual machines.
void | loadAgent(String agent) Loads an agent.
abstract void | loadAgent(String agent, String options) Loads an agent.
void | loadAgentLibrary(String agentLibrary) Loads an agent library.
abstract void | loadAgentLibrary(String agentLibrary, String options) Loads an agent library.
void | loadAgentPath(String agentPath) Load a native agent library by full pathname.
abstract void | loadAgentPath(String agentPath, String options) Load a native agent library by full pathname.
AttachProvider | provider() Returns the provider that created this virtual machine.
String | toString() Returns the string representation of the VirtualMachine.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

VirtualMachine

protected VirtualMachine(AttachProvider provider,
                         String id)
Initializes a new instance of this class.

Parameters:
provider - The attach provider creating this class.
id - The abstract identifier that identifies the Java virtual machine.
Throws:
NullPointerException - If provider or id is null.
Method Detail

list

public static List<VirtualMachineDescriptor> list()
Return a list of Java virtual machines.

This method returns a list of Java VirtualMachineDescriptor elements. The list is an aggregation of the virtual machine descriptor lists obtained by invoking the listVirtualMachines method of all installed attach providers. If there are no Java virtual machines known to any provider then an empty list is returned.

Returns:
The list of virtual machine descriptors.

attach

public static VirtualMachine attach(String id)
                             throws AttachNotSupportedException,
                                    IOException
Attaches to a Java virtual machine.

This method obtains the list of attach providers by invoking the AttachProvider.providers() method. It then iterates overs the list and invokes each provider's attachVirtualMachine method in turn. If a provider successfully attaches then the iteration terminates, and the VirtualMachine created by the provider that successfully attached is returned by this method. If the attachVirtualMachine method of all providers throws AttachNotSupportedException then this method also throws AttachNotSupportedException. This means that AttachNotSupportedException is thrown when the identifier provided to this method is invalid, or the identifier corresponds to a Java virtual machine that does not exist, or none of the providers can attach to it. This exception is also thrown if AttachProvider.providers() returns an empty list.

Parameters:
id - The abstract identifier that identifies the Java virtual machine.
Returns:
A VirtualMachine representing the target VM.
Throws:
SecurityException - If a security manager has been installed and it denies AttachPermission ("attachVirtualMachine"), or another permission required by the implementation.
AttachNotSupportedException - If the attachVirtualmachine method of all installed providers throws AttachNotSupportedException, or there aren't any providers installed.
IOException - If an I/O error occurs
NullPointerException - If id is null.

attach

public static VirtualMachine attach(VirtualMachineDescriptor vmd)
                             throws AttachNotSupportedException,
                                    IOException
Attaches to a Java virtual machine.

This method first invokes the provider() method of the given virtual machine descriptor to obtain the attach provider. It then invokes the attach provider's attachVirtualMachine to attach to the target VM.

Parameters:
vmd - The virtual machine descriptor.
Returns:
A VirtualMachine representing the target VM.
Throws:
SecurityException - If a security manager has been installed and it denies AttachPermission ("attachVirtualMachine"), or another permission required by the implementation.
AttachNotSupportedException - If the attach provider's attachVirtualmachine throws AttachNotSupportedException.
IOException - If an I/O error occurs
NullPointerException - If vmd is null.

detach

public abstract void detach()
                     throws IOException
Detach from the virtual machine.

After detaching from the virtual machine, any further attempt to invoke operations on that virtual machine will cause an IOException to be thrown. If an operation (such as loadAgent for example) is in progress when this method is invoked then the behaviour is implementation dependent. In other words, it is implementation specific if the operation completes or throws IOException.

If already detached from the virtual machine then invoking this method has no effect.

Throws:
IOException - If an I/O error occurs

provider

public final AttachProvider provider()
Returns the provider that created this virtual machine.

Returns:
The provider that created this virtual machine.

id

public final String id()
Returns the identifier for this Java virtual machine.

Returns:
The identifier for this Java virtual machine.

loadAgentLibrary

public abstract void loadAgentLibrary(String agentLibrary,
                                      String options)
                               throws AgentLoadException,
                                      AgentInitializationException,
                                      IOException
Loads an agent library.

A JVM TI client is called an agent. It is developed in a native language. A JVM TI agent is deployed in a platform specific manner but it is typically the platform equivalent of a dynamic library. This method causes the given agent library to be loaded into the target VM (if not already loaded). It then causes the target VM to invoke the Agent_OnAttach function as specified in the JVM Tools Interface specification. Note that the Agent_OnAttach function is invoked even if the agent library was loaded prior to invoking this method.

The agent library provided is the name of the agent library. It is interpreted in the target virtual machine in an implementation-dependent manner. Typically an implementation will expand the library name into an operating system specific file name. For example, on UNIX systems, the name foo might be expanded to libfoo.so, and located using the search path specified by the LD_LIBRARY_PATH environment variable.

If the Agent_OnAttach function in the agent library returns an error then an AgentInitializationException is thrown. The return value from the Agent_OnAttach can then be obtained by invoking the returnValue method on the exception.

Parameters:
agentLibrary - The name of the agent library.
options - The options to provide to the Agent_OnAttach function (can be null).
Throws:
AgentLoadException - If the agent library does not exist, or cannot be loaded for another reason.
AgentInitializationException - If the Agent_OnAttach function returns an error
IOException - If an I/O error occurs
NullPointerException - If agentLibrary is null.
See Also:
AgentInitializationException.returnValue()

loadAgentLibrary

public void loadAgentLibrary(String agentLibrary)
                      throws AgentLoadException,
                             AgentInitializationException,
                             IOException
Loads an agent library.

This convenience method works as if by invoking:

loadAgentLibrary(agentLibrary, null);

Parameters:
agentLibrary - The name of the agent library.
Throws:
AgentLoadException - If the agent library does not exist, or cannot be loaded for another reason.
AgentInitializationException - If the Agent_OnAttach function returns an error
IOException - If an I/O error occurs
NullPointerException - If agentLibrary is null.

loadAgentPath

public abstract void loadAgentPath(String agentPath,
                                   String options)
                            throws AgentLoadException,
                                   AgentInitializationException,
                                   IOException
Load a native agent library by full pathname.

A JVM TI client is called an agent. It is developed in a native language. A JVM TI agent is deployed in a platform specific manner but it is typically the platform equivalent of a dynamic library. This method causes the given agent library to be loaded into the target VM (if not already loaded). It then causes the target VM to invoke the Agent_OnAttach function as specified in the JVM Tools Interface specification. Note that the Agent_OnAttach function is invoked even if the agent library was loaded prior to invoking this method.

The agent library provided is the absolute path from which to load the agent library. Unlike loadAgentLibrary, the library name is not expanded in the target virtual machine.

If the Agent_OnAttach function in the agent library returns an error then an AgentInitializationException is thrown. The return value from the Agent_OnAttach can then be obtained by invoking the returnValue method on the exception.

Parameters:
agentPath - The full path of the agent library.
options - The options to provide to the Agent_OnAttach function (can be null).
Throws:
AgentLoadException - If the agent library does not exist, or cannot be loaded for another reason.
AgentInitializationException - If the Agent_OnAttach function returns an error
IOException - If an I/O error occurs
NullPointerException - If agentPath is null.
See Also:
AgentInitializationException.returnValue()

loadAgentPath

public void loadAgentPath(String agentPath)
                   throws AgentLoadException,
                          AgentInitializationException,
                          IOException
Load a native agent library by full pathname.

This convenience method works as if by invoking:

loadAgentPath(agentLibrary, null);

Parameters:
agentPath - The full path to the agent library.
Throws:
AgentLoadException - If the agent library does not exist, or cannot be loaded for another reason.
AgentInitializationException - If the Agent_OnAttach function returns an error
IOException - If an I/O error occurs
NullPointerException - If agentPath is null.

loadAgent

public abstract void loadAgent(String agent,
                               String options)
                        throws AgentLoadException,
                               AgentInitializationException,
                               IOException
Loads an agent.

The agent provided to this method is a path name to a JAR file on the file system of the target virtual machine. This path is passed to the target virtual machine where it is interpreted. The target virtual machine attempts to start the agent as specified by the java.lang.instrument specification. That is, the specified JAR file is added to the system class path (of the target virtual machine), and the agentmain method of the agent class, specified by the Agent-Class attribute in the JAR manifest, is invoked. This method completes when the agentmain method completes.

Parameters:
agent - Path to the JAR file containing the agent.
options - The options to provide to the agent's agentmain method (can be null).
Throws:
AgentLoadException - If the agent does not exist, or cannot be started in the manner specified in the java.lang.instrument specification.
AgentInitializationException - If the agentmain throws an exception
IOException - If an I/O error occurs
NullPointerException - If agent is null.

loadAgent

public void loadAgent(String agent)
               throws AgentLoadException,
                      AgentInitializationException,
                      IOException
Loads an agent.

This convenience method works as if by invoking:

loadAgent(agent, null);

Parameters:
agent - Path to the JAR file containing the agent.
Throws:
AgentLoadException - If the agent does not exist, or cannot be started in the manner specified in the java.lang.instrument specification.
AgentInitializationException - If the agentmain throws an exception
IOException - If an I/O error occurs
NullPointerException - If agent is null.

getSystemProperties

public abstract Properties getSystemProperties()
                                        throws IOException
Returns the current system properties in the target virtual machine.

This method returns the system properties in the target virtual machine. Properties whose key or value is not a String are omitted. The method is approximately equivalent to the invocation of the method System.getProperties in the target virtual machine except that properties with a key or value that is not a String are not included.

This method is typically used to decide which agent to load into the target virtual machine with loadAgent, or loadAgentLibrary. For example, the java.home or user.dir properties might be use to create the path to the agent library or JAR file.

Returns:
The system properties
Throws:
IOException - If an I/O error occurs
See Also:
System.getProperties(),
loadAgentLibrary(java.lang.String, java.lang.String),
loadAgent(java.lang.String, java.lang.String)

getAgentProperties

public abstract Properties getAgentProperties()
                                       throws IOException
Returns the current agent properties in the target virtual machine.

The target virtual machine can maintain a list of properties on behalf of agents. The manner in which this is done, the names of the properties, and the types of values that are allowed, is implementation specific. Agent properties are typically used to store communication end-points and other agent configuration details. For example, a debugger agent might create an agent property for its transport address.

This method returns the agent properties whose key and value is a String. Properties whose key or value is not a String are omitted. If there are no agent properties maintained in the target virtual machine then an empty property list is returned.

Returns:
The agent properties
Throws:
IOException - If an I/O error occurs

hashCode

public int hashCode()
Returns a hash-code value for this VirtualMachine. The hash code is based upon the VirtualMachine's components, and satifies the general contract of the Object.hashCode method.

Overrides:
hashCode in class Object
Returns:
A hash-code value for this virtual machine

equals

public boolean equals(Object ob)
Tests this VirtualMachine for equality with another object.

If the given object is not a VirtualMachine then this method returns false. For two VirtualMachines to be considered equal requires that they both reference the same provider, and their identifiers are equal.

This method satisfies the general contract of the Object.equals method.

Overrides:
equals in class Object
Parameters:
ob - The object to which this object is to be compared
Returns:
true if, and only if, the given object is a VirtualMachine that is equal to this VirtualMachine.

toString

public String toString()
Returns the string representation of the VirtualMachine.

Overrides:
toString in class Object
Overview Package Class Use Tree Index Help
Attach API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VirtualMachineDescriptor

Overview Package Class Use Tree Index Help
Attach API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.tools.attach
Class VirtualMachineDescriptor

java.lang.Object
    extended by  com.sun.tools.attach.VirtualMachineDescriptor

public class VirtualMachineDescriptor
extends Object

Describes a Java virtual machine.

A VirtualMachineDescriptor is a container class used to describe a Java virtual machine. It encapsulates an identifier that identifies a target virtual machine, and a reference to the AttachProvider that should be used when attempting to attach to the virtual machine. The identifier is implementation-dependent but is typically the process identifier (or pid) environments where each Java virtual machine runs in its own operating system process.

A VirtualMachineDescriptor also has a displayName. The display name is typically a human readable string that a tool might display to a user. For example, a tool that shows a list of Java virtual machines running on a system might use the display name rather than the identifier. A VirtualMachineDescriptor may be created without a display name. In that case the identifier is used as the display name.

VirtualMachineDescriptor instances are typically created by invoking the VirtualMachine.list() method. This returns the complete list of descriptors to describe the Java virtual machines known to all installed attach providers.

Since:
1.6

Constructor Summary
VirtualMachineDescriptor(AttachProvider provider, String id)
Creates a virtual machine descriptor from the given components.
VirtualMachineDescriptor(AttachProvider provider, String id, String displayName)
Creates a virtual machine descriptor from the given components.
Method Summary
String | displayName() Return the display name component of this descriptor.
boolean | equals(Object ob) Tests this VirtualMachineDescriptor for equality with another object.
int | hashCode() Returns a hash-code value for this VirtualMachineDescriptor.
String | id() Return the identifier component of this descriptor.
AttachProvider | provider() Return the AttachProvider that this descriptor references.
String | toString() Returns the string representation of the VirtualMachineDescriptor.
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

VirtualMachineDescriptor

public VirtualMachineDescriptor(AttachProvider provider,
                                String id,
                                String displayName)
Creates a virtual machine descriptor from the given components.

Parameters:
provider - The AttachProvider to attach to the Java virtual machine.
id - The virtual machine identifier.
displayName - The display name.
Throws:
NullPointerException - If any of the arguments are null

VirtualMachineDescriptor

public VirtualMachineDescriptor(AttachProvider provider,
                                String id)
Creates a virtual machine descriptor from the given components.

This convenience constructor works as if by invoking the three-argument constructor as follows:

new VirtualMachineDescriptor(provider,  id,  id);

That is, it creates a virtual machine descriptor such that the display name is the same as the virtual machine identifier.

Parameters:
provider - The AttachProvider to attach to the Java virtual machine.
id - The virtual machine identifier.
Throws:
NullPointerException - If provider or id is null.
Method Detail

provider

public AttachProvider provider()
Return the AttachProvider that this descriptor references.

Returns:
The AttachProvider that this descriptor references.

id

public String id()
Return the identifier component of this descriptor.

Returns:
The identifier component of this descriptor.

displayName

public String displayName()
Return the display name component of this descriptor.

Returns:
The display name component of this descriptor.

hashCode

public int hashCode()
Returns a hash-code value for this VirtualMachineDescriptor. The hash code is based upon the descriptor's components, and satifies the general contract of the Object.hashCode method.

Overrides:
hashCode in class Object
Returns:
A hash-code value for this descriptor.

equals

public boolean equals(Object ob)
Tests this VirtualMachineDescriptor for equality with another object.

If the given object is not a VirtualMachineDescriptor then this method returns false. For two VirtualMachineDescriptors to be considered equal requires that they both reference the same provider, and their identifiers are equal.

This method satisfies the general contract of the Object.equals method.

Overrides:
equals in class Object
Parameters:
ob - The object to which this object is to be compared
Returns:
true if, and only if, the given object is a VirtualMachineDescriptor that is equal to this VirtualMachineDescriptor.

toString

public String toString()
Returns the string representation of the VirtualMachineDescriptor.

Overrides:
toString in class Object
Overview Package Class Use Tree Index Help
Attach API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


tree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Compiler Tree API

Packages
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


 All Classes
AnnotationTree
ArrayAccessTree
ArrayTypeTree
AssertTree
AssignmentTree
BinaryTree
BlockTree
BreakTree
CaseTree
CatchTree
ClassTree
CompilationUnitTree
CompoundAssignmentTree
ConditionalExpressionTree
ContinueTree
DoWhileLoopTree
EmptyStatementTree
EnhancedForLoopTree
ErroneousTree
ExpressionStatementTree
ExpressionTree
ForLoopTree
IdentifierTree
IfTree
ImportTree
InstanceOfTree
JavacTask
LabeledStatementTree
LineMap
LiteralTree
MemberSelectTree
MethodInvocationTree
MethodTree
ModifiersTree
NewArrayTree
NewClassTree
ParameterizedTypeTree
ParenthesizedTree
PrimitiveTypeTree
ReturnTree
Scope
SimpleTreeVisitor
SourcePositions
StatementTree
SwitchTree
SynchronizedTree
TaskEvent
TaskEvent.Kind
TaskListener
ThrowTree
Tree
Tree.Kind
TreePath
TreePathScanner
Trees
TreeScanner
TreeVisitor
TryTree
TypeCastTree
TypeParameterTree
UnaryTree
VariableTree
WhileLoopTree
WildcardTree


API Help

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

How This API Document Is Organized

This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.

Overview

The Overview page is the front page of this API document and provides a list of all packages with a summary for each. This page can also contain an overall description of the set of packages.

Package

Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain four categories:

  • Interfaces (italic)
  • Classes
  • Enums
  • Exceptions
  • Errors
  • Annotation Types

Class/Interface

Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:

  • Class inheritance diagram
  • Direct Subclasses
  • All Known Subinterfaces
  • All Known Implementing Classes
  • Class/interface declaration
  • Class/interface description

  • Nested Class Summary
  • Field Summary
  • Constructor Summary
  • Method Summary

  • Field Detail
  • Constructor Detail
  • Method Detail
Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.

Annotation Type

Each annotation type has its own separate page with the following sections:

  • Annotation Type declaration
  • Annotation Type description
  • Required Element Summary
  • Optional Element Summary
  • Element Detail

Enum

Each enum has its own separate page with the following sections:

  • Enum declaration
  • Enum description
  • Enum Constant Summary
  • Enum Constant Detail

Use

Each documented package, class and interface has its own Use page. This page describes what packages, classes, methods, constructors and fields use any part of the given class or package. Given a class or interface A, its Use page includes subclasses of A, fields declared as A, methods that return A, and methods and constructors with parameters of type A. You can access this page by first going to the package, class or interface, then clicking on the "Use" link in the navigation bar.

Tree (Class Hierarchy)

There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with java.lang.Object. The interfaces do not inherit from java.lang.Object.
  • When viewing the Overview page, clicking on "Tree" displays the hierarchy for all packages.
  • When viewing a particular package, class or interface page, clicking "Tree" displays the hierarchy for only that package.

Deprecated API

The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.

Index

The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.

Prev/Next

These links take you to the next or previous class, interface, package, or related page.

Frames/No Frames

These links show and hide the HTML frames. All pages are available with or without frames.

Serialized Form

Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.

Constant Field Values

The Constant Field Values page lists the static final fields and their values.

This help file applies to API documentation generated using the standard doclet.

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Compiler Tree API

Frame Alert

This document is designed to be viewed using the frames feature. If you see this message, you are using a non-frame-capable web client.
Link toNon-frame version.


Constant Field Values

Contents
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Deprecated List

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Deprecated API

Contents
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Hierarchy

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Hierarchy For All Packages

Package Hierarchies:
com.sun.source.tree, com.sun.source.util

Class Hierarchy

  • java.lang.Object
    • com.sun.source.util.JavacTask (implements javax.tools.JavaCompiler.CompilationTask)
    • com.sun.source.util.SimpleTreeVisitor<R,P> (implements com.sun.source.tree.TreeVisitor<R,P>)
    • com.sun.source.util.TaskEvent
    • com.sun.source.util.TreePath (implements java.lang.Iterable<T>)
    • com.sun.source.util.Trees
    • com.sun.source.util.TreeScanner<R,P> (implements com.sun.source.tree.TreeVisitor<R,P>)
      • com.sun.source.util.TreePathScanner<R,P>

Interface Hierarchy

  • com.sun.source.tree.LineMap
  • com.sun.source.tree.Scope
  • com.sun.source.util.SourcePositions
  • com.sun.source.util.TaskListener
  • com.sun.source.tree.Tree
    • com.sun.source.tree.AnnotationTree
    • com.sun.source.tree.ArrayAccessTree
    • com.sun.source.tree.ArrayTypeTree
    • com.sun.source.tree.AssertTree
    • com.sun.source.tree.AssignmentTree
    • com.sun.source.tree.BinaryTree
    • com.sun.source.tree.BlockTree
    • com.sun.source.tree.BreakTree
    • com.sun.source.tree.CaseTree
    • com.sun.source.tree.CatchTree
    • com.sun.source.tree.ClassTree
    • com.sun.source.tree.CompilationUnitTree
    • com.sun.source.tree.CompoundAssignmentTree
    • com.sun.source.tree.ConditionalExpressionTree
    • com.sun.source.tree.ContinueTree
    • com.sun.source.tree.DoWhileLoopTree
    • com.sun.source.tree.EmptyStatementTree
    • com.sun.source.tree.EnhancedForLoopTree
    • com.sun.source.tree.ErroneousTree
    • com.sun.source.tree.ExpressionStatementTree
    • com.sun.source.tree.ExpressionTree
      • com.sun.source.tree.AnnotationTree
      • com.sun.source.tree.ArrayAccessTree
      • com.sun.source.tree.AssignmentTree
      • com.sun.source.tree.BinaryTree
      • com.sun.source.tree.CompoundAssignmentTree
      • com.sun.source.tree.ConditionalExpressionTree
      • com.sun.source.tree.ErroneousTree
      • com.sun.source.tree.IdentifierTree
      • com.sun.source.tree.InstanceOfTree
      • com.sun.source.tree.LiteralTree
      • com.sun.source.tree.MemberSelectTree
      • com.sun.source.tree.MethodInvocationTree
      • com.sun.source.tree.NewArrayTree
      • com.sun.source.tree.NewClassTree
      • com.sun.source.tree.ParenthesizedTree
      • com.sun.source.tree.TypeCastTree
      • com.sun.source.tree.UnaryTree
    • com.sun.source.tree.ForLoopTree
    • com.sun.source.tree.IdentifierTree
    • com.sun.source.tree.IfTree
    • com.sun.source.tree.ImportTree
    • com.sun.source.tree.InstanceOfTree
    • com.sun.source.tree.LabeledStatementTree
    • com.sun.source.tree.LiteralTree
    • com.sun.source.tree.MemberSelectTree
    • com.sun.source.tree.MethodInvocationTree
    • com.sun.source.tree.MethodTree
    • com.sun.source.tree.ModifiersTree
    • com.sun.source.tree.NewArrayTree
    • com.sun.source.tree.NewClassTree
    • com.sun.source.tree.ParameterizedTypeTree
    • com.sun.source.tree.ParenthesizedTree
    • com.sun.source.tree.PrimitiveTypeTree
    • com.sun.source.tree.ReturnTree
    • com.sun.source.tree.StatementTree
      • com.sun.source.tree.AssertTree
      • com.sun.source.tree.BlockTree
      • com.sun.source.tree.BreakTree
      • com.sun.source.tree.ClassTree
      • com.sun.source.tree.ContinueTree
      • com.sun.source.tree.DoWhileLoopTree
      • com.sun.source.tree.EmptyStatementTree
      • com.sun.source.tree.EnhancedForLoopTree
      • com.sun.source.tree.ExpressionStatementTree
      • com.sun.source.tree.ForLoopTree
      • com.sun.source.tree.IfTree
      • com.sun.source.tree.LabeledStatementTree
      • com.sun.source.tree.ReturnTree
      • com.sun.source.tree.SwitchTree
      • com.sun.source.tree.SynchronizedTree
      • com.sun.source.tree.ThrowTree
      • com.sun.source.tree.TryTree
      • com.sun.source.tree.VariableTree
      • com.sun.source.tree.WhileLoopTree
    • com.sun.source.tree.SwitchTree
    • com.sun.source.tree.SynchronizedTree
    • com.sun.source.tree.ThrowTree
    • com.sun.source.tree.TryTree
    • com.sun.source.tree.TypeCastTree
    • com.sun.source.tree.TypeParameterTree
    • com.sun.source.tree.UnaryTree
    • com.sun.source.tree.VariableTree
    • com.sun.source.tree.WhileLoopTree
    • com.sun.source.tree.WildcardTree
  • com.sun.source.tree.TreeVisitor<R,P>

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • com.sun.source.tree.Tree.Kind
      • com.sun.source.util.TaskEvent.Kind
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Index

Compiler Tree API
PREV NEXT FRAMES NO FRAMES
A B C D E F G I J L M N P R S T U V W

A

accept(TreeVisitor<R, D>, D) - Method in interface com.sun.source.tree.Tree
Accept method used to implement the visitor pattern.
analyze() - Method in class com.sun.source.util.JavacTask
Complete all analysis.
AnnotationTree - Interface in com.sun.source.tree
A tree node for an annotation.
ArrayAccessTree - Interface in com.sun.source.tree
A tree node for an array access expression.
ArrayTypeTree - Interface in com.sun.source.tree
A tree node for an array type.
asInterface() - Method in enum com.sun.source.tree.Tree.Kind
AssertTree - Interface in com.sun.source.tree
A tree node for an 'assert' statement.
AssignmentTree - Interface in com.sun.source.tree
A tree node for an assignment expression.

B

BinaryTree - Interface in com.sun.source.tree
A tree node for a binary expression.
BlockTree - Interface in com.sun.source.tree
A tree node for a statement block.
BreakTree - Interface in com.sun.source.tree
A tree node for a 'break' statement.

C

CaseTree - Interface in com.sun.source.tree
A tree node for a 'case' in a 'switch' statement.
CatchTree - Interface in com.sun.source.tree
A tree node for a 'catch' block in a 'try' statement.
ClassTree - Interface in com.sun.source.tree
A tree node for a class, interface, enum, or annotation type declaration.
com.sun.source.tree - package com.sun.source.tree
Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util - package com.sun.source.util
Provides utilities for operations on abstract syntax trees (AST).
CompilationUnitTree - Interface in com.sun.source.tree
Represents the abstract syntax tree for compilation units (source files) and package declarations (package-info.java).
CompoundAssignmentTree - Interface in com.sun.source.tree
A tree node for compound assignment operator.
ConditionalExpressionTree - Interface in com.sun.source.tree
A tree node for the conditional operator ? :.
ContinueTree - Interface in com.sun.source.tree
A tree node for a 'continue' statement.

D

DEFAULT_VALUE - Variable in class com.sun.source.util.SimpleTreeVisitor
defaultAction(Tree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
DoWhileLoopTree - Interface in com.sun.source.tree
A tree node for a 'do' statement.

E

EmptyStatementTree - Interface in com.sun.source.tree
A tree node for an empty (skip) statement.
EnhancedForLoopTree - Interface in com.sun.source.tree
A tree node for an "enhanced" 'for' loop statement.
ErroneousTree - Interface in com.sun.source.tree
A tree node to stand in for a malformed expression.
ExpressionStatementTree - Interface in com.sun.source.tree
A tree node for an expression statement.
ExpressionTree - Interface in com.sun.source.tree
A tree node used as the base class for the different types of expressions.

F

finished(TaskEvent) - Method in interface com.sun.source.util.TaskListener
ForLoopTree - Interface in com.sun.source.tree
A tree node for a basic 'for' loop statement.

G

generate() - Method in class com.sun.source.util.JavacTask
Generate code.
getAnnotations() - Method in interface com.sun.source.tree.ModifiersTree
getAnnotationType() - Method in interface com.sun.source.tree.AnnotationTree
getArguments() - Method in interface com.sun.source.tree.AnnotationTree
getArguments() - Method in interface com.sun.source.tree.MethodInvocationTree
getArguments() - Method in interface com.sun.source.tree.NewClassTree
getBlock() - Method in interface com.sun.source.tree.CatchTree
getBlock() - Method in interface com.sun.source.tree.SynchronizedTree
getBlock() - Method in interface com.sun.source.tree.TryTree
getBody() - Method in interface com.sun.source.tree.MethodTree
getBound() - Method in interface com.sun.source.tree.WildcardTree
getBounds() - Method in interface com.sun.source.tree.TypeParameterTree
getCases() - Method in interface com.sun.source.tree.SwitchTree
getCatches() - Method in interface com.sun.source.tree.TryTree
getClassBody() - Method in interface com.sun.source.tree.NewClassTree
getColumnNumber(long) - Method in interface com.sun.source.tree.LineMap
Find the column for a character position.
getCompilationUnit() - Method in class com.sun.source.util.TaskEvent
getCompilationUnit() - Method in class com.sun.source.util.TreePath
Get the compilation unit associated with this path.
getCondition() - Method in interface com.sun.source.tree.AssertTree
getCondition() - Method in interface com.sun.source.tree.ConditionalExpressionTree
getCondition() - Method in interface com.sun.source.tree.DoWhileLoopTree
getCondition() - Method in interface com.sun.source.tree.ForLoopTree
getCondition() - Method in interface com.sun.source.tree.IfTree
getCondition() - Method in interface com.sun.source.tree.WhileLoopTree
getCurrentPath() - Method in class com.sun.source.util.TreePathScanner
Get the current path for the node, as built up by the currently active set of scan calls.
getDefaultValue() - Method in interface com.sun.source.tree.MethodTree
getDetail() - Method in interface com.sun.source.tree.AssertTree
getDimensions() - Method in interface com.sun.source.tree.NewArrayTree
getElement(TreePath) - Method in class com.sun.source.util.Trees
Gets the Element for the Tree node identified by a given TreePath.
getElements() - Method in class com.sun.source.util.JavacTask
Get a utility object for dealing with program elements.
getElseStatement() - Method in interface com.sun.source.tree.IfTree
getEnclosingClass() - Method in interface com.sun.source.tree.Scope
Returns the innermost type element containing the position of this scope
getEnclosingExpression() - Method in interface com.sun.source.tree.NewClassTree
getEnclosingMethod() - Method in interface com.sun.source.tree.Scope
Returns the innermost executable element containing the position of this scope.
getEnclosingScope() - Method in interface com.sun.source.tree.Scope
Returns the enclosing scope.
getEndPosition(CompilationUnitTree, Tree) - Method in interface com.sun.source.util.SourcePositions
Gets the ending position of tree within file.
getErrorTrees() - Method in interface com.sun.source.tree.ErroneousTree
getExpression() - Method in interface com.sun.source.tree.ArrayAccessTree
getExpression() - Method in interface com.sun.source.tree.AssignmentTree
getExpression() - Method in interface com.sun.source.tree.CaseTree
getExpression() - Method in interface com.sun.source.tree.CompoundAssignmentTree
getExpression() - Method in interface com.sun.source.tree.EnhancedForLoopTree
getExpression() - Method in interface com.sun.source.tree.ExpressionStatementTree
getExpression() - Method in interface com.sun.source.tree.InstanceOfTree
getExpression() - Method in interface com.sun.source.tree.MemberSelectTree
getExpression() - Method in interface com.sun.source.tree.ParenthesizedTree
getExpression() - Method in interface com.sun.source.tree.ReturnTree
getExpression() - Method in interface com.sun.source.tree.SwitchTree
getExpression() - Method in interface com.sun.source.tree.SynchronizedTree
getExpression() - Method in interface com.sun.source.tree.ThrowTree
getExpression() - Method in interface com.sun.source.tree.TypeCastTree
getExpression() - Method in interface com.sun.source.tree.UnaryTree
getExtendsClause() - Method in interface com.sun.source.tree.ClassTree
getFalseExpression() - Method in interface com.sun.source.tree.ConditionalExpressionTree
getFinallyBlock() - Method in interface com.sun.source.tree.TryTree
getFlags() - Method in interface com.sun.source.tree.ModifiersTree
getIdentifier() - Method in interface com.sun.source.tree.MemberSelectTree
getIdentifier() - Method in interface com.sun.source.tree.NewClassTree
getImplementsClause() - Method in interface com.sun.source.tree.ClassTree
getImports() - Method in interface com.sun.source.tree.CompilationUnitTree
getIndex() - Method in interface com.sun.source.tree.ArrayAccessTree
getInitializer() - Method in interface com.sun.source.tree.ForLoopTree
getInitializer() - Method in interface com.sun.source.tree.VariableTree
getInitializers() - Method in interface com.sun.source.tree.NewArrayTree
getKind() - Method in interface com.sun.source.tree.Tree
Gets the kind of this tree.
getKind() - Method in class com.sun.source.util.TaskEvent
getLabel() - Method in interface com.sun.source.tree.BreakTree
getLabel() - Method in interface com.sun.source.tree.ContinueTree
getLabel() - Method in interface com.sun.source.tree.LabeledStatementTree
getLeaf() - Method in class com.sun.source.util.TreePath
Get the leaf node for this path.
getLeftOperand() - Method in interface com.sun.source.tree.BinaryTree
getLineMap() - Method in interface com.sun.source.tree.CompilationUnitTree
Gets the line map for this compilation unit, if available.
getLineNumber(long) - Method in interface com.sun.source.tree.LineMap
Find the line containing a position; a line termination character is on the line it terminates.
getLocalElements() - Method in interface com.sun.source.tree.Scope
Returns the elements directly contained in this scope.
getMembers() - Method in interface com.sun.source.tree.ClassTree
getMethodSelect() - Method in interface com.sun.source.tree.MethodInvocationTree
getModifiers() - Method in interface com.sun.source.tree.ClassTree
getModifiers() - Method in interface com.sun.source.tree.MethodTree
getModifiers() - Method in interface com.sun.source.tree.VariableTree
getName() - Method in interface com.sun.source.tree.IdentifierTree
getName() - Method in interface com.sun.source.tree.MethodTree
getName() - Method in interface com.sun.source.tree.TypeParameterTree
getName() - Method in interface com.sun.source.tree.VariableTree
getPackageAnnotations() - Method in interface com.sun.source.tree.CompilationUnitTree
getPackageName() - Method in interface com.sun.source.tree.CompilationUnitTree
getParameter() - Method in interface com.sun.source.tree.CatchTree
getParameters() - Method in interface com.sun.source.tree.MethodTree
getParentPath() - Method in class com.sun.source.util.TreePath
Get the path for the enclosing node, or null if there is no enclosing node.
getPath(CompilationUnitTree, Tree) - Static method in class com.sun.source.util.TreePath
Gets a tree path for a tree node within a compilation unit.
getPath(TreePath, Tree) - Static method in class com.sun.source.util.TreePath
Gets a tree path for a tree node within a subtree identified by a TreePath object.
getPath(CompilationUnitTree, Tree) - Method in class com.sun.source.util.Trees
Gets the path to tree node within the specified compilation unit.
getPath(Element) - Method in class com.sun.source.util.Trees
Gets the TreePath node for a given Element.
getPath(Element, AnnotationMirror) - Method in class com.sun.source.util.Trees
Gets the TreePath node for an AnnotationMirror on a given Element.
getPath(Element, AnnotationMirror, AnnotationValue) - Method in class com.sun.source.util.Trees
Gets the TreePath node for an AnnotationValue for an AnnotationMirror on a given Element.
getPosition(long, long) - Method in interface com.sun.source.tree.LineMap
Find the position corresponding to a (line,column).
getPrimitiveTypeKind() - Method in interface com.sun.source.tree.PrimitiveTypeTree
getQualifiedIdentifier() - Method in interface com.sun.source.tree.ImportTree
getReturnType() - Method in interface com.sun.source.tree.MethodTree
getRightOperand() - Method in interface com.sun.source.tree.BinaryTree
getScope(TreePath) - Method in class com.sun.source.util.Trees
Gets the Scope for the Tree node identified by a given TreePath.
getSimpleName() - Method in interface com.sun.source.tree.ClassTree
getSourceFile() - Method in interface com.sun.source.tree.CompilationUnitTree
getSourceFile() - Method in class com.sun.source.util.TaskEvent
getSourcePositions() - Method in class com.sun.source.util.Trees
Gets a utility object for obtaining source positions.
getStartPosition(long) - Method in interface com.sun.source.tree.LineMap
Find the start position of a line.
getStartPosition(CompilationUnitTree, Tree) - Method in interface com.sun.source.util.SourcePositions
Gets the starting position of tree within file.
getStatement() - Method in interface com.sun.source.tree.DoWhileLoopTree
getStatement() - Method in interface com.sun.source.tree.EnhancedForLoopTree
getStatement() - Method in interface com.sun.source.tree.ForLoopTree
getStatement() - Method in interface com.sun.source.tree.LabeledStatementTree
getStatement() - Method in interface com.sun.source.tree.WhileLoopTree
getStatements() - Method in interface com.sun.source.tree.BlockTree
getStatements() - Method in interface com.sun.source.tree.CaseTree
getThenStatement() - Method in interface com.sun.source.tree.IfTree
getThrows() - Method in interface com.sun.source.tree.MethodTree
getTree(Element) - Method in class com.sun.source.util.Trees
Gets the Tree node for a given Element.
getTree(TypeElement) - Method in class com.sun.source.util.Trees
Gets the ClassTree node for a given TypeElement.
getTree(ExecutableElement) - Method in class com.sun.source.util.Trees
Gets the MethodTree node for a given ExecutableElement.
getTree(Element, AnnotationMirror) - Method in class com.sun.source.util.Trees
Gets the Tree node for an AnnotationMirror on a given Element.
getTree(Element, AnnotationMirror, AnnotationValue) - Method in class com.sun.source.util.Trees
Gets the Tree node for an AnnotationValue for an AnnotationMirror on a given Element.
getTrueExpression() - Method in interface com.sun.source.tree.ConditionalExpressionTree
getType() - Method in interface com.sun.source.tree.ArrayTypeTree
getType() - Method in interface com.sun.source.tree.InstanceOfTree
getType() - Method in interface com.sun.source.tree.NewArrayTree
getType() - Method in interface com.sun.source.tree.ParameterizedTypeTree
getType() - Method in interface com.sun.source.tree.TypeCastTree
getType() - Method in interface com.sun.source.tree.VariableTree
getTypeArguments() - Method in interface com.sun.source.tree.MethodInvocationTree
getTypeArguments() - Method in interface com.sun.source.tree.NewClassTree
getTypeArguments() - Method in interface com.sun.source.tree.ParameterizedTypeTree
getTypeDecls() - Method in interface com.sun.source.tree.CompilationUnitTree
getTypeElement() - Method in class com.sun.source.util.TaskEvent
getTypeMirror(Iterable<? extends Tree>) - Method in class com.sun.source.util.JavacTask
Get a type mirror of the tree node determined by the specified path.
getTypeMirror(TreePath) - Method in class com.sun.source.util.Trees
Gets the TypeMirror for the Tree node identified by a given TreePath.
getTypeParameters() - Method in interface com.sun.source.tree.ClassTree
getTypeParameters() - Method in interface com.sun.source.tree.MethodTree
getTypes() - Method in class com.sun.source.util.JavacTask
Get a utility object for dealing with type mirrors.
getUpdate() - Method in interface com.sun.source.tree.ForLoopTree
getValue() - Method in interface com.sun.source.tree.LiteralTree
getVariable() - Method in interface com.sun.source.tree.AssignmentTree
getVariable() - Method in interface com.sun.source.tree.CompoundAssignmentTree
getVariable() - Method in interface com.sun.source.tree.EnhancedForLoopTree

I

IdentifierTree - Interface in com.sun.source.tree
A tree node for an identifier expression.
IfTree - Interface in com.sun.source.tree
A tree node for an 'if' statement.
ImportTree - Interface in com.sun.source.tree
A tree node for an import statement.
instance(JavaCompiler.CompilationTask) - Static method in class com.sun.source.util.Trees
Gets a Trees object for a given CompilationTask.
instance(ProcessingEnvironment) - Static method in class com.sun.source.util.Trees
Gets a Trees object for a given CompilationTask.
InstanceOfTree - Interface in com.sun.source.tree
A tree node for an 'instanceof' expression.
isAccessible(Scope, TypeElement) - Method in class com.sun.source.util.Trees
Checks whether a given type is accessible in a given scope.
isAccessible(Scope, Element, DeclaredType) - Method in class com.sun.source.util.Trees
Checks whether the given element is accessible as a member of the given type in a given scope.
isStatic() - Method in interface com.sun.source.tree.BlockTree
isStatic() - Method in interface com.sun.source.tree.ImportTree
iterator() - Method in class com.sun.source.util.TreePath

J

JavacTask - Class in com.sun.source.util
Provides access to functionality specific to the Sun Java Compiler, javac.
JavacTask() - Constructor for class com.sun.source.util.JavacTask

L

LabeledStatementTree - Interface in com.sun.source.tree
A tree node for a labeled statement.
LineMap - Interface in com.sun.source.tree
Provides methods to convert between character positions and line numbers for a compilation unit.
LiteralTree - Interface in com.sun.source.tree
A tree node for a literal expression.

M

MemberSelectTree - Interface in com.sun.source.tree
A tree node for a member access expression.
MethodInvocationTree - Interface in com.sun.source.tree
A tree node for a method invocation expression.
MethodTree - Interface in com.sun.source.tree
A tree node for a method or annotation type element declaration.
ModifiersTree - Interface in com.sun.source.tree
A tree node for the modifiers, including annotations, for a declaration.

N

NewArrayTree - Interface in com.sun.source.tree
A tree node for an expression to create a new instance of an array.
NewClassTree - Interface in com.sun.source.tree
A tree node to declare a new instance of a class.

P

ParameterizedTypeTree - Interface in com.sun.source.tree
A tree node for a type expression involving type parameters.
ParenthesizedTree - Interface in com.sun.source.tree
A tree node for a parenthesized expression.
parse() - Method in class com.sun.source.util.JavacTask
Parse the specified files returning a list of abstract syntax trees.
PrimitiveTypeTree - Interface in com.sun.source.tree
A tree node for a primitive type.

R

reduce(R, R) - Method in class com.sun.source.util.TreeScanner
Reduces two results into a combined result.
ReturnTree - Interface in com.sun.source.tree
A tree node for a 'return' statement.

S

scan(TreePath, P) - Method in class com.sun.source.util.TreePathScanner
Scan a tree from a position identified by a TreePath.
scan(Tree, P) - Method in class com.sun.source.util.TreePathScanner
Scan a single node.
scan(Tree, P) - Method in class com.sun.source.util.TreeScanner
Scan a single node.
scan(Iterable<? extends Tree>, P) - Method in class com.sun.source.util.TreeScanner
Scan a list of nodes.
Scope - Interface in com.sun.source.tree
Interface for determining locally available program elements, such as local variables and imports.
setTaskListener(TaskListener) - Method in class com.sun.source.util.JavacTask
The specified listener will receive events describing the progress of this compilation task.
SimpleTreeVisitor<R,P> - Class in com.sun.source.util
A simple visitor for tree nodes.
SimpleTreeVisitor() - Constructor for class com.sun.source.util.SimpleTreeVisitor
SimpleTreeVisitor(R) - Constructor for class com.sun.source.util.SimpleTreeVisitor
SourcePositions - Interface in com.sun.source.util
Provides methods to obtain the position of a Tree within a CompilationUnit.
started(TaskEvent) - Method in interface com.sun.source.util.TaskListener
StatementTree - Interface in com.sun.source.tree
A tree node used as the base class for the different kinds of statements.
SwitchTree - Interface in com.sun.source.tree
A tree node for a 'switch' statement.
SynchronizedTree - Interface in com.sun.source.tree
A tree node for a 'synchronized' statement.

T

TaskEvent - Class in com.sun.source.util
Provides details about work that has been done by the Sun Java Compiler, javac.
TaskEvent(TaskEvent.Kind) - Constructor for class com.sun.source.util.TaskEvent
TaskEvent(TaskEvent.Kind, JavaFileObject) - Constructor for class com.sun.source.util.TaskEvent
TaskEvent(TaskEvent.Kind, CompilationUnitTree) - Constructor for class com.sun.source.util.TaskEvent
TaskEvent(TaskEvent.Kind, CompilationUnitTree, TypeElement) - Constructor for class com.sun.source.util.TaskEvent
TaskEvent.Kind - Enum in com.sun.source.util
Kind of task event.
TaskListener - Interface in com.sun.source.util
Provides a listener to monitor the activity of the Sun Java Compiler, javac.
ThrowTree - Interface in com.sun.source.tree
A tree node for a 'throw' statement.
toString() - Method in class com.sun.source.util.TaskEvent
Tree - Interface in com.sun.source.tree
Common interface for all nodes in an abstract syntax tree.
Tree.Kind - Enum in com.sun.source.tree
Enumerates all kinds of trees.
TreePath - Class in com.sun.source.util
A path of tree nodes, typically used to represent the sequence of ancestor nodes of a tree node up to the top level CompilationUnitTree node.
TreePath(CompilationUnitTree) - Constructor for class com.sun.source.util.TreePath
Creates a TreePath for a root node.
TreePath(TreePath, Tree) - Constructor for class com.sun.source.util.TreePath
Creates a TreePath for a child node.
TreePathScanner<R,P> - Class in com.sun.source.util
A TreeVisitor that visits all the child tree nodes, and provides support for maintaining a path for the parent nodes.
TreePathScanner() - Constructor for class com.sun.source.util.TreePathScanner
Trees - Class in com.sun.source.util
Bridges JSR 199, JSR 269, and the Tree API.
Trees() - Constructor for class com.sun.source.util.Trees
TreeScanner<R,P> - Class in com.sun.source.util
A TreeVisitor that visits all the child tree nodes.
TreeScanner() - Constructor for class com.sun.source.util.TreeScanner
TreeVisitor<R,P> - Interface in com.sun.source.tree
A visitor of trees, in the style of the visitor design pattern.
TryTree - Interface in com.sun.source.tree
A tree node for a 'try' statement.
TypeCastTree - Interface in com.sun.source.tree
A tree node for a type cast expression.
TypeParameterTree - Interface in com.sun.source.tree
A tree node for a type parameter.

U

UnaryTree - Interface in com.sun.source.tree
A tree node for postfix and unary expressions.

V

valueOf(String) - Static method in enum com.sun.source.tree.Tree.Kind
Returns the enum constant of this type with the specified name.
valueOf(String) - Static method in enum com.sun.source.util.TaskEvent.Kind
Returns the enum constant of this type with the specified name.
values() - Static method in enum com.sun.source.tree.Tree.Kind
Returns an array containing the constants of this enum type, in the order they are declared.
values() - Static method in enum com.sun.source.util.TaskEvent.Kind
Returns an array containing the constants of this enum type, in the order they are declared.
VariableTree - Interface in com.sun.source.tree
A tree node for a variable declaration.
visit(Tree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visit(Iterable<? extends Tree>, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitAnnotation(AnnotationTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitAnnotation(AnnotationTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitAnnotation(AnnotationTree, P) - Method in class com.sun.source.util.TreeScanner
visitArrayAccess(ArrayAccessTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitArrayAccess(ArrayAccessTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitArrayAccess(ArrayAccessTree, P) - Method in class com.sun.source.util.TreeScanner
visitArrayType(ArrayTypeTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitArrayType(ArrayTypeTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitArrayType(ArrayTypeTree, P) - Method in class com.sun.source.util.TreeScanner
visitAssert(AssertTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitAssert(AssertTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitAssert(AssertTree, P) - Method in class com.sun.source.util.TreeScanner
visitAssignment(AssignmentTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitAssignment(AssignmentTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitAssignment(AssignmentTree, P) - Method in class com.sun.source.util.TreeScanner
visitBinary(BinaryTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitBinary(BinaryTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitBinary(BinaryTree, P) - Method in class com.sun.source.util.TreeScanner
visitBlock(BlockTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitBlock(BlockTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitBlock(BlockTree, P) - Method in class com.sun.source.util.TreeScanner
visitBreak(BreakTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitBreak(BreakTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitBreak(BreakTree, P) - Method in class com.sun.source.util.TreeScanner
visitCase(CaseTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitCase(CaseTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitCase(CaseTree, P) - Method in class com.sun.source.util.TreeScanner
visitCatch(CatchTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitCatch(CatchTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitCatch(CatchTree, P) - Method in class com.sun.source.util.TreeScanner
visitClass(ClassTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitClass(ClassTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitClass(ClassTree, P) - Method in class com.sun.source.util.TreeScanner
visitCompilationUnit(CompilationUnitTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitCompilationUnit(CompilationUnitTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitCompilationUnit(CompilationUnitTree, P) - Method in class com.sun.source.util.TreeScanner
visitCompoundAssignment(CompoundAssignmentTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitCompoundAssignment(CompoundAssignmentTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitCompoundAssignment(CompoundAssignmentTree, P) - Method in class com.sun.source.util.TreeScanner
visitConditionalExpression(ConditionalExpressionTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitConditionalExpression(ConditionalExpressionTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitConditionalExpression(ConditionalExpressionTree, P) - Method in class com.sun.source.util.TreeScanner
visitContinue(ContinueTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitContinue(ContinueTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitContinue(ContinueTree, P) - Method in class com.sun.source.util.TreeScanner
visitDoWhileLoop(DoWhileLoopTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitDoWhileLoop(DoWhileLoopTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitDoWhileLoop(DoWhileLoopTree, P) - Method in class com.sun.source.util.TreeScanner
visitEmptyStatement(EmptyStatementTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitEmptyStatement(EmptyStatementTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitEmptyStatement(EmptyStatementTree, P) - Method in class com.sun.source.util.TreeScanner
visitEnhancedForLoop(EnhancedForLoopTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitEnhancedForLoop(EnhancedForLoopTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitEnhancedForLoop(EnhancedForLoopTree, P) - Method in class com.sun.source.util.TreeScanner
visitErroneous(ErroneousTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitErroneous(ErroneousTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitErroneous(ErroneousTree, P) - Method in class com.sun.source.util.TreeScanner
visitExpressionStatement(ExpressionStatementTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitExpressionStatement(ExpressionStatementTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitExpressionStatement(ExpressionStatementTree, P) - Method in class com.sun.source.util.TreeScanner
visitForLoop(ForLoopTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitForLoop(ForLoopTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitForLoop(ForLoopTree, P) - Method in class com.sun.source.util.TreeScanner
visitIdentifier(IdentifierTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitIdentifier(IdentifierTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitIdentifier(IdentifierTree, P) - Method in class com.sun.source.util.TreeScanner
visitIf(IfTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitIf(IfTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitIf(IfTree, P) - Method in class com.sun.source.util.TreeScanner
visitImport(ImportTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitImport(ImportTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitImport(ImportTree, P) - Method in class com.sun.source.util.TreeScanner
visitInstanceOf(InstanceOfTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitInstanceOf(InstanceOfTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitInstanceOf(InstanceOfTree, P) - Method in class com.sun.source.util.TreeScanner
visitLabeledStatement(LabeledStatementTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitLabeledStatement(LabeledStatementTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitLabeledStatement(LabeledStatementTree, P) - Method in class com.sun.source.util.TreeScanner
visitLiteral(LiteralTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitLiteral(LiteralTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitLiteral(LiteralTree, P) - Method in class com.sun.source.util.TreeScanner
visitMemberSelect(MemberSelectTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitMemberSelect(MemberSelectTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitMemberSelect(MemberSelectTree, P) - Method in class com.sun.source.util.TreeScanner
visitMethod(MethodTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitMethod(MethodTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitMethod(MethodTree, P) - Method in class com.sun.source.util.TreeScanner
visitMethodInvocation(MethodInvocationTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitMethodInvocation(MethodInvocationTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitMethodInvocation(MethodInvocationTree, P) - Method in class com.sun.source.util.TreeScanner
visitModifiers(ModifiersTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitModifiers(ModifiersTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitModifiers(ModifiersTree, P) - Method in class com.sun.source.util.TreeScanner
visitNewArray(NewArrayTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitNewArray(NewArrayTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitNewArray(NewArrayTree, P) - Method in class com.sun.source.util.TreeScanner
visitNewClass(NewClassTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitNewClass(NewClassTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitNewClass(NewClassTree, P) - Method in class com.sun.source.util.TreeScanner
visitOther(Tree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitOther(Tree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitOther(Tree, P) - Method in class com.sun.source.util.TreeScanner
visitParameterizedType(ParameterizedTypeTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitParameterizedType(ParameterizedTypeTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitParameterizedType(ParameterizedTypeTree, P) - Method in class com.sun.source.util.TreeScanner
visitParenthesized(ParenthesizedTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitParenthesized(ParenthesizedTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitParenthesized(ParenthesizedTree, P) - Method in class com.sun.source.util.TreeScanner
visitPrimitiveType(PrimitiveTypeTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitPrimitiveType(PrimitiveTypeTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitPrimitiveType(PrimitiveTypeTree, P) - Method in class com.sun.source.util.TreeScanner
visitReturn(ReturnTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitReturn(ReturnTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitReturn(ReturnTree, P) - Method in class com.sun.source.util.TreeScanner
visitSwitch(SwitchTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitSwitch(SwitchTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitSwitch(SwitchTree, P) - Method in class com.sun.source.util.TreeScanner
visitSynchronized(SynchronizedTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitSynchronized(SynchronizedTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitSynchronized(SynchronizedTree, P) - Method in class com.sun.source.util.TreeScanner
visitThrow(ThrowTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitThrow(ThrowTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitThrow(ThrowTree, P) - Method in class com.sun.source.util.TreeScanner
visitTry(TryTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitTry(TryTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitTry(TryTree, P) - Method in class com.sun.source.util.TreeScanner
visitTypeCast(TypeCastTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitTypeCast(TypeCastTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitTypeCast(TypeCastTree, P) - Method in class com.sun.source.util.TreeScanner
visitTypeParameter(TypeParameterTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitTypeParameter(TypeParameterTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitTypeParameter(TypeParameterTree, P) - Method in class com.sun.source.util.TreeScanner
visitUnary(UnaryTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitUnary(UnaryTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitUnary(UnaryTree, P) - Method in class com.sun.source.util.TreeScanner
visitVariable(VariableTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitVariable(VariableTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitVariable(VariableTree, P) - Method in class com.sun.source.util.TreeScanner
visitWhileLoop(WhileLoopTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitWhileLoop(WhileLoopTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitWhileLoop(WhileLoopTree, P) - Method in class com.sun.source.util.TreeScanner
visitWildcard(WildcardTree, P) - Method in interface com.sun.source.tree.TreeVisitor
visitWildcard(WildcardTree, P) - Method in class com.sun.source.util.SimpleTreeVisitor
visitWildcard(WildcardTree, P) - Method in class com.sun.source.util.TreeScanner

W

WhileLoopTree - Interface in com.sun.source.tree
A tree node for a 'while' loop statement.
WildcardTree - Interface in com.sun.source.tree
A tree node for a wildcard type argument.
A B C D E F G I J L M N P R S T U V W
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


tree

Compiler Tree API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package com.sun.source.tree

Provides interfaces to represent source code as abstract syntax trees (AST).

See:
Description

Interface Summary
AnnotationTree | A tree node for an annotation.
ArrayAccessTree | A tree node for an array access expression.
ArrayTypeTree | A tree node for an array type.
AssertTree | A tree node for an 'assert' statement.
AssignmentTree | A tree node for an assignment expression.
BinaryTree | A tree node for a binary expression.
BlockTree | A tree node for a statement block.
BreakTree | A tree node for a 'break' statement.
CaseTree | A tree node for a 'case' in a 'switch' statement.
CatchTree | A tree node for a 'catch' block in a 'try' statement.
ClassTree | A tree node for a class, interface, enum, or annotation type declaration.
CompilationUnitTree | Represents the abstract syntax tree for compilation units (source files) and package declarations (package-info.java).
CompoundAssignmentTree | A tree node for compound assignment operator.
ConditionalExpressionTree | A tree node for the conditional operator ? :.
ContinueTree | A tree node for a 'continue' statement.
DoWhileLoopTree | A tree node for a 'do' statement.
EmptyStatementTree | A tree node for an empty (skip) statement.
EnhancedForLoopTree | A tree node for an "enhanced" 'for' loop statement.
ErroneousTree | A tree node to stand in for a malformed expression.
ExpressionStatementTree | A tree node for an expression statement.
ExpressionTree | A tree node used as the base class for the different types of expressions.
ForLoopTree | A tree node for a basic 'for' loop statement.
IdentifierTree | A tree node for an identifier expression.
IfTree | A tree node for an 'if' statement.
ImportTree | A tree node for an import statement.
InstanceOfTree | A tree node for an 'instanceof' expression.
LabeledStatementTree | A tree node for a labeled statement.
LineMap | Provides methods to convert between character positions and line numbers for a compilation unit.
LiteralTree | A tree node for a literal expression.
MemberSelectTree | A tree node for a member access expression.
MethodInvocationTree | A tree node for a method invocation expression.
MethodTree | A tree node for a method or annotation type element declaration.
ModifiersTree | A tree node for the modifiers, including annotations, for a declaration.
NewArrayTree | A tree node for an expression to create a new instance of an array.
NewClassTree | A tree node to declare a new instance of a class.
ParameterizedTypeTree | A tree node for a type expression involving type parameters.
ParenthesizedTree | A tree node for a parenthesized expression.
PrimitiveTypeTree | A tree node for a primitive type.
ReturnTree | A tree node for a 'return' statement.
Scope | Interface for determining locally available program elements, such as local variables and imports.
StatementTree | A tree node used as the base class for the different kinds of statements.
SwitchTree | A tree node for a 'switch' statement.
SynchronizedTree | A tree node for a 'synchronized' statement.
ThrowTree | A tree node for a 'throw' statement.
Tree | Common interface for all nodes in an abstract syntax tree.
TreeVisitor<R,P> | A visitor of trees, in the style of the visitor design pattern.
TryTree | A tree node for a 'try' statement.
TypeCastTree | A tree node for a type cast expression.
TypeParameterTree | A tree node for a type parameter.
UnaryTree | A tree node for postfix and unary expressions.
VariableTree | A tree node for a variable declaration.
WhileLoopTree | A tree node for a 'while' loop statement.
WildcardTree | A tree node for a wildcard type argument.

Enum Summary
Tree.Kind Enumerates all kinds of trees.

Package com.sun.source.tree Description

Provides interfaces to represent source code as abstract syntax trees (AST).

Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


com.sun.source.tree Class Hierarchy

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Hierarchy For Package com.sun.source.tree

Package Hierarchies:
All Packages

Interface Hierarchy

  • com.sun.source.tree.LineMap
  • com.sun.source.tree.Scope
  • com.sun.source.tree.Tree
    • com.sun.source.tree.ArrayTypeTree
    • com.sun.source.tree.CaseTree
    • com.sun.source.tree.CatchTree
    • com.sun.source.tree.CompilationUnitTree
    • com.sun.source.tree.ExpressionTree
      • com.sun.source.tree.AnnotationTree
      • com.sun.source.tree.ArrayAccessTree
      • com.sun.source.tree.AssignmentTree
      • com.sun.source.tree.BinaryTree
      • com.sun.source.tree.CompoundAssignmentTree
      • com.sun.source.tree.ConditionalExpressionTree
      • com.sun.source.tree.ErroneousTree
      • com.sun.source.tree.IdentifierTree
      • com.sun.source.tree.InstanceOfTree
      • com.sun.source.tree.LiteralTree
      • com.sun.source.tree.MemberSelectTree
      • com.sun.source.tree.MethodInvocationTree
      • com.sun.source.tree.NewArrayTree
      • com.sun.source.tree.NewClassTree
      • com.sun.source.tree.ParenthesizedTree
      • com.sun.source.tree.TypeCastTree
      • com.sun.source.tree.UnaryTree
    • com.sun.source.tree.ImportTree
    • com.sun.source.tree.MethodTree
    • com.sun.source.tree.ModifiersTree
    • com.sun.source.tree.ParameterizedTypeTree
    • com.sun.source.tree.PrimitiveTypeTree
    • com.sun.source.tree.StatementTree
      • com.sun.source.tree.AssertTree
      • com.sun.source.tree.BlockTree
      • com.sun.source.tree.BreakTree
      • com.sun.source.tree.ClassTree
      • com.sun.source.tree.ContinueTree
      • com.sun.source.tree.DoWhileLoopTree
      • com.sun.source.tree.EmptyStatementTree
      • com.sun.source.tree.EnhancedForLoopTree
      • com.sun.source.tree.ExpressionStatementTree
      • com.sun.source.tree.ForLoopTree
      • com.sun.source.tree.IfTree
      • com.sun.source.tree.LabeledStatementTree
      • com.sun.source.tree.ReturnTree
      • com.sun.source.tree.SwitchTree
      • com.sun.source.tree.SynchronizedTree
      • com.sun.source.tree.ThrowTree
      • com.sun.source.tree.TryTree
      • com.sun.source.tree.VariableTree
      • com.sun.source.tree.WhileLoopTree
    • com.sun.source.tree.TypeParameterTree
    • com.sun.source.tree.WildcardTree
  • com.sun.source.tree.TreeVisitor<R,P>

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • com.sun.source.tree.Tree.Kind
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Package com.sun.source.tree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Package
com.sun.source.tree

Packages that use com.sun.source.tree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Classes in com.sun.source.tree used by com.sun.source.tree
AnnotationTree
A tree node for an annotation.
ArrayAccessTree
A tree node for an array access expression.
ArrayTypeTree
A tree node for an array type.
AssertTree
A tree node for an 'assert' statement.
AssignmentTree
A tree node for an assignment expression.
BinaryTree
A tree node for a binary expression.
BlockTree
A tree node for a statement block.
BreakTree
A tree node for a 'break' statement.
CaseTree
A tree node for a 'case' in a 'switch' statement.
CatchTree
A tree node for a 'catch' block in a 'try' statement.
ClassTree
A tree node for a class, interface, enum, or annotation type declaration.
CompilationUnitTree
Represents the abstract syntax tree for compilation units (source files) and package declarations (package-info.java).
CompoundAssignmentTree
A tree node for compound assignment operator.
ConditionalExpressionTree
A tree node for the conditional operator ? :.
ContinueTree
A tree node for a 'continue' statement.
DoWhileLoopTree
A tree node for a 'do' statement.
EmptyStatementTree
A tree node for an empty (skip) statement.
EnhancedForLoopTree
A tree node for an "enhanced" 'for' loop statement.
ErroneousTree
A tree node to stand in for a malformed expression.
ExpressionStatementTree
A tree node for an expression statement.
ExpressionTree
A tree node used as the base class for the different types of expressions.
ForLoopTree
A tree node for a basic 'for' loop statement.
IdentifierTree
A tree node for an identifier expression.
IfTree
A tree node for an 'if' statement.
ImportTree
A tree node for an import statement.
InstanceOfTree
A tree node for an 'instanceof' expression.
LabeledStatementTree
A tree node for a labeled statement.
LineMap
Provides methods to convert between character positions and line numbers for a compilation unit.
LiteralTree
A tree node for a literal expression.
MemberSelectTree
A tree node for a member access expression.
MethodInvocationTree
A tree node for a method invocation expression.
MethodTree
A tree node for a method or annotation type element declaration.
ModifiersTree
A tree node for the modifiers, including annotations, for a declaration.
NewArrayTree
A tree node for an expression to create a new instance of an array.
NewClassTree
A tree node to declare a new instance of a class.
ParameterizedTypeTree
A tree node for a type expression involving type parameters.
ParenthesizedTree
A tree node for a parenthesized expression.
PrimitiveTypeTree
A tree node for a primitive type.
ReturnTree
A tree node for a 'return' statement.
Scope
Interface for determining locally available program elements, such as local variables and imports.
StatementTree
A tree node used as the base class for the different kinds of statements.
SwitchTree
A tree node for a 'switch' statement.
SynchronizedTree
A tree node for a 'synchronized' statement.
ThrowTree
A tree node for a 'throw' statement.
Tree
Common interface for all nodes in an abstract syntax tree.
Tree.Kind
Enumerates all kinds of trees.
TreeVisitor
A visitor of trees, in the style of the visitor design pattern.
TryTree
A tree node for a 'try' statement.
TypeCastTree
A tree node for a type cast expression.
TypeParameterTree
A tree node for a type parameter.
UnaryTree
A tree node for postfix and unary expressions.
VariableTree
A tree node for a variable declaration.
WhileLoopTree
A tree node for a 'while' loop statement.
WildcardTree
A tree node for a wildcard type argument.

Classes in com.sun.source.tree used by com.sun.source.util
AnnotationTree
A tree node for an annotation.
ArrayAccessTree
A tree node for an array access expression.
ArrayTypeTree
A tree node for an array type.
AssertTree
A tree node for an 'assert' statement.
AssignmentTree
A tree node for an assignment expression.
BinaryTree
A tree node for a binary expression.
BlockTree
A tree node for a statement block.
BreakTree
A tree node for a 'break' statement.
CaseTree
A tree node for a 'case' in a 'switch' statement.
CatchTree
A tree node for a 'catch' block in a 'try' statement.
ClassTree
A tree node for a class, interface, enum, or annotation type declaration.
CompilationUnitTree
Represents the abstract syntax tree for compilation units (source files) and package declarations (package-info.java).
CompoundAssignmentTree
A tree node for compound assignment operator.
ConditionalExpressionTree
A tree node for the conditional operator ? :.
ContinueTree
A tree node for a 'continue' statement.
DoWhileLoopTree
A tree node for a 'do' statement.
EmptyStatementTree
A tree node for an empty (skip) statement.
EnhancedForLoopTree
A tree node for an "enhanced" 'for' loop statement.
ErroneousTree
A tree node to stand in for a malformed expression.
ExpressionStatementTree
A tree node for an expression statement.
ForLoopTree
A tree node for a basic 'for' loop statement.
IdentifierTree
A tree node for an identifier expression.
IfTree
A tree node for an 'if' statement.
ImportTree
A tree node for an import statement.
InstanceOfTree
A tree node for an 'instanceof' expression.
LabeledStatementTree
A tree node for a labeled statement.
LiteralTree
A tree node for a literal expression.
MemberSelectTree
A tree node for a member access expression.
MethodInvocationTree
A tree node for a method invocation expression.
MethodTree
A tree node for a method or annotation type element declaration.
ModifiersTree
A tree node for the modifiers, including annotations, for a declaration.
NewArrayTree
A tree node for an expression to create a new instance of an array.
NewClassTree
A tree node to declare a new instance of a class.
ParameterizedTypeTree
A tree node for a type expression involving type parameters.
ParenthesizedTree
A tree node for a parenthesized expression.
PrimitiveTypeTree
A tree node for a primitive type.
ReturnTree
A tree node for a 'return' statement.
Scope
Interface for determining locally available program elements, such as local variables and imports.
SwitchTree
A tree node for a 'switch' statement.
SynchronizedTree
A tree node for a 'synchronized' statement.
ThrowTree
A tree node for a 'throw' statement.
Tree
Common interface for all nodes in an abstract syntax tree.
TreeVisitor
A visitor of trees, in the style of the visitor design pattern.
TryTree
A tree node for a 'try' statement.
TypeCastTree
A tree node for a type cast expression.
TypeParameterTree
A tree node for a type parameter.
UnaryTree
A tree node for postfix and unary expressions.
VariableTree
A tree node for a variable declaration.
WhileLoopTree
A tree node for a 'while' loop statement.
WildcardTree
A tree node for a wildcard type argument.

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


AnnotationTree

Compiler Tree API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface AnnotationTree

All Superinterfaces:
ExpressionTree, Tree
public interface AnnotationTree
extends ExpressionTree

A tree node for an annotation. For example:

    @annotationType
    @annotationType ( arguments )

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 9.7"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
Tree | getAnnotationType()
List<? extends ExpressionTree> | getArguments()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getAnnotationType

Tree getAnnotationType()

getArguments

List<? extends ExpressionTree> getArguments()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ArrayAccessTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface ArrayAccessTree

All Superinterfaces:
ExpressionTree, Tree
public interface ArrayAccessTree
extends ExpressionTree

A tree node for an array access expression. For example:

   expression [ index ]

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 15.13"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
ExpressionTree | getExpression()
ExpressionTree | getIndex()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getExpression

ExpressionTree getExpression()

getIndex

ExpressionTree getIndex()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ArrayTypeTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface ArrayTypeTree

All Superinterfaces:
Tree
public interface ArrayTypeTree
extends Tree

A tree node for an array type. For example:

   type []

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 10.1"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
 Tree getType()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getType

Tree getType()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


AssertTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface AssertTree

All Superinterfaces:
StatementTree, Tree
public interface AssertTree
extends StatementTree

A tree node for an 'assert' statement. For example:

   assert condition ;

   assert condition : detail ;

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.10"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
ExpressionTree | getCondition()
ExpressionTree | getDetail()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getCondition

ExpressionTree getCondition()

getDetail

ExpressionTree getDetail()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


AssignmentTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface AssignmentTree

All Superinterfaces:
ExpressionTree, Tree
public interface AssignmentTree
extends ExpressionTree

A tree node for an assignment expression. For example:

   variable = expression

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 15.26.1"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
ExpressionTree | getExpression()
ExpressionTree | getVariable()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getVariable

ExpressionTree getVariable()

getExpression

ExpressionTree getExpression()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


BinaryTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface BinaryTree

All Superinterfaces:
ExpressionTree, Tree
public interface BinaryTree
extends ExpressionTree

A tree node for a binary expression. Use getKind to determine the kind of operator. For example:

   leftOperand operator rightOperand

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, sections 15.17 to 15.24"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
ExpressionTree | getLeftOperand()
ExpressionTree | getRightOperand()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getLeftOperand

ExpressionTree getLeftOperand()

getRightOperand

ExpressionTree getRightOperand()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


BlockTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface BlockTree

All Superinterfaces:
StatementTree, Tree
public interface BlockTree
extends StatementTree

A tree node for a statement block. For example:

   { }

   { statements }

   static { statements }

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.2"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
List<? extends StatementTree> | getStatements()
boolean | isStatic()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

isStatic

boolean isStatic()

getStatements

List<? extends StatementTree> getStatements()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


BreakTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface BreakTree

All Superinterfaces:
StatementTree, Tree
public interface BreakTree
extends StatementTree

A tree node for a 'break' statement. For example:

   break;

   break label ;

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.15"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
 Name getLabel()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getLabel

Name getLabel()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


CaseTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface CaseTree

All Superinterfaces:
Tree
public interface CaseTree
extends Tree

A tree node for a 'case' in a 'switch' statement. For example:

   case expression :
       statements

   default :
       statements

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.11"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
ExpressionTree | getExpression()
List<? extends StatementTree> | getStatements()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getExpression

ExpressionTree getExpression()
Returns:
null if and only if this Case is default:

getStatements

List<? extends StatementTree> getStatements()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


CatchTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface CatchTree

All Superinterfaces:
Tree
public interface CatchTree
extends Tree

A tree node for a 'catch' block in a 'try' statement. For example:

   catch ( parameter )
       block

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.20"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
BlockTree | getBlock()
VariableTree | getParameter()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getParameter

VariableTree getParameter()

getBlock

BlockTree getBlock()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.source.tree.Tree.Kind

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.source.tree.Tree.Kind

Packages that use Tree.Kind
com.sun.source.tree Provides interfaces to represent source code as abstract syntax trees (AST).

Uses of Tree.Kind in com.sun.source.tree

Methods in com.sun.source.tree that return Tree.Kind
Tree.Kind | Tree.getKind() Gets the kind of this tree.
static Tree.Kind | Tree.Kind.valueOf(String name) Returns the enum constant of this type with the specified name.
static Tree.Kind[] | Tree.Kind.values() Returns an array containing the constants of this enum type, in the order they are declared.

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.AnnotationTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.AnnotationTree

Packages that use AnnotationTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of AnnotationTree in com.sun.source.tree

Methods in com.sun.source.tree that return types with arguments of type AnnotationTree
List<? extends AnnotationTree> | ModifiersTree.getAnnotations()
List<? extends AnnotationTree> | CompilationUnitTree.getPackageAnnotations()

Methods in com.sun.source.tree with parameters of type AnnotationTree
 R TreeVisitor.visitAnnotation(AnnotationTree node, P p)

Uses of AnnotationTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type AnnotationTree
R | TreeScanner.visitAnnotation(AnnotationTree node, P p)
R | SimpleTreeVisitor.visitAnnotation(AnnotationTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.ArrayAccessTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.ArrayAccessTree

Packages that use ArrayAccessTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of ArrayAccessTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type ArrayAccessTree
 R TreeVisitor.visitArrayAccess(ArrayAccessTree node, P p)

Uses of ArrayAccessTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type ArrayAccessTree
R | TreeScanner.visitArrayAccess(ArrayAccessTree node, P p)
R | SimpleTreeVisitor.visitArrayAccess(ArrayAccessTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.ArrayTypeTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.ArrayTypeTree

Packages that use ArrayTypeTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of ArrayTypeTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type ArrayTypeTree
 R TreeVisitor.visitArrayType(ArrayTypeTree node, P p)

Uses of ArrayTypeTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type ArrayTypeTree
R | TreeScanner.visitArrayType(ArrayTypeTree node, P p)
R | SimpleTreeVisitor.visitArrayType(ArrayTypeTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.AssertTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.AssertTree

Packages that use AssertTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of AssertTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type AssertTree
 R TreeVisitor.visitAssert(AssertTree node, P p)

Uses of AssertTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type AssertTree
R | TreeScanner.visitAssert(AssertTree node, P p)
R | SimpleTreeVisitor.visitAssert(AssertTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.AssignmentTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.AssignmentTree

Packages that use AssignmentTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of AssignmentTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type AssignmentTree
 R TreeVisitor.visitAssignment(AssignmentTree node, P p)

Uses of AssignmentTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type AssignmentTree
R | TreeScanner.visitAssignment(AssignmentTree node, P p)
R | SimpleTreeVisitor.visitAssignment(AssignmentTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.BinaryTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.BinaryTree

Packages that use BinaryTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of BinaryTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type BinaryTree
 R TreeVisitor.visitBinary(BinaryTree node, P p)

Uses of BinaryTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type BinaryTree
R | TreeScanner.visitBinary(BinaryTree node, P p)
R | SimpleTreeVisitor.visitBinary(BinaryTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.BlockTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.BlockTree

Packages that use BlockTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of BlockTree in com.sun.source.tree

Methods in com.sun.source.tree that return BlockTree
BlockTree | CatchTree.getBlock()
BlockTree | TryTree.getBlock()
BlockTree | SynchronizedTree.getBlock()
BlockTree | MethodTree.getBody()
BlockTree | TryTree.getFinallyBlock()

Methods in com.sun.source.tree with parameters of type BlockTree
 R TreeVisitor.visitBlock(BlockTree node, P p)

Uses of BlockTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type BlockTree
R | TreeScanner.visitBlock(BlockTree node, P p)
R | SimpleTreeVisitor.visitBlock(BlockTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.BreakTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.BreakTree

Packages that use BreakTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of BreakTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type BreakTree
 R TreeVisitor.visitBreak(BreakTree node, P p)

Uses of BreakTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type BreakTree
R | TreeScanner.visitBreak(BreakTree node, P p)
R | SimpleTreeVisitor.visitBreak(BreakTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.CaseTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.CaseTree

Packages that use CaseTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of CaseTree in com.sun.source.tree

Methods in com.sun.source.tree that return types with arguments of type CaseTree
 List<? extends CaseTree> SwitchTree.getCases()

Methods in com.sun.source.tree with parameters of type CaseTree
 R TreeVisitor.visitCase(CaseTree node, P p)

Uses of CaseTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type CaseTree
R | TreeScanner.visitCase(CaseTree node, P p)
R | SimpleTreeVisitor.visitCase(CaseTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.CatchTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.CatchTree

Packages that use CatchTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of CatchTree in com.sun.source.tree

Methods in com.sun.source.tree that return types with arguments of type CatchTree
 List<? extends CatchTree> TryTree.getCatches()

Methods in com.sun.source.tree with parameters of type CatchTree
 R TreeVisitor.visitCatch(CatchTree node, P p)

Uses of CatchTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type CatchTree
R | TreeScanner.visitCatch(CatchTree node, P p)
R | SimpleTreeVisitor.visitCatch(CatchTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.ClassTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.ClassTree

Packages that use ClassTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of ClassTree in com.sun.source.tree

Methods in com.sun.source.tree that return ClassTree
 ClassTree NewClassTree.getClassBody()

Methods in com.sun.source.tree with parameters of type ClassTree
 R TreeVisitor.visitClass(ClassTree node, P p)

Uses of ClassTree in com.sun.source.util

Methods in com.sun.source.util that return ClassTree
abstract  ClassTree Trees.getTree(TypeElement element)
Gets the ClassTree node for a given TypeElement.

Methods in com.sun.source.util with parameters of type ClassTree
R | TreeScanner.visitClass(ClassTree node, P p)
R | SimpleTreeVisitor.visitClass(ClassTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.CompilationUnitTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.CompilationUnitTree

Packages that use CompilationUnitTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of CompilationUnitTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type CompilationUnitTree
 R TreeVisitor.visitCompilationUnit(CompilationUnitTree node, P p)

Uses of CompilationUnitTree in com.sun.source.util

Methods in com.sun.source.util that return CompilationUnitTree
CompilationUnitTree | TreePath.getCompilationUnit() Get the compilation unit associated with this path.
CompilationUnitTree | TaskEvent.getCompilationUnit()

Methods in com.sun.source.util that return types with arguments of type CompilationUnitTree
abstract  Iterable<? extends CompilationUnitTree> JavacTask.parse()
Parse the specified files returning a list of abstract syntax trees.

Methods in com.sun.source.util with parameters of type CompilationUnitTree
long | SourcePositions.getEndPosition(CompilationUnitTree file, Tree tree) Gets the ending position of tree within file.
static TreePath | TreePath.getPath(CompilationUnitTree unit, Tree target) Gets a tree path for a tree node within a compilation unit.
abstract TreePath | Trees.getPath(CompilationUnitTree unit, Tree node) Gets the path to tree node within the specified compilation unit.
long | SourcePositions.getStartPosition(CompilationUnitTree file, Tree tree) Gets the starting position of tree within file.
R | TreeScanner.visitCompilationUnit(CompilationUnitTree node, P p)
R | SimpleTreeVisitor.visitCompilationUnit(CompilationUnitTree node, P p)

Constructors in com.sun.source.util with parameters of type CompilationUnitTree
TaskEvent(TaskEvent.Kind kind, CompilationUnitTree unit)
TaskEvent(TaskEvent.Kind kind, CompilationUnitTree unit, TypeElement clazz)
TreePath(CompilationUnitTree t)
Creates a TreePath for a root node.

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.CompoundAssignmentTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.CompoundAssignmentTree

Packages that use CompoundAssignmentTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of CompoundAssignmentTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type CompoundAssignmentTree
 R TreeVisitor.visitCompoundAssignment(CompoundAssignmentTree node, P p)

Uses of CompoundAssignmentTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type CompoundAssignmentTree
R | TreeScanner.visitCompoundAssignment(CompoundAssignmentTree node, P p)
R | SimpleTreeVisitor.visitCompoundAssignment(CompoundAssignmentTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.ConditionalExpressionTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.ConditionalExpressionTree

Packages that use ConditionalExpressionTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of ConditionalExpressionTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type ConditionalExpressionTree
 R TreeVisitor.visitConditionalExpression(ConditionalExpressionTree node, P p)

Uses of ConditionalExpressionTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type ConditionalExpressionTree
R | TreeScanner.visitConditionalExpression(ConditionalExpressionTree node, P p)
R | SimpleTreeVisitor.visitConditionalExpression(ConditionalExpressionTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.ContinueTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.ContinueTree

Packages that use ContinueTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of ContinueTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type ContinueTree
 R TreeVisitor.visitContinue(ContinueTree node, P p)

Uses of ContinueTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type ContinueTree
R | TreeScanner.visitContinue(ContinueTree node, P p)
R | SimpleTreeVisitor.visitContinue(ContinueTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.DoWhileLoopTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.DoWhileLoopTree

Packages that use DoWhileLoopTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of DoWhileLoopTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type DoWhileLoopTree
 R TreeVisitor.visitDoWhileLoop(DoWhileLoopTree node, P p)

Uses of DoWhileLoopTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type DoWhileLoopTree
R | TreeScanner.visitDoWhileLoop(DoWhileLoopTree node, P p)
R | SimpleTreeVisitor.visitDoWhileLoop(DoWhileLoopTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.EmptyStatementTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.EmptyStatementTree

Packages that use EmptyStatementTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of EmptyStatementTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type EmptyStatementTree
 R TreeVisitor.visitEmptyStatement(EmptyStatementTree node, P p)

Uses of EmptyStatementTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type EmptyStatementTree
R | TreeScanner.visitEmptyStatement(EmptyStatementTree node, P p)
R | SimpleTreeVisitor.visitEmptyStatement(EmptyStatementTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.EnhancedForLoopTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.EnhancedForLoopTree

Packages that use EnhancedForLoopTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of EnhancedForLoopTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type EnhancedForLoopTree
 R TreeVisitor.visitEnhancedForLoop(EnhancedForLoopTree node, P p)

Uses of EnhancedForLoopTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type EnhancedForLoopTree
R | TreeScanner.visitEnhancedForLoop(EnhancedForLoopTree node, P p)
R | SimpleTreeVisitor.visitEnhancedForLoop(EnhancedForLoopTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.ErroneousTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.ErroneousTree

Packages that use ErroneousTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of ErroneousTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type ErroneousTree
 R TreeVisitor.visitErroneous(ErroneousTree node, P p)

Uses of ErroneousTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type ErroneousTree
R | TreeScanner.visitErroneous(ErroneousTree node, P p)
R | SimpleTreeVisitor.visitErroneous(ErroneousTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.ExpressionStatementTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.ExpressionStatementTree

Packages that use ExpressionStatementTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of ExpressionStatementTree in com.sun.source.tree

Methods in com.sun.source.tree that return types with arguments of type ExpressionStatementTree
 List<? extends ExpressionStatementTree> ForLoopTree.getUpdate()

Methods in com.sun.source.tree with parameters of type ExpressionStatementTree
 R TreeVisitor.visitExpressionStatement(ExpressionStatementTree node, P p)

Uses of ExpressionStatementTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type ExpressionStatementTree
R | TreeScanner.visitExpressionStatement(ExpressionStatementTree node, P p)
R | SimpleTreeVisitor.visitExpressionStatement(ExpressionStatementTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.ExpressionTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.ExpressionTree

Packages that use ExpressionTree
com.sun.source.tree Provides interfaces to represent source code as abstract syntax trees (AST).

Uses of ExpressionTree in com.sun.source.tree

Subinterfaces of ExpressionTree in com.sun.source.tree
interface | AnnotationTree A tree node for an annotation.
interface | ArrayAccessTree A tree node for an array access expression.
interface | AssignmentTree A tree node for an assignment expression.
interface | BinaryTree A tree node for a binary expression.
interface | CompoundAssignmentTree A tree node for compound assignment operator.
interface | ConditionalExpressionTree A tree node for the conditional operator ? :.
interface | ErroneousTree A tree node to stand in for a malformed expression.
interface | IdentifierTree A tree node for an identifier expression.
interface | InstanceOfTree A tree node for an 'instanceof' expression.
interface | LiteralTree A tree node for a literal expression.
interface | MemberSelectTree A tree node for a member access expression.
interface | MethodInvocationTree A tree node for a method invocation expression.
interface | NewArrayTree A tree node for an expression to create a new instance of an array.
interface | NewClassTree A tree node to declare a new instance of a class.
interface | ParenthesizedTree A tree node for a parenthesized expression.
interface | TypeCastTree A tree node for a type cast expression.
interface | UnaryTree A tree node for postfix and unary expressions.

Methods in com.sun.source.tree that return ExpressionTree
ExpressionTree | AssertTree.getCondition()
ExpressionTree | IfTree.getCondition()
ExpressionTree | ConditionalExpressionTree.getCondition()
ExpressionTree | ForLoopTree.getCondition()
ExpressionTree | WhileLoopTree.getCondition()
ExpressionTree | DoWhileLoopTree.getCondition()
ExpressionTree | AssertTree.getDetail()
ExpressionTree | NewClassTree.getEnclosingExpression()
ExpressionTree | MemberSelectTree.getExpression()
ExpressionTree | ArrayAccessTree.getExpression()
ExpressionTree | InstanceOfTree.getExpression()
ExpressionTree | TypeCastTree.getExpression()
ExpressionTree | UnaryTree.getExpression()
ExpressionTree | CompoundAssignmentTree.getExpression()
ExpressionTree | AssignmentTree.getExpression()
ExpressionTree | ParenthesizedTree.getExpression()
ExpressionTree | ThrowTree.getExpression()
ExpressionTree | ReturnTree.getExpression()
ExpressionTree | ExpressionStatementTree.getExpression()
ExpressionTree | SynchronizedTree.getExpression()
ExpressionTree | CaseTree.getExpression()
ExpressionTree | SwitchTree.getExpression()
ExpressionTree | EnhancedForLoopTree.getExpression()
ExpressionTree | ConditionalExpressionTree.getFalseExpression()
ExpressionTree | NewClassTree.getIdentifier()
ExpressionTree | ArrayAccessTree.getIndex()
ExpressionTree | VariableTree.getInitializer()
ExpressionTree | BinaryTree.getLeftOperand()
ExpressionTree | MethodInvocationTree.getMethodSelect()
ExpressionTree | CompilationUnitTree.getPackageName()
ExpressionTree | BinaryTree.getRightOperand()
ExpressionTree | ConditionalExpressionTree.getTrueExpression()
ExpressionTree | CompoundAssignmentTree.getVariable()
ExpressionTree | AssignmentTree.getVariable()

Methods in com.sun.source.tree that return types with arguments of type ExpressionTree
List<? extends ExpressionTree> | AnnotationTree.getArguments()
List<? extends ExpressionTree> | NewClassTree.getArguments()
List<? extends ExpressionTree> | MethodInvocationTree.getArguments()
List<? extends ExpressionTree> | NewArrayTree.getDimensions()
List<? extends ExpressionTree> | NewArrayTree.getInitializers()
List<? extends ExpressionTree> | MethodTree.getThrows()

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.ForLoopTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.ForLoopTree

Packages that use ForLoopTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of ForLoopTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type ForLoopTree
 R TreeVisitor.visitForLoop(ForLoopTree node, P p)

Uses of ForLoopTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type ForLoopTree
R | TreeScanner.visitForLoop(ForLoopTree node, P p)
R | SimpleTreeVisitor.visitForLoop(ForLoopTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.IdentifierTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.IdentifierTree

Packages that use IdentifierTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of IdentifierTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type IdentifierTree
 R TreeVisitor.visitIdentifier(IdentifierTree node, P p)

Uses of IdentifierTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type IdentifierTree
R | TreeScanner.visitIdentifier(IdentifierTree node, P p)
R | SimpleTreeVisitor.visitIdentifier(IdentifierTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.IfTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.IfTree

Packages that use IfTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of IfTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type IfTree
 R TreeVisitor.visitIf(IfTree node, P p)

Uses of IfTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type IfTree
R | TreeScanner.visitIf(IfTree node, P p)
R | SimpleTreeVisitor.visitIf(IfTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.ImportTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.ImportTree

Packages that use ImportTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of ImportTree in com.sun.source.tree

Methods in com.sun.source.tree that return types with arguments of type ImportTree
 List<? extends ImportTree> CompilationUnitTree.getImports()

Methods in com.sun.source.tree with parameters of type ImportTree
 R TreeVisitor.visitImport(ImportTree node, P p)

Uses of ImportTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type ImportTree
R | TreeScanner.visitImport(ImportTree node, P p)
R | SimpleTreeVisitor.visitImport(ImportTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.InstanceOfTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.InstanceOfTree

Packages that use InstanceOfTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of InstanceOfTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type InstanceOfTree
 R TreeVisitor.visitInstanceOf(InstanceOfTree node, P p)

Uses of InstanceOfTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type InstanceOfTree
R | TreeScanner.visitInstanceOf(InstanceOfTree node, P p)
R | SimpleTreeVisitor.visitInstanceOf(InstanceOfTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.LabeledStatementTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.LabeledStatementTree

Packages that use LabeledStatementTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of LabeledStatementTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type LabeledStatementTree
 R TreeVisitor.visitLabeledStatement(LabeledStatementTree node, P p)

Uses of LabeledStatementTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type LabeledStatementTree
R | TreeScanner.visitLabeledStatement(LabeledStatementTree node, P p)
R | SimpleTreeVisitor.visitLabeledStatement(LabeledStatementTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.LineMap

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.LineMap

Packages that use LineMap
com.sun.source.tree Provides interfaces to represent source code as abstract syntax trees (AST).

Uses of LineMap in com.sun.source.tree

Methods in com.sun.source.tree that return LineMap
 LineMap CompilationUnitTree.getLineMap()
Gets the line map for this compilation unit, if available.

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.LiteralTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.LiteralTree

Packages that use LiteralTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of LiteralTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type LiteralTree
 R TreeVisitor.visitLiteral(LiteralTree node, P p)

Uses of LiteralTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type LiteralTree
R | TreeScanner.visitLiteral(LiteralTree node, P p)
R | SimpleTreeVisitor.visitLiteral(LiteralTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.MemberSelectTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.MemberSelectTree

Packages that use MemberSelectTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of MemberSelectTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type MemberSelectTree
 R TreeVisitor.visitMemberSelect(MemberSelectTree node, P p)

Uses of MemberSelectTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type MemberSelectTree
R | TreeScanner.visitMemberSelect(MemberSelectTree node, P p)
R | SimpleTreeVisitor.visitMemberSelect(MemberSelectTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.MethodInvocationTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.MethodInvocationTree

Packages that use MethodInvocationTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of MethodInvocationTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type MethodInvocationTree
 R TreeVisitor.visitMethodInvocation(MethodInvocationTree node, P p)

Uses of MethodInvocationTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type MethodInvocationTree
R | TreeScanner.visitMethodInvocation(MethodInvocationTree node, P p)
R | SimpleTreeVisitor.visitMethodInvocation(MethodInvocationTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.MethodTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.MethodTree

Packages that use MethodTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of MethodTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type MethodTree
 R TreeVisitor.visitMethod(MethodTree node, P p)

Uses of MethodTree in com.sun.source.util

Methods in com.sun.source.util that return MethodTree
abstract  MethodTree Trees.getTree(ExecutableElement method)
Gets the MethodTree node for a given ExecutableElement.

Methods in com.sun.source.util with parameters of type MethodTree
R | TreeScanner.visitMethod(MethodTree node, P p)
R | SimpleTreeVisitor.visitMethod(MethodTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.ModifiersTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.ModifiersTree

Packages that use ModifiersTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of ModifiersTree in com.sun.source.tree

Methods in com.sun.source.tree that return ModifiersTree
ModifiersTree | VariableTree.getModifiers()
ModifiersTree | MethodTree.getModifiers()
ModifiersTree | ClassTree.getModifiers()

Methods in com.sun.source.tree with parameters of type ModifiersTree
 R TreeVisitor.visitModifiers(ModifiersTree node, P p)

Uses of ModifiersTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type ModifiersTree
R | TreeScanner.visitModifiers(ModifiersTree node, P p)
R | SimpleTreeVisitor.visitModifiers(ModifiersTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.NewArrayTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.NewArrayTree

Packages that use NewArrayTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of NewArrayTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type NewArrayTree
 R TreeVisitor.visitNewArray(NewArrayTree node, P p)

Uses of NewArrayTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type NewArrayTree
R | TreeScanner.visitNewArray(NewArrayTree node, P p)
R | SimpleTreeVisitor.visitNewArray(NewArrayTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.NewClassTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.NewClassTree

Packages that use NewClassTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of NewClassTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type NewClassTree
 R TreeVisitor.visitNewClass(NewClassTree node, P p)

Uses of NewClassTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type NewClassTree
R | TreeScanner.visitNewClass(NewClassTree node, P p)
R | SimpleTreeVisitor.visitNewClass(NewClassTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.ParameterizedTypeTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.ParameterizedTypeTree

Packages that use ParameterizedTypeTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of ParameterizedTypeTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type ParameterizedTypeTree
 R TreeVisitor.visitParameterizedType(ParameterizedTypeTree node, P p)

Uses of ParameterizedTypeTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type ParameterizedTypeTree
R | TreeScanner.visitParameterizedType(ParameterizedTypeTree node, P p)
R | SimpleTreeVisitor.visitParameterizedType(ParameterizedTypeTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.ParenthesizedTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.ParenthesizedTree

Packages that use ParenthesizedTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of ParenthesizedTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type ParenthesizedTree
 R TreeVisitor.visitParenthesized(ParenthesizedTree node, P p)

Uses of ParenthesizedTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type ParenthesizedTree
R | TreeScanner.visitParenthesized(ParenthesizedTree node, P p)
R | SimpleTreeVisitor.visitParenthesized(ParenthesizedTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.PrimitiveTypeTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.PrimitiveTypeTree

Packages that use PrimitiveTypeTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of PrimitiveTypeTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type PrimitiveTypeTree
 R TreeVisitor.visitPrimitiveType(PrimitiveTypeTree node, P p)

Uses of PrimitiveTypeTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type PrimitiveTypeTree
R | TreeScanner.visitPrimitiveType(PrimitiveTypeTree node, P p)
R | SimpleTreeVisitor.visitPrimitiveType(PrimitiveTypeTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.ReturnTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.ReturnTree

Packages that use ReturnTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of ReturnTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type ReturnTree
 R TreeVisitor.visitReturn(ReturnTree node, P p)

Uses of ReturnTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type ReturnTree
R | TreeScanner.visitReturn(ReturnTree node, P p)
R | SimpleTreeVisitor.visitReturn(ReturnTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.Scope

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.Scope

Packages that use Scope
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of Scope in com.sun.source.tree

Methods in com.sun.source.tree that return Scope
 Scope Scope.getEnclosingScope()
Returns the enclosing scope.

Uses of Scope in com.sun.source.util

Methods in com.sun.source.util that return Scope
abstract  Scope Trees.getScope(TreePath path)
Gets the Scope for the Tree node identified by a given TreePath.

Methods in com.sun.source.util with parameters of type Scope
abstract boolean | Trees.isAccessible(Scope scope, Element member, DeclaredType type) Checks whether the given element is accessible as a member of the given type in a given scope.
abstract boolean | Trees.isAccessible(Scope scope, TypeElement type) Checks whether a given type is accessible in a given scope.

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.StatementTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.StatementTree

Packages that use StatementTree
com.sun.source.tree Provides interfaces to represent source code as abstract syntax trees (AST).

Uses of StatementTree in com.sun.source.tree

Subinterfaces of StatementTree in com.sun.source.tree
interface | AssertTree A tree node for an 'assert' statement.
interface | BlockTree A tree node for a statement block.
interface | BreakTree A tree node for a 'break' statement.
interface | ClassTree A tree node for a class, interface, enum, or annotation type declaration.
interface | ContinueTree A tree node for a 'continue' statement.
interface | DoWhileLoopTree A tree node for a 'do' statement.
interface | EmptyStatementTree A tree node for an empty (skip) statement.
interface | EnhancedForLoopTree A tree node for an "enhanced" 'for' loop statement.
interface | ExpressionStatementTree A tree node for an expression statement.
interface | ForLoopTree A tree node for a basic 'for' loop statement.
interface | IfTree A tree node for an 'if' statement.
interface | LabeledStatementTree A tree node for a labeled statement.
interface | ReturnTree A tree node for a 'return' statement.
interface | SwitchTree A tree node for a 'switch' statement.
interface | SynchronizedTree A tree node for a 'synchronized' statement.
interface | ThrowTree A tree node for a 'throw' statement.
interface | TryTree A tree node for a 'try' statement.
interface | VariableTree A tree node for a variable declaration.
interface | WhileLoopTree A tree node for a 'while' loop statement.

Methods in com.sun.source.tree that return StatementTree
StatementTree | IfTree.getElseStatement()
StatementTree | LabeledStatementTree.getStatement()
StatementTree | EnhancedForLoopTree.getStatement()
StatementTree | ForLoopTree.getStatement()
StatementTree | WhileLoopTree.getStatement()
StatementTree | DoWhileLoopTree.getStatement()
StatementTree | IfTree.getThenStatement()

Methods in com.sun.source.tree that return types with arguments of type StatementTree
List<? extends StatementTree> | ForLoopTree.getInitializer()
List<? extends StatementTree> | CaseTree.getStatements()
List<? extends StatementTree> | BlockTree.getStatements()

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.SwitchTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.SwitchTree

Packages that use SwitchTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of SwitchTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type SwitchTree
 R TreeVisitor.visitSwitch(SwitchTree node, P p)

Uses of SwitchTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type SwitchTree
R | TreeScanner.visitSwitch(SwitchTree node, P p)
R | SimpleTreeVisitor.visitSwitch(SwitchTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.SynchronizedTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.SynchronizedTree

Packages that use SynchronizedTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of SynchronizedTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type SynchronizedTree
 R TreeVisitor.visitSynchronized(SynchronizedTree node, P p)

Uses of SynchronizedTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type SynchronizedTree
R | TreeScanner.visitSynchronized(SynchronizedTree node, P p)
R | SimpleTreeVisitor.visitSynchronized(SynchronizedTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.ThrowTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.ThrowTree

Packages that use ThrowTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of ThrowTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type ThrowTree
 R TreeVisitor.visitThrow(ThrowTree node, P p)

Uses of ThrowTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type ThrowTree
R | TreeScanner.visitThrow(ThrowTree node, P p)
R | SimpleTreeVisitor.visitThrow(ThrowTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.Tree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.Tree

Packages that use Tree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of Tree in com.sun.source.tree

Subinterfaces of Tree in com.sun.source.tree
interface | AnnotationTree A tree node for an annotation.
interface | ArrayAccessTree A tree node for an array access expression.
interface | ArrayTypeTree A tree node for an array type.
interface | AssertTree A tree node for an 'assert' statement.
interface | AssignmentTree A tree node for an assignment expression.
interface | BinaryTree A tree node for a binary expression.
interface | BlockTree A tree node for a statement block.
interface | BreakTree A tree node for a 'break' statement.
interface | CaseTree A tree node for a 'case' in a 'switch' statement.
interface | CatchTree A tree node for a 'catch' block in a 'try' statement.
interface | ClassTree A tree node for a class, interface, enum, or annotation type declaration.
interface | CompilationUnitTree Represents the abstract syntax tree for compilation units (source files) and package declarations (package-info.java).
interface | CompoundAssignmentTree A tree node for compound assignment operator.
interface | ConditionalExpressionTree A tree node for the conditional operator ? :.
interface | ContinueTree A tree node for a 'continue' statement.
interface | DoWhileLoopTree A tree node for a 'do' statement.
interface | EmptyStatementTree A tree node for an empty (skip) statement.
interface | EnhancedForLoopTree A tree node for an "enhanced" 'for' loop statement.
interface | ErroneousTree A tree node to stand in for a malformed expression.
interface | ExpressionStatementTree A tree node for an expression statement.
interface | ExpressionTree A tree node used as the base class for the different types of expressions.
interface | ForLoopTree A tree node for a basic 'for' loop statement.
interface | IdentifierTree A tree node for an identifier expression.
interface | IfTree A tree node for an 'if' statement.
interface | ImportTree A tree node for an import statement.
interface | InstanceOfTree A tree node for an 'instanceof' expression.
interface | LabeledStatementTree A tree node for a labeled statement.
interface | LiteralTree A tree node for a literal expression.
interface | MemberSelectTree A tree node for a member access expression.
interface | MethodInvocationTree A tree node for a method invocation expression.
interface | MethodTree A tree node for a method or annotation type element declaration.
interface | ModifiersTree A tree node for the modifiers, including annotations, for a declaration.
interface | NewArrayTree A tree node for an expression to create a new instance of an array.
interface | NewClassTree A tree node to declare a new instance of a class.
interface | ParameterizedTypeTree A tree node for a type expression involving type parameters.
interface | ParenthesizedTree A tree node for a parenthesized expression.
interface | PrimitiveTypeTree A tree node for a primitive type.
interface | ReturnTree A tree node for a 'return' statement.
interface | StatementTree A tree node used as the base class for the different kinds of statements.
interface | SwitchTree A tree node for a 'switch' statement.
interface | SynchronizedTree A tree node for a 'synchronized' statement.
interface | ThrowTree A tree node for a 'throw' statement.
interface | TryTree A tree node for a 'try' statement.
interface | TypeCastTree A tree node for a type cast expression.
interface | TypeParameterTree A tree node for a type parameter.
interface | UnaryTree A tree node for postfix and unary expressions.
interface | VariableTree A tree node for a variable declaration.
interface | WhileLoopTree A tree node for a 'while' loop statement.
interface | WildcardTree A tree node for a wildcard type argument.

Methods in com.sun.source.tree that return Tree
Tree | AnnotationTree.getAnnotationType()
Tree | WildcardTree.getBound()
Tree | MethodTree.getDefaultValue()
Tree | ClassTree.getExtendsClause()
Tree | ImportTree.getQualifiedIdentifier()
Tree | MethodTree.getReturnType()
Tree | ParameterizedTypeTree.getType()
Tree | ArrayTypeTree.getType()
Tree | InstanceOfTree.getType()
Tree | TypeCastTree.getType()
Tree | NewArrayTree.getType()
Tree | VariableTree.getType()

Methods in com.sun.source.tree that return types with arguments of type Tree
Class<? extends Tree> | Tree.Kind.asInterface()
List<? extends Tree> | TypeParameterTree.getBounds()
List<? extends Tree> | ErroneousTree.getErrorTrees()
List<? extends Tree> | ClassTree.getImplementsClause()
List<? extends Tree> | ClassTree.getMembers()
List<? extends Tree> | ParameterizedTypeTree.getTypeArguments()
List<? extends Tree> | NewClassTree.getTypeArguments()
List<? extends Tree> | MethodInvocationTree.getTypeArguments()
List<? extends Tree> | CompilationUnitTree.getTypeDecls()

Methods in com.sun.source.tree with parameters of type Tree
 R TreeVisitor.visitOther(Tree node, P p)

Uses of Tree in com.sun.source.util

Methods in com.sun.source.util that return Tree
Tree | TreePath.getLeaf() Get the leaf node for this path.
abstract Tree | Trees.getTree(Element element) Gets the Tree node for a given Element.
abstract Tree | Trees.getTree(Element e, AnnotationMirror a) Gets the Tree node for an AnnotationMirror on a given Element.
abstract Tree | Trees.getTree(Element e, AnnotationMirror a, AnnotationValue v) Gets the Tree node for an AnnotationValue for an AnnotationMirror on a given Element.

Methods in com.sun.source.util that return types with arguments of type Tree
 Iterator<Tree> TreePath.iterator()

Methods in com.sun.source.util with parameters of type Tree
protected R | SimpleTreeVisitor.defaultAction(Tree node, P p)
long | SourcePositions.getEndPosition(CompilationUnitTree file, Tree tree) Gets the ending position of tree within file.
static TreePath | TreePath.getPath(CompilationUnitTree unit, Tree target) Gets a tree path for a tree node within a compilation unit.
abstract TreePath | Trees.getPath(CompilationUnitTree unit, Tree node) Gets the path to tree node within the specified compilation unit.
static TreePath | TreePath.getPath(TreePath path, Tree target) Gets a tree path for a tree node within a subtree identified by a TreePath object.
long | SourcePositions.getStartPosition(CompilationUnitTree file, Tree tree) Gets the starting position of tree within file.
R | TreeScanner.scan(Tree node, P p) Scan a single node.
R | TreePathScanner.scan(Tree tree, P p) Scan a single node.
R | SimpleTreeVisitor.visit(Tree node, P p)
R | TreeScanner.visitOther(Tree node, P p)
R | SimpleTreeVisitor.visitOther(Tree node, P p)

Method parameters in com.sun.source.util with type arguments of type Tree
abstract TypeMirror | JavacTask.getTypeMirror(Iterable<? extends Tree> path) Get a type mirror of the tree node determined by the specified path.
R | TreeScanner.scan(Iterable<? extends Tree> nodes, P p) Scan a list of nodes.
R | SimpleTreeVisitor.visit(Iterable<? extends Tree> nodes, P p)

Constructors in com.sun.source.util with parameters of type Tree
TreePath(TreePath p, Tree t)
Creates a TreePath for a child node.

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.TreeVisitor

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.TreeVisitor

Packages that use TreeVisitor
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of TreeVisitor in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type TreeVisitor
<R,D> R
Tree.accept(TreeVisitor<R,D> visitor, D data)
Accept method used to implement the visitor pattern.

Uses of TreeVisitor in com.sun.source.util

Classes in com.sun.source.util that implement TreeVisitor
class | SimpleTreeVisitor<R,P> A simple visitor for tree nodes.
class | TreePathScanner<R,P> A TreeVisitor that visits all the child tree nodes, and provides support for maintaining a path for the parent nodes.
class | TreeScanner<R,P> A TreeVisitor that visits all the child tree nodes.

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.TryTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.TryTree

Packages that use TryTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of TryTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type TryTree
 R TreeVisitor.visitTry(TryTree node, P p)

Uses of TryTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type TryTree
R | TreeScanner.visitTry(TryTree node, P p)
R | SimpleTreeVisitor.visitTry(TryTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.TypeCastTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.TypeCastTree

Packages that use TypeCastTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of TypeCastTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type TypeCastTree
 R TreeVisitor.visitTypeCast(TypeCastTree node, P p)

Uses of TypeCastTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type TypeCastTree
R | TreeScanner.visitTypeCast(TypeCastTree node, P p)
R | SimpleTreeVisitor.visitTypeCast(TypeCastTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.TypeParameterTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.TypeParameterTree

Packages that use TypeParameterTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of TypeParameterTree in com.sun.source.tree

Methods in com.sun.source.tree that return types with arguments of type TypeParameterTree
List<? extends TypeParameterTree> | MethodTree.getTypeParameters()
List<? extends TypeParameterTree> | ClassTree.getTypeParameters()

Methods in com.sun.source.tree with parameters of type TypeParameterTree
 R TreeVisitor.visitTypeParameter(TypeParameterTree node, P p)

Uses of TypeParameterTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type TypeParameterTree
R | TreeScanner.visitTypeParameter(TypeParameterTree node, P p)
R | SimpleTreeVisitor.visitTypeParameter(TypeParameterTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.UnaryTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.UnaryTree

Packages that use UnaryTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of UnaryTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type UnaryTree
 R TreeVisitor.visitUnary(UnaryTree node, P p)

Uses of UnaryTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type UnaryTree
R | TreeScanner.visitUnary(UnaryTree node, P p)
R | SimpleTreeVisitor.visitUnary(UnaryTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.VariableTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.VariableTree

Packages that use VariableTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of VariableTree in com.sun.source.tree

Methods in com.sun.source.tree that return VariableTree
VariableTree | CatchTree.getParameter()
VariableTree | EnhancedForLoopTree.getVariable()

Methods in com.sun.source.tree that return types with arguments of type VariableTree
 List<? extends VariableTree> MethodTree.getParameters()

Methods in com.sun.source.tree with parameters of type VariableTree
 R TreeVisitor.visitVariable(VariableTree node, P p)

Uses of VariableTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type VariableTree
R | TreeScanner.visitVariable(VariableTree node, P p)
R | SimpleTreeVisitor.visitVariable(VariableTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.WhileLoopTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.WhileLoopTree

Packages that use WhileLoopTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of WhileLoopTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type WhileLoopTree
 R TreeVisitor.visitWhileLoop(WhileLoopTree node, P p)

Uses of WhileLoopTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type WhileLoopTree
R | TreeScanner.visitWhileLoop(WhileLoopTree node, P p)
R | SimpleTreeVisitor.visitWhileLoop(WhileLoopTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.tree.WildcardTree

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.tree.WildcardTree

Packages that use WildcardTree
com.sun.source.tree | Provides interfaces to represent source code as abstract syntax trees (AST).
com.sun.source.util | Provides utilities for operations on abstract syntax trees (AST).

Uses of WildcardTree in com.sun.source.tree

Methods in com.sun.source.tree with parameters of type WildcardTree
 R TreeVisitor.visitWildcard(WildcardTree node, P p)

Uses of WildcardTree in com.sun.source.util

Methods in com.sun.source.util with parameters of type WildcardTree
R | TreeScanner.visitWildcard(WildcardTree node, P p)
R | SimpleTreeVisitor.visitWildcard(WildcardTree node, P p)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ClassTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface ClassTree

All Superinterfaces:
StatementTree, Tree
public interface ClassTree
extends StatementTree

A tree node for a class, interface, enum, or annotation type declaration. For example:

   modifiers class simpleName typeParameters
       extends extendsClause
       implements implementsClause
   {
       members
   }

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, sections 8.1, 8.9, 9.1, and 9.6"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
Tree | getExtendsClause()
List<? extends Tree> | getImplementsClause()
List<? extends Tree> | getMembers()
ModifiersTree | getModifiers()
Name | getSimpleName()
List<? extends TypeParameterTree> | getTypeParameters()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getModifiers

ModifiersTree getModifiers()

getSimpleName

Name getSimpleName()

getTypeParameters

List<? extends TypeParameterTree> getTypeParameters()

getExtendsClause

Tree getExtendsClause()

getImplementsClause

List<? extends Tree> getImplementsClause()

getMembers

List<? extends Tree> getMembers()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


CompilationUnitTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface CompilationUnitTree

All Superinterfaces:
Tree
public interface CompilationUnitTree
extends Tree

Represents the abstract syntax tree for compilation units (source files) and package declarations (package-info.java).

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, sections 7.3, and 7.4"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
List<? extends ImportTree> | getImports()
LineMap | getLineMap() Gets the line map for this compilation unit, if available.
List<? extends AnnotationTree> | getPackageAnnotations()
ExpressionTree | getPackageName()
JavaFileObject | getSourceFile()
List<? extends Tree> | getTypeDecls()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getPackageAnnotations

List<? extends AnnotationTree> getPackageAnnotations()

getPackageName

ExpressionTree getPackageName()

getImports

List<? extends ImportTree> getImports()

getTypeDecls

List<? extends Tree> getTypeDecls()

getSourceFile

JavaFileObject getSourceFile()

getLineMap

LineMap getLineMap()
Gets the line map for this compilation unit, if available. Returns null if the line map is not available.

Returns:
the line map for this compilation unit
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


CompoundAssignmentTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface CompoundAssignmentTree

All Superinterfaces:
ExpressionTree, Tree
public interface CompoundAssignmentTree
extends ExpressionTree

A tree node for compound assignment operator. Use getKind to determine the kind of operator. For example:

   variable operator expression

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 15.26.2"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
ExpressionTree | getExpression()
ExpressionTree | getVariable()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getVariable

ExpressionTree getVariable()

getExpression

ExpressionTree getExpression()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ConditionalExpressionTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface ConditionalExpressionTree

All Superinterfaces:
ExpressionTree, Tree
public interface ConditionalExpressionTree
extends ExpressionTree

A tree node for the conditional operator ? :. For example:

   condition ? trueExpression : falseExpression

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 15.25"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
ExpressionTree | getCondition()
ExpressionTree | getFalseExpression()
ExpressionTree | getTrueExpression()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getCondition

ExpressionTree getCondition()

getTrueExpression

ExpressionTree getTrueExpression()

getFalseExpression

ExpressionTree getFalseExpression()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ContinueTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface ContinueTree

All Superinterfaces:
StatementTree, Tree
public interface ContinueTree
extends StatementTree

A tree node for a 'continue' statement. For example:

   continue;
   continue label ;

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.16"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
 Name getLabel()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getLabel

Name getLabel()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


DoWhileLoopTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface DoWhileLoopTree

All Superinterfaces:
StatementTree, Tree
public interface DoWhileLoopTree
extends StatementTree

A tree node for a 'do' statement. For example:

   do
       statement
   while ( expression );

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.13"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
ExpressionTree | getCondition()
StatementTree | getStatement()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getCondition

ExpressionTree getCondition()

getStatement

StatementTree getStatement()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


EmptyStatementTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface EmptyStatementTree

All Superinterfaces:
StatementTree, Tree
public interface EmptyStatementTree
extends StatementTree

A tree node for an empty (skip) statement. For example:

    ;

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.6"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


EnhancedForLoopTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface EnhancedForLoopTree

All Superinterfaces:
StatementTree, Tree
public interface EnhancedForLoopTree
extends StatementTree

A tree node for an "enhanced" 'for' loop statement. For example:

   for ( variable : expression )
       statement

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.14.2"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
ExpressionTree | getExpression()
StatementTree | getStatement()
VariableTree | getVariable()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getVariable

VariableTree getVariable()

getExpression

ExpressionTree getExpression()

getStatement

StatementTree getStatement()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ErroneousTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface ErroneousTree

All Superinterfaces:
ExpressionTree, Tree
public interface ErroneousTree
extends ExpressionTree

A tree node to stand in for a malformed expression.

Since:
1.6

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
 List<? extends Tree> getErrorTrees()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getErrorTrees

List<? extends Tree> getErrorTrees()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ExpressionStatementTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface ExpressionStatementTree

All Superinterfaces:
StatementTree, Tree
public interface ExpressionStatementTree
extends StatementTree

A tree node for an expression statement. For example:

   expression ;

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.8"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
 ExpressionTree getExpression()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getExpression

ExpressionTree getExpression()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ExpressionTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface ExpressionTree

All Superinterfaces:
Tree
All Known Subinterfaces:
AnnotationTree, ArrayAccessTree, AssignmentTree, BinaryTree, CompoundAssignmentTree, ConditionalExpressionTree, ErroneousTree, IdentifierTree, InstanceOfTree, LiteralTree, MemberSelectTree, MethodInvocationTree, NewArrayTree, NewClassTree, ParenthesizedTree, TypeCastTree, UnaryTree
public interface ExpressionTree
extends Tree

A tree node used as the base class for the different types of expressions.

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, chapter 15"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ForLoopTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface ForLoopTree

All Superinterfaces:
StatementTree, Tree
public interface ForLoopTree
extends StatementTree

A tree node for a basic 'for' loop statement. For example:

   for ( initializer ; condition ; update )
       statement

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.14.1"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
ExpressionTree | getCondition()
List<? extends StatementTree> | getInitializer()
StatementTree | getStatement()
List<? extends ExpressionStatementTree> | getUpdate()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getInitializer

List<? extends StatementTree> getInitializer()

getCondition

ExpressionTree getCondition()

getUpdate

List<? extends ExpressionStatementTree> getUpdate()

getStatement

StatementTree getStatement()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


IdentifierTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface IdentifierTree

All Superinterfaces:
ExpressionTree, Tree
public interface IdentifierTree
extends ExpressionTree

A tree node for an identifier expression. For example:

   name

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 6.5.6.1"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
 Name getName()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getName

Name getName()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


IfTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface IfTree

All Superinterfaces:
StatementTree, Tree
public interface IfTree
extends StatementTree

A tree node for an 'if' statement. For example:

   if ( condition )
      thenStatement

   if ( condition )
       thenStatement
   else
       elseStatement

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.9"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
ExpressionTree | getCondition()
StatementTree | getElseStatement()
StatementTree | getThenStatement()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getCondition

ExpressionTree getCondition()

getThenStatement

StatementTree getThenStatement()

getElseStatement

StatementTree getElseStatement()
Returns:
null if this if statement has no else branch.
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ImportTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface ImportTree

All Superinterfaces:
Tree
public interface ImportTree
extends Tree

A tree node for an import statement. For example:

   import qualifiedIdentifier ;

   static import qualifiedIdentifier ;

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 7.5"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
Tree | getQualifiedIdentifier()
boolean | isStatic()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

isStatic

boolean isStatic()

getQualifiedIdentifier

Tree getQualifiedIdentifier()
Returns:
a qualified identifier ending in "*" if and only if this is an import-on-demand.
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


InstanceOfTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface InstanceOfTree

All Superinterfaces:
ExpressionTree, Tree
public interface InstanceOfTree
extends ExpressionTree

A tree node for an 'instanceof' expression. For example:

   expression instanceof type

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 15.20.2"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
ExpressionTree | getExpression()
Tree | getType()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getExpression

ExpressionTree getExpression()

getType

Tree getType()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


LabeledStatementTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface LabeledStatementTree

All Superinterfaces:
StatementTree, Tree
public interface LabeledStatementTree
extends StatementTree

A tree node for a labeled statement. For example:

   label : statement

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.7"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
Name | getLabel()
StatementTree | getStatement()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getLabel

Name getLabel()

getStatement

StatementTree getStatement()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


LineMap

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface LineMap

public interface LineMap

Provides methods to convert between character positions and line numbers for a compilation unit.

Since:
1.6

Method Summary
long | getColumnNumber(long pos) Find the column for a character position.
long | getLineNumber(long pos) Find the line containing a position; a line termination character is on the line it terminates.
long | getPosition(long line, long column) Find the position corresponding to a (line,column).
long | getStartPosition(long line) Find the start position of a line.

Method Detail

getStartPosition

long getStartPosition(long line)
Find the start position of a line.

Parameters:
line - line number (beginning at 1)
Returns:
position of first character in line
Throws:
IndexOutOfBoundsException - if lineNumber < 1 if lineNumber > no. of lines

getPosition

long getPosition(long line,
                 long column)
Find the position corresponding to a (line,column).

Parameters:
line - line number (beginning at 1)
column - tab-expanded column number (beginning 1)
Returns:
position of character
Throws:
IndexOutOfBoundsException - if line < 1 if line > no. of lines

getLineNumber

long getLineNumber(long pos)
Find the line containing a position; a line termination character is on the line it terminates.

Parameters:
pos - character offset of the position
Returns:
the line number of pos (first line is 1)

getColumnNumber

long getColumnNumber(long pos)
Find the column for a character position. Tab characters preceding the position on the same line will be expanded when calculating the column number.

Parameters:
pos - character offset of the position
Returns:
the tab-expanded column number of pos (first column is 1)
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


LiteralTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface LiteralTree

All Superinterfaces:
ExpressionTree, Tree
public interface LiteralTree
extends ExpressionTree

A tree node for a literal expression. Use getKind to determine the kind of literal. For example:

   value

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 15.28"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
 Object getValue()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getValue

Object getValue()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


MemberSelectTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface MemberSelectTree

All Superinterfaces:
ExpressionTree, Tree
public interface MemberSelectTree
extends ExpressionTree

A tree node for a member access expression. For example:

   expression . identifier

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, sections 6.5, 15.11, and 15.12"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
ExpressionTree | getExpression()
Name | getIdentifier()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getExpression

ExpressionTree getExpression()

getIdentifier

Name getIdentifier()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


MethodInvocationTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface MethodInvocationTree

All Superinterfaces:
ExpressionTree, Tree
public interface MethodInvocationTree
extends ExpressionTree

A tree node for a method invocation expression. For example:

   identifier ( arguments )

   this . typeArguments identifier ( arguments )

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 15.12"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
List<? extends ExpressionTree> | getArguments()
ExpressionTree | getMethodSelect()
List<? extends Tree> | getTypeArguments()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getTypeArguments

List<? extends Tree> getTypeArguments()

getMethodSelect

ExpressionTree getMethodSelect()

getArguments

List<? extends ExpressionTree> getArguments()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


MethodTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface MethodTree

All Superinterfaces:
Tree
public interface MethodTree
extends Tree

A tree node for a method or annotation type element declaration. For example:

   modifiers typeParameters type name
      ( parameters )
      body

   modifiers type name () default defaultValue

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, sections 8.4, 8.6, 8.7, 9.4, and 9.6"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
BlockTree | getBody()
Tree | getDefaultValue()
ModifiersTree | getModifiers()
Name | getName()
List<? extends VariableTree> | getParameters()
Tree | getReturnType()
List<? extends ExpressionTree> | getThrows()
List<? extends TypeParameterTree> | getTypeParameters()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getModifiers

ModifiersTree getModifiers()

getName

Name getName()

getReturnType

Tree getReturnType()

getTypeParameters

List<? extends TypeParameterTree> getTypeParameters()

getParameters

List<? extends VariableTree> getParameters()

getThrows

List<? extends ExpressionTree> getThrows()

getBody

BlockTree getBody()

getDefaultValue

Tree getDefaultValue()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ModifiersTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface ModifiersTree

All Superinterfaces:
Tree
public interface ModifiersTree
extends Tree

A tree node for the modifiers, including annotations, for a declaration. For example:

   flags

   flags annotations

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, sections 8.1.1, 8.3.1, 8.4.3, 8.5.1, 8.8.3, 9.1.1, and 9.7"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
List<? extends AnnotationTree> | getAnnotations()
Set<Modifier> | getFlags()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getFlags

Set<Modifier> getFlags()

getAnnotations

List<? extends AnnotationTree> getAnnotations()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


NewArrayTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface NewArrayTree

All Superinterfaces:
ExpressionTree, Tree
public interface NewArrayTree
extends ExpressionTree

A tree node for an expression to create a new instance of an array. For example:

   new type dimensions initializers

   new type dimensions [ ] initializers

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 15.10"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
List<? extends ExpressionTree> | getDimensions()
List<? extends ExpressionTree> | getInitializers()
Tree | getType()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getType

Tree getType()

getDimensions

List<? extends ExpressionTree> getDimensions()

getInitializers

List<? extends ExpressionTree> getInitializers()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


NewClassTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface NewClassTree

All Superinterfaces:
ExpressionTree, Tree
public interface NewClassTree
extends ExpressionTree

A tree node to declare a new instance of a class. For example:

   new identifier ( )

   new identifier ( arguments )

   new typeArguments identifier ( arguments )
       classBody

   enclosingExpression.new identifier ( arguments )

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 15.9"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
List<? extends ExpressionTree> | getArguments()
ClassTree | getClassBody()
ExpressionTree | getEnclosingExpression()
ExpressionTree | getIdentifier()
List<? extends Tree> | getTypeArguments()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getEnclosingExpression

ExpressionTree getEnclosingExpression()

getTypeArguments

List<? extends Tree> getTypeArguments()

getIdentifier

ExpressionTree getIdentifier()

getArguments

List<? extends ExpressionTree> getArguments()

getClassBody

ClassTree getClassBody()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ParameterizedTypeTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface ParameterizedTypeTree

All Superinterfaces:
Tree
public interface ParameterizedTypeTree
extends Tree

A tree node for a type expression involving type parameters. For example:

   type < typeArguments >

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 4.5.1"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
Tree | getType()
List<? extends Tree> | getTypeArguments()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getType

Tree getType()

getTypeArguments

List<? extends Tree> getTypeArguments()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ParenthesizedTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface ParenthesizedTree

All Superinterfaces:
ExpressionTree, Tree
public interface ParenthesizedTree
extends ExpressionTree

A tree node for a parenthesized expression. Note: parentheses not be preserved by the parser. For example:

   ( expression )

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 15.8.5"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
 ExpressionTree getExpression()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getExpression

ExpressionTree getExpression()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


PrimitiveTypeTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface PrimitiveTypeTree

All Superinterfaces:
Tree
public interface PrimitiveTypeTree
extends Tree

A tree node for a primitive type. For example:

   primitiveTypeKind

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 4.2"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
 TypeKind getPrimitiveTypeKind()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getPrimitiveTypeKind

TypeKind getPrimitiveTypeKind()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ReturnTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface ReturnTree

All Superinterfaces:
StatementTree, Tree
public interface ReturnTree
extends StatementTree

A tree node for a 'return' statement. For example:

   return;
   return expression;

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.17"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
 ExpressionTree getExpression()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getExpression

ExpressionTree getExpression()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Scope

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface Scope

public interface Scope

Interface for determining locally available program elements, such as local variables and imports. Upon creation, a Scope is associated with a given program position; for example, a tree node. This position may be used to infer an enclosing method and/or class.

A Scope does not itself contain the details of the elements corresponding to the parameters, methods and fields of the methods and classes containing its position. However, these elements can be determined from the enclosing elements.

Scopes may be contained in an enclosing scope. The outermost scope contains those elements available via "star import" declarations; the scope within that contains the top level elements of the compilation unit, including any named imports.

Since:
1.6

Method Summary
TypeElement | getEnclosingClass() Returns the innermost type element containing the position of this scope
ExecutableElement | getEnclosingMethod() Returns the innermost executable element containing the position of this scope.
Scope | getEnclosingScope() Returns the enclosing scope.
Iterable<? extends Element> | getLocalElements() Returns the elements directly contained in this scope.

Method Detail

getEnclosingScope

Scope getEnclosingScope()
Returns the enclosing scope.

getEnclosingClass

TypeElement getEnclosingClass()
Returns the innermost type element containing the position of this scope

getEnclosingMethod

ExecutableElement getEnclosingMethod()
Returns the innermost executable element containing the position of this scope.

getLocalElements

Iterable<? extends Element> getLocalElements()
Returns the elements directly contained in this scope.

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


StatementTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface StatementTree

All Superinterfaces:
Tree
All Known Subinterfaces:
AssertTree, BlockTree, BreakTree, ClassTree, ContinueTree, DoWhileLoopTree, EmptyStatementTree, EnhancedForLoopTree, ExpressionStatementTree, ForLoopTree, IfTree, LabeledStatementTree, ReturnTree, SwitchTree, SynchronizedTree, ThrowTree, TryTree, VariableTree, WhileLoopTree
public interface StatementTree
extends Tree

A tree node used as the base class for the different kinds of statements.

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, chapter 14"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


SwitchTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface SwitchTree

All Superinterfaces:
StatementTree, Tree
public interface SwitchTree
extends StatementTree

A tree node for a 'switch' statement. For example:

   switch ( expression ) {
     cases
   }

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.11"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
List<? extends CaseTree> | getCases()
ExpressionTree | getExpression()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getExpression

ExpressionTree getExpression()

getCases

List<? extends CaseTree> getCases()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


SynchronizedTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface SynchronizedTree

All Superinterfaces:
StatementTree, Tree
public interface SynchronizedTree
extends StatementTree

A tree node for a 'synchronized' statement. For example:

   synchronized ( expression )
       block

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.19"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
BlockTree | getBlock()
ExpressionTree | getExpression()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getExpression

ExpressionTree getExpression()

getBlock

BlockTree getBlock()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


ThrowTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface ThrowTree

All Superinterfaces:
StatementTree, Tree
public interface ThrowTree
extends StatementTree

A tree node for a 'throw' statement. For example:

   throw expression;

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.18"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
 ExpressionTree getExpression()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getExpression

ExpressionTree getExpression()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Tree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface Tree

All Known Subinterfaces:
AnnotationTree, ArrayAccessTree, ArrayTypeTree, AssertTree, AssignmentTree, BinaryTree, BlockTree, BreakTree, CaseTree, CatchTree, ClassTree, CompilationUnitTree, CompoundAssignmentTree, ConditionalExpressionTree, ContinueTree, DoWhileLoopTree, EmptyStatementTree, EnhancedForLoopTree, ErroneousTree, ExpressionStatementTree, ExpressionTree, ForLoopTree, IdentifierTree, IfTree, ImportTree, InstanceOfTree, LabeledStatementTree, LiteralTree, MemberSelectTree, MethodInvocationTree, MethodTree, ModifiersTree, NewArrayTree, NewClassTree, ParameterizedTypeTree, ParenthesizedTree, PrimitiveTypeTree, ReturnTree, StatementTree, SwitchTree, SynchronizedTree, ThrowTree, TryTree, TypeCastTree, TypeParameterTree, UnaryTree, VariableTree, WhileLoopTree, WildcardTree
public interface Tree

Common interface for all nodes in an abstract syntax tree.

WARNING: This interface and its sub-interfaces are subject to change as the Java™ programming language evolves. These interfaces are implemented by Sun's Java compiler (javac) and should not be implemented either directly or indirectly by other applications.

Since:
1.6

Nested Class Summary
static class Tree.Kind
Enumerates all kinds of trees.
Method Summary
<R,D> R
accept(TreeVisitor<R,D> visitor, D data)
Accept method used to implement the visitor pattern.
 Tree.Kind getKind()
Gets the kind of this tree.

Method Detail

getKind

Tree.Kind getKind()
Gets the kind of this tree.

Returns:
the kind of this tree.

accept

<R,D> R accept(TreeVisitor<R,D> visitor,
               D data)
Accept method used to implement the visitor pattern. The visitor pattern is used to implement operations on trees.

Type Parameters:
R - result type of this operation.
D - type of additonal data.
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Tree.Kind

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

com.sun.source.tree
Enum Tree.Kind

java.lang.Object
    extended by  java.lang.Enum<Tree.Kind>
        extended by  com.sun.source.tree.Tree.Kind
All Implemented Interfaces:
Serializable, Comparable<Tree.Kind>
Enclosing interface:
Tree
public static enum Tree.Kind
extends Enum<Tree.Kind>

Enumerates all kinds of trees.

Enum Constant Summary
AND
Used for instances of BinaryTree representing bitwise and logical "and" &.
AND_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing bitwise and logical "and" assignment &=.
ANNOTATION
Used for instances of AnnotationTree.
ARRAY_ACCESS
Used for instances of ArrayAccessTree.
ARRAY_TYPE
Used for instances of ArrayTypeTree.
ASSERT
Used for instances of AssertTree.
ASSIGNMENT
Used for instances of AssignmentTree.
BITWISE_COMPLEMENT
Used for instances of UnaryTree representing bitwise complement operator ~.
BLOCK
Used for instances of BlockTree.
BOOLEAN_LITERAL
Used for instances of LiteralTree representing a boolean literal expression of type boolean.
BREAK
Used for instances of BreakTree.
CASE
Used for instances of CaseTree.
CATCH
Used for instances of CatchTree.
CHAR_LITERAL
Used for instances of LiteralTree representing a character literal expression of type char.
CLASS
Used for instances of ClassTree.
COMPILATION_UNIT
Used for instances of CompilationUnitTree.
CONDITIONAL_AND
Used for instances of BinaryTree representing conditional-and &&.
CONDITIONAL_EXPRESSION
Used for instances of ConditionalExpressionTree.
CONDITIONAL_OR
Used for instances of BinaryTree representing conditional-or ||.
CONTINUE
Used for instances of ContinueTree.
DIVIDE
Used for instances of BinaryTree representing division /.
DIVIDE_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing division assignment /=.
DO_WHILE_LOOP
Used for instances of DoWhileLoopTree.
DOUBLE_LITERAL
Used for instances of LiteralTree representing a floating-point literal expression of type double.
EMPTY_STATEMENT
Used for instances of EmptyStatementTree.
ENHANCED_FOR_LOOP
Used for instances of EnhancedForLoopTree.
EQUAL_TO
Used for instances of BinaryTree representing equal-to ==.
ERRONEOUS
Used for instances of ErroneousTree.
EXPRESSION_STATEMENT
Used for instances of ExpressionStatementTree.
EXTENDS_WILDCARD
Used for instances of WildcardTree representing an extends bounded wildcard type argument.
FLOAT_LITERAL
Used for instances of LiteralTree representing a floating-point literal expression of type float.
FOR_LOOP
Used for instances of ForLoopTree.
GREATER_THAN
Used for instances of BinaryTree representing greater-than >.
GREATER_THAN_EQUAL
Used for instances of BinaryTree representing greater-than-equal >=.
IDENTIFIER
Used for instances of IdentifierTree.
IF
Used for instances of IfTree.
IMPORT
Used for instances of ImportTree.
INSTANCE_OF
Used for instances of InstanceOfTree.
INT_LITERAL
Used for instances of LiteralTree representing an integral literal expression of type int.
LABELED_STATEMENT
Used for instances of LabeledStatementTree.
LEFT_SHIFT
Used for instances of BinaryTree representing left shift <<.
LEFT_SHIFT_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing left shift assignment <<=.
LESS_THAN
Used for instances of BinaryTree representing less-than <.
LESS_THAN_EQUAL
Used for instances of BinaryTree representing less-than-equal <=.
LOGICAL_COMPLEMENT
Used for instances of UnaryTree representing logical complement operator !.
LONG_LITERAL
Used for instances of LiteralTree representing an integral literal expression of type long.
MEMBER_SELECT
Used for instances of MemberSelectTree.
METHOD
Used for instances of MethodTree.
METHOD_INVOCATION
Used for instances of MethodInvocationTree.
MINUS
Used for instances of BinaryTree representing subtraction -.
MINUS_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing subtraction assignment -=.
MODIFIERS
Used for instances of ModifiersTree.
MULTIPLY
Used for instances of BinaryTree representing multiplication *.
MULTIPLY_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing multiplication assignment *=.
NEW_ARRAY
Used for instances of NewArrayTree.
NEW_CLASS
Used for instances of NewClassTree.
NOT_EQUAL_TO
Used for instances of BinaryTree representing not-equal-to !=.
NULL_LITERAL
Used for instances of LiteralTree representing the use of null.
OR
Used for instances of BinaryTree representing bitwise and logical "or" |.
OR_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing bitwise and logical "or" assignment |=.
OTHER
An implementation-reserved node.
PARAMETERIZED_TYPE
Used for instances of ParameterizedTypeTree.
PARENTHESIZED
Used for instances of ParenthesizedTree.
PLUS
Used for instances of BinaryTree representing addition or string concatenation +.
PLUS_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing addition or string concatenation assignment +=.
POSTFIX_DECREMENT
Used for instances of UnaryTree representing postfix decrement operator --.
POSTFIX_INCREMENT
Used for instances of UnaryTree representing postfix increment operator ++.
PREFIX_DECREMENT
Used for instances of UnaryTree representing prefix decrement operator --.
PREFIX_INCREMENT
Used for instances of UnaryTree representing prefix increment operator ++.
PRIMITIVE_TYPE
Used for instances of PrimitiveTypeTree.
REMAINDER
Used for instances of BinaryTree representing remainder %.
REMAINDER_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing remainder assignment %=.
RETURN
Used for instances of ReturnTree.
RIGHT_SHIFT
Used for instances of BinaryTree representing right shift >>.
RIGHT_SHIFT_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing right shift assignment >>=.
STRING_LITERAL
Used for instances of LiteralTree representing a string literal expression of type String.
SUPER_WILDCARD
Used for instances of WildcardTree representing a super bounded wildcard type argument.
SWITCH
Used for instances of SwitchTree.
SYNCHRONIZED
Used for instances of SynchronizedTree.
THROW
Used for instances of ThrowTree.
TRY
Used for instances of TryTree.
TYPE_CAST
Used for instances of TypeCastTree.
TYPE_PARAMETER
Used for instances of TypeParameterTree.
UNARY_MINUS
Used for instances of UnaryTree representing unary minus operator -.
UNARY_PLUS
Used for instances of UnaryTree representing unary plus operator +.
UNBOUNDED_WILDCARD
Used for instances of WildcardTree representing an unbounded wildcard type argument.
UNSIGNED_RIGHT_SHIFT
Used for instances of BinaryTree representing unsigned right shift >>>.
UNSIGNED_RIGHT_SHIFT_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing unsigned right shift assignment >>>=.
VARIABLE
Used for instances of VariableTree.
WHILE_LOOP
Used for instances of WhileLoopTree.
XOR
Used for instances of BinaryTree representing bitwise and logical "xor" ^.
XOR_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing bitwise and logical "xor" assignment ^=.
Method Summary
Class<? extends Tree> | asInterface()
static Tree.Kind | valueOf(String name) Returns the enum constant of this type with the specified name.
static Tree.Kind[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

ANNOTATION

public static final Tree.Kind ANNOTATION
Used for instances of AnnotationTree.

ARRAY_ACCESS

public static final Tree.Kind ARRAY_ACCESS
Used for instances of ArrayAccessTree.

ARRAY_TYPE

public static final Tree.Kind ARRAY_TYPE
Used for instances of ArrayTypeTree.

ASSERT

public static final Tree.Kind ASSERT
Used for instances of AssertTree.

ASSIGNMENT

public static final Tree.Kind ASSIGNMENT
Used for instances of AssignmentTree.

BLOCK

public static final Tree.Kind BLOCK
Used for instances of BlockTree.

BREAK

public static final Tree.Kind BREAK
Used for instances of BreakTree.

CASE

public static final Tree.Kind CASE
Used for instances of CaseTree.

CATCH

public static final Tree.Kind CATCH
Used for instances of CatchTree.

CLASS

public static final Tree.Kind CLASS
Used for instances of ClassTree.

COMPILATION_UNIT

public static final Tree.Kind COMPILATION_UNIT
Used for instances of CompilationUnitTree.

CONDITIONAL_EXPRESSION

public static final Tree.Kind CONDITIONAL_EXPRESSION
Used for instances of ConditionalExpressionTree.

CONTINUE

public static final Tree.Kind CONTINUE
Used for instances of ContinueTree.

DO_WHILE_LOOP

public static final Tree.Kind DO_WHILE_LOOP
Used for instances of DoWhileLoopTree.

ENHANCED_FOR_LOOP

public static final Tree.Kind ENHANCED_FOR_LOOP
Used for instances of EnhancedForLoopTree.

EXPRESSION_STATEMENT

public static final Tree.Kind EXPRESSION_STATEMENT
Used for instances of ExpressionStatementTree.

MEMBER_SELECT

public static final Tree.Kind MEMBER_SELECT
Used for instances of MemberSelectTree.

FOR_LOOP

public static final Tree.Kind FOR_LOOP
Used for instances of ForLoopTree.

IDENTIFIER

public static final Tree.Kind IDENTIFIER
Used for instances of IdentifierTree.

IF

public static final Tree.Kind IF
Used for instances of IfTree.

IMPORT

public static final Tree.Kind IMPORT
Used for instances of ImportTree.

INSTANCE_OF

public static final Tree.Kind INSTANCE_OF
Used for instances of InstanceOfTree.

LABELED_STATEMENT

public static final Tree.Kind LABELED_STATEMENT
Used for instances of LabeledStatementTree.

METHOD

public static final Tree.Kind METHOD
Used for instances of MethodTree.

METHOD_INVOCATION

public static final Tree.Kind METHOD_INVOCATION
Used for instances of MethodInvocationTree.

MODIFIERS

public static final Tree.Kind MODIFIERS
Used for instances of ModifiersTree.

NEW_ARRAY

public static final Tree.Kind NEW_ARRAY
Used for instances of NewArrayTree.

NEW_CLASS

public static final Tree.Kind NEW_CLASS
Used for instances of NewClassTree.

PARENTHESIZED

public static final Tree.Kind PARENTHESIZED
Used for instances of ParenthesizedTree.

PRIMITIVE_TYPE

public static final Tree.Kind PRIMITIVE_TYPE
Used for instances of PrimitiveTypeTree.

RETURN

public static final Tree.Kind RETURN
Used for instances of ReturnTree.

EMPTY_STATEMENT

public static final Tree.Kind EMPTY_STATEMENT
Used for instances of EmptyStatementTree.

SWITCH

public static final Tree.Kind SWITCH
Used for instances of SwitchTree.

SYNCHRONIZED

public static final Tree.Kind SYNCHRONIZED
Used for instances of SynchronizedTree.

THROW

public static final Tree.Kind THROW
Used for instances of ThrowTree.

TRY

public static final Tree.Kind TRY
Used for instances of TryTree.

PARAMETERIZED_TYPE

public static final Tree.Kind PARAMETERIZED_TYPE
Used for instances of ParameterizedTypeTree.

TYPE_CAST

public static final Tree.Kind TYPE_CAST
Used for instances of TypeCastTree.

TYPE_PARAMETER

public static final Tree.Kind TYPE_PARAMETER
Used for instances of TypeParameterTree.

VARIABLE

public static final Tree.Kind VARIABLE
Used for instances of VariableTree.

WHILE_LOOP

public static final Tree.Kind WHILE_LOOP
Used for instances of WhileLoopTree.

POSTFIX_INCREMENT

public static final Tree.Kind POSTFIX_INCREMENT
Used for instances of UnaryTree representing postfix increment operator ++.

POSTFIX_DECREMENT

public static final Tree.Kind POSTFIX_DECREMENT
Used for instances of UnaryTree representing postfix decrement operator --.

PREFIX_INCREMENT

public static final Tree.Kind PREFIX_INCREMENT
Used for instances of UnaryTree representing prefix increment operator ++.

PREFIX_DECREMENT

public static final Tree.Kind PREFIX_DECREMENT
Used for instances of UnaryTree representing prefix decrement operator --.

UNARY_PLUS

public static final Tree.Kind UNARY_PLUS
Used for instances of UnaryTree representing unary plus operator +.

UNARY_MINUS

public static final Tree.Kind UNARY_MINUS
Used for instances of UnaryTree representing unary minus operator -.

BITWISE_COMPLEMENT

public static final Tree.Kind BITWISE_COMPLEMENT
Used for instances of UnaryTree representing bitwise complement operator ~.

LOGICAL_COMPLEMENT

public static final Tree.Kind LOGICAL_COMPLEMENT
Used for instances of UnaryTree representing logical complement operator !.

MULTIPLY

public static final Tree.Kind MULTIPLY
Used for instances of BinaryTree representing multiplication *.

DIVIDE

public static final Tree.Kind DIVIDE
Used for instances of BinaryTree representing division /.

REMAINDER

public static final Tree.Kind REMAINDER
Used for instances of BinaryTree representing remainder %.

PLUS

public static final Tree.Kind PLUS
Used for instances of BinaryTree representing addition or string concatenation +.

MINUS

public static final Tree.Kind MINUS
Used for instances of BinaryTree representing subtraction -.

LEFT_SHIFT

public static final Tree.Kind LEFT_SHIFT
Used for instances of BinaryTree representing left shift <<.

RIGHT_SHIFT

public static final Tree.Kind RIGHT_SHIFT
Used for instances of BinaryTree representing right shift >>.

UNSIGNED_RIGHT_SHIFT

public static final Tree.Kind UNSIGNED_RIGHT_SHIFT
Used for instances of BinaryTree representing unsigned right shift >>>.

LESS_THAN

public static final Tree.Kind LESS_THAN
Used for instances of BinaryTree representing less-than <.

GREATER_THAN

public static final Tree.Kind GREATER_THAN
Used for instances of BinaryTree representing greater-than >.

LESS_THAN_EQUAL

public static final Tree.Kind LESS_THAN_EQUAL
Used for instances of BinaryTree representing less-than-equal <=.

GREATER_THAN_EQUAL

public static final Tree.Kind GREATER_THAN_EQUAL
Used for instances of BinaryTree representing greater-than-equal >=.

EQUAL_TO

public static final Tree.Kind EQUAL_TO
Used for instances of BinaryTree representing equal-to ==.

NOT_EQUAL_TO

public static final Tree.Kind NOT_EQUAL_TO
Used for instances of BinaryTree representing not-equal-to !=.

AND

public static final Tree.Kind AND
Used for instances of BinaryTree representing bitwise and logical "and" &.

XOR

public static final Tree.Kind XOR
Used for instances of BinaryTree representing bitwise and logical "xor" ^.

OR

public static final Tree.Kind OR
Used for instances of BinaryTree representing bitwise and logical "or" |.

CONDITIONAL_AND

public static final Tree.Kind CONDITIONAL_AND
Used for instances of BinaryTree representing conditional-and &&.

CONDITIONAL_OR

public static final Tree.Kind CONDITIONAL_OR
Used for instances of BinaryTree representing conditional-or ||.

MULTIPLY_ASSIGNMENT

public static final Tree.Kind MULTIPLY_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing multiplication assignment *=.

DIVIDE_ASSIGNMENT

public static final Tree.Kind DIVIDE_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing division assignment /=.

REMAINDER_ASSIGNMENT

public static final Tree.Kind REMAINDER_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing remainder assignment %=.

PLUS_ASSIGNMENT

public static final Tree.Kind PLUS_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing addition or string concatenation assignment +=.

MINUS_ASSIGNMENT

public static final Tree.Kind MINUS_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing subtraction assignment -=.

LEFT_SHIFT_ASSIGNMENT

public static final Tree.Kind LEFT_SHIFT_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing left shift assignment <<=.

RIGHT_SHIFT_ASSIGNMENT

public static final Tree.Kind RIGHT_SHIFT_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing right shift assignment >>=.

UNSIGNED_RIGHT_SHIFT_ASSIGNMENT

public static final Tree.Kind UNSIGNED_RIGHT_SHIFT_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing unsigned right shift assignment >>>=.

AND_ASSIGNMENT

public static final Tree.Kind AND_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing bitwise and logical "and" assignment &=.

XOR_ASSIGNMENT

public static final Tree.Kind XOR_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing bitwise and logical "xor" assignment ^=.

OR_ASSIGNMENT

public static final Tree.Kind OR_ASSIGNMENT
Used for instances of CompoundAssignmentTree representing bitwise and logical "or" assignment |=.

INT_LITERAL

public static final Tree.Kind INT_LITERAL
Used for instances of LiteralTree representing an integral literal expression of type int.

LONG_LITERAL

public static final Tree.Kind LONG_LITERAL
Used for instances of LiteralTree representing an integral literal expression of type long.

FLOAT_LITERAL

public static final Tree.Kind FLOAT_LITERAL
Used for instances of LiteralTree representing a floating-point literal expression of type float.

DOUBLE_LITERAL

public static final Tree.Kind DOUBLE_LITERAL
Used for instances of LiteralTree representing a floating-point literal expression of type double.

BOOLEAN_LITERAL

public static final Tree.Kind BOOLEAN_LITERAL
Used for instances of LiteralTree representing a boolean literal expression of type boolean.

CHAR_LITERAL

public static final Tree.Kind CHAR_LITERAL
Used for instances of LiteralTree representing a character literal expression of type char.

STRING_LITERAL

public static final Tree.Kind STRING_LITERAL
Used for instances of LiteralTree representing a string literal expression of type String.

NULL_LITERAL

public static final Tree.Kind NULL_LITERAL
Used for instances of LiteralTree representing the use of null.

UNBOUNDED_WILDCARD

public static final Tree.Kind UNBOUNDED_WILDCARD
Used for instances of WildcardTree representing an unbounded wildcard type argument.

EXTENDS_WILDCARD

public static final Tree.Kind EXTENDS_WILDCARD
Used for instances of WildcardTree representing an extends bounded wildcard type argument.

SUPER_WILDCARD

public static final Tree.Kind SUPER_WILDCARD
Used for instances of WildcardTree representing a super bounded wildcard type argument.

ERRONEOUS

public static final Tree.Kind ERRONEOUS
Used for instances of ErroneousTree.

OTHER

public static final Tree.Kind OTHER
An implementation-reserved node. This is the not the node you are looking for.

Method Detail

values

public static Tree.Kind[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (Tree.Kind c : Tree.Kind.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static Tree.Kind valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null

asInterface

public Class<? extends Tree> asInterface()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


TreeVisitor

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface TreeVisitor<R,P>

Type Parameters:
R - the return type of this visitor's methods. Use Void for visitors that do not need to return results.
P - the type of the additional parameter to this visitor's methods. Use Void for visitors that do not need an additional parameter.
All Known Implementing Classes:
SimpleTreeVisitor, TreePathScanner, TreeScanner
public interface TreeVisitor<R,P>

A visitor of trees, in the style of the visitor design pattern. Classes implementing this interface are used to operate on a tree when the kind of tree is unknown at compile time. When a visitor is passed to an tree's accept method, the visitXYZ method most applicable to that tree is invoked.

Classes implementing this interface may or may not throw a NullPointerException if the additional parameter p is null; see documentation of the implementing class for details.

WARNING: It is possible that methods will be added to this interface to accommodate new, currently unknown, language structures added to future versions of the Java™ programming language. Therefore, visitor classes directly implementing this interface may be source incompatible with future versions of the platform.

Since:
1.6

Method Summary
R | visitAnnotation(AnnotationTree node, P p)
R | visitArrayAccess(ArrayAccessTree node, P p)
R | visitArrayType(ArrayTypeTree node, P p)
R | visitAssert(AssertTree node, P p)
R | visitAssignment(AssignmentTree node, P p)
R | visitBinary(BinaryTree node, P p)
R | visitBlock(BlockTree node, P p)
R | visitBreak(BreakTree node, P p)
R | visitCase(CaseTree node, P p)
R | visitCatch(CatchTree node, P p)
R | visitClass(ClassTree node, P p)
R | visitCompilationUnit(CompilationUnitTree node, P p)
R | visitCompoundAssignment(CompoundAssignmentTree node, P p)
R | visitConditionalExpression(ConditionalExpressionTree node, P p)
R | visitContinue(ContinueTree node, P p)
R | visitDoWhileLoop(DoWhileLoopTree node, P p)
R | visitEmptyStatement(EmptyStatementTree node, P p)
R | visitEnhancedForLoop(EnhancedForLoopTree node, P p)
R | visitErroneous(ErroneousTree node, P p)
R | visitExpressionStatement(ExpressionStatementTree node, P p)
R | visitForLoop(ForLoopTree node, P p)
R | visitIdentifier(IdentifierTree node, P p)
R | visitIf(IfTree node, P p)
R | visitImport(ImportTree node, P p)
R | visitInstanceOf(InstanceOfTree node, P p)
R | visitLabeledStatement(LabeledStatementTree node, P p)
R | visitLiteral(LiteralTree node, P p)
R | visitMemberSelect(MemberSelectTree node, P p)
R | visitMethod(MethodTree node, P p)
R | visitMethodInvocation(MethodInvocationTree node, P p)
R | visitModifiers(ModifiersTree node, P p)
R | visitNewArray(NewArrayTree node, P p)
R | visitNewClass(NewClassTree node, P p)
R | visitOther(Tree node, P p)
R | visitParameterizedType(ParameterizedTypeTree node, P p)
R | visitParenthesized(ParenthesizedTree node, P p)
R | visitPrimitiveType(PrimitiveTypeTree node, P p)
R | visitReturn(ReturnTree node, P p)
R | visitSwitch(SwitchTree node, P p)
R | visitSynchronized(SynchronizedTree node, P p)
R | visitThrow(ThrowTree node, P p)
R | visitTry(TryTree node, P p)
R | visitTypeCast(TypeCastTree node, P p)
R | visitTypeParameter(TypeParameterTree node, P p)
R | visitUnary(UnaryTree node, P p)
R | visitVariable(VariableTree node, P p)
R | visitWhileLoop(WhileLoopTree node, P p)
R | visitWildcard(WildcardTree node, P p)

Method Detail

visitAnnotation

R visitAnnotation(AnnotationTree node,
                  P p)

visitMethodInvocation

R visitMethodInvocation(MethodInvocationTree node,
                        P p)

visitAssert

R visitAssert(AssertTree node,
              P p)

visitAssignment

R visitAssignment(AssignmentTree node,
                  P p)

visitCompoundAssignment

R visitCompoundAssignment(CompoundAssignmentTree node,
                          P p)

visitBinary

R visitBinary(BinaryTree node,
              P p)

visitBlock

R visitBlock(BlockTree node,
             P p)

visitBreak

R visitBreak(BreakTree node,
             P p)

visitCase

R visitCase(CaseTree node,
            P p)

visitCatch

R visitCatch(CatchTree node,
             P p)

visitClass

R visitClass(ClassTree node,
             P p)

visitConditionalExpression

R visitConditionalExpression(ConditionalExpressionTree node,
                             P p)

visitContinue

R visitContinue(ContinueTree node,
                P p)

visitDoWhileLoop

R visitDoWhileLoop(DoWhileLoopTree node,
                   P p)

visitErroneous

R visitErroneous(ErroneousTree node,
                 P p)

visitExpressionStatement

R visitExpressionStatement(ExpressionStatementTree node,
                           P p)

visitEnhancedForLoop

R visitEnhancedForLoop(EnhancedForLoopTree node,
                       P p)

visitForLoop

R visitForLoop(ForLoopTree node,
               P p)

visitIdentifier

R visitIdentifier(IdentifierTree node,
                  P p)

visitIf

R visitIf(IfTree node,
          P p)

visitImport

R visitImport(ImportTree node,
              P p)

visitArrayAccess

R visitArrayAccess(ArrayAccessTree node,
                   P p)

visitLabeledStatement

R visitLabeledStatement(LabeledStatementTree node,
                        P p)

visitLiteral

R visitLiteral(LiteralTree node,
               P p)

visitMethod

R visitMethod(MethodTree node,
              P p)

visitModifiers

R visitModifiers(ModifiersTree node,
                 P p)

visitNewArray

R visitNewArray(NewArrayTree node,
                P p)

visitNewClass

R visitNewClass(NewClassTree node,
                P p)

visitParenthesized

R visitParenthesized(ParenthesizedTree node,
                     P p)

visitReturn

R visitReturn(ReturnTree node,
              P p)

visitMemberSelect

R visitMemberSelect(MemberSelectTree node,
                    P p)

visitEmptyStatement

R visitEmptyStatement(EmptyStatementTree node,
                      P p)

visitSwitch

R visitSwitch(SwitchTree node,
              P p)

visitSynchronized

R visitSynchronized(SynchronizedTree node,
                    P p)

visitThrow

R visitThrow(ThrowTree node,
             P p)

visitCompilationUnit

R visitCompilationUnit(CompilationUnitTree node,
                       P p)

visitTry

R visitTry(TryTree node,
           P p)

visitParameterizedType

R visitParameterizedType(ParameterizedTypeTree node,
                         P p)

visitArrayType

R visitArrayType(ArrayTypeTree node,
                 P p)

visitTypeCast

R visitTypeCast(TypeCastTree node,
                P p)

visitPrimitiveType

R visitPrimitiveType(PrimitiveTypeTree node,
                     P p)

visitTypeParameter

R visitTypeParameter(TypeParameterTree node,
                     P p)

visitInstanceOf

R visitInstanceOf(InstanceOfTree node,
                  P p)

visitUnary

R visitUnary(UnaryTree node,
             P p)

visitVariable

R visitVariable(VariableTree node,
                P p)

visitWhileLoop

R visitWhileLoop(WhileLoopTree node,
                 P p)

visitWildcard

R visitWildcard(WildcardTree node,
                P p)

visitOther

R visitOther(Tree node,
             P p)
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


TryTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface TryTree

All Superinterfaces:
StatementTree, Tree
public interface TryTree
extends StatementTree

A tree node for a 'try' statement. For example:

   try
       block
   catches
   finally
       finallyBlock

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.20"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
BlockTree | getBlock()
List<? extends CatchTree> | getCatches()
BlockTree | getFinallyBlock()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getBlock

BlockTree getBlock()

getCatches

List<? extends CatchTree> getCatches()

getFinallyBlock

BlockTree getFinallyBlock()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


TypeCastTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface TypeCastTree

All Superinterfaces:
ExpressionTree, Tree
public interface TypeCastTree
extends ExpressionTree

A tree node for a type cast expression. For example:

   ( type ) expression

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 15.16"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
ExpressionTree | getExpression()
Tree | getType()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getType

Tree getType()

getExpression

ExpressionTree getExpression()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


TypeParameterTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface TypeParameterTree

All Superinterfaces:
Tree
public interface TypeParameterTree
extends Tree

A tree node for a type parameter. For example:

   name

   name extends bounds

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 4.4"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
List<? extends Tree> | getBounds()
Name | getName()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getName

Name getName()

getBounds

List<? extends Tree> getBounds()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


UnaryTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface UnaryTree

All Superinterfaces:
ExpressionTree, Tree
public interface UnaryTree
extends ExpressionTree

A tree node for postfix and unary expressions. Use getKind to determine the kind of operator. For example:

   operator expression

   expression operator

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, sections 15.14 and 15.15"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
 ExpressionTree getExpression()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getExpression

ExpressionTree getExpression()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


VariableTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface VariableTree

All Superinterfaces:
StatementTree, Tree
public interface VariableTree
extends StatementTree

A tree node for a variable declaration. For example:

   modifiers type name initializer ;

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, sections 8.3 and 14.4"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
ExpressionTree | getInitializer()
ModifiersTree | getModifiers()
Name | getName()
Tree | getType()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getModifiers

ModifiersTree getModifiers()

getName

Name getName()

getType

Tree getType()

getInitializer

ExpressionTree getInitializer()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


WhileLoopTree

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface WhileLoopTree

All Superinterfaces:
StatementTree, Tree
public interface WhileLoopTree
extends StatementTree

A tree node for a 'while' loop statement. For example:

   while ( condition )
     statement

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 14.12"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
ExpressionTree | getCondition()
StatementTree | getStatement()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getCondition

ExpressionTree getCondition()

getStatement

StatementTree getStatement()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


WildcardTree

Compiler Tree API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.source.tree
Interface WildcardTree

All Superinterfaces:
Tree
public interface WildcardTree
extends Tree

A tree node for a wildcard type argument. Use getKind to determine the kind of bound. For example:

   ?

   ? extends bound

   ? super bound

Since:
1.6
See Also:
"The Java Language Specification, 3rd ed, section 4.5.1"

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.source.tree.Tree
Tree.Kind
Method Summary
 Tree getBound()
Methods inherited from interface com.sun.source.tree.Tree
accept, getKind

Method Detail

getBound

Tree getBound()
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


util

Compiler Tree API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package com.sun.source.util

Provides utilities for operations on abstract syntax trees (AST).

See:
Description

Interface Summary
SourcePositions | Provides methods to obtain the position of a Tree within a CompilationUnit.
TaskListener | Provides a listener to monitor the activity of the Sun Java Compiler, javac.

Class Summary
JavacTask | Provides access to functionality specific to the Sun Java Compiler, javac.
SimpleTreeVisitor<R,P> | A simple visitor for tree nodes.
TaskEvent | Provides details about work that has been done by the Sun Java Compiler, javac.
TreePath | A path of tree nodes, typically used to represent the sequence of ancestor nodes of a tree node up to the top level CompilationUnitTree node.
TreePathScanner<R,P> | A TreeVisitor that visits all the child tree nodes, and provides support for maintaining a path for the parent nodes.
Trees | Bridges JSR 199, JSR 269, and the Tree API.
TreeScanner<R,P> | A TreeVisitor that visits all the child tree nodes.

Enum Summary
TaskEvent.Kind Kind of task event.

Package com.sun.source.util Description

Provides utilities for operations on abstract syntax trees (AST).

Since:
1.6
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


com.sun.source.util Class Hierarchy

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Hierarchy For Package com.sun.source.util

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • com.sun.source.util.JavacTask (implements javax.tools.JavaCompiler.CompilationTask)
    • com.sun.source.util.SimpleTreeVisitor<R,P> (implements com.sun.source.tree.TreeVisitor<R,P>)
    • com.sun.source.util.TaskEvent
    • com.sun.source.util.TreePath (implements java.lang.Iterable<T>)
    • com.sun.source.util.Trees
    • com.sun.source.util.TreeScanner<R,P> (implements com.sun.source.tree.TreeVisitor<R,P>)
      • com.sun.source.util.TreePathScanner<R,P>

Interface Hierarchy

  • com.sun.source.util.SourcePositions
  • com.sun.source.util.TaskListener

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • com.sun.source.util.TaskEvent.Kind
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Package com.sun.source.util

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Package
com.sun.source.util

Packages that use com.sun.source.util
com.sun.source.util Provides utilities for operations on abstract syntax trees (AST).

Classes in com.sun.source.util used by com.sun.source.util
SourcePositions
Provides methods to obtain the position of a Tree within a CompilationUnit.
TaskEvent
Provides details about work that has been done by the Sun Java Compiler, javac.
TaskEvent.Kind
Kind of task event.
TaskListener
Provides a listener to monitor the activity of the Sun Java Compiler, javac.
TreePath
A path of tree nodes, typically used to represent the sequence of ancestor nodes of a tree node up to the top level CompilationUnitTree node.
Trees
Bridges JSR 199, JSR 269, and the Tree API.
TreeScanner
A TreeVisitor that visits all the child tree nodes.

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.source.util.JavacTask

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.source.util.JavacTask

No usage of com.sun.source.util.JavacTask

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.source.util.SimpleTreeVisitor

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.source.util.SimpleTreeVisitor

No usage of com.sun.source.util.SimpleTreeVisitor

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.source.util.TaskEvent

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.source.util.TaskEvent

Packages that use TaskEvent
com.sun.source.util Provides utilities for operations on abstract syntax trees (AST).

Uses of TaskEvent in com.sun.source.util

Methods in com.sun.source.util with parameters of type TaskEvent
void | TaskListener.finished(TaskEvent e)
void | TaskListener.started(TaskEvent e)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.source.util.TaskEvent.Kind

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.source.util.TaskEvent.Kind

Packages that use TaskEvent.Kind
com.sun.source.util Provides utilities for operations on abstract syntax trees (AST).

Uses of TaskEvent.Kind in com.sun.source.util

Methods in com.sun.source.util that return TaskEvent.Kind
TaskEvent.Kind | TaskEvent.getKind()
static TaskEvent.Kind | TaskEvent.Kind.valueOf(String name) Returns the enum constant of this type with the specified name.
static TaskEvent.Kind[] | TaskEvent.Kind.values() Returns an array containing the constants of this enum type, in the order they are declared.

Constructors in com.sun.source.util with parameters of type TaskEvent.Kind
TaskEvent(TaskEvent.Kind kind)
TaskEvent(TaskEvent.Kind kind, CompilationUnitTree unit)
TaskEvent(TaskEvent.Kind kind, CompilationUnitTree unit, TypeElement clazz)
TaskEvent(TaskEvent.Kind kind, JavaFileObject sourceFile)

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.source.util.TreePath

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.source.util.TreePath

Packages that use TreePath
com.sun.source.util Provides utilities for operations on abstract syntax trees (AST).

Uses of TreePath in com.sun.source.util

Methods in com.sun.source.util that return TreePath
TreePath | TreePathScanner.getCurrentPath() Get the current path for the node, as built up by the currently active set of scan calls.
TreePath | TreePath.getParentPath() Get the path for the enclosing node, or null if there is no enclosing node.
static TreePath | TreePath.getPath(CompilationUnitTree unit, Tree target) Gets a tree path for a tree node within a compilation unit.
abstract TreePath | Trees.getPath(CompilationUnitTree unit, Tree node) Gets the path to tree node within the specified compilation unit.
abstract TreePath | Trees.getPath(Element e) Gets the TreePath node for a given Element.
abstract TreePath | Trees.getPath(Element e, AnnotationMirror a) Gets the TreePath node for an AnnotationMirror on a given Element.
abstract TreePath | Trees.getPath(Element e, AnnotationMirror a, AnnotationValue v) Gets the TreePath node for an AnnotationValue for an AnnotationMirror on a given Element.
static TreePath | TreePath.getPath(TreePath path, Tree target) Gets a tree path for a tree node within a subtree identified by a TreePath object.

Methods in com.sun.source.util with parameters of type TreePath
abstract Element | Trees.getElement(TreePath path) Gets the Element for the Tree node identified by a given TreePath.
static TreePath | TreePath.getPath(TreePath path, Tree target) Gets a tree path for a tree node within a subtree identified by a TreePath object.
abstract Scope | Trees.getScope(TreePath path) Gets the Scope for the Tree node identified by a given TreePath.
abstract TypeMirror | Trees.getTypeMirror(TreePath path) Gets the TypeMirror for the Tree node identified by a given TreePath.
R | TreePathScanner.scan(TreePath path, P p) Scan a tree from a position identified by a TreePath.

Constructors in com.sun.source.util with parameters of type TreePath
TreePath(TreePath p, Tree t)
Creates a TreePath for a child node.

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.source.util.TreePathScanner

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.source.util.TreePathScanner

No usage of com.sun.source.util.TreePathScanner

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.source.util.Trees

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.source.util.Trees

Packages that use Trees
com.sun.source.util Provides utilities for operations on abstract syntax trees (AST).

Uses of Trees in com.sun.source.util

Methods in com.sun.source.util that return Trees
static Trees | Trees.instance(JavaCompiler.CompilationTask task) Gets a Trees object for a given CompilationTask.
static Trees | Trees.instance(ProcessingEnvironment env) Gets a Trees object for a given CompilationTask.

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Class com.sun.source.util.TreeScanner

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.source.util.TreeScanner

Packages that use TreeScanner
com.sun.source.util Provides utilities for operations on abstract syntax trees (AST).

Uses of TreeScanner in com.sun.source.util

Subclasses of TreeScanner in com.sun.source.util
 class TreePathScanner<R,P>
A TreeVisitor that visits all the child tree nodes, and provides support for maintaining a path for the parent nodes.

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.util.SourcePositions

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.util.SourcePositions

Packages that use SourcePositions
com.sun.source.util Provides utilities for operations on abstract syntax trees (AST).

Uses of SourcePositions in com.sun.source.util

Methods in com.sun.source.util that return SourcePositions
abstract  SourcePositions Trees.getSourcePositions()
Gets a utility object for obtaining source positions.

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Uses of Interface com.sun.source.util.TaskListener

Compiler Tree API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.source.util.TaskListener

Packages that use TaskListener
com.sun.source.util Provides utilities for operations on abstract syntax trees (AST).

Uses of TaskListener in com.sun.source.util

Methods in com.sun.source.util with parameters of type TaskListener
abstract  void JavacTask.setTaskListener(TaskListener taskListener)
The specified listener will receive events describing the progress of this compilation task.

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV NEXT FRAMES NO FRAMES
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


JavacTask

Compiler Tree API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.source.util
Class JavacTask

java.lang.Object
    extended by  com.sun.source.util.JavacTask
All Implemented Interfaces:
Callable<Boolean>, JavaCompiler.CompilationTask
public abstract class JavacTask
extends Object
implements JavaCompiler.CompilationTask

Provides access to functionality specific to the Sun Java Compiler, javac.

Since:
1.6

Constructor Summary
JavacTask()
Method Summary
abstract Iterable<? extends Element> | analyze() Complete all analysis.
abstract Iterable<? extends JavaFileObject> | generate() Generate code.
abstract Elements | getElements() Get a utility object for dealing with program elements.
abstract TypeMirror | getTypeMirror(Iterable<? extends Tree> path) Get a type mirror of the tree node determined by the specified path.
abstract Types | getTypes() Get a utility object for dealing with type mirrors.
abstract Iterable<? extends CompilationUnitTree> | parse() Parse the specified files returning a list of abstract syntax trees.
abstract void | setTaskListener(TaskListener taskListener) The specified listener will receive events describing the progress of this compilation task.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface javax.tools.JavaCompiler.CompilationTask
call, setLocale, setProcessors

Constructor Detail

JavacTask

public JavacTask()
Method Detail

parse

public abstract Iterable<? extends CompilationUnitTree> parse()
                                                       throws IOException
Parse the specified files returning a list of abstract syntax trees.

Returns:
a list of abstract syntax trees
Throws:
IOException - if an unhandled I/O error occurred in the compiler.

analyze

public abstract Iterable<? extends Element> analyze()
                                             throws IOException
Complete all analysis.

Returns:
a list of elements that were analyzed
Throws:
IOException - if an unhandled I/O error occurred in the compiler.

generate

public abstract Iterable<? extends JavaFileObject> generate()
                                                     throws IOException
Generate code.

Returns:
a list of files that were generated
Throws:
IOException - if an unhandled I/O error occurred in the compiler.

setTaskListener

public abstract void setTaskListener(TaskListener taskListener)
The specified listener will receive events describing the progress of this compilation task.

getTypeMirror

public abstract TypeMirror getTypeMirror(Iterable<? extends Tree> path)
Get a type mirror of the tree node determined by the specified path.

getElements

public abstract Elements getElements()
Get a utility object for dealing with program elements.

getTypes

public abstract Types getTypes()
Get a utility object for dealing with type mirrors.

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


SimpleTreeVisitor

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.util
Class SimpleTreeVisitor<R,P>

java.lang.Object
    extended by  com.sun.source.util.SimpleTreeVisitor<R,P>
All Implemented Interfaces:
TreeVisitor<R,P>
public class SimpleTreeVisitor<R,P>
extends Object
implements TreeVisitor<R,P>

A simple visitor for tree nodes.

Since:
1.6

Field Summary
protected  R DEFAULT_VALUE
Constructor Summary
protected | SimpleTreeVisitor()
protected | SimpleTreeVisitor(R defaultValue)
Method Summary
protected R | defaultAction(Tree node, P p)
R | visit(Iterable<? extends Tree> nodes, P p)
R | visit(Tree node, P p)
R | visitAnnotation(AnnotationTree node, P p)
R | visitArrayAccess(ArrayAccessTree node, P p)
R | visitArrayType(ArrayTypeTree node, P p)
R | visitAssert(AssertTree node, P p)
R | visitAssignment(AssignmentTree node, P p)
R | visitBinary(BinaryTree node, P p)
R | visitBlock(BlockTree node, P p)
R | visitBreak(BreakTree node, P p)
R | visitCase(CaseTree node, P p)
R | visitCatch(CatchTree node, P p)
R | visitClass(ClassTree node, P p)
R | visitCompilationUnit(CompilationUnitTree node, P p)
R | visitCompoundAssignment(CompoundAssignmentTree node, P p)
R | visitConditionalExpression(ConditionalExpressionTree node, P p)
R | visitContinue(ContinueTree node, P p)
R | visitDoWhileLoop(DoWhileLoopTree node, P p)
R | visitEmptyStatement(EmptyStatementTree node, P p)
R | visitEnhancedForLoop(EnhancedForLoopTree node, P p)
R | visitErroneous(ErroneousTree node, P p)
R | visitExpressionStatement(ExpressionStatementTree node, P p)
R | visitForLoop(ForLoopTree node, P p)
R | visitIdentifier(IdentifierTree node, P p)
R | visitIf(IfTree node, P p)
R | visitImport(ImportTree node, P p)
R | visitInstanceOf(InstanceOfTree node, P p)
R | visitLabeledStatement(LabeledStatementTree node, P p)
R | visitLiteral(LiteralTree node, P p)
R | visitMemberSelect(MemberSelectTree node, P p)
R | visitMethod(MethodTree node, P p)
R | visitMethodInvocation(MethodInvocationTree node, P p)
R | visitModifiers(ModifiersTree node, P p)
R | visitNewArray(NewArrayTree node, P p)
R | visitNewClass(NewClassTree node, P p)
R | visitOther(Tree node, P p)
R | visitParameterizedType(ParameterizedTypeTree node, P p)
R | visitParenthesized(ParenthesizedTree node, P p)
R | visitPrimitiveType(PrimitiveTypeTree node, P p)
R | visitReturn(ReturnTree node, P p)
R | visitSwitch(SwitchTree node, P p)
R | visitSynchronized(SynchronizedTree node, P p)
R | visitThrow(ThrowTree node, P p)
R | visitTry(TryTree node, P p)
R | visitTypeCast(TypeCastTree node, P p)
R | visitTypeParameter(TypeParameterTree node, P p)
R | visitUnary(UnaryTree node, P p)
R | visitVariable(VariableTree node, P p)
R | visitWhileLoop(WhileLoopTree node, P p)
R | visitWildcard(WildcardTree node, P p)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_VALUE

protected final R DEFAULT_VALUE
Constructor Detail

SimpleTreeVisitor

protected SimpleTreeVisitor()

SimpleTreeVisitor

protected SimpleTreeVisitor(R defaultValue)
Method Detail

defaultAction

protected R defaultAction(Tree node,
                          P p)

visit

public final R visit(Tree node,
                     P p)

visit

public final R visit(Iterable<? extends Tree> nodes,
                     P p)

visitCompilationUnit

public R visitCompilationUnit(CompilationUnitTree node,
                              P p)
Specified by:
visitCompilationUnit in interface TreeVisitor<R,P>

visitImport

public R visitImport(ImportTree node,
                     P p)
Specified by:
visitImport in interface TreeVisitor<R,P>

visitClass

public R visitClass(ClassTree node,
                    P p)
Specified by:
visitClass in interface TreeVisitor<R,P>

visitMethod

public R visitMethod(MethodTree node,
                     P p)
Specified by:
visitMethod in interface TreeVisitor<R,P>

visitVariable

public R visitVariable(VariableTree node,
                       P p)
Specified by:
visitVariable in interface TreeVisitor<R,P>

visitEmptyStatement

public R visitEmptyStatement(EmptyStatementTree node,
                             P p)
Specified by:
visitEmptyStatement in interface TreeVisitor<R,P>

visitBlock

public R visitBlock(BlockTree node,
                    P p)
Specified by:
visitBlock in interface TreeVisitor<R,P>

visitDoWhileLoop

public R visitDoWhileLoop(DoWhileLoopTree node,
                          P p)
Specified by:
visitDoWhileLoop in interface TreeVisitor<R,P>

visitWhileLoop

public R visitWhileLoop(WhileLoopTree node,
                        P p)
Specified by:
visitWhileLoop in interface TreeVisitor<R,P>

visitForLoop

public R visitForLoop(ForLoopTree node,
                      P p)
Specified by:
visitForLoop in interface TreeVisitor<R,P>

visitEnhancedForLoop

public R visitEnhancedForLoop(EnhancedForLoopTree node,
                              P p)
Specified by:
visitEnhancedForLoop in interface TreeVisitor<R,P>

visitLabeledStatement

public R visitLabeledStatement(LabeledStatementTree node,
                               P p)
Specified by:
visitLabeledStatement in interface TreeVisitor<R,P>

visitSwitch

public R visitSwitch(SwitchTree node,
                     P p)
Specified by:
visitSwitch in interface TreeVisitor<R,P>

visitCase

public R visitCase(CaseTree node,
                   P p)
Specified by:
visitCase in interface TreeVisitor<R,P>

visitSynchronized

public R visitSynchronized(SynchronizedTree node,
                           P p)
Specified by:
visitSynchronized in interface TreeVisitor<R,P>

visitTry

public R visitTry(TryTree node,
                  P p)
Specified by:
visitTry in interface TreeVisitor<R,P>

visitCatch

public R visitCatch(CatchTree node,
                    P p)
Specified by:
visitCatch in interface TreeVisitor<R,P>

visitConditionalExpression

public R visitConditionalExpression(ConditionalExpressionTree node,
                                    P p)
Specified by:
visitConditionalExpression in interface TreeVisitor<R,P>

visitIf

public R visitIf(IfTree node,
                 P p)
Specified by:
visitIf in interface TreeVisitor<R,P>

visitExpressionStatement

public R visitExpressionStatement(ExpressionStatementTree node,
                                  P p)
Specified by:
visitExpressionStatement in interface TreeVisitor<R,P>

visitBreak

public R visitBreak(BreakTree node,
                    P p)
Specified by:
visitBreak in interface TreeVisitor<R,P>

visitContinue

public R visitContinue(ContinueTree node,
                       P p)
Specified by:
visitContinue in interface TreeVisitor<R,P>

visitReturn

public R visitReturn(ReturnTree node,
                     P p)
Specified by:
visitReturn in interface TreeVisitor<R,P>

visitThrow

public R visitThrow(ThrowTree node,
                    P p)
Specified by:
visitThrow in interface TreeVisitor<R,P>

visitAssert

public R visitAssert(AssertTree node,
                     P p)
Specified by:
visitAssert in interface TreeVisitor<R,P>

visitMethodInvocation

public R visitMethodInvocation(MethodInvocationTree node,
                               P p)
Specified by:
visitMethodInvocation in interface TreeVisitor<R,P>

visitNewClass

public R visitNewClass(NewClassTree node,
                       P p)
Specified by:
visitNewClass in interface TreeVisitor<R,P>

visitNewArray

public R visitNewArray(NewArrayTree node,
                       P p)
Specified by:
visitNewArray in interface TreeVisitor<R,P>

visitParenthesized

public R visitParenthesized(ParenthesizedTree node,
                            P p)
Specified by:
visitParenthesized in interface TreeVisitor<R,P>

visitAssignment

public R visitAssignment(AssignmentTree node,
                         P p)
Specified by:
visitAssignment in interface TreeVisitor<R,P>

visitCompoundAssignment

public R visitCompoundAssignment(CompoundAssignmentTree node,
                                 P p)
Specified by:
visitCompoundAssignment in interface TreeVisitor<R,P>

visitUnary

public R visitUnary(UnaryTree node,
                    P p)
Specified by:
visitUnary in interface TreeVisitor<R,P>

visitBinary

public R visitBinary(BinaryTree node,
                     P p)
Specified by:
visitBinary in interface TreeVisitor<R,P>

visitTypeCast

public R visitTypeCast(TypeCastTree node,
                       P p)
Specified by:
visitTypeCast in interface TreeVisitor<R,P>

visitInstanceOf

public R visitInstanceOf(InstanceOfTree node,
                         P p)
Specified by:
visitInstanceOf in interface TreeVisitor<R,P>

visitArrayAccess

public R visitArrayAccess(ArrayAccessTree node,
                          P p)
Specified by:
visitArrayAccess in interface TreeVisitor<R,P>

visitMemberSelect

public R visitMemberSelect(MemberSelectTree node,
                           P p)
Specified by:
visitMemberSelect in interface TreeVisitor<R,P>

visitIdentifier

public R visitIdentifier(IdentifierTree node,
                         P p)
Specified by:
visitIdentifier in interface TreeVisitor<R,P>

visitLiteral

public R visitLiteral(LiteralTree node,
                      P p)
Specified by:
visitLiteral in interface TreeVisitor<R,P>

visitPrimitiveType

public R visitPrimitiveType(PrimitiveTypeTree node,
                            P p)
Specified by:
visitPrimitiveType in interface TreeVisitor<R,P>

visitArrayType

public R visitArrayType(ArrayTypeTree node,
                        P p)
Specified by:
visitArrayType in interface TreeVisitor<R,P>

visitParameterizedType

public R visitParameterizedType(ParameterizedTypeTree node,
                                P p)
Specified by:
visitParameterizedType in interface TreeVisitor<R,P>

visitTypeParameter

public R visitTypeParameter(TypeParameterTree node,
                            P p)
Specified by:
visitTypeParameter in interface TreeVisitor<R,P>

visitWildcard

public R visitWildcard(WildcardTree node,
                       P p)
Specified by:
visitWildcard in interface TreeVisitor<R,P>

visitModifiers

public R visitModifiers(ModifiersTree node,
                        P p)
Specified by:
visitModifiers in interface TreeVisitor<R,P>

visitAnnotation

public R visitAnnotation(AnnotationTree node,
                         P p)
Specified by:
visitAnnotation in interface TreeVisitor<R,P>

visitErroneous

public R visitErroneous(ErroneousTree node,
                        P p)
Specified by:
visitErroneous in interface TreeVisitor<R,P>

visitOther

public R visitOther(Tree node,
                    P p)
Specified by:
visitOther in interface TreeVisitor<R,P>
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


SourcePositions

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.util
Interface SourcePositions

public interface SourcePositions

Provides methods to obtain the position of a Tree within a CompilationUnit. A position is defined as a simple character offset from the start of a CompilationUnit where the first character is at offset 0.

Since:
1.6

Method Summary
long | getEndPosition(CompilationUnitTree file, Tree tree) Gets the ending position of tree within file.
long | getStartPosition(CompilationUnitTree file, Tree tree) Gets the starting position of tree within file.

Method Detail

getStartPosition

long getStartPosition(CompilationUnitTree file,
                      Tree tree)
Gets the starting position of tree within file. If tree is not found within file, or if the starting position is not available, return Diagnostic.NOPOS. The returned position must be at the start of the yield of this tree, that is for any sub-tree of this tree, the following must hold:

tree.getStartPosition() <= subtree.getStartPosition() or
tree.getStartPosition() == NOPOS or
subtree.getStartPosition() == NOPOS

Parameters:
file - CompilationUnit in which to find tree.
tree - tree for which a position is sought.
Returns:
the start position of tree.

getEndPosition

long getEndPosition(CompilationUnitTree file,
                    Tree tree)
Gets the ending position of tree within file. If tree is not found within file, or if the starting position is not available, return Diagnostic.NOPOS. The returned position must be at the end of the yield of this tree, that is for any sub-tree of this tree, the following must hold:

tree.getEndPosition() >= subtree.getEndPosition() or
tree.getEndPosition() == NOPOS or
subtree.getEndPosition() == NOPOS

In addition, the following must hold:

tree.getStartPosition() <= tree.getEndPosition() or
tree.getStartPosition() == NOPOS or
tree.getEndPosition() == NOPOS

Parameters:
file - CompilationUnit in which to find tree.
tree - tree for which a position is sought.
Returns:
the end position of tree.
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


TaskEvent

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.util
Class TaskEvent

java.lang.Object
    extended by  com.sun.source.util.TaskEvent

public final class TaskEvent
extends Object

Provides details about work that has been done by the Sun Java Compiler, javac.

Since:
1.6

Nested Class Summary
static class TaskEvent.Kind
Kind of task event.
Constructor Summary
TaskEvent(TaskEvent.Kind kind)
TaskEvent(TaskEvent.Kind kind, CompilationUnitTree unit)
TaskEvent(TaskEvent.Kind kind, CompilationUnitTree unit, TypeElement clazz)
TaskEvent(TaskEvent.Kind kind, JavaFileObject sourceFile)
Method Summary
CompilationUnitTree | getCompilationUnit()
TaskEvent.Kind | getKind()
JavaFileObject | getSourceFile()
TypeElement | getTypeElement()
String | toString()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TaskEvent

public TaskEvent(TaskEvent.Kind kind)

TaskEvent

public TaskEvent(TaskEvent.Kind kind,
                 JavaFileObject sourceFile)

TaskEvent

public TaskEvent(TaskEvent.Kind kind,
                 CompilationUnitTree unit)

TaskEvent

public TaskEvent(TaskEvent.Kind kind,
                 CompilationUnitTree unit,
                 TypeElement clazz)
Method Detail

getKind

public TaskEvent.Kind getKind()

getSourceFile

public JavaFileObject getSourceFile()

getCompilationUnit

public CompilationUnitTree getCompilationUnit()

getTypeElement

public TypeElement getTypeElement()

toString

public String toString()
Overrides:
toString in class Object
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


TaskEvent.Kind

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

com.sun.source.util
Enum TaskEvent.Kind

java.lang.Object
    extended by  java.lang.Enum<TaskEvent.Kind>
        extended by  com.sun.source.util.TaskEvent.Kind
All Implemented Interfaces:
Serializable, Comparable<TaskEvent.Kind>
Enclosing class:
TaskEvent
public static enum TaskEvent.Kind
extends Enum<TaskEvent.Kind>

Kind of task event.

Since:
1.6

Enum Constant Summary
ANALYZE
For events relating to elements being analyzed for errors.
ANNOTATION_PROCESSING
For events relating to overall annotaion processing.
ANNOTATION_PROCESSING_ROUND
For events relating to an individual annotation processing round.
ENTER
For events relating to elements being entered.
GENERATE
For events relating to class files being generated.
PARSE
For events related to the parsing of a file.
Method Summary
static TaskEvent.Kind | valueOf(String name) Returns the enum constant of this type with the specified name.
static TaskEvent.Kind[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

PARSE

public static final TaskEvent.Kind PARSE
For events related to the parsing of a file.

ENTER

public static final TaskEvent.Kind ENTER
For events relating to elements being entered.

ANALYZE

public static final TaskEvent.Kind ANALYZE
For events relating to elements being analyzed for errors.

GENERATE

public static final TaskEvent.Kind GENERATE
For events relating to class files being generated.

ANNOTATION_PROCESSING

public static final TaskEvent.Kind ANNOTATION_PROCESSING
For events relating to overall annotaion processing.

ANNOTATION_PROCESSING_ROUND

public static final TaskEvent.Kind ANNOTATION_PROCESSING_ROUND
For events relating to an individual annotation processing round.

Method Detail

values

public static TaskEvent.Kind[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (TaskEvent.Kind c : TaskEvent.Kind.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static TaskEvent.Kind valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


TaskListener

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.util
Interface TaskListener

public interface TaskListener

Provides a listener to monitor the activity of the Sun Java Compiler, javac.

Since:
1.6

Method Summary
void | finished(TaskEvent e)
void | started(TaskEvent e)

Method Detail

started

void started(TaskEvent e)

finished

void finished(TaskEvent e)
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


TreePath

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.util
Class TreePath

java.lang.Object
    extended by  com.sun.source.util.TreePath
All Implemented Interfaces:
Iterable<Tree>
public class TreePath
extends Object
implements Iterable<Tree>

A path of tree nodes, typically used to represent the sequence of ancestor nodes of a tree node up to the top level CompilationUnitTree node.

Since:
1.6

Constructor Summary
TreePath(CompilationUnitTree t)
Creates a TreePath for a root node.
TreePath(TreePath p, Tree t)
Creates a TreePath for a child node.
Method Summary
CompilationUnitTree | getCompilationUnit() Get the compilation unit associated with this path.
Tree | getLeaf() Get the leaf node for this path.
TreePath | getParentPath() Get the path for the enclosing node, or null if there is no enclosing node.
static TreePath | getPath(CompilationUnitTree unit, Tree target) Gets a tree path for a tree node within a compilation unit.
static TreePath | getPath(TreePath path, Tree target) Gets a tree path for a tree node within a subtree identified by a TreePath object.
Iterator<Tree> | iterator()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TreePath

public TreePath(CompilationUnitTree t)
Creates a TreePath for a root node.

TreePath

public TreePath(TreePath p,
                Tree t)
Creates a TreePath for a child node.

Method Detail

getPath

public static TreePath getPath(CompilationUnitTree unit,
                               Tree target)
Gets a tree path for a tree node within a compilation unit.

Returns:
null if the node is not found

getPath

public static TreePath getPath(TreePath path,
                               Tree target)
Gets a tree path for a tree node within a subtree identified by a TreePath object.

Returns:
null if the node is not found

getCompilationUnit

public CompilationUnitTree getCompilationUnit()
Get the compilation unit associated with this path.

getLeaf

public Tree getLeaf()
Get the leaf node for this path.

getParentPath

public TreePath getParentPath()
Get the path for the enclosing node, or null if there is no enclosing node.

iterator

public Iterator<Tree> iterator()
Specified by:
iterator in interface Iterable<Tree>
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


TreePathScanner

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.util
Class TreePathScanner<R,P>

java.lang.Object
    extended by  com.sun.source.util.TreeScanner<R,P>
        extended by  com.sun.source.util.TreePathScanner<R,P>
All Implemented Interfaces:
TreeVisitor<R,P>
public class TreePathScanner<R,P>
extends TreeScanner<R,P>

A TreeVisitor that visits all the child tree nodes, and provides support for maintaining a path for the parent nodes. To visit nodes of a particular type, just override the corresponding visitorXYZ method. Inside your method, call super.visitXYZ to visit descendant nodes.

Since:
1.6

Constructor Summary
TreePathScanner()
Method Summary
TreePath | getCurrentPath() Get the current path for the node, as built up by the currently active set of scan calls.
R | scan(Tree tree, P p) Scan a single node.
R | scan(TreePath path, P p) Scan a tree from a position identified by a TreePath.
Methods inherited from class com.sun.source.util.TreeScanner
reduce, scan, visitAnnotation, visitArrayAccess, visitArrayType, visitAssert, visitAssignment, visitBinary, visitBlock, visitBreak, visitCase, visitCatch, visitClass, visitCompilationUnit, visitCompoundAssignment, visitConditionalExpression, visitContinue, visitDoWhileLoop, visitEmptyStatement, visitEnhancedForLoop, visitErroneous, visitExpressionStatement, visitForLoop, visitIdentifier, visitIf, visitImport, visitInstanceOf, visitLabeledStatement, visitLiteral, visitMemberSelect, visitMethod, visitMethodInvocation, visitModifiers, visitNewArray, visitNewClass, visitOther, visitParameterizedType, visitParenthesized, visitPrimitiveType, visitReturn, visitSwitch, visitSynchronized, visitThrow, visitTry, visitTypeCast, visitTypeParameter, visitUnary, visitVariable, visitWhileLoop, visitWildcard
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TreePathScanner

public TreePathScanner()
Method Detail

scan

public R scan(TreePath path,
              P p)
Scan a tree from a position identified by a TreePath.

scan

public R scan(Tree tree,
              P p)
Scan a single node. The current path is updated for the duration of the scan.

Overrides:
scan in class TreeScanner<R,P>

getCurrentPath

public TreePath getCurrentPath()
Get the current path for the node, as built up by the currently active set of scan calls.

Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


Trees

Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.source.util
Class Trees

java.lang.Object
    extended by  com.sun.source.util.Trees

public abstract class Trees
extends Object

Bridges JSR 199, JSR 269, and the Tree API.

Constructor Summary
Trees()
Method Summary
abstract Element | getElement(TreePath path) Gets the Element for the Tree node identified by a given TreePath.
abstract TreePath | getPath(CompilationUnitTree unit, Tree node) Gets the path to tree node within the specified compilation unit.
abstract TreePath | getPath(Element e) Gets the TreePath node for a given Element.
abstract TreePath | getPath(Element e, AnnotationMirror a) Gets the TreePath node for an AnnotationMirror on a given Element.
abstract TreePath | getPath(Element e, AnnotationMirror a, AnnotationValue v) Gets the TreePath node for an AnnotationValue for an AnnotationMirror on a given Element.
abstract Scope | getScope(TreePath path) Gets the Scope for the Tree node identified by a given TreePath.
abstract SourcePositions | getSourcePositions() Gets a utility object for obtaining source positions.
abstract Tree | getTree(Element element) Gets the Tree node for a given Element.
abstract Tree | getTree(Element e, AnnotationMirror a) Gets the Tree node for an AnnotationMirror on a given Element.
abstract Tree | getTree(Element e, AnnotationMirror a, AnnotationValue v) Gets the Tree node for an AnnotationValue for an AnnotationMirror on a given Element.
abstract MethodTree | getTree(ExecutableElement method) Gets the MethodTree node for a given ExecutableElement.
abstract ClassTree | getTree(TypeElement element) Gets the ClassTree node for a given TypeElement.
abstract TypeMirror | getTypeMirror(TreePath path) Gets the TypeMirror for the Tree node identified by a given TreePath.
static Trees | instance(JavaCompiler.CompilationTask task) Gets a Trees object for a given CompilationTask.
static Trees | instance(ProcessingEnvironment env) Gets a Trees object for a given CompilationTask.
abstract boolean | isAccessible(Scope scope, Element member, DeclaredType type) Checks whether the given element is accessible as a member of the given type in a given scope.
abstract boolean | isAccessible(Scope scope, TypeElement type) Checks whether a given type is accessible in a given scope.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Trees

public Trees()
Method Detail

instance

public static Trees instance(JavaCompiler.CompilationTask task)
Gets a Trees object for a given CompilationTask.

Throws:
IllegalArgumentException - if the task does not support the Trees API.

instance

public static Trees instance(ProcessingEnvironment env)
Gets a Trees object for a given CompilationTask.

Throws:
IllegalArgumentException - if the env does not support the Trees API.

getSourcePositions

public abstract SourcePositions getSourcePositions()
Gets a utility object for obtaining source positions.

getTree

public abstract Tree getTree(Element element)
Gets the Tree node for a given Element. Returns null if the node can not be found.

getTree

public abstract ClassTree getTree(TypeElement element)
Gets the ClassTree node for a given TypeElement. Returns null if the node can not be found.

getTree

public abstract MethodTree getTree(ExecutableElement method)
Gets the MethodTree node for a given ExecutableElement. Returns null if the node can not be found.

getTree

public abstract Tree getTree(Element e,
                             AnnotationMirror a)
Gets the Tree node for an AnnotationMirror on a given Element. Returns null if the node can not be found.

getTree

public abstract Tree getTree(Element e,
                             AnnotationMirror a,
                             AnnotationValue v)
Gets the Tree node for an AnnotationValue for an AnnotationMirror on a given Element. Returns null if the node can not be found.

getPath

public abstract TreePath getPath(CompilationUnitTree unit,
                                 Tree node)
Gets the path to tree node within the specified compilation unit.

getPath

public abstract TreePath getPath(Element e)
Gets the TreePath node for a given Element. Returns null if the node can not be found.

getPath

public abstract TreePath getPath(Element e,
                                 AnnotationMirror a)
Gets the TreePath node for an AnnotationMirror on a given Element. Returns null if the node can not be found.

getPath

public abstract TreePath getPath(Element e,
                                 AnnotationMirror a,
                                 AnnotationValue v)
Gets the TreePath node for an AnnotationValue for an AnnotationMirror on a given Element. Returns null if the node can not be found.

getElement

public abstract Element getElement(TreePath path)
Gets the Element for the Tree node identified by a given TreePath. Returns null if the element is not available.

Throws:
IllegalArgumentException - is the TreePath does not identify a Tree node that might have an associated Element.

getTypeMirror

public abstract TypeMirror getTypeMirror(TreePath path)
Gets the TypeMirror for the Tree node identified by a given TreePath. Returns null if the TypeMirror is not available.

Throws:
IllegalArgumentException - is the TreePath does not identify a Tree node that might have an associated TypeMirror.

getScope

public abstract Scope getScope(TreePath path)
Gets the Scope for the Tree node identified by a given TreePath. Returns null if the Scope is not available.

isAccessible

public abstract boolean isAccessible(Scope scope,
                                     TypeElement type)
Checks whether a given type is accessible in a given scope.

Parameters:
scope - the scope to be checked
type - the type to be checked
Returns:
true if type is accessible

isAccessible

public abstract boolean isAccessible(Scope scope,
                                     Element member,
                                     DeclaredType type)
Checks whether the given element is accessible as a member of the given type in a given scope.

Parameters:
scope - the scope to be checked
member - the member to be checked
type - the type for which to check if the member is accessible
Returns:
true if member is accessible in type
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


TreeScanner

Compiler Tree API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.source.util
Class TreeScanner<R,P>

java.lang.Object
    extended by  com.sun.source.util.TreeScanner<R,P>
All Implemented Interfaces:
TreeVisitor<R,P>
Direct Known Subclasses:
TreePathScanner
public class TreeScanner<R,P>
extends Object
implements TreeVisitor<R,P>

A TreeVisitor that visits all the child tree nodes. To visit nodes of a particular type, just override the corresponding visitXYZ method. Inside your method, call super.visitXYZ to visit descendant nodes.

The default implementation of the visitXYZ methods will determine a result as follows:

  • If the node being visited has no children, the result will be null.
  • If the node being visited has one child, the result will be the result of calling scan on that child. The child may be a simple node or itself a list of nodes.
  • If the node being visited has more than one child, the result will be determined by calling scan each child in turn, and then combining the result of each scan after the first with the cumulative result so far, as determined by the reduce(R, R) method. Each child may be either a simple node of a list of nodes. The default behavior of the reduce method is such that the result of the visitXYZ method will be the result of the last child scanned.

Here is an example to count the number of identifier nodes in a tree:

   class CountIdentifiers extends TreeScanner {
        @Override
        public Integer visitIdentifier(IdentifierTree node, Void p) {
            return 1;
        }
        @Override
        public Integer reduce(Integer r1, Integer r2) {
            return (r1 == null ? 0 : r1) + (r2 == null ? 0 : r2);
        }
   }

Since:
1.6

Constructor Summary
TreeScanner()
Method Summary
R | reduce(R r1, R r2) Reduces two results into a combined result.
R | scan(Iterable<? extends Tree> nodes, P p) Scan a list of nodes.
R | scan(Tree node, P p) Scan a single node.
R | visitAnnotation(AnnotationTree node, P p)
R | visitArrayAccess(ArrayAccessTree node, P p)
R | visitArrayType(ArrayTypeTree node, P p)
R | visitAssert(AssertTree node, P p)
R | visitAssignment(AssignmentTree node, P p)
R | visitBinary(BinaryTree node, P p)
R | visitBlock(BlockTree node, P p)
R | visitBreak(BreakTree node, P p)
R | visitCase(CaseTree node, P p)
R | visitCatch(CatchTree node, P p)
R | visitClass(ClassTree node, P p)
R | visitCompilationUnit(CompilationUnitTree node, P p)
R | visitCompoundAssignment(CompoundAssignmentTree node, P p)
R | visitConditionalExpression(ConditionalExpressionTree node, P p)
R | visitContinue(ContinueTree node, P p)
R | visitDoWhileLoop(DoWhileLoopTree node, P p)
R | visitEmptyStatement(EmptyStatementTree node, P p)
R | visitEnhancedForLoop(EnhancedForLoopTree node, P p)
R | visitErroneous(ErroneousTree node, P p)
R | visitExpressionStatement(ExpressionStatementTree node, P p)
R | visitForLoop(ForLoopTree node, P p)
R | visitIdentifier(IdentifierTree node, P p)
R | visitIf(IfTree node, P p)
R | visitImport(ImportTree node, P p)
R | visitInstanceOf(InstanceOfTree node, P p)
R | visitLabeledStatement(LabeledStatementTree node, P p)
R | visitLiteral(LiteralTree node, P p)
R | visitMemberSelect(MemberSelectTree node, P p)
R | visitMethod(MethodTree node, P p)
R | visitMethodInvocation(MethodInvocationTree node, P p)
R | visitModifiers(ModifiersTree node, P p)
R | visitNewArray(NewArrayTree node, P p)
R | visitNewClass(NewClassTree node, P p)
R | visitOther(Tree node, P p)
R | visitParameterizedType(ParameterizedTypeTree node, P p)
R | visitParenthesized(ParenthesizedTree node, P p)
R | visitPrimitiveType(PrimitiveTypeTree node, P p)
R | visitReturn(ReturnTree node, P p)
R | visitSwitch(SwitchTree node, P p)
R | visitSynchronized(SynchronizedTree node, P p)
R | visitThrow(ThrowTree node, P p)
R | visitTry(TryTree node, P p)
R | visitTypeCast(TypeCastTree node, P p)
R | visitTypeParameter(TypeParameterTree node, P p)
R | visitUnary(UnaryTree node, P p)
R | visitVariable(VariableTree node, P p)
R | visitWhileLoop(WhileLoopTree node, P p)
R | visitWildcard(WildcardTree node, P p)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TreeScanner

public TreeScanner()
Method Detail

scan

public R scan(Tree node,
              P p)
Scan a single node.

scan

public R scan(Iterable<? extends Tree> nodes,
              P p)
Scan a list of nodes.

reduce

public R reduce(R r1,
                R r2)
Reduces two results into a combined result. The default implementation is to return the first parameter. The general contract of the method is that it may take any action whatsoever.

visitCompilationUnit

public R visitCompilationUnit(CompilationUnitTree node,
                              P p)
Specified by:
visitCompilationUnit in interface TreeVisitor<R,P>

visitImport

public R visitImport(ImportTree node,
                     P p)
Specified by:
visitImport in interface TreeVisitor<R,P>

visitClass

public R visitClass(ClassTree node,
                    P p)
Specified by:
visitClass in interface TreeVisitor<R,P>

visitMethod

public R visitMethod(MethodTree node,
                     P p)
Specified by:
visitMethod in interface TreeVisitor<R,P>

visitVariable

public R visitVariable(VariableTree node,
                       P p)
Specified by:
visitVariable in interface TreeVisitor<R,P>

visitEmptyStatement

public R visitEmptyStatement(EmptyStatementTree node,
                             P p)
Specified by:
visitEmptyStatement in interface TreeVisitor<R,P>

visitBlock

public R visitBlock(BlockTree node,
                    P p)
Specified by:
visitBlock in interface TreeVisitor<R,P>

visitDoWhileLoop

public R visitDoWhileLoop(DoWhileLoopTree node,
                          P p)
Specified by:
visitDoWhileLoop in interface TreeVisitor<R,P>

visitWhileLoop

public R visitWhileLoop(WhileLoopTree node,
                        P p)
Specified by:
visitWhileLoop in interface TreeVisitor<R,P>

visitForLoop

public R visitForLoop(ForLoopTree node,
                      P p)
Specified by:
visitForLoop in interface TreeVisitor<R,P>

visitEnhancedForLoop

public R visitEnhancedForLoop(EnhancedForLoopTree node,
                              P p)
Specified by:
visitEnhancedForLoop in interface TreeVisitor<R,P>

visitLabeledStatement

public R visitLabeledStatement(LabeledStatementTree node,
                               P p)
Specified by:
visitLabeledStatement in interface TreeVisitor<R,P>

visitSwitch

public R visitSwitch(SwitchTree node,
                     P p)
Specified by:
visitSwitch in interface TreeVisitor<R,P>

visitCase

public R visitCase(CaseTree node,
                   P p)
Specified by:
visitCase in interface TreeVisitor<R,P>

visitSynchronized

public R visitSynchronized(SynchronizedTree node,
                           P p)
Specified by:
visitSynchronized in interface TreeVisitor<R,P>

visitTry

public R visitTry(TryTree node,
                  P p)
Specified by:
visitTry in interface TreeVisitor<R,P>

visitCatch

public R visitCatch(CatchTree node,
                    P p)
Specified by:
visitCatch in interface TreeVisitor<R,P>

visitConditionalExpression

public R visitConditionalExpression(ConditionalExpressionTree node,
                                    P p)
Specified by:
visitConditionalExpression in interface TreeVisitor<R,P>

visitIf

public R visitIf(IfTree node,
                 P p)
Specified by:
visitIf in interface TreeVisitor<R,P>

visitExpressionStatement

public R visitExpressionStatement(ExpressionStatementTree node,
                                  P p)
Specified by:
visitExpressionStatement in interface TreeVisitor<R,P>

visitBreak

public R visitBreak(BreakTree node,
                    P p)
Specified by:
visitBreak in interface TreeVisitor<R,P>

visitContinue

public R visitContinue(ContinueTree node,
                       P p)
Specified by:
visitContinue in interface TreeVisitor<R,P>

visitReturn

public R visitReturn(ReturnTree node,
                     P p)
Specified by:
visitReturn in interface TreeVisitor<R,P>

visitThrow

public R visitThrow(ThrowTree node,
                    P p)
Specified by:
visitThrow in interface TreeVisitor<R,P>

visitAssert

public R visitAssert(AssertTree node,
                     P p)
Specified by:
visitAssert in interface TreeVisitor<R,P>

visitMethodInvocation

public R visitMethodInvocation(MethodInvocationTree node,
                               P p)
Specified by:
visitMethodInvocation in interface TreeVisitor<R,P>

visitNewClass

public R visitNewClass(NewClassTree node,
                       P p)
Specified by:
visitNewClass in interface TreeVisitor<R,P>

visitNewArray

public R visitNewArray(NewArrayTree node,
                       P p)
Specified by:
visitNewArray in interface TreeVisitor<R,P>

visitParenthesized

public R visitParenthesized(ParenthesizedTree node,
                            P p)
Specified by:
visitParenthesized in interface TreeVisitor<R,P>

visitAssignment

public R visitAssignment(AssignmentTree node,
                         P p)
Specified by:
visitAssignment in interface TreeVisitor<R,P>

visitCompoundAssignment

public R visitCompoundAssignment(CompoundAssignmentTree node,
                                 P p)
Specified by:
visitCompoundAssignment in interface TreeVisitor<R,P>

visitUnary

public R visitUnary(UnaryTree node,
                    P p)
Specified by:
visitUnary in interface TreeVisitor<R,P>

visitBinary

public R visitBinary(BinaryTree node,
                     P p)
Specified by:
visitBinary in interface TreeVisitor<R,P>

visitTypeCast

public R visitTypeCast(TypeCastTree node,
                       P p)
Specified by:
visitTypeCast in interface TreeVisitor<R,P>

visitInstanceOf

public R visitInstanceOf(InstanceOfTree node,
                         P p)
Specified by:
visitInstanceOf in interface TreeVisitor<R,P>

visitArrayAccess

public R visitArrayAccess(ArrayAccessTree node,
                          P p)
Specified by:
visitArrayAccess in interface TreeVisitor<R,P>

visitMemberSelect

public R visitMemberSelect(MemberSelectTree node,
                           P p)
Specified by:
visitMemberSelect in interface TreeVisitor<R,P>

visitIdentifier

public R visitIdentifier(IdentifierTree node,
                         P p)
Specified by:
visitIdentifier in interface TreeVisitor<R,P>

visitLiteral

public R visitLiteral(LiteralTree node,
                      P p)
Specified by:
visitLiteral in interface TreeVisitor<R,P>

visitPrimitiveType

public R visitPrimitiveType(PrimitiveTypeTree node,
                            P p)
Specified by:
visitPrimitiveType in interface TreeVisitor<R,P>

visitArrayType

public R visitArrayType(ArrayTypeTree node,
                        P p)
Specified by:
visitArrayType in interface TreeVisitor<R,P>

visitParameterizedType

public R visitParameterizedType(ParameterizedTypeTree node,
                                P p)
Specified by:
visitParameterizedType in interface TreeVisitor<R,P>

visitTypeParameter

public R visitTypeParameter(TypeParameterTree node,
                            P p)
Specified by:
visitTypeParameter in interface TreeVisitor<R,P>

visitWildcard

public R visitWildcard(WildcardTree node,
                       P p)
Specified by:
visitWildcard in interface TreeVisitor<R,P>

visitModifiers

public R visitModifiers(ModifiersTree node,
                        P p)
Specified by:
visitModifiers in interface TreeVisitor<R,P>

visitAnnotation

public R visitAnnotation(AnnotationTree node,
                         P p)
Specified by:
visitAnnotation in interface TreeVisitor<R,P>

visitOther

public R visitOther(Tree node,
                    P p)
Specified by:
visitOther in interface TreeVisitor<R,P>

visitErroneous

public R visitErroneous(ErroneousTree node,
                        P p)
Specified by:
visitErroneous in interface TreeVisitor<R,P>
Overview Package Class Use Tree Deprecated Index Help
Compiler Tree API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD
Report a bug or request a feature.
Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.


 All Classes
AnnotationDesc
AnnotationDesc.ElementValuePair
AnnotationTypeDoc
AnnotationTypeElementDoc
AnnotationValue
ClassDoc
ConstructorDoc
Doc
DocErrorReporter
Doclet
ExecutableMemberDoc
FieldDoc
LanguageVersion
MemberDoc
MethodDoc
PackageDoc
Parameter
ParameterizedType
ParamTag
ProgramElementDoc
RootDoc
SeeTag
SerialFieldTag
SourcePosition
Tag
ThrowsTag
Type
TypeVariable
WildcardType


API Help

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

How This API Document Is Organized

This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.

Package

Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain four categories:

  • Interfaces (italic)
  • Classes
  • Enums
  • Exceptions
  • Errors
  • Annotation Types

Class/Interface

Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:

  • Class inheritance diagram
  • Direct Subclasses
  • All Known Subinterfaces
  • All Known Implementing Classes
  • Class/interface declaration
  • Class/interface description

  • Nested Class Summary
  • Field Summary
  • Constructor Summary
  • Method Summary

  • Field Detail
  • Constructor Detail
  • Method Detail
Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.

Annotation Type

Each annotation type has its own separate page with the following sections:

  • Annotation Type declaration
  • Annotation Type description
  • Required Element Summary
  • Optional Element Summary
  • Element Detail

Enum

Each enum has its own separate page with the following sections:

  • Enum declaration
  • Enum description
  • Enum Constant Summary
  • Enum Constant Detail

Use

Each documented package, class and interface has its own Use page. This page describes what packages, classes, methods, constructors and fields use any part of the given class or package. Given a class or interface A, its Use page includes subclasses of A, fields declared as A, methods that return A, and methods and constructors with parameters of type A. You can access this page by first going to the package, class or interface, then clicking on the "Use" link in the navigation bar.

Tree (Class Hierarchy)

There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with java.lang.Object. The interfaces do not inherit from java.lang.Object.
  • When viewing the Overview page, clicking on "Tree" displays the hierarchy for all packages.
  • When viewing a particular package, class or interface page, clicking "Tree" displays the hierarchy for only that package.

Deprecated API

The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.

Index

The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.

Prev/Next

These links take you to the next or previous class, interface, package, or related page.

Frames/No Frames

These links show and hide the HTML frames. All pages are available with or without frames.

Serialized Form

Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.

Constant Field Values

The Constant Field Values page lists the static final fields and their values.

This help file applies to API documentation generated using the standard doclet.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Constant Field Values

Contents
Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Deprecated List

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Deprecated API

Contents
  • Deprecated Methods
Deprecated Methods
com.sun.javadoc.ClassDoc.importedClasses()
Import declarations are implementation details that should not be exposed here. In addition, not all imported classes are imported through single-type-import declarations.
com.sun.javadoc.ClassDoc.importedPackages()
Import declarations are implementation details that should not be exposed here. In addition, this method's return type does not allow for all type-import-on-demand declarations to be returned.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Doclet API

Frame Alert

This document is designed to be viewed using the frames feature. If you see this message, you are using a non-frame-capable web client.
Link toNon-frame version.


Hierarchy

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Hierarchy For All Packages

Package Hierarchies:
com.sun.javadoc

Class Hierarchy

  • java.lang.Object
    • com.sun.javadoc.Doclet

Interface Hierarchy

  • com.sun.javadoc.AnnotationDesc
  • com.sun.javadoc.AnnotationDesc.ElementValuePair
  • com.sun.javadoc.AnnotationValue
  • java.lang.Comparable<T>
    • com.sun.javadoc.AnnotationTypeDoc
    • com.sun.javadoc.AnnotationTypeElementDoc
    • com.sun.javadoc.ClassDoc (also extends com.sun.javadoc.ProgramElementDoc, com.sun.javadoc.Type)
      • com.sun.javadoc.AnnotationTypeDoc
    • com.sun.javadoc.ConstructorDoc
    • com.sun.javadoc.Doc
      • com.sun.javadoc.AnnotationTypeDoc
      • com.sun.javadoc.AnnotationTypeElementDoc
      • com.sun.javadoc.ClassDoc (also extends com.sun.javadoc.ProgramElementDoc, com.sun.javadoc.Type)
        • com.sun.javadoc.AnnotationTypeDoc
      • com.sun.javadoc.ConstructorDoc
      • com.sun.javadoc.ExecutableMemberDoc
        • com.sun.javadoc.AnnotationTypeElementDoc
        • com.sun.javadoc.ConstructorDoc
        • com.sun.javadoc.MethodDoc
          • com.sun.javadoc.AnnotationTypeElementDoc
      • com.sun.javadoc.FieldDoc
      • com.sun.javadoc.MemberDoc
        • com.sun.javadoc.AnnotationTypeElementDoc
        • com.sun.javadoc.ConstructorDoc
        • com.sun.javadoc.ExecutableMemberDoc
          • com.sun.javadoc.AnnotationTypeElementDoc
          • com.sun.javadoc.ConstructorDoc
          • com.sun.javadoc.MethodDoc
            • com.sun.javadoc.AnnotationTypeElementDoc
        • com.sun.javadoc.FieldDoc
        • com.sun.javadoc.MethodDoc
          • com.sun.javadoc.AnnotationTypeElementDoc
      • com.sun.javadoc.MethodDoc
        • com.sun.javadoc.AnnotationTypeElementDoc
      • com.sun.javadoc.PackageDoc
      • com.sun.javadoc.ProgramElementDoc
        • com.sun.javadoc.AnnotationTypeDoc
        • com.sun.javadoc.AnnotationTypeElementDoc
        • com.sun.javadoc.ClassDoc (also extends com.sun.javadoc.Type)
          • com.sun.javadoc.AnnotationTypeDoc
        • com.sun.javadoc.ConstructorDoc
        • com.sun.javadoc.ExecutableMemberDoc
          • com.sun.javadoc.AnnotationTypeElementDoc
          • com.sun.javadoc.ConstructorDoc
          • com.sun.javadoc.MethodDoc
            • com.sun.javadoc.AnnotationTypeElementDoc
        • com.sun.javadoc.FieldDoc
        • com.sun.javadoc.MemberDoc
          • com.sun.javadoc.AnnotationTypeElementDoc
          • com.sun.javadoc.ConstructorDoc
          • com.sun.javadoc.ExecutableMemberDoc
            • com.sun.javadoc.AnnotationTypeElementDoc
            • com.sun.javadoc.ConstructorDoc
            • com.sun.javadoc.MethodDoc
              • com.sun.javadoc.AnnotationTypeElementDoc
          • com.sun.javadoc.FieldDoc
          • com.sun.javadoc.MethodDoc
            • com.sun.javadoc.AnnotationTypeElementDoc
        • com.sun.javadoc.MethodDoc
          • com.sun.javadoc.AnnotationTypeElementDoc
      • com.sun.javadoc.RootDoc (also extends com.sun.javadoc.DocErrorReporter)
    • com.sun.javadoc.ExecutableMemberDoc
      • com.sun.javadoc.AnnotationTypeElementDoc
      • com.sun.javadoc.ConstructorDoc
      • com.sun.javadoc.MethodDoc
        • com.sun.javadoc.AnnotationTypeElementDoc
    • com.sun.javadoc.FieldDoc
    • com.sun.javadoc.MemberDoc
      • com.sun.javadoc.AnnotationTypeElementDoc
      • com.sun.javadoc.ConstructorDoc
      • com.sun.javadoc.ExecutableMemberDoc
        • com.sun.javadoc.AnnotationTypeElementDoc
        • com.sun.javadoc.ConstructorDoc
        • com.sun.javadoc.MethodDoc
          • com.sun.javadoc.AnnotationTypeElementDoc
      • com.sun.javadoc.FieldDoc
      • com.sun.javadoc.MethodDoc
        • com.sun.javadoc.AnnotationTypeElementDoc
    • com.sun.javadoc.MethodDoc
      • com.sun.javadoc.AnnotationTypeElementDoc
    • com.sun.javadoc.PackageDoc
    • com.sun.javadoc.ProgramElementDoc
      • com.sun.javadoc.AnnotationTypeDoc
      • com.sun.javadoc.AnnotationTypeElementDoc
      • com.sun.javadoc.ClassDoc (also extends com.sun.javadoc.Type)
        • com.sun.javadoc.AnnotationTypeDoc
      • com.sun.javadoc.ConstructorDoc
      • com.sun.javadoc.ExecutableMemberDoc
        • com.sun.javadoc.AnnotationTypeElementDoc
        • com.sun.javadoc.ConstructorDoc
        • com.sun.javadoc.MethodDoc
          • com.sun.javadoc.AnnotationTypeElementDoc
      • com.sun.javadoc.FieldDoc
      • com.sun.javadoc.MemberDoc
        • com.sun.javadoc.AnnotationTypeElementDoc
        • com.sun.javadoc.ConstructorDoc
        • com.sun.javadoc.ExecutableMemberDoc
          • com.sun.javadoc.AnnotationTypeElementDoc
          • com.sun.javadoc.ConstructorDoc
          • com.sun.javadoc.MethodDoc
            • com.sun.javadoc.AnnotationTypeElementDoc
        • com.sun.javadoc.FieldDoc
        • com.sun.javadoc.MethodDoc
          • com.sun.javadoc.AnnotationTypeElementDoc
      • com.sun.javadoc.MethodDoc
        • com.sun.javadoc.AnnotationTypeElementDoc
    • com.sun.javadoc.RootDoc (also extends com.sun.javadoc.Doc, com.sun.javadoc.DocErrorReporter)
    • com.sun.javadoc.SerialFieldTag (also extends com.sun.javadoc.Tag)
  • com.sun.javadoc.DocErrorReporter
    • com.sun.javadoc.RootDoc (also extends com.sun.javadoc.Doc)
  • com.sun.javadoc.Parameter
  • com.sun.javadoc.SourcePosition
  • com.sun.javadoc.Tag
    • com.sun.javadoc.ParamTag
    • com.sun.javadoc.SeeTag
    • com.sun.javadoc.SerialFieldTag (also extends java.lang.Comparable<T>)
    • com.sun.javadoc.ThrowsTag
  • com.sun.javadoc.Type
    • com.sun.javadoc.AnnotationTypeDoc
    • com.sun.javadoc.ClassDoc (also extends com.sun.javadoc.ProgramElementDoc)
      • com.sun.javadoc.AnnotationTypeDoc
    • com.sun.javadoc.ParameterizedType
    • com.sun.javadoc.TypeVariable
    • com.sun.javadoc.WildcardType

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • com.sun.javadoc.LanguageVersion
Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Index

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
A B C D E F G H I K L M N O P Q R S T V W

A

allClasses(boolean) - Method in interface com.sun.javadoc.PackageDoc
Get all classes and interfaces in the package, filtered to the specified access modifier option.
allClasses() - Method in interface com.sun.javadoc.PackageDoc
Get all included classes and interfaces in the package.
AnnotationDesc - Interface in com.sun.javadoc
Represents an annotation.
AnnotationDesc.ElementValuePair - Interface in com.sun.javadoc
Represents an association between an annotation type element and one of its values.
annotations() - Method in interface com.sun.javadoc.PackageDoc
Get the annotations of this package.
annotations() - Method in interface com.sun.javadoc.Parameter
Get the annotations of this parameter.
annotations() - Method in interface com.sun.javadoc.ProgramElementDoc
Get the annotations of this program element.
annotationType() - Method in interface com.sun.javadoc.AnnotationDesc
Returns the annotation type of this annotation.
AnnotationTypeDoc - Interface in com.sun.javadoc
Represents an annotation type.
AnnotationTypeElementDoc - Interface in com.sun.javadoc
Represents an element of an annotation type.
annotationTypes() - Method in interface com.sun.javadoc.PackageDoc
Get included annotation types in this package.
AnnotationValue - Interface in com.sun.javadoc
Represents a value of an annotation type element.
asAnnotationTypeDoc() - Method in interface com.sun.javadoc.Type
Return this type as an AnnotationTypeDoc if it represents an annotation type.
asClassDoc() - Method in interface com.sun.javadoc.ParameterizedType
Return the generic class or interface that declared this type.
asClassDoc() - Method in interface com.sun.javadoc.Type
Return this type as a ClassDoc if it represents a class or interface.
asParameterizedType() - Method in interface com.sun.javadoc.Type
Return this type as a ParameterizedType if it represents an invocation of a generic class or interface.
asTypeVariable() - Method in interface com.sun.javadoc.Type
Return this type as a TypeVariable if it represents a type variable.
asWildcardType() - Method in interface com.sun.javadoc.Type
Return this type as a WildcardType if it represents a wildcard type.

B

bounds() - Method in interface com.sun.javadoc.TypeVariable
Return the bounds of this type variable.

C

ClassDoc - Interface in com.sun.javadoc
Represents a java class or interface and provides access to information about the class, the class's comment and tags, and the members of the class.
classes() - Method in interface com.sun.javadoc.RootDoc
Return the included classes and interfaces in all packages.
classNamed(String) - Method in interface com.sun.javadoc.RootDoc
Return a ClassDoc for the specified class or interface name.
column() - Method in interface com.sun.javadoc.SourcePosition
The column in the source file.
com.sun.javadoc - package com.sun.javadoc
The Doclet API (also called the Javadoc API) provides a mechanism for clients to inspect the source-level structure of programs and libraries, including javadoc comments embedded in the source.
commentText() - Method in interface com.sun.javadoc.Doc
Return the text of the comment for this doc item.
compareTo(Object) - Method in interface com.sun.javadoc.Doc
Compares this doc object with the specified object for order.
compareTo(Object) - Method in interface com.sun.javadoc.SerialFieldTag
Compares this Object with the specified Object for order.
constantValue() - Method in interface com.sun.javadoc.FieldDoc
Get the value of a constant field.
constantValueExpression() - Method in interface com.sun.javadoc.FieldDoc
Get the value of a constant field.
ConstructorDoc - Interface in com.sun.javadoc
Represents a constructor of a java class.
constructors() - Method in interface com.sun.javadoc.ClassDoc
Return included constructors in this class.
constructors(boolean) - Method in interface com.sun.javadoc.ClassDoc
Return constructors in this class, filtered to the specified access modifier option.
containingClass() - Method in interface com.sun.javadoc.ProgramElementDoc
Get the containing class or interface of this program element.
containingPackage() - Method in interface com.sun.javadoc.ProgramElementDoc
Get the package that this program element is contained in.
containingType() - Method in interface com.sun.javadoc.ParameterizedType
Return the type that contains this type as a member.

D

defaultValue() - Method in interface com.sun.javadoc.AnnotationTypeElementDoc
Returns the default value of this element.
definesSerializableFields() - Method in interface com.sun.javadoc.ClassDoc
Return true if Serializable fields are explicitly defined with the special class member serialPersistentFields.
description() - Method in interface com.sun.javadoc.SerialFieldTag
Return the field comment.
dimension() - Method in interface com.sun.javadoc.Type
Return the type's dimension information, as a string.
Doc - Interface in com.sun.javadoc
Represents Java language constructs (package, class, constructor, method, field) which have comments and have been processed by this run of javadoc.
DocErrorReporter - Interface in com.sun.javadoc
This interface provides error, warning and notice printing.
Doclet - Class in com.sun.javadoc
This is an example of a starting class for a doclet, showing the entry-point methods.
Doclet() - Constructor for class com.sun.javadoc.Doclet

E

element() - Method in interface com.sun.javadoc.AnnotationDesc.ElementValuePair
Returns the annotation type element.
elements() - Method in interface com.sun.javadoc.AnnotationTypeDoc
Returns the elements of this annotation type.
elementValues() - Method in interface com.sun.javadoc.AnnotationDesc
Returns this annotation's elements and their values.
enumConstants() - Method in interface com.sun.javadoc.ClassDoc
Return the enum constants if this is an enum type.
enums() - Method in interface com.sun.javadoc.PackageDoc
Get included enum types in this package.
errors() - Method in interface com.sun.javadoc.PackageDoc
Get included Error classes in this package.
exception() - Method in interface com.sun.javadoc.ThrowsTag
Return a ClassDoc that represents the exception.
exceptionComment() - Method in interface com.sun.javadoc.ThrowsTag
Return the exception comment associated with this ThrowsTag.
exceptionName() - Method in interface com.sun.javadoc.ThrowsTag
Return the name of the exception associated with this ThrowsTag.
exceptions() - Method in interface com.sun.javadoc.PackageDoc
Get included Exception classes in this package.
exceptionType() - Method in interface com.sun.javadoc.ThrowsTag
Return the type of the exception associated with this ThrowsTag.
ExecutableMemberDoc - Interface in com.sun.javadoc
Represents a method or constructor of a java class.
extendsBounds() - Method in interface com.sun.javadoc.WildcardType
Return the upper bounds of this wildcard type argument as given by the extends clause.

F

FieldDoc - Interface in com.sun.javadoc
Represents a field in a java class.
fieldName() - Method in interface com.sun.javadoc.SerialFieldTag
Return the serialziable field name.
fields() - Method in interface com.sun.javadoc.ClassDoc
Return included fields in this class or interface.
fields(boolean) - Method in interface com.sun.javadoc.ClassDoc
Return fields in this class or interface, filtered to the specified access modifier option.
fieldType() - Method in interface com.sun.javadoc.SerialFieldTag
Return the field type string.
fieldTypeDoc() - Method in interface com.sun.javadoc.SerialFieldTag
Return the ClassDoc for field type.
file() - Method in interface com.sun.javadoc.SourcePosition
The source file.
findClass(String) - Method in interface com.sun.javadoc.ClassDoc
Find the specified class or interface within the context of this class doc.
findClass(String) - Method in interface com.sun.javadoc.PackageDoc
Lookup a class or interface within this package.
firstSentenceTags() - Method in interface com.sun.javadoc.Doc
Return the first sentence of the comment as an array of tags.
firstSentenceTags() - Method in interface com.sun.javadoc.Tag
Return the first sentence of the comment as an array of tags.
flatSignature() - Method in interface com.sun.javadoc.ExecutableMemberDoc
get flat signature.

G

getRawCommentText() - Method in interface com.sun.javadoc.Doc
Return the full unprocessed text of the comment.

H

holder() - Method in interface com.sun.javadoc.Tag
Return the containing Doc of this Tag element.

I

importedClasses() - Method in interface com.sun.javadoc.ClassDoc
Deprecated. Import declarations are implementation details that should not be exposed here. In addition, not all imported classes are imported through single-type-import declarations.
importedPackages() - Method in interface com.sun.javadoc.ClassDoc
Deprecated. Import declarations are implementation details that should not be exposed here. In addition, this method's return type does not allow for all type-import-on-demand declarations to be returned.
inlineTags() - Method in interface com.sun.javadoc.Doc
Return comment as an array of tags.
inlineTags() - Method in interface com.sun.javadoc.Tag
For a documentation comment with embedded {@link} tags, return an array of Tag objects.
innerClasses() - Method in interface com.sun.javadoc.ClassDoc
Return included nested classes and interfaces within this class or interface.
innerClasses(boolean) - Method in interface com.sun.javadoc.ClassDoc
Return nested classes and interfaces within this class or interface filtered to the specified access modifier option.
interfaces() - Method in interface com.sun.javadoc.ClassDoc
Return interfaces implemented by this class or interfaces extended by this interface.
interfaces() - Method in interface com.sun.javadoc.PackageDoc
Get included interfaces in this package, omitting annotation types.
interfaceTypes() - Method in interface com.sun.javadoc.ClassDoc
Return interfaces implemented by this class or interfaces extended by this interface.
interfaceTypes() - Method in interface com.sun.javadoc.ParameterizedType
Return the interface types directly implemented by or extended by this parameterized type.
isAbstract() - Method in interface com.sun.javadoc.ClassDoc
Return true if this class is abstract.
isAbstract() - Method in interface com.sun.javadoc.MethodDoc
Return true if this method is abstract
isAnnotationType() - Method in interface com.sun.javadoc.Doc
Is this Doc item an annotation type?
isAnnotationTypeElement() - Method in interface com.sun.javadoc.Doc
Is this Doc item an annotation type element?
isClass() - Method in interface com.sun.javadoc.Doc
Is this Doc item a class (and not an interface or annotation type)?
isConstructor() - Method in interface com.sun.javadoc.Doc
Is this Doc item a constructor?
isEnum() - Method in interface com.sun.javadoc.Doc
Is this Doc item an enum type?
isEnumConstant() - Method in interface com.sun.javadoc.Doc
Is this Doc item an enum constant?
isError() - Method in interface com.sun.javadoc.Doc
Is this Doc item an error class?
isException() - Method in interface com.sun.javadoc.Doc
Is this Doc item an exception class?
isExternalizable() - Method in interface com.sun.javadoc.ClassDoc
Return true if this class implements or interface extends java.io.Externalizable.
isField() - Method in interface com.sun.javadoc.Doc
Is this Doc item a field (but not an enum constant)?
isFinal() - Method in interface com.sun.javadoc.ProgramElementDoc
Return true if this program element is final.
isIncluded() - Method in interface com.sun.javadoc.Doc
Return true if this Doc item is included in the result set.
isInterface() - Method in interface com.sun.javadoc.Doc
Is this Doc item an interface (but not an annotation type)?
isMethod() - Method in interface com.sun.javadoc.Doc
Is this Doc item a method (but not a constructor or annotation type element)?
isNative() - Method in interface com.sun.javadoc.ExecutableMemberDoc
Return true if this method is native
isOrdinaryClass() - Method in interface com.sun.javadoc.Doc
Is this Doc item an ordinary class?
isPackagePrivate() - Method in interface com.sun.javadoc.ProgramElementDoc
Return true if this program element is package private.
isPrimitive() - Method in interface com.sun.javadoc.Type
Return true if this type represents a primitive type.
isPrivate() - Method in interface com.sun.javadoc.ProgramElementDoc
Return true if this program element is private.
isProtected() - Method in interface com.sun.javadoc.ProgramElementDoc
Return true if this program element is protected.
isPublic() - Method in interface com.sun.javadoc.ProgramElementDoc
Return true if this program element is public.
isSerializable() - Method in interface com.sun.javadoc.ClassDoc
Return true if this class implements or interface extends java.io.Serializable.
isStatic() - Method in interface com.sun.javadoc.ProgramElementDoc
Return true if this program element is static.
isSynchronized() - Method in interface com.sun.javadoc.ExecutableMemberDoc
Return true if this method is synchronized
isSynthetic() - Method in interface com.sun.javadoc.MemberDoc
Returns true if this member was synthesized by the compiler.
isTransient() - Method in interface com.sun.javadoc.FieldDoc
Return true if this field is transient
isTypeParameter() - Method in interface com.sun.javadoc.ParamTag
Return true if this ParamTag corresponds to a type parameter.
isVarArgs() - Method in interface com.sun.javadoc.ExecutableMemberDoc
Return true if this method was declared to take a variable number of arguments.
isVolatile() - Method in interface com.sun.javadoc.FieldDoc
Return true if this field is volatile

K

kind() - Method in interface com.sun.javadoc.Tag
Return the kind of this tag.

L

label() - Method in interface com.sun.javadoc.SeeTag
Get the label of the @see tag.
languageVersion() - Static method in class com.sun.javadoc.Doclet
Return the version of the Java Programming Language supported by this doclet.
LanguageVersion - Enum in com.sun.javadoc
Java Programming Language version.
line() - Method in interface com.sun.javadoc.SourcePosition
The line in the source file.

M

MemberDoc - Interface in com.sun.javadoc
Represents a member of a java class: field, constructor, or method.
MethodDoc - Interface in com.sun.javadoc
Represents a method of a java class.
methods() - Method in interface com.sun.javadoc.ClassDoc
Return included methods in this class or interface.
methods(boolean) - Method in interface com.sun.javadoc.ClassDoc
Return methods in this class or interface, filtered to the specified access modifier option.
modifiers() - Method in interface com.sun.javadoc.ProgramElementDoc
Get modifiers string.
modifierSpecifier() - Method in interface com.sun.javadoc.ProgramElementDoc
Get the modifier specifier integer.

N

name() - Method in interface com.sun.javadoc.Doc
Returns the non-qualified name of this Doc item.
name() - Method in interface com.sun.javadoc.Parameter
Get local name of this parameter.
name() - Method in interface com.sun.javadoc.Tag
Return the name of this tag.

O

optionLength(String) - Static method in class com.sun.javadoc.Doclet
Check for doclet-added options.
options() - Method in interface com.sun.javadoc.RootDoc
Command line options.
ordinaryClasses() - Method in interface com.sun.javadoc.PackageDoc
Get included ordinary classes (that is, exclude exceptions, errors, enums, interfaces, and annotation types) in this package.
overriddenClass() - Method in interface com.sun.javadoc.MethodDoc
Return the class containing the method that this method overrides.
overriddenMethod() - Method in interface com.sun.javadoc.MethodDoc
Return the method that this method overrides.
overriddenType() - Method in interface com.sun.javadoc.MethodDoc
Return the type containing the method that this method overrides.
overrides(MethodDoc) - Method in interface com.sun.javadoc.MethodDoc
Tests whether this method overrides another.
owner() - Method in interface com.sun.javadoc.TypeVariable
Return the class, interface, method, or constructor within which this type variable is declared.

P

PackageDoc - Interface in com.sun.javadoc
Represents a java package.
packageNamed(String) - Method in interface com.sun.javadoc.RootDoc
Return a PackageDoc for the specified package name.
Parameter - Interface in com.sun.javadoc
Parameter information.
parameterComment() - Method in interface com.sun.javadoc.ParamTag
Return the parameter comment associated with this ParamTag.
ParameterizedType - Interface in com.sun.javadoc
Represents an invocation of a generic class or interface.
parameterName() - Method in interface com.sun.javadoc.ParamTag
Return the name of the parameter or type parameter associated with this ParamTag.
parameters() - Method in interface com.sun.javadoc.ExecutableMemberDoc
Get argument information.
ParamTag - Interface in com.sun.javadoc
Represents an @param documentation tag.
paramTags() - Method in interface com.sun.javadoc.ExecutableMemberDoc
Return the param tags in this method, excluding the type parameter tags.
position() - Method in interface com.sun.javadoc.Doc
Return the source position of the first line of the corresponding declaration, or null if no position is available.
position() - Method in interface com.sun.javadoc.Tag
Return the source position of this tag.
printError(String) - Method in interface com.sun.javadoc.DocErrorReporter
Print error message and increment error count.
printError(SourcePosition, String) - Method in interface com.sun.javadoc.DocErrorReporter
Print an error message and increment error count.
printNotice(String) - Method in interface com.sun.javadoc.DocErrorReporter
Print a message.
printNotice(SourcePosition, String) - Method in interface com.sun.javadoc.DocErrorReporter
Print a message.
printWarning(String) - Method in interface com.sun.javadoc.DocErrorReporter
Print warning message and increment warning count.
printWarning(SourcePosition, String) - Method in interface com.sun.javadoc.DocErrorReporter
Print warning message and increment warning count.
ProgramElementDoc - Interface in com.sun.javadoc
Represents a java program element: class, interface, field, constructor, or method.

Q

qualifiedName() - Method in interface com.sun.javadoc.ProgramElementDoc
Get the fully qualified name of this program element.
qualifiedTypeName() - Method in interface com.sun.javadoc.Type
Return qualified name of type excluding any dimension information.

R

referencedClass() - Method in interface com.sun.javadoc.SeeTag
Get the class doc referenced by the class name part of @see.
referencedClassName() - Method in interface com.sun.javadoc.SeeTag
Get the class or interface name of the @see reference.
referencedMember() - Method in interface com.sun.javadoc.SeeTag
Get the member doc for the field, constructor or method referenced by @see.
referencedMemberName() - Method in interface com.sun.javadoc.SeeTag
Get the field, constructor or method substring of the @see reference.
referencedPackage() - Method in interface com.sun.javadoc.SeeTag
Get the package doc when @see references only a package.
returnType() - Method in interface com.sun.javadoc.MethodDoc
Get return type.
RootDoc - Interface in com.sun.javadoc
Represents the root of the program structure information for one run of javadoc.

S

SeeTag - Interface in com.sun.javadoc
Represents a user-defined cross-reference to related documentation.
seeTags() - Method in interface com.sun.javadoc.Doc
Return the see also tags in this Doc item.
SerialFieldTag - Interface in com.sun.javadoc
Documents a Serializable field defined by an ObjectStreamField.
serialFieldTags() - Method in interface com.sun.javadoc.FieldDoc
Return the serialField tags in this FieldDoc item.
serializableFields() - Method in interface com.sun.javadoc.ClassDoc
Return the Serializable fields of this class or interface.
serializationMethods() - Method in interface com.sun.javadoc.ClassDoc
Return the serialization methods for this class or interface.
setRawCommentText(String) - Method in interface com.sun.javadoc.Doc
Set the full unprocessed text of the comment.
signature() - Method in interface com.sun.javadoc.ExecutableMemberDoc
Get the signature.
simpleTypeName() - Method in interface com.sun.javadoc.Type
Return the simple name of this type excluding any dimension information.
SourcePosition - Interface in com.sun.javadoc
This interface describes a source position: filename, line number, and column number.
specifiedClasses() - Method in interface com.sun.javadoc.RootDoc
Return the classes and interfaces specified as source file names on the command line.
specifiedPackages() - Method in interface com.sun.javadoc.RootDoc
Return the packages specified on the command line.
start(RootDoc) - Static method in class com.sun.javadoc.Doclet
Generate documentation here.
subclassOf(ClassDoc) - Method in interface com.sun.javadoc.ClassDoc
Test whether this class is a subclass of the specified class.
superBounds() - Method in interface com.sun.javadoc.WildcardType
Return the lower bounds of this wildcard type argument as given by the super clause.
superclass() - Method in interface com.sun.javadoc.ClassDoc
Return the superclass of this class.
superclassType() - Method in interface com.sun.javadoc.ClassDoc
Return the superclass of this class.
superclassType() - Method in interface com.sun.javadoc.ParameterizedType
Return the class type that is a direct supertype of this one.

T

Tag - Interface in com.sun.javadoc
Represents a simple documentation tag, such as @since, @author, @version.
tags() - Method in interface com.sun.javadoc.Doc
Return all tags in this Doc item.
tags(String) - Method in interface com.sun.javadoc.Doc
Return tags of the specified kind in this Doc item.
text() - Method in interface com.sun.javadoc.Tag
Return the text of this tag, that is, portion beyond tag name.
thrownExceptions() - Method in interface com.sun.javadoc.ExecutableMemberDoc
Return exceptions this method or constructor throws.
thrownExceptionTypes() - Method in interface com.sun.javadoc.ExecutableMemberDoc
Return exceptions this method or constructor throws.
ThrowsTag - Interface in com.sun.javadoc
Represents a @throws or @exception documentation tag.
throwsTags() - Method in interface com.sun.javadoc.ExecutableMemberDoc
Return the throws tags in this method.
toString() - Method in interface com.sun.javadoc.AnnotationValue
Returns a string representation of the value.
toString() - Method in interface com.sun.javadoc.Parameter
Returns a string representation of the parameter.
toString() - Method in interface com.sun.javadoc.SourcePosition
Convert the source position to the form "Filename:line".
toString() - Method in interface com.sun.javadoc.Tag
Convert this object to a string.
toString() - Method in interface com.sun.javadoc.Type
Return a string representation of the type.
type() - Method in interface com.sun.javadoc.FieldDoc
Get type of this field.
type() - Method in interface com.sun.javadoc.Parameter
Get the type of this parameter.
Type - Interface in com.sun.javadoc
Represents a type.
typeArguments() - Method in interface com.sun.javadoc.ParameterizedType
Return the actual type arguments of this type.
typeName() - Method in interface com.sun.javadoc.Parameter
Get type name of this parameter.
typeName() - Method in interface com.sun.javadoc.Type
Return unqualified name of type excluding any dimension information.
typeParameters() - Method in interface com.sun.javadoc.ClassDoc
Return the formal type parameters of this class or interface.
typeParameters() - Method in interface com.sun.javadoc.ExecutableMemberDoc
Return the formal type parameters of this method or constructor.
typeParamTags() - Method in interface com.sun.javadoc.ClassDoc
Return the type parameter tags of this class or interface.
typeParamTags() - Method in interface com.sun.javadoc.ExecutableMemberDoc
Return the type parameter tags in this method.
TypeVariable - Interface in com.sun.javadoc
Represents a type variable.

V

validOptions(String[][], DocErrorReporter) - Static method in class com.sun.javadoc.Doclet
Check that options have the correct arguments.
value() - Method in interface com.sun.javadoc.AnnotationDesc.ElementValuePair
Returns the value associated with the annotation type element.
value() - Method in interface com.sun.javadoc.AnnotationValue
Returns the value.
valueOf(String) - Static method in enum com.sun.javadoc.LanguageVersion
Returns the enum constant of this type with the specified name.
values() - Static method in enum com.sun.javadoc.LanguageVersion
Returns an array containing the constants of this enum type, in the order they are declared.

W

WildcardType - Interface in com.sun.javadoc
Represents a wildcard type argument.
A B C D E F G H I K L M N O P Q R S T V W
Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


javadoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package com.sun.javadoc

The Doclet API (also called the Javadoc API) provides a mechanism for clients to inspect the source-level structure of programs and libraries, including javadoc comments embedded in the source.

See:
Description

Interface Summary
AnnotationDesc | Represents an annotation.
AnnotationDesc.ElementValuePair | Represents an association between an annotation type element and one of its values.
AnnotationTypeDoc | Represents an annotation type.
AnnotationTypeElementDoc | Represents an element of an annotation type.
AnnotationValue | Represents a value of an annotation type element.
ClassDoc | Represents a java class or interface and provides access to information about the class, the class's comment and tags, and the members of the class.
ConstructorDoc | Represents a constructor of a java class.
Doc | Represents Java language constructs (package, class, constructor, method, field) which have comments and have been processed by this run of javadoc.
DocErrorReporter | This interface provides error, warning and notice printing.
ExecutableMemberDoc | Represents a method or constructor of a java class.
FieldDoc | Represents a field in a java class.
MemberDoc | Represents a member of a java class: field, constructor, or method.
MethodDoc | Represents a method of a java class.
PackageDoc | Represents a java package.
Parameter | Parameter information.
ParameterizedType | Represents an invocation of a generic class or interface.
ParamTag | Represents an @param documentation tag.
ProgramElementDoc | Represents a java program element: class, interface, field, constructor, or method.
RootDoc | Represents the root of the program structure information for one run of javadoc.
SeeTag | Represents a user-defined cross-reference to related documentation.
SerialFieldTag | Documents a Serializable field defined by an ObjectStreamField.
SourcePosition | This interface describes a source position: filename, line number, and column number.
Tag | Represents a simple documentation tag, such as @since, @author, @version.
ThrowsTag | Represents a @throws or @exception documentation tag.
Type | Represents a type.
TypeVariable | Represents a type variable.
WildcardType | Represents a wildcard type argument.

Class Summary
Doclet This is an example of a starting class for a doclet, showing the entry-point methods.

Enum Summary
LanguageVersion Java Programming Language version.

Package com.sun.javadoc Description

The Doclet API (also called the Javadoc API) provides a mechanism for clients to inspect the source-level structure of programs and libraries, including javadoc comments embedded in the source. This is useful for documentation, program checking, automatic code generation and many other tools.

Doclets are invoked by javadoc and use this API to write out program information to files. For example, the standard doclet is called by default and writes out documentation to HTML files.

The invocation is defined by the abstract Doclet class -- the entry point is the start method:

    public static boolean start(RootDoc root)
The RootDoc instance holds the root of the program structure information. From this root all other program structure information can be extracted.

Terminology

When calling javadoc, you pass in package names and source file names -- these are called the specified packages and classes. You also pass in Javadoc options; the access control Javadoc options (-public, -protected, -package, and -private) filter program elements, producing a result set, called the included set, or "documented" set. (The unfiltered set is also available through allClasses(false).)

Throughout this API, the term class is normally a shorthand for "class or interface", as in: ClassDoc, allClasses(), and findClass(String). In only a couple of other places, it means "class, as opposed to interface", as in: Doc.isClass(). In the second sense, this API calls out four kinds of classes: ordinary classes, enums, errors and exceptions. Throughout the API, the detailed description of each program element describes explicitly which meaning is being used.

A qualified class or interface name is one that has its package name prepended to it, such as java.lang.String. A non-qualified name has no package name, such as String.

Example

The following is an example doclet that displays information in the @param tags of the processed classes:
import com.sun.javadoc.*;

public class ListParams extends Doclet {

    public static boolean start(RootDoc root) {
        ClassDoc[] classes = root.classes();
        for (int i = 0; i < classes.length; ++i) {
            ClassDoc cd = classes[i];
            printMembers(cd.constructors());
            printMembers(cd.methods());
        }
        return true;
    }

    static void printMembers(ExecutableMemberDoc[] mems) {
        for (int i = 0; i < mems.length; ++i) {
            ParamTag[] params = mems[i].paramTags();
            System.out.println(mems[i].qualifiedName());
            for (int j = 0; j < params.length; ++j) {
                System.out.println("   " + params[j].parameterName()
                    + " - " + params[j].parameterComment());
            }
        }
    }
}
Interfaces and methods from the Javadoc API are marked in red. Doclet is an abstract class that specifies the invocation interface for doclets, Doclet holds class or interface information, ExecutableMemberDoc is a superinterface of MethodDoc and ConstructorDoc, and ParamTag holds information from "@param" tags.

This doclet when invoked with a command line like:

    javadoc -doclet ListParams -sourcepath <source-location> java.util
producing output like:
    ...
    java.util.ArrayList.add
       index - index at which the specified element is to be inserted.
       element - element to be inserted.
    java.util.ArrayList.remove
       index - the index of the element to removed.
    ...

See Also:
Doclet, RootDoc
Package Class Use Tree Deprecated Index Help
Doclet API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


com.sun.javadoc Class Hierarchy

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Hierarchy For Package com.sun.javadoc

Class Hierarchy

  • java.lang.Object
    • com.sun.javadoc.Doclet

Interface Hierarchy

  • com.sun.javadoc.AnnotationDesc
  • com.sun.javadoc.AnnotationDesc.ElementValuePair
  • com.sun.javadoc.AnnotationValue
  • java.lang.Comparable<T>
    • com.sun.javadoc.Doc
      • com.sun.javadoc.PackageDoc
      • com.sun.javadoc.ProgramElementDoc
        • com.sun.javadoc.ClassDoc (also extends com.sun.javadoc.Type)
          • com.sun.javadoc.AnnotationTypeDoc
        • com.sun.javadoc.MemberDoc
          • com.sun.javadoc.ExecutableMemberDoc
            • com.sun.javadoc.ConstructorDoc
            • com.sun.javadoc.MethodDoc
              • com.sun.javadoc.AnnotationTypeElementDoc
          • com.sun.javadoc.FieldDoc
      • com.sun.javadoc.RootDoc (also extends com.sun.javadoc.DocErrorReporter)
    • com.sun.javadoc.SerialFieldTag (also extends com.sun.javadoc.Tag)
  • com.sun.javadoc.DocErrorReporter
    • com.sun.javadoc.RootDoc (also extends com.sun.javadoc.Doc)
  • com.sun.javadoc.Parameter
  • com.sun.javadoc.SourcePosition
  • com.sun.javadoc.Tag
    • com.sun.javadoc.ParamTag
    • com.sun.javadoc.SeeTag
    • com.sun.javadoc.SerialFieldTag (also extends java.lang.Comparable<T>)
    • com.sun.javadoc.ThrowsTag
  • com.sun.javadoc.Type
    • com.sun.javadoc.ClassDoc (also extends com.sun.javadoc.ProgramElementDoc)
      • com.sun.javadoc.AnnotationTypeDoc
    • com.sun.javadoc.ParameterizedType
    • com.sun.javadoc.TypeVariable
    • com.sun.javadoc.WildcardType

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • com.sun.javadoc.LanguageVersion
Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


ConstructorDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface ConstructorDoc

All Superinterfaces:
Comparable<Object>, Doc, ExecutableMemberDoc, MemberDoc, ProgramElementDoc
public interface ConstructorDoc
extends ExecutableMemberDoc

Represents a constructor of a java class.

Since:
1.2

Method Summary
Methods inherited from interface com.sun.javadoc.ExecutableMemberDoc
flatSignature, isNative, isSynchronized, isVarArgs, parameters, paramTags, signature, thrownExceptions, thrownExceptionTypes, throwsTags, typeParameters, typeParamTags
Methods inherited from interface com.sun.javadoc.MemberDoc
isSynthetic
Methods inherited from interface com.sun.javadoc.ProgramElementDoc
annotations, containingClass, containingPackage, isFinal, isPackagePrivate, isPrivate, isProtected, isPublic, isStatic, modifiers, modifierSpecifier, qualifiedName
Methods inherited from interface com.sun.javadoc.Doc
commentText, compareTo, firstSentenceTags, getRawCommentText, inlineTags, isAnnotationType, isAnnotationTypeElement, isClass, isConstructor, isEnum, isEnumConstant, isError, isException, isField, isIncluded, isInterface, isMethod, isOrdinaryClass, name, position, seeTags, setRawCommentText, tags, tags

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Package com.sun.javadoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Package
com.sun.javadoc

Classes in com.sun.javadoc used by com.sun.javadoc
AnnotationDesc
Represents an annotation.
AnnotationDesc.ElementValuePair
Represents an association between an annotation type element and one of its values.
AnnotationTypeDoc
Represents an annotation type.
AnnotationTypeElementDoc
Represents an element of an annotation type.
AnnotationValue
Represents a value of an annotation type element.
ClassDoc
Represents a java class or interface and provides access to information about the class, the class's comment and tags, and the members of the class.
ConstructorDoc
Represents a constructor of a java class.
Doc
Represents Java language constructs (package, class, constructor, method, field) which have comments and have been processed by this run of javadoc.
DocErrorReporter
This interface provides error, warning and notice printing.
ExecutableMemberDoc
Represents a method or constructor of a java class.
FieldDoc
Represents a field in a java class.
LanguageVersion
Java Programming Language version.
MemberDoc
Represents a member of a java class: field, constructor, or method.
MethodDoc
Represents a method of a java class.
PackageDoc
Represents a java package.
Parameter
Parameter information.
ParameterizedType
Represents an invocation of a generic class or interface.
ParamTag
Represents an @param documentation tag.
ProgramElementDoc
Represents a java program element: class, interface, field, constructor, or method.
RootDoc
Represents the root of the program structure information for one run of javadoc.
SeeTag
Represents a user-defined cross-reference to related documentation.
SerialFieldTag
Documents a Serializable field defined by an ObjectStreamField.
SourcePosition
This interface describes a source position: filename, line number, and column number.
Tag
Represents a simple documentation tag, such as @since, @author, @version.
ThrowsTag
Represents a @throws or @exception documentation tag.
Type
Represents a type.
TypeVariable
Represents a type variable.
WildcardType
Represents a wildcard type argument.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


AnnotationDesc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface AnnotationDesc

public interface AnnotationDesc

Represents an annotation. An annotation associates a value with each element of an annotation type.

Since:
1.5

Nested Class Summary
static interface AnnotationDesc.ElementValuePair
Represents an association between an annotation type element and one of its values.
Method Summary
AnnotationTypeDoc | annotationType() Returns the annotation type of this annotation.
AnnotationDesc.ElementValuePair[] | elementValues() Returns this annotation's elements and their values.

Method Detail

annotationType

AnnotationTypeDoc annotationType()
Returns the annotation type of this annotation.

Returns:
the annotation type of this annotation.

elementValues

AnnotationDesc.ElementValuePair[] elementValues()
Returns this annotation's elements and their values. Only those explicitly present in the annotation are included, not those assuming their default values. Returns an empty array if there are none.

Returns:
this annotation's elements and their values.
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


AnnotationDesc.ElementValuePair

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface AnnotationDesc.ElementValuePair

Enclosing interface:
AnnotationDesc
public static interface AnnotationDesc.ElementValuePair

Represents an association between an annotation type element and one of its values.

Since:
1.5

Method Summary
AnnotationTypeElementDoc | element() Returns the annotation type element.
AnnotationValue | value() Returns the value associated with the annotation type element.

Method Detail

element

AnnotationTypeElementDoc element()
Returns the annotation type element.

Returns:
the annotation type element.

value

AnnotationValue value()
Returns the value associated with the annotation type element.

Returns:
the value associated with the annotation type element.
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


AnnotationTypeDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface AnnotationTypeDoc

All Superinterfaces:
ClassDoc, Comparable<Object>, Doc, ProgramElementDoc, Type
public interface AnnotationTypeDoc
extends ClassDoc

Represents an annotation type.

Since:
1.5

Method Summary
 AnnotationTypeElementDoc[] elements()
Returns the elements of this annotation type.
Methods inherited from interface com.sun.javadoc.ClassDoc
constructors, constructors, definesSerializableFields, enumConstants, fields, fields, findClass, importedClasses, importedPackages, innerClasses, innerClasses, interfaces, interfaceTypes, isAbstract, isExternalizable, isSerializable, methods, methods, serializableFields, serializationMethods, subclassOf, superclass, superclassType, typeParameters, typeParamTags
Methods inherited from interface com.sun.javadoc.ProgramElementDoc
annotations, containingClass, containingPackage, isFinal, isPackagePrivate, isPrivate, isProtected, isPublic, isStatic, modifiers, modifierSpecifier, qualifiedName
Methods inherited from interface com.sun.javadoc.Doc
commentText, compareTo, firstSentenceTags, getRawCommentText, inlineTags, isAnnotationType, isAnnotationTypeElement, isClass, isConstructor, isEnum, isEnumConstant, isError, isException, isField, isIncluded, isInterface, isMethod, isOrdinaryClass, name, position, seeTags, setRawCommentText, tags, tags
Methods inherited from interface com.sun.javadoc.Type
asAnnotationTypeDoc, asClassDoc, asParameterizedType, asTypeVariable, asWildcardType, dimension, isPrimitive, qualifiedTypeName, simpleTypeName, toString, typeName

Method Detail

elements

AnnotationTypeElementDoc[] elements()
Returns the elements of this annotation type. Returns an empty array if there are none.

Returns:
the elements of this annotation type.
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


AnnotationTypeElementDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface AnnotationTypeElementDoc

All Superinterfaces:
Comparable<Object>, Doc, ExecutableMemberDoc, MemberDoc, MethodDoc, ProgramElementDoc
public interface AnnotationTypeElementDoc
extends MethodDoc

Represents an element of an annotation type.

Since:
1.5

Method Summary
 AnnotationValue defaultValue()
Returns the default value of this element.
Methods inherited from interface com.sun.javadoc.MethodDoc
isAbstract, overriddenClass, overriddenMethod, overriddenType, overrides, returnType
Methods inherited from interface com.sun.javadoc.ExecutableMemberDoc
flatSignature, isNative, isSynchronized, isVarArgs, parameters, paramTags, signature, thrownExceptions, thrownExceptionTypes, throwsTags, typeParameters, typeParamTags
Methods inherited from interface com.sun.javadoc.MemberDoc
isSynthetic
Methods inherited from interface com.sun.javadoc.ProgramElementDoc
annotations, containingClass, containingPackage, isFinal, isPackagePrivate, isPrivate, isProtected, isPublic, isStatic, modifiers, modifierSpecifier, qualifiedName
Methods inherited from interface com.sun.javadoc.Doc
commentText, compareTo, firstSentenceTags, getRawCommentText, inlineTags, isAnnotationType, isAnnotationTypeElement, isClass, isConstructor, isEnum, isEnumConstant, isError, isException, isField, isIncluded, isInterface, isMethod, isOrdinaryClass, name, position, seeTags, setRawCommentText, tags, tags

Method Detail

defaultValue

AnnotationValue defaultValue()
Returns the default value of this element. Returns null if this element has no default.

Returns:
the default value of this element.
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


AnnotationValue

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface AnnotationValue

public interface AnnotationValue

Represents a value of an annotation type element.

Since:
1.5

Method Summary
String | toString() Returns a string representation of the value.
Object | value() Returns the value.

Method Detail

value

Object value()
Returns the value. The type of the returned object is one of the following:
  • a wrapper class for a primitive type
  • String
  • Type (representing a class literal)
  • FieldDoc (representing an enum constant)
  • AnnotationDesc
  • AnnotationValue[]

Returns:
the value.

toString

String toString()
Returns a string representation of the value.

Overrides:
toString in class Object
Returns:
the text of a Java language annotation value expression whose value is the value of this element.
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Class com.sun.javadoc.Doclet

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.javadoc.Doclet

No usage of com.sun.javadoc.Doclet

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Class com.sun.javadoc.LanguageVersion

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.javadoc.LanguageVersion

Uses of LanguageVersion in com.sun.javadoc

Methods in com.sun.javadoc that return LanguageVersion
static LanguageVersion | Doclet.languageVersion() Return the version of the Java Programming Language supported by this doclet.
static LanguageVersion | LanguageVersion.valueOf(String name) Returns the enum constant of this type with the specified name.
static LanguageVersion[] | LanguageVersion.values() Returns an array containing the constants of this enum type, in the order they are declared.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.AnnotationDesc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.AnnotationDesc

Uses of AnnotationDesc in com.sun.javadoc

Methods in com.sun.javadoc that return AnnotationDesc
AnnotationDesc[] | Parameter.annotations() Get the annotations of this parameter.
AnnotationDesc[] | PackageDoc.annotations() Get the annotations of this package.
AnnotationDesc[] | ProgramElementDoc.annotations() Get the annotations of this program element.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.AnnotationDesc.ElementValuePair

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.AnnotationDesc.ElementValuePair

Uses of AnnotationDesc.ElementValuePair in com.sun.javadoc

Methods in com.sun.javadoc that return AnnotationDesc.ElementValuePair
 AnnotationDesc.ElementValuePair[] AnnotationDesc.elementValues()
Returns this annotation's elements and their values.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.AnnotationTypeDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.AnnotationTypeDoc

Uses of AnnotationTypeDoc in com.sun.javadoc

Methods in com.sun.javadoc that return AnnotationTypeDoc
AnnotationTypeDoc | AnnotationDesc.annotationType() Returns the annotation type of this annotation.
AnnotationTypeDoc[] | PackageDoc.annotationTypes() Get included annotation types in this package.
AnnotationTypeDoc | Type.asAnnotationTypeDoc() Return this type as an AnnotationTypeDoc if it represents an annotation type.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.AnnotationTypeElementDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.AnnotationTypeElementDoc

Uses of AnnotationTypeElementDoc in com.sun.javadoc

Methods in com.sun.javadoc that return AnnotationTypeElementDoc
AnnotationTypeElementDoc | AnnotationDesc.ElementValuePair.element() Returns the annotation type element.
AnnotationTypeElementDoc[] | AnnotationTypeDoc.elements() Returns the elements of this annotation type.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.AnnotationValue

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.AnnotationValue

Uses of AnnotationValue in com.sun.javadoc

Methods in com.sun.javadoc that return AnnotationValue
AnnotationValue | AnnotationTypeElementDoc.defaultValue() Returns the default value of this element.
AnnotationValue | AnnotationDesc.ElementValuePair.value() Returns the value associated with the annotation type element.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.ClassDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.ClassDoc

Uses of ClassDoc in com.sun.javadoc

Subinterfaces of ClassDoc in com.sun.javadoc
 interface AnnotationTypeDoc
Represents an annotation type.

Methods in com.sun.javadoc that return ClassDoc
ClassDoc[] | PackageDoc.allClasses() Get all included classes and interfaces in the package.
ClassDoc[] | PackageDoc.allClasses(boolean filter) Get all classes and interfaces in the package, filtered to the specified access modifier option.
ClassDoc | ParameterizedType.asClassDoc() Return the generic class or interface that declared this type.
ClassDoc | Type.asClassDoc() Return this type as a ClassDoc if it represents a class or interface.
ClassDoc[] | RootDoc.classes() Return the included classes and interfaces in all packages.
ClassDoc | RootDoc.classNamed(String qualifiedName) Return a ClassDoc for the specified class or interface name.
ClassDoc | ProgramElementDoc.containingClass() Get the containing class or interface of this program element.
ClassDoc[] | PackageDoc.enums() Get included enum types in this package.
ClassDoc[] | PackageDoc.errors() Get included Error classes in this package.
ClassDoc | ThrowsTag.exception() Return a ClassDoc that represents the exception.
ClassDoc[] | PackageDoc.exceptions() Get included Exception classes in this package.
ClassDoc | SerialFieldTag.fieldTypeDoc() Return the ClassDoc for field type.
ClassDoc | PackageDoc.findClass(String className) Lookup a class or interface within this package.
ClassDoc | ClassDoc.findClass(String className) Find the specified class or interface within the context of this class doc.
ClassDoc[] | ClassDoc.importedClasses() Deprecated. Import declarations are implementation details that should not be exposed here. In addition, not all imported classes are imported through single-type-import declarations.
ClassDoc[] | ClassDoc.innerClasses() Return included nested classes and interfaces within this class or interface.
ClassDoc[] | ClassDoc.innerClasses(boolean filter) Return nested classes and interfaces within this class or interface filtered to the specified access modifier option.
ClassDoc[] | PackageDoc.interfaces() Get included interfaces in this package, omitting annotation types.
ClassDoc[] | ClassDoc.interfaces() Return interfaces implemented by this class or interfaces extended by this interface.
ClassDoc[] | PackageDoc.ordinaryClasses() Get included ordinary classes (that is, exclude exceptions, errors, enums, interfaces, and annotation types) in this package.
ClassDoc | MethodDoc.overriddenClass() Return the class containing the method that this method overrides.
ClassDoc | SeeTag.referencedClass() Get the class doc referenced by the class name part of @see.
ClassDoc[] | RootDoc.specifiedClasses() Return the classes and interfaces specified as source file names on the command line.
ClassDoc | ClassDoc.superclass() Return the superclass of this class.
ClassDoc[] | ExecutableMemberDoc.thrownExceptions() Return exceptions this method or constructor throws.

Methods in com.sun.javadoc with parameters of type ClassDoc
 boolean ClassDoc.subclassOf(ClassDoc cd)
Test whether this class is a subclass of the specified class.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.ConstructorDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.ConstructorDoc

Uses of ConstructorDoc in com.sun.javadoc

Methods in com.sun.javadoc that return ConstructorDoc
ConstructorDoc[] | ClassDoc.constructors() Return included constructors in this class.
ConstructorDoc[] | ClassDoc.constructors(boolean filter) Return constructors in this class, filtered to the specified access modifier option.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.Doc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.Doc

Uses of Doc in com.sun.javadoc

Subinterfaces of Doc in com.sun.javadoc
interface | AnnotationTypeDoc Represents an annotation type.
interface | AnnotationTypeElementDoc Represents an element of an annotation type.
interface | ClassDoc Represents a java class or interface and provides access to information about the class, the class's comment and tags, and the members of the class.
interface | ConstructorDoc Represents a constructor of a java class.
interface | ExecutableMemberDoc Represents a method or constructor of a java class.
interface | FieldDoc Represents a field in a java class.
interface | MemberDoc Represents a member of a java class: field, constructor, or method.
interface | MethodDoc Represents a method of a java class.
interface | PackageDoc Represents a java package.
interface | ProgramElementDoc Represents a java program element: class, interface, field, constructor, or method.
interface | RootDoc Represents the root of the program structure information for one run of javadoc.

Methods in com.sun.javadoc that return Doc
 Doc Tag.holder()
Return the containing Doc of this Tag element.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.DocErrorReporter

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.DocErrorReporter

Uses of DocErrorReporter in com.sun.javadoc

Subinterfaces of DocErrorReporter in com.sun.javadoc
 interface RootDoc
Represents the root of the program structure information for one run of javadoc.

Methods in com.sun.javadoc with parameters of type DocErrorReporter
static boolean Doclet.validOptions(String[][] options, DocErrorReporter reporter)
Check that options have the correct arguments.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.ExecutableMemberDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.ExecutableMemberDoc

Uses of ExecutableMemberDoc in com.sun.javadoc

Subinterfaces of ExecutableMemberDoc in com.sun.javadoc
interface | AnnotationTypeElementDoc Represents an element of an annotation type.
interface | ConstructorDoc Represents a constructor of a java class.
interface | MethodDoc Represents a method of a java class.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.FieldDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.FieldDoc

Uses of FieldDoc in com.sun.javadoc

Methods in com.sun.javadoc that return FieldDoc
FieldDoc[] | ClassDoc.enumConstants() Return the enum constants if this is an enum type.
FieldDoc[] | ClassDoc.fields() Return included fields in this class or interface.
FieldDoc[] | ClassDoc.fields(boolean filter) Return fields in this class or interface, filtered to the specified access modifier option.
FieldDoc[] | ClassDoc.serializableFields() Return the Serializable fields of this class or interface.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.MemberDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.MemberDoc

Uses of MemberDoc in com.sun.javadoc

Subinterfaces of MemberDoc in com.sun.javadoc
interface | AnnotationTypeElementDoc Represents an element of an annotation type.
interface | ConstructorDoc Represents a constructor of a java class.
interface | ExecutableMemberDoc Represents a method or constructor of a java class.
interface | FieldDoc Represents a field in a java class.
interface | MethodDoc Represents a method of a java class.

Methods in com.sun.javadoc that return MemberDoc
 MemberDoc SeeTag.referencedMember()
Get the member doc for the field, constructor or method referenced by @see.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.MethodDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.MethodDoc

Uses of MethodDoc in com.sun.javadoc

Subinterfaces of MethodDoc in com.sun.javadoc
 interface AnnotationTypeElementDoc
Represents an element of an annotation type.

Methods in com.sun.javadoc that return MethodDoc
MethodDoc[] | ClassDoc.methods() Return included methods in this class or interface.
MethodDoc[] | ClassDoc.methods(boolean filter) Return methods in this class or interface, filtered to the specified access modifier option.
MethodDoc | MethodDoc.overriddenMethod() Return the method that this method overrides.
MethodDoc[] | ClassDoc.serializationMethods() Return the serialization methods for this class or interface.

Methods in com.sun.javadoc with parameters of type MethodDoc
 boolean MethodDoc.overrides(MethodDoc meth)
Tests whether this method overrides another.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.PackageDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.PackageDoc

Uses of PackageDoc in com.sun.javadoc

Methods in com.sun.javadoc that return PackageDoc
PackageDoc | ProgramElementDoc.containingPackage() Get the package that this program element is contained in.
PackageDoc[] | ClassDoc.importedPackages() Deprecated. Import declarations are implementation details that should not be exposed here. In addition, this method's return type does not allow for all type-import-on-demand declarations to be returned.
PackageDoc | RootDoc.packageNamed(String name) Return a PackageDoc for the specified package name.
PackageDoc | SeeTag.referencedPackage() Get the package doc when @see references only a package.
PackageDoc[] | RootDoc.specifiedPackages() Return the packages specified on the command line.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.Parameter

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.Parameter

Uses of Parameter in com.sun.javadoc

Methods in com.sun.javadoc that return Parameter
 Parameter[] ExecutableMemberDoc.parameters()
Get argument information.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.ParameterizedType

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.ParameterizedType

Uses of ParameterizedType in com.sun.javadoc

Methods in com.sun.javadoc that return ParameterizedType
 ParameterizedType Type.asParameterizedType()
Return this type as a ParameterizedType if it represents an invocation of a generic class or interface.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.ParamTag

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.ParamTag

Uses of ParamTag in com.sun.javadoc

Methods in com.sun.javadoc that return ParamTag
ParamTag[] | ExecutableMemberDoc.paramTags() Return the param tags in this method, excluding the type parameter tags.
ParamTag[] | ExecutableMemberDoc.typeParamTags() Return the type parameter tags in this method.
ParamTag[] | ClassDoc.typeParamTags() Return the type parameter tags of this class or interface.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.ProgramElementDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.ProgramElementDoc

Uses of ProgramElementDoc in com.sun.javadoc

Subinterfaces of ProgramElementDoc in com.sun.javadoc
interface | AnnotationTypeDoc Represents an annotation type.
interface | AnnotationTypeElementDoc Represents an element of an annotation type.
interface | ClassDoc Represents a java class or interface and provides access to information about the class, the class's comment and tags, and the members of the class.
interface | ConstructorDoc Represents a constructor of a java class.
interface | ExecutableMemberDoc Represents a method or constructor of a java class.
interface | FieldDoc Represents a field in a java class.
interface | MemberDoc Represents a member of a java class: field, constructor, or method.
interface | MethodDoc Represents a method of a java class.

Methods in com.sun.javadoc that return ProgramElementDoc
 ProgramElementDoc TypeVariable.owner()
Return the class, interface, method, or constructor within which this type variable is declared.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.RootDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.RootDoc

Uses of RootDoc in com.sun.javadoc

Methods in com.sun.javadoc with parameters of type RootDoc
static boolean Doclet.start(RootDoc root)
Generate documentation here.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.SeeTag

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.SeeTag

Uses of SeeTag in com.sun.javadoc

Methods in com.sun.javadoc that return SeeTag
 SeeTag[] Doc.seeTags()
Return the see also tags in this Doc item.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.SerialFieldTag

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.SerialFieldTag

Uses of SerialFieldTag in com.sun.javadoc

Methods in com.sun.javadoc that return SerialFieldTag
 SerialFieldTag[] FieldDoc.serialFieldTags()
Return the serialField tags in this FieldDoc item.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.SourcePosition

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.SourcePosition

Uses of SourcePosition in com.sun.javadoc

Methods in com.sun.javadoc that return SourcePosition
SourcePosition | Tag.position() Return the source position of this tag.
SourcePosition | Doc.position() Return the source position of the first line of the corresponding declaration, or null if no position is available.

Methods in com.sun.javadoc with parameters of type SourcePosition
void | DocErrorReporter.printError(SourcePosition pos, String msg) Print an error message and increment error count.
void | DocErrorReporter.printNotice(SourcePosition pos, String msg) Print a message.
void | DocErrorReporter.printWarning(SourcePosition pos, String msg) Print warning message and increment warning count.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.Tag

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.Tag

Uses of Tag in com.sun.javadoc

Subinterfaces of Tag in com.sun.javadoc
interface | ParamTag Represents an @param documentation tag.
interface | SeeTag Represents a user-defined cross-reference to related documentation.
interface | SerialFieldTag Documents a Serializable field defined by an ObjectStreamField.
interface | ThrowsTag Represents a @throws or @exception documentation tag.

Methods in com.sun.javadoc that return Tag
Tag[] | Tag.firstSentenceTags() Return the first sentence of the comment as an array of tags.
Tag[] | Doc.firstSentenceTags() Return the first sentence of the comment as an array of tags.
Tag[] | Tag.inlineTags() For a documentation comment with embedded {@link} tags, return an array of Tag objects.
Tag[] | Doc.inlineTags() Return comment as an array of tags.
Tag[] | Doc.tags() Return all tags in this Doc item.
Tag[] | Doc.tags(String tagname) Return tags of the specified kind in this Doc item.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.ThrowsTag

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.ThrowsTag

Uses of ThrowsTag in com.sun.javadoc

Methods in com.sun.javadoc that return ThrowsTag
 ThrowsTag[] ExecutableMemberDoc.throwsTags()
Return the throws tags in this method.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.Type

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.Type

Uses of Type in com.sun.javadoc

Subinterfaces of Type in com.sun.javadoc
interface | AnnotationTypeDoc Represents an annotation type.
interface | ClassDoc Represents a java class or interface and provides access to information about the class, the class's comment and tags, and the members of the class.
interface | ParameterizedType Represents an invocation of a generic class or interface.
interface | TypeVariable Represents a type variable.
interface | WildcardType Represents a wildcard type argument.

Methods in com.sun.javadoc that return Type
Type[] | TypeVariable.bounds() Return the bounds of this type variable.
Type | ParameterizedType.containingType() Return the type that contains this type as a member.
Type | ThrowsTag.exceptionType() Return the type of the exception associated with this ThrowsTag.
Type[] | WildcardType.extendsBounds() Return the upper bounds of this wildcard type argument as given by the extends clause.
Type[] | ParameterizedType.interfaceTypes() Return the interface types directly implemented by or extended by this parameterized type.
Type[] | ClassDoc.interfaceTypes() Return interfaces implemented by this class or interfaces extended by this interface.
Type | MethodDoc.overriddenType() Return the type containing the method that this method overrides.
Type | MethodDoc.returnType() Get return type.
Type[] | WildcardType.superBounds() Return the lower bounds of this wildcard type argument as given by the super clause.
Type | ParameterizedType.superclassType() Return the class type that is a direct supertype of this one.
Type | ClassDoc.superclassType() Return the superclass of this class.
Type[] | ExecutableMemberDoc.thrownExceptionTypes() Return exceptions this method or constructor throws.
Type | Parameter.type() Get the type of this parameter.
Type | FieldDoc.type() Get type of this field.
Type[] | ParameterizedType.typeArguments() Return the actual type arguments of this type.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.TypeVariable

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.TypeVariable

Uses of TypeVariable in com.sun.javadoc

Methods in com.sun.javadoc that return TypeVariable
TypeVariable | Type.asTypeVariable() Return this type as a TypeVariable if it represents a type variable.
TypeVariable[] | ExecutableMemberDoc.typeParameters() Return the formal type parameters of this method or constructor.
TypeVariable[] | ClassDoc.typeParameters() Return the formal type parameters of this class or interface.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.javadoc.WildcardType

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.javadoc.WildcardType

Uses of WildcardType in com.sun.javadoc

Methods in com.sun.javadoc that return WildcardType
 WildcardType Type.asWildcardType()
Return this type as a WildcardType if it represents a wildcard type.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV NEXT FRAMES NO FRAMES
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


ClassDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface ClassDoc

All Superinterfaces:
Comparable<Object>, Doc, ProgramElementDoc, Type
All Known Subinterfaces:
AnnotationTypeDoc
public interface ClassDoc
extends ProgramElementDoc, Type

Represents a java class or interface and provides access to information about the class, the class's comment and tags, and the members of the class. A ClassDoc only exists if it was processed in this run of javadoc. References to classes which may or may not have been processed in this run are referred to using Type (which can be converted to ClassDoc, if possible).

Since:
1.2
See Also:
Type

Method Summary
ConstructorDoc[] | constructors() Return included constructors in this class.
ConstructorDoc[] | constructors(boolean filter) Return constructors in this class, filtered to the specified access modifier option.
boolean | definesSerializableFields() Return true if Serializable fields are explicitly defined with the special class member serialPersistentFields.
FieldDoc[] | enumConstants() Return the enum constants if this is an enum type.
FieldDoc[] | fields() Return included fields in this class or interface.
FieldDoc[] | fields(boolean filter) Return fields in this class or interface, filtered to the specified access modifier option.
ClassDoc | findClass(String className) Find the specified class or interface within the context of this class doc.
ClassDoc[] | importedClasses() Deprecated. Import declarations are implementation details that should not be exposed here. In addition, not all imported classes are imported through single-type-import declarations.
PackageDoc[] | importedPackages() Deprecated. Import declarations are implementation details that should not be exposed here. In addition, this method's return type does not allow for all type-import-on-demand declarations to be returned.
ClassDoc[] | innerClasses() Return included nested classes and interfaces within this class or interface.
ClassDoc[] | innerClasses(boolean filter) Return nested classes and interfaces within this class or interface filtered to the specified access modifier option.
ClassDoc[] | interfaces() Return interfaces implemented by this class or interfaces extended by this interface.
Type[] | interfaceTypes() Return interfaces implemented by this class or interfaces extended by this interface.
boolean | isAbstract() Return true if this class is abstract.
boolean | isExternalizable() Return true if this class implements or interface extends java.io.Externalizable.
boolean | isSerializable() Return true if this class implements or interface extends java.io.Serializable.
MethodDoc[] | methods() Return included methods in this class or interface.
MethodDoc[] | methods(boolean filter) Return methods in this class or interface, filtered to the specified access modifier option.
FieldDoc[] | serializableFields() Return the Serializable fields of this class or interface.
MethodDoc[] | serializationMethods() Return the serialization methods for this class or interface.
boolean | subclassOf(ClassDoc cd) Test whether this class is a subclass of the specified class.
ClassDoc | superclass() Return the superclass of this class.
Type | superclassType() Return the superclass of this class.
TypeVariable[] | typeParameters() Return the formal type parameters of this class or interface.
ParamTag[] | typeParamTags() Return the type parameter tags of this class or interface.
Methods inherited from interface com.sun.javadoc.ProgramElementDoc
annotations, containingClass, containingPackage, isFinal, isPackagePrivate, isPrivate, isProtected, isPublic, isStatic, modifiers, modifierSpecifier, qualifiedName
Methods inherited from interface com.sun.javadoc.Doc
commentText, compareTo, firstSentenceTags, getRawCommentText, inlineTags, isAnnotationType, isAnnotationTypeElement, isClass, isConstructor, isEnum, isEnumConstant, isError, isException, isField, isIncluded, isInterface, isMethod, isOrdinaryClass, name, position, seeTags, setRawCommentText, tags, tags
Methods inherited from interface com.sun.javadoc.Type
asAnnotationTypeDoc, asClassDoc, asParameterizedType, asTypeVariable, asWildcardType, dimension, isPrimitive, qualifiedTypeName, simpleTypeName, toString, typeName

Method Detail

isAbstract

boolean isAbstract()
Return true if this class is abstract. Return true for all interfaces.

isSerializable

boolean isSerializable()
Return true if this class implements or interface extends java.io.Serializable. Since java.io.Externalizable extends java.io.Serializable, Externalizable objects are also Serializable.

isExternalizable

boolean isExternalizable()
Return true if this class implements or interface extends java.io.Externalizable.

serializationMethods

MethodDoc[] serializationMethods()
Return the serialization methods for this class or interface.

Returns:
an array of MethodDoc objects that represents the serialization methods for this class or interface.

serializableFields

FieldDoc[] serializableFields()
Return the Serializable fields of this class or interface.

Return either a list of default fields documented by serial tag
or return a single FieldDoc for serialPersistentField member. There should be a serialField tag for each Serializable field defined by an ObjectStreamField array component of serialPersistentField.

Returns:
an array of FieldDoc objects for the Serializable fields of this class or interface.
See Also:
definesSerializableFields(), SerialFieldTag

definesSerializableFields

boolean definesSerializableFields()
Return true if Serializable fields are explicitly defined with the special class member serialPersistentFields.

See Also:
serializableFields(), SerialFieldTag

superclass

ClassDoc superclass()
Return the superclass of this class. Return null if this is an interface.

This method cannot accommodate certain generic type constructs. The superclassType method should be used instead.

Returns:
the ClassDoc for the superclass of this class, null if there is no superclass.
See Also:
superclassType()

superclassType

Type superclassType()
Return the superclass of this class. Return null if this is an interface. A superclass is represented by either a ClassDoc or a ParametrizedType.

Returns:
the superclass of this class, or null if there is no superclass.
Since:
1.5

subclassOf

boolean subclassOf(ClassDoc cd)
Test whether this class is a subclass of the specified class. If this is an interface, return false for all classes except java.lang.Object (we must keep this unexpected behavior for compatibility reasons).

Parameters:
cd - the candidate superclass.
Returns:
true if cd is a superclass of this class.

interfaces

ClassDoc[] interfaces()
Return interfaces implemented by this class or interfaces extended by this interface. Includes only directly-declared interfaces, not inherited interfaces. Return an empty array if there are no interfaces.

This method cannot accommodate certain generic type constructs. The interfaceTypes method should be used instead.

Returns:
an array of ClassDoc objects representing the interfaces.
See Also:
interfaceTypes()

interfaceTypes

Type[] interfaceTypes()
Return interfaces implemented by this class or interfaces extended by this interface. Includes only directly-declared interfaces, not inherited interfaces. Return an empty array if there are no interfaces.

Returns:
an array of interfaces, each represented by a ClassDoc or a ParametrizedType.
Since:
1.5

typeParameters

TypeVariable[] typeParameters()
Return the formal type parameters of this class or interface. Return an empty array if there are none.

Returns:
the formal type parameters of this class or interface.
Since:
1.5

typeParamTags

ParamTag[] typeParamTags()
Return the type parameter tags of this class or interface. Return an empty array if there are none.

Returns:
the type parameter tags of this class or interface.
Since:
1.5

fields

FieldDoc[] fields()
Return included fields in this class or interface. Excludes enum constants if this is an enum type.

Returns:
an array of FieldDoc objects representing the included fields in this class or interface.

fields

FieldDoc[] fields(boolean filter)
Return fields in this class or interface, filtered to the specified access modifier option. Excludes enum constants if this is an enum type.

Parameters:
filter - Specify true to filter according to the specified access modifier option. Specify false to include all fields regardless of access modifier option.
Returns:
an array of FieldDoc objects representing the included fields in this class or interface.

enumConstants

FieldDoc[] enumConstants()
Return the enum constants if this is an enum type. Return an empty array if there are no enum constants, or if this is not an enum type.

Returns:
the enum constants if this is an enum type.

methods

MethodDoc[] methods()
Return included methods in this class or interface. Same as methods(true).

Returns:
an array of MethodDoc objects representing the included methods in this class or interface. Does not include constructors or annotation type elements.

methods

MethodDoc[] methods(boolean filter)
Return methods in this class or interface, filtered to the specified access modifier option. Does not include constructors or annotation type elements.

Parameters:
filter - Specify true to filter according to the specified access modifier option. Specify false to include all methods regardless of access modifier option.
Returns:
an array of MethodDoc objects representing the included methods in this class or interface.

constructors

ConstructorDoc[] constructors()
Return included constructors in this class. An array containing the default no-arg constructor is returned if no other constructors exist. Return empty array if this is an interface.

Returns:
an array of ConstructorDoc objects representing the included constructors in this class.

constructors

ConstructorDoc[] constructors(boolean filter)
Return constructors in this class, filtered to the specified access modifier option. Return an array containing the default no-arg constructor if no other constructors exist.

Parameters:
filter - Specify true to filter according to the specified access modifier option. Specify false to include all constructors regardless of access modifier option.
Returns:
an array of ConstructorDoc objects representing the included constructors in this class.

innerClasses

ClassDoc[] innerClasses()
Return included nested classes and interfaces within this class or interface. This includes both static and non-static nested classes. (This method should have been named nestedClasses(), as inner classes are technically non-static.) Anonymous and local classes or interfaces are not included.

Returns:
an array of ClassDoc objects representing the included classes and interfaces defined in this class or interface.

innerClasses

ClassDoc[] innerClasses(boolean filter)
Return nested classes and interfaces within this class or interface filtered to the specified access modifier option. This includes both static and non-static nested classes. Anonymous and local classes are not included.

Parameters:
filter - Specify true to filter according to the specified access modifier option. Specify false to include all nested classes regardless of access modifier option.
Returns:
a filtered array of ClassDoc objects representing the included classes and interfaces defined in this class or interface.

findClass

ClassDoc findClass(String className)
Find the specified class or interface within the context of this class doc. Search order: 1) qualified name, 2) nested in this class or interface, 3) in this package, 4) in the class imports, 5) in the package imports. Return the ClassDoc if found, null if not found.

importedClasses

@Deprecated
ClassDoc[] importedClasses()
Deprecated. Import declarations are implementation details that should not be exposed here. In addition, not all imported classes are imported through single-type-import declarations.

Get the list of classes and interfaces declared as imported. These are called "single-type-import declarations" in the Java Language Specification.

Returns:
an array of ClassDoc representing the imported classes.

importedPackages

@Deprecated
PackageDoc[] importedPackages()
Deprecated. Import declarations are implementation details that should not be exposed here. In addition, this method's return type does not allow for all type-import-on-demand declarations to be returned.

Get the list of packages declared as imported. These are called "type-import-on-demand declarations" in the Java Language Specification.

Returns:
an array of PackageDoc representing the imported packages.
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Doc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface Doc

All Superinterfaces:
Comparable<Object>
All Known Subinterfaces:
AnnotationTypeDoc, AnnotationTypeElementDoc, ClassDoc, ConstructorDoc, ExecutableMemberDoc, FieldDoc, MemberDoc, MethodDoc, PackageDoc, ProgramElementDoc, RootDoc
public interface Doc
extends Comparable<Object>

Represents Java language constructs (package, class, constructor, method, field) which have comments and have been processed by this run of javadoc. All Doc objects are unique, that is, they are == comparable.

Since:
1.2

Method Summary
String | commentText() Return the text of the comment for this doc item.
int | compareTo(Object obj) Compares this doc object with the specified object for order.
Tag[] | firstSentenceTags() Return the first sentence of the comment as an array of tags.
String | getRawCommentText() Return the full unprocessed text of the comment.
Tag[] | inlineTags() Return comment as an array of tags.
boolean | isAnnotationType() Is this Doc item an annotation type?
boolean | isAnnotationTypeElement() Is this Doc item an annotation type element?
boolean | isClass() Is this Doc item a class (and not an interface or annotation type)?
boolean | isConstructor() Is this Doc item a constructor?
boolean | isEnum() Is this Doc item an enum type?
boolean | isEnumConstant() Is this Doc item an enum constant?
boolean | isError() Is this Doc item an error class?
boolean | isException() Is this Doc item an exception class?
boolean | isField() Is this Doc item a field (but not an enum constant)?
boolean | isIncluded() Return true if this Doc item is included in the result set.
boolean | isInterface() Is this Doc item an interface (but not an annotation type)?
boolean | isMethod() Is this Doc item a method (but not a constructor or annotation type element)?
boolean | isOrdinaryClass() Is this Doc item an ordinary class?
String | name() Returns the non-qualified name of this Doc item.
SourcePosition | position() Return the source position of the first line of the corresponding declaration, or null if no position is available.
SeeTag[] | seeTags() Return the see also tags in this Doc item.
void | setRawCommentText(String rawDocumentation) Set the full unprocessed text of the comment.
Tag[] | tags() Return all tags in this Doc item.
Tag[] | tags(String tagname) Return tags of the specified kind in this Doc item.

Method Detail

commentText

String commentText()
Return the text of the comment for this doc item. Tags have been removed.

tags

Tag[] tags()
Return all tags in this Doc item.

Returns:
an array of Tag objects containing all tags on this Doc item.

tags

Tag[] tags(String tagname)
Return tags of the specified kind in this Doc item. For example, if 'tagname' has value "@serial", all tags in this Doc item of kind "@serial" will be returned.

Parameters:
tagname - name of the tag kind to search for.
Returns:
an array of Tag containing all tags whose 'kind()' matches 'tagname'.

seeTags

SeeTag[] seeTags()
Return the see also tags in this Doc item.

Returns:
an array of SeeTag containing all @see tags.

inlineTags

Tag[] inlineTags()
Return comment as an array of tags. Includes inline tags (i.e. {@link reference} tags) but not block tags. Each section of plain text is represented as a Tag of kind "Text". Inline tags are represented as a SeeTag of kind "@see" and name "@link".

Returns:
an array of Tags representing the comment

firstSentenceTags

Tag[] firstSentenceTags()
Return the first sentence of the comment as an array of tags. Includes inline tags (i.e. {@link reference} tags) but not block tags. Each section of plain text is represented as a Tag of kind "Text". Inline tags are represented as a SeeTag of kind "@see" and name "@link".

If the locale is English language, the first sentence is determined by the rules described in the Java Language Specification (first version): "This sentence ends at the first period that is followed by a blank, tab, or line terminator or at the first tagline.", in addition a line will be terminated by block HTML tags: <p> </p> <h1> <h2> <h3> <h4> <h5> <h6> <hr> <pre> or </pre>. If the locale is not English, the sentence end will be determined by BreakIterator.getSentenceInstance(Locale).

Returns:
an array of Tags representing the first sentence of the comment

getRawCommentText

String getRawCommentText()
Return the full unprocessed text of the comment. Tags are included as text. Used mainly for store and retrieve operations like internalization.

setRawCommentText

void setRawCommentText(String rawDocumentation)
Set the full unprocessed text of the comment. Tags are included as text. Used mainly for store and retrieve operations like internalization.

name

String name()
Returns the non-qualified name of this Doc item.

Returns:
the name

compareTo

int compareTo(Object obj)
Compares this doc object with the specified object for order. Returns a negative integer, zero, or a positive integer as this doc object is less than, equal to, or greater than the given object.

This method satisfies the Comparable interface.

Specified by:
compareTo in interface Comparable<Object>
Parameters:
obj - the Object to be compared.
Returns:
a negative integer, zero, or a positive integer as this Object is less than, equal to, or greater than the given Object.
Throws:
ClassCastException - the specified Object's type prevents it from being compared to this Object.

isField

boolean isField()
Is this Doc item a field (but not an enum constant)?

Returns:
true if it represents a field

isEnumConstant

boolean isEnumConstant()
Is this Doc item an enum constant?

Returns:
true if it represents an enum constant
Since:
1.5

isConstructor

boolean isConstructor()
Is this Doc item a constructor?

Returns:
true if it represents a constructor

isMethod

boolean isMethod()
Is this Doc item a method (but not a constructor or annotation type element)?

Returns:
true if it represents a method

isAnnotationTypeElement

boolean isAnnotationTypeElement()
Is this Doc item an annotation type element?

Returns:
true if it represents an annotation type element
Since:
1.5

isInterface

boolean isInterface()
Is this Doc item an interface (but not an annotation type)?

Returns:
true if it represents an interface

isException

boolean isException()
Is this Doc item an exception class?

Returns:
true if it represents an exception

isError

boolean isError()
Is this Doc item an error class?

Returns:
true if it represents a error

isEnum

boolean isEnum()
Is this Doc item an enum type?

Returns:
true if it represents an enum type
Since:
1.5

isAnnotationType

boolean isAnnotationType()
Is this Doc item an annotation type?

Returns:
true if it represents an annotation type
Since:
1.5

isOrdinaryClass

boolean isOrdinaryClass()
Is this Doc item an ordinary class? (i.e. not an interface, annotation type, enum, exception, or error)?

Returns:
true if it represents an ordinary class

isClass

boolean isClass()
Is this Doc item a class (and not an interface or annotation type)? This includes ordinary classes, enums, errors and exceptions.

Returns:
true if it represents a class

isIncluded

boolean isIncluded()
Return true if this Doc item is included in the result set.

position

SourcePosition position()
Return the source position of the first line of the corresponding declaration, or null if no position is available. A default constructor returns null because it has no location in the source file.

Since:
1.4
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


DocErrorReporter

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface DocErrorReporter

All Known Subinterfaces:
RootDoc
public interface DocErrorReporter

This interface provides error, warning and notice printing.

Since:
1.2

Method Summary
void | printError(SourcePosition pos, String msg) Print an error message and increment error count.
void | printError(String msg) Print error message and increment error count.
void | printNotice(SourcePosition pos, String msg) Print a message.
void | printNotice(String msg) Print a message.
void | printWarning(SourcePosition pos, String msg) Print warning message and increment warning count.
void | printWarning(String msg) Print warning message and increment warning count.

Method Detail

printError

void printError(String msg)
Print error message and increment error count.

Parameters:
msg - message to print

printError

void printError(SourcePosition pos,
                String msg)
Print an error message and increment error count.

Parameters:
pos - the position item where the error occurs
msg - message to print
Since:
1.4

printWarning

void printWarning(String msg)
Print warning message and increment warning count.

Parameters:
msg - message to print

printWarning

void printWarning(SourcePosition pos,
                  String msg)
Print warning message and increment warning count.

Parameters:
pos - the position item where the warning occurs
msg - message to print
Since:
1.4

printNotice

void printNotice(String msg)
Print a message.

Parameters:
msg - message to print

printNotice

void printNotice(SourcePosition pos,
                 String msg)
Print a message.

Parameters:
pos - the position item where the message occurs
msg - message to print
Since:
1.4
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Doclet

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Class Doclet

java.lang.Object
    extended by  com.sun.javadoc.Doclet

public abstract class Doclet
extends Object

This is an example of a starting class for a doclet, showing the entry-point methods. A starting class must import com.sun.javadoc.* and implement the start(RootDoc) method, as described in the package description. If the doclet takes command line options, it must also implement optionLength and validOptions.

A doclet supporting the language features added since 1.1 (such as generics and annotations) should indicate this by implementing languageVersion. In the absence of this the doclet should not invoke any of the Doclet API methods added since 1.5, and the results of several other methods are modified so as to conceal the new constructs (such as type parameters) from the doclet.

To start the doclet, pass -doclet followed by the fully-qualified name of the starting class on the javadoc tool command line.

Constructor Summary
Doclet()
Method Summary
static LanguageVersion | languageVersion() Return the version of the Java Programming Language supported by this doclet.
static int | optionLength(String option) Check for doclet-added options.
static boolean | start(RootDoc root) Generate documentation here.
static boolean | validOptions(String[][] options, DocErrorReporter reporter) Check that options have the correct arguments.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Doclet

public Doclet()
Method Detail

start

public static boolean start(RootDoc root)
Generate documentation here. This method is required for all doclets.

Returns:
true on success.

optionLength

public static int optionLength(String option)
Check for doclet-added options. Returns the number of arguments you must specify on the command line for the given option. For example, "-d docs" would return 2.

This method is required if the doclet contains any options. If this method is missing, Javadoc will print an invalid flag error for every option.

Returns:
number of arguments on the command line for an option including the option name itself. Zero return means option not known. Negative value means error occurred.

validOptions

public static boolean validOptions(String[][] options,
                                   DocErrorReporter reporter)
Check that options have the correct arguments.

This method is not required, but is recommended, as every option will be considered valid if this method is not present. It will default gracefully (to true) if absent.

Printing option related error messages (using the provided DocErrorReporter) is the responsibility of this method.

Returns:
true if the options are valid.

languageVersion

public static LanguageVersion languageVersion()
Return the version of the Java Programming Language supported by this doclet.

This method is required by any doclet supporting a language version newer than 1.1.

Returns:
the language version supported by this doclet.
Since:
1.5
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


ExecutableMemberDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface ExecutableMemberDoc

All Superinterfaces:
Comparable<Object>, Doc, MemberDoc, ProgramElementDoc
All Known Subinterfaces:
AnnotationTypeElementDoc, ConstructorDoc, MethodDoc
public interface ExecutableMemberDoc
extends MemberDoc

Represents a method or constructor of a java class.

Since:
1.2

Method Summary
String | flatSignature() get flat signature.
boolean | isNative() Return true if this method is native
boolean | isSynchronized() Return true if this method is synchronized
boolean | isVarArgs() Return true if this method was declared to take a variable number of arguments.
Parameter[] | parameters() Get argument information.
ParamTag[] | paramTags() Return the param tags in this method, excluding the type parameter tags.
String | signature() Get the signature.
ClassDoc[] | thrownExceptions() Return exceptions this method or constructor throws.
Type[] | thrownExceptionTypes() Return exceptions this method or constructor throws.
ThrowsTag[] | throwsTags() Return the throws tags in this method.
TypeVariable[] | typeParameters() Return the formal type parameters of this method or constructor.
ParamTag[] | typeParamTags() Return the type parameter tags in this method.
Methods inherited from interface com.sun.javadoc.MemberDoc
isSynthetic
Methods inherited from interface com.sun.javadoc.ProgramElementDoc
annotations, containingClass, containingPackage, isFinal, isPackagePrivate, isPrivate, isProtected, isPublic, isStatic, modifiers, modifierSpecifier, qualifiedName
Methods inherited from interface com.sun.javadoc.Doc
commentText, compareTo, firstSentenceTags, getRawCommentText, inlineTags, isAnnotationType, isAnnotationTypeElement, isClass, isConstructor, isEnum, isEnumConstant, isError, isException, isField, isIncluded, isInterface, isMethod, isOrdinaryClass, name, position, seeTags, setRawCommentText, tags, tags

Method Detail

thrownExceptions

ClassDoc[] thrownExceptions()
Return exceptions this method or constructor throws. If the type of the exception is a type variable, return the ClassDoc of its erasure.

The thrownExceptions method cannot accommodate certain generic type constructs. The thrownExceptionTypes method should be used instead.

Returns:
an array of ClassDoc[] representing the exceptions thrown by this method.
See Also:
thrownExceptionTypes()

thrownExceptionTypes

Type[] thrownExceptionTypes()
Return exceptions this method or constructor throws.

Returns:
an array representing the exceptions thrown by this method. Each array element is either a ClassDoc or a TypeVariable.
Since:
1.5

isNative

boolean isNative()
Return true if this method is native

isSynchronized

boolean isSynchronized()
Return true if this method is synchronized

isVarArgs

boolean isVarArgs()
Return true if this method was declared to take a variable number of arguments.

Since:
1.5

parameters

Parameter[] parameters()
Get argument information.

Returns:
an array of Parameter, one element per argument in the order the arguments are present.
See Also:
Parameter

throwsTags

ThrowsTag[] throwsTags()
Return the throws tags in this method.

Returns:
an array of ThrowTag containing all @exception and @throws tags.

paramTags

ParamTag[] paramTags()
Return the param tags in this method, excluding the type parameter tags.

Returns:
an array of ParamTag containing all @param tags corresponding to the parameters of this method.

typeParamTags

ParamTag[] typeParamTags()
Return the type parameter tags in this method.

Returns:
an array of ParamTag containing all @param tags corresponding to the type parameters of this method.
Since:
1.5

signature

String signature()
Get the signature. It is the parameter list, type is qualified. For instance, for a method mymethod(String x, int y), it will return (java.lang.String,int).

flatSignature

String flatSignature()
get flat signature. all types are not qualified. return a String, which is the flat signiture of this member. It is the parameter list, type is not qualified. For instance, for a method mymethod(String x, int y), it will return (String, int).

typeParameters

TypeVariable[] typeParameters()
Return the formal type parameters of this method or constructor. Return an empty array if this method or constructor is not generic.

Returns:
the formal type parameters of this method or constructor.
Since:
1.5
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


FieldDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface FieldDoc

All Superinterfaces:
Comparable<Object>, Doc, MemberDoc, ProgramElementDoc
public interface FieldDoc
extends MemberDoc

Represents a field in a java class.

Since:
1.2
See Also:
MemberDoc

Method Summary
Object | constantValue() Get the value of a constant field.
String | constantValueExpression() Get the value of a constant field.
boolean | isTransient() Return true if this field is transient
boolean | isVolatile() Return true if this field is volatile
SerialFieldTag[] | serialFieldTags() Return the serialField tags in this FieldDoc item.
Type | type() Get type of this field.
Methods inherited from interface com.sun.javadoc.MemberDoc
isSynthetic
Methods inherited from interface com.sun.javadoc.ProgramElementDoc
annotations, containingClass, containingPackage, isFinal, isPackagePrivate, isPrivate, isProtected, isPublic, isStatic, modifiers, modifierSpecifier, qualifiedName
Methods inherited from interface com.sun.javadoc.Doc
commentText, compareTo, firstSentenceTags, getRawCommentText, inlineTags, isAnnotationType, isAnnotationTypeElement, isClass, isConstructor, isEnum, isEnumConstant, isError, isException, isField, isIncluded, isInterface, isMethod, isOrdinaryClass, name, position, seeTags, setRawCommentText, tags, tags

Method Detail

type

Type type()
Get type of this field.

isTransient

boolean isTransient()
Return true if this field is transient

isVolatile

boolean isVolatile()
Return true if this field is volatile

serialFieldTags

SerialFieldTag[] serialFieldTags()
Return the serialField tags in this FieldDoc item.

Returns:
an array of SerialFieldTag objects containing all @serialField tags.

constantValue

Object constantValue()
Get the value of a constant field.

Returns:
the value of a constant field. The value is automatically wrapped in an object if it has a primitive type. If the field is not constant, returns null.

constantValueExpression

String constantValueExpression()
Get the value of a constant field.

Returns:
the text of a Java language expression whose value is the value of the constant. The expression uses no identifiers other than primitive literals. If the field is not constant, returns null.
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


LanguageVersion

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

com.sun.javadoc
Enum LanguageVersion

java.lang.Object
    extended by  java.lang.Enum<LanguageVersion>
        extended by  com.sun.javadoc.LanguageVersion
All Implemented Interfaces:
Serializable, Comparable<LanguageVersion>
public enum LanguageVersion
extends Enum<LanguageVersion>

Java Programming Language version. The constants of this enum identify the JDK and J2SE releases containing language changes relevant to doclets.

All doclets support at least the 1.1 language version. The first release subsequent to this with language changes affecting doclets is 1.5.

Since:
1.5

Enum Constant Summary
JAVA_1_1
1.1 added nested classes and interfaces.
JAVA_1_5
1.5 added generic types, annotations, enums, and varArgs.
Method Summary
static LanguageVersion | valueOf(String name) Returns the enum constant of this type with the specified name.
static LanguageVersion[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

JAVA_1_1

public static final LanguageVersion JAVA_1_1
1.1 added nested classes and interfaces.

JAVA_1_5

public static final LanguageVersion JAVA_1_5
1.5 added generic types, annotations, enums, and varArgs.

Method Detail

values

public static LanguageVersion[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (LanguageVersion c : LanguageVersion.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static LanguageVersion valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


MemberDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface MemberDoc

All Superinterfaces:
Comparable<Object>, Doc, ProgramElementDoc
All Known Subinterfaces:
AnnotationTypeElementDoc, ConstructorDoc, ExecutableMemberDoc, FieldDoc, MethodDoc
public interface MemberDoc
extends ProgramElementDoc

Represents a member of a java class: field, constructor, or method. This is an abstract class dealing with information common to method, constructor and field members. Class members of a class (innerclasses) are represented instead by ClassDoc.

See Also:
MethodDoc, FieldDoc, ClassDoc

Method Summary
 boolean isSynthetic()
Returns true if this member was synthesized by the compiler.
Methods inherited from interface com.sun.javadoc.ProgramElementDoc
annotations, containingClass, containingPackage, isFinal, isPackagePrivate, isPrivate, isProtected, isPublic, isStatic, modifiers, modifierSpecifier, qualifiedName
Methods inherited from interface com.sun.javadoc.Doc
commentText, compareTo, firstSentenceTags, getRawCommentText, inlineTags, isAnnotationType, isAnnotationTypeElement, isClass, isConstructor, isEnum, isEnumConstant, isError, isException, isField, isIncluded, isInterface, isMethod, isOrdinaryClass, name, position, seeTags, setRawCommentText, tags, tags

Method Detail

isSynthetic

boolean isSynthetic()
Returns true if this member was synthesized by the compiler.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


MethodDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface MethodDoc

All Superinterfaces:
Comparable<Object>, Doc, ExecutableMemberDoc, MemberDoc, ProgramElementDoc
All Known Subinterfaces:
AnnotationTypeElementDoc
public interface MethodDoc
extends ExecutableMemberDoc

Represents a method of a java class.

Since:
1.2

Method Summary
boolean | isAbstract() Return true if this method is abstract
ClassDoc | overriddenClass() Return the class containing the method that this method overrides.
MethodDoc | overriddenMethod() Return the method that this method overrides.
Type | overriddenType() Return the type containing the method that this method overrides.
boolean | overrides(MethodDoc meth) Tests whether this method overrides another.
Type | returnType() Get return type.
Methods inherited from interface com.sun.javadoc.ExecutableMemberDoc
flatSignature, isNative, isSynchronized, isVarArgs, parameters, paramTags, signature, thrownExceptions, thrownExceptionTypes, throwsTags, typeParameters, typeParamTags
Methods inherited from interface com.sun.javadoc.MemberDoc
isSynthetic
Methods inherited from interface com.sun.javadoc.ProgramElementDoc
annotations, containingClass, containingPackage, isFinal, isPackagePrivate, isPrivate, isProtected, isPublic, isStatic, modifiers, modifierSpecifier, qualifiedName
Methods inherited from interface com.sun.javadoc.Doc
commentText, compareTo, firstSentenceTags, getRawCommentText, inlineTags, isAnnotationType, isAnnotationTypeElement, isClass, isConstructor, isEnum, isEnumConstant, isError, isException, isField, isIncluded, isInterface, isMethod, isOrdinaryClass, name, position, seeTags, setRawCommentText, tags, tags

Method Detail

isAbstract

boolean isAbstract()
Return true if this method is abstract

returnType

Type returnType()
Get return type.

Returns:
the return type of this method, null if it is a constructor.

overriddenClass

ClassDoc overriddenClass()
Return the class containing the method that this method overrides.

The overriddenClass method cannot accommodate certain generic type constructs. The overriddenType method should be used instead.

Returns:
a ClassDoc representing the superclass defining a method that this method overrides, or null if this method does not override.

overriddenType

Type overriddenType()
Return the type containing the method that this method overrides. It may be a ClassDoc or a ParameterizedType.

Returns:
the supertype whose method is overridden, or null if this method does not override another in a superclass
Since:
1.5

overriddenMethod

MethodDoc overriddenMethod()
Return the method that this method overrides.

Returns:
a MethodDoc representing a method definition in a superclass this method overrides, null if this method does not override.

overrides

boolean overrides(MethodDoc meth)
Tests whether this method overrides another. The overridden method may be one declared in a superclass or a superinterface (unlike overriddenMethod()).

When a non-abstract method overrides an abstract one, it is also said to implement the other.

Parameters:
meth - the other method to examine
Returns:
true if this method overrides the other
Since:
1.5
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


PackageDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface PackageDoc

All Superinterfaces:
Comparable<Object>, Doc
public interface PackageDoc
extends Doc

Represents a java package. Provides access to information about the package, the package's comment and tags, and the classes in the package.

Each method whose return type is an array will return an empty array (never null) when there are no objects in the result.

Since:
1.2

Method Summary
ClassDoc[] | allClasses() Get all included classes and interfaces in the package.
ClassDoc[] | allClasses(boolean filter) Get all classes and interfaces in the package, filtered to the specified access modifier option.
AnnotationDesc[] | annotations() Get the annotations of this package.
AnnotationTypeDoc[] | annotationTypes() Get included annotation types in this package.
ClassDoc[] | enums() Get included enum types in this package.
ClassDoc[] | errors() Get included Error classes in this package.
ClassDoc[] | exceptions() Get included Exception classes in this package.
ClassDoc | findClass(String className) Lookup a class or interface within this package.
ClassDoc[] | interfaces() Get included interfaces in this package, omitting annotation types.
ClassDoc[] | ordinaryClasses() Get included ordinary classes (that is, exclude exceptions, errors, enums, interfaces, and annotation types) in this package.
Methods inherited from interface com.sun.javadoc.Doc
commentText, compareTo, firstSentenceTags, getRawCommentText, inlineTags, isAnnotationType, isAnnotationTypeElement, isClass, isConstructor, isEnum, isEnumConstant, isError, isException, isField, isIncluded, isInterface, isMethod, isOrdinaryClass, name, position, seeTags, setRawCommentText, tags, tags

Method Detail

allClasses

ClassDoc[] allClasses(boolean filter)
Get all classes and interfaces in the package, filtered to the specified access modifier option.

Parameters:
filter - Specifying true filters according to the specified access modifier option. Specifying false includes all classes and interfaces regardless of access modifier option.
Returns:
filtered classes and interfaces in this package
Since:
1.4

allClasses

ClassDoc[] allClasses()
Get all included classes and interfaces in the package. Same as allClasses(true).

Returns:
all included classes and interfaces in this package.

ordinaryClasses

ClassDoc[] ordinaryClasses()
Get included ordinary classes (that is, exclude exceptions, errors, enums, interfaces, and annotation types) in this package.

Returns:
included ordinary classes in this package.

exceptions

ClassDoc[] exceptions()
Get included Exception classes in this package.

Returns:
included Exceptions in this package.

errors

ClassDoc[] errors()
Get included Error classes in this package.

Returns:
included Errors in this package.

enums

ClassDoc[] enums()
Get included enum types in this package.

Returns:
included enum types in this package.
Since:
1.5

interfaces

ClassDoc[] interfaces()
Get included interfaces in this package, omitting annotation types.

Returns:
included interfaces in this package.

annotationTypes

AnnotationTypeDoc[] annotationTypes()
Get included annotation types in this package.

Returns:
included annotation types in this package.
Since:
1.5

annotations

AnnotationDesc[] annotations()
Get the annotations of this package. Return an empty array if there are none.

Returns:
the annotations of this package.
Since:
1.5

findClass

ClassDoc findClass(String className)
Lookup a class or interface within this package.

Returns:
ClassDoc of found class or interface, or null if not found.
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Parameter

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface Parameter

public interface Parameter

Parameter information. This includes a parameter type and parameter name.

Method Summary
AnnotationDesc[] | annotations() Get the annotations of this parameter.
String | name() Get local name of this parameter.
String | toString() Returns a string representation of the parameter.
Type | type() Get the type of this parameter.
String | typeName() Get type name of this parameter.

Method Detail

type

Type type()
Get the type of this parameter.

name

String name()
Get local name of this parameter. For example if parameter is the short 'index', returns "index".

typeName

String typeName()
Get type name of this parameter. For example if parameter is the short 'index', returns "short".

This method returns a complete string representation of the type, including the dimensions of arrays and the type arguments of parameterized types. Names are qualified.

toString

String toString()
Returns a string representation of the parameter.

For example if parameter is the short 'index', returns "short index".

Overrides:
toString in class Object
Returns:
type and parameter name of this parameter.

annotations

AnnotationDesc[] annotations()
Get the annotations of this parameter. Return an empty array if there are none.

Returns:
the annotations of this parameter.
Since:
1.5
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


ParameterizedType

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface ParameterizedType

All Superinterfaces:
Type
public interface ParameterizedType
extends Type

Represents an invocation of a generic class or interface. For example, given the generic interface List<E>, possible invocations include:

        List<String>
        List<T extends Number>
        List<?>
A generic inner class Outer<T>.Inner<S> might be invoked as:
        Outer<Number>.Inner<String>

Since:
1.5

Method Summary
ClassDoc | asClassDoc() Return the generic class or interface that declared this type.
Type | containingType() Return the type that contains this type as a member.
Type[] | interfaceTypes() Return the interface types directly implemented by or extended by this parameterized type.
Type | superclassType() Return the class type that is a direct supertype of this one.
Type[] | typeArguments() Return the actual type arguments of this type.
Methods inherited from interface com.sun.javadoc.Type
asAnnotationTypeDoc, asParameterizedType, asTypeVariable, asWildcardType, dimension, isPrimitive, qualifiedTypeName, simpleTypeName, toString, typeName

Method Detail

asClassDoc

ClassDoc asClassDoc()
Return the generic class or interface that declared this type.

Specified by:
asClassDoc in interface Type
Returns:
the generic class or interface that declared this type.

typeArguments

Type[] typeArguments()
Return the actual type arguments of this type. For a generic type that is nested within some other generic type (such as Outer<T>.Inner<S>), only the type arguments of the innermost type are included.

Returns:
the actual type arguments of this type.

superclassType

Type superclassType()
Return the class type that is a direct supertype of this one. This is the superclass of this type's declaring class, with type arguments substituted in. Return null if this is an interface type.

For example, if this parameterized type is java.util.ArrayList<String>, the result will be java.util.AbstractList<String>.

Returns:
the class type that is a direct supertype of this one.

interfaceTypes

Type[] interfaceTypes()
Return the interface types directly implemented by or extended by this parameterized type. These are the interfaces directly implemented or extended by this type's declaring class or interface, with type arguments substituted in. Return an empty array if there are no interfaces.

For example, the interface extended by java.util.Set<String> is java.util.Collection<String>.

Returns:
the interface types directly implemented by or extended by this parameterized type.

containingType

Type containingType()
Return the type that contains this type as a member. Return null is this is a top-level type.

For example, the containing type of AnInterface.Nested<Number> is the ClassDoc representing AnInterface, and the containing type of Outer<String>.Inner<Number> is the ParameterizedType representing Outer<String>.

Returns:
the type that contains this type as a member.
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


ParamTag

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface ParamTag

All Superinterfaces:
Tag
public interface ParamTag
extends Tag

Represents an @param documentation tag. Stores the name and comment parts of the parameter tag. An @param tag may represent either a method or constructor parameter, or a type parameter.

Method Summary
boolean | isTypeParameter() Return true if this ParamTag corresponds to a type parameter.
String | parameterComment() Return the parameter comment associated with this ParamTag.
String | parameterName() Return the name of the parameter or type parameter associated with this ParamTag.
Methods inherited from interface com.sun.javadoc.Tag
firstSentenceTags, holder, inlineTags, kind, name, position, text, toString

Method Detail

parameterName

String parameterName()
Return the name of the parameter or type parameter associated with this ParamTag. The angle brackets delimiting a type parameter are not part of its name.

Returns:
the parameter name.

parameterComment

String parameterComment()
Return the parameter comment associated with this ParamTag.

Returns:
the parameter comment.

isTypeParameter

boolean isTypeParameter()
Return true if this ParamTag corresponds to a type parameter. Return false if it corresponds to an ordinary parameter of a method or constructor.

Returns:
true if this ParamTag corresponds to a type parameter.
Since:
1.5
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


ProgramElementDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface ProgramElementDoc

All Superinterfaces:
Comparable<Object>, Doc
All Known Subinterfaces:
AnnotationTypeDoc, AnnotationTypeElementDoc, ClassDoc, ConstructorDoc, ExecutableMemberDoc, FieldDoc, MemberDoc, MethodDoc
public interface ProgramElementDoc
extends Doc

Represents a java program element: class, interface, field, constructor, or method. This is an abstract class dealing with information common to these elements.

See Also:
MemberDoc, ClassDoc

Method Summary
AnnotationDesc[] | annotations() Get the annotations of this program element.
ClassDoc | containingClass() Get the containing class or interface of this program element.
PackageDoc | containingPackage() Get the package that this program element is contained in.
boolean | isFinal() Return true if this program element is final.
boolean | isPackagePrivate() Return true if this program element is package private.
boolean | isPrivate() Return true if this program element is private.
boolean | isProtected() Return true if this program element is protected.
boolean | isPublic() Return true if this program element is public.
boolean | isStatic() Return true if this program element is static.
String | modifiers() Get modifiers string.
int | modifierSpecifier() Get the modifier specifier integer.
String | qualifiedName() Get the fully qualified name of this program element.
Methods inherited from interface com.sun.javadoc.Doc
commentText, compareTo, firstSentenceTags, getRawCommentText, inlineTags, isAnnotationType, isAnnotationTypeElement, isClass, isConstructor, isEnum, isEnumConstant, isError, isException, isField, isIncluded, isInterface, isMethod, isOrdinaryClass, name, position, seeTags, setRawCommentText, tags, tags

Method Detail

containingClass

ClassDoc containingClass()
Get the containing class or interface of this program element.

Returns:
a ClassDoc for this element's containing class or interface. If this is a top-level class or interface, return null.

containingPackage

PackageDoc containingPackage()
Get the package that this program element is contained in.

Returns:
a PackageDoc for this element containing package. If in the unnamed package, this PackageDoc will have the name "".

qualifiedName

String qualifiedName()
Get the fully qualified name of this program element. For example, for the class java.util.Hashtable, return "java.util.Hashtable".

For the method bar() in class Foo in the unnamed package, return "Foo.bar".

Returns:
the qualified name of the program element as a String.

modifierSpecifier

int modifierSpecifier()
Get the modifier specifier integer.

See Also:
Modifier

modifiers

String modifiers()
Get modifiers string. For example, for:
   public abstract int foo() { ... }
return "public abstract". Annotations are not included.

annotations

AnnotationDesc[] annotations()
Get the annotations of this program element. Return an empty array if there are none.

Returns:
the annotations of this program element.
Since:
1.5

isPublic

boolean isPublic()
Return true if this program element is public.

isProtected

boolean isProtected()
Return true if this program element is protected.

isPrivate

boolean isPrivate()
Return true if this program element is private.

isPackagePrivate

boolean isPackagePrivate()
Return true if this program element is package private.

isStatic

boolean isStatic()
Return true if this program element is static.

isFinal

boolean isFinal()
Return true if this program element is final.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


RootDoc

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface RootDoc

All Superinterfaces:
Comparable<Object>, Doc, DocErrorReporter
public interface RootDoc
extends Doc, DocErrorReporter

Represents the root of the program structure information for one run of javadoc. From this root all other program structure information can be extracted. Also represents the command line information -- the packages, classes and options specified by the user.

Since:
1.2

Method Summary
ClassDoc[] | classes() Return the included classes and interfaces in all packages.
ClassDoc | classNamed(String qualifiedName) Return a ClassDoc for the specified class or interface name.
String[][] | options() Command line options.
PackageDoc | packageNamed(String name) Return a PackageDoc for the specified package name.
ClassDoc[] | specifiedClasses() Return the classes and interfaces specified as source file names on the command line.
PackageDoc[] | specifiedPackages() Return the packages specified on the command line.
Methods inherited from interface com.sun.javadoc.Doc
commentText, compareTo, firstSentenceTags, getRawCommentText, inlineTags, isAnnotationType, isAnnotationTypeElement, isClass, isConstructor, isEnum, isEnumConstant, isError, isException, isField, isIncluded, isInterface, isMethod, isOrdinaryClass, name, position, seeTags, setRawCommentText, tags, tags
Methods inherited from interface com.sun.javadoc.DocErrorReporter
printError, printError, printNotice, printNotice, printWarning, printWarning

Method Detail

options

String[][] options()
Command line options.

For example, given:

     javadoc -foo this that -bar other ...
this method will return:
      options()[0][0] = "-foo"
      options()[0][1] = "this"
      options()[0][2] = "that"
      options()[1][0] = "-bar"
      options()[1][1] = "other"

Returns:
an array of arrays of String.

specifiedPackages

PackageDoc[] specifiedPackages()
Return the packages specified on the command line. If -subpackages and -exclude options are used, return all the non-excluded packages.

Returns:
packages specified on the command line.

specifiedClasses

ClassDoc[] specifiedClasses()
Return the classes and interfaces specified as source file names on the command line.

Returns:
classes and interfaces specified on the command line.

classes

ClassDoc[] classes()
Return the included classes and interfaces in all packages.

Returns:
included classes and interfaces in all packages.

packageNamed

PackageDoc packageNamed(String name)
Return a PackageDoc for the specified package name.

Parameters:
name - package name
Returns:
a PackageDoc holding the specified package, null if this package is not referenced.

classNamed

ClassDoc classNamed(String qualifiedName)
Return a ClassDoc for the specified class or interface name.

Parameters:
qualifiedName - qualified class or package name
Returns:
a ClassDoc holding the specified class, null if this class is not referenced.
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


SeeTag

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface SeeTag

All Superinterfaces:
Tag
public interface SeeTag
extends Tag

Represents a user-defined cross-reference to related documentation. The tag can reference a package, class or member, or can hold plain text. (The plain text might be a reference to something not online, such as a printed book, or be a hard-coded HTML link.) The reference can either be inline with the comment, using {@link}, or a separate block comment, using @see. Method name() returns "@link" (no curly braces) or "@see", depending on the tag. Method kind() returns "@see" for both tags.

Method Summary
String | label() Get the label of the @see tag.
ClassDoc | referencedClass() Get the class doc referenced by the class name part of @see.
String | referencedClassName() Get the class or interface name of the @see reference.
MemberDoc | referencedMember() Get the member doc for the field, constructor or method referenced by @see.
String | referencedMemberName() Get the field, constructor or method substring of the @see reference.
PackageDoc | referencedPackage() Get the package doc when @see references only a package.
Methods inherited from interface com.sun.javadoc.Tag
firstSentenceTags, holder, inlineTags, kind, name, position, text, toString

Method Detail

label

String label()
Get the label of the @see tag. Return null if no label is present. For example, for:

@see String#trim() the trim method

return "the trim method".

referencedPackage

PackageDoc referencedPackage()
Get the package doc when @see references only a package. Return null if the package cannot be found, or if @see references any other element (class, interface, field, constructor, method) or non-element. For example, for:

@see java.lang

return the PackageDoc for java.lang.

referencedClassName

String referencedClassName()
Get the class or interface name of the @see reference. The name is fully qualified if the name specified in the original @see tag was fully qualified, or if the class or interface can be found; otherwise it is unqualified. If @see references only a package name, then return the package name instead. For example, for:

@see String#valueOf(java.lang.Object)

return "java.lang.String". For "@see java.lang", return "java.lang". Return null if @see references a non-element, such as @see <a href="java.sun.com">.

referencedClass

ClassDoc referencedClass()
Get the class doc referenced by the class name part of @see. Return null if the class cannot be found. For example, for:

@see String#valueOf(java.lang.Object)

return the ClassDoc for java.lang.String.

referencedMemberName

String referencedMemberName()
Get the field, constructor or method substring of the @see reference. Return null if the reference is to any other element or to any non-element. References to member classes (nested classes) return null. For example, for:

@see String#startsWith(String)

return "startsWith(String)".

referencedMember

MemberDoc referencedMember()
Get the member doc for the field, constructor or method referenced by @see. Return null if the member cannot be found or if the reference is to any other element or to any non-element. References to member classes (nested classes) return null. For example, for:

@see String#startsWith(java.lang.String)

return the MethodDoc for startsWith.

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


SerialFieldTag

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface SerialFieldTag

All Superinterfaces:
Comparable<Object>, Tag
public interface SerialFieldTag
extends Tag, Comparable<Object>

Documents a Serializable field defined by an ObjectStreamField.

 The class parses and stores the three serialField tag parameters:

 - field name
 - field type name
      (fully-qualified or visible from the current import context)
 - description of the valid values for the field
This tag is only allowed in the javadoc for the special member serialPersistentFields.

See Also:
ObjectStreamField

Method Summary
int | compareTo(Object obj) Compares this Object with the specified Object for order.
String | description() Return the field comment.
String | fieldName() Return the serialziable field name.
String | fieldType() Return the field type string.
ClassDoc | fieldTypeDoc() Return the ClassDoc for field type.
Methods inherited from interface com.sun.javadoc.Tag
firstSentenceTags, holder, inlineTags, kind, name, position, text, toString

Method Detail

fieldName

String fieldName()
Return the serialziable field name.

fieldType

String fieldType()
Return the field type string.

fieldTypeDoc

ClassDoc fieldTypeDoc()
Return the ClassDoc for field type.

Returns:
null if no ClassDoc for field type is visible from containingClass context.

description

String description()
Return the field comment. If there is no serialField comment, return javadoc comment of corresponding FieldDoc.

compareTo

int compareTo(Object obj)
Compares this Object with the specified Object for order. Returns a negative integer, zero, or a positive integer as this Object is less than, equal to, or greater than the given Object.

Included to make SerialFieldTag items java.lang.Comparable.

Specified by:
compareTo in interface Comparable<Object>
Parameters:
obj - the Object to be compared.
Returns:
a negative integer, zero, or a positive integer as this Object is less than, equal to, or greater than the given Object.
Throws:
ClassCastException - the specified Object's type prevents it from being compared to this Object.
Since:
1.2
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


SourcePosition

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface SourcePosition

public interface SourcePosition

This interface describes a source position: filename, line number, and column number.

Since:
1.4

Method Summary
int | column() The column in the source file.
File | file() The source file.
int | line() The line in the source file.
String | toString() Convert the source position to the form "Filename:line".

Method Detail

file

File file()
The source file. Returns null if no file information is available.

line

int line()
The line in the source file. The first line is numbered 1; 0 means no line number information is available.

column

int column()
The column in the source file. The first column is numbered 1; 0 means no column information is available. Columns count characters in the input stream; a tab advances the column number to the next 8-column tab stop.

toString

String toString()
Convert the source position to the form "Filename:line".

Overrides:
toString in class Object
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Tag

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface Tag

All Known Subinterfaces:
ParamTag, SeeTag, SerialFieldTag, ThrowsTag
public interface Tag

Represents a simple documentation tag, such as @since, @author, @version. Given a tag (e.g. "@since 1.2"), holds tag name (e.g. "@since") and tag text (e.g. "1.2"). Tags with structure or which require special processing are handled by subclasses such as ParamTag (for @param), SeeTag (for @see and {@link}), and ThrowsTag (for @throws).

See Also:
SeeTag, ParamTag, ThrowsTag, SerialFieldTag, Doc.tags()

Method Summary
Tag[] | firstSentenceTags() Return the first sentence of the comment as an array of tags.
Doc | holder() Return the containing Doc of this Tag element.
Tag[] | inlineTags() For a documentation comment with embedded {@link} tags, return an array of Tag objects.
String | kind() Return the kind of this tag.
String | name() Return the name of this tag.
SourcePosition | position() Return the source position of this tag.
String | text() Return the text of this tag, that is, portion beyond tag name.
String | toString() Convert this object to a string.

Method Detail

name

String name()
Return the name of this tag. The name is the string starting with "@" that is used in a doc comment, such as @return. For inline tags, such as {@link}, the curly brackets are not part of the name, so in this example the name would be simply @link.

holder

Doc holder()
Return the containing Doc of this Tag element.

kind

String kind()
Return the kind of this tag. similar or synonymous tags. For most tags, kind() == name(); the following table lists those cases where there is more than one tag of a given kind:

kind() | name()
@throws | @throws
@throws | @exception
@see | @see
@see | @link
@see | @linkplain
@serial | @serial
@serial | @serialData

text

String text()
Return the text of this tag, that is, portion beyond tag name.

toString

String toString()
Convert this object to a string.

Overrides:
toString in class Object

inlineTags

Tag[] inlineTags()
For a documentation comment with embedded {@link} tags, return an array of Tag objects. The entire doc comment is broken down into strings separated by {@link} tags, where each successive element of the array represents either a string or {@link} tag, in order, from start to end. Each string is represented by a Tag object of name "Text", where text() returns the string. Each {@link} tag is represented by a SeeTag of name "@link" and kind "@see". For example, given the following comment tag:

This is a {@link Doc commentlabel} example.

return an array of Tag objects:

  • tags[0] is a Tag with name "Text" and text consisting of "This is a "
  • tags[1] is a SeeTag with name "@link", referenced class Doc and label "commentlabel"
  • tags[2] is a Tag with name "Text" and text consisting of " example."

Returns:
Tag[] array of tags
See Also:
ParamTag, ThrowsTag

firstSentenceTags

Tag[] firstSentenceTags()
Return the first sentence of the comment as an array of tags. Includes inline tags (i.e. {@link reference} tags) but not block tags. Each section of plain text is represented as a Tag of kind "Text". Inline tags are represented as a SeeTag of kind "@link". If the locale is English language, the first sentence is determined by the rules described in the Java Language Specification (first version): "This sentence ends at the first period that is followed by a blank, tab, or line terminator or at the first tagline.", in addition a line will be terminated by paragraph and section terminating HTML tags: <p> </p> <h1> <h2> <h3> <h4> <h5> <h6> <hr> <pre> or </pre>. If the locale is not English, the sentence end will be determined by BreakIterator.getSentenceInstance(Locale).

Returns:
an array of Tag objects representing the first sentence of the comment

position

SourcePosition position()
Return the source position of this tag.

Returns:
the source position of this tag.
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


ThrowsTag

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface ThrowsTag

All Superinterfaces:
Tag
public interface ThrowsTag
extends Tag

Represents a @throws or @exception documentation tag. Parses and holds the exception name and exception comment. Note: @exception is a backwards compatible synonymy for @throws.

See Also:
ExecutableMemberDoc.throwsTags()

Method Summary
ClassDoc | exception() Return a ClassDoc that represents the exception.
String | exceptionComment() Return the exception comment associated with this ThrowsTag.
String | exceptionName() Return the name of the exception associated with this ThrowsTag.
Type | exceptionType() Return the type of the exception associated with this ThrowsTag.
Methods inherited from interface com.sun.javadoc.Tag
firstSentenceTags, holder, inlineTags, kind, name, position, text, toString

Method Detail

exceptionName

String exceptionName()
Return the name of the exception associated with this ThrowsTag.

Returns:
name of the exception.

exceptionComment

String exceptionComment()
Return the exception comment associated with this ThrowsTag.

Returns:
exception comment.

exception

ClassDoc exception()
Return a ClassDoc that represents the exception. If the type of the exception is a type variable, return the ClassDoc of its erasure.

This method cannot accommodate certain generic type constructs. The exceptionType method should be used instead.

Returns:
ClassDoc that represents the exception.
See Also:
exceptionType()

exceptionType

Type exceptionType()
Return the type of the exception associated with this ThrowsTag. This may be a ClassDoc or a TypeVariable.

Returns:
the type of the exception.
Since:
1.5
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Type

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface Type

All Known Subinterfaces:
AnnotationTypeDoc, ClassDoc, ParameterizedType, TypeVariable, WildcardType
public interface Type

Represents a type. A type can be a class or interface, an invocation (like List<String>) of a generic class or interface, a type variable, a wildcard type ("?"), or a primitive data type (like char).

Since:
1.2

Method Summary
AnnotationTypeDoc | asAnnotationTypeDoc() Return this type as an AnnotationTypeDoc if it represents an annotation type.
ClassDoc | asClassDoc() Return this type as a ClassDoc if it represents a class or interface.
ParameterizedType | asParameterizedType() Return this type as a ParameterizedType if it represents an invocation of a generic class or interface.
TypeVariable | asTypeVariable() Return this type as a TypeVariable if it represents a type variable.
WildcardType | asWildcardType() Return this type as a WildcardType if it represents a wildcard type.
String | dimension() Return the type's dimension information, as a string.
boolean | isPrimitive() Return true if this type represents a primitive type.
String | qualifiedTypeName() Return qualified name of type excluding any dimension information.
String | simpleTypeName() Return the simple name of this type excluding any dimension information.
String | toString() Return a string representation of the type.
String | typeName() Return unqualified name of type excluding any dimension information.

Method Detail

typeName

String typeName()
Return unqualified name of type excluding any dimension information.

For example, a two dimensional array of String returns "String".

qualifiedTypeName

String qualifiedTypeName()
Return qualified name of type excluding any dimension information.

For example, a two dimensional array of String returns "java.lang.String".

simpleTypeName

String simpleTypeName()
Return the simple name of this type excluding any dimension information. This is the unqualified name of the type, except that for nested types only the identifier of the innermost type is included.

For example, the class Outer.Inner returns "Inner".

Since:
1.5

dimension

String dimension()
Return the type's dimension information, as a string.

For example, a two dimensional array of String returns "[][]".

toString

String toString()
Return a string representation of the type. This includes any dimension information and type arguments.

For example, a two dimensional array of String may return "java.lang.String[][]", and the parameterized type List<Integer> may return "java.util.List<java.lang.Integer>".

Overrides:
toString in class Object
Returns:
a string representation of the type.

isPrimitive

boolean isPrimitive()
Return true if this type represents a primitive type.

Returns:
true if this type represents a primitive type.
Since:
1.5

asClassDoc

ClassDoc asClassDoc()
Return this type as a ClassDoc if it represents a class or interface. Array dimensions are ignored. If this type is a ParameterizedType, TypeVariable, or WildcardType, return the ClassDoc of the type's erasure. If this is an AnnotationTypeDoc, return this as a ClassDoc (but see asAnnotationTypeDoc()). If this is a primitive type, return null.

Returns:
the ClassDoc of this type, or null if it is a primitive type.

asParameterizedType

ParameterizedType asParameterizedType()
Return this type as a ParameterizedType if it represents an invocation of a generic class or interface. Array dimensions are ignored.

Returns:
a ParameterizedType if the type is an invocation of a generic type, or null if it is not.
Since:
1.5

asTypeVariable

TypeVariable asTypeVariable()
Return this type as a TypeVariable if it represents a type variable. Array dimensions are ignored.

Returns:
a TypeVariable if the type is a type variable, or null if it is not.
Since:
1.5

asWildcardType

WildcardType asWildcardType()
Return this type as a WildcardType if it represents a wildcard type.

Returns:
a WildcardType if the type is a wildcard type, or null if it is not.
Since:
1.5

asAnnotationTypeDoc

AnnotationTypeDoc asAnnotationTypeDoc()
Return this type as an AnnotationTypeDoc if it represents an annotation type. Array dimensions are ignored.

Returns:
an AnnotationTypeDoc if the type is an annotation type, or null if it is not.
Since:
1.5
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


TypeVariable

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface TypeVariable

All Superinterfaces:
Type
public interface TypeVariable
extends Type

Represents a type variable. For example, the generic interface List<E> has a single type variable E. A type variable may have explicit bounds, as in C<R extends Remote>.

Since:
1.5

Method Summary
Type[] | bounds() Return the bounds of this type variable.
ProgramElementDoc | owner() Return the class, interface, method, or constructor within which this type variable is declared.
Methods inherited from interface com.sun.javadoc.Type
asAnnotationTypeDoc, asClassDoc, asParameterizedType, asTypeVariable, asWildcardType, dimension, isPrimitive, qualifiedTypeName, simpleTypeName, toString, typeName

Method Detail

bounds

Type[] bounds()
Return the bounds of this type variable. These are the types given by the extends clause. Return an empty array if there are no explicit bounds.

Returns:
the bounds of this type variable.

owner

ProgramElementDoc owner()
Return the class, interface, method, or constructor within which this type variable is declared.

Returns:
the class, interface, method, or constructor within which this type variable is declared.
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


WildcardType

Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.javadoc
Interface WildcardType

All Superinterfaces:
Type
public interface WildcardType
extends Type

Represents a wildcard type argument. Examples include:

 <?>
 <? extends E>
 <? super T>
A wildcard type can have explicit extends bounds or explicit super bounds or neither, but not both.

Since:
1.5

Method Summary
Type[] | extendsBounds() Return the upper bounds of this wildcard type argument as given by the extends clause.
Type[] | superBounds() Return the lower bounds of this wildcard type argument as given by the super clause.
Methods inherited from interface com.sun.javadoc.Type
asAnnotationTypeDoc, asClassDoc, asParameterizedType, asTypeVariable, asWildcardType, dimension, isPrimitive, qualifiedTypeName, simpleTypeName, toString, typeName

Method Detail

extendsBounds

Type[] extendsBounds()
Return the upper bounds of this wildcard type argument as given by the extends clause. Return an empty array if no such bounds are explicitly given.

Returns:
the extends bounds of this wildcard type argument

superBounds

Type[] superBounds()
Return the lower bounds of this wildcard type argument as given by the super clause. Return an empty array if no such bounds are explicitly given.

Returns:
the super bounds of this wildcard type argument
Package Class Use Tree Deprecated Index Help
Doclet API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


doclets

Package com.sun.tools.doclets

As of JDK version 1.5, replaced by com.sun.tools.doclets.internal.toolkit.util.

See:
Description

Interface Summary
Taglet The interface for a custom tag used by Doclets.

Package com.sun.tools.doclets Description

As of JDK version 1.5, replaced by com.sun.tools.doclets.internal.toolkit.util.

Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


com.sun.tools.doclets Class Hierarchy

Hierarchy For Package com.sun.tools.doclets

Interface Hierarchy

  • com.sun.tools.doclets.Taglet
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Package com.sun.tools.doclets

Uses of Package
com.sun.tools.doclets

No usage of com.sun.tools.doclets

Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Uses of Interface com.sun.tools.doclets.Taglet

Uses of Interface
com.sun.tools.doclets.Taglet

No usage of com.sun.tools.doclets.Taglet

Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


Taglet

com.sun.tools.doclets
Interface Taglet

public interface Taglet

The interface for a custom tag used by Doclets. A custom tag must implement this interface. To be loaded and used by doclets at run-time, the taglet must have a static method called register that accepts a Map as an argument with the following signature:

   public void register(Map map)
This method should add an instance of the custom taglet to the map with the name of the taglet as the key. If overriding a taglet, to avoid a name conflict, the overridden taglet must be deleted from the map before an instance of the new taglet is added to the map.

It is recommended that the taglet throw an exception when it fails to register itself. The exception that it throws is up to the user.

Here are two sample taglets:

  • ToDoTaglet.java - Standalone taglet
  • UnderlineTaglet.java - Inline taglet

For more information on how to create your own Taglets, please see the Taglet Overview.

Since:
1.4

Method Summary
String | getName() Return the name of this custom tag.
boolean | inConstructor() Return true if this Taglet is used in constructor documentation.
boolean | inField() Return true if this Taglet is used in field documentation.
boolean | inMethod() Return true if this Taglet is used in method documentation.
boolean | inOverview() Return true if this Taglet is used in overview documentation.
boolean | inPackage() Return true if this Taglet is used in package documentation.
boolean | inType() Return true if this Taglet is used in type documentation (classes or interfaces).
boolean | isInlineTag() Return true if this Taglet is an inline tag.
String | toString(com.sun.javadoc.Tag tag) Given the Tag representation of this custom tag, return its string representation, which is output to the generated page.
String | toString(com.sun.javadoc.Tag[] tags) Given an array of Tags representing this custom tag, return its string representation, which is output to the generated page.

Method Detail

inField

boolean inField()
Return true if this Taglet is used in field documentation. Set to false for inline tags.

Returns:
true if this Taglet is used in field documentation and false otherwise.

inConstructor

boolean inConstructor()
Return true if this Taglet is used in constructor documentation. Set to false for inline tags.

Returns:
true if this Taglet is used in constructor documentation and false otherwise.

inMethod

boolean inMethod()
Return true if this Taglet is used in method documentation. Set to false for inline tags.

Returns:
true if this Taglet is used in method documentation and false otherwise.

inOverview

boolean inOverview()
Return true if this Taglet is used in overview documentation. Set to false for inline tags.

Returns:
true if this Taglet is used in method documentation and false otherwise.

inPackage

boolean inPackage()
Return true if this Taglet is used in package documentation. Set to false for inline tags.

Returns:
true if this Taglet is used in package documentation and false otherwise.

inType

boolean inType()
Return true if this Taglet is used in type documentation (classes or interfaces). Set to false for inline tags.

Returns:
true if this Taglet is used in type documentation and false otherwise.

isInlineTag

boolean isInlineTag()
Return true if this Taglet is an inline tag. Return false otherwise.

Returns:
true if this Taglet is an inline tag and false otherwise.

getName

String getName()
Return the name of this custom tag.

Returns:
the name of this custom tag.

toString

String toString(com.sun.javadoc.Tag tag)
Given the Tag representation of this custom tag, return its string representation, which is output to the generated page.

Parameters:
tag - the Tag representation of this custom tag.
Returns:
the string representation of this Tag.

toString

String toString(com.sun.javadoc.Tag[] tags)
Given an array of Tags representing this custom tag, return its string representation, which is output to the generated page. This method should return null if this taglet represents an inline tag.

Parameters:
tags - the array of Tags representing of this custom tag.
Returns:
the string representation of this Tag.
Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2006 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.


 All Classes
JConsoleContext
JConsoleContext.ConnectionState
JConsolePlugin


API Help

Package Class Use Tree Index Help
JConsole API
PREV NEXT FRAMES NO FRAMES

How This API Document Is Organized

This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.

Package

Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain four categories:

  • Interfaces (italic)
  • Classes
  • Enums
  • Exceptions
  • Errors
  • Annotation Types

Class/Interface

Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:

  • Class inheritance diagram
  • Direct Subclasses
  • All Known Subinterfaces
  • All Known Implementing Classes
  • Class/interface declaration
  • Class/interface description

  • Nested Class Summary
  • Field Summary
  • Constructor Summary
  • Method Summary

  • Field Detail
  • Constructor Detail
  • Method Detail
Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.

Annotation Type

Each annotation type has its own separate page with the following sections:

  • Annotation Type declaration
  • Annotation Type description
  • Required Element Summary
  • Optional Element Summary
  • Element Detail

Enum

Each enum has its own separate page with the following sections:

  • Enum declaration
  • Enum description
  • Enum Constant Summary
  • Enum Constant Detail

Use

Each documented package, class and interface has its own Use page. This page describes what packages, classes, methods, constructors and fields use any part of the given class or package. Given a class or interface A, its Use page includes subclasses of A, fields declared as A, methods that return A, and methods and constructors with parameters of type A. You can access this page by first going to the package, class or interface, then clicking on the "Use" link in the navigation bar.

Tree (Class Hierarchy)

There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with java.lang.Object. The interfaces do not inherit from java.lang.Object.
  • When viewing the Overview page, clicking on "Tree" displays the hierarchy for all packages.
  • When viewing a particular package, class or interface page, clicking "Tree" displays the hierarchy for only that package.

Index

The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.

Prev/Next

These links take you to the next or previous class, interface, package, or related page.

Frames/No Frames

These links show and hide the HTML frames. All pages are available with or without frames.

Serialized Form

Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.

Constant Field Values

The Constant Field Values page lists the static final fields and their values.

This help file applies to API documentation generated using the standard doclet.

Package Class Use Tree Index Help
JConsole API
PREV NEXT FRAMES NO FRAMES


Constant Field Values

Contents
  • com.sun.*
com.sun.*

com.sun.tools.jconsole.JConsoleContext
public static final String CONNECTION_STATE_PROPERTY "connectionState"

Package Class Use Tree Index Help
JConsole API
PREV NEXT FRAMES NO FRAMES


Hierarchy

Package Class Use Tree Index Help
JConsole API
PREV NEXT FRAMES NO FRAMES

Hierarchy For All Packages

Package Hierarchies:
com.sun.tools.jconsole

Class Hierarchy

  • java.lang.Object
    • com.sun.tools.jconsole.JConsolePlugin

Interface Hierarchy

  • com.sun.tools.jconsole.JConsoleContext

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • com.sun.tools.jconsole.JConsoleContext.ConnectionState
Package Class Use Tree Index Help
JConsole API
PREV NEXT FRAMES NO FRAMES


Index

Package Class Use Tree Index Help
JConsole API
PREV NEXT FRAMES NO FRAMES
A C D G J N R S V

A

addContextPropertyChangeListener(PropertyChangeListener) - Method in class com.sun.tools.jconsole.JConsolePlugin
Adds a PropertyChangeListener to the JConsoleContext object for this plugin.
addPropertyChangeListener(PropertyChangeListener) - Method in interface com.sun.tools.jconsole.JConsoleContext
Add a PropertyChangeListener to the listener list.

C

com.sun.tools.jconsole - package com.sun.tools.jconsole
This package contains the JConsole API.
CONNECTION_STATE_PROPERTY - Static variable in interface com.sun.tools.jconsole.JConsoleContext
The ConnectionState bound property name.

D

dispose() - Method in class com.sun.tools.jconsole.JConsolePlugin
Dispose this plugin.

G

getConnectionState() - Method in interface com.sun.tools.jconsole.JConsoleContext
Returns the current connection state.
getContext() - Method in class com.sun.tools.jconsole.JConsolePlugin
Returns the JConsoleContext object representing the connection to an application.
getMBeanServerConnection() - Method in interface com.sun.tools.jconsole.JConsoleContext
Returns the MBeanServerConnection for the connection to an application.
getTabs() - Method in class com.sun.tools.jconsole.JConsolePlugin
Returns the tabs to be added in JConsole window.

J

JConsoleContext - Interface in com.sun.tools.jconsole
JConsoleContext represents a JConsole connection to a target application.
JConsoleContext.ConnectionState - Enum in com.sun.tools.jconsole
Values for the ConnectionState bound property.
JConsolePlugin - Class in com.sun.tools.jconsole
A JConsole plugin class.
JConsolePlugin() - Constructor for class com.sun.tools.jconsole.JConsolePlugin
Constructor.

N

newSwingWorker() - Method in class com.sun.tools.jconsole.JConsolePlugin
Returns a SwingWorker to perform the GUI update for this plugin at the same interval as JConsole updates the GUI.

R

removeContextPropertyChangeListener(PropertyChangeListener) - Method in class com.sun.tools.jconsole.JConsolePlugin
Removes a PropertyChangeListener from the listener list of the JConsoleContext object for this plugin.
removePropertyChangeListener(PropertyChangeListener) - Method in interface com.sun.tools.jconsole.JConsoleContext
Removes a PropertyChangeListener from the listener list.

S

setContext(JConsoleContext) - Method in class com.sun.tools.jconsole.JConsolePlugin
Sets the JConsoleContext object representing the connection to an application.

V

valueOf(String) - Static method in enum com.sun.tools.jconsole.JConsoleContext.ConnectionState
Returns the enum constant of this type with the specified name.
values() - Static method in enum com.sun.tools.jconsole.JConsoleContext.ConnectionState
Returns an array containing the constants of this enum type, in the order they are declared.
A C D G J N R S V
Package Class Use Tree Index Help
JConsole API
PREV NEXT FRAMES NO FRAMES


JConsole API

Frame Alert

This document is designed to be viewed using the frames feature. If you see this message, you are using a non-frame-capable web client.
Link toNon-frame version.


jconsole

Package Class Use Tree Index Help
JConsole API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package com.sun.tools.jconsole

This package contains the JConsole API.

See:
Description

Interface Summary
JConsoleContext JConsoleContext represents a JConsole connection to a target application.

Class Summary
JConsolePlugin A JConsole plugin class.

Enum Summary
JConsoleContext.ConnectionState Values for the ConnectionState bound property.

Package com.sun.tools.jconsole Description

This package contains the JConsole API.

Since:
1.6
Package Class Use Tree Index Help
JConsole API
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


com.sun.tools.jconsole Class Hierarchy

Package Class Use Tree Index Help
JConsole API
PREV NEXT FRAMES NO FRAMES

Hierarchy For Package com.sun.tools.jconsole

Class Hierarchy

  • java.lang.Object
    • com.sun.tools.jconsole.JConsolePlugin

Interface Hierarchy

  • com.sun.tools.jconsole.JConsoleContext

Enum Hierarchy

  • java.lang.Object
    • java.lang.Enum<E> (implements java.lang.Comparable<T>, java.io.Serializable)
      • com.sun.tools.jconsole.JConsoleContext.ConnectionState
Package Class Use Tree Index Help
JConsole API
PREV NEXT FRAMES NO FRAMES


Uses of Package com.sun.tools.jconsole

Package Class Use Tree Index Help
JConsole API
PREV NEXT FRAMES NO FRAMES

Uses of Package
com.sun.tools.jconsole

Classes in com.sun.tools.jconsole used by com.sun.tools.jconsole
JConsoleContext
JConsoleContext represents a JConsole connection to a target application.
JConsoleContext.ConnectionState
Values for the ConnectionState bound property.

Package Class Use Tree Index Help
JConsole API
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.tools.jconsole.JConsoleContext.ConnectionState

Package Class Use Tree Index Help
JConsole API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.tools.jconsole.JConsoleContext.ConnectionState

Uses of JConsoleContext.ConnectionState in com.sun.tools.jconsole

Methods in com.sun.tools.jconsole that return JConsoleContext.ConnectionState
JConsoleContext.ConnectionState | JConsoleContext.getConnectionState() Returns the current connection state.
static JConsoleContext.ConnectionState | JConsoleContext.ConnectionState.valueOf(String name) Returns the enum constant of this type with the specified name.
static JConsoleContext.ConnectionState[] | JConsoleContext.ConnectionState.values() Returns an array containing the constants of this enum type, in the order they are declared.

Package Class Use Tree Index Help
JConsole API
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.tools.jconsole.JConsolePlugin

Package Class Use Tree Index Help
JConsole API
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.tools.jconsole.JConsolePlugin

No usage of com.sun.tools.jconsole.JConsolePlugin

Package Class Use Tree Index Help
JConsole API
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.tools.jconsole.JConsoleContext

Package Class Use Tree Index Help
JConsole API
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.tools.jconsole.JConsoleContext

Uses of JConsoleContext in com.sun.tools.jconsole

Methods in com.sun.tools.jconsole that return JConsoleContext
 JConsoleContext JConsolePlugin.getContext()
Returns the JConsoleContext object representing the connection to an application.

Methods in com.sun.tools.jconsole with parameters of type JConsoleContext
 void JConsolePlugin.setContext(JConsoleContext context)
Sets the JConsoleContext object representing the connection to an application.

Package Class Use Tree Index Help
JConsole API
PREV NEXT FRAMES NO FRAMES


JConsoleContext

Package Class Use Tree Index Help
JConsole API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.tools.jconsole
Interface JConsoleContext

public interface JConsoleContext

JConsoleContext represents a JConsole connection to a target application.

JConsoleContext notifies any PropertyChangeListeners about the ConnectionState property change to CONNECTED and DISCONNECTED. The JConsoleContext instance will be the source for any generated events.

Since:
1.6

Nested Class Summary
static class JConsoleContext.ConnectionState
Values for the ConnectionState bound property.
Field Summary
static String CONNECTION_STATE_PROPERTY
The ConnectionState bound property name.
Method Summary
void | addPropertyChangeListener(PropertyChangeListener listener) Add a PropertyChangeListener to the listener list.
JConsoleContext.ConnectionState | getConnectionState() Returns the current connection state.
MBeanServerConnection | getMBeanServerConnection() Returns the MBeanServerConnection for the connection to an application.
void | removePropertyChangeListener(PropertyChangeListener listener) Removes a PropertyChangeListener from the listener list.

Field Detail

CONNECTION_STATE_PROPERTY

static final String CONNECTION_STATE_PROPERTY
The ConnectionState bound property name.

See Also:
Constant Field Values
Method Detail

getMBeanServerConnection

MBeanServerConnection getMBeanServerConnection()
Returns the MBeanServerConnection for the connection to an application. The returned MBeanServerConnection object becomes invalid when the connection state is changed to the DISCONNECTED state.

Returns:
the MBeanServerConnection for the connection to an application.

getConnectionState

JConsoleContext.ConnectionState getConnectionState()
Returns the current connection state.

Returns:
the current connection state.

addPropertyChangeListener

void addPropertyChangeListener(PropertyChangeListener listener)
Add a PropertyChangeListener to the listener list. The listener is registered for all properties. The same listener object may be added more than once, and will be called as many times as it is added. If listener is null, no exception is thrown and no action is taken.

Parameters:
listener - The PropertyChangeListener to be added

removePropertyChangeListener

void removePropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties. If listener was added more than once to the same event source, it will be notified one less time after being removed. If listener is null, or was never added, no exception is thrown and no action is taken.

Parameters:
listener - the PropertyChangeListener to be removed
Package Class Use Tree Index Help
JConsole API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


JConsoleContext.ConnectionState

Package Class Use Tree Index Help
JConsole API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD

com.sun.tools.jconsole
Enum JConsoleContext.ConnectionState

java.lang.Object
    extended by  java.lang.Enum<JConsoleContext.ConnectionState>
        extended by  com.sun.tools.jconsole.JConsoleContext.ConnectionState
All Implemented Interfaces:
Serializable, Comparable<JConsoleContext.ConnectionState>
Enclosing interface:
JConsoleContext
public static enum JConsoleContext.ConnectionState
extends Enum<JConsoleContext.ConnectionState>

Values for the ConnectionState bound property.

Enum Constant Summary
CONNECTED
The connection has been successfully established.
CONNECTING
The connection is being attempted.
DISCONNECTED
No connection present.
Method Summary
static JConsoleContext.ConnectionState | valueOf(String name) Returns the enum constant of this type with the specified name.
static JConsoleContext.ConnectionState[] | values() Returns an array containing the constants of this enum type, in the order they are declared.
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

CONNECTED

public static final JConsoleContext.ConnectionState CONNECTED
The connection has been successfully established.

DISCONNECTED

public static final JConsoleContext.ConnectionState DISCONNECTED
No connection present.

CONNECTING

public static final JConsoleContext.ConnectionState CONNECTING
The connection is being attempted.

Method Detail

values

public static JConsoleContext.ConnectionState[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (JConsoleContext.ConnectionState c : JConsoleContext.ConnectionState.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static JConsoleContext.ConnectionState valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null
Package Class Use Tree Index Help
JConsole API
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD DETAIL: ENUM CONSTANTS | FIELD | METHOD


JConsolePlugin

Package Class Use Tree Index Help
JConsole API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.tools.jconsole
Class JConsolePlugin

java.lang.Object
    extended by  com.sun.tools.jconsole.JConsolePlugin

public abstract class JConsolePlugin
extends Object

A JConsole plugin class. JConsole uses the service provider mechanism to search the JConsole plugins. Users can provide their JConsole plugins in a jar file containing a file named

 META-INF/services/com.sun.tools.jconsole.JConsolePlugin

This file contains one line for each plugin, for example,

 com.sun.example.JTop

which is the fully qualified class name of the class implementing JConsolePlugin.

To load the JConsole plugins in JConsole, run:

 jconsole -pluginpath <plugin-path>

where <plugin-path> specifies the paths of JConsole plugins to look up which can be a directory or a jar file. Multiple paths are separated by the path separator character of the platform.

When a new JConsole window is created for a connection, an instance of each JConsolePlugin will be created. The JConsoleContext object is not available at its construction time. JConsole will set the JConsoleContext object for a plugin after the plugin object is created. It will then call its getTabs method and add the returned tabs to the JConsole window.

Since:
1.6
See Also:
java.util.ServiceLoader

Constructor Summary
protected JConsolePlugin()
Constructor.
Method Summary
void | addContextPropertyChangeListener(PropertyChangeListener listener) Adds a PropertyChangeListener to the JConsoleContext object for this plugin.
void | dispose() Dispose this plugin.
JConsoleContext | getContext() Returns the JConsoleContext object representing the connection to an application.
abstract Map<String,JPanel> | getTabs() Returns the tabs to be added in JConsole window.
abstract SwingWorker<?,?> | newSwingWorker() Returns a SwingWorker to perform the GUI update for this plugin at the same interval as JConsole updates the GUI.
void | removeContextPropertyChangeListener(PropertyChangeListener listener) Removes a PropertyChangeListener from the listener list of the JConsoleContext object for this plugin.
void | setContext(JConsoleContext context) Sets the JConsoleContext object representing the connection to an application.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JConsolePlugin

protected JConsolePlugin()
Constructor.

Method Detail

setContext

public final void setContext(JConsoleContext context)
Sets the JConsoleContext object representing the connection to an application. This method will be called only once after the plugin is created and before the getTabs() is called. The given context can be in any connection state when this method is called.

Parameters:
context - a JConsoleContext object

getContext

public final JConsoleContext getContext()
Returns the JConsoleContext object representing the connection to an application. This method may return null if it is called before the context is initialized.

Returns:
the JConsoleContext object representing the connection to an application.

getTabs

public abstract Map<String,JPanel> getTabs()
Returns the tabs to be added in JConsole window.

The returned map contains one entry for each tab to be added in the tabbed pane in a JConsole window with the tab name as the key and the JPanel object as the value. This method returns an empty map if no tab is added by this plugin. This method will be called from the Event Dispatch Thread once at the new connection time.

Returns:
a map of a tab name and a JPanel object representing the tabs to be added in the JConsole window; or an empty map.

newSwingWorker

public abstract SwingWorker<?,?> newSwingWorker()
Returns a SwingWorker to perform the GUI update for this plugin at the same interval as JConsole updates the GUI.

JConsole schedules the GUI update at an interval specified for a connection. This method will be called at every update to obtain a SwingWorker for each plugin.

JConsole will invoke the execute() method to schedule the returned SwingWorker for execution if:

  • the SwingWorker object has not been executed (i.e. the SwingWorker.getState() method returns PENDING state); and
  • the SwingWorker object returned in the previous update has completed the task if it was not null (i.e. the SwingWorker.isDone method returns true).

Otherwise, SwingWorker object will not be scheduled to work.

A plugin can schedule its own GUI update and this method will return null.

Returns:
a SwingWorker to perform the GUI update; or null.

dispose

public void dispose()
Dispose this plugin. This method is called by JConsole to inform that this plugin will be discarded and that it should free any resources that it has allocated. The JConsoleContext can be in any connection state when this method is called.

addContextPropertyChangeListener

public final void addContextPropertyChangeListener(PropertyChangeListener listener)
Adds a PropertyChangeListener to the JConsoleContext object for this plugin. This method is a convenient method for this plugin to register a listener when the JConsoleContext object may or may not be available.

For example, a plugin constructor can call this method to register a listener to listen to the connectionState property changes and the listener will be added to the JConsoleContext object when it is available.

Parameters:
listener - The PropertyChangeListener to be added
Throws:
NullPointerException - if listener is null.

removeContextPropertyChangeListener

public final void removeContextPropertyChangeListener(PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list of the JConsoleContext object for this plugin. If listener was never added, no exception is thrown and no action is taken.

Parameters:
listener - the PropertyChangeListener to be removed
Throws:
NullPointerException - if listener is null.
Package Class Use Tree Index Help
JConsole API
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


jdi

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Java™ Debug Interface

The JavaTM Debug Interface (JDI) is a high level Java API providing information useful for debuggers and similiar systems needing access to the running state of a (usually remote) virtual machine.

See:
Description

Packages
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.connect | This package defines connections between the virtual machine using the JDI and the target virtual machine.
com.sun.jdi.connect.spi | This package comprises the interfaces and classes used to develop new TransportService implementations.
com.sun.jdi.event | This package defines JDI events and event processing.
com.sun.jdi.request | This package is used to request that a JDI event be sent under specified conditions.

The JavaTM Debug Interface (JDI) is a high level Java API providing information useful for debuggers and similiar systems needing access to the running state of a (usually remote) virtual machine.

The JDI provides introspective access to a running virtual machine's state, Class, Array, Interface, and primitive types, and instances of those types.

The JDI also provides explicit control over a virtual machine's execution. The ability to suspend and resume threads, and to set breakpoints, watchpoints, ... Notification of exceptions, class loading, thread creation... The ability to inspect a suspended thread's state, local variables, stack backtrace...

JDI is the highest-layer of the Java Platform Debugger Architecture (JPDA). For more information on the Java Platform Debugger Architecture, see the Java Platform Debugger Architecture documentation for this release and the Java Platform Debugger Architecture website.

Global Exceptions:

This section documents exceptions which apply to the entire API and are thus not documented on individual methods.

VMMismatchException

Any method on a Mirror that takes a Mirror as an parameter directly or indirectly (e.g., as a element in a List) will throw VMMismatchException if the mirrors are from different virtual machines.

NullPointerException

Any method which takes a Object as an parameter will throw NullPointerException if null is passed directly or indirectly -- unless null is explicitly mentioned as a valid parameter.

NOTE: The exceptions below may be thrown whenever the specified conditions are met but a guarantee that they are thrown only exists when a valid result cannot be returned.

VMDisconnectedException

Any method on ObjectReference, ReferenceType, EventRequest, StackFrame, or VirtualMachine or which takes one of these directly or indirectly as an parameter may throw VMDisconnectedException if the target VM is disconnected and the VMDisconnectEvent has been or is available to be read from the EventQueue.

VMOutOfMemoryException

Any method on ObjectReference, ReferenceType, EventRequest, StackFrame, or VirtualMachine or which takes one of these directly or indirectly as an parameter may throw VMOutOfMemoryException if the target VM has run out of memory.

ObjectCollectedException

Any method on ObjectReference or which directly or indirectly takes ObjectReference as parameter may throw ObjectCollectedException if the mirrored object has been garbage collected.

Any method on ReferenceType or which directly or indirectly takes ReferenceType as parameter may throw ObjectCollectedException if the mirrored type has been unloaded.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


 All Classes
AbsentInformationException
Accessible
AccessWatchpointEvent
AccessWatchpointRequest
ArrayReference
ArrayType
AttachingConnector
BooleanType
BooleanValue
Bootstrap
BreakpointEvent
BreakpointRequest
ByteType
ByteValue
CharType
CharValue
ClassLoaderReference
ClassNotLoadedException
ClassNotPreparedException
ClassObjectReference
ClassPrepareEvent
ClassPrepareRequest
ClassType
ClassUnloadEvent
ClassUnloadRequest
ClosedConnectionException
Connection
Connector
Connector.Argument
Connector.BooleanArgument
Connector.IntegerArgument
Connector.SelectedArgument
Connector.StringArgument
DoubleType
DoubleValue
DuplicateRequestException
Event
EventIterator
EventQueue
EventRequest
EventRequestManager
EventSet
ExceptionEvent
ExceptionRequest
Field
FloatType
FloatValue
IllegalConnectorArgumentsException
IncompatibleThreadStateException
InconsistentDebugInfoException
IntegerType
IntegerValue
InterfaceType
InternalException
InvalidCodeIndexException
InvalidLineNumberException
InvalidRequestStateException
InvalidStackFrameException
InvalidTypeException
InvocationException
JDIPermission
LaunchingConnector
ListeningConnector
LocalVariable
Locatable
LocatableEvent
Location
LongType
LongValue
Method
MethodEntryEvent
MethodEntryRequest
MethodExitEvent
MethodExitRequest
Mirror
ModificationWatchpointEvent
ModificationWatchpointRequest
MonitorContendedEnteredEvent
MonitorContendedEnteredRequest
MonitorContendedEnterEvent
MonitorContendedEnterRequest
MonitorInfo
MonitorWaitedEvent
MonitorWaitedRequest
MonitorWaitEvent
MonitorWaitRequest
NativeMethodException
ObjectCollectedException
ObjectReference
PathSearchingVirtualMachine
PrimitiveType
PrimitiveValue
ReferenceType
ShortType
ShortValue
StackFrame
StepEvent
StepRequest
StringReference
ThreadDeathEvent
ThreadDeathRequest
ThreadGroupReference
ThreadReference
ThreadStartEvent
ThreadStartRequest
Transport
TransportService
TransportService.Capabilities
TransportService.ListenKey
TransportTimeoutException
Type
TypeComponent
Value
VirtualMachine
VirtualMachineManager
VMCannotBeModifiedException
VMDeathEvent
VMDeathRequest
VMDisconnectedException
VMDisconnectEvent
VMMismatchException
VMOutOfMemoryException
VMStartEvent
VMStartException
VoidType
VoidValue
WatchpointEvent
WatchpointRequest


API Help

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

How This API Document Is Organized

This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.

Overview

The Overview page is the front page of this API document and provides a list of all packages with a summary for each. This page can also contain an overall description of the set of packages.

Package

Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain four categories:

  • Interfaces (italic)
  • Classes
  • Enums
  • Exceptions
  • Errors
  • Annotation Types

Class/Interface

Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:

  • Class inheritance diagram
  • Direct Subclasses
  • All Known Subinterfaces
  • All Known Implementing Classes
  • Class/interface declaration
  • Class/interface description

  • Nested Class Summary
  • Field Summary
  • Constructor Summary
  • Method Summary

  • Field Detail
  • Constructor Detail
  • Method Detail
Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.

Annotation Type

Each annotation type has its own separate page with the following sections:

  • Annotation Type declaration
  • Annotation Type description
  • Required Element Summary
  • Optional Element Summary
  • Element Detail

Enum

Each enum has its own separate page with the following sections:

  • Enum declaration
  • Enum description
  • Enum Constant Summary
  • Enum Constant Detail

Use

Each documented package, class and interface has its own Use page. This page describes what packages, classes, methods, constructors and fields use any part of the given class or package. Given a class or interface A, its Use page includes subclasses of A, fields declared as A, methods that return A, and methods and constructors with parameters of type A. You can access this page by first going to the package, class or interface, then clicking on the "Use" link in the navigation bar.

Tree (Class Hierarchy)

There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with java.lang.Object. The interfaces do not inherit from java.lang.Object.
  • When viewing the Overview page, clicking on "Tree" displays the hierarchy for all packages.
  • When viewing a particular package, class or interface page, clicking "Tree" displays the hierarchy for only that package.

Index

The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.

Prev/Next

These links take you to the next or previous class, interface, package, or related page.

Frames/No Frames

These links show and hide the HTML frames. All pages are available with or without frames.

Serialized Form

Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.

Constant Field Values

The Constant Field Values page lists the static final fields and their values.

This help file applies to API documentation generated using the standard doclet.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Constant Field Values

Contents
  • com.sun.*
com.sun.*

com.sun.jdi.ClassType
public static final int INVOKE_SINGLE_THREADED 1

com.sun.jdi.ObjectReference
public static final int | INVOKE_NONVIRTUAL | 2
public static final int | INVOKE_SINGLE_THREADED | 1

com.sun.jdi.ThreadReference
public static final int | THREAD_STATUS_MONITOR | 3
public static final int | THREAD_STATUS_NOT_STARTED | 5
public static final int | THREAD_STATUS_RUNNING | 1
public static final int | THREAD_STATUS_SLEEPING | 2
public static final int | THREAD_STATUS_UNKNOWN | -1
public static final int | THREAD_STATUS_WAIT | 4
public static final int | THREAD_STATUS_ZOMBIE | 0

com.sun.jdi.VirtualMachine
public static final int | TRACE_ALL | 16777215
public static final int | TRACE_EVENTS | 4
public static final int | TRACE_NONE | 0
public static final int | TRACE_OBJREFS | 16
public static final int | TRACE_RECEIVES | 2
public static final int | TRACE_REFTYPES | 8
public static final int | TRACE_SENDS | 1

com.sun.jdi.request.EventRequest
public static final int | SUSPEND_ALL | 2
public static final int | SUSPEND_EVENT_THREAD | 1
public static final int | SUSPEND_NONE | 0

com.sun.jdi.request.StepRequest
public static final int | STEP_INTO | 1
public static final int | STEP_LINE | -2
public static final int | STEP_MIN | -1
public static final int | STEP_OUT | 3
public static final int | STEP_OVER | 2

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Hierarchy

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Hierarchy For All Packages

Package Hierarchies:
com.sun.jdi, com.sun.jdi.connect, com.sun.jdi.connect.spi, com.sun.jdi.event, com.sun.jdi.request

Class Hierarchy

  • java.lang.Object
    • com.sun.jdi.Bootstrap
    • com.sun.jdi.connect.spi.Connection
    • java.security.Permission (implements java.security.Guard, java.io.Serializable)
      • java.security.BasicPermission (implements java.io.Serializable)
        • com.sun.jdi.JDIPermission
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • com.sun.jdi.AbsentInformationException
        • com.sun.jdi.ClassNotLoadedException
        • com.sun.jdi.connect.IllegalConnectorArgumentsException
        • com.sun.jdi.IncompatibleThreadStateException
        • com.sun.jdi.InvalidTypeException
        • com.sun.jdi.InvocationException
        • java.io.IOException
          • com.sun.jdi.connect.spi.ClosedConnectionException
          • com.sun.jdi.connect.TransportTimeoutException
        • java.lang.RuntimeException
          • com.sun.jdi.ClassNotPreparedException
          • com.sun.jdi.request.DuplicateRequestException
          • com.sun.jdi.InconsistentDebugInfoException
          • com.sun.jdi.InternalException
          • com.sun.jdi.InvalidCodeIndexException
          • com.sun.jdi.InvalidLineNumberException
          • com.sun.jdi.request.InvalidRequestStateException
          • com.sun.jdi.InvalidStackFrameException
          • com.sun.jdi.NativeMethodException
          • com.sun.jdi.ObjectCollectedException
          • java.lang.UnsupportedOperationException
            • com.sun.jdi.VMCannotBeModifiedException
          • com.sun.jdi.VMDisconnectedException
          • com.sun.jdi.VMMismatchException
          • com.sun.jdi.VMOutOfMemoryException
        • com.sun.jdi.connect.VMStartException
    • com.sun.jdi.connect.spi.TransportService
    • com.sun.jdi.connect.spi.TransportService.Capabilities
    • com.sun.jdi.connect.spi.TransportService.ListenKey

Interface Hierarchy

  • com.sun.jdi.Accessible
    • com.sun.jdi.ArrayType
    • com.sun.jdi.ClassType
    • com.sun.jdi.Field (also extends java.lang.Comparable<T>, com.sun.jdi.TypeComponent)
    • com.sun.jdi.InterfaceType
    • com.sun.jdi.Method (also extends java.lang.Comparable<T>, com.sun.jdi.Locatable, com.sun.jdi.TypeComponent)
    • com.sun.jdi.ReferenceType (also extends java.lang.Comparable<T>, com.sun.jdi.Type)
      • com.sun.jdi.ArrayType
      • com.sun.jdi.ClassType
      • com.sun.jdi.InterfaceType
    • com.sun.jdi.TypeComponent (also extends com.sun.jdi.Mirror)
      • com.sun.jdi.Field (also extends java.lang.Comparable<T>)
      • com.sun.jdi.Method (also extends java.lang.Comparable<T>, com.sun.jdi.Locatable)
  • java.lang.Comparable<T>
    • com.sun.jdi.ArrayType
    • com.sun.jdi.ByteValue (also extends com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.CharValue (also extends com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.ClassType
    • com.sun.jdi.DoubleValue (also extends com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.Field (also extends com.sun.jdi.TypeComponent)
    • com.sun.jdi.FloatValue (also extends com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.IntegerValue (also extends com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.InterfaceType
    • com.sun.jdi.LocalVariable (also extends com.sun.jdi.Mirror)
    • com.sun.jdi.Location (also extends com.sun.jdi.Mirror)
    • com.sun.jdi.LongValue (also extends com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.Method (also extends com.sun.jdi.Locatable, com.sun.jdi.TypeComponent)
    • com.sun.jdi.ReferenceType (also extends com.sun.jdi.Accessible, com.sun.jdi.Type)
      • com.sun.jdi.ArrayType
      • com.sun.jdi.ClassType
      • com.sun.jdi.InterfaceType
    • com.sun.jdi.ShortValue (also extends com.sun.jdi.PrimitiveValue)
  • com.sun.jdi.connect.Connector
    • com.sun.jdi.connect.AttachingConnector
    • com.sun.jdi.connect.LaunchingConnector
    • com.sun.jdi.connect.ListeningConnector
  • java.lang.Iterable<T>
    • java.util.Collection<E>
      • com.sun.jdi.event.EventSet (also extends com.sun.jdi.Mirror, java.util.Set<E>)
      • java.util.Set<E>
        • com.sun.jdi.event.EventSet (also extends com.sun.jdi.Mirror)
    • com.sun.jdi.event.EventSet (also extends com.sun.jdi.Mirror, java.util.Set<E>)
    • java.util.Set<E>
      • com.sun.jdi.event.EventSet (also extends com.sun.jdi.Mirror)
  • java.util.Iterator<E>
    • com.sun.jdi.event.EventIterator
  • com.sun.jdi.Locatable
    • com.sun.jdi.event.AccessWatchpointEvent
    • com.sun.jdi.event.BreakpointEvent
    • com.sun.jdi.request.BreakpointRequest (also extends com.sun.jdi.request.EventRequest)
    • com.sun.jdi.event.ExceptionEvent
    • com.sun.jdi.event.LocatableEvent (also extends com.sun.jdi.event.Event)
      • com.sun.jdi.event.AccessWatchpointEvent
      • com.sun.jdi.event.BreakpointEvent
      • com.sun.jdi.event.ExceptionEvent
      • com.sun.jdi.event.MethodEntryEvent
      • com.sun.jdi.event.MethodExitEvent
      • com.sun.jdi.event.ModificationWatchpointEvent
      • com.sun.jdi.event.MonitorContendedEnteredEvent
      • com.sun.jdi.event.MonitorContendedEnterEvent
      • com.sun.jdi.event.MonitorWaitedEvent
      • com.sun.jdi.event.MonitorWaitEvent
      • com.sun.jdi.event.StepEvent
      • com.sun.jdi.event.WatchpointEvent
        • com.sun.jdi.event.AccessWatchpointEvent
        • com.sun.jdi.event.ModificationWatchpointEvent
    • com.sun.jdi.Method (also extends java.lang.Comparable<T>, com.sun.jdi.TypeComponent)
    • com.sun.jdi.event.MethodEntryEvent
    • com.sun.jdi.event.MethodExitEvent
    • com.sun.jdi.event.ModificationWatchpointEvent
    • com.sun.jdi.event.MonitorContendedEnteredEvent
    • com.sun.jdi.event.MonitorContendedEnterEvent
    • com.sun.jdi.event.MonitorWaitedEvent
    • com.sun.jdi.event.MonitorWaitEvent
    • com.sun.jdi.StackFrame (also extends com.sun.jdi.Mirror)
    • com.sun.jdi.event.StepEvent
    • com.sun.jdi.event.WatchpointEvent
      • com.sun.jdi.event.AccessWatchpointEvent
      • com.sun.jdi.event.ModificationWatchpointEvent
  • com.sun.jdi.Mirror
    • com.sun.jdi.event.AccessWatchpointEvent
    • com.sun.jdi.request.AccessWatchpointRequest
    • com.sun.jdi.ArrayReference
    • com.sun.jdi.ArrayType
    • com.sun.jdi.BooleanType
    • com.sun.jdi.BooleanValue
    • com.sun.jdi.event.BreakpointEvent
    • com.sun.jdi.request.BreakpointRequest (also extends com.sun.jdi.request.EventRequest, com.sun.jdi.Locatable)
    • com.sun.jdi.ByteType
    • com.sun.jdi.ByteValue (also extends java.lang.Comparable<T>, com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.CharType
    • com.sun.jdi.CharValue (also extends java.lang.Comparable<T>, com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.ClassLoaderReference
    • com.sun.jdi.ClassObjectReference
    • com.sun.jdi.event.ClassPrepareEvent
    • com.sun.jdi.request.ClassPrepareRequest
    • com.sun.jdi.ClassType
    • com.sun.jdi.event.ClassUnloadEvent
    • com.sun.jdi.request.ClassUnloadRequest
    • com.sun.jdi.DoubleType
    • com.sun.jdi.DoubleValue (also extends java.lang.Comparable<T>, com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.event.Event
      • com.sun.jdi.event.AccessWatchpointEvent
      • com.sun.jdi.event.BreakpointEvent
      • com.sun.jdi.event.ClassPrepareEvent
      • com.sun.jdi.event.ClassUnloadEvent
      • com.sun.jdi.event.ExceptionEvent
      • com.sun.jdi.event.LocatableEvent (also extends com.sun.jdi.Locatable)
        • com.sun.jdi.event.AccessWatchpointEvent
        • com.sun.jdi.event.BreakpointEvent
        • com.sun.jdi.event.ExceptionEvent
        • com.sun.jdi.event.MethodEntryEvent
        • com.sun.jdi.event.MethodExitEvent
        • com.sun.jdi.event.ModificationWatchpointEvent
        • com.sun.jdi.event.MonitorContendedEnteredEvent
        • com.sun.jdi.event.MonitorContendedEnterEvent
        • com.sun.jdi.event.MonitorWaitedEvent
        • com.sun.jdi.event.MonitorWaitEvent
        • com.sun.jdi.event.StepEvent
        • com.sun.jdi.event.WatchpointEvent
          • com.sun.jdi.event.AccessWatchpointEvent
          • com.sun.jdi.event.ModificationWatchpointEvent
      • com.sun.jdi.event.MethodEntryEvent
      • com.sun.jdi.event.MethodExitEvent
      • com.sun.jdi.event.ModificationWatchpointEvent
      • com.sun.jdi.event.MonitorContendedEnteredEvent
      • com.sun.jdi.event.MonitorContendedEnterEvent
      • com.sun.jdi.event.MonitorWaitedEvent
      • com.sun.jdi.event.MonitorWaitEvent
      • com.sun.jdi.event.StepEvent
      • com.sun.jdi.event.ThreadDeathEvent
      • com.sun.jdi.event.ThreadStartEvent
      • com.sun.jdi.event.VMDeathEvent
      • com.sun.jdi.event.VMDisconnectEvent
      • com.sun.jdi.event.VMStartEvent
      • com.sun.jdi.event.WatchpointEvent
        • com.sun.jdi.event.AccessWatchpointEvent
        • com.sun.jdi.event.ModificationWatchpointEvent
    • com.sun.jdi.event.EventQueue
    • com.sun.jdi.request.EventRequest
      • com.sun.jdi.request.AccessWatchpointRequest
      • com.sun.jdi.request.BreakpointRequest (also extends com.sun.jdi.Locatable)
      • com.sun.jdi.request.ClassPrepareRequest
      • com.sun.jdi.request.ClassUnloadRequest
      • com.sun.jdi.request.ExceptionRequest
      • com.sun.jdi.request.MethodEntryRequest
      • com.sun.jdi.request.MethodExitRequest
      • com.sun.jdi.request.ModificationWatchpointRequest
      • com.sun.jdi.request.MonitorContendedEnteredRequest
      • com.sun.jdi.request.MonitorContendedEnterRequest
      • com.sun.jdi.request.MonitorWaitedRequest
      • com.sun.jdi.request.MonitorWaitRequest
      • com.sun.jdi.request.StepRequest
      • com.sun.jdi.request.ThreadDeathRequest
      • com.sun.jdi.request.ThreadStartRequest
      • com.sun.jdi.request.VMDeathRequest
      • com.sun.jdi.request.WatchpointRequest
        • com.sun.jdi.request.AccessWatchpointRequest
        • com.sun.jdi.request.ModificationWatchpointRequest
    • com.sun.jdi.request.EventRequestManager
    • com.sun.jdi.event.EventSet (also extends java.util.Set<E>)
    • com.sun.jdi.event.ExceptionEvent
    • com.sun.jdi.request.ExceptionRequest
    • com.sun.jdi.Field (also extends java.lang.Comparable<T>, com.sun.jdi.TypeComponent)
    • com.sun.jdi.FloatType
    • com.sun.jdi.FloatValue (also extends java.lang.Comparable<T>, com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.IntegerType
    • com.sun.jdi.IntegerValue (also extends java.lang.Comparable<T>, com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.InterfaceType
    • com.sun.jdi.LocalVariable (also extends java.lang.Comparable<T>)
    • com.sun.jdi.event.LocatableEvent (also extends com.sun.jdi.event.Event, com.sun.jdi.Locatable)
      • com.sun.jdi.event.AccessWatchpointEvent
      • com.sun.jdi.event.BreakpointEvent
      • com.sun.jdi.event.ExceptionEvent
      • com.sun.jdi.event.MethodEntryEvent
      • com.sun.jdi.event.MethodExitEvent
      • com.sun.jdi.event.ModificationWatchpointEvent
      • com.sun.jdi.event.MonitorContendedEnteredEvent
      • com.sun.jdi.event.MonitorContendedEnterEvent
      • com.sun.jdi.event.MonitorWaitedEvent
      • com.sun.jdi.event.MonitorWaitEvent
      • com.sun.jdi.event.StepEvent
      • com.sun.jdi.event.WatchpointEvent
        • com.sun.jdi.event.AccessWatchpointEvent
        • com.sun.jdi.event.ModificationWatchpointEvent
    • com.sun.jdi.Location (also extends java.lang.Comparable<T>)
    • com.sun.jdi.LongType
    • com.sun.jdi.LongValue (also extends java.lang.Comparable<T>, com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.Method (also extends java.lang.Comparable<T>, com.sun.jdi.Locatable, com.sun.jdi.TypeComponent)
    • com.sun.jdi.event.MethodEntryEvent
    • com.sun.jdi.request.MethodEntryRequest
    • com.sun.jdi.event.MethodExitEvent
    • com.sun.jdi.request.MethodExitRequest
    • com.sun.jdi.event.ModificationWatchpointEvent
    • com.sun.jdi.request.ModificationWatchpointRequest
    • com.sun.jdi.event.MonitorContendedEnteredEvent
    • com.sun.jdi.request.MonitorContendedEnteredRequest
    • com.sun.jdi.event.MonitorContendedEnterEvent
    • com.sun.jdi.request.MonitorContendedEnterRequest
    • com.sun.jdi.MonitorInfo
    • com.sun.jdi.event.MonitorWaitedEvent
    • com.sun.jdi.request.MonitorWaitedRequest
    • com.sun.jdi.event.MonitorWaitEvent
    • com.sun.jdi.request.MonitorWaitRequest
    • com.sun.jdi.ObjectReference
      • com.sun.jdi.ArrayReference
      • com.sun.jdi.ClassLoaderReference
      • com.sun.jdi.ClassObjectReference
      • com.sun.jdi.StringReference
      • com.sun.jdi.ThreadGroupReference
      • com.sun.jdi.ThreadReference
    • com.sun.jdi.PathSearchingVirtualMachine
    • com.sun.jdi.PrimitiveType
      • com.sun.jdi.BooleanType
      • com.sun.jdi.ByteType
      • com.sun.jdi.CharType
      • com.sun.jdi.DoubleType
      • com.sun.jdi.FloatType
      • com.sun.jdi.IntegerType
      • com.sun.jdi.LongType
      • com.sun.jdi.ShortType
    • com.sun.jdi.PrimitiveValue
      • com.sun.jdi.BooleanValue
      • com.sun.jdi.ByteValue (also extends java.lang.Comparable<T>)
      • com.sun.jdi.CharValue (also extends java.lang.Comparable<T>)
      • com.sun.jdi.DoubleValue (also extends java.lang.Comparable<T>)
      • com.sun.jdi.FloatValue (also extends java.lang.Comparable<T>)
      • com.sun.jdi.IntegerValue (also extends java.lang.Comparable<T>)
      • com.sun.jdi.LongValue (also extends java.lang.Comparable<T>)
      • com.sun.jdi.ShortValue (also extends java.lang.Comparable<T>)
    • com.sun.jdi.ReferenceType (also extends com.sun.jdi.Accessible, java.lang.Comparable<T>, com.sun.jdi.Type)
      • com.sun.jdi.ArrayType
      • com.sun.jdi.ClassType
      • com.sun.jdi.InterfaceType
    • com.sun.jdi.ShortType
    • com.sun.jdi.ShortValue (also extends java.lang.Comparable<T>, com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.StackFrame (also extends com.sun.jdi.Locatable)
    • com.sun.jdi.event.StepEvent
    • com.sun.jdi.request.StepRequest
    • com.sun.jdi.StringReference
    • com.sun.jdi.event.ThreadDeathEvent
    • com.sun.jdi.request.ThreadDeathRequest
    • com.sun.jdi.ThreadGroupReference
    • com.sun.jdi.ThreadReference
    • com.sun.jdi.event.ThreadStartEvent
    • com.sun.jdi.request.ThreadStartRequest
    • com.sun.jdi.Type
      • com.sun.jdi.ArrayType
      • com.sun.jdi.BooleanType
      • com.sun.jdi.ByteType
      • com.sun.jdi.CharType
      • com.sun.jdi.ClassType
      • com.sun.jdi.DoubleType
      • com.sun.jdi.FloatType
      • com.sun.jdi.IntegerType
      • com.sun.jdi.InterfaceType
      • com.sun.jdi.LongType
      • com.sun.jdi.PrimitiveType
        • com.sun.jdi.BooleanType
        • com.sun.jdi.ByteType
        • com.sun.jdi.CharType
        • com.sun.jdi.DoubleType
        • com.sun.jdi.FloatType
        • com.sun.jdi.IntegerType
        • com.sun.jdi.LongType
        • com.sun.jdi.ShortType
      • com.sun.jdi.ReferenceType (also extends com.sun.jdi.Accessible, java.lang.Comparable<T>)
        • com.sun.jdi.ArrayType
        • com.sun.jdi.ClassType
        • com.sun.jdi.InterfaceType
      • com.sun.jdi.ShortType
      • com.sun.jdi.VoidType
    • com.sun.jdi.TypeComponent (also extends com.sun.jdi.Accessible)
      • com.sun.jdi.Field (also extends java.lang.Comparable<T>)
      • com.sun.jdi.Method (also extends java.lang.Comparable<T>, com.sun.jdi.Locatable)
    • com.sun.jdi.Value
      • com.sun.jdi.ArrayReference
      • com.sun.jdi.BooleanValue
      • com.sun.jdi.ByteValue (also extends java.lang.Comparable<T>, com.sun.jdi.PrimitiveValue)
      • com.sun.jdi.CharValue (also extends java.lang.Comparable<T>, com.sun.jdi.PrimitiveValue)
      • com.sun.jdi.ClassLoaderReference
      • com.sun.jdi.ClassObjectReference
      • com.sun.jdi.DoubleValue (also extends java.lang.Comparable<T>, com.sun.jdi.PrimitiveValue)
      • com.sun.jdi.FloatValue (also extends java.lang.Comparable<T>, com.sun.jdi.PrimitiveValue)
      • com.sun.jdi.IntegerValue (also extends java.lang.Comparable<T>, com.sun.jdi.PrimitiveValue)
      • com.sun.jdi.LongValue (also extends java.lang.Comparable<T>, com.sun.jdi.PrimitiveValue)
      • com.sun.jdi.ObjectReference
        • com.sun.jdi.ArrayReference
        • com.sun.jdi.ClassLoaderReference
        • com.sun.jdi.ClassObjectReference
        • com.sun.jdi.StringReference
        • com.sun.jdi.ThreadGroupReference
        • com.sun.jdi.ThreadReference
      • com.sun.jdi.PrimitiveValue
        • com.sun.jdi.BooleanValue
        • com.sun.jdi.ByteValue (also extends java.lang.Comparable<T>)
        • com.sun.jdi.CharValue (also extends java.lang.Comparable<T>)
        • com.sun.jdi.DoubleValue (also extends java.lang.Comparable<T>)
        • com.sun.jdi.FloatValue (also extends java.lang.Comparable<T>)
        • com.sun.jdi.IntegerValue (also extends java.lang.Comparable<T>)
        • com.sun.jdi.LongValue (also extends java.lang.Comparable<T>)
        • com.sun.jdi.ShortValue (also extends java.lang.Comparable<T>)
      • com.sun.jdi.ShortValue (also extends java.lang.Comparable<T>, com.sun.jdi.PrimitiveValue)
      • com.sun.jdi.StringReference
      • com.sun.jdi.ThreadGroupReference
      • com.sun.jdi.ThreadReference
      • com.sun.jdi.VoidValue
    • com.sun.jdi.VirtualMachine
      • com.sun.jdi.PathSearchingVirtualMachine
    • com.sun.jdi.event.VMDeathEvent
    • com.sun.jdi.request.VMDeathRequest
    • com.sun.jdi.event.VMDisconnectEvent
    • com.sun.jdi.event.VMStartEvent
    • com.sun.jdi.VoidType
    • com.sun.jdi.VoidValue
    • com.sun.jdi.event.WatchpointEvent
      • com.sun.jdi.event.AccessWatchpointEvent
      • com.sun.jdi.event.ModificationWatchpointEvent
    • com.sun.jdi.request.WatchpointRequest
      • com.sun.jdi.request.AccessWatchpointRequest
      • com.sun.jdi.request.ModificationWatchpointRequest
  • java.io.Serializable
    • com.sun.jdi.connect.Connector.Argument
      • com.sun.jdi.connect.Connector.BooleanArgument
      • com.sun.jdi.connect.Connector.IntegerArgument
      • com.sun.jdi.connect.Connector.SelectedArgument
      • com.sun.jdi.connect.Connector.StringArgument
    • com.sun.jdi.connect.Connector.BooleanArgument
    • com.sun.jdi.connect.Connector.IntegerArgument
    • com.sun.jdi.connect.Connector.SelectedArgument
    • com.sun.jdi.connect.Connector.StringArgument
  • com.sun.jdi.connect.Transport
  • com.sun.jdi.VirtualMachineManager
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Index

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES
A B C D E F G H I J L M N O P R S T U V W

A

AbsentInformationException - Exception in com.sun.jdi
Thrown to indicate line number or variable information is not available.
AbsentInformationException() - Constructor for exception com.sun.jdi.AbsentInformationException
AbsentInformationException(String) - Constructor for exception com.sun.jdi.AbsentInformationException
accept(Map<String, ? extends Connector.Argument>) - Method in interface com.sun.jdi.connect.ListeningConnector
Waits for a target VM to attach to this connector.
accept(TransportService.ListenKey, long, long) - Method in class com.sun.jdi.connect.spi.TransportService
Accept a connection from a target VM.
Accessible - Interface in com.sun.jdi
Provides information on the accessibility of a type or type component.
AccessWatchpointEvent - Interface in com.sun.jdi.event
Notification of a field access in the target VM.
AccessWatchpointRequest - Interface in com.sun.jdi.request
Request for notification when the contents of a field are accessed in the target VM.
accessWatchpointRequests() - Method in interface com.sun.jdi.request.EventRequestManager
Return an unmodifiable list of the enabled and disabled access watchpoint requests.
addClassExclusionFilter(String) - Method in interface com.sun.jdi.request.ClassPrepareRequest
Restricts the events generated by this request to the preparation of reference types whose name does not match this restricted regular expression.
addClassExclusionFilter(String) - Method in interface com.sun.jdi.request.ClassUnloadRequest
Restricts the events generated by this request to the unloading of reference types whose name does not match a restricted regular expression.
addClassExclusionFilter(String) - Method in interface com.sun.jdi.request.ExceptionRequest
Restricts the events generated by this request to those whose location is in a class whose name does not match a restricted regular expression.
addClassExclusionFilter(String) - Method in interface com.sun.jdi.request.MethodEntryRequest
Restricts the events generated by this request to those whose method is in a class whose name does not match this restricted regular expression, e.g.
addClassExclusionFilter(String) - Method in interface com.sun.jdi.request.MethodExitRequest
Restricts the events generated by this request to those whose method is in a class whose name does not match this restricted regular expression.
addClassExclusionFilter(String) - Method in interface com.sun.jdi.request.MonitorContendedEnteredRequest
Restricts the events generated by this request to those whose method is in a class whose name does not match this restricted regular expression, e.g.
addClassExclusionFilter(String) - Method in interface com.sun.jdi.request.MonitorContendedEnterRequest
Restricts the events generated by this request to those whose method is in a class whose name does not match this restricted regular expression, e.g.
addClassExclusionFilter(String) - Method in interface com.sun.jdi.request.MonitorWaitedRequest
Restricts the events generated by this request to those in which the name of the class of the monitor object does notmatch this restricted regular expression, e.g.
addClassExclusionFilter(String) - Method in interface com.sun.jdi.request.MonitorWaitRequest
Restricts the events generated by this request to those in which the name of the class of the monitor object does notmatch this restricted regular expression, e.g.
addClassExclusionFilter(String) - Method in interface com.sun.jdi.request.StepRequest
Restricts the events generated by this request to those whose location is in a class whose name does not match a restricted regular expression.
addClassExclusionFilter(String) - Method in interface com.sun.jdi.request.WatchpointRequest
Restricts the events generated by this request to those whose location is in a class whose name does not match this restricted regular expression.
addClassFilter(ReferenceType) - Method in interface com.sun.jdi.request.ClassPrepareRequest
Restricts the events generated by this request to be the preparation of the given reference type and any subtypes.
addClassFilter(String) - Method in interface com.sun.jdi.request.ClassPrepareRequest
Restricts the events generated by this request to the preparation of reference types whose name matches this restricted regular expression.
addClassFilter(String) - Method in interface com.sun.jdi.request.ClassUnloadRequest
Restricts the events generated by this request to the unloading of reference types whose name matches a restricted regular expression.
addClassFilter(ReferenceType) - Method in interface com.sun.jdi.request.ExceptionRequest
Restricts the events generated by this request to those whose location is in the given reference type or any of its subtypes.
addClassFilter(String) - Method in interface com.sun.jdi.request.ExceptionRequest
Restricts the events generated by this request to those whose location is in a class whose name matches a restricted regular expression.
addClassFilter(ReferenceType) - Method in interface com.sun.jdi.request.MethodEntryRequest
Restricts the events generated by this request to those whose method is in the given reference type or any of its subtypes.
addClassFilter(String) - Method in interface com.sun.jdi.request.MethodEntryRequest
Restricts the events generated by this request to those whose method is in a class whose name matches this restricted regular expression.
addClassFilter(ReferenceType) - Method in interface com.sun.jdi.request.MethodExitRequest
Restricts the events generated by this request to those whose method is in the given reference type or any of its subtypes.
addClassFilter(String) - Method in interface com.sun.jdi.request.MethodExitRequest
Restricts the events generated by this request to those whose method is in a class whose name matches a restricted regular expression.
addClassFilter(ReferenceType) - Method in interface com.sun.jdi.request.MonitorContendedEnteredRequest
Restricts the events generated by this request to those whose method is in the given reference type or any of its subtypes.
addClassFilter(String) - Method in interface com.sun.jdi.request.MonitorContendedEnteredRequest
Restricts the events generated by this request to those whose method is in a class whose name matches this restricted regular expression.
addClassFilter(ReferenceType) - Method in interface com.sun.jdi.request.MonitorContendedEnterRequest
Restricts the events generated by this request to those whose method is in the given reference type or any of its subtypes.
addClassFilter(String) - Method in interface com.sun.jdi.request.MonitorContendedEnterRequest
Restricts the events generated by this request to those whose method is in a class whose name matches this restricted regular expression.
addClassFilter(ReferenceType) - Method in interface com.sun.jdi.request.MonitorWaitedRequest
Restricts the events generated by this request to those whose monitor object is of the given reference type or any of its subtypes.
addClassFilter(String) - Method in interface com.sun.jdi.request.MonitorWaitedRequest
Restricts the events generated by this request to those in which the name of the class of the monitor object matches this restricted regular expression.
addClassFilter(ReferenceType) - Method in interface com.sun.jdi.request.MonitorWaitRequest
Restricts the events generated by this request to those whose monitor object is of the given reference type or any of its subtypes.
addClassFilter(String) - Method in interface com.sun.jdi.request.MonitorWaitRequest
Restricts the events generated by this request to those in which the name of the class of the monitor object matches this restricted regular expression.
addClassFilter(ReferenceType) - Method in interface com.sun.jdi.request.StepRequest
Restricts the events generated by this request to those whose location is in the given reference type or any of its subtypes.
addClassFilter(String) - Method in interface com.sun.jdi.request.StepRequest
Restricts the events generated by this request to those whose location is in a class whose name matches a restricted regular expression.
addClassFilter(ReferenceType) - Method in interface com.sun.jdi.request.WatchpointRequest
Restricts the events generated by this request to those whose location is in the given reference type or any of its subtypes.
addClassFilter(String) - Method in interface com.sun.jdi.request.WatchpointRequest
Restricts the events generated by this request to those whose location is in a class whose name matches a restricted regular expression.
addCountFilter(int) - Method in interface com.sun.jdi.request.EventRequest
Limit the requested event to be reported at most once after a given number of occurrences.
addInstanceFilter(ObjectReference) - Method in interface com.sun.jdi.request.BreakpointRequest
Restricts the events generated by this request to those in which the currently executing instance is the object specified.
addInstanceFilter(ObjectReference) - Method in interface com.sun.jdi.request.ExceptionRequest
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
addInstanceFilter(ObjectReference) - Method in interface com.sun.jdi.request.MethodEntryRequest
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
addInstanceFilter(ObjectReference) - Method in interface com.sun.jdi.request.MethodExitRequest
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
addInstanceFilter(ObjectReference) - Method in interface com.sun.jdi.request.MonitorContendedEnteredRequest
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
addInstanceFilter(ObjectReference) - Method in interface com.sun.jdi.request.MonitorContendedEnterRequest
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
addInstanceFilter(ObjectReference) - Method in interface com.sun.jdi.request.MonitorWaitedRequest
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
addInstanceFilter(ObjectReference) - Method in interface com.sun.jdi.request.MonitorWaitRequest
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
addInstanceFilter(ObjectReference) - Method in interface com.sun.jdi.request.StepRequest
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
addInstanceFilter(ObjectReference) - Method in interface com.sun.jdi.request.WatchpointRequest
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
address() - Method in class com.sun.jdi.connect.spi.TransportService.ListenKey
Returns a string representation of the listen key.
addSourceNameFilter(String) - Method in interface com.sun.jdi.request.ClassPrepareRequest
Restricts the events generated by this request to the preparation of reference types for which the restricted regular expression 'sourceNamePattern' matches one of the 'sourceNames' for the reference type being prepared.
addThreadFilter(ThreadReference) - Method in interface com.sun.jdi.request.BreakpointRequest
Restricts the events generated by this request to those in the given thread.
addThreadFilter(ThreadReference) - Method in interface com.sun.jdi.request.ExceptionRequest
Restricts the events generated by this request to those in the given thread.
addThreadFilter(ThreadReference) - Method in interface com.sun.jdi.request.MethodEntryRequest
Restricts the events generated by this request to those in the given thread.
addThreadFilter(ThreadReference) - Method in interface com.sun.jdi.request.MethodExitRequest
Restricts the events generated by this request to those in the given thread.
addThreadFilter(ThreadReference) - Method in interface com.sun.jdi.request.MonitorContendedEnteredRequest
Restricts the events generated by this request to those in the given thread.
addThreadFilter(ThreadReference) - Method in interface com.sun.jdi.request.MonitorContendedEnterRequest
Restricts the events generated by this request to those in the given thread.
addThreadFilter(ThreadReference) - Method in interface com.sun.jdi.request.MonitorWaitedRequest
Restricts the events generated by this request to those in the given thread.
addThreadFilter(ThreadReference) - Method in interface com.sun.jdi.request.MonitorWaitRequest
Restricts the events generated by this request to those in the given thread.
addThreadFilter(ThreadReference) - Method in interface com.sun.jdi.request.ThreadDeathRequest
Restricts the events generated by this request to those in the given thread.
addThreadFilter(ThreadReference) - Method in interface com.sun.jdi.request.ThreadStartRequest
Restricts the events generated by this request to those in the given thread.
addThreadFilter(ThreadReference) - Method in interface com.sun.jdi.request.WatchpointRequest
Restricts the events generated by this request to those in the given thread.
allClasses() - Method in interface com.sun.jdi.VirtualMachine
Returns all loaded types.
allConnectors() - Method in interface com.sun.jdi.VirtualMachineManager
Returns the list of all known Connector objects.
allFields() - Method in interface com.sun.jdi.ReferenceType
Returns a list containing each Field declared in this type, and its superclasses, implemented interfaces, and/or superinterfaces.
allInterfaces() - Method in interface com.sun.jdi.ClassType
Gets the interfaces directly and indirectly implemented by this class.
allLineLocations() - Method in interface com.sun.jdi.Method
Returns a list containing a Location object for each executable source line in this method.
allLineLocations(String, String) - Method in interface com.sun.jdi.Method
Returns a list containing a Location object for each executable source line in this method.
allLineLocations() - Method in interface com.sun.jdi.ReferenceType
Returns a list containing a Location object for each executable source line in this reference type.
allLineLocations(String, String) - Method in interface com.sun.jdi.ReferenceType
Returns a list containing a Location object for each executable source line in this reference type.
allMethods() - Method in interface com.sun.jdi.ReferenceType
Returns a list containing each Method declared in this type, and its superclasses, implemented interfaces, and/or superinterfaces.
allThreads() - Method in interface com.sun.jdi.VirtualMachine
Returns a list of the currently running threads.
argumentNames() - Method in exception com.sun.jdi.connect.IllegalConnectorArgumentsException
Return a List containing the names of the invalid or inconsistent arguments.
arguments() - Method in interface com.sun.jdi.Method
Returns a list containing each LocalVariable that is declared as an argument of this method.
argumentTypeNames() - Method in interface com.sun.jdi.Method
Returns a list containing a text representation of the type of each formal parameter of this method.
argumentTypes() - Method in interface com.sun.jdi.Method
Returns a list containing the type of each formal parameter of this method.
ArrayReference - Interface in com.sun.jdi
Provides access to an array object and its components in the target VM.
ArrayType - Interface in com.sun.jdi
Provides access to the class of an array and the type of its components in the target VM.
attach(Map<String, ? extends Connector.Argument>) - Method in interface com.sun.jdi.connect.AttachingConnector
Attaches to a running application and and returns a mirror of its VM.
attach(String, long, long) - Method in class com.sun.jdi.connect.spi.TransportService
Attaches to the specified address.
AttachingConnector - Interface in com.sun.jdi.connect
A connector which attaches to a previously running target VM.
attachingConnectors() - Method in interface com.sun.jdi.VirtualMachineManager
Returns the list of known AttachingConnector objects.
availableStrata() - Method in interface com.sun.jdi.ReferenceType
Return the available strata for this reference type.

B

baseDirectory() - Method in interface com.sun.jdi.PathSearchingVirtualMachine
Get the base directory used for path searching.
BooleanType - Interface in com.sun.jdi
The type of all primitive boolean values accessed in the target VM.
BooleanValue - Interface in com.sun.jdi
Provides access to a primitive boolean value in the target VM.
booleanValue() - Method in interface com.sun.jdi.connect.Connector.BooleanArgument
Return the value of the argument as a boolean.
booleanValue() - Method in interface com.sun.jdi.PrimitiveValue
Converts this value to a BooleanValue and returns the result as a boolean.
bootClassPath() - Method in interface com.sun.jdi.PathSearchingVirtualMachine
Get the boot class path for this virtual machine.
Bootstrap - Class in com.sun.jdi
Initial class that provides access to the default implementation of JDI interfaces.
Bootstrap() - Constructor for class com.sun.jdi.Bootstrap
BreakpointEvent - Interface in com.sun.jdi.event
Notification of a breakpoint in the target VM.
BreakpointRequest - Interface in com.sun.jdi.request
Identifies a Location in the target VM at which execution should be stopped.
breakpointRequests() - Method in interface com.sun.jdi.request.EventRequestManager
Return an unmodifiable list of the enabled and disabled breakpoint requests.
bytecodes() - Method in interface com.sun.jdi.Method
Returns an array containing the bytecodes for this method.
ByteType - Interface in com.sun.jdi
The type of all primitive byte values accessed in the target VM.
ByteValue - Interface in com.sun.jdi
Provides access to a primitive byte value in the target VM.
byteValue() - Method in interface com.sun.jdi.PrimitiveValue
Converts this value to a ByteValue and returns the result as a byte.

C

canAddMethod() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports the addition of methods when performing class redefinition.
canBeModified() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM is a read-only VM.
canForceEarlyReturn() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports the forcing of a method to return early.
canGetBytecodes() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports the retrieval of a method's bytecodes.
canGetClassFileVersion() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports reading class file major and minor versions.
canGetConstantPool() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports getting constant pool information of a class.
canGetCurrentContendedMonitor() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports the retrieval of the monitor for which a thread is currently waiting.
canGetInstanceInfo() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports the accessing of class instances, instance counts, and referring objects.
canGetMethodReturnValues() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports the inclusion of return values in MethodExitEvents.
canGetMonitorFrameInfo() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports getting which frame has acquired a monitor.
canGetMonitorInfo() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports the retrieval of the monitor information for an object.
canGetOwnedMonitorInfo() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports the retrieval of the monitors owned by a thread.
canGetSourceDebugExtension() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports getting the source debug extension.
canGetSyntheticAttribute() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports the query of the synthetic attribute of a method or field.
canPopFrames() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports popping frames of a threads stack.
canRedefineClasses() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports any level of class redefinition.
canRequestMonitorEvents() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports the creation of MonitorContendedEnterRequests.
canRequestVMDeathEvent() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports the creation of VMDeathRequests.
canUnrestrictedlyRedefineClasses() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports unrestricted changes when performing class redefinition.
canUseInstanceFilters() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports filtering events by specific instance object.
canUseSourceNameFilters() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports the filtering of class prepare events by source name.
canWatchFieldAccess() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports watchpoints for field access.
canWatchFieldModification() - Method in interface com.sun.jdi.VirtualMachine
Determines if the target VM supports watchpoints for field modification.
capabilities() - Method in class com.sun.jdi.connect.spi.TransportService
Returns the capabilities of the transport service.
catchLocation() - Method in interface com.sun.jdi.event.ExceptionEvent
Gets the location where the exception will be caught.
CharType - Interface in com.sun.jdi
The type of all primitive char values accessed in the target VM.
CharValue - Interface in com.sun.jdi
Provides access to a primitive char value in the target VM.
charValue() - Method in interface com.sun.jdi.PrimitiveValue
Converts this value to a CharValue and returns the result as a char.
choices() - Method in interface com.sun.jdi.connect.Connector.SelectedArgument
Return the possible values for the argument
classesByName(String) - Method in interface com.sun.jdi.VirtualMachine
Returns the loaded reference types that match a given name.
classLoader() - Method in interface com.sun.jdi.ReferenceType
Gets the classloader object which loaded the class corresponding to this type.
ClassLoaderReference - Interface in com.sun.jdi
A class loader object from the target VM.
className() - Method in exception com.sun.jdi.ClassNotLoadedException
className() - Method in interface com.sun.jdi.event.ClassUnloadEvent
Returns the name of the class that has been unloaded.
ClassNotLoadedException - Exception in com.sun.jdi
Thrown to indicate that the requested class has not yet been loaded through the appropriate class loader.
ClassNotLoadedException(String) - Constructor for exception com.sun.jdi.ClassNotLoadedException
ClassNotLoadedException(String, String) - Constructor for exception com.sun.jdi.ClassNotLoadedException
ClassNotPreparedException - Exception in com.sun.jdi
Thrown to indicate that the requested operation cannot be completed because the specified class has not yet been prepared.
ClassNotPreparedException() - Constructor for exception com.sun.jdi.ClassNotPreparedException
ClassNotPreparedException(String) - Constructor for exception com.sun.jdi.ClassNotPreparedException
classObject() - Method in interface com.sun.jdi.ReferenceType
Returns the class object that corresponds to this type in the target VM.
ClassObjectReference - Interface in com.sun.jdi
An instance of java.lang.Class from the target VM.
classPath() - Method in interface com.sun.jdi.PathSearchingVirtualMachine
Get the class path for this virtual machine.
ClassPrepareEvent - Interface in com.sun.jdi.event
Notification of a class prepare in the target VM.
ClassPrepareRequest - Interface in com.sun.jdi.request
Request for notification when a class is prepared in the target VM.
classPrepareRequests() - Method in interface com.sun.jdi.request.EventRequestManager
Return an unmodifiable list of the enabled and disabled class prepare requests.
classSignature() - Method in interface com.sun.jdi.event.ClassUnloadEvent
Returns the JNI-style signature of the class that has been unloaded.
ClassType - Interface in com.sun.jdi
A mirror of a class in the target VM.
ClassUnloadEvent - Interface in com.sun.jdi.event
Notification of a class unload in the target VM.
ClassUnloadRequest - Interface in com.sun.jdi.request
Request for notification when a class is unloaded in the target VM.
classUnloadRequests() - Method in interface com.sun.jdi.request.EventRequestManager
Return an unmodifiable list of the enabled and disabled class unload requests.
close() - Method in class com.sun.jdi.connect.spi.Connection
Closes this connection.
ClosedConnectionException - Exception in com.sun.jdi.connect.spi
This exception may be thrown as a result of an asynchronous close of a Connection while an I/O operation is in progress.
ClosedConnectionException() - Constructor for exception com.sun.jdi.connect.spi.ClosedConnectionException
Constructs a ClosedConnectionException with no detail message.
ClosedConnectionException(String) - Constructor for exception com.sun.jdi.connect.spi.ClosedConnectionException
Constructs a ClosedConnectionException with the specified detail message.
codeIndex() - Method in interface com.sun.jdi.Location
Gets the code position within this location's method.
com.sun.jdi - package com.sun.jdi
This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.connect - package com.sun.jdi.connect
This package defines connections between the virtual machine using the JDI and the target virtual machine.
com.sun.jdi.connect.spi - package com.sun.jdi.connect.spi
This package comprises the interfaces and classes used to develop new TransportService implementations.
com.sun.jdi.event - package com.sun.jdi.event
This package defines JDI events and event processing.
com.sun.jdi.request - package com.sun.jdi.request
This package is used to request that a JDI event be sent under specified conditions.
componentSignature() - Method in interface com.sun.jdi.ArrayType
Gets the JNI signature of the components of this array class.
componentType() - Method in interface com.sun.jdi.ArrayType
Returns the component type of this array, as specified in the array declaration.
componentTypeName() - Method in interface com.sun.jdi.ArrayType
Returns a text representation of the component type of this array.
concreteMethodByName(String, String) - Method in interface com.sun.jdi.ClassType
Returns a the single non-abstract Method visible from this class that has the given name and signature.
connectedVirtualMachines() - Method in interface com.sun.jdi.VirtualMachineManager
Lists all target VMs which are connected to the debugger.
Connection - Class in com.sun.jdi.connect.spi
A connection between a debugger and a target VM which it debugs.
Connection() - Constructor for class com.sun.jdi.connect.spi.Connection
Connector - Interface in com.sun.jdi.connect
A method of connection between a debugger and a target VM.
Connector.Argument - Interface in com.sun.jdi.connect
Specification for and value of a Connector argument.
Connector.BooleanArgument - Interface in com.sun.jdi.connect
Specification for and value of a Connector argument, whose value is Boolean.
Connector.IntegerArgument - Interface in com.sun.jdi.connect
Specification for and value of a Connector argument, whose value is an integer.
Connector.SelectedArgument - Interface in com.sun.jdi.connect
Specification for and value of a Connector argument, whose value is a String selected from a list of choices.
Connector.StringArgument - Interface in com.sun.jdi.connect
Specification for and value of a Connector argument, whose value is a String.
constantPool() - Method in interface com.sun.jdi.ReferenceType
Returns the raw bytes of the constant pool in the format of the constant_pool item of the Class File Format in the Java Virtual Machine Specification.
constantPoolCount() - Method in interface com.sun.jdi.ReferenceType
Returns the number of entries in the constant pool plus one.
createAccessWatchpointRequest(Field) - Method in interface com.sun.jdi.request.EventRequestManager
Creates a new disabled watchpoint which watches accesses to the specified field.
createBreakpointRequest(Location) - Method in interface com.sun.jdi.request.EventRequestManager
Creates a new disabled BreakpointRequest.
createClassPrepareRequest() - Method in interface com.sun.jdi.request.EventRequestManager
Creates a new disabled ClassPrepareRequest.
createClassUnloadRequest() - Method in interface com.sun.jdi.request.EventRequestManager
Creates a new disabled ClassUnloadRequest.
createExceptionRequest(ReferenceType, boolean, boolean) - Method in interface com.sun.jdi.request.EventRequestManager
Creates a new disabled ExceptionRequest.
createMethodEntryRequest() - Method in interface com.sun.jdi.request.EventRequestManager
Creates a new disabled MethodEntryRequest.
createMethodExitRequest() - Method in interface com.sun.jdi.request.EventRequestManager
Creates a new disabled MethodExitRequest.
createModificationWatchpointRequest(Field) - Method in interface com.sun.jdi.request.EventRequestManager
Creates a new disabled watchpoint which watches accesses to the specified field.
createMonitorContendedEnteredRequest() - Method in interface com.sun.jdi.request.EventRequestManager
Creates a new disabled MonitorContendedEnteredRequest.
createMonitorContendedEnterRequest() - Method in interface com.sun.jdi.request.EventRequestManager
Creates a new disabled MonitorContendedEnterRequest.
createMonitorWaitedRequest() - Method in interface com.sun.jdi.request.EventRequestManager
Creates a new disabled MonitorWaitedRequest.
createMonitorWaitRequest() - Method in interface com.sun.jdi.request.EventRequestManager
Creates a new disabled MonitorWaitRequest.
createStepRequest(ThreadReference, int, int) - Method in interface com.sun.jdi.request.EventRequestManager
Creates a new disabled StepRequest.
createThreadDeathRequest() - Method in interface com.sun.jdi.request.EventRequestManager
Creates a new disabled ThreadDeathRequest.
createThreadStartRequest() - Method in interface com.sun.jdi.request.EventRequestManager
Creates a new disabled ThreadStartRequest.
createVirtualMachine(Connection, Process) - Method in interface com.sun.jdi.VirtualMachineManager
Create a virtual machine mirror for a target VM.
createVirtualMachine(Connection) - Method in interface com.sun.jdi.VirtualMachineManager
Creates a new virtual machine.
createVMDeathRequest() - Method in interface com.sun.jdi.request.EventRequestManager
Creates a new disabled VMDeathRequest.
currentContendedMonitor() - Method in interface com.sun.jdi.ThreadReference
Returns an ObjectReference for the monitor, if any, for which this thread is currently waiting.

D

declaringType() - Method in interface com.sun.jdi.Location
Gets the type to which this Location belongs.
declaringType() - Method in interface com.sun.jdi.TypeComponent
Returns the type in which this component was declared.
defaultArguments() - Method in interface com.sun.jdi.connect.Connector
Returns the arguments accepted by this Connector and their default values.
defaultConnector() - Method in interface com.sun.jdi.VirtualMachineManager
Identifies the default connector.
defaultStratum() - Method in interface com.sun.jdi.ReferenceType
Returns the default stratum for this reference type.
definedClasses() - Method in interface com.sun.jdi.ClassLoaderReference
Returns a list of all loaded classes that were defined by this class loader.
deleteAllBreakpoints() - Method in interface com.sun.jdi.request.EventRequestManager
Remove all breakpoints managed by this EventRequestManager.
deleteEventRequest(EventRequest) - Method in interface com.sun.jdi.request.EventRequestManager
Removes an eventRequest.
deleteEventRequests(List<? extends EventRequest>) - Method in interface com.sun.jdi.request.EventRequestManager
Removes a list of EventRequests.
depth() - Method in interface com.sun.jdi.request.StepRequest
description() - Method in interface com.sun.jdi.connect.Connector.Argument
Returns a human-readable description of this argument and its purpose.
description() - Method in interface com.sun.jdi.connect.Connector
Returns a human-readable description of this connector and its purpose.
description() - Method in class com.sun.jdi.connect.spi.TransportService
Returns a description of the transport service.
description() - Method in interface com.sun.jdi.VirtualMachine
Returns text information on the target VM and the debugger support that mirrors it.
disable() - Method in interface com.sun.jdi.request.EventRequest
Same as setEnabled(false).
disableCollection() - Method in interface com.sun.jdi.ObjectReference
Prevents garbage collection for this object.
dispose() - Method in interface com.sun.jdi.VirtualMachine
Invalidates this virtual machine mirror.
DoubleType - Interface in com.sun.jdi
The type of all primitive double values accessed in the target VM.
DoubleValue - Interface in com.sun.jdi
Provides access to a primitive double value in the target VM.
doubleValue() - Method in interface com.sun.jdi.PrimitiveValue
Converts this value to a DoubleValue and returns the result as a double.
DuplicateRequestException - Exception in com.sun.jdi.request
Thrown to indicate a duplicate event request.
DuplicateRequestException() - Constructor for exception com.sun.jdi.request.DuplicateRequestException
DuplicateRequestException(String) - Constructor for exception com.sun.jdi.request.DuplicateRequestException

E

enable() - Method in interface com.sun.jdi.request.EventRequest
Same as setEnabled(true).
enableCollection() - Method in interface com.sun.jdi.ObjectReference
Permits garbage collection for this object.
entryCount() - Method in interface com.sun.jdi.ObjectReference
Returns the number times this object's monitor has been entered by the current owning thread.
equals(Object) - Method in interface com.sun.jdi.BooleanValue
Compares the specified Object with this BooleanValue for equality.
equals(Object) - Method in interface com.sun.jdi.ByteValue
Compares the specified Object with this ByteValue for equality.
equals(Object) - Method in interface com.sun.jdi.CharValue
Compares the specified Object with this CharValue for equality.
equals(Object) - Method in interface com.sun.jdi.DoubleValue
Compares the specified Object with this DoubleValue for equality.
equals(Object) - Method in interface com.sun.jdi.Field
Compares the specified Object with this field for equality.
equals(Object) - Method in interface com.sun.jdi.FloatValue
Compares the specified Object with this FloatValue for equality.
equals(Object) - Method in interface com.sun.jdi.IntegerValue
Compares the specified Object with this IntegerValue for equality.
equals(Object) - Method in interface com.sun.jdi.LocalVariable
Compares the specified Object with this LocalVariable for equality.
equals(Object) - Method in interface com.sun.jdi.Location
Compares the specified Object with this Location for equality.
equals(Object) - Method in interface com.sun.jdi.LongValue
Compares the specified Object with this LongValue for equality.
equals(Object) - Method in interface com.sun.jdi.Method
Compares the specified Object with this method for equality.
equals(Object) - Method in interface com.sun.jdi.ObjectReference
Compares the specified Object with this ObjectReference for equality.
equals(Object) - Method in interface com.sun.jdi.ReferenceType
Compares the specified Object with this ReferenceType for equality.
equals(Object) - Method in interface com.sun.jdi.ShortValue
Compares the specified Object with this ShortValue for equality.
equals(Object) - Method in interface com.sun.jdi.VoidValue
Compares the specified Object with this VoidValue for equality.
errorCode() - Method in exception com.sun.jdi.InternalException
Event - Interface in com.sun.jdi.event
An occurrence in a target VM that is of interest to a debugger.
EventIterator - Interface in com.sun.jdi.event
EventIterators are unmodifiable.
eventIterator() - Method in interface com.sun.jdi.event.EventSet
Return an iterator specific to Event objects.
EventQueue - Interface in com.sun.jdi.event
Manager of incoming debugger events for a target VM.
eventQueue() - Method in interface com.sun.jdi.VirtualMachine
Returns the event queue for this virtual machine.
EventRequest - Interface in com.sun.jdi.request
Represents a request for notification of an event.
EventRequestManager - Interface in com.sun.jdi.request
Manages the creation and deletion of EventRequests.
eventRequestManager() - Method in interface com.sun.jdi.VirtualMachine
Returns the event request manager for this virtual machine.
EventSet - Interface in com.sun.jdi.event
Several Event objects may be created at a given time by the target VirtualMachine.
exception() - Method in interface com.sun.jdi.event.ExceptionEvent
Gets the thrown exception object.
exception() - Method in exception com.sun.jdi.InvocationException
exception() - Method in interface com.sun.jdi.request.ExceptionRequest
Returns exception type for which exception events are requested.
ExceptionEvent - Interface in com.sun.jdi.event
Notification of an exception in the target VM.
ExceptionRequest - Interface in com.sun.jdi.request
Request for notification when an exception occurs in the target VM.
exceptionRequests() - Method in interface com.sun.jdi.request.EventRequestManager
Return an unmodifiable list of the enabled and disabled exception requests.
exit(int) - Method in interface com.sun.jdi.VirtualMachine
Causes the mirrored VM to terminate with the given error code.

F

failedToInitialize() - Method in interface com.sun.jdi.ReferenceType
Determines if initialization failed for this class.
field() - Method in interface com.sun.jdi.event.WatchpointEvent
Returns the field that is about to be accessed/modified.
Field - Interface in com.sun.jdi
A class or instance variable in the target VM.
field() - Method in interface com.sun.jdi.request.WatchpointRequest
Gets the Field being watched by this WatchpointRequest.
fieldByName(String) - Method in interface com.sun.jdi.ReferenceType
Finds the visible Field with the given non-ambiguous name.
fields() - Method in interface com.sun.jdi.ReferenceType
Returns a list containing each Field declared in this type.
FloatType - Interface in com.sun.jdi
The type of all primitive float values accessed in the target VM.
FloatValue - Interface in com.sun.jdi
Provides access to a primitive float value in the target VM.
floatValue() - Method in interface com.sun.jdi.PrimitiveValue
Converts this value to a FloatValue and returns the result as a float.
forceEarlyReturn(Value) - Method in interface com.sun.jdi.ThreadReference
Force a method to return before it reaches a return statement.
frame(int) - Method in interface com.sun.jdi.ThreadReference
Returns the StackFrame at the given index in the thread's current call stack.
frameCount() - Method in interface com.sun.jdi.ThreadReference
Returns the number of stack frames in the thread's current call stack.
frames() - Method in interface com.sun.jdi.ThreadReference
Returns a List containing each StackFrame in the thread's current call stack.
frames(int, int) - Method in interface com.sun.jdi.ThreadReference
Returns a List containing a range of StackFrame mirrors from the thread's current call stack.

G

genericSignature() - Method in interface com.sun.jdi.LocalVariable
Gets the generic signature for this variable if there is one.
genericSignature() - Method in interface com.sun.jdi.ReferenceType
Gets the generic signature for this type if there is one.
genericSignature() - Method in interface com.sun.jdi.TypeComponent
Gets the generic signature for this TypeComponent if there is one.
getArgumentValues() - Method in interface com.sun.jdi.StackFrame
Returns the values of all arguments in this frame.
getDefaultStratum() - Method in interface com.sun.jdi.VirtualMachine
Return this VM's default stratum.
getProperty(Object) - Method in interface com.sun.jdi.request.EventRequest
Returns the value of the property with the specified key.
getValue(int) - Method in interface com.sun.jdi.ArrayReference
Returns an array component value.
getValue(Field) - Method in interface com.sun.jdi.ObjectReference
Gets the value of a given instance or static field in this object.
getValue(Field) - Method in interface com.sun.jdi.ReferenceType
Gets the Value of a given static Field in this type.
getValue(LocalVariable) - Method in interface com.sun.jdi.StackFrame
Gets the Value of a LocalVariable in this frame.
getValues() - Method in interface com.sun.jdi.ArrayReference
Returns all of the components in this array.
getValues(int, int) - Method in interface com.sun.jdi.ArrayReference
Returns a range of array components.
getValues(List<? extends Field>) - Method in interface com.sun.jdi.ObjectReference
Gets the value of multiple instance and/or static fields in this object.
getValues(List<? extends Field>) - Method in interface com.sun.jdi.ReferenceType
Returns a map containing the Value of each static Field in the given list.
getValues(List<? extends LocalVariable>) - Method in interface com.sun.jdi.StackFrame
Returns the values of multiple local variables in this frame.

H

hashCode() - Method in interface com.sun.jdi.BooleanValue
Returns the hash code value for this BooleanValue.
hashCode() - Method in interface com.sun.jdi.ByteValue
Returns the hash code value for this BooleanValue.
hashCode() - Method in interface com.sun.jdi.CharValue
Returns the hash code value for this CharValue.
hashCode() - Method in interface com.sun.jdi.DoubleValue
Returns the hash code value for this DoubleValue.
hashCode() - Method in interface com.sun.jdi.Field
Returns the hash code value for this Field.
hashCode() - Method in interface com.sun.jdi.FloatValue
Returns the hash code value for this FloatValue.
hashCode() - Method in interface com.sun.jdi.IntegerValue
Returns the hash code value for this IntegerValue.
hashCode() - Method in interface com.sun.jdi.LocalVariable
Returns the hash code value for this LocalVariable.
hashCode() - Method in interface com.sun.jdi.Location
Returns the hash code value for this Location.
hashCode() - Method in interface com.sun.jdi.LongValue
Returns the hash code value for this LongValue.
hashCode() - Method in interface com.sun.jdi.Method
Returns the hash code value for this Method.
hashCode() - Method in interface com.sun.jdi.ObjectReference
Returns the hash code value for this ObjectReference.
hashCode() - Method in interface com.sun.jdi.ReferenceType
Returns the hash code value for this ObjectReference.
hashCode() - Method in interface com.sun.jdi.ShortValue
Returns the hash code value for this ShortValue.
hashCode() - Method in interface com.sun.jdi.VoidValue
Returns the hash code value for this VoidValue.

I

IllegalConnectorArgumentsException - Exception in com.sun.jdi.connect
Thrown to indicate an invalid argument or inconsistent passed to a Connector.
IllegalConnectorArgumentsException(String, String) - Constructor for exception com.sun.jdi.connect.IllegalConnectorArgumentsException
Construct an IllegalConnectorArgumentsException with the specified detail message and the name of the argument which is invalid or inconsistent.
IllegalConnectorArgumentsException(String, List<String>) - Constructor for exception com.sun.jdi.connect.IllegalConnectorArgumentsException
Construct an IllegalConnectorArgumentsException with the specified detail message and a List of names of arguments which are invalid or inconsistent.
implementors() - Method in interface com.sun.jdi.InterfaceType
Gets the currently prepared classes which directly implement this interface.
IncompatibleThreadStateException - Exception in com.sun.jdi
Thrown to indicate that the requested operation cannot be completed while the specified thread is in its current state.
IncompatibleThreadStateException() - Constructor for exception com.sun.jdi.IncompatibleThreadStateException
IncompatibleThreadStateException(String) - Constructor for exception com.sun.jdi.IncompatibleThreadStateException
InconsistentDebugInfoException - Exception in com.sun.jdi
Thrown to indicate that there is an inconistency in the debug information provided by the target VM.
InconsistentDebugInfoException() - Constructor for exception com.sun.jdi.InconsistentDebugInfoException
InconsistentDebugInfoException(String) - Constructor for exception com.sun.jdi.InconsistentDebugInfoException
instanceCounts(List<? extends ReferenceType>) - Method in interface com.sun.jdi.VirtualMachine
Returns the number of instances of each ReferenceType in the 'refTypes' list.
instances(long) - Method in interface com.sun.jdi.ReferenceType
Returns instances of this ReferenceType.
IntegerType - Interface in com.sun.jdi
The type of all primitive int values accessed in the target VM.
IntegerValue - Interface in com.sun.jdi
Provides access to a primitive int value in the target VM.
interfaces() - Method in interface com.sun.jdi.ClassType
Gets the interfaces directly implemented by this class.
InterfaceType - Interface in com.sun.jdi
A mirror of an interface in the target VM.
InternalException - Exception in com.sun.jdi
Thrown to indicate that an unexpected internal error has occurred.
InternalException() - Constructor for exception com.sun.jdi.InternalException
InternalException(String) - Constructor for exception com.sun.jdi.InternalException
InternalException(int) - Constructor for exception com.sun.jdi.InternalException
InternalException(String, int) - Constructor for exception com.sun.jdi.InternalException
interrupt() - Method in interface com.sun.jdi.ThreadReference
Interrupts this thread unless the thread has been suspended by the debugger.
intValue() - Method in interface com.sun.jdi.connect.Connector.IntegerArgument
Return the value of the argument as a int.
intValue() - Method in interface com.sun.jdi.PrimitiveValue
Converts this value to an IntegerValue and returns the result as an int.
InvalidCodeIndexException - Exception in com.sun.jdi
Deprecated. This exception is no longer thrown
InvalidCodeIndexException() - Constructor for exception com.sun.jdi.InvalidCodeIndexException
Deprecated.
InvalidCodeIndexException(String) - Constructor for exception com.sun.jdi.InvalidCodeIndexException
Deprecated.
InvalidLineNumberException - Exception in com.sun.jdi
Deprecated. This exception is no longer thrown
InvalidLineNumberException() - Constructor for exception com.sun.jdi.InvalidLineNumberException
Deprecated.
InvalidLineNumberException(String) - Constructor for exception com.sun.jdi.InvalidLineNumberException
Deprecated.
InvalidRequestStateException - Exception in com.sun.jdi.request
Thrown to indicate that the requested event cannot be modified because it is enabled.
InvalidRequestStateException() - Constructor for exception com.sun.jdi.request.InvalidRequestStateException
InvalidRequestStateException(String) - Constructor for exception com.sun.jdi.request.InvalidRequestStateException
InvalidStackFrameException - Exception in com.sun.jdi
Thrown to indicate that the requested operation cannot be completed because the specified stack frame is no longer valid.
InvalidStackFrameException() - Constructor for exception com.sun.jdi.InvalidStackFrameException
InvalidStackFrameException(String) - Constructor for exception com.sun.jdi.InvalidStackFrameException
InvalidTypeException - Exception in com.sun.jdi
Thrown to indicate a type mismatch in setting the value of a field or variable, or in specifying the return value of a method.
InvalidTypeException() - Constructor for exception com.sun.jdi.InvalidTypeException
InvalidTypeException(String) - Constructor for exception com.sun.jdi.InvalidTypeException
InvocationException - Exception in com.sun.jdi
Thrown to indicate an exception occurred in an invoked method within the target VM.
InvocationException(ObjectReference) - Constructor for exception com.sun.jdi.InvocationException
INVOKE_NONVIRTUAL - Static variable in interface com.sun.jdi.ObjectReference
Perform non-virtual method invocation
INVOKE_SINGLE_THREADED - Static variable in interface com.sun.jdi.ClassType
Perform method invocation with only the invoking thread resumed
INVOKE_SINGLE_THREADED - Static variable in interface com.sun.jdi.ObjectReference
Perform method invocation with only the invoking thread resumed
invokeMethod(ThreadReference, Method, List<? extends Value>, int) - Method in interface com.sun.jdi.ClassType
Invokes the specified static Method in the target VM.
invokeMethod(ThreadReference, Method, List<? extends Value>, int) - Method in interface com.sun.jdi.ObjectReference
Invokes the specified Method on this object in the target VM.
isAbstract() - Method in interface com.sun.jdi.Method
Determine if this method is abstract.
isAbstract() - Method in interface com.sun.jdi.ReferenceType
Determines if this type was declared abstract.
isArgument() - Method in interface com.sun.jdi.LocalVariable
Determines if this variable is an argument to its method.
isAtBreakpoint() - Method in interface com.sun.jdi.ThreadReference
Determines whether the thread is suspended at a breakpoint.
isBridge() - Method in interface com.sun.jdi.Method
Determine if this method is a bridge method.
isCollected() - Method in interface com.sun.jdi.ObjectReference
Determines if this object has been garbage collected in the target VM.
isConstructor() - Method in interface com.sun.jdi.Method
Determine if this method is a constructor.
isEnabled() - Method in interface com.sun.jdi.request.EventRequest
Determines if this event request is currently enabled.
isEnum() - Method in interface com.sun.jdi.ClassType
Determine if this class was declared as an enum.
isEnumConstant() - Method in interface com.sun.jdi.Field
Determine if this is a field that represents an enum constant.
isFinal() - Method in interface com.sun.jdi.ReferenceType
Determines if this type was declared final.
isFinal() - Method in interface com.sun.jdi.TypeComponent
Determines if this TypeComponent is final.
isInitialized() - Method in interface com.sun.jdi.ReferenceType
Determines if this type has been initialized.
isNative() - Method in interface com.sun.jdi.Method
Determine if this method is native.
isObsolete() - Method in interface com.sun.jdi.Method
Determine if this method is obsolete.
isOpen() - Method in class com.sun.jdi.connect.spi.Connection
Tells whether or not this connection is open.
isPackagePrivate() - Method in interface com.sun.jdi.Accessible
Determines if this object mirrors a package private item.
isPrepared() - Method in interface com.sun.jdi.ReferenceType
Determines if this type has been prepared.
isPrivate() - Method in interface com.sun.jdi.Accessible
Determines if this object mirrors a private item.
isProtected() - Method in interface com.sun.jdi.Accessible
Determines if this object mirrors a protected item.
isPublic() - Method in interface com.sun.jdi.Accessible
Determines if this object mirrors a public item.
isStatic() - Method in interface com.sun.jdi.ReferenceType
Determines if this type was declared static.
isStatic() - Method in interface com.sun.jdi.TypeComponent
Determines if this TypeComponent is static.
isStaticInitializer() - Method in interface com.sun.jdi.Method
Determine if this method is a static initializer.
isSuspended() - Method in interface com.sun.jdi.ThreadReference
Determines whether the thread has been suspended by the the debugger.
isSynchronized() - Method in interface com.sun.jdi.Method
Determine if this method is synchronized.
isSynthetic() - Method in interface com.sun.jdi.TypeComponent
Determines if this TypeComponent is synthetic.
isTransient() - Method in interface com.sun.jdi.Field
Determine if this is a transient field.
isValid(String) - Method in interface com.sun.jdi.connect.Connector.Argument
Performs basic sanity check of argument.
isValid(String) - Method in interface com.sun.jdi.connect.Connector.BooleanArgument
Performs basic sanity check of argument.
isValid(String) - Method in interface com.sun.jdi.connect.Connector.IntegerArgument
Performs basic sanity check of argument.
isValid(int) - Method in interface com.sun.jdi.connect.Connector.IntegerArgument
Performs basic sanity check of argument.
isValid(String) - Method in interface com.sun.jdi.connect.Connector.SelectedArgument
Performs basic sanity check of argument.
isValid(String) - Method in interface com.sun.jdi.connect.Connector.StringArgument
Performs basic sanity check of argument.
isVarArgs() - Method in interface com.sun.jdi.Method
Determine if this method accepts a variable number of arguments.
isVerified() - Method in interface com.sun.jdi.ReferenceType
Determines if this type has been verified.
isVisible(StackFrame) - Method in interface com.sun.jdi.LocalVariable
Determines whether this variable can be accessed from the given StackFrame.
isVolatile() - Method in interface com.sun.jdi.Field
Determine if this is a volatile field.

J

JDIPermission - Class in com.sun.jdi
The JDIPermission class represents access rights to the VirtualMachineManager.
JDIPermission(String) - Constructor for class com.sun.jdi.JDIPermission
The JDIPermission class represents access rights to the VirtualMachineManager
JDIPermission(String, String) - Constructor for class com.sun.jdi.JDIPermission
Constructs a new JDIPermission object.

L

label() - Method in interface com.sun.jdi.connect.Connector.Argument
Returns a short human-readable label for this argument.
launch(Map<String, ? extends Connector.Argument>) - Method in interface com.sun.jdi.connect.LaunchingConnector
Launches an application and connects to its VM.
LaunchingConnector - Interface in com.sun.jdi.connect
A connector which can launch a target VM before connecting to it.
launchingConnectors() - Method in interface com.sun.jdi.VirtualMachineManager
Returns the list of known LaunchingConnector objects.
length() - Method in interface com.sun.jdi.ArrayReference
Returns the number of components in this array.
lineNumber() - Method in interface com.sun.jdi.Location
Gets the line number of this Location.
lineNumber(String) - Method in interface com.sun.jdi.Location
The line number of this Location.
ListeningConnector - Interface in com.sun.jdi.connect
A connector which listens for a connection initiated by a target VM.
listeningConnectors() - Method in interface com.sun.jdi.VirtualMachineManager
Returns the list of known ListeningConnector objects.
LocalVariable - Interface in com.sun.jdi
A local variable in the target VM.
Locatable - Interface in com.sun.jdi
A mirror that has a Location.
LocatableEvent - Interface in com.sun.jdi.event
Abstract superinterface of events which have both location and thread.
location() - Method in interface com.sun.jdi.Locatable
Returns the Location of this mirror, if there is executable code associated with it.
Location - Interface in com.sun.jdi
A point within the executing code of the target VM.
location() - Method in interface com.sun.jdi.Method
Returns the Location of this method, if there is executable code associated with it.
location() - Method in interface com.sun.jdi.request.BreakpointRequest
Returns the location of the requested breakpoint.
location() - Method in interface com.sun.jdi.StackFrame
Returns the Location of the current instruction in the frame.
locationOfCodeIndex(long) - Method in interface com.sun.jdi.Method
Returns a Location for the given code index.
locationsOfLine(int) - Method in interface com.sun.jdi.Method
Returns a List containing all Location objects that map to the given line number.
locationsOfLine(String, String, int) - Method in interface com.sun.jdi.Method
Returns a List containing all Location objects that map to the given line number and source name.
locationsOfLine(int) - Method in interface com.sun.jdi.ReferenceType
Returns a List containing all Location objects that map to the given line number.
locationsOfLine(String, String, int) - Method in interface com.sun.jdi.ReferenceType
Returns a List containing all Location objects that map to the given line number.
LongType - Interface in com.sun.jdi
The type of all primitive long values accessed in the target VM.
LongValue - Interface in com.sun.jdi
Provides access to a primitive long value in the target VM.
longValue() - Method in interface com.sun.jdi.PrimitiveValue
Converts this value to a LongValue and returns the result as a long.

M

majorInterfaceVersion() - Method in interface com.sun.jdi.VirtualMachineManager
Returns the major version number of the JDI interface.
majorVersion() - Method in interface com.sun.jdi.ReferenceType
Returns the class major version number, as defined in the class file format of the Java Virtual Machine Specification.
max() - Method in interface com.sun.jdi.connect.Connector.IntegerArgument
The upper bound for the value.
method() - Method in interface com.sun.jdi.event.MethodEntryEvent
Returns the method that was entered.
method() - Method in interface com.sun.jdi.event.MethodExitEvent
Returns the method that was exited.
method() - Method in interface com.sun.jdi.Location
Gets the method containing this Location.
Method - Interface in com.sun.jdi
A static or instance method in the target VM.
MethodEntryEvent - Interface in com.sun.jdi.event
Notification of a method invocation in the target VM.
MethodEntryRequest - Interface in com.sun.jdi.request
Request for notification when a method is invoked in the target VM.
methodEntryRequests() - Method in interface com.sun.jdi.request.EventRequestManager
Return an unmodifiable list of the enabled and disabled method entry requests.
MethodExitEvent - Interface in com.sun.jdi.event
Notification of a method return in the target VM.
MethodExitRequest - Interface in com.sun.jdi.request
Request for notification when a method returns in the target VM.
methodExitRequests() - Method in interface com.sun.jdi.request.EventRequestManager
Return an unmodifiable list of the enabled and disabled method exit requests.
methods() - Method in interface com.sun.jdi.ReferenceType
Returns a list containing each Method declared directly in this type.
methodsByName(String) - Method in interface com.sun.jdi.ReferenceType
Returns a List containing each visible Method that has the given name.
methodsByName(String, String) - Method in interface com.sun.jdi.ReferenceType
Returns a List containing each visible Method that has the given name and signature.
min() - Method in interface com.sun.jdi.connect.Connector.IntegerArgument
The lower bound for the value.
minorInterfaceVersion() - Method in interface com.sun.jdi.VirtualMachineManager
Returns the minor version number of the JDI interface.
minorVersion() - Method in interface com.sun.jdi.ReferenceType
Returns the class minor version number, as defined in the class file format of the Java Virtual Machine Specification.
Mirror - Interface in com.sun.jdi
A proxy used by a debugger to examine or manipulate some entity in another virtual machine.
mirrorOf(boolean) - Method in interface com.sun.jdi.VirtualMachine
Creates a BooleanValue for the given value.
mirrorOf(byte) - Method in interface com.sun.jdi.VirtualMachine
Creates a ByteValue for the given value.
mirrorOf(char) - Method in interface com.sun.jdi.VirtualMachine
Creates a CharValue for the given value.
mirrorOf(short) - Method in interface com.sun.jdi.VirtualMachine
Creates a ShortValue for the given value.
mirrorOf(int) - Method in interface com.sun.jdi.VirtualMachine
Creates an IntegerValue for the given value.
mirrorOf(long) - Method in interface com.sun.jdi.VirtualMachine
Creates a LongValue for the given value.
mirrorOf(float) - Method in interface com.sun.jdi.VirtualMachine
Creates a FloatValue for the given value.
mirrorOf(double) - Method in interface com.sun.jdi.VirtualMachine
Creates a DoubleValue for the given value.
mirrorOf(String) - Method in interface com.sun.jdi.VirtualMachine
Creates a string in this virtual machine.
mirrorOfVoid() - Method in interface com.sun.jdi.VirtualMachine
Creates a VoidValue.
ModificationWatchpointEvent - Interface in com.sun.jdi.event
Notification of a field modification in the target VM.
ModificationWatchpointRequest - Interface in com.sun.jdi.request
Request for notification when a field is set.
modificationWatchpointRequests() - Method in interface com.sun.jdi.request.EventRequestManager
Return an unmodifiable list of the enabled and disabled modification watchpoint requests.
modifiers() - Method in interface com.sun.jdi.Accessible
Returns the JavaTM programming language modifiers, encoded in an integer.
monitor() - Method in interface com.sun.jdi.event.MonitorContendedEnteredEvent
Returns the monitor that was entered.
monitor() - Method in interface com.sun.jdi.event.MonitorContendedEnterEvent
Returns the method that was entered.
monitor() - Method in interface com.sun.jdi.event.MonitorWaitedEvent
Returns the monitor object this thread waited on.
monitor() - Method in interface com.sun.jdi.event.MonitorWaitEvent
Returns the monitor object that the thread about to wait.
monitor() - Method in interface com.sun.jdi.MonitorInfo
Returns the ObjectReference object for the monitor.
MonitorContendedEnteredEvent - Interface in com.sun.jdi.event
Notification that a thread in the target VM is entering a monitor after waiting for it to be released by another thread.
MonitorContendedEnteredRequest - Interface in com.sun.jdi.request
Request for notification of a thread in the target VM entering a monitor after waiting for it to be released by another thread.
monitorContendedEnteredRequests() - Method in interface com.sun.jdi.request.EventRequestManager
Return an unmodifiable list of the enabled and disabled monitor contended entered requests.
MonitorContendedEnterEvent - Interface in com.sun.jdi.event
Notification that a thread in the target VM is attempting to enter a monitor that is already acquired by another thread.
MonitorContendedEnterRequest - Interface in com.sun.jdi.request
Request for notification of a thread in the target VM attempting to enter a monitor already acquired by another thread.
monitorContendedEnterRequests() - Method in interface com.sun.jdi.request.EventRequestManager
Return an unmodifiable list of the enabled and disabled monitor contended enter requests.
MonitorInfo - Interface in com.sun.jdi
Information about a monitor owned by a thread.
MonitorWaitedEvent - Interface in com.sun.jdi.event
Notification that a thread in the target VM has finished waiting on an monitor object.
MonitorWaitedRequest - Interface in com.sun.jdi.request
Request for notification when a thread in the target VM has finished waiting on a monitor object.
monitorWaitedRequests() - Method in interface com.sun.jdi.request.EventRequestManager
Return an unmodifiable list of the enabled and disabled monitor waited requests.
MonitorWaitEvent - Interface in com.sun.jdi.event
Notification that a thread in the target VM is about to wait on a monitor object.
MonitorWaitRequest - Interface in com.sun.jdi.request
Request for notification when a thread in the target VM is about to wait on a monitor object.
monitorWaitRequests() - Method in interface com.sun.jdi.request.EventRequestManager
Return an unmodifiable list of the enabled and disabled monitor wait requests.
mustSpecify() - Method in interface com.sun.jdi.connect.Connector.Argument
Indicates whether the argument must be specified.

N

name() - Method in interface com.sun.jdi.connect.Connector.Argument
Returns a short, unique identifier for the argument.
name() - Method in interface com.sun.jdi.connect.Connector
Returns a short identifier for the connector.
name() - Method in class com.sun.jdi.connect.spi.TransportService
Returns a name to identify the transport service.
name() - Method in interface com.sun.jdi.connect.Transport
Returns a short identifier for the transport.
name() - Method in interface com.sun.jdi.LocalVariable
Gets the name of the local variable.
name() - Method in interface com.sun.jdi.ReferenceType
Gets the fully qualified name of this type.
name() - Method in interface com.sun.jdi.ThreadGroupReference
Returns the name of this thread group.
name() - Method in interface com.sun.jdi.ThreadReference
Returns the name of this thread.
name() - Method in interface com.sun.jdi.Type
name() - Method in interface com.sun.jdi.TypeComponent
Gets the name of this type component.
name() - Method in interface com.sun.jdi.VirtualMachine
Returns the name of the target VM as reported by the property java.vm.name.
NativeMethodException - Exception in com.sun.jdi
Thrown to indicate an operation cannot be completed because it is not valid for a native method.
NativeMethodException() - Constructor for exception com.sun.jdi.NativeMethodException
NativeMethodException(String) - Constructor for exception com.sun.jdi.NativeMethodException
nestedTypes() - Method in interface com.sun.jdi.ReferenceType
Returns a List containing ReferenceType objects that are declared within this type and are currently loaded into the Virtual Machine.
newInstance(int) - Method in interface com.sun.jdi.ArrayType
Creates a new instance of this array class in the target VM.
newInstance(ThreadReference, Method, List<? extends Value>, int) - Method in interface com.sun.jdi.ClassType
Constructs a new instance of this type, using the given constructor Method in the target VM.
nextEvent() - Method in interface com.sun.jdi.event.EventIterator
notifyCaught() - Method in interface com.sun.jdi.request.ExceptionRequest
Returns whether caught exceptions of the requested type will generate events when they are thrown.
notifyUncaught() - Method in interface com.sun.jdi.request.ExceptionRequest
Returns whether uncaught exceptions of the requested type will generate events when they are thrown.

O

object() - Method in interface com.sun.jdi.event.WatchpointEvent
Returns the object whose field is about to be accessed/modified.
ObjectCollectedException - Exception in com.sun.jdi
Thrown to indicate that the requested operation cannot be completed because the specified object has been garbage collected.
ObjectCollectedException() - Constructor for exception com.sun.jdi.ObjectCollectedException
ObjectCollectedException(String) - Constructor for exception com.sun.jdi.ObjectCollectedException
ObjectReference - Interface in com.sun.jdi
An object that currently exists in the target VM.
ownedMonitors() - Method in interface com.sun.jdi.ThreadReference
Returns a List containing an ObjectReference for each monitor owned by the thread.
ownedMonitorsAndFrames() - Method in interface com.sun.jdi.ThreadReference
Returns a List containing a MonitorInfo object for each monitor owned by the thread.
owningThread() - Method in interface com.sun.jdi.ObjectReference
Returns an ThreadReference for the thread, if any, which currently owns this object's monitor.

P

parent() - Method in interface com.sun.jdi.ThreadGroupReference
Returns the parent of this thread group.
PathSearchingVirtualMachine - Interface in com.sun.jdi
A virtual machine which searches for classes through paths
popFrames(StackFrame) - Method in interface com.sun.jdi.ThreadReference
Pop stack frames.
PrimitiveType - Interface in com.sun.jdi
The type associated with non-object values in a target VM.
PrimitiveValue - Interface in com.sun.jdi
The value assigned to a field or variable of primitive type in a target VM.
process() - Method in exception com.sun.jdi.connect.VMStartException
process() - Method in interface com.sun.jdi.VirtualMachine
Returns the Process object for this virtual machine if launched by a LaunchingConnector
putProperty(Object, Object) - Method in interface com.sun.jdi.request.EventRequest
Add an arbitrary key/value "property" to this request.

R

readPacket() - Method in class com.sun.jdi.connect.spi.Connection
Reads a packet from the target VM.
redefineClasses(Map<? extends ReferenceType, byte[]>) - Method in interface com.sun.jdi.VirtualMachine
All classes given are redefined according to the definitions supplied.
referenceType() - Method in interface com.sun.jdi.event.ClassPrepareEvent
Returns the reference type for which this event was generated.
referenceType() - Method in interface com.sun.jdi.ObjectReference
Gets the ReferenceType that mirrors the type of this object.
ReferenceType - Interface in com.sun.jdi
The type of an object in a target VM.
referringObjects(long) - Method in interface com.sun.jdi.ObjectReference
Returns objects that directly reference this object.
reflectedType() - Method in interface com.sun.jdi.ClassObjectReference
Returns the ReferenceType corresponding to this class object.
remove() - Method in interface com.sun.jdi.event.EventQueue
Waits forever for the next available event.
remove(long) - Method in interface com.sun.jdi.event.EventQueue
Waits a specified time for the next available event.
request() - Method in interface com.sun.jdi.event.Event
resume() - Method in interface com.sun.jdi.event.EventSet
Resumes threads suspended by this event set.
resume() - Method in interface com.sun.jdi.ThreadGroupReference
Resumes all threads in this thread group.
resume() - Method in interface com.sun.jdi.ThreadReference
Resumes this thread.
resume() - Method in interface com.sun.jdi.VirtualMachine
Continues the execution of the application running in this virtual machine.
returnType() - Method in interface com.sun.jdi.Method
Returns the return type, as specified in the declaration of this method.
returnTypeName() - Method in interface com.sun.jdi.Method
Returns a text representation of the return type, as specified in the declaration of this method.
returnValue() - Method in interface com.sun.jdi.event.MethodExitEvent
Returns the value that the method will return.

S

setDebugTraceMode(int) - Method in interface com.sun.jdi.VirtualMachine
Traces the activities performed by the com.sun.jdi implementation.
setDefaultStratum(String) - Method in interface com.sun.jdi.VirtualMachine
Set this VM's default stratum (see Location for a discussion of strata).
setEnabled(boolean) - Method in interface com.sun.jdi.request.EventRequest
Enables or disables this event request.
setSuspendPolicy(int) - Method in interface com.sun.jdi.request.EventRequest
Determines the threads to suspend when the requested event occurs in the target VM.
setValue(int, Value) - Method in interface com.sun.jdi.ArrayReference
Replaces an array component with another value.
setValue(Field, Value) - Method in interface com.sun.jdi.ClassType
Assigns a value to a static field.
setValue(String) - Method in interface com.sun.jdi.connect.Connector.Argument
Sets the value of the argument.
setValue(boolean) - Method in interface com.sun.jdi.connect.Connector.BooleanArgument
Sets the value of the argument.
setValue(int) - Method in interface com.sun.jdi.connect.Connector.IntegerArgument
Sets the value of the argument.
setValue(Field, Value) - Method in interface com.sun.jdi.ObjectReference
Sets the value of a given instance or static field in this object.
setValue(LocalVariable, Value) - Method in interface com.sun.jdi.StackFrame
Sets the Value of a LocalVariable in this frame.
setValues(List<? extends Value>) - Method in interface com.sun.jdi.ArrayReference
Replaces all array components with other values.
setValues(int, List<? extends Value>, int, int) - Method in interface com.sun.jdi.ArrayReference
Replaces a range of array components with other values.
ShortType - Interface in com.sun.jdi
The type of all primitive short values accessed in the target VM.
shortValue() - Method in interface com.sun.jdi.PrimitiveValue
Converts this value to a ShortValue and returns the result as a short.
ShortValue - Interface in com.sun.jdi
Provides access to a primitive short value in the target VM.
signature() - Method in interface com.sun.jdi.LocalVariable
Gets the JNI signature of the local variable.
signature() - Method in interface com.sun.jdi.Type
Returns the JNI-style signature for this type.
signature() - Method in interface com.sun.jdi.TypeComponent
Gets the JNI-style signature for this type component.
size() - Method in interface com.sun.jdi.request.StepRequest
sourceDebugExtension() - Method in interface com.sun.jdi.ReferenceType
Get the source debug extension of this type.
sourceName() - Method in interface com.sun.jdi.Location
Gets an identifing name for the source corresponding to this location.
sourceName(String) - Method in interface com.sun.jdi.Location
Gets an identifing name for the source corresponding to this location.
sourceName() - Method in interface com.sun.jdi.ReferenceType
Gets an identifying name for the source corresponding to the declaration of this type.
sourceNames(String) - Method in interface com.sun.jdi.ReferenceType
Gets the identifying names for all the source corresponding to the declaration of this type.
sourcePath() - Method in interface com.sun.jdi.Location
Gets the path to the source corresponding to this location.
sourcePath(String) - Method in interface com.sun.jdi.Location
Gets the path to the source corresponding to this location.
sourcePaths(String) - Method in interface com.sun.jdi.ReferenceType
Gets the paths to the source corresponding to the declaration of this type.
stackDepth() - Method in interface com.sun.jdi.MonitorInfo
Returns the stack depth at which this monitor was acquired by the owning thread.
StackFrame - Interface in com.sun.jdi
The state of one method invocation on a thread's call stack.
startListening(Map<String, ? extends Connector.Argument>) - Method in interface com.sun.jdi.connect.ListeningConnector
Listens for one or more connections initiated by target VMs.
startListening(String) - Method in class com.sun.jdi.connect.spi.TransportService
Listens on the specified address for inbound connections.
startListening() - Method in class com.sun.jdi.connect.spi.TransportService
Listens on an address choosen by the transport service.
status() - Method in interface com.sun.jdi.ThreadReference
Returns the thread's status.
STEP_INTO - Static variable in interface com.sun.jdi.request.StepRequest
Step into any newly pushed frames
STEP_LINE - Static variable in interface com.sun.jdi.request.StepRequest
Step to the next location on a different line
STEP_MIN - Static variable in interface com.sun.jdi.request.StepRequest
Step to the next available location
STEP_OUT - Static variable in interface com.sun.jdi.request.StepRequest
Step out of the current frame
STEP_OVER - Static variable in interface com.sun.jdi.request.StepRequest
Step over any newly pushed frames
StepEvent - Interface in com.sun.jdi.event
Notification of step completion in the target VM.
StepRequest - Interface in com.sun.jdi.request
Request for notification when a step occurs in the target VM.
stepRequests() - Method in interface com.sun.jdi.request.EventRequestManager
Return an unmodifiable list of the enabled and disabled step requests.
stop(ObjectReference) - Method in interface com.sun.jdi.ThreadReference
Stops this thread with an asynchronous exception.
stopListening(Map<String, ? extends Connector.Argument>) - Method in interface com.sun.jdi.connect.ListeningConnector
Cancels listening for connections.
stopListening(TransportService.ListenKey) - Method in class com.sun.jdi.connect.spi.TransportService
Stop listening for inbound connections.
StringReference - Interface in com.sun.jdi
A string object from the target VM.
stringValueOf(boolean) - Method in interface com.sun.jdi.connect.Connector.BooleanArgument
Return the string representation of the value parameter.
stringValueOf(int) - Method in interface com.sun.jdi.connect.Connector.IntegerArgument
Return the string representation of the value parameter.
subclasses() - Method in interface com.sun.jdi.ClassType
Gets the currently loaded, direct subclasses of this class.
subinterfaces() - Method in interface com.sun.jdi.InterfaceType
Gets the currently prepared interfaces which directly extend this interface.
superclass() - Method in interface com.sun.jdi.ClassType
Gets the superclass of this class.
superinterfaces() - Method in interface com.sun.jdi.InterfaceType
Gets the interfaces directly extended by this interface.
supportsAcceptTimeout() - Method in class com.sun.jdi.connect.spi.TransportService.Capabilities
Tell whether or not this transport service supports a timeout while waiting for a target VM to connect.
supportsAttachTimeout() - Method in class com.sun.jdi.connect.spi.TransportService.Capabilities
Tell whether or not this transport service supports a timeout when attaching to a target VM.
supportsHandshakeTimeout() - Method in class com.sun.jdi.connect.spi.TransportService.Capabilities
Tells whether or not this transport service supports a timeout when handshaking with the target VM.
supportsMultipleConnections() - Method in interface com.sun.jdi.connect.ListeningConnector
Indicates whether this listening connector supports multiple connections for a single argument map.
supportsMultipleConnections() - Method in class com.sun.jdi.connect.spi.TransportService.Capabilities
Tells whether or not this transport service can support multiple concurrent connections to a single address that it is listening on.
suspend() - Method in interface com.sun.jdi.ThreadGroupReference
Suspends all threads in this thread group.
suspend() - Method in interface com.sun.jdi.ThreadReference
Suspends this thread.
suspend() - Method in interface com.sun.jdi.VirtualMachine
Suspends the execution of the application running in this virtual machine.
SUSPEND_ALL - Static variable in interface com.sun.jdi.request.EventRequest
Suspend all threads when the event occurs
SUSPEND_EVENT_THREAD - Static variable in interface com.sun.jdi.request.EventRequest
Suspend only the thread which generated the event when the event occurs
SUSPEND_NONE - Static variable in interface com.sun.jdi.request.EventRequest
Suspend no threads when the event occurs
suspendCount() - Method in interface com.sun.jdi.ThreadReference
Returns the number of pending suspends for this thread.
suspendPolicy() - Method in interface com.sun.jdi.event.EventSet
Returns the policy used to suspend threads in the target VM for this event set.
suspendPolicy() - Method in interface com.sun.jdi.request.EventRequest
Returns a value which describes the threads to suspend when the requested event occurs in the target VM.

T

thisObject() - Method in interface com.sun.jdi.StackFrame
Returns the value of 'this' for the current frame.
thread() - Method in interface com.sun.jdi.event.ClassPrepareEvent
Returns the thread in which this event has occurred.
thread() - Method in interface com.sun.jdi.event.LocatableEvent
Returns the thread in which this event has occurred.
thread() - Method in interface com.sun.jdi.event.MonitorContendedEnteredEvent
Returns the thread in which this event has occurred.
thread() - Method in interface com.sun.jdi.event.MonitorContendedEnterEvent
Returns the thread in which this event has occurred.
thread() - Method in interface com.sun.jdi.event.MonitorWaitedEvent
Returns the thread in which this event has occurred.
thread() - Method in interface com.sun.jdi.event.MonitorWaitEvent
Returns the thread in which monitor wait event has occurred.
thread() - Method in interface com.sun.jdi.event.ThreadDeathEvent
Returns the thread which is terminating.
thread() - Method in interface com.sun.jdi.event.ThreadStartEvent
Returns the thread which has started.
thread() - Method in interface com.sun.jdi.event.VMStartEvent
Returns the initial thread of the VM which has started.
thread() - Method in interface com.sun.jdi.MonitorInfo
Returns a ThreadReference object for the thread that owns the monitor.
thread() - Method in interface com.sun.jdi.request.StepRequest
thread() - Method in interface com.sun.jdi.StackFrame
Returns the thread under which this frame's method is running.
THREAD_STATUS_MONITOR - Static variable in interface com.sun.jdi.ThreadReference
Thread is waiting on a java monitor
THREAD_STATUS_NOT_STARTED - Static variable in interface com.sun.jdi.ThreadReference
Thread has not yet been started
THREAD_STATUS_RUNNING - Static variable in interface com.sun.jdi.ThreadReference
Thread is runnable
THREAD_STATUS_SLEEPING - Static variable in interface com.sun.jdi.ThreadReference
Thread is sleeping - Thread.sleep() or JVM_Sleep() was called
THREAD_STATUS_UNKNOWN - Static variable in interface com.sun.jdi.ThreadReference
Thread status is unknown
THREAD_STATUS_WAIT - Static variable in interface com.sun.jdi.ThreadReference
Thread is waiting - Object.wait() or JVM_MonitorWait() was called
THREAD_STATUS_ZOMBIE - Static variable in interface com.sun.jdi.ThreadReference
Thread has completed execution
ThreadDeathEvent - Interface in com.sun.jdi.event
Notification of a completed thread in the target VM.
ThreadDeathRequest - Interface in com.sun.jdi.request
Request for notification when a thread terminates in the target VM.
threadDeathRequests() - Method in interface com.sun.jdi.request.EventRequestManager
Return an unmodifiable list of the enabled and disabled thread death requests.
threadGroup() - Method in interface com.sun.jdi.ThreadReference
Returns this thread's thread group.
ThreadGroupReference - Interface in com.sun.jdi
A thread group object from the target VM.
threadGroups() - Method in interface com.sun.jdi.ThreadGroupReference
Returns a List containing each active ThreadGroupReference in this thread group.
ThreadReference - Interface in com.sun.jdi
A thread object from the target VM.
threads() - Method in interface com.sun.jdi.ThreadGroupReference
Returns a List containing a ThreadReference for each live thread in this thread group.
ThreadStartEvent - Interface in com.sun.jdi.event
Notification of a new running thread in the target VM.
ThreadStartRequest - Interface in com.sun.jdi.request
Request for notification when a thread starts execution in the target VM.
threadStartRequests() - Method in interface com.sun.jdi.request.EventRequestManager
Return an unmodifiable list of the enabled and disabled thread start requests.
timedout() - Method in interface com.sun.jdi.event.MonitorWaitedEvent
Returns whether the wait has timed out or been interrupted.
timeout() - Method in interface com.sun.jdi.event.MonitorWaitEvent
Returns the number of millisecond the thread will wait.
topLevelThreadGroups() - Method in interface com.sun.jdi.VirtualMachine
Returns each thread group which does not have a parent.
toString() - Method in interface com.sun.jdi.Mirror
Returns a String describing this mirror
TRACE_ALL - Static variable in interface com.sun.jdi.VirtualMachine
All tracing is enabled.
TRACE_EVENTS - Static variable in interface com.sun.jdi.VirtualMachine
Tracing enabled for internal event handling.
TRACE_NONE - Static variable in interface com.sun.jdi.VirtualMachine
All tracing is disabled.
TRACE_OBJREFS - Static variable in interface com.sun.jdi.VirtualMachine
Tracing enabled for internal management of object references.
TRACE_RECEIVES - Static variable in interface com.sun.jdi.VirtualMachine
Tracing enabled for JDWP packets received from target VM.
TRACE_REFTYPES - Static variable in interface com.sun.jdi.VirtualMachine
Tracing enabled for internal managment of reference types.
TRACE_SENDS - Static variable in interface com.sun.jdi.VirtualMachine
Tracing enabled for JDWP packets sent to target VM.
transport() - Method in interface com.sun.jdi.connect.Connector
Returns the transport mechanism used by this connector to establish connections with a target VM.
Transport - Interface in com.sun.jdi.connect
A method of communication between a debugger and a target VM.
TransportService - Class in com.sun.jdi.connect.spi
A transport service for connections between a debugger and a target VM.
TransportService() - Constructor for class com.sun.jdi.connect.spi.TransportService
TransportService.Capabilities - Class in com.sun.jdi.connect.spi
The transport service capabilities.
TransportService.Capabilities() - Constructor for class com.sun.jdi.connect.spi.TransportService.Capabilities
TransportService.ListenKey - Class in com.sun.jdi.connect.spi
A listen key.
TransportService.ListenKey() - Constructor for class com.sun.jdi.connect.spi.TransportService.ListenKey
TransportTimeoutException - Exception in com.sun.jdi.connect
This exception may be thrown as a result of a timeout when attaching to a target VM, or waiting to accept a connection from a target VM.
TransportTimeoutException() - Constructor for exception com.sun.jdi.connect.TransportTimeoutException
Constructs a TransportTimeoutException with no detail message.
TransportTimeoutException(String) - Constructor for exception com.sun.jdi.connect.TransportTimeoutException
Constructs a TransportTimeoutException with the specified detail message.
type() - Method in interface com.sun.jdi.Field
Returns the type of this field.
type() - Method in interface com.sun.jdi.LocalVariable
Returns the type of this variable.
Type - Interface in com.sun.jdi
The mirror for a type in the target VM.
type() - Method in interface com.sun.jdi.Value
Returns the run-time type of this value.
TypeComponent - Interface in com.sun.jdi
An entity declared within a user defined type (class or interface).
typeName() - Method in interface com.sun.jdi.Field
Returns a text representation of the type of this field.
typeName() - Method in interface com.sun.jdi.LocalVariable
Returns a text representation of the type of this variable.

U

uniqueID() - Method in interface com.sun.jdi.ObjectReference
Returns a unique identifier for this ObjectReference.

V

value() - Method in interface com.sun.jdi.BooleanValue
Returns this BooleanValue as a boolean.
value() - Method in interface com.sun.jdi.ByteValue
Returns this ByteValue as a byte.
value() - Method in interface com.sun.jdi.CharValue
Returns this CharValue as a char.
value() - Method in interface com.sun.jdi.connect.Connector.Argument
Returns the current value of the argument.
value() - Method in interface com.sun.jdi.DoubleValue
Returns this DoubleValue as a double.
value() - Method in interface com.sun.jdi.FloatValue
Returns this FloatValue as a float.
value() - Method in interface com.sun.jdi.IntegerValue
Returns this IntegerValue as an int.
value() - Method in interface com.sun.jdi.LongValue
Returns this LongValue as a long.
value() - Method in interface com.sun.jdi.ShortValue
Returns this ShortValue as a short.
value() - Method in interface com.sun.jdi.StringReference
Returns the StringReference as a String.
Value - Interface in com.sun.jdi
The mirror for a value in the target VM.
valueCurrent() - Method in interface com.sun.jdi.event.WatchpointEvent
Current value of the field.
valueToBe() - Method in interface com.sun.jdi.event.ModificationWatchpointEvent
Value that will be assigned to the field when the instruction completes.
variables() - Method in interface com.sun.jdi.Method
Returns a list containing each LocalVariable declared in this method.
variablesByName(String) - Method in interface com.sun.jdi.Method
Returns a list containing each LocalVariable of a given name in this method.
version() - Method in interface com.sun.jdi.VirtualMachine
Returns the version of the Java Runtime Environment in the target VM as reported by the property java.version.
virtualMachine() - Method in interface com.sun.jdi.Mirror
Gets the VirtualMachine to which this Mirror belongs.
VirtualMachine - Interface in com.sun.jdi
A virtual machine targeted for debugging.
virtualMachineManager() - Static method in class com.sun.jdi.Bootstrap
Returns the virtual machine manager.
VirtualMachineManager - Interface in com.sun.jdi
A manager of connections to target virtual machines.
visibleClasses() - Method in interface com.sun.jdi.ClassLoaderReference
Returns a list of all classes for which this class loader has been recorded as the initiating loader in the target VM.
visibleFields() - Method in interface com.sun.jdi.ReferenceType
Returns a list containing each unhidden and unambiguous Field in this type.
visibleMethods() - Method in interface com.sun.jdi.ReferenceType
Returns a list containing each Method declared or inherited by this type.
visibleVariableByName(String) - Method in interface com.sun.jdi.StackFrame
Finds a LocalVariable that matches the given name and is visible at the current frame location.
visibleVariables() - Method in interface com.sun.jdi.StackFrame
Returns a list containing each LocalVariable that can be accessed from this frame's location.
VMCannotBeModifiedException - Exception in com.sun.jdi
Thrown to indicate that the operation is invalid because it would modify the VM and the VM is read-only.
VMCannotBeModifiedException() - Constructor for exception com.sun.jdi.VMCannotBeModifiedException
VMCannotBeModifiedException(String) - Constructor for exception com.sun.jdi.VMCannotBeModifiedException
VMDeathEvent - Interface in com.sun.jdi.event
Notification of target VM termination.
VMDeathRequest - Interface in com.sun.jdi.request
Request for notification when the target VM terminates.
vmDeathRequests() - Method in interface com.sun.jdi.request.EventRequestManager
Return an unmodifiable list of the enabled and disabled VM death requests.
VMDisconnectedException - Exception in com.sun.jdi
Unchecked exception thrown to indicate that the requested operation cannot be completed because there is no longer a connection to the target VM.
VMDisconnectedException() - Constructor for exception com.sun.jdi.VMDisconnectedException
VMDisconnectedException(String) - Constructor for exception com.sun.jdi.VMDisconnectedException
VMDisconnectEvent - Interface in com.sun.jdi.event
Notification of disconnection from target VM.
VMMismatchException - Exception in com.sun.jdi
Thrown to indicate that the requested operation cannot be completed because the a mirror from one target VM is being combined with a mirror from another target VM.
VMMismatchException() - Constructor for exception com.sun.jdi.VMMismatchException
VMMismatchException(String) - Constructor for exception com.sun.jdi.VMMismatchException
VMOutOfMemoryException - Exception in com.sun.jdi
Thrown to indicate that the requested operation cannot be completed because the target VM has run out of memory.
VMOutOfMemoryException() - Constructor for exception com.sun.jdi.VMOutOfMemoryException
VMOutOfMemoryException(String) - Constructor for exception com.sun.jdi.VMOutOfMemoryException
VMStartEvent - Interface in com.sun.jdi.event
Notification of initialization of a target VM.
VMStartException - Exception in com.sun.jdi.connect
A target VM was successfully launched, but terminated with an error before a connection could be established.
VMStartException(Process) - Constructor for exception com.sun.jdi.connect.VMStartException
VMStartException(String, Process) - Constructor for exception com.sun.jdi.connect.VMStartException
VoidType - Interface in com.sun.jdi
The type of all primitive void values accessed in the target VM.
VoidValue - Interface in com.sun.jdi
Provides access to a primitive void value in the target VM.

W

waitingThreads() - Method in interface com.sun.jdi.ObjectReference
Returns a List containing a ThreadReference for each thread currently waiting for this object's monitor.
WatchpointEvent - Interface in com.sun.jdi.event
Notification of a field triggered event encountered by a thread in the target VM.
WatchpointRequest - Interface in com.sun.jdi.request
Identifies a Field in the target VM being watched.
writePacket(byte[]) - Method in class com.sun.jdi.connect.spi.Connection
Writes a packet to the target VM.
A B C D E F G H I J L M N O P R S T U V W
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Java Debug Interface

Frame Alert

This document is designed to be viewed using the frames feature. If you see this message, you are using a non-frame-capable web client.
Link toNon-frame version.


Serialized Form

Package com.sun.jdi

Class com.sun.jdi.AbsentInformationException extends Exception implements Serializable

Class com.sun.jdi.ClassNotLoadedException extends Exception implements Serializable

Serialized Fields

className

String className

Class com.sun.jdi.ClassNotPreparedException extends RuntimeException implements Serializable

Class com.sun.jdi.IncompatibleThreadStateException extends Exception implements Serializable

Class com.sun.jdi.InconsistentDebugInfoException extends RuntimeException implements Serializable

Class com.sun.jdi.InternalException extends RuntimeException implements Serializable

Serialized Fields

errorCode

int errorCode

Class com.sun.jdi.InvalidCodeIndexException extends RuntimeException implements Serializable

Class com.sun.jdi.InvalidLineNumberException extends RuntimeException implements Serializable

Class com.sun.jdi.InvalidStackFrameException extends RuntimeException implements Serializable

Class com.sun.jdi.InvalidTypeException extends Exception implements Serializable

Class com.sun.jdi.InvocationException extends Exception implements Serializable

Serialized Fields

exception

ObjectReference exception

Class com.sun.jdi.JDIPermission extends BasicPermission implements Serializable

Class com.sun.jdi.NativeMethodException extends RuntimeException implements Serializable

Class com.sun.jdi.ObjectCollectedException extends RuntimeException implements Serializable

Class com.sun.jdi.VMCannotBeModifiedException extends UnsupportedOperationException implements Serializable

Class com.sun.jdi.VMDisconnectedException extends RuntimeException implements Serializable

Class com.sun.jdi.VMMismatchException extends RuntimeException implements Serializable

Class com.sun.jdi.VMOutOfMemoryException extends RuntimeException implements Serializable

Package com.sun.jdi.connect

Class com.sun.jdi.connect.IllegalConnectorArgumentsException extends Exception implements Serializable

Serialized Fields

names

List<E> names

Class com.sun.jdi.connect.TransportTimeoutException extends IOException implements Serializable

Class com.sun.jdi.connect.VMStartException extends Exception implements Serializable

Serialized Fields

process

Process process
Package com.sun.jdi.connect.spi

Class com.sun.jdi.connect.spi.ClosedConnectionException extends IOException implements Serializable

Package com.sun.jdi.request

Class com.sun.jdi.request.DuplicateRequestException extends RuntimeException implements Serializable

Class com.sun.jdi.request.InvalidRequestStateException extends RuntimeException implements Serializable

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


jdi

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package com.sun.jdi

This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

See:
Description

Interface Summary
Accessible | Provides information on the accessibility of a type or type component.
ArrayReference | Provides access to an array object and its components in the target VM.
ArrayType | Provides access to the class of an array and the type of its components in the target VM.
BooleanType | The type of all primitive boolean values accessed in the target VM.
BooleanValue | Provides access to a primitive boolean value in the target VM.
ByteType | The type of all primitive byte values accessed in the target VM.
ByteValue | Provides access to a primitive byte value in the target VM.
CharType | The type of all primitive char values accessed in the target VM.
CharValue | Provides access to a primitive char value in the target VM.
ClassLoaderReference | A class loader object from the target VM.
ClassObjectReference | An instance of java.lang.Class from the target VM.
ClassType | A mirror of a class in the target VM.
DoubleType | The type of all primitive double values accessed in the target VM.
DoubleValue | Provides access to a primitive double value in the target VM.
Field | A class or instance variable in the target VM.
FloatType | The type of all primitive float values accessed in the target VM.
FloatValue | Provides access to a primitive float value in the target VM.
IntegerType | The type of all primitive int values accessed in the target VM.
IntegerValue | Provides access to a primitive int value in the target VM.
InterfaceType | A mirror of an interface in the target VM.
LocalVariable | A local variable in the target VM.
Locatable | A mirror that has a Location.
Location | A point within the executing code of the target VM.
LongType | The type of all primitive long values accessed in the target VM.
LongValue | Provides access to a primitive long value in the target VM.
Method | A static or instance method in the target VM.
Mirror | A proxy used by a debugger to examine or manipulate some entity in another virtual machine.
MonitorInfo | Information about a monitor owned by a thread.
ObjectReference | An object that currently exists in the target VM.
PathSearchingVirtualMachine | A virtual machine which searches for classes through paths
PrimitiveType | The type associated with non-object values in a target VM.
PrimitiveValue | The value assigned to a field or variable of primitive type in a target VM.
ReferenceType | The type of an object in a target VM.
ShortType | The type of all primitive short values accessed in the target VM.
ShortValue | Provides access to a primitive short value in the target VM.
StackFrame | The state of one method invocation on a thread's call stack.
StringReference | A string object from the target VM.
ThreadGroupReference | A thread group object from the target VM.
ThreadReference | A thread object from the target VM.
Type | The mirror for a type in the target VM.
TypeComponent | An entity declared within a user defined type (class or interface).
Value | The mirror for a value in the target VM.
VirtualMachine | A virtual machine targeted for debugging.
VirtualMachineManager | A manager of connections to target virtual machines.
VoidType | The type of all primitive void values accessed in the target VM.
VoidValue | Provides access to a primitive void value in the target VM.

Class Summary
Bootstrap | Initial class that provides access to the default implementation of JDI interfaces.
JDIPermission | The JDIPermission class represents access rights to the VirtualMachineManager.

Exception Summary
AbsentInformationException | Thrown to indicate line number or variable information is not available.
ClassNotLoadedException | Thrown to indicate that the requested class has not yet been loaded through the appropriate class loader.
ClassNotPreparedException | Thrown to indicate that the requested operation cannot be completed because the specified class has not yet been prepared.
IncompatibleThreadStateException | Thrown to indicate that the requested operation cannot be completed while the specified thread is in its current state.
InconsistentDebugInfoException | Thrown to indicate that there is an inconistency in the debug information provided by the target VM.
InternalException | Thrown to indicate that an unexpected internal error has occurred.
InvalidCodeIndexException | Deprecated. This exception is no longer thrown
InvalidLineNumberException | Deprecated. This exception is no longer thrown
InvalidStackFrameException | Thrown to indicate that the requested operation cannot be completed because the specified stack frame is no longer valid.
InvalidTypeException | Thrown to indicate a type mismatch in setting the value of a field or variable, or in specifying the return value of a method.
InvocationException | Thrown to indicate an exception occurred in an invoked method within the target VM.
NativeMethodException | Thrown to indicate an operation cannot be completed because it is not valid for a native method.
ObjectCollectedException | Thrown to indicate that the requested operation cannot be completed because the specified object has been garbage collected.
VMCannotBeModifiedException | Thrown to indicate that the operation is invalid because it would modify the VM and the VM is read-only.
VMDisconnectedException | Unchecked exception thrown to indicate that the requested operation cannot be completed because there is no longer a connection to the target VM.
VMMismatchException | Thrown to indicate that the requested operation cannot be completed because the a mirror from one target VM is being combined with a mirror from another target VM.
VMOutOfMemoryException | Thrown to indicate that the requested operation cannot be completed because the target VM has run out of memory.

Package com.sun.jdi Description

This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities. VirtualMachine mirrors the target virtual machine and is the origin of all information provided by the JDI. A VirtualMachine is typically created by using the VirtualMachineManager to create a connection to the target virtual machine (see the com.sun.jdi.connect package). In turn the VirtualMachineManager is typically created by calling Bootstrap.virtualMachineManager().

Most of the methods within this package can throw the unchecked exception VMDisconnectedException.

Methods may be added to the interfaces in the JDI packages in future releases. Existing packages may be renamed if the JDI becomes a standard extension.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


BooleanType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface BooleanType

All Superinterfaces:
Mirror, PrimitiveType, Type
public interface BooleanType
extends PrimitiveType

The type of all primitive boolean values accessed in the target VM. Calls to Value.type() will return an implementor of this interface.

Since:
1.3
See Also:
BooleanValue

Method Summary
Methods inherited from interface com.sun.jdi.Type
name, signature
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ByteType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface ByteType

All Superinterfaces:
Mirror, PrimitiveType, Type
public interface ByteType
extends PrimitiveType

The type of all primitive byte values accessed in the target VM. Calls to Value.type() will return an implementor of this interface.

Since:
1.3
See Also:
ByteValue

Method Summary
Methods inherited from interface com.sun.jdi.Type
name, signature
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CharType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface CharType

All Superinterfaces:
Mirror, PrimitiveType, Type
public interface CharType
extends PrimitiveType

The type of all primitive char values accessed in the target VM. Calls to Value.type() will return an implementor of this interface.

Since:
1.3
See Also:
CharValue

Method Summary
Methods inherited from interface com.sun.jdi.Type
name, signature
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


com.sun.jdi Class Hierarchy

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Hierarchy For Package com.sun.jdi

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • com.sun.jdi.Bootstrap
    • java.security.Permission (implements java.security.Guard, java.io.Serializable)
      • java.security.BasicPermission (implements java.io.Serializable)
        • com.sun.jdi.JDIPermission
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • com.sun.jdi.AbsentInformationException
        • com.sun.jdi.ClassNotLoadedException
        • com.sun.jdi.IncompatibleThreadStateException
        • com.sun.jdi.InvalidTypeException
        • com.sun.jdi.InvocationException
        • java.lang.RuntimeException
          • com.sun.jdi.ClassNotPreparedException
          • com.sun.jdi.InconsistentDebugInfoException
          • com.sun.jdi.InternalException
          • com.sun.jdi.InvalidCodeIndexException
          • com.sun.jdi.InvalidLineNumberException
          • com.sun.jdi.InvalidStackFrameException
          • com.sun.jdi.NativeMethodException
          • com.sun.jdi.ObjectCollectedException
          • java.lang.UnsupportedOperationException
            • com.sun.jdi.VMCannotBeModifiedException
          • com.sun.jdi.VMDisconnectedException
          • com.sun.jdi.VMMismatchException
          • com.sun.jdi.VMOutOfMemoryException

Interface Hierarchy

  • com.sun.jdi.Accessible
    • com.sun.jdi.ReferenceType (also extends java.lang.Comparable<T>, com.sun.jdi.Type)
      • com.sun.jdi.ArrayType
      • com.sun.jdi.ClassType
      • com.sun.jdi.InterfaceType
    • com.sun.jdi.TypeComponent (also extends com.sun.jdi.Mirror)
      • com.sun.jdi.Field (also extends java.lang.Comparable<T>)
      • com.sun.jdi.Method (also extends java.lang.Comparable<T>, com.sun.jdi.Locatable)
  • java.lang.Comparable<T>
    • com.sun.jdi.ByteValue (also extends com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.CharValue (also extends com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.DoubleValue (also extends com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.Field (also extends com.sun.jdi.TypeComponent)
    • com.sun.jdi.FloatValue (also extends com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.IntegerValue (also extends com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.LocalVariable (also extends com.sun.jdi.Mirror)
    • com.sun.jdi.Location (also extends com.sun.jdi.Mirror)
    • com.sun.jdi.LongValue (also extends com.sun.jdi.PrimitiveValue)
    • com.sun.jdi.Method (also extends com.sun.jdi.Locatable, com.sun.jdi.TypeComponent)
    • com.sun.jdi.ReferenceType (also extends com.sun.jdi.Accessible, com.sun.jdi.Type)
      • com.sun.jdi.ArrayType
      • com.sun.jdi.ClassType
      • com.sun.jdi.InterfaceType
    • com.sun.jdi.ShortValue (also extends com.sun.jdi.PrimitiveValue)
  • com.sun.jdi.Locatable
    • com.sun.jdi.Method (also extends java.lang.Comparable<T>, com.sun.jdi.TypeComponent)
    • com.sun.jdi.StackFrame (also extends com.sun.jdi.Mirror)
  • com.sun.jdi.Mirror
    • com.sun.jdi.LocalVariable (also extends java.lang.Comparable<T>)
    • com.sun.jdi.Location (also extends java.lang.Comparable<T>)
    • com.sun.jdi.MonitorInfo
    • com.sun.jdi.StackFrame (also extends com.sun.jdi.Locatable)
    • com.sun.jdi.Type
      • com.sun.jdi.PrimitiveType
        • com.sun.jdi.BooleanType
        • com.sun.jdi.ByteType
        • com.sun.jdi.CharType
        • com.sun.jdi.DoubleType
        • com.sun.jdi.FloatType
        • com.sun.jdi.IntegerType
        • com.sun.jdi.LongType
        • com.sun.jdi.ShortType
      • com.sun.jdi.ReferenceType (also extends com.sun.jdi.Accessible, java.lang.Comparable<T>)
        • com.sun.jdi.ArrayType
        • com.sun.jdi.ClassType
        • com.sun.jdi.InterfaceType
      • com.sun.jdi.VoidType
    • com.sun.jdi.TypeComponent (also extends com.sun.jdi.Accessible)
      • com.sun.jdi.Field (also extends java.lang.Comparable<T>)
      • com.sun.jdi.Method (also extends java.lang.Comparable<T>, com.sun.jdi.Locatable)
    • com.sun.jdi.Value
      • com.sun.jdi.ObjectReference
        • com.sun.jdi.ArrayReference
        • com.sun.jdi.ClassLoaderReference
        • com.sun.jdi.ClassObjectReference
        • com.sun.jdi.StringReference
        • com.sun.jdi.ThreadGroupReference
        • com.sun.jdi.ThreadReference
      • com.sun.jdi.PrimitiveValue
        • com.sun.jdi.BooleanValue
        • com.sun.jdi.ByteValue (also extends java.lang.Comparable<T>)
        • com.sun.jdi.CharValue (also extends java.lang.Comparable<T>)
        • com.sun.jdi.DoubleValue (also extends java.lang.Comparable<T>)
        • com.sun.jdi.FloatValue (also extends java.lang.Comparable<T>)
        • com.sun.jdi.IntegerValue (also extends java.lang.Comparable<T>)
        • com.sun.jdi.LongValue (also extends java.lang.Comparable<T>)
        • com.sun.jdi.ShortValue (also extends java.lang.Comparable<T>)
      • com.sun.jdi.VoidValue
    • com.sun.jdi.VirtualMachine
      • com.sun.jdi.PathSearchingVirtualMachine
  • com.sun.jdi.VirtualMachineManager
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


DoubleType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface DoubleType

All Superinterfaces:
Mirror, PrimitiveType, Type
public interface DoubleType
extends PrimitiveType

The type of all primitive double values accessed in the target VM. Calls to Value.type() will return an implementor of this interface.

Since:
1.3
See Also:
DoubleValue

Method Summary
Methods inherited from interface com.sun.jdi.Type
name, signature
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FloatType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface FloatType

All Superinterfaces:
Mirror, PrimitiveType, Type
public interface FloatType
extends PrimitiveType

The type of all primitive float values accessed in the target VM. Calls to Value.type() will return an implementor of this interface.

Since:
1.3
See Also:
FloatValue

Method Summary
Methods inherited from interface com.sun.jdi.Type
name, signature
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IntegerType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface IntegerType

All Superinterfaces:
Mirror, PrimitiveType, Type
public interface IntegerType
extends PrimitiveType

The type of all primitive int values accessed in the target VM. Calls to Value.type() will return an implementor of this interface.

Since:
1.3
See Also:
IntegerValue

Method Summary
Methods inherited from interface com.sun.jdi.Type
name, signature
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LongType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface LongType

All Superinterfaces:
Mirror, PrimitiveType, Type
public interface LongType
extends PrimitiveType

The type of all primitive long values accessed in the target VM. Calls to Value.type() will return an implementor of this interface.

Since:
1.3
See Also:
LongValue

Method Summary
Methods inherited from interface com.sun.jdi.Type
name, signature
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrimitiveType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface PrimitiveType

All Superinterfaces:
Mirror, Type
All Known Subinterfaces:
BooleanType, ByteType, CharType, DoubleType, FloatType, IntegerType, LongType, ShortType
public interface PrimitiveType
extends Type

The type associated with non-object values in a target VM. Instances of one of the sub-interfaces of this interface will be returned from Value.type() for all PrimitiveValue objects.

Since:
1.3
See Also:
PrimitiveValue

Method Summary
Methods inherited from interface com.sun.jdi.Type
name, signature
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ShortType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface ShortType

All Superinterfaces:
Mirror, PrimitiveType, Type
public interface ShortType
extends PrimitiveType

The type of all primitive short values accessed in the target VM. Calls to Value.type() will return an implementor of this interface.

Since:
1.3
See Also:
LongValue

Method Summary
Methods inherited from interface com.sun.jdi.Type
name, signature
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Package com.sun.jdi

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Package
com.sun.jdi

Packages that use com.sun.jdi
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.connect | This package defines connections between the virtual machine using the JDI and the target virtual machine.
com.sun.jdi.event | This package defines JDI events and event processing.
com.sun.jdi.request | This package is used to request that a JDI event be sent under specified conditions.

Classes in com.sun.jdi used by com.sun.jdi
AbsentInformationException
Thrown to indicate line number or variable information is not available.
Accessible
Provides information on the accessibility of a type or type component.
ArrayReference
Provides access to an array object and its components in the target VM.
BooleanValue
Provides access to a primitive boolean value in the target VM.
ByteValue
Provides access to a primitive byte value in the target VM.
CharValue
Provides access to a primitive char value in the target VM.
ClassLoaderReference
A class loader object from the target VM.
ClassNotLoadedException
Thrown to indicate that the requested class has not yet been loaded through the appropriate class loader.
ClassObjectReference
An instance of java.lang.Class from the target VM.
ClassType
A mirror of a class in the target VM.
DoubleValue
Provides access to a primitive double value in the target VM.
Field
A class or instance variable in the target VM.
FloatValue
Provides access to a primitive float value in the target VM.
IncompatibleThreadStateException
Thrown to indicate that the requested operation cannot be completed while the specified thread is in its current state.
IntegerValue
Provides access to a primitive int value in the target VM.
InterfaceType
A mirror of an interface in the target VM.
InvalidTypeException
Thrown to indicate a type mismatch in setting the value of a field or variable, or in specifying the return value of a method.
InvocationException
Thrown to indicate an exception occurred in an invoked method within the target VM.
LocalVariable
A local variable in the target VM.
Locatable
A mirror that has a Location.
Location
A point within the executing code of the target VM.
LongValue
Provides access to a primitive long value in the target VM.
Method
A static or instance method in the target VM.
Mirror
A proxy used by a debugger to examine or manipulate some entity in another virtual machine.
MonitorInfo
Information about a monitor owned by a thread.
ObjectReference
An object that currently exists in the target VM.
PrimitiveType
The type associated with non-object values in a target VM.
PrimitiveValue
The value assigned to a field or variable of primitive type in a target VM.
ReferenceType
The type of an object in a target VM.
ShortValue
Provides access to a primitive short value in the target VM.
StackFrame
The state of one method invocation on a thread's call stack.
StringReference
A string object from the target VM.
ThreadGroupReference
A thread group object from the target VM.
ThreadReference
A thread object from the target VM.
Type
The mirror for a type in the target VM.
TypeComponent
An entity declared within a user defined type (class or interface).
Value
The mirror for a value in the target VM.
VirtualMachine
A virtual machine targeted for debugging.
VirtualMachineManager
A manager of connections to target virtual machines.
VoidValue
Provides access to a primitive void value in the target VM.

Classes in com.sun.jdi used by com.sun.jdi.connect
VirtualMachine
A virtual machine targeted for debugging.

Classes in com.sun.jdi used by com.sun.jdi.event
Field
A class or instance variable in the target VM.
Locatable
A mirror that has a Location.
Location
A point within the executing code of the target VM.
Method
A static or instance method in the target VM.
Mirror
A proxy used by a debugger to examine or manipulate some entity in another virtual machine.
ObjectReference
An object that currently exists in the target VM.
ReferenceType
The type of an object in a target VM.
ThreadReference
A thread object from the target VM.
Value
The mirror for a value in the target VM.

Classes in com.sun.jdi used by com.sun.jdi.request
Field
A class or instance variable in the target VM.
Locatable
A mirror that has a Location.
Location
A point within the executing code of the target VM.
Mirror
A proxy used by a debugger to examine or manipulate some entity in another virtual machine.
ObjectReference
An object that currently exists in the target VM.
ReferenceType
The type of an object in a target VM.
ThreadReference
A thread object from the target VM.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


VoidType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface VoidType

All Superinterfaces:
Mirror, Type
public interface VoidType
extends Type

The type of all primitive void values accessed in the target VM. Calls to Value.type() will return an implementor of this interface.

Since:
1.3
See Also:
VoidValue

Method Summary
Methods inherited from interface com.sun.jdi.Type
name, signature
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


AbsentInformationException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class AbsentInformationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  com.sun.jdi.AbsentInformationException
All Implemented Interfaces:
Serializable
public class AbsentInformationException
extends Exception

Thrown to indicate line number or variable information is not available.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
AbsentInformationException()
AbsentInformationException(String s)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AbsentInformationException

public AbsentInformationException()

AbsentInformationException

public AbsentInformationException(String s)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Accessible

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface Accessible

All Known Subinterfaces:
ArrayType, ClassType, Field, InterfaceType, Method, ReferenceType, TypeComponent
public interface Accessible

Provides information on the accessibility of a type or type component. Mirrors for program elements which allow an an access specifier (private, protected, public) provide information on that part of the declaration through this interface.

Since:
1.3

Method Summary
boolean | isPackagePrivate() Determines if this object mirrors a package private item.
boolean | isPrivate() Determines if this object mirrors a private item.
boolean | isProtected() Determines if this object mirrors a protected item.
boolean | isPublic() Determines if this object mirrors a public item.
int | modifiers() Returns the JavaTM programming language modifiers, encoded in an integer.

Method Detail

modifiers

int modifiers()
Returns the JavaTM programming language modifiers, encoded in an integer.

The modifier encodings are defined in the Java Virtual Machine Specification, in the access_flag tables for classes, fields, and methods.

isPrivate

boolean isPrivate()
Determines if this object mirrors a private item. For ArrayType, the return value depends on the array component type. For primitive arrays the return value is always false. For object arrays, the return value is the same as would be returned for the component type. For primitive classes, such as Integer.TYPE, the return value is always false.

Returns:
true for items with private access; false otherwise.

isPackagePrivate

boolean isPackagePrivate()
Determines if this object mirrors a package private item. A package private item is declared with no access specifier. For ArrayType, the return value depends on the array component type. For primitive arrays the return value is always false. For object arrays, the return value is the same as would be returned for the component type. For primitive classes, such as Integer.TYPE, the return value is always false.

Returns:
true for items with package private access; false otherwise.

isProtected

boolean isProtected()
Determines if this object mirrors a protected item. For ArrayType, the return value depends on the array component type. For primitive arrays the return value is always false. For object arrays, the return value is the same as would be returned for the component type. For primitive classes, such as Integer.TYPE, the return value is always false.

Returns:
true for items with private access; false otherwise.

isPublic

boolean isPublic()
Determines if this object mirrors a public item. For ArrayType, the return value depends on the array component type. For primitive arrays the return value is always true. For object arrays, the return value is the same as would be returned for the component type. For primitive classes, such as Integer.TYPE, the return value is always true.

Returns:
true for items with public access; false otherwise.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ArrayReference

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface ArrayReference

All Superinterfaces:
Mirror, ObjectReference, Value
public interface ArrayReference
extends ObjectReference

Provides access to an array object and its components in the target VM. Each array component is mirrored by a Value object. The array components, in aggregate, are placed in List objects instead of arrays for consistency with the rest of the API and for interoperability with other APIs.

Since:
1.3

Field Summary
Fields inherited from interface com.sun.jdi.ObjectReference
INVOKE_NONVIRTUAL, INVOKE_SINGLE_THREADED
Method Summary
Value | getValue(int index) Returns an array component value.
List<Value> | getValues() Returns all of the components in this array.
List<Value> | getValues(int index, int length) Returns a range of array components.
int | length() Returns the number of components in this array.
void | setValue(int index, Value value) Replaces an array component with another value.
void | setValues(int index, List<? extends Value> values, int srcIndex, int length) Replaces a range of array components with other values.
void | setValues(List<? extends Value> values) Replaces all array components with other values.
Methods inherited from interface com.sun.jdi.ObjectReference
disableCollection, enableCollection, entryCount, equals, getValue, getValues, hashCode, invokeMethod, isCollected, owningThread, referenceType, referringObjects, setValue, uniqueID, waitingThreads
Methods inherited from interface com.sun.jdi.Value
type
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

length

int length()
Returns the number of components in this array.

Returns:
the integer count of components in this array.

getValue

Value getValue(int index)
Returns an array component value.

Parameters:
index - the index of the component to retrieve
Returns:
the Value at the given index.
Throws:
IndexOutOfBoundsException - if index is outside the range of this array, that is, if either of the following are true:
    index < 0
    index >= length()

getValues

List<Value> getValues()
Returns all of the components in this array.

Returns:
a list of Value objects, one for each array component ordered by array index. For zero length arrays, an empty list is returned.

getValues

List<Value> getValues(int index,
                      int length)
Returns a range of array components.

Parameters:
index - the index of the first component to retrieve
length - the number of components to retrieve, or -1 to retrieve all components to the end of this array.
Returns:
a list of Value objects, one for each requested array component ordered by array index. When there are no elements in the specified range (e.g. length is zero) an empty list is returned
Throws:
IndexOutOfBoundsException - if the range specified with index and length is not within the range of the array, that is, if either of the following are true:
    index < 0
    index > length()
or if length != -1 and either of the following are true:
    length < 0
    index + length >  length()

setValue

void setValue(int index,
              Value value)
              throws InvalidTypeException,
                     ClassNotLoadedException
Replaces an array component with another value.

Object values must be assignment compatible with the component type (This implies that the component type must be loaded through the declaring class's class loader). Primitive values must be either assignment compatible with the component type or must be convertible to the component type without loss of information. See JLS section 5.2 for more information on assignment compatibility.

Parameters:
value - the new value
index - the index of the component to set
Throws:
IndexOutOfBoundsException - if index is outside the range of this array, that is, if either of the following are true:
    index < 0
    index >= length()
InvalidTypeException - if the type of value is not compatible with the declared type of array components.
ClassNotLoadedException - if the array component type has not yet been loaded through the appropriate class loader.
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().
See Also:
ArrayType.componentType()

setValues

void setValues(List<? extends Value> values)
               throws InvalidTypeException,
                      ClassNotLoadedException
Replaces all array components with other values. If the given list is larger in size than the array, the values at the end of the list are ignored.

Object values must be assignment compatible with the element type (This implies that the component type must be loaded through the enclosing class's class loader). Primitive values must be either assignment compatible with the component type or must be convertible to the component type without loss of information. See JLS section 5.2 for more information on assignment compatibility.

Parameters:
values - a list of Value objects to be placed in this array. If values.size() is less that the length of the array, the first values.size() elements are set.
Throws:
InvalidTypeException - if any of the new values is not compatible with the declared type of array components.
ClassNotLoadedException - if the array component type has not yet been loaded through the appropriate class loader.
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().
See Also:
ArrayType.componentType()

setValues

void setValues(int index,
               List<? extends Value> values,
               int srcIndex,
               int length)
               throws InvalidTypeException,
                      ClassNotLoadedException
Replaces a range of array components with other values.

Object values must be assignment compatible with the component type (This implies that the component type must be loaded through the enclosing class's class loader). Primitive values must be either assignment compatible with the component type or must be convertible to the component type without loss of information. See JLS section 5.2 for more information on assignment compatibility.

Parameters:
index - the index of the first component to set.
values - a list of Value objects to be placed in this array.
srcIndex - the index of the first source value to use.
length - the number of components to set, or -1 to set all components to the end of this array or the end of values (whichever comes first).
Throws:
InvalidTypeException - if any element of values is not compatible with the declared type of array components.
IndexOutOfBoundsException - if the array range specified with index and length is not within the range of the array, or if the source range specified with srcIndex and length is not within values, that is, if any of the following are true:
    index < 0
    index > length()
    srcIndex < 0
    srcIndex > values.size()
or if length != -1 and any of the following are true:
    length < 0
    index + length > length()
    srcIndex + length > values.size()
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().
ClassNotLoadedException
See Also:
ArrayType.componentType()
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ArrayType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface ArrayType

All Superinterfaces:
Accessible, Comparable<ReferenceType>, Mirror, ReferenceType, Type
public interface ArrayType
extends ReferenceType

Provides access to the class of an array and the type of its components in the target VM.

Since:
1.3
See Also:
ArrayReference

Method Summary
String | componentSignature() Gets the JNI signature of the components of this array class.
Type | componentType() Returns the component type of this array, as specified in the array declaration.
String | componentTypeName() Returns a text representation of the component type of this array.
ArrayReference | newInstance(int length) Creates a new instance of this array class in the target VM.
Methods inherited from interface com.sun.jdi.ReferenceType
allFields, allLineLocations, allLineLocations, allMethods, availableStrata, classLoader, classObject, constantPool, constantPoolCount, defaultStratum, equals, failedToInitialize, fieldByName, fields, genericSignature, getValue, getValues, hashCode, instances, isAbstract, isFinal, isInitialized, isPrepared, isStatic, isVerified, locationsOfLine, locationsOfLine, majorVersion, methods, methodsByName, methodsByName, minorVersion, name, nestedTypes, sourceDebugExtension, sourceName, sourceNames, sourcePaths, visibleFields, visibleMethods
Methods inherited from interface com.sun.jdi.Type
signature
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface java.lang.Comparable
compareTo
Methods inherited from interface com.sun.jdi.Accessible
isPackagePrivate, isPrivate, isProtected, isPublic, modifiers

Method Detail

newInstance

ArrayReference newInstance(int length)
Creates a new instance of this array class in the target VM. The array is created with the given length and each component is initialized to is standard default value.

Parameters:
length - the number of components in the new array
Returns:
the newly created ArrayReference mirroring the new object in the target VM.
Throws:
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().

componentSignature

String componentSignature()
Gets the JNI signature of the components of this array class. The signature describes the declared type of the components. If the components are objects, their actual type in a particular run-time context may be a subclass of the declared class.

Returns:
a string containing the JNI signature of array components.

componentTypeName

String componentTypeName()
Returns a text representation of the component type of this array.

Returns:
a text representation of the component type.

componentType

Type componentType()
                   throws ClassNotLoadedException
Returns the component type of this array, as specified in the array declaration.

Note: The component type of a array will always be created or loaded before the array - see the Java Virtual Machine Specification, section 5.3.3 Creating Array Classes. However, although the component type will be loaded it may not yet be prepared, in which case the type will be returned but attempts to perform some operations on the returned type (e.g. fields()) will throw a ClassNotPreparedException. Use ReferenceType.isPrepared() to determine if a reference type is prepared.

Returns:
the Type of this array's components.
Throws:
ClassNotLoadedException
See Also:
Type, Field.type() - for usage examples
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BooleanValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface BooleanValue

All Superinterfaces:
Mirror, PrimitiveValue, Value
public interface BooleanValue
extends PrimitiveValue

Provides access to a primitive boolean value in the target VM.

Since:
1.3

Method Summary
boolean | equals(Object obj) Compares the specified Object with this BooleanValue for equality.
int | hashCode() Returns the hash code value for this BooleanValue.
boolean | value() Returns this BooleanValue as a boolean.
Methods inherited from interface com.sun.jdi.PrimitiveValue
booleanValue, byteValue, charValue, doubleValue, floatValue, intValue, longValue, shortValue
Methods inherited from interface com.sun.jdi.Value
type
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

value

boolean value()
Returns this BooleanValue as a boolean.

Returns:
the boolean mirrored by this object.

equals

boolean equals(Object obj)
Compares the specified Object with this BooleanValue for equality.

Overrides:
equals in class Object
Returns:
true if the Object is a BooleanValue and if applying "==" to the two mirrored primitives would evaluate to true; false otherwise.

hashCode

int hashCode()
Returns the hash code value for this BooleanValue.

Overrides:
hashCode in class Object
Returns:
the integer hash code
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Bootstrap

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class Bootstrap

java.lang.Object
    extended by  com.sun.jdi.Bootstrap

public class Bootstrap
extends Object

Initial class that provides access to the default implementation of JDI interfaces. A debugger application uses this class to access the single instance of the VirtualMachineManager interface.

Since:
1.3

Constructor Summary
Bootstrap()
Method Summary
static VirtualMachineManager virtualMachineManager()
Returns the virtual machine manager.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Bootstrap

public Bootstrap()
Method Detail

virtualMachineManager

public static VirtualMachineManager virtualMachineManager()
Returns the virtual machine manager.

May throw an unspecified error if initialization of the VirtualMachineManager fails or if the virtual machine manager is unable to locate or create any Connectors.

@exception SecurityException if a security manager has been installed and it denies JDIPermission ("virtualMachineManager") or other unspecified permissions required by the implementation.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ByteValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface ByteValue

All Superinterfaces:
Comparable<ByteValue>, Mirror, PrimitiveValue, Value
public interface ByteValue
extends PrimitiveValue, Comparable<ByteValue>

Provides access to a primitive byte value in the target VM.

Since:
1.3

Method Summary
boolean | equals(Object obj) Compares the specified Object with this ByteValue for equality.
int | hashCode() Returns the hash code value for this BooleanValue.
byte | value() Returns this ByteValue as a byte.
Methods inherited from interface com.sun.jdi.PrimitiveValue
booleanValue, byteValue, charValue, doubleValue, floatValue, intValue, longValue, shortValue
Methods inherited from interface com.sun.jdi.Value
type
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface java.lang.Comparable
compareTo

Method Detail

value

byte value()
Returns this ByteValue as a byte.

Returns:
the byte mirrored by this object.

equals

boolean equals(Object obj)
Compares the specified Object with this ByteValue for equality.

Overrides:
equals in class Object
Returns:
true if the Object is a ByteValue and if applying "==" to the two mirrored primitives would evaluate to true; false otherwise.

hashCode

int hashCode()
Returns the hash code value for this BooleanValue.

Overrides:
hashCode in class Object
Returns:
the integer hash code
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


CharValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface CharValue

All Superinterfaces:
Comparable<CharValue>, Mirror, PrimitiveValue, Value
public interface CharValue
extends PrimitiveValue, Comparable<CharValue>

Provides access to a primitive char value in the target VM.

Since:
1.3

Method Summary
boolean | equals(Object obj) Compares the specified Object with this CharValue for equality.
int | hashCode() Returns the hash code value for this CharValue.
char | value() Returns this CharValue as a char.
Methods inherited from interface com.sun.jdi.PrimitiveValue
booleanValue, byteValue, charValue, doubleValue, floatValue, intValue, longValue, shortValue
Methods inherited from interface com.sun.jdi.Value
type
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface java.lang.Comparable
compareTo

Method Detail

value

char value()
Returns this CharValue as a char.

Returns:
the char mirrored by this object.

equals

boolean equals(Object obj)
Compares the specified Object with this CharValue for equality.

Overrides:
equals in class Object
Returns:
true if the Object is a CharValue and if applying "==" to the two mirrored primitives would evaluate to true; false otherwise.

hashCode

int hashCode()
Returns the hash code value for this CharValue.

Overrides:
hashCode in class Object
Returns:
the integer hash code
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class com.sun.jdi.AbsentInformationException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.AbsentInformationException

Packages that use AbsentInformationException
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of AbsentInformationException in com.sun.jdi

Methods in com.sun.jdi that throw AbsentInformationException
List<Location> | Method.allLineLocations() Returns a list containing a Location object for each executable source line in this method.
List<Location> | ReferenceType.allLineLocations() Returns a list containing a Location object for each executable source line in this reference type.
List<Location> | Method.allLineLocations(String stratum, String sourceName) Returns a list containing a Location object for each executable source line in this method.
List<Location> | ReferenceType.allLineLocations(String stratum, String sourceName) Returns a list containing a Location object for each executable source line in this reference type.
List<LocalVariable> | Method.arguments() Returns a list containing each LocalVariable that is declared as an argument of this method.
List<Location> | Method.locationsOfLine(int lineNumber) Returns a List containing all Location objects that map to the given line number.
List<Location> | ReferenceType.locationsOfLine(int lineNumber) Returns a List containing all Location objects that map to the given line number.
List<Location> | Method.locationsOfLine(String stratum, String sourceName, int lineNumber) Returns a List containing all Location objects that map to the given line number and source name.
List<Location> | ReferenceType.locationsOfLine(String stratum, String sourceName, int lineNumber) Returns a List containing all Location objects that map to the given line number.
String | ReferenceType.sourceDebugExtension() Get the source debug extension of this type.
String | Location.sourceName() Gets an identifing name for the source corresponding to this location.
String | ReferenceType.sourceName() Gets an identifying name for the source corresponding to the declaration of this type.
String | Location.sourceName(String stratum) Gets an identifing name for the source corresponding to this location.
List<String> | ReferenceType.sourceNames(String stratum) Gets the identifying names for all the source corresponding to the declaration of this type.
String | Location.sourcePath() Gets the path to the source corresponding to this location.
String | Location.sourcePath(String stratum) Gets the path to the source corresponding to this location.
List<String> | ReferenceType.sourcePaths(String stratum) Gets the paths to the source corresponding to the declaration of this type.
List<LocalVariable> | Method.variables() Returns a list containing each LocalVariable declared in this method.
List<LocalVariable> | Method.variablesByName(String name) Returns a list containing each LocalVariable of a given name in this method.
LocalVariable | StackFrame.visibleVariableByName(String name) Finds a LocalVariable that matches the given name and is visible at the current frame location.
List<LocalVariable> | StackFrame.visibleVariables() Returns a list containing each LocalVariable that can be accessed from this frame's location.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.Bootstrap

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.Bootstrap

No usage of com.sun.jdi.Bootstrap

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.ClassNotLoadedException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.ClassNotLoadedException

Packages that use ClassNotLoadedException
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of ClassNotLoadedException in com.sun.jdi

Methods in com.sun.jdi that throw ClassNotLoadedException
List<Type> | Method.argumentTypes() Returns a list containing the type of each formal parameter of this method.
Type | ArrayType.componentType() Returns the component type of this array, as specified in the array declaration.
void | ThreadReference.forceEarlyReturn(Value value) Force a method to return before it reaches a return statement.
Value | ClassType.invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified static Method in the target VM.
Value | ObjectReference.invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified Method on this object in the target VM.
ObjectReference | ClassType.newInstance(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Constructs a new instance of this type, using the given constructor Method in the target VM.
Type | Method.returnType() Returns the return type, as specified in the declaration of this method.
void | ClassType.setValue(Field field, Value value) Assigns a value to a static field.
void | ObjectReference.setValue(Field field, Value value) Sets the value of a given instance or static field in this object.
void | ArrayReference.setValue(int index, Value value) Replaces an array component with another value.
void | StackFrame.setValue(LocalVariable variable, Value value) Sets the Value of a LocalVariable in this frame.
void | ArrayReference.setValues(int index, List<? extends Value> values, int srcIndex, int length) Replaces a range of array components with other values.
void | ArrayReference.setValues(List<? extends Value> values) Replaces all array components with other values.
Type | LocalVariable.type() Returns the type of this variable.
Type | Field.type() Returns the type of this field.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.ClassNotPreparedException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.ClassNotPreparedException

No usage of com.sun.jdi.ClassNotPreparedException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.IncompatibleThreadStateException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.IncompatibleThreadStateException

Packages that use IncompatibleThreadStateException
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of IncompatibleThreadStateException in com.sun.jdi

Methods in com.sun.jdi that throw IncompatibleThreadStateException
ObjectReference | ThreadReference.currentContendedMonitor() Returns an ObjectReference for the monitor, if any, for which this thread is currently waiting.
int | ObjectReference.entryCount() Returns the number times this object's monitor has been entered by the current owning thread.
void | ThreadReference.forceEarlyReturn(Value value) Force a method to return before it reaches a return statement.
StackFrame | ThreadReference.frame(int index) Returns the StackFrame at the given index in the thread's current call stack.
int | ThreadReference.frameCount() Returns the number of stack frames in the thread's current call stack.
List<StackFrame> | ThreadReference.frames() Returns a List containing each StackFrame in the thread's current call stack.
List<StackFrame> | ThreadReference.frames(int start, int length) Returns a List containing a range of StackFrame mirrors from the thread's current call stack.
Value | ClassType.invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified static Method in the target VM.
Value | ObjectReference.invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified Method on this object in the target VM.
ObjectReference | ClassType.newInstance(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Constructs a new instance of this type, using the given constructor Method in the target VM.
List<ObjectReference> | ThreadReference.ownedMonitors() Returns a List containing an ObjectReference for each monitor owned by the thread.
List<MonitorInfo> | ThreadReference.ownedMonitorsAndFrames() Returns a List containing a MonitorInfo object for each monitor owned by the thread.
ThreadReference | ObjectReference.owningThread() Returns an ThreadReference for the thread, if any, which currently owns this object's monitor.
void | ThreadReference.popFrames(StackFrame frame) Pop stack frames.
List<ThreadReference> | ObjectReference.waitingThreads() Returns a List containing a ThreadReference for each thread currently waiting for this object's monitor.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.InconsistentDebugInfoException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.InconsistentDebugInfoException

No usage of com.sun.jdi.InconsistentDebugInfoException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.InternalException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.InternalException

No usage of com.sun.jdi.InternalException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.InvalidCodeIndexException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.InvalidCodeIndexException

No usage of com.sun.jdi.InvalidCodeIndexException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.InvalidLineNumberException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.InvalidLineNumberException

No usage of com.sun.jdi.InvalidLineNumberException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.InvalidStackFrameException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.InvalidStackFrameException

No usage of com.sun.jdi.InvalidStackFrameException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.InvalidTypeException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.InvalidTypeException

Packages that use InvalidTypeException
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of InvalidTypeException in com.sun.jdi

Methods in com.sun.jdi that throw InvalidTypeException
void | ThreadReference.forceEarlyReturn(Value value) Force a method to return before it reaches a return statement.
Value | ClassType.invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified static Method in the target VM.
Value | ObjectReference.invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified Method on this object in the target VM.
ObjectReference | ClassType.newInstance(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Constructs a new instance of this type, using the given constructor Method in the target VM.
void | ClassType.setValue(Field field, Value value) Assigns a value to a static field.
void | ObjectReference.setValue(Field field, Value value) Sets the value of a given instance or static field in this object.
void | ArrayReference.setValue(int index, Value value) Replaces an array component with another value.
void | StackFrame.setValue(LocalVariable variable, Value value) Sets the Value of a LocalVariable in this frame.
void | ArrayReference.setValues(int index, List<? extends Value> values, int srcIndex, int length) Replaces a range of array components with other values.
void | ArrayReference.setValues(List<? extends Value> values) Replaces all array components with other values.
void | ThreadReference.stop(ObjectReference throwable) Stops this thread with an asynchronous exception.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.InvocationException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.InvocationException

Packages that use InvocationException
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of InvocationException in com.sun.jdi

Methods in com.sun.jdi that throw InvocationException
Value | ClassType.invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified static Method in the target VM.
Value | ObjectReference.invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified Method on this object in the target VM.
ObjectReference | ClassType.newInstance(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Constructs a new instance of this type, using the given constructor Method in the target VM.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.JDIPermission

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.JDIPermission

No usage of com.sun.jdi.JDIPermission

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.NativeMethodException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.NativeMethodException

No usage of com.sun.jdi.NativeMethodException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.ObjectCollectedException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.ObjectCollectedException

No usage of com.sun.jdi.ObjectCollectedException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.VMCannotBeModifiedException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.VMCannotBeModifiedException

No usage of com.sun.jdi.VMCannotBeModifiedException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.VMDisconnectedException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.VMDisconnectedException

No usage of com.sun.jdi.VMDisconnectedException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.VMMismatchException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.VMMismatchException

No usage of com.sun.jdi.VMMismatchException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.VMOutOfMemoryException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.VMOutOfMemoryException

No usage of com.sun.jdi.VMOutOfMemoryException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.Accessible

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.Accessible

Packages that use Accessible
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of Accessible in com.sun.jdi

Subinterfaces of Accessible in com.sun.jdi
interface | ArrayType Provides access to the class of an array and the type of its components in the target VM.
interface | ClassType A mirror of a class in the target VM.
interface | Field A class or instance variable in the target VM.
interface | InterfaceType A mirror of an interface in the target VM.
interface | Method A static or instance method in the target VM.
interface | ReferenceType The type of an object in a target VM.
interface | TypeComponent An entity declared within a user defined type (class or interface).

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.ArrayReference

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.ArrayReference

Packages that use ArrayReference
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of ArrayReference in com.sun.jdi

Methods in com.sun.jdi that return ArrayReference
 ArrayReference ArrayType.newInstance(int length)
Creates a new instance of this array class in the target VM.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.ArrayType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.ArrayType

No usage of com.sun.jdi.ArrayType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.BooleanType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.BooleanType

No usage of com.sun.jdi.BooleanType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.BooleanValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.BooleanValue

Packages that use BooleanValue
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of BooleanValue in com.sun.jdi

Methods in com.sun.jdi that return BooleanValue
 BooleanValue VirtualMachine.mirrorOf(boolean value)
Creates a BooleanValue for the given value.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.ByteType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.ByteType

No usage of com.sun.jdi.ByteType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.ByteValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.ByteValue

Packages that use ByteValue
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of ByteValue in com.sun.jdi

Methods in com.sun.jdi that return ByteValue
 ByteValue VirtualMachine.mirrorOf(byte value)
Creates a ByteValue for the given value.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.CharType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.CharType

No usage of com.sun.jdi.CharType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.CharValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.CharValue

Packages that use CharValue
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of CharValue in com.sun.jdi

Methods in com.sun.jdi that return CharValue
 CharValue VirtualMachine.mirrorOf(char value)
Creates a CharValue for the given value.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.ClassLoaderReference

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.ClassLoaderReference

Packages that use ClassLoaderReference
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of ClassLoaderReference in com.sun.jdi

Methods in com.sun.jdi that return ClassLoaderReference
 ClassLoaderReference ReferenceType.classLoader()
Gets the classloader object which loaded the class corresponding to this type.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.ClassObjectReference

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.ClassObjectReference

Packages that use ClassObjectReference
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of ClassObjectReference in com.sun.jdi

Methods in com.sun.jdi that return ClassObjectReference
 ClassObjectReference ReferenceType.classObject()
Returns the class object that corresponds to this type in the target VM.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.ClassType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.ClassType

Packages that use ClassType
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of ClassType in com.sun.jdi

Methods in com.sun.jdi that return ClassType
 ClassType ClassType.superclass()
Gets the superclass of this class.

Methods in com.sun.jdi that return types with arguments of type ClassType
List<ClassType> | InterfaceType.implementors() Gets the currently prepared classes which directly implement this interface.
List<ClassType> | ClassType.subclasses() Gets the currently loaded, direct subclasses of this class.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.DoubleType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.DoubleType

No usage of com.sun.jdi.DoubleType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.DoubleValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.DoubleValue

Packages that use DoubleValue
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of DoubleValue in com.sun.jdi

Methods in com.sun.jdi that return DoubleValue
 DoubleValue VirtualMachine.mirrorOf(double value)
Creates a DoubleValue for the given value.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.Field

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.Field

Packages that use Field
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.event | This package defines JDI events and event processing.
com.sun.jdi.request | This package is used to request that a JDI event be sent under specified conditions.

Uses of Field in com.sun.jdi

Methods in com.sun.jdi that return Field
 Field ReferenceType.fieldByName(String fieldName)
Finds the visible Field with the given non-ambiguous name.

Methods in com.sun.jdi that return types with arguments of type Field
List<Field> | ReferenceType.allFields() Returns a list containing each Field declared in this type, and its superclasses, implemented interfaces, and/or superinterfaces.
List<Field> | ReferenceType.fields() Returns a list containing each Field declared in this type.
Map<Field,Value> | ReferenceType.getValues(List<? extends Field> fields) Returns a map containing the Value of each static Field in the given list.
Map<Field,Value> | ObjectReference.getValues(List<? extends Field> fields) Gets the value of multiple instance and/or static fields in this object.
List<Field> | ReferenceType.visibleFields() Returns a list containing each unhidden and unambiguous Field in this type.

Methods in com.sun.jdi with parameters of type Field
Value | ReferenceType.getValue(Field field) Gets the Value of a given static Field in this type.
Value | ObjectReference.getValue(Field sig) Gets the value of a given instance or static field in this object.
void | ClassType.setValue(Field field, Value value) Assigns a value to a static field.
void | ObjectReference.setValue(Field field, Value value) Sets the value of a given instance or static field in this object.

Method parameters in com.sun.jdi with type arguments of type Field
Map<Field,Value> | ReferenceType.getValues(List<? extends Field> fields) Returns a map containing the Value of each static Field in the given list.
Map<Field,Value> | ObjectReference.getValues(List<? extends Field> fields) Gets the value of multiple instance and/or static fields in this object.

Uses of Field in com.sun.jdi.event

Methods in com.sun.jdi.event that return Field
 Field WatchpointEvent.field()
Returns the field that is about to be accessed/modified.

Uses of Field in com.sun.jdi.request

Methods in com.sun.jdi.request that return Field
 Field WatchpointRequest.field()
Gets the Field being watched by this WatchpointRequest.

Methods in com.sun.jdi.request with parameters of type Field
AccessWatchpointRequest | EventRequestManager.createAccessWatchpointRequest(Field field) Creates a new disabled watchpoint which watches accesses to the specified field.
ModificationWatchpointRequest | EventRequestManager.createModificationWatchpointRequest(Field field) Creates a new disabled watchpoint which watches accesses to the specified field.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.FloatType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.FloatType

No usage of com.sun.jdi.FloatType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.FloatValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.FloatValue

Packages that use FloatValue
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of FloatValue in com.sun.jdi

Methods in com.sun.jdi that return FloatValue
 FloatValue VirtualMachine.mirrorOf(float value)
Creates a FloatValue for the given value.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.IntegerType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.IntegerType

No usage of com.sun.jdi.IntegerType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.IntegerValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.IntegerValue

Packages that use IntegerValue
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of IntegerValue in com.sun.jdi

Methods in com.sun.jdi that return IntegerValue
 IntegerValue VirtualMachine.mirrorOf(int value)
Creates an IntegerValue for the given value.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.InterfaceType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.InterfaceType

Packages that use InterfaceType
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of InterfaceType in com.sun.jdi

Methods in com.sun.jdi that return types with arguments of type InterfaceType
List<InterfaceType> | ClassType.allInterfaces() Gets the interfaces directly and indirectly implemented by this class.
List<InterfaceType> | ClassType.interfaces() Gets the interfaces directly implemented by this class.
List<InterfaceType> | InterfaceType.subinterfaces() Gets the currently prepared interfaces which directly extend this interface.
List<InterfaceType> | InterfaceType.superinterfaces() Gets the interfaces directly extended by this interface.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.LocalVariable

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.LocalVariable

Packages that use LocalVariable
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of LocalVariable in com.sun.jdi

Methods in com.sun.jdi that return LocalVariable
 LocalVariable StackFrame.visibleVariableByName(String name)
Finds a LocalVariable that matches the given name and is visible at the current frame location.

Methods in com.sun.jdi that return types with arguments of type LocalVariable
List<LocalVariable> | Method.arguments() Returns a list containing each LocalVariable that is declared as an argument of this method.
Map<LocalVariable,Value> | StackFrame.getValues(List<? extends LocalVariable> variables) Returns the values of multiple local variables in this frame.
List<LocalVariable> | Method.variables() Returns a list containing each LocalVariable declared in this method.
List<LocalVariable> | Method.variablesByName(String name) Returns a list containing each LocalVariable of a given name in this method.
List<LocalVariable> | StackFrame.visibleVariables() Returns a list containing each LocalVariable that can be accessed from this frame's location.

Methods in com.sun.jdi with parameters of type LocalVariable
Value | StackFrame.getValue(LocalVariable variable) Gets the Value of a LocalVariable in this frame.
void | StackFrame.setValue(LocalVariable variable, Value value) Sets the Value of a LocalVariable in this frame.

Method parameters in com.sun.jdi with type arguments of type LocalVariable
 Map<LocalVariable,Value> StackFrame.getValues(List<? extends LocalVariable> variables)
Returns the values of multiple local variables in this frame.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.Locatable

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.Locatable

Packages that use Locatable
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.event | This package defines JDI events and event processing.
com.sun.jdi.request | This package is used to request that a JDI event be sent under specified conditions.

Uses of Locatable in com.sun.jdi

Subinterfaces of Locatable in com.sun.jdi
interface | Method A static or instance method in the target VM.
interface | StackFrame The state of one method invocation on a thread's call stack.

Uses of Locatable in com.sun.jdi.event

Subinterfaces of Locatable in com.sun.jdi.event
interface | AccessWatchpointEvent Notification of a field access in the target VM.
interface | BreakpointEvent Notification of a breakpoint in the target VM.
interface | ExceptionEvent Notification of an exception in the target VM.
interface | LocatableEvent Abstract superinterface of events which have both location and thread.
interface | MethodEntryEvent Notification of a method invocation in the target VM.
interface | MethodExitEvent Notification of a method return in the target VM.
interface | ModificationWatchpointEvent Notification of a field modification in the target VM.
interface | MonitorContendedEnteredEvent Notification that a thread in the target VM is entering a monitor after waiting for it to be released by another thread.
interface | MonitorContendedEnterEvent Notification that a thread in the target VM is attempting to enter a monitor that is already acquired by another thread.
interface | MonitorWaitedEvent Notification that a thread in the target VM has finished waiting on an monitor object.
interface | MonitorWaitEvent Notification that a thread in the target VM is about to wait on a monitor object.
interface | StepEvent Notification of step completion in the target VM.
interface | WatchpointEvent Notification of a field triggered event encountered by a thread in the target VM.

Uses of Locatable in com.sun.jdi.request

Subinterfaces of Locatable in com.sun.jdi.request
 interface BreakpointRequest
Identifies a Location in the target VM at which execution should be stopped.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.Location

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.Location

Packages that use Location
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.event | This package defines JDI events and event processing.
com.sun.jdi.request | This package is used to request that a JDI event be sent under specified conditions.

Uses of Location in com.sun.jdi

Methods in com.sun.jdi that return Location
Location | StackFrame.location() Returns the Location of the current instruction in the frame.
Location | Locatable.location() Returns the Location of this mirror, if there is executable code associated with it.
Location | Method.location() Returns the Location of this method, if there is executable code associated with it.
Location | Method.locationOfCodeIndex(long codeIndex) Returns a Location for the given code index.

Methods in com.sun.jdi that return types with arguments of type Location
List<Location> | Method.allLineLocations() Returns a list containing a Location object for each executable source line in this method.
List<Location> | ReferenceType.allLineLocations() Returns a list containing a Location object for each executable source line in this reference type.
List<Location> | Method.allLineLocations(String stratum, String sourceName) Returns a list containing a Location object for each executable source line in this method.
List<Location> | ReferenceType.allLineLocations(String stratum, String sourceName) Returns a list containing a Location object for each executable source line in this reference type.
List<Location> | Method.locationsOfLine(int lineNumber) Returns a List containing all Location objects that map to the given line number.
List<Location> | ReferenceType.locationsOfLine(int lineNumber) Returns a List containing all Location objects that map to the given line number.
List<Location> | Method.locationsOfLine(String stratum, String sourceName, int lineNumber) Returns a List containing all Location objects that map to the given line number and source name.
List<Location> | ReferenceType.locationsOfLine(String stratum, String sourceName, int lineNumber) Returns a List containing all Location objects that map to the given line number.

Uses of Location in com.sun.jdi.event

Methods in com.sun.jdi.event that return Location
 Location ExceptionEvent.catchLocation()
Gets the location where the exception will be caught.

Uses of Location in com.sun.jdi.request

Methods in com.sun.jdi.request that return Location
 Location BreakpointRequest.location()
Returns the location of the requested breakpoint.

Methods in com.sun.jdi.request with parameters of type Location
 BreakpointRequest EventRequestManager.createBreakpointRequest(Location location)
Creates a new disabled BreakpointRequest.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.LongType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.LongType

No usage of com.sun.jdi.LongType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.LongValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.LongValue

Packages that use LongValue
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of LongValue in com.sun.jdi

Methods in com.sun.jdi that return LongValue
 LongValue VirtualMachine.mirrorOf(long value)
Creates a LongValue for the given value.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.Method

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.Method

Packages that use Method
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.event | This package defines JDI events and event processing.

Uses of Method in com.sun.jdi

Methods in com.sun.jdi that return Method
Method | ClassType.concreteMethodByName(String name, String signature) Returns a the single non-abstract Method visible from this class that has the given name and signature.
Method | Location.method() Gets the method containing this Location.

Methods in com.sun.jdi that return types with arguments of type Method
List<Method> | ReferenceType.allMethods() Returns a list containing each Method declared in this type, and its superclasses, implemented interfaces, and/or superinterfaces.
List<Method> | ReferenceType.methods() Returns a list containing each Method declared directly in this type.
List<Method> | ReferenceType.methodsByName(String name) Returns a List containing each visible Method that has the given name.
List<Method> | ReferenceType.methodsByName(String name, String signature) Returns a List containing each visible Method that has the given name and signature.
List<Method> | ReferenceType.visibleMethods() Returns a list containing each Method declared or inherited by this type.

Methods in com.sun.jdi with parameters of type Method
Value | ClassType.invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified static Method in the target VM.
Value | ObjectReference.invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified Method on this object in the target VM.
ObjectReference | ClassType.newInstance(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Constructs a new instance of this type, using the given constructor Method in the target VM.

Uses of Method in com.sun.jdi.event

Methods in com.sun.jdi.event that return Method
Method | MethodExitEvent.method() Returns the method that was exited.
Method | MethodEntryEvent.method() Returns the method that was entered.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.Mirror

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.Mirror

Packages that use Mirror
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.event | This package defines JDI events and event processing.
com.sun.jdi.request | This package is used to request that a JDI event be sent under specified conditions.

Uses of Mirror in com.sun.jdi

Subinterfaces of Mirror in com.sun.jdi
interface | ArrayReference Provides access to an array object and its components in the target VM.
interface | ArrayType Provides access to the class of an array and the type of its components in the target VM.
interface | BooleanType The type of all primitive boolean values accessed in the target VM.
interface | BooleanValue Provides access to a primitive boolean value in the target VM.
interface | ByteType The type of all primitive byte values accessed in the target VM.
interface | ByteValue Provides access to a primitive byte value in the target VM.
interface | CharType The type of all primitive char values accessed in the target VM.
interface | CharValue Provides access to a primitive char value in the target VM.
interface | ClassLoaderReference A class loader object from the target VM.
interface | ClassObjectReference An instance of java.lang.Class from the target VM.
interface | ClassType A mirror of a class in the target VM.
interface | DoubleType The type of all primitive double values accessed in the target VM.
interface | DoubleValue Provides access to a primitive double value in the target VM.
interface | Field A class or instance variable in the target VM.
interface | FloatType The type of all primitive float values accessed in the target VM.
interface | FloatValue Provides access to a primitive float value in the target VM.
interface | IntegerType The type of all primitive int values accessed in the target VM.
interface | IntegerValue Provides access to a primitive int value in the target VM.
interface | InterfaceType A mirror of an interface in the target VM.
interface | LocalVariable A local variable in the target VM.
interface | Location A point within the executing code of the target VM.
interface | LongType The type of all primitive long values accessed in the target VM.
interface | LongValue Provides access to a primitive long value in the target VM.
interface | Method A static or instance method in the target VM.
interface | MonitorInfo Information about a monitor owned by a thread.
interface | ObjectReference An object that currently exists in the target VM.
interface | PathSearchingVirtualMachine A virtual machine which searches for classes through paths
interface | PrimitiveType The type associated with non-object values in a target VM.
interface | PrimitiveValue The value assigned to a field or variable of primitive type in a target VM.
interface | ReferenceType The type of an object in a target VM.
interface | ShortType The type of all primitive short values accessed in the target VM.
interface | ShortValue Provides access to a primitive short value in the target VM.
interface | StackFrame The state of one method invocation on a thread's call stack.
interface | StringReference A string object from the target VM.
interface | ThreadGroupReference A thread group object from the target VM.
interface | ThreadReference A thread object from the target VM.
interface | Type The mirror for a type in the target VM.
interface | TypeComponent An entity declared within a user defined type (class or interface).
interface | Value The mirror for a value in the target VM.
interface | VirtualMachine A virtual machine targeted for debugging.
interface | VoidType The type of all primitive void values accessed in the target VM.
interface | VoidValue Provides access to a primitive void value in the target VM.

Uses of Mirror in com.sun.jdi.event

Subinterfaces of Mirror in com.sun.jdi.event
interface | AccessWatchpointEvent Notification of a field access in the target VM.
interface | BreakpointEvent Notification of a breakpoint in the target VM.
interface | ClassPrepareEvent Notification of a class prepare in the target VM.
interface | ClassUnloadEvent Notification of a class unload in the target VM.
interface | Event An occurrence in a target VM that is of interest to a debugger.
interface | EventQueue Manager of incoming debugger events for a target VM.
interface | EventSet Several Event objects may be created at a given time by the target VirtualMachine.
interface | ExceptionEvent Notification of an exception in the target VM.
interface | LocatableEvent Abstract superinterface of events which have both location and thread.
interface | MethodEntryEvent Notification of a method invocation in the target VM.
interface | MethodExitEvent Notification of a method return in the target VM.
interface | ModificationWatchpointEvent Notification of a field modification in the target VM.
interface | MonitorContendedEnteredEvent Notification that a thread in the target VM is entering a monitor after waiting for it to be released by another thread.
interface | MonitorContendedEnterEvent Notification that a thread in the target VM is attempting to enter a monitor that is already acquired by another thread.
interface | MonitorWaitedEvent Notification that a thread in the target VM has finished waiting on an monitor object.
interface | MonitorWaitEvent Notification that a thread in the target VM is about to wait on a monitor object.
interface | StepEvent Notification of step completion in the target VM.
interface | ThreadDeathEvent Notification of a completed thread in the target VM.
interface | ThreadStartEvent Notification of a new running thread in the target VM.
interface | VMDeathEvent Notification of target VM termination.
interface | VMDisconnectEvent Notification of disconnection from target VM.
interface | VMStartEvent Notification of initialization of a target VM.
interface | WatchpointEvent Notification of a field triggered event encountered by a thread in the target VM.

Uses of Mirror in com.sun.jdi.request

Subinterfaces of Mirror in com.sun.jdi.request
interface | AccessWatchpointRequest Request for notification when the contents of a field are accessed in the target VM.
interface | BreakpointRequest Identifies a Location in the target VM at which execution should be stopped.
interface | ClassPrepareRequest Request for notification when a class is prepared in the target VM.
interface | ClassUnloadRequest Request for notification when a class is unloaded in the target VM.
interface | EventRequest Represents a request for notification of an event.
interface | EventRequestManager Manages the creation and deletion of EventRequests.
interface | ExceptionRequest Request for notification when an exception occurs in the target VM.
interface | MethodEntryRequest Request for notification when a method is invoked in the target VM.
interface | MethodExitRequest Request for notification when a method returns in the target VM.
interface | ModificationWatchpointRequest Request for notification when a field is set.
interface | MonitorContendedEnteredRequest Request for notification of a thread in the target VM entering a monitor after waiting for it to be released by another thread.
interface | MonitorContendedEnterRequest Request for notification of a thread in the target VM attempting to enter a monitor already acquired by another thread.
interface | MonitorWaitedRequest Request for notification when a thread in the target VM has finished waiting on a monitor object.
interface | MonitorWaitRequest Request for notification when a thread in the target VM is about to wait on a monitor object.
interface | StepRequest Request for notification when a step occurs in the target VM.
interface | ThreadDeathRequest Request for notification when a thread terminates in the target VM.
interface | ThreadStartRequest Request for notification when a thread starts execution in the target VM.
interface | VMDeathRequest Request for notification when the target VM terminates.
interface | WatchpointRequest Identifies a Field in the target VM being watched.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.MonitorInfo

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.MonitorInfo

Packages that use MonitorInfo
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of MonitorInfo in com.sun.jdi

Methods in com.sun.jdi that return types with arguments of type MonitorInfo
 List<MonitorInfo> ThreadReference.ownedMonitorsAndFrames()
Returns a List containing a MonitorInfo object for each monitor owned by the thread.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.ObjectReference

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.ObjectReference

Packages that use ObjectReference
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.event | This package defines JDI events and event processing.
com.sun.jdi.request | This package is used to request that a JDI event be sent under specified conditions.

Uses of ObjectReference in com.sun.jdi

Subinterfaces of ObjectReference in com.sun.jdi
interface | ArrayReference Provides access to an array object and its components in the target VM.
interface | ClassLoaderReference A class loader object from the target VM.
interface | ClassObjectReference An instance of java.lang.Class from the target VM.
interface | StringReference A string object from the target VM.
interface | ThreadGroupReference A thread group object from the target VM.
interface | ThreadReference A thread object from the target VM.

Methods in com.sun.jdi that return ObjectReference
ObjectReference | ThreadReference.currentContendedMonitor() Returns an ObjectReference for the monitor, if any, for which this thread is currently waiting.
ObjectReference | InvocationException.exception()
ObjectReference | MonitorInfo.monitor() Returns the ObjectReference object for the monitor.
ObjectReference | ClassType.newInstance(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Constructs a new instance of this type, using the given constructor Method in the target VM.
ObjectReference | StackFrame.thisObject() Returns the value of 'this' for the current frame.

Methods in com.sun.jdi that return types with arguments of type ObjectReference
List<ObjectReference> | ReferenceType.instances(long maxInstances) Returns instances of this ReferenceType.
List<ObjectReference> | ThreadReference.ownedMonitors() Returns a List containing an ObjectReference for each monitor owned by the thread.
List<ObjectReference> | ObjectReference.referringObjects(long maxReferrers) Returns objects that directly reference this object.

Methods in com.sun.jdi with parameters of type ObjectReference
 void ThreadReference.stop(ObjectReference throwable)
Stops this thread with an asynchronous exception.

Constructors in com.sun.jdi with parameters of type ObjectReference
InvocationException(ObjectReference exception)

Uses of ObjectReference in com.sun.jdi.event

Methods in com.sun.jdi.event that return ObjectReference
ObjectReference | ExceptionEvent.exception() Gets the thrown exception object.
ObjectReference | MonitorWaitedEvent.monitor() Returns the monitor object this thread waited on.
ObjectReference | MonitorWaitEvent.monitor() Returns the monitor object that the thread about to wait.
ObjectReference | MonitorContendedEnteredEvent.monitor() Returns the monitor that was entered.
ObjectReference | MonitorContendedEnterEvent.monitor() Returns the method that was entered.
ObjectReference | WatchpointEvent.object() Returns the object whose field is about to be accessed/modified.

Uses of ObjectReference in com.sun.jdi.request

Methods in com.sun.jdi.request with parameters of type ObjectReference
void | WatchpointRequest.addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
void | BreakpointRequest.addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance is the object specified.
void | StepRequest.addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
void | MonitorWaitedRequest.addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
void | MonitorWaitRequest.addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
void | MonitorContendedEnteredRequest.addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
void | MonitorContendedEnterRequest.addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
void | MethodExitRequest.addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
void | MethodEntryRequest.addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
void | ExceptionRequest.addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.PathSearchingVirtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.PathSearchingVirtualMachine

No usage of com.sun.jdi.PathSearchingVirtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.PrimitiveType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.PrimitiveType

Packages that use PrimitiveType
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of PrimitiveType in com.sun.jdi

Subinterfaces of PrimitiveType in com.sun.jdi
interface | BooleanType The type of all primitive boolean values accessed in the target VM.
interface | ByteType The type of all primitive byte values accessed in the target VM.
interface | CharType The type of all primitive char values accessed in the target VM.
interface | DoubleType The type of all primitive double values accessed in the target VM.
interface | FloatType The type of all primitive float values accessed in the target VM.
interface | IntegerType The type of all primitive int values accessed in the target VM.
interface | LongType The type of all primitive long values accessed in the target VM.
interface | ShortType The type of all primitive short values accessed in the target VM.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.PrimitiveValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.PrimitiveValue

Packages that use PrimitiveValue
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of PrimitiveValue in com.sun.jdi

Subinterfaces of PrimitiveValue in com.sun.jdi
interface | BooleanValue Provides access to a primitive boolean value in the target VM.
interface | ByteValue Provides access to a primitive byte value in the target VM.
interface | CharValue Provides access to a primitive char value in the target VM.
interface | DoubleValue Provides access to a primitive double value in the target VM.
interface | FloatValue Provides access to a primitive float value in the target VM.
interface | IntegerValue Provides access to a primitive int value in the target VM.
interface | LongValue Provides access to a primitive long value in the target VM.
interface | ShortValue Provides access to a primitive short value in the target VM.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.ReferenceType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.ReferenceType

Packages that use ReferenceType
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.event | This package defines JDI events and event processing.
com.sun.jdi.request | This package is used to request that a JDI event be sent under specified conditions.

Uses of ReferenceType in com.sun.jdi

Subinterfaces of ReferenceType in com.sun.jdi
interface | ArrayType Provides access to the class of an array and the type of its components in the target VM.
interface | ClassType A mirror of a class in the target VM.
interface | InterfaceType A mirror of an interface in the target VM.

Methods in com.sun.jdi that return ReferenceType
ReferenceType | Location.declaringType() Gets the type to which this Location belongs.
ReferenceType | TypeComponent.declaringType() Returns the type in which this component was declared.
ReferenceType | ObjectReference.referenceType() Gets the ReferenceType that mirrors the type of this object.
ReferenceType | ClassObjectReference.reflectedType() Returns the ReferenceType corresponding to this class object.

Methods in com.sun.jdi that return types with arguments of type ReferenceType
List<ReferenceType> | VirtualMachine.allClasses() Returns all loaded types.
List<ReferenceType> | VirtualMachine.classesByName(String className) Returns the loaded reference types that match a given name.
List<ReferenceType> | ClassLoaderReference.definedClasses() Returns a list of all loaded classes that were defined by this class loader.
List<ReferenceType> | ReferenceType.nestedTypes() Returns a List containing ReferenceType objects that are declared within this type and are currently loaded into the Virtual Machine.
List<ReferenceType> | ClassLoaderReference.visibleClasses() Returns a list of all classes for which this class loader has been recorded as the initiating loader in the target VM.

Method parameters in com.sun.jdi with type arguments of type ReferenceType
long[] | VirtualMachine.instanceCounts(List<? extends ReferenceType> refTypes) Returns the number of instances of each ReferenceType in the 'refTypes' list.
void | VirtualMachine.redefineClasses(Map<? extends ReferenceType,byte[]> classToBytes) All classes given are redefined according to the definitions supplied.

Uses of ReferenceType in com.sun.jdi.event

Methods in com.sun.jdi.event that return ReferenceType
 ReferenceType ClassPrepareEvent.referenceType()
Returns the reference type for which this event was generated.

Uses of ReferenceType in com.sun.jdi.request

Methods in com.sun.jdi.request that return ReferenceType
 ReferenceType ExceptionRequest.exception()
Returns exception type for which exception events are requested.

Methods in com.sun.jdi.request with parameters of type ReferenceType
void | WatchpointRequest.addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose location is in the given reference type or any of its subtypes.
void | StepRequest.addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose location is in the given reference type or any of its subtypes.
void | MonitorWaitedRequest.addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose monitor object is of the given reference type or any of its subtypes.
void | MonitorWaitRequest.addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose monitor object is of the given reference type or any of its subtypes.
void | MonitorContendedEnteredRequest.addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose method is in the given reference type or any of its subtypes.
void | MonitorContendedEnterRequest.addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose method is in the given reference type or any of its subtypes.
void | MethodExitRequest.addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose method is in the given reference type or any of its subtypes.
void | MethodEntryRequest.addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose method is in the given reference type or any of its subtypes.
void | ExceptionRequest.addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose location is in the given reference type or any of its subtypes.
void | ClassPrepareRequest.addClassFilter(ReferenceType refType) Restricts the events generated by this request to be the preparation of the given reference type and any subtypes.
ExceptionRequest | EventRequestManager.createExceptionRequest(ReferenceType refType, boolean notifyCaught, boolean notifyUncaught) Creates a new disabled ExceptionRequest.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.ShortType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.ShortType

No usage of com.sun.jdi.ShortType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.ShortValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.ShortValue

Packages that use ShortValue
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of ShortValue in com.sun.jdi

Methods in com.sun.jdi that return ShortValue
 ShortValue VirtualMachine.mirrorOf(short value)
Creates a ShortValue for the given value.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.StackFrame

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.StackFrame

Packages that use StackFrame
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of StackFrame in com.sun.jdi

Methods in com.sun.jdi that return StackFrame
 StackFrame ThreadReference.frame(int index)
Returns the StackFrame at the given index in the thread's current call stack.

Methods in com.sun.jdi that return types with arguments of type StackFrame
List<StackFrame> | ThreadReference.frames() Returns a List containing each StackFrame in the thread's current call stack.
List<StackFrame> | ThreadReference.frames(int start, int length) Returns a List containing a range of StackFrame mirrors from the thread's current call stack.

Methods in com.sun.jdi with parameters of type StackFrame
boolean | LocalVariable.isVisible(StackFrame frame) Determines whether this variable can be accessed from the given StackFrame.
void | ThreadReference.popFrames(StackFrame frame) Pop stack frames.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.StringReference

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.StringReference

Packages that use StringReference
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of StringReference in com.sun.jdi

Methods in com.sun.jdi that return StringReference
 StringReference VirtualMachine.mirrorOf(String value)
Creates a string in this virtual machine.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.ThreadGroupReference

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.ThreadGroupReference

Packages that use ThreadGroupReference
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of ThreadGroupReference in com.sun.jdi

Methods in com.sun.jdi that return ThreadGroupReference
ThreadGroupReference | ThreadGroupReference.parent() Returns the parent of this thread group.
ThreadGroupReference | ThreadReference.threadGroup() Returns this thread's thread group.

Methods in com.sun.jdi that return types with arguments of type ThreadGroupReference
List<ThreadGroupReference> | ThreadGroupReference.threadGroups() Returns a List containing each active ThreadGroupReference in this thread group.
List<ThreadGroupReference> | VirtualMachine.topLevelThreadGroups() Returns each thread group which does not have a parent.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.ThreadReference

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.ThreadReference

Packages that use ThreadReference
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.event | This package defines JDI events and event processing.
com.sun.jdi.request | This package is used to request that a JDI event be sent under specified conditions.

Uses of ThreadReference in com.sun.jdi

Methods in com.sun.jdi that return ThreadReference
ThreadReference | ObjectReference.owningThread() Returns an ThreadReference for the thread, if any, which currently owns this object's monitor.
ThreadReference | MonitorInfo.thread() Returns a ThreadReference object for the thread that owns the monitor.
ThreadReference | StackFrame.thread() Returns the thread under which this frame's method is running.

Methods in com.sun.jdi that return types with arguments of type ThreadReference
List<ThreadReference> | VirtualMachine.allThreads() Returns a list of the currently running threads.
List<ThreadReference> | ThreadGroupReference.threads() Returns a List containing a ThreadReference for each live thread in this thread group.
List<ThreadReference> | ObjectReference.waitingThreads() Returns a List containing a ThreadReference for each thread currently waiting for this object's monitor.

Methods in com.sun.jdi with parameters of type ThreadReference
Value | ClassType.invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified static Method in the target VM.
Value | ObjectReference.invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified Method on this object in the target VM.
ObjectReference | ClassType.newInstance(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Constructs a new instance of this type, using the given constructor Method in the target VM.

Uses of ThreadReference in com.sun.jdi.event

Methods in com.sun.jdi.event that return ThreadReference
ThreadReference | VMStartEvent.thread() Returns the initial thread of the VM which has started.
ThreadReference | ThreadStartEvent.thread() Returns the thread which has started.
ThreadReference | ThreadDeathEvent.thread() Returns the thread which is terminating.
ThreadReference | MonitorWaitedEvent.thread() Returns the thread in which this event has occurred.
ThreadReference | MonitorWaitEvent.thread() Returns the thread in which monitor wait event has occurred.
ThreadReference | MonitorContendedEnteredEvent.thread() Returns the thread in which this event has occurred.
ThreadReference | MonitorContendedEnterEvent.thread() Returns the thread in which this event has occurred.
ThreadReference | ClassPrepareEvent.thread() Returns the thread in which this event has occurred.
ThreadReference | LocatableEvent.thread() Returns the thread in which this event has occurred.

Uses of ThreadReference in com.sun.jdi.request

Methods in com.sun.jdi.request that return ThreadReference
 ThreadReference StepRequest.thread()

Methods in com.sun.jdi.request with parameters of type ThreadReference
void | WatchpointRequest.addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
void | BreakpointRequest.addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
void | MonitorWaitedRequest.addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
void | MonitorWaitRequest.addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
void | MonitorContendedEnteredRequest.addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
void | MonitorContendedEnterRequest.addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
void | MethodExitRequest.addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
void | MethodEntryRequest.addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
void | ExceptionRequest.addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
void | ThreadDeathRequest.addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
void | ThreadStartRequest.addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
StepRequest | EventRequestManager.createStepRequest(ThreadReference thread, int size, int depth) Creates a new disabled StepRequest.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.Type

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.Type

Packages that use Type
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of Type in com.sun.jdi

Subinterfaces of Type in com.sun.jdi
interface | ArrayType Provides access to the class of an array and the type of its components in the target VM.
interface | BooleanType The type of all primitive boolean values accessed in the target VM.
interface | ByteType The type of all primitive byte values accessed in the target VM.
interface | CharType The type of all primitive char values accessed in the target VM.
interface | ClassType A mirror of a class in the target VM.
interface | DoubleType The type of all primitive double values accessed in the target VM.
interface | FloatType The type of all primitive float values accessed in the target VM.
interface | IntegerType The type of all primitive int values accessed in the target VM.
interface | InterfaceType A mirror of an interface in the target VM.
interface | LongType The type of all primitive long values accessed in the target VM.
interface | PrimitiveType The type associated with non-object values in a target VM.
interface | ReferenceType The type of an object in a target VM.
interface | ShortType The type of all primitive short values accessed in the target VM.
interface | VoidType The type of all primitive void values accessed in the target VM.

Methods in com.sun.jdi that return Type
Type | ArrayType.componentType() Returns the component type of this array, as specified in the array declaration.
Type | Method.returnType() Returns the return type, as specified in the declaration of this method.
Type | LocalVariable.type() Returns the type of this variable.
Type | Field.type() Returns the type of this field.
Type | Value.type() Returns the run-time type of this value.

Methods in com.sun.jdi that return types with arguments of type Type
 List<Type> Method.argumentTypes()
Returns a list containing the type of each formal parameter of this method.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.TypeComponent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.TypeComponent

Packages that use TypeComponent
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of TypeComponent in com.sun.jdi

Subinterfaces of TypeComponent in com.sun.jdi
interface | Field A class or instance variable in the target VM.
interface | Method A static or instance method in the target VM.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.Value

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.Value

Packages that use Value
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.event | This package defines JDI events and event processing.

Uses of Value in com.sun.jdi

Subinterfaces of Value in com.sun.jdi
interface | ArrayReference Provides access to an array object and its components in the target VM.
interface | BooleanValue Provides access to a primitive boolean value in the target VM.
interface | ByteValue Provides access to a primitive byte value in the target VM.
interface | CharValue Provides access to a primitive char value in the target VM.
interface | ClassLoaderReference A class loader object from the target VM.
interface | ClassObjectReference An instance of java.lang.Class from the target VM.
interface | DoubleValue Provides access to a primitive double value in the target VM.
interface | FloatValue Provides access to a primitive float value in the target VM.
interface | IntegerValue Provides access to a primitive int value in the target VM.
interface | LongValue Provides access to a primitive long value in the target VM.
interface | ObjectReference An object that currently exists in the target VM.
interface | PrimitiveValue The value assigned to a field or variable of primitive type in a target VM.
interface | ShortValue Provides access to a primitive short value in the target VM.
interface | StringReference A string object from the target VM.
interface | ThreadGroupReference A thread group object from the target VM.
interface | ThreadReference A thread object from the target VM.
interface | VoidValue Provides access to a primitive void value in the target VM.

Methods in com.sun.jdi that return Value
Value | ReferenceType.getValue(Field field) Gets the Value of a given static Field in this type.
Value | ObjectReference.getValue(Field sig) Gets the value of a given instance or static field in this object.
Value | ArrayReference.getValue(int index) Returns an array component value.
Value | StackFrame.getValue(LocalVariable variable) Gets the Value of a LocalVariable in this frame.
Value | ClassType.invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified static Method in the target VM.
Value | ObjectReference.invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified Method on this object in the target VM.

Methods in com.sun.jdi that return types with arguments of type Value
List<Value> | StackFrame.getArgumentValues() Returns the values of all arguments in this frame.
List<Value> | ArrayReference.getValues() Returns all of the components in this array.
List<Value> | ArrayReference.getValues(int index, int length) Returns a range of array components.
Map<Field,Value> | ReferenceType.getValues(List<? extends Field> fields) Returns a map containing the Value of each static Field in the given list.
Map<Field,Value> | ObjectReference.getValues(List<? extends Field> fields) Gets the value of multiple instance and/or static fields in this object.
Map<LocalVariable,Value> | StackFrame.getValues(List<? extends LocalVariable> variables) Returns the values of multiple local variables in this frame.

Methods in com.sun.jdi with parameters of type Value
void | ThreadReference.forceEarlyReturn(Value value) Force a method to return before it reaches a return statement.
void | ClassType.setValue(Field field, Value value) Assigns a value to a static field.
void | ObjectReference.setValue(Field field, Value value) Sets the value of a given instance or static field in this object.
void | ArrayReference.setValue(int index, Value value) Replaces an array component with another value.
void | StackFrame.setValue(LocalVariable variable, Value value) Sets the Value of a LocalVariable in this frame.

Method parameters in com.sun.jdi with type arguments of type Value
Value | ClassType.invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified static Method in the target VM.
Value | ObjectReference.invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified Method on this object in the target VM.
ObjectReference | ClassType.newInstance(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Constructs a new instance of this type, using the given constructor Method in the target VM.
void | ArrayReference.setValues(int index, List<? extends Value> values, int srcIndex, int length) Replaces a range of array components with other values.
void | ArrayReference.setValues(List<? extends Value> values) Replaces all array components with other values.

Uses of Value in com.sun.jdi.event

Methods in com.sun.jdi.event that return Value
Value | MethodExitEvent.returnValue() Returns the value that the method will return.
Value | WatchpointEvent.valueCurrent() Current value of the field.
Value | ModificationWatchpointEvent.valueToBe() Value that will be assigned to the field when the instruction completes.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.VirtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.VirtualMachine

Packages that use VirtualMachine
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.connect | This package defines connections between the virtual machine using the JDI and the target virtual machine.

Uses of VirtualMachine in com.sun.jdi

Subinterfaces of VirtualMachine in com.sun.jdi
 interface PathSearchingVirtualMachine
A virtual machine which searches for classes through paths

Methods in com.sun.jdi that return VirtualMachine
VirtualMachine | VirtualMachineManager.createVirtualMachine(Connection connection) Creates a new virtual machine.
VirtualMachine | VirtualMachineManager.createVirtualMachine(Connection connection, Process process) Create a virtual machine mirror for a target VM.
VirtualMachine | Mirror.virtualMachine() Gets the VirtualMachine to which this Mirror belongs.

Methods in com.sun.jdi that return types with arguments of type VirtualMachine
 List<VirtualMachine> VirtualMachineManager.connectedVirtualMachines()
Lists all target VMs which are connected to the debugger.

Uses of VirtualMachine in com.sun.jdi.connect

Methods in com.sun.jdi.connect that return VirtualMachine
VirtualMachine | ListeningConnector.accept(Map<String,? extends Connector.Argument> arguments) Waits for a target VM to attach to this connector.
VirtualMachine | AttachingConnector.attach(Map<String,? extends Connector.Argument> arguments) Attaches to a running application and and returns a mirror of its VM.
VirtualMachine | LaunchingConnector.launch(Map<String,? extends Connector.Argument> arguments) Launches an application and connects to its VM.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.VirtualMachineManager

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.VirtualMachineManager

Packages that use VirtualMachineManager
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of VirtualMachineManager in com.sun.jdi

Methods in com.sun.jdi that return VirtualMachineManager
static VirtualMachineManager Bootstrap.virtualMachineManager()
Returns the virtual machine manager.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.VoidType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.VoidType

No usage of com.sun.jdi.VoidType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.VoidValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.VoidValue

Packages that use VoidValue
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of VoidValue in com.sun.jdi

Methods in com.sun.jdi that return VoidValue
 VoidValue VirtualMachine.mirrorOfVoid()
Creates a VoidValue.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


ClassLoaderReference

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface ClassLoaderReference

All Superinterfaces:
Mirror, ObjectReference, Value
public interface ClassLoaderReference
extends ObjectReference

A class loader object from the target VM. A ClassLoaderReference is an ObjectReference with additional access to classloader-specific information from the target VM. Instances ClassLoaderReference are obtained through calls to ReferenceType.classLoader()

Since:
1.3
See Also:
ObjectReference

Field Summary
Fields inherited from interface com.sun.jdi.ObjectReference
INVOKE_NONVIRTUAL, INVOKE_SINGLE_THREADED
Method Summary
List<ReferenceType> | definedClasses() Returns a list of all loaded classes that were defined by this class loader.
List<ReferenceType> | visibleClasses() Returns a list of all classes for which this class loader has been recorded as the initiating loader in the target VM.
Methods inherited from interface com.sun.jdi.ObjectReference
disableCollection, enableCollection, entryCount, equals, getValue, getValues, hashCode, invokeMethod, isCollected, owningThread, referenceType, referringObjects, setValue, uniqueID, waitingThreads
Methods inherited from interface com.sun.jdi.Value
type
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

definedClasses

List<ReferenceType> definedClasses()
Returns a list of all loaded classes that were defined by this class loader. No ordering of this list guaranteed.

The returned list will include reference types loaded at least to the point of preparation and types (like array) for which preparation is not defined.

Returns:
a List of ReferenceType objects mirroring types loaded by this class loader. The list has length 0 if no types have been defined by this classloader.

visibleClasses

List<ReferenceType> visibleClasses()
Returns a list of all classes for which this class loader has been recorded as the initiating loader in the target VM. The list contains ReferenceTypes defined directly by this loader (as returned by definedClasses()) and any types for which loading was delegated by this class loader to another class loader.

The visible class list has useful properties with respect to the type namespace. A particular type name will occur at most once in the list. Each field or variable declared with that type name in a class defined by this class loader must be resolved to that single type.

No ordering of the returned list is guaranteed.

See the revised Java Virtual Machine Specification section 5.3 Creation and Loading for more information on the initiating classloader.

Note that unlike definedClasses() and VirtualMachine.allClasses(), some of the returned reference types may not be prepared. Attempts to perform some operations on unprepared reference types (e.g. fields()) will throw a ClassNotPreparedException. Use ReferenceType.isPrepared() to determine if a reference type is prepared.

Returns:
a List of ReferenceType objects mirroring classes initiated by this class loader. The list has length 0 if no classes are visible to this classloader.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ClassNotLoadedException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class ClassNotLoadedException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  com.sun.jdi.ClassNotLoadedException
All Implemented Interfaces:
Serializable
public class ClassNotLoadedException
extends Exception

Thrown to indicate that the requested class has not yet been loaded through the appropriate class loader.

Due to the lazy class linking performed by many VMs, it is possible for a field or variable to be visible in a program before the associated class is loaded. Until the class is loaded all that is available is a signature string. If an attempt is made to set the value of such a field or variable from JDI, the appropriate type checking cannot be done because the destination class has not been loaded. The same is true for the element class of array elements.

It is not advisable to solve this problem by attempting a class load on the fly in this case. There are two problems in having the debugger load a class instead of waiting for it to load over the normal course of events.

  • There can be no guarantee that running the appropriate class loader won't cause a deadlock in loading the class. Class loaders can consist of arbitrary JavaTM programming language code and the class loading methods are usually synchronized. Most of the work done by a debugger happens when threads are suspended. If another application thread is suspended within the same class loader, a deadlock is very possible.
  • Changing the order in which classes are normally loaded may either mask or reveal bugs in the application. An unintrusive debugger should strive to leave unchanged the behavior of the application being debugged.
To avoid these potential problems, this exception is thrown.

Note that this exception will be thrown until the class in question is visible to the class loader of enclosing class. (That is, the class loader of the enclosing class must be an initiating class loader for the class in question.) See the Java Virtual Machine Specification for more details.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
ClassNotLoadedException(String className)
ClassNotLoadedException(String className, String message)
Method Summary
 String className()
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ClassNotLoadedException

public ClassNotLoadedException(String className)

ClassNotLoadedException

public ClassNotLoadedException(String className,
                               String message)
Method Detail

className

public String className()
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ClassNotPreparedException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class ClassNotPreparedException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  com.sun.jdi.ClassNotPreparedException
All Implemented Interfaces:
Serializable
public class ClassNotPreparedException
extends RuntimeException

Thrown to indicate that the requested operation cannot be completed because the specified class has not yet been prepared.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
ClassNotPreparedException()
ClassNotPreparedException(String s)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ClassNotPreparedException

public ClassNotPreparedException()

ClassNotPreparedException

public ClassNotPreparedException(String s)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ClassObjectReference

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface ClassObjectReference

All Superinterfaces:
Mirror, ObjectReference, Value
public interface ClassObjectReference
extends ObjectReference

An instance of java.lang.Class from the target VM. Use this interface to access type information for the class, array, or interface that this object reflects.

Since:
1.3
See Also:
ReferenceType

Field Summary
Fields inherited from interface com.sun.jdi.ObjectReference
INVOKE_NONVIRTUAL, INVOKE_SINGLE_THREADED
Method Summary
 ReferenceType reflectedType()
Returns the ReferenceType corresponding to this class object.
Methods inherited from interface com.sun.jdi.ObjectReference
disableCollection, enableCollection, entryCount, equals, getValue, getValues, hashCode, invokeMethod, isCollected, owningThread, referenceType, referringObjects, setValue, uniqueID, waitingThreads
Methods inherited from interface com.sun.jdi.Value
type
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

reflectedType

ReferenceType reflectedType()
Returns the ReferenceType corresponding to this class object. The returned type can be used to obtain detailed information about the class.

Returns:
the ReferenceType reflected by this class object.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ClassType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface ClassType

All Superinterfaces:
Accessible, Comparable<ReferenceType>, Mirror, ReferenceType, Type
public interface ClassType
extends ReferenceType

A mirror of a class in the target VM. A ClassType is a refinement of ReferenceType that applies to true classes in the JLS sense of the definition (not an interface, not an array type). Any ObjectReference that mirrors an instance of such a class will have a ClassType as its type.

Since:
1.3
See Also:
ObjectReference

Field Summary
static int INVOKE_SINGLE_THREADED
Perform method invocation with only the invoking thread resumed
Method Summary
List<InterfaceType> | allInterfaces() Gets the interfaces directly and indirectly implemented by this class.
Method | concreteMethodByName(String name, String signature) Returns a the single non-abstract Method visible from this class that has the given name and signature.
List<InterfaceType> | interfaces() Gets the interfaces directly implemented by this class.
Value | invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified static Method in the target VM.
boolean | isEnum() Determine if this class was declared as an enum.
ObjectReference | newInstance(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Constructs a new instance of this type, using the given constructor Method in the target VM.
void | setValue(Field field, Value value) Assigns a value to a static field.
List<ClassType> | subclasses() Gets the currently loaded, direct subclasses of this class.
ClassType | superclass() Gets the superclass of this class.
Methods inherited from interface com.sun.jdi.ReferenceType
allFields, allLineLocations, allLineLocations, allMethods, availableStrata, classLoader, classObject, constantPool, constantPoolCount, defaultStratum, equals, failedToInitialize, fieldByName, fields, genericSignature, getValue, getValues, hashCode, instances, isAbstract, isFinal, isInitialized, isPrepared, isStatic, isVerified, locationsOfLine, locationsOfLine, majorVersion, methods, methodsByName, methodsByName, minorVersion, name, nestedTypes, sourceDebugExtension, sourceName, sourceNames, sourcePaths, visibleFields, visibleMethods
Methods inherited from interface com.sun.jdi.Type
signature
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface java.lang.Comparable
compareTo
Methods inherited from interface com.sun.jdi.Accessible
isPackagePrivate, isPrivate, isProtected, isPublic, modifiers

Field Detail

INVOKE_SINGLE_THREADED

static final int INVOKE_SINGLE_THREADED
Perform method invocation with only the invoking thread resumed

See Also:
Constant Field Values
Method Detail

superclass

ClassType superclass()
Gets the superclass of this class.

Returns:
a ClassType that mirrors the superclass of this class in the target VM. If no such class exists, returns null

interfaces

List<InterfaceType> interfaces()
Gets the interfaces directly implemented by this class. Only the interfaces that are declared with the "implements" keyword in this class are included.

Returns:
a List of InterfaceType objects each mirroring a direct interface this ClassType in the target VM. If none exist, returns a zero length List.
Throws:
ClassNotPreparedException - if this class not yet been prepared.

allInterfaces

List<InterfaceType> allInterfaces()
Gets the interfaces directly and indirectly implemented by this class. Interfaces returned by interfaces() are returned as well all superinterfaces.

Returns:
a List of InterfaceType objects each mirroring an interface of this ClassType in the target VM. If none exist, returns a zero length List.
Throws:
ClassNotPreparedException - if this class not yet been prepared.

subclasses

List<ClassType> subclasses()
Gets the currently loaded, direct subclasses of this class. No ordering of this list is guaranteed.

Returns:
a List of ClassType objects each mirroring a loaded subclass of this class in the target VM. If no such classes exist, this method returns a zero-length list.

isEnum

boolean isEnum()
Determine if this class was declared as an enum.

Returns:
true if this class was declared as an enum; false otherwise.

setValue

void setValue(Field field,
              Value value)
              throws InvalidTypeException,
                     ClassNotLoadedException
Assigns a value to a static field. The Field must be valid for this ClassType; that is, it must be from the mirrored object's class or a superclass of that class. The field must not be final.

Object values must be assignment compatible with the field type (This implies that the field type must be loaded through the enclosing class's class loader). Primitive values must be either assignment compatible with the field type or must be convertible to the field type without loss of information. See JLS section 5.2 for more information on assignment compatibility.

Parameters:
field - the field to set.
value - the value to be assigned.
Throws:
IllegalArgumentException - if the field is not static, the field is final, or the field does not exist in this class.
ClassNotLoadedException - if the field type has not yet been loaded through the appropriate class loader.
InvalidTypeException - if the value's type does not match the field's declared type.
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().

invokeMethod

Value invokeMethod(ThreadReference thread,
                   Method method,
                   List<? extends Value> arguments,
                   int options)
                   throws InvalidTypeException,
                          ClassNotLoadedException,
                          IncompatibleThreadStateException,
                          InvocationException
Invokes the specified static Method in the target VM. The specified method can be defined in this class, or in a superclass. The method must be a static method but not a static initializer. Use newInstance(com.sun.jdi.ThreadReference, com.sun.jdi.Method, java.util.List, int) to create a new object and run its constructor.

The method invocation will occur in the specified thread. Method invocation can occur only if the specified thread has been suspended by an event which occurred in that thread. Method invocation is not supported when the target VM has been suspended through VirtualMachine.suspend() or when the specified thread is suspended through ThreadReference.suspend().

The specified method is invoked with the arguments in the specified argument list. The method invocation is synchronous; this method does not return until the invoked method returns in the target VM. If the invoked method throws an exception, this method will throw an InvocationException which contains a mirror to the exception object thrown.

Object arguments must be assignment compatible with the argument type (This implies that the argument type must be loaded through the enclosing class's class loader). Primitive arguments must be either assignment compatible with the argument type or must be convertible to the argument type without loss of information. If the method being called accepts a variable number of arguments, then the last argument type is an array of some component type. The argument in the matching position can be omitted, or can be null, an array of the same component type, or an argument of the component type followed by any number of other arguments of the same type. If the argument is omitted, then a 0 length array of the component type is passed. The component type can be a primitive type. Autoboxing is not supported. See the Java Language Specification. section 5.2 for more information on assignment compatibility.

By default, all threads in the target VM are resumed while the method is being invoked if they were previously suspended by an event or by VirtualMachine.suspend() or ThreadReference.suspend(). This is done to prevent the deadlocks that will occur if any of the threads own monitors that will be needed by the invoked method. Note, however, that this implicit resume acts exactly like ThreadReference.resume(), so if the thread's suspend count is greater than 1, it will remain in a suspended state during the invocation and thus a deadlock could still occur. By default, when the invocation completes, all threads in the target VM are suspended, regardless their state before the invocation. It is possible that breakpoints or other events might occur during the invocation. This can cause deadlocks as described above. It can also cause a deadlock if invokeMethod is called from the client's event handler thread. In this case, this thread will be waiting for the invokeMethod to complete and won't read the EventSet that comes in for the new event. If this new EventSet is SUSPEND_ALL, then a deadlock will occur because no one will resume the EventSet. To avoid this, all EventRequests should be disabled before doing the invokeMethod, or the invokeMethod should not be done from the client's event handler thread.

The resumption of other threads during the invocation can be prevented by specifying the INVOKE_SINGLE_THREADED bit flag in the options argument; however, there is no protection against or recovery from the deadlocks described above, so this option should be used with great caution. Only the specified thread will be resumed (as described for all threads above). Upon completion of a single threaded invoke, the invoking thread will be suspended once again. Note that any threads started during the single threaded invocation will not be suspended when the invocation completes.

If the target VM is disconnected during the invoke (for example, through VirtualMachine.dispose()) the method invocation continues.

Parameters:
thread - the thread in which to invoke.
method - the Method to invoke.
arguments - the list of Value arguments bound to the invoked method. Values from the list are assigned to arguments in the order they appear in the method signature.
options - the integer bit flag options.
Returns:
a Value mirror of the invoked method's return value.
Throws:
IllegalArgumentException - if the method is not a member of this class or a superclass, if the size of the argument list does not match the number of declared arguemnts for the method, or if the method is an initializer, constructor or static intializer.
{@link - InvalidTypeException} if any argument in the argument list is not assignable to the corresponding method argument type.
ClassNotLoadedException - if any argument type has not yet been loaded through the appropriate class loader.
IncompatibleThreadStateException - if the specified thread has not been suspended by an event.
InvocationException - if the method invocation resulted in an exception in the target VM.
InvalidTypeException - If the arguments do not meet this requirement -- Object arguments must be assignment compatible with the argument type. This implies that the argument type must be loaded through the enclosing class's class loader. Primitive arguments must be either assignment compatible with the argument type or must be convertible to the argument type without loss of information. See JLS section 5.2 for more information on assignment compatibility.
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().

newInstance

ObjectReference newInstance(ThreadReference thread,
                            Method method,
                            List<? extends Value> arguments,
                            int options)
                            throws InvalidTypeException,
                                   ClassNotLoadedException,
                                   IncompatibleThreadStateException,
                                   InvocationException
Constructs a new instance of this type, using the given constructor Method in the target VM. The specified constructor must be defined in this class.

Instance creation will occur in the specified thread. Instance creation can occur only if the specified thread has been suspended by an event which occurred in that thread. Instance creation is not supported when the target VM has been suspended through VirtualMachine.suspend() or when the specified thread is suspended through ThreadReference.suspend().

The specified constructor is invoked with the arguments in the specified argument list. The invocation is synchronous; this method does not return until the constructor returns in the target VM. If the invoked method throws an exception, this method will throw an InvocationException which contains a mirror to the exception object thrown.

Object arguments must be assignment compatible with the argument type (This implies that the argument type must be loaded through the enclosing class's class loader). Primitive arguments must be either assignment compatible with the argument type or must be convertible to the argument type without loss of information. If the method being called accepts a variable number of arguments, then the last argument type is an array of some component type. The argument in the matching position can be omitted, or can be null, an array of the same component type, or an argument of the component type, followed by any number of other arguments of the same type. If the argument is omitted, then a 0 length array of the component type is passed. The component type can be a primitive type. Autoboxing is not supported. See the Java Language Specification. section 5.2 for more information on assignment compatibility.

By default, all threads in the target VM are resumed while the method is being invoked if they were previously suspended by an event or by VirtualMachine.suspend() or ThreadReference.suspend(). This is done to prevent the deadlocks that will occur if any of the threads own monitors that will be needed by the invoked method. It is possible that breakpoints or other events might occur during the invocation. Note, however, that this implicit resume acts exactly like ThreadReference.resume(), so if the thread's suspend count is greater than 1, it will remain in a suspended state during the invocation. By default, when the invocation completes, all threads in the target VM are suspended, regardless their state before the invocation.

The resumption of other threads during the invocation can be prevented by specifying the INVOKE_SINGLE_THREADED bit flag in the options argument; however, there is no protection against or recovery from the deadlocks described above, so this option should be used with great caution. Only the specified thread will be resumed (as described for all threads above). Upon completion of a single threaded invoke, the invoking thread will be suspended once again. Note that any threads started during the single threaded invocation will not be suspended when the invocation completes.

If the target VM is disconnected during the invoke (for example, through VirtualMachine.dispose()) the method invocation continues.

Parameters:
thread - the thread in which to invoke.
method - the constructor Method to invoke.
arguments - the list of Value arguments bound to the invoked constructor. Values from the list are assigned to arguments in the order they appear in the constructor signature.
options - the integer bit flag options.
Returns:
an ObjectReference mirror of the newly created object.
Throws:
IllegalArgumentException - if the method is not a member of this class, if the size of the argument list does not match the number of declared arguments for the constructor, or if the method is not a constructor.
{@link - InvalidTypeException} if any argument in the argument list is not assignable to the corresponding method argument type.
ClassNotLoadedException - if any argument type has not yet been loaded through the appropriate class loader.
IncompatibleThreadStateException - if the specified thread has not been suspended by an event.
InvocationException - if the method invocation resulted in an exception in the target VM.
InvalidTypeException - If the arguments do not meet this requirement -- Object arguments must be assignment compatible with the argument type. This implies that the argument type must be loaded through the enclosing class's class loader. Primitive arguments must be either assignment compatible with the argument type or must be convertible to the argument type without loss of information. See JLS section 5.2 for more information on assignment compatibility.
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().

concreteMethodByName

Method concreteMethodByName(String name,
                            String signature)
Returns a the single non-abstract Method visible from this class that has the given name and signature. See ReferenceType.methodsByName(java.lang.String, java.lang.String) for information on signature format.

The returned method (if non-null) is a component of ClassType.

Parameters:
name - the name of the method to find.
signature - the signature of the method to find
Returns:
the Method that matches the given name and signature or null if there is no match.
Throws:
ClassNotPreparedException - if methods are not yet available because the class has not yet been prepared.
See Also:
ReferenceType.visibleMethods(),
ReferenceType.methodsByName(java.lang.String name),
ReferenceType.methodsByName(java.lang.String name, java.lang.String signature)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


connect

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package com.sun.jdi.connect

This package defines connections between the virtual machine using the JDI and the target virtual machine.

See:
Description

Interface Summary
AttachingConnector | A connector which attaches to a previously running target VM.
Connector | A method of connection between a debugger and a target VM.
Connector.Argument | Specification for and value of a Connector argument.
Connector.BooleanArgument | Specification for and value of a Connector argument, whose value is Boolean.
Connector.IntegerArgument | Specification for and value of a Connector argument, whose value is an integer.
Connector.SelectedArgument | Specification for and value of a Connector argument, whose value is a String selected from a list of choices.
Connector.StringArgument | Specification for and value of a Connector argument, whose value is a String.
LaunchingConnector | A connector which can launch a target VM before connecting to it.
ListeningConnector | A connector which listens for a connection initiated by a target VM.
Transport | A method of communication between a debugger and a target VM.

Exception Summary
IllegalConnectorArgumentsException | Thrown to indicate an invalid argument or inconsistent passed to a Connector.
TransportTimeoutException | This exception may be thrown as a result of a timeout when attaching to a target VM, or waiting to accept a connection from a target VM.
VMStartException | A target VM was successfully launched, but terminated with an error before a connection could be established.

Package com.sun.jdi.connect Description

This package defines connections between the virtual machine using the JDI and the target virtual machine. In concert with VirtualMachineManager it is the mechanism for launching, attaching, etc to target virtual machines.

Methods may be added to the interfaces in the JDI packages in future releases. Existing packages may be renamed if the JDI becomes a standard extension.

Overview Package Class Use Tree Index Help
Java Debug Interface


com.sun.jdi.connect Class Hierarchy

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Hierarchy For Package com.sun.jdi.connect

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • com.sun.jdi.connect.IllegalConnectorArgumentsException
        • java.io.IOException
          • com.sun.jdi.connect.TransportTimeoutException
        • com.sun.jdi.connect.VMStartException

Interface Hierarchy

  • com.sun.jdi.connect.Connector
    • com.sun.jdi.connect.AttachingConnector
    • com.sun.jdi.connect.LaunchingConnector
    • com.sun.jdi.connect.ListeningConnector
  • java.io.Serializable
    • com.sun.jdi.connect.Connector.Argument
      • com.sun.jdi.connect.Connector.BooleanArgument
      • com.sun.jdi.connect.Connector.IntegerArgument
      • com.sun.jdi.connect.Connector.SelectedArgument
      • com.sun.jdi.connect.Connector.StringArgument
  • com.sun.jdi.connect.Transport
Overview Package Class Use Tree Index Help
Java Debug Interface


Uses of Package com.sun.jdi.connect

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Package
com.sun.jdi.connect

Packages that use com.sun.jdi.connect
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.connect | This package defines connections between the virtual machine using the JDI and the target virtual machine.

Classes in com.sun.jdi.connect used by com.sun.jdi
AttachingConnector
A connector which attaches to a previously running target VM.
Connector
A method of connection between a debugger and a target VM.
LaunchingConnector
A connector which can launch a target VM before connecting to it.
ListeningConnector
A connector which listens for a connection initiated by a target VM.

Classes in com.sun.jdi.connect used by com.sun.jdi.connect
Connector
A method of connection between a debugger and a target VM.
Connector.Argument
Specification for and value of a Connector argument.
IllegalConnectorArgumentsException
Thrown to indicate an invalid argument or inconsistent passed to a Connector.
Transport
A method of communication between a debugger and a target VM.
VMStartException
A target VM was successfully launched, but terminated with an error before a connection could be established.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


AttachingConnector

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect
Interface AttachingConnector

All Superinterfaces:
Connector
public interface AttachingConnector
extends Connector

A connector which attaches to a previously running target VM.

Since:
1.3

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.jdi.connect.Connector
Connector.Argument, Connector.BooleanArgument, Connector.IntegerArgument, Connector.SelectedArgument, Connector.StringArgument
Method Summary
 VirtualMachine attach(Map<String,? extends Connector.Argument> arguments)
Attaches to a running application and and returns a mirror of its VM.
Methods inherited from interface com.sun.jdi.connect.Connector
defaultArguments, description, name, transport

Method Detail

attach

VirtualMachine attach(Map<String,? extends Connector.Argument> arguments)
                      throws IOException,
                             IllegalConnectorArgumentsException
Attaches to a running application and and returns a mirror of its VM.

The connector uses the given argument map in attaching the application. These arguments will include addressing information that identifies the VM. The argument map associates argument name strings to instances of Connector.Argument. The default argument map for a connector can be obtained through Connector.defaultArguments(). Argument map values can be changed, but map entries should not be added or deleted.

Parameters:
arguments - the argument map to be used in launching the VM.
Returns:
the VirtualMachine mirror of the target VM.
Throws:
TransportTimeoutException - when the Connector encapsulates a transport that supports a timeout when attaching, a Connector.Argument representing a timeout has been set in the argument map, and a timeout occurs when trying to attach to the target VM.
IOException - when unable to attach. Specific exceptions are dependent on the Connector implementation in use.
IllegalConnectorArgumentsException - when one of the connector arguments is invalid.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Uses of Class com.sun.jdi.connect.IllegalConnectorArgumentsException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.connect.IllegalConnectorArgumentsException

Packages that use IllegalConnectorArgumentsException
com.sun.jdi.connect This package defines connections between the virtual machine using the JDI and the target virtual machine.

Uses of IllegalConnectorArgumentsException in com.sun.jdi.connect

Methods in com.sun.jdi.connect that throw IllegalConnectorArgumentsException
VirtualMachine | ListeningConnector.accept(Map<String,? extends Connector.Argument> arguments) Waits for a target VM to attach to this connector.
VirtualMachine | AttachingConnector.attach(Map<String,? extends Connector.Argument> arguments) Attaches to a running application and and returns a mirror of its VM.
VirtualMachine | LaunchingConnector.launch(Map<String,? extends Connector.Argument> arguments) Launches an application and connects to its VM.
String | ListeningConnector.startListening(Map<String,? extends Connector.Argument> arguments) Listens for one or more connections initiated by target VMs.
void | ListeningConnector.stopListening(Map<String,? extends Connector.Argument> arguments) Cancels listening for connections.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.connect.TransportTimeoutException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.connect.TransportTimeoutException

No usage of com.sun.jdi.connect.TransportTimeoutException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.connect.VMStartException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.connect.VMStartException

Packages that use VMStartException
com.sun.jdi.connect This package defines connections between the virtual machine using the JDI and the target virtual machine.

Uses of VMStartException in com.sun.jdi.connect

Methods in com.sun.jdi.connect that throw VMStartException
 VirtualMachine LaunchingConnector.launch(Map<String,? extends Connector.Argument> arguments)
Launches an application and connects to its VM.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.connect.AttachingConnector

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.connect.AttachingConnector

Packages that use AttachingConnector
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of AttachingConnector in com.sun.jdi

Methods in com.sun.jdi that return types with arguments of type AttachingConnector
 List<AttachingConnector> VirtualMachineManager.attachingConnectors()
Returns the list of known AttachingConnector objects.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.connect.Connector

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.connect.Connector

Packages that use Connector
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.connect | This package defines connections between the virtual machine using the JDI and the target virtual machine.

Uses of Connector in com.sun.jdi

Methods in com.sun.jdi that return types with arguments of type Connector
 List<Connector> VirtualMachineManager.allConnectors()
Returns the list of all known Connector objects.

Uses of Connector in com.sun.jdi.connect

Subinterfaces of Connector in com.sun.jdi.connect
interface | AttachingConnector A connector which attaches to a previously running target VM.
interface | LaunchingConnector A connector which can launch a target VM before connecting to it.
interface | ListeningConnector A connector which listens for a connection initiated by a target VM.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.connect.Connector.Argument

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.connect.Connector.Argument

Packages that use Connector.Argument
com.sun.jdi.connect This package defines connections between the virtual machine using the JDI and the target virtual machine.

Uses of Connector.Argument in com.sun.jdi.connect

Subinterfaces of Connector.Argument in com.sun.jdi.connect
static interface | Connector.BooleanArgument Specification for and value of a Connector argument, whose value is Boolean.
static interface | Connector.IntegerArgument Specification for and value of a Connector argument, whose value is an integer.
static interface | Connector.SelectedArgument Specification for and value of a Connector argument, whose value is a String selected from a list of choices.
static interface | Connector.StringArgument Specification for and value of a Connector argument, whose value is a String.

Methods in com.sun.jdi.connect that return types with arguments of type Connector.Argument
 Map<String,Connector.Argument> Connector.defaultArguments()
Returns the arguments accepted by this Connector and their default values.

Method parameters in com.sun.jdi.connect with type arguments of type Connector.Argument
VirtualMachine | ListeningConnector.accept(Map<String,? extends Connector.Argument> arguments) Waits for a target VM to attach to this connector.
VirtualMachine | AttachingConnector.attach(Map<String,? extends Connector.Argument> arguments) Attaches to a running application and and returns a mirror of its VM.
VirtualMachine | LaunchingConnector.launch(Map<String,? extends Connector.Argument> arguments) Launches an application and connects to its VM.
String | ListeningConnector.startListening(Map<String,? extends Connector.Argument> arguments) Listens for one or more connections initiated by target VMs.
void | ListeningConnector.stopListening(Map<String,? extends Connector.Argument> arguments) Cancels listening for connections.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.connect.Connector.BooleanArgument

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.connect.Connector.BooleanArgument

No usage of com.sun.jdi.connect.Connector.BooleanArgument

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.connect.Connector.IntegerArgument

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.connect.Connector.IntegerArgument

No usage of com.sun.jdi.connect.Connector.IntegerArgument

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.connect.Connector.SelectedArgument

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.connect.Connector.SelectedArgument

No usage of com.sun.jdi.connect.Connector.SelectedArgument

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.connect.Connector.StringArgument

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.connect.Connector.StringArgument

No usage of com.sun.jdi.connect.Connector.StringArgument

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.connect.LaunchingConnector

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.connect.LaunchingConnector

Packages that use LaunchingConnector
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of LaunchingConnector in com.sun.jdi

Methods in com.sun.jdi that return LaunchingConnector
 LaunchingConnector VirtualMachineManager.defaultConnector()
Identifies the default connector.

Methods in com.sun.jdi that return types with arguments of type LaunchingConnector
 List<LaunchingConnector> VirtualMachineManager.launchingConnectors()
Returns the list of known LaunchingConnector objects.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.connect.ListeningConnector

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.connect.ListeningConnector

Packages that use ListeningConnector
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of ListeningConnector in com.sun.jdi

Methods in com.sun.jdi that return types with arguments of type ListeningConnector
 List<ListeningConnector> VirtualMachineManager.listeningConnectors()
Returns the list of known ListeningConnector objects.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.connect.Transport

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.connect.Transport

Packages that use Transport
com.sun.jdi.connect This package defines connections between the virtual machine using the JDI and the target virtual machine.

Uses of Transport in com.sun.jdi.connect

Methods in com.sun.jdi.connect that return Transport
 Transport Connector.transport()
Returns the transport mechanism used by this connector to establish connections with a target VM.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Connector

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect
Interface Connector

All Known Subinterfaces:
AttachingConnector, LaunchingConnector, ListeningConnector
public interface Connector

A method of connection between a debugger and a target VM. A connector encapsulates exactly one Transport. used to establish the connection. Each connector has a set of arguments which controls its operation. The arguments are stored as a map, keyed by a string. Each implementation defines the string argument keys it accepts.

Since:
1.3
See Also:
LaunchingConnector, AttachingConnector, ListeningConnector, Connector.Argument

Nested Class Summary
static interface | Connector.Argument Specification for and value of a Connector argument.
static interface | Connector.BooleanArgument Specification for and value of a Connector argument, whose value is Boolean.
static interface | Connector.IntegerArgument Specification for and value of a Connector argument, whose value is an integer.
static interface | Connector.SelectedArgument Specification for and value of a Connector argument, whose value is a String selected from a list of choices.
static interface | Connector.StringArgument Specification for and value of a Connector argument, whose value is a String.
Method Summary
Map<String,Connector.Argument> | defaultArguments() Returns the arguments accepted by this Connector and their default values.
String | description() Returns a human-readable description of this connector and its purpose.
String | name() Returns a short identifier for the connector.
Transport | transport() Returns the transport mechanism used by this connector to establish connections with a target VM.

Method Detail

name

String name()
Returns a short identifier for the connector. Connector implementors should follow similar naming conventions as are used with packages to avoid name collisions. For example, the Sun connector implementations have names prefixed with "com.sun.jdi.". Not intended for exposure to end-user.

Returns:
the name of this connector.

description

String description()
Returns a human-readable description of this connector and its purpose.

Returns:
the description of this connector

transport

Transport transport()
Returns the transport mechanism used by this connector to establish connections with a target VM.

Returns:
the Transport used by this connector.

defaultArguments

Map<String,Connector.Argument> defaultArguments()
Returns the arguments accepted by this Connector and their default values. The keys of the returned map are string argument names. The values are Connector.Argument containing information about the argument and its default value.

Returns:
the map associating argument names with argument information and default value.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Connector.Argument

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect
Interface Connector.Argument

All Superinterfaces:
Serializable
All Known Subinterfaces:
Connector.BooleanArgument, Connector.IntegerArgument, Connector.SelectedArgument, Connector.StringArgument
Enclosing interface:
Connector
public static interface Connector.Argument
extends Serializable

Specification for and value of a Connector argument. Will always implement a subinterface of Argument: Connector.StringArgument, Connector.BooleanArgument, Connector.IntegerArgument, or Connector.SelectedArgument.

Method Summary
String | description() Returns a human-readable description of this argument and its purpose.
boolean | isValid(String value) Performs basic sanity check of argument.
String | label() Returns a short human-readable label for this argument.
boolean | mustSpecify() Indicates whether the argument must be specified.
String | name() Returns a short, unique identifier for the argument.
void | setValue(String value) Sets the value of the argument.
String | value() Returns the current value of the argument.

Method Detail

name

String name()
Returns a short, unique identifier for the argument. Not intended for exposure to end-user.

Returns:
the name of this argument.

label

String label()
Returns a short human-readable label for this argument.

Returns:
a label for this argument

description

String description()
Returns a human-readable description of this argument and its purpose.

Returns:
the description of this argument

value

String value()
Returns the current value of the argument. Initially, the default value is returned. If the value is currently unspecified, null is returned.

Returns:
the current value of the argument.

setValue

void setValue(String value)
Sets the value of the argument. The value should be checked with isValid(String) before setting it; invalid values will throw an exception when the connection is established - for example, on LaunchingConnector.launch(java.util.Map)

isValid

boolean isValid(String value)
Performs basic sanity check of argument.

Returns:
true if the value is valid to be used in setValue(String)

mustSpecify

boolean mustSpecify()
Indicates whether the argument must be specified. If true, setValue(java.lang.String) must be used to set a non-null value before using this argument in establishing a connection.

Returns:
true if the argument must be specified; false otherwise.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Connector.BooleanArgument

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect
Interface Connector.BooleanArgument

All Superinterfaces:
Connector.Argument, Serializable
Enclosing interface:
Connector
public static interface Connector.BooleanArgument
extends Connector.Argument

Specification for and value of a Connector argument, whose value is Boolean. Boolean values are represented by the localized versions of the strings "true" and "false".

Method Summary
boolean | booleanValue() Return the value of the argument as a boolean.
boolean | isValid(String value) Performs basic sanity check of argument.
void | setValue(boolean value) Sets the value of the argument.
String | stringValueOf(boolean value) Return the string representation of the value parameter.
Methods inherited from interface com.sun.jdi.connect.Connector.Argument
description, label, mustSpecify, name, setValue, value

Method Detail

setValue

void setValue(boolean value)
Sets the value of the argument.

isValid

boolean isValid(String value)
Performs basic sanity check of argument.

Specified by:
isValid in interface Connector.Argument
Returns:
true if value is a string representation of a boolean value.
See Also:
stringValueOf(boolean)

stringValueOf

String stringValueOf(boolean value)
Return the string representation of the value parameter. Does not set or examine the current value of this instance.

Returns:
the localized String representation of the boolean value.

booleanValue

boolean booleanValue()
Return the value of the argument as a boolean. Since the argument may not have been set or may have an invalid value isValid(String) should be called on Connector.Argument.value() to check its validity. If it is invalid the boolean returned by this method is undefined.

Returns:
the value of the argument as a boolean.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Connector.IntegerArgument

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect
Interface Connector.IntegerArgument

All Superinterfaces:
Connector.Argument, Serializable
Enclosing interface:
Connector
public static interface Connector.IntegerArgument
extends Connector.Argument

Specification for and value of a Connector argument, whose value is an integer. Integer values are represented by their corresponding strings.

Method Summary
int | intValue() Return the value of the argument as a int.
boolean | isValid(int value) Performs basic sanity check of argument.
boolean | isValid(String value) Performs basic sanity check of argument.
int | max() The upper bound for the value.
int | min() The lower bound for the value.
void | setValue(int value) Sets the value of the argument.
String | stringValueOf(int value) Return the string representation of the value parameter.
Methods inherited from interface com.sun.jdi.connect.Connector.Argument
description, label, mustSpecify, name, setValue, value

Method Detail

setValue

void setValue(int value)
Sets the value of the argument. The value should be checked with isValid(int) before setting it; invalid values will throw an exception when the connection is established - for example, on LaunchingConnector.launch(java.util.Map)

isValid

boolean isValid(String value)
Performs basic sanity check of argument.

Specified by:
isValid in interface Connector.Argument
Returns:
true if value represents an int that is min() <= value <= max()

isValid

boolean isValid(int value)
Performs basic sanity check of argument.

Returns:
true if min() <= value <= max()

stringValueOf

String stringValueOf(int value)
Return the string representation of the value parameter. Does not set or examine the current value of this instance.

Returns:
the String representation of the int value.

intValue

int intValue()
Return the value of the argument as a int. Since the argument may not have been set or may have an invalid value isValid(String) should be called on Connector.Argument.value() to check its validity. If it is invalid the int returned by this method is undefined.

Returns:
the value of the argument as a int.

max

int max()
The upper bound for the value.

Returns:
the maximum allowed value for this argument.

min

int min()
The lower bound for the value.

Returns:
the minimum allowed value for this argument.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Connector.SelectedArgument

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect
Interface Connector.SelectedArgument

All Superinterfaces:
Connector.Argument, Serializable
Enclosing interface:
Connector
public static interface Connector.SelectedArgument
extends Connector.Argument

Specification for and value of a Connector argument, whose value is a String selected from a list of choices.

Method Summary
List<String> | choices() Return the possible values for the argument
boolean | isValid(String value) Performs basic sanity check of argument.
Methods inherited from interface com.sun.jdi.connect.Connector.Argument
description, label, mustSpecify, name, setValue, value

Method Detail

choices

List<String> choices()
Return the possible values for the argument

Returns:
List of String

isValid

boolean isValid(String value)
Performs basic sanity check of argument.

Specified by:
isValid in interface Connector.Argument
Returns:
true if value is one of choices().
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Connector.StringArgument

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect
Interface Connector.StringArgument

All Superinterfaces:
Connector.Argument, Serializable
Enclosing interface:
Connector
public static interface Connector.StringArgument
extends Connector.Argument

Specification for and value of a Connector argument, whose value is a String.

Method Summary
 boolean isValid(String value)
Performs basic sanity check of argument.
Methods inherited from interface com.sun.jdi.connect.Connector.Argument
description, label, mustSpecify, name, setValue, value

Method Detail

isValid

boolean isValid(String value)
Performs basic sanity check of argument.

Specified by:
isValid in interface Connector.Argument
Returns:
true always
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IllegalConnectorArgumentsException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect
Class IllegalConnectorArgumentsException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  com.sun.jdi.connect.IllegalConnectorArgumentsException
All Implemented Interfaces:
Serializable
public class IllegalConnectorArgumentsException
extends Exception

Thrown to indicate an invalid argument or inconsistent passed to a Connector.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
IllegalConnectorArgumentsException(String s, List<String> names)
Construct an IllegalConnectorArgumentsException with the specified detail message and a List of names of arguments which are invalid or inconsistent.
IllegalConnectorArgumentsException(String s, String name)
Construct an IllegalConnectorArgumentsException with the specified detail message and the name of the argument which is invalid or inconsistent.
Method Summary
 List<String> argumentNames()
Return a List containing the names of the invalid or inconsistent arguments.
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

IllegalConnectorArgumentsException

public IllegalConnectorArgumentsException(String s,
                                          String name)
Construct an IllegalConnectorArgumentsException with the specified detail message and the name of the argument which is invalid or inconsistent.

Parameters:
s - the detailed message.
name - the name of the invalid or inconsistent argument.

IllegalConnectorArgumentsException

public IllegalConnectorArgumentsException(String s,
                                          List<String> names)
Construct an IllegalConnectorArgumentsException with the specified detail message and a List of names of arguments which are invalid or inconsistent.

Parameters:
s - the detailed message.
names - a List containing the names of the invalid or inconsistent argument.
Method Detail

argumentNames

public List<String> argumentNames()
Return a List containing the names of the invalid or inconsistent arguments.

Returns:
a List of argument names.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LaunchingConnector

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect
Interface LaunchingConnector

All Superinterfaces:
Connector
public interface LaunchingConnector
extends Connector

A connector which can launch a target VM before connecting to it.

Since:
1.3

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.jdi.connect.Connector
Connector.Argument, Connector.BooleanArgument, Connector.IntegerArgument, Connector.SelectedArgument, Connector.StringArgument
Method Summary
 VirtualMachine launch(Map<String,? extends Connector.Argument> arguments)
Launches an application and connects to its VM.
Methods inherited from interface com.sun.jdi.connect.Connector
defaultArguments, description, name, transport

Method Detail

launch

VirtualMachine launch(Map<String,? extends Connector.Argument> arguments)
                      throws IOException,
                             IllegalConnectorArgumentsException,
                             VMStartException
Launches an application and connects to its VM. Properties of the launch (possibly including options, main class, and arguments) are specified in arguments. The argument map associates argument name strings to instances of Connector.Argument. The default argument map for a connector can be obtained through Connector.defaultArguments(). Argument map values can be changed, but map entries should not be added or deleted.

A target VM launched by a launching connector is not guaranteed to be stable until after the VMStartEvent has been received.

Important note: If a target VM is launched through this funcctions, its output and error streams must be read as it executes. These streams are available through the Process object returned by VirtualMachine.process(). If the streams are not periodically read, the target VM will stop executing when the buffers for these streams are filled.

Parameters:
arguments - the argument map to be used in launching the VM.
Returns:
the VirtualMachine mirror of the target VM.
Throws:
IOException - when unable to launch. Specific exceptions are dependent on the Connector implementation in use.
IllegalConnectorArgumentsException - when one of the connector arguments is invalid.
VMStartException - when the VM was successfully launched, but terminated with an error before a connection could be established.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ListeningConnector

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect
Interface ListeningConnector

All Superinterfaces:
Connector
public interface ListeningConnector
extends Connector

A connector which listens for a connection initiated by a target VM.

Since:
1.3

Nested Class Summary
Nested classes/interfaces inherited from interface com.sun.jdi.connect.Connector
Connector.Argument, Connector.BooleanArgument, Connector.IntegerArgument, Connector.SelectedArgument, Connector.StringArgument
Method Summary
VirtualMachine | accept(Map<String,? extends Connector.Argument> arguments) Waits for a target VM to attach to this connector.
String | startListening(Map<String,? extends Connector.Argument> arguments) Listens for one or more connections initiated by target VMs.
void | stopListening(Map<String,? extends Connector.Argument> arguments) Cancels listening for connections.
boolean | supportsMultipleConnections() Indicates whether this listening connector supports multiple connections for a single argument map.
Methods inherited from interface com.sun.jdi.connect.Connector
defaultArguments, description, name, transport

Method Detail

supportsMultipleConnections

boolean supportsMultipleConnections()
Indicates whether this listening connector supports multiple connections for a single argument map. If so, a call to startListening(java.util.Map) may allow multiple target VM to become connected.

Returns:
true if multiple connections are supported; false otherwise.

startListening

String startListening(Map<String,? extends Connector.Argument> arguments)
                      throws IOException,
                             IllegalConnectorArgumentsException
Listens for one or more connections initiated by target VMs. The connector uses the given argument map in determining the address at which to listen or else it generates an appropriate listen address. In either case, an address string is returned from this method which can be used in starting target VMs to identify this connector. The format of the address string is connector, transport, and, possibly, platform dependent.

The argument map associates argument name strings to instances of Connector.Argument. The default argument map for a connector can be obtained through Connector.defaultArguments(). Argument map values can be changed, but map entries should not be added or deleted.

This method does not return a VirtualMachine, and, normally, returns before any target VM initiates a connection. The connected target is obtained through accept(java.util.Map) (using the same argument map as is passed to this method).

If arguments contains addressing information. and only one conection will be accepted, the accept method can be called immediately without calling this method.

Returns:
the address at which the connector is listening for a connection.
Throws:
IOException - when unable to start listening. Specific exceptions are dependent on the Connector implementation in use.
IllegalConnectorArgumentsException - when one of the connector arguments is invalid.

stopListening

void stopListening(Map<String,? extends Connector.Argument> arguments)
                   throws IOException,
                          IllegalConnectorArgumentsException
Cancels listening for connections. The given argument map should match the argument map given for a previous startListening(java.util.Map) invocation.

Throws:
IOException - when unable to stop listening. Specific exceptions are dependent on the Connector implementation in use.
IllegalConnectorArgumentsException - when one of the connector arguments is invalid.

accept

VirtualMachine accept(Map<String,? extends Connector.Argument> arguments)
                      throws IOException,
                             IllegalConnectorArgumentsException
Waits for a target VM to attach to this connector.

Throws:
TransportTimeoutException - when the Connector encapsulates a transport that supports a timeout when accepting, a Connector.Argument representing a timeout has been set in the argument map, and a timeout occurs whilst waiting for the target VM to connect.
IOException - when unable to accept. Specific exceptions are dependent on the Connector implementation in use.
IllegalConnectorArgumentsException - when one of the connector arguments is invalid.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


spi

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package com.sun.jdi.connect.spi

This package comprises the interfaces and classes used to develop new TransportService implementations.

See:
Description

Class Summary
Connection | A connection between a debugger and a target VM which it debugs.
TransportService | A transport service for connections between a debugger and a target VM.
TransportService.Capabilities | The transport service capabilities.
TransportService.ListenKey | A listen key.

Exception Summary
ClosedConnectionException This exception may be thrown as a result of an asynchronous close of a Connection while an I/O operation is in progress.

Package com.sun.jdi.connect.spi Description

This package comprises the interfaces and classes used to develop new TransportService implementations.

Overview Package Class Use Tree Index Help
Java Debug Interface


com.sun.jdi.connect.spi Class Hierarchy

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Hierarchy For Package com.sun.jdi.connect.spi

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • com.sun.jdi.connect.spi.Connection
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.io.IOException
          • com.sun.jdi.connect.spi.ClosedConnectionException
    • com.sun.jdi.connect.spi.TransportService
    • com.sun.jdi.connect.spi.TransportService.Capabilities
    • com.sun.jdi.connect.spi.TransportService.ListenKey
Overview Package Class Use Tree Index Help
Java Debug Interface


Uses of Package com.sun.jdi.connect.spi

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Package
com.sun.jdi.connect.spi

Packages that use com.sun.jdi.connect.spi
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.connect.spi | This package comprises the interfaces and classes used to develop new TransportService implementations.

Classes in com.sun.jdi.connect.spi used by com.sun.jdi
Connection
A connection between a debugger and a target VM which it debugs.

Classes in com.sun.jdi.connect.spi used by com.sun.jdi.connect.spi
Connection
A connection between a debugger and a target VM which it debugs.
TransportService.Capabilities
The transport service capabilities.
TransportService.ListenKey
A listen key.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.connect.spi.ClosedConnectionException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.connect.spi.ClosedConnectionException

No usage of com.sun.jdi.connect.spi.ClosedConnectionException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.connect.spi.Connection

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.connect.spi.Connection

Packages that use Connection
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.connect.spi | This package comprises the interfaces and classes used to develop new TransportService implementations.

Uses of Connection in com.sun.jdi

Methods in com.sun.jdi with parameters of type Connection
VirtualMachine | VirtualMachineManager.createVirtualMachine(Connection connection) Creates a new virtual machine.
VirtualMachine | VirtualMachineManager.createVirtualMachine(Connection connection, Process process) Create a virtual machine mirror for a target VM.

Uses of Connection in com.sun.jdi.connect.spi

Methods in com.sun.jdi.connect.spi that return Connection
abstract Connection | TransportService.accept(TransportService.ListenKey listenKey, long acceptTimeout, long handshakeTimeout) Accept a connection from a target VM.
abstract Connection | TransportService.attach(String address, long attachTimeout, long handshakeTimeout) Attaches to the specified address.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.connect.spi.TransportService

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.connect.spi.TransportService

No usage of com.sun.jdi.connect.spi.TransportService

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.connect.spi.TransportService.Capabilities

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.connect.spi.TransportService.Capabilities

Packages that use TransportService.Capabilities
com.sun.jdi.connect.spi This package comprises the interfaces and classes used to develop new TransportService implementations.

Uses of TransportService.Capabilities in com.sun.jdi.connect.spi

Methods in com.sun.jdi.connect.spi that return TransportService.Capabilities
abstract  TransportService.Capabilities TransportService.capabilities()
Returns the capabilities of the transport service.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.connect.spi.TransportService.ListenKey

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.connect.spi.TransportService.ListenKey

Packages that use TransportService.ListenKey
com.sun.jdi.connect.spi This package comprises the interfaces and classes used to develop new TransportService implementations.

Uses of TransportService.ListenKey in com.sun.jdi.connect.spi

Methods in com.sun.jdi.connect.spi that return TransportService.ListenKey
abstract TransportService.ListenKey | TransportService.startListening() Listens on an address choosen by the transport service.
abstract TransportService.ListenKey | TransportService.startListening(String address) Listens on the specified address for inbound connections.

Methods in com.sun.jdi.connect.spi with parameters of type TransportService.ListenKey
abstract Connection | TransportService.accept(TransportService.ListenKey listenKey, long acceptTimeout, long handshakeTimeout) Accept a connection from a target VM.
abstract void | TransportService.stopListening(TransportService.ListenKey listenKey) Stop listening for inbound connections.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


ClosedConnectionException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect.spi
Class ClosedConnectionException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.io.IOException
                extended by  com.sun.jdi.connect.spi.ClosedConnectionException
All Implemented Interfaces:
Serializable
public class ClosedConnectionException
extends IOException

This exception may be thrown as a result of an asynchronous close of a Connection while an I/O operation is in progress.

When a thread is blocked in readPacket waiting for packet from a target VM the Connection may be closed asynchronous by another thread invokving the close method. When this arises the thread in readPacket will throw this exception. Similiarly when a thread is blocked in Connection.writePacket(byte[]) the Connection may be closed. When this occurs the thread in writePacket will throw this exception.

Since:
1.5
See Also:
Connection.readPacket(), Connection.writePacket(byte[]), Serialized Form

Constructor Summary
ClosedConnectionException()
Constructs a ClosedConnectionException with no detail message.
ClosedConnectionException(String message)
Constructs a ClosedConnectionException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ClosedConnectionException

public ClosedConnectionException()
Constructs a ClosedConnectionException with no detail message.

ClosedConnectionException

public ClosedConnectionException(String message)
Constructs a ClosedConnectionException with the specified detail message.

Parameters:
message - the detail message pertaining to this exception.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Connection

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect.spi
Class Connection

java.lang.Object
    extended by  com.sun.jdi.connect.spi.Connection

public abstract class Connection
extends Object

A connection between a debugger and a target VM which it debugs.

A Connection represents a bi-directional communication channel between a debugger and a target VM. A Connection is created when TransportService establishes a connection and successfully handshakes with a target VM. A TransportService implementation provides a reliable JDWP packet transportation service and consequently a Connection provides a reliable flow of JDWP packets between the debugger and the target VM. A Connection is stream oriented, that is, the JDWP packets written to a connection are read by the target VM in the order in which they were written. Similiarly packets written to a Connection by the target VM are read by the debugger in the order in which they were written.

A connection is either open or closed. It is open upon creation, and remains open until it is closed. Once closed, it remains closed, and any attempt to invoke an I/O operation upon it will cause a ClosedConnectionException to be thrown. A connection can be tested by invoking the isOpen method.

A Connection is safe for access by multiple concurrent threads, although at most one thread may be reading and at most one thread may be writing at any given time.

Since:
1.5

Constructor Summary
Connection()
Method Summary
abstract void | close() Closes this connection.
abstract boolean | isOpen() Tells whether or not this connection is open.
abstract byte[] | readPacket() Reads a packet from the target VM.
abstract void | writePacket(byte[] pkt) Writes a packet to the target VM.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Connection

public Connection()
Method Detail

readPacket

public abstract byte[] readPacket()
                           throws IOException
Reads a packet from the target VM.

Attempts to read a JDWP packet from the target VM. A read operation may block indefinitely and only returns when it reads all bytes of a packet, or in the case of a transport service that is based on a stream-oriented communication protocol, the end of stream is encountered.

Reading a packet does not do any integrity checking on the packet aside from a check that the length of the packet (as indicated by the value of the length field, the first four bytes of the packet) is 11 or more bytes. If the value of the length value is less then 11 then an IOException is thrown.

Returns a byte array of a length equal to the length of the received packet, or a byte array of length 0 when an end of stream is encountered. If end of stream is encountered after some, but not all bytes of a packet, are read then it is considered an I/O error and an IOException is thrown. The first byte of the packet is stored in element 0 of the byte array, the second in element 1, and so on. The bytes in the byte array are laid out as per the JDWP specification. That is, all fields in the packet are in big endian order as per the JDWP specification.

This method may be invoked at any time. If another thread has already initiated a readPacket on this connection then the invocation of this method will block until the first operation is complete.

Returns:
the packet read from the target VM
Throws:
ClosedConnectionException - If the connection is closed, or another thread closes the connection while the readPacket is in progress.
IOException - If the length of the packet (as indictaed by the first 4 bytes) is less than 11 bytes, or an I/O error occurs.

writePacket

public abstract void writePacket(byte[] pkt)
                          throws IOException
Writes a packet to the target VM.

Attempts to write, or send, a JDWP packet to the target VM. A write operation only returns after writing the entire packet to the target VM. Writing the entire packet does not mean the entire packet has been transmitted to the target VM but rather that all bytes have been written to the transport service. A transport service based on a TCP/IP connection may, for example, buffer some or all of the packet before transmission on the network.

The byte array provided to this method should be laid out as per the JDWP specification. That is, all fields in the packet are in big endian order. The first byte, that is element pkt[0], is the first byte of the length field. pkt[1] is the second byte of the length field, and so on.

Writing a packet does not do any integrity checking on the packet aside from checking the packet length. Checking the packet length requires checking that the value of the length field (as indicated by the first four bytes of the packet) is 11 or greater. Consequently the length of the byte array provided to this method, that is pkt.length, must be 11 or more, and must be equal or greater than the value of the length field. If the length of the byte array is greater than the value of the length field then all bytes from element pkt[length] onwards are ignored. In other words, any additional bytes that follow the packet in the byte array are ignored and will not be transmitted to the target VM.

A write operation may block or may complete immediately. The exact circumstances when an operation blocks depends on the transport service. In the case of a TCP/IP connection to the target VM, the writePacket method may block if there is network congestion or there is insufficient space to buffer the packet in the underlying network system.

This method may be invoked at any time. If another thread has already initiated a write operation upon this Connection then a subsequent invocation of this method will block until the first operation is complete.

Parameters:
pkt - The packet to write to the target VM.
Throws:
ClosedConnectionException - If the connection is closed, or another thread closes the connection while the write operation is in progress.
IOException - If an I/O error occurs.
IllegalArgumentException - If the value of the length field is invalid, or the byte array is of insufficient length.

close

public abstract void close()
                    throws IOException
Closes this connection.

If the connection is already closed then invoking this method has no effect. After a connection is closed, any further attempt calls to readPacket or writePacket will throw a ClosedConnectionException.

Any thread currently blocked in an I/O operation (readPacket or writePacket) will throw a ClosedConnectionException).

This method may be invoked at any time. If some other thread has already invoked it, however, then another invocation will block until the first invocation is complete, after which it will return without effect.

Throws:
IOException - If an I/O error occurs

isOpen

public abstract boolean isOpen()
Tells whether or not this connection is open.

Returns:
true if, and only if, this connection is open
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TransportService

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect.spi
Class TransportService

java.lang.Object
    extended by  com.sun.jdi.connect.spi.TransportService

public abstract class TransportService
extends Object

A transport service for connections between a debugger and a target VM.

A transport service is a concrete subclass of this class that has a zero-argument constructor and implements the abstract methods specified below. It is the underlying service used by a Transport for connections between a debugger and a target VM.

A transport service is used to establish a connection between a debugger and a target VM, and to transport Java Debug Wire Protocol (JDWP) packets over an underlying communication protocol. In essence a transport service implementation binds JDWP (as specified in the JDWP specification) to an underlying communication protocol. A transport service implementation provides a reliable JDWP packet transportation service. JDWP packets are sent to and from the target VM without duplication or data loss. A transport service implementation may be based on an underlying communication protocol that is reliable or unreliable. If the underlying communication protocol is reliable then the transport service implementation may be relatively simple and may only need to transport JDWP packets as payloads of the underlying communication protocol. In the case of an unreliable communication protocol the transport service implementation may include additional protocol support in order to ensure that packets are not duplicated and that there is no data loss. The details of such protocols are specific to the implementation but may involve techniques such as the positive acknowledgment with retransmission technique used in protocols such as the Transmission Control Protocol (TCP) (see RFC 793 ).

A transport service can be used to initiate a connection to a target VM. This is done by invoking the attach(java.lang.String, long, long) method. Alternatively, a transport service can listen and accept connections initiated by a target VM. This is done by invoking the startListening(String) method to put the transport into listen mode. Then the accept(com.sun.jdi.connect.spi.TransportService.ListenKey, long, long) method is used to accept a connection initiated by a target VM.

Since:
1.5

Nested Class Summary
static class | TransportService.Capabilities The transport service capabilities.
static class | TransportService.ListenKey A listen key.
Constructor Summary
TransportService()
Method Summary
abstract Connection | accept(TransportService.ListenKey listenKey, long acceptTimeout, long handshakeTimeout) Accept a connection from a target VM.
abstract Connection | attach(String address, long attachTimeout, long handshakeTimeout) Attaches to the specified address.
abstract TransportService.Capabilities | capabilities() Returns the capabilities of the transport service.
abstract String | description() Returns a description of the transport service.
abstract String | name() Returns a name to identify the transport service.
abstract TransportService.ListenKey | startListening() Listens on an address choosen by the transport service.
abstract TransportService.ListenKey | startListening(String address) Listens on the specified address for inbound connections.
abstract void | stopListening(TransportService.ListenKey listenKey) Stop listening for inbound connections.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TransportService

public TransportService()
Method Detail

name

public abstract String name()
Returns a name to identify the transport service.

Returns:
The name of the transport service

description

public abstract String description()
Returns a description of the transport service.

Returns:
The description of the transport service

capabilities

public abstract TransportService.Capabilities capabilities()
Returns the capabilities of the transport service.

Returns:
the transport service capabilities

attach

public abstract Connection attach(String address,
                                  long attachTimeout,
                                  long handshakeTimeout)
                           throws IOException
Attaches to the specified address.

Attaches to the specified address and returns a connection representing the bi-directional communication channel to the target VM.

Attaching to the target VM involves two steps: First, a connection is established to specified address. This is followed by a handshake to ensure that the connection is to a target VM. The handshake involves the exchange of a string JDWP-Handshake as specified in the Java Debug Wire Protocol specification.

Parameters:
address - The address of the target VM.
attachTimeout - If this transport service supports an attach timeout, and if attachTimeout is positive, then it specifies the timeout, in milliseconds (more or less), to use when attaching to the target VM. If the transport service does not support an attach timeout, or if attachTimeout is specified as zero then attach without any timeout.
handshakeTimeout - If this transport service supports a handshake timeout, and if handshakeTimeout is positive, then it specifies the timeout, in milliseconds (more or less), to use when handshaking with the target VM. The exact usage of the timeout are specific to the transport service. A transport service may, for example, use the handshake timeout as the inter-character timeout while waiting for the JDWP-Handshake message from the target VM. Alternatively, a transport service may, for example, use the handshakeTimeout as a timeout for the duration of the handshake exchange. If the transport service does not support a handshake timeout, or if handshakeTimeout is specified as zero then the handshake does not timeout if there isn't a response from the target VM.
Returns:
The Connection representing the bi-directional communication channel to the target VM.
Throws:
TransportTimeoutException - If a timeout occurs while establishing the connection.
IOException - If an I/O error occurs (including a timeout when handshaking).
IllegalArgumentException - If the address is invalid or the value of the attach timeout or handshake timeout is negative.
See Also:
TransportService.Capabilities.supportsAttachTimeout()

startListening

public abstract TransportService.ListenKey startListening(String address)
                                                   throws IOException
Listens on the specified address for inbound connections.

This method starts the transport service listening on the specified address so that it can subsequently accept an inbound connection. It does not wait until an inbound connection is established.

Parameters:
address - The address to start listening for connections, or null to listen on an address choosen by the transport service.
Returns:
a listen key to be used in subsequent calls to be accept or stopListening methods.
Throws:
IOException - If an I/O error occurs.
IllegalArgumentException - If the specific address is invalid

startListening

public abstract TransportService.ListenKey startListening()
                                                   throws IOException
Listens on an address choosen by the transport service.

This convenience method works as if by invoking startListening(null).

Returns:
a listen key to be used in subsequent calls to be accept or stopListening methods.
Throws:
IOException - If an I/O error occurs.

stopListening

public abstract void stopListening(TransportService.ListenKey listenKey)
                            throws IOException
Stop listening for inbound connections.

Invoking this method while another thread is blocked in accept, with the same listen key, waiting to accept a connection will cause that thread to throw an IOException. If the thread blocked in accept has already accepted a connection from a target VM and is in the process of handshaking with the target VM then invoking this method will not cause the thread to throw an exception.

Parameters:
listenKey - The listen key obtained from a previous call to startListening(String) or startListening().
Throws:
IllegalArgumentException - If the listen key is invalid
IOException - If an I/O error occurs.

accept

public abstract Connection accept(TransportService.ListenKey listenKey,
                                  long acceptTimeout,
                                  long handshakeTimeout)
                           throws IOException
Accept a connection from a target VM.

Waits (indefinitely or with timeout) to accept a connection from a target VM. Returns a connection representing the bi-directional communication channel to the target VM.

Accepting a connection from a target VM involves two steps. First, the transport service waits to accept the connection from the target VM. Once the connection is established a handshake is performed to ensure that the connection is indeed to a target VM. The handshake involves the exchange of a string JDWP-Handshake as specified in the Java Debug Wire Protocol specification.

Parameters:
listenKey - A listen key obtained from a previous call to startListening(String) or startListening().
acceptTimeout - if this transport service supports an accept timeout, and if acceptTimeout is positive then block for up to acceptTimeout milliseconds, more or less, while waiting for the target VM to connect. If the transport service does not support an accept timeout or if acceptTimeout is zero then block indefinitely for a target VM to connect.
handshakeTimeout - If this transport service supports a handshake timeout, and if handshakeTimeout is positive, then it specifies the timeout, in milliseconds (more or less), to use when handshaking with the target VM. The exact usage of the timeout is specific to the transport service. A transport service may, for example, use the handshake timeout as the inter-character timeout while waiting for the JDWP-Handshake message from the target VM. Alternatively, a transport service may, for example, use the timeout as a timeout for the duration of the handshake exchange. If the transport service does not support a handshake timeout, of if handshakeTimeout is specified as zero then the handshake does not timeout if there isn't a response from the target VM.
Returns:
The Connection representing the bi-directional communication channel to the target VM.
Throws:
TransportTimeoutException - If a timeout occurs while waiting for a target VM to connect.
IOException - If an I/O error occurs (including a timeout when handshaking).
IllegalArgumentException - If the value of the acceptTimeout argument, or handshakeTimeout is negative, or an invalid listen key is provided.
IllegalStateException - If stopListening has already been called with this listen key and the transport service is no longer listening for inbound connections.
See Also:
TransportService.Capabilities.supportsAcceptTimeout()
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TransportService.Capabilities

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect.spi
Class TransportService.Capabilities

java.lang.Object
    extended by  com.sun.jdi.connect.spi.TransportService.Capabilities
Enclosing class:
TransportService
public abstract static class TransportService.Capabilities
extends Object

The transport service capabilities.

Constructor Summary
TransportService.Capabilities()
Method Summary
abstract boolean | supportsAcceptTimeout() Tell whether or not this transport service supports a timeout while waiting for a target VM to connect.
abstract boolean | supportsAttachTimeout() Tell whether or not this transport service supports a timeout when attaching to a target VM.
abstract boolean | supportsHandshakeTimeout() Tells whether or not this transport service supports a timeout when handshaking with the target VM.
abstract boolean | supportsMultipleConnections() Tells whether or not this transport service can support multiple concurrent connections to a single address that it is listening on.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TransportService.Capabilities

public TransportService.Capabilities()
Method Detail

supportsMultipleConnections

public abstract boolean supportsMultipleConnections()
Tells whether or not this transport service can support multiple concurrent connections to a single address that it is listening on.

Returns:
true if, and only if, this transport service supports multiple connections.

supportsAttachTimeout

public abstract boolean supportsAttachTimeout()
Tell whether or not this transport service supports a timeout when attaching to a target VM.

Returns:
true if, and only if, this transport service supports attaching with a timeout.
See Also:
TransportService.attach(String,long,long)

supportsAcceptTimeout

public abstract boolean supportsAcceptTimeout()
Tell whether or not this transport service supports a timeout while waiting for a target VM to connect.

Returns:
true if, and only if, this transport service supports timeout while waiting for a target VM to connect.
See Also:
TransportService.accept(TransportService.ListenKey,long,long)

supportsHandshakeTimeout

public abstract boolean supportsHandshakeTimeout()
Tells whether or not this transport service supports a timeout when handshaking with the target VM.

Returns:
true if, and only if, this transport service supports a timeout while handshaking with the target VM.
See Also:
TransportService.attach(String,long,long), TransportService.accept(TransportService.ListenKey,long,long)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TransportService.ListenKey

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect.spi
Class TransportService.ListenKey

java.lang.Object
    extended by  com.sun.jdi.connect.spi.TransportService.ListenKey
Enclosing class:
TransportService
public abstract static class TransportService.ListenKey
extends Object

A listen key.

A TransportService may listen on multiple, yet different, addresses at the same time. To uniquely identify each listener a listen key is created each time that startListening is called. The listen key is used in calls to the accept method to accept inbound connections to that listener. A listen key is valid until it is used as an argument to stopListening to stop the transport service from listening on an address.

Constructor Summary
TransportService.ListenKey()
Method Summary
abstract  String address()
Returns a string representation of the listen key.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TransportService.ListenKey

public TransportService.ListenKey()
Method Detail

address

public abstract String address()
Returns a string representation of the listen key.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Transport

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect
Interface Transport

public interface Transport

A method of communication between a debugger and a target VM.

A Transport represents the transport mechanism used by a Connector to establish a connection with a target VM. It consists of a name which is obtained by invoking the name() method. Furthermore, a Transport encapsulates a TransportService which is the underlying service used to establish connections and exchange Java Debug Wire Protocol (JDWP) packets with a target VM.

Since:
1.3

Method Summary
 String name()
Returns a short identifier for the transport.

Method Detail

name

String name()
Returns a short identifier for the transport.

Returns:
the name of this transport.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TransportTimeoutException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect
Class TransportTimeoutException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.io.IOException
                extended by  com.sun.jdi.connect.TransportTimeoutException
All Implemented Interfaces:
Serializable
public class TransportTimeoutException
extends IOException

This exception may be thrown as a result of a timeout when attaching to a target VM, or waiting to accept a connection from a target VM.

When attaching to a target VM, using attach this exception may be thrown if the connector supports a timeout connector argument. Similiarly, when waiting to accept a connection from a target VM, using accept this exception may be thrown if the connector supports a timeout connector argument when accepting.

In addition, for developers creating TransportService implementations this exception is thrown when attach times out when establishing a connection to a target VM, or accept times out while waiting for a target VM to connect.

Since:
1.5
See Also:
AttachingConnector.attach(java.util.Map),
ListeningConnector.accept(java.util.Map),
TransportService.attach(java.lang.String, long, long),
TransportService.accept(com.sun.jdi.connect.spi.TransportService.ListenKey, long, long),
Serialized Form

Constructor Summary
TransportTimeoutException()
Constructs a TransportTimeoutException with no detail message.
TransportTimeoutException(String message)
Constructs a TransportTimeoutException with the specified detail message.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TransportTimeoutException

public TransportTimeoutException()
Constructs a TransportTimeoutException with no detail message.

TransportTimeoutException

public TransportTimeoutException(String message)
Constructs a TransportTimeoutException with the specified detail message.

Parameters:
message - the detail message pertaining to this exception.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VMStartException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.connect
Class VMStartException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  com.sun.jdi.connect.VMStartException
All Implemented Interfaces:
Serializable
public class VMStartException
extends Exception

A target VM was successfully launched, but terminated with an error before a connection could be established. This exception provides the Process object for the launched target to help in diagnosing the problem.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
VMStartException(Process process)
VMStartException(String message, Process process)
Method Summary
 Process process()
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

VMStartException

public VMStartException(Process process)

VMStartException

public VMStartException(String message,
                        Process process)
Method Detail

process

public Process process()
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


JDI Type Signatures
Type Signature | Java Type
Z | boolean
B | byte
C | char
S | short
I | int
J | long
F | float
D | double
L fully-qualified-class ; | fully-qualified-class
[ type | type[]
( arg-types ) ret-type | method type (including constructors)

For example, the Java method:

    long f (int n, String s, int[] arr);
has the following type signature:

    (ILjava/lang/String;[I)J


DoubleValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface DoubleValue

All Superinterfaces:
Comparable<DoubleValue>, Mirror, PrimitiveValue, Value
public interface DoubleValue
extends PrimitiveValue, Comparable<DoubleValue>

Provides access to a primitive double value in the target VM.

Since:
1.3

Method Summary
boolean | equals(Object obj) Compares the specified Object with this DoubleValue for equality.
int | hashCode() Returns the hash code value for this DoubleValue.
double | value() Returns this DoubleValue as a double.
Methods inherited from interface com.sun.jdi.PrimitiveValue
booleanValue, byteValue, charValue, doubleValue, floatValue, intValue, longValue, shortValue
Methods inherited from interface com.sun.jdi.Value
type
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface java.lang.Comparable
compareTo

Method Detail

value

double value()
Returns this DoubleValue as a double.

Returns:
the double mirrored by this object.

equals

boolean equals(Object obj)
Compares the specified Object with this DoubleValue for equality.

Overrides:
equals in class Object
Returns:
true if the Object is a DoubleValue and if applying "==" to the two mirrored primitives would evaluate to true; false otherwise.

hashCode

int hashCode()
Returns the hash code value for this DoubleValue.

Overrides:
hashCode in class Object
Returns:
the integer hash code
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


event

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package com.sun.jdi.event

This package defines JDI events and event processing.

See:
Description

Interface Summary
AccessWatchpointEvent | Notification of a field access in the target VM.
BreakpointEvent | Notification of a breakpoint in the target VM.
ClassPrepareEvent | Notification of a class prepare in the target VM.
ClassUnloadEvent | Notification of a class unload in the target VM.
Event | An occurrence in a target VM that is of interest to a debugger.
EventIterator | EventIterators are unmodifiable.
EventQueue | Manager of incoming debugger events for a target VM.
EventSet | Several Event objects may be created at a given time by the target VirtualMachine.
ExceptionEvent | Notification of an exception in the target VM.
LocatableEvent | Abstract superinterface of events which have both location and thread.
MethodEntryEvent | Notification of a method invocation in the target VM.
MethodExitEvent | Notification of a method return in the target VM.
ModificationWatchpointEvent | Notification of a field modification in the target VM.
MonitorContendedEnteredEvent | Notification that a thread in the target VM is entering a monitor after waiting for it to be released by another thread.
MonitorContendedEnterEvent | Notification that a thread in the target VM is attempting to enter a monitor that is already acquired by another thread.
MonitorWaitedEvent | Notification that a thread in the target VM has finished waiting on an monitor object.
MonitorWaitEvent | Notification that a thread in the target VM is about to wait on a monitor object.
StepEvent | Notification of step completion in the target VM.
ThreadDeathEvent | Notification of a completed thread in the target VM.
ThreadStartEvent | Notification of a new running thread in the target VM.
VMDeathEvent | Notification of target VM termination.
VMDisconnectEvent | Notification of disconnection from target VM.
VMStartEvent | Notification of initialization of a target VM.
WatchpointEvent | Notification of a field triggered event encountered by a thread in the target VM.

Package com.sun.jdi.event Description

This package defines JDI events and event processing. An Event is always a member of an EventSet, which is retrieved from the EventQueue. Examples of Events include "breakpoints events", "thread creation events" and "virtual machine death event". With the exception of termination events, all events received must be requested with an "EventRequest". The com.sun.jdi.request package defines event requests and event request management.

Methods may be added to the interfaces in the JDI packages in future releases. Existing packages may be renamed if the JDI becomes a standard extension.

Overview Package Class Use Tree Index Help
Java Debug Interface


AccessWatchpointEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface AccessWatchpointEvent

All Superinterfaces:
Event, Locatable, LocatableEvent, Mirror, WatchpointEvent
public interface AccessWatchpointEvent
extends WatchpointEvent

Notification of a field access in the target VM. Field modifications are not considered field accesses.

Since:
1.3
See Also:
EventQueue, VirtualMachine

Method Summary
Methods inherited from interface com.sun.jdi.event.WatchpointEvent
field, object, valueCurrent
Methods inherited from interface com.sun.jdi.event.LocatableEvent
thread
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface com.sun.jdi.Locatable
location

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


BreakpointEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface BreakpointEvent

All Superinterfaces:
Event, Locatable, LocatableEvent, Mirror
public interface BreakpointEvent
extends LocatableEvent

Notification of a breakpoint in the target VM. The breakpoint event is generated before the code at its location is executed. When a location is reached which satisfies a currently enabled breakpoint request, an event set containing an instance of this class will be added to the VM's event queue.

Since:
1.3
See Also:
EventQueue, VirtualMachine, BreakpointRequest

Method Summary
Methods inherited from interface com.sun.jdi.event.LocatableEvent
thread
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface com.sun.jdi.Locatable
location

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


com.sun.jdi.event Class Hierarchy

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Hierarchy For Package com.sun.jdi.event

Package Hierarchies:
All Packages

Interface Hierarchy

  • java.lang.Iterable<T>
    • java.util.Collection<E>
      • java.util.Set<E>
        • com.sun.jdi.event.EventSet (also extends com.sun.jdi.Mirror)
  • java.util.Iterator<E>
    • com.sun.jdi.event.EventIterator
  • com.sun.jdi.Locatable
    • com.sun.jdi.event.LocatableEvent (also extends com.sun.jdi.event.Event)
      • com.sun.jdi.event.BreakpointEvent
      • com.sun.jdi.event.ExceptionEvent
      • com.sun.jdi.event.MethodEntryEvent
      • com.sun.jdi.event.MethodExitEvent
      • com.sun.jdi.event.MonitorContendedEnteredEvent
      • com.sun.jdi.event.MonitorContendedEnterEvent
      • com.sun.jdi.event.MonitorWaitedEvent
      • com.sun.jdi.event.MonitorWaitEvent
      • com.sun.jdi.event.StepEvent
      • com.sun.jdi.event.WatchpointEvent
        • com.sun.jdi.event.AccessWatchpointEvent
        • com.sun.jdi.event.ModificationWatchpointEvent
  • com.sun.jdi.Mirror
    • com.sun.jdi.event.Event
      • com.sun.jdi.event.ClassPrepareEvent
      • com.sun.jdi.event.ClassUnloadEvent
      • com.sun.jdi.event.LocatableEvent (also extends com.sun.jdi.Locatable)
        • com.sun.jdi.event.BreakpointEvent
        • com.sun.jdi.event.ExceptionEvent
        • com.sun.jdi.event.MethodEntryEvent
        • com.sun.jdi.event.MethodExitEvent
        • com.sun.jdi.event.MonitorContendedEnteredEvent
        • com.sun.jdi.event.MonitorContendedEnterEvent
        • com.sun.jdi.event.MonitorWaitedEvent
        • com.sun.jdi.event.MonitorWaitEvent
        • com.sun.jdi.event.StepEvent
        • com.sun.jdi.event.WatchpointEvent
          • com.sun.jdi.event.AccessWatchpointEvent
          • com.sun.jdi.event.ModificationWatchpointEvent
      • com.sun.jdi.event.ThreadDeathEvent
      • com.sun.jdi.event.ThreadStartEvent
      • com.sun.jdi.event.VMDeathEvent
      • com.sun.jdi.event.VMDisconnectEvent
      • com.sun.jdi.event.VMStartEvent
    • com.sun.jdi.event.EventQueue
    • com.sun.jdi.event.EventSet (also extends java.util.Set<E>)
Overview Package Class Use Tree Index Help
Java Debug Interface


StepEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface StepEvent

All Superinterfaces:
Event, Locatable, LocatableEvent, Mirror
public interface StepEvent
extends LocatableEvent

Notification of step completion in the target VM. The step event is generated immediately before the code at its location is executed; thus, if the step is entering a new method (as might occur with StepRequest.STEP_INTO) the location of the event is the first instruction of the method. When a step leaves a method, the location of the event will be the first instruction after the call in the calling method; note that this location may not be at a line boundary, even if StepRequest.STEP_LINE was used.

Since:
1.3
See Also:
StepRequest, EventQueue

Method Summary
Methods inherited from interface com.sun.jdi.event.LocatableEvent
thread
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface com.sun.jdi.Locatable
location

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Package com.sun.jdi.event

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Package
com.sun.jdi.event

Packages that use com.sun.jdi.event
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.event | This package defines JDI events and event processing.

Classes in com.sun.jdi.event used by com.sun.jdi
EventQueue
Manager of incoming debugger events for a target VM.

Classes in com.sun.jdi.event used by com.sun.jdi.event
Event
An occurrence in a target VM that is of interest to a debugger.
EventIterator
EventIterators are unmodifiable.
EventSet
Several Event objects may be created at a given time by the target VirtualMachine.
LocatableEvent
Abstract superinterface of events which have both location and thread.
WatchpointEvent
Notification of a field triggered event encountered by a thread in the target VM.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


VMDeathEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface VMDeathEvent

All Superinterfaces:
Event, Mirror
public interface VMDeathEvent
extends Event

Notification of target VM termination. This event occurs if the target VM terminates before the VM disconnects (VMDisconnectEvent). Thus, this event will NOT occur if external forces terminate the connection (e.g. a crash) or if the connection is intentionally terminated with VirtualMachine.dispose()

On VM termination, a single unsolicited VMDeathEvent will always be sent with a suspend policy of SUSPEND_NONE. Additional VMDeathEvents will be sent in the same event set if they are requested with a VMDeathRequest.

The VM is still intact and can be queried at the point this event was initiated but immediately thereafter it is not considered intact and cannot be queried. Note: If the enclosing EventSet has a suspend policy other than SUSPEND_ALL the initiating point may be long past.

All VMDeathEvents will be in a single EventSet, no other events will be in the event set. A resume must occur to continue execution after any event set which performs suspensions - in this case to allow proper shutdown.

Since:
1.3
See Also:
VMDisconnectEvent, EventRequestManager.createVMDeathRequest(), VMDeathRequest, EventQueue, VirtualMachine

Method Summary
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VMDisconnectEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface VMDisconnectEvent

All Superinterfaces:
Event, Mirror
public interface VMDisconnectEvent
extends Event

Notification of disconnection from target VM. May be caused by normal termination of a VM, VM termination by uncaught exception or other error, debugger action ( VirtualMachine.dispose() or VirtualMachine.exit(int)) or by external events (for example, target process termination by the operating system, transport termination, etc).

If the target VM terminates before the disconnection, this event will be preceded by a VMDeathEvent.

This event is always sent. There is no corresponding EventRequest. The enclosing singleton EventSet always has a suspend policy of EventRequest.SUSPEND_NONE.

Since:
1.3
See Also:
VMDeathEvent, EventQueue, VirtualMachine

Method Summary
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Interface com.sun.jdi.event.AccessWatchpointEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.AccessWatchpointEvent

No usage of com.sun.jdi.event.AccessWatchpointEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.BreakpointEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.BreakpointEvent

No usage of com.sun.jdi.event.BreakpointEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.ClassPrepareEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.ClassPrepareEvent

No usage of com.sun.jdi.event.ClassPrepareEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.ClassUnloadEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.ClassUnloadEvent

No usage of com.sun.jdi.event.ClassUnloadEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.Event

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.Event

Packages that use Event
com.sun.jdi.event This package defines JDI events and event processing.

Uses of Event in com.sun.jdi.event

Subinterfaces of Event in com.sun.jdi.event
interface | AccessWatchpointEvent Notification of a field access in the target VM.
interface | BreakpointEvent Notification of a breakpoint in the target VM.
interface | ClassPrepareEvent Notification of a class prepare in the target VM.
interface | ClassUnloadEvent Notification of a class unload in the target VM.
interface | ExceptionEvent Notification of an exception in the target VM.
interface | LocatableEvent Abstract superinterface of events which have both location and thread.
interface | MethodEntryEvent Notification of a method invocation in the target VM.
interface | MethodExitEvent Notification of a method return in the target VM.
interface | ModificationWatchpointEvent Notification of a field modification in the target VM.
interface | MonitorContendedEnteredEvent Notification that a thread in the target VM is entering a monitor after waiting for it to be released by another thread.
interface | MonitorContendedEnterEvent Notification that a thread in the target VM is attempting to enter a monitor that is already acquired by another thread.
interface | MonitorWaitedEvent Notification that a thread in the target VM has finished waiting on an monitor object.
interface | MonitorWaitEvent Notification that a thread in the target VM is about to wait on a monitor object.
interface | StepEvent Notification of step completion in the target VM.
interface | ThreadDeathEvent Notification of a completed thread in the target VM.
interface | ThreadStartEvent Notification of a new running thread in the target VM.
interface | VMDeathEvent Notification of target VM termination.
interface | VMDisconnectEvent Notification of disconnection from target VM.
interface | VMStartEvent Notification of initialization of a target VM.
interface | WatchpointEvent Notification of a field triggered event encountered by a thread in the target VM.

Methods in com.sun.jdi.event that return Event
 Event EventIterator.nextEvent()

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.EventIterator

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.EventIterator

Packages that use EventIterator
com.sun.jdi.event This package defines JDI events and event processing.

Uses of EventIterator in com.sun.jdi.event

Methods in com.sun.jdi.event that return EventIterator
 EventIterator EventSet.eventIterator()
Return an iterator specific to Event objects.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.EventQueue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.EventQueue

Packages that use EventQueue
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of EventQueue in com.sun.jdi

Methods in com.sun.jdi that return EventQueue
 EventQueue VirtualMachine.eventQueue()
Returns the event queue for this virtual machine.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.EventSet

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.EventSet

Packages that use EventSet
com.sun.jdi.event This package defines JDI events and event processing.

Uses of EventSet in com.sun.jdi.event

Methods in com.sun.jdi.event that return EventSet
EventSet | EventQueue.remove() Waits forever for the next available event.
EventSet | EventQueue.remove(long timeout) Waits a specified time for the next available event.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.ExceptionEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.ExceptionEvent

No usage of com.sun.jdi.event.ExceptionEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.LocatableEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.LocatableEvent

Packages that use LocatableEvent
com.sun.jdi.event This package defines JDI events and event processing.

Uses of LocatableEvent in com.sun.jdi.event

Subinterfaces of LocatableEvent in com.sun.jdi.event
interface | AccessWatchpointEvent Notification of a field access in the target VM.
interface | BreakpointEvent Notification of a breakpoint in the target VM.
interface | ExceptionEvent Notification of an exception in the target VM.
interface | MethodEntryEvent Notification of a method invocation in the target VM.
interface | MethodExitEvent Notification of a method return in the target VM.
interface | ModificationWatchpointEvent Notification of a field modification in the target VM.
interface | MonitorContendedEnteredEvent Notification that a thread in the target VM is entering a monitor after waiting for it to be released by another thread.
interface | MonitorContendedEnterEvent Notification that a thread in the target VM is attempting to enter a monitor that is already acquired by another thread.
interface | MonitorWaitedEvent Notification that a thread in the target VM has finished waiting on an monitor object.
interface | MonitorWaitEvent Notification that a thread in the target VM is about to wait on a monitor object.
interface | StepEvent Notification of step completion in the target VM.
interface | WatchpointEvent Notification of a field triggered event encountered by a thread in the target VM.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.MethodEntryEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.MethodEntryEvent

No usage of com.sun.jdi.event.MethodEntryEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.MethodExitEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.MethodExitEvent

No usage of com.sun.jdi.event.MethodExitEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.ModificationWatchpointEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.ModificationWatchpointEvent

No usage of com.sun.jdi.event.ModificationWatchpointEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.MonitorContendedEnteredEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.MonitorContendedEnteredEvent

No usage of com.sun.jdi.event.MonitorContendedEnteredEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.MonitorContendedEnterEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.MonitorContendedEnterEvent

No usage of com.sun.jdi.event.MonitorContendedEnterEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.MonitorWaitedEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.MonitorWaitedEvent

No usage of com.sun.jdi.event.MonitorWaitedEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.MonitorWaitEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.MonitorWaitEvent

No usage of com.sun.jdi.event.MonitorWaitEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.StepEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.StepEvent

No usage of com.sun.jdi.event.StepEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.ThreadDeathEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.ThreadDeathEvent

No usage of com.sun.jdi.event.ThreadDeathEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.ThreadStartEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.ThreadStartEvent

No usage of com.sun.jdi.event.ThreadStartEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.VMDeathEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.VMDeathEvent

No usage of com.sun.jdi.event.VMDeathEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.VMDisconnectEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.VMDisconnectEvent

No usage of com.sun.jdi.event.VMDisconnectEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.VMStartEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.VMStartEvent

No usage of com.sun.jdi.event.VMStartEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.event.WatchpointEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.event.WatchpointEvent

Packages that use WatchpointEvent
com.sun.jdi.event This package defines JDI events and event processing.

Uses of WatchpointEvent in com.sun.jdi.event

Subinterfaces of WatchpointEvent in com.sun.jdi.event
interface | AccessWatchpointEvent Notification of a field access in the target VM.
interface | ModificationWatchpointEvent Notification of a field modification in the target VM.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


ClassPrepareEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface ClassPrepareEvent

All Superinterfaces:
Event, Mirror
public interface ClassPrepareEvent
extends Event

Notification of a class prepare in the target VM. See the JVM specification for a definition of class preparation. Class prepare events are not generated for primtiive classes (for example, java.lang.Integer.TYPE).

Since:
1.3
See Also:
EventQueue, VirtualMachine

Method Summary
ReferenceType | referenceType() Returns the reference type for which this event was generated.
ThreadReference | thread() Returns the thread in which this event has occurred.
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

thread

ThreadReference thread()
Returns the thread in which this event has occurred.

In rare cases, this event may occur in a debugger system thread within the target VM. Debugger threads take precautions to prevent these events, but they cannot be avoided under some conditions, especially for some subclasses of Error. If the event was generated by a debugger system thread, the value returned by this method is null, and if the requested suspend policy for the event was EventRequest.SUSPEND_EVENT_THREAD, all threads will be suspended instead, and the EventSet.suspendPolicy() will reflect this change.

Note that the discussion above does not apply to system threads created by the target VM during its normal (non-debug) operation.

Returns:
a ThreadReference which mirrors the event's thread in the target VM, or null in the rare cases described above.

referenceType

ReferenceType referenceType()
Returns the reference type for which this event was generated.

Returns:
a ReferenceType which mirrors the class, interface, or array which has been linked.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ClassUnloadEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface ClassUnloadEvent

All Superinterfaces:
Event, Mirror
public interface ClassUnloadEvent
extends Event

Notification of a class unload in the target VM.

There are severe constraints on the debugger back-end during garbage collection, so unload information is greatly limited.

Since:
1.3
See Also:
EventQueue, VirtualMachine

Method Summary
String | className() Returns the name of the class that has been unloaded.
String | classSignature() Returns the JNI-style signature of the class that has been unloaded.
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

className

String className()
Returns the name of the class that has been unloaded.

classSignature

String classSignature()
Returns the JNI-style signature of the class that has been unloaded.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Event

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface Event

All Superinterfaces:
Mirror
All Known Subinterfaces:
AccessWatchpointEvent, BreakpointEvent, ClassPrepareEvent, ClassUnloadEvent, ExceptionEvent, LocatableEvent, MethodEntryEvent, MethodExitEvent, ModificationWatchpointEvent, MonitorContendedEnteredEvent, MonitorContendedEnterEvent, MonitorWaitedEvent, MonitorWaitEvent, StepEvent, ThreadDeathEvent, ThreadStartEvent, VMDeathEvent, VMDisconnectEvent, VMStartEvent, WatchpointEvent
public interface Event
extends Mirror

An occurrence in a target VM that is of interest to a debugger. Event is the common superinterface for all events (examples include BreakpointEvent, ExceptionEvent, ClassPrepareEvent). When an event occurs, an instance of Event as a component of an EventSet is enqueued in the VirtualMachine's EventQueue.

Since:
1.3
See Also:
EventSet, EventQueue

Method Summary
 EventRequest request()
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

request

EventRequest request()
Returns:
The EventRequest that requested this event. Some events (eg. VMDeathEvent) may not have a cooresponding request and thus will return null.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EventIterator

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface EventIterator

All Superinterfaces:
Iterator<Event>
public interface EventIterator
extends Iterator<Event>

EventIterators are unmodifiable.

Since:
1.3
See Also:
Event, EventSet, Set.iterator()

Method Summary
 Event nextEvent()
Methods inherited from interface java.util.Iterator
hasNext, next, remove

Method Detail

nextEvent

Event nextEvent()
Returns:
The next Event in an EventSet.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EventQueue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface EventQueue

All Superinterfaces:
Mirror
public interface EventQueue
extends Mirror

Manager of incoming debugger events for a target VM. Events are always grouped in EventSets. EventSets generated by the debugger back end can be read here. There is one instance of EventQueue assigned to a particular VirtualMachine.

Some events cause the suspension of the target VM - event requests (com.sun.jdi.request) with a suspend policy of SUSPEND_ALL or SUSPEND_EVENT_THREAD and sometimes VMStartEvent. If these suspensions are not resumed the target VM will hang. Thus, it is always good policy to remove() every EventSet from the event queue until an EventSet containing a VMDisconnectEvent is read. Unless resume is being handled in another way, each EventSet should invoke EventSet.resume().

Since:
1.3
See Also:
EventSet, VirtualMachine

Method Summary
EventSet | remove() Waits forever for the next available event.
EventSet | remove(long timeout) Waits a specified time for the next available event.
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

remove

EventSet remove()
                throws InterruptedException
Waits forever for the next available event.

Returns:
the next EventSet.
Throws:
InterruptedException - if any thread has interrupted this thread.
VMDisconnectedException - if the connection to the target VM is no longer available. Note this will always be preceded by a VMDisconnectEvent.

remove

EventSet remove(long timeout)
                throws InterruptedException
Waits a specified time for the next available event.

Parameters:
timeout - Time in milliseconds to wait for the next event
Returns:
the next EventSet, or null if there is a timeout.
Throws:
InterruptedException - if any thread has interrupted this thread.
VMDisconnectedException - if the connection to the target VM is no longer available. Note this will always be preceded by a VMDisconnectEvent.
IllegalArgumentException - if the timeout argument contains an illegal value.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EventSet

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface EventSet

All Superinterfaces:
Collection<Event>, Iterable<Event>, Mirror, Set<Event>
public interface EventSet
extends Mirror, Set<Event>

Several Event objects may be created at a given time by the target VirtualMachine. For example, there may be more than one BreakpointRequest for a given Location or you might single step to the same location as a BreakpointRequest. These Event objects are delivered together as an EventSet. For uniformity, an EventSet is always used to deliver Event objects. EventSets are delivered by the EventQueue. EventSets are unmodifiable.

Associated with the issuance of an event set, suspensions may have occurred in the target VM. These suspensions correspond with the suspend policy. To assure matching resumes occur, it is recommended, where possible, to complete the processing of an event set with EventSet.resume().

The events that are grouped in an EventSet are restricted in the following ways:

  • Always singleton sets:
    • VMStartEvent
    • VMDisconnectEvent
  • Only with other VMDeathEvents:
    • VMDeathEvent
  • Only with other ThreadStartEvents for the same thread:
    • ThreadStartEvent
  • Only with other ThreadDeathEvents for the same thread:
    • ThreadDeathEvent
  • Only with other ClassPrepareEvents for the same class:
    • ClassPrepareEvent
  • Only with other ClassUnloadEvents for the same class:
    • ClassUnloadEvent
  • Only with other AccessWatchpointEvents for the same field access:
    • AccessWatchpointEvent
  • Only with other ModificationWatchpointEvents for the same field modification:
    • ModificationWatchpointEvent
  • Only with other ExceptionEvents for the same exception occurrance:
    • ExceptionEvent
  • Only with other MethodExitEvents for the same method exit:
    • MethodExitEvent
  • Only with other Monitor contended enter events for the same monitor object:
    • Monitor Contended Enter Event
  • Only with other Monitor contended entered events for the same monitor object:
    • Monitor Contended Entered Event
  • Only with other Monitor wait events for the same monitor object:
    • Monitor Wait Event
  • Only with other Monitor waited events for the same monitor object:
    • Monitor Waited Event
  • Only with other members of this group, at the same location and in the same thread:
    • BreakpointEvent
    • StepEvent
    • MethodEntryEvent

Since:
1.3
See Also:
Event, EventQueue

Method Summary
EventIterator | eventIterator() Return an iterator specific to Event objects.
void | resume() Resumes threads suspended by this event set.
int | suspendPolicy() Returns the policy used to suspend threads in the target VM for this event set.
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface java.util.Set
add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray

Method Detail

suspendPolicy

int suspendPolicy()
Returns the policy used to suspend threads in the target VM for this event set. This policy is selected from the suspend policies for each event's request; the target VM chooses the policy which suspends the most threads. The target VM suspends threads according to that policy and that policy is returned here. See EventRequest for the possible policy values.

In rare cases, the suspend policy may differ from the requested value if a ClassPrepareEvent has occurred in a debugger system thread. See ClassPrepareEvent.thread() for details.

Returns:
the suspendPolicy which is either SUSPEND_ALL, SUSPEND_EVENT_THREAD or SUSPEND_NONE.

eventIterator

EventIterator eventIterator()
Return an iterator specific to Event objects.

resume

void resume()
Resumes threads suspended by this event set. If the suspendPolicy() is EventRequest.SUSPEND_ALL, a call to this method is equivalent to VirtualMachine.resume(). If the suspend policy is EventRequest.SUSPEND_EVENT_THREAD, a call to this method is equivalent to ThreadReference.resume() for the event thread. Otherwise, a call to this method is a no-op.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ExceptionEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface ExceptionEvent

All Superinterfaces:
Event, Locatable, LocatableEvent, Mirror
public interface ExceptionEvent
extends LocatableEvent

Notification of an exception in the target VM. When an exception is thrown which satisfies a currently enabled exception request, an event set containing an instance of this class will be added to the VM's event queue. If the exception is thrown from a non-native method, the exception event is generated at the location where the exception is thrown. If the exception is thrown from a native method, the exception event is generated at the first non-native location reached after the exception is thrown.

Since:
1.3

Method Summary
Location | catchLocation() Gets the location where the exception will be caught.
ObjectReference | exception() Gets the thrown exception object.
Methods inherited from interface com.sun.jdi.event.LocatableEvent
thread
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface com.sun.jdi.Locatable
location

Method Detail

exception

ObjectReference exception()
Gets the thrown exception object. The exception object is an instance of Throwable or a subclass in the target VM.

Returns:
an ObjectReference which mirrors the thrown object in the target VM.

catchLocation

Location catchLocation()
Gets the location where the exception will be caught. An exception is considered to be caught if, at the point of the throw, the current location is dynamically enclosed in a try statement that handles the exception. (See the JVM specification for details). If there is such a try statement, the catch location is the first code index of the appropriate catch clause.

If there are native methods in the call stack at the time of the exception, there are important restrictions to note about the returned catch location. In such cases, it is not possible to predict whether an exception will be handled by some native method on the call stack. Thus, it is possible that exceptions considered uncaught here will, in fact, be handled by a native method and not cause termination of the target VM. Furthermore, it cannot be assumed that the catch location returned here will ever be reached by the throwing thread. If there is a native frame between the current location and the catch location, the exception might be handled and cleared in that native method instead.

Note that the compiler can generate try-catch blocks in some cases where they are not explicit in the source code; for example, the code generated for synchronized and finally blocks can contain implicit try-catch blocks. If such an implicitly generated try-catch is present on the call stack at the time of the throw, the exception will be considered caught even though it appears to be uncaught from examination of the source code.

Returns:
the Location where the exception will be caught or null if the exception is uncaught.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LocatableEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface LocatableEvent

All Superinterfaces:
Event, Locatable, Mirror
All Known Subinterfaces:
AccessWatchpointEvent, BreakpointEvent, ExceptionEvent, MethodEntryEvent, MethodExitEvent, ModificationWatchpointEvent, MonitorContendedEnteredEvent, MonitorContendedEnterEvent, MonitorWaitedEvent, MonitorWaitEvent, StepEvent, WatchpointEvent
public interface LocatableEvent
extends Event, Locatable

Abstract superinterface of events which have both location and thread.

Since:
1.3

Method Summary
 ThreadReference thread()
Returns the thread in which this event has occurred.
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface com.sun.jdi.Locatable
location

Method Detail

thread

ThreadReference thread()
Returns the thread in which this event has occurred.

Returns:
a ThreadReference which mirrors the event's thread in the target VM.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MethodEntryEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface MethodEntryEvent

All Superinterfaces:
Event, Locatable, LocatableEvent, Mirror
public interface MethodEntryEvent
extends LocatableEvent

Notification of a method invocation in the target VM. This event occurs after entry into the invoked method and before any code has executed. Method entry events are generated for both native and non-native methods.

In some VMs method entry events can occur for a particular thread before its ThreadStartEvent occurs if methods are called as part of the thread's initialization.

Since:
1.3
See Also:
EventQueue

Method Summary
 Method method()
Returns the method that was entered.
Methods inherited from interface com.sun.jdi.event.LocatableEvent
thread
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface com.sun.jdi.Locatable
location

Method Detail

method

Method method()
Returns the method that was entered.

Returns:
a Method which mirrors the method that was entered.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MethodExitEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface MethodExitEvent

All Superinterfaces:
Event, Locatable, LocatableEvent, Mirror
public interface MethodExitEvent
extends LocatableEvent

Notification of a method return in the target VM. This event is generated after all code in the method has executed, but the location of this event is the last executed location in the method. Method exit events are generated for both native and non-native methods. Method exit events are not generated if the method terminates with a thrown exception.

Since:
1.3
See Also:
EventQueue

Method Summary
Method | method() Returns the method that was exited.
Value | returnValue() Returns the value that the method will return.
Methods inherited from interface com.sun.jdi.event.LocatableEvent
thread
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface com.sun.jdi.Locatable
location

Method Detail

method

Method method()
Returns the method that was exited.

Returns:
a Method which mirrors the method that was exited.
Throws:
ObjectCollectedException - may be thrown if class has been garbage collected.

returnValue

Value returnValue()
Returns the value that the method will return. Not all target virtual machines support this operation. Use canGetMethodReturnValues() to determine if this operation is supported.

Returns:
a Value which mirrors the value to be returned.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation - see canGetMethodReturnValues()
Since:
1.6
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ModificationWatchpointEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface ModificationWatchpointEvent

All Superinterfaces:
Event, Locatable, LocatableEvent, Mirror, WatchpointEvent
public interface ModificationWatchpointEvent
extends WatchpointEvent

Notification of a field modification in the target VM.

Since:
1.3
See Also:
EventQueue, VirtualMachine, ModificationWatchpointRequest

Method Summary
 Value valueToBe()
Value that will be assigned to the field when the instruction completes.
Methods inherited from interface com.sun.jdi.event.WatchpointEvent
field, object, valueCurrent
Methods inherited from interface com.sun.jdi.event.LocatableEvent
thread
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface com.sun.jdi.Locatable
location

Method Detail

valueToBe

Value valueToBe()
Value that will be assigned to the field when the instruction completes.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MonitorContendedEnteredEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface MonitorContendedEnteredEvent

All Superinterfaces:
Event, Locatable, LocatableEvent, Mirror
public interface MonitorContendedEnteredEvent
extends LocatableEvent

Notification that a thread in the target VM is entering a monitor after waiting for it to be released by another thread.

Since:
1.6
See Also:
EventQueue, MonitorContendedEnterEvent

Method Summary
ObjectReference | monitor() Returns the monitor that was entered.
ThreadReference | thread() Returns the thread in which this event has occurred.
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface com.sun.jdi.Locatable
location

Method Detail

thread

ThreadReference thread()
Returns the thread in which this event has occurred.

Specified by:
thread in interface LocatableEvent
Returns:
a ThreadReference which mirrors the event's thread in the target VM.

monitor

ObjectReference monitor()
Returns the monitor that was entered.

Returns:
an ObjectReference for the monitor.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MonitorContendedEnterEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface MonitorContendedEnterEvent

All Superinterfaces:
Event, Locatable, LocatableEvent, Mirror
public interface MonitorContendedEnterEvent
extends LocatableEvent

Notification that a thread in the target VM is attempting to enter a monitor that is already acquired by another thread.

Since:
1.6
See Also:
EventQueue, MonitorContendedEnteredEvent

Method Summary
ObjectReference | monitor() Returns the method that was entered.
ThreadReference | thread() Returns the thread in which this event has occurred.
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface com.sun.jdi.Locatable
location

Method Detail

thread

ThreadReference thread()
Returns the thread in which this event has occurred.

Specified by:
thread in interface LocatableEvent
Returns:
a ThreadReference which mirrors the event's thread in the target VM.

monitor

ObjectReference monitor()
Returns the method that was entered.

Returns:
an ObjectReference for the monitor.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MonitorWaitedEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface MonitorWaitedEvent

All Superinterfaces:
Event, Locatable, LocatableEvent, Mirror
public interface MonitorWaitedEvent
extends LocatableEvent

Notification that a thread in the target VM has finished waiting on an monitor object.

Since:
1.6
See Also:
EventQueue, MonitorWaitEvent

Method Summary
ObjectReference | monitor() Returns the monitor object this thread waited on.
ThreadReference | thread() Returns the thread in which this event has occurred.
boolean | timedout() Returns whether the wait has timed out or been interrupted.
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface com.sun.jdi.Locatable
location

Method Detail

thread

ThreadReference thread()
Returns the thread in which this event has occurred.

Specified by:
thread in interface LocatableEvent
Returns:
a ThreadReference which mirrors the event's thread in the target VM.

monitor

ObjectReference monitor()
Returns the monitor object this thread waited on.

Returns:
an ObjectReference for the monitor.

timedout

boolean timedout()
Returns whether the wait has timed out or been interrupted.

Returns:
true if the wait is timed out.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MonitorWaitEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface MonitorWaitEvent

All Superinterfaces:
Event, Locatable, LocatableEvent, Mirror
public interface MonitorWaitEvent
extends LocatableEvent

Notification that a thread in the target VM is about to wait on a monitor object.

Since:
1.6
See Also:
EventQueue, MonitorWaitedEvent

Method Summary
ObjectReference | monitor() Returns the monitor object that the thread about to wait.
ThreadReference | thread() Returns the thread in which monitor wait event has occurred.
long | timeout() Returns the number of millisecond the thread will wait.
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface com.sun.jdi.Locatable
location

Method Detail

thread

ThreadReference thread()
Returns the thread in which monitor wait event has occurred.

Specified by:
thread in interface LocatableEvent
Returns:
a ThreadReference which mirrors the event's thread in the target VM.

monitor

ObjectReference monitor()
Returns the monitor object that the thread about to wait.

Returns:
an ObjectReference for the monitor.

timeout

long timeout()
Returns the number of millisecond the thread will wait.

Returns:
a jlong containing monitor wait time in milliseconds.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ThreadDeathEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface ThreadDeathEvent

All Superinterfaces:
Event, Mirror
public interface ThreadDeathEvent
extends Event

Notification of a completed thread in the target VM. The notification is generated by the dying thread before it terminates. Because of this timing, it is possible for VirtualMachine.allThreads() to return this thread after this event is received.

Note that this event gives no information about the lifetime of the thread object. It may or may not be collected soon depending on what references exist in the target VM.

Since:
1.3
See Also:
EventQueue, VirtualMachine, ThreadReference

Method Summary
 ThreadReference thread()
Returns the thread which is terminating.
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

thread

ThreadReference thread()
Returns the thread which is terminating.

Returns:
a ThreadReference which mirrors the event's thread in the target VM.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ThreadStartEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface ThreadStartEvent

All Superinterfaces:
Event, Mirror
public interface ThreadStartEvent
extends Event

Notification of a new running thread in the target VM. The new thread can be the result of a call to Thread.start() or the result of attaching a new thread to the VM though JNI. The notification is generated by the new thread some time before its execution starts. Because of this timing, it is possible to receive other events for the thread before this event is received. (Notably, MethodEntryEvents and MethodExitEvents might occur during thread initialization.) It is also possible for VirtualMachine.allThreads() to return a new started thread before this event is received.

Note that this event gives no information about the creation of the thread object which may have happened much earlier, depending on the VM being debugged.

Since:
1.3
See Also:
EventQueue, VirtualMachine, ThreadReference

Method Summary
 ThreadReference thread()
Returns the thread which has started.
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

thread

ThreadReference thread()
Returns the thread which has started.

Returns:
a ThreadReference which mirrors the event's thread in the target VM.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VMStartEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface VMStartEvent

All Superinterfaces:
Event, Mirror
public interface VMStartEvent
extends Event

Notification of initialization of a target VM. This event is received before the main thread is started and before any application code has been executed. Before this event occurs a significant amount of system code has executed and a number of system classes have been loaded. This event is always generated by the target VM, even if not explicitly requested.

Since:
1.3
See Also:
VMDeathEvent, EventQueue, VirtualMachine

Method Summary
 ThreadReference thread()
Returns the initial thread of the VM which has started.
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

thread

ThreadReference thread()
Returns the initial thread of the VM which has started.

Returns:
a ThreadReference which mirrors the event's thread in the target VM.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WatchpointEvent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.event
Interface WatchpointEvent

All Superinterfaces:
Event, Locatable, LocatableEvent, Mirror
All Known Subinterfaces:
AccessWatchpointEvent, ModificationWatchpointEvent
public interface WatchpointEvent
extends LocatableEvent

Notification of a field triggered event encountered by a thread in the target VM.

Since:
1.3
See Also:
EventQueue, VirtualMachine

Method Summary
Field | field() Returns the field that is about to be accessed/modified.
ObjectReference | object() Returns the object whose field is about to be accessed/modified.
Value | valueCurrent() Current value of the field.
Methods inherited from interface com.sun.jdi.event.LocatableEvent
thread
Methods inherited from interface com.sun.jdi.event.Event
request
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface com.sun.jdi.Locatable
location

Method Detail

field

Field field()
Returns the field that is about to be accessed/modified.

Returns:
a Field which mirrors the field in the target VM.
Throws:
ObjectCollectedException - may be thrown if class has been garbage collected.

object

ObjectReference object()
Returns the object whose field is about to be accessed/modified. Return null is the access is to a static field.

Returns:
a ObjectReference which mirrors the event's object in the target VM.

valueCurrent

Value valueCurrent()
Current value of the field.

Throws:
ObjectCollectedException - if object or class have been garbage collected.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


Field

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface Field

All Superinterfaces:
Accessible, Comparable<Field>, Mirror, TypeComponent
public interface Field
extends TypeComponent, Comparable<Field>

A class or instance variable in the target VM. See TypeComponent for general information about Field and Method mirrors.

Since:
1.3
See Also:
ObjectReference, ReferenceType

Method Summary
boolean | equals(Object obj) Compares the specified Object with this field for equality.
int | hashCode() Returns the hash code value for this Field.
boolean | isEnumConstant() Determine if this is a field that represents an enum constant.
boolean | isTransient() Determine if this is a transient field.
boolean | isVolatile() Determine if this is a volatile field.
Type | type() Returns the type of this field.
String | typeName() Returns a text representation of the type of this field.
Methods inherited from interface com.sun.jdi.TypeComponent
declaringType, genericSignature, isFinal, isStatic, isSynthetic, name, signature
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface com.sun.jdi.Accessible
isPackagePrivate, isPrivate, isProtected, isPublic, modifiers
Methods inherited from interface java.lang.Comparable
compareTo

Method Detail

typeName

String typeName()
Returns a text representation of the type of this field. Where the type is the type specified in the declaration of this field.

This type name is always available even if the type has not yet been created or loaded.

Returns:
a String representing the type of this field.

type

Type type()
          throws ClassNotLoadedException
Returns the type of this field. Where the type is the type specified in the declaration of this field.

For example, if a target class defines:

    short s;
    Date d;
    byte[] ba;
And the JDI client defines these Field objects:
    Field sField = targetClass.fieldByName("s");
    Field dField = targetClass.fieldByName("d");
    Field baField = targetClass.fieldByName("ba");
to mirror the corresponding fields, then sField.type() is a ShortType, dField.type() is the ReferenceType for java.util.Date and ((ArrayType)(baField.type())).componentType() is a ByteType.

Note: if the type of this field is a reference type (class, interface, or array) and it has not been created or loaded by the declaring type's class loader - that is, declaringType() .classLoader(), then ClassNotLoadedException will be thrown. Also, a reference type may have been loaded but not yet prepared, in which case the type will be returned but attempts to perform some operations on the returned type (e.g. fields()) will throw a ClassNotPreparedException. Use ReferenceType.isPrepared() to determine if a reference type is prepared.

Returns:
the Type of this field.
Throws:
ClassNotLoadedException - if the type has not yet been loaded or created through the appropriate class loader.
See Also:
Type

isTransient

boolean isTransient()
Determine if this is a transient field.

Returns:
true if this field is transient; false otherwise.

isVolatile

boolean isVolatile()
Determine if this is a volatile field.

Returns:
true if this field is volatile; false otherwise.

isEnumConstant

boolean isEnumConstant()
Determine if this is a field that represents an enum constant.

Returns:
true if this field represents an enum constant; false otherwise.

equals

boolean equals(Object obj)
Compares the specified Object with this field for equality.

Overrides:
equals in class Object
Returns:
true if the Object is a Field and if both mirror the same field (declared in the same class or interface, in the same VM).

hashCode

int hashCode()
Returns the hash code value for this Field.

Overrides:
hashCode in class Object
Returns:
the integer hash code
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


FloatValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface FloatValue

All Superinterfaces:
Comparable<FloatValue>, Mirror, PrimitiveValue, Value
public interface FloatValue
extends PrimitiveValue, Comparable<FloatValue>

Provides access to a primitive float value in the target VM.

Since:
1.3

Method Summary
boolean | equals(Object obj) Compares the specified Object with this FloatValue for equality.
int | hashCode() Returns the hash code value for this FloatValue.
float | value() Returns this FloatValue as a float.
Methods inherited from interface com.sun.jdi.PrimitiveValue
booleanValue, byteValue, charValue, doubleValue, floatValue, intValue, longValue, shortValue
Methods inherited from interface com.sun.jdi.Value
type
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface java.lang.Comparable
compareTo

Method Detail

value

float value()
Returns this FloatValue as a float.

Returns:
the float mirrored by this object.

equals

boolean equals(Object obj)
Compares the specified Object with this FloatValue for equality.

Overrides:
equals in class Object
Returns:
true if the Object is a FloatValue and if applying "==" to the two mirrored primitives would evaluate to true; false otherwise.

hashCode

int hashCode()
Returns the hash code value for this FloatValue.

Overrides:
hashCode in class Object
Returns:
the integer hash code
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IncompatibleThreadStateException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class IncompatibleThreadStateException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  com.sun.jdi.IncompatibleThreadStateException
All Implemented Interfaces:
Serializable
public class IncompatibleThreadStateException
extends Exception

Thrown to indicate that the requested operation cannot be completed while the specified thread is in its current state.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
IncompatibleThreadStateException()
IncompatibleThreadStateException(String s)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

IncompatibleThreadStateException

public IncompatibleThreadStateException()

IncompatibleThreadStateException

public IncompatibleThreadStateException(String s)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InconsistentDebugInfoException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class InconsistentDebugInfoException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  com.sun.jdi.InconsistentDebugInfoException
All Implemented Interfaces:
Serializable
public class InconsistentDebugInfoException
extends RuntimeException

Thrown to indicate that there is an inconistency in the debug information provided by the target VM. For example, this exception is thrown if there is a type mismatch between a retrieved value's runtime type and its declared type as reported by the target VM.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
InconsistentDebugInfoException()
InconsistentDebugInfoException(String s)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InconsistentDebugInfoException

public InconsistentDebugInfoException()

InconsistentDebugInfoException

public InconsistentDebugInfoException(String s)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


IntegerValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface IntegerValue

All Superinterfaces:
Comparable<IntegerValue>, Mirror, PrimitiveValue, Value
public interface IntegerValue
extends PrimitiveValue, Comparable<IntegerValue>

Provides access to a primitive int value in the target VM.

Since:
1.3

Method Summary
boolean | equals(Object obj) Compares the specified Object with this IntegerValue for equality.
int | hashCode() Returns the hash code value for this IntegerValue.
int | value() Returns this IntegerValue as an int.
Methods inherited from interface com.sun.jdi.PrimitiveValue
booleanValue, byteValue, charValue, doubleValue, floatValue, intValue, longValue, shortValue
Methods inherited from interface com.sun.jdi.Value
type
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface java.lang.Comparable
compareTo

Method Detail

value

int value()
Returns this IntegerValue as an int.

Returns:
the int mirrored by this object.

equals

boolean equals(Object obj)
Compares the specified Object with this IntegerValue for equality.

Overrides:
equals in class Object
Returns:
true if the Object is an IntegerValue and if applying "==" to the two mirrored primitives would evaluate to true; false otherwise.

hashCode

int hashCode()
Returns the hash code value for this IntegerValue.

Overrides:
hashCode in class Object
Returns:
the integer hash code
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InterfaceType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface InterfaceType

All Superinterfaces:
Accessible, Comparable<ReferenceType>, Mirror, ReferenceType, Type
public interface InterfaceType
extends ReferenceType

A mirror of an interface in the target VM. An InterfaceType is a refinement of ReferenceType that applies to true interfaces in the JLS sense of the definition (not a class, not an array type). An interface type will never be returned by ObjectReference.referenceType(), but it may be in the list of implemented interfaces for a ClassType that is returned by that method.

Since:
1.3
See Also:
ObjectReference

Method Summary
List<ClassType> | implementors() Gets the currently prepared classes which directly implement this interface.
List<InterfaceType> | subinterfaces() Gets the currently prepared interfaces which directly extend this interface.
List<InterfaceType> | superinterfaces() Gets the interfaces directly extended by this interface.
Methods inherited from interface com.sun.jdi.ReferenceType
allFields, allLineLocations, allLineLocations, allMethods, availableStrata, classLoader, classObject, constantPool, constantPoolCount, defaultStratum, equals, failedToInitialize, fieldByName, fields, genericSignature, getValue, getValues, hashCode, instances, isAbstract, isFinal, isInitialized, isPrepared, isStatic, isVerified, locationsOfLine, locationsOfLine, majorVersion, methods, methodsByName, methodsByName, minorVersion, name, nestedTypes, sourceDebugExtension, sourceName, sourceNames, sourcePaths, visibleFields, visibleMethods
Methods inherited from interface com.sun.jdi.Type
signature
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface java.lang.Comparable
compareTo
Methods inherited from interface com.sun.jdi.Accessible
isPackagePrivate, isPrivate, isProtected, isPublic, modifiers

Method Detail

superinterfaces

List<InterfaceType> superinterfaces()
Gets the interfaces directly extended by this interface. The returned list contains only those interfaces this interface has declared to be extended.

Returns:
a List of InterfaceType objects each mirroring an interface extended by this interface. If none exist, returns a zero length List.
Throws:
ClassNotPreparedException - if this class not yet been prepared.

subinterfaces

List<InterfaceType> subinterfaces()
Gets the currently prepared interfaces which directly extend this interface. The returned list contains only those interfaces that declared this interface in their "extends" clause.

Returns:
a List of InterfaceType objects each mirroring an interface extending this interface. If none exist, returns a zero length List.

implementors

List<ClassType> implementors()
Gets the currently prepared classes which directly implement this interface. The returned list contains only those classes that declared this interface in their "implements" clause.

Returns:
a List of ClassType objects each mirroring a class implementing this interface. If none exist, returns a zero length List.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InternalException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class InternalException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  com.sun.jdi.InternalException
All Implemented Interfaces:
Serializable
public class InternalException
extends RuntimeException

Thrown to indicate that an unexpected internal error has occurred.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
InternalException()
InternalException(int errorCode)
InternalException(String s)
InternalException(String s, int errorCode)
Method Summary
 int errorCode()
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InternalException

public InternalException()

InternalException

public InternalException(String s)

InternalException

public InternalException(int errorCode)

InternalException

public InternalException(String s,
                         int errorCode)
Method Detail

errorCode

public int errorCode()
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidCodeIndexException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class InvalidCodeIndexException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  com.sun.jdi.InvalidCodeIndexException
All Implemented Interfaces:
Serializable
Deprecated. This exception is no longer thrown

@Deprecated
public class InvalidCodeIndexException
extends RuntimeException

Thrown to indicate that the requested operation cannot be completed because the specified code index is not valid.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
InvalidCodeIndexException()
Deprecated.
InvalidCodeIndexException(String s)
Deprecated.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidCodeIndexException

public InvalidCodeIndexException()
Deprecated.

InvalidCodeIndexException

public InvalidCodeIndexException(String s)
Deprecated.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidLineNumberException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class InvalidLineNumberException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  com.sun.jdi.InvalidLineNumberException
All Implemented Interfaces:
Serializable
Deprecated. This exception is no longer thrown

@Deprecated
public class InvalidLineNumberException
extends RuntimeException

Thrown to indicate that the requested operation cannot be completed because the specified line number is not valid.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
InvalidLineNumberException()
Deprecated.
InvalidLineNumberException(String s)
Deprecated.
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidLineNumberException

public InvalidLineNumberException()
Deprecated.

InvalidLineNumberException

public InvalidLineNumberException(String s)
Deprecated.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidStackFrameException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class InvalidStackFrameException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  com.sun.jdi.InvalidStackFrameException
All Implemented Interfaces:
Serializable
public class InvalidStackFrameException
extends RuntimeException

Thrown to indicate that the requested operation cannot be completed because the specified stack frame is no longer valid.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
InvalidStackFrameException()
InvalidStackFrameException(String s)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidStackFrameException

public InvalidStackFrameException()

InvalidStackFrameException

public InvalidStackFrameException(String s)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidTypeException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class InvalidTypeException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  com.sun.jdi.InvalidTypeException
All Implemented Interfaces:
Serializable
public class InvalidTypeException
extends Exception

Thrown to indicate a type mismatch in setting the value of a field or variable, or in specifying the return value of a method.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
InvalidTypeException()
InvalidTypeException(String s)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidTypeException

public InvalidTypeException()

InvalidTypeException

public InvalidTypeException(String s)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvocationException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class InvocationException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  com.sun.jdi.InvocationException
All Implemented Interfaces:
Serializable
public class InvocationException
extends Exception

Thrown to indicate an exception occurred in an invoked method within the target VM.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
InvocationException(ObjectReference exception)
Method Summary
 ObjectReference exception()
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvocationException

public InvocationException(ObjectReference exception)
Method Detail

exception

public ObjectReference exception()
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


JDIPermission

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class JDIPermission

java.lang.Object
    extended by  java.security.Permission
        extended by  java.security.BasicPermission
            extended by  com.sun.jdi.JDIPermission
All Implemented Interfaces:
Serializable, Guard
public final class JDIPermission
extends BasicPermission

The JDIPermission class represents access rights to the VirtualMachineManager. This is the permission which the SecurityManager will check when code that is running with a SecurityManager requests access to the VirtualMachineManager, as defined in the Java Debug Interface (JDI) for the Java platform.

A JDIPermission object contains a name (also referred to as a "target name") but no actions list; you either have the named permission or you don't.

The following table provides a summary description of what the permission allows, and discusses the risks of granting code the permission.

Permission Target Name | What the Permission Allows | Risks of Allowing this Permission
virtualMachineManager | Ability to inspect and modify the JDI objects in the VirtualMachineManager | This allows an attacker to control the VirtualMachineManager and cause the system to misbehave.

Programmers do not normally create JDIPermission objects directly. Instead they are created by the security policy code based on reading the security policy file.

Since:
1.5
See Also:
Bootstrap, BasicPermission, Permission, Permissions, PermissionCollection, SecurityManager, Serialized Form

Constructor Summary
JDIPermission(String name)
The JDIPermission class represents access rights to the VirtualMachineManager
JDIPermission(String name, String actions)
Constructs a new JDIPermission object.
Method Summary
Methods inherited from class java.security.BasicPermission
equals, getActions, hashCode, implies, newPermissionCollection
Methods inherited from class java.security.Permission
checkGuard, getName, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

JDIPermission

public JDIPermission(String name)
The JDIPermission class represents access rights to the VirtualMachineManager

Parameters:
name - Permission name. Must be "virtualMachineManager".
Throws:
IllegalArgumentException - if the name argument is invalid.

JDIPermission

public JDIPermission(String name,
                     String actions)
              throws IllegalArgumentException
Constructs a new JDIPermission object.

Parameters:
name - Permission name. Must be "virtualMachineManager".
actions - Must be either null or the empty string.
Throws:
IllegalArgumentException - if arguments are invalid.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LocalVariable

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface LocalVariable

All Superinterfaces:
Comparable<LocalVariable>, Mirror
public interface LocalVariable
extends Mirror, Comparable<LocalVariable>

A local variable in the target VM. Each variable declared within a Method has its own LocalVariable object. Variables of the same name declared in different scopes have different LocalVariable objects. LocalVariables can be used alone to retrieve static information about their declaration, or can be used in conjunction with a StackFrame to set and get values.

Since:
1.3
See Also:
StackFrame, Method

Method Summary
boolean | equals(Object obj) Compares the specified Object with this LocalVariable for equality.
String | genericSignature() Gets the generic signature for this variable if there is one.
int | hashCode() Returns the hash code value for this LocalVariable.
boolean | isArgument() Determines if this variable is an argument to its method.
boolean | isVisible(StackFrame frame) Determines whether this variable can be accessed from the given StackFrame.
String | name() Gets the name of the local variable.
String | signature() Gets the JNI signature of the local variable.
Type | type() Returns the type of this variable.
String | typeName() Returns a text representation of the type of this variable.
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface java.lang.Comparable
compareTo

Method Detail

name

String name()
Gets the name of the local variable.

Returns:
a string containing the name.

typeName

String typeName()
Returns a text representation of the type of this variable. Where the type is the type specified in the declaration of this local variable.

This type name is always available even if the type has not yet been created or loaded.

Returns:
a String representing the type of this local variable.

type

Type type()
          throws ClassNotLoadedException
Returns the type of this variable. Where the type is the type specified in the declaration of this local variable.

Note: if the type of this variable is a reference type (class, interface, or array) and it has not been created or loaded by the class loader of the enclosing class, then ClassNotLoadedException will be thrown. Also, a reference type may have been loaded but not yet prepared, in which case the type will be returned but attempts to perform some operations on the returned type (e.g. fields()) will throw a ClassNotPreparedException. Use ReferenceType.isPrepared() to determine if a reference type is prepared.

Returns:
the Type of this local variable.
Throws:
ClassNotLoadedException - if the type has not yet been loaded through the appropriate class loader.
See Also:
Type, Field.type() - for usage examples

signature

String signature()
Gets the JNI signature of the local variable.

Returns:
a string containing the signature.
See Also:
Type Signatures

genericSignature

String genericSignature()
Gets the generic signature for this variable if there is one. Generic signatures are described in the "JavaTM Virtual Machine Specification, 3rd Edition.

Returns:
a string containing the generic signature, or null if there is no generic signature.
Since:
1.5

isVisible

boolean isVisible(StackFrame frame)
Determines whether this variable can be accessed from the given StackFrame. See StackFrame.visibleVariables() for a complete description variable visibility in this interface.

Parameters:
frame - the StackFrame querying visibility
Returns:
true if this variable is visible; false otherwise.
Throws:
IllegalArgumentException - if the stack frame's method does not match this variable's method.

isArgument

boolean isArgument()
Determines if this variable is an argument to its method.

Returns:
true if this variable is an argument; false otherwise.

equals

boolean equals(Object obj)
Compares the specified Object with this LocalVariable for equality.

Overrides:
equals in class Object
Returns:
true if the Object is a LocalVariable, if both LocalVariables are contained in the same method (as determined by Method.equals(java.lang.Object)), and if both LocalVariables mirror the same declaration within that method

hashCode

int hashCode()
Returns the hash code value for this LocalVariable.

Overrides:
hashCode in class Object
Returns:
the integer hash code
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Locatable

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface Locatable

All Known Subinterfaces:
AccessWatchpointEvent, BreakpointEvent, BreakpointRequest, ExceptionEvent, LocatableEvent, Method, MethodEntryEvent, MethodExitEvent, ModificationWatchpointEvent, MonitorContendedEnteredEvent, MonitorContendedEnterEvent, MonitorWaitedEvent, MonitorWaitEvent, StackFrame, StepEvent, WatchpointEvent
public interface Locatable

A mirror that has a Location.

Since:
1.3

Method Summary
 Location location()
Returns the Location of this mirror, if there is executable code associated with it.

Method Detail

location

Location location()
Returns the Location of this mirror, if there is executable code associated with it. Note that both JavaTM programming language methods and native methods have executable code. Returns null for abstract methods, since abstract methods have no executable code.

Returns:
the Location of this mirror, or null if there is no executable code associated with it.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Location

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface Location

All Superinterfaces:
Comparable<Location>, Mirror
public interface Location
extends Mirror, Comparable<Location>

A point within the executing code of the target VM. Locations are used to identify the current position of a suspended thread (analogous to an instruction pointer or program counter register in native programs). They are also used to identify the position at which to set a breakpoint.

The availability of a line number for a location will depend on the level of debugging information available from the target VM.

Several mirror interfaces have locations. Each such mirror extends a Locatable interface.

Strata

The source information for a Location is dependent on the stratum which is used. A stratum is a source code level within a sequence of translations. For example, say the baz program is written in the programming language "Foo" then translated to the language "Bar" and finally translated into the Java programming language. The Java programming language stratum is named "Java", let's say the other strata are named "Foo" and "Bar". A given location (as viewed by the sourceName() and lineNumber() methods) might be at line 14 of "baz.foo" in the "Foo" stratum, line 23 of "baz.bar" in the "Bar" stratum and line 71 of the "Java" stratum. Note that while the Java programming language may have only one source file for a reference type, this restriction does not apply to other strata - thus each Location should be consulted to determine its source path. Queries which do not specify a stratum (sourceName(), sourcePath() and lineNumber()) use the VM's default stratum (VirtualMachine.getDefaultStratum()). If the specified stratum (whether explicitly specified by a method parameter or implicitly as the VM's default) is null or is not available in the declaring type, the declaring type's default stratum is used (declaringType().defaultStratum()). Note that in the normal case, of code that originates as Java programming language source, there will be only one stratum ("Java") and it will be returned as the default. To determine the available strata use ReferenceType.availableStrata().

Since:
1.3
See Also:
EventRequestManager, StackFrame, BreakpointEvent, ExceptionEvent, Locatable

Method Summary
long | codeIndex() Gets the code position within this location's method.
ReferenceType | declaringType() Gets the type to which this Location belongs.
boolean | equals(Object obj) Compares the specified Object with this Location for equality.
int | hashCode() Returns the hash code value for this Location.
int | lineNumber() Gets the line number of this Location.
int | lineNumber(String stratum) The line number of this Location.
Method | method() Gets the method containing this Location.
String | sourceName() Gets an identifing name for the source corresponding to this location.
String | sourceName(String stratum) Gets an identifing name for the source corresponding to this location.
String | sourcePath() Gets the path to the source corresponding to this location.
String | sourcePath(String stratum) Gets the path to the source corresponding to this location.
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface java.lang.Comparable
compareTo

Method Detail

declaringType

ReferenceType declaringType()
Gets the type to which this Location belongs. Normally the declaring type is a ClassType, but executable locations also may exist within the static initializer of an InterfaceType.

Returns:
the ReferenceType containing this Location.

method

Method method()
Gets the method containing this Location.

Returns:
the location's Method.

codeIndex

long codeIndex()
Gets the code position within this location's method.

Returns:
the long representing the position within the method or -1 if location is within a native method.

sourceName

String sourceName()
                  throws AbsentInformationException
Gets an identifing name for the source corresponding to this location.

This method is equivalent to sourceName(vm.getDefaultStratum()) - see sourceName(String) for more information.

Returns:
a string specifying the source
Throws:
AbsentInformationException - if the source name is not known

sourceName

String sourceName(String stratum)
                  throws AbsentInformationException
Gets an identifing name for the source corresponding to this location. Interpretation of this string is the responsibility of the source repository mechanism.

Returned name is for the specified stratum (see the class comment for a description of strata).

The returned string is the unqualified name of the source file for this Location. For example, java.lang.Thread would return "Thread.java".

Parameters:
stratum - The stratum to retrieve information from or null for the declaring type's default stratum.
Returns:
a string specifying the source
Throws:
AbsentInformationException - if the source name is not known
Since:
1.4

sourcePath

String sourcePath()
                  throws AbsentInformationException
Gets the path to the source corresponding to this location.

This method is equivalent to sourcePath(vm.getDefaultStratum()) - see sourcePath(String) for more information.

Returns:
a string specifying the source
Throws:
AbsentInformationException - if the source name is not known

sourcePath

String sourcePath(String stratum)
                  throws AbsentInformationException
Gets the path to the source corresponding to this location. Interpretation of this string is the responsibility of the source repository mechanism.

Returned path is for the specified stratum (see the class comment for a description of strata).

In the reference implementation, for strata which do not explicitly specify source path (the Java programming language stratum never does), the returned string is the package name of declaringType() converted to a platform dependent path followed by the unqualified name of the source file for this Location (sourceName(stratum)). For example, on a Windows platform, java.lang.Thread would return "java\lang\Thread.java".

Parameters:
stratum - The stratum to retrieve information from or null for the declaring type's default stratum.
Returns:
a string specifying the source
Throws:
AbsentInformationException - if the source name is not known
Since:
1.4

lineNumber

int lineNumber()
Gets the line number of this Location.

This method is equivalent to lineNumber(vm.getDefaultStratum()) - see lineNumber(String) for more information.

Returns:
an int specifying the line in the source, returns -1 if the information is not available; specifically, always returns -1 for native methods.

lineNumber

int lineNumber(String stratum)
The line number of this Location. The line number is relative to the source specified by sourceName(stratum).

Returned line number is for the specified stratum (see the class comment for a description of strata).

Parameters:
stratum - The stratum to retrieve information from or null for the declaring type's default stratum.
Returns:
an int specifying the line in the source, returns -1 if the information is not available; specifically, always returns -1 for native methods.
Since:
1.4

equals

boolean equals(Object obj)
Compares the specified Object with this Location for equality.

Overrides:
equals in class Object
Returns:
true if the Object is a Location and if it refers to the same point in the same VM as this Location.

hashCode

int hashCode()
Returns the hash code value for this Location.

Overrides:
hashCode in class Object
Returns:
the integer hash code
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


LongValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface LongValue

All Superinterfaces:
Comparable<LongValue>, Mirror, PrimitiveValue, Value
public interface LongValue
extends PrimitiveValue, Comparable<LongValue>

Provides access to a primitive long value in the target VM.

Since:
1.3

Method Summary
boolean | equals(Object obj) Compares the specified Object with this LongValue for equality.
int | hashCode() Returns the hash code value for this LongValue.
long | value() Returns this LongValue as a long.
Methods inherited from interface com.sun.jdi.PrimitiveValue
booleanValue, byteValue, charValue, doubleValue, floatValue, intValue, longValue, shortValue
Methods inherited from interface com.sun.jdi.Value
type
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface java.lang.Comparable
compareTo

Method Detail

value

long value()
Returns this LongValue as a long.

Returns:
the long mirrored by this object.

equals

boolean equals(Object obj)
Compares the specified Object with this LongValue for equality.

Overrides:
equals in class Object
Returns:
true if the Object is a LongValue and if applying "==" to the two mirrored primitives would evaluate to true; false otherwise.

hashCode

int hashCode()
Returns the hash code value for this LongValue.

Overrides:
hashCode in class Object
Returns:
the integer hash code
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Method

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface Method

All Superinterfaces:
Accessible, Comparable<Method>, Locatable, Mirror, TypeComponent
public interface Method
extends TypeComponent, Locatable, Comparable<Method>

A static or instance method in the target VM. See TypeComponent for general information about Field and Method mirrors.

Since:
1.3
See Also:
ObjectReference, ReferenceType

Method Summary
List<Location> | allLineLocations() Returns a list containing a Location object for each executable source line in this method.
List<Location> | allLineLocations(String stratum, String sourceName) Returns a list containing a Location object for each executable source line in this method.
List<LocalVariable> | arguments() Returns a list containing each LocalVariable that is declared as an argument of this method.
List<String> | argumentTypeNames() Returns a list containing a text representation of the type of each formal parameter of this method.
List<Type> | argumentTypes() Returns a list containing the type of each formal parameter of this method.
byte[] | bytecodes() Returns an array containing the bytecodes for this method.
boolean | equals(Object obj) Compares the specified Object with this method for equality.
int | hashCode() Returns the hash code value for this Method.
boolean | isAbstract() Determine if this method is abstract.
boolean | isBridge() Determine if this method is a bridge method.
boolean | isConstructor() Determine if this method is a constructor.
boolean | isNative() Determine if this method is native.
boolean | isObsolete() Determine if this method is obsolete.
boolean | isStaticInitializer() Determine if this method is a static initializer.
boolean | isSynchronized() Determine if this method is synchronized.
boolean | isVarArgs() Determine if this method accepts a variable number of arguments.
Location | location() Returns the Location of this method, if there is executable code associated with it.
Location | locationOfCodeIndex(long codeIndex) Returns a Location for the given code index.
List<Location> | locationsOfLine(int lineNumber) Returns a List containing all Location objects that map to the given line number.
List<Location> | locationsOfLine(String stratum, String sourceName, int lineNumber) Returns a List containing all Location objects that map to the given line number and source name.
Type | returnType() Returns the return type, as specified in the declaration of this method.
String | returnTypeName() Returns a text representation of the return type, as specified in the declaration of this method.
List<LocalVariable> | variables() Returns a list containing each LocalVariable declared in this method.
List<LocalVariable> | variablesByName(String name) Returns a list containing each LocalVariable of a given name in this method.
Methods inherited from interface com.sun.jdi.TypeComponent
declaringType, genericSignature, isFinal, isStatic, isSynthetic, name, signature
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface com.sun.jdi.Accessible
isPackagePrivate, isPrivate, isProtected, isPublic, modifiers
Methods inherited from interface java.lang.Comparable
compareTo

Method Detail

returnTypeName

String returnTypeName()
Returns a text representation of the return type, as specified in the declaration of this method.

This type name is always available even if the type has not yet been created or loaded.

Returns:
a String containing the return type name.

returnType

Type returnType()
                throws ClassNotLoadedException
Returns the return type, as specified in the declaration of this method.

Note: if the return type of this method is a reference type (class, interface, or array) and it has not been created or loaded by the declaring type's class loader - that is, declaringType() .classLoader(), then ClassNotLoadedException will be thrown. Also, a reference type may have been loaded but not yet prepared, in which case the type will be returned but attempts to perform some operations on the returned type (e.g. fields()) will throw a ClassNotPreparedException. Use ReferenceType.isPrepared() to determine if a reference type is prepared.

Returns:
the return Type of this method.
Throws:
ClassNotLoadedException - if the type has not yet been created or loaded through the appropriate class loader.
See Also:
Type, Field.type() - for usage examples

argumentTypeNames

List<String> argumentTypeNames()
Returns a list containing a text representation of the type of each formal parameter of this method.

This list is always available even if the types have not yet been created or loaded.

Returns:
a List of String, one List element for each parameter of this method. Each element represents the type of a formal parameter as specified at compile-time. If the formal parameter was declared with an ellipsis, then it is represented as an array of the type before the ellipsis.

argumentTypes

List<Type> argumentTypes()
                         throws ClassNotLoadedException
Returns a list containing the type of each formal parameter of this method.

Note: if there is any parameter whose type is a reference type (class, interface, or array) and it has not been created or loaded by the declaring type's class loader - that is, declaringType() .classLoader(), then ClassNotLoadedException will be thrown. Also, a reference type may have been loaded but not yet prepared, in which case the list will be returned but attempts to perform some operations on the type (e.g. fields()) will throw a ClassNotPreparedException. Use ReferenceType.isPrepared() to determine if a reference type is prepared.

Returns:
return a List of Type, one List element for each parameter of this method. Each element represents the type of a formal parameter as specified at compile-time. If the formal parameter was declared with an ellipsis, then it is represented as an array of the type before the ellipsis.
Throws:
ClassNotLoadedException - if the type has not yet been loaded through the appropriate class loader.
See Also:
Type

isAbstract

boolean isAbstract()
Determine if this method is abstract.

Returns:
true if the method is declared abstract; false otherwise.

isSynchronized

boolean isSynchronized()
Determine if this method is synchronized.

Returns:
true if the method is declared synchronized; false otherwise.

isNative

boolean isNative()
Determine if this method is native.

Returns:
true if the method is declared native; false otherwise.

isVarArgs

boolean isVarArgs()
Determine if this method accepts a variable number of arguments.

Returns:
true if the method accepts a variable number of arguments, false otherwise.
Since:
1.5

isBridge

boolean isBridge()
Determine if this method is a bridge method. Bridge methods are defined in the "JavaTM Language Specification, 3rd Edition.

Returns:
true if the method is a bridge method, false otherwise.
Since:
1.5

isConstructor

boolean isConstructor()
Determine if this method is a constructor.

Returns:
true if the method is a constructor; false otherwise.

isStaticInitializer

boolean isStaticInitializer()
Determine if this method is a static initializer.

Returns:
true if the method is a static initializer; false otherwise.

isObsolete

boolean isObsolete()
Determine if this method is obsolete.

Returns:
true if this method has been made obsolete by a VirtualMachine.redefineClasses(java.util.Map) operation.
Since:
1.4

allLineLocations

List<Location> allLineLocations()
                                throws AbsentInformationException
Returns a list containing a Location object for each executable source line in this method.

This method is equivalent to allLineLocations(vm.getDefaultStratum(),null) - see allLineLocations(String,String) for more information.

Returns:
a List of all source line Location objects.
Throws:
AbsentInformationException - if there is no line number information for this (non-native, non-abstract) method.

allLineLocations

List<Location> allLineLocations(String stratum,
                                String sourceName)
                                throws AbsentInformationException
Returns a list containing a Location object for each executable source line in this method.

Each location maps a source line to a range of code indices. The beginning of the range can be determined through Location.codeIndex(). The returned list is ordered by code index (from low to high).

The returned list may contain multiple locations for a particular line number, if the compiler and/or VM has mapped that line to two or more disjoint code index ranges.

If the method is native or abstract, an empty list is returned.

Returned list is for the specified stratum (see Location for a description of strata).

Parameters:
stratum - The stratum to retrieve information from or null for the ReferenceType.defaultStratum()
sourceName - Return locations only within this source file or null to return locations.
Returns:
a List of all source line Location objects.
Throws:
AbsentInformationException - if there is no line number information for this (non-native, non-abstract) method. Or if sourceName is non-null and source name information is not present.
Since:
1.4

locationsOfLine

List<Location> locationsOfLine(int lineNumber)
                               throws AbsentInformationException
Returns a List containing all Location objects that map to the given line number.

This method is equivalent to locationsOfLine(vm.getDefaultStratum(), null, lineNumber) - see locationsOfLine(java.lang.String,java.lang.String,int) for more information.

Parameters:
lineNumber - the line number
Returns:
a List of Location objects that map to the given line number.
Throws:
AbsentInformationException - if there is no line number information for this method.

locationsOfLine

List<Location> locationsOfLine(String stratum,
                               String sourceName,
                               int lineNumber)
                               throws AbsentInformationException
Returns a List containing all Location objects that map to the given line number and source name.

Returns a list containing each Location that maps to the given line. The returned list will contain a location for each disjoint range of code indices that have been assigned to the given line by the compiler and/or VM. Each returned location corresponds to the beginning of this range. An empty list will be returned if there is no executable code at the specified line number; specifically, native and abstract methods will always return an empty list.

Returned list is for the specified stratum (see Location for a description of strata).

Parameters:
stratum - the stratum to use for comparing line number and source name, or null to use the default stratum
sourceName - the source name containing the line number, or null to match all source names
lineNumber - the line number
Returns:
a List of Location objects that map to the given line number.
Throws:
AbsentInformationException - if there is no line number information for this method. Or if sourceName is non-null and source name information is not present.
Since:
1.4

locationOfCodeIndex

Location locationOfCodeIndex(long codeIndex)
Returns a Location for the given code index.

Returns:
the Location corresponding to the given code index or null if the specified code index is not a valid code index for this method (native and abstract methods will always return null).

variables

List<LocalVariable> variables()
                              throws AbsentInformationException
Returns a list containing each LocalVariable declared in this method. The list includes any variable declared in any scope within the method. It may contain multiple variables of the same name declared within disjoint scopes. Arguments are considered local variables and will be present in the returned list. If local variable information is not available, values of actual arguments to method invocations can be obtained by using the method StackFrame.getArgumentValues()

Returns:
the list of LocalVariable objects which mirror local variables declared in this method in the target VM. If there are no local variables, a zero-length list is returned.
Throws:
AbsentInformationException - if there is no variable information for this method. Generally, local variable information is not available for native or abstract methods (that is, their argument name information is not available), thus they will throw this exception.

variablesByName

List<LocalVariable> variablesByName(String name)
                                    throws AbsentInformationException
Returns a list containing each LocalVariable of a given name in this method. Multiple variables can be returned if the same variable name is used in disjoint scopes within the method.

Returns:
the list of LocalVariable objects of the given name. If there are no matching local variables, a zero-length list is returned.
Throws:
AbsentInformationException - if there is no variable information for this method. Generally, local variable information is not available for native or abstract methods (that is, their argument name information is not available), thus they will throw this exception.

arguments

List<LocalVariable> arguments()
                              throws AbsentInformationException
Returns a list containing each LocalVariable that is declared as an argument of this method. If local variable information is not available, values of actual arguments to method invocations can be obtained by using the method StackFrame.getArgumentValues()

Returns:
the list of LocalVariable arguments. If there are no arguments, a zero-length list is returned.
Throws:
AbsentInformationException - if there is no variable information for this method. Generally, local variable information is not available for native or abstract methods (that is, their argument name information is not available), thus they will throw this exception.

bytecodes

byte[] bytecodes()
Returns an array containing the bytecodes for this method.

Not all target virtual machines support this operation. Use VirtualMachine.canGetBytecodes() to determine if the operation is supported.

Returns:
the array of bytecodes; abstract and native methods will return a zero-length array.
Throws:
UnsupportedOperationException - if the target virtual machine does not support the retrieval of bytecodes.

location

Location location()
Returns the Location of this method, if there is executable code associated with it.

Specified by:
location in interface Locatable
Returns:
the Location of this mirror, or null if this is an abstract method; native methods will return a Location object whose codeIndex is -1.

equals

boolean equals(Object obj)
Compares the specified Object with this method for equality.

Overrides:
equals in class Object
Returns:
true if the Object is a method and if both mirror the same method (declared in the same class or interface, in the same VM).

hashCode

int hashCode()
Returns the hash code value for this Method.

Overrides:
hashCode in class Object
Returns:
the integer hash code
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Mirror

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface Mirror

All Known Subinterfaces:
AccessWatchpointEvent, AccessWatchpointRequest, ArrayReference, ArrayType, BooleanType, BooleanValue, BreakpointEvent, BreakpointRequest, ByteType, ByteValue, CharType, CharValue, ClassLoaderReference, ClassObjectReference, ClassPrepareEvent, ClassPrepareRequest, ClassType, ClassUnloadEvent, ClassUnloadRequest, DoubleType, DoubleValue, Event, EventQueue, EventRequest, EventRequestManager, EventSet, ExceptionEvent, ExceptionRequest, Field, FloatType, FloatValue, IntegerType, IntegerValue, InterfaceType, LocalVariable, LocatableEvent, Location, LongType, LongValue, Method, MethodEntryEvent, MethodEntryRequest, MethodExitEvent, MethodExitRequest, ModificationWatchpointEvent, ModificationWatchpointRequest, MonitorContendedEnteredEvent, MonitorContendedEnteredRequest, MonitorContendedEnterEvent, MonitorContendedEnterRequest, MonitorInfo, MonitorWaitedEvent, MonitorWaitedRequest, MonitorWaitEvent, MonitorWaitRequest, ObjectReference, PathSearchingVirtualMachine, PrimitiveType, PrimitiveValue, ReferenceType, ShortType, ShortValue, StackFrame, StepEvent, StepRequest, StringReference, ThreadDeathEvent, ThreadDeathRequest, ThreadGroupReference, ThreadReference, ThreadStartEvent, ThreadStartRequest, Type, TypeComponent, Value, VirtualMachine, VMDeathEvent, VMDeathRequest, VMDisconnectEvent, VMStartEvent, VoidType, VoidValue, WatchpointEvent, WatchpointRequest
public interface Mirror

A proxy used by a debugger to examine or manipulate some entity in another virtual machine. Mirror is the root of the interface hierarchy for this package. Mirrors can be proxies for objects in the target VM (ObjectReference), primitive values (for example, IntegerValue), types (for example, ReferenceType), dynamic application state (for example, StackFrame), and even debugger-specific constructs (for example, BreakpointRequest). The VirtualMachine itself is also considered a mirror, representing the composite state of the target VM.

There is no guarantee that a particular entity in the target VM will map to a single instance of Mirror. Implementors are free to decide whether a single mirror will be used for some or all mirrors. Clients of this interface should always use equals to compare two mirrors for equality.

Any method on a Mirror that takes a Mirror as an parameter directly or indirectly (e.g., as a element in a List) will throw VMMismatchException if the mirrors are from different virtual machines.

Since:
1.3
See Also:
VirtualMachine

Method Summary
String | toString() Returns a String describing this mirror
VirtualMachine | virtualMachine() Gets the VirtualMachine to which this Mirror belongs.

Method Detail

virtualMachine

VirtualMachine virtualMachine()
Gets the VirtualMachine to which this Mirror belongs. A Mirror must be associated with a VirtualMachine to have any meaning.

Returns:
the VirtualMachine for which this mirror is a proxy.

toString

String toString()
Returns a String describing this mirror

Overrides:
toString in class Object
Returns:
a string describing this mirror.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MonitorInfo

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface MonitorInfo

All Superinterfaces:
Mirror
public interface MonitorInfo
extends Mirror

Information about a monitor owned by a thread.

Since:
1.6

Method Summary
ObjectReference | monitor() Returns the ObjectReference object for the monitor.
int | stackDepth() Returns the stack depth at which this monitor was acquired by the owning thread.
ThreadReference | thread() Returns a ThreadReference object for the thread that owns the monitor.
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

monitor

ObjectReference monitor()
Returns the ObjectReference object for the monitor.

Returns:
the ObjectReference object for the monitor.
Throws:
InvalidStackFrameException - if the associated stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.
Since:
1.6
See Also:
ThreadReference.ownedMonitorsAndFrames()

stackDepth

int stackDepth()
Returns the stack depth at which this monitor was acquired by the owning thread. Returns -1 if the implementation cannot determine the stack depth (e.g., for monitors acquired by JNI MonitorEnter).

Returns:
the stack depth at which this monitor was acquired by the owning thread.
Throws:
InvalidStackFrameException - if the associated stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.
See Also:
ThreadReference.ownedMonitorsAndFrames()

thread

ThreadReference thread()
Returns a ThreadReference object for the thread that owns the monitor.

Returns:
a ThreadReference object for the thread that owns the monitor.
Throws:
InvalidStackFrameException - if the associated stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.
See Also:
ThreadReference.frame(int)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


NativeMethodException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class NativeMethodException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  com.sun.jdi.NativeMethodException
All Implemented Interfaces:
Serializable
public class NativeMethodException
extends RuntimeException

Thrown to indicate an operation cannot be completed because it is not valid for a native method.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
NativeMethodException()
NativeMethodException(String message)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NativeMethodException

public NativeMethodException()

NativeMethodException

public NativeMethodException(String message)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectCollectedException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class ObjectCollectedException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  com.sun.jdi.ObjectCollectedException
All Implemented Interfaces:
Serializable
public class ObjectCollectedException
extends RuntimeException

Thrown to indicate that the requested operation cannot be completed because the specified object has been garbage collected.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
ObjectCollectedException()
ObjectCollectedException(String s)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ObjectCollectedException

public ObjectCollectedException()

ObjectCollectedException

public ObjectCollectedException(String s)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ObjectReference

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface ObjectReference

All Superinterfaces:
Mirror, Value
All Known Subinterfaces:
ArrayReference, ClassLoaderReference, ClassObjectReference, StringReference, ThreadGroupReference, ThreadReference
public interface ObjectReference
extends Value

An object that currently exists in the target VM. An ObjectReference mirrors only the object itself and is not specific to any Field or LocalVariable to which it is currently assigned. An ObjectReference can have 0 or more references from field(s) and/or variable(s).

Any method on ObjectReference which directly or indirectly takes ObjectReference as an parameter may throw VMDisconnectedException if the target VM is disconnected and the VMDisconnectEvent has been or is available to be read from the EventQueue.

Any method on ObjectReference which directly or indirectly takes ObjectReference as an parameter may throw VMOutOfMemoryException if the target VM has run out of memory.

Any method on ObjectReference or which directly or indirectly takes ObjectReference as parameter may throw ObjectCollectedException if the mirrored object has been garbage collected.

Since:
1.3

Field Summary
static int | INVOKE_NONVIRTUAL Perform non-virtual method invocation
static int | INVOKE_SINGLE_THREADED Perform method invocation with only the invoking thread resumed
Method Summary
void | disableCollection() Prevents garbage collection for this object.
void | enableCollection() Permits garbage collection for this object.
int | entryCount() Returns the number times this object's monitor has been entered by the current owning thread.
boolean | equals(Object obj) Compares the specified Object with this ObjectReference for equality.
Value | getValue(Field sig) Gets the value of a given instance or static field in this object.
Map<Field,Value> | getValues(List<? extends Field> fields) Gets the value of multiple instance and/or static fields in this object.
int | hashCode() Returns the hash code value for this ObjectReference.
Value | invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options) Invokes the specified Method on this object in the target VM.
boolean | isCollected() Determines if this object has been garbage collected in the target VM.
ThreadReference | owningThread() Returns an ThreadReference for the thread, if any, which currently owns this object's monitor.
ReferenceType | referenceType() Gets the ReferenceType that mirrors the type of this object.
List<ObjectReference> | referringObjects(long maxReferrers) Returns objects that directly reference this object.
void | setValue(Field field, Value value) Sets the value of a given instance or static field in this object.
long | uniqueID() Returns a unique identifier for this ObjectReference.
List<ThreadReference> | waitingThreads() Returns a List containing a ThreadReference for each thread currently waiting for this object's monitor.
Methods inherited from interface com.sun.jdi.Value
type
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Field Detail

INVOKE_SINGLE_THREADED

static final int INVOKE_SINGLE_THREADED
Perform method invocation with only the invoking thread resumed

See Also:
Constant Field Values

INVOKE_NONVIRTUAL

static final int INVOKE_NONVIRTUAL
Perform non-virtual method invocation

See Also:
Constant Field Values
Method Detail

referenceType

ReferenceType referenceType()
Gets the ReferenceType that mirrors the type of this object. The type may be a subclass or implementor of the declared type of any field or variable which currently holds it. For example, right after the following statement.

Object obj = new String("Hello, world!");

The ReferenceType of obj will mirror java.lang.String and not java.lang.Object.

The type of an object never changes, so this method will always return the same ReferenceType over the lifetime of the mirrored object.

The returned ReferenceType will be a ClassType or ArrayType and never an InterfaceType.

Returns:
the ReferenceType for this object.

getValue

Value getValue(Field sig)
Gets the value of a given instance or static field in this object. The Field must be valid for this ObjectReference; that is, it must be from the mirrored object's class or a superclass of that class.

Parameters:
sig - the field containing the requested value
Returns:
the Value of the instance field.
Throws:
IllegalArgumentException - if the field is not valid for this object's class.

getValues

Map<Field,Value> getValues(List<? extends Field> fields)
Gets the value of multiple instance and/or static fields in this object. The Fields must be valid for this ObjectReference; that is, they must be from the mirrored object's class or a superclass of that class.

Parameters:
fields - a list of Field objects containing the requested values.
Returns:
a Map of the requested Field objects with their Value.
Throws:
IllegalArgumentException - if any field is not valid for this object's class.

setValue

void setValue(Field field,
              Value value)
              throws InvalidTypeException,
                     ClassNotLoadedException
Sets the value of a given instance or static field in this object. The Field must be valid for this ObjectReference; that is, it must be from the mirrored object's class or a superclass of that class. If static, the field must not be final.

Object values must be assignment compatible with the field type (This implies that the field type must be loaded through the enclosing class's class loader). Primitive values must be either assignment compatible with the field type or must be convertible to the field type without loss of information. See the JavaTM Language Specification. section 5.2 for more information on assignment compatibility.

Parameters:
field - the field containing the requested value
value - the new value to assign
Throws:
IllegalArgumentException - if the field is not valid for this object's class.
InvalidTypeException - if the value's type does not match the field's type.
ClassNotLoadedException - if 'value' is not null, and the field type has not yet been loaded through the appropriate class loader.
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().

invokeMethod

Value invokeMethod(ThreadReference thread,
                   Method method,
                   List<? extends Value> arguments,
                   int options)
                   throws InvalidTypeException,
                          ClassNotLoadedException,
                          IncompatibleThreadStateException,
                          InvocationException
Invokes the specified Method on this object in the target VM. The specified method can be defined in this object's class, in a superclass of this object's class, or in an interface implemented by this object. The method may be a static method or an instance method, but not a static initializer or constructor. Use ClassType.newInstance(com.sun.jdi.ThreadReference, com.sun.jdi.Method, java.util.List, int) to create a new object and run its constructor.

The method invocation will occur in the specified thread. Method invocation can occur only if the specified thread has been suspended by an event which occurred in that thread. Method invocation is not supported when the target VM has been suspended through VirtualMachine.suspend() or when the specified thread is suspended through ThreadReference.suspend().

The specified method is invoked with the arguments in the specified argument list. The method invocation is synchronous; this method does not return until the invoked method returns in the target VM. If the invoked method throws an exception, this method will throw an InvocationException which contains a mirror to the exception object thrown.

Object arguments must be assignment compatible with the argument type (This implies that the argument type must be loaded through the enclosing class's class loader). Primitive arguments must be either assignment compatible with the argument type or must be convertible to the argument type without loss of information. If the method being called accepts a variable number of arguments, then the last argument type is an array of some component type. The argument in the matching position can be omitted, or can be null, an array of the same component type, or an argument of the component type followed by any number of other arguments of the same type. If the argument is omitted, then a 0 length array of the component type is passed. The component type can be a primitive type. Autoboxing is not supported. See the Java Language Specification. section 5.2 for more information on assignment compatibility.

By default, the method is invoked using dynamic lookup as documented in the Java Language Specification second edition, section 15.12.4.4; in particular, overriding based on the runtime type of the object mirrored by this ObjectReference will occur. This behavior can be changed by specifying the INVOKE_NONVIRTUAL bit flag in the options argument. If this flag is set, the specified method is invoked whether or not it is overridden for this object's runtime type. The method, in this case, must not belong to an interface and must not be abstract. This option is useful for performing method invocations like those done with the super keyword in the Java programming language.

By default, all threads in the target VM are resumed while the method is being invoked if they were previously suspended by an event or by VirtualMachine.suspend() or ThreadReference.suspend(). This is done to prevent the deadlocks that will occur if any of the threads own monitors that will be needed by the invoked method. Note, however, that this implicit resume acts exactly like ThreadReference.resume(), so if the thread's suspend count is greater than 1, it will remain in a suspended state during the invocation and thus a deadlock could still occur. By default, when the invocation completes, all threads in the target VM are suspended, regardless their state before the invocation. It is possible that breakpoints or other events might occur during the invocation. This can cause deadlocks as described above. It can also cause a deadlock if invokeMethod is called from the client's event handler thread. In this case, this thread will be waiting for the invokeMethod to complete and won't read the EventSet that comes in for the new event. If this new EventSet is SUSPEND_ALL, then a deadlock will occur because no one will resume the EventSet. To avoid this, all EventRequests should be disabled before doing the invokeMethod, or the invokeMethod should not be done from the client's event handler thread.

The resumption of other threads during the invocation can be prevented by specifying the INVOKE_SINGLE_THREADED bit flag in the options argument; however, there is no protection against or recovery from the deadlocks described above, so this option should be used with great caution. Only the specified thread will be resumed (as described for all threads above). Upon completion of a single threaded invoke, the invoking thread will be suspended once again. Note that any threads started during the single threaded invocation will not be suspended when the invocation completes.

If the target VM is disconnected during the invoke (for example, through VirtualMachine.dispose()) the method invocation continues.

Parameters:
thread - the thread in which to invoke.
method - the Method to invoke.
arguments - the list of Value arguments bound to the invoked method. Values from the list are assigned to arguments in the order they appear in the method signature.
options - the integer bit flag options.
Returns:
a Value mirror of the invoked method's return value.
Throws:
IllegalArgumentException - if the method is not a member of this object's class, if the size of the argument list does not match the number of declared arguemnts for the method, if the method is a constructor or static intializer, or if INVOKE_NONVIRTUAL is specified and the method is either abstract or an interface member.
{@link - InvalidTypeException} if any argument in the argument list is not assignable to the corresponding method argument type.
ClassNotLoadedException - if any argument type has not yet been loaded through the appropriate class loader.
IncompatibleThreadStateException - if the specified thread has not been suspended by an event.
InvocationException - if the method invocation resulted in an exception in the target VM.
InvalidTypeException - If the arguments do not meet this requirement -- Object arguments must be assignment compatible with the argument type. This implies that the argument type must be loaded through the enclosing class's class loader. Primitive arguments must be either assignment compatible with the argument type or must be convertible to the argument type without loss of information. See JLS section 5.2 for more information on assignment compatibility.
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().

disableCollection

void disableCollection()
Prevents garbage collection for this object. By default all ObjectReference values returned by JDI may be collected at any time the target VM is running. A call to this method guarantees that the object will not be collected. enableCollection() can be used to allow collection once again.

Calls to this method are counted. Every call to this method requires a corresponding call to enableCollection() before garbage collection is re-enabled.

Note that while the target VM is suspended, no garbage collection will occur because all threads are suspended. The typical examination of variables, fields, and arrays during the suspension is safe without explicitly disabling garbage collection.

This method should be used sparingly, as it alters the pattern of garbage collection in the target VM and, consequently, may result in application behavior under the debugger that differs from its non-debugged behavior.

Throws:
VMCannotBeModifiedException - if the VirtualMachine is read-only -see VirtualMachine.canBeModified().

enableCollection

void enableCollection()
Permits garbage collection for this object. By default all ObjectReference values returned by JDI may be collected at any time the target VM is running. A call to this method is necessary only if garbage collection was previously disabled with disableCollection().

Throws:
VMCannotBeModifiedException - if the VirtualMachine is read-only -see VirtualMachine.canBeModified().

isCollected

boolean isCollected()
Determines if this object has been garbage collected in the target VM.

Returns:
true if this ObjectReference has been collected; false otherwise.
Throws:
VMCannotBeModifiedException - if the VirtualMachine is read-only -see VirtualMachine.canBeModified().

uniqueID

long uniqueID()
Returns a unique identifier for this ObjectReference. It is guaranteed to be unique among all ObjectReferences from the same VM that have not yet been disposed. The guarantee applies as long as this ObjectReference has not yet been disposed.

Returns:
a long unique ID

waitingThreads

List<ThreadReference> waitingThreads()
                                     throws IncompatibleThreadStateException
Returns a List containing a ThreadReference for each thread currently waiting for this object's monitor. See ThreadReference.currentContendedMonitor() for information about when a thread is considered to be waiting for a monitor.

Not all target VMs support this operation. See VirtualMachine#canGetMonitorInfo to determine if the operation is supported.

Returns:
a List of ThreadReference objects. The list has zero length if no threads are waiting for the monitor.
Throws:
UnsupportedOperationException - if the target VM does not support this operation.
IncompatibleThreadStateException - if any waiting thread is not suspended in the target VM

owningThread

ThreadReference owningThread()
                             throws IncompatibleThreadStateException
Returns an ThreadReference for the thread, if any, which currently owns this object's monitor. See ThreadReference.ownedMonitors() for a definition of ownership.

Not all target VMs support this operation. See VirtualMachine#canGetMonitorInfo to determine if the operation is supported.

Returns:
the ThreadReference which currently owns the monitor, or null if it is unowned.
Throws:
UnsupportedOperationException - if the target VM does not support this operation.
IncompatibleThreadStateException - if the owning thread is not suspended in the target VM

entryCount

int entryCount()
               throws IncompatibleThreadStateException
Returns the number times this object's monitor has been entered by the current owning thread. See ThreadReference.ownedMonitors() for a definition of ownership.

Not all target VMs support this operation. See VirtualMachine#canGetMonitorInfo to determine if the operation is supported.

Returns:
the integer count of the number of entries.
Throws:
UnsupportedOperationException - if the target VM does not support this operation.
IncompatibleThreadStateException - if the owning thread is not suspended in the target VM
See Also:
owningThread()

referringObjects

List<ObjectReference> referringObjects(long maxReferrers)
Returns objects that directly reference this object. Only objects that are reachable for the purposes of garbage collection are returned. Note that an object can also be referenced in other ways, such as from a local variable in a stack frame, or from a JNI global reference. Such non-object referrers are not returned by this method.

Not all target virtual machines support this operation. Use VirtualMachine.canGetInstanceInfo() to determine if the operation is supported.

Parameters:
maxReferrers - The maximum number of referring objects to return. Must be non-negative. If zero, all referring objects are returned.
Returns:
a of List of ObjectReference objects. If there are no objects that reference this object, a zero-length list is returned..
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation - see canGetInstanceInfo()
IllegalArgumentException - if maxReferrers is less than zero.
Since:
1.6
See Also:
VirtualMachine.instanceCounts(List), ReferenceType.instances(long)

equals

boolean equals(Object obj)
Compares the specified Object with this ObjectReference for equality.

Overrides:
equals in class Object
Returns:
true if the Object is an ObjectReference, if the ObjectReferences belong to the same VM, and if applying the "==" operator on the mirrored objects in that VM evaluates to true.

hashCode

int hashCode()
Returns the hash code value for this ObjectReference.

Overrides:
hashCode in class Object
Returns:
the integer hash code
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PathSearchingVirtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface PathSearchingVirtualMachine

All Superinterfaces:
Mirror, VirtualMachine
public interface PathSearchingVirtualMachine
extends VirtualMachine

A virtual machine which searches for classes through paths

Since:
1.3

Field Summary
Fields inherited from interface com.sun.jdi.VirtualMachine
TRACE_ALL, TRACE_EVENTS, TRACE_NONE, TRACE_OBJREFS, TRACE_RECEIVES, TRACE_REFTYPES, TRACE_SENDS
Method Summary
String | baseDirectory() Get the base directory used for path searching.
List<String> | bootClassPath() Get the boot class path for this virtual machine.
List<String> | classPath() Get the class path for this virtual machine.
Methods inherited from interface com.sun.jdi.VirtualMachine
allClasses, allThreads, canAddMethod, canBeModified, canForceEarlyReturn, canGetBytecodes, canGetClassFileVersion, canGetConstantPool, canGetCurrentContendedMonitor, canGetInstanceInfo, canGetMethodReturnValues, canGetMonitorFrameInfo, canGetMonitorInfo, canGetOwnedMonitorInfo, canGetSourceDebugExtension, canGetSyntheticAttribute, canPopFrames, canRedefineClasses, canRequestMonitorEvents, canRequestVMDeathEvent, canUnrestrictedlyRedefineClasses, canUseInstanceFilters, canUseSourceNameFilters, canWatchFieldAccess, canWatchFieldModification, classesByName, description, dispose, eventQueue, eventRequestManager, exit, getDefaultStratum, instanceCounts, mirrorOf, mirrorOf, mirrorOf, mirrorOf, mirrorOf, mirrorOf, mirrorOf, mirrorOf, mirrorOf, mirrorOfVoid, name, process, redefineClasses, resume, setDebugTraceMode, setDefaultStratum, suspend, topLevelThreadGroups, version
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

classPath

List<String> classPath()
Get the class path for this virtual machine.

Returns:
List of components of the classpath, each represented by a String.

bootClassPath

List<String> bootClassPath()
Get the boot class path for this virtual machine.

Returns:
List of components of the boot class path, each represented by a String.

baseDirectory

String baseDirectory()
Get the base directory used for path searching. Relative directories in the class path and boot class path can be resolved through this directory name.

Returns:
the base directory.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


PrimitiveValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface PrimitiveValue

All Superinterfaces:
Mirror, Value
All Known Subinterfaces:
BooleanValue, ByteValue, CharValue, DoubleValue, FloatValue, IntegerValue, LongValue, ShortValue
public interface PrimitiveValue
extends Value

The value assigned to a field or variable of primitive type in a target VM. Each primitive values is accessed through a subinterface of this interface.

Since:
1.3

Method Summary
boolean | booleanValue() Converts this value to a BooleanValue and returns the result as a boolean.
byte | byteValue() Converts this value to a ByteValue and returns the result as a byte.
char | charValue() Converts this value to a CharValue and returns the result as a char.
double | doubleValue() Converts this value to a DoubleValue and returns the result as a double.
float | floatValue() Converts this value to a FloatValue and returns the result as a float.
int | intValue() Converts this value to an IntegerValue and returns the result as an int.
long | longValue() Converts this value to a LongValue and returns the result as a long.
short | shortValue() Converts this value to a ShortValue and returns the result as a short.
Methods inherited from interface com.sun.jdi.Value
type
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

booleanValue

boolean booleanValue()
Converts this value to a BooleanValue and returns the result as a boolean.

Returns:
true if this value is non-zero (or true if already a BooleanValue); false otherwise.

byteValue

byte byteValue()
Converts this value to a ByteValue and returns the result as a byte. The value will be narrowed as necessary, and magnitude or precision information may be lost (as if the primitive had been cast to a byte).

Returns:
the value, converted to byte

charValue

char charValue()
Converts this value to a CharValue and returns the result as a char. The value will be narrowed or widened as necessary, and magnitude or precision information may be lost (as if the primitive had been cast to a char, in the narrowing case).

Returns:
the value, converted to char

shortValue

short shortValue()
Converts this value to a ShortValue and returns the result as a short. The value will be narrowed or widened as necessary, and magnitude or precision information may be lost (as if the primitive had been cast to a short, in the narrowing case).

Returns:
the value, converted to short

intValue

int intValue()
Converts this value to an IntegerValue and returns the result as an int. The value will be narrowed or widened as necessary, and magnitude or precision information may be lost (as if the primitive had been cast to an int, in the narrowing case).

Returns:
the value, converted to int

longValue

long longValue()
Converts this value to a LongValue and returns the result as a long. The value will be narrowed or widened as necessary, and magnitude or precision information may be lost (as if the primitive had been cast to a long, in the narrowing case).

Returns:
the value, converted to long

floatValue

float floatValue()
Converts this value to a FloatValue and returns the result as a float. The value will be narrowed or widened as necessary, and magnitude or precision information may be lost (as if the primitive had been cast to a float, in the narrowing case).

Returns:
the value, converted to float

doubleValue

double doubleValue()
Converts this value to a DoubleValue and returns the result as a double. The value will be widened as necessary, and precision information may be lost.

Returns:
the value, converted to double
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ReferenceType

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface ReferenceType

All Superinterfaces:
Accessible, Comparable<ReferenceType>, Mirror, Type
All Known Subinterfaces:
ArrayType, ClassType, InterfaceType
public interface ReferenceType
extends Type, Comparable<ReferenceType>, Accessible

The type of an object in a target VM. ReferenceType encompasses classes, interfaces, and array types as defined in the JavaTM Language Specification. All ReferenceType objects belong to one of the following subinterfaces: ClassType for classes, InterfaceType for interfaces, and ArrayType for arrays. Note that primitive classes (for example, the reflected type of Integer.TYPE) are represented as ClassType. The VM creates Class objects for all three, so from the VM perspective, each ReferenceType maps to a distinct Class object.

ReferenceTypes can be obtained by querying a particular ObjectReference for its type or by getting a list of all reference types from the VirtualMachine.

ReferenceType provides access to static type information such as methods and fields and provides access to dynamic type information such as the corresponding Class object and the classloader.

Any method on ReferenceType which directly or indirectly takes ReferenceType as an parameter may throw VMDisconnectedException if the target VM is disconnected and the VMDisconnectEvent has been or is available to be read from the EventQueue.

Any method on ReferenceType which directly or indirectly takes ReferenceType as an parameter may throw VMOutOfMemoryException if the target VM has run out of memory.

Any method on ReferenceType or which directly or indirectly takes ReferenceType as parameter may throw ObjectCollectedException if the mirrored type has been unloaded.

Since:
1.3
See Also:
ObjectReference, ObjectReference.referenceType(), VirtualMachine, VirtualMachine.allClasses()

Method Summary
List<Field> | allFields() Returns a list containing each Field declared in this type, and its superclasses, implemented interfaces, and/or superinterfaces.
List<Location> | allLineLocations() Returns a list containing a Location object for each executable source line in this reference type.
List<Location> | allLineLocations(String stratum, String sourceName) Returns a list containing a Location object for each executable source line in this reference type.
List<Method> | allMethods() Returns a list containing each Method declared in this type, and its superclasses, implemented interfaces, and/or superinterfaces.
List<String> | availableStrata() Return the available strata for this reference type.
ClassLoaderReference | classLoader() Gets the classloader object which loaded the class corresponding to this type.
ClassObjectReference | classObject() Returns the class object that corresponds to this type in the target VM.
byte[] | constantPool() Returns the raw bytes of the constant pool in the format of the constant_pool item of the Class File Format in the Java Virtual Machine Specification.
int | constantPoolCount() Returns the number of entries in the constant pool plus one.
String | defaultStratum() Returns the default stratum for this reference type.
boolean | equals(Object obj) Compares the specified Object with this ReferenceType for equality.
boolean | failedToInitialize() Determines if initialization failed for this class.
Field | fieldByName(String fieldName) Finds the visible Field with the given non-ambiguous name.
List<Field> | fields() Returns a list containing each Field declared in this type.
String | genericSignature() Gets the generic signature for this type if there is one.
Value | getValue(Field field) Gets the Value of a given static Field in this type.
Map<Field,Value> | getValues(List<? extends Field> fields) Returns a map containing the Value of each static Field in the given list.
int | hashCode() Returns the hash code value for this ObjectReference.
List<ObjectReference> | instances(long maxInstances) Returns instances of this ReferenceType.
boolean | isAbstract() Determines if this type was declared abstract.
boolean | isFinal() Determines if this type was declared final.
boolean | isInitialized() Determines if this type has been initialized.
boolean | isPrepared() Determines if this type has been prepared.
boolean | isStatic() Determines if this type was declared static.
boolean | isVerified() Determines if this type has been verified.
List<Location> | locationsOfLine(int lineNumber) Returns a List containing all Location objects that map to the given line number.
List<Location> | locationsOfLine(String stratum, String sourceName, int lineNumber) Returns a List containing all Location objects that map to the given line number.
int | majorVersion() Returns the class major version number, as defined in the class file format of the Java Virtual Machine Specification.
List<Method> | methods() Returns a list containing each Method declared directly in this type.
List<Method> | methodsByName(String name) Returns a List containing each visible Method that has the given name.
List<Method> | methodsByName(String name, String signature) Returns a List containing each visible Method that has the given name and signature.
int | minorVersion() Returns the class minor version number, as defined in the class file format of the Java Virtual Machine Specification.
String | name() Gets the fully qualified name of this type.
List<ReferenceType> | nestedTypes() Returns a List containing ReferenceType objects that are declared within this type and are currently loaded into the Virtual Machine.
String | sourceDebugExtension() Get the source debug extension of this type.
String | sourceName() Gets an identifying name for the source corresponding to the declaration of this type.
List<String> | sourceNames(String stratum) Gets the identifying names for all the source corresponding to the declaration of this type.
List<String> | sourcePaths(String stratum) Gets the paths to the source corresponding to the declaration of this type.
List<Field> | visibleFields() Returns a list containing each unhidden and unambiguous Field in this type.
List<Method> | visibleMethods() Returns a list containing each Method declared or inherited by this type.
Methods inherited from interface com.sun.jdi.Type
signature
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface java.lang.Comparable
compareTo
Methods inherited from interface com.sun.jdi.Accessible
isPackagePrivate, isPrivate, isProtected, isPublic, modifiers

Method Detail

name

String name()
Gets the fully qualified name of this type. The returned name is formatted as it might appear in a Java programming langauge declaration for objects of this type.

For primitive classes the returned name is the name of the corresponding primitive type; for example, "int" is returned as the name of the class represented by Integer.TYPE.

Specified by:
name in interface Type
Returns:
a string containing the type name.

genericSignature

String genericSignature()
Gets the generic signature for this type if there is one. Generic signatures are described in the "JavaTM Virtual Machine Specification, 3rd Edition.

Returns:
a string containing the generic signature, or null if there is no generic signature.
Since:
1.5

classLoader

ClassLoaderReference classLoader()
Gets the classloader object which loaded the class corresponding to this type.

Returns:
a ClassLoaderReference which mirrors the classloader, or null if the class was loaded through the bootstrap class loader.

sourceName

String sourceName()
                  throws AbsentInformationException
Gets an identifying name for the source corresponding to the declaration of this type. Interpretation of this string is the responsibility of the source repository mechanism.

The returned name is dependent on VM's default stratum (VirtualMachine.getDefaultStratum()). In the reference implementation, when using the base stratum, the returned string is the unqualified name of the source file containing the declaration of this type. In other strata the returned source name is the first source name for that stratum. Since other languages may have more than one source name for a reference type, the use of Location.sourceName() or sourceNames(String) is preferred.

For arrays (ArrayType) and primitive classes, AbsentInformationException is always thrown.

Returns:
the string source file name
Throws:
AbsentInformationException - if the source name is not known

sourceNames

List<String> sourceNames(String stratum)
                         throws AbsentInformationException
Gets the identifying names for all the source corresponding to the declaration of this type. Interpretation of these names is the responsibility of the source repository mechanism.

The returned names are for the specified stratum (see Location for a description of strata). In the reference implementation, when using the Java programming language stratum, the returned List contains one element: a String which is the unqualified name of the source file containing the declaration of this type. In other strata the returned source names are all the source names defined for that stratum.

Parameters:
stratum - The stratum to retrieve information from or null for the declaring type's default stratum.
Returns:
a List of String objects each representing a source name
Throws:
AbsentInformationException - if the source names are not known.

For arrays (ArrayType) and primitive classes, AbsentInformationException is always thrown.

Since:
1.4

sourcePaths

List<String> sourcePaths(String stratum)
                         throws AbsentInformationException
Gets the paths to the source corresponding to the declaration of this type. Interpretation of these paths is the responsibility of the source repository mechanism.

The returned paths are for the specified stratum (see Location for a description of strata). In the reference implementation, for strata which do not explicitly specify source path (the Java programming language stratum never does), the returned strings are the sourceNames(String) prefixed by the package name of this ReferenceType converted to a platform dependent path. For example, on a Windows platform, java.lang.Thread would return a List containing one element: "java\lang\Thread.java".

Parameters:
stratum - The stratum to retrieve information from or null for the declaring type's default stratum.
Returns:
a List of String objects each representing a source path
Throws:
AbsentInformationException - if the source names are not known.

For arrays (ArrayType) and primitive classes, AbsentInformationException is always thrown.

Since:
1.4

sourceDebugExtension

String sourceDebugExtension()
                            throws AbsentInformationException
Get the source debug extension of this type.

Not all target virtual machines support this operation. Use canGetSourceDebugExtension() to determine if the operation is supported.

Returns:
as a string the source debug extension attribute
Throws:
AbsentInformationException - if the extension is not specified
UnsupportedOperationException - if the target virtual machine does not support this operation - see canGetSourceDebugExtension(),

isStatic

boolean isStatic()
Determines if this type was declared static. Only nested types, can be declared static, so false is returned for any package-level type, array type, or primitive class.

Returns:
true if this type is static; false otherwise.

isAbstract

boolean isAbstract()
Determines if this type was declared abstract.

For arrays (ArrayType) and primitive classes, the return value is undefined.

Returns:
true if this type is abstract; false otherwise.

isFinal

boolean isFinal()
Determines if this type was declared final.

For arrays (ArrayType) and primitive classes, the return value is always true.

Returns:
true if this type is final; false otherwise.

isPrepared

boolean isPrepared()
Determines if this type has been prepared. See the JVM specification for a definition of class preparation.

For arrays (ArrayType) and primitive classes, the return value is undefined.

Returns:
true if this type is prepared; false otherwise.

isVerified

boolean isVerified()
Determines if this type has been verified. See the JVM specification for a definition of class verification.

For arrays (ArrayType) and primitive classes, the return value is undefined.

Returns:
true if this type is verified; false otherwise.

isInitialized

boolean isInitialized()
Determines if this type has been initialized. See the JVM specification for a definition of class verification. For InterfaceType, this method always returns the same value as isPrepared().

For arrays (ArrayType) and primitive classes, the return value is undefined.

Returns:
true if this type is initialized; false otherwise.

failedToInitialize

boolean failedToInitialize()
Determines if initialization failed for this class. See the JVM specification for details on class initialization.

For arrays (ArrayType) and primitive classes, the return value is undefined.

Returns:
true if initialization was attempted and failed; false otherwise.

fields

List<Field> fields()
Returns a list containing each Field declared in this type. Inherited fields are not included. Any synthetic fields created by the compiler are included in the list.

For arrays (ArrayType) and primitive classes, the returned list is always empty.

Returns:
a list Field objects; the list has length 0 if no fields exist.
Throws:
ClassNotPreparedException - if this class not yet been prepared.

visibleFields

List<Field> visibleFields()
Returns a list containing each unhidden and unambiguous Field in this type. Each field that can be accessed from the class or its instances with its simple name is included. Fields that are ambiguously multiply inherited or fields that are hidden by fields with the same name in a more recently inherited class cannot be accessed by their simple names and are not included in the returned list. All other inherited fields are included. See JLS section 8.3 for details.

For arrays (ArrayType) and primitive classes, the returned list is always empty.

Returns:
a List of Field objects; the list has length 0 if no visible fields exist.
Throws:
ClassNotPreparedException - if this class not yet been prepared.

allFields

List<Field> allFields()
Returns a list containing each Field declared in this type, and its superclasses, implemented interfaces, and/or superinterfaces. All declared and inherited fields are included, regardless of whether they are hidden or multiply inherited.

For arrays (ArrayType) and primitive classes, the returned list is always empty.

Returns:
a List of Field objects; the list has length 0 if no fields exist.
Throws:
ClassNotPreparedException - if this class not yet been prepared.

fieldByName

Field fieldByName(String fieldName)
Finds the visible Field with the given non-ambiguous name. This method follows the inheritance rules specified in the JLS (8.3.3) to determine visibility.

For arrays (ArrayType) and primitive classes, the returned value is always null.

Parameters:
fieldName - a String containing the name of desired field.
Returns:
a Field object which mirrors the found field, or null if there is no field with the given name or if the given name is ambiguous.
Throws:
ClassNotPreparedException - if this class not yet been prepared.

methods

List<Method> methods()
Returns a list containing each Method declared directly in this type. Inherited methods are not included. Constructors, the initialization method if any, and any synthetic methods created by the compiler are included in the list.

For arrays (ArrayType) and primitive classes, the returned list is always empty.

Returns:
a list Method objects; the list has length 0 if no methods exist.
Throws:
ClassNotPreparedException - if this class not yet been prepared.

visibleMethods

List<Method> visibleMethods()
Returns a list containing each Method declared or inherited by this type. Methods from superclasses or superinterfaces that that have been hidden or overridden are not included.

Note that despite this exclusion, multiple inherited methods with the same signature can be present in the returned list, but at most one can be a member of a ClassType. See JLS section 8.4.6 for details.

For arrays (ArrayType) and primitive classes, the returned list is always empty.

Returns:
a List of Method objects; the list has length 0 if no visible methods exist.
Throws:
ClassNotPreparedException - if this class not yet been prepared.

allMethods

List<Method> allMethods()
Returns a list containing each Method declared in this type, and its superclasses, implemented interfaces, and/or superinterfaces. All declared and inherited methods are included, regardless of whether they are hidden or overridden.

For arrays (ArrayType) and primitive classes, the returned list is always empty.

Returns:
a List of Method objects; the list has length 0 if no methods exist.
Throws:
ClassNotPreparedException - if this class not yet been prepared.

methodsByName

List<Method> methodsByName(String name)
Returns a List containing each visible Method that has the given name. This is most commonly used to find overloaded methods.

Overridden and hidden methods are not included. See JLS (8.4.6) for details.

For arrays (ArrayType) and primitive classes, the returned list is always empty.

Parameters:
name - the name of the method to find.
Returns:
a List of Method objects that match the given name; the list has length 0 if no matching methods are found.
Throws:
ClassNotPreparedException - if this class not yet been prepared.

methodsByName

List<Method> methodsByName(String name,
                           String signature)
Returns a List containing each visible Method that has the given name and signature. The signature string is the JNI signature for the target method:
  • ()V
  • ([Ljava/lang/String;)V
  • (IIII)Z
This method follows the inheritance rules specified in the JLS (8.4.6) to determine visibility.

At most one method in the list is a concrete method and a component of ClassType; any other methods in the list are abstract. Use ClassType.concreteMethodByName(java.lang.String, java.lang.String) to retrieve only the matching concrete method.

For arrays (ArrayType) and primitive classes, the returned list is always empty.

Parameters:
name - the name of the method to find.
signature - the signature of the method to find
Returns:
a List of Method objects that match the given name and signature; the list has length 0 if no matching methods are found.
Throws:
ClassNotPreparedException - if this class not yet been prepared.

nestedTypes

List<ReferenceType> nestedTypes()
Returns a List containing ReferenceType objects that are declared within this type and are currently loaded into the Virtual Machine. Both static nested types and non-static nested types (that is, inner types) are included. Local inner types (declared within a code block somewhere in this reference type) are also included in the returned list.

For arrays (ArrayType) and primitive classes, the returned list is always empty.

Returns:
a List of nested ReferenceType objects; the list has 0 length if there are no nested types.

getValue

Value getValue(Field field)
Gets the Value of a given static Field in this type. The Field must be valid for this type; that is, it must be declared in this type, a superclass, a superinterface, or an implemented interface.

Parameters:
field - the field containing the requested value
Returns:
the Value of the instance field.
Throws:
IllegalArgumentException - if the field is not valid for this object's class.

getValues

Map<Field,Value> getValues(List<? extends Field> fields)
Returns a map containing the Value of each static Field in the given list. The Fields must be valid for this type; that is, they must be declared in this type, a superclass, a superinterface, or an implemented interface.

Parameters:
fields - a list of Field objects containing the requested values.
Returns:
a Map of the requested Field objects with their Value.
Throws:
IllegalArgumentException - if any field is not valid for this object's class.
VMMismatchException - if a Mirror argument and this mirror do not belong to the same VirtualMachine.

classObject

ClassObjectReference classObject()
Returns the class object that corresponds to this type in the target VM. The VM creates class objects for every kind of ReferenceType: classes, interfaces, and array types.

Returns:
the ClassObjectReference for this reference type in the target VM.

allLineLocations

List<Location> allLineLocations()
                                throws AbsentInformationException
Returns a list containing a Location object for each executable source line in this reference type.

This method is equivalent to allLineLocations(vm.getDefaultStratum(),null) - see allLineLocations(String,String) for more information.

Throws:
AbsentInformationException - if there is no line number information for this class and there are non-native, non-abstract executable members of this class.
ClassNotPreparedException - if this class not yet been prepared.

allLineLocations

List<Location> allLineLocations(String stratum,
                                String sourceName)
                                throws AbsentInformationException
Returns a list containing a Location object for each executable source line in this reference type. Each location maps a source line to a range of code indices. The beginning of the range can be determined through Location.codeIndex(). The returned list may contain multiple locations for a particular line number, if the compiler and/or VM has mapped that line to two or more disjoint code index ranges. Note that it is possible for the same source line to represent different code index ranges in different methods.

For arrays (ArrayType) and primitive classes, the returned list is always empty. For interfaces (InterfaceType), the returned list will be non-empty only if the interface has executable code in its class initialization.

Returned list is for the specified stratum (see Location for a description of strata).

Parameters:
stratum - The stratum to retrieve information from or null for the defaultStratum().
sourceName - Return locations only within this source file or null to return locations.
Returns:
a List of all source line Location objects.
Throws:
AbsentInformationException - if there is no line number information for this class and there are non-native, non-abstract executable members of this class. Or if sourceName is non-null and source name information is not present.
ClassNotPreparedException - if this class not yet been prepared.
Since:
1.4

locationsOfLine

List<Location> locationsOfLine(int lineNumber)
                               throws AbsentInformationException
Returns a List containing all Location objects that map to the given line number.

This method is equivalent to locationsOfLine(vm.getDefaultStratum(), null, lineNumber) - see locationsOfLine(java.lang.String,java.lang.String,int) for more information.

Parameters:
lineNumber - the line number
Returns:
a List of all Location objects that map to the given line.
Throws:
AbsentInformationException - if there is no line number information for this class.
ClassNotPreparedException - if this class not yet been prepared.
See Also:
VirtualMachine.getDefaultStratum()

locationsOfLine

List<Location> locationsOfLine(String stratum,
                               String sourceName,
                               int lineNumber)
                               throws AbsentInformationException
Returns a List containing all Location objects that map to the given line number.

For arrays (ArrayType) and primitive classes, the returned list is always empty. For interfaces (InterfaceType), the returned list will be non-empty only if the interface has executable code in its class initialization at the specified line number. An empty list will be returned if there is no executable code at the specified line number.

Returned list is for the specified stratum (see Location for a description of strata).

Parameters:
stratum - the stratum to use for comparing line number and source name, or null to use the defaultStratum().
sourceName - the source name containing the line number, or null to match all source names
lineNumber - the line number
Returns:
a List of all Location objects that map to the given line.
Throws:
AbsentInformationException - if there is no line number information for this class. Or if sourceName is non-null and source name information is not present.
ClassNotPreparedException - if this class not yet been prepared.
Since:
1.4

availableStrata

List<String> availableStrata()
Return the available strata for this reference type.

See the Location for a description of strata.

Returns:
List of java.lang.String, each representing a stratum
Since:
1.4

defaultStratum

String defaultStratum()
Returns the default stratum for this reference type. This value is specified in the class file and cannot be set by the user. If the class file does not specify a default stratum the base stratum ("Java") will be returned.

See the Location for a description of strata.

Since:
1.4

instances

List<ObjectReference> instances(long maxInstances)
Returns instances of this ReferenceType. Only instances that are reachable for the purposes of garbage collection are returned.

Not all target virtual machines support this operation. Use VirtualMachine.canGetInstanceInfo() to determine if the operation is supported.

Parameters:
maxInstances - the maximum number of instances to return. Must be non-negative. If zero, all instances are returned.
Returns:
a List of ObjectReference objects. If there are no instances of this ReferenceType, a zero-length list is returned.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation - see canGetInstanceInfo()
IllegalArgumentException - if maxInstances is less than zero.
Since:
1.6
See Also:
VirtualMachine.instanceCounts(List), ObjectReference.referringObjects(long)

equals

boolean equals(Object obj)
Compares the specified Object with this ReferenceType for equality.

Overrides:
equals in class Object
Returns:
true if the Object is a ReferenceType, if the ReferenceTypes belong to the same VM, and if they mirror classes which correspond to the same instance of java.lang.Class in that VM.

hashCode

int hashCode()
Returns the hash code value for this ObjectReference.

Overrides:
hashCode in class Object
Returns:
the integer hash code

majorVersion

int majorVersion()
Returns the class major version number, as defined in the class file format of the Java Virtual Machine Specification. For arrays (ArrayType) and primitive classes, the returned major version number value is zero. Not all target virtual machines support this operation. Use VirtualMachine.canGetClassFileVersion() to determine if the operation is supported.

Returns:
the major version number of the class.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation - see canGetClassFileVersion()
Since:
1.6

minorVersion

int minorVersion()
Returns the class minor version number, as defined in the class file format of the Java Virtual Machine Specification. For arrays (ArrayType) and primitive classes, the returned minor version number value is zero. Not all target virtual machines support this operation. Use VirtualMachine.canGetClassFileVersion() to determine if the operation is supported.

Returns:
the minor version number of the class.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation - see canGetClassFileVersion()
Since:
1.6

constantPoolCount

int constantPoolCount()
Returns the number of entries in the constant pool plus one. This corresponds to the constant_pool_count item of the Class File Format in the Java Virtual Machine Specification. For arrays (ArrayType) and primitive classes, the returned constant pool count value is zero. Not all target virtual machines support this operation. Use VirtualMachine.canGetConstantPool() to determine if the operation is supported.

Returns:
total number of constant pool entries for a class plus one.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation - see canGetConstantPool()
Since:
1.6
See Also:
constantPool()

constantPool

byte[] constantPool()
Returns the raw bytes of the constant pool in the format of the constant_pool item of the Class File Format in the Java Virtual Machine Specification. The format of the constant pool may differ between versions of the Class File Format, so, the minor and major class version numbers should be checked for compatibility. For arrays (ArrayType) and primitive classes, a zero length byte array is returned. Not all target virtual machines support this operation. Use VirtualMachine.canGetConstantPool() to determine if the operation is supported.

Returns:
the raw bytes of constant pool.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation - see canGetConstantPool()
Since:
1.6
See Also:
constantPoolCount()
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


request

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Package com.sun.jdi.request

This package is used to request that a JDI event be sent under specified conditions.

See:
Description

Interface Summary
AccessWatchpointRequest | Request for notification when the contents of a field are accessed in the target VM.
BreakpointRequest | Identifies a Location in the target VM at which execution should be stopped.
ClassPrepareRequest | Request for notification when a class is prepared in the target VM.
ClassUnloadRequest | Request for notification when a class is unloaded in the target VM.
EventRequest | Represents a request for notification of an event.
EventRequestManager | Manages the creation and deletion of EventRequests.
ExceptionRequest | Request for notification when an exception occurs in the target VM.
MethodEntryRequest | Request for notification when a method is invoked in the target VM.
MethodExitRequest | Request for notification when a method returns in the target VM.
ModificationWatchpointRequest | Request for notification when a field is set.
MonitorContendedEnteredRequest | Request for notification of a thread in the target VM entering a monitor after waiting for it to be released by another thread.
MonitorContendedEnterRequest | Request for notification of a thread in the target VM attempting to enter a monitor already acquired by another thread.
MonitorWaitedRequest | Request for notification when a thread in the target VM has finished waiting on a monitor object.
MonitorWaitRequest | Request for notification when a thread in the target VM is about to wait on a monitor object.
StepRequest | Request for notification when a step occurs in the target VM.
ThreadDeathRequest | Request for notification when a thread terminates in the target VM.
ThreadStartRequest | Request for notification when a thread starts execution in the target VM.
VMDeathRequest | Request for notification when the target VM terminates.
WatchpointRequest | Identifies a Field in the target VM being watched.

Exception Summary
DuplicateRequestException | Thrown to indicate a duplicate event request.
InvalidRequestStateException | Thrown to indicate that the requested event cannot be modified because it is enabled.

Package com.sun.jdi.request Description

This package is used to request that a JDI event be sent under specified conditions. With the exception of termination events, which are always sent, there is one kind of EventRequest for each kind of Event - for example, BreakpointRequest is used to request a BreakpointEvent. Event requests are created by the EventRequestManager. Events and event processing are defined in the com.sun.jdi.event package.

Methods may be added to the interfaces in the JDI packages in future releases. Existing packages may be renamed if the JDI becomes a standard extension.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES


AccessWatchpointRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface AccessWatchpointRequest

All Superinterfaces:
EventRequest, Mirror, WatchpointRequest
public interface AccessWatchpointRequest
extends WatchpointRequest

Request for notification when the contents of a field are accessed in the target VM. This event will be triggered when the specified field is accessed by JavaTM programming language code or by a Java Native Interface (JNI) get function (Get<Type>Field, GetStatic<Type>Field). Access by JDI does not trigger this event. When an enabled AccessWatchpointRequest is satisfied, an event set containing an AccessWatchpointEvent will be placed on the EventQueue. The collection of existing ExceptionRequests is managed by the EventRequestManager The collection of existing watchpoints is managed by the EventRequestManager.

Note that the modification of a Field is not considered an access.

Since:
1.3
See Also:
ModificationWatchpointRequest, EventQueue, EventRequestManager

Field Summary
Fields inherited from interface com.sun.jdi.request.EventRequest
SUSPEND_ALL, SUSPEND_EVENT_THREAD, SUSPEND_NONE
Method Summary
Methods inherited from interface com.sun.jdi.request.WatchpointRequest
addClassExclusionFilter, addClassFilter, addClassFilter, addInstanceFilter, addThreadFilter, field
Methods inherited from interface com.sun.jdi.request.EventRequest
addCountFilter, disable, enable, getProperty, isEnabled, putProperty, setEnabled, setSuspendPolicy, suspendPolicy
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


com.sun.jdi.request Class Hierarchy

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Hierarchy For Package com.sun.jdi.request

Package Hierarchies:
All Packages

Class Hierarchy

  • java.lang.Object
    • java.lang.Throwable (implements java.io.Serializable)
      • java.lang.Exception
        • java.lang.RuntimeException
          • com.sun.jdi.request.DuplicateRequestException
          • com.sun.jdi.request.InvalidRequestStateException

Interface Hierarchy

  • com.sun.jdi.Locatable
    • com.sun.jdi.request.BreakpointRequest (also extends com.sun.jdi.request.EventRequest)
  • com.sun.jdi.Mirror
    • com.sun.jdi.request.EventRequest
      • com.sun.jdi.request.BreakpointRequest (also extends com.sun.jdi.Locatable)
      • com.sun.jdi.request.ClassPrepareRequest
      • com.sun.jdi.request.ClassUnloadRequest
      • com.sun.jdi.request.ExceptionRequest
      • com.sun.jdi.request.MethodEntryRequest
      • com.sun.jdi.request.MethodExitRequest
      • com.sun.jdi.request.MonitorContendedEnteredRequest
      • com.sun.jdi.request.MonitorContendedEnterRequest
      • com.sun.jdi.request.MonitorWaitedRequest
      • com.sun.jdi.request.MonitorWaitRequest
      • com.sun.jdi.request.StepRequest
      • com.sun.jdi.request.ThreadDeathRequest
      • com.sun.jdi.request.ThreadStartRequest
      • com.sun.jdi.request.VMDeathRequest
      • com.sun.jdi.request.WatchpointRequest
        • com.sun.jdi.request.AccessWatchpointRequest
        • com.sun.jdi.request.ModificationWatchpointRequest
    • com.sun.jdi.request.EventRequestManager
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


ModificationWatchpointRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface ModificationWatchpointRequest

All Superinterfaces:
EventRequest, Mirror, WatchpointRequest
public interface ModificationWatchpointRequest
extends WatchpointRequest

Request for notification when a field is set. This event will be triggered when a value is assigned to the specified field with a JavaTM programming language statement (assignment, increment, etc) or by a Java Native Interface (JNI) set function (Set<Type>Field, SetStatic<Type>Field). Setting a field to a value which is the same as the previous value still triggers this event. Modification by JDI does not trigger this event. When an enabled ModificationWatchpointRequest is satisfied, an event set containing a ModificationWatchpointEvent will be placed on the EventQueue. The collection of existing watchpoints is managed by the EventRequestManager.

Since:
1.3
See Also:
ModificationWatchpointEvent, AccessWatchpointRequest, EventQueue, EventRequestManager

Field Summary
Fields inherited from interface com.sun.jdi.request.EventRequest
SUSPEND_ALL, SUSPEND_EVENT_THREAD, SUSPEND_NONE
Method Summary
Methods inherited from interface com.sun.jdi.request.WatchpointRequest
addClassExclusionFilter, addClassFilter, addClassFilter, addInstanceFilter, addThreadFilter, field
Methods inherited from interface com.sun.jdi.request.EventRequest
addCountFilter, disable, enable, getProperty, isEnabled, putProperty, setEnabled, setSuspendPolicy, suspendPolicy
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Package com.sun.jdi.request

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Package
com.sun.jdi.request

Packages that use com.sun.jdi.request
com.sun.jdi | This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.
com.sun.jdi.event | This package defines JDI events and event processing.
com.sun.jdi.request | This package is used to request that a JDI event be sent under specified conditions.

Classes in com.sun.jdi.request used by com.sun.jdi
EventRequestManager
Manages the creation and deletion of EventRequests.

Classes in com.sun.jdi.request used by com.sun.jdi.event
EventRequest
Represents a request for notification of an event.

Classes in com.sun.jdi.request used by com.sun.jdi.request
AccessWatchpointRequest
Request for notification when the contents of a field are accessed in the target VM.
BreakpointRequest
Identifies a Location in the target VM at which execution should be stopped.
ClassPrepareRequest
Request for notification when a class is prepared in the target VM.
ClassUnloadRequest
Request for notification when a class is unloaded in the target VM.
EventRequest
Represents a request for notification of an event.
ExceptionRequest
Request for notification when an exception occurs in the target VM.
MethodEntryRequest
Request for notification when a method is invoked in the target VM.
MethodExitRequest
Request for notification when a method returns in the target VM.
ModificationWatchpointRequest
Request for notification when a field is set.
MonitorContendedEnteredRequest
Request for notification of a thread in the target VM entering a monitor after waiting for it to be released by another thread.
MonitorContendedEnterRequest
Request for notification of a thread in the target VM attempting to enter a monitor already acquired by another thread.
MonitorWaitedRequest
Request for notification when a thread in the target VM has finished waiting on a monitor object.
MonitorWaitRequest
Request for notification when a thread in the target VM is about to wait on a monitor object.
StepRequest
Request for notification when a step occurs in the target VM.
ThreadDeathRequest
Request for notification when a thread terminates in the target VM.
ThreadStartRequest
Request for notification when a thread starts execution in the target VM.
VMDeathRequest
Request for notification when the target VM terminates.
WatchpointRequest
Identifies a Field in the target VM being watched.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


VMDeathRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface VMDeathRequest

All Superinterfaces:
EventRequest, Mirror
public interface VMDeathRequest
extends EventRequest

Request for notification when the target VM terminates. When an enabled VMDeathRequest is satisfied, an event set containing a VMDeathEvent will be placed on the EventQueue. The collection of existing VMDeathRequests is managed by the EventRequestManager

Even without creating a VMDeathRequest, a single unsolicited VMDeathEvent will be sent with a suspend policy of SUSPEND_NONE. This request would typically be created so that a VMDeathEvent with a suspend policy of SUSPEND_ALL will be sent. This event can be used to assure completion of any processing which requires the VM to be alive (e.g. event processing). Note: the unsolicited VMDeathEvent will still be sent.

Since:
1.4
See Also:
VMDeathEvent, EventQueue, EventRequestManager

Field Summary
Fields inherited from interface com.sun.jdi.request.EventRequest
SUSPEND_ALL, SUSPEND_EVENT_THREAD, SUSPEND_NONE
Method Summary
Methods inherited from interface com.sun.jdi.request.EventRequest
addCountFilter, disable, enable, getProperty, isEnabled, putProperty, setEnabled, setSuspendPolicy, suspendPolicy
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


BreakpointRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface BreakpointRequest

All Superinterfaces:
EventRequest, Locatable, Mirror
public interface BreakpointRequest
extends EventRequest, Locatable

Identifies a Location in the target VM at which execution should be stopped. When an enabled BreakpointRequest is satisfied, an event set containing an BreakpointEvent will be placed on the EventQueue and the application is interrupted. The collection of existing breakpoints is managed by the EventRequestManager

Since:
1.3
See Also:
Location, BreakpointEvent, EventQueue, EventRequestManager

Field Summary
Fields inherited from interface com.sun.jdi.request.EventRequest
SUSPEND_ALL, SUSPEND_EVENT_THREAD, SUSPEND_NONE
Method Summary
void | addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance is the object specified.
void | addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
Location | location() Returns the location of the requested breakpoint.
Methods inherited from interface com.sun.jdi.request.EventRequest
addCountFilter, disable, enable, getProperty, isEnabled, putProperty, setEnabled, setSuspendPolicy, suspendPolicy
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

location

Location location()
Returns the location of the requested breakpoint.

Specified by:
location in interface Locatable
Returns:
the Location where this breakpoint has been set.

addThreadFilter

void addThreadFilter(ThreadReference thread)
Restricts the events generated by this request to those in the given thread.

Parameters:
thread - the thread to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addInstanceFilter

void addInstanceFilter(ObjectReference instance)
Restricts the events generated by this request to those in which the currently executing instance is the object specified.

Not all targets support this operation. Use VirtualMachine.canUseInstanceFilters() to determine if the operation is supported.

Parameters:
instance - the object which must be the current instance in order to pass this filter.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.
Since:
1.4
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Uses of Class com.sun.jdi.request.DuplicateRequestException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.request.DuplicateRequestException

No usage of com.sun.jdi.request.DuplicateRequestException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Class com.sun.jdi.request.InvalidRequestStateException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Class
com.sun.jdi.request.InvalidRequestStateException

No usage of com.sun.jdi.request.InvalidRequestStateException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.AccessWatchpointRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.AccessWatchpointRequest

Packages that use AccessWatchpointRequest
com.sun.jdi.request This package is used to request that a JDI event be sent under specified conditions.

Uses of AccessWatchpointRequest in com.sun.jdi.request

Methods in com.sun.jdi.request that return AccessWatchpointRequest
 AccessWatchpointRequest EventRequestManager.createAccessWatchpointRequest(Field field)
Creates a new disabled watchpoint which watches accesses to the specified field.

Methods in com.sun.jdi.request that return types with arguments of type AccessWatchpointRequest
 List<AccessWatchpointRequest> EventRequestManager.accessWatchpointRequests()
Return an unmodifiable list of the enabled and disabled access watchpoint requests.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.BreakpointRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.BreakpointRequest

Packages that use BreakpointRequest
com.sun.jdi.request This package is used to request that a JDI event be sent under specified conditions.

Uses of BreakpointRequest in com.sun.jdi.request

Methods in com.sun.jdi.request that return BreakpointRequest
 BreakpointRequest EventRequestManager.createBreakpointRequest(Location location)
Creates a new disabled BreakpointRequest.

Methods in com.sun.jdi.request that return types with arguments of type BreakpointRequest
 List<BreakpointRequest> EventRequestManager.breakpointRequests()
Return an unmodifiable list of the enabled and disabled breakpoint requests.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.ClassPrepareRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.ClassPrepareRequest

Packages that use ClassPrepareRequest
com.sun.jdi.request This package is used to request that a JDI event be sent under specified conditions.

Uses of ClassPrepareRequest in com.sun.jdi.request

Methods in com.sun.jdi.request that return ClassPrepareRequest
 ClassPrepareRequest EventRequestManager.createClassPrepareRequest()
Creates a new disabled ClassPrepareRequest.

Methods in com.sun.jdi.request that return types with arguments of type ClassPrepareRequest
 List<ClassPrepareRequest> EventRequestManager.classPrepareRequests()
Return an unmodifiable list of the enabled and disabled class prepare requests.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.ClassUnloadRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.ClassUnloadRequest

Packages that use ClassUnloadRequest
com.sun.jdi.request This package is used to request that a JDI event be sent under specified conditions.

Uses of ClassUnloadRequest in com.sun.jdi.request

Methods in com.sun.jdi.request that return ClassUnloadRequest
 ClassUnloadRequest EventRequestManager.createClassUnloadRequest()
Creates a new disabled ClassUnloadRequest.

Methods in com.sun.jdi.request that return types with arguments of type ClassUnloadRequest
 List<ClassUnloadRequest> EventRequestManager.classUnloadRequests()
Return an unmodifiable list of the enabled and disabled class unload requests.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.EventRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.EventRequest

Packages that use EventRequest
com.sun.jdi.event | This package defines JDI events and event processing.
com.sun.jdi.request | This package is used to request that a JDI event be sent under specified conditions.

Uses of EventRequest in com.sun.jdi.event

Methods in com.sun.jdi.event that return EventRequest
 EventRequest Event.request()

Uses of EventRequest in com.sun.jdi.request

Subinterfaces of EventRequest in com.sun.jdi.request
interface | AccessWatchpointRequest Request for notification when the contents of a field are accessed in the target VM.
interface | BreakpointRequest Identifies a Location in the target VM at which execution should be stopped.
interface | ClassPrepareRequest Request for notification when a class is prepared in the target VM.
interface | ClassUnloadRequest Request for notification when a class is unloaded in the target VM.
interface | ExceptionRequest Request for notification when an exception occurs in the target VM.
interface | MethodEntryRequest Request for notification when a method is invoked in the target VM.
interface | MethodExitRequest Request for notification when a method returns in the target VM.
interface | ModificationWatchpointRequest Request for notification when a field is set.
interface | MonitorContendedEnteredRequest Request for notification of a thread in the target VM entering a monitor after waiting for it to be released by another thread.
interface | MonitorContendedEnterRequest Request for notification of a thread in the target VM attempting to enter a monitor already acquired by another thread.
interface | MonitorWaitedRequest Request for notification when a thread in the target VM has finished waiting on a monitor object.
interface | MonitorWaitRequest Request for notification when a thread in the target VM is about to wait on a monitor object.
interface | StepRequest Request for notification when a step occurs in the target VM.
interface | ThreadDeathRequest Request for notification when a thread terminates in the target VM.
interface | ThreadStartRequest Request for notification when a thread starts execution in the target VM.
interface | VMDeathRequest Request for notification when the target VM terminates.
interface | WatchpointRequest Identifies a Field in the target VM being watched.

Methods in com.sun.jdi.request with parameters of type EventRequest
 void EventRequestManager.deleteEventRequest(EventRequest eventRequest)
Removes an eventRequest.

Method parameters in com.sun.jdi.request with type arguments of type EventRequest
 void EventRequestManager.deleteEventRequests(List<? extends EventRequest> eventRequests)
Removes a list of EventRequests.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.EventRequestManager

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.EventRequestManager

Packages that use EventRequestManager
com.sun.jdi This is the core package of the Java Debug Interface (JDI), it defines mirrors for values, types, and the target VirtualMachine itself - as well bootstrapping facilities.

Uses of EventRequestManager in com.sun.jdi

Methods in com.sun.jdi that return EventRequestManager
 EventRequestManager VirtualMachine.eventRequestManager()
Returns the event request manager for this virtual machine.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.ExceptionRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.ExceptionRequest

Packages that use ExceptionRequest
com.sun.jdi.request This package is used to request that a JDI event be sent under specified conditions.

Uses of ExceptionRequest in com.sun.jdi.request

Methods in com.sun.jdi.request that return ExceptionRequest
 ExceptionRequest EventRequestManager.createExceptionRequest(ReferenceType refType, boolean notifyCaught, boolean notifyUncaught)
Creates a new disabled ExceptionRequest.

Methods in com.sun.jdi.request that return types with arguments of type ExceptionRequest
 List<ExceptionRequest> EventRequestManager.exceptionRequests()
Return an unmodifiable list of the enabled and disabled exception requests.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.MethodEntryRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.MethodEntryRequest

Packages that use MethodEntryRequest
com.sun.jdi.request This package is used to request that a JDI event be sent under specified conditions.

Uses of MethodEntryRequest in com.sun.jdi.request

Methods in com.sun.jdi.request that return MethodEntryRequest
 MethodEntryRequest EventRequestManager.createMethodEntryRequest()
Creates a new disabled MethodEntryRequest.

Methods in com.sun.jdi.request that return types with arguments of type MethodEntryRequest
 List<MethodEntryRequest> EventRequestManager.methodEntryRequests()
Return an unmodifiable list of the enabled and disabled method entry requests.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.MethodExitRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.MethodExitRequest

Packages that use MethodExitRequest
com.sun.jdi.request This package is used to request that a JDI event be sent under specified conditions.

Uses of MethodExitRequest in com.sun.jdi.request

Methods in com.sun.jdi.request that return MethodExitRequest
 MethodExitRequest EventRequestManager.createMethodExitRequest()
Creates a new disabled MethodExitRequest.

Methods in com.sun.jdi.request that return types with arguments of type MethodExitRequest
 List<MethodExitRequest> EventRequestManager.methodExitRequests()
Return an unmodifiable list of the enabled and disabled method exit requests.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.ModificationWatchpointRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.ModificationWatchpointRequest

Packages that use ModificationWatchpointRequest
com.sun.jdi.request This package is used to request that a JDI event be sent under specified conditions.

Uses of ModificationWatchpointRequest in com.sun.jdi.request

Methods in com.sun.jdi.request that return ModificationWatchpointRequest
 ModificationWatchpointRequest EventRequestManager.createModificationWatchpointRequest(Field field)
Creates a new disabled watchpoint which watches accesses to the specified field.

Methods in com.sun.jdi.request that return types with arguments of type ModificationWatchpointRequest
 List<ModificationWatchpointRequest> EventRequestManager.modificationWatchpointRequests()
Return an unmodifiable list of the enabled and disabled modification watchpoint requests.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.MonitorContendedEnteredRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.MonitorContendedEnteredRequest

Packages that use MonitorContendedEnteredRequest
com.sun.jdi.request This package is used to request that a JDI event be sent under specified conditions.

Uses of MonitorContendedEnteredRequest in com.sun.jdi.request

Methods in com.sun.jdi.request that return MonitorContendedEnteredRequest
 MonitorContendedEnteredRequest EventRequestManager.createMonitorContendedEnteredRequest()
Creates a new disabled MonitorContendedEnteredRequest.

Methods in com.sun.jdi.request that return types with arguments of type MonitorContendedEnteredRequest
 List<MonitorContendedEnteredRequest> EventRequestManager.monitorContendedEnteredRequests()
Return an unmodifiable list of the enabled and disabled monitor contended entered requests.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.MonitorContendedEnterRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.MonitorContendedEnterRequest

Packages that use MonitorContendedEnterRequest
com.sun.jdi.request This package is used to request that a JDI event be sent under specified conditions.

Uses of MonitorContendedEnterRequest in com.sun.jdi.request

Methods in com.sun.jdi.request that return MonitorContendedEnterRequest
 MonitorContendedEnterRequest EventRequestManager.createMonitorContendedEnterRequest()
Creates a new disabled MonitorContendedEnterRequest.

Methods in com.sun.jdi.request that return types with arguments of type MonitorContendedEnterRequest
 List<MonitorContendedEnterRequest> EventRequestManager.monitorContendedEnterRequests()
Return an unmodifiable list of the enabled and disabled monitor contended enter requests.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.MonitorWaitedRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.MonitorWaitedRequest

Packages that use MonitorWaitedRequest
com.sun.jdi.request This package is used to request that a JDI event be sent under specified conditions.

Uses of MonitorWaitedRequest in com.sun.jdi.request

Methods in com.sun.jdi.request that return MonitorWaitedRequest
 MonitorWaitedRequest EventRequestManager.createMonitorWaitedRequest()
Creates a new disabled MonitorWaitedRequest.

Methods in com.sun.jdi.request that return types with arguments of type MonitorWaitedRequest
 List<MonitorWaitedRequest> EventRequestManager.monitorWaitedRequests()
Return an unmodifiable list of the enabled and disabled monitor waited requests.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.MonitorWaitRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.MonitorWaitRequest

Packages that use MonitorWaitRequest
com.sun.jdi.request This package is used to request that a JDI event be sent under specified conditions.

Uses of MonitorWaitRequest in com.sun.jdi.request

Methods in com.sun.jdi.request that return MonitorWaitRequest
 MonitorWaitRequest EventRequestManager.createMonitorWaitRequest()
Creates a new disabled MonitorWaitRequest.

Methods in com.sun.jdi.request that return types with arguments of type MonitorWaitRequest
 List<MonitorWaitRequest> EventRequestManager.monitorWaitRequests()
Return an unmodifiable list of the enabled and disabled monitor wait requests.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.StepRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.StepRequest

Packages that use StepRequest
com.sun.jdi.request This package is used to request that a JDI event be sent under specified conditions.

Uses of StepRequest in com.sun.jdi.request

Methods in com.sun.jdi.request that return StepRequest
 StepRequest EventRequestManager.createStepRequest(ThreadReference thread, int size, int depth)
Creates a new disabled StepRequest.

Methods in com.sun.jdi.request that return types with arguments of type StepRequest
 List<StepRequest> EventRequestManager.stepRequests()
Return an unmodifiable list of the enabled and disabled step requests.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.ThreadDeathRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.ThreadDeathRequest

Packages that use ThreadDeathRequest
com.sun.jdi.request This package is used to request that a JDI event be sent under specified conditions.

Uses of ThreadDeathRequest in com.sun.jdi.request

Methods in com.sun.jdi.request that return ThreadDeathRequest
 ThreadDeathRequest EventRequestManager.createThreadDeathRequest()
Creates a new disabled ThreadDeathRequest.

Methods in com.sun.jdi.request that return types with arguments of type ThreadDeathRequest
 List<ThreadDeathRequest> EventRequestManager.threadDeathRequests()
Return an unmodifiable list of the enabled and disabled thread death requests.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.ThreadStartRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.ThreadStartRequest

Packages that use ThreadStartRequest
com.sun.jdi.request This package is used to request that a JDI event be sent under specified conditions.

Uses of ThreadStartRequest in com.sun.jdi.request

Methods in com.sun.jdi.request that return ThreadStartRequest
 ThreadStartRequest EventRequestManager.createThreadStartRequest()
Creates a new disabled ThreadStartRequest.

Methods in com.sun.jdi.request that return types with arguments of type ThreadStartRequest
 List<ThreadStartRequest> EventRequestManager.threadStartRequests()
Return an unmodifiable list of the enabled and disabled thread start requests.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.VMDeathRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.VMDeathRequest

Packages that use VMDeathRequest
com.sun.jdi.request This package is used to request that a JDI event be sent under specified conditions.

Uses of VMDeathRequest in com.sun.jdi.request

Methods in com.sun.jdi.request that return VMDeathRequest
 VMDeathRequest EventRequestManager.createVMDeathRequest()
Creates a new disabled VMDeathRequest.

Methods in com.sun.jdi.request that return types with arguments of type VMDeathRequest
 List<VMDeathRequest> EventRequestManager.vmDeathRequests()
Return an unmodifiable list of the enabled and disabled VM death requests.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


Uses of Interface com.sun.jdi.request.WatchpointRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES

Uses of Interface
com.sun.jdi.request.WatchpointRequest

Packages that use WatchpointRequest
com.sun.jdi.request This package is used to request that a JDI event be sent under specified conditions.

Uses of WatchpointRequest in com.sun.jdi.request

Subinterfaces of WatchpointRequest in com.sun.jdi.request
interface | AccessWatchpointRequest Request for notification when the contents of a field are accessed in the target VM.
interface | ModificationWatchpointRequest Request for notification when a field is set.

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV NEXT FRAMES NO FRAMES


ClassPrepareRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface ClassPrepareRequest

All Superinterfaces:
EventRequest, Mirror
public interface ClassPrepareRequest
extends EventRequest

Request for notification when a class is prepared in the target VM. When an enabled ClassPrepareRequest is satisfied, an event set containing a ClassPrepareEvent will be placed on the EventQueue. The collection of existing ClassPrepareRequests is managed by the EventRequestManager

Class preparation is defined in the Java Virtual Machine Specification.

Since:
1.3
See Also:
ClassPrepareEvent, EventQueue, EventRequestManager

Field Summary
Fields inherited from interface com.sun.jdi.request.EventRequest
SUSPEND_ALL, SUSPEND_EVENT_THREAD, SUSPEND_NONE
Method Summary
void | addClassExclusionFilter(String classPattern) Restricts the events generated by this request to the preparation of reference types whose name does not match this restricted regular expression.
void | addClassFilter(ReferenceType refType) Restricts the events generated by this request to be the preparation of the given reference type and any subtypes.
void | addClassFilter(String classPattern) Restricts the events generated by this request to the preparation of reference types whose name matches this restricted regular expression.
void | addSourceNameFilter(String sourceNamePattern) Restricts the events generated by this request to the preparation of reference types for which the restricted regular expression 'sourceNamePattern' matches one of the 'sourceNames' for the reference type being prepared.
Methods inherited from interface com.sun.jdi.request.EventRequest
addCountFilter, disable, enable, getProperty, isEnabled, putProperty, setEnabled, setSuspendPolicy, suspendPolicy
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

addClassFilter

void addClassFilter(ReferenceType refType)
Restricts the events generated by this request to be the preparation of the given reference type and any subtypes. An event will be generated for any prepared reference type that can be safely cast to the given reference type.

Parameters:
refType - the reference type to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(String classPattern)
Restricts the events generated by this request to the preparation of reference types whose name matches this restricted regular expression. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Parameters:
classPattern - the pattern String to filter for.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassExclusionFilter

void addClassExclusionFilter(String classPattern)
Restricts the events generated by this request to the preparation of reference types whose name does not match this restricted regular expression. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Parameters:
classPattern - the pattern String to filter against.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addSourceNameFilter

void addSourceNameFilter(String sourceNamePattern)
Restricts the events generated by this request to the preparation of reference types for which the restricted regular expression 'sourceNamePattern' matches one of the 'sourceNames' for the reference type being prepared. That is, if refType is the ReferenceType being prepared, then there exists at least one stratum, call it 'someStratum' on the list returned by refType.availableStrata(); such that a name on the list returned by refType.sourceNames(someStratam) matches 'sourceNamePattern'. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Not all targets support this operation. Use VirtualMachine.canUseSourceNameFilters() to determine if the operation is supported.

Parameters:
sourceNamePattern - the pattern string to filter for.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.
Since:
1.6
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ClassUnloadRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface ClassUnloadRequest

All Superinterfaces:
EventRequest, Mirror
public interface ClassUnloadRequest
extends EventRequest

Request for notification when a class is unloaded in the target VM. When an enabled ClassUnloadRequest is satisfied, a event set containing an ClassUnloadEvent will be placed on the EventQueue. The collection of existing ClassUnloadRequests is managed by the EventRequestManager

Refer to the Java Virtual Machine Specification for more information on class unloading.

Since:
1.3
See Also:
ClassUnloadEvent, EventQueue, EventRequestManager

Field Summary
Fields inherited from interface com.sun.jdi.request.EventRequest
SUSPEND_ALL, SUSPEND_EVENT_THREAD, SUSPEND_NONE
Method Summary
void | addClassExclusionFilter(String classPattern) Restricts the events generated by this request to the unloading of reference types whose name does not match a restricted regular expression.
void | addClassFilter(String classPattern) Restricts the events generated by this request to the unloading of reference types whose name matches a restricted regular expression.
Methods inherited from interface com.sun.jdi.request.EventRequest
addCountFilter, disable, enable, getProperty, isEnabled, putProperty, setEnabled, setSuspendPolicy, suspendPolicy
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

addClassFilter

void addClassFilter(String classPattern)
Restricts the events generated by this request to the unloading of reference types whose name matches a restricted regular expression. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Parameters:
classPattern - the pattern String to filter for.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassExclusionFilter

void addClassExclusionFilter(String classPattern)
Restricts the events generated by this request to the unloading of reference types whose name does not match a restricted regular expression. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Parameters:
classPattern - the pattern String to filter against.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


DuplicateRequestException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Class DuplicateRequestException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  com.sun.jdi.request.DuplicateRequestException
All Implemented Interfaces:
Serializable
public class DuplicateRequestException
extends RuntimeException

Thrown to indicate a duplicate event request.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
DuplicateRequestException()
DuplicateRequestException(String s)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DuplicateRequestException

public DuplicateRequestException()

DuplicateRequestException

public DuplicateRequestException(String s)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EventRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface EventRequest

All Superinterfaces:
Mirror
All Known Subinterfaces:
AccessWatchpointRequest, BreakpointRequest, ClassPrepareRequest, ClassUnloadRequest, ExceptionRequest, MethodEntryRequest, MethodExitRequest, ModificationWatchpointRequest, MonitorContendedEnteredRequest, MonitorContendedEnterRequest, MonitorWaitedRequest, MonitorWaitRequest, StepRequest, ThreadDeathRequest, ThreadStartRequest, VMDeathRequest, WatchpointRequest
public interface EventRequest
extends Mirror

Represents a request for notification of an event. Examples include BreakpointRequest and ExceptionRequest. When an event occurs for which an enabled request is present, an EventSet will be placed on the EventQueue. The collection of existing event requests is managed by the EventRequestManager.

The number of events generated for an event request can be controlled through filters. Filters provide additional constraints that an event must satisfy before it is placed on the event queue. Multiple filters can be used by making multiple calls to filter addition methods such as ExceptionRequest.addClassFilter(java.lang.String classPattern). Filters are added to an event one at a time only while the event is disabled. Multiple filters are applied with CUT-OFF AND, in the order it was added to the request. Only events that satisfy all filters are placed in the event queue.

The set of available filters is dependent on the event request, some examples of filters are:

  • Thread filters allow control over the thread for which events are generated.
  • Class filters allow control over the class in which the event occurs.
  • Instance filters allow control over the instance in which the event occurs.
  • Count filters allow control over the number of times an event is reported.
Filters can dramatically improve debugger performance by reducing the amount of event traffic sent from the target VM to the debugger VM.

Any method on EventRequest which takes EventRequest as an parameter may throw VMDisconnectedException if the target VM is disconnected and the VMDisconnectEvent has been or is available to be read from the EventQueue.

Any method on EventRequest which takes EventRequest as an parameter may throw VMOutOfMemoryException if the target VM has run out of memory.

Since:
1.3
See Also:
BreakpointEvent, EventQueue, EventRequestManager

Field Summary
static int | SUSPEND_ALL Suspend all threads when the event occurs
static int | SUSPEND_EVENT_THREAD Suspend only the thread which generated the event when the event occurs
static int | SUSPEND_NONE Suspend no threads when the event occurs
Method Summary
void | addCountFilter(int count) Limit the requested event to be reported at most once after a given number of occurrences.
void | disable() Same as setEnabled(false).
void | enable() Same as setEnabled(true).
Object | getProperty(Object key) Returns the value of the property with the specified key.
boolean | isEnabled() Determines if this event request is currently enabled.
void | putProperty(Object key, Object value) Add an arbitrary key/value "property" to this request.
void | setEnabled(boolean val) Enables or disables this event request.
void | setSuspendPolicy(int policy) Determines the threads to suspend when the requested event occurs in the target VM.
int | suspendPolicy() Returns a value which describes the threads to suspend when the requested event occurs in the target VM.
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Field Detail

SUSPEND_NONE

static final int SUSPEND_NONE
Suspend no threads when the event occurs

See Also:
Constant Field Values

SUSPEND_EVENT_THREAD

static final int SUSPEND_EVENT_THREAD
Suspend only the thread which generated the event when the event occurs

See Also:
Constant Field Values

SUSPEND_ALL

static final int SUSPEND_ALL
Suspend all threads when the event occurs

See Also:
Constant Field Values
Method Detail

isEnabled

boolean isEnabled()
Determines if this event request is currently enabled.

Returns:
true if enabled; false otherwise.

setEnabled

void setEnabled(boolean val)
Enables or disables this event request. While this event request is disabled, the event request will be ignored and the target VM will not be stopped if any of its threads reaches the event request. Disabled event requests still exist, and are included in event request lists such as EventRequestManager.breakpointRequests().

Parameters:
val - true if the event request is to be enabled; false otherwise.
Throws:
InvalidRequestStateException - if this request has been deleted.
IllegalThreadStateException - if this is a StepRequest, val is true, and the thread named in the request has died.

enable

void enable()
Same as setEnabled(true).

Throws:
InvalidRequestStateException - if this request has been deleted.
IllegalThreadStateException - if this is a StepRequest and the thread named in the request has died.

disable

void disable()
Same as setEnabled(false).

Throws:
InvalidRequestStateException - if this request has been deleted.

addCountFilter

void addCountFilter(int count)
Limit the requested event to be reported at most once after a given number of occurrences. The event is not reported the first count - 1 times this filter is reached. To request a one-off event, call this method with a count of 1.

Once the count reaches 0, any subsequent filters in this request are applied. If none of those filters cause the event to be suppressed, the event is reported. Otherwise, the event is not reported. In either case subsequent events are never reported for this request.

Parameters:
count - the number of ocurrences before generating an event.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.
IllegalArgumentException - if count is less than one.

setSuspendPolicy

void setSuspendPolicy(int policy)
Determines the threads to suspend when the requested event occurs in the target VM. Use SUSPEND_ALL to suspend all threads in the target VM (the default). Use SUSPEND_EVENT_THREAD to suspend only the thread which generated the event. Use SUSPEND_NONE to suspend no threads.

Thread suspensions through events have the same functionality as explicitly requested suspensions. See ThreadReference.suspend() and VirtualMachine.suspend() for details.

Parameters:
policy - the selected suspend policy.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Suspend policy may only be set in disabled requests.
IllegalArgumentException - if the policy argument contains an illegal value.

suspendPolicy

int suspendPolicy()
Returns a value which describes the threads to suspend when the requested event occurs in the target VM. The returned value is SUSPEND_ALL, SUSPEND_EVENT_THREAD, or SUSPEND_NONE.

Returns:
the current suspend mode for this request

putProperty

void putProperty(Object key,
                 Object value)
Add an arbitrary key/value "property" to this request. The property can be used by a client of the JDI to associate application information with the request; These client-set properties are not used internally by the JDI.

The get/putProperty methods provide access to a small per-instance map. This is not to be confused with Properties.

If value is null this method will remove the property.

See Also:
getProperty(java.lang.Object)

getProperty

Object getProperty(Object key)
Returns the value of the property with the specified key. Only properties added with putProperty(java.lang.Object, java.lang.Object) will return a non-null value.

Returns:
the value of this property or null
See Also:
putProperty(java.lang.Object, java.lang.Object)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


EventRequestManager

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface EventRequestManager

All Superinterfaces:
Mirror
public interface EventRequestManager
extends Mirror

Manages the creation and deletion of EventRequests. A single implementor of this interface exists in a particuar VM and is accessed through VirtualMachine.eventRequestManager()

Since:
1.3
See Also:
EventRequest, Event, BreakpointRequest, BreakpointEvent, VirtualMachine

Method Summary
List<AccessWatchpointRequest> | accessWatchpointRequests() Return an unmodifiable list of the enabled and disabled access watchpoint requests.
List<BreakpointRequest> | breakpointRequests() Return an unmodifiable list of the enabled and disabled breakpoint requests.
List<ClassPrepareRequest> | classPrepareRequests() Return an unmodifiable list of the enabled and disabled class prepare requests.
List<ClassUnloadRequest> | classUnloadRequests() Return an unmodifiable list of the enabled and disabled class unload requests.
AccessWatchpointRequest | createAccessWatchpointRequest(Field field) Creates a new disabled watchpoint which watches accesses to the specified field.
BreakpointRequest | createBreakpointRequest(Location location) Creates a new disabled BreakpointRequest.
ClassPrepareRequest | createClassPrepareRequest() Creates a new disabled ClassPrepareRequest.
ClassUnloadRequest | createClassUnloadRequest() Creates a new disabled ClassUnloadRequest.
ExceptionRequest | createExceptionRequest(ReferenceType refType, boolean notifyCaught, boolean notifyUncaught) Creates a new disabled ExceptionRequest.
MethodEntryRequest | createMethodEntryRequest() Creates a new disabled MethodEntryRequest.
MethodExitRequest | createMethodExitRequest() Creates a new disabled MethodExitRequest.
ModificationWatchpointRequest | createModificationWatchpointRequest(Field field) Creates a new disabled watchpoint which watches accesses to the specified field.
MonitorContendedEnteredRequest | createMonitorContendedEnteredRequest() Creates a new disabled MonitorContendedEnteredRequest.
MonitorContendedEnterRequest | createMonitorContendedEnterRequest() Creates a new disabled MonitorContendedEnterRequest.
MonitorWaitedRequest | createMonitorWaitedRequest() Creates a new disabled MonitorWaitedRequest.
MonitorWaitRequest | createMonitorWaitRequest() Creates a new disabled MonitorWaitRequest.
StepRequest | createStepRequest(ThreadReference thread, int size, int depth) Creates a new disabled StepRequest.
ThreadDeathRequest | createThreadDeathRequest() Creates a new disabled ThreadDeathRequest.
ThreadStartRequest | createThreadStartRequest() Creates a new disabled ThreadStartRequest.
VMDeathRequest | createVMDeathRequest() Creates a new disabled VMDeathRequest.
void | deleteAllBreakpoints() Remove all breakpoints managed by this EventRequestManager.
void | deleteEventRequest(EventRequest eventRequest) Removes an eventRequest.
void | deleteEventRequests(List<? extends EventRequest> eventRequests) Removes a list of EventRequests.
List<ExceptionRequest> | exceptionRequests() Return an unmodifiable list of the enabled and disabled exception requests.
List<MethodEntryRequest> | methodEntryRequests() Return an unmodifiable list of the enabled and disabled method entry requests.
List<MethodExitRequest> | methodExitRequests() Return an unmodifiable list of the enabled and disabled method exit requests.
List<ModificationWatchpointRequest> | modificationWatchpointRequests() Return an unmodifiable list of the enabled and disabled modification watchpoint requests.
List<MonitorContendedEnteredRequest> | monitorContendedEnteredRequests() Return an unmodifiable list of the enabled and disabled monitor contended entered requests.
List<MonitorContendedEnterRequest> | monitorContendedEnterRequests() Return an unmodifiable list of the enabled and disabled monitor contended enter requests.
List<MonitorWaitedRequest> | monitorWaitedRequests() Return an unmodifiable list of the enabled and disabled monitor waited requests.
List<MonitorWaitRequest> | monitorWaitRequests() Return an unmodifiable list of the enabled and disabled monitor wait requests.
List<StepRequest> | stepRequests() Return an unmodifiable list of the enabled and disabled step requests.
List<ThreadDeathRequest> | threadDeathRequests() Return an unmodifiable list of the enabled and disabled thread death requests.
List<ThreadStartRequest> | threadStartRequests() Return an unmodifiable list of the enabled and disabled thread start requests.
List<VMDeathRequest> | vmDeathRequests() Return an unmodifiable list of the enabled and disabled VM death requests.
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

createClassPrepareRequest

ClassPrepareRequest createClassPrepareRequest()
Creates a new disabled ClassPrepareRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.

Returns:
the created ClassPrepareRequest

createClassUnloadRequest

ClassUnloadRequest createClassUnloadRequest()
Creates a new disabled ClassUnloadRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.

Returns:
the created ClassUnloadRequest

createThreadStartRequest

ThreadStartRequest createThreadStartRequest()
Creates a new disabled ThreadStartRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.

Returns:
the created ThreadStartRequest

createThreadDeathRequest

ThreadDeathRequest createThreadDeathRequest()
Creates a new disabled ThreadDeathRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.

Returns:
the created ThreadDeathRequest

createExceptionRequest

ExceptionRequest createExceptionRequest(ReferenceType refType,
                                        boolean notifyCaught,
                                        boolean notifyUncaught)
Creates a new disabled ExceptionRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.

A specific exception type and its subclasses can be selected for exception events. Caught exceptions, uncaught exceptions, or both can be selected. Note, however, that at the time an exception is thrown, it is not always possible to determine whether it is truly caught. See ExceptionEvent.catchLocation() for details.

Parameters:
refType - If non-null, specifies that exceptions which are instances of refType will be reported. Note: this will include instances of sub-types. If null, all instances will be reported
notifyCaught - If true, caught exceptions will be reported.
notifyUncaught - If true, uncaught exceptions will be reported.
Returns:
the created ExceptionRequest

createMethodEntryRequest

MethodEntryRequest createMethodEntryRequest()
Creates a new disabled MethodEntryRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.

Returns:
the created MethodEntryRequest

createMethodExitRequest

MethodExitRequest createMethodExitRequest()
Creates a new disabled MethodExitRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.

Returns:
the created MethodExitRequest

createMonitorContendedEnterRequest

MonitorContendedEnterRequest createMonitorContendedEnterRequest()
Creates a new disabled MonitorContendedEnterRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request. Not all target virtual machines support this operation. Use VirtualMachine.canRequestMonitorEvents() to determine if the operation is supported.

Returns:
the created MonitorContendedEnterRequest
Throws:
UnsupportedOperationException - if the target VM does not support this operation.
Since:
1.6

createMonitorContendedEnteredRequest

MonitorContendedEnteredRequest createMonitorContendedEnteredRequest()
Creates a new disabled MonitorContendedEnteredRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request. Not all target virtual machines support this operation. Use VirtualMachine.canRequestMonitorEvents() to determine if the operation is supported.

Returns:
the created MonitorContendedEnteredRequest
Throws:
UnsupportedOperationException - if the target VM does not support this operation.
Since:
1.6

createMonitorWaitRequest

MonitorWaitRequest createMonitorWaitRequest()
Creates a new disabled MonitorWaitRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request. Not all target virtual machines support this operation. Use VirtualMachine.canRequestMonitorEvents() to determine if the operation is supported.

Returns:
the created MonitorWaitRequest
Throws:
UnsupportedOperationException - if the target VM does not support this operation.
Since:
1.6

createMonitorWaitedRequest

MonitorWaitedRequest createMonitorWaitedRequest()
Creates a new disabled MonitorWaitedRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request. Not all target virtual machines support this operation. Use VirtualMachine.canRequestMonitorEvents() to determine if the operation is supported.

Returns:
the created MonitorWaitedRequest
Throws:
UnsupportedOperationException - if the target VM does not support this operation.
Since:
1.6

createStepRequest

StepRequest createStepRequest(ThreadReference thread,
                              int size,
                              int depth)
Creates a new disabled StepRequest. The new event request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.

The returned request will control stepping only in the specified thread; all other threads will be unaffected. A sizevalue of StepRequest.STEP_MIN will generate a step event each time the code index changes. It represents the smallest step size available and often maps to the instruction level. A size value of StepRequest.STEP_LINE will generate a step event each time the source line changes unless line number information is not available, in which case a STEP_MIN will be done instead. For example, no line number information is available during the execution of a method that has been rendered obsolete by by a VirtualMachine.redefineClasses(java.util.Map) operation. A depth value of StepRequest.STEP_INTO will generate step events in any called methods. A depth value of StepRequest.STEP_OVER restricts step events to the current frame or caller frames. A depth value of StepRequest.STEP_OUT restricts step events to caller frames only. All depth restrictions are relative to the call stack immediately before the step takes place.

Only one pending step request is allowed per thread.

Note that a typical debugger will want to cancel stepping after the first step is detected. Thus a next line method would do the following:

     EventRequestManager mgr = myVM.eventRequestManager();
     StepRequest request = mgr.createStepRequest(myThread,
                                                 StepRequest.STEP_LINE,
                                                 StepRequest.STEP_OVER);
     request.addCountFilter(1);  // next step only
     request.enable();
     myVM.resume();

Parameters:
thread - the thread in which to step
depth - the step depth
size - the step size
Returns:
the created StepRequest
Throws:
DuplicateRequestException - if there is already a pending step request for the specified thread.
IllegalArgumentException - if the size or depth arguments contain illegal values.

createBreakpointRequest

BreakpointRequest createBreakpointRequest(Location location)
Creates a new disabled BreakpointRequest. The given Location must have a valid (that is, non-negative) code index. The new breakpoint is added to the list managed by this EventRequestManager. Multiple breakpoints at the same location are permitted. Use EventRequest.enable() to activate this event request.

Parameters:
location - the location of the new breakpoint.
Returns:
the created BreakpointRequest
Throws:
NativeMethodException - if location is within a native method.

createAccessWatchpointRequest

AccessWatchpointRequest createAccessWatchpointRequest(Field field)
Creates a new disabled watchpoint which watches accesses to the specified field. The new watchpoint is added to the list managed by this EventRequestManager. Multiple watchpoints on the same field are permitted. Use EventRequest.enable() to activate this event request.

Not all target virtual machines support this operation. Use VirtualMachine.canWatchFieldAccess() to determine if the operation is supported.

Parameters:
field - the field to watch
Returns:
the created watchpoint
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.

createModificationWatchpointRequest

ModificationWatchpointRequest createModificationWatchpointRequest(Field field)
Creates a new disabled watchpoint which watches accesses to the specified field. The new watchpoint is added to the list managed by this EventRequestManager. Multiple watchpoints on the same field are permitted. Use EventRequest.enable() to activate this event request.

Not all target virtual machines support this operation. Use VirtualMachine.canWatchFieldModification() to determine if the operation is supported.

Parameters:
field - the field to watch
Returns:
the created watchpoint
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.

createVMDeathRequest

VMDeathRequest createVMDeathRequest()
Creates a new disabled VMDeathRequest. The new request is added to the list managed by this EventRequestManager. Use EventRequest.enable() to activate this event request.

This request (if enabled) will cause a VMDeathEvent to be sent on termination of the target VM.

A VMDeathRequest with a suspend policy of SUSPEND_ALL can be used to assure processing of incoming SUSPEND_NONE or SUSPEND_EVENT_THREAD events before VM death. If all event processing is being done in the same thread as event sets are being read, enabling the request is all that is needed since the VM will be suspended until the EventSet containing the VMDeathEvent is resumed.

Not all target virtual machines support this operation. Use VirtualMachine.canRequestVMDeathEvent() to determine if the operation is supported.

Returns:
the created request
Throws:
UnsupportedOperationException - if the target VM does not support this operation.
Since:
1.4

deleteEventRequest

void deleteEventRequest(EventRequest eventRequest)
Removes an eventRequest. The eventRequest is disabled and the removed from the requests managed by this EventRequestManager. Once the eventRequest is deleted, no operations (for example, EventRequest.setEnabled(boolean)) are permitted - attempts to do so will generally cause an InvalidRequestStateException. No other eventRequests are effected.

Because this method changes the underlying lists of event requests, attempting to directly delete from a list returned by a request accessor (e.g. below):

   Iterator iter = requestManager.stepRequests().iterator();
   while (iter.hasNext()) {
      requestManager.deleteEventRequest(iter.next());
  }
may cause a ConcurrentModificationException. Instead use deleteEventRequests(List) or copy the list before iterating.

Parameters:
eventRequest - the eventRequest to remove

deleteEventRequests

void deleteEventRequests(List<? extends EventRequest> eventRequests)
Removes a list of EventRequests.

Parameters:
eventRequests - the list of eventRequests to remove
See Also:
deleteEventRequest(EventRequest)

deleteAllBreakpoints

void deleteAllBreakpoints()
Remove all breakpoints managed by this EventRequestManager.

See Also:
deleteEventRequest(EventRequest)

stepRequests

List<StepRequest> stepRequests()
Return an unmodifiable list of the enabled and disabled step requests. This list is a live view of these requests and thus changes as requests are added and deleted.

Returns:
the all StepRequest objects.

classPrepareRequests

List<ClassPrepareRequest> classPrepareRequests()
Return an unmodifiable list of the enabled and disabled class prepare requests. This list is a live view of these requests and thus changes as requests are added and deleted.

Returns:
the all ClassPrepareRequest objects.

classUnloadRequests

List<ClassUnloadRequest> classUnloadRequests()
Return an unmodifiable list of the enabled and disabled class unload requests. This list is a live view of these requests and thus changes as requests are added and deleted.

Returns:
the all ClassUnloadRequest objects.

threadStartRequests

List<ThreadStartRequest> threadStartRequests()
Return an unmodifiable list of the enabled and disabled thread start requests. This list is a live view of these requests and thus changes as requests are added and deleted.

Returns:
the all ThreadStartRequest objects.

threadDeathRequests

List<ThreadDeathRequest> threadDeathRequests()
Return an unmodifiable list of the enabled and disabled thread death requests. This list is a live view of these requests and thus changes as requests are added and deleted.

Returns:
the all ThreadDeathRequest objects.

exceptionRequests

List<ExceptionRequest> exceptionRequests()
Return an unmodifiable list of the enabled and disabled exception requests. This list is a live view of these requests and thus changes as requests are added and deleted.

Returns:
the all ExceptionRequest objects.

breakpointRequests

List<BreakpointRequest> breakpointRequests()
Return an unmodifiable list of the enabled and disabled breakpoint requests. This list is a live view of these requests and thus changes as requests are added and deleted.

Returns:
the list of all BreakpointRequest objects.

accessWatchpointRequests

List<AccessWatchpointRequest> accessWatchpointRequests()
Return an unmodifiable list of the enabled and disabled access watchpoint requests. This list is a live view of these requests and thus changes as requests are added and deleted.

Returns:
the all AccessWatchpointRequest objects.

modificationWatchpointRequests

List<ModificationWatchpointRequest> modificationWatchpointRequests()
Return an unmodifiable list of the enabled and disabled modification watchpoint requests. This list is a live view of these requests and thus changes as requests are added and deleted.

Returns:
the all ModificationWatchpointRequest objects.

methodEntryRequests

List<MethodEntryRequest> methodEntryRequests()
Return an unmodifiable list of the enabled and disabled method entry requests. This list is a live view of these requests and thus changes as requests are added and deleted.

Returns:
the list of all MethodEntryRequest objects.

methodExitRequests

List<MethodExitRequest> methodExitRequests()
Return an unmodifiable list of the enabled and disabled method exit requests. This list is a live view of these requests and thus changes as requests are added and deleted.

Returns:
the list of all MethodExitRequest objects.

monitorContendedEnterRequests

List<MonitorContendedEnterRequest> monitorContendedEnterRequests()
Return an unmodifiable list of the enabled and disabled monitor contended enter requests. This list is a live view of these requests and thus changes as requests are added and deleted.

Returns:
the list of all MonitorContendedEnterRequest objects.
Since:
1.6

monitorContendedEnteredRequests

List<MonitorContendedEnteredRequest> monitorContendedEnteredRequests()
Return an unmodifiable list of the enabled and disabled monitor contended entered requests. This list is a live view of these requests and thus changes as requests are added and deleted.

Returns:
the list of all MonitorContendedEnteredRequest objects.
Since:
1.6

monitorWaitRequests

List<MonitorWaitRequest> monitorWaitRequests()
Return an unmodifiable list of the enabled and disabled monitor wait requests. This list is a live view of these requests and thus changes as requests are added and deleted.

Returns:
the list of all MonitorWaitRequest objects.
Since:
1.6

monitorWaitedRequests

List<MonitorWaitedRequest> monitorWaitedRequests()
Return an unmodifiable list of the enabled and disabled monitor waited requests. This list is a live view of these requests and thus changes as requests are added and deleted.

Returns:
the list of all MonitorWaitedRequest objects.
Since:
1.6

vmDeathRequests

List<VMDeathRequest> vmDeathRequests()
Return an unmodifiable list of the enabled and disabled VM death requests. This list is a live view of these requests and thus changes as requests are added and deleted. Note: the unsolicited VMDeathEvent does not have a corresponding request.

Returns:
the list of all VMDeathRequest objects.
Since:
1.4
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ExceptionRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface ExceptionRequest

All Superinterfaces:
EventRequest, Mirror
public interface ExceptionRequest
extends EventRequest

Request for notification when an exception occurs in the target VM. When an enabled ExceptionRequest is satisfied, an event set containing an ExceptionEvent will be placed on the EventQueue. The collection of existing ExceptionRequests is managed by the EventRequestManager

Since:
1.3
See Also:
ExceptionEvent, EventQueue, EventRequestManager

Field Summary
Fields inherited from interface com.sun.jdi.request.EventRequest
SUSPEND_ALL, SUSPEND_EVENT_THREAD, SUSPEND_NONE
Method Summary
void | addClassExclusionFilter(String classPattern) Restricts the events generated by this request to those whose location is in a class whose name does not match a restricted regular expression.
void | addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose location is in the given reference type or any of its subtypes.
void | addClassFilter(String classPattern) Restricts the events generated by this request to those whose location is in a class whose name matches a restricted regular expression.
void | addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
void | addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
ReferenceType | exception() Returns exception type for which exception events are requested.
boolean | notifyCaught() Returns whether caught exceptions of the requested type will generate events when they are thrown.
boolean | notifyUncaught() Returns whether uncaught exceptions of the requested type will generate events when they are thrown.
Methods inherited from interface com.sun.jdi.request.EventRequest
addCountFilter, disable, enable, getProperty, isEnabled, putProperty, setEnabled, setSuspendPolicy, suspendPolicy
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

exception

ReferenceType exception()
Returns exception type for which exception events are requested.

Returns:
The exception (and its subclasses) requested with EventRequestManager.createExceptionRequest(com.sun.jdi.ReferenceType, boolean, boolean), or null if, as by default, all exceptions are requested.

notifyCaught

boolean notifyCaught()
Returns whether caught exceptions of the requested type will generate events when they are thrown.

Note that at the time an exception is thrown, it is not always possible to determine whether it is truly caught. See ExceptionEvent.catchLocation() for details.

Returns:
boolean true if caught exceptions will be reported, false otherwise.

notifyUncaught

boolean notifyUncaught()
Returns whether uncaught exceptions of the requested type will generate events when they are thrown.

Note that at the time an exception is thrown, it is not always possible to determine whether it is truly uncaught. See ExceptionEvent.catchLocation() for details.

Returns:
boolean true if caught exceptions will be reported, false otherwise.

addThreadFilter

void addThreadFilter(ThreadReference thread)
Restricts the events generated by this request to those in the given thread.

Parameters:
thread - the thread to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(ReferenceType refType)
Restricts the events generated by this request to those whose location is in the given reference type or any of its subtypes. An event will be generated for any location in a reference type that can be safely cast to the given reference type.

Parameters:
refType - the reference type to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(String classPattern)
Restricts the events generated by this request to those whose location is in a class whose name matches a restricted regular expression. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Parameters:
classPattern - the pattern String to filter for.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassExclusionFilter

void addClassExclusionFilter(String classPattern)
Restricts the events generated by this request to those whose location is in a class whose name does not match a restricted regular expression. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Parameters:
classPattern - the pattern String to filter against.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addInstanceFilter

void addInstanceFilter(ObjectReference instance)
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.

Not all targets support this operation. Use VirtualMachine.canUseInstanceFilters() to determine if the operation is supported.

Parameters:
instance - the object which must be the current instance in order to pass this filter.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.
Since:
1.4
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


InvalidRequestStateException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Class InvalidRequestStateException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  com.sun.jdi.request.InvalidRequestStateException
All Implemented Interfaces:
Serializable
public class InvalidRequestStateException
extends RuntimeException

Thrown to indicate that the requested event cannot be modified because it is enabled. Filters can be added only to disabled event requests. Also thrown if an operation is attempted on a deleted request. See EventRequestManager.deleteEventRequest(EventRequest)

Since:
1.3
See Also:
Serialized Form

Constructor Summary
InvalidRequestStateException()
InvalidRequestStateException(String s)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

InvalidRequestStateException

public InvalidRequestStateException()

InvalidRequestStateException

public InvalidRequestStateException(String s)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MethodEntryRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface MethodEntryRequest

All Superinterfaces:
EventRequest, Mirror
public interface MethodEntryRequest
extends EventRequest

Request for notification when a method is invoked in the target VM. When an enabled MethodEntryRequest is satisfied, an event set containing a MethodEntryEvent will be placed on the EventQueue. The collection of existing MethodEntryRequests is managed by the EventRequestManager

Since:
1.3
See Also:
MethodEntryEvent, EventQueue, EventRequestManager

Field Summary
Fields inherited from interface com.sun.jdi.request.EventRequest
SUSPEND_ALL, SUSPEND_EVENT_THREAD, SUSPEND_NONE
Method Summary
void | addClassExclusionFilter(String classPattern) Restricts the events generated by this request to those whose method is in a class whose name does not match this restricted regular expression, e.g.
void | addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose method is in the given reference type or any of its subtypes.
void | addClassFilter(String classPattern) Restricts the events generated by this request to those whose method is in a class whose name matches this restricted regular expression.
void | addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
void | addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
Methods inherited from interface com.sun.jdi.request.EventRequest
addCountFilter, disable, enable, getProperty, isEnabled, putProperty, setEnabled, setSuspendPolicy, suspendPolicy
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

addThreadFilter

void addThreadFilter(ThreadReference thread)
Restricts the events generated by this request to those in the given thread.

Parameters:
thread - the thread to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(ReferenceType refType)
Restricts the events generated by this request to those whose method is in the given reference type or any of its subtypes. An event will be generated for any location in a reference type that can be safely cast to the given reference type.

Parameters:
refType - the reference type to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(String classPattern)
Restricts the events generated by this request to those whose method is in a class whose name matches this restricted regular expression. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Parameters:
classPattern - the pattern String to filter for.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassExclusionFilter

void addClassExclusionFilter(String classPattern)
Restricts the events generated by this request to those whose method is in a class whose name does not match this restricted regular expression, e.g. "java.*" or "*.Foo".

Parameters:
classPattern - the pattern String to filter against.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addInstanceFilter

void addInstanceFilter(ObjectReference instance)
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.

Not all targets support this operation. Use VirtualMachine.canUseInstanceFilters() to determine if the operation is supported.

Parameters:
instance - the object which must be the current instance in order to pass this filter.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.
Since:
1.4
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MethodExitRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface MethodExitRequest

All Superinterfaces:
EventRequest, Mirror
public interface MethodExitRequest
extends EventRequest

Request for notification when a method returns in the target VM. When an enabled MethodExitRequest is hit, an event set containing a MethodExitEvent will be placed on the EventQueue. The collection of existing MethodExitRequests is managed by the EventRequestManager

Since:
1.3
See Also:
MethodExitEvent, EventQueue, EventRequestManager

Field Summary
Fields inherited from interface com.sun.jdi.request.EventRequest
SUSPEND_ALL, SUSPEND_EVENT_THREAD, SUSPEND_NONE
Method Summary
void | addClassExclusionFilter(String classPattern) Restricts the events generated by this request to those whose method is in a class whose name does not match this restricted regular expression.
void | addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose method is in the given reference type or any of its subtypes.
void | addClassFilter(String classPattern) Restricts the events generated by this request to those whose method is in a class whose name matches a restricted regular expression.
void | addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
void | addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
Methods inherited from interface com.sun.jdi.request.EventRequest
addCountFilter, disable, enable, getProperty, isEnabled, putProperty, setEnabled, setSuspendPolicy, suspendPolicy
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

addThreadFilter

void addThreadFilter(ThreadReference thread)
Restricts the events generated by this request to those in the given thread.

Parameters:
thread - the thread to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(ReferenceType refType)
Restricts the events generated by this request to those whose method is in the given reference type or any of its subtypes. An event will be generated for any location in a reference type that can be safely cast to the given reference type.

Parameters:
refType - the reference type to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(String classPattern)
Restricts the events generated by this request to those whose method is in a class whose name matches a restricted regular expression. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Parameters:
classPattern - the pattern String to filter for.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassExclusionFilter

void addClassExclusionFilter(String classPattern)
Restricts the events generated by this request to those whose method is in a class whose name does not match this restricted regular expression. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Parameters:
classPattern - the pattern String to filter against.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addInstanceFilter

void addInstanceFilter(ObjectReference instance)
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.

Not all targets support this operation. Use VirtualMachine.canUseInstanceFilters() to determine if the operation is supported.

Parameters:
instance - the object which must be the current instance in order to pass this filter.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.
Since:
1.4
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MonitorContendedEnteredRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface MonitorContendedEnteredRequest

All Superinterfaces:
EventRequest, Mirror
public interface MonitorContendedEnteredRequest
extends EventRequest

Request for notification of a thread in the target VM entering a monitor after waiting for it to be released by another thread. When an enabled MonitorContededEnteredRequest is satisfied, an event set containing a MonitorContendedEnteredEvent will be placed on the EventQueue. The collection of existing MonitorContendedEnteredEvents is managed by the EventRequestManager

Since:
1.6
See Also:
MonitorContendedEnteredEvent, EventQueue, EventRequestManager

Field Summary
Fields inherited from interface com.sun.jdi.request.EventRequest
SUSPEND_ALL, SUSPEND_EVENT_THREAD, SUSPEND_NONE
Method Summary
void | addClassExclusionFilter(String classPattern) Restricts the events generated by this request to those whose method is in a class whose name does not match this restricted regular expression, e.g.
void | addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose method is in the given reference type or any of its subtypes.
void | addClassFilter(String classPattern) Restricts the events generated by this request to those whose method is in a class whose name matches this restricted regular expression.
void | addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
void | addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
Methods inherited from interface com.sun.jdi.request.EventRequest
addCountFilter, disable, enable, getProperty, isEnabled, putProperty, setEnabled, setSuspendPolicy, suspendPolicy
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

addThreadFilter

void addThreadFilter(ThreadReference thread)
Restricts the events generated by this request to those in the given thread.

Parameters:
thread - the thread to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(ReferenceType refType)
Restricts the events generated by this request to those whose method is in the given reference type or any of its subtypes. An event will be generated for any location in a reference type that can be safely cast to the given reference type.

Parameters:
refType - the reference type to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(String classPattern)
Restricts the events generated by this request to those whose method is in a class whose name matches this restricted regular expression. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Parameters:
classPattern - the pattern String to filter for.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassExclusionFilter

void addClassExclusionFilter(String classPattern)
Restricts the events generated by this request to those whose method is in a class whose name does not match this restricted regular expression, e.g. "java.*" or "*.Foo".

Parameters:
classPattern - the pattern String to filter against.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addInstanceFilter

void addInstanceFilter(ObjectReference instance)
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.

Not all targets support this operation. Use VirtualMachine.canUseInstanceFilters() to determine if the operation is supported.

Parameters:
instance - the object which must be the current instance in order to pass this filter.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MonitorContendedEnterRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface MonitorContendedEnterRequest

All Superinterfaces:
EventRequest, Mirror
public interface MonitorContendedEnterRequest
extends EventRequest

Request for notification of a thread in the target VM attempting to enter a monitor already acquired by another thread. When an enabled MonitorContededEnterRequest is satisfied, an event set containing a MonitorContendedEnterEvent will be placed on the EventQueue. The collection of existing MonitorContendedEnterEvents is managed by the EventRequestManager

Since:
1.6
See Also:
MonitorContendedEnterEvent, EventQueue, EventRequestManager

Field Summary
Fields inherited from interface com.sun.jdi.request.EventRequest
SUSPEND_ALL, SUSPEND_EVENT_THREAD, SUSPEND_NONE
Method Summary
void | addClassExclusionFilter(String classPattern) Restricts the events generated by this request to those whose method is in a class whose name does not match this restricted regular expression, e.g.
void | addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose method is in the given reference type or any of its subtypes.
void | addClassFilter(String classPattern) Restricts the events generated by this request to those whose method is in a class whose name matches this restricted regular expression.
void | addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
void | addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
Methods inherited from interface com.sun.jdi.request.EventRequest
addCountFilter, disable, enable, getProperty, isEnabled, putProperty, setEnabled, setSuspendPolicy, suspendPolicy
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

addThreadFilter

void addThreadFilter(ThreadReference thread)
Restricts the events generated by this request to those in the given thread.

Parameters:
thread - the thread to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(ReferenceType refType)
Restricts the events generated by this request to those whose method is in the given reference type or any of its subtypes. An event will be generated for any location in a reference type that can be safely cast to the given reference type.

Parameters:
refType - the reference type to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(String classPattern)
Restricts the events generated by this request to those whose method is in a class whose name matches this restricted regular expression. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Parameters:
classPattern - the pattern String to filter for.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassExclusionFilter

void addClassExclusionFilter(String classPattern)
Restricts the events generated by this request to those whose method is in a class whose name does not match this restricted regular expression, e.g. "java.*" or "*.Foo".

Parameters:
classPattern - the pattern String to filter against.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addInstanceFilter

void addInstanceFilter(ObjectReference instance)
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.

Not all targets support this operation. Use VirtualMachine.canUseInstanceFilters() to determine if the operation is supported.

Parameters:
instance - the object which must be the current instance in order to pass this filter.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MonitorWaitedRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface MonitorWaitedRequest

All Superinterfaces:
EventRequest, Mirror
public interface MonitorWaitedRequest
extends EventRequest

Request for notification when a thread in the target VM has finished waiting on a monitor object. That is, a thread is leaving Object.wait(). " When an enabled MonitorWaitedRequest is satisfied, an event set containing a MonitorWaitedEvent will be placed on the EventQueue. The collection of existing MonitorWaitedEvents is managed by the EventRequestManager

Since:
1.6
See Also:
MonitorWaitedEvent, EventQueue, EventRequestManager

Field Summary
Fields inherited from interface com.sun.jdi.request.EventRequest
SUSPEND_ALL, SUSPEND_EVENT_THREAD, SUSPEND_NONE
Method Summary
void | addClassExclusionFilter(String classPattern) Restricts the events generated by this request to those in which the name of the class of the monitor object does notmatch this restricted regular expression, e.g.
void | addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose monitor object is of the given reference type or any of its subtypes.
void | addClassFilter(String classPattern) Restricts the events generated by this request to those in which the name of the class of the monitor object matches this restricted regular expression.
void | addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
void | addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
Methods inherited from interface com.sun.jdi.request.EventRequest
addCountFilter, disable, enable, getProperty, isEnabled, putProperty, setEnabled, setSuspendPolicy, suspendPolicy
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

addThreadFilter

void addThreadFilter(ThreadReference thread)
Restricts the events generated by this request to those in the given thread.

Parameters:
thread - the thread to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(ReferenceType refType)
Restricts the events generated by this request to those whose monitor object is of the given reference type or any of its subtypes.

Parameters:
refType - the reference type to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(String classPattern)
Restricts the events generated by this request to those in which the name of the class of the monitor object matches this restricted regular expression. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Parameters:
classPattern - the pattern String to filter for.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassExclusionFilter

void addClassExclusionFilter(String classPattern)
Restricts the events generated by this request to those in which the name of the class of the monitor object does notmatch this restricted regular expression, e.g. "java.*" or "*.Foo".

Parameters:
classPattern - the pattern String to filter against.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addInstanceFilter

void addInstanceFilter(ObjectReference instance)
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.

Not all targets support this operation. Use VirtualMachine.canUseInstanceFilters() to determine if the operation is supported.

Parameters:
instance - the object which must be the current instance in order to pass this filter.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


MonitorWaitRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface MonitorWaitRequest

All Superinterfaces:
EventRequest, Mirror
public interface MonitorWaitRequest
extends EventRequest

Request for notification when a thread in the target VM is about to wait on a monitor object. That is, a thread is entering Object.wait(). When an enabled MonitorWaitRequest is satisfied, an event set containing a MonitorWaitEvent will be placed on the EventQueue. The collection of existing MonitorWaitEvents is managed by the EventRequestManager

Since:
1.6
See Also:
MonitorWaitEvent, EventQueue, EventRequestManager

Field Summary
Fields inherited from interface com.sun.jdi.request.EventRequest
SUSPEND_ALL, SUSPEND_EVENT_THREAD, SUSPEND_NONE
Method Summary
void | addClassExclusionFilter(String classPattern) Restricts the events generated by this request to those in which the name of the class of the monitor object does notmatch this restricted regular expression, e.g.
void | addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose monitor object is of the given reference type or any of its subtypes.
void | addClassFilter(String classPattern) Restricts the events generated by this request to those in which the name of the class of the monitor object matches this restricted regular expression.
void | addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
void | addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
Methods inherited from interface com.sun.jdi.request.EventRequest
addCountFilter, disable, enable, getProperty, isEnabled, putProperty, setEnabled, setSuspendPolicy, suspendPolicy
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

addThreadFilter

void addThreadFilter(ThreadReference thread)
Restricts the events generated by this request to those in the given thread.

Parameters:
thread - the thread to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(ReferenceType refType)
Restricts the events generated by this request to those whose monitor object is of the given reference type or any of its subtypes.

Parameters:
refType - the reference type to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(String classPattern)
Restricts the events generated by this request to those in which the name of the class of the monitor object matches this restricted regular expression. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Parameters:
classPattern - the pattern String to filter for.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassExclusionFilter

void addClassExclusionFilter(String classPattern)
Restricts the events generated by this request to those in which the name of the class of the monitor object does notmatch this restricted regular expression, e.g. "java.*" or "*.Foo".

Parameters:
classPattern - the pattern String to filter against.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addInstanceFilter

void addInstanceFilter(ObjectReference instance)
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.

Not all targets support this operation. Use VirtualMachine.canUseInstanceFilters() to determine if the operation is supported.

Parameters:
instance - the object which must be the current instance in order to pass this filter.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StepRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface StepRequest

All Superinterfaces:
EventRequest, Mirror
public interface StepRequest
extends EventRequest

Request for notification when a step occurs in the target VM. When an enabled StepRequest is satisfied, an event set containing a StepEvent will be placed on the EventQueue. The collection of existing StepRequests is managed by the EventRequestManager

Since:
1.3
See Also:
StepEvent, EventQueue, EventRequestManager

Field Summary
static int | STEP_INTO Step into any newly pushed frames
static int | STEP_LINE Step to the next location on a different line
static int | STEP_MIN Step to the next available location
static int | STEP_OUT Step out of the current frame
static int | STEP_OVER Step over any newly pushed frames
Fields inherited from interface com.sun.jdi.request.EventRequest
SUSPEND_ALL, SUSPEND_EVENT_THREAD, SUSPEND_NONE
Method Summary
void | addClassExclusionFilter(String classPattern) Restricts the events generated by this request to those whose location is in a class whose name does not match a restricted regular expression.
void | addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose location is in the given reference type or any of its subtypes.
void | addClassFilter(String classPattern) Restricts the events generated by this request to those whose location is in a class whose name matches a restricted regular expression.
void | addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
int | depth()
int | size()
ThreadReference | thread()
Methods inherited from interface com.sun.jdi.request.EventRequest
addCountFilter, disable, enable, getProperty, isEnabled, putProperty, setEnabled, setSuspendPolicy, suspendPolicy
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Field Detail

STEP_INTO

static final int STEP_INTO
Step into any newly pushed frames

See Also:
Constant Field Values

STEP_OVER

static final int STEP_OVER
Step over any newly pushed frames

See Also:
Constant Field Values

STEP_OUT

static final int STEP_OUT
Step out of the current frame

See Also:
Constant Field Values

STEP_MIN

static final int STEP_MIN
Step to the next available location

See Also:
Constant Field Values

STEP_LINE

static final int STEP_LINE
Step to the next location on a different line

See Also:
Constant Field Values
Method Detail

thread

ThreadReference thread()
Returns:
the thread on which the step event is being requested.

size

int size()
Returns:
the step size

depth

int depth()
Returns:
the step depth

addClassFilter

void addClassFilter(ReferenceType refType)
Restricts the events generated by this request to those whose location is in the given reference type or any of its subtypes. An event will be generated for any location in a reference type that can be safely cast to the given reference type.

Parameters:
refType - the reference type to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(String classPattern)
Restricts the events generated by this request to those whose location is in a class whose name matches a restricted regular expression. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Parameters:
classPattern - the pattern String to filter for.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassExclusionFilter

void addClassExclusionFilter(String classPattern)
Restricts the events generated by this request to those whose location is in a class whose name does not match a restricted regular expression. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Parameters:
classPattern - the pattern String to filter against.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addInstanceFilter

void addInstanceFilter(ObjectReference instance)
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.

Not all targets support this operation. Use VirtualMachine.canUseInstanceFilters() to determine if the operation is supported.

Parameters:
instance - the object which must be the current instance in order to pass this filter.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.
Since:
1.4
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ThreadDeathRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface ThreadDeathRequest

All Superinterfaces:
EventRequest, Mirror
public interface ThreadDeathRequest
extends EventRequest

Request for notification when a thread terminates in the target VM. When an enabled ThreadDeathRequest is satisfied, an event set containing a ThreadDeathEvent will be placed on the EventQueue. The collection of existing ThreadDeathRequests is managed by the EventRequestManager

Since:
1.3
See Also:
ThreadDeathEvent, EventQueue, EventRequestManager

Field Summary
Fields inherited from interface com.sun.jdi.request.EventRequest
SUSPEND_ALL, SUSPEND_EVENT_THREAD, SUSPEND_NONE
Method Summary
 void addThreadFilter(ThreadReference thread)
Restricts the events generated by this request to those in the given thread.
Methods inherited from interface com.sun.jdi.request.EventRequest
addCountFilter, disable, enable, getProperty, isEnabled, putProperty, setEnabled, setSuspendPolicy, suspendPolicy
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

addThreadFilter

void addThreadFilter(ThreadReference thread)
Restricts the events generated by this request to those in the given thread.

Parameters:
thread - the thread to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ThreadStartRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface ThreadStartRequest

All Superinterfaces:
EventRequest, Mirror
public interface ThreadStartRequest
extends EventRequest

Request for notification when a thread starts execution in the target VM. When an enabled ThreadStartRequest is hit, an event set containing a ThreadStartEvent will be placed on the EventQueue. The collection of existing ThreadStartRequests is managed by the EventRequestManager

Since:
1.3
See Also:
ThreadStartEvent, EventQueue, EventRequestManager

Field Summary
Fields inherited from interface com.sun.jdi.request.EventRequest
SUSPEND_ALL, SUSPEND_EVENT_THREAD, SUSPEND_NONE
Method Summary
 void addThreadFilter(ThreadReference thread)
Restricts the events generated by this request to those in the given thread.
Methods inherited from interface com.sun.jdi.request.EventRequest
addCountFilter, disable, enable, getProperty, isEnabled, putProperty, setEnabled, setSuspendPolicy, suspendPolicy
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

addThreadFilter

void addThreadFilter(ThreadReference thread)
Restricts the events generated by this request to those in the given thread.

Parameters:
thread - the thread to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


WatchpointRequest

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi.request
Interface WatchpointRequest

All Superinterfaces:
EventRequest, Mirror
All Known Subinterfaces:
AccessWatchpointRequest, ModificationWatchpointRequest
public interface WatchpointRequest
extends EventRequest

Identifies a Field in the target VM being watched.

Since:
1.3
See Also:
AccessWatchpointRequest, ModificationWatchpointRequest, EventQueue, EventRequestManager

Field Summary
Fields inherited from interface com.sun.jdi.request.EventRequest
SUSPEND_ALL, SUSPEND_EVENT_THREAD, SUSPEND_NONE
Method Summary
void | addClassExclusionFilter(String classPattern) Restricts the events generated by this request to those whose location is in a class whose name does not match this restricted regular expression.
void | addClassFilter(ReferenceType refType) Restricts the events generated by this request to those whose location is in the given reference type or any of its subtypes.
void | addClassFilter(String classPattern) Restricts the events generated by this request to those whose location is in a class whose name matches a restricted regular expression.
void | addInstanceFilter(ObjectReference instance) Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.
void | addThreadFilter(ThreadReference thread) Restricts the events generated by this request to those in the given thread.
Field | field() Gets the Field being watched by this WatchpointRequest.
Methods inherited from interface com.sun.jdi.request.EventRequest
addCountFilter, disable, enable, getProperty, isEnabled, putProperty, setEnabled, setSuspendPolicy, suspendPolicy
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

field

Field field()
Gets the Field being watched by this WatchpointRequest.

Returns:
the Field this Watchpoint is monitoring.

addThreadFilter

void addThreadFilter(ThreadReference thread)
Restricts the events generated by this request to those in the given thread.

Parameters:
thread - the thread to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(ReferenceType refType)
Restricts the events generated by this request to those whose location is in the given reference type or any of its subtypes. An event will be generated for any location in a reference type that can be safely cast to the given reference type.

Parameters:
refType - the reference type to filter on.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassFilter

void addClassFilter(String classPattern)
Restricts the events generated by this request to those whose location is in a class whose name matches a restricted regular expression. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Parameters:
classPattern - the pattern String to filter for.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addClassExclusionFilter

void addClassExclusionFilter(String classPattern)
Restricts the events generated by this request to those whose location is in a class whose name does not match this restricted regular expression. Regular expressions are limited to exact matches and patterns that begin with '*' or end with '*'; for example, "*.Foo" or "java.*".

Parameters:
classPattern - the pattern String to filter against.
Throws:
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.

addInstanceFilter

void addInstanceFilter(ObjectReference instance)
Restricts the events generated by this request to those in which the currently executing instance ("this") is the object specified.

Not all targets support this operation. Use VirtualMachine.canUseInstanceFilters() to determine if the operation is supported.

Parameters:
instance - the object which must be the current instance in order to pass this filter.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.
InvalidRequestStateException - if this request is currently enabled or has been deleted. Filters may be added only to disabled requests.
Since:
1.4
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


ShortValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface ShortValue

All Superinterfaces:
Comparable<ShortValue>, Mirror, PrimitiveValue, Value
public interface ShortValue
extends PrimitiveValue, Comparable<ShortValue>

Provides access to a primitive short value in the target VM.

Since:
1.3

Method Summary
boolean | equals(Object obj) Compares the specified Object with this ShortValue for equality.
int | hashCode() Returns the hash code value for this ShortValue.
short | value() Returns this ShortValue as a short.
Methods inherited from interface com.sun.jdi.PrimitiveValue
booleanValue, byteValue, charValue, doubleValue, floatValue, intValue, longValue, shortValue
Methods inherited from interface com.sun.jdi.Value
type
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface java.lang.Comparable
compareTo

Method Detail

value

short value()
Returns this ShortValue as a short.

Returns:
the short mirrored by this object.

equals

boolean equals(Object obj)
Compares the specified Object with this ShortValue for equality.

Overrides:
equals in class Object
Returns:
true if the Object is a ShortValue and if applying "==" to the two mirrored primitives would evaluate to true; false otherwise.

hashCode

int hashCode()
Returns the hash code value for this ShortValue.

Overrides:
hashCode in class Object
Returns:
the integer hash code
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StackFrame

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface StackFrame

All Superinterfaces:
Locatable, Mirror
public interface StackFrame
extends Mirror, Locatable

The state of one method invocation on a thread's call stack. As a thread executes, stack frames are pushed and popped from its call stack as methods are invoked and then return. A StackFrame mirrors one such frame from a target VM at some point in its thread's execution. The call stack is, then, simply a List of StackFrame objects. The call stack can be obtained any time a thread is suspended through a call to ThreadReference.frames()

StackFrames provide access to a method's local variables and their current values.

The lifetime of a StackFrame is very limited. It is available only for suspended threads and becomes invalid once its thread is resumed.

Any method on StackFrame which takes StackFrame as an parameter may throw VMDisconnectedException if the target VM is disconnected and the VMDisconnectEvent has been or is available to be read from the EventQueue.

Any method on StackFrame which takes StackFrame as an parameter may throw VMOutOfMemoryException if the target VM has run out of memory.

Since:
1.3

Method Summary
List<Value> | getArgumentValues() Returns the values of all arguments in this frame.
Value | getValue(LocalVariable variable) Gets the Value of a LocalVariable in this frame.
Map<LocalVariable,Value> | getValues(List<? extends LocalVariable> variables) Returns the values of multiple local variables in this frame.
Location | location() Returns the Location of the current instruction in the frame.
void | setValue(LocalVariable variable, Value value) Sets the Value of a LocalVariable in this frame.
ObjectReference | thisObject() Returns the value of 'this' for the current frame.
ThreadReference | thread() Returns the thread under which this frame's method is running.
LocalVariable | visibleVariableByName(String name) Finds a LocalVariable that matches the given name and is visible at the current frame location.
List<LocalVariable> | visibleVariables() Returns a list containing each LocalVariable that can be accessed from this frame's location.
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

location

Location location()
Returns the Location of the current instruction in the frame. The method for which this frame was created can also be accessed through the returned location. For the top frame in the stack, this location identifies the next instruction to be executed. For all other frames, this location identifies the instruction that caused the next frame's method to be invoked. If the frame represents a native method invocation, the returned location indicates the class and method, but the code index will not be valid (-1).

Specified by:
location in interface Locatable
Returns:
the Location of the current instruction.
Throws:
InvalidStackFrameException - if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.

thread

ThreadReference thread()
Returns the thread under which this frame's method is running.

Returns:
a ThreadReference which mirrors the frame's thread.
Throws:
InvalidStackFrameException - if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.

thisObject

ObjectReference thisObject()
Returns the value of 'this' for the current frame. The ObjectReference for 'this' is only available for non-native instance methods.

Returns:
an ObjectReference, or null if the frame represents a native or static method.
Throws:
InvalidStackFrameException - if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.

visibleVariables

List<LocalVariable> visibleVariables()
                                     throws AbsentInformationException
Returns a list containing each LocalVariable that can be accessed from this frame's location.

Visibility is based on the code index of the current instruction of this StackFrame. Each variable has a range of byte code indices in which it is accessible. If this stack frame's method matches this variable's method and if the code index of this StackFrame is within the variable's byte code range, the variable is visible.

A variable's byte code range is at least as large as the scope of that variable, but can continue beyond the end of the scope under certain circumstances:

  • the compiler/VM does not immediately reuse the variable's slot.
  • the compiler/VM is implemented to report the extended range that would result from the item above.
The advantage of an extended range is that variables from recently exited scopes may remain available for examination (this is especially useful for loop indices). If, as a result of the extensions above, the current frame location is contained within the range of multiple local variables of the same name, the variable with the highest-starting range is chosen for the returned list.

Returns:
the list of LocalVariable objects currently visible; the list will be empty if there are no visible variables; specifically, frames in native methods will always return a zero-length list.
Throws:
AbsentInformationException - if there is no local variable information for this method.
InvalidStackFrameException - if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.
NativeMethodException - if the current method is native.

visibleVariableByName

LocalVariable visibleVariableByName(String name)
                                    throws AbsentInformationException
Finds a LocalVariable that matches the given name and is visible at the current frame location. See visibleVariables() for more information on visibility.

Parameters:
name - the variable name to find
Returns:
the matching LocalVariable, or null if there is no visible variable with the given name; frames in native methods will always return null.
Throws:
AbsentInformationException - if there is no local variable information for this method.
InvalidStackFrameException - if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.
NativeMethodException - if the current method is native.

getValue

Value getValue(LocalVariable variable)
Gets the Value of a LocalVariable in this frame. The variable must be valid for this frame's method and visible according to the rules described in visibleVariables().

Parameters:
variable - the LocalVariable to be accessed
Returns:
the Value of the instance field.
Throws:
IllegalArgumentException - if the variable is either invalid for this frame's method or not visible.
InvalidStackFrameException - if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.

getValues

Map<LocalVariable,Value> getValues(List<? extends LocalVariable> variables)
Returns the values of multiple local variables in this frame. Each variable must be valid for this frame's method and visible according to the rules described in visibleVariables().

Parameters:
variables - a list of LocalVariable objects to be accessed
Returns:
a map associating each LocalVariable with its Value
Throws:
IllegalArgumentException - if any variable is either invalid for this frame's method or not visible.
InvalidStackFrameException - if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.

setValue

void setValue(LocalVariable variable,
              Value value)
              throws InvalidTypeException,
                     ClassNotLoadedException
Sets the Value of a LocalVariable in this frame. The variable must be valid for this frame's method and visible according to the rules described in visibleVariables().

Object values must be assignment compatible with the variable type (This implies that the variable type must be loaded through the enclosing class's class loader). Primitive values must be either assignment compatible with the variable type or must be convertible to the variable type without loss of information. See JLS section 5.2 for more information on assignment compatibility.

Parameters:
variable - the field containing the requested value
value - the new value to assign
Throws:
IllegalArgumentException - if the field is not valid for this object's class.
InvalidTypeException - if the value's type does not match the variable's type.
ClassNotLoadedException - if the variable type has not yet been loaded through the appropriate class loader.
InvalidStackFrameException - if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().

getArgumentValues

List<Value> getArgumentValues()
Returns the values of all arguments in this frame. Values are returned even if no local variable information is present.

Returns:
a list containing a Value object for each argument to this frame, in the order in which the arguments were declared. If the method corresponding to this frame has no arguments, an empty list is returned.
Throws:
InvalidStackFrameException - if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.
Since:
1.6
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


StringReference

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface StringReference

All Superinterfaces:
Mirror, ObjectReference, Value
public interface StringReference
extends ObjectReference

A string object from the target VM. A StringReference is an ObjectReference with additional access to string-specific information from the target VM.

Since:
1.3

Field Summary
Fields inherited from interface com.sun.jdi.ObjectReference
INVOKE_NONVIRTUAL, INVOKE_SINGLE_THREADED
Method Summary
 String value()
Returns the StringReference as a String.
Methods inherited from interface com.sun.jdi.ObjectReference
disableCollection, enableCollection, entryCount, equals, getValue, getValues, hashCode, invokeMethod, isCollected, owningThread, referenceType, referringObjects, setValue, uniqueID, waitingThreads
Methods inherited from interface com.sun.jdi.Value
type
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

value

String value()
Returns the StringReference as a String. The returned string is the equivalent of the mirrored string, but is an entity in the client VM and can be manipulated like any other string.

Returns:
the string value.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ThreadGroupReference

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface ThreadGroupReference

All Superinterfaces:
Mirror, ObjectReference, Value
public interface ThreadGroupReference
extends ObjectReference

A thread group object from the target VM. A ThreadGroupReference is an ObjectReference with additional access to threadgroup-specific information from the target VM.

Since:
1.3

Field Summary
Fields inherited from interface com.sun.jdi.ObjectReference
INVOKE_NONVIRTUAL, INVOKE_SINGLE_THREADED
Method Summary
String | name() Returns the name of this thread group.
ThreadGroupReference | parent() Returns the parent of this thread group.
void | resume() Resumes all threads in this thread group.
void | suspend() Suspends all threads in this thread group.
List<ThreadGroupReference> | threadGroups() Returns a List containing each active ThreadGroupReference in this thread group.
List<ThreadReference> | threads() Returns a List containing a ThreadReference for each live thread in this thread group.
Methods inherited from interface com.sun.jdi.ObjectReference
disableCollection, enableCollection, entryCount, equals, getValue, getValues, hashCode, invokeMethod, isCollected, owningThread, referenceType, referringObjects, setValue, uniqueID, waitingThreads
Methods inherited from interface com.sun.jdi.Value
type
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

name

String name()
Returns the name of this thread group.

Returns:
the string containing the thread group name.

parent

ThreadGroupReference parent()
Returns the parent of this thread group.

Returns:
a ThreadGroupReference mirroring the parent of this thread group in the target VM, or null if this is a top-level thread group.

suspend

void suspend()
Suspends all threads in this thread group. Each thread in this group and in all of its subgroups will be suspended as described in ThreadReference.suspend(). This is not guaranteed to be an atomic operation; if the target VM is not interrupted at the time this method is called, it is possible that new threads will be created between the time that threads are enumerated and all of them have been suspended.

Throws:
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().

resume

void resume()
Resumes all threads in this thread group. Each thread in this group and in all of its subgroups will be resumed as described in ThreadReference.resume().

Throws:
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().

threads

List<ThreadReference> threads()
Returns a List containing a ThreadReference for each live thread in this thread group. Only the live threads in this immediate thread group (and not its subgroups) are returned. A thread is alive if it has been started and has not yet been stopped.

Returns:
a List of ThreadReference objects mirroring the live threads from this thread group in the target VM.

threadGroups

List<ThreadGroupReference> threadGroups()
Returns a List containing each active ThreadGroupReference in this thread group. Only the active thread groups in this immediate thread group (and not its subgroups) are returned. See java.lang.ThreadGroup for information about 'active' ThreadGroups.

Returns:
a List of ThreadGroupReference objects mirroring the active thread groups from this thread group in the target VM.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


ThreadReference

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface ThreadReference

All Superinterfaces:
Mirror, ObjectReference, Value
public interface ThreadReference
extends ObjectReference

A thread object from the target VM. A ThreadReference is an ObjectReference with additional access to thread-specific information from the target VM.

Since:
1.3

Field Summary
static int | THREAD_STATUS_MONITOR Thread is waiting on a java monitor
static int | THREAD_STATUS_NOT_STARTED Thread has not yet been started
static int | THREAD_STATUS_RUNNING Thread is runnable
static int | THREAD_STATUS_SLEEPING Thread is sleeping - Thread.sleep() or JVM_Sleep() was called
static int | THREAD_STATUS_UNKNOWN Thread status is unknown
static int | THREAD_STATUS_WAIT Thread is waiting - Object.wait() or JVM_MonitorWait() was called
static int | THREAD_STATUS_ZOMBIE Thread has completed execution
Fields inherited from interface com.sun.jdi.ObjectReference
INVOKE_NONVIRTUAL, INVOKE_SINGLE_THREADED
Method Summary
ObjectReference | currentContendedMonitor() Returns an ObjectReference for the monitor, if any, for which this thread is currently waiting.
void | forceEarlyReturn(Value value) Force a method to return before it reaches a return statement.
StackFrame | frame(int index) Returns the StackFrame at the given index in the thread's current call stack.
int | frameCount() Returns the number of stack frames in the thread's current call stack.
List<StackFrame> | frames() Returns a List containing each StackFrame in the thread's current call stack.
List<StackFrame> | frames(int start, int length) Returns a List containing a range of StackFrame mirrors from the thread's current call stack.
void | interrupt() Interrupts this thread unless the thread has been suspended by the debugger.
boolean | isAtBreakpoint() Determines whether the thread is suspended at a breakpoint.
boolean | isSuspended() Determines whether the thread has been suspended by the the debugger.
String | name() Returns the name of this thread.
List<ObjectReference> | ownedMonitors() Returns a List containing an ObjectReference for each monitor owned by the thread.
List<MonitorInfo> | ownedMonitorsAndFrames() Returns a List containing a MonitorInfo object for each monitor owned by the thread.
void | popFrames(StackFrame frame) Pop stack frames.
void | resume() Resumes this thread.
int | status() Returns the thread's status.
void | stop(ObjectReference throwable) Stops this thread with an asynchronous exception.
void | suspend() Suspends this thread.
int | suspendCount() Returns the number of pending suspends for this thread.
ThreadGroupReference | threadGroup() Returns this thread's thread group.
Methods inherited from interface com.sun.jdi.ObjectReference
disableCollection, enableCollection, entryCount, equals, getValue, getValues, hashCode, invokeMethod, isCollected, owningThread, referenceType, referringObjects, setValue, uniqueID, waitingThreads
Methods inherited from interface com.sun.jdi.Value
type
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Field Detail

THREAD_STATUS_UNKNOWN

static final int THREAD_STATUS_UNKNOWN
Thread status is unknown

See Also:
Constant Field Values

THREAD_STATUS_ZOMBIE

static final int THREAD_STATUS_ZOMBIE
Thread has completed execution

See Also:
Constant Field Values

THREAD_STATUS_RUNNING

static final int THREAD_STATUS_RUNNING
Thread is runnable

See Also:
Constant Field Values

THREAD_STATUS_SLEEPING

static final int THREAD_STATUS_SLEEPING
Thread is sleeping - Thread.sleep() or JVM_Sleep() was called

See Also:
Constant Field Values

THREAD_STATUS_MONITOR

static final int THREAD_STATUS_MONITOR
Thread is waiting on a java monitor

See Also:
Constant Field Values

THREAD_STATUS_WAIT

static final int THREAD_STATUS_WAIT
Thread is waiting - Object.wait() or JVM_MonitorWait() was called

See Also:
Constant Field Values

THREAD_STATUS_NOT_STARTED

static final int THREAD_STATUS_NOT_STARTED
Thread has not yet been started

See Also:
Constant Field Values
Method Detail

name

String name()
Returns the name of this thread.

Returns:
the string containing the thread name.

suspend

void suspend()
Suspends this thread. The thread can be resumed through resume() or resumed with other threads through VirtualMachine.resume().

Unlike Thread.suspend(), suspends of both the virtual machine and individual threads are counted. Before a thread will run again, it must be resumed (through resume() or resume()) the same number of times it has been suspended.

Suspending single threads with this method has the same dangers as Thread.suspend(). If the suspended thread holds a monitor needed by another running thread, deadlock is possible in the target VM (at least until the suspended thread is resumed again).

The suspended thread is guaranteed to remain suspended until resumed through one of the JDI resume methods mentioned above; the application in the target VM cannot resume the suspended thread through Thread.resume().

Throws:
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().

resume

void resume()
Resumes this thread. If this thread was not previously suspended through suspend() or through VirtualMachine.suspend(), or because of a SUSPEND_ALL or SUSPEND_EVENT_THREAD event, then invoking this method has no effect. Otherwise, the count of pending suspends on this thread is decremented. If it is decremented to 0, the thread will continue to execute. Note: the normal way to resume from an event related suspension is via EventSet.resume().

Throws:
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().

suspendCount

int suspendCount()
Returns the number of pending suspends for this thread. See suspend() for an explanation of counted suspends.

Returns:
pending suspend count as an integer

stop

void stop(ObjectReference throwable)
          throws InvalidTypeException
Stops this thread with an asynchronous exception. A debugger thread in the target VM will stop this thread with the given Throwable object.

Parameters:
throwable - the asynchronous exception to throw.
Throws:
InvalidTypeException - if throwable is not an instance of java.lang.Throwable in the target VM.
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().
See Also:
Thread.stop(Throwable)

interrupt

void interrupt()
Interrupts this thread unless the thread has been suspended by the debugger.

Throws:
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().
See Also:
Thread.interrupt()

status

int status()
Returns the thread's status. If the thread is not suspended the thread's current status is returned. If the thread is suspended, the thread's status before the suspension is returned (or THREAD_STATUS_UNKNOWN if this information is not available. isSuspended() can be used to determine if the thread has been suspended.

Returns:
one of THREAD_STATUS_UNKNOWN, THREAD_STATUS_ZOMBIE, THREAD_STATUS_RUNNING, THREAD_STATUS_SLEEPING, THREAD_STATUS_MONITOR, THREAD_STATUS_WAIT, THREAD_STATUS_NOT_STARTED,

isSuspended

boolean isSuspended()
Determines whether the thread has been suspended by the the debugger.

Returns:
true if the thread is currently suspended; false otherwise.

isAtBreakpoint

boolean isAtBreakpoint()
Determines whether the thread is suspended at a breakpoint.

Returns:
true if the thread is currently stopped at a breakpoint; false otherwise.

threadGroup

ThreadGroupReference threadGroup()
Returns this thread's thread group.

Returns:
a ThreadGroupReference that mirrors this thread's thread group in the target VM.

frameCount

int frameCount()
               throws IncompatibleThreadStateException
Returns the number of stack frames in the thread's current call stack. The thread must be suspended (normally through an interruption to the VM) to get this information, and it is only valid until the thread is resumed again.

Returns:
an integer frame count
Throws:
IncompatibleThreadStateException - if the thread is not suspended in the target VM

frames

List<StackFrame> frames()
                        throws IncompatibleThreadStateException
Returns a List containing each StackFrame in the thread's current call stack. The thread must be suspended (normally through an interruption to the VM) to get this information, and it is only valid until the thread is resumed again.

Returns:
a List of StackFrame with the current frame first followed by each caller's frame.
Throws:
IncompatibleThreadStateException - if the thread is not suspended in the target VM

frame

StackFrame frame(int index)
                 throws IncompatibleThreadStateException
Returns the StackFrame at the given index in the thread's current call stack. Index 0 retrieves the current frame; higher indices retrieve caller frames. The thread must be suspended (normally through an interruption to the VM) to get this information, and it is only valid until the thread is resumed again.

Parameters:
index - the desired frame
Returns:
the requested StackFrame
Throws:
IncompatibleThreadStateException - if the thread is not suspended in the target VM
IndexOutOfBoundsException - if the index is greater than or equal to frameCount() or is negative.

frames

List<StackFrame> frames(int start,
                        int length)
                        throws IncompatibleThreadStateException
Returns a List containing a range of StackFrame mirrors from the thread's current call stack. The thread must be suspended (normally through an interruption to the VM) to get this information, and it is only valid until the thread is resumed again.

Parameters:
start - the index of the first frame to retrieve. Index 0 represents the current frame.
length - the number of frames to retrieve
Returns:
a List of StackFrame with the current frame first followed by each caller's frame.
Throws:
IncompatibleThreadStateException - if the thread is not suspended in the target VM
IndexOutOfBoundsException - if the specified range is not within the range of stack frame indicies. That is, the exception is thrown if any of the following are true:
    start < 0
    start >= frameCount()
    length < 0
    (start+length) > frameCount()

ownedMonitors

List<ObjectReference> ownedMonitors()
                                    throws IncompatibleThreadStateException
Returns a List containing an ObjectReference for each monitor owned by the thread. A monitor is owned by a thread if it has been entered (via the synchronized statement or entry into a synchronized method) and has not been relinquished through Object.wait(long).

Not all target virtual machines support this operation. Use VirtualMachine.canGetOwnedMonitorInfo() to determine if the operation is supported.

Returns:
a List of ObjectReference objects. The list has zero length if no monitors are owned by this thread.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.
IncompatibleThreadStateException - if the thread is not suspended in the target VM

ownedMonitorsAndFrames

List<MonitorInfo> ownedMonitorsAndFrames()
                                         throws IncompatibleThreadStateException
Returns a List containing a MonitorInfo object for each monitor owned by the thread. A monitor is owned by a thread if it has been entered (via the synchronized statement or entry into a synchronized method) and has not been relinquished through Object.wait(long).

Not all target virtual machines support this operation. Use VirtualMachine.canGetMonitorFrameInfo() to determine if the operation is supported.

Returns:
a List of MonitorInfo objects. The list has zero length if no monitors are owned by this thread.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.
IncompatibleThreadStateException - if the thread is not suspended in the target VM
Since:
1.6

currentContendedMonitor

ObjectReference currentContendedMonitor()
                                        throws IncompatibleThreadStateException
Returns an ObjectReference for the monitor, if any, for which this thread is currently waiting. The thread can be waiting for a monitor through entry into a synchronized method, the synchronized statement, or Object.wait(long). The status() method can be used to differentiate between the first two cases and the third.

Not all target virtual machines support this operation. Use VirtualMachine.canGetCurrentContendedMonitor() to determine if the operation is supported.

Returns:
the ObjectReference corresponding to the contended monitor, or null if it is not waiting for a monitor.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.
IncompatibleThreadStateException - if the thread is not suspended in the target VM

popFrames

void popFrames(StackFrame frame)
               throws IncompatibleThreadStateException
Pop stack frames.

All frames up to and including the frame are popped off the stack. The frame previous to the parameter frame will become the current frame.

After this operation, this thread will be suspended at the invoke instruction of the target method that created frame. The frame's method can be reentered with a step into the instruction.

The operand stack is restored, however, any changes to the arguments that occurred in the called method, remain. For example, if the method foo:

    void foo(int x) {
        System.out.println("Foo: " + x);
        x = 4;
        System.out.println("pop here");
    }
was called with foo(7) and foo is popped at the second println and resumed, it will print: Foo: 4.

Locks acquired by a popped frame are released when it is popped. This applies to synchronized methods that are popped, and to any synchronized blocks within them.

Finally blocks are not executed.

No aspect of state, other than this thread's execution point and locks, is affected by this call. Specifically, the values of fields are unchanged, as are external resources such as I/O streams. Additionally, the target program might be placed in a state that is impossible with normal program flow; for example, order of lock acquisition might be perturbed. Thus the target program may proceed differently than the user would expect.

The specified thread must be suspended.

All StackFrame objects for this thread are invalidated.

No events are generated by this method.

None of the frames through and including the frame for the caller of frame may be native.

Not all target virtual machines support this operation. Use VirtualMachine.canPopFrames() to determine if the operation is supported.

Parameters:
frame - Stack frame to pop. frame is on this thread's call stack.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation - see VirtualMachine.canPopFrames().
IncompatibleThreadStateException - if this thread is not suspended.
IllegalArgumentException - if frame is not on this thread's call stack.
NativeMethodException - if one of the frames that would be popped is that of a native method or if the frame previous to frame is native.
InvalidStackFrameException - if frame has become invalid. Once this thread is resumed, the stack frame is no longer valid. This exception is also thrown if there are no more frames.
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().
Since:
1.4

forceEarlyReturn

void forceEarlyReturn(Value value)
                      throws InvalidTypeException,
                             ClassNotLoadedException,
                             IncompatibleThreadStateException
Force a method to return before it reaches a return statement.

The method which will return early is referred to as the called method. The called method is the current method (as defined by the Frames section in the Java Virtual Machine Specification) for the specified thread at the time this method is called.

The thread must be suspended. The return occurs when execution of Java programming language code is resumed on this thread. Between the call to this method and resumption of thread execution, the state of the stack is undefined.

No further instructions are executed in the called method. Specifically, finally blocks are not executed. Note: this can cause inconsistent states in the application.

A lock acquired by calling the called method (if it is a synchronized method) and locks acquired by entering synchronized blocks within the called method are released. Note: this does not apply to native locks or java.util.concurrent.locks locks.

Events, such as MethodExit, are generated as they would be in a normal return.

The called method must be a non-native Java programming language method. Forcing return on a thread with only one frame on the stack causes the thread to exit when resumed.

The value argument is the value that the method is to return. If the return type of the method is void, then value must be a VoidValue. Object values must be assignment compatible with the method return type (This implies that the method return type must be loaded through the enclosing class's class loader). Primitive values must be either assignment compatible with the method return type or must be convertible to the variable type without loss of information. See JLS section 5.2 for more information on assignment compatibility.

Not all target virtual machines support this operation. Use VirtualMachine.canForceEarlyReturn() to determine if the operation is supported.

Parameters:
value - the value the method is to return.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation - see canForceEarlyReturn()
IncompatibleThreadStateException - if this thread is not suspended.
NativeMethodException - if the frame to be returned from is that of a native method.
InvalidStackFrameException - if there are no frames.
InvalidTypeException - if the value's type does not match the method's return type.
ClassNotLoadedException - if the method's return type has not yet been loaded through the appropriate class loader.
VMCannotBeModifiedException - if the VirtualMachine is read-only - see VirtualMachine.canBeModified().
Since:
1.6
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Type

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface Type

All Superinterfaces:
Mirror
All Known Subinterfaces:
ArrayType, BooleanType, ByteType, CharType, ClassType, DoubleType, FloatType, IntegerType, InterfaceType, LongType, PrimitiveType, ReferenceType, ShortType, VoidType
public interface Type
extends Mirror

The mirror for a type in the target VM. This interface is the root of a type hierarchy encompassing primitive types and reference types.

A Type may be used to represent a run-time type:

Value.type()
or a compile-time type:
Field.type()
Method.returnType()
Method.argumentTypes()
LocalVariable.type()
ArrayType.componentType()

The following table illustrates which subinterfaces of Type are used to mirror types in the target VM --
Subinterfaces of PrimitiveType
Type declared in target as |  | Is mirrored as an instance of
boolean |  | BooleanType
byte |  | ByteType
char |  | CharType
double |  | DoubleType
float |  | FloatType
int |  | IntegerType
long |  | LongType
short |  | ShortType
void |  | VoidType
Subinterfaces of ReferenceType
Type declared in target as | For example | Is mirrored as an instance of
a class | Date | ClassType
an interface | Runnable | InterfaceType
an array |  | ArrayType
an array | int[] | ArrayType whose componentType() is IntegerType
an array | Date[] | ArrayType whose componentType() is ClassType
an array | Runnable[] | ArrayType whose componentType() is InterfaceType

Since:
1.3
See Also:
Subinterface PrimitiveType, Subinterface ReferenceType, Value - for relationship between Type and Value, Field.type() - for usage examples

Method Summary
String | name()
String | signature() Returns the JNI-style signature for this type.
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

signature

String signature()
Returns the JNI-style signature for this type.

For primitive classes the returned signature is the signature of the corresponding primitive type; for example, "I" is returned as the signature of the class represented by Integer.TYPE.

Returns:
the string containing the type signature.
See Also:
Type Signatures

name

String name()
Returns:
a text representation of this type.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


TypeComponent

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface TypeComponent

All Superinterfaces:
Accessible, Mirror
All Known Subinterfaces:
Field, Method
public interface TypeComponent
extends Mirror, Accessible

An entity declared within a user defined type (class or interface). This interface is the root of the type component hierarchy which includes Field and Method. Type components of the same name declared in different classes (including those related by inheritance) have different TypeComponent objects. TypeComponents can be used alone to retrieve static information about their declaration, or can be used in conjunction with a ReferenceType or ObjectReference to access values or invoke, as applicable.

Since:
1.3

Method Summary
ReferenceType | declaringType() Returns the type in which this component was declared.
String | genericSignature() Gets the generic signature for this TypeComponent if there is one.
boolean | isFinal() Determines if this TypeComponent is final.
boolean | isStatic() Determines if this TypeComponent is static.
boolean | isSynthetic() Determines if this TypeComponent is synthetic.
String | name() Gets the name of this type component.
String | signature() Gets the JNI-style signature for this type component.
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
Methods inherited from interface com.sun.jdi.Accessible
isPackagePrivate, isPrivate, isProtected, isPublic, modifiers

Method Detail

name

String name()
Gets the name of this type component.

Note: for fields, this is the field name; for methods, this is the method name; for constructors, this is <init>; for static initializers, this is <clinit>.

Returns:
a string containing the name.

signature

String signature()
Gets the JNI-style signature for this type component. The signature is encoded type information as defined in the JNI documentation. It is a convenient, compact format for for manipulating type information internally, not necessarily for display to an end user. See Field.typeName() and Method.returnTypeName() for ways to help get a more readable representation of the type.

Returns:
a string containing the signature
See Also:
Type Signatures

genericSignature

String genericSignature()
Gets the generic signature for this TypeComponent if there is one. Generic signatures are described in the "JavaTM Virtual Machine Specification, 3rd Edition.

Returns:
a string containing the generic signature, or null if there is no generic signature.
Since:
1.5

declaringType

ReferenceType declaringType()
Returns the type in which this component was declared. The returned ReferenceType mirrors either a class or an interface in the target VM.

Returns:
a ReferenceType for the type that declared this type component.

isStatic

boolean isStatic()
Determines if this TypeComponent is static. Return value is undefined for constructors and static initializers.

Returns:
true if this type component was declared static; false otherwise.

isFinal

boolean isFinal()
Determines if this TypeComponent is final. Return value is undefined for constructors and static initializers.

Returns:
true if this type component was declared final; false otherwise.

isSynthetic

boolean isSynthetic()
Determines if this TypeComponent is synthetic. Synthetic members are generated by the compiler and are not present in the source code for the containing class.

Not all target VMs support this query. See VirtualMachine.canGetSyntheticAttribute() to determine if the operation is supported.

Returns:
true if this type component is synthetic; false otherwise.
Throws:
UnsupportedOperationException - if the target VM cannot provide information on synthetic attributes.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


Value

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface Value

All Superinterfaces:
Mirror
All Known Subinterfaces:
ArrayReference, BooleanValue, ByteValue, CharValue, ClassLoaderReference, ClassObjectReference, DoubleValue, FloatValue, IntegerValue, LongValue, ObjectReference, PrimitiveValue, ShortValue, StringReference, ThreadGroupReference, ThreadReference, VoidValue
public interface Value
extends Mirror

The mirror for a value in the target VM. This interface is the root of a value hierarchy encompassing primitive values and object values.

Some examples of where values may be accessed:

ObjectReference.getValue(Field) | - value of a field
StackFrame.getValue(LocalVariable) | - value of a variable
VirtualMachine.mirrorOf(double) | - created in the target VM by the JDI client
ModificationWatchpointEvent.valueToBe() | - returned with an event

The following table illustrates which subinterfaces of Value are used to mirror values in the target VM --
Subinterfaces of PrimitiveValue
Kind of value For example -
expression in target 		Is mirrored as an
instance of 		Type of value
Value.type()
a boolean | true | BooleanValue | BooleanType
a byte | (byte)4 | ByteValue | ByteType
a char | 'a' | CharValue | CharType
a double | 3.1415926 | DoubleValue | DoubleType
a float | 2.5f | FloatValue | FloatType
an int | 22 | IntegerValue | IntegerType
a long | 1024L | LongValue | LongType
a short | (short)12 | ShortValue | ShortType
a void   | VoidValue | VoidType
Subinterfaces of ObjectReference
Kind of value For example -
expression in target 		Is mirrored as an
instance of 		Type of value
Value.type()
a class instance | this | ObjectReference | ClassType
an array | new int[5] | ArrayReference | ArrayType
a string | "hello" | StringReference | ClassType
a thread | Thread.currentThread() | ThreadReference | ClassType
a thread group Thread.currentThread()
  .getThreadGroup() 		ThreadGroupReference ClassType
a java.lang.Class
instance 		this.getClass() ClassObjectReference ClassType
a class loader this.getClass()
  .getClassLoader() 		ClassLoaderReference ClassType
Other
Kind of value For example -
expression in target 		Is mirrored as Type of value
null | null | null | n/a

Since:
1.3

Method Summary
 Type type()
Returns the run-time type of this value.
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

type

Type type()
Returns the run-time type of this value.

Returns:
a Type which mirrors the value's type in the target VM.
See Also:
Type
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VirtualMachine

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface VirtualMachine

All Superinterfaces:
Mirror
All Known Subinterfaces:
PathSearchingVirtualMachine
public interface VirtualMachine
extends Mirror

A virtual machine targeted for debugging. More precisely, a mirror representing the composite state of the target VM. All other mirrors are associated with an instance of this interface. Access to all other mirrors is achieved directly or indirectly through an instance of this interface. Access to global VM properties and control of VM execution are supported directly by this interface.

Instances of this interface are created by instances of Connector. For example, an AttachingConnector attaches to a target VM and returns its virtual machine mirror. A Connector will typically create a VirtualMachine by invoking the VirtualMachineManager's VirtualMachineManager.createVirtualMachine(Connection) createVirtualMachine(Connection) method.

Note that a target VM launched by a launching connector is not guaranteed to be stable until after the VMStartEvent has been received.

Any method on VirtualMachine which takes VirtualMachine as an parameter may throw VMDisconnectedException if the target VM is disconnected and the VMDisconnectEvent has been or is available to be read from the EventQueue.

Any method on VirtualMachine which takes VirtualMachine as an parameter may throw VMOutOfMemoryException if the target VM has run out of memory.

Since:
1.3

Field Summary
static int | TRACE_ALL All tracing is enabled.
static int | TRACE_EVENTS Tracing enabled for internal event handling.
static int | TRACE_NONE All tracing is disabled.
static int | TRACE_OBJREFS Tracing enabled for internal management of object references.
static int | TRACE_RECEIVES Tracing enabled for JDWP packets received from target VM.
static int | TRACE_REFTYPES Tracing enabled for internal managment of reference types.
static int | TRACE_SENDS Tracing enabled for JDWP packets sent to target VM.
Method Summary
List<ReferenceType> | allClasses() Returns all loaded types.
List<ThreadReference> | allThreads() Returns a list of the currently running threads.
boolean | canAddMethod() Determines if the target VM supports the addition of methods when performing class redefinition.
boolean | canBeModified() Determines if the target VM is a read-only VM.
boolean | canForceEarlyReturn() Determines if the target VM supports the forcing of a method to return early.
boolean | canGetBytecodes() Determines if the target VM supports the retrieval of a method's bytecodes.
boolean | canGetClassFileVersion() Determines if the target VM supports reading class file major and minor versions.
boolean | canGetConstantPool() Determines if the target VM supports getting constant pool information of a class.
boolean | canGetCurrentContendedMonitor() Determines if the target VM supports the retrieval of the monitor for which a thread is currently waiting.
boolean | canGetInstanceInfo() Determines if the target VM supports the accessing of class instances, instance counts, and referring objects.
boolean | canGetMethodReturnValues() Determines if the target VM supports the inclusion of return values in MethodExitEvents.
boolean | canGetMonitorFrameInfo() Determines if the target VM supports getting which frame has acquired a monitor.
boolean | canGetMonitorInfo() Determines if the target VM supports the retrieval of the monitor information for an object.
boolean | canGetOwnedMonitorInfo() Determines if the target VM supports the retrieval of the monitors owned by a thread.
boolean | canGetSourceDebugExtension() Determines if the target VM supports getting the source debug extension.
boolean | canGetSyntheticAttribute() Determines if the target VM supports the query of the synthetic attribute of a method or field.
boolean | canPopFrames() Determines if the target VM supports popping frames of a threads stack.
boolean | canRedefineClasses() Determines if the target VM supports any level of class redefinition.
boolean | canRequestMonitorEvents() Determines if the target VM supports the creation of MonitorContendedEnterRequests.
boolean | canRequestVMDeathEvent() Determines if the target VM supports the creation of VMDeathRequests.
boolean | canUnrestrictedlyRedefineClasses() Determines if the target VM supports unrestricted changes when performing class redefinition.
boolean | canUseInstanceFilters() Determines if the target VM supports filtering events by specific instance object.
boolean | canUseSourceNameFilters() Determines if the target VM supports the filtering of class prepare events by source name.
boolean | canWatchFieldAccess() Determines if the target VM supports watchpoints for field access.
boolean | canWatchFieldModification() Determines if the target VM supports watchpoints for field modification.
List<ReferenceType> | classesByName(String className) Returns the loaded reference types that match a given name.
String | description() Returns text information on the target VM and the debugger support that mirrors it.
void | dispose() Invalidates this virtual machine mirror.
EventQueue | eventQueue() Returns the event queue for this virtual machine.
EventRequestManager | eventRequestManager() Returns the event request manager for this virtual machine.
void | exit(int exitCode) Causes the mirrored VM to terminate with the given error code.
String | getDefaultStratum() Return this VM's default stratum.
long[] | instanceCounts(List<? extends ReferenceType> refTypes) Returns the number of instances of each ReferenceType in the 'refTypes' list.
BooleanValue | mirrorOf(boolean value) Creates a BooleanValue for the given value.
ByteValue | mirrorOf(byte value) Creates a ByteValue for the given value.
CharValue | mirrorOf(char value) Creates a CharValue for the given value.
DoubleValue | mirrorOf(double value) Creates a DoubleValue for the given value.
FloatValue | mirrorOf(float value) Creates a FloatValue for the given value.
IntegerValue | mirrorOf(int value) Creates an IntegerValue for the given value.
LongValue | mirrorOf(long value) Creates a LongValue for the given value.
ShortValue | mirrorOf(short value) Creates a ShortValue for the given value.
StringReference | mirrorOf(String value) Creates a string in this virtual machine.
VoidValue | mirrorOfVoid() Creates a VoidValue.
String | name() Returns the name of the target VM as reported by the property java.vm.name.
Process | process() Returns the Process object for this virtual machine if launched by a LaunchingConnector
void | redefineClasses(Map<? extends ReferenceType,byte[]> classToBytes) All classes given are redefined according to the definitions supplied.
void | resume() Continues the execution of the application running in this virtual machine.
void | setDebugTraceMode(int traceFlags) Traces the activities performed by the com.sun.jdi implementation.
void | setDefaultStratum(String stratum) Set this VM's default stratum (see Location for a discussion of strata).
void | suspend() Suspends the execution of the application running in this virtual machine.
List<ThreadGroupReference> | topLevelThreadGroups() Returns each thread group which does not have a parent.
String | version() Returns the version of the Java Runtime Environment in the target VM as reported by the property java.version.
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Field Detail

TRACE_NONE

static final int TRACE_NONE
All tracing is disabled.

See Also:
Constant Field Values

TRACE_SENDS

static final int TRACE_SENDS
Tracing enabled for JDWP packets sent to target VM.

See Also:
Constant Field Values

TRACE_RECEIVES

static final int TRACE_RECEIVES
Tracing enabled for JDWP packets received from target VM.

See Also:
Constant Field Values

TRACE_EVENTS

static final int TRACE_EVENTS
Tracing enabled for internal event handling.

See Also:
Constant Field Values

TRACE_REFTYPES

static final int TRACE_REFTYPES
Tracing enabled for internal managment of reference types.

See Also:
Constant Field Values

TRACE_OBJREFS

static final int TRACE_OBJREFS
Tracing enabled for internal management of object references.

See Also:
Constant Field Values

TRACE_ALL

static final int TRACE_ALL
All tracing is enabled.

See Also:
Constant Field Values
Method Detail

classesByName

List<ReferenceType> classesByName(String className)
Returns the loaded reference types that match a given name. The name must be fully qualified (for example, java.lang.String). The returned list will contain a ReferenceType for each class or interface found with the given name. The search is confined to loaded classes only; no attempt is made to load a class of the given name.

The returned list will include reference types loaded at least to the point of preparation and types (like array) for which preparation is not defined.

Parameters:
className - the class/interface name to search for
Returns:
a list of ReferenceType objects, each mirroring a type in the target VM with the given name.

allClasses

List<ReferenceType> allClasses()
Returns all loaded types. For each loaded type in the target VM a ReferenceType will be placed in the returned list. The list will include ReferenceTypes which mirror classes, interfaces, and array types.

The returned list will include reference types loaded at least to the point of preparation and types (like array) for which preparation is not defined.

Returns:
a list of ReferenceType objects, each mirroring a loaded type in the target VM.

redefineClasses

void redefineClasses(Map<? extends ReferenceType,byte[]> classToBytes)
All classes given are redefined according to the definitions supplied. A method in a redefined class is called 'equivalent' (to the old version of the method) if
  • their bytecodes are the same except for indicies into the constant pool, and
  • the referenced constants are equal.
Otherwise, the new method is called 'non-equivalent'. If a redefined method has active stack frames, those active frames continue to run the bytecodes of the previous version of the method. If the new version of such a method is non-equivalent, then a method from one of these active frames is called 'obsolete' and Method.isObsolete() will return true when called on one of these methods. If resetting such a frame is desired, use ThreadReference.popFrames(StackFrame) to pop the old obsolete method execution from the stack. New invocations of redefined methods will always invoke the new versions.

This function does not cause any initialization except that which would occur under the customary JVM semantics. In other words, redefining a class does not cause its initializers to be run. The values of preexisting static variables will remain as they were prior to the call. However, completely uninitialized (new) static variables will be assigned their default value.

If a redefined class has instances then all those instances will have the fields defined by the redefined class at the completion of the call. Preexisting fields will retain their previous values. Any new fields will have their default values; no instance initializers or constructors are run.

Threads need not be suspended.

No events are generated by this function.

All breakpoints in the redefined classes are deleted.

Not all target virtual machines support this operation. Use canRedefineClasses() to determine if the operation is supported. Use canAddMethod() to determine if the redefinition can add methods. Use canUnrestrictedlyRedefineClasses() to determine if the redefinition can change the schema, delete methods, change the class hierarchy, etc.

Parameters:
classToBytes - A map from ReferenceType to array of byte. The bytes represent the new class definition and are in Java Virtual Machine class file format.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.
  • If canRedefineClasses() is false any call of this method will throw this exception.
  • If canAddMethod() is false attempting to add a method will throw this exception.
  • If canUnrestrictedlyRedefineClasses() is false, attempting any of the following will throw this exception
    • changing the schema (the fields)
    • changing the hierarchy (subclasses, interfaces)
    • deleting a method
    • changing class modifiers
    • changing method modifiers
NoClassDefFoundError - if the bytes don't correspond to the reference type (the names don't match).
VerifyError - if a "verifier" detects that a class, though well formed, contains an internal inconsistency or security problem.
ClassFormatError - if the bytes do not represent a valid class.
ClassCircularityError - if a circularity has been detected while initializing a class.
UnsupportedClassVersionError - if the major and minor version numbers in bytes are not supported by the VM.
VMCannotBeModifiedException - if the VirtualMachine is read-only - see canBeModified().
Since:
1.4
See Also:
Method.isObsolete(),
ThreadReference.popFrames(com.sun.jdi.StackFrame),
canRedefineClasses(),
canAddMethod(),
canUnrestrictedlyRedefineClasses()

allThreads

List<ThreadReference> allThreads()
Returns a list of the currently running threads. For each running thread in the target VM, a ThreadReference that mirrors it is placed in the list. The returned list contains threads created through java.lang.Thread, all native threads attached to the target VM through JNI, and system threads created by the target VM. Thread objects that have not yet been started (see Thread.start()) and thread objects that have completed their execution are not included in the returned list.

Returns:
a list of ThreadReference objects, one for each running thread in the mirrored VM.

suspend

void suspend()
Suspends the execution of the application running in this virtual machine. All threads currently running will be suspended.

Unlike Thread.suspend(), suspends of both the virtual machine and individual threads are counted. Before a thread will run again, it must be resumed (through resume() or ThreadReference.resume()) the same number of times it has been suspended.

Throws:
VMCannotBeModifiedException - if the VirtualMachine is read-only - see canBeModified().

resume

void resume()
Continues the execution of the application running in this virtual machine. All threads are resumed as documented in ThreadReference.resume().

Throws:
VMCannotBeModifiedException - if the VirtualMachine is read-only - see canBeModified().
See Also:
suspend()

topLevelThreadGroups

List<ThreadGroupReference> topLevelThreadGroups()
Returns each thread group which does not have a parent. For each top level thread group a ThreadGroupReference is placed in the returned list.

This command may be used as the first step in building a tree (or trees) of the existing thread groups.

Returns:
a list of ThreadGroupReference objects, one for each top level thread group.

eventQueue

EventQueue eventQueue()
Returns the event queue for this virtual machine. A virtual machine has only one EventQueue object, this method will return the same instance each time it is invoked.

Returns:
the EventQueue for this virtual machine.
Throws:
VMCannotBeModifiedException - if the VirtualMachine is read-only - see canBeModified().

eventRequestManager

EventRequestManager eventRequestManager()
Returns the event request manager for this virtual machine. The EventRequestManager controls user settable events such as breakpoints. A virtual machine has only one EventRequestManager object, this method will return the same instance each time it is invoked.

Returns:
the EventRequestManager for this virtual machine.
Throws:
VMCannotBeModifiedException - if the VirtualMachine is read-only - see canBeModified().

mirrorOf

BooleanValue mirrorOf(boolean value)
Creates a BooleanValue for the given value. This value can be used for setting and comparing against a value retrieved from a variable or field in this virtual machine.

Parameters:
value - a boolean for which to create the value
Returns:
the BooleanValue for the given boolean.

mirrorOf

ByteValue mirrorOf(byte value)
Creates a ByteValue for the given value. This value can be used for setting and comparing against a value retrieved from a variable or field in this virtual machine.

Parameters:
value - a byte for which to create the value
Returns:
the ByteValue for the given byte.

mirrorOf

CharValue mirrorOf(char value)
Creates a CharValue for the given value. This value can be used for setting and comparing against a value retrieved from a variable or field in this virtual machine.

Parameters:
value - a char for which to create the value
Returns:
the CharValue for the given char.

mirrorOf

ShortValue mirrorOf(short value)
Creates a ShortValue for the given value. This value can be used for setting and comparing against a value retrieved from a variable or field in this virtual machine.

Parameters:
value - a short for which to create the value
Returns:
the ShortValue for the given short.

mirrorOf

IntegerValue mirrorOf(int value)
Creates an IntegerValue for the given value. This value can be used for setting and comparing against a value retrieved from a variable or field in this virtual machine.

Parameters:
value - an int for which to create the value
Returns:
the IntegerValue for the given int.

mirrorOf

LongValue mirrorOf(long value)
Creates a LongValue for the given value. This value can be used for setting and comparing against a value retrieved from a variable or field in this virtual machine.

Parameters:
value - a long for which to create the value
Returns:
the LongValue for the given long.

mirrorOf

FloatValue mirrorOf(float value)
Creates a FloatValue for the given value. This value can be used for setting and comparing against a value retrieved from a variable or field in this virtual machine.

Parameters:
value - a float for which to create the value
Returns:
the FloatValue for the given float.

mirrorOf

DoubleValue mirrorOf(double value)
Creates a DoubleValue for the given value. This value can be used for setting and comparing against a value retrieved from a variable or field in this virtual machine.

Parameters:
value - a double for which to create the value
Returns:
the DoubleValue for the given double.

mirrorOf

StringReference mirrorOf(String value)
Creates a string in this virtual machine. The created string can be used for setting and comparing against a string value retrieved from a variable or field in this virtual machine.

Parameters:
value - the string to be created
Returns:
a StringReference that mirrors the newly created string in the target VM.
Throws:
VMCannotBeModifiedException - if the VirtualMachine is read-only -see canBeModified().

mirrorOfVoid

VoidValue mirrorOfVoid()
Creates a VoidValue. This value can be passed to ThreadReference.forceEarlyReturn(com.sun.jdi.Value) when a void method is to be exited.

Returns:
the VoidValue.

process

Process process()
Returns the Process object for this virtual machine if launched by a LaunchingConnector

Returns:
the Process object for this virtual machine, or null if it was not launched by a LaunchingConnector.
Throws:
VMCannotBeModifiedException - if the VirtualMachine is read-only -see canBeModified().

dispose

void dispose()
Invalidates this virtual machine mirror. The communication channel to the target VM is closed, and the target VM prepares to accept another subsequent connection from this debugger or another debugger, including the following tasks:
  • All event requests are cancelled.
  • All threads suspended by suspend() or by ThreadReference.suspend() are resumed as many times as necessary for them to run.
  • Garbage collection is re-enabled in all cases where it was disabled through ObjectReference.disableCollection().
Any current method invocations executing in the target VM are continued after the disconnection. Upon completion of any such method invocation, the invoking thread continues from the location where it was originally stopped.

Resources originating in this VirtualMachine (ObjectReferences, ReferenceTypes, etc.) will become invalid.

exit

void exit(int exitCode)
Causes the mirrored VM to terminate with the given error code. All resources associated with this VirtualMachine are freed. If the mirrored VM is remote, the communication channel to it will be closed. Resources originating in this VirtualMachine (ObjectReferences, ReferenceTypes, etc.) will become invalid.

Threads running in the mirrored VM are abruptly terminated. A thread death exception is not thrown and finally blocks are not run.

Parameters:
exitCode - the exit code for the target VM. On some platforms, the exit code might be truncated, for example, to the lower order 8 bits.
Throws:
VMCannotBeModifiedException - if the VirtualMachine is read-only - see canBeModified().

canWatchFieldModification

boolean canWatchFieldModification()
Determines if the target VM supports watchpoints for field modification.

Returns:
true if the feature is supported, false otherwise.

canWatchFieldAccess

boolean canWatchFieldAccess()
Determines if the target VM supports watchpoints for field access.

Returns:
true if the feature is supported, false otherwise.

canGetBytecodes

boolean canGetBytecodes()
Determines if the target VM supports the retrieval of a method's bytecodes.

Returns:
true if the feature is supported, false otherwise.

canGetSyntheticAttribute

boolean canGetSyntheticAttribute()
Determines if the target VM supports the query of the synthetic attribute of a method or field.

Returns:
true if the feature is supported, false otherwise.

canGetOwnedMonitorInfo

boolean canGetOwnedMonitorInfo()
Determines if the target VM supports the retrieval of the monitors owned by a thread.

Returns:
true if the feature is supported, false otherwise.

canGetCurrentContendedMonitor

boolean canGetCurrentContendedMonitor()
Determines if the target VM supports the retrieval of the monitor for which a thread is currently waiting.

Returns:
true if the feature is supported, false otherwise.

canGetMonitorInfo

boolean canGetMonitorInfo()
Determines if the target VM supports the retrieval of the monitor information for an object.

Returns:
true if the feature is supported, false otherwise.

canUseInstanceFilters

boolean canUseInstanceFilters()
Determines if the target VM supports filtering events by specific instance object. For example, see BreakpointRequest.addInstanceFilter(com.sun.jdi.ObjectReference).

Returns:
true if the feature is supported, false otherwise.

canRedefineClasses

boolean canRedefineClasses()
Determines if the target VM supports any level of class redefinition.

Returns:
true if the feature is supported, false otherwise.
Since:
1.4
See Also:
redefineClasses(java.util.Map)

canAddMethod

boolean canAddMethod()
Determines if the target VM supports the addition of methods when performing class redefinition.

Returns:
true if the feature is supported, false otherwise.
Since:
1.4
See Also:
redefineClasses(java.util.Map)

canUnrestrictedlyRedefineClasses

boolean canUnrestrictedlyRedefineClasses()
Determines if the target VM supports unrestricted changes when performing class redefinition.

Returns:
true if the feature is supported, false otherwise.
Since:
1.4
See Also:
redefineClasses(java.util.Map)

canPopFrames

boolean canPopFrames()
Determines if the target VM supports popping frames of a threads stack.

Returns:
true if the feature is supported, false otherwise.
Since:
1.4
See Also:
ThreadReference.popFrames(com.sun.jdi.StackFrame)

canGetSourceDebugExtension

boolean canGetSourceDebugExtension()
Determines if the target VM supports getting the source debug extension.

Returns:
true if the feature is supported, false otherwise.
Since:
1.4
See Also:
ReferenceType.sourceDebugExtension()

canRequestVMDeathEvent

boolean canRequestVMDeathEvent()
Determines if the target VM supports the creation of VMDeathRequests.

Returns:
true if the feature is supported, false otherwise.
Since:
1.4
See Also:
EventRequestManager.createVMDeathRequest()

canGetMethodReturnValues

boolean canGetMethodReturnValues()
Determines if the target VM supports the inclusion of return values in MethodExitEvents.

Returns:
true if the feature is supported, false otherwise.
Since:
1.6
See Also:
EventRequestManager.createMethodExitRequest()

canGetInstanceInfo

boolean canGetInstanceInfo()
Determines if the target VM supports the accessing of class instances, instance counts, and referring objects.

Returns:
true if the feature is supported, false otherwise.
Since:
1.6
See Also:
instanceCounts(java.util.List),
ReferenceType.instances(long),
ObjectReference.referringObjects(long)

canUseSourceNameFilters

boolean canUseSourceNameFilters()
Determines if the target VM supports the filtering of class prepare events by source name. see ClassPrepareRequest.addSourceNameFilter(java.lang.String).

Returns:
true if the feature is supported, false otherwise.
Since:
1.6

canForceEarlyReturn

boolean canForceEarlyReturn()
Determines if the target VM supports the forcing of a method to return early.

Returns:
true if the feature is supported, false otherwise.
Since:
1.6
See Also:
ThreadReference.forceEarlyReturn(Value)

canBeModified

boolean canBeModified()
Determines if the target VM is a read-only VM. If a method which would modify the state of the VM is called on a read-only VM, then VMCannotBeModifiedException is thrown.

Returns:
true if the feature is supported, false otherwise.
Since:
1.5

canRequestMonitorEvents

boolean canRequestMonitorEvents()
Determines if the target VM supports the creation of MonitorContendedEnterRequests. MonitorContendedEnteredRequests. MonitorWaitRequests. MonitorWaitedRequests.

Returns:
true if the feature is supported, false otherwise.
Since:
1.6
See Also:
EventRequestManager.createMonitorContendedEnterRequest(),
EventRequestManager.createMonitorContendedEnteredRequest(),
EventRequestManager.createMonitorWaitRequest(),
EventRequestManager.createMonitorWaitedRequest()

canGetMonitorFrameInfo

boolean canGetMonitorFrameInfo()
Determines if the target VM supports getting which frame has acquired a monitor.

Returns:
true if the feature is supported, false otherwise.
Since:
1.6
See Also:
ThreadReference.ownedMonitorsAndFrames()

canGetClassFileVersion

boolean canGetClassFileVersion()
Determines if the target VM supports reading class file major and minor versions.

Returns:
true if the feature is supported, false otherwise.
Since:
1.6
See Also:
ReferenceType.majorVersion(), ReferenceType.minorVersion()

canGetConstantPool

boolean canGetConstantPool()
Determines if the target VM supports getting constant pool information of a class.

Returns:
true if the feature is supported, false otherwise.
Since:
1.6
See Also:
ReferenceType.constantPoolCount(), ReferenceType.constantPool()

setDefaultStratum

void setDefaultStratum(String stratum)
Set this VM's default stratum (see Location for a discussion of strata). Overrides the per-class default set in the class file.

Affects location queries (such as, Location.sourceName()) and the line boundaries used in single stepping.

Parameters:
stratum - the stratum to set as VM default, or null to use per-class defaults.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation.
Since:
1.4

getDefaultStratum

String getDefaultStratum()
Return this VM's default stratum.

Returns:
null (meaning that the per-class default - ReferenceType.defaultStratum() - should be used) unless the default stratum has been set with setDefaultStratum(String).
Since:
1.4
See Also:
setDefaultStratum(String), ReferenceType.defaultStratum()

instanceCounts

long[] instanceCounts(List<? extends ReferenceType> refTypes)
Returns the number of instances of each ReferenceType in the 'refTypes' list. Only instances that are reachable for the purposes of garbage collection are counted.

Not all target virtual machines support this operation. Use canGetInstanceInfo() to determine if the operation is supported.

Parameters:
refTypes - the list of ReferenceType objects for which counts are to be obtained.
Returns:
an array of long containing one element for each element in the 'refTypes' list. Element i of the array contains the number of instances in the target VM of the ReferenceType at position i in the 'refTypes' list. If the 'refTypes' list is empty, a zero-length array is returned. If a ReferenceType in refTypes has been garbage collected, zero is returned for its instance count.
Throws:
UnsupportedOperationException - if the target virtual machine does not support this operation - see canGetInstanceInfo()
NullPointerException - if the 'refTypes' list is null.
Since:
1.6
See Also:
ReferenceType.instances(long), ObjectReference.referringObjects(long)

description

String description()
Returns text information on the target VM and the debugger support that mirrors it. No specific format for this information is guaranteed. Typically, this string contains version information for the target VM and debugger interfaces. More precise information on VM and JDI versions is available through version(), VirtualMachineManager.majorInterfaceVersion(), and VirtualMachineManager.minorInterfaceVersion()

Returns:
the description.

version

String version()
Returns the version of the Java Runtime Environment in the target VM as reported by the property java.version. For obtaining the JDI interface version, use VirtualMachineManager.majorInterfaceVersion() and VirtualMachineManager.minorInterfaceVersion()

Returns:
the target VM version.

name

String name()
Returns the name of the target VM as reported by the property java.vm.name.

Returns:
the target VM name.

setDebugTraceMode

void setDebugTraceMode(int traceFlags)
Traces the activities performed by the com.sun.jdi implementation. All trace information is output to System.err. The given trace flags are used to limit the output to only the information desired. The given flags are in effect and the corresponding trace will continue until the next call to this method.

Output is implementation dependent and trace mode may be ignored.

Parameters:
traceFlags - identifies which kinds of tracing to enable.
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VirtualMachineManager

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface VirtualMachineManager

public interface VirtualMachineManager

A manager of connections to target virtual machines. The VirtualMachineManager allows one application to debug multiple target VMs. (Note that the converse is not supported; a target VM can be debugged by only one debugger application.) This interface contains methods to manage connections to remote target VMs and to obtain the VirtualMachine mirror for available target VMs.

Connections can be made using one of several different Connector objects. Each connector encapsulates a different way of connecting the debugger with a target VM.

The VirtualMachineManager supports many different scenarios for connecting a debugger to a virtual machine. Four examples are presented in the table below. The examples use the command line syntax in Sun's implementation. Some Connector implementations may require slightly different handling than presented below.

Scenario Description
Debugger launches target VM (simplest, most-common scenario) Debugger calls the LaunchingConnector.launch(java.util.Map) method of the default connector, obtained with defaultConnector(). The target VM is launched, and a connection between that VM and the debugger is established. A VirtualMachine mirror is returned.

Or, for more control

  • Debugger selects a connector from the list returned by launchingConnectors() with desired characteristics (for example, transport type, etc.).
  • Debugger calls the LaunchingConnector.launch(java.util.Map) method of the selected connector. The target VM is launched, and a connection between that VM and the debugger is established. A VirtualMachine mirror is returned.
Debugger attaches to previously-running VM
  • Target VM is launched using the options -agentlib:jdwp=transport=xxx,server=y
  • Target VM generates and outputs the tranport-specific address at which it will listen for a connection.
  • Debugger is launched. Debugger selects a connector in the list returned by attachingConnectors() matching the transport with the name "xxx".
  • Debugger presents the default connector parameters (obtained through Connector.defaultArguments()) to the end user, allowing the user to fill in the transport-specific address generated by the target VM.
  • Debugger calls the AttachingConnector.attach(java.util.Map) method of the selected to attach to the target VM. A VirtualMachine mirror is returned.
Target VM attaches to previously-running debugger
  • At startup, debugger selects one or more connectors from the list returned by listeningConnectors() for one or more transports.
  • Debugger calls the ListeningConnector.startListening(java.util.Map) method for each selected connector. For each call, a transport-specific address string is generated and returned. The debugger makes the transport names and corresponding address strings available to the end user.
  • Debugger calls ListeningConnector.accept(java.util.Map) for each selected connector to wait for a target VM to connect.
  • Later, target VM is launched by end user with the options -agentlib:jdwp=transport=xxx,address=yyy where "xxx" the transport for one of the connectors selected by the the debugger and "yyy" is the address generated by ListeningConnector.accept(java.util.Map) for that transport.
  • Debugger's call to ListeningConnector.accept(java.util.Map) returns a VirtualMachine mirror.
            •
    Target VM launches debugger (sometimes called "Just-In-Time" debugging)
  • Target VM is launched with the options -agentlib:jdwp=launch=cmdline,onuncaught=y,transport=xxx,server=y
  • Later, an uncaught exception is thrown in the target VM. The target VM generates the tranport-specific address at which it will listen for a connection.
  • Target VM launches the debugger with the following items concatenated together (separated by spaces) to form the command line:
    • The launch= value
    • The transport= value
    • The generated transport-specific address at which VM is listening for debugger connection.
  • Upon launch, debugger selects a connector in the list returned by attachingConnectors() matching the transport with the name "xxx".
  • Debugger changes the default connector parameters (obtained through Connector.defaultArguments()) to specify the transport specific address at which the VM is listenig. Optionally, other connector arguments can be presented to the user.
  • Debugger calls the AttachingConnector.attach(java.util.Map) method of the selected to attach to the target VM. A VirtualMachine mirror is returned.

    • Connectors are created at start-up time. That is, they are created the first time that Bootstrap.virtualMachineManager() is invoked. The list of all Connectors created at start-up time can be obtained from the VirtualMachineManager by invoking the allConnectors method.

    Connectors are created at start-up time if they are installed on the platform. In addition, Connectors are created automatically by the VirtualMachineManager to encapsulate any TransportService implementations that are installed on the platform. These two mechanisms for creating Connectors are described here.

    A Connector is installed on the platform if it is installed in a jar file that is visible to the defining class loader of the Connector type, and that jar file contains a provider configuration file named com.sun.jdi.connect.Connector in the resource directory META-INF/services, and the provider configuration file lists the full-qualified class name of the Connector implementation. A Connector is a class that implements the Connector interface. More appropriately the class implements one of the specific Connector types, namely AttachingConnector, ListeningConnector, or LaunchingConnector. The format of the provider configuration file is one fully-qualified class name per line. Space and tab characters surrounding each class, as well as blank lines are ignored. The comment character is '#' (0x23), and on each line all characters following the first comment character are ignored. The file must be encoded in UTF-8.

    At start-up time the VirtualMachineManager attempts to load and instantiate (using the no-arg constructor) each class listed in the provider configuration file. Exceptions thrown when loading or creating the Connector are caught and ignored. In other words, the start-up process continues despite of errors.

    In addition to Connectors installed on the platform the VirtualMachineManager will also create Connectors to encapsulate any TransportService implementations that are installed on the platform. A TransportService is installed on the platform if it installed in a jar file that is visible to the defining class loader for the TransportService type, and that jar file contains a provider configuration file named com.sun.jdi.connect.spi.TransportService in the resource directory META-INF/services, and the provider configuration file lists the the full-qualified class name of the TransportService implementation. A TransportService is a concrete sub-class of TransportService. The format of the provider configuration file is the same as the provider configuration file for Connectors except that each class listed must be the fully-qualified class name of a class that implements the TransportService interface.

    For each TransportService installed on the platform, the VirtualMachineManager creates a corresponding AttachingConnector and ListeningConnector. These Connectors are created to encapsulate a Transport that in turn encapsulates the TransportService. The AttachingConnector will be named based on the name of the transport service concatenated with the string Attach. For example, if the transport service name() method returns telepathic then the AttachingConnector will be named telepathicAttach. Similiarly the ListeningConnector will be named with the string Listen tagged onto the name of the transport service. The description() method of both the AttachingConnector, and the ListeningConnector, will delegate to the description() method of the underlying transport service. Both the AttachingConnector and the ListeningConnector will have two Connector Arguments. A StringArgument named address is the connector argument to specify the address to attach too, or to listen on. A IntegerArgument named timeout is the connector argument to specify the timeout when attaching, or accepting. The timeout connector may be ignored depending on if the transport service supports an attach timeout or accept timeout.

    Initialization of the virtual machine manager will fail, that is Bootstrap.virtualMachineManager() will throw an error if the virtual machine manager is unable to create any connectors.

    Since:
    1.3

    Method Summary
List<Connector> | allConnectors() Returns the list of all known Connector objects.
List<AttachingConnector> | attachingConnectors() Returns the list of known AttachingConnector objects.
List<VirtualMachine> | connectedVirtualMachines() Lists all target VMs which are connected to the debugger.
VirtualMachine | createVirtualMachine(Connection connection) Creates a new virtual machine.
VirtualMachine | createVirtualMachine(Connection connection, Process process) Create a virtual machine mirror for a target VM.
LaunchingConnector | defaultConnector() Identifies the default connector.
List<LaunchingConnector> | launchingConnectors() Returns the list of known LaunchingConnector objects.
List<ListeningConnector> | listeningConnectors() Returns the list of known ListeningConnector objects.
int | majorInterfaceVersion() Returns the major version number of the JDI interface.
int | minorInterfaceVersion() Returns the minor version number of the JDI interface.

    Method Detail

    defaultConnector

    LaunchingConnector defaultConnector()
    Identifies the default connector. This connector should be used as the launching connector when selection of a connector with specific characteristics is unnecessary.

    Returns:
    the default LaunchingConnector

    launchingConnectors

    List<LaunchingConnector> launchingConnectors()
    Returns the list of known LaunchingConnector objects. Any of the returned objects can be used to launch a new target VM and immediately create a VirtualMachine mirror for it. Note that a target VM launched by a launching connector is not guaranteed to be stable until after the VMStartEvent has been received.

    Returns:
    a list of LaunchingConnector objects.

    attachingConnectors

    List<AttachingConnector> attachingConnectors()
    Returns the list of known AttachingConnector objects. Any of the returned objects can be used to attach to an existing target VM and create a VirtualMachine mirror for it.

    Returns:
    a list of AttachingConnector objects.

    listeningConnectors

    List<ListeningConnector> listeningConnectors()
    Returns the list of known ListeningConnector objects. Any of the returned objects can be used to listen for a connection initiated by a target VM and create a VirtualMachine mirror for it.

    Returns:
    a list of ListeningConnector objects.

    allConnectors

    List<Connector> allConnectors()
    Returns the list of all known Connector objects.

    Returns:
    a list of Connector objects.

    connectedVirtualMachines

    List<VirtualMachine> connectedVirtualMachines()
    Lists all target VMs which are connected to the debugger. The list includes VirtualMachine instances for any target VMs which initiated a connection and any target VMs to which this manager has initiated a connection. A target VM will remain in this list until the VM is disconnected. VMDisconnectEvent is placed in the event queue after the VM is removed from the list.

    Returns:
    a list of VirtualMachine objects, each mirroring a target VM.

    majorInterfaceVersion

    int majorInterfaceVersion()
    Returns the major version number of the JDI interface. See VirtualMachine.version() target VM version and information and VirtualMachine.description() more version information.

    Returns:
    the integer major version number.

    minorInterfaceVersion

    int minorInterfaceVersion()
    Returns the minor version number of the JDI interface. See VirtualMachine.version() target VM version and information and VirtualMachine.description() more version information.

    Returns:
    the integer minor version number

    createVirtualMachine

    VirtualMachine createVirtualMachine(Connection connection,
                                    Process process)
                                    throws IOException
    Create a virtual machine mirror for a target VM.

    Creates a virtual machine mirror for a target VM for which a Connection already exists. A Connection is created when a Connector establishes a connection and successfully handshakes with a target VM. A Connector can then use this method to create a virtual machine mirror to represent the composite state of the target VM.

    The process argument specifies the Process object for the taget VM. It may be specified as null. If the target VM is launched by a LaunchingConnector the process argument should be specified, otherwise calling VirtualMachine.process() on the created virtual machine will return null.

    This method exists so that Connectors may create a virtual machine mirror when a connection is established to a target VM. Only developers creating new Connector implementations should need to make direct use of this method.

    Parameters:
    connection - The open connection to the target VM.
    process - If launched, the Process object for the target VM. null if not launched.
    Returns:
    new virtual machine representing the target VM.
    Throws:
    IOException - if an I/O error occurs
    IllegalStateException - if the connection is not open
    Since:
    1.5
    See Also:
    Connection.isOpen(), VirtualMachine.process()

    createVirtualMachine

    VirtualMachine createVirtualMachine(Connection connection)
                                    throws IOException
    Creates a new virtual machine.

    This convenience method works as if by invoking createVirtualMachine(Connection, Process) method and specifying null as the process argument.

    This method exists so that Connectors may create a virtual machine mirror when a connection is established to a target VM. Only developers creating new Connector implementations should need to make direct use of this method.

    Returns:
    the new virtual machine
    Throws:
    IOException - if an I/O error occurs
    IllegalStateException - if the connection is not open
    Since:
    1.5
    Overview Package Class Use Tree Index Help
            Java Debug Interface
    PREV CLASS NEXT CLASS FRAMES NO FRAMES
    SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VMCannotBeModifiedException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class VMCannotBeModifiedException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  java.lang.UnsupportedOperationException
                    extended by  com.sun.jdi.VMCannotBeModifiedException
All Implemented Interfaces:
Serializable
public class VMCannotBeModifiedException
extends UnsupportedOperationException

Thrown to indicate that the operation is invalid because it would modify the VM and the VM is read-only. See VirtualMachine.canBeModified().

Since:
1.5
See Also:
Serialized Form

Constructor Summary
VMCannotBeModifiedException()
VMCannotBeModifiedException(String s)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

VMCannotBeModifiedException

public VMCannotBeModifiedException()

VMCannotBeModifiedException

public VMCannotBeModifiedException(String s)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VMDisconnectedException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class VMDisconnectedException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  com.sun.jdi.VMDisconnectedException
All Implemented Interfaces:
Serializable
public class VMDisconnectedException
extends RuntimeException

Unchecked exception thrown to indicate that the requested operation cannot be completed because there is no longer a connection to the target VM.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
VMDisconnectedException()
VMDisconnectedException(String message)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

VMDisconnectedException

public VMDisconnectedException()

VMDisconnectedException

public VMDisconnectedException(String message)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VMMismatchException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class VMMismatchException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  com.sun.jdi.VMMismatchException
All Implemented Interfaces:
Serializable
public class VMMismatchException
extends RuntimeException

Thrown to indicate that the requested operation cannot be completed because the a mirror from one target VM is being combined with a mirror from another target VM.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
VMMismatchException()
VMMismatchException(String s)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

VMMismatchException

public VMMismatchException()

VMMismatchException

public VMMismatchException(String s)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VMOutOfMemoryException

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Class VMOutOfMemoryException

java.lang.Object
    extended by  java.lang.Throwable
        extended by  java.lang.Exception
            extended by  java.lang.RuntimeException
                extended by  com.sun.jdi.VMOutOfMemoryException
All Implemented Interfaces:
Serializable
public class VMOutOfMemoryException
extends RuntimeException

Thrown to indicate that the requested operation cannot be completed because the target VM has run out of memory.

Since:
1.3
See Also:
Serialized Form

Constructor Summary
VMOutOfMemoryException()
VMOutOfMemoryException(String s)
Method Summary
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

VMOutOfMemoryException

public VMOutOfMemoryException()

VMOutOfMemoryException

public VMOutOfMemoryException(String s)
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD


VoidValue

Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface VoidValue

All Superinterfaces:
Mirror, Value
public interface VoidValue
extends Value

Provides access to a primitive void value in the target VM.

Since:
1.3

Method Summary
boolean | equals(Object obj) Compares the specified Object with this VoidValue for equality.
int | hashCode() Returns the hash code value for this VoidValue.
Methods inherited from interface com.sun.jdi.Value
type
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine

Method Detail

equals

boolean equals(Object obj)
Compares the specified Object with this VoidValue for equality.

Overrides:
equals in class Object
Returns:
true if the Object is a VoidValue; false otherwise.

hashCode

int hashCode()
Returns the hash code value for this VoidValue.

Overrides:
hashCode in class Object
Returns:
the hash code
Overview Package Class Use Tree Index Help
Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD


JAVA PLATFORM, STANDARD EDITION

 Specification: JAVA PLATFORM, STANDARD EDITION (Java SE)

Version: 6
Status: Final Release
Release: December 11, 2006

Copyright 2006 Sun Microsystems, Inc.
4150 Network Circle, Santa Clara, California 95054, U.S.A
All rights reserved.

NOTICE
The Specification is protected by copyright and the information described therein may be protected by one or more U.S. patents, foreign patents, or pending applications. Except as provided under the following license, no part of the Specification may be reproduced in any form by any means without the prior written authorization of Sun Microsystems, Inc. ("Sun") and its licensors, if any. Any use of the Specification and the information described therein will be governed by the terms and conditions of this Agreement.

Subject to the terms and conditions of this license, including your compliance with Paragraphs 1, 2 and 3 below, Sun hereby grants you a fully-paid, non-exclusive, non-transferable, limited license (without the right to sublicense) under Sun's intellectual property rights to:

1.Review the Specification for the purposes of evaluation. This includes: (i) developing implementations of the Specification for your internal, non-commercial use; (ii) discussing the Specification with any third party; and (iii) providing to other licensees (under this or a substantially similar version of this Agreement) of the Specification limited excerpts of text to the extent relevant to the point[s] under discussion;

2.Distribute implementations of the Specification to third parties for their testing and evaluation use, provided that any such implementation: (i) fully implements the Specification including all its required interfaces and functionality; (ii) does not modify, subset, superset or otherwise extend the Licensor Name Space, or include any public or protected packages, classes, Java interfaces, fields or methods within the Licensor Name Space other than those required/authorized by the Specification or Specifications being implemented; (iii) is clearly and prominently marked with the word "UNTESTED" or "INCOMPATIBLE" or "UNSTABLE" or "BETA" in any list of available builds and in every link initiating its download, where the list or link is under Licensee's control; and (iv) includes the following notice: "This is an implementation of an early-draft specification developed under the Java Community Process (JCP) and is made available for testing and evaluation purposes only. The code is not compatible with any specification of the JCP."

3.Distribute applications written to the Specification to third parties for their testing and evaluation use, provided that any such application includes the following notice: "This is an application written to interoperate with an early-draft specification developed under the Java Community Process (JCP) and is made available for testing and evaluation purposes only. The code is not compatible with any specification of the JCP." The grant set forth above concerning your distribution of implementations of the specification is contingent upon your agreement to terminate development and distribution of your implementation of early draft upon final completion of the specification. If you fail to do so, the foregoing grant shall be considered null and void. Other than this limited license, you acquire no right, title or interest in or to the Specification or any other Sun intellectual property, and the Specification may only be used in accordance with the license terms set forth herein. This license will expire on the earlier of: (a) two (2) years from the date of Release listed above; (b) the date on which the final version of the Specification is publicly released; or (c) the date on which the Java Specification Request (JSR) to which the Specification corresponds is withdrawn. In addition, this license will terminate immediately without notice from Sun if you fail to comply with any provision of this license. Upon termination, you must cease use of or destroy the Specification. "Licensor Name Space" means the public class or interface declarations whose names begin with "java", "javax", "com.sun" or their equivalents in any subsequent naming convention adopted by Sun through the Java Community Process, or any recognized successors or replacements thereof

TRADEMARKS
No right, title, or interest in or to any trademarks, service marks, or trade names of Sun or Sun's licensors is granted hereunder. Sun, Sun Microsystems, the Sun logo, Java, Java TM Platform, Standard Edition (Java SE) are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

DISCLAIMER OF WARRANTIES
THE SPECIFICATION IS PROVIDED "AS IS" AND IS EXPERIMENTAL AND MAY CONTAIN DEFECTS OR DEFICIENCIES WHICH CANNOT OR WILL NOT BE CORRECTED BY SUN. SUN MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE OR THAT ANY PRACTICE OR IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This document does not represent any commitment to release or implement any portion of the Specification in any product.

THE SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEW VERSIONS OF THE SPECIFICATION, IF ANY. SUN MAY MAKE IMPROVEMENTS AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THE SPECIFICATION AT ANY TIME. Any use of such changes in the Specification will be governed by the then-current license for the applicable version of the Specification.

LIMITATION OF LIABILITY
TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO ANY FURNISHING, PRACTICING, MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF SUN AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

You will hold Sun (and its licensors) harmless from any claims based on your use of the Specification for any purposes other than the limited right of evaluation as described above, and from any claims that later versions or releases of any Specification furnished to you are incompatible with the Specification provided to you under this license.

RESTRICTED RIGHTS LEGEND
If this Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), then the Government's rights in the Software and accompanying documentation shall be only as set forth in this license; this is in accordance with 48 C.F.R. 227.7201 through 227.7202-4 (for Department of Defense (DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD acquisitions).

REPORT
You may wish to report any ambiguities, inconsistencies or inaccuracies you may find in connection with your evaluation of the Specification ("Feedback"). To the extent that you provide Sun with any Feedback, you hereby: (i) agree that such Feedback is provided on a non-proprietary and non-confidential basis, and (ii) grant Sun a perpetual, non-exclusive, worldwide, fully paid-up, irrevocable license, with the right to sublicense through multiple levels of sublicensees, to incorporate, disclose, and use without limitation the Feedback for any purpose related to the Specification and future versions, implementations, and test suites thereof.

GENERAL TERMS
Any action related to this Agreement will be governed by California law and controlling U.S. federal law. The U.N. Convention for the International Sale of Goods and the choice of law rules of any jurisdiction will not apply.

The Specification is subject to U.S. export control laws and may be subject to export or import regulations in other countries. Licensee agrees to comply strictly with all such laws and regulations and acknowledges that it has the responsibility to obtain such licenses to export, re-export or import as may be required after delivery to Licensee.

Neither party may assign or otherwise transfer any of its rights or obligations under this Agreement, without the prior written consent of the other party, except that Sun may assign this Agreement to an affiliated company.

This Agreement is the parties' entire agreement relating to its subject matter. It supersedes all prior or contemporaneous oral or written communications, proposals, conditions, representations and warranties and prevails over any conflicting or additional terms of any quote, order, acknowledgment, or other communication between the parties relating to its subject matter during the term of this Agreement. No modification to this Agreement will be binding, unless in writing and signed by an authorized representative of each party.


Legal Notices

 Documentation Contents

Proprietary Rights Notice

JavaTM SE Specification License

Documentation Redistribution Policy
(On java.sun.com web site)

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Sun


Properietary Rights Notice

 English:

Copyright © 2006 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved.U.S.
SUN PROPRIETARY/CONFIDENTIAL.

Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. Use is subject to license terms.

This distribution may include materials developed by third parties.Sun, Sun Microsystems, the Sun logo, Java, Jini, Solaris, and Java SE are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. This product is covered and controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited.

Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited.

French:

Copyright © 2006 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, Etats-Unis. Tous droits réservés. L'utilisation est soumise aux termes du contrat de licence.

Cette distribution peut comprendre des composants développés par des tierces parties.Sun, Sun Microsystems, le logo Sun, Java, Jini, Solaris et Java SE sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc. aux Etats-Unis et dans d'autres pays.Ce produit est soumis à la législation américaine en matière de contrôle des exportations et peut être soumis à la règlementation en vigueur dans d'autres pays dans le domaine des exportations et importations. Les utilisations, ou utilisateurs finaux, pour des armes nucléaires,des missiles, des armes biologiques et chimiques ou du nucléaire maritime, directement ou indirectement, sont strictement interdites.

Les exportations ou réexportations vers les pays sous embargo américain, ou vers des entités figurant sur les listes d'exclusion d'exportation américaines, y compris, mais de manière non exhaustive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une façon directe ou indirecte, aux exportations des produits ou des services qui sont régis par la législation américaine en matière de contrôle des exportations et la liste de ressortissants spécifiquement désignés, sont rigoureusement interdites.


Java(tm) Debug Wire Protocol

  • VirtualMachine Command Set (1)
    • Version (1)
    • ClassesBySignature (2)
    • AllClasses (3)
    • AllThreads (4)
    • TopLevelThreadGroups (5)
    • Dispose (6)
    • IDSizes (7)
    • Suspend (8)
    • Resume (9)
    • Exit (10)
    • CreateString (11)
    • Capabilities (12)
    • ClassPaths (13)
    • DisposeObjects (14)
    • HoldEvents (15)
    • ReleaseEvents (16)
    • CapabilitiesNew (17)
    • RedefineClasses (18)
    • SetDefaultStratum (19)
    • AllClassesWithGeneric (20)
    • InstanceCounts (21)
  • ReferenceType Command Set (2)
    • Signature (1)
    • ClassLoader (2)
    • Modifiers (3)
    • Fields (4)
    • Methods (5)
    • GetValues (6)
    • SourceFile (7)
    • NestedTypes (8)
    • Status (9)
    • Interfaces (10)
    • ClassObject (11)
    • SourceDebugExtension (12)
    • SignatureWithGeneric (13)
    • FieldsWithGeneric (14)
    • MethodsWithGeneric (15)
    • Instances (16)
    • ClassFileVersion (17)
    • ConstantPool (18)
  • ClassType Command Set (3)
    • Superclass (1)
    • SetValues (2)
    • InvokeMethod (3)
    • NewInstance (4)
  • ArrayType Command Set (4)
    • NewInstance (1)
  • InterfaceType Command Set (5)
  • Method Command Set (6)
    • LineTable (1)
    • VariableTable (2)
    • Bytecodes (3)
    • IsObsolete (4)
    • VariableTableWithGeneric (5)
  • Field Command Set (8)
  • ObjectReference Command Set (9)
    • ReferenceType (1)
    • GetValues (2)
    • SetValues (3)
    • MonitorInfo (5)
    • InvokeMethod (6)
    • DisableCollection (7)
    • EnableCollection (8)
    • IsCollected (9)
    • ReferringObjects (10)
  • StringReference Command Set (10)
    • Value (1)
  • ThreadReference Command Set (11)
    • Name (1)
    • Suspend (2)
    • Resume (3)
    • Status (4)
    • ThreadGroup (5)
    • Frames (6)
    • FrameCount (7)
    • OwnedMonitors (8)
    • CurrentContendedMonitor (9)
    • Stop (10)
    • Interrupt (11)
    • SuspendCount (12)
    • OwnedMonitorsStackDepthInfo (13)
    • ForceEarlyReturn (14)
  • ThreadGroupReference Command Set (12)
    • Name (1)
    • Parent (2)
    • Children (3)
  • ArrayReference Command Set (13)
    • Length (1)
    • GetValues (2)
    • SetValues (3)
  • ClassLoaderReference Command Set (14)
    • VisibleClasses (1)
  • EventRequest Command Set (15)
    • Set (1)
    • Clear (2)
    • ClearAllBreakpoints (3)
  • StackFrame Command Set (16)
    • GetValues (1)
    • SetValues (2)
    • ThisObject (3)
    • PopFrames (4)
  • ClassObjectReference Command Set (17)
    • ReflectedType (1)
  • Event Command Set (64)
    • Composite (100)
  • Error Constants
  • EventKind Constants
  • ThreadStatus Constants
  • SuspendStatus Constants
  • ClassStatus Constants
  • TypeTag Constants
  • Tag Constants
  • StepDepth Constants
  • StepSize Constants
  • SuspendPolicy Constants
  • InvokeOptions Constants

    VirtualMachine Command Set (1)

    Version Command (1)
    Returns the JDWP version implemented by the target VM. The version string format is implementation dependent.
    Out Data
    (None)
    Reply Data
    string | description | Text information on the VM version
    int | jdwpMajor | Major JDWP Version number
    int | jdwpMinor | Minor JDWP Version number
    string | vmVersion | Target VM JRE version, as in the java.version property
    string | vmName | Target VM name, as in the java.vm.name property
    Error Data
    VM_DEAD The virtual machine is not running.
    ClassesBySignature Command (2)
    Returns reference types for all the classes loaded by the target VM which match the given signature. Multple reference types will be returned if two or more class loaders have loaded a class of the same name. The search is confined to loaded classes only; no attempt is made to load a class of the given signature.
    Out Data
    string signature JNI signature of the class to find (for example, "Ljava/lang/String;").
    Reply Data
    int | classes | Number of reference types that follow.
    Repeated classes times:
    byte | refTypeTag | Kind of following reference type.
    referenceTypeID | typeID | Matching loaded reference type
    int | status | The current class status.
    Error Data
    VM_DEAD The virtual machine is not running.
    AllClasses Command (3)
    Returns reference types for all classes currently loaded by the target VM.
    Out Data
    (None)
    Reply Data
    int | classes | Number of reference types that follow.
    Repeated classes times:
    byte | refTypeTag | Kind of following reference type.
    referenceTypeID | typeID | Loaded reference type
    string | signature | The JNI signature of the loaded reference type
    int | status | The current class status.
    Error Data
    VM_DEAD The virtual machine is not running.
    AllThreads Command (4)
    Returns all threads currently running in the target VM . The returned list contains threads created through java.lang.Thread, all native threads attached to the target VM through JNI, and system threads created by the target VM. Threads that have not yet been started and threads that have completed their execution are not included in the returned list.
    Out Data
    (None)
    Reply Data
    int | threads | Number of threads that follow.
    Repeated threads times:
    threadID | thread | A running thread
    Error Data
    VM_DEAD The virtual machine is not running.
    TopLevelThreadGroups Command (5)
    Returns all thread groups that do not have a parent. This command may be used as the first step in building a tree (or trees) of the existing thread groups.
    Out Data
    (None)
    Reply Data
    int | groups | Number of thread groups that follow.
    Repeated groups times:
    threadGroupID | group | A top level thread group
    Error Data
    VM_DEAD The virtual machine is not running.
    Dispose Command (6)
    Invalidates this virtual machine mirror. The communication channel to the target VM is closed, and the target VM prepares to accept another subsequent connection from this debugger or another debugger, including the following tasks:
    • All event requests are cancelled.
    • All threads suspended by the thread-level resume command or the VM-level resume command are resumed as many times as necessary for them to run.
    • Garbage collection is re-enabled in all cases where it was disabled
    Any current method invocations executing in the target VM are continued after the disconnection. Upon completion of any such method invocation, the invoking thread continues from the location where it was originally stopped.

    Resources originating in this VirtualMachine (ObjectReferences, ReferenceTypes, etc.) will become invalid.

    Out Data
    (None)
    Reply Data
    (None)
    Error Data
    (None)
    IDSizes Command (7)
    Returns the sizes of variably-sized data types in the target VM.The returned values indicate the number of bytes used by the identifiers in command and reply packets.
    Out Data
    (None)
    Reply Data
    int | fieldIDSize | fieldID size in bytes
    int | methodIDSize | methodID size in bytes
    int | objectIDSize | objectID size in bytes
    int | referenceTypeIDSize | referenceTypeID size in bytes
    int | frameIDSize | frameID size in bytes
    Error Data
    VM_DEAD The virtual machine is not running.
    Suspend Command (8)
    Suspends the execution of the application running in the target VM. All Java threads currently running will be suspended.

    Unlike java.lang.Thread.suspend, suspends of both the virtual machine and individual threads are counted. Before a thread will run again, it must be resumed through the VM-level resume command or the thread-level resume command the same number of times it has been suspended.

    Out Data
    (None)
    Reply Data
    (None)
    Error Data
    VM_DEAD The virtual machine is not running.
    Resume Command (9)
    Resumes execution of the application after the suspend command or an event has stopped it. Suspensions of the Virtual Machine and individual threads are counted. If a particular thread is suspended n times, it must resumed n times before it will continue.
    Out Data
    (None)
    Reply Data
    (None)
    Error Data
    (None)
    Exit Command (10)
    Terminates the target VM with the given exit code. On some platforms, the exit code might be truncated, for example, to the low order 8 bits. All ids previously returned from the target VM become invalid. Threads running in the VM are abruptly terminated. A thread death exception is not thrown and finally blocks are not run.
    Out Data
    int exitCode the exit code
    Reply Data
    (None)
    Error Data
    (None)
    CreateString Command (11)
    Creates a new string object in the target VM and returns its id.
    Out Data
    string utf UTF-8 characters to use in the created string.
    Reply Data
    stringID stringObject Created string (instance of java.lang.String)
    Error Data
    VM_DEAD The virtual machine is not running.
    Capabilities Command (12)
    Retrieve this VM's capabilities. The capabilities are returned as booleans, each indicating the presence or absence of a capability. The commands associated with each capability will return the NOT_IMPLEMENTED error if the cabability is not available.
    Out Data
    (None)
    Reply Data
    boolean | canWatchFieldModification | Can the VM watch field modification, and therefore can it send the Modification Watchpoint Event?
    boolean | canWatchFieldAccess | Can the VM watch field access, and therefore can it send the Access Watchpoint Event?
    boolean | canGetBytecodes | Can the VM get the bytecodes of a given method?
    boolean | canGetSyntheticAttribute | Can the VM determine whether a field or method is synthetic? (that is, can the VM determine if the method or the field was invented by the compiler?)
    boolean | canGetOwnedMonitorInfo | Can the VM get the owned monitors infornation for a thread?
    boolean | canGetCurrentContendedMonitor | Can the VM get the current contended monitor of a thread?
    boolean | canGetMonitorInfo | Can the VM get the monitor information for a given object?
    Error Data
    VM_DEAD The virtual machine is not running.
    ClassPaths Command (13)
    Retrieve the classpath and bootclasspath of the target VM. If the classpath is not defined, returns an empty list. If the bootclasspath is not defined returns an empty list.
    Out Data
    (None)
    Reply Data
    string | baseDir | Base directory used to resolve relative paths in either of the following lists.
    int | classpaths | Number of paths in classpath.
    Repeated classpaths times:
    string | path | One component of classpath
    int | bootclasspaths | Number of paths in bootclasspath.
    Repeated bootclasspaths times:
    string | path | One component of bootclasspath
    Error Data
    VM_DEAD The virtual machine is not running.
    DisposeObjects Command (14)
    Releases a list of object IDs. For each object in the list, the following applies. The count of references held by the back-end (the reference count) will be decremented by refCnt. If thereafter the reference count is less than or equal to zero, the ID is freed. Any back-end resources associated with the freed ID may be freed, and if garbage collection was disabled for the object, it will be re-enabled. The sender of this command promises that no further commands will be sent referencing a freed ID.

    Use of this command is not required. If it is not sent, resources associated with each ID will be freed by the back-end at some time after the corresponding object is garbage collected. It is most useful to use this command to reduce the load on the back-end if a very large number of objects has been retrieved from the back-end (a large array, for example) but may not be garbage collected any time soon.

    IDs may be re-used by the back-end after they have been freed with this command.This description assumes reference counting, a back-end may use any implementation which operates equivalently.

    Out Data
    int | requests | Number of object dispose requests that follow
    Repeated requests times:
    objectID | object | The object ID
    int | refCnt | The number of times this object ID has been part of a packet received from the back-end. An accurate count prevents the object ID from being freed on the back-end if it is part of an incoming packet, not yet handled by the front-end.
    Reply Data
    (None)
    Error Data
    (None)
    HoldEvents Command (15)
    Tells the target VM to stop sending events. Events are not discarded; they are held until a subsequent ReleaseEvents command is sent. This command is useful to control the number of events sent to the debugger VM in situations where very large numbers of events are generated. While events are held by the debugger back-end, application execution may be frozen by the debugger back-end to prevent buffer overflows on the back end. Responses to commands are never held and are not affected by this command. If events are already being held, this command is ignored.
    Out Data
    (None)
    Reply Data
    (None)
    Error Data
    (None)
    ReleaseEvents Command (16)
    Tells the target VM to continue sending events. This command is used to restore normal activity after a HoldEvents command. If there is no current HoldEvents command in effect, this command is ignored.
    Out Data
    (None)
    Reply Data
    (None)
    Error Data
    (None)
    CapabilitiesNew Command (17)
    Retrieve all of this VM's capabilities. The capabilities are returned as booleans, each indicating the presence or absence of a capability. The commands associated with each capability will return the NOT_IMPLEMENTED error if the cabability is not available.Since JDWP version 1.4.
    Out Data
    (None)
    Reply Data
    boolean | canWatchFieldModification | Can the VM watch field modification, and therefore can it send the Modification Watchpoint Event?
    boolean | canWatchFieldAccess | Can the VM watch field access, and therefore can it send the Access Watchpoint Event?
    boolean | canGetBytecodes | Can the VM get the bytecodes of a given method?
    boolean | canGetSyntheticAttribute | Can the VM determine whether a field or method is synthetic? (that is, can the VM determine if the method or the field was invented by the compiler?)
    boolean | canGetOwnedMonitorInfo | Can the VM get the owned monitors infornation for a thread?
    boolean | canGetCurrentContendedMonitor | Can the VM get the current contended monitor of a thread?
    boolean | canGetMonitorInfo | Can the VM get the monitor information for a given object?
    boolean | canRedefineClasses | Can the VM redefine classes?
    boolean | canAddMethod | Can the VM add methods when redefining classes?
    boolean | canUnrestrictedlyRedefineClasses | Can the VM redefine classesin arbitrary ways?
    boolean | canPopFrames | Can the VM pop stack frames?
    boolean | canUseInstanceFilters | Can the VM filter events by specific object?
    boolean | canGetSourceDebugExtension | Can the VM get the source debug extension?
    boolean | canRequestVMDeathEvent | Can the VM request VM death events?
    boolean | canSetDefaultStratum | Can the VM set a default stratum?
    boolean | canGetInstanceInfo | Can the VM return instances, counts of instances of classes and referring objects?
    boolean | canRequestMonitorEvents | Can the VM request monitor events?
    boolean | canGetMonitorFrameInfo | Can the VM get monitors with frame depth info?
    boolean | canUseSourceNameFilters | Can the VM filter class prepare events by source name?
    boolean | canGetConstantPool | Can the VM return the constant pool information?
    boolean | canForceEarlyReturn | Can the VM force early return from a method?
    boolean | reserved22 | Reserved for future capability
    boolean | reserved23 | Reserved for future capability
    boolean | reserved24 | Reserved for future capability
    boolean | reserved25 | Reserved for future capability
    boolean | reserved26 | Reserved for future capability
    boolean | reserved27 | Reserved for future capability
    boolean | reserved28 | Reserved for future capability
    boolean | reserved29 | Reserved for future capability
    boolean | reserved30 | Reserved for future capability
    boolean | reserved31 | Reserved for future capability
    boolean | reserved32 | Reserved for future capability
    Error Data
    VM_DEAD The virtual machine is not running.
    RedefineClasses Command (18)
    Installs new class definitions. If there are active stack frames in methods of the redefined classes in the target VM then those active frames continue to run the bytecodes of the original method. These methods are considered obsolete - see IsObsolete. The methods in the redefined classes will be used for new invokes in the target VM. The original method ID refers to the redefined method. All breakpoints in the redefined classes are cleared.If resetting of stack frames is desired, the PopFrames command can be used to pop frames with obsolete methods.

    Requires canRedefineClasses capability - see CapabilitiesNew. In addition to the canRedefineClasses capability, the target VM must have the canAddMethod capability to add methods when redefining classes, or the canUnrestrictedlyRedefineClasses to redefine classes in arbitrary ways.

    Out Data
    int | classes | Number of reference types that follow.
    Repeated classes times:
    referenceTypeID | refType | The reference type.
    int | classfile | Number of bytes defining class (below)
    Repeated classfile times:
    byte | classbyte | byte in JVM class file format.
    Reply Data
    (None)
    Error Data
    INVALID_CLASS | One of the refTypes is not the ID of a reference type.
    INVALID_OBJECT | One of the refTypes is not a known ID.
    UNSUPPORTED_VERSION | A class file has a version number not supported by this VM.
    INVALID_CLASS_FORMAT | The virtual machine attempted to read a class file and determined that the file is malformed or otherwise cannot be interpreted as a class file.
    CIRCULAR_CLASS_DEFINITION | A circularity has been detected while initializing a class.
    FAILS_VERIFICATION | The verifier detected that a class file, though well formed, contained some sort of internal inconsistency or security problem.
    NAMES_DONT_MATCH | The class name defined in the new class file is different from the name in the old class object.
    NOT_IMPLEMENTED | No aspect of this functionality is implemented (CapabilitiesNew.canRedefineClasses is false)
    ADD_METHOD_NOT_IMPLEMENTED | Adding methods has not been implemented.
    SCHEMA_CHANGE_NOT_IMPLEMENTED | Schema change has not been implemented.
    HIERARCHY_CHANGE_NOT_IMPLEMENTED | A direct superclass is different for the new class version, or the set of directly implemented interfaces is different and canUnrestrictedlyRedefineClasses is false.
    DELETE_METHOD_NOT_IMPLEMENTED | The new class version does not declare a method declared in the old class version and canUnrestrictedlyRedefineClasses is false.
    CLASS_MODIFIERS_CHANGE_NOT_IMPLEMENTED | The new class version has different modifiers and and canUnrestrictedlyRedefineClasses is false.
    METHOD_MODIFIERS_CHANGE_NOT_IMPLEMENTED | A method in the new class version has different modifiers than its counterpart in the old class version and and canUnrestrictedlyRedefineClasses is false.
    VM_DEAD | The virtual machine is not running.
    SetDefaultStratum Command (19)
    Set the default stratum. Requires canSetDefaultStratum capability - see CapabilitiesNew.
    Out Data
    string stratumID default stratum, or empty string to use reference type default.
    Reply Data
    (None)
    Error Data
    NOT_IMPLEMENTED | The functionality is not implemented in this virtual machine.
    VM_DEAD | The virtual machine is not running.
    AllClassesWithGeneric Command (20)
    Returns reference types for all classes currently loaded by the target VM. Both the JNI signature and the generic signature are returned for each class. Generic signatures are described in the signature attribute section in the Java Virtual Machine Specification, 3rd Edition. Since JDWP version 1.5.
    Out Data
    (None)
    Reply Data
    int | classes | Number of reference types that follow.
    Repeated classes times:
    byte | refTypeTag | Kind of following reference type.
    referenceTypeID | typeID | Loaded reference type
    string | signature | The JNI signature of the loaded reference type.
    string | genericSignature | The generic signature of the loaded reference type or an empty string if there is none.
    int | status | The current class status.
    Error Data
    VM_DEAD The virtual machine is not running.
    InstanceCounts Command (21)
    Returns the number of instances of each reference type in the input list. Only instances that are reachable for the purposes of garbage collection are counted. If a reference type is invalid, eg. it has been unloaded, zero is returned for its instance count.

    Since JDWP version 1.6. Requires canGetInstanceInfo capability - see CapabilitiesNew.

    Out Data
    int | refTypesCount | Number of reference types that follow. Must be non-negative.
    Repeated refTypesCount times:
    referenceTypeID | refType | A reference type ID.
    Reply Data
    int | counts | The number of counts that follow.
    Repeated counts times:
    long | instanceCount | The number of instances for the corresponding reference type in 'Out Data'.
    Error Data
    ILLEGAL_ARGUMENT | refTypesCount is less than zero.
    NOT_IMPLEMENTED | The functionality is not implemented in this virtual machine.
    VM_DEAD | The virtual machine is not running.

    ReferenceType Command Set (2)

    Signature Command (1)
    Returns the JNI signature of a reference type. JNI signature formats are described in the Java Native Inteface Specification

    For primitive classes the returned signature is the signature of the corresponding primitive type; for example, "I" is returned as the signature of the class represented by java.lang.Integer.TYPE.

    Out Data
    referenceTypeID refType The reference type ID.
    Reply Data
    string signature The JNI signature for the reference type.
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    VM_DEAD | The virtual machine is not running.
    ClassLoader Command (2)
    Returns the instance of java.lang.ClassLoader which loaded a given reference type. If the reference type was loaded by the system class loader, the returned object ID is null.
    Out Data
    referenceTypeID refType The reference type ID.
    Reply Data
    classLoaderID classLoader The class loader for the reference type.
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    VM_DEAD | The virtual machine is not running.
    Modifiers Command (3)
    Returns the modifiers (also known as access flags) for a reference type. The returned bit mask contains information on the declaration of the reference type. If the reference type is an array or a primitive class (for example, java.lang.Integer.TYPE), the value of the returned bit mask is undefined.
    Out Data
    referenceTypeID refType The reference type ID.
    Reply Data
    int modBits Modifier bits as defined in the VM Specification
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    VM_DEAD | The virtual machine is not running.
    Fields Command (4)
    Returns information for each field in a reference type. Inherited fields are not included. The field list will include any synthetic fields created by the compiler. Fields are returned in the order they occur in the class file.
    Out Data
    referenceTypeID refType The reference type ID.
    Reply Data
    int | declared | Number of declared fields.
    Repeated declared times:
    fieldID | fieldID | Field ID.
    string | name | Name of field.
    string | signature | JNI Signature of field.
    int | modBits | The modifier bit flags (also known as access flags) which provide additional information on the field declaration. Individual flag values are defined in the VM Specification.In addition, The 0xf0000000 bit identifies the field as synthetic, if the synthetic attribute capability is available.
    Error Data
    CLASS_NOT_PREPARED | Class has been loaded but not yet prepared.
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    VM_DEAD | The virtual machine is not running.
    Methods Command (5)
    Returns information for each method in a reference type. Inherited methods are not included. The list of methods will include constructors (identified with the name "<init>"), the initialization method (identified with the name "<clinit>") if present, and any synthetic methods created by the compiler. Methods are returned in the order they occur in the class file.
    Out Data
    referenceTypeID refType The reference type ID.
    Reply Data
    int | declared | Number of declared methods.
    Repeated declared times:
    methodID | methodID | Method ID.
    string | name | Name of method.
    string | signature | JNI signature of method.
    int | modBits | The modifier bit flags (also known as access flags) which provide additional information on the method declaration. Individual flag values are defined in the VM Specification.In addition, The 0xf0000000 bit identifies the method as synthetic, if the synthetic attribute capability is available.
    Error Data
    CLASS_NOT_PREPARED | Class has been loaded but not yet prepared.
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    VM_DEAD | The virtual machine is not running.
    GetValues Command (6)
    Returns the value of one or more static fields of the reference type. Each field must be member of the reference type or one of its superclasses, superinterfaces, or implemented interfaces. Access control is not enforced; for example, the values of private fields can be obtained.
    Out Data
    referenceTypeID | refType | The reference type ID.
    int | fields | The number of values to get
    Repeated fields times:
    fieldID | fieldID | A field to get
    Reply Data
    int | values | The number of values returned, always equal to fields, the number of values to get.
    Repeated values times:
    value | value | The field value
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    INVALID_FIELDID | Invalid field.
    VM_DEAD | The virtual machine is not running.
    SourceFile Command (7)
    Returns the name of source file in which a reference type was declared.
    Out Data
    referenceTypeID refType The reference type ID.
    Reply Data
    string sourceFile The source file name. No path information for the file is included
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    ABSENT_INFORMATION | The source file attribute is absent.
    VM_DEAD | The virtual machine is not running.
    NestedTypes Command (8)
    Returns the classes and interfaces directly nested within this type.Types further nested within those types are not included.
    Out Data
    referenceTypeID refType The reference type ID.
    Reply Data
    int | classes | The number of nested classes and interfaces
    Repeated classes times:
    byte | refTypeTag | Kind of following reference type.
    referenceTypeID | typeID | The nested class or interface ID.
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    VM_DEAD | The virtual machine is not running.
    Status Command (9)
    Returns the current status of the reference type. The status indicates the extent to which the reference type has been initialized, as described in the VM specification. If the class is linked the PREPARED and VERIFIED bits in the returned status bits will be set. If the class is initialized the INITIALIZED bit in the returned status bits will be set. If an error occured during initialization then the ERROR bit in the returned status bits will be set. The returned status bits are undefined for array types and for primitive classes (such as java.lang.Integer.TYPE).
    Out Data
    referenceTypeID refType The reference type ID.
    Reply Data
    int status Status bits:See JDWP.ClassStatus
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    VM_DEAD | The virtual machine is not running.
    Interfaces Command (10)
    Returns the interfaces declared as implemented by this class. Interfaces indirectly implemented (extended by the implemented interface or implemented by a superclass) are not included.
    Out Data
    referenceTypeID refType The reference type ID.
    Reply Data
    int | interfaces | The number of implemented interfaces
    Repeated interfaces times:
    interfaceID | interfaceType | implemented interface.
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    VM_DEAD | The virtual machine is not running.
    ClassObject Command (11)
    Returns the class object corresponding to this type.
    Out Data
    referenceTypeID refType The reference type ID.
    Reply Data
    classObjectID classObject class object.
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    VM_DEAD | The virtual machine is not running.
    SourceDebugExtension Command (12)
    Returns the value of the SourceDebugExtension attribute. Since JDWP version 1.4. Requires canGetSourceDebugExtension capability - see CapabilitiesNew.
    Out Data
    referenceTypeID refType The reference type ID.
    Reply Data
    string extension extension attribute
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    ABSENT_INFORMATION | If the extension is not specified.
    NOT_IMPLEMENTED | The functionality is not implemented in this virtual machine.
    VM_DEAD | The virtual machine is not running.
    SignatureWithGeneric Command (13)
    Returns the JNI signature of a reference type along with the generic signature if there is one. Generic signatures are described in the signature attribute section in the Java Virtual Machine Specification, 3rd Edition. Since JDWP version 1.5.

    Out Data
    referenceTypeID refType The reference type ID.
    Reply Data
    string | signature | The JNI signature for the reference type.
    string | genericSignature | The generic signature for the reference type or an empty string if there is none.
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    VM_DEAD | The virtual machine is not running.
    FieldsWithGeneric Command (14)
    Returns information, including the generic signature if any, for each field in a reference type. Inherited fields are not included. The field list will include any synthetic fields created by the compiler. Fields are returned in the order they occur in the class file. Generic signatures are described in the signature attribute section in the Java Virtual Machine Specification, 3rd Edition. Since JDWP version 1.5.
    Out Data
    referenceTypeID refType The reference type ID.
    Reply Data
    int | declared | Number of declared fields.
    Repeated declared times:
    fieldID | fieldID | Field ID.
    string | name | The name of the field.
    string | signature | The JNI signature of the field.
    string | genericSignature | The generic signature of the field, or an empty string if there is none.
    int | modBits | The modifier bit flags (also known as access flags) which provide additional information on the field declaration. Individual flag values are defined in the VM Specification.In addition, The 0xf0000000 bit identifies the field as synthetic, if the synthetic attribute capability is available.
    Error Data
    CLASS_NOT_PREPARED | Class has been loaded but not yet prepared.
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    VM_DEAD | The virtual machine is not running.
    MethodsWithGeneric Command (15)
    Returns information, including the generic signature if any, for each method in a reference type. Inherited methodss are not included. The list of methods will include constructors (identified with the name "<init>"), the initialization method (identified with the name "<clinit>") if present, and any synthetic methods created by the compiler. Methods are returned in the order they occur in the class file. Generic signatures are described in the signature attribute section in the Java Virtual Machine Specification, 3rd Edition. Since JDWP version 1.5.
    Out Data
    referenceTypeID refType The reference type ID.
    Reply Data
    int | declared | Number of declared methods.
    Repeated declared times:
    methodID | methodID | Method ID.
    string | name | The name of the method.
    string | signature | The JNI signature of the method.
    string | genericSignature | The generic signature of the method, or an empty string if there is none.
    int | modBits | The modifier bit flags (also known as access flags) which provide additional information on the method declaration. Individual flag values are defined in the VM Specification.In addition, The 0xf0000000 bit identifies the method as synthetic, if the synthetic attribute capability is available.
    Error Data
    CLASS_NOT_PREPARED | Class has been loaded but not yet prepared.
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    VM_DEAD | The virtual machine is not running.
    Instances Command (16)
    Returns instances of this reference type. Only instances that are reachable for the purposes of garbage collection are returned.

    Since JDWP version 1.6. Requires canGetInstanceInfo capability - see CapabilitiesNew.

    Out Data
    referenceTypeID | refType | The reference type ID.
    int | maxInstances | Maximum number of instances to return. Must be non-negative. If zero, all instances are returned.
    Reply Data
    int | instances | The number of instances that follow.
    Repeated instances times:
    tagged-objectID | instance | An instance of this reference type.
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    ILLEGAL_ARGUMENT | maxInstances is less than zero.
    NOT_IMPLEMENTED | The functionality is not implemented in this virtual machine.
    VM_DEAD | The virtual machine is not running.
    ClassFileVersion Command (17)
    Returns the class file major and minor version numbers, as defined in the class file format of the Java Virtual Machine specification.

    Since JDWP version 1.6.

    Out Data
    referenceTypeID refType The class.
    Reply Data
    int | majorVersion | Major version number
    int | minorVersion | Minor version number
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    ABSENT_INFORMATION | The class file version information is absent for primitive and array types.
    VM_DEAD | The virtual machine is not running.
    ConstantPool Command (18)
    Return the raw bytes of the constant pool in the format of the constant_pool item of the Class File Format in the Java Virtual Machine Specification.

    Since JDWP version 1.6. Requires canGetConstantPool capability - see CapabilitiesNew.

    Out Data
    referenceTypeID refType The class.
    Reply Data
    int | count | Total number of constant pool entries plus one. This corresponds to the constant_pool_count item of the Class File Format in the Java Virtual Machine Specification.
    int | bytes
    Repeated bytes times:
    byte | cpbytes | Raw bytes of constant pool
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    NOT_IMPLEMENTED | If the target virtual machine does not support the retrieval of constant pool information.
    ABSENT_INFORMATION | The Constant Pool information is absent for primitive and array types.
    VM_DEAD | The virtual machine is not running.

    ClassType Command Set (3)

    Superclass Command (1)
    Returns the immediate superclass of a class.
    Out Data
    classID clazz The class type ID.
    Reply Data
    classID superclass The superclass (null if the class ID for java.lang.Object is specified).
    Error Data
    INVALID_CLASS | clazz is not the ID of a class.
    INVALID_OBJECT | clazz is not a known ID.
    VM_DEAD | The virtual machine is not running.
    SetValues Command (2)
    Sets the value of one or more static fields. Each field must be member of the class type or one of its superclasses, superinterfaces, or implemented interfaces. Access control is not enforced; for example, the values of private fields can be set. Final fields cannot be set.For primitive values, the value's type must match the field's type exactly. For object values, there must exist a widening reference conversion from the value's type to the field's type and the field's type must be loaded.
    Out Data
    classID | clazz | The class type ID.
    int | values | The number of fields to set.
    Repeated values times:
    fieldID | fieldID | Field to set.
    untagged-value | value | Value to put in the field.
    Reply Data
    (None)
    Error Data
    INVALID_CLASS | clazz is not the ID of a class.
    CLASS_NOT_PREPARED | Class has been loaded but not yet prepared.
    INVALID_OBJECT | clazz is not a known ID or a value of an object field is not a known ID.
    INVALID_FIELDID | Invalid field.
    VM_DEAD | The virtual machine is not running.
    InvokeMethod Command (3)
    Invokes a static method. The method must be member of the class type or one of its superclasses, superinterfaces, or implemented interfaces. Access control is not enforced; for example, private methods can be invoked.

    The method invocation will occur in the specified thread. Method invocation can occur only if the specified thread has been suspended by an event. Method invocation is not supported when the target VM has been suspended by the front-end.

    The specified method is invoked with the arguments in the specified argument list. The method invocation is synchronous; the reply packet is not sent until the invoked method returns in the target VM. The return value (possibly the void value) is included in the reply packet. If the invoked method throws an exception, the exception object ID is set in the reply packet; otherwise, the exception object ID is null.

    For primitive arguments, the argument value's type must match the argument's type exactly. For object arguments, there must exist a widening reference conversion from the argument value's type to the argument's type and the argument's type must be loaded.

    By default, all threads in the target VM are resumed while the method is being invoked if they were previously suspended by an event or by command. This is done to prevent the deadlocks that will occur if any of the threads own monitors that will be needed by the invoked method. It is possible that breakpoints or other events might occur during the invocation. Note, however, that this implicit resume acts exactly like the ThreadReference resume command, so if the thread's suspend count is greater than 1, it will remain in a suspended state during the invocation. By default, when the invocation completes, all threads in the target VM are suspended, regardless their state before the invocation.

    The resumption of other threads during the invoke can be prevented by specifying the INVOKE_SINGLE_THREADED bit flag in the options field; however, there is no protection against or recovery from the deadlocks described above, so this option should be used with great caution. Only the specified thread will be resumed (as described for all threads above). Upon completion of a single threaded invoke, the invoking thread will be suspended once again. Note that any threads started during the single threaded invocation will not be suspended when the invocation completes.

    If the target VM is disconnected during the invoke (for example, through the VirtualMachine dispose command) the method invocation continues.

    Out Data
    classID | clazz | The class type ID.
    threadID | thread | The thread in which to invoke.
    methodID | methodID | The method to invoke.
    int | arguments
    Repeated arguments times:
    value | arg | The argument value.
    int | options | Invocation options
    Reply Data
    value | returnValue | The returned value.
    tagged-objectID | exception | The thrown exception.
    Error Data
    INVALID_CLASS | clazz is not the ID of a class.
    INVALID_OBJECT | clazz is not a known ID.
    INVALID_METHODID | methodID is not the ID of a method.
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    THREAD_NOT_SUSPENDED | If the specified thread has not been suspended by an event.
    VM_DEAD | The virtual machine is not running.
    NewInstance Command (4)
    Creates a new object of this type, invoking the specified constructor. The constructor method ID must be a member of the class type.

    Instance creation will occur in the specified thread. Instance creation can occur only if the specified thread has been suspended by an event. Method invocation is not supported when the target VM has been suspended by the front-end.

    The specified constructor is invoked with the arguments in the specified argument list. The constructor invocation is synchronous; the reply packet is not sent until the invoked method returns in the target VM. The return value (possibly the void value) is included in the reply packet. If the constructor throws an exception, the exception object ID is set in the reply packet; otherwise, the exception object ID is null.

    For primitive arguments, the argument value's type must match the argument's type exactly. For object arguments, there must exist a widening reference conversion from the argument value's type to the argument's type and the argument's type must be loaded.

    By default, all threads in the target VM are resumed while the method is being invoked if they were previously suspended by an event or by command. This is done to prevent the deadlocks that will occur if any of the threads own monitors that will be needed by the invoked method. It is possible that breakpoints or other events might occur during the invocation. Note, however, that this implicit resume acts exactly like the ThreadReference resume command, so if the thread's suspend count is greater than 1, it will remain in a suspended state during the invocation. By default, when the invocation completes, all threads in the target VM are suspended, regardless their state before the invocation.

    The resumption of other threads during the invoke can be prevented by specifying the INVOKE_SINGLE_THREADED bit flag in the options field; however, there is no protection against or recovery from the deadlocks described above, so this option should be used with great caution. Only the specified thread will be resumed (as described for all threads above). Upon completion of a single threaded invoke, the invoking thread will be suspended once again. Note that any threads started during the single threaded invocation will not be suspended when the invocation completes.

    If the target VM is disconnected during the invoke (for example, through the VirtualMachine dispose command) the method invocation continues.

    Out Data
    classID | clazz | The class type ID.
    threadID | thread | The thread in which to invoke the constructor.
    methodID | methodID | The constructor to invoke.
    int | arguments
    Repeated arguments times:
    value | arg | The argument value.
    int | options | Constructor invocation options
    Reply Data
    tagged-objectID | newObject | The newly created object, or null if the constructor threw an exception.
    tagged-objectID | exception | The thrown exception, if any; otherwise, null.
    Error Data
    INVALID_CLASS | clazz is not the ID of a class.
    INVALID_OBJECT | clazz is not a known ID or a value of an object parameter is not a known ID..
    INVALID_METHODID | methodID is not the ID of a method.
    INVALID_OBJECT | If this reference type has been unloaded and garbage collected.
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    THREAD_NOT_SUSPENDED | If the specified thread has not been suspended by an event.
    VM_DEAD | The virtual machine is not running.

    ArrayType Command Set (4)

    NewInstance Command (1)
    Creates a new array object of this type with a given length.
    Out Data
    arrayTypeID | arrType | The array type of the new instance.
    int | length | The length of the array.
    Reply Data
    tagged-objectID newArray The newly created array object.
    Error Data
    INVALID_ARRAY | The array is invalid.
    INVALID_OBJECT | If this reference type has been unloaded and garbage collected.
    VM_DEAD | The virtual machine is not running.

    InterfaceType Command Set (5)

    Method Command Set (6)

    LineTable Command (1)
    Returns line number information for the method, if present. The line table maps source line numbers to the initial code index of the line. The line table is ordered by code index (from lowest to highest). The line number information is constant unless a new class definition is installed using RedefineClasses.
    Out Data
    referenceTypeID | refType | The class.
    methodID | methodID | The method.
    Reply Data
    long | start | Lowest valid code index for the method, >=0, or -1 if the method is native
    long | end | Highest valid code index for the method, >=0, or -1 if the method is native
    int | lines | The number of entries in the line table for this method.
    Repeated lines times:
    long | lineCodeIndex | Initial code index of the line, start <= lineCodeIndex="lineCodeIndex" <="<" end ="end " | int | lineNumber | Line number.
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    INVALID_METHODID | methodID is not the ID of a method.
    VM_DEAD | The virtual machine is not running.
    VariableTable Command (2)
    Returns variable information for the method. The variable table includes arguments and locals declared within the method. For instance methods, the "this" reference is included in the table. Also, synthetic variables may be present.
    Out Data
    referenceTypeID | refType | The class.
    methodID | methodID | The method.
    Reply Data
    int | argCnt | The number of words in the frame used by arguments. Eight-byte arguments use two words; all others use one.
    int | slots | The number of variables.
    Repeated slots times:
    long | codeIndex | First code index at which the variable is visible (unsigned). Used in conjunction with length. The variable can be get or set only when the current codeIndex <= current="current" frame="frame" code="code" index="index" <="<" codeIndex + length
    string | name | The variable's name.
    string | signature | The variable type's JNI signature.
    int | length | Unsigned value used in conjunction with codeIndex. The variable can be get or set only when the current codeIndex <= current="current" frame="frame" code="code" index="index" <="<" code index + length
    int | slot | The local variable's index in its frame
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    INVALID_METHODID | methodID is not the ID of a method.
    ABSENT_INFORMATION | there is no variable information for the method.
    VM_DEAD | The virtual machine is not running.
    Bytecodes Command (3)
    Retrieve the method's bytecodes as defined in the JVM Specification.Requires canGetBytecodes capability - see CapabilitiesNew.
    Out Data
    referenceTypeID | refType | The class.
    methodID | methodID | The method.
    Reply Data
    int | bytes
    Repeated bytes times:
    byte | bytecode | A Java bytecode.
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    INVALID_METHODID | methodID is not the ID of a method.
    NOT_IMPLEMENTED | If the target virtual machine does not support the retrieval of bytecodes.
    VM_DEAD | The virtual machine is not running.
    IsObsolete Command (4)
    Determine if this method is obsolete. A method is obsolete if it has been replaced by a non-equivalent method using the RedefineClasses command. The original and redefined methods are considered equivalent if their bytecodes are the same except for indices into the constant pool and the referenced constants are equal.
    Out Data
    referenceTypeID | refType | The class.
    methodID | methodID | The method.
    Reply Data
    boolean isObsolete true if this method has been replacedby a non-equivalent method usingthe RedefineClasses command.
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    INVALID_METHODID | methodID is not the ID of a method.
    NOT_IMPLEMENTED | If the target virtual machine does not support this query.
    VM_DEAD | The virtual machine is not running.
    VariableTableWithGeneric Command (5)
    Returns variable information for the method, including generic signatures for the variables. The variable table includes arguments and locals declared within the method. For instance methods, the "this" reference is included in the table. Also, synthetic variables may be present. Generic signatures are described in the signature attribute section in the Java Virtual Machine Specification, 3rd Edition. Since JDWP version 1.5.
    Out Data
    referenceTypeID | refType | The class.
    methodID | methodID | The method.
    Reply Data
    int | argCnt | The number of words in the frame used by arguments. Eight-byte arguments use two words; all others use one.
    int | slots | The number of variables.
    Repeated slots times:
    long | codeIndex | First code index at which the variable is visible (unsigned). Used in conjunction with length. The variable can be get or set only when the current codeIndex <= current="current" frame="frame" code="code" index="index" <="<" codeIndex + length
    string | name | The variable's name.
    string | signature | The variable type's JNI signature.
    string | genericSignature | The variable type's generic signature or an empty string if there is none.
    int | length | Unsigned value used in conjunction with codeIndex. The variable can be get or set only when the current codeIndex <= current="current" frame="frame" code="code" index="index" <="<" code index + length
    int | slot | The local variable's index in its frame
    Error Data
    INVALID_CLASS | refType is not the ID of a reference type.
    INVALID_OBJECT | refType is not a known ID.
    INVALID_METHODID | methodID is not the ID of a method.
    ABSENT_INFORMATION | there is no variable information for the method.
    VM_DEAD | The virtual machine is not running.

    Field Command Set (8)

    ObjectReference Command Set (9)

    ReferenceType Command (1)
    Returns the runtime type of the object. The runtime type will be a class or an array.
    Out Data
    objectID object The object ID
    Reply Data
    byte | refTypeTag | Kind of following reference type.
    referenceTypeID | typeID | The runtime reference type.
    Error Data
    INVALID_OBJECT | If this reference type has been unloaded and garbage collected.
    VM_DEAD | The virtual machine is not running.
    GetValues Command (2)
    Returns the value of one or more instance fields. Each field must be member of the object's type or one of its superclasses, superinterfaces, or implemented interfaces. Access control is not enforced; for example, the values of private fields can be obtained.
    Out Data
    objectID | object | The object ID
    int | fields | The number of values to get
    Repeated fields times:
    fieldID | fieldID | Field to get.
    Reply Data
    int | values | The number of values returned, always equal to 'fields', the number of values to get. Field values are ordered in the reply in the same order as corresponding fieldIDs in the command.
    Repeated values times:
    value | value | The field value
    Error Data
    INVALID_OBJECT | If this reference type has been unloaded and garbage collected.
    INVALID_FIELDID | Invalid field.
    VM_DEAD | The virtual machine is not running.
    SetValues Command (3)
    Sets the value of one or more instance fields. Each field must be member of the object's type or one of its superclasses, superinterfaces, or implemented interfaces. Access control is not enforced; for example, the values of private fields can be set. For primitive values, the value's type must match the field's type exactly. For object values, there must be a widening reference conversion from the value's type to the field's type and the field's type must be loaded.
    Out Data
    objectID | object | The object ID
    int | values | The number of fields to set.
    Repeated values times:
    fieldID | fieldID | Field to set.
    untagged-value | value | Value to put in the field.
    Reply Data
    (None)
    Error Data
    INVALID_OBJECT | If this reference type has been unloaded and garbage collected.
    INVALID_FIELDID | Invalid field.
    VM_DEAD | The virtual machine is not running.
    MonitorInfo Command (5)
    Returns monitor information for an object. All threads int the VM must be suspended.Requires canGetMonitorInfo capability - see CapabilitiesNew.
    Out Data
    objectID object The object ID
    Reply Data
    threadID | owner | The monitor owner, or null if it is not currently owned.
    int | entryCount | The number of times the monitor has been entered.
    int | waiters | The number of threads that are waiting for the monitor 0 if there is no current owner
    Repeated waiters times:
    threadID | thread | A thread waiting for this monitor.
    Error Data
    INVALID_OBJECT | If this reference type has been unloaded and garbage collected.
    NOT_IMPLEMENTED | The functionality is not implemented in this virtual machine.
    VM_DEAD | The virtual machine is not running.
    InvokeMethod Command (6)
    Invokes a instance method. The method must be member of the object's type or one of its superclasses, superinterfaces, or implemented interfaces. Access control is not enforced; for example, private methods can be invoked.

    The method invocation will occur in the specified thread. Method invocation can occur only if the specified thread has been suspended by an event. Method invocation is not supported when the target VM has been suspended by the front-end.

    The specified method is invoked with the arguments in the specified argument list. The method invocation is synchronous; the reply packet is not sent until the invoked method returns in the target VM. The return value (possibly the void value) is included in the reply packet. If the invoked method throws an exception, the exception object ID is set in the reply packet; otherwise, the exception object ID is null.

    For primitive arguments, the argument value's type must match the argument's type exactly. For object arguments, there must be a widening reference conversion from the argument value's type to the argument's type and the argument's type must be loaded.

    By default, all threads in the target VM are resumed while the method is being invoked if they were previously suspended by an event or by command. This is done to prevent the deadlocks that will occur if any of the threads own monitors that will be needed by the invoked method. It is possible that breakpoints or other events might occur during the invocation. Note, however, that this implicit resume acts exactly like the ThreadReference resume command, so if the thread's suspend count is greater than 1, it will remain in a suspended state during the invocation. By default, when the invocation completes, all threads in the target VM are suspended, regardless their state before the invocation.

    The resumption of other threads during the invoke can be prevented by specifying the INVOKE_SINGLE_THREADED bit flag in the options field; however, there is no protection against or recovery from the deadlocks described above, so this option should be used with great caution. Only the specified thread will be resumed (as described for all threads above). Upon completion of a single threaded invoke, the invoking thread will be suspended once again. Note that any threads started during the single threaded invocation will not be suspended when the invocation completes.

    If the target VM is disconnected during the invoke (for example, through the VirtualMachine dispose command) the method invocation continues.

    Out Data
    objectID | object | The object ID
    threadID | thread | The thread in which to invoke.
    classID | clazz | The class type.
    methodID | methodID | The method to invoke.
    int | arguments | The number of arguments.
    Repeated arguments times:
    value | arg | The argument value.
    int | options | Invocation options
    Reply Data
    value | returnValue | The returned value, or null if an exception is thrown.
    tagged-objectID | exception | The thrown exception, if any.
    Error Data
    INVALID_OBJECT | If this reference type has been unloaded and garbage collected.
    INVALID_CLASS | clazz is not the ID of a reference type.
    INVALID_METHODID | methodID is not the ID of a method.
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    THREAD_NOT_SUSPENDED | If the specified thread has not been suspended by an event.
    VM_DEAD | The virtual machine is not running.
    DisableCollection Command (7)
    Prevents garbage collection for the given object. By default all objects in back-end replies may be collected at any time the target VM is running. A call to this command guarantees that the object will not be collected. The EnableCollection command can be used to allow collection once again.

    Note that while the target VM is suspended, no garbage collection will occur because all threads are suspended. The typical examination of variables, fields, and arrays during the suspension is safe without explicitly disabling garbage collection.

    This method should be used sparingly, as it alters the pattern of garbage collection in the target VM and, consequently, may result in application behavior under the debugger that differs from its non-debugged behavior.

    Out Data
    objectID object The object ID
    Reply Data
    (None)
    Error Data
    INVALID_OBJECT | If this reference type has been unloaded and garbage collected.
    VM_DEAD | The virtual machine is not running.
    EnableCollection Command (8)
    Permits garbage collection for this object. By default all objects returned by JDWP may become unreachable in the target VM, and hence may be garbage collected. A call to this command is necessary only if garbage collection was previously disabled with the DisableCollection command.
    Out Data
    objectID object The object ID
    Reply Data
    (None)
    Error Data
    VM_DEAD The virtual machine is not running.
    IsCollected Command (9)
    Determines whether an object has been garbage collected in the target VM.
    Out Data
    objectID object The object ID
    Reply Data
    boolean isCollected true if the object has been collected; false otherwise
    Error Data
    INVALID_OBJECT | If this reference type has been unloaded and garbage collected.
    VM_DEAD | The virtual machine is not running.
    ReferringObjects Command (10)
    Returns objects that directly reference this object. Only objects that are reachable for the purposes of garbage collection are returned. Note that an object can also be referenced in other ways, such as from a local variable in a stack frame, or from a JNI global reference. Such non-object referrers are not returned by this command.

    Since JDWP version 1.6. Requires canGetInstanceInfo capability - see CapabilitiesNew.

    Out Data
    objectID | object | The object ID
    int | maxReferrers | Maximum number of referring objects to return. Must be non-negative. If zero, all referring objects are returned.
    Reply Data
    int | referringObjects | The number of objects that follow.
    Repeated referringObjects times:
    tagged-objectID | instance | An object that references this object.
    Error Data
    INVALID_OBJECT | object is not a known ID.
    ILLEGAL_ARGUMENT | maxReferrers is less than zero.
    NOT_IMPLEMENTED | The functionality is not implemented in this virtual machine.
    VM_DEAD | The virtual machine is not running.

    StringReference Command Set (10)

    Value Command (1)
    Returns the characters contained in the string.
    Out Data
    objectID stringObject The String object ID.
    Reply Data
    string stringValue UTF-8 representation of the string value.
    Error Data
    INVALID_STRING | The string is invalid.
    INVALID_OBJECT | If this reference type has been unloaded and garbage collected.
    VM_DEAD | The virtual machine is not running.

    ThreadReference Command Set (11)

    Name Command (1)
    Returns the thread name.
    Out Data
    threadID thread The thread object ID.
    Reply Data
    string threadName The thread name.
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | thread is not a known ID.
    VM_DEAD | The virtual machine is not running.
    Suspend Command (2)
    Suspends the thread.

    Unlike java.lang.Thread.suspend(), suspends of both the virtual machine and individual threads are counted. Before a thread will run again, it must be resumed the same number of times it has been suspended.

    Suspending single threads with command has the same dangers java.lang.Thread.suspend(). If the suspended thread holds a monitor needed by another running thread, deadlock is possible in the target VM (at least until the suspended thread is resumed again).

    The suspended thread is guaranteed to remain suspended until resumed through one of the JDI resume methods mentioned above; the application in the target VM cannot resume the suspended thread through {@link java.lang.Thread#resume}.

    Note that this doesn't change the status of the thread (see the ThreadStatus command.) For example, if it was Running, it will still appear running to other threads.

    Out Data
    threadID thread The thread object ID.
    Reply Data
    (None)
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | thread is not a known ID.
    VM_DEAD | The virtual machine is not running.
    Resume Command (3)
    Resumes the execution of a given thread. If this thread was not previously suspended by the front-end, calling this command has no effect. Otherwise, the count of pending suspends on this thread is decremented. If it is decremented to 0, the thread will continue to execute.
    Out Data
    threadID thread The thread object ID.
    Reply Data
    (None)
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | thread is not a known ID.
    VM_DEAD | The virtual machine is not running.
    Status Command (4)
    Returns the current status of a thread. The thread status reply indicates the thread status the last time it was running. the suspend status provides information on the thread's suspension, if any.
    Out Data
    threadID thread The thread object ID.
    Reply Data
    int | threadStatus | One of the thread status codes See JDWP.ThreadStatus
    int | suspendStatus | One of the suspend status codes See JDWP.SuspendStatus
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | thread is not a known ID.
    VM_DEAD | The virtual machine is not running.
    ThreadGroup Command (5)
    Returns the thread group that contains a given thread.
    Out Data
    threadID thread The thread object ID.
    Reply Data
    threadGroupID group The thread group of this thread.
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | thread is not a known ID.
    VM_DEAD | The virtual machine is not running.
    Frames Command (6)
    Returns the current call stack of a suspended thread. The sequence of frames starts with the currently executing frame, followed by its caller, and so on. The thread must be suspended, and the returned frameID is valid only while the thread is suspended.
    Out Data
    threadID | thread | The thread object ID.
    int | startFrame | The index of the first frame to retrieve.
    int | length | The count of frames to retrieve (-1 means all remaining).
    Reply Data
    int | frames | The number of frames retreived
    Repeated frames times:
    frameID | frameID | The ID of this frame.
    location | location | The current location of this frame
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | thread is not a known ID.
    VM_DEAD | The virtual machine is not running.
    FrameCount Command (7)
    Returns the count of frames on this thread's stack. The thread must be suspended, and the returned count is valid only while the thread is suspended. Returns JDWP.Error.errorThreadNotSuspended if not suspended.
    Out Data
    threadID thread The thread object ID.
    Reply Data
    int frameCount The count of frames on this thread's stack.
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | thread is not a known ID.
    VM_DEAD | The virtual machine is not running.
    OwnedMonitors Command (8)
    Returns the objects whose monitors have been entered by this thread. The thread must be suspended, and the returned information is relevant only while the thread is suspended. Requires canGetOwnedMonitorInfo capability - see CapabilitiesNew.
    Out Data
    threadID thread The thread object ID.
    Reply Data
    int | owned | The number of owned monitors
    Repeated owned times:
    tagged-objectID | monitor | An owned monitor
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | thread is not a known ID.
    NOT_IMPLEMENTED | The functionality is not implemented in this virtual machine.
    VM_DEAD | The virtual machine is not running.
    CurrentContendedMonitor Command (9)
    Returns the object, if any, for which this thread is waiting. The thread may be waiting to enter a monitor, or it may be waiting, via the java.lang.Object.wait method, for another thread to invoke the notify method. The thread must be suspended, and the returned information is relevant only while the thread is suspended. Requires canGetCurrentContendedMonitor capability - see CapabilitiesNew.
    Out Data
    threadID thread The thread object ID.
    Reply Data
    tagged-objectID monitor The contended monitor, or null if there is no current contended monitor.
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | thread is not a known ID.
    NOT_IMPLEMENTED | The functionality is not implemented in this virtual machine.
    VM_DEAD | The virtual machine is not running.
    Stop Command (10)
    Stops the thread with an asynchronous exception, as if done by java.lang.Thread.stop
    Out Data
    threadID | thread | The thread object ID.
    objectID | throwable | Asynchronous exception. This object must be an instance of java.lang.Throwable or a subclass
    Reply Data
    (None)
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | If thread is not a known ID or the asynchronous exception has been garbage collected.
    VM_DEAD | The virtual machine is not running.
    Interrupt Command (11)
    Interrupt the thread, as if done by java.lang.Thread.interrupt
    Out Data
    threadID thread The thread object ID.
    Reply Data
    (None)
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | thread is not a known ID.
    VM_DEAD | The virtual machine is not running.
    SuspendCount Command (12)
    Get the suspend count for this thread. The suspend count is the number of times the thread has been suspended through the thread-level or VM-level suspend commands without a corresponding resume
    Out Data
    threadID thread The thread object ID.
    Reply Data
    int suspendCount The number of outstanding suspends of this thread.
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | thread is not a known ID.
    VM_DEAD | The virtual machine is not running.
    OwnedMonitorsStackDepthInfo Command (13)
    Returns monitor objects owned by the thread, along with stack depth at which the monitor was acquired. Returns stack depth of -1 if the implementation cannot determine the stack depth (e.g., for monitors acquired by JNI MonitorEnter).The thread must be suspended, and the returned information is relevant only while the thread is suspended. Requires canGetMonitorFrameInfo capability - see CapabilitiesNew.

    Since JDWP version 1.6.

    Out Data
    threadID thread The thread object ID.
    Reply Data
    int | owned | The number of owned monitors
    Repeated owned times:
    tagged-objectID | monitor | An owned monitor
    int | stack_depth | Stack depth location where monitor was acquired
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | thread is not a known ID.
    NOT_IMPLEMENTED | The functionality is not implemented in this virtual machine.
    VM_DEAD | The virtual machine is not running.
    ForceEarlyReturn Command (14)
    Force a method to return before it reaches a return statement.

    The method which will return early is referred to as the called method. The called method is the current method (as defined by the Frames section in the Java Virtual Machine Specification) for the specified thread at the time this command is received.

    The specified thread must be suspended. The return occurs when execution of Java programming language code is resumed on this thread. Between sending this command and resumption of thread execution, the state of the stack is undefined.

    No further instructions are executed in the called method. Specifically, finally blocks are not executed. Note: this can cause inconsistent states in the application.

    A lock acquired by calling the called method (if it is a synchronized method) and locks acquired by entering synchronized blocks within the called method are released. Note: this does not apply to JNI locks or java.util.concurrent.locks locks.

    Events, such as MethodExit, are generated as they would be in a normal return.

    The called method must be a non-native Java programming language method. Forcing return on a thread with only one frame on the stack causes the thread to exit when resumed.

    For void methods, the value must be a void value. For methods that return primitive values, the value's type must match the return type exactly. For object values, there must be a widening reference conversion from the value's type to the return type type and the return type must be loaded.

    Since JDWP version 1.6. Requires canForceEarlyReturn capability - see CapabilitiesNew.

    Out Data
    threadID | thread | The thread object ID.
    value | value | The value to return.
    Reply Data
    (None)
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | Thread or value is not a known ID.
    THREAD_NOT_SUSPENDED | If the specified thread has not been suspended by an event.
    THREAD_NOT_ALIVE | Thread has not been started or is now dead.
    OPAQUE_FRAME | Attempted to return early from a frame corresponding to a native method. Or the implementation is unable to provide this functionality on this frame.
    NO_MORE_FRAMES | There are no more Java or JNI frames on the call stack.
    NOT_IMPLEMENTED | The functionality is not implemented in this virtual machine.
    TYPE_MISMATCH | Value is not an appropriate type for the return value of the method.
    VM_DEAD | The virtual machine is not running.

    ThreadGroupReference Command Set (12)

    Name Command (1)
    Returns the thread group name.
    Out Data
    threadGroupID group The thread group object ID.
    Reply Data
    string groupName The thread group's name.
    Error Data
    INVALID_THREAD_GROUP | Thread group invalid.
    INVALID_OBJECT | group is not a known ID.
    VM_DEAD | The virtual machine is not running.
    Parent Command (2)
    Returns the thread group, if any, which contains a given thread group.
    Out Data
    threadGroupID group The thread group object ID.
    Reply Data
    threadGroupID parentGroup The parent thread group object, or null if the given thread group is a top-level thread group
    Error Data
    INVALID_THREAD_GROUP | Thread group invalid.
    INVALID_OBJECT | group is not a known ID.
    VM_DEAD | The virtual machine is not running.
    Children Command (3)
    Returns the live threads and active thread groups directly contained in this thread group. Threads and thread groups in child thread groups are not included. A thread is alive if it has been started and has not yet been stopped. See java.lang.ThreadGroup for information about active ThreadGroups.
    Out Data
    threadGroupID group The thread group object ID.
    Reply Data
    int | childThreads | The number of live child threads.
    Repeated childThreads times:
    threadID | childThread | A direct child thread ID.
    int | childGroups | The number of active child thread groups.
    Repeated childGroups times:
    threadGroupID | childGroup | A direct child thread group ID.
    Error Data
    INVALID_THREAD_GROUP | Thread group invalid.
    INVALID_OBJECT | group is not a known ID.
    VM_DEAD | The virtual machine is not running.

    ArrayReference Command Set (13)

    Length Command (1)
    Returns the number of components in a given array.
    Out Data
    arrayID arrayObject The array object ID.
    Reply Data
    int arrayLength The length of the array.
    Error Data
    INVALID_OBJECT | arrayObject is not a known ID.
    INVALID_ARRAY | The array is invalid.
    VM_DEAD | The virtual machine is not running.
    GetValues Command (2)
    Returns a range of array components. The specified range must be within the bounds of the array.
    Out Data
    arrayID | arrayObject | The array object ID.
    int | firstIndex | The first index to retrieve.
    int | length | The number of components to retrieve.
    Reply Data
    arrayregion values The retrieved values. If the values are objects, they are tagged-values; otherwise, they are untagged-values
    Error Data
    INVALID_LENGTH | If index is beyond the end of this array.
    INVALID_OBJECT | arrayObject is not a known ID.
    INVALID_ARRAY | The array is invalid.
    VM_DEAD | The virtual machine is not running.
    SetValues Command (3)
    Sets a range of array components. The specified range must be within the bounds of the array. For primitive values, each value's type must match the array component type exactly. For object values, there must be a widening reference conversion from the value's type to the array component type and the array component type must be loaded.
    Out Data
    arrayID | arrayObject | The array object ID.
    int | firstIndex | The first index to set.
    int | values | The number of values to set.
    Repeated values times:
    untagged-value | value | A value to set.
    Reply Data
    (None)
    Error Data
    INVALID_LENGTH | If index is beyond the end of this array.
    INVALID_OBJECT | arrayObject is not a known ID.
    INVALID_ARRAY | The array is invalid.
    VM_DEAD | The virtual machine is not running.

    ClassLoaderReference Command Set (14)

    VisibleClasses Command (1)
    Returns a list of all classes which this class loader has been requested to load. This class loader is considered to be an initiating class loader for each class in the returned list. The list contains each reference type defined by this loader and any types for which loading was delegated by this class loader to another class loader.

    The visible class list has useful properties with respect to the type namespace. A particular type name will occur at most once in the list. Each field or variable declared with that type name in a class defined by this class loader must be resolved to that single type.

    No ordering of the returned list is guaranteed.

    Out Data
    classLoaderID classLoaderObject The class loader object ID.
    Reply Data
    int | classes | The number of visible classes.
    Repeated classes times:
    byte | refTypeTag | Kind of following reference type.
    referenceTypeID | typeID | A class visible to this class loader.
    Error Data
    INVALID_OBJECT | If this reference type has been unloaded and garbage collected.
    INVALID_CLASS_LOADER | The class loader is invalid.
    VM_DEAD | The virtual machine is not running.

    EventRequest Command Set (15)

    Set Command (1)
    Set an event request. When the event described by this request occurs, an event is sent from the target VM. If an event occurs that has not been requested then it is not sent from the target VM. The two exceptions to this are the VM Start Event and the VM Death Event which are automatically generated events - see Composite Command for further details.
    Out Data
    byte | eventKind | Event kind to request. See JDWP.EventKind for a complete list of events that can be requested.
    byte | suspendPolicy | What threads are suspended when this event occurs? Note that the order of events and command replies accurately reflects the order in which threads are suspended and resumed. For example, if a VM-wide resume is processed before an event occurs which suspends the VM, the reply to the resume command will be written to the transport before the suspending event.
    intmodifiersConstraints used to control the number of generated events.Modifiers specify additional tests that an event must satisfy before it is placed in the event queue. Events are filtered by applying each modifier to an event in the order they are specified in this collection Only events that satisfy all modifiers are reported. A value of 0 means there are no modifiers in the request.

    Filtering can improve debugger performance dramatically by reducing the amount of event traffic sent from the target VM to the debugger VM.

    Repeated modifiers times:
    byte | modKind | Modifier kind
    Case Count - if modKind is 1: Limit the requested event to be reported at most once after a given number of occurrences. The event is not reported the first count - 1 times this filter is reached. To request a one-off event, call this method with a count of 1.

    Once the count reaches 0, any subsequent filters in this request are applied. If none of those filters cause the event to be suppressed, the event is reported. Otherwise, the event is not reported. In either case subsequent events are never reported for this request. This modifier can be used with any event kind.

    int | count | Count before event. One for one-off.
    Case Conditional - if modKind is 2: Conditional on expression
    int | exprID | For the future
    Case ThreadOnly - if modKind is 3: Restricts reported events to those in the given thread. This modifier can be used with any event kind except for class unload.
    threadID | thread | Required thread
    Case ClassOnly - if modKind is 4: For class prepare events, restricts the events generated by this request to be the preparation of the given reference type and any subtypes. For monitor wait and waited events, restricts the events generated by this request to those whose monitor object is of the given reference type or any of its subtypes. For other events, restricts the events generated by this request to those whose location is in the given reference type or any of its subtypes. An event will be generated for any location in a reference type that can be safely cast to the given reference type. This modifier can be used with any event kind except class unload, thread start, and thread end.
    referenceTypeID | clazz | Required class
    Case ClassMatch - if modKind is 5: Restricts reported events to those for classes whose name matches the given restricted regular expression. For class prepare events, the prepared class name is matched. For class unload events, the unloaded class name is matched. For monitor wait and waited events, the name of the class of the monitor object is matched. For other events, the class name of the event's location is matched. This modifier can be used with any event kind except thread start and thread end.
    string | classPattern | Required class pattern. Matches are limited to exact matches of the given class pattern and matches of patterns that begin or end with '*'; for example, "*.Foo" or "java.*".
    Case ClassExclude - if modKind is 6: Restricts reported events to those for classes whose name does not match the given restricted regular expression. For class prepare events, the prepared class name is matched. For class unload events, the unloaded class name is matched. For monitor wait and waited events, the name of the class of the monitor object is matched. For other events, the class name of the event's location is matched. This modifier can be used with any event kind except thread start and thread end.
    string | classPattern | Disallowed class pattern. Matches are limited to exact matches of the given class pattern and matches of patterns that begin or end with '*'; for example, "*.Foo" or "java.*".
    Case LocationOnly - if modKind is 7: Restricts reported events to those that occur at the given location. This modifier can be used with breakpoint, field access, field modification, step, and exception event kinds.
    location | loc | Required location
    Case ExceptionOnly - if modKind is 8: Restricts reported exceptions by their class and whether they are caught or uncaught. This modifier can be used with exception event kinds only.
    referenceTypeID | exceptionOrNull | Exception to report. Null (0) means report exceptions of all types. A non-null type restricts the reported exception events to exceptions of the given type or any of its subtypes.
    boolean | caught | Report caught exceptions
    boolean | uncaught | Report uncaught exceptions. Note that it is not always possible to determine whether an exception is caught or uncaught at the time it is thrown. See the exception event catch location under composite events for more information.
    Case FieldOnly - if modKind is 9: Restricts reported events to those that occur for a given field. This modifier can be used with field access and field modification event kinds only.
    referenceTypeID | declaring | Type in which field is declared.
    fieldID | fieldID | Required field
    Case Step - if modKind is 10: Restricts reported step events to those which satisfy depth and size constraints. This modifier can be used with step event kinds only.
    threadID | thread | Thread in which to step
    int | size | size of each step. See JDWP.StepSize
    int | depth | relative call stack limit. See JDWP.StepDepth
    Case InstanceOnly - if modKind is 11: Restricts reported events to those whose active 'this' object is the given object. Match value is the null object for static methods. This modifier can be used with any event kind except class prepare, class unload, thread start, and thread end. Introduced in JDWP version 1.4.
    objectID | instance | Required 'this' object
    Case SourceNameMatch - if modKind is 12: Restricts reported class prepare events to those for reference types which have a source name which matches the given restricted regular expression. The source names are determined by the reference type's SourceDebugExtension. This modifier can only be used with class prepare events. Since JDWP version 1.6. Requires the canUseSourceNameFilters capability - see CapabilitiesNew.
    string | sourceNamePattern | Required source name pattern. Matches are limited to exact matches of the given pattern and matches of patterns that begin or end with '*'; for example, "*.Foo" or "java.*".
    Reply Data
    int requestID ID of created request
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_CLASS | Invalid class.
    INVALID_STRING | The string is invalid.
    INVALID_OBJECT | If this reference type has been unloaded and garbage collected.
    INVALID_COUNT | The count is invalid.
    INVALID_FIELDID | Invalid field.
    INVALID_METHODID | Invalid method.
    INVALID_LOCATION | Invalid location.
    INVALID_EVENT_TYPE | The specified event type id is not recognized.
    NOT_IMPLEMENTED | The functionality is not implemented in this virtual machine.
    VM_DEAD | The virtual machine is not running.
    Clear Command (2)
    Clear an event request. See JDWP.EventKind for a complete list of events that can be cleared. Only the event request matching the specified event kind and requestID is cleared. If there isn't a matching event request the command is a no-op and does not result in an error. Automatically generated events do not have a corresponding event request and may not be cleared using this command.
    Out Data
    byte | eventKind | Event kind to clear
    int | requestID | ID of request to clear
    Reply Data
    (None)
    Error Data
    VM_DEAD | The virtual machine is not running.
    INVALID_EVENT_TYPE | The specified event type id is not recognized.
    ClearAllBreakpoints Command (3)
    Removes all set breakpoints, a no-op if there are no breakpoints set.
    Out Data
    (None)
    Reply Data
    (None)
    Error Data
    VM_DEAD The virtual machine is not running.

    StackFrame Command Set (16)

    GetValues Command (1)
    Returns the value of one or more local variables in a given frame. Each variable must be visible at the frame's code index. Even if local variable information is not available, values can be retrieved if the front-end is able to determine the correct local variable index. (Typically, this index can be determined for method arguments from the method signature without access to the local variable table information.)
    Out Data
    threadID | thread | The frame's thread.
    frameID | frame | The frame ID.
    int | slots | The number of values to get.
    Repeated slots times:
    int | slot | The local variable's index in the frame.
    byte | sigbyte | A tag identifying the type of the variable
    Reply Data
    int | values | The number of values retrieved, always equal to slots, the number of values to get.
    Repeated values times:
    value | slotValue | The value of the local variable.
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | If this reference type has been unloaded and garbage collected.
    INVALID_FRAMEID | Invalid jframeID.
    INVALID_SLOT | Invalid slot.
    VM_DEAD | The virtual machine is not running.
    SetValues Command (2)
    Sets the value of one or more local variables. Each variable must be visible at the current frame code index. For primitive values, the value's type must match the variable's type exactly. For object values, there must be a widening reference conversion from the value's type to the variable's type and the variable's type must be loaded.

    Even if local variable information is not available, values can be set, if the front-end is able to determine the correct local variable index. (Typically, this index can be determined for method arguments from the method signature without access to the local variable table information.)

    Out Data
    threadID | thread | The frame's thread.
    frameID | frame | The frame ID.
    int | slotValues | The number of values to set.
    Repeated slotValues times:
    int | slot | The slot ID.
    value | slotValue | The value to set.
    Reply Data
    (None)
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | If this reference type has been unloaded and garbage collected.
    INVALID_FRAMEID | Invalid jframeID.
    VM_DEAD | The virtual machine is not running.
    ThisObject Command (3)
    Returns the value of the 'this' reference for this frame. If the frame's method is static or native, the reply will contain the null object reference.
    Out Data
    threadID | thread | The frame's thread.
    frameID | frame | The frame ID.
    Reply Data
    tagged-objectID objectThis The 'this' object for this frame.
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | If this reference type has been unloaded and garbage collected.
    INVALID_FRAMEID | Invalid jframeID.
    VM_DEAD | The virtual machine is not running.
    PopFrames Command (4)
    Pop the top-most stack frames of the thread stack, up to, and including 'frame'. The thread must be suspended to perform this command. The top-most stack frames are discarded and the stack frame previous to 'frame' becomes the current frame. The operand stack is restored -- the argument values are added back and if the invoke was not invokestatic, objectref is added back as well. The Java virtual machine program counter is restored to the opcode of the invoke instruction.

    Since JDWP version 1.4. Requires canPopFrames capability - see CapabilitiesNew.

    Out Data
    threadID | thread | The thread object ID.
    frameID | frame | The frame ID.
    Reply Data
    (None)
    Error Data
    INVALID_THREAD | Passed thread is null, is not a valid thread or has exited.
    INVALID_OBJECT | thread is not a known ID.
    INVALID_FRAMEID | Invalid jframeID.
    THREAD_NOT_SUSPENDED | If the specified thread has not been suspended by an event.
    NO_MORE_FRAMES | There are no more Java or JNI frames on the call stack.
    INVALID_FRAMEID | Invalid jframeID.
    NOT_IMPLEMENTED | The functionality is not implemented in this virtual machine.
    VM_DEAD | The virtual machine is not running.

    ClassObjectReference Command Set (17)

    ReflectedType Command (1)
    Returns the reference type reflected by this class object.
    Out Data
    classObjectID classObject The class object.
    Reply Data
    byte | refTypeTag | Kind of following reference type.
    referenceTypeID | typeID | reflected reference type
    Error Data
    INVALID_OBJECT | If this reference type has been unloaded and garbage collected.
    VM_DEAD | The virtual machine is not running.

    Event Command Set (64)

    Composite Command (100)
    Several events may occur at a given time in the target VM. For example, there may be more than one breakpoint request for a given location or you might single step to the same location as a breakpoint request. These events are delivered together as a composite event. For uniformity, a composite event is always used to deliver events, even if there is only one event to report.

    The events that are grouped in a composite event are restricted in the following ways:

    • Only with other thread start events for the same thread:
      • Thread Start Event
    • Only with other thread death events for the same thread:
      • Thread Death Event
    • Only with other class prepare events for the same class:
      • Class Prepare Event
    • Only with other class unload events for the same class:
      • Class Unload Event
    • Only with other access watchpoint events for the same field access:
      • Access Watchpoint Event
    • Only with other modification watchpoint events for the same field modification:
      • Modification Watchpoint Event
    • Only with other Monitor contended enter events for the same monitor object:
      • Monitor Contended Enter Event
    • Only with other Monitor contended entered events for the same monitor object:
      • Monitor Contended Entered Event
    • Only with other Monitor wait events for the same monitor object:
      • Monitor Wait Event
    • Only with other Monitor waited events for the same monitor object:
      • Monitor Waited Event
    • Only with other ExceptionEvents for the same exception occurrance:
      • ExceptionEvent
    • Only with other members of this group, at the same location and in the same thread:
      • Breakpoint Event
      • Step Event
      • Method Entry Event
      • Method Exit Event

    The VM Start Event and VM Death Event are automatically generated events. This means they do not need to be requested using the EventRequest.Set command. The VM Start event signals the completion of VM initialization. The VM Death event signals the termination of the VM.If there is a debugger connected at the time when an automatically generated event occurs it is sent from the target VM. Automatically generated events may also be requested using the EventRequest.Set command and thus multiple events of the same event kind will be sent from the target VM when an event occurs.Automatically generated events are sent with the requestID field in the Event Data set to 0. The value of the suspendPolicy field in the Event Data depends on the event. For the automatically generated VM Start Event the value of suspendPolicy is not defined and is therefore implementation or configuration specific. In the Sun implementation, for example, the suspendPolicy is specified as an option to the JDWP agent at launch-time.The automatically generated VM Death Event will have the suspendPolicy set to NONE.

    Event Data
    byte | suspendPolicy | Which threads where suspended by this composite event?
    int | events | Events in set.
    Repeated events times:
    byte | eventKind | Event kind selector
    Case VMStart - if eventKind is JDWP.EventKind.VM_START: Notification of initialization of a target VM. This event is received before the main thread is started and before any application code has been executed. Before this event occurs a significant amount of system code has executed and a number of system classes have been loaded. This event is always generated by the target VM, even if not explicitly requested.
    int | requestID | Request that generated event (or 0 if this event is automatically generated.
    threadID | thread | Initial thread
    Case SingleStep - if eventKind is JDWP.EventKind.SINGLE_STEP: Notification of step completion in the target VM. The step event is generated before the code at its location is executed.
    int | requestID | Request that generated event
    threadID | thread | Stepped thread
    location | location | Location stepped to
    Case Breakpoint - if eventKind is JDWP.EventKind.BREAKPOINT: Notification of a breakpoint in the target VM. The breakpoint event is generated before the code at its location is executed.
    int | requestID | Request that generated event
    threadID | thread | thread which hit breakpoint
    location | location | Location hit
    Case MethodEntry - if eventKind is JDWP.EventKind.METHOD_ENTRY: Notification of a method invocation in the target VM. This event is generated before any code in the invoked method has executed. Method entry events are generated for both native and non-native methods.

    In some VMs method entry events can occur for a particular thread before its thread start event occurs if methods are called as part of the thread's initialization.

    int | requestID | Request that generated event
    threadID | thread | thread which entered method
    location | location | The initial executable location in the method.
    Case MethodExit - if eventKind is JDWP.EventKind.METHOD_EXIT: Notification of a method return in the target VM. This event is generated after all code in the method has executed, but the location of this event is the last executed location in the method. Method exit events are generated for both native and non-native methods. Method exit events are not generated if the method terminates with a thrown exception.
    int | requestID | Request that generated event
    threadID | thread | thread which exited method
    location | location | Location of exit
    Case MethodExitWithReturnValue - if eventKind is JDWP.EventKind.METHOD_EXIT_WITH_RETURN_VALUE: Notification of a method return in the target VM. This event is generated after all code in the method has executed, but the location of this event is the last executed location in the method. Method exit events are generated for both native and non-native methods. Method exit events are not generated if the method terminates with a thrown exception.

    Since JDWP version 1.6.

    int | requestID | Request that generated event
    threadID | thread | Thread which exited method
    location | location | Location of exit
    value | value | Value that will be returned by the method
    Case MonitorContendedEnter - if eventKind is JDWP.EventKind.MONITOR_CONTENDED_ENTER: Notification that a thread in the target VM is attempting to enter a monitor that is already acquired by another thread.

    Since JDWP version 1.6.

    int | requestID | Request that generated event
    threadID | thread | Thread which is trying to enter the monitor
    tagged-objectID | object | Monitor object reference
    location | location | location of contended monitor enter
    Case MonitorContendedEntered - if eventKind is JDWP.EventKind.MONITOR_CONTENDED_ENTERED: Notification of a thread in the target VM is entering a monitor after waiting for it to be released by another thread.

    Since JDWP version 1.6.

    int | requestID | Request that generated event
    threadID | thread | Thread which entered monitor
    tagged-objectID | object | Monitor object reference
    location | location | location of contended monitor enter
    Case MonitorWait - if eventKind is JDWP.EventKind.MONITOR_WAIT: Notification of a thread about to wait on a monitor object.

    Since JDWP version 1.6.

    int | requestID | Request that generated event
    threadID | thread | Thread which entered monitor
    tagged-objectID | object | Monitor object reference
    location | location | location contended monitor enter
    long | timeout | thread wait time in milliseconds
    Case MonitorWaited - if eventKind is JDWP.EventKind.MONITOR_WAITED: Notification that a thread in the target VM has finished waiting on a monitor object.

    Since JDWP version 1.6.

    int | requestID | Request that generated event
    threadID | thread | Thread which entered monitor
    tagged-objectID | object | Monitor object reference
    location | location | location contended monitor enter
    boolean | timed_out | true if timed out
    Case Exception - if eventKind is JDWP.EventKind.EXCEPTION: Notification of an exception in the target VM. If the exception is thrown from a non-native method, the exception event is generated at the location where the exception is thrown. If the exception is thrown from a native method, the exception event is generated at the first non-native location reached after the exception is thrown.
    int | requestID | Request that generated event
    threadID | thread | Thread with exception
    location | location | Location of exception throw (or first non-native location after throw if thrown from a native method)
    tagged-objectID | exception | Thrown exception
    locationcatchLocationLocation of catch, or 0 if not caught. An exception is considered to be caught if, at the point of the throw, the current location is dynamically enclosed in a try statement that handles the exception. (See the JVM specification for details). If there is such a try statement, the catch location is the first location in the appropriate catch clause.

    If there are native methods in the call stack at the time of the exception, there are important restrictions to note about the returned catch location. In such cases, it is not possible to predict whether an exception will be handled by some native method on the call stack. Thus, it is possible that exceptions considered uncaught here will, in fact, be handled by a native method and not cause termination of the target VM. Furthermore, it cannot be assumed that the catch location returned here will ever be reached by the throwing thread. If there is a native frame between the current location and the catch location, the exception might be handled and cleared in that native method instead.

    Note that compilers can generate try-catch blocks in some cases where they are not explicit in the source code; for example, the code generated for synchronized and finally blocks can contain implicit try-catch blocks. If such an implicitly generated try-catch is present on the call stack at the time of the throw, the exception will be considered caught even though it appears to be uncaught from examination of the source code.

    Case ThreadStart - if eventKind is JDWP.EventKind.THREAD_START: Notification of a new running thread in the target VM. The new thread can be the result of a call to java.lang.Thread.start or the result of attaching a new thread to the VM though JNI. The notification is generated by the new thread some time before its execution starts. Because of this timing, it is possible to receive other events for the thread before this event is received. (Notably, Method Entry Events and Method Exit Events might occur during thread initialization. It is also possible for the VirtualMachine AllThreads command to return a thread before its thread start event is received.

    Note that this event gives no information about the creation of the thread object which may have happened much earlier, depending on the VM being debugged.

    int | requestID | Request that generated event
    threadID | thread | Started thread
    Case ThreadDeath - if eventKind is JDWP.EventKind.THREAD_DEATH: Notification of a completed thread in the target VM. The notification is generated by the dying thread before it terminates. Because of this timing, it is possible for {@link VirtualMachine#allThreads} to return this thread after this event is received.

    Note that this event gives no information about the lifetime of the thread object. It may or may not be collected soon depending on what references exist in the target VM.

    int | requestID | Request that generated event
    threadID | thread | Ending thread
    Case ClassPrepare - if eventKind is JDWP.EventKind.CLASS_PREPARE: Notification of a class prepare in the target VM. See the JVM specification for a definition of class preparation. Class prepare events are not generated for primtiive classes (for example, java.lang.Integer.TYPE).
    int | requestID | Request that generated event
    threadIDthreadPreparing thread. In rare cases, this event may occur in a debugger system thread within the target VM. Debugger threads take precautions to prevent these events, but they cannot be avoided under some conditions, especially for some subclasses of java.lang.Error. If the event was generated by a debugger system thread, the value returned by this method is null, and if the requested suspend policy for the event was EVENT_THREAD all threads will be suspended instead, and the composite event's suspend policy will reflect this change.

    Note that the discussion above does not apply to system threads created by the target VM during its normal (non-debug) operation.

    byte | refTypeTag | Kind of reference type. See JDWP.TypeTag
    referenceTypeID | typeID | Type being prepared
    string | signature | Type signature
    int | status | Status of type. See JDWP.ClassStatus
    Case ClassUnload - if eventKind is JDWP.EventKind.CLASS_UNLOAD: Notification of a class unload in the target VM.

    There are severe constraints on the debugger back-end during garbage collection, so unload information is greatly limited.

    int | requestID | Request that generated event
    string | signature | Type signature
    Case FieldAccess - if eventKind is JDWP.EventKind.FIELD_ACCESS: Notification of a field access in the target VM. Field modifications are not considered field accesses. Requires canWatchFieldAccess capability - see CapabilitiesNew.
    int | requestID | Request that generated event
    threadID | thread | Accessing thread
    location | location | Location of access
    byte | refTypeTag | Kind of reference type. See JDWP.TypeTag
    referenceTypeID | typeID | Type of field
    fieldID | fieldID | Field being accessed
    tagged-objectID | object | Object being accessed (null=0 for statics
    Case FieldModification - if eventKind is JDWP.EventKind.FIELD_MODIFICATION: Notification of a field modification in the target VM. Requires canWatchFieldModification capability - see CapabilitiesNew.
    int | requestID | Request that generated event
    threadID | thread | Modifying thread
    location | location | Location of modify
    byte | refTypeTag | Kind of reference type. See JDWP.TypeTag
    referenceTypeID | typeID | Type of field
    fieldID | fieldID | Field being modified
    tagged-objectID | object | Object being modified (null=0 for statics
    value | valueToBe | Value to be assigned
    Case VMDeath - if eventKind is JDWP.EventKind.VM_DEATH:
    int | requestID | Request that generated event

    Error Constants

    NONE | 0 | No error has occurred.
    INVALID_THREAD | 10 | Passed thread is null, is not a valid thread or has exited.
    INVALID_THREAD_GROUP | 11 | Thread group invalid.
    INVALID_PRIORITY | 12 | Invalid priority.
    THREAD_NOT_SUSPENDED | 13 | If the specified thread has not been suspended by an event.
    THREAD_SUSPENDED | 14 | Thread already suspended.
    THREAD_NOT_ALIVE | 15 | Thread has not been started or is now dead.
    INVALID_OBJECT | 20 | If this reference type has been unloaded and garbage collected.
    INVALID_CLASS | 21 | Invalid class.
    CLASS_NOT_PREPARED | 22 | Class has been loaded but not yet prepared.
    INVALID_METHODID | 23 | Invalid method.
    INVALID_LOCATION | 24 | Invalid location.
    INVALID_FIELDID | 25 | Invalid field.
    INVALID_FRAMEID | 30 | Invalid jframeID.
    NO_MORE_FRAMES | 31 | There are no more Java or JNI frames on the call stack.
    OPAQUE_FRAME | 32 | Information about the frame is not available.
    NOT_CURRENT_FRAME | 33 | Operation can only be performed on current frame.
    TYPE_MISMATCH | 34 | The variable is not an appropriate type for the function used.
    INVALID_SLOT | 35 | Invalid slot.
    DUPLICATE | 40 | Item already set.
    NOT_FOUND | 41 | Desired element not found.
    INVALID_MONITOR | 50 | Invalid monitor.
    NOT_MONITOR_OWNER | 51 | This thread doesn't own the monitor.
    INTERRUPT | 52 | The call has been interrupted before completion.
    INVALID_CLASS_FORMAT | 60 | The virtual machine attempted to read a class file and determined that the file is malformed or otherwise cannot be interpreted as a class file.
    CIRCULAR_CLASS_DEFINITION | 61 | A circularity has been detected while initializing a class.
    FAILS_VERIFICATION | 62 | The verifier detected that a class file, though well formed, contained some sort of internal inconsistency or security problem.
    ADD_METHOD_NOT_IMPLEMENTED | 63 | Adding methods has not been implemented.
    SCHEMA_CHANGE_NOT_IMPLEMENTED | 64 | Schema change has not been implemented.
    INVALID_TYPESTATE | 65 | The state of the thread has been modified, and is now inconsistent.
    HIERARCHY_CHANGE_NOT_IMPLEMENTED | 66 | A direct superclass is different for the new class version, or the set of directly implemented interfaces is different and canUnrestrictedlyRedefineClasses is false.
    DELETE_METHOD_NOT_IMPLEMENTED | 67 | The new class version does not declare a method declared in the old class version and canUnrestrictedlyRedefineClasses is false.
    UNSUPPORTED_VERSION | 68 | A class file has a version number not supported by this VM.
    NAMES_DONT_MATCH | 69 | The class name defined in the new class file is different from the name in the old class object.
    CLASS_MODIFIERS_CHANGE_NOT_IMPLEMENTED | 70 | The new class version has different modifiers and and canUnrestrictedlyRedefineClasses is false.
    METHOD_MODIFIERS_CHANGE_NOT_IMPLEMENTED | 71 | A method in the new class version has different modifiers than its counterpart in the old class version and and canUnrestrictedlyRedefineClasses is false.
    NOT_IMPLEMENTED | 99 | The functionality is not implemented in this virtual machine.
    NULL_POINTER | 100 | Invalid pointer.
    ABSENT_INFORMATION | 101 | Desired information is not available.
    INVALID_EVENT_TYPE | 102 | The specified event type id is not recognized.
    ILLEGAL_ARGUMENT | 103 | Illegal argument.
    OUT_OF_MEMORY | 110 | The function needed to allocate memory and no more memory was available for allocation.
    ACCESS_DENIED | 111 | Debugging has not been enabled in this virtual machine. JVMTI cannot be used.
    VM_DEAD | 112 | The virtual machine is not running.
    INTERNAL | 113 | An unexpected internal error has occurred.
    UNATTACHED_THREAD | 115 | The thread being used to call this function is not attached to the virtual machine. Calls must be made from attached threads.
    INVALID_TAG | 500 | object type id or class tag.
    ALREADY_INVOKING | 502 | Previous invoke not complete.
    INVALID_INDEX | 503 | Index is invalid.
    INVALID_LENGTH | 504 | The length is invalid.
    INVALID_STRING | 506 | The string is invalid.
    INVALID_CLASS_LOADER | 507 | The class loader is invalid.
    INVALID_ARRAY | 508 | The array is invalid.
    TRANSPORT_LOAD | 509 | Unable to load the transport.
    TRANSPORT_INIT | 510 | Unable to initialize the transport.
    NATIVE_METHOD | 511
    INVALID_COUNT | 512 | The count is invalid.

    EventKind Constants

    SINGLE_STEP | 1
    BREAKPOINT | 2
    FRAME_POP | 3
    EXCEPTION | 4
    USER_DEFINED | 5
    THREAD_START | 6
    THREAD_DEATH | 7
    THREAD_END | 7 | obsolete - was used in jvmdi
    CLASS_PREPARE | 8
    CLASS_UNLOAD | 9
    CLASS_LOAD | 10
    FIELD_ACCESS | 20
    FIELD_MODIFICATION | 21
    EXCEPTION_CATCH | 30
    METHOD_ENTRY | 40
    METHOD_EXIT | 41
    METHOD_EXIT_WITH_RETURN_VALUE | 42
    MONITOR_CONTENDED_ENTER | 43
    MONITOR_CONTENDED_ENTERED | 44
    MONITOR_WAIT | 45
    MONITOR_WAITED | 46
    VM_START | 90
    VM_INIT | 90 | obsolete - was used in jvmdi
    VM_DEATH | 99
    VM_DISCONNECTED | 100 | Never sent across JDWP

    ThreadStatus Constants

    ZOMBIE | 0
    RUNNING | 1
    SLEEPING | 2
    MONITOR | 3
    WAIT | 4

    SuspendStatus Constants

    SUSPEND_STATUS_SUSPENDED 0x1

    ClassStatus Constants

    VERIFIED | 1
    PREPARED | 2
    INITIALIZED | 4
    ERROR | 8

    TypeTag Constants

    CLASS | 1 | ReferenceType is a class.
    INTERFACE | 2 | ReferenceType is an interface.
    ARRAY | 3 | ReferenceType is an array.

    Tag Constants

    ARRAY | 91 | '[' - an array object (objectID size).
    BYTE | 66 | 'B' - a byte value (1 byte).
    CHAR | 67 | 'C' - a character value (2 bytes).
    OBJECT | 76 | 'L' - an object (objectID size).
    FLOAT | 70 | 'F' - a float value (4 bytes).
    DOUBLE | 68 | 'D' - a double value (8 bytes).
    INT | 73 | 'I' - an int value (4 bytes).
    LONG | 74 | 'J' - a long value (8 bytes).
    SHORT | 83 | 'S' - a short value (2 bytes).
    VOID | 86 | 'V' - a void value (no bytes).
    BOOLEAN | 90 | 'Z' - a boolean value (1 byte).
    STRING | 115 | 's' - a String object (objectID size).
    THREAD | 116 | 't' - a Thread object (objectID size).
    THREAD_GROUP | 103 | 'g' - a ThreadGroup object (objectID size).
    CLASS_LOADER | 108 | 'l' - a ClassLoader object (objectID size).
    CLASS_OBJECT | 99 | 'c' - a class object object (objectID size).

    StepDepth Constants

    INTO | 0 | Step into any method calls that occur before the end of the step.
    OVER | 1 | Step over any method calls that occur before the end of the step.
    OUT | 2 | Step out of the current method.

    StepSize Constants

    MIN | 0 | Step by the minimum possible amount (often a bytecode instruction).
    LINE | 1 | Step to the next source line unless there is no line number information in which case a MIN step is done instead.

    SuspendPolicy Constants

    NONE | 0 | Suspend no threads when this event is encountered.
    EVENT_THREAD | 1 | Suspend the event thread when this event is encountered.
    ALL | 2 | Suspend all threads when this event is encountered.

    InvokeOptions Constants

    The invoke options are a combination of zero or more of the following bit flags:
    INVOKE_SINGLE_THREADED | 0x01 | otherwise, all threads started.
    INVOKE_NONVIRTUAL | 0x02 | otherwise, normal virtual invoke (instance methods only)


JVM(TM) Tool Interface 1.1.102

JVMTM Tool Interface

Version 1.1
  • Introduction
    • What is the JVM Tool Interface?
    • Architecture
    • Writing Agents
    • Deploying Agents
    • Agent Command Line Options
    • Agent Start-Up
    • Agent Start-Up (OnLoad phase)
    • Agent Start-Up (Live phase)
    • Agent Shutdown
    • JAVA_TOOL_OPTIONS
    • Environments
    • Bytecode Instrumentation
    • Modified UTF-8 String Encoding
    • Specification Context
  • Functions
    • Accessing Functions
    • Function Return Values
    • Managing JNI Object References
    • Prerequisite State for Calling Functions
    • Exceptions and Functions
    • Function Index
      • Memory Management
      • Thread
      • Thread Group
      • Stack Frame
      • Force Early Return
      • Heap
      • Heap (1.0)
      • Local Variable
      • Breakpoint
      • Watched Field
      • Class
      • Object
      • Field
      • Method
      • Raw Monitor
      • JNI Function Interception
      • Event Management
      • Extension Mechanism
      • Capability
      • Timers
      • Class Loader Search
      • System Properties
      • General
    • Error Codes
  • Events
    • Event Index
  • Data Types
    • JNI Types Used in the JVM Tool Interface
    • JVM Tool Interface Base Types
    • Structure Type Definitions
    • Function Type Definitions
    • Enumeration Definitions
    • Function Table
  • Constant Index
  • Change History

What is the JVM Tool Interface?

The JVMTM Tool Interface (JVM TI) is a programming interface used by development and monitoring tools. It provides both a way to inspect the state and to control the execution of applications running in the JavaTM virtual machine (VM).

JVM TI is intended to provide a VM interface for the full breadth of tools that need access to VM state, including but not limited to: profiling, debugging, monitoring, thread analysis, and coverage analysis tools.

JVM TI may not be available in all implementations of the JavaTM virtual machine.

JVM TI is a two-way interface. A client of JVM TI, hereafter called an agent, can be notified of interesting occurrences through events. JVM TI can query and control the application through many functions, either in response to events or independent of them.

Agents run in the same process with and communicate directly with the virtual machine executing the application being examined. This communication is through a native interface (JVM TI). The native in-process interface allows maximal control with minimal intrusion on the part of a tool. Typically, agents are relatively compact. They can be controlled by a separate process which implements the bulk of a tool's function without interfering with the target application's normal execution.

Architecture

Tools can be written directly to JVM TI or indirectly through higher level interfaces. The Java Platform Debugger Architecture includes JVM TI, but also contains higher-level, out-of-process debugger interfaces. The higher-level interfaces are more appropriate than JVM TI for many tools. For more information on the Java Platform Debugger Architecture, see the Java Platform Debugger Architecture website.

Writing Agents

Agents can be written in any native language that supports C language calling conventions and C or C++ definitions.

The function, event, data type, and constant definitions needed for using JVM TI are defined in the include file jvmti.h. To use these definitions add the J2SETM include directory to your include path and add
#include <jvmti.h>
to your source code.

Deploying Agents

An agent is deployed in a platform specific manner but is typically the platform equivalent of a dynamic library. On the WindowsTM operating system, for example, an agent library is a "Dynamic Linked Library" (DLL). On the SolarisTM Operating Environment, an agent library is a shared object (.so file).

An agent may be started at VM startup by specifying the agent library name using a command line option. Some implementations may support a mechanism to start agents in the live phase. The details of how this is initiated are implementation specific.

Agent Command Line Options

The term "command-line option" is used below to mean options supplied in the JavaVMInitArgs argument to the JNI_CreateJavaVM function of the JNI Invocation API.

One of the two following command-line options is used on VM startup to properly load and run agents. These arguments identify the library containing the agent as well as an options string to be passed in at startup.
-agentlib:<agent-lib-name>=<options>
The name following -agentlib: is the name of the library to load. Lookup of the library, both its full name and location, proceeds in a platform-specific manner. Typically, the <agent-lib-name> is expanded to an operating system specific file name. The <options> will be passed to the agent on start-up. For example, if the option -agentlib:foo=opt1,opt2 is specified, the VM will attempt to load the shared library foo.dll from the system PATH under WindowsTM or libfoo.so from the LD_LIBRARY_PATH under the SolarisTM operating environment.
-agentpath:<path-to-agent>=<options>
The path following -agentpath: is the absolute path from which to load the library. No library name expansion will occur. The <options> will be passed to the agent on start-up. For example, if the option -agentpath:c:\myLibs\foo.dll=opt1,opt2 is specified, the VM will attempt to load the shared library c:\myLibs\foo.dll.
The start-up routine Agent_OnLoad in the library will be invoked.

Libraries loaded with -agentlib: or -agentpath: will be searched for JNI native method implementations to facilitate the use of Java programming language code in tools, as is needed for bytecode instrumentation.

The agent libraries will be searched after all other libraries have been searched (agents wishing to override or intercept the native method implementations of non-agent methods can use the NativeMethodBind event).

These switches do the above and nothing more - they do not change the state of the VM or JVM TI. No command line options are needed to enable JVM TI or aspects of JVM TI, this is handled programmatically by the use of capabilities.

Agent Start-Up

The VM starts each agent by invoking a start-up function. If the agent is started in the OnLoad phase the function Agent_OnLoad will be invoked. If the agent is started in the live phase the function Agent_OnAttach will be invoked. Exactly one call to a start-up function is made per agent.

Agent Start-Up (OnLoad phase)

If an agent is started during the OnLoad phase then its agent library must export a start-up function with the following prototype:
JNIEXPORT jint JNICALL
Agent_OnLoad(JavaVM *vm, char *options, void *reserved)
The VM will start the agent by calling this function. It will be called early enough in VM initialization that:
  • system properties may be set before they have been used in the start-up of the VM
  • the full set of capabilities is still available (note that capabilities that configure the VM may only be available at this time--see the Capability function section)
  • no bytecodes have executed
  • no classes have been loaded
  • no objects have been created

The VM will call the Agent_OnLoad function with <options> as the second argument - that is, using the command-line option examples, "opt1,opt2" will be passed to the char *options argument of Agent_OnLoad. The options argument is encoded as a modified UTF-8 string. If =<options> is not specified, a zero length string is passed to options. The lifespan of the options string is the Agent_OnLoad call. If needed beyond this time the string or parts of the string must be copied. The period between when Agent_OnLoad is called and when it returns is called the OnLoad phase. Since the VM is not initialized during the OnLoad phase, the set of allowed operations inside Agent_OnLoad is restricted (see the function descriptions for the functionality available at this time). The agent can safely process the options and set event callbacks with SetEventCallbacks. Once the VM initialization event is received (that is, the VMInit callback is invoked), the agent can complete its initialization.

Rationale: Early startup is required so that agents can set the desired capabilities, many of which must be set before the VM is initialized. In JVMDI, the -Xdebug command-line option provided very coarse-grain control of capabilities. JVMPI implementations use various tricks to provide a single "JVMPI on" switch. No reasonable command-line option could provide the fine-grain of control required to balance needed capabilities vs performance impact. Early startup is also needed so that agents can control the execution environment - modifying the file system and system properties to install their functionality.

The return value from Agent_OnLoad is used to indicate an error. Any value other than zero indicates an error and causes termination of the VM.

Agent Start-Up (Live phase)

A VM may support a mechanism that allows agents to be started in the VM during the live phase. The details of how this is supported, are implementation specific. For example, a tool may use some platform specific mechanism, or implementation specific API, to attach to the running VM, and request it start a given agent.

If an agent is started during the live phase then its agent library must export a start-up function with the following prototype:
JNIEXPORT jint JNICALL
Agent_OnAttach(JavaVM* vm, char *options, void *reserved)

The VM will start the agent by calling this function. It will be called in the context of a thread that is attached to the VM. The first argument <vm> is the Java VM. The <options> argument is the startup options provided to the agent. <options> is encoded as a modified UTF-8 string. If startup options were not provided, a zero length string is passed to options. The lifespan of the options string is the Agent_OnAttach call. If needed beyond this time the string or parts of the string must be copied.

Note that some capabilities may not be available in the live phase.

The Agent_OnAttach function initializes the agent and returns a value to the VM to indicate if an error occurred. Any value other than zero indicates an error. An error does not cause the VM to terminate. Instead the VM ignores the error, or takes some implementation specific action -- for example it might print an error to standard error, or record the error in a system log.

Agent Shutdown

The library may optionally export a shutdown function with the following prototype:
JNIEXPORT void JNICALL
Agent_OnUnload(JavaVM *vm)
This function will be called by the VM when the library is about to be unloaded. The library will be unloaded and this function will be called if some platform specific mechanism causes the unload (an unload mechanism is not specified in this document) or the library is (in effect) unloaded by the termination of the VM whether through normal termination or VM failure, including start-up failure. Uncontrolled shutdown is, of couse, an exception to this rule. Note the distinction between this function and the VM Death event: for the VM Death event to be sent, the VM must have run at least to the point of initialization and a valid JVM TI environment must exist which has set a callback for VMDeath and enabled the event None of these are required for Agent_OnUnload and this function is also called if the library is unloaded for other reasons. In the case that a VM Death event is sent, it will be sent before this function is called (assuming this function is called due to VM termination). This function can be used to clean-up resources allocated by the agent.

JAVA_TOOL_OPTIONS

Since the command-line cannot always be accessed or modified, for example in embedded VMs or simply VMs launched deep within scripts, a JAVA_TOOL_OPTIONS variable is provided so that agents may be launched in these cases.

Platforms which support environment variables or other named strings, may support the JAVA_TOOL_OPTIONS variable. This variable will be broken into options at white-space boundaries. White-space characters include space, tab, carriage-return, new-line, vertical-tab, and form-feed. Sequences of white-space characters are considered equivalent to a single white-space character. No white-space is included in the options unless quoted. Quoting is as follows:
  • All characters enclosed between a pair of single quote marks (''), except a single quote, are quoted.
  • Double quote characters have no special meaning inside a pair of single quote marks.
  • All characters enclosed between a pair of double quote marks (""), except a double quote, are quoted.
  • Single quote characters have no special meaning inside a pair of double quote marks.
  • A quoted part can start or end anywhere in the variable.
  • White-space characters have no special meaning when quoted -- they are included in the option like any other character and do not mark white-space boundaries.
  • The pair of quote marks is not included in the option.
JNI_CreateJavaVM (in the JNI Invocation API) will prepend these options to the options supplied in its JavaVMInitArgs argument. Platforms may disable this feature in cases where security is a concern; for example, the Reference Implementation disables this feature on Unix systems when the effective user or group ID differs from the real ID. This feature is intended to support the initialization of tools -- specifically including the launching of native or Java programming language agents. Multiple tools may wish to use this feature, so the variable should not be overwritten, instead, options should be appended to the variable. Note that since the variable is processed at the time of the JNI Invocation API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled.

Environments

The JVM TI specification supports the use of multiple simultaneous JVM TI agents. Each agent has its own JVM TI environment. That is, the JVM TI state is separate for each agent - changes to one environment do not affect the others. The state of a JVM TI environment includes:
  • the event callbacks
  • the set of events which are enabled
  • the capabilities
  • the memory allocation/deallocation hooks
Although their JVM TI state is separate, agents inspect and modify the shared state of the VM, they also share the native environment in which they execute. As such, an agent can perturb the results of other agents or cause them to fail. It is the responsibility of the agent writer to specify the level of compatibility with other agents. JVM TI implementations are not capable of preventing destructive interactions between agents. Techniques to reduce the likelihood of these occurrences are beyond the scope of this document.

An agent creates a JVM TI environment by passing a JVM TI version as the interface ID to the JNI Invocation API function GetEnv. See Accessing JVM TI Functions for more details on the creation and use of JVM TI environments. Typically, JVM TI environments are created by calling GetEnv from Agent_OnLoad.

Bytecode Instrumentation

This interface does not include some events that one might expect in an interface with profiling support. Some examples include object allocation events and full speed method enter and exit events. The interface instead provides support for bytecode instrumentation, the ability to alter the Java virtual machine bytecode instructions which comprise the target program. Typically, these alterations are to add "events" to the code of a method - for example, to add, at the beginning of a method, a call to MyProfiler.methodEntered(). Since the changes are purely additive, they do not modify application state or behavior. Because the inserted agent code is standard bytecodes, the VM can run at full speed, optimizing not only the target program but also the instrumentation. If the instrumentation does not involve switching from bytecode execution, no expensive state transitions are needed. The result is high performance events. This approach also provides complete control to the agent: instrumentation can be restricted to "interesting" portions of the code (e.g., the end user's code) and can be conditional. Instrumentation can run entirely in Java programming language code or can call into the native agent. Instrumentation can simply maintain counters or can statistically sample events.

Instrumentation can be inserted in one of three ways:
  • Static Instrumentation: The class file is instrumented before it is loaded into the VM - for example, by creating a duplicate directory of *.class files which have been modified to add the instrumentation. This method is extremely awkward and, in general, an agent cannot know the origin of the class files which will be loaded.
  • Load-Time Instrumentation: When a class file is loaded by the VM, the raw bytes of the class file are sent for instrumentation to the agent. The ClassFileLoadHook event, triggered by the class load, provides this functionality. This mechanism provides efficient and complete access to one-time instrumentation.
  • Dynamic Instrumentation: A class which is already loaded (and possibly even running) is modified. This optional feature is provided by the ClassFileLoadHook event, triggered by calling the RetransformClasses function. Classes can be modified multiple times and can be returned to their original state. The mechanism allows instrumentation which changes during the course of execution.

The class modification functionality provided in this interface is intended to provide a mechanism for instrumentation (the ClassFileLoadHook event and the RetransformClasses function) and, during development, for fix-and-continue debugging (the RedefineClasses function).

Care must be taken to avoid perturbing dependencies, especially when instrumenting core classes. For example, an approach to getting notification of every object allocation is to instrument the constructor on Object. Assuming that the constructor is initially empty, the constructor could be changed to:
      public Object() {
        MyProfiler.allocationTracker(this);
      }
However, if this change was made using the ClassFileLoadHook event then this might impact a typical VM as follows: the first created object will call the constructor causing a class load of MyProfiler; which will then cause object creation, and since MyProfiler isn't loaded yet, infinite recursion; resulting in a stack overflow. A refinement of this would be to delay invoking the tracking method until a safe time. For example, trackAllocations could be set in the handler for the VMInit event.
      static boolean trackAllocations = false;

      public Object() {
        if (trackAllocations) {
          MyProfiler.allocationTracker(this);
        }
      }

The SetNativeMethodPrefix allows native methods to be instrumented by the use of wrapper methods.

Modified UTF-8 String Encoding

JVM TI uses modified UTF-8 to encode character strings. This is the same encoding used by JNI. Modified UTF-8 differs from standard UTF-8 in the representation of supplementary characters and of the null character. See the Modified UTF-8 Strings section of the JNI specification for details.

Specification Context

Since this interface provides access to the state of applications running in the Java virtual machine; terminology refers to the Java platform and not the native platform (unless stated otherwise). For example:
  • "thread" means Java programming language thread.
  • "stack frame" means Java virtual machine stack frame.
  • "class" means Java programming language class.
  • "heap" means Java virtual machine heap.
  • "monitor" means Java programming language object monitor.

Sun, Sun Microsystems, the Sun logo, Java, and JVM are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

Functions

Accessing Functions

Native code accesses JVM TI features by calling JVM TI functions. Access to JVM TI functions is by use of an interface pointer in the same manner as Java Native Interface (JNI) functions are accessed. The JVM TI interface pointer is called the environment pointer.

An environment pointer is a pointer to an environment and has the type jvmtiEnv*. An environment has information about its JVM TI connection. The first value in the environment is a pointer to the function table. The function table is an array of pointers to JVM TI functions. Every function pointer is at a predefined offset inside the array.

When used from the C language: double indirection is used to access the functions; the environment pointer provides context and is the first parameter of each function call; for example:
jvmtiEnv *jvmti;
...
jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &class_count, &classes);

When used from the C++ language: functions are accessed as member functions of jvmtiEnv; the environment pointer is not passed to the function call; for example:
jvmtiEnv *jvmti;
...
jvmtiError err = jvmti->GetLoadedClasses(&class_count, &classes);
Unless otherwise stated, all examples and declarations in this specification use the C language.

A JVM TI environment can be obtained through the JNI Invocation API GetEnv function:
jvmtiEnv *jvmti;
...
(*jvm)->GetEnv(jvm, &jvmti, JVMTI_VERSION_1_0);
Each call to GetEnv creates a new JVM TI connection and thus a new JVM TI environment. The version argument of GetEnv must be a JVM TI version. The returned environment may have a different version than the requested version but the returned environment must be compatible. GetEnv will return JNI_EVERSION if a compatible version is not available, if JVM TI is not supported or JVM TI is not supported in the current VM configuration. Other interfaces may be added for creating JVM TI environments in specific contexts. Each environment has its own state (for example, desired events, event handling functions, and capabilities). An environment is released with DisposeEnvironment. Thus, unlike JNI which has one environment per thread, JVM TI environments work across threads and are created dynamically.

Function Return Values

JVM TI functions always return an error code via the jvmtiError function return value. Some functions can return additional values through pointers provided by the calling function. In some cases, JVM TI functions allocate memory that your program must explicitly deallocate. This is indicated in the individual JVM TI function descriptions. Empty lists, arrays, sequences, etc are returned as NULL.

In the event that the JVM TI function encounters an error (any return value other than JVMTI_ERROR_NONE) the values of memory referenced by argument pointers is undefined, but no memory will have been allocated and no global references will have been allocated. If the error occurs because of invalid input, no action will have occurred.

Managing JNI Object References

JVM TI functions identify objects with JNI references (jobject and jclass) and their derivatives (jthread and jthreadGroup). References passed to JVM TI functions can be either global or local, but they must be strong references. All references returned by JVM TI functions are local references--these local references are created during the JVM TI call. Local references are a resource that must be managed (see the JNI Documentation). When threads return from native code all local references are freed. Note that some threads, including typical agent threads, will never return from native code. A thread is ensured the ability to create sixteen local references without the need for any explicit management. For threads executing a limited number of JVM TI calls before returning from native code (for example, threads processing events), it may be determined that no explicit management is needed. However, long running agent threads will need explicit local reference management--usually with the JNI functions PushLocalFrame and PopLocalFrame. Conversely, to preserve references beyond the return from native code, they must be converted to global references. These rules do not apply to jmethodID and jfieldID as they are not jobjects.

Prerequisite State for Calling Functions

Unless the function explicitly states that the agent must bring a thread or the VM to a particular state (for example, suspended), the JVM TI implementation is responsible for bringing the VM to a safe and consistent state for performing the function.

Exceptions and Functions

JVM TI functions never throw exceptions; error conditions are communicated via the function return value. Any existing exception state is preserved across a call to a JVM TI function. See the Java Exceptions section of the JNI specification for information on handling exceptions.

Function Index

  • Memory Management
    • Allocate
    • Deallocate
  • Thread
    • Get Thread State
    • Get Current Thread
    • Get All Threads
    • Suspend Thread
    • Suspend Thread List
    • Resume Thread
    • Resume Thread List
    • Stop Thread
    • Interrupt Thread
    • Get Thread Info
    • Get Owned Monitor Info
    • Get Owned Monitor Stack Depth Info
    • Get Current Contended Monitor
    • Run Agent Thread
    • Set Thread Local Storage
    • Get Thread Local Storage
  • Thread Group
    • Get Top Thread Groups
    • Get Thread Group Info
    • Get Thread Group Children
  • Stack Frame
    • Get Stack Trace
    • Get All Stack Traces
    • Get Thread List Stack Traces
    • Get Frame Count
    • Pop Frame
    • Get Frame Location
    • Notify Frame Pop
  • Force Early Return
    • Force Early Return - Object
    • Force Early Return - Int
    • Force Early Return - Long
    • Force Early Return - Float
    • Force Early Return - Double
    • Force Early Return - Void
  • Heap
    • Follow References
    • Iterate Through Heap
    • Get Tag
    • Set Tag
    • Get Objects With Tags
    • Force Garbage Collection
  • Heap (1.0)
    • Iterate Over Objects Reachable From Object
    • Iterate Over Reachable Objects
    • Iterate Over Heap
    • Iterate Over Instances Of Class
  • Local Variable
    • Get Local Variable - Object
    • Get Local Variable - Int
    • Get Local Variable - Long
    • Get Local Variable - Float
    • Get Local Variable - Double
    • Set Local Variable - Object
    • Set Local Variable - Int
    • Set Local Variable - Long
    • Set Local Variable - Float
    • Set Local Variable - Double
  • Breakpoint
    • Set Breakpoint
    • Clear Breakpoint
  • Watched Field
    • Set Field Access Watch
    • Clear Field Access Watch
    • Set Field Modification Watch
    • Clear Field Modification Watch
  • Class
    • Get Loaded Classes
    • Get Classloader Classes
    • Get Class Signature
    • Get Class Status
    • Get Source File Name
    • Get Class Modifiers
    • Get Class Methods
    • Get Class Fields
    • Get Implemented Interfaces
    • Get Class Version Numbers
    • Get Constant Pool
    • Is Interface
    • Is Array Class
    • Is Modifiable Class
    • Get Class Loader
    • Get Source Debug Extension
    • Retransform Classes
    • Redefine Classes
  • Object
    • Get Object Size
    • Get Object Hash Code
    • Get Object Monitor Usage
  • Field
    • Get Field Name (and Signature)
    • Get Field Declaring Class
    • Get Field Modifiers
    • Is Field Synthetic
  • Method
    • Get Method Name (and Signature)
    • Get Method Declaring Class
    • Get Method Modifiers
    • Get Max Locals
    • Get Arguments Size
    • Get Line Number Table
    • Get Method Location
    • Get Local Variable Table
    • Get Bytecodes
    • Is Method Native
    • Is Method Synthetic
    • Is Method Obsolete
    • Set Native Method Prefix
    • Set Native Method Prefixes
  • Raw Monitor
    • Create Raw Monitor
    • Destroy Raw Monitor
    • Raw Monitor Enter
    • Raw Monitor Exit
    • Raw Monitor Wait
    • Raw Monitor Notify
    • Raw Monitor Notify All
  • JNI Function Interception
    • Set JNI Function Table
    • Get JNI Function Table
  • Event Management
    • Set Event Callbacks
    • Set Event Notification Mode
    • Generate Events
  • Extension Mechanism
    • Get Extension Functions
    • Get Extension Events
    • Set Extension Event Callback
  • Capability
    • Get Potential Capabilities
    • Add Capabilities
    • Relinquish Capabilities
    • Get Capabilities
  • Timers
    • Get Current Thread CPU Timer Information
    • Get Current Thread CPU Time
    • Get Thread CPU Timer Information
    • Get Thread CPU Time
    • Get Timer Information
    • Get Time
    • Get Available Processors
  • Class Loader Search
    • Add To Bootstrap Class Loader Search
    • Add To System Class Loader Search
  • System Properties
    • Get System Properties
    • Get System Property
    • Set System Property
  • General
    • Get Phase
    • Dispose Environment
    • Set Environment Local Storage
    • Get Environment Local Storage
    • Get Version Number
    • Get Error Name
    • Set Verbose Flag
    • Get JLocation Format

Memory Management

Memory Management functions:
  • Allocate
  • Deallocate
These functions provide for the allocation and deallocation of memory used by JVM TI functionality and can be used to provide working memory for agents. Memory managed by JVM TI is not compatible with other memory allocation libraries and mechanisms.

Allocate

jvmtiError
Allocate(jvmtiEnv* env,
            jlong size,
            unsigned char** mem_ptr)
Allocate an area of memory through the JVM TI allocator. The allocated memory should be freed with Deallocate.

Phase | Callback Safe | Position | Since
may be called during any phase | This function may be called from the callbacks to the Heap iteration functions, or from the event handlers for the GarbageCollectionStart, GarbageCollectionFinish, and ObjectFree events. | 46 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
size | jlong | The number of bytes to allocate. Rationale: jlong is used for compatibility with JVMDI.
mem_ptr | unsigned char** | On return, a pointer to the beginning of the allocated memory. If size is zero, NULL is returned. Agent passes a pointer to a unsigned char*. On return, the unsigned char* points to a newly allocated array of size size. The array should be freed with Deallocate.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_OUT_OF_MEMORY | Memory request cannot be honored.
JVMTI_ERROR_ILLEGAL_ARGUMENT | size is less than zero.
JVMTI_ERROR_NULL_POINTER | mem_ptr is NULL.

Deallocate

jvmtiError
Deallocate(jvmtiEnv* env,
            unsigned char* mem)
Deallocate mem using the JVM TI allocator. This function should be used to deallocate any memory allocated and returned by a JVM TI function (including memory allocated with Allocate). All allocated memory must be deallocated or the memory cannot be reclaimed.

Phase | Callback Safe | Position | Since
may be called during any phase | This function may be called from the callbacks to the Heap iteration functions, or from the event handlers for the GarbageCollectionStart, GarbageCollectionFinish, and ObjectFree events. | 47 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
mem | unsigned char * | A pointer to the beginning of the allocated memory. Please ignore "On return, the elements are set." Agent passes an array of unsigned char. The incoming values of the elements of the array are ignored. On return, the elements are set. If mem is NULL, the call is ignored.

Errors
This function returns a universal error

Thread

Thread functions:
  • Get Thread State
  • Get Current Thread
  • Get All Threads
  • Suspend Thread
  • Suspend Thread List
  • Resume Thread
  • Resume Thread List
  • Stop Thread
  • Interrupt Thread
  • Get Thread Info
  • Get Owned Monitor Info
  • Get Owned Monitor Stack Depth Info
  • Get Current Contended Monitor
  • Run Agent Thread
  • Set Thread Local Storage
  • Get Thread Local Storage
Thread function types:
  • Agent Start Function
Thread types:
  • jvmtiThreadInfo - Thread information structure
  • jvmtiMonitorStackDepthInfo - Monitor stack depth information structure
Thread flags and constants:
  • Thread State Flags
  • java.lang.Thread.State Conversion Masks
  • Thread Priority Constants

Get Thread State

jvmtiError
GetThreadState(jvmtiEnv* env,
            jthread thread,
            jint* thread_state_ptr)
Get the state of a thread. The state of the thread is represented by the answers to the hierarchical set of questions below:
  • Alive?
    • Not alive.
      • Why not alive?
        • New.
        • Terminated (JVMTI_THREAD_STATE_TERMINATED)
    • Alive (JVMTI_THREAD_STATE_ALIVE)
      • Suspended?
        • Suspended (JVMTI_THREAD_STATE_SUSPENDED)
        • Not suspended
      • Interrupted?
        • Interrupted (JVMTI_THREAD_STATE_INTERRUPTED)
        • Not interrupted.
      • In native?
        • In native code (JVMTI_THREAD_STATE_IN_NATIVE)
        • In Java programming language code
      • What alive state?
        • Runnable (JVMTI_THREAD_STATE_RUNNABLE)
        • Blocked (JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER)
        • Waiting (JVMTI_THREAD_STATE_WAITING)
          • Timed wait?
            • Indefinite (JVMTI_THREAD_STATE_WAITING_INDEFINITELY
            • Timed (JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT)
          • Why waiting?
            • Object.wait (JVMTI_THREAD_STATE_IN_OBJECT_WAIT)
            • LockSupport.park (JVMTI_THREAD_STATE_PARKED)
            • Sleeping (JVMTI_THREAD_STATE_SLEEPING)

The answers are represented by the following bit vector.
Thread State Flags
Constant | Value | Description
JVMTI_THREAD_STATE_ALIVE | 0x0001 | Thread is alive. Zero if thread is new (not started) or terminated.
JVMTI_THREAD_STATE_TERMINATED | 0x0002 | Thread has completed execution.
JVMTI_THREAD_STATE_RUNNABLE | 0x0004 | Thread is runnable.
JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER | 0x0400 | Thread is waiting to enter a synchronization block/method or, after an Object.wait(), waiting to re-enter a synchronization block/method.
JVMTI_THREAD_STATE_WAITING | 0x0080 | Thread is waiting.
JVMTI_THREAD_STATE_WAITING_INDEFINITELY | 0x0010 | Thread is waiting without a timeout. For example, Object.wait().
JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT | 0x0020 | Thread is waiting with a maximum time to wait specified. For example, Object.wait(long).
JVMTI_THREAD_STATE_SLEEPING | 0x0040 | Thread is sleeping -- Thread.sleep(long).
JVMTI_THREAD_STATE_IN_OBJECT_WAIT | 0x0100 | Thread is waiting on an object monitor -- Object.wait.
JVMTI_THREAD_STATE_PARKED | 0x0200 | Thread is parked, for example: LockSupport.park, LockSupport.parkUtil and LockSupport.parkNanos.
JVMTI_THREAD_STATE_SUSPENDED | 0x100000 | Thread suspended. java.lang.Thread.suspend() or a JVM TI suspend function (such as SuspendThread) has been called on the thread. If this bit is set, the other bits refer to the thread state before suspension.
JVMTI_THREAD_STATE_INTERRUPTED | 0x200000 | Thread has been interrupted.
JVMTI_THREAD_STATE_IN_NATIVE 0x400000 Thread is in native code--that is, a native method is running which has not called back into the VM or Java programming language code.

This flag is not set when running VM compiled Java programming language code nor is it set when running VM code or VM support code. Native VM interface functions, such as JNI and JVM TI functions, may be implemented as VM code.
JVMTI_THREAD_STATE_VENDOR_1 | 0x10000000 | Defined by VM vendor.
JVMTI_THREAD_STATE_VENDOR_2 | 0x20000000 | Defined by VM vendor.
JVMTI_THREAD_STATE_VENDOR_3 | 0x40000000 | Defined by VM vendor.
The following definitions are used to convert JVM TI thread state to java.lang.Thread.State style states.
java.lang.Thread.State Conversion Masks
Constant | Value | Description
JVMTI_JAVA_LANG_THREAD_STATE_MASK | JVMTI_THREAD_STATE_TERMINATED | JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT | Mask the state with this before comparison
JVMTI_JAVA_LANG_THREAD_STATE_NEW | 0 | java.lang.Thread.State.NEW
JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED | JVMTI_THREAD_STATE_TERMINATED | java.lang.Thread.State.TERMINATED
JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE | JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE | java.lang.Thread.State.RUNNABLE
JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED | JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER | java.lang.Thread.State.BLOCKED
JVMTI_JAVA_LANG_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY | java.lang.Thread.State.WAITING
JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING | JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT | java.lang.Thread.State.TIMED_WAITING
Rules

There can be no more than one answer to a question, although there can be no answer (because the answer is unknown, does not apply, or none of the answers is correct). An answer is set only when the enclosing answers match. That is, no more than one of
  • JVMTI_THREAD_STATE_RUNNABLE
  • JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER
  • JVMTI_THREAD_STATE_WAITING
can be set (a J2SETM compliant implementation will always set one of these if JVMTI_THREAD_STATE_ALIVE is set). And if any of these are set, the enclosing answer JVMTI_THREAD_STATE_ALIVE is set. No more than one of
  • JVMTI_THREAD_STATE_WAITING_INDEFINITELY
  • JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT
can be set (a J2SETM compliant implementation will always set one of these if JVMTI_THREAD_STATE_WAITING is set). And if either is set, the enclosing answers JVMTI_THREAD_STATE_ALIVE and JVMTI_THREAD_STATE_WAITING are set. No more than one of
  • JVMTI_THREAD_STATE_IN_OBJECT_WAIT
  • JVMTI_THREAD_STATE_PARKED
  • JVMTI_THREAD_STATE_SLEEPING
can be set. And if any of these is set, the enclosing answers JVMTI_THREAD_STATE_ALIVE and JVMTI_THREAD_STATE_WAITING are set. Also, if JVMTI_THREAD_STATE_SLEEPING is set, then JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT is set. If a state A is implemented using the mechanism of state B then it is state A which is returned by this function. For example, if Thread.sleep(long) is implemented using Object.wait(long) then it is still JVMTI_THREAD_STATE_SLEEPING which is returned. More than one of
  • JVMTI_THREAD_STATE_SUSPENDED
  • JVMTI_THREAD_STATE_INTERRUPTED
  • JVMTI_THREAD_STATE_IN_NATIVE
can be set, but if any is set, JVMTI_THREAD_STATE_ALIVE is set.

And finally, JVMTI_THREAD_STATE_TERMINATED cannot be set unless JVMTI_THREAD_STATE_ALIVE is not set.

The thread state representation is designed for extension in future versions of the specification; thread state values should be used accordingly, that is they should not be used as ordinals. Most queries can be made by testing a single bit, if use in a switch statement is desired, the state bits should be masked with the interesting bits. All bits not defined above are reserved for future use. A VM, compliant to the current specification, must set reserved bits to zero. An agent should ignore reserved bits -- they should not be assumed to be zero and thus should not be included in comparisons.

Examples

Note that the values below exclude reserved and vendor bits.

The state of a thread blocked at a synchronized-statement would be:
            JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER
The state of a thread which hasn't started yet would be:
            0
The state of a thread at a Object.wait(3000) would be:
            JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING +
                JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT +
                JVMTI_THREAD_STATE_MONITOR_WAITING
The state of a thread suspended while runnable would be:
            JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED

Testing the State

In most cases, the thread state can be determined by testing the one bit corresponding to that question. For example, the code to test if a thread is sleeping:
    jint state;
    jvmtiError err;

    err = (*jvmti)->GetThreadState(jvmti, thread, &state);
    if (err == JVMTI_ERROR_NONE) {
       if (state & JVMTI_THREAD_STATE_SLEEPING) {  ...

For waiting (that is, in Object.wait, parked, or sleeping) it would be:
       if (state & JVMTI_THREAD_STATE_WAITING) {  ...
For some states, more than one bit will need to be tested as is the case when testing if a thread has not yet been started:
       if ((state & (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0)  {  ...
To distinguish timed from untimed Object.wait:
       if (state & JVMTI_THREAD_STATE_IN_OBJECT_WAIT)  {
             if (state & JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT)  {
               printf("in Object.wait(long timeout)\n");
             } else {
               printf("in Object.wait()\n");
             }
           }

Relationship to java.lang.Thread.State

The thread state represented by java.lang.Thread.State returned from java.lang.Thread.getState() is a subset of the information returned from this function. The corresponding java.lang.Thread.State can be determined by using the provided conversion masks. For example, this returns the name of the java.lang.Thread.State thread state:
        err = (*jvmti)->GetThreadState(jvmti, thread, &state);
        abortOnError(err);
            switch (state & JVMTI_JAVA_LANG_THREAD_STATE_MASK) {
            case JVMTI_JAVA_LANG_THREAD_STATE_NEW:
              return "NEW";
            case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED:
              return "TERMINATED";
            case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE:
              return "RUNNABLE";
            case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED:
              return "BLOCKED";
            case JVMTI_JAVA_LANG_THREAD_STATE_WAITING:
              return "WAITING";
            case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING:
              return "TIMED_WAITING";
            }

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 17 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
thread | jthread | The thread to query. If thread is NULL, the current thread is used.
thread_state_ptr | jint* | On return, points to state flags, as defined by the Thread State Flags. Agent passes a pointer to a jint. On return, the jint has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_NULL_POINTER | thread_state_ptr is NULL.

Get Current Thread

jvmtiError
GetCurrentThread(jvmtiEnv* env,
            jthread* thread_ptr)
Get the current thread. The current thread is the Java programming language thread which has called the function.

Note that most JVM TI functions that take a thread as an argument will accept NULL to mean the current thread.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 18 | 1.1

Capabilities
Required Functionality

Parameters
Name | Type | Description
thread_ptr | jthread* | On return, points to the current thread. Agent passes a pointer to a jthread. On return, the jthread has been set. The object returned by thread_ptr is a JNI local reference and must be managed.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | thread_ptr is NULL.

Get All Threads

jvmtiError
GetAllThreads(jvmtiEnv* env,
            jint* threads_count_ptr,
            jthread** threads_ptr)
Get all live threads. The threads are Java programming language threads; that is, threads that are attached to the VM. A thread is live if java.lang.Thread.isAlive() would return true, that is, the thread has been started and has not yet died. The universe of threads is determined by the context of the JVM TI environment, which typically is all threads attached to the VM. Note that this includes JVM TI agent threads (see RunAgentThread).

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 4 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
threads_count_ptr | jint* | On return, points to the number of running threads. Agent passes a pointer to a jint. On return, the jint has been set.
threads_ptr | jthread** | On return, points to an array of references, one for each running thread. Agent passes a pointer to a jthread*. On return, the jthread* points to a newly allocated array of size *threads_count_ptr. The array should be freed with Deallocate. The objects returned by threads_ptr are JNI local references and must be managed.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | threads_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | threads_ptr is NULL.

Suspend Thread

jvmtiError
SuspendThread(jvmtiEnv* env,
            jthread thread)
Suspend the specified thread. If the calling thread is specified, this function will not return until some other thread calls ResumeThread. If the thread is currently suspended, this function does nothing and returns an error.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 5 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_suspend | Can suspend and resume threads

Parameters
Name | Type | Description
thread | jthread | The thread to suspend. If thread is NULL, the current thread is used.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_suspend. Use AddCapabilities.
JVMTI_ERROR_THREAD_SUSPENDED | Thread already suspended.
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).

Suspend Thread List

jvmtiError
SuspendThreadList(jvmtiEnv* env,
            jint request_count,
            const jthread* request_list,
            jvmtiError* results)
Suspend the request_count threads specified in the request_list array. Threads may be resumed with ResumeThreadList or ResumeThread. If the calling thread is specified in the request_list array, this function will not return until some other thread resumes it. Errors encountered in the suspension of a thread are returned in the results array, not in the return value of this function. Threads that are currently suspended do not change state.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 92 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_suspend | Can suspend and resume threads

Parameters
Name | Type | Description
request_count | jint | The number of threads to suspend.
request_list | const jthread* | The list of threads to suspend. Agent passes in an array of request_count elements of jthread.
results | jvmtiError* | An agent supplied array of request_count elements. On return, filled with the error code for the suspend of the corresponding thread. The error code will be JVMTI_ERROR_NONE if the thread was suspended by this call. Possible error codes are those specified for SuspendThread. Agent passes an array large enough to hold request_count elements of jvmtiError. The incoming values of the elements of the array are ignored. On return, the elements are set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_suspend. Use AddCapabilities.
JVMTI_ERROR_ILLEGAL_ARGUMENT | request_count is less than 0.
JVMTI_ERROR_NULL_POINTER | request_list is NULL.
JVMTI_ERROR_NULL_POINTER | results is NULL.

Resume Thread

jvmtiError
ResumeThread(jvmtiEnv* env,
            jthread thread)
Resume a suspended thread. Any threads currently suspended through a JVM TI suspend function (eg. SuspendThread) or java.lang.Thread.suspend() will resume execution; all other threads are unaffected.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 6 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_suspend | Can suspend and resume threads

Parameters
Name | Type | Description
thread | jthread | The thread to resume.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_suspend. Use AddCapabilities.
JVMTI_ERROR_THREAD_NOT_SUSPENDED | Thread was not suspended.
JVMTI_ERROR_INVALID_TYPESTATE | The state of the thread has been modified, and is now inconsistent.
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).

Resume Thread List

jvmtiError
ResumeThreadList(jvmtiEnv* env,
            jint request_count,
            const jthread* request_list,
            jvmtiError* results)
Resume the request_count threads specified in the request_list array. Any thread suspended through a JVM TI suspend function (eg. SuspendThreadList) or java.lang.Thread.suspend() will resume execution.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 93 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_suspend | Can suspend and resume threads

Parameters
Name | Type | Description
request_count | jint | The number of threads to resume.
request_list | const jthread* | The threads to resume. Agent passes in an array of request_count elements of jthread.
results | jvmtiError* | An agent supplied array of request_count elements. On return, filled with the error code for the resume of the corresponding thread. The error code will be JVMTI_ERROR_NONE if the thread was suspended by this call. Possible error codes are those specified for ResumeThread. Agent passes an array large enough to hold request_count elements of jvmtiError. The incoming values of the elements of the array are ignored. On return, the elements are set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_suspend. Use AddCapabilities.
JVMTI_ERROR_ILLEGAL_ARGUMENT | request_count is less than 0.
JVMTI_ERROR_NULL_POINTER | request_list is NULL.
JVMTI_ERROR_NULL_POINTER | results is NULL.

Stop Thread

jvmtiError
StopThread(jvmtiEnv* env,
            jthread thread,
            jobject exception)
Send the specified asynchronous exception to the specified thread (similar to java.lang.Thread.stop). Normally, this function is used to kill the specified thread with an instance of the exception ThreadDeath.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 7 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_signal_thread | Can send stop or interrupt to threads

Parameters
Name | Type | Description
thread | jthread | The thread to stop.
exception | jobject | The asynchronous exception object.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_signal_thread. Use AddCapabilities.
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_INVALID_OBJECT | exception is not an object.

Interrupt Thread

jvmtiError
InterruptThread(jvmtiEnv* env,
            jthread thread)
Interrupt the specified thread (similar to java.lang.Thread.interrupt).

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 8 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_signal_thread | Can send stop or interrupt to threads

Parameters
Name | Type | Description
thread | jthread | The thread to interrupt.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_signal_thread. Use AddCapabilities.
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).

Get Thread Info

typedef struct {
    char* name;
    jint priority;
    jboolean is_daemon;
    jthreadGroup thread_group;
    jobject context_class_loader;
} jvmtiThreadInfo;
jvmtiError
GetThreadInfo(jvmtiEnv* env,
            jthread thread,
            jvmtiThreadInfo* info_ptr)
Get thread information. The fields of the jvmtiThreadInfo structure are filled in with details of the specified thread.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 9 | 1.0

Capabilities
Required Functionality

jvmtiThreadInfo - Thread information structure
Field | Type | Description
name | char* | The thread name, encoded as a modified UTF-8 string.
priority | jint | The thread priority. See the thread priority constants: jvmtiThreadPriority.
is_daemon | jboolean | Is this a daemon thread?
thread_group | jthreadGroup | The thread group to which this thread belongs. NULL if the thread has died.
context_class_loader | jobject | The context class loader associated with this thread.

Parameters
Name | Type | Description
thread | jthread | The thread to query. If thread is NULL, the current thread is used.
info_ptr | jvmtiThreadInfo* | On return, filled with information describing the specified thread. For JDK 1.1 implementations that don't recognize context class loaders, the context_class_loader field will be NULL. Agent passes a pointer to a jvmtiThreadInfo. On return, the jvmtiThreadInfo has been set. The pointer returned in the field name of jvmtiThreadInfo is a newly allocated array. The array should be freed with Deallocate. The object returned in the field thread_group of jvmtiThreadInfo is a JNI local reference and must be managed. The object returned in the field context_class_loader of jvmtiThreadInfo is a JNI local reference and must be managed.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_NULL_POINTER | info_ptr is NULL.

Get Owned Monitor Info

jvmtiError
GetOwnedMonitorInfo(jvmtiEnv* env,
            jthread thread,
            jint* owned_monitor_count_ptr,
            jobject** owned_monitors_ptr)
Get information about the monitors owned by the specified thread.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 10 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_get_owned_monitor_info | Can get information about ownership of monitors - GetOwnedMonitorInfo

Parameters
Name | Type | Description
thread | jthread | The thread to query. If thread is NULL, the current thread is used.
owned_monitor_count_ptr | jint* | The number of monitors returned. Agent passes a pointer to a jint. On return, the jint has been set.
owned_monitors_ptr | jobject** | The array of owned monitors. Agent passes a pointer to a jobject*. On return, the jobject* points to a newly allocated array of size *owned_monitor_count_ptr. The array should be freed with Deallocate. The objects returned by owned_monitors_ptr are JNI local references and must be managed.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_get_owned_monitor_info. Use AddCapabilities.
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_NULL_POINTER | owned_monitor_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | owned_monitors_ptr is NULL.

Get Owned Monitor Stack Depth Info

typedef struct {
    jobject monitor;
    jint stack_depth;
} jvmtiMonitorStackDepthInfo;
jvmtiError
GetOwnedMonitorStackDepthInfo(jvmtiEnv* env,
            jthread thread,
            jint* monitor_info_count_ptr,
            jvmtiMonitorStackDepthInfo** monitor_info_ptr)
Get information about the monitors owned by the specified thread and the depth of the stack frame which locked them.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 153 | 1.1

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_get_owned_monitor_stack_depth_info | Can get information about owned monitors with stack depth - GetOwnedMonitorStackDepthInfo

jvmtiMonitorStackDepthInfo - Monitor stack depth information structure
Field | Type | Description
monitor | jobject | The owned monitor.
stack_depth | jint | The stack depth. Corresponds to the stack depth used in the Stack Frame functions. That is, zero is the current frame, one is the frame which called the current frame. And it is negative one if the implementation cannot determine the stack depth (e.g., for monitors acquired by JNI MonitorEnter).

Parameters
Name | Type | Description
thread | jthread | The thread to query. If thread is NULL, the current thread is used.
monitor_info_count_ptr | jint* | The number of monitors returned. Agent passes a pointer to a jint. On return, the jint has been set.
monitor_info_ptr | jvmtiMonitorStackDepthInfo ** | The array of owned monitor depth information. Agent passes a pointer to a jvmtiMonitorStackDepthInfo*. On return, the jvmtiMonitorStackDepthInfo* points to a newly allocated array of size *owned_monitor_depth_count_ptr. The array should be freed with Deallocate. The objects returned in the field monitor of jvmtiMonitorStackDepthInfo are JNI local references and must be managed.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_get_owned_monitor_stack_depth_info. Use AddCapabilities.
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_NULL_POINTER | monitor_info_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | monitor_info_ptr is NULL.

Get Current Contended Monitor

jvmtiError
GetCurrentContendedMonitor(jvmtiEnv* env,
            jthread thread,
            jobject* monitor_ptr)
Get the object, if any, whose monitor the specified thread is waiting to enter or waiting to regain through java.lang.Object.wait.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 11 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_get_current_contended_monitor | Can GetCurrentContendedMonitor

Parameters
Name | Type | Description
thread | jthread | The thread to query. If thread is NULL, the current thread is used.
monitor_ptr | jobject* | On return, filled with the current contended monitor, or NULL if there is none. Agent passes a pointer to a jobject. On return, the jobject has been set. The object returned by monitor_ptr is a JNI local reference and must be managed.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_get_current_contended_monitor. Use AddCapabilities.
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_NULL_POINTER | monitor_ptr is NULL.

Agent Start Function

typedef void (JNICALL *jvmtiStartFunction)
    (jvmtiEnv* jvmti_env,
     JNIEnv* jni_env,
     void* arg);
Agent supplied callback function. This function is the entry point for an agent thread started with RunAgentThread.

Parameters
Name | Type | Description
jvmti_env | jvmtiEnv * | The JVM TI environment.
jni_env | JNIEnv * | The JNI environment.
arg | void * | The arg parameter passed to RunAgentThread.

Run Agent Thread

jvmtiError
RunAgentThread(jvmtiEnv* env,
            jthread thread,
            jvmtiStartFunction proc,
            const void* arg,
            jint priority)
Starts the execution of an agent thread. with the specified native function. The parameter arg is forwarded on to the start function (specified with proc) as its single argument. This function allows the creation of agent threads for handling communication with another process or for handling events without the need to load a special subclass of java.lang.Thread or implementer of java.lang.Runnable. Instead, the created thread can run entirely in native code. However, the created thread does require a newly created instance of java.lang.Thread (referenced by the argument thread) to which it will be associated. The thread object can be created with JNI calls.

The following common thread priorities are provided for your convenience:
Thread Priority Constants
Constant | Value | Description
JVMTI_THREAD_MIN_PRIORITY | 1 | Minimum possible thread priority
JVMTI_THREAD_NORM_PRIORITY | 5 | Normal thread priority
JVMTI_THREAD_MAX_PRIORITY | 10 | Maximum possible thread priority

The new thread is started as a daemon thread with the specified priority. If enabled, a ThreadStart event will be sent.

Since the thread has been started, the thread will be live when this function returns, unless the thread has died immediately.

The thread group of the thread is ignored -- specifically, the thread is not added to the thread group and the thread is not seen on queries of the thread group at either the Java programming language or JVM TI levels.

The thread is not visible to Java programming language queries but is included in JVM TI queries (for example, GetAllThreads and GetAllStackTraces).

Upon execution of proc, the new thread will be attached to the VM--see the JNI documentation on Attaching to the VM.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 12 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
thread | jthread | The thread to run.
proc | jvmtiStartFunction | The start function.
arg | const void * | The argument to the start function. Agent passes in a pointer. If arg is NULL, NULL is passed to the start function.
priority | jint | The priority of the started thread. Any thread priority allowed by java.lang.Thread.setPriority can be used including those in jvmtiThreadPriority.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_PRIORITY | priority is less than JVMTI_THREAD_MIN_PRIORITY or greater than JVMTI_THREAD_MAX_PRIORITY
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_NULL_POINTER | proc is NULL.

Set Thread Local Storage

jvmtiError
SetThreadLocalStorage(jvmtiEnv* env,
            jthread thread,
            const void* data)
The VM stores a pointer value associated with each environment-thread pair. This pointer value is called thread-local storage. This value is NULL unless set with this function. Agents can allocate memory in which they store thread specific information. By setting thread-local storage it can then be accessed with GetThreadLocalStorage.

This function is called by the agent to set the value of the JVM TI thread-local storage. JVM TI supplies to the agent a pointer-size thread-local storage that can be used to record per-thread information.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 103 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
thread | jthread | Store to this thread. If thread is NULL, the current thread is used.
data | const void * | The value to be entered into the thread-local storage. Agent passes in a pointer. If data is NULL, value is set to NULL.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).

Get Thread Local Storage

jvmtiError
GetThreadLocalStorage(jvmtiEnv* env,
            jthread thread,
            void** data_ptr)
Called by the agent to get the value of the JVM TI thread-local storage.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 102 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
thread | jthread | Retrieve from this thread. If thread is NULL, the current thread is used.
data_ptr | void** | Pointer through which the value of the thread local storage is returned. If thread-local storage has not been set with SetThreadLocalStorage the returned pointer is NULL.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_NULL_POINTER | data_ptr is NULL.

Thread Group

Thread Group functions:
  • Get Top Thread Groups
  • Get Thread Group Info
  • Get Thread Group Children
Thread Group types:
  • jvmtiThreadGroupInfo - Thread group information structure

Get Top Thread Groups

jvmtiError
GetTopThreadGroups(jvmtiEnv* env,
            jint* group_count_ptr,
            jthreadGroup** groups_ptr)
Return all top-level (parentless) thread groups in the VM.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 13 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
group_count_ptr | jint* | On return, points to the number of top-level thread groups. Agent passes a pointer to a jint. On return, the jint has been set.
groups_ptr | jthreadGroup** | On return, refers to a pointer to the top-level thread group array. Agent passes a pointer to a jthreadGroup*. On return, the jthreadGroup* points to a newly allocated array of size *group_count_ptr. The array should be freed with Deallocate. The objects returned by groups_ptr are JNI local references and must be managed.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | group_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | groups_ptr is NULL.

Get Thread Group Info

typedef struct {
    jthreadGroup parent;
    char* name;
    jint max_priority;
    jboolean is_daemon;
} jvmtiThreadGroupInfo;
jvmtiError
GetThreadGroupInfo(jvmtiEnv* env,
            jthreadGroup group,
            jvmtiThreadGroupInfo* info_ptr)
Get information about the thread group. The fields of the jvmtiThreadGroupInfo structure are filled in with details of the specified thread group.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 14 | 1.0

Capabilities
Required Functionality

jvmtiThreadGroupInfo - Thread group information structure
Field | Type | Description
parent | jthreadGroup | The parent thread group.
name | char* | The thread group's name, encoded as a modified UTF-8 string.
max_priority | jint | The maximum priority for this thread group.
is_daemon | jboolean | Is this a daemon thread group?

Parameters
Name | Type | Description
group | jthreadGroup | The thread group to query.
info_ptr | jvmtiThreadGroupInfo* | On return, filled with information describing the specified thread group. Agent passes a pointer to a jvmtiThreadGroupInfo. On return, the jvmtiThreadGroupInfo has been set. The object returned in the field parent of jvmtiThreadGroupInfo is a JNI local reference and must be managed. The pointer returned in the field name of jvmtiThreadGroupInfo is a newly allocated array. The array should be freed with Deallocate.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_THREAD_GROUP | group is not a thread group object.
JVMTI_ERROR_NULL_POINTER | info_ptr is NULL.

Get Thread Group Children

jvmtiError
GetThreadGroupChildren(jvmtiEnv* env,
            jthreadGroup group,
            jint* thread_count_ptr,
            jthread** threads_ptr,
            jint* group_count_ptr,
            jthreadGroup** groups_ptr)
Get the live threads and active subgroups in this thread group.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 15 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
group | jthreadGroup | The group to query.
thread_count_ptr | jint* | On return, points to the number of live threads in this thread group. Agent passes a pointer to a jint. On return, the jint has been set.
threads_ptr | jthread** | On return, points to an array of the live threads in this thread group. Agent passes a pointer to a jthread*. On return, the jthread* points to a newly allocated array of size *thread_count_ptr. The array should be freed with Deallocate. The objects returned by threads_ptr are JNI local references and must be managed.
group_count_ptr | jint* | On return, points to the number of active child thread groups Agent passes a pointer to a jint. On return, the jint has been set.
groups_ptr | jthreadGroup** | On return, points to an array of the active child thread groups. Agent passes a pointer to a jthreadGroup*. On return, the jthreadGroup* points to a newly allocated array of size *group_count_ptr. The array should be freed with Deallocate. The objects returned by groups_ptr are JNI local references and must be managed.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_THREAD_GROUP | group is not a thread group object.
JVMTI_ERROR_NULL_POINTER | thread_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | threads_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | group_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | groups_ptr is NULL.

Stack Frame

Stack Frame functions:
  • Get Stack Trace
  • Get All Stack Traces
  • Get Thread List Stack Traces
  • Get Frame Count
  • Pop Frame
  • Get Frame Location
  • Notify Frame Pop
Stack Frame types:
  • jvmtiFrameInfo - Stack frame information structure
  • jvmtiStackInfo - Stack information structure
These functions provide information about the stack of a thread. Stack frames are referenced by depth. The frame at depth zero is the current frame.

Stack frames are as described in the Frames section of the Java Virtual Machine Specification. That is, they correspond to method invocations (including native methods) but do not correspond to platform native or VM internal frames.

A JVM TI implementation may use method invocations to launch a thread and the corresponding frames may be included in the stack as presented by these functions -- that is, there may be frames shown deeper than main() and run(). However this presentation must be consistent across all JVM TI functionality which uses stack frames or stack depth.

Stack frame information structure

Information about a stack frame is returned in this structure.

typedef struct {
    jmethodID method;
    jlocation location;
} jvmtiFrameInfo;
jvmtiFrameInfo - Stack frame information structure
Field | Type | Description
method | jmethodID | The method executing in this frame.
location | jlocation | The index of the instruction executing in this frame. -1 if the frame is executing a native method.

Stack information structure

Information about a set of stack frames is returned in this structure.

typedef struct {
    jthread thread;
    jint state;
    jvmtiFrameInfo* frame_buffer;
    jint frame_count;
} jvmtiStackInfo;
jvmtiStackInfo - Stack information structure
Field | Type | Description
thread | jthread | On return, the thread traced.
state | jint | On return, the thread state. See GetThreadState.
frame_buffer | jvmtiFrameInfo * | On return, this agent allocated buffer is filled with stack frame information.
frame_count | jint | On return, the number of records filled into frame_buffer. This will be min(max_frame_count, stackDepth).

Get Stack Trace

jvmtiError
GetStackTrace(jvmtiEnv* env,
            jthread thread,
            jint start_depth,
            jint max_frame_count,
            jvmtiFrameInfo* frame_buffer,
            jint* count_ptr)
Get information about the stack of a thread. If max_frame_count is less than the depth of the stack, the max_frame_count topmost frames are returned, otherwise the entire stack is returned. The topmost frames, those most recently invoked, are at the beginning of the returned buffer.

The following example causes up to five of the topmost frames to be returned and (if there are any frames) the currently executing method name to be printed.
jvmtiFrameInfo frames[5];
jint count;
jvmtiError err;

err = (*jvmti)->GetStackTrace(jvmti, aThread, 0, 5,
                               &frames, &count);
if (err == JVMTI_ERROR_NONE && count >= 1) {
   char *methodName;
   err = (*jvmti)->GetMethodName(jvmti, frames[0].method,
                       &methodName, NULL);
   if (err == JVMTI_ERROR_NONE) {
      printf("Executing method: %s", methodName);
   }
}

The thread need not be suspended to call this function.

The GetLineNumberTable function can be used to map locations to line numbers. Note that this mapping can be done lazily.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 104 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
thread | jthread | Fetch the stack trace of this thread. If thread is NULL, the current thread is used.
start_depth | jint | Begin retrieving frames at this depth. If non-negative, count from the current frame, the first frame retrieved is at depth start_depth. For example, if zero, start from the current frame; if one, start from the caller of the current frame; if two, start from the caller of the caller of the current frame; and so on. If negative, count from below the oldest frame, the first frame retrieved is at depth stackDepth + start_depth, where stackDepth is the count of frames on the stack. For example, if negative one, only the oldest frame is retrieved; if negative two, start from the frame called by the oldest frame.
max_frame_count | jint | The maximum number of jvmtiFrameInfo records to retrieve.
frame_buffer | jvmtiFrameInfo * | On return, this agent allocated buffer is filled with stack frame information. Agent passes an array large enough to hold max_frame_count elements of jvmtiFrameInfo. The incoming values of the elements of the array are ignored. On return, *count_ptr of the elements are set.
count_ptr | jint* | On return, points to the number of records filled in. For non-negative start_depth, this will be min(max_frame_count, stackDepth - start_depth). For negative start_depth, this will be min(max_frame_count, -start_depth). Agent passes a pointer to a jint. On return, the jint has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_ILLEGAL_ARGUMENT | start_depth is positive and greater than or equal to stackDepth. Or start_depth is negative and less than -stackDepth.
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_ILLEGAL_ARGUMENT | max_frame_count is less than 0.
JVMTI_ERROR_NULL_POINTER | frame_buffer is NULL.
JVMTI_ERROR_NULL_POINTER | count_ptr is NULL.

Get All Stack Traces

jvmtiError
GetAllStackTraces(jvmtiEnv* env,
            jint max_frame_count,
            jvmtiStackInfo** stack_info_ptr,
            jint* thread_count_ptr)
Get information about the stacks of all live threads (including agent threads). If max_frame_count is less than the depth of a stack, the max_frame_count topmost frames are returned for that thread, otherwise the entire stack is returned. The topmost frames, those most recently invoked, are at the beginning of the returned buffer.

All stacks are collected simultaneously, that is, no changes will occur to the thread state or stacks between the sampling of one thread and the next. The threads need not be suspended.
jvmtiStackInfo *stack_info;
jint thread_count;
int ti;
jvmtiError err;

err = (*jvmti)->GetAllStackTraces(jvmti, MAX_FRAMES, &stack_info, &thread_count);
if (err != JVMTI_ERROR_NONE) {
   ...
}
for (ti = 0; ti < thread_count; ++ti) {
   jvmtiStackInfo *infop = &stack_info[ti];
   jthread thread = infop->thread;
   jint state = infop->state;
   jvmtiFrameInfo *frames = infop->frame_buffer;
   int fi;

   myThreadAndStatePrinter(thread, state);
   for (fi = 0; fi < infop->frame_count; fi++) {
      myFramePrinter(frames[fi].method, frames[fi].location);
   }
}
/* this one Deallocate call frees all data allocated by GetAllStackTraces */
err = (*jvmti)->Deallocate(jvmti, stack_info);

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 100 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
max_frame_count | jint | The maximum number of jvmtiFrameInfo records to retrieve per thread.
stack_info_ptr | jvmtiStackInfo ** | On return, this buffer is filled with stack information for each thread. The number of jvmtiStackInfo records is determined by thread_count_ptr. Note that this buffer is allocated to include the jvmtiFrameInfo buffers pointed to by jvmtiStackInfo.frame_buffer. These buffers must not be separately deallocated. Agent passes a pointer to a jvmtiStackInfo*. On return, the jvmtiStackInfo* points to a newly allocated array. The array should be freed with Deallocate. The objects returned in the field thread of jvmtiStackInfo are JNI local references and must be managed.
thread_count_ptr | jint* | The number of threads traced. Agent passes a pointer to a jint. On return, the jint has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_ILLEGAL_ARGUMENT | max_frame_count is less than 0.
JVMTI_ERROR_NULL_POINTER | stack_info_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | thread_count_ptr is NULL.

Get Thread List Stack Traces

jvmtiError
GetThreadListStackTraces(jvmtiEnv* env,
            jint thread_count,
            const jthread* thread_list,
            jint max_frame_count,
            jvmtiStackInfo** stack_info_ptr)
Get information about the stacks of the supplied threads. If max_frame_count is less than the depth of a stack, the max_frame_count topmost frames are returned for that thread, otherwise the entire stack is returned. The topmost frames, those most recently invoked, are at the beginning of the returned buffer.

All stacks are collected simultaneously, that is, no changes will occur to the thread state or stacks between the sampling one thread and the next. The threads need not be suspended.

If a thread has not yet started or terminates before the stack information is collected, a zero length stack (jvmtiStackInfo.frame_count will be zero) will be returned and the thread jvmtiStackInfo.state can be checked.

See the example for the similar function GetAllStackTraces.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 101 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
thread_count | jint | The number of threads to trace.
thread_list | const jthread* | The list of threads to trace. Agent passes in an array of thread_count elements of jthread.
max_frame_count | jint | The maximum number of jvmtiFrameInfo records to retrieve per thread.
stack_info_ptr | jvmtiStackInfo ** | On return, this buffer is filled with stack information for each thread. The number of jvmtiStackInfo records is determined by thread_count. Note that this buffer is allocated to include the jvmtiFrameInfo buffers pointed to by jvmtiStackInfo.frame_buffer. These buffers must not be separately deallocated. Agent passes a pointer to a jvmtiStackInfo*. On return, the jvmtiStackInfo* points to a newly allocated array of size *thread_count. The array should be freed with Deallocate. The objects returned in the field thread of jvmtiStackInfo are JNI local references and must be managed.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_THREAD | An element in thread_list is not a thread object.
JVMTI_ERROR_ILLEGAL_ARGUMENT | thread_count is less than 0.
JVMTI_ERROR_NULL_POINTER | thread_list is NULL.
JVMTI_ERROR_ILLEGAL_ARGUMENT | max_frame_count is less than 0.
JVMTI_ERROR_NULL_POINTER | stack_info_ptr is NULL.

Get Frame Count

jvmtiError
GetFrameCount(jvmtiEnv* env,
            jthread thread,
            jint* count_ptr)
Get the number of frames currently in the specified thread's call stack.

If this function is called for a thread actively executing bytecodes (for example, not the current thread and not suspended), the information returned is transient.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 16 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
thread | jthread | The thread to query. If thread is NULL, the current thread is used.
count_ptr | jint* | On return, points to the number of frames in the call stack. Agent passes a pointer to a jint. On return, the jint has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_NULL_POINTER | count_ptr is NULL.

Pop Frame

jvmtiError
PopFrame(jvmtiEnv* env,
            jthread thread)
Pop the current frame of thread's stack. Popping a frame takes you to the previous frame. When the thread is resumed, the execution state of the thread is reset to the state immediately before the called method was invoked. That is (using the Java Virtual Machine Specification terminology):
  • the current frame is discarded as the previous frame becomes the current one
  • the operand stack is restored--the argument values are added back and if the invoke was not invokestatic, objectref is added back as well
  • the Java virtual machine PC is restored to the opcode of the invoke instruction
Note however, that any changes to the arguments, which occurred in the called method, remain; when execution continues, the first instruction to execute will be the invoke.

Between calling PopFrame and resuming the thread the state of the stack is undefined. To pop frames beyond the first, these three steps must be repeated:
  • suspend the thread via an event (step, breakpoint, ...)
  • call PopFrame
  • resume the thread

A lock acquired by calling the called method (if it is a synchronized method) and locks acquired by entering synchronized blocks within the called method are released. Note: this does not apply to native locks or java.util.concurrent.locks locks.

Finally blocks are not executed.

Changes to global state are not addressed and thus remain changed.

The specified thread must be suspended (which implies it cannot be the current thread).

Both the called method and calling method must be non-native Java programming language methods.

No JVM TI events are generated by this function.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 80 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_pop_frame | Can pop frames off the stack - PopFrame

Parameters
Name | Type | Description
thread | jthread | The thread whose current frame is to be popped.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_pop_frame. Use AddCapabilities.
JVMTI_ERROR_OPAQUE_FRAME | Called or calling method is a native method. The implementation is unable to pop this frame.
JVMTI_ERROR_THREAD_NOT_SUSPENDED | Thread was not suspended.
JVMTI_ERROR_NO_MORE_FRAMES | There are less than two stack frames on the call stack.
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).

Get Frame Location

jvmtiError
GetFrameLocation(jvmtiEnv* env,
            jthread thread,
            jint depth,
            jmethodID* method_ptr,
            jlocation* location_ptr)

For a Java programming language frame, return the location of the instruction currently executing.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 19 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
thread | jthread | The thread of the frame to query. If thread is NULL, the current thread is used.
depth | jint | The depth of the frame to query.
method_ptr | jmethodID* | On return, points to the method for the current location. Agent passes a pointer to a jmethodID. On return, the jmethodID has been set.
location_ptr | jlocation* | On return, points to the index of the currently executing instruction. Is set to -1 if the frame is executing a native method. Agent passes a pointer to a jlocation. On return, the jlocation has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_ILLEGAL_ARGUMENT | depth is less than zero.
JVMTI_ERROR_NO_MORE_FRAMES | There are no stack frames at the specified depth.
JVMTI_ERROR_NULL_POINTER | method_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | location_ptr is NULL.

Notify Frame Pop

jvmtiError
NotifyFramePop(jvmtiEnv* env,
            jthread thread,
            jint depth)
When the frame that is currently at depth is popped from the stack, generate a FramePop event. See the FramePop event for details. Only frames corresponding to non-native Java programming language methods can receive notification.

The specified thread must either be the current thread or the thread must be suspended.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 20 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_generate_frame_pop_events | Can set and thus get FramePop events

Parameters
Name | Type | Description
thread | jthread | The thread of the frame for which the frame pop event will be generated. If thread is NULL, the current thread is used.
depth | jint | The depth of the frame for which the frame pop event will be generated.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_generate_frame_pop_events. Use AddCapabilities.
JVMTI_ERROR_OPAQUE_FRAME | The frame at depth is executing a native method.
JVMTI_ERROR_THREAD_NOT_SUSPENDED | Thread was not suspended and was not the current thread.
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_ILLEGAL_ARGUMENT | depth is less than zero.
JVMTI_ERROR_NO_MORE_FRAMES | There are no stack frames at the specified depth.

Force Early Return

Force Early Return functions:
  • Force Early Return - Object
  • Force Early Return - Int
  • Force Early Return - Long
  • Force Early Return - Float
  • Force Early Return - Double
  • Force Early Return - Void
These functions allow an agent to force a method to return at any point during its execution. The method which will return early is referred to as the called method. The called method is the current method (as defined by the Frames section of the Java Virtual Machine Specification) for the specified thread at the time the function is called.

The specified thread must be suspended or must be the current thread. The return occurs when execution of Java programming language code is resumed on this thread. Between calling one of these functions and resumption of thread execution, the state of the stack is undefined.

No further instructions are executed in the called method. Specifically, finally blocks are not executed. Note: this can cause inconsistent states in the application.

A lock acquired by calling the called method (if it is a synchronized method) and locks acquired by entering synchronized blocks within the called method are released. Note: this does not apply to native locks or java.util.concurrent.locks locks.

Events, such as MethodExit, are generated as they would be in a normal return.

The called method must be a non-native Java programming language method. Forcing return on a thread with only one frame on the stack causes the thread to exit when resumed.

Force Early Return - Object

jvmtiError
ForceEarlyReturnObject(jvmtiEnv* env,
            jthread thread,
            jobject value)
This function can be used to return from a method whose result type is Object or a subclass of Object.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 81 | 1.1

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_force_early_return | Can return early from a method, as described in the Force Early Return category.

Parameters
Name | Type | Description
thread | jthread | The thread whose current frame is to return early. If thread is NULL, the current thread is used.
value | jobject | The return value for the called frame. An object or NULL.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_force_early_return. Use AddCapabilities.
JVMTI_ERROR_OPAQUE_FRAME | Attempted to return early from a frame corresponding to a native method. Or the implementation is unable to provide this functionality on this frame.
JVMTI_ERROR_TYPE_MISMATCH | The result type of the called method is not Object or a subclass of Object.
JVMTI_ERROR_TYPE_MISMATCH | The supplied value is not compatible with the result type of the called method.
JVMTI_ERROR_THREAD_NOT_SUSPENDED | Thread was not the current thread and was not suspended.
JVMTI_ERROR_NO_MORE_FRAMES | There are no more frames on the call stack.
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_INVALID_OBJECT | value is not an object.

Force Early Return - Int

jvmtiError
ForceEarlyReturnInt(jvmtiEnv* env,
            jthread thread,
            jint value)
This function can be used to return from a method whose result type is int, short, char, byte, or boolean.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 82 | 1.1

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_force_early_return | Can return early from a method, as described in the Force Early Return category.

Parameters
Name | Type | Description
thread | jthread | The thread whose current frame is to return early. If thread is NULL, the current thread is used.
value | jint | The return value for the called frame.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_force_early_return. Use AddCapabilities.
JVMTI_ERROR_OPAQUE_FRAME | Attempted to return early from a frame corresponding to a native method. Or the implementation is unable to provide this functionality on this frame.
JVMTI_ERROR_TYPE_MISMATCH | The result type of the called method is not int, short, char, byte, or boolean.
JVMTI_ERROR_THREAD_NOT_SUSPENDED | Thread was not the current thread and was not suspended.
JVMTI_ERROR_NO_MORE_FRAMES | There are no frames on the call stack.
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).

Force Early Return - Long

jvmtiError
ForceEarlyReturnLong(jvmtiEnv* env,
            jthread thread,
            jlong value)
This function can be used to return from a method whose result type is long.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 83 | 1.1

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_force_early_return | Can return early from a method, as described in the Force Early Return category.

Parameters
Name | Type | Description
thread | jthread | The thread whose current frame is to return early. If thread is NULL, the current thread is used.
value | jlong | The return value for the called frame.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_force_early_return. Use AddCapabilities.
JVMTI_ERROR_OPAQUE_FRAME | Attempted to return early from a frame corresponding to a native method. Or the implementation is unable to provide this functionality on this frame.
JVMTI_ERROR_TYPE_MISMATCH | The result type of the called method is not long.
JVMTI_ERROR_THREAD_NOT_SUSPENDED | Thread was not the current thread and was not suspended.
JVMTI_ERROR_NO_MORE_FRAMES | There are no frames on the call stack.
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).

Force Early Return - Float

jvmtiError
ForceEarlyReturnFloat(jvmtiEnv* env,
            jthread thread,
            jfloat value)
This function can be used to return from a method whose result type is float.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 84 | 1.1

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_force_early_return | Can return early from a method, as described in the Force Early Return category.

Parameters
Name | Type | Description
thread | jthread | The thread whose current frame is to return early. If thread is NULL, the current thread is used.
value | jfloat | The return value for the called frame.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_force_early_return. Use AddCapabilities.
JVMTI_ERROR_OPAQUE_FRAME | Attempted to return early from a frame corresponding to a native method. Or the implementation is unable to provide this functionality on this frame.
JVMTI_ERROR_TYPE_MISMATCH | The result type of the called method is not float.
JVMTI_ERROR_THREAD_NOT_SUSPENDED | Thread was not the current thread and was not suspended.
JVMTI_ERROR_NO_MORE_FRAMES | There are no frames on the call stack.
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).

Force Early Return - Double

jvmtiError
ForceEarlyReturnDouble(jvmtiEnv* env,
            jthread thread,
            jdouble value)
This function can be used to return from a method whose result type is double.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 85 | 1.1

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_force_early_return | Can return early from a method, as described in the Force Early Return category.

Parameters
Name | Type | Description
thread | jthread | The thread whose current frame is to return early. If thread is NULL, the current thread is used.
value | jdouble | The return value for the called frame.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_force_early_return. Use AddCapabilities.
JVMTI_ERROR_OPAQUE_FRAME | Attempted to return early from a frame corresponding to a native method. Or the implementation is unable to provide this functionality on this frame.
JVMTI_ERROR_TYPE_MISMATCH | The result type of the called method is not double.
JVMTI_ERROR_THREAD_NOT_SUSPENDED | Thread was not the current thread and was not suspended.
JVMTI_ERROR_NO_MORE_FRAMES | There are no frames on the call stack.
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).

Force Early Return - Void

jvmtiError
ForceEarlyReturnVoid(jvmtiEnv* env,
            jthread thread)
This function can be used to return from a method with no result type. That is, the called method must be declared void.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 86 | 1.1

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_force_early_return | Can return early from a method, as described in the Force Early Return category.

Parameters
Name | Type | Description
thread | jthread | The thread whose current frame is to return early. If thread is NULL, the current thread is used.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_force_early_return. Use AddCapabilities.
JVMTI_ERROR_OPAQUE_FRAME | Attempted to return early from a frame corresponding to a native method. Or the implementation is unable to provide this functionality on this frame.
JVMTI_ERROR_TYPE_MISMATCH | The called method has a result type.
JVMTI_ERROR_THREAD_NOT_SUSPENDED | Thread was not the current thread and was not suspended.
JVMTI_ERROR_NO_MORE_FRAMES | There are no frames on the call stack.
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).

Heap

Heap functions:
  • Follow References
  • Iterate Through Heap
  • Get Tag
  • Set Tag
  • Get Objects With Tags
  • Force Garbage Collection
Heap function types:
  • Heap Iteration Callback
  • Heap Reference Callback
  • Primitive Field Callback
  • Array Primitive Value Callback
  • String Primitive Value Callback
  • reserved for future use Callback
Heap types:
  • jvmtiHeapReferenceKind - Heap Reference Enumeration
  • jvmtiPrimitiveType - Primitive Type Enumeration
  • jvmtiHeapReferenceInfoField - Reference information structure for Field references
  • jvmtiHeapReferenceInfoArray - Reference information structure for Array references
  • jvmtiHeapReferenceInfoConstantPool - Reference information structure for Constant Pool references
  • jvmtiHeapReferenceInfoStackLocal - Reference information structure for Local Variable references
  • jvmtiHeapReferenceInfoJniLocal - Reference information structure for JNI local references
  • jvmtiHeapReferenceInfoReserved - Reference information structure for Other references
  • jvmtiHeapReferenceInfo - Reference information structure
  • jvmtiHeapCallbacks - Heap callback function structure
Heap flags and constants:
  • Heap Filter Flags
  • Heap Visit Control Flags
These functions are used to analyze the heap. Functionality includes the ability to view the objects in the heap and to tag these objects.

Object Tags

A tag is a value associated with an object. Tags are explicitly set by the agent using the SetTag function or by callback functions such as jvmtiHeapIterationCallback.

Tags are local to the environment; that is, the tags of one environment are not visible in another.

Tags are jlong values which can be used simply to mark an object or to store a pointer to more detailed information. Objects which have not been tagged have a tag of zero. Setting a tag to zero makes the object untagged.

Heap Callback Functions

Heap functions which iterate through the heap and recursively follow object references use agent supplied callback functions to deliver the information.

These heap callback functions must adhere to the following restrictions -- These callbacks must not use JNI functions. These callbacks must not use JVM TI functions except callback safe functions which specifically allow such use (see the raw monitor, memory management, and environment local storage functions).

An implementation may invoke a callback on an internal thread or the thread which called the iteration function. Heap callbacks are single threaded -- no more than one callback will be invoked at a time.

The Heap Filter Flags can be used to prevent reporting based on the tag status of an object or its class. If no flags are set (the jint is zero), objects will not be filtered out.
Heap Filter Flags
Constant | Value | Description
JVMTI_HEAP_FILTER_TAGGED | 0x4 | Filter out tagged objects. Objects which are tagged are not included.
JVMTI_HEAP_FILTER_UNTAGGED | 0x8 | Filter out untagged objects. Objects which are not tagged are not included.
JVMTI_HEAP_FILTER_CLASS_TAGGED | 0x10 | Filter out objects with tagged classes. Objects whose class is tagged are not included.
JVMTI_HEAP_FILTER_CLASS_UNTAGGED | 0x20 | Filter out objects with untagged classes. Objects whose class is not tagged are not included.

The Heap Visit Control Flags are returned by the heap callbacks and can be used to abort the iteration. For the Heap Reference Callback, it can also be used to prune the graph of traversed references (JVMTI_VISIT_OBJECTS is not set).
Heap Visit Control Flags
Constant | Value | Description
JVMTI_VISIT_OBJECTS | 0x100 | If we are visiting an object and if this callback was initiated by FollowReferences, traverse the references of this object. Otherwise ignored.
JVMTI_VISIT_ABORT | 0x8000 | Abort the iteration. Ignore all other bits.

The Heap Reference Enumeration is provided by the Heap Reference Callback and Primitive Field Callback to describe the kind of reference being reported.
Heap Reference Enumeration (jvmtiHeapReferenceKind)
Constant | Value | Description
JVMTI_HEAP_REFERENCE_CLASS | 1 | Reference from an object to its class.
JVMTI_HEAP_REFERENCE_FIELD | 2 | Reference from an object to the value of one of its instance fields.
JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT | 3 | Reference from an array to one of its elements.
JVMTI_HEAP_REFERENCE_CLASS_LOADER | 4 | Reference from a class to its class loader.
JVMTI_HEAP_REFERENCE_SIGNERS | 5 | Reference from a class to its signers array.
JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN | 6 | Reference from a class to its protection domain.
JVMTI_HEAP_REFERENCE_INTERFACE | 7 | Reference from a class to one of its interfaces. Note: interfaces are defined via a constant pool reference, so the referenced interfaces may also be reported with a JVMTI_HEAP_REFERENCE_CONSTANT_POOL reference kind.
JVMTI_HEAP_REFERENCE_STATIC_FIELD | 8 | Reference from a class to the value of one of its static fields.
JVMTI_HEAP_REFERENCE_CONSTANT_POOL | 9 | Reference from a class to a resolved entry in the constant pool.
JVMTI_HEAP_REFERENCE_SUPERCLASS | 10 | Reference from a class to its superclass. A callback is bot sent if the superclass is java.lang.Object. Note: loaded classes define superclasses via a constant pool reference, so the referenced superclass may also be reported with a JVMTI_HEAP_REFERENCE_CONSTANT_POOL reference kind.
JVMTI_HEAP_REFERENCE_JNI_GLOBAL | 21 | Heap root reference: JNI global reference.
JVMTI_HEAP_REFERENCE_SYSTEM_CLASS | 22 | Heap root reference: System class.
JVMTI_HEAP_REFERENCE_MONITOR | 23 | Heap root reference: monitor.
JVMTI_HEAP_REFERENCE_STACK_LOCAL | 24 | Heap root reference: local variable on the stack.
JVMTI_HEAP_REFERENCE_JNI_LOCAL | 25 | Heap root reference: JNI local reference.
JVMTI_HEAP_REFERENCE_THREAD | 26 | Heap root reference: Thread.
JVMTI_HEAP_REFERENCE_OTHER | 27 | Heap root reference: other heap root reference.

Definitions for the single character type descriptors of primitive types.
Primitive Type Enumeration (jvmtiPrimitiveType)
Constant | Value | Description
JVMTI_PRIMITIVE_TYPE_BOOLEAN | 90 | 'Z' - Java programming language boolean - JNI jboolean
JVMTI_PRIMITIVE_TYPE_BYTE | 66 | 'B' - Java programming language byte - JNI jbyte
JVMTI_PRIMITIVE_TYPE_CHAR | 67 | 'C' - Java programming language char - JNI jchar
JVMTI_PRIMITIVE_TYPE_SHORT | 83 | 'S' - Java programming language short - JNI jshort
JVMTI_PRIMITIVE_TYPE_INT | 73 | 'I' - Java programming language int - JNI jint
JVMTI_PRIMITIVE_TYPE_LONG | 74 | 'J' - Java programming language long - JNI jlong
JVMTI_PRIMITIVE_TYPE_FLOAT | 70 | 'F' - Java programming language float - JNI jfloat
JVMTI_PRIMITIVE_TYPE_DOUBLE | 68 | 'D' - Java programming language double - JNI jdouble

Reference information structure for Field references

Reference information returned for JVMTI_HEAP_REFERENCE_FIELD and JVMTI_HEAP_REFERENCE_STATIC_FIELD references.

typedef struct {
    jint index;
} jvmtiHeapReferenceInfoField;
jvmtiHeapReferenceInfoField - Reference information structure for Field references
Field Type Description
index jint For JVMTI_HEAP_REFERENCE_FIELD, the referrer object is not a class or an inteface. In this case, index is the index of the field in the class of the referrer object. This class is referred to below as C.

For JVMTI_HEAP_REFERENCE_STATIC_FIELD, the referrer object is a class (referred to below as C) or an interface (referred to below as I). In this case, index is the index of the field in that class or interface.

If the referrer object is not an interface, then the field indices are determined as follows:
  • make a list of all the fields in C and its superclasses, starting with all the fields in java.lang.Object and ending with all the fields in C.
  • Within this list, put the fields for a given class in the order returned by GetClassFields.
  • Assign the fields in this list indices n, n+1, ..., in order, where n is the count of the fields in all the interfaces implemented by C. Note that C implements all interfaces directly implemented by its superclasses; as well as all superinterfaces of these interfaces.
If the referrer object is an interface, then the field indices are determined as follows:
  • make a list of the fields directly declared in I.
  • Within this list, put the fields in the order returned by GetClassFields.
  • Assign the fields in this list indices n, n+1, ..., in order, where n is the count of the fields in all the superinterfaces of I.
All fields are included in this computation, regardless of field modifier (static, public, private, etc).

For example, given the following classes and interfaces:
interface I0 {
    int p = 0;
}

interface I1 extends I0 {
    int x = 1;
}

interface I2 extends I0 {
    int y = 2;
}

class C1 implements I1 {
    public static int a = 3;
    private int b = 4;
}

class C2 extends C1 implements I2 {
    static int q = 5;
    final int r = 6;
}
Assume that GetClassFields called on C1 returns the fields of C1 in the order: a, b; and that the fields of C2 are returned in the order: q, r. An instance of class C1 will have the following field indices:
a | 2 | The count of the fields in the interfaces implemented by C1 is two (n=2): p of I0 and x of I1.
b | 3 | the subsequent index.
The class C1 will have the same field indices.

An instance of class C2 will have the following field indices:
a | 3 | The count of the fields in the interfaces implemented by C2 is three (n=3): p of I0, x of I1 and y of I2 (an interface of C2). Note that the field p of I0 is only included once.
b | 4 | the subsequent index to "a".
q | 5 | the subsequent index to "b".
r | 6 | the subsequent index to "q".
The class C2 will have the same field indices. Note that a field may have a different index depending on the object that is viewing it -- for example field "a" above. Note also: not all field indices may be visible from the callbacks, but all indices are shown for illustrative purposes.

The interface I1 will have the following field indices:
x 1 The count of the fields in the superinterfaces of I1 is one (n=1): p of I0.

Reference information structure for Array references

Reference information returned for JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT references.

typedef struct {
    jint index;
} jvmtiHeapReferenceInfoArray;
jvmtiHeapReferenceInfoArray - Reference information structure for Array references
Field | Type | Description
index | jint | The array index.

Reference information structure for Constant Pool references

Reference information returned for JVMTI_HEAP_REFERENCE_CONSTANT_POOL references.

typedef struct {
    jint index;
} jvmtiHeapReferenceInfoConstantPool;
jvmtiHeapReferenceInfoConstantPool - Reference information structure for Constant Pool references
Field | Type | Description
index | jint | The index into the constant pool of the class. See the Constant Pool section of the Java Virtual Machine Specification description.

Reference information structure for Local Variable references

Reference information returned for JVMTI_HEAP_REFERENCE_STACK_LOCAL references.

typedef struct {
    jlong thread_tag;
    jlong thread_id;
    jint depth;
    jmethodID method;
    jlocation location;
    jint slot;
} jvmtiHeapReferenceInfoStackLocal;
jvmtiHeapReferenceInfoStackLocal - Reference information structure for Local Variable references
Field | Type | Description
thread_tag | jlong | The tag of the thread corresponding to this stack, zero if not tagged.
thread_id | jlong | The unique thread ID of the thread corresponding to this stack.
depth | jint | The depth of the frame.
method | jmethodID | The method executing in this frame.
location | jlocation | The currently executing location in this frame.
slot | jint | The slot number of the local variable.

Reference information structure for JNI local references

Reference information returned for JVMTI_HEAP_REFERENCE_JNI_LOCAL references.

typedef struct {
    jlong thread_tag;
    jlong thread_id;
    jint depth;
    jmethodID method;
} jvmtiHeapReferenceInfoJniLocal;
jvmtiHeapReferenceInfoJniLocal - Reference information structure for JNI local references
Field | Type | Description
thread_tag | jlong | The tag of the thread corresponding to this stack, zero if not tagged.
thread_id | jlong | The unique thread ID of the thread corresponding to this stack.
depth | jint | The depth of the frame.
method | jmethodID | The method executing in this frame.

Reference information structure for Other references

Reference information returned for other references.

typedef struct {
    jlong reserved1;
    jlong reserved2;
    jlong reserved3;
    jlong reserved4;
    jlong reserved5;
    jlong reserved6;
    jlong reserved7;
    jlong reserved8;
} jvmtiHeapReferenceInfoReserved;
jvmtiHeapReferenceInfoReserved - Reference information structure for Other references
Field | Type | Description
reserved1 | jlong | reserved for future use.
reserved2 | jlong | reserved for future use.
reserved3 | jlong | reserved for future use.
reserved4 | jlong | reserved for future use.
reserved5 | jlong | reserved for future use.
reserved6 | jlong | reserved for future use.
reserved7 | jlong | reserved for future use.
reserved8 | jlong | reserved for future use.

Reference information structure

The information returned about referrers. Represented as a union of the various kinds of reference information.

typedef union {
    jvmtiHeapReferenceInfoField field;
    jvmtiHeapReferenceInfoArray array;
    jvmtiHeapReferenceInfoConstantPool constant_pool;
    jvmtiHeapReferenceInfoStackLocal stack_local;
    jvmtiHeapReferenceInfoJniLocal jni_local;
    jvmtiHeapReferenceInfoReserved other;
} jvmtiHeapReferenceInfo;
jvmtiHeapReferenceInfo - Reference information structure
Field | Type | Description
field | jvmtiHeapReferenceInfoField | The referrer information for JVMTI_HEAP_REFERENCE_FIELD and JVMTI_HEAP_REFERENCE_STATIC_FIELD references.
array | jvmtiHeapReferenceInfoArray | The referrer information for For JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT references.
constant_pool | jvmtiHeapReferenceInfoConstantPool | The referrer information for For JVMTI_HEAP_REFERENCE_CONSTANT_POOL references.
stack_local | jvmtiHeapReferenceInfoStackLocal | The referrer information for For JVMTI_HEAP_REFERENCE_STACK_LOCAL references.
jni_local | jvmtiHeapReferenceInfoJniLocal | The referrer information for For JVMTI_HEAP_REFERENCE_JNI_LOCAL references.
other | jvmtiHeapReferenceInfoReserved | reserved for future use.

Heap callback function structure

typedef struct {
    jvmtiHeapIterationCallback heap_iteration_callback;
    jvmtiHeapReferenceCallback heap_reference_callback;
    jvmtiPrimitiveFieldCallback primitive_field_callback;
    jvmtiArrayPrimitiveValueCallback array_primitive_value_callback;
    jvmtiStringPrimitiveValueCallback string_primitive_value_callback;
    jvmtiReservedCallback reserved5;
    jvmtiReservedCallback reserved6;
    jvmtiReservedCallback reserved7;
    jvmtiReservedCallback reserved8;
    jvmtiReservedCallback reserved9;
    jvmtiReservedCallback reserved10;
    jvmtiReservedCallback reserved11;
    jvmtiReservedCallback reserved12;
    jvmtiReservedCallback reserved13;
    jvmtiReservedCallback reserved14;
    jvmtiReservedCallback reserved15;
} jvmtiHeapCallbacks;
jvmtiHeapCallbacks - Heap callback function structure
Field | Type | Description
heap_iteration_callback | jvmtiHeapIterationCallback | The callback to be called to describe an object in the heap. Used by the IterateThroughHeap function, ignored by the FollowReferences function.
heap_reference_callback | jvmtiHeapReferenceCallback | The callback to be called to describe an object reference. Used by the FollowReferences function, ignored by the IterateThroughHeap function.
primitive_field_callback | jvmtiPrimitiveFieldCallback | The callback to be called to describe a primitive field.
array_primitive_value_callback | jvmtiArrayPrimitiveValueCallback | The callback to be called to describe an array of primitive values.
string_primitive_value_callback | jvmtiStringPrimitiveValueCallback | The callback to be called to describe a String value.
reserved5 | jvmtiReservedCallback | Reserved for future use..
reserved6 | jvmtiReservedCallback | Reserved for future use..
reserved7 | jvmtiReservedCallback | Reserved for future use..
reserved8 | jvmtiReservedCallback | Reserved for future use..
reserved9 | jvmtiReservedCallback | Reserved for future use..
reserved10 | jvmtiReservedCallback | Reserved for future use..
reserved11 | jvmtiReservedCallback | Reserved for future use..
reserved12 | jvmtiReservedCallback | Reserved for future use..
reserved13 | jvmtiReservedCallback | Reserved for future use..
reserved14 | jvmtiReservedCallback | Reserved for future use..
reserved15 | jvmtiReservedCallback | Reserved for future use..

Rationale: The heap dumping functionality (below) uses a callback for each object. While it would seem that a buffered approach would provide better throughput, tests do not show this to be the case--possibly due to locality of memory reference or array access overhead.

Heap Iteration Callback

typedef jint (JNICALL *jvmtiHeapIterationCallback)
    (jlong class_tag,
     jlong size,
     jlong* tag_ptr,
     jint length,
     void* user_data);
Agent supplied callback function. Describes (but does not pass in) an object in the heap.

This function should return a bit vector of the desired visit control flags. This will determine if the entire iteration should be aborted (the JVMTI_VISIT_OBJECTS flag is ignored).

See the heap callback function restrictions.

Parameters
Name | Type | Description
class_tag | jlong | The tag of the class of object (zero if the class is not tagged). If the object represents a runtime class, the class_tag is the tag associated with java.lang.Class (zero if java.lang.Class is not tagged).
size | jlong | Size of the object (in bytes). See GetObjectSize.
tag_ptr | jlong* | The object tag value, or zero if the object is not tagged. To set the tag value to be associated with the object the agent sets the jlong pointed to by the parameter.
length | jint | If this object is an array, the length of the array. Otherwise negative one (-1).
user_data | void* | The user supplied data that was passed into the iteration function.

Heap Reference Callback

typedef jint (JNICALL *jvmtiHeapReferenceCallback)
    (jvmtiHeapReferenceKind reference_kind,
     const jvmtiHeapReferenceInfo* reference_info,
     jlong class_tag,
     jlong referrer_class_tag,
     jlong size,
     jlong* tag_ptr,
     jlong* referrer_tag_ptr,
     jint length,
     void* user_data);
Agent supplied callback function. Describes a reference from an object or the VM (the referrer) to another object (the referree) or a heap root to a referree.

This function should return a bit vector of the desired visit control flags. This will determine if the objects referenced by the referree should be visited or if the entire iteration should be aborted.

See the heap callback function restrictions.

Parameters
Name | Type | Description
reference_kind | jvmtiHeapReferenceKind | The kind of reference.
reference_info | const jvmtiHeapReferenceInfo * | Details about the reference. Set when the reference_kind is JVMTI_HEAP_REFERENCE_FIELD, JVMTI_HEAP_REFERENCE_STATIC_FIELD, JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT, JVMTI_HEAP_REFERENCE_CONSTANT_POOL, JVMTI_HEAP_REFERENCE_STACK_LOCAL, or JVMTI_HEAP_REFERENCE_JNI_LOCAL. Otherwise NULL.
class_tag | jlong | The tag of the class of referree object (zero if the class is not tagged). If the referree object represents a runtime class, the class_tag is the tag associated with java.lang.Class (zero if java.lang.Class is not tagged).
referrer_class_tag | jlong | The tag of the class of the referrer object (zero if the class is not tagged or the referree is a heap root). If the referrer object represents a runtime class, the referrer_class_tag is the tag associated with the java.lang.Class (zero if java.lang.Class is not tagged).
size | jlong | Size of the referree object (in bytes). See GetObjectSize.
tag_ptr | jlong* | Points to the referree object tag value, or zero if the object is not tagged. To set the tag value to be associated with the object the agent sets the jlong pointed to by the parameter.
referrer_tag_ptr | jlong* | Points to the tag of the referrer object, or points to the zero if the referrer object is not tagged. NULL if the referrer in not an object (that is, this callback is reporting a heap root). To set the tag value to be associated with the referrer object the agent sets the jlong pointed to by the parameter. If this callback is reporting a reference from an object to itself, referrer_tag_ptr == tag_ptr.
length | jint | If this object is an array, the length of the array. Otherwise negative one (-1).
user_data | void* | The user supplied data that was passed into the iteration function.

Primitive Field Callback

typedef jint (JNICALL *jvmtiPrimitiveFieldCallback)
    (jvmtiHeapReferenceKind kind,
     const jvmtiHeapReferenceInfo* info,
     jlong object_class_tag,
     jlong* object_tag_ptr,
     jvalue value,
     jvmtiPrimitiveType value_type,
     void* user_data);
Agent supplied callback function which describes a primitive field of an object (the object). A primitive field is a field whose type is a primitive type. This callback will describe a static field if the object is a class, and otherwise will describe an instance field.

This function should return a bit vector of the desired visit control flags. This will determine if the entire iteration should be aborted (the JVMTI_VISIT_OBJECTS flag is ignored).

See the heap callback function restrictions.

Parameters
Name | Type | Description
kind | jvmtiHeapReferenceKind | The kind of field -- instance or static (JVMTI_HEAP_REFERENCE_FIELD or JVMTI_HEAP_REFERENCE_STATIC_FIELD).
info | const jvmtiHeapReferenceInfo * | Which field (the field index).
object_class_tag | jlong | The tag of the class of the object (zero if the class is not tagged). If the object represents a runtime class, the object_class_tag is the tag associated with java.lang.Class (zero if java.lang.Class is not tagged).
object_tag_ptr | jlong* | Points to the tag of the object, or zero if the object is not tagged. To set the tag value to be associated with the object the agent sets the jlong pointed to by the parameter.
value | jvalue | The value of the field.
value_type | jvmtiPrimitiveType | The type of the field.
user_data | void* | The user supplied data that was passed into the iteration function.

Array Primitive Value Callback

typedef jint (JNICALL *jvmtiArrayPrimitiveValueCallback)
    (jlong class_tag,
     jlong size,
     jlong* tag_ptr,
     jint element_count,
     jvmtiPrimitiveType element_type,
     const void* elements,
     void* user_data);
Agent supplied callback function. Describes the values in an array of a primitive type.

This function should return a bit vector of the desired visit control flags. This will determine if the entire iteration should be aborted (the JVMTI_VISIT_OBJECTS flag is ignored).

See the heap callback function restrictions.

Parameters
Name | Type | Description
class_tag | jlong | The tag of the class of the array object (zero if the class is not tagged).
size | jlong | Size of the array (in bytes). See GetObjectSize.
tag_ptr | jlong* | Points to the tag of the array object, or zero if the object is not tagged. To set the tag value to be associated with the object the agent sets the jlong pointed to by the parameter.
element_count | jint | The length of the primitive array.
element_type | jvmtiPrimitiveType | The type of the elements of the array.
elements | const void* | The elements of the array in a packed array of element_count items of element_type size each.
user_data | void* | The user supplied data that was passed into the iteration function.

String Primitive Value Callback

typedef jint (JNICALL *jvmtiStringPrimitiveValueCallback)
    (jlong class_tag,
     jlong size,
     jlong* tag_ptr,
     const jchar* value,
     jint value_length,
     void* user_data);
Agent supplied callback function. Describes the value of a java.lang.String.

This function should return a bit vector of the desired visit control flags. This will determine if the entire iteration should be aborted (the JVMTI_VISIT_OBJECTS flag is ignored).

See the heap callback function restrictions.

Parameters
Name | Type | Description
class_tag | jlong | The tag of the class of the String class (zero if the class is not tagged).
size | jlong | Size of the string (in bytes). See GetObjectSize.
tag_ptr | jlong* | Points to the tag of the String object, or zero if the object is not tagged. To set the tag value to be associated with the object the agent sets the jlong pointed to by the parameter.
value | const jchar* | The value of the String, encoded as a Unicode string.
value_length | jint | The length of the string. The length is equal to the number of 16-bit Unicode characters in the string.
user_data | void* | The user supplied data that was passed into the iteration function.

reserved for future use Callback

typedef jint (JNICALL *jvmtiReservedCallback)
    ();
Placeholder -- reserved for future use.

Parameters
Name Type Description

Follow References

jvmtiError
FollowReferences(jvmtiEnv* env,
            jint heap_filter,
            jclass klass,
            jobject initial_object,
            const jvmtiHeapCallbacks* callbacks,
            const void* user_data)
This function initiates a traversal over the objects that are directly and indirectly reachable from the specified object or, if initial_object is not specified, all objects reachable from the heap roots. The heap root are the set of system classes, JNI globals, references from thread stacks, and other objects used as roots for the purposes of garbage collection.

This function operates by traversing the reference graph. Let A, B, ... represent objects. When a reference from A to B is traversed, when a reference from a heap root to B is traversed, or when B is specified as the initial_object, then B is said to be visited. A reference from A to B is not traversed until A is visited. References are reported in the same order that the references are traversed. Object references are reported by invoking the agent supplied callback function jvmtiHeapReferenceCallback. In a reference from A to B, A is known as the referrer and B as the referree. The callback is invoked exactly once for each reference from a referrer; this is true even if there are reference cycles or multiple paths to the referrer. There may be more than one reference between a referrer and a referree, each reference is reported. These references may be distinguished by examining the reference_kind and reference_info parameters of the jvmtiHeapReferenceCallback callback.

This function reports a Java programming language view of object references, not a virtual machine implementation view. The following object references are reported when they are non-null:
  • Instance objects report references to each non-primitive instance fields (including inherited fields).
  • Instance objects report a reference to the object type (class).
  • Classes report a reference to the superclass and directly implemented/extended interfaces.
  • Classes report a reference to the class loader, protection domain, signers, and resolved entries in the constant pool.
  • Classes report a reference to each directly declared non-primitive static field.
  • Arrays report a reference to the array type (class) and each array element.
  • Primitive arrays report a reference to the array type.

This function can also be used to examine primitive (non-object) values. The primitive value of an array or String is reported after the object has been visited; it is reported by invoking the agent supplied callback function jvmtiArrayPrimitiveValueCallback or jvmtiStringPrimitiveValueCallback. A primitive field is reported after the object with that field is visited; it is reported by invoking the agent supplied callback function jvmtiPrimitiveFieldCallback.

Whether a callback is provided or is NULL only determines whether the callback will be invoked, it does not influence which objects are visited nor does it influence whether other callbacks will be invoked. However, the visit control flags returned by jvmtiHeapReferenceCallback do determine if the objects referenced by the current object as visited. The heap filter flags and klass provided as parameters to this function do not control which objects are visited but they do control which objects and primitive values are reported by the callbacks. For example, if the only callback that was set is array_primitive_value_callback and klass is set to the array of bytes class, then only arrays of byte will be reported. The table below summarizes this:

 | Controls objects visited | Controls objects reported | Controls primitives reported
the Heap Visit Control Flags returned by jvmtiHeapReferenceCallback | Yes | Yes, since visits are controlled | Yes, since visits are controlled
object_reference_callback in callbacks set | No | Yes | No
heap_filter | No | Yes | Yes
klass | No | Yes | Yes

During the execution of this function the state of the heap does not change: no objects are allocated, no objects are garbage collected, and the state of objects (including held values) does not change. As a result, threads executing Java programming language code, threads attempting to resume the execution of Java programming language code, and threads attempting to execute JNI functions are typically stalled.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 115 | 1.1

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_tag_objects | Can set and get tags, as described in the Heap category.

Parameters
Name | Type | Description
heap_filter | jint | This bit vector of heap filter flags. restricts the objects for which the callback function is called. This applies to both the object and primitive callbacks.
klass | jclass | Callbacks are only reported when the object is an instance of this class. Objects which are instances of a subclass of klass are not reported. If klass is an interface, no objects are reported. This applies to both the object and primitive callbacks. If klass is NULL, callbacks are not limited to instances of a particular class.
initial_object | jobject | The object to follow If initial_object is NULL, references are followed from the heap roots.
callbacks | const jvmtiHeapCallbacks * | Structure defining the set of callback functions. Agent passes in a pointer to jvmtiHeapCallbacks.
user_data | const void * | User supplied data to be passed to the callback. Agent passes in a pointer. If user_data is NULL, NULL is passed as the user supplied data.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_tag_objects. Use AddCapabilities.
JVMTI_ERROR_INVALID_CLASS | klass is not a valid class.
JVMTI_ERROR_INVALID_OBJECT | initial_object is not a valid object.
JVMTI_ERROR_NULL_POINTER | callbacks is NULL.

Iterate Through Heap

jvmtiError
IterateThroughHeap(jvmtiEnv* env,
            jint heap_filter,
            jclass klass,
            const jvmtiHeapCallbacks* callbacks,
            const void* user_data)
Initiate an iteration over all objects in the heap. This includes both reachable and unreachable objects. Objects are visited in no particular order.

Heap objects are reported by invoking the agent supplied callback function jvmtiHeapIterationCallback. References between objects are not reported. If only reachable objects are desired, or if object reference information is needed, use FollowReferences.

This function can also be used to examine primitive (non-object) values. The primitive value of an array or String is reported after the object has been visited; it is reported by invoking the agent supplied callback function jvmtiArrayPrimitiveValueCallback or jvmtiStringPrimitiveValueCallback. A primitive field is reported after the object with that field is visited; it is reported by invoking the agent supplied callback function jvmtiPrimitiveFieldCallback.

Unless the iteration is aborted by the Heap Visit Control Flags returned by a callback, all objects in the heap are visited. Whether a callback is provided or is NULL only determines whether the callback will be invoked, it does not influence which objects are visited nor does it influence whether other callbacks will be invoked. The heap filter flags and klass provided as parameters to this function do not control which objects are visited but they do control which objects and primitive values are reported by the callbacks. For example, if the only callback that was set is array_primitive_value_callback and klass is set to the array of bytes class, then only arrays of byte will be reported. The table below summarizes this (contrast this with FollowReferences):

 | Controls objects visited | Controls objects reported | Controls primitives reported
the Heap Visit Control Flags returned by jvmtiHeapIterationCallback | No (unless they abort the iteration) | No (unless they abort the iteration) | No (unless they abort the iteration)
object_callback in callbacks set | No | Yes | No
heap_filter | No | Yes | Yes
klass | No | Yes | Yes

During the execution of this function the state of the heap does not change: no objects are allocated, no objects are garbage collected, and the state of objects (including held values) does not change. As a result, threads executing Java programming language code, threads attempting to resume the execution of Java programming language code, and threads attempting to execute JNI functions are typically stalled.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 116 | 1.1

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_tag_objects | Can set and get tags, as described in the Heap category.

Parameters
Name | Type | Description
heap_filter | jint | This bit vector of heap filter flags. restricts the objects for which the callback function is called. This applies to both the object and primitive callbacks.
klass | jclass | Callbacks are only reported when the object is an instance of this class. Objects which are instances of a subclass of klass are not reported. If klass is an interface, no objects are reported. This applies to both the object and primitive callbacks. If klass is NULL, callbacks are not limited to instances of a particular class.
callbacks | const jvmtiHeapCallbacks * | Structure defining the set callback functions. Agent passes in a pointer to jvmtiHeapCallbacks.
user_data | const void * | User supplied data to be passed to the callback. Agent passes in a pointer. If user_data is NULL, NULL is passed as the user supplied data.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_tag_objects. Use AddCapabilities.
JVMTI_ERROR_INVALID_CLASS | klass is not a valid class.
JVMTI_ERROR_NULL_POINTER | callbacks is NULL.

Get Tag

jvmtiError
GetTag(jvmtiEnv* env,
            jobject object,
            jlong* tag_ptr)
Retrieve the tag associated with an object. The tag is a long value typically used to store a unique identifier or pointer to object information. The tag is set with SetTag. Objects for which no tags have been set return a tag value of zero.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 106 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_tag_objects | Can set and get tags, as described in the Heap category.

Parameters
Name | Type | Description
object | jobject | The object whose tag is to be retrieved.
tag_ptr | jlong* | On return, the referenced long is set to the value of the tag. Agent passes a pointer to a jlong. On return, the jlong has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_tag_objects. Use AddCapabilities.
JVMTI_ERROR_INVALID_OBJECT | object is not an object.
JVMTI_ERROR_NULL_POINTER | tag_ptr is NULL.

Set Tag

jvmtiError
SetTag(jvmtiEnv* env,
            jobject object,
            jlong tag)
Set the tag associated with an object. The tag is a long value typically used to store a unique identifier or pointer to object information. The tag is visible with GetTag.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 107 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_tag_objects | Can set and get tags, as described in the Heap category.

Parameters
Name | Type | Description
object | jobject | The object whose tag is to be set.
tag | jlong | The new value of the tag.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_tag_objects. Use AddCapabilities.
JVMTI_ERROR_INVALID_OBJECT | object is not an object.

Get Objects With Tags

jvmtiError
GetObjectsWithTags(jvmtiEnv* env,
            jint tag_count,
            const jlong* tags,
            jint* count_ptr,
            jobject** object_result_ptr,
            jlong** tag_result_ptr)
Return objects in the heap with the specified tags. The format is parallel arrays of objects and tags.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 114 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_tag_objects | Can set and get tags, as described in the Heap category.

Parameters
Name | Type | Description
tag_count | jint | Number of tags to scan for.
tags | const jlong * | Scan for objects with these tags. Zero is not permitted in this array. Agent passes in an array of tag_count elements of jlong.
count_ptr | jint * | Return the number of objects with any of the tags in tags. Agent passes a pointer to a jint. On return, the jint has been set.
object_result_ptr | jobject ** | Returns the array of objects with any of the tags in tags. Agent passes a pointer to a jobject*. On return, the jobject* points to a newly allocated array of size *count_ptr. The array should be freed with Deallocate. If object_result_ptr is NULL, this information is not returned. The objects returned by object_result_ptr are JNI local references and must be managed.
tag_result_ptr | jlong ** | For each object in object_result_ptr, return the tag at the corresponding index. Agent passes a pointer to a jlong*. On return, the jlong* points to a newly allocated array of size *count_ptr. The array should be freed with Deallocate. If tag_result_ptr is NULL, this information is not returned.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_tag_objects. Use AddCapabilities.
JVMTI_ERROR_ILLEGAL_ARGUMENT | Zero is present in tags.
JVMTI_ERROR_ILLEGAL_ARGUMENT | tag_count is less than 0.
JVMTI_ERROR_NULL_POINTER | tags is NULL.
JVMTI_ERROR_NULL_POINTER | count_ptr is NULL.

Force Garbage Collection

jvmtiError
ForceGarbageCollection(jvmtiEnv* env)
Force the VM to perform a garbage collection. The garbage collection is as complete as possible. This function does not cause finalizers to be run. This function does not return until the garbage collection is finished.

Although garbage collection is as complete as possible there is no guarantee that all ObjectFree events will have been sent by the time that this function returns. In particular, an object may be prevented from being freed because it is awaiting finalization.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 108 | 1.0

Capabilities
Required Functionality

Parameters
Name Type Description

Errors
This function returns a universal error

Heap (1.0)

Heap (1.0) functions:
  • Iterate Over Objects Reachable From Object
  • Iterate Over Reachable Objects
  • Iterate Over Heap
  • Iterate Over Instances Of Class
Heap (1.0) function types:
  • Heap Object Callback
  • Heap Root Object Callback
  • Stack Reference Object Callback
  • Object Reference Callback
Heap (1.0) types:
  • jvmtiHeapObjectFilter - Heap Object Filter Enumeration
  • jvmtiHeapRootKind - Heap Root Kind Enumeration
  • jvmtiObjectReferenceKind - Object Reference Enumeration
  • jvmtiIterationControl - Iteration Control Enumeration
These functions and data types were introduced in the original JVM TI version 1.0 and have been superseded by more powerful and flexible versions which:
  • Allow access to primitive values (the value of Strings, arrays, and primitive fields)
  • Allow the tag of the referrer to be set, thus enabling more efficient localized reference graph building
  • Provide more extensive filtering abilities
  • Are extensible, allowing their abilities to grow in future versions of JVM TI

Please use the current Heap functions.

Heap Object Filter Enumeration (jvmtiHeapObjectFilter)
Constant | Value | Description
JVMTI_HEAP_OBJECT_TAGGED | 1 | Tagged objects only.
JVMTI_HEAP_OBJECT_UNTAGGED | 2 | Untagged objects only.
JVMTI_HEAP_OBJECT_EITHER | 3 | Either tagged or untagged objects.
Heap Root Kind Enumeration (jvmtiHeapRootKind)
Constant | Value | Description
JVMTI_HEAP_ROOT_JNI_GLOBAL | 1 | JNI global reference.
JVMTI_HEAP_ROOT_SYSTEM_CLASS | 2 | System class.
JVMTI_HEAP_ROOT_MONITOR | 3 | Monitor.
JVMTI_HEAP_ROOT_STACK_LOCAL | 4 | Stack local.
JVMTI_HEAP_ROOT_JNI_LOCAL | 5 | JNI local reference.
JVMTI_HEAP_ROOT_THREAD | 6 | Thread.
JVMTI_HEAP_ROOT_OTHER | 7 | Other.
Object Reference Enumeration (jvmtiObjectReferenceKind)
Constant | Value | Description
JVMTI_REFERENCE_CLASS | 1 | Reference from an object to its class.
JVMTI_REFERENCE_FIELD | 2 | Reference from an object to the value of one of its instance fields. For references of this kind the referrer_index parameter to the jvmtiObjectReferenceCallback is the index of the the instance field. The index is based on the order of all the object's fields. This includes all fields of the directly declared static and instance fields in the class, and includes all fields (both public and private) fields declared in superclasses and superinterfaces. The index is thus calculated by summing the index of the field in the directly declared class (see GetClassFields), with the total number of fields (both public and private) declared in all superclasses and superinterfaces. The index starts at zero.
JVMTI_REFERENCE_ARRAY_ELEMENT | 3 | Reference from an array to one of its elements. For references of this kind the referrer_index parameter to the jvmtiObjectReferenceCallback is the array index.
JVMTI_REFERENCE_CLASS_LOADER | 4 | Reference from a class to its class loader.
JVMTI_REFERENCE_SIGNERS | 5 | Reference from a class to its signers array.
JVMTI_REFERENCE_PROTECTION_DOMAIN | 6 | Reference from a class to its protection domain.
JVMTI_REFERENCE_INTERFACE | 7 | Reference from a class to one of its interfaces.
JVMTI_REFERENCE_STATIC_FIELD 8 Reference from a class to the value of one of its static fields. For references of this kind the referrer_index parameter to the jvmtiObjectReferenceCallback is the index of the the static field. The index is based on the order of all the object's fields. This includes all fields of the directly declared static and instance fields in the class, and includes all fields (both public and private) fields declared in superclasses and superinterfaces. The index is thus calculated by summing the index of the field in the directly declared class (see GetClassFields), with the total number of fields (both public and private) declared in all superclasses and superinterfaces. The index starts at zero. Note: this definition differs from that in the JVM TI 1.0 Specification.

Rationale: No known implementations used the 1.0 definition.
JVMTI_REFERENCE_CONSTANT_POOL | 9 | Reference from a class to a resolved entry in the constant pool. For references of this kind the referrer_index parameter to the jvmtiObjectReferenceCallback is the index into constant pool table of the class, starting at 1. See the Constant Pool section of the Java Virtual Machine Specification
Iteration Control Enumeration (jvmtiIterationControl)
Constant | Value | Description
JVMTI_ITERATION_CONTINUE | 1 | Continue the iteration. If this is a reference iteration, follow the references of this object.
JVMTI_ITERATION_IGNORE | 2 | Continue the iteration. If this is a reference iteration, ignore the references of this object.
JVMTI_ITERATION_ABORT | 0 | Abort the iteration.

Heap Object Callback

typedef jvmtiIterationControl (JNICALL *jvmtiHeapObjectCallback)
    (jlong class_tag,
     jlong size,
     jlong* tag_ptr,
     void* user_data);
Agent supplied callback function. Describes (but does not pass in) an object in the heap.

Return value should be JVMTI_ITERATION_CONTINUE to continue iteration, or JVMTI_ITERATION_ABORT to stop iteration.

See the heap callback function restrictions.

Parameters
Name | Type | Description
class_tag | jlong | The tag of the class of object (zero if the class is not tagged). If the object represents a runtime class, the class_tag is the tag associated with java.lang.Class (zero if java.lang.Class is not tagged).
size | jlong | Size of the object (in bytes). See GetObjectSize.
tag_ptr | jlong* | The object tag value, or zero if the object is not tagged. To set the tag value to be associated with the object the agent sets the jlong pointed to by the parameter.
user_data | void* | The user supplied data that was passed into the iteration function.

Heap Root Object Callback

typedef jvmtiIterationControl (JNICALL *jvmtiHeapRootCallback)
    (jvmtiHeapRootKind root_kind,
     jlong class_tag,
     jlong size,
     jlong* tag_ptr,
     void* user_data);
Agent supplied callback function. Describes (but does not pass in) an object that is a root for the purposes of garbage collection.

Return value should be JVMTI_ITERATION_CONTINUE to continue iteration, JVMTI_ITERATION_IGNORE to continue iteration without pursuing references from referree object or JVMTI_ITERATION_ABORT to stop iteration.

See the heap callback function restrictions.

Parameters
Name | Type | Description
root_kind | jvmtiHeapRootKind | The kind of heap root.
class_tag | jlong | The tag of the class of object (zero if the class is not tagged). If the object represents a runtime class, the class_tag is the tag associated with java.lang.Class (zero if java.lang.Class is not tagged).
size | jlong | Size of the object (in bytes). See GetObjectSize.
tag_ptr | jlong* | The object tag value, or zero if the object is not tagged. To set the tag value to be associated with the object the agent sets the jlong pointed to by the parameter.
user_data | void* | The user supplied data that was passed into the iteration function.

Stack Reference Object Callback

typedef jvmtiIterationControl (JNICALL *jvmtiStackReferenceCallback)
    (jvmtiHeapRootKind root_kind,
     jlong class_tag,
     jlong size,
     jlong* tag_ptr,
     jlong thread_tag,
     jint depth,
     jmethodID method,
     jint slot,
     void* user_data);
Agent supplied callback function. Describes (but does not pass in) an object on the stack that is a root for the purposes of garbage collection.

Return value should be JVMTI_ITERATION_CONTINUE to continue iteration, JVMTI_ITERATION_IGNORE to continue iteration without pursuing references from referree object or JVMTI_ITERATION_ABORT to stop iteration.

See the heap callback function restrictions.

Parameters
Name | Type | Description
root_kind | jvmtiHeapRootKind | The kind of root (either JVMTI_HEAP_ROOT_STACK_LOCAL or JVMTI_HEAP_ROOT_JNI_LOCAL).
class_tag | jlong | The tag of the class of object (zero if the class is not tagged). If the object represents a runtime class, the class_tag is the tag associated with java.lang.Class (zero if java.lang.Class is not tagged).
size | jlong | Size of the object (in bytes). See GetObjectSize.
tag_ptr | jlong* | The object tag value, or zero if the object is not tagged. To set the tag value to be associated with the object the agent sets the jlong pointed to by the parameter.
thread_tag | jlong | The tag of the thread corresponding to this stack, zero if not tagged.
depth | jint | The depth of the frame.
method | jmethodID | The method executing in this frame.
slot | jint | The slot number.
user_data | void* | The user supplied data that was passed into the iteration function.

Object Reference Callback

typedef jvmtiIterationControl (JNICALL *jvmtiObjectReferenceCallback)
    (jvmtiObjectReferenceKind reference_kind,
     jlong class_tag,
     jlong size,
     jlong* tag_ptr,
     jlong referrer_tag,
     jint referrer_index,
     void* user_data);
Agent supplied callback function. Describes a reference from an object (the referrer) to another object (the referree).

Return value should be JVMTI_ITERATION_CONTINUE to continue iteration, JVMTI_ITERATION_IGNORE to continue iteration without pursuing references from referree object or JVMTI_ITERATION_ABORT to stop iteration.

See the heap callback function restrictions.

Parameters
Name | Type | Description
reference_kind | jvmtiObjectReferenceKind | The type of reference.
class_tag | jlong | The tag of the class of referree object (zero if the class is not tagged). If the referree object represents a runtime class, the class_tag is the tag associated with java.lang.Class (zero if java.lang.Class is not tagged).
size | jlong | Size of the referree object (in bytes). See GetObjectSize.
tag_ptr | jlong* | The referree object tag value, or zero if the object is not tagged. To set the tag value to be associated with the object the agent sets the jlong pointed to by the parameter.
referrer_tag | jlong | The tag of the referrer object, or zero if the referrer object is not tagged.
referrer_index | jint | For references of type JVMTI_REFERENCE_FIELD or JVMTI_REFERENCE_STATIC_FIELD the index of the field in the referrer object. The index is based on the order of all the object's fields - see JVMTI_REFERENCE_FIELD or JVMTI_REFERENCE_STATIC_FIELD for further description. For references of type JVMTI_REFERENCE_ARRAY_ELEMENT the array index - see JVMTI_REFERENCE_ARRAY_ELEMENT for further description. For references of type JVMTI_REFERENCE_CONSTANT_POOL the index into the constant pool of the class - see JVMTI_REFERENCE_CONSTANT_POOL for further description. For references of other kinds the referrer_index is -1.
user_data | void* | The user supplied data that was passed into the iteration function.

Iterate Over Objects Reachable From Object

jvmtiError
IterateOverObjectsReachableFromObject(jvmtiEnv* env,
            jobject object,
            jvmtiObjectReferenceCallback object_reference_callback,
            const void* user_data)
This function iterates over all objects that are directly and indirectly reachable from the specified object. For each object A (known as the referrer) with a reference to object B the specified callback function is called to describe the object reference. The callback is called exactly once for each reference from a referrer; this is true even if there are reference cycles or multiple paths to the referrer. There may be more than one reference between a referrer and a referree, These may be distinguished by the jvmtiObjectReferenceCallback.reference_kind and jvmtiObjectReferenceCallback.referrer_index. The callback for an object will always occur after the callback for its referrer.

See FollowReferences for the object references which are reported.

During the execution of this function the state of the heap does not change: no objects are allocated, no objects are garbage collected, and the state of objects (including held values) does not change. As a result, threads executing Java programming language code, threads attempting to resume the execution of Java programming language code, and threads attempting to execute JNI functions are typically stalled.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 109 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_tag_objects | Can set and get tags, as described in the Heap category.

Parameters
Name | Type | Description
object | jobject | The object
object_reference_callback | jvmtiObjectReferenceCallback | The callback to be called to describe each object reference.
user_data | const void * | User supplied data to be passed to the callback. Agent passes in a pointer. If user_data is NULL, NULL is passed as the user supplied data.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_tag_objects. Use AddCapabilities.
JVMTI_ERROR_INVALID_OBJECT | object is not an object.
JVMTI_ERROR_NULL_POINTER | object_reference_callback is NULL.

Iterate Over Reachable Objects

jvmtiError
IterateOverReachableObjects(jvmtiEnv* env,
            jvmtiHeapRootCallback heap_root_callback,
            jvmtiStackReferenceCallback stack_ref_callback,
            jvmtiObjectReferenceCallback object_ref_callback,
            const void* user_data)
This function iterates over the root objects and all objects that are directly and indirectly reachable from the root objects. The root objects comprise the set of system classes, JNI globals, references from thread stacks, and other objects used as roots for the purposes of garbage collection.

For each root the heap_root_callback or stack_ref_callback callback is called. An object can be a root object for more than one reason and in that case the appropriate callback is called for each reason.

For each object reference the object_ref_callback callback function is called to describe the object reference. The callback is called exactly once for each reference from a referrer; this is true even if there are reference cycles or multiple paths to the referrer. There may be more than one reference between a referrer and a referree, These may be distinguished by the jvmtiObjectReferenceCallback.reference_kind and jvmtiObjectReferenceCallback.referrer_index. The callback for an object will always occur after the callback for its referrer.

See FollowReferences for the object references which are reported.

Roots are always reported to the profiler before any object references are reported. In other words, the object_ref_callback callback will not be called until the appropriate callback has been called for all roots. If the object_ref_callback callback is specified as NULL then this function returns after reporting the root objects to the profiler.

During the execution of this function the state of the heap does not change: no objects are allocated, no objects are garbage collected, and the state of objects (including held values) does not change. As a result, threads executing Java programming language code, threads attempting to resume the execution of Java programming language code, and threads attempting to execute JNI functions are typically stalled.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 110 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_tag_objects | Can set and get tags, as described in the Heap category.

Parameters
Name | Type | Description
heap_root_callback | jvmtiHeapRootCallback | The callback function to be called for each heap root of type JVMTI_HEAP_ROOT_JNI_GLOBAL, JVMTI_HEAP_ROOT_SYSTEM_CLASS, JVMTI_HEAP_ROOT_MONITOR, JVMTI_HEAP_ROOT_THREAD, or JVMTI_HEAP_ROOT_OTHER. If heap_root_callback is NULL, do not report heap roots.
stack_ref_callback | jvmtiStackReferenceCallback | The callback function to be called for each heap root of JVMTI_HEAP_ROOT_STACK_LOCAL or JVMTI_HEAP_ROOT_JNI_LOCAL. If stack_ref_callback is NULL, do not report stack references.
object_ref_callback | jvmtiObjectReferenceCallback | The callback function to be called for each object reference. If object_ref_callback is NULL, do not follow references from the root objects.
user_data | const void * | User supplied data to be passed to the callback. Agent passes in a pointer. If user_data is NULL, NULL is passed as the user supplied data.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_tag_objects. Use AddCapabilities.

Iterate Over Heap

jvmtiError
IterateOverHeap(jvmtiEnv* env,
            jvmtiHeapObjectFilter object_filter,
            jvmtiHeapObjectCallback heap_object_callback,
            const void* user_data)
Iterate over all objects in the heap. This includes both reachable and unreachable objects.

The object_filter parameter indicates the objects for which the callback function is called. If this parameter is JVMTI_HEAP_OBJECT_TAGGED then the callback will only be called for every object that is tagged. If the parameter is JVMTI_HEAP_OBJECT_UNTAGGED then the callback will only be for objects that are not tagged. If the parameter is JVMTI_HEAP_OBJECT_EITHER then the callback will be called for every object in the heap, irrespective of whether it is tagged or not.

During the execution of this function the state of the heap does not change: no objects are allocated, no objects are garbage collected, and the state of objects (including held values) does not change. As a result, threads executing Java programming language code, threads attempting to resume the execution of Java programming language code, and threads attempting to execute JNI functions are typically stalled.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 111 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_tag_objects | Can set and get tags, as described in the Heap category.

Parameters
Name | Type | Description
object_filter | jvmtiHeapObjectFilter | Indicates the objects for which the callback function is called.
heap_object_callback | jvmtiHeapObjectCallback | The iterator function to be called for each object matching the object_filter.
user_data | const void * | User supplied data to be passed to the callback. Agent passes in a pointer. If user_data is NULL, NULL is passed as the user supplied data.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_tag_objects. Use AddCapabilities.
JVMTI_ERROR_ILLEGAL_ARGUMENT | object_filter is not a jvmtiHeapObjectFilter.
JVMTI_ERROR_NULL_POINTER | heap_object_callback is NULL.

Iterate Over Instances Of Class

jvmtiError
IterateOverInstancesOfClass(jvmtiEnv* env,
            jclass klass,
            jvmtiHeapObjectFilter object_filter,
            jvmtiHeapObjectCallback heap_object_callback,
            const void* user_data)
Iterate over all objects in the heap that are instances of the specified class. This includes direct instances of the specified class and instances of all subclasses of the specified class. This includes both reachable and unreachable objects.

The object_filter parameter indicates the objects for which the callback function is called. If this parameter is JVMTI_HEAP_OBJECT_TAGGED then the callback will only be called for every object that is tagged. If the parameter is JVMTI_HEAP_OBJECT_UNTAGGED then the callback will only be called for objects that are not tagged. If the parameter is JVMTI_HEAP_OBJECT_EITHER then the callback will be called for every object in the heap, irrespective of whether it is tagged or not.

During the execution of this function the state of the heap does not change: no objects are allocated, no objects are garbage collected, and the state of objects (including held values) does not change. As a result, threads executing Java programming language code, threads attempting to resume the execution of Java programming language code, and threads attempting to execute JNI functions are typically stalled.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 112 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_tag_objects | Can set and get tags, as described in the Heap category.

Parameters
Name | Type | Description
klass | jclass | Iterate over objects of this class only.
object_filter | jvmtiHeapObjectFilter | Indicates the objects for which the callback function is called.
heap_object_callback | jvmtiHeapObjectCallback | The iterator function to be called for each klass instance matching the object_filter.
user_data | const void * | User supplied data to be passed to the callback. Agent passes in a pointer. If user_data is NULL, NULL is passed as the user supplied data.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_tag_objects. Use AddCapabilities.
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_ILLEGAL_ARGUMENT | object_filter is not a jvmtiHeapObjectFilter.
JVMTI_ERROR_NULL_POINTER | heap_object_callback is NULL.

Local Variable

Local Variable functions:
  • Get Local Variable - Object
  • Get Local Variable - Int
  • Get Local Variable - Long
  • Get Local Variable - Float
  • Get Local Variable - Double
  • Set Local Variable - Object
  • Set Local Variable - Int
  • Set Local Variable - Long
  • Set Local Variable - Float
  • Set Local Variable - Double
These functions are used to retrieve or set the value of a local variable. The variable is identified by the depth of the frame containing its value and the variable's slot number within that frame. The mapping of variables to slot numbers can be obtained with the function GetLocalVariableTable.

Get Local Variable - Object

jvmtiError
GetLocalObject(jvmtiEnv* env,
            jthread thread,
            jint depth,
            jint slot,
            jobject* value_ptr)
This function can be used to retrieve the value of a local variable whose type is Object or a subclass of Object.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 21 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_access_local_variables | Can set and get local variables

Parameters
Name | Type | Description
thread | jthread | The thread of the frame containing the variable's value. If thread is NULL, the current thread is used.
depth | jint | The depth of the frame containing the variable's value.
slot | jint | The variable's slot number.
value_ptr | jobject* | On return, points to the variable's value. Agent passes a pointer to a jobject. On return, the jobject has been set. The object returned by value_ptr is a JNI local reference and must be managed.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_access_local_variables. Use AddCapabilities.
JVMTI_ERROR_INVALID_SLOT | Invalid slot.
JVMTI_ERROR_TYPE_MISMATCH | The variable type is not Object or a subclass of Object.
JVMTI_ERROR_OPAQUE_FRAME | Not a visible frame
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_ILLEGAL_ARGUMENT | depth is less than zero.
JVMTI_ERROR_NO_MORE_FRAMES | There are no stack frames at the specified depth.
JVMTI_ERROR_NULL_POINTER | value_ptr is NULL.

Get Local Variable - Int

jvmtiError
GetLocalInt(jvmtiEnv* env,
            jthread thread,
            jint depth,
            jint slot,
            jint* value_ptr)
This function can be used to retrieve the value of a local variable whose type is int, short, char, byte, or boolean.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 22 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_access_local_variables | Can set and get local variables

Parameters
Name | Type | Description
thread | jthread | The thread of the frame containing the variable's value. If thread is NULL, the current thread is used.
depth | jint | The depth of the frame containing the variable's value.
slot | jint | The variable's slot number.
value_ptr | jint* | On return, points to the variable's value. Agent passes a pointer to a jint. On return, the jint has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_access_local_variables. Use AddCapabilities.
JVMTI_ERROR_INVALID_SLOT | Invalid slot.
JVMTI_ERROR_TYPE_MISMATCH | The variable type is not int, short, char, byte, or boolean.
JVMTI_ERROR_OPAQUE_FRAME | Not a visible frame
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_ILLEGAL_ARGUMENT | depth is less than zero.
JVMTI_ERROR_NO_MORE_FRAMES | There are no stack frames at the specified depth.
JVMTI_ERROR_NULL_POINTER | value_ptr is NULL.

Get Local Variable - Long

jvmtiError
GetLocalLong(jvmtiEnv* env,
            jthread thread,
            jint depth,
            jint slot,
            jlong* value_ptr)
This function can be used to retrieve the value of a local variable whose type is long.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 23 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_access_local_variables | Can set and get local variables

Parameters
Name | Type | Description
thread | jthread | The thread of the frame containing the variable's value. If thread is NULL, the current thread is used.
depth | jint | The depth of the frame containing the variable's value.
slot | jint | The variable's slot number.
value_ptr | jlong* | On return, points to the variable's value. Agent passes a pointer to a jlong. On return, the jlong has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_access_local_variables. Use AddCapabilities.
JVMTI_ERROR_INVALID_SLOT | Invalid slot.
JVMTI_ERROR_TYPE_MISMATCH | The variable type is not long.
JVMTI_ERROR_OPAQUE_FRAME | Not a visible frame
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_ILLEGAL_ARGUMENT | depth is less than zero.
JVMTI_ERROR_NO_MORE_FRAMES | There are no stack frames at the specified depth.
JVMTI_ERROR_NULL_POINTER | value_ptr is NULL.

Get Local Variable - Float

jvmtiError
GetLocalFloat(jvmtiEnv* env,
            jthread thread,
            jint depth,
            jint slot,
            jfloat* value_ptr)
This function can be used to retrieve the value of a local variable whose type is float.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 24 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_access_local_variables | Can set and get local variables

Parameters
Name | Type | Description
thread | jthread | The thread of the frame containing the variable's value. If thread is NULL, the current thread is used.
depth | jint | The depth of the frame containing the variable's value.
slot | jint | The variable's slot number.
value_ptr | jfloat* | On return, points to the variable's value. Agent passes a pointer to a jfloat. On return, the jfloat has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_access_local_variables. Use AddCapabilities.
JVMTI_ERROR_INVALID_SLOT | Invalid slot.
JVMTI_ERROR_TYPE_MISMATCH | The variable type is not float.
JVMTI_ERROR_OPAQUE_FRAME | Not a visible frame
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_ILLEGAL_ARGUMENT | depth is less than zero.
JVMTI_ERROR_NO_MORE_FRAMES | There are no stack frames at the specified depth.
JVMTI_ERROR_NULL_POINTER | value_ptr is NULL.

Get Local Variable - Double

jvmtiError
GetLocalDouble(jvmtiEnv* env,
            jthread thread,
            jint depth,
            jint slot,
            jdouble* value_ptr)
This function can be used to retrieve the value of a local variable whose type is long.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 25 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_access_local_variables | Can set and get local variables

Parameters
Name | Type | Description
thread | jthread | The thread of the frame containing the variable's value. If thread is NULL, the current thread is used.
depth | jint | The depth of the frame containing the variable's value.
slot | jint | The variable's slot number.
value_ptr | jdouble* | On return, points to the variable's value. Agent passes a pointer to a jdouble. On return, the jdouble has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_access_local_variables. Use AddCapabilities.
JVMTI_ERROR_INVALID_SLOT | Invalid slot.
JVMTI_ERROR_TYPE_MISMATCH | The variable type is not double.
JVMTI_ERROR_OPAQUE_FRAME | Not a visible frame
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_ILLEGAL_ARGUMENT | depth is less than zero.
JVMTI_ERROR_NO_MORE_FRAMES | There are no stack frames at the specified depth.
JVMTI_ERROR_NULL_POINTER | value_ptr is NULL.

Set Local Variable - Object

jvmtiError
SetLocalObject(jvmtiEnv* env,
            jthread thread,
            jint depth,
            jint slot,
            jobject value)
This function can be used to set the value of a local variable whose type is Object or a subclass of Object.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 26 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_access_local_variables | Can set and get local variables

Parameters
Name | Type | Description
thread | jthread | The thread of the frame containing the variable's value. If thread is NULL, the current thread is used.
depth | jint | The depth of the frame containing the variable's value.
slot | jint | The variable's slot number.
value | jobject | The new value for the variable.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_access_local_variables. Use AddCapabilities.
JVMTI_ERROR_INVALID_SLOT | Invalid slot.
JVMTI_ERROR_TYPE_MISMATCH | The variable type is not Object or a subclass of Object.
JVMTI_ERROR_TYPE_MISMATCH | The supplied value is not compatible with the variable type.
JVMTI_ERROR_OPAQUE_FRAME | Not a visible frame
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_ILLEGAL_ARGUMENT | depth is less than zero.
JVMTI_ERROR_NO_MORE_FRAMES | There are no stack frames at the specified depth.
JVMTI_ERROR_INVALID_OBJECT | value is not an object.

Set Local Variable - Int

jvmtiError
SetLocalInt(jvmtiEnv* env,
            jthread thread,
            jint depth,
            jint slot,
            jint value)
This function can be used to set the value of a local variable whose type is int, short, char, byte, or boolean.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 27 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_access_local_variables | Can set and get local variables

Parameters
Name | Type | Description
thread | jthread | The thread of the frame containing the variable's value. If thread is NULL, the current thread is used.
depth | jint | The depth of the frame containing the variable's value.
slot | jint | The variable's slot number.
value | jint | The new value for the variable.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_access_local_variables. Use AddCapabilities.
JVMTI_ERROR_INVALID_SLOT | Invalid slot.
JVMTI_ERROR_TYPE_MISMATCH | The variable type is not int, short, char, byte, or boolean.
JVMTI_ERROR_OPAQUE_FRAME | Not a visible frame
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_ILLEGAL_ARGUMENT | depth is less than zero.
JVMTI_ERROR_NO_MORE_FRAMES | There are no stack frames at the specified depth.

Set Local Variable - Long

jvmtiError
SetLocalLong(jvmtiEnv* env,
            jthread thread,
            jint depth,
            jint slot,
            jlong value)
This function can be used to set the value of a local variable whose type is long.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 28 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_access_local_variables | Can set and get local variables

Parameters
Name | Type | Description
thread | jthread | The thread of the frame containing the variable's value. If thread is NULL, the current thread is used.
depth | jint | The depth of the frame containing the variable's value.
slot | jint | The variable's slot number.
value | jlong | The new value for the variable.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_access_local_variables. Use AddCapabilities.
JVMTI_ERROR_INVALID_SLOT | Invalid slot.
JVMTI_ERROR_TYPE_MISMATCH | The variable type is not long.
JVMTI_ERROR_OPAQUE_FRAME | Not a visible frame
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_ILLEGAL_ARGUMENT | depth is less than zero.
JVMTI_ERROR_NO_MORE_FRAMES | There are no stack frames at the specified depth.

Set Local Variable - Float

jvmtiError
SetLocalFloat(jvmtiEnv* env,
            jthread thread,
            jint depth,
            jint slot,
            jfloat value)
This function can be used to set the value of a local variable whose type is float.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 29 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_access_local_variables | Can set and get local variables

Parameters
Name | Type | Description
thread | jthread | The thread of the frame containing the variable's value. If thread is NULL, the current thread is used.
depth | jint | The depth of the frame containing the variable's value.
slot | jint | The variable's slot number.
value | jfloat | The new value for the variable.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_access_local_variables. Use AddCapabilities.
JVMTI_ERROR_INVALID_SLOT | Invalid slot.
JVMTI_ERROR_TYPE_MISMATCH | The variable type is not float.
JVMTI_ERROR_OPAQUE_FRAME | Not a visible frame
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_ILLEGAL_ARGUMENT | depth is less than zero.
JVMTI_ERROR_NO_MORE_FRAMES | There are no stack frames at the specified depth.

Set Local Variable - Double

jvmtiError
SetLocalDouble(jvmtiEnv* env,
            jthread thread,
            jint depth,
            jint slot,
            jdouble value)
This function can be used to set the value of a local variable whose type is double.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 30 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_access_local_variables | Can set and get local variables

Parameters
Name | Type | Description
thread | jthread | The thread of the frame containing the variable's value. If thread is NULL, the current thread is used.
depth | jint | The depth of the frame containing the variable's value.
slot | jint | The variable's slot number.
value | jdouble | The new value for the variable.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_access_local_variables. Use AddCapabilities.
JVMTI_ERROR_INVALID_SLOT | Invalid slot.
JVMTI_ERROR_TYPE_MISMATCH | The variable type is not double.
JVMTI_ERROR_OPAQUE_FRAME | Not a visible frame
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_ILLEGAL_ARGUMENT | depth is less than zero.
JVMTI_ERROR_NO_MORE_FRAMES | There are no stack frames at the specified depth.

Breakpoint

Breakpoint functions:
  • Set Breakpoint
  • Clear Breakpoint

Set Breakpoint

jvmtiError
SetBreakpoint(jvmtiEnv* env,
            jmethodID method,
            jlocation location)
Set a breakpoint at the instruction indicated by method and location. An instruction can only have one breakpoint.

Whenever the designated instruction is about to be executed, a Breakpoint event is generated.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 38 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_generate_breakpoint_events | Can set and thus get Breakpoint events

Parameters
Name | Type | Description
method | jmethodID | The method in which to set the breakpoint
location | jlocation | the index of the instruction at which to set the breakpoint

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_generate_breakpoint_events. Use AddCapabilities.
JVMTI_ERROR_DUPLICATE | The designated bytecode already has a breakpoint.
JVMTI_ERROR_INVALID_METHODID | method is not a jmethodID.
JVMTI_ERROR_INVALID_LOCATION | location is not a valid location.

Clear Breakpoint

jvmtiError
ClearBreakpoint(jvmtiEnv* env,
            jmethodID method,
            jlocation location)
Clear the breakpoint at the bytecode indicated by method and location.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 39 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_generate_breakpoint_events | Can set and thus get Breakpoint events

Parameters
Name | Type | Description
method | jmethodID | The method in which to clear the breakpoint
location | jlocation | the index of the instruction at which to clear the breakpoint

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_generate_breakpoint_events. Use AddCapabilities.
JVMTI_ERROR_NOT_FOUND | There's no breakpoint at the designated bytecode.
JVMTI_ERROR_INVALID_METHODID | method is not a jmethodID.
JVMTI_ERROR_INVALID_LOCATION | location is not a valid location.

Watched Field

Watched Field functions:
  • Set Field Access Watch
  • Clear Field Access Watch
  • Set Field Modification Watch
  • Clear Field Modification Watch

Set Field Access Watch

jvmtiError
SetFieldAccessWatch(jvmtiEnv* env,
            jclass klass,
            jfieldID field)
Generate a FieldAccess event when the field specified by klass and field is about to be accessed. An event will be generated for each access of the field until it is canceled with ClearFieldAccessWatch. Field accesses from Java programming language code or from JNI code are watched, fields modified by other means are not watched. Note that JVM TI users should be aware that their own field accesses will trigger the watch. A field can only have one field access watch set. Modification of a field is not considered an access--use SetFieldModificationWatch to monitor modifications.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 41 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_generate_field_access_events | Can set watchpoints on field access - SetFieldAccessWatch

Parameters
Name | Type | Description
klass | jclass | The class containing the field to watch
field | jfieldID | The field to watch

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_generate_field_access_events. Use AddCapabilities.
JVMTI_ERROR_DUPLICATE | The designated field is already being watched for accesses.
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_INVALID_FIELDID | field is not a jfieldID.

Clear Field Access Watch

jvmtiError
ClearFieldAccessWatch(jvmtiEnv* env,
            jclass klass,
            jfieldID field)
Cancel a field access watch previously set by SetFieldAccessWatch, on the field specified by klass and field.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 42 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_generate_field_access_events | Can set watchpoints on field access - SetFieldAccessWatch

Parameters
Name | Type | Description
klass | jclass | The class containing the field to watch
field | jfieldID | The field to watch

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_generate_field_access_events. Use AddCapabilities.
JVMTI_ERROR_NOT_FOUND | The designated field is not being watched for accesses.
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_INVALID_FIELDID | field is not a jfieldID.

Set Field Modification Watch

jvmtiError
SetFieldModificationWatch(jvmtiEnv* env,
            jclass klass,
            jfieldID field)
Generate a FieldModification event when the field specified by klass and field is about to be modified. An event will be generated for each modification of the field until it is canceled with ClearFieldModificationWatch. Field modifications from Java programming language code or from JNI code are watched, fields modified by other means are not watched. Note that JVM TI users should be aware that their own field modifications will trigger the watch. A field can only have one field modification watch set.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 43 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_generate_field_modification_events | Can set watchpoints on field modification - SetFieldModificationWatch

Parameters
Name | Type | Description
klass | jclass | The class containing the field to watch
field | jfieldID | The field to watch

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_generate_field_modification_events. Use AddCapabilities.
JVMTI_ERROR_DUPLICATE | The designated field is already being watched for modifications.
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_INVALID_FIELDID | field is not a jfieldID.

Clear Field Modification Watch

jvmtiError
ClearFieldModificationWatch(jvmtiEnv* env,
            jclass klass,
            jfieldID field)
Cancel a field modification watch previously set by SetFieldModificationWatch, on the field specified by klass and field.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 44 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_generate_field_modification_events | Can set watchpoints on field modification - SetFieldModificationWatch

Parameters
Name | Type | Description
klass | jclass | The class containing the field to watch
field | jfieldID | The field to watch

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_generate_field_modification_events. Use AddCapabilities.
JVMTI_ERROR_NOT_FOUND | The designated field is not being watched for modifications.
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_INVALID_FIELDID | field is not a jfieldID.

Class

Class functions:
  • Get Loaded Classes
  • Get Classloader Classes
  • Get Class Signature
  • Get Class Status
  • Get Source File Name
  • Get Class Modifiers
  • Get Class Methods
  • Get Class Fields
  • Get Implemented Interfaces
  • Get Class Version Numbers
  • Get Constant Pool
  • Is Interface
  • Is Array Class
  • Is Modifiable Class
  • Get Class Loader
  • Get Source Debug Extension
  • Retransform Classes
  • Redefine Classes
Class types:
  • jvmtiClassDefinition - Class redefinition description
Class flags and constants:
  • Class Status Flags

Get Loaded Classes

jvmtiError
GetLoadedClasses(jvmtiEnv* env,
            jint* class_count_ptr,
            jclass** classes_ptr)
Return an array of all classes loaded in the virtual machine. The number of classes in the array is returned via class_count_ptr, and the array itself via classes_ptr.

Array classes of all types (including arrays of primitive types) are included in the returned list. Primitive classes (for example, java.lang.Integer.TYPE) are not included in this list.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 78 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
class_count_ptr | jint* | On return, points to the number of classes. Agent passes a pointer to a jint. On return, the jint has been set.
classes_ptr | jclass** | On return, points to an array of references, one for each class. Agent passes a pointer to a jclass*. On return, the jclass* points to a newly allocated array of size *class_count_ptr. The array should be freed with Deallocate. The objects returned by classes_ptr are JNI local references and must be managed.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | class_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | classes_ptr is NULL.

Get Classloader Classes

jvmtiError
GetClassLoaderClasses(jvmtiEnv* env,
            jobject initiating_loader,
            jint* class_count_ptr,
            jclass** classes_ptr)
Returns an array of those classes for which this class loader has been recorded as an initiating loader. Each class in the returned array was created by this class loader, either by defining it directly or by delegation to another class loader. See the Creation and Loading section of the Java Virtual Machine Specification.

For JDK version 1.1 implementations that don't recognize the distinction between initiating and defining class loaders, this function should return all classes loaded in the virtual machine. The number of classes in the array is returned via class_count_ptr, and the array itself via classes_ptr.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 79 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
initiating_loader | jobject | An initiating class loader. If initiating_loader is NULL, the classes initiated by the bootstrap loader will be returned.
class_count_ptr | jint* | On return, points to the number of classes. Agent passes a pointer to a jint. On return, the jint has been set.
classes_ptr | jclass** | On return, points to an array of references, one for each class. Agent passes a pointer to a jclass*. On return, the jclass* points to a newly allocated array of size *class_count_ptr. The array should be freed with Deallocate. The objects returned by classes_ptr are JNI local references and must be managed.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | class_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | classes_ptr is NULL.

Get Class Signature

jvmtiError
GetClassSignature(jvmtiEnv* env,
            jclass klass,
            char** signature_ptr,
            char** generic_ptr)
For the class indicated by klass, return the JNI type signature and the generic signature of the class. For example, java.util.List is "Ljava/util/List;" and int[] is "[I" The returned name for primitive classes is the type signature character of the corresponding primitive type. For example, java.lang.Integer.TYPE is "I".

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 48 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
klass | jclass | The class to query.
signature_ptr | char ** | On return, points to the JNI type signature of the class, encoded as a modified UTF-8 string. Agent passes a pointer to a char*. On return, the char* points to a newly allocated array. The array should be freed with Deallocate. If signature_ptr is NULL, the signature is not returned.
generic_ptr | char ** | On return, points to the generic signature of the class, encoded as a modified UTF-8 string. If there is no generic signature attribute for the class, then, on return, points to NULL. Agent passes a pointer to a char*. On return, the char* points to a newly allocated array. The array should be freed with Deallocate. If generic_ptr is NULL, the generic signature is not returned.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.

Get Class Status

jvmtiError
GetClassStatus(jvmtiEnv* env,
            jclass klass,
            jint* status_ptr)
Get the status of the class. Zero or more of the following bits can be set.
Class Status Flags
Constant | Value | Description
JVMTI_CLASS_STATUS_VERIFIED | 1 | Class bytecodes have been verified
JVMTI_CLASS_STATUS_PREPARED | 2 | Class preparation is complete
JVMTI_CLASS_STATUS_INITIALIZED | 4 | Class initialization is complete. Static initializer has been run.
JVMTI_CLASS_STATUS_ERROR | 8 | Error during initialization makes class unusable
JVMTI_CLASS_STATUS_ARRAY | 16 | Class is an array. If set, all other bits are zero.
JVMTI_CLASS_STATUS_PRIMITIVE | 32 | Class is a primitive class (for example, java.lang.Integer.TYPE). If set, all other bits are zero.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 49 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
klass | jclass | The class to query.
status_ptr | jint* | On return, points to the current state of this class as one or more of the class status flags. Agent passes a pointer to a jint. On return, the jint has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_NULL_POINTER | status_ptr is NULL.

Get Source File Name

jvmtiError
GetSourceFileName(jvmtiEnv* env,
            jclass klass,
            char** source_name_ptr)
For the class indicated by klass, return the source file name via source_name_ptr. The returned string is a file name only and never contains a directory name.

For primitive classes (for example, java.lang.Integer.TYPE) and for arrays this function returns JVMTI_ERROR_ABSENT_INFORMATION.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 50 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_get_source_file_name | Can get the source file name of a class

Parameters
Name | Type | Description
klass | jclass | The class to query.
source_name_ptr | char** | On return, points to the class's source file name, encoded as a modified UTF-8 string. Agent passes a pointer to a char*. On return, the char* points to a newly allocated array. The array should be freed with Deallocate.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_get_source_file_name. Use AddCapabilities.
JVMTI_ERROR_ABSENT_INFORMATION | Class information does not include a source file name. This includes cases where the class is an array class or primitive class.
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_NULL_POINTER | source_name_ptr is NULL.

Get Class Modifiers

jvmtiError
GetClassModifiers(jvmtiEnv* env,
            jclass klass,
            jint* modifiers_ptr)
For the class indicated by klass, return the access flags via modifiers_ptr. Access flags are defined in the Class File Format chapter of the Java Virtual Machine Specification.

If the class is an array class, then its public, private, and protected modifiers are the same as those of its component type. For arrays of primitives, this component type is represented by one of the primitive classes (for example, java.lang.Integer.TYPE).

If the class is a primitive class, its public modifier is always true, and its protected and private modifiers are always false.

If the class is an array class or a primitive class then its final modifier is always true and its interface modifier is always false. The values of its other modifiers are not determined by this specification.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 51 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
klass | jclass | The class to query.
modifiers_ptr | jint* | On return, points to the current access flags of this class. Agent passes a pointer to a jint. On return, the jint has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_NULL_POINTER | modifiers_ptr is NULL.

Get Class Methods

jvmtiError
GetClassMethods(jvmtiEnv* env,
            jclass klass,
            jint* method_count_ptr,
            jmethodID** methods_ptr)
For the class indicated by klass, return a count of methods via method_count_ptr and a list of method IDs via methods_ptr. The method list contains constructors and static initializers as well as true methods. Only directly declared methods are returned (not inherited methods). An empty method list is returned for array classes and primitive classes (for example, java.lang.Integer.TYPE).

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 52 | 1.0

Capabilities
Required Functionality
Optional Features
Capability | Effect
can_maintain_original_method_order | Can return methods in the order they occur in the class file

Parameters
Name | Type | Description
klass | jclass | The class to query.
method_count_ptr | jint* | On return, points to the number of methods declared in this class. Agent passes a pointer to a jint. On return, the jint has been set.
methods_ptr | jmethodID** | On return, points to the method ID array. Agent passes a pointer to a jmethodID*. On return, the jmethodID* points to a newly allocated array of size *method_count_ptr. The array should be freed with Deallocate.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_CLASS_NOT_PREPARED | klass is not prepared.
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_NULL_POINTER | method_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | methods_ptr is NULL.

Get Class Fields

jvmtiError
GetClassFields(jvmtiEnv* env,
            jclass klass,
            jint* field_count_ptr,
            jfieldID** fields_ptr)
For the class indicated by klass, return a count of fields via field_count_ptr and a list of field IDs via fields_ptr. Only directly declared fields are returned (not inherited fields). Fields are returned in the order they occur in the class file. An empty field list is returned for array classes and primitive classes (for example, java.lang.Integer.TYPE). Use JNI to determine the length of an array.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 53 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
klass | jclass | The class to query.
field_count_ptr | jint* | On return, points to the number of fields declared in this class. Agent passes a pointer to a jint. On return, the jint has been set.
fields_ptr | jfieldID** | On return, points to the field ID array. Agent passes a pointer to a jfieldID*. On return, the jfieldID* points to a newly allocated array of size *field_count_ptr. The array should be freed with Deallocate.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_CLASS_NOT_PREPARED | klass is not prepared.
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_NULL_POINTER | field_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | fields_ptr is NULL.

Get Implemented Interfaces

jvmtiError
GetImplementedInterfaces(jvmtiEnv* env,
            jclass klass,
            jint* interface_count_ptr,
            jclass** interfaces_ptr)
Return the direct super-interfaces of this class. For a class, this function returns the interfaces declared in its implements clause. For an interface, this function returns the interfaces declared in its extends clause. An empty interface list is returned for array classes and primitive classes (for example, java.lang.Integer.TYPE).

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 54 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
klass | jclass | The class to query.
interface_count_ptr | jint* | On return, points to the number of interfaces. Agent passes a pointer to a jint. On return, the jint has been set.
interfaces_ptr | jclass** | On return, points to the interface array. Agent passes a pointer to a jclass*. On return, the jclass* points to a newly allocated array of size *interface_count_ptr. The array should be freed with Deallocate. The objects returned by interfaces_ptr are JNI local references and must be managed.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_CLASS_NOT_PREPARED | klass is not prepared.
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_NULL_POINTER | interface_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | interfaces_ptr is NULL.

Get Class Version Numbers

jvmtiError
GetClassVersionNumbers(jvmtiEnv* env,
            jclass klass,
            jint* minor_version_ptr,
            jint* major_version_ptr)
For the class indicated by klass, return the minor and major version numbers, as defined in the Class File Format chapter of the Java Virtual Machine Specification.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 145 | 1.1

Capabilities
Required Functionality

Parameters
Name | Type | Description
klass | jclass | The class to query.
minor_version_ptr | jint* | On return, points to the value of the minor_version item of the Class File Format. Note: to be consistent with the Class File Format, the minor version number is the first parameter. Agent passes a pointer to a jint. On return, the jint has been set.
major_version_ptr | jint* | On return, points to the value of the major_version item of the Class File Format. Agent passes a pointer to a jint. On return, the jint has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_ABSENT_INFORMATION | The class is a primitive or array class.
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_NULL_POINTER | minor_version_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | major_version_ptr is NULL.

Get Constant Pool

jvmtiError
GetConstantPool(jvmtiEnv* env,
            jclass klass,
            jint* constant_pool_count_ptr,
            jint* constant_pool_byte_count_ptr,
            unsigned char** constant_pool_bytes_ptr)
For the class indicated by klass, return the raw bytes of the constant pool in the format of the constant_pool item of the Class File Format in the Java Virtual Machine Specification. The format of the constant pool may differ between versions of the Class File Format, so, the minor and major class version numbers should be checked for compatibility.

The returned constant pool might not have the same layout or contents as the constant pool in the defining class file. The constant pool returned by GetConstantPool() may have more or fewer entries than the defining constant pool. Entries may be in a different order. The constant pool returned by GetConstantPool() will match the constant pool used by GetBytecodes(). That is, the bytecodes returned by GetBytecodes() will have constant pool indices which refer to constant pool entries returned by GetConstantPool(). Note that since RetransformClasses and RedefineClasses can change the constant pool, the constant pool returned by this function can change accordingly. Thus, the correspondence between GetConstantPool() and GetBytecodes() does not hold if there is an intervening class retransformation or redefinition. The value of a constant pool entry used by a given bytecode will match that of the defining class file (even if the indices don't match). Constant pool entries which are not used directly or indirectly by bytecodes (for example, UTF-8 strings associated with annotations) are not required to exist in the returned constant pool.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 146 | 1.1

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_get_constant_pool | Can get the constant pool of a class - GetConstantPool

Parameters
Name | Type | Description
klass | jclass | The class to query.
constant_pool_count_ptr | jint* | On return, points to the number of entries in the constant pool table plus one. This corresponds to the constant_pool_count item of the Class File Format. Agent passes a pointer to a jint. On return, the jint has been set.
constant_pool_byte_count_ptr | jint* | On return, points to the number of bytes in the returned raw constant pool. Agent passes a pointer to a jint. On return, the jint has been set.
constant_pool_bytes_ptr | unsigned char** | On return, points to the raw constant pool, that is the bytes defined by the constant_pool item of the Class File Format Agent passes a pointer to a unsigned char*. On return, the unsigned char* points to a newly allocated array of size *constant_pool_byte_count_ptr. The array should be freed with Deallocate.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_get_constant_pool. Use AddCapabilities.
JVMTI_ERROR_ABSENT_INFORMATION | The class is a primitive or array class.
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_NULL_POINTER | constant_pool_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | constant_pool_byte_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | constant_pool_bytes_ptr is NULL.

Is Interface

jvmtiError
IsInterface(jvmtiEnv* env,
            jclass klass,
            jboolean* is_interface_ptr)
Determines whether a class object reference represents an interface. The jboolean result is JNI_TRUE if the "class" is actually an interface, JNI_FALSE otherwise.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 55 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
klass | jclass | The class to query.
is_interface_ptr | jboolean* | On return, points to the boolean result of this function. Agent passes a pointer to a jboolean. On return, the jboolean has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_NULL_POINTER | is_interface_ptr is NULL.

Is Array Class

jvmtiError
IsArrayClass(jvmtiEnv* env,
            jclass klass,
            jboolean* is_array_class_ptr)
Determines whether a class object reference represents an array. The jboolean result is JNI_TRUE if the class is an array, JNI_FALSE otherwise.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 56 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
klass | jclass | The class to query.
is_array_class_ptr | jboolean* | On return, points to the boolean result of this function. Agent passes a pointer to a jboolean. On return, the jboolean has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_NULL_POINTER | is_array_class_ptr is NULL.

Is Modifiable Class

jvmtiError
IsModifiableClass(jvmtiEnv* env,
            jclass klass,
            jboolean* is_modifiable_class_ptr)
Determines whether a class is modifiable. If a class is modifiable (is_modifiable_class_ptr returns JNI_TRUE) the class can be redefined with RedefineClasses (assuming the agent possesses the can_redefine_classes capability) or retransformed with RetransformClasses (assuming the agent possesses the can_retransform_classes capability). If a class is not modifiable (is_modifiable_class_ptr returns JNI_FALSE) the class can be neither redefined nor retransformed.

Primitive classes (for example, java.lang.Integer.TYPE) and array classes are never modifiable.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 45 | 1.1

Capabilities
Required Functionality
Optional Features
Capability | Effect
can_redefine_any_class | If possessed then all classes (except primitive and array classes) are modifiable.
can_redefine_classes | No effect on the result of the function. But must additionally be possessed to modify the class with RedefineClasses.
can_retransform_classes | No effect on the result of the function. But must additionally be possessed to modify the class with RetransformClasses.

Parameters
Name | Type | Description
klass | jclass | The class to query.
is_modifiable_class_ptr | jboolean* | On return, points to the boolean result of this function. Agent passes a pointer to a jboolean. On return, the jboolean has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_NULL_POINTER | is_modifiable_class_ptr is NULL.

Get Class Loader

jvmtiError
GetClassLoader(jvmtiEnv* env,
            jclass klass,
            jobject* classloader_ptr)
For the class indicated by klass, return via classloader_ptr a reference to the class loader for the class.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 57 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
klass | jclass | The class to query.
classloader_ptr | jobject* | On return, points to the class loader that loaded this class. If the class was not created by a class loader or if the class loader is the bootstrap class loader, points to NULL. Agent passes a pointer to a jobject. On return, the jobject has been set. The object returned by classloader_ptr is a JNI local reference and must be managed.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_NULL_POINTER | classloader_ptr is NULL.

Get Source Debug Extension

jvmtiError
GetSourceDebugExtension(jvmtiEnv* env,
            jclass klass,
            char** source_debug_extension_ptr)
For the class indicated by klass, return the debug extension via source_debug_extension_ptr. The returned string contains exactly the debug extension information present in the class file of klass.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 90 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_get_source_debug_extension | Can get the source debug extension of a class

Parameters
Name | Type | Description
klass | jclass | The class to query.
source_debug_extension_ptr | char** | On return, points to the class's debug extension, encoded as a modified UTF-8 string. Agent passes a pointer to a char*. On return, the char* points to a newly allocated array. The array should be freed with Deallocate.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_get_source_debug_extension. Use AddCapabilities.
JVMTI_ERROR_ABSENT_INFORMATION | Class information does not include a debug extension.
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_NULL_POINTER | source_debug_extension_ptr is NULL.

Retransform Classes

jvmtiError
RetransformClasses(jvmtiEnv* env,
            jint class_count,
            const jclass* classes)
This function facilitates the bytecode instrumentation of already loaded classes. To replace the class definition without reference to the existing bytecodes, as one might do when recompiling from source for fix-and-continue debugging, RedefineClasses function should be used instead.

When classes are initially loaded or when they are redefined, the initial class file bytes can be transformed with the ClassFileLoadHook event. This function reruns the transformation process (whether or not a transformation has previously occurred). This retransformation follows these steps:
  • starting from the initial class file bytes
  • for each retransformation incapable agent which received a ClassFileLoadHook event during the previous load or redefine, the bytes it returned (via the new_class_data parameter) are reused as the output of the transformation; note that this is equivalent to reapplying the previous transformation, unaltered. except that the ClassFileLoadHook event is not sent to these agents
  • for each retransformation capable agent, the ClassFileLoadHook event is sent, allowing a new transformation to be applied
  • the transformed class file bytes are installed as the new definition of the class
See the ClassFileLoadHook event for more details.

The initial class file bytes represent the bytes passed to ClassLoader.defineClass or RedefineClasses (before any transformations were applied), however they may not exactly match them. The constant pool may differ in ways described in GetConstantPool. Constant pool indices in the bytecodes of methods will correspond. Some attributes may not be present. Where order is not meaningful, for example the order of methods, order may not be preserved.

Retransformation can cause new versions of methods to be installed. Old method versions may become obsolete The new method version will be used on new invokes. If a method has active stack frames, those active frames continue to run the bytecodes of the original method version.

This function does not cause any initialization except that which would occur under the customary JVM semantics. In other words, retransforming a class does not cause its initializers to be run. The values of static fields will remain as they were prior to the call.

Threads need not be suspended.

All breakpoints in the class are cleared.

All attributes are updated.

Instances of the retransformed class are not affected -- fields retain their previous values. Tags on the instances are also unaffected.

In response to this call, no events other than the ClassFileLoadHook event will be sent.

The retransformation may change method bodies, the constant pool and attributes. The retransformation must not add, remove or rename fields or methods, change the signatures of methods, change modifiers, or change inheritance. These restrictions may be lifted in future versions. See the error return description below for information on error codes returned if an unsupported retransformation is attempted. The class file bytes are not verified or installed until they have passed through the chain of ClassFileLoadHook events, thus the returned error code reflects the result of the transformations. If any error code is returned other than JVMTI_ERROR_NONE, none of the classes to be retransformed will have a new definition installed. When this function returns (with the error code of JVMTI_ERROR_NONE) all of the classes to be retransformed will have their new definitions installed.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 152 | 1.1

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_retransform_classes | Can retransform classes with RetransformClasses. In addition to the restrictions imposed by the specific implementation on this capability (see the Capability section), this capability must be set before the ClassFileLoadHook event is enabled for the first time in this environment. An environment that possesses this capability at the time that ClassFileLoadHook is enabled for the first time is said to be retransformation capable. An environment that does not possess this capability at the time that ClassFileLoadHook is enabled for the first time is said to be retransformation incapable.
Optional Features
can_retransform_any_class | RetransformClasses can be called on any class (can_retransform_classes must also be set)

Parameters
Name | Type | Description
class_count | jint | The number of classes to be retransformed.
classes | const jclass* | The array of classes to be retransformed. Agent passes in an array of class_count elements of jclass.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_retransform_classes. Use AddCapabilities.
JVMTI_ERROR_UNMODIFIABLE_CLASS | One of the classes cannot be modified. See IsModifiableClass.
JVMTI_ERROR_INVALID_CLASS | One of the classes is not a valid class.
JVMTI_ERROR_UNSUPPORTED_VERSION | A retransformed class file has a version number not supported by this VM.
JVMTI_ERROR_INVALID_CLASS_FORMAT | A retransformed class file is malformed (The VM would return a ClassFormatError).
JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION | The retransformed class file definitions would lead to a circular definition (the VM would return a ClassCircularityError).
JVMTI_ERROR_FAILS_VERIFICATION | The retransformed class file bytes fail verification.
JVMTI_ERROR_NAMES_DONT_MATCH | The class name defined in a retransformed class file is different from the name in the old class object.
JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED | A retransformed class file would require adding a method.
JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED | A retransformed class file changes a field.
JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED | A direct superclass is different for a retransformed class file, or the set of directly implemented interfaces is different.
JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED | A retransformed class file does not declare a method declared in the old class version.
JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED | A retransformed class file has different class modifiers.
JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED | A method in the retransformed class file has different modifiers than its counterpart in the old class version.
JVMTI_ERROR_ILLEGAL_ARGUMENT | class_count is less than 0.
JVMTI_ERROR_NULL_POINTER | classes is NULL.

Redefine Classes

typedef struct {
    jclass klass;
    jint class_byte_count;
    const unsigned char* class_bytes;
} jvmtiClassDefinition;
jvmtiError
RedefineClasses(jvmtiEnv* env,
            jint class_count,
            const jvmtiClassDefinition* class_definitions)
All classes given are redefined according to the definitions supplied. This function is used to replace the definition of a class with a new definition, as might be needed in fix-and-continue debugging. Where the existing class file bytes are to be transformed, for example in bytecode instrumentation, RetransformClasses should be used.

Redefinition can cause new versions of methods to be installed. Old method versions may become obsolete The new method version will be used on new invokes. If a method has active stack frames, those active frames continue to run the bytecodes of the original method version. If resetting of stack frames is desired, use PopFrame to pop frames with obsolete method versions.

This function does not cause any initialization except that which would occur under the customary JVM semantics. In other words, redefining a class does not cause its initializers to be run. The values of static fields will remain as they were prior to the call.

Threads need not be suspended.

All breakpoints in the class are cleared.

All attributes are updated.

Instances of the redefined class are not affected -- fields retain their previous values. Tags on the instances are also unaffected.

In response to this call, the JVM TI event Class File Load Hook will be sent (if enabled), but no other JVM TI events will be sent.

The redefinition may change method bodies, the constant pool and attributes. The redefinition must not add, remove or rename fields or methods, change the signatures of methods, change modifiers, or change inheritance. These restrictions may be lifted in future versions. See the error return description below for information on error codes returned if an unsupported redefinition is attempted. The class file bytes are not verified or installed until they have passed through the chain of ClassFileLoadHook events, thus the returned error code reflects the result of the transformations applied to the bytes passed into class_definitions. If any error code is returned other than JVMTI_ERROR_NONE, none of the classes to be redefined will have a new definition installed. When this function returns (with the error code of JVMTI_ERROR_NONE) all of the classes to be redefined will have their new definitions installed.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 87 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_redefine_classes | Can redefine classes with RedefineClasses.
Optional Features
can_redefine_any_class | Can modify (retransform or redefine) any non-primitive non-array class. See IsModifiableClass.

jvmtiClassDefinition - Class redefinition description
Field | Type | Description
klass | jclass | Class object for this class
class_byte_count | jint | Number of bytes defining class (below)
class_bytes | const unsigned char* | Bytes defining class (in the Class File Format of the Java Virtual Machine Specification)

Parameters
Name | Type | Description
class_count | jint | The number of classes specified in class_definitions
class_definitions | const jvmtiClassDefinition* | The array of new class definitions Agent passes in an array of class_count elements of jvmtiClassDefinition.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_redefine_classes. Use AddCapabilities.
JVMTI_ERROR_NULL_POINTER | One of class_bytes is NULL.
JVMTI_ERROR_UNMODIFIABLE_CLASS | An element of class_definitions cannot be modified. See IsModifiableClass.
JVMTI_ERROR_INVALID_CLASS | An element of class_definitions is not a valid class.
JVMTI_ERROR_UNSUPPORTED_VERSION | A new class file has a version number not supported by this VM.
JVMTI_ERROR_INVALID_CLASS_FORMAT | A new class file is malformed (The VM would return a ClassFormatError).
JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION | The new class file definitions would lead to a circular definition (the VM would return a ClassCircularityError).
JVMTI_ERROR_FAILS_VERIFICATION | The class bytes fail verification.
JVMTI_ERROR_NAMES_DONT_MATCH | The class name defined in a new class file is different from the name in the old class object.
JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED | A new class file would require adding a method.
JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED | A new class version changes a field.
JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED | A direct superclass is different for a new class version, or the set of directly implemented interfaces is different.
JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED | A new class version does not declare a method declared in the old class version.
JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED | A new class version has different modifiers.
JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED | A method in the new class version has different modifiers than its counterpart in the old class version.
JVMTI_ERROR_ILLEGAL_ARGUMENT | class_count is less than 0.
JVMTI_ERROR_NULL_POINTER | class_definitions is NULL.

Object

Object functions:
  • Get Object Size
  • Get Object Hash Code
  • Get Object Monitor Usage
Object types:
  • jvmtiMonitorUsage - Object monitor usage information

Get Object Size

jvmtiError
GetObjectSize(jvmtiEnv* env,
            jobject object,
            jlong* size_ptr)
For the object indicated by object, return via size_ptr the size of the object. This size is an implementation-specific approximation of the amount of storage consumed by this object. It may include some or all of the object's overhead, and thus is useful for comparison within an implementation but not between implementations. The estimate may change during a single invocation of the JVM.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 154 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
object | jobject | The object to query.
size_ptr | jlong* | On return, points to the object's size in bytes. Agent passes a pointer to a jlong. On return, the jlong has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_OBJECT | object is not an object.
JVMTI_ERROR_NULL_POINTER | size_ptr is NULL.

Get Object Hash Code

jvmtiError
GetObjectHashCode(jvmtiEnv* env,
            jobject object,
            jint* hash_code_ptr)
For the object indicated by object, return via hash_code_ptr a hash code. This hash code could be used to maintain a hash table of object references, however, on some implementations this can cause significant performance impacts--in most cases tags will be a more efficient means of associating information with objects. This function guarantees the same hash code value for a particular object throughout its life

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 58 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
object | jobject | The object to query.
hash_code_ptr | jint* | On return, points to the object's hash code. Agent passes a pointer to a jint. On return, the jint has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_OBJECT | object is not an object.
JVMTI_ERROR_NULL_POINTER | hash_code_ptr is NULL.

Get Object Monitor Usage

typedef struct {
    jthread owner;
    jint entry_count;
    jint waiter_count;
    jthread* waiters;
    jint notify_waiter_count;
    jthread* notify_waiters;
} jvmtiMonitorUsage;
jvmtiError
GetObjectMonitorUsage(jvmtiEnv* env,
            jobject object,
            jvmtiMonitorUsage* info_ptr)
Get information about the object's monitor. The fields of the jvmtiMonitorUsage structure are filled in with information about usage of the monitor.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 59 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_get_monitor_info | Can GetObjectMonitorUsage

jvmtiMonitorUsage - Object monitor usage information
Field | Type | Description
owner | jthread | The thread owning this monitor, or NULL if unused
entry_count | jint | The number of times the owning thread has entered the monitor
waiter_count | jint | The number of threads waiting to own this monitor
waiters | jthread* | The waiter_count waiting threads
notify_waiter_count | jint | The number of threads waiting to be notified by this monitor
notify_waiters | jthread* | The notify_waiter_count threads waiting to be notified

Parameters
Name | Type | Description
object | jobject | The object to query.
info_ptr | jvmtiMonitorUsage* | On return, filled with monitor information for the specified object. Agent passes a pointer to a jvmtiMonitorUsage. On return, the jvmtiMonitorUsage has been set. The object returned in the field owner of jvmtiMonitorUsage is a JNI local reference and must be managed. The pointer returned in the field waiters of jvmtiMonitorUsage is a newly allocated array. The array should be freed with Deallocate. The objects returned in the field waiters of jvmtiMonitorUsage are JNI local references and must be managed. The pointer returned in the field notify_waiters of jvmtiMonitorUsage is a newly allocated array. The array should be freed with Deallocate. The objects returned in the field notify_waiters of jvmtiMonitorUsage are JNI local references and must be managed.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_get_monitor_info. Use AddCapabilities.
JVMTI_ERROR_INVALID_OBJECT | object is not an object.
JVMTI_ERROR_NULL_POINTER | info_ptr is NULL.

Field

Field functions:
  • Get Field Name (and Signature)
  • Get Field Declaring Class
  • Get Field Modifiers
  • Is Field Synthetic

Get Field Name (and Signature)

jvmtiError
GetFieldName(jvmtiEnv* env,
            jclass klass,
            jfieldID field,
            char** name_ptr,
            char** signature_ptr,
            char** generic_ptr)
For the field indicated by klass and field, return the field name via name_ptr and field signature via signature_ptr.

Field signatures are defined in the JNI Specification and are referred to as field descriptors in the Java Virtual Machine Specification.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 60 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
klass | jclass | The class of the field to query.
field | jfieldID | The field to query.
name_ptr | char ** | On return, points to the field name, encoded as a modified UTF-8 string. Agent passes a pointer to a char*. On return, the char* points to a newly allocated array. The array should be freed with Deallocate. If name_ptr is NULL, the name is not returned.
signature_ptr | char ** | On return, points to the field signature, encoded as a modified UTF-8 string. Agent passes a pointer to a char*. On return, the char* points to a newly allocated array. The array should be freed with Deallocate. If signature_ptr is NULL, the signature is not returned.
generic_ptr | char ** | On return, points to the generic signature of the field, encoded as a modified UTF-8 string. If there is no generic signature attribute for the field, then, on return, points to NULL. Agent passes a pointer to a char*. On return, the char* points to a newly allocated array. The array should be freed with Deallocate. If generic_ptr is NULL, the generic signature is not returned.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_INVALID_FIELDID | field is not a jfieldID.

Get Field Declaring Class

jvmtiError
GetFieldDeclaringClass(jvmtiEnv* env,
            jclass klass,
            jfieldID field,
            jclass* declaring_class_ptr)
For the field indicated by klass and field return the class that defined it via declaring_class_ptr. The declaring class will either be klass, a superclass, or an implemented interface.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 61 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
klass | jclass | The class to query.
field | jfieldID | The field to query.
declaring_class_ptr | jclass* | On return, points to the declaring class Agent passes a pointer to a jclass. On return, the jclass has been set. The object returned by declaring_class_ptr is a JNI local reference and must be managed.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_INVALID_FIELDID | field is not a jfieldID.
JVMTI_ERROR_NULL_POINTER | declaring_class_ptr is NULL.

Get Field Modifiers

jvmtiError
GetFieldModifiers(jvmtiEnv* env,
            jclass klass,
            jfieldID field,
            jint* modifiers_ptr)
For the field indicated by klass and field return the access flags via modifiers_ptr. Access flags are defined in the Class File Format chapter of the Java Virtual Machine Specification.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 62 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
klass | jclass | The class to query.
field | jfieldID | The field to query.
modifiers_ptr | jint* | On return, points to the access flags. Agent passes a pointer to a jint. On return, the jint has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_INVALID_FIELDID | field is not a jfieldID.
JVMTI_ERROR_NULL_POINTER | modifiers_ptr is NULL.

Is Field Synthetic

jvmtiError
IsFieldSynthetic(jvmtiEnv* env,
            jclass klass,
            jfieldID field,
            jboolean* is_synthetic_ptr)
For the field indicated by klass and field, return a value indicating whether the field is synthetic via is_synthetic_ptr. Synthetic fields are generated by the compiler but not present in the original source code.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 63 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_get_synthetic_attribute | Can test if a field or method is synthetic - IsFieldSynthetic and IsMethodSynthetic

Parameters
Name | Type | Description
klass | jclass | The class of the field to query.
field | jfieldID | The field to query.
is_synthetic_ptr | jboolean* | On return, points to the boolean result of this function. Agent passes a pointer to a jboolean. On return, the jboolean has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_get_synthetic_attribute. Use AddCapabilities.
JVMTI_ERROR_INVALID_CLASS | klass is not a class object or the class has been unloaded.
JVMTI_ERROR_INVALID_FIELDID | field is not a jfieldID.
JVMTI_ERROR_NULL_POINTER | is_synthetic_ptr is NULL.

Method

Method functions:
  • Get Method Name (and Signature)
  • Get Method Declaring Class
  • Get Method Modifiers
  • Get Max Locals
  • Get Arguments Size
  • Get Line Number Table
  • Get Method Location
  • Get Local Variable Table
  • Get Bytecodes
  • Is Method Native
  • Is Method Synthetic
  • Is Method Obsolete
  • Set Native Method Prefix
  • Set Native Method Prefixes
Method types:
  • jvmtiLineNumberEntry - Line number table entry
  • jvmtiLocalVariableEntry - Local variable table entry
These functions provide information about a method (represented as a jmethodID) and set how methods are processed.

Obsolete Methods

The functions RetransformClasses and RedefineClasses can cause new versions of methods to be installed. An original version of a method is considered equivalent to the new version if:
  • their bytecodes are the same except for indices into the constant pool and
  • the referenced constants are equal.
An original method version which is not equivalent to the new method version is called obsolete and is assigned a new method ID; the original method ID now refers to the new method version. A method ID can be tested for obsolescence with IsMethodObsolete.

Get Method Name (and Signature)

jvmtiError
GetMethodName(jvmtiEnv* env,
            jmethodID method,
            char** name_ptr,
            char** signature_ptr,
            char** generic_ptr)
For the method indicated by method, return the method name via name_ptr and method signature via signature_ptr.

Method signatures are defined in the JNI Specification and are referred to as method descriptors in the Java Virtual Machine Specification. Note this is different than method signatures as defined in the Java Language Specification.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 64 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
method | jmethodID | The method to query.
name_ptr | char ** | On return, points to the method name, encoded as a modified UTF-8 string. Agent passes a pointer to a char*. On return, the char* points to a newly allocated array. The array should be freed with Deallocate. If name_ptr is NULL, the name is not returned.
signature_ptr | char ** | On return, points to the method signature, encoded as a modified UTF-8 string. Agent passes a pointer to a char*. On return, the char* points to a newly allocated array. The array should be freed with Deallocate. If signature_ptr is NULL, the signature is not returned.
generic_ptr | char ** | On return, points to the generic signature of the method, encoded as a modified UTF-8 string. If there is no generic signature attribute for the method, then, on return, points to NULL. Agent passes a pointer to a char*. On return, the char* points to a newly allocated array. The array should be freed with Deallocate. If generic_ptr is NULL, the generic signature is not returned.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_METHODID | method is not a jmethodID.

Get Method Declaring Class

jvmtiError
GetMethodDeclaringClass(jvmtiEnv* env,
            jmethodID method,
            jclass* declaring_class_ptr)
For the method indicated by method, return the class that defined it via declaring_class_ptr.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 65 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
method | jmethodID | The method to query.
declaring_class_ptr | jclass* | On return, points to the declaring class Agent passes a pointer to a jclass. On return, the jclass has been set. The object returned by declaring_class_ptr is a JNI local reference and must be managed.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_METHODID | method is not a jmethodID.
JVMTI_ERROR_NULL_POINTER | declaring_class_ptr is NULL.

Get Method Modifiers

jvmtiError
GetMethodModifiers(jvmtiEnv* env,
            jmethodID method,
            jint* modifiers_ptr)
For the method indicated by method, return the access flags via modifiers_ptr. Access flags are defined in the Class File Format chapter of the Java Virtual Machine Specification.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 66 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
method | jmethodID | The method to query.
modifiers_ptr | jint* | On return, points to the access flags. Agent passes a pointer to a jint. On return, the jint has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_METHODID | method is not a jmethodID.
JVMTI_ERROR_NULL_POINTER | modifiers_ptr is NULL.

Get Max Locals

jvmtiError
GetMaxLocals(jvmtiEnv* env,
            jmethodID method,
            jint* max_ptr)
For the method indicated by method, return the number of local variable slots used by the method, including the local variables used to pass parameters to the method on its invocation.

See max_locals in the Code Attribute section of the Java Virtual Machine Specification.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 68 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
method | jmethodID | The method to query.
max_ptr | jint* | On return, points to the maximum number of local slots Agent passes a pointer to a jint. On return, the jint has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_METHODID | method is not a jmethodID.
JVMTI_ERROR_NATIVE_METHOD | method is a native method.
JVMTI_ERROR_NULL_POINTER | max_ptr is NULL.

Get Arguments Size

jvmtiError
GetArgumentsSize(jvmtiEnv* env,
            jmethodID method,
            jint* size_ptr)
For the method indicated by method, return via max_ptr the number of local variable slots used by the method's arguments. Note that two-word arguments use two slots.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 69 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
method | jmethodID | The method to query.
size_ptr | jint* | On return, points to the number of argument slots Agent passes a pointer to a jint. On return, the jint has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_METHODID | method is not a jmethodID.
JVMTI_ERROR_NATIVE_METHOD | method is a native method.
JVMTI_ERROR_NULL_POINTER | size_ptr is NULL.

Get Line Number Table

typedef struct {
    jlocation start_location;
    jint line_number;
} jvmtiLineNumberEntry;
jvmtiError
GetLineNumberTable(jvmtiEnv* env,
            jmethodID method,
            jint* entry_count_ptr,
            jvmtiLineNumberEntry** table_ptr)
For the method indicated by method, return a table of source line number entries. The size of the table is returned via entry_count_ptr and the table itself is returned via table_ptr.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 70 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_get_line_numbers | Can get the line number table of a method

jvmtiLineNumberEntry - Line number table entry
Field | Type | Description
start_location | jlocation | the jlocation where the line begins
line_number | jint | the line number

Parameters
Name | Type | Description
method | jmethodID | The method to query.
entry_count_ptr | jint* | On return, points to the number of entries in the table Agent passes a pointer to a jint. On return, the jint has been set.
table_ptr | jvmtiLineNumberEntry** | On return, points to the line number table pointer. Agent passes a pointer to a jvmtiLineNumberEntry*. On return, the jvmtiLineNumberEntry* points to a newly allocated array of size *entry_count_ptr. The array should be freed with Deallocate.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_get_line_numbers. Use AddCapabilities.
JVMTI_ERROR_ABSENT_INFORMATION | Class information does not include line numbers.
JVMTI_ERROR_INVALID_METHODID | method is not a jmethodID.
JVMTI_ERROR_NATIVE_METHOD | method is a native method.
JVMTI_ERROR_NULL_POINTER | entry_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | table_ptr is NULL.

Get Method Location

jvmtiError
GetMethodLocation(jvmtiEnv* env,
            jmethodID method,
            jlocation* start_location_ptr,
            jlocation* end_location_ptr)
For the method indicated by method, return the beginning and ending addresses through start_location_ptr and end_location_ptr. In a conventional byte code indexing scheme, start_location_ptr will always point to zero and end_location_ptr will always point to the byte code count minus one.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 71 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
method | jmethodID | The method to query.
start_location_ptr | jlocation* | On return, points to the first location, or -1 if location information is not available. If the information is available and GetJLocationFormat returns JVMTI_JLOCATION_JVMBCI then this will always be zero. Agent passes a pointer to a jlocation. On return, the jlocation has been set.
end_location_ptr | jlocation* | On return, points to the last location, or -1 if location information is not available. Agent passes a pointer to a jlocation. On return, the jlocation has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_ABSENT_INFORMATION | Class information does not include method sizes.
JVMTI_ERROR_INVALID_METHODID | method is not a jmethodID.
JVMTI_ERROR_NATIVE_METHOD | method is a native method.
JVMTI_ERROR_NULL_POINTER | start_location_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | end_location_ptr is NULL.

Get Local Variable Table

typedef struct {
    jlocation start_location;
    jint length;
    char* name;
    char* signature;
    char* generic_signature;
    jint slot;
} jvmtiLocalVariableEntry;
jvmtiError
GetLocalVariableTable(jvmtiEnv* env,
            jmethodID method,
            jint* entry_count_ptr,
            jvmtiLocalVariableEntry** table_ptr)
Return local variable information.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 72 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_access_local_variables | Can set and get local variables

jvmtiLocalVariableEntry - Local variable table entry
Field | Type | Description
start_location | jlocation | The code array index where the local variable is first valid (that is, where it must have a value).
length | jint | The length of the valid section for this local variable. The last code array index where the local variable is valid is start_location + length.
name | char* | The local variable name, encoded as a modified UTF-8 string.
signature | char* | The local variable's type signature, encoded as a modified UTF-8 string. The signature format is the same as that defined in Field Descriptors section of the Java Virtual Machine Specification
generic_signature | char* | The local variable's generic signature, encoded as a modified UTF-8 string. The value of this field will be NULL for any local variable which does not have a generic type.
slot | jint | The local variable's slot. See Local Variables.

Parameters
Name | Type | Description
method | jmethodID | The method to query.
entry_count_ptr | jint* | On return, points to the number of entries in the table Agent passes a pointer to a jint. On return, the jint has been set.
table_ptr | jvmtiLocalVariableEntry** | On return, points to an array of local variable table entries. Agent passes a pointer to a jvmtiLocalVariableEntry*. On return, the jvmtiLocalVariableEntry* points to a newly allocated array of size *entry_count_ptr. The array should be freed with Deallocate. The pointers returned in the field name of jvmtiLocalVariableEntry are newly allocated arrays. The arrays should be freed with Deallocate. The pointers returned in the field signature of jvmtiLocalVariableEntry are newly allocated arrays. The arrays should be freed with Deallocate. The pointers returned in the field generic_signature of jvmtiLocalVariableEntry are newly allocated arrays. The arrays should be freed with Deallocate.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_access_local_variables. Use AddCapabilities.
JVMTI_ERROR_ABSENT_INFORMATION | Class information does not include local variable information.
JVMTI_ERROR_INVALID_METHODID | method is not a jmethodID.
JVMTI_ERROR_NATIVE_METHOD | method is a native method.
JVMTI_ERROR_NULL_POINTER | entry_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | table_ptr is NULL.

Get Bytecodes

jvmtiError
GetBytecodes(jvmtiEnv* env,
            jmethodID method,
            jint* bytecode_count_ptr,
            unsigned char** bytecodes_ptr)
For the method indicated by method, return the byte codes that implement the method. The number of bytecodes is returned via bytecode_count_ptr. The byte codes themselves are returned via bytecodes_ptr.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 75 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_get_bytecodes | Can get bytecodes of a method GetBytecodes

Parameters
Name | Type | Description
method | jmethodID | The method to query.
bytecode_count_ptr | jint* | On return, points to the length of the byte code array Agent passes a pointer to a jint. On return, the jint has been set.
bytecodes_ptr | unsigned char** | On return, points to the pointer to the byte code array Agent passes a pointer to a unsigned char*. On return, the unsigned char* points to a newly allocated array of size *bytecode_count_ptr. The array should be freed with Deallocate.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_get_bytecodes. Use AddCapabilities.
JVMTI_ERROR_INVALID_METHODID | method is not a jmethodID.
JVMTI_ERROR_NATIVE_METHOD | method is a native method.
JVMTI_ERROR_NULL_POINTER | bytecode_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | bytecodes_ptr is NULL.

Is Method Native

jvmtiError
IsMethodNative(jvmtiEnv* env,
            jmethodID method,
            jboolean* is_native_ptr)
For the method indicated by method, return a value indicating whether the method is native via is_native_ptr

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 76 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
method | jmethodID | The method to query.
is_native_ptr | jboolean* | On return, points to the boolean result of this function. Agent passes a pointer to a jboolean. On return, the jboolean has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_METHODID | method is not a jmethodID.
JVMTI_ERROR_NULL_POINTER | is_native_ptr is NULL.

Is Method Synthetic

jvmtiError
IsMethodSynthetic(jvmtiEnv* env,
            jmethodID method,
            jboolean* is_synthetic_ptr)
For the method indicated by method, return a value indicating whether the method is synthetic via is_synthetic_ptr. Synthetic methods are generated by the compiler but not present in the original source code.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 77 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_get_synthetic_attribute | Can test if a field or method is synthetic - IsFieldSynthetic and IsMethodSynthetic

Parameters
Name | Type | Description
method | jmethodID | The method to query.
is_synthetic_ptr | jboolean* | On return, points to the boolean result of this function. Agent passes a pointer to a jboolean. On return, the jboolean has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_get_synthetic_attribute. Use AddCapabilities.
JVMTI_ERROR_INVALID_METHODID | method is not a jmethodID.
JVMTI_ERROR_NULL_POINTER | is_synthetic_ptr is NULL.

Is Method Obsolete

jvmtiError
IsMethodObsolete(jvmtiEnv* env,
            jmethodID method,
            jboolean* is_obsolete_ptr)
Determine if a method ID refers to an obsolete method version.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 91 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
method | jmethodID | The method ID to query.
is_obsolete_ptr | jboolean* | On return, points to the boolean result of this function. Agent passes a pointer to a jboolean. On return, the jboolean has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_METHODID | method is not a jmethodID.
JVMTI_ERROR_NULL_POINTER | is_obsolete_ptr is NULL.

Set Native Method Prefix

jvmtiError
SetNativeMethodPrefix(jvmtiEnv* env,
            const char* prefix)
This function modifies the failure handling of native method resolution by allowing retry with a prefix applied to the name. When used with the ClassFileLoadHook event, it enables native methods to be instrumented.

Since native methods cannot be directly instrumented (they have no bytecodes), they must be wrapped with a non-native method which can be instrumented. For example, if we had:
native boolean foo(int x);

We could transform the class file (with the ClassFileLoadHook event) so that this becomes:
boolean foo(int x) {
  ... record entry to foo ...
  return wrapped_foo(x);
}

native boolean wrapped_foo(int x);

Where foo becomes a wrapper for the actual native method with the appended prefix "wrapped_". Note that "wrapped_" would be a poor choice of prefix since it might conceivably form the name of an existing method thus something like "$$$MyAgentWrapped$$$_" would be better but would make these examples less readable.

The wrapper will allow data to be collected on the native method call, but now the problem becomes linking up the wrapped method with the native implementation. That is, the method wrapped_foo needs to be resolved to the native implementation of foo, which might be:
Java_somePackage_someClass_foo(JNIEnv* env, jint x)

This function allows the prefix to be specified and the proper resolution to occur. Specifically, when the standard resolution fails, the resolution is retried taking the prefix into consideration. There are two ways that resolution occurs, explicit resolution with the JNI function RegisterNatives and the normal automatic resolution. For RegisterNatives, the VM will attempt this association:
method(foo) -> nativeImplementation(foo)

When this fails, the resolution will be retried with the specified prefix prepended to the method name, yielding the correct resolution:
method(wrapped_foo) -> nativeImplementation(foo)

For automatic resolution, the VM will attempt:
method(wrapped_foo) -> nativeImplementation(wrapped_foo)

When this fails, the resolution will be retried with the specified prefix deleted from the implementation name, yielding the correct resolution:
method(wrapped_foo) -> nativeImplementation(foo)

Note that since the prefix is only used when standard resolution fails, native methods can be wrapped selectively.

Since each JVM TI environment is independent and can do its own transformation of the bytecodes, more than one layer of wrappers may be applied. Thus each environment needs its own prefix. Since transformations are applied in order, the prefixes, if applied, will be applied in the same order. The order of transformation application is described in the ClassFileLoadHook event. Thus if three environments applied wrappers, foo might become $env3_$env2_$env1_foo. But if, say, the second environment did not apply a wrapper to foo it would be just $env3_$env1_foo. To be able to efficiently determine the sequence of prefixes, an intermediate prefix is only applied if its non-native wrapper exists. Thus, in the last example, even though $env1_foo is not a native method, the $env1_ prefix is applied since $env1_foo exists.

Since the prefixes are used at resolution time and since resolution may be arbitrarily delayed, a native method prefix must remain set as long as there are corresponding prefixed native methods.

Phase | Callback Safe | Position | Since
may be called during any phase | No | 73 | 1.1

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_set_native_method_prefix | Can set prefix to be applied when native method cannot be resolved - SetNativeMethodPrefix and SetNativeMethodPrefixes

Parameters
Name | Type | Description
prefix | const char * | The prefix to apply, encoded as a modified UTF-8 string. Agent passes in an array of char. If prefix is NULL, any existing prefix in this environment is cancelled .

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_set_native_method_prefix. Use AddCapabilities.

Set Native Method Prefixes

jvmtiError
SetNativeMethodPrefixes(jvmtiEnv* env,
            jint prefix_count,
            char** prefixes)
For a normal agent, SetNativeMethodPrefix will provide all needed native method prefixing. For a meta-agent that performs multiple independent class file transformations (for example as a proxy for another layer of agents) this function allows each transformation to have its own prefix. The prefixes are applied in the order supplied and are processed in the same manor as described for the application of prefixes from multiple JVM TI environments in SetNativeMethodPrefix.

Any previous prefixes are replaced. Thus, calling this function with a prefix_count of 0 disables prefixing in this environment.

SetNativeMethodPrefix and this function are the two ways to set the prefixes. Calling SetNativeMethodPrefix with a prefix is the same as calling this function with prefix_count of 1. Calling SetNativeMethodPrefix with NULL is the same as calling this function with prefix_count of 0.

Phase | Callback Safe | Position | Since
may be called during any phase | No | 74 | 1.1

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_set_native_method_prefix | Can set prefix to be applied when native method cannot be resolved - SetNativeMethodPrefix and SetNativeMethodPrefixes

Parameters
Name | Type | Description
prefix_count | jint | The number of prefixes to apply.
prefixes | char ** | The prefixes to apply for this environment, each encoded as a modified UTF-8 string.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_set_native_method_prefix. Use AddCapabilities.
JVMTI_ERROR_ILLEGAL_ARGUMENT | prefix_count is less than 0.
JVMTI_ERROR_NULL_POINTER | prefixes is NULL.

Raw Monitor

Raw Monitor functions:
  • Create Raw Monitor
  • Destroy Raw Monitor
  • Raw Monitor Enter
  • Raw Monitor Exit
  • Raw Monitor Wait
  • Raw Monitor Notify
  • Raw Monitor Notify All

Create Raw Monitor

jvmtiError
CreateRawMonitor(jvmtiEnv* env,
            const char* name,
            jrawMonitorID* monitor_ptr)
Create a raw monitor.

Phase | Callback Safe | Position | Since
may only be called during the OnLoad or the live phase | This function may be called from the callbacks to the Heap iteration functions, or from the event handlers for the GarbageCollectionStart, GarbageCollectionFinish, and ObjectFree events. | 31 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
name | const char* | A name to identify the monitor, encoded as a modified UTF-8 string. Agent passes in an array of char.
monitor_ptr | jrawMonitorID* | On return, points to the created monitor. Agent passes a pointer to a jrawMonitorID. On return, the jrawMonitorID has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | name is NULL.
JVMTI_ERROR_NULL_POINTER | monitor_ptr is NULL.

Destroy Raw Monitor

jvmtiError
DestroyRawMonitor(jvmtiEnv* env,
            jrawMonitorID monitor)
Destroy the raw monitor. If the monitor being destroyed has been entered by this thread, it will be exited before it is destroyed. If the monitor being destroyed has been entered by another thread, an error will be returned and the monitor will not be destroyed.

Phase | Callback Safe | Position | Since
may only be called during the OnLoad or the live phase | This function may be called from the callbacks to the Heap iteration functions, or from the event handlers for the GarbageCollectionStart, GarbageCollectionFinish, and ObjectFree events. | 32 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
monitor | jrawMonitorID | The monitor

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NOT_MONITOR_OWNER | Not monitor owner
JVMTI_ERROR_INVALID_MONITOR | monitor is not a jrawMonitorID.

Raw Monitor Enter

jvmtiError
RawMonitorEnter(jvmtiEnv* env,
            jrawMonitorID monitor)
Gain exclusive ownership of a raw monitor. The same thread may enter a monitor more then once. The thread must exit the monitor the same number of times as it is entered. If a monitor is entered during OnLoad (before attached threads exist) and has not exited when attached threads come into existence, the enter is considered to have occurred on the main thread.

Phase | Callback Safe | Position | Since
may be called during any phase | This function may be called from the callbacks to the Heap iteration functions, or from the event handlers for the GarbageCollectionStart, GarbageCollectionFinish, and ObjectFree events. | 33 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
monitor | jrawMonitorID | The monitor

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_MONITOR | monitor is not a jrawMonitorID.

Raw Monitor Exit

jvmtiError
RawMonitorExit(jvmtiEnv* env,
            jrawMonitorID monitor)
Release exclusive ownership of a raw monitor.

Phase | Callback Safe | Position | Since
may be called during any phase | This function may be called from the callbacks to the Heap iteration functions, or from the event handlers for the GarbageCollectionStart, GarbageCollectionFinish, and ObjectFree events. | 34 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
monitor | jrawMonitorID | The monitor

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NOT_MONITOR_OWNER | Not monitor owner
JVMTI_ERROR_INVALID_MONITOR | monitor is not a jrawMonitorID.

Raw Monitor Wait

jvmtiError
RawMonitorWait(jvmtiEnv* env,
            jrawMonitorID monitor,
            jlong millis)
Wait for notification of the raw monitor.

Causes the current thread to wait until either another thread calls RawMonitorNotify or RawMonitorNotifyAll for the specified raw monitor, or the specified timeout has elapsed.

Phase | Callback Safe | Position | Since
may be called during any phase | This function may be called from the callbacks to the Heap iteration functions, or from the event handlers for the GarbageCollectionStart, GarbageCollectionFinish, and ObjectFree events. | 35 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
monitor | jrawMonitorID | The monitor
millis | jlong | The timeout, in milliseconds. If the timeout is zero, then real time is not taken into consideration and the thread simply waits until notified.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NOT_MONITOR_OWNER | Not monitor owner
JVMTI_ERROR_INTERRUPT | Wait was interrupted, try again
JVMTI_ERROR_INVALID_MONITOR | monitor is not a jrawMonitorID.

Raw Monitor Notify

jvmtiError
RawMonitorNotify(jvmtiEnv* env,
            jrawMonitorID monitor)
Notify a single thread waiting on the raw monitor.

Phase | Callback Safe | Position | Since
may be called during any phase | This function may be called from the callbacks to the Heap iteration functions, or from the event handlers for the GarbageCollectionStart, GarbageCollectionFinish, and ObjectFree events. | 36 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
monitor | jrawMonitorID | The monitor

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NOT_MONITOR_OWNER | Not monitor owner
JVMTI_ERROR_INVALID_MONITOR | monitor is not a jrawMonitorID.

Raw Monitor Notify All

jvmtiError
RawMonitorNotifyAll(jvmtiEnv* env,
            jrawMonitorID monitor)
Notify all threads waiting on the raw monitor.

Phase | Callback Safe | Position | Since
may be called during any phase | This function may be called from the callbacks to the Heap iteration functions, or from the event handlers for the GarbageCollectionStart, GarbageCollectionFinish, and ObjectFree events. | 37 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
monitor | jrawMonitorID | The monitor

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NOT_MONITOR_OWNER | Not monitor owner
JVMTI_ERROR_INVALID_MONITOR | monitor is not a jrawMonitorID.

JNI Function Interception

JNI Function Interception functions:
  • Set JNI Function Table
  • Get JNI Function Table
Provides the ability to intercept and resend Java Native Interface (JNI) function calls by manipulating the JNI function table. See JNI Functions in the Java Native Interface Specification.

The following example illustrates intercepting the NewGlobalRef JNI call in order to count reference creation.
JNIEnv original_jni_Functions;
JNIEnv redirected_jni_Functions;
int my_global_ref_count = 0;

jobject
MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) {
   ++my_global_ref_count;
   return originalJNIFunctions->NewGlobalRef(env, lobj);
}

void
myInit() {
   jvmtiError err;

   err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &original_jni_Functions);
   if (err != JVMTI_ERROR_NONE) {
      die();
   }
   err = (*jvmti_env)->GetJNIFunctionTable(jvmti_env, &redirected_jni_Functions);
   if (err != JVMTI_ERROR_NONE) {
      die();
   }
   redirectedJNIFunctions->NewGlobalRef = MyNewGlobalRef;
      err = (*jvmti_env)->SetJNIFunctionTable(jvmti_env, redirected_jni_Functions);
   if (err != JVMTI_ERROR_NONE) {
      die();
   }
}
Sometime after myInit is called the user's JNI code is executed which makes the call to create a new global reference. Instead of going to the normal JNI implementation the call goes to myNewGlobalRef. Note that a copy of the original function table is kept so that the normal JNI function can be called after the data is collected. Note also that any JNI functions which are not overwritten will behave normally.

Set JNI Function Table

jvmtiError
SetJNIFunctionTable(jvmtiEnv* env,
            const jniNativeInterface* function_table)
Set the JNI function table in all current and future JNI environments. As a result, all future JNI calls are directed to the specified functions. Use GetJNIFunctionTable to get the function table to pass to this function. For this function to take effect the the updated table entries must be used by the JNI clients. Since the table is defined const some compilers may optimize away the access to the table, thus preventing this function from taking effect. The table is copied--changes to the local copy of the table have no effect. This function affects only the function table, all other aspects of the environment are unaffected. See the examples above.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 120 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
function_table | const jniNativeInterface * | Points to the new JNI function table. Agent passes in a pointer to jniNativeInterface.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | function_table is NULL.

Get JNI Function Table

jvmtiError
GetJNIFunctionTable(jvmtiEnv* env,
            jniNativeInterface** function_table)
Get the JNI function table. The JNI function table is copied into allocated memory. If SetJNIFunctionTable has been called, the modified (not the original) function table is returned. Only the function table is copied, no other aspects of the environment are copied. See the examples above.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | No | 121 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
function_table | jniNativeInterface ** | On return, *function_table points a newly allocated copy of the JNI function table. Agent passes a pointer to a jniNativeInterface*. On return, the jniNativeInterface* points to a newly allocated array. The array should be freed with Deallocate.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | function_table is NULL.

Event Management

Event Management functions:
  • Set Event Callbacks
  • Set Event Notification Mode
  • Generate Events
Event Management types:
  • jvmtiEventMode - Event Enable/Disable

Set Event Callbacks

jvmtiError
SetEventCallbacks(jvmtiEnv* env,
            const jvmtiEventCallbacks* callbacks,
            jint size_of_callbacks)
Set the functions to be called for each event. The callbacks are specified by supplying a replacement function table. The function table is copied--changes to the local copy of the table have no effect. This is an atomic action, all callbacks are set at once. No events are sent before this function is called. When an entry is NULL or when the event is beyond size_of_callbacks no event is sent. Details on events are described later in this document. An event must be enabled and have a callback in order to be sent--the order in which this function and SetEventNotificationMode are called does not affect the result.

Phase | Callback Safe | Position | Since
may only be called during the OnLoad or the live phase | No | 122 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
callbacks | const jvmtiEventCallbacks * | The new event callbacks. Agent passes in a pointer to jvmtiEventCallbacks. If callbacks is NULL, remove the existing callbacks.
size_of_callbacks | jint | sizeof(jvmtiEventCallbacks)--for version compatibility.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_ILLEGAL_ARGUMENT | size_of_callbacks is less than 0.

Set Event Notification Mode

typedef enum {
    JVMTI_ENABLE = 1,
    JVMTI_DISABLE = 0
} jvmtiEventMode;
jvmtiError
SetEventNotificationMode(jvmtiEnv* env,
            jvmtiEventMode mode,
            jvmtiEvent event_type,
            jthread event_thread,
             ...)
Control the generation of events.
Event Enable/Disable (jvmtiEventMode)
Constant | Value | Description
JVMTI_ENABLE | 1 | If mode is JVMTI_ENABLE, the event event_type will be enabled
JVMTI_DISABLE | 0 | If mode is JVMTI_DISABLE, the event event_type will be disabled
If thread is NULL, the event is enabled or disabled globally; otherwise, it is enabled or disabled for a particular thread. An event is generated for a particular thread if it is enabled either at the thread or global levels.

See below for information on specific events.

The following events cannot be controlled at the thread level through this function.
  • VMInit
  • VMStart
  • VMDeath
  • ThreadStart
  • CompiledMethodLoad
  • CompiledMethodUnload
  • DynamicCodeGenerated
  • DataDumpRequest

Initially, no events are enabled at either the thread level or the global level.

Any needed capabilities (see Event Enabling Capabilities below) must be possessed before calling this function.

Details on events are described below.

Phase | Callback Safe | Position | Since
may only be called during the OnLoad or the live phase | No | 2 | 1.0

Capabilities
Required Functionality
Event Enabling Capabilities
Capability | Events
can_generate_field_modification_events | FieldModification
can_generate_field_access_events | FieldAccess
can_generate_single_step_events | SingleStep
can_generate_exception_events | Exception ExceptionCatch
can_generate_frame_pop_events | FramePop
can_generate_breakpoint_events | Breakpoint
can_generate_method_entry_events | MethodEntry
can_generate_method_exit_events | MethodExit
can_generate_compiled_method_load_events | CompiledMethodLoad CompiledMethodUnload
can_generate_monitor_events | MonitorContendedEnter MonitorContendedEntered MonitorWait MonitorWaited
can_generate_vm_object_alloc_events | VMObjectAlloc
can_generate_native_method_bind_events | NativeMethodBind
can_generate_garbage_collection_events | GarbageCollectionStart GarbageCollectionFinish
can_generate_object_free_events | ObjectFree

Parameters
Name | Type | Description
mode | jvmtiEventMode | JVMTI_ENABLE or JVMTI_DISABLE
event_type | jvmtiEvent | the event to control
event_thread | jthread | The thread to control If event_thread is NULL, event is controlled at the global level.
... | ... | for future expansion

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_INVALID_THREAD | event_thread is non-NULL and is not a valid thread.
JVMTI_ERROR_THREAD_NOT_ALIVE | event_thread is non-NULL and is not live (has not been started or is now dead).
JVMTI_ERROR_ILLEGAL_ARGUMENT | thread level control was attempted on events which do not permit thread level control.
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The Required Event Enabling Capability is not possessed.
JVMTI_ERROR_ILLEGAL_ARGUMENT | mode is not a jvmtiEventMode.
JVMTI_ERROR_INVALID_EVENT_TYPE | event_type is not a jvmtiEvent.

Generate Events

jvmtiError
GenerateEvents(jvmtiEnv* env,
            jvmtiEvent event_type)
Generate events to represent the current state of the VM. For example, if event_type is JVMTI_EVENT_COMPILED_METHOD_LOAD, a CompiledMethodLoad event will be sent for each currently compiled method. Methods that were loaded and now have been unloaded are not sent. The history of what events have previously been sent does not effect what events are sent by this function--for example, all currently compiled methods will be sent each time this function is called.

This function is useful when events may have been missed due to the agent attaching after program execution begins; this function generates the missed events.

Attempts to execute Java programming language code or JNI functions may be paused until this function returns - so neither should be called from the thread sending the event. This function returns only after the missed events have been sent, processed and have returned. The event may be sent on a different thread than the thread on which the event occurred. The callback for the event must be set with SetEventCallbacks and the event must be enabled with SetEventNotificationMode or the events will not occur. If the VM no longer has the information to generate some or all of the requested events, the events are simply not sent - no error is returned.

Only the following events are supported:
  • CompiledMethodLoad
  • DynamicCodeGenerated

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 123 | 1.0

Capabilities
Required Functionality
Optional Features
Capability | Effect
can_generate_compiled_method_load_events | Can generate events when a method is compiled or unloaded

Parameters
Name Type Description
event_type jvmtiEvent The type of event to generate. Must be one of these:
  • JVMTI_EVENT_COMPILED_METHOD_LOAD
  • JVMTI_EVENT_DYNAMIC_CODE_GENERATED

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | event_type is JVMTI_EVENT_COMPILED_METHOD_LOAD and can_generate_compiled_method_load_events is false.
JVMTI_ERROR_ILLEGAL_ARGUMENT | event_type is other than JVMTI_EVENT_COMPILED_METHOD_LOAD or JVMTI_EVENT_DYNAMIC_CODE_GENERATED.
JVMTI_ERROR_INVALID_EVENT_TYPE | event_type is not a jvmtiEvent.

Extension Mechanism

Extension Mechanism functions:
  • Get Extension Functions
  • Get Extension Events
  • Set Extension Event Callback
Extension Mechanism function types:
  • Extension Function
  • Extension Event
Extension Mechanism types:
  • jvmtiParamTypes - Extension Function/Event Parameter Types
  • jvmtiParamKind - Extension Function/Event Parameter Kinds
  • jvmtiParamInfo - Extension Function/Event Parameter Info
  • jvmtiExtensionFunctionInfo - Extension Function Info
  • jvmtiExtensionEventInfo - Extension Event Info
These functions allow a JVM TI implementation to provide functions and events beyond those defined in this specification.

Both extension functions and extension events have parameters each of which has a 'type' and 'kind' chosen from the following tables:
Extension Function/Event Parameter Types (jvmtiParamTypes)
Constant | Value | Description
JVMTI_TYPE_JBYTE | 101 | Java programming language primitive type - byte. JNI type jbyte.
JVMTI_TYPE_JCHAR | 102 | Java programming language primitive type - char. JNI type jchar.
JVMTI_TYPE_JSHORT | 103 | Java programming language primitive type - short. JNI type jshort.
JVMTI_TYPE_JINT | 104 | Java programming language primitive type - int. JNI type jint.
JVMTI_TYPE_JLONG | 105 | Java programming language primitive type - long. JNI type jlong.
JVMTI_TYPE_JFLOAT | 106 | Java programming language primitive type - float. JNI type jfloat.
JVMTI_TYPE_JDOUBLE | 107 | Java programming language primitive type - double. JNI type jdouble.
JVMTI_TYPE_JBOOLEAN | 108 | Java programming language primitive type - boolean. JNI type jboolean.
JVMTI_TYPE_JOBJECT | 109 | Java programming language object type - java.lang.Object. JNI type jobject. Returned values are JNI local references and must be managed.
JVMTI_TYPE_JTHREAD | 110 | Java programming language object type - java.lang.Thread. JVM TI type jthread. Returned values are JNI local references and must be managed.
JVMTI_TYPE_JCLASS | 111 | Java programming language object type - java.lang.Class. JNI type jclass. Returned values are JNI local references and must be managed.
JVMTI_TYPE_JVALUE | 112 | Union of all Java programming language primitive and object types - JNI type jvalue. Returned values which represent object types are JNI local references and must be managed.
JVMTI_TYPE_JFIELDID | 113 | Java programming language field identifier - JNI type jfieldID.
JVMTI_TYPE_JMETHODID | 114 | Java programming language method identifier - JNI type jmethodID.
JVMTI_TYPE_CCHAR | 115 | C programming language type - char.
JVMTI_TYPE_CVOID | 116 | C programming language type - void.
JVMTI_TYPE_JNIENV | 117 | JNI environment - JNIEnv. Should be used with the correct jvmtiParamKind to make it a pointer type.
Extension Function/Event Parameter Kinds (jvmtiParamKind)
Constant | Value | Description
JVMTI_KIND_IN | 91 | Ingoing argument - foo.
JVMTI_KIND_IN_PTR | 92 | Ingoing pointer argument - const foo*.
JVMTI_KIND_IN_BUF | 93 | Ingoing array argument - const foo*.
JVMTI_KIND_ALLOC_BUF | 94 | Outgoing allocated array argument - foo**. Free with Deallocate.
JVMTI_KIND_ALLOC_ALLOC_BUF | 95 | Outgoing allocated array of allocated arrays argument - foo***. Free with Deallocate.
JVMTI_KIND_OUT | 96 | Outgoing argument - foo*.
JVMTI_KIND_OUT_BUF | 97 | Outgoing array argument (pre-allocated by agent) - foo*. Do not Deallocate.

Extension Function/Event Parameter Info

typedef struct {
    char* name;
    jvmtiParamKind kind;
    jvmtiParamTypes base_type;
    jboolean null_ok;
} jvmtiParamInfo;
jvmtiParamInfo - Extension Function/Event Parameter Info
Field | Type | Description
name | char* | The parameter name, encoded as a modified UTF-8 string
kind | jvmtiParamKind | The kind of the parameter - type modifiers
base_type | jvmtiParamTypes | The base type of the parameter - modified by kind
null_ok | jboolean | Is a NULL argument permitted? Applies only to pointer and object types.

Extension Function

typedef jvmtiError (JNICALL *jvmtiExtensionFunction)
    (jvmtiEnv* jvmti_env,
      ...);
This is the implementation-specific extension function.

Parameters
Name | Type | Description
jvmti_env | jvmtiEnv * | The JVM TI environment is the only fixed parameter for extension functions.
... | ... | The extension function-specific parameters

Get Extension Functions

typedef struct {
    jvmtiExtensionFunction func;
    char* id;
    char* short_description;
    jint param_count;
    jvmtiParamInfo* params;
    jint error_count;
    jvmtiError* errors;
} jvmtiExtensionFunctionInfo;
jvmtiError
GetExtensionFunctions(jvmtiEnv* env,
            jint* extension_count_ptr,
            jvmtiExtensionFunctionInfo** extensions)
Returns the set of extension functions.

Phase | Callback Safe | Position | Since
may only be called during the OnLoad or the live phase | No | 124 | 1.0

Capabilities
Required Functionality

jvmtiExtensionFunctionInfo - Extension Function Info
Field | Type | Description
func | jvmtiExtensionFunction | The actual function to call
id | char* | The identifier for the extension function, encoded as a modified UTF-8 string. Uses package name conventions. For example, com.sun.hotspot.bar
short_description | char* | A one sentence description of the function, encoded as a modified UTF-8 string.
param_count | jint | The number of parameters excluding jvmtiEnv *jvmti_env
params | jvmtiParamInfo * | Array of param_count parameters (jvmtiEnv *jvmti_env excluded)
error_count | jint | The number of possible error returns (excluding universal errors)
errors | jvmtiError * | Array of error_count possible errors

Parameters
Name | Type | Description
extension_count_ptr | jint* | On return, points to the number of extension functions Agent passes a pointer to a jint. On return, the jint has been set.
extensions | jvmtiExtensionFunctionInfo** | Returns an array of extension function info, one per function Agent passes a pointer to a jvmtiExtensionFunctionInfo*. On return, the jvmtiExtensionFunctionInfo* points to a newly allocated array of size *extension_count_ptr. The array should be freed with Deallocate. The pointers returned in the field id of jvmtiExtensionFunctionInfo are newly allocated arrays. The arrays should be freed with Deallocate. The pointers returned in the field short_description of jvmtiExtensionFunctionInfo are newly allocated arrays. The arrays should be freed with Deallocate. The pointers returned in the field params of jvmtiExtensionFunctionInfo are newly allocated arrays. The arrays should be freed with Deallocate. The pointers returned in the field name of jvmtiParamInfo are newly allocated arrays. The arrays should be freed with Deallocate. The pointers returned in the field errors of jvmtiExtensionFunctionInfo are newly allocated arrays. The arrays should be freed with Deallocate.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | extension_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | extensions is NULL.

Get Extension Events

typedef struct {
    jint extension_event_index;
    char* id;
    char* short_description;
    jint param_count;
    jvmtiParamInfo* params;
} jvmtiExtensionEventInfo;
jvmtiError
GetExtensionEvents(jvmtiEnv* env,
            jint* extension_count_ptr,
            jvmtiExtensionEventInfo** extensions)
Returns the set of extension events.

Phase | Callback Safe | Position | Since
may only be called during the OnLoad or the live phase | No | 125 | 1.0

Capabilities
Required Functionality

jvmtiExtensionEventInfo - Extension Event Info
Field | Type | Description
extension_event_index | jint | The identifying index of the event
id | char* | The identifier for the extension event, encoded as a modified UTF-8 string. Uses package name conventions. For example, com.sun.hotspot.bar
short_description | char* | A one sentence description of the event, encoded as a modified UTF-8 string.
param_count | jint | The number of parameters excluding jvmtiEnv *jvmti_env
params | jvmtiParamInfo * | Array of param_count parameters (jvmtiEnv *jvmti_env excluded)

Parameters
Name | Type | Description
extension_count_ptr | jint* | On return, points to the number of extension events Agent passes a pointer to a jint. On return, the jint has been set.
extensions | jvmtiExtensionEventInfo** | Returns an array of extension event info, one per event Agent passes a pointer to a jvmtiExtensionEventInfo*. On return, the jvmtiExtensionEventInfo* points to a newly allocated array of size *extension_count_ptr. The array should be freed with Deallocate. The pointers returned in the field id of jvmtiExtensionEventInfo are newly allocated arrays. The arrays should be freed with Deallocate. The pointers returned in the field short_description of jvmtiExtensionEventInfo are newly allocated arrays. The arrays should be freed with Deallocate. The pointers returned in the field params of jvmtiExtensionEventInfo are newly allocated arrays. The arrays should be freed with Deallocate. The pointers returned in the field name of jvmtiParamInfo are newly allocated arrays. The arrays should be freed with Deallocate.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | extension_count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | extensions is NULL.

Extension Event

typedef void (JNICALL *jvmtiExtensionEvent)
    (jvmtiEnv* jvmti_env,
      ...);
This is the implementation-specific event. The event handler is set with SetExtensionEventCallback.

Event handlers for extension events must be declared varargs to match this definition. Failure to do so could result in calling convention mismatch and undefined behavior on some platforms.

For example, if the jvmtiParamInfo returned by GetExtensionEvents indicates that there is a jint parameter, the event handler should be declared:
    void JNICALL myHandler(jvmtiEnv* jvmti_env, jint myInt, ...)
Note the terminal "..." which indicates varargs.

Parameters
Name | Type | Description
jvmti_env | jvmtiEnv * | The JVM TI environment is the only fixed parameter for extension events.
... | ... | The extension event-specific parameters

Set Extension Event Callback

jvmtiError
SetExtensionEventCallback(jvmtiEnv* env,
            jint extension_event_index,
            jvmtiExtensionEvent callback)
Sets the callback function for an extension event and enables the event. Or, if the callback is NULL, disables the event. Note that unlike standard events, setting the callback and enabling the event are a single operation.

Phase | Callback Safe | Position | Since
may only be called during the OnLoad or the live phase | No | 126 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
extension_event_index | jint | Identifies which callback to set. This index is the extension_event_index field of jvmtiExtensionEventInfo.
callback | jvmtiExtensionEvent | If callback is non-NULL, set callback to be the event callback function and enable the event. If callback is NULL, disable the event.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_ILLEGAL_ARGUMENT | extension_event_index is not an extension_event_index returned by GetExtensionEvents

Capability

Capability functions:
  • Get Potential Capabilities
  • Add Capabilities
  • Relinquish Capabilities
  • Get Capabilities
Capability types:
  • jvmtiCapabilities - The Capabilities Structure
The capabilities functions allow you to change the functionality available to JVM TI--that is, which JVM TI functions can be called, what events can be generated, and what functionality these events and functions can provide.

The "Capabilities" section of each function and event describe which capabilities, if any, they are associated with. "Required Functionality" means it is available for use and no capabilities must be added to use it. "Optional Functionality" means the agent must possess the capability before it can be used. To possess a capability, the agent must add the capability. "Optional Features" describe capabilities which, if added, extend the feature set.

The potentially available capabilities of each JVM TI implementation are different. Depending on the implementation, a capability:
  • may never be added
  • may be added in either the OnLoad or live phase in any environment
  • may be added only during the OnLoad phase
  • may be possessed by only one environment at a time
  • may be possessed by only one environment at a time, and only during the OnLoad phase
  • and so on ...
Frequently, the addition of a capability may incur a cost in execution speed, start up time, and/or memory footprint. Note that the overhead of using a capability is completely different than the overhead of possessing a capability. Take single stepping as an example. When single stepping is on (that is, when the event is enabled and thus actively sending events) the overhead of sending and processing an event on each instruction is huge in any implementation. However, the overhead of possessing the capability may be small or large, depending on the implementation. Also, when and if a capability is potentially available depends on the implementation. Some examples:
  • One VM might perform all execution by compiling bytecodes into native code and be unable to generate single step instructions. In this implementation the capability can not be added.
  • Another VM may be able to switch execution to a single stepping interpreter at any time. In this implementation, having the capability has no overhead and could be added at any time.
  • Yet another VM might be able to choose a bytecode compiling or single stepping capable interpreted execution engine at start up, but be unable to switch between them. In this implementation the capability would need to be added during the OnLoad phase (before bytecode execution begins) and would have a large impact on execution speed even if single stepping was never used.
  • Still another VM might be able to add an "is single stepping on" check into compiled bytecodes or a generated interpreter. Again in this implementation the capability would need to be added during the OnLoad phase but the overhead (a test and branch on each instruction) would be considerably less.

Each JVM TI environment has its own set of capabilities. Initially, that set is empty. Any desired capability must be added. If possible, capabilities should be added during the OnLoad phase. For most virtual machines certain capabilities require special set up for the virtual machine and this set up must happen during the OnLoad phase, before the virtual machine begins execution. Once a capability is added, it can only be removed if explicitly relinquished by the environment.

The agent can, determine what capabilities this VM can potentially provide, add the capabilities to be used, release capabilities which are no longer needed, and examine the currently available capabilities.

Capability Examples

For example, a freshly started agent (in the OnLoad function) wants to enable all possible capabilities. Note that, in general, this is not advisable as the agent may suffer a performance penalty for functionality it is not using. The code might look like this in C:
    jvmtiCapabilities capa;
    jvmtiError err;

    err = (*jvmti)->GetPotentialCapabilities(jvmti, &capa);
    if (err == JVMTI_ERROR_NONE) {
       err = (*jvmti)->AddCapabilities(jvmti, &capa);
For example, if an agent wants to check if it can get the bytecodes of a method (that is, it wants to check if it previously added this capability and has not relinquished it), the code might look like this in C:
    jvmtiCapabilities capa;
    jvmtiError err;

    err = (*jvmti)->GetCapabilities(jvmti, &capa);
    if (err == JVMTI_ERROR_NONE) {
          if (capa.can_get_bytecodes) { ... } }

The Capabilities Structure

The functions in this category use this capabilities structure which contains boolean flags corresponding to each capability:

typedef struct {
    unsigned int can_tag_objects : 1;
    unsigned int can_generate_field_modification_events : 1;
    unsigned int can_generate_field_access_events : 1;
    unsigned int can_get_bytecodes : 1;
    unsigned int can_get_synthetic_attribute : 1;
    unsigned int can_get_owned_monitor_info : 1;
    unsigned int can_get_current_contended_monitor : 1;
    unsigned int can_get_monitor_info : 1;
    unsigned int can_pop_frame : 1;
    unsigned int can_redefine_classes : 1;
    unsigned int can_signal_thread : 1;
    unsigned int can_get_source_file_name : 1;
    unsigned int can_get_line_numbers : 1;
    unsigned int can_get_source_debug_extension : 1;
    unsigned int can_access_local_variables : 1;
    unsigned int can_maintain_original_method_order : 1;
    unsigned int can_generate_single_step_events : 1;
    unsigned int can_generate_exception_events : 1;
    unsigned int can_generate_frame_pop_events : 1;
    unsigned int can_generate_breakpoint_events : 1;
    unsigned int can_suspend : 1;
    unsigned int can_redefine_any_class : 1;
    unsigned int can_get_current_thread_cpu_time : 1;
    unsigned int can_get_thread_cpu_time : 1;
    unsigned int can_generate_method_entry_events : 1;
    unsigned int can_generate_method_exit_events : 1;
    unsigned int can_generate_all_class_hook_events : 1;
    unsigned int can_generate_compiled_method_load_events : 1;
    unsigned int can_generate_monitor_events : 1;
    unsigned int can_generate_vm_object_alloc_events : 1;
    unsigned int can_generate_native_method_bind_events : 1;
    unsigned int can_generate_garbage_collection_events : 1;
    unsigned int can_generate_object_free_events : 1;
    unsigned int can_force_early_return : 1;
    unsigned int can_get_owned_monitor_stack_depth_info : 1;
    unsigned int can_get_constant_pool : 1;
    unsigned int can_set_native_method_prefix : 1;
    unsigned int can_retransform_classes : 1;
    unsigned int can_retransform_any_class : 1;
    unsigned int can_generate_resource_exhaustion_heap_events : 1;
    unsigned int can_generate_resource_exhaustion_threads_events : 1;
    unsigned int : 7;
    unsigned int : 16;
    unsigned int : 16;
    unsigned int : 16;
    unsigned int : 16;
    unsigned int : 16;
} jvmtiCapabilities;
jvmtiCapabilities - The Capabilities Structure
All types are unsigned int : 1
Field | Description | Since
can_tag_objects | Can set and get tags, as described in the Heap category. | 1.0
can_generate_field_modification_events | Can set watchpoints on field modification - SetFieldModificationWatch | 1.0
can_generate_field_access_events | Can set watchpoints on field access - SetFieldAccessWatch | 1.0
can_get_bytecodes | Can get bytecodes of a method GetBytecodes | 1.0
can_get_synthetic_attribute | Can test if a field or method is synthetic - IsFieldSynthetic and IsMethodSynthetic | 1.0
can_get_owned_monitor_info | Can get information about ownership of monitors - GetOwnedMonitorInfo | 1.0
can_get_current_contended_monitor | Can GetCurrentContendedMonitor | 1.0
can_get_monitor_info | Can GetObjectMonitorUsage | 1.0
can_pop_frame | Can pop frames off the stack - PopFrame | 1.0
can_redefine_classes | Can redefine classes with RedefineClasses. | 1.0
can_signal_thread | Can send stop or interrupt to threads | 1.0
can_get_source_file_name | Can get the source file name of a class | 1.0
can_get_line_numbers | Can get the line number table of a method | 1.0
can_get_source_debug_extension | Can get the source debug extension of a class | 1.0
can_access_local_variables | Can set and get local variables | 1.0
can_maintain_original_method_order | Can return methods in the order they occur in the class file | 1.0
can_generate_single_step_events | Can get single step events | 1.0
can_generate_exception_events | Can get exception thrown and exception catch events | 1.0
can_generate_frame_pop_events | Can set and thus get FramePop events | 1.0
can_generate_breakpoint_events | Can set and thus get Breakpoint events | 1.0
can_suspend | Can suspend and resume threads | 1.0
can_redefine_any_class | Can modify (retransform or redefine) any non-primitive non-array class. See IsModifiableClass. | 1.0
can_get_current_thread_cpu_time | Can get current thread CPU time | 1.0
can_get_thread_cpu_time | Can get thread CPU time | 1.0
can_generate
_method_entry_events 		Can generate method entry events on entering a method 1.0
can_generate
_method_exit_events 		Can generate method exit events on leaving a method 1.0
can_generate
_all_class_hook_events 		Can generate ClassFileLoadHook events for every loaded class. 1.0
can_generate
_compiled_method_load_events 		Can generate events when a method is compiled or unloaded 1.0
can_generate
_monitor_events 		Can generate events on monitor activity 1.0
can_generate
_vm_object_alloc_events 		Can generate events on VM allocation of an object 1.0
can_generate
_native_method_bind_events 		Can generate events when a native method is bound to its implementation 1.0
can_generate
_garbage_collection_events 		Can generate events when garbage collection begins or ends 1.0
can_generate
_object_free_events 		Can generate events when the garbage collector frees an object 1.0
can_force_early_return | Can return early from a method, as described in the Force Early Return category. | 1.1
can_get_owned_monitor_stack_depth_info | Can get information about owned monitors with stack depth - GetOwnedMonitorStackDepthInfo | 1.1
can_get_constant_pool | Can get the constant pool of a class - GetConstantPool | 1.1
can_set_native_method_prefix | Can set prefix to be applied when native method cannot be resolved - SetNativeMethodPrefix and SetNativeMethodPrefixes | 1.1
can_retransform_classes | Can retransform classes with RetransformClasses. In addition to the restrictions imposed by the specific implementation on this capability (see the Capability section), this capability must be set before the ClassFileLoadHook event is enabled for the first time in this environment. An environment that possesses this capability at the time that ClassFileLoadHook is enabled for the first time is said to be retransformation capable. An environment that does not possess this capability at the time that ClassFileLoadHook is enabled for the first time is said to be retransformation incapable. | 1.1
can_retransform_any_class | RetransformClasses can be called on any class (can_retransform_classes must also be set) | 1.1
can_generate_resource_exhaustion_heap_events | Can generate events when the VM is unable to allocate memory from the JavaTM platform heap. See ResourceExhausted. | 1.1
can_generate_resource_exhaustion_threads_events | Can generate events when the VM is unable to create a thread. See ResourceExhausted. | 1.1

Get Potential Capabilities

jvmtiError
GetPotentialCapabilities(jvmtiEnv* env,
            jvmtiCapabilities* capabilities_ptr)
Returns via capabilities_ptr the JVM TI features that can potentially be possessed by this environment at this time. The returned capabilities differ from the complete set of capabilities implemented by the VM in two cases: another environment possesses capabilities that can only be possessed by one environment, or the current phase is live, and certain capabilities can only be added during the OnLoad phase. The AddCapabilities function may be used to set any or all or these capabilities. Currently possessed capabilities are included.

Typically this function is used in the OnLoad function. Some virtual machines may allow a limited set of capabilities to be added in the live phase. In this case, the set of potentially available capabilities will likely differ from the OnLoad phase set.

See the Capability Examples.

Phase | Callback Safe | Position | Since
may only be called during the OnLoad or the live phase | No | 140 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
capabilities_ptr | jvmtiCapabilities* | On return, points to the JVM TI capabilities that may be added. Agent passes a pointer to a jvmtiCapabilities. On return, the jvmtiCapabilities has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | capabilities_ptr is NULL.

Add Capabilities

jvmtiError
AddCapabilities(jvmtiEnv* env,
            const jvmtiCapabilities* capabilities_ptr)
Set new capabilities by adding the capabilities whose values are set to one (1) in * capabilities_ptr. All previous capabilities are retained. Typically this function is used in the OnLoad function. Some virtual machines may allow a limited set of capabilities to be added in the live phase.

See the Capability Examples.

Phase | Callback Safe | Position | Since
may only be called during the OnLoad or the live phase | No | 142 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
capabilities_ptr | const jvmtiCapabilities* | Points to the JVM TI capabilities to add. Agent passes in a pointer to jvmtiCapabilities.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NOT_AVAILABLE | The desired capabilities are not even potentially available.
JVMTI_ERROR_NULL_POINTER | capabilities_ptr is NULL.

Relinquish Capabilities

jvmtiError
RelinquishCapabilities(jvmtiEnv* env,
            const jvmtiCapabilities* capabilities_ptr)
Relinquish the capabilities whose values are set to one (1) in * capabilities_ptr. Some implementations may allow only one environment to have a capability (see the capability introduction). This function releases capabilities so that they may be used by other agents. All other capabilities are retained. The capability will no longer be present in GetCapabilities. Attempting to relinquish a capability that the agent does not possess is not an error.

Phase | Callback Safe | Position | Since
may only be called during the OnLoad or the live phase | No | 143 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
capabilities_ptr | const jvmtiCapabilities* | Points to the JVM TI capabilities to relinquish. Agent passes in a pointer to jvmtiCapabilities.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | capabilities_ptr is NULL.

Get Capabilities

jvmtiError
GetCapabilities(jvmtiEnv* env,
            jvmtiCapabilities* capabilities_ptr)
Returns via capabilities_ptr the optional JVM TI features which this environment currently possesses. Each possessed capability is indicated by a one (1) in the corresponding field of the capabilities structure. An environment does not possess a capability unless it has been successfully added with AddCapabilities. An environment only loses possession of a capability if it has been relinquished with RelinquishCapabilities. Thus, this function returns the net result of the AddCapabilities and RelinquishCapabilities calls which have been made.

See the Capability Examples.

Phase | Callback Safe | Position | Since
may be called during any phase | No | 89 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
capabilities_ptr | jvmtiCapabilities* | On return, points to the JVM TI capabilities. Agent passes a pointer to a jvmtiCapabilities. On return, the jvmtiCapabilities has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | capabilities_ptr is NULL.

Timers

Timers functions:
  • Get Current Thread CPU Timer Information
  • Get Current Thread CPU Time
  • Get Thread CPU Timer Information
  • Get Thread CPU Time
  • Get Timer Information
  • Get Time
  • Get Available Processors
Timers types:
  • jvmtiTimerInfo - Timer Info
  • jvmtiTimerKind - Timer Kinds
These functions provide timing information. The resolution at which the time is updated is not specified. They provides nanosecond precision, but not necessarily nanosecond accuracy. Details about the timers, such as their maximum values, can be accessed with the timer information functions.

Timer Info

The information function for each timer returns this data structure.

typedef struct {
    jlong max_value;
    jboolean may_skip_forward;
    jboolean may_skip_backward;
    jvmtiTimerKind kind;
    jlong reserved1;
    jlong reserved2;
} jvmtiTimerInfo;
jvmtiTimerInfo - Timer Info
Field | Type | Description
max_value | jlong | The maximum value the timer can reach. After this value is reached the timer wraps back to zero. This is an unsigned value. If tested or printed as a jlong (signed value) it may appear to be a negative number.
may_skip_forward | jboolean | If true, the timer can be externally adjusted and as a result skip forward. If false, the timer value will never increase faster than real time.
may_skip_backward | jboolean | If true, the timer can be externally adjusted and as a result skip backward. If false, the timer value will be monotonically increasing.
kind | jvmtiTimerKind | The kind of timer. On a platform that does not distinguish between user and system time, JVMTI_TIMER_TOTAL_CPU is returned.
reserved1 | jlong | Reserved for future use.
reserved2 | jlong | Reserved for future use.
Where the timer kind is --
Timer Kinds (jvmtiTimerKind)
Constant | Value | Description
JVMTI_TIMER_USER_CPU | 30 | CPU time that a thread is in user mode.
JVMTI_TIMER_TOTAL_CPU | 31 | CPU time that a thread is in user or system mode.
JVMTI_TIMER_ELAPSED | 32 | Elapsed time.

Get Current Thread CPU Timer Information

jvmtiError
GetCurrentThreadCpuTimerInfo(jvmtiEnv* env,
            jvmtiTimerInfo* info_ptr)
Get information about the GetCurrentThreadCpuTime timer. The fields of the jvmtiTimerInfo structure are filled in with details about the timer. This information is specific to the platform and the implementation of GetCurrentThreadCpuTime and thus does not vary by thread nor does it vary during a particular invocation of the VM.

Note that the implementations of GetCurrentThreadCpuTime and GetThreadCpuTime may differ, and thus the values returned by GetCurrentThreadCpuTimerInfo and GetThreadCpuTimerInfo may differ -- see GetCurrentThreadCpuTime for more information.

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | This function may be called from the callbacks to the Heap iteration functions, or from the event handlers for the GarbageCollectionStart, GarbageCollectionFinish, and ObjectFree events. | 134 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_get_current_thread_cpu_time | Can get current thread CPU time.

Parameters
Name | Type | Description
info_ptr | jvmtiTimerInfo* | On return, filled with information describing the time returned by GetCurrentThreadCpuTime. Agent passes a pointer to a jvmtiTimerInfo. On return, the jvmtiTimerInfo has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_get_current_thread_cpu_time. Use AddCapabilities.
JVMTI_ERROR_NULL_POINTER | info_ptr is NULL.

Get Current Thread CPU Time

jvmtiError
GetCurrentThreadCpuTime(jvmtiEnv* env,
            jlong* nanos_ptr)
Return the CPU time utilized by the current thread.

Note that the GetThreadCpuTime function provides CPU time for any thread, including the current thread. GetCurrentThreadCpuTime exists to support platforms which cannot supply CPU time for threads other than the current thread or which have more accurate information for the current thread (see GetCurrentThreadCpuTimerInfo vs GetThreadCpuTimerInfo). On many platforms this call will be equivalent to:
  GetThreadCpuTime(env, NULL, nanos_ptr)

Phase | Callback Safe | Position | Since
may only be called during the start or the live phase | This function may be called from the callbacks to the Heap iteration functions, or from the event handlers for the GarbageCollectionStart, GarbageCollectionFinish, and ObjectFree events. | 135 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_get_current_thread_cpu_time | Can get current thread CPU time. If this capability is enabled after threads have started, the implementation may choose any time up to and including the time that the capability is enabled as the point where CPU time collection starts. This capability must be potentially available on any platform where can_get_thread_cpu_time is potentially available.

Parameters
Name | Type | Description
nanos_ptr | jlong* | On return, points to the CPU time used by this thread in nanoseconds. This is an unsigned value. If tested or printed as a jlong (signed value) it may appear to be a negative number. Agent passes a pointer to a jlong. On return, the jlong has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_get_current_thread_cpu_time. Use AddCapabilities.
JVMTI_ERROR_NULL_POINTER | nanos_ptr is NULL.

Get Thread CPU Timer Information

jvmtiError
GetThreadCpuTimerInfo(jvmtiEnv* env,
            jvmtiTimerInfo* info_ptr)
Get information about the GetThreadCpuTime timer. The fields of the jvmtiTimerInfo structure are filled in with details about the timer. This information is specific to the platform and the implementation of GetThreadCpuTime and thus does not vary by thread nor does it vary during a particular invocation of the VM.

Note that the implementations of GetCurrentThreadCpuTime and GetThreadCpuTime may differ, and thus the values returned by GetCurrentThreadCpuTimerInfo and GetThreadCpuTimerInfo may differ -- see GetCurrentThreadCpuTime for more information.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 136 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_get_thread_cpu_time | Can get thread CPU time.

Parameters
Name | Type | Description
info_ptr | jvmtiTimerInfo* | On return, filled with information describing the time returned by GetThreadCpuTime. Agent passes a pointer to a jvmtiTimerInfo. On return, the jvmtiTimerInfo has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_get_thread_cpu_time. Use AddCapabilities.
JVMTI_ERROR_NULL_POINTER | info_ptr is NULL.

Get Thread CPU Time

jvmtiError
GetThreadCpuTime(jvmtiEnv* env,
            jthread thread,
            jlong* nanos_ptr)
Return the CPU time utilized by the specified thread.

Get information about this timer with GetThreadCpuTimerInfo.

Phase | Callback Safe | Position | Since
may only be called during the live phase | No | 137 | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability | Effect
can_get_thread_cpu_time | Can get thread CPU time. If this capability is enabled after threads have started, the implementation may choose any time up to and including the time that the capability is enabled as the point where CPU time collection starts.

Parameters
Name | Type | Description
thread | jthread | The thread to query. If thread is NULL, the current thread is used.
nanos_ptr | jlong* | On return, points to the CPU time used by the specified thread in nanoseconds. This is an unsigned value. If tested or printed as a jlong (signed value) it may appear to be a negative number. Agent passes a pointer to a jlong. On return, the jlong has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY | The environment does not possess the capability can_get_thread_cpu_time. Use AddCapabilities.
JVMTI_ERROR_INVALID_THREAD | thread is not a thread object.
JVMTI_ERROR_THREAD_NOT_ALIVE | thread is not live (has not been started or is now dead).
JVMTI_ERROR_NULL_POINTER | nanos_ptr is NULL.

Get Timer Information

jvmtiError
GetTimerInfo(jvmtiEnv* env,
            jvmtiTimerInfo* info_ptr)
Get information about the GetTime timer. The fields of the jvmtiTimerInfo structure are filled in with details about the timer. This information will not change during a particular invocation of the VM.

Phase | Callback Safe | Position | Since
may be called during any phase | This function may be called from the callbacks to the Heap iteration functions, or from the event handlers for the GarbageCollectionStart, GarbageCollectionFinish, and ObjectFree events. | 138 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
info_ptr | jvmtiTimerInfo* | On return, filled with information describing the time returned by GetTime. Agent passes a pointer to a jvmtiTimerInfo. On return, the jvmtiTimerInfo has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | info_ptr is NULL.

Get Time

jvmtiError
GetTime(jvmtiEnv* env,
            jlong* nanos_ptr)
Return the current value of the system timer, in nanoseconds.

The value returned represents nanoseconds since some fixed but arbitrary time (perhaps in the future, so values may be negative). This function provides nanosecond precision, but not necessarily nanosecond accuracy. No guarantees are made about how frequently values change.

Get information about this timer with GetTimerInfo.

Phase | Callback Safe | Position | Since
may be called during any phase | This function may be called from the callbacks to the Heap iteration functions, or from the event handlers for the GarbageCollectionStart, GarbageCollectionFinish, and ObjectFree events. | 139 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
nanos_ptr | jlong* | On return, points to the time in nanoseconds. This is an unsigned value. If tested or printed as a jlong (signed value) it may appear to be a negative number. Agent passes a pointer to a jlong. On return, the jlong has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | nanos_ptr is NULL.

Get Available Processors

jvmtiError
GetAvailableProcessors(jvmtiEnv* env,
            jint* processor_count_ptr)
Returns the number of processors available to the Java virtual machine.

This value may change during a particular invocation of the virtual machine. Applications that are sensitive to the number of available processors should therefore occasionally poll this property.

Phase | Callback Safe | Position | Since
may be called during any phase | No | 144 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
processor_count_ptr | jint* | On return, points to the maximum number of processors available to the virtual machine; never smaller than one. Agent passes a pointer to a jint. On return, the jint has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | processor_count_ptr is NULL.

Class Loader Search

Class Loader Search functions:
  • Add To Bootstrap Class Loader Search
  • Add To System Class Loader Search
These functions allow the agent to add to the locations that a class loader searches for a class. This is useful for installing instrumentation under the correct class loader.

Add To Bootstrap Class Loader Search

jvmtiError
AddToBootstrapClassLoaderSearch(jvmtiEnv* env,
            const char* segment)
This function can be used to cause instrumentation classes to be defined by the bootstrap class loader. See Loading Using the Bootstrap Class Loader in the Java Virtual Machine Specification. After the bootstrap class loader unsuccessfully searches for a class, the specified platform-dependent search path segment will be searched as well. Only one segment may be specified in the segment. This function may be called multiple times to add multiple segments, the segments will be searched in the order that this function was called.

In the OnLoad phase the function may be used to specify any platform-dependent search path segment to be searched after the bootstrap class loader unsuccessfully searches for a class. The segment is typically a directory or JAR file.

In the live phase the segment may be used to specify any platform-dependent path to a JAR file. The agent should take care that the JAR file does not contain any classes or resources other than those to be defined by the bootstrap class loader for the purposes of instrumentation.

The Java Virtual Machine Specification specifies that a subsequent attempt to resolve a symbolic reference that the Java virtual machine has previously unsuccessfully attempted to resolve always fails with the same error that was thrown as a result of the initial resolution attempt. Consequently, if the JAR file contains an entry that corresponds to a class for which the Java virtual machine has unsuccessfully attempted to resolve a reference, then subsequent attempts to resolve that reference will fail with the same error as the initial attempt.

Phase | Callback Safe | Position | Since
may only be called during the OnLoad or the live phase | No | 149 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
segment | const char* | The platform-dependent search path segment, encoded as a modified UTF-8 string. Agent passes in an array of char.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_ILLEGAL_ARGUMENT | segment is an invalid path. In the live phase, anything other than an existing JAR file is an invalid path.
JVMTI_ERROR_NULL_POINTER | segment is NULL.

Add To System Class Loader Search

jvmtiError
AddToSystemClassLoaderSearch(jvmtiEnv* env,
            const char* segment)
This function can be used to cause instrumentation classes to be defined by the system class loader. See Loading Using a User-defined Class Loader in the Java Virtual Machine Specification. After the class loader unsuccessfully searches for a class, the specified platform-dependent search path segment will be searched as well. Only one segment may be specified in the segment. This function may be called multiple times to add multiple segments, the segments will be searched in the order that this function was called.

In the OnLoad phase the function may be used to specify any platform-dependent search path segment to be searched after the system class loader unsuccessfully searches for a class. The segment is typically a directory or JAR file.

In the live phase the segment is a platform-dependent path to a JAR file to be searched after the system class loader unsuccessfully searches for a class. The agent should take care that the JAR file does not contain any classes or resources other than those to be defined by the system class loader for the purposes of instrumentation.

In the live phase the system class loader supports adding a JAR file to be searched if the system class loader implements a method name appendToClassPathForInstrumentation which takes a single parameter of type java.lang.String. The method is not required to have public access.

The Java Virtual Machine Specification specifies that a subsequent attempt to resolve a symbolic reference that the Java virtual machine has previously unsuccessfully attempted to resolve always fails with the same error that was thrown as a result of the initial resolution attempt. Consequently, if the JAR file contains an entry that corresponds to a class for which the Java virtual machine has unsuccessfully attempted to resolve a reference, then subsequent attempts to resolve that reference will fail with the same error as the initial attempt.

Phase | Callback Safe | Position | Since
may only be called during the OnLoad or the live phase | No | 151 | 1.1

Capabilities
Required Functionality

Parameters
Name | Type | Description
segment | const char* | The platform-dependent search path segment, encoded as a modified UTF-8 string. Agent passes in an array of char.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_ILLEGAL_ARGUMENT | segment is an invalid path. In the live phase, anything other than an existing JAR file is an invalid path.
JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED | Operation not supported by the system class loader.
JVMTI_ERROR_NULL_POINTER | segment is NULL.

System Properties

System Properties functions:
  • Get System Properties
  • Get System Property
  • Set System Property
These functions get and set system properties.

Get System Properties

jvmtiError
GetSystemProperties(jvmtiEnv* env,
            jint* count_ptr,
            char*** property_ptr)
The list of VM system property keys which may be used with GetSystemProperty is returned. It is strongly recommended that virtual machines provide the following property keys:
  • java.vm.vendor
  • java.vm.version
  • java.vm.name
  • java.vm.info
  • java.library.path
  • java.class.path
Provides access to system properties defined by and used by the VM. Properties set on the command-line are included. This allows getting and setting of these properties before the VM even begins executing bytecodes. Since this is a VM view of system properties, the set of available properties will usually be different than that in java.lang.System.getProperties. JNI method invocation may be used to access java.lang.System.getProperties.

The set of properties may grow during execution.

Phase | Callback Safe | Position | Since
may only be called during the OnLoad or the live phase | No | 130 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
count_ptr | jint* | On return, points to the number of property keys returned. Agent passes a pointer to a jint. On return, the jint has been set.
property_ptr | char*** | On return, points to an array of property keys, encoded as modified UTF-8 strings. Agent passes a pointer to a char**. On return, the char** points to a newly allocated array of size *count_ptr, each element of which is also newly allocated. The array should be freed with Deallocate. Each of the elements should be freed with Deallocate.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | count_ptr is NULL.
JVMTI_ERROR_NULL_POINTER | property_ptr is NULL.

Get System Property

jvmtiError
GetSystemProperty(jvmtiEnv* env,
            const char* property,
            char** value_ptr)
Return a VM system property value given the property key.

The function GetSystemProperties returns the set of property keys which may be used. The properties which can be retrieved may grow during execution.

Since this is a VM view of system properties, the values of properties may differ from that returned by java.lang.System.getProperty(String). A typical VM might copy the values of the VM system properties into the Properties held by java.lang.System during the initialization of that class. Thereafter any changes to the VM system properties (with SetSystemProperty) or the java.lang.System system properties (with java.lang.System.setProperty(String,String)) would cause the values to diverge. JNI method invocation may be used to access java.lang.System.getProperty(String).

Phase | Callback Safe | Position | Since
may only be called during the OnLoad or the live phase | No | 131 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
property | const char* | The key of the property to retrieve, encoded as a modified UTF-8 string. Agent passes in an array of char.
value_ptr | char** | On return, points to the property value, encoded as a modified UTF-8 string. Agent passes a pointer to a char*. On return, the char* points to a newly allocated array. The array should be freed with Deallocate.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NOT_AVAILABLE | This property is not available. Use GetSystemProperties to find available properties.
JVMTI_ERROR_NULL_POINTER | property is NULL.
JVMTI_ERROR_NULL_POINTER | value_ptr is NULL.

Set System Property

jvmtiError
SetSystemProperty(jvmtiEnv* env,
            const char* property,
            const char* value)
Set a VM system property value.

The function GetSystemProperties returns the set of property keys, some of these may be settable. See GetSystemProperty.

Phase | Callback Safe | Position | Since
may only be called during the OnLoad phase | No | 132 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
property | const char* | The key of the property, encoded as a modified UTF-8 string. Agent passes in an array of char.
value | const char * | The property value to set, encoded as a modified UTF-8 string. Agent passes in an array of char. If value is NULL, do not set the value, but return JVMTI_ERROR_NOT_AVAILABLE if the property is not writeable .

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NOT_AVAILABLE | This property is not available or is not writeable.
JVMTI_ERROR_NULL_POINTER | property is NULL.

General

General functions:
  • Get Phase
  • Dispose Environment
  • Set Environment Local Storage
  • Get Environment Local Storage
  • Get Version Number
  • Get Error Name
  • Set Verbose Flag
  • Get JLocation Format
General types:
  • jvmtiPhase - Phases of execution
  • jvmtiVerboseFlag - Verbose Flag Enumeration
  • jvmtiJlocationFormat - JLocation Format Enumeration
General flags and constants:
  • Version Interface Types
  • Version Masks
  • Version Shifts

Get Phase

typedef enum {
    JVMTI_PHASE_ONLOAD = 1,
    JVMTI_PHASE_PRIMORDIAL = 2,
    JVMTI_PHASE_START = 6,
    JVMTI_PHASE_LIVE = 4,
    JVMTI_PHASE_DEAD = 8
} jvmtiPhase;
jvmtiError
GetPhase(jvmtiEnv* env,
            jvmtiPhase* phase_ptr)
Return the current phase of VM execution. The phases proceed in sequence:
Phases of execution (jvmtiPhase)
Constant | Value | Description
JVMTI_PHASE_ONLOAD | 1 | OnLoad phase: while in the Agent_OnLoad function.
JVMTI_PHASE_PRIMORDIAL | 2 | Primordial phase: between return from Agent_OnLoad and the VMStart event.
JVMTI_PHASE_START | 6 | Start phase: when the VMStart event is sent and until the VMInit event is sent.
JVMTI_PHASE_LIVE | 4 | Live phase: when the VMInit event is sent and until the VMDeath event returns.
JVMTI_PHASE_DEAD | 8 | Dead phase: after the VMDeath event returns or after start-up failure.
In the case of start-up failure the VM will proceed directly to the dead phase skipping intermediate phases and neither a VMInit nor VMDeath event will be sent.

Most JVM TI functions operate only in the live phase. The following functions operate in either the OnLoad or live phases:
  • CreateRawMonitor
  • DestroyRawMonitor
  • SetEventCallbacks
  • SetEventNotificationMode
  • GetExtensionFunctions
  • GetExtensionEvents
  • SetExtensionEventCallback
  • GetPotentialCapabilities
  • AddCapabilities
  • RelinquishCapabilities
  • AddToBootstrapClassLoaderSearch
  • AddToSystemClassLoaderSearch
  • GetSystemProperties
  • GetSystemProperty
The following functions operate in only the OnLoad phase:
  • SetSystemProperty
The following functions operate in the start or live phases:
  • GetCurrentThread
  • SetThreadLocalStorage
  • GetThreadLocalStorage
  • GetTag
  • SetTag
  • GetClassSignature
  • GetClassStatus
  • GetSourceFileName
  • GetClassModifiers
  • GetClassMethods
  • GetClassFields
  • GetImplementedInterfaces
  • GetClassVersionNumbers
  • GetConstantPool
  • IsInterface
  • IsArrayClass
  • IsModifiableClass
  • GetClassLoader
  • GetSourceDebugExtension
  • GetObjectSize
  • GetObjectHashCode
  • GetFieldName
  • GetFieldDeclaringClass
  • GetFieldModifiers
  • IsFieldSynthetic
  • GetMethodName
  • GetMethodDeclaringClass
  • GetMethodModifiers
  • GetMaxLocals
  • GetArgumentsSize
  • GetLineNumberTable
  • GetMethodLocation
  • GetBytecodes
  • IsMethodNative
  • IsMethodSynthetic
  • IsMethodObsolete
  • SetJNIFunctionTable
  • GetJNIFunctionTable
  • GetCurrentThreadCpuTimerInfo
  • GetCurrentThreadCpuTime
The following functions operate in any phase:
  • Allocate
  • Deallocate
  • SetNativeMethodPrefix
  • SetNativeMethodPrefixes
  • RawMonitorEnter
  • RawMonitorExit
  • RawMonitorWait
  • RawMonitorNotify
  • RawMonitorNotifyAll
  • GetCapabilities
  • GetTimerInfo
  • GetTime
  • GetAvailableProcessors
  • GetPhase
  • DisposeEnvironment
  • SetEnvironmentLocalStorage
  • GetEnvironmentLocalStorage
  • GetVersionNumber
  • GetErrorName
  • SetVerboseFlag
  • GetJLocationFormat
JNI functions (except the Invocation API) must only be used in the start or live phases.

Most JVM TI events are sent only in the live phase. The following events operate in others phases:
  • ThreadStart
  • ThreadEnd
  • ClassLoad
  • ClassPrepare
  • VMStart
  • NativeMethodBind
  • ClassFileLoadHook
  • DynamicCodeGenerated

Phase | Callback Safe | Position | Since
may be called during any phase | No | 133 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
phase_ptr | jvmtiPhase* | On return, points to the phase. Agent passes a pointer to a jvmtiPhase. On return, the jvmtiPhase has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | phase_ptr is NULL.

Dispose Environment

jvmtiError
DisposeEnvironment(jvmtiEnv* env)
Shutdown a JVM TI connection created with JNI GetEnv (see JVM TI Environments). Dispose of any resources held by the environment. Threads suspended by this environment are not resumed by this call, this must be done explicitly by the agent. Memory allocated by this environment via calls to JVM TI functions is not released, this can be done explicitly by the agent by calling Deallocate. Raw monitors created by this environment are not destroyed, this can be done explicitly by the agent by calling DestroyRawMonitor. The state of threads waiting on raw monitors created by this environment are not affected.

Any native method prefixes for this environment will be unset; the agent must remove any prefixed native methods before dispose is called.

Any capabilities held by this environment are relinquished.

Events enabled by this environment will no longer be sent, however event handlers currently running will continue to run. Caution must be exercised in the design of event handlers whose environment may be disposed and thus become invalid during their execution.

This environment may not be used after this call. This call returns to the caller.

Phase | Callback Safe | Position | Since
may be called during any phase | No | 127 | 1.0

Capabilities
Required Functionality

Parameters
Name Type Description

Errors
This function returns a universal error

Set Environment Local Storage

jvmtiError
SetEnvironmentLocalStorage(jvmtiEnv* env,
            const void* data)
The VM stores a pointer value associated with each environment. This pointer value is called environment-local storage. This value is NULL unless set with this function. Agents can allocate memory in which they store environment specific information. By setting environment-local storage it can then be accessed with GetEnvironmentLocalStorage.

Called by the agent to set the value of the JVM TI environment-local storage. JVM TI supplies to the agent a pointer-size environment-local storage that can be used to record per-environment information.

Phase | Callback Safe | Position | Since
may be called during any phase | This function may be called from the callbacks to the Heap iteration functions, or from the event handlers for the GarbageCollectionStart, GarbageCollectionFinish, and ObjectFree events. | 148 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
data | const void * | The value to be entered into the environment-local storage. Agent passes in a pointer. If data is NULL, value is set to NULL.

Errors
This function returns a universal error

Get Environment Local Storage

jvmtiError
GetEnvironmentLocalStorage(jvmtiEnv* env,
            void** data_ptr)
Called by the agent to get the value of the JVM TI environment-local storage.

Phase | Callback Safe | Position | Since
may be called during any phase | This function may be called from the callbacks to the Heap iteration functions, or from the event handlers for the GarbageCollectionStart, GarbageCollectionFinish, and ObjectFree events. | 147 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
data_ptr | void** | Pointer through which the value of the environment local storage is returned. If environment-local storage has not been set with SetEnvironmentLocalStorage returned pointer is NULL.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | data_ptr is NULL.

Get Version Number

jvmtiError
GetVersionNumber(jvmtiEnv* env,
            jint* version_ptr)
Return the JVM TI version via version_ptr. The return value is the version identifier. The version identifier includes major, minor and micro version as well as the interface type.
Version Interface Types
Constant | Value | Description
JVMTI_VERSION_INTERFACE_JNI | 0x00000000 | Value of JVMTI_VERSION_MASK_INTERFACE_TYPE for JNI.
JVMTI_VERSION_INTERFACE_JVMTI | 0x30000000 | Value of JVMTI_VERSION_MASK_INTERFACE_TYPE for JVM TI.
Version Masks
Constant | Value | Description
JVMTI_VERSION_MASK_INTERFACE_TYPE | 0x70000000 | Mask to extract interface type. The value of the version returned by this function masked with JVMTI_VERSION_MASK_INTERFACE_TYPE is always JVMTI_VERSION_INTERFACE_JVMTI since this is a JVM TI function.
JVMTI_VERSION_MASK_MAJOR | 0x0FFF0000 | Mask to extract major version number.
JVMTI_VERSION_MASK_MINOR | 0x0000FF00 | Mask to extract minor version number.
JVMTI_VERSION_MASK_MICRO | 0x000000FF | Mask to extract micro version number.
Version Shifts
Constant | Value | Description
JVMTI_VERSION_SHIFT_MAJOR | 16 | Shift to extract major version number.
JVMTI_VERSION_SHIFT_MINOR | 8 | Shift to extract minor version number.
JVMTI_VERSION_SHIFT_MICRO | 0 | Shift to extract micro version number.

Phase | Callback Safe | Position | Since
may be called during any phase | No | 88 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
version_ptr | jint* | On return, points to the JVM TI version. Agent passes a pointer to a jint. On return, the jint has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | version_ptr is NULL.

Get Error Name

jvmtiError
GetErrorName(jvmtiEnv* env,
            jvmtiError error,
            char** name_ptr)
Return the symbolic name for an error code.

For example GetErrorName(env, JVMTI_ERROR_NONE, &err_name) would return in err_name the string "JVMTI_ERROR_NONE".

Phase | Callback Safe | Position | Since
may be called during any phase | No | 128 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
error | jvmtiError | The error code.
name_ptr | char** | On return, points to the error name. The name is encoded as a modified UTF-8 string, but is restricted to the ASCII subset. Agent passes a pointer to a char*. On return, the char* points to a newly allocated array. The array should be freed with Deallocate.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_ILLEGAL_ARGUMENT | error is not a jvmtiError.
JVMTI_ERROR_NULL_POINTER | name_ptr is NULL.

Set Verbose Flag

typedef enum {
    JVMTI_VERBOSE_OTHER = 0,
    JVMTI_VERBOSE_GC = 1,
    JVMTI_VERBOSE_CLASS = 2,
    JVMTI_VERBOSE_JNI = 4
} jvmtiVerboseFlag;
jvmtiError
SetVerboseFlag(jvmtiEnv* env,
            jvmtiVerboseFlag flag,
            jboolean value)
Verbose Flag Enumeration (jvmtiVerboseFlag)
Constant | Value | Description
JVMTI_VERBOSE_OTHER | 0 | Verbose output other than the below.
JVMTI_VERBOSE_GC | 1 | Verbose garbage collector output, like that specified with -verbose:gc.
JVMTI_VERBOSE_CLASS | 2 | Verbose class loading output, like that specified with -verbose:class.
JVMTI_VERBOSE_JNI | 4 | Verbose JNI output, like that specified with -verbose:jni.
Control verbose output. This is the output which typically is sent to stderr.

Phase | Callback Safe | Position | Since
may be called during any phase | No | 150 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
flag | jvmtiVerboseFlag | Which verbose flag to set.
value | jboolean | New value of the flag.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_ILLEGAL_ARGUMENT | flag is not a jvmtiVerboseFlag.

Get JLocation Format

typedef enum {
    JVMTI_JLOCATION_JVMBCI = 1,
    JVMTI_JLOCATION_MACHINEPC = 2,
    JVMTI_JLOCATION_OTHER = 0
} jvmtiJlocationFormat;
jvmtiError
GetJLocationFormat(jvmtiEnv* env,
            jvmtiJlocationFormat* format_ptr)
Although the greatest functionality is achieved with location information referencing the virtual machine bytecode index, the definition of jlocation has intentionally been left unconstrained to allow VM implementations that do not have this information.

This function describes the representation of jlocation used in this VM. If the returned format is JVMTI_JLOCATION_JVMBCI, jlocations can be used as in indices into the array returned by GetBytecodes.
JLocation Format Enumeration (jvmtiJlocationFormat)
Constant | Value | Description
JVMTI_JLOCATION_JVMBCI | 1 | jlocation values represent virtual machine bytecode indices--that is, offsets into the virtual machine code for a method.
JVMTI_JLOCATION_MACHINEPC | 2 | jlocation values represent native machine program counter values.
JVMTI_JLOCATION_OTHER | 0 | jlocation values have some other representation.

Phase | Callback Safe | Position | Since
may be called during any phase | No | 129 | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
format_ptr | jvmtiJlocationFormat* | On return, points to the format identifier for jlocation values. Agent passes a pointer to a jvmtiJlocationFormat. On return, the jvmtiJlocationFormat has been set.

Errors
This function returns either a universal error or one of the following errors
Error | Description
JVMTI_ERROR_NULL_POINTER | format_ptr is NULL.

Errors

Every JVM TI function returns a jvmtiError error code.

It is the responsibility of the agent to call JVM TI functions with valid parameters and in the proper context (calling thread is attached, phase is correct, etc.). Detecting some error conditions may be difficult, inefficient, or impossible for an implementation. The errors listed in Function Specific Required Errors must be detected by the implementation. All other errors represent the recommended response to the error condition.

Universal Errors

The following errors may be returned by any function

JVMTI_ERROR_NONE (0)
No error has occurred. This is the error code that is returned on successful completion of the function.

JVMTI_ERROR_NULL_POINTER (100)
Pointer is unexpectedly NULL.

JVMTI_ERROR_OUT_OF_MEMORY (110)
The function attempted to allocate memory and no more memory was available for allocation.

JVMTI_ERROR_ACCESS_DENIED (111)
The desired functionality has not been enabled in this virtual machine.

JVMTI_ERROR_UNATTACHED_THREAD (115)
The thread being used to call this function is not attached to the virtual machine. Calls must be made from attached threads. See AttachCurrentThread in the JNI invocation API.

JVMTI_ERROR_INVALID_ENVIRONMENT (116)
The JVM TI environment provided is no longer connected or is not an environment.

JVMTI_ERROR_WRONG_PHASE (112)
The desired functionality is not available in the current phase. Always returned if the virtual machine has completed running.

JVMTI_ERROR_INTERNAL (113)
An unexpected internal error has occurred.

Function Specific Required Errors

The following errors are returned by some JVM TI functions and must be returned by the implementation when the condition occurs.

JVMTI_ERROR_INVALID_PRIORITY (12)
Invalid priority.

JVMTI_ERROR_THREAD_NOT_SUSPENDED (13)
Thread was not suspended.

JVMTI_ERROR_THREAD_SUSPENDED (14)
Thread already suspended.

JVMTI_ERROR_THREAD_NOT_ALIVE (15)
This operation requires the thread to be alive--that is, it must be started and not yet have died.

JVMTI_ERROR_CLASS_NOT_PREPARED (22)
The class has been loaded but not yet prepared.

JVMTI_ERROR_NO_MORE_FRAMES (31)
There are no Java programming language or JNI stack frames at the specified depth.

JVMTI_ERROR_OPAQUE_FRAME (32)
Information about the frame is not available (e.g. for native frames).

JVMTI_ERROR_DUPLICATE (40)
Item already set.

JVMTI_ERROR_NOT_FOUND (41)
Desired element (e.g. field or breakpoint) not found

JVMTI_ERROR_NOT_MONITOR_OWNER (51)
This thread doesn't own the raw monitor.

JVMTI_ERROR_INTERRUPT (52)
The call has been interrupted before completion.

JVMTI_ERROR_UNMODIFIABLE_CLASS (79)
The class cannot be modified.

JVMTI_ERROR_NOT_AVAILABLE (98)
The functionality is not available in this virtual machine.

JVMTI_ERROR_ABSENT_INFORMATION (101)
The requested information is not available.

JVMTI_ERROR_INVALID_EVENT_TYPE (102)
The specified event type ID is not recognized.

JVMTI_ERROR_NATIVE_METHOD (104)
The requested information is not available for native method.

JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED (106)
The class loader does not support this operation.

Function Specific Agent Errors

The following errors are returned by some JVM TI functions. They are returned in the event of invalid parameters passed by the agent or usage in an invalid context. An implementation is not required to detect these errors.

JVMTI_ERROR_INVALID_THREAD (10)
The passed thread is not a valid thread.

JVMTI_ERROR_INVALID_FIELDID (25)
Invalid field.

JVMTI_ERROR_INVALID_METHODID (23)
Invalid method.

JVMTI_ERROR_INVALID_LOCATION (24)
Invalid location.

JVMTI_ERROR_INVALID_OBJECT (20)
Invalid object.

JVMTI_ERROR_INVALID_CLASS (21)
Invalid class.

JVMTI_ERROR_TYPE_MISMATCH (34)
The variable is not an appropriate type for the function used.

JVMTI_ERROR_INVALID_SLOT (35)
Invalid slot.

JVMTI_ERROR_MUST_POSSESS_CAPABILITY (99)
The capability being used is false in this environment.

JVMTI_ERROR_INVALID_THREAD_GROUP (11)
Thread group invalid.

JVMTI_ERROR_INVALID_MONITOR (50)
Invalid raw monitor.

JVMTI_ERROR_ILLEGAL_ARGUMENT (103)
Illegal argument.

JVMTI_ERROR_INVALID_TYPESTATE (65)
The state of the thread has been modified, and is now inconsistent.

JVMTI_ERROR_UNSUPPORTED_VERSION (68)
A new class file has a version number not supported by this VM.

JVMTI_ERROR_INVALID_CLASS_FORMAT (60)
A new class file is malformed (the VM would return a ClassFormatError).

JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION (61)
The new class file definitions would lead to a circular definition (the VM would return a ClassCircularityError).

JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED (63)
A new class file would require adding a method.

JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED (64)
A new class version changes a field.

JVMTI_ERROR_FAILS_VERIFICATION (62)
The class bytes fail verification.

JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED (66)
A direct superclass is different for the new class version, or the set of directly implemented interfaces is different.

JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED (67)
A new class version does not declare a method declared in the old class version.

JVMTI_ERROR_NAMES_DONT_MATCH (69)
The class name defined in the new class file is different from the name in the old class object.

JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED (70)
A new class version has different modifiers.

JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED (71)
A method in the new class version has different modifiers than its counterpart in the old class version.

Data Types

JVM TI extends the data types defined by JNI.

JNI Types Used in the JVM Tool Interface
Type | Description
jboolean | Holds a Java programming language boolean. Unsigned 8 bits.
jint | Holds a Java programming language int. Signed 32 bits.
jlong | Holds a Java programming language long. Signed 64 bits.
jfloat | Holds a Java programming language float. 32 bits.
jdouble | Holds a Java programming language double. 64 bits.
jobject | Holds a Java programming language object.
jclass | Holds a Java programming language class.
jvalue | Is a union of all primitive types and jobject. Thus, holds any Java programming language value.
jfieldID | Identifies a Java programming language field. jfieldIDs returned by JVM TI functions and events may be safely stored.
jmethodID | Identifies a Java programming language method, initializer, or constructor. jmethodIDs returned by JVM TI functions and events may be safely stored. However, if the class is unloaded, they become invalid and must not be used.
JNIEnv | Pointer to the JNI function table. Pointer to this (JNIEnv *) is a JNI environment.

JVM Tool Interface Base Types
Type | Description
jvmtiEnv | The JVM TI environment pointer. See the Function Section. jvmtiEnv points to the function table pointer.
jthread | Subtype of jobject that holds a thread.
typedef jobject jthread;
jthreadGroup | Subtype of jobject that holds a thread group.
typedef jobject jthreadGroup;
jlocation | A 64 bit value, representing a monotonically increasing executable position within a method. -1 indicates a native method. See GetJLocationFormat for the format on a given VM.
typedef jlong jlocation;
jrawMonitorID | A raw monitor.
struct _jrawMonitorID;
typedef struct _jrawMonitorID *jrawMonitorID;
jvmtiError Holds an error return code. See the Error section for possible values.
typedef enum {
    JVMTI_ERROR_NONE = 0,
    JVMTI_ERROR_INVALID_THREAD = 10,
      ...
} jvmtiError;
jvmtiEvent An identifier for an event type. See the Event section for possible values. It is guaranteed that future versions of this specification will never assign zero as an event type identifier.
typedef enum {
    JVMTI_EVENT_SINGLE_STEP = 1,
    JVMTI_EVENT_BREAKPOINT = 2,
      ...
} jvmtiEvent;
jvmtiEventCallbacks The callbacks used for events.
typedef struct {
    jvmtiEventVMInit VMInit;
    jvmtiEventVMDeath VMDeath;
      ...
} jvmtiEventCallbacks;
See event callbacks for the complete structure.

Where, for example, the VM initialization callback is defined:
typedef void (JNICALL *jvmtiEventVMInit)
    (jvmtiEnv *jvmti_env,
     JNIEnv* jni_env,
     jthread thread);
See the individual events for the callback function definition.
jniNativeInterface | Typedef for the JNI function table JNINativeInterface defined in the JNI Specification. The JNI reference implementation defines this with an underscore.
typedef struct JNINativeInterface_ jniNativeInterface;

Structure Type Definitions
Type | Description
jvmtiAddrLocationMap | Native address to location entry
jvmtiCapabilities | The Capabilities Structure
jvmtiClassDefinition | Class redefinition description
jvmtiExtensionEventInfo | Extension Event Info
jvmtiExtensionFunctionInfo | Extension Function Info
jvmtiFrameInfo | Stack frame information structure
jvmtiHeapCallbacks | Heap callback function structure
jvmtiHeapReferenceInfo | Reference information structure
jvmtiHeapReferenceInfoArray | Reference information structure for Array references
jvmtiHeapReferenceInfoConstantPool | Reference information structure for Constant Pool references
jvmtiHeapReferenceInfoField | Reference information structure for Field references
jvmtiHeapReferenceInfoJniLocal | Reference information structure for JNI local references
jvmtiHeapReferenceInfoReserved | Reference information structure for Other references
jvmtiHeapReferenceInfoStackLocal | Reference information structure for Local Variable references
jvmtiLineNumberEntry | Line number table entry
jvmtiLocalVariableEntry | Local variable table entry
jvmtiMonitorStackDepthInfo | Monitor stack depth information structure
jvmtiMonitorUsage | Object monitor usage information
jvmtiParamInfo | Extension Function/Event Parameter Info
jvmtiStackInfo | Stack information structure
jvmtiThreadGroupInfo | Thread group information structure
jvmtiThreadInfo | Thread information structure
jvmtiTimerInfo | Timer Info

Function Type Definitions
Type | Description
jvmtiArrayPrimitiveValueCallback | Array Primitive Value Callback
jvmtiExtensionEvent | Extension Event
jvmtiExtensionFunction | Extension Function
jvmtiHeapIterationCallback | Heap Iteration Callback
jvmtiHeapObjectCallback | Heap Object Callback
jvmtiHeapReferenceCallback | Heap Reference Callback
jvmtiHeapRootCallback | Heap Root Object Callback
jvmtiObjectReferenceCallback | Object Reference Callback
jvmtiPrimitiveFieldCallback | Primitive Field Callback
jvmtiReservedCallback | reserved for future use Callback
jvmtiStackReferenceCallback | Stack Reference Object Callback
jvmtiStartFunction | Agent Start Function
jvmtiStringPrimitiveValueCallback | String Primitive Value Callback

Enumeration Definitions
Type | Description
jvmtiEventMode | Event Enable/Disable
jvmtiHeapObjectFilter | Heap Object Filter Enumeration
jvmtiHeapReferenceKind | Heap Reference Enumeration
jvmtiHeapRootKind | Heap Root Kind Enumeration
jvmtiIterationControl | Iteration Control Enumeration
jvmtiJlocationFormat | JLocation Format Enumeration
jvmtiObjectReferenceKind | Object Reference Enumeration
jvmtiParamKind | Extension Function/Event Parameter Kinds
jvmtiParamTypes | Extension Function/Event Parameter Types
jvmtiPhase | Phases of execution
jvmtiPrimitiveType | Primitive Type Enumeration
jvmtiTimerKind | Timer Kinds
jvmtiVerboseFlag | Verbose Flag Enumeration

Function Table Layout
Position Function Declaration
1 reserved
void *reserved1;
2 Set Event Notification Mode
jvmtiError (JNICALL *SetEventNotificationMode) (jvmtiEnv* env,
                       jvmtiEventMode mode,
                       jvmtiEvent event_type,
                       jthread event_thread,
                        ...);
3 reserved
void *reserved3;
4 Get All Threads
jvmtiError (JNICALL *GetAllThreads) (jvmtiEnv* env,
                       jint* threads_count_ptr,
                       jthread** threads_ptr);
5 Suspend Thread
jvmtiError (JNICALL *SuspendThread) (jvmtiEnv* env,
                       jthread thread);
6 Resume Thread
jvmtiError (JNICALL *ResumeThread) (jvmtiEnv* env,
                       jthread thread);
7 Stop Thread
jvmtiError (JNICALL *StopThread) (jvmtiEnv* env,
                       jthread thread,
                       jobject exception);
8 Interrupt Thread
jvmtiError (JNICALL *InterruptThread) (jvmtiEnv* env,
                       jthread thread);
9 Get Thread Info
jvmtiError (JNICALL *GetThreadInfo) (jvmtiEnv* env,
                       jthread thread,
                       jvmtiThreadInfo* info_ptr);
10 Get Owned Monitor Info
jvmtiError (JNICALL *GetOwnedMonitorInfo) (jvmtiEnv* env,
                       jthread thread,
                       jint* owned_monitor_count_ptr,
                       jobject** owned_monitors_ptr);
11 Get Current Contended Monitor
jvmtiError (JNICALL *GetCurrentContendedMonitor) (jvmtiEnv* env,
                       jthread thread,
                       jobject* monitor_ptr);
12 Run Agent Thread
jvmtiError (JNICALL *RunAgentThread) (jvmtiEnv* env,
                       jthread thread,
                       jvmtiStartFunction proc,
                       const void* arg,
                       jint priority);
13 Get Top Thread Groups
jvmtiError (JNICALL *GetTopThreadGroups) (jvmtiEnv* env,
                       jint* group_count_ptr,
                       jthreadGroup** groups_ptr);
14 Get Thread Group Info
jvmtiError (JNICALL *GetThreadGroupInfo) (jvmtiEnv* env,
                       jthreadGroup group,
                       jvmtiThreadGroupInfo* info_ptr);
15 Get Thread Group Children
jvmtiError (JNICALL *GetThreadGroupChildren) (jvmtiEnv* env,
                       jthreadGroup group,
                       jint* thread_count_ptr,
                       jthread** threads_ptr,
                       jint* group_count_ptr,
                       jthreadGroup** groups_ptr);
16 Get Frame Count
jvmtiError (JNICALL *GetFrameCount) (jvmtiEnv* env,
                       jthread thread,
                       jint* count_ptr);
17 Get Thread State
jvmtiError (JNICALL *GetThreadState) (jvmtiEnv* env,
                       jthread thread,
                       jint* thread_state_ptr);
18 Get Current Thread
jvmtiError (JNICALL *GetCurrentThread) (jvmtiEnv* env,
                       jthread* thread_ptr);
19 Get Frame Location
jvmtiError (JNICALL *GetFrameLocation) (jvmtiEnv* env,
                       jthread thread,
                       jint depth,
                       jmethodID* method_ptr,
                       jlocation* location_ptr);
20 Notify Frame Pop
jvmtiError (JNICALL *NotifyFramePop) (jvmtiEnv* env,
                       jthread thread,
                       jint depth);
21 Get Local Variable - Object
jvmtiError (JNICALL *GetLocalObject) (jvmtiEnv* env,
                       jthread thread,
                       jint depth,
                       jint slot,
                       jobject* value_ptr);
22 Get Local Variable - Int
jvmtiError (JNICALL *GetLocalInt) (jvmtiEnv* env,
                       jthread thread,
                       jint depth,
                       jint slot,
                       jint* value_ptr);
23 Get Local Variable - Long
jvmtiError (JNICALL *GetLocalLong) (jvmtiEnv* env,
                       jthread thread,
                       jint depth,
                       jint slot,
                       jlong* value_ptr);
24 Get Local Variable - Float
jvmtiError (JNICALL *GetLocalFloat) (jvmtiEnv* env,
                       jthread thread,
                       jint depth,
                       jint slot,
                       jfloat* value_ptr);
25 Get Local Variable - Double
jvmtiError (JNICALL *GetLocalDouble) (jvmtiEnv* env,
                       jthread thread,
                       jint depth,
                       jint slot,
                       jdouble* value_ptr);
26 Set Local Variable - Object
jvmtiError (JNICALL *SetLocalObject) (jvmtiEnv* env,
                       jthread thread,
                       jint depth,
                       jint slot,
                       jobject value);
27 Set Local Variable - Int
jvmtiError (JNICALL *SetLocalInt) (jvmtiEnv* env,
                       jthread thread,
                       jint depth,
                       jint slot,
                       jint value);
28 Set Local Variable - Long
jvmtiError (JNICALL *SetLocalLong) (jvmtiEnv* env,
                       jthread thread,
                       jint depth,
                       jint slot,
                       jlong value);
29 Set Local Variable - Float
jvmtiError (JNICALL *SetLocalFloat) (jvmtiEnv* env,
                       jthread thread,
                       jint depth,
                       jint slot,
                       jfloat value);
30 Set Local Variable - Double
jvmtiError (JNICALL *SetLocalDouble) (jvmtiEnv* env,
                       jthread thread,
                       jint depth,
                       jint slot,
                       jdouble value);
31 Create Raw Monitor
jvmtiError (JNICALL *CreateRawMonitor) (jvmtiEnv* env,
                       const char* name,
                       jrawMonitorID* monitor_ptr);
32 Destroy Raw Monitor
jvmtiError (JNICALL *DestroyRawMonitor) (jvmtiEnv* env,
                       jrawMonitorID monitor);
33 Raw Monitor Enter
jvmtiError (JNICALL *RawMonitorEnter) (jvmtiEnv* env,
                       jrawMonitorID monitor);
34 Raw Monitor Exit
jvmtiError (JNICALL *RawMonitorExit) (jvmtiEnv* env,
                       jrawMonitorID monitor);
35 Raw Monitor Wait
jvmtiError (JNICALL *RawMonitorWait) (jvmtiEnv* env,
                       jrawMonitorID monitor,
                       jlong millis);
36 Raw Monitor Notify
jvmtiError (JNICALL *RawMonitorNotify) (jvmtiEnv* env,
                       jrawMonitorID monitor);
37 Raw Monitor Notify All
jvmtiError (JNICALL *RawMonitorNotifyAll) (jvmtiEnv* env,
                       jrawMonitorID monitor);
38 Set Breakpoint
jvmtiError (JNICALL *SetBreakpoint) (jvmtiEnv* env,
                       jmethodID method,
                       jlocation location);
39 Clear Breakpoint
jvmtiError (JNICALL *ClearBreakpoint) (jvmtiEnv* env,
                       jmethodID method,
                       jlocation location);
40 reserved
void *reserved40;
41 Set Field Access Watch
jvmtiError (JNICALL *SetFieldAccessWatch) (jvmtiEnv* env,
                       jclass klass,
                       jfieldID field);
42 Clear Field Access Watch
jvmtiError (JNICALL *ClearFieldAccessWatch) (jvmtiEnv* env,
                       jclass klass,
                       jfieldID field);
43 Set Field Modification Watch
jvmtiError (JNICALL *SetFieldModificationWatch) (jvmtiEnv* env,
                       jclass klass,
                       jfieldID field);
44 Clear Field Modification Watch
jvmtiError (JNICALL *ClearFieldModificationWatch) (jvmtiEnv* env,
                       jclass klass,
                       jfieldID field);
45 Is Modifiable Class
jvmtiError (JNICALL *IsModifiableClass) (jvmtiEnv* env,
                       jclass klass,
                       jboolean* is_modifiable_class_ptr);
46 Allocate
jvmtiError (JNICALL *Allocate) (jvmtiEnv* env,
                       jlong size,
                       unsigned char** mem_ptr);
47 Deallocate
jvmtiError (JNICALL *Deallocate) (jvmtiEnv* env,
                       unsigned char* mem);
48 Get Class Signature
jvmtiError (JNICALL *GetClassSignature) (jvmtiEnv* env,
                       jclass klass,
                       char** signature_ptr,
                       char** generic_ptr);
49 Get Class Status
jvmtiError (JNICALL *GetClassStatus) (jvmtiEnv* env,
                       jclass klass,
                       jint* status_ptr);
50 Get Source File Name
jvmtiError (JNICALL *GetSourceFileName) (jvmtiEnv* env,
                       jclass klass,
                       char** source_name_ptr);
51 Get Class Modifiers
jvmtiError (JNICALL *GetClassModifiers) (jvmtiEnv* env,
                       jclass klass,
                       jint* modifiers_ptr);
52 Get Class Methods
jvmtiError (JNICALL *GetClassMethods) (jvmtiEnv* env,
                       jclass klass,
                       jint* method_count_ptr,
                       jmethodID** methods_ptr);
53 Get Class Fields
jvmtiError (JNICALL *GetClassFields) (jvmtiEnv* env,
                       jclass klass,
                       jint* field_count_ptr,
                       jfieldID** fields_ptr);
54 Get Implemented Interfaces
jvmtiError (JNICALL *GetImplementedInterfaces) (jvmtiEnv* env,
                       jclass klass,
                       jint* interface_count_ptr,
                       jclass** interfaces_ptr);
55 Is Interface
jvmtiError (JNICALL *IsInterface) (jvmtiEnv* env,
                       jclass klass,
                       jboolean* is_interface_ptr);
56 Is Array Class
jvmtiError (JNICALL *IsArrayClass) (jvmtiEnv* env,
                       jclass klass,
                       jboolean* is_array_class_ptr);
57 Get Class Loader
jvmtiError (JNICALL *GetClassLoader) (jvmtiEnv* env,
                       jclass klass,
                       jobject* classloader_ptr);
58 Get Object Hash Code
jvmtiError (JNICALL *GetObjectHashCode) (jvmtiEnv* env,
                       jobject object,
                       jint* hash_code_ptr);
59 Get Object Monitor Usage
jvmtiError (JNICALL *GetObjectMonitorUsage) (jvmtiEnv* env,
                       jobject object,
                       jvmtiMonitorUsage* info_ptr);
60 Get Field Name (and Signature)
jvmtiError (JNICALL *GetFieldName) (jvmtiEnv* env,
                       jclass klass,
                       jfieldID field,
                       char** name_ptr,
                       char** signature_ptr,
                       char** generic_ptr);
61 Get Field Declaring Class
jvmtiError (JNICALL *GetFieldDeclaringClass) (jvmtiEnv* env,
                       jclass klass,
                       jfieldID field,
                       jclass* declaring_class_ptr);
62 Get Field Modifiers
jvmtiError (JNICALL *GetFieldModifiers) (jvmtiEnv* env,
                       jclass klass,
                       jfieldID field,
                       jint* modifiers_ptr);
63 Is Field Synthetic
jvmtiError (JNICALL *IsFieldSynthetic) (jvmtiEnv* env,
                       jclass klass,
                       jfieldID field,
                       jboolean* is_synthetic_ptr);
64 Get Method Name (and Signature)
jvmtiError (JNICALL *GetMethodName) (jvmtiEnv* env,
                       jmethodID method,
                       char** name_ptr,
                       char** signature_ptr,
                       char** generic_ptr);
65 Get Method Declaring Class
jvmtiError (JNICALL *GetMethodDeclaringClass) (jvmtiEnv* env,
                       jmethodID method,
                       jclass* declaring_class_ptr);
66 Get Method Modifiers
jvmtiError (JNICALL *GetMethodModifiers) (jvmtiEnv* env,
                       jmethodID method,
                       jint* modifiers_ptr);
67 reserved
void *reserved67;
68 Get Max Locals
jvmtiError (JNICALL *GetMaxLocals) (jvmtiEnv* env,
                       jmethodID method,
                       jint* max_ptr);
69 Get Arguments Size
jvmtiError (JNICALL *GetArgumentsSize) (jvmtiEnv* env,
                       jmethodID method,
                       jint* size_ptr);
70 Get Line Number Table
jvmtiError (JNICALL *GetLineNumberTable) (jvmtiEnv* env,
                       jmethodID method,
                       jint* entry_count_ptr,
                       jvmtiLineNumberEntry** table_ptr);
71 Get Method Location
jvmtiError (JNICALL *GetMethodLocation) (jvmtiEnv* env,
                       jmethodID method,
                       jlocation* start_location_ptr,
                       jlocation* end_location_ptr);
72 Get Local Variable Table
jvmtiError (JNICALL *GetLocalVariableTable) (jvmtiEnv* env,
                       jmethodID method,
                       jint* entry_count_ptr,
                       jvmtiLocalVariableEntry** table_ptr);
73 Set Native Method Prefix
jvmtiError (JNICALL *SetNativeMethodPrefix) (jvmtiEnv* env,
                       const char* prefix);
74 Set Native Method Prefixes
jvmtiError (JNICALL *SetNativeMethodPrefixes) (jvmtiEnv* env,
                       jint prefix_count,
                       char** prefixes);
75 Get Bytecodes
jvmtiError (JNICALL *GetBytecodes) (jvmtiEnv* env,
                       jmethodID method,
                       jint* bytecode_count_ptr,
                       unsigned char** bytecodes_ptr);
76 Is Method Native
jvmtiError (JNICALL *IsMethodNative) (jvmtiEnv* env,
                       jmethodID method,
                       jboolean* is_native_ptr);
77 Is Method Synthetic
jvmtiError (JNICALL *IsMethodSynthetic) (jvmtiEnv* env,
                       jmethodID method,
                       jboolean* is_synthetic_ptr);
78 Get Loaded Classes
jvmtiError (JNICALL *GetLoadedClasses) (jvmtiEnv* env,
                       jint* class_count_ptr,
                       jclass** classes_ptr);
79 Get Classloader Classes
jvmtiError (JNICALL *GetClassLoaderClasses) (jvmtiEnv* env,
                       jobject initiating_loader,
                       jint* class_count_ptr,
                       jclass** classes_ptr);
80 Pop Frame
jvmtiError (JNICALL *PopFrame) (jvmtiEnv* env,
                       jthread thread);
81 Force Early Return - Object
jvmtiError (JNICALL *ForceEarlyReturnObject) (jvmtiEnv* env,
                       jthread thread,
                       jobject value);
82 Force Early Return - Int
jvmtiError (JNICALL *ForceEarlyReturnInt) (jvmtiEnv* env,
                       jthread thread,
                       jint value);
83 Force Early Return - Long
jvmtiError (JNICALL *ForceEarlyReturnLong) (jvmtiEnv* env,
                       jthread thread,
                       jlong value);
84 Force Early Return - Float
jvmtiError (JNICALL *ForceEarlyReturnFloat) (jvmtiEnv* env,
                       jthread thread,
                       jfloat value);
85 Force Early Return - Double
jvmtiError (JNICALL *ForceEarlyReturnDouble) (jvmtiEnv* env,
                       jthread thread,
                       jdouble value);
86 Force Early Return - Void
jvmtiError (JNICALL *ForceEarlyReturnVoid) (jvmtiEnv* env,
                       jthread thread);
87 Redefine Classes
jvmtiError (JNICALL *RedefineClasses) (jvmtiEnv* env,
                       jint class_count,
                       const jvmtiClassDefinition* class_definitions);
88 Get Version Number
jvmtiError (JNICALL *GetVersionNumber) (jvmtiEnv* env,
                       jint* version_ptr);
89 Get Capabilities
jvmtiError (JNICALL *GetCapabilities) (jvmtiEnv* env,
                       jvmtiCapabilities* capabilities_ptr);
90 Get Source Debug Extension
jvmtiError (JNICALL *GetSourceDebugExtension) (jvmtiEnv* env,
                       jclass klass,
                       char** source_debug_extension_ptr);
91 Is Method Obsolete
jvmtiError (JNICALL *IsMethodObsolete) (jvmtiEnv* env,
                       jmethodID method,
                       jboolean* is_obsolete_ptr);
92 Suspend Thread List
jvmtiError (JNICALL *SuspendThreadList) (jvmtiEnv* env,
                       jint request_count,
                       const jthread* request_list,
                       jvmtiError* results);
93 Resume Thread List
jvmtiError (JNICALL *ResumeThreadList) (jvmtiEnv* env,
                       jint request_count,
                       const jthread* request_list,
                       jvmtiError* results);
94 reserved
void *reserved94;
95 reserved
void *reserved95;
96 reserved
void *reserved96;
97 reserved
void *reserved97;
98 reserved
void *reserved98;
99 reserved
void *reserved99;
100 Get All Stack Traces
jvmtiError (JNICALL *GetAllStackTraces) (jvmtiEnv* env,
                       jint max_frame_count,
                       jvmtiStackInfo** stack_info_ptr,
                       jint* thread_count_ptr);
101 Get Thread List Stack Traces
jvmtiError (JNICALL *GetThreadListStackTraces) (jvmtiEnv* env,
                       jint thread_count,
                       const jthread* thread_list,
                       jint max_frame_count,
                       jvmtiStackInfo** stack_info_ptr);
102 Get Thread Local Storage
jvmtiError (JNICALL *GetThreadLocalStorage) (jvmtiEnv* env,
                       jthread thread,
                       void** data_ptr);
103 Set Thread Local Storage
jvmtiError (JNICALL *SetThreadLocalStorage) (jvmtiEnv* env,
                       jthread thread,
                       const void* data);
104 Get Stack Trace
jvmtiError (JNICALL *GetStackTrace) (jvmtiEnv* env,
                       jthread thread,
                       jint start_depth,
                       jint max_frame_count,
                       jvmtiFrameInfo* frame_buffer,
                       jint* count_ptr);
105 reserved
void *reserved105;
106 Get Tag
jvmtiError (JNICALL *GetTag) (jvmtiEnv* env,
                       jobject object,
                       jlong* tag_ptr);
107 Set Tag
jvmtiError (JNICALL *SetTag) (jvmtiEnv* env,
                       jobject object,
                       jlong tag);
108 Force Garbage Collection
jvmtiError (JNICALL *ForceGarbageCollection) (jvmtiEnv* env);
109 Iterate Over Objects Reachable From Object
jvmtiError (JNICALL *IterateOverObjectsReachableFromObject) (jvmtiEnv* env,
                       jobject object,
                       jvmtiObjectReferenceCallback object_reference_callback,
                       const void* user_data);
110 Iterate Over Reachable Objects
jvmtiError (JNICALL *IterateOverReachableObjects) (jvmtiEnv* env,
                       jvmtiHeapRootCallback heap_root_callback,
                       jvmtiStackReferenceCallback stack_ref_callback,
                       jvmtiObjectReferenceCallback object_ref_callback,
                       const void* user_data);
111 Iterate Over Heap
jvmtiError (JNICALL *IterateOverHeap) (jvmtiEnv* env,
                       jvmtiHeapObjectFilter object_filter,
                       jvmtiHeapObjectCallback heap_object_callback,
                       const void* user_data);
112 Iterate Over Instances Of Class
jvmtiError (JNICALL *IterateOverInstancesOfClass) (jvmtiEnv* env,
                       jclass klass,
                       jvmtiHeapObjectFilter object_filter,
                       jvmtiHeapObjectCallback heap_object_callback,
                       const void* user_data);
113 reserved
void *reserved113;
114 Get Objects With Tags
jvmtiError (JNICALL *GetObjectsWithTags) (jvmtiEnv* env,
                       jint tag_count,
                       const jlong* tags,
                       jint* count_ptr,
                       jobject** object_result_ptr,
                       jlong** tag_result_ptr);
115 Follow References
jvmtiError (JNICALL *FollowReferences) (jvmtiEnv* env,
                       jint heap_filter,
                       jclass klass,
                       jobject initial_object,
                       const jvmtiHeapCallbacks* callbacks,
                       const void* user_data);
116 Iterate Through Heap
jvmtiError (JNICALL *IterateThroughHeap) (jvmtiEnv* env,
                       jint heap_filter,
                       jclass klass,
                       const jvmtiHeapCallbacks* callbacks,
                       const void* user_data);
117 reserved
void *reserved117;
118 reserved
void *reserved118;
119 reserved
void *reserved119;
120 Set JNI Function Table
jvmtiError (JNICALL *SetJNIFunctionTable) (jvmtiEnv* env,
                       const jniNativeInterface* function_table);
121 Get JNI Function Table
jvmtiError (JNICALL *GetJNIFunctionTable) (jvmtiEnv* env,
                       jniNativeInterface** function_table);
122 Set Event Callbacks
jvmtiError (JNICALL *SetEventCallbacks) (jvmtiEnv* env,
                       const jvmtiEventCallbacks* callbacks,
                       jint size_of_callbacks);
123 Generate Events
jvmtiError (JNICALL *GenerateEvents) (jvmtiEnv* env,
                       jvmtiEvent event_type);
124 Get Extension Functions
jvmtiError (JNICALL *GetExtensionFunctions) (jvmtiEnv* env,
                       jint* extension_count_ptr,
                       jvmtiExtensionFunctionInfo** extensions);
125 Get Extension Events
jvmtiError (JNICALL *GetExtensionEvents) (jvmtiEnv* env,
                       jint* extension_count_ptr,
                       jvmtiExtensionEventInfo** extensions);
126 Set Extension Event Callback
jvmtiError (JNICALL *SetExtensionEventCallback) (jvmtiEnv* env,
                       jint extension_event_index,
                       jvmtiExtensionEvent callback);
127 Dispose Environment
jvmtiError (JNICALL *DisposeEnvironment) (jvmtiEnv* env);
128 Get Error Name
jvmtiError (JNICALL *GetErrorName) (jvmtiEnv* env,
                       jvmtiError error,
                       char** name_ptr);
129 Get JLocation Format
jvmtiError (JNICALL *GetJLocationFormat) (jvmtiEnv* env,
                       jvmtiJlocationFormat* format_ptr);
130 Get System Properties
jvmtiError (JNICALL *GetSystemProperties) (jvmtiEnv* env,
                       jint* count_ptr,
                       char*** property_ptr);
131 Get System Property
jvmtiError (JNICALL *GetSystemProperty) (jvmtiEnv* env,
                       const char* property,
                       char** value_ptr);
132 Set System Property
jvmtiError (JNICALL *SetSystemProperty) (jvmtiEnv* env,
                       const char* property,
                       const char* value);
133 Get Phase
jvmtiError (JNICALL *GetPhase) (jvmtiEnv* env,
                       jvmtiPhase* phase_ptr);
134 Get Current Thread CPU Timer Information
jvmtiError (JNICALL *GetCurrentThreadCpuTimerInfo) (jvmtiEnv* env,
                       jvmtiTimerInfo* info_ptr);
135 Get Current Thread CPU Time
jvmtiError (JNICALL *GetCurrentThreadCpuTime) (jvmtiEnv* env,
                       jlong* nanos_ptr);
136 Get Thread CPU Timer Information
jvmtiError (JNICALL *GetThreadCpuTimerInfo) (jvmtiEnv* env,
                       jvmtiTimerInfo* info_ptr);
137 Get Thread CPU Time
jvmtiError (JNICALL *GetThreadCpuTime) (jvmtiEnv* env,
                       jthread thread,
                       jlong* nanos_ptr);
138 Get Timer Information
jvmtiError (JNICALL *GetTimerInfo) (jvmtiEnv* env,
                       jvmtiTimerInfo* info_ptr);
139 Get Time
jvmtiError (JNICALL *GetTime) (jvmtiEnv* env,
                       jlong* nanos_ptr);
140 Get Potential Capabilities
jvmtiError (JNICALL *GetPotentialCapabilities) (jvmtiEnv* env,
                       jvmtiCapabilities* capabilities_ptr);
141 reserved
void *reserved141;
142 Add Capabilities
jvmtiError (JNICALL *AddCapabilities) (jvmtiEnv* env,
                       const jvmtiCapabilities* capabilities_ptr);
143 Relinquish Capabilities
jvmtiError (JNICALL *RelinquishCapabilities) (jvmtiEnv* env,
                       const jvmtiCapabilities* capabilities_ptr);
144 Get Available Processors
jvmtiError (JNICALL *GetAvailableProcessors) (jvmtiEnv* env,
                       jint* processor_count_ptr);
145 Get Class Version Numbers
jvmtiError (JNICALL *GetClassVersionNumbers) (jvmtiEnv* env,
                       jclass klass,
                       jint* minor_version_ptr,
                       jint* major_version_ptr);
146 Get Constant Pool
jvmtiError (JNICALL *GetConstantPool) (jvmtiEnv* env,
                       jclass klass,
                       jint* constant_pool_count_ptr,
                       jint* constant_pool_byte_count_ptr,
                       unsigned char** constant_pool_bytes_ptr);
147 Get Environment Local Storage
jvmtiError (JNICALL *GetEnvironmentLocalStorage) (jvmtiEnv* env,
                       void** data_ptr);
148 Set Environment Local Storage
jvmtiError (JNICALL *SetEnvironmentLocalStorage) (jvmtiEnv* env,
                       const void* data);
149 Add To Bootstrap Class Loader Search
jvmtiError (JNICALL *AddToBootstrapClassLoaderSearch) (jvmtiEnv* env,
                       const char* segment);
150 Set Verbose Flag
jvmtiError (JNICALL *SetVerboseFlag) (jvmtiEnv* env,
                       jvmtiVerboseFlag flag,
                       jboolean value);
151 Add To System Class Loader Search
jvmtiError (JNICALL *AddToSystemClassLoaderSearch) (jvmtiEnv* env,
                       const char* segment);
152 Retransform Classes
jvmtiError (JNICALL *RetransformClasses) (jvmtiEnv* env,
                       jint class_count,
                       const jclass* classes);
153 Get Owned Monitor Stack Depth Info
jvmtiError (JNICALL *GetOwnedMonitorStackDepthInfo) (jvmtiEnv* env,
                       jthread thread,
                       jint* monitor_info_count_ptr,
                       jvmtiMonitorStackDepthInfo** monitor_info_ptr);
154 Get Object Size
jvmtiError (JNICALL *GetObjectSize) (jvmtiEnv* env,
                       jobject object,
                       jlong* size_ptr);

Events

Handling Events

Agents can be informed of many events that occur in application programs.

To handle events, designate a set of callback functions with SetEventCallbacks. For each event the corresponding callback function will be called. Arguments to the callback function provide additional information about the event.

The callback function is usually called from within an application thread. The JVM TI implementation does not queue events in any way. This means that event callback functions must be written carefully. Here are some general guidelines. See the individual event descriptions for further suggestions.

  • Any exception thrown during the execution of an event callback can overwrite any current pending exception in the current application thread. Care must be taken to preserve a pending exception when an event callback makes a JNI call that might generate an exception.
  • Event callback functions must be re-entrant. The JVM TI implementation does not queue events. If an agent needs to process events one at a time, it can use a raw monitor inside the event callback functions to serialize event processing.
  • Event callback functions that execute JNI's FindClass function to load classes need to note that FindClass locates the class loader associated with the current native method. For the purposes of class loading, an event callback that includes a JNI environment as a parameter to the callback will treated as if it is a native call, where the native method is in the class of the event thread's current frame.

Some JVM TI events identify objects with JNI references. All references in JVM TI events are JNI local references and will become invalid after the event callback returns. Unless stated otherwise, memory referenced by pointers sent in event callbacks may not be referenced after the event callback returns.

Except where stated otherwise, events are delivered on the thread that caused the event. Events are sent at the time they occur. The specification for each event includes the set of phases in which it can be sent; if an event triggering activity occurs during another phase, no event is sent.

A thread that generates an event does not change its execution status (for example, the event does not cause the thread to be suspended). If an agent wishes the event to result in suspension, then the agent is responsible for explicitly suspending the thread with SuspendThread.

If an event is enabled in multiple environments, the event will be sent to each agent in the order that the environments were created.

Enabling Events

All events are initially disabled. In order to receive any event:
  • If the event requires a capability, that capability must be added with AddCapabilities.
  • A callback for the event must be set with SetEventCallbacks.
  • The event must be enabled with SetEventNotificationMode.

Multiple Co-located Events

In many situations it is possible for multiple events to occur at the same location in one thread. When this happens, all the events are reported through the event callbacks in the order specified in this section.

If the current location is at the entry point of a method, the MethodEntry event is reported before any other event at the current location in the same thread.

If an exception catch has been detected at the current location, either because it is the beginning of a catch clause or a native method that cleared a pending exception has returned, the exceptionCatch event is reported before any other event at the current location in the same thread.

If a singleStep event or breakpoint event is triggered at the current location, the event is defined to occur immediately before the code at the current location is executed. These events are reported before any events which are triggered by the execution of code at the current location in the same thread (specifically: exception, fieldAccess, and fieldModification). If both a step and breakpoint event are triggered for the same thread and location, the step event is reported before the breakpoint event.

If the current location is the exit point of a method (that is, the last location before returning to the caller), the MethodExit event and the FramePop event (if requested) are reported after all other events at the current location in the same thread. There is no specified ordering of these two events with respect to each other.

Co-located events can be triggered during the processing of some other event by the agent at the same location in the same thread. If such an event, of type y, is triggered during the processing of an event of type x, and if x precedes y in the ordering specified above, the co-located event y is reported for the current thread and location. If x does not precede y, y is not reported for the current thread and location. For example, if a breakpoint is set at the current location during the processing of SingleStep, that breakpoint will be reported before the thread moves off the current location.

The following events are never considered to be co-located with other events.
  • VMStart
  • VMInit
  • VMDeath
  • ThreadStart
  • ThreadEnd
  • ClassLoad
  • ClassPrepare

Event Callbacks

The event callback structure below is used to specify the handler function for events. It is set with the SetEventCallbacks function.
typedef struct {
    jvmtiEventVMInit VMInit;
    jvmtiEventVMDeath VMDeath;
    jvmtiEventThreadStart ThreadStart;
    jvmtiEventThreadEnd ThreadEnd;
    jvmtiEventClassFileLoadHook ClassFileLoadHook;
    jvmtiEventClassLoad ClassLoad;
    jvmtiEventClassPrepare ClassPrepare;
    jvmtiEventVMStart VMStart;
    jvmtiEventException Exception;
    jvmtiEventExceptionCatch ExceptionCatch;
    jvmtiEventSingleStep SingleStep;
    jvmtiEventFramePop FramePop;
    jvmtiEventBreakpoint Breakpoint;
    jvmtiEventFieldAccess FieldAccess;
    jvmtiEventFieldModification FieldModification;
    jvmtiEventMethodEntry MethodEntry;
    jvmtiEventMethodExit MethodExit;
    jvmtiEventNativeMethodBind NativeMethodBind;
    jvmtiEventCompiledMethodLoad CompiledMethodLoad;
    jvmtiEventCompiledMethodUnload CompiledMethodUnload;
    jvmtiEventDynamicCodeGenerated DynamicCodeGenerated;
    jvmtiEventDataDumpRequest DataDumpRequest;
    jvmtiEventReserved reserved72;
    jvmtiEventMonitorWait MonitorWait;
    jvmtiEventMonitorWaited MonitorWaited;
    jvmtiEventMonitorContendedEnter MonitorContendedEnter;
    jvmtiEventMonitorContendedEntered MonitorContendedEntered;
    jvmtiEventReserved reserved77;
    jvmtiEventReserved reserved78;
    jvmtiEventReserved reserved79;
    jvmtiEventResourceExhausted ResourceExhausted;
    jvmtiEventGarbageCollectionStart GarbageCollectionStart;
    jvmtiEventGarbageCollectionFinish GarbageCollectionFinish;
    jvmtiEventObjectFree ObjectFree;
    jvmtiEventVMObjectAlloc VMObjectAlloc;
} jvmtiEventCallbacks;

Event Index

  • Breakpoint
  • Class File Load Hook
  • Class Load
  • Class Prepare
  • Compiled Method Load
  • Compiled Method Unload
  • Data Dump Request
  • Dynamic Code Generated
  • Exception
  • Exception Catch
  • Field Access
  • Field Modification
  • Frame Pop
  • Garbage Collection Finish
  • Garbage Collection Start
  • Method Entry
  • Method Exit
  • Monitor Contended Enter
  • Monitor Contended Entered
  • Monitor Wait
  • Monitor Waited
  • Native Method Bind
  • Object Free
  • Resource Exhausted
  • Single Step
  • Thread End
  • Thread Start
  • VM Death Event
  • VM Initialization Event
  • VM Object Allocation
  • VM Start Event

Single Step

void JNICALL
SingleStep(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jmethodID method,
            jlocation location)
Single step events allow the agent to trace thread execution at the finest granularity allowed by the VM. A single step event is generated whenever a thread reaches a new location. Typically, single step events represent the completion of one VM instruction as defined in the Java Virtual Machine Specification. However, some implementations may define locations differently. In any case the method and location parameters uniquely identify the current location and allow the mapping to source file and line number when that information is available.

No single step events are generated from within native methods.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_SINGLE_STEP | 60 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_SINGLE_STEP, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_single_step_events | Can get single step events

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread
thread | jthread | Thread about to execution a new instruction
method | jmethodID | Method about to execute a new instruction
location | jlocation | Location of the new instruction

Breakpoint

void JNICALL
Breakpoint(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jmethodID method,
            jlocation location)
Breakpoint events are generated whenever a thread reaches a location designated as a breakpoint with SetBreakpoint. The method and location parameters uniquely identify the current location and allow the mapping to source file and line number when that information is available.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_BREAKPOINT | 62 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_BREAKPOINT, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_breakpoint_events | Can set and thus get Breakpoint events

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread.
thread | jthread | Thread that hit the breakpoint
method | jmethodID | Method that hit the breakpoint
location | jlocation | location of the breakpoint

Field Access

void JNICALL
FieldAccess(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jmethodID method,
            jlocation location,
            jclass field_klass,
            jobject object,
            jfieldID field)
Field access events are generated whenever a thread accesses a field that was designated as a watchpoint with SetFieldAccessWatch. The method and location parameters uniquely identify the current location and allow the mapping to source file and line number when that information is available.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_FIELD_ACCESS | 63 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_FIELD_ACCESS, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_field_access_events | Can set watchpoints on field access - SetFieldAccessWatch

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread
thread | jthread | Thread accessing the field
method | jmethodID | Method where the access is occurring
location | jlocation | Location where the access is occurring
field_klass | jclass | Class of the field being accessed
object | jobject | Object with the field being accessed if the field is an instance field; NULL otherwise
field | jfieldID | Field being accessed

Field Modification

void JNICALL
FieldModification(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jmethodID method,
            jlocation location,
            jclass field_klass,
            jobject object,
            jfieldID field,
            char signature_type,
            jvalue new_value)
Field modification events are generated whenever a thread modifies a field that was designated as a watchpoint with SetFieldModificationWatch. The method and location parameters uniquely identify the current location and allow the mapping to source file and line number when that information is available.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_FIELD_MODIFICATION | 64 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_FIELD_MODIFICATION, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_field_modification_events | Can set watchpoints on field modification - SetFieldModificationWatch

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread
thread | jthread | Thread modifying the field
method | jmethodID | Method where the modification is occurring
location | jlocation | Location where the modification is occurring
field_klass | jclass | Class of the field being modified
object | jobject | Object with the field being modified if the field is an instance field; NULL otherwise
field | jfieldID | Field being modified
signature_type | char | Signature type of the new value
new_value | jvalue | The new value

Frame Pop

void JNICALL
FramePop(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jmethodID method,
            jboolean was_popped_by_exception)
Frame pop events are generated upon exit from a single method in a single frame as specified in a call to NotifyFramePop. This is true whether termination is caused by executing its return instruction or by throwing an exception to its caller (see was_popped_by_exception). However, frame pops caused by the PopFrame function are not reported.

The location reported by GetFrameLocation identifies the executable location in the returning method, immediately prior to the return.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_FRAME_POP | 61 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_FRAME_POP, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_frame_pop_events | Can set and thus get FramePop events

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread
thread | jthread | Thread that is popping the frame
method | jmethodID | Method being popped
was_popped_by_exception | jboolean | True if frame was popped by a thrown exception. False if method exited through its return instruction.

Method Entry

void JNICALL
MethodEntry(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jmethodID method)
Method entry events are generated upon entry of Java programming language methods (including native methods).

The location reported by GetFrameLocation identifies the initial executable location in the method.

Enabling method entry or exit events will significantly degrade performance on many platforms and is thus not advised for performance critical usage (such as profiling). Bytecode instrumentation should be used in these cases.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_METHOD_ENTRY | 65 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_METHOD_ENTRY, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_method_entry_events | Can generate method entry events on entering a method

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread
thread | jthread | Thread entering the method
method | jmethodID | Method being entered

Method Exit

void JNICALL
MethodExit(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jmethodID method,
            jboolean was_popped_by_exception,
            jvalue return_value)
Method exit events are generated upon exit from Java programming language methods (including native methods). This is true whether termination is caused by executing its return instruction or by throwing an exception to its caller (see was_popped_by_exception).

The method field uniquely identifies the method being entered or exited. The frame field provides access to the stack frame for the method.

The location reported by GetFrameLocation identifies the executable location in the returning method immediately prior to the return.

Enabling method entry or exit events will significantly degrade performance on many platforms and is thus not advised for performance critical usage (such as profiling). Bytecode instrumentation should be used in these cases.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_METHOD_EXIT | 66 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_METHOD_EXIT, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_method_exit_events | Can generate method exit events on leaving a method

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread
thread | jthread | Thread exiting the method
method | jmethodID | Method being exited
was_popped_by_exception | jboolean | True if frame was popped by a thrown exception. False if method exited through its return instruction.
return_value | jvalue | The return value of the method being exited. Undefined and should not be used if was_popped_by_exception is true.

Native Method Bind

void JNICALL
NativeMethodBind(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jmethodID method,
            void* address,
            void** new_address_ptr)
A Native Method Bind event is sent when a VM binds a Java programming language native method to the address of a function that implements the native method. This will occur when the native method is called for the first time and also occurs when the JNI function RegisterNatives is called. This event allows the bind to be redirected to an agent-specified proxy function. This event is not sent when the native method is unbound. Typically, this proxy function will need to be specific to a particular method or, to handle the general case, automatically generated assembly code, since after instrumentation code is executed the function at the original binding address will usually be invoked. The original binding can be restored or the redirection changed by use of the JNI function RegisterNatives. Some events may be sent during the primordial phase, JNI and most of JVM TI cannot be used at this time but the method and address can be saved for use later.

Phase | Event Type | Number | Enabling | Since
sent during the primordial, start or live phase | JVMTI_EVENT_NATIVE_METHOD_BIND | 67 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_NATIVE_METHOD_BIND, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_native_method_bind_events | Can generate events when a native method is bound to its implementation

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread Will be NULL if sent during the primordial phase.
thread | jthread | Thread requesting the bind
method | jmethodID | Native method being bound
address | void* | The address the VM is about to bind to--that is, the address of the implementation of the native method
new_address_ptr | void** | if the referenced address is changed (that is, if *new_address_ptr is set), the binding will instead be made to the supplied address.

Exception

void JNICALL
Exception(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jmethodID method,
            jlocation location,
            jobject exception,
            jmethodID catch_method,
            jlocation catch_location)
Exception events are generated whenever an exception is first detected in a Java programming language method. Where "exception" means any java.lang.Throwable. The exception may have been thrown by a Java programming language or native method, but in the case of native methods, the event is not generated until the exception is first seen by a Java programming language method. If an exception is set and cleared in a native method (and thus is never visible to Java programming language code), no exception event is generated.

The method and location parameters uniquely identify the current location (where the exception was detected) and allow the mapping to source file and line number when that information is available. The exception field identifies the thrown exception object. The catch_method and catch_location identify the location of the catch clause, if any, that handles the thrown exception. If there is no such catch clause, each field is set to 0. There is no guarantee that the thread will ever reach this catch clause. If there are native methods on the call stack between the throw location and the catch clause, the exception may be reset by one of those native methods. Similarly, exceptions that are reported as uncaught (catch_klass et al. set to 0) may in fact be caught by native code. Agents can check for these occurrences by monitoring ExceptionCatch events. Note that finally clauses are implemented as catch and re-throw. Therefore they will be reported in the catch location.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_EXCEPTION | 58 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_EXCEPTION, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_exception_events | Can get exception thrown and exception catch events

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread
thread | jthread | Thread generating the exception
method | jmethodID | Method generating the exception
location | jlocation | Location where exception occurred
exception | jobject | The exception being thrown
catch_method | jmethodID | Method that will catch the exception, or NULL if no known catch
catch_location | jlocation | location which will catch the exception or zero if no known catch

Exception Catch

void JNICALL
ExceptionCatch(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jmethodID method,
            jlocation location,
            jobject exception)
Exception catch events are generated whenever a thrown exception is caught. Where "exception" means any java.lang.Throwable. If the exception is caught in a Java programming language method, the event is generated when the catch clause is reached. If the exception is caught in a native method, the event is generated as soon as control is returned to a Java programming language method. Exception catch events are generated for any exception for which a throw was detected in a Java programming language method. Note that finally clauses are implemented as catch and re-throw. Therefore they will generate exception catch events.

The method and location parameters uniquely identify the current location and allow the mapping to source file and line number when that information is available. For exceptions caught in a Java programming language method, the exception object identifies the exception object. Exceptions caught in native methods are not necessarily available by the time the exception catch is reported, so the exception field is set to NULL.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_EXCEPTION_CATCH | 59 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_EXCEPTION_CATCH, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_exception_events | Can get exception thrown and exception catch events

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread
thread | jthread | Thread catching the exception
method | jmethodID | Method catching the exception
location | jlocation | Location where exception is being caught
exception | jobject | Exception being caught

Thread Start

void JNICALL
ThreadStart(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread)
Thread start events are generated by a new thread before its initial method executes.

A thread may be listed in the array returned by GetAllThreads before its thread start event is generated. It is possible for other events to be generated on a thread before its thread start event.

The event is sent on the newly started thread.

Phase | Event Type | Number | Enabling | Since
sent during the start or live phase | JVMTI_EVENT_THREAD_START | 52 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_THREAD_START, NULL) | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread.
thread | jthread | Thread starting

Thread End

void JNICALL
ThreadEnd(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread)
Thread end events are generated by a terminating thread after its initial method has finished execution.

A thread may be listed in the array returned by GetAllThreads after its thread end event is generated. No events are generated on a thread after its thread end event.

The event is sent on the dying thread.

Phase | Event Type | Number | Enabling | Since
sent during the start or live phase | JVMTI_EVENT_THREAD_END | 53 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_THREAD_END, NULL) | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread.
thread | jthread | Thread ending

Class Load

void JNICALL
ClassLoad(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jclass klass)
A class load event is generated when a class is first loaded. The order of class load events generated by a particular thread are guaranteed to match the order of class loading within that thread. Array class creation does not generate a class load event. The creation of a primitive class (for example, java.lang.Integer.TYPE) does not generate a class load event.

This event is sent at an early stage in loading the class. As a result the class should be used carefully. Note, for example, that methods and fields are not yet loaded, so queries for methods, fields, subclasses, and so on will not give correct results. See "Loading of Classes and Interfaces" in the Java Language Specification. For most purposes the ClassPrepare event will be more useful.

Phase | Event Type | Number | Enabling | Since
sent during the start or live phase | JVMTI_EVENT_CLASS_LOAD | 55 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_CLASS_LOAD, NULL) | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread
thread | jthread | Thread loading the class
klass | jclass | Class being loaded

Class Prepare

void JNICALL
ClassPrepare(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jclass klass)
A class prepare event is generated when class preparation is complete. At this point, class fields, methods, and implemented interfaces are available, and no code from the class has been executed. Since array classes never have fields or methods, class prepare events are not generated for them. Class prepare events are not generated for primitive classes (for example, java.lang.Integer.TYPE).

Phase | Event Type | Number | Enabling | Since
sent during the start or live phase | JVMTI_EVENT_CLASS_PREPARE | 56 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_CLASS_PREPARE, NULL) | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread
thread | jthread | Thread generating the class prepare
klass | jclass | Class being prepared

Class File Load Hook

void JNICALL
ClassFileLoadHook(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jclass class_being_redefined,
            jobject loader,
            const char* name,
            jobject protection_domain,
            jint class_data_len,
            const unsigned char* class_data,
            jint* new_class_data_len,
            unsigned char** new_class_data)
This event is sent when the VM obtains class file data, but before it constructs the in-memory representation for that class. This event is also sent when the class is being modified by the RetransformClasses function or the RedefineClasses function, called in any JVM TI environment. The agent can instrument the existing class file data sent by the VM to include profiling/debugging hooks. See the description of bytecode instrumentation for usage information.

This event may be sent before the VM is initialized (the primordial phase). During this time no VM resources should be created. Some classes might not be compatible with the function (eg. ROMized classes) and this event will not be generated for these classes.

The agent must allocate the space for the modified class file data buffer using the memory allocation function Allocate because the VM is responsible for freeing the new class file data buffer using Deallocate. Note that Allocate is permitted during the primordial phase.

If the agent wishes to modify the class file, it must set new_class_data to point to the newly instrumented class file data buffer and set new_class_data_len to the length of that buffer before returning from this call. If no modification is desired, the agent simply does not set new_class_data. If multiple agents have enabled this event the results are chained. That is, if new_class_data has been set, it becomes the class_data for the next agent.

The order that this event is sent to each environment differs from other events. This event is sent to environments in the following order:
  • retransformation incapable environments, in the order in which they were created
  • retransformation capable environments, in the order in which they were created
When triggered by RetransformClasses, this event is sent only to retransformation capable environments.

Phase | Event Type | Number | Enabling | Since
sent during the primordial, start or live phase | JVMTI_EVENT_CLASS_FILE_LOAD_HOOK | 54 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_CLASS_FILE_LOAD_HOOK, NULL) | 1.0

Capabilities
Required Functionality
Optional Features
Capability | Effect
can_generate_all_class_hook_events | Can generate ClassFileLoadHook events for every loaded class.

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread. Will be NULL if sent during the primordial phase.
class_being_redefined | jclass | The class being redefined or retransformed. NULL if sent by class load.
loader | jobject | The class loader loading the class. NULL if the bootstrap class loader.
name | const char* | Name of class being loaded as a VM internal qualified name (for example, "java/util/List"), encoded as a modified UTF-8 string. Note: if the class is defined with a NULL name or without a name specified, name will be NULL.
protection_domain | jobject | The ProtectionDomain of the class.
class_data_len | jint | Length of current class file data buffer.
class_data | const unsigned char* | Pointer to the current class file data buffer.
new_class_data_len | jint* | Pointer to the length of the new class file data buffer.
new_class_data | unsigned char** | Pointer to the pointer to the instrumented class file data buffer.

VM Start Event

void JNICALL
VMStart(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env)
The VM initialization event signals the start of the VM. At this time JNI is live but the VM is not yet fully initialized. Once this event is generated, the agent is free to call any JNI function. This event signals the beginning of the start phase, JVM TI functions permitted in the start phase may be called.

In the case of VM start-up failure, this event will not be sent.

Phase | Event Type | Number | Enabling | Since
sent during the start or live phase | JVMTI_EVENT_VM_START | 57 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_VM_START, NULL) | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread.

VM Initialization Event

void JNICALL
VMInit(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread)
The VM initialization event signals the completion of VM initialization. Once this event is generated, the agent is free to call any JNI or JVM TI function. The VM initialization event can be preceded by or can be concurrent with other events, but the preceding events should be handled carefully, if at all, because the VM has not completed its initialization. The thread start event for the main application thread is guaranteed not to occur until after the handler for the VM initialization event returns.

In the case of VM start-up failure, this event will not be sent.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_VM_INIT | 50 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_VM_INIT, NULL) | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread.
thread | jthread | The initial thread

VM Death Event

void JNICALL
VMDeath(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env)
The VM death event notifies the agent of the termination of the VM. No events will occur after the VMDeath event.

In the case of VM start-up failure, this event will not be sent. Note that Agent_OnUnload will still be called in these cases.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_VM_DEATH | 51 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_VM_DEATH, NULL) | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread

Compiled Method Load

typedef struct {
    const void* start_address;
    jlocation location;
} jvmtiAddrLocationMap;
void JNICALL
CompiledMethodLoad(jvmtiEnv *jvmti_env,
            jmethodID method,
            jint code_size,
            const void* code_addr,
            jint map_length,
            const jvmtiAddrLocationMap* map,
            const void* compile_info)
Sent when a method is compiled and loaded into memory by the VM. If it is unloaded, the CompiledMethodUnload event is sent. If it is moved, the CompiledMethodUnload event is sent, followed by a new CompiledMethodLoad event. Note that a single method may have multiple compiled forms, and that this event will be sent for each form. Note also that several methods may be inlined into a single address range, and that this event will be sent for each method.

These events can be sent after their initial occurrence with GenerateEvents.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_COMPILED_METHOD_LOAD | 68 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_COMPILED_METHOD_LOAD, NULL) | 1.0

jvmtiAddrLocationMap - Native address to location entry
Field | Type | Description
start_address | const void* | Starting native address of code corresponding to a location
location | jlocation | Corresponding location. See GetJLocationFormat for the meaning of location.

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_compiled_method_load_events | Can generate events when a method is compiled or unloaded

Parameters
Name | Type | Description
method | jmethodID | Method being compiled and loaded
code_size | jint | Size of compiled code
code_addr | const void* | Address where compiled method code is loaded
map_length | jint | Number of jvmtiAddrLocationMap entries in the address map. Zero if mapping information cannot be supplied.
map | const jvmtiAddrLocationMap* | Map from native addresses to location. The native address range of each entry is from start_address to start_address-1 of the next entry. NULL if mapping information cannot be supplied.
compile_info | const void* | VM-specific compilation information. The referenced compile information is managed by the VM and must not depend on the agent for collection. A VM implementation defines the content and lifetime of the information.

Compiled Method Unload

void JNICALL
CompiledMethodUnload(jvmtiEnv *jvmti_env,
            jmethodID method,
            const void* code_addr)
Sent when a compiled method is unloaded from memory. This event might not be sent on the thread which performed the unload. This event may be sent sometime after the unload occurs, but will be sent before the memory is reused by a newly generated compiled method. This event may be sent after the class is unloaded.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_COMPILED_METHOD_UNLOAD | 69 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_COMPILED_METHOD_UNLOAD, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_compiled_method_load_events | Can generate events when a method is compiled or unloaded

Parameters
Name | Type | Description
method | jmethodID | Compiled method being unloaded. For identification of the compiled method only -- the class may be unloaded and therefore the method should not be used as an argument to further JNI or JVM TI functions.
code_addr | const void* | Address where compiled method code was loaded. For identification of the compiled method only -- the space may have been reclaimed.

Dynamic Code Generated

void JNICALL
DynamicCodeGenerated(jvmtiEnv *jvmti_env,
            const char* name,
            const void* address,
            jint length)
Sent when a component of the virtual machine is generated dynamically. This does not correspond to Java programming language code that is compiled--see CompiledMethodLoad. This is for native code--for example, an interpreter that is generated differently depending on command-line options.

Note that this event has no controlling capability. If a VM cannot generate these events, it simply does not send any.

These events can be sent after their initial occurrence with GenerateEvents.

Phase | Event Type | Number | Enabling | Since
sent during the primordial, start or live phase | JVMTI_EVENT_DYNAMIC_CODE_GENERATED | 70 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_DYNAMIC_CODE_GENERATED, NULL) | 1.0

Capabilities
Required Functionality

Parameters
Name | Type | Description
name | const char* | Name of the code, encoded as a modified UTF-8 string. Intended for display to an end-user. The name might not be unique.
address | const void* | Native address of the code
length | jint | Length in bytes of the code

Data Dump Request

void JNICALL
DataDumpRequest(jvmtiEnv *jvmti_env)
Sent by the VM to request the agent to dump its data. This is just a hint and the agent need not react to this event. This is useful for processing command-line signals from users. For example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Solaris causes the VM to send this event to the agent.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_DATA_DUMP_REQUEST | 71 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_DATA_DUMP_REQUEST, NULL) | 1.0

Capabilities
Required Functionality

Parameters
Name Type Description

Monitor Contended Enter

void JNICALL
MonitorContendedEnter(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jobject object)
Sent when a thread is attempting to enter a Java programming language monitor already acquired by another thread.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_MONITOR_CONTENDED_ENTER | 75 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_MONITOR_CONTENDED_ENTER, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_monitor_events | Can generate events on monitor activity

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread
thread | jthread | JNI local reference to the thread attempting to enter the monitor
object | jobject | JNI local reference to the monitor

Monitor Contended Entered

void JNICALL
MonitorContendedEntered(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jobject object)
Sent when a thread enters a Java programming language monitor after waiting for it to be released by another thread.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_MONITOR_CONTENDED_ENTERED | 76 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_MONITOR_CONTENDED_ENTERED, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_monitor_events | Can generate events on monitor activity

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread
thread | jthread | JNI local reference to the thread entering the monitor
object | jobject | JNI local reference to the monitor

Monitor Wait

void JNICALL
MonitorWait(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jobject object,
            jlong timeout)
Sent when a thread is about to wait on an object.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_MONITOR_WAIT | 73 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_MONITOR_WAIT, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_monitor_events | Can generate events on monitor activity

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread
thread | jthread | JNI local reference to the thread about to wait
object | jobject | JNI local reference to the monitor
timeout | jlong | The number of milliseconds the thread will wait

Monitor Waited

void JNICALL
MonitorWaited(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jobject object,
            jboolean timed_out)
Sent when a thread finishes waiting on an object.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_MONITOR_WAITED | 74 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_MONITOR_WAITED, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_monitor_events | Can generate events on monitor activity

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread
thread | jthread | JNI local reference to the thread that was finished waiting
object | jobject | JNI local reference to the monitor.
timed_out | jboolean | True if the monitor timed out

Resource Exhausted

void JNICALL
ResourceExhausted(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jint flags,
            const void* reserved,
            const char* description)
Sent when a VM resource needed by a running application has been exhausted. Except as required by the optional capabilities, the set of resources which report exhaustion is implementation dependent.

The following bit flags define the properties of the resource exhaustion:
Resource Exhaustion Flags
Constant | Value | Description
JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR | 0x0001 | After this event returns, the VM will throw a java.lang.OutOfMemoryError.
JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP | 0x0002 | The VM was unable to allocate memory from the JavaTM platform heap. The heap is the runtime data area from which memory for all class instances and arrays are allocated.
JVMTI_RESOURCE_EXHAUSTED_THREADS | 0x0004 | The VM was unable to create a thread.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_RESOURCE_EXHAUSTED | 80 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_RESOURCE_EXHAUSTED, NULL) | 1.1

Capabilities
Required Functionality
Optional Features
Capability | Effect
can_generate_resource_exhaustion_heap_events | Can generate events when the VM is unable to allocate memory from the heap.
can_generate_resource_exhaustion_threads_events | Can generate events when the VM is unable to create a thread.

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread
flags | jint | Flags defining the properties of the of resource exhaustion as specified by the Resource Exhaustion Flags.
reserved | const void* | Reserved.
description | const char* | Description of the resource exhaustion, encoded as a modified UTF-8 string.

VM Object Allocation

void JNICALL
VMObjectAlloc(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jobject object,
            jclass object_klass,
            jlong size)
Sent when a method causes the virtual machine to allocate an Object visible to Java programming language code and the allocation is not detectable by other intrumentation mechanisms. Generally object allocation should be detected by instrumenting the bytecodes of allocating methods. Object allocation generated in native code by JNI function calls should be detected using JNI function interception. Some methods might not have associated bytecodes and are not native methods, they instead are executed directly by the VM. These methods should send this event. Virtual machines which are incapable of bytecode instrumentation for some or all of their methods can send this event.

Typical examples where this event might be sent:
  • Reflection -- for example, java.lang.Class.newInstance()
  • Methods not represented by bytecodes -- for example, VM intrinsics and J2ME preloaded classes
Cases where this event would not be generated:
  • Allocation due to bytecodes -- for example, the new and newarray VM instructions
  • Allocation due to JNI function calls -- for example, AllocObject
  • Allocations during VM initialization
  • VM internal objects

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_VM_OBJECT_ALLOC | 84 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_VM_OBJECT_ALLOC, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_vm_object_alloc_events | Can generate events on VM allocation of an object

Parameters
Name | Type | Description
jni_env | JNIEnv * | The JNI environment of the event (current) thread
thread | jthread | Thread allocating the object.
object | jobject | JNI local reference to the object that was allocated
object_klass | jclass | JNI local reference to the class of the object
size | jlong | Size of the object (in bytes). See GetObjectSize.

Object Free

void JNICALL
ObjectFree(jvmtiEnv *jvmti_env,
            jlong tag)
An Object Free event is sent when the garbage collector frees an object. Events are only sent for tagged objects--see heap functions.

The event handler must not use JNI functions and must not use JVM TI functions except those which specifically allow such use (see the raw monitor, memory management, and environment local storage functions).

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_OBJECT_FREE | 83 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_OBJECT_FREE, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_object_free_events | Can generate events when the garbage collector frees an object

Parameters
Name | Type | Description
tag | jlong | The freed object's tag

Garbage Collection Start

void JNICALL
GarbageCollectionStart(jvmtiEnv *jvmti_env)
A Garbage Collection Start event is sent when a full cycle garbage collection begins. Only stop-the-world collections are reported--that is, collections during which all threads cease to modify the state of the Java virtual machine. This means that some collectors will never generate these events. This event is sent while the VM is still stopped, thus the event handler must not use JNI functions and must not use JVM TI functions except those which specifically allow such use (see the raw monitor, memory management, and environment local storage functions).

This event is always sent as a matched pair with GarbageCollectionFinish (assuming both events are enabled) and no garbage collection events will occur between them.

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_GARBAGE_COLLECTION_START | 81 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_GARBAGE_COLLECTION_START, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_garbage_collection_events | Can generate events when garbage collection begins or ends

Parameters
Name Type Description

Garbage Collection Finish

void JNICALL
GarbageCollectionFinish(jvmtiEnv *jvmti_env)
A Garbage Collection Finish event is sent when a full garbage collection cycle ends. This event is sent while the VM is still stopped, thus the event handler must not use JNI functions and must not use JVM TI functions except those which specifically allow such use (see the raw monitor, memory management, and environment local storage functions).

Some agents may need to do post garbage collection operations that require the use of the disallowed JVM TI or JNI functions. For these cases an agent thread can be created which waits on a raw monitor, and the handler for the Garbage Collection Finish event simply notifies the raw monitor

This event is always sent as a matched pair with GarbageCollectionStart (assuming both events are enabled).

Phase | Event Type | Number | Enabling | Since
sent only during the live phase | JVMTI_EVENT_GARBAGE_COLLECTION_FINISH | 82 | SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_GARBAGE_COLLECTION_FINISH, NULL) | 1.0

Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability | Effect
can_generate_garbage_collection_events | Can generate events when garbage collection begins or ends

Parameters
Name Type Description

Constant Index

JVMTI_CLASS_STATUS_ARRAY
JVMTI_CLASS_STATUS_ERROR
JVMTI_CLASS_STATUS_INITIALIZED
JVMTI_CLASS_STATUS_PREPARED
JVMTI_CLASS_STATUS_PRIMITIVE
JVMTI_CLASS_STATUS_VERIFIED
JVMTI_DISABLE
JVMTI_ENABLE
JVMTI_HEAP_FILTER_CLASS_TAGGED
JVMTI_HEAP_FILTER_CLASS_UNTAGGED
JVMTI_HEAP_FILTER_TAGGED
JVMTI_HEAP_FILTER_UNTAGGED
JVMTI_HEAP_OBJECT_EITHER
JVMTI_HEAP_OBJECT_TAGGED
JVMTI_HEAP_OBJECT_UNTAGGED
JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT
JVMTI_HEAP_REFERENCE_CLASS
JVMTI_HEAP_REFERENCE_CLASS_LOADER
JVMTI_HEAP_REFERENCE_CONSTANT_POOL
JVMTI_HEAP_REFERENCE_FIELD
JVMTI_HEAP_REFERENCE_INTERFACE
JVMTI_HEAP_REFERENCE_JNI_GLOBAL
JVMTI_HEAP_REFERENCE_JNI_LOCAL
JVMTI_HEAP_REFERENCE_MONITOR
JVMTI_HEAP_REFERENCE_OTHER
JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN
JVMTI_HEAP_REFERENCE_SIGNERS
JVMTI_HEAP_REFERENCE_STACK_LOCAL
JVMTI_HEAP_REFERENCE_STATIC_FIELD
JVMTI_HEAP_REFERENCE_SUPERCLASS
JVMTI_HEAP_REFERENCE_SYSTEM_CLASS
JVMTI_HEAP_REFERENCE_THREAD
JVMTI_HEAP_ROOT_JNI_GLOBAL
JVMTI_HEAP_ROOT_JNI_LOCAL
JVMTI_HEAP_ROOT_MONITOR
JVMTI_HEAP_ROOT_OTHER
JVMTI_HEAP_ROOT_STACK_LOCAL
JVMTI_HEAP_ROOT_SYSTEM_CLASS
JVMTI_HEAP_ROOT_THREAD
JVMTI_ITERATION_ABORT
JVMTI_ITERATION_CONTINUE
JVMTI_ITERATION_IGNORE
JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED
JVMTI_JAVA_LANG_THREAD_STATE_MASK
JVMTI_JAVA_LANG_THREAD_STATE_NEW
JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE
JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED
JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING
JVMTI_JAVA_LANG_THREAD_STATE_WAITING
JVMTI_JLOCATION_JVMBCI
JVMTI_JLOCATION_MACHINEPC
JVMTI_JLOCATION_OTHER
JVMTI_KIND_ALLOC_ALLOC_BUF
JVMTI_KIND_ALLOC_BUF
JVMTI_KIND_IN
JVMTI_KIND_IN_BUF
JVMTI_KIND_IN_PTR
JVMTI_KIND_OUT
JVMTI_KIND_OUT_BUF
JVMTI_PHASE_DEAD
JVMTI_PHASE_LIVE
JVMTI_PHASE_ONLOAD
JVMTI_PHASE_PRIMORDIAL
JVMTI_PHASE_START
JVMTI_PRIMITIVE_TYPE_BOOLEAN
JVMTI_PRIMITIVE_TYPE_BYTE
JVMTI_PRIMITIVE_TYPE_CHAR
JVMTI_PRIMITIVE_TYPE_DOUBLE
JVMTI_PRIMITIVE_TYPE_FLOAT
JVMTI_PRIMITIVE_TYPE_INT
JVMTI_PRIMITIVE_TYPE_LONG
JVMTI_PRIMITIVE_TYPE_SHORT
JVMTI_REFERENCE_ARRAY_ELEMENT
JVMTI_REFERENCE_CLASS
JVMTI_REFERENCE_CLASS_LOADER
JVMTI_REFERENCE_CONSTANT_POOL
JVMTI_REFERENCE_FIELD
JVMTI_REFERENCE_INTERFACE
JVMTI_REFERENCE_PROTECTION_DOMAIN
JVMTI_REFERENCE_SIGNERS
JVMTI_REFERENCE_STATIC_FIELD
JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP
JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR
JVMTI_RESOURCE_EXHAUSTED_THREADS
JVMTI_THREAD_MAX_PRIORITY
JVMTI_THREAD_MIN_PRIORITY
JVMTI_THREAD_NORM_PRIORITY
JVMTI_THREAD_STATE_ALIVE
JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER
JVMTI_THREAD_STATE_IN_NATIVE
JVMTI_THREAD_STATE_IN_OBJECT_WAIT
JVMTI_THREAD_STATE_INTERRUPTED
JVMTI_THREAD_STATE_PARKED
JVMTI_THREAD_STATE_RUNNABLE
JVMTI_THREAD_STATE_SLEEPING
JVMTI_THREAD_STATE_SUSPENDED
JVMTI_THREAD_STATE_TERMINATED
JVMTI_THREAD_STATE_VENDOR_1
JVMTI_THREAD_STATE_VENDOR_2
JVMTI_THREAD_STATE_VENDOR_3
JVMTI_THREAD_STATE_WAITING
JVMTI_THREAD_STATE_WAITING_INDEFINITELY
JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT
JVMTI_TIMER_ELAPSED
JVMTI_TIMER_TOTAL_CPU
JVMTI_TIMER_USER_CPU
JVMTI_TYPE_CCHAR
JVMTI_TYPE_CVOID
JVMTI_TYPE_JBOOLEAN
JVMTI_TYPE_JBYTE
JVMTI_TYPE_JCHAR
JVMTI_TYPE_JCLASS
JVMTI_TYPE_JDOUBLE
JVMTI_TYPE_JFIELDID
JVMTI_TYPE_JFLOAT
JVMTI_TYPE_JINT
JVMTI_TYPE_JLONG
JVMTI_TYPE_JMETHODID
JVMTI_TYPE_JNIENV
JVMTI_TYPE_JOBJECT
JVMTI_TYPE_JSHORT
JVMTI_TYPE_JTHREAD
JVMTI_TYPE_JVALUE
JVMTI_VERBOSE_CLASS
JVMTI_VERBOSE_GC
JVMTI_VERBOSE_JNI
JVMTI_VERBOSE_OTHER
JVMTI_VERSION_INTERFACE_JNI
JVMTI_VERSION_INTERFACE_JVMTI
JVMTI_VERSION_MASK_INTERFACE_TYPE
JVMTI_VERSION_MASK_MAJOR
JVMTI_VERSION_MASK_MICRO
JVMTI_VERSION_MASK_MINOR
JVMTI_VERSION_SHIFT_MAJOR
JVMTI_VERSION_SHIFT_MICRO
JVMTI_VERSION_SHIFT_MINOR
JVMTI_VISIT_ABORT
JVMTI_VISIT_OBJECTS

Change History

Last update: 06/08/06 22:33:32
File version: @(#)jvmti.xml 1.202
Version: 1.1.102

The JVM TI specification is an evolving document with major, minor, and micro version numbers. A released version of the specification is uniquely identified by its major and minor version. The functions, events, and capabilities in this specification indicate a "Since" value which is the major and minor version in which it was introduced. The version of the specification implemented by the VM can be retrieved at runtime with the GetVersionNumber function.

Version
Date 		Changes
14 Nov 2002 | Converted to XML document.
14 Nov 2002 | Elided heap dump functions (for now) since what was there was wrong.
18 Nov 2002 | Added detail throughout.
18 Nov 2002 | Changed JVMTI_THREAD_STATUS_RUNNING to JVMTI_THREAD_STATUS_RUNNABLE.
19 Nov 2002 | Added AsyncGetStackTrace.
19 Nov 2002 | Added jframeID return to GetStackTrace.
19 Nov 2002 | Elided GetCurrentFrame and GetCallingFrame functions (for now) since what was there since they are redundant with GetStackTrace.
19 Nov 2002 | Elided ClearAllBreakpoints since it has always been redundant.
19 Nov 2002 | Added GetSystemProperties.
19 Nov 2002 | Changed the thread local storage functions to use jthread.
20 Nov 2002 | Added GetJLocationFormat.
22 Nov 2002 | Added events and introductory text.
22 Nov 2002 | Cross reference type and constant definitions.
24 Nov 2002 | Added DTD.
24 Nov 2002 | Added capabilities function section.
29 Nov 2002 | Assign capabilities to each function and event.
29 Nov 2002 | Add JNI interception functions.
30 Nov 2002 | Auto generate SetEventNotificationMode capabilities.
30 Nov 2002 | Add VMObjectAlloc event.
30 Nov 2002 | Add DynamicCodeGenerated event.
30 Nov 2002 | Add const to declarations.
30 Nov 2002 | Change method exit and frame pop to send on exception.
1 Dec 2002 | Add ForceGarbageCollection.
2 Dec 2002 | Redo Xrun section; clarify GetStackTrace and add example; Fix width problems; use "agent" consistently.
8 Dec 2002 | Remove previous start-up intro. Add JVM TI Environments section.
8 Dec 2002 | Add DisposeEnvironment.
9 Dec 2002 | Numerous minor updates.
15 Dec 2002 | Add heap profiling functions added: get/set annotation, iterate live objects/heap. Add heap profiling functions place holder added: heap roots. Heap profiling event added: object free. Heap profiling event redesigned: vm object allocation. Heap profiling event placeholders added: garbage collection start/finish. Native method bind event added.
19 Dec 2002 | Revamp suspend/resume functions. Add origin information with jvmdi tag. Misc fixes.
24 Dec 2002 | Add semantics to types.
27 Dec 2002 | Add local reference section. Autogenerate parameter descriptions from types.
28 Dec 2002 | Document that RunAgentThread sends threadStart.
29 Dec 2002 | Remove redundant local ref and dealloc warning. Convert GetRawMonitorName to allocated buffer. Add GenerateEvents.
30 Dec 2002 | Make raw monitors a type and rename to "jrawMonitorID".
1 Jan 2003 | Include origin information. Clean-up JVMDI issue references. Remove Deallocate warnings which are now automatically generated.
2 Jan 2003 | Fix representation issues for jthread.
3 Jan 2003 | Make capabilities buffered out to 64 bits - and do it automatically.
4 Jan 2003 | Make constants which are enumeration into enum types. Parameters now of enum type. Clean-up and index type section. Replace remaining datadef entities with callback.
7 Jan 2003 | Correct GenerateEvents description. More internal semantics work.
9 Jan 2003 | Replace previous GetSystemProperties with two functions which use allocated information instead fixed. Add SetSystemProperty. More internal semantics work.
12 Jan 2003 | Add varargs to end of SetEventNotificationMode.
20 Jan 2003 | Finish fixing spec to reflect that alloc sizes are jlong.
22 Jan 2003 | Allow NULL as RunAgentThread arg.
22 Jan 2003 | Fixed names to standardized naming convention Removed AsyncGetStackTrace.
29 Jan 2003 | Since we are using jthread, removed GetThread.
31 Jan 2003 | Change GetFieldName to allow NULLs like GetMethodName.
v40
29 Feb 2003 		Rewrite the introductory text, adding sections on start-up, environments and bytecode instrumentation. Change the command line arguments per EG discussions. Add an introduction to the capabilities section. Add the extension mechanism category and functions. Mark for deletion, but clarified anyhow, SuspendAllThreads. Rename IterateOverLiveObjects to IterateOverReachableObjects and change the text accordingly. Clarify IterateOverHeap. Clarify CompiledMethodLoad. Discuss prerequisite state for Calling Functions. Clarify SetAllocationHooks. Added issues ("To be resolved:") through-out. And so on...
v41
6 Mar 2003 		Remove struct from the call to GetOwnedMonitorInfo. Automatically generate most error documentation, remove (rather broken) hand written error doc. Better describe capability use (empty initial set). Add min value to jint params. Remove the capability can_access_thread_local_storage. Rename error JVMTI_ERROR_NOT_IMPLEMENTED to JVMTI_ERROR_MUST_POSSESS_CAPABILITY; same for *NOT_IMPLEMENTED. Description fixes.
v42
8 Mar 2003 		Rename GetClassSignature to GetClassName. Rename IterateOverClassObjects to IterateOverInstancesOfClass. Remove GetMaxStack (operand stack isn't used in JVM TI). Description fixes: define launch-time, remove native frame pop from PopFrame, and assorted clarifications.
v43
8 Mar 2003 		Fix minor editing problem.
v44
10 Mar 2003 		Add phase information. Remap (compact) event numbers.
v45
11 Mar 2003 		More phase information - allow "any". Elide raw monitor queries and events. Minor description fixes.
v46
12 Mar 2003 		Add GetPhase. Use "phase" through document. Elide GetRawMonitorName. Elide GetObjectMonitors.
v47
12 Mar 2003 		Fixes from link, XML, and spell checking. Auto-generate the callback structure.
v48
13 Mar 2003 		One character XML fix.
v49
13 Mar 2003 		Change function parameter names to be consistent with event parameters (fooBarBaz becomes foo_bar_baz).
v50
14 Mar 2003 		Fix broken link. Fix thread markers.
v51
14 Mar 2003 		Change constants so they are under 128 to workaround compiler problems.
v52
23 Mar 2003 		Overhaul capabilities. Separate GetStackTrace into GetStackTrace and GetStackFrames.
v54
8 Apr 2003 		Use depth instead of jframeID to reference frames. Remove the now irrelevant GetCurrentFrame, GetCallerFrame and GetStackFrames. Remove frame arg from events.
v55
9 Apr 2003 		Remove GetObjectWithAnnotation since tests show bufferred approach more efficient. Add missing annotation_count to GetObjectsWithAnnotations
v56
10 Apr 2003 		Remove confusing parenthetical statement in GetObjectsWithAnnotations
v58
13 Apr 2003 		Replace jclass/jmethodID representation of method with simply jmethodID; Pass JvmtiEnv* as first arg of every event; remove JNIEnv* where inappropriate. Replace can_access_frames with can_access_local_variables; remove from purely stack access. Use can_get_synthetic_attribute; fix description. Clarify that zero length arrays must be deallocated. Clarify RelinquishCapabilities. Generalize JVMTI_ERROR_VM_DEAD to JVMTI_ERROR_WRONG_PHASE.
v59
27 Apr 2003 		Remove lingering indirect references to OBSOLETE_METHOD_ID.
v60
4 May 2003 		Allow DestroyRawMonitor during OnLoad.
v61
7 May 2003 		Added not monitor owner error return to DestroyRawMonitor.
v62
13 May 2003 		Clarify semantics of raw monitors. Change flags on GetThreadStatus. GetClassLoader return NULL for the bootstrap class loader. Add GetClassName issue. Define local variable signature. Disallow zero in annotations array of GetObjectsWithAnnotations. Remove over specification in GetObjectsWithAnnotations. Elide SetAllocationHooks. Elide SuspendAllThreads.
v63
14 May 2003 		Define the data type jvmtiEventCallbacks. Zero length allocations return NULL. Keep SetAllocationHooks in JVMDI, but remove from JVM TI. Add JVMTI_THREAD_STATUS_FLAG_INTERRUPTED.
v64
15 May 2003 		Better wording, per review.
v65
15 May 2003 		First Alpha. Make jmethodID and jfieldID unique, jclass not used.
v66
27 May 2003 		Fix minor XSLT errors.
v67
13 June 2003 		Undo making jfieldID unique (jmethodID still is).
v68
17 June 2003 		Changes per June 11th Expert Group meeting -- Overhaul Heap functionality: single callback, remove GetHeapRoots, add reachable iterators, and rename "annotation" to "tag". NULL thread parameter on most functions is current thread. Add timers. Remove ForceExit. Add GetEnvironmentLocalStorage. Add verbose flag and event. Add AddToBootstrapClassLoaderSearch. Update ClassFileLoadHook.
v69
18 June 2003 		Clean up issues sections. Rename GetClassName back to GetClassSignature and fix description. Add generic signature to GetClassSignature, GetFieldSignature, GetMethodSignature, and GetLocalVariableTable. Elide EstimateCostOfCapabilities. Clarify that the system property functions operate on the VM view of system properties. Clarify Agent_OnLoad. Remove "const" from JNIEnv* in events. Add metadata accessors.
v70
18 June 2003 		Add start_depth to GetStackTrace. Move system properties to a new category. Add GetObjectSize. Remove "X" from command line flags. XML, HTML, and spell check corrections.
v71
19 June 2003 		Fix JVMTI_HEAP_ROOT_THREAD to be 6. Make each synopsis match the function name. Fix unclear wording.
v72
26 June 2003 		SetThreadLocalStorage and SetEnvironmentLocalStorage should allow value to be set to NULL. NotifyFramePop, GetFrameLocationm and all the local variable operations needed to have their wording about frames fixed. Grammar and clarity need to be fixed throughout. Capitalization and puntuation need to be consistent. Need micro version number and masks for accessing major, minor, and micro. The error code lists should indicate which must be returned by an implementation. The command line properties should be visible in the properties functions. Disallow popping from the current thread. Allow implementations to return opaque frame error when they cannot pop. The NativeMethodBind event should be sent during any phase. The DynamicCodeGenerated event should be sent during any phase. The following functions should be allowed to operate before VMInit: Set/GetEnvironmentLocalStorage GetMethodDeclaringClass GetClassSignature GetClassModifiers IsInterface IsArrayClass GetMethodName GetMethodModifiers GetMaxLocals GetArgumentsSize GetLineNumberTable GetMethodLocation IsMethodNative IsMethodSynthetic. Other changes (to XSL): Argument description should show asterisk after not before pointers. NotifyFramePop, GetFrameLocationm and all the local variable operations should hsve the NO_MORE_FRAMES error added. Not alive threads should have a different error return than invalid thread.
v73
7 July 2003 		VerboseOutput event was missing message parameter. Minor fix-ups.
v74
14 July 2003 		Technical Publications Department corrections. Allow thread and environment local storage to be set to NULL.
v75
23 July 2003 		Use new Agent_OnLoad rather than overloaded JVM_OnLoad. Add JNICALL to callbacks (XSL). Document JNICALL requirement for both events and callbacks (XSL). Restrict RedefineClasses to methods and attributes. Elide the VerboseOutput event. VMObjectAlloc: restrict when event is sent and remove method parameter. Finish loose ends from Tech Pubs edit.
v76
24 July 2003 		Change ClassFileLoadHook event to send the class instead of a boolean of redefine.
v77
24 July 2003 		XML fixes. Minor text clarifications and corrections.
v78
24 July 2003 		Remove GetExceptionHandlerTable and GetThrownExceptions from JVM TI. Clarify that stack frames are JVM Spec frames. Split can_get_source_info into can_get_source_file_name, can_get_line_numbers, and can_get_source_debug_extension. PopFrame cannot have a native calling method. Removed incorrect statement in GetClassloaderClasses (see http://java.sun.com/docs/books/vmspec/2nd-edition/html/ConstantPool.doc.html#79383).
v79
24 July 2003 		XML and text fixes. Move stack frame description into Stack Frame category.
v80
26 July 2003 		Allow NULL (means bootstrap loader) for GetClassloaderClasses. Add new heap reference kinds for references from classes. Add timer information struct and query functions. Add AvailableProcessors. Rename GetOtherThreadCpuTime to GetThreadCpuTime. Explicitly add JVMTI_ERROR_INVALID_THREAD and JVMTI_ERROR_THREAD_NOT_ALIVE to SetEventNotification mode. Add initial thread to the VM_INIT event. Remove platform assumptions from AddToBootstrapClassLoaderSearch.
v81
26 July 2003 		Grammar and clarity changes per review.
v82
27 July 2003 		More grammar and clarity changes per review. Add Agent_OnUnload.
v83
28 July 2003 		Change return type of Agent_OnUnload to void.
v84
28 July 2003 		Rename JVMTI_REFERENCE_ARRAY to JVMTI_REFERENCE_ARRAY_ELEMENT.
v85
28 July 2003 		Steal java.lang.Runtime.availableProcessors() wording for AvailableProcessors(). Guarantee that zero will never be an event ID. Remove some issues which are no longer issues. Per review, rename and more completely document the timer information functions.
v86
29 July 2003 		Non-spec visible change to XML controlled implementation: SetThreadLocalStorage must run in VM mode.
0.1.87
5 August 2003 		Add GetErrorName. Add varargs warning to jvmtiExtensionEvent. Remove "const" on the jvmtiEnv* of jvmtiExtensionEvent. Remove unused can_get_exception_info capability. Pass jvmtiEnv* and JNIEnv* to the jvmtiStartFunction. Fix jvmtiExtensionFunctionInfo.func declared type. Extension function returns error code. Use new version numbering.
0.2.88
5 August 2003 		Remove the ClassUnload event.
0.2.89
8 August 2003 		Heap reference iterator callbacks return an enum that allows outgoing object references to be ignored. Allow JNIEnv as a param type to extension events/functions.
0.2.90
15 August 2003 		Fix a typo.
0.2.91
2 September 2003 		Remove all metadata functions: GetClassMetadata, GetFieldMetadata, and GetMethodMetadata.
0.2.92
1 October 2003 		Mark the functions Allocate. Deallocate, RawMonitor*, SetEnvironmentLocalStorage, and GetEnvironmentLocalStorage as safe for use in heap callbacks and GC events.
0.2.93
24 November 2003 		Add pass through opaque user data pointer to heap iterate functions and callbacks. In the CompiledMethodUnload event, send the code address. Add GarbageCollectionOccurred event. Add constant pool reference kind. Mark the functions CreateRawMonitor and DestroyRawMonitor as safe for use in heap callbacks and GC events. Clarify: VMDeath, GetCurrentThreadCpuTimerInfo, GetThreadCpuTimerInfo, IterateOverReachableObjects, IterateOverObjectsReachableFromObject, GetTime and JVMTI_ERROR_NULL_POINTER. Add missing errors to: GenerateEvents and AddToBootstrapClassLoaderSearch. Fix description of ClassFileLoadHook name parameter. In heap callbacks and GC/ObjectFree events, specify that only explicitly allowed functions can be called. Allow GetCurrentThreadCpuTimerInfo, GetCurrentThreadCpuTime, GetTimerInfo, and GetTime during callback. Allow calling SetTag/GetTag during the onload phase. SetEventNotificationMode, add: error attempted inappropriate thread level control. Remove jvmtiExceptionHandlerEntry. Fix handling of native methods on the stack -- location_ptr param of GetFrameLocation, remove JVMTI_ERROR_OPAQUE_FRAME from GetFrameLocation, jvmtiFrameInfo.location, and jlocation. Remove typo (from JVMPI) implying that the MonitorWaited event is sent on sleep.
0.2.94
25 November 2003 		Clarifications and typos.
0.2.95
3 December 2003 		Allow NULL user_data in heap iterators.
0.2.97
28 January 2004 		Add GetThreadState, deprecate GetThreadStatus.
0.2.98
29 January 2004 		INVALID_SLOT and TYPE_MISMATCH errors should be optional.
0.2.102
12 February 2004 		Remove MonitorContendedExit. Added JNIEnv parameter to VMObjectAlloc. Clarified definition of class_tag and referrer_index parameters to heap callbacks.
0.2.103
16 Febuary 2004 		Document JAVA_TOOL_OPTIONS.
0.2.105
17 Febuary 2004 		Divide start phase into primordial and start. Add VMStart event Change phase associations of functions and events.
0.3.6
18 Febuary 2004 		Elide deprecated GetThreadStatus. Bump minor version, subtract 100 from micro version
0.3.7
18 Febuary 2004 		Document that timer nanosecond values are unsigned. Clarify text having to do with native methods.
0.3.8
19 Febuary 2004 		Fix typos. Remove elided deprecated GetThreadStatus.
0.3.9
23 Febuary 2004 		Require NotifyFramePop to act on suspended threads.
0.3.10
24 Febuary 2004 		Add capabilities (can_redefine_any_class and can_generate_all_class_hook_events) and an error (JVMTI_ERROR_UNMODIFIABLE_CLASS) which allow some classes to be unmodifiable.
0.3.11
28 Febuary 2004 		Add JVMTI_ERROR_MUST_POSSESS_CAPABILITY to SetEventNotificationMode.
0.3.12
8 March 2004 		Clarified CompiledMethodUnload so that it is clear the event may be posted after the class has been unloaded.
0.3.13
5 March 2004 		Change the size parameter of VMObjectAlloc to jlong to match GetObjectSize.
0.3.14
13 March 2004 		Added guideline for the use of the JNI FindClass function in event callback functions.
0.3.15
15 March 2004 		Add GetAllStackTraces and GetThreadListStackTraces.
0.3.16
19 March 2004 		ClassLoad and ClassPrepare events can be posted during start phase.
0.3.17
25 March 2004 		Add JVMTI_ERROR_NATIVE_METHOD to GetLineNumberTable, GetLocalVariableTable, GetMaxLocals, GetArgumentsSize, GetMethodLocation, GetBytecodes.
0.3.18
29 March 2004 		Return the timer kind in the timer information structure.
0.3.19
31 March 2004 		Spec clarifications: JVMTI_THREAD_STATE_IN_NATIVE might not include JNI or JVM TI. ForceGarbageCollection does not run finalizers. The context of the specification is the Java platform. Warn about early instrumentation.
0.3.20
1 April 2004 		Refinements to the above clarifications and Clarify that an error returned by Agent_OnLoad terminates the VM.
0.3.21
1 April 2004 		Array class creation does not generate a class load event.
0.3.22
7 April 2004 		Align thread state hierarchy more closely with java.lang.Thread.State.
0.3.23
12 April 2004 		Clarify the documentation of thread state.
0.3.24
19 April 2004 		Remove GarbageCollectionOccurred event -- can be done by agent.
0.3.25
22 April 2004 		Define "command-line option".
0.3.26
29 April 2004 		Describe the intended use of bytecode instrumentation. Fix description of extension event first parameter.
0.3.27
30 April 2004 		Clarification and typos.
0.3.28
18 May 2004 		Remove DataDumpRequest event.
0.3.29
18 May 2004 		Clarify RawMonitorWait with zero timeout. Clarify thread state after RunAgentThread.
0.3.30
24 May 2004 		Clean-up: fix bad/old links, etc.
0.3.31
30 May 2004 		Clarifications including: All character strings are modified UTF-8. Agent thread visibiity. Meaning of obsolete method version. Thread invoking heap callbacks,
1.0.32
1 June 2004 		Bump major.minor version numbers to "1.0".
1.0.33
2 June 2004 		Clarify interaction between ForceGarbageCollection and ObjectFree.
1.0.34
6 June 2004 		Restrict AddToBootstrapClassLoaderSearch and SetSystemProperty to the OnLoad phase only.
1.0.35
11 June 2004 		Fix typo in SetTag.
1.0.36
18 June 2004 		Fix trademarks. Add missing parameter in example GetThreadState usage.
1.0.37
4 August 2004 		Copyright updates.
1.0.38
5 November 2004 		Add missing function table layout. Add missing description of C++ member function format of functions. Clarify that name in CFLH can be NULL. Released as part of J2SETM 5.0.
1.1.47
24 April 2005 		Bump major.minor version numbers to "1.1". Add ForceEarlyReturn* functions. Add GetOwnedMonitorStackDepthInfo function. Add GetCurrentThread function. Add "since" version marker. Add AddToSystemClassLoaderSearch. Allow AddToBootstrapClassLoaderSearch be used in live phase. Fix historic rubbish in the descriptions of the heap_object_callback parameter of IterateOverHeap and IterateOverInstancesOfClass functions; disallow NULL for this parameter. Clarify, correct and make consistent: wording about current thread, opaque frames and insufficient number of frames in PopFrame. Consistently use "current frame" rather than "topmost". Clarify the JVMTI_ERROR_TYPE_MISMATCH errors in GetLocal* and SetLocal* by making them compatible with those in ForceEarlyReturn*. Many other clarifications and wording clean ups.
1.1.48
25 April 2005 		Add GetConstantPool. Switch references to the first edition of the VM Spec, to the seconds edition.
1.1.49
26 April 2005 		Clarify minor/major version order in GetConstantPool.
1.1.50
26 April 2005 		Add SetNativeMethodPrefix and SetNativeMethodPrefixes. Reassign GetOwnedMonitorStackDepthInfo to position 153. Break out Class Loader Search in its own documentation category. Deal with overly long lines in XML source.
1.1.51
29 April 2005 		Allow agents be started in the live phase. Added paragraph about deploying agents.
1.1.52
30 April 2005 		Add specification description to SetNativeMethodPrefix(es). Better define the conditions on GetConstantPool.
1.1.53
30 April 2005 		Break out the GetClassVersionNumber function from GetConstantPool. Clean-up the references to the VM Spec.
1.1.54
1 May 2005 		Allow SetNativeMethodPrefix(es) in any phase. Add clarifications about the impact of redefinition on GetConstantPool.
1.1.56
2 May 2005 		Various clarifications to SetNativeMethodPrefix(es).
1.1.57
2 May 2005 		Add missing performance warning to the method entry event.
1.1.58
5 May 2005 		Remove internal JVMDI support.
1.1.59
8 May 2005 		Add RetransformClasses. Revamp the bytecode instrumentation documentation. Change IsMethodObsolete to no longer require the can_redefine_classes capability.
1.1.63
11 May 2005 		Clarifications for retransformation.
1.1.64
11 May 2005 		Clarifications for retransformation, per review. Lock "retransformation (in)capable" at class load enable time.
1.1.67
4 June 2005 		Add new heap functionity which supports reporting primitive values, allows setting the referrer tag, and has more powerful filtering: FollowReferences, IterateThroughHeap, and their associated callbacks, structs, enums, and constants.
1.1.68
4 June 2005 		Clarification.
1.1.69
6 June 2005 		FollowReferences, IterateThroughHeap: Put callbacks in a struct; Add missing error codes; reduce bits in the visit control flags.
1.1.70
14 June 2005 		More on new heap functionity: spec clean-up per review.
1.1.71
15 June 2005 		More on new heap functionity: Rename old heap section to Heap (1.0).
1.1.72
21 June 2005 		Fix typos.
1.1.73
27 June 2005 		Make referrer info structure a union.
1.1.74
9 September 2005 		In new heap functions: Add missing superclass reference kind. Use a single scheme for computing field indexes. Remove outdated references to struct based referrer info.
1.1.75
12 September 2005 		Don't callback during FollowReferences on frivolous java.lang.Object superclass.
1.1.76
13 September 2005 		In string primitive callback, length now Unicode length. In array and string primitive callbacks, value now "const". Note possible compiler impacts on setting JNI function table.
1.1.77
13 September 2005 		GetClassVersionNumbers() and GetConstantPool() should return error on array or primitive class.
1.1.78
14 September 2005 		Grammar fixes.
1.1.79
26 September 2005 		Add IsModifiableClass query.
1.1.81
9 February 2006 		Add referrer_class_tag parameter to jvmtiHeapReferenceCallback.
1.1.82
13 February 2006 		Doc fixes: update can_redefine_any_class to include retransform. Clarify that exception events cover all Throwables. In GetStackTrace, no test is done for start_depth too big if start_depth is zero, Clarify fields reported in Primitive Field Callback -- static vs instance. Repair confusing names of heap types, including callback names. Require consistent usage of stack depth in the face of thread launch methods. Note incompatibility of JVM TI memory management with other systems.
1.1.85
14 February 2006 		Fix typos and missing renames.
1.1.86
13 March 2006 		Clarify that jmethodIDs and jfieldIDs can be saved. Clarify that Iterate Over Instances Of Class includes subclasses.
1.1.87
14 March 2006 		Better phrasing.
1.1.88
16 March 2006 		Match the referrer_index for static fields in Object Reference Callback with the Reference Implementation (and all other known implementations); that is, make it match the definition for instance fields. In GetThreadListStackTraces, add JVMTI_ERROR_INVALID_THREAD to cover an invalid thread in the list; and specify that not started threads return empty stacks.
1.1.89
17 March 2006 		Typo.
1.1.90
25 March 2006 		Typo.
1.1.91
6 April 2006 		Remove restrictions on AddToBootstrapClassLoaderSearch and AddToSystemClassLoaderSearch.
1.1.93
1 May 2006 		Changed spec to return -1 for monitor stack depth for the implementation which can not determine stack depth.
1.1.94
3 May 2006 		Corrections for readability and accuracy courtesy of Alan Pratt of IBM. List the object relationships reported in FollowReferences.
1.1.95
5 May 2006 		Clarify the object relationships reported in FollowReferences.
1.1.98
28 June 2006 		Clarify DisposeEnvironment; add warning. Fix typos in SetLocalXXX "retrieve" => "set". Clarify that native method prefixes must remain set while used. Clarify that exactly one Agent_OnXXX is called per agent. Clarify that library loading is independent from start-up. Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec.
1.1.99
31 July 2006 		Clarify the interaction between functions and exceptions. Clarify and give examples of field indices. Remove confusing "That is" sentence from MonitorWait and MonitorWaited events. Update links to point to Java 6.
1.1.102
6 August 2006 		Add ResourceExhaustedEvent.


1 - Introduction

CONTENTS | PREV | NEXT Java Remote Method Invocation

Introduction

CHAPTER 1

Topics:

  • Background
  • System Goals

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


1 - Introduction

CONTENTS | PREV | NEXT Java Remote Method Invocation

1.1 Background

Distributed systems require that computations running in different address spaces, potentially on different hosts, be able to communicate. For a basic communication mechanism, the JavaTM programming language supports sockets, which are flexible and sufficient for general communication. However, sockets require the client and server to engage in applications-level protocols to encode and decode messages for exchange, and the design of such protocols is cumbersome and can be error-prone.

An alternative to sockets is Remote Procedure Call (RPC), which abstracts the communication interface to the level of a procedure call. Instead of working directly with sockets, the programmer has the illusion of calling a local procedure, when in fact the arguments of the call are packaged up and shipped off to the remote target of the call. RPC systems encode arguments and return values using an external data representation, such as XDR.

RPC, however, does not translate well into distributed object systems, where communication between program-level objects residing in different address spaces is needed. In order to match the semantics of object invocation, distributed object systems require remote method invocation or RMI. In such systems, a local surrogate (stub) object manages the invocation on a remote object.

The Java platform's remote method invocation system described in this specification has been specifically designed to operate in the Java application environment. The Java programming language's RMI system assumes the homogeneous environment of the Java virtual machine (JVM), and the system can therefore take advantage of the Java platform's object model whenever possible.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


1 - Introduction

CONTENTS | PREV | NEXT Java Remote Method Invocation

1.2 System Goals

The goals for supporting distributed objects in the Java programming language are:

  • Support seamless remote invocation on objects in different virtual machines
  • Support callbacks from servers to applets
  • Integrate the distributed object model into the Java programming language in a natural way while retaining most of the Java programming language's object semantics
  • Make differences between the distributed object model and local Java platform's object model apparent
  • Make writing reliable distributed applications as simple as possible
  • Preserve the type-safety provided by the Java platform's runtime environment
  • Support various reference semantics for remote objects; for example live (nonpersistent) references, persistent references, and lazy activation
  • Maintain the safe environment of the Java platform provided by security managers and class loaders
Underlying all these goals is a general requirement that the RMI model be both simple (easy to use) and natural (fits well in the language).

The first two chapters in this specification describe the distributed object model for the Java programming language and the system overview. The remaining chapters describe the RMI client and server visible APIs which are part of the Java SE platform.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


2 - Distributed Object Model

CONTENTS | PREV | NEXT Java Remote Method Invocation

2.7 Locating Remote Objects

A simple bootstrap name server is provided for storing named references to remote objects. A remote object reference can be stored using the URL-based methods of the class java.rmi.Naming.

For a client to invoke a method on a remote object, that client must first obtain a reference to the object. A reference to a remote object is usually obtained as a parameter or return value in a method call. The RMI system provides a simple bootstrap name server from which to obtain remote objects on given hosts. The java.rmi.Naming class provides Uniform Resource Locator (URL) based methods to look up, bind, rebind, unbind, and list the name-object pairings maintained on a particular host and port.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


2 - Distributed Object Model

CONTENTS | PREV | NEXT Java Remote Method Invocation

2.5 Implementing a Remote Interface

The general rules for a class that implements a remote interface are as follows:

  • The class usually extends java.rmi.server.UnicastRemoteObject, thereby inheriting the remote behavior provided by the classes java.rmi.server.RemoteObject and java.rmi.server.RemoteServer.
  • The class can implement any number of remote interfaces.
  • The class can extend another remote implementation class.
  • The class can define methods that do not appear in the remote interface, but those methods can only be used locally and are not available remotely.
For example, the following class BankAcctImpl implements the BankAccount remote interface and extends the java.rmi.server.UnicastRemoteObject class:

package mypackage;

import java.rmi.RemoteException;
import java.rmi.server.UnicastRemoteObject;

public class BankAccountImpl
    extends UnicastRemoteObject
    implements BankAccount
{
    private float balance = 0.0;

    public BankAccountImpl(float initialBalance)
        throws RemoteException
    {
        balance = initialBalance;
    }
    public void deposit(float amount) throws RemoteException {
        ...
    }
    public void withdraw(float amount) throws OverdrawnException,
        RemoteException {
        ...
    }
    public float getBalance() throws RemoteException {
        ...
    }
}
Note that if necessary, a class that implements a remote interface can extend some other class besides java.rmi.server.UnicastRemoteObject. However, the implementation class must then assume the responsibility for exporting the object (taken care of by the UnicastRemoteObject constructor) and for implementing (if needed) the correct remote semantics of the hashCode, equals, and toString methods inherited from the java.lang.Object class.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


2 - Distributed Object Model

CONTENTS | PREV | NEXT Java Remote Method Invocation

2.6 Parameter Passing in Remote Method Invocation

An argument to, or a return value from, a remote object can be any object that is serializable. This includes primitive types, remote objects, and non-remote objects that implement the java.io.Serializable interface. For more details on how to make classes serializable, see the "Java Object Serialization Specification." Classes, for parameters or return values, that are not available locally are downloaded dynamically by the RMI system. See the section on "Dynamic Class Loading" for more information on how RMI downloads parameter and return value classes when reading parameters, return values and exceptions.

2.6.1 Passing Non-remote Objects

A non-remote object, that is passed as a parameter of a remote method invocation or returned as a result of a remote method invocation, is passed by copy; that is, the object is serialized using the object serialization mechanism of the Java SE platform.

So, when a non-remote object is passed as an argument or return value in a remote method invocation, the content of the non-remote object is copied before invoking the call on the remote object.

When a non-remote object is returned from a remote method invocation, a new object is created in the calling virtual machine.

2.6.2 Passing Remote Objects

When passing an exported remote object as a parameter or return value in a remote method call, the stub for that remote object is passed instead. Remote objects that are not exported will not be replaced with a stub instance. A remote object passed as a parameter can only implement remote interfaces.

2.6.3 Referential Integrity

If two references to an object are passed from one JVM to another JVM in parameters (or in the return value) in a single remote method call and those references refer to the same object in the sending JVM, those references will refer to a single copy of the object in the receiving JVM. More generally stated: within a single remote method call, the RMI system maintains referential integrity among the objects passed as parameters or as a return value in the call.

2.6.4 Class Annotation

When an object is sent from one JVM to another in a remote method call, the RMI system annotates the class descriptor in the call stream with information (the URL) of the class so that the class can be loaded at the receiver. It is a requirement that classes be downloaded on demand during remote method invocation.

2.6.5 Parameter Transmission

Parameters in an RMI call are written to a stream that is a subclass of the class java.io.ObjectOutputStream in order to serialize the parameters to the destination of the remote call. The ObjectOutputStream subclass overrides the replaceObject method to replace each exported remote object with its corresponding stub instance. Parameters that are objects are written to the stream using the ObjectOutputStream's writeObject method. The ObjectOutputStream calls the replaceObject method for each object written to the stream via the writeObject method (that includes objects referenced by those objects that are written). The replaceObject method of RMI's subclass of ObjectOutputStream returns the following:

  • If the object passed to replaceObject is an instance of java.rmi.Remote and that object is exported to the RMI runtime, then it returns the stub for the remote object. If the object is an instance of java.rmi.Remote and the object is not exported to the RMI runtime, then replaceObject returns the object itself. A stub for a remote object is obtained via a call to the method java.rmi.server.RemoteObject.toStub.
  • If the object passed to replaceObject is not an instance of java.rmi.Remote, then the object is simply returned.
RMI's subclass of ObjectOutputStream also implements the annotateClass method that annotates the call stream with the location of the class so that it can be downloaded at the receiver. See the section "Dynamic Class Loading" for more information on how annotateClass is used.

Since parameters are written to a single ObjectOutputStream, references that refer to the same object at the caller will refer to the same copy of the object at the receiver. At the receiver, parameters are read by a single ObjectInputStream.

Any other default behavior of ObjectOutputStream for writing objects (and similarly ObjectInputStream for reading objects) is maintained in parameter passing. For example, the calling of writeReplace when writing objects and readResolve when reading objects is honored by RMI's parameter marshal and unmarshal streams.

In a similar manner to parameter passing in RMI as described above, a return value (or exception) is written to a subclass of ObjectOutputStream and has the same replacement behavior as parameter transmission.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


2 - Distributed Object Model

CONTENTS | PREV | NEXT Java Remote Method Invocation

2.1 Distributed Object Applications

RMI applications are often comprised of two separate programs: a server and a client. A typical server application creates a number of remote objects, makes references to those remote objects accessible, and waits for clients to invoke methods on those remote objects. A typical client application gets a remote reference to one or more remote objects in the server and then invokes methods on them. RMI provides the mechanism by which the server and the client communicate and pass information back and forth. Such an application is sometimes referred to as a distributed object application.

Distributed object applications need to:

  • Locate remote objects

    • Applications can use one of two mechanisms to obtain references to remote objects. An application can register its remote objects with RMI's simple naming facility, the rmiregistry, or the application can pass and return remote object references as part of its normal operation.

  • Communicate with remote objects

    • Details of communication between remote objects are handled by RMI; to the programmer, remote communication looks like a standard method invocation.

  • Load class bytecodes for objects that are passed as parameters or return values

    • Because RMI allows a caller to pass objects to remote objects, RMI provides the necessary mechanisms for loading an object's code as well as transmitting its data.

The illustration below depicts an RMI distributed application that uses the registry to obtain references to a remote object. The server calls the registry to associate a name with a remote object. The client looks up the remote object by its name in the server's registry and then invokes a method on it. The illustration also shows that the RMI system uses an existing web server to load bytecodes of classes written in the Java programming language, from server to client and from client to server, for objects when needed. RMI can load class bytecodes using any URL protocol (e.g., HTTP, FTP, file, etc.) that is supported by the Java platform.

This illustration depicts an RMI distributed application that uses the registry to obtain references to a remote object.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


2 - Distributed Object Model

CONTENTS | PREV | NEXT Java Remote Method Invocation

2.2 Definition of Terms

In the Java SE platform's distributed object model, a remote object is one whose methods can be invoked from another Java virtual machine, potentially on a different host. An object of this type is described by one or more remote interfaces, which are interfaces written in the Java programming language that declare the methods of the remote object.

Remote method invocation (RMI) is the action of invoking a method of a remote interface on a remote object. Most importantly, a method invocation on a remote object has the same syntax as a method invocation on a local object.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


2 - Distributed Object Model

CONTENTS | PREV | NEXT Java Remote Method Invocation

Distributed Object Model

CHAPTER 2

Topics:

  • Distributed Object Applications
  • Definition of Terms
  • The Distributed and Nondistributed Models Contrasted
  • Overview of RMI Interfaces and Classes
  • Implementing a Remote Interface
  • Parameter Passing in Remote Method Invocation
  • Locating Remote Objects

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


2 - Distributed Object Model

CONTENTS | PREV | NEXT Java Remote Method Invocation

2.3 The Distributed and Nondistributed Models Contrasted

The Java SE platform's distributed object model is similar to the Java SE platform's object model in the following ways:

  • A reference to a remote object can be passed as an argument or returned as a result in any method invocation (local or remote).
  • A remote object can be cast to any of the set of remote interfaces supported by the implementation using the syntax for casting built into the Java programming language.
  • The built-in instanceof operator can be used to test the remote interfaces supported by a remote object.
The Java SE platform's distributed object model differs from the Java SE platform's object model in these ways:

  • Clients of remote objects interact with remote interfaces, never with the implementation classes of those interfaces.
  • Non-remote arguments to, and results from, a remote method invocation are passed by copy rather than by reference. This is because references to objects are only useful within a single virtual machine.
  • A remote object is passed by reference, not by copying the actual remote implementation.
  • The semantics of some of the methods defined by class java.lang.Object are specialized for remote objects.
  • Since the failure modes of invoking remote objects are inherently more complicated than the failure modes of invoking local objects, clients must deal with additional exceptions that can occur during a remote method invocation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


2 - Distributed Object Model

CONTENTS | PREV | NEXT Java Remote Method Invocation

2.4 Overview of RMI Interfaces and Classes

The interfaces and classes that are responsible for specifying the remote behavior of the RMI system are defined in the java.rmi package hierarchy. The following figure shows the relationship between several of these interfaces and classes:

relationship between several of these interfaces and classes

2.4.1 The java.rmi.Remote Interface

In RMI, a remote interface is an interface that declares a set of methods that may be invoked from a remote Java virtual machine. A remote interface must satisfy the following requirements:

  • A remote interface must at least extend, either directly or indirectly, the interface java.rmi.Remote.
  • Each method declaration in a remote interface or its super-interfaces must satisfy the requirements of a remote method declaration as follows:
    • A remote method declaration must include the exception java.rmi.RemoteException (or one of its superclasses such as java.io.IOException or java.lang.Exception) in its throws clause, in addition to any application-specific exceptions (note that application specific exceptions do not have to extend java.rmi.RemoteException).
    • In a remote method declaration, a remote object declared as a parameter or return value (either declared directly in the parameter list or embedded within a non-remote object in a parameter) must be declared as the remote interface, not the implementation class of that interface.
The interface java.rmi.Remote is a marker interface that defines no methods:

public interface Remote {}
A remote interface must at least extend the interface java.rmi.Remote (or another remote interface that extends java.rmi.Remote). However, a remote interface may extend a non-remote interface under the following condition:

  • A remote interface may also extend another non-remote interface, as long as all of the methods (if any) of the extended interface satisfy the requirements of a remote method declaration.
For example, the following interface BankAccount defines a remote interface for accessing a bank account. It contains remote methods to deposit to the account, to get the account balance, and to withdraw from the account:

public interface BankAccount extends java.rmi.Remote {
    public void deposit(float amount)
        throws java.rmi.RemoteException;
    public void withdraw(float amount)
        throws OverdrawnException, java.rmi.RemoteException;
    public float getBalance()
        throws java.rmi.RemoteException;
}
The next example shows a valid remote interface Beta that extends a non-remote interface Alpha, which has remote methods, and the interface java.rmi.Remote:

public interface Alpha {
    public final String okay = "constants are okay too";
    public Object foo(Object obj)
        throws java.rmi.RemoteException;
    public void bar() throws java.io.IOException;
    public int baz() throws java.lang.Exception;
}

public interface Beta extends Alpha, java.rmi.Remote {
    public void ping() throws java.rmi.RemoteException;
}

2.4.2 The RemoteException Class

The java.rmi.RemoteException class is the superclass of exceptions thrown by the RMI runtime during a remote method invocation. To ensure the robustness of applications using the RMI system, each remote method declared in a remote interface must specify java.rmi.RemoteException (or one of its superclasses such as java.io.IOException or java.lang.Exception) in its throws clause.

The exception java.rmi.RemoteException is thrown when a remote method invocation fails for some reason. Some reasons for remote method invocation failure include:

  • Communication failure (the remote server is unreachable or is refusing connections; the connection is closed by the server, etc.)
  • Failure during parameter or return value marshalling or unmarshalling

  • Protocol errors
The class RemoteException is a checked exception (one that must be handled by the caller of a remote method and is checked by the compiler), not a RuntimeException.

2.4.3 The RemoteObject Class and its Subclasses

RMI server functions are provided by java.rmi.server.RemoteObject and its subclasses, java.rmi.server.RemoteServer and java.rmi.server.UnicastRemoteObject and java.rmi.activation.Activatable.

  • The class java.rmi.server.RemoteObject provides implementations for the java.lang.Object methods, hashCode, equals, and toString that are sensible for remote objects.
  • The methods needed to create remote objects and export them (make them available to remote clients) are provided by the classes UnicastRemoteObject and Activatable. The subclass identifies the semantics of the remote reference, for example whether the server is a simple remote object or is an activatable remote object (one that executes when invoked).

  • The java.rmi.server.UnicastRemoteObject class defines a singleton (unicast) remote object whose references are valid only while the server process is alive.
  • The class java.rmi.activation.Activatable is an abstract class that defines an activatable remote object that starts executing when its remote methods are invoked and can shut itself down when necessary.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


3 - RMI System Overview

CONTENTS | PREV | NEXT Java Remote Method Invocation

RMI System Overview

CHAPTER 3

Topics:

  • Stubs and Skeletons
  • Thread Usage in Remote Method Invocations
  • Garbage Collection of Remote Objects
  • Dynamic Class Loading
  • RMI Through Firewalls Via Proxies

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


3 - RMI System Overview

CONTENTS | PREV | NEXT Java Remote Method Invocation

3.3 Garbage Collection of Remote Objects

In a distributed system, just as in the local system, it is desirable to automatically delete those remote objects that are no longer referenced by any client. This frees the programmer from needing to keep track of the remote objects' clients so that it can terminate appropriately. RMI uses a reference-counting garbage collection algorithm similar to Modula-3's Network Objects. (See "Network Objects" by Birrell, Nelson, and Owicki, Digital Equipment Corporation Systems Research Center Technical Report 115, 1994.)

To accomplish reference-counting garbage collection, the RMI runtime keeps track of all live references within each Java virtual machine. When a live reference enters a Java virtual machine, its reference count is incremented. The first reference to an object sends a "referenced" message to the server for the object. As live references are found to be unreferenced in the local virtual machine, the count is decremented. When the last reference has been discarded, an unreferenced message is sent to the server. Many subtleties exist in the protocol; most of these are related to maintaining the ordering of referenced and unreferenced messages in order to ensure that the object is not prematurely collected.

When a remote object is not referenced by any client, the RMI runtime refers to it using a weak reference. The weak reference allows the Java virtual machine's garbage collector to discard the object if no other local references to the object exist. The distributed garbage collection algorithm interacts with the local Java virtual machine's garbage collector in the usual ways by holding normal or weak references to objects.

As long as a local reference to a remote object exists, it cannot be garbage-collected and it can be passed in remote calls or returned to clients. Passing a remote object adds the identifier for the virtual machine to which it was passed to the referenced set. A remote object needing unreferenced notification must implement the java.rmi.server.Unreferenced interface. When those references no longer exist, the unreferenced method will be invoked. unreferenced is called when the set of references is found to be empty so it might be called more than once. Remote objects are only collected when no more references, either local or remote, still exist.

Note that if a network partition exists between a client and a remote server object, it is possible that premature collection of the remote object will occur (since the transport might believe that the client crashed). Because of the possibility of premature collection, remote references cannot guarantee referential integrity; in other words, it is always possible that a remote reference may in fact not refer to an existing object. An attempt to use such a reference will generate a RemoteException which must be handled by the application.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


3 - RMI System Overview

CONTENTS | PREV | NEXT Java Remote Method Invocation

3.4 Dynamic Class Loading

RMI allows parameters, return values and exceptions passed in RMI calls to be any object that is serializable. RMI uses the object serialization mechanism to transmit data from one virtual machine to another and also annotates the call stream with the appropriate location information so that the class definition files can be loaded at the receiver.

When parameters and return values for a remote method invocation are unmarshalled to become live objects in the receiving JVM, class definitions are required for all of the types of objects in the stream. The unmarshalling process first attempts to resolve classes by name in its local class loading context (the context class loader of the current thread). RMI also provides a facility for dynamically loading the class definitions for the actual types of objects passed as parameters and return values for remote method invocations from network locations specified by the transmitting endpoint. This includes the dynamic downloading of remote stub classes corresponding to particular remote object implementation classes (and used to contain remote references) as well as any other type that is passed by value in RMI calls, such as the subclass of a declared parameter type, that is not already available in the class loading context of the unmarshalling side.

To support dynamic class loading, the RMI runtime uses special subclasses of java.io.ObjectOutputStream and java.io.ObjectInputStream for the marshal streams that it uses for marshalling and unmarshalling RMI parameters and return values. These subclasses respectively override the annotateClass method of ObjectOutputStream and the resolveClass method of ObjectInputStream to communicate information about where to locate class files containing the definitions for classes corresponding to the class descriptors in the stream.

For every class descriptor written to an RMI marshal stream, the annotateClass method adds to the stream the result of calling java.rmi.server.RMIClassLoader.getClassAnnotation for the class object, which may be null or may be a String object representing the codebase URL path (a space-separated list of URLs) from which the remote endpoint should download the class definition file for the given class.

For every class descriptor read from an RMI marshal stream, the resolveClass method reads a single object from the stream. If the object is a String (and the value of the java.rmi.server.useCodebaseOnly property is not true), then resolveClass returns the result of calling RMIClassLoader.loadClass with the annotated String object as the first parameter and the name of the desired class in the class descriptor as the second parameter. Otherwise, resolveClass returns the result of calling RMIClassLoader.loadClass with the name of the desired class as the only parameter.

See the section "The RMIClassLoader Class" for more details about class loading in RMI.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


3 - RMI System Overview

CONTENTS | PREV | NEXT Java Remote Method Invocation

3.2 Thread Usage in Remote Method Invocations

A method dispatched by the RMI runtime to a remote object implementation may or may not execute in a separate thread. The RMI runtime makes no guarantees with respect to mapping remote object invocations to threads. Since remote method invocation on the same remote object may execute concurrently, a remote object implementation needs to make sure its implementation is thread-safe.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


3 - RMI System Overview

CONTENTS | PREV | NEXT Java Remote Method Invocation

3.5 RMI Through Firewalls Via Proxies

The RMI transport layer normally attempts to open direct sockets to hosts on the Internet. Many intranets, however, have firewalls that do not allow this. The default RMI transport, therefore, provides two alternate HTTP-based mechanisms which enable a client behind a firewall to invoke a method on a remote object which resides outside the firewall.

As described in this section, the HTTP-based mechanism that the RMI transport layer uses for RMI calls only applies to firewalls with HTTP proxy servers.

3.5.1 How an RMI Call is Packaged within the HTTP Protocol

To get outside a firewall, the transport layer embeds an RMI call within the firewall-trusted HTTP protocol. The RMI call data is sent outside as the body of an HTTP POST request, and the return information is sent back in the body of the HTTP response. The transport layer will formulate the POST request in one of two ways:

    1. If the firewall proxy will forward an HTTP request directed to an arbitrary port on the host machine, then it is forwarded directly to the port on which the RMI server is listening. The default RMI transport layer on the target machine is listening with a server socket that is capable of understanding and decoding RMI calls inside POST requests.
    2. If the firewall proxy will only forward HTTP requests directed to certain well-known HTTP ports, then the call is forwarded to the HTTP server listening on port 80 of the host machine, and a CGI script is executed to forward the call to the target RMI server port on the same machine.

3.5.2 The Default Socket Factory

The RMI transport implementation includes an extension of the class java.rmi.server.RMISocketFactory, which is the default resource-provider for client and server sockets used to send and receive RMI calls; this default socket factory can be obtained via the java.rmi.server.RMISocketFactory.getDefaultSocketFactory method. This default socket factory creates sockets that transparently provide the firewall tunnelling mechanism as follows:

  • Client sockets first attempt a direct socket connection. Client sockets automatically attempt HTTP connections to hosts that cannot be contacted with a direct socket if that direct socket connection results in either a java.net.NoRouteToHostException or a java.net.UnknownHostException being thrown. If a direct socket connection results in any other java.io.IOException being thrown, such as a java.net.ConnectException, the implementation may attempt an HTTP connection.
  • Server sockets automatically detect if a newly-accepted connection is an HTTP POST request, and if so, return a socket that will expose only the body of the request to the transport and format its output as an HTTP response.
Client-side sockets, with this default behavior, are provided by the factory's java.rmi.server.RMISocketFactory.createSocket method. Server-side sockets with this default behavior are provided by the factory's java.rmi.server.RMISocketFactory.createServerSocket method.

3.5.3 Configuring the Client

A client can disable the packaging of RMI calls as HTTP requests by setting the java.rmi.server.disableHttp property to equal the boolean value true.

3.5.4 Configuring the Server

Note - The host name should not be specified as the host's IP address, because some firewall proxies will not forward to such a host name.
    1. In order for a client outside the server host's domain to be able to invoke methods on a server's remote objects, the client must be able to find the server. To do this, the remote references that the server exports must contain the fully-qualified name of the server host.

      2. Depending on the server's platform and network environment, this information may or may not be available to the Java virtual machine on which the server is running. If it is not available, the host's fully qualified name must be specified with the property java.rmi.server.hostname when starting the server.

      For example, use this command to start the RMI server class ServerImpl on the machine chatsubo.javasoft.com:

         java -Djava.rmi.server.hostname=chatsubo.javasoft.com ServerImpl
    2. If the server will not support RMI clients behind firewalls that can forward to arbitrary ports, use this configuration:

      1. An HTTP server is listening on port 80.

      2. A CGI script is located at the aliased URL path

        /cgi-bin/java-rmi.cgi
        This script:

        • Invokes the local interpreter for the Java programming language to execute a class internal to the transport layer which forwards the request to the appropriate RMI server port.

        • Defines properties in the Java virtual machine with the same names and values as the CGI 1.0 defined environment variables.

    An example script is supplied in the RMI distribution for the Solaris and Windows 32 operating systems. Note that the script must specify the complete path to the interpreter for the Java programming language on the server machine.

3.5.5 Performance Issues and Limitations

Calls transmitted via HTTP requests are at least an order of magnitude slower that those sent through direct sockets, without taking proxy forwarding delays into consideration.

Because HTTP requests can only be initiated in one direction through a firewall, a client cannot export its own remote objects outside the firewall, because a host outside the firewall cannot initiate a method invocation back on the client.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


3 - RMI System Overview

CONTENTS | PREV | NEXT Java Remote Method Invocation

3.1 Stubs and Skeletons

RMI uses a standard mechanism (employed in RPC systems) for communicating with remote objects: stubs and skeletons. A stub for a remote object acts as a client's local representative or proxy for the remote object. The caller invokes a method on the local stub which is responsible for carrying out the method call on the remote object. In RMI, a stub for a remote object implements the same set of remote interfaces that a remote object implements.

When a stub's method is invoked, it does the following:

  • initiates a connection with the remote JVM containing the remote object,
  • marshals (writes and transmits) the parameters to the remote JVM,
  • waits for the result of the method invocation,
  • unmarshals (reads) the return value or exception returned, and
  • returns the value to the caller.
The stub hides the serialization of parameters and the network-level communication in order to present a simple invocation mechanism to the caller.

In the remote JVM, each remote object may have a corresponding skeleton (in Java 2 platform-only environments, skeletons are not required). The skeleton is responsible for dispatching the call to the actual remote object implementation. When a skeleton receives an incoming method invocation it does the following:

  • unmarshals (reads) the parameters for the remote method,
  • invokes the method on the actual remote object implementation, and
  • marshals (writes and transmits) the result (return value or exception) to the caller.
In the Java 2 SDK, Standard Edition, v1.2 an additional stub protocol was introduced that eliminates the need for skeletons in Java 2 platform-only environments. Instead, generic code is used to carry out the duties performed by skeletons in JDK1.1. Stubs and skeletons are generated by the rmic compiler.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


4 - Client Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

4.3 The Naming Class

See the Naming API documentation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


4 - Client Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

4.1 The Remote Interface

See the Remote API documentation, and for more details on how to define a remote interface see the section "The java.rmi.Remote Interface".

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


4 - Client Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

Client Interfaces

CHAPTER 4

When writing an applet or an application that uses remote objects, the programmer needs to be aware of the RMI system's client visible interfaces that are available in the java.rmi package.

Topics:

  • The Remote Interface
  • The RemoteException Class
  • The Naming Class

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


4 - Client Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

4.2 The RemoteException Class

See the RemoteException API documentation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


5 - Server Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

5.9 The RMIFailureHandler Interface

The java.rmi.server.RMIFailureHandler interface provides a method for specifying how the RMI runtime should respond when server socket creation fails (except during object export).

package java.rmi.server;

public interface RMIFailureHandler {

    public boolean failure(Exception ex);
}
The failure method is invoked with the exception that prevented the RMI runtime from creating a java.net.ServerSocket. The method returns true if the runtime should attempt to retry and false otherwise.

Before this method can be invoked, a failure handler needs to be registered via the RMISocketFactory.setFailureHandler call. If the failure handler is not set, the RMI runtime attempts to re-create the ServerSocket after waiting for a short period of time.

Note that the RMIFailureHandler is not called when ServerSocket creation fails upon initial export of the object. The RMIFailureHandler will be called when there is an attempt to create a ServerSocket after a failed accept on that ServerSocket.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


5 - Server Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

5.3 The UnicastRemoteObject Class

The class java.rmi.server.UnicastRemoteObject provides support for creating and exporting remote objects. The class implements a remote server object with the following characteristics:

  • References to such objects are valid only for, at most, the life of the process that creates the remote object.
  • Communication with the remote object uses a TCP transport.
  • Invocations, parameters, and results use a stream protocol for communicating between client and server.
package java.rmi.server;

public class UnicastRemoteObject extends RemoteServer {

    protected UnicastRemoteObject()
        throws java.rmi.RemoteException {...}
    protected UnicastRemoteObject(int port)
        throws java.rmi.RemoteException {...}
    protected UnicastRemoteObject(int port,
                                      RMIClientSocketFactory csf,
                                      RMIServerSocketFactory ssf)
        throws java.rmi.RemoteException {...}

    public Object clone()
        throws java.lang.CloneNotSupportedException {...}
    public static RemoteStub exportObject(java.rmi.Remote obj)
        throws java.rmi.RemoteException {...}
    public static Remote exportObject(java.rmi.Remote obj, int port)
        throws java.rmi.RemoteException {...}
    public static Remote exportObject(Remote obj, int port,
                                          RMIClientSocketFactory csf,
                                          RMIServerSocketFactory ssf)
        throws java.rmi.RemoteException {...}
    public static boolean unexportObject(java.rmi.Remote obj,
                                             boolean force)
        throws java.rmi.NoSuchObjectException {...}
}

5.3.1 Constructing a New Remote Object

A remote object implementation (one that implements one or more remote interfaces) must be created and exported. Exporting a remote object makes that object available to accept incoming calls from clients. For a remote object implementation that is exported as a UnicastRemoteObject, the exporting involves listening on a TCP port (note that more than one remote object can accept incoming calls on the same port, so listening on a new port is not always necessary). A remote object implementation can extend the class UnicastRemoteObject to make use of its constructors that export the object, or it can extend some other class (or none at all) and export the object via UnicastRemoteObject's exportObject methods.

The no argument constructor creates and exports a remote object on an anonymous (or arbitrary) port, chosen at runtime. The second form of the constructor takes a single argument, port, that specifies the port number on which the remote object accepts incoming calls. The third constructor creates and exports a remote object that accepts incoming calls on the specified port via a ServerSocket created from the RMIServerSocketFactory; clients will make connections to the remote object via Sockets supplied from the RMIClientSocketFactory.

5.3.2 Exporting an Implementation Not Extended From RemoteObject

An exportObject method (any of the forms) is used to export a simple peer-to-peer remote object that is not implemented by extending the UnicastRemoteObject class. The first form of the exportObject method takes a single parameter, obj, which is the remote object that will accept incoming RMI calls; this exportObject method exports the object on an anonymous (or arbitrary) port, chosen at runtime. The second exportObject method takes two parameters, both the remote object, obj, and port, the port number on which the remote object accepts incoming calls. The third exportObject method exports the object, obj, with the specified RMIClientSocketFactory, csf, and RMIServerSocketFactory, ssf, on the specified port.

The exportObject method returns a Remote stub which is the stub object for the remote object, obj, that is passed in place of the remote object in an RMI call.

5.3.3 Passing a UnicastRemoteObject in an RMI Call

As stated above, when an exported object of type UnicastRemoteObject is passed as a parameter or return value in an RMI call, the object is replaced by the remote object's stub. An exported remote object implementation remains in the virtual machine in which it was created and does not move (even by value) from that virtual machine. In other words, an exported remote object is passed by reference in an RMI call; exported remote object implementations cannot be passed by value.

5.3.4 Serializing a UnicastRemoteObject

Information contained in UnicastRemoteObject is transient and is not saved if an object of that type is written to a user-defined ObjectOutputStream (for example, if the object is written to a file using serialization). An object that is an instance of a user-defined subclass of UnicastRemoteObject, however, may have non-transient data that can be saved when the object is serialized.

When a UnicastRemoteObject is read from an ObjectInputStream using UnicastRemoteObject's readObject method, the remote object is automatically exported to the RMI runtime so that it may receive RMI calls. If exporting the object fails for some reason, deserializing the object will terminate with an exception.

5.3.5 Unexporting a UnicastRemoteObject

The unexportObject method makes the remote object, obj, unavailable for incoming calls. If the force parameter is true, the object is forcibly unexported even if there are pending calls to the remote object or the remote object still has calls in progress. If the force parameter is false, the object is only unexported if there are no pending or in-progress calls to the object. If the object is successfully unexported, the RMI runtime removes the object from its internal tables. Unexporting the object in this forcible manner may leave clients holding stale remote references to the remote object. This method throws java.rmi.NoSuchObjectException if the object was not previously exported to the RMI runtime.

5.3.6 The clone method

Objects are only clonable using the Java programming language's default mechanism if they support the java.lang.Cloneable interface. The class java.rmi.server.UnicastRemoteObject does not implement this interface, but does implement the clone method so that if subclasses need to implement Cloneable, the remote object will be capable of being cloned properly. The clone method can be used by a subclass to create a cloned remote object with initially the same contents, but is exported to accept remote calls and is distinct from the original object.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


5 - Server Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

5.4 The Unreferenced Interface

package java.rmi.server;

public interface Unreferenced {
    public void unreferenced();
}
The java.rmi.server.Unreferenced interface allows a server object to receive notification that there are no clients holding remote references to it. The distributed garbage collection mechanism maintains for each remote object, the set of client virtual machines that hold references to that remote object. As long as some client holds a remote reference to the remote object, the RMI runtime keeps a local reference to the remote object. Each time the remote object's "reference" set becomes empty (meaning that the number of clients that reference the object becomes zero), the Unreferenced.unreferenced method is invoked (if that remote object implements the Unreferenced interface). A remote object is not required to support the Unreferenced interface.

As long as some local reference to the remote object exists, it may be passed in remote calls or returned to clients. The process that receives the reference is added to the reference set for the remote object. When the reference set becomes empty, the remote object's unreferenced method will be invoked. As such, the unreferenced method can be called more than once (each time the set is newly emptied). Remote objects are only collected when no more references, either local references or those held by clients, still exist.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


5 - Server Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

5.10 The LogStream Class

See the LogStream API documentation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


5 - Server Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

5.5 The RMISecurityManager Class

See the RMISecurityManager API documentation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


5 - Server Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

5.1 The RemoteObject Class

See the RemoteObject API documentation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


5 - Server Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

5.6 The RMIClassLoader Class

See the RMIClassLoader API documentation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


5 - Server Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

Server Interfaces

CHAPTER 5
The java.rmi.server package contains interfaces and classes typically used to implement remote objects.

Topics:

  • The RemoteObject Class
  • The RemoteServer Class
  • The UnicastRemoteObject Class
  • The Unreferenced Interface
  • The RMISecurityManager Class
  • The RMIClassLoader Class
  • The LoaderHandler Interface
  • RMI Socket Factories
  • The RMIFailureHandler Interface
  • The LogStream Class
  • Stub and Skeleton Compiler

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


5 - Server Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

5.7 The LoaderHandler Interface

See the LoaderHandler API documentation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


5 - Server Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

5.2 The RemoteServer Class

See the RemoteServer API documentation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


5 - Server Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

5.8 RMI Socket Factories

When the RMI runtime implementation needs instances of java.net.Socket and java.net.ServerSocket for its connections, instead of instantiating objects of those classes directly, it calls the createSocket and createServerSocket methods on the current RMISocketFactory object, returned by the static method RMISocketFactory.getSocketFactory. This allows the application to have a hook to customize the type of sockets used by the RMI transport, such as alternate subclasses of the java.net.Socket and java.net.ServerSocket classes. The instance of RMISocketFactory to be used can be set once by trusted system code. In JDK1.1, this customization was limited to relatively global decisions about socket type, because the only parameters supplied to the factory's methods were host and port (for createSocket) and just port (for createServerSocket).

In the Java SE platform, the new interfaces RMIServerSocketFactory and RMIClientSocketFactory have been introduced to provide more flexible customization of what protocols are used to communicate with remote objects.

To allow applications using RMI to take advantage of these new socket factory interfaces, several new constructors and exportObject methods, that take the client and server socket factory as additional parameters, have been added to both UnicastRemoteObject and java.rmi.activation.Activatable.

Remote objects exported with either of the new constructors or exportObject methods (with RMIClientSocketFactory and RMIServerSocketFactory parameters) will be treated differently by the RMI runtime. For the lifetime of such a remote object, the runtime will use the custom RMIServerSocketFactory to create a ServerSocket to accept incoming calls to the remote object and use the custom RMIClientSocketFactory to create a Socket to connect clients to the remote object.

The implementation of RemoteRef and ServerRef used in the stubs and skeletons for remote objects exported with custom socket factories is UnicastRef2 and UnicastServerRef2, respectively. The wire representation of the UnicastRef2 type contains a different representation of the "endpoint" to contact than the UnicastRef type has (which used just a host name string in UTF format, following by an integer port number). For UnicastRef2, the endpoint's wire representation consists of a format byte specifying the contents of the rest of the endpoint's representation (to allow for future expansion of the endpoint representation) followed by data in the indicated format. Currently, the data may consist of a hostname in UTF format, a port number, and optionally (as specified by the endpoint format byte) the serialized representation of an RMIClientSocketFactory object that is used by clients to generate socket connections to remote object at this endpoint. The endpoint representation does not contain the RMIServerSocketFactory object that was specified when the remote object was exported.

When calls are made through references of the UnicastRef2 type, the runtime uses the createSocket method of the RMIClientSocketFactory object in the endpoint when creating sockets for connections to the referent remote object. Also, when the runtime makes DGC "dirty" and "clean" calls for a particular remote object, it must call the DGC on the remote JVM using a connection generated from the same RMIClientSocketFactory object as specified in the remote reference, and the DGC implementation on the server side should verify that this was done correctly.

Remote objects exported with the older constructor or method on UnicastRemoteObject that do not take custom socket factories as arguments will have RemoteRef and ServerRef of type UnicastRef and UnicastServerRef as before and use the old wire representation for their endpoints, i.e. a host string in UTF format followed by an integer specifying the port number. This is so that RMI servers that do not use new 1.2 features will interoperate with older RMI clients.

5.8.1 The RMISocketFactory Class

The java.rmi.server.RMISocketFactory abstract class provides an interface for specifying how the transport should obtain sockets. Note that the class below uses Socket and ServerSocket from the java.net package.

package java.rmi.server;

public abstract class RMISocketFactory
    implements RMIClientSocketFactory, RMIServerSocketFactory
{

    public abstract Socket createSocket(String host, int port)
        throws IOException;
     public abstract ServerSocket createServerSocket(int port)
        throws IOException;
    public static void setSocketFactory(RMISocketFactory fac)
        throws IOException {...}
    public static RMISocketFactory getSocketFactory() {...}
    public static void setFailureHandler(RMIFailureHandler fh) {...}
    public static RMIFailureHandler getFailureHandler() {...}
}
The static method setSocketFactory is used to set the socket factory from which RMI obtains sockets. The application may invoke this method with its own RMISocketFactory instance only once. An application-defined implementation of RMISocketFactory could, for example, do preliminary filtering on the requested connection and throw exceptions, or return its own extension of the java.net.Socket or java.net.ServerSocket classes, such as ones that provide a secure communication channel. Note that the RMISocketFactory may only be set if the current security manager allows setting a socket factory; if setting the socket factory is disallowed, a SecurityException will be thrown.

The static method getSocketFactory returns the socket factory used by RMI. The method returns null if the socket factory is not set.

The transport layer invokes the createSocket and createServerSocket methods on the RMISocketFactory returned by the getSocketFactory method when the transport needs to create sockets. For example:

RMISocketFactory.getSocketFactory().createSocket(myhost, myport)
The method createSocket should create a client socket connected to the specified host and port. The method createServerSocket should create a server socket on the specified port.

The default transport's implementation of RMISocketFactory provides for transparent RMI through firewalls using HTTP as follows:

  • On createSocket, the factory automatically attempts HTTP connections to hosts that cannot be contacted with a direct socket.
  • On createServerSocket, the factory returns a server socket that automatically detects if a newly accepted connection is an HTTP POST request. If so, it returns a socket that will transparently expose only the body of the request to the transport and format its output as an HTTP response.
The method setFailureHandler sets the failure handler to be called by the RMI runtime if the creation of a server socket fails. The failure handler returns a boolean to indicate if retry should occur. The default failure handler returns false, meaning that by default recreation of sockets is not attempted by the runtime.

The method getFailureHandler returns the current handler for socket creation failure, or null if the failure handler is not set.

5.8.2 The RMIServerSocketFactory Interface

See the RMIServerSocketFactory API documentation.

5.8.3 The RMIClientSocketFactory Interface

See the RMIClientSocketFactory API documentation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


5 - Server Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

5.11 Stub and Skeleton Compiler

The rmic stub and skeleton compiler is used to compile the appropriate stubs and skeletons for a specific remote object implementation.

Please see the following URLs for further information on rmic:

  • For the SolarisTM Operating System:
http://java.sun.com/products/jdk/1.6.0/docs/tooldocs/solaris/rmic.html
  • For the Windows platform:
http://java.sun.com/products/jdk/1.6.0/docs/tooldocs/windows/rmic.html

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


6 - Registry Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

6.1 The Registry Interface

See the Registry API documentation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


6 - Registry Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

6.3 The RegistryHandler Interface

See the RegistryHandler API documentation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


6 - Registry Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

Registry Interfaces

CHAPTER 6
The RMI system uses the java.rmi.registry.Registry interface and the java.rmi.registry.LocateRegistry class to provide a well-known bootstrap service for retrieving and registering objects by simple names.

A registry is a remote object that maps names to remote objects. Any server process can support its own registry or a single registry can be used for a host.

The methods of LocateRegistry are used to get a registry operating on a particular host or host and port. The methods of the java.rmi.Naming class makes calls to a remote object that implements the Registry interface using the appropriate LocateRegistry.getRegistry method.

Topics:

  • The Registry Interface
  • The LocateRegistry Class
  • The RegistryHandler Interface

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


6 - Registry Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

6.2 The LocateRegistry Class

The class java.rmi.registry.LocateRegistry is used to obtain a reference (construct a stub) to a bootstrap remote object registry on a particular host (including the local host), or to create a remote object registry that accepts calls on a specific port.

The registry implements a simple flat naming syntax that associates the name of a remote object (a string) with a remote object reference. The name and remote object bindings are not remembered across server restarts.

Note that a getRegistry call does not actually make a connection to the remote host. It simply creates a local reference to the remote registry and will succeed even if no registry is running on the remote host. Therefore, a subsequent method invocation to a remote registry returned as a result of this method may fail.

package java.rmi.registry;

public final class LocateRegistry {

    public static Registry getRegistry()
        throws java.rmi.RemoteException {...}
    public static Registry getRegistry(int port)
        throws java.rmi.RemoteException {...}
    public static Registry getRegistry(String host)
        throws java.rmi.RemoteException {...}
    public static Registry getRegistry(String host, int port)
        throws java.rmi.RemoteException {...}
    public static Registry getRegistry(String host, int port,
                                           RMIClientSocketFactory csf)
        throws RemoteException {...}
    public static Registry createRegistry(int port)
        throws java.rmi.RemoteException {...}
    public static Registry createRegistry(int port,
                                      RMIClientSocketFactory csf,
                                      RMIServerSocketFactory ssf)
        throws RemoteException {...}
}
The first four getRegistry methods return a reference to a registry on the current host, current host at a specified port, a specified host, or at a particular port on a specified host. What is returned is the remote stub for the registry with the specified host and port information.

The fifth getRegistry method (that takes an RMIClientSocketFactory as one of its arguments), returns a locally created remote stub to the remote object Registry on the specified host and port. Communication with the remote registry whose stub is constructed with this method will use the supplied RMIClientSocketFactory, csf, to create Socket connections to the registry on the remote host and port.

Note - A registry returned from the getRegistry method is a specially constructed stub that contains a well-known object identifier. Passing a registry stub from one JVM to another is not supported (it may or may not work depending on the implementation). Use the LocateRegistry.getRegistry methods to obtain the appropriate registry for a host.
The createRegistry method creates and exports a registry on the local host on the specified port.

The second createRegistry method allows more flexibility in communicating with the registry. This call creates and exports a Registry on the local host that uses custom socket factories for communication with that registry. The registry that is created listens for incoming requests on the given port using a ServerSocket created from the supplied RMIServerSocketFactory. A client that receives a reference to this registry will use a Socket created from the supplied RMIClientSocketFactory.

Note - Starting a registry with the createRegistry method does not keep the server process alive.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


7 - Remote Object Activation

CONTENTS | PREV | NEXT Java Remote Method Invocation

7.3 Implementation Model for an "Activatable" Remote Object

In order to make a remote object that can be accessed via an activation identifier over time, a developer needs to:

  • register an activation descriptor for the remote object, and
  • include a special constructor in the object's class that the RMI system calls when it activates the activatable object.
An activation descriptor (ActivationDesc) can be registered in one of several ways:

  • via a call to the static register method of the class Activatable, or
  • by creating an "activatable" object via the first or second constructor of the Activatable class, or
  • by exporting an "activatable" object explicitly via Activatable's first or second exportObject method.
For a specific object, only one of the above methods should be used to register the object for activation. See the section below on "Constructing an Activatable Remote Object" for examples on how to implement activatable objects.

7.3.1 The ActivationDesc Class

An ActivationDesc contains the information necessary to activate an object. It contains the object's activation group identifier, the class name for the object, a codebase path (or URLs) from which the object's code can be loaded, and a MarshalledObject that may contain object-specific initialization data used during each activation.

A descriptor registered with the activation system is consulted (during the activation process) to obtain information in order to re-create or activate an object. The MarshalledObject in the object's descriptor is passed as the second argument to the remote object's constructor for the object to use during activation.

package java.rmi.activation;

public final class ActivationDesc implements java.io.Serializable
{

    public ActivationDesc(String className,
                  String codebase,
                  java.rmi.MarshalledObject data)
        throws ActivationException;

    public ActivationDesc(String className,
                  String codebase,
                  java.rmi.MarshalledObject data,
                  boolean restart)
        throws ActivationException;

    public ActivationDesc(ActivationGroupID groupID,
                  String className,
                  String codebase,
                          java.rmi.MarshalledObject data,
                  boolean restart);

    public ActivationDesc(ActivationGroupID groupID,
                  String className,
                  String codebase,
                  java.rmi.MarshalledObject data);

    public ActivationGroupID getGroupID();

    public String getClassName();

    public String getLocation();

    public java.rmi.MarshalledObject getData()

    public boolean getRestartMode();
}
The first constructor for ActivationDesc constructs an object descriptor for an object whose class is className, that can be loaded from codebase path, and whose initialization information, in marshalled form, is data. If this form of the constructor is used, the object's group identifier defaults to the current identifier for ActivationGroup for this JVM. All objects with the same ActivationGroupID are activated in the same JVM. If the current group is inactive an ActivationException is thrown. If the groupID is null, an IllegalArgumentException is thrown.

The second constructor for ActivationDesc constructs an object descriptor in the same manner as the first constructor except an additional parameter, restart, must be supplied. If the object requires restart service, meaning that the object will be restarted automatically when the activator is restarted (as opposed to being activated lazily upon demand), restart should be true. If restart is false, the object is simply activated upon demand (via a remote method call).

The third constructor for ActivationDesc constructs an object descriptor for an object whose group identifier is groupID, whose class name is className that can be loaded from the codebase path, and whose initialization information is data. All objects with the same groupID are activated in the same JVM.

The fourth constructor for ActivationDesc constructs an object descriptor in the same manner as the third constructor, but allows a restart mode to be specified. If an object requires restart service (as defined above), restart should be true.

The getGroupID method returns the group identifier for the object specified by the descriptor. A group provides a way to aggregate objects into a single Java virtual machine.

The getClassName method returns the class name for the object specified by the activation descriptor.

The getLocation method returns the codebase path from where the object's class can be downloaded.

The getData method returns a "marshalled object" containing initialization (activation) data for the object specified by the descriptor.

The getRestartMode method returns true if the restart mode is enabled for this object, otherwise it returns false.

7.3.2 The ActivationID Class

The activation protocol makes use of activation identifiers to denote remote objects that can be activated over time. An activation identifier (an instance of the class ActivationID) contains several pieces of information needed for activating an object:

  • a remote reference to the object's activator, and
  • a unique identifier for the object.
An activation identifier for an object can be obtained by registering an object with the activation system. Registration is accomplished in a few ways (also noted above):

  • via the Activatable.register method, or
  • via the first or second Activatable constructor, which both registers and exports the object, or
  • via the first or second Activatable.exportObject method, this method both registers and exports the object.

package java.rmi.activation;

public class ActivationID implements java.io.Serializable
{
    public ActivationID(Activator activator);

    public Remote activate(boolean force)
        throws ActivationException, UnknownObjectException,
               java.rmi.RemoteException;

    public boolean equals(Object obj);

    public int hashCode();
}
The constructor for ActivationID takes a single argument, activator, that specifies a remote reference to the activator responsible for activating the object associated with this activation identifier. An instance of ActivationID is globally unique.

The activate method activates the object associated with the activation identifier. If the force parameter is true, the activator considers any cached reference for the remote object as stale, thus forcing the activator to contact the group when activating the object. If force is false, then returning the cached value is acceptable. If activation fails, ActivationException is thrown. If the object identifier is not known to the activator, then the method throws UnknownObjectException. If the remote call to the activator fails, then RemoteException is thrown.

The equals method implements content equality. It returns true if all fields are equivalent (either identical or equivalent according to each field's Object.equals semantics). If p1 and p2 are instances of the class ActivationID, the hashCode method will return the same value if p1.equals(p2) returns true.

7.3.3 The Activatable Class

The Activatable class provides support for remote objects that require persistent access over time and that can be activated by the system. The class Activatable is the main API that developers need to use to implement and manage activatable objects. Note that you must first run the activation system daemon, rmid, before objects can be registered and/or activated.

package java.rmi.activation;

public abstract class Activatable
    extends java.rmi.server.RemoteServer
{
    protected Activatable(String codebase,
                  java.rmi.MarshalledObject data,
                  boolean restart,
                  int port)
        throws ActivationException, java.rmi.RemoteException;

    protected Activatable(String codebase,
                  java.rmi.MarshalledObject data,
                  boolean restart, int port,
                  RMIClientSocketFactory csf,
                  RMIServerSocketFactory ssf)
        throws ActivationException, java.rmi.RemoteException;

    protected Activatable(ActivationID id, int port)
        throws java.rmi.RemoteException;

    protected Activatable(ActivationID id, int port,
                  RMIClientSocketFactory csf,
                  RMIServerSocketFactory ssf)
        throws java.rmi.RemoteException;

    protected ActivationID getID();

    public static Remote register(ActivationDesc desc)
        throws UnknownGroupException, ActivationException,
               java.rmi.RemoteException;

    public static boolean inactive(ActivationID id)
        throws UnknownObjectException, ActivationException,
               java.rmi.RemoteException;

    public static void unregister(ActivationID id)
        throws UnknownObjectException, ActivationException,
               java.rmi.RemoteException;

    public static ActivationID exportObject(Remote obj,
                        String codebase,
                        MarshalledObject data,
                        boolean restart,
                        int port)
        throws ActivationException, java.rmi.RemoteException;

    public static ActivationID exportObject(Remote obj,
                        String codebase,
                        MarshalledObject data,
                        boolean restart,
                        int port,
                        RMIClientSocketFactory csf,
                        RMIServerSocketFactory ssf)
        throws ActivationException, java.rmi.RemoteException;

    public static Remote exportObject(Remote obj,
                      ActivationID id,
                      int port)
        throws java.rmi.RemoteException;

    public static Remote exportObject(Remote obj,
                      ActivationID id,
                      int port,
                      RMIClientSocketFactory csf,
                      RMIServerSocketFactory ssf)
        throws java.rmi.RemoteException;

     public static boolean unexportObject(Remote obj, boolean force)
        throws java.rmi.NoSuchObjectException;
}
An implementation for an activatable remote object may or may not extend the class Activatable. A remote object implementation that does extend the Activatable class inherits the appropriate definitions of the hashCode and equals methods from the superclass java.rmi.server.RemoteObject. So, two remote object references that refer to the same Activatable remote object will be equivalent (the equals method will return true). Also, an instance of the class Activatable will be "equals" to the appropriate stub object for the instance (i.e., the Object.equals method will return true if called with the matching stub object for the implementation as an argument, and vice versa).

Activatable Class Methods

The first constructor for the Activatable class is used to register and export the object on a specified port (an anonymous port is chosen if port is zero). The object's URL path for downloading its class code is codebase, and its initialization data is data. If restart is true, the object will be restarted automatically when the activator is restarted and if the group crashes. If restart is false, the object will be activated on demand (via a remote method call to the object).

A concrete subclass of the Activatable class must call this constructor to register and export the object during initial construction. As a side-effect of activatable object construction, the remote object is both "registered" with the activation system and "exported" (on an anonymous port, if port is zero) to the RMI runtime so that it is available to accept incoming calls from clients.

The constructor throws ActivationException if registering the object with the activation system fails. RemoteException is thrown if exporting the object to the RMI runtime fails.

The second constructor is the same as the first Activatable constructor but allows the specification of the client and server socket factories used to communicate with this activatable object. See the section in about "RMI Socket Factories" for details.

The third constructor is used to activate and export the object (with the ActivationID, id) on a specified port. A concrete subclass of the Activatable class must call this constructor when the object itself is activated via its special "activation" constructor whose parameters must be:

  • the object's activation identifier (ActivationID), and
  • the object's initialization/bootstrap data (a MarshalledObject).
As a side-effect of construction, the remote object is "exported" to the RMI runtime (on the specified port) and is available to accept incoming calls from clients. The constructor throws RemoteException if exporting the object to the RMI runtime fails.

The fourth constructor is the same as the third constructor, but allows the specification of the client and server socket factories used to communicate with this activatable object.

The getID method returns the object's activation identifier. The method is protected so that only subclasses can obtain an object's identifier. The object's identifier is used to report the object as inactive or to unregister the object's activation descriptor.

The register method registers, with the activation system, an object descriptor, desc, for an activatable remote object so that it can be activated on demand. This method is used to register an activatable object without having to first create the object. This method returns the Remote stub for the activatable object so that it can be saved and called at a later time thus forcing the object to be created/activated for the first time. The method throws UnknownGroupException if the group identifier in desc is not registered with the activation system. ActivationException is thrown if the activation system is not running. Finally, RemoteException is thrown if the remote call to the activation system fails.

The inactive method is used to inform the system that the object with the corresponding activation id is currently inactive. If the object is currently known to be active, the object is unexported from the RMI runtime (only if there are no pending or executing calls) so the that it can no longer receive incoming calls. This call also informs this JVM's ActivationGroup that the object is inactive; the group, in turn, informs its ActivationMonitor. If the call completes successfully, subsequent activate requests to the activator will cause the object to reactivate. The inactive method returns true if the object was successfully unexported (meaning that it had no pending or executing calls at the time) and returns false if the object could not be unexported due to pending or in-progress calls. The method throws UnknownObjectException if the object is not known (it may already be inactive); an ActivationException is thrown if the group is not active; a RemoteException is thrown if the call informing the monitor fails. The operation may still succeed if the object is considered active but has already unexported itself.

The unregister method revokes previous registration for the activation descriptor associated with id. An object can no longer be activated via that id. If the object id is unknown to the activation system, an UnknownObjectException is thrown. If the activation system is not running, an ActivationException is thrown. If the remote call to the activation system fails, then a RemoteException is thrown.

The first exportObject method may be invoked explicitly by an "activatable" object that does not extend the Activatable class, in order to both

  • register the object's activation descriptor, desc, constructed from the supplied codebase and data, with the activation system so the object can be activated, and
  • export the remote object, obj, on a specific port. If the port is zero, then an anonymous port is chosen.
Once the object is exported, it can receive incoming RMI calls.

This exportObject method returns the activation identifier obtained from registering the descriptor, desc, with the activation system. If the activation group is not active in the JVM, then ActivationException is thrown. If the object registration or export fails, then RemoteException is thrown.

This method does not need to be called if obj extends Activatable, since the first Activatable constructor calls this method.

The second exportObject method is the same as the first except it allows the specification of client and server socket factories used to communicate with the activatable object.

The third exportObject method exports an "activatable" remote object (not necessarily of type Activatable) with the identifier, id, to the RMI runtime to make the object, obj, available to receive incoming calls. The object is exported on an anonymous port, if port is zero.

During activation, this exportObject method should be invoked explicitly by an "activatable" object, that does not extend the Activatable class. There is no need for objects that do extend the Activatable class to invoke this method directly; this method is called by the third constructor above (which a subclass should invoke from its special activation constructor).

This exportObject method returns the Remote stub for the activatable object. If the object export fails, then the method throws RemoteException.

The fourth exportObject method is the same as the third but allows the specification of the client and server socket factories used to communicate with this activatable object.

The unexportObject method makes the remote object, obj, unavailable for incoming calls. If the force parameter is true, the object is forcibly unexported even if there are pending calls to the remote object or the remote object still has calls in progress. If the force parameter is false, the object is only unexported if there are no pending or in progress calls to the object. If the object is successfully unexported, the RMI runtime removes the object from its internal tables. Removing the object from RMI use in this forcible manner may leave clients holding stale remote references to the remote object. This method throws java.rmi.NoSuchObjectException if the object was not previously exported to the RMI runtime.

Constructing an Activatable Remote Object

In order for an object to be activated, the "activatable" object implementation class (whether or not it extends the Activatable class) must define a special public constructor that takes two arguments, its activation identifier of type ActivationID, and its activation data, a java.rmi.MarshalledObject, supplied in the activation descriptor used during registration. When an activation group activates a remote object inside its JVM, it constructs the object via this special constructor (described in more detail below). The remote object implementation may use the activation data to initialize itself in a suitable manner. The remote object may also wish to retain its activation identifier, so that it can inform the activation group when it becomes inactive (via a call to the Activatable.inactive method).

The first and second constructor forms for Activatable are used to both register and export an activatable object on a specified port. This constructor should be used when initially constructing the object; the third form of the constructor is used when re-activating the object.

A concrete subclass of Activatable must call the first or second constructor form to register and export the object during initial construction. This constructor first creates an activation descriptor (ActivationDesc) with the object's class name, the object's supplied codebase and data, and whose activation group is the default group for the JVM. Next, the constructor registers this descriptor with the default ActivationSystem. Finally, the constructor exports the activatable object to the RMI runtime on the specific port (if port is zero, then an anonymous port is chosen) and reports the object as an activeObject to the local ActivationGroup. If an error occurs during registration or export, the constructor throws RemoteException. Note that the constructor also initializes its ActivationID (obtained via registration), so that subsequent calls to the protected method getID will return the object's activation identifier.

The third constructor form for Activatable is used to export the object on a specified port. A concrete subclass of Activatable must call the third constructor form when it is activated via the object's own "activation" constructor, which takes two arguments:

  • the object's ActivationID
  • the object's initialization data, a MarshalledObject
This constructor only exports the activatable object to the RMI runtime on the specific port (if port is 0, then an anonymous port is chosen). It does not inform the ActivationGroup that the object is active, since it is the ActivationGroup that is activating the object and knows it to be active already.

The following is an example of a remote object interface, Server, and an implementation, ServerImpl, that extends the Activatable class:

package examples;

public interface Server extends java.rmi.Remote {
    public void doImportantStuff()
        throws java.rmi.RemoteException;
}

public class ServerImpl extends Activatable implements Server
{
    // Constructor for initial construction, registration and export
    public ServerImpl(String codebase, MarshalledObject data)
        throws ActivationException, java.rmi.RemoteException
    {
        // register object with activation system, then
        // export on anonymous port
        super(codebase, data, false, 0);
    }

    // Constructor for activation and export; this constructor
    // is called by the ActivationInstantiator.newInstance
    // method during activation in order to construct the object.
    public ServerImpl(ActivationID id, MarshalledObject data)
        throws java.rmi.RemoteException
    {
        // call the superclass's constructor in order to
        // export the object to the RMI runtime.
        super(id, 0);
        // initialize object (using data, for example)
    }

    public void doImportantStuff() { ... }
}
An object is responsible for exporting itself. The constructors for Activatable take care of exporting the object to the RMI runtime with the live reference type of a UnicastRemoteObject, so the object implementation extending Activatable does not need to worry about the detail of exporting the object explicitly (other than invoking the appropriate superclasses constructor). If an object implementation does not extend the class Activatable, the object must export the object explicitly via a call to one of the Activatable.exportObject static methods.

In the following example, ServerImpl does not extend Activatable, but rather another class, so ServerImpl is responsible for exporting itself during initial construction and activation. The following class definition shows ServerImpl's initialization constructor and its special "activation" constructor and the appropriate call to export the object within each constructor:

package examples;

public class ServerImpl extends SomeClass implements Server
{
    // constructor for initial creation
    public ServerImpl(String codebase, MarshalledObject data)
        throws ActivationException, java.rmi.RemoteException
    {
        // register and export the object
        Activatable.exportObject(this, codebase, data, false, 0);
    }

    // constructor for activation
    public ServerImpl(ActivationID id, MarshalledObject data)
        throws java.rmi.RemoteException
    {
        // export the object
        Activatable.exportObject(this, id, 0);
    }

    public void doImportantStuff() { ... }
}

Registering an Activation Descriptor Without Creating the Object

To register an activatable remote object with the activation system without first creating the object, the programmer can simply register an activation descriptor (an instance of the class ActivationDesc) for the object. An activation descriptor contains all the necessary information so that the activation system can activate the object when needed. An activation descriptor for an instance of the class examples.ServerImpl can be registered in the following manner (exception handling elided):

Server server;
ActivationDesc desc;
String codebase = "http://zaphod/codebase/";

MarshalledObject data = new MarshalledObject("some data");
desc = new ActivationDesc( "examples.ServerImpl", codebase, data);
server = (Server)Activatable.register(desc);

The register call returns a Remote stub that is the stub for the examples.ServerImpl object and implements the same set of remote interfaces that examples.ServerImpl implements (i.e, the stub implements the remote interface Server). This stub object (above, cast and assigned to server) can be passed as a parameter in any method call expecting an object that implements the examples.Server remote interface.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


7 - Remote Object Activation

CONTENTS | PREV | NEXT Java Remote Method Invocation

Remote Object Activation

CHAPTER 7

Topics:

  • Overview
  • Activation Protocol
  • Implementation Model for an "Activatable" Remote Object
  • Activation Interfaces

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


7 - Remote Object Activation

CONTENTS | PREV | NEXT Java Remote Method Invocation

7.1 Overview

Distributed object systems are designed to support long-lived persistent objects. Given that these systems will be made up of many thousands (perhaps millions) of such objects, it would be unreasonable for object implementations to become active and remain active, taking up valuable system resources, for indefinite periods of time. In addition, clients need the ability to store persistent references to objects so that communication among objects can be re-established after a system crash, since typically a reference to a distributed object is valid only while the object is active.

Object activation is a mechanism for providing persistent references to objects and managing the execution of object implementations. In RMI, activation allows objects to begin execution on an as-needed basis. When an activatable remote object is accessed (via a method invocation) if that remote object is not currently executing, the system initiates the object's execution inside an appropriate JVM.

7.1.1 Terminology

An active object is a remote object that is instantiated and exported in a JVM on some system. A passive object is one that is not yet instantiated (or exported) in a JVM, but which can be brought into an active state. Transforming a passive object into an active object is a process known as activation. Activation requires that an object be associated with a JVM, which may entail loading the class for that object into a JVM and the object restoring its persistent state (if any).

In the RMI system, we use lazy activation. Lazy activation defers activating an object until a client's first use (i.e., the first method invocation).

7.1.2 Lazy Activation

Lazy activation of remote objects is implemented using a faulting remote reference (sometimes referred to as a fault block). A faulting remote reference to a remote object "faults in" the active object's reference upon the first method invocation to the object. Each faulting reference maintains both a persistent handle (an activation identifier) and a transient remote reference to the target remote object. The remote object's activation identifier contains enough information to engage a third party in activating the object. The transient reference is the actual "live" reference to the active remote object that can be used to contact the executing object.

In a faulting reference, if the live reference to a remote object is null, the target object is not known to be active. Upon method invocation, the faulting reference (for that object) engages in the activation protocol to obtain a "live" reference, which is a remote reference (such as a unicast remote reference) for the newly-activated object. Once the faulting reference obtains the live reference, the faulting reference forwards method invocations to the underlying remote reference which, in turn, forwards the method invocation to the remote object.

In more concrete terms, a remote object's stub contains a "faulting" remote reference type that contains both:

  • an activation identifier for a remote object, and
  • a "live" reference (possibly null) containing the "active" remote reference type of the remote object (for example, a remote reference type with unicast semantics).
Note - The RMI system preserves "at most once" semantics for remote calls. In other words, a call to an activatable or unicast remote object is sent at most once. Thus, if a call to a remote object fails (indicated by a RemoteException being thrown), the client can be guaranteed that the remote method executed no more than once (and perhaps not at all).

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


7 - Remote Object Activation

CONTENTS | PREV | NEXT Java Remote Method Invocation

7.4 Activation Interfaces

In the RMI activation protocol, there are two guarantees that the activator must make for the system to function properly:

  • like all system daemons, the activator should remain running while the machine is up, and
  • the activator must not reactivate remote objects that are already active.
The activator maintains a database of appropriate information for the groups and objects that it participates in activating.

7.4.1 The Activator Interface

The activator is one of the entities that participates during the activation process. As described earlier, a faulting reference (inside a stub) calls the activator's activate method to obtain a "live" reference to an activatable remote object. Upon receiving a request for activation, the activator looks up the activation descriptor for the activation identifier, id, determines the group in which the object should be activated, and invokes the newInstance method on the activation group's instantiator (the remote interface ActivationGroup is described below). The activator initiates the execution of activation groups as necessary. For example, if an activation group for a specific group descriptor is not already executing, the activator will spawn a child JVM for the activation group to establish the group in the new JVM.

The activator is responsible for monitoring and detecting when activation groups fail so that it can remove stale remote references from its internal tables.

package java.rmi.activation;

public interface Activator extends java.rmi.Remote
{
    java.rmi.MarshalledObject activate(ActivationID id,
                       boolean force)
        throws UnknownObjectException, ActivationException,
               java.rmi.RemoteException;
}
The activate method activates the object associated with the activation identifier, id. If the activator knows the object to be active already and the force parameter is false, the stub with a "live" reference is returned immediately to the caller; otherwise, if the activator does not know that the corresponding remote object is active or the force parameter is true, the activator uses the activation descriptor information (previously registered to obtain the id) to determine the group (JVM) in which the object should be activated. If an ActivationInstantiator corresponding to the object's group already exists, the activator invokes the activation instantiator's newInstance method, passing it the id and the object's activation descriptor.

If the activation instantiator (group) for the object's group descriptor does not yet exist, the activator starts a new incarnation of an ActivationInstantiator executing (by spawning a child process, for example). When the activator re-creates an ActivationInstantiator for a group, it must increment the group's incarnation number. Note that the incarnation number is zero-based. The activation system uses incarnation numbers to detect late ActivationSystem.activeGroup and ActivationMonitor.inactiveGroup calls. The activation system discards calls with an earlier incarnation number than the current number for the group.

Note - The activator must communicate both the activation group's identifier, descriptor, and incarnation number when it starts up a new activation group. The activator spawns an activation group in a separate JVM (as a separate or child process, for example), and therefore must pass information specifying the information necessary to create the group via the ActivationGroup.createGroup method. How the activator sends this information to the spawned process is unspecified, however, this information could be sent in the form of marshalled objects to the child process's standard input.
When the activator receives the activation group's call back (via the ActivationSystem.activeGroup method) specifying the activation group's reference and incarnation number, the activator can then invoke that activation instantiator's newInstance method to forward each pending activation request to the activation instantiator and return the result (a marshalled remote object reference, a stub) to each caller.

Note that the activator receives a MarshalledObject instead of a Remote object so that the activator does not need to load the code for that object, or participate in distributed garbage collection for that object. If the activator kept a strong reference to the remote object, the activator would then prevent the object from being garbage collected under the normal distributed garbage collection mechanism.

The activate method throws ActivationException if activation fails. Activation may fail for a variety of reasons: the class could not be found, the activation group could not be contacted, etc. The activate method throws UnknownObjectException if no activation descriptor for the activation identifier, id, has been previously registered with this activator. RemoteException is thrown if the remote call to the activator fails.

7.4.2 The ActivationSystem Interface

The ActivationSystem provides a means for registering groups and activatable objects to be activated within those groups. The ActivationSystem works closely with both the Activator, which activates objects registered via the ActivationSystem, and the ActivationMonitor, which obtains information about active and inactive objects and inactive groups.

package java.rmi.activation;

public interface ActivationSystem extends java.rmi.Remote
{
    public static final int SYSTEM_PORT = 1098;

    ActivationGroupID registerGroup(ActivationGroupDesc desc)
        throws ActivationException, java.rmi.RemoteException;

    ActivationMonitor activeGroup(ActivationGroupID id,
                      ActivationInstantiator group,
                      long incarnation)
        throws UnknownGroupException, ActivationException,
               java.rmi.RemoteException;

    void unregisterGroup(ActivationGroupID id)
        throws ActivationException, UnknownGroupException,
               java.rmi.RemoteException;

    ActivationID registerObject(ActivationDesc desc)
        throws ActivationException, UnknownGroupException,
               java.rmi.RemoteException;

    void unregisterObject(ActivationID id)
        throws ActivationException, UnknownObjectException,
               java.rmi.RemoteException;

    void shutdown() throws java.rmi.RemoteException;
}
Note - As a security measure, all of the above methods (registerGroup, activeGroup, unregisterGroup, registerObject, unregisterObject, and shutdown) will throw java.rmi.AccessException, a subclass of java.rmi.RemoteException, if called from a client that does not reside on the same host as the activation system.
The registerObject method is used to register an activation descriptor, desc, and obtain an activation identifier for an activatable remote object. The ActivationSystem creates an ActivationID (an activation identifier) for the object specified by the descriptor, desc, and records, in stable storage, the activation descriptor and its associated identifier for later use. When the Activator receives an activate request for a specific identifier, it looks up the activation descriptor (registered previously) for the specified identifier and uses that information to activate the object. If the group referred to in desc is not registered with this system, then the method throws UnknownGroupException. If registration fails (e.g., database update failure, etc), then the method throws ActivationException. If the remote call fails, then RemoteException is thrown.

The unregisterObject method removes the activation identifier, id, and associated descriptor previously registered with the ActivationSystem. After the call completes, the object can no longer be activated via the object's activation id. If the object id is unknown (not registered) the method throws UnknownObjectException. If the unregister operation fails (e.g., database update failure, etc.), then the method throws ActivationException. If the remote call fails, then RemoteException is thrown.

The registerGroup method registers the activation group specified by the group descriptor, desc, with the activation system and returns the ActivationGroupID assigned to that group. An activation group must be registered with the ActivationSystem before objects can be registered within that group. If group registration fails, the method throws ActivationException. If the remote call fails, then RemoteException is thrown.

The activeGroup method is a call back from the ActivationGroup (with the identifier, id), to inform the activation system that group is now active and is the ActivationInstantiator for that JVM. This call is made internally by the ActivationGroup.createGroup method to obtain an ActivationMonitor that the group uses to update the system regarding objects' and the group's status (i.e., that the group or objects within that group have become inactive). If the group is not registered, then the method throws UnknownGroupException. If the group is already active, then ActivationException is thrown. If the remote call to the activation system fails, then RemoteException is thrown.

The unregisterGroup method removes the activation group with identifier, id, from the activation system. An activation group makes this call back to inform the activator that the group should be destroyed. If this call completes successfully, objects can no longer be registered or activated within the group. All information of the group and its associated objects is removed from the system. The method throws UnknownGroupException if the group is not registered. If the remote call fails, then RemoteException is thrown. If the unregister fails, ActivationException is thrown (e.g., database update failure, etc.).

The shutdown method gracefully terminates (asynchronously) the activation system and all related activation processes (activator, monitors and groups). All groups spawned by the activation daemon will be destroyed and the activation daemon will exit. In order to shut down the activation system daemon, rmid, execute the command:

        rmid -stop [-port num]
This command will shut down the activation daemon on the specified port (if no port is specified, the daemon on the default port will be shut down).

7.4.3 The ActivationMonitor Class

An ActivationMonitor is specific to an ActivationGroup and is obtained when a group is reported via a call to ActivationSystem.activeGroup (this is done internally by the ActivationGroup.createGroup method). An activation group is responsible for informing its ActivationMonitor when:

a. its objects become active,

b. its objects become inactive, or

c. the group as a whole becomes inactive.

package java.rmi.activation;

public interface ActivationMonitor
    extends java.rmi.Remote
{

    public abstract void inactiveObject(ActivationID id)
        throws UnknownObjectException, RemoteException;

    public void activeObject(ActivationID id,
                 java.rmi.MarshalledObject mobj)
        throws UnknownObjectException, java.rmi.RemoteException;

    public void inactiveGroup(ActivationGroupID id,
                  long incarnation)
        throws UnknownGroupException, java.rmi.RemoteException;
}
An activation group calls its monitor's inactiveObject method when an object in its group becomes inactive (deactivates). An activation group discovers that an object (that it participated in activating) in its JVM is no longer active via a call to the activation group's inactiveObject method.

The inactiveObject call informs the ActivationMonitor that the remote object reference it holds for the object with the activation identifier, id, is no longer valid. The monitor considers the reference associated with id as a stale reference. Since the reference is considered stale, a subsequent activate call for the same activation identifier results in re-activating the remote object. If the object is not known to the ActivationMonitor, the method throws UnknownObjectException. If the remote call fails, then RemoteException is thrown.

The activeObject call informs the ActivationMonitor that the object associated with id is now active. The parameter obj is the marshalled representation of the object's stub. An ActivationGroup must inform its monitor if an object in its group becomes active by other means than being activated directly by the system (i.e., the object is registered and "activated" itself). If the object id is not previously registered, then the method throws UnknownObjectException. If the remote call fails, then RemoteException is thrown.

The inactiveGroup call informs the monitor that the group specified by id and incarnation is now inactive. The group will be re-created with a greater incarnation number upon a subsequent request to activate an object within the group. A group becomes inactive when all objects in the group report that they are inactive. If either the group id is not registered or the incarnation number is smaller than the current incarnation for the group, then the method throws UnknownGroupException. If the remote call fails, then RemoteException is thrown.

7.4.4 The ActivationInstantiator Class

The ActivationInstantiator is responsible for creating instances of activatable objects. A concrete subclass of ActivationGroup implements the newInstance method to handle creating objects within the group.

package java.rmi.activation;

public interface ActivationInstantiator
    extends java.rmi.Remote
{
    public MarshalledObject newInstance(ActivationID id,
                        ActivationDesc desc)
        throws ActivationException, java.rmi.RemoteException;

}
The activator calls an instantiator's newInstance method in order to re-create in that group an object with the activation identifier, id, and descriptor, desc. The instantiator is responsible for:

  • determining the class for the object using the descriptor's getClassName method,
  • loading the class from the codebase path obtained from the descriptor (using the getLocation method),
  • creating an instance of the class by invoking the special "activation" constructor of the object's class that takes two arguments: the object's ActivationID, and the MarshalledObject containing object-specific initialization data, and
  • returning a MarshalledObject containing the remote object it created.
An instantiator is also responsible for reporting when objects it creates or activates are no longer active, so that it can make the appropriate inactiveObject call to its ActivationMonitor (see the ActivationGroup class for more details).

If object activation fails, then the newInstance method throws ActivationException. If the remote call fails, then the method throws RemoteException.

7.4.5 The ActivationGroupDesc Class

An activation group descriptor (ActivationGroupDesc) contains the information necessary to create or re-create an activation group in which to activate objects in the same JVM.

Such a descriptor contains:

  • the group's class name (a class name of null indicates the default ActivationGroup implementation),
  • the group's codebase path (the location of the group's class), and
  • a "marshalled" object that can contain object-specific initialization data.
The group's class must be a concrete subclass of ActivationGroup. A subclass of ActivationGroup is created or re-created via the ActivationGroup.createGroup static method, which invokes a special constructor that takes two arguments:

  • the group's ActivationGroupID, and
  • the group's initialization data (in a java.rmi.MarshalledObject)

package java.rmi.activation;

public final class ActivationGroupDesc
    implements java.io.Serializable
{

    public ActivationGroupDesc(java.util.Properties props,
                   CommandEnvironment env);;

    public ActivationGroupDesc(String className,
                   String codebase,
                   java.rmi.MarshalledObject data,
                   java.util.Properties props,
                   CommandEnvironment env);

    public String getClassName();

    public String getLocation();

    public java.rmi.MarshalledObject getData();

    public CommandEnvironment getCommandEnvironment();

    public java.util.Properties getPropertiesOverrides();

}
The first constructor creates a group descriptor that uses system default for group implementation and code location. Properties specify Java application environment overrides (which will override system properties in the group implementation's JVM). The command environment can control the exact command/options used in starting the child JVM, or can be null to accept rmid's default. This constructor will create an ActivationGroupDesc with a null group class name, which indicates the system's default ActivationGroup implementation.

The second constructor is the same as the first, but allows the specification of Properties and CommandEnvironment.

The getClassName method returns the group's class name (possibly null). A null group class name indicates the system's default ActivationGroup implementation.

The getLocation method returns the codebase path from where the group's class can be loaded.

The getData method returns the group's initialization data in marshalled form.

The getCommandEnvironment method returns the command environment (possibly null).

The getPropertiesOverrides method returns the properties overrides (possibly null) for this descriptor.

7.4.6 The ActivationGroupDesc.CommandEnvironment Class

The CommandEnvironment class allows overriding default system properties and specifying implemention-defined options for an ActivationGroup.

public static class CommandEnvironment
    implements java.io.Serializable
{
    public CommandEnvironment(String cmdpath, String[] args);
    public boolean equals(java.lang.Object);
    public String[] getCommandOptions();
    public String getCommandPath();
    public int hashCode();

}
The constructor creates a CommandEnvironment with the given command, cmdpath, and additional command line options, args.

The equals implements content equality for command environment objects. The hashCode method is implemented appropriately so that a CommandEnvironment can be stored in a hash table if necessary.

The getCommandOptions method returns the environment object's command line options.

The getCommandPath method returns the environment object's command string.

7.4.7 The ActivationGroupID Class

The identifier for a registered activation group serves several purposes:

  • it identifies the group uniquely within the activation system, and
  • it contains a reference to the group's activation system so that the group can contact its activation system when necessary.
The ActivationGroupID is returned from the call to ActivationSystem.registerGroup and is used to identify the group within the activation system. This group identifier is passed as one of the arguments to the activation group's special constructor when an activation group is created or re-created.

package java.rmi.activation;

public class ActivationGroupID implements java.io.Serializable
{
    public ActivationGroupID(ActivationSystem system);

    public ActivationSystem getSystem();

    public boolean equals(Object obj);

    public int hashCode();
}
The ActivationGroupID constructor creates a unique group identifier whose ActivationSystem is system.

The getSystem method returns the activation system for the group.

The hashCode method returns a hashcode for the group's identifier. Two group identifiers that refer to the same remote group will have the same hash code.

The equals method compares two group identifiers for content equality. The method returns true if both of the following conditions are true: 1) the unique identifiers are equivalent (by content), and 2) the activation system specified in each refers to the same remote object.

7.4.8 The ActivationGroup Class

An ActivationGroup is responsible for creating new instances of activatable objects in its group, informing its ActivationMonitor when:

a. its objects become active,

b. its objects become inactive, or

c. the group as a whole becomes inactive.

An ActivationGroup is initially created in one of several ways:

  • as a side-effect of creating a "default" ActivationDesc for an object, or
  • by an explicit call to the ActivationGroup.createGroup method, or
  • as a side-effect of activating the first object in a group whose ActivationGroupDesc was only registered.
Only the activator can re-create an ActivationGroup. The activator spawns, as needed, a separate JVM (as a child process, for example) for each registered activation group and directs activation requests to the appropriate group. It is implementation specific how JVMs are spawned. An activation group is created via the ActivationGroup.createGroup static method. The createGroup method has two requirements on the group to be created: 1) the group must be a concrete subclass of ActivationGroup, and 2) the group must have a constructor that takes two arguments:

  • the group's ActivationGroupID, and
  • the group's initialization data (in a MarshalledObject)
When created, the default implementation of ActivationGroup will set the system properties to the system properties in force when the ActivationGroupDesc was created, and will set the security manager to the java.rmi.RMISecurityManager. If your application requires some specific properties to be set when objects are activated in the group, the application should set the properties before creating any ActivationDescs (before the default ActivationGroupDesc is created).

package java.rmi.activation;

public abstract class ActivationGroup
    extends UnicastRemoteObject
    implements ActivationInstantiator
{
    protected ActivationGroup(ActivationGroupID groupID)
        throws java.rmi.RemoteException;

    public abstract MarshalledObject newInstance(ActivationID id,
                             ActivationDesc desc)
        throws ActivationException, java.rmi.RemoteException;

    public abstract boolean inactiveObject(ActivationID id)
        throws ActivationException, UnknownObjectException,
               java.rmi.RemoteException;

    public static ActivationGroup createGroup(ActivationGroupID id,
                              ActivationGroupDesc desc,
                          long incarnation)
        throws ActivationException;

    public static ActivationGroupID currentGroupID();

    public static void setSystem(ActivationSystem system)
        throws ActivationException;

    public static ActivationSystem getSystem()
        throws ActivationException;

    protected void activeObject(ActivationID id,
                    java.rmi.MarshalledObject mobj)
        throws ActivationException, UnknownObjectException,
               java.rmi.RemoteException;

    protected void inactiveGroup()
        throws UnknownGroupException, java.rmi.RemoteException;

}
The activator calls an activation group's newInstance method in order to activate an object with the activation descriptor, desc. The activation group is responsible for:

  • determining the class for the object using the descriptor's getClassName method,
  • loading the class from the URL path obtained from the descriptor (using the getLocation method),
  • creating an instance of the class by invoking the special constructor of the object's class that takes two arguments: the object's ActivationID, and a MarshalledObject containing the object's initialization data, and
  • returning a serialized version of the remote object it just created to the activator.
The method throws ActivationException if the instance for the given descriptor could not be created.

The group's inactiveObject method is called indirectly via a call to the Activatable.inactive method. A remote object implementation must call Activatable's inactive method when that object deactivates (the object deems that it is no longer active). If the object does not call Activatable.inactive when it deactivates, the object will never be garbage collected since the group keeps strong references to the objects it creates.

The group's inactiveObject method unexports the remote object, associated with id (only if there are no pending or executing calls to the remote object) from the RMI runtime so that the object can no longer receive incoming RMI calls. If the object currently has pending or executing calls, inactiveObject returns false and no action is taken.

If the unexportObject operation was successful (meaning that the object has no pending or executing calls), the group informs its ActivationMonitor (via the monitor's inactiveObject method) that the remote object is not currently active so that the remote object will be reactivated by the activator upon a subsequent activation request. If the operation was successful, inactiveObject returns true. The operation may still succeed if the object is considered active by the ActivationGroup but has already been unexported.

The inactiveObject method throws an UnknownObjectException if the activation group has no knowledge of this object (e.g., the object was previously reported as inactive, or the object was never activated via the activation group). If the inactive operation fails (e.g., if the remote call to the activator or activation group fails), RemoteException is thrown.

The createGroup method creates and sets the activation group for the current JVM. The activation group can only be set if it is not currently set. An activation group is set using the createGroup method when the Activator initiates the re-creation of an activation group in order to carry out incoming activate requests. A group must first register a group descriptor with the ActivationSystem before it can be created via this method (passing it the ActivationID obtained from previous registration).

The group specified by the ActivationGroupDesc, desc, must be a concrete subclass of ActivationGroup and have a public constructor that takes two arguments; the ActivationGroupID for the group and a MarshalledObject containing the group's initialization data (obtained from its ActivationGroupDesc). If the ActivationGroupDesc.getClassName method returns null, the system's default group implementation is used. Note: if your application creates its own custom activation group, the group must set a security manager in the constructor, or objects cannot be activated in the group.

After the group is created, the ActivationSystem is informed that the group is active by calling the activeGroup method, which returns the ActivationMonitor for the group. The application need not call activeGroup independently since that callback is taken care of by the createGroup method.

Once a group is created, subsequent calls to the currentGroupID method will return the identifier for this group until the group becomes inactive, at which point the currentGroupID method will return null.

The parameter incarnation indicates the current group incarnation, i.e., the number of times the group has been activated. The incarnation number is used as a parameter to the activeGroup method, once the group has been successfully created. The incarnation number is zero-based. If the group already exists, or if an error occurs during group creation, the createGroup method throws ActivationException.

The setSystem method sets the ActivationSystem, system, for the JVM. The activation system can only be set if no group is currently active. If the activation system is not set via an explicit call to setSystem, then the getSystem method will attempt to obtain a reference to the ActivationSystem by looking up the name java.rmi.activation.ActivationSystem in the Activator's registry. By default, the port number used to look up the activation system is defined by ActivationSystem.SYSTEM_PORT. This port can be overridden by setting the property java.rmi.activation.port. If the activation system is already set when setSystem is called, the method throws ActivationException.

The getSystem method returns the activation system for the JVM. The activation system may be set by the setSystem method (described above).

The activeObject method is a protected method used by subclasses to make the activeObject call back to the group's monitor to inform the monitor that the remote object with the specified activation id and whose stub is contained in mobj is now active. The call is simply forwarded to the group's ActivationMonitor.

The inactiveGroup method is a protected method used by subclasses to inform the group's monitor that the group has become inactive. A subclass makes this call when each object the group participated in activating in the JVM has become inactive.

7.4.9 The MarshalledObject Class

A MarshalledObject is a container for an object that allows that object to be passed as a parameter in an RMI call, but postpones deserializing the object at the receiver until the application explicitly requests the object (via a call to the container object). The Serializable object contained in the MarshalledObject is serialized and deserialized (when requested) with the same semantics as parameters passed in RMI calls, which means that any remote object in the MarshalledObject is represented by a serialized instance of its stub. The object contained by the MarshalledObject may be a remote object, a non-remote object, or an entire graph of remote and non-remote objects.

When an object is placed inside the MarshalledObject wrapper, the serialized form of the object is annotated with the codebase URL (where the class can be loaded); likewise, when the contained object is retrieved from its MarshalledObject wrapper, if the code for the object is not available locally, the URL (annotated during serialization) is used to locate and load the bytecodes for the object's class.

package java.rmi;

public final class MarshalledObject implements java.io.Serializable
{
    public MarshalledObject(Object obj)
        throws java.io.IOException;

    public Object get()
        throws java.io.IOException, ClassNotFoundException;

    public int hashCode();

    public boolean equals();
}
MarshalledObject's constructor takes a serializable object, obj, as its single argument and holds the marshalled representation of the object in a byte stream. The marshalled representation of the object preserves the semantics of objects that are passed in RMI calls:

  • each class in the stream is annotated with its codebase URL so that when the object is reconstructed (by a call to the get method), the bytecodes for each class can be located and loaded, and
  • remote objects are replaced with their proxy stubs.
When an instance of the class MarshalledObject is written to a java.io.ObjectOutputStream, the contained object's marshalled form (created during construction) is written to the stream; thus, only the byte stream is serialized.

When a MarshalledObject is read from a java.io.ObjectInputStream, the contained object is not deserialized into a concrete object; the object remains in its marshalled representation until the marshalled object's get method is called.

The get method always reconstructs a new copy of the contained object from its marshalled form. The internal representation is deserialized with the semantics used for unmarshalling parameters for RMI calls. So, the deserialization of the object's representation loads class code (if not available locally) using the URL annotation embedded in the serialized stream for the object.

The hashCode of the marshalled representation of the object is the same as the object passed to the constructor. The equals method will return true if the marshalled representation of the objects being compared are equivalent. The comparison that equals uses ignores a class's codebase annotation, meaning that two objects are equivalent if they have the same serialized representation except for the codebase of each class in the serialized representation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


7 - Remote Object Activation

CONTENTS | PREV | NEXT Java Remote Method Invocation

7.2 Activation Protocol

During a remote method invocation, if the "live" reference for a target object is unknown, the faulting reference engages in the activation protocol. The activation protocol involves several entities: the faulting reference, the activator, an activation group, and the remote object being activated.

The activator (usually one per host) is the entity which supervises activation by being both:

  • a database of information that maps activation identifiers to the information necessary to activate an object (the object's class, the location--a URL path--from which the class can be loaded, specific data the object may need to bootstrap, etc.), and
  • a manager of Java virtual machines, that starts up JVMs (when necessary) and forwards requests for object activation (along with the necessary information) to the correct activation group inside a remote JVM.
Note that the activator keeps the current mapping of activation identifiers to active objects as a cache, so that the group does not need to be consulted on each activation request.

An activation group (one per JVM) is the entity which receives a request to activate an object in the JVM and returns the activated object back to the activator.

The activation protocol is as follows. A faulting reference uses an activation identifier and calls the activator (an internal RMI interface) to activate the object associated with the identifier. The activator looks up the object's activation descriptor (registered previously). The object's descriptor contains:

  • the object's group identifier, specifying the JVM in which it is activated,
  • the object's class name,
  • a URL path from which to load the object's class code, and
  • object-specific initialization data in marshalled form (initialization data might be the name of a file containing the object's persistent state, for example).
If the activation group in which this object should reside exists, the activator forwards the activation request to that group. If the activation group does not exist, the activator initiates a JVM executing an activation group and then forwards the activation request to that group.

The activation group loads the class for the object and instantiates the object using a special constructor that takes several arguments, including the activation descriptor registered previously.

When the object is finished activating, the activation group passes back a marshalled object reference to the activator that then records the activation identifier and active reference pairing and returns the active (live) reference to the faulting reference. The faulting reference (inside the stub) then forwards method invocations via the live reference directly to the remote object.

Note - In Java 2 SDK, Standard Edition, v 1.2, RMI provides an implementation of the activation system interfaces. In order to use activation, you must first run the activation system daemon rmid.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


8 - Stub/Skeleton Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

Stub/Skeleton Interfaces

CHAPTER 8
This section contains the interfaces and classes used by the stubs and skeletons generated by the rmic stub compiler.

Topics:

  • The RemoteStub Class
  • The RemoteCall Interface
  • The RemoteRef Interface
  • The ServerRef Interface
  • The Skeleton Interface
  • The Operation Class

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


8 - Stub/Skeleton Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

8.1 The RemoteStub Class

The java.rmi.server.RemoteStub class is the common superclass for stubs of remote objects. Stub objects are surrogates that support exactly the same set of remote interfaces defined by the actual implementation of a remote object.

package java.rmi.server;

public abstract class RemoteStub extends java.rmi.RemoteObject {
    protected RemoteStub() {...}
    protected RemoteStub(RemoteRef ref) {...}

    protected static void setRef(RemoteStub stub, RemoteRef ref) {...}
}
The first constructor of RemoteStub creates a stub with a null remote reference. The second constructor creates a stub with the given remote reference, ref.

The setRef method is deprecated (and unsupported) as of the Java 2 SDK, Standard Edition, v1.2.

8.1.1 Type Equivalency of Remote Objects with a Stub Class

Clients interact with stub (surrogate) objects that have exactly the same set of remote interfaces defined by the remote object's class; the stub class does not include the non-remote portions of the class hierarchy that constitutes the object's type graph. This is because the stub class is generated from the most refined implementation class that implements one or more remote interfaces. For example, if C extends B and B extends A, but only B implements a remote interface, then a stub is generated from B, not C.

Because the stub implements the same set of remote interfaces as the remote object's class, the stub has the same type as the remote portions of the server object's type graph. A client, therefore, can make use of the built-in Java programming language operations to check a remote object's type and to cast from one remote interface to another.

Stubs are generated using the rmic compiler.

8.1.2 The Semantics of Object Methods Declared final

The following methods are declared final in the java.lang.Object class and therefore cannot be overridden by any implementation:

  • getClass
  • notify
  • notifyAll
  • wait
The default implementation for getClass is appropriate for all objects written in the Java programming language, local or remote; so, the method needs no special implementation for remote objects. When used on a remote stub, the getClass method reports the exact type of the stub object, generated by rmic. Note that stub type reflects only the remote interfaces implemented by the remote object, not that object's local interfaces.

The wait and notify methods of java.lang.Object deal with waiting and notification in the context of the Java programming language's threading model. While use of these methods for remote stubs does not break the threading model, these methods do not have the same semantics as they do for local objects written in the Java programming language. Specifically, these methods operate on the client's local reference to the remote object (the stub), not the actual object at the remote site.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


8 - Stub/Skeleton Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

8.3 The RemoteRef Interface

The interface RemoteRef represents the handle for a remote object. Each stub contains an instance of RemoteRef that contains the concrete representation of a reference. This remote reference is used to carry out remote calls on the remote object for which it is a reference.

package java.rmi.server;

public interface RemoteRef extends java.io.Externalizable {
    Object invoke(Remote obj,
                   java.lang.reflect.Method method,
                   Object[] params,
                   long opnum)
        throws Exception;

    RemoteCall newCall(RemoteObject obj, Operation[] op, int opnum,
                   long hash) throws RemoteException;
    void invoke(RemoteCall call) throws Exception;
    void done(RemoteCall call) throws RemoteException;
    String getRefClass(java.io.ObjectOutput out);
    int remoteHashCode();
    boolean remoteEquals(RemoteRef obj);
    String remoteToString();
}
The invoke(Remote,Method,Object[],long) method delegates method invocation to the stub's (obj) remote reference and allows the reference to take care of setting up the connection to the remote host, marshaling some representation for the method and parameters, params, then communicating the method invocation to the remote host. This method either returns the result of the method invocation on the remote object which resides on the remote host or throws a RemoteException if the call failed or an application-level exception if the remote invocation throws an exception. Note that the operation number, opnum, represents a hash of the method signature and may be used to encode the method for transmission.

The method hash to be used for the opnum parameter is a 64-bit (long) integer computed from the first two 32-bit values of the message digest of a particular byte stream using the National Institute of Standards and Technology (NIST) Secure Hash Algorithm (SHA-1). This byte stream contains a string as if it was written using the java.io.DataOutput.writeUTF method, consisting of the remote method's name followed by its method descriptor (see section 4.3.3 of The Java Virtual Machine Specification (JVMS) for a description of method descriptors).

For example, if a method of a remote interface has the following name and signature:

    void myRemoteMethod(int count, Object obj, boolean flag)
the string containing the remote method's name and descriptor would be the following:

    myRemoteMethod(ILjava/lang/Object;Z)V
The 64-bit hash value is the little-endian composition of an eight byte sequence where the first four bytes are the first 32-bit value of the message digest in big-endian byte order and the last four bytes are the second 32-bit value of the message digest in big-endian byte order. For example, if the first two 32-bit values of the message digest are 0xB0B1B2B3 and 0xB4B5B6B7, then the hash value would be 0xB7B6B5B4B3B2B1B0.
Note - The methods newCall(RemoteObject,Operation[],int,long), invoke(RemoteCall), and done(RemoteCall) are deprecated as of the Java 2 SDK, Standard Edition, v1.2. The stubs generated by rmic using the 1.2 stub protocol version do not use these methods any longer. The sequence of calls consisting of newCall, invoke, and done have been replaced by a new invoke method that takes a Method object as one of its parameters.
The method newCall creates an appropriate call object for a new remote method invocation on the remote object obj. The operation array, op, contains the available operations on the remote object. The operation number, opnum, is an index into the operation array which specifies the particular operation for this remote call. The interface hash is a 64-bit value used to enforce compatibility between a stub and skeleton using the v1.1 stub protocol. The interface hash is computed from the first two 32-bit values of the message digest of a particular byte stream using SHA-1. This byte stream contains data as if it was written using the writeInt and writeUTF methods of the interface java.io.DataOutput, consisting of the following items:

  • (int) stub version number, always 1
  • for each remote method, in order of operation number:
    • (UTF-8) remote method name
    • (UTF-8) remote method descriptor (see section 4.3.3 of JVMS)
    • for each declared exception, in lexicographic order of binary name:
      • (UTF-8) the name of the exception class

    The interface hash value is composed from the message digest in the same manner as described above for the method hash used in the invoke method.

    The method invoke(RemoteCall) executes the remote call. invoke will raise any "user" exceptions which should pass through and not be caught by the stub. If any exception is raised during the remote invocation, invoke should take care of cleaning up the connection before raising the "user exception" or RemoteException.

    The method done allows the remote reference to clean up (or reuse) the connection. done should only be called if the invoke call returns successfully (non-exceptionally) to the stub.

    The method getRefClass returns the nonpackage-qualified class name of the reference type to be serialized onto the stream out.

    The method remoteHashCode returns a hashcode for a remote object. Two remote object stubs that refer to the same remote object will have the same hash code (in order to support remote objects as keys in hashtables). A RemoteObject forwards a call to its hashCode method to the remoteHashCode method of the remote reference.

    The method remoteEquals compares two remote objects for equality. Two remote objects are equal if they refer to the same remote object. For example, two stubs are equal if they refer to the same remote object. A RemoteObject forwards a call to its equals method to the remoteEquals method of the remote reference.

    The method remoteToString returns a String that represents the reference of this remote object.

    • CONTENTS | PREV | NEXT
    Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


8 - Stub/Skeleton Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

8.4 The ServerRef Interface

The interface ServerRef represents the server-side handle for a remote object implementation.

package java.rmi.server;

public interface ServerRef extends RemoteRef {
    RemoteStub exportObject(java.rmi.Remote obj, Object data)
        throws java.rmi.RemoteException;
    String getClientHost() throws ServerNotActiveException;
}
The method exportObject finds or creates a client stub object for the supplied Remote object implementation obj.The parameter data contains information necessary to export the object (such as port number).

The method getClientHost returns the host name of the current client. When called from a thread actively handling a remote method invocation, the host name of the client invoking the call is returned. If a remote method call is not currently being service, then ServerNotActiveException is called.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


8 - Stub/Skeleton Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

8.2 The RemoteCall Interface

The interface RemoteCall is an abstraction used by the stubs and skeletons of remote objects to carry out a call to a remote object.

Note - The RemoteCall interface is deprecated as of the Java 2 SDK, Standard Edition, v1.2. The 1.2 stub protocol does not make use of this interface anymore. As of the Java 2 SDK, Standard Edition, v1.2, stubs now use the new invoke method which does not require RemoteCall as a parameter.
package java.rmi.server;

import java.io.*;

public interface RemoteCall {
    ObjectOutput getOutputStream() throws IOException;
    void releaseOutputStream() throws IOException;
    ObjectInput getInputStream() throws IOException;
    void releaseInputStream() throws IOException;
    ObjectOutput getResultStream(boolean success)
        throws IOException, StreamCorruptedException;
    void executeCall() throws Exception;
    void done() throws IOException;
}
The method getOutputStream returns the output stream into which either the stub marshals arguments or the skeleton marshals results.

The method releaseOutputStream releases the output stream; in some transports this will release the stream.

The method getInputStream returns the InputStream from which the stub unmarshals results or the skeleton unmarshals parameters.

The method releaseInputStream releases the input stream. This will allow some transports to release the input side of a connection early.

The method getResultStream returns an output stream (after writing out header information relating to the success of the call). Obtaining a result stream should only succeed once per remote call. If success is true, then the result to be marshaled is a normal return; otherwise the result is an exception. StreamCorruptedException is thrown if the result stream has already been obtained for this remote call.

The method executeCall does whatever it takes to execute the call.

The method done allows cleanup after the remote call has completed.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


8 - Stub/Skeleton Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

8.5 The Skeleton Interface

The interface Skeleton is used solely by the implementation of skeletons generated by the rmic compiler. A skeleton for a remote object is a server-side entity that dispatches calls to the actual remote object implementation.

Note - The Skeleton interface was deprecated as of the Java 2 SDK, Standard Edition, v 1.2. Every 1.1 (and version 1.1 compatible skeletons generated in 1.2 using rmic -vcompat, the default) skeleton class generated by the rmic stub compiler implements this interface. Skeletons are no longer required for remote method call dispatch as of Java 2 SDK, Standard Edition, v1.2-compatible versions. To generate stubs that are compatible with 1.2 or later versions, use the command rmic with the option -v 1.2.
package java.rmi.server;

public interface Skeleton {
    void dispatch(Remote obj, RemoteCall call, int opnum, long hash)
        throws Exception;
    Operation[] getOperations();
}
The dispatch method unmarshals any arguments from the input stream obtained from the call object, invokes the method (indicated by the operation number opnum) on the actual remote object implementation obj, and marshals the return value or throws an exception if one occurs during the invocation.

The getOperations method returns an array containing the operation descriptors for the remote object's methods.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


8 - Stub/Skeleton Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

8.6 The Operation Class

The class Operation holds a description of a method in the Java programming language for a remote object.

Note - The Operation interface is deprecated as of the Java 2 SDK, Standard Edition, v1.2. The 1.2 stub protocol no longer uses the old RemoteRef.invoke method which takes an Operation as one of its arguments. As of the Java 2 SDK, Standard Edition, v1.2, stubs now use the new invoke method which does not require Operation as a parameter.
package java.rmi.server;

public class Operation {
    public Operation(String op) {...}
    public String getOperation() {...}
    public String toString() {...}
}
An Operation object is typically constructed with the method signature.

The method getOperation returns the contents of the operation descriptor (the value with which it was initialized).

The method toString also returns the string representation of the operation descriptor (typically the method signature).

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


9 - Garbage Collector Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

9.5 The VMID Class

See the VMID API documentation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


9 - Garbage Collector Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

9.3 The ObjID Class

See the ObjID API documentation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


9 - Garbage Collector Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

9.4 The UID Class

See the UID API documentation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


9 - Garbage Collector Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

9.2 The Lease Class

See the Lease API documentation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


9 - Garbage Collector Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

9.1 The DGC Interface

See the DGC API documentation.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


9 - Garbage Collector Interfaces

CONTENTS | PREV | NEXT Java Remote Method Invocation

Garbage Collector Interfaces

CHAPTER 9
The interfaces and classes in this chapter are used by the distributed garbage collector (DGC) for RMI.

Topics:

  • The DGC Interface
  • The Lease Class
  • The ObjID Class
  • The UID Class
  • The VMID Class

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


10 - RMI Wire Protocol

CONTENTS | PREV | NEXT Java Remote Method Invocation

10.1 Overview

The RMI protocol makes use of two other protocols for its on-the-wire format: Java Object Serialization and HTTP. The Object Serialization protocol is used to marshal call and return data. The HTTP protocol is used to "POST" a remote method invocation and obtain return data when circumstances warrant. Each protocol is documented as a separate grammar. Nonterminal symbols in production rules may refer to rules governed by another protocol (either Object Serialization or HTTP). When a protocol boundary is crossed, subsequent productions use that embedded protocol.

Notes about Grammar Notation

  • We use a similar notation to that used in The Java Language Specification (see section 2.3 of the JLS).
  • Control codes in the stream are represented by literal values expressed in hexadecimal.
  • Some nonterminal symbols in the grammar represent application specific values supplied in a method invocation. The definition of such a nonterminal consists of its Java programming language type. A table mapping each of these nonterminals to its respective type follows the grammar.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


10 - RMI Wire Protocol

CONTENTS | PREV | NEXT Java Remote Method Invocation

10.3 RMI's Use of Object Serialization

Call and return data in RMI calls are formatted using the Java Object Serialization protocol. Each method invocation's CallData is written to a Java object output stream that contains the ObjectIdentifier (the target of the call), an Operation (a number representing the method to be invoked), a Hash (a number that verifies that client stub and remote object skeleton use the same stub protocol), followed by a list of zero or more Arguments for the call.

In the JDK1.1 stub protocol the Operation represents the method number as assigned by rmic, and the Hash was the stub/skeleton hash which is the stub's interface hash. As of the Java 2 stub protocol (Java 2 stubs are generated using the -v1.2 option with rmic), Operation has the value -1 and the Hash is a hash representing the method to call. The hash is described in the section "The RemoteRef Interface".

CallData:

ObjectIdentifier Operation Hash Argumentsopt

ObjectIdentifier:

ObjectNumber UniqueIdentifier

UniqueIdentifier:

Number Time Count

Arguments:

Value

Arguments Value

Value:

Object

Primitive

A ReturnValue of an RMI call consists of a return code to indicate either a normal or exceptional return, a UniqueIdentifier to tag the return value (used to send a DGCAck if necessary) followed by the return result: either the Value returned or the Exception thrown.

ReturnValue:

0x01 UniqueIdentifier Valueopt

0x02 UniqueIdentifier Exception

Note - ObjectIdentifier, UniqueIdentifier, and EndpointIdentifier are not written out using default serialization, but each uses its own special write method (this is not the writeObject method used by object serialization); the write method for each type of identifier adds its component data consecutively to the output stream.

10.3.1 Class Annotation and Class Loading

RMI overrides the annotateClass and resolveClass methods of ObjectOutputStream and ObjectInputStream respectively. Each class is annotated with the codebase URL (the location from which the class can be loaded). In the annotateClass method, the classloader that loaded the class is queried for its codebase URL. If the classloader is non-null and the classloader has a non-null codebase, then the codebase is written to the stream using the ObjectOutputStream.writeObject method; otherwise a null is written to the stream using the writeObject method. Note: as an optimization, classes in the "java" package are not annotated, since they are always available to the receiver.

The class annotation is resolved during deserialization using the ObjectInputStream.resolveClass method. The resolveClass method first reads the annotation via the ObjectInputStream.readObject method. If the annotation, a codebase URL, is non-null, then it obtains the classloader for that URL and attempts to load the class. The class is loaded by using a java.net.URLConnection to fetch the class bytes (the same mechanism used by a web browser's applet classloader).

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


10 - RMI Wire Protocol

CONTENTS | PREV | NEXT Java Remote Method Invocation

10.6 RMI's Multiplexing Protocol

The purpose of multiplexing is to provide a model where two endpoints can each open multiple full duplex connections to the other endpoint in an environment where only one of the endpoints is able to open such a bidirectional connection using some other facility (e.g., a TCP connection). RMI use this simple multiplexing protocol to allow a client to connect to an RMI server object in some situations where that is otherwise not possible. For example, some security managers for applet environments disallow the creation of server sockets to listen for incoming connections, thereby preventing such applets to export RMI objects and service remote calls from direct socket connections. If the applet can open a normal socket connection to its codebase host, however, then it can use the multiplexing protocol over that connection to allow the codebase host to invoke methods on RMI objects exported by the applet. This section describes how the format and rules of the multiplexing protocol.

10.6.1 Definitions

This sections defines some terms as they are used in the rest of the description of the protocol.

An endpoint is one of the two users of a connection using the multiplexing protocol.

The multiplexing protocol must layer on top of one existing bidirectional, reliable byte stream, presumably initiated by one of the endpoints to the other. In current RMI usage, this is always a TCP connection, made with a java.net.Socket object. This connection will be referred to as the concrete connection.

The multiplexing protocol facilitates the use of virtual connections, which are themselves bidirectional, reliable byte streams, representing a particular session between two endpoints. The set of virtual connections between two endpoints over a single concrete connection comprises a multiplexed connection. Using the multiplexing protocol, virtual connections can be opened and closed by either endpoint. The state of an virtual connection with respect to a given endpoint is defined by the elements of the multiplexing protocol that are sent and received over the concrete connection. Such state involves if the connection is open or closed, the actual data that has been transmitted across, and the related flow control mechanisms. If not otherwise qualified, the term connection used in the remainder of this section means virtual connection.

A virtual connections within a given multiplexed connection is identified by a 16 bit integer, known as the connection identifier. Thus, there exist 65,536 possible virtual connections in one multiplexed connection. The implementation may limit the number of these virtual connections that may be used simultaneously.

10.6.2 Connection State and Flow Control

Connections are manipulated using the various operations defined by the multiplexing protocol. The following are the names of the operations defined by the protocol: OPEN, CLOSE, CLOSEACK, REQUEST, and TRANSMIT. The exact format and rules for all the operations are detailed in Section 10.6.3, "Protocol Format."

The OPEN, CLOSE, and CLOSEACK operations control connections becoming opened and closed, while the REQUEST and TRANSMIT operations are used to transmit data across an open connection within the constraints of the flow control mechanism.

Connection States

A virtual connection is open with respect to a particular endpoint if the endpoint has sent an OPEN operation for that connection, or it has received an OPEN operation for that connection (and it had not been subsequently closed). The various protocol operations are described below.

A virtual connection is pending close with respect to a particular endpoint if the endpoint has sent a CLOSE operation for that connection, but it has not yet received a subsequent CLOSE or CLOSEACK operation for that connection.

A virtual connection is closed with respect to a particular endpoint if it has never been opened, or if it has received a CLOSE or a CLOSEACK operation for that connection (and it has not been subsequently opened).

Flow Control

The multiplexing protocol uses a simple packeting flow control mechanism to allow multiple virtual connections to exist in parallel over the same concrete connection. The high level requirement of the flow control mechanism is that the state of all virtual connections is independent; the state of one connection may not affect the behavior of others. For example, if the data buffers handling data coming in from one connection become full, this cannot prevent the transmission and processing of data for any other connection. This is necessary if the continuation of one connection is dependent on the completion of the use of another connection, such as would happen with recursive RMI calls. Therefore, the practical implication is that the implementation must always be able to consume and process all of the multiplexing protocol data ready for input on the concrete connection (assuming that it conforms to this specification).

Each endpoint has two state values associated with each connection: how many bytes of data the endpoint has requested but not received (input request count) and how many bytes the other endpoint has requested but have not been supplied by this endpoint (output request count).

An endpoint's output request count is increased when it receives a REQUEST operation from the other endpoint, and it is decreased when it sends a TRANSMIT operation. An endpoint's input request count is increased when it sends a REQUEST operation, and it is decreased when it receives a TRANSMIT operation. It is a protocol violation if either of these values becomes negative.

It is a protocol violation for an endpoint to send a REQUEST operation that would increase its input request count to more bytes that it can currently handle without blocking. It should, however, make sure that its input request count is greater than zero if the user of the connection is waiting to read data.

It is a protocol violation for an endpoint to send a TRANSMIT operation containing more bytes that its output request count. It may buffer outgoing data until the user of the connection requests that data written to the connection be explicitly flushed. If data must be sent over the connection, however, by either an explicit flush or because the implementation's output buffers are full, then the user of the connection may be blocked until sufficient TRANSMIT operations can proceed.

Beyond the rules outlined above, implementations are free to send REQUEST and TRANSMIT operations as deemed appropriate. For example, an endpoint may request more data for a connection even if its input buffer is not empty.

10.6.3 Protocol Format

The byte stream format of the multiplexing protocol consists of a contiguous series of variable length records. The first byte of the record is an operation code that identifies the operation of the record and determines the format of the rest of its content. The following legal operation codes are defined:

value

name

0xE1

OPEN

0xE2

CLOSE

0xE3

CLOSEACK

0xE4

REQUEST

0xE5

TRANSMIT

It is a protocol violation if the first byte of a record is not one of the defined operation codes. The following sections describe the format of the records for each operation code.

OPEN operation

This is the format for records of the OPEN operation:

size (bytes)

name

description

1

opcode

operation code (OPEN)

2

ID

connection identifier

An endpoint sends an OPEN operation to open the indicated connection. It is a protocol violation if ID refers to a connection that is currently open or pending close with respect to the sending endpoint. After the connection is opened, both input and request count states for the connection are zero for both endpoints.

Receipt of an OPEN operation indicates that the other endpoint is opening the indicated connection. After the connection is opened, both input and output request count states for the connection are zero for both endpoints.

To prevent identifier collisions between the two endpoints, the space of valid connection identifiers is divided in half, depending on the value of the most significant bit. Each endpoint is only allowed to open connections with a particular value for the high bit. The endpoint that initiated the concrete connection must only open connections with the high bit set in the identifier and the other endpoint must only open connections with a zero in the high bit. For example, if an RMI applet that cannot create a server socket initiates a multiplexed connection to its codebase host, the applet may open virtual connections in the identifier range 0x8000-7FFF, and the server may open virtual connection in the identifier range 0-0x7FFF.

CLOSE operation

This is the format for records of the CLOSE operation:

size (bytes)

name

description

1

opcode

operation code (OPEN)

2

ID

connection identifier

An endpoint sends a CLOSE operation to close the indicated connection. It is a protocol violation if ID refers to a connection that is currently closed or pending close with respect to the sending endpoint (it may be pending close with respect to the receiving endpoint if it has also sent a CLOSE operation for this connection). After sending the CLOSE, the connection becomes pending close for the sending endpoint. Thus, it may not reopen the connection until it has received a CLOSE or a CLOSEACK for it from the other endpoint.

Receipt of a CLOSE operation indicates that the other endpoint has closed the indicated connection, and it thus becomes closed on the receiving endpoint. Although the receiving endpoint may not send any more operations for this connection (until it is opened again), it still should provide data in the implementation's input buffers to readers of the connection. If the connection had previously been open instead of pending close, the receiving endpoint must respond with a CLOSEACK operation for the connection.

CLOSEACK operation

The following is the format for records with the CLOSEACK operation:

size (bytes)

name

description

1

opcode

operation code (OPEN)

2

ID

connection identifier

An endpoint sends a CLOSEACK operation to acknowledge a CLOSE operation from the receiving endpoint. It is a protocol violation if ID refers to a connection that is not pending close for the receiving endpoint when the operation is received.

Receipt of a CLOSEACK operation changes the state of the indicated connection from pending close to closed, and thus the connection may be reopened in the future.

REQUEST operation

This is the format for records of the REQUEST operation:

size (bytes)

name

description

1

opcode

operation code (OPEN)

2

ID

connection identifier

4

count

number of additional bytes requested

An endpoint sends a REQUEST operation to increase its input request count for the indicated connection. It is a protocol violation if ID does not refer to a connection that is open with respect to the sending endpoint. The endpoint's input request count is incremented by the value count. The value of count is a signed 32 bit integer, and it is a protocol violation if it is negative or zero.

Receipt of a REQUEST operation causes the output request count for the indicated connection to increase by count. If the connection is pending close by the receiving endpoint, then any REQUEST operations may be ignored.

TRANSMIT operation

This is the format for records of the TRANSMIT operation.

size (bytes)

name

description

1

opcode

operation code (OPEN)

2

ID

connection identifier

4

count

number of bytes in transmission

count

data

transmission data

An endpoint sends a TRANSMIT operation to actually transmit data over the indicated connection. It is a protocol violation if ID does not refer to a connection that is open with respect to the sending endpoint. The endpoint's output request count is decremented by the value count. The value of count is a signed 32 bit integer, and it is a protocol violation if it is negative or zero. It is also a protocol violation if the TRANSMIT operation would cause the sending endpoint's output request count to become negative.

Receipt of a TRANSMIT operation causes the count bytes of data to be added to the queue of bytes available for reading from the connection. The receiving endpoint's input request count is decremented by count. If this causes the input request count to become zero and the user of the connection is trying to read more data, the endpoint should respond with another REQUEST operation. If the connection is pending close by the receiving endpoint, then any TRANSMIT operations may be ignored.

Protocol Violations

If a protocol violation occurs, as defined above or if a communication error is detected in the concrete connection, then the multiplexed connection is shut down. The real connection is terminated, and all virtual connections become closed immediately. Data already available for reading from virtual connections may be read by the users of the connections.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


10 - RMI Wire Protocol

CONTENTS | PREV | NEXT Java Remote Method Invocation

10.4 RMI's Use of HTTP POST Protocol

In order to invoke remote methods through a firewall, some RMI calls make use of the HTTP protocol, more specifically HTTP POST. The URL specified in the post header can be one of the following:

http://<host>:<port>/
http://<host>:80/cgi-bin/java-rmi?forward=<port>

The first URL is used for direct communication with an RMI server on the specific host and port. The second URL form is used to invoke a "cgi" script on the server which forwards the invocation to the server on the specified port.

An HttpPostHeader is a standard HTTP header for a POST request. An HttpResponseHeader is a standard HTTP response to a post. If the response status code is not 200, then it is assumed that there is no Return. Note that only a single RMI call is embedded in an HTTP POST request.

HttpMessage:

HttpPostHeader Header Message

HttpReturn:

HttpResponseHeader Return

      Note - Only the SingleOpProtocol appears in the Header of an HttpMessage. An HttpReturn does not contain a protocol acknowledgment byte.

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


10 - RMI Wire Protocol

CONTENTS | PREV | NEXT Java Remote Method Invocation

10.2 RMI Transport Protocol

The wire format for RMI is represented by a Stream. The terminology adopted here reflects a client perspective. Out refers to output messages and In refers to input messages. The contents of the transport header are not formatted using object serialization.

Stream:

Out

In

The input and output streams used by RMI are paired. Each Out stream has a corresponding In stream. An Out stream in the grammar maps to the output stream of a socket (from the client's perspective). An In stream (in the grammar) is paired with the corresponding socket's input stream. Since output and input streams are paired, the only header information needed on an input stream is an acknowledgment as to whether the protocol is understood; other header information (such as the magic number and version number) can be implied by the context of stream pairing.

10.2.1 Format of an Output Stream

An output stream in RMI consists of transport Header information followed by a sequence of Messages. Alternatively, an output stream can contain an invocation embedded in the HTTP protocol.

Out:

Header Messages
HttpMessage

Header:

0x4a 0x52 0x4d 0x49 Version Protocol

Version:

0x00 0x01

Protocol:

StreamProtocol
SingleOpProtocol
MultiplexProtocol

StreamProtocol:

0x4b

SingleOpProtocol:

0x4c

MultiplexProtocol:

0x4d

Messages:

Message
Messages Message

The Messages are wrapped within a particular protocol as specified by Protocol. For the SingleOpProtocol, there may only be one Message after the Header, and there is no additional data that the Message is wrapped in. The SingleOpProtocol is used for invocation embedded in HTTP requests, where interaction beyond a single request and response is not possible.

For the StreamProtocol and the MultiplexProtocol, the server must respond with a a byte 0x4e acknowledging support for the protocol, and an EndpointIdentifier that contains the host name and port number that the server can see is being used by the client. The client can use this information to determine its host name if it is otherwise unable to do that for security reasons. The client must then respond with another EndpointIdentifier that contains the client's default endpoint for accepting connections. This can be used by a server in the MultiplexProtocol case to identify the client.

For the StreamProtocol, after this endpoint negotiation, the Messages are sent over the output stream without any additional wrapping of the data. For the MultiplexProtocol, the socket connection is used as the concrete connection for a multiplexed connection, as described in Section 10.6, "RMI's Multiplexing Protocol." Virtual connections initiated over this multiplexed connection consist of a series of Messages as described below.

There are three types of output messages: Call, Ping and DgcAck. A Call encodes a method invocation. A Ping is a transport-level message for testing liveness of a remote virtual machine. A DGCAck is an acknowledgment directed to a server's distributed garbage collector that indicates that remote objects in a return value from a server have been received by the client.

Message:

Call
Ping
DgcAck

Call:

0x50 CallData

Ping:

0x52

DgcAck:

0x54 UniqueIdentifier

10.2.2 Format of an Input Stream

There are currently three types of input messages: ReturnData, HttpReturn and PingAck. ReturnData is the result of a "normal" RMI call. An HttpReturn is a return result from an invocation embedded in the HTTP protocol. A PingAck is the acknowledgment for a Ping message.

In:

ProtocolAck Returns
ProtocolNotSupported
HttpReturn

ProtocolAck:

0x4e

ProtocolNotSupported:

0x4f

Returns:

Return
Returns Return

Return:

ReturnData
PingAck

ReturnData:

0x51 ReturnValue

PingAck:

0x53

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


10 - RMI Wire Protocol

CONTENTS | PREV | NEXT Java Remote Method Invocation

10.5 Application-Specific Values for RMI

This table lists the nonterminal symbols that represent application-specific values used by RMI. The table maps each symbol to its respective type. Each is formatted using the protocol in which it is embedded.

Symbol

type

Count

short

Exception

java.lang.Exception

Hash

long

Hostname

UTF

Number

int

Object

java.lang.Object

ObjectNumber

long

Operation

int

PortNumber

int

Primitive

byte, int, short, long...

Time

long

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


10 - RMI Wire Protocol

CONTENTS | PREV | NEXT Java Remote Method Invocation

RMI Wire Protocol

CHAPTER 10

Topics:

  • Overview
  • RMI Transport Protocol
  • RMI's Use of Object Serialization Protocol
  • RMI's Use of HTTP POST Protocol
  • Application-Specific Values for RMI
  • RMI's Multiplexing Protocol

CONTENTS | PREV | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


Contents

JavaTM Remote Method Invocation Specification

JavaTM Remote Method Invocation (Java RMI) is a distributed object model for the Java programming language that retains the semantics of the Java platform's object model, making distributed objects easy to implement and to use. The system combines aspects of the Modula-3 Network Objects system and Spring's subcontract and includes some novel features made possible by the Java SE platform.
Revision 1.11, JavaTM SE Developer Kit, v6

CONTENTS | NEXT
Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved.


1 - System Architecture

CONTENTS | PREV | NEXT Java Object Serialization Specification
version 6.0

System Architecture

CHAPTER 1

Topics:

  • Overview
  • Writing to an Object Stream
  • Reading from an Object Stream
  • Object Streams as Containers
  • Defining Serializable Fields for a Class
  • Documenting Serializable Fields and Data for a Class
  • Accessing Serializable Fields of a Class
  • The ObjectOutput Interface
  • The ObjectInput Interface
  • The Serializable Interface
  • The Externalizable Interface
  • Serialization of Enum Constants
  • Protecting Sensitive Information

1.1 Overview

The ability to store and retrieve JavaTM objects is essential to building all but the most transient applications. The key to storing and retrieving objects in a serialized form is representing the state of objects sufficient to reconstruct the object(s). Objects to be saved in the stream may support either the Serializable or the Externalizable interface. For JavaTM objects, the serialized form must be able to identify and verify the JavaTM class from which the contents of the object were saved and to restore the contents to a new instance. For serializable objects, the stream includes sufficient information to restore the fields in the stream to a compatible version of the class. For Externalizable objects, the class is solely responsible for the external format of its contents.

Objects to be stored and retrieved frequently refer to other objects. Those other objects must be stored and retrieved at the same time to maintain the relationships between the objects. When an object is stored, all of the objects that are reachable from that object are stored as well.

The goals for serializing JavaTM objects are to:

  • Have a simple yet extensible mechanism.
  • Maintain the JavaTM object type and safety properties in the serialized form.
  • Be extensible to support marshaling and unmarshaling as needed for remote objects.
  • Be extensible to support simple persistence of JavaTM objects.
  • Require per class implementation only for customization.
  • Allow the object to define its external format.

1.2 Writing to an Object Stream

Writing objects and primitives to a stream is a straightforward process. For example:

// Serialize today's date to a file.
    FileOutputStream f = new FileOutputStream("tmp");
    ObjectOutput s = new ObjectOutputStream(f);
    s.writeObject("Today");
    s.writeObject(new Date());
    s.flush();
First an OutputStream, in this case a FileOutputStream, is needed to receive the bytes. Then an ObjectOutputStream is created that writes to the FileOutputStream. Next, the string "Today" and a Date object are written to the stream. More generally, objects are written with the writeObject method and primitives are written to the stream with the methods of DataOutput.

The writeObject method (see Section 2.3, "The writeObject Method") serializes the specified object and traverses its references to other objects in the object graph recursively to create a complete serialized representation of the graph. Within a stream, the first reference to any object results in the object being serialized or externalized and the assignment of a handle for that object. Subsequent references to that object are encoded as the handle. Using object handles preserves sharing and circular references that occur naturally in object graphs. Subsequent references to an object use only the handle allowing a very compact representation.

Special handling is required for arrays, enum constants, and objects of type Class, ObjectStreamClass, and String. Other objects must implement either the Serializable or the Externalizable interface to be saved in or restored from a stream.

Primitive data types are written to the stream with the methods in the DataOutput interface, such as writeInt, writeFloat, or writeUTF. Individual bytes and arrays of bytes are written with the methods of OutputStream. Except for serializable fields, primitive data is written to the stream in block-data records, with each record prefixed by a marker and an indication of the number of bytes in the record.

ObjectOutputStream can be extended to customize the information about classes in the stream or to replace objects to be serialized. Refer to the annotateClass and replaceObject method descriptions for details.

1.3 Reading from an Object Stream

Reading an object from a stream, like writing, is straightforward:

// Deserialize a string and date from a file.
    FileInputStream in = new FileInputStream("tmp");
    ObjectInputStream s = new ObjectInputStream(in);
    String today = (String)s.readObject();
    Date date = (Date)s.readObject();
First an InputStream, in this case a FileInputStream, is needed as the source stream. Then an ObjectInputStream is created that reads from the InputStream. Next, the string "Today" and a Date object are read from the stream. Generally, objects are read with the readObject method and primitives are read from the stream with the methods of DataInput.

The readObject method deserializes the next object in the stream and traverses its references to other objects recursively to create the complete graph of objects serialized.

Primitive data types are read from the stream with the methods in the DataInput interface, such as readInt, readFloat, or readUTF. Individual bytes and arrays of bytes are read with the methods of InputStream. Except for serializable fields, primitive data is read from block-data records.

ObjectInputStream can be extended to utilize customized information in the stream about classes or to replace objects that have been deserialized. Refer to the resolveClass and resolveObject method descriptions for details.

1.4 Object Streams as Containers

Object Serialization produces and consumes a stream of bytes that contain one or more primitives and objects. The objects written to the stream, in turn, refer to other objects, which are also represented in the stream. Object Serialization produces just one stream format that encodes and stores the contained objects.

Each object that acts as a container implements an interface which allows primitives and objects to be stored in or retrieved from it. These interfaces are the ObjectOutput and ObjectInput interfaces which:

  • Provide a stream to write to and to read from
  • Handle requests to write primitive types and objects to the stream
  • Handle requests to read primitive types and objects from the stream
Each object which is to be stored in a stream must explicitly allow itself to be stored and must implement the protocols needed to save and restore its state. Object Serialization defines two such protocols. The protocols allow the container to ask the object to write and read its state.

To be stored in an Object Stream, each object must implement either the Serializable or the Externalizable interface:

  • For a Serializable class, Object Serialization can automatically save and restore fields of each class of an object and automatically handle classes that evolve by adding fields or supertypes. A serializable class can declare which of its fields are saved or restored, and write and read optional values and objects.
  • For an Externalizable class, Object Serialization delegates to the class complete control over its external format and how the state of the supertype(s) is saved and restored.

1.5 Defining Serializable Fields for a Class

The serializable fields of a class can be defined two different ways. Default serializable fields of a class are defined to be the non-transient and non-static fields. This default computation can be overridden by declaring a special field in the Serializable class, serialPersistentFields. This field must be initialized with an array of ObjectStreamField objects that list the names and types of the serializable fields. The modifiers for the field are required to be private, static, and final. If the field's value is null or is otherwise not an instance of ObjectStreamField[], or if the field does not have the required modifiers, then the behavior is as if the field were not declared at all.

For example, the following declaration duplicates the default behavior.

class List implements Serializable {
    List next;

    private static final ObjectStreamField[] serialPersistentFields
                 = {new ObjectStreamField("next", List.class)};

}
By using serialPersistentFields to define the Serializable fields for a class, there no longer is a limitation that a serializable field must be a field within the current definition of the Serializable class. The writeObject and readObject methods of the Serializable class can map the current implementation of the class to the serializable fields of the class using the interface that is described in Section 1.7, "Accessing Serializable Fields of a Class." Therefore, the fields for a Serializable class can change in a later release, as long as it maintains the mapping back to its Serializable fields that must remain compatible across release boundaries.

Note - There is, however, a limitation to the use of this mechanism to specify serializable fields for inner classes. Inner classes can only contain final static fields that are initialized to constants or expressions built up from constants. Consequently, it is not possible to set serialPersistentFields for an inner class (though it is possible to set it for static member classes). For other restrictions pertaining to serialization of inner class instances, see section Section 1.10, "The Serializable Interface".

1.6 Documenting Serializable Fields and Data for a Class

It is important to document the serializable state of a class to enable interoperability with alternative implementations of a Serializable class and to document class evolution. Documenting a serializable field gives one a final opportunity to review whether or not the field should be serializable. The serialization javadoc tags, @serial, @serialField, and @serialData, provide a way to document the serialized form for a Serializable class within the source code.

  • The @serial tag should be placed in the javadoc comment for a default serializable field. The syntax is as follows:
    @serial field-description
    The optional field-description describes the meaning of the field and its acceptable values. The field-description can span multiple lines. When a field is added after the initial release, a @since tag indicates the version the field was added. The field-description for @serial provides serialization-specific documentation and is appended to the javadoc comment for the field within the serialized form documentation.
  • The @serialField tag is used to document an ObjectStreamField component of a serialPersistentFields array. One of these tags should be used for each ObjectStreamField component. The syntax is as follows:
    @serialField field-name field-type field-description
  • The @serialData tag describes the sequences and types of data written or read. The tag describes the sequence and type of optional data written by writeObject or all data written by the Externalizable.writeExternal method. The syntax is as follows:
    @serialData data-description
The javadoc application recognizes the serialization javadoc tags and generates a specification for each Serializable and Externalizable class. See Section C.1, "Example Alternate Implementation of java.io.File" for an example that uses these tags.

When a class is declared Serializable, the serializable state of the object is defined by serializable fields (by name and type) plus optional data. Optional data can only be written explicitly by the writeObject method of a Serializable class. Optional data can be read by the Serializable class' readObject method or serialization will skip unread optional data.

When a class is declared Externalizable, the data that is written to the stream by the class itself defines the serialized state. The class must specify the order, types, and meaning of each datum that is written to the stream. The class must handle its own evolution, so that it can continue to read data written by and write data that can be read by previous versions. The class must coordinate with the superclass when saving and restoring data. The location of the superclasses data in the stream must be specified.

The designer of a Serializable class must ensure that the information saved for the class is appropriate for persistence and follows the serialization-specified rules for interoperability and evolution. Class evolution is explained in greater detail in Chapter 5, "Versioning of Serializable Objects."

1.7 Accessing Serializable Fields of a Class

Serialization provides two mechanisms for accessing the serializable fields in a stream:

  • The default mechanism requires no customization
  • The Serializable Fields API allows a class to explicitly access/set the serializable fields by name and type
The default mechanism is used automatically when reading or writing objects that implement the Serializable interface and do no further customization. The serializable fields are mapped to the corresponding fields of the class and values are either written to the stream from those fields or are read in and assigned respectively. If the class provides writeObject and readObject methods, the default mechanism can be invoked by calling defaultWriteObject and defaultReadObject. When the writeObject and readObject methods are implemented, the class has an opportunity to modify the serializable field values before they are written or after they are read.

When the default mechanism cannot be used, the serializable class can use the putFields method of ObjectOutputStream to put the values for the serializable fields into the stream. The writeFields method of ObjectOutputStream puts the values in the correct order, then writes them to the stream using the existing protocol for serialization. Correspondingly, the readFields method of ObjectInputStream reads the values from the stream and makes them available to the class by name in any order. See Section 2.2, "The ObjectOutputStream.PutField Class" and Section 3.2, "The ObjectInputStream.GetField Class." for a detailed description of the Serializable Fields API.

1.8 The ObjectOutput Interface

The ObjectOutput interface provides an abstract, stream-based interface to object storage. It extends the DataOutput interface so those methods can be used for writing primitive data types. Objects that implement this interface can be used to store primitives and objects.

package java.io;

public interface ObjectOutput extends DataOutput
{
    public void writeObject(Object obj) throws IOException;
    public void write(int b) throws IOException;
    public void write(byte b[]) throws IOException;
     public void write(byte b[], int off, int len) throws IOException;
    public void flush() throws IOException;
    public void close() throws IOException;
}
The writeObject method is used to write an object. The exceptions thrown reflect errors while accessing the object or its fields, or exceptions that occur in writing to storage. If any exception is thrown, the underlying storage may be corrupted. If this occurs, refer to the object that is implementing this interface for more information.

1.9 The ObjectInput Interface

The ObjectInput interface provides an abstract stream based interface to object retrieval. It extends the DataInput interface so those methods for reading primitive data types are accessible in this interface.

package java.io;

public interface ObjectInput extends DataInput
{
    public Object readObject()
        throws ClassNotFoundException, IOException;
    public int read() throws IOException;
    public int read(byte b[]) throws IOException;
    public int read(byte b[], int off, int len) throws IOException;
    public long skip(long n) throws IOException;
    public int available() throws IOException;
    public void close() throws IOException;
}
The readObject method is used to read and return an object. The exceptions thrown reflect errors while accessing the objects or its fields or exceptions that occur in reading from the storage. If any exception is thrown, the underlying storage may be corrupted. If this occurs, refer to the object implementing this interface for additional information.

1.10 The Serializable Interface

Object Serialization produces a stream with information about the JavaTM classes for the objects which are being saved. For serializable objects, sufficient information is kept to restore those objects even if a different (but compatible) version of the implementation of the class is present. The Serializable interface is defined to identify classes which implement the serializable protocol:

package java.io;

public interface Serializable {};
A Serializable class must do the following:

  • Implement the java.io.Serializable interface
  • Identify the fields that should be serializable
(Use the serialPersistentFields member to explicitly declare them serializable or use the transient keyword to denote nonserializable fields.)

  • Have access to the no-arg constructor of its first nonserializable superclass
The class can optionally define the following methods:

  • A writeObject method to control what information is saved or to append additional information to the stream
  • A readObject method either to read the information written by the corresponding writeObject method or to update the state of the object after it has been restored
  • A writeReplace method to allow a class to nominate a replacement object to be written to the stream
(See Section 2.5, "The writeReplace Method" for additional information.)

  • A readResolve method to allow a class to designate a replacement object for the object just read from the stream
(See Section 3.7, "The readResolve Method" for additional information.)

ObjectOutputStream and ObjectInputStream allow the serializable classes on which they operate to evolve (allow changes to the classes that are compatible with the earlier versions of the classes). See Section 5.5, "Compatible JavaTM Type Evolution" for information about the mechanism which is used to allow compatible changes.

Note - Serialization of inner classes (i.e., nested classes that are not static member classes), including local and anonymous classes, is strongly discouraged for several reasons. Because inner classes declared in non-static contexts contain implicit non-transient references to enclosing class instances, serializing such an inner class instance will result in serialization of its associated outer class instance as well. Synthetic fields generated by javac (or other JavaTM compilers) to implement inner classes are implementation dependent and may vary between compilers; differences in such fields can disrupt compatibility as well as result in conflicting default serialVersionUID values. The names assigned to local and anonymous inner classes are also implementation dependent and may differ between compilers. Since inner classes cannot declare static members other than compile-time constant fields, they cannot use the serialPersistentFields mechanism to designate serializable fields. Finally, because inner classes associated with outer instances do not have zero-argument constructors (constructors of such inner classes implicitly accept the enclosing instance as a prepended parameter), they cannot implement Externalizable. None of the issues listed above, however, apply to static member classes.

1.11 The Externalizable Interface

For Externalizable objects, only the identity of the class of the object is saved by the container; the class must save and restore the contents. The Externalizable interface is defined as follows:

package java.io;

public interface Externalizable extends Serializable
{
    public void writeExternal(ObjectOutput out)
        throws IOException;

    public void readExternal(ObjectInput in)
        throws IOException, java.lang.ClassNotFoundException;
}
The class of an Externalizable object must do the following:

  • Implement the java.io.Externalizable interface
  • Implement a writeExternal method to save the state of the object
(It must explicitly coordinate with its supertype to save its state.)

  • Implement a readExternal method to read the data written by the writeExternal method from the stream and restore the state of the object
(It must explicitly coordinate with the supertype to save its state.)

  • Have the writeExternal and readExternal methods be solely responsible for the format, if an externally defined format is written
Note - The writeExternal and readExternal methods are public and raise the risk that a client may be able to write or read information in the object other than by using its methods and fields. These methods must be used only when the information held by the object is not sensitive or when exposing it does not present a security risk.
  • Have a public no-arg constructor
Note - Inner classes associated with enclosing instances cannot have no-arg constructors, since constructors of such classes implicitly accept the enclosing instance as a prepended parameter. Consequently the Externalizable interface mechanism cannot be used for inner classes and they should implement the Serializable interface, if they must be serialized. Several limitations exist for serializable inner classes as well, however; see Section 1.10, "The Serializable Interface", for a full enumeration.
An Externalizable class can optionally define the following methods:

  • A writeReplace method to allow a class to nominate a replacement object to be written to the stream
(See Section 2.5, "The writeReplace Method" for additional information.)

  • A readResolve method to allow a class to designate a replacement object for the object just read from the stream
(See Section 3.7, "The readResolve Method" for additional information.)

1.12 Serialization of Enum Constants

Enum constants are serialized differently than ordinary serializable or externalizable objects. The serialized form of an enum constant consists solely of its name; field values of the constant are not present in the form. To serialize an enum constant, ObjectOutputStream writes the value returned by the enum constant's name method. To deserialize an enum constant, ObjectInputStream reads the constant name from the stream; the deserialized constant is then obtained by calling the java.lang.Enum.valueOf method, passing the constant's enum type along with the received constant name as arguments. Like other serializable or externalizable objects, enum constants can function as the targets of back references appearing subsequently in the serialization stream.

The process by which enum constants are serialized cannot be customized: any class-specific writeObject, readObject, readObjectNoData, writeReplace, and readResolve methods defined by enum types are ignored during serialization and deserialization. Similarly, any serialPersistentFields or serialVersionUID field declarations are also ignored--all enum types have a fixed serialVersionUID of 0L. Documenting serializable fields and data for enum types is unnecessary, since there is no variation in the type of data sent.

1.13 Protecting Sensitive Information

When developing a class that provides controlled access to resources, care must be taken to protect sensitive information and functions. During deserialization, the private state of the object is restored. For example, a file descriptor contains a handle that provides access to an operating system resource. Being able to forge a file descriptor would allow some forms of illegal access, since restoring state is done from a stream. Therefore, the serializing runtime must take the conservative approach and not trust the stream to contain only valid representations of objects. To avoid compromising a class, the sensitive state of an object must not be restored from the stream, or it must be reverified by the class. Several techniques are available to protect sensitive data in classes.

The easiest technique is to mark fields that contain sensitive data as private transient. Transient fields are not persistent and will not be saved by any persistence mechanism. Marking the field will prevent the state from appearing in the stream and from being restored during deserialization. Since writing and reading (of private fields) cannot be superseded outside of the class, the transient fields of the class are safe.

Particularly sensitive classes should not be serialized at all. To accomplish this, the object should not implement either the Serializable or the Externalizable interface.

Some classes may find it beneficial to allow writing and reading but specifically handle and revalidate the state as it is deserialized. The class should implement writeObject and readObject methods to save and restore only the appropriate state. If access should be denied, throwing a NotSerializableException will prevent further access.

CONTENTS | PREV | NEXT
Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved.


2 - Object Output Classes

CONTENTS | PREV | NEXT Java Object Serialization Specification
version 6.0

Object Output Classes

CHAPTER 2

Topics:

  • The ObjectOutputStream Class
  • The ObjectOutputStream.PutField Class
  • The writeObject Method
  • The writeExternal Method
  • The writeReplace Method
  • The useProtocolVersion Method

2.1 The ObjectOutputStream Class

Class ObjectOutputStream implements object serialization. It maintains the state of the stream including the set of objects already serialized. Its methods control the traversal of objects to be serialized to save the specified objects and the objects to which they refer.

package java.io;

public class ObjectOutputStream
    extends OutputStream
    implements ObjectOutput, ObjectStreamConstants
{
    public ObjectOutputStream(OutputStream out)
        throws IOException;

    public final void writeObject(Object obj)
        throws IOException;

    public void writeUnshared(Object obj)
        throws IOException;

    public void defaultWriteObject()
        throws IOException, NotActiveException;

    public PutField putFields()
        throws IOException;

    public writeFields()
        throws IOException;

    public void reset() throws IOException;

    protected void annotateClass(Class cl) throws IOException;

    protected void writeClassDescriptor(ObjectStreamClass desc)
        throws IOException;

    protected Object replaceObject(Object obj) throws IOException;

    protected boolean enableReplaceObject(boolean enable)
        throws SecurityException;

    protected void writeStreamHeader() throws IOException;

    public void write(int data) throws IOException;

    public void write(byte b[]) throws IOException;

    public void write(byte b[], int off, int len) throws IOException;

    public void flush() throws IOException;

    protected void drain() throws IOException;

    public void close() throws IOException;

    public void writeBoolean(boolean data) throws IOException;

    public void writeByte(int data) throws IOException;

    public void writeShort(int data) throws IOException;

    public void writeChar(int data) throws IOException;

    public void writeInt(int data) throws IOException;

    public void writeLong(long data) throws IOException;

    public void writeFloat(float data) throws IOException;

    public void writeDouble(double data) throws IOException;

    public void writeBytes(String data) throws IOException;

    public void writeChars(String data) throws IOException;

    public void writeUTF(String data) throws IOException;

    // Inner class to provide access to serializable fields.
    abstract static public class PutField
    {
        public void put(String name, boolean value)
            throws IOException, IllegalArgumentException;

        public void put(String name, char data)
            throws IOException, IllegalArgumentException;

        public void put(String name, byte data)
            throws IOException, IllegalArgumentException;

        public void put(String name, short data)
            throws IOException, IllegalArgumentException;

        public void put(String name, int data)
            throws IOException, IllegalArgumentException;

        public void put(String name, long data)
            throws IOException, IllegalArgumentException;

        public void put(String name, float data)
            throws IOException, IllegalArgumentException;

        public void put(String name, double data)
            throws IOException, IllegalArgumentException;

        public void put(String name, Object data)
            throws IOException, IllegalArgumentException;
    }

    public void useProtocolVersion(int version) throws IOException;

    protected ObjectOutputStream()
        throws IOException;

     protected writeObjectOverride()
        throws NotActiveException, IOException;
}
The single-argument ObjectOutputStream constructor creates an ObjectOutputStream that serializes objects to the given OutputStream. The constructor calls writeStreamHeader to write a magic number and version to the stream that will be read and verified by a corresponding call to readStreamHeader in the single-argument ObjectInputStream constructor. If a security manager is installed, this constructor checks for the "enableSubclassImplementation" SerializablePermission when invoked directly or indirectly by the constructor of a subclass which overrides the putFields and/or writeUnshared methods.

The writeObject method is used to serialize an object to the stream. An object is serialized as follows:

1. If a subclass is overriding the implementation, call the writeObjectOverride method and return. Overriding the implementation is described at the end of this section.
2. If there is data in the block-data buffer, the data is written to the stream and the buffer is reset.
3. If the object is null, null is put in the stream and writeObject returns.
4. If the object has been previously replaced, as described in Step 8, write the handle of the replacement to the stream and writeObject returns.
5. If the object has already been written to the stream, its handle is written to the stream and writeObject returns.
6. If the object is a Class, the corresponding ObjectStreamClass is written to the stream, a handle is assigned for the class, and writeObject returns.
7. If the object is an ObjectStreamClass, a handle is assigned to the object, after which it is written to the stream using one of the class descriptor formats described in section 4.3. In versions 1.3 and later of the JavaTM 2 SDK, Standard Edition, the writeClassDescriptor method is called to output the ObjectStreamClass if it represents a class that is not a dynamic proxy class, as determined by passing the associated Class object to the isProxyClass method of java.lang.reflect.Proxy. Afterwards, an annotation for the represented class is written: if the class is a dynamic proxy class, then the annotateProxyClass method is called; otherwise, the annotateClass method is called. The writeObject method then returns.
8. Process potential substitutions by the class of the object and/or by a subclass of ObjectInputStream.
a. If the class of an object is not an enum type and defines the appropriate writeReplace method, the method is called. Optionally, it can return a substitute object to be serialized.
b. Then, if enabled by calling the enableReplaceObject method, the replaceObject method is called to allow subclasses of ObjectOutputStream to substitute for the object being serialized. If the original object was replaced in the previous step, the replaceObject method is called with the replacement object.
If the original object was replaced by either one or both steps above, the mapping from the original object to the replacement is recorded for later use in Step 4. Then, Steps 3 through 7 are repeated on the new object.
If the replacement object is not one of the types covered by Steps 3 through 7, processing resumes using the replacement object at Step 10.
9. If the object is a java.lang.String, the string is written as length information followed by the contents of the string encoded in modified UTF-8. For details, refer to Section 6.2, "Stream Elements". A handle is assigned to the string, and writeObject returns.
10. If the object is an array, writeObject is called recursively to write the ObjectStreamClass of the array. The handle for the array is assigned. It is followed by the length of the array. Each element of the array is then written to the stream, after which writeObject returns.
11. If the object is an enum constant, the ObjectStreamClass for the enum type of the constant is written by recursively calling writeObject. It will appear in the stream only the first time it is referenced. A handle is assigned for the enum constant. Next, the value returned by the name method of the enum constant is written as a String object, as described in step 9. Note that if the same name string has appeared previously in the stream, a back reference to it will be written. The writeObject method then returns.
12. For regular objects, the ObjectStreamClass for the class of the object is written by recursively calling writeObject. It will appear in the stream only the first time it is referenced. A handle is assigned for the object.
13. The contents of the object are written to the stream.
a. If the object is serializable, the highest serializable class is located. For that class, and each derived class, that class's fields are written. If the class does not have a writeObject method, the defaultWriteObject method is called to write the serializable fields to the stream. If the class does have a writeObject method, it is called. It may call defaultWriteObject or putFields and writeFields to save the state of the object, and then it can write other information to the stream.
b. If the object is externalizable, the writeExternal method of the object is called.
c. If the object is neither serializable or externalizable, the NotSerializableException is thrown.
Exceptions may occur during the traversal or may occur in the underlying stream. For any subclass of IOException, the exception is written to the stream using the exception protocol and the stream state is discarded. If a second IOException is thrown while attempting to write the first exception into the stream, the stream is left in an unknown state and StreamCorruptedException is thrown from writeObject. For other exceptions, the stream is aborted and left in an unknown and unusable state.

The writeUnshared method writes an "unshared" object to the ObjectOutputStream. This method is identical to writeObject, except that it always writes the given object as a new, unique object in the stream (as opposed to a back-reference pointing to a previously serialized instance). Specifically:

  • An object written via writeUnshared is always serialized in the same manner as a newly appearing object (an object that has not been written to the stream yet), regardless of whether or not the object has been written previously.
  • If writeObject is used to write an object that has been previously written with writeUnshared, the previous writeUnshared operation is treated as if it were a write of a separate object. In other words, ObjectOutputStream will never generate back-references to object data written by calls to writeUnshared.
While writing an object via writeUnshared does not in itself guarantee a unique reference to the object when it is deserialized, it allows a single object to be defined multiple times in a stream, so that multiple calls to the ObjectInputStream.readUnshared method (see Section 3.1, "The ObjectInputStream Class") by the receiver will not conflict. Note that the rules described above only apply to the base-level object written with writeUnshared, and not to any transitively referenced sub-objects in the object graph to be serialized.

The defaultWriteObject method implements the default serialization mechanism for the current class. This method may be called only from a class's writeObject method. The method writes all of the serializable fields of the current class to the stream. If called from outside the writeObject method, the NotActiveException is thrown.

The putFields method returns a PutField object the caller uses to set the values of the serializable fields in the stream. The fields may be set in any order. After all of the fields have been set, writeFields must be called to write the field values in the canonical order to the stream. If a field is not set, the default value appropriate for its type will be written to the stream. This method may only be called from within the writeObject method of a serializable class. It may not be called more than once or if defaultWriteObject has been called. Only after writeFields has been called can other data be written to the stream.

The reset method resets the stream state to be the same as if it had just been constructed. Reset will discard the state of any objects already written to the stream. The current point in the stream is marked as reset, so the corresponding ObjectInputStream will reset at the same point. Objects previously written to the stream will not be remembered as already having been written to the stream. They will be written to the stream again. This is useful when the contents of an object or objects must be sent again. Reset may not be called while objects are being serialized. If called inappropriately, an IOException is thrown.

Starting with the JavaTM 2 SDK, Standard Edition, v1.3, the writeClassDescriptor method is called when an ObjectStreamClass needs to be serialized. writeClassDescriptor is responsible for writing a representation of the ObjectStreamClass to the serialization stream. Subclasses may override this method to customize the way in which class descriptors are written to the serialization stream. If this method is overridden, then the corresponding readClassDescriptor method in ObjectInputStream should also be overridden to reconstitute the class descriptor from its custom stream representation. By default, writeClassDescriptor writes class descriptors according to the format specified in Section 6.4, "Grammar for the Stream Format". Note that this method will only be called if the ObjectOutputStream is not using the old serialization stream format (see Section 6.3, "Stream Protocol Versions"). If the serialization stream is using the old format (ObjectStreamConstants.PROTOCOL_VERSION_1), the class descriptor will be written internally in a manner that cannot be overridden or customized.

The annotateClass method is called while a Class is being serialized, and after the class descriptor has been written to the stream. Subclasses may extend this method and write other information to the stream about the class. This information must be read by the resolveClass method in a corresponding ObjectInputStream subclass.

An ObjectOutputStream subclass can implement the replaceObject method to monitor or replace objects during serialization. Replacing objects must be enabled explicitly by calling enableReplaceObject before calling writeObject with the first object to be replaced. Once enabled, replaceObject is called for each object just prior to serializing the object for the first time. Note that the replaceObject method is not called for objects of the specially handled classes, Class and ObjectStreamClass. An implementation of a subclass may return a substitute object that will be serialized instead of the original. The substitute object must be serializable. All references in the stream to the original object will be replaced by the substitute object.

When objects are being replaced, the subclass must ensure that the substituted object is compatible with every field where the reference will be stored, or that a complementary substitution will be made during deserialization. Objects, whose type is not a subclass of the type of the field or array element, will later abort the deserialization by raising a ClassCastException and the reference will not be stored.

The enableReplaceObject method can be called by trusted subclasses of ObjectOutputStream to enable the substitution of one object for another during serialization. Replacing objects is disabled until enableReplaceObject is called with a true value. It may thereafter be disabled by setting it to false. The previous setting is returned. The enableReplaceObject method checks that the stream requesting the replacement can be trusted. To ensure that the private state of objects is not unintentionally exposed, only trusted stream subclasses may use replaceObject. Trusted classes are those classes that belong to a security protection domain with permission to enable Serializable substitution.

If the subclass of ObjectOutputStream is not considered part of the system domain, SerializablePermission "enableSubstitution" must be added to the security policy file. AccessControlException is thrown if the protection domain of the subclass of ObjectInputStream does not have permission to "enableSubstitution" by calling enableReplaceObject. See the document JavaTM Security Architecture (JDK1.2) for additional information about the security model.

The writeStreamHeader method writes the magic number and version to the stream. This information must be read by the readStreamHeader method of ObjectInputStream. Subclasses may need to implement this method to identify the stream's unique format.

The flush method is used to empty any buffers being held by the stream and to forward the flush to the underlying stream. The drain method may be used by subclassers to empty only the ObjectOutputStream's buffers without forcing the underlying stream to be flushed.

All of the write methods for primitive types encode their values using a DataOutputStream to put them in the standard stream format. The bytes are buffered into block data records so they can be distinguished from the encoding of objects. This buffering allows primitive data to be skipped if necessary for class versioning. It also allows the stream to be parsed without invoking class-specific methods.

To override the implementation of serialization, the subclass of ObjectOutputStream should call the protected no-arg ObjectOutputStream, constructor. There is a security check within the no-arg constructor for SerializablePermission "enableSubclassImplementation" to ensure that only trusted classes are allowed to override the default implementation. This constructor does not allocate any private data for ObjectOutputStream and sets a flag that indicates that the final writeObject method should invoke the writeObjectOverride method and return. All other ObjectOutputStream methods are not final and can be directly overridden by the subclass.

2.2 The ObjectOutputStream.PutField Class

Class PutField provides the API for setting values of the serializable fields for a class when the class does not use default serialization. Each method puts the specified named value into the stream. An IllegalArgumentException is thrown if name does not match the name of a serializable field for the class whose fields are being written, or if the type of the named field does not match the second parameter type of the specific put method invoked.

2.3 The writeObject Method

For serializable objects, the writeObject method allows a class to control the serialization of its own fields. Here is its signature:

    private void writeObject(ObjectOutputStream stream)
        throws IOException;
Each subclass of a serializable object may define its own writeObject method. If a class does not implement the method, the default serialization provided by defaultWriteObject will be used. When implemented, the class is only responsible for writing its own fields, not those of its supertypes or subtypes.

The class's writeObject method, if implemented, is responsible for saving the state of the class. Either ObjectOutputStream's defaultWriteObject or writeFields method must be called once (and only once) before writing any optional data that will be needed by the corresponding readObject method to restore the state of the object; even if no optional data is written, defaultWriteObject or writeFields must still be invoked once. If defaultWriteObject or writeFields is not invoked once prior to the writing of optional data (if any), then the behavior of instance deserialization is undefined in cases where the ObjectInputStream cannot resolve the class which defined the writeObject method in question.

The responsibility for the format, structure, and versioning of the optional data lies completely with the class.

2.4 The writeExternal Method

Objects implementing java.io.Externalizable must implement the writeExternal method to save the entire state of the object. It must coordinate with its superclasses to save their state. All of the methods of ObjectOutput are available to save the object's primitive typed fields and object fields.

    public void writeExternal(ObjectOutput stream)
        throws IOException;
A new default format for writing Externalizable data has been introduced in JDKTM 1.2. The new format specifies that primitive data will be written in block data mode by writeExternal methods. Additionally, a tag denoting the end of the External object is appended to the stream after the writeExternal method returns. The benefits of this format change are discussed in Section 3.6, "The readExternal Method." Compatibility issues caused by this change are discussed in Section 2.6, "The useProtocolVersion Method."

2.5 The writeReplace Method

For Serializable and Externalizable classes, the writeReplace method allows a class of an object to nominate its own replacement in the stream before the object is written. By implementing the writeReplace method, a class can directly control the types and instances of its own instances being serialized.

The method is defined as follows:

    ANY-ACCESS-MODIFIER Object writeReplace() {
            throws ObjectStreamException;
The writeReplace method is called when ObjectOutputStream is preparing to write the object to the stream. The ObjectOutputStream checks whether the class defines the writeReplace method. If the method is defined, the writeReplace method is called to allow the object to designate its replacement in the stream. The object returned should be either of the same type as the object passed in or an object that when read and resolved will result in an object of a type that is compatible with all references to the object. If it is not, a ClassCastException will occur when the type mismatch is discovered.

2.6 The useProtocolVersion Method

Due to a stream protocol change that was not backwards compatible, a mechanism has been added to enable the current Virtual Machine to write a serialization stream that is readable by a previous release. Of course, the problems that are corrected by the new stream format will exist when using the backwards compatible protocol.

Stream protocol versions are discussed in Section 6.3, "Stream Protocol Versions."

CONTENTS | PREV | NEXT
Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved.


3 - Object Input Classes

CONTENTS | PREV | NEXT Java Object Serialization Specification
version 6.0

Object Input Classes

CHAPTER 3

Topics:

  • The ObjectInputStream Class
  • The ObjectInputStream.GetField Class
  • The ObjectInputValidation Interface
  • The readObject Method
  • The readExternal Method
  • The readResolve Method

3.1 The ObjectInputStream Class

Class ObjectInputStream implements object deserialization. It maintains the state of the stream including the set of objects already deserialized. Its methods allow primitive types and objects to be read from a stream written by ObjectOutputStream. It manages restoration of the object and the objects that it refers to from the stream.

package java.io;

public class ObjectInputStream
    extends InputStream
    implements ObjectInput, ObjectStreamConstants
{
    public ObjectInputStream(InputStream in)
        throws StreamCorruptedException, IOException;

    public final Object readObject()
        throws OptionalDataException, ClassNotFoundException,
            IOException;

    public Object readUnshared()
        throws OptionalDataException, ClassNotFoundException,
            IOException;

    public void defaultReadObject()
        throws IOException, ClassNotFoundException,
            NotActiveException;

    public GetField readFields()
        throws IOException;

    public synchronized void registerValidation(
        ObjectInputValidation obj, int prio)
        throws NotActiveException, InvalidObjectException;

    protected ObjectStreamClass readClassDescriptor()
        throws IOException, ClassNotFoundException;

    protected Class resolveClass(ObjectStreamClass v)
        throws IOException, ClassNotFoundException;

    protected Object resolveObject(Object obj)
        throws IOException;

    protected boolean enableResolveObject(boolean enable)
        throws SecurityException;

    protected void readStreamHeader()
        throws IOException, StreamCorruptedException;

    public int read() throws IOException;

    public int read(byte[] data, int offset, int length)
        throws IOException

    public int available() throws IOException;

    public void close() throws IOException;

    public boolean readBoolean() throws IOException;

    public byte readByte() throws IOException;

    public int readUnsignedByte() throws IOException;

    public short readShort() throws IOException;

    public int readUnsignedShort() throws IOException;

    public char readChar() throws IOException;

    public int readInt() throws IOException;

    public long readLong() throws IOException;

    public float readFloat() throws IOException;

    public double readDouble() throws IOException;

    public void readFully(byte[] data) throws IOException;

    public void readFully(byte[] data, int offset, int size)
        throws IOException;

    public int skipBytes(int len) throws IOException;

    public String readLine() throws IOException;

    public String readUTF() throws IOException;

    // Class to provide access to serializable fields.
    static abstract public class GetField
    {
        public ObjectStreamClass getObjectStreamClass();

        public boolean defaulted(String name)
            throws IOException, IllegalArgumentException;

        public char get(String name, char default)
            throws IOException, IllegalArgumentException;

        public boolean get(String name, boolean default)
            throws IOException, IllegalArgumentException;

        public byte get(String name, byte default)
            throws IOException, IllegalArgumentException;

        public short get(String name, short default)
            throws IOException, IllegalArgumentException;

        public int get(String name, int default)
            throws IOException, IllegalArgumentException;

        public long get(String name, long default)
            throws IOException, IllegalArgumentException;

        public float get(String name, float default)
            throws IOException, IllegalArgumentException;

        public double get(String name, double default)
            throws IOException, IllegalArgumentException;

        public Object get(String name, Object default)
            throws IOException, IllegalArgumentException;
    }

    protected ObjectInputStream()
        throws StreamCorruptedException, IOException;

    protected readObjectOverride()
        throws OptionalDataException, ClassNotFoundException,
            IOException;
}
The single-argument ObjectInputStream constructor requires an InputStream. The constructor calls readStreamHeader to read and verifies the header and version written by the corresponding ObjectOutputStream.writeStreamHeader method. If a security manager is installed, this constructor checks for the "enableSubclassImplementation" SerializablePermission when invoked directly or indirectly by the constructor of a subclass which overrides the readFields and/or readUnshared methods.

Note - The ObjectInputStream constructor blocks until it completes reading the serialization stream header. Code which waits for an ObjectInputStream to be constructed before creating the corresponding ObjectOutputStream for that stream will deadlock, since the ObjectInputStream constructor will block until a header is written to the stream, and the header will not be written to the stream until the ObjectOutputStream constructor executes. This problem can be resolved by creating the ObjectOutputStream before the ObjectInputStream, or otherwise removing the timing dependency between completion of ObjectInputStream construction and the creation of the ObjectOutputStream.
The readObject method is used to deserialize an object from the stream. It reads from the stream to reconstruct an object.

1. If the ObjectInputStream subclass is overriding the implementation, call the readObjectOverride method and return. Reimplementation is described at the end of this section.
2. If a block data record occurs in the stream, throw a BlockDataException with the number of available bytes.
3. If the object in the stream is null, return null.
4. If the object in the stream is a handle to a previous object, return the object.
5. If the object in the stream is a Class, read its ObjectStreamClass descriptor, add it and its handle to the set of known objects, and return the corresponding Class object.
6. If the object in the stream is an ObjectStreamClass, read in its data according to the formats described in section 4.3. Add it and its handle to the set of known objects. In versions 1.3 and later of the JavaTM 2 SDK, Standard Edition, the readClassDescriptor method is called to read in the ObjectStreamClass if it represents a class that is not a dynamic proxy class, as indicated in the stream data. If the class descriptor represents a dynamic proxy class, call the resolveProxyClass method on the stream to get the local class for the descriptor; otherwise, call the resolveClass method on the stream to get the local class. If the class cannot be resolved, throw a ClassNotFoundException. Return the resulting ObjectStreamClass object.
7. If the object in the stream is a String, read its length information followed by the contents of the string encoded in modified UTF-8. For details, refer to Section 6.2, "Stream Elements". Add the String and its handle to the set of known objects, and proceed to Step 12.
8. If the object in the stream is an array, read its ObjectStreamClass and the length of the array. Allocate the array, and add it and its handle in the set of known objects. Read each element using the appropriate method for its type and assign it to the array. Proceed to Step 12.
9. If the object in the stream is an enum constant, read its ObjectStreamClass and the enum constant name. If the ObjectStreamClass represents a class that is not an enum type, an InvalidClassException is thrown. Obtain a reference to the enum constant by calling the java.lang.Enum.valueOf method, passing the enum type bound to the received ObjectStreamClass along with the received name as arguments. If the valueOf method throws an IllegalArgumentException, an InvalidObjectException is thrown with the IllegalArgumentException as its cause. Add the enum constant and its handle in the set of known objects, and proceed to Step 12.
10. For all other objects, the ObjectStreamClass of the object is read from the stream. The local class for that ObjectStreamClass is retrieved. The class must be serializable or externalizable, and must not be an enum type. If the class does not satisfy these criteria, an InvalidClassException is thrown.
11. An instance of the class is allocated. The instance and its handle are added to the set of known objects. The contents restored appropriately:
a. For serializable objects, the no-arg constructor for the first non-serializable supertype is run. For serializable classes, the fields are initialized to the default value appropriate for its type. Then the fields of each class are restored by calling class-specific readObject methods, or if these are not defined, by calling the defaultReadObject method. Note that field initializers and constructors are not executed for serializable classes during deserialization. In the normal case, the version of the class that wrote the stream will be the same as the class reading the stream. In this case, all of the supertypes of the object in the stream will match the supertypes in the currently-loaded class. If the version of the class that wrote the stream had different supertypes than the loaded class, the ObjectInputStream must be more careful about restoring or initializing the state of the differing classes. It must step through the classes, matching the available data in the stream with the classes of the object being restored. Data for classes that occur in the stream, but do not occur in the object, is discarded. For classes that occur in the object, but not in the stream, the class fields are set to default values by default serialization.
b. For externalizable objects, the no-arg constructor for the class is run and then the readExternal method is called to restore the contents of the object.
12. Process potential substitutions by the class of the object and/or by a subclass of ObjectInputStream:
a. If the class of the object is not an enum type and defines the appropriate readResolve method, the method is called to allow the object to replace itself.
b. Then if previously enabled by enableResolveObject, the resolveObject method is called to allow subclasses of the stream to examine and replace the object. If the previous step did replace the original object, the resolveObject method is called with the replacement object.
If a replacement took place, the table of known objects is updated so the replacement object is associated with the handle. The replacement object is then returned from readObject.
All of the methods for reading primitives types only consume bytes from the block data records in the stream. If a read for primitive data occurs when the next item in the stream is an object, the read methods return -1 or the EOFException as appropriate. The value of a primitive type is read by a DataInputStream from the block data record.

The exceptions thrown reflect errors during the traversal or exceptions that occur on the underlying stream. If any exception is thrown, the underlying stream is left in an unknown and unusable state.

When the reset token occurs in the stream, all of the state of the stream is discarded. The set of known objects is cleared.

When the exception token occurs in the stream, the exception is read and a new WriteAbortedException is thrown with the terminating exception as an argument. The stream context is reset as described earlier.

The readUnshared method is used to read "unshared" objects from the stream. This method is identical to readObject, except that it prevents subsequent calls to readObject and readUnshared from returning additional references to the deserialized instance returned by the original call to readUnshared. Specifically:

  • If readUnshared is called to deserialize a back-reference (the stream representation of an object which has been written previously to the stream), an ObjectStreamException will be thrown.
  • If readUnshared returns successfully, then any subsequent attempts to deserialize back-references to the stream handle deserialized by readUnshared will cause an ObjectStreamException to be thrown.
Deserializing an object via readUnshared invalidates the stream handle associated with the returned object. Note that this in itself does not always guarantee that the reference returned by readUnshared is unique; the deserialized object may define a readResolve method which returns an object visible to other parties, or readUnshared may return a Class object or enum constant obtainable elsewhere in the stream or through external means. If the deserialized object defines a readResolve method and the invocation of that method returns an array, then readUnshared returns a shallow clone of that array; this guarantees that the returned array object is unique and cannot be obtained a second time from an invocation of readObject or readUnshared on the ObjectInputStream, even if the underlying data stream has been manipulated.

The defaultReadObject method is used to read the fields and object from the stream. It uses the class descriptor in the stream to read the fields in the canonical order by name and type from the stream. The values are assigned to the matching fields by name in the current class. Details of the versioning mechanism can be found in Section 5.5, "Compatible JavaTM Type Evolution." Any field of the object that does not appear in the stream is set to its default value. Values that appear in the stream, but not in the object, are discarded. This occurs primarily when a later version of a class has written additional fields that do not occur in the earlier version. This method may only be called from the readObject method while restoring the fields of a class. When called at any other time, the NotActiveException is thrown.

The readFields method reads the values of the serializable fields from the stream and makes them available via the GetField class. The readFields method is only callable from within the readObject method of a serializable class. It cannot be called more than once or if defaultReadObject has been called. The GetFields object uses the current object's ObjectStreamClass to verify the fields that can be retrieved for this class. The GetFields object returned by readFields is only valid during this call to the classes readObject method. The fields may be retrieved in any order. Additional data may only be read directly from stream after readFields has been called.

The registerValidation method can be called to request a callback when the entire graph has been restored but before the object is returned to the original caller of readObject. The order of validate callbacks can be controlled using the priority. Callbacks registered with higher values are called before those with lower values. The object to be validated must support the ObjectInputValidation interface and implement the validateObject method. It is only correct to register validations during a call to a class's readObject method. Otherwise, a NotActiveException is thrown. If the callback object supplied to registerValidation is null, an InvalidObjectException is thrown.

Starting with the JavaTM SDK, Standard Edition, v1.3, the readClassDescriptor method is used to read in all ObjectStreamClass objects. readClassDescriptor is called when the ObjectInputStream expects a class descriptor as the next item in the serialization stream. Subclasses of ObjectInputStream may override this method to read in class descriptors that have been written in non-standard formats (by subclasses of ObjectOutputStream which have overridden the writeClassDescriptor method). By default, this method reads class descriptors according to the format described in Section 6.4, "Grammar for the Stream Format".

The resolveClass method is called while a class is being deserialized, and after the class descriptor has been read. Subclasses may extend this method to read other information about the class written by the corresponding subclass of ObjectOutputStream. The method must find and return the class with the given name and serialVersionUID. The default implementation locates the class by calling the class loader of the closest caller of readObject that has a class loader. If the class cannot be found ClassNotFoundException should be thrown. Prior to JDKTM 1.1.6, the resolveClass method was required to return the same fully qualified class name as the class name in the stream. In order to accommodate package renaming across releases, method resolveClass only needs to return a class with the same base class name and SerialVersionUID in JDKTM 1.1.6 and later versions.

The resolveObject method is used by trusted subclasses to monitor or substitute one object for another during deserialization. Resolving objects must be enabled explicitly by calling enableResolveObject before calling readObject for the first object to be resolved. Once enabled, resolveObject is called once for each serializable object just prior to the first time it is being returned from readObject. Note that the resolveObject method is not called for objects of the specially handled classes, Class, ObjectStreamClass, String, and arrays. A subclass's implementation of resolveObject may return a substitute object that will be assigned or returned instead of the original. The object returned must be of a type that is consistent and assignable to every reference of the original object or else a ClassCastException will be thrown. All assignments are type-checked. All references in the stream to the original object will be replaced by references to the substitute object.

The enableResolveObject method is called by trusted subclasses of ObjectOutputStream to enable the monitoring or substitution of one object for another during deserialization. Replacing objects is disabled until enableResolveObject is called with a true value. It may thereafter be disabled by setting it to false. The previous setting is returned. The enableResolveObject method checks if the stream has permission to request substitution during serialization. To ensure that the private state of objects is not unintentionally exposed, only trusted streams may use resolveObject. Trusted classes are those classes with a class loader equal to null or belong to a security protection domain that provides permission to enable substitution.

If the subclass of ObjectInputStream is not considered part of the system domain, a line has to be added to the security policy file to provide to a subclass of ObjectInputStream permission to call enableResolveObject. The SerializablePermission to add is "enableSubstitution". AccessControlException is thrown if the protection domain of the subclass of ObjectStreamClass does not have permission to "enableSubstitution" by calling enableResolveObject. See the document JavaTM Security Architecture (JDKTM 1.2) for additional information about the security model.

The readStreamHeader method reads and verifies the magic number and version of the stream. If they do not match, the StreamCorruptedMismatch is thrown.

To override the implementation of deserialization, a subclass of ObjectInputStream should call the protected no-arg ObjectInputStream, constructor. There is a security check within the no-arg constructor for SerializablePermission "enableSubclassImplementation" to ensure that only trusted classes are allowed to override the default implementation. This constructor does not allocate any private data for ObjectInputStream and sets a flag that indicates that the final readObject method should invoke the readObjectOverride method and return. All other ObjectInputStream methods are not final and can be directly overridden by the subclass.

3.2 The ObjectInputStream.GetField Class

The class ObjectInputStream.GetField provides the API for getting the values of serializable fields. The protocol of the stream is the same as used by defaultReadObject. Using readFields to access the serializable fields does not change the format of the stream. It only provides an alternate API to access the values which does not require the class to have the corresponding non-transient and non-static fields for each named serializable field. The serializable fields are those declared using serialPersistentFields or if it is not declared the non-transient and non-static fields of the object. When the stream is read the available serializable fields are those written to the stream when the object was serialized. If the class that wrote the stream is a different version not all fields will correspond to the serializable fields of the current class. The available fields can be retrieved from the ObjectStreamClass of the GetField object.

The getObjectStreamClass method returns an ObjectStreamClass object representing the class in the stream. It contains the list of serializable fields.

The defaulted method returns true if the field is not present in the stream. An IllegalArgumentException is thrown if the requested field is not a serializable field of the current class.

Each get method returns the specified serializable field from the stream. I/O exceptions will be thrown if the underlying stream throws an exception. An IllegalArgumentException is thrown if the name or type does not match the name and type of an field serializable field of the current class. The default value is returned if the stream does not contain an explicit value for the field.

3.3 The ObjectInputValidation Interface

This interface allows an object to be called when a complete graph of objects has been deserialized. If the object cannot be made valid, it should throw the ObjectInvalidException. Any exception that occurs during a call to validateObject will terminate the validation process, and the InvalidObjectException will be thrown.

package java.io;

public interface ObjectInputValidation
{
    public void validateObject()
        throws InvalidObjectException;
}

3.4 The readObject Method

For serializable objects, the readObject method allows a class to control the deserialization of its own fields. Here is its signature:

    private void readObject(ObjectInputStream stream)
        throws IOException, ClassNotFoundException;
Each subclass of a serializable object may define its own readObject method. If a class does not implement the method, the default serialization provided by defaultReadObject will be used. When implemented, the class is only responsible for restoring its own fields, not those of its supertypes or subtypes.

The readObject method of the class, if implemented, is responsible for restoring the state of the class. The values of every field of the object whether transient or not, static or not are set to the default value for the fields type. Either ObjectInputStream's defaultReadObject or readFields method must be called once (and only once) before reading any optional data written by the corresponding writeObject method; even if no optional data is read, defaultReadObject or readFields must still be invoked once. If the readObject method of the class attempts to read more data than is present in the optional part of the stream for this class, the stream will return -1 for bytewise reads, throw an EOFException for primitive data reads (e.g., readInt, readFloat), or throw an OptionalDataException with the eof field set to true for object reads.

The responsibility for the format, structure, and versioning of the optional data lies completely with the class. The @serialData javadoc tag within the javadoc comment for the readObject method should be used to document the format and structure of the optional data.

If the class being restored is not present in the stream being read, then its readObjectNoData method, if defined, is invoked (instead of readObject); otherwise, its fields are initialized to the appropriate default values. For further detail, see section 3.5.

Reading an object from the ObjectInputStream is analogous to creating a new object. Just as a new object's constructors are invoked in the order from the superclass to the subclass, an object being read from a stream is deserialized from superclass to subclass. The readObject or readObjectNoData method is called instead of the constructor for each Serializable subclass during deserialization.

One last similarity between a constructor and a readObject method is that both provide the opportunity to invoke a method on an object that is not fully constructed. Any overridable (neither private, static nor final) method called while an object is being constructed can potentially be overridden by a subclass. Methods called during the construction phase of an object are resolved by the actual type of the object, not the type currently being initialized by either its constructor or readObject/readObjectNoData method. Therefore, calling an overridable method from within a readObject or readObjectNoData method may result in the unintentional invocation of a subclass method before the superclass has been fully initialized.

3.5 The readObjectNoData Method

For serializable objects, the readObjectNoData method allows a class to control the initialization of its own fields in the event that a subclass instance is deserialized and the serialization stream does not list the class in question as a superclass of the deserialized object. This may occur in cases where the receiving party uses a different version of the deserialized instance's class than the sending party, and the receiver's version extends classes that are not extended by the sender's version. This may also occur if the serialization stream has been tampered; hence, readObjectNoData is useful for initializing deserialized objects properly despite a "hostile" or incomplete source stream.

  private void readObjectNoData() throws ObjectStreamException;
Each serializable class may define its own readObjectNoData method. If a serializable class does not define a readObjectNoData method, then in the circumstances listed above the fields of the class will be initialized to their default values (as listed in section 4.5.5 of The JavaTM Language Specification, Second Edition); this behavior is consistent with that of ObjectInputStream prior to version 1.4 of the JavaTM 2 SDK, Standard Edition, when support for readObjectNoData methods was introduced. If a serializable class does define a readObjectNoData method and the aforementioned conditions arise, then readObjectNoData will be invoked at the point during deserialization when a class-defined readObject method would otherwise be called had the class in question been listed by the stream as a superclass of the instance being deserialized.

3.6 The readExternal Method

Objects implementing java.io.Externalizable must implement the readExternal method to restore the entire state of the object. It must coordinate with its superclasses to restore their state. All of the methods of ObjectInput are available to restore the object's primitive typed fields and object fields.

    public void readExternal(ObjectInput stream)
        throws IOException;
Note - The readExternal method is public, and it raises the risk of a client being able to overwrite an existing object from a stream. The class may add its own checks to insure that this is only called when appropriate.
A new stream protocol version has been introduced in JDKTM 1.2 to correct a problem with Externalizable objects. The old definition of Externalizable objects required the local virtual machine to find a readExternal method to be able to properly read an Externalizable object from the stream. The new format adds enough information to the stream protocol so serialization can skip an Externalizable object when the local readExternal method is not available. Due to class evolution rules, serialization must be able to skip an Externalizable object in the input stream if there is not a mapping for the object using the local classes.

An additional benefit of the new Externalizable stream format is that ObjectInputStream can detect attempts to read more External data than is available, and can also skip by any data that is left unconsumed by a readExternal method. The behavior of ObjectInputStream in response to a read past the end of External data is the same as the behavior when a class-defined readObject method attempts to read past the end of its optional data: bytewise reads will return -1, primitive reads will throw EOFExceptions, and object reads will throw OptionalDataExceptions with the eof field set to true.

Due to the format change, JDKTM 1.1.6 and earlier releases are not able to read the new format. StreamCorruptedException is thrown when JDKTM 1.1.6 or earlier attempts to read an Externalizable object from a stream written in PROTOCOL_VERSION_2. Compatibility issues are discussed in more detail in Section 6.3, "Stream Protocol Versions."

3.7 The readResolve Method

For Serializable and Externalizable classes, the readResolve method allows a class to replace/resolve the object read from the stream before it is returned to the caller. By implementing the readResolve method, a class can directly control the types and instances of its own instances being deserialized. The method is defined as follows:

    ANY-ACCESS-MODIFIER Object readResolve()
            throws ObjectStreamException;
The readResolve method is called when ObjectInputStream has read an object from the stream and is preparing to return it to the caller. ObjectInputStream checks whether the class of the object defines the readResolve method. If the method is defined, the readResolve method is called to allow the object in the stream to designate the object to be returned. The object returned should be of a type that is compatible with all uses. If it is not compatible, a ClassCastException will be thrown when the type mismatch is discovered.

For example, a Symbol class could be created for which only a single instance of each symbol binding existed within a virtual machine. The readResolve method would be implemented to determine if that symbol was already defined and substitute the preexisting equivalent Symbol object to maintain the identity constraint. In this way the uniqueness of Symbol objects can be maintained across serialization.

Note - The readResolve method is not invoked on the object until the object is fully constructed, so any references to this object in its object graph will not be updated to the new object nominated by readResolve. However, during the serialization of an object with the writeReplace method, all references to the original object in the replacement object's object graph are replaced with references to the replacement object. Therefore in cases where an object being serialized nominates a replacement object whose object graph has a reference to the original object, deserialization will result in an incorrect graph of objects. Furthermore, if the reference types of the object being read (nominated by writeReplace) and the original object are not compatible, the construction of the object graph will raise a ClassCastException.

CONTENTS | PREV | NEXT
Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved.


4 - Class Descriptors

CONTENTS | PREV | NEXT Java Object Serialization Specification
version 6.0

Class Descriptors

CHAPTER 4

Topics:

  • The ObjectStreamClass Class
  • Dynamic Proxy Class Descriptors
  • Serialized Form
  • The ObjectStreamField Class
  • Inspecting Serializable Classes
  • Stream Unique Identifiers

4.1 The ObjectStreamClass Class

The ObjectStreamClass provides information about classes that are saved in a Serialization stream. The descriptor provides the fully-qualified name of the class and its serialization version UID. A SerialVersionUID identifies the unique original class version for which this class is capable of writing streams and from which it can read.

package java.io;

public class ObjectStreamClass
{
    public static ObjectStreamClass lookup(Class cl);

    public static ObjectStreamClass lookupAny(Class cl);

    public String getName();

    public Class forClass();

    public ObjectStreamField[] getFields();

    public long getSerialVersionUID();

    public String toString();
}
The lookup method returns the ObjectStreamClass descriptor for the specified class in the virtual machine. If the class has defined serialVersionUID it is retrieved from the class. If the serialVersionUID is not defined by the class, it is computed from the definition of the class in the virtual machine. If the specified class is not serializable or externalizable, null is returned.

The lookupAny method behaves like the lookup method, except that it returns the descriptor for any class, regardless of whether it implements Serializable. The serialVersionUID of a class that does not implement Serializable is 0L.

The getName method returns the name of the class, in the same format that is used by the Class.getName method.

The forClass method returns the Class in the local virtual machine if one was found by ObjectInputStream.resolveClass method. Otherwise, it returns null.

The getFields method returns an array of ObjectStreamField objects that represent the serializable fields of this class.

The getSerialVersionUID method returns the serialVersionUID of this class. Refer to Section 4.6, "Stream Unique Identifiers." If not specified by the class, the value returned is a hash computed from the class's name, interfaces, methods, and fields using the Secure Hash Algorithm (SHA) as defined by the National Institute of Standards.

The toString method returns a printable representation of the class descriptor including the name of the class and the serialVersionUID.

4.2 Dynamic Proxy Class Descriptors

ObjectStreamClass descriptors are also used to provide information about dynamic proxy classes (e.g., classes obtained via calls to the getProxyClass method of java.lang.reflect.Proxy) saved in a serialization stream. A dynamic proxy class itself has no serializable fields and a serialVersionUID of 0L. In other words, when the Class object for a dynamic proxy class is passed to the static lookup method of ObjectStreamClass, the returned ObjectStreamClass instance will have the following properties:

  • Invoking its getSerialVersionUID method will return 0L.
  • Invoking its getFields method will return an array of length zero.
  • Invoking its getField method with any String argument will return null.

4.3 Serialized Form

The serialized form of an ObjectStreamClass instance depends on whether or not the Class object it represents is serializable, externalizable, or a dynamic proxy class.

When an ObjectStreamClass instance that does not represent a dynamic proxy class is written to the stream, it writes the class name and serialVersionUID, flags, and the number of fields. Depending on the class, additional information may be written:

  • For non-serializable classes, the number of fields is always zero. Neither the SC_SERIALIZABLE nor the SC_EXTERNALIZABLE flag bits are set.
  • For serializable classes, the SC_SERIALIZABLE flag is set, the number of fields counts the number of serializable fields and is followed by a descriptor for each serializable field. The descriptors are written in canonical order. The descriptors for primitive typed fields are written first sorted by field name followed by descriptors for the object typed fields sorted by field name. The names are sorted using String.compareTo. For details of the format, refer to Section 6.4, "Grammar for the Stream Format".
  • For externalizable classes, flags includes the SC_EXTERNALIZABLE flag, and the number of fields is always zero.
  • For enum types, flags includes the SC_ENUM flag, and the number of fields is always zero.
When an ObjectOutputStream serializes the ObjectStreamClass descriptor for a dynamic proxy class, as determined by passing its Class object to the isProxyClass method of java.lang.reflect.Proxy, it writes the number of interfaces that the dynamic proxy class implements, followed by the interface names. Interfaces are listed in the order that they are returned by invoking the getInterfaces method on the Class object of the dynamic proxy class.

The serialized representations of ObjectStreamClass descriptors for dynamic proxy classes and non-dynamic proxy classes are differentiated through the use of different typecodes (TC_PROXYCLASSDESC and TC_CLASSDESC, respectively); for a more detailed specification of the grammar, see Section 6.4, "Grammar for the Stream Format".

4.4 The ObjectStreamField Class

An ObjectStreamField represents a serializable field of a serializable class. The serializable fields of a class can be retrieved from the ObjectStreamClass.

The special static serializable field, serialPersistentFields, is an array of ObjectStreamField components that is used to override the default serializable fields.

package java.io;

public class ObjectStreamField implements Comparable {

    public ObjectStreamField(String fieldName,
                             Class fieldType);

    public ObjectStreamField(String fieldName,
                             Class fieldType,
                             boolean unshared);

    public String getName();

    public Class getType();

    public String getTypeString();

    public char getTypeCode();

    public boolean isPrimitive();

    public boolean isUnshared();

    public int getOffset();

    protected void setOffset(int offset);

    public int compareTo(Object obj);

    public String toString();
}
ObjectStreamField objects are used to specify the serializable fields of a class or to describe the fields present in a stream. Its constructors accept arguments describing the field to represent: a string specifying the name of the field, a Class object specifying the type of the field, and a boolean flag (implicitly false for the two-argument constructor) indicating whether or not values of the represented field should be read and written as "unshared" objects if default serialization/deserialization is in use (see the descriptions of the ObjectInputStream.readUnshared and ObjectOutputStream.writeUnshared methods in sections 3.1 and 2.1, respectively).

The getName method returns the name of the serializable field.

The getType method returns the type of the field.

The getTypeString method returns the type signature of the field.

The getTypeCode method returns a character encoding of the field type (`B' for byte, `C' for char, `D' for double, `F' for float, `I' for int, `J' for long, `L' for non-array object types, `S' for short, `Z' for boolean, and `[` for arrays).

The isPrimitive method returns true if the field is of primitive type, or false otherwise.

The isUnshared method returns true if values of the field should be written as "unshared" objects, or false otherwise.

The getOffset method returns the offset of the field's value within instance data of the class defining the field.

The setOffset method allows ObjectStreamField subclasses to modify the offset value returned by the getOffset method.

The compareTo method compares ObjectStreamFields for use in sorting. Primitive fields are ranked as "smaller" than non-primitive fields; fields otherwise equal are ranked alphabetically.

The toString method returns a printable representation with name and type.

4.5 Inspecting Serializable Classes

The program serialver can be used to find out if a class is serializable and to get its serialVersionUID. When invoked with the-show option, it puts up a simple user interface. To find out if a class is serializable and to find out its serialVersionUID, enter its full class name, then press either the Enter or the Show button. The string printed can be copied and pasted into the evolved class.

When invoked on the command line with one or more class names, serialver prints the serialVersionUID for each class in a form suitable for copying into an evolving class. When invoked with no arguments, it prints a usage line.

4.6 Stream Unique Identifiers

Each versioned class must identify the original class version for which it is capable of writing streams and from which it can read. For example, a versioned class must declare:

    private static final long serialVersionUID = 3487495895819393L;
The stream-unique identifier is a 64-bit hash of the class name, interface class names, methods, and fields. The value must be declared in all versions of a class except the first. It may be declared in the original class but is not required. The value is fixed for all compatible classes. If the SUID is not declared for a class, the value defaults to the hash for that class. The serialVersionUID for dynamic proxy classes and enum types always have the value 0L. Array classes cannot declare an explicit serialVersionUID, so they always have the default computed value, but the requirement for matching serialVersionUID values is waived for array classes.

Note - It is strongly recommended that all serializable classes explicitly declare serialVersionUID values, since the default serialVersionUID computation is highly sensitive to class details that may vary depending on compiler implementations, and can thus result in unexpected serialVersionUID conflicts during deserialization, causing deserialization to fail.
The initial version of an Externalizable class must output a stream data format that is extensible in the future. The initial version of the method readExternal has to be able to read the output format of all future versions of the method writeExternal.

The serialVersionUID is computed using the signature of a stream of bytes that reflect the class definition. The National Institute of Standards and Technology (NIST) Secure Hash Algorithm (SHA-1) is used to compute a signature for the stream. The first two 32-bit quantities are used to form a 64-bit hash. A java.lang.DataOutputStream is used to convert primitive data types to a sequence of bytes. The values input to the stream are defined by the JavaTM Virtual Machine (VM) specification for classes. Class modifiers may include the ACC_PUBLIC, ACC_FINAL, ACC_INTERFACE, and ACC_ABSTRACT flags; other flags are ignored and do not affect serialVersionUID computation. Similarly, for field modifiers, only the ACC_PUBLIC, ACC_PRIVATE, ACC_PROTECTED, ACC_STATIC, ACC_FINAL, ACC_VOLATILE, and ACC_TRANSIENT flags are used when computing serialVersionUID values. For constructor and method modifiers, only the ACC_PUBLIC, ACC_PRIVATE, ACC_PROTECTED, ACC_STATIC, ACC_FINAL, ACC_SYNCHRONIZED, ACC_NATIVE, ACC_ABSTRACT and ACC_STRICT flags are used. Names and descriptors are written in the format used by the java.io.DataOutputStream.writeUTF method.

The sequence of items in the stream is as follows:

  1. The class name.
  2. The class modifiers written as a 32-bit integer.
  3. The name of each interface sorted by name.
  4. For each field of the class sorted by field name (except private static and private transient fields:
    1. The name of the field.
    2. The modifiers of the field written as a 32-bit integer.
    3. The descriptor of the field.
  5. If a class initializer exists, write out the following:
    1. The name of the method, <clinit>.
    2. The modifier of the method, java.lang.reflect.Modifier.STATIC, written as a 32-bit integer.
    3. The descriptor of the method, ()V.
  6. For each non-private constructor sorted by method name and signature:
    1. The name of the method, <init>.
    2. The modifiers of the method written as a 32-bit integer.
    3. The descriptor of the method.
  7. For each non-private method sorted by method name and signature:
    1. The name of the method.
    2. The modifiers of the method written as a 32-bit integer.
    3. The descriptor of the method.
  8. The SHA-1 algorithm is executed on the stream of bytes produced by DataOutputStream and produces five 32-bit values sha[0..4].
  9. The hash value is assembled from the first and second 32-bit values of the SHA-1 message digest. If the result of the message digest, the five 32-bit words H0 H1 H2 H3 H4, is in an array of five int values named sha, the hash value would be computed as follows:
      long hash = ((sha[0] >>> 24) & 0xFF) |
          ((sha[0] >>> 16) & 0xFF) << 8 |
          ((sha[0] >>> 8) & 0xFF) << 16 |
          ((sha[0] >>> 0) & 0xFF) << 24 |
          ((sha[1] >>> 24) & 0xFF) << 32 |
          ((sha[1] >>> 16) & 0xFF) << 40 |
          ((sha[1] >>> 8) & 0xFF) << 48 |
          ((sha[1] >>> 0) & 0xFF) << 56;

CONTENTS | PREV | NEXT
Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved.


5 - Versioning of Serializable Objects

CONTENTS | PREV | NEXT Java Object Serialization Specification
version 6.0

Versioning of Serializable Objects

CHAPTER 5

Topics:

  • Overview
  • Goals
  • Assumptions
  • Who's Responsible for Versioning of Streams
  • Compatible JavaTM Type Evolution
  • Type Changes Affecting Serialization

5.1 Overview

When JavaTM objects use serialization to save state in files, or as blobs in databases, the potential arises that the version of a class reading the data is different than the version that wrote the data.

Versioning raises some fundamental questions about the identity of a class, including what constitutes a compatible change. A compatible change is a change that does not affect the contract between the class and its callers.

This section describes the goals, assumptions, and a solution that attempts to address this problem by restricting the kinds of changes allowed and by carefully choosing the mechanisms.

The proposed solution provides a mechanism for "automatic" handling of classes that evolve by adding fields and adding classes. Serialization will handle versioning without class-specific methods to be implemented for each version. The stream format can be traversed without invoking class-specific methods.

5.2 Goals

The goals are to:

  • Support bidirectional communication between different versions of a class operating in different virtual machines by:
    • Defining a mechanism that allows JavaTM classes to read streams written by older versions of the same class.
    • Defining a mechanism that allows JavaTM classes to write streams intended to be read by older versions of the same class.
  • Provide default serialization for persistence and for RMI.
  • Perform well and produce compact streams in simple cases, so that RMI can use serialization.
  • Be able to identify and load classes that match the exact class used to write the stream.
  • Keep the overhead low for nonversioned classes.
  • Use a stream format that allows the traversal of the stream without having to invoke methods specific to the objects saved in the stream.

5.3 Assumptions

The assumptions are that:

  • Versioning will only apply to serializable classes since it must control the stream format to achieve it goals. Externalizable classes will be responsible for their own versioning which is tied to the external format.
  • All data and objects must be read from, or skipped in, the stream in the same order as they were written.
  • Classes evolve individually as well as in concert with supertypes and subtypes.
  • Classes are identified by name. Two classes with the same name may be different versions or completely different classes that can be distinguished only by comparing their interfaces or by comparing hashes of the interfaces.
  • Default serialization will not perform any type conversions.
  • The stream format only needs to support a linear sequence of type changes, not arbitrary branching of a type.

5.4 Who's Responsible for Versioning of Streams

In the evolution of classes, it is the responsibility of the evolved (later version) class to maintain the contract established by the nonevolved class. This takes two forms. First, the evolved class must not break the existing assumptions about the interface provided by the original version, so that the evolved class can be used in place of the original. Secondly, when communicating with the original (or previous) versions, the evolved class must provide sufficient and equivalent information to allow the earlier version to continue to satisfy the nonevolved contract.

For the purposes of the discussion here, each class implements and extends the interface or contract defined by its supertype. New versions of a class, for example foo', must continue to satisfy the contract for foo and may extend the interface or modify its implementation.

Communication between objects via serialization is not part of the contract defined by these interfaces. Serialization is a private protocol between the implementations. It is the responsibility of the implementations to communicate sufficiently to allow each implementation to continue to satisfy the contract expected by its clients.

5.5 Compatible JavaTM Type Evolution

In the JavaTM Language Specification, Chapter 13 discusses binary compatibility of JavaTM classes as those classes evolve. Most of the flexibility of binary compatibility comes from the use of late binding of symbolic references for the names of classes, interfaces, fields, methods, and so on.

The following are the principle aspects of the design for versioning of serialized object streams.

  • The default serialization mechanism will use a symbolic model for binding the fields in the stream to the fields in the corresponding class in the virtual machine.
  • Each class referenced in the stream will uniquely identify itself, its supertype, and the types and names of each serializable field written to the stream. The fields are ordered with the primitive types first sorted by field name, followed by the object fields sorted by field name.
  • Two types of data may occur in the stream for each class: required data (corresponding directly to the serializable fields of the object); and optional data (consisting of an arbitrary sequence of primitives and objects). The stream format defines how the required and optional data occur in the stream so that the whole class, the required, or the optional parts can be skipped if necessary.
    • The required data consists of the fields of the object in the order defined by the class descriptor.
    • The optional data is written to the stream and does not correspond directly to fields of the class. The class itself is responsible for the length, types, and versioning of this optional information.
  • If defined for a class, the writeObject/readObject methods supersede the default mechanism to write/read the state of the class. These methods write and read the optional data for a class. The required data is written by calling defaultWriteObject and read by calling defaultReadObject.
  • The stream format of each class is identified by the use of a Stream Unique Identifier (SUID). By default, this is the hash of the class. All later versions of the class must declare the Stream Unique Identifier (SUID) that they are compatible with. This guards against classes with the same name that might inadvertently be identified as being versions of a single class.
  • Subtypes of ObjectOutputStream and ObjectInputStream may include their own information identifying the class using the annotateClass method; for example, MarshalOutputStream embeds the URL of the class.

5.6 Type Changes Affecting Serialization

With these concepts, we can now describe how the design will cope with the different cases of an evolving class. The cases are described in terms of a stream written by some version of a class. When the stream is read back by the same version of the class, there is no loss of information or functionality. The stream is the only source of information about the original class. Its class descriptions, while a subset of the original class description, are sufficient to match up the data in the stream with the version of the class being reconstituted.

The descriptions are from the perspective of the stream being read in order to reconstitute either an earlier or later version of the class. In the parlance of RPC systems, this is a "receiver makes right" system. The writer writes its data in the most suitable form and the receiver must interpret that information to extract the parts it needs and to fill in the parts that are not available.

5.6.1 Incompatible Changes

Incompatible changes to classes are those changes for which the guarantee of interoperability cannot be maintained. The incompatible changes that may occur while evolving a class are:

  • Deleting fields - If a field is deleted in a class, the stream written will not contain its value. When the stream is read by an earlier class, the value of the field will be set to the default value because no value is available in the stream. However, this default value may adversely impair the ability of the earlier version to fulfill its contract.
  • Moving classes up or down the hierarchy - This cannot be allowed since the data in the stream appears in the wrong sequence.
  • Changing a nonstatic field to static or a nontransient field to transient - When relying on default serialization, this change is equivalent to deleting a field from the class. This version of the class will not write that data to the stream, so it will not be available to be read by earlier versions of the class. As when deleting a field, the field of the earlier version will be initialized to the default value, which can cause the class to fail in unexpected ways.
  • Changing the declared type of a primitive field - Each version of the class writes the data with its declared type. Earlier versions of the class attempting to read the field will fail because the type of the data in the stream does not match the type of the field.
  • Changing the writeObject or readObject method so that it no longer writes or reads the default field data or changing it so that it attempts to write it or read it when the previous version did not. The default field data must consistently either appear or not appear in the stream.
  • Changing a class from Serializable to Externalizable or vice versa is an incompatible change since the stream will contain data that is incompatible with the implementation of the available class.
  • Changing a class from a non-enum type to an enum type or vice versa since the stream will contain data that is incompatible with the implementation of the available class.
  • Removing either Serializable or Externalizable is an incompatible change since when written it will no longer supply the fields needed by older versions of the class.
  • Adding the writeReplace or readResolve method to a class is incompatible if the behavior would produce an object that is incompatible with any older version of the class.

5.6.2 Compatible Changes

The compatible changes to a class are handled as follows:

  • Adding fields - When the class being reconstituted has a field that does not occur in the stream, that field in the object will be initialized to the default value for its type. If class-specific initialization is needed, the class may provide a readObject method that can initialize the field to nondefault values.
  • Adding classes - The stream will contain the type hierarchy of each object in the stream. Comparing this hierarchy in the stream with the current class can detect additional classes. Since there is no information in the stream from which to initialize the object, the class's fields will be initialized to the default values.
  • Removing classes - Comparing the class hierarchy in the stream with that of the current class can detect that a class has been deleted. In this case, the fields and objects corresponding to that class are read from the stream. Primitive fields are discarded, but the objects referenced by the deleted class are created, since they may be referred to later in the stream. They will be garbage-collected when the stream is garbage-collected or reset.
  • Adding writeObject/readObject methods - If the version reading the stream has these methods then readObject is expected, as usual, to read the required data written to the stream by the default serialization. It should call defaultReadObject first before reading any optional data. The writeObject method is expected as usual to call defaultWriteObject to write the required data and then may write optional data.
  • Removing writeObject/readObject methods - If the class reading the stream does not have these methods, the required data will be read by default serialization, and the optional data will be discarded.
  • Adding java.io.Serializable - This is equivalent to adding types. There will be no values in the stream for this class so its fields will be initialized to default values. The support for subclassing nonserializable classes requires that the class's supertype have a no-arg constructor and the class itself will be initialized to default values. If the no-arg constructor is not available, the InvalidClassException is thrown.
  • Changing the access to a field - The access modifiers public, package, protected, and private have no effect on the ability of serialization to assign values to the fields.
  • Changing a field from static to nonstatic or transient to nontransient - When relying on default serialization to compute the serializable fields, this change is equivalent to adding a field to the class. The new field will be written to the stream but earlier classes will ignore the value since serialization will not assign values to static or transient fields.
    •

 CONTENTS | PREV
 | NEXT

Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved.


6 - Object Serialization Stream Protocol

CONTENTS | PREV | NEXT Java Object Serialization Specification
version 6.0

Object Serialization Stream Protocol

CHAPTER 6

Topics:

  • Overview
  • Stream Elements
  • Stream Protocol Versions
  • Grammar for the Stream Format
  • Example

6.1 Overview

The stream format satisfies the following design goals:

  • Is compact and is structured for efficient reading.
  • Allows skipping through the stream using only the knowledge of the structure and format of the stream. Does not require invoking any per class code.
  • Requires only stream access to the data.

6.2 Stream Elements

A basic structure is needed to represent objects in a stream. Each attribute of the object needs to be represented: its classes, its fields, and data written and later read by class-specific methods. The representation of objects in the stream can be described with a grammar. There are special representations for null objects, new objects, classes, arrays, strings, and back references to any object already in the stream. Each object written to the stream is assigned a handle that is used to refer back to the object. Handles are assigned sequentially starting from 0x7E0000. The handles restart at 0x7E0000 when the stream is reset.

A class object is represented by the following:

  • Its ObjectStreamClass object.
An ObjectStreamClass object for a Class that is not a dynamic proxy class is represented by the following:

  • The Stream Unique Identifier (SUID) of compatible classes.
  • A set of flags indicating various properties of the class, such as whether the class defines a writeObject method, and whether the class is serializable, externalizable, or an enum type
  • The number of serializable fields
  • The array of fields of the class that are serialized by the default mechanismFor arrays and object fields, the type of the field is included as a string which must be in "field descriptor" format (e.g., "Ljava/lang/Object;") as specified in section 4.3.2 of The JavaTM Virtual Machine Specification, Second Edition.
  • Optional block-data records or objects written by the annotateClass method
  • The ObjectStreamClass of its supertype (null if the superclass is not serializable)
An ObjectStreamClass object for a dynamic proxy class is represented by the following:

  • The number of interfaces that the dynamic proxy class implements
  • The names of all of the interfaces implemented by the dynamic proxy class, listed in the order that they are returned by invoking the getInterfaces method on the Class object.
  • Optional block-data records or objects written by the annotateProxyClass method.
  • The ObjectStreamClass of its supertype, java.lang.reflect.Proxy.
The representation of String objects consists of length information followed by the contents of the string encoded in modified UTF-8. The modified UTF-8 encoding is the same as used in the JavaTM Virtual Machine and in the java.io.DataInput and DataOutput interfaces; it differs from standard UTF-8 in the representation of supplementary characters and of the null character. The form of the length information depends on the length of the string in modified UTF-8 encoding. If the modified UTF-8 encoding of the given String is less than 65536 bytes in length, the length is written as 2 bytes representing an unsigned 16-bit integer. Starting with the JavaTM 2 platform, Standard Edition, v1.3, if the length of the string in modified UTF-8 encoding is 65536 bytes or more, the length is written in 8 bytes representing a signed 64-bit integer. The typecode preceding the String in the serialization stream indicates which format was used to write the String.

Arrays are represented by the following:

  • Their ObjectStreamClass object.
  • The number of elements.
  • The sequence of values. The type of the values is implicit in the type of the array. for example the values of a byte array are of type byte.
Enum constants are represented by the following:

  • The ObjectStreamClass object of the constant's base enum type.
  • The constant's name string.
New objects in the stream are represented by the following:

  • The most derived class of the object.
  • Data for each serializable class of the object, with the highest superclass first.For each class the stream contains the following:
  • The serializable fields.See Section 1.5, "Defining Serializable Fields for a Class."
  • If the class has writeObject/readObject methods, there may be optional objects and/or block-data records of primitive types written by the writeObject method followed by an endBlockData code.
All primitive data written by classes is buffered and wrapped in block-data records, regardless if the data is written to the stream within a writeObject method or written directly to the stream from outside a writeObject method. This data can only be read by the corresponding readObject methods or be read directly from the stream. Objects written by the writeObject method terminate any previous block-data record and are written either as regular objects or null or back references, as appropriate. The block-data records allow error recovery to discard any optional data. When called from within a class, the stream can discard any data or objects until the endBlockData.

6.3 Stream Protocol Versions

It was necessary to make a change to the serialization stream format in JDKTM 1.2 that is not backwards compatible to all minor releases of JDKTM 1.1. To provide for cases where backwards compatibility is required, a capability has been added to indicate what PROTOCOL_VERSION to use when writing a serialization stream. The method ObjectOutputStream.useProtocolVersion takes as a parameter the protocol version to use to write the serialization stream.

The Stream Protocol Versions are as follows:

  • ObjectStreamConstants.PROTOCOL_VERSION_1
Indicates the initial stream format.
  • ObjectStreamConstants.PROTOCOL_VERSION_2
Indicates the new external data format. Primitive data is written in block data mode and is terminated with TC_ENDBLOCKDATA.
Block data boundaries have been standardized. Primitive data written in block data mode is normalized to not exceed 1024 byte chunks. The benefit of this change was to tighten the specification of serialized data format within the stream. This change is fully backward and forward compatible.
JDKTM 1.2 defaults to writing PROTOCOL_VERSION_2.

JDKTM 1.1 defaults to writing PROTOCOL_VERSION_1.

JDKTM 1.1.7 and greater can read both versions.

Releases prior to JDKTM 1.1.7 can only read PROTOCOL_VERSION_1.

6.4 Grammar for the Stream Format

The table below contains the grammar for the stream format. Nonterminal symbols are shown in italics. Terminal symbols in a fixed width font. Definitions of nonterminals are followed by a ":". The definition is followed by one or more alternatives, each on a separate line. The following table describes the notation:

Notation
 Meaning

(datatype)

This token has the data type specified, such as byte.

token[n]

A predefined number of occurrences of the token, that is an array.

x0001

A literal value expressed in hexadecimal. The number of hex digits reflects the size of the value.

<xxx>

A value read from the stream used to indicate the length of an array.

Note that the symbol (utf) is used to designate a string written using 2-byte length information, and (long-utf) is used to designate a string written using 8-byte length information. For details, refer to Section 6.2, "Stream Elements".

6.4.1 Rules of the Grammar

A Serialized stream is represented by any stream satisfying the stream rule.

stream:
  magic version contents

contents:
  content
  contents content

content:
  object
  blockdata

object:
  newObject
  newClass
  newArray
  newString
  newEnum
  newClassDesc
  prevObject
  nullReference
  exception
  TC_RESET

newClass:
  TC_CLASS classDesc newHandle

classDesc:
  newClassDesc
  nullReference
  (ClassDesc)prevObject      // an object required to be of type
                             // ClassDesc

superClassDesc:
  classDesc

newClassDesc:
  TC_CLASSDESC className serialVersionUID newHandle classDescInfo
  TC_PROXYCLASSDESC newHandle proxyClassDescInfo

classDescInfo:
  classDescFlags fields classAnnotation superClassDesc

className:
  (utf)

serialVersionUID:
  (long)

classDescFlags:
  (byte)                  // Defined in Terminal Symbols and
                            // Constants

proxyClassDescInfo:
  (int)<count> proxyInterfaceName[count] classAnnotation
      superClassDesc

proxyInterfaceName:

  (utf)

fields:
  (short)<count>  fieldDesc[count]

fieldDesc:
  primitiveDesc
  objectDesc

primitiveDesc:
  prim_typecode fieldName

objectDesc:
  obj_typecode fieldName className1

fieldName:
  (utf)

className1:
  (String)object             // String containing the field's type,
                             // in field descriptor format

classAnnotation:
  endBlockData
  contents endBlockData      // contents written by annotateClass

prim_typecode:
  `B'	// byte
  `C'	// char
  `D'	// double
  `F'	// float
  `I'	// integer
  `J'	// long
  `S'	// short
  `Z'	// boolean

obj_typecode:
  `[`	// array
  `L'	// object

newArray:
  TC_ARRAY classDesc newHandle (int)<size> values[size]

newObject:
  TC_OBJECT classDesc newHandle classdata[]  // data for each class

classdata:
  nowrclass                 // SC_SERIALIZABLE & classDescFlag &&
                            // !(SC_WRITE_METHOD & classDescFlags)
  wrclass objectAnnotation  // SC_SERIALIZABLE & classDescFlag &&
                            // SC_WRITE_METHOD & classDescFlags
  externalContents          // SC_EXTERNALIZABLE & classDescFlag &&
                            // !(SC_BLOCKDATA  & classDescFlags
  objectAnnotation          // SC_EXTERNALIZABLE & classDescFlag&&
                            // SC_BLOCKDATA & classDescFlags

nowrclass:
  values                    // fields in order of class descriptor

wrclass:
  nowrclass

objectAnnotation:
  endBlockData
  contents endBlockData     // contents written by writeObject
                            // or writeExternal PROTOCOL_VERSION_2.

blockdata:
  blockdatashort
  blockdatalong

blockdatashort:
  TC_BLOCKDATA (unsigned byte)<size> (byte)[size]

blockdatalong:
  TC_BLOCKDATALONG (int)<size> (byte)[size]

endBlockData	:
  TC_ENDBLOCKDATA

externalContent:          // Only parseable by readExternal
  ( bytes)                // primitive data
    object

externalContents:         // externalContent written by
  externalContent         // writeExternal in PROTOCOL_VERSION_1.
  externalContents externalContent

newString:
  TC_STRING newHandle (utf)
  TC_LONGSTRING newHandle (long-utf)

newEnum:
  TC_ENUM classDesc newHandle enumConstantName

enumConstantName:
  (String)object

prevObject
  TC_REFERENCE (int)handle

nullReference
  TC_NULL

exception:
  TC_EXCEPTION reset (Throwable)object	 reset

magic:
  STREAM_MAGIC

version
  STREAM_VERSION

values:          // The size and types are described by the
                 // classDesc for the current object

newHandle:       // The next number in sequence is assigned
                 // to the object being serialized or deserialized

reset:           // The set of known objects is discarded
                 // so the objects of the exception do not
                 // overlap with the previously sent objects
                 // or with objects that may be sent after
                 // the exception

6.4.2 Terminal Symbols and Constants

The following symbols in java.io.ObjectStreamConstants define the terminal and constant values expected in a stream.

    final static short STREAM_MAGIC = (short)0xaced;
    final static short STREAM_VERSION = 5;
    final static byte TC_NULL = (byte)0x70;
    final static byte TC_REFERENCE = (byte)0x71;
    final static byte TC_CLASSDESC = (byte)0x72;
    final static byte TC_OBJECT = (byte)0x73;
    final static byte TC_STRING = (byte)0x74;
    final static byte TC_ARRAY = (byte)0x75;
    final static byte TC_CLASS = (byte)0x76;
    final static byte TC_BLOCKDATA = (byte)0x77;
    final static byte TC_ENDBLOCKDATA = (byte)0x78;
    final static byte TC_RESET = (byte)0x79;
    final static byte TC_BLOCKDATALONG = (byte)0x7A;
    final static byte TC_EXCEPTION = (byte)0x7B;
    final static byte TC_LONGSTRING = (byte) 0x7C;
    final static byte TC_PROXYCLASSDESC = (byte) 0x7D;
    final static byte TC_ENUM = (byte) 0x7E;
    final static  int   baseWireHandle = 0x7E0000;
The flag byte classDescFlags may include values of

    final static byte SC_WRITE_METHOD = 0x01; //if SC_SERIALIZABLE
     final static byte SC_BLOCK_DATA = 0x08;    //if SC_EXTERNALIZABLE
    final static byte SC_SERIALIZABLE = 0x02;
    final static byte SC_EXTERNALIZABLE = 0x04;
    final static byte SC_ENUM = 0x10;
The flag SC_WRITE_METHOD is set if the Serializable class writing the stream had a writeObject method that may have written additional data to the stream. In this case a TC_ENDBLOCKDATA marker is always expected to terminate the data for that class.

The flag SC_BLOCKDATA is set if the Externalizable class is written into the stream using STREAM_PROTOCOL_2. By default, this is the protocol used to write Externalizable objects into the stream in JDKTM 1.2. JDKTM 1.1 writes STREAM_PROTOCOL_1.

The flag SC_SERIALIZABLE is set if the class that wrote the stream extended java.io.Serializable but not java.io.Externalizable, the class reading the stream must also extend java.io.Serializable and the default serialization mechanism is to be used.

The flag SC_EXTERNALIZABLE is set if the class that wrote the stream extended java.io.Externalizable, the class reading the data must also extend Externalizable and the data will be read using its writeExternal and readExternal methods.

The flag SC_ENUM is set if the class that wrote the stream was an enum type. The receiver's corresponding class must also be an enum type. Data for constants of the enum type will be written and read as described in Section 1.12, "Serialization of Enum Constants".

Example

Consider the case of an original class and two instances in a linked list:

class List implements java.io.Serializable {
    int value;
    List next;
    public static void main(String[] args) {
        try {
            List list1 = new List();
            List list2 = new List();
            list1.value = 17;
            list1.next = list2;
            list2.value = 19;
            list2.next = null;

            ByteArrayOutputStream o = new ByteArrayOutputStream();
            ObjectOutputStream out = new ObjectOutputStream(o);
            out.writeObject(list1);
            out.writeObject(list2);
            out.flush();
            ...
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }
}
The resulting stream contains:

00: ac ed 00 05 73 72 00 04 4c 69 73 74 69 c8 8a 15 >....sr..Listi...<

10: 40 16 ae 68 02 00 02 49 00 05 76 61 6c 75 65 4c >Z......I..valueL<

20: 00 04 6e 65 78 74 74 00 06 4c 4c 69 73 74 3b 78 >..nextt..LList;x<

30: 70 00 00 00 11 73 71 00 7e 00 00 00 00 00 13 70 >p....sq.~......p<

40: 71 00 7e 00 03                                  >q.~..<

 CONTENTS | PREV
 | NEXT

Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved.


Contents

CONTENTS | PREV | NEXT

Java Object Serialization Specification

Table of Contents

1 System Architecture
1.1 Overview
1.2 Writing to an Object Stream
1.3 Reading from an Object Stream
1.4 Object Streams as Containers
1.5 Defining Serializable Fields for a Class
1.6 Documenting Serializable Fields and Data for a Class
1.7 Accessing Serializable Fields of a Class
1.8 The ObjectOutput Interface
1.9 The ObjectInput Interface
1.10 The Serializable Interface
1.11 The Externalizable Interface
1.12 Serialization of Enum Constants
1.13 Protecting Sensitive Information

2 Object Output Classes
2.1 The ObjectOutputStream Class
2.2 The ObjectOutputStream.PutField Class
2.3 The writeObject Method
2.4 The writeExternal Method
2.5 The writeReplace Method
2.6 The useProtocolVersion Method

3 Object Input Classes
3.1 The ObjectInputStream Class
3.2 The ObjectInputStream.GetField Class
3.3 The ObjectInputValidation Interface
3.4 The readObject Method
3.5 The readObjectNoData Method
3.6 The readExternal Method
3.7 The readResolve Method

4 Class Descriptors
4.1 The ObjectStreamClass Class
4.2 Dynamic Proxy Class Descriptors
4.3 Serialized Form
4.4 The ObjectStreamField Class
4.5 Inspecting Serializable Classes
4.6 Stream Unique Identifiers

5 Versioning of Serializable Objects
5.1 Overview
5.2 Goals
5.3 Assumptions
5.4 Who's Responsible for Versioning of Streams
5.5 Compatible JavaTM Type Evolution
5.6 Type Changes Affecting Serialization
5.6.1 Incompatible Changes
5.6.2 Compatible Changes

6 Object Serialization Stream Protocol
6.1 Overview
6.2 Stream Elements
6.3 Stream Protocol Versions
6.4 Grammar for the Stream Format
6.4.1 Rules of the Grammar
6.4.2 Terminal Symbols and Constants

A Security in Object Serialization
A.1 Overview
A.2 Design Goals
A.3 Security Issues
A.4 Preventing Serialization of Sensitive Data
A.5 Writing Class-Specific Serializing Methods
A.6 Guarding Unshared Deserialized Objects
A.7 Preventing Overwriting of Externalizable Objects
A.8 Encrypting a Bytestream

B Exceptions In Object Serialization

C Example of Serializable Fields
C.1 Example Alternate Implementation of java.io.File
CONTENTS | PREV | NEXT
Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved.


Java(TM) Platform, Standard Edition 6

Java

JavaTM Platform, Standard Edition 6
Overview

 Contents

  • JRE and JDK
  • Java Programming Language
  • Java Virtual Machines
  • Base Libraries
  • Integration Libraries
  • User Interface Libraries
  • Deployment
  • Tool Specifications
  • JDK Tools & Utilities
  • Platforms

JRE and JDK

Sun Microsystems provides two principal software products in the JavaTM Platform, Standard Edition (JavaTM SE) family:

Java SE Runtime Environment (JRE)

The JRE provides the libraries, Java virtual machine, and other components necessary for you to run applets and applications written in the Java programming language. This runtime environment can be redistributed with applications to make them free-standing.

Java SE Development Kit (JDK)

The JDK includes the JRE plus command-line development tools such as compilers and debuggers that are necessary or useful for developing applets and applications.

Java Programming Language

The Java Programming Language is a general-purpose, concurrent, strongly typed, class-based object-oriented language. It is normally compiled to the bytecode instruction set and binary format defined in the Java Virtual Machine Specification. For more information see Language Features.

Java Virtual Machines

The Java virtual machine is an abstract computing machine that has an instruction set and manipulates memory at run time. The Java virtual machine is ported to different platforms to provide hardware- and operating system-independence.

The Java Platform, Standard Edition provides two implementations of the Java virtual machine (VM):

Java HotSpot Client VM

The client VM is an implementation for platforms typically used for client applications. The client VM is tuned for reducing start-up time and memory footprint. It can be invoked by using the -client command-line option when launching an application.

Java HotSpot Server VM

The server VM is an implementation designed for maximum program execution speed, trading off launch time and memory. It can be invoked by using the -server command-line option when launching an application.

For more information, see the VM documentation.

Base Libraries

Classes and interfaces that provide basic features and fundamental functionality for the Java platform.

Lang and Util Packages

Provides the fundamental Object and Class classes, wrapper classes for primitive types, a basic math class, and more. See the Lang and Util documentation for more information.

Math

Math functionality includes floating point libraries and arbitrary-precision math. For more information, see the Math documentation.

Monitoring and Management

Comprehensive monitoring and management support for Java platform including Monitoring and Management API for Java virtual machine, Monitoring and Management API for the Logging Facility, jconsole and other monitoring utilities, out-of-the-box monitoring and management, Java Management Extensions (JMX), and Sun's Platform Extension. See the Monitoring and Management documentation for more information.

Package Version Identification

The package versioning feature enables package-level version control so that applications and applets can identify at runtime the version of a specific Java Runtime Environment, VM, and class package. For more information, see the Package Version Identification documentation.

Reference Objects

Reference objects 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. Reference objects are therefore useful for building simple caches as well as caches that are flushed when memory runs low, for implementing mappings that do not prevent their keys (or values) from being reclaimed, and for scheduling pre-mortem cleanup actions in a more flexible way than is possible with the Java finalization mechanism. For more information, see the Reference Objects documentation.

Reflection

Reflection enables Java code to discover information about the fields, methods and constructors of loaded classes, and to use reflected fields, methods, and constructors to operate on their underlying counterparts on objects, within security restrictions. The API accommodates applications that need access to either the public members of a target object (based on its runtime class) or the members declared by a given class. Programs can suppress default reflective access control. For more information, see the Reflection documentation.

Collections Framework

A collection is an object that represents a group of objects. The collections framework is a unified architecture for representing collections, allowing them to be manipulated independently of the details of their representation. It reduces programming effort while increasing performance. It allows for interoperability among unrelated APIs, reduces effort in designing and learning new APIs, and fosters software reuse. For more information, see the Collections Framework documentation.

Concurrency Utilities

The Concurrency Utilities packages provide a powerful, extensible framework of high-performance threading utilities such as thread pools and blocking queues. This package frees the programmer from the need to craft these utilities by hand, in much the same manner the Collections Framework did for data structures. Additionally, these packages provide low-level primitives for advanced concurrent programming. For more information, See the Concurrency Utilities documentation.

Java Archive (JAR) Files

JAR (Java Archive) is a platform-independent file format that aggregates many files into one. Multiple Java applets and their requisite components (.class files, images and sounds) can be bundled in a JAR file and subsequently downloaded to a browser in a single HTTP transaction, greatly improving the download speed. The JAR format also supports compression, which reduces the file size, further improving the download time. In addition, the applet author can digitally sign individual entries in a JAR file to authenticate their origin. It is fully extensible. For more information, see the Java Archive documentation.

Logging

The Logging APIs facilitate software servicing and maintenance at customer sites by producing log reports suitable for analysis by end users, system administrators, field service engineers, and software development teams. The Logging APIs capture information such as security failures, configuration errors, performance bottlenecks, and/or bugs in the application or platform. For more information, see the Logging documentation.

Preferences

The Preferences API provides a way for applications to store and retrieve user and system preference and configuration data. The data is stored persistently in an implementation-dependent backing store. There are two separate trees of preference nodes, one for user preferences and one for system preferences. For more information, see the Preferences API documentation,

Other Base Packages

I/O

The java.io and java.nio packages provide a rich set of APIs for managing an application's I/O. The functionality includes file and device I/O, object serialization, buffer management, and character-set support. Additionally, the APIs support features for scalable servers including multiplexed, non-blocking I/O, memory mapping and locks for files. For more information, see the I/O documentation.

Object Serialization

Object Serialization extends the core Java Input/Output classes with support for objects. Object Serialization supports the encoding of objects, and the objects reachable from them, into a stream of bytes; and it supports the complementary reconstruction of the object graph from the stream. Serialization is used for lightweight persistence and for communication via sockets or Remote Method Invocation (RMI). See the Object Serialization documentation for more information.

Networking

Provides classes for networking functionality, including addressing, classes for using URLs and URIs, socket classes for connecting to servers, networking security functionality, and more. See the Networking documentation for more information.

Security

APIs for security-related functionality such as configurable access control, digital signing, authentication and authorization, cryptography, secure Internet communication, and more. See the Security documentation for more information.

Internationalization

APIs that enable the development of internationalized applications. Internationalization is the process of designing an application so that it can be adapted to various languages and regions without engineering changes. See the Internationalization documentation for more information.

JavaBeansTM Component API

Contains classes related to developing beans -- components based on the JavaBeansTM architecture that can be pieced together as part of developing an application. See the JavaBeans documentation for more information.

Java Mangement Extensions (JMX)

The Java Management Extensions (JMX) API is a standard API for management and monitoring of resources such as applications, devices, services, and the Java virtual machine. Typical uses include consulting and changing application configuration, accumulating statistics about application behavior, and notifying of state changes and erroneous conditions. The JMX API includes remote access, so a remote management program can interact with a running application for these purposes. See the Java Management Extensions documentation for more information.

XML (JAXP)

The Java platform provides a rich set of APIs for processing XML documents and data. See the Java SE XML documentation for more information.

Java Native Interface (JNI)

Java Native Interface (JNI) is a standard programming interface for writing Java native methods and embedding the Java virtual machine into native applications. The primary goal is binary compatibility of native method libraries across all Java virtual machine implementations on a given platform. See the Java Native Interface documentation for more information.

Extension Mechanism

Optional packages are packages of Java classes (and any associated native code) that application developers can use to extend the functionality of the core platform. The extension mechanism allows the Java virtual machine (VM) to use the classes of the optional extension in much the same way as the VM uses classes in the Java Platform. The extension mechanism also provides a way for needed optional packages to be retrieved from specified URLs when they are not already installed in the JDK or Runtime Environment. See the Java Extension Mechanism documentation for more information.

Endorsed Standards Override Mechanism

An endorsed standard is a Java API defined through a standards process other than the Java Community ProcessSM (JCP). Because endorsed standards are defined outside the JCP, it is anticipated that such standards may be revised between releases of the Java Platform. In order to take advantage of new revisions to endorsed standards, developers and software vendors may use the Endorsed Standards Override Mechanism to provide newer versions of an endorsed standard than those included in the Java Platform as released by Sun Microsystems. See the Endorsed Standards Override Mechanism documentation for more information.

Integration Libraries

Java Database Connectivity (JDBC) API

The JDBCTM API provides universal data access from the Java programming language. Using the JDBC 3.0 API, you developers can write applications that can access virtually any data source, from relational databases to spreadsheets and flat files. JDBC technology also provides a common base on which tools and alternate interfaces can be built. For more information, see the JDBC documentation.

Remote Method Invocation (RMI)

Remote Method Invocation (RMI) enables the development of distributed applications by providing for remote communication between programs written in the Java programming language. RMI enables an object running in one Java Virtual Machine to invoke methods on an object running in another Java VM, which may be on a different host. For more information, see the Java SE RMI documentation.

Java IDL (CORBA)

Java IDL technology adds CORBA (Common Object Request Broker Architecture) capability to the Java platform, providing standards-based interoperability and connectivity. Java IDL enables distributed Web-enabled Java applications to transparently invoke operations on remote network services using the industry standard IDL (Object Management Group Interface Definition Language) and IIOP (Internet Inter-ORB Protocol) defined by the Object Management Group. Runtime components include a Java ORB for distributed computing using IIOP communication. For more information, see the Java IDL documentation.

RMI-IIOP

Java Remote Method Invocation over Internet Inter-ORB Protocol technology The RMI Programming Model enables the programming of CORBA servers and applications via the RMI API. You can choose to work completely within the Java programming language using the Java Remote Method Protocol (JRMP) as the transport, or work with other CORBA-compliant programming languages using the Internet InterORB Protocol (IIOP). You use the rmic compiler to generate the code necessary for connecting your applications via the Internet InterORB Protocol (IIOP) to others written in any CORBA-compliant language. To work with CORBA applications in other languages, IDL can be generated from Java programming language interfaces using the rmic compiler with the -idl option. To generate IIOP stubs and tie classes, use the rmic compiler with the -iiop option. For more information, see the RMI-IIOP documentation.

Scripting for the Java Platform

Java SE 6 includes the JSR 223: Scripting for the JavaTM Platform API. This is a framework by which Java Applications can "host" script engines. Sun's implementation of Java SE 6 includes an example script engine based on Mozilla Rhino:java_script for Java. The scripting framework supports third-party script engines through jar "service discovery" mechanism. It is possible to "drop" any JSR-223 compliant script engine in the CLASSPATH and access the same from your Java applications For more information, see the Scripting documentation.

Java Naming and Directory InterfaceTM (JNDI) API

The Java Naming and Directory InterfaceTM (JNDI) provides naming and directory functionality to applications written in the Java programming language. It is designed to be independent of any specific naming or directory service implementation. Thus a variety of services--new, emerging, and already deployed ones--can be accessed in a common way. The JNDI architecture consists of a API and an SPI (Service Provider Interface). Java applications use this API to access a variety of naming and directory services. The SPI enables a variety of naming and directory services to be plugged in transparently, allowing the Java application using the JNDI API to access their services. For more information, see JNDI documentation.

User Interface Libraries

Input Method Framework

The input method framework enables the collaboration between text editing components and input methods in entering text. 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 more information, see the Input Method Framework documentation.

Accessibility

With the Java Accessibility API, developers can easily create Java applications that are accessible to disabled persons. Accessible Java applications are compatible with assistive technologies such as screen readers, speech recognition systems, and refreshable braille displays. For more information, see the Accessibility documentation.

Print Service

The JavaTM Print Service API, allows printing on all Java platforms including those requiring a small footprint, such as a Java ME profile. For more information, see Java Print Service documentation.

Sound

The Java platform includes a powerful API for capturing, processing, and playing back audio and MIDI (Musical Intstrument Digital Interface) data. This API is supported by an efficient sound engine which guarantees high-quality audio mixing and MIDI synthesis capabilities for the platform. For more information, see Java Sound documentation.

Drag and Drop Data Transfer

Drag and Drop enables data transfer both across Java programming language and native applications, between Java programming language applications, and within a single Java programming language application. For more information, see Drag and Drop Transfer.

Image I/O

The Java Image I/O API provides a pluggable architecture for working with images stored in files and accessed across the network. The API provides provides a framework for the addition of format-specific plugins. Plug-ins for several common formats are included with Java Image I/O, but third parties can use this API to create their own plugins to handle special formats. For more information, see Image I/O.

Java 2DTM Graphics and Imaging

The Java 2DTM API is a set of classes for advanced 2D graphics and imaging. It encompasses line art, text, and images in a single comprehensive model. The API provides extensive support for image compositing and alpha channel images, a set of classes to provide accurate color space definition and conversion, and a rich set of display-oriented imaging operators. For more information, see the Java 2D documentation.

AWT

The JavaTM platform's Abstract Windowing Toolkit (AWT) provides APIs for constructing user interface components such as menus, buttons, text fields, dialog boxes, checkboxes, and for handling user input through those components. In addition, AWT allows for rendering of simple shapes such as ovals and polygons and enables developers to control the user-interface layout and fonts used by their applications. For more information, see the AWT documentation.

Swing

The Swing APIs also provide graphical component (GUI) for use in user interfaces. The Swing APIs are written in the Java programming language without any reliance on code that is specific to the GUI facilities provided by underlying operating system. This allows the Swing GUI components to have a "pluggable" look-and-feel that can be switched while an application is running. For more information, see the Java SE Swing documentation.

Deployment

Java Deployment

Installation, setup, updating, redistribution and related topics:

  • Installation of the Java Platform on a computer
  • Setting Options in the Java Control Panel
  • Writing applications and applets in the Java Programming language
  • Authoring web pages that invoke applets or download and launch applications
  • Making Java-related files available on web servers
  • Updating the Java Platform on a computer

For more information, see General Deployment, Java Plug-in, and Java Web Start.

Tool Specifications

Debugger Architecture

Architecture and specifications for for use by debuggers in development environments. For more information, see the Java Platform Debugger Architecture (JPDA) documentation.

VM Tool Interface

The Java Virtual Machine Tool Interface (JVM TI) is a specification for inspecting the state and controlling the execution of applications running in the JVM. The Java Virtual Machine Profiler Interface (JVMPI) has been deprecated. For more information, see the Java Virtual Machine Tool Interface (JVM TI) documentation.

Javadoc Tool

Javadoc is a tool that parses the declarations and documentation comments source files to produce a set of HTML pages describing the program elements. The Doclet API provides a mechanism for clients to inspect the source-level structure of programs and libraries, including javadoc comments embedded in the source. This API can be used by doclets to generate documentation. For more information, see the Javadoc documentation.

Annotation Processing

The apt tool is a command-line utility for annotation processing. It includes a set of reflective APIs and supporting infrastructure to process program annotations. These reflective APIs provide a build-time, source-based, read-only view of program structure. They are designed to cleanly model the Java programming language's type system after the addition of generics. For more information, see the apt documentation.

Dynamic Attach

The package com.sun.tools.attach contains a Sun Microsystems extension to the Java Platform that allows an application to attach to a running Java virtual machine. Once the attach has been made, a tool agent can be started in the target virutal machine. For more information, see the attach documentation.

JConsole API

The package com.sun.tools.jconsole contains a Sun Microsystems extension to the Java Platform that provides a programmatic interface to access JConsole. For more information, see Using JConsole.

JDK Tools & Utilities

Documentation for the tools and utilities included in the JDK. Covers basic tools (javac, java, javadoc, apt, appletviewer, jar, jdb, javah, javap, extcheck), security tools, internationalization tools, RMI tools, IDL and RMI-IIOP tools, deployment tools, Java Plug-in tools, and Java Web Start tools, monitoring and management tools, and troubleshooting tools. For more information, see the JDK Tools and Utilities documentation.

Platforms

Sun provides implementations of the JDK and Java Runtime Environment for Microsoft Windows, Linux, and the Solaris operating systems. See System Configurations for information about which versions of these platforms are supported.

Other companies may provide implementations of the Java platform for other operating systems such as Macintosh, AIX, etc.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved. Sun
Java Software


Java 2D API Specification

Java

Java 2DTM API Specification

 Documentation Contents
The following list contains all of the packages and classes included in the Java 2D API. Each item in the list is linked to its API documentation.
  • java.awt.color
    Provides classes for color spaces and color profiles based on the ICC Profile Format Specification.
  • java.awt.font
    Provides classes and interfaces relating to fonts and support for representing Type 1, Type 1 Multiple Master, OpenType, and TrueType fonts.
  • java.awt.geom
    Provides classes for defining and performing operations on two-dimensional geometric objects.
  • java.awt.image
    Provides classes for creating and modifying images, as well as image producers, consumers and filters for configuring image processing.
  • java.awt.print
    Provides classes and interfaces for printing two-dimensional objects and includes support for specifying document types, controlling page setup and page formats, and managing job control dialogs.
  • javax.print
    Provides the principal classes and interfaces for the Java Print Service API.
  • java.awt.image.renderable
    Provides classes and interfaces for producing rendering-independent images.

The java.awt package also includes classes that are part of the Java 2D API:

  • java.awt - Contains classes for generating user interfaces and painting graphics and images. The following java.awt classes are part of the Java 2D API.
    • java.awt.AlphaComposite
    • java.awt.BasicStroke
    • java.awt.Color
    • java.awt.Composite
    • java.awt.CompositeContext
    • java.awt.Font
    • java.awt.FontMetrics
    • java.awt.GradientPaint
    • java.awt.Graphics
    • java.awt.Graphics2D
    • java.awt.GraphicsConfigTemplate
    • java.awt.GraphicsConfiguration
    • java.awt.GraphicsDevice
    • java.awt.GraphicsEnvironment
    • java.awt.Image
    • java.awt.ImageCapabilities
    • java.awt.MediaTracker
    • java.awt.PageAttributes and its nested classes
    • java.awt.Paint
    • java.awt.PaintContext
    • java.awt.Point
    • java.awt.Polygon
    • java.awt.Rectangle
    • java.awt.RenderingHints and its nested class
    • java.awt.Shape
    • java.awt.Stroke
    • java.awt.TexturePaint
    • java.awt.Toolkit
    • java.awt.Transparency

Copyright © 1995-2004 Sun Microsystems, Inc. All Rights Reserved.

Please send comments using the Java 2D Feedback page. 		Sun Microsystems, Inc
Java Software


Java 2D Graphics and Imaging

Java

Java 2DTM Graphics and Imaging

 Documentation Contents
The Java 2DTM API is a set of classes for advanced 2D graphics and imaging. It encompasses line art, text, and images in a single comprehensive model. The API provides extensive support for image compositing and alpha channel images, a set of classes to provide accurate color space definition and conversion, and a rich set of display-oriented imaging operators. These classes are provided as additions to the java.awt and java.awt.image packages.

Overview

  • Java 2D API Overview from the Programmer's Guide to the Java 2D API.

API Specification

  • Java 2D API Specification - a list of the packages and classes included in the Java 2D API.

Tutorials and Programmer's Guides

  • Java 2D API Guide: Enhanced Graphics and Imaging for Java.
    Read the README for instructions on how to run the code samples used in the Imaging chapter of the Java2D API Guide.
  • The 2D Graphics trail in The Java Tutorial demonstrates how to display and print 2D graphics.

API Enhancements

  • Java 2D Enhancements in J2SE 5.0 - A list of features added to the Java 2D API for J2SE 5.0.
  • Java 2D Enhancements in Java 2 SDK, v1.4 - Features added for v1.4.0.

More Information

  • System Properties for Java 2D Technology - A list of unsupported properties that you can use to customize how the 2D painting system operates.
  • The Java 2D Home Page
  • The JFC Home Page
  • High Performance Graphics White Paper

Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved.

Please send comments using the Java 2D Feedback page. 		Sun Microsystems, Inc
Java Software


New Features in Java 2D(TM) Technology

Java

New Java 2DTM Features
in J2SE 5.0

2D Contents

  • Caching All BufferedImages
  • Methods for Controlling Hardware Acceleration of Images
  • Support for Hardware-Accelerated Rendering Using OpenGL
  • Solaris and Linux Support for CUPS Printers
  • Bicubic Interpolation
  • Creating Fonts from Files and Streams
  • Improved Text Rendering Performance and Reliability
  • Multilingual Text Rendering

Caching All BufferedImages

As of J2SE 5.0, all images created with a BufferedImage constructor are now managed images and can be cached in video memory or, in the case of a remote X server, on the X server side. Previously, the Sun implementation managed only compatible images — those created with the Component createImage(int, int) method or with the GraphicsConfiguration createCompatibleImage methods. Managed images generally perform better than unmanaged images.

Methods for Controlling Hardware Acceleration of Images

The bug report that corresponds to this change is: 4881082

The Image class has three new methods related to hardware acceleration. The getCapabilities method, formerly defined only in VolatileImage, allows you to determine whether the image is currently accelerated. Two other methods let you set or get a hint about how important acceleration is for the image: setAccelerationPriority and getAccelerationPriority.

The GraphicsConfiguration class has two new methods, createCompatibleVolatileImage(int, int, int) and createCompatibleVolatileImage(int, int, ImageCapabilities, int), that allow you to create transparent VolatileImages.

Note: In J2SE 5.0, these methods are not fully operational. The value set by setAccelerationPriority is ignored, and images created with the createCompatibleVolatileImage methods are not always hardware accelerated. On Linux and Solaris systems, only OPAQUE VolatileImages are hardware accelerated. On Microsoft Windows systems, images created with createCompatibleVolatileImage in J2SE 5.0 are hardware accelerated only if the hardware supports acceleration and one of the following is true:
  • The transparency value is OPAQUE.
  • The transparency value is TRANSLUCENT and translucency acceleration has been specifically enabled at runtime (sun.java2d.translaccel=true).
We expect to fully implement these methods on all platforms in future releases.

Support for Hardware-Accelerated Rendering Using OpenGL

The bug reports that correspond to this change are: 4607536 and 5008045.

J2SE 5.0 includes a new OpenGL-based pipeline for Java 2D. This pipeline provides hardware acceleration for simple rendering operations (text, images, lines, and filled primitives) as well as those that involve complex transforms, paints, composites, and clips. This pipeline is available on all platforms (Solaris, Linux, and Microsoft Windows) and is currently disabled by default.

To silently enable the OpenGL-based pipeline, specify the following system property on the command line:

    -Dsun.java2d.opengl=true

To receive verbose console output about whether the OpenGL-based pipeline is initialized successfully for a particular screen, specify "True" (note the uppercase T):

    -Dsun.java2d.opengl=True

Minimum requirements for Solaris/Linux:

  • Hardware accelerated OpenGL/GLX libraries installed and configured properly
  • OpenGL version 1.2 or higher
  • GLX version 1.3 or higher
  • At least one TrueColor visual with an available stencil buffer

Minimum requirements for Microsoft Windows:

  • Hardware accelerated drivers supporting the WGL_ARB_pbuffer, WGL_ARB_render_texture, and WGL_ARB_pixel_format extensions
  • OpenGL version 1.2 or higher
  • At least one pixel format with an available stencil buffer

Solaris OpenGL Notes

Accelerated OpenGL libraries for the Solaris SPARC platform are available directly from Sun:

http://wwws.sun.com/software/graphics/opengl/index.html
The following Sun framebuffers are known to work with the OpenGL-based Java 2D pipeline:
  • Expert3D
  • Expert3D Lite
  • XVR-500
  • XVR-600
  • XVR-1000
  • XVR-1200

Accelerated OpenGL libraries for the Solaris x86 platform are not available from Sun. However, third-parties such as Xi Graphics are known to support OpenGL libraries for Solaris x86.

Linux OpenGL Notes

Most Linux distributions include the Mesa 3D graphics library, which is a software implementation of the OpenGL specification. Since Mesa does not take advantage of hardware acceleration, it is likely that the OpenGL-based Java 2D pipeline will run much more slowly than the default (X11-based) pipeline. Therefore, to achieve optimal performance with the OpenGL-based pipeline, it is recommended that you install accelerated OpenGL drivers provided by your graphics hardware manufacturer.

The following web sites may have accelerated OpenGL drivers you can download.

  • Nvidia (GeForce 2 and above): http://www.nvidia.com
  • ATI (Radeon 8500 and above, FireGL, etc.): http://www.atitech.com
  • Others:
    • http://dri.sourceforge.net
    • http://www.xig.com

Microsoft Windows OpenGL Notes

To achieve optimal performance with the OpenGL-based pipeline, install accelerated OpenGL drivers provided by your graphics hardware manufacturer. The following websites have accelerated OpenGL drivers available for download that are known to be compatible with the OpenGL-based Java 2D pipeline:

  • Nvidia (GeForce 2 and above): http://www.nvidia.com
  • ATI (Radeon series, FireGL, and so on): http://www.atitech.com

Note: The latest drivers from both Nvidia and ATI have known issues on Microsoft Windows that might cause rendering artifacts in your application. We are actively investigating these driver bugs and are working with the manufacturers to have them resolved in future driver updates.

Solaris and Linux Support for CUPS Printers

The bug reports that correspond to this change are: 4641868 and 4683270

Solaris and Linux systems can now use printers configured as CUPS (Common UNIX Printing System) printers. This expands the printers the Java platform can use to all those supported by CUPS — including most PostScript and raster printers — making it much easier to use low-cost printers with Linux. CUPS is based on IPP (Internet Printing Protocol).

See http://www.cups.org for more information.

Bicubic Interpolation

The bug report that corresponds to this change is: 4200154

The 2D implementation now supports bicubic interpolation and uses it whenever requested. Previously, the VALUE_INTERPOLATION_BICUBIC hint defined by the RenderingHints class wasn't honored, and bilinear interpolation was used instead. Now the bicubic rendering hint is honored, and a new constant TYPE_BICUBIC has been added to AffineTransformOp.

Creating Fonts from Files and Streams

The bug reports that correspond to this change are: 4390880 and 4468862

It is now possible to create Font objects from Type 1 fonts and to create Font objects directly from files containing either Type 1 or TrueType font data.

To support the new functionality, the Font class has a new createFont method that creates Font objects from files. The pre-existing createFont method creates Font objects from streams. A new constant, Font.TYPE1_FONT, specifies Type 1 fonts to either createFont method.

Improved Text Rendering Performance and Reliability

The bug report that corresponds to this change is: 4641861

A number of internal changes to text rendering code greatly improve its robustness, performance, and scalability.

Multilingual Text Rendering

The bug report that corresponds to this change is: 4097028

2D text rendering using logical fonts now takes advantage of installed host OS fonts for all supported writing systems to render multilingual text. For example, if you run in a Thai locale environment but have Korean fonts installed, both Thai and Korean are rendered.

Copyright © 1995-2004 Sun Microsystems, Inc. All Rights Reserved.

Please send comments using the Java 2D Feedback page. 		Sun Microsystems, Inc
Java Software


New Features in Java 2D(TM) Technology

Java

New Java 2DTM Features in
JavaTM 2 SDK, v1.4

2D Contents

New Pipeline Architecture Hardware Acceleration for Offscreen Images
Pluggable Image I/O Framework New Java Print Service API
Support for additional Image Types Public Bidi Algorithm
Font Rasterizer support for TrueType hinting Hinted Lucida Fonts
OpenType Font Table Support Support for Numeric Shaping
Improved Complex Text Layout Support Complete Porter-Duff Support
Support for Checking if Font has a Transform New Equality Methods for FontRenderContext

New Pipeline Architecture

The bugtraq reports that correspond to this change are: 4228939 and 4268962

In the Java 2 SDK, version 1.2 and 1.3, common operations on a Graphics object often invalidated the rendering data cached for this Graphics object. This invalidation interrupted the rendering process by causing continuous re-creation of rendering information for the Graphics object, even for such simple and benign operations as create(), setColor(), and translate(). Because the rendering of Swing hierarchies relies heavily on these common operations, the invalidation and re-creation of rendering data caused poor repaint performance for many Swing applications.

The new pipeline architecture reduces this performance overhead with several implementation changes that:

  • Improve the way that data is shared by the various rendering pipelines.
  • Reduce the amount of code executed and garbage created when responding to changes in the rendering attributes.
  • Improve the way that various graphics routines are chosen such as the routines that copy pixels from one format and location to another.
These changes are especially noticeable when the following calls are used frequently, as they are in Swing applications:
  • getGraphics, Graphics.create() and Graphics.dispose()
  • Graphics.setColor(), Graphics.translate
  • Graphics.copyArea, especially when the source and destination regions overlap.
The runtime footprint should also be improved through better code sharing.

Other changes in the pipeline architecture have greatly improved the performance of:

  • draw(Shape) and fill(Shape), especially when the Shape is a GeneralPath
  • scaled drawImage.
  • Blitting from an offscreen image created with createImage() multiple times without any intervening rendering or modifications to that image
  • Remote X11 display over the network of applications that use createImage() to create an image buffer for double buffering.
  • Rendering non-opaque text.
  • Systems, such as the SGI Visual 320 workstation, which have display cards that use an RGBx format for pixel storage.
  • Rendering coordinates outside of the range -32768 to 32767 with antialiasing turned off.
For more information on this feature, see the whitepaper, High Performance Graphics.

Hardware Acceleration for Offscreen Images

The bugtraq report that corresponds to this change is: 4330166

The SDK 1.4 provides access to hardware acceleration for offscreen images, resulting in better performance of rendering to and copying from these images. One problem with hardware-accelerated images is that, on some platforms such as Microsoft Windows, their contents can be lost at any time due to circumstances beyond the application's control. The new VolatileImage class allows you to create a hardware-accelerated offscreen image and manage the contents of that image.

This new API includes:

  • java.awt.image.VolatileImage:
    This class represents an image whose content can be lost at any time, but provides performance benefits. For example, on Microsoft Windows this image can be stored in VRAM and can benefit from hardware acceleration. The class includes methods that you can call to find out if the contents of the image need to be restored.
  • createVolatileImage(w,h) in Component.
    This method creates a VolatileImage that is compatible with the Component.
  • createCompatibleVolatileImage(int width, int height)
    This method creates a VolatileImage that is compatible with the GraphicsConfiguration.
  • GraphicsDevice.getAvailableAcceleratedMemory
    This method returns the number of bytes of available accelerated memory. The VolatileImage.flush method can be used to release the memory used by an offscreen image.

For more information on using the VolatileImage API, see The VolatileImage API User Guide ( PDF)

Pluggable Image I/O Framework

The bugtraq report that corresponds to this change is: 4101949

The JavaTM Image I/O API is an pluggable, extensible framework that supports reading and writing images of various formats and protocols. The API provides this support through plug-ins, most of which will be written by third parties. A conforming implementation will only be required to provide a minimal set of plug-ins, principally for compatibility with previous versions of the Java SDK. An application using this API should be able to read and write images without knowing the image's storage format or the plug-in used to support the format.

Fundamentally, all image I/O operations consist of reading or writing streams that contain one or more images, one or more preview (thumbnail) images associated with each image, and metadata, which is everything other than pixel data.

The Java Image I/O API allows applications to:

  • Auto-detect installed plug-ins
  • Choose plug-ins based on format name, file suffix, file contents, or MIME type
  • Access individual images in multi-image files
  • Monitor reading and writing progress
  • Provide progressive updates of images being loaded
  • Read or write only a region of interest of an image
  • Read only selected bands of an image
  • Choose the output size of resolution-independent imagery
  • Retrieve detailed image and stream metadata
  • Work with unknown formats using generic interfaces
  • Work efficiently with both random-access and streaming data sources
  • Transcode between different formats

See Java Image I/O for more information on the Java Image I/O API.

New JavaTM Print Service

The bugtraq reports that corresponds to this change are:
4285177 and 4360752

This API is the product of JSR006, Unified Printing API, and will allow client applications to provide rich access to the capablities of print services available including:

  • Printer browsing and selection
  • Discovery of the capablities of printers
  • Selection of printers for a printer job
  • Specification of a printer job.
Since all capabilities will be exposed through the API, server applications become first class citizens of this API.

Server applications can be beneficiaries of the capabilities for spooling documents to print services, whereas previously only graphics calls could be used to generate printer jobs from Java applications.

See Java Print Service for more information.

Support for float and double Image Types

The bugtraq report that corresponds to this change is: 4364491

Prior to the SDK 1.4, the Java 2D API did not have DataBuffer subclasses for float or double sample types. The Java Image I/O API needs these classes to read and write float and double image types.

The SDK 1.4 contains two new classes to provide float and double image type support: DataBufferFloat and DataBufferDouble. The DataBufferFloat class wraps float arrays of pixels. The DataBufferDouble class wraps double arrays of pixels.

The existing ComponentColorModel and ComponentSampleModel class implementations have also been updated to support signed short,float, and double data. These classes include definitions of the normalized ranges of component values for the newly-supported data types:

  • For the existing data types, the range remains 0.0 to 1.0.
  • For short data, the values are scaled to between -1.0 and 1.0.
  • For float data, the range is the full range of the float primitive type.
  • For double data, the range is also the range of the float primitive type, since values must be cast to float to interact with the ColorSpace class.
The ComponentColorModel class will not clamp the pixel data. Applications are expected to scale to the appropriate range. Methods are added to the ColorSpace class to determine per component minimum and maximum normalized values. Alpha component values must still range from 0.0 to 1.0 normalized.

The complete additional API is listed below.

java.awt.image.ColorModel includes three new methods to parallel existing methods:

  • getDataElement(float[] normComponents, int normOffset)
  • getDataElements(float[] normComponents, int normOffset, Object obj)
  • getNormalizedComponents(Object pixel, float[] normComponents, int normOffset)
java.awt.image.ComponentColorModel includes a new constructor based on the new datatypes and new methods to override the existing ColorModel methods:
  • ComponentColorModel(ColorSpace colorSpace, boolean hasAlpha, boolean isAlphaPremultiplied, int transparency, int transferType)
  • getRed(Object inData)
  • getGreen(Object inData)
  • getBlue(Object inData)
  • getAlpha(Object inData)
  • getDataElements(int rgb, Object pixel)
  • coerceData(WritableRaster raster, boolean isAlphaPremultiplied)
  • createCompatibleWritableRaster(int w, int h)
  • createCompatibleSampleModel(int w, int h)
java.awt.image.SampleModel includes two new methods to accept the new datatypes:
  • getDataElements(int x, int y, int w, int h, Object obj, DataBuffer data)
  • setDataElements(int x, int y, int w, int h, Object obj, DataBuffer data)
java.awt.image.ComponentSampleModel includes two methods to accept the new datatypes:
  • createDataBuffer()
  • getDataElements(int x, int y, Object obj, DataBuffer data)
java.awt.image.BandedSampleModel has three methods that were edited to accept the new datatypes:
  • createDataBuffer()
  • getDataElements(int x, int y, Object obj, DataBuffer data)
  • setDataElements(int x, int y, Object obj, DataBuffer data)
java.awt.color.ColorSpace includes two new methods determine per component minimum and maximum normalized values:
  • getMinValue(int component)
  • getMaxValue(int component)
java.awt.color.ICC_ColorSpace includes new methods override the two new ColorSpace methods.

Public Bidi Algorithm

The bugtraq report that corresponds to this change is: 4285083

The Unicode Bidirectional Algorithm analyzes text using the Unicode character properties and determines the direction of runs of the text. The algorithm is necessary to properly display bidirectional text, such as Hebrew and Arabic text, in the correct order.

The current implementation is all written in the Java programming language, but the SDK 1.4 will include efficient access from native font code so that Hebrew and Arabic text can be more efficiently rendered. The SDK 1.4 will provide access to the native code through the Java Native Interface.

The new public Bidi class implements the Unicode 3.0 Bidi Algorithm and allows access to information on the bidirectional reordering of text so that the mixed, bidirectional text is properly displayed.

The example BidiSample demonstrates some of the Bidi routines.

Font Rasterizer support for TrueType hinting

Before this release, the T2K font rasterizer used by Java 2D did not support font-hinting for TrueType fonts. As a result, when TrueType fonts did not always display with a consistent, attractive appearance. For this release, the T2K rasterizer has been modified to use the hints stored in the TrueType fonts.

By adding this functionality to the T2K rasterizer, dependency on native rasterizers has been greatly reduced. Reducing this dependency results in:

  • Greater portability because hinting of TrueType fonts is performed by the cross-platform T2K rasterizer, not the native rasterizer.
  • More consistent metrics display of TrueType fonts because the same rasterizer is being used for on-screen and off-screen drawing.

Hinted Lucida Fonts

The bugtraq report that corresponds to this change is: 4285089

For the SDK 1.4, the Lucida fonts that are in the Java 2 SDK will be upgraded to contain hints. This will give the Java 2 SDK higher quality fonts that could be used in place of existing fonts or if no other fonts are available. Adding hints to the Lucida fonts also allows the new cross-platform rasterizer to hint the Lucida fonts contained in the SDK, which causes the Lucida fonts to be displayed in a more consistent and attractive manner.

OpenType Font Table Support

The bugtraq report that corresponds to this change is: 4285161

The SDK 1.4 includes a new architecture for providing general OpenType font support. This new architecture provides international character support for contextual scripts like Thai, Indic, Arabic, and Hebrew. It also provides enhanced typographical support for Roman languages.

Support for Numeric Shaping

The bugtraq report that corresponds to this change is: 4210199

Currently, when Java 2D renders numerals surrounded by Arabic text, the numerals have Arabic (roman) shapes, which are the commonly expected numeral shapes in most western countries. However, people in a Hindi locale expect to see Hindi shapes.

A new attribute, TextAttribute.NUMERIC_SHAPING, and a new class, NumericShaper, enable you to shape ASCII digits to other Unicode decimal ranges.

For example, to cause a TextLayout instance to convert digits from European to Arabic:

  1. Create a NumericShaper that shapes ARABIC digits:
          Numeric Shaper nS
       = NumericShaper.getContextualShaper(NumericShaper.ARABIC)
  2. Add the NumericShaper to an attribute Map along with the key value of TextAttribute.NUMERIC_SHAPING:
          Map map = new HashMap();
      map.put(TextAttribute.NUMERIC_SHAPING, nS);
  3. Create a TextLayout with the attribute Map:
          FontRenderContext frc = ...;
      TextLayout layout = new TextLayout(text, map, frc);
  4. Render the text:
          layout.draw(g2d, x, y);

The NumericShaper class includes 19 constants representing different Unicode decimal ranges, allowing you to convert to 19 different digit shapes, including Devanagari and Thai.

Improved Complex-Layout Support in GlyphVector

Prior to this release, clients could not access glyph-to-character mapping information from GlyphVector. Clients can use this information to find out which glyphs in the GlyphVector correspond to which characters. This release also defines new methods to get the precise bounds of the GlyphVector and of individual glyphs within a GlyphVector.

Note: Although clients can use GlyphVector and the glyph-to-character mapping information to implement selection and hit testing, most clients will find TextLayout and the Swing JTextArea and JTextField classes to be more useful and convenient.

These GlyphVector methods are new in the SDK 1.4:

  • getGlyphCharIndex(int glyphIndex)
    Returns the character index of the specified glyph. The character index is the index of the first logical character represented by the glyph.
  • getGlyphCharIndices(int beginGlyphIndex, int numEntries, int[] codeReturn)
    Returns the character indices of the specified glyphs.
  • getGlyphOutline(int glyphIndex, float x, float y)
    Returns a Shape whose interior corresponds to the visual representation of the specified glyph within this GlyphVector, offset to x, y.
  • getPixelBounds(FontRenderContext renderFRC, float x, float y)
    Returns the pixel bounds of this GlyphVector when rendered in a graphics with the given FontRenderContext at the given location.
  • getGlyphPixelBounds(int index, FontRenderContext renderFRC, float x, float y)
    Returns the pixel bounds of the glyph at index when this GlyphVector is rendered in a Graphics with the given FontRenderContext at the given location.
These new GlyphMetrics methods deal with transformed fonts:
  • getAdvanceX()
    Returns the x-component of the advance of the glyph.
  • getAdvanceY
    Returns the y-component of the advance of the glyph.
Complete Porter-Duff Support

The bugtraq report that corresponds to this change is: 4380232

The AlphaComposite class provides alpha blending capabilities according to modes or rules established by Porter and Duff. Out of the 12 rules that Porter and Duff identified, the AlphaComposite API for the SDK, version 1.3 defines and implements only 8 of them:

  • Clear
  • A (Src)
  • A over B (SrcOver)
  • B over A (DstOver)
  • A in B (SrcIn)
  • B in A (DstIn)
  • A held out by B (SrcOut)
  • B held out by A (DstOut)

For the SDK 1.4, AlphaComposite implements the remaining 4 Porter-Duff rules:

  • B (Dst)
  • A atop B (SrcAtop)
  • B atop A (DstAtop)
  • A xor B (Xor)

Support for Checking if Font has a Transform

The bugtraq report that corresponds to this change is: 4314043

As of the SDK 1.2 the Font object has a transform attribute that can be accessed with the Font.getTransform method. You can perform geometric transformations, such as rotating and shearing, on the Font by setting the transform attribute. However, most applications use the Size attribute rather than the transform to control the size and shape of characters. In this case, the transform is a simple identity transform.

Currently, the only way to determine if the transform is an identity transform is to call getTransform and inspect the returned AffineTransform. Unfortunately, calling getTransform requires the Font object to clone the AffineTransform because the transform is mutable.

Two new methods in the SDK 1.4 allow you to check if a Font object's transform is an identity tranform without creating a new AffineTransform:

  • java.awt.Font.isTransformed:
    Returns true if this Font object has a non-identity AffineTransform attribute.
  • java.awt.font.TransformAttribute.isIdentity:
    Returns true if the wrapped transform is an identity transform.
New Equality Methods for FontRenderContext

The bugtraq report that corresponds to this change is: 4328579

A FontRenderContext object encapsulates state about the graphics context and is used by GlyphVector and TextLayout. Three new methods in FontRenderContext allow you to compare the FontRenderContext in the GlyphVector against the one in the graphics context into which the GlyphVector draws:

  • equals(FontRenderContext)
  • equals(Object)
  • hashCode()
These equals methods also have performance benefits because a client does not have to create an AffineTransform to perform an equality test.

*As used on this web site, the terms "Java Virtual Machine" or "JVM" mean a virtual machine for the Java platform.

Copyright © 1995-2001 Sun Microsystems, Inc. All Rights Reserved.

Please send comments using the Java 2D Feedback page. 		Sun Microsystems, Inc
Java Software


System Properties for Java 2D(TM) Technology

Java

System Properties
for Java 2DTM Technology

 2D Contents

This document describes several unsupported properties that you can use to customize how the 2D painting system operates. You might use these properties to improve performance, fix incorrect rendering, or avoid system crashes under certain configurations. For example, on a small set of Microsoft Windows computers with bad DirectDraw or Direct3D drivers, the use of hardware-accelerated rendering might cause system crashes. You can use properties to specify that on these computers, the Java 2D system shouldn't use DirectDraw or Direct3D.

Warning: Take care when using these properties. Some of them are unsupported for very practical reasons. For example, some behaviors are disabled by default due to driver instabilities; enabling such behaviors could cause system instabilities on some configurations.

Since these properties have the sole purpose of enabling or disabling implementation-specific behaviors, they are subject to change or removal without notification. Some properties might work only on the exact product releases for which they are documented.

2D properties have the prefix sun.java2d.. To specify them, you can use either command-line flags or the _JAVA_OPTIONS environment variable. For example, you can specify the 2D trace property with a flag when running an application, like this:

java -Dsun.java2d.trace=log SomeApp
Or you can specify it by setting _JAVA_OPTIONS before running the application, like this:
export _JAVA_OPTIONS='-Dsun.java2d.trace=log' (UNIX bash shell)
java SomeApp

Some system properties are also settable using environment variables. For example, the d3d property has the equivalent environment variable J2D_D3D. The property description lists the equivalent environment variable, if one exists.

Note: See the High Performance Graphics White Paper for explanations of terms used in property descriptions.

This document lists the following properties:

  • System Properties for All Platforms
    • opengl
    • trace
    • awt.useSystemAAFontSettings
  • System Properties for Microsoft Windows Platforms
    • accthreshold
    • d3d
    • d3dtexbpp
    • ddforcevram
    • ddoffscreen
    • ddscale
    • noddraw
    • translaccel
  • System Properties for Linux and Solaris Platforms
    • NO_J2D_DGA
    • J2D_PIXMAPS
    • pmoffscreen

System Properties for All Platforms

opengl

Intended use: To enable the OpenGL-based pipeline, which provides hardware acceleration.
Introduced: 1.5 Beta 1 (Solaris/Linux); 1.5 Beta 2 (Microsoft Windows)
Default value: false
How to use: To silently enable the OpenGL-based pipeline, set this property to true:

-Dsun.java2d.opengl=true

To receive verbose console output about whether the OpenGL-based pipeline is initialized successfully for a particular screen, set this property to True (note the uppercase T):

-Dsun.java2d.opengl=True

An OpenGL-based pipeline for Java 2D was introduced in 1.5 Beta 1 for Solaris/Linux and 1.5 Beta 2 for Microsoft Windows platforms. This pipeline is currently disabled by default. It provides hardware acceleration for simple rendering operations (text, images, lines, and filled primitives) as well as those that involve complex transforms, paints, composites, and clips.

For more information: The OpenGL section of New Java 2D Features in the Java 2 SDK, v1.5.

trace

Intended use: To help determine the source of less-than-desirable graphics performance.
Introduced: 1.4
How to use: If your application is experiencing less-than-desirable performance, the trace runtime flag can help you determine the source of the problem. The flag is specified with a list of options:

    -Dsun.java2d.trace=[log[,timestamp]],[count],[out:<filename>],[help],[verbose]

The options are:

log
print out the name of each primitive as it is executed
timestamp
precede each log entry with the currentTimeMillis()
count
at exit, print out a count of each primitive used
out:<filename>
send output (logging and counts) to the indicated file
help
print out a short usage statement
verbose
print out a summary of the options chosen for this run

If you use the log option, the Java runtime will print the executed primitives' names, most of which will be in this format:

    <classname>.<methodname>(<src>,<composite>,<dst>)

The methodname represents the basic graphics operation that is used to do the actual rendering work of a Graphics method invocation. These method names will not necessarily map directly to methods on the Graphics object, nor will the number of calls made on the Graphics object map directly to the number of primitive operations performed.

The src and dst represent the type of surfaces or source data involved in the operation.

The composite names match the names in the AlphaComposite class fairly closely with the suffix "NoEa" meaning that the AlphaComposite instance had an "extra alpha" attribute of 1.0. The "SrcNoEa" type is the most commonly used composite type and represents the simplest way of transferring pixels with no blending required. "SrcNoEa" is often used behind the scenes even though the default composite is "SrcOver" when opaque colors and images are rendered because the two operations are indistinguishable for opaque source pixels.

Platform rendering pipelines are sometimes used for doing opaque operations on surfaces accessible by a platform renderer, such as X11, GDI, or DirectDraw. Their names currently use a simplified naming format, which has a prefix for the platform renderer and the name of the operation but without any classname or operand type list. Examples are "X11DrawLine", "GDIFillOval", and "DXFillRect". In the future these names should more closely approximate the names of the other primitives.

awt.useSystemAAFontSettings

Intended use:To override what text anti-aliasing settings are identified as being "desktop settings".
Introduced: 1.6
Default value:true.
How to use:Set on the command line or in a webstart jnlp file as one of the specified values below to control rendering hints used by Swing text.

Strictly this flag doesn't control Java 2D but is documented here because the values all directly map to Java 2D text antialiasing rendering hints values.

What the flag really does is override what the JRE reads from the user's desktop settings as the user's desktop antialiased text preferences. Swing instructs Java 2D to render Swing text to match that preference, so by overriding it you can control Swing text. This applies to standard Swing components (like JTextArea, JButton) in the Metal L&F (aka Java L&F) and native (Windows, GTK) Swing L&Fs. It should also apply to any custom component or L&F which picks up the same property.

For information on the desktop setting this overrides see AWT Desktop Properties

There aren't many reasons for you to specify this property but a couple are

  • The desktop setting you want isn't supported on your desktop (eg you want LCD text on Windows 2000)
  • JRE doesn't recognise your desktop setting (eg KDE)
  • You are automating testing under each of these conditions
System Property Value   | java.awt.RenderingHint value
"off"|"false"|"default" : VALUE_TEXT_ANTIALIAS_DEFAULT
"on"                    : VALUE_TEXT_ANTIALIAS_ON
"gasp"                  : VALUE_TEXT_ANTIALIAS_GASP
"lcd"|"lcd_hrgb"        : VALUE_TEXT_ANTIALIAS_LCD_HRGB
"lcd_hbgr"              : VALUE_TEXT_ANTIALIAS_LCD_HBGR
"lcd_vrgb"              : VALUE_TEXT_ANTIALIAS_LCD_VRGB
"lcd_vbgr"              : VALUE_TEXT_ANTIALIAS_LCD_VBGR

System Properties for Microsoft Windows Platforms

accthreshold

Intended use: To determine how many copies from managed images will occur before a VRAM version of the image is automatically created.
Introduced: 1.4.1_02
Default value: 1
How to use: To force accelerated surfaces to be created during image initialization, set the value to 0, as follows:

-Dsun.java2d.accthreshold=0

This property can be used to eliminate the initial delay in rendering when the images are being copied to the VRAM after the first few copies. Instead, the delay is effectively shifted to the image creation time.

This could be useful behavior when you know that your application will be able to take advantage of image management; just get the overhead of the copy over with at the start instead of incurring some number of slower copies to begin with and then having the copy overhead at some later time.

d3d

Intended use: To turn off the Java 2D system's use of Direct3D.
Introduced: 1.4.1_02
Equivalent environment variable: J2D_D3D
How to use: On a small subset of Windows 2000 systems with buggy Direct3D drivers, the use of Direct3D can cause a system crash. To turn off the use of Direct3D, set this property to false:
-Dsun.java2d.d3d=false
If problems persist, try setting the ddoffscreen property to false. If that doesn't solve the problems, try setting noddraw to true.

d3dtexbpp

Intended use: To specify that accelerated surfaces for managed or translucent images should be in 16-bit (4444) format, which saves VRAM and system memory but at the cost of decreased quality.
Introduced: 1.4.1_02
Default value: 32
How to use: To turn on 4444 format, set this property to 16:

-Dsun.java2d.d3dtexbpp=16
Note: The d3dtexbpp property has no effect if the OpenGL pipeline is in use.

When this property is set to 16, it forces the accelerated surfaces for managed images (created with GraphicsConfiguration.createCompatibleImage(w,h, TRANSLUCENT)) or translucent images loaded with Toolkit.getImage to be in 4444 format. The system memory surface for these images will be in 4444 format as well.

This option is useful when you have lots of images to be stored in VRAM. The downside is poorer quality.

This option is also useful for computers with video boards (such as 3dfx Voodoo3) that don't support 32-bit textures. When the Java 2D system uses 32-bit textures, as it does by default, then when it encounters a card without 32-bit texture support it disables support for accelerated translucent images. If you want acceleration of translucent images on a video board that doesn't support 32-bit textures, set the d3dtexbpp property to 16.

ddforcevram

Intended use: To specify whether VolatileImages should be kept in VRAM.
Introduced: 1.4.1_02
Default value: false in 1.4; as of 1.5 Beta 1, true if translaccel is true, and otherwise false
How to use: Normally, if the 2D system is using the DirectDraw/Direct3D pipeline and detects that an image in video memory is being read from too often (an expensive operation), it punts it to a system memory surface, which is faster to read from. Later, if the system detects that the user is copying from this surface to an accelerated surface again, it promotes it to the video memory. Setting this property to true disables the punting mechanism and always keeps the image in video memory.
Note: The ddforcevram property has no effect if the OpenGL pipeline is in use.

Although this property is often used with the translaccel property, it can be used separately. To set this property to true, either set translaccel to true in a 1.5 release, or set it separately:

-Dsun.java2d.ddforcevram=true

ddoffscreen

Intended use: To turn off the Java 2D system's use of DirectDraw and Direct3D for offscreen surfaces such as the Swing back buffer.
Introduced: 1.4
Default value: true
How to use: Setting this flag to false turns off DirectDraw offscreen surfaces acceleration.

ddscale

Intended use: To turn on hardware-accelerated scaling when the DirectDraw/Direct3D pipeline is in use.
Introduced: 1.2
Default value: false
How to use: Setting this flag to true enables hardware-accelerated scaling if the DirectDraw/Direct3D pipeline is in use. DirectDraw/Direct3D hardware scaling is disabled by default to avoid rendering artifacts in existing applications. These rendering artifacts are caused by possible inconsistencies between the scale method that the software scaling operation uses (nearest neighbor) and the different scale methods that video cards use. Certain events that occur while an application is running might cause a scaled image to be rendered partially with hardware scaling operations and partially with software scaling operations, resulting in an inconsistent appearance. For now, you can enable acceleration by setting the ddscale flag to true.

Note: The ddscale property has no effect if the OpenGL pipeline is in use.

For more information: High Performance Graphics White Paper

noddraw

Intended use: To turn off the Java 2D system's use of DirectDraw and Direct3D completely.
Introduced: 1.2
Default value: false
How to use: Setting this flag to true turns off DirectDraw usage, which sometimes helps to get rid of rendering problems on Win32.

translaccel

Intended use: To specify whether translucent images should be hardware-accelerated when the DirectDraw/Direct3D pipeline is in use.
Introduced: 1.4.1_02
Default value: false
How to use: When the DirectDraw/Direct3D pipeline is being used, both translaccel and ddforcevram must be true for translucent images to be accelerated.

Note: The translaccel property has no effect if the OpenGL pipeline is in use.

To turn on acceleration of translucent images in 1.4 and 1.5:

-Dsun.java2d.translaccel=true
-Dsun.java2d.ddforcevram=true //unnecessary as of 1.5 Beta 1

When both these properties are true, the Java 2D system attempts to put translucent images into VRAM and use Direct3D for rendering (compositing) them to the screen or to a VolatileImage. Only translation transforms are supported (no rotation, scaling, and so on). Before 1.5, to be accelerated a translucent image had to be created in one of the following ways:

  • GraphicsConfiguration.createCompatibleImage(w,h, Transparency.TRANSLUCENT)
  • Images loaded with Toolkit.getImage() that have a translucent color model
As of 1.5, translucent images created with a BufferedImage constructor can also be accelerated. To find out whether an image can be accelerated on a particular device, you can use the Image getCapabilities method (added in 1.5) to get an ImageCapabilities object, which you can query using the isAccelerated method. Note that a managed image gets accelerated only after a certain number of copies to the screen or to another accelerated surface.

The following code fragment illustrates the use of accelerated images. The fragment assumes that back buffer is a VolatileImage. BufferStrategy can be used as well.

Image translucentImage = gc.createCompatibleImage(w, h, Transparency.TRANSLUCENT);
//...
Graphics2D g2 = (Grahics2D)backBuffer.getGraphics();
g2.drawImage(translucentImage, x, y, null);

Compositing with extra alpha with SRC_OVER rule (which is the default Graphics2D compositing rule) is accelerated, so the following code will allow the use of hardware for compositing: Code:

Image translucentImage = gc.createCompatibleImage(w, h, Transparency.TRANSLUCENT);
// ...
float ea = 0.5;
Graphics2D g2 = (Grahics2D)backBuffer.getGraphics();
g2.setComposite(AlphaComposite.getInstance(AlphaComposite.SRC_OVER, ea));
g2.drawImage(translucentImage, x, y, null);

System Properties for Linux and Solaris Platforms

NO_J2D_DGA

Intended use: To turn off DGA support and hardware acceleration on Solaris Sparc, which sometimes helps to reduce rendering artifacts.
Introduced: 1.2
Default value: (unset)
How to use: This property is settable only as an environment variable; it has no command-line flag equivalent. To turn off DGA support and hardware acceleration on Solaris Sparc, define the variable:
setenv NO_J2D_DGA

Setting this variable automatically enables the use of pixmaps, in effect setting pmoffscreen to true. The reverse, however, is not true: setting pmoffscreen to true doesn't disable DGA.

J2D_PIXMAPS

Intended use: To determine whether the 2D system uses shared memory pixmaps in the local display environment for storing images that experience frequent reads.
Introduced: 1.4 Beta 3
Default value: (unset)
How to use: This property is settable only as an environment variable; it has no command-line flag equivalent. As of 1.4 Beta 3, Java 2D starts out using normal pixmaps to store images, but changes the storage of frequently read images to use Shared Memory Pixmaps in the local display environment. You can override this default behavior — and force only one type of pixmap to be used — with J2D_PIXMAPS environment flag:

    setenv J2D_PIXMAPS=shared
    setenv J2D_PIXMAPS=server

If you set this flag to shared, all images are stored in Shared Memory Pixmaps if you are working in a local display environment. Conversely, if you set this flag to server, all images are stored in normal pixmaps, not Shared Memory Pixmaps; the normal pixmaps can be stored in VRAM at the discretion of the device driver.

For more information: High Performance Graphics White Paper

pmoffscreen

Intended use: To determine whether Java 2D stores images in pixmaps by default when DGA is not available.
Introduced: 1.4 Beta 3
Default value: (unset)
How to use: As of 1.4 Beta 3, Java 2D stores images in pixmaps by default when DGA is not available, whether you are working in a local or remote display environment. You can override this behavior with the pmoffscreen flag:

    -Dsun.java2d.pmoffscreen=true
    -Dsun.java2d.pmoffscreen=false

Setting this flag to false disables offscreen pixmap support, which can solve some rendering problems. When the flag is true, offscreen pixmap support is enabled even if DGA is available.

For more information: High Performance Graphics White Paper

Copyright © 1995-2004 Sun Microsystems, Inc. All Rights Reserved.

Please send comments using the Java 2D Feedback page. 		Sun Microsystems, Inc
Java Software


Java 2D(TM) Programmer's Guide, Imaging Sample Programs

These sample programs demonstrate new Java 2DTM Imaging features available in the Java TM 2 SDK, version 1.2 -- you will need to download the Java 2 SDKTM 1.2 or a more recent version of the SDK to run these programs.

Downloading the Sample Programs

Click the following link to download a zip file that contains all of the Imaging sample programs and necessary images.

  • Download Java 2D Imaging Programs and images [zip]

List of Sample Programs

Java Files | Description
BufferedShapeMover.java | Illustrates off-screen buffering.
Blur.java | Illustrates blurring using convolution.
Edge.java | Illustrates edge detection using convolution.
LookUp.java | Illustrates lookup-table manipulation.
Rescale.java | Illustrates rescaling.
Sharpen.java | Illustrates sharpening using convolution.

Compiling the Sample Programs

You can compile a sample by running javac on the sample's .java file. For example, to compile the Blur sample, type:

javac Blur.java

(This assumes javac is in your executible path and that you are using Java 2 SDK 1.2 FCS or greater)

Running the Sample Programs

These sample programs are designed to run as standalone Java applications or applets. To run a sample as an application, execute the java command on the class name. For example, to run the Blur application, type:

java Blur

(This assumes java is in your executible path and that you are using Java 2 SDK 1.2 FCS or greater)

You can also run the samples as applets by running appletviewer on the particular sample's html file. For example, if you would like to run the Blur applet, you would type the following line while you are in the same directory as the html file.

appletviewer Blur.html

(This assumes appletviewer is in your executible path and that you are using Java 2 SDK 1.2 FCS or greater)


Contents | Previous | Next Programmer's Guide to the JavaTM 2D API

Chapter 6

Color

Color imaging is one of the fundamental components of any graphics system, and it is often a source of great complexity in the imaging model. The Java 2D™ API provides support for high-quality color output that is easy to use and allows advanced clients to make sophisticated use of color.

The key color management classes in the Java 2D API are ColorSpace, Color, ColorModel:

  • A ColorSpace represents a system for measuring colors, typically using three separate numerical values or components. The ColorSpace class contains methods for converting between the color space and two standard color spaces, CIEXYZ and RGB.
  • A Color is a fixed color, defined in terms of its components in a particular ColorSpace. To draw a Shape in a color, such as red, you pass a Color object representing that color to the Graphics2D context. Color is defined in the java.awt package.
  • A ColorModel describes a particular way that pixel values are mapped to colors. A ColorModel is typically associated with an Image or BufferedImage and provides the information necessary to correctly interpret the pixel values. ColorModel is defined in the java.awt.image package.

6.1 Classes

Class | Description
ColorSpace | Identifies the color space of a Color object, Image, BufferedImage, or GraphicsDevice. Has methods to transform between RGB and CIEXYZ color spaces.
ICC_ColorSpace | Extends: ColorSpace Represents device-independent and device-dependent color spaces based on the ICC Profile Format Specification.
ICC_Profile | A representation of color profile data for device independent and device dependent color spaces based on the ICC Profile Format Specification.
ICC_ProfileGray | Extends: ICC_Profile A representation of color space type gray.
ICC_ProfileRGB | Extends: ICC_Profile A representation of color space type RGB.

6.2 Color Concepts

A ColorModel is used to interpret pixel data in an image. This includes mapping components in the bands of an image to components of a particular color space. It might also involve extracting pixel components from packed pixel data, retrieving multiple components from a single band using masks, and converting pixel data through a lookup table.

To determine the color value of a particular pixel in an image, you need to know how color information is encoded in each pixel. The ColorModel associated with an image encapsulates the data and methods necessary for translating a pixel value to and from its constituent color components.

The Java 2D™ API provides two color models in addition to the DirectColorModel and IndexColorModel defined in the JDK 1.1 software release:

  • ComponentColorModel can handle an arbitrary ColorSpace and an array of color components to match the ColorSpace. This model can be used to represent most color models on most types of GraphicsDevices.
  • PackedColorModel is a base class for models that represent pixel values that have their color components embedded directly in the bits of an integer pixel. A PackedColorModel stores the packing information that describes how color and alpha components are extracted from the channel.The DirectColorModel in the JDK 1.1 software release is a PackedColorModel.

6.2.0.1 ColorSpace

A ColorSpace object represents a system for measuring colors, typically using three separate numeric values. For example, RGB and CMYK are color spaces. A ColorSpace object serves as a colorspace tag that identifies the specific color space of a Color object or, through a ColorModel object, of an Image, BufferedImage, or GraphicsConfiguration. ColorSpace provides methods that transform Colors in a specific color space to and from sRGB and to and from a well-defined CIEXYZ color space.

All ColorSpace objects must be able to map a color from the represented color space into sRGB and transform an sRGB color into the represented color space. Since every Color contains a ColorSpace object, set explicitly or by default, every Color can also be converted to sRGB. Every GraphicsConfiguration is associated with a ColorSpace object that in turn has an associated ColorSpace. A color specified in any color space can be displayed by any device by mapping it through sRGB as an intermediate color space.

The methods used for this process are toRGB and fromRGB:

  • toRGB transforms a Color in the represented color space to a Color in sRGB.
  • fromRGB takes a Color in sRGB and transforms it into the represented color space.

Though mapping through sRGB always works, it's not always the best solution. For one thing, sRGB cannot represent every color in the full gamut of CIEXYZ colors. If a color is specified in some space that has a different gamut (spectrum of representable colors) than sRGB, then using sRGB as an intermediate space results in a loss of information. To address this problem, the ColorSpace class can map colors to and from another color space, the “conversion space” CIEXYZ.

The methods toCIEXYZ and fromCIEXYZ map color values from the represented color space to the conversion space. These methods support conversions between any two color spaces at a reasonably high degree of accuracy, one Color at a time. However, it is expected that Java 2D API implementations will support high-performance conversion based on underlying platform color-management systems, operating on entire images. (See ColorConvertOp in “Imaging” on page 67.)

Figure 6-1 and Figure 6-2 illustrate the process of translating a color specified in a CMYK color space for display on an RGB color monitor. Figure 6-1 shows a mapping through sRGB. As this figure illustrates, the translation of the CMYK color to an RGB color is not exact because of a gamut mismatch. 1

The previous context describes this graphic.

Figure 6-1 Mapping Through sRGB

Figure 6-2 shows the same process using CIEXYZ as the conversion space. When CIEXYZ is used, the color is passed through accurately.

The previous context describes this graphic.

Figure 6-2 Mapping Through CIEXYZ

6.2.0.2 ICC_Profile and ICC_ColorSpace

ColorSpace is actually an abstract class. The Java 2D API provides one implementation, ICC_ColorSpace, which is based on ICC Profile data as represented by the ICC_Profile class. You can define your own subclasses to represent arbitrary color spaces, as long as the methods discussed above are implemented. However, most developers can simply use the default sRGB ColorSpace or color spaces that are represented by commonly available ICC Profiles, such as profiles for monitors and printers, or profiles embedded in image data.

“ColorSpace” on page 90 describes how ColorSpace objects represent a color space and how colors in the represented space can be mapped to and from a conversion space. Color management systems are often used to handle the mapping between color spaces. A typical color management system (CMS) manages ICC profiles, which are similar to ColorSpace objects; ICC profiles describe an input space and a connection space, and define how to map between them. Color management systems are very good at figuring out how to map a color tagged with one profile into the color space of another profile.

The Java 2D API defines a class called ICC_Profile that holds data for an arbitrary ICC Profile. ICC_ColorSpace is an implementation of the abstract ColorSpace class. ICC_ColorSpace objects can be constructed from ICC_Profiles. (There are some limitations—not all ICC Profiles are appropriate for defining an ICC_ColorSpace).

ICC_Profile has several subclasses that correspond to specific color space types, such as ICC_ProfileRGB and ICC_ProfileGray. Each subclass of ICC_Profile has a well-defined input space (such as an RGB space) and a well-defined connection space (like CIEXYZ). The Java 2D API can use a platform's CMS to access color profiles for various devices such as scanners, printers, and monitors. It can also use the CMS to find the best mapping between profiles.

6.2.1 Describing Colors

The Color class provides a description of a color in a particular color space. An instance of Color contains the value of the color components and a ColorSpace object. Because a ColorSpace object can be specified in addition to the color components when a new instance of Color is created, the Color class can handle colors in any color space.

The Color class has a number of methods that support a proposed standard RGB color space called sRGB (see http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html). sRGB is the default color space for the Java 2D API. Several constructors defined by the Color class omit the ColorSpace parameter. These constructors assume that the color's RGB values are defined in sRGB, and use a default instance of ColorSpace to represent that space.

The Java 2D API uses sRGB as a convenience to application programmers, not as a reference color space for color conversion. Many applications are primarily concerned with RGB images and monitors, and defining a standard RGB color space makes writing such applications easier. The ColorSpace class defines the methods toRGB and fromRGB so that developers can easily retrieve colors in this standard space. These methods are not intended to be used for highly accurate color correction or conversions. See “ColorSpace” on page 90 for more information.

To create a color in a color space other than sRGB, you use the Color constructor that takes a ColorSpace object and an array of floats that represent the color components appropriate to that space. The ColorSpace object identifies the color space.

To display a rectangle of a certain color, such as the process color cyan, you need a way to describe this color to the system. There are a number of different ways to describe a color; for example, a color could be described as a set of red, green, and blue (RGB) components, or a set of cyan, magenta, yellow, and black (CMYK) components. These different techniques for specifying colors are called color spaces.

As you probably know, colors on a computer screen are generated by blending different amounts of red, green, and blue light. Therefore, using an RGB color space is standard for imaging on computer monitors. Similarly, four-color process printing uses cyan, magenta, yellow, and black ink to produce color on a printed page; the printed colors are specified as percentages in a CMYK color space.

Due to the prevalence of computer monitors and color printing, RGB and CMYK color spaces are both commonly used to describe colors. However, both types of color spaces have a fundamental drawback—they are device-dependent. The cyan ink used by one printer might not exactly match the cyan ink used by another. Similarly, a color described as an RGB color might look blue on one monitor and purplish on another.

6.2.2 Mapping Colors through sRGB and CIEXYZ

The Java 2D API refers to RGB and CMYK as color space types. A particular model of monitor with its particular phosphors defines its own RGB color space. Similarly, a particular model of printer has its own CMYK color space. Different RGB or CMYK color spaces can be related to each other through a device-independent color space.

Standards for the device-independent specification of color have been defined by the International Commission on Illumination (CIE). The most commonly used device-independent color space is the three-component XYZ color space developed by CIE. When you specify a color using CIEXYZ, you are insulated from device dependencies.

Unfortunately, it’s not always practical to describe colors in the CIEXYZ color space—there are valid reasons for representing colors in other color spaces. To obtain consistent results when a color is represented using a device-dependent color space such as a particular RGB space, it is necessary to show how that RGB space relates to a device-independent space like CIEXYZ.

One way to map between color spaces is to attach information to the spaces that describes how the device-dependent space relates to the device-independent space. This additional information is called a profile. A commonly used type of color profile is the ICC Color Profile, as defined by the International Color Consortium. For details, see the ICC Profile Format Specification, version 3.4 available at http://www.color.org.

Figure 6-3 illustrates how a solid color and a scanned image are passed to the Java 2D API, and how they are displayed by various output devices. As you can see in Figure 6-3, both the input color and the image have profiles attached.

using profiles to map between color spaces

Figure 6-3 Using Profiles to Map Between Color Spaces

6.2.2.1 Color Matching

Once the API has an accurately specified color, it must reproduce that color on an output device, such as a monitor or printer. These devices have imaging characteristics of their own that must be taken into account to make sure that they produce the correct results. Another profile is associated with each output device to describe how the colors need to be transformed to produce accurate results.

Achieving consistent and accurate color requires that both input colors and output devices be profiled against a standard color space. For example, an input color could be mapped from its original color space into a standard device-independent space, and then mapped from that space to the output device’s color space. In many respects, the transformation of colors mimics the transformation of graphical objects in an (x, y) coordinate space. In both cases, a transformation is used to specify coordinates in a “standard” space and then map those coordinates to a device-specific space for output.

1Of course, the colors used in these diagrams are illustrative, not accurate. The point is that colors might not be mapped accurately between color spaces unless an appropriate conversion space is used.

Contents | Previous | Next Programmer's Guide to the JavaTM 2D API
JavaTM 2 SDK, Standard Edition, 1.4 version

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


Copyright Page for Sun Microsystems, Inc.

Sun Microsystems, Inc.

Copyright 1996-1999 Sun Microsystems, Inc.
901 San Antonio Road, Palo Alto, California 94303-4900 U.S.A.

All rights reserved. Copyright in this document is owned by Sun Microsystems, Inc.

Sun Microsystems, Inc. (SUN) hereby grants to you a fully-paid, nonexclusive, nontransferable, perpetual, worldwide limited license (without the right to sublicense) under SUN's intellectual property rights that are essential to practice this specification. This license allows and is limited to the creation and distribution of clean room implementations of this specification that (i) include a complete implementation of the current version of this specification without subsetting or supersetting, (ii) implement all the interfaces and functionality of the standard java.* packages as defined by SUN, without subsetting or supersetting, (iii) do not add any additional packages, classes or methods to the java.* packages (iv) pass all test suites relating to the most recent published version of this specification that are available from SUN six (6) months prior to any beta release of the clean room implementation or upgrade thereto, (v) do not derive from SUN source code or binary materials, and (vi) do not include any SUN binary materials without an appropriate and separate license from SUN.

RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the U.S. Government is subject to restrictions of FAR 52.227-14(g)(2)(6/87) and FAR 52.227-19(6/87), or DFAR 252.227-7015(b)(6/95) and DFAR 227.7202-1(a).

This software and documentation is the confidential and proprietary information of Sun Microsystems, Inc. ("Confidential Information"). You shall not disclose such Confidential Information and shall use it only in accordance with the terms of the license agreement you entered into with Sun.

SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.

TRADEMARKS

Sun, the Sun logo, Sun Microsystems, SunNet Manager, SunCore, SunWeb, Sun Workshop, Sun Workstation, Java, the Java Coffee Cup logo, JavaSoft, JavaBeans, HotJava, HotJava Views, Java WorkShop, Visual Java, JDK and all Java-based trademarks and logos, Solaris, the Solaris sunburst design, SolarNet, Solstice, NEO, Joe, Netra, NFS, PC-NFS, ONC, ONC+, OpenWindows, SNM, The Network Is The Computer, ToolTalk, Ultra, Ultracomputing, Ultraserver, Where The Network Is Going, and XView, are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.

UNIX is a registered trademark in the United States and other countries, exclusively licensed through X/Open Company, Ltd. OPEN LOOK® is a registered trademark of Novell, Inc.

All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the United States and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc.

The OPEN LOOK® and Sun(TM) Graphical User Interfaces were developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun's licensees who implement OPEN LOOK GUIs and otherwise comply with Sun's written license agreements.

X Window System is a trademark of the X Consortium, Inc.

OpenStep is a trademark owned by NeXT and is used under license.

THIS PUBLICATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.

For further information on Intellectual Property matters, see Terms of Use or contact Sun Legal Department:

  • Trademarks, Karrie Malouf at (650) 336-7419
  • Patents at 415-336-0069


Contents | Previous | Next Programmer's Guide to the JavaTM 2D API

Chapter 4

Fonts and Text Layout

You can use the Java 2D™ API transformation and drawing mechanisms with text strings. In addition, the Java 2D API provides text-related classes that support fine-grain font control and sophisticated text layout. These include an enhanced Font class and the new TextLayout class.

This chapter focuses on the new font and text layout capabilities supported through interfaces and classes in java.awt, and java.awt.font. For more information about using these features, see the 2D Text Tutorial that’s available through the Java Developer Connection at http://developer.java.sun.com/developer/onlineTraining/Graphics/2DText/.

For information about text analysis and internationalization, refer to the java.text documentation and the “Writing Global Programs” track in the Java Tutorial. For information about using the text layout mechanisms implemented in Swing, see the java.awt.swing.text documentation and “Using the JFC/Swing Packages” in the Java Tutorial.

Note: The information on international text layout contained in this chapter is based on the paper International Text in JDK 1.2 by Mark Davis, Doug Felt, and John Raley, copyright 1997, Taligent, Inc.

4.1 Interfaces and Classes

The following tables list the key font and text layout interfaces and classes. Most of these interfaces and classes are part of the java.awt.font package. Some, like Font, are part of the java.awt package to maintain backward compatibility with earlier versions of the JDK.

Interface | Description
MultipleMaster | Represents Type 1 Multiple Master fonts. Implemented by Font objects that are multiple master fonts to enable access to multiple master design controls.
OpenType | Represents Open Type and True Type fonts. Implemented by Font objects that are Open Type or True Type fonts to enable access to the font’s sfnt tables.
Class | Description
Font (java.awt) | Represents an instance of a font face from the collection of font faces available on the host system. Supports the specification of detailed font information and provides access to information about the font and its glyphs.
FontRenderContext | Encapsulates the information necessary to correctly measure text.
GlyphJustificationInfo | Represents information about the justification properties of a glyph, such as weight, priority, absorb, and limit.
GlyphMetrics | Provides metrics for a single glyph.
GlyphVector | A collection of glyphs and their positions.
GraphicAttribute | Base class for a TextLayout attribute that specifies a graphic to be embedded within text. Implemented by ShapeGraphicAttribute and ImageGraphicAttribute, which enable Shapes and Images to be embedded in a TextLayout. Can be subclassed to implement custom character replacement graphics.
ImageGraphicAttribute | Extends: GraphicAttribute A GraphicsAttribute used to draw Images within a TextLayout.
LineBreakMeasurer | Breaks a block of text that spans multiple lines into TextLayout objects that fit within a specified line length.
LineMetrics | Provides access to the font metrics needed to lay out characters along a line and to lay out a set of lines. These metrics include ascent, descent, leading, height, and baseline information.
ShapeGraphicAttribute | Extends: GraphicAttribute A GraphicsAttribute used to draw Shapes within a TextLayout.
TextAttribute | Defines attribute keys and values used for text rendering.
TextHitInfo | Represents hit test information for characters in a TextLayout.
TextLayout | Implements: Cloneable Provides an immutable graphical representation of styled character data, including bidirectional text.

4.2 Font Concepts

The Font class has been enhanced to support the specification of detailed font information and enable the use of sophisticated typographic features.

A Font object represents an instance of a font face from the collection of font faces available on the system. Examples of common font faces include Helvetica Bold and Courier Bold Italic.

Three names are associated with a Font—its logical name, family name, and font face name:

  • A Font object’s logical name is a name mapped onto one of the specific fonts available on the platform. The logical font name is the name used to specify a Font in JDK 1.1 and earlier releases. When specifying a Font in Java™ 2 SDK, you should use the font face name instead of the logical name.You can get the logical name from the Font by calling getName. To get a list of the logical names that are mapped onto the specific fonts available on a platform, call java.awt.Toolkit.getFontList.
  • A Font object’s family name is the name of the font family that determines the typographic design across several faces, such as Helvetica. You retrieve the family name through the getFamily method.
  • A Font objects’ font face name refers to an actual font installed on the system. This is the name you should use when specifying a font in Java 2 SDK. It’s often referred to as just the font name. You can retrieve the font name by calling getFontName. To determine which font faces are available on the system, you can call GraphicsEnvironment.getAllFonts.

You can access information about a Font through the getAttributes method. A Font’s attributes include its name, size, transform, and font features such as weight and posture.

A LineMetrics object encapsulates the measurement information associated with a Font, such as its ascent, descent, and leading:

  • Ascent is the distance from the baseline to the ascender line. This distance represents the typical height of capital letters, but some characters might extend above the ascender line.
  • Descent is the distance from the baseline to the descender line. The lowest point of most characters will fall within the descent, but some characters might extend below the descender line.
  • Leading is the recommended distance from the bottom of the descender line to the top of the next line.

The previous context describes this graphic.

Figure 4-1 Line Metrics

This information is used to properly position characters along a line, and to position lines relative to one another. You can access these line metrics through the getAscent, getDescent, and getLeading methods. You can also access information about a Font’s height, baseline, and underline and strikethrough characteristics through LineMetrics.

4.3 Text Layout Concepts

Before a piece of text can be displayed, it must be properly shaped and positioned using the appropriate glyphs and ligatures. This process is referred to as text layout. The text layout process involves:

  • Shaping text using the appropriate glyphs and ligatures.
  • Properly ordering the text.
  • Measuring and positioning the text.

The information used to lay out text is also necessary for performing text operations such as caret positioning, hit detection, and highlighting.

To develop software that can be deployed in international markets, text must be laid out in different languages in a way that conforms to the rules of the appropriate writing system.

4.3.1 Shaping Text

A glyph is the visual representation of one or more characters. The shape, size, and position of a glyph is dependent on its context. Many different glyphs can be used to represent a single character or combination of characters, depending on the font and style.

For example, in handwritten cursive text, a particular character can take on different shapes depending on how it is connected to adjacent characters.

In some writing systems, particularly Arabic, the context of a glyph must always be taken into account. Unlike in English, cursive forms are mandatory in Arabic; it is unacceptable to present text without using cursive forms.

Depending on the context, these cursive forms can differ radically in shape. For example, the Arabic letter heh has the four cursive forms shown in Figure 4-2.

Illustration of unconnected, connect on right, connect on both sides and connect on left cursive forms in Arabic.

Figure 4-2 Cursive Forms in Arabic

Although these four forms are quite different from one another, such cursive shape-changing is not fundamentally different from cursive writing in English.

In some contexts, two glyphs can change shape even more radically and merge to form a single glyph. This type of merged glyph is called a ligature. For example, most English fonts contain the ligature fi shown in Figure 4-3. The merged glyph takes into account the overhang on the letter f and combines the characters in a natural-looking way, instead of simply letting the letters collide.

The previous context describes this graphic.

Figure 4-3 English Ligatures

Ligatures are also used in Arabic and the use of some ligatures is mandatory—it is unacceptable to present certain character combinations without using the appropriate ligature. When ligatures are formed from Arabic characters, the shapes change even more radically than they do in English. For example, Figure 4-4 illustrates how two Arabic characters are combined into a single ligature when they appear together.

The previous context describes this graphic.

Figure 4-4 Arabic Ligatures

4.3.2 Ordering Text

In the Java™ programming language, text is encoded using Unicode character encoding. Text that uses Unicode character encoding is stored in memory in logical order. Logical order is the order in which characters and words are read and written. The logical order is not necessarily the same as the visual order, the order in which the corresponding glyphs are displayed.

The visual order for glyphs in a particular writing system (script) is called the script order. For example, the script order for Roman text is left-to-right and the script order for Arabic and Hebrew is right-to-left.

Some writing systems have rules in addition to script order for arranging glyphs and words on lines of text. For example, Arabic and Hebrew numbers run left to right, even though the letters run right to left. (This means that Arabic and Hebrew, even with no embedded English text, are truly bidirectional.)

A writing system’s visual order must be maintained even when languages are mixed together. This is illustrated in Figure 4-5, which displays an Arabic phrase embedded in an English sentence.

Note: In this and subsequent examples, Arabic and Hebrew text is represented by uppercase letters and spaces are represented by underscores. Each illustration contains two parts: a representation of the characters stored in memory (the characters in logical order) followed by a representation of how those characters are displayed (the characters in visual order). The numbers below the character boxes indicate the insertion offsets.

The previous context describes this graphic.

Figure 4-5 Bidirectional Text

Even though they are part of an English sentence, the Arabic words are displayed in the Arabic script order, right-to-left. Because the italicized Arabic word is logically after the Arabic in plain text, it is visually to the left of the plain text.

When a line with a mixture of left-to-right and right-to-left text is displayed, the base direction is significant. The base direction is the script order of the predominant writing system. For example, if the text is primarily English with some embedded Arabic, then the base direction is left-to-right. If the text is primarily Arabic with some embedded English or numbers, then the base direction is right-to-left.

The base direction determines the order in which segments of text with a common direction are displayed. In the example shown in Figure 4-5, the base direction is left-to-right. There are three directional runs in this example: the English text at the beginning of the sentence runs left to right, the Arabic text runs right to left, and the period runs left to right.

Graphics are often embedded in the flow of text. These inline graphics behave like glyphs in terms of how they affect the text flow and line wrapping. Such inline graphics need to be positioned using the same bidirectional layout algorithm so that they appear in the proper location in the flow of characters.

For more information about the precise algorithm used to order glyphs within a line, see the description of the Bidirectional Algorithm in The Unicode Standard, Version 2.0, Section 3.11.

4.3.3 Measuring and Positioning Text

Unless you are working with a monospace font, different characters in a font have different widths. This means that all positioning and measuring of text has to take into account exactly which characters are used, not just how many. For example, to right-align a column of numbers displayed in a proportional font, you can’t simply use extra spaces to position the text. To properly align the column, you need to know the exact width of each number so that you can adjust accordingly.

Text is often displayed using multiple fonts and styles, such as bold or italic. In this case, even the same character can have different shapes and widths, depending on how it is styled. To properly position, measure, and render text, you need to keep track of each individual character and the style applied to that character. Fortunately, TextLayout does this for you.

To properly display text in languages such as Hebrew and Arabic, each individual character needs to be measured and positioned within the context of neighboring characters. Because the shapes and positions of the characters can change depending on the context, measuring and positioning such text without taking the context into account produces unacceptable results.

4.3.4 Supporting Text Manipulation

To allow the user to edit the text that is displayed, you must be able to:

  • Display a caret that indicates where new characters will be inserted when the user enters text.
  • Move the caret and insertion point in response to user input.
  • Detect user selections (hit detection).
  • Highlight selected text.

4.3.4.1 Displaying Carets

In editable text, a caret is used to graphically represent the current insertion point, the position in the text where new characters will be inserted. Typically, a caret is shown as a blinking vertical bar between two glyphs. New characters are inserted and displayed at the caret's location.

Calculating the caret position can be complicated, particularly for bidirectional text. Insertion offsets on directional boundaries have two possible caret positions because the two glyphs that correspond to the character offset are not displayed adjacent to one another. This is illustrated in Figure 4-6. In this figure, the carets are shown as square brackets to indicate the glyph to which the caret corresponds.

The previous context describes this graphic.

Figure 4-6 Dual Carets

Character offset 8 corresponds to the location after the _ and before the A. If the user enters an Arabic character, its glyph is displayed to the right of (before) the A; if the user enters an English character, its glyph is displayed to the right of (after) the _.

To handle this situation, some systems display dual carets, a strong (primary) caret and a weak (secondary) caret. The strong caret indicates where an inserted character will be displayed when that character's direction is the same as the base direction of the text. The weak caret shows where an inserted character will be displayed when the character's direction is the opposite of the base direction. TextLayout automatically supports dual carets; JTextComponent does not.

When you’re working with bidirectional text, you can’t simply add the widths of the glyphs before a character offset to calculate the caret position. If you did, the caret would be drawn in the wrong place, as shown in Figure 4-7.

The previous context describes this graphic.

Figure 4-7 Caret Drawn Incorrectly

For the caret to be properly positioned, the widths of the glyphs to the left of the offset need to be added and the current context taken into account. Unless the context is taken into account, the glyph metrics won’t necessarily match the display. (The context can affect which glyphs are used.)

4.3.4.2 Moving Carets

All text editors allow the user to move the caret with the arrow keys. Users expect the caret to move in the direction of the pressed arrow key. In left-to-right text, moving the insertion offset is simple: the right arrow key increases the insertion offset by one and the left arrow key decreases it by one. In bidirectional text or in text with ligatures, this behavior would cause the caret to jump across glyphs at direction boundaries and move in the reverse direction within different directional runs.

To move the caret smoothly through bidirectional text, you need to take into account the direction of the text runs. You can’t simply increment the insertion offset when the right arrow key is pressed and decrement it when the left arrow key is pressed. If the current insertion offset is within a run of right-to-left characters, the right arrow key should decrease the insertion offset, and the left arrow key should increase it.

Moving the caret across a directional boundary is even more complicated. Figure 4-8 illustrates what happens when a directional boundary is crossed when the user is navigating with the arrow key. Stepping three positions to the right in the displayed text corresponds to moving to the character offsets 7, 19, then 18.

The previous context describes this graphic.

Figure 4-8 Caret Movement

Certain glyphs should never have a caret between them; instead, the caret should move as though the glyphs represented a single character. For example, there should never be a caret between an o and an umlaut if they are represented by two separate characters. (See The Unicode Standard, Version 2.0, Chapter 5, for more information.)

TextLayout provides methods (getNextRightHit and getNextLeftHit) that enable you to easily move the caret smoothly through bidirectional text.

4.3.4.3 Hit Testing

Often, a location in device space must be converted to a text offset. For example, when a user clicks the mouse on selectable text, the location of the mouse is converted to a text offset and used as one end of the selection range. Logically, this is the inverse of positioning a caret.

When you’re working with bidirectional text, a single visual location in the display can correspond to two different offsets in the source text, as shown in Figure 4-9.

The previous context describes this graphic.

Figure 4-9 Hit Testing Bidirectional Text

Because a single visual location can correspond to two different offsets, hit testing bidirectional text isn’t just a matter of measuring glyph widths until the glyph at the correct location is found and then mapping that position back to a character offset. Detecting the side that the hit was on helps distinguish between the two alternatives.

You can perform hit testing using TextLayout.hitTestChar. Hit information is encapsulated in a TextHitInfo object and includes information about the side that the hit was on.

4.3.4.4 Highlighting Selections

A selected range of characters is represented graphically by a highlight region, an area in which glyphs are displayed with inverse video or against a different background color.

Highlight regions, like carets, are more complicated for bidirectional text than for monodirectional text. In bidirectional text, a contiguous range of characters might not have a contiguous highlight region when displayed. Conversely, a highlight region showing a visually contiguous range of glyphs might not correspond to a single, contiguous range of characters.

This results in two strategies for highlighting selections in bidirectional text:

  • Logical highlighting —with logical highlighting, the selected characters are always contiguous in the text model, and the highlight region is allowed to be discontiguous. For an example of logical highlighting, see Figure 4-10.
  • Visual highlighting—with visual highlighting, there might be more than one range of selected characters, but the highlight region is always contiguous. For an example of visual highlighting, see Figure 4-11.

Illustration of logical highlighting (contiguous characters)

Figure 4-10 Logical Highlighting (contiguous characters)

Illustration of visual highlighting (contiguous highlight region)

Figure 4-11 Visual Highlighting (contiguous highlight region)

Logical highlighting is simpler to implement, since the selected characters are always contiguous in the text.

4.3.5 Performing Text Layout in a Java™ Application

Depending on which Java™ APIs you use, you can have as little or as much control over text layout as you need:

  • If you just want to display a block of text or need an editable text control, you can use JTextComponent, which will perform the text layout for you. JTextComponent is designed to handle the needs of most international applications and supports bidirectional text For more information about JTextComponent, see “Using the JFC/Swing Packages” in the Java Tutorial.
  • If you want to display a simple text string, you can call Graphics2D.drawString and let Java 2D™ lay out the string for you. You can also use drawString to render styled strings and strings that contain bidirectional text. For more information about rendering text through Graphics2D, see “Rendering Graphics Primitives” on page 37.
  • If you want to implement your own text editing routines, you can use TextLayout to manage text layout, highlighting, and hit detection. The facilities provided by TextLayout handle most common cases, including text strings with mixed fonts, mixed languages, and bidirectional text. For more information about using TextLayout, see “Managing Text Layout” on page 58.
  • If you want total control over how text is shaped and positioned, you can construct your own GlyphVectors using Font and then render them through Graphics2D. For more information about implementing your own text layout mechanism, see “Implementing a Custom Text Layout Mechanism” on page 64.

Generally, you do not need to perform text layout operations yourself. For most applications, JTextComponent is the best solution for displaying static and editable text. However, JTextComponent does not support the display of dual carets or discontiguous selections in bidirectional text. If your application requires these features, or you prefer to implement your own text editing routines, you can use the Java 2D text layout APIs.

4.4 Managing Text Layout

The TextLayout class supports text that contains multiple styles and characters from different writing systems, including Arabic and Hebrew. (Arabic and Hebrew are particularly difficult to display because you must reshape and reorder the text to achieve an acceptable representation.)

TextLayout simplifies the process of displaying and measuring text even if you are working with English-only text. By using TextLayout, you can achieve high-quality typography with no extra effort.

Text Layout Performance
TextLayout is designed so that there is no significant performance impact when it’s used to display simple, monodirectional text. There is some additional processing overhead when TextLayout is used to display Arabic or Hebrew text. However, it’s typically on the order of microseconds per character and is dominated by the execution of normal drawing code.

The TextLayout class manages the positioning and ordering of glyphs for you. You can use TextLayout to:

  • Lay out monodirectional and bidirectional text
  • Display and move carets
  • Perform hit testing on text
  • Highlight text selections

In some situations, you might want to compute the text layout yourself, so that you can control exactly which glyphs are used and where they are placed. Using information such as glyph sizes, kerning tables, and ligature information, you can construct your own algorithms for computing the text layout, bypassing the system’s layout mechanism. For more information, see “Implementing a Custom Text Layout Mechanism” on page 64.

4.4.1 Laying Out Text

TextLayout automatically lays out text, including bidirectional (BIDI) text, with the correct shaping and ordering. To correctly shape and order the glyphs representing a line of text, TextLayout must know the full context of the text:

  • If the text fits on a single line, such as a single-word label for a button or a line in a dialog box, you can construct a TextLayout directly from the text.
  • If you have more text than can fit on a single line or want to break text on a single line into tabbed segments, you cannot construct a TextLayout directly. You must use a LineBreakMeasurer to provide sufficient context.

The base direction of the text is normally set by an attribute (style) on the text. If that attribute is missing, TextLayout follows the Unicode bidirectional algorithm and derives the base direction from the initial characters in the paragraph.

4.4.2 Displaying Dual Carets

TextLayout maintains caret information such as the caret Shape, position, and angle. You can use this information to easily display carets in both monodirectional and bidirectional text. When you’re drawing carets for bidirectional text, using TextLayout ensures that the carets will be positioned correctly.

TextLayout provides default caret Shapes and automatically supports dual carets. For italic and oblique glyphs, TextLayout produces angled carets, as shown in Figure 4-12. These caret positions are also used as the boundaries between glyphs for highlighting and hit testing, which helps produce a consistent user experience.

The previous context describes this graphic.

Figure 4-12 Angled Carets

Given an insertion offset, the getCaretShapes method returns a two-element array of Shapes: element 0 contains the strong caret and element 1 contains the weak caret, if one exists. To display dual carets, you simply draw both caret Shapes; the carets will be automatically be rendered in the correct positions.

If you want to use custom caret Shapes, you can retrieve the position and angle of the carets from the TextLayout and draw them yourself.

In the following example, the default strong and weak caret Shapes are drawn in different colors. This is a common way to differentiate dual carets.

Shape[] caretShapes = layout.getCaretShapes(hit);
g2.setColor(PRIMARY_CARET_COLOR);
g2.draw(caretShapes[0]);
if (caretShapes[1] != null){
  g2.setColor(SECONDARY_CARET_COLOR);
  g2.draw(caretShapes[1]);
}

4.4.3 Moving the Caret

You can also use TextLayout to determine the resulting insertion offset when a user presses the left or right arrow key. Given a TextHitInfo object that represents the current insertion offset, the getNextRightHit method returns a TextHitInfo object that represents the correct insertion offset if the right arrow key is pressed. The getNextLeftHit method provides the same information for the left arrow key.

In the following example, the current insertion offset is moved in response to a right arrow key.

TextHitInfo newInsertionOffset =             layout.getNextRightHit(insertionOffset);
if (newInsertionOffset != null) {
  Shape[] caretShapes =
          layout.getCaretShapes(newInsertionOffset);
  // draw carets
  ...
  insertionOffset = newInsertionOffset;
}

4.4.4 Hit Testing

TextLayout provides a simple mechanism for hit testing text. The hitTestChar method takes x and y coordinates from the mouse as arguments and returns a TextHitInfo object. The TextHitInfo contains the insertion offset for the specified position and the side that the hit was on. The insertion offset is the offset closest to the hit: if the hit is past the end of the line, the offset at the end of the line is returned.

In the following example, hitTestChar is called on a TextLayout and then getInsertIndex is used to retrieve the offset.

TextHitInfo hit = layout.hitTestChar(x, y);
int insertIndex = hit.getInsertIndex();

4.4.5 Highlighting Selections

You can get a Shape that represents the highlight region from the TextLayout. TextLayout automatically takes the context into account when calculating the dimensions of the highlight region. TextLayout supports both logical and visual highlighting.

In the following example, the highlight region is filled with the highlight color and then the TextLayout is drawn over the filled region. This is one simple way to display highlighted text.

Shape highlightRegion = layout.getLogicalHighlightShape(hit1,      hit2);
graphics.setColor(HIGHLIGHT_COLOR);
graphics.fill(highlightRegion);
graphics.drawString(layout, 0, 0);

4.4.6 Querying Layout Metrics

TextLayout provides access to graphical metrics for the entire range of text it represents. Metrics available from TextLayout include the ascent, descent, leading, advance, visible advance, and the bounding rectangle.

More than one Font can be associated with a TextLayout: different style runs can use different fonts. The ascent and descent values for a TextLayout are the maximum values of all of the fonts used in the TextLayout. The computation of the TextLayout's leading is more complicated; it’s not just the maximum leading value.

The advance of a TextLayout is its length: the distance from the left edge of the leftmost glyph to the right edge of the rightmost glyph. The advance is sometimes referred to as the total advance. The visible advance is the length of the TextLayout without its trailing whitespace.

The bounding box of a TextLayout encloses all of the text in the layout. It includes all the visible glyphs and the caret boundaries. (Some of these might hang over the origin or origin + advance). The bounding box is relative to the origin of the TextLayout, not to any particular screen position.

In the following example, the text in a TextLayout is drawn within the layout’s bounding box.

graphics.drawString(layout, 0, 0);
Rectangle2D bounds = layout.getBounds();
graphics.drawRect(bounds.getX()-1, bounds.getY()-1,
         bounds.getWidth()+2, bounds.getHeight()+2);

4.4.7 Drawing Text Across Multiple Lines

TextLayout can also be used to display a piece of text that spans multiple lines. For example, you might take a paragraph of text, line-wrap the text to a certain width, and display the paragraph as multiple lines of text.

To do this, you do not directly create the TextLayouts that represent each line of text—LineBreakMeasurer generates them for you. Bidirectional ordering cannot always be performed correctly unless all of the text in a paragraph is available. LineBreakMeasurer encapsulates enough information about the context to produce correct TextLayouts.

When text is displayed across multiple lines, the length of the lines is usually determined by the width of the display area. Line breaking (line wrapping) is the process of determining where lines begin and end, given a graphical width in which the lines must fit.

The most common strategy is to place as many words on each line as will fit. This strategy is implemented in LineBreakMeasurer. Other more complex line break strategies use hyphenation, or attempt to minimize the differences in line length within paragraphs. The Java 2D™ API does not provide implementations of these strategies.

To break a paragraph of text into lines, you construct a LineBreakMeasurer with the entire paragraph and then call nextLayout to step through the text and generate TextLayouts for each line.

To do this, LineBreakMeasurer maintains an offset within the text. Initially, the offset is at the beginning of the text. Each call to nextLayout moves the offset by the character count of the TextLayout that was created. When this offset reaches the end of the text, nextLayout returns null.

The visible advance of each TextLayout that the LineBreakMeasurer creates doesn’t exceed the specified line width. By varying the width you specify when you call nextLayout, you can break text to fit complicated areas, such as an HTML page with images in fixed positions or tab-stop fields. You can also pass in a BreakIterator to tell LineBreakMeasurer where valid breakpoints are; if you don't supply one the BreakIterator for the default locale is used.

In the following example, a bilingual text segment is drawn line by line. The lines are aligned to either to the left margin or right margin, depending on whether the base text direction is left-to-right or right-to-left.

Point2D pen = initialPosition;
LineBreakMeasurer measurer = new LineBreakMeasurer(styledText, myBreakIterator);
while (true) {
  TextLayout layout = measurer.nextLayout(wrappingWidth);
  if (layout == null) break;
    pen.y += layout.getAscent();
    float dx = 0;
    if (layout.isLeftToRight())
      dx = wrappingWidth - layout.getAdvance();
    layout.draw(graphics, pen.x + dx, pen.y);
    pen.y += layout.getDescent() + layout.getLeading();
}

4.5 Implementing a Custom Text Layout Mechanism

The GlyphVector class provides a way to display the results of custom layout mechanisms. A GlyphVector object can be thought of as the output of an algorithm that takes a string and computes exactly how the string should be displayed. The system has a built-in algorithm and the Java 2D™ API lets advanced clients define their own algorithms.

A GlyphVector object is basically an array of glyphs and glyph locations. Glyphs are used instead of characters to provide total control over layout characteristics such as kerning and ligatures. For example, when displaying the string “final”, you might want to replace the leading fi substring with the ligature fi. In this case, the GlyphVector object will have fewer glyphs than the number of characters in the original string.

Figure 4-13 and Figure 4-14 illustrate how GlyphVector objects are used by layout mechanisms. Figure 4-13 shows the default layout mechanism. When drawString is called on a String, the built-in layout algorithm:

  • Uses the current Font in the Graphics2D context to determine which glyphs to use.
  • Calculates where each glyph should be placed.
  • Stores the resulting glyph and position information in a GlyphVector.
  • Passes the GlyphVector to a glyph rendering routine that does the actual drawing.

The previous context describes this graphic.

Figure 4-13 Using the Built-in Layout Algorithm

Figure 4-14 shows the process for using a custom layout algorithm. To use a custom layout algorithm, you must assemble all of the information necessary to lay out the text. The basic process is the same:

  • Using the Font, determine which glyphs to use
  • Determine where to place the glyphs
  • Store this layout information in a GlyphVector

To render the text, you pass the GlyphVector to drawString, which in turn passes it to the glyph renderer. In Figure 4-14, the custom layout algorithm replaces the fi substring with the ligature fi.

using a custom layout algorithm

Figure 4-14 Using a Custom Layout Algorithm

4.6 Creating Font Derivations

Using the Font.deriveFont methods, you can create a new Font object with different attributes from an existing Font object. Often, a transform is applied to the existing Font to create a new derived Font. To do this, you:

  1. Create a Font object.,
  2. Create the AffineTransform you want to apply to the Font.
  3. Call Font.deriveFont, passing in the AffineTransform.

In this way, you could easily create a Font in a custom size or a skewed version of an existing Font.

In the following code excerpt, an AffineTransform is applied to create a skewed version of the font Helvetica. The new derived font is then used to render a string.

    // Create a transformation for the font.
AffineTransform fontAT = new AffineTransform();
fontAT.setToShear(-1.2, 0.0);
// Create a Font Object.
Font theFont = new Font("Helvetica", Font.PLAIN, 1);
// Derive a new font using the shear transform
theDerivedFont = theFont.deriveFont(fontAT);
// Add the derived font to the Graphics2D context
g2.setFont(theDerivedFont);
// Render a string using the derived font
g2.drawString(“Java”, 0.0f, 0.0f);

Contents | Previous | Next Programmer's Guide to the JavaTM 2D API
JavaTM 2 SDK, Standard Edition, 1.4 version

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


Contents | Previous | Next Programmer's Guide to the JavaTM 2D API

Chapter 3

Geometries

The Java 2D™ API provides several classes that define common geometric objects, such as points, lines, curves, and rectangles. These new geometry classes are part of the java.awt.geom package. For backward compatibility, the geometry classes that existed in previous versions of the JDK software, such as Rectangle, Point, and Polygon, remain in the java.awt package.

The Java 2D API geometries such as GeneralPath, Arc2D, and Rectangle2D implement the Shape interface defined in java.awt. Shape provides a common protocol for describing and inspecting geometric path objects. A new interface, PathIterator, defines methods for retrieving elements from a geometry.

Using the geometry classes, you can easily define and manipulate virtually any two-dimensional object.

3.1 Interfaces and Classes

The following tables list the key geometry interfaces and classes. Most of these interfaces and classes are part of the java.awt.geom package. Some, like Shape, are part of the java.awt package, primarily to maintain backward compatibility with earlier versions of the JDK software.

Interface | Description
PathIterator | Defines methods for retrieving elements from a path.
Shape (java.awt) | Provides a common set of methods for describing and inspecting geometric path objects. Implemented by GeneralPath and other geometry classes.

Class
Description
Arc2D
Arc2D.Double
Arc2D.Float
Extends: RectangularShape
Represents an arc defined by a bounding rectangle, start angle, angular extent, and a closure type. Implemented to specify arcs in float and double precision: Arc2D.Float and Arc2D.Double.
Area
Implements: Shape, Cloneable
Represents an area geometry that supports boolean operations.
CubicCurve2D
CubicCurve2D.Double
CubicCurve2D.Float
Implements: Shape
Represents a cubic parametric curve segment in (w) coordinate space. Implemented to specify cubic curves in float and double precision: CubicCurve2D.Float and CubicCurve2D.Double.
Dimension2D
Encapsulates a width and height dimension. Abstract superclass for all objects that store a 2D dimension.
Ellipse2D
Ellipse2D.Double
Ellipse2D.Float
Extends: RectangularShape
Represents an ellipse defined by a bounding rectangle. Implemented to specify ellipses in float and double precision: Ellipse2D.Float and Ellipse2D.Double.
FlatteningPathIterator
Returns a flattened view of a PathIterator object.
Can be used to provide flattening behavior for Shapes that don’t perform the interpolation calculations themselves.
GeneralPath
Implements: Shape
Represents a geometric path constructed from lines and quadratic and cubic curves.
Line2D
Line2D.Double
Line2D.Float
Implements: Shape
Represents a line segment in (x, y) coordinate space. Implemented to specify lines in float and double precision: Line2D.Float and Line2D.Double.
Point2D
Point2D.Double
Point2D.Float
A point representing a location in (x,y) coordinate space. Implemented to specify points in float and double precision: Point2D.Float and Point2D.Double.
QuadCurve2D
QuadCurve2D.Double
QuadCurve2D.Float
Implements: Shape
Represents a quadratic parametric curve segment in (x, y) coordinate space. Implemented to specify quadratic curves in float and double precision: QuadCurve2D.Float and QuadCurve2D.Double.
Rectangle2D
Rectangle2D.Double
Rectangle2D.Float
Extends: RectangularShape
Represents a rectangle defined by a location (x, y) and dimension (w x h). Implemented to specify rectangles in float and double precision: Rectangle2D.Float and Rectangle2D.Double.
RectangularShape
Implements: Shape
Provides common manipulation routines for operating on shapes that have rectangular bounds.
RoundRectangle2D
RoundRectangle2D.Double
RoundRectangle2D.Float
Extends: RectangularShape
Represents a rectangle with rounded corners defined by a location (x, y), a dimension (w x h), and the width and height of the corner arc. Implemented to specify round rectangles in float and double precision: RoundRectangle2D.Float and RoundRectangle2D.Double.

3.2 Geometry Concepts

A Shape is an instance of any class that implements the Shape interface, such as GeneralPath or Rectangle2D.Float. A Shape’s contour (outline) is referred to as its path.

When a Shape is drawn, the pen style defined by the Stroke object in the Graphics2D context is applied to the Shape’s path. When a Shape is filled, the Paint in the Graphics2D context is applied to the area within its path. For more information, see “Rendering with Graphics2D” on page 15.

A Shape’s path can be also used to define a clipping path. A clipping path determines what pixels are rendered—only those pixels that lie within the area defined by the clipping path are rendered. The clipping path is part of the Graphics2D context. For more information, see “Setting the Clipping Path” on page 32.

A GeneralPath is a shape that can be used to represent any two-dimensional object that can be constructed from lines and quadratic or cubic curves. For convenience, java.awt.geom provides additional implementations of the Shape interface that represent common geometric objects such as rectangles, ellipses, arcs, and curves. The Java2D™ API also provides a special type of shape that supports constructive area geometry.

3.2.1 Constructive Area Geometry

Constructive Area Geometry (CAG) is the process of creating new geometric objects by performing boolean operations on existing objects. In the Java 2D API, a special type of Shape called an Area supports boolean operations. You can construct an Area from any Shape.

Areas support the following Boolean operations:

  • Union
  • Intersection
  • Subtraction
  • Exclusive OR (XOR)

These operations are illustrated in Figure 3-1.

Graphic illustration of union, intersection, subtraction and exclusive OR boolean operations

Figure 3-1 Boolean Operations

3.2.2 Bounds and Hit Testing

A bounding box is a rectangle that fully encloses a shape’s geometry. Bounding boxes are used to determine whether or not an object has been selected or “hit” by the user.

The Shape interface defines two methods for retrieving a shape’s bounding box, getBounds and getBounds2D. The getBounds2D method returns a Rectangle2D instead of a Rectangle, providing a higher-precision description of the shape’s bounding box.

Shape also provides methods for determining whether or not:

  • A specified point lies within the bounds of the shape (contains)
  • A specified rectangle lies totally within the bounds of the shape (contains)
  • A specified rectangle intersects the shape (intersects)

3.3 Combining Areas to Create New Shapes

Areas can be used to quickly construct complex Shapes from simple shapes such as circles and squares. To create a new complex Shape by combining Areas:

  1. Using Shapes, construct the Areas to be combined.
  2. Call the appropriate Boolean operators: add, subtract, intersect, exclusiveOr.

For example, CAG could be used to create a pear like that shown in Figure 3-2 .

The following context describes the graphic

Figure 3-2 Pear constructed from circles

The body of the pear is constructed by performing a union operation on two overlapping Areas: a circle and an oval. The leaves are each created by performing an intersection on two overlapping circles and then joined into a single Shape through a union operation. Overlapping circles are also used to construct the stem through two subtraction operations.

3.4 Creating a Custom Shape

You can implement the Shape interface to create a class that defines a new type of shape. It doesn’t matter how you represent the shape internally, as long as you can implement the Shape interface methods. The Shape must be able to generate a path that specifies its contour.

For example, you could create a simple implementation of Shape that represents polygons as arrays of points. Once the polygon is built, it could be passed to draw, setClip, or any other method that expects a Shape object as an argument.

The PolygonPath class must implement the Shape interface methods:

  • contains
  • getBounds
  • getBounds2D
  • getPathIterator
  • intersects

Contents | Previous | Next Programmer's Guide to the JavaTM 2D API
JavaTM 2 SDK, Standard Edition, 1.4 version

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


Contents | Previous | Next Programmer's Guide to the JavaTM 2D API

Chapter 5

Imaging

The Java 2D™ API supports three imaging models

  • The producer/consumer (push) model provided in previous versions of the JDK software.
  • The immediate mode model introduced in the Java™ 2 SDK software release.
  • The pipeline (pull) model compatible with the immediate mode model and that will be fully implemented in the forthcoming Java Advanced Imaging API.

The following table contrasts the features of each of these imaging models.

Push Model
Immediate Mode Image Buffer Model
Pull Model
Major Interfaces/Classes
  • Image
  • ImageProducer
  • ImageConsumer
  • ImageObserver
     (JDK 1.0.x, 1.1.x)
  • BufferedImage
  • Raster
  • BufferedImageOp
  • RasterOp
    (JavaTM 2D API)
  • RenderableImage
  • RenderableImageOp
    (Java 2D API)
  • RenderedOp
  • RenderableOp
  • TiledImage
    (Java Advanced Imaging API)
Pros
  • Processing driven by image availability (e.g. over network)
  • Images processed incrementally
  • Simplest programming interface
  • Commonly used model
  • Stores/processes only required data
  • Allows lazy evaluation
Cons
  • Requires transfer (but not processing)
  • More complex programming interface
  • Requires memory allocation of complete images
  • Requires processing of complete images
  • More complex programming interface
  • More complex implementation

This chapter focuses on the objects and techniques of the immediate mode imaging model. The immediate mode imaging classes and interfaces of the Java 2D API provide techniques for dealing with pixel mapped images whose data is stored in memory. This API supports accessing image data in a variety of storage formats and manipulating image data through several types of filtering operations.

5.1 Interfaces and Classes

The immediate mode imaging APIs in the Java 2D™ API can be grouped into six categories: interfaces, image data classes, image operation classes, sample model classes, color model classes, and exceptions.

5.1.1 Imaging Interfaces

Interface | Description
BufferedImageOp | Describes single-input/single-output operations performed on BufferedImage objects. Implemented by AffineTransformOp, ColorConvertOp, ConvolveOp, LookupOp, and RescaleOp.
RasterOp | Defines single-input/single-output operations performed on Raster objects. Implemented by AffineTransformOp, BandCombineOp, ColorConvertOp, ConvolveOp, LookupOp, and RescaleOp.
RenderedImage | Defines a common protocol for objects that contain or can produce image data in the form of Rasters.
WritableRenderedImage | Extends: RenderedImage Defines a common protocol for objects that contain or can produce image data in the form of Rasters which can be modified.
TileObserver | Defines a protocol for objects that want to be notified when the modification state of a WritableRenderedImage changes.

5.1.2 Image Data Classes

Class | Description
BufferedImage | Extends: Image Implements: WriteableRenderedImage An image with an accessible data buffer. A BufferedImage has a ColorModel and a Raster of image data.
ByteLookupTable | Extends: LookupTable A LookupTable that contains byte data.
DataBuffer | Wraps one or more data arrays holding pixel data. Each data array is called a bank.
DataBufferByte | Extends: DataBuffer (Final) A data buffer that stores bytes of data. (Used in Java Advanced Imaging API)
DataBufferInt | Extends: DataBuffer (Final)) A data buffer that stores integer data.(Used in Java Advanced Imaging API)
DataBufferShort | Extends: DataBuffer (Final) A data buffer that stores short data.(Used in Java Advanced Imaging API)
DataBufferUShort | Extends: DataBuffer (Final) A data buffer that stores unsigned short data.
Kernel | A matrix that describes how an input pixel and its surrounding pixels affect the value of an output pixel in a ConvolveOp filtering operation.
LookupTable | Extends: Object A table that maps values from single-banded pixel data to color values.
Raster | A rectangular array of pixels from which you can retrieve image data. A Raster contains a DataBuffer and a SampleModel.
ShortLookupTable | Extends: LookupTable A lookup table that contains short data.
WritableRaster | Extends: Raster A Raster that you can modify.

5.1.3 Image Operation Classes

Class | Description
AffineTransformOp | Implements: BufferedImageOp, RasterOp A class that defines an affine transform to perform a linear mapping from 2D coordinates in a source Image or Raster to 2D coordinates in the destination image or Raster. This class can perform either bilinear or nearest neighbor affine transform operations.
BandCombineOp | Implements: RasterOp Using a specified matrix, this operation performs an arbitrary linear combination of bands in a Raster.
BufferedImageFilter | Extends: ImageFilter An ImageFilter that provides a simple means of using a BufferedImageOp (a single-source/single-destination image operator) to filter a BufferedImage or Raster.
ColorConvertOp | Implements: BufferedImageOp, RasterOp Performs a pixel-by-pixel color conversion of the data in the source image.
ConvolveOp | Implements: BufferedImageOp, RasterOp Uses a Kernel to perform a convolution on the source image. A convolution is a spatial operation where the pixels surrounding the input pixel are multiplied by a kernel value to generate the value of the output pixel. The Kernel mathematically defines the relationship between the pixels in the immediate neighborhood of the input pixel and the output pixel.
LookupOp | Implements: BufferedImageOp, RasterOp Performs a lookup operation from the source to the destination. For Rasters, the lookup operates on sample values. For BufferedImages, the lookup operates on color and alpha components.
RescaleOp | Implements: BufferedImageOp, RasterOp Performs a pixel-by-pixel rescaling of the data in the source image by multiplying each pixel value by a scale factor and then adding an offset.

5.1.4 Sample Model Classes

Class | Description
BandedSampleModel | Extends: ComponentSampleModel (Final) Provides access to image data stored with like samples stored as bands in separate banks of a DataBuffer. A pixel consists of one sample from each band.
ComponentSampleModel | Extends: SampleModel Provides access to image data stored with each sample of a pixel residing in a separate element of a DataBuffer. Different types of pixel interleaving are supported.
MultiPixelPackedSampleModel | Extends: SampleModel Provides access to image data stored with multiple one-sample pixels packed into one element of a DataBuffer.
PixelInterleavedSampleModel | Extends: ComponentSampleModel Provides access to image data stored with the sample data for each pixel in adjacent elements of the data array, and all elements in a single bank of a DataBuffer.
SampleModel | An abstract class that defines a mechanism for extracting sample data from an image without knowing how the underlying data is stored in a DataBuffer.
SinglePixelPackedSampleModel | Extends: SampleModel Provides access to image data stored with all the samples belonging to an individual pixel packed into one element of a DataBuffer.

5.1.5 Color Model Classes

Class | Description
ColorModel | Implements: Transparency JDK1.1 class. An abstract class that defines methods for translating from image pixel values to color components such as red, green, and blue.
ComponentColorModel | Extends: ColorModel A ColorModel that can handle an arbitrary ColorSpace and an array of color components to match the ColorSpace. This class can be used to represent most color models on most types of GraphicsDevices.
DirectColorModel | Extends: PackedColorModel JDK1.1 class. A ColorModel that represents pixel values that have RGB color components embedded directly in the bits of the pixel. This color model is similar to an X11 TrueColor visual. The default RGB ColorModel returned by ColorModel.getRGBdefault is a DirectColorModel.
IndexColorModel | Extends: ColorModel JDK1.1 class. A ColorModel that represents pixel values that are indices into a fixed color map in the sRGB ColorSpace.
PackedColorModel | Extends: ColorModel An abstract ColorModel that represents pixel values that have color components embedded directly in the bits of a pixel. DirectColorModel extends PackedColorModel to support pixels that contain RGB color components.

5.1.6 Exception Classes

Class | Description
ImagingOpException | Extends: RuntimeException Thrown if one of the BufferedImageOp or RasterOp filter methods can’t process the image.
RasterFormatException | Extends: RuntimeException Thrown if there is invalid layout information in the Raster.

5.2 Immediate Mode Imaging Concepts

The immediate mode imaging model supports fixed-resolution images stored in memory. The model also supports filtering operations on image data. A number of classes and interfaces are used in this model.

The following context describes this graphic.

Figure 5-1 BufferedImage and supporting classes

As shown in Figure 5-1, BufferedImage provides general image management. A BufferedImage can be created directly in memory and used to hold and manipulate image data retrieved from a file or URL. A BufferedImage can be displayed using any Graphics2D object for a screen device, or rendered to any other destination using appropriate Graphics2D context. A BufferedImage object contains two other objects: a Raster and a ColorModel.

The Raster class provides image data management. It represents the rectangular coordinates of the image, maintains image data in memory, and provides a mechanism for creating multiple subimages from a single image data buffer. It also provides methods for accessing specific pixels within an image. A Raster object contains two other objects, a DataBuffer and a SampleModel.

The DataBuffer class holds pixel data in memory.

The SampleModel class interprets data in the buffer and provides it as individual pixels or rectangular ranges of pixels.

The ColorModel class provides a color interpretation of pixel data provided by the image’s sample model.

The image package provides additional classes that define filtering operations on BufferedImage and Raster objects. Each image processing operation is embodied in a class that implements the BufferedImageOp interface, the RasterOp interface, or both interfaces. The operation class defines filter methods that performs the actual image manipulation.

Figure 5-2 illustrates the basic model for Java 2D™ API image processing:

Flow diagram shows that the source image flows through an image-processing operation before becoming the destination image.

Figure 5-2 Image Processing Model

The operations supported include:

  • Affine transformation
  • Amplitude scaling
  • Lookup-table modification
  • Linear combination of bands
  • Color conversion
  • Convolution

Note that if you’re interested just in displaying and manipulating images, you only need to understand the BufferedImage class and the filtering operation classes. On the other hand, if you’re planning to write filters or otherwise directly access image data, you’ll need to understand the classes associated with BufferedImage.

5.2.1 Terminology

Here are some terms used throughout the following discussions:

Data Elements: primitive types used as units of storage of image data. Data elements are individual members of a DataBuffer array. The layout of elements in the data buffer is independent of the interpretation of the data as pixels by an image’s SampleModel.

Samples: distinct members of the pixels of an image. A SampleModel provides a mechanism for converting elements in the DataBuffer to pixels and their samples. The samples of a pixel may represent primary values in a particular color model. For example, a pixel in an RGB color model consists of three samples: red, green, and blue.

Components: values of pixels independent of color interpretation. The distinction between component and sample is useful with IndexColorModel, where pixel components are indexes into the LookupTable.

Band: the set of all samples of one type in an image, such as all red samples or all green samples. Pixel data can be stored in a number of ways, the two supported in the Java 2D API being banded and pixel interleaved. Banded storage organizes image data by bands, and a pixel is made up of sample data from the same position in each band. Pixel interleaved storage organizes image data by pixels, with a single array containing all pixels, and bands consisting of the set of samples at the same index position in each pixel.

Primaries: distinct members of a color value in a specific color model; for example the RGB model forms color values from the primaries red, green, and blue.

5.3 Using BufferedImages

The BufferedImage class is the main class supporting the immediate imaging mode. It manages an image in memory, providing ways to store pixel data, interpret pixel data, and to render the pixel data to a Graphics or Graphics2D context.

5.3.1 Creating a BufferedImage

To create a BufferedImage, call the Component.createImage method; this returns a BufferedImage whose drawing characteristics match those of the component used to create it—the created image is opaque, has the foreground and background colors of the Component, and you can’t adjust the transparency of the image. You could use this technique when you want to do double buffered drawing for animation in a component; the discussion “Drawing in an Offscreen Buffer” on page 79 gives more details.

    public Graphics2D createDemoGraphics2D(Graphics g) {
        Graphics2D g2 = null;
        int width = getSize().width;
        int height = getSize().height;

        if (offImg == null || offImg.getWidth() != width ||
                        offImg.getHeight() != height) {
            offImg = (BufferedImage) createImage(width, height);
        }

        if (offImg != null) {
            g2 = offImg.createGraphics();
            g2.setBackground(getBackground());
        }

        // .. clear canvas ..
        g2.clearRect(0, 0, width, height);

        return g2;
    }

You can also create a blank BufferedImage in memory using one of several constructor methods provided.

5.3.2 Drawing in an Offscreen Buffer

The BufferedImage class can be used to prepare graphic elements offscreen then copy them to the screen. This technique is especially useful when a graphic is complex or used repeatedly. For example, if you want to display a complicated shape several times, you could draw it once into an offscreen buffer and then copy it to different locations in the window. By drawing the shape once and copying it, you can display the graphics more quickly.

The java.awt package facilitates the use of offscreen buffers by letting you draw to an Image object the same way that you draw to a window. All of the Java 2D™ API rendering features can be used when drawing to offscreen images.

Offscreen buffers are often used for animation. For example, you could use an offscreen buffer to draw an object once and then move it around in a window. Similarly, you could use an offscreen buffer to provide feedback as a user moves a graphic using the mouse. Instead of redrawing the graphic at every mouse location, you could draw the graphic once to an offscreen buffer, and then copy it to the mouse location as the user drags the mouse.1

The following context describes this graphic.

Figure 5-3 Using an Offscreen Buffer

Figure 5-3 demonstrates how a program can draw to an offscreen image and then copy that image into a window multiple times. The last time the image is copied, it is transformed. Note that transforming the image instead of redrawing it with the transformation might produce unsatisfactory results.

5.3.2.1 Creating an Offscreen Buffer

The simplest way to create an image that you can use as an offscreen buffer is to use the Component.createImage method.

By creating an image whose color space, depth, and pixel layout exactly match the window into which you are drawing, the image can be efficiently blitted to a graphics device. This allows drawImage to do its job quickly.

You can also construct a BufferedImage object directly to use as an offscreen buffer. This is useful when you need control over the offscreen image’s type or transparency.

BufferedImage supports several predefined image types:

  • TYPE_3BYTE_BGR
  • TYPE_4BYTE_ABGR
  • TYPE_4BYTE_ABGR_PRE
  • TYPE_BYTE_BINARY
  • TYPE_BYTE_GRAY
  • TYPE_BYTE_INDEXED
  • TYPE_CUSTOM
  • TYPE_INT_ARGB_PRE
  • TYPE_INT_ARGB
  • TYPE_INT_BGR
  • TYPE_INT_RGB
  • TYPE_USHORT_555_RGB
  • TYPE_USHORT_565_RGB
  • TYPE_INT_GRAY

A BufferedImage object can contain an alpha channel. In Figure 5-3, an alpha channel is used to distinguish painted and unpainted areas, allowing an irregular shape to appear over graphics that have already been painted (in this case, a shaded rectangle). In other cases, you might use alpha channel to blend the colors of the new image into those in the existing image.

Note: unless you need alpha image data for transparency, as with the irregularly shaped images shown in Figure 5-2, you should avoid creating an off-screen buffer with alpha. Using alpha where it’s unnecessary slows rendering performance.

GraphicsConfiguration provides convenience methods that automatically create buffered images in a format compatible with your configuration. You can also query the graphics configuration associated with the graphics device on which the window resides to get the information you need to construct a compatible BufferedImage object.

5.3.2.2 Drawing in an Offscreen Buffer

To draw in a buffered image, you call its BufferedImage.createGraphics method, which returns a Graphics2D object. With this object, you can call all of the Graphics2D methods to draw graphics primitives, place text, and render other images in the image. This drawing technique supports dithering and other enhancements provided by the 2D imaging package. The following code illustrates the use of offscreen buffering:

    public void update(Graphics g){
        Graphics2D g2 = (Graphics2D)g;
        if(firstTime){
            Dimension dim = getSize();
            int w = dim.width;
            int h = dim.height;
            area = new Rectangle(dim);
            bi = (BufferedImage)createImage(w, h);
            big = bi.createGraphics();
            rect.setLocation(w/2-50, h/2-25);
            big.setStroke(new BasicStroke(8.0f));
            firstTime = false;
        }

        // Clears the rectangle that was previously drawn.
        big.setColor(Color.white);
        big.clearRect(0, 0, area.width, area.height);

        // Draws and fills the newly positioned rectangle to the buffer.
        big.setPaint(strokePolka);
        big.draw(rect);
        big.setPaint(fillPolka);
        big.fill(rect);

        // Draws the buffered image to the screen.
        g2.drawImage(bi, 0, 0, this);

    }

5.3.3 Manipulating BufferedImage Data Directly

In addition to drawing directly in a BufferedImage, you can directly access and manipulate the image’s pixel data in a couple of ways. These are useful if you’re implementing the BufferedImageOp filtering interface, as described in “Image Processing and Enhancement” on page 84.

You can use the BufferedImage.setRGB methods to directly set the value of a pixel or a pixel array to a specific RGB value. Note that no dithering is performed when you modify pixels directly. You can also manipulate pixel data by manipulating a WritableRaster object associated with a BufferedImage (see“Managing and Manipulating Rasters” on page 80).

5.3.4 Filtering a BufferedImage

You can apply a filtering operation to a BufferedImage using an object that implements BufferedImageOp interface. Filtering and the classes that provide this filtering interface are discussed in “Image Processing and Enhancement” on page 84.

5.3.5 Rendering a BufferedImage

To render a buffered image into a specific context, call one of the drawImage method of the context’s Graphics object. For example, when rendering within a Component.paint method, you call drawImage on the graphics object passed to the method.

    public void paint(Graphics g) {

        if (getSize().width <= 0 || getSize().height <= 0)
            return;

        Graphics2D g2 = (Graphics2D) g;

        if (offImg != null && isShowing())  {
            g2.drawImage(offImg, 0, 0, this);
        }
    }

5.4 Managing and Manipulating Rasters

A BufferedImage object uses a Raster to manage its rectangular array of pixel data. The Raster class defines fields for the image’s coordinate system—width, height, and origin. A Raster object itself uses two objects to manage the pixel data, a DataBuffer and a SampleModel. The DataBuffer is the object that stores pixel data for the raster (as described on page 82), and the SampleModel provides the interpretation of pixel data from the DataBuffer (as described on page 82).

5.4.1 Creating a Raster

In most cases, you don’t need to create a Raster directly, since one is supplied with any BufferedImage that you create in memory. However, one of the BufferedImage constructor methods allows you to create a Raster by passing in a WritableRaster.

The Raster class provides a number of static factory methods for creating Rasters with the DataBuffers and SampleModels you specify. You can use these factories when implementing RasterOp filtering classes.

5.4.2 Parent and Child Rasters

The Raster class incorporates the concept of parent and child rasters. This can improve storage efficiency by allowing you to construct any number of buffered images from the same parent. The parent and its children all refer to the same data buffer, and each child has a specific offset and bounds to identify its image location in the buffer. A child identifies its ownership through its getParent method.

To create a subraster, you use the Raster.createSubRaster method.When you create a subraster, you identify the area of its parent that it covers and its offset from the parent’s origin.

5.4.3 Operations on a Raster

The Raster class defines a number of ways to access pixels and pixel data. These are useful when you’re implementing the RasterOp interface, which provides raster-level filtering and manipulation of image data, or when implementing any method that needs to perform low-level pixel manipulation.

The Raster.getPixel methods let you get an individual pixel, which is returned as individual samples in an array. The Raster.getDataElements methods return a specified run of uninterpreted image data from the DataBuffer. The Raster.getSample method returns samples of an individual pixel. The getSamples method returns a band for a particular region of an image.

In addition to these methods, you can also access the data buffer and the sample model through instance variables of the Raster class. These objects provide additional ways to access and interpret the Raster’s pixel data.

5.4.4 The WritableRaster Subclass

The WritableRaster subclass provides methods for setting pixel data and samples. The Raster associated with a BufferedImage is actually a WritableRaster, thus providing full access to manipulate its pixel data.

5.5 Image Data and DataBuffers

The DataBuffer belonging to a Raster represents an array of image data. When you create a Raster directly or through the BufferedImage constructors, you specify a width and height in pixels, along with a SampleModel for the image data. This information is used to create a DataBuffer of the appropriate data type and size.

There are three subclasses of DataBuffer, each representing a different type of data element:

  • DataBufferByte (represents 8-bit values)
  • DataBufferInt (represents 32-bit values)
  • DataBufferShort (represents 16-bit values)
  • DataBufferUShort (represents unsigned short values)

As defined earlier, elements are the discrete members of the array of the data buffer, and components or samples are the discrete values that together make up a pixel. There can be various mappings between a particular type of element in a DataBuffer and a particular type of pixel represented by a SampleModel. It is the responsibility of the various SampleModel subclasses to implement that mapping and provide a way to get specific pixels from a specific DataBuffer.

DataBuffer constructors provide ways to create buffers of a specific size and a specific number of banks.

While you can access image data in a DataBuffer directly, it’s generally easier and more convenient to do so through the methods of the Raster and WritableRaster classes.

5.6 Extracting Pixel Data from a SampleModel

The abstract SampleModel class defines methods for extracting samples of an image without knowing how the underlying data is stored. The class provides fields for tracking the height and width of the image data in the associated DataBuffer, and for describing the number of bands and the data type of that buffer. SampleModel methods provide image data as a collection of pixels, with each pixel consisting of a number of samples or components.

The java.awt.image package provides five types of sample models:

  • ComponentSampleModel—used to extract pixels from images that store sample data in separate data array elements in one bank of a DataBuffer.
  • BandedSampleModel—used to extract pixels from images that store each sample in a separate data element with bands stored in a sequence of data elements
  • PixelInterleavedSampleModel—used to extract pixels from images that store each sample in a separate data element with pixels stored in a sequence of data elements.
  • MultiPixelPackedSampleModel—used to extract pixels from single banded images that store multiple one-sample pixels in one data element.
  • SinglePixelPackedSampleModel—used to extract samples from images that store sample data for a single pixel in one data array element in the first bank of a DataBuffer.

Pixel data presented by the SampleModel may or may not correlate directly to a color data representation of a particular color model, depending on the data source. For example, in photographic image data, the samples may represent RGB data. In image data from a medical imaging device, samples can represent different types of data such as temperature or bone density.

There are three categories of methods for accessing image data. The getPixel methods return a whole pixel as an array, with one entry for each sample. The getDataElement methods provide access to the raw, uninterpreted data stored in the DataBuffer. The getSample methods provide access to pixel components for a specific band.

5.7 ColorModels and Color Data

In addition to the Raster object for managing image data, the BufferedImage class includes a ColorModel for interpreting that data as color pixel values. The abstract ColorModel class defines methods for turning an image’s pixel data into a color value in its associated ColorSpace.

The java.awt.image package provides four types of color models:

  • PackedColorModel—An abstract ColorModel that represents pixel values that have color components embedded directly in the bits of an integer pixel. A DirectColorModel is a subclass of PackedColorModel.
  • DirectColorModel—a ColorModel that represents pixel values that have RGB color components embedded directly in the bits of the pixel itself. DirectColorModel model is similar to an X11 TrueColor visual.
  • ComponentColorModel—a ColorModel that can handle an arbitrary ColorSpace and an array of color components to match the ColorSpace.
  • IndexColorModel—a ColorModel that represents pixel values that are indices into a fixed color map in the sRGB color space.

ComponentColorModel and PackedColorModel are new in the Java™ 2 SDK software release.

Based on data in the DataBuffer, the SampleModel provides the ColorModel with a pixel, which the ColorModel then interprets as a color.

5.7.1 Lookup Table

A lookup table contains data for one or more channels or image components; for example, separate arrays for R, G, and B. The java.awt.image package defines two types of lookup tables that extend the abstract LookupTable class, one that contains byte data and one that contains short data (ByteLookupTable and ShortLookupData).

5.8 Image Processing and Enhancement

The image package provides a pair of interfaces that define operations on BufferedImage and Raster objects: BufferedImageOp and RasterOp.

The classes that implement these interfaces include AffineTransformOp, BandCombineOp, ColorConvertOp, ConvolveOp, LookupOp, RescaleOp. These classes can be used to geometrically transform, blur, sharpen, enhance contrast, threshold, and color correct images.

Figure 5-4 illustrates edge detection and enhancement, an operation that emphasizes sharp changes in intensity within an image. Edge detection is commonly used in medical imaging and mapping applications. Edge detection is used to increase the contrast between adjacent structures in an image, allowing the viewer to discriminate greater detail.

The previous context describes this graphic.

Figure 5-4 Edge detection and enhancement

The following code illustrates edge detection:

float[] elements = { 0.0f, -1.0f, 0.0f,
                    -1.0f, 4.f, -1.0f,
                    0.0f, -1.0f, 0.0f};
...

BufferedImage bimg = new BufferedImage(bw,bh,BufferedImage.TYPE_INT_RGB);
Kernel kernel = new Kernel(3, 3, elements);
ConvolveOp cop = new ConvolveOp(kernel, ConvolveOp.EDGE_NO_OP, 		                                   null);
cop.filter(bi,bimg);

Figure 5-5 demonstrates lookup table manipulation. A lookup operation can be used to alter individual components of a pixel.

The previous context describes this graphic.

Figure 5-5 Lookup-table Manipulation

The following code demonstrates Lookup-table manipulation:

    byte reverse[] = new byte[256];
   for (int j=0; j<200; j++){
               reverse[j]=(byte)(256-j);
    }
       ByteLookupTable blut=new ByteLookupTable(0, reverse);
       LookupOp lop = new LookupOp(blut, null);
   lop.filter(bi,bimg);

Figure 5-6 illustrates rescaling. Rescaling can increase or decrease the intensity of all points. Rescaling can be used to increase the dynamic range of an otherwise neutral image, bringing out detail in a region that appears neutral or flat.

The previous context describes this graphic.

Figure 5-6 Rescaling

The following code snippet illustrates rescaling:

    RescaleOp rop = new RescaleOp(1.5f, 1.0f, null);
    rop.filter(bi,bimg);

5.8.1 Using an Image Processing Operation

Convolution is the process that underlies most spatial filtering algorithms. Convolution is the process of weighting or averaging the value of each pixel in an image with the values of neighboring pixels.This allows each output pixel to be affected by the immediate neighborhood in a way that can be mathematically specified with a kernel. Figure 5-7 illustrates Convolution.

The previous context describes this graphic.

Figure 5-7 Blurring with Convolution

The following code fragment illustrates how to use one of the image processing classes, ConvolveOp. In this example, each pixel in the source image is averaged equally with the eight pixels that surround it.

float weight = 1.0f/9.0f;float[] elements = new float[9]; // create 2D array// fill the array with nine equal elements
for (i = 0; i < 9; i++) {   elements[i] = weight;}// use the array of elements as argument to create a Kernelprivate Kernel myKernel = new Kernel(3, 3, elements);public ConvolveOp simpleBlur = new ConvolveOp(myKernel);

// sourceImage and destImage are instances of BufferedImagesimpleBlur.filter(sourceImage, destImage) // blur the image

The variable simpleBlur contains a new instance of ConvolveOp that implements a blur operation on a BufferedImage or a Raster. Suppose that sourceImage and destImage are two instances of BufferedImage. When you call filter, the core method of the ConvolveOp class, it sets the value of each pixel in the destination image by averaging the corresponding pixel in the source image with the eight pixels that surround it.

The convolution kernel in this example could be represented by the following matrix, with elements specified to four significant figures:

A 3 by 3 matrix with all values being 0.1111.

When an image is convolved, the value of each pixel in the destination image is calculated by using the kernel as a set of weights to average the pixel’s value with the values of surrounding pixels. This operation is performed on each channel of the image.

The following formula shows how the weights in the kernel are associated with the pixels in the source image when the convolution is performed. Each value in the kernel is tied to a spatial position in the image.

A 3 by 3 matrix. The first row values are i minus 1, j minus 1, i, j minus 1, and i plus 1, j minus1. The second row values are i minus 1, j, i, j, and i plus1, j. The third row values are i minus 1, j plus 1, i, j plus 1, and i plus 1, j plus 1.

The value of a destination pixel is the sum of the products of the weights in the kernel multiplied by the value of the corresponding source pixel. For many simple operations, the kernel is a matrix that is square and symmetric, and the sum of its weights adds up to one.2

The convolution kernel in this example is relatively simple. It weights each pixel from the source image equally. By choosing a kernel that weights the source image at a higher or lower level, a program can increase or decrease the intensity of the destination image. The Kernel object, which is set in the ConvolveOp constructor, determines the type of filtering that is performed. By setting other values, you can perform other types of convolutions, including blurring (such as Gaussian blur, radial blur, and motion blur), sharpening, and smoothing operations. Figure 5-8 illustrates sharpening using Convolution.

The previous context describes this graphic.

Figure 5-8 Sharpening with Convolution

The following code snippet illustrates sharpening with Convolution:

float[] elements = { 0.0f, -1.0f, 0.0f,
                    -1.0f,  5.f, -1.0f,
                     0.0f, -1.0f,  0.0f};
...

Kernel kernel = new Kernel(3,3,elements);
ConvolveOp cop = new ConvolveOp(kernel, ConvolveOp.EDGE_NO_OP, 														null);
    cop.filter(bi,bimg);

1It is up to the programmer to “erase” the previous version of the image before making a new copy at a new location. This can be done by redrawing the background or copying the background from another offscreen buffer.
2If the sum of the weights in the matrix is one, the intensity of the destination image is unchanged from the source.

Contents | Previous | Next Programmer's Guide to the JavaTM 2D API
JavaTM 2 SDK, Standard Edition, 1.4 version

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


Contents | Previous | Next Programmer's Guide to the JavaTM 2D API

Chapter 1

Java 2DTM API Overview

The Java 2D™ API enhances the graphics, text, and imaging capabilities of the Abstract Windowing Toolkit (AWT), enabling the development of richer user interfaces and new types of Java™ applications.

Along with these richer graphics, font, and image APIs, the Java 2D API supports enhanced color definition and composition, hit detection on arbitrary geometric shapes and text, and a uniform rendering model for printers and display devices.

The Java 2D API also enables the creation of advanced graphics libraries, such as CAD-CAM libraries and graphics or imaging special effects libraries, as well as the creation of image and graphic file read/write filters.

When used in conjunction with the Java Media Framework and other Java Media APIs, the Java 2D APIs can be used to create and display animations and other multimedia presentations. The Java Animation and Java Media Framework APIs rely on the Java 2D API for rendering support.

1.1 Enhanced Graphics, Text, and Imaging

Early versions of the AWT provided a simple rendering package suitable for rendering common HTML pages, but not full-featured enough for complex graphics, text, or imaging. As a simplified rendering package, the early AWT embodied specific cases of more general rendering concepts. The Java 2D™ API provides a more flexible, full-featured rendering package by expanding the AWT to support more general graphics and rendering operations.

For example, through the Graphics class you can draw rectangles, ovals, and polygons. Graphics2D enhances the concept of geometric rendering by providing a mechanism for rendering virtually any geometric shape. Similarly, with the Java 2D API you can draw styled lines of any width and fill geometric shapes with virtually any texture.

Geometric shapes are provided through implementations of the Shape interface, for example Rectangle2D and Ellipse2D. Curves and arcs are also specific implementations of Shape.

Fill and pen styles are provided through implementations of the Paint and Stroke interfaces, for example BasicStroke, GradientPaint, TexturePaint, and Color.

AffineTransform defines linear transformations of 2D coordinates, including scale, translate, rotate, and shear.

Clip regions are defined by the same implementations of the Shape interface that are used to define general clipping regions, for example Rectangle2D and GeneralPath.

Color composition is provided by implementations of the Composite interface, for example AlphaComposite.

A Font is defined by collections of Glyphs, which are in turn defined by individual Shapes.

1.2 Rendering Model

The basic graphics rendering model has not changed with the addition of the Java 2D™ APIs. To render a graphic, you set up the graphics context and invoke a rendering method on the Graphics object.

The Java 2D API class Graphics2D extends Graphics to support more graphics attributes and provide new rendering methods. Setting up a Graphics2D context is described in “Rendering with Graphics2D” on page 15.

The Java 2D API automatically compensates for differences in rendering devices and provides a uniform rendering model across different types of devices. At the application level, the rendering process is the same whether the target rendering device is a display or a printer.

With the JavaTM 2 SDK, version 1.3 relsease and later, the Java 2D API provides support for multi-screen environments. See Section 1.2.1, “Coordinate Systems” and “Rendering in a Multi-Screen Environment” on page 39 for more information.

1.2.1 Coordinate Systems

The Java 2D API maintains two coordinate systems:

  • User space is a device-independent, logical coordinate system. Applications use this coordinate system exclusively; all geometries passed into Java 2D rendering routines are specified in user space.
  • Device space is a device-dependent coordinate system that varies according to the target rendering device.
    In a multi-screen environment with a virtual desktop where a window can span more than one physical screen device, the device coordinate system that’s used is the coordinate system of the virtual desktop that encompasses all of the screens. For more information on how the Java 2DTM API supports multi-screen environments, see “Rendering in a Multi-Screen Environment” on page 39.

The Java 2D system automatically performs the necessary conversions between user space and the device space of the target rendering device. Although the coordinate system for a monitor is very different from the coordinate system for a printer, these differences are invisible to applications.

1.2.1.1 User Space

As shown in Figure 1-1, the user space origin is located in the upper-left corner of the space, with x values increasing to the right and y values increasing downward.

The previous context describes the graphic

Figure 1-1 User Space Coordinate System

User space represents a uniform abstraction of all possible device coordinate systems. The device space for a particular device might have the same origin and direction as user space, or it might be different. Regardless, user space coordinates are automatically transformed into the appropriate device space when a graphic object is rendered. Often, the underlying platform device drivers are used to perform this conversion.

1.2.1.2 Device Space

The Java 2D API defines three levels of configuration information that are maintained to support the conversion from user space to device space. This information is encapsulated by three classes:

  • GraphicsEnvironment
  • GraphicsDevice
  • GraphicsConfiguration

Between them, the GraphicsEnvironment, GraphicsDevice, and GraphicsConfiguration represent all of the information necessary for locating a rendering device or font on the Java platform and for converting coordinates from user space to device space. An application can access this information, but does not need to perform any transformations between user space and device space.

The GraphicsEnvironment describes the collection of rendering devices visible to a Java application on a particular platform. Rendering devices include screens, printers, and image buffers. The GraphicsEnvironment also includes a list of all of the available fonts on the platform.

A GraphicsDevice describes an application-visible rendering device, such as a screen or printer. Each possible configuration of the device is represented by a GraphicsConfiguration. For example, an SVGA display device can operate in several modes: 640x480x16 colors, 640x480x256 colors, and 800x600x256 colors. The SVGA screen is represented by a GraphicsDevice object and each of the modes is represented by a GraphicsConfiguration object.

A GraphicsEnvironment can contain one or more GraphicsDevices; in turn, each GraphicsDevice can have one or more GraphicsConfigurations.

1.2.2 Transforms

The Java 2D API has a unified coordinate transformation model. All coordinate transformations, including transformations from user to device space, are represented by AffineTransform objects. AffineTransform defines the rules for manipulating coordinates using matrices.

You can add an AffineTransform to the graphics context to rotate, scale, translate, or shear a geometric shape, text, or image when it is rendered. The added transform is applied to any graphic object rendered in that context. The transform is performed when user space coordinates are converted to device space coordinates.

1.2.3 Fonts

A string is commonly thought of in terms of the characters that comprise the string. When a string is drawn, its appearance is determined by the font that is selected. However, the shapes that the font uses to display the string don’t always correspond to individual characters. For example, in professional publishing, certain combinations of two or more characters are often replaced by a single shape called a ligature.

The shapes that a font uses to represent the characters in the string are called glyphs. A font might represent a character such as a lowercase a acute using multiple glyphs, or represent certain character combinations such as the fi in final with a single glyph. In the Java 2D API, a glyph is simply a Shape that can be manipulated and rendered in the same way as any other Shape.

A font can be thought of as a collection of glyphs. A single font might have many versions, such as heavy, medium, oblique, gothic, and regular. These different versions are called faces. All of the faces in a font have a similar typographic design and can be recognized as members of the same family. In other words, a collection of glyphs with a particular style forms a font face, a collection of font faces forms a font family, and a collection of font families forms the set of fonts available within a particular GraphicsEnvironment.

In the Java 2D API, fonts are specified by a name that describes a particular font face—for example, Helvetica Bold. This is different from the JDK 1.1 software, in which fonts are described by logical names that map onto different font faces depending on which font faces are available on a particular platform. For backward compatibility, the Java 2D API supports the specification of fonts by logical name as well as by font face name.

Using the Java 2D API, you can compose and render strings that contain multiple fonts of different families, faces, sizes, and even languages. The appearance of the text is kept logically separate from the layout of the text. Font objects are used to describe the appearance, and the layout information is stored in TextLayout and TextAttributeSet objects. Keeping the font and layout information separate makes it easier to use the same fonts in different layout configurations.

1.2.4 Images

Images are collections of pixels organized spatially. A pixel defines the appearance of an image at a single display location. A two-dimensional array of pixels is called a raster.

The pixel’s appearance can be defined directly or as an index into a color table for the image.

In images that contain many colors (more than 256), the pixels usually directly represent the color, alpha, and other display characteristics for each screen location. Such images tend to be much larger than indexed-color images, but they look more realistic.

In an indexed-color image, the colors in the image are limited to the colors specified in the color table, often resulting in fewer colors that can be used in the image. However, an index typically requires less storage space than a color value, so images stored as a set of indexed colors are usually smaller. This pixel format is popular for images that contain only 16 or 256 colors.

Images in the Java 2D API have two primary components:

  • The raw image data (the pixels)
  • The information necessary for interpreting the pixels

The rules for interpreting the pixel are encapsulated by a ColorModel object—for example, whether the values should be interpreted as direct or indexed colors. For a pixel to be displayed, it must be paired with a color model.

A band is one component of the color space for an image. For example, the Red, Green, and Blue components are the bands in an RGB image. A pixel in a direct color model image can be thought of as a collection of band values for a single screen location.

The java.awt.image package contains several ColorModel implementations, including those for packed and component pixel representations.

A ColorSpace object encapsulates the rules that govern how a set of numeric measurements corresponds to a particular color. The ColorSpace implementations in the java.awt.color represent the most popular color spaces, including RGB and gray scale. Note that a color space is not a collection of colors—it defines the rules for how to interpret individual color values.

Separating the color space from the color model provides greater flexibility in how colors are represented and converted from one color representation to another.

1.2.5 Fills and Strokes

With the Java 2D API, you can render Shapes using different pen styles and fill patterns. Because text is ultimately represented by a set of glyphs, text strings can also be stroked and filled.

Pen styles are defined by objects that implement the Stroke interface. Strokes enable you to specify different widths and dashing patterns for lines and curves.

Fill patterns are defined by objects that implement the Paint interface. The Color class, which was available in earlier versions of the AWT, is a simple type of Paint object used to define solid-color fills. The Java 2D API provides two additional Paint implementations, TexturePaint and GradientPaint. TexturePaint defines a fill pattern using a simple image fragment that is repeated uniformly. GradientPaint defines a fill pattern as a gradient between two colors.

In Java 2D, rendering a shape’s outline and filling the shape with a pattern are two separate operations:

  • Using one of the draw methods renders the shape’s contour or outline using the pen style specified by the Stroke attribute and the fill pattern specified by the Paint attribute.
  • Using the fill method fills the interior of the shape with the pattern specified by the Paint attribute.

When a text string is rendered, the current Paint attribute is applied to the glyphs that form the string. Note, however, that drawString actually fills the glyphs that are rendered. To stroke the outlines of the glyphs in a text string, you need to get the outlines and render them as shapes using the draw method.

1.2.6 Composites

When you render an object that overlaps an existing object, you need to determine how to combine the colors of the new object with the colors that already occupy the area where you are going to draw. The Java 2D API encapsulates rules for how to combine colors in a Composite object.

Primitive rendering systems provide only basic Boolean operators for combining colors. For example, a Boolean compositing rule might allow the source and destination color values to be ANDed, ORed, or XORed. There are several problems with this approach

  • It’s not “human friendly”—it’s difficult to think in terms of what the resulting color will be if red and blue are ANDed, not added.
  • Boolean composition does not support the accurate composition of colors in different color spaces.
  • Straight Boolean composition doesn’t take into account the color models of the colors. For example, in an indexed color model, the result of a Boolean operation on two pixel values in an image is the composite of two indices, not two colors.

The Java 2D API avoids these pitfalls by implementing alpha-blending1 rules that take color model information into account when compositing colors. An AlphaComposite object includes the color model of both the source and destination colors.

1.3 Backward Compatibility and Platform Independence

The Java 2D™ API maintains backward compatibility with JDK 1.1 software. It is also architected so that applications can maintain platform-independence.

1.3.1 Backward Compatibility

To ensure backward compatibility, the functionality of existing JDK graphics and imaging classes and interfaces was maintained. Existing features were not removed and no package designations were changed for existing classes. The Java 2D API enhances the functionality of the AWT by implementing new methods in existing classes, extending existing classes, and adding new classes and interfaces that don’t affect the legacy APIs.

For example, much of the Java 2D API functionality is delivered through an expanded graphics context, Graphics2D. To provide this extended graphics context while maintaining backward compatibility, Graphics2D extends the Graphics class from the JDK 1.1 release.

The usage model of the graphics context remains unchanged. The AWT passes a graphics context to an AWT Component through the following methods:

  • paint
  • paintAll
  • update
  • print
  • printAll
  • getGraphics

A JDK 1.1 applet interprets the graphics context that’s passed in as an instance of Graphics. To gain access to the new features implemented in Graphics2D, a Java 2D API–compatible applet casts the graphics context to a Graphics2D object:

public void Paint (Graphics g) {

    Graphics2D g2 = (Graphics2D) g;
    ...
    ...
    g2.setTransform (t);
}

In some cases, rather than extending a legacy class, the Java 2D API generalizes it. Two techniques were used to generalize legacy classes:

  • One or more parent classes were inserted in the hierarchy, and the legacy class was updated to extend the new parent classes. This technique is used to add general implemented methods and instance data to the legacy class.
  • One or more interface implementations were added to the legacy class. This technique is used to add general abstract methods to the legacy class.

For example, the Java 2D API generalizes the AWT Rectangle class using both of these techniques. The hierarchy for rectangle now looks like:

java.lang.object
|
+-------java.awt.geom.RectangularShape
             |
             +---------java.awt.geom.Rectangle2D
                               |
                               +-------java.awt.Rectangle

In the JDK 1.1 software, Rectangle simply extended Object. It now extends the new Rectangle2D class and implements both Shape and Serializable. Two parent classes were added to the Rectangle hierarchy: RectangularShape and Rectangle2D. Applets written for JDK 1.1 software are unaware of the new parent classes and interface implementations, but are unaffected because Rectangle still contains the methods and members that were present in earlier versions.

The Java 2D API adds several new classes and interfaces that are “orthogonal” to the legacy API. These additions do not extend or generalize existing classes—they are entirely new and distinct. These new classes and interfaces embody concepts that had no explicit representation in the legacy API.

For example, the Java 2D API implements several new Shape classes, including Arc2D, CubicCurve2D, and QuadCurve2D. Although early versions of the AWT could render arcs using the drawArc and fillArc methods, there was no general curve abstraction and no discrete classes that embodied arcs. These discrete classes could be added to the Java 2D API without disrupting legacy applets because drawArc and fillArc are still supported through the Graphics class.

1.3.2 Platform Independence

To enable the development of platform-independent applications, the Java 2D API makes no assumptions about the resolution, color space, or color model of the target rendering device. Nor does the Java 2D API assume any particular image file format.

Truly platform-independent fonts are possible only when the fonts are built-in (provided as part of the JDK software), or when they are mathematically or programmatically generated. The Java 2D API does not currently support built-in or mathematically generated fonts, but it does enable the programmatic definition of entire fonts through their glyph set. Each glyph can in turn be defined by a Shape that consists of line segments and curves. Many fonts of particular styles and sizes can be derived from a single glyph set.

1.4 The Java 2D™ API Packages

The Java 2D API classes are organized into the following packages:

  • java.awt
  • java.awt.geom
  • java.awt.font
  • java.awt.color
  • java.awt.image
  • java.awt.image.renderable
  • java.awt.print

Package java.awt contains those Java 2D API classes and interfaces that are general in nature or that enhance legacy classes. (Obviously, not all of the classes in java.awt are Java 2D classes.)

AlphaComposite | BasicStroke | Color
Composite | CompositeContext | Font
GradientPaint | Graphics2D | GraphicsConfiguration
GraphicsDevice | GraphicsEnvironment | Paint
PaintContext | Rectangle | Shape
Stroke | TexturePaint | Transparency

Package java.awt.geom contains classes and interfaces related to the definition of geometric primitives:

AffineTransform | Arc2D | Arc2D.Double
Arc2D.Float | Area | CubicCurve2D
CubicCurve2D.Double | CubicCurve2D.Float | Dimension2D
Ellipse2D | Ellipse2D.Double | Ellipse2D.Float
FlatteningPathIterator | GeneralPath | Line2D
Line2D.Double | Line2D.Float | PathIterator
Point2D | Point2D.Double | Point2D.Float
QuadCurve2D | QuadCurve2D.Double | QuadCurve2D.Float
Rectangle2D | Rectangle2D.Double | Rectangle2D.Float
RectangularShape | RoundRectangle2D | RoundRectangle2D.Double
RoundRectangle2D.Float |  |

Many of the geometric primitives have corresponding .Float and .Double implementations. This was done to enable both floating single- and double-precision implementations. Double-precision implementations provide greater rendering precision at the expense of performance on some platforms.

Package java.awt.font contains classes and interfaces used for text layout and the definition of fonts:

FontRenderContext | GlyphJustificationInfo | GlyphMetrics
GlyphVector | GraphicAttribute | ImageGraphicAttribute
LineBreakMeasurer | LineMetrics | MultipleMaster
OpenType | ShapeGrapicAttribute | TextAttribute
TextHitInfo | TextLayout | TransformAttribute

Packagejava.awt.color contains classes and interfaces for the definition of color spaces and color profiles:

ColorSpace | ICC_ColorSpace | ICC_Profile
ICC_ProfileGray | ICC_ProfileRGB |

The java.awt.image and java.awt.image.renderable packages contain classes and interfaces for the definition and rendering of images:

AffineTransformOp | BandCombineOp | BandedSampleModel
BufferedImage | BufferedImageFilter | BufferedImageOp
ByteLookupTable | ColorConvertOp | ColorModel
ComponentColorModel | ComponentSampleModel | ConvolveOp
ContextualRenderedImageFactory |  | DataBuffer
DataBufferByte | DataBufferInt | DataBufferShort
DataBufferUShort | DirectColorModel | IndexColorModel
Kernel | LookupOp | LookupTable
MultiPixelPackedSampleModel | PackedColorModel | ParameterBlock
PixelInterleavedSampleModel | Raster | RasterOp
RenderableImage | RenderableImageOp | RenderableImageProducer
RenderContext | RenderedImageFactory | RenderedImage
RescaleOp | SampleModel | ShortLookupTable
SinglePixelPackedSampleModel |  | TileObserver
WritableRaster | WritableRenderedImage |

Package java.awt.image was present in earlier versions of the AWT. The Java 2D API enhances the following legacy AWT image classes:

  • ColorModel
  • DirectColorModel
  • IndexColorModel

These color model classes remain in the java.awt.image package for backward compatibility. To maintain consistency, the new color model classes are also located in the java.awt.image package.

Package java.awt.print contains classes and interfaces that enable printing of all Java 2D–based text, graphics, and images

Book | Pageable | PageFormat
Paper | Printable | PrinterGraphics
PrinterJob |  |

1For detailed information about alpha blending, see Section 17.6 of Computer Graphics: Principles and Practice. 2nd ed. J.D. Foley, A. van Dam, S.K. Feiner, J.F. Hughes. Addison- Wesley, 1990.

Contents | Previous | Next Programmer's Guide to the JavaTM 2D API
JavaTM 2 SDK, Standard Edition, 1.4 version

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


Java 2DTM API Overview 1

Programmer's Guide to the JavaTM 2D API

JavaTM 2 SDK, Standard Edition
1.4 version

April 24, 2001
Contents | Previous | Next

Java 2DTM API Overview

Enhanced Graphics, Text, and Imaging

Rendering Model

Coordinate Systems

Transforms

Fonts

Images

Fills and Strokes

Composites

Backward Compatibility and Platform Independence

Backward Compatibility

Platform Independence

The Java 2D™ API Packages

Rendering with Graphics2D

Interfaces and Classes

Rendering Concepts

Rendering Process

Controlling Rendering Quality

Stroke Attributes

Fill Attributes

Clipping Paths

Transformations

Composite Attributes

Setting Up the Graphics2D Context

Setting Rendering Hints

Specifying Stroke Attributes

Specifying Fill Attributes

Setting the Clipping Path

Setting the Graphics2D Transform

Specifying a Composition Style

Rendering Graphics Primitives

Drawing a Shape

Filling a Shape

Rendering Text

Rendering Images

Defining Custom Composition Rules

Rendering in a Multi-Screen Environment

Geometries

Interfaces and Classes

Geometry Concepts

Constructive Area Geometry

Bounds and Hit Testing

Combining Areas to Create New Shapes

Creating a Custom Shape

Fonts and Text Layout

Interfaces and Classes

Font Concepts

Text Layout Concepts

Shaping Text

Ordering Text

Measuring and Positioning Text

Supporting Text Manipulation

Performing Text Layout in a Java™ Application

Managing Text Layout

Laying Out Text

Displaying Dual Carets

Moving the Caret

Hit Testing

Highlighting Selections

Querying Layout Metrics

Drawing Text Across Multiple Lines

Implementing a Custom Text Layout Mechanism

Creating Font Derivations

Imaging

Interfaces and Classes

Imaging Interfaces

Image Data Classes

Image Operation Classes

Sample Model Classes

Color Model Classes

Exception Classes

Immediate Mode Imaging Concepts

Terminology

Using BufferedImages

Creating a BufferedImage

Drawing in an Offscreen Buffer

Manipulating BufferedImage Data Directly

Filtering a BufferedImage

Rendering a BufferedImage

Managing and Manipulating Rasters

Creating a Raster

Parent and Child Rasters

Operations on a Raster

The WritableRaster Subclass

Image Data and DataBuffers

Extracting Pixel Data from a SampleModel

ColorModels and Color Data

Lookup Table

Image Processing and Enhancement

Using an Image Processing Operation

Color

Classes

Color Concepts

Describing Colors

Mapping Colors through sRGB and CIEXYZ

Printing

Interfaces and Classes

Printing Concepts

Supporting Printing

Page Painters

Printable Jobs and Pageable Jobs

Typical Life-Cycle of a PrinterJob

Dialogs

Printing with Printables

Using Graphics2D for Rendering

Printing a File

Printing with Pageables and Books

Using a Pageable Job

Using Multiple Page Painters

Contents | Previous | Next

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


Contents | Previous | Next Programmer's Guide to the JavaTM 2D API

Chapter 7

Printing

The Java Printing API enables applications to:

  • Print all AWT and Java 2D™ graphics, including composited graphics and images.
  • Control document-composition functions such as soft collating, reverse order printing, and booklet printing.
  • Invoke printer-specific functions such as duplex (two-sided) printing and stapling.
  • Print on all platforms, including Windows and Solaris. This includes printers directly attached to the computer as well as those that the platform software is able to access using network printing protocols.

Not all of these features are supported in the Java™ 2 SDK Printing API and implementation. The API will be extended to support all of these features in future releases. For example, additional printer controls will be added by augmenting the set of named properties of a print job that the application can control.

7.1 Interfaces and Classes

Interface | Description
Printable | The Printable interface is implemented by each page painter, the application class(es) called by the printing system to render a page. The system calls the page painter’s print method to request that a page be rendered.
Pageable | The Pageable interface is implemented by a document that is to be printed by the printing system. Through the Pageable methods, the system can determine the number of pages in the document, the format to use for each page, and the page painter to use to render each page.
PrinterGraphics | The Graphics2D objects that a page painter uses to render a page implement the PrinterGraphics interface. This enables an application to get the PrinterJob object that is controlling the printing.
Class | Description
Book | Implements: Pageable Represents a document in which pages can have different page formats and page painters. This class uses the Pageable interface to interact with a PrinterJob.
PageFormat | Describes the size and orientation of a page to be printed, as well as the Paper used to print it. For example, portrait and landscape paper orientations are represented by PageFormat.
Paper | Describes the physical characteristics of a piece of paper.
PrinterJob | The principal class that controls printing. The application calls PrinterJob methods to set up a job, display a print dialog to the user (optional), and to print the pages in the job.

7.2 Printing Concepts

The Java Printing API is based on a callback printing model in which the printing system, not the application, controls when pages are printed. The application provides information about the document to be printed and the printing system asks the application to render each page as it needs them.

The printing system might request that a particular page be rendered more than once or request that pages be rendered out of order. The application must be able to generate the proper page image, no matter which page the printing system requests. In this respect, the printing system is similar to the window toolkit, which can request components to repaint at any time, in any order.

The callback printing model is more flexible than traditional application-driven printing models and supports printing on a wider range of systems and printers. For example, if a printer stacks output pages in reverse order, the printing system can ask the application to generate pages in reverse order so that the final stack is in proper reading order.

This model also enables applications to print to a bitmap printer from computers that don’t have enough memory or disk space to buffer a full-page bitmap. In this situation, a page is printed as a series of small bitmaps or bands. For example, if only enough memory to buffer one tenth of a page is available, the page is divided into ten bands. The printing system asks the application to render each page ten times, once to fill each band. The application does not need to be aware of the number or size of the bands; it simply must be able to render each page when requested.

7.2.1 Supporting Printing

An application has to perform two tasks to support printing:

  • Job control—initiating and managing the print job.
  • Imaging—rendering each page when the printing system requests it.

7.2.1.1 Job Control

The user often initiates printing by clicking a button or selecting a menu item in an application. When a print operation is triggered by the user, the application creates a PrinterJob object and uses it to manage the printing process.

The application is responsible for setting up the print job, displaying print dialogs to the user, and starting the printing process.

7.2.1.2 Imaging

When a document is printed, the application has to render each page when the printing system requests it. To support this mechanism, the application provides a page painter that implements the Printable interface. When the printing system needs a page rendered, it calls the page painter’s print method.

When a page painter’s print method is called, it is passed a Graphics context to use to render the page image. It is also passed a PageFormat object that specifies the geometric layout of the page, and an integer page index that identifies the ordinal position of the page in the print job.

The printing system supports both Graphics and Graphics2D rendering, To print Java 2D™ Shapes, Text, and Images, you cast the Graphics object passed into the print method to a Graphics2D.

To print documents in which the pages use different page painters and have different formats, you use a pageable job. To create a pageable job, you can use the Book class or your own implementation of the Pageable interface. To implement simple printing operations, you do not need to use a pageable print job; Printable can be used as long as all of the pages share the same page format and painter.

7.2.2 Page Painters

The principal job of a page painter is to render a page using the graphics context that is provided by the printing system. A page painter implements the Printable.print method:

public int print(Graphics g, PageFormat pf, int pageIndex)

The graphics context passed to the print method is either an instance of Graphics or Graphics2D, depending on the packages loaded in your Java Virtual Machine. To use Graphics2D features, you can cast the Graphics object to a Graphics2D. The Graphics instance passed to print also implements the PrinterGraphics interface.

The PageFormat passed to a Printable describes the geometry of the page being printed. The coordinate system of the graphics context passed to print is fixed to the page: the origin of the coordinate system is at the upper left corner of the paper, X increases to the right, Y increases downward, and the units are 1/72 inch. If the page is in portrait orientation, the x-axis aligns with the paper’s “width,” while the y-axis aligns with the paper’s “height.” (Normally, but not always, a paper’s height exceeds its width.) If the page is in landscape orientation, the roles are reversed: the x-axis aligns with the paper’s “height” and the y-axis with its “width.”

Because many printers cannot print on the entire paper surface, the PageFormat specifies the imageable area of the page: this is the portion of the page in which it’s safe to render. The specification of the imageable area does not alter the coordinate system; it is provided so that the contents of the page can be rendered so that they don’t extend into the area where the printer can’t print.

The graphics context passed to print has a clip region that describes the portion of the imageable area that should be drawn. It is always safe to draw the entire page into the context; the printing system will handle the necessary clipping. However, to eliminate the overhead of drawing portions of the page that won’t be printed, you can use the clipping region to limit the areas that you render. To get the clipping region from the graphics context, call Graphics.getClip. You are strongly encouraged to use the clip region to reduce the rendering overhead.

It is sometimes desirable to launch the entire printing operation “in the background” so that a user can continue to interact with the application while pages are being rendered. To do this, call PrinterJob.print in a separate thread.

If possible, you should avoid graphics operations that require knowledge of the previous image contents, such as copyArea, setXOR, and compositing. These operations can slow rendering and the results might be inconsistent.

7.2.3 Printable Jobs and Pageable Jobs

A Printable job provides the simplest way to print. Only one page painter is used; the application provides a single class that implements the Printable interface. When it’s time to print, the printing system calls the page painter’s print method to render each page. The pages are requested in order, starting with page index 0. However, the page painter might be asked to render each page several times before it advances to the next page. When the last page has been printed, the page painter’s print method returns NO_SUCH_PAGE.

In a Printable job:

  • All pages use the same page painter and PageFormat. If a print dialog is presented, it will not display the number of pages in the document because that information is not available to the printing system.
  • The printing system always asks the page painter to print each page in indexed order, starting with the page at index 0. No pages are skipped. For example, if a user asks to print pages 2 and 3 of a document, the page painter will be called with indices 0, 1, and 2. The printing system might request that a page be rendered multiple times before moving to the next page.
  • The page painter informs the printing system when the end of the document has been reached.
  • All page painters are called in the same thread.
  • Some printing systems might not be able to achieve the ideal output. For example, the stack of pages emerging from the printer might be in the wrong order, or the pages might not be collated if multiple copies are requested.

A Pageable job is more flexible than a Printable job. Unlike the pages in a Printable job, pages in a Pageable job can differ in layout and implementation. To manage a Pageable job, you can use the Book class or implement your own Pageable class. Through the Pageable, the printing system can determine the number of pages to print, the page painter to use for each page, and the PageFormat to use for each page. Applications that need to print documents that have a planned structure and format should use Pageable jobs.

In a Pageable job:

  • Different pages can use different page painters and PageFormats.
  • The printing system can ask page painters to print pages in an arbitrary order and some pages might be skipped. For example, if a user asks to print pages 2 and 3 of a document, the page painter will be called with indices 1 and 2 and page index 0 will be skipped.
  • Pageable jobs do not need to know in advance how many pages are in the document. However, unlike Printable jobs, they must be able to render pages in any order. There might be gaps in the sequencing and the printing system might request that a page be rendered multiple times before moving to the next page. For example, a request to print pages 2 and 3 of a document might result in a sequence of calls that request pages with indices 2,2,1,1, and 1.

7.2.4 Typical Life-Cycle of a PrinterJob

An application steers the PrinterJob object through a sequence of steps to complete a printing job. The simplest sequence used by an application is:

  1. Get a new PrinterJob object by calling PrinterJob.getPrinterJob.
  2. Determine what PageFormat to use for printing. A default PageFormat can be obtained by calling defaultPage or you can invoke pageDialog to present a dialog box that allows the user to specify a format.
  3. Specify the characteristics of the job to be printed to the PrinterJob. For a Printable job, call setPrintable; for a Pageable job, call setPageable. Note that a Book object is ideal for passing to setPageable.
  4. Specify additional print job properties, such as the number of copies to print or the name of the job to print on the banner page.
  5. Call printDialog to present a dialog box to the user. This is optional. The contents and appearance of this dialog can vary across different platforms and printers. On most platforms, the user can use this dialog to change the printer selection. If the user cancels the print job, the printDialog method returns FALSE.
  6. Call Printerjob.print to print the job. This method in turn calls print on the appropriate page painters.

A job can be interrupted during printing if:

  • A PrinterException is thrown—the exception is caught by the print method and the job is halted. A page painter throws a PrinterException if it detects a fatal error.
  • PrinterJob.cancel is called—the printing loop is terminated and the job is canceled. The cancel method can be called from a separate thread that displays a dialog box and allows the user to cancel printing by clicking a button in the box.

Pages generated before a print job is stopped might or might not be printed.

The print job is usually not finished when the print method returns. Work is typically still being done by a printer driver, print server, or the printer itself. The state of the PrinterJob object might not reflect the state of the actual job being printed.

Because the state of a PrinterJob changes during its life cycle, it is illegal to invoke certain methods at certain times. For example, calling setPageable after you’ve called print makes no sense. When illegal calls are detected, the PrinterJob throws a java.lang.IllegalStateException.

7.2.5 Dialogs

The Java Printing API requires that applications invoke user-interface dialogs explicitly. These dialogs might be provided by the platform software (such as Windows) or by a Java™ 2 SDK software implementation. For interactive applications, it is customary to use such dialogs. For production printing applications, however, dialogs are not necessary. For example, you wouldn’t want to display a dialog when automatically generating and printing a nightly database report. A print job that requires no user interaction is sometimes called a silent print job.

7.2.5.1 Page setup dialog

You can allow the user to alter the page setup information contained in a PageFormat by displaying a page setup dialog. To display the page setup dialog, you call PrinterJob.pageDialog. The page setup dialog is initialized using the parameter passed to pageDialog. If the user clicks the OK button in the dialog, the PageFormat instance is cloned, altered to reflect the user’s selections, and then returned. If the user cancels the dialog, pageDialog returns the original unaltered PageFormat.

7.2.5.2 Print dialog

Typically, an application presents a print dialog to the user when a print menu item or button is activated. To display this print dialog, you call the PrinterJob’s printDialog method. The user’s choices in the dialog are constrained based on the number and format of the pages in the Printable or Pageable that have been furnished to the PrinterJob. If the user clicks OK in the print dialog, printDialog returns TRUE. If the user cancels the print dialog, FALSE is returned and the print job should be considered abandoned.

7.3 Printing with Printables

To provide basic printing support:

  1. Implement the Printable interface to provide a page painter that can render each page to be printed.
  2. Create a PrinterJob.
  3. Call setPrintable to tell the PrinterJob how to print your document.
  4. Call print on the PrinterJob object to start the job.

In the following example, a Printable job is used to print five pages, each of which displays a green page number. Job control is managed in the main method, which obtains and controls the PrinterJob. Rendering is performed in the page painter’s print method.

import java.awt.*; import java.awt.print.*;
public class SimplePrint implements Printable
{
  private static Font fnt = new Font("Helvetica",Font.PLAIN,24);

  public static void main(String[] args)
  {
    // Get a PrinterJob
    PrinterJob job = PrinterJob.getPrinterJob();
    // Specify the Printable is an instance of SimplePrint
    job.setPrintable(new SimplePrint());
    // Put up the dialog box
    if (job.printDialog())
    {
      // Print the job if the user didn't cancel printing
      try { job.print(); }
      catch (Exception e)
        { /* handle exception */ }
    }
    System.exit(0);
  }

  public int print(Graphics g, PageFormat pf, int pageIndex)
  throws PrinterException
  {
    // pageIndex 0 to 4 corresponds to page numbers 1 to 5.
    if (pageIndex >= 5) return Printable.NO_SUCH_PAGE;
    g.setFont(fnt);
    g.setColor(Color.green);
    g.drawString("Page " + (pageIndex+1), 100, 100);
    return Printable.PAGE_EXISTS;
  }
}

7.3.1 Using Graphics2D for Rendering

You can invoke Graphics2D functions in you page painter’s print method by first casting the Graphics context to a Graphics2D.

In the following example, the page numbers are rendered using a red-green gradient. To do this, a GradientPaint is set in the Graphics2D context.

import java.awt.*; import java.awt.print.*;
public class SimplePrint2D implements Printable
{
  private static Font fnt = new Font("Helvetica",Font.PLAIN,24);

  private Paint pnt = new GradientPaint(100f, 100f, Color.red, 	                                          136f, 100f, Color.green, true);

  public static void main(String[] args)
  {
    // Get a PrinterJob
    PrinterJob job = PrinterJob.getPrinterJob();
    // Specify the Printable is an instance of SimplePrint2D
    job.setPrintable(new SimplePrint2D());
    // Put up the dialog box
    if (job.printDialog())
    {
      // Print the job if the user didn't cancel printing
      try { job.print(); }
      catch (Exception e) { /* handle exception */ }
    }
  System.exit(0);
  }

  public int print(Graphics g, PageFormat pf, int pageIndex)
  throws PrinterException
  {
    // pageIndex 0 to 4 corresponds to page numbers 1 to 5.
    if (pageIndex >= 5) return Printable.NO_SUCH_PAGE;
    Graphics2D g2 = (Graphics2D) g;
    // Use the font defined above
    g2.setFont(fnt);
    // Use the gradient color defined above
    g2.setPaint(pnt);
    g2.drawString("Page " + (pageIndex+1), 100f, 100f);
    return Printable.PAGE_EXISTS;
  }
}

7.3.2 Printing a File

When a page painter’s print method is invoked several times for the same page, it must generate the same output each time.

There are many ways to ensure that repeated requests to render a page yield the same output. For example, to ensure that the same output is generated each time the printing system requests a particular page of a text file, page painter could either store and reuse file pointers for each page or store the actual page data.

In the following example, a “listing” of a text file is printed. The name of the file is passed as an argument to the main method. The PrintListingPainter class stores the file pointer in effect at the beginning of each new page it is asked to render. When the same page is rendered again, the file pointer is reset to the remembered position.

import java.awt.*;
import java.awt.print.*;
import java.io.*;

public class PrintListing
{
  public static void main(String[] args)
  {
    // Get a PrinterJob
    PrinterJob job = PrinterJob.getPrinterJob();
    // Ask user for page format (e.g., portrait/landscape)
    PageFormat pf = job.pageDialog(job.defaultPage());
    // Specify the Printable is an instance of
    // PrintListingPainter; also provide given PageFormat
    job.setPrintable(new PrintListingPainter(args[0]), pf);
    // Print 1 copy
    job.setCopies(1);
    // Put up the dialog box
    if (job.printDialog())
    {
      // Print the job if the user didn't cancel printing
      try { job.print(); }
      catch (Exception e) { /* handle exception */ }
    }
    System.exit(0);
  }
}

class PrintListingPainter implements Printable
{
  private RandomAccessFile raf;
  private String fileName;
  private Font fnt = new Font("Helvetica", Font.PLAIN, 10);
  private int rememberedPageIndex = -1;
  private long rememberedFilePointer = -1;
  private boolean rememberedEOF = false;

  public PrintListingPainter(String file)
  {
    fileName = file;
    try
    {
      // Open file
      raf = new RandomAccessFile(file, "r");
    }
    catch (Exception e) { rememberedEOF = true; }
  }

  public int print(Graphics g, PageFormat pf, int pageIndex)
  throws PrinterException
  {
  try
  {
    // For catching IOException
    if (pageIndex != rememberedPageIndex)
    {
      // First time we've visited this page
      rememberedPageIndex = pageIndex;
      // If encountered EOF on previous page, done
      if (rememberedEOF) return Printable.NO_SUCH_PAGE;
      // Save current position in input file
      rememberedFilePointer = raf.getFilePointer();
    }
    else raf.seek(rememberedFilePointer);
    g.setColor(Color.black);
    g.setFont(fnt);
    int x = (int) pf.getImageableX() + 10;
    int y = (int) pf.getImageableY() + 12;
    // Title line
    g.drawString("File: " + fileName + ", page: " + 			                 (pageIndex+1),  x, y);
    // Generate as many lines as will fit in imageable area
    y += 36;
    while (y + 12 < pf.getImageableY()+pf.getImageableHeight())
    {
      String line = raf.readLine();
      if (line == null)
      {
        rememberedEOF = true;
        break;
        }
        g.drawString(line, x, y);
        y += 12;
      }
      return Printable.PAGE_EXISTS;
    }
    catch (Exception e) { return Printable.NO_SUCH_PAGE;}
  }
}

7.4 Printing with Pageables and Books

Pageable jobs are suited for applications that build an explicit representation of a document, page by page. The Book class is a convenient way to use Pageables, but you can also build your own Pageable structures if Book does not suit your needs. This section shows you how to use Book.

Although slightly more involved, Pageable jobs are preferred over Printable jobs because the printing system has more flexibility. A major advantage of Pageables is that the number of pages in the document is usually known and can be displayed to the user in the print dialog box. This helps the user to confirm that the job is specified correctly or to select a range of pages for printing.

A Book represents a collection of pages. The pages in a book do not have to share the same size, orientation, or page painter. For example, a Book might contain two letter size pages in portrait orientation and a letter size page in landscape orientation.

When a Book is first constructed, it is empty. To add pages to a Book, you use the append method. This method takes a PageFormat object that defines the page’s size, printable area, and orientation and a page painter that implements the Printable interface.

Multiple pages in a Book can share the same page format and painter. The append method is overloaded to enable you to add a series of pages that have the same attributes by specifying a third parameter, the number of pages.

If you don’t know the total number of pages in a Book, you can pass UNKNOWN_NUMBER_OF_PAGES to the append method. The printing system will then call your page painters in order of increasing page index until one of them returns NO_SUCH_PAGE.

The setPage method can be used to change a page’s page format or painter. The page to be changed is identified by a page index that indicates the page’s location in the Book.

You call setPageable and pass in the Book to prepare the print job. The setPageable and setPrintable methods are mutually exclusive; that is, you should call one or the other but not both when preparing the PrinterJob.

7.4.1 Using a Pageable Job

In the following example, a Book is used to reproduce the first simple printing example. (Because this case is so simple, there is little benefit in using a Pageable job instead of a Printable job, but it illustrates the basics of using a Book.) Note that you still have to implement the Printable interface and perform page rendering in the page painter’s print method.

import java.awt.*;
import java.awt.print.*;

public class SimplePrintBook implements Printable
{
  private static Font fnt = new Font("Helvetica",Font.PLAIN,24);
  public static void main(String[] args)
  {
    // Get a PrinterJob
    PrinterJob job = PrinterJob.getPrinterJob();
    // Set up a book
    Book bk = new Book();
    bk.append(new SimplePrintBook(), job.defaultPage(), 5);
    // Pass the book to the PrinterJob
    job.setPageable(bk);
    // Put up the dialog box
    if (job.printDialog())
    {
      // Print the job if the user didn't cancel printing
      try { job.print(); }
      catch (Exception e) { /* handle exception */ }
    }
    System.exit(0);
  }

  public int print(Graphics g, PageFormat pf, int pageIndex)
  throws PrinterException
  {
    g.setFont(fnt);
    g.setColor(Color.green);
    g.drawString("Page " + (pageIndex+1), 100, 100);
    return Printable.PAGE_EXISTS;
  }
}

7.4.2 Using Multiple Page Painters

In the following example, two different page painters are used: one for a cover page and one for content pages. The cover page is printed in landscape mode and the contents pages are printed in portrait mode.

import java.awt.*;
import java.awt.print.*;

public class PrintBook
{
  public static void main(String[] args)
  {
    // Get a PrinterJob
    PrinterJob job = PrinterJob.getPrinterJob();
    // Create a landscape page format
    PageFormat pfl = job.defaultPage();
    pfl.setOrientation(PageFormat.LANDSCAPE);
    // Set up a book
    Book bk = new Book();
    bk.append(new PaintCover(), pfl);
    bk.append(new PaintContent(), job.defaultPage(), 2);
    // Pass the book to the PrinterJob
    job.setPageable(bk);
    // Put up the dialog box
    if (job.printDialog())
    {
      // Print the job if the user didn't cancel printing
      try { job.print(); }
      catch (Exception e) { /* handle exception */ }
    }
  System.exit(0);
  }
}

class PaintCover implements Printable
{
  Font fnt = new Font("Helvetica-Bold", Font.PLAIN, 72);

  public int print(Graphics g, PageFormat pf, int pageIndex)
  throws PrinterException
  {
    g.setFont(fnt);
    g.setColor(Color.black);
     int yc = (int) (pf.getImageableY() +               pf.getImageableHeight()/2);
    g.drawString("Widgets, Inc.", 72, yc+36);
    return Printable.PAGE_EXISTS;
  }
}
class PaintContent implements Printable
{
  public int print(Graphics g, PageFormat pf, int pageIndex)
  throws PrinterException
  {
    Graphics2D g2 = (Graphics2D) g;
    int useRed = 0;
   int xo = (int) pf.getImageableX();
    int yo = (int) pf.getImageableY();
    // Fill page with circles or squares, alternating red & green
    for (int x = 0; x+28 < pf.getImageableWidth(); x += 36)
    for (int y = 0; y+28 < pf.getImageableHeight(); y += 36)
    {
      if (useRed == 0) g.setColor(Color.red);
      else g.setColor(Color.green);
      useRed = 1 - useRed;
      if (pageIndex % 2 == 0) g.drawRect(xo+x+4, yo+y+4, 28, 28);
      else g.drawOval(xo+x+4, yo+y+4, 28, 28);
    }
    return   Printable.PAGE_EXISTS;
  }
}

Contents | Previous | Next Programmer's Guide to the JavaTM 2D API
JavaTM 2 SDK, Standard Edition, 1.4 version

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


Programmer's Guide to the Java 2D API

CONTENTS | PREV | NEXT

Programmer's Guide to the Java 2DTM API

Enhanced Graphics and Imaging for the JavaTM Programming Language

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


Contents | Previous | Next Programmer's Guide to the JavaTM 2D API

Chapter 2

Rendering with Graphics2D

Graphics2D extends java.awt.Graphics to provide more sophisticated control over the presentation of shapes, text, and images. The Java 2D™ rendering process is controlled through the Graphics2D object and its state attributes.

The Graphics2D state attributes, such as line styles and transformations, are applied to graphic objects when they are rendered. The collection of state attributes associated with a Graphics2D is referred to as the Graphics2D context. To render text, shapes, or images, you set up the Graphics2D context and then call one of the Graphics2D rendering methods, such as draw or fill.

2.1 Interfaces and Classes

The following tables list the interfaces and classes used in conjunction with the Graphics2D context, including the classes that represent state attributes. Most of these classes are part of the java.awt package.

Interface | Description
Composite | Defines methods to compose a draw primitive with the underlying graphics area. Implemented by AlphaComposite.
CompositeContext | Defines the encapsulated and optimized environment for a composite operation. Used by programmers implementing custom compositing rules.
Paint | Extends: Transparency Defines colors for a draw or fill operation. Implemented by Color, GradientPaint and TexturePaint.
PaintContext | Defines the encapsulated and optimized environment for a paint operation. Used by programmers implementing custom paint operations.
Stroke | Generates a Shape that encloses the outline of the Shape to be rendered. Implemented by BasicStroke.
Class | Description
AffineTransform (java.awt.geom) | Represents a 2D affine transform, which performs a linear mapping from 2D coordinates to other 2D coordinates.
AlphaComposite | Implements: Composite Implements basic alpha composite rules for shapes, text, and images.
BasicStroke | Implements: Stroke Defines the “pen style” to be applied to the outline of a Shape.
Color | Implements: Paint Defines a solid color fill for a Shape.
GradientPaint | Implements: Paint Defines a linear color gradient fill pattern for a Shape. This fill pattern changes from color C1 at point P1 to color C2 at point P2.
Graphics2D | Extends: Graphics Fundamental class for 2D rendering. Extends the original java.awt.Graphics class.
TexturePaint | Implements: Paint Defines a texture or pattern fill for a Shape. The texture or pattern is generated from a BufferedImage.

2.2 Rendering Concepts

To render a graphic object using the Java 2D™ API, you set up the Graphics2D context and pass the graphic object to one of the Graphics2D rendering methods.

You can modify the state attributes that form the Graphics2D context to:

  • Vary the stroke width.
  • Change how strokes are joined together.
  • Set a clipping path to limit the area that is rendered.
  • Translate, rotate, scale, or shear objects when they are rendered.
  • Define colors and patterns to fill shapes with.
  • Specify how multiple graphics objects should be composed.

Graphics2D defines several methods for adding and changing attributes in the graphics context. Most of these methods take an object that represents a particular attribute, such as a Paint or Stroke object.

The Graphics2D context holds references to these attribute objects: they are not cloned. If you alter an attribute object that is part of the Graphics2D context, you need to call the appropriate set method to notify the context. Modifying an attribute object during a rendering operation will cause unpredictable and possibly unstable behavior.

2.2.1 Rendering Process

When a graphic object is rendered, the geometry, image, and attribute information are combined to calculate which pixel values must be changed on the display.

The rendering process for a Shape can be broken down into four steps:

  1. If the Shape is to be stroked, the Stroke attribute in the Graphics2D context is used to generate a new Shape that encompasses the stroked path.
  2. The coordinates of the Shape’s path are transformed from user space into device space according to the transform attribute in the Graphics2D context.
  3. The Shape’s path is clipped using the clip attribute in the Graphics2D context.
  4. The remaining Shape, if any, is filled using the Paint and Composite attributes in the Graphics2D context.

Rendering text is similar to rendering a Shape, since the text is rendered as individual glyphs and each glyph is a Shape. The only difference is that the Java 2D API must determine what Font to apply to the text and get the appropriate glyphs from the Font before rendering.

Images are handled differently, transformations and clipping operations are performed on the image’s bounding box. The color information is taken from the image itself and its alpha channel is used in conjunction with the current Composite attribute when the image pixels are composited onto the rendering surface.

2.2.2 Controlling Rendering Quality

The Java 2D API lets you indicate whether you want objects to be rendered as quickly as possible, or whether you prefer that the rendering quality be as high as possible. Your preferences are specified as hints through the RenderingHints attribute in the Graphics2D context. Not all platforms support modification of the rendering mode so specifying rendering hints does not guarantee that they will be used.

The RenderingHints class supports the following types of hints:

  • Alpha interpolation—can be set to default, quality, or speed.
  • Antialiasing—can be set to default, on, or off.
  • Color Rendering–can be set to default, quality, or speed.
  • Dithering—can be set to default, disable, or enable.
  • Fractional Metrics—can be set to default, on, or off.
  • Interpolation—can be set to nearest-neighbor, bilinear, or bicubic.
  • Rendering—can be set to default, quality, or speed.
  • Text antialiasing—can be set to default, on, or off.

To set or change the RenderingHints attribute in the Graphics2D context, you call setRenderingHints. When a hint is set to default, the platform rendering default is used is used.

Antialiasing

When graphics primitives are rendered on raster-graphics display devices, their edges can appear jagged because of aliasing. Arcs and diagonal lines take on a jagged appearance because they are approximated by turning on the pixels that are closest to the path of the line or curve. This is particularly noticeable on low-resolution devices, where the jagged edges appear in stark contrast to the smooth edges of horizontal or vertical lines.

Antialiasing is a technique used to render objects with smoother-appearing edges. Instead of simply turning on the pixel that is closest to the line or curve, the intensity of surrounding pixels is set in proportion to the amount of area covered by the geometry being rendered. This softens the edges and spreads the on-off transition over multiple pixels. However, antialiasing requires additional computing resources and can reduce rendering speed

.

This graphic shows examples of aliased and antialiased graphics as described in the previous context.

2.2.3 Stroke Attributes

Stroking a Shape such as a GeneralPath object is equivalent to running a logical pen along the segments of the GeneralPath. The Graphics2D Stroke attribute defines the characteristics of the mark drawn by the pen.

A BasicStroke object is used to define the stroke attributes for a Graphics2D context. BasicStroke defines characteristics such as the line width, endcap style, segment join-style, and the dashing pattern. To set or change the Stroke attribute in the Graphics2D context, you call setStroke.

This graphics shows endcap styles supported by BasicStroke including chopped, round and squared.

Figure 2-1 endcap styles supported by BasicStroke

This graphic shows join styles supported by BasicStroke including bevel, round and miter.

Figure 2-2 Join styles supported by BasicStroke

For example, the first image in Figure 2-3 uses the miter join-style; the second image uses a round join-style, a round endcap style, and a dashing pattern.

The previous context describes this graphic

Figure 2-3 Stroke Styles

The Graphics2D rendering methods that use the Stroke attribute are draw, drawArc, drawLine, drawOval, drawPolygon, drawPolyline, drawRect, and drawRoundRect.When one of these methods is called, the outline of the specified Shape is rendered. The Stroke attribute defines the line characteristics and the Paint attribute defines the color or pattern of the mark drawn by the pen.

For example, when draw(myRectangle) is called:

  1. The Stroke is applied to the rectangle’s outline.
  2. The stroked outline is converted to a Shape object.
  3. The Paint is applied to the pixels that lie within the contour of the outline Shape.

This process is illustrated in Figure 2-4:

The previous context describes this graphic.

Figure 2-4 Stroking a Shape

2.2.4 Fill Attributes

The fill attribute in the Graphics2D context is represented by a Paint object. You add a Paint to the Graphics2D context by calling setPaint.

When a Shape or glyph is drawn (Graphics2D.draw, Graphics2D.drawString), the Paint is applied to all of the pixels that lie inside of the Shape that represents the object’s stroked outline. When a Shape is filled (Graphics2D.fill), the Paint is applied to all of the pixels that lie within the Shape’s contour.

Simple solid color fills can be set with the setColor method. Color is the simplest implementation of the Paint interface.

To fill Shapes with more complex paint styles such as gradients and textures, you use the Java 2D Paint classes GradientPaint and TexturePaint. These classes eliminate the time-consuming task of creating complex fills using simple solid-color paints. Figure 2-5 illustrates two fills that could easily be defined by GradientPaint and TexturePaint.

The previous context describes this graphic.

Figure 2-5 Complex Fill Styles

When fill is called to render a Shape, the system:

  1. Determines what pixels comprise the Shape.
  2. Gets the color of each pixel from the Paint object.
  3. Converts the color to an appropriate pixel value for the output device.
  4. Writes the pixel to that device.
Batch Processing

To streamline the processing of pixels, the Java 2D API processes them in batches. A batch can be either a contiguous set of pixels on a given scanline or a block of pixels. This batch processing is done in two steps:

  1. The Paint object’s createContext method is called to create a PaintContext. The PaintContext stores the contextual information about the current rendering operation and the information necessary to generate the colors. The createContext method is passed the bounding boxes of the graphics object being filled in user space and in device space, the ColorModel in which the colors should be generated, and the transform used to map user space into device space. The ColorModel is treated as a hint because not all Paint objects can support an arbitrary ColorModel. (For more information about ColorModels, see “Color” on page 89.”)
  2. The getColorModel method is called to get the ColorModel of the generated paint color from the PaintContext.

The getRaster method is then called repeatedly to get the Raster that contains the actual color data for each batch. This information is passed to the next stage in the rendering pipeline, which draws the generated color using the current Composite object.

2.2.5 Clipping Paths

A clipping path identifies the portion of a Shape or Image that needs to be rendered. When a clipping path is part of the Graphics2D context, only those parts of a Shape or Image that lie within the path are rendered.

To add a clipping path to the Graphics2D context, you call setClip. Any Shape can be used to define the clipping path.

To change the clipping path, you can either use setClip to specify a new path or call clip to change the clipping path to the intersection of the old clipping path and a new Shape.

2.2.6 Transformations

The Graphics2D context contains a transform that is used to transform objects from user space to device space during rendering. To perform additional transformations, such as rotation or scaling, you can add other transforms to the Graphics2D context. These additional transforms become part of the pipeline of transformations applied during rendering.

Graphics2D provides several different ways to modify the transform in the Graphics2D context. The simplest is to call one of the Graphics2D transformation methods: rotate, scale, shear, or translate. You specify the characteristics of the transform that you want to be applied during rendering, and Graphics2D automatically makes the appropriate changes.

You can also explicitly concatenate an AffineTransform with the current Graphics2D transform. An AffineTransform performs a linear transformation such as translation, scaling, rotation, or shearing on a set of graphics primitives. When a transform is concatenated with an existing transform, the last transform specified is the first to be applied. To concatenate a transform with the current transform, you pass an AffineTransform to Graphics2D.transform.

The Graphics2D class also contains a setTransform method, but this method should never be used to concatenate another coordinate transform onto of an existing transform. The setTransform method overwrites the Graphics2D object’s current transform, which is needed for other purposes, such as:

  • Applying a scaling transform to adjust for printer resolution.
  • Painting a JComponent at non-zero translation from its parent’s origin
  • Scaling up a component for easier viewing.
  • Any other situation in which the supplier of a Graphics2D object might want to transform the rendering for effect .

The setTransform method is intended for setting the Graphics2D object back to the original transform after rendering the transformed graphics, text or images:

AffineTransform aT = g2d.getTransform();
g2d.transform(...);g2d.draw(...);
g2d.setTransform(aT);

Graphics2D also provides a version of drawImage that takes an AffineTransform as a parameter. This enables you to apply a transformation to an image object when it is drawn without permanently modifying the transformation pipeline. The image is drawn as if you had concatenated the transform with the current transform in the Graphics2D context.

Affine Transforms

The Java 2D API provides one transform class, AffineTransform. AffineTransforms are used to transform text, shapes, and images when they are rendered. You can also apply transforms to Font objects to create new font derivations, as discussed in “Creating Font Derivations” on page 65.

An affine transformation performs a linear transformation on a set of graphics primitives. It always transforms straight lines into straight lines and parallel lines into parallel lines; however, the distance between points and the angles between nonparallel lines might be altered.

Affine transformations are based on two-dimensional matrices of the following form:

A 2 by 3 matrix with the top row containing a, c and t sub x. The second row contains b, d and t sub y. where x prime equals a x plus c y plus t sub x and y prime equals b x plus d y plus t sub y

Transforms can be combined, effectively creating a series or pipeline of transformations that can be applied to an object. This combination is referred to as concatenation. When a transform is concatenated with an existing transform, such as with AffineTransform.concatenate, the last transform specified is the first to be applied. A transform can also be pre-concatenated with an existing transform. In this case, the last transform specified is the last to be applied.

Pre-concatenation is used to perform transformations relative to device space instead of user space. For example, you could use AffineTransform.preConcatenate to perform a translation relative to absolute pixel space.

2.2.6.1 Constructing an AffineTransform

AffineTransform provides a set of convenience methods for constructing AffineTransform objects:

  • getTranslateInstance
  • getRotateInstance
  • getScaleInstance
  • getShearInstance

To use these methods, you specify the characteristics of the transform you want to create and AffineTransform generates the appropriate transform matrix. You can also construct an AffineTransform by directly specifying the elements of the transformation matrix.

2.2.7 Composite Attributes

When two graphic objects overlap, it is necessary to determine what colors to render the overlapping pixels. For example, if a red rectangle and a blue rectangle overlap, the pixels that they share could be rendered red, blue, or some combination of the two. The color of the pixels in the overlapping area will determine which rectangle appears to be on top and how transparent it looks. The process of determining what color to render pixels shared by overlapping objects is called compositing.

Two interfaces form the basis of the Java 2D compositing model: Composite and CompositeContext.

To specify the compositing style that should be used, you add an AlphaComposite object to the Graphics2D context by calling setComposite. AlphaComposite, an implementation of the Composite interface, supports a number of different compositing styles. Instances of this class embody a compositing rule that describes how to blend a new color with an existing one.

One of the most commonly used compositing rules in the AlphaComposite class is SRC_OVER, which indicates that the new color (the source color) should be blended over the existing color (the destination color).

AlphaComposite Composition Rule | Description | Example
CLEAR | Clear |
DEST_IN | Destination In |
DEST_OUT | Destination Out |
DEST_OVER | Destination Over |
SRC | Source |
SRC_IN | Source In |
SRC_OUT | Source Out |
SRC_OVER | Source Over |

2.2.7.1 Managing Transparency

A color’s alpha value is a measure of its transparency: it indicates, as a percentage, how much of a previously rendered color should show through when colors overlap. Opaque colors (alpha=1.0) don’t allow any of the underlying color to show through, while transparent colors (alpha=0.0) let all of it show through.

When text and Shapes are rendered, the alpha value is derived from the Paint attribute in the Graphics2D context. When Shapes and text are antialiased, the alpha value from the Paint in the Graphics2D context is combined with pixel coverage information from the rasterized path. Images maintain their own alpha information—see “Transparency and Images” on page 26 for more information.

When you construct an AlphaComposite object, you can specify an additional alpha value. When you add this AlphaComposite object to the Graphics2D context, this extra alpha value increases the transparency of any graphic objects that are rendered—the alpha value of each graphic object is multiplied by the AlphaComposite’s alpha value.

2.2.7.2 Transparency and Images

Images can carry transparency information for each pixel in the image. This information, called an alpha channel, is used in conjunction with the Composite object in the Graphics2D context to blend the image with existing drawings.

For example, Figure 2-6 contains three images with different transparency information. In each case, the image is displayed over a blue rectangle. This example assumes that the Graphics2D context contains an AlphaComposite object that uses SRC_OVER as the compositing operation.

The following context describes this graphic.

Figure 2-6 Transparency and Images

In the first image, all of the pixels are either fully opaque (the dog’s body) or fully transparent (the background). This effect is often used on Web pages. In the second image, all of the pixels in the dog’s body are rendered using a uniform, non-opaque alpha value, allowing the blue background to show through. In the third image, the pixels around the dogs face are fully opaque (alpha=1.0), but as the distance from its face increases, the alpha values for the pixels decrease.

2.3 Setting Up the Graphics2D Context

To configure the Graphics2D context for rendering, you use the Graphics2D set methods to specify attributes such as the RenderingHints, Stroke, Paint, clipping path, Composite, and Transform.

2.3.1 Setting Rendering Hints

A RenderingHints object encapsulates all of your preferences concerning how an object is rendered. To set the rendering hints in the Graphics2D context, you create a RenderingHints object and pass it into Graphics2D.setRenderingHints.

Setting a rendering hint does not guarantee that a particular rendering algorithm will be used: not all platforms support modification of the rendering mode.

In the following example, antialiasing is enabled and the rendering preference is set to quality:

qualityHints = new               RenderingHints(RenderingHints.KEY_ANTIALIASING,               RenderingHints.VALUE_ANTIALIAS_ON);
qualityHints.put(RenderingHints.KEY_RENDERING,               RenderingHints.VALUE_RENDER_QUALITY);
g2.setRenderingHints(qualityHints);

2.3.2 Specifying Stroke Attributes

A BasicStroke defines the characteristics applied to a Shape’s outline, including its width and dashing pattern, how line segments are joined together, and the decoration (if any) applied to the end of a line. To set the stroke attributes in the Graphics2D context, you create a BasicStroke object and pass it into setStroke.

2.3.2.1 Setting the Stroke Width

To set the stroke width, you create a BasicStroke object with the desired width and call setStroke.

In the following example, the stroke width is set to twelve points and the defaults are used for the join and endcap decorations:

wideStroke = new BasicStroke(12.0f);
g2.setStroke(wideStroke);

2.3.2.2 Specifying Join and Endcap Styles

To set the join and endcap styles, you create a BasicStroke object with the desired attributes.

In the following example, the stroke width is set to twelve points and the round join and endcap styles are used instead of the defaults:

roundStroke = new BasicStroke(4.0f, BasicStroke.CAP_ROUND,              BasicStroke.JOIN_ROUND);
g2.setStroke(roundStroke);

2.3.2.3 Setting the Dashing Pattern

Complex dashing patterns can easily be defined with a BasicStroke object. When you create a BasicStroke object, you can specify two parameters that control the dashing pattern:

  • dash—an array that represents the dashing pattern. Alternating elements in the array represent the dash size and the size of the space between dashes. Element 0 represents the first dash, element 1 represents the first space.
  • dash_phase—an offset that defines where the dashing pattern starts.

In the following example, two different dashing patterns are applied to a line. In the first, the size of the dashes and the space between them is constant. The second dashing pattern is more complex, using a six-element array to define the dashing pattern.

float dash1[] = {10.0f};
BasicStroke bs = new BasicStroke(5.0f, BasicStroke.CAP_BUTT,
                 BasicStroke.JOIN_MITER, 10.0f, dash1, 0.0f);
g2.setStroke(bs);
Line2D line = new Line2D.Float(20.0f, 10.0f, 100.0f, 10.0f);
g2.draw(line);

float[] dash2 = {6.0f, 4.0f, 2.0f, 4.0f, 2.0f, 4.0f};
bs = new BasicStroke(5.0f, BasicStroke.CAP_BUTT,
     BasicStroke.JOIN_MITER, 10.0f, dash2, 0.0f);
g2.setStroke(bs);
g2.draw(line);

Both dashing patterns use a dash phase of zero, causing the dashes to be drawn starting at the beginning of the dashing pattern. The two dashing patterns are shown in Figure Figure 2-7

.

The previous context describes this graphic.

Figure 2-7 Dashing Patterns

2.3.3 Specifying Fill Attributes

The Paint attribute in the Graphics2D context determines the fill color or pattern that is used when text and Shapes are rendered.

2.3.3.1 Filling a Shape with a Gradient

The GradientPaint class provides an easy way to fill a shape with a gradient of one color to another. When you create a GradientPaint, you specify a beginning position and color, and an ending position and color. The fill color changes proportionally from one color to the other along the line connecting the two positions, as shown in Figure 2-8.

The previous context describes this graphic.

Figure 2-8 Creating Gradient Fills

In the third star in Figure 2-8, both points lie within the shape. All of the points along the gradient line extending beyond P1 take the beginning color, and the points along the gradient line extending beyond P2 take the ending color.

To fill a shape with a gradient of one color to another:

  1. Create a GradientPaint object.
  2. Call Graphics2D.setPaint.
  3. Create the Shape.
  4. Call Graphics2D.fill(shape).

In the following example, a rectangle is filled with a blue-green gradient.

GradientPaint gp = new GradientPaint(50.0f, 50.0f, Color.blue
                   50.0f, 250.0f, Color.green);
g2.setPaint(gp);
g2.fillRect(50, 50, 200, 200);

2.3.3.2 Filling a Shape with a Texture

The TexturePaint class provides an easy way to fill a shape with a repeating pattern. When you create a TexturePaint, you specify a BufferedImage to use as the pattern. You also pass the constructor a rectangle to define the repetition frequency of the pattern, as shown in Figure 2-9.

The previous context describes this graphic.

Figure 2-9 Creating Texture Paints

To fill a shape with a texture:

  1. Create a TexturePaint object.
  2. Call Graphics2D.setPaint.
  3. Create the Shape.
  4. Call Graphics2D.fill(shape).

In the following example, a rectangle is filled with a simple texture created from a buffered image.

// Create a buffered image texture patch of size 5x5
BufferedImage bi = new BufferedImage(5, 5,
                       BufferedImage.TYPE_INT_RGB);
Graphics2D big = bi.createGraphics();
// Render into the BufferedImage graphics to create the texture
big.setColor(Color.green);
big.fillRect(0,0,5,5);
big.setColor(Color.lightGray);
big.fillOval(0,0,5,5);

// Create a texture paint from the buffered image
Rectangle r = new Rectangle(0,0,5,5);
TexturePaint tp = new TexturePaint(bi,r,TexturePaint.NEAREST_NEIGHBOR);

// Add the texture paint to the graphics context.
g2.setPaint(tp);

// Create and render a rectangle filled with the texture.
g2.fillRect(0,0,200,200);
}

2.3.4 Setting the Clipping Path

To define a clipping path:

  1. Create a Shape that represents the area you want to render.
  2. Call Graphics2D.setClip to use the shape as the clipping path for the Graphics2D context.

To shrink the clipping path:

  1. Create a Shape that intersects the current clipping path.
  2. Call clip to change the clipping path to the intersection of the current clipping path and the new Shape.

In the following example, a clipping path is created from an ellipse and then modified by calling clip.

public void paint(Graphics g) {
  Graphics2D g2 = (Graphics2D) g;

// The width and height of the canvas
  int w = getSize().width;
  int h = getSize().height;
  // Create an ellipse and use it as the clipping path
  Ellipse2D e = new Ellipse2D.Float(w/4.0f,h/4.0f,
                                    w/2.0f,h/2.0f);
  g2.setClip(e);

  // Fill the canvas. Only the area within the clip is rendered
  g2.setColor(Color.cyan);
  g2.fillRect(0,0,w,h);

  // Change the clipping path, setting it to the intersection of
  // the current clip and a new rectangle.
  Rectangle r = new Rectangle(w/4+10,h/4+10,w/2-20,h/2-20);
  g2.clip(r);

  // Fill the canvas. Only the area within the new clip
  // is rendered
  g2.setColor(Color.magenta);
  g2.fillRect(0,0,w,h);
}

2.3.5 Setting the Graphics2D Transform

To transform a Shape, text string, or Image you add a new AffineTransform to the transformation pipeline in the Graphics2D context before rendering. The transformation is applied when the graphic object is rendered.

For example, to draw a rectangle that is rotated 45 degrees:

  1. Get the current Graphics2D transform before performing any transformations. Always call getTransform on the Graphics2D before adding a transform to the graphics context because the graphics context might already have a transform that is needed for other reasons, such as positioning Swing and lightweight components within a window.
  2. Get a rotation transform by calling AffineTransform. getRotateInstance.
  3. Call Graphics2D.transform to add the new transform to the transformation pipeline. Never use the setTransform method to add a new coordinate transform because setTransform will overwrite the current transform in the graphics context.
  4. Create a Rectangle2D.Float object.
  5. Call Graphics2D.draw to render the rectangle.
  6. After you have rendered your transformed rectangle, reset the transform of the Graphics2D back to the original transform that you saved in Step 1 by calling setTransform with the original transform.

In the following example, an instance of AffineTransform is used to rotate a rectangle 45 degrees when it is rendered.

AffineTransform aT = g2.getTransform();Rectangle2D rect = new Rectangle2D.Float(1.0,1.0,2.0,3.0);
AffineTransform rotate45 =
  AffineTransform.getRotateInstance(Math.PI/4.0,0.0,0.0)
g2.transform(rotate45);
g2.draw(rect);g2.setTransform(aT);

In this example, an AffineTransform is used to rotate a text string around a center point:

// Define the rendering transform
AffineTransform at = new AffineTransform();
// Apply a translation transform to make room for the
// rotated text.
at.setToTranslation(400.0, 400.0);
g2.transform(at);
// Create a rotation transform to rotate the text
at.setToRotation(Math.PI / 2.0);
// Render four copies of the string “Java” at 90 degree angles
for (int i = 0; i < 4; i++) {
    g2.drawString(“Java”, 0.0f, 0.0f);
    g2.transform(at);
}

You can transform an image in the same way—the transform in the Graphics2D context is applied during rendering regardless of the type of graphic object being rendered.

To apply a transform to an image without changing the transform in the Graphics2D context, you can pass an AffineTransform to drawImage:

AffineTransform rotate45 =
  AffineTransform.getRotateInstance(Math.PI/4.0,0.0,0.0)
g2.drawImage(myImage, rotate45);

Transforms can also be applied to a Font to create a modified version of the Font, for more information see “Creating Font Derivations” on page 65.

2.3.6 Specifying a Composition Style

An AlphaComposite encapsulates composition rules that determine how colors should be rendered when one object overlaps another. To specify the composition style for the Graphics2D context, you create an AlphaComposite and pass it into setComposite. The most commonly used is composition style is SRC_OVER.

2.3.6.1 Using the Source Over Compositing Rule

The SRC_OVER compositing rule composites the source pixel over the destination pixel such that the shared pixel takes the color of the source pixel. For example, if you render a blue rectangle and then render a red rectangle that partially overlaps it, the overlapping area will be red. In other words, the object that is rendered last will appear to be on top.

To use the SRC_OVER composition rule:

  1. Create an AlphaComposite object by calling getInstance and specifying the SRC_OVER rule.
    2. AlphaComposite ac = AlphaComposite.getInstance(AlphaComposite.SRC_OVER);
  2. Call setComposite to add the AlphaComposite object to the Graphics2D context.

    g2.setComposite(ac);

Once the composite object is set, overlapping objects will be rendered using the specified composition rule.

2.3.6.2 Increasing the Transparency of Composited Objects

AlphaComposite allows you to specify an additional constant alpha value that is multiplied with the alpha of the source pixels to increase transparency.

For example, to create an AlphaComposite object that renders the source object 50% transparent, specify an alpha of .5:

AlphaComposite ac = AlphaComposite.getInstance(AlphaComposite.SRC_OVER, .5f);

In the following example, a source over alpha composite object is created with an alpha of .5 and added to the graphics context, causing subsequent shapes to be rendered 50% transparent.

public void paint(Graphics g) {
  Graphics2D g2 = (Graphics2D) g;

  g2.setColor(Color.red);
  g2.translate(100,50);
  // radians=degree * pie / 180
  g2.rotate((45*java.lang.Math.PI)/180);
  g2.fillRect(0,0,100,100);
  g2.setTransform(new AffineTransform());  // set to identity
  // Create a new alpha composite
  AlphaComposite ac =
      AlphaComposite.getInstance(AlphaComposite.SRC_OVER,0.5f);
  g2.setComposite(ac);
  g2.setColor(Color.green);
  g2.fillRect(50,0,100,100);
  g2.setColor(Color.blue);
  g2.fillRect(125,75,100,100);
  g2.setColor(Color.yellow);
  g2.fillRect(50,125,100,100);
  g2.setColor(Color.pink);
  g2.fillRect(-25,75,100,100);
}

2.4 Rendering Graphics Primitives

Graphics2D provides rendering methods for Shapes, Text, and Images:

  • draw—strokes a Shape’s path using the Stroke and Paint objects in the Graphics2D context.
  • fill—fills a Shape using the Paint in the Graphics2D context.
  • drawString—renders the specified text string using the Paint in the Graphics2D context.
  • drawImage—renders the specified image.

To stroke and fill a shape, you must call both the draw and fill methods.

Graphics2D also supports the draw and fill methods from previous versions of the JDK software, such as drawOval and fillRect.

2.4.1 Drawing a Shape

The outline of any Shape can be rendered with the Graphics2D.draw method. The draw methods from previous versions of the JDK software are also supported: drawLine, drawRect, drawRoundRect, drawOval, drawArc, drawPolyline, drawPolygon, draw3DRect.

When a Shape is drawn, its path is stroked with the Stroke object in the Graphics2D context. (See “Stroke Attributes” on page 19 for more information.) By setting an appropriate BasicStroke object in the Graphics2D context, you can draw lines of any width or pattern. The BasicStroke object also defines the line’s endcap and join attributes.

To render shape’s outline:

  1. Create a BasicStroke object
  2. Call Graphics2D.setStroke
  3. Create the Shape.
  4. Call Graphics2D.draw(shape).

In the following example, a GeneralPath object is used to define a star and a BasicStroke object is added to the Graphics2D context to define the star’s line with and join attributes.

public void paint(Graphics g) {
  Graphics2D g2 = (Graphics2D) g;

  // create and set the stroke
  g2.setStroke(new BasicStroke(4.0f));

  // Create a star using a general path object
  GeneralPath p = new GeneralPath(GeneralPath.NON_ZERO);
  p.moveTo(- 100.0f, - 25.0f);
  p.lineTo(+ 100.0f, - 25.0f);
  p.lineTo(- 50.0f, + 100.0f);
  p.lineTo(+ 0.0f, - 100.0f);
  p.lineTo(+ 50.0f, + 100.0f);
  p.closePath();

  // translate origin towards center of canvas
  g2.translate(100.0f, 100.0f);

  // render the star's path
  g2.draw(p);
}

2.4.2 Filling a Shape

The Graphics2D.fill method can be used to fill any Shape. When a Shape is filled, the area within its path is rendered with the Graphics2D context’s current Paint attribute—a Color, TexturePaint, or GradientPaint.

The fill methods from previous versions of the JDK software are also supported: fillRect, fill3DRect, fillRoundRect, fillOval, fillArc, fillPolygon, clearRect.

To fill a Shape:

  1. Set the fill color or pattern on the graphics context using
    Graphics2D.setColor or Graphics2D.setPaint.
  2. Create the Shape.
  3. Call Graphics2D.fill to render the Shape.

In the following example, setColor is called to define a green fill for a Rectangle2D.

public void paint(Graphics g) {
  Graphics2D g2 = (Graphics2D) g;

  g2.setPaint(Color.green);
  Rectangle2D r2 = new Rectangle2D.Float(25,25,150,150);

   g2.fill(r2);
}

2.4.3 Rendering Text

To render a text string, you call Graphics2D.drawString, passing in the string that you want to render. For more information about rendering text and selecting fonts, see “Fonts and Text Layout” on page 45.

2.4.4 Rendering Images

To render an Image, you create the Image and call Graphics2D.drawImage. For more information about processing and rendering images, see “Imaging” on page 67.

2.5 Defining Custom Composition Rules

You can create an entirely new type of compositing operation by implementing the Composite and CompositeContext interfaces. A Composite object provides a CompositeContext object that actually holds the state and performs the compositing work. Multiple CompositeContext objects can be created from one Composite object to maintain the separate states in a multithreaded environment.

2.6 Rendering in a Multi-Screen Environment

With the release of the JavaTM 2 SDK, version 1.3 and later versions, the Java 2DTM API supports three different multi-screen configurations that can possibly be configured by a native platform:

  • Two or more independent screens
  • Two or more screens where one screen is the primary screen and the other screens display copies of what appears on the primary screen.
  • Two or more screens that form a virtual desktop, which is also called a virtual device.

The Java 2D API enables you to create Frame, JFrame, Window, or JWindow objects with a GraphicsConfiguration to target a screen device for rendering.

In all three configurations, each screen device is represented by a GraphicsDevice. A GraphicsDevice can have multiple GraphicsConfiguration objects associated with it.

When two or more screens are used to form a virtual device, a virtual coordinate system that exists outside of the physical screens is used to represent the virtual device. The bounds of each GraphicsConfiguration in this multi-screen configuration are relative to the virtual coordinate system. One screen in this environment is identified as the primary screen, which is located at (0, 0) in the virtual coordinate system. Depending on the location of the primary screen, the virtual device might have negative coordinates, as shown in Figure 2-10:

example of a virtual device environment

Figure 2-10 Example of a virtual device environment

To determine if your environment is a virtual device environment in which a Window or a Frame can span two or more physical screens, call getBounds on each GraphicsConfiguration in your system and check to see if the origin is something other than (0, 0). The getBounds method of a GraphicsConfiguration returns a Rectangle in the virtual coordinate system. So, if any of the origins are not (0, 0), your environment is a virtual device environment.

In a virtual device environment, the coordinates of the GraphicsConfiguration objects are relative to the virtual coordinate system. So, you must use virtual coordinates when calling the setLocation method of a Frame or Window. For example, this code sample gets the bounds of a GraphicsConfiguration and uses the bounds to set the location of a Frame at (10, 10) relative to the origin of the physical screen of the corresponding GraphicsConfiguration.

Frame f = new Frame(GraphicsConfiguration gc);
Rectangle bounds = gc.getBounds();
f.setLocation(10 + bounds.x, 10 + bounds.y);

If the bounds of the GraphicsConfiguration are not taken into account, the Frame is displayed at (10, 10) on the primary physical screen, which might be different from the physical screen of the specified GraphicsConfiguration.

The getBounds method can also be used to determine the bounds of the virtual device. Call getBounds on each GraphicsConfiguration in your system. To determine the bounds of the virtual device, calculate the union of all the bounds. This technique is used in the following sample.

Rectangle virtualBounds = new Rectangle();
GraphicsEnvironment ge =
   GraphicsEnvironment.getLocalGraphicsEnvironment();
GraphicsDevice[] gs = ge.getScreenDevices();
for (int j = 0; j < gs.length; j++) {
   GraphicsDevice gd = gs[j];
   GraphicsConfiguration[] gc = gd.getConfigurations();
   for (int i = 0; i < gc.length; i++) {
      virtualBounds = virtualBounds.union(gc[i].getBounds());
   }
}

The following applet creates a JFrame with every GraphicsConfiguration of every GraphicsDevice in the GraphicsEnvironment. Each JFrame displays a set of red, green and blue stripes, the screen number, the GraphicsConfiguration number and the bounds of the GraphicsConfiguration. This code sample must be run with the JavaTM 2 SDK, version 1.3 or later.

import java.applet.Applet;
import java.awt.*;
import javax.swing.*;

public class MultiFrameApplet extends Applet {

    public MultiFrameApplet() {
        main(null);
    }

    public static void main(String[] argv) {
        GraphicsEnvironment ge =
           GraphicsEnvironment.getLocalGraphicsEnvironment();
        GraphicsDevice[] gs = ge.getScreenDevices();
        for (int j = 0; j < gs.length; j++) {
          GraphicsDevice gd = gs[j];
          GraphicsConfiguration[] gc =
             gd.getConfigurations();
             for (int i=0; i < gc.length; i++) {
               JFrame f =
                  new JFrame(gs[j].getDefaultConfiguration());
               GCCanvas c = new GCCanvas(gc[i]);
               Rectangle gcBounds = gc[i].getBounds();
               int xoffs = gcBounds.x;
               int yoffs = gcBounds.y;
               f.getContentPane().add(c);
               f.setTitle("Screen# "+Integer.toString(j)+",
                  GC# "+Integer.toString(i));
               f.setSize(300, 150);
               f.setLocation((i*50)+xoffs, (i*60)+yoffs);
               f.show();
             }
        }
    }
}

class GCCanvas extends Canvas {

    GraphicsConfiguration gc;
    Rectangle bounds;

    public GCCanvas(GraphicsConfiguration gc) {
        super(gc);
        this.gc = gc;
        bounds = gc.getBounds();
    }

    public Dimension getPreferredSize() {
        return new Dimension(300, 150);
    }

    public void paint(Graphics g) {
        g.setColor(Color.red);
        g.fillRect(0, 0, 100, 150);
        g.setColor(Color.green);
        g.fillRect(100, 0, 100, 150);
        g.setColor(Color.blue);
        g.fillRect(200, 0, 100, 150);
        g.setColor(Color.black);
        g.drawString("ScreenSize="+
           Integer.toString(bounds.width)+
           "X"+ Integer.toString(bounds.height), 10, 15);
        g.drawString(gc.toString(), 10, 30);
    }
}

Contents | Previous | Next Programmer's Guide to the JavaTM 2D API
JavaTM 2 SDK, Standard Edition, 1.4 version

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


This guide describes the features provided by the Java 2D™ API and illustrates how you can use the Java 2D API classes to enhance your applications. For additional information about the Java 2D APIs, see:

Contents | Previous | Next Programmer's Guide to the JavaTM 2D API

This guide describes the features provided by the Java 2D™ API and illustrates how you can use the Java 2D API classes to enhance your applications. For additional information about the Java 2D APIs, see:

  • The Java Tutorial, 2nd Volume. Available online at:
    http://java.sun.com/docs/books/tutorial/2d/index.html
  • The 2D Text Tutorial. Available online from the Java Developer Connection:
    http://developer.java.sun.com/developer/onlineTraining/Graphics/2DText/
  • The Java 2D Sample Programs. Available online at:
    http://java.sun.com/products/java-media/2D/samples/index.html
  • The Java 2D Demo. Available from the Java 2D website:
    http://java.sun.com/products/java-media/2D/index.html

    • This information in this guide is organized into seven chapters:

    Overview —introduces the packages and key classes in the Java 2D API.

    Rendering with Graphics2D—describes the Java 2D API classes in the java.awt package and how to set up the Graphics2D rendering context.

    Geometries—describes the Java 2D API classes in the java.awt.geom package and how to define and manipulate 2D shapes and areas.

    Fonts and Text Layout—describes the Java 2D API classes in the java.awt.font package, how to specify and retrieve font information, and how to display and manipulate international text using the Java 2D text layout APIs directly.

    Imaging—describes the Java 2D API classes in the java.awt.image, java.awt.image.codec, and java.awt.image.renderable packages and how to display and manipulate images and offscreen buffers.

    Color—describes the Java 2D API classes in the java.awt.color package and color management.

    Printing—describes the Java 2D API classes in the java.awt.print package and the Java 2D API printing model.

    Contents | Previous | Next Programmer's Guide to the JavaTM 2D API
    JavaTM 2 SDK, Standard Edition, 1.4 version

    Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


Accessibility - New Features

Java logo

Accessibility

New Features in JavaTM 2 Platform Standard Edition 5

 Java Accessibility
The features described here were introduced in Java 2 Platform Standard Edition 5. These features are also part of subsequent releases of the Java platform. Many of these additions were made to maintain compatibility between the Java Accessibility API and the GNOME Accessibility Framework, described at http://developer.gnome.org/projects/gap

Contents

AccessibleAction New Constant
AccessibleContext New Constants
AccessibleRelation New Constants
AccessibleRole New Constants
AccessibleState New Constants
AccessibleText New Constants
API Enhancements
AccessibleExtendedText
AccessibleStreamable
Accessibility Support for JSpinner and ProgressMonitor
AccessibleAction New Constant
Class AccessibleAction contains the following new constant:
  • TOGGLE_EXPAND
AccessibleContext New Constants
Class AccessibleContext contains the following new constants:
  • ACCESSIBLE_COMPONENT_BOUNDS_CHANGE
  • ACCESSIBLE_INVALIDATE_CHILDREN
  • ACCESSIBLE_TEXT_ATTRIBUTE_CHANGED
AccessibleRelation New Constants
Class AccessibleRelation contains the following new constants:
  • CHILD_NODE_OF
  • CHILD_NODE_OF_PROPERTY
  • EMBEDS
  • EMBEDS_PROPERTY
  • EMBEDDED_BY
  • EMBEDDED_BY_PROPERTY
  • FLOWS_FROM
  • FLOWS_FROM_PROPERTY
  • FLOWS_TO
  • FLOWS_TO_PROPERTY
  • PARENT_WINDOW_OF
  • PARENT_WINDOW_OF_PROPERTY
  • SUBWINDOW_OF
  • SUBWINDOW_OF_PROPERTY
AccessibleRole New Constants
Class AccessibleRole contains the following new constants:
  • EDITBAR
  • FOOTER
  • HEADER
  • PARAGRAPH
  • PROGRESS_MONITOR
  • RULER
AccessibleState New Constants
Class AccessibleState contains the following new constants:
  • INDETERMINATE
  • MANAGES_DESCENDANTS
  • TRANSIENT
  • TRUNCATED
AccessibleText New Constants
Class AccessibleText contains the following new constants:
  • LINE
  • ACCESSIBLE_CHANGED_TEXT
  • ATTRIBUTE_RUN
API Enhancements
The following new classes and interfaces have been added to the JavaTM Accessibility API:
  • javax.accessibility.AccessibleExtendedText
  • javax.accessibility.AccessibleStreamable
AccessibleExtendedText
Interface AccessibleExtendedText provides support for braille and screen reader review mode.
AccessibleStreamable
Interface AccessibleStreamable provides a stream interface to raw data based on mime type.
Accessibility Support for JSpinner and ProgressMonitor
This release provides accessibility support for spinners and progress monitors in Swing.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: access@sun.com 		Sun


Accessibility - New Features

Java logo

Accessibility

New Features in the JavaTM 2 Platform, v1.4

 Java Accessibility
The features described here were introduced in the Java 2 Platform, v1.4.0. These features are also part of subsequent releases of the Java 2 Platform.

Contents

AccessibleExtendedComponent.getAccessibleKeyBinding
AccessibleRole New Constants
Accessibility Support for HTML Object Tags
Support for Tracking HTMLEditorKit Keyboard Link Traversal
Assistive Technologies Property
Screen Reader Property
API Enhancements
AccessibleEditableText
AccessibleExtendedComponent
AccessibleExtendedTable
AccessibleKeyBinding
Mnemonic Tab Navigation
List Navigation by First Letter
Accessibility Support for HTML Components
Screen Magnifier Property
AccessibleExtendedComponent.getAccessibleKeyBinding
Interface AccessibleExtendedComponent has a new method, getAccessibleKeyBinding, to return key bindings associated with an object.
AccessibleRole New Constants
Class AccessibleRole contains the following new constants:
  • DATE_EDITOR
  • FONT_CHOOSER
  • GROUP_BOX
  • SPIN_BOX
  • STATUS_BAR
Accessibility Support for HTML Object Tags
This release adds accessibility support for HTML object tags. CTRL-t and SHIFT-CTRL-t navigate to the next and previous component, respectively, associated with an object tag in an HTML document. CTRL-SPACE activates the default action associated with the component.
Support for Tracking HTMLEditorKit Keyboard Link Traversal
Assistive technologies needed a way to track HTMLEditorKit keyboard link traversal. The constant AccessibleContext.ACCESSIBLE_HYPERTEXT_OFFSET was added to support this feature.
Assistive Technologies Property
The javax.accessibility.assistive_technologies property specifies the assistive technologies to load into the JVM.
Screen Reader Property
The javax.accessibility.screen_reader_present property, when set to true, lets the Java platform libraries know that a screen reader is present on the system. Application developers can check this property. If an application is self-voicing and a screen reader is present, developers can turn off the self-voicing.
API Enhancements
The following new classes and interfaces have been added to the JavaTM Accessibility API:
  • javax.accessibility.AccessibleEditableText
  • javax.accessibility.AccessibleExtendedComponent
  • javax.accessibility.AccessibleExtendedTable
  • javax.accessibility.AccessibleKeyBinding
In addition, javax.accessibility.AccessibleContext was updated to reflect the new classes and interfaces.
AccessibleEditableText
Interface AccessibleEditableText provides support for text editing by assistive technologies.
AccessibleExtendedComponent
Interface AccessibleExtendedComponent provides the standard mechanism for an assistive technology to determine the extended graphical representation of an object.
AccessibleExtendedTable
Interface AccessibleExtendedTable provides extended information about a user-interface component that presents data in a two-dimensional table format.
AccessibleKeyBinding
Interface AccessibleKeyBinding provides the standard mechanism for an assistive technology to determine the key bindings which exist for an object.
Mnemonic Tab Navigation
This new feature provides support for easier tab navigation using mnemonics on a JTabbedPane.
List Navigation by First Letter
This new feature provides support for list navigation using the first letter of list items.
Accessibility Support for HTML Components
This release provides accessibility support for HTML components in Swing.
Screen Magnifier Property
The javax.accessibility.screen_magnifier_present property, when set to true, lets the Java platform libraries know that a screen magnifier is present on the system. Application developers can check this property, and if a screen magnifier is present, developers should make sure their applications are compatible with screen magnification.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: access@sun.com 		Sun


Accessibility Properties

 Java Accessibility

Available Properties

The javax.accessibility package provides the following properties:
  • assistive_technologies
  • screen_magnifier_present
  • screen_reader_present

Loading Assistive Technologies

The assistive_technologies property specifies the assistive technologies to load into the JVM. It takes a comma-delimited list as input.

Indicating the Presence of a Screen Magnifier

When the screen_magnifier_present property is set to true, it lets the Java platform libraries know that a screen magnifier is present on the system. Application developers can check this property, and if a screen magnifier is present, developers should make sure their applications are compatible with screen magnification. For example, on Microsoft Windows operating systems, the reference implementation of the Java 2DTM API checks this property and if true, turns off Microsoft DirectDraw to avoid problems with the screen magnifier. (Some screen magnifiers may not be able to magnify DirectDraw graphics.)

Indicating the Presence of a Screen Reader

When the screen_reader_present property is set to true, it lets the Java platform libraries know that a screen reader is present on the system. Application developers can check this property. If an application is self-voicing and a screen reader is present, developers can turn off the self-voicing.

Setting Properties

You can set a property at run time or in a properties file. To set a property at run time, enter a command such as the following:

java -Djavax.accessibility.screen_magnifier_present=true foo.class

The reference implementation includes an accessibility.properties file in the jre/lib directory. To set a property in the accessibility.properties file, add a line or lines such as the following:

assistive_technologies=Ferret,Monkey
screen_magnifier_present=true
screen_reader_present=true

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.
Please send comments to: access@sun.com 		Sun


Java Accessibility

Java logo

JavaTM Accessibility

 Documentation Contents
With the Java Accessibility API, developers can easily create Java applications that are accessible to persons with disabilities. Accessible Java applications are compatible with assistive technologies such as screen readers, speech recognition systems, and refreshable braille displays.

Overview

  • Accessibility Overview

API Specification

  • javax.accessibility
  • Accessibility Properties

Tutorials and Programmer's Guides

  • How to Support Assistive Technologies from The Swing Tutorial.

API Enhancements

  • Accessibility Enhancements in the Java 2 Platform Standard Edition 5.0
  • Accessibility Enhancements in the Java 2 Platform, v1.4

More Information

  • Java Accessibility Utilities
    The Utilities help assistive technologies take advantage of the Java Accessibility API.
  • Java Access Bridge for Microsoft Windows
    The Java Access Bridge for Microsoft Windows allows Windows-native assistive technologies to provide access to Java applications running on Windows to assistive technologies on Windows.
  • Assistive Technology Defined
  • The JFC Home Page
  • Sun Microsystems' Accessibility Program

Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: access@sun.com 		Sun


Java Accessibility Overview

 Documentation Contents

Java Accessibility API

The Java Accessibility API (JAAPI) is one of the core parts of the Java Foundation Classes (JFC). The JFC are a comprehensive set of graphical user interface components and foundation services designed to simplify deployment of Internet, intranet and desktop applications. The JAAPI makes GUI component information available to assistive technologies, giving users alternative presentation and control of Java applications.

Java Accessibility Utilities

The Java Accessibility Utilities help assistive technologies take advantage of the Java Accessibility API. The Utilities monitor events related to UI components. They also help assistive technologies get additional information about a GUI, such as the current position of the mouse, or the window that currently has focus.

The Utilities are released separately from the JFC, but they can be downloaded from the JFC Home Page.

Pluggable Look and Feel

The Java Foundation Classes implement a Pluggable Look and Feel architecture. This architecture allows non-visual manifestations of a user interface to replace or enhance the visual presentation of an application. The expression of the user interface is separated from the underlying structure and data of each individual component. This is accomplished by separating the user interface of the component from its model. The model of a component is the structure which encapsulates the state and information that is presented to the user by the user interface. More information on this architecture can be found in The Swing Connection.


Annotation Processing Tool

Java

Annotation Processing Tool (apt)

 Documetation Contents
apt is a command-line utility for annotation processing. It includes a set of reflective APIs and supporting infrastructure to process program annotations (JSR 175). These reflective APIs provide a build-time, source-based, read-only view of program structure. They are designed to cleanly model the JavaTM programming language's type system after the addition of generics (JSR 14).

apt first runs annotation processors that can produce new source code and other files. Next, apt can cause compilation of both original and generated source files, thus easing the development cycle.

JSR 269, also known as the Language Model API, has two basic pieces: an API that models the Java programming language, and an API for writing annotation processors. This functionality is accessed through new options to the javac command; by including JSR 269 support, javac now acts analogously to the apt command in JDK 5.

API Specification
  • Mirror API
  • javax.annotation.processing
  • javax.lang.model
  • javax.lang.model.element
  • javax.lang.model.type
  • javax.lang.model.util
Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Feedback

Sun


Getting Started with the Annotation Processing Tool

Java

Getting Started with
the Annotation Processing Tool (apt)

 apt Contents

What is apt?

The command-line utility apt, annotation processing tool, finds and executes annotation processors based on the annotations present in the set of specified source files being examined. The annotation processors use a set of reflective APIs and supporting infrastructure to perform their processing of program annotations (JSR 175). The apt reflective APIs provide a build-time, source-based, read-only view of program structure. These reflective APIs are designed to cleanly model the JavaTM programming language's type system after the addition of generics (JSR 14). First, apt runs annotation processors that can produce new source code and other files. Next, apt can cause compilation of both original and generated source files, thus easing the development cycle.

Why Should I Use apt?

Many of the intended use cases for annotations involve having annotations in a base file hold information that is used to generate new derived files (source files, class files, deployment descriptors, etc.) that are logically consistent with the base file and its annotations. In other words, instead of manually maintaining consistency among the entire set of files, only the base file would need to be maintained since the derived files are generated. The apt tool is designed for creating the derived files.

Compared to using a doclet to generate the derived files based on annotations, apt

  • has a cleaner model of the declarations and current type structure of programs
  • uses a more contemporary API design, such as returning generic collections instead of arrays and providing visitors to operate on declarations and types
  • supports recursive processing of newly generated files and can automatically cause compilation of original and generated source files
While intended for annotation processing, apt can be used for other reflective programming tasks too.

How to use apt

Overview

First, apt determines what annotations are present on the source code being operated on. Next, apt looks for annotation processor factories you've written. The tool asks the factories what annotations they process. Then apt asks a factory to provide an annotation processor if the factory processes an annotation present in source files being operated on. Next, the annotation processors are run. If the processors have generated new source files, apt will repeat this process until no new source files are generated.

Developing an Annotation Processor

Writing an annotation processor relies on four packages:
  • com.sun.mirror.apt: interfaces to interact with the tool
  • com.sun.mirror.declaration: interfaces to model the source code declarations of fields, methods, classes, etc.
  • com.sun.mirror.type: interfaces to model types found in the source code
  • com.sun.mirror.util: various utilities for processing types and declarations, including visitors
Each processor implements the AnnotationProcessor interface in the package com.sun.mirror.apt. This interface has one method -- process -- used by the apt tool to invoke the processor. A processor will "process" one or more annotation types.

A processor instance is returned by its corresponding factory -- an AnnotationProcessorFactory. The apt tool calls the factory's getProcessorFor method to get hold of the processor. During this call, the tool provides an AnnotationProcessorEnvironment. In the environment the processor will find everything it needs to get started, including references to the program structure on which it is operating, and the means to communicate and cooperate with the apt tool by creating new files and passing on warning and error messages.

There are two ways a factory can be found; the factory to use can be specified via the "-factory" command line option or the factory can be located during the apt discovery procedure. Using the "-factory" option is the simplest way to run a single known factory; this option may also be used when a factory needs more control over how it is run. To locate the factories on a particular path, the discovery procedure retrieves from jar files META-INF/services information in the format described below.

To create and use an annotation processor using the "-factory" option:

  1. Write an AnnotationProcessorFactory that in turn can create an AnnotationProcessor for the annotation type(s) of interest.
  2. Compile the processors and factories using javac with tools.jar on the classpath; tools.jar contains the com.sun.mirror.* interfaces.
  3. Put the compiled class files, or jar files containing the class files, on the appropriate path when invoking apt
To create and use an annotation processor with the default discovery procedure use the same first two steps then,
  3. Create a UTF-8 encoded text file in META-INF/services named com.sun.mirror.apt.AnnotationProcessorFactory whose contents are a list of fully qualified names of the concrete factory classes, one per line. (This is the same format used by sun.misc.Service.)
  4. Package the factory, processor, and META-INF/services information into a jar file
  5. Place the jar file on the appropriate path when invoking apt. The appropriate path is discussed in the Discovery section.

A Simple Sample Annotation Processor

import com.sun.mirror.apt.*;
import com.sun.mirror.declaration.*;
import com.sun.mirror.type.*;
import com.sun.mirror.util.*;

import java.util.Collection;
import java.util.Set;
import java.util.Arrays;

import static java.util.Collections.*;
import static com.sun.mirror.util.DeclarationVisitors.*;

/*
 * This class is used to run an annotation processor that lists class
 * names.  The functionality of the processor is analogous to the
 * ListClass doclet in the Doclet Overview.
 */
public class ListClassApf implements AnnotationProcessorFactory {
    // Process any set of annotations
    private static final Collection<String> supportedAnnotations
        = unmodifiableCollection(Arrays.asList("*"));

    // No supported options
    private static final Collection<String> supportedOptions = emptySet();

    public Collection<String> supportedAnnotationTypes() {
        return supportedAnnotations;
    }

    public Collection<String> supportedOptions() {
        return supportedOptions;
    }

    public AnnotationProcessor getProcessorFor(
            Set<AnnotationTypeDeclaration> atds,
            AnnotationProcessorEnvironment env) {
        return new ListClassAp(env);
    }

    private static class ListClassAp implements AnnotationProcessor {
        private final AnnotationProcessorEnvironment env;
        ListClassAp(AnnotationProcessorEnvironment env) {
            this.env = env;
        }

        public void process() {
        for (TypeDeclaration typeDecl : env.getSpecifiedTypeDeclarations())
        typeDecl.accept(getDeclarationScanner(new ListClassVisitor(),
                              NO_OP));
        }

    private static class ListClassVisitor extends SimpleDeclarationVisitor {
        public void visitClassDeclaration(ClassDeclaration d) {
        System.out.println(d.getQualifiedName());
        }
    }
    }
}

A number of new language and library features are used in the sample processor. First, static imports are used so that the simple name of various utility methods can be used; for example
"unmodifiableCollection"
instead of
"Collections.unmodifiableCollection".
Second, generic collections are used throughout. The Arrays.asList method is now a var-args method so it can accept a comma separated list of strings and create a list with the desired elements. The Collections.emptySet method is a generic method and can be used to create a type-safe empty set. The for loop in the process method is an enhanced for loop that can iterate over collections.

Specifying the Annotations to Process

To tell the tool what annotations it processes, a factory returns a collection of import-style strings, as shown in the example. A particular string entry may have one of the following three forms:
*
Process all annotations. This also processes an empty list of annotations; in other words, a factory that processes * could be asked to provide a non-trivial processor even if no annotations are present. This capability allows the com.sun.mirror APIs to be used to write general source code processing tools.
foo.bar.Baz
Process an annotation whose canonical name is "foo.bar.Baz".
foo.bar.*
Process annotations whose canonical names start with "foo.bar.".

The apt tool presents the factory with a set of annotations for the factory to process. Based on the set of annotations and the annotation processor environment, the factory returns a single annotation processor. What if the factory wants to return multiple annotation processors? The factory can use com.sun.mirror.apt.AnnotationProcessors.getCompositeAnnotationProcessor to combine and sequence the operation of multiple annotation processors.

Specifying the Command Line Options to Recognize

The supportedOptions method allows a factory to communicate to apt which command line options it recognizes. Command line options starting with "-A" are reserved for communicating with annotation processors. For example, if this factory recognizes options such as -Adebug and -Aloglevel=3, it will return the strings "-Adebug" and "-Aloglevel". In the future, apt may give an indication if -A options are given that no factory recognizes.

The apt Command Line

In addition to its own options, the apt tool accepts all of the command-line options accepted by javac. The javac options are passed to the final javac call, if any.

The apt specific options are:

-s dir
Specify the directory root under which processor-generated source files will be placed; files are placed in subdirectories based on package namespace
-nocompile
Do not compile source files to class files.
-print
Print out textual representation of specified types; perform no annotation processing or compilation.
-A[key[=val]]
Options to pass to annotation processors -- these are not interpreted by apt directly, but are made available for use by individual processors
-factorypath path
Specify where to find annotation processor factories; if this option is used, the classpath is not searched for factories.
-factory classname
Name of AnnotationProcessorFactory to use; bypasses default discovery process
How apt shares some of javac's options:
-d dir
Specify where to place processor and javac generated class files
-cp path or -classpath path
Specify where to find user class files and annotation processor factories. If -factorypath is given, the classpath is not searched for factories.
There are a few apt hidden options that may be useful for debugging:
-XListAnnotationTypes
List found annotation types
-XListDeclarations
List specified and included declarations
-XPrintAptRounds
Print information about initial and recursive apt rounds
-XPrintFactoryInfo
Print information about which annotations a factory is asked to process

How the apt Tool Operates

Discovery

After scanning the source files on the command line to determine what annotations are present, by default the apt tool looks for annotation processor factories on the appropriate path. If the -factorypath option is used, that path is the appropriate path to search for factories; otherwise, the classpath is the appropriate path. The factories are queried to determine what annotations they process. If a factory processes one of the annotations present, that annotation is considered claimed. Once all annotations are claimed, the tool does not look for additional factories. After the annotations are all claimed or no more factories can be found, apt will call the factories' getProcessorFor methods, passing in the set of annotations that factory has claimed. Each factory returns a single processor to perform the appropriate processing for the set of annotations in question. After all processors are returned, apt calls each processor in turn. If any processor generated a new source file, a recursive round of apt will occur. In recursive apt rounds, discovery calls getProcessorFor on any factory that provided a processor in a previous round, even if that factory processes none of the current annotations. This allows the factory to register a listener in subsequent apt rounds; though most factories will simply return AnnotationProcessors.NO_OP in this case. After a round where no new source files are generated, apt will invoke javac on the original and generated source files. If no processors are found or the processors found don't process the annotations present, calling apt is essentially equivalent to calling javac directly on the source files.

If a factory class is used by more than one round of annotation processing, the factory class is loaded once and the factory's getProcessorFor method will be called once per round. This allows a factory to store static state across rounds.

If the -factory option is used, the named factory is the only one queried.

Rounds of apt Processing

The first round of apt analyzes the input source files, runs the discovery procedure, and calls the resulting annotation processors. The second round of apt analyzes the new source files produced by the first round (if any), runs the discovery procedure on those new files, and calls the resulting annotation processors. Likewise, if the second round has produced new source files, the third round analyzes the new source, runs discovery, etc. The apt rounds continue until no new source files are generated. Finally, after the last round, by default the apt tool will run javac on the original and generated source files.

Listeners

Annotation processors or factories can register listeners for the end of a round using the addListener method in the environment. The tool calls the registered listeners after all annotation processors for that round have run to completion. The listener is passed information about the status of the round, such as if any new source files were written, if an error was raised, and if the just completed round was the last round. Listeners can be used to write out trailing ends of files when all annotation processing has completed. The same class can implement both the AnnotationProcessor and RoundCompleteListener interfaces so the same object can serve in both contexts.

Return Code

If javac is invoked after the last apt round, the return code of apt will be the return code of javac compiling those files. If javac is not invoked, apt will have a 0 exit status if no errors were reported, either by the tool itself or by processors. Operating on malformed or incomplete source files in and of itself is not sufficient to cause apt to have a nonzero exit status.

Declarations and Types

The mirror API represents source code constructs principally through the Declaration interface and its hierarchy of subinterfaces, in the package com.sun.mirror.declaration. A Declaration represents a program element such as a package, class, or method, and typically corresponds one-to-one with a particular fragment of source code. Declarations are the structures that may be annotated.

Types are represented by the TypeMirror interface and its hierarchy of subinterfaces in the package com.sun.mirror.type. Types include primitive types, class and interface types, array types, type variables, and wildcard types.

The API is careful to distinguish between declarations and types. This is most significant for generic types, where a single declaration can define a whole family of types. For example, the declaration of the class java.util.Set corresponds to

  • the parameterized type java.util.Set<String>
  • the parameterized type java.util.Set<Number>
  • the parameterized type java.util.Set<T> for some type T other than String or Number
  • the raw type java.util.Set.
A declaration has doc comments, a source position, modifiers, and annotations. A declaration may have different kinds of names (simple, qualified). More specific declaration subclasses provide additional information appropriate for that construct. For example, class declarations provide access to constructors and the superclass. A declaration for an enum has a method to provide the enum constants.

TypeMirrors are used to model the return types, parameter types, etc., in source code. A TypeMirror for a reference type provides a mapping from a type to corresponding declaration; for example from the type mirror for java.util.Set<String> to the declaration for java.util.Set.

FAQs

  • Do you know about the Debian Advanced Packaging Tool?
    Yes.
  • How does an annotation processor compare to a doclet?
    The two entities certainly have some similarities; both use build-time reflective APIs to process source code. However, the mirror APIs used in annotation processors better model the current type system of the Java programming language. Also, by default the annotation processor(s) to run are determined by the annotations present in the source code rather than only on a mechanism analogous to the -doclet option. In other words, instead of running a single fixed doclet, apt dynamically chooses potentially multiple processors to run.
  • How can I process annotations on local variables?
    Annotations on local variables are invisible since the declaration hierarchy does not model program structure inside a method or constructor.
  • Why are there separate factory and processor interfaces in com.sun.mirror.apt?
    It would be possible to combine determining how to process and controlling when to process; however, we choose to distinguish and separate the two steps with factory and processor interfaces.
  • Is there an apt ant task
    Not at present.
  • What is a mirror?
    Somewhere you find a reflection. In reflective programming, a mirror design maintains a consistent separation between the objects being represented and the objects doing the representing.
  • Why were the annotations a factory supports and the options a factory supports returned by methods instead of being encoded as annotations on the factory class?
    Implementing an interface is the usual mechanism to indicate a class has a desired capability, such as providing an indication of what annotations it processes. There is no language mechanism to require a class be annotated with a particular annotation type. Therefore, while it would have been technically possible to encode such information in annotations, doing so would have lacked the type safety of just having methods in an interface.
  • I'm not familiar with visitors, do I have to use them?
    The visitor pattern is one of the standard patterns in the "Gang of Four" Design Patterns book. The pattern provides a powerful mechanism to invoke a type-dependent operation without explicitly testing for the type. However, using visitors is not mandatory.

See Also

  • apt Tool Reference Page
  • Mirror API Specification
Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved. Sun


Attach API

 Documetation Contents
The Attach API is a Sun Microsystems extension that provides a mechanism to attach to a JavaTM virtual machine. A tool written in the Java Language, uses this API to attach to a target virtual machine and load its tool agent into that virtual machine. For example, a management console might have a management agent which it uses to obtain management information from instrumented objects in a virtual machine. If the management console is required to manage an application that is running in a virtual machine that does not include the management agent, then this API can be used to attach to the target virtual machine and load the agent.

API Specification
  • Attach API
Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved. Sun


Abstract Window Toolkit

Java

Abstract Window Toolkit (AWT)

 Documentation Contents

The Abstract Window Toolkit (AWT) supports Graphical User Interface (GUI) programming. AWT features include:
  • a set of native user interface components
  • a robust event-handling model
  • graphics and imaging tools, including shape, color, and font classes
  • layout managers, for flexible window layouts that don't depend on a particular window size or screen resolution
  • data transfer classes, for cut-and-paste through the native platform clipboard
The Swing classes are built on top of the AWT architecture.

API Specification

  • API Reference
  • Focus Model Specification

Tutorials and Programmer's Guides

  • The Swing Tutorial touches on parts of the AWT that support the Swing architecture:
    • Introduction to Event Listeners
    • Top-Level Containers and the Containment Hierarchy
    • Laying out Components in a Container
  • Full-Screen Exclusive Mode API

API Enhancements

  • AWT Enhancements in the Java 2 Platform Standard Edition 5.0
  • AWT Enhancements in the Java 2 SDK, v1.4

More Information

  • XAWT
  • AWT Native Interface
  • Drag and Drop and Data Transfer
  • Java 2D Graphics and Imaging
Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved. Please send comments to: java-awt@java.sun.com Sun Microsystems, Inc
Java Software


AWT Enhancements

Java

AWT Enhancements in the JavaTM 2 SDK, v1.4

 Documentation Contents
1.4.2 Bug Fixes
1.4.1 Bug Fixes
New Focus Subsystem
Deprecated Focus Methods
ActionEvents (and Other Events) Need Timestamps
Headless Support
Window Centering API Required for Multiscreen Support
The New Fullscreen Exclusive Mode API
Sync Out of Range Error From Video Driver Under Windows NT Undecorated Frames
Mouse Wheel Support
Programmatic Zooming of Frames
Dynamic Layout During Resize
Access to Component Listener Lists
Changes to Drag and Drop
64-Bit Compliance on Solaris
Inconsistent DLLs Warning
Removal of the DrawingSurface API
New InputEvent Key Modifiers
Change in Drop Down Behavior for Choice Menus
Choice Component Now Obeys Layout Manager Constraints
1.4.2 Bug Fixes

4648702: On Microsoft Windows 2000 and Windows XP, a TextArea will sometimes display only a vertical scrollbar, even though the SCROLLBARS_BOTH field is set to true.

4636311: Modal dialogs may hang when run from a Runnable on release 1.3.1 and 1.4.

4385243: Unable to input text in Microsoft Windows locales that don't have an ANSI code page (such as Hindi).

1.4.1 Bug Fixes

4690831: Game applets fail to repaint properly with Internet Explorer.

4627627: Focus traversal keys moved from awt.properties to Preferences API.

4636548/ 4639735: Crash of release 1.4 when screensaver on Microsoft Windows 2000 is activated.

4379138: Problems on Linux with key events for some dead keys.

4627542: Swing applications don't support international keyboards under Linux.

4395157: Under Linux on 1.3, can't type "%" in applets.

4669873: A drag and drop bug, reported on hopper-beta under Microsoft Windows, caused an application to briefly freeze during DnD and is fixed in the final release of 1.4.1.

New Focus Subsystem

The bugtraq report that corresponds to this change is: 4290675.

A new focus subsystem replaces the previous focus architecture and addresses many focus-related bugs caused by platform inconsistencies, and incompatibilities between AWT and Swing components. See the new Focus Model Specification for further details.

See the javadoc here.

Headless Support

The bugtraq report that corresponds to this change is: 4281163.

Many environments, such as mainframe machines and dedicated servers, do not support a display, keyboard, or mouse. Headless support is enabled by the new GraphicsEnvironment methods isHeadless and isHeadlessInstance. These methods indicate whether a display, keyboard, and mouse can be supported in a graphics environment.

The API changes for headless include:

  • A new public exception class, java.awt.HeadlessException, is introduced. It is derived from UnsupportedOperationException, which derives from RuntimeException, so that existing implementations of methods that throw the new exception will not require signature changes.
  • Two new methods, are added to java.awt.GraphicsEnvironment.
        public static boolean isHeadless()

    public boolean isHeadlessInstance()
  • The constructors of Applet and all heavyweight components (*) are changed to throw HeadlessException if a display, keyboard, and mouse are not supported by the toolkit implementation. All javadoc tags on all constructors are changed to reflect this RuntimeException.
  • The Robot constructor throws an AWTException if a display, keyboard, and mouse are not supported by the toolkit implementation.
  • Many of the methods in Toolkit and GraphicsEnvironment, with the exception of fonts, imaging, and printing, are changed to throw HeadlessException if a display, keyboard, and mouse are not supported. All the javadoc tags on these methods are changed to reflect this RuntimeException.
  • Other methods that may be affected by lack of display, keyboard, or mouse support, are changed to throw HeadlessException.
  • It should be worth noting that the HeadlessException is thrown if and only if isHeadless returns true, and that all javadoc comments should specify this.

(*)Applet, Button, Checkbox, Choice, FileDialog, Label, List, Menu, MenuBar, MenuComponent, MenuItem, PopupMenu, Scrollbar, ScrollPane, TextArea, TextComponent, Frame, Window, Dialog, JApplet, JFrame, JWindow, JDialog, and TextField. Canvas and Panel do not need to throw this exception since these can be given empty peers and treated as lightweights.

To run our environment with a headless implementation, the follow property may be specified at the java command line:

  -Djava.awt.headless=true
If this property is not specified and a display, keyboard, and mouse are not supported, then headless implementation is used by default.

Source code should check for headless, so that the exception may be caught gracefully. For example, see the following pre-headless implementation of the class Foo:

class Foo {
  static Choice c = new Choice();  // could throw HeadlessException
}
The new and improved implementation of Foo should be placed in a static block:
class Foo {
  static Choice c;
  static {
    try {
      c = new Choice();
    catch (HeadlessException e) {
        ...
    }
  }
}

The New Fullscreen Exclusive Mode API

The bugtraq report that corresponds to this change is: 4189326.

The new full-screen exclusive mode API supports high performance graphics by suspending the windowing system so that drawing can be done directly to the screen. Full screen mode, which is entirely different from simply taking an AWT Frame, Window, or Dialog and expanding it to fit the screen, is a graphics mode whereby the application takes entire control over the contents of video memory. The application tells the graphics card what to draw, how to draw it, and when to draw it. This mode is not always available. On some operating systems, it may not be implemented at all. On other operating systems, it may only be available if the capability is supported by the graphics card. Nevertheless, this mode is critical for performance and is necessary for enabling hardware page-flipping on Windows.

For a tutorial explaining how to use the full screen exclusive API mode with several code examples, see here.

API Changes:

  • A new public final class, java.awt.DisplayMode, is introduced.
  • Changes to java.awt.GraphicsDevice:
        public void setFullScreenWindow(Window w)

    public Window getFullScreenWindow()

    public boolean isDisplayChangeSupported()

    public void setDisplayMode(DisplayMode dm)

    public DisplayMode getDisplayMode()

    public DisplayMode[] getDisplayModes()
  • The algorithm which handles direct video buffer control has been localized to a new class, java.awt.image.BufferStrategy.
  • A new class java.awt.BufferCapabilities can be used when creating a buffer strategy. Likewise, a new class java.awt.ImageCapabilities is available to define the image capabilities of a specific configuration.
  • An application programmer can create and use a buffer strategy from a Canvas or a Window. There are two buffer strategies that are supported as protected inner classes: java.awt.Component.FlipBufferStrategy and java.awt.Component.BltBufferStrategy. One of these two inner classes is used on the Canvas or Window when the createBufferStrategy method is called, depending on the BufferCapabilities object supplied when creating the strategy (if any). To get the buffer strategy used by a particular component, the getBufferStrategy method is used.
Sync Out of Range Error From Video Driver Under Windows NT

The bugtraq report that corresponds to this change is: 4452207.

If you have a Dell Optiplex GX110 using an Intel 810 Graphics Controller, under Windows NT, you may get a "sync out of range" message from the video driver if you change the display mode more than once and use a high display resolution. There is evidently a bug in the (DirectX) video driver that is causing this. There are several workarounds to this problem:

  • Disable DirectDraw by using -Dsun.java2d.noddraw=true at the command line.
  • Do not change the display resolution more than once during the lifetime of a program that is intended to run on this hardware.
  • Disallow the following display modes on this hardware:
        1152 X 864     8       85
    1152 X 864     16      85
    1152 X 864     24      85

    1280 X 1024    8       70,72,75,85
    1280 X 1024    16      70,72,75,85
    1280 X 1024    24      70,75,85

    Bad Color (Unsatisfactory appearance in terms of color)

    1024 X 768     8       60,70,72,75,85

Undecorated Frames

The bugtraq report that corresponds to this change is: 4038769.

For certain applications having no native frame decorations makes sense. For example, applications that will run across many platforms and that require that the look and feel is the same, or when the programmer does not want the end-user coming in contact with the native operating system.

This release allows a Java application to turn off the creation of frame decorations; no native titlebar, system menu, border, or other native operating system dependent screen components appear when this mode is enabled. AWT and Swing components work transparently.

Changes to java.awt.Frame:

    public void setUndecorated(boolean undecorated)

    public boolean isUndecorated()

Changes to java.awt.Dialog:

    public void setUndecorated(boolean undecorated)

    public boolean isUndecorated()

Mouse Wheel Support

The bugtraq report that corresponds to this change is: 4289845.

The mouse wheel, with a scroll wheel in place of the middle mouse button, is enabled with new built-in Java support for scrolling via the mouse wheel. The java.awt.event.MouseWheelEvent class enables seamless support for mouse wheel scrolling in Java applications with no recompiling required. Also, a new java.awt.event.MouseWheelListener interface allows customization of mouse wheel behavior.

Note, for those using the mouse wheel on Linux, see here.

  • Scrolling Behavior:

    • A scrollbar is considered "scrollable" if it is both showing and there is more content in the scrolling Component than can be displayed at once, such that the scroll thumb does not occupy the entire scroll track.
    • It is possible for a scrollbar to be showing, but not be scrollable. Usually this occurs when a scrollbar is set to always be displayed.
    • The scrollbar to be scrolled by the mouse wheel is determined as follows:
      • If only one scrollbar is scrollable, it will be scrolled.
      • If both a horizontal and a vertical scrollbar are scrollable, the vertical scrollbar will be scrolled.
    • Wheel scrolling may be disabled altogether using setWheelScrollEnabled(false).
    • Up/away-from-user rotations cause vertical scroll bars to scroll upwards, and horizontal scrollbars to scroll to the left. Just the opposite is true for down/towards rotations.
    • No scrolling takes place if a scroll thumb is at the end of the scroll track.

  • Heavyweight support:

    • Some native peers with integrated scroll bars can handle mouse wheel scrolling by themselves. Examples on Windows includes TextArea, Choice, FileDialog, and List. Such components will let their native peers handle wheel scrolling.
    • Components which do not inherit any native mouse wheel behavior will propagate mouse wheel events up the Container hierarchy until a Container with MouseWheelEvents enabled is found. This is typically a ScrollPane. Mouse wheel events are delivered to the Component with MouseWheelEvents enabled.
    • Alternatively, client programmers may add MouseWheelListeners to customize what happens when the mouse wheel is moved while the mouse is over a Component. In the case of Components that already have native handling of mouse wheel events, clients may consume the mouse wheel event to avoid native handling.
    • java.awt.ScrollPane is modified to have MouseWheelEvents enabled by default. When a ScrollPane receives a MouseWheelEvent, it will properly scroll its contained Component. This functionality may be disabled with the new setWheelScrollingEnabled method.

  • Lightweight Support:

    • Lightweight components will deliver mouse wheel events to their first ancestor with a MouseWheelListener.
    • MouseWheelListeners may be added to any JComponent for custom event handling.
    • javax.swing.JScrollPane is modified to properly scroll its viewed component. Like java.awt.ScrollPane, this may be disabled using setWheelScrollingEnabled.

  • New API:

    In addition to the new class and new interface previously mentioned, there are some other changes to the API to support the mouse wheel.

    • Change to java.awt.AWTEvent:
          public final static long MOUSE_WHEEL_EVENT_MASK;
    • Changes to java.awt.AWTEventMulticaster:
          public void mouseWheelMoved(MouseWheelEvent e)

    public static MouseWheelListener add(MouseWheelListener a, MouseWheelListener b)

    public static MouseWheelListener remove(MouseWheelListener l, MouseWheelListener oldl)
    • Changes to java.awt.Component:
          public synchronized void addMouseWheelListener(MouseWheelListener l)

    public synchronized void removeMouseWheelListener(MouseWheelListener l)
    • Changes to java.awt.ScrollPane:
          public void setWheelScrollingEnabled(boolean handleWheel)

    public boolean isWheelScrollingEnabled()
    • Change to java.awt.Robot:
          public synchronized void mouseWheel(int wheelAmt)
  • Linux Mouse Wheel Support:

    For Linux to recognize your mouse wheel, two modifications to the /etc/X11/XF86Config file are required. Under the "Pointer" section:

    • Add the line:

          ZAxisMapping 4 5

    • Change the protocol to: "imps/2" (this will vary depending on your particular wheel mouse).

Programmatic Zooming of Frames

The bugtraq report that corresponds to this change is: 4071554.

Previously there was no way to zoom (or maximize) a Frame programmatically. This feature has been added to this release.

The new interface java.awt.event.WindowStateListener is introduced.

Changes to java.awt.Frame:

    public static final int MAXIMIZED_HORIZ;

    public static final int MAXIMIZED_VERT;

    public static final int MAXIMIZED_BOTH;

    public synchronized void setMaximizedBounds(Rectangle bounds)

    public Rectangle getMaximizedBounds()

    public synchronized void setExtendedState(int state)

    public synchronized int getExtendedState()

Changes to java.awt.event.WindowEvent:

    public static final int WINDOW_STATE_CHANGED;

    public WindowEvent(Window source, int id, Window opposite, int oldState, int newState)

    public WindowEvent(Window source, int id, int oldState, int newState)

    public int getOldState()

    public int getNewState()

Changes to java.awt.AWTEvent:

    public final static long WINDOW_STATE_EVENT_MASK;

Changes to java.awt.Toolkit:

    public boolean isFrameStateSupported(int state) throws HeadlessException

Changes to java.awt.Window:

    public synchronized void addWindowStateListener(WindowStateListener l)

    public synchronized void removeWindowStateListener(WindowStateListener l)

    public synchronized WindowStateListener[] getWindowStateListeners()

    protected void processWindowStateEvent(WindowEvent e)

Change to java.awt.event.WindowAdapter:

    public void windowStateChanged(WindowEvent e)

Changes to java.awt.AWTEventMulticaster:

    public static WindowStateListener add(WindowStateListener a, WindowStateListener b)

    public static WindowStateListener remove(WindowStateListener l, WindowStateListener oldl)

Dynamic Layout During Resize

The bugtraq report that corresponds to this change is: 4077991.

Previously, dynamic window resizing wasn't supported on all platforms. For example, on Windows NT, with solid resize on, resizing a window recalculated the layout only when the drag was finished. This has been fixed in this release with the addition of the new desktop property awt.dynamicLayoutSupported. When dynamic layout is enabled, a Container continually lays out its components as it resizes. If disabled, the layout will be validated after resizing has finished.

API changes to java.awt.Toolkit.

    public void setDynamicLayout(boolean dynamic)

    protected boolean isDynamicLayoutSet()

    public boolean isDynamicLayoutActive()

Access to Component Listener Lists

The bugtraq report that corresponds to this change is: 4290704.

Previously all of the state in an AWT component that could be written could also be read. For example, there are no write-only properties in the component API. Event listeners were a notable exception. AWT event listeners are managed according to the JavaBeansTM conventions with a pair of methods: addXXXListener and removeXXXListener for a listener that implements the XXXEventListener interface.

No access was provided to the listener lists themselves. The fields that contain the listener lists are package private and no method was provided that returns the contents of a listener list. This has caused some problems for Swing and other AWT clients.

To mitigate the problem in the Java 2 SDK, v1.3 release, we added a getListeners method to Component and to the Swing classes that defined listener lists. The getListeners method uses a class to specify a particular listener list. For example to get all of the listeners added with addFocusListener, one would write: getListeners(FocusListener.class).

This particular approach to exposing listener lists was taken to minimize the overall change to the AWT/Swing public API. It was not intended to be a convention for all JavaBeans and it did not handle PropertyChangeListeners - which can be added to a single property, as in addPropertyChangeListener("myProperty", myListener). For this release, we have designed a more complete solution to accessing event listeners. The two conceptual changes are:

  • The addition of a getFooListeners method to the add/remove convention in AWT and Swing classes.
  • Support for PropertyChangeListeners and VetoableChangeListeners, including those which listen to a single property, using the new java.util.EventListenerProxy class.

There is a new java.awt.event.AWTEventListenerProxy class.

API Changes to java.awt.Toolkit:

    public PropertyChangeListener[] getPropertyChangeListeners()

    public synchronized PropertyChangeListener[] getPropertyChangeListeners(String propertyName)

    public AWTEventListener[] getAWTEventListeners()

    public AWTEventListener[] getAWTEventListeners(long eventMask)

Changes to Drag and Drop

The bugtraq reports that corresponds to this change are: 4407057 and 4426750.

In the Solaris and Linux releases of Java 2 Standard Edition, SDK 1.3, several of the AWT heavyweight Components exhibited default drag behavior via the middle mouse button, even if the application did not identify these Components as DragSources via the java.awt.dnd API. These Components were implemented using Motif peers, and Motif provides middle button drag behavior for these peers by default.

Because of the design of the AWT, and because of bugs in the Motif library, this default behavior has been the source of numerous stability problems. Rather than continue to risk the stability of AWT and Drag & Drop for a niche feature, we have chosen to disable this feature explicitly in our implementations.

Developers can still identify these Components as DragSources in their applications using the java.awt.dnd API. This is both functional and supported. This approach is superior to relying upon default Motif behavior in any case, because it enables drag support for these Components on all platforms, not just Solaris and Linux.

64-Bit Compliance on Solaris Machines

The bugtraq report that corresponds to this change is: 4295833.

64-bit Solaris applications use 64 bits to address memory instead of 32. This allows larger applications by providing a much larger virtual memory space. For this release, AWT has been brought up to 64-bit compliance. For more information, see here.

Inconsistent DLLs Warning

The bugtraq report that corresponds to this change is: 4414004.

If you have installed English VC++ 6.0 onto a machine that also has Asian Windows NT installed, you may encounter strange artifacts when rendering Asian text in the TextArea component. You may also see this problem if you have installed Microsoft Exchange or Microsoft Office 97 onto a machine running Asian Windows NT 4.0. Although this problem was reported on the Japanese version of Windows NT, it will probably occur on other non-Latin versions of NT as well, such as Chinese or Korean.

The problem was caused when the installation of those programs replaced the Asian Riched32.dll with the English version. The problem can be corrected by replacing Riched32.dll with the Asian version.

Removal of the Drawing Surface API

The bugtraq report that corresponds to this change is: 4293646.

The sun.awt.DrawingSurface API has been removed. It was never made public, but some developers have been using it. The functionality has been replaced by the JAWT. For more information, see the AWT Native Interface description.

Window Centering API Required for Multiscreen Support

The bugtraq report that corresponds to this change is: 4463949.

Xinerama-aware applications running on multi-headed systems have caused problems which have resulted in a variety of bug reports. Some multi-headed environments use monitors with little or no borders, which can be butted up against one another such that the resulting effect is one mammoth display. In this case, a "properly" centered window may span multiple screens. Other multi-headed environments use regular CRT monitors, with several inches of packaging between the actual display areas. In this case, a window spanning multiple screens produces a disconcerting effect, especially if the window cannot be dragged onto one monitor or the other (the Solaris login screen, for example). In short there was no way to tell where to center a window in a Xinerama environment.

To address this problem, the X group has added API which allows Xinerama users to specify where they want "centered" windows to be centered, and allows developers of Xinerama-aware applications to code accordingly.

Prior to this release, the way to center a window has been to center it within the bounds of the default GraphicsDevice, like this:

    bounds = getDefaultScreenDevice().getDefaultConfiguration().getBounds();
    frame.setLocation(bounds / 2 - size of window / 2);
This code would center the windows "correctly" on Xinerama systems where windows should be centered to the entire Xinerama coordinate space.

As of this release, post 4356756-fix JDKs will center windows "correctly" on Xinerama systems where windows should be centered within the first display.

To accomplish this, the getCenterPoint method has been added to GraphicsEnvironment .

This method works as follows on various platforms:

  • Microsoft Windows/Macintosh:
    These platforms include all monitors in a single virtual coordinate space. However, there is one "primary" display (on Microsoft Windows the primary display contains the task bar, on the Mac, the menubar). Here, getCenterPoint returns the coordinates of the center of the primary display.

  • X-Window, non-Xinerama
    Each display has its own coordinate system; the upper-left corner of every display is 0.0. Again, there is a "first" display. Here, getCenterPoint returns the center point of the primary display.

  • X-Window, Xinerama
    All monitors share a single virtual coordinate space, as on Microsoft Windows. However, it is possible for the user to specify through X resources where windows should be centered. If these resources are set, getCenterPoint reflects their value. Otherwise, it returns the point at the center of the virtual coordinate space. (In practice, this will almost always be set - CDE sets it by default.)

As of JDK 1.4, the correct code for centering is:

    frame.setLocation(getCenterPoint() - size of window / 2);

The other method added to GraphicsEnvironment is getMaximumWindowBounds. Both getCenterPoint and getMaximumWindowBounds throw a HeadlessException when in Headless mode.

New InputEvent Key Modifiers

The bugtraq reports that corresponds to this change are: 4387938 and 4421515.

Previously, the InputEvent modifiers had the same values for keyboard and mouse buttons. In certain situations there was no way to distinguish which one was pressed or when more than one was held simultaneously. These situations included cases when more than one mouse button was down at the same time, or when a modifier key was used to modify a mouse event.

To address this deficiency, the following constants were added to InputEvent:

  • SHIFT_DOWN_MASK
  • CTRL_DOWN_MASK
  • META_DOWN_MASK
  • ALT_DOWN_MASK
  • ALT_GRAPH_DOWN_MASK
  • BUTTON1_DOWN_MASK
  • BUTTON2_DOWN_MASK
  • BUTTON3_DOWN_MASK

The following methods were added to InputEvent:

  • getModifiersEx
  • getModifiersExText

The class spec for MouseEvent was updated. The following constants were also added to MouseEvent:

  • NOBUTTON
  • BUTTON1
  • BUTTON2
  • BUTTON3

These methods in MouseEvent were added:

  • MouseEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger, int button)
  • getButton
  • getMouseModifiersText

DragSourceDragEvent has the new method getGestureModifiersEx.

Change in Drop Down Behavior for Choice Menus

The bugtraq report that corresponds to this change is: 4462677.

The Choice drop down menu behavior has changed from JDK 1.3.1 to 1.4. In 1.3.1, you could click anywhere on the choice bar and the menu would drop down. In 1.4, you must click on the arrow selector on the right hand side of the Choice bar. Clicking anywhere else on the Choice bar has no effect. Also, the symbol on the Choice bar has changed from a bar to an arrow/bar combination. Finally, if the drop down menu extends outside of the parent, when clicking on that area, the application underneath is brought to the foreground. This happens on Solaris, not Windows.

Choice Component Now Obeys Layout Manager Constraints

The bugtraq report that corresponds to this change is: 4288285.

In releases prior to 1.4, the AWT Choice widget sometimes ignored the size that the layout manager told it to be. As of this release, it now obeys the layout manager constraints.

Deprecated Focus Methods

The bugtraq report that corresponds to this change is: 4476300.

The new focus subsystem, introduced in this release, introduced a new architecture and a new terminology for handling keyboard focus in sophisticated AWT and Swing applications. Prior to this project, many of the focus-related APIs were inconsistent in usage and termonology, were improperly documented, and led to poorly designed UIs. Now that the new architecture is in place, the most egregious of these APIs has been deprecated.

The following constants and methods have been deprecated:

  • javax.swing.FocusManager.FOCUS_MANAGER_CLASS_PROPERTY
  • javax.swing.FocusManager.disableSwingFocusManager()
  • javax.swing.FocusManager.isFocusManagerEnabled()
  • javax.swing.JComponent.requestDefaultFocus()
  • javax.swing.JComponent.isManagingFocus()
  • javax.swing.JComponent.setNextFocusableComponent(Component)
  • javax.swing.JComponent.getNextFocusableComponent()
  • java.awt.Component.isFocusTraversable()
  • java.awt.Component.hasFocus()
  • javax.swing.SwingUtilities.findFocusOwner(Component)
ActionEvents (and Other Events) Need Timestamps

The bugtraq report that corresponds to this change is: 4434193.

The new focus architecture includes a type-ahead mechanism that ensures that subsequent KeyEvents that follow a KeyEvent that initiates a focus transfer are not delivered until the transfer is completed. The design for this feature is based on the UTC timestamps of the various events. Events with timestamps later than that of the initiating event are enqueued pending resolution of the transfer; events with earlier timestamps are not.

To implement this feature, the focus code keeps track of the timestamp of the event currently being handled. If a focus change is initiated during this handling, the timestamp is available for use. However, if the current event does not have a timestamp, then the current system time is used. This time is usually too far ahead of the time that the event actually occurred to be of any real use. As a result, the type-ahead mechanism fails, and KeyEvents are delivered before the focus transfer is completed.

The most common case where we encountered this problem was with ActionEvents. ActionEvents are high-level, semantic events generated in response to underlying InputEvents. While the InputEvents had timestamps associated with them, the ActionEvents did not. The ActionEvent API has therefore been expanded to accomodate a timestamp and the implementation has been updated so that an ActionEvent's timestamp is equal to that of its underlying InputEvent.

The following methods have been added to ActionEvent:

  • ActionEvent(Object source, int id, String command, long when, int modifiers)
  • getWhen

The following ActionEvent methods were modified:

  • ActionEvent(Object source, int id, String command)
  • ActionEvent(Object source, int id, String command, int modifiers)

The getWhen method was added to InvocationEvent.

The InvocationEvent constructors InvocationEvent(Object, Runnable) and InvocationEvent(Object, Runnable, Object, boolean) were modified.

A new constructor InputMethodEvent(Component, int, long, AttributedCharacterIterator, int, TextHitInfo, TextHitInfo) was added to InputMethodEvent, as well as the getWhen method.

The following InputMethodEvent constructors have been modified:

  • InputMethodEvent(Component, int, AttributedCharacterIterator, int, TextHitInfo, TextHitInfo)
  • InputMethodEvent(Component, int, TextHitInfo, TextHitInfo).

Finally, the following methods were added to EventQueue:

  • getMostRecentEventTime
  • getCurrentEvent

Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: java-awt@java.sun.com 		Sun


AWT Native Interface

The AWT Native Interface

The Key to Rendering to an AWT Canvas from Native Code

The new JavaTM 2 AWT Native Interface enables rendering libraries compiled to native code to draw directly to a Java Canvas drawing surface. This means that such libraries can be used without being converted to Java first and without significant impact on performance. An example illustrating how easy it is to use the AWT Native Interface is presented and discussed in this technical note.

Introduction

The definition of Java 2 Platform, Standard Edition includes JNI, the Java Native Interface. Most Java developers will never need to use it, but the interface is invaluable in certain situations because it provides the only way for Java byte code to interact directly with application code that has been compiled to the native machine instructions for the host microprocessor. JNI is most often used as an ``escape valve'' to enable access to platform functionality not yet supported by the Java programming language. For example, you could use JNI to integrate with native code that communicates with a peripheral device, such as a scanner, connected to a system via a USB port.

Of course, JNI is general enough to be used to access almost any sort of native library, regardless of whether the task to be accomplished could also be done using pure Java. The major penalty for using it is that code portability suffers, but this may be acceptable or even necessary for business or technical reasons.

Business reasons? Consider the situation where the legacy software you're trying to port to Java uses a third-party library for a critical set of operations. If you don't have source rights to this library and you can't convince the owner to provide a Java version, you may not be able to use it. Even if you do have the source, the effort needed to port a standard library to Java and test it may be too expensive to consider.

Another important reason for leaving the native code alone is related to performance. If you're dealing with a finely crafted piece of code, carefully tuned for performance over the course of years, you probably do not want to convert it to Java and risk a performance penalty. It's usually best to keep it intact until you're satisfied that the benefits of Java portability and code maintainability outweigh the expected performance difference.

A rendering library is a good example of a piece of native code that most developers would just as soon leave alone for performance reasons. Unfortunately, this is the very type of library that has been most difficult to integrate with Java code through JNI. The fundamental problem has been that the rendering code doesn't know where to draw! It needs access to information about a Java drawing surface (such as a handle to the underlying peer of a Canvas), but can't get it.

Until now, the Java platform has kept access to this information private -- ``private'' in the sense of undocumented, unsupported, and deprecated. The good news is that this situation will be remedied with the introduction of the ``AWT Native Interface'' in the Java 2 upgrade release (``Kestrel'') expected in early 2000. For the first time there will be an official way to obtain all the information you need to know about the peer of a Java Canvas so that you can draw directly to the Canvas from a native code library using the drawing routines provided by the operating system.

How It Works

In this section we'll describe the most common usage of the AWT Native Interface -- overriding the paint method to direct drawing operations to a native rendering library which then queries the Java VM to determine the information it needs in order to render. Note, however, that any native code may use the AWT Native Interface to learn about a target drawing surface, not just code in a paint method.

The first step in hooking up a native rendering library to a Java Canvas is to define a new class that extends Canvas and overrides the paint method. The Java system routes all drawing operations for a Canvas object through the paint method, as it does for all other GUI objects.

The new paint method, to be implemented in the native rendering library, must be declared as public native void , and the native library itself is loaded at runtime by including a call to System.loadLibrary( "myRenderingLib") in the static block of the class. ``myRenderingLib'' is the name we're using for the native shared library; for the Solaris operating environment, the actual name for the library file on disk is libmyRenderingLib.so .

Here's a simple example of such a class:

import java.awt.*;
import java.awt.event.*;

public class MyCanvas extends Canvas {
    static {
        System.loadLibrary("myRenderingLib");
    }
    public native void paint(Graphics g);

    public static void main(String[] args) {
        Frame f = new Frame();
        f.setBounds(0, 0, 500, 110);
        f.add( new MyCanvas() );
        f.addWindowListener( new WindowAdapter() {
            public void windowClosing(WindowEvent ev) {
                System.exit(0);
            }
        } );
        f.show();
    }
}

Note that this class has a main method that can be used torun this code as an application for testing purposes.

The next step is to run the javah tool on the MyCanvas class file above to generate a C/C++ header file that describes the interface to the native paint method that Java expects to be used. javah is a standard tool included with the Java 2 SDK.

The final step the most interesting one is to write the native rendering method, with an interface that conforms to the header file that javah generated, and build it as a standard shared library (called myRenderingLib in the above example) by linking it, for the Solaris operating environment, against the jre/lib/sparc/libjawt.so library. (For Microsoft Windows, link against the jre/bin/jawt.dll library.) This code will call back to the Java virtual machine to get the drawing surface information it needs to access the MyCanvas peer. Once this information is available, the code can draw directly to MyCanvas using standard drawing routines supplied by the underlying operating system.

Here is sample source code for a native paint method designed for use in a Solaris X11-based drawing environment and a Java VM where the AWT Native Interface is present:

/*
 * Copyright 1999 Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 */

#include "MyCanvas.h"
#include "jawt_md.h"

/*
 * Class:     MyCanvas
 * Method:    paint
 * Signature: (Ljava/awt/Graphics;)V
 */
JNIEXPORT void JNICALL Java_MyCanvas_paint
(JNIEnv* env, jobject canvas, jobject graphics)
{
    JAWT awt;
    JAWT_DrawingSurface* ds;
    JAWT_DrawingSurfaceInfo* dsi;
    JAWT_X11DrawingSurfaceInfo* dsi_x11;
    jboolean result;
    jint lock;
    GC gc;

    short	i;
    char	*testString = "^^^ rendered from native code ^^^";

    /* Get the AWT */
    awt.version = JAWT_VERSION_1_3;
    if (JAWT_GetAWT(env, &awt) == JNI_FALSE) {
        printf("AWT Not found\n");
        return;
    }

    /* Get the drawing surface */
    ds = awt.GetDrawingSurface(env, canvas);
    if (ds == NULL) {
        printf("NULL drawing surface\n");
        return;
    }

    /* Lock the drawing surface */
    lock = ds->Lock(ds);
    if((lock & JAWT_LOCK_ERROR) != 0) {
        printf("Error locking surface\n");
        awt.FreeDrawingSurface(ds);
        return;
    }

    /* Get the drawing surface info */
    dsi = ds->GetDrawingSurfaceInfo(ds);
    if (dsi == NULL) {
        printf("Error getting surface info\n");
        ds->Unlock(ds);
        awt.FreeDrawingSurface(ds);
        return;
    }

    /* Get the platform-specific drawing info */
    dsi_x11 = (JAWT_X11DrawingSurfaceInfo*)dsi->platformInfo;

    /* Now paint */
    gc = XCreateGC(dsi_x11->display, dsi_x11->drawable, 0, 0);
    XSetBackground(dsi_x11->display, gc, 0);
    for (i=0; i<36;i++) {="{" XSetForeground(dsi_x11-="XSetForeground(dsi_x11-">display, gc, 10*i);
       XFillRectangle(dsi_x11->display, dsi_x11->drawable, gc,
                       10*i, 5, 90, 90);
    }
    XSetForeground(dsi_x11->display, gc, 155);
    XDrawImageString(dsi_x11->display, dsi_x11->drawable, gc,
                100, 110, testString, strlen(testString));
    XFreeGC(dsi_x11->display, gc);

    /* Free the drawing surface info */
    ds->FreeDrawingSurfaceInfo(dsi);

    /* Unlock the drawing surface */
    ds->Unlock(ds);

    /* Free the drawing surface */
    awt.FreeDrawingSurface(ds);
}

The key data structure here is JAWT , which is defined in jawt.h (included by jawt_md.h) ; it provides access to all the information the native code needs to get the job done. The first part of the native method is boilerplate: it populates the JAWT structure, gets a JAWT_DrawingSurface structure, locks the surface (only one drawing engine at a time, please!), then gets a JAWT_DrawingSurfaceInfo structure that contains a pointer (in the platformInfo field) to the necessary platform-specific drawing information. It also includes the bounding rectangle of the drawing surface and the current clipping region.

The structure of the information pointed to by platformInfo is defined in a machine-dependent header file called jawt_md.h. For Solaris/X11 drawing, it includes information about the X11 display and X11 drawable associated with MyCanvas. After the drawing operations are completed, there is more boilerplate code as JAWT_DrawingSurfaceInfo is freed and JAWT_DrawingSurface is unlocked and freed.

The corresponding code for the Microsoft Windows platform would be structured similarly, but would include the version of jawt_md.h for Microsoft Windows and the structure located in the platformInfo field of drawing surface info would be cast as a JAWT_Win32DrawingSurfaceInfo* . And, of course, the actual drawing operations would need to be changed to those appropriate for the Microsoft Windows platform.

Summary

The ability to draw directly into a Java Canvas from a native code library is extremely useful for developers planning to migrate a legacy software system to Java, especially one that includes a high-performance rendering engine. It makes it much easier to migrate in stages, leaving performance-sensitive rendering code alone, while other less-sensitive portions of code are converted to Java. The result can be a modern Java-centric application, providing the benefit of portability and development efficiency, but one that does not sacrifice an investment in performance of a key piece of native code.

References

The definitive reference to the Java Native Interface is The Java Native Interface: Programmer's Guide and Specification by Sheng Liang of Sun Microsystems. This book was published in June 1999 by Addison-Wesley. The ISBN is 0-201-32577-2.

Appendix

Header Files for jawt.h and jawt_md.h

jawt.h

/*
 * @(#)jawt.h	1.2 99/05/27
 *
 * Copyright 1999 by Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Sun Microsystems, Inc. ("Confidential Information").  You
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with Sun.
 */

#ifndef _JAVASOFT_JAWT_H_
#define _JAVASOFT_JAWT_H_

#include "jni.h"

#ifdef __cplusplus
extern "C" {
#endif

/*
 * AWT native interface (new in JDK 1.3)
 *
 * The AWT native interface allows a native C or C++ application a means
 * by which to access native structures in AWT.  This is to facilitate moving
 * legacy C and C++ applications to Java and to target the needs of the
 * community who, at present, wish to do their own native rendering to canvases
 * for performance reasons.  Standard extensions such as Java3D also require a
 * means to access the underlying native data structures of AWT.
 *
 * There may be future extensions to this API depending on demand.
 *
 * A VM does not have to implement this API in order to pass the JCK.
 * It is recommended, however, that this API is implemented on VMs that support
 * standard extensions, such as Java3D.
 *
 * Since this is a native API, any program which uses it cannot be considered
 * 100% pure java.
 */

/*
 * AWT Native Drawing Surface (JAWT_DrawingSurface).
 *
 * For each platform, there is a native drawing surface structure.  This
 * platform-specific structure can be found in jawt_md.h.  It is recommended
 * that additional platforms follow the same model.  It is also recommended
 * that VMs on Microsoft Windows platforms and Solaris operating environment
 * support the existing structures in jawt_md.h.
 *
 *******************
 * EXAMPLE OF USAGE:
 *******************
 *
 * In Miscrosoft Windows, a programmer wishes to access the HWND of a canvas
 * to perform native rendering into it.  The programmer has declared the
 * paint() method for their canvas subclass to be native:
 *
 *
 * MyCanvas.java:
 *
 * import java.awt.*;
 *
 * public class MyCanvas extends Canvas {
 *
 *     static {
 *         System.loadLibrary("mylib");
 *     }
 *
 *     public native void paint(Graphics g);
 * }
 *
 *
 * myfile.c:
 *
 * #include "jawt_md.h"
 * #include
 *
 * JNIEXPORT void JNICALL
 * Java_MyCanvas_paint(JNIEnv* env, jobject canvas, jobject graphics)
 * {
 *     JAWT awt;
 *     JAWT_DrawingSurface* ds;
 *     JAWT_DrawingSurfaceInfo* dsi;
 *     JAWT_Win32DrawingSurfaceInfo* dsi_win;
 *     jboolean result;
 *     jint lock;
 *
 *     // Get the AWT
 *     awt.version = JAWT_VERSION_1_3;
 *     result = JAWT_GetAWT(env, &awt);
 *     assert(result != JNI_FALSE);
 *
 *     // Get the drawing surface
 *     ds = awt.GetDrawingSurface(env, canvas);
 *     assert(ds != NULL);
 *
 *     // Lock the drawing surface
 *     lock = ds->Lock(ds);
 *     assert((lock & JAWT_LOCK_ERROR) == 0);
 *
 *     // Get the drawing surface info
 *     dsi = ds->GetDrawingSurfaceInfo(ds);
 *
 *     // Get the platform-specific drawing info
 *     dsi_win = (JAWT_Win32DrawingSurfaceInfo*)dsi->platformInfo;
 *
 *     //////////////////////////////
 *     // !!! DO PAINTING HERE !!! //
 *     //////////////////////////////
 *
 *     // Free the drawing surface info
 *     ds->FreeDrawingSurfaceInfo(dsi);
 *
 *     // Unlock the drawing surface
 *     ds->Unlock(ds);
 *
 *     // Free the drawing surface
 *     awt.FreeDrawingSurface(ds);
 * }
 *
 */

/*
 * JAWT_Rectangle
 * Structure for a native rectangle.
 */
typedef struct jawt_Rectangle {
    jint x;
    jint y;
    jint width;
    jint height;
} JAWT_Rectangle;

struct jawt_DrawingSurface;

/*
 * JAWT_DrawingSurfaceInfo
 * Structure for containing the underlying drawing information of a component.
 */
typedef struct jawt_DrawingSurfaceInfo {
    /*
     * Pointer to the platform-specific information.  This can be safely
     * cast to a JAWT_Win32DrawingSurfaceInfo on Microsoft Windows or a
     * JAWT_X11DrawingSurfaceInfo on Solaris operating environment.
     * See jawt_md.h for details.
     */
    void* platformInfo;
    /* Cached pointer to the underlying drawing surface */
    struct jawt_DrawingSurface* ds;
    /* Bounding rectangle of the drawing surface */
    JAWT_Rectangle bounds;
    /* Number of rectangles in the clip */
    jint clipSize;
    /* Clip rectangle array */
    JAWT_Rectangle* clip;
} JAWT_DrawingSurfaceInfo;

#define JAWT_LOCK_ERROR                 0x00000001
#define JAWT_LOCK_CLIP_CHANGED          0x00000002
#define JAWT_LOCK_BOUNDS_CHANGED        0x00000004
#define JAWT_LOCK_SURFACE_CHANGED       0x00000008

/*
 * JAWT_DrawingSurface
 * Structure for containing the underlying drawing information of a component.
 * All operations on a JAWT_DrawingSurface MUST be performed from the same
 * thread as the call to GetDrawingSurface.
 */
typedef struct jawt_DrawingSurface {
    /* Cached reference to the Java environment of the calling thread */
    JNIEnv* env;
    /* Cached reference to the target object */
    jobject target;
    /*
     * Lock the surface of the target component for native rendering.
     * When finished drawing, the surface must be unlocked with
     * Unlock().  This function returns a bitmask with one or more of the
     * following values:
     *
     * JAWT_LOCK_ERROR - When an error has occurred and the surface could not
     * be locked.
     *
     * JAWT_LOCK_CLIP_CHANGED - When the clip region has changed.
     *
     * JAWT_LOCK_BOUNDS_CHANGED - When the bounds of the surface have changed.
     *
     * JAWT_LOCK_SURFACE_CHANGED - When the surface itself has changed
     */
    jint (JNICALL *Lock)
        (struct jawt_DrawingSurface* ds);
    /*
     * Get the drawing surface info.
     * The value returned may be cached, but the values may change if
     * additional calls to Lock() or Unlock() are made.
     * Lock() must be called before this can return a valid value.
     * Returns NULL if an error has occurred.
     * When finished with the returned value, FreeDrawingSurfaceInfo must be
     * called.
     */
    JAWT_DrawingSurfaceInfo* (JNICALL *GetDrawingSurfaceInfo)
        (struct jawt_DrawingSurface* ds);
    /*
     * Free the drawing surface info.
     */
    void (JNICALL *FreeDrawingSurfaceInfo)
        (JAWT_DrawingSurfaceInfo* dsi);
    /*
     * Unlock the drawing surface of the target component for native rendering.
     */
    void (JNICALL *Unlock)
        (struct jawt_DrawingSurface* ds);
} JAWT_DrawingSurface;

/*
 * JAWT
 * Structure for containing native AWT functions.
 */
typedef struct jawt {
    /*
     * Version of this structure.  This must always be set before
     * calling JAWT_GetAWT()
     */
    jint version;
    /*
     * Return a drawing surface from a target jobject.  This value
     * may be cached.
     * Returns NULL if an error has occurred.
     * Target must be a java.awt.Canvas.
     * FreeDrawingSurface() must be called when finished with the
     * returned JAWT_DrawingSurface.
     */
    JAWT_DrawingSurface* (JNICALL *GetDrawingSurface)
        (JNIEnv* env, jobject target);
    /*
     * Free the drawing surface allocated in GetDrawingSurface.
     */
    void (JNICALL *FreeDrawingSurface)
        (JAWT_DrawingSurface* ds);
} JAWT;

/*
 * Get the AWT native structure.  This function returns JNI_FALSE if
 * an error occurs.
 */
_JNI_IMPORT_OR_EXPORT_
jboolean JNICALL JAWT_GetAWT(JNIEnv* env, JAWT* awt);

#define JAWT_VERSION_1_3 0x00010003

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* !_JAVASOFT_JAWT_H_ */

jawt_md.h (Solaris/X11 operating environment version)

/*
 * @(#)jawt_md.h	1.2 99/05/27
 *
 * Copyright 1999 by Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Sun Microsystems, Inc. ("Confidential Information").  You
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with Sun.
 */

#ifndef _JAVASOFT_JAWT_MD_H_
#define _JAVASOFT_JAWT_MD_H_

#include
#include
#include
#include "jawt.h"

#ifdef __cplusplus
extern "C" {
#endif

/*
 * X11-specific declarations for AWT native interface.
 * See notes in jawt.h for an example of use.
 */
typedef struct jawt_X11DrawingSurfaceInfo {
    Drawable drawable;
    Display* display;
    VisualID visualID;
    Colormap colormapID;
    int depth;
} JAWT_X11DrawingSurfaceInfo;

#ifdef __cplusplus
}
#endif

#endif /* !_JAVASOFT_JAWT_MD_H_ */

jawt_md.h (Microsoft Windows version)

/*
 * @(#)jawt_md.h	1.2 99/05/27
 *
 * Copyright 1999 by Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Sun Microsystems, Inc. ("Confidential Information").  You
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with Sun.
 */

#ifndef _JAVASOFT_JAWT_MD_H_
#define _JAVASOFT_JAWT_MD_H_

#include
#include "jawt.h"

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Microsoft Windows specific declarations for AWT native interface.
 * See notes in jawt.h for an example of use.
 */
typedef struct jawt_Win32DrawingSurfaceInfo {
    /* Native window, DDB, or DIB handle */
    union {
        HWND hwnd;
        HBITMAP hbitmap;
        void* pbits;
    };
    /*
     * This HDC should always be used instead of the HDC returned from
     * BeginPaint() or any calls to GetDC().
     */
    HDC hdc;
    HPALETTE hpalette;
} JAWT_Win32DrawingSurfaceInfo;

#ifdef __cplusplus
}
#endif

#endif /* !_JAVASOFT_JAWT_MD_H_ */

Copyright © 1999 Sun Microsystems, Inc. All Rights Reserved.

 Sun


AWT Packages

 Documentation Contents
  • java.awt - Contains all of the classes for creating user interfaces and for painting graphics and images.
  • java.awt.event - Provides interfaces and classes for dealing with different types of events fired by AWT components.

The following packages are located within the AWT package, and are used to support Drag and Drop:

  • java.awt.datatransfer - Provides interfaces and classes for transferring data between and within applications.
  • java.awt.dnd - Drag and drop is a direct manipulation gesture, found in many Graphical User Interface systems, that provides a mechanism to transfer information between two entities logically associated with presentation elements in the GUI.

The following packages are located within the AWT package, but are actually part of Java 2D:

  • java.awt.color
  • java.awt.font
  • java.awt.geom
  • java.awt.image
  • java.awt.image.renderable
  • java.awt.print

The following packages are located within the AWT package, but are actually part of the Input Method Framework:

  • java.awt.im
  • java.awt.im.spi


AWT Enhancements

Java

AWT Enhancements in the JavaTM 2 Platform Standard Edition 5.0

 Documentation Contents
Major Changes
Window Bugfixes and Enhancements
DnD and Data Transfer Bugfixes and Enhancements
Layout Bugfixes
Miscellaneous Bugfixes
Known Bugs and Issues

Major Changes

4615479: XToolkit on Solaris and Linux

In this release, AWT has been reimplemented on the Solaris and Linux platforms. It is possible to force the Motif toolkit on Linux or XAWT on Solaris. This is done either by setting the AWT_TOOLKIT variable or using the -Dawt.toolkit command line parameter. The value for XAWT is sun.awt.X11.XToolkit and the value for Motif is sun.awt.motif.MToolkit. For more information, see the XToolkit on Solaris/Linux note.

4638443: XDnD Support

As of this release, the XDnD Protocol support has been implemented as part of the data transfer system. Prior to this release, only the Motif DnD protocol was supported on X11.

4009555: Obtaining the mouse location on the desktop

API has been added to obtain the mouse location on the desktop. The new PointerInfo class describes the pointer coordinates and the associated GraphicsDevice object at the moment the PointerInfo instance is created. PointerInfo has the following methods:
  • GraphicsDevice getDevice()
  • Point getLocation()

The new MouseInfo class has information about the current location of the mouse pointer. MouseInfo has two methods:

  • PointerInfo getPointerInfo()
  • int getNumberOfButtons

Other new methods:

    java.awt.Component.getMousePosition()
    java.awt.Container.getMousePosition(boolean)
    java.awt.Toolkit.getMouseInfoPeer

Window Bugfixes and Enhancements

4632143: Window, Frame or Dialog Always on Top

New API has been added to ensure that a particular Window, Frame or Dialog is always on top of the desktop. This is useful when implementing certain GUI elements, such as tool boxes, notification or information applets, and other desktop-enhancing features. The new and modified API includes:
  • isAlwaysOnTop()
  • setAlwaysOnTop(boolean)
  • addPropertyChangeListener(PropertyChangeListener)
  • addPropertyChangeListener(String, PropertyChangeListener)
    The addXXX methods have been modified to support setting a property change listener on the window's alwaysOnTop state.
  • java.awt.Permission
    The new setWindowAlwaysOnTop permission has been added.

Depending on the system setup, always-on-top Windows, Frames or Dialogs may not be supported. They are supported on Microsoft Windows, Linux and Solaris running GNOME2/Metacity, as well as Linux running KDE/kwin. They are not supported on Solaris running CDE/dtwm. It is possible that always-on-top windows do not work on Linux or Solaris running session and window managers other than those mentioned above.

4102292: New API to Specify Default Window Location by Platform

Two new methods and one new property allow the user to specify the default location for a new Window, appropriate to the platform. This is especially important for X11. The new api includes:
  • Window.setLocationByPlatform(boolean)
  • Window.isLocationByPlatform
  • Window.isLocationByPlatform (a property)
Note that the locationByPlatform property must be set to true for the underlying window manager to tile the window according to its own logic. Otherwise, AWT won't know whether the window was put at 0,0 intentionally or was just unspecified and the window will be placed at the upper-left-hand corner of the screen.

4101435: Window/Dialog/Frame.setLocation doesn't always work as expected

The location and size of Windows, Dialogs and Frames, is under the control of the desktop's window management system, not the application or the toolkit. The window manager is free to ignore or modify a window placement request. Therefore, when calling Window.setLocation(x, y), you can't rely on the Window being moved to location (x, y). The same situation exists for Window.setSize and Window.setBounds. The Window documentation has been clarified to explain this.

4401846: New _JAVA_AWT_WM_STATIC_GRAVITY Environment Variable

Certain window managers position AWT windows incorrectly. For example, a window that is requested to be moved to (0,0) will, under some window managers, be positioned so that the window's title and left border are off-screen. This is because there are two schools of window managers that disagree on the interpretation of the ICCCM specification for the ConfigureRequest requests that X11 programs make to position their windows.

To address this issue, the _JAVA_AWT_VM_STATIC_GRAVITY environment variable has been added so that a power user can indicate that his window manager implements the StaticGravity behavior.

DnD and Data Transfer Bugfixes and Enhancements

4378091: New DropTarget.getTransferable method

The new java.awt.dnd.DropTargetDragEvent.getTransferable method enables the drop target to access transfer data during a drag operation.

This also fixes bug 4248542: DropTargetListener can't access the transferable in dragOver and dragEnter.

4259272: Notification of Clipboard contents changes is now supported

Previously, the Java clipboard API didn't allow an efficient way to track changes to the set of DataFlavors available on the clipboard or notify interested parties about those changes. API has been added for this purpose:
  • addFlavorListener(FlavorListener)
  • removeFlavorListener(FlavorListener)
  • getFlavorListeners()

4287795: New methods for querying information in a Clipboard

Three new methods have been added:
  • DataFlavor[] getAvailableDataFlavors() returns the DataFlavors currently available on the clipboard.
  • boolean isDataFlavorAvailable(DataFlavor) returns true if the specified data flavor is available.
  • Object getData(DataFlavor) returns the data in the specified data flavor.

4790833: Memory Usage No Longer Shoots Up using Clipboard.getContents

Prior to this release, Clipboard.getContents fetched clipboard data in all provided formats for which a mapping to the corresponding data flavor in the default flavor map exists. If there were a lot of formats and the data were large, a lot of memory was consumed with the fetched data in different formats. Thanks to the new methods introduced with bug fix 4287795, this problem has been fixed.

4415175: New API to Globally Change the DnD Gesture Motion Threshold

The drag motion gesture threshold represents the number of pixels the cursor is dragged before the data transfer system initiates a drag operation. Prior to this release, this was hard-coded to 5 pixels. As of release 5.0, there is support for picking up the desktop properties for drag sensitivity and mapping it to the threshold, and new API that allows users to get and change this threshold. The new API includes:
  • java.awt.dnd.DragSource.getDragThreshold()
  • java.awt.dnd.drag.threshold (a property)
  • java.awt.dnd.MouseDragGestureRecognizer (updated class spec)

4712068: DnD Usability Issue for Dragging Text

Prior to this release, the hotspot of the drop icons used on X platforms was located at the middle of the icon. When dragging text, the text cursor moves to indicate the current drop location, but this was obscurbed by the drop icon itself. For this release, the drop cursors used on X platforms have been changed to point to the upper-left corner of the drop icon. The corresponding hotspots have been changed accordingly.

4191708: Clarification in spec for several java.awt.dnd.DropTarget methods

The doc has been clarified with respect to passing in a null parameter for the following java.awt.dnd.DropTarget methods:
  • dragEnter(DropTargetDragEvent)
  • dragOver(DropTargetDragEvent)
  • dropActionChanged(DropTargetDragEvent)
  • drop(DropTargetDropEvent)
  • dragExit(DropTargetEvent)

4819437: DragSourceListener.dragExit is now called in a consistent way

The class specification for the DragSourceAdapter and DragSourceAdapter classes, and the documentation for the DragSourceAdapter.dragExit and DragSourceListener.dragExit methods have been updated to clarify the notion that the drop site is associated with the previous call to dragEnter.

4654688: SystemFlavorMap Methods Now Consistent with Documentation

The SystemFlavorMap class is used to store mappings between native formats and Java data flavors in order to support data transfer between native and Java applications. The documentation for the SystemFlavorMap.getNativesForFlavor(DataFlavor) method has been clarified to say that a DataFlavor (or a native format) is known if and only if it has at least one static mapping associated with it.

4123385: Documentation Clarification for Drag Source Events Constructors Constructors

The documentation has been clarified with respect to passing in invalid parameters for the following constructors of drag source events:
  • DragSourceDragEvent(DragSourceContext, int int, int)
  • DragSourceDragEvent(DragSourceContext, int int, int, int, int)
  • DragSourceDropEvent(DragSourceContext)
  • DragSourceDropEvent(DragSourceContext, int, boolean)
  • DragSourceDropEvent(DragSourceContext, int, boolean, int, int)

Layout Bugfixes

GridBagLayout Bugfixes

GridBagLayout: Several bugfixes have been implemented for GridBagLayout. Note that two of these bugs listed apply to the documentation only. The most significant bugfixes include:

4254022: More than 512 horizontal or vertical components are now possible in a GridBagLayout

Previously, GridBagLayout had been implemented with a hard-coded width and height limit of 512. This is now allocated dynamically and the MAXGRIDSIZE constant is no longer used.

4532201: GridBagLayout.lookupConstraints doc is clarified

Documentation was added to clarify what happens when the specified Component is not in the grid bag layout.

4618355: Doc for GridBagLayout.gridwidth/gridheight is clarified

The class spec for GridBagLayout.gridwidth/gridheight was confusing in its description of REMAINDER and RELATIVE. This has been corrected.

FlowLayout Bugfixes

FlowLayout: Several documentation bugs have been fixed for FlowLayout

4586806: FlowLayout spec is corrected regarding alignment

Previously, the class spec stated that components are centered on the line. Actually, the align property determines how the components are laid out. The doc has been corrected.

4881919: FlowLayout class spec no longer implies that components are always left to right

The FlowLayout class spec was written before the ability to go right to left was added. Therefore it assumed that left to right was the only possible orientation. The doc has been corrected.

4587456: Corrected spec for FlowLayout constructor

Previously, the doc for the FlowLayout constructor neglected to mention that the hgap and vap were applied to the spacing between the components and the container border as well as between the components. The documentation has been corrected.

4172932: New methods to get constraints for children in BorderLayout

Three public methods have been added to BorderLayout, one to get the constraints for a component, and two different ways to get the component for a given constraint (one takes component orientation into account and the other doesn't). The new methods are:
  • Component getLayoutComponent(Object)
  • Component getLayoutComponent(Container, Object)
  • Object getConstraints(Component)

4515041: Clarified spec for GridLayout.layoutContainer regarding vgap and hgap params

Previously, the spec for layoutContainer stated that the vgap and hgap was added between each cell and between the first/last cell and the border. In reality, the gaps are applied between the components only. This has been corrected in the doc.

Miscellaneous Bugfixes

4533021: New API to Change the Z-ordering of Children

New API has been added to specify the z-ordering of children in a Container. The two new Container methods include:
  • getComponentZOrder(Component, int)
  • setComponentZOrder(Component, int)

4370733: AWTKeyStroke.getAWTKeyStroke(String) and toString are now symmetric

Previously it was not possible to take the output from AWTKeyStroke.toString and pass it to the getAWTKeyStroke method. This has been changed so the methods

4341785: Clarify spec for several List methods

The spec for the following List methods has been clarified to state that unspecified behavior results when the range is out of bounds:
  • deselect(int)
  • setMultipleMode(boolean)
  • select(int)

4368570: Clarify List spec regarding behavior of clicking on a selected item

Previously, the class spec for List stated that clicking on an unselected item selects it and clicking on a selected item de-selects it. This is true only if the list is in multiple-selection mode. In single-selection mode, any click on a list's item selects the clicked item. The spec has been clarified.

4082708: Clarified spec for the ContainerEvent.getContainer method

The ContainerEvent.getContainer method assumes that source is of type Container. Previously, it casted the source to type Container without first checking which could result in ClassCastException. The method has been changed to return a value of null if the source isn't a Container.

4620715: New KeyEvent codes for two standard Microsoft Windows keys.

Two keys on a standard Microsoft Windows keyboard don't have Java keycodes — the windows key and the context menu key. This impedes the ability to meet 508 requirements. Therefore, the java.awt.event.KeyEvent.VK_WINDOWS and java.awt.event.KeyEvent.VK_CONTEXT_MENU keycodes have been added.

4829063: Scrollbar now specifies that Scrollbar thumb may not be visible

Previously, the doc for Scrollbar.getVisibleAmount and setVisibleAmount did not say that sometimes the thumb might not be visible or accurately describe what the scrollbar's range is used for. The specification has been cleaned up. This is a doc-only change.

4840172: Behavior of KeyEvent.getKeyChar is clarified

Use of KeyEvent.getKeyChar is explained in the KeyEvent class documentation, but the doc for the method itself was brief. The doc for getKeyChar has been improved for this release.

4233061: Clarify spec that ENTER doesn't fire an ActionEvent

There is confusion among some developers that when the focus is on a Button, pressing the ENTER key doesn't fire an ActionEvent. This is correct behavior. The SPACE bar fires an ActionEvent. The ActionEvent class specification was updated to clarify this fact.

4221123: New FileDialog constructors

Three new FileDialog constructors have been added that can specify a Dialog as the owner:
  • FileDialog(Dialog)
  • FileDialog(Dialog, String)
  • FileDialog(Dialog, String, int)

4691481: Updated spec for Robot.createScreenCapture

Previously, the documentation for Robot.createScreenCapture didn't mention that the mouse cursor is not included in the captured image. This has always been true of Solaris, Linux, Windows and Mac OS X. The documentation has been updated to reflect this information.

4704042: New method for setting Insets

A single method to set Insets has been added: set(int, int, int, int).

4492739: Clarify InputEvent.ALT_MASK/BUTTON2_MASK and META_MASK/BUTTON3_MASK doc

There is an overlap in the values for some of the InputEvent constants. This is confusing because when calling KeyEvent.getModifiersExText(int) and MouseEvent.getMouseEventModifiersText(int) the string returned for KeyEvent.BUTTON2_MASK is "Alt" and the string returned for KeyEvent.BUTTON3_MASK is "Meta". For this release, documentation was added to the InputEvent, KeyEvent and MouseEvent classes to clarify this.

Known Bugs and Issues
Here is a list of known problems you may encounter in release 5.0.

Metacity versioning

We recommend using the latest build of Metacity (which is currently 2.6.2). There were some bugs that occurred with versions prior to 2.4.34 (problems with programmatic iconification, and non-resizable frames, for example) that have since been fixed.

5051557: Applet focus incompatibility

We have received reports that, in some applets, pressing a key on the keyboard doesn't have the expected result. This usually happens because the applet doesn't get the focus automatically when there are no child components in the applet. To ensure that such an applet works across all platforms, it is recommended that you request the focus at startup (via requestFocus) and on mouse press. If you don't want the focus, call setFocusable(false).

5050387: JVM may crash when JOptionPane is invoked from drop()

On Solaris/Linus running MToolKit, displaying a JOptionpane from the drop method may cause the JVM to crash. This bug will be addressed in a future release.

Focus bugs when running applets

There were focus-related bugs noticeable when running applets in Mozilla in release 1.4.2 and earlier. This includes:
  • 4907493: Input focus not working with multiple applets
  • 4902616: The characters of a text field can't delete when doing Java Plug-in test
  • 4877530: Unable to input text into JTextField in 1.4.1_02
  • 4806274: The requestFocus method doesn't bring focus to the component on Netscape 7 on Solaris
  • 4816394: Can't input anything to SpreadSheet
  • 4837794: Can't input charact to login AnswerCenter with Java applet
  • 4902609: Tab key can't work when doing Java test case
To solve this problem, the client side of the XEmbed protocol was implemented:
  • 4849238: Add XEmbed support to AWT
  • 4907325: XEmbed should be implemented for the Motif toolkit
However, the browser should support the server side of XEmbed in order for it to work. We recommend using the following browsers with Java:
  • On Linux, Mozilla community edition at least version 1.5 or higher.
  • On Solaris, Sun Mozilla at least version 1.4 or higher.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: java-awt@java.sun.com 		Sun


XToolkit on Solaris/Linux

Starting with release J2SETM 5.0, AWT has been re-implemented on the Solaris and Linux platforms. The new Toolkit implementation provides the following advantages:
  • Removes the dependency on Motif and Xt libraries.
  • Interoperates better with other GUI Toolkits.
  • Provides better performance and quality.

The new Toolkit (XToolkit) is the default on Linux in J2SE 5.0. Solaris will continue to use the MToolkit (Motif-based Toolkit) as the default in J2SE 5.0, but eventually will be replaced with XToolkit.

Explicitly Setting the Toolkit

You can explicitly set the toolkit for an applet or application using an environment variable or a system property. Keep in mind that the environment variable overrides the system property.

  • Setting the toolkit for an application:

    • Using an environment variable. This needs to be set before starting the VM.
       csh:
 setenv AWT_TOOLKIT XToolkit #selects the XToolkit
 setenv AWT_TOOLKIT MToolkit #selects the MToolkit

 ksh/bash:
 export AWT_TOOLKIT=XToolkit
 export AWT_TOOLKIT=MToolkit

    • Using a system property on the command line:
       java -Dawt.toolkit=sun.awt.X11.XToolkit MyApp
 java -Dawt.toolkit=sun.awt.motif.MToolkit MyApp
  • Setting the toolkit for an applet:

    • Using an environment variable.

      If the browser is started from a terminal window, the environment variable must be set in the terminal window before launching the browser. If the browser is launched from a desktop icon or menu, the toolkit for an applet can't be set using an environment variable. The Java Plug-in Control Panel should be used instead.

    • Using the Plug-in Control Panel:

      • Launch the Java Plug-in Control Panel:
        $java_home/bin/ControlPanel

      • Add the system property to the Java Runtime Parameters field under the Advanced tab.
        -Dawt.toolkit=sun.awt.X11.XToolkit
-Dawt.toolkit=sun.awt.motif.MToolkit


Focus API changes

This document outlines the API changes that have been done to AWT and Swing to accomodate the new focus model. For a general overview of the changes, you may want to first read this.

Modifications to existing classes:

  • java.awt.AWTEvent
  • java.awt.Component
  • java.awt.Container
  • java.awt.Window
  • java.awt.Frame
  • java.awt.Dialog
  • java.awt.FocusEvent
  • java.awt.event.WindowEvent
  • java.awt.event.WindowListener
  • java.awt.event.WindowAdapter
  • java.awt.AWTEventMulticaster
  • javax.swing.FocusManager
  • javax.swing.DefaultFocusManager
  • javax.swing.JComponent
  • javax.swing.JWindow
  • javax.swing.JInternalFrame
  • javax.swing.KeyStroke
  • javax.swing.SwingUtilities

New classes:

  • java.awt.KeyboardFocusManager
  • java.awt.KeyEventDispatcher
  • java.awt.DefaultKeyboardFocusManager
  • java.awt.FocusTraversalPolicy
  • java.awt.ContainerOrderFocusTraversalPolicy
  • java.awt.DefaultFocusTraversalPolicy
  • java.awt.AWTKeyStroke
  • java.awt.event.WindowFocusListener
  • javax.swing.SortingFocusTraversalPolicy
  • javax.swing.LayoutFocusTraversalPolicy
  • javax.swing.InternalFrameFocusTraversalPolicy

Add the following to java.awt.AWTEvent:

    public void setSource(Object newSource)

Changes to java.awt.Component:

    public boolean isFocusTraversable()

    public boolean isFocusable()

    public void setFocusable(boolean focusable)

    public void setFocusTraversalKeys(int id, Set keystroke)

    public Set getFocusTraversalKeys(int id)

    public void setFocusTraversalKeysEnabled(boolean focusTraversalKeysEnabled)

    public boolean getFocusTraversalKeysEnabled()

    public void requestFocus()

    protected boolean requestFocus(boolean temporary)

    public boolean requestFocusInWindow()

    protected boolean requestFocusInWindow(boolean temporary)

    public void transferFocus()

    public void transferFocusBackward()

    public void transferFocusUpCycle()

    public Container getFocusCycleRootAncestor()

    public boolean isFocusCycleRoot(Container container)

    public boolean hasFocus()

    public boolean isFocusOwner()

    public void addPropertyChangeListener(PropertyChangeListener listener)

    public void removePropertyChangeListener(PropertyChangeListener listener)

    public void addPropertyChangeListener(String propertyName, PropertyChangeListener listener)

    public void removePropertyChangeListener(String propertyName, PropertyChangeListener listener)

    public void firePropertyChange(String propertyName, boolean oldValue, boolean newValue)

    public void firePropertyChange(String propertyName, int oldValue, int newValue)

    public boolean isFontSet()

    public boolean isBackgroundSet()

    public boolean isForegroundSet()

    public boolean isCursorSet()

    public boolean areFocusTraversalKeysSet(int id)

Changes to java.awt.Container:

    public void setFocusTraversalKeys(int id, Set keystroke)

    public Set getFocusTraversalKeys(int id)

    public void setFocusTraversalPolicy(FocusTraversalPolicy policy)

    public FocusTraversalPolicy getFocusTraversalPolicy()

    public void setFocusCycleRoot(boolean focusCycleRoot)

    public boolean isFocusCycleRoot()

    public boolean isFocusCycleRoot(Container container)

    public void transferFocusDownCycle()

    public void addPropertyChangeListener(PropertyChangeListener listener)

    public void addPropertyChangeListener(String propertyName, PropertyChangeListener listener)

    public boolean areFocusTraversalKeysSet(int id)

    public boolean isFocusTraversalPolicySet()

Changes to java.awt.Window:

    public void toFront()

    public void toBack()

    public Component getFocusOwner()

    public Component getMostRecentFocusOwner()

    public boolean isActive()

    public boolean isFocused()

    public final void setFocusCycleRoot(boolean focusCycleRoot)

    public final boolean isFocusCycleRoot()

    public final Container getFocusCycleRootAncestor()

    public boolean isFocusableWindow()

    public void setFocusableWindowState(boolean focusableWindowState)

    public void addPropertyChangeListener(PropertyChangeListener listener)

    public void addPropertyChangeListener(String propertyName, PropertyChangeListener listener)

Add the following to the javadoc of java.awt.Frame:

/**
 * Frames are capable of generating the following types of WindowEvents:
 * WindowOpened, WindowClosing, WindowClosed, WindowIconified,
 * WindowDeiconified, WindowActivated, WindowDeactivated, WindowGainedFocus,
 * WindowLostFocus.
 */

Add the following to the javadoc of java.awt.Dialog:

/**
 * Dialogs are capable of generating the following WindowEvents:
 * WindowOpened, WindowClosing, WindowClosed, WindowActivated,
 * WindowDeactivated, WindowGainedFocus, WindowLostFocus.
 */

Add the following to java.awt.event.FocusEvent:

    public FocusEvent(Component source, int id, boolean temporary, Component opposite)

    public Component getOppositeComponent()

Add the following to the javadoc of java.awt.event.WindowEvent:

/**
 * A low-level event that indicates that a window has changed its status. This
 * low-level event is generated by a Window object when it is opened, closed,
 * activated, deactivated, iconified, or deiconified, or when focus is
 * transfered into or out of the Window.
 */

Add the following to java.awt.event.WindowEvent:

    public static final int WINDOW_ACTIVATED

    public static final int WINDOW_DEACTIVATED

    public static final int WINDOW_GAINED_FOCUS

    public static final int WINDOW_LOST_FOCUS

    public WindowEvent(Window source, int id, Window opposite)

    public Window getOppositeWindow()

Add the following to java.awt.event.WindowListener:

    public void windowActivated(WindowEvent e)

    public void windowDeactivated(WindowEvent e)

Add the following to java.awt.event.WindowAdapter:

    public void windowGainedFocus(WindowEvent e)

    public void windowLostFocus(WindowEvent e)

Add the following to java.awt.AWTEventMulticaster:

    public void windowGainedFocus(WindowEvent e)

    public void windowLostFocus(WindowEvent e)

Modifications to javax.swing.FocusManager

This class has been obsoleted. New applications should use java.awt.KeyboardFocusManager exclusively. Nevertheless, we have preserved backward compatibility for existing applications (but not applets) which define their own FocusManager.

The Swing FocusManager has been changed to be a subclass of the new, AWT KeyboardFocusManager. FocusManager.setCurrentManager(FocusManager) and FocusManager.getCurrentManager() have been changed to wrappers around KeyboardFocusManager.setCurrentKeyboardFocusManager(KeyboardFocusManager) and KeyboardFocusManager.getCurrentKeyboardFocusManager(), respectively.

There was much discussion over these changes because KeyboardFocusManager.setCurrentKeyboardFocusManager(KeyboardFocusManager) will throw a SecurityException if the calling thread was not granted the "replaceKeyboardFocusManager" permission. Previously, FocusManager.setCurrentManager(FocusManager) would never throw a SecurityException. Although we were able to design a convoluted class organization which avoided this problem, we felt that the elegance and simplicity of the proposed design outweighed the rather small backward compatibility concern.

disableSwingFocusManager() and isFocusManagerEnabled() should not be used. Disabling the Swing FocusManager now has the semantics of reverting the default FocusTraversalPolicy from the Swing default of javax.swing.LayoutFocusTraversalPolicy to the AWT default of java.awt.DefaultFocusTraversalPolicy.

Modifications to javax.swing.DefaultFocusManager

This class has been obsoleted. New applications should use java.awt.KeyboardFocusManager exclusively. Nevertheless, we have preserved backward compatibility for existing applications (but not applets) which define their own DefaultFocusManager.

If client code installs a legacy DefaultFocusManager, we provide backward compatibility by installing a non-public LegacyGlueFocusTraversalPolicy which routes FocusTraversalPolicy method invocations to the corresponding methods on DefaultFocusManager.

Modifications to javax.swing.JComponent

isManagingFocus: This method has been obsoleted. It changed a JComponent's focus traversal keys from TAB and SHIFT-TAB to CTRL-TAB and CTRL-SHIFT-TAB. It also marked the JComponent in such a way that focus traversal would not automatically enter the JComponent. This was similar to, but different from, marking a JComponent as a focus cycle root. Its functionality is superseded by the FocusTraversalPolicy class, per-Component focus traversal keys, and the ability to disable a Component's focus traversal keys en masse.

setNextFocusableComponent/getNextFocusableComponents: These methods have been obsoleted FocusTraversalPolicies are more reliable because they allow an algorithmic expression of focus traversal. These methods force applications to hard-code focus traversal Component by Component.

The spec for setRequestFocusEnabled/isRequestFocusEnabled has changed, such that the requestFocusEnabled property is now a hint to the current look and feel.

requestDefaultFocus: This method has been obsoleted. Its functionality is superseded by FocusTraversalPolicy.getDefaultComponent(Container).requestFocus().

Modifications to javax.swing.JWindow

setFocusableWindow/isFocusableWindow: These methods are declared final in JWindow to enforce the restriction that all JWindows constructed with a 'null' owner must be non-focusable. This restriction is necessary because Swing constructs such JWindows so that they are owned by a private, hidden Frame, and the new focus implementation requires that KeyEvents intended for a Window or its descendants be proxied through that Frame. Since X11 requires a window to be mapped in order to be focused, a JWindow with a 'null' owner could never receive KeyEvents on X11.

Modifications to javax.swing.JInternalFrame

getMostRecentFocusOwner: Like java.awt.Window, JInternalFrame has a getFocusOwner() method left over from before centralization of focus management in java.awt.KeyboardFocusManager. To round out the API, and to remain consistent with Window, getMostRecentFocusOwner() has been added to JInternalFrame with the same specification as the corresponding method on Window.

setFocusCycleRoot/isFocusCycleRoot: These methods give JInternalFrames similar semantics to top-level Windows in AWT. Since a JInternalFrame must always be a focus cycle root, these methods are overridden and declared final to enforce that restriction. However, unlike an AWT Window, a JInternalFrame can have a focus-cycle-root ancestor, such as a JDesktopPane. Thus, Component.getFocusCycleRootAncestor() is not declared final in JInternalFrame as it is in Window.

Modifications to javax.swing.KeyStroke

Because the existing KeyStroke class was useful for designing per-Component focus traversal key APIs, this class was promoted with minor modifications to AWT as java.awt.AWTKeyStroke. The Swing class is now a subclass of the AWT class.

The one deprecated method in KeyStroke, getKeyStroke(char, boolean), was not promoted to AWT. Because of this, there is no simple way for this method to participate in the standard AWTKeyStroke caching scheme. The specification of this method has been changed to note that implementations need not cache the instances returned by this method.

Modifications to javax.swing.SwingUtilities

findFocusOwner: This method has been obsoleted. Its functionality is superseded by KeyboardFocusManager.getFocusOwner().


JavaBeans

Java

JavaBeansTM Component API

 Documentation Contents
The JavaBeans component API extends the Java platform's Write Once, Run AnywhereTM capability to reusable component development. In fact, the JavaBeans architecture takes interoperability a major step forward — your code runs on every OS and also within any application environment. A developer who creates components based on the JavaBeans architecture (beans) secures a future in the emerging network software market without losing customers that use proprietary platforms, because beans interoperate with ActiveX, OpenDoc, and LiveConnect. Long-term persistence for JavaBeans enables you to read and write a bean as a textual representation of its property values.

API Specification

  • API Reference
  • BeanContext Specification ( PDF | PS)
    Extensible Runtime Containment and Services Protocol for JavaBeans
  • JavaBeans Specification (PDF and PS)

Tutorials and Programmer's Guides

  • JavaBeans Tutorial
  • ActiveX Bridge Developer Guide

API Enhancements

  • API Enhancements in J2SE 5.0
  • API Enhancements in v1.4

More Information

  • The JavaBeans Home Page

Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: java-beans@java.sun.com 		Sun
Java Software


JavaBeans API

Java

JavaBeansTM API

 Documentation Contents
  • java.beans - Contains classes related to developing beans — components based on the JavaBeans architecture.
  • java.beans.beancontext - Provides classes and interfaces relating to bean context.


JavaBeans API Enhancements in J2SE 5.0

Java

API Enhancements to the JavaBeansTM Component API in J2SE 5.0

 JavaBeansTM Component API
This document describes changes to the java.beans package that were introduced in version 5.0 of the JavaTM 2 Platform Standard Edition:
  • Support for IndexedPropertyChangeEvent
  • New Method for Creating a PropertyEditor
  • Public Constructors for PropertyEditorSupport

Support for IndexedPropertyChangeEvent

The bugtraq report that corresponds to this change is: 4353056

A new subclass of PropertyChangeEvent named IndexedPropertyChangeEvent has been added to support bound properties that use an index to identify the part of the bean that changed. Also, three methods — all named fireIndexedPropertyChange — have been added to the PropertyChangeSupport utility class to support firing indexed property change events. You can find an example of using indexed property change events in IndexedTest.java.

New Method for Creating a PropertyEditor

The bugtraq report that corresponds to this change is: 4274639

A new method called createPropertyEditor has been added to the PropertyDescriptor class.

Public Constructors for PropertyEditorSupport

The bugtraq report that corresponds to this change is: 4305280

The two PropertyEditorSupport constructors are now public instead of protected, so that PropertyEditorSupport objects can be more easily created and used as delegates. Also, the source object is now exposed by means of new setSource and getSource methods.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


V1.4 JavaBeans API Enhancements

Java

API Enhancements to the JavaBeansTM Component API in v1.4

 JavaBeansTM Component API
This document describes changes to the java.beans package that were introduced in version 1.4 of the Java 2 Platform, Standard Edition:
  • New API for Long-Term Persistence
  • Other API Additions
  • Changes to the Introspector
  • Garbage Collection and Custom Attributes

New API for Long-Term Persistence

To support long-term persistence, the following classes were added:

Class | Description
Statement | An object that represents a method call, possibly with arguments, upon an object. For example: a.setFoo(b).
Expression | A statement that returns a result. For example: a.getFoo().
XMLDecoder | Reads XML documents that were created using XMLEncoder.
Encoder | Uses persistence delegates to break an object graph down into a series of Statements and Expressions that can be used to recreate it.
XMLEncoder | An Encoder that produces statements and expressions in an XML encoding.
PersistenceDelegate | An abstract class that defines objects that can express the state of another object using the public methods of that object's class.
DefaultPersistenceDelegate | The persistence delegate used, by default, for beans.

See JavaBeans Component API for links to where you can find more information about long-term persistence.

Other API Additions

The following classes were also added in v1.4:

Class | Description
EventHandler | Provides support for dynamically generating event listeners that have a small footprint and can be saved automatically by the persistence scheme.
ExceptionListener | Defines a listener to be notified when a exception was thrown but then recovered from. You can register an exception listener on an XMLEncoder or XMLDecoder object to be notified when the object encounters a recoverable problem while writing or reading a bean.
PropertyChangeListenerProxy | A proxy that implements PropertyChangeListener and serves to group another PropertyChangeListener (the real event handler) with a specific property; the proxy forwards property change events to the real event handler.
VetoableChangeListenerProxy | A proxy that implements VetoableChangeListener and serves to group another VetoableChangeListener (the real event handler) with a specific constrained property; the proxy forwards vetoable property change events to the real event handler.

The following classes have additional methods:

  • The PropertyChangeSupport class now contains a no-argument method to get all the registered property change listeners: getPropertyChangeListeners.
  • Similarly, the VetoableChangeSupport class now contains a no-argument method to get all the registered vetoable change listeners: getVetoableChangeListeners.

Changes to the Introspector

The Introspector class has been reimplemented, and its performance has improved. The new implementation has caused the following changes in the behavior of the introspector:
  • FeatureDescriptors are now shared on a per-BeanInfo basis, rather than copied when the BeanInfo is returned. This change improves the performance of the getBeanInfo method. It also means that when an attribute/value in a FeatureDescriptor changes, that change is persistent among getBeanInfo invocations as long as the BeanInfo is not garbage collected. (Garbage collection of BeanInfos is described in Garbage Collection and Custom Attributes.)

  • The getBeanInfo methods no longer create a copy of the requested BeanInfo. Instead, they cache the BeanInfo and return it. If necessary, you can get the old behavior by storing a reference to the returned BeanInfo and using the flushFromCaches method to flush the bean's class from the introspector's cache.

  • If the instantiate method can't instantiate a particular class using the sibling or bootstrap class loader, it now tries to load the class using the current thread's class loader.

Garbage Collection and Custom Attributes

As of v 1.4, a BeanInfo can be garbage collected when no direct references to it exist and the system is low on memory. This is implemented in the Introspector by wrapping BeanInfos in SoftReferences.

The possibility of garbage collection affects how you store custom attributes inside BeanInfos. If a particular BeanInfo is garbage collected, then the next time you invoke Introspector.getBeanInfo to get the BeanInfo, the returned object won't contain any custom attributes.

To avoid this problem, if you store custom attributes inside a BeanInfo you must ensure that the BeanInfo is correctly initialized with those attributes every time you retrieve the BeanInfo. The following is an example of initializing a BeanInfo class with a custom property in the bean descriptor. The code would be similar for a custom attribute in a property descriptor, method descriptor, or event set descriptor.

BeanInfo beanInfo = getBeanInfo(SomeBean.class);
BeanDescriptor beanDescriptor = beanInfo.getBeanDescriptor();

/*
 * Before using the BeanInfo, check to see if our custom
 * property has been initialized.  (Even if we initialized
 * it before, if the BeanInfo has been garbage collected,
 * then we need to initialize it again.)  Since our custom
 * property's value could be null, we define another property
 * to tell us if the custom property is initialized.
 */
if (beanDescriptor.getValue("myProperty_init") == null) {
    beanDescriptor.setValue("myProperty", someValue);
    beanDescriptor.setValue("myProperty_init", Boolean.TRUE);
}

Copyright © 2002 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


ActiveX Bridge

ActiveX Bridge Developer Guide

Implementation for SDK/JRE 1.4.2 and Above

This document includes the following topics:

  • Overview
  • Supported OSs and ActiveX Containers
  • Packaging the Bean
  • Using the Bean in an Application
  • Deployment
  • Java Objects in the ActiveX Bridge Environment
  • Other Topics
    • Methods
    • Properites
    • Ambient properties
    • Events
    • Security
    • JVM Configuration

The Example Applications chapter describes two example applications.

Overview

The ActiveX Bridge allow a component based on JavaBeans(TM) component architecture ("bean") to be effectively packaged as an ActiveX control, thereby allowing it to be used as a functional component in an ActiveX container.

Note that this implementation of the ActiveX Bridge may not be compatible with the previous implementation for SDK/JRE 1.1 through 1.3.1. In order to use the new bridge, beans will need to be repackaged.

Supported OSs and ActiveX Containers

For development purposes, this implementation supports the following OSs and ActiveX Containers:

OSs: Windows NT, 2000, XP.

ActiveX Containers: Visual Studio 6.0 with SP3.

Note that packaged beans should run on any Windows platform and in any ActiveX container—not just those platforms and containers listed above.

Packaging the Bean

Notes

1. Running the packager (packager.exe) requires that you have the following installed on your computer:

  • SDK 1.4.2 or higher
  • Microsoft Visual C++ 6.0 with SP3

2. In order for packager to work you must first run VCVARS32.BAT. cd to the /bin directory where it is located in your Microsoft Visual C++ installation and type VCVARS32.

Use packager.exe to generated the .dll for the bean.

Use of packager.exe is as follows:

Packager Usage

Usage: packager [-options] <jar file name> <bean name>

where options include:
   -clsid <class-id>         CLSID for the packaged bean
   -out <output directory>   destination directory for the packaged bean
   -reg                      consent to register the Active-X control

Additional Information

  • A .dll can contain only one packaged bean. Thus, a separate .jar file is required for each bean.
  • If one .jar file depends on another .jar file or .class file(s), then you will need to set CLASSPATH.
  • <jar file name> needs to include the path to the .jar file. The path may be full or relative.
  • <bean name> needs to be the fully qualified package name of the bean (e.g., sunw.demo.jelly.JellyBean.).
  • If the -clsid option is not used, the packaged bean CLSID will be generated randomly. This -clsid option allows you to specify the same CLSID for a given bean every time.
  • Default: Unless -out is specified, packager.exe will generate the .dll fill in the same directory in which it is executed. If you specify the -out parameter, then packager places the .dll file in the directory you specify. For example, you might want to place the .dll in a directory called <jre_home>\axbridge\bin where it could be deployed with an application. (Note that <jre_home> would be the public JRE, not the private one. The public JRE on Windows is normally located at C:\Program Files\Java\j2re1.4.2. The private JRE, associated with the SDK, is normally located at C:\j2sdk1.4.2\jre.)
  • If -out is not specified, or -out does not specify <jre_home>\axbridge\bin, then the -reg option should not be used.

Example

For example, suppose <bean>.jar is jelly.jar; jelly.jar is located at C:\my_bean_jars; the fully qualified bean name is sunw.demo.jelly.JellyBean; and the SDK is j2sdk1.4.2. You could run packager.exe as follows:

C:\j2sdk1.4.2\bin\packager -clsid {D824B185-AE3C-11D6-ABF5-00B0D07B8581} -out C:\Program Files\Java\j2re1.4.2\axbridge\bin -reg C:\my_bean_jars\jelly.jar sunw.demo.jelly.JellyBean

The packager would:

  • generate a .dll file with the bean name (JellyBean.dll) and put it in the j2re\axbridge\bin directory;
  • create a j2re1.4.2\axbridge\lib directory and place jelly.jar there;
  • register the bean .dll with the CLSID D824B185-AE3C-11D6-ABF5-00B0D07B8581.

Manually Registering the bean .dll

If you don't use the -reg option with packager.exe as shown above, you can manually register the .dll with regsvr32.exe. cd to the directory where the .dll file is located (e.g., C:\Program Files\Java\j2re1.4.2\axbridge\bin) and type:

<path_regsvr32>\regsvr32 <bean name>.dll

Suppose you are running Windows 2000. regsvr32.exe is located at C:\winnt\system32 on Windows 2000. Then to register JellyBean.dll you would do this:

C:\Program Files\Java\j2re1.4.2\axbridge\bin>C:\winnt\system32\regsvr32 JellyBean.dll

This will:

  • create a CLSID registry entry for JellyBean.dll under HKEY_CLASSES_ROOT;
  • create a j2re1.4.2\axbridge\lib directory and place jelly.jar there.

Using the Bean in an Application

Now that the bean is registered as an ActiveX control, you should be able to insert it into an ActiveX container. In the case of the ActiveX Control Test Container that comes with Visual Studio, on the main menu go to Edit>Insert New Control... and scroll down the list until you find the bean control. In the case of the JellyBean.dll control, it shows up as JellyBean Bean Control. Below it is shown inserted into the Visual Studio test container.

Deployment

To deploy a bean packaged as an ActiveX control in an application, you will need to include registration of the .dll as part of the installation process. The .dll should be installed into the <jre_home>axbridge\bin directory, and it should be registered there with regsvr32.exe. As stated previously, when the .dll is registered, the bean .jar will be placed in the <jre_home>\axbridge\lib directory.

Java Objects in the ActiveX Bridge Environment

Java objects are accessible via wrapper objects supporting the IDispatch interface; i.e., they are accessed indirectly through the ActiveX Bridge. For example, if you are working with a packaged bean in Visual Basic (VB) and want to pass a Java object as an argument to a bean method, it is necessary that either (1) the bean has a method that returns the required type of Java object; or (2) the Java object is available as a bean property.

For example, consider the calendar example, JCalendarPanel, in the Examples chapter.

If you were working directly in Java with this bean, you would create a Date object, set its properties, then pass it as an argument to the setSelectedDate() method of JCalendarePanel. The way this is done with the ActiveX Bridge as follows:

Assuming you are working in VB and have an instance of JCalendarPanel called JCalendarPanel1, in VB you could use the JCalendarPanel1.selectedDate property to get a Date object:

Set dat = JCalendarPanel1.selectedDate

Then you would use the VB methods of the Date object (dat) to set it. For instance:

dat.setYear (1986 - 1900)
dat.setMonth (11 - 1)
dat.setDate 24

Finally, you would use the setSelectedDate method of JCalendarPanel1 to set the date:

JCalendarPanel1.setSelectedDate dat

Other Considerations

Methods and Method Overloading

All the methods provided by the BeanInfo via getMethodDescriptors() are accessible from ActiveX containers.

However, if a method is overloaded, only the method which takes the highest number of arguments will be available. This is because COM IDL does not support overloading. However, the argument and return value type will be VARIANT. Each argument is optional. For any overloaded method you will need to refer to the bean documentation to know the exact number of arguments and their types. Methods or property names which are identical to any MIDL keyword are dropped.

Properties

All the properties are accessible though the bridge with the same access right as defined in the BeanInfo via PropertyDescriptor. The ActiveX bridge will invoke the accessor methods as defined in the PropertyDescriptor.

If the bean property is bound or constrained, the bindable or requestedit flags are set in the attributes of the COM property. The container is notified of the property change through IPropertyNotifySink interface. If the property is constrained and the container denies the property change, then the bean PropertyVetoException is thrown by the bridge.

For primitive types and for string, font, and color properties, most ActiveX containers like Visual Basic will allow direct manipulation of properties in their PropertySheet. For all other properties, such as arrays or objects, the properties will not be accessible in the PropertySheet but can still be invoked through the scripting language associated with the container.

Ambient Properties

The bridge will support four ambient properties that get translated to the bean properties if the bean component implements these properties. These ambient properties will be read and set on the bean component when the component is initialized and each time a change notification for the ambient properties is received.

DISPID_BACKCOLOR
DISPID_FORECOLOR
DISPID_FONT
DISPID_ENABLED

The bridge will forward ActiveX container ambient property changes to the bean via setting properties.

Events

All source interfaces that are declared as default in the EventSetDescriptor array returned by the BeanInfo will be merged into one interface which is declared as being the ActiveX default source interface. It is an ActiveX requirement that at least the default source interface is accessible by ActiveX containers.

Each method returned by the getListenerMethodDescriptors API of the EventSetDescriptor is mapped to an ActiveX event. The event name is the method name. Since all default interfaces of beans are merged to a unique interface, interfaces that contain the same method name are not allowed.

Consider, for example the java.awt.event.ActionListener source interface:

public interface ActionListener extends EventListener {

  public void actionPerformed(ActionEvent e);

}

The ActiveX event name generated from this interface definition is actionPerformed. For example, in case of Visual Basic the event signature looks like this:

Private Sub Button_actionPerformed (ByVal evt As Object)

  MsgBox evt.toString

End-Sub

The evt provided to the container is an automation object, which represents the java.awt.AWTEvent Object. Containers could access the information on the event by invoking the methods supported by the AWTEvent class.

Security

The bean packaged as an ActiveX control will be part of a stand-alone application. Hence it will be executed outside the applet sand box security model.

In Internet Explorer scripting of the bean is not safe, as it has been granted the AllPermission permission.

JVM Configuration

Note that you can configure the JVM through the Java Plug-in Control Panel. The following tabs are relevant to the ActiveX Bridge:

  • Basic
  • Advanced
  • Proxies

You can use the Java Console for debugging beans.


Example Applications

Below are two application examples:

  • Bound Properties: boundprop.exe
  • Calendar: cal.exe

Bound Properties

This application consists of an ActiveX container with two beans packaged as ActiveX controls: BoundPropTest, a JavaBeans button; and the JellyBean bean. The applications works because the button is registered as a listener with JellyBean. Every time the JellyBean is clicked, the button receives notification and code is called that changes the text on the button. The resources for this application—boundprop.exe, BoundPropTest.dll, and JellyBean.dll—can be found in the boundprop subdirectory of this document, should you care to set it up and run it.

To run the application on your computer, copy BoundPropTest.dll and JellyBean.dll to <jre_home>\axbridge\bin on your computer. Register both .dll files with regsvr32.exe. Then execute boundprop.exe. You should see the following:

Calendar

The Calendar application is similar. It consists of an ActiveX container with an ActiveX control calendar and a JavaBean calendar. In this application, both components are registered with each other as listeners. Changes in one calendar are reflected in the other via change notification. Resources for this application—cal.exe and JCalendarPanel.dll—can be found in the cal subdirectory of this document, should you care to set it up and run it. (Copy JCalendarPanel.dll to <jre_home>\axbridge\bin and register it; then execute cal.exe. You should see the following.

Sample calendar window


Extensible Runtime Containment and Server Protocol for JavaBeans Version 1.0

Extensible Runtime Containment and Server Protocol for JavaBeans

Version 1.0

Laurence Cable
Contents | Previous | Next

Extensible Runtime Containment and Server Protocol for JavaBeans Version 1.0

2.0 API Specification

3.0 Overloading java.beans.instantiate() static method

4.0 Providing better support for Beans that are also Applets

5.0 Standard/Suggested Conventions for BeanContext Services

6.0 Support classes

Contents | Previous | Next

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


Extensible Runtime Containment and Services Protocol for JavaBeans Version 1.0

Send comments to java-beans@java.sun.com.

1.0 Introduction.

Currently the JavaBeans specification (Version 1.0) contains neither conventions describing a hierarchy or logical structure of JavaBeans, nor conventions for those JavaBeans to rendezvous with, or obtain arbitrary services or facilities from, the execution environment within which the JavaBean was instantiated.

It is desirable to both provide a logical, traversable, hierarchy of JavaBeans, and further to provide a general mechanism whereby an object instantiating an arbitrary JavaBean can offer that JavaBean a variety of services, or interpose itself between the underlying system service and the JavaBean, in a conventional fashion.

In other component models there exists the concept of a relationship between a Component and its environment, or Container, wherein a newly instantiated Component is provided with a reference to its Container or Embedding Context.

The Container, or Embedding Context not only establishes the hierarchy or logical structure, but its also acts as a service provider that Components may interrogate in order to determine, and subsequently employ, the services provided by their Context.

This proposal defines such a protocol that supports extensible mechanisms that:

  • Introduce an abstraction for the environment, or context, in which a JavaBean logically functions during its lifecycle, that is a hierarchy or structure of JavaBeans.
  • Enable the dynamic addition of arbitrary services to a JavaBean’s environment.
  • Provide a single service discovery mechanism through which JavaBeans may interrogate their environment in order both to ascertain the availability of particular services and to subsequently employ those services.
  • Provide a simple mechanism to propagate an Environment to a JavaBean.
  • Provide better support for JavaBeans that are also Applets.
graphic representation of previous list points

2.0 API Specification

2.1 interface java.beans.beancontext.BeanContext

The hierarchal structure and general facilities of a BeanContext are provided for as follows:

public interface		java.beans.beancontext.BeanContext
       extends	 	java.beans.beancontext.BeanContextChild,
              java.util.Collection,
             java.beans.DesignMode,
              java.beans.Visibility {

    Object instantiateChild(String beanName)
          throws IOException, ClassNotFoundException;

    public InputStream
        getResourceAsStream(String           name,
                            BeanContextChild requestor
        );

    public java.net.URL
        getResource(String           name,
                    BeanContextChild requestor
        );

    void addBeanContextMembershipListener(
           BeanContextMembershipListener bcml
          );

    void removeBeanContextMembershipListener{
            BeanContextMembershipListener bcml
    );

    public static final Object globalHierarchyLock;
}

Notifications of changes in the membership of a BeanContext are modeled as follows:

public interface BeanContextMembershipListener
      extends   java.util.Listener {
    void childrenAdded(BeanContextMembershipEvent   bcme);
    void childrenRemoved(BeanContextMembershipEvent bcme);
}

The base class of all BeanContext related Events is defined by:

public abstract class BeanContextEvent
      extends  java.util.EventObject {
    public BeanContext getBeanContext();

    public synchronized void
        setPropagatedFrom(BeanContext bc);

    public synchronized BeanContext getPropagatedFrom();

    public synchronized boolean isPropagated()
}

The BeanContextMembershipEvent is defined as:

public class BeanContextMembershipEvent
      extends BeanContextEvent {

    public BeanContextMembershipEvent(BeanContext bc,
                                      Object[]    deltas);

    public BeanContextMembershipEvent(BeanContext bc,
                                      Collection	 deltas);

    public int size();

    public boolean contains(Object child);

    public Object[] toArray();

    public Iterator iterator();
}

2.1.1 The BeanContext as a participant in nested structure

One of the roles of the BeanContext is to introduce the notion of a hierarchical nesting or structure of BeanContext and JavaBean instances. In order to model this structure the BeanContext must expose API that defines the relationships in the structure or hierarchy.

The BeanContext exposes its superstructure through implementation of the java.beans.beancontext.BeanContextChild interface (as described later). This interface allows the discovery and manipulation of a BeanContext’s nesting BeanContext, and thus introduces a facility to create a hierarchy of BeanContexts.

The BeanContext exposes its substructure through a number of interface methods modeled by the java.util.Collection interface semantics

BeanContexts are required to implement all the mandatory Collection API’s, with the following particular semantics for add() and remove():.

The add() method may be invoked in order to nest a new Object, BeanContextChild, or BeanContext within the target BeanContext. A conformant add() implementation is required to adhere to the following semantics:

  • Synchronize on the BeanContext.globalHierarchyLock.
  • Each child object shall appear only once in the set of children for a given BeanContext. If the instance is already a member of the BeanContext then the method shall return False.
  • Each valid child shall be added to the set of children of a given source BeanContext, and thus shall appear in the set of children, obtained through either the toArray(), or iterator() methods, until such time as that child is deleted from the nesting BeanContext via an invocation of remove(), removeAll(), retainAll(), or clear()
  • As the child is added to the set of nested children, and where that child implements the java.beans.beancontext.BeanContextChild interface (or BeanContextProxy, see later for details), the BeanContext shall invoke the setBeanContext() method upon that child, with a reference to itself. Upon invocation, a child may, if it is for some reason unable or unprepared to function in that BeanContext, throw a PropertyVetoException to notify the nesting BeanContext. If the child throws such an exception the BeanContext shall revoke the addition of the child (and any other partial changes made to the state of the BeanContext as a side effect of this addition operation) to the set of nested children and throw an IllegalStateException.
  • JavaBeans that implement the java.beans.Visibility interface shall be notified via the appropriate method, either dontUseGui() or okToUseGui(), of their current ability to render GUI as defined the policy of the BeanContext.
  • If the newly added child implements BeanContextChild, the BeanContext shall register itself with the child on both its VetoableChangeListener and PropertyChangeListener interfaces to monitor, at least, that BeanContextChild’s “beanContext” property.

    • By doing so the BeanContext can monitor its child and can detect when such children are removed by a 3rd party (usually another BeanContext) invoking setBeanContext(). A BeanContext may veto such a change by a 3rd party if it determines that the child is not in a state to depart membership at that time.

  • If the JavaBean(s) added implement Listener interfaces that the BeanContext is a source for, then the BeanContext may register the newly added objects via the appropriate Listener registration methods as a permissible side effect of nesting.
  • If the JavaBean(s) added are Event Sources for Event that a particular BeanContext has interest in the BeanContext may, as a side effect of adding the child, register Listeners on that child. The BeanContext should avoid using Serializable Listeners thus avoiding accidental serialization of unwanted structure when a child serializes itself.
  • Once the targetChild has been successfully processed, the BeanContext shall fire a java.beans.beancontext.BeanContextMembershipEvent, containing a reference to the newly added targetChild, to the childrenAdded() method of all the BeanContextMemebrshipListeners currently registered.
  • The method shall return true if successful.

The remove() method may be invoked in order to remove an existing child JavaBean or BeanContext from within the target BeanContext. A conformant remove() implementation is required to adhere to the following semantics:

  • Synchronize with the BeanContext.globalHierarchyLock.
  • If a particular child is not present in the set of children for the source BeanContext, the method shall return False.
  • Remove the valid targetChild from the set of children for the source BeanContext, also removing that child from any other Listener interfaces that it was implicitly registered on, for that BeanContext as a side-effect of nesting.

    • Subsequently, if the targetChild implements the java.beans.beancontext.BeanContextChild interface (or BeanContextProxy, see later for deatils), the BeanContext shall invoke the setBeanContext() with a null1 BeanContext value, in order to notify that child that it is no longer nested within the BeanContext.

    If a particular BeanContextChild is in a state where it is not able to be un-nested from its nesting BeanContext it may throw a PropertyVetoException, upon receipt of this the BeanContext shall revoke the remove operation for this instance and throw IllegalStateException. To avoid infinite recursion, children are not permitted to repeatedly veto subsequent remove notifications. In practice, a child should attempt to resolve the condition (if temporary) that precludes it’s removal from it’s current nesting BeanContext.

  • If the targetChild implements java.beans.beancontext.BeanContextChild then the BeanContext shall de-register itself from that child’s PropertyChangeListener and VetoableChangeListener sources.
  • If the BeanContext had previously registered the object(s) removed as Listeners on events sources implemented by the BeanContext as a side effect of nesting those objects, then the BeanContext shall de-register the newly removed object from the applicable source(s) via the appropriate Listener de-registration method(s)
  • If the BeanContext had previously registered Listener(s) on the object(s) removed then the BeanContext shall remove those Listener(s) from those object(s).
  • Once the targetChild has been removed from the set of children, the BeanContext shall fire a java.beans.beancontext.BeanContextMembershipEvent, containing a reference to the targetChild just removed, to the childrenRemoved() method of all the BeanContextMembershipListeners currently registered.
  • Finally the method shall return the value true if successful.

Note that the lifetime of any child of a nesting BeanContext, is at least for the duration of that child’s containment within a given BeanContext. For simple JavaBeans that are not aware of their containment within a BeanContext, this usually implies that the JavaBean shall exist for at least the lifetime of the nesting BeanContext.

BeanContext’s are not required to implement either addAll(), removeAll(), retainAll() or clear() optional methods defined by java.util.Collection API, however if they do they must implement the semantics defined, per object, for both add() and remove() above. In the failure cases these methods shall revoke any partially applied changes to return the BeanContext to the state it was in prior to the failing composite operation being invoked, no BeanContextEvents shall be fired in the failure case as is consistent with the definition of add() and remove() above.

BeanContextMembershipListeners may be added and removed via invocations of addBeanContextMembershipListener() and removeBeanContextMembershipListener().

The toArray(), method shall return a copy of the current set of JavaBean or BeanContext instances nested within the target BeanContext, and the iterator() method shall supply a java.util.Iterator object over the same set of children.

The contains() method shall return true if the object specified is currently a child of the BeanContext.

The size() method returns the current number of children nested.

The isEmpty() method returns true if the BeanContext has no children.

Note that all the Collection methods all require proper synchronization between each other by a given implementation in order to function correctly in a multi-threaded environment, that is, to ensure that any changes to the membership of the set of JavaBeans nested within a given BeanContext are applied atomically. All implementations are required to synchronized their implementations of these methods with the BeanContext.globalHierarchyLock.

In some situations, add() and remove() (or a variant thereof) operations may occur nested, that is multiple occurrences may appear on the stack of the calling Thread simultaneously, e.g: when BeanContextChild, A, is added (or removed), it’s setBeanContext() method also adds (or removes) another BeanContextChild, B. A particular BeanContext implementation may choose to fire either two BeanContextMembershipListener notifications, one for each add()/remove() operation of B then A (in this order since B is successfully added before A), or coalesce these into a single notification containing both A, and B. Note that should A be unable to be added or removed for any reason it shall not perform, or undo, any add or remove operations upon B as a side-effect, prior to throwing a PropertyVetoException to indicate this condition, that is, it must avoid or undo any side-effect membership changes prior to rejecting any changes to its own membership status.

The instantiateChild() method is a convenience method that may be invoked to instantiate a new JavaBean instance as a child of the target BeanContext. The implementation of the JavaBean is derived from the value of the beanName actual parameter, and is defined by the java.beans.Beans.instantiate() method.

Typically, this shall be implemented by calling the appropriate java.beans.Beans.instantiate() method, using the ClassLoader of the target BeanContext. However a particular BeanContext implementation may interpose side-effects on the instantiate operation in their implementation of this method.

The BeanContextEvent is the abstract root EventObject class for all Events pertaining to changes in state of a BeanContext’s defined semantics. This abstract root class defines the BeanContext that is the source of the notification, and also introduces a mechanism to allow the propagation of BeanContextEvent subclasses through a hierarchy of BeanContexts. The setPropagatedFrom() and getPropagatedFrom() methods allows a BeanContext to identify itself as the source of a propagated Event to the BeanContext to which it subsequently propagates the Event to. This is a general propagation mechanism and should be used with care as it has significant performance implications when propagated through large hierarchies.

The BeanContextMembershipEvent describes changes that occur in the membership of a particular BeanContext instance. This event encapsulates the list of children either added to, or removed from, the membership of a particular BeanContext instance, i.e the delta in the membership set.

Whenever a successful add(), remove(), addAll(), retainAll(), removeAll(), or clear() is invoked upon a particular BeanContext instance, a BeanContextMembershipEvent is fired describing the children effected by the operation.

2.1.2 Resources.

The BeanContext defines two methods; getResourceAsStream() and getResource() which are analogous to those methods found on java.lang.ClassLoader. BeanContextChild instances nested within a BeanContext shall invoke the methods on their nesting BeanContext in preference for those on ClassLoader, to allow a BeanContext implementation to augment the semantics by interposing behavior between the child and the underlying ClassLoader semantics.

2.1.3 The BeanContext as a Service Provider

The service facilities of a BeanContext are provided as follows:

public interface BeanContextServices
      extends   BeanContext,BeanContextServicesListener {

    boolean addService(Class           serviceClass,
                       BeanContextServiceProvider service);

    boolean revokeService(Class           serviceClass,
                          BeanContextServiceProvider bcsp,
                          boolean         revokeNow
    );

    boolean hasService(Class serviceClass);

    Object getService(BeanContextChild      bcc,
                      Object                requestor.
                      Class                 serviceClass,
                      Object                serviceSelector,
                      BeanContextServicesRevokedListener sl
    ) throws TooManyListenersException;

    void releaseService(BeanContextChild bcc,
                        Object           requestor,
                        Object           service);

    Iterator getCurrentServiceClasses();

    public Iterator getCurrentServiceSelectors(Class sc);

    addBeanContextServicesListener(
        BeanContextServicesListener bcsl
    );

    removeBeanContextServicesListener(
        BeanContextServicesListener bcsl
     );
}

The BeanContextServiceProvider interface is defined as follows:

public interface BeanContextServiceProvider {
    Object getService(BeanContext bc,
                      Object      requestor,
                      Class       serviceCls,
                      Object      serviceSelector);

    void releaseService(BeanContext bc,
                        Object      requestor,
                        Object      service);

    Iterator getCurrentServiceSelectors(BeanContext bc,
                                        Class serviceCls);
}

The BeanContextServiceRevokedListener is defined as follows:

public interface BeanContextServiceRevokedListener
      extends java.util.EventListener {
    void serviceRevoked(
        BeanContextServiceRevokedEvent bcsre
    );
}

The BeanContextServicesListener is defined as follows:

public interface BeanContextServicesListener
      extends BeanContextServiceRevokedListener {
    void serviceAvailable(
        BeanContextServiceAvailableEvent bcsae
    );
}

The BeanContextServiceAvailableEvent is defined as follows:

public class BeanContextServiceAvailableEvent
      extends BeanContextEvent {

    public BeanContextServiceAvailableEvent(
            BeanContextServices        bcs,
            Class                      sc
     );

    BeanContextServices getSourceAsBeanContextServices();

    public Class getServiceClass();

    public boolean isServiceClass(Class serviceClass);

    public Iterator getCurrentServiceSelectors();
}

The BeanContextServiceRevokedEvent is defined as follows:

public class BeanContextServiceRevokedEvent
      extends BeanContextEvent {
    public BeanContextServiceRevokedEvent(
                BeanContextServices        bcs,
                Class                      sc,
                 boolean                    invalidNow
    );
    public BeanContextServices
            getSourceAsBeanContextServices();

    public Class getServiceClass();

    public boolean isServiceClass(Class service);

    public boolean isCurrentServiceInvalidNow();
}

The BeanContextServiceProviderBeanInfo is defined as follows:

public interface BeanContextServicesProviderBeanInfo
       extends   java.beans.BeanInfo {
    java.beans.BeanInfo[] getServicesBeanInfo();
}

Apart from providing a structured hierarchy, the other major role of a BeanContext is to provide a standard mechanism for a JavaBean component to obtain context-specific facilities or services from its environment.

A service, represented by a Class object, is typically a reference to either an interface, or to an implementation that is not publicly instantiable. This Class defines an interface protocol or contract between a BeanContextServiceProvider, the factory of the service, and an arbitrary object associated with a BeanContextChild that is currently nested within the BeanContext the service is registered with. Typically such protocols encapsulate some context specific or sensitive behavior that isolates a BeanContextChild’s implementation from such dependencies thus resulting in simpler implementations, greater interoperability and portability.

A BeanContextServiceProvider, is a “factory” for one or more services. It registers itself with a particular BeanContextServices via it’s adService() method, if the service is not already registered with the BeanContextServices, the BeanContextServices associates the service specified with the BeanContextServiceProvider, and fires a BeanContextServiceAvailableEvent via the serviceAvailable() method to those BeanContextServicesListeners currently registered, then returns true, otherwise false indicating that the service is already registered for that BeanContextServices.

Once registered, and until revoked, the service is available via the BeanContextServices getService() method.

The hasService() method may be used to test the presence of a particular service, and the getCurrentServices() method returns an iterator over the currently available services for that BeanContextServices.

A BeanContextChild or any arbitrary object associated with a BeanContextChild, may obtain a reference to a currently registered service from its nesting BeanContextServices via an invocation of the getService() method. The getService() method specifies; the BeanContextChild, the associated requestor, the Class of the service requested, a service dependent parameter (known as a Service Selector), and a BeanContextServicesRevokedListener used to subsequently notify the requestor that the service class has been revoked by the BeanContextServiceProvider. The Listener is registered automatically with a unicast event source per requestor and service class and is automatically unregistered when a requestor relinquishes all references of a given service class, or as a side effect of the service being “forcibly revoked” by the providing BeanContextServiceProvider.

The BeanContextServices passes this getService() invocation onto the associated BeanContextServiceProvider (if any) to be satisfied via an invocation of its getService() method. The BeanContextServiceProvider is passed the BeanContext, the Class of the service provided, the service dependent service parameter (the Service Selector) and a reference to the object requesting the service.

The reference to the BeanContext is intended to enable the BeanContextServiceProvider to distinguish service requests from multiple sources. A BeanContextServiceProvider is only permitted to retain a weak reference to any BeanContext so obtained.

The Service Selector parameter is a service dependent value used by a service requestor for a particular service in order to parameterize the service to be provided to it by the BeanContextServiceProvider. Some examples of its usage are; a parameter to a constructor for the service implementation class; a value for a particular service’s property, or as a key into a map of existing implementations.

The reference to the requestor is intended to permit the BeanContextServiceProvider to interrogate the state of the requestor in order to perform any customization or parameterization of the service, therefore this reference shall be treated as immutable by the BeanContextServicesProvider. Additionally the BeanContextServiceProvider is permitted to retain only weak and immutable reference to both the requestor and the BeanContextChild after returning from the getService() invocation.

The BeanContextServiceProvider may satisfy the request, returning a reference to an instance of the Class of the requested service (such that the reference returned shall result in the expression: <serviceRefence> instanceof <serviceClass> being true), return null, or throw an unchecked exception.

In the case when a nested BeanContextServices is requested for a particular service that it has no BeanContextServiceProvider for, then the BeanContextServices may delegate the service requested to its own nesting BeanContextServices in order to be satisfied. Thus delegation requests can propagate from the leaf BeanContextServices to the root BeanContextServices.

A BeanContextChild may query a particular BeanContextServices for a list of currently available Service Classes (via the getCurrentServiceClasses() method)and any associated Service Selectors, if a particular service Class implements a finite list of apriori values for a Service Class, via its nesting BeanContextServices.getCurrentServiceSelectors() method, which in turn obtains the currently available Service Selectors (if any) via the BeanContextServiceProvider.getCurrentServiceSelectors() method.

If the service in question does not implement a finite set of apriori values for the set of valid Service Selectors it shall return null.

A reference obtained by a BeanContextChild via getService() is valid until the reference is released by the BeanContextChild via an invocation of its nesting BeanContextServices releaseService() method, except in the case where the BeanContextServices fires a BeanContextServiceRevokedEvent and that Event’s isCurrentServiceInvalidNow() method returns true, in this case the BeanContextServices and/or the BeanContextServiceProvider that provided the service has determined that current service references are immediately invalidated, or “forcibly revoked” (this typically occurs in the following situation).

When BeanContextChild instances are removed from a particular BeanContextServices instance, they shall discard all references to any services they obtained from that BeanContextServices by appropriate invocations of releaseService(). If the un-nesting BeanContextChild is also a BeanContextServices instance, and if any of these service references have been exposed to the un-nesting BeanContextServices’s own members as a result of a delegated getService() request as defined above, the BeanContextServiecs shall fire a BeanContextServiceRevokedEvent to notify its nested children that the service(s) are “forcibly revoked”. This immediate invalidation of current references to delegated services at un-nesting is to ensure that services that are dependent upon the structure of the hierarchy are not used by requestors after their location in the structure has changed.

BeanContextChild instances receiving a “forcable revocation” of a Service Class shall not invoke releaseService() for any references it may hold of that type, since in this case, the BeanContextServiceProvider or the BeanContextServices that provided the service reference to that BeanContextChild has already invalidated all references to that service on their behalf.

A BeanContextServiceProvider may revoke a Service Class at any time after it has registered it with a BeanContextServices by invoking its revokeService() method. Once the BeanContextServices has fired a BeanContextServiceRevokedEvent notifying the currently registered BeanContextServiceRevokedListeners and the BeanContextServicesListeners that the service is now unavailable it shall no longer satisfy any new service requests for the revoked service until (if at all) that Service Class is re-registered. References obtained by BeanContextChild requestors to a service prior to its being revoked remain valid, and therefore the service shall remain valid to satisfy those extant references, until all references to that service are released, unless in exceptional circumstances the BeanContextServiceProvider, or BeanContextServices, when revoking the service, wants to immediately terminate service to all the current references. This immediate revocation is achieved by invoking the BeanContextServices .revokeService() method with an actual parameter value of revokeNow == true. Subsequent to immediate invalidation of current service references the service implementation may throw a service specific unchecked exception in response to any attempts to continue to use the revoked service by service requestors that have erroneously retained references to the service, ignoring the earlier immediate revocation notification.

Note that in order to function correctly (when delegating service requests) in a multi-threaded environment, implementations of BeanContextServices are required to synchronize their implementations of; addService(), hasService(), getCurrentServiceClasses(), getCurrentServiceSelectors(), getService(), releaseService() and revokeService() with the BeanContext.globalHierarhyLock.

A BeanContextServicesProvider may expose the BeanInfo for the Service Classes it provides implementations for by providing a BeanInfo class that implements BeanContextServicesProviderBeanInfo. Thus exposing an array of BeanInfo’s, one for each Service Class supported. Builder tools can, for example, use this infomation to provide application developers with a palette of Servlice Classes for inclusion in an application.

2.1.4 The role of a BeanContext in Persistence

Since one of the primary roles of a BeanContext is to represent a logical nested structure of JavaBean component and BeanContext instance hierarchies, it is natural to expect that in many scenarios that hierarchy should be persistent, i.e that the BeanContext should participate in persistence mechanisms, in particular, either java.io.Serializable or java.io.Externalizable (If the latter the BeanContext is responsible for acting as the persistence container for the sub-graph of children, encoding and decoding the class information, and maintaining sub-graph equivalence after deserialization, basically the function(s) provide for serialization by ObjectOutputStream and ObjectInputStream).

In particular BeanContexts shall persist and restore their current children that implement the appropriate persistence interfaces when they themselves are made persistent or subsequently restored.

As a result of the above requirement, persistent BeanContextChild implementations are required to not persist any references to either their nesting BeanContext, or to any Delegates obtained via its nesting BeanContextServices.

BeanContexts shall, when restoring an instance of BeanContextChild from its persistence state, be required to perform the equivalent of invoking add()on the newly instantiated BeanContextChild,, in order to notify the newly restored instance of its nesting BeanContext, thus allowing that BeanContextChild to fully reestablish its dependencies on its environment.

Also note that since BeanContext implements java.beans.beancontext.BeanContextChild it shall obey the persistence requirements defined below for implementors of that interface.

2.1.5 BeanContext with associated presentation hierarchies

Although not required, many BeanContexts may be associated within a presentation hierarchy of java.awt.Containers and java.awt.Components. A Container cannot implement BeanContext directly2 but may be associated with one by implementing the BeanContextProxy interface described herein.

public interface BeanContextProxy {
    BeanContext getBeanContext();
}

For instances of classes that do not (or cannot in the case of Component or subclasses thereof) directly implement the BeanContext interface, but are associated with an instance of such an implementation, (via delegation) such instances may expose this association by implementing the BeanContextProxy interface. By doing so, this enables arbitrary 3rd parties, such as builder tools, to interrogate and discover the BeanContext associated with such objects for the purposes of either nesting objects within that associated BeanContext, observing changes in the membership, or obtaining services thereof.

This also permits multiple distinct objects (e.g: Containers) to share a single BeanContext. [Note though that in this case a shared BeanContext shall not implement BeanContextContainerProxy since that is a peer-to-peer relationship between a single BeanContext and the Container implementing that interface]

The value returned from getBeanContext() is constant for the lifetime of the implementing instance, that is the relationship between a BeanContextProxy and it’s associated BeanContext is static and thus may not change for the lifetime of either participant.

No class may implement both the BeanContext (or BeanContextChild) and the BeanContextProxy interfaces, they are mutually exclusive.

Some BeanContextProxy implementors may also implement java.util.Collection, or some other collection-like API (e.g java.awt.Container), in addition to, and possibly distinct from, maintaining a BeanContext based Collection.

In such cases it is possible to add, or remove, elements from either the BeanContext, via it’s Collection API’s, or the BeanContextProxy implementor using it’s own collection-like API’s (e.g: public boolean java.awt.Container.add(Component)). It is implementation dependent whether or not objects added or removed from either the BeanContext’s Collection, or the BeanContextProxy implementor’s collection are also added or removed from the corresponding object’s collection (i.e: should a Container.add() also infer a BeanContext.add() and vica-versa?). In such situations both participants (the implementor of BeanContextProxy and the BeanContext itself) are required to; 1) implement the same add/remove semantics as the other (i.e: if x.add(o) has a side effect of x.getBeanContext().add(o) then x.getBeanContext().add(o) should also a have side effect of x.add(o)), and 2) before adding/removing an object to/from the other participants collection, it should test (synchronized) if that object is/is not a member of the other participants collection before proceeding with the operation in question (this is to avoid infinite recursion between collection operations on both participants) (i.e: x.add(o) should not invoke x.getBeanContext().add(o) if x.getBeanContext().contains(o) is true and vica-versa).

It is important to note that if an object that implements BeanContextProxy is added to , or removed from, a BeanContext, that in addition to the operation performed on that object, the same operation should be performed on the BeanContext returned from BeanContextProxy.getBeanContext(). That is an implementor of BeanContextProxy shall be treated as though it directly implemented BeanContext by any nesting BeanContext. (and vica-versa if the operation is applied to the BeanContext its shall also be applied to the corresponding BeanContextProxy)

The following interface is defined to allow a BeanContext to expose a reference to an associated Container to enable it’s BeanContextChild members to add, or remove, their associated Component objects to/from that Container or to inspect some state on the Container.

public interface BeanContextContainerProxy {
    Container getContainer()
}

When a BeanContextChild with an associated Component is added to a BeanContext with an associated Container there are three models of interaction that can occur in relation to the nesting of the Component in the Container as a result:

  1. If the associated Component was added to the associated Container via a Container API, then the nesting of the BeanContextChild in the BeanContext is a side effect of that and no further action is required.
  2. If the Component and Container are not nested then the nesting BeanContext may as a side effect cause the Component associated with the BeanContextChild to be added to it’s associated Container.

    3. OR

  3. If the Component and Container are not nested then the BeanContextChild being nested may as a side effect may cause it’s Component to be associated with the Container associated with the nesting BeanContext.

Thus, for greatest interoperability a BeanContextChild shall always check if its Compoent’s parent is the BeanContext Container, and if it is not, then it may add itself if appropriate. Thus a BeanContextChild may function correctly under all scenarios.

The BeanContextChild is responsible for initially causing itself to eligible to be displayed via an invocation of show() [note that the BeanContextChild may also subsequently repeatedly hide() and show() itself].

The nesting BeanContext, or its associated Container, may subsequently hide() or show() the BeanContextChild’s Component arbitrarily, but it is strongly recommended that it treat that Component as immutable in all other respects with the exception of registering Listeners to obtain event notifications, or where other Component/Container specific protocols permit or require the Container to alter the state of its Component containees. An example of such a permitted interaction would be where a property such as background or foreground color were propagated from Container to Component.

Once a BeanContextChild has been un-nested from it’s BeanContext, it’s associated Component (if any) shall be removed from that BeanContext’s Container as a side effect of the removal operation, this is the responsibility of the BeanContext (typically if the BeanContextChild has been moved to another BeanContext with an associated Container via an invocation of it’s setBeanContext() method, the Component will already have been re-parented as a side effect of that operation by the time the original BeanContext is notified of the change via a PropertyChangeEvent from the child, however the check should be made and the Component removed if it has not already occurred).

To avoid infinite recursion, both a BeanContext and a BeanContextChild that also are associated with a Container and Component nesting relationship should avoid undoing any changes applied to the Component by the other party in the relationship. In general the BeanContext is responsible for the appearance, visibility and relative layout of the BeanContextChild’s Component, and the BeanContextChild is responsible for the Component’s state and content pertaining to the application functionality it is implementing.

The value returned from the getContainer() method is constant for the lifetime of the implementing BeanContext, that is the relationship between a BeanContext and a Container is static for the lifetime of both participants.

In addition the following interface is also defined:

public interface BeanContextChildComponentProxy {
    Component getComponent();
}

A BeanContext or a BeanContextChild may implement this interface to expose the GUI Component that it is associated with to it’s nesting BeanContext. A BeanContext may use this method to establish the relationship between references to instances of Component and BeanContextChild that are known to it, where a BeanContextChild and Component are not implemented by the same object instance (that is the BeanContextChild delegates its Component implementation to a distinct object rather than inheriting from Component]. A BeanContext may interrogate the Component reference it obtains from a nested BeanContextChild in order to determine its state, and it may also register Listeners for particular events, however it is strongly recommended that the BeanContext treat the reference as generally immutable to avoid changing the Component state.

The value returned from the getComponent() method is a constant for the lifetime of that BeanContextChild.

In the situation where a BeanContext has an associated Container, but does not wish to expose that Container by implementing the BeanContextContainerProxy interface, but wishes to handle the nesting of an arbitrary BeanContextChild’s associated Component (exposed by the BeanContextChild either implementing the BeanContextChildComponentProxy interface or as direct subclass of Component) the BeanContext is permitted to add/remove that Component to/from its associated Container.In such cases the BeanContextChild and it’s associated Component implementation shall not interfere with this action.

If a class implements both BeanContextChildComponentProxy and BeanContextContainerProxy then the object returned by both getComponent() and getContainer() shall be the same object.

2.2 interface java.beans.beancontext.BeanContextChild3

Simple JavaBeans that do not require any support or knowledge of their environment shall continue to function as they do today. However both JavaBeans that wish to utilize their containing BeanContext, and BeanContexts that may be nested, require to implement a mechanism that enables the propagation of the reference to the enclosing BeanContext through to cognizant JavaBeans and nested BeanContexts, the interface proposed is:

public interface java.beans.beancontext.BeanContextChild {
    void        setBeanContext(BeanContext bc)
                throws PropertyVetoException;

    BeanContext getBeanContext();

    void addPropertyChangeListener
        (String name, PropertyChangeListener pcl);

     void removePropertyChangeListener
        (String name, PropertyChangeListener pcl);

    void addVetoableChangeListener
        (String name, VetoableChangeListener pcl);

     void removeVetoableChangeListener
        (String name, VetoableChangeListener pcl);

}

The expected usage is that some 3rd party shall invoke one of the appropriate methods defined on BeanContext (by virtue of its inheritance from Collection) in order to add a BeanContextChild to the membership of the target BeanContext. As a consequence the BeanContext shall attempt to set the BeanContextChild’s “beanContext” property by invoking its setter method, setBeanContext(). Only a BeanContext may call a BeanContextChild’s setBeanContext() method, since this is the mechanism that a BeanContext uses to notify a child that it is now has a new BeanContext value. Since this property is not directly settable or customizable by a user in the context of an application construction tool the BeanInfo for a BeanContextChild should set the hidden state for this property in order for builder tools to avoid presenting the property to the user for customization.

A BeanContextChild object may throw a PropertyVetoException, to notify the nesting BeanContext that it is unable to function/be nested within that particular BeanContext. Such a veto shall be interpreted by a BeanContext as an indication that the BeanContextChild has determined that it is unable to function in that particular BeanContext and is final.

During the un-nesting of a BeanContextChild from its BeanContext, it is possible for the child, or a 3rd party listening to the child’s “beanContext” property for PropertyVetoEvents, to throw a PropertyVetoException to notify the caller that it is not in a state to be un-nested. In order to bound this interaction a BeanContextChild, or 3rd party, may veto the initial un-nesting notification, but may not veto any subsequent notifications, and must, upon receipt of such notifications, amend its state accordingly to prepare itself to be subsequently un-nested.

Note that classes that implement this interface, also act as an Event Source for (sub)interface(s) of java.beans.PropertyChangeListener, and are required to update their state accordingly and subsequently fire the appropriate java.beans.PropertyChangeEvent with propertyName = “beanContext”, oldValue = the reference to the previous nesting BeanContext, and newValue = the reference to the new nesting BeanContext, to notify any Listeners that its nesting BeanContext has changed value.

BeanContextChild instances, or nested BeanContexts in the process of terminating themselves, shall invoke the remove() method on their nesting BeanContext in order to withdraw themselves from the hierarchy prior to termination.

2.2.1 Important Persistence considerations

Instances of BeanContextChild nested within an BeanContext, will typically define fields or instance variables that will contain references to their nesting BeanContext instance, and possibly services obtained from that BeanContextServices instance via its getService() method.

In order to ensure that the act of making such an instance persistent does not erroneously persist objects from the instances nesting environment, such instances shall be required to define such fields, or instance variables as either transient, or to implement custom persistence methods that avoid persisting such state.

This requirement is crucial since operations such as cutting and pasting object instances through a clipboard via object serialization will not function correctly if the act of serializing the target object also serializes much of the entire source environment it is nested within.

3.0 Overloading java.beans.instantiate() static method

Since java.beans.instantiate() is the current mechanism for (re)instantiating JavaBeans we need to extend or overload the syntax and semantics of this method in order to accommodate the introduction of the BeanContext abstraction. The extension proposed is:

public static Object instantiate(ClassLoader cl,
                        String	      beanName,
                        BeanContext beanContext);

This method behaves has it is currently defined in the JavaBeans specification, but in addition to these existing semantics, when a non-null BeanContext is specified then the method invokes the add() method on the beanContext actual parameter with the value of the targetChild actual parameter = a reference to the newly instantiated JavaBean component.4

4.0 Providing better support for Beans that are also Applets

The current implementation of java.beans.instantiate() contains minimal support for instantiating JavaBeans that are also Applets. In particular, this method will currently construct an AppletContext and AppletStub for the newly instantiated JavaBean, set the stub on the newly instantiated Applet, and init() the Applet if it has not already been invoked.

Unfortunately this does not provide sufficient support in order to allow most Applets to be fully functional, since the AppletContext and AppletStub created by java.beans.instantiate(), are no-ops. This is a direct consequence of the lack of sufficient specification of how to construct AppletContext and AppletStub implementations in the existing Applet API’s. Furthermore, even if such specifications existed we would require an API that propagated a number of Applet attributes such as its Codebase, Parameters, AppletContext, and Documentbase into java.beans.instantiate() in order for it to subsequently instantiate the appropriately initialized objects.

Since key to supporting fully functional Applets is to provide them with fully functional AppletContext and AppletStub instances, the design goal is to provide a mechanism to provide this state to instantiate() so that it may carry out the appropriate initialization and binding5, therefore the proposed interface is:

public static Object
            instantiate(ClassLoader 				cl,
                      String      		beanName,
                      BeanContext 		bCtxt,
                      AppletInitializer															ai
            );

public interface AppletInitializer {
    void initialize(Applet newApplet, BeanContext bCtxt);
    void activate(Applet newApplet);
}

If the newly instantiated JavaBean component is an instance of java.applet.Applet then the new constructed Applet, (Bean) will be passed to the AppletInitializer via a call to initialize().

Compliant implementations of AppletInitializer.initialize() shall:

  1. Associate the newly instantiated Applet with the appropriate AppletContext.
  2. Instantiate an AppletStub() and associate that AppletStub with the Applet via
    1. an invocation of setStub().
    2. If BeanContext parameter is null, then it shall associate the Applet with its appropriate Container by adding that Applet to its Container via an invocation of add(). If the BeanContext parameter is non-null, then it is the responsibility of the BeanContext to associate the Applet with its Container during the subsequent invocation of its addChildren() method.

    Compliant implementations of AppletInitializer.activate() shall mark the Applet as active, and may optionally also invoke the Applet’s start() method.

    Note that if the newly instantiated JavaBean is not an instance of Applet, then the AppletInitializer interface is ignored.

    5.0 Standard/Suggested Conventions for BeanContext Services

    5.0.1 BeanContexts that support InfoBus.

    The InfoBus technology is a standard extension package that is intended to facilitate the rendezvous and exchange of dynamic self describing data, based upon a publish and subscribe abstraction, between JavaBean Components within a single Java Virtual Machine.

    A BeanContext that exposes an InfoBus to its nested BeanContextChild shall do so by exposing a service via the hasService() and getService() methods of type javax.infobus.InfoBus.

    Thus BeanContextChild implementations may locate a common InfoBus implementation for their current BeanContext by using this mechanism to rendezvous with that InfoBus instance.

    The Infobus 1.2 specification shall define a convenience mechanism provided by the InfoBus class to simplify the discovery mechanism for BeanContextChild instances nested within a particular instance of BeanContextServices.

    5.0.2 BeanContexts that support printing

    A BeanContext that wishes to expose printing facilities to its descendants may delegate a reference of (sub)type java.awt.PrintJob.

    As the Java Network Printing Interface evolves additional specifications will be provided to expose it’s facilities via the services mechanism.

    5.0.3 BeanContext Design/Runtime mode support.

    JavaBeans support the concepts of “design”-mode, when JavaBeans are being manipulated and composed by a developer in an Application Builder or IDE, and “Run”-mode, when the resulting JavaBeans are instantiated at runtime as part of an Applet, Application or some other executable abstraction.

    In the first version of the specification, the “mode” or state, that is “design”-time or “run”-time was a JVM global attribute. This is insufficient since, for example, in an Application Builder environment, there may be JavaBeans that function, in “run”-mode, as part of the Application Builder environment itself, as well as the JavaBeans that function, in “design”-mode, under construction by the developer using the Application Builder to compose an application.

    Therefore we require the ability to scope this “mode” at a granularity below that of JVM global.

    The BeanContext abstraction, as a “Container” or “Context” for one or more JavaBeans provides appropriate mechanism to better scope this “mode”.

    Thus BeanContext’s that wish to expose and propagate this “mode” to its descendants may delegate a reference of type java.beans.DesignMode:

    public interface java.beans.DesignMode {
    void    setDesignTime(boolean isDesignTime);
    boolean isDesignTime();
}

    Additionally, BeanContexts delegating such a reference shall be required to fire the appropriate java.beans.propertyChangeEvent, with propertyName = “designTime”, with the appropriate values for oldValue and newValue, when the “mode” changes value.

    Note that it is illegal for instances of BeanContextChild to call setDesignTime() on instances of BeanContext that they are nested within.

    5.0.4 BeanContext Visibility support.

    JavaBeans with associated presentation, or GUI, may be instantiated in environments where the ability to present that GUI is either not physically possible (when the hardware is not present), or is not appropriate under the current conditions (running in a server context instead of a client).

    The first version of the JavaBeans Specification introduced the java.beans.Visibility interface in order to provide a mechanism for JavaBeans to have their “visible” state, or ability to render a GUI, controlled from their environment.

    BeanContexts that wish to enforce a particular policy regarding the ability of their children to present GUI, shall use the java.beans.Visibility interface to control their children.

    5.0.5 Determining Locale from a BeanContext

    BeanContexts may have a locale associated with them, in order to associate and propagate this important attribute across the JavaBeans nested therein.

    Therefore, BeanContexts, shall be required to fire the appropriate java.beans.PropertyChangeEvent, with propertyName = “locale”, oldValue = the reference to the previous value of the Locale delegate, and newValue = the reference to the new value of the Locale delegate, in order to notify its Listeners of any change in Locale.

    Setting and getting the value of the Locale on the BeanContext is implementation dependent.

    6.0 Support classes

    In order to ease the implementation of this relatively complex protocol a “helper” classes are provided; java.beans.beancontext.BeanContextChildSupport, java.beans.beancontext.BeanContextSupport, and java.beans.beancontext.BeanContextServicesSupport. These classes are designed to either be subclassed, or delegated implicitly by another object, and provides fully compliant (extensible) implementations of the protocols embodied herein.

    1Note, if the remove() was invoked as a result of the BeanContext receiving an unexpected PropertyChan- geEvent notification as a result of a 3rd party invoking setBeanContext() then the remove implementation shall not invoke setBeanContext(null) on that child as part of the remove() semantics, since to do so would overwrite the value previously set by the 3rd party.
    2Unfortunately because of method name collisions between Component and Collection a Component can- not implement BeanContext or Collection directly and must model the capability with a “HasA” rather than an “IsA” relationship.
    3I don’t like this name much but I am struggling for a better alternative! (we are stuck with it)
    4Note: Since simple JavaBeans have no knowledge of a BeanContext, it is not advisable to introduce such instances into the hierarchy since there is no mechanism for these simple JavaBeans to remove them- selves from the hierarchy and thus subsequently be garbage collected.
    5AppletContext objects expose a list of Applet objects they “contain”, unfortunately the current Applet or AppletStub API’s as defined, provide no mechanism for the AppletContext to discover its Applets from its AppletStubs, or for an AppletStub to inform its AppletContext of its Applet. Therefore we will have to assume that this binding/discovery can occur in order for this mechanism to be worthwhile in java.beans.instantiate().

    Contents Extensible Runtime Containment and Server Protocol for JavaBeans
    , Version 1.0

    Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


Annotated Outline of the Collections Framework

Java

Annotated Outline of Collections Framework
The collections framework consists of:
  • Collection Interfaces - The primary means by which collections are manipulated.
    • Collection - A group of objects. No assumptions are made about the order of the collection (if any), or whether it may contain duplicate elements.
    • Set - The familiar set abstraction. No duplicate elements permitted. May or may not be ordered. Extends the Collection interface.
    • List - Ordered collection, also known as a sequence. Duplicates are generally permitted. Allows positional access. Extends the Collection interface.
    • Queue - A collection designed for holding elements prior to processing. Besides basic Collection operations, queues provide additional insertion, extraction, and inspection operations.
    • Deque - A double ended queue, supporting element insertion and removal at both ends. Extends the Queue interface.
    • Map - A mapping from keys to values. Each key can map to at most one value.
    • SortedSet - A set whose elements are automatically sorted, either in their natural ordering (see the Comparable interface), or by a Comparator object provided when a SortedSet instance is created. Extends the Set interface.
    • SortedMap - A map whose mappings are automatically sorted by key, either in the keys' natural ordering or by a comparator provided when a SortedMap instance is created. Extends the Map interface.
    • NavigableSet - A SortedSet extended with navigation methods reporting closest matches for given search targets. A NavigableSet may be accessed and traversed in either ascending or descending order.
    • NavigableMap - A SortedMap extended with navigation methods returning the closest matches for given search targets. A NavigableMap may be accessed and traversed in either ascending or descending key order.
    • BlockingQueue - A Queue with operations that wait for the queue to become non-empty when retrieving an element, and that wait for space to become available in the queue when storing an element. (This interface is part of java.util.concurrent.)
    • BlockingDeque - A Deque with operations that wait for the deque to become non-empty when retrieving an element, and wait for space to become available in the deque when storing an element. Extends both the Deque and BlockingQueue interfaces. (This interface is part of java.util.concurrent.)
    • ConcurrentMap - A Map with atomic putIfAbsent, remove, and replace methods. (This interface is part of java.util.concurrent.)
    • ConcurrentNavigableMap - A ConcurrentMap that is also a NavigableMap.
  • General-Purpose Implementations - The primary implementations of the collection interfaces.
    • HashSet - Hash table implementation of the Set interface. The best all-around implementation of the Set interface.
    • TreeSet - Red-black tree implementation of the NavigableSet interface.
    • LinkedHashSet - Hash table and linked list implementation of the Set interface. An insertion-ordered Set implementation that runs nearly as fast as HashSet.
    • ArrayList - Resizable-array implementation of the List interface. (Essentially an unsynchronized Vector.) The best all-around implementation of the List interface.
    • ArrayDeque - Efficient resizable-array implementation of the Deque interface.
    • LinkedList - Doubly-linked list implementation of the List interface. May provide better performance than the ArrayList implementation if elements are frequently inserted or deleted within the list. Also implements the Deque interface. When accessed via the Queue interface, LinkedList behaves as a FIFO queue.
    • PriorityQueue - Heap implementation of an unbounded priority queue.
    • HashMap - Hash table implementation of the Map interface. (Essentially an unsynchronized Hashtable that supports null keys and values.) The best all-around implementation of the Map interface.
    • TreeMap Red-black tree implementation of the NavigableMap interface.
    • LinkedHashMap - Hash table and linked list implementation of the Map interface. An insertion-ordered Map implementation that runs nearly as fast as HashMap. Also useful for building caches (see removeEldestEntry(Map.Entry) ).
  • Wrapper Implementations - Functionality-enhancing implementations for use with other implementations. Accessed solely through static factory methods.
    • Collections.unmodifiableInterface - Return an unmodifiable view of a specified collection that throws an UnsupportedOperationException if the user attempts to modify it.
    • Collections.synchronizedInterface - Return a synchronized collection that is backed by the specified (typically unsynchronized) collection. As long as all accesses to the backing collection are through the returned collection, thread-safety is guaranteed.
    • Collections.checkedInterface - Return a dynamically typesafe view of the specified collection, which throws a ClassCastException if a client attempts to add an element of the wrong type. The generics mechanism in the language provides compile-time (static) type checking, but it is possible to defeat this mechanism. Dynamically typesafe views eliminate this possibility entirely.
  • Convenience Implementations - High-performance "mini-implementations" of the collection interfaces.
    • Arrays.asList - Allows an array to be viewed as a list.
    • EMPTY_SET, EMPTY_LIST and EMPTY_MAP - Constants representing the empty set and list (immutable).
    • singleton, singletonList, and singletonMap - Returns an immutable "singleton" set, list, or map, containing only the specified object (or key-value mapping).
    • nCopies - Returns an immutable list consisting of n copies of a specified object.
  • Legacy Implementations - Older collection classes have been retrofitted to implement the collection interfaces.
    • Vector - Synchronized resizable-array implementation of the List interface with additional "legacy methods."
    • Hashtable - Synchronized hash table implementation of the Map interface that does not allow null keys or values, with additional "legacy methods."
  • Special Purpose Implementations
    • WeakHashMap - An implementation of the Map interface that stores only weak references to its keys. Storing only weak references allows key-value pairs to be garbage-collected when the key is no longer referenced outside of the WeakHashMap. This class provides the easiest way to harness the power of weak references. It is useful for implementing "registry-like" data structures, where the utility of an entry vanishes when its key is no longer reachable by any thread.
    • IdentityHashMap - Identity-based Map implementation based on a hash table. This class is useful for topology-preserving object graph transformations (such as serialization or deep-copying). To perform such transformations, you need to maintain an identity-based "node table" that keeps track of which objects have already been seen. Identity-based maps are also used to maintain object-to-meta-information mappings in dynamic debuggers and similar systems. Finally, identity-based maps are useful in thwarting "spoof attacks" resulting from intentionally perverse equals methods. (IdentityHashMap never invokes the equals method on its keys.) An added benefit of this implementation is that it is fast.
    • CopyOnWriteArrayList - a List implementation backed by an copy-on-write array. All mutative operations (such as add, set, and remove) are implemented by making a new copy of the array. No synchronization is necessary, even during iteration, and iterators are guaranteed never to throw ConcurrentModificationException. This implementation is well-suited to maintaining event-handler lists (where change is infrequent, and traversal is frequent and potentially time-consuming).
    • CopyOnWriteArraySet - A Set implementation backed by a copy-on-write array. This implementation is similar in nature to CopyOnWriteArrayList. Unlike most Set implementations, the add, remove, and contains methods require time proportional to the size of the set. This implementation is well-suited to maintaining event-handler lists that must prevent duplicates.
    • EnumSet - a high-performance Set implementation backed by a bit-vector. All elements of each EnumSet instance must be elements of a single enum type.
    • EnumMap - a high-performance Map implementation backed by an array. All keys in each EnumMap instance must be elements of a single enum type.
  • Concurrent Implementations - These implementations are part of java.util.concurrent.
    • ConcurrentLinkedQueue - An unbounded FIFO (first-in first-out) queue based on linked nodes.
    • LinkedBlockingQueue - An optionally bounded FIFO blocking queue backed by linked nodes.
    • ArrayBlockingQueue - A bounded FIFO blocking queue backed by an array.
    • PriorityBlockingQueue - An unbounded blocking priority queue backed by a priority heap.
    • DelayQueue - A time-based scheduling queue backed by a priority heap.
    • SynchronousQueue - A simple rendezvous mechanism utilizing the BlockingQueue interface.
    • LinkedBlockingDeque - An optionally bounded FIFO blocking deque backed by linked nodes.
    • ConcurrentHashMap - A highly concurrent, high-performance ConcurrentMap implementation based on a hash table. This implementation never blocks when performing retrievals and allows the client to select the concurrency level for updates. It is intended as a drop-in replacement for Hashtable: in addition to implementing ConcurrentMap, it supports all of the "legacy" methods peculiar to Hashtable.
    • ConcurrentSkipListSet - Skip list implementation of the NavigableSet interface.
    • ConcurrentSkipListMap - Skip list implementation of the ConcurrentNavigableMap interface.
  • Abstract Implementations - Skeletal implementations of the collection interfaces to facilitate custom implementations.
    • AbstractCollection - Skeletal Collection implementation that is neither a set nor a list (such as a "bag" or multiset).
    • AbstractSet - Skeletal Set implementation.
    • AbstractList - Skeletal List implementation backed by a random-access data store (such as an array).
    • AbstractSequentialList - Skeletal List implementation backed by a sequential-access data store (such as a linked list).
    • AbstractQueue - Skeletal Queue implementation.
    • AbstractMap - Skeletal Map implementation.
  • Algorithms - The Collections class contains these useful static methods:
    • sort(List) - Sorts a list using a merge sort algorithm, which provides average-case performance comparable to a high-quality quicksort, guaranteed O(n*log n) performance (unlike quicksort), and stability (unlike quicksort). (A stable sort is one that does not reorder equal elements.)
    • binarySearch(List, Object) - Searches for an element in an ordered list using the binary search algorithm.
    • reverse(List) - Reverses the order of the elements in the a list.
    • shuffle(List) - Randomly permutes the elements in a list.
    • fill(List, Object) - Overwrites every element in a list with the specified value.
    • copy(List dest, List src) - Copies the source list into the destination list.
    • min(Collection) - Returns the minimum element in a collection.
    • max(Collection) - Returns the maximum element in a collection.
    • rotate(List list, int distance) - Rotates all of the elements in the list by the specified distance.
    • replaceAll(List list, Object oldVal, Object newVal) - Replaces all occurrences of one specified value with another.
    • indexOfSubList(List source, List target) - Returns the index of the first sublist of source that is equal to target.
    • lastIndexOfSubList(List source, List target) - Returns the index of the last sublist of source that is equal to target.
    • swap(List, int, int) - Swaps the elements at the specified positions in the specified list.
    • frequency(Collection, Object) - Counts the number of times the specified element occurs in the specified collection.
    • disjoint(Collection, Collection) - Determines whether two collections are disjoint, in other words, whether they contain no elements in common.
    • addAll(Collection<? super T>, T...) - Adds all of the elements in the specified array to the specified collection.
    • newSetFromMap(Map) - Creates a general purpose Set implementation from a general purpose Map implementation.
    • asLifoQueue(Deque) - Returns a view of a Deque as a Last-in-first-out (Lifo) Queue.
  • Infrastructure
    • Iterators - Similar to the familiar Enumeration interface, but more powerful, and with improved method names.
      • Iterator - In addition to the functionality of the Enumeration interface, allows the user to remove elements from the backing collection with well defined, useful semantics.
      • ListIterator - Iterator for use with lists. In addition to the functionality of the Iterator interface, supports bi-directional iteration, element replacement, element insertion and index retrieval.
    • Ordering
      • Comparable - Imparts a natural ordering to classes that implement it. The natural ordering may be used to sort a list or maintain order in a sorted set or map. Many classes have been retrofitted to implement this interface.
      • Comparator - Represents an order relation, which may be used to sort a list or maintain order in a sorted set or map. Can override a type's natural ordering, or order objects of a type that does not implement the Comparable interface.
    • Runtime Exceptions
      • UnsupportedOperationException - Thrown by collections if an unsupported optional operation is called.
      • ConcurrentModificationException - Thrown by iterators and list iterators if the backing collection is modified unexpectedly while the iteration is in progress. Also thrown by sublist views of lists if the backing list is modified unexpectedly.
    • Performance
      • RandomAccess - Marker interface that allows List implementations to indicate that they support fast (generally constant time) random access. This allows generic algorithms to alter their behavior to provide good performance when applied to either random or sequential access lists.
  • Array Utilities
    • Arrays - Contains static methods to sort, search, compare, hash, copy, resize, convert to String, and fill arrays of primitives and Objects.

Copyright © 1995-2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: collections-comments@java.sun.com 		Sun
Java Software


Collections Framework Change Summary for J2SDK 1.4

Java

Collections Framework Enhancements
This page summarizes the enhancements made to the collections framework in version 1.4 of the JavaTM 2 SDK.
  • The Collections utility class has several new methods:
    • rotate(List list, int distance) - Rotates all of the elements in the list by the the specified distance. This operation is common in GUI computations: moving one or more columns in a table can be accomplished efficiently by applying this operation to a sublist. This operation is also common in mathematical and scientific calculations.

    • replaceAll(List list, Object oldVal, Object newVal) - Replaces all occurrences of one specified value with another. This is essentially a convenience method. Though not difficult to program, it's very commonly needed.

    • indexOfSubList(List source, List target) - Returns the index of the first sublist of source that is equal to target. Commonly used in many domains including text processing.

    • lastIndexOfSubList(List source, List target) - Returns the index of the last sublist of source that is equal to target. Commonly used in many domains including text processing.

    • swap(List list, int i, int j) - Swaps the elements at the specified positions in the specified list. Essentially a convenience method, though this implementation is faster than the naive implementation.

    • list(Enumeration e) - Returns an ArrayList containing the elements returned by the specified enumeration. This convenience method provides interoperability between legacy APIs that return enumerations and new APIs that require collections.

  • New interface RandomAccess is a marker interface that allows List implementations to indicate that they support fast (generally constant time) random access. This allows generic algorithms to alter their behavior to provide good performance when applied to either random or sequential access lists.

  • New class LinkedHashMap provides an insertion-ordered Map implementation that runs nearly as fast as HashMap. Internally, it uses a hash table with a doubly linked list running through it in insertion order. Also available is a corresponding Set implementation, called LinkedHashSet.

  • New class IdentityHashMap is an identity-based Map implementation based on a hash table. This class is useful for topology-preserving object graph transformations (such as serialization or deep-copying). To perform such transformations, you need to maintain an identity-based "node table" that keeps track of which objects have already been seen. Identity-based maps are also used to maintain object-to-meta-information mappings in dynamic debuggers and similar systems. Finally, identity-based maps are useful in thwarting "spoof attacks" resulting from intentionally perverse equals methods. (IdentityHashMap never invokes the equals method on its keys.) An added benefit of this implementation is that it is fast.

Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: collections-comments@java.sun.com 		Sun
Java Software


Collections Framework Change Summary for Java SE 6

Java

Collections Framework Enhancements
This page summarizes enhancements to the collections framework in Java SE 6.

This release saw fewer API changes than 5.0, but there was more of a focus on the accuracy and clarity of the specification. We recommend using the Java SE 6 specification even when writing programs for older releases.

The primary theme of the API changes was better bi-directional collection access.

These new collection interfaces are provided:

  • Deque - a double ended queue, supporting element insertion and removal at both ends. Extends the Queue interface.
  • BlockingDeque - a Deque with operations that wait for the deque to become non-empty when retrieving an element, and wait for space to become available in the deque when storing an element. Extends both the Deque and BlockingQueue interfaces. (This interface is part of java.util.concurrent.)
  • NavigableSet - a SortedSet extended with navigation methods reporting closest matches for given search targets. A NavigableSet may be accessed and traversed in either ascending or descending order. This interface is intended to supersede the SortedSet interface.
  • NavigableMap - a SortedMap extended with navigation methods returning the closest matches for given search targets. A NavigableMap may be accessed and traversed in either ascending or descending key order. This interface is intended to supersede the SortedMap interface.
  • ConcurrentNavigableMap - a ConcurrentMap that is also a NavigableMap. (This interface is part of java.util.concurrent.)

The following concrete implementation classes have been added:

  • ArrayDeque - efficient resizable-array implementation of the Deque interface.
  • ConcurrentSkipListSet - concurrent scalable skip list implementation of the NavigableSet interface.
  • ConcurrentSkipListMap - concurrent scalable skip list implementation of the ConcurrentNavigableMap interface.
  • LinkedBlockingDeque - concurrent scalable optionally bounded FIFO blocking deque backed by linked nodes.
  • AbstractMap.SimpleEntry - simple mutable implementation of Map.Entry
  • AbstractMap.SimpleImmutableEntry - simple immutable implementation of Map.Entry

These existing classes have been retrofitted to implement new interfaces:

  • LinkedList - retrofitted to implement the Deque interface.
  • TreeSet - retrofitted to implement the NavigableSet interface.
  • TreeMap - retrofitted to implement the NavigableMap interface.

Two new methods were added to the Collections utility class:

  • newSetFromMap(Map) - creates a general purpose Set implementation from a general purpose Map implementation.

    There is no IdentityHashSet class, but instead, just use

    Set<Object> identityHashSet=
    Collections.newSetFromMap(
        new IdentityHashMap<Object, Boolean>());
  • asLifoQueue(Deque) - returns a view of a Deque as a Last-in-first-out (Lifo) Queue.
The Arrays utility class now has methods copyOf and copyOfRange that can efficiently resize, truncate, or copy subarrays for arrays of all types.

Before:

int[] newArray = new int[newLength];
System.arraycopy(oldArray, 0, newArray, 0, oldArray.length);

After:

int[] newArray = Arrays.copyOf(a, newLength);

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: collections-comments@java.sun.com 		Sun
Java Software


Collections Framework Change Summary for JDK 5

Java

Collections Framework Enhancements
This page summarizes enhancements to the collections framework in version 5 of the JDK.

Three new language features significantly enhance the collections framework:

  • Generics - adds compile-time type safety to the collections framework and eliminates the need to cast when reading elements from collections.
  • Enhanced for loop - eliminates the need for explicit iterators when interating over collections.
  • Autoboxing/unboxing - automatically converts primitives (such as int) to wrapper classes (such as Integer) when inserting them into collections, and converts wrapper class instances to primitives when reading from collections.
Three new collection interfaces are provided:
  • Queue - represents a collection designed for holding elements prior to processing. Besides basic Collection operations, queues provide additional insertion, extraction, and inspection operations.
  • BlockingQueue - extends Queue with operations that wait for the queue to become non-empty when retrieving an element, and that wait for space to become available in the queue when storing an element. (This interface is part of the new package java.util.concurrent.)
  • ConcurrentMap - extends Map with atomic putIfAbsent, remove, and replace methods. (This interface is part of java.util.concurrent.)
Two new concrete Queue implementations are provided, one existing List implementation has been retrofitted to implement Queue, and one abstract Queue implementation is provided:
  • PriorityQueue - an unbounded priority queue backed by a heap.
  • ConcurrentLinkedQueue - an unbounded thread-safe FIFO (first-in first-out) queue backed by linked nodes. (This class is part of java.util.concurrent.)
  • LinkedList - retrofitted to implement the Queue interface. When accessed via the Queue interface, LinkedList behaves as a FIFO queue.
  • AbstractQueue - a skeletal Queue implementation.
Five new BlockingQueue implementations are provided, all of which are part of java.util.concurrent:
  • LinkedBlockingQueue - an optionally bounded FIFO blocking queue backed by linked nodes.
  • ArrayBlockingQueue - a bounded FIFO blocking queue backed by an array.
  • PriorityBlockingQueue - an unbounded blocking priority queue backed by a heap.
  • DelayQueue - a time-based scheduling queue backed by a heap.
  • SynchronousQueue - a simple rendezvous mechanism utilizing the BlockingQueue interface.
One ConcurrentMap implementation is provided:
  • ConcurrentHashMap - a highly concurrent, high-performance ConcurrentMap implementation backed by a hash table. This implementation never blocks when performing retrievals and allows the client to select the concurrency level for updates. It is intended as a drop-in replacement for Hashtable: in addition to implementing ConcurrentMap, it supports all of the "legacy" methods peculiar to Hashtable.
Special-purpose List and Set implementations are provided for use in situations where read operations vastly outnumber write operations and iteration cannot or should not be synchronized:
  • CopyOnWriteArrayList - a List implementation backed by an array. All mutative operations (such as add, set, and remove) are implemented by making a new copy of the array. No synchronization is necessary, even during iteration, and iterators are guaranteed never to throw ConcurrentModificationException. This implementation is well-suited to maintaining event-handler lists (where change is infrequent, and traversal is frequent and potentially time-consuming).
  • CopyOnWriteArraySet - a Set implementation backed by a copy-on-write array. This implementation is similar in nature to CopyOnWriteArrayList. Unlike most Set implementations, the add, remove, and contains methods require time proportional to the size of the set. This implementation is well-suited to maintaining event-handler lists that must prevent duplicates.
Special-purpose Set and Map implementations are provided for use with enums:
  • EnumSet - a high-performance Set implementation backed by a bit-vector. All elements of each EnumSet instance must be elements of a single enum type.
  • EnumMap - a high-performance Map implementation backed by an array. All keys in each EnumMap instance must be elements of a single enum type.
A new family of wrapper implementations is provided, primarily for use with generic collections:
  • Collections.checkedInterface - returns a dynamically typesafe view of the specified collection, which throws a ClassCastException if a client attempts to add an element of the wrong type. The generics mechanism in the language provides compile-time (static) type checking, but it is possible to defeat this mechanism. Dynamically typesafe views eliminate this possibility entirely.
Three new generic algorithms and one comparator converter were added to the Collections utility class:
  • frequency(Collection<?> c, Object o) - counts the number of times the specified element occurs in the specified collection.
  • disjoint(Collection<?> c1, Collection<?> c2) - determines whether two collecitons are disjoint, in other words, whether they contain no elements in common.
  • addAll(Collection<? super T> c, T... a) - convenience method to add all of the elements in the specified array to the specified collection.
  • Comparator<T> reverseOrder(Comparator<T> cmp) - returns a comparator that represents the reverse ordering of the specified comparator.
The Arrays utility class has been outfitted with content-based hashCode and toString methods for arrays of all types. These methods complement the existing equals methods. Versions of all three methods are provided to operate on nested (or "multidimensional") arrays: deepEquals, deepHashCode, and deepToString. It is now trivial to print the contents of any array. The idiom for printing a "flat" array is:
    System.out.println(Arrays.toString(a));
The idiom for printing a nested (multidimensional) array is:
    System.out.println(Arrays.deepToString(a));

Finally, Boolean was retrofitted to implement Comparable.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: collections-comments@java.sun.com 		Sun
Java Software


Collections Framework Overview

Introduction

The Java 2 platform includes a collections framework. A collection is an object that represents a group of objects (such as the classic Vector class). A collections framework is a unified architecture for representing and manipulating collections, allowing them to be manipulated independently of the details of their representation.

The primary advantages of a collections framework are that it:

  • Reduces programming effort by providing useful data structures and algorithms so you don't have to write them yourself.
  • Increases performance by providing high-performance implementations of useful data structures and algorithms. Because the various implementations of each interface are interchangeable, programs can be easily tuned by switching implementations.
  • Provides interoperability between unrelated APIs by establishing a common language to pass collections back and forth.
  • Reduces the effort required to learn APIs by eliminating the need to learn multiple ad hoc collection APIs.
  • Reduces the effort required to design and implement APIs by eliminating the need to produce ad hoc collections APIs.
  • Fosters software reuse by providing a standard interface for collections and algorithms to manipulate them.

The collections framework consists of:

  • Collection Interfaces - Represent different types of collections, such as sets, lists and maps. These interfaces form the basis of the framework.
  • General-purpose Implementations - Primary implementations of the collection interfaces.
  • Legacy Implementations - The collection classes from earlier releases, Vector and Hashtable, have been retrofitted to implement the collection interfaces.
  • Special-purpose Implementations - Implementations designed for use in special situations. These implementations display nonstandard performance characteristics, usage restrictions, or behavior.
  • Concurrent Implementations - Implementations designed for highly concurrent use.
  • Wrapper Implementations - Add functionality, such as synchronization, to other implementations.
  • Convenience Implementations - High-performance "mini-implementations" of the collection interfaces.
  • Abstract Implementations - Partial implementations of the collection interfaces to facilitate custom implementations.
  • Algorithms - Static methods that perform useful functions on collections, such as sorting a list.
  • Infrastructure - Interfaces that provide essential support for the collection interfaces.
  • Array Utilities - Utility functions for arrays of primitives and reference objects. Not, strictly speaking, a part of the Collections Framework, this functionality was added to the Java platform at the same time and relies on some of the same infrastructure.

Collection Interfaces

There are fourteen collection interfaces. The most basic interface is Collection. These interfaces extend Collection: Set, List, SortedSet, NavigableSet, Queue, Deque, BlockingQueue and BlockingDeque. The other collection interfaces, Map, SortedMap, NavigableMap, ConcurrentMap and ConcurrentNavigableMap do not extend Collection, as they represent mappings rather than true collections. However, these interfaces contain collection-view operations, which allow them to be manipulated as collections.

Many of the modification methods in the collection interfaces are labeled optional. Some implementations may not perform one or more of these operations, throwing a runtime exception (UnsupportedOperationException) if they are attempted. Implementations must specify in their documentation which optional operations they support. Several terms are introduced to aid in this specification:

  • Collections that do not support any modification operations (such as add, remove and clear) are referred to as unmodifiable. Collections that are not unmodifiable are referred to modifiable.
  • Collections that additionally guarantee that no change in the Collection object will ever be visible are referred to as immutable. Collections that are not immutable are referred to as mutable.
  • Lists that guarantee that their size remains constant even though the elements may change are referred to as fixed-size. Lists that are not fixed-size are referred to as variable-size.
  • Lists that support fast (generally constant time) indexed element access are known as random access lists. Lists that do not support fast indexed element access are known as sequential access lists. The RandomAccess marker interface is provided to allow lists to advertise the fact that they support random access. This allows generic algorithms to alter their behavior to provide good performance when applied to either random or sequential access lists.

Some implementations may restrict what elements (or in the case of Maps, keys and values) may be stored. Possible restrictions include requiring elements to:

  • Be of a particular type.
  • Be non-null.
  • Obey some arbitrary predicate.

Attempting to add an element that violates an implementation's restrictions results in a runtime exception, typically a ClassCastException, an IllegalArgumentException or a NullPointerException. Attempting to remove or test for the presence of an element that violates an implementation's restrictions may result in an exception, though some "restricted collections" may permit this usage.

Collection Implementations

Classes that implement the collection interfaces typically have names of the form <Implementation-style><Interface>. The general purpose implementations are summarized in the table below:
 |  | Implementations
 |  | Hash Table | Resizable Array | Balanced Tree | Linked List | Hash Table + Linked List
Interfaces | Set | HashSet |  | TreeSet |  | LinkedHashSet
 | List |  | ArrayList |  | LinkedList |
 | Deque |  | ArrayDeque |  | LinkedList |
 | Map | HashMap |  | TreeMap |  | LinkedHashMap

The general-purpose implementations support all of the optional operations in the collection interfaces, and have no restrictions on the elements they may contain. They are unsynchronized, but the Collections class contains static factories called synchronization wrappers that may be used to add synchronization to many unsynchronized collections. All of the new implementations have fail-fast iterators, which detect illegal concurrent modification, and fail quickly and cleanly (rather than behaving erratically).

The AbstractCollection, AbstractSet, AbstractList, AbstractSequentialList and AbstractMap classes provide skeletal implementations of the core collection interfaces, to minimize the effort required to implement them. The API documentation for these classes describes precisely how each method is implemented so the implementer knows which methods should be overridden, given the performance of the "basic operations" of a specific implementation.

Design Goals

The main design goal was to produce an API that was reasonably small, both in size, and, more importantly, in "conceptual weight." It was critical that the new functionality not seem alien to current Java programmers; it had to augment current facilities, rather than replacing them. At the same time, the new API had to be powerful enough to provide all the advantages described above.

To keep the number of core interfaces small, the interfaces do not attempt to capture such subtle distinctions as mutability, modifiability, and resizability. Instead, certain calls in the core interfaces are optional, allowing implementations to throw an UnsupportedOperationException to indicate that they do not support a specified optional operation. Of course, collection implementers must clearly document which optional operations are supported by an implementation.

To keep the number of methods in each core interface small, an interface contains a method only if either:

  1. It is a truly fundamental operation: a basic operations in terms of which others could be reasonably defined,
  2. There is a compelling performance reason why an important implementation would want to override it.

It was critical that all reasonable representations of collections interoperate well. This included arrays, which cannot be made to implement the Collection interface directly without changing the language. Thus, the framework includes methods to allow collections to be dumped into arrays, arrays to be viewed as collections, and maps to be viewed as collections.

Copyright © 1995-2004 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: collections-comments@java.sun.com 		Sun
Java Software


Java Collections API Design FAQ
This document answers frequently asked questions concerning the design of the Java collections framework. It is derived from the large volume of traffic on the collections-comments alias. It serves as a design rationale for the collections framework.

Core Interfaces - General Questions

  1. Why don't you support immutability directly in the core collection interfaces so that you can do away with optional operations (and UnsupportedOperationException)?

  2. Won't programmers have to surround any code that calls optional operations with a try-catch clause in case they throw an UnsupportedOperationException?

  3. Why isn't there a core interface for "bags" (AKA multisets)?

  4. Why didn't you use "Beans-style names" for consistency?

Collection Interface

  1. Why doesn't Collection extend Cloneable and Serializable?

  2. Why don't you provide an "apply" method in Collection to apply a given method ("upcall") to all the elements of the Collection?

  3. Why didn't you provide a "Predicate" interface, and related methods (e.g., a method to find the first element in the Collection satisfying the predicate)?

  4. Why don't you provide a form of the addAll method that takes an Enumeration (or an Iterator)?

  5. Why don't the concrete implementations in the JDK have Enumeration (or Iterator) constructors?

  6. Why don't you provide an Iterator.add method?

List Interface

  1. Why don't you rename the List interface to Sequence; doesn't "list" generally suggest "linked list"? Also, doesn't it conflict with java.awt.List?

  2. Why don't you rename List's set method to replace, to avoid confusion with Set.

Map Interface

  1. Why doesn't Map extend Collection?

Iterator Interface

  1. Why doesn't Iterator extend Enumeration?

  2. Why don't you provide an Iterator.peek method that allows you to look at the next element in an iteration without advancing the iterator?

Miscellaneous

  1. Why did you write a new collections framework instead of adopting JGL (a preexisting collections package from ObjectSpace, Inc.) into the JDK?

  2. Why don't you eliminate all of the methods and classes that return "views" (Collections backed by other collection-like objects). This would greatly reduce aliasing.

  3. Why don't you provide for "observable" collections that send out Events when they're modified?

Core Interfaces - General Questions

  1. Why don't you support immutability directly in the core collection interfaces so that you can do away with optional operations (and UnsupportedOperationException)?

    This is the most controversial design decision in the whole API. Clearly, static (compile time) type checking is highly desirable, and is the norm in Java. We would have supported it if we believed it were feasible. Unfortunately, attempts to achieve this goal cause an explosion in the size of the interface hierarchy, and do not succeed in eliminating the need for runtime exceptions (though they reduce it substantially).

    Doug Lea, who wrote a popular Java collections package that did reflect mutability distinctions in its interface hierarchy, no longer believes it is a viable approach, based on user experience with his collections package. In his words (from personal correspondence) "Much as it pains me to say it, strong static typing does not work for collection interfaces in Java."

    To illustrate the problem in gory detail, suppose you want to add the notion of modifiability to the Hierarchy. You need four new interfaces: ModifiableCollection, ModifiableSet, ModifiableList, and ModifiableMap. What was previously a simple hierarchy is now a messy heterarchy. Also, you need a new Iterator interface for use with unmodifiable Collections, that does not contain the remove operation. Now can you do away with UnsupportedOperationException? Unfortunately not.

    Consider arrays. They implement most of the List operations, but not remove and add. They are "fixed-size" Lists. If you want to capture this notion in the hierarchy, you have to add two new interfaces: VariableSizeList and VariableSizeMap. You don't have to add VariableSizeCollection and VariableSizeSet, because they'd be identical to ModifiableCollection and ModifiableSet, but you might choose to add them anyway for consistency's sake. Also, you need a new variety of ListIterator that doesn't support the add and remove operations, to go along with unmodifiable List. Now we're up to ten or twelve interfaces, plus two new Iterator interfaces, instead of our original four. Are we done? No.

    Consider logs (such as error logs, audit logs and journals for recoverable data objects). They are natural append-only sequences, that support all of the List operations except for remove and set (replace). They require a new core interface, and a new iterator.

    And what about immutable Collections, as opposed to unmodifiable ones? (i.e., Collections that cannot be changed by the client AND will never change for any other reason). Many argue that this is the most important distinction of all, because it allows multiple threads to access a collection concurrently without the need for synchronization. Adding this support to the type hierarchy requires four more interfaces.

    Now we're up to twenty or so interfaces and five iterators, and it's almost certain that there are still collections arising in practice that don't fit cleanly into any of the interfaces. For example, the collection-views returned by Map are natural delete-only collections. Also, there are collections that will reject certain elements on the basis of their value, so we still haven't done away with runtime exceptions.

    When all was said and done, we felt that it was a sound engineering compromise to sidestep the whole issue by providing a very small set of core interfaces that can throw a runtime exception.

  2. Won't programmers have to surround any code that calls optional operations with a try-catch clause in case they throw an UnsupportedOperationException?

    It was never our intention that programs should catch these exceptions: that's why they're unchecked (runtime) exceptions. They should only arise as a result of programming errors, in which case, your program will halt due to the uncaught exception.

  3. Why isn't there a core interface for "bags" (AKA multisets)?

    The Collection interface provides this functionality. We are not providing any public implementations of this interface, as we think that it wouldn't be used frequently enough to "pull its weight." We occasionally return such Collections, which are implemented easily atop AbstractCollection (for example, the Collection returned by Map.values).

  4. Why didn't you use "Beans-style names" for consistency?

    While the names of the new collections methods do not adhere to the "Beans naming conventions", we believe that they are reasonable, consistent and appropriate to their purpose. It should be remembered that the Beans naming conventions do not apply to the JDK as a whole; the AWT did adopt these conventions, but that decision was somewhat controversial. We suspect that the collections APIs will be used quite pervasively, often with multiple method calls on a single line of code, so it is important that the names be short. Consider, for example, the Iterator methods. Currently, a loop over a collection looks like this:

        for (Iterator i = c.iterator(); i.hasNext(); )
        System.out.println(i.next());
    Everything fits neatly on one line, even if the Collection name is a long expression. If we named the methods "getIterator", "hasNextElement" and "getNextElement", this would no longer be the case. Thus, we adopted the "traditional" JDK style rather than the Beans style.

Collection Interface

  1. Why doesn't Collection extend Cloneable and Serializable?

    Many Collection implementations (including all of the ones provided by the JDK) will have a public clone method, but it would be mistake to require it of all Collections. For example, what does it mean to clone a Collection that's backed by a terabyte SQL database? Should the method call cause the company to requisition a new disk farm? Similar arguments hold for serializable.

    If the client doesn't know the actual type of a Collection, it's much more flexible and less error prone to have the client decide what type of Collection is desired, create an empty Collection of this type, and use the addAll method to copy the elements of the original collection into the new one.

  2. Why don't you provide an "apply" method in Collection to apply a given method ("upcall") to all the elements of the Collection?

    This is what is referred to as an "Internal Iterator" in the "Design Patterns" book (Gamma et al.). We considered providing it, but decided not to as it seems somewhat redundant to support internal and external iterators, and Java already has a precedent for external iterators (with Enumerations). The "throw weight" of this functionality is increased by the fact that it requires a public interface to describe upcalls.

  3. Why didn't you provide a "Predicate" interface, and related methods (e.g., a method to find the first element in the Collection satisfying the predicate)?

    It's easy to implement this functionality atop Iterators, and the resulting code may actually look cleaner as the user can inline the predicate. Thus, it's not clear whether this facility pulls its weight. It could be added to the Collections class at a later date (implemented atop Iterator), if it's deemed useful.

  4. Why don't you provide a form of the addAll method that takes an Enumeration (or an Iterator)?

    Because we don't believe in using Enumerations (or Iterators) as "poor man's collections." This was occasionally done in prior releases, but now that we have the Collection interface, it is the preferred way to pass around abstract collections of objects.

  5. Why don't the concrete implementations in the JDK have Enumeration (or Iterator) constructors?

    Again, this is an instance of an Enumeration serving as a "poor man's collection" and we're trying to discourage that. Note however, that we strongly suggest that all concrete implementations should have constructors that take a Collection (and create a new Collection with the same elements).

  6. Why don't you provide an Iterator.add method?

    The semantics are unclear, given that the contract for Iterator makes no guarantees about the order of iteration. Note, however, that ListIterator does provide an add operation, as it does guarantee the order of the iteration.

List Interface

  1. Why don't you rename the List interface to Sequence; doesn't "list" generally suggest "linked list"? Also, doesn't it conflict with java.awt.List?

    People were evenly divided as to whether List suggests linked lists. Given the implementation naming convention, <Implementation><Interface>, there was a strong desire to keep the core interface names short. Also, several existing names (AbstractSequentialList, LinkedList) would have been decidedly worse if we changed List to Sequence. The naming conflict can be dealt with by the following incantation:

        import java.util.*;
    import java.awt.*;
    import java.util.List;   // Dictates interpretation of "List"

  2. Why don't you rename List's set method to replace, to avoid confusion with Set.

    It was decided that the "set/get" naming convention was strongly enough enshrined in the language that we'd stick with it.

Map Interface

  1. Why doesn't Map extend Collection?

    This was by design. We feel that mappings are not collections and collections are not mappings. Thus, it makes little sense for Map to extend the Collection interface (or vice versa).

    If a Map is a Collection, what are the elements? The only reasonable answer is "Key-value pairs", but this provides a very limited (and not particularly useful) Map abstraction. You can't ask what value a given key maps to, nor can you delete the entry for a given key without knowing what value it maps to.

    Collection could be made to extend Map, but this raises the question: what are the keys? There's no really satisfactory answer, and forcing one leads to an unnatural interface.

    Maps can be viewed as Collections (of keys, values, or pairs), and this fact is reflected in the three "Collection view operations" on Maps (keySet, entrySet, and values). While it is, in principle, possible to view a List as a Map mapping indices to elements, this has the nasty property that deleting an element from the List changes the Key associated with every element before the deleted element. That's why we don't have a map view operation on Lists.

Iterator Interface

  1. Why doesn't Iterator extend Enumeration?

    We view the method names for Enumeration as unfortunate. They're very long, and very frequently used. Given that we were adding a method and creating a whole new framework, we felt that it would be foolish not to take advantage of the opportunity to improve the names. Of course we could support the new and old names in Iterator, but it doesn't seem worthwhile.

  2. Why don't you provide an Iterator.peek method that allows you to look at the next element in an iteration without advancing the iterator?

    It can be implemented atop the current Iterators (a similar pattern to java.io.PushbackInputStream). We believe that its use would be rare enough that it isn't worth including in the interface that everyone has to implement.

Miscellaneous

  1. Why did you write a new collections framework instead of adopting JGL (a preexisting collections package from ObjectSpace, Inc.) into the JDK?

    If you examine the goals for our Collections framework (in the Overview), you'll see that we are not really "playing in the same space" as JGL. Quoting from the "Design Goals" Section of the Java Collections Overview: "Our main design goal was to produce an API that was reasonably small, both in size, and (more importantly) in 'conceptual weight.'"

    JGL consists of approximately 130 classes and interfaces; its main goal was consistency with the C++ Standard Template Library (STL). This was not one of our goals. Java has traditionally stayed away from C++'s more complex features (e.g., multiple inheritance, operator overloading). Our entire framework, including all infrastructure, contains approximately 25 classes and interfaces.

    While this may cause some discomfort for some C++ programmers, we feel that it will be good for Java in the long run. As the Java libraries mature, they inevitably grow, but we are trying as hard as we can to keep them small and manageable, so that Java continues to be an easy, fun language to learn and to use.

  2. Why don't you eliminate all of the methods and classes that return "views" (Collections backed by other collection-like objects). This would greatly reduce aliasing.

    Given that we provide core collection interfaces behind which programmers can "hide" their own implementations, there will be aliased collections whether the JDK provides them or not. Eliminating all views from the JDK would greatly increase the cost of common operations like making a Collection out of an array, and would do away with many useful facilities (like synchronizing wrappers). One view that we see as being particularly useful is List.subList. The existence of this method means that people who write methods taking List on input do not have to write secondary forms taking an offset and a length (as they do for arrays).

  3. Why don't you provide for "observable" collections that send out Events when they're modified?

    Primarily, resource constraints. If we're going to commit to such an API, it has to be something that works for everyone, that we can live with for the long haul. We may provide such a facility some day. In the meantime, it's not difficult to implement such a facility on top of the public APIs.

Copyright © 1997-1999 Sun Microsystems, Inc., 901 San Antonia Ave., Palo Alto, CA 94303 USA. All rights reserved.

Please send comments to: collections-comments@java.sun.com 		Sun
Java Software


The Collections Framework

 Documentation Contents
The collections framework is a unified architecture for representing and manipulating collections, allowing them to be manipulated independently of the details of their representation. It reduces programming effort while increasing performance. It allows for interoperability among unrelated APIs, reduces effort in designing and learning new APIs, and fosters software reuse. The framework is based on fourteen collection interfaces. It includes implementations of these interfaces, and algorithms to manipulate them.
Overview
  • Overview - An overview of the Collections framework.
API Specification
  • API Reference - An annotated outline of the classes and interfaces comprising the collections framework, with links into the JavaDoc.
Tutorials and Programmer's Guides
  • Tutorial - A tutorial introduction to the collections framework with plenty of programming examples.
API Enhancements
  • API Enhancements in Java SE 6 - An annotated list of API changes between the 5.0 and 6 releases.
  • API Enhancements in J2SE 5.0 - An annotated list of API changes between the 1.4 and 5.0 releases.
  • API Enhancements in J2SDK 1.4 - An annotated list of API changes between the 1.3 and 1.4 releases.
More Information
  • Design FAQ- Answers to frequently asked questions concerning the design of the collections framework.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: collections-comments@java.sun.com 		Sun
Java Software


Concurrency Utilities

 Documentation Contents
The Concurrency Utilities packages provide a powerful, extensible framework of high-performance threading utilities such as thread pools and blocking queues. This package frees the programmer from the need to craft these utilities by hand, in much the same manner the Collections Framework did for data structures. Additionally, these packages provide low-level primitives for advanced concurrent programming.

Overview

  • Overview - An overview of the Concurrency Utilities.

API Specification

  • java.util.concurrent Package (package description)
  • java.util.concurrent.atomic Package (package description)
  • java.util.concurrent.locks Package (package description)

Tutorial

  • Tutorial - Concurrency Lesson

More Information

  • Java Thread Primitive Deprecation
  • JSR 166 - Concurrency Utilities
  • Concurrent Programming in Java: Design Principles and Patterns

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: collections-comments@java.sun.com 		Sun
Java Software


Concurrency Utilities Overview

Java

Concurrency Utilities
Overview

Introduction

The Java 2 platform includes a new package of concurrency utilities. These are classes which are designed to be used as building blocks in building concurrent classes or applications. Just as the Collections Framework greatly simplified the organization and manipulation of in-memory data by providing implementations of commonly used data structures, the Concurrency Utilities aims to simplify the development of concurrent classes by providing implementations of building blocks commonly used in concurrent designs. The Concurrency Utilities include a high-performance, flexible thread pool; a framework for asynchronous execution of tasks; a host of collection classes optimized for concurrent access; synchronization utilities such as counting semaphores; atomic variables; locks; and condition variables.

Using the Concurrency Utilities, instead of developing components such as thread pools yourself, offers a number of advantages:

  • Reduced programming effort. It is far easier to use a standard class than to develop it yourself.
  • Increased performance. The implementations in the Concurrency Utilities were developed and peer-reviewed by concurrency and performance experts; these implementations are likely to be faster and more scalable than a typical implementation, even by a skilled developer.
  • Increased reliability. Developing concurrent classes is difficult -- the low-level concurrency primitives provided by the Java language (synchronized, volatile, wait(), notify(), and notifyAll()) are difficult to use correctly, and errors using these facilities can be difficult to detect and debug. By using standardized, extensively tested concurrency building blocks, many potential sources of threading hazards such as deadlock, starvation, race conditions, or excessive context switching are eliminated. The concurrency utilities have been carefully audited for deadlock, starvation, and race conditions.
  • Improved maintainability. Programs which use standard library classes are easier to understand and maintain than those which rely on complicated, homegrown classes.
  • Increased productivity. Developers are likely to already understand the standard library classes, so there is no need to learn the API and behavior of ad-hoc concurrent components. Additionally, concurrent applications are far simpler to debug when they are built on reliable, well-tested components.

In short, using the Concurrency Utilities to implement a concurrent application can help you make your program clearer, shorter, faster, more reliable, more scalable, easier to write, easier to read, and easier to maintain.

The Concurrency Utilities includes:

  • Task Scheduling Framework - The Executor framework is a framework for standardizing invocation, scheduling, execution, and control of asynchronous tasks according to a set of execution policies. Implementations are provided that allow tasks to be executed within the submitting thread, in a single background thread (as with events in Swing), in a newly created thread, or in a thread pool, and developers can create customized implementations of Executor supporting arbitrary execution policies. The built-in implementations offer configurable policies such as queue length limits and saturation policy which can improve the stability of applications by preventing runaway resource consumption.
  • Concurrent Collections - Several new Collections classes have been added, including the new Queue, BlockingQueue and BlockingDeque interfaces, and high-performance, concurrent implementations of Map, List, and Queue. See the Collections Framework Guide for more details.
  • Atomic Variables - Classes for atomically manipulating single variables (primitive types or references), providing high-performance atomic arithmetic and compare-and-set methods. The atomic variable implementations in java.util.concurrent.atomic offer higher performance than would be available by using synchronization (on most platforms), making them useful for implementing high-performance concurrent algorithms as well as conveniently implementing counters and sequence number generators.
  • Synchronizers - General purpose synchronization classes, including semaphores, mutexes, barriers, latches, and exchangers, which facilitate coordination between threads.
  • Locks - While locking is built into the Java language via the synchronized keyword, there are a number of inconvenient limitations to built-in monitor locks. The java.util.concurrent.locks package provides a high-performance lock implementation with the same memory semantics as synchronization, but which also supports specifying a timeout when attempting to acquire a lock, multiple condition variables per lock, non-nested ("hand-over-hand") holding of multiple locks, and support for interrupting threads which are waiting to acquire a lock.
  • Nanosecond-granularity timing - The System.nanoTime method enables access to a nanosecond-granularity time source for making relative time measurements, and methods which accept timeouts (such as the BlockingQueue.offer, BlockingQueue.poll, Lock.tryLock, Condition.await, and Thread.sleep) can take timeout values in nanoseconds. The actual precision of System.nanoTime is platform-dependent.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


Java Thread Primitive Deprecation

Why is Thread.stop deprecated?

Because it is inherently unsafe. Stopping a thread causes it to unlock all the monitors that it has locked. (The monitors are unlocked as the ThreadDeath exception propagates up the stack.) If any of the objects previously protected by these monitors were in an inconsistent state, other threads may now view these objects in an inconsistent state. Such objects are said to be damaged. When threads operate on damaged objects, arbitrary behavior can result. This behavior may be subtle and difficult to detect, or it may be pronounced. Unlike other unchecked exceptions, ThreadDeath kills threads silently; thus, the user has no warning that his program may be corrupted. The corruption can manifest itself at any time after the actual damage occurs, even hours or days in the future.

Couldn't I just catch the ThreadDeath exception and fix the damaged object?

In theory, perhaps, but it would vastly complicate the task of writing correct multithreaded code. The task would be nearly insurmountable for two reasons:

  1. A thread can throw a ThreadDeath exception almost anywhere. All synchronized methods and blocks would have to be studied in great detail, with this in mind.
  2. A thread can throw a second ThreadDeath exception while cleaning up from the first (in the catch or finally clause). Cleanup would have to repeated till it succeeded. The code to ensure this would be quite complex.
In sum, it just isn't practical.

What about Thread.stop(Throwable)?

In addition to all of the problems noted above, this method may be used to generate exceptions that its target thread is unprepared to handle (including checked exceptions that the thread could not possibly throw, were it not for this method). For example, the following method is behaviorally identical to Java's throw operation, but circumvents the compiler's attempts to guarantee that the calling method has declared all of the checked exceptions that it may throw:

    static void sneakyThrow(Throwable t) {
        Thread.currentThread().stop(t);
    }

What should I use instead of Thread.stop?

Most uses of stop should be replaced by code that simply modifies some variable to indicate that the target thread should stop running. The target thread should check this variable regularly, and return from its run method in an orderly fashion if the variable indicates that it is to stop running. To ensure prompt communication of the stop-request, the variable must be volatile (or access to the variable must be synchronized).

For example, suppose your applet contains the following start, stop and run methods:

    private Thread blinker;

    public void start() {
        blinker = new Thread(this);
        blinker.start();
    }

    public void stop() {
        blinker.stop();  // UNSAFE!
    }

    public void run() {
        Thread thisThread = Thread.currentThread();
        while (true) {
            try {
                thisThread.sleep(interval);
            } catch (InterruptedException e){
            }
            repaint();
        }
    }
You can avoid the use of Thread.stop by replacing the applet's stop and run methods with:
    private volatile Thread blinker;

    public void stop() {
        blinker = null;
    }

    public void run() {
        Thread thisThread = Thread.currentThread();
        while (blinker == thisThread) {
            try {
                thisThread.sleep(interval);
            } catch (InterruptedException e){
            }
            repaint();
        }
    }

How do I stop a thread that waits for long periods (e.g., for input)?

That's what the Thread.interrupt method is for. The same "state based" signaling mechanism shown above can be used, but the state change (blinker = null, in the previous example) can be followed by a call to Thread.interrupt, to interrupt the wait:

    public void stop() {
        Thread moribund = waiter;
        waiter = null;
        moribund.interrupt();
    }
For this technique to work, it's critical that any method that catches an interrupt exception and is not prepared to deal with it immediately reasserts the exception. We say reasserts rather than rethrows, because it is not always possible to rethrow the exception. If the method that catches the InterruptedException is not declared to throw this (checked) exception, then it should "reinterrupt itself" with the following incantation:
    Thread.currentThread().interrupt();
This ensures that the Thread will reraise the InterruptedException as soon as it is able.

What if a thread doesn't respond to Thread.interrupt?

In some cases, you can use application specific tricks. For example, if a thread is waiting on a known socket, you can close the socket to cause the thread to return immediately. Unfortunately, there really isn't any technique that works in general. It should be noted that in all situations where a waiting thread doesn't respond to Thread.interrupt, it wouldn't respond to Thread.stop either. Such cases include deliberate denial-of-service attacks, and I/O operations for which thread.stop and thread.interrupt do not work properly.

Why are Thread.suspend and Thread.resume deprecated?

Thread.suspend is inherently deadlock-prone. If the target thread holds a lock on the monitor protecting a critical system resource when it is suspended, no thread can access this resource until the target thread is resumed. If the thread that would resume the target thread attempts to lock this monitor prior to calling resume, deadlock results. Such deadlocks typically manifest themselves as "frozen" processes.

What should I use instead of Thread.suspend and Thread.resume?

As with Thread.stop, the prudent approach is to have the "target thread" poll a variable indicating the desired state of the thread (active or suspended). When the desired state is suspended, the thread waits using Object.wait. When the thread is resumed, the target thread is notified using Object.notify.

For example, suppose your applet contains the following mousePressed event handler, which toggles the state of a thread called blinker:

    private boolean threadSuspended;

    Public void mousePressed(MouseEvent e) {
        e.consume();

        if (threadSuspended)
            blinker.resume();
        else
            blinker.suspend();  // DEADLOCK-PRONE!

        threadSuspended = !threadSuspended;
    }
You can avoid the use of Thread.suspend and Thread.resume by replacing the event handler above with:
    public synchronized void mousePressed(MouseEvent e) {
        e.consume();

        threadSuspended = !threadSuspended;

        if (!threadSuspended)
            notify();
    }
and adding the following code to the "run loop":
                synchronized(this) {
                    while (threadSuspended)
                        wait();
                }
The wait method throws the InterruptedException, so it must be inside a try ... catch clause. It's fine to put it in the same clause as the sleep. The check should follow (rather than precede) the sleep so the window is immediately repainted when the the thread is "resumed." The resulting run method follows:
    public void run() {
        while (true) {
            try {
                Thread.currentThread().sleep(interval);

                synchronized(this) {
                    while (threadSuspended)
                        wait();
                }
            } catch (InterruptedException e){
            }
            repaint();
        }
    }
Note that the notify in the mousePressed method and the wait in the run method are inside synchronized blocks. This is required by the language, and ensures that wait and notify are properly serialized. In practical terms, this eliminates race conditions that could cause the "suspended" thread to miss a notify and remain suspended indefinitely.

While the cost of synchronization in Java is decreasing as the platform matures, it will never be free. A simple trick can be used to remove the synchronization that we've added to each iteration of the "run loop." The synchronized block that was added is replaced by a slightly more complex piece of code that enters a synchronized block only if the thread has actually been suspended:

                if (threadSuspended) {
                    synchronized(this) {
                        while (threadSuspended)
                            wait();
                    }
                }

In the absence of explicit synchronization, threadSuspended must be made volatile to ensure prompt communication of the suspend-request.

The resulting run method is:
    private boolean volatile threadSuspended;

    public void run() {
        while (true) {
            try {
                Thread.currentThread().sleep(interval);

                if (threadSuspended) {
                    synchronized(this) {
                        while (threadSuspended)
                            wait();
                    }
                }
            } catch (InterruptedException e){
            }
            repaint();
        }
    }

Can I combine the two techniques to produce a thread that may be safely "stopped" or "suspended"?

Yes; it's reasonably straightforward. The one subtlety is that the target thread may already be suspended at the time that another thread tries to stop it. If the stop method merely sets the state variable (blinker) to null, the target thread will remain suspended (waiting on the monitor), rather than exiting gracefully as it should. If the applet is restarted, multiple threads could end up waiting on the monitor at the same time, resulting in erratic behavior.

To rectify this situation, the stop method must ensure that the target thread resumes immediately if it is suspended. Once the target thread resumes, it must recognize immediately that it has been stopped, and exit gracefully. Here's how the resulting run and stop methods look:

    public void run() {
        Thread thisThread = Thread.currentThread();
        while (blinker == thisThread) {
            try {
                thisThread.sleep(interval);

                synchronized(this) {
                    while (threadSuspended && blinker==thisThread)
                        wait();
                }
            } catch (InterruptedException e){
            }
            repaint();
        }
    }

    public synchronized void stop() {
        blinker = null;
        notify();
    }
If the stop method calls Thread.interrupt, as described above, it needn't call notify as well, but it still must be synchronized. This ensures that the target thread won't miss an interrupt due to a race condition.

What about Thread.destroy?

Thread.destroy has never been implemented. If it were implemented, it would be deadlock-prone in the manner of Thread.suspend. (In fact, it is roughly equivalent to Thread.suspend without the possibility of a subsequent Thread.resume.) We are not implementing it at this time, but neither are we deprecating it (forestalling its implementation in future). While it would certainly be deadlock prone, it has been argued that there may be circumstances where a program is willing to risk a deadlock rather than exit outright.

Why is Runtime.runFinalizersOnExit deprecated?

Because it is inherently unsafe. It may result in finalizers being called on live objects while other threads are concurrently manipulating those objects, resulting in erratic behavior or deadlock. While this problem could be prevented if the class whose objects are being finalized were coded to "defend against" this call, most programmers do not defend against it. They assume that an object is dead at the time that its finalizer is called.

Further, the call is not "thread-safe" in the sense that it sets a VM-global flag. This forces every class with a finalizer to defend against the finalization of live objects!

Copyright © 1995-99 Sun Microsystems, Inc. All Rights Reserved.

Suggest a feature or make comments

Java Software


Deployment Enhancements in Java SE 6

  • Java Web Start and Java Plug-in Common Enhancements
    • Cache and System Format
    • Download Engine and Cache Consolidation
    • Secure Versioning
    • Other Enhancements

Java Web Start and Java Plug-in Common Enhancements

Cache and System Format

The format of the cache is completely changed and should never be assumed. Any existing code using the previous cache format for Java Web Start or Java Plug-in will no longer work. Existing applications in the Java Web Start cache will be upgraded and converted to the new cache format the first time you run a Java Web Start application, or if you launch the cache viewer using javaws -viewer.

The system cache will be upgraded and converted to the new format the first time you launch Java Web Start in system mode, or if you just launch javaws -system.

Download Engine and Cache Consolidation

The caching mechanism and download engine are redesigned and consolidated between Java Web Start and Java Plug-in. This brings several new features to Java Web Start, previously available only in Java Plug-in and vice versa. They are :

  • Caching can be disabled using the Java Control Panel.
  • Java Web Start honors the maximum cache size set using Java Control Panel.
  • Java Web Start can start a cleanup thread to remove Least Recently Used(LRU) items from the cache when approaching the maximum cache size.
  • The <no-cache> directive is now supported. When the no-cache directive is used , an update check is made to make sure the cached contents are same as at the URL. The resource is then downloaded into the cache and the expiration field is ignored.
  • The expiration-date is supported. If a downloaded resource contains an expiration date, it will not be used after that date.

Secure Versioning

In Java SE 6 unsigned Java Web Start applications that specify a version other than the latest one will trigger a security warning, requiring explicit user permission before the application will run. Signed Java Web Start applications are not affected.

Other Enhancements

Java Web Start and Java Plug-in now support CRL (Certificate Revocation Lists) and OCSP (Online Certificate Status Protocol) for verifying the certificates.

Java Control Panel provides an option to select the default SSL handshaking protocol. The default is set to SSLv3 and SSLv2. You can also change it to TSL.

The Java Console is excluded from modality. By using the new modality features of AWT in Java 6, you can interact with Java Console even when your application is displaying a modal dialog.

All dialogs and screens of Java Web Start and Java Plug-in are redesigned to be more user friendly, intuitive, and accessible.


General Deployment Enhancements in J2SE 5.0

  • Much of the common functionality between Java Plug-in and Java Web Start has been combined. There is now a single Java Control Panel for both. It replaces both the Java Plug-in Control Panel and the Preference panel of the Java Web Start Application Manager. The settings are used in both products. (4667682)

  • Security: (1) This release features improved security access and control, including both user- and system-level security options and an expanded list of deployment properties. (4667645) (2) Several new configuration properties have been added so that an enterprise can customize user security settings. These allow control of what applications a user is allowed to grant trust to, and what permissions are given to code for which trust is granted. Also, a user or enterprise can configure what information is to be displayed on security warnings; and an enterprise can configure if a user is allowed to run applications in the enhanced sandbox of the JNLP API. An enterprise can also pre-accept its own certificates so that users will not see any security warnings in its own applications.

  • Enterprise Configuration: Both deployment products can now be configured with an enterprise configuration file. This file, accessed as a URL, can set any set of configuration properties, either as defaults, or as locked properties which cannot be overridden by the user.

  • Support is available for pack/crunch compression for downloading Java applications and applets. Pack200, a new hyper-compression format for JAR files defined by JSR-200, can reduce the download size of JNLP applications and Java Plug-in applets. File size can be reduced to about 1/8th of the original size. (4666040)

  • Support of browser keystores in Internet Explorer and Mozilla in Java Plug-in and Web Start: Certificates and keys in browser keystores will be used for signing verification, HTTPS server authentication, and HTTPS client authentication. Certificates and keys on the smart card exposed in the browser keystore will also be recognized. See Browser Keystores for more information. (4480333, 4957907)

  • Support of time-stamped, signed JAR files: With time-stamping now built into the signing tool, Java Plug-in and Java Web Start now recognize the time-of-signing information when they verify a signed JAR file. This solves the problem of a signed applet signed with a valid certificate at time-of-signing but the certificate expired later after the applet deployment. (4649690)

  • Support of Client Authentication in HTTPS: This release provides interactive user interface in Java Plug-in and Java Web Start during HTTPS client authentication for users to select the personal certificate from the personal keystore. (4802844)


Java (TM) Deployment

Java

JavaTM Deployment

 Documentation Contents

For new features and enhancement in Java Deployment for Java SE 6, see Deployment Enhancements in Java SE 6.

JavaTM Deployment is a broad-ranging topic, including the following:

  • Installation of the Java Platform on a computer
  • Setting options in the Java Control Panel
  • Writing applications and applets in the Java Programming language
  • Authoring web pages that invoke applets or download and launch applications
  • Making Java-related files available on web servers
  • Updating the Java Platform on a computer

Some of these topics, such as setting options in the Java Control Panel and updating the Java Platform on a computer, are covered in the Java Deployment Guide mentioned below; others, such as Installation of the Java Platform and writing applications and applets, are covered elsewhere. For a more detailed description of the topics listed above, see the Overview in the Java Deployment Guide.

Java Deployment Guide

The Java Deployment Guide provides an overview of Java Deployment; describes the Java Control Panel, the Java Update mechanism, applet compatibility issues related to the Microsoft versus Sun VM, silent installation for Windows, and autodownload; and includes an installation and update FAQ.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: java-deployment-feedback@sun.com 		Sun
Java Software


Applet Caching

Applet Caching in Java Plug-in

Applet caching ensures that applets are not unnecessarily downloaded by a browser every time a user references them. Java Plug-in has supported caching in previous versions by using the same cache the browser uses for all other web documents.

This works for casual applet usage, but larger applets can often get flushed from the cache to make room for other documents since the browser has no knowledge that an applet file might be needed in the future. The result is that this caching strategy fails where is needed most in large business applets.

This release introduces an alternative form of applet caching which allows an applet deployer to decide her applet should be "sticky", that is, to stay on the disk in a secondary cache which the browser cannot overwrite. The only time "sticky" applets get downloaded after that is when they are updated on their server. Otherwise the applet is always available for quick loading. We recommend that applets which provide core business applications be made sticky to improve their startup performance.

This new feature is activated by including the new PARAM NAME="cache_option" and PARAM NAME="cache_archive" values in the tag that specifies the use of Java Plug-in as below:

<OBJECT ....>
     <PARAM NAME="archive" VALUE="...">
     ....
     <PARAM NAME="cache_option" VALUE="...">
     <PARAM NAME="cache_archive" VALUE="...">
</OBJECT>

The cache_option attribute can take one of three values:

No
Disable applet installation. Always download the file from the web server.

Browser
Run applets from the browser cache (default).

Plugin
Run applets from the new Java Plug-in cache.

The cache_archive attribute contains a list of the files to be cached:

<PARAM NAME="cache_archive" VALUE="a.jar,b.jar,c.jar">

Like the archive attribute in the APPLET tag, the list of jar files in the cache_archive attribute do not contain the full URL, but are always downloaded from the codebase specified in the EMBED/OBJECT tag.

Note that the list of JAR files in the cache_archive attribute and those in the archive attribute may be similar but should not contain the same JAR files. There are two possible cases:

  1. A JAR file is listed in cache_archive but not in archive. In this case, the JAR file is cached according to cache_option.

  2. A JAR file is listed in archive but not in cache_archive. In this case, the JAR file is cached using the native browser cache. This guarantees a minimum of caching.
cache_option and cache_archive can only be specified once per EMBED/OBJECT tag. In addition, both attributes must be specified. If either cache_archive or cache_option are missing, Java Plug-in will treat the applet normally using the archive attribute.

Note: Caching of the JAR files specified in the manifest's CLASSPATH variable using Java Plug-in's cache is currently not supported.


Applet Compatibility -- Microsoft vs Java 2 Virtual Machine

Applet Compatibility Issues

This document describes all known applet compatibility issues between the Microsoft Virtual Machine (VM) and the Sun Java VM. The term Java SE used here refers to the Java Platform Standard Edition version 1.2 or later.

ClassFormatError

This error is caused by bytecode generated from old JDK 1.0.2 or 1.1 compilers. In the past, a lot of these compilers generated bytecode that does not conform to the Java VM Specification. Since the verifiers in recent J2SE releases are much stricter about bad class format, the ClassFormatError is thrown by the VM when these bad class files are loaded.

Some typical problems in some older class files are the following (note that this list is not exhaustive):

  • There are extra bytes at the end of the class file;
  • The class file contains method or field names that do not begin with a letter;
  • The class attempts to access private members of another class;
  • The class file has other format errors, including illegal constant pool indices and illegal UTF-8 strings;
  • Some early (third-party) bytecode obfuscators produced class files that violated proper class-file format.

You can avoid this type of problem by recompiling your classes with the Javac bytecode compiler from the current JDK. If you choose to use a third-party obfuscator, be sure to use one that produces class files that respect proper class-file format.

To allow some of the applets with bad class files to run in Java SE, Java Plug-in contains a bytecode transformer to transform some of the bad class files to good ones. Currently, only bad class files with the following ClassFormatError may be transformed:

  • Local variable name has bad constant pool index
  • Extra bytes at the end of the class file
  • Code segment has wrong length
  • Illegal Field/Method name
  • Illegal Field/Method modifiers
  • Invalid start_pc/length in local var table

Unfortunately, the following ClassFormatError problems are not fixable by the bytecode transformer:

  • Illegal use of nonvirtual function call
  • Arguments can't fit into locals
  • Unsorted lookup switch
  • Truncated class file

Thus, any class file having any of these problems will not run under Java SE:

Security exception with sun.audio

The sun.audio package was accessible by applets in JDK 1.1. However, in Java SE the applet sandbox was closed up. Thus, applets trying to access any class libraries in the sun.audio package will result in SecurityException.

To provide maximum applet compatibility, the applet sandbox in Java Plug-in has been opened up to allow applets to again access the sun.audio package.

Unable to find resources from AppletContext.getAudioClip() and AppletContext.getImage()

For the Microsoft and Sun implementations, the resource lookup sequence in AppletContext.getImage() and AppletContext.getAudioClip() is different.

In the Microsoft implementation, resources are looked up in the following sequence:

  1. Archives specified through HTML archive or cabbase parameters
  2. codebase URL

In the Sun implementation, resources are looked up simply by codebase URL.

As a result, some applets relying on the resources lookup sequence of the Microsoft VM may not load resources properly in Java SE.

To provide maximum applet compatibility, the resources lookup sequence in Java Plug-in has been changed as follows:

  1. Archives specified through HTML archive parameters
  2. codebase URL

ClassLoader sharing policy

The ClassLoader sharing policy is different in the Microsoft and Sun implementations.

In the Microsoft implementation, a ClassLoader object is shared between applets if and only if:

  • codebase values are the same,
  • archive values are the same, and
  • cabbase values are the same.

In the Sun implementation, a ClassLoader object is shared between applets if and only if codebase values are the same.

Some applets relying on the ClassLoader sharing policy of the Microsoft implementation may not run properly in Java SE because of potential class definition conflicts.

To provide maximum applet compatibility, the ClassLoader sharing policy in Java Plug-in has been changed. A ClassLoader object is now shared between applets if and only if:

  • codebase values are the same,
  • cache_archive values are the same,
  • java_archive values are the same, and
  • archive values are the same.

Security model—Java SE VS Microsoft

Java SE has a new security model which provides much more capability and flexibility than JDK 1.1, while Microsoft's VM security model is based on JDK 1.1 and its own proprietary technologies.

This issue is not fixable. Thus, an applet that relies on the Microsoft's security model will not run properly in Java SE.

Applet packaging

Applet packaging in Java SE and JDK 1.1 is through .jar files, whereas the Microsoft VM supports applet packaging through .jar files and its own proprietary .cab (cabinet) files.

This issue is not fixable. Thus, an applet packaged in Microsoft .cab file format will not be loaded in Java SE.

Java language specification strictness (null vs zero-length string)

In JDK 1.1 the Java language specification was loose in dealing with null and zero-length strings in the class libraries. Some APIs may treat a zero-length string as null, while other APIs may treat null as it is. In Java SE, the Java language specification has been tightened up to specify what the exact behavior should be.

This issue is not fixable. Thus, in Java SE an applet that relies on the APIs to treat null as a zero-length string may result in an exception.

Applet signing—RSA vs Authenticode

In Java SE, applet signing is supported through RSA and the .jar file, whereas Microsoft supports applet signing through its own proprietary Authenticode and .cab file technologies.

This issue is not fixable. Thus an applet that relies on Microsoft's Authenticode and .cab file technologies may not load properly in Java SE.

Implementation changes in AWT class libraries

In the past, some programmers assumed that AWT was thread safe. Therefore some applets were written using AWT libraries that interacted with the GUI in multiple threads, assuming that the class libraries took care of synchronization issues. In fact, neither AWT nor Swing are thread safe. Therefore, all code that updates the GUI or processes events should occur on the event dispatching thread. Failure to do so may result in a deadlock or race condition. For more information, see How to Use Threads in The Swing Tutorial. Although this tutorial specifically covers Swing, in this instance, the same rules apply to all Components.

Java/JavaScript communication

In the Microsoft implementation, an applet's methods and properties exposed in JavaScript in an HTML page are exactly the same as the methods and properties of the applet object. In Java Plug-in, an applet's methods and properties are exposed in JavaScript in an HTML page through JavaBeans Introspection, which analyzes methods and properties through naming conventions in the applet object. The side effect is that applet's fields are treated differently.

This problem will be fixed in a future release of Java Plug-in. In the meantime, JavaScript access to fields in the applet object may not work properly in Java SE.

Microsoft proprietary Java classes, methods, and variables

Microsoft has provided many proprietary class libraries in its VM implementation, including J/Direct, AFC, WFC, etc. For other classes, methods, and variables, see How to avoid potential pitfalls of Microsoft's non-standard SDK for Java.

This issue is not fixable. Thus, applets that rely on any of the Microsoft proprietary Java class libraries will not work properly in Java SE.

Whitespace characters in strings returned from Applet.getParameter()

In the Microsoft implementation, whitespace characters are stripped off before the string is returned to an applet in Applet.getParameter(). On the other hand, Sun's implementation returns the string as it is specified in the HTML parameters. As a result, some JDK 1.1 applets refuse to run in Java SE because the applet's logic doesn't take the whitespace into account.

To provide maximum applet compatibility, the implementation of Applet.getParameter() in Java Plug-in has been changed to strip off whitespace characters in the return value.

Design changes in java.util.Hashtable.hashCode()

In JDK 1.1, Hashtable.hashCode() was implemented based on the object identity; thus, each Hashtable object returns its unique value when hashCode() is called. In Java SE, the implementation of Hashtable.hashCode() was changed to be value-based as part of the Java Collection Framework. A Hashtable object returns its hashcode value based on the objects it contains.

This change breaks some JDK 1.1 applets if they add a Hashtable object into itself, which breaks the fundamental design of the Collection Framework and causes StackOverflowError. It breaks logic in some applet code that relies on Hashtable.hashCode() to return a constant value from the same Hashtable object.

To provide maximum applet compatibility, the implementation of Hashtable.hashCode() has been changed to check for this special case to avoid stack overflow.

Accessing frame from applet

To track mouse events or for some other reasons, an applet may sometimes try to access its frame . In the Microsoft and Sun implementations, the number of containers between the frame and the applet is different.

An applet that relies on a frame being at a particular level of containment in the Microsoft VM, without navigating the entire AWT hierarchical component tree, is likely to fail in Java SE. The most common symptom is ClassCastException from the AWT Dispatch Event Thread.

This issue is not fixable. Thus, an applet with this issue may not run properly in Java SE.

MAYSCRIPT

In Netscape Navigator and Java Plug-in, an applet accessing JavaScript is required to specify the MAYSCRIPT attribute in the applet element. Microsoft's implementation, however, doesn't honor this special parameter; it allows an applet to access JavaScript under all conditions. Since most of Internet applets target Microsoft's VM instead of Netscape's, MAYSCRIPT is not specified in these applets.

To provide maximum applet compatibility, the MAYSCRIPT check has been removed from Java Plug-in.

HTTP User-Agent

In the Microsoft and Sun implementations, different HTTP User-Agent strings are passed to the server when an HTTP connection is requested. Most web sites target Microsoft's VM instead of Sun's and do not recognize Sun's HTTP User-Agent.This may result in failure.

For that reason, the HTTP User-Agent string used in Java Plug-in has been made similar to the Microsoft one. Thus, most web servers will recognize requests made from applets running in Java Plug-in.

Events during applet startup and shutdown

In the Microsoft and Sun implementations, the events occurring during applet startup and shutdown may not be exactly the same. For example, the logic in the applet may rely on the applet being visible when Applet.start() or Applet.stop() is called, which may be true in the Microsoft implementation but not in Sun implementation.

An applet that relies on specific events during applet startup and shutdown in the Microsoft VM may not function properly in Java SE. The most common symptom is NullPointerException from the AWT Dispatch Event Thread.

This issue is not fixable.

Java class libraries compatibility

There are many changes in the Java class libraries and Java SE. Some APIs are clarified, some are depreciated, and some have altered implementations. The following have caused some applets run in the Microsoft VM to fail in Java SE:

  • java.awt.Graphics.drawString()

    drawString() treats null as an empty string in the Microsoft VM. In Java SE, drawString() treats null as it is and throws NullPointerException.
  • java.awt.Graphics.drawImage()

    drawImage() ignores null image in the Microsoft VM. In Java SE, drawImage() treats null as it is and throws NullPointerException.
  • java.awt.Color constructors

    In the Microsoft VM, passing over-bound/under-bound values in the Color constructor will cause the VM to print out a warning message in the console, but the values will be reset to max/min automatically. In Java SE, Color constructor checks for illegal values and throws IllegalArgumentException.
  • Thread.stop(), Thread.suspend(), Thread.resume()

    In the Microsoft VM, stopping, suspending, or resuming a dead thread will cause the call to be ignored. In Java SE, calling these methods on a dead thread will result in AccessControlException.

Applets affected by these issues will result in exceptions and may not run properly in Java SE.

Java Moniker

This is a proprietary Microsoft technology that is not supported by Java SE.

object attribute with PARAM element

With the conventional applet format, use of an attribute named object with a PARAM element will cause an exception with the Sun VM: 'Either "code" or "object" should be specified, but not both.' With the Microsoft VM, no exception will be thrown. This is a compatibility issue. To avoid the exception with the Sun VM, do not use an attribute named object with a PARAM element in an applet.


Autodownload

Auto Download of the Java Platform

The Windows releases of Java Plug-in and Java Web Start make use of the codebase attribute of the OBJECT element to autodownload and install a particular version of the JRE. See:

  • Auto download with Java Plug-in
  • Auto download with Java Web Start

By specifying a particular .cab file in the codebase, a particular version of the JRE can be automatically downloaded and installed as required by an applet or application. For a list of the available .cab files, see Autodownload Files. Note that not every release of the JRE has an associated .cab file for autodownload.

For additional information read the technical article on Auto Install.


Autodownload Files

Autdownload Files (Windows Only)

The table below lists various JRE releases and the .cab files that can be used for autodownloading them. Note that not every release of the JRE has an associated .cab file for autodownload.

JRE Release | .cab File for codebase attribute for Autodownload
1.3.0_05 | http://java.sun.com/products/plugin/autodl/jinstall-1_3_0_05-win.cab
1.3.1_01 | http://java.sun.com/products/plugin/autodl/jinstall-1_3_1_01-win.cab
1.3.1_02 | http://java.sun.com/products/plugin/autodl/jinstall-1_3_1_02-win.cab
1.3.1_03 | http://java.sun.com/products/plugin/autodl/jinstall-1_3_1_03-win.cab
1.3.1_04 | http://java.sun.com/products/plugin/autodl/jinstall-1_3_1_04-win.cab
1.3.1_05 | http://java.sun.com/products/plugin/autodl/jinstall-1_3_1_05-windows-i586.cab
1.3.1_06 | http://java.sun.com/products/plugin/autodl/jinstall-1_3_1_06-windows-i586.cab
1.3.1_07 | http://java.sun.com/products/plugin/autodl/jinstall-1_3_1_07-windows-i586.cab
1.3.1_08 | http://java.sun.com/products/plugin/autodl/jinstall-1_3_1_08-windows-i586.cab
1.4.0 | http://java.sun.com/products/plugin/autodl/jinstall-1_4_0-win.cab
1.4.0_01 | http://java.sun.com/products/plugin/autodl/jinstall-1_4_0_01-win.cab
1.4.0_02 | http://java.sun.com/products/plugin/autodl/jinstall-1_4_0_02-win.cab
1.4.0_03 | http://java.sun.com/products/plugin/autodl/jinstall-1_4_0_03-win.cab
1.4.0_04 | http://java.sun.com/products/plugin/autodl/jinstall-1_4_0_04-win.cab
1.4.1 | http://java.sun.com/products/plugin/autodl/jinstall-1_4_1-windows-i586.cab
1.4.1_01 | http://java.sun.com/products/plugin/autodl/jinstall-1_4_1_01-windows-i586.cab
1.4.1_02 | http://java.sun.com/products/plugin/autodl/jinstall-1_4_1_02-windows-i586.cab
1.4.1_03 | http://java.sun.com/products/plugin/autodl/jinstall-1_4_1_03-windows-i586.cab
1.4.2 | http://java.sun.com/products/plugin/autodl/jinstall-1_4_2-windows-i586.cab
1.4.2_01 | http://java.sun.com/update/1.4.2/jinstall-1_4_2_01-windows-i586.cab
1.4.2_02 | http://java.sun.com/update/1.4.2/jinstall-1_4_2_02-windows-i586.cab
1.4.2_03 | http://java.sun.com/update/1.4.2/jinstall-1_4_2_03-windows-i586.cab
1.5.0 | http://java.sun.com/update/1.5.0/jinstall-1_5_0-windows-i586.cab


Contents

JavaTM Deployment Guide

Note: There are two ways to navigate this guide:

  • Search the guide
  • Select from the contents below

Java Deployment Overview

Overview

Installation

Automatic Download
Silent Installation
 Deployment with Active Directory

Deployment

Java Plug-in
Java Web Start
Security

Security
JAR Signing
JAR Signing with Timestamp
Browser Keystores

Networking

Proxy Configuration
Cookie Support
Pack200 and Compression

Configuration

Deployment Configuration File and Properties
Java Control Panel

Debugging

Java Console
 Tracing and Logging

Update

Java Update

Appendices

Appendix 1: Windows Online Installation and Java Update FAQ
 Appendix 2: Sun-Supported Specification-Version and Implemenation-Version Formats
Appendix 3: Applet Tag
Appendix 4: Applet Caching
Appendix 5: Applet Compatibility Issues
Appendix 6: Java Upgrade: Upgrading from the Microsoft VM to the Sun Java Virtual Machine
Appendix 7: Java Upgrade: System-Wide Repository


Cookie Support

Cookie Support includes the following topics:

  • Introduction
  • Cookie Support in Java Plug-in and Java Web Start
  • Programmatic Access to Cookies
  • More Information

Introduction

Cookies are a way of storing data on the client side. They have been used extensively for personalization of portal sites, user preference tracking, and logging into web sites. For enterprise customers using cookies in their web sites, cookie support in Java Plug-in and Java Web Start facilitates deployment of client-side Java.

Cookie support allows a Java application to pass a cookie back to a web server if that cookie originated from the web server. This provides the server with information about the state of the client.

Cookie Support in Java Plug-in and Java Web Start

There are two main types of cookies: Session Cookies and Permanent Cookies.

Session Cookies

Session cookies are stored in memory during the applet or application session. Session cookies expire when the applet or application exits and are automatically deleted. These cookies usually store a session ID that is not personally identifiable to users, allowing the user to move from page to page without having to log-in repeatedly. They are widely used by commercial web sites (for example, to keep track of items that a consumer has added to a shopping cart.)

Permanent Cookies

Permanent cookies are stored in persistent storage and are not deleted when the application exits. They are deleted when they expire. They can retain user preferences for a particular web site, allowing those preferences to be used in future sessions. Permanent cookies can be used to identify individual users, so they may be used by web sites to analyze users' surfing behavior within the web site. These cookies can also be used to provide information about the numbers of visitors, the average time spent on a particular page, and the general performance of the web site. They are usually configured to keep track of users for a prolonged period of time, in some cases many years into the future.

Support

Java Plug-in and Java Web Start support handling of both types of cookie on all platforms.

Java Plug-in provides permanent cookie support using the underlying browser cookie store. When it runs in Internet Explorer, the cookie store in IE is used; when it runs in Mozilla, the cookie store in Mozilla is used. Because each browser has a different cookie policy, the cookie-handling behavior depends on the cookie control in the browser. For example, if the browser is configured to reject third-party cookies, the policy will apply to Java Plug-in when it runs in this browser.

Java Web Start provides permanent cookie support on Windows using the cookie store in Internet Explorer, and the cookie-handling behavior is determined by the cookie control in IE. On Linux/Solaris, Java Web Start provides permanent cookie support using its own cookie store implementation.

Programmatic Access to Cookies

There are several ways for an application to override the default cookie handling. Four are outlined below.

void URLConnection.setRequestProperty(String key, String value)

This approach allows the application to set a custom cookie header in URLConnection before making a connection.

URL url = new URL( "http://java.sun.com/" );
URLConnection conn = url.openConnection();
conn.setRequestProperty("Cookie", "foo=bar");
InputStream is = conn.getInputStream();
.....

When the connection is made, the custom cookie would be sent to the server in the HTTP/HTTPS request headers.

Map<String, List<String>> URLConnection.getHeaderFields()

After a connection is made, the server may return a cookie in the HTTP/HTTPS response headers. The approach outlined below allows the application to retrieve the cookie value through URLConnection.

URL url = new URL( "http://java.sun.com/" );
URLConnection conn = url.openConnection();
conn.connect();
.....
Map<String, List<String>> headers = conn.getHeaderFields();
List<String> values = headers.get("Set-Cookie");

String cookieValue = null;
for (Iterator iter = values.iterator(); iter.hasNext(); ) {
     String v = values.next();
     if (cookieValue == null)
         cookieValue = v;
     else
         cookieValue = cookieValue + ";" + v;
}

After the connection is made, the server may return the cookie in the HTTP/HTTPS response headers.

Map<String,List<String>> CookieHandler.get(URI uri, Map<String,List<String>> requestHeaders)

This approach allows the application to retrieve session/permanent cookies for a given URL:

String retrieveCookie(URL url)
{
     String cookieValue = null;

     CookieHandler handler = CookieHandler.getDefault();
     if (handler != null)    {
          Map<String, List<String>> headers = handler.get(url.toURI(), new Map<String,                                                           List<String>>());
          List<String> values = headers.get("Cookie");
          for (Iterator<String> iter=values.iterator(); iter.hasNext();) {
               String v = iter.next();

               if (cookieValue == null)
                    cookieValue = v;
               else
                    cookieValue = cookieValue + ";" + v;
          }
     }
     return cookieValue;
}

CookieHandler is an abstraction of the browser/system cookie storage, so additional security permission is required for execution; the above code will be executed successfully only if the application is trusted.

void CookieHandler.put(URI uri, Map<String,List<String>> responseHeaders)

This approach allows the application to set a session/permanent cookie for a given URL:

void setCookie(URL url, String value)
{
     CookieHandler handler = CookieHandler.getDefault();
     if (handler != null)    {
          Map<String, List<String>> headers= new Map<String, List<String>>();
          List<String> values = new List<String>();
          values.add(value);
          headers.put("Cookie", values);

          handler.put(url.toURI(), headers);
     }
}

CookieHandler is an abstraction of the browser/system cookie storage, so additional security permission is required for execution; the above code will be executed successfully only if the application is trusted.

More information

  • Persistent Client State - HTTP Cookies: http://wp.netscape.com/newsref/std/cookie_spec.html
  • Unofficial Cookie FAQ: http://www.cookiecentral.com/faq/


Extracting an .msi File for Active Directory Distribution

JRE Deployment with Active Directory

This procedure describes how to obtain the .msi file necessary to deploy the Java Runtime Environment (JRE) across a Windows 2000/Windows XP Active Directory-based network. It works for version 1.4.2 and later of the JRE installers. Sun includes an .msi (Microsoft Installer) file bundled up in the JRE Windows Offline installers. The .msi file extracted below can be assigned to an Active Directory software distribution policy.

  1. Download and launch the Sun JRE Windows Offline Installion executable (.exe) file.

  2. Retrieve the ".msi" file from the LocalAppData folder (the user's Application Data folder). The LocalAppData folder will differ for each Windows platform.

  3. Inside this folder you will find a folder named:
           {3248F0A6-6813-11D6-A77b-00B0D0150000}
    The first 2 digits are "71" for version 1.4.2_xx, and "32" for 1.5.0_xx. The last 6 digits of this CLSID and the name of the .msi file correspond to the release number. A CLSID ending with "150000" means version 1.5.0_00, and "142010" means verision 1.4.2_01

  4. From there, you can use Active Directory to distribute this .msi file to as many client Windows platforms as you want.

  5. If you want to register the JRE as the default VM of Internet Explorer and Mozilla, you will have to create a transform that will set the variables IEXPLORER and MOZILLA to 1 in the Property.idt table. You can find instructions on how to generate and use transforms at the Microsoft MSDN site.


Java Console

Java Console includes the following topics:

  • What is Java Console?
  • Debugging Options
  • Task-Bar Integration
  • Startup Behavior

What is Java Console?

Java Console is a simple debugging aid that redirects any System.out and System.err to the console window. It is available for applets running with Java Plug-in and applications running with Java Web Start.

Debugging Options

Java Console provides various options as shown below to make applet and application debugging easier.

An action/option is selected by typing its letter/number while the Java Console window has focus.

Key
Description
c: Clears the Java Console window.
f: Triggers finalization on the objects in the finalization queue and then displays memory information. Memory refers to the current heap size used by the JRE. Free is the available memory that is free in the heap. The percent (xx%) is the free memory as a percent of the total heap size.
g: Triggers garbage collection and displays memory information as described above.
h: Displays help message, which is being described here.
l: Displays a list of the cached ClassLoader objects in the Java Plug-in. (These are runtime objects cached in semiconductor memory, not on disk, and should not be confused with the cached JAR files mentioned in Applet Caching.) Classes are cached to avoid having to load them again when returning to previously-visited pages. When a page is visited the first time, a ClassLoader object will be created and all of the classes that are downloaded will be cached in that object. These objects are created and cached according to their codebase. To identify a ClassLoader object, the "classloader list" displays the codebase for that object. Additional information displayed with a ClassLoader object includes zombie, cache and info. zombie = true indicates that a ClassLoader object is not being used (i.e., the applet is not currently loaded on the page). cache = true indicates that the applet should be cached, while false indicates that the applet will be destroyed when the page is left. info is a value used for debugging.
m: Displays heap memory usage as described above.
o: Triggers logging, which directs output from the Java Plug-in Console to a log file.
p: Reloads the proxy configuration.
q: Causes the Java Console to disapper from the main screen.
r: Reloads the policy configuration.
s: Prints out the system properties. This is mostly for debugging.
t: Prints out all the existing thread groups. The first group shown is Group main. ac stands for active count; it is the total number of active threads in a thread group and its child thread groups. agc stands for active group count; it is the number of active child thread groups of a thread group. pri stands for priority; it is the priority of a thread group. Following Group main, other thread groups will be shown as Group <name>, where name is the URL associated with an applet. Individual listings of threads will show the thread name, the thread priority, alive if the thread is alive or destroyed if the thread is in the process of being destroyed, and daemon if the thread is a daemon thread.
x:

This removes (destroys) all ClassLoader objects in the cache.

Modified jar files will be downloaded from the server when a page with an applet is refreshed or revisited if you first do this: type "x" in the Java Console to clear the Classloader cache.
0-5: This sets the trace-level options as described in the next section, Tracing and Logging.

Task-Bar Integration

When Java Plug-in is running an icon is displayed—in the taskbar for Windows or on the desktop for Solaris. When right-clicked, a menu option displays, allowing the user to Open/Hide the Java Console. Thus the user can open and hide the Java Console any number of times within the same browser session.

Startup Behavior

Java Console may be shown, hidden, or not started at startup time, as configured through the Java Control Panel in the Advanced tab.


Java Control Panel

The Java Control Panel is a multipurpose control panel. It allows you to view and set a wide range of parameters controlling how Java runs on your computer. It lets you view and delete temporary files used for Java Plug-in, which allows Sun Java to be used by your web browser to run applets, and Java Web Start, which allows you to run Java applications over the network. It allows you to control certificates, making it safe to run applets and applications over the network. It allows you to set runtime parameters for applets run with Java Plug-in and applications run with Java Web Start. It provides a mechanism for updating your version of Java so that you always have the latest. And it allows you to set options for debugging, desktop integration, applet handling, etc. The Java Control Panel includes the following separately viewable panels:

  • General
  • Security
  • Java
  • Update
  • Advanced

Each is discussed below.

General

The General panel looks like this:

It includes three subpanels: About, Network Settings, and Temporary Internet Files.

About

The About... button displays version information for the latest JRE installed on the computer.

Network Settings Subpanel

These settings are for network connections. Press the Network Settings... button to get the Network Settings dialog. There are four choices:

Use browser settings

Check this to use the browser default proxy settings. This is the default setting (checked).

Use proxy server

You have two choices here:

  • You can set the Address and the Port for a proxy server with the option to bypass it for local addresses.
  • You can press the Advanced ... button to get the Advanced Network Settings dialog. In this panel you can individually set the proxy server for HTTP, Secure, FTP, and Socks connections. You can also provide a list of addresses for which you do not want to use a proxy server. The Advanced Network Settings panel looks like this:

Use automatic proxy configuration script

You can specify the location (URL) for the JavaScript file (.js or .pac extension) that contains the FindProxyForURL function. FindProxyForURL has the logic to determine the proxy server to use for a connection request.

Direct Connection

Select this for situations where you do not want to use a proxy.

Temporary Internet Files Subpanel

You can do the following:

  • Press the Delete Files... button to get the Delete Temporary Files dialog from which you can delete:
    • Downloaded Applets;
    • Downloaded Applications;
    • Other Files.
  • Press the Settings... button to get the Temporary Files Settings dialog from which you can:
      • Press the Delete Files... button (same as above) to get the Delete Temporary Files dialog, from which you can delete:
        • Downloaded Applets,
        • Downloaded Applications,
        • Other Files;
      • press the View Applications... button to get the Java JNLP Applications Viewer dialog, from which you can:
        • view and remove applications, applets, libraries, and installers,
        • launch online and offline applications, applets, and installers;
      • press the View Applets... button to view the Details - Cache dialog, from which you can view cached applet files, enable/disable caching in Java Plug-in, Delete cached files, and Refresh the viewer;
      • from the Settings subpanel, set the location, the amount of disk space, and the compression for .jar files.

Security

Notes

  1. Some information in this section depends on an understanding of System- and User-Level Properties Files. Please read that section.
  2. System-Level keystore files do not exist by default; they are created and managed by a System Administrator using keytool. (See Security Tools.)

The Security panel looks like this:

Press the Certificates... button to get the Certificates dialog, which looks like this:

Certificate Types

It handles both User- and System-Level (enterprise-wide) certificates of the following types:

  • Trusted
  • Secure Site
  • Signer CA
  • Secure site CA
  • Client Authentication

Trusted Certificates

These are certificates for signed applets and applications that are trusted.

Secure site

These are certificates for secure sites.

Signer CA

These are certificates of Certificate Authorities (CAs) for Trusted Certificates; Certificate Authorities are the ones who issue the certificates to the signers of Trusted Certificates.

Secure site CA

These are certificates of Certificate Authorities (CAs) for secure sites; Certificate Authorities are the ones who issue the certificates for secure sites.

Client Authentication

These are certificates for a client to authenticiate itself to a server.

User-Level Certificates

Options

For Trusted, Secure site, and Client Authentication certificates, there are four options: Import, Export, Remove, and Details. The user can import, export, remove, and view the details of a certificate.

For Signer CA and Secure site CA, there is only one option: Details. The user can only view the details of a certificate.

Default Keystore Location

The default locations of the of the keystore files for Unix and Windows are as follows:

Operating System
Location
Unix ${user.home}/.java/deployment/security.
Windows

${deployment.user.home}\security

For instance, on Windows 2000/XP, the default location of the keystore files for user jsmith would be as follows:

C:\Docments and Settings\jsmith\Application Data\Sun\Java\Deployment\security

Non-Default Keystore Location

For non-default locations of the certificate keystore files, specify them in the User-Level deployment.properties file with the following property names:

Certificate Type
Property Name
Trusted Certificates | deployment.user.security.trusted.certs
Secure site | deployment.user.security.trusted.jssecerts
Signer CA | deployment.user.security.trusted.cacerts
Secure site CA | deployment.user.security. trusted.jssecacerts
Client Authentication | deployment.user.security.trusted.clientcerts

System-Level Certificates

Options

For System-Level certificates, the only options a user has are Export and Details.

Default Keystore Location

Trusted, Secure Site, and Client Authentication certificate keystore files do not exist by default. Thus there are no default locations for them.

The default location for the Signer CA keystore is:

Operating System
Location
Unix $JAVA_HOME/lib/security/cacerts
Windows

$JAVA_HOME\lib\security\cacerts

The default location for the Secure Site CA keystore is:

Operating System
Location
Unix $JAVA_HOME/lib/security/jssecacerts
Windows

$JAVA_HOME\lib\security\jssecacerts

Non-Default Keystore Location

The location of the keystore files for the various types of certificates can also be set in a System-Level deployment.properties file, if it exists. (The System-Level deployment.properties file does not exist by default. It is specified in a deployment.config file. See System-Level deployment.properties file.) The following properties may be specified:

Certificate Type
Property Name
Trusted Certificates | deployment.system.security.trusted.certs
Secure site | deployment.system.security.trusted.jssecerts
Signer CA | deployment.system.security.trusted.cacerts
Secure site CA | deployment.system.security. trusted.jssecacerts
Client Authentication | deployment.system.security.trusted.clientcerts

Java

The Java panel looks like this:

It has two subpanels: Java Applet Runtime Settings and Java Application Runtime Settings.

Java Applet Runtime Settings

These settings will be used when an applet is launched in a browser. Press View... for the Java Runtime Settings for applets. On Windows you will see this:

Note that on Unix there will also be Add and Remove buttons.

Notes

There will always be at least one entry. It will be the most recently installed JRE; i.e., the JRE associated with the Java Control Panel.

Windows will show all JREs installed on a computer. The Java Control Panel finds the JREs by looking in the registry. On Unix the situation is different. There is no registry so there is no easy way to find the JREs that a user may have installed. Thus, for Unix there are Add and Remove buttons.

For Unix, only version 5.0 or higher should be added. For Windows, where all JREs are found in the registry, only version 5.0 or higher will be displayed.

Example:

Assume you are running on Microsoft Windows with Microsoft Internet Explorer, have first installed version 1.4.2, then version 5.0, and you want to run 1.4.2.

  1. Go to the j2re1.4.2\bin directory where JRE 1.4.2 was installed. On a Windows default installation, this would be here: C:\Program Files\Java\j2re1.4.2\bin
  2. Double-click the jpicpl32.exe file located there. It will launch the control panel for 1.4.2.
  3. Select the Browser tab. Microsoft Internet Explorer might still appear to be set (checked). However, when 5.0 was installed, the registration of the 1.4.2 JRE with Internet Explorer was overwritten by the 5.0 JRE.
  4. If Microsoft Internet Explorer is shown as checked, uncheck it and click Apply. You will see a confirmation dialog stating that browser settings have changed.
  5. Check Microsoft Internet Explorer and click Apply. You should see a confirmation dialog.
  6. Restart the browser. It should now use the 1.4.2 JRE for conventional APPLET tags.

On Unix you can add a JRE by pressing Add and specifiying its location (see notes above).

For Window and Unix you can optionally set Java Runtime Settings for the JRE.

Java Runtime Parameters

You can override the Java Plug-in default startup parameters by specifying custom options in the Java Runtime Parameters field. With the exception of setting classpath and cp (see Setting classpath and cp below), the syntax is the same as used with parameters to the java command line invocation. See the java launcher for a full list of command line options:

java launcher: Windows, Solaris and Linux.

Below are some examples of Java runtime parameters.

Setting classpath and cp

The following format should be used for setting classpath and cp in Java Plug-in. It differs slightly from the java command line format, which uses a space instead of the equal (=) sign.

-classpath=<path>

-cp=<path>

Enabling and disabling assertion support

To enable assertion support, the following system property must be specified in the Java Runtime Parameters:

-D[ enableassertions | ea ][:<package name>"..." | : <class name> ]

To disable assertion in the Java Plug-in, specify the following in the Java Runtime Parameters:

-D[ disableassertions | da ][:<package name>"..." | : <class name> ]

See Assertion Facility for more details on enabling/disabling assertions.

Assertion is disabled in Java Plug-in code by default. Since the effect of assertion is determined during Java Plug-in startup, changing assertion settings in the Java Plug-in Control Panel will require a browser restart in order for the new settings to take effect.

Because Java code in Java Plug-in also has built-in assertion, it is possible to enable the assertion in Java Plug-in code through the following:

-D[ enableassertions | ea ]:sun.plugin

Tracing and logging support

Tracing is a facility to redirect any output in the Java Console to a trace file (.plugin<version>.trace).

-Djavaplugin.trace=true
-Djavaplugin.trace.option=basic|net|security|ext|liveconnect

If you do not want to use the default trace file name:

-Djavaplugin.trace.filename=<tracefilename>

Similar to tracing, logging is a facility to redirect any output in the Java Console to a log file (.plugin<version>.log) using the Java Logging API. Logging can be turned on by enabling the property javaplugin.logging.

-Djavaplugin.logging=true

If you do not want to use the default log file name, enter:

-Djavaplugin.log.filename=<logfilename>

Furthermore, if you do not want to overwrite the trace and log files each session, you can set the property:

-Djavaplugin.outputfiles.overwrite=false.

If the property is set to false, then trace and log files will be uniquely named for each session. If the default trace and log file names are used, then the files would be named as follows

.plugin<username><date hash code>.trace
.plugin<username><date hash code>.log

Tracing and logging set through the Control Panel will take effect when the Plug-in is launched, but changes made through the Control Panel while a Plug-in is running will have no effect until a restart.

For more information about tracing and logging, see the chapter called Tracing and Logging.

Debugging applets in Java Plug-in

The following options are used when debugging applets in the Java Plug-in. For more information on this topic see the Debugging Support in the Java Plug-in Developer Guide.

-Djava.compiler=NONE
-Xnoagent
-Xdebug
-Xrunjdwp:transport=dt_shmem,address=<connect-address>,server=y,suspend=n

The <connect-address> can be any string (example: 2502) which is used by the Java Debugger (jdb) later to connect to the JVM

Default connection timeout

When a connection is made by an applet to a server and the server doesn't respond properly, the applet may appear to hang and may also cause the browser to hang, since by default there is no network connection timeout.

To avoid this problem, Java Plug-in 1.4 has added a default network timeout value (2 minutes) for all HTTP connections. You can override this setting in the Java Runtime Parameters:

-Dsun.net.client.defaultConnectTimeout=<value in milliseconds>

Another networking property that you can set is sun.net.client.defaultReadTimeout.

-Dsun.net.client.defaultReadTimeout=<value in milliseconds>

Note

Java Plug-in does not set sun.net.client.defaultReadTimeout by default. If you want to set it, do so through the Java Runtime Parameters as shown above.

Networking properties description:

sun.net.client.defaultConnectTimeout
sun.net.client.defaultReadTimeout

These properties specify, respectively, the default connect and read timeout values for the protocol handlers used by java.net.URLConnection. The default value set by the protocol handlers is -1, which means there is no timeout set.

sun.net.client.defaultConnectTimeout specifies the timeout (in milliseconds) to establish the connection to the host. For example, for http connections it is the timeout when establishing the connection to the http server. For ftp connections it is the timeout when establishing the connection to ftp servers.

sun.net.client.defaultReadTimeout specifies the timeout (in milliseconds) when reading from an input stream when a connection is established to a resource.

For the official description of these properties, see Networking Properties.

Java Application (JNLP) Runtime Settings

These settings will be used when a JNLP application is launched. Press View... for JNLP Java Runtime Settings. You will see this:

The Table contains the following information:

  • Platform Version
  • Product Version
  • Product Location
  • Path (Command)
  • Enabled -- a checkbox that indicates that this JRE is enabled.

The panel includes the following buttons:

The Choose... button allows user to choose content of the Path (Command) field. This button becomes enabled when the user clicks on Path (Command) field of an existing JRE.

The Find... button pops up a tool that allows the user to find JREs installed on the system.

The Add button adds a new line to the table of JREs.

The Remove button removes a line from the table of JREs.

When the OK button is pressed, the changes will be saved in the config file and the dialog will be dismissed. When the Cancel button is pressed, the changes will be discarded and the dialog will be dismissed.

Update

The Update panel looks like this:

Note

This panel is only available on Windows for 1.4.2_01 and higher releases and only for users with Administrative privileges.

The Update panel, in conjunction with the Java Update Scheduler (jusched.exe), is used to provide the latest Java updates to the end user.

Update Panel Options

There are two basic options on the Update tab:

  • Automatic update—available only on Windows XP, 2003, 2000 (SP2 or higher) and set by default for those operating systems
  • Manual update

Automatic update is performed on a scheduled basis and it is selected by checking the Check for Updates Automatically check box.

Manual update is performed by pressing the Update Now button.

If you select automatic update, you can then set the notification via the Notify Me: drop-down menu, and you can set the update schedule via the Advanced... button.

With notification, you can chose to be notified before an update is downloaded and before it is installed; or you can chose to be notified only before an update is installed (i.e., the download is automatic).

The Advanced... allows you to select the desired frequency for updates: daily, weekly (default), or montly. For daily updates, you can select the time of the day for the udpate; for weekly updates, you can select the day of the week and the time of the day; for montly updates, you can select the day of the month and the time of the day.

You can do manual updates at any time by presseing the Update Now button. This allows you to do immediate, unscheduled upates.

Java Update Scheduler

The Java Update Scheduler (jusched.exe) is used for launching automatic updates when Update Automatically is selected in the Update tab. jusched.exe runs as a background process that launches the Update Manager at predefined intervals set by the user through the Advanced ... button of the Update tab. The Update Manager coordinates the update process.

jusched.exe is launched when the user reboots the computer after installing the SDK/JRE. It is normally transparent to the user but can be viewed in the Processes tab of the Windows Task Manager. Should a user for some reason not want the scheduler to run, it can be killed via End Process button of the Processes tab.

Advanced

The Advanced panel looks like this:

It includes options for Debugging, Java console, Default Java for Browsers, Desktop integration, JNLP File/MIME Association, and Security.

Debugging

You can enable tracing and logging. For more information on tracing and logging and how to set runtime parameters for tracing and logging, see Tracing and Logging.

Java Console

There are three options:

  • Show the console
  • Hide the console (default)
  • Do not start the console

See Java Console for information about it.

<APPLET> tag support (Windows only)

Here you can specify whether a particular browser should use the Sun VM for the standard <APPLET> tag.

Note

If Mozilla and Netscape 7 are both installed and <APPLET> tag support for Mozilla and Netscape is disabled (unchecked), <APPLET> tags continue to run with the Sun VM. This is a bug that is related to the autoscan feature of Netscape 7.

Shortcut Creation (Windows only)

This provides options for Java Web Start for creating shorcuts on the desktop. The options are:

  • Always allow
  • Always allow if hinted
  • Prompt user
  • Prompt user if hinted
  • Never allow

JNLP File/MIME Association (Windows only)

This allows you to associate files with the JNLP MIME type. The options are (radio button, select only one):

  • Prompt user
  • Prompt user to replace
  • Allow if association is new
  • Never allow

Security

The options are checkboxes. You can select any number of available options. All options are checked by default except for those specified. The following are the various Java security options:

  • Allow user to grant permissions to signed content
  • Allow user to grant permissions to content from an untrusted authority
  • Use certificates and keys in browser keystore
  • Use personal certificate automatically if only one matches server request
  • Warn if site certification does not match hostname
  • Show sandbox warning banner
  • Allow user to accept JNLP security requests
  • Check publisher certificate for verification (Not Checked by Default)
  • Enable online certificate validation (Not Checked by Default)
  • Use SSL 2.0
  • Use SSL 3.0
  • Use TLS 1.0 (Not Checked by Default)

Miscellaneous (Window only)

Here you have the option to place the Java icon in the system tray (default).

Command to launch default browser (Unix only, not shown above)

Allows you to specify the location of the default browser to be launched.


Java Deployment Overview

JavaTM Deployment Overview

Overview

There are two types of deployment technologies available in JavaTM Standard Edition (Java SE) for deploying client-side Java applications on the desktop:

  1. Java Plug-in

    Java Plug-in is a tool used for deploying Java applets that run inside a web browser. Supported web browsers include Internet Explorer, Mozilla, and Netscape Navigator. For more information, see Java Plug-in Developer Guide.
  2. Java Web Start

    Java Web Start is a tool used for deploying standalone Java applications on the desktop, using JNLP (Java Network Launching Protocol). For more information, see Java Web Start Developer Guide.

Many similar deployment features between Java Plug-in and Java Web Start have been consolidated. The focus of this guide is to outline common deployment features and general deployment practices for both products.

Installation of the Java Platform

To deploy a Java applet or application, one must first decide how to deploy the JRE (Java Runtime Environment) . The JRE is available in many install formats for download and manual install. An automatic download and install is available for deploying JRE and applications through the browsers on Windows. Enterprise developers or ISVs who would like the JRE to install silently, can use the silent installation option in the installer. For developers and ISVs deploying the Java Platform in Windows-only environments, they should also check out the Active Directory deployment option in the installer.

Writing Java applets and applications

Applets and applications written in the Java Programming language are the main target for deployment. Java Platform, Standard Edition, v 6 API Specification provides the means, along with various compilers and debuggers, to develop applets and applications in the Java Programming language. See Java(TM) Platform, Standard Edition, v 6 API Specification.

If you are migrating applets from Microsoft VM to Sun's Java Virtual Machine, please check out Applet Compatibility, Java Upgrade Guide and System-Wide Repository for tips on the migration.

Deploying Java applets and applications

To deploy applets and applications over the Internet, it is necessary to specify the applets and applications on the web page for download and launch.

For an applet in a web page displayed in a browser using Sun's JVM, the applet must be embedded in the page with the required tagging structure for Java Plug-in. For topics related to Java Plug-in, see the Java Plug-in Developer Guide.

To seamlessly download, cache, and launch an applications from a web page, such a page will need to contain a link to a special Java Network Launch Protocol (JNLP) file on a web server. Java Web Start, which comes with the JRE, will then be able to download, cache, and launch the application. For topics related to JNLP and Java Web Start, see the Java Web Start Developer Guide.

Networking in Java Deployment

Both Java Plug-in and Java Web Start support the deployment of applets and applications over many types of network protocols (e.g. HTTP, HTTPS, FTP, SOCKS) and many types of security authentication (HTTP Basic, Digest, NTLM).

For deployment of the applets and applications behind a proxy server, Java Plug-in and Java Web Start also provide complete proxy support for various configurations from the browser as well as from the Java Control Panel. See Proxy Configuration.

For applets and applications deployed from servers or connecting to servers, Java Plug-in and Java Web Start also provide complete cookie support as a way for servers to store data on the client side. See Cookie.

Although Java Archive (JAR) is the de facto way to package applets and applications, it is not always the most efficient for network download. Two new compression formats are available for deploying Java applets and applications in Java Plug-in and Java Web Start: gzip and Pack200. See Pack200 and Compression.

Security in Java Deployment

By default, Java applets and applications deployed using Java Plug-in and Java Web Start are run in a secure sandbox which defines the set of permissions granted to an untrusted application. See Security.

With JAR signing, Java applets and applications deployed using Java Plug-in and Java Web Start are allowed to run outside the sandbox with additional permissions, if the users grant the permissions to the trusted application. See jarsigner on how to properly sign an application for deployment.

To ensure the signed applets and applications will continue to work after deployment even if the certificate has expired, deployers should consider signature timestamp signing. This is fully supported by Java Plug-in and Java Web Start. See Signature Timestamp.

During signature verification and HTTPS server/client authentication, certificates and keys in the default Java keystore are used by Java Plug-in and Java Web Start. In addition, Java Plug-in and Java Web Start also support certificates and keys in the browser and on the smart card for various purposes. See Browser Keystores.

Configuration in Java Deployment

Under the cover of Java Plug-in and Java Web Start, many aspects of the deployment environment, including security access controls, networking configuration, certificate stores, etc., are configurable through deployment configuration properties.

For developers who would like to customize the deployment environment, the deployment configuration file can be used for customization.

For enterprise developers or ISVs who would like to centrally deploy a configuration to tens of thousands of systems, they can also leverage the enterprise configuration support that is built-into the deployment configuration infrastructure in Java Plug-in and Java Web Start. See Deployment Configuration File and Properties for more details.

For developers or end users who would like to customize a user specific deployment environment in a user-friendly manner, Java Control Panel is a tool that can be used to serve this purpose. See Java Control Panel.

Debugging in Java Deployment

Debugging Java applets and applications is often done through Java IDEs or Java debuggers. In addition, Java Plug-in and Java Web Start have several built-in facilities that make debugging easier, including Java Console, and Tracing and Logging.

Updating the Java Platform

Java Update is a solution for keeping the Java platform up-to-date automatically with latest updates on end users' supported Windows platform. Java Update is bundled with the JRE, so every system with a JRE installed is also Java Update enabled by default. Java Update keeps most systems up-to-date with latest versions of the JRE. Therefore, developers are encouraged to take advantage of the latest JRE features for development, without worrying too much on deploying the latest JRE on their customers systems. For more information, see Java Update.


Java Update

Installing the JRE automatically installs the Java Update feature. Java Update can keep your computer up to date automatically with the latest JRE releases. You no longer need to search for critical JRE updates; Java Update delivers the latest version of the JRE directly to your computer. Java Update recognizes when you are online and, using your Internet connection, searches for available updates from the Java Update web site. Whenever an update becomes available, an icon will appear in the status area of the taskbar.

You can specify how and when you want Java Update to update your computer. For example, you can set up Java Update to automatically download and install updates on a schedule that you specify. And you can choose to be notified before the download and the installation of the update occurs, or only before the installation of the update. You can also disable the option for automatic updates altogether and do them manually. It's your choice, and you can reset the options anytime you want.

For more detailed information, see Update Panel in Java Control Panel.


Language IDs

The following are the localized language IDs for the installer:

Language | Language ID
English (en) | 1033
French (fr) | 1036
German (de) | 1031
Italian (it) | 1040
Japanese (ja) | 1041
Korean (ko) | 1042
Spanish (es) | 1034
Swedish (sv) | 1053
Simplified Chinese (zh) | 2052
Traditional Chinese (zh_TW) | 1028


Mozilla Browser eystores

Browser Keystores

Overview

Java Plug-in and Java Web Start support browser keystore in Internet Explorer and Mozilla; certificates and keys in browser keystores are used for the following purpose:

  • Signature signing verification
  • HTTPS server authentication
  • HTTPS client authentication

If the certificates and keys are on the smart cards, they are also recognized by Java Plug-in and Java Web Start if exposed in the browser keystore.

By default, browser keystore support is enabled; users may configure the support through the Advanced tab in the Java Control Panel.

Internet Explorer keystore support

On Windows, browser keystore is supported through Internet Explorer. Certificates and keys in Internet Explorer are automatically recognized by Java Plug-in and Java Web Start when Java applications and applets are deployed on Windows.

This feature is supported only with Internet Explorer 5.0 or higher.

Mozilla keystore support

On Linux and Solaris, browser keystore is supported through Mozilla. Certificates and keys in Mozilla are recognized by Java Plug-in and Java Web Start when Java applications and applets are deployed on Linux and Solaris.

Support for Mozilla keystore requires a Mozilla library called JSS (Network Security Services for Java). By default, JSS is a separate component that does not ship with Mozilla -- it is the responsibility of the deployer to install JSS with Mozilla. Java Plug-in and Java Web Start will enable the Mozilla keystore support appropriately after JSS is deployed.

This feature is supported only with Mozilla 1.4 or higher and JSS 3.2 or higher, assuming both Mozilla and JSS are compiled using the same compiler on the same platform.

  • Installing JSS with Mozilla

    Windows

    1. Create jss directory under Mozilla's installed directory.
    2. Copy JSS JAR file into the jss directory.
    3. Copy JSS native library DLL into Mozilla's installed directory.

    Linux / Solaris

    1. Create jss directory under Mozilla's installed directory.
    2. Copy JSS JAR file into the jss directory.
    3. Copy JSS native library .so into Mozilla's installed directory.
    4. Set environment variable MOZILLA_HOME to Mozilla's installed directory in Mozilla's launch script.
    5. Change environment variable LD_LIBRARY_PATH to include Mozilla's installed directory in Mozilla's launch script.


Pack200 and Compression for Network Deployment

Pack200 and Compression

This chapter includes the following topics:

  • Introduction
  • Theory
  • GZIP Compression
  • Pack200 Compression
  • Testing
  • More Information

Introduction

To increase server and network availability and band-width, two new compression formats are available to Java deployment of applications and applets: gzip and Pack200.

With both techniques the compressed JAR files are transmitted over the network and the receiving application decompresses and restores them.

Theory

HTTP 1.1 (RFC 2616) protocol discusses HTTP compression. HTTP Compression allows applications JAR files to be deployed as compressed JAR files. The supported compression techniques are gzip,compress,deflate.

As of SDK/JRE version 5.0, HTTP compression is implemented in Java Web Start and Java Plug-in in compliance with RFC 2616. The supported techniques are gzip and pack200-gzip.

The requesting application sends an HTTP request to the server. An HTTP request has multiple fields. The Accept-Encoding (AE) field is set to pack200-gzip or gzip, indicating to the server that the application can handle pack200-gzip or gzip format.

The server implementation will search for the requested JAR file with .pack.gz or .gz file extension and respond back with the located file. The server will set the response header Content-Encoding (CE) field to pack200-gzip , gzip, or NULL depending on the type of file that is being sent, and optionally may set the Content-Type (CT) to application/Java-archive. Therefore, by inspecting the CE field, the requesting application can apply the corresponding transformation to restore the original JAR file.

The above can be achieved using a simple servlet or server module with any HTTP 1.1 compliant web-servers. Compressing files on the fly will degrade server performance, especially with Pack200, and therefore not recommended.

Sample Tomcat Servlet:

/**
 *  A simple HTTP Compression Servlet
 */

import java.util.*;
import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
import java.util.zip.*;
import java.net.*;

/**
 * The servlet class.
 */
public class ContentType extends HttpServlet {

    private static final String JNLP_MIME_TYPE          = "application/x-java-jnlp-file";
    private static final String JAR_MIME_TYPE           = "application/x-java-archive";
    private static final String PACK200_MIME_TYPE       = "application/x-java-pack200";

    // HTTP Compression RFC 2616 : Standard headers
    public static final String ACCEPT_ENCODING          = "accept-encoding";
    public static final String CONTENT_TYPE             = "content-type";
    public static final String CONTENT_ENCODING         = "content-encoding";

    // HTTP Compression RFC 2616 : Standard header for HTTP/Pack200 Compression
    public static final String GZIP_ENCODING            = "gzip";
    public static final String PACK200_GZIP_ENCODING    = "pack200-gzip";

    private void sendHtml(HttpServletResponse response, String s)
                 throws IOException {
         PrintWriter out = response.getWriter();

         out.println("<html>");
         out.println("<head>");
         out.println("<title>ContentType</title>");
         out.println("</head>");
         out.println("<body>");
         out.println(s);
         out.println("</body>");
         out.println("</html>");
    }

    /*
     * Copy the inputStream to output ,
     */
    private void sendOut(InputStream in, OutputStream ostream)
                 throws IOException {
        byte buf[] = new byte[8192];

        int n = in.read(buf);
        while (n > 0 ) {
            ostream.write(buf,0,n);
            n = in.read(buf);
        }
        ostream.close();
        in.close();
    }

    boolean doFile(String name, HttpServletResponse response) {
        File f = new File(name);
        if (f.exists()) {
            getServletContext().log("Found file " + name);

            response.setContentLength(Integer.parseInt(
                        Long.toString(f.length())));

            response.setDateHeader("Last-Modified",f.lastModified());
            return true;
        }
        getServletContext().log("File not found " + name);
        return false;
    }

    /** Called when someone accesses the servlet. */
    public void doGet(HttpServletRequest request,
                HttpServletResponse response)
                throws IOException, ServletException {

        String encoding = request.getHeader(ACCEPT_ENCODING);
        String pathInfo = request.getPathInfo();
        String pathInfoEx = request.getPathTranslated();
        String contentType = request.getContentType();
        StringBuffer requestURL  = request.getRequestURL();
        String requestName = pathInfo;

        ServletContext sc = getServletContext();
        sc.log("----------------------------");
        sc.log("pathInfo="+pathInfo);
        sc.log("pathInfoEx="+pathInfoEx);
        sc.log("Accept-Encoding="+encoding);
        sc.log("Content-Type="+contentType);
        sc.log("requestURL="+requestURL);

        if (pathInfoEx == null) {
            response.sendError(response.SC_NOT_FOUND);
            return;
        }
        String outFile = pathInfo;
        boolean found = false;
        String contentEncoding = null;

        // Pack200 Compression
        if (encoding != null && contentType != null &&
                contentType.compareTo(JAR_MIME_TYPE) == 0 &&
                encoding.toLowerCase().indexOf(PACK200_GZIP_ENCODING) > -1){

            contentEncoding = PACK200_GZIP_ENCODING;

            if (doFile(pathInfoEx.concat(".pack.gz"),response)) {
                outFile = pathInfo.concat(".pack.gz") ;
                found = true;
            } else {
                // Pack/Compress and transmit, not very efficient.
                found = false;
            }
        }

        // HTTP Compression
        if (found == false && encoding != null &&
                contentType != null &&
                contentType.compareTo(JAR_MIME_TYPE) == 0 &&
                encoding.toLowerCase().indexOf("gzip") > -1) {

            contentEncoding = GZIP_ENCODING;

            if (doFile(pathInfoEx.concat(".gz"),response)) {
                outFile = pathInfo.concat(".gz");
                found = true;
            }
        }

        // No Compression
        if (found == false) { // just send the file
            contentEncoding = null;
            sc.log(CONTENT_ENCODING + "=" + "null");
            doFile(pathInfoEx,response);
            outFile = pathInfo;
        }

        response.setHeader(CONTENT_ENCODING, contentEncoding);
        sc.log(CONTENT_ENCODING + "=" + contentEncoding +
                " : outFile="+outFile);

        if (sc.getMimeType(pathInfo) != null) {
            response.setContentType(sc.getMimeType(pathInfo));
        }

        InputStream in = sc.getResourceAsStream(outFile);
        OutputStream out = response.getOutputStream();

        if (in != null) {
            try {
                sendOut(in,out);
            } catch (IOException ioe) {
                if (ioe.getMessage().compareTo("Broken pipe") == 0) {
                    sc.log("Broken Pipe while writing");
                    return;
                } else  throw ioe;
            }
        } else response.sendError(response.SC_NOT_FOUND);

    }

}

GZIP Compression

GZIP is a freely available compressor available within the JRE and the SDK as Java.util.zip.GZIPInputStream and Java.util.zip.GZIPOutputStream.
The Command line versions are available with most Unix Operating Systems, Windows Unix Toolkits (Cygwin and MKS), or they are downloadable for a plethora of operating systems at http://www.gzip.org/.

One can get the highest degree of compression using gzip to compress an uncompressed jar file vs. compressing a compressed jar file, the downside is that the file may be stored uncompressed on the target systems.

Here is an example:
Compressing using gzip on a jar file containing individual deflated entries.
Notepad.jar 46.25 kb
Notepad.jar.gz 43.00 kb

Compressing using gzip on a jar file containing "stored" entries
Notepad.jar 987.47 kb
Notepad.jar.gz 32.47 kb

As you can see the download size can be reduced by 14% using uncompressed jar, versus 3% using compressed jar file.

Pack200 Compression

Pack200 compresses large files very efficiently, depending on the density and size of the class files in the JAR file. One can expect compression to 1/9 the size of the JAR file, if it contains only class files and is in the order of several MB.

Using the same jar in the previous example:
Notepad.jar 46.25 kb
Notepad.jar.pack.gz 22.58 kb

In this case the same jar can be reduced by 50%.

Please note: when signing large jars, step 5 may fail with a Security Error — a likely cause is bug 5078608. Please use one of the workarounds detailed in the release notes.

Pack200 works most efficiently on Java class files. It uses several techniques to efficiently reduce the size of JAR files:

  1. It merges and sorts the constant-pool data in the class files and co-locates them in the archive.
  2. It removes redundant class attributes.
  3. It stores internal data structures.
  4. It use delta and variable length encoding.
  5. It chooses optimum coding types for secondary compression.
Pack200 can be used by using the Command Line Interfaces pack200(1), unpack200(1) in the bin directory of your SDK or the JRE directory.
Pack200 interfaces can also invoked programmatically from Java, please refer to the API and JavaDoc references to Java.util.jar.Pack200.

Steps to Pack a file

1. Consider the size of the JAR file, the contents of the JAR file, and the bandwidth of your target audience.

All these factors play into choosing a compression technique. The unpack200 is designed to be as efficient as possible and it takes little time to restore the original file. If you have large JAR files (2 MB or more) comprised mostly of class files, Pack200 is the preferred compression technique. If you have large JAR files which are comprised of resource files (JPEG, GIF, data, etc.), then gzip is the preferred compression technique.

2. Pack200 segmenting.

Pack200 loads the entire packed file into memory. However, when target systems are memory and resource constrained, setting the Pack200.Packer.SEGMENT_LIMIT to a lower value, will reduce the memory requirements during packing and unpacking. The Pack200.Packer.SEGMENT_LIMIT=-1 will force one segment to be generated, which will be effect in size reduction, but will require a much larger Java heap on the packing and and unpacking system. Note that several of these packed segments may be concatenated to produce a single packed file.

3. Signing the JAR files.

Pack200 rearranges the contents of the resultant JAR file. The jarsigner hashes the contents of the class file and stores the hash in an encrypted digest in the manifest. When the unpacker runs on a packed packed, the contents of the classes will be rearranged and thus invalidate the signature. Therefore, the JAR file must be normalized first using pack200 and unpack200, and thereafter signed.

(Here's why this works: Any reordering the packer does of any classfile structures is idempotent, so the second packing does not change the orderings produced by the first packing. Also, the unpacker is guaranteed by the JSR 200 specification to produce a specific bytewise image for any given transmission ordering of archive elements.)

An Example

Suppose you wish to use HelloWorld.jar.

Step 1: Repack the file to normalize the jar, repacking calls the packer and unpacks the file in one step.

% pack200 --repack HelloWorld.jar

Step 2: Sign the jar after we normalize using repack.

% jarsigner -keystore myKeystore HelloWorld.jar ksrini

Verify the just signed jar to ensure the signing worked.

% jarsigner -verify HelloWorld.jar
jar verified.

Ensure the jar still works.

% Java -jar HelloWorld.jar
HelloWorld

Step 3: Now we pack the file

% pack200 HelloWorld.jar.pack.gz HelloWorld.jar

Step 4: Unpack the file

% unpack200 HelloWorld.jar.pack.gz HelloT1.jar

Step 5: Verify the jar

% jarsigner -verify HelloT1.jar
jar verified.

// Test the jar ...
% Java -jar HelloT1.jar
HelloWorld

After verification, the compressed pack file HelloWorld.jar.pack.gz can be deployed.

4. Reduction techniques:

Pack200 by default behaves in a High Fidelity (Hi-Fi) mode, meaning all the original attributes present in the classes as well as the attributes of each individual entry in a JAR file is retained. These typically tend to add to the packed file size, here are some of the
techniques one can use to further reduce the size of the download:
  1. Modification times: If modification time of the individual entries in a JAR file is not a concern, you can specify the option   Pack200.Packer.MODIFICATION_TIME="LATEST". This will allow one modification time to be transmitted in the pack file for each segment. The latest time will be the latest time of any entry within that segment.

  2. Deflation hint: Similar to the above, if the compression state of the individual entries in the archive is not required, set Pack200.Packer.DEFLATION_HINT="false". This will fractionally reduce the download size, as individual compression hints will not be transmitted. However, the jar when recomposed will contain "stored" entries and hence may consume more disk space on the target system.

    For example:

    pack200 --modification-time=latest --deflate-hint="true" tools-md.jar.pack.gz tools.jar

    Note: the above optimizations will yield better results with a JAR file containing thousands of entries.

  3. Attributes: Several class attributes are not required when deploying JAR files. These attributes can be stripped out of class files, significantly reducing download size. However, care must be taken to ensure that required runtime attributes are maintained.

    1. Debugging attributes: If debugging information, such as Line Numbers and Source File, is not required (typically in applications stack traces), then these attributes can be discarded by specifying Pack200.Packer.STRIP_DEBUG=true.This typically reduces the packed file by about 10%.

      Example:
      pack200 --strip-debug tools-stripped.jar.pack.gz tools.jar

    2. Other attributes: Advanced users may use some of the other strip-related properties to strip out additional attributes. However, extreme caution should be used when doing so, the resultant JAR file must be tested on all possible Java runtime systems to ensure that the runtime does not depend on the stripped attributes.

5. Handling unknown attributes:

Pack200 deals with standard attributes defined by the Java Virtual Machine Specification, however compilers are free to introduce custom attributes. When such attributes are present, by default, Pack200 passes through the class, emitting a warning message. These "passed-through" class files, may contribute to bloating of packed files. If the unknown attributes are prevalent in the classes of a JAR file, this may lead to a very large bloat of the packed output. In such a cases, consider the following strategies:

Strip the attribute if the attribute is deemed to be redundant at runtime, this can be achieved by setting the property Pack200.Packer.UNKNOWN_ATTRIBUTE=STRIP or

pack200 --unknown-attribute=strip foo.pack.gz foo.jar

If the attributes are required at runtime, and they do contribute to an inflation, then identify the attribute from the warning message and apply a suitable layout for these, as described in the Pack200 JSR 200 specification., and the Java API reference section for Pack200.Packer.

Its possible that a compiler could define an attribute not implemented in the layout specification of Pack200, and may cause the Packer to malfunction, in such cases an entire class file(s) can be "passed through", as if it were a resource by virtue of its name and can be specified as follows:

pack200 --pass-file="com/acme/foo/bar/baz.class" foo.pack.gz foo.jar

or an entire directory and its contents,

pack200 --pass-file="com/acme/foo/bar/" foo.pack.gz foo.jar
6. Installers:
You may wish to take advantage of the Pack200 technology in your installation program, whereby a product's jars may need to compressed using Pack200 and decompressed during the installation. If the JRE or SDK is bundled in the installation, you are free to use the unpack200 (Unix) or unpack200.exe(Windows) in the distribution 'bin' directory, this implementation is a pure C++ application requiring no Java runtime to be present for it to run.

Windows: Installers may use a better algorithm than the one in GZIP to compress entries in such cases, one will get better compression using the Installer's intrinsic compression, by using the pack200 as follows:

pack200 --no-gzip foo.jar.pack foo.jar

This will prevent the output file from being gzip compressed.

unpack200 is a Windows Console application, ie. it will display a MS-DOS window during the install, to suppress this, you can use a launcher with a WinMain which will suppress this window, as shown below.

Sample Code:
#include "windows.h"
#include <stdio.h>

int APIENTRY WinMain(HINSTANCE hInstance,
                     HINSTANCE hPrevInstance,
                     LPSTR     lpCmdLine,
                     int       nCmdShow) {
  STARTUPINFO si;
  memset(&si, 0, sizeof(si));
  si.cb = sizeof(si);

  PROCESS_INFORMATION pi;
  memset(&pi, 0, sizeof(pi));

  //Test
  //lpCmdLine = "c:/build/windows-i586/bin/unpack200 -l c:/Temp/log c:/Temp/rt.pack c:/Temp/rt.jar";
  int ret = CreateProcess(NULL,			/* Exec. name */
              lpCmdLine,		/* cmd line */
              NULL,			/* proc. sec. attr. */
              NULL,			/* thread sec. attr */
              TRUE,			/* inherit file handle */
              CREATE_NO_WINDOW | DETACHED_PROCESS, /* detach the process/suppress console */
              NULL,			/* env block */
              NULL,			/* inherit cwd */
              &si,			/* startup info */
              &pi);			/* process info */
  if ( ret == 0) ExitProcess(255);

  // Wait until child process exits.
  WaitForSingleObject( pi.hProcess, INFINITE );

  DWORD exit_val;

  // Be conservative and return
  if (GetExitCodeProcess(pi.hProcess, &exit_val) == 0) ExitProcess(255);

  ExitProcess(exit_val); // Return the error code of the child process

  return -1;
}

Testing

It is required that all JAR files, packed and unpacked, be tested for correctness with your applications test qualifiers. When using the command line interface pack200, the output file will be compressed using gzip with default values. A user may create a simple pack file and compress using gzip with user-specified options or using some other compressor.

More Information

For more information see pack200 and unpack200 in Java Deployment Tools.

Updates in Java Standard Edition 6

In Java SE 6, the Java class file format has been updated. For more information see JSR 202: Java Class File Specification Update. Due to JSR 202 the Pack200 engine needs to be updated accordingly for the following reasons:

  • Align with the new class file format for Java SE 6
  • Ensure that Java SE 6 class files are compressed effectively.

To keep the changes minimal and seamless for users, the packer will generate appropriately versioned pack files based on the version of the input class files.

Also to maintain backward compatibility, if the input JAR-files are solely comprised of JDK 1.5 or older class files, a 1.5 compatible pack file is produced. Otherwise a Java SE 6 compatible pack200 file is produced. For more information, refer the Pack200 man page.


Proxy Configuration

Proxy Configuration covers the following topics:

  • Introduction
  • How Java Plug-in and Java Web Start Obtain Proxy Information
  • Manual Proxy Configuration
  • Automatic Proxy Configuration
  • java.net.ProxySelector API in J2SE 5.0

Introduction

For enterprise customers it is important to be able to set up secure computing environments within their companies, and proxy configuration is an essential part of doing that. Proxy configuration acts as a security barrier; it ensures that the proxy server monitors all traffic between the Internet and the intranet. This is normally an integral part of security enforcement in corporate firewalls within intranets. Enterprise customers who want to use Java Plug-in to deploy applets, or Java Web Start to run applications, on their intranet web pages may also set up proxy support. This support is required for Java Plug-in and Java Web Start to work in an intranet environment and can be set up through the Java Control Panel.

Java Control Panel

The Java Control Panel provides four proxy options via the Network Setting subpanel:

  • Use browser settings
  • Use proxy server
  • Use automatic proxy configuration script
  • Direct connection

Use browser settings

If "Use browser settings" is selected, then proxy information is entered entirely through the browser. For Internet Explorer, go to Tools>Internet Options ... and select the Connections tab and then LAN Settings ... ; for Netscape, go to Edit>Preferences ... and select Advanced under Category and then Proxies. How this works and the three types of connections that can be set up through the browser—Direct, Manual, and Automatic—are described in the following sections.

Use proxy Server

If you select "Use proxy server" in the Java Control Panel, you have two choices here:

  1. You can set the Address and the Port for a proxy server with the option to bypass it for local addresses.
  2. You can individually set the proxy server for HTTP, Secure, FTP, and Socks connections. You can also provide a list of addresses for which you do not want to use a proxy server.

Use automatic proxy configuration script

If you select "Use automatic proxy configuration script", then you must enter the URL for the location of the JavaScript called FindProxyForURL(URL url) that returns the proxy server to be used for a URL. Support for this script is the same as described below under Automatic Proxy Configuration.

Direct connection

Direct connection does not use a proxy. For certain situations, such as when mobile users connect to the company through a modem, direct connection to the intranet environment is required, and proxies should not be used in these cases.

How Java Plug-in and Java Web Start Obtain Proxy Information From the Browser

Because browsers on different platforms store proxy information differently, there is no generic mechanism to obtain proxy information. Here's how proxy information is obtained for two different browser-platform combinations:

Microsoft Internet Explorer: Internet Explorer stores proxy information in the same set of keys in the windows registry. Java Plug-in and
Java Web Start extract this information directly from the registry.

Mozilla: Mozilla stores proxy information in a preference file under the user profile directory on the local machine. Mozilla also has public APIs available for determining proxy information. Java Plug-in uses the Mozilla public APIs to obtain the proxy information; Java Web Start obtains the proxy information through reading and parsing the preference file.

Netscape Navigator: Navigator stores proxy information in a preference file under the user profile directory on the local machine. Java Plug-in and Java Web Start read and parse this file to obtain the proxy information.

Java Plug-in and Java Web Start obtain proxy information at startup time. If you change the proxy settings after Java Plug-in or Java Web Start have started, you may force reloading of the proxy information from the browser through the p option in the Java Console. Java Web Start is restarted for each application, so new proxy information will be used automatically on subsequent launches.

Manual Proxy Configuration

Internet Explorer, Mozilla, and Netscape Navigator support manual proxy configuration. Users can specify the proxy server and port for each protocol. Users can also specify one proxy server and port for all protocols. To minimize the workload of the proxy server, some sites might bypass the proxy server completely when a machine is connecting to another machine inside the intranet environment. To do this, network administrators and users can specify a proxy server bypass list in the browser's proxy setting.

Internet Explorer: Java Plug-in and Java Web Start recognize and supports the proxy server and port setting associated with the protocol. IE supports various syntaxes in the proxy server bypass list, as follows:

  • IP address/hostname only
  • IP address/hostname with wildcard
  • IP address/hostname with protocol

For example, if you specify "121.141.23.5;*.eng;http://*.com" in the proxy server bypass list, then the browser bypasses the proxy whenever one of the following occurs:

  • "121.141.23.5" is requested
  • the URL hostname ends with ".eng"
  • the URL protocol is http and the URL hostname ends with ".com"

Currently Java Plug-in and Java Web Start support the first two syntaxes in the proxy server bypass list in IE. IE also supports bypassing the proxy server for local (intranet) addresses without using the proxy server bypass list. Java Plug-in and Java Web Start support this option by bypassing the proxy server if the URL hostname is plain; i.e., the hostname contains no dot (.).

Mozilla and Netscape Navigator: Java Plug-in and Java Web Start recognize and supports the proxy server and port setting associated with the protocol. For example, if you specify ".eng,.sun.com" in the proxy server bypass list in Mozilla , it bypasses the proxy whenever the URL hostname ends with ".eng" or ".sun.com". Java Plug-in and Java Web Start fully support this syntax in the proxy server bypass list in Mozilla and Navigator.

For more information about manual proxy configuration in your browser, consult the user guide for your browser.

Automatic Proxy Configuration

Automatic proxy configuration is supported in the browser by setting a particular URL that contains a JavaScript file with .pac or .js extension. This file contains a function called FindProxyForURL that contains the logic to determine which proxy server to use when the browser receives a connection request. This function is written by the system administrator for the particular intranet environment. When the browser starts up, it recognizes the URL of the JavaScript file and downloads the file to the local machine using direct connection. Then whenever it needs to make a new connection, the browser executes the JavaScript function FindProxyForURL in the file to obtain the proxy information to set up the connection.

Java Plug-in:

Internet Explorer: During startup, Java Plug-in downloads the JavaScript file to the local machine using direct connection. Then whenever it needs to make a new connection, it executes the FindProxyForURL function to obtain the proxy information using the JavaScript engine in Internet Explorer.

Mozilla/Netscape Navigator: During startup, Java Plug-in downloads the JavaScript file to the local machine using direct connection. Then
whenever it needs to make a new connection, it executes the FindProxyForURL function to obtain the proxy information by using the JavaScript engine in Mozilla/Navigator.

Java Web Start:

Windows: During startup, Java Web Start downloads the JavaScript file to the local machine using direct connection. Then whenever it needs to make a new connection, it executes the FindProxyForURL function to obtain the proxy information using the JavaScript engine in Internet Explorer.

Linux/Solaris: During startup, Java Web Start downloads the JavaScript file to the local machine using direct connection. Then whenever it needs to make a new connection, it will parse the FindProxyForURL function and try its best guess to obtain the proxy information.

Notes on FindProxyForURL

Given a JavaScript engine, the following is applicable to Java Plug-in on all platforms and to Java Web Start on Windows only.

  1. There are a number of JavaScript helper functions which can be called from the JavaScript function FindProxyForURL. Java Plug-in and Java Web Start provide their own implementations of these functions to completely emulate automatic proxy configuration. Regarding the implementation of these helper function, note the following:
    • Function dnsResolve always returns an empty string if the host is not an IP address.
    • Function isResolvable always returns false if the host is not an IP address.
    • Function isInNet always returns false if the host is not an IP address.
  2. Executing the function FindProxyForURL always returns proxy information as a string. Java Plug-in and Java Web Start extract the setting in the following way:
    • If "DIRECT" is in the string, Java Plug-in and Java Web Start assume direct connection.
    • If "PROXY" is in the string, they use the first proxy setting for the connection.
    • If "SOCKS" is in the string, they use the SOCKS v4 for the connection.
    • Otherwise, the proxy information in the string is incorrect. In this cases, Java Plug-in and Java Web Start assume direct connection.

For more information about automatic proxy configuration in your browser, consult the user guide for your browser.

java.net.ProxySelector API in J2SE 5.0

Developers may sometimes need to determine the proxy configuration of a given host. By knowing the proxy configuration they can write more intelligent code to connect to the host through the proper proxy server. In J2SE 5.0, java.net.ProxySelector is a new API for proxy configuration support. Here is a simple code example:

 private Proxy findProxy(URI uri)
{
try
{
ProxySelector
    selector = ProxySelector.getDefault();
List<Proxy>
    proxyList = selector.select(uri);
if (proxyList.size()
    > 1)
return
    proxyList.get(0);
}
catch (IllegalArgumentException e)
{
}
return Proxy.NO_PROXY;
}


Security

Security includes the following topics:

  • Policy Files and Permissions
  • Property Files and Certificates
  • Security Dialogs
  • More Information

Policy Files and Permissions

Java applications and applets deployed using Java Web Start and Java Plug-in are by default run in a secure sandbox that defines the set of permissions that code in an untrusted app is granted.

The standard java policy files can be used to enhance the permissions granted to untrusted apps. In addition to $JRE_HOME/lib/security/java.policy and $USER_HOME/.java.policy (used by all java programs), applications and applets loaded by Java Web Start and Java Plug-in load two additional policy files, whose location can be configured by the deployment configuration properties: deployment.user.security.policy and deployment.system.security.policy.

The default sandbox, combined with the permissions granted by these policy files, if they exist, determine the permissions granted to untrusted code.

One other policy file, whose location is determined by the deployment configuration property deployment.security.trusted.policy, can be used to restrict the permissions granted to trusted code. With this property unset (default), trusted code will be granted the AllPermission permission. With this property set, trusted code will be granted only the permissions granted to untrusted code, plus any other permissions granted by the policy file pointed to by this property.

Property Files and Certificates

The deployment configuration also has several properties that determine how and if code can be trusted. Normally, any signed JAR file in Java Plug-in, and any set of signed JAR files in Java Web Start that are listed in a jnlp file requesting the AllPermission permission, will be granted trust by the user after the certificate chains have been verified and shown to the user in a security dialog.

The deployment configuration property deployment.user.security.trusted.certs points to a certificate store that contains the certificates already accepted by the user.

The deployment configuration property deployment.system.security.trusted.certs can be configured to point to a certificate store of certificates pre-accepted by the system administrator.

If a JAR file (in Java Plug-in) or set of JAR files in a jnlp file requesting the AllPermission permission (in Java Web Start) is signed by a certificate that is in one of these stores, it will be trusted.

The deployment configuration property deployment.security.askgrantdialog.show can control if the user is permitted to grant trust to new code signed with new certificates, and the deployment configuration property deployment.security.askgrantdialog.notinca can further be used to control if the user is permitted to grant trust to code signed by certificates whose root certificate is not in one of the Root Certificate Authority certificate stores (see below).

Security Dialogs

If the above two properties allow it, and the code is signed with certificate chains that can be properly validated, the user will then be shown a security dialog asking him/her to grant trust to the code.

Click Run and the following dialog appears.

The Root Certificate Authority certificate stores mentioned above are the union of the certificate stores in the files pointed to by the properties: deployment.user.security.cacerts and deployment.system.security.cacerts. By default deployment.system.security.cacerts points to the cacerts file in the jre/lib/security directory. deployment.user.security.cacerts points to a file that contains any additional cacerts imported into it using the Certificates dialog in the Security tab of the Java Control Panel.

One final setting can be used to customize the user experience in Java Web Start. By default the sandbox does not include the AWTPermission showWindowWithoutWarningBanner. Without this permission, all top-level windows will contain the awt banner "Java Application Window" or "Java Applet Window". The deployment configuration property deployment.security.sandbox.awtwarningwindow can be used to add this permission to untrusted code.

More Information

  • For a detailed discussion of properties, see Deployment Configuration File and Properties.
  • For details about security in the Java Control Panel, see the Security section in the Java Control Panel.


Silent Installation

This section discussess silent installation of the Java Runtime Environment (JRE) on Windows 32-bit platform. It is intended for:

  • System Administrators deploying Java Plug-in and the JRE on multiple PCs in Intranet without user interaction
  • Companies having products requiring the JRE. The JRE can be silently installed with their product.

The Silent Installation section has the following topics:

  • Introduction
  • Installation in Silent Mode
  • Uninstallation in Silent Mode
  • Creating a Log File

Introduction

JavaTM SE Runtime Environment (JRE) installations are built using Microsoft Window Installer (MSI) 2.0 technology. MSI contains built-in support for silent or unattended installations. This document tells how to silently install the JRE using the .exe that launches the MSI installation.

Installation in Silent Mode

In Java SE 6 The Windows offline installation command has the same syntax as the Windows Installation. The command is as follows:

 <jre>.exe   [/lang=<language ID>] /s [ADDLOCAL=jrecore[,extra][,other_US] | ALL]
              [IEXPLORER=1] [MOZILLA=1] [INSTALLDIR=<drive>:\<install_path>]
             [REBOOT=Suppress]

where

  • <jre>.exe is the single executable installer for the Java Runtime Environment (JRE)
  • /lang=<language ID>, if used, sets the localized language for the installer (see language IDs)
  • ADDLOCAL, if used, is either jrecore[,extra][,other_US] or ALL
  • IEXPLORER=1, if used, indicates that the Plug-in should be registered with the Internet Explorer browser
  • MOZILLA=1 indicates that the Plug-in should be registered with Mozilla 1.1 and later and Netscape browsers (for releases prior to 5.0, see note above)
  • INSTALLDIR, if used, specifies the drive and path of the installation
  • REBOOT=Suppress, if used, indicates that if locked files are encountered the computer should not be rebooted
  • If ADDLOCAL=ALL is used, then all the features will be installed.
  • If ADDLOCAL=jrecore[,extra][,other_US]can specify the following options:
    • jrecore indicates the core of the JRE is installed
    • extra (optional) indicates additional Fonts, Colors, and Soundbank is installed
    • other (optional) indicates locale-specific .jar files will be installed.
  • If ADDLOCAL is not used, then only the following configuration is installed:
    • jrecore will be installed
    • extra will not be installed
    • other will be installed only if localization support, other than English, is installed.
  • If INSTALLDIR is not specified, the installation will go into C:\Program Files\java\jre1.6.0 (default location).

Note

The command is case sensitive and there must be no spaces in the features listed with ADDLOCAL.

Installation Configurations

Example 1

Suppose the JRE installer is jre-6-rc-windows-i586.exe and you want to install the following configuration:

  • Perform a Windows Installation
  • Install the JRE core, additional fonts, colors, and Soundbank
  • Register the Plug-in with Netscape 7 and Mozilla 1.3

The command to install the above mentioned configuration is as follows:

jre-6-rc-windows-i586.exe /s ADDLOCAL=jrecore,extra MOZILLA=1

Example 2

Suppose the JRE installer is jre-6-rc-windows-i586.exe and you want to install the following configuration:

  • Perform a Windows Offline Installation and install the JRE on D drive at java\jre
  • Have all features of the JRE installed
  • Register the Plug-in with Internet Explorer

The command to install the above mentioned configuration is as follows:

jre-6-rc-windows-i586.exe /s ADDLOCAL=ALL IEXPLORER=1 INSTALLDIR=D:\java\jre"

Note

To keep the MS-DOS window open, until the installation of JRE is complete use the start /w command as follows:

start /w jre-6-rc-windows-i586.exe /s ADDLOCAL=jrecore,extra MOZILLA=1

Uninstallation in Silent Mode

This is the command line for uninstalling in silent mode for Implementation-Version n1.n2.n3_n4n5:

msiexec.exe /qn /x {3248F0A8-6813-11D6-A77B-00B0D0n1n2n3n4n50}

Notes

  1. This command can be run from anywhere.
  2. The msiexec.exe executable is located in the windows system directory.
  3. The REBOOT=Suppress option, mentioned above under installation, may also be used with the uninstall command.
  4. For more information on version formats, see Appendix 2: Sun-Supported Specification-Version and Implementation-Version Formats.

Example for version 1.6.0

msiexec.exe /qn /x {3248F0A8-6813-11D6-A77B-00B0D0160000}

Example for version 1.6.0_02

msiexec.exe /qn /x {3248F0A8-6813-11D6-A77B-00B0D0160020}

Creating a Log File

Log file can be used to verify if a installation or uninstallation succeeded. To create a log file describing the installation or uninstallation append /L C:\<path>setup.log to the install or uninstall command and scroll to the end of the log file to verify.

Installation Example

The following is an example for installation:

jre-6-rc-windows-i586.exe /s /L C:\<path>setup.log

The above command causes the log to be written to the setup.log file.

Uninstallation Example

The following is an example for uninstalling:

msiexec.exe /qn /x {3248F0A8-6813-11D6-A77B-00B0D0160000} /L C:\<path>setup.log


System- and User-Level Properties

Deployment Configuration File and Properties

Deployment Configuration File and Properties includes the following topics:

  • Overview
  • Deployment Configuration File
  • Deployment Configuration Properties

Overview

The deployment.properties file is used for storing and retrieving deployment configuration properties in the Java Control Panel. They are also used for customizing runtime behavior for both Java Plug-in and Java Web Start.

There is always a User-Level deployment.properties file. Its location, which is non-configurable, is described below. There may also be an (optional) System-Level deployment.properties file. If it exists, its location is determined by a System Administrator through the deployment.config file as described below.

Deployment Configuration File (deployment.properties)

User Level

The User-Level deployment.properties file is located as follows:

Operating System
Location
Windows | <User Application Data Folder>\Sun\Java\Deployment\deployment.properties
Unix | ${user.home}/.java/deployment/deployment.properties

(${user.home} is typically home/<username>.)

Examples:

For user jsmith running on Windows 2000/XP, the deployment.properties file would be located as follows:

C:\Documents and Settings\jsmith\Application Data\Sun\Java\Deployment\deployment.properties

For user bjones running on Unix, the deployment.properties file would be located as follows:

/home/bjones/.java/deployment/deployment.properties

System Level

The deployment.config file is used for specifying the System-Level deployment.properties in the infrastructure. By default no deployment.config file exists; thus, no system-wide deployment.properties file exists. If deployment.config exists, it is located either here

Operating System
Location
Windows | <Windows Directory>\Sun\Java\Deployment\deployment.config
Unix | /etc/.java/deployment/deployment.config

or here

Operating System
Location
Windows | ${deployment.java.home}\lib\deployment.config
Unix | ${deployment.java.home}/lib/deployment.config

(${deployment.java.home} is the location of the jre from which the deployment products are run. Deployment products include Java Web Start, Java Plug-in, Java Control Panel ...)

deployment.config (if it exists) contains two properties: deployment.system.config and deployment.system.config.mandatory.

deployment.system.config is the URL to the system (enterprise-wide) deployment.properties file. It can be used by system administrators to centrally administrate or "lock-down" user-specific configuration settings.

deployment.system.config.mandatory is a boolean. The default is false. If false, there will be an attempt to load the deployment.properties file pointed to by the deployment.system.config URL. If the URL can be found and loaded, it will be used. If true, there will likewise be an attempt to load the system deployment.properties file pointed to by the deployment.system.config URL. If the URL can be found and loaded, it will be used; but if it cannot be found or loaded, then nothing will be allowed to run.

Deployment Configuration Properties

The following table describes the properties that can be set in the deployment.properties file.

Note

Any system deployment property, say SomeKey=SomeValue, may be locked by including another key, SomeKey.locked. The key SomeKey.locked may or may not be set to a value; in either case, SomeKey=SomeValue will be locked so that the user cannot change it. If a system deployment property is not locked, then a user will be allowed to change it.

Property Key
Type
Default Value
Description
Infrastructure
deployment.user.cachedir
 String "$USER_HOME" +
File.separator + "cache" 		User-level cache directory.
deployment.system.cachedir
 String null System-level cache directory.
deployment.user.logdir | String | "$USER_HOME" + File.separator + "log" | User-level log directory.
deployment.user.tmp
 String "$USER_HOME" +
File.separator + "tmp"; 		Temporary user directory.
Certificate stores and policy files
deployment.user.security.policy
 String "file://$USER_HOME/security/java.policy"

User-level security policy file. The protocol of URL is either file, HTTP, or HTTPS.

deployment.user.security.trusted.cacerts

String "$USER_HOME" + File.separator + "security" + File.separator + "trusted.cacerts";

User-level Root CA certificate store.

deployment.user.security.trusted.jssecacerts

String "$USER_HOME" + File.separator + "security" + File.separator + "trusted.jssecacerts"

User-level JSSE CA certificate store.

deployment.user.security.trusted.certs

String "$USER_HOME" + File.separator + "security" + File.separator + "trusted.certs"

User-level Trusted signer certificate store.

deployment.user.security.trusted.jssecerts

String "$USER_HOME" + File.separator + "security" + File.separator + "trusted.jssecerts";

User-level Trusted JSSE certificate store.

deployment.user.security.trusted.clientauthcerts

String "$USER_HOME" + File.separator + "security" + File.separator + "trusted.clientcerts"

User-level Client Authentication certificate store.

deployment.system.security.policy

String null

System-level security policy file. The protocol of URL is either file, HTTP, or HTTPS.

deployment.system.security.cacerts

String "$JAVA_HOME" + File.separator + "lib" + File.separator + "security" + File.separator + "cacerts"

System-level Root CA certificate store.

deployment.system.security.jssecacerts

String "$JAVA_HOME" + File.separator + "lib" + File.separator + "security" + File.separator + "jssecacerts";

System-level JSSE CA certificate store.

deployment.system.security.trusted.certs

String "$SYSTEM_HOME" + File.separator + "security" + File.separator + "trusted.certs"

System-level Signer certificate store.

deployment.system.security.trusted.jssecerts

String "$SYSTEM_HOME" + File.separator + "security" + File.separator + "trusted.jssecerts"

System-level JSSE certificate store.

deployment.system.security.trusted.clientauthcerts

String "$SYSTEM_HOME" + File.separator + "security" + File.separator + "trusted.clientcerts"

System-level Client Authentication certificate store.
Security Access And Control settings

deployment.security.askgrantdialog.show

String true Must be "true" if the user is allowed to grant permissions at all.

deployment.security.askgrantdialog.notinca

 String true Must be "true" if the user is allowed to grant permissions to certificates that are not issued by a CA in the Root/JSSE CA certificate store.

deployment.security.jsse.hostmismatch.warning

String true Must be "true" for JSSE HTTPS certificate verification to show host-mismatch warning.

deployment.security.trusted.policy

String ""

Policy file contains the ceiling policy of permissions granted to trusted applications and applets. By default this is all permissions, but by using this configuration setting, a user or enterprise can configure a lesser set of permissions.

deployment.security.sandbox.awtwarningwindow

String true "true" if the sandbox has awtShowWindowWithoutWarning.

deployment.security.sandbox.jnlp.enhanced

String true Must be "true" for the user to see and accept JNLP api security dialogs.
deployment.security.validation.ocsp | Boolean | false | Specifies whether Online Certificate Status Protocol is enabled.
deployment.security.validation.ocsp.url | String | null | Specifies a url string pointing to an OCSP response server.
deployment.security.validation.ocsp.signer | String | null | Points to a OCSP response singer certificate subject name.
deployment.security.validation.crl | Boolean | false | Specifies whether to use certificate revocation list.
deployment.security.validation.crl.url | String | null | Specifies a URL in the Certificate Revocation List to perform a certificate validation.
deployment.security.authenticator
String true Normally plugin and webstart install an Authenticator to handle communication with Authenticating webpages or Authenticating proxies. This is the default behavior (true). This option can be used to turn the normal behavior off if, for example, an application communicates itself with an authenticating web page and needs to install it's own Authenticator.
Networking

deployment.proxy.type

int 3 for PROX_TYPE_BROWSER

This is for the type of proxy that should be use. The choices are:

PROX_TYPE_UNKNOWN = -1;
PROX_TYPE_NONE = 0;
PROX_TYPE_MANUAL = 1;
PROX_TYPE_AUTO = 2; and
PROX_TYPE_BROWSER = 3;

deployment.proxy.same

boolean false This parameter (true) says to use the same web server and port for https and ftp as is configured for http. (This is only valid if deployment.proxy.type = PROX_TYPE_MANUAL.)
deployment.proxy.auto.config.url | String | (no default) | URL for auto-Auto proxy configuration JavaScript.proxy configuration JavaScript.
deployment.proxy.bypass.list | String | (no default) | List of hostnames that should bypass the proxy. Each hostname is delimited by a comma in the property; e.g., "192.168.1.100,localhost,sun.com"
deployment.proxy.bypass.local String (no default)

All local hosts should be bypassed.
deployment.proxy.http.host | String | (no default) | HTTP proxy hostname.
deployment.proxy.http.port | String | (no default) | HTTP proxy port.
deployment.proxy.https.host | String | (no default) | HTTPS proxy hostname.
deployment.proxy.https.port | String | (no default) | HTTPS proxy port.
deployment.proxy.ftp.host | String | (no default) | FTP proxy hostname.
deployment.proxy.ftp.port | String | (no default) | FTP proxy port.
deployment.proxy.socks.host | String | (no default) | SOCKS v4 proxy hostname.
deployment.proxy.socks.port | String | (no default) | SOCKS v4 proxy port.
deployment.proxy.override.hosts
String "" Proxy overridden list.
Cache and Optional Package Repository
deployment.cache.max.size
String "-1"

Maximum size of deployment cache in MB. This is the cache size for each cache: Java Web Start and Java Plug-in.

"0"—Disables caching in Java Plug-in; cache size in Java Web Start will be unlimited.

"-1"—For unlimited cache size.
deployment.cache.jarcompression
String 0

0-9 compression ratio to be used in applet jar compression.
deployment.javapi.cache.enabled
 String false Specifies if cache should be disabled. false means it should not be disabled.
Java Console

deployment.console.startup.mode

String

"HIDE"

The choices are:

  • "HIDE" to hide the Java Console;
  • "SHOW" to show the Java Console;
  • "DISABLE" to disable the Java Console;
Tracing and Logging
deployment.trace | String | false | Enbable tracing.
deployment.log
String false Enable logging.
Java Web Start: JNLP Association
deployment.javaws.associations int 2

The JNLP associations. The choices are:

ASSOCIATION_NEVER = 0;
ASSOCIATION_NEW_ONLY = 1;
ASSOCIATION_ASK_USER = 2;
ASSOCIATION_REPLACE_ASK = 3;
Java Web Start: Desktop Integration

deployment.javaws.shortcut

 String "ASK_IF_HINTED"

This relates to creating a desktop shortcut for Java Web Start. The choices are:

  • "NEVER"
  • "ALWAYS"
  • "ASK_USER"
  • "ASK_IF_HINTED"
  • "ALWAYS_IF_HINTED"
Java Web Start JRE Selections

deployment.javaws.installURL

String "http://java.sun.com/products/autodl/j2se"

The autodownload URL.
Java Web Start JRE management

deployment.javaws.autodownload

String "ALWAYS"

This sets the choices for autodownloading. The choices are:

  • "ALWAYS"
  • "PROMPT"
  • "NEVER"
Browser selection and path

deployment.browser.path

 String "<No Browser Selected>"

This is the path to the browser for showing web pages from the application viewer, the About Box, and webstart applications.

Note that this property is used for Solaris and Linux only. On Widows, this property is ignored, and the default browser is determined the same way it is by any other application that launches a browser on Windows.
Check for update Timeout
deployment.javaws.update.timeout
int 500 Units are miliseconds.


System-Wide Repository

System-Wide Repository (Windows only)

Previous to this release, when a new JRE was installed, JAR and native libraries for the old release were not visible to the new one. Thus applications and applets that relied on those libraries would not work, and developers were forced to redeploy their libraries to the new JRE. The new System-Wide Repository is the solution to that problem. It provides a global or system-wide location where the VM can search for libraries, JAR or native, indepenent of the JRE location. It provides functionality similar to the repository in the Microsoft VM (see How Does the Virtual Machine Search for Java Classes?).

Note: In this release the system-wide repository is supported only by Java Plug-in and only on Windows.

The table below shows the location of the new System-Wide Repository:

Type of Library
System-Wide Location
DLL | Any directory in the System Path environment variable.
Untrusted JAR | <Windows Directory>\Sun\Java\Deployment\Lib\Untrusted
Trusted JAR | <Windows Directory>\Sun\Java\Deployment\Lib\Trusted

<Windows Directory> is the Windows OS directory on the drive where Windows was installed (also called %SystemRoot%).

For example, on Windows XP, where Windows has been installed on the C drive (typical), the locations of these libraries would be as follows:

Type of Library
System-Wide Location
DLL | Any directory in the System Path variable; e.g., C:\WINDOWS\repository if C:\WINDOWS\repository has been set in the System Path variable.
Untrusted JAR | C:\WINDOWS\Sun\Java\Deployment\Lib\Untrusted
Trusted JAR | C:\WINDOWS\Sun\Java\Deployment\Lib\Trusted

Note the following:

  1. The classes in the JARS from the system-wide trusted repository are loaded by the extension class loader, whereas the classes in the JARs from system-wide untrusted repository are loaded by the applet class loader. Thus the former classes are given the AllPermission permissions, while the latter are given only default applet permissions.
  2. The repository does not provide version or namespaces control. It is up to the deployer to avoid version and namespaces conflicts at deployment time.
  3. The system-wide trusted repository implementation is based on the system property java.ext.dirs. If the user selects his/her own java.ext.dirs system property via the Java Control Panel, the JARs in the system-wide trusted repository will not be loaded by Java Plug-in.


The APPLET Tag

 Documentation Contents

Here is an example of a simple APPLET tag:

  <applet code="MyApplet.class" width=100 height=140></applet>
This tells the viewer or browser to load the applet whose compiled code is in MyApplet.class (in the same directory as the current HTML document), and to set the initial size of the applet to 100 pixels wide and 140 pixels high.

Here's a more complex example of an APPLET tag:

    <applet codebase="http://java.sun.com/applets/NervousText/1.1"
    code="NervousText.class" width=400 height=75>
    <param name="text" value="Welcome to HotJava!">
    <hr>
    If you were using a Java-enabled browser such as HotJava,
    you would see dancing text instead of this paragraph.
    <hr>
    </applet>
This tells the viewer or browser to load the applet whose compiled code is at the URL http://java.sun.com/applets/NervousText/1.1/NervousText.class, to set the initial size of the applet to 400x75 pixels. The viewer/browser must also set the applet's "text" attribute (which customizes the text this applet displays) to be "Welcome to HotJava!" If the page is viewed by a browser that can't execute Java applets, then the browser will ignore the APPLET and PARAM tags, displaying only the HTML between the <param> and </applet> tags (the alternate HTML).

Here's the result of putting the above example in your HTML file. (The first time you load this page, you may have to wait for the applet to be loaded.)

If you were using a Java-enabled browser such as HotJava, you would see dancing text instead of this paragraph.

Here is another example of an APPLET tag:

     <applet code=A21 width=256 height=256 archive="toir.jar">
     <param name=img value=test.gif>
     <hr>
     We need to convert some of the standard applets to use
     archive.  Any volunteers?
     <hr>
     </applet>
In this example, the applet class is A21. Its bytecodes (may) reside in the archive "toir.jar". This archive may also contain the image resource (see resources documentation) with name test.gif.

Here's the complete syntax for the APPLET tag. Required elements are in bold. Optional elements are in regular typeface. Elements your specify are in italics.

    <APPLET
        CODEBASE = codebaseURL
        ARCHIVE = archiveList
        CODE = appletFile ...or...  OBJECT = serializedApplet
        ALT = alternateText
        NAME = appletInstanceName
        WIDTH = pixels  HEIGHT = pixels
        ALIGN = alignment
        VSPACE = pixels  HSPACE = pixels
    >
    <PARAM NAME = appletAttribute1 VALUE = value>
    <PARAM NAME = appletAttribute2 VALUE = value>
    . . .
    alternateHTML
    </APPLET>

CODE, CODEBASE, and so on are attributes of the applet tag; they give the browser information about the applet. The only mandatory attributes are CODE, WIDTH, and HEIGHT. Each attribute is described below.

CODEBASE = codebaseURL
This OPTIONAL attribute specifies the base URL of the applet--the directory that contains the applet's code. If this attribute is not specified, then the document's URL is used.
ARCHIVE = archiveList
This OPTIONAL attribute describes one or more archives containing classes and other resources that will be "preloaded". The classes are loaded using an instance of an AppletClassLoader with the given CODEBASE.
The archives in archiveList are separated by ",". NB: in JDK1.1, multiple APPLET tags with the same CODEBASE share the same instance of a ClassLoader. This is used by some client code to implement inter-applet communication. Future JDKs may provide other mechanisms for inter-applet communication. For security reasons, the applet's class loader can read only from the same codebase from which the applet was started. This means that archives in archiveList must be in the same directory as, or in a subdirectory of, the codebase. Entries in archiveList of the form ../a/b.jar will not work unless explicitly allowed for in the security policy file (except in the case of an http codebase, where archives in archiveList must be from the same host as the codebase, but can have ".."'s in their paths.)
CODE = appletFile
This REQUIRED attribute gives the name of the file that contains the applet's compiled Applet subclass. This file is relative to the base URL of the applet. It cannot be absolute. One of CODE or OBJECT must be present. The value appletFile can be of the form classname.class or of the form packagename.classname.class.
OBJECT = serializedApplet
This attribute gives the name of the file that contains a serialized representation of an Applet. The Applet will be deserialized. The init() method will *not* be invoked; but its start() method will. Attributes valid when the original object was serialized are *not* restored. Any attributes passed to this APPLET instance will be available to the Applet; we advocate very strong restraint in using this feature. An applet should be stopped before it is serialized. One of CODE or OBJECT must be present.
ALT = alternateText
This OPTIONAL attribute specifies any text that should be displayed if the browser understands the APPLET tag but can't run Java applets.
NAME = appletInstanceName
This OPTIONAL attribute specifies a name for the applet instance, which makes it possible for applets on the same page to find (and communicate with) each other.
WIDTH = pixels HEIGHT = pixels
These REQUIRED attributes give the initial width and height (in pixels) of the applet display area, not counting any windows or dialogs that the applet brings up.
ALIGN = alignment
This OPTIONAL attribute specifies the alignment of the applet. The possible values of this attribute are the same as those for the IMG tag: left, right, top, texttop, middle, absmiddle, baseline, bottom, absbottom.
VSPACE = pixels HSPACE = pixels
These OPTIONAL attributes specify the number of pixels above and below the applet (VSPACE) and on each side of the applet (HSPACE). They're treated the same way as the IMG tag's VSPACE and HSPACE attributes.
<PARAM NAME = appletAttribute1 VALUE = value>
<PARAM NAME = appletAttribute2 VALUE = value> . . .
This tag is the only way to specify an applet-specific attribute. Applets access their attributes with the getParameter() method.
Copyright © 1995-98 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: jdk-comments@java.sun.com 		Sun

Java Software


Tracing and Logging

Tracing and Logging includes the following topics:

  • Tracing
  • Logging
  • Other Options

Tracing

Tracing is a facility to redirect any output in the Java Console to a trace file.

Java Plug-in

Tracing can be turned on by enabling the property javaplugin.trace. However, it turns on all tracing facilities inside Java Plug-in. To enable more fine-grained tracing, javaplugin.trace.option may be used. You can set trace-level options (0-5) in the Java Console, shown in the previous chapter, with the following meanings:

  • 0 — off
  • 1 — basic
  • 2 — network, cache, and basic
  • 3 — security, network and basic
  • 4 — extension, security, network and basic
  • 5 — LiveConnect, extension, security, network, temp, and basic

This enables tracing on the fly.

Another way to set fine-grained tracing is through the Java Control Panel. For instance, to enable tracing for everthing (option 5 above), enter the following in the "Java Run Time Parameters" textfield:

-Djavaplugin.trace=true
-Djavaplugin.trace.option=basic|net|cache|security|ext|liveconnect|temp

Tracing set through the Control Panel will take effect when the Plug-in is launched, but changes made through the Control Panel while a Plug-in is running will have no effect until restart.

Java Web Start

To set the initial trace level for a Java Web Start application set the deployment property deployment.trace.level. The deployment.trace.level property can have one of the following values:

  • basic
  • cache
  • net
  • security
  • ext
  • liveconnect

To use all the tracing level set deployment.trace.level to all.

Logging

Similar to tracing, logging is a facility to redirect any output in the Java Console to a log file using the Java Logging API. To enable logging perform the following actions:

  • Open Java Control Panel
  • Click Advanced tab.
  • Select Enable Logging under the Debugging option

Other Options

File Names

The names of the trace and log files are

plugin<modified version number>.trace
plugin<modified version number>.log

where the <modified version number> includes the major, minor and patch version numbers; e.g., plugin142_06.trace or plugin150.log

File Locations

The default location (directory) of the trace and log files is:

  • <user.home>/.java/deployment/log on Unix/Linux
  • <User Application Data Folder>\Sun\Java\Deployment\log on Windows

where <User Application Data Folder> is as defined here.

If the environment variable USER_JPI_PROFILE is set to <user plugin home> then the trace and log files will be written to:

  • <user plugin home>/.java/deployment/log on Unix/Linux
  • <user plugin home>\Sun\Java\Deployment\log on Windows


Versions Formats

Appendix 2: Sun-Supported Specification-Version and Implementation-Version Formats

Specification-Version and Implementation-Version follow these rules for Sun products, and third-party products must follow the same rules for Java Plug-in to make reliable decisions about whether an extension is up-to-date or not:

The Specification-Version string will be of the form:

n1.n2[.n3]

where n1, n2, and n3 are integers, n1.n2 is the major version number, and optional n3 is the minor version number (also referred to as the maintenance version number).

The Implementation-Version will be of the same form initially but may:

  • append with a preceding underscore("_") n4n5 to indicate a patch version number (also referred to as the update version number)
  • or append with a hyphen ("-") a milestone name (ea , alpha, beta, rc ...), which may also include a trailing integer number (ea1, beta2, rc1 ...).

Both patch version number and milestone name may not be used together in the Implemenation-Version string.

The general form is as follows:

n1.n2[.n3][_<patch_number>|-<milestone_name>]

Integers (n1,n2, n3 ...), letters, dots, hyphens, and underscores , may be used in the version format as described above; no other characters ("*", "+" ...) are allowed.

Note that the Specification-Version and Implementation-Version numbers are in theory independent, though in practice they are often in sync with each other.

Examples:

Specification-Version examples: 1.3, 1.4

Implementation-Version examples: 1.3.1, 1.4.0_02, 1.4.0-beta3

While these are the rules, it is always a good idea when using a third-party extension JAR to examine its MANIFEST.MF file to see what actual values are in it. If it does not follow these rules, you may need to change your applet JAR MANIFEST.MF accordingly or alter the extension JAR.


Windows Online Installation and Java Update FAQ

Questions:

Q. I have "Check for Updates Automatically" checked in the Java Control Panel, but scheduled automatic updates do not seem to happening. Is there something wrong?

Q: I downloaded the installer and it is only 200KB. Why is it so small?

Q: Why does Java Update ask me to reboot?

Q: I had the Java Control Panel open for Java Update and the About tab showed version x.x.x. Then I ran Java Update and it still showed version x.x.x. Why is this?

Q: Netscape/Mozilla is not working correctly with Java Plug-in. Why?

Q: I try to install on the D:\ drive and Java Update is still installing files onto the C:\ drive. Why?

Q: How can I uninstall the Java Update version I just installed?

Q. After the JRE bootstrap installer is downloaded and executed, why does the message "This installer cannot proceed with the current Internet Connection settings of this system. Please check your Control Panel -> Internet Options, and make sure the settings and proxy information are correct, and/or make sure you can view webpages through Internet Explorer" appear?.

Q: I found two processes—jucheck.exe and jusched.exe—running in the background of my system after installing JRE. Is there a way to shut them down?

Q . After Java Update updates my system, my browser still uses the Microsoft VM, or an older version of the Sun Java VM, to run applets. What's wrong?

Q: When I click the Update Now button from the Java Control Panel, it complains about the system being "offline." What does that means?

Q: I followed the instruction to install version x.x.x. After the installation and reboot, a message popped-up from system tray saying an update is available for download. What should I do?

Q: I want to try out Java Update but I am afraid beta software may cause problems on my computer. What should I do?

Q: I encountered the error "Error 1606: Could not access network location file MSI/CAB and still fail after immediate retry." when running the Java SE installer.

Q: I encountered the error "This installation package could not be opened. Contact the application vendor to verify that this is a valid Windows Installer package." when running the Java SE installer.

Q: Error 1311: Source File Not Found. Could not find C:\Downloads\ja555000.cab.

Q: Error 1722. There is a problem with this windows installer package. A program run as part of the setup did not finish as expected. Contact your support personnel or package vender.

Questions and Answers:

Q. I have "Check for Updates Automatically" checked in the Java Control Panel, but scheduled automatic updates do not seem to happening. Is there something wrong?

A: The automatic update feature works only on Windows 2000 with SP3 and WindowsXP. If you are running on one of the other supported operating system, this feature will not work. If you want to do an update, use the Update Now button for manually updating Java.

Q: I downloaded the installer and it is only 200KB. Why is it so small?

A: The Java installer is designed for Install On Demand. It will download more installer files based on user selection and system configuration. Using this installer helps users avoid downloading large amounts of unnecessary files.

Q: Why does Java Update ask me to reboot?

A: Rebooting is sometimes required because installing Windows Installer 2.0 the Microsoft technology used by the Java installer requires rebooting.

Note: Java Installer now detects Java enabled Mozilla browsers locked files and will prompt you to close the browser so that a reboot can be avoided.

Q: I had the Java Control Panel open for Java Update and the About tab showed version x.x.x. Then I ran Java Update and it still showed version x.x.x. Why is this?

A: You need to close and restart the Java Control Panel to get the updated Control Panel.

Q: Netscape/Mozilla is not working correctly with Java Plug-in. Why?

A: First close all the browsers sessions. If this does not work, reboot the system and try again.

Q: I try to install on the D:\ drive and Java Update is still installing files onto the C:\ drive. Why?

A: Regardless of whether an alternate target directory was selected, Java Update needs to install some update files on the Windows system drive . Doing so saves download time on future updates to the latest version of Java.

Q: How can I uninstall the Java Update version I just installed?

There are two ways to accomplish this:

  1. If you want to uninstall the JRE, use the "Add/Remove Programs" utility in the Microsoft Windows Control Panel (Start->Settings->Control Panel to get to "Add/Remove Programs").
  2. Alternatively, if you still have the original installation program that you used to install the JRE, you can double-click on it. This will take you to a screen with Modify and Remove options. Select Remove to uninstall the JRE. Note that you must be connected to the Internet for this to work.

Q. After the JRE bootstrap installer is downloaded and executed, why does the message "This installer cannot proceed with the current Internet Connection settings of your system. In your Windows Control Panel, please check Internet Options -> Connections to make sure the settings and proxy information are correct." appear?.

A: The JRE bootstrap installer uses the system Internet Connection settings to connect to the web for downloading extra files. If you are behind a firewall and require proxy settings, make sure the proxy settings in Internet Options/Internet Properties are set up properly (Start->Control Panel->Internet Options/Internet Properties->Connections->LAN Settings ...).

If you can browser the external web (i.e., outside the firewall) with Internet Explorer, then your proxy settings are properly set up. The installer doesn't understand the proxy settings specified in Netscape/Mozilla.

Q: I found two processes—jucheck.exe and jusched.exe—running in the background of my system after installing JRE. Is there a way to shut them down?

A: jusched.exe is the scheduler process of Java Update; jucheck.exe is the process for checking/performing updates in Java Update. These processes run automatically and transparently to users. To shutdown these processes, simply uncheck the "Check for Updates Automatically" checkbox in the Update tab of Java Control Panel.

Q . After Java Update updates my system, my browser still uses the Microsoft VM, or an older version of the Sun Java VM, to run applets. What's wrong?

A: If you installed the JRE through the Custom option but unchecked the browser selections, you may run into this situation. To fix the problem, go to the Browser tab in Java Control Panel and check the browsers that you want to run the newly installed version of Java.

Q: When I click the "Update Now" button from the Java Control Panel, it complains about the system being "offline." What does that means?

A: Java Update can only be run if the system is connected to the network. A system that is not connected to the network is referred to as being "offline". When the Update Now button is clicked, it will check the online/offline status of your system. If your system is not currently connected to the network or dial-up networking is disconnected, the error message will show up. Check that your system is currently connected to the network and try it again.

Q: I followed the instruction to install version x.x.x. After the installation and reboot, a message popped-up from system tray saying an update is available for download. What should I do?

A: The message is part of the Java Auto Update mechanism, which detects at user login time if a newer version of the JRE is available for download . You may simply click on the system tray Java Update icon to download and install the update.

Q: I want to run Java Update but I am afraid it may cause problems on my computer. What should I do?

A: You may want to backup your Windows registry before testing out Java Update. The following command will export the necessary registry keys to a file:

regedit -e reg.1 -t HKEY_LOCAL_MACHINE
regedit -e reg.2 -t HKEY_CURRENT_USER
regedit -e reg.3 -t HKEY_CLASSES_ROOT

To fully restore the registry keys, the following command can be used to import the exported registry values:

regedit -i reg.1
regedit -i reg.2
regedit -i reg.3

Q: I encountered the error "Error 1606: Could not access network location file MSI/CAB and still fail after immediate retry." when running the Java SE installer.What does it mean?

A: This problem occurs when the server is too busy or when the network is too congested to serve the file. Please retry by running the installer again.

Q: I encountered the error "This installation package could not be opened. Contact the application vendor to verify that this is a valid Windows Installer package." when running the Java SE installer.

A: There are several possible reasons:

  • Network connection fails
  • Download manager software interrupts the download process, e.g., GetRight;
  • TSR (Terminate and Stay Resident) programs, like Norton Anti Virus, may distract the installation process.

To address these problems, please make sure third-party downloader/TSR programs are turned off and the network connection is setup properly. Also, if a proxy is in use, make sure that proxy authentication is turned off.

Q: Error 1311: Source File Not Found. Could not find C:\Downloads\ja555000.cab.

A: This is a known MSI engine problem. See following:

  • http://support.microsoft.com/default.aspx?scid=kb;[LN];Q290106
  • http://support.microsoft.com/default.aspx?scid=kb;[LN];Q307346
  • http://support.microsoft.com/default.aspx?scid=kb;[LN];290896

Q: Error 1722. There is a problem with this windows installer package. A program run as part of the setup did not finish as expected. Contact your support personnel or package vender.

A: If you encounter this error please contact the feedback alias at java-deployment-feedback@sun.com.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.


Deva Search

This page is designed to be viewed by a browser that supports frames.


Deva Search

Java Deployment Search Page
Tips


Deva Search - Help Page

Enter multiple terms with a space between them. The search engine searches for pages that contain any term in the list (using boolean "OR"), except as noted below. As you add more terms, the search result widens.

Search terms are not case sensitive. You can enter terms in any combination of upper and lower case and will get the same results.

Terms may include any of the following characters: A-Z a-z 0-9 _ - . ' , $ %.

Place a plus sign (+) in front of each word that must appear in the results. For example, if you enter +printer +cartridge +maintenance, the search engine will find all pages that have all three words in them. Note that the three words may not necessarily be adjacent to each other, but they will be in the same page.

Place a minus sign (-) in front of words that you do not want to appear in the results. For example, if you enter +printer +cartridge -maintenance, the search engine will find all pages that have the words "printer" and "cartridge" but not "maintenance."

Common words (a, an, the, etc.) are excluded from the search index.


Deva Search - Refresh previous page or no Javascript

Has the Browser Lost Your Search Results?

Click the Back button on your browser, refresh the page, and then click Search.

Is JavaScript Enabled in Your Browser?

To search for terms, your browser must support JavaScript, and JavaScript must be enabled. If your search is not working at all, make sure JavaScript is enabled in your browser by checking your browser preferences or options.


Applet is no longer signed after repackaging signed .cab files ...

Applet is no longer signed after repackaging signed .cab files as .jar files

Symptoms

After repackaging signed .cab files as .jar files, an applet running in the Sun JRE is treated as unsigned. The same applet packaged as .cab files runs as signed in the Microsoft VM.

Cause

Microsoft supports applet signing through its own proprietary Authenticode and .cab file technologies. The signing information is lost in the process of repackaging. As a result, the Sun JVM treats the .jar files as unsigned.

Resolution

The workaround is to sign the .jar files using the jarsigner tool from the JDK:

  1. Obtain the Sun Java Signing certificate from VeriSign or the Java Code Signing certificate from Thawte or similar certificates from other Certificate Authorities (CAs).
  2. Import the certificate into your keystore using keytool and an alias name. For example:
    3. C:\>C:\j2sdk1.5\bin\keytool -import -alias MyCert -file VSSStanleyNew.cer
  3. Use jarsigner to sign the .jar file, using the RSA credentials in your keystore that were generated in the previous step. Make sure the same alias name is specified, for example:
    4. C:\>C:\j2sdk1.5\bin\jarsigner C:\TestApplet.jar MyCert
Enter Passphrase for keystore: ********
  4. Use "jarsigner -verify -verbose -certs" to verify the .jar files.
    C:>C:\jdk1.4.2\bin\jarsigner -verify -verbose
                -certs d:\TestApplet.jar

         245 Wed Mar 10 11:48:52 PST 2000 META-INF/manifest.mf
         187 Wed Mar 10 11:48:52 PST 2000 META-INF/MYCERT.SF
         968 Wed Mar 10 11:48:52 PST 2000 META-INF/MYCERT.RSA
smk      943 Wed Mar 10 11:48:52 PST 2000 TestApplet.class
smk      163 Wed Mar 10 11:48:52 PST 2000 TestHelper.class

      X.509, CN=XXXXXXX YYY, OU=Java Software,
                O=Sun Microsystems, L=Cupertino,
                ST=CA, C=US (mycert)
      X.509, CN=Sun Microsystems, OU=Java Plug-in QA,
                O=Sun Microsystems, L=Cupertino, ST=CA, C=US
      X.509, EmailAddress=server-certs@thawte.com,
                CN=Thawte Server CA, OU=Certification
                Services Division, O=Thawte Consulting cc,
                L=Cape Town, ST=Western Cape, C=ZA

  s = signature was verified
  m = entry is listed in manifest
  k = at least one certificate was found in keystore
  i = at least one certificate was found in identity scope

jar verified.

Related Information

See Code Signing by VerSign and code-signing certificate support by Thawte.


Applet packaged as .cab file ...

Applet packaged as .cab file results in java.lang.ClassNotFoundException thrown when applet runs.

Symptoms

When running an applet in a browser using the Sun JRE, a ClassNotFoundException is thrown by the ClassLoader. The same applet runs under the Microsoft VM.

Cause

This error is caused by applets being packaged as .cab files. The .cab file is an archive format specific to Microsoft Windows, and it is not supported by the Sun JRE.

Resolution

The workaround is to extract the applet classes and resources from the .cab files and repackage them as .jar files using the jar tool from JDK:

jar cvf <jar_file> <input_files>

The <APPLET> tag in the HTML page will also need to be modified to specify the .jar files in the archive attribute. For example,

        <APPLET code="MyApplet"
      width=100 height=100>
<PARAM name="cabbase"
      value="package1.cab, package2.cab">
</APPLET>

should be modified as follows:

<APPLET code="MyApplet" archive="package1.jar, package2.jar" width=100 height=100>
</APPLET>

Related Information

Please refer to the JAR tool documentation for more details.


Deadlock in AWT if methods of the applet are over-synchronized

Symptoms

When running an applet in a browser using the Sun JRE, deadlock may occur if methods of the applet are over-synchronized, especially those inherited from java.awt.Component. The same applet runs under the Microsoft VM.

Cause

The AWT class libraries are sometimes used by developers as thread-safe class libraries. Applets performed actions through the AWT using multiple threads, with the assumption that the class libraries would take care of synchronization issues.

However , the AWT class libraries guarantee thread safety only when calls are made from the AWT event dispatch thread. Because the implementation of the Microsoft VM and Sun differs, thread-unsafe code that runs without incident under one VM might fail under another.

One bad practice used by some applets is to synchronize every method of an applet to avoid possible race conditions or deadlocks in the Microsoft VM. However, this practice may result in deadlocks.

Resolution

To work around this problem, use synchronization in the applet only where it is really needed, and remove unnecessary synchronization. For example:

        public synchronized void
      paint(Graphics g) {
....
}

public synchronized void dispose() {
super.dispose();
.....
}

    public synchronized void stop() {
        ....
    }

    public synchronized void destroy() {
        ....
    }

In this case, the synchronized keyword in the paint, dispose, stop, and destroy methods should be removed because they are always called from a dedicated thread: paint and dispose by the AWT event dispatching thread; stop and destroy by the applet thread. The code should be changed as follows:

        public void paint(Graphics
      g) {
....
}

public void dispose() {
super.dispose();
.....
}

    public void stop() {
        ....
    }

    public void destroy() {
        ....
    }

Related Information

The Java Tutorial discusses thread issues and techniques that apply both to AWT and Swing programs: How to Use Threads.


Either "code" or "object" ...

java.lang.InstantiationException: Either "code" or "object" should be specified, but not both.

Symptoms

When running an applet in a browser using the Sun JRE, an InstantiationException is thrown. The same applet runs under the Microsoft VM.

Cause

There are two possible causes.

  1. Both code and object attributes are specified in the <APPLET> tag:

    <APPLET code=MyApplet object=MyApplet.ser width=100 height=100>
    </APPLET>

    The Sun JRE can access either the code or the object attribute, but not both.
  2. A code attribute is specified in the <APPLET> tag, and an object attribute is specified in a <PARAM> tag :

    <APPLET code=MyApplet width=100 height=100>
    <PARAM name="object" value="someValue">
    </APPLET>

    public class MyApplet extends java.applet.Applet
    {
    public void init()
    {
    String value = getParameter("object");
    }
    ....
    }

    The Sun JRE does not support object as a parameter name.

Resolution

The workaround in the first case is to eliminate the code attribute in the <APPLET> tag:

     <APPLET object=MyApplet.ser width=100 height=100>
     </APPLET>

The workaround in the second case is to change the parameter name to a different name:

     <APPLET code=MyApplet width=100 height=100>
     <PARAM name="property1" value="someValue">
     </APPLET>

     public class MyApplet extends java.applet.Applet
     {
     public void init()
     {
      String value = getParameter("property1");
     }
     ....
     }

Related Information

N/A


Internet/Intranet Deployment of the Sun JRE

Internet deployment

If you would like to have your internet customers download Sun's Java Runtime Enivronment (JRE) to run your applets inside Internet Explorer, you should consider hosting the Java(tm) Technology Logos at your web site. More information is available about the logos at:

http://logos.sun.com/logosite.jsp?Category=third#java

When users click on any one of these logos, they will be prompted with a security dialog box asking if they want to install and run Java Plug-in, signed and distributed by Sun Microsystems. If they agree to install, the browser will download and launch the installer. The user will have to go through a few installer dialogs to successfully install Java Plug-in on their system. After a successfull installation, the browser will display a confirmation message, and the system tray will contain a Java icon, indicating the system is running the Sun's JRE.

Intranet deployment

You can distribute Sun's JRE to intranet users by hosting the .msi file on an internal web site and asking users to launch the installer through msiexec. The other option is to install the JRE through Active Directory. If you are using Active Directory, you may have to customize the .msi file, which is known as creating a transform.

You can obtain the .msi file for the JRE installer by installing the JRE offline Windows installer. After installation, the .msi file, jre1.6.0.msi, will be available in the directory AppDataFolder\jre1.6.0, whereAppDataFolder is the user's "Application Data" folder (typically something like C:\Documents and Settings\username\Application Data), and CLSID is a long string like 7148F0A6-6813-11D6-A77b-00B0D0142010, depending on the release.


Java Plug-in does not use the certificates in the browser certificate store

Java Plug-in does not use the certificates in the browser certificate store for HTTPS client authentication.

Symptoms

Unable to use certificates from the browser for client authentication.

Cause

The Java Plug-in uses certificates for client authentication from a certificate store specific to the JRE. It does not use the certificates from the browser certificate store.

Resolution

Client authentication in Java Plug-in requires the client certificate store on the user disk, keystore type, and the password to access it. These three parameters should be provided with system properties as follows:

-Djavax.net.ssl.keyStore=<client_keystore_file_path>
-Djavax.net.ssl.keyStorePassword=<password to access the client keystore file>
-Djavax.net.ssl.keyStoreType=<keystore_type>

These properties should be specified in the Advanced tab of the Java Control Panel.

Here are the steps to export a digital certificate from the browser certificate store into a file:

  1. Open a browser window, click on Tools, then click the Internet Options submenu item.
  2. Click the Content tab.
  3. In the certificates section in the middle, click the Certificates button. The available certificates are shown in the dialog box.
  4. Select Client Authentication in the Intended Purpose drop down menu.
  5. Select the certificate you want to export.
  6. Click the Export button. The Certificate Manager Export Wizard starts.
  7. On the Welcome window, click Next.
  8. Keep the default to "Yes, export the private key" and click Next.
  9. Keep the default to "Personal Information Exchange - PKCS #12(.PFX)" and click Next.
  10. Complete the Password window.
  11. Type the path and filename of the file to export. The system automatically gives it a .pfx extension. Click Next.
  12. Review the information and click Finish.

Example:

If the user exports the certificate to a file called (path included) c:\certs\client.pfx and uses the password "test" to protect the .pfx file, the required system properties will take the following values:

-Djavax.net.ssl.keyStore=c:\certs\client.pfx
-Djavax.net.ssl.keyStorePassword=test
-Djavax.net.ssl.keyStoreType=pkcs12

Related Information

N/A


java.lang.ClassCastException thrown ...

java.lang.ClassCastException thrown from the AWT event dispatching thread when the mouse moves over an applet frame

Symptoms

When running an applet in a browser using the Sun JRE, a ClassCastException is thrown from the AWT event dispatching thread when the mouse moves over the applet's frame. The same applet runs under the Microsoft VM.

java.lang.ClassCastException: sun.plugin....
         at MyApplet.mouseExit(Unknown Source)
         at java.awt.Component.handleEvent(Unknown Source)
         at java.awt.Component.postEvent(Unknown Source)
         at java.awt.Component.dispatchEventImpl(Unknown Source)
         at java.awt.Container.dispatchEventImpl(Unknown Source)
         at java.awt.Component.dispatchEvent(Unknown Source)
         at java.awt.EventQueue.dispatchEvent(Unknown Source)
         at java.awt.EventDispatchThread.pumpOneEventForHierarchy(Unknown Source)
         at java.awt.EventDispatchThread.pumpEventsForHierarchy(Unknown Source)
         at java.awt.EventDispatchThread.pumpEvents(Unknown Source)
         at java.awt.EventDispatchThread.run(Unknown Source)

Cause

This exception has two possible causes:

  1. To track mouse events on its frame, the applet tries to register MouseListener on the frame. In the Microsoft VM implementation, the applet's direct parent in the AWT hierarchical component tree is the frame. While this is implementation specific and subject to change, some applets rely on this in their code:

    public void foo()
    {
            Frame f = (Frame) getParent();
            ....
    }

    Because the Sun JRE has other containers between the applet and the frame, getParent() does not return a Frame object, and the above code results in a ClassCastException.
  2. In the Microsoft VM implementation, java.applet.AppletContext is implemented by the applet frame. While this is implementation specific and subject to change, some applets rely on this in their code:

    public void foo()
{
Frame f = (Frame) getParent();
....
AppletContext ac = (AppletContext)
        f;
....
}

    Because the Sun JRE implements AppletContext using a different object, the above code results in a ClassCastException.

Resolution

The workaround in the first case is to navigate the entire AWT hierarchical component tree from the applet to locate the frame, instead of relying on a frame being at a particular level of containment:

 public void foo()
{
// Navigate component tree
Container c = getParent();
while (c != null && (c instanceof
        Frame) == false)
c
        = c.getParent();

// Cast Container to Frame
if (c instanceof Frame)
{
Frame f =
        (Frame) c;
...
}
}

The workaround in the second case is to access AppletContext using the Applet.getAppletContext() method:

public void foo()
    {
         ....
         AppletContext ac = (AppletContext) getAppletContext();
         ...
    }

Related Information

N/A


java.lang.ClassFormatError ...

java.lang.ClassFormatError thrown when applet runs

Symptoms

When running an applet in a browser using the Sun JVM, a ClassFormatError is thrown by the ClassLoader. The same applet runs under the Microsoft VM.

Cause

This error is caused by bytecodes generated from old JDK 1.0.2/1.1 compilers, or from a third-party obfuscator. In the past, many of these compilers and obfuscators generated bytecode that does not conform to the Java VM Specification. Because the verifiers in recent J2SE releases are much stricter about bad class format, the ClassFormatError is thrown by the VM when these bad class files are loaded.

Some typical problems in some older class files are the following (note that this list is not exhaustive):

  • There are extra bytes at the end of the class file.
  • The class file contains method or field names that do not begin with a letter.
  • The class attempts to access private members of another class.
  • The class file has other format errors, including illegal constant pool indices and illegal UTF-8 strings.
  • The class file produced by an early (third-party) bytecode obfuscator violates proper class-file format.

Resolution

To allow some of the applets with bad class files to run in the Java platform, Java Plug-in contains a bytecode transformer to transform some of the bad class files to good ones. Currently, only bad class files with the following problems may be transformed:

  • Local variable name with a bad constant pool index
  • Extra bytes at the end of the class file
  • Code segment of the wrong length
  • Illegal field/method name
  • Illegal field/method modifiers
  • Invalid start_pc/length in local var table

Unfortunately, the bytecode transformer cannot transform the following problems, which will still result in a ClassFormatError:

  • Illegal use of nonvirtual function call
  • Arguments can't fit into locals
  • Unsorted lookup switch
  • Truncated class file

You can resolve these problems by simply recompiling your Java classes with the javac compiler from the JDK. If you choose to use a third-party obfuscator, be sure to use one that produces class files that respect proper class-file format.

Related Information

N/A


java.lang.ClassNotFoundException thrown ...

java.lang.ClassNotFoundException thrown on com.ms.* package when applet runs

Symptoms

When running an applet in a browser using the Sun JRE, a ClassNotFoundException is thrown by the ClassLoader on the com.ms.* package. The same applet runs under the Microsoft VM.

Cause

The Microsoft VM provides many proprietary class libraries, including J/Direct, AFC, and WFC. These package are not available in the Sun JRE, so a ClassNotFoundException is thrown when the applet runs.

Resolution

The workaround is to migrate the applet source code from using the Microsoft proprietary class libraries to similar classes in the Java platform.

Microsoft VM | Java Platform
J/Direct | Java Native Interface
Application Foundation Classes | Swing, Java 2D APIs
Windows Foundation Classes | Swing, Java 2D APIs

Related Information

How to avoid potential pitfalls of Microsoft's non-standard SDK for Java
 Lesson: User Interfaces that Swing: A Quick Start Guide
 Trail: Creating a GUI with JFC/Swing
Trail: Java Native Interface


java.lang.ClassNotFoundException thrown ...

java.lang.ClassNotFoundException thrown on com.ms.security package when applet runs

Symptoms

When running an applet in a browser using the Sun JRE, a ClassNotFoundException is thrown by the ClassLoader on the com.ms.security package. The same applet runs under the Microsoft VM.

Cause

The Microsoft VM provides the proprietary com.ms.security package for applets and applications to access the security policy at runtime. This package is not available in the Sun JRE, so a ClassNotFoundException is thrown when the applet runs.

Resolution

The workaround is to migrate the applet source from using the com.ms.security package to using similar classes in the java.security package.

For example, the following applet uses com.ms.security.PolicyEngine to assert the network I/O permission before connecting to a URL.

public class AssertPermissionApplet extends java.applet.Applet
{
    public void init()
    {
        try
        {
            // Assert permission on network I/O
            com.ms.security.PolicyEngine.assertPermission
            (com.ms.security.PermissionID.NETIO);
            java.net.URL url = new java.net.URL(
            "http://randomhost/randomfile");
            .....
        } catch (java.net.MalformedURLException mue) {
        }
        catch (java.io.IOException ioe) {
        }
      } // init
}

In the Java platform, java.security.AccessController provides similar functionality for permission assertion. Here is the source code after migration:

public class AssertPermissionApplet extends java.applet.Applet
{
    public void init()
    {
        try
        {
            // Assert permission on network I/O
            java.net.AccessController.checkPermission(new             java.net.SocketPermission("randomhost:80", "connect, accept"));
            java.net.URL url = new java.net.URL(
            "http://randomhost/randomfile");
            .....
        } catch (java.net.MalformedURLException mue) {
        }
        catch (java.io.IOException ioe) {
        }
      } // init
}

Please refer to the Java SE API documentation for more details on security.

Related Information

See Security.


java.lang.IllegalArgumentException thrown in java.awt.Color constructor ...

Symptoms

When running an applet in a browser using the Sun JRE, an IllegalArgumentException is thrown in the java.awt.Color constructor. The same applet runs under the Microsoft VM.

Cause

This exception is caused by passing over-bound or under-bound values to the Color constructor in the Sun JRE.

The Java class libraries in the Sun JRE have changed over time. Some APIs have been clarified, some have been deprecated, and some have had their implementation altered.

The result of passing over-bound/under-bound values in the Color constructor was not well defined, and the Microsoft VM would automatically readjust the values to maximum color values and minimum color values automatically. The Sun JRE took a different approach, using an IllegalArgumentException to let the programmer know that they specified an out-of-bounds value.

Resolution

Code defensively to ensure only valid color values are passed to the Color constructor. For example,

  void Color newColor(int r, int g, int b)
        {
            return new Color(r, g, b);
        }

The code should be changed to

        int ensureColorRange(int v)
        {
            if (v < 0)
                return 0;
            else if (v > 255)
                return 255;
            else
                return v;
        }
        void Color newColor(int r, int g, int b)
        {
            r = ensureColorRange(r);
            g = ensureColorRange(g);
            b = ensureColorRange(b);

            return new Color(r, g, b);
        }

Related Information

N/A


java.lang.NullPointerException thrown from a thread ...

java.lang.NullPointerException thrown from a thread when Applet.start() or Applet.stop() is called

Symptoms

When running an applet in a browser using the Sun JRE, a NullPointerException is thrown from a thread when Applet.start() or Applet.stop() is called. The same applet runs under the Microsoft VM.

Cause

In the Microsoft VM, an applet may be visible immediately after Applet.init() is called but before Applet.start(). Similarly, an applet may still be visible after Applet.stop() but before Applet.destroy().

The Sun JRE implementation is slightly different in terms of applet visibility related to the lifecycle methods, so any applet that relies on the Microsoft VM event sequences may break.

Resolution

Code defensively to ensure the applet is visible before drawing. One way to do this is to test whether the Graphics object is null. For example, suppose the applet has the following methods:

        private Thread paintThread
      = null;

public void start()
{
if (paintThread == null)
{
paintThread = new Thread(this);
paintThread.start();
}
}

        public void stop()
{
if (paintThread != null)
{
paintThread.interrupt();    // Assuming the thread
      has sufficient                                       //
      time to be interrupted and stop                                       //
      drawing before destroy() is called.
paintThread = null;
}
}

public void run()
{
while (Thread.currentThread().isInterrupted() == false)
{
Graphics g = getGraphics();
g.drawString("Hello World", 100, 100);   //
      NullPointerException if                                                      //
      applet is not visible -
//
      g will be null !
}
}

The code for the run
      method should be changed to the following:

public void run()
{
while (Thread.currentThread().isInterrupted() == false)
{
Graphics g = getGraphics();

      if (g != null)               //
      Code defensively!
g.drawString("Hello World", 100, 100);
}
}

Related Information

N/A


java.security.AccessControlException thrown ...

java.security.AccessControlException thrown when applet calls java.beans.Introspector.setBeanInfoSearchPath()

Symptoms

When running an applet in a browser using the Sun JRE, an AccessControlException is thrown in the execution of Introspector.setBeanInfoSearchPath():

java.security.AccessControlException: access denied (java.util.PropertyPermission * read,write)
    at java.security.AccessControlContext.checkPermission(Unknown Source)
    at java.security.AccessController.checkPermission(Unknown Source)
    at java.lang.SecurityManager.checkPermission(Unknown Source)
    at java.lang.SecurityManager.checkPropertiesAccess(Unknown Source)
    at java.beans.Introspector.setBeanInfoSearchPath(Unknown Source)
    at ....

The same applet runs under the Microsoft VM.

Cause

The Introspector.setBeanInfoSearchPath() method call can change the list of package names used for finding BeanInfo classes. If more than one applet is running in the VM, an untrusted applet could call this method to redirect other applets to look up BeanInfo in unexpected packages. This is a security hole.

A security check for java.util.PropertyPermission was added to this method in the JRE to address the security concern. If the applet is unsigned and it calls into this method, an AccessControlException will be thrown.

Resolution

The workaround is to either:

  1. Sign the applet using the JDK jarsigner tool, so that the applet runs as a trusted applet and has permissions to call the Introspector.setBeanInfoSearchPath() method.
  2. Rearchitect the applet code to avoid the call to Introspector.setBeanInfoSearchPath(). For example, instead of relying on the BeanInfo search path, use a fully qualified package name for looking up the BeanInfo.

Related Information

See jarsigner - JAR Signing and Verification Tool.


java.security.AccessControlException thrown ...

java.security.AccessControlException thrown in stop, suspend, or resume method of java.lang.Thread

Symptoms

When running an applet in a browser using the Sun JRE, an AccessControlException is thrown in the stop, suspend, or resume method of java.lang.Thread.

java.security.AccessControlException: access denied (java.lang.RuntimePermission modifyThread)
        at java.security.AccessControlContext.checkPermission(Unknown Source)
        at java.security.AccessController.checkPermission(Unknown Source)
        at java.lang.SecurityManager.checkPermission(Unknown Source)
        at sun.applet.AppletSecurity.checkAccess(Unknown Source)
        at java.lang.Thread.checkAccess(Unknown Source)
        at java.lang.Thread.stop(Unknown Source)
        at ....

The same applet runs under the Microsoft VM.

Cause

This exception is caused by calling these methods on a dead Thread object in the Sun JRE.

The Java class libraries in the Sun JRE have changed over time. Some APIs have been clarified, some have been deprecated, and some have had their implementation altered.

The result of calling stop, suspend, and resume on a dead Thread object was not well defined. In the Microsoft VM, they result in a no-op. However, in the Sun JRE, calling these methods on a dead Thread object invalidates the underlying invariant of the implementation, thus resulting in an AccessControlException.

Resolution

The Thread stop, suspend, and resume methods are inherently unsafe and have been deprecated in the Java platform.

To work around this problem, replace calls to stop, suspend, and resume with code that simply modifies some variable to indicate that the target thread should stop/suspend/resume.

For example, suppose your applet contains the following methods:

    private Thread blinker;

    public void start() {
        blinker = new Thread(this);
        blinker.start();
    }

    public void stop() {
        blinker.stop();  // UNSAFE!
    }
    public void destroy() {
        blinker.stop();  // UNSAFE and WILL throw AccessControlException in the Sun JRE!
    }

    public void run() {
        Thread thisThread = Thread.currentThread();
        while (true) {
            try {
                thisThread.sleep(interval);
            } catch (InterruptedException e){
            }
            repaint();
        }
    }

You can avoid the use of Thread.stop by replacing the applet's stop, destroy, and run methods with:

    private volatile Thread blinker;

    public void stop() {
        blinker = null;
    }

    public void destroy() {
        blinker = null;
    }

    public void run() {
        Thread thisThread = Thread.currentThread();
        while (blinker == thisThread) {
            try {
                thisThread.sleep(interval);
            } catch (InterruptedException e){
            }
            repaint();
        }
    }

Another example: Suppose your applet contains the following mousePressed event handler, which toggles the state of a thread called blinker:

    private boolean threadSuspended;

    public void mousePressed(MouseEvent e) {
        e.consume();

        if (threadSuspended)
            blinker.resume();
        else
            blinker.suspend();  // DEADLOCK-PRONE!

        threadSuspended = !threadSuspended;
    }

    public void run()
    {
     while (true) {
        try {
            Thread.currentThread().sleep(interval);
        } catch (InterruptedException e){
        }
        repaint();
    }

You can avoid the use of Thread.suspend and Thread.resume by replacing the event handler above with the following:

    private boolean volatile threadSuspended;

    public synchronized void mousePressed(MouseEvent e) {
        e.consume();

        threadSuspended = !threadSuspended;

        if (!threadSuspended)
            notify();
    }

    public void run() {
        while (true) {
            try {
                Thread.currentThread().sleep(interval);

                if (threadSuspended) {
                    synchronized(this) {
                        while (threadSuspended)
                            wait();
                    }
                }
            } catch (InterruptedException e){
            }
            repaint();
        }
    }

Related Information

Why Are Thread.stop, Thread.suspend, Thread.resume, and Runtime.runFinalizersOnExit Deprecated?


NullPointerException thrown in java.awt.Graphics.drawImage()

Symptoms

When running an applet in a browser using the Sun JRE, a NullPointerException is thrown in the java.awt.Graphics.drawImage method. The same applet runs under the Microsoft VM.

Cause

This exception is caused by passing a null image to the drawImage method in the Sun JRE.

The Java class libraries in the Sun JRE have changed over time. Some APIs have been clarified, some have been deprecated, and some have had their implementation altered.

The result of passing a null image into the Graphics.drawImage method was not well defined, and the Microsoft VM treats null image as a no-op. However, most versions of the Sun JRE do not accept null as a valid image, thus resulting in a NullPointerException. As of 5.0, the specification has been clarified, and a null image argument is treated as a no-op.

Resolution

In JRE versions before 5.0, code defensively to ensure that only non-null images are passed to the drawImage method. For example:

Graphics g = getGraphics();
    g.drawImage(img, 100, 100, this);

The code should be changed to:

Graphics g = getGraphics();
if (img != null)
g.drawImage(img, 100, 100, this);

Related Information

N/A


NullPointerException thrown in java.awt.Graphics.drawString()

Symptoms

When running an applet in a browser using the Sun JRE, a NullPointerException is thrown by the java.awt.Graphics.drawString()method. The same applet runs under the Microsoft VM.

Cause

This exception is caused by passing a null string to the Graphics.drawString() method in the Sun JRE.

The Java class libraries in the Sun JRE have changed over time. Some APIs have been clarified, some have been deprecated, and some have had their implementation altered.

The result of passing a null string to the Graphics.drawString() method was not well defined, and the Microsoft VM treats null as an empty string. However, the implementation in the Sun JRE does not accept null as a valid string, thus resulting in a NullPointerException.

Resolution

Code defensively to ensure only a non-null string is passed to the drawString() method. For example, the following code

Graphics g = getGraphics();
g.drawString(s, 100, 100);

should be changed to:

Graphics g = getGraphics();
if (s !== null) {
   g.drawString(s, 100, 100);
}

Related Information

N/A


Redirection between HTTP URL and HTTPS URL is not followed.

Redirection between HTTP and HTTPS URLs is not followed.

Symptoms

When running an applet in a browser using the Sun JRE, if the applet makes HTTP requests to a server which redirects to an HTTPS URL, the redirection fails. It fails also in the case of making HTTPS requests to a server which redirects to an HTTP URL. The same applet runs without error in the Microsoft VM.

Cause

The issue is caused by the HTTP/HTTPS redirection policy implemented in Sun JRE; because of serious security consequences, redirection between HTTP and HTTPS is not automatically followed.

With the Microsoft VM, a security warning dialog prompts the user for consent for any redirection. Redirection occurs only if the user consents to it.

Resolution

To work around the problem, it is the application's responsibility to check the response code and recognize it as a redirect. The Location header field value can be checked for the redirect information, and then the application must decide whether or not to follow the redirect using the new protocol. For example, the following code

public void makeConnection(URL url)
{
URLConnection conn = url.openConnection();
InputStream is = conn.getInputStream();
....
is.close();
}

should be changed to

 private InputStream openConnectionCheckRedirects(URLConnection
        c) throws IOException
{
boolean redir;
int redirects = 0;
InputStream in = null;
do
{
if (c instanceof HttpURLConnection)
{
((HttpURLConnection)
        c).setInstanceFollowRedirects(false);
}
// We want to open the
        input stream before getting headers
// because getHeaderField() et al
        swallow IOExceptions.
in = c.getInputStream();
redir = false;
if (c instanceof HttpURLConnection)
{
HttpURLConnection
        http = (HttpURLConnection) c;
int stat = http.getResponseCode();
if (stat >= 300
        && stat <= 307 && stat != 306 &&
stat
        != HttpURLConnection.HTTP_NOT_MODIFIED)
{
URL
        base = http.getURL();
String
        loc = http.getHeaderField("Location");
URL
        target = null;
if
        (loc != null)
{
target
        = new URL(base, loc);
}
http.disconnect();
//
        Redirection should be allowed only for HTTP and HTTPS
//
        and should be limited to 5 redirections at most.
if
        (target == null || !(target.getProtocol().equals("http")
||
        target.getProtocol().equals("https"))
||
        redirects >= 5)
{
throw
        new SecurityException("illegal URL redirect");
}
redir
        = true;
c
        = target.openConnection();
redirects++;
}
}
}
while (redir);
return in;
}

public void makeConnection(URL url){
   URLConnection conn = url.openConnection();
   InputStream is = openConnectionCheckRedirects(conn);
   ....
   is.close();
}

Related Information

N/A


Redirection between HTTP URL and HTTPS URL is not followed.

BOLD CJK fonts are hard to read.

Symptoms

CJK (Chinese-Japanese-Korean) fonts, when displayed in BOLD, are hard to read.

Cause

CJK fonts, when displayed in bold, are sometimes overly BOLD and so may be difficult to read at small sizes (typically 16 pt or less).

Resolution

If this is a problem, then always specify the font as PLAIN.

Related Information

N/A


Signed applet upgraded from .cab to .jar files ...

Signed applet upgraded from .cab to .jar files throws a security exception when run in Microsoft VM

Symptoms

After upgrading a signed applet from .cab to .jar files, the applet no longer works in the Microsoft VM. The applet runs fine in the Sun JRE.

Cause

This error is caused by a lack of signed .jar file support in the Microsoft VM. While the Microsoft VM supports unsigned .jar files through the archive attribute of the <APPLET> tag, classes and resources within signed .jar files are treated as untrusted in the Microsoft VM.

As a result, the applet is treated as untrusted by the Microsoft VM; any action performed by the applet that requires access outside the applet sandbox will likely result in a security exception.

Resolution

The only applet signing scheme recognized by the Microsoft VM is Authenticode used with .cab files.

The workaround is specify the upgraded .jar files through the archive attribute for the Sun JVM, and continue to specify the .cab files through cabbase for the Microsoft VM. For example,

<APPLET code="MyApplet" width=100 height=100>
<PARAM name="cabbase" value="package1.cab, package2.cab">
</APPLET>

should be changed to

<APPLET code="MyApplet" archive="package1.jar, package2.jar"
width=100 height=100>
<PARAM name="cabbase" value="package1.cab, package2.cab">
</APPLET>

Related Information

N/A


Upgrading From the Microsoft to the Sun Java Virtual Machine

Java Upgrade Guide:
Migrating From the Microsoft VM
for Java to the Sun JRE
Search Guide

This guide explains why and how to upgrade applets from the Microsoft Virtual Machine (VM) for Java to the Sun JRE. In 98% of cases, applets run unchanged under the Sun JRE. For the remaining 2%, this document points to migration tips. The results of upgrading should be richly rewarding, as the Microsoft VM is based upon version 1.1, an early, 1997 version of Java technology. The latest, standards-compliant version from Sun Microsystems is 1.4.2. Released in 2003, it includes many enhancements over the early version.

Why Upgrade?

The Microsoft VM, based upon Java 1.1 technology that is over five years old, is clearly outmoded. On the other hand Sun Microsystem's VM, which is part of Sun's 1.4.2 Java Runtime Environment (JRE), is thoroughly standards compliant and up to date. That makes one good reason for upgrading Java applets and applications to run on the Sun JRE. But there are other compelling reasons: millions of copies of the Sun JRE have already been downloaded and deployed, and millions of new computers will soon be shipping with the Sun JRE. The time is ripe for upgrading.

Another reason to upgrade is that after September, 2004, Microsoft will no longer support or provide a Java implementation with any of its products. Microsoft has already discontinued shipping Java technology in its Internet Explorer web browser with the latest versions of its operating systems. This has two important implications:

  • Those running applets in the Internet Explorer web browser will need to download and install an alternate VM.
  • In a very few cases, developers will need to modify applets that use proprietary features of the Microsoft VM so they will continue to work.

Note that while Microsoft makes a case for migrating Java applets and applications to J# or C#, neither of these solutions offers cross-platform capability. J# and C# run only on the Microsoft Windows platform.

How to Upgrade

Here are the steps for upgrading to the Sun JRE:

  1. Install the Sun JRE if it is not already installed.
  2. Check that your browser uses the Sun JRE and not the old Microsoft VM.
  3. Test your applet with the Sun JRE to determine if the applet runs correctly. If the applet doesn't run correctly, find the problem in the list of Potential Upgrade Issues. Click on any issue to see an article that discusses the synopsis, symptom, cause, resolution, and related information, for that issue.

Although most applets run correctly in the Sun JRE, testing is always a good idea. If you should detect an issue, the solution is at hand. Once you have upgraded your applets, they will be able to run on a robust, secure, cross-platform, standards-compliant version of the Java platform.

Once you have confirmed that your applet works properly with the Sun JRE, you may want to consider the best way of deploying the Sun JRE for users. See Internet/Intranet Deployment of the Sun JRE.

Installing the Sun JRE

If you don't already have the Sun JRE installed on your test computer, click below to get it.

Checking the VM/JRE

Before you test your applet, you need to make sure that your browser is running the Sun JRE.

To do so, first open the Windows Control Panel (Start > Settings > Control Panel), then double-click the coffee-cup icon labeled Java Plug-in to launch the Java Plug-in Control Panel. When it appears, select the Browser tab. It looks like this:

Make sure that the check box for the browser you are using is checked.

Next, verify that your browser is running the Sun JRE. If it is, when you run the applet you should:

  • see the Java icon in the system tray
  • initially see the Java icon in the browser window's gray applet-loading box;

Java Icon in System Tray:

Java Logo in Gray Box:

Note: If you have Show Java Console selected in the Java Plug-in Control Panel (Basic tab), then the Java Console displays and shows a Java version number, as shown in the next section. The version number indicates which Sun JRE is being used by your browser.

Testing Your Applet

Test your applet by running it. If you have a set of standard tests for it, run it through those tests.

If there is a compatibility issue, you will see details about it in the Java Console. The Java Console looks like this:

For details about the Java Console, see http://java.sun.com/j2se/1.4.2/docs/technotes/guides/plugin/developer_guide/console.html

Potential Upgrade Issues

Here are some potential issues, listed by symptoms, that you might encounter:

  • When running an applet in a browser using the Sun JRE, a ClassFormatError is thrown by the ClassLoader. The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, a ClassNotFoundException is thrown by the ClassLoader. The same applet runs under Microsoft VM.
  • After repackaging the signed .cab files as .jar files, an applet running in the Sun JRE is treated as unsigned. The same applet packaged as .cab files runs as signed in the Microsoft VM.
  • After upgrading the signed applet from .cab to .jar to run in the Sun JRE, the applet no longer works in the Microsoft VM. The applet runs fine in the Sun JRE.
  • When running an applet in a browser using Sun's JRE, an AccessControlException is thrown in the execution of Introspector.setBeanInfoSearchPath() .The same applet runs under the Microsoft VM.
  • When running an applet in a browser using Sun JRE, a ClassNotFoundException is thrown by the ClassLoader on the com.ms.security package. The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, a ClassNotFoundException is thrown by the ClassLoader on the com.ms.* package. The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, deadlock may occur if methods of the applet are over-synchronized, especially those inherited from java.awt.Component. The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, a ClassCastException is thrown from the AWT Dispatch Event Thread when mouse moves over the applet frame. The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, a NullPointerException is thrown from a thread when Applet.start() or Applet.stop() is called. The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, a NullPointerException is thrown in java.awt.Graphics.drawString(). The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, a NullPointerException is thrown in java.awt.Graphics.drawImage(). The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, an IllegalArgumentException is thrown in java.awt.Color constructor. The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, an AccessControlException is thrown in stop(), suspend(), or resume() of java.lang.Thread. The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, an InstantiationException is thrown. The same applet runs under the Microsoft VM.
  • Unable to use certificates from the browser for client authentication.
  • When running an applet in a browser using the Sun JRE, if the applet makes HTTP requests to a server which redirects to an HTTPS URL, the redirection fails. It fails also in the case of making HTTPS requests to a server which redirects to an HTTP URL. The same applet runs without error in the Microsoft VM.
  • CJK (Chinese-Japanese-Korean) fonts, when displayed in BOLD, are hard to read.

If you run into an issue not covered in the preceeding list, please see the Java Upgrade Forum:

http://forum.java.sun.com/forum.jsp?forum=481


Search Java Upgrade Guide

Enter multiple terms with a space between them. The search engine searches for any instance of each term in the list.

Search terms are not case sensitive. You can enter terms in any combination of upper and lower case.

Terms may include any of the following characters: A-Z a-z 0-9 _ - . ' , $ %.

Place a plus sign (+) in front of each word that must appear in the results. For example, if you enter +printer +cartridge +maintenance, the search engine will find all pages that have all three words in them. Note that the three words may not necessarily be adjacent to each other, but they will be in the same page.

Place a minus sign (-) in front of words that you do not want to appear in the results. For example, if you enter +printer +cartridge -maintenance, the search engine will find all pages that have the words "printer" and "cartridge" but not "maintenance."

Common words (a, an, the, etc.) are excluded from the search index.


Search Java Upgrade Guide

This page is designed to be viewed by a browser which supports frames.


Search Java Upgrade Guide

Search the Java Upgrade Guide
Tips


Upgrading From the Microsoft to the Sun Java Virtual Machine

Java Upgrade Guide:
Migrating From the Microsoft VM
for Java to the Sun JRE
Search Guide

This guide explains why and how to upgrade applets from the Microsoft Virtual Machine (VM) for Java to the Sun JRE. In 98% of cases, applets run unchanged under the Sun JRE. For the remaining 2%, this document points to migration tips. The results of upgrading should be richly rewarding, as the Microsoft VM is based upon version 1.1, an early, 1997 version of Java technology. The latest, standards-compliant version from Sun Microsystems is 1.4.2. Released in 2003, it includes many enhancements over the early version.

Why Upgrade?

The Microsoft VM, based upon Java 1.1 technology that is over five years old, is clearly outmoded. On the other hand Sun Microsystem's VM, which is part of Sun's 1.4.2 Java Runtime Environment (JRE), is thoroughly standards compliant and up to date. That makes one good reason for upgrading Java applets and applications to run on the Sun JRE. But there are other compelling reasons: millions of copies of the Sun JRE have already been downloaded and deployed, and millions of new computers will soon be shipping with the Sun JRE. The time is ripe for upgrading.

Another reason to upgrade is that after September, 2004, Microsoft will no longer support or provide a Java implementation with any of its products. Microsoft has already discontinued shipping Java technology in its Internet Explorer web browser with the latest versions of its operating systems. This has two important implications:

  • Those running applets in the Internet Explorer web browser will need to download and install an alternate VM.
  • In a very few cases, developers will need to modify applets that use proprietary features of the Microsoft VM so they will continue to work.

Note that while Microsoft makes a case for migrating Java applets and applications to J# or C#, neither of these solutions offers cross-platform capability. J# and C# run only on the Microsoft Windows platform.

How to Upgrade

Here are the steps for upgrading to the Sun JRE:

  1. Install the Sun JRE if it is not already installed.
  2. Check that your browser uses the Sun JRE and not the old Microsoft VM.
  3. Test your applet with the Sun JRE to determine if the applet runs correctly. If the applet doesn't run correctly, find the problem in the list of Potential Upgrade Issues. Click on any issue to see an article that discusses the synopsis, symptom, cause, resolution, and related information, for that issue.

Although most applets run correctly in the Sun JRE, testing is always a good idea. If you should detect an issue, the solution is at hand. Once you have upgraded your applets, they will be able to run on a robust, secure, cross-platform, standards-compliant version of the Java platform.

Once you have confirmed that your applet works properly with the Sun JRE, you may want to consider the best way of deploying the Sun JRE for users. See Internet/Intranet Deployment of the Sun JRE.

Installing the Sun JRE

If you don't already have the Sun JRE installed on your test computer, click below to get it.

Checking the VM/JRE

Before you test your applet, you need to make sure that your browser is running the Sun JRE.

To do so, first open the Windows Control Panel (Start > Settings > Control Panel), then double-click the coffee-cup icon labeled Java Plug-in to launch the Java Plug-in Control Panel. When it appears, select the Browser tab. It looks like this:

Make sure that the check box for the browser you are using is checked.

Next, verify that your browser is running the Sun JRE. If it is, when you run the applet you should:

  • see the Java icon in the system tray
  • initially see the Java icon in the browser window's gray applet-loading box;

Java Icon in System Tray:

Java Logo in Gray Box:

Note: If you have Show Java Console selected in the Java Control Panel, then the Java Console displays and shows a Java version number, as shown in the next section. The version number indicates which Sun JRE is being used by your browser.

Testing Your Applet

Test your applet by running it. If you have a set of standard tests for it, run it through those tests.

If there is a compatibility issue, you will see details about it in the Java Console. The Java Console looks like this:

For details about the Java Console, see Java Console page.

Potential Upgrade Issues

Here are some potential issues, listed by symptoms, that you might encounter:

  • When running an applet in a browser using the Sun JRE, a ClassFormatError is thrown by the ClassLoader. The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, a ClassNotFoundException is thrown by the ClassLoader. The same applet runs under Microsoft VM.
  • After repackaging the signed .cab files as .jar files, an applet running in the Sun JRE is treated as unsigned. The same applet packaged as .cab files runs as signed in the Microsoft VM.
  • After upgrading the signed applet from .cab to .jar to run in the Sun JRE, the applet no longer works in the Microsoft VM. The applet runs fine in the Sun JRE.
  • When running an applet in a browser using Sun's JRE, an AccessControlException is thrown in the execution of Introspector.setBeanInfoSearchPath() .The same applet runs under the Microsoft VM.
  • When running an applet in a browser using Sun JRE, a ClassNotFoundException is thrown by the ClassLoader on the com.ms.security package. The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, a ClassNotFoundException is thrown by the ClassLoader on the com.ms.* package. The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, deadlock may occur if methods of the applet are over-synchronized, especially those inherited from java.awt.Component. The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, a ClassCastException is thrown from the AWT Dispatch Event Thread when mouse moves over the applet frame. The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, a NullPointerException is thrown from a thread when Applet.start() or Applet.stop() is called. The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, a NullPointerException is thrown in java.awt.Graphics.drawString(). The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, a NullPointerException is thrown in java.awt.Graphics.drawImage(). The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, an IllegalArgumentException is thrown in java.awt.Color constructor. The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, an AccessControlException is thrown in stop(), suspend(), or resume() of java.lang.Thread. The same applet runs under the Microsoft VM.
  • When running an applet in a browser using the Sun JRE, an InstantiationException is thrown. The same applet runs under the Microsoft VM.
  • Unable to use certificates from the browser for client authentication.
  • When running an applet in a browser using the Sun JRE, if the applet makes HTTP requests to a server which redirects to an HTTPS URL, the redirection fails. It fails also in the case of making HTTPS requests to a server which redirects to an HTTP URL. The same applet runs without error in the Microsoft VM.
  • CJK (Chinese-Japanese-Korean) fonts, when displayed in BOLD, are hard to read.

If you run into an issue not covered in the preceeding list, please see the Java Upgrade Forum:

http://forum.java.sun.com/forum.jsp?forum=481


Drag and Drop and Data Transfer

Java

Drag and Drop

 Documentation Contents
Drag and Drop enables data transfer across JavaTM programming language and native applications, between Java programming language applications, and within a single Java programming language application.

Support for drag and drop is implemented primarily in the AWT package, but there is additional support built in to the Swing GUI classes. In many cases, drag and drop support can be enabled by calling a single method on a Swing component. For more information, please see How to Use Drag and Drop and Data Transfer, a section in The Swing Tutorial

API Specification
  • API Reference
  • Drag and Drop Specification.
Tutorials and Programmer's Guides
  • How to Use Drag and Drop and Data Transfer from The Swing Tutorial
API Enhancements
  • AWT Enhancements in the Java 2 Platform Standard Edition 5.0 - contains a section that specifically deals with enhancements to drag and drop.
More Information

  • Swing Data Transfer
  • The JFC Home Page

Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved.

Please send Drag and Drop comments to our Java Drag and Drop team: java-dnd@java.sun.com 		Sun Microsystems, Inc
Java Software


Drag and Drop Packages

 Documentation Contents
  • java.awt.datatransfer - Provides interfaces and classes for transferring data between and within applications.
  • java.awt.dnd - Drag and drop is a direct manipulation gesture, found in many Graphical User Interface systems, that provides a mechanism to transfer information between two entities logically associated with presentation elements in the GUI.


Drag and Drop Subsystem for the Java 2 Platform Standard Edition 5.0

Drag and Drop Subsystem for the JavaTM 2 Platform Standard Edition 5.0

This document has these sections:

  • 1.0 Requirements
  • 2.0 API
  • 2.1 Overview
  • 2.2 Drag Gesture Recognition
    • 2.2.1 DragGestureRecognizer
  • 2.3 Drag Source
    • 2.3.1 The DragSource Definition
    • 2.3.2 The DragSourceContext Definition
    • 2.3.3 The DragSourceListener Definition
    • 2.3.4 The DragSourceEvent Definition
    • 2.3.5 The DragSourceDragEvent Definition
    • 2.3.6 The DragSourceDropEvent Definition
  • 2.4 Drop Target
    • 2.4.1 java.awt.Component additions for DropTarget (de)registration
    • 2.4.2 The DropTarget Definition
    • 2.4.3 The DropTargetContext Definition
    • 2.4.4 The DropTargetListener Definition
    • 2.4.5 The DropTargetDragEvent and DropTargetDropEvent Definitions
    • 2.4.6 Autoscrolling Support
  • 2.5 Data Transfer Phase
    • 2.5.1 FlavorMap and SystemFlavorMap
    • 2.5.2 Transferring Data across the JVM boundary
    • 2.5.3 Transferring lists of files across the JVM boundary
    • 2.5.4 Transferring java.rmi.Remote references across the JVM boundary
  • 3.0 Issues
    • 3.0.1 What are the implications of the various platform protocol engines?
    • 3.0.2 Inter/Intra VM transfers?
    • 3.0.3 Lifetime of the Transferable(s)?
    • 3.0.4 Implications of ACTION_MOVE semantics on source objects exposed via Transferable?
    • 3.0.5 Semantics of ACTION_REFERENCE operation
  • Appendix A: DropTargetPeer definition
  • Appendix B: DragSourceContextPeer definition
  • Appendix C: DropTargetContextPeer definition

1.0 Requirements

This specification defines the API for the drag and drop facilities for the Java 2 Platform.

The primary requirements that this specification addresses, are:

  1. Provision of a platform-independent drag and drop facility for Java GUI clients implemented through AWT and Swing classes.
  2. Integration with platform dependent drag and drop facilities, permitting Java clients to be able to participate in DnD operation with native applications using:
    • OLE (Win32) DnD
    • XDND protocol
    • CDE/Motif dynamic protocol
    • MacOS
    • OS/2
  3. Support for 100% pure JavaOS/Java implementation.
  4. Leverages the existing java.awt.datatransfer.* package to enable the transfer of data, described by an extensible data type system based on the MIME standard.
  5. Does not preclude the use of "accessibility" features where available.
  6. Extensible to support diverse input devices.

The specification derives from the previous work mentioned above, but incorporates significant differences from that original work as a result of the advent of the JavaBeansTM event model, lightweight (Swing) components, and an increasing understanding of the cross-platform integration and interoperability issues.

2.0 API

The following sections cover the drag and drop API.

2.1 Overview

Drag and drop is a direct manipulation gesture found in many graphical user interface systems that provides a mechanism to transfer information between two entities logically associated with presentation elements in the GUI. Normally driven by a physical gesture of a human user using an appropriate input device, drag and drop provides both a mechanism to enable continuous feedback regarding the possible outcome of any subsequent data transfer to the user during navigation over the presentation elements in the GUI, and the facilities to provide for any subsequent data negotiation and transfer.

A typical drag and drop operation can be decomposed into the following states (not entirely sequentially):

  • A DragSource comes into existence, associated with some presentation element (Component) in the GUI, to initiate a drag and drop of some potentially Transferable data.
  • 1 or more DropTargets come into/go out of existence, associated with presentation elements in the GUI (Components), potentially capable of consuming Transferable data types.
  • A 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.
  • A human user makes a drag gesture over the Component, which the registered DragGestureRecognizer detects, and notifies its DragGestureListener of.

    Note: Although the body of this document 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.

  • The 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.
  • As the user gestures navigate over 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:
  • By the transfer "operation" selected by the user, and supported by both the DragSource and DropTarget: Copy, Move or Reference(link).
  • By the intersection of the set of data types provided by the DragSource and the set of data types comprehensible by the DropTarget.
  • When the user terminates the drag operation, normally resulting in a successful Drop, both the 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.

The remainder of this document details the proposed API changes to support this model.

2.2 Drag Gesture Recognition

The gesture(s) that can initiate a drag and drop operation vary, not only per platform, but also per Component, and per device. Therefore a mechanism is required in order to encapsulate these dependencies, thus making the task of the author of a Component that wishes to initiate a drag and drop operation much simpler.

2.2.1 DragGestureRecognizer

The DragGestureRecognizer is an abstract base class for all device/platform/Component specific drag and drop gesture recognizers, and is defined as:

public abstract DragGestureRecognizer {
    protected DragGestureRecognizer(
        DragSource  ds,
        Component c,
        int  srcActions,
        DragGestureListener dgl
    );
    public Component getComponent();
    public void      setComponent(Component c);
    public int  getSourceActions();
    public void setSourceActions(int actions);
    public java.awt.InputEvent getTriggerEvent();
    public void resetRecognizer();
    public void addDragGestureListener(
        DragGestureListener dgl
    ) throws TooManyListenerExceptions;
    public void removeDragGestureListener(
       DragGestureListener dgl
    );
    protected abstract void registerListeners();
    protected abstract void unregisterListeners();
    protected void fireDragGestureRecognized(
       int dragAction
    );
    protected void appendEvent(InputEvent awtie);
}

An appropriate concrete subclasses of DragGestureRecognizer for a particular may be obtained in a variety of ways; from a DragSource instance, from the Toolkit, or by other means. Concrete implementation subclasses are obtained through standard APIs' by specifying a Class reference to an abstract DragGestureRecognizer superclass, an instance of a concrete subclass of this actual parameter is instantiated and returned to the requestor.

Once a DragGestureRecognizer instance is associated with a Component and a DragSource it registers its own particular set of EventListeners' with the target Component in order to monitor the appropriate events being delivered to that Component to detect an initiating gesture. (Using registerListeners and unregisterListeners to add/remove these monitoring EventListeners').

Note that a DragGestureRecognizer may throw either an IllegalStateException or an IllegalArgumentException if either the Component or DragSource specified is either not in the correct state for, or is not interoperable with, that DragGestureRecognizer.

When a concrete DragGestureRecognizer instance detects a drag-initiating user gesture on the Component it is associated with, it will fire a DragGestureEvent to the DragGestureListener registered on its unicast event source for DragGestureListener events. This DragGestureListener is responsible for causing the associated DragSource to start the drag and drop operation (if appropriate).

The implementation provides (at least) an abstract subclass for recognizing mouse device gestures MouseDragGestureRecognizer. Other abstract subclasses may be provided by the platform to support other input devices or particular Component class semantics. Concrete superclasses of this MouseDragGestureRecognizer that encapsulate platform dependent mouse based gestures are available from the Toolkit object via its createDragGestureRecognizer(Class adgrc, DragSource ds, Component c, int sa, DragGestureListener dgl) method. This Toolkit API provides platform dependent concrete implementations that extend particular platform independent abstract definitions (classes).

The MouseDragGestureRecognizer abstract class is defined as:

public abstract   MouseDragGestureRecognizer
       extends    DragGestureRecognizer
      implements MouseListener, MouseMotionListener {

    public MouseDragGestureRecognizer(
        DragSource  ds,
        Component   c,
        int  sa,
        DragGestureListener dsl
    );
    //...
}

The DragGestureListener is defined as:

public interface DragGestureListener extends EventListener {
    void dragGestureRecognized(DragGestureEvent dge);
}

Usually the dragGestureRecognized() method will simply, via the DragGestureEvent's convenience API startDrag, start a drag and drop operation on the associated DragSource.

Note that per Component (class or instance) behavior that may effect the initiating gesture would usually be implemented in this DragGestureListener method, or in the DragGestureRecognizer subclass where appropriate or possible.

The DragGestureEvent is defined as:

publc class DragGestureEvent extends EventObject {
    public DragGestureEvent(DragGestureRecognizer dgr,
             int  dragAction,
             java.util.List  events
     );
    public DragGestureRecognizer getSourceAsDragGestureRecognizer();
    public Component  getComponent();
    public DragSource getDragSource();
    public java.util.Iterator iterator();
    public Object[] toArray();
    public Object[] toArray(Object[] array);
    public int getDragAction();
    public startDrag(Cursor             dragCursor,
                     Transferable       t,
                     DragSourceListener dsl
    );
    public startDrag(Cursor             dragCursor,
                     Image              dragImage,
                     Point              imageOffset,
                     Transferable       t,
                     DragSourceListener dsl
    );
    //...
}

The DragGestureEvent encapsulates all the information regarding the nature of the gesture that has just been recognized, including:

  • The DragGestureRecognizer that recognized the gesture
  • The Component that the gesture occurred on
  • The DragSource that will process the operation
  • The List of InputEvent objects that comprise the gesture.
  • The action (ACTION_COPY, ACTION_MOVE or ACTION_LINK, selected by the user's gesture.

2.3 Drag Source

The DragSource is the entity responsible for the initiation of the drag and drop operation:

2.3.1 The DragSource definition

The DragSource and associated constant interfaces are defined as follows:

The DnDConstants class defines the operations that may be applied to the subject of the transfer:

public final class java.awt.dnd.DnDConstants {
     public static int ACTION_NONE = 0x0;
     public static int ACTION_COPY = 0x1;
     public static int ACTION_MOVE = 0x2;
     public static int ACTION_COPY_OR_MOVE= ACTION_COPY | ACTION_MOVE;
     public static int ACTION_REFERENCE = 0x40000000;
}

public class java.awt.dnd.DragSource {
     public static Cursor     DefaultCopyDrop;
     public static Cursor     DefaultMoveDrop;
     public static Cursor     DefaultLinkDrop;
     public static Cursor     DefaultCopyNoDrop;
     public static Cursor     DefaultMoveNoDrop;
     public static Cursor     DefaultLinkNoDrop;
     public static DragSource getDefaultDragSource();
     public static boolean isDragImageSupported();
     public void startDrag(DragGestureEvent trigger,
            Cursor             dragCursor,
            Image	           dragImage,
            Point	           dragImageOffset,
            Transferable       transferable,
            DragSourceListener dsl,
            FlavorMap          fm)
          throws InvalidDnDOperationException;
     protected DragSourceContext  createDragSourceContext(
            DragSourceContextPeer dscp,
            DragGestureEvent      trigger,
            Cursor                dragCursor,
            Image                 dragImage,
              Point                 dragImageOffset,
            Transferable          transferable,
            DragSourceListener    dsl
      );
      public FlavorMap getFlavorMap();
      public DragGestureRecongizer createDragGestureRecognizer(
              Class               abstractRecognizerClass,
              Component           c,
              int                 srcActions,
              DragGestureListener dgl
     );
     public DragGestureRecongizer createDefaultDragGestureRecognizer(
              Component           c,
              int                 srcActions,
              DragGestureListener dgl
     );
     //...
}

The DragSource may be used in a number of scenarios:

  • 1 default instance per JVM for the lifetime of that JVM. (defined by this spec)
  • 1 instance per class of potential Drag Initiator object (e.g TextField). [implementation dependent]
  • 1 per instance of a particular Component, or application specific object associated with a Component instance in the GUI. [implementation dependent]
  • some other arbitrary association. [implementation dependent]

A controlling object, shall obtain a DragSource instance prior to a user's gesture, effecting an associated Component, in order to process the operation. Once obtained a DragGestureRecognizer should be obtained and used to associate the DragSource with a Component.

The initial interpretation of the user's gesture, and the subsequent starting of the drag operation are the responsibility of the implementing Component, this is usually implemented by a DragGestureRecognizer.

When a gesture occurs, the DragSource's startDrag method shall be invoked in order to cause processing of the user's navigational gestures and delivery of drag and drop protocol notifications. A DragSource shall only permit a single drag and drop operation to be current at any one time, and shall reject any further startDrag requests by throwing an IllegalDnDOperationException until such time as the extant operation is complete.

In order to start a drag operation the caller of the startDrag method shall provide the following parameters:

  • The DragGestureEvent for the gesture.

  • A Cursor representing the initial "Drag Over" feedback for the operation(s) specified. (This shall be a Cursor that provides "No Drop" visual feedback to the user).

  • An (optional) Image to visually represent the item, or item(s) that are the subject(s) of the operation.

    • On platforms that can support this feature, a "Drag" image may be associated with the operation to enhance the fidelity of the "Drag Over" feedback. This image would typically be a small "iconic" representation of the object, or objects being dragged, and would be rendered by the underlying system, tracking the movement of, and coincident with, but typically in addition to the Cursor animation.

    Where this facility is not available, or where the image is not of a suitable type to be rendered by the underlying system, this parameter is ignored and only Cursor "Drag Over" animation results, so applications should not depend upon this feature. The presence of the facility on a particular platform may be tested by invoking the static method isDragImageSupported.

  • Where an Image is provided; a Point (in the co-ordinate space of the Component) specifying the initial origin of that Image relative to the co-ordinates of the "hotspot" of the drag "Cursor", in the co-ordinate space of the Component, at the time of the initial gesture, for the purposes of initiating a correctly positioned "Drag Over" animation of that Image relative to that "hotspot".

  • A Transferable that describes the various DataFlavor(s) that represent the subject(s) of any subsequent data transfer that may result from a successful Drop.

    The Transferable instance associated with the DragSource at the start of the drag operation, represents the object(s) or data that are the operand(s), or the subject(s), of the Drag and Drop operation, that is the information that will subsequently be passed from the DragSource to the DropTarget as a result of a successful Drop on the Component associated with that DropTarget.

    Note that multiple (collections) of either homogeneous, or heterogeneous, objects may be subject of a Drag and Drop operation, by creating a container object, that is the subject of the transfer, and implements Transferable. However it should be noted that since none of the targeted native platforms systems support a standard mechanism for describing and thus transferring such collections it is not possible to implement such transfers in a transparent, or platform portable fashion.

  • A DragSourceListener instance, which will subsequently receive events notifying it of changes in the state of the ongoing operation in order to provide the "Drag Over" feedback to the user.

As stated above, the primary role of the startDrag method is to initiate a Drag on behalf of the user. In order to accomplish this, the startDrag method must create a DragSourceContext instance to track the operation itself, and more importantly it must initiate the operation itself in the underlying platform implementation. In order to accomplish this, the DragSource must first obtain a DragSourceContextPeer from the underlying system (usually via an invocation of java.awt.Toolkit.createDragSourceContextPeer method) and subsequently associate this newly created DragSourceContextPeer (which provides a platform independent interface to the underlying systems capabilities) with a DragSourceContext.The startDrag method invokes the createDragSourceContext method to instantiate an appropriate DragSourceContext and associate the DragSourceContextPeer with that.

If the drag and drop system is unable to initiate a drag operation for some reason the startDrag method shall throw a java.awt.dnd.InvalidDnDOperationException to signal such a condition. Typically this exception is thrown when the underlying platform system is either not in a state to initiate a drag, or the parameters specified are invalid.

Note that during the drag neither the set of operations the source exposed at the start of the drag operation may change for the duration of the operation, in other words the operation(s) and are constant for the duration of the operation with respect to the DragSource.

The getFlavorMap method is used by the underlying system to obtain a FlavorMap object in order to map the DataFlavors exposed by the Transferable to data type names of the underlying DnD platform. [see later for details of the FlavorMap]

A "private" FlavorMap may be provided to the startDrag() method of the DragSource, or null, in which case the "default" FlavorMap for that DragSource class or instance is used.

2.3.2 The DragSourceContext Definition

As a result of a DragSource's startDrag method being successfully invoked an instance of the DragSourceContext class is created. This instance is responsible for tracking the state of the operation on behalf of the DragSource and dispatching state changes to the DragSourceListener.

The DragSourceContext class is defined as follows:

public class DragSourceContext implements DragSourceListener {
    public DragSourceContext(
        DragSourceContextPeer dscp,
        DragGestureEvent  trigger,
        Cursor  dragCursor,
        Image  dragImage,
        Point  dragOffset,
        Transferable  transferable,
        DragSourceListener  dsl
    );
        public DragSource  getDragSource();
        public Component  getComponent();
        public DragGestureEvent	getTrigger();
        public Image	 getDragImage();
        public Point	 getDragImageOffset();
        public void transferablesFlavorsChanged();
        public int getSourceActions();
        public Cursor getCursor();
        pbulic void   setCursor(Cursor Cursor)
            throws InvalidDnDOperationException;
        public void addDragSourceListener(DragSourceListener dsl)
            throws TooManyListenersException;
        public void removeDragSourceListener(DragSourceListener dsl);
        protected updateCurrentCursor(int dropOperation,
                                   int targetActions,
                                   int status
        );
        // values for status parameter above.
        protected static final int DEFAULT = 0;
        protected static final int ENTER   = 1;
        protected static final int OVER    = 2;
        protected static final int CHANGED = 3;

        //...
}

Note that the DragSourceContext itself implements DragSourceListener, this is to allow the platform peer, the DragSourceContextPeer instance, created by the DragSource, to notify the DragSourceContext of changes in state in the ongoing operation, and thus allows the DragSourceContext to interpose itself between the platform and the DragSourceListener provided by the initiator of the operation.

The state machine the platform exposes, with respect to the source, or initiator of the Drag and Drop operation is detailed below:

Following context describes this graphic

Notifications of changes in state with respect to the initiator during a drag and drop operation, as illustrated above, are delivered from the DragSourceContextPeer, to the appropriate DragSourceContext, which delegates notifications, via a unicast JavaBeans compliant EventListener subinterface, to an arbitrary object that implements DragSourceListener registered with the DragSource via startDrag.

The primary responsibility of the DragSourceListener is to monitor the progress of the user's navigation during the drag and drop operation and provide the "Drag-Over" effects feedback to the user. Typically this is accomplished via changes to the "Drag Cursor".

Every drag operation has 2 logical cursor states (Drag Cursors) associated with it:

  • The Drop Cursor, the cursor displayed when dragging over a valid DropTarget.
  • The NoDrop Cursor, the cursor displayed when dragging over everything else (the initial state of the cursor at the start of a drag).

The state of the Cursor may be modified by calling the setCursor method of the DragSourceContext.

2.3.3 The DragSourceListener Definition

The DragSourceListener interface is defined as follows:

public interface java.awt.dnd.DragSourceListener
    extends java.util.EventListener {
    void dragEnter	(DragSourceDragEvent dsde);
    void dragOver	(DragSourceDragEvent dsde);
    void dropActionChanged (DragSourceDragEvent dsde);
    void dragExit	(DragSourceEvent     dse);
    void dragDropEnd  (DragSourceDropEvent dsde);
}

As the drag operation progresses, the DragSourceListener's dragEnter, dragOver, and dragExit methods shall be invoked as a result of the user's navigation of the logical "Drag" cursor's location intersecting the geometry of GUI Component(s) with associated DropTarget(s). [See below for details of the DropTarget's protocol interactions].

The DragSourceListener's dragEnter method is invoked when the following conditions are true:

  • The logical cursor's hotspot initially intersects a GUI Component's visible geometry.
  • That Component has an active DropTarget associated.

    The DropTarget's registered DropTargetListener dragEnter method is invoked and returns successfully.

    The registered DropTargetListener invokes the DropTargetDragEvent's acceptDrag method to accept the drag based upon interrogation of the source's potential drop actions and available data types (DataFlavors).

    The DragSourceListener's dragOver method is invoked when the following conditions are true:

    • The cursor's logical hotspot has moved but still intersects the visible geometry of the Component associated with the previous dragEnter invocation.
    • That Component still has a DropTarget associated.
    • That DropTarget is still active.
    • The DropTarget's registered DropTargetListener dragOver method is invoked and returns successfully.
    • The DropTarget does not reject the drag via rejectDrag.

    The DragSourceListener's dragExit method is invoked when one of the following conditions is true:

    • The cursor's logical hotspot no longer intersects the visible geometry of the Component associated with the previous dragEnter invocation.

      Or:

    • The Component that the logical cursor's hotspot intersected that resulted in the previous dragEnter invocation, no longer has an active DropTarget (or DropTargetListener) associated.

      Or:

    • The current DropTarget's DropTargetListener has invoked rejectDrag since the last dragEnter or dragOver invocation.

    The DragSourceListener's dropActionChanged() method is invoked when the state of the input device(s), typically the mouse buttons or keyboard modifiers, that the user is interacting with in order to perform the drag operation, changes.

    The dragDropEnd() method is invoked to signify that the operation is completed. The getDropSuccess method of the DragSourceDropEvent can be used to determine the termination state. The getDropAction method returns the operation that the DropTarget selected (via the DropTargetDropEvent acceptDrop parameter) to apply to the drop operation.

    Once this method is complete the current DragSourceContext and the associated resources are invalid.

    2.3.4 The DragSourceEvent Definition

    The DragSourceEvent class is the root Event class for all events pertaining to the DragSource, and is defined as follows:

    public class   java.awt.dnd.DragSourceEvent extends java.util.EventObject {
        public DragSourceEvent(DragSourceContext dsc);
        public DragSourceContext getDragSourceContext();
        //...
};

    An instance of this event is passed to the DragSourceListener dragExit method.

    2.3.5 The DragSourceDragEvent Definition

    The DragSourceDragEvent class is defined as follows:

public class java.awt.dnd.DragSourceDragEvent extends DragSourceEvent {
        public int getTargetActions();
        public int getUserAction();
        public int getGestureModifiers();
        public int getGestureModifiersEx();
        public int getDropAction();
}

    An instance of the above class is passed to a DragSourceListener's dragEnter, dragOver, and dragGestureChanged methods.

    The getDragSourceContext method returns the DragSourceContext associated with the current drag and drop operation.

    The getUserAction method returns the action that is currently selected by the user's gesture.

    The getTargetActions method returns the drop action selected by the current drop target if this drop action is supported by the drag source or DnDConstants.ACTION_NONE if this drop action is not supported by the drag source.

    The logical intersection of these two results and the set of drop actions supported by the drag source defines the actual effect of a drop and is returned via getDropAction.

    The getGestureModifiers method returns the current state of the input device modifiers, usually the mouse buttons and keyboard modifiers, associated with the user's gesture.

    The getGestureModifiersEx method returns the current state of the input device extended modifiers associated with the user's gesture.

    2.3.6 The DragSourceDropEvent Definition

    The DragSourceDropEvent class is defined as follows:

    public public class java.awt.dnd.DragSourceDropEvent
                        extends java.util.EventObject {
       public DragSourceDropEvent(DragSourceContext dsc);
       public DragSourceDropEvent(DragSourceContext dsc,
                int  action,
                boolean success);
       public boolean getDropSuccess();
       public int getDropAction();
}

    An instance of the above class is passed to a DragSourceListener's dragDropEnd method. This event encapsulates the termination state of the drag and drop operation for the DragSource.

    If the drop occurs, then the participating DropTarget will signal the success or failure of the data transfer via the DropTargetContext's dropComplete method, this status is made available to the initiator via the getDropSuccess method. The operation that the destination DropTarget selected to perform on the subject of the drag (passed by the DropTarget's acceptDrop method) is returned via the getDropAction method.

    If the drag operation was aborted for any reason prior to a drop occurring, for example if the user ends the gesture outside a DropTarget, or if the DropTarget invokes rejectDrop, the getDropSuccess method will return false, otherwise true.

    2.4 Drop Target

    2.4.1 java.awt.Component additions for DropTarget (de)registration.

    The java.awt.Component class has two additional methods added to allow the (dis)association with a DropTarget. In particular:

    public class java.awt.Component /* ... */ {
    //...
    public synchronized void setDropTarget(DropTarget dt);
    public synchronized DropTarget getDropTarget(DropTarget df);
    //...
}

    To associate a DropTarget with a Component one may invoke either; DropTarget.setCompononent or Component.setDropTarget methods. Thus conforming implementations of both methods are required to guard against mutual recursive invocations.

    To disassociate a DropTarget with a Component one may invoke either; DropTarget.setCompononent(null) or Component.setDropTarget(null) methods.

    Conformant implementations of both setter methods in DropTarget and Component should be implemented in terms of each other to ensure proper maintenance of each other's state.

    The setDropTarget method throws IllegalArgumentException if the DropTarget actual parameter is not suitable for use with this class/instance of Component. It may also throw UnsupportedOperationException if, for instance, the Component does not support external setting of a DropTarget.

    2.4.2 The DropTarget Definition

    A DropTarget encapsulates all of the platform-specific handling of the Drag and Drop protocol with respect to the role of the recipient or destination of the operation.

    A single DropTarget instance may typically be associated with any arbitrary instance of java.awt.Component. Establishing such a relationship exports the associated Components geometry to the client desktop as being receptive to drag and drop operations when the coordinates of the logical cursor intersects that visible geometry.

    The DropTarget class is defined as follows:

    public class java.awt.dnd.DropTarget
       implements DropTargetListener, Serializable {

        public DropTarget(Component          c,
                       int                actions,
                       DropTargetListener dsl,
                       boolean            isActive,
                       FlavorMap          fm
        );
        public DropTarget();
        public DropTarget(Component c);
        public DropTarget(Component c, DropTargetListener dsl);
        public Component getComponent();
        public void      setComponent(Component c);
        public DropTargetContext getDropTargetContext();
        public void addDropTargetListener(DropTargetListener dte)
          throws TooManyListenersException;
        public void removeDropTargetListener(DropTargetListener dte);
        public void setActive(boolean active);
        public boolean isActive();
        public FlavorMap getFlavorMap();
        public void      setFlavorMap(FlavorMap fm);
        public void setDefaultActions(int actions);
        public int  getDefaultActions();
        protected DropTargetContext createDropTargetContext();
        public void addNotify(ComponentPeer cp);
        public void removeNotify(ComponentPeer cp);
        // ...
}

    The setComponent method throws IllegalArgumentException if the Component actual parameter is not appropriate for use with this class/instance of DropTarget, and may also throw UnsupportedOperationException if the Component specified disallows the external setting of a DropTarget.

    The addDropTargetListener and removeDropTargetListener methods allow the unicast DropTargetListener to be changed.

    The setActive and isActive methods allow the DropTarget to be made active or otherwise and for its current state to be determined.

    The getFlavorMap methods is used to obtain the FlavorMap associated with this DropTarget for the purposes of mapping any platform dependent type names to/from their corresponding platform independent DataFlavors.

    The setFlavorMap method allows a new FlavorMap to be assigned to the DropTarget, a parameter of null causes a "default" FlavorMap to be installed for the DropTarget.

    The createDropTargetContext method is only invoked to provide the underlying platform dependent peer with an instantiation of a new DropTargetContext as a Drag operation initially encounters the Component associated with the DropTarget. If no DropTargetContext is currently associated with a DropTarget, a permitted side-effect of an invocation of getDropTargetContext is to instantiate a new DropTargetContext.

    The addNotify and removeNotify methods are only called from Component to notify the DropTarget of the Component's (dis)association with its ComponentPeer.

    Note that the DropTarget itself implements DropTargetListener, this is to allow the platform peer, the DropTargetContextPeer instance, created by the platform, to notify the DropTarget of changes in state in the ongoing operation, and thus allows the DropTarget to interpose itself between the platform and the DropTargetListener registered with the DropTarget.

    2.4.3 The DropTargetContext Definition

    As the logical cursor associated with an ongoing drag and drop operation first intersects the visible geometry of a Component with an associated DropTarget, the DropTargetContext associated with the DropTarget is the interface, through which, access to, and control over state of the recipient protocol is achieved from the DropTargetListener.

    A DropTargetContext is created by a DropTarget, via it's createDropTargetContext method, as a side effect of a call to a DropTarget's getDropTargetContext method, if no DropTargetContext currently exists for that DropTarget.

    The DropTargetContext interface is defined as follows:

    public class DropTargetContext {
        public DropTarget getDropTarget();
        public Component getComponent();
        public void  dropComplete(boolean success)
                throws InvalidDnDOperationException;
        public void acceptDrag(int dropAction);
        public void rejectDrag();
        public void acceptDrop(int dropAction);
        public void rejectDrop();
        public void addNotify(DropTargetContextPeer dtcp);
        public void removeNotify();
        protected Transferable createTransferableProxy(Transferable t,
           boolean isLocal
        );
        protected void setTargetActions(int actions);
        protected int  getTargetActions();
        protected DataFlavor[] getCurrentDataFlavors();
        protected List getCurrentDataFlavorsAsList();
        protected boolean isDataFlavorSupported(DataFlavor df);
        protected Transferable getTransferable();
        // ...
}

    Most of the access and control methods are protected, since public access to their state is usually achieved by calling through a particular DropTargetEvent subclass that delegates the request to the DropTargetContext.

    The getDropTarget() method return the DropTarget that created this DropTargetContext.

    The getComponent method returns the Component associated with the DropTarget that created this DropTargetContext.

    The acceptDrag method is delegated from the similar method on DropTargetDragEvent and is invoked from one of the DropTargetListener's methods; dragEnter(), dragOver or dropActionChanged to signify that the recipient is prepared to accept a drop with the operation specified, which is usually the user's currently selected action.

    The rejectDrag method is delegated from the similar method on DropTargetDragEvent and is invoked from one of the DropTargetListener's methods; dragEnter, dragOver or dropActionChanged to signify that the recipient is unable to accept a drop with the user's currently selected action.

    The acceptDrop method is delegated from the similar method on DropTargetDropEvent and is invoked from the DropTargetListener's drop method to signify that the recipient is prepared to accept a drop with the operation specified, which is usually the user's currently selected action.

    The rejectDrop method is delegated from the similar method on DropTargetDropEvent and is invoked from the DropTargetListener's drop method to signify that the recipient is unable to accept a drop with the user's currently selected action. This terminates a drag and drop operation without a data transfer.

    The dropComplete method signals to the originating DragSource that the DropTargetListener has completed the transfer(s) that comprise the subject of the drag and drop operation and that the operation is complete. The success (or failure) of the transfer(s) and the subsequent application of the operation specified is signaled by the value of the actual parameter.

    The getDataFlavors method returns an array of the DataFlavors available from the DragSource.

    The getTransferable method returns a Transferable (not necessarily the one the DragSource registered, it may be a proxy, and certainly shall be in the inter-JVM case) to enable data transfers to occur via its getTransferData method. Note that it is illegal to invoke getTransferable without first invoking an acceptDrop.

    The addNotify and removeNotify methods are exclusively called by the underlying platform's DropTargetContextPeer in order to notify the DropTargetContext that a drag and drop operation is occurring/ceasing on the DropTargetContext and associated DropTarget.

    The createTransferableProxy method enables a DropTargetContext implementation to interpose a Transferable between the DropTargetListener and the Transferable provided by the caller, which is typically the underlying platform DropTargetContextPeer.

    2.4.4 The DropTargetListener Definition

    Providing the appropriate "Drag-under" feedback semantics, and processing of any subsequent Drop, is enabled through the DropTargetListener asssociated with a DropTarget.

    The DropTargetListener determines the appropriate "Drag-under" feedback and its response to the DragSource regarding drop eligibility by inspecting the sources suggested actions, the data types available and the data itself.

    A particular DropTargetListener instance may be associated with a DropTarget via addDropTargetListener and removed via removeDropTargetListener methods.

    public interface java.awt.dnd.DropTargetListener
        extends java.util.EventListener {
        void dragEnter            (DropTargetDragEvent dtde);
        void dragOver             (DropTargetDragEvent dtde);
        void dropActionChanged    (DropTargetDragEvent dtde);
        void dragExit             (DropTargetDragEvent dtde);
        void drop                 (DropTargetDropEvent dtde);
}

    The following context describes this graphic.

    The dragEnter method of the DropTargetListener is invoked when the hotspot of the logical "Drag" Cursor intersects a visible portion of the DropTarget's associated Component's geometry. The DropTargetListener, upon receipt of this notification, shall interrogate the operations or actions, and the types of the data (DataFlavors) and the data itself as supplied by the DragSource to determine the appropriate actions and "Drag-under" feedback to respond with invocation of either acceptDrag or rejectDrag.

    The dragOver method of the DropTargetListener is invoked while the hotspot of the logical "Drag" Cursor, in motion, continues to intersect a visible portion of the DropTarget's associated Component's geometry. The DropTargetListener, upon receipt of this notification, shall interrogate the operation "actions" the types of the data and the data itself as supplied by the DragSource to determine the appropriate "actions" and "Drag-under" feedback to respond with an invocation of either acceptDrag or rejectDrag.

    The dragExit method of the DropTargetListener is invoked when the hotspot of the logical "Drag" Cursor ceases to intersect a visible portion of the DropTarget's associated Component's geometry, or immediately prior to a drop notification. The DropTargetListener, upon receipt of this notification, shall undo any "Drag-under" feedback effects it has previously applied. Note that the DropTargetContext associated with the DropTarget is invalidated as a side-effect.

    The drop method of the DropTargetListener is invoked as a result of the user terminating their drag gesture while intersecting. The DropTargetListener, upon receipt of this notification, shall perform the operation specified by the return value of the getSourceActions method on the DropTargetDropEvent object, upon the Transferable object returned from the getTransferable method, and subsequently invoke the dropComplete method of the associated DropTargetContext to signal the success, or otherwise, of the operation.

    2.4.5 The DropTargetDragEvent and DropTargetDropEvent Definitions

    The DropTargetEvent and DropTargetDragEvent are defined as follows:

    public abstract class java.awt.dnd.DropTargetEvent
      extends java.util.EventObject {

        public DropTargetContext getDropTargetContext();
        //...
}

    A DropTargetEvent is passed to the DropTargetListener's dragExit method.

    public class   java.awt.dnd.DropTargetDragEvent
                     extends java.awt.dnd.DropTargetEvent {
        public Transferable getTransferable();
        public Point  getLocation();
        public int   getSourceActions();
        public getDropAction();
        public DataFlavor[] getCurrentDataFlavors();
        public List  getCurrentDataFlavorsAsList();
        public boolean isDataFlavorSupported();
    public void acceptDrag(int operation);
    public void rejectDrag();
        //...
}

    A DropTargetDragEvent is passed to the DropTargetListener's dragEnter, dragOver and dropActionChanged methods.

    The getLocation method return the current co-ordinates, relative to the associated Component's origin, of the hotspot of the logical "Drag" cursor.

    The getSourceActions method returns the current "actions", or operations (ACTION_MOVE, ACTION_COPY, or ACTION_REFERENCE) the DragSource associates with the current drag and drop gesture.

    The return value of the getDropAction method is the action that is selected by the user's gesture.

    The getCurrentDataFlavors, getCurrentDataFlavorsAsList and isDataFlavorSupported methods are provided in order for the recipient to interrogate the list of types available from the source.

    The getTransferable method is provided in order for the recipient to interrogate the data available from the source. Note that getTransferable on the DropTargetDragEvent instance should only be called within the respective DropTargetListener's method, and all the necessary data should be retrieved from the returned Transferable before that method returns.

    The DropTargetDropEvent is defined as follows:

    public class java.awt.dnd.DropTargetDropEvent
      extends java.awt.dnd.DropTargetEvent {

        public Point	  getLocation();
        public int getSourceActions();
        public int getDropAction();
        public void acceptDrop(int dropAction);
        public void rejectDrop();
        public boolean isLocalTransfer();
        public DataFlavor[] getCurrentDataFlavors();
        public List  getCurrentDataFlavorsAsList();
        public boolean isDataFlavorSupported(DataFlavor df);
        public Transferable getTransferable();
        public void dropComplete(boolean success);
        //...
}

    A DropTargetDropEvent is passed to the DropTargetListener's drop method, as the drop occurs. The DropTargetDropEvent provides the DropTargetListener with access to the data associated with the operation, via the Transferable returned from the getTransferable method.

    The return value of the getSourceActions method is defined to be the action(s) defined by the source at the time at which the drop occurred.

    The return value of the getDropAction method is the action that is selected by the user's gesture.

    The return value of the getLocation method is defined to be the location at which the drop occurred.

    The getCurrentDataFlavors, getCurrentDataFlavorsAsList, and isDataFlavorSupported, methods are provided in order for the recipient to interrogate the list of types available from the source for subsequent transfer via the getTransferData method of the Transferable.

    A typical implementation of the drop method will inspect the actions and the DataFlavors' available to determine if a successful exchange can occur or not.

    When an exchange may occur, a DropTargetListener.drop implementation shall invoke acceptDrop with the selected operation as an actual parameter, prior to any invocation of getTransferable. Calling getTransferable prior to acceptDrop shall result in an InvalidDnDOperationException.

    The rejectDrop shall be called to reject the drop operation. Once called no further interaction can occur between the two participants, therefore it is typical to return from the drop method immediately after calling this.

    The isLocalTransfer method shall return true, if the source of the drag and drop operation resides within the same physical JVM as the recipient of the drop notification, and false otherwise.

    This distinction is significant to the recipient when it receives object references back from invoking Transferable.getTransferData in the local case, since in this case the object reference it receives is the same object reference held by the source (i.e it is not a copy, proxy or distinct object) thus the recipient must treat such a shared object reference differently in the local case as follows:

    • If the action is ACTION_COPY then the recipient shall, depending upon the nature of the object(s) and data transferred, either take a copy of; the object itself, the data encapsulated within, or both.
    • If the action is ACTION_MOVE, then the recipient shall not modify the state of the object or the data encapsulated within until after it has signalled to the source, via an invocation of dropCompete that the transfer is effected. (Note that a source is also prohibited from modifying the state of such an object after it has returned such an object from it's getTransferData method, until such time as it receives a dragDropEnd notification.)
    • If the action is ACTION_LINK, neither the recipient nor the source shall alter the state of either the object exchanged or any data contained therein until after the dropComplete and dragDropEnd methods have been processed. Thereafter the sharing semantics are implementation dependent upon the object(s) shared.

    The dropComplete method signals the end of the associated drag and drop operation, and indicates the success (or failure) of the transfers performed by the recipient. Invoking this method results in the DragSourceListener's dragDropEnd method being called with the appropriate state available from it's DragSourceDropEvent. Failure to invoke this method will result in the drag and drop operation failing to terminate properly.

    2.4.6 Autoscrolling Support

    Many GUI Components present a scrollable "viewport" over a (potentially) large dataset. During a drag and drop operation it is desirable to be able to "autoscroll" such "viewports" to allow a user to navigate over such a dataset, scrolling to locate a particular member (initially not visible through the "viewport") that they wish to drop the subject of the operation upon.

    Components that are scrollable provide drag "autoscrolling" support to their DropTarget by implementing the following interface:

    public interface Autoscroll {
        Insets getAutoscrollInsets();
        void autoScrollContent(Point cursorLocn);
}

    An implementing DropTarget shall periodically call the autoscroll method of its associated Component (if present), passing the current logical cursor location in Component co-ordinates, when the following conditions are met:

    • If the logical cursor's hotspot intersects with the associated Component's visible geometry and the boundary region described by the Insets returned by the getAutoscrollInsets method.
    • If the logical cursor's hotspot has not moved (subject to the next condition below) for an implementation defined period (millisecs)
    • If any cursor movement subsequent to the initial triggering occurrence does not exceed a platform dependent hysteresis value (pixels).

    Should any of the above conditions cease to be valid, autoscrolling shall terminate until the next triggering condition occurs.

    Both the initial delay prior to autoscrolling commencing, the interval between autoscrolling notifications, and the pixel hysteresis value are externally configurable and can be queried from the Toolkit.getDesktopProperty method.

    2.5 Data Transfer Phase

    In the case where a valid drop occurs, the DropTargetListener's drop method is responsible for undertaking the transfer of the data associated with the gesture. The DropTargetDropEvent provides a means to obtain a Transferable object that represent that data object(s) to be transferred.

    From the drop method, the DropTargetListener shall initially either rejectDrop (immediately returning thereafter) or acceptDrop specifying the selected operation from those returned by getSourceActions.

    Subsequent to an acceptDrop, but not before, getTransferable may be invoked, and any data transfers performed via the returned Transferable's getTransferData method. Finally, once the destination of the drop has completed the transfer(s) of the objects from the source it shall signal the success, or immediate failure, of the transfer(s) via an invocation of DropTargetContext.dropComplete.

    Upon returning from the DropTargetContext.dropComplete method the Transferable and DragSourceContext instances are no longer guaranteed to be valid and all references to them shall be discarded by the recipient to allow them to be subsequently garbage collected.

    When using the ACTION_REFERENCE operation the source and destination should take care to agree upon the object and the associated semantics of the transfer. Typically in intra-JVM transfers a live object reference would be passed between source and destination, but in the case of inter-JVM transfers, or transfers between native and Java applications, live object references do not make sense, so some other ‘reference' type should be exchanged such as a URI for example. Both the DragSource and DropTarget can detect if the transfer is intra-JVM or not.

    2.5.1 FlavorMap and SystemFlavorMap

    All the target DnD platforms represent their transfer data types using a similar mechanism, however the representations do differ. The Java platform uses MIME types encapsulated within a DataFlavor to represent its data types. Unfortunately in order to permit the transfer of data between Java and platform native applications the existence of these platform names need to be exposed, thus a mechanism is required in order to create an extensible (platform independent) mapping between these platform dependent type names, their representations, and the Java MIME based DataFlavors.

    The implementation will provide a mechanism to externally specify a mapping between platform native data types (strings) and MIME types (strings) used to construct DataFlavors. This external mapping will be used by the underlying platform specific implementation code in order to expose the appropriate DataFlavors (MIME types), exported by the source, to the destination, via the underlying platform DnD mechanisms.

    Both the DragSource and DropTarget classes provide access for the underlying system to map platform dependent names to and from DataFlavors.

    public interface java.awt.datatransfer.FlavorMap {
        java.util.Map getNativesForFlavors(DataFlavor[] dfs);
        java.util.Map getFlavorsForNatives(String[] natives);
}

    The getNativesForFlavors method takes an array of DataFlavors and returns a Map object containing zero or more keys of type DataFlavor, from the actual parameter dfs, with associated values of type String, which correspond to the platform-dependent type name for that MIME type.

    The getFlavorsForNatives method takes an array of String types and returns a Map object containing zero or more keys of type String, from the actual parameter natives, with associated values of type DataFlavor, which correspond to the platform-independent type for that platform-dependent type name.

    The Map object returned by both methods may be mutable but is not required to be.

    If NULL is passed to either of these methods they should return their current map of all keys and values known to the implementation at the time of the call.

    For example on Win32 the Clipboard Format Name for simple text is "CF_TEXT" (actually it is the integer 1) and on Motif it is the X11 Atom named "STRING", the MIME type one may use to represent this would be "text/plain;charset=us-ascii". Therefore a platform portable FlavorMap would map between these names; CF_TEXT on win32 and STRING on Motif/X11.

    Typically, as implemented in the SystemFlavorMap these mappings are held in an external persistent configuration format (a properties file or URL) and are loaded from the platform to configure the FlavorMap appropriately for a given platform.

    The SystemFlavorMap class is provided to implement a simple, platform configurable mechanism for specifying a system-wide set of common mappings, and is defined as follows:

    public class  java.awt.datatransfer.SystemFlavorMap implements FlavorMap, FlavorTable {
    public static FlavorMap getSystemFlavorMap();
    public synchronized Map getNativesForFlavors(DataFlavor[] dfs);
    public synchronized Map getFlavorsForNatives(String[] natives);
    public static String encodeDataFlavor(DataFlavor flav);
    public static String encodeJavaMIMEType(String mimeType);
    public static boolean isJavaMIMEType(String mimeStr);
    public static String decodeJavaMIMEType(String nat);
    public static DataFlavor decodeDataFlavor(String nat);
    //...
}

    The SystemFlavorMap class provides a simple implementation, using a properties file (see java.awt.Properties), of a persistent platform FlavorMap. Using the value of the AWT property "AWT.flavorMapFileURL" (see Toolkit.getProperty) or the default file location of System.getProperty("java.home") + File.separator + "lib" + File.separator + "flavormap.properties", this class creates the appropriate Maps from the properties found therein.

    In addition the class provides several static convenience functions used to encode and decode Java MimeTypes to and from a platform dependent namespace. The syntax of the properties file is:

    { <platform_type_name> ‘=' <IETF_MIME_RFC_conformant_specification> <nl> } *

    The default implementations of DragSource and DropTarget return the SystemFlavorMap from their getFlavorMap method, unless they have been provided with an overriding implementation.

    2.5.2 Transferring Data across the JVM boundary

    Since one of the primary goals of this API is to allow drag and drop of data between Java and native applications this has some significant consequences upon the method and mechanism of the actual data encoding and exchange when data is passed across the boundary of the Java Virtual Machine.

    Since one of the participants in such an exchange may be a native application, and thus has no knowledge of the Java type system, the drag and drop system cannot just exchange a Java object reference since the other participant may have no knowledge of, or capability to manipulate such a type.

    When any exchange occurs, it can only do so, regardless of the implementation of the participants, if and only if both participants are agreed upon a familiar data type and encoding. Thus, sadly the burden of the exchange is born mostly by the participants themselves.

    What this means in practical terms is that for "native" data formats, such as platform-dependent image, document, or other "Content-Types" the encoding and decoding of their associated external data format is the responsibility of the source and destination of the transfer.

    The drag and drop system shall expose the external representation of such "native" data types across the boundary of the Java Virtual Machine as encapsulated within a java.io.InputStream or a subclass thereof.

    This means that any DataFlavor with a representation class that extends java.io.InputStream can be transferred, and will be exposed for transfer, across the Java Virtual Machine boundary.

    To implement the exchange of such a native data type, a developer would define a DataFlavor with a MIME "Content-Type" that describes the nature of the "native" data type, with a representation class that extends a java.io.InputStream class that encodes the data encapsulated into a stream of bytes.

    In particular such InputStream subclasses shall implement the following semantics:

    • Provide a public constructor with a single argument of type java.io.InputStream.

      Provision of this constructor by a subclass of java.io.InputStream will allow the drag and drop system (associated with the DropTarget) to automatically re-construct an instance of the representation class specified by the requested DataFlavor, and initialize it with an InputStream containing the encapsulated data formatted according to the expectations of that subclass. Once initialized this instance is returned to the caller of the Transferable.getTransferData method, thus allowing the caller to subsequently re-read and interpret the formatted content of the data stream transferred.

    • Provide an implementation of InputStream.read(byte b[], int off, int len).

    Provision of this method (or inheriting a superclasses implementation) enables the drag and drop system (associated with the DragSource) to automatically extract an encoded stream of the encapsulated data from the Transferable, thus enabling the transfer of the data across the JVM boundary as a simple byte stream to the requestor of the particular DataFlavor.

    2.5.3 Transferring lists of files across the JVM boundary.

    A typical subject of a Drag and Drop transfer is a list of one or more platform dependent filenames. In order to ease the programming task of developers either producing or consuming such lists the drag and drop system treats them as a special case.

    If a DataFlavor is specified with a MIME "Content-Type" of application/x-java-file-list;class=java.util.List the drag and drop system will expect the list elements to be a homogeneous list of objects of type java.io.File. Thus a source shall, if supporting the transfer of a list of files, construct such a List of File objects when such a DataFlavor is requested, and a recipient shall expect such a List of File objects if it requests such a valid DataFlavor from its source. This special case provides a simple mechanism for the transfer of lists of files between source and target.

    2.5.4 Transferring java.rmi.Remote references across the JVM boundary.

    It is possible to Drag and Drop object references between JVMs' by using the facilities of the RMI mechanism. The Drag and Drop system will automatically arrange for the transfer of any object reference that adheres to these requirements:

    • The representation class of interface associated with the requested DataFlavor implements both java.rmi.Remote and java.io.Serializable.

      (the MIME "Content-Type" can be any suitable, arbitrary type or application/x-java-remote-object)

      (effectively the object implementation class transferred should be extended from java.rmi.server.UnicastRemoteObject since the RMI system implements some required initialization, without which the transfer will not complete properly).

    • The drop action is ACTION_LINK.

    If these conditions are met, then if an appropriate DataFlavor is requested, then the object returned to the requestor (if it is in a difference JVM from the source) will be an RMI reference to an instance of the Remote object subinterface specified as the representation class of the DataFlavor.

    3.0 Issues

    3.0.1 What are the implications of the various platform protocol engines?

    Due to limitations of particular underlying platform drag and drop and window system implementations, the interaction of a drag operation, and the event delivery semantics to AWT Components is platform dependent. Therefore during a drag operation a DragSource may process platform Window System Events pertaining to that drag to the exclusion of normal event processing.

    Due to interactions between the single-threaded design center of the platform native DnD systems, and the native window system event dispatching implementations in AWT, "callbacks" into DropTargetListener and DragSourceListener will occur either on, or synchronized with the AWT system event dispatch thread. This behavior is highly undesirable for security reasons but is an implementation, not architectural feature, and is unavoidable.

    3.0.2 Inter/Intra VM transfers?

    To enable intra-JVM Drag and Drop Transfers the existing DataFlavor class will be extended to enable it to represent the type of a "live" object reference, as opposed to a Serialized (persistent) representation of one. Such objects may be transferred between source and destination within the same JVM and ClassLoader context.

    The MIME Content-Type shall be application/x-java-local-objectref.

    3.0.3 Lifetime of the Transferable(s)?

    Transferable objects, their associated DataFlavors', and the objects that encapsulate the underlying data specified as the operand(s) of a drag and drop operation shall remain valid until, at least, the DragSourceListener associated with the DragSource controlling the operation, receives a dragDropEnd. The lifetime of the subject(s) of the operation, transferred between source and target is implementation defined beyond that point in time.

    3.0.4 Implications of ACTION_MOVE semantics on source objects exposed via Transferable?

    The "source" of a successful Drag and Drop (ACTION_MOVE) operation is required to delete/relinquish all references to the object(s) that are the subject of the Transferable immediately after transfer has been successfully completed. That is before returning from the DragSourceListener.dragDropEnd notification.

    3.0.5 Semantics of ACTION_REFERENCE operation.

    As a result of significant input from developers to an earlier version of the specification an additional operation/action tag; ACTION_REFERENCE was added to include existing platform Drag and Drop"Link" semantics.

    It is believed that Reference, or Link, semantics are already sufficiently poorly specified for the platform native Drag and Drop to render it essentially useless even between native applications, thus between native and platform independent Java applications it is not recommended.

    For Java to Java usage the required semantic; within the same JVM/ClassLoader, is defined such that the destination shall obtain a Java object reference to the subject(s) of the transfer. Between Java JVM's or ClassLoaders, the semantic is implementation defined, but could be implemented through transferring either a URL from the source to the destination or an RMI Remote reference.

    Appendix A : DropTargetPeer definition

    Although not a normative part of this specification this definition is included for clarity:

    public interface DropTargetPeer {
        void addDropTarget(DropTarget dt);
        void removeDropTarget(DropTarget dt);
}

    Appendix B : DragSourceContextPeer definition

    Although not a normative part of this specification this definition is included for clarity:

    public interface DragSourceContextPeer {
    void startDrag(DragSourceContext dsc,
                   Cursor            c,
                   Image             di,
                   Point             ioff
    ) throws InvalidDnDOperationException;
    Cursor getCursor();
    void   setCursor(Cursor c) throws InvalidDnDOperationException;
    void transferablesFlavorsChanged();
}

    Appendix C : DropTargetContextPeer definition

    Although not a normative part of this specification this definition is included for clarity:

    public interface DropTargetContextPeer {
    int  getTargetActions();
    void setTargetActions(int actions);
    DropTarget getDropTarget();
    DataFlavor[] getTransferDataFlavors();
    Transferable getTransferable() throws InvalidDnDOperationException;
    boolean isTransferableJVMLocal();
    void acceptDrag(int dragAction);
    void rejectDrag();
    void acceptDrop(int dropAction);
    void rejectDrop();
    void dropComplete(boolean success);
}


Extension Versioning

Java

Optional Package Versioning

 Optional Package Documentation

Note: Optional packages is the new term for what used to be known as standard extensions or just extensions.

This section includes the following topics:

  • Overview
  • Manifest Attributes for Use by Installed Optional Packages
  • Manifest Attributes for Use by Applet Jar Files
  • Java Plug-in Update Rules
  • Download and Installation of Optional Packages

Overview

Version 1.3 of the JavaTM 2 Platform introduced support for an expanded set of Jar-file manifest attributes that enable applets to specify version and vendor information for the optional packages that they require. The manifests of Jar-packaged applets can specify a URL at which the latest version of the optional package the Java Plug-in can download if

  • the needed optional package is not already installed in the Java runtime environment, or
  • the optional package is installed but has an out-of-date version number, or
  • the optional package is installed but is not from a specified vendor.

The manifest attributes that can be used to specify version and vendor information are described below.

Manifest Attributes for Use by Installed Optional Packages

The following portion of a sample manifest file illustrates the attributes that are available for use by optional packages.
Extension-Name: javax.help
Specification-Vendor: Sun Microsystems, Inc
Specification-Version: 1.0
Implementation-Vendor-Id: com.sun
Implementation-Vendor: Sun Microsystems, Inc
Implementation-Version: 1.0
The attributes in this example are:
Extension-Name
This attribute specifies a name for the optional package contained in the Jar file. The name should be a unique identifier such as the name of the main package comprising the optional package.
Specification-Vendor
This attribute identifies the company that originated the specification to which the optional package conforms.
Specification-Version
This attribute specifies the version number of the specification to which the implementation conforms.
Implementation-Vendor-Id
This attribute's value is a unique identifier for the company that produced the optional package implementation contained in the Jar file.
Implementation-Vendor
This attribute's value is the name of the company that produced the implementation of the optional package. This attribute should be used only for such purposes such as user feedback, and the Java Plug-in software does not use it to identify the optional package vendor. Rather, the Java Plug-in relies on the Implementation-Vendor-Id attribute to provide unique vendor identification.
Implementation-Version
This attribute indicates the vendor's version number for the implementation of the optional package.

Each optional package installed in the Java runtime environment can use these manifest attributes to identify itself. When the Java Plug-in is running an applet that requires an optional package, the plug-in can access these attributes to determine if the installed optional packages match the vendor and version criteria specified by the applet. The applet specifies such information by using the manifest attributes described in the following section. Note that all of the above manifest attributes should be included in an optional package's manifest. If the plug-in looks for but doesn't find one of these attributes in an optional package's manifest, it will assume that the optional package is not suitable for the applet.

Manifest Attributes for Use by Applet Jar Files

The following sample manifest file illustrates the attributes that are available for use by Jar-packaged applets. (This sample is for illustrative purposes only. No actual optional packages are available at the URLs mentioned in this example.)
Extension-List: javahelp java3d
javahelp-Extension-Name: javax.help
javahelp-Specification-Version: 1.0
javahelp-Implementation-Version: 1.0.3
javahelp-Implementation-Vendor-Id: com.sun
javahelp-Implementation-URL: http://java.sun.com/products/stdext/javahelp.jar
java3d-Extension-Name: javax.3d
java3d-Specification-Version: 1.0
java3d-Implementation-Version: 1.2.1
java3d-Implementation-Vendor-Id: com.sun
java3d-Implementation-URL: http://java.sun.com/products/stdext/java3d.jar
The attributes used in this example are:
Extension-List
This attribute indicates the optional packages that are needed by the applet. Each optional package listed in this attribute will have a set of additional attributes that the applet uses to specify which version and vendor of the optional package it requires.
<extension>-Extension-Name
This attribute is the unique name of the optional package. The Java Plug-in will compare the value of this attribute with the Extension-Name attribute in the manifests of installed optional packages to determine if the optional package is installed.
<extension>-Specification-Version (Optional)
This attribute specifies the minimum optional package specification version that is required by the applet. The Java Plug-in will compare the value of this attribute with the Specification-Version attribute of the installed optional package to determine if the optional package is up to date.
<extension>-Implementation-Version (Optional)
This attritute specifies the miminum optional package implementation version number that is required by the applet. The Java Plug-in will compare the value of this attribute with the Implementation-Version attribute of the installed optional package to see if a more recent implementation needs to be downloaded.
<extension>-Implementation-Vendor-Id (Optional)
This attribute can be used to identify the vendor of an optional package implementation if the applet requires an implementation from a specific vendor. The Java Plug-in will compare the value of this attribute with the Implementation-Vendor-Id attribute of the installed optional package.
<extension>-Implementation-URL
This attritute specifies a URL that can be used to obtain the most recent version of the optional package if the required version is not already installed.

Java Plug-in Update Rules

The Java Plug-in performs the following determinations when loading an applet whose manifest indicates that it needs one or more optional packages:

  • If an optional package with the correct value of the Extension-Name attribute is not installed, the Java Plug-in will prompt the user to let it download the optional package.
  • If an optional package with the correct value of the Extension-Name attribute is already installed, the Java Plug-in makes the following comparisons:
    • If the optional package's Specification-Version value is greater or equal to that required by the applet:
      • If the Implementation-Vendor-Id attributes match:
        • If the optional package's Implementation-Version is greater than or equal to that specified in the applet's manifest, do nothing - an up-to-date version of the optional package is already installed.
        • If the optional package's Implementation-Version is less than that specified in applet's manifest, the plug-in will prompt the user to download an upgrade from the same vendor.
      • If the Implementation-Vendor-Id attributes do not match, the Java Plug-in will prompt the user to download the optional package from the vendor specified in the applet's manifest.
    • If the optional package's Specification-Version value is less than that required by the applet:
      • If the optional package's Implementation-Vendor-Id matches that indicated in the applet's manifest, the Java Plug-in will prompt the user to download an updated optional package from the same vendor.
      • If the optional package's Implementation-Vendor-Id does not match that specified by the applet's manifest, the Java Plug-in will prompt the user to download the optional package from the vendor specified in the the applet's manifest.

If the applet's manifest doesn't contain one or more of the optional attributes, the plug-in will accept any value of the corresponding attribute in the optional package's manifest.

Download and Installation of Optional Packages

The following considerations pertain to optional packages that are downloaded by the Java Plug-in.

The optional package download URL as indicated in the applet manifest's <extension>-Implementation-URL attribute need not be limited to the Applet codebase.

All downloadable files should be signed using a DSA or RSA certificate. Any optional packages not so signed will not be installed but instead will be treated as a bundled optional package and loaded through the applet class loader, sharing the applet security attributes.

When the Java Plug-in retrieves an optional package from the URL indicated in the applet's manifest, it will check the optional package's manifest for a Main-Class attribute after verifying the optional package's signature. If the optional package's manifest file does not contain a Main-Class attribute, the Java Plug-in will simply drop the Jar file into the optional packages directory of the runtime environment (jre/lib/ext in the JDK and lib/ext in the JRE).

Some optional package Jar files may contain their own installer programs in either native code or as applications written in the Java programming language. Such an installer program may be necessary for purposes such as installing native libraries or accessing the Microsoft Windows registry, for example. If the Java Plug-in finds a Main-Class attribute in the optional package's manifest, it will assume that it indicates a class that serves as a Java-language installer and will invoke the main() method of that class.

An optional package's manifest may alternatively contain a Extension-Installation attribute. The value of this field will point to a native installation application that is to be used by the Java Plug-in to install the optional package.

The URL of an optional package as specified by the <extension>-Implementation-URL must point to a JAR-file. The plug-in will not download and install optional packages packaged as .exe or .bin files.

Some optional packages come packaged in different Jar files for different operating systems. Such cases can be accomodated by the <extension>-Implementation-URL attribute by using the $(os-name)$ construction in the attribute's value. Here is an example.

javaExt-Implementation-URL: http://.../stdext/javaExt-$(os-name)$.jar
Here, $(os-name)$ is the name of target operating system as defined by the os.name system property.
Copyright © 1999 Sun Microsystems, Inc. All Rights Reserved. Sun

Java Software


Optional Package Overview

Java

Optional Packages - An Overview

Contents

  • What an optional package is
  • Installed optional packages
  • Download optional packages

What an optional package is

Note: Optional packages were formerly known as standard extensions or just extensions.

Optional packages are packages of Java classes and associated native code that application developers can use to extend the functionality of the core platform. The extension mechanism allows the Java virtual machine (VM) to use the optional-package classes in much the same way as the VM uses bootstrap classes. (Bootstrap classes are those implementing the core platform, contained in jre/lib/rt.jar and several other important jar files. These include classes of the public API such as java.lang, java.io, etc., and classes supporting the platform's internationalization/localization features.). Like bootstrap classes, classes in optional packages do not have to be placed on the class path. The extension mechanism also provides a way for needed optional packages to be retrieved from specified URLs when they are not already installed in the Java 2 Runtime Environment or JDK.

Optional packages are embodied in JAR files, and every JAR file is a potential optional package. A JAR file can be made to play the role of an optional package in two ways:

  • by being placed in a special location in the Java 2 Runtime Environment or JDK directory structure - in which case it is an installed optional package.
  • by being referenced in a specified way from the manifest of the JAR file of an applet or application - in which case it is a download optional package.
When the VM is searching for a class of a particular name, it will first look among the bootstrap classes. If it fails to find the desired class there, it will next look for the class among any installed optional packages. If it doesn't find the class among either the bootstrap classes or the installed optional packages, the VM will search among any download optional packages referenced by the application or applet. The VM only searches the class path if it fails to find a class among the bootstrap classes or optional package classes.

Installed optional packages

Installed optional packages are JAR files in the directory
lib/ext       [in the JRE]
jre/lib/ext   [in the JDK]
Classes within JAR files in this directory can be used by applets and applications much as if they were part of the set of bootstrap classes, without having to explicitly include them in the class path.

An installed optional package's native code binaries, if any, are placed in

jre\bin         [Microsoft Windows]
jre/lib/<arch>  [Solaris operating environment]
where <arch> is the Solaris processor architecture, either sparc or i386. Native libraries may also be placed in jre/lib/ext/<arch> for both Microsoft Windows and the Solaris operating environment, where <arch> will be i386 on Microsoft Windows systems. The jre/lib/ext/<arch> directory is searched after jre\bin or jre/lib/<arch>.

When the Java VM encounters a class name, it looks first for the class in the runtime environment. If it fails to find the desired class among the classes that are part of the standard runtime environment, the VM will search for the class in any JAR files in the optional packages directory.

Note that there is nothing special about any particular JAR file itself or the classes it contains that makes it an installed optional package. It is an installed optional package by virtue of its location in jre/lib/ext.

The manifest of an installed optional package's JAR file should contain version and vendor information for use by applets that need to use the optional packages classes. The attributes that specify the version and vendor information are described in Optional Package Versioning. Here is an example of what such a manifest might look like:

Manifest-version: 1.0
Extension-Name: javax.extension
Specification-Version: 1.0
Specification Vendor: Sun Microsystems, Inc.
Implementation-Vendor: Sun Microsystems, Inc.
Implementation-Vendor-Id: com.sun
Sealed: true
This version and vendor information can be used by the Java Plug-in when running an applet to see if optional packages needed by the applet are installed, are up to date, and are from the vendor requested by the applet. If not, the Java Plug-in can prompt the applet user to download the proper optional package. See Optional Package Versioning for more information.

If a class is not found after searching both the system classes and the classes in the installed optional packages, the extension mechanism will search for the class in a download optional package....

Download optional packages

A download optional package is a JAR files that is specified in the Class-Path header field in the manifest of another JAR files. Classes in download optional packages may be used by classes in the referencing JAR file. In a typical situation, an applet will be bundled in a JAR file whose manifest references a JAR file (or several JAR files) that will serve as an optional package for the purposes of that applet. Optional packages may reference each other in the same way.

A Class-Path header might look like this, for example:

Class-Path: servlet.jar infobus.jar acme/beans.jar
This specifies that the classes in the files servlet.jar, infobus.jar, and acme/beans.jar will serve as optional pakcages for purposes of the classes in the JAR file whose manifest contains this header. The URLs in the Class-Path field are given relative to the URL of the JAR file of the applet or application.

Unlike the case of installed optional packages, the location of the JAR files that serve as download optional packages is irrelevent. A download optional package is an optional package because it is specified as the value of the Class-Path header in another JAR file's manifest, not because it has any particular location.

Another difference between installed and download optional packages is that only applets and applications bundled in a JAR file can make use of download optional packages. Applets and applications not bundled in a JAR file don't have a manifest from which to reference download optional packages.

When searching for a class, the VM first searches among the classes in the system classes and in any installed optional packages. If the class is not found in either the system classes or in the installed optional packages, the VM will search for the class in any download optional packages referenced by the manifest of the application or applet. A download optional package will not be downloaded if a desired class is found among the installed optional packages, even if the download optional package is referenced by the manifest file of the applet or application.

The extension mechanism will not install a download optional package in the JRE or JDK directory structure. Download optional packages do not become installed extentions after they have once been downloaded.

Unlike installed optional packages, download optional packages cannot have any native code.

Copyright © 1997, 1998 Sun Microsystems, Inc. All Rights Reserved. Sun

Java Software


The Extension Mechanism

for Support of Optional Packages

 Documentation Contents

Optional packages are packages of classes (and any associated native code) that application developers can use to extend the functionality of the core platform. The extension mechanism allows the Java virtual machine (VM) to use the classes of the optional extension in much the same way as the VM uses classes in the Java Platform. The extension mechanism also provides a way for needed optional packages to be retrieved from specified URLs when they are not already installed in the JDK or JRE.

Overview
  • Overview - What optional packages are and how to use them.
API Specification

The following classes play a role in the extension mechanism:

  • java.lang.ClassLoader
  • java.lang.Package
  • java.lang.Thread
  • java.net.JarURLConnection
  • java.net.URLClassLoader
  • java.security.SecureClassLoader
See also the API Details section of the mechanism specification for notes on these APIs.

Tutorials and Programmer's Guides

Located on the Java Software website:
  • The Extension Mechanism trail of the Java Tutorial.

API Enhancements

  • Enhancements to the extension mechanism in version 1.3 included an extended set of manifest attributes that can be used for checking vendor and versioning information of installed optional packages. If an applet requires an optional package that isn't installed, or that is installed but has the wrong version number or is not from the appropriate vendor, the Java Plug-in can download the needed extension from a specified URL. For more information, see Optional-Package Versioning.
More Information
  • Extension Mechanism Architecture - Notes on the extension mechanism API and how optional packages use the Jar file format.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback

Sun
Java Software


The Extension Mechanism

Java

Extension Mechanism Architecture

Contents

  • Introduction
  • The Extension Mechanism
    • Architecture
    • Optional Package Deployment
    • Bundled Optional Packages
    • Installed Optional Packages
  • Optional Package Sealing
  • Optional Package Security
  • Related APIs

Introduction

Note: Optional packages are the new name for what used to be known as standard extensions. The "extension mechanism" is that functionality of the JDK™ and JRE™ that supports the use of optional packages.

This document describes the mechanism provided by the Java™ platform for handling optional packages. An optional package is a group of packages housed in one or more JAR files that implement an API that extends the Java platform. Optional package classes extend the platform in the sense that the virtual machine can find and load them without their being on the class path, much as if they were classes in the platform's core API.

Since optional packages extend the platform's core API, their use should be judiciously applied. Most commonly they are used for well standardized interfaces such as those defined by the Java Community ProcessSM, although it may also be appropriate for site wide interfaces. Optional packages are rarely appropriate for interfaces used by a single, or small set of applications.

Furthermore, since the symbols defined by installed optional packages will be visible in all Java processes, care should be taken to ensure that all visible symbols follow the appropriate "reverse domain name" and "class hierarchy" conventions. For example, com.mycompany.MyClass.

An implementation of an optional package may consist of code written in the Java programming language and, less commonly, platform-specific native code. In addition, it may include properties, localization catalogs, images, serialized data, and other resources specific to the optional package.

Support for optional packages in browsers such as Internet Explorer and Netscape Navigator is available through the Java Plug-in.

A optional package is an implementation of an open, standard API (examples of optional packages from Sun are JavaServlet, Java3D, JavaManagement). Most optional packages are rooted in the javax.* namespace, although there may be exceptions.

The Extension Mechanism

Architecture

The extension mechanism is designed to contain the following elements:
  • an optional package or application packaged as a JAR file can declare dependencies on other JAR files, thus allowing an application to consist of multiple modules, and,
  • the class loading mechanism is augmented to search installed optional packages (and other libraries) for classes, and, if that fails, to search along an application-specified path for classes.
Applications must therefore, in general, be prepared to specify and supply the optional packages (and, more generally, libraries) that it needs. The system will prefer installed copies of optional packages (and libraries) if they exist; otherwise, it will delegate to the class loader of the application to find and load the referenced optional package (and library) classes.

This architecture, since it allows applications, applets and servlets to extend their own class path, also permits packaging and deploying these as multiple JAR files.

Each optional package or application consists of at least one JAR file containing an optional manifest, code and assorted resources. As described below, this primary JAR file can also include additional information in its manifest to describe dependencies on other JAR files. The jar command line tool included with the JDK provides a convenient means of packaging optional packages. (See the reference pages for the jar tool: [Microsoft Windows] [Solaris™ Operating System (Solaris OS), Linux])

An optional package or application may refer to additional JAR files which will be referenced from the primary JAR, and these can optionally contain their own dependency information as well.

Packages comprising optional packages should be named per the standard package naming conventions when implementing optional packages. These conventions are outlined in The Java Language Specification, but the requirement that the domain prefix be specified in all upper case letters has been removed. For example, the package name com.sun.server is an accepted alternative to COM.sun.server. Unique package naming is recommended in order to avoid conflicts, because applications and optional packages may share the same class loader.

Optional Package Deployment

An optional package may either be bundled with an application or installed in the JRE for use by all applications. Bundled optional packages are provided at the same code base as the application and will automatically be downloaded in the case of network applications (applets). For this reason, bundled optional packages are often called download optional packages. When the manifest of a bundled optional package's JAR file contains version information and the JAR is signed, it can be installed into the extensions directory of the JRE which downloads it (see Deploying Java Extensions). Installed optional packages are loaded when first used and will be shared by all applications using the same JRE.

When packaging optional packages, the JAR file manifest can be used to identify vendor and version information (see Package Version Identification).

Classes for installed optional packages are shared by all code in the same virtual machine. Thus, installed optional packages are similar to the platform's core classes (in rt.jar), but with an associated class loader and a pre-configured security policy as described below.

Classes for bundled optional packages are private to the class loader of the application, applet or servlet. In the case of network applications such as applets, these optional packages will be automatically downloaded as needed. Since class loaders are currently associated with a codebase, this permits multiple applets originating from the same codebase to share implementations (JARs). However, signed bundled optional packages with version information as described above are installed in the JRE, and their contents are available to all applications running on that JRE and are therefore not private.

Bundled Optional Packages

The manifest for an application or optional package can specify one or more relative URLs referring to the JAR files and directories for the optional packages (and other libraries) that it needs. These relative URLs will be treated relative to the code base that the containing application or optional package JAR file was loaded from.

An application (or, more generally, JAR file) specifies the relative URLs of the optional packages (and libraries) that it needs via the manifest attribute Class-Path. This attribute lists the URLs to search for implementations of optional packages (or other libraries) if they cannot be found as optional packages installed on the host Java virtual machine*. These relative URLs may include JAR files and directories for any libraries or resources needed by the application or optional package. Relative URLs not ending with '/' are assumed to refer to JAR files. For example,

Class-Path: servlet.jar infobus.jar acme/beans.jar images/
At most one Class-Path header may be specified in a JAR file's manifest..

Currently, the URLs must be relative to the code base of the JAR file for security reasons. Thus, remote optional packages will originate from the same code base as the application.

Each relative URL is resolved against the code base that the containing application or optional package was loaded from. If the resulting URL is invalid or refers to a resource that cannot be found then it is ignored.

The resulting URLs are used to extend the class path for the application, applet, or servlet by inserting the URLs in the class path immediately following the URL of the containing JAR file. Any duplicate URLs are omitted. For example, given the following class path:

        a.jar b.jar
If optional package b.jar contained the following Class-Path manifest attribute:
        Class-Path: x.jar a.jar
Then the resulting application class path would be the following:
        a.jar b.jar x.jar
Of course, if x.jar had dependencies of its own then these would be added according to the same rules and so on for each subsequent URL. In the actual implementation, JAR file dependencies are processed lazily so that the JAR files are not actually opened until needed.

Installed Optional Packages

Beginning with Sun's implementation of the Java 2 Platform, the JAR files of a installed optional package are placed in a standard local code source:
<java-home>\lib\ext                     [Microsoft Windows]
<java-home>/lib/ext                     [Solaris OS, Linux]

Here <java-home> refers to the directory where the runtime software is installed (which is the top-level directory of the JRE or the jre directory in the JDK).

The locations for installed optional packages can be specified through the system property java.ext.dirs. This property specifies one or more directories to search for installed optional packages, each separated by File.pathSeparatorChar. The default setting for java.ext.dirs is the standard directory for installed optional packages, as indicated above. For Java 6 and later, the default is enhanced: it is suffixed with the path to a platform-specific directory that is shared by all JREs (Java 6 or later) installed on a system:

%SystemRoot%\Sun\Java\lib\ext           [Microsoft Windows]
/usr/java/packages/lib/ext              [Linux]
/usr/jdk/packages/lib/ext               [Solaris OS]

An installed optional package may also contain one or more shared libraries (such as .dll files) and executables. In what follows, <arch> will be shown but in practice should be the name of an instruction set architecture, for example sparc, sparcv9, i386, and amd64. These can be installed in one of two places. The first to be searched is:

<java-home>\bin                         [Microsoft Windows]
<java-home>/lib/<arch>                  [Solaris OS, Linux]

The second extension directory to be searched applies only to Java 6 and later. As with Java packages, native libraries can be installed in directories that will be shared by all Java 6 and later JREs:

%SystemRoot%\Sun\Java\bin               [Microsoft Windows]
/usr/java/packages/lib/<arch>           [Linux]
/usr/jdk/packages/lib/<arch>            [Solaris OS]

An optional package that contains native code cannot be downloaded by network code into the virtual machine at execution time, whether such code is trusted or not. An optional package that contains native code and is bundled with a network application must be installed in the JDK or JRE.

By default, installed optional packages in this standard directory are trusted. That is, they are granted the same privileges as if they were core platform classes (those in rt.jar). This default privilege is specified in the system policy file (in <java-home>/jre/lib/security/java.policy), but can be overridden for a particular optional package by adding the appropriate policy file entry (see Permissions in the JDK).

Note also that if a installed optional package JAR is signed by a trusted entity, then it will be granted the privileges associated with the trusted signer.

Optional Package Sealing

JAR files and packages can be optionally sealed, so that an optional package or package can enforce consistency within a version.

A package sealed within a JAR specifies that all classes defined in that package must originate from the same JAR. Otherwise, a SecurityException is thrown.

A sealed JAR specifies that all packages defined by that JAR are sealed unless overridden specifically for a package.

A sealed package is specified via the manifest attribute, Sealed, whose value is true or false (case irrelevant). For example,

Name: javax/servlet/internal/
Sealed: true
specifies that the javax.servlet.internal package is sealed, and that all classes in that package must be loaded from the same JAR file.

If this attribute is missing, the package sealing attribute is that of the containing JAR file.

A sealed JAR is specified via the same manifest header, Sealed, with the value again of either true or false. For example,

Sealed: true
specifies that all packages in this archive are sealed unless explicitly overridden for a particular package with the Sealed attribute in a manifest entry.

If this attribute is missing, the JAR file is assumed to not be sealed, for backwards compatibility. The system then defaults to examining package headers for sealing information.

Package sealing is also important for security, because it restricts access to package-protected members to only those classes defined in the package that originated from the same JAR file.

Package sealing is checked for installed as well as downloaded optional packages, and will result in a SecurityException if violated. Also, the null package is not sealable, so classes that are to be sealed must be placed in their own packages.

Optional Package Security

The code source for a installed optional package (namely <java-home>/lib/ext) has a pre-configured security policy associated with it. In Sun's implementation, the exact level of trust granted to JARs in this directory is specified by the standard security policy configuration file
<java-home>/lib/security/java.policy
The default policy is for a installed optional package to behave the same way it would if were part of the core platform. This follows from the common need for a installed optional package to load native code.

The Java Security Model provides some safety when installed optional package code is called from untrusted code. However optional package code must be carefully reviewed for potential security breaches wherever it uses privileged blocks.

A remotely loaded optional package that needs to use access-checked system services (such as file I/O) to function correctly must either be signed by a trusted entity or loaded from a trusted source.

Consult the Java security documentation for further details regarding how to write optional package and application code to use the security features of the Java Platform.

Related APIs

Several classes in the Java platform support the extension mechanism, including:
  • public class java.lang.ClassLoader
  • public class java.lang.Package
  • public class java.net.URLClassLoader

*As used on this web site, the terms "Java Virtual Machine" or "JVM" mean a virtual machine for the Java platform.

Copyright © 1997-2006 Sun Microsystems, Inc. All Rights Reserved. Sun


Changes in CORBA Features Between J2SE 1.4.x and 5.0

 Java SE Documentation Contents

This release of the JavaTM 2 Platform Standard Edition (J2SE), contains the following enhancements to CORBA, Java IDL, and Java RMI-IIOP technology:

  • Enhancement 4674929. Additional serviceability features for the Java SE ORB provide a logging framework based on J2SE 1.4 logging APIs. When an error is encountered and an OMG minor code is generated, this minor code will now be translated to a Java error code for error logging. The ORB will also include the standard minor codes as specified by the OMG specifications.

  • Enhancement 4607440. Better performance of the default ORB in Java SE in high volume deployments, including better scalability and performance.

  • Enhancement 4629589. Added Object Reference Template (ORT) to ORB. An Object Reference Template is an extension to portable interceptors that supports portable server activation frameworks, load balancing, fault tolerance, dynamic bridging, and other advanced features.

  • Enhancement 4674944. Added on-the-wire interoperability. This includes identifying and incorporating any resolutions and/or updates from the OMG of any interoperability issues since CORBA 2.3.1 that affect on-the-wire interoperability for the J2EE Application Servers, and incorporating those resolutions into the Java SE ORB.

  • When the J2SE 5.0 ORB marshals an org.omg.CORBA.SystemException response, it adds an ExceptionDetailMessage (i.e., a ServiceContext with ServiceId 14) as defined in:

        /**
     * CORBA formal/02-06-01: 13.7.1:
     * ExceptionDetailMessage identifies a CDR encapsulation of a wstring,
     * encoded using GIOP 1.2 with a TCS-W of UTF-16.  This service context
     * may be sent on Reply messages with a reply_status of SYSTEM_EXCEPTION
     * or USER_EXCEPTION. The usage of this service context is defined
     * by language mappings.
     *
     * IDL/Java: ptc/02-01-22: 1.15.2:
     * When a System Exception is marshaled, its GIOP Reply message shall
     * include an associated ExceptionDetailMessage service context. The
     * callee's stack trace is often very valuable debugging information but
     * may contain sensitive or unwanted information. The wstring within the
     * service context will therefore contain additional information relating
     * to the exception, for example the result of calling either
     * printStackTrace(PrintWriter) or getMessage() on the exception. When
     * unmarshaling a System Exception on the client side, the wstring from
     * any ExceptionDetailMessage service context shall become the Java error
     * message in the unmarshaled exception object.
     */

    When the J2SE 5.0 ORB unmarshals an org.omg.CORBA.SystemException response it constructs the SystemException with the contents of the ExceptionDetailMessage as the message argument to the SystemException constructor.

    NOTE: The content of the message may change. In J2SE 5.0, the message contains the server side stack trace. The following code example (note: all details may change) of a stack trace on the client side for an exception generated on the server-side (note the server-side stack trace in the exception's message):

    org.omg.CORBA.FREE_MEM: ----------BEGIN server-side stack trace----------
org.omg.CORBA.FREE_MEM: idlIConnect  vmcid: 0x0  minor code: 0  completed: No
    at corba.exceptiondetailsc.idlIServantConnect.raise_system_exception(idlIServantConnect.java:23)
    at corba.exceptiondetailsc._idlIImplBase._invoke(_idlIImplBase.java:42)
    at com.sun.corba.ee.impl.protocol.CorbaServerRequestDispatcherImpl.dispatchToServant(CorbaServerRequestDispatcherImpl.java:647)
    at com.sun.corba.ee.impl.protocol.CorbaServerRequestDispatcherImpl.dispatch(CorbaServerRequestDispatcherImpl.java:190)
    at com.sun.corba.ee.impl.protocol.CorbaMessageMediatorImpl.handleRequestRequest(CorbaMessageMediatorImpl.java:1653)
    at com.sun.corba.ee.impl.protocol.CorbaMessageMediatorImpl.handleRequest(CorbaMessageMediatorImpl.java:1513)
    at com.sun.corba.ee.impl.protocol.CorbaMessageMediatorImpl.handleInput(CorbaMessageMediatorImpl.java:895)
    at com.sun.corba.ee.impl.protocol.giopmsgheaders.RequestMessage_1_2.callback(RequestMessage_1_2.java:172)
    at com.sun.corba.ee.impl.protocol.CorbaMessageMediatorImpl.handleRequest(CorbaMessageMediatorImpl.java:668)
    at com.sun.corba.ee.impl.transport.SocketOrChannelConnectionImpl.dispatch(SocketOrChannelConnectionImpl.java:375)
    at com.sun.corba.ee.impl.transport.SocketOrChannelConnectionImpl.read(SocketOrChannelConnectionImpl.java:284)
    at com.sun.corba.ee.impl.transport.ReaderThreadImpl.doWork(ReaderThreadImpl.java:73)
    at com.sun.corba.ee.impl.orbutil.threadpool.ThreadPoolImpl$WorkerThread.run(ThreadPoolImpl.java:382)
----------END server-side stack trace----------  vmcid: 0x0  minor code: 0  completed: No
    at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
    at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:39)
    at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:27)
    at java.lang.reflect.Constructor.newInstance(Constructor.java:274)
    at com.sun.corba.ee.impl.protocol.giopmsgheaders.MessageBase.getSystemException(MessageBase.java:791)
    at com.sun.corba.ee.impl.protocol.giopmsgheaders.ReplyMessage_1_2.getSystemException(ReplyMessage_1_2.java:97)
    at com.sun.corba.ee.impl.protocol.CorbaMessageMediatorImpl.getSystemExceptionReply(CorbaMessageMediatorImpl.java:546)
    at com.sun.corba.ee.impl.protocol.CorbaClientRequestDispatcherImpl.processResponse(CorbaClientRequestDispatcherImpl.java:407)
    at com.sun.corba.ee.impl.protocol.CorbaClientRequestDispatcherImpl.marshalingComplete(CorbaClientRequestDispatcherImpl.java:303)
    at com.sun.corba.ee.impl.protocol.CorbaClientDelegateImpl.invoke(CorbaClientDelegateImpl.java:132)
    at org.omg.CORBA.portable.ObjectImpl._invoke(ObjectImpl.java:457)
    at corba.exceptiondetailsc._idlIStub.raise_system_exception(_idlIStub.java:20)
    at corba.exceptiondetailsc.Client.main(Client.java:87)

------------------------------------------------------------------------------

See Official Specifications for CORBA support in J2SE 5.0 for information on how Java IDL and Java RMI-IIOP comply with the CORBA Specifications.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved. Sun

Java Software


Concepts

Distributed Application Concepts

CORBA and the Java Platform

Glossary

Home Concepts Programming Reference Tutorial
Copyright © 1996-2004 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.


CORBA and Java technologies

Java OMG Sun

CORBA Technology and the JavaTM 2 Platform Standard Edition

The Java 2 Platform Standard Edition, v1.4, provides an Object Request Broker (ORB) and two CORBA programming models that can utilize the Java CORBA ORB and Internet InterORB Protocol (IIOP). This topic discusses these options for creating and distributing CORBA technology.

CORBA technology is an integral part of the Java 2 platform. It consists of an Object Request Broker (ORB), APIs for the the RMI programming model, and APIs for the the IDL programming model.

For more information on which specifications are implemented in this release of the Java platform, see the compliance document.

How does Java SE leverage CORBA

Common Object Request Broker Architecture (CORBA) technology is the open standard for heterogeneous computing. CORBA complements the JavaTM platform by providing a distributed object framework, services to support that framework, and interoperability with other languages. The Java platform complements CORBA by providing "Write Once, Run AnywhereTM" portability, a highly productive implementation environment, and a very robust platform. By combining the Java platform with CORBA and other key enterprise technologies, the Java 2 Platform is the ultimate platform for distributed technology solutions.

CORBA standards provide the proven, interoperable infrastructure to the Java platform. IIOP (Internet Inter-ORB Protocol) manages the communication between the object components that power the system. The Java platform provides a portable object infrastructure that works on every major operating system. CORBA provides the network transparency, Java provides the implementation transparency.

The Object Request Broker

An Object Request Broker (ORB) is part of the Java 2 Platform Standard Edition, since version 1.3. The ORB is a runtime component that can be used for distributed computing using IIOP communication.

NOTE: Although it is true that ORBs written in different languages should be able to talk to each other, we haven't tested the interoperability of the Java ORB with other vendor's ORBs.

The Object Management Group (OMG) is an industry consortium that creates and publishes specifications for CORBA. Vendors implement the specifications to produce products known as Object Request Brokers (ORB). The good news for developers is that the JavaTM Platform Standard Edition, v1.2 and higher includes an ORB that is available in every deployment of the Java 2 Platform Standard Edition. To read more about the ORB class, follow the link.

The Java CORBA ORB supports both the RMI and IDL programming models, both of which can use the underlying IIOP wire-level protocol for communication.

Introducing the CORBA Programming Models

History of the CORBA Programming Models

In 1997, Remote Method Invocation, or RMI, was introduced in JDK 1.1. Initially, RMI was positioned as a natural outgrowth of Remote Procedure Calls (RPC), strictly for enabling calls to be made between Java objects in different virtual machines, and even on different physical machines.

In 1998, came JDK 1.2, which introduced Java IDL, a Java API for interoperability and integration with CORBA. Java IDL included both a Java-based ORB, which supported IIOP, and the IDL-to-Java compiler, idltojava, for generating client-side stubs and server-side code skeletons. The ORB supports both the RMI over IIOP and Java IDL programming models.

In 1999, the RMI over IIOP standard extension to the Java platform was introduced for JDK 1.1.6 and 1.2. Now that RMI over IIOP is integrated into J2SE version 1.3 and higher, the optional download has been end-of-lifed, but is still available from the archives.

The OMG finalized modifications of its IIOP specification so that it would support most of the JDK 1.1 functionality of RMI. RMI over IIOP was introduced as a standard extension to JDK 1.2. This enabled remote objects written in the Java programming language to be accessible from any language via IIOP.

J2SE, v.1.3 introduced a new, 100% Pure JavaTM, IDL-to-Java compiler, idlj, along with support for IDL abstract interfaces and value types. Also in v.1.3, RMI over IIOP is included in the JDK.

J2SE v.1.4, the current version, was introduced in 2001, and includes support for the Portable Object Adapter, Portable Interceptors, Interoperable Naming Service, GIOP 1.2, and Dynamic Anys. J2SE v.1.4 also includes an Object Request Broker Daemon (ORBD), which is used to enable clients to transparently locate and invoke persistent objects on servers in the CORBA environment, and servertool, which provides a command-line interface for application programmers to register, unregister, startup, and shutdown a persistent server. For more information on new features in J2SE v.1.4, see Changes in CORBA Features Between J2SE 1.3 and 1.4.

Comparing the CORBA Programming Models

Cross-language, cross-vendor interoperability is achieved via the Internet InterORB Protocol, or IIOP. IIOP is a transport protocol for distributed applications written in either IDL or Java RMI.

When using the IDL programming model, the interface is everything! It defines the points of entry that can be called from a remote process, such as the types of arguments the called procedure will accept, or the value/output parameter of information returned. Using IDL, the programmer can make the entry points and data types that pass between communicating processes act like a standard language.

CORBA is a language-neutral system in which the argument values or return values are limited to what can be represented in the involved implementation languages. In CORBA, object orientation is limited only to objects that can be passed by reference (the object code itself cannot be passed from machine-to-machine) or are predefined in the overall framework. Passed and returned types must be those declared in the interface.

With RMI, the interface and the implementation language are described in the same language, so you don't have to worry about mapping from one to the other. Language-level objects (the code itself) can be passed from one process to the next. Values can be returned by their actual type, not the declared type. Or, you can compile the interfaces to generate IIOP stubs and skeletons which allow your objects to be accessible from other CORBA-compliant languages.

The RMI Programming Model

What is the RMI Programming Model

The RMI Programming model is a general object model for distributed computing via the rmi API. You can choose to work completely within the Java programming language, using the Java Remote Method Protocol (JRMP) or work with other CORBA-compliant programming languages using the Internet InterORB Protocol (IIOP).

The RMI programming model is part of the JavaTM 2 Platform Standard Edition, and consists of both an Object Request Broker (ORB) and the rmic compiler. The rmic compiler is used to generate stubs, skeletons, and ties for remote objects using either the JRMP or IIOP protocols. The rmic compiler can also generates OMG IDL. For more information on using rmic, link to rmic - The Java RMI Stub Compiler.

The RMI over IIOP Programmer's Guide discusses the differences between using RMI with JRMP or IIOP.

When should I use the RMI programming model instead of the IDL programming model?

The RMI programming model speeds distributed application development by allowing developers to work completely in the Java programming language. When using the RMI programming model to produce Java technology-based distributed applications, there is no separate Interface Definition Language (IDL) or mapping to learn. The RMI programming model provides flexibility by allowing developers to pass any serializable Java object (Objects By Value) between application components. Like the IDL programming model, the RMI programming model is based on open standards defined with the participation of hundreds of vendors and users in the Java Community Process (JCP). Like the IDL programming model, the RMI programming model can use the Internet Inter-ORB Protocol (IIOP) as its communication protocol. IIOP eases legacy application and platform integration by allowing application components written in C++, Smalltalk, and other CORBA supported languages to communicate with components running on the Java platform.

With the RMI programming model, developers can write remote interfaces in the Java programming language and implement them simply using Java technology and the Java RMI APIs. These interfaces can be implemented in any other language that is supported by an OMG mapping and a vendor supplied ORB for that language. Similarly, clients can be written in other languages using IDL derived from the remote Java technology-based interfaces.

Where can I found out more about the RMI programming model

  • For more information on RMI over IIOP, see RMI over IIOP Documentation.

  • For more information on RMI over JRMP, see RMI Documentation.

  • For an introductory tutorial using RMI over IIOP, see Tutorial: Getting Started with RMI over IIOP.

  • For more information on mapping Java interfaces to OMG IDL, see Java Language to OMG IDL Mapping Specification.

The IDL Programming Model

What is the IDL Programming Model

The IDL programming model, known as JavaTM IDL, consists of both the Java CORBA ORB and the idlj compiler that maps the OMG IDL to Java bindings that use the Java CORBA ORB, as well as a set of APIs, which can be explored by selecting the org.omg prefix from the Package section of the API index.

Java IDL adds CORBA (Common Object Request Broker Architecture) capability to the Java platform, providing standards-based interoperability and connectivity. Java IDL enables distributed Web-enabled Java applications to transparently invoke operations on remote network services using the industry standard IDL (Object Management Group Interface Definition Language) and IIOP (Internet Inter-ORB Protocol) defined by the Object Management Group. Runtime components include a Java ORB for distributed computing using IIOP communication.

To use the IDL programming model, you define remote interfaces using the Object Management Group's (OMG) Interface Definition Language (IDL), then compile the interfaces using the idlj compiler. When you run the idlj compiler over your interface definition file, it generates the Java version of the interface, as well as the class code files for the stubs and skeletons that enable your applications to hook into the ORB.

JavaTM IDL is part of the Java 2 Platform Standard Edition, v1.2 and above. To develop applications with Java IDL, use JavaTM IDL Compiler, idlj, which is included in every installation of J2SE v1.3 and higher.

When should I use the IDL programming model instead of the RMI programming model?

The OMG IDL (Interface Definition Language) is a purely declarative language designed for specifying programming-language-independent operational interfaces for distributed applications. OMG specifies a mapping from IDL to several different programming languages, including Java, C, C++, Lisp, Python, Smalltalk, COBOL, and Ada. When mapped, each statement in OMG IDL is translated to a corresponding statement in the programming language of choice. Java IDL is an implementation of the CORBA specification. For example, you could use the Java IDL Compiler, idlj, to map an IDL interface to Java and implement the client class in Java. If you map the same IDL to C++, using an IDL-to-C++ compiler and a C++ ORB, and implement the server in that language, the Java client and C++ server interoperate through the ORB.

NOTE: Although it is true that ORBs written in different languages should be able to talk to each other, we haven't tested the interoperability of the Java ORB with other vendor's ORBs.

Where can I find out more about the IDL programming model

  • For more information on the IDL programming model, see Java IDL Documentation.

  • For an introductory tutorial to the IDL programming model, see Tutorial: Getting Started with Java IDL .

  • For more information on how IDL maps to the Java language, see see the OMG IDL to Java Language Mapping Specification.

Comparison of IDL and RMI programming models

There are several scenarios that will define how you will want to create distributed CORBA applications. Here are some of them:

  • If you have been developing CORBA applications using IDL for some time, you will probably want to stay in this environment. Create the interfaces using IDL, and define the client and server applications using the Java programming language to take advantage of its "Write Once, Run AnywhereTM" portability, its highly productive implementation environment, and its very robust platform.

  • If all of your applications are written in the Java programming language, you will probably want to use Java RMI to enable communication between Java objects on different virtual machines and different physical machines. Using Java RMI without its IIOP option leverages its strengths of code portability, security, and garbage collection.

  • If you are writing most of your new applications using the Java programming language, but need to maintain legacy applications written in other programming languages as well, you will probably want to use Java RMI with its IIOP compiler option.

What about CORBA and J2EE?

In addition to Java IDL and RMI over IIOP, J2EE includes Enterprise JavaBeansTM technology (EJBTM).

Enterprise JavaBeans is part of the Java 2 Platform, Enterprise Edition. The EJB server-side component model simplifies development of middleware components that are transactional, scalable, and portable. EJB servers reduce the complexity of developing middleware by providing automatic support for middleware services such as transactions, security, database connectivity, and more.

EJBs use RMI over IIOP for their distributed object model, and use the Java Transaction Service (JTS) for their distributed transaction model. When Enterprise JavaBeans are implemented using the RMI over IIOP protocol for EJB interoperability in heterogeneous server environments, the standard mapping of the EJB architecture to CORBA enables the following interoperability:

  • A Java client using an ORB from one vendor can access enterprise beans residing on an EJB server provided by another vendor.
  • Enterprise beans in one EJB server can access enterprise beans in another EJB server.
  • A non-Java platform CORBA client can access any enterprise bean object.

Copyright © 2002 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


CORBA Compatibility Information

CORBA Compatibility Information - J2SE 5.0
  • CORBA API Changes Between J2SE 1.4.x and J2SE 5.0.x
  • Official Specifications for CORBA support in J2SE 5.0.x
  • Other Compatibility Information

CORBA API Changes Between J2SE 1.3 and J2SE 5.0

This document contains information regarding all of the API changes related to CORBA functionality between JDK 1.3 and 5.0. The changes have been made to make the APIs for the CORBA technology shipped in the JDK 5.0 compliant to the CORBA 2.3 mapping as specified by the following OMG documents:
  • CORBA 2.3.1 (formal/99-10-07)
  • IDL to Java language mapping (ptc/00-01-08)
  • Java to IDL language mapping (ptc/00-01-06)
  • Interoperable Naming Service (/ptc/00-08-07)
  • Portable Interceptors (ptc/2001-03-04)

API changes to org.omg.COSNaming classes

To comply with the IDL to Java mapping specified by the CORBA Version 2.3 specification, the following org.omg.COSNaming classes have been regenerated from the idlj compiler shipped with the JDK. This change (CCC 4284015) consists of the following API changes. Compatibility impact: None.

    To conform with CORBA V (2.3) All Helpers Section 1.5.2 Spec ptc/00-01-08.pdf, all Helpers are now abstract public classes. Below is the list of all Helper classes under org.omg.CosNaming that have been changed to abstract public classes.

    • BindingHelper.java
    • BindingIteratorHelper.java
    • BindingListHelper.java
    • BindingTypeHelper.java
    • IStringHelper.java
    • NameComponentHelper.java
    • NameHelper.java
    • NamingContextHelper.java
    • AlreadyBoundHelper.java
    • CannotProceedHelper.java
    • InvalidNameHelper.java
    • NotEmptyHelper.java
    • NotFoundHelper.java
    • NotFoundReasonHelper.java

    To conform with Section 1.7 OMG Spec ptc/00-01-08.pdf, Mapping for Enum, the mapping for the following Enum constructors is changed to protected.
    CLASS | BEFORE | NOW
BindingType.java | private BindingType( int ) | protected BindingType( int )
NotFoundReason.java | private NotFoundReason( int ) | protected NotFoundReason( int )

  1. To conform with CORBA 2.3 spec (ptc/00-01-08.pdf), Deletion of constructors in Stub classes, the following constructors have been deleted.

    2. CLASS | BEFORE | NOW
_BindingIteratorStub.java | public _BindingIteratorStub(org.omg.CORBA.portable.Delegate d) | The constructor is deleted.
_NamingContextStub.java | public _NamingContextStub(org.omg.CORBA.portable.Delegate d) | The constructor is deleted.

  2. To conform with CORBA 2.3 spec (ptc/00-01-08.pdf), the following exceptions have been changed.

    3. CLASS | BEFORE | NOW
AlreadyBound.java | public final class AlreadyBound extends org.omg.CORBA.UserException implements org.omg.CORBA.portable.IDLEntity | public final class AlreadyBound extends org.omg.CORBA.UserException
AlreadyBound.java | Only default constructor | Add new constructor public AlreadyBound (String reason)
CannotProceed.java | public final class CannotProceed extends org.omg.CORBA.UserException implements org.omg.CORBA.portable.IDLEntity | public final class CannotProceed extends org.omg.CORBA.UserException
CannotProceed.java | Only default constructor | Add new constructor public CannotProceed (String reason)
InvalidName.java | public final class InvalidName extends org.omg.CORBA.UserException implements org.omg.CORBA.portable.IDLEntity | public final class InvalidName extends org.omg.CORBA.UserException
InvalidName.java | Only default constructor | Add new constructor public InvalidName (String reason)
NotEmpty.java | public final class NotEmpty extends org.omg.CORBA.UserException implements org.omg.CORBA.portable.IDLEntity | public final class NotEmpty extends org.omg.CORBA.UserException
NotEmpty.java | Only default constructor | Add new constructor public NotEmpty (String reason)
NotFound.java | public final class NotFound extends org.omg.CORBA.UserException implements org.omg.CORBA.portable.IDLEntity | public final class NotFound extends org.omg.CORBA.UserException
NotFound.java | Only default constructor | Add new constructor public NotFound (String, org.omg.CosNaming.NamingContextPackage.NotFoundReason, org.omg.CosNaming.NameComponent[])

  3. To conform with the CORBA 2.3 specification, the following classes have been added.

    • NamingContextPOA.java
    • BindingIteratorPOA.java

    To conform with the CORBA 2.3 specification, the following classes are deprecated.

    • _NamingContextImplBase.java
    • _BindingIteratorImplBase.java

API changes to org.omg.CORBA

  • To conform to OMG spec 99-07-57, IDL to Java mapping, the following methods have been changed.

    • The signature of method org.omg.CORBA.Any.insert_fixed(java.math.BigDecimal, org.omg.CORBA.TypeCode) is changed to throw an org.omg.CORBA.Bad_INV_ORDER exception. System exception does not need to be declared in user's code. (CCC 4340915)
    • The method TypeCode.equivalent is defined as abstract. BEFORE: threw a NO_IMPLEMENT exception. Compatibility impact: Minimal impact for licensees, not for end user. Licensees need to provide a dummy implementation of this method. (CCC 4340932)
    • The method TypeCode.get_compact_typecode is defined as abstract. BEFORE: threw a NO_IMPLEMENT exception. Compatibility impact: Minimal impact for licensees, not for end user. Licensees need to provide a dummy implementation of this method. (CCC 4340932)
    • The mapping for the get_interface_def(org.omg.CORBA.Object) method in org.omg.CORBA.portable.Delegate.java is defined as abstract. Compatibility impact: Yes, a non-abstract method is converted to abstract. (CCC 4366071)
    • The mapping for the write_Principal() method in org.omg.CORBA.portable.OutputStream.java is no longer abstract. Compatibility impact: No, an abstract method is converted to non-abstract. (CCC 4366072)
    • The mapping for the read_Principal() method in org.omg.CORBA.portable.InputStream.java is no longer abstract. Compatibility impact: None, changing a method that is declared abstract to no longer be abstract does not break compatibility with pre-existing binaries. (CCC 4366074)

  • To conform to the CORBA 2.3 specification, the org.omg.DomainManagerOperations interface no longer extends org.omg.CORBA.Object. Compatibility impact: None, no CORBA program will use the DomainManagerOperations interface directly. The DomainManagerOperations interface can only be used by the programs via the DomainManager interface, which already extends org.omg.CORBA.Object. (CCC 4340907)

  • The following classes are declared as abstract and no longer have a private constructor. (CCC 4372196)

    • org.omg.CORBA.ServiceDetailHelper
    • org.omg.CORBA.ServiceInformationHelper

  • To conform with the IDL to Java spec in section 1.15.2, the default constructor javadoc comments in the following org.omg.CORBA files have been changed from COMPLETED_MAYBE to COMPLETED_NO. Compatibility impact: None. (CCC 4363355)

    • INTERNAL.java
    • INVALID_TRANSACTION.java
    • INV_OBJREF.java

  • The following Helper classes in org.omg.CORBA have been changed from public final to public abstract, and the default constructor for the Helper classes has been deleted. This change has been made to comply with the ORB core specification as defined by CORBA 2.3.1 and with the IDL/Java Language mapping as defined in ptc/00-01-08. Compatibility impact: Minimal since the Helper classes have been made 'abstract' as defined by the OMG IDL/Java Language mapping specification, applications which had previously instantiated a Helper class instance would fail. But the Helper class has only static methods in it, and there is no good reason for an application to create an instance of the Helper class. (CCC 4364208)

    • AnySeqHelper.java
    • BooleanSeqHelper.java
    • CharSeqHelper.java
    • DoubleSeqHelper.java
    • FloatSeqHelper.java
    • LongLongSeqHelper.java
    • LongSeqHelper.java
    • OctetSeqHelper.java
    • ShortSeqHelper.java
    • StringValueHelper.java
    • ULongLongSeqHelper.java
    • ULongSeqHelper.java
    • UShortSeqHelper.java
    • WCharSeqHelper.java
    • WStringValueHelper.java

  • To conform with the recently passed OMG issue 3015, which adds a new class, AbstractInterfaceDef to Interface Repository classes, we have added the following new constants to org.omg.CORBA.DefinitionKind. Compatibility impact: None. (CCC 4367601)

    • _dk_AbstractInterface=24. This is a constant that indicates that an Interface Repository object is representing an abstract object.
    • public static final DefinitionKind dk_AbstractInterface = new DefinitionKind(_dk_AbstractInterface). This is the static instance of DefinitionKind, indicating that an Interface Repository object represents an abstract interface.

  • The following org.omg.CORBA APIs for typecodes were changed to conform to the OMG specification. All of the classes in the following list are in the org.omg.CORBA package. Compatibility impact: Yes. See each change below for details. (CCC 4368800)

    • The Typecode methods fixed_digits, fixed_scale, member_visibility, type_modified, and concrete_base_type are changed from concrete to abstract. Typecode is always implemented by an ORB implementor and never subclassed by an ORB user, so this should not impact customers.
    • TCKind.from_int no longer throws the unchecked exception BAD_PARAM. Since BAD_PARAM is an unchecked exception, removing the exception should not affect customer code at compile time.
    • Principal is changed to a concrete class with methods that throw NO_IMPLEMENT from an abstract class with abstract methods. Principal is deprecated and rarely used. In any case, it would not generally be subclassed by a user and would always be fully implemented by an ORB implementor.
    • An extract_Streamable method is added to Any. Adding a method does not affect compatibility.
    • Any.insert_object( object, Typecode ) is changed to throw BAD_PARAM. Since BAD_PARAM is an unchecked exception, adding the exception should not affect customer code at compile time.
    • The Any methods insert_Streamable, extract_Principal, and insert_Principal are no longer abstract. Any is fully implemented by ORB implementors and never subclassed by ORB users, so this should not impact customers.
    • The Any methods extract_value and insert_value are changed to abstract. Any is fully implemented by ORB implementors and never subclassed by ORB users, so this should not impact customers.

  • The Identifier field is added to org.omg.CORBA.Initializer. Compatibility impact: None. (CCC 4372194)

  • To comply with ptc/00-01-08.pdf, the following classes are changed:

    • org.omg.CORBA.ORBPackage.InvalidName.java is declared as final. Compatibility impact: Yes. The InvalidName is being declared as final, which would impact source code that was subclassing this. Since it is an exception type, we do not anticipate this kind of behavior. (CCC 4366734)
    • org.omg.stub.java.rmi._Remote_Stub.java returns a clone of _type_ids. This will prevent mangling of the original type_ids_ array by external users. (CCC 4366734)
    • The from_int(Int i) method in org.omg.CORBA.SetOverrideType no longer throws a BAD_PARAM exception. Compatibility impact: No. Should not cause a compatibility problem since we are removing a throws declaration of an unchecked exception. (CCC 4369490)
    • The from_int(Int i) method in org.omg.CORBA.DefinitionKind no longer throws a BAD_PARAM exception. Compatibility impact: No. (CCC 4370659)
    • org.omg.CORBA.DynamicImplementation has been deprecated by the OMG in favor of the Portable Object Adapter (POA). A default invoke body is supplied. Compatibility impact: No. Should not impact anyone implementing this class. (CCC 4369490)

  • The following classes are changed to correct errors. Compatibility impact: No (CCC 4362556)
    • Helper and Holder classes are added to UnknownUserException.java. No compatibility impact.
    • Helper and Holder classes are added to WrongTransaction.java, and the class is declared final. No compatibility impact.
    • CompletionStatus.java is declared final, no longer implements IDLEntity, is changed to a private constructor. A BAD_PARAM RuntimeException will no longer explicitly be thrown by from_int. Compatibility impact: Yes. New code written using the new CompletionStatus.java class will not have to explicitly catch the BAD_PARAM runtime exception. If it's recompiled with an older JDK, it would get a compile-time error. -- These changes were undone due to JCK regression (4375061). An OMG issue has been filed instead (http://www.omg.org/issues/java-rtf.html#Issue3946).
    • INV_POLICY.java is declared as final. No compatibility impact.

  • The addition of portable interceptors requires a new method on existing CORBA APIs and four new classes generated from IDL typedefs. Compatibility impact: none, these changes are all additions. (CCC 4379826)

    • register_initial_reference is added in public class org.omg.CORBA.ORB.
    • New class org.omg.CORBA.StringSeqHelper is added for 2 IDL typedefs.
    • New class org.omg.CORBA.StringSeqHolder is added for 2 IDL typedefs.
    • New class org.omg.CORBA.WStringSeqHelper is added for 2 IDL typedefs.
    • New class org.omg.CORBA.WStringSeqHolder is added for 2 IDL typedefs.

API changes to javax.rmi.CORBA

To comply with OMG API specifications, the following changes have been made to javax.rmi.CORBA:

  • The protected constructor in javax.rmi.CORBA.Stub is removed. Compatibility impact: None. (CCC 4366722)
  • To comply with OMG specification 00-01-06.pdf, the jaxax.rmi.CORBA.ClassDesc constructor is removed. (CCC 4366734)

Non-API changes

The following non-API changes were also implemented in JDK 5.0.
  • Correct repository id computations. Compatibility impact: Yes. Added ORB versioning support to allow interoperability with the JDK 1.3 ORB, maintain backwards compatibility, and enable interoperability with other vendor ORBs. (CCC 4365188)

  • To conform with the recently passed OMG issue 3015, we have taken all Interface Repository-related version pragmas out of org.omg.CORBA.ir.idl. This also changes the Repository ID values of a few IR interfaces that we ship in org.omg.CORBA, for example, IDLTypeHelper, from

    private static String _id = "IDL:omg.org/CORBA/IDLType:2.3";
    to
    private static String _id = "IDL:omg.org/CORBA/IDLType:1.0";

    Compatibility impact: Yes. This change might affect interoperability with existing implementations. Restart the application and the IR if you get a COMM_FAILURE exception (or something similar). (CCC 4372718)

  • Added @serial exclude tags to all org.omg.* package files so that JAVADOC will ignore the whole package for the Serialization spec. There is no requirement from Object Management Group (OMG) to have Serialization compatibility between different versions. Practically speaking there are no use cases where the org.omg classes will be serialized in one version and de-serialized in the next version. Compatibility impact: None. (CCC 4394004)

  • Changed idlj compiler arguments in support of POA, which is a new CORBA feature in Merlin. Changes to the idlj tool arguments include:

    • removed undocumented -poa flag
    • enabled generation of standard POA-based skeletons by default
    • added a new flag, -oldImplBase, to allow generation of backward compatible skeletons (compatible with JDK 1.2 and 1.3)

    Compatibility impact: Yes, existing programs that use the compiler may need to add the -oldImplBase flag to their idlj invocation to maintain compatibility. (CCC 4407835)

New API

The following new API were added to JDK 5.0.
  • The PortableInterceptor API is added. An incorrect specification, ptc/2000-04-05, was being referenced in the test plan. Another incorrect specification, orbos/99-12-02 was being referenced in the feature list (ptc/2000-04-05 is the same as orbos/99-12-02 except the format has changed). The correct specification reference for this new API is http://www.omg.org/cgi-gin/doc?ptc/2001-03-04. CCC 4307834 includes the list of changes/additions from ptc/2000-04-05. Compatibility impact: none, this is a new feature so no existing code uses it.

  • The addition of portable interceptors requires a new method, id, in public interface org.omg.PortableServer.POA.

Official Specifications for CORBA support in J2SE 5.0

Specification References

The specifications with which the Java 2 Platform Standard Edition (J2SE) 5.0 ORB complies are as follows. If these links do not take you to the referenced specification, the OMG may have changed the URL, and you can link to www.omg.org to search for the correct specification.
  • CORBA 2.3.1 (formal/99-10-07)
  • IDL to Java language mapping (ptc/00-01-08)
  • Revised IDL to Java language mapping (ptc/00-11-03)
  • Java to IDL language mapping (ptc/00-01-06)
  • Interoperable Naming Service (ptc/00-08-07)
  • Portable Interceptors (ptc/2001-08-31)
These are the only specifications referenced by this document.

Supported Specification Details

Not all of the above specifications are currently implemented in the ORB in J2SE 5.0. The precise list of supported sections is as follows:
  • CORBA 2.3.1 chapters 1-3 and 6-9
  • Revised IDL to Java language mapping, section 1.21.8.2, the orb.properties file.
  • CORBA 2.3.1 chapter 4 with the following replacements from the Portable Interceptors specification:
    • section 4.2.3.5 destroy
    • section 4.5.2 CodeFactory and PICurrent are required
    • Section 4.5.3.4 as updated for register_initial_reference
  • CORBA 2.3.1 chapter 5 with the following update from the Portable Interceptors specification:
    • 5.5.2 StringSeq and WStringSeq are required. This adds the following classes to org.omg.CORBA:
      • StringSeqHolder
      • StringSeqHelper
      • WStringSeqHolder
      • WStringSeqHelper
  • CORBA 2.3.1 sections 10.6.1 and 10.6.2 are supported for repository IDs.
  • CORBA 2.3.1 section 10.7 for TypeCode APIs.
  • CORBA 2.3.1 chapter 11, Portable Object Adapter (POA), with the following updates from the Portable Interceptors specification:
    • Section 11.3.7 POAs must preserve all policies
    • Section 11.3.8.2 again states that POAs must preserve all policies
    • Section 11.3.8.26 POA::id is required.
  • CORBA 2.3.1 chapters 13 and 15 define GIOP 1.0, 1.1, and 1.2. The J2SE 5.0 ORB fully supports all versions of GIOP, with the exception that the bi-directional GIOP feature defined in sections 15.8 and 15.9 is not supported.
  • All of the Interoperable Naming Service is supported.
  • Portable Interceptors section 13.8 (the new Coder/Decoder interfaces) and all of chapter 21 (the interceptor specification).
  • Section 1.21.8 of the Revised IDL to Java Language Mapping Specification (ptc/00-11-03) has been changed from the version in the IDL to Java Language Mapping Specification (ptc/00-01-08).

Tools

  • The IDL to Java compiler (idlj) complies with:
    • CORBA 2.3.1 chapter 3 (IDL definition)
    • CORBA 2.3.1 chapters 5 and 6 (semantics of Value types)
    • CORBA 2.3.1 section 10.6.5 (pragmas)
    • The IDL to Java mapping specification
    • The Revised IDL to Java language mapping specification section 1.12.1 "local interfaces"
  • The Java to IDL compiler (the IIOP backend for rmic) complies with:
    • CORBA 2.3.1 chapters 5 and 6 (value types)
    • The Java to IDL language mapping. Note that this implicitly references section 1.21 of the IDL to Java language mapping
    • IDL generated by the -idl flag complies with CORBA 2.3.1 chapter 3.

Other Compatibility Information

  • The class java.util.Calendar is not interoperable between J2SE 1.3.x and J2SE 5.0 when using RMI-IIOP. OMG issue 3151 may resolve this, but it will probably have to be implemented in a later release of the Java platform.

    The J2SE 5.0 version of Calendar writes a ZoneInfo object in its writeObject method. Similarly, it calls readObject to read this. Based on Java Object Serialization, it expects that if it's talking to an older version, the object won't be there, so the stream will throw an EOFException and keep the stream position intact.

Copyright © 2001-2004 Sun Microsystems, Inc. All Rights Reserved.

Sun

Java Software


Developing Clients

This document was not updated for this J2SETM release.

When updated, topics in this section will include:

  • ORBs and Invocations
  • Static Invocation
  • Dynamic Invocation

ORBs and Invocations

For a client to invoke a CORBA object operation, both the client and the server (the object implementation) must use a CORBA software component called an ORB (object request broker). ORBs are the common denominators that bridge the differences in location, platform, and programming language that can separate a client and a server. ORBs can contact each other across the network, can create and interpret object references (CORBA object handles), and can marshal parameters into and out of the format used by IIOP. In addition to enabling client/server communication, ORBs provide other services, but they are not described here.

The two ways to invoke an operation on a CORBA object are:

  • Static invocation, which is used most often and most resembles conventional Java programming, is type-checked by the compiler. But it can only be used for objects whose interface definitions exist when the invoking client is compiled.

  • Dynamic invocation is more flexible because clients can invoke objects they discover at runtime. However, compile-time type-checking is impossible with dynamic invocation. Although it's possible to type-check parameters at runtime, doing so requires a CORBA Interface Repository, which the current release of Java IDL does not provide.

Static Invocation

To make a static invocation on a CORBA object, a Java client needs an object reference to the servant that performs the operation. The object reference has two important functions:

  • It uniquely identifies the servant, wherever it is located.

  • It implements the client stub interface, making the reference a local proxy for the servant object.

Clients don't create object references but obtain them, typically from other objects such as factories or naming contexts.

OMG IDL is the language in which CORBA object interfaces are defined. For each OMG IDL module, the idlj compiler generates a Java package. For each interface Foo defined in an OMG IDL module, the generated package contains the following items of interest to the client programmer:

  • A Java signature interface Foo, which extends org.omg.portable.IDLEntity, org.omg.CORBA.Object, and the operations interface. The signature interface is used as the signature type in method declarations when interfaces of the specified type are used in other interfaces. From the client's point of view, an object reference for a CORBA Foo object implements this interface.

    Note: The Stub implements the Foo interface, where it generates code for each method to marshall the arguments, invoke the method, and then unmarshall the arguments.

  • A Java operations interface FooOperations, which is used in the server-side mapping and as a mechanism for providing optimized calls for co-located clients and server. The server developer provides implementation for the methods indicated by the operations interface.

    Note: The server writer usually extends FooPOA and provides implementation for the methods provided by the operations interface.

  • A Java class FooHelper, that defines auxiliary methods, notably narrow(), which is the CORBA counterpart of Java casting.

  • A Java class called FooHolder, that holds a public Foo member. Holders are required for CORBA operations that take out or inout arguments, which, unlike CORBA in arguments, don't map directly to Java's pass-by-value semantics.

Dynamic Invocation

CORBA dynamic invocation uses an object called a request to hold everything pertinent to an invocation: the object reference, the name of the operation, its parameters, and space for the result. The client builds a request object describing an operation, then calls the request's invoke method, which dispatches the request just as a stub would. When the invoke method returns, the result is available in the request object.

The key to dynamic invocation is the ability of requests to hold self-describing data. This facility enables a request object to represent any invocation of any operation, regardless of its parameters. Each self-describing data element has a special type known in OMG IDL as Any. An Any consists of a typecode (whose values are defined by OMG IDL) and a value; the typecode specifies the type of the value.

Clients | Servers | Exceptions | Initialization | Naming

Copyright © 1996-2004 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.


Developing Servers

This document was not updated for this release

This topic introduces Java IDL support for servers of both persistent and transient CORBA objects.

Transient and Persistent Objects

A persistent CORBA object lives until it is explicitly destroyed. If a client has a reference to a persistent CORBA object, that reference can be used even if the object's server is not running -- an ORB daemon, ORBD, will start the server when the ORB receives an invocation on the object.

Starting with J2SE 1.4, Java IDL includes a Portable Object Adapter (POA), Object Request Broker Daemon (ORBD), and the servertool. These features enable persistent object servers to be written using Java IDL!

By contrast, a transient CORBA object has the same lifetime as the execution of the server process that creates it. When a server terminates, its transient objects disappear with it and any object references held by the client become invalid. Transient objects are often used to effect asynchronous, or callback communication between applications and objects. For example, suppose a timing service notifies a client application when an interval expires; it could do so as follows:

  • The timing service defines an interface for a notifier object that includes an interval_expired() operation.

  • The timing service requires that a client pass a notifier object to the timing service's set_interval() operation.

  • The timing service client application implements a transient object that implements the notifier interface.

  • The client application creates and passes a notifier object to the timing service.

  • When the interval expires, the timing service invokes the notifier object's interval_expired() operation.

The arrangement, in other words, is much like a callback in procedural programming.

Persistent Object Servers

Starting with J2SE 1.4, Java IDL includes a Portable Object Adapter (POA), Object Request Broker Daemon (ORBD), and the servertool. These features enable persistent object servers to be written using Java IDL! The tutorial Hello World with persistent server provides a version of the "Hello World" application that utilizes a persistent object server.

Transient Object Servers

The Hello World example includes a transient object server.

Clients | Servers | Exceptions | Initialization | Naming

Home
Fundamentals
Programming
References
Tutorial

Copyright © 1996-2004 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.


Distributed Application Concepts

Topics discussed in this section include:

  • Multi-Tiered Applications
  • User-Interface Tier
  • Service (Server) Tier
  • Data Store (Database) Tier

Multi-Tiered Applications

Traditional enterprise applications are, for the most part, self-contained monolithic programs which have limited access to one another's procedures and data. They are usually cumbersome to build and expensive to maintain because even simple changes require the entire program to be recompiled and retested.

By contrast, applications built using distributed objects such as CORBA naturally lend themselves to a multitiered architecture, fostering a neat separation of concerns. A three-tiered application has a user interface code layer, a computation code (or business logic) layer, and a database access layer. All interaction between the layers occurs via the interfaces that all CORBA objects must publish. The diagram below illustrates the transition from monolithic applications to multi-tiered, modular applications.

User-Interface Tier

The user-interface tier is the layer of user interaction. Its focus is on efficient user interface design and accessibility throughout your organization. The user interface tier can reside on the user's desktop, on your organization's intranet, or on the World Wide Web (Internet). Several user interface implementations may be deployed which access the same server. The UI tier usually invokes methods on the business logic tier and thus acts as a client of the business logic servers.

Service (Server) Tier

The service, or business logic layer, is server-based code with which the client code interacts. The business logic layer is made up of business objects - CORBA objects that perform logical business functions such as inventory control, budget, sales orders, and billing. These objects invoke methods on Data Store tier objects.

Data Store (Database) Tier

The data store layer is made up of objects that encapsulate database routines and interact directly with the DBMS product(s). For example, a hypothetical get_Sales_Sum method might be implemented to obtain data from a relational database via the appropriate SQL SELECT statements.

Distributed Application Concepts | CORBA and the Java Platform | Glossary
Home
Copyright © 1996-2004 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.


DSI Programming

Advanced Topic: The Dynamic Skeleton Interface (DSI)

The Dynamic Skeleton Interface (DSI) allows servers to serve a servant object without prior (compile time) knowledge of the object's interface. Insead of using skeleton code compiled from the IDL interface definition, the server constructs an operation invocation dynamically.

Why Use DSI?

DSI can be used to bridge CORBA with non-CORBA environments. Such a bridge would allow CORBA clients to invoke methods on CORBA objects that are implemented as, for example, COM services.

The dynamic servant is implemented to convert the CORBA client request to a format understood by the COM server. You must write all the code to perform this work. Contrast this with a typical static object invocation. The server has access to the compiled skeletons for the interface being invoked. These skeletons are generated by compiling the IDL interface definitions with the idlj compiler. When the ORB receives a request, it uses the skeleton code to build operation arguments on the server side and to send back any result.

Home

Copyright © 2002-2004 Sun Microsystems, Inc. All Rights Reserved.


Example with Callback Object

Java IDL: Example with Callback Object

Client programs often react to changes or updates that occur in a server. For example, a client graph or spreadsheet program might need to be updated with each stock price update on a stock market server. The client has two options in this scenario:

  • Periodically ask for the stock price via a method request on the stock server. This is known as the "polling" or "pull" model.
  • Ask to be notified by the server whenever a price change occurs. This option is referred to as a "callback" or the "push" model.

The example in this document illustrates how a client program can pass a callback object to a server, and the server can then callback to notify changes to the client. At this time, we have provided the code for an extension of a simple application. Notes about simplifying the application are contained within the code.

This document provides the code for:

  • The IDL for an example program with a callback.
  • A server implementation that callsback to a client.
  • A client that sends a callback object reference to a server.
  • An implementation of the Listener.
  • An implementation of the MessageServer.

Instructions for compiling and running the example are also provided.

Callback Example: Intermediate Level

Writing the IDL file

For the example application, the file callback.idl looks like this:

    interface Listener {
    void message(in string msg);
};

interface MessageServer {
    void register(in Listener lt);
};

Writing the Server Code

For the example application, the Server.java file looks like as follows.

    import org.omg.CORBA.ORB;
import org.omg.PortableServer.POA;
import org.omg.PortableServer.POAHelper;
import org.omg.CosNaming.NameComponent;
import org.omg.CosNaming.NamingContext;
import org.omg.CosNaming.NamingContextHelper;

public class Server {

    public static void main(String[] args) {
    try {
            //create and initialize the ORB
            Properties props = System.getProperties();
            props.put("org.omg.CORBA.ORBInitialPort", "1050");
            //Replace MyHost with the name of the host on which you are running the server
            props.put("org.omg.CORBA.ORBInitialHost", "<MyHost>");
            ORB orb = ORB.init(args, props);
        System.out.println("Initialized ORB");

            //Instantiate Servant and create reference
        POA rootPOA = POAHelper.narrow(
        orb.resolve_initial_references("RootPOA"));
        MessageServerImpl msImpl = new MessageServerImpl();
        rootPOA.activate_object(msImpl);
        MessageServer msRef = MessageServerHelper.narrow(
        rootPOA.servant_to_reference(msImpl));

            //Bind reference with NameService
        NamingContext namingContext = NamingContextHelper.narrow(
        orb.resolve_initial_references("NameService"));
            System.out.println("Resolved NameService");
            NameComponent[] nc = { new NameComponent("MessageServer", "") };
        namingContext.rebind(nc, msRef);

        //Activate rootpoa
            rootPOA.the_POAManager().activate();

            //Start readthread and wait for incoming requests
            System.out.println("Server ready and running ....");

            //REMOVE THE NEXT LINE FOR THE SIMPLER EXAMPLE
            msImpl.startReadThread();

            orb.run();

    } catch (Exception e) {
        e.printStackTrace();
    }
    }
}

Writing the MessageServer Implementation

The file registers new clients, accepts messages, then relays the messages to the registered clients. For the example application, the file MessageServerImpl.java looks like the following example.

    import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.util.Vector;
import java.util.Iterator;

public class MessageServerImpl extends MessageServerPOA {

    private Vector clients = new Vector();
    private ReadThread rt = null;

    public MessageServerImpl() {
    rt = new ReadThread(this);
    }

    public void register(Listener lt) {
    clients.add(lt);
    }

    public void startReadThread() {
        rt.start();
    }

    public void message(String msg) {
    Iterator it = clients.iterator();
    while (it.hasNext()) {
        Listener lt = (Listener) it.next();
        lt.message(msg);
        //FOR THE SIMPLER EXAMPLE, ADD A SIMPLE
        //MESSAGE TO BE CALLED BACK, FOR EXAMPLE,
        //SLEEP FOR 30 SECONDS, THEN SEND THE TIME
    }
    }
}

//EXCLUDE THIS CLASS FOR THE SIMPLER EXAMPLE
class ReadThread extends Thread {

    MessageServerImpl msImpl = null;

    public ReadThread(MessageServerImpl msImpl) {
    this.msImpl = msImpl;
    }

    public void run() {
    BufferedReader br = new BufferedReader(
        new InputStreamReader(System.in));

        try {
        for (;;) {
                System.out.print("message > ");
        String msg = br.readLine();
        msImpl.message(msg);
        }
    } catch (Exception e) {
        e.printStackTrace();
    }
    }
}

Writing the Client Code

For the example application, the file Client.java file looks like the following example.

    import java.util.Properties;
import org.omg.CORBA.ORB;
import org.omg.PortableServer.POA;
import org.omg.PortableServer.POAHelper;
import org.omg.CosNaming.NameComponent;
import org.omg.CosNaming.NamingContext;
import org.omg.CosNaming.NamingContextHelper;

public class Client {

    public static void main(String[] args) {
    try {

            //initialize orb
            Properties props = System.getProperties();
            props.put("org.omg.CORBA.ORBInitialPort", "1050");
            //Replace MyHost with the name of the host on which you are running the server
            props.put("org.omg.CORBA.ORBInitialHost", "<MyHost>");
            ORB orb = ORB.init(args, props);
        System.out.println("Initialized ORB");

            //Instantiate Servant and create reference
        POA rootPOA = POAHelper.narrow(
        orb.resolve_initial_references("RootPOA"));
            ListenerImpl listener  = new ListenerImpl();
            rootPOA.activate_object(listener);
        Listener ref = ListenerHelper.narrow(
                rootPOA.servant_to_reference(listener));

            //Resolve MessageServer
        MessageServer msgServer = MessageServerHelper.narrow(
            orb.string_to_object("corbaname:iiop:1.2@localhost:1050#MessageServer"));

            //Register listener reference (callback object) with MessageServer
            msgServer.register(ref);
            System.out.println("Listener registered with MessageServer");

        //Activate rootpoa
            rootPOA.the_POAManager().activate();

            //Wait for messages
            System.out.println("Wait for incoming messages");
            orb.run();

    } catch (Exception e) {
        e.printStackTrace();
    }
    }
}

Writing the Listener Implementation

When the Listener identifies that a message has been received from the server, it displays the message on the client. For the example application, the ListenerImpl.java file looks like the following example.

    public class ListenerImpl extends ListenerPOA {

    public void message(String msg) {
    System.out.println("Message from server : " + msg);
    }
}

Instructions for compiling and running the example

To run the example application, you would follow these instructions on the SERVER machine:

  1. If you've run the example previously, remove any existing generated files. In the Unix operating environment, this command would be as follows:
      rm -rf ./classes ./orb.db

  2. Generate the stubs and skeletons. First, you need to create the directory where the stubs and skeletons will reside, then run the idlj compiler to generate the stubs and skeletons. This command would look like this:
      mkdir -p ./classes
<path_to_java>/bin/idlj -fall -td ./classes callback.idl

  3. Compile the .java files, as follows:
      <path_to_java>/bin/javac -classpath ./classes -d ./classes *.java

  4. Start the orbd naming service, as follows:
      <path_to_java>/bin/orbd -ORBInitialPort 1050 -ORBInitialHost <host_name> &

  5. Run the server, as follows:
      <path_to_java>/bin/java -classpath ./classes Server -ORBInitialPort 1050

After you have started the server, you will see output such as the following in the terminal window:

    Initialized ORB
Resolved NameService
Server ready and running ....
message >

At this prompt, you will send messages to the client, but first you need to start the client application. From the CLIENT terminal, follow these steps to run the client. Make sure that you used the host name on which the server is running in the properties section of the client code.

    <path_to_java>/bin/java -classpath ./classes Client -ORBInitialPort 1050

The output from the client will display in a format similar to this:

    Initialized ORB
Listener registered with MessageServer
Wait for incoming messages

To display the functionality of using a callback, you would enter a data on the server terminal, at the prompt, and it will display on all client terminals. This could be anything where clients are interested in some notifications.

One example is a football game score where clients are notified whenever the score changes.

    message > Niners TD. Niners 7 - Giants 0
message > Giants TD. Niners 7 - Giants 7
message > Niners TD. Niners 14 - Giants 7

When messages such as those shown above are sent, the client display looks similar to the following:

    Wait for incoming messages
Message from server : Niners TD. Niners 7 - Giants 0
Message from server : Giants TD. Niners 7 - Giants 7
Message from server : Niners TD. Niners 14 - Giants 7

Home

Copyright © 2002-2004 Sun Microsystems, Inc. All Rights Reserved.


Exceptions

CORBA has two types of exceptions: standard system exceptions which are fully specified by the OMG and user exceptions which are defined by the individual application programmer. CORBA exceptions are a little different from Java exception objects, but those differences are largely handled in the mapping from IDL to Java.

Topics in this section include:

  • Differences Between CORBA and Java Exceptions
  • System Exceptions
    • System Exception Structure
    • Minor Codes
    • Completion Status
  • User Exceptions
  • Minor Code Meanings

Differences Between CORBA and Java Exceptions

To specify an exception in IDL, the interface designer uses the raises keyword. This is similar to the throws specification in Java. When you use the exception keyword in IDL you create a user-defined exception. The standard system exceptions need not (and cannot) be specified this way.

System Exceptions

CORBA defines a set of standard system exceptions, which are generally raised by the ORB libraries to signal systemic error conditions like:

  • Server-side system exceptions, such as resource exhaustion or activation failure.
  • Communication system exceptions, for example, losing contact with the object, host down, or cannot talk to ORB daemon (orbd).
  • Client-side system exceptions, such as invalid operand type or anything that occurs before a request is sent or after the result comes back.

All IDL operations can throw system exceptions when invoked. The interface designer need not specify anything to enable operations in the interface to throw system exceptions -- the capability is automatic.

This makes sense because no matter how trivial an operation's implementation is, the potential of an operation invocation coming from a client that is in another process, and perhaps (likely) on another machine, means that a whole range of errors is possible.

Therefore, a CORBA client should always catch CORBA system exceptions. Moreover, developers cannot rely on the Java compiler to notify them of a system exception they should catch, because CORBA system exceptions are descendants of java.lang.RuntimeException.

System Exception Structure

All CORBA system exceptions have the same structure:

exception <SystemExceptionName> { // descriptive of error
    unsigned long minor;          // more detail about error
    CompletionStatus completed;   // yes, no, maybe
}

System exceptions are subtypes of java.lang.RuntimeException through org.omg.CORBA.SystemException:

java.lang.Exception
 |
 +--java.lang.RuntimeException
     |
     +--org.omg.CORBA.SystemException
         |
         +--BAD_PARAM
         |
         +--//etc.

Minor Codes

All CORBA system exceptions have a minor code field, a number that provides additional information about the nature of the failure that caused the exception. Minor code meanings are not specified by the OMG; each ORB vendor specifies appropriate minor codes for that implementation. For the meaning of minor codes thrown by the Java ORB, see Minor code meanings .

Completion Status

All CORBA system exceptions have a completion status field, indicating the status of the operation that threw the exception. The completion codes are:

COMPLETED_YES
The object implementation has completed processing prior to the exception being raised.
COMPLETED_NO
The object implementation was not invoked prior to the exception being raised.
COMPLETED_MAYBE
The status of the invocation is unknown.

User Exceptions

CORBA user exceptions are subtypes of java.lang.Exception through org.omg.CORBA.UserException:

java.lang.Exception
 |
 +--org.omg.CORBA.UserException
      |
      +-- Stocks.BadSymbol
      |
      +--//etc.

Each user-defined exception specified in IDL results in a generated Java exception class. These exceptions are entirely defined and implemented by the programmer

Minor Code Meanings

System exceptions all have a field minor that allows CORBA vendors to provide additional information about the cause of the exception. For a list of standard OMG minor code exceptions (OMGVMCID), refer to the OMG document at http://www.omg.org/docs/omg/03-01-04.txt.

Some of the most common Sun minor code exceptions are the following:

  • COMM_FAILURE/201. vmcid: SUN minor code: 201 literally means "CONNECT_FAILURE". This may be caused by a java.net.SocketException, usually one of BindException, ConnectException, or NoRouteToHostException.

    Some things to verify are:

    • Is a naming service running? If not, start the ORBD naming service as described in the document Starting and Stopping ORBD.
    • Are the -ORBInitialHost and -ORBInitialPort values being set correctly for the naming service? If you are uncertain about what the settings should be, read the document Starting and Stopping ORBD.
    • Are the client and server applications aware of the port number (and machine name, if applicable) where the Naming Service is running? Read Starting and Stopping ORBD for more information on how to do this.

  • COMM_FAILURE/208. vmcid: SUN minor code: 208 literally means "CONNECTION ABORT", which generally means the connection has been dropped.

  • COMM_FAILURE/209. vmcid: SUN minor code: 209 literally means "CREATE_LISTENER_FAILED": Unable to create the listener thread on the specific port. Either the post is taken or there was an error creating the daemon thread. This generally indicates that the port on which you are trying to run the naming service is in use by another process. If you are running on Solaris, you could discover whether or not something is running on this port using the following terminal prompt command:

    netstat | grep port_number

  • OBJECT_NOT_EXIST/204. vmcid: SUN minor code: 204 literally means "SERVANT_NOT_FOUND". It is only thrown in one place: corba.INSSubcontract.getINSReference.

  • MARSHAL/217. vmcid: SUN minor code: 217 means that your client tried to send either a wchar or wstring in GIOP 1.0, which is not legal in the spec.

  • MARSHAL/202. vmcid: SUN minor code: 202 means that the code is attempting to marshal an object that derives from org.omg.CORBA.Object, but that particular instance has never been connected to an ORB. When using the POA, you need to register the object with the POA first. If you need more information on how to register an object with the POA, refer to the POA document or the tutorial.

  • BAD_PARAM/201. vmcid: SUN minor code: 201 literally means "NULL_PARAM". This exception often occurs because a Java null was given to a write method such as write_string, write_octet_array, etc. You cannot return a Java null as the result of a Java method.

  • org.omg.CORBA.INTERNAL. vmcid: SUN minor code: 208 means Unable to determine local hostname using InetAddress.getLocalHost().getHostName().

    The ORB uses InetAddress.getLocalHost().getHostName() to create a reference to the name service for looking for and/or binding references. It also uses InetAddress.getLocalHost().getHostName() on the server side to create remote object references (i.e., IORs) that contain the name/port of the server (rather than a dotted-decimal/port pair).

    To avoid the call to getHostName, you can set the following properties (refer to Starting and Stopping ORBD if you are not sure how to do this):

    • Set com.sun.CORBA.ORBServerHost to the DNS name or dotted-decimal address of the server if the ORB is acting as a server.
    • Set com.sun.CORBA.ORBInitialHost to the DNS name or dotted-decimal address of the name server.

    NOTE: These properties are proprietary and are subject to deletion or change.

If none of these suggestions work for you, or if you encounter a different Sun minor code exception, post a message to the developer forum at http://forum.java.sun.com.

When requesting the meaning of a minor code please include the following information:

  • The platform on which the client and server are running (e.g., Solaris, Linux, Win32)
  • The version of Java SE you are using (e.g., 1.5.0_01)
  • A complete stack trace
  • If you are using a naming service or an ORB from a different vendor, please provide the information on the vendor and version of the product.

Home

Copyright © 1996-2004 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.


Getting Started with Java IDL

Getting Started with JavaTM IDL

Java TM IDL is a technology for distributed objects--that is, objects interacting on different platforms across a network. Java IDL enables objects to interact regardless of whether they're written in the Java programming language or another language such as C, C++, COBOL, or others.

This is possible because Java IDL is based on the Common Object Request Brokerage Architecture (CORBA), an industry-standard distributed object model. A key feature of CORBA is IDL, a language-neutral Interface Definition Language. Each language that supports CORBA has its own IDL mapping--and as its name implies, Java IDL supports the mapping for Java. To learn more about the IDL-to-Java language mapping, see IDL-to-Java Language Mapping.

To support interaction between objects in separate programs, Java IDL provides an Object Request Broker, or ORB. The ORB is a class library that enables low-level communication between Java IDL applications and other CORBA-compliant applications.

This tutorial teaches the basic tasks needed to build a CORBA distributed application using Java IDL. You will build the classic "Hello World" program as a distributed application. The Hello World program has a single operation that returns a string to be printed.

Any relationship between distributed objects has two sides: the client and the server. The server provides a remote interface, and the client calls a remote interface. These relationships are common to most distributed object standards, including Java Remote Method Invocation (RMI, RMI-IIOP) and CORBA. Note that in this context, the terms client and server define object-level rather than application-level interaction--any application could be a server for some objects and a client of others. In fact, a single object could be the client of an interface provided by a remote object and at the same time implement an interface to be called remotely by other objects.

This figure shows how a one-method distributed object is shared between a CORBA client and server to implement the classic "Hello World" application.

A one-method distributed object shared between a CORBA client and server.

On the client side, the application includes a reference for the remote object. The object reference has a stub method, which is a stand-in for the method being called remotely. The stub is actually wired into the ORB, so that calling it invokes the ORB's connection capabilities, which forwards the invocation to the server.

On the server side, the ORB uses skeleton code to translate the remote invocation into a method call on the local object. The skeleton translates the call and any parameters to their implementation-specific format and calls the method being invoked. When the method returns, the skeleton code transforms results or errors, and sends them back to the client via the ORBs.

Between the ORBs, communication proceeds by means of a shared protocol, IIOP--the Internet Inter-ORB Protocol. IIOP, which is based on the standard TCP/IP internet protocol, defines how CORBA-compliant ORBs pass information back and forth. Like CORBA and IDL, the IIOP standard is defined by OMG, the Object Management Group.

The Java IDL Development Process and the Hello World Tutorial

This tutorial teaches the basic tasks in building a CORBA distributed application using Java IDL. You will build the classic "Hello World" program as a distributed application. The "Hello World" program has a single operation that returns a string to be printed.

Despite its simple design, the Hello World program lets you learn and experiment with all the tasks required to develop almost any CORBA program that uses static invocation. The following steps provide a general guide to designing and developing a distributed object application with Java IDL. Links to the relevant steps of the tutorial will guide you through creating this sample application.

  1. Define the remote interface

    You define the interface for the remote object using the OMG's Interface Definition Langauge (IDL). You use IDL instead of the Java language because the idlj compiler automatically maps from IDL, generating all Java language stub and skeleton source files, along with the infrastructure code for connecting to the ORB. Also, by using IDL, you make it possible for developers to implement clients and servers in any other CORBA-compliant language.

    Note that if you're implementing a client for an existing CORBA service, or a server for an existing client, you would get the IDL interfaces from the implementer--such as a service provider or vendor. You would then run the idlj compiler over those interfaces and follow these steps.

    Writing the IDL file in this tutorial walks you through defining the remote interface for the simple "Hello World" example.

  2. Compile the remote interface

    When you run the idlj compiler over your interface definition file, it generates the Java version of the interface, as well as the class code files for the stubs and skeletons that enable your applications to hook into the ORB.

    Mapping Hello.idl to Java in this tutorial walks you through these steps for the simple "Hello World" example.

  3. Implement the server

    Once you run the idlj compiler, you can use the skeletons it generates to put together your server application. In addition to implementing the methods of the remote interface, your server code includes a mechanism to start the ORB and wait for invocation from a remote client.

    Developing the Hello World Server walks you through writing a simple server for the "Hello World" application.

  4. Implement the client

    Similarly, you use the stubs generated by the idlj compiler as the basis of your client application. The client code builds on the stubs to start its ORB, look up the server using the name service provided with Java IDL, obtain a reference for the remote object, and call its method.

    Developing a Client Application walks you through writing a simple client application.

  5. Start the applications

    Once you implement a server and a client, you can start the name service, then start the server, then run the client.

    Running the Hello World Application walks you through running the server and client program that together make up the "Hello World" application, and the name service that enables them to find one another.

Using Stringified Object References walks you through making an object reference when there is no naming service.

Running the Hello World Application on Two Machines describes one way of distributing the simple application across two machines - a client and a server.

For More Information

Although concepts are explained as they are introduced in the tutorial, you will find more information in the Concepts section. New terms are linked to their definitions throughout the tutorial.

The Object Management Group no longer maintains this site, but the CORBA for Beginnners page contains links to web pages that provide introductory CORBA information.

Next: Writing the Interface Definition
Java IDL Home
Copyright ©2001-2004 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.


Glossary

Glossary of Java IDL Terms

adapter activator
An adapter activator is an object that the application developer can associate with a POA. The ORB will invoke an operation on an adapter activator when a request is received for a child POA that does not currently exist. The adapter activator can then create the required POA on demand.

attribute (IDL)
An identifiable association between an object and a value. An attribute A is made visible to clients as a pair of operations: get_A and set_A. Readonly attributes only generate a get operation.

Also, that part of an IDL interface that is similar to a public class field or C++ data member. The idlj compiler maps an OMG IDL attribute to accessor and modifier methods in the Java programming language. For example, an interface ball might include the attribute color. The idlj compiler would generate a Java programming language method to get the color, and unless the attribute is readonly, a method to set the color.

client
Any code which invokes an operation on a distributed object. A client might itself be a CORBA object, or it might be a non-object-oriented program, but while invoking a method on a CORBA object, it is said to be acting as client.

client stub
A Java programming language class generated by idlj and used transparently by the client ORB during object invocation. The remote object reference held by the client points to the client stub. This stub is specific to the IDL interface from which it was generated, and it contains the information needed for the client to invoke a method on the CORBA object that was defined in the IDL interface.

client tier
The portion of a distributed application that requests services from the server tier. Typically, the client tier is characterized by a small local footprint, a graphical user interface, and simplified development and maintenance efforts.

Common Object Request Broker Architecture (CORBA)
An OMG-specified architecture that is the basis for the CORBA object model. The CORBA specification includes an interface definition language (IDL), which is a language-independent way of creating contracts between objects for implementation as distributed applications.

The Java 2 Platform Standard Edition (J2SE) provides a CORBA Object Request Broker (ORB) and two CORBA programming models that utilize the Java CORBA ORB and Internet InterORB Protocol (IIOP). The two programming models are the RMI programming model, or RMI-IIOP, and the IDL programming model, or Java IDL. For more information on these programming models, read CORBA Technology and the Java Platform.
See also: client tier, service tier, data store tier

CORBA object
An entity which (1) is defined by an OMG IDL interface, and (2) for which an object reference is available. Object is also the implicit common base type for object references of IDL interfaces.

data store tier
The portion of a distributed application that manages access to persistent data and its storage mechanisms, such as relational databases.

distributed application
A program designed to run on more than one computer, typically with functionality separated into tiers such as client, service, and data store.

distributed environment
A network of one or more computers that use CORBA objects. Objects are installed on the various machines and can communicate with each other.

Dynamic Invocation Interface (DII)
An API that allows a client to make dynamic invocations on remote CORBA objects. It is used when at compile time a client does not have knowledge about an object it wants to invoke. Once an object is discovered, the client program can obtain a definition of it, issue a parameterized call to it, and receive a reply from it, all without having a type-specific client stub for the remote object.

Dynamic Skeleton Interface (DSI)
An API that provides a way to deliver requests from an ORB to an object implementation when the type of the object implementation is not known at compile time. DSI, which is the server side analog to the client side DII, makes it possible for the application programmer to inspect the parameters of an incoming request to determine a target object and method.

exception (IDL)
An IDL construct that represents an exceptional condition that could be returned in response to an invocation. There are two categories of exceptions: (1) system exceptions, which inherit from org.omg.CORBA.SystemException (which is a java.lang.RuntimeException), and (2) user-defined exceptions, which inherit from org.omg.CORBA.UserException (which is a java.lang.Exception).

factory object
A CORBA object that is used to create new CORBA objects. Factory objects are themselves usually created at server installation time.

idlj compiler
A tool that takes an interface written in OMG IDL and produces Java programming language interfaces and classes that represent the mapping from the IDL interface to the Java programming language. The resulting files are .java files. Prior to JDK 1.3, the idlj compiler was known as the idltojava compiler. The idlj compiler supports new CORBA-standard features required for RMI-IIOP. The idlj compiler is placed in the SDK's .bin directory by the installer.

idltojava compiler
A tool that takes an interface written in OMG IDL and produces Java programming language interfaces and classes that represent the mapping from the IDL interface to the Java programming language. The resulting files are .java files. Beginning with JDK 1.3, the IDL-to-Java language mapping is handled by the idlj compiler, which supports new CORBA-standard features required for RMI-IIOP. The idltojava compiler can be downloaded from the Java Developer Connection (JDC) web site.

implementation
A concrete class that defines the behavior for all of the operations and attributes of the IDL interface it supports. A servant object is an instance of an implementation. There may be many implementations of a single interface.

initial naming context
The NamingContext object returned by a call to the method orb.resolve_initial_references("NameService"). It is an object reference to the COS Naming Service registered with the ORB and can be used to create other NamingContext objects.
See also: naming context

Interface Definition Language (IDL)
The OMG-standard language for defining the interfaces for all CORBA objects. An IDL interface declares a set of operations, exceptions, and attributes. Each operation has a signature, which defines its name, parameters, result and exceptions. OMG IDL does not include implementations for operations; rather, as its name indicates, it is simply a language for defining interfaces. The complete syntax and semantics for IDL are available in the OMG specification at the OMG web site.

Interface Repository (IFR)
A service that contains all the registered component interfaces, the methods they support, and the parameters they require. The IFR stores, updates, and manages object interface definitions. Programs may use the IFR APIs to access and update this information. An IFR is not necessary for normal client/server interactions.

Internet InterORB Protocol (IIOP)
The OMG-specified network protocol for communicating between ORBs. Java IDL conforms to CORBA/IIOP specification 2.3.1.

invocation
The process of performing a method call on a CORBA object, which can be done without knowledge of the object's location on the network. Static invocation, which uses a client stub for the invocation and a server skeleton for the service being invoked, is used when the interface of the object is known at compile time. If the interface is not known at compile time, dynamic invocation must be used.

Java IDL
The classes, libraries, and tools that make it possible to use CORBA objects from the Java programming language. The main components of Java IDL are an ORB, a naming service, and the idlj compiler. All are part of this release of J2SE.

name binding
The association of a name with an object reference. Name bindings are stored in a naming context.

namespace
A collection of naming contexts that are grouped together.

naming context
A CORBA object that supports the NamingContext interface and functions as a sort of directory which contains (points to) other naming contexts and/or simple names. Similar to a directory structure, where the last item is a file and preceding items are directories, in a naming context, the last item is an object reference name, and the preceding items are naming contexts.

naming service
A CORBA service that allows CORBA objects to be named by means of binding a name to an object reference. The name binding may be stored in the naming service, and a client may supply the name to obtain the desired object reference. The two options for Naming Services shipped with this version of Java SE are orbd, which is a daemon process containing a Bootstrap Service, a Transient Naming Service, a Persistent Naming Service, and a Server Manager, and tnameserv, a transient naming service.

object
A computational grouping of operations and data into a modular unit. An object is defined by the interface it presents to others, its behavior when operations on its interface are invoked, and its state.

object adapter
The ORB component which provides object reference, activation, and state related services to an object implementation. There may be different adapters provided for different kinds of implementations. The POA is a particular type of object adapter specified by OMG that can be used with multiple ORB implementations with a minimum of rewriting needed to deal with different vendors' implementations.

object id
An object id is a value that is used by the POA and by the user-supplied implementation to identify a particular abstract CORBA object. Object Id values may be assigned and managed by the POA, or they may be assigned and managed by the implementation. Object Id values are hidden from clients, encapsulated by references. Object Ids have no standard form; they are managed by the POA as uninterpreted octet sequences.

object implementation
See implementation.

Object Management Group (OMG)
An international organization with over 700 members that establishes industry guidelines and object management specifications in order to provide a common framework for object-oriented application development. Its members include platform vendors, object-oriented database vendors, software tool developers, corporate developers, and software application vendors. The OMG Common Object Request Broker Architecture specifies the CORBA object model. See www.omg.org for more information.

object reference
A construct containing the information needed to specify an object within an ORB. An object reference is used in method invocations to locate a CORBA object. Object references are the CORBA object equivalent to programming language-specific object pointers. They may be obtained from a factory object or from the Naming Service. An object reference, which is opaque (its internal structure is irrelevant to application developers), identifies the same CORBA object each time it is used. It is possible, however, for multiple object references to refer to the same CORBA object.

Object Request Broker (ORB)
The libraries, processes, and other infrastructure in a distributed environment that enable CORBA objects to communicate with each other. The ORB connects objects requesting services to the objects providing them.

operation (IDL)
The construct in an IDL interface that maps to a Java programming language method. For example, an interface ball might support the operation bounce. Operations may take parameters, return a result, or raise exceptions. IDL operations can be oneway, in which case they cannot return results (return values or out arguments) or raise exceptions.

operations interface
A non abstract IDL interface is mapped to two public Java interfaces: a signature interface and an operations interface. The operations interface has the same name as the IDL interface with the suffix Operations appended to the end and is used in the server-side mapping and as a mechanism for providing optimized calls for collocated clients and servers.

ORBD (Object Request Broker Daemon)
The orbd tool is a daemon process containing a Bootstrap Service, a Transient Naming Service, a Persistent Naming Service, and a Server Manager.

parameter (IDL)
One or more objects the client passes to an IDL operation when it invokes the operation. Parameters may be declared as "in" (passed from client to server), "out" (passed from server to client), or "inout" (passed from client to server and then back from server to client).

persistent object
An object that can survive the process or thread that created it. A persistent object exists until it is explicitly deleted.

PIDL (Pseudo-IDL)
The interface definition language for describing a CORBA pseudo-object. Each language mapping, including the mapping from IDL to the Java programming language, describes how pseudo objects are mapped to language-specific constructs. PIDL mappings may or may not follow the rules that apply to mapping regular CORBA objects.

POA (Portable Object Adapter)
An object adapter is the mechanism that connects a request using an object reference with the proper code to service that request. The POA is a particular type of object adapter specified by OMG that can be used with multiple ORB implementations with a minimum of rewriting needed to deal with different vendors' implementations.

The POA is also intended to allow persistent objects -- at least, from the client's perspective. That is, as far as the client is concerned, these objects are always alive, and maintain data values stored in them, even though physically, the server may have been restarted many times, or the implementation may be provided by many different object implementations.

POA Manager
A POA manager is an object that encapsulates the processing state of one or more POAs. Using operations on a POA manager, the developer can cause requests for the associated POAs to be queued or discarded. The developer can also use the POA manager to deactivate the POAs.

policy
A policy is an object associated with a POA by an application in order to specify a characteristic shared by the objects implemented in that POA. This specification defines policies controlling the POA's threading model as well as a variety of other options related to the management of objects. Other specifications may define other policies that affect how an ORB processes requests on objects implemented in the POA.

Portable Interceptors
Portable Interceptors are hooks into the ORB through which ORB services can intercept the normal flow of execution of the ORB. For more information, see PortableInterceptor Package.

pragma
In J2SE v.1.2, a directive to the idltojava compiler to perform certain operations while compiling an IDL file. For example, the pragma "javaPackage" directs the idltojava compiler to put the Java programming language interfaces and classes it generates from the IDL interface into the Java programming language package specified. In J2SE v.1.3 and higher, this functionality is supported via the -pkgPrefix command line option to idlj.

pseudo-object
An object similar to a CORBA object in that it is described in IDL, but unlike a CORBA object, it cannot be passed around using its object reference, nor can it be narrowed or stringified. Examples of pseudo-objects include the Interface Repository and DII which, although implemented as libraries, are more clearly described in OMG specifications as pseudo-objects with IDL interfaces. The IDL for pseudo-objects is called "PIDL" to indicate that a pseudo-object is being defined.

RMI-IIOP
Java RMI-IIOP is an Object Request Broker and a compiler, rmic -iiop, that generates IIOP stub and tie classes. With RMI-IIOP, developers can write remote interfaces in the Java programming language and implement them simply using Java technology and the Java RMI APIs. These interfaces can be implemented in any other language that is supported by an OMG mapping and a vendor supplied ORB for that language. Similarly, clients can be written in other languages using IDL derived from the remote Java technology-based interfaces. Using RMI-IIOP, objects can be passed both by reference and by value over IIOP.

servant
A servant is a programming language object or entity that implements requests on one or more objects. Servants generally exist within the context of a server process. Requests made on an object's references are mediated by the ORB and transformed into invocations on a particular servant. In the course of an object's lifetime it may be associated with (that is, requests on its references will be targeted at) multiple servants.

servant manager
A servant manager is an object that the application developer can associate with a POA. The ORB will invoke operations on servant managers to activate servants on demand, and to deactivate servants. Servant managers are responsible for managing the association of an object (as characterized by its Object Id value) with a particular servant, and for determining whether an object exists or not. There are two kinds of servant managers, called ServantActivator and ServantLocator; the type used in a particular situation depends on policies in the POA.

servant object
An instance of an object implementation for an IDL interface. The servant object is registered with the ORB so that the ORB knows where to send invocations. It is the servant that performs the services requested when a CORBA object's method is invoked.

server
A program that contains the implementations of one or more IDL interfaces. For example, a desktop publishing server might implement a Document object type, a ParagraphTag object type, and other related object types. The server is required to register each implementation (servant object) with the ORB so that the ORB knows about the servant. Servers are sometimes referred to as object servers.

server skeleton
A public abstract class generated by the idlj compiler that provides the ORB with information it needs in dispatching method invocations to the servant object(s). A server skeleton, like a client stub, is specific to the IDL interface from which it is generated. A server skeleton is the server side analog to a client stub, and these two classes are used by ORBs in static invocation.

servertool
The Java IDL Server Tool, servertool provides the ease-of-use interface for the application programmers to register, unregister, startup, and shutdown a server.

service tier
The portion of a distributed application that contains the business logic and performs most of the computation. The service tier is typically located on a shared machine for optimum resource use.

signature interface
A non-abstract IDL interface is mapped to two public Java interfaces: a signature interface and an operations interface. The signature interface, which extends IDLEntity, has the same name as the IDL interface name and is used as the signature type in method declarations when interfaces of the specified type are used in other interfaces.

skeleton
The object-interface-specific ORB component which assists an object adapter in passing requests to particular methods.

static invocation
See invocation.

stringified object reference
An object reference that has been converted to a string so that it may be stored on disk in a text file (or stored in some other manner). Such strings should be treated as opaque because they are ORB-implementation independent. Standard object_to_string and string_to_object methods on org.omg.CORBA.Object make stringified references available to all CORBA Objects.

stub
A local procedure corresponding to a single operation that invokes that operation when called.

tnameserv
The CORBA COS (Common Object Services) Naming Service provides a tree-like directory for object references much like a filesystem provides a directory structure for files. The Transient Naming Service provided with Java IDL, tnameserv, is a simple implementation of the COS Naming Service specification. Object references are stored in the namespace by name and each object reference-name pair is called a name binding. Name bindings may be organized under naming contexts. Naming contexts are themselves name bindings and serve the same organizational function as a file system subdirectory. All bindings are stored under the initial naming context. The initial naming context is the only persistent binding in the namespace; the rest of the namespace is lost if the transient naming service process halts and restarts.

transient object
An object whose existence is limited by the lifetime of the process or thread that created it.

Distributed Application Concepts | CORBA and the Java Platform | Glossary
Home
Copyright © 1996-2004 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.


Initialization

This document was not updated for this J2SETM release.

Before a Java program can use CORBA objects, it must initialize itself as follows:

  • Create an ORB object.
  • Obtain one or more initial object references, typically at least a naming context.

Home

Copyright © 1996-2004 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.


Interoperable Naming Service (INS) Example

Java IDL: Interoperable Naming Service (INS) Example

The Interoperable Naming Service (INS) is an extension to the CosNaming service. It provides the following additional features:

  • Capability to resolve using stringified names (e.g., Department/Accounting/TravelExpenses)
  • URLs for CORBA object references (corbaloc: and corbaname: formats)
  • Convenient APIs in NamingContextExt for handling CosNames and URLs
  • ORB arguments for bootstrapping (ORBInitRef and ORBDefaultInitRef)

The following diagram shows how INS fits into ORBD:

An object reference contains at least three pieces of information: an address, the name of the POA that created an object reference, and an Object ID.

Using INS, you can provide an URL to access the CORBA object, which is more readable than a stringified Interoperable Object References (IOR). The following stringified object reference formats are allowed:

  • Interoperable Object References (IOR)

    An IOR is an object reference that is understood by ORBs that can interoperate using the OMG-defined protocols General Inter-ORB Protocol (GIOP) and Internet Inter-ORB Protocol (IIOP). A client can obtain an object reference using orb.object_to_string(objRef), as shown in the Browsing the Namespace example, or as a result of an invocation on another object reference.

  • Human-Readable URL Formats for CORBA Object References

    The corbaloc and corbaname formats enable you to provide a URL to access CORBA objects. Use the corbaloc format for resolving to a particular CORBAservice without going through a naming service. Use the corbaname format to resolve a stringified name from a specific naming context.

    • corbaloc:

      The corbaloc: format is used to locate CORBA services, is useful for CORBA client programs, and is typically used to resolve the reference using the GIOP LocateRequest or Request message. For example, a corbaloc: object reference might look like this:

           corbaloc:iiop:1.2@MyBank.com:2050/TraderService

      This example show how to get an object reference for TraderService from host myBank.com on port 2050.

      NOTE: The 1.2 in the example URL refers to GIOP version 1.2 for the IOR that corresponds to that corbaloc URL. GIOP 1.2 is the default value for Sun's Java CORBA ORB. It is shown in this example in order to demonstrate how you can plug in a different version.

    • corbaname:

      The corbaname: format provides a mechanism for a client to bootstrap directly, and is typically used to resolve the stringified name from the root naming context. For example, a corbaname: object reference might look like this:

           corbaname::myBank.com:2050#Personal/schedule

      where myBank.com is the host, 2050 is the port. The portion of the reference up to the hash mark (corbaname::myBank.com:2050 ) is the URL that returns the root naming context. This example provides the URL to use to: a) locate the Naming Service, and, b) resolve the name Personal/schedule from the Naming Service.

NamingContextExt API

The NamingContextExt interface, derived from NamingContext provides the operations required to use URLs and stringified names. Some of the APIs in NamingContextExt for converting between CosNames, Stringified Names, and URLs are listed below. See the COS Naming Specification, Section 3.6.4, for more information on these API.

  • to_string

    This operation accepts a Name and returns a stringified name. If the Name is invalid, an InvalidName exception is raised.

  • to_name

    This operation accepts a stringified name and returns a Name. If the stringified name is syntactically malformed or violates an implementation limit, an InvalidName exception is raised.

  • resolve_str

    This is a convenience operation that performs a resolve in the same manner as NamingContext.resolve(). It accepts a stringified name as an argument instead of a Name.

  • to_url

    This operation takes a corbaloc URL <address> and <key_string> component such as

    • :myhost.555xyz.com
    • :myhost.555xyz.com/a/b/c
    • atm:00002112...,:myhost.xyz.com/a/b/c

    for the first parameter, and a stringified name for the second. It then performs any escapes necessary on the parameters and returns a fully formed URL string. An exception is raised if either the corbaloc address and key parameter or name parameter are malformed.

    It is legal for the stringified_name to be empty. If the address is empty, an InvalidAddress exception is raised.

Conversions from URLs to objects are handled by org.omg.CORBA.ORB.string_to_object() as described in the CORBA 2.3 Specification, Section 13.6.6.

The following Java IDL tutorials use NamingContextExt:

  • Java IDL: The "Hello World" Example (using the POA and a transient server)
  • Java IDL: The "Hello World" Example (using the POA, a persistent server, and a persistent naming service)
  • Java IDL: The "Hello World" Example (using the POA-Tie server-side model)

Bootstrap Options for the ORB

The ORB can be configured to return the handle of a customized CORBA service from resolve_initial_references() using either ORBInitRef and/or ORBDefaultInitRef. For example,

  • Use -ORBInitRef to resolve to specific CORBA services, for example,

    -ORBInitRef TraderService=corbaloc::myBank.com:2050/TraderService

  • If no -ORBInitRef is given, -ORBDefaultInitRef is used to resolve. In the TraderService example,

    -ORBDefaultInitRef corbaloc:iiop:1.2:myBank.com:2050

The order of resolution when these options are used is as follows:

  1. Objects registered with register_initial_references
  2. -ORBInitRef
  3. -ORBDefaultInitRef
  4. Proprietary Bootstrap (Sun ORBs only)

For more information about INS, refer to the OMG specification at (ptc/00-08-07).

INS Example: Publishing a Reference to be Accessed by INS URL's

This document is a high-level overview of how to create a complete CORBA (Common Object Request Broker Architecture) application using the Interoperable Naming Service (INS).

This example makes use of the following files:

  • The IDL for a simple interface for this example
  • A server that creates an object and publishes it to be used by INS URL's
  • The implementation of the Service interface
  • An application client that retrieves a reference from the server using corbaloc: URL
  • Instructions for compiling and running the example

step Each step in the tutorial is indicated by this symbol.

Defining the Interface (Service.idl)

The first step to creating a CORBA application is to specify all of your objects and their interfaces using the OMG's Interface Definition Language (IDL).

The following code is written in the OMG IDL, and describes a CORBA object whose ping() operation pings the INS Service.

step Create the file Service.idl and add the following code:

Service.idl

// A very simple interface to explain this example
interface Service {
    void ping();
};

Implementing the Server (INSServer.java)

The INSServer class has the server's main() method, which:

  • Sets the ORBPeristentServerPort property in order to open up a port to listen for INS requests (Sun proprietary property)
  • Creates and initializes an ORB instance
  • Gets a reference to the root POA and activates its POAManager
  • Creates a servant (the implementation of one CORBA ServiceImpl object)
  • Registers the new object in the naming context under the name "PingService"
  • Waits for invocations of the new object from the client

step Create the file INSServer.java and add the following code:

INSServer.java

// INSServer.java
// Copyright and License
import java.util.Properties;
import org.omg.CORBA.Object;
import org.omg.CORBA.ORB;
import org.omg.CORBA.Policy;
import org.omg.PortableServer.POA;
import org.omg.PortableServer.*;
import org.omg.PortableServer.Servant;

public class INSServer {
    public static void main( String args[] ) {
        try {
            Properties properties = System.getProperties( );
            // STEP 1: Set ORBPeristentServerPort property
            // Set the proprietary property to open up a port to listen to
            // INS requests.
            // Note: This property is subject to change in future releases
            properties.put( "com.sun.CORBA.POA.ORBPersistentServerPort",
                Integer.toString(1060) );

            // STEP 2: Instantiate the ORB, By passing in the
            // ORBPersistentServerPort property set in the previous step
            ORB orb = ORB.init( args, properties );

            // STEP 3: Instantiate the Service Object that needs to be published
            // and associate it with RootPOA.
            ServiceImpl servant = new ServiceImpl( );
            POA rootPOA = POAHelper.narrow( orb.resolve_initial_references( "RootPOA" ));
            rootPOA.the_POAManager().activate();
            rootPOA.activate_object( servant );

            // STEP 4: Publish the INS Service using
            // orb.register_initial_reference( <ObjectKey>, <ObjectReference>
            // NOTE: Sun private internal API, not part of CORBA 2.3.1.
            // May move as our compliance with OMG standards evolves.
            ((com.sun.corba.se.internal.Interceptors.PIORB) orb).
                register_initial_reference(
                "PingService", rootPOA.servant_to_reference(servant) );

            System.out.println( "INS Server is Ready..." );

            // STEP 5: We are ready to receive requests
            orb.run( );
        } catch ( Exception e ) {
             System.err.println( "Error in setup : " + e );
        }
    }
}

Implementing the Service (ServiceImpl.java)

The example implementation, ServiceImpl, is the implementation of the Service IDL interface.

step Create the file ServiceImpl.java and add the following code:

ServiceImpl.java

// ServiceImpl.java
// Copyright and License

// Implementation of Service interface
public class ServiceImpl extends ServicePOA {
    public void ping( ) {
        System.out.println( "PingService.ping called..." );
    }
}

Implementing the Client Application (INSClient.java)

The example application client that follows:

  • Creates and initializes an ORB
  • Retrieves PingService object reference using resolve_initial_references()
  • Invokes the PingService's ping() operation and prints the result

step Create the file INSClient.java and add the following code:

INSClient.java

// INSClient.java
// Copyright and License

import org.omg.CORBA.ORB;

public class INSClient {
    public static void main( String args[] ) {
        try {
            // STEP 1: Instantiate the ORB
            ORB orb = ORB.init( args, null );

            // STEP 2: Resolve PingService using orb.resolve_initial_references()
            // In this example we have used -ORBInitRef argument to locate the
            // PingService. User can also choose to pass the corbaloc: url to
            // orb.string_to_object to resolve the published PingService
            // reference.
            org.omg.CORBA.Object object = orb.resolve_initial_references(
                "PingService" );

            // STEP 3: Narrow the reference and we are ready to invoke method
            // on PingService.
            Service insService = ServiceHelper.narrow( object );

            insService.ping( );
            System.out.println( "The server has been pinged" );

        } catch ( Exception e ) {
            System.err.println( "Exception in INSClient " + e );
            e.printStackTrace( );
        }
    }
}

Building and Running the INS Example

When running this example, we recommend that you use a port number greater than or equal to 1024. This is because you must become root to start a process on a port under 1024 when using Solaris software. The ORBPersistentServerPort property of the server has been set to 1060 in this example.

Compile the Interface Definition

step Change to the directory that contains the file Service.idl, and run the IDL-to-Java compiler as shown below:

  idlj -fall  Service.idl

You must use the -fall option with the idlj compiler to generate both client and server-side bindings. For more information on the idlj options, link to IDL-to-Java compiler options.

The files generated by the idlj compiler for Service.idl, with the -fall command line option, are:

  • ServicePOA.java - the server skeleton

  • _ServiceStub.java - client stub

  • Service.java - the Java version of our IDL interface

  • ServiceHelper.java - auxiliary functionality, notably the narrow() method

  • ServiceHolder.java - holds a public instance member of type INS

  • ServiceOperations.java - contains the method ping()

Compile the Java files

step Compile the .java files, including the stubs and skeletons, as follows:

   javac *.java

Start the INS Server

step Start the INS server:

  java -classpath . INSServer

If the INS Server is running correctly, the following message will display:

INS Server is Ready...

Start the Client Application

step Open another terminal window or DOS shell and run the client application:

  java -classpath . INSClient -ORBInitRef
    PingService=corbaloc:iiop:1.2@localhost:1060/PingService

When the client is run with the -ORBInitRef option, it will be able to locate PingService. The following message displays in the client window:

The server has been pinged

And the following message displays in the server window:

PingService.ping called...

When you have finished this tutorial, be sure to shut down or kill the INS server. To do this from a DOS prompt, select the window that is running the server and enter Ctrl+C to shut it down. To do this from a Unix shell, open the shell that was running the client and type pkill INSServer.

Home

Copyright © 1995-2004 Sun Microsystems, Inc. All Rights Reserved.


Java IDL Examples License

JavaTM IDL Examples License

/*

 * Copyright (c) 1996-2004 Sun Microsystems, Inc. All Rights Reserved.

 *

 * Sun grants you ("Licensee") a non-exclusive, royalty free, license to use,

 * modify and redistribute this software in source and binary code form,

 * provided that i) this copyright notice and license appear on all copies of

 * the software; and ii) Licensee does not utilize the software in a manner

 * which is disparaging to Sun.

 *

 * This software is provided "AS IS," without a warranty of any kind. ALL

 * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY

 * IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR

 * NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN AND ITS LICENSORS SHALL NOT BE

 * LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING

 * OR DISTRIBUTING THE SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS

 * LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT,

 * INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER

 * CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF

 * OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE

 * POSSIBILITY OF SUCH DAMAGES.

 *

 * This software is not designed or intended for use in on-line control of

 * aircraft, air traffic, aircraft navigation or aircraft communications; or in

 * the design, construction, operation or maintenance of any nuclear

 * facility. Licensee represents and warrants that it will not use or

 * redistribute the Software for such purposes.

 */

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.


Java IDL Technology

Java

JavaTM IDL

Documentation Contents

OMG

JavaTM IDL technology ("Java IDL") adds CORBA (Common Object Request Broker Architecture) capability to the Java platform, providing standards-based interoperability and connectivity. Java IDL enables distributed Web-enabled Java applications to transparently invoke operations on remote network services using the industry standard IDL (Object Management Group Interface Definition Language) and IIOP (Internet Inter-ORB Protocol) defined by the Object Management Group. Runtime components include a Java ORB for distributed computing using IIOP communication.

Overview

  • CORBA and the Java Programming Language
  • Java Developer Connection: Introduction to CORBA
  • Distributed Application Concepts
  • Glossary
  • POA - Portable Object Adapter
  • Portable Interceptors **Advanced Topic**
  • INS - Interoperable Naming Service

API Specification

  • package org.omg.CORBA - provides the mapping of the OMG CORBA APIs to the Java[tm] programming language
  • package org.omg.CosNaming - provides the naming service for Java IDL
  • package org.omg.PortableServer - provides classes and interfaces for making the server side of your applications portable across multivendor ORBs
  • package org.omg.PortableInterceptor - provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB
  • package org.omg.DynamicAny - provides classes and interfaces to enable Any values to be dynamically interpreted (traversed) and constructed through DynAny objects
  • org.omg.CORBA.ORB - provides APIs for the CORBA Object Request Broker features

Tutorials and Programmer's Guides

Most of the tutorials are variations on the basic distributed "Hello World" application.

Introductory-Level Tutorials

The following documents provide introductory-level information on creating applications that use Java IDL. All use the POA-server side model. The differences are in the server implementations.

In order to best understand the material, progress through the examples in the order presented here.

  • Introductory "Hello World" example using Java IDL technology
  • "Hello World" example with a transient server (same code as above example, less descriptive material)
  • "Hello World" example with a persistent server
Other server-side models may be created using J2SE. If you'd like to use other server- side models, refer to these tutorials. Both of these tutorials use a transient server implementation.

  • "Hello World" example with a POA-Tie (Delegation) server-side model
  • "Hello World" example with an ImplBase (Inheritance) server-side model

Intermediate-Level Tutorials

The tutorials listed in this section are for developers who understand the material in the introductory-level tutorials, and are looking for more complex material.

  • Using the Interoperable Naming Service
  • CORBA Programming with J2SE: Programming Transient and Persistent Servers

Advanced-Level Tutorials

These tutorials are for experienced developers. The descriptive material is reduced, the sample code is commented for better understanding of the material.

  • Portable Interceptors
  • Using Servant Activators
  • Using Servant Locators
  • Using Adapter Activators

Programming Guides

  • Exceptions
  • Initialization
  • Naming Service
  • Dynamic Skeleton Interface
  • Mapping IDL to the Java Programming Language

Additional Sample Applications

  • Sample Code for Hello World provides the code for all created and generated files used in the POA server-side model tutorial
  • Example: Interoperable Naming Service
  • Example: Callback Objects

API Enhancements

  • Changes in CORBA (JavaTM IDL, Java RMI-IIOP) Features Between J2SE 1.4.x and 5.0

Tools

  • idlj - the IDL-to-Java compiler (command-line documentation)
  • orbd - a daemon process containing a Bootstrap Service, a Transient Naming Service, a Persistent Naming Service, and a Server Manager
  • servertool - the ease-of-use interface for application programmers to register, unregister, startup, and shutdown a server.
  • tnameserv - the Transient Java IDL Naming Service (provided for backward compatibility)

More Information

The CORBA Home Page

The OMG is the official source of information for all CORBA and IIOP related information. The CORBA 2.3.1 Specification is available electronically from formal/99-10-07.pdf. The URLs for the CORBA specifications may change. If this link is broken, link to http://www.omg.org and search the specifications.

For more information on which OMG specifications are implemented in this release of the Java platform, see the compliance document.

For information on product limitations in this release of the Java IDL/RMI-IIOP technologies, see Java IDL Product Limitations.

For questions, please check the Java IDL FAQ and the user supported forum for Java IDL technology, which is available at http://forums.java.sun.com.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved. Sun


Java(TM) IDL FAQ

Java

JavaTM IDL FAQ

This is a document that attempts to answer many of the questions you may have about using JavaTM IDL technology. We will continue to update this document with your questions as we receive them. If you do not find your question answered here, please check the user-supported forum for Java IDL technology, which is available at http://forums.java.sun.com.

Errors

  • Why do I get this message when I try to run HelloServer: Exception in thread "main" java.lang.NoClassDefFoundError: HelloServer/java
  • My existing programs aren't running using this release. Are there any compatibility issues that could affect this?
  • Why can't I connect using IOR's from a Linux server when the IOR contains 127.0.0.0 as the host address?
  • What does this minor code mean?
  • Can I add multiple classpaths when starting a server using servertool?
  • What do I do when the naming service (tnameserv, orbd) fails to run on the Linux platform??

Features

  • What is the thread model supported by the CORBA implementation in this release?
  • Does Java IDL contain notification/event services? an Interface Repository?
  • How can I run the Hello World example on two machines?
  • Is Java IDL compliant with OMG CORBA specifications?

Compatibility/Interoperability

  • With which CORBA specifications does J2SE 5.0 comply?
  • How can I specify a different ORB?
  • How can I test whether my JDK ORB Client can communicate with another vendor's ORB implementation?
  • Do you have any examples that use a CORBA client and a Java server application?
  • How do I connect to a 3rd-party Naming Service from Sun's ORB?
  • Can I use the Java IDL ORB with a C++ CORBA server? (interoperability)

General

  • Should I use Java IDL or Java RMI-IIOP technology?
  • Where can I download the idltojava compiler?
  • What are my options for developing CORBA applications using Java technology?
  • What is the difference between Java IDL and Java RMI-IIOP?
  • What are the limitations of Java IDL and Java RMI-IIOP in this release?
  • What are the standard tags for ...?

Errors

Why do I get this message when I try to run HelloServer: "Exception in thread "main" java.lang.NoClassDefFoundError: HelloServer/java"
The most common reason for this error when running HelloServer (and also HelloClient) from the Java IDL tutorial is that HelloServer is not in the classpath. For more information on setting the classpath variable, see Setting the classpath.

The second most common reason occurs when a space is added between quotation marks in the following line of code:

NameComponent nc = new NameComponent("Hello", "");

There should be no spaces between the quotation marks. Without spaces, this value is passed as a null. With a space between the quotations, a space character is passed.

My existing programs aren't running using this release. Are there any compatibility issues that could affect this?

Information on compatibility between J2SE 1.4.x and J2SE 5.0 can be found in the compatibility document.

Why can't I connect using IOR's from a Linux server when the IOR contains 127.0.0.0 as the host address?

On Red Hat Linux installations InetAddress.getLocalHost() may return an InetAddress corresponding to the loopback address (127.0.0.1). This arises because the default installation creates an association in /etc/hosts between the hostname of the machine and the loopback address. To ensure that InetAddress.getLocalHost() returns the actual host address, update the /etc/hosts file or the name service configuration file (/etc/nsswitch.conf) to query dns or nis before searching hosts.

What does this minor code mean?

The most recent versions of the standard (OMG) minor code exceptions can be found on the OMG Web site at http://www.omg.org/.

Some of the most common Sun minor code exceptions are the following:

  • COMM_FAILURE/201. vmcid: SUN minor code: 201 literally means "CONNECT_FAILURE". This may be caused by a java.net.SocketException, usually one of BindException, ConnectException, or NoRouteToHostException.

    Some things to verify are:

    • Is a naming service running? If not, start the ORBD naming service as described in the document Starting and Stopping ORBD.
    • Are the -ORBInitialHost and -ORBInitialPort values being set correctly for the naming service? If you are uncertain about what the settings should be, read the document Starting and Stopping ORBD.
    • Are the client and server applications aware of the port number (and machine name, if applicable) where the Naming Service is running? Read Starting and Stopping ORBD for more information on how to do this.

  • COMM_FAILURE/208. vmcid: SUN minor code: 208 literally means "CONNECTION ABORT", which generally means the connection has been dropped.

  • COMM_FAILURE/209. vmcid: SUN minor code: 209 literally means "CREATE_LISTENER_FAILED": Unable to create the listener thread on the specific port. Either the post is taken or there was an error creating the daemon thread. This generally indicates that the port on which you are trying to run the naming service is in use by another process. If you are running on Solaris, you could discover whether or not something is running on this port using the following terminal prompt command:

    netstat | grep port_number

  • OBJECT_NOT_EXIST/204. vmcid: SUN minor code: 204 literally means "SERVANT_NOT_FOUND". It is only thrown in one place: corba.INSSubcontract.getINSReference.

  • MARSHAL/217. vmcid: SUN minor code: 217 means that your client tried to send either a wchar or wstring in GIOP 1.0, which is not legal in the spec.

  • MARSHAL/202. vmcid: SUN minor code: 202 means that the code is attempting to marshal an object that derives from org.omg.CORBA.Object, but that particular instance has never been connected to an ORB. When using the POA, you need to register the object with the POA first. If you need more information on how to register an object with the POA, refer to the POA document or the tutorial.

  • BAD_PARAM/201. vmcid: SUN minor code: 201 literally means "NULL_PARAM". This exception often occurs because a Java null was given to a write method such as write_string, write_octet_array, etc. You cannot return a Java null as the result of a Java method.

  • org.omg.CORBA.INTERNAL. vmcid: SUN minor code: 208 means Unable to determine local hostname using InetAddress.getLocalHost().getHostName().

    The ORB uses InetAddress.getLocalHost().getHostName() to create a reference to the name service for looking for and/or binding references. It also uses InetAddress.getLocalHost().getHostName() on the server side to create remote object references (i.e., IORs) that contain the name/port of the server (rather than a dotted-decimal/port pair).

    To avoid the call to getHostName, you can set the following properties (refer to Starting and Stopping ORBD if you are not sure how to do this):

    • Set com.sun.CORBA.ORBServerHost to the DNS name or dotted-decimal address of the server if the ORB is acting as a server.
    • Set com.sun.CORBA.ORBInitialHost to the DNS name or dotted-decimal address of the name server.

    NOTE: These properties are proprietary and are subject to deletion or change.

If none of these suggestions work for you, or if you encounter a different Sun minor code exception, try to Java IDL user-supported forum at http://forums.java.sun.com. When submitting a request to the forum, please include the following information:

  • The platform on which the client and server are running (e.g., Solaris, Linux, Win32)
  • The version ofJava SE you are using (e.g., 1.5.0_01)
  • A complete stack trace
  • If you are using a naming service or an ORB from another vendor, please provide that information

Can I add multiple classpaths when starting a server using servertool?

The longer version of this question was as follows:

My server code needs multiple JAR files in the classpath. When I register my server using the servertool, and try to specify the classpath, I get the syntax of the register command. I assume my command line is exceeding the limit.

How do I specify a really long classpath while registering the server in the servertool?

The servertool does accept multiple JAR files, however, there is currently a bug with the length of the command line buffer in servertool. Read more about the servertool wrapper bug (bug 4482166) at http://developer.java.sun.com/developer/bugParade/bugs/4482166.html.

The workaround is to call the ServerTool class to start the server, rather than starting the server from within servertool, such as:

${JAVA_HOME}/bin/java com.sun.corba.se.internal.Activation.ServerTool
-ORBInitialPort ${ORB_INITIAL_PORT} -cmd register -server
sample.MyServer -classpath jar1:jar2:jar3 -applicationName sample

Please note that the name of the servertool class may change in future releases.

What do I do when the naming service (tnameserv, orbd) fails to run on the Linux platform?

If the naming service fails to startup on Linux, include the following lines in the /etc/hosts file:

    <Local Host IP Address>   localhost
<Local Host IP Address>   <HostName>

where <Local Host IP Address> is the IP address where the naming service (tnameserv, orbd) is started.

Features

What is the thread model supported by the CORBA implementation in this release?

The Java CORBA ORB shipped in Java SE is multi-threaded. On the server side, we have a thread pool such that each incoming request is handled by a separate thread. If all the pool's threads are in use when a new request comes in, a new thread is created and added to the pool. The thread is returned to the pool after the request is finished.
The Java CORBA ORB is threaded to allow scalability and concurrent request processing. The SINGLE_THREAD option for the POA threading policy is not supported.
The threading model for the Java CORBA ORB is implicit: the user does not set the thread policy for the ORB. There are no external, user-level APIs exposed for controlling the threading model or the number of threads.

Does Java IDL contain notification/event services? an Interface Repository?

No, it does not. If you need one of these services, you can implement one, you can purchase one off the shelf, or you can search for one freely available to start things off with. You can plug-in 3rd party services such as these to the ORB using INS technology.

How can I run the Hello World example on two machines?

You need to use the -ORBInitialHost <Host Name where Name Service is Launched> option when starting the client and/or server (whichever is not running on the same machine as the name server). This way the client and server know where to find the Name Service. An example can be found at http://java.sun.com/j2se/1.5.0/docs/technotes/guides/idl/tutorial/jidl2machines.html.

Is Java IDL technology compliant with CORBA specifications?

For compliance information for CORBA technology shipped with J2SE 5.0, read the CORBA compliance statement at http://java.sun.com/j2se/1.5.0/docs/technotes/guides/idl/compliance.html.

Compatibility/Interoperability

With which CORBA specifications does J2SE 5.0 comply?

See Official Specifications for CORBA support in J2SE 5.0.

How can I specify a different ORB?

To use an ORB other than the Java CORBA ORB in your application, you can set the org.omg.CORBA.ORBClass property to the ORB of your choice. For example, use code as shown in the example to explicitly set the ORB to the ORB-implementation you would prefer to use:

public class MyApp {

    public static void main( String args[] ) {
        Properties properties = System.getProperties();
        properties.put( "org.omg.CORBA.ORBClass",
            "<com.other_company.package.ORB>" );

        try {
             ORB orb = ORB.init( args, properties);

             ...

Check the vendor's documentation for information on setting properties specific to their ORB implementation.

How can I test whether my JDK ORB Client can communicate with another company's ORB implementation?

This ORB has been tested as part of the J2EE certification process, however, it has not been tested with all vendor's standalone CORBA ORBs.

If INS is supported in the other vendor's service, then, try this. Convert the Interoperable Object References (see IOR discussion in INS tutorial) on the other vendor's ORB server to a string using the ORB.object_to_string() method using INS. Write that string to a file.

Do you have any examples that use a CORBA client and an EJB server application?

A developer guide that includes an example application with a C++ client and an Enterprise JavaBeans component can be found on the Web site at: http://java.sun.com/j2se/1.5.0/docs/technotes/guides/rmi-iiop/interop.html.

How do I connect to a 3rd-party Naming Service from Sun's ORB?

The recommended way is to use the Interoperable Naming Service (INS), if this option is supported by the 3rd-party Naming Service.

To use the Sun ORB with another vendor's Naming Service,

  1. Start the 3rd-party name server on Host and Port.

  2. Pass the following argument to ORB.init():
            -ORBInitRef NameService=corbaloc:iiop:1.2@:/NameService

When you do orb.resolve_initial_references( "NameService" ), you should be able to connect to 3rd-party Name Service. If you are still not able to connect, try these troubleshooting hints:

  • Verify that the 3rd-party Name Service supports INS.
  • Verify that the host and port information is accurate.
  • Verify that the 3rd-party Name Service has been started successfully.
  • Verify that the 3rd-party Name Service supports GIOP 1.2. If not, refer to the Name Server's documentation for the correct the GIOP version, and modify the corbaloc: URL accordingly.
  • Determine if the 3rd-party Name Service has a different object key it uses to contact NameService. If so, refer to the Name Server's documentation.

Can I use the Java IDL ORB with a C++ CORBA server? (interoperability)

The Java IDL ORB is an ORB completely written using Java technology. The idlj compiler generates code that follows the conventions defined in the IDL to Java Language Mapping Specification. The Java ORB does not provide a compiler that generates code in any languages other than the Java platform. If you want to test interoperability between the Java ORB and an ORB written in another language (such as C++), you will need to find an ORB written in that language and a compiler that conforms to the specific language mapping. Language mapping specifications are available from the Object Management Group Web site at http://www.omg.org/. A user who wants to use the Java platform on one side and C++ on the other will only share the IDL. You will have to use your C++ ORB's tools to generate the stubs and skeletons for use with the C++ ORB, but you don't have to change the IDL at all. To find a vendor that provides a CORBA ORB and a language mapping compiler in the language you are working with, search the Web for "C++ CORBA ORB", or equivalent.

A developer guide that includes an example application with a C++ client and an Enterprise JavaBeans component can be found on the Web site at: http://java.sun.com/j2se/1.5.0/docs/technotes/guides/rmi-iiop/interop.html.

Although it is true that ORBs written in different languages should be able to talk to each other, we haven't tested the interoperability of the Java ORB with other vendor's ORBs.

General

Should I use Java IDL or Java RMI-IIOP technology?

This is a fundamental question and it's important to understand the distinction between these two ways of integrating the Java programming language with CORBA.

Java IDL technology is for CORBA programmers who want to program in the Java programming language based on interfaces defined in CORBA Interface Definition Language (IDL). This is "business as usual" CORBA programming, supporting Java in exactly the same way as other languages like C++ or COBOL.

Java Remote Method Invocation over Internet Inter-ORB Protocol ("RMI-IIOP") technology is for Java programmers who want to program to the Java Remote Method Invocation ("Java RMI") interfaces, but use IIOP as the underlying transport. RMI-IIOP provides interoperability with other CORBA objects implemented in various languages - but only if all the remote interfaces are originally defined as Java RMI interfaces. It is of particular interest to programmers using Enterprise JavaBeansTM (EJBTM) technology, since the EJB remote object model is based on Java RMI technology.

Where can I download the idltojava compiler?

The idltojava compiler is no longer available for download. We highly recommend that you use the latest version of the IDL-to-Java compiler, idlj.

To get the latest version of the IDL-to-Java compiler, download the latest version of JavaTM 2 Platform, Standard Edition (J2SETM). When Java SE is installed, idlj will be located in the bin directory.

Other troubleshooting information related to idltojava is located in the Java IDL FAQ for J2SE v.1.3.

What are my options for developing CORBA applications using Java technology?

CORBA technology as part of the Java 2 platform consists of an Object Request Broker (ORB) written in the Java language (with a small bit of native code), the RMI programming model, and the IDL programming model.
The "magic" that gives us the cross-language, cross-vendor interoperability is the Internet InterORB Protocol, or IIOP. IIOP can be a transport protocol for distributed applications written in either IDL or Java RMI. IIOP allows distributed objects to conform to OMG's CORBA specification.
When using the IDL programming model, the interface is everything! It defines the points of entry that can be called from a remote process, such as the types of arguments the called procedure will accept, or the value/output parameter of information returned. Using IDL, the programmer can make the entry points and datatypes that pass between communicating processes act like a standard language.
CORBA is a language-neutral system in which the argument values or return values are limited to what can be represented in the involved implementation languages. In CORBA, object orientation is limited only to objects that can be passed by reference (the object code itself cannot be passed from machine-to-machine) or are predefined in the overall framework. Passed and returned types must be those declared in the interface.
With RMI, the IDL and the implementation language are the same thing, so you don't have to worry about mapping from one to the other. Language-level objects (the code itself) can be passed from one process to the next. Values can be returned by their actual type, not the declared type. Or, you can compile the interfaces to generate IIOP-compliant stubs and skeletons to talk to objects written on other machines in other CORBA-compliant languages.

What is the difference between Java IDL and Java RMI-IIOP?

This is a fundamental question and it's important to understand the distinction between these two ways of integrating the Java programming language with CORBA.
Java IDL is for CORBA programmers who want to program in the Java programming language based on interfaces defined in CORBA Interface Definition Language (IDL). This is "business as usual" CORBA programming, supporting the Java language in exactly the same way as other languages like C++ or COBOL.
Java RMI-IIOP (Remote Method Invocation over Internet Inter-ORB Protocol) is for developers who want to use the Java programming language to program to the Java RMI interfaces, but use IIOP as the underlying transport. Java RMI-IIOP provides interoperability with other CORBA objects implemented in various languages - but only if all the remote interfaces are originally defined as Java RMI interfaces. It is of particular interest to programmers using Enterprise JavaBeans (EJB), since the remote object model for EJB's is RMI-based.
There are several scenarios that will define how you will want to create distributed CORBA applications. Here are some of them:
  • Java IDL - If you have been developing CORBA applications using IDL for some time, you will probably want to stay in this environment. Create the interfaces using IDL, and define the client and server applications using the Java programming language to take advantage of its "Write Once, Run AnywhereTM" portability, its highly productive implementation environment, and its very robust platform.
  • RMI-JRMP - If all of your applications are written in the Java programming language, you will probably want to use Java RMI technology to enable communication between Java objects on different virtual machines and different physical machines. Using Java RMI without its IIOP option leverages its strengths of code portability, security, and garbage collection.
  • Java RMI-IIOP - If you are writing most of your new applications using the Java programming language, but need to maintain legacy applications written in other programming languages as well, you will probably want to use Java RMI with its IIOP compiler option.

What are the limitations when using Java IDL and/or Java RMI-IIOP?

For more information on product limitations, read Limitations.

What are the standard tags for ...?

The most recent versions of standard tag allocation files can be found at the OMG Web site: http://www.omg.org/.

Copyright © 2000-2004 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


Limitations

Java

Limitations (JavaTM IDL/JavaTM RMI over IIOP)

This document lists some of the limitations regarding JavaTM IDL and JavaTM RMI over IIOP technology in this release of the JavaTM 2 Platform Standard Edition (J2SETM). The limitations are outlined below.

The Official Specifications for CORBA Support in J2SE 5.0 document provides information outlining with which OMG Specifications this implementation of the Java IDL and Java RMI over IIOP technologies comply.

LIMITATIONS:

  • JavaTM SDK version interoperability
    When a J2SETM 1.3.x client talks to a server written in J2SE 1.4 or higher using RMI-IIOP and an unchecked or RemoteException is thrown by the server, the client will hang. Similarly, when the server is using J2SE 1.3.x and the client is using J2SE 1.4 or higher, the client will receive a CORBA UNKNOWN exception with minor code 0.

    This issue is currently being addressed at the OMG in the Java to IDL RTF as issue 4795: http://www.omg.org/issues/java2idl-rtf.html#Issue4795.

    In J2SE 1.4.1 and higher: If one side is using J2SE 1.3.1.05, and the other side is using J2SE 1.4.1 or higher on the other side, this type of communication will work properly.

  • Multiple Profile IOR
    If an IOR has multiple profiles, the first IIOP profile is used for the invocation.

  • Multiple ORBs not allowed in persistent servers
    This release of Java SE platform does not allow multiple ORB instantiations in persistent servers. If the persistent server is written using the Java RMI over IIOP APIs, instantiating JNDI's InitialContext() creates an ORB. To avoid creating multiple ORBs in this setting, you can set the java.naming.ORB system property to an ORB that is already initialized.

  • Locally-optimized stubs
    Locally-optimized stubs, those with the local optimization generated by a different IDL-to-Java compiler than idlj, may be used with the J2SE 1.4 or higher ORB. However, Portable Interceptors will not be invoked when taking the locally-optimized stub branch. This is due to an issue with the OMG IDL to Java language mapping and is being addressed under OMG issue 4701.

    The J2SE 1.4 or higher rmic compiler generates locally optimized stubs when used in conjunction with the -iiop option. However, the J2SE 1.4 and higher implementation of javax.rmi.CORBA.Util always returns false for isLocal. The result is that the stubs never use the local optimization. This is due to an issue with the OMG Java to IDL language mapping and is addressed under OMG issue 3754.

    The J2SE 1.4 and higher ORB does use a locally-optimized transport for both Java IDL and Java RMI-IIOP when it detects that the client and server are running sharing the same ORB.

  • Single thread POA policy
    As per the CORBA 2.3.1 specification, there can be two choices for Thread Policy for the Portable Object Adapter (POA): The ORB Controlled Model and the Single Thread Model. J2SE 5.0 does not support the Single Thread Model.

  • RMI-IIOP Stream Format version 2
    If the super-type of a class has evolved to become custom-marshalled and writes optional, custom data, then that class cannot be sent between J2SE 1.3.x and J2SE 1.4 or higher. One example of this is that java.util.Calendar in J2SE 1.4 or higher cannot be sent back to J2SE 1.3.x.


Naming Services

Naming Service

Topics in this section include:

  • COS Naming Service: an Overview
  • Using the Naming Service

COS Naming Service: an Overview

The CORBA COS (Common Object Services) Naming Service provides a tree-like directory for object references much like a filesystem provides a directory structure for files. The Naming Service provided with Java IDL is an implementation of the COS Naming Service specification. The following overview is taken from that document.

A name-to-object association is called a name binding. A name binding is always defined relative to a naming context. A naming context is an object that contains a set of name bindings in which each name is unique. Different names can be bound to an object in the same or different contexts at the same time.

To resolve a name is to determine the object associated with the name in a given context. To bind a name is to create a name binding in a given context. A name is always resolved relative to a context - there are no absolute names.

Because a context is like any other object, it can also be bound to a name in a naming context. Binding contexts in other contexts creates a naming graph - a directed graph with nodes and labeled edges where the nodes are contexts. A naming graph allows more complex names to reference an object. Given a context in a naming graph, a sequence of names can reference an object. This sequence of names (called a compound name) defines a path in the naming graph to navigate the resolution process.

The following figure shows an example of a naming graph. A sample program that illustrates how to add names to the namespace uses this same model.

For an application to use the COS Naming Service, its ORB must know the port of a host running a naming service or have access to a stringified initial naming context for that naming service. The naming service can either be the Java IDL naming service or another COS-compliant naming service.

Prior to running a client or a server, you will start ORBD. ORBD includes a persistent Naming Service and a transient Naming Service, both of which are an implementation of the COS Naming Service.

  • The Persistent Naming Service provides persistence for naming contexts. This means that this information is persistent across service shutdowns and startups, and is recoverable in the event of a service failure. If ORBD is restarted, the Persistent Naming Service will restore the naming context graph, so that the binding of all clients' and servers' names remains intact (persistent).

  • For backward compatibility, tnameserv, a Transient Naming Service shipped with older versions of the JDK, is also included in this release of J2SE. A transient naming service retains naming contexts as long as it is running. If there is a service interruption, the naming context graph is lost.

Both client and server should agree on which root naming context to use. The orb.resolve_initial_references(String name_of_service) method is used to obtain the root naming context. If you get a handle on a Naming Service by providing "NameService" as the name_of_service, you will get a persistent naming service, meaning that the naming context graph will be restored after a service failure. If you get the handle using "TNameService", you will get a transient naming service, meaning that you will need to re-obtain the root naming context using orb.resolve_initial_references(String name_of_service) if there is a service interruption.

For example,

      // get the root naming context
      org.omg.CORBA.Object objRef =
          orb.resolve_initial_references("NameService");
      NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef);

The string "NameService" is defined for all CORBA ORBs. When you pass in this string, the ORB returns a naming context object that is an object reference for:

  • The persistent name service if you are using the Naming Service that is part of ORBD.
  • The transient name service if you are using tnameserv.

To specify that you want to use the transient naming service with ORBD, pass in the string "TNameService". The string "TNameService" is a proprietary name. When you pass in this string, the ORB returns a naming context object that is an object reference for ORBD's transient name service.

As with all CORBA object references, objRef is a generic CORBA object. To use it as a NamingContextExt object, you must narrow it to its proper type.

NamingContextExtHelper is an idlj-generated helper class, similar in function to HelloHelper. The ncRef object is now an org.omg.CosNaming.NamingContextExt and you can use it to access the naming service and register the server.

NamingContextExt and NamingContextExtHelper are new to this release of J2SE. NamingContextExt is the extension of NamingContext. It contains a set of name bindings in which each name is unique and is part of the Interoperable Naming Service. Different names can be bound to an object in the same or different contexts at the same time. Using NamingContextExt, you can use URL-based names to bind and resolve. NamingContextExtHelper provides additional helper methods like narrow() that are type-specific but don't deal with business logic.

Interoperable Naming Service

The Interoperable Naming Service (INS) is a URL-based naming system on top of the CORBA Naming Service, as well as a common bootstrap mechanism that lets applications share a common initial naming context.

The Interoperable Naming Service (INS) provides the following features:

  • Capability to resolve using stringified names (e.g., a/b.c/d)
  • URLs for CORBA object references (corbaloc: and corbaname: formats)
  • Standard APIs in NamingContextExt for converting between CosNames, URLs, and Strings
  • ORB arguments for bootstrapping (ORBInitRef and ORBDefaultInitRef)

An example application that demonstrates how to use the INS can be found at Interoperable Naming Service Example.

The following diagram shows how INS fits into ORBD:

An object reference contains at least three pieces of information: an address, the name of the POA that created an object reference, and an Object ID.

Using INS, you can provide a URL to access the CORBA object, which is more readable than a stringified IOR. The following stringified object reference formats are allowed:

  • Interoperable Object References (IOR)

    An IOR is an object reference that is understood by ORBs that can interoperate using the OMG-defined protocols GIOP and IIOP. A client can obtain an object reference using orb.object_to_string(objRef), as shown in the Browsing the Namespace example, or as a result of an invocation on another object reference.

    Note: If an IOR contains multiple profiles, the J2SE v.1.4 and higher ORB always uses the first one.

  • Human-Readable URL Formats for CORBA Object References

    • corbaloc:

      The corbaloc: format is useful for CORBA client programs, and is typically used to resolve the reference using the GIOP LocateRequest or Request message. For example, a corbaloc: object reference might look like this:

           corbaloc:iiop:1.2@MyBank.com:2050/TraderService

      This example show how to get an object reference for TraderService from host myBank.com on port 2050.

    • corbaname:

      The corbaname: format provides a mechanism for a client to bootstrap directly, and is typically used to resolve the stringified name from the root naming context. For example, a corbaname: object reference might look like this:

           corbaname::myBank.com:2050#Personal/schedule

      where myBank.com is the host, 2050 is the port. The portion of the reference up to the hash mark (corbaname::myBank.com:2050 ) is the URL that returns the root naming context. This example provides the URL to use to: a) locate the Naming Service, and, b) resolve the name Personal/schedule from the Naming Service.

Bootstrap Options for the ORB

INS provides ORB options for bootstrapping. To bootstrap a CORBA system, you must give it an object reference. The ORB can be configured to return the handle of a customized CORBA service from resolve_initial_references() using either ORBInitRef and/or ORBDefaultInitRef. For example,

    -ORBInitRef TraderService=corbaloc::myBank.com:2050/TraderService
-ORBDefaultInitRef corbaloc:iiop:1.2:myBank.com:2050

The order of resolution when these options are used is as follows:

  1. Objects registered with register_initial_references
  2. -ORBInitRef
  3. -ORBDefaultInitRef
  4. Proprietary Bootstrap (Sun ORBs only)

For more information about INS, refer to the OMG specification at (ptc/00-08-07).

Using the Naming Service

To use the Naming Service, you must first write the server and client code that finds and/or creates the namespace and/or the objects in the namespace. Before running the client and server, you must start the Naming Service and tell the client and server where to find it. The following steps loosely suggest what happens when the client and server attempt to access the Naming Service:

  • The server invokes the bind or rebind method to associate a logical name with an object reference.
  • The Naming Service adds this object reference/name binding to its namespace database.
  • A client application invokes the resolve method to obtain an object reference with this name.
  • The client uses an object reference to invoke methods on the target object.

The following topics are covered in this section:

  • Sample Client: Adding Objects to the Namespace
  • Sample Client: Resolving Objects from the Namespace
  • Sample Client: Browsing the Namespace
  • Starting the Naming Service
  • Stopping the Naming Service

Sample Client: Adding Objects to the Namespace

The following sample program illustrates how to add names to the namespace. It is a self-contained Naming Service client that creates the following simple tree. Naming contexts are in italics and object references are in normal font.

In this example, plans is an object reference and Personal is a naming context that contains two object references: calendar and schedule.

  1. Create the NameClient.java file and import the proper libraries:

    import java.util.Properties;
import org.omg.CORBA.*;
import org.omg.CosNaming.*;

public class NameClient
{
   public static void main(String args[])
   {
      try {

  2. Set Port and Host properties.

    In the section, Starting the Naming Service, the name server is started on port 1050 and host localhost. The following code ensures that the client program is aware of this port number and host name.

            Properties props = new Properties();
        props.put("org.omg.CORBA.ORBInitialPort", "1050");
        props.put("org.omg.CORBA.ORBInitialHost", "localhost");
        ORB orb = ORB.init(args, props);

  3. Obtain the initial naming context.

    The following code obtains the initial naming context and assigns it to ctx. The second line copies ctx into a dummy object reference objref that we'll attach to various names and add into the namespace.

        NamingContextExt ctx =
          NamingContextExtHelper.narrow(orb.resolve_initial_references(
            "NameService"));
        org.omg.CORBA.Object objref = ctx;

  4. Bind the name "plans" to the object reference.

    This code binds the name "plans" to our dummy object reference. The object reference, "plans", is then added under the initial naming context using rebind. The rebind method allows us to run this program over and over again without getting the exceptions we'd get from using bind.

            NameComponent name1[] = ctx.to_name("plans");
        ctx.rebind(name1, objref);
        System.out.println("plans rebind successful!");

  5. Create a new naming context named "Personal".

    This code creates a new naming context called "Personal". The resulting object reference, ctx2, is bound to the name and added under the initial naming context.

            NameComponent name2[] = ctx.to_name("Personal");
        NamingContextExt ctx2 = (NamingContextExt)ctx.bind_new_context(name2);
        System.out.println("New naming context, Personal, added!");

  6. Bind "schedule" and "calendar" to a dummy object reference. To bind a name is to create a name binding in a given context. A name is always resolved relative to a context - there are no absolute names.

    This code binds the dummy object reference using the names "schedule" and "calendar" under the "Personal" naming context (ctx2).

            NameComponent name3[] = ctx.to_name("schedule");
        ctx2.rebind(name3, objref);
        System.out.println("schedule rebind successful!");

        NameComponent name4[] = ctx.to_name("calendar");
        ctx2.rebind(name4, objref);
        System.out.println("calendar rebind successful!");

    } catch (Exception e) {
        e.printStackTrace(System.err);
    }
  }
}

  7. Save NameClient.java, and compile the file as follows:

         javac NameClient.java

    Correct any syntax errors before proceeding.

  8. Run the Object Request Broker Daemon as shown in Starting the Naming Service.

  9. Run NameClient, as follows:

         java NameClient -ORBInitialPort 1050

The output in the terminal window looks like this:

We now have a namespace that to the Naming Service looks like the above diagram.

Sample Client: Resolving Objects from the Namespace

The following sample program illustrates how to resolve names from the namespace. To resolve a name is to determine the object associated with the name in a given context. When using the persistent Naming Service, you do not need to re-resolve if the Naming Service goes down. If you use a transient Naming Service, you do need to re-resolve in the Naming Service goes down.

In this example, plans is an object reference and Personal is a naming context that contains two object references: calendar and schedule.

  1. Create the NameClientResolve.java file and import the proper libraries:

    import java.util.Properties;
import org.omg.CORBA.*;
import org.omg.CosNaming.*;

public class NameClientResolve
{
   public static void main(String args[])
   {
      try {

  2. Set Port and Host properties.

    In the section, Starting the Naming Service, the name server is started on port 1050 and host localhost. The following code ensures that the client program is aware of this port number and host name.

            Properties props = new Properties();
        props.put("org.omg.CORBA.ORBInitialPort", "1050");
        props.put("org.omg.CORBA.ORBInitialHost", "localhost");
        ORB orb = ORB.init(args, props);

  3. Obtain the initial naming context.

    The following code obtains the initial naming context and assigns it to nc.

        NamingContextExt nc =
          NamingContextExtHelper.narrow(orb.resolve_initial_references(
            "NameService"));

  4. Resolve each namespace.

    The following code resolves each namespace.

       org.omg.CORBA.Object sched = nc.resolve_str("Personal/schedule");
        org.omg.CORBA.Object cal = nc.resolve_str("Personal/calendar");
        org.omg.CORBA.Object plan = nc.resolve_str("plans");

      //finish the try-catch block
      } catch (Exception e) {
        e.printStackTrace(System.err);
        }
}

  5. Save NameClientResolve.java, and compile the file as follows:

         javac NameClientResolve.java

    Correct any syntax errors before proceeding.

  6. Make sure the Object Request Broker Daemon is running and the client application illustrated in Sample Client: Adding Objects to the Namespace has been run.

  7. Run NameClientResolve, as follows:

         java NameClientResolve -ORBInitialPort 1050

There is no output to the terminal window when you run this client application. If you want verification that the object references have been resolved, you could add code such as the following for testing purposes:

    if (sched == null){
      System.out.println("Schedule is null");
    }

    if (cal == null){
      System.out.println("Calendar is null");
    }

    if (plan == null){
      System.out.println("Plans is null");
    }

Sample Client: Browsing the Namespace

The following sample program illustrates how to browse the namespace.

  1. Create the NameClientList.java file and import the proper libraries:

    import java.util.Properties;
import org.omg.CORBA.*;
import org.omg.CosNaming.*;

public class NameClientList
{
   public static void main(String args[])
   {
      try {

  2. In the section, Starting the Naming Service, the nameserver is started on port 1050 and host localhost. The following code ensures that the client program is aware of this port number and host name.

        Properties props = new Properties();
        props.put("org.omg.CORBA.ORBInitialPort", "1050");
        props.put("org.omg.CORBA.ORBInitialHost", "localhost");
        ORB orb = ORB.init(args, props);

  3. Obtain the initial naming context.

            NamingContextExt nc =
          NamingContextExtHelper.narrow(orb.resolve_initial_references(
            "NameService"));

  4. List all bindings in the naming context.

    The list method lists the bindings in the naming context. In this case, up to 1000 bindings from the initial naming context will be returned in the BindingListHolder; any remaining bindings are returned in the BindingIteratorHolder.

        BindingListHolder bl = new BindingListHolder();
        BindingIteratorHolder blIt= new BindingIteratorHolder();
        nc.list(1000, bl, blIt);

  5. Get the array of bindings.

    This code gets the array of bindings out of the returned BindingListHolder.

            Binding bindings[] = bl.value;

  6. This code loops through the bindings and prints the names out.
            for (int i=0; i < bindings.length; i++) {

            int lastIx = bindings[i].binding_name.length-1;

            // check to see if this is a naming context
            if (bindings[i].binding_type == BindingType.ncontext) {
              System.out.println( "Context: " +
                bindings[i].binding_name[lastIx].id);
            } else {
                System.out.println("Object: " +
                  bindings[i].binding_name[lastIx].id);
            }
        }

       } catch (Exception e) {
        e.printStackTrace(System.err);
       }
   }
}

  7. Save NameClientList.java, and compile the file as follows:

         javac NameClientList.java

    Correct any syntax errors before proceeding.

  8. Make sure the Object Request Broker Daemon is running, the client application illustrated in Sample Client: Adding Objects to the Namespace has been run, and the client application illustrated in Sample Client: Resolving Objects from the Namespace has been run.

  9. Run NameClientList, as follows:

         java NameClientList -ORBInitialPort 1050

The output in the terminal window looks like this:

Starting the Naming Service

In all of the tutorials we use the Object Request Broker Daemon, orbd, which includes both a Persistent and a Transient Naming Service, and is available with every download of J2SE 1.4 and higher.

For a caller (client, peer, or client application) to be able to invoke a method on a remote object, that caller must first obtain a reference to the remote object.

Once a remote object is registered on the server, callers can look up the object by name, obtain a remote object reference, and then remotely invoke methods on the object.

To learn how to start the Naming Service, see the topic Starting the Naming Service in the ORBD documentation.

Stopping the Naming Service

To stop the naming service, use the relevant operating system command, such as kill on Solaris, or Ctrl+C in the DOS window in which orbd is running. Note that names registered with the naming service may disappear when the service is terminated if the naming service is transient. The Java IDL naming service will run until it is explicitly stopped.

Naming Service FAQ

How do I connect to a 3rd-party Naming Service from Sun's ORB?

The recommended way is to use the Inter-Operable Naming Service (INS), if this option is supported by the 3rd-party Naming Service.

To use the Sun ORB with another vendor's Naming Service,

  1. Start the 3rd-party name server on Host and Port.

  2. Pass the following argument to ORB.init():
            -ORBInitRef NameService=corbaloc:iiop:1.2@:
    /NameService

When you do orb.resolve_initial_references( "NameService" ), you should be able to connect to 3rd-party Name Service. If you are still not able to connect, try these troubleshooting hints:

  • Verify that the 3rd-party Name Service supports INS.
  • Verify that the host and port information is accurate.
  • Verify that the 3rd-party Name Service has been started successfully.
  • Verify that the 3rd-party Name Service supports GIOP 1.2. If not, refer to the Name Server's documentation for the correct the GIOP version, and modify the corbaloc: URL accordingly.
  • Determine if the 3rd-party Name Service has a different object key it uses to contact NameService. If so, refer to the Name Server's documentation.
Java IDL Home


Official Specifications for CORBA support in J2SE 5.0

Specification References

The specifications with which the Java 2 Platform Standard Edition (J2SE) 5.0 ORB complies are as follows. If these links do not take you to the referenced specification, the OMG may have changed the URL, and you can link to www.omg.org to search for the correct specification.
  • CORBA 2.3.1 (formal/99-10-07)
  • IDL to Java language mapping (ptc/00-01-08)
  • Revised IDL to Java language mapping (ptc/00-11-03)
  • Java to IDL language mapping (ptc/00-01-06)
  • Interoperable Naming Service (ptc/00-08-07)
  • Portable Interceptors (ptc/2001-08-31)
These are the only specifications referenced by this document.

Supported Specification Details

Not all of the above specifications are currently implemented in the ORB in J2SE 5.0. The precise list of supported sections is as follows:
  • CORBA 2.3.1 chapters 1-3 and 6-9
  • Revised IDL to Java language mapping, section 1.21.8.2, the orb.properties file.
  • CORBA 2.3.1 chapter 4 with the following replacements from the Portable Interceptors specification:
    • section 4.2.3.5 destroy
    • section 4.5.2 CodeFactory and PICurrent are required
    • Section 4.5.3.4 as updated for register_initial_reference
  • CORBA 2.3.1 chapter 5 with the following update from the Portable Interceptors specification:
    • 5.5.2 StringSeq and WStringSeq are required. This adds the following classes to org.omg.CORBA:
      • StringSeqHolder
      • StringSeqHelper
      • WStringSeqHolder
      • WStringSeqHelper
  • CORBA 2.3.1 sections 10.6.1 and 10.6.2 are supported for repository IDs.
  • CORBA 2.3.1 section 10.7 for TypeCode APIs.
  • CORBA 2.3.1 chapter 11, Portable Object Adapter (POA), with the following updates from the Portable Interceptors specification:
    • Section 11.3.7 POAs must preserve all policies
    • Section 11.3.8.2 again states that POAs must preserve all policies
    • Section 11.3.8.26 POA::id is required.
  • CORBA 2.3.1 chapters 13 and 15 define GIOP 1.0, 1.1, and 1.2. The J2SE 5.0 ORB fully supports all versions of GIOP, with the exception that the bi-directional GIOP feature defined in sections 15.8 and 15.9 is not supported.
  • All of the Interoperable Naming Service is supported.
  • Portable Interceptors section 13.8 (the new Coder/Decoder interfaces) and all of chapter 21 (the interceptor specification).
  • Section 1.21.8 of the Revised IDL to Java Language Mapping Specification (ptc/00-11-03) has been changed from the version in the IDL to Java Language Mapping Specification (ptc/00-01-08).

Tools

  • The IDL to Java compiler (idlj) complies with:
    • CORBA 2.3.1 chapter 3 (IDL definition)
    • CORBA 2.3.1 chapters 5 and 6 (semantics of Value types)
    • CORBA 2.3.1 section 10.6.5 (pragmas)
    • The IDL to Java mapping specification
    • The Revised IDL to Java language mapping specification section 1.12.1 "local interfaces"
  • The Java to IDL compiler (the IIOP backend for rmic) complies with:
    • CORBA 2.3.1 chapters 5 and 6 (value types)
    • The Java to IDL language mapping. Note that this implicitly references section 1.21 of the IDL to Java language mapping
    • IDL generated by the -idl flag complies with CORBA 2.3.1 chapter 3.


Portable Interceptors (PI)

Java IDL and Java RMI-IIOP Technologies:

Using Portable Interceptors (PI)

Last Update: 4/25/2002

NOTICE: This document is intended for advanced CORBA developers.

The JavaTM CORBA Object Request Broker (ORB) provides hooks, or interception points, through which ORB services can intercept the normal flow of execution of the ORB. These Portable Interceptors provide a mechanism for plugging in additional ORB behavior, or, by modifying the communications between client and server, for modifying the behavior of the ORB. The example that follows shows different ways of using Portable Interceptors.

Support for Portable Interceptors is a major recent addition to the CORBA specification. Using RequestInterceptors, one can easily write and attach portable ORB hooks that will intercept any ORB-mediated invocation. Using IORInterceptors, one can write code to annotate CORBA object references.

It is highly recommended that you read the Portable Interceptors Specification at ptc/2001-03-04 before reading this document.

The following topics are included in this document:

  • Interceptor Types
  • Registering ORBInitializers in Java
    • Notes About the Scope of Interceptors
    • Notes on Interceptor Order
    • Notes about Registering Interceptors
  • Portable Interceptor Current (PICurrent)
    • Obtaining PICurrent
    • Obtaining PICurrent
    • Request Scope vs Thread Scope
  • Portable Interceptor Example
    • Flowing Context Information between Clients and Servers
    • Avoiding Infinite Recursion During Interceptor Outcalls
    • Avoiding Recursion for Colocated Outcall References
    • Avoid recursion by using multiple ORBs
  • Example Code
  • Compiling and running the application

Interceptor Types There are currently three types of interceptors that can be registered, as shown below. Examples of each are shown in the example that follows.
  • IORInterceptor

    In some cases, a portable ORB service implementation may need to add information describing the server's or object's ORB service-related capabilities to object references in order to enable the ORB service implementation in the client to function properly. This is supported through the IORInterceptor and IORInfo interfaces. The IOR Interceptor is used to establish tagged components in the profiles within an Interoperable Object Reference (IOR).

    An example of an IOR Interceptor is shown in the file AServiceIORInterceptor.java in the example that follows.

  • ClientRequestInterceptor

    A request Interceptor is designed to intercept the flow of a request/reply sequence through the ORB at specific points so that services can query the request information and manipulate the service contexts which are propagated between clients and servers. The primary use of request Interceptors is to enable ORB services to transfer context information between clients and servers.

    A ClientRequestInterceptor intercepts the flow of a request/reply sequence through the ORB on the client side.

    • An example of a ClientRequestInterceptor is shown in the file LoggingServiceClientInterceptor.java in the example that follows.

  • ServerRequestInterceptor

    A ServerRequestInterceptor intercepts the flow of a request/reply sequence through the ORB on the server side.

    An example of a ServerRequestInterceptor is shown in the file LoggingServiceServerInterceptor.java in the example that follows.

Registering ORBInitializers in Java

The ORBInitializer interface facilitates interceptor registration and ORB initialization.

Interceptors are intended to be a means by which ORB services gain access to ORB processing, effectively becoming part of the ORB. Since interceptors are part of the ORB, when ORB.init returns an ORB, the interceptors shall have been registered. Interceptors cannot be registered on an ORB after it has been returned by a call to ORB.init.

ORBInitializers are registered via Java ORB properties. An interceptor is registered by registering an associated ORBInitializer object which implements the ORBInitializer interface. When an ORB is initializing, it shall call each registered ORBInitializer, passing it an ORBInitInfo object which is used to register its interceptor.

The property names are of the form:

org.omg.PortableInterceptor.ORBInitializerClass.<Service>
where <Service> is the string name of a class which implements
org.omg.PortableInterceptor.ORBInitializer
To avoid name collisions, the reverse DNS name convention should be used. For example, if company X has three initializers, it could define the following properties:
  • org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init1
  • org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init2
  • org.omg.PortableInterceptor.ORBInitializerClass.com.x.Init3

Note: Any values associated with ORBInitializerClass properties are ignored.

During ORB.init, these ORB properties which begin with org.omg.PortableInterceptor.ORBInitializerClass shall be collected, the <Service> portion of each property shall be extracted, an object shall be instantiated with the <Service> string as its class name, and the pre_init and post_init methods shall be called on that object. If there are any exceptions, the ORB shall ignore them and proceed.

Notes About the Scope of Interceptors

  • Interceptors are registered on a per-ORB basis.

  • To achieve virtual per-POA interceptors, instantiate each POA with a different ORB.

Notes on Interceptor Order

  • While interceptors may be ordered administratively, there is no concept of order with respect to the registration of interceptors. Request Interceptors are concerned with service contexts. Service contexts have no order, so there is no purpose for request interceptors to have an order. IOR Interceptors are concerned with tagged components. Tagged components also have no order, so there is no purpose for IOR Interceptors to have an order.

Notes about Registering Interceptors

  • Registration code should avoid using the ORB (i.e., calling ORB.init with the provided orb_id). Since registration occurs during ORB initialization, results of invocations on this ORB while it is in this state are undefined.

Portable Interceptor Current (PICurrent)

The PortableInterceptor::Current object (hereafter referred to as PICurrent) is a Current object that is used specifically by portable Interceptors to transfer thread context information to a request context. Portable Interceptors are not required to use PICurrent, but if information from a client's thread context is required at an Interceptor's interception points, then PICurrent can be used to propagate that information. PICurrent allows portable service code to be written regardless of an ORB's threading model.

Note: PICurrent is typically NOT used directly by CORBA client or server code. Instead, it is generally used by interceptor-based service implementations as demonstrated in the AService example interceptor which follows.

Obtaining PICurrent

Before an invocation is made, PICurrent is obtained via a call to ORB::resolve_initial_references ( PICurrent ). From within the interception points, the data on PICurrent that has moved from the thread scope to the request scope is available via the get_slot operation on the RequestInfo object. A PICurrent can still be obtained via resolve_initial_references, but that is the Interceptor's thread scope PICurrent.

Request Scope vs Thread Scope

The thread scope PICurrent (TSC) is the PICurrent that exists within a thread's context. A request scope PICurrent (RSC) is the PICurrent associated with the request. On the client-side, the thread scope PICurrent is logically copied to the request scope PICurrent from the thread s context when a request begins and is attached to the ClientRequestInfo object. On the server-side, the request scope PICurrent is attached to the ServerRequestInfo and follows the request processing. It is logically copied to the thread scope PICurrent after the list of receive_request_service_contexts interception points are processed. See the Updated Interceptors specification, Section, 21.4.4.5, Flow of PICurrent between Scopes for a detailed discussion of the scope of PICurrent.

Portable Interceptor Example

This section contains an example logging service application. The sample code for this application is quite complicated because it covers even subtle "corner cases". The following scenarios are covered in this sample application:

  1. A logging service which logs invocations. Neither client nor server explicitly use the logging service.

  2. An "empty" service which passes information from the client to the server. The client and server explicitly use this service but are not aware that it is implemented using interceptors.

Note: These examples explicitly register ORBInitializers to make the code easier to experiment with and setup. Typically this would not be done. Instead, this information would be passed as -D properties to the Java virtual machine when the applications are started. That way the applications are not coupled to the fact that either the service exists (e.g., the logging service) or that a service that they explicitly use (e.g., the AService interface) is implemented as an interceptor.

The purpose of the logging service example is to show how to avoid infinite recursion when making outcalls (i.e., invocations on CORBA references) from within interception points. This turns out to be quite involved when all corner cases are covered.

The purpose of the "empty" service example is to show how to implement services which flow context information from client to server and back.

Flowing Context Information between Clients and Servers

A typical interceptor-based service will flow context information between clients and servers. The AService example shows how this information is flowed from the client thread into the client interceptors, across the wire into the server interceptors, to the servant thread and back.

It is important to note that neither the client nor the servant is aware that the service is implemented using interceptors. Instead, they interact with the service through local object references (the aService reference in this example).

AService diagram

AService diagram

Description of the steps of the AService diagram:

  1. The client invokes aService.begin().

    1.a. aService.begin() sets the service context information in a slot it has reserved in PICurrent.

  2. The client invokes a method on some reference (i.e., ref.method()). This invocation is taking place inside the context of the service since aService.begin() has been invoked.

  3. send_request is entered for the ref.method call.

  4. get_effective_component(s) may be called to determine if the reference being invoked needs to interact with the service.

  5. get_slot is called to retrieve the context set in step 1a. Slots set in PICurrent are logically copied and made available to ClientRequestInfo.

  6. The service interceptor adds a service context containing the appropriate context (most likely depending on the context set in step 1a and any components retrieved in step 4). It uses add_request_service_context to add this context information to the request which is sent over the wire.

  7. The ref.method request arrives at the server, activating the receive_request_service_contexts interception point.

  8. get_request_service_context is used to retrieve the service context added at step 6.

  9. ServerRequestInfo.set_slot is used to transfer the context information from the service context retrieved in step 8 to the logical thread local data.

  10. receive_request is entered.

  11. The "ref" Servant's "method" is entered.

  12. The servant method invokes aService.verify() to interact with the service.

  13. The service uses get_slot on PICurrent to retrieve the context information sent from the client side. The service may also use set_slot on PICurrent to set any return context information.

  14. After the Servant completes, the send_* interception point is entered. If the service set any return context information, it would add a service context to the return. This is not shown in this example.

  15. When the reply arrives at the client, the receive_* interception point is entered. If the service set any return context information, it would be retrieved at this point. This is not shown in this example.

Avoiding Infinite Recursion During Interceptor Outcalls

Some services may need to make invocations on other CORBA object references from within interception points. When making outcalls from within interception points, steps must be taken to avoid infinite recursion since those outcalls will flow through the interception points. The LoggingService example illustrates this case.

The LoggingService example is comprised of ClientRequestInterceptors registered in a client program, and ServerRequestInterceptors registered in a server program. These interceptors send information from the client and server to a LoggingService implemenation which logs this information.

However, since the LoggingService implementation is itself a CORBA server, we must ensure that we do not log calls to the logger. The following diagrams illustrate the steps taken to avoid infinite recursion.

The following diagram shows the simplest case of avoiding recursion when calling an external logger from within interceptors. These steps are useful for the case where the client ORB only contains ClientRequestInterceptors, the server ORB only contains ServerRequestInterceptors, and the LoggingService is external to both the client and server ORBs.

LoggingService diagram

Logging Service diagram

Description of the steps of the LoggingService diagram:

  1. The client invokes a method on some reference.

  2. The client interceptor's send_request method is entered for the method invoked in step 1.

  3. A slot reserved for indicating an outcall is set to true on PICurrent.

  4. The same slot is checked on ClientRequestInfo via get_slot. This value will not be set since it represents the client's thread state at step 1. Therefore a call to the logger will be made.

  5. send_request is recursively entered for the logger invocation made in step 4.

  6. A slot reserved for indicating an outcall is set to true on PICurrent. Note, this slot is always unconditionally set. This is necessary when there are 2 or more interceptors doing outcalls. Since interceptors do not know about the existence of other interceptors we always set the PICurrent slot.

  7. The slot is checked on ClientRequestInfo via get_slot. This time the value is set (from step 3). Therefore we do not log this call (which is the call to the logger itself). The send_request point that entered at step 5 finishes.

  8. The ORB sends the log invocation made at step 4 to the logging service.

  9. The send_request point for step 2 finishes. The ORB sends the initial client invocation made in step 1 to the server for the appropriate reference.

  10. The server's receive_request_service_contexts point is entered. It logs the incoming request. A server which does not contain client interceptors which make outcalls and which does not contain the implementation of the logger itself does not need to set recursion avoidance slots. That is what this diagram represents.

  11. - 13. Therefore all the server side interception points are entered with no further checking and the response from the method initially invoked by the client is returned to the client ORB.

  14. The client's receive_* point is entered. Steps similar to steps 2 through 9 will occur if this point needs to make an outcall.

Avoiding Recursion for Colocated Outcall References

The following diagram illustrates the case where the LoggingService may be colocated in the same ORB as the reference being invoked by the client. In general, it is not possible to know that a particular object reference is NOT colocated with any other objects hosted by that ORB. Therefore, to cover all corner cases, more steps must be taken.

This diagram shows only the server side. The client side steps are identical to those in the preceding diagram.

LoggingServiceColocated diagram

LoggingServiceColocated diagram

Description of the steps of the LoggingServiceColocated diagram:

  1. The request from the client ORB arrives, activating the receive_request_service_contexts interception point.

  2. A slot reserved for indicating an outcall is set to true on PICurrent.

  3. ServerRequestInfo.get_request_service_context is used to check for the presence of a service context indicating an outcall. The service context is not present so the logger is invoked from within the interception point.

  4. The send_request interception point is entered for the logger request.

  5. get_slot checks for the outcall indicator.

  6. The outcall indicator slot has been set (from step 2), therefore add_request_service_context is used to a service context indicating an outcall. This is necessary since there is no logical relationship between client and server threads.

  7. The logger invocation arrives at receive_request_service_contexts.

  8. A slot reserved for indicating an outcall is set to true on PICurrent.

  9. ServerRequestInfo.get_request_service_context is used to check for the presence of a service context indicating an outcall. The service context is present so no further action is taken. receive_request_service_contexts exits.

  10. The logger request proceeds to receive_request. Steps similar to those taken inside receive_request_service_context are necessary if the logger is called at the receive_request point (this is not shown in the diagram (although the example code logs all points)).

  11. The logger request arrives at the LoggingService Servant, which logs the initial client request (not invocation of the logger).

  12. The logger request proceeds to ServerRequestInterceptor.send_* (most likely send_reply).

  13. The logger request proceeds to ClientRequestInterceptor.receive_* (most likely receive_reply).

    After Step 13, the original request that left off at Step 3 would be serviced.

The main point illustrated in this example is the necessity of using both client and server interceptors in conjunction with PICurrent slots and service contexts to indicate an outcall.

Avoid recursion by using multiple ORBs

A simpler way to avoid recursion is to ensure that the outcall references are associated with a different ORB that does not have the logging interceptors registered. That way the outcall invocations never go through interceptors.

This seems like a simple solution, but, in general, interceptors are registered via properties passed to the VM during startup. This means that all ORBs created in that VM will contain all interceptors so this solution will not work.

This solution will only work where interceptors are explicitly registered in client code during ORB.init. However, that is neither a typical nor a recommended way to register interceptor-based services.

Example Code

The following files contain the code which the above diagrams illustrate. Instructions for compiling and executing these examples follow the code. The files included in this example are:

  • serviceexample.idl
  • LoggingServiceClientORBInitializer.java
  • LoggingServiceClientInterceptor.java
  • LoggingServiceServerORBInitializer.java
  • LoggingServiceServerInterceptor.java
  • LoggingServiceImpl.java
  • AServiceORBInitializer.java
  • AServiceImpl.java
  • AServiceInterceptor.java
  • AServiceIORInterceptor.java
  • ArbitaryObjectImpl.java
  • Client.java
  • ColocatedServers.java

    serviceexample.idl

    This is the Interface Definition Language (IDL) file that contains definitions of an arbitrary object on which to make invocations and two services which will service calls to the arbitrary object.

// serviceexample.idl
// Copyright and License

module pi
{
module serviceexample
{

    // Create some arbitrary object to call.  Those calls
    // will be serviced by the service implemented using interceptors.

    exception ArbitraryObjectException { string reason; };

    interface ArbitraryObject
    {
             string         arbitraryOperation1 ( in string a1 );

        oneway void         arbitraryOperation2 ( in long a1 );

           void         arbitraryOperation3 ( in string a1 )
                            raises (ArbitraryObjectException);
    };

    // This would typically be in a file separate from the "ArbitraryObject"
    // and probably unknown to it.

    interface LoggingService
    {
    void log ( in string a1 );
    };

    // This would also typically be in a file of its own.
    // IMPORTANT: the interface should be a local object to avoid
    // unnecessary overhead.

    /*local*/ interface AService
    {
    void begin();
    void end();
    void verify();
    };

    // Tagged component for adding to an IOR to indicate that
    // the AService must be in effect when invocations are made
    // on the object containing this tagged component.

    // Note: we explicitly declare the tag type rather than using
    // the IOP typedef (commented out) to simplify compiling this
    // example (i.e., to avoid includes and make include path directives).
    //const IOP::ComponentId TAG_ASERVICE_COMPONENT = 2345;
    const unsigned long TAG_ASERVICE_COMPONENT = 2345;

    struct ASERVICE_COMPONENT {
        boolean requiresAService;
    };

}; // module serviceexample

}; // module pi

    LoggingServiceClientORBInitializer.java

    This file creates and registers the logging service interceptor used by object clients.

// LoggingServiceClientORBInitializer.java
// Copyright and License

package pi.serviceexample;

import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.PortableInterceptor.Current;
import org.omg.PortableInterceptor.CurrentHelper;
import org.omg.PortableInterceptor.ORBInitInfo;

public class LoggingServiceClientORBInitializer
    extends org.omg.CORBA.LocalObject
    implements org.omg.PortableInterceptor.ORBInitializer
{
    public void pre_init(ORBInitInfo info)
    {
    }

    public void post_init(ORBInitInfo info)
    {
    try {

        // Get a reference to the LoggingService object.

        NamingContext nameService =
        NamingContextHelper.narrow(
                    info.resolve_initial_references("NameService"));

        NameComponent path[] =
            { new NameComponent("LoggingService", "") };
        LoggingService loggingService =
        LoggingServiceHelper.narrow(nameService.resolve(path));

        // Get a reference to TSC PICurrent.

        Current piCurrent =
        CurrentHelper.narrow(
                info.resolve_initial_references("PICurrent"));

        // Allocate a slot id to use for the interceptor to indicate
        // that it is making an outcall.  This is used to avoid
        // infinite recursion.

        int outCallIndicatorSlotId = info.allocate_slot_id();

        // Create (with the above data) and register the client
        // side interceptor.

        LoggingServiceClientInterceptor interceptor =
        new LoggingServiceClientInterceptor(loggingService,
                            piCurrent,
                            outCallIndicatorSlotId);

        info.add_client_request_interceptor(interceptor);
    } catch (Throwable t) {
        System.out.println("Exception handling not shown.");
    }
    }
}

    LoggingServiceClientInterceptor.java

    This interceptor logs client side interception points. It illustrates how to make invocations on other objects from within an interceptor and how to avoid infinite recursion during those "outcall" invocations.

// LoggingServiceClientInterceptor.java
// Copyright and License

package pi.serviceexample;

import org.omg.CORBA.Any;
import org.omg.CORBA.ORB;
import org.omg.CORBA.TCKind;
import org.omg.IOP.ServiceContext;
import org.omg.PortableInterceptor.ClientRequestInterceptor;
import org.omg.PortableInterceptor.ClientRequestInfo;
import org.omg.PortableInterceptor.Current;
import org.omg.PortableInterceptor.InvalidSlot;

public class LoggingServiceClientInterceptor
    extends org.omg.CORBA.LocalObject
    implements ClientRequestInterceptor
{
    private LoggingService loggingService;
    private Current piCurrent;
    private int outCallIndicatorSlotId;

    public LoggingServiceClientInterceptor(LoggingService loggingService,
                       Current piCurrent,
                       int outCallIndicatorSlotId)
    {
    this.loggingService = loggingService;
    this.piCurrent = piCurrent;
    this.outCallIndicatorSlotId = outCallIndicatorSlotId;
    }

    //
    // Interceptor operations
    //

    public String name()
    {
    return "LoggingServiceClientInterceptor";
    }

    public void destroy()
    {
    }

    //
    // ClientRequestInterceptor operations
    //

    public void send_request(ClientRequestInfo ri)
    {
    log(ri, "send_request");
    }

    public void send_poll(ClientRequestInfo ri)
    {
    log(ri, "send_poll");
    }

    public void receive_reply(ClientRequestInfo ri)
    {
    log(ri, "receive_reply");
    }

    public void receive_exception(ClientRequestInfo ri)
    {
    log(ri, "receive_exception");
    }

    public void receive_other(ClientRequestInfo ri)
    {
    log(ri, "receive_other");
    }

    //
    // Utilities.
    //

    public void log(ClientRequestInfo ri, String point)
    {
    // IMPORTANT: Always set the TSC out call indicator in case
    // other interceptors make outcalls for this request.
    // Otherwise the outcall will not be set for the other interceptor's
    // outcall resulting in infinite recursion.

    Any indicator = ORB.init().create_any();
    indicator.insert_boolean(true);
    try {
        piCurrent.set_slot(outCallIndicatorSlotId, indicator);
    } catch (InvalidSlot e) { }

    try {
        indicator = ri.get_slot(outCallIndicatorSlotId);

        // If the RSC out call slot is not set then log this invocation.
        // If it is set that indicates the interceptor is servicing the
        // invocation of loggingService itself.  In that case do
        // nothing (to avoid infinite recursion).

        if (indicator.type().kind().equals(TCKind.tk_null)) {
        loggingService.log(ri.operation() + " " + point);
        }
    } catch (InvalidSlot e) {
        System.out.println("Exception handling not shown.");
    }
    }
}

    LoggingServiceServerORBInitializer.java

    This file creates and registers the logging service interceptor used by object servers. Even though this interceptor is meant to only log server-side interception points, it is both a client and server interceptor. The code illustrates how to avoid infinite recursion in the case where the object being called is colocated in the same ORB in which the interceptors are registered.

// LoggingServiceServerORBInitializer.java
// Copyright and License

package pi.serviceexample;

import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.PortableInterceptor.Current;
import org.omg.PortableInterceptor.CurrentHelper;
import org.omg.PortableInterceptor.ORBInitInfo;

public class LoggingServiceServerORBInitializer
    extends org.omg.CORBA.LocalObject
    implements org.omg.PortableInterceptor.ORBInitializer
{
    public void pre_init(ORBInitInfo info)
    {
    }

    public void post_init(ORBInitInfo info)
    {
    try {

        // Create and register the logging service interceptor.
        // Give that interceptor references to the NameService and
        // PICurrent to avoid further lookups (i.e., optimization).
        // More importantly, allocate and give the interceptor
        // a slot id which is will use to tell itself not to
        // log calls that the interceptor makes to the logging process.

        NamingContext nameService =
        NamingContextHelper.narrow(
                    info.resolve_initial_references("NameService"));

        Current piCurrent =
        CurrentHelper.narrow(
                info.resolve_initial_references("PICurrent"));

        int outCallIndicatorSlotId = info.allocate_slot_id();

        LoggingServiceServerInterceptor interceptor =
        new LoggingServiceServerInterceptor(nameService,
                            piCurrent,
                            outCallIndicatorSlotId);

        info.add_client_request_interceptor(interceptor);
        info.add_server_request_interceptor(interceptor);
    } catch (Throwable t) {
        System.out.println("Exception handling not shown.");
    }
    }
}

    LoggingServiceServerInterceptor.java

    This interceptor logs server side interception points, and is implemented as both a ClientRequestInterceptor and a ServerRequestInterceptor to illustrate the need to set some "out call" service context data (in addition to setting an out call slot) to avoid infinite recursion for the case noted in the description of LoggingServiceServerORBInitializer.java.

// LoggingServiceServerInterceptor.java
// Copyright and License

package pi.serviceexample;

import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.CORBA.Any;
import org.omg.CORBA.BAD_PARAM;
import org.omg.CORBA.ORB;
import org.omg.CORBA.TCKind;
import org.omg.IOP.ServiceContext;
import org.omg.PortableInterceptor.ClientRequestInterceptor;
import org.omg.PortableInterceptor.ClientRequestInfo;
import org.omg.PortableInterceptor.Current;
import org.omg.PortableInterceptor.InvalidSlot;
import org.omg.PortableInterceptor.ServerRequestInterceptor;
import org.omg.PortableInterceptor.ServerRequestInfo;

public class LoggingServiceServerInterceptor
    extends org.omg.CORBA.LocalObject
    implements ClientRequestInterceptor,
           ServerRequestInterceptor
{
    private NamingContext nameService;
    private LoggingService loggingService;
    private Current piCurrent;
    private int outCallIndicatorSlotId;
    private static final int serviceContextId = 100001;
    private static final byte[] serviceContextData = {1};

    // Returns a reference to the logging process.

    private LoggingService loggingService()
    {
    if (loggingService == null) {
        NameComponent path[] =
            { new NameComponent("LoggingService", "") };
        try {
        loggingService =
            LoggingServiceHelper.narrow(nameService.resolve(path));
        } catch (Throwable t) {
        System.out.println("Exception handling not shown.");
        }
    }
    return loggingService;
    }

    public LoggingServiceServerInterceptor(NamingContext nameService,
                       Current piCurrent,
                       int outCallIndicatorSlotId)
    {
    this.nameService = nameService;
    this.piCurrent = piCurrent;
    this.outCallIndicatorSlotId = outCallIndicatorSlotId;
    }

    //
    // Interceptor operations
    //

    public String name()
    {
    return "LoggingServiceServerInterceptor";
    }

    public void destroy()
    {
    }

    //
    // ClientRequestInterceptor operations
    //

    public void send_request(ClientRequestInfo ri)
    {

    // If the server interceptor sets the recursion slot then
    // put in the service context so the server doesn't make
    // the call again in the case where the server side interceptor
    // is colocated in the same ORB as the object being invoked.

    try {
        Any indicator = ri.get_slot(outCallIndicatorSlotId);
        if (indicator.type().kind().equals(TCKind.tk_boolean)) {
        ServiceContext serviceContext =
            new ServiceContext(serviceContextId, serviceContextData);
        ri.add_request_service_context(serviceContext, false);
        }
    } catch (InvalidSlot e) {
        System.out.println("Exception handling not shown.");
    }
    }

    public void send_poll(ClientRequestInfo ri)
    {
    }

    public void receive_reply(ClientRequestInfo ri)
    {
    }

    public void receive_exception(ClientRequestInfo ri)
    {
    }

    public void receive_other(ClientRequestInfo ri)
    {
    }

    //
    // ServerRequestInterceptor operations
    //

    public void receive_request_service_contexts(ServerRequestInfo ri)
    {
    log(ri, "receive_request_service_contexts");
    }

    public void receive_request(ServerRequestInfo ri)
    {
    log(ri, "receive_request");
    }

    public void send_reply(ServerRequestInfo ri)
    {
    log(ri, "send_reply");
    }

    public void send_exception(ServerRequestInfo ri)
    {
    log(ri, "send_exception");
    }

    public void send_other(ServerRequestInfo ri)
    {
    log(ri, "send_other");
    }

    //
    // Utilities.
    //

    public void log(ServerRequestInfo ri, String point)
    {
    // This is only relevant for the colocated example.
    // Do not attempt to log until the logging service object
    // has been bound in naming.  Otherwise the attempt to call
    // rebind on naming will call log which will fail.
    if (! ColocatedServers.colocatedBootstrapDone) {
        return;
    }

    // IMPORTANT:
    // The conditional logging of the invocation is only necessary
    // if there is a chance that the object being invoked is colocated
    // in the same ORB as this interceptor.  Otherwise the outcall to
    // the logging service can be made unconditionally.

    // Always set the recursion slot.

    Any indicator = ORB.init().create_any();
    indicator.insert_boolean(true);
    try {
        piCurrent.set_slot(outCallIndicatorSlotId, indicator);
    } catch (InvalidSlot e) {
        System.out.println("Exception handling not shown.");
    }

    // Make the out call if you have not already done so.

    try {

        // Only the presence of the service context counts.
        // The data is ignored.

        ri.get_request_service_context(serviceContextId);
    } catch (BAD_PARAM e) {
        // Recursion indicator not set so make the call.
        loggingService().log(ri.operation() + " " + point);
    }
    }
}

    LoggingServiceImpl.java

    This file is the implementation of the logging object to which the logging service interceptors send their data.

//
// Copyright and License

package pi.serviceexample;

import org.omg.CORBA.ORB;
import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.PortableServer.POAHelper;

import java.util.Properties;

class LoggingServiceImpl
    extends LoggingServicePOA
{
    public static ORB orb;

    //
    // The IDL operations.
    //

    public void log(String a1)
    {
    System.out.println(a1);
    }

    //
    // The server.
    //

    public static void main(String[] av)
    {
    try {
        if (orb == null) {
        orb = ORB.init(av, null);
        }

        POA rootPOA =  POAHelper.narrow( orb.resolve_initial_references("RootPOA"));
        rootPOA.the_POAManager().activate();

        byte[] objectId =
        rootPOA.activate_object(new LoggingServiceImpl());
        org.omg.CORBA.Object ref = rootPOA.id_to_reference(objectId);

        NamingContext nameService =
        NamingContextHelper.narrow(
                    orb.resolve_initial_references("NameService"));
        NameComponent path[] =
            { new NameComponent("LoggingService", "") };
        nameService.rebind(path, ref);

        // Only relevant for colocated example.
        ColocatedServers.colocatedBootstrapDone = true;

        System.out.println("LoggingService ready.");

        orb.run();

        } catch (Exception e) {
        e.printStackTrace();
        System.exit(-1);
        }
    System.exit(0);
    }
}

    AServiceORBInitializer.java

    The file creates and registers the AServiceInterceptor as both a client and server interceptor, creates and registers the AServiceIORInterceptor which puts a TaggedComponent into IORs, and creates a local object to be used by applications to explicitly control the services offered by AService. This local object is registered as an initial service with the ORB such that it can be obtained by clients using org.omg.CORBA.ORB.resolve_initial_references.

// AServiceORBInitializer.java
// Copyright and License

package pi.serviceexample;

import org.omg.IOP.Codec;
import org.omg.IOP.CodecFactory;
import org.omg.IOP.CodecFactoryHelper;
import org.omg.IOP.Encoding;
import org.omg.PortableInterceptor.Current;
import org.omg.PortableInterceptor.CurrentHelper;
import org.omg.PortableInterceptor.ORBInitInfo;

public class AServiceORBInitializer
    extends org.omg.CORBA.LocalObject
    implements org.omg.PortableInterceptor.ORBInitializer
{
    private AServiceImpl aServiceImpl;
    private AServiceInterceptor aServiceInterceptor;

    public void pre_init(ORBInitInfo info)
    {
    try {
        int id = info.allocate_slot_id();

        aServiceInterceptor = new AServiceInterceptor(id);

        info.add_client_request_interceptor(aServiceInterceptor);
        info.add_server_request_interceptor(aServiceInterceptor);

        // Create and register a reference to the service to be
        // used by client code.

        aServiceImpl = new AServiceImpl(id);

        info.register_initial_reference("AService", aServiceImpl);

    } catch (Throwable t) {
        System.out.println("Exception handling not shown.");
    }
    }

    public void post_init(ORBInitInfo info)
    {
    try {

        Current piCurrent =
        CurrentHelper.narrow(
            info.resolve_initial_references("PICurrent"));
        aServiceImpl.setPICurrent(piCurrent);

        CodecFactory codecFactory =
        CodecFactoryHelper.narrow(
                info.resolve_initial_references("CodecFactory"));
        Encoding encoding = new Encoding((short)0, (byte)1, (byte)2);
        Codec codec = codecFactory.create_codec(encoding);
        aServiceInterceptor.setCodec(codec);

        AServiceIORInterceptor aServiceIORInterceptor =
        new AServiceIORInterceptor(codec);
        info.add_ior_interceptor(aServiceIORInterceptor);

    } catch (Throwable t) {
        System.out.println("Exception handling not shown.");
    }
    }

}

    AServiceImpl.java

    This file contains an object that is explicitly used by client and servant code to communicate with the service. When the client calls begin() on the service, the service causes a ServiceID specific to the service to be put in the TSC PICurrent slot reserved by this service. When the client calls end() on the service, it sets the TSC slot to a non-valid value to indicate that the service is not in effect. Servants use the verify() method to determine whether the ServiceID was passed from the client side to the server side.

//
// Copyright and License

package pi.serviceexample;

import org.omg.CORBA.Any;
import org.omg.CORBA.TCKind;
import org.omg.CORBA.LocalObject;
import org.omg.CORBA.ORB;
import org.omg.PortableInterceptor.Current;
import org.omg.PortableInterceptor.InvalidSlot;

class AServiceImpl
    extends LocalObject
    implements AService
{
    private int slotId;

    private int currentServiceId = 0;

    private Current piCurrent;

    private Any NOT_IN_EFFECT;

    public AServiceImpl(int slotId)
    {
    this.slotId = slotId;
    NOT_IN_EFFECT = ORB.init().create_any();
    }

    // Package protected so the AService ORBInitializer can access this
    // non-IDL defined method.
    void setPICurrent(Current piCurrent)
    {
    this.piCurrent = piCurrent;
    }

    public void begin()
    {
    Any any = ORB.init().create_any();
    any.insert_long(++currentServiceId);
    setSlot(any);
    }

    public void end()
    {
    setSlot(NOT_IN_EFFECT);
    }

    public void verify()
    {
    try {
        Any any = piCurrent.get_slot(slotId);
        if (any.type().kind().equals(TCKind.tk_long)) {
        System.out.println("Service present: " + any.extract_long());
        } else {
        System.out.println("Service not present");
        }
    } catch (InvalidSlot e) {
        System.out.println("Exception handling not shown.");
    }
    }

    // Synchronized because two threads in the same ORB could be
    // sharing this object.
    synchronized private void setSlot(Any any)
    {
    try {
        piCurrent.set_slot(slotId, any);
    } catch (InvalidSlot e) {
        System.out.println("Exception handling not shown.");
    }
    }
}

    AServiceInterceptor.java

    This interceptor is responsible for arranging to pass the client side AService information to the service side.

    On the client side, if AService.begin() has been called, the send_request(ri) point will see the service id in the RSC slot. In this case, it inserts the value of that service id into an org.omg.CORBA.ServiceContext and adds that service context to the data to be passed along with the invocation.

    On the server side, receive_request_service_context(ri) looks for the presence of that service context. When present, it extracts the service id value from the ServiceContext and sets the RSC slot to that value. When the servant is executing, the value of that RSC slot is available in the TSC slot.

// AServiceInterceptor.java
// Copyright and License

package pi.serviceexample;

import org.omg.CORBA.Any;
import org.omg.CORBA.BAD_PARAM;
import org.omg.CORBA.ORB;
import org.omg.CORBA.TCKind;
import org.omg.IOP.Codec;
import org.omg.IOP.CodecPackage.FormatMismatch;
import org.omg.IOP.CodecPackage.TypeMismatch;
import org.omg.IOP.ServiceContext;
import org.omg.IOP.TaggedComponent;
import org.omg.PortableInterceptor.ClientRequestInterceptor;
import org.omg.PortableInterceptor.ClientRequestInfo;
import org.omg.PortableInterceptor.InvalidSlot;
import org.omg.PortableInterceptor.ServerRequestInterceptor;
import org.omg.PortableInterceptor.ServerRequestInfo;

public class AServiceInterceptor
    extends org.omg.CORBA.LocalObject
    implements ClientRequestInterceptor, ServerRequestInterceptor
{
    private int slotId;
    private Codec codec;

    private static final int serviceContextId = 1234;

    public AServiceInterceptor(int slotId)
    {
    this.slotId = slotId;
    }

    void setCodec(Codec codec)
    {
    this.codec = codec;
    }

    //
    // Interceptor operations
    //

    public String name()
    {
    return "AServiceInterceptor";
    }

    public void destroy()
    {
    }

    //
    // ClientRequestInterceptor operations
    //

    public void send_request(ClientRequestInfo ri)
    {
    //
    // See if the target object contains an ASERVICE_COMPONENT.
    //

    try {
        TaggedComponent taggedComponent =
        ri.get_effective_component(TAG_ASERVICE_COMPONENT.value);

        Any sAny = null;
        try {
        sAny = codec.decode_value(taggedComponent.component_data,
                      ASERVICE_COMPONENTHelper.type());
        } catch (TypeMismatch e) {
        System.out.println("Exception handling not shown.");
        } catch (FormatMismatch e) {
        System.out.println("Exception handling not shown.");
        }

        ASERVICE_COMPONENT aServiceComponent =
        ASERVICE_COMPONENTHelper.extract(sAny);

        //
        // Only send the service context if the target object requires it.
        //

        if (aServiceComponent.requiresAService) {
        try {
            Any any = ri.get_slot(slotId);
            if (any.type().kind().equals(TCKind.tk_long)) {
            int serviceId = any.extract_long();
            byte[] serviceContextData = {
                // Little endian to make it
                // easier to see in debugger.
                (byte)((serviceId >>>  0) &  0xFF),
                (byte)((serviceId >>>  8) &  0xFF),
                (byte)((serviceId >>> 16) &  0xFF),
                (byte)((serviceId >>> 24) &  0xFF)
            };
            ri.add_request_service_context(
                new ServiceContext(serviceContextId,
                           serviceContextData),
                false);
            }
        } catch (InvalidSlot e) {
            System.out.println("Exception handling not shown.");
        }
        }
    } catch (BAD_PARAM e) {
        // If it is not present, do nothing.
        ;
    }
    }

    public void send_poll(ClientRequestInfo ri)
    {
    }

    public void receive_reply(ClientRequestInfo ri)
    {
    }

    public void receive_exception(ClientRequestInfo ri)
    {
    }

    public void receive_other(ClientRequestInfo ri)
    {
    }

    //
    // ServerRequestInterceptor operations
    //

    public void receive_request_service_contexts(ServerRequestInfo ri)
    {
    try {
        ServiceContext serviceContext =
        ri.get_request_service_context(serviceContextId);
        byte[] data = serviceContext.context_data;
        int b1, b2, b3, b4;
        b4 = (data[0] <<  0) & 0x000000FF;
        b3 = (data[1] <<  8) & 0x0000FF00;
        b2 = (data[2] << 16) & 0x00FF0000;
        b1 = (data[3] << 24) & 0xFF000000;
        int serviceId = (b1 | b2 | b3 | b4);
        Any any = ORB.init().create_any();
        any.insert_long(serviceId);
        ri.set_slot(slotId, any);
    } catch (BAD_PARAM e) {
        // Not present means service is not in effect.
        // Do nothing.
        ;
    } catch (InvalidSlot e) {
        System.out.println("Exception handling not shown.");
    }
    }

    public void receive_request(ServerRequestInfo ri)
    {
    }

    public void send_reply(ServerRequestInfo ri)
    {
    }

    public void send_exception(ServerRequestInfo ri)
    {
    }

    public void send_other(ServerRequestInfo ri)
    {
    }
}

    AServiceIORInterceptor.java

    This file adds a TaggedComponent to IORs.

// AServiceIORInterceptor.java
// Copyright and License

package pi.serviceexample;

import org.omg.CORBA.Any;
import org.omg.CORBA.LocalObject;
import org.omg.CORBA.ORB;
import org.omg.IOP.TaggedComponent;
import org.omg.IOP.Codec;
import org.omg.IOP.CodecPackage.InvalidTypeForEncoding;
import org.omg.PortableInterceptor.IORInfo;
import org.omg.PortableInterceptor.IORInterceptor;

public class AServiceIORInterceptor
    extends org.omg.CORBA.LocalObject
    implements IORInterceptor
{
    private Codec codec;

    public AServiceIORInterceptor(Codec codec)
    {
    this.codec = codec;
    }

    //
    // Interceptor operations
    //

    public String name()
    {
    return "AServiceInterceptor";
    }

    public void destroy()
    {
    }

    //
    // IOR Interceptor operations
    //

    public void establish_components(IORInfo info)
    {
    //
    // Note: typically, rather than just inserting a tagged component
    // this interceptor would check info.get_effective_policy(int)
    // to determine if a tagged component reflecting that policy
    // should be added to the IOR.  That is not shown in this example.
    //

    ASERVICE_COMPONENT aServiceComponent = new ASERVICE_COMPONENT(true);
    Any any = ORB.init().create_any();
    ASERVICE_COMPONENTHelper.insert(any, aServiceComponent);
    byte[] value = null;
    try {
        value = codec.encode_value(any);
    } catch (InvalidTypeForEncoding e) {
        System.out.println("Exception handling not shown.");
    }
    TaggedComponent taggedComponent =
        new TaggedComponent(TAG_ASERVICE_COMPONENT.value, value);
    info.add_ior_component(taggedComponent);
    }

}

    ArbitaryObjectImpl.java

    This file is an implementation and server for the ArbitraryObject IDL interface. The implementations of the IDL interface operations explicitly call the AServiceImpl.verify() method to illustrate the end-to-end passing of data from the client (via AService.begin()) to the servant.

// ArbitaryObjectImpl.java
// Copyright and License

package pi.serviceexample;

import org.omg.CORBA.ORB;
import org.omg.CORBA.ORBPackage.InvalidName;
import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.PortableServer.POAHelper;

import java.util.Properties;

class ArbitraryObjectImpl
    extends ArbitraryObjectPOA
{
    public static ORB orb;

    private AService aService;

    //
    // The IDL operations.
    //

    public String arbitraryOperation1(String a1)
    {
    verifyService();
    return "I got this from the client: " + a1;
    }

    public void arbitraryOperation2 (int a1)
    {
    verifyService();
    }

    public void arbitraryOperation3(String a1)
    throws ArbitraryObjectException
    {
    verifyService();
    if (a1.equals("throw exception")) {
        throw new ArbitraryObjectException("because you told me to");
    }
    }

    private void verifyService()
    {
    getAService().verify();
    }

    private AService getAService()
    {
    // Only look up the service once, then cache it.

    if (aService == null) {
        try {
        aService =
            AServiceHelper.narrow(
                    orb.resolve_initial_references("AService"));
        } catch (InvalidName e) {
        System.out.println("Exception handling not shown.");
        }
    }
    return aService;
    }

    //
    // The server.
    //

    public static void main(String[] av)
    {
    try {
        if (orb == null) {
        Properties props = new Properties();
        props.put("org.omg.PortableInterceptor.ORBInitializerClass."
              + "pi.serviceexample.AServiceORBInitializer",
              "");
        props.put("org.omg.PortableInterceptor.ORBInitializerClass."
              + "pi.serviceexample.LoggingServiceServerORBInitializer",
              "");
        orb = ORB.init(av, props);
        }

        POA rootPOA =  POAHelper.narrow( orb.resolve_initial_references("RootPOA"));
        // Create a POA so the IOR interceptor executes.
        POA childPOA = rootPOA.create_POA("childPOA", null, null);
        childPOA.the_POAManager().activate();

        byte[] objectId =
        childPOA.activate_object(new ArbitraryObjectImpl());
        org.omg.CORBA.Object ref = childPOA.id_to_reference(objectId);

        NamingContext nameService =
        NamingContextHelper.narrow(
                    orb.resolve_initial_references("NameService"));
        NameComponent path[] =
            { new NameComponent("ArbitraryObject", "") };
        nameService.rebind(path, ref);

        System.out.println("ArbitaryObject ready.");

        orb.run();

        } catch (Exception e) {
        e.printStackTrace();
        System.exit(-1);
        }
    System.exit(0);
    }
}

    Client.java

    This is a client that calls methods on ArbitraryObject. It makes some of those calls within the context of AService and some outside of its context. It is unaware of the existence of the logging interceptor (except that it explicitly registers the LoggingServerClientORBInitializer as noted above).

// Client.java
// Copyright and License

package pi.serviceexample;

import org.omg.CORBA.ORB;
import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;

import java.util.Properties;

public class Client
{
    public static void main(String av[])
    {
        try {
        Properties props = new Properties();
        props.put("org.omg.PortableInterceptor.ORBInitializerClass."
              + "pi.serviceexample.AServiceORBInitializer",
              "");
        props.put("org.omg.PortableInterceptor.ORBInitializerClass."
              + "pi.serviceexample.LoggingServiceClientORBInitializer",
              "");
        ORB orb = ORB.init(av, props);

        //
        // The client obtains a reference to a service.
        // The client does not know the service is implemented
        // using interceptors.
        //

        AService aService =
        AServiceHelper.narrow(
                orb.resolve_initial_references("AService"));

        //
        // The client obtains a reference to some object that
        // it will invoke.
        //

        NamingContext nameService =
        NamingContextHelper.narrow(
                    orb.resolve_initial_references("NameService"));
        NameComponent arbitraryObjectPath[] =
            { new NameComponent("ArbitraryObject", "") };
        ArbitraryObject arbitraryObject =
        ArbitraryObjectHelper.narrow(nameService.resolve(arbitraryObjectPath));

        //
        // The client begins the service so that invocations of
        // any object will be done with that service in effect.
        //

        aService.begin();

        arbitraryObject.arbitraryOperation1("one");
        arbitraryObject.arbitraryOperation2(2);

        //
        // The client ends the service so that further invocations
        // of any object will not be done with that service in effect.
        //

        aService.end();

        // This invocation is not serviced by aService since
        // it is outside the begin/end.
        arbitraryObject.arbitraryOperation3("just return");

        aService.begin();
        try {
        arbitraryObject.arbitraryOperation3("throw exception");
        throw new RuntimeException("should not see this");
        } catch (ArbitraryObjectException e) {
        // Expected in this example, so do nothing.
        }
        aService.end();

        } catch (Exception e) {
            e.printStackTrace();
        System.exit(-1);
        }
    System.out.println("Client done.");
    System.exit(0);
    }
}

    ColocatedServers.java

    This is a server which runs both ArbitraryObject and LoggingService in the same ORB. This means that these objects are colocated.

    The server is created this way in order to exercise the code in LoggingServiceServerInterceptor that illustrates when interceptors make out calls to objects colocated in the same ORB extra steps must be taken to avoid infinite recursion.

// ColocatedServers.java
// Copyright and License

package pi.serviceexample;

import org.omg.CORBA.ORB;
import java.util.Properties;

public class ColocatedServers
{
    public static ORB orb;

    public static boolean colocatedBootstrapDone = false;

    public static void main (String[] av)
    {
    try {

        //
        // Share an ORB between objects servers.
        //

        Properties props = new Properties();
        props.put("org.omg.PortableInterceptor.ORBInitializerClass."
              + "pi.serviceexample.AServiceORBInitializer",
              "");
        props.put("org.omg.PortableInterceptor.ORBInitializerClass."
              + "pi.serviceexample.LoggingServiceServerORBInitializer",
              "");
        ORB orb = ORB.init(av, props);
        ArbitraryObjectImpl.orb = orb;
        LoggingServiceImpl.orb = orb;

        //
        // Start both object servers.
        //

        ServerThread ServerThread = new ServerThread(av);
        ServerThread.start();
        ArbitraryObjectImpl.main(av);
    } catch (Exception e) {
        e.printStackTrace();
        System.exit(-1);
    }
    }
}

class ServerThread extends Thread
{
    String[] av;
    ServerThread (String[] av)
    {
    this.av = av;
    }
    public void run ()
    {
    LoggingServiceImpl.main(av);
    }
}

Compiling and running the application

The example code, which contains the logging example and the service example, may be compiled and run using a Makefile such as that shown below:

# Makefile for the Example Files
# Copyright and License

JAVA_HOME=/path_to_J2SE_installation

CLASSPATH=.

JAVAC=$(JAVA_HOME)/bin/javac
JAVA=$(JAVA_HOME)/bin/java

ORB_INITIAL_PORT=1050

IDLJ=$(JAVA_HOME)/bin/idlj
IDLJ_FLAGS=-fall -td $(CLASSPATH) -verbose

ORBD=${JAVA_HOME}/bin/orbd -ORBInitialPort ${ORB_INITIAL_PORT}

build:
        $(IDLJ) $(IDLJ_FLAGS) serviceexample.idl
        $(JAVAC) -d $(CLASSPATH) *.java
        $(JAVAC) pi/serviceexample/*.java

runorbd:
        $(ORBD)

runloggingservice:
        $(JAVA) -classpath $(CLASSPATH) pi.serviceexample.LoggingServiceImpl \
                -ORBInitialPort ${ORB_INITIAL_PORT}

runarbitraryobject:
        $(JAVA) -classpath $(CLASSPATH) pi.serviceexample.ArbitraryObjectImpl \
                -ORBInitialPort ${ORB_INITIAL_PORT}

runcolocatedservers:
        $(JAVA) -classpath $(CLASSPATH) pi.serviceexample.ColocatedServers \
                -ORBInitialPort ${ORB_INITIAL_PORT}

runclient:
        $(JAVA) -classpath $(CLASSPATH) pi.serviceexample.Client \
                -ORBInitialPort ${ORB_INITIAL_PORT}

clean:
        rm -rf pi
        rm -rf orb.db

# Order of steps:
# Build:     clean build
# Remote:    runorbd runloggingservice runarbitraryobjectimpl runclient
# Colocated: runorbd runcolocatedservers runclient

The following steps show how to build and run the example on the Solaris operating system using the above Makefile. From the command prompt, run these commands as shown. The % symbol is used as a reminder that these are commands that are to be run from the command prompt.

  1. % make clean
  2. % make build
  3. % make runorbd &
  4. % make runloggingservice &
  5. % make runarbitraryobject &
  6. % make runclient

    After this step, you will see output such as this:

      resolve send_request
resolve receive_reply
arbitraryOperation1 send_request
Service present: 1
arbitraryOperation1 receive_reply
arbitraryOperation2 send_request
Service present: 1
arbitraryOperation2 receive_other
arbitraryOperation3 send_request
Service not present
arbitraryOperation3 receive_reply
arbitraryOperation3 send_request
Service present: 2
arbitraryOperation3 receive_exception
Client done.

  7. % jobs

    After this step, you will see output such as this:

      [1]   Running                 make runorbd &
[2]-  Running                 make runloggingservice &
[3]+  Running                 make runarbitraryobject &

  8. % kill %2 %3
  9. % make runcolocatedservers &
  10. % make runclient

    After this step, you will see output such as this:

      log receive_request_service_contexts
log receive_request
resolve send_request
log send_reply
log receive_request_service_contexts
log receive_request
resolve receive_reply
log send_reply
log receive_request_service_contexts
log receive_request
arbitraryOperation1 send_request
log send_reply
arbitraryOperation1 receive_request_service_contexts
arbitraryOperation1 receive_request
Service present: 1
arbitraryOperation1 send_reply
log receive_request_service_contexts
log receive_request
arbitraryOperation1 receive_reply
log send_reply
log receive_request_service_contexts
log receive_request
arbitraryOperation2 send_request
log send_reply
arbitraryOperation2 receive_request_service_contexts
arbitraryOperation2 receive_request
log receive_request_service_contexts
Service present: 1
arbitraryOperation2 send_reply
log receive_request
arbitraryOperation2 receive_other
log send_reply
log receive_request_service_contexts
log receive_request
arbitraryOperation3 send_request
log send_reply
arbitraryOperation3 receive_request_service_contexts
arbitraryOperation3 receive_request
Service not present
arbitraryOperation3 send_reply
log receive_request_service_contexts
log receive_request
arbitraryOperation3 receive_reply
log send_reply
log receive_request_service_contexts
log receive_request
arbitraryOperation3 send_request
log send_reply
arbitraryOperation3 receive_request_service_contexts
arbitraryOperation3 receive_request
Service present: 2
arbitraryOperation3 send_exception
log receive_request_service_contexts
log receive_request
arbitraryOperation3 receive_exception
log send_reply
Client done.

  11. % jobs

    After this step, you will see output such as this:

      [1]-  Running                 make runorbd &
[4]+  Running                 make runcolocatedservers &

  12. % kill %1 %4
  13. % make clean

See Also:
ORBInitInfo
org.omg.PortableInterceptor package.
Portable Interceptors Specification at ptc/2001-08-31

Consult the Java Developer's Forum on Distributed Computing at http://forum.java.sun.com/ for more information on Portable Interceptors.


Portable Object Adapter (POA)

What is the Portable Object Adapter (POA)?

An object adapter is the mechanism that connects a request using an object reference with the proper code to service that request. The Portable Object Adapter, or POA, is a particular type of object adapter that is defined by the CORBA specification. The POA is designed to meet the following goals:

  • Allow programmers to construct object implementations that are portable between different ORB products.
  • Provide support for objects with persistent identities.
  • Provide support for transparent activation of objects.
  • Allow a single servant to support multiple object identities simultaneously.

This document presents an introduction to using the POA with the Java 2 Platform, Standard Edition. For a more complete description of the POA, see Chapter 11 of the CORBA 2.3.1 Specification.

Creating and Using the POA

The steps for creating and using a POA will vary according to the specific application being developed. The following steps generally occur during the POA life cycle:

  1. Get the root POA
  2. Define the POA's policies
  3. Create the POA
  4. Activate the POAManager
  5. Activate the servants, which may include activating the Tie
  6. Create the object reference from the POA

Each step is described in more detail in the sections that follow.

Step 1: Get the root POA

The first step is to get the first POA, which is called the rootPOA. The root POA is managed by the ORB and provided to the application using the ORB initialization interface under the initial object name "RootPOA".

An example of code that will get the root POA object and cast it to a POA is:

      ORB orb = ORB.init( args, null );
      POA rootPOA = POAHelper.narrow(orb.resolve_initial_references("RootPOA"));
Step 2: Define the POA's Policies

The Portable Object Adapter (POA) is designed to provide an object adapter that can be used with multiple ORB implementations with no rewriting needed to deal with different vendors' implementations.

The POA is also intended to allow persistent objects -- at least, from the client's perspective. That is, as far as the client is concerned, these objects are always alive, and maintain data values stored in them, even though physically, the server may have been restarted many times.

The POA allows the object implementer a lot more control over the object's identity, state, storage, and life cycle. You can create a POA without defining any policies and the default values will be used. The root POA has the following policies by default:

  • Thread Policy: ORB_CTRL_MODEL
  • Lifespan Policy: TRANSIENT
  • Object Id Uniqueness Policy: UNIQUE_ID
  • Id Assignment Policy: SYSTEM_ID
  • Servant Retention Policy: RETAIN
  • Request Processing Policy: USE_ACTIVE_OBJECT_MAP_ONLY
  • Implicit Activation Policy: IMPLICIT_ACTIVATION

The following code snippet shows how policies are set in the RMI-IIOP (with POA) example:

      Policy[] tpolicy = new Policy[3];
      tpolicy[0] = rootPOA.create_lifespan_policy(
        LifespanPolicyValue.TRANSIENT );
      tpolicy[1] = rootPOA.create_request_processing_policy(
        RequestProcessingPolicyValue.USE_ACTIVE_OBJECT_MAP_ONLY );
      tpolicy[2] = rootPOA.create_servant_retention_policy(
        ServantRetentionPolicyValue.RETAIN);

Each policy is discussed briefly in the following topics. For more information on POA policies, refer to Chapter 11, Portable Object Adapter of the CORBA/IIOP 2.3.1 Specification at http://www.omg.org/docs/formal/99-10-07.pdf

Thread Policy

This policy specifies the threading model used with the created POA. The default is ORB_CTRL_MODEL.

The ThreadPolicyValue can have the following values:

  • ORB_CTRL_MODEL - The ORB is responsible for assigning requests for an ORB-controlled POA to threads.
  • SINGLE_THREAD_MODEL - Requests for a single-threaded POA are processed sequentially. (NOTE: This policy is not supported in the ORB shipped with Sun's J2SE v.1.4.1 or higher).

Lifespan Policy

This policy specifies the lifespan of the objects implemented in the created POA. The default is TRANSIENT.

The LifespanPolicyValue can have the following values:

  • TRANSIENT - The objects implemented in the POA cannot outlive the POA instance in which they are first created.
  • PERSISTENT - The objects implemented in the POA can outlive the process in which they are first created.

Object Id Uniqueness Policy

This policy specifies whether the servants activated in the created POA must have unique object identities. The default is UNIQUE_ID.

The IdUniquenessPolicyValue can have the following values:

  • UNIQUE_ID - Servants activated with that POA support exactly one Object Id.
  • MULTIPLE_ID - A servant activated with that POA may support one or more Object Ids.

Id Assignment Policy

This policy specifies whether Object Ids in the created POA are generated by the application or by the ORB. The default is SYSTEM_ID.

The IdAssignmentPolicyValue can have the following values:

  • USER_ID - Objects created with that POA are assigned Object Ids only by the application.
  • SYSTEM_ID - Objects created with that POA are assigned a unique object id by the POA. If the POA also has the PERSISTENT policy, assigned Object Ids must be unique across all instantiations of the same POA.

Servant Retention Policy

This policy specifies whether the created POA retains active servants in an Active Object Map. The default is RETAIN.

The ServantRetentionPolicyValue can have the following values.

  • RETAIN - to indicate that the POA will retain active servants in its Active Object Map.
  • NON_RETAIN - to indicate Servants are not retained by the POA.

Request Processing Policy

This policy specifies how requests are processed by the created POA. The default is USE_ACTIVE_OBJECT_MAP_ONLY.

The RequestProcessingPolicyValue can have the following values:

  • USE_ACTIVE_OBJECT_MAP_ONLY - If the object ID is not found in the Active Object Map, an OBJECT_NOT_EXIST exception is returned to the client. The RETAIN policy is also required.
  • USE_DEFAULT_SERVANT - If the object ID is not found in the Active Object Map or the NON_RETAIN policy is present, and a default servant has been registered with the POA using the set_servant operation, the request is dispatched to the default servant.
  • USE_SERVANT_MANAGER - If the object ID is not found in the Active Object Map or the NON_RETAIN policy is present, and a servant manager has been registered with the POA using the set_servant_manager operation, the servant manager is given the opportunity to locate or activate a servant or raise an exception.

Implicit Activation Policy

This policy specifies whether implicit activation of servants is supported in the created POA. The default value is IMPLICIT_ACTIVATION.

The ImplicitActivationPolicyValue can have the following values:

  • IMPLICIT_ACTIVATION - Indicates implicit activation of servants. This requires SYSTEM_ID and RETAIN policies to be set.
  • NO_IMPLICIT_ACTIVATION - Indicates no implicit servant activation.
Step 3: Create the POA

Creating a new POA allows the application developer to declare specific policy choices for the new POA and to provide a different adapter activator and servant manager (these are callback objects used by the POA to activate POAs on demand and activate servants). Creating new POAs also allows the application developer to partition the name space of objects, as Object Ids are interpreted relative to a POA. Finally, by creating new POAs, the developer can independently control request processing for multiple sets of objects.

A POA is created as a child of an existing POA using the create_POA operation on the parent POA. To create a new POA, pass in the following information:

  • Name of the POA. The POA is given a name that must be unique with respect to all other POAs with the same parent. In the following example, the POA is named childPOA.
  • POA Manager. Specify the POA Manager to be associated with the new POA. If, as is shown in the following example, null is passed for this parameter, a new POA Manager will be created. The user can also choose to pass the POA Manager of another POA.
  • Policy List. Specify the policy list to be associated with the POA to control its behavior. In the following example, a persistent lifespan policy has already been defined for this POA.

The following code snippet shows how the POA is created in the Hello World: Persistent Server example.

    // Create a POA by passing the Persistent Policy
POA persistentPOA = rootPOA.create_POA("childPOA", null,
   persistentPolicy );
Step 4: Activate the POAManager

Each POA object has an associated POAManager object that controls the processing state of the POAs with which it is associated, such as whether requests to the POA are queued or discarded. The POAManager can also deactivate the POA. A POA Manager may be associated with one or more POA objects.

The POAManager can have the following states:

  • Holding - In this state, associated POAs will queue incoming requests.
  • Active - In this state, associated POAs will start processing requests.
  • Discarding - In this state, associated POAs will discard incoming requests.
  • Inactive - In this state, associated POAs will reject the requests that have not begun executing as well as as any new requests.

The POAManagerOperations javadocs contain more information on these states.

POA Managers are not automatically activated when they are created. The following code snippet shows how the POAManager is activated in the Hello World: Persistent Server example. If the POA Manager is not activated in this way, all calls to the Servant will hang because, by default, the POA Manager is in the HOLD state.

            // Activate PersistentPOA's POAManager. Without this step,
            // all calls to Persistent Server will hang because POAManager
            // will be in the 'HOLD' state.
            persistentPOA.the_POAManager().activate( );

Step 5: Activate the servants

The following information is quoted from section 11.2.5 of the CORBA Specification.

At any point in time, a CORBA object may or may not be associated with an active servant.

If the POA has the RETAIN policy, the servant and its associated Object Id are entered into the Active Object Map of the appropriate POA. This type of activation can be accomplished in one of the following ways.

  • The server application itself explicitly activates individual objects (via the activate_object or activate_object_with_id operations).

  • The server application instructs the POA to activate objects on demand by having the POA invoke a user-supplied servant manager. The server application registers this servant manager with set_servant_manager.

  • Under some circumstances (when the IMPLICIT_ACTIVATION policy is also in effect and the language binding allows such an operation), the POA may implicitly activate an object when the server application attempts to obtain a reference for a servant that is not already active (that is, not associated with an Object Id).

If the USE_DEFAULT_SERVANT policy is also in effect, the server application instructs the POA to activate unknown objects by having the POA invoke a single servant no matter what the Object Id is. The server application registers this servant with set_servant.

If the POA has the NON_RETAIN policy, for every request, the POA may use either a default servant or a servant manager to locate an active servant. From the POA's point of view, the servant is active only for the duration of that one request. The POA does not enter the servant-object association into the Active Object Map.

When using RMI-IIOP technology, your implementations use delegation (known as the Tie model) to associate your implementation with the interface. When you create an instance of your implementation, you also need to create a Tie object to associate it with a CORBA interface. The following code snippet shows how to activate the Tie, if the POA policy is USE_ACTIVE_OBJECT_MAP_ONLY. This sample code is from the RMI-IIOP with POA example.

    _HelloImpl_Tie tie = (_HelloImpl_Tie)Util.getTie( helloImpl );
String helloId = "hello";
byte[] id = helloId.getBytes();
tPOA.activate_object_with_id( id, tie );

The CORBA Specification discusses creating object references (section 11.2.4), activating objects (section 11.2.5), and processing requests (section 11.2.6) in more detail than is done in this document. Please refer to the CORBA 2.3.1 Specification for more information.

Step 6: Create the object reference

Object references are created in servers. Once created, they may be exported to clients. Object references encapsulate object identity information and information required by the ORB to identify and locate the server and the POA with which the object is associated. References are created in the following ways:

  • Explicitly activate a servant and associate it with an object reference.

    The following example is from Hello World: Persistent Server. This example uses the servant_to_reference operation to map an activated servant to its corresponding object reference.

      // Resolve Root Naming context and bind a name for the
// servant.
org.omg.CORBA.Object obj = orb.resolve_initial_references(
  "NameService" );
NamingContextExt rootContext = NamingContextExtHelper.narrow( obj );

NameComponent[] nc = rootContext.to_name(
  "PersistentServerTutorial" );
rootContext.rebind( nc, persistentPOA.servant_to_reference(
  servant ) );

  • Server application directly creates a reference.

    The following example is from the RMI-IIOP with POA example. In this example, the following code directly creates a reference. In doing so, they bring the abstract object into existence, but do not associate it with an active servant.

      // Publish the object reference using the same object id
// used to activate the Tie object.
Context initialNamingContext = new InitialContext();
initialNamingContext.rebind("HelloService",
tPOA.create_reference_with_id(id,
  tie._all_interfaces(tPOA,id)[0]) );

  • Server application causes a servant to implicitly activate itself.

    The behavior can occur only if the POA has been created with the IMPLICIT_ACTIVATION policy, which is the default behavior.

Once an reference is created in the server, it can be made available to clients. For more information on creating object references and exporting to clients, please refer to section 11.2.4 of the CORBA 2.3.1 Specification for more information.

Adapter Activators

  • For an example application that uses Adapter Activators, see Using Adapter Activators.

An adapter activator is optional. You would use an adapter activator if POAs need to be created during request processing. If all needed POAs are created when the application is executed, an adapter activator is not required.

An adapter activator supplies a POA with the ability to create child POAs on demand, as a side-effect of receiving a request that names the child POA (or one of its children), or when the find_POA method is called with an activate parameter value of TRUE. The ORB will invoke an operation on an adapter activator when a request is received for a child POA that does not currently exist. The adapter activator can then create the required POA on demand.

A request must be capable of conveying the Object Id of the target object as well as the identification of the POA that created the target object reference. When a client issues a request, the ORB first locates an appropriate server (perhaps starting one if needed) and then it locates the appropriate POA within that server.

If the POA does not exist in the server process, the application has the opportunity to re-create the required POA by using an adapter activator. An adapter activator is a user-implemented object that can be associated with a POA. It is invoked by the ORB when a request is received for a non-existent child POA. The adapter activator has the opportunity to create the required POA. If it does not, the client receives the ADAPTER_NONEXISTENT exception.

Once the ORB has located the appropriate POA, it delivers the request to that POA. The further processing of that request depends both upon the policies associated with that POA as well as the object's current state of activation.

For more information on Adapter Activators, please refer to section 11.3.3 of the CORBA 2.3.1 Specification or the AdapterActivatorOperations API documentation.

Servant Managers

Servant Managers are optional. You would use a servant manager to allow the POA to activate servants on demand when a request for an inactive object is received. If your server loads all objects when it starts up, you do not need a servant manager.

A servant manager is a callback object that the application developer can associate with a POA. The ORB will invoke operations on servant managers to activate servants on demand, and to deactivate servants. Servant managers are responsible for managing the association of an object reference (as characterized by its Object Id value) with a particular servant, and for determining whether an object reference exists or not. Each servant manager type contains two operations, the first called to find and return a servant and the second to deactivate a servant. The operations differ according to the amount of information usable for their situation.

To use servant managers, the USE_SERVANT_MANAGER policy must be set. Once set, the type of servant manager used in a particular situation depends on other policies in the POA. The two types of servant managers are:

  • ServantActivator

    When the POA has the RETAIN policy, it uses servant managers that are ServantActivators.

    This type is typically used to activate persistent objects.

    • For an example that uses Servant Activators, see Using Servant Activators.

  • ServantLocator

    When the POA has the NON_RETAIN policy, it uses servant managers that are ServantLocators. Because the POA knows that the servant returned by this servant manager will be used only for a single request, it can supply extra information to the servant manager's operations and the servant manager's pair of operations may be able to cooperate to do something different than a ServantActivator. When the POA uses the ServantLocator interface, immediately after performing the operation invocation on the servant returned by preinvoke, the POA will invoke postinvoke on the servant manager, passing the ObjectId value and the Servant value as parameters (among others). This feature may be used to force every request for objects associated with a POA to be mediated by the servant manager.

    This type is typically used to activate transient objects.

    • For an example that uses Servant Locators see Using Servant Locators.

For more information on Servant Managers, please refer to section 11.3.4 of the CORBA 2.3.1 Specification.

POA Q&A

Is POAManager.activate() required for a newly created POA?

POAManager.activate() is required for a newly created POA if a null is passed for the POAManager parameter to POA::createPOA . If null is passed, a new POAManager is created and associated with the created POA. In this case, POAManager.activate() is needed.

To control several POAs with the same POAManager, you would:

  1. Create a POA or use the rootPOA
  2. Obtain the POA's manager via POA::the_POAManager
  3. Pass the POAManager to subsequent createPOA calls

There is no implicit relationship between the Root POA's POAManager and other POAs unless explicitly programmed by the programmer as shown above.

For more information, read section 11.3.2 of the CORBA specification, formal/99-10-07.

For more information

For more information about the Portable Object Adapter, read Chapter 11 of the CORBA/IIOP v.2.3.1 Specification from the Object Management Group's Web site. At the time of this writing, the specification can be found at http://www.omg.org/docs/formal/99-10-07.pdf.

Java IDL Home


Programming Guide

Getting Started: Hello World has a transient server

Example: Persistent Server

Example: POA-Tie Server-Side Model

Example: ImplBase Server-Side Model

Example: Interoperable Naming Service

Home Concepts Programming Reference Tutorial
Copyright © 1996-2004 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.


Reference

All packages that begin with org.omg are part of the Java IDL API. Those of most interest are:

  • package org.omg.CORBA - provides the mapping of the OMG CORBA APIs to the Java[tm] programming language
  • package org.omg.CosNaming - provides the naming service for Java IDL
  • package org.omg.PortableServer - provides classes and interfaces for making the server side of your applications portable across multivendor ORBs
  • package org.omg.PortableInterceptor - provides a mechanism to register ORB hooks through which ORB services can intercept the normal flow of execution of the ORB
  • package org.omg.DynamicAny - provides classes and interfaces to enable Any values to be dynamically interpreted (traversed) and constructed through DynAny objects
  • org.omg.CORBA.ORB - provides APIs for the CORBA Object Request Broker features

Mapping IDL to Java

Home Concepts Programming Reference Tutorial
Copyright © 1996-2004 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.


Sample code

 << /TABLE="/TABLE">

Sample Code for Hello.idl

This document shows the code generated by the IDL-to-Java compiler in accordance with the IDL to Java Language Mapping Specification (for compliance details refer to the compliance document), as well as sample client and server applications.

For a detailed description of the code listed here, consult the introductory tutorial, Getting Started with Java IDL.

Hello.idl, the interface definition

The following file, Hello.idl, is written in the OMG Interface Definition Language, and describes a CORBA object whose sayHello() operation returns a string and whose shutdown() method shuts down the ORB. OMG IDL is a purely declarative language designed for specifying programming-language-independent operational interfaces for distributed applications. The IDL can be mapped to a variety of programming languages. The IDL mapping for Java is summarized in IDL to Java Language Mapping Summary.

To learn more about OMG IDL Syntax and Semantics, link to the OMG Web site, and read Chapter 3 of the CORBA Specification.

Hello.idl

module HelloApp
{
  interface Hello
  {
  string sayHello();
  oneway void shutdown();
  };
};

Generated Files

The idlj compiler uses the IDL-to-Java mapping to convert IDL interface definitions to corresponding Java interfaces, classes, and methods, which you can then use to implement your client and server code. The following files are generated when Hello.idl is compiled with the IDL-to-Java compiler, using the following command:

       idlj -fall Hello.idl

Hello.java, the signature interface

The signature interface file, Hello.java extends org.omg.portable.IDLEntity, org.omg.CORBA.Object, and the operations interface, HelloOperations. The signature interface is used as the signature type in method declarations when interfaces of the specified type are used in other interfaces. From the client's point of view, an object reference for a CORBA Hello object implements this interface.

Note: The Stub implements the Hello interface, where it generates code for each method to marshall the arguments, invoke the method, and then unmarshall the arguments.

    HelloApp/Hello.java

    package HelloApp;

/**
* HelloApp/Hello.java
* Generated by the IDL-to-Java compiler (portable), version "3.0"
* from Hello.idl
* Thursday, March 22, 2001 2:17:15 PM PST
*/

public interface Hello extends HelloOperations, org.omg.CORBA.Object,
org.omg.CORBA.portable.IDLEntity
{
} // interface Hello

HelloOperations.java, the operations interface

The Java operations interface, HelloOperations.java, is used in the server-side mapping and as a mechanism for providing optimized calls for co-located clients and server. The server developer provides implementation for the methods indicated by the operations interface.

This interface contains the methods sayHello() and shutdown(). The IDL-to-Java mapping puts all of the operations defined on the IDL interface into this file, which is shared by both the stubs and skeletons.

Note: The server writer usually extends HelloPOA and provides implementation for the methods provided by the operations interface.

    HelloApp/HelloOperations.java

    package HelloApp;

/**
* HelloApp/HelloOperations.java
* Generated by the IDL-to-Java compiler (portable), version "3.0"
* from Hello.idl
* Thursday, March 22, 2001 2:17:15 PM PST
*/

public interface HelloOperations
{
  String sayHello ();
  void Shutdown ();
} // interface HelloOperations

HelloHelper.java, the Helper class

The Java class HelloHelper provides auxiliary functionality, notably the narrow() method required to cast CORBA object references to their proper types. The Helper class is responsible for reading and writing the data type to CORBA streams, and inserting and extracting the data type from Anys. The Holder class delegates to the methods in the Helper class for reading and writing.

    HelloApp/HelloHelper.java

    package HelloApp;

/**
* HelloApp/HelloHelper.java
* Generated by the IDL-to-Java compiler (portable), version "3.0"
* from Hello.idl
* Thursday, March 22, 2001 2:17:15 PM PST
*/

abstract public class HelloHelper
{
  private static String  _id = "IDL:HelloApp/Hello:1.0";

  public static void insert (org.omg.CORBA.Any a, HelloApp.Hello that)
  {
    org.omg.CORBA.portable.OutputStream out = a.create_output_stream ();
    a.type (type ());
    write (out, that);
    a.read_value (out.create_input_stream (), type ());
  }

  public static HelloApp.Hello extract (org.omg.CORBA.Any a)
  {
    return read (a.create_input_stream ());
  }

  private static org.omg.CORBA.TypeCode __typeCode = null;
  synchronized public static org.omg.CORBA.TypeCode type ()
  {
    if (__typeCode == null)
    {
      __typeCode = org.omg.CORBA.ORB.init ().create_interface_tc
(HelloApp.HelloHelper.id (), "Hello");
    }
    return __typeCode;
  }

  public static String id ()
  {
    return _id;
  }

  public static HelloApp.Hello read (org.omg.CORBA.portable.InputStream istream)
  {
    return narrow (istream.read_Object (_HelloStub.class));
  }

  public static void write (org.omg.CORBA.portable.OutputStream ostream,
HelloApp.Hello value)
  {
    ostream.write_Object ((org.omg.CORBA.Object) value);
  }

  public static HelloApp.Hello narrow (org.omg.CORBA.Object obj)
  {
    if (obj == null)
      return null;
    else if (obj instanceof HelloApp.Hello)
      return (HelloApp.Hello)obj;
    else if (!obj._is_a (id ()))
      throw new org.omg.CORBA.BAD_PARAM ();
    else
    {
      org.omg.CORBA.portable.Delegate delegate =
((org.omg.CORBA.portable.ObjectImpl)obj)._get_delegate ();
      HelloApp._HelloStub stub = new HelloApp._HelloStub ();
      stub._set_delegate(delegate);
      return stub;
    }
  }

}

HelloHolder.java, the Holder class

The Java class called HelloHolder holds a public instance member of type Hello. Whenever the IDL type is an out or an inout parameter, the Holder class is used. It provides operations for org.omg.CORBA.portable.OutputStream and org.omg.CORBA.portable.InputStream arguments, which CORBA allows, but which do not map easily to Java's semantics. The Holder class delegates to the methods in the Helper class for reading and writing. It implements org.omg.CORBA.portable.Streamable.

    HelloApp/HelloHolder.java

    package HelloApp;

/**
* HelloApp/HelloHolder.java
* Generated by the IDL-to-Java compiler (portable), version "3.0"
* from Hello.idl
* Thursday, March 22, 2001 2:17:15 PM PST
*/

public final class HelloHolder implements org.omg.CORBA.portable.Streamable
{
  public HelloApp.Hello value = null;

  public HelloHolder ()
  {
  }

  public HelloHolder (HelloApp.Hello initialValue)
  {
    value = initialValue;
  }

  public void _read (org.omg.CORBA.portable.InputStream i)
  {
    value = HelloApp.HelloHelper.read (i);
  }

  public void _write (org.omg.CORBA.portable.OutputStream o)
  {
    HelloApp.HelloHelper.write (o, value);
  }

  public org.omg.CORBA.TypeCode _type ()
  {
    return HelloApp.HelloHelper.type ();
  }

}

_HelloStub.java, the client stub

The Java class _HelloStub is the stub file for the client-side mapping. It extends org.omg.CORBA.portable.ObjectImpl and implements the Hello.java interface.

    HelloApp/_HelloStub.java

    package HelloApp;

/**
* HelloApp/_HelloStub.java
* Generated by the IDL-to-Java compiler (portable), version "3.0"
* from Hello.idl
* Thursday, March 22, 2001 2:17:15 PM PST
*/

public class _HelloStub extends org.omg.CORBA.portable.ObjectImpl implements
HelloApp.Hello
{

  public String sayHello ()
  {
    org.omg.CORBA.portable.InputStream _in = null;
    try {
       org.omg.CORBA.portable.OutputStream _out = _request ("sayHello", true);
       _in = _invoke (_out);
       String __result = _in.read_string ();
       return __result;
    } catch (org.omg.CORBA.portable.ApplicationException _ex) {
       _in = _ex.getInputStream ();
       String _id = _ex.getId ();
       throw new org.omg.CORBA.MARSHAL (_id);
    } catch (org.omg.CORBA.portable.RemarshalException _rm) {
       return sayHello ();
    } finally {
        _releaseReply (_in);
    }
  } // sayHello

  public void Shutdown ()
  {
    org.omg.CORBA.portable.InputStream _in = null;
    try {
       org.omg.CORBA.portable.OutputStream _out = _request ("Shutdown", false);
       _in = _invoke (_out);
    } catch (org.omg.CORBA.portable.ApplicationException _ex) {
       _in = _ex.getInputStream ();
       String _id = _ex.getId ();
       throw new org.omg.CORBA.MARSHAL (_id);
    } catch (org.omg.CORBA.portable.RemarshalException _rm) {
       Shutdown ();
    } finally {
        _releaseReply (_in);
    }
  } // Shutdown

  // Type-specific CORBA::Object operations
  private static String[] __ids = {
    "IDL:HelloApp/Hello:1.0"};

  public String[] _ids ()
  {
    return (String[])__ids.clone ();
  }

  private void readObject (java.io.ObjectInputStream s) throws java.io.IOException
  {
     String str = s.readUTF ();
     String[] args = null;
     java.util.Properties props = null;
     org.omg.CORBA.Object obj = org.omg.CORBA.ORB.init (args,
props).string_to_object
(str);
     org.omg.CORBA.portable.Delegate delegate = ((org.omg.CORBA.portable.ObjectImpl)
obj)._get_delegate ();
     _set_delegate (delegate);
  }

  private void writeObject (java.io.ObjectOutputStream s) throws java.io.IOException
  {
     String[] args = null;
     java.util.Properties props = null;
     String str = org.omg.CORBA.ORB.init (args, props).object_to_string (this);
     s.writeUTF (str);
  }
} // class _HelloStub

HelloPOA.java, the server skeleton

The Java class HelloImplPOA is the skeleton file for the server-side mapping, providing basic CORBA functionality for the server. It extends org.omg.PortableServer.Servant, and implements the InvokeHandler interface and the HelloOperations interface. The server class, HelloServant, extends HelloPOA.

    HelloApp/HelloPOA.java

    package HelloApp;

/**
* HelloApp/HelloPOA.java
* Generated by the IDL-to-Java compiler (portable), version "3.0"
* from Hello.idl
* Thursday, March 22, 2001 2:17:15 PM PST
*/

public abstract class HelloPOA extends org.omg.PortableServer.Servant
 implements HelloApp.HelloOperations, org.omg.CORBA.portable.InvokeHandler
{

  // Constructors

  private static java.util.Hashtable _methods = new java.util.Hashtable ();
  static
  {
    _methods.put ("sayHello", new java.lang.Integer (0));
    _methods.put ("Shutdown", new java.lang.Integer (1));
  }

  public org.omg.CORBA.portable.OutputStream _invoke (String method,
                                org.omg.CORBA.portable.InputStream in,
                                org.omg.CORBA.portable.ResponseHandler rh)
  {
    org.omg.CORBA.portable.OutputStream out = null;
    java.lang.Integer __method = (java.lang.Integer)_methods.get (method);
    if (__method == null)
      throw new org.omg.CORBA.BAD_OPERATION (0,
org.omg.CORBA.CompletionStatus.COMPLETED_MAYBE);

    switch (__method.intValue ())
    {
       case 0:  // HelloApp/Hello/sayHello
       {
         String __result = null;
         __result = this.sayHello ();
         out = rh.createReply();
         out.write_string (__result);
         break;
       }

       case 1:  // HelloApp/Hello/Shutdown
       {
         this.Shutdown ();
         out = rh.createReply();
         break;
       }

       default:
         throw new org.omg.CORBA.BAD_OPERATION (0,
org.omg.CORBA.CompletionStatus.COMPLETED_MAYBE);
    }

    return out;
  } // _invoke

  // Type-specific CORBA::Object operations
  private static String[] __ids = {
    "IDL:HelloApp/Hello:1.0"};

  public String[] _all_interfaces (org.omg.PortableServer.POA poa, byte[] objectId)
  {
    return (String[])__ids.clone ();
  }

  public Hello _this()
  {
    return HelloHelper.narrow(
    super._this_object());
  }

  public Hello _this(org.omg.CORBA.ORB orb)
  {
    return HelloHelper.narrow(
    super._this_object(orb));
  }

} // class HelloPOA

Completing the application

To complete the application, the developer must write the client and server code.

HelloServer.java, a transient server

The example server consists of two classes, the servant and the server. The servant, HelloImpl, is the implementation of the Hello IDL interface; each Hello instance is implemented by a HelloImpl instance. The servant is a subclass of HelloPOA, which is generated by the idlj compiler from the example IDL.

The servant contains one method for each IDL operation, in this example, the sayHello() and shutdown() methods. Servant methods are just like ordinary Java methods; the extra code to deal with the ORB, with marshaling arguments and results, and so on, is provided by the skeleton.

This example shows the code for a transient server. For a "Hello World" application with a persistent server, see Hello World with a Persistent Server.

The following code is written by the developer.

    HelloServer.java

    // HelloServer.java
// Copyright and License
import HelloApp.*;
import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.CORBA.*;
import org.omg.PortableServer.*;
import org.omg.PortableServer.POA;

import java.util.Properties;

class HelloImpl extends HelloPOA {
  private ORB orb;

  public void setORB(ORB orb_val) {
    orb = orb_val;
  }

  // implement sayHello() method
  public String sayHello() {
    return "\nHello world !!\n";
  }

  // implement shutdown() method
  public void shutdown() {
    orb.shutdown(false);
  }
}

public class HelloServer {

  public static void main(String args[]) {
    try{
      // create and initialize the ORB
      ORB orb = ORB.init(args, null);

      // get reference to rootpoa & activate the POAManager
      POA rootpoa = POAHelper.narrow(orb.resolve_initial_references("RootPOA"));
      rootpoa.the_POAManager().activate();

      // create servant and register it with the ORB
      HelloImpl helloImpl = new HelloImpl();
      helloImpl.setORB(orb);

      // get object reference from the servant
      org.omg.CORBA.Object ref = rootpoa.servant_to_reference(helloImpl);
      Hello href = HelloHelper.narrow(ref);

      // get the root naming context
      // NameService invokes the name service
      org.omg.CORBA.Object objRef =
          orb.resolve_initial_references("NameService");
      // Use NamingContextExt which is part of the Interoperable
      // Naming Service (INS) specification.
      NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef);

      // bind the Object Reference in Naming
      String name = "Hello";
      NameComponent path[] = ncRef.to_name( name );
      ncRef.rebind(path, href);

      System.out.println("HelloServer ready and waiting ...");

      // wait for invocations from clients
      orb.run();
    }

      catch (Exception e) {
        System.err.println("ERROR: " + e);
        e.printStackTrace(System.out);
      }

      System.out.println("HelloServer Exiting ...");

  }
}

HelloClient.java, the client application

This example shows a Java client application. You could write a CORBA client as a servlet, a JSP, an applet, etc.

    HelloClient.java

    // Copyright and License

import HelloApp.*;
import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.CORBA.*;

public class HelloClient
{
  static Hello helloImpl;

  public static void main(String args[])
    {
      try{
        // create and initialize the ORB
    ORB orb = ORB.init(args, null);

        // get the root naming context
        org.omg.CORBA.Object objRef =
        orb.resolve_initial_references("NameService");
        // Use NamingContextExt instead of NamingContext. This is
        // part of the Interoperable naming Service.
        NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef);

        // resolve the Object Reference in Naming
        String name = "Hello";
        helloImpl = HelloHelper.narrow(ncRef.resolve_str(name));

        System.out.println("Obtained a handle on server object: " + helloImpl);
        System.out.println(helloImpl.sayHello());
        helloImpl.shutdown();

    } catch (Exception e) {
          System.out.println("ERROR : " + e) ;
      e.printStackTrace(System.out);
      }
    }

}

Compiling and Running a Java CORBA application

For the details of compiling and running a Java CORBA application, refer to Building and Running the Hello World Application.

Java
Copyright © 2001-2004 Sun Microsystems, Inc. All Rights Reserved.

Sun

Java Software


The "Hello World" Example

Java IDL: The "Hello World" Example

Using the POA, a persistent server, and a persistent naming service

This document is a high-level overview of how to create a complete CORBA (Common Object Request Broker Architecture) application using IDL (Interface Definiton Language) to define interfaces and the Java IDL compiler to generate stubs and skeletons. For more information on the development process, and a more detailed tutorial on creating a CORBA application using IDL, link to Getting Started with Java IDL: The Hello World Tutorial. You can also create CORBA applications by defining the interfaces in the Java programming language. For more information and a tutorial on this development process, link to Java RMI-IIOP documentation.

For more information on transient vs. persistent servers, please refer to the document Developing Servers.

This document contains:

  • The IDL for a simple "Hello World" program
  • A persistent server that creates an object and publishes it with the naming service using the default server-side implementation (POA)
  • A servant that implements each of the IDL interfaces
  • An application client that knows the object's name, retrieves a reference for it from the naming service, and invokes the object
  • Instructions for compiling and running the example

Defining the Interface (PersistentHello.idl)

The first step to creating a CORBA application is to specify all of your objects and their interfaces using the OMG's Interface Definition Language (IDL). IDL has a syntax similar to C++ and can be used to define modules, interfaces, data structures, and more. The IDL can be mapped to a variety of programming languages. The IDL mapping for Java is summarized in IDL to Java Language Mapping Summary.

The following code is written in the OMG IDL, and describes a CORBA object whose sayHello() operation returns a string and whose shutdown() method shuts down the ORB. To learn more about OMG IDL Syntax and Semantics, link to the OMG Web site, and read Chapter 3 of the CORBA Specification.

PersistentHello.idl

    module Persistent {
    interface Hello {
        string sayHello( );
        oneway void shutdown();
    };
};
NOTE: When writing code in OMG IDL, do not use an interface name as the name of a module. Doing so runs the risk of getting inconsistent results when compiling with tools from different vendors, thereby jeopardizing the code's portability. For example, code containing the same names could be compiled with the IDL to Java compiler from Sun Microsystems and get one result. The same code compiled with another vendor's IDL to Java compiler could produce a different result.

To complete the application, you simply provide the server (PersistentServer.java), servant (PersistentHelloServant.java), and client (PersistentClient.java) implementations.

Implementing the Server (PersistentServer.java)

The example server, PersistentServer, has the server's main() method, which:

  • Creates and initializes an ORB instance
  • Creates a servant
  • Gets a reference to the root POA
  • Creates the policy that makes the server persistent
  • Creates a persistent POA by passing in the persistent policy
  • Activates the persistent POA's POAManager
  • Associates the servant with the persistent POA
  • Gets a CORBA object reference for the root naming context in which to register the new CORBA object
  • Narrows the object reference to a naming context
  • Registers the new object in the naming context under the name "PersistentServerTutorial"
  • Waits for invocations of the new object from the client

This example provides an example of a persistent object server. For an example of the "Hello World" program with a transient object server, see Hello World with a Transient Server. For more discussion of CORBA servers, see Developing Servers.

PersistentServer.java

    // PersistentServer.java
// Copyright and License
import java.util.Properties;
import org.omg.CORBA.Object;
import org.omg.CORBA.ORB;
import org.omg.CosNaming.NameComponent;
import org.omg.CosNaming.NamingContextExt;
import org.omg.CosNaming.NamingContextExtHelper;
import org.omg.CORBA.Policy;
import org.omg.PortableServer.POA;
import org.omg.PortableServer.*;
import org.omg.PortableServer.Servant;

public class PersistentServer {

    public static void main( String args[] ) {
        Properties properties = System.getProperties();
        properties.put( "org.omg.CORBA.ORBInitialHost",
            "localhost" );
        properties.put( "org.omg.CORBA.ORBInitialPort",
            "1050" );

        try {
            // Step 1: Instantiate the ORB
            ORB orb = ORB.init(args, properties);

            // Step 2: Instantiate the servant
            PersistentHelloServant servant = new PersistentHelloServant(orb);

            // Step 3 : Create a POA with Persistent Policy
            // *******************
            // Step 3-1: Get the rootPOA
            POA rootPOA = POAHelper.narrow(orb.resolve_initial_references("RootPOA"));
            // Step 3-2: Create the Persistent Policy
            Policy[] persistentPolicy = new Policy[1];
            persistentPolicy[0] = rootPOA.create_lifespan_policy(
                LifespanPolicyValue.PERSISTENT);
            // Step 3-3: Create a POA by passing the Persistent Policy
            POA persistentPOA = rootPOA.create_POA("childPOA", null,
                persistentPolicy );
            // Step 3-4: Activate PersistentPOA's POAManager, Without this
            // All calls to Persistent Server will hang because POAManager
            // will be in the 'HOLD' state.
            persistentPOA.the_POAManager().activate( );
            // ***********************

            // Step 4: Associate the servant with PersistentPOA
            persistentPOA.activate_object( servant );

            // Step 5: Resolve RootNaming context and bind a name for the
            // servant.
            // NOTE: If the Server is persistent in nature then using Persistent
            // Name Service is a good choice. Even if ORBD is restarted the Name
            // Bindings will be intact. To use Persistent Name Service use
            // 'NameService' as the key for resolve_initial_references() when
            // ORBD is running.
            org.omg.CORBA.Object obj = orb.resolve_initial_references(
                "NameService" );
            NamingContextExt rootContext = NamingContextExtHelper.narrow( obj );

            NameComponent[] nc = rootContext.to_name(
                "PersistentServerTutorial" );
            rootContext.rebind( nc, persistentPOA.servant_to_reference(
                servant ) );

            // Step 6: We are ready to receive client requests
            orb.run();
        } catch ( Exception e ) {
            System.err.println( "Exception in Persistent Server Startup " + e );
        }
    }
}

Implementing the Servant (PersistentHelloServant.java)

The example servant, PersistentHelloServant, is the implementation of the Hello IDL interface; each Hello instance is implemented by a PersistentHelloServant instance. The servant is a subclass of HelloPOA, which is generated by the idlj compiler from the example IDL. The servant contains one method for each IDL operation, in this example, the sayHello() and shutdown() methods. Servant methods are just like ordinary Java methods; the extra code to deal with the ORB, with marshaling arguments and results, and so on, is provided by the skeleton.

PersistentHelloServant.java

    // PersistentHelloServant.java
// Copyright and License
import org.omg.CORBA.ORB;

public class PersistentHelloServant extends Persistent.HelloPOA {
    private ORB orb;

    public PersistentHelloServant( ORB orb ) {
        this.orb = orb;
    }

    /**
     *  sayHello() method implementation returns a simple message.
     */
    public String sayHello( ) {
        return "Hello From Persistent Server...";
    }

    /**
     *  shutdown() method shuts down the Persistent Server.
     *  See NOTE below.
     */
    public void shutdown( ) {
        orb.shutdown( false );
    }
}

Note: For convenience of presentation in this example, the shutdown() method is included as part of the servant. This has been done in order to demonstrate the persistence of the server in this example. This is not a recommended programming convention for the following reasons:

  • If the orb.shutdown() method is called with parameter true (meaning "wait for completion") within the implementation of a remote method, the ORB will hang in a deadlock. Other threads can invoke orb.shutdown() without deadlock.
  • If you have multiple servants associated with the ORB, using the shutdown(false) method by one of them will make all of them unavailable.
  • The orb.shutdown(false) method should be called as part of the SERVER code under more controlled circumstances.

Implementing the Client Application (PersistentClient.java)

The example application client that follows:

  • Creates and initializes an ORB.
  • Resolves the PersistentHelloServant by using the Interoperable Naming Service's (INS) corbaname url. The URL locates the Naming Service running on host localhost and listening on port 1050. When located, it resolves "PersistentServerTutorial" from that Naming Service.
  • Invokes the object's sayHello() and shutdown() operations and prints the result. In this example, the client calls the sayHello() method every 3 seconds, then shuts down the server. The next call from the client will restart the server (because of the persistent lifespan of the server).

PersistentClient.java

// Copyright and License

import java.util.Properties;
import org.omg.CORBA.ORB;
import org.omg.CORBA.OBJ_ADAPTER;
import org.omg.CosNaming.NamingContext;
import org.omg.CosNaming.NamingContextHelper;
import org.omg.CosNaming.NameComponent;
import org.omg.PortableServer.POA;

import Persistent.HelloHelper;
import Persistent.Hello;

public class PersistentClient {

    public static void main(String args[]) {

        try {
            // Step 1: Instantiate the ORB
            ORB orb = ORB.init(args, null);

            // Step 2: Resolve the PersistentHelloServant by using INS's
            // corbaname url. The URL locates the NameService running on
            // localhost and listening on 1050 and resolve
            // 'PersistentServerTutorial' from that NameService
            org.omg.CORBA.Object obj = orb.string_to_object(
                "corbaname::localhost:1050#PersistentServerTutorial");

            Hello hello = HelloHelper.narrow( obj );

            // Step 3: Call the sayHello() method every 60 seconds and shutdown
            // the server. Next call from the client will restart the server,
            // because it is persistent in nature.
            while( true ) {
                System.out.println( "Calling Persistent Server.." );
                String helloFromServer = hello.sayHello();
                System.out.println("Message From Persistent Server: " +
                    helloFromServer );
                System.out.println( "Shutting down Persistent Server.." );
                hello.shutdown( );
                Thread.sleep( 60000 );
            }
        } catch ( Exception e ) {
            System.err.println( "Exception in PersistentClient.java..." + e );
            e.printStackTrace( );
        }
    }
}

Building and Running Hello World

Despite its simple design, the Hello World program lets you learn and experiment with all the tasks required to develop almost any CORBA program that uses static invocation.

This example requires a naming service, which is a CORBA service that allows CORBA objects to be named by means of binding a name to an object reference. The name binding may be stored in the naming service, and a client may supply the name to obtain the desired object reference. This example uses orbd, which contains a Persistent Naming Service and a Server Manager.

When running this example, remember that, when using Solaris software, you must become root to start a process on a port under 1024. For this reason, we recommend that you use a port number greater than or equal to 1024. The following instructions assume you can set the -ORBInitialPort option to use port 1050 for the Java IDL Object Request Broker Daemon, orbd. You can substitute a different port if necessary.

To run this client-server application on your development machine:

  1. Create or download the IDL and Java files for this example.
  2. Change to the directory that contains the file PersistentHello.idl.

  3. Run the IDL-to-Java compiler, idlj, on the IDL file to create stubs and skeletons. This step assumes that you have included the path to the java/bin directory in your path.
      idlj  -fall -td . -verbose  PersistentHello.idl

    You must use the -fall option with the idlj compiler to generate both client and server-side bindings. This command line will generate the default server-side bindings, which assumes the POA Inheritance server-side model. For more information on the idlj options, link to IDL-to-Java compiler options.

    The idlj compiler generates a number of files. The actual number of files generated depends on the options selected when the IDL file is compiled. The generated files provide standard functionality, so you can ignore them until it is time to deploy and run your program. The files generated by the idlj compiler for PersistentHello.idl, with the -fall command line option, are:

    • HelloPOA.java

      This abstract class is the stream-based server skeleton, providing basic CORBA functionality for the server. It extends org.omg.PortableServer.Servant , and implements the InvokeHandler interface and the HelloOperations interface. The server class PersistentHelloServant extends HelloPOA.

    • _HelloStub.java

      This class is the client stub, providing CORBA functionality for the client. It extends org.omg.CORBA.portable.ObjectImpl and implements the Hello interface.

    • Hello.java

      This interface contains the Java version of our IDL interface. The Hello.java interface extends org.omg.CORBA.Object, providing standard CORBA object functionality. It also extends the HelloOperations interface and org.omg.CORBA.portable.IDLEntity.

    • HelloHelper.java

      This class provides auxiliary functionality, notably the narrow() method required to cast CORBA object references to their proper types.The Helper class is responsible for reading and writing the data type to CORBA streams, and inserting and extracting the data type from Anys. The Holder class delegates to the methods in the Helper class for reading and writing.

    • HelloHolder.java

      This final class holds a public instance member of type Hello. Whenever the IDL type is an out or an inout parameter, the Holder class is used. It provides operations for org.omg.CORBA.portable.OutputStream and org.omg.CORBA.portable.InputStream arguments, which CORBA allows, but which do not map easily to Java's semantics. The Holder class delegates to the methods in the Helper class for reading and writing. It implements org.omg.CORBA.portable.Streamable.

    • HelloOperations.java

      This interface contains the methods sayHello() and shutdown(). The IDL-to-Java mapping puts all of the operations defined on the IDL interface into this file, which is shared by both the stubs and skeletons.

  4. Compile the .java files, including the stubs and skeletons (which are in the directory Persistent). This step assumes the java/bin directory is included in your path.
       javac *.java Persistent/*.java
  5. Start orbd.

    To start orbd, enter:

      orbd -ORBInitialPort 1050 -serverPollingTime 200&          (Unix operating system)

  start orbd  -ORBInitialPort 1050 -serverPollingTime 200&   (Windows operating system)

    Note that 1050 is the port on which you want the name server to run. The -ORBInitialPort argument is a required command-line argument. Note that when using Solaris software, you must become root to start a process on a port under 1024. For this reason, we recommend that you use a port number greater than or equal to 1024.

    The -serverPollingTime 200 argument specifies how often ORBD checks for the health of persistent servers registered via servertool. The default value is 1,000 ms. We are setting this parameter to 200 ms in this example to enable more frequent monitoring of failures. In the event that a server failure is detected, the server will be restarted to its proper state.

  6. Start the Hello server:

    To register a persistent server with the ORBD, the server must be started using servertool, which is a command-line interface for application programmers to register, unregister, startup, and shutdown a persistent server. When the servertool is started, you must specify the port and the host (if different) on which orbd is executing.

    To start the Hello server,

    • Start the servertool from the command line of another terminal window or command prompt as follows:

        servertool -ORBInitialPort 1050        (Unix operating system)

  start servertool -ORBInitialPort 1050  (Windows operating system)

      Make sure the name server (orbd) port is the same as in the previous step, for example, -ORBInitialPort 1050. The servertool must be started on the same port as the name server.

      The servertool command line interface appears:

    • Register the PersistentServer from the servertool prompt, as shown below. Type the information in one long string without returns.

        servertool  > register -server PersistentServer -applicationName s1
                -classpath path_to_server_class_files

      The servertool registers the server, assigns it the name of "s1", and displays its server id.

  7. Run the client application from the command line of another terminal window or command prompt:

      java -classpath . PersistentClient

    The terminal window or DOS prompt displays the following messages:

    Calling Persistent Server..
Message From Persistent Server: Hello From Persistent Server...
Shutting down Persistent Server..
Calling Persistent Server..
Message From Persistent Server: Hello From Persistent Server...
Shutting down Persistent Server..

In this example, the client invokes the sayHello() method every minute and then kills the persistent server, which will be automatically restarted the next time the client invokes the sayHello() method.

When you have finished this tutorial, be sure to shut down or kill the name server (orbd). To do this from a DOS prompt, select the window that is running the server and enter Ctrl+C to shut it down. To do this from a Unix shell, type pkill ordb from a terminal window. The server will continue to wait for invocations until it is explicitly stopped.

Running the Hello World Application on Two Machines describes one way of distributing the simple application across two machines - a client and a server.

Running the Example on Unix Using a Makefile

The following code provides an example of a Makefile that can be used to run this example. Change the location of JAVA_HOME to the location where you installed J2SE 5.0. Change the CLASSPATH variable to the directory where you have created the sample application. This example is for the Unix operating system, modify accordingly if using the Windows operating system.

#Change to location of your Java SE installation.
JAVA_HOME=/home/user_name/j2sdk1.5.0/

CLASSPATH=.

JAVAC=$(JAVA_HOME)/bin/javac
JAVA=$(JAVA_HOME)/bin/java

ORB_INITIAL_PORT=1050
ORB_INITIAL_HOST=localhost
ORB_ACTIVATION_PORT=1049

#Change ClassPath based on where your PersistentServer is located.
export CLASSPATH=<path to server class files>
IDLJ :=$(JAVA_HOME)/bin/idlj

ORB_PROPS=-Dorg.omg.CORBA.ORBInitialHost=$(ORB_INITIAL_HOST)
-Dorg.omg.CORBA.ORBInitialPort=$(ORB_INITIAL_PORT)

IDLJ_FLAGS=-fall -td . -verbose

ORBD=${JAVA_HOME}/bin/orbd -ORBInitialPort ${ORB_INITIAL_PORT}
-port ${ORB_ACTIVATION_PORT} -serverPollingTime 200
-serverStartupDelay 1000

SERVERTOOL=${JAVA_HOME}/bin/servertool

all: clean build run

build: stubs

stubs:
    $(IDLJ) $(IDLJ_FLAGS) PersistentHello.idl
    $(JAVAC) *.java
    $(JAVAC) Persistent/*.java

runc:
    $(JAVA) -classpath . PersistentClient

runorbd:
    $(ORBD)

# Enter the following command in servertool to register server:
# (without the # sign)
# register -server PersistentServer -applicationName s1
-classpath path_to_server_class_files

servertool:
    $(SERVERTOOL) -ORBInitialPort $(ORB_INITIAL_PORT)

clean:
    rm -rf Persistent
    rm -rf *.class

To run the application using the Makefile, enter the following commands:

  1. gnumake build
  2. gnumake runorbd
  3. gnumake runservertool
  4. In servertool, enter the commands as shown above
  5. gnumake runc

Java IDL Home


The "Hello World" Example

Java IDL: The "Hello World" Example

POA model, transient server

This document is a high-level overview of how to create a complete CORBA (Common Object Request Broker Architecture) application using IDL (Interface Definiton Language) to define interfaces and the Java IDL compiler to generate stubs and skeletons. For more information on the development process, and a more detailed tutorial on creating a CORBA application using IDL, link to Getting Started with Java IDL: The Hello World Tutorial. You can also create CORBA application by defining the interfaces in the Java programming language. For more information and a tutorial on this development process, link to Java RMI-IIOP documentation.

In this release of Java SE, the server-side implementation generated by the idlj compiler is the Portable Servant Inheritance Model, also known as the POA model. The POA, or Portable Object Adapter, is discussed in more detail in Portable Object Adapter. This document presents a sample application created using the default behavior of the idlj compiler, which uses a POA server-side model.

CORBA supports at least two different server-side mappings for implementing an IDL interface:

  • The Inheritance Model

    Using the Inheritance Model, you implement the IDL interface using an implementation class that also extends the compiler-generated skeleton.

    Inheritance models include:

    • The OMG-standard, POA. Given an interface My defined in My.idl, the file MyPOA.java is generated by the idlj compiler. You must provide the implementation for My and it must inherit from MyPOA, a stream-based skeleton that extends org.omg.PortableServer.Servant , which serves as the base class for all POA servant implementations.

    • ImplBase. Given an interface My defined in My.idl, the file _MyImplBase.java is generated. You must provide the implementation for My and it must inherit from _MyImplBase.

      NOTE: ImplBase is deprecated in favor of the POA model, but is provided to allow compatibility with servers written in J2SE 1.3 and prior. We do not recommend creating new servers using this nonstandard model.

  • The Delegation Model

    Using the Delegation Model, you implement the IDL interface using two classes:

    • An IDL-generated Tie class that inherits from the compiler-generated skeleton, but delegates all calls to an implementation class.
    • A class that implements the IDL-generated operations interface (such as HelloOperations), which defines the IDL function.

    The Delegation model is also known as the Tie model, or the Tie Delegation model. It inherits from either the POA or ImplBase compiler-generated skeleton, so the models will be described as POA/Tie or ImplBase/Tie models in this document.

This tutorial presents the POA Inheritance model for server-side implementation. For tutorials using the other server-side implementations, see the following documents:

  • Java IDL: The "Hello World" Example with the POA/Tie Server-Side Model

    The Tie Model is a delegation model. Use the idlj compiler to first generate server-side bindings. Then, run the idlj compiler a second time with the with the -fallTie option to generate Tie model server-side bindings. For the interface Hello, HelloPOATie.java is one of the generated files. The constructor to HelloPOATie takes a delegate or a delegate and a poa. You must provide the implementation for delegate and/or the poa, but the delegate does not have to inherit from any other class, only the interface HelloOperations. For more information, refer to the IDL to Java Language Mapping Specification.

    You might want to use the Tie model instead of the typical Inheritance model if your implementation must inherit from some other implementation. Java allows any number of interface inheritance, but there is only one slot for class inheritance. If you use the inheritance model, that slot is used up . By using the Tie Model, that slot is freed up for your own use. The drawback is that it introduces a level of indirection: one extra method call occurs when invoking a method.

  • Java IDL: The "Hello World" Example with the ImplBase Server-Side Model

    The ImplBase server-side model is an Inheritance Model, as is the POA model. Use the idlj compiler with the -oldImplBase flag to generate server-side bindings that are compatible with versions of Java IDL prior to J2SE 1.4. Given an interface Hello defined in Hello.idl, the file _HelloImplBase.java is generated. You must provide the implementation for Hello and it must inherit from _HelloImplBase.

    Note that using the -oldImplBase flag is non-standard: these APIs are being deprecated. You would use this flag ONLY for compatibility with existing servers written in J2SE 1.3 or earlier. In that case, you would need to modify an existing MAKEFILE to add the -oldImplBase flag to the idlj compiler, otherwise POA-based server-side mappings will be generated.

This document contains:

  • The example code for this application
  • The IDL for a simple "Hello World" program
  • A server that creates an object and publishes it with the naming service using the default server-side implementation (POA)
  • An application client that knows the object's name, retrieves a reference for it from the naming service, and invokes the object
  • Instructions for compiling and running the example

To create this example, create a directory named hello/ where you develop sample applications and create the files in this directory, or download the example code and unzip it into your sample applications directory.

Defining the Interface (Hello.idl)

The first step to creating a CORBA application is to specify all of your objects and their interfaces using the OMG's Interface Definition Language (IDL). IDL has a syntax similar to C++ and can be used to define modules, interfaces, data structures, and more. The IDL can be mapped to a variety of programming languages. The IDL mapping for Java is summarized in IDL to Java Language Mapping Summary.

The following code is written in the OMG IDL, and describes a CORBA object whose sayHello() operation returns a string and whose shutdown() method shuts down the ORB. To learn more about OMG IDL Syntax and Semantics, link to the OMG Web site, and read Chapter 3 of the CORBA Specification.

Hello.idl

module HelloApp
{
  interface Hello
  {
  string sayHello();
  oneway void shutdown();
  };
};
NOTE: When writing code in OMG IDL, do not use an interface name as the name of a module. Doing so runs the risk of getting inconsistent results when compiling with tools from different vendors, thereby jeopardizing the code's portability. For example, code containing the same names could be compiled with the IDL to Java compiler from Sun Microsystems and get one result. The same code compiled with another vendor's IDL to Java compiler could produce a different result.

To complete the application, you simply provide the server (HelloServer.java) and client (HelloClient.java) implementations.

Implementing the Server (HelloServer.java)

The example server consists of two classes, the servant and the server. The servant, HelloImpl, is the implementation of the Hello IDL interface; each Hello instance is implemented by a HelloImpl instance. The servant is a subclass of HelloPOA, which is generated by the idlj compiler from the example IDL. The servant contains one method for each IDL operation, in this example, the sayHello() and shutdown() methods. Servant methods are just like ordinary Java methods; the extra code to deal with the ORB, with marshaling arguments and results, and so on, is provided by the skeleton.

The HelloServer class has the server's main() method, which:

  • Creates and initializes an ORB instance
  • Gets a reference to the root POA and activates the POAManager
  • Creates a servant instance (the implementation of one CORBA Hello object) and tells the ORB about it
  • Gets a CORBA object reference for a naming context in which to register the new CORBA object
  • Gets the root naming context
  • Registers the new object in the naming context under the name "Hello"
  • Waits for invocations of the new object from the client

This example provides an example of a transient object server. For an example of the "Hello World" program with a persistent object server, see Example 2: Hello World with Persistent State. For more discussion of CORBA servers, see Developing Servers.

For more discussion of the code, see the detailed tutorial topic Getting Started with Java IDL: Developing a Hello World Server.

HelloServer.java

// HelloServer.java
// Copyright and License
import HelloApp.*;
import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.CORBA.*;
import org.omg.PortableServer.*;
import org.omg.PortableServer.POA;

import java.util.Properties;

class HelloImpl extends HelloPOA {
  private ORB orb;

  public void setORB(ORB orb_val) {
    orb = orb_val;
  }

  // implement sayHello() method
  public String sayHello() {
    return "\nHello world !!\n";
  }

  // implement shutdown() method
  public void shutdown() {
    orb.shutdown(false);
  }
}

public class HelloServer {

  public static void main(String args[]) {
    try{
      // create and initialize the ORB
      ORB orb = ORB.init(args, null);

      // get reference to rootpoa & activate the POAManager
      POA rootpoa = POAHelper.narrow(orb.resolve_initial_references("RootPOA"));
      rootpoa.the_POAManager().activate();

      // create servant and register it with the ORB
      HelloImpl helloImpl = new HelloImpl();
      helloImpl.setORB(orb);

      // get object reference from the servant
      org.omg.CORBA.Object ref = rootpoa.servant_to_reference(helloImpl);
      Hello href = HelloHelper.narrow(ref);

      // get the root naming context
      // NameService invokes the name service
      org.omg.CORBA.Object objRef =
          orb.resolve_initial_references("NameService");
      // Use NamingContextExt which is part of the Interoperable
      // Naming Service (INS) specification.
      NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef);

      // bind the Object Reference in Naming
      String name = "Hello";
      NameComponent path[] = ncRef.to_name( name );
      ncRef.rebind(path, href);

      System.out.println("HelloServer ready and waiting ...");

      // wait for invocations from clients
      orb.run();
    }

      catch (Exception e) {
        System.err.println("ERROR: " + e);
        e.printStackTrace(System.out);
      }

      System.out.println("HelloServer Exiting ...");

  }
}

Implementing the Client Application (HelloClient.java)

The example application client that follows:

  • Creates and initializes an ORB
  • Obtains a reference to the root naming context
  • Looks up "Hello" in the naming context and receives a reference to that CORBA object
  • Invokes the object's sayHello() and shutdown() operations and prints the result

For more discussion of the details of the code, link to Getting Started with Java IDL: Developing a Client Application.

HelloClient.java

// Copyright and License

import HelloApp.*;
import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.CORBA.*;

public class HelloClient
{
  static Hello helloImpl;

  public static void main(String args[])
    {
      try{
        // create and initialize the ORB
    ORB orb = ORB.init(args, null);

        // get the root naming context
        org.omg.CORBA.Object objRef =
        orb.resolve_initial_references("NameService");
        // Use NamingContextExt instead of NamingContext. This is
        // part of the Interoperable naming Service.
        NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef);

        // resolve the Object Reference in Naming
        String name = "Hello";
        helloImpl = HelloHelper.narrow(ncRef.resolve_str(name));

        System.out.println("Obtained a handle on server object: " + helloImpl);
        System.out.println(helloImpl.sayHello());
        helloImpl.shutdown();

    } catch (Exception e) {
          System.out.println("ERROR : " + e) ;
      e.printStackTrace(System.out);
      }
    }

}

Building and Running Hello World

Despite its simple design, the Hello World program lets you learn and experiment with all the tasks required to develop almost any CORBA program that uses static invocation. Static invocation, which uses a client stub for the invocation and a server skeleton for the service being invoked, is used when the interface of the object is known at compile time. If the interface is not known at compile time, dynamic invocation must be used.

This example requires a naming service, which is a CORBA service that allows CORBA objects to be named by means of binding a name to an object reference. The name binding may be stored in the naming service, and a client may supply the name to obtain the desired object reference. The two options for Naming Services shipped with this release of Java SE include orbd, a daemon process containing a Bootstrap Service, a Transient Naming Service, a Persistent Naming Service, and a Server Manager, and tnameserv, a transient naming service that is provided for backward compatibility. This example uses orbd.

When running this example, remember that, when using Solaris software, you must become root to start a process on a port under 1024. For this reason, we recommend that you use a port number greater than or equal to 1024. The -ORBInitialPort option is used to override the default port number in this example. The following instructions assume you can use port 1050 for the Java IDL Object Request Broker Daemon, orbd. You can substitute a different port if necessary. When running these examples on a Windows machine, subtitute a backslash (\) in path names.

To run this client-server application on your development machine:

  1. Change to the directory that contains the file Hello.idl.

  2. Run the IDL-to-Java compiler, idlj, on the IDL file to create stubs and skeletons. This step assumes that you have included the path to the java/bin directory in your path.
      idlj -fall  Hello.idl

    You must use the -fall option with the idlj compiler to generate both client and server-side bindings. This command line will generate the default server-side bindings, which assumes the POA Inheritance server-side model. For more information on the idlj options, link to IDL-to-Java compiler options.

    The idlj compiler generates a number of files. The actual number of files generated depends on the options selected when the IDL file is compiled. The generated files provide standard functionality, so you can ignore them until it is time to deploy and run your program. The files generated by the idlj compiler for Hello.idl, with the -fall command line option, are:

    • HelloPOA.java

      This abstract class is the stream-based server skeleton, providing basic CORBA functionality for the server. It extends org.omg.PortableServer.Serva nt , and implements the InvokeHandler interface and the HelloOperations interface. The server class HelloImpl extends HelloPOA.

    • _HelloStub.java

      This class is the client stub, providing CORBA functionality for the client. It extends org.omg.CORBA.portable.ObjectImpl and implements the Hello.java interface.

    • Hello.java

      This interface contains the Java version of our IDL interface. The Hello.java interface extends org.omg.CORBA.Object, providing standard CORBA object functionality. It also extends the HelloOperations interface and org.omg.CORBA.portable.IDLEntity.

    • HelloHelper.java

      This class provides auxiliary functionality, notably the narrow() method required to cast CORBA object references to their proper types.The Helper class is responsible for reading and writing the data type to CORBA streams, and inserting and extracting the data type from Anys. The Holder class delegates to the methods in the Helper class for reading and writing.

    • HelloHolder.java

      This final class holds a public instance member of type Hello. Whenever the IDL type is an out or an inout parameter, the Holder class is used. It provides operations for org.omg.CORBA.portable.OutputStream and org.omg.CORBA.portable.InputStream arguments, which CORBA allows, but which do not map easily to Java's semantics. The Holder class delegates to the methods in the Helper class for reading and writing. It implements org.omg.CORBA.portable.Streamable.

    • HelloOperations.java

      This interface contains the methods sayHello() and shutdown(). The IDL-to-Java mapping puts all of the operations defined on the IDL interface into this file, which is shared by both the stubs and skeletons.

  3. Compile the .java files, including the stubs and skeletons (which are in the directory HelloApp). This step assumes the java/bin directory is included in your path.
       javac *.java HelloApp/*.java
  4. Start orbd.

    To start orbd from a UNIX command shell, enter:

      orbd -ORBInitialPort 1050&

    From an MS-DOS system prompt (Windows), enter:

      start orbd -ORBInitialPort 1050

    Note that 1050 is the port on which you want the name server to run. The -ORBInitialPort argument is a required command-line argument. Note that when using Solaris software, you must become root to start a process on a port under 1024. For this reason, we recommend that you use a port number greater than or equal to 1024.

    For an example of how to run this program on two machines, see Running the Hello World Program on 2 machines.

  5. Start the Hello server:

    To start the Hello server from a UNIX command shell, enter:

      java HelloServer -ORBInitialPort 1050 -ORBInitialHost localhost&

    From an MS-DOS system prompt (Windows), enter:

      start java HelloServer -ORBInitialPort 1050 -ORBInitialHost localhost

    You will see HelloServer ready and waiting... when the server is started.

    For this example, you can omit -ORBInitialHost localhost since the name server is running on the same host as the Hello server. If the name server is running on a different host, use -ORBInitialHost nameserverhost to specify the host on which the IDL name server is running.

    Specify the name server (orbd) port as done in the previous step, for example, -ORBInitialPort 1050.

  6. Run the client application:

      java HelloClient -ORBInitialPort 1050 -ORBInitialHost localhost

    When the client is running, you will see a response such as the following on your terminal: Obtained a handle on server object: IOR: (binary code) Hello World! HelloServer exiting...

    For this example, you can omit -ORBInitialHost localhost since the name server is running on the same host as the Hello client. If the name server is running on a different host, use -ORBInitialHost nameserverhost to specify the host on which the IDL name server is running.

    Specify the name server (orbd) port as done in the previous step, for example, -ORBInitialPort 1050.

When you have finished this tutorial, be sure to shut down or kill the name server (orbd). To do this from a DOS prompt, select the window that is running the server and enter Ctrl+C to shut it down. To do this from a Unix shell, find the process, and kill it. The server will continue to wait for invocations until it is explicitly stopped.

Running the Hello World Application on Two Machines describes one way of distributing the simple application across two machines - a client and a server.

Home

Copyright © 1995-2004 Sun Microsystems, Inc. All Rights Reserved.


The "Hello World" Example With The ImplBase Server-Side Model

Java IDL: The "Hello World" Example With The ImplBase Server-Side Model

This document is a high-level overview of how to create a complete CORBA (Common Object Request Broker Architecture) application using IDL (Interface Definiton Language) to define interfaces and the Java IDL compiler to generate stubs and skeletons. This document describes using the ImplBase Inheritance Server-Side Model.

The idlj compiler now generates server-side mappings based on the POA Inheritance Model as the default. For compatibility with existing applications, a new flag has been added to the idlj compiler to allow it to generate server-side mappings based on the ImplBase Inheritance Model, -oldImplBase. Existing applications that need to talk to servers created in J2SE 1.3 or prior may need to update their MAKEFILE so that this flag is used, however, new applications that have no such requirements should not generate these deprecated mappings.

NOTE: ImplBase is deprecated in favor of the POA model, but is provided to allow compatibility with servers written in J2SE 1.3 and prior. We do not recommend creating new servers using this nonstandard model.

This document contains:

  • The IDL for a simple "Hello World" program
  • A server that creates an object and publishes it with a naming service using the ImplBase server-side implementation
  • An application client that knows the object's name, retrieves a reference for it from the naming service, and invokes the object
  • Instructions for compiling and running the example

Defining the Interface (Hello.idl)

The first step to creating a CORBA application is to specify all of your objects and their interfaces using the OMG's Interface Definition Language (IDL). IDL has a syntax similar to C++ and can be used to define modules, interfaces, data structures, and more. The IDL can be mapped to a variety of programming languages. The IDL mapping for Java is summarized in IDL to Java Language Mapping Summary.

The following code is written in the OMG IDL, and describes a CORBA object whose sayHello() operation returns a string and whose shutdown() operation shuts down the ORB. To learn more about OMG IDL Syntax and Semantics, link to the OMG Web site, and read Chapter 3 of the CORBA Specification.

Hello.idl

module HelloApp
{
  interface Hello
  {
  string sayHello();
  oneway void shutdown();
  };
};
NOTE: When writing code in OMG IDL, do not use an interface name as the name of a module. Doing so runs the risk of getting inconsistent results when compiling with tools from different vendors, thereby jeopardizing the code's portability. For example, code containing the same names could be compiled with the IDL to Java compiler from Sun Microsystems and get one result. The same code compiled with another vendor's IDL to Java compiler could produce a different result.

To complete the application, you simply provide the server (HelloServer.java) and client (HelloClient.java) implementations.

Implementing the Server (HelloServer.java)

The example server consists of two classes, the servant and the server. The servant, HelloImpl, is the implementation of the Hello IDL interface; each Hello instance is implemented by a HelloImpl instance. The servant is a subclass of _HelloImplBase, which is generated by the idlj compiler from the example IDL. The servant contains one method for each IDL operation, in this example, the sayHello() and shutdown() methods. Servant methods are just like ordinary Java methods; the extra code to deal with the ORB, with marshaling arguments and results, and so on, is provided by the skeleton.

The HelloServer class has the server's main() method, which:

  • Creates and initializes an ORB instance
  • Creates a servant instance (the implementation of one CORBA Hello object) and tells the ORB about it
  • Gets a CORBA object reference for a naming context in which to register the new CORBA object
  • Gets the root naming context
  • Registers the new object in the naming context under the name "Hello"
  • Waits for invocations of the new object from the client

NOTE: ImplBase is deprecated in favor of the POA model, but is provided to allow compatibility with servers written in J2SE 1.3 and prior. We do not recommend creating new servers using this nonstandard model.

The HelloServer for the ImplBase server-side implementation differs only slightly from its POA counterpart. The sections of the POA-based server that get a reference to the root POA and activate the POAManager are not necessary for this implementation, which follows:

HelloServer.java

// Copyright and License
import HelloApp.*;
import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.CORBA.*;

import java.util.Properties;

class HelloImpl extends _HelloImplBase{

  private ORB orb;

  public void setORB(ORB orb_val){
    orb = orb_val;
  }

  public String sayHello(){
    return "\nHello world !!\n";
  }

  public void shutdown(){
    orb.shutdown(false);
  }
}

public class HelloServer {

  public static void main(String args[]) {
    try{
      // create and initialize the ORB
      ORB orb = ORB.init(args, null);

      // create servant and register it with the ORB
      HelloImpl helloImpl = new HelloImpl();
      helloImpl.setORB(orb);

      // get the root naming context
      org.omg.CORBA.Object objRef =
          orb.resolve_initial_references("NameService");
      NamingContext ncRef = NamingContextHelper.narrow(objRef);

      Hello href = HelloHelper.narrow(helloImpl);

      // bind the Object Reference in Naming
      NameComponent nc = new NameComponent("Hello", "");
      NameComponent path[] = {nc};
      ncRef.rebind(path, href);

      System.out.println("HelloServer ready and waiting ...");

      // wait for invocations from clients
      orb.run();
    }

    catch (Exception e) {
      System.err.println("ERROR: " + e);
      e.printStackTrace(System.out);
    }

    System.out.println("HelloServer Exiting ...");

  }
}

Implementing the Client Application (HelloClient.java)

The example application client that follows is similar to the one presented in the default tutorial, however, the new Interoperable Naming Service features are not used in this example to preserve backward compatibility. The example client application:

  • Creates and initiliazes an ORB
  • Obtains a reference to the naming context
  • Looks up "Hello" in the naming context and receives a reference to that CORBA object
  • Invokes the object's sayHello() and shutdown() operations and prints the result

HelloClient.java

// Copyright and License

import HelloApp.*;
import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.CORBA.*;

public class HelloClient{

  static Hello helloImpl;

  public static void main(String args[]){

    try{
      // create and initialize the ORB
      ORB orb = ORB.init(args, null);

      // get the root naming context
      org.omg.CORBA.Object objRef =
      orb.resolve_initial_references("NameService");
      NamingContext ncRef = NamingContextHelper.narrow(objRef);

      // resolve the Object Reference in Naming
      NameComponent nc = new NameComponent("Hello", "");
      NameComponent path[] = {nc};
      Hello helloImpl = HelloHelper.narrow(ncRef.resolve(path));

      System.out.println("Obtained a handle on server object: " + helloImpl);
      System.out.println(helloImpl.sayHello());
      helloImpl.shutdown();
      }

    catch (Exception e) {
      System.out.println("ERROR : " + e) ;
      e.printStackTrace(System.out);
    }
  }
}

Building and Running Hello World

Despite its simple design, the Hello World program lets you learn and experiment with all the tasks required to develop almost any CORBA program that uses static invocation.

This example requires a naming service, which is a CORBA service that allows CORBA objects to be named by means of binding a name to an object reference. The name binding may be stored in the naming service, and a client may supply the name to obtain the desired object reference. The two options for Naming Services shipped with this version of Java SE are tnameserv, a transient naming service, and orbd, which is a daemon process containing a Bootstrap Service, a Transient Naming Service, a Persistent Naming Service, and a Server Manager. This example uses orbd.

When running this example, remember that, when using Solaris software, you must become root to start a process on a port under 1024. For this reason, we recommend that you use a port number greater than or equal to 1024. The -ORBInitialPort option is used to override the default port number in this example. The following instructions assume you can use port 1050 for the Java IDL Object Request Broker Daemon, orbd. You can substitute a different port if necessary. When running these examples on a Windows machine, subtitute a backslash (\) in path names.

To run this client-server application on your development machine:

  1. Create the program files or download and unzip HelloImplBase.zip.

  2. Change to the directory that contains the file Hello.idl.

  3. Run the IDL-to-Java compiler, idlj, on the IDL file to create stubs and skeletons. This step assumes that you have included the path to the java/bin directory in your path.

    NOTE: ImplBase is deprecated in favor of the POA model, but is provided to allow compatibility with servers written in J2SE 1.3 and prior. We do not recommend creating new servers using this nonstandard model.

      idlj -fall -oldImplBase Hello.idl

    You must use the -fall option with the idlj compiler to generate both client and server-side bindings. This command line will generate the default server-side bindings, which assumes the POA programming model. The -oldImplBase option tells the compiler to generate the ImplBase Inheritance Model server-side bindings, instead of the default POA Inheritance Model server-side bindings. For more information on the idlj options, link to IDL-to-Java compiler options.

    The idlj compiler generates a number of files. The actual number of files generated depends on the options selected when the IDL file is compiled. The generated files provide standard functionality, so you can ignore them until it is time to deploy and run your program. The files generated by the idlj compiler for Hello.idl, with the -fall command line option, are:

    • _HelloImplBase.java

      This abstract class is the server skeleton, providing basic CORBA functionality for the server. It implements the InvokeHandler and the Hello interface. It inherits from org.omg.CORBA.portable.ObjectImpl. The server class HelloImpl inherits from _HelloImplBase.

    • _HelloStub.java

      This class is the client stub, providing CORBA functionality for the client. It inherits from org.omg.CORBA.portable.ObjectImpl and implements the Hello interface.

    • Hello.java

      This interface contains the Java version of our IDL interface. The Hello.java interface inherits from org.omg.CORBA.Object, providing standard CORBA object functionality. It also inherits from HelloOperations and org.omg.CORBA.portable.IDLEntity.

    • HelloHelper.java

      This class provides auxiliary functionality, notably the narrow() method required to cast CORBA object references to their proper types.The Helper class is responsible for reading and writing the data type to CORBA streams, and inserting and extracting the data type from Anys. The Holder class delegates to the methods in the Helper class for reading and writing.

    • HelloHolder.java

      This final class holds a public instance member of type Hello. Whenever the IDL type is an out or an inout parameter, the Holder class is used. It provides operations for org.omg.CORBA.portable.OutputStream and org.omg.CORBA.portable.InputStream arguments, which CORBA allows, but which do not map easily to Java's semantics. The Holder class delegates to the methods in the Helper class for reading and writing. It implements org.omg.CORBA.portable.Streamable.

    • HelloOperations.java

      This interface contains the methods sayHello() and shutdown(). The IDL-to-Java mapping puts all of the operations defined on the IDL interface into this file, which is shared by both the stubs and skeletons.

  4. Compile the .java files, including the stubs and skeletons (which are in the directory HelloApp). This step assumes the java/bin directory is included in your path.
       javac *.java HelloApp/*.java
  5. Start orbd.

    To start orbd from a UNIX command shell, enter:

      orbd -ORBInitialPort 1050 -ORBInitialHost localhost&

    From an MS-DOS system prompt (Windows), enter:

      start orbd -ORBInitialPort 1050 -ORBInitialHost localhost

    Note that 1050 is the port on which you want the name server to run. -ORBInitialPort is a required command-line argument. Note that when using Solaris software, you must become root to start a process on a port under 1024. For this reason, we recommend that you use a port number greater than or equal to 1024.

    -ORBInitialHost is an optional command-line argument. For this example, since both client and server on running on the development machine, we have set the host to localhost. When developing on more than one machine, you will replace this with the name of the host. For an example of how to run this program on two machines, see Running the Hello World Program on 2 machines.

  6. Start the Hello server:

    To start the Hello server from a UNIX command shell, enter:

      java HelloServer -ORBInitialPort 1050 -ORBInitialHost localhost&

    From an MS-DOS system prompt (Windows), enter:

      start java HelloServer -ORBInitialPort 1050 -ORBInitialHost localhost

    For this example, you can omit -ORBInitialHost localhost since the name server is running on the same host as the Hello server. If the name server is running on a different host, use -ORBInitialHost nameserverhost to specify the host on which the IDL name server is running.

    Specify the name server (orbd) port as done in the previous step, for example, -ORBInitialPort 1050.

    When the server is running, it will echo the following message back to the terminal:

    HelloServer ready and waiting ...
  7. Run the client application:

      java HelloClient -ORBInitialPort 1050 -ORBInitialHost localhost

    For this example, you can omit -ORBInitialHost localhost since the name server is running on the same host as the Hello client. If the name server is running on a different host, use -ORBInitialHost nameserverhost to specify the host on which the IDL name server is running.

    Specify the name server (orbd) port as done in the previous step, for example, -ORBInitialPort 1050.

    When the client is running, the following message will echo to the terminal:

       Obtained a handle on server object: IOR: ...
   Hello World !!
   HelloServer Exiting ...

When you have finished this tutorial, be sure to shut down or kill the name server (orbd). To do this from a DOS prompt, select the window that is running the server and enter Ctrl+C to shut it down. To do this from a Unix shell, find the process, and kill it. The server will continue to wait for invocations until it is explicitly stopped.

Running the Hello World Application on Two Machines describes one way of distributing the simple application across two machines - a client and a server.

Home

Copyright © 1995-2004 Sun Microsystems, Inc. All Rights Reserved.


The "Hello World" Example With The POA-Tie Server-Side Model

Java IDL: The "Hello World" Example With The POA-Tie Server-Side Model

This document is a high-level overview of how to create a complete CORBA (Common Object Request Broker Architecture) application using IDL (Interface Definiton Language) to define interfaces and the Java IDL compiler to generate stubs and skeletons. This document describes using the POA-Tie Server-Side Model. You might want to use the Tie model instead of the typical Inheritance model if your implementation must inherit from some other implementation. Java allows any number of interface inheritance, but there is only one slot for class inheritance. If you use the inheritance model, that slot is used up. By using the Tie Model, that slot is freed up for your own use. The drawback is that it introduces a level of indirection: one extra method call occurs when invoking a method.

The other part of this programming model is the Portable Object Adapter, or POA, which is designed to meet the following goals:

  • Allow programmers to construct object implementations that are portable between different ORB products.
  • Provide support for objects with persistent identities.
  • Provide support for transparent activation of objects.
  • Allow a single servant to support multiple object identities simultaneously.

This document contains:

  • The IDL for a simple "Hello World" program
  • A server that creates an object and publishes it with a naming service using the POA-Tie server-side implementation
  • An application client that knows the object's name, retrieves a reference for it from the naming service, and invokes the object
  • Instructions for compiling and running the example

Defining the Interface (Hello.idl)

The first step to creating a CORBA application is to specify all of your objects and their interfaces using the OMG's Interface Definition Language (IDL). IDL has a syntax similar to C++ and can be used to define modules, interfaces, data structures, and more. The IDL can be mapped to a variety of programming languages. The IDL mapping for Java is summarized in IDL to Java Language Mapping Summary.

The following code is written in the OMG IDL, and describes a CORBA object whose sayHello() operation returns a string and whose shutdown() method shuts down the ORB. To learn more about OMG IDL Syntax and Semantics, link to the OMG Web site, and read Chapter 3 of the CORBA Specification.

Hello.idl

module HelloApp
{
  interface Hello
  {
  string sayHello();
  oneway void shutdown();
  };
};
NOTE: When writing code in OMG IDL, do not use an interface name as the name of a module. Doing so runs the risk of getting inconsistent results when compiling with tools from different vendors, thereby jeopardizing the code's portability. For example, code containing the same names could be compiled with the IDL to Java compiler from Sun Microsystems and get one result. The same code compiled with another vendor's IDL to Java compiler could produce a different result.

To complete the application, you simply provide the server (HelloServer.java) and client (HelloClient.java) implementations.

Implementing the Server (HelloServer.java)

The example server consists of two classes, the servant and the server. The servant, HelloImpl, is the implementation of the Hello IDL interface; each Hello instance is implemented by a HelloImpl instance. The servant is a subclass of HelloPOA, which is generated by the idlj compiler from the example IDL. The servant contains one method for each IDL operation, in this example, the sayHello() and shutdown() methods. Servant methods are just like ordinary Java methods; the extra code to deal with the ORB, with marshaling arguments and results, and so on, is provided by the skeleton.

The HelloServer class has the server's main() method, which:

  • Creates and initializes an ORB instance
  • Gets a reference to the root POA and activates the POAManager
  • Creates a servant instance (the implementation of one CORBA Hello object) and tells the ORB about it
  • Creates a tie with the servant being the delegate
  • Gets a CORBA object reference for a naming context in which to register the tie. This step also implicitly activates the object. See the POA topic for more information on POA policies and activations.
  • Gets the root naming context
  • Registers the new object in the naming context under the name "Hello"
  • Waits for invocations of the new object from the client

The code that is different from that in the default tutorial is highlighted in bold.

HelloServer.java

// Copyright and License
import HelloApp.*;
import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.CORBA.*;
import org.omg.PortableServer.*;
import org.omg.PortableServer.POA;

import java.util.Properties;

class HelloImpl extends HelloPOA{
  private ORB orb;

  public void setORB(ORB orb_val){
    orb = orb_val;
  }

  public String sayHello(){
    return "\nHello world !!\n";
  }

  public void shutdown(){
    orb.shutdown(false);
  }
}

public class HelloServer{

  public static void main(String args[]){
    try{
      // create and initialize the ORB
      ORB orb = ORB.init(args, null);

      // Get reference to rootpoa & activate the POAManager
      POA rootpoa = POAHelper.narrow(orb.resolve_initial_references("RootPOA"));
      rootpoa.the_POAManager().activate();

      // create servant and register it with the ORB
      HelloImpl helloImpl = new HelloImpl();
      helloImpl.setORB(orb);

      // create a tie, with servant being the delegate.
      HelloPOATie tie = new HelloPOATie(helloImpl, rootpoa);

      // obtain the objectRef for the tie
      // this step also implicitly activates the
      // the object
      Hello href = tie._this(orb);

      // get the root naming context
      org.omg.CORBA.Object objRef = orb.resolve_initial_references("NameService");

      // Use NamingContextExt which is part of the Interoperable
      // Naming Service specification.
      NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef);

      // bind the Object Reference in Naming
      String name = "Hello";
      NameComponent path[] = ncRef.to_name( name );
      ncRef.rebind(path, href);

      System.out.println("HelloServer ready and waiting ...");

      // wait for invocations from clients
      orb.run();
      }

    catch (Exception e){
      System.err.println("ERROR: " + e);
      e.printStackTrace(System.out);
    }

    System.out.println("HelloServer Exiting ...");

  }
}

Implementing the Client Application (HelloClient.java)

The example application client that follows is the same as the one presented in the default tutorial. The server implementation is the only file that is changed from that example. The example client application:

  • Creates and initializes an ORB
  • Obtains a reference to the root naming context
  • Looks up "Hello" in the naming context and receives a reference to that CORBA object
  • Invokes the object's sayHello() and shutdown() operations and prints the result

HelloClient.java

// Copyright and License

import HelloApp.*;
import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.CORBA.*;

public class HelloClient{

  public static void main(String args[]){

    try{
      // create and initialize the ORB
      ORB orb = ORB.init(args, null);

      // get the root naming context
      org.omg.CORBA.Object objRef =
      orb.resolve_initial_references("NameService");

      // Use NamingContextExt instead of NamingContext. This is
      // part of the Interoperable naming Service.
      NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef);

      // resolve the Object Reference in Naming
      String name = "Hello";
      Hello helloImpl = HelloHelper.narrow(ncRef.resolve_str(name));

      System.out.println("Obtained a handle on server object: " + helloImpl);
      System.out.println(helloImpl.sayHello());
      helloImpl.shutdown();
      }

    catch (Exception e) {
      System.out.println("ERROR : " + e) ;
      e.printStackTrace(System.out);
    }
  }
}

Building and Running Hello World

Despite its simple design, the Hello World program lets you learn and experiment with all the tasks required to develop almost any CORBA program that uses static invocation.

This example requires a naming service, which is a CORBA service that allows CORBA objects to be named by means of binding a name to an object reference. The name binding may be stored in the naming service, and a client may supply the name to obtain the desired object reference. The two options for Naming Services shipped with this version of Java SE are tnameserv, a transient naming service, and orbd, which contain a Naming Service. This example uses orbd.

When running this example, remember that, when using Solaris software, you must become root to start a process on a port under 1024. For this reason, we recommend that you use a port number greater than or equal to 1024. The -ORBInitialPort option is used to override the default port number in this example. The following instructions assume you can use port 1050 for the Java IDL Object Request Broker Daemon, orbd. You can substitute a different port if necessary. When running these examples on a Windows machine, subtitute a backslash (\) in path names.

To run this client-server application on your development machine:

  1. Create the program files or download and unzip the file HelloTie.zip.

  2. Change to the directory that contains the program files.

  3. Run the IDL-to-Java compiler, idlj, twice on the IDL file to create stubs and skeletons. This step assumes that you have included the path to the java/bin directory in your path.
      idlj -fall  Hello.idl
  idlj -fallTie Hello.idl

    You must use the -fall option with the idlj compiler to generate both client and server-side bindings. This command line will generate the default server-side bindings, which assumes the POA programming model. The -fallTie option generates another file, HelloPOATie, which is used to create a Tie. For more information on the idlj options, link to IDL-to-Java compiler options.

    The idlj compiler generates a number of files. The actual number of files generated depends on the options selected when the IDL file is compiled. The generated files provide standard functionality, so you can ignore them until it is time to deploy and run your program. The files generated by the idlj compiler for Hello.idl, with the -fall command line option, are:

    • HelloPOA.java

      This abstract class is the stream-based server skeleton, providing basic CORBA functionality for the server. It extends org.omg.PortableServer.Servant, and implements the InvokeHandler interface and the HelloOperations interface. The server class HelloImpl extends HelloPOA.

    • _HelloStub.java

      This class is the client stub, providing CORBA functionality for the client. It extends org.omg.CORBA.portable.ObjectImpl and implements the Hello interface.

    • Hello.java

      This interface contains the Java version of our IDL interface. The Hello interface extends org.omg.CORBA.Object, providing standard CORBA object functionality. It also extends the HelloOperations interface and org.omg.CORBA.portable.IDLEntity.

    • HelloHelper.java

      This class provides auxiliary functionality, notably the narrow() method required to cast CORBA object references to their proper types.The Helper class is responsible for reading and writing the data type to CORBA streams, and inserting and extracting the data type from Anys. The Holder class delegates to the methods in the Helper class for reading and writing.

    • HelloHolder.java

      This final class holds a public instance member of type Hello. Whenever the IDL type is an out or an inout parameter, the Holder class is used. It provides operations for org.omg.CORBA.portable.OutputStream and org.omg.CORBA.portable.InputStream arguments, which CORBA allows, but which do not map easily to Java's semantics. The Holder class delegates to the methods in the Helper class for reading and writing. It implements org.omg.CORBA.portable.Streamable.

    • HelloOperations.java

      This interface contains the methods sayHello() and shutdown(). The IDL-to-Java mapping puts all of the operations defined on the IDL interface into this file, which is shared by both the stubs and skeletons.

    The files generated by the idlj compiler for Hello.idl, with the -fallTie command line option, are:

    • HelloPOATie.java

      The constructor to MyPOATie takes a delegate and/or a poa. You must provide the implementations for delegate and/or poa, but the delegate does not have to inherit from any other class, only the interface HelloOperations. For more information, refer to the IDL to Java Language Mapping Specification.

  4. Compile the .java files, including the stubs and skeletons (which are in the directory HelloApp). This step assumes the java/bin directory is included in your path.
       javac *.java HelloApp/*.java
  5. Start orbd.

    To start orbd from a UNIX command shell, enter:

      orbd -ORBInitialPort 1050 -ORBInitialHost localhost&

    From an MS-DOS system prompt (Windows), enter:

      start orbd -ORBInitialPort 1050 -ORBInitialHost localhost

    Note that 1050 is the port on which you want the name server to run. -ORBInitialPort is a required command-line argument. Note that when using Solaris software, you must become root to start a process on a port under 1024. For this reason, we recommend that you use a port number greater than or equal to 1024.

    -ORBInitialHost is an optional command-line argument. For this example, since both client and server on running on the development machine, we have set the host to localhost. When developing on more than one machine, you will replace this with the name of the host. For an example of how to run this program on two machines, see Running the Hello World Program on 2 machines.

  6. Start the Hello server.

    To start the Hello server from a UNIX command shell, enter:

      java HelloServer -ORBInitialPort 1050 -ORBInitialHost localhost&

    From an MS-DOS system prompt (Windows), enter:

      start java HelloServer -ORBInitialPort 1050 -ORBInitialHost localhost

    For this example, you can omit -ORBInitialHost localhost since the name server is running on the same host as the Hello server. If the name server is running on a different host, use -ORBInitialHost nameserverhost to specify the host on which the IDL name server is running.

    Specify the name server (orbd) port as done in the previous step, for example, -ORBInitialPort 1050.

    The server starts and echos the following message back to the terminal:

    HelloServer ready and waiting ...
  7. Run the client application:

      java HelloClient -ORBInitialPort 1050 -ORBInitialHost localhost

    For this example, you can omit -ORBInitialHost localhost since the name server is running on the same host as the Hello client. If the name server is running on a different host, use -ORBInitialHost nameserverhost to specify the host on which the IDL name server is running.

    Specify the name server (orbd) port as done in the previous step, for example, -ORBInitialPort 1050.

    The client runs and echos the following information back to the terminal:

    Obtained a handle on server object: IOR:
...
Hello World!
Hello Server Exiting ...

When you have finished this tutorial, be sure to shut down or kill the name server (orbd). To do this from a DOS prompt, select the window that is running orbd and enter Ctrl+C to shut it down. To do this from a Unix shell, find the process, and kill it. The name server will continue to wait for invocations until it is explicitly stopped.

Running the Hello World Application on Two Machines describes one way of distributing the simple application across two machines - a client and a server.

Home

Copyright © 1995-2004 Sun Microsystems, Inc. All Rights Reserved.


Tutorial

Hello World Tutorial

Home Concepts Programming Reference Tutorial
Copyright © 1996-2004 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.


Using Adapter Activators

When creating a new POA, the application developer may declare specific policy choices for the new POA and provide a different adapter activator and servant manager (these are callback objects used by the POA to activate POAs on demand and activate servants). Creating new POAs also allows the application developer to partition the name space of objects, as Object Ids are interpreted relative to a POA. Finally, by creating new POAs, the developer can independently control request processing for multiple sets of objects.

An adapter activator is optional. You would use an adapter activator if POAs need to be created during request processing. If all needed POAs are created when the application is initialized, an adapter activator is not required.

An adapter activator supplies a POA with the ability to create child POAs on demand, as a side-effect of receiving a request that names the child POA (or one of its children), or when the find_POA method is called with an activate parameter value of TRUE. The ORB will invoke an operation on an adapter activator when a request is received for a child POA that does not currently exist. The adapter activator can then create the required POA on demand.

A request must be capable of conveying the Object Id of the target object as well as the identification of the POA that created the target object reference. When a client issues a request, the ORB first locates an appropriate server (perhaps starting one if needed) and then it locates the appropriate POA within that server.

If the POA does not exist in the server process, the application has the opportunity to re-create the required POA by using an adapter activator. An adapter activator is a user-implemented object that can be associated with a POA. It is invoked by the ORB when a request is received for a nonexistent child POA. The adapter activator has the opportunity to create the required POA. If it does not, the client receives the ADAPTER_NONEXISTENT exception.

Once the ORB has located the appropriate POA, it delivers the request to that POA. The further processing of that request depends both upon the policies associated with that POA as well as the object's current state of activation.

An Example Using Adapter Activators

The following example code shows an application that uses Adapter Activators to enable the POA to be created during request processing. This application builds on the "Hello World" example. The following files are included in this example:

  • Client.java
  • Server.java
  • Hello.idl
  • HelloServant.java
  • Makefile
  • run.bat

For instructions on running this example, see Running the Example Adapter Activator Application.

Client.java

The code for the example client initializes the ORB, resolves HelloServant, and invokes the sayHello() method.

//Client.java
import org.omg.CORBA.ORB;
import org.omg.CosNaming.NamingContext;
import org.omg.CosNaming.NamingContextHelper;
import org.omg.CosNaming.NameComponent;

public class Client {

    public void run(String[] args) {
        try {
            //initialize the orb
            ORB orb = ORB.init(args, null);
            System.out.println("ORB initialized");

            NamingContext namingContext = NamingContextHelper.narrow(
                orb.resolve_initial_references("NameService"));
            NameComponent[] nc = { new NameComponent("HelloServer", "") };

            //resolve HelloServant and invoke sayHello()
            Hello helloRef = HelloHelper.narrow(namingContext.resolve(nc));
            System.out.println("Resolved HelloServant");

            System.out.println(helloRef.sayHello());

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    public static void main(String[] args) {
        new Client().run(args);
    }
}

Server.java

The code for the server does the following:

  • Initializes the ORB.
  • Resolve RootPOA.
  • Registers the adapter activator with rootPOA so that child POAs can be created on demand.
  • Runs find_POA with an activate parameter of TRUE to cause the adapter activator associated with rootPOA to be invoked if 'HelloPOA' does not exist.
  • Creates the object reference for HelloServant and registers it with the naming service.
  • Destroys 'HelloPOA'. This POA will be transparently recreated when the ORB receives a request on HelloPOA using the adapter activator we registered with the RootPOA.
  • Activates rootPOA.
  • Waits for incoming requests.
  • Creates MyAdapterActivator to create the POA with appropriate policies, associate the servant with the new POA, and activate the new POA.

//Server.java
import org.omg.CORBA.ORB;
import org.omg.CORBA.LocalObject;
import org.omg.CORBA.Policy;
import org.omg.PortableServer.POA;
import org.omg.PortableServer.POAHelper;
import org.omg.PortableServer.AdapterActivator;
import org.omg.PortableServer.IdAssignmentPolicyValue;
import org.omg.PortableServer.LifespanPolicyValue;
import org.omg.PortableServer.ImplicitActivationPolicyValue;
import org.omg.CosNaming.NamingContext;
import org.omg.CosNaming.NamingContextHelper;
import org.omg.CosNaming.NameComponent;

public class Server {

    public void run(String[] args) {
        try {
            //initialize the orb
            ORB orb = ORB.init(args, null);
            System.out.println("ORB initialized");

            //resolve RootPOA
            POA rootPOA = POAHelper.narrow(
                orb.resolve_initial_references("RootPOA"));

            //register adapter activator with rootPOA so that child POAs can
            //be created on demand
            rootPOA.the_activator(new MyAdapterActivator());

            //find_POA with an activate parameter TRUE would cause the
            //adapter activator associated with rootPOA to be invoked if
            //'HelloPOA' does not exist
            POA childPOA = rootPOA.find_POA("HelloPOA", true);

            //Create the object reference for HelloServant
            //and register with naming service
            org.omg.CORBA.Object obj = childPOA.id_to_reference(
                "abcd".getBytes());
            Hello helloRef = HelloHelper.narrow(obj);

            NamingContext namingContext = NamingContextHelper.narrow(
                orb.resolve_initial_references("NameService"));
            NameComponent[] nc = { new NameComponent("HelloServer", "") };
            namingContext.rebind(nc, helloRef);

            //Destroy 'HelloPOA'. This POA will be transparently recreated when
            //ORB receives a request on HelloPOA using the adapter activator we
            //registered with the RootPOA
            childPOA.destroy(true, true);

            //activate rootPOA
            rootPOA.the_POAManager().activate();

            //wait for incoming requests
            System.out.println("Server ready and running....");
            orb.run();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    public static void main(String[] args) {
        new Server().run(args);
    }
}

class MyAdapterActivator extends LocalObject implements AdapterActivator {

    public boolean unknown_adapter(POA parent, String name) {
        System.out.println("unknown_adapter() invoked for POA - " + name);
        try {
            // create the POA with appropriate policies
            // this sample uses PERSISTENT, NO_IMPLICIT_ACTIVATION
            // and USER_ID policies
            Policy[] policy = new Policy[3];
            policy[0] = parent.create_lifespan_policy(
                LifespanPolicyValue.PERSISTENT);
            policy[1] = parent.create_id_assignment_policy(
                IdAssignmentPolicyValue.USER_ID);
            policy[2] = parent.create_implicit_activation_policy(
                ImplicitActivationPolicyValue.NO_IMPLICIT_ACTIVATION);

            POA child = parent.create_POA(name, null, policy);

            //Associate the servant with the new POA
            HelloServant hello = new HelloServant();
            child.activate_object_with_id("abcd".getBytes(), hello);

            //activate the new POA
            child.the_POAManager().activate();

            return true;
        } catch (Exception e) {
            e.printStackTrace();
        }
        return false;
    }
}

Hello.idl

This Interface Definition Language (IDL) file is used in all of the "Hello World" example variations on this site. This IDL file describes a CORBA object whose sayHello() operation returns a string.

interface Hello {
   string sayHello();
};

HelloServant.java

The servant is the implementation of the Hello IDL interface; each Hello instance is implemented by a HelloServant instance. The servant is a subclass of HelloPOA, which is generated by the idlj compiler from the example IDL. The servant contains one method for each IDL operation, in this example, the sayHello() method. Servant methods are just like ordinary Java methods; the extra code to deal with the ORB, with marshaling arguments and results, and so on, is provided by the skeleton.

//HelloServant.java
public class HelloServant extends HelloPOA {

    public String sayHello() {
        return "Hello :)";
    }
}

Makefile

The make program generates a sequence of commands for execution by the Unix shell.

JAVA_HOME=<path_to_your_Java_installation_bin_directory>

#setup tools
JAVA=$(JAVA_HOME)/bin/java
JAVAC=$(JAVA_HOME)/bin/javac
IDLJ=$(JAVA_HOME)/bin/idlj
ORBD=$(JAVA_HOME)/bin/orbd

all	: clean build run

clean	:
    - rm -rf classes orb.db

build	:
    mkdir -p classes
    $(IDLJ) -fall -td classes Hello.idl
    $(JAVAC) -classpath classes -d classes HelloServant.java Server.java Client.java

run	: runorbd register runclient

runorbd :
    $(ORBD) -ORBInitialPort 10001 &
    sleep 20

register:
    #servertool does not support script based register due to a bug
    #using class instead
    #Please note that the name of the servertool
    #class may change in future releases.
    $(JAVA) com.sun.corba.se.internal.Activation.ServerTool \
    -ORBInitialPort 10001 -cmd \
    register -server Server -classpath classes

runclient :
    $(JAVA) -classpath classes Client -ORBInitialPort 10001

run.bat

The bat utility generates a sequence of commands for execution by the Microsoft Windows command shell.

SET JAVA_HOME=<path_to_your_Java_installation_build_directory>

mkdir classes

%JAVA_HOME%\bin\idlj -fall -td classes Hello.idl
%JAVA_HOME%\bin\javac -classpath classes -d classes HelloServant.java Server.java Client.java

REM - Start the ORB daemon

start %JAVA_HOME%\bin\orbd -ORBInitialPort 10001 -ORBDebug orbd
@echo Wait 10-15 seconds for the orbd to start
@pause

REM - Register the persistent server with orbd using servertool
REM - Please note that the name of the servertool
REM - class may change in future releases.
%JAVA_HOME%\bin\java com.sun.corba.se.internal.Activation.ServerTool -ORBInitialPort 10001 -cmd register -server Server -classpath classes

%JAVA_HOME%\bin\java -classpath classes Client -ORBInitialPort 10001

Running the Example Adapter Activator Application

To run this example,

  • Create the files using the code shown above.
  • Run the example using either of these methods:

    • If you have the Make utility, run the application using the Makefile:

      make all

    • If you have the batch utility, run the application using run.bat. From the application directory, enter:

      run

You will see output generated to the terminal window similar to that below when you run the Makefile:

rm -rf classes orb.db
mkdir -p classes
/j2sdk1.5.0/bin/idlj -fall -td classes Hello.idl
/j2sdk1.5.0/bin/javac -classpath classes -d classes HelloServant.java Server.java Client.java
/j2sdk1.5.0/bin/orbd -ORBInitialPort 10001 &
sleep 20
#servertool does not support script based register due to a bug
#using class instead
#Please note that the name of the servertool
#class may change in future releases.
/j2sdk1.5.0/bin/java com.sun.corba.se.internal.Activation.ServerTool \
-ORBInitialPort 10001 -cmd \
register -server Server -classpath classes

        server registered (serverid = 257).

/j2sdk1.5.0/bin/java -classpath classes Client -ORBInitialPort 10001
ORB initialized
Resolved HelloServant
Hello :)
Shut down ORBD when you have completed this example.
  • If using the Unix operating system, type pkill orbd in the terminal window.
  • If using Microsoft Windows, enter Ctrl+C in the command prompt window.

Further Information

For more information on Adapter Activators, please refer to section 11.3.3 of the CORBA 2.3.1 Specification or the AdapterActivatorOperations API documentation.

Java IDL Home


Using Servant Activators

What is a Servant Activator?

When creating a new POA, the application developer may declare specific policy choices for the new POA and provide a different adapter activator and servant manager (these are callback objects used by the POA to activate POAs on demand and activate servants). Creating new POAs also allows the application developer to partition the name space of objects, as Object Ids are interpreted relative to a POA. Finally, by creating new POAs, the developer can independently control request processing for multiple sets of objects.

A Servant Activator is a type of Servant Manager. Servant Managers are optional. You would use a servant manager to allow the POA to activate servants on demand when a request for an inactive object is received. If your server loads all objects when it starts up, you do not need a servant manager.

A servant manager is a callback object that the application developer can associate with a POA. The ORB will invoke operations on servant managers to activate servants on demand, and to deactivate servants. Servant managers are responsible for managing the association of an object reference (as characterized by its Object Id value) with a particular servant, and for determining whether an object reference exists or not. Each servant manager type contains two operations, the first called to find and return a servant and the second to deactivate a servant. The operations differ according to the amount of information usable for their situation.

To use servant managers, the USE_SERVANT_MANAGER policy must be set. Once set, the type of servant manager used in a particular situation depends on other policies in the POA. The two types of servant managers are:

  • ServantActivator

    When the POA has the RETAIN policy, it uses servant managers that are ServantActivators. A ServantActivator always results in an entry in the Active Object Map. The servant is then used until it is deactivated. A servant can be deactivated by destroying the POA, the POA Manager, or the ORB, or by an explicit deactivate call.

    • This document includes an example that uses Servant Activators, see An Example Using Servant Activators.

  • ServantLocator

    When the POA has the NON_RETAIN policy, it uses servant managers that are ServantLocators. Because the POA knows that the servant returned by this servant manager will be used only for a single request, it can supply extra information to the servant manager's operations and the servant manager's pair of operations may be able to cooperate to do something different than a ServantActivator. When the POA uses the ServantLocator interface, immediately after performing the operation invocation on the servant returned by preinvoke, the POA will invoke postinvoke on the servant manager, passing the ObjectId value and the Servant value as parameters (among others). This feature may be used to force every request for objects associated with a POA to be mediated by the servant manager.

    • For an example that uses Servant Locators see Using Servant Locators.

An Example Using Servant Activators

**In progress, please check back for updates!

The following example code shows an application that uses Servant Activators to enable the POA to activate transient objects. This application builds on the "Hello World" example. The following files are included for your information:

  • Client.java
  • Server.java
  • Hello.idl
  • HelloImpl.java
  • Makefile
  • runSample

Client.java

    import org.omg.CORBA.ORB;
import org.omg.CosNaming.*;

public class Client {
    public Client(String[] args) {
        try {
            ORB orb = ORB.init(args, System.getProperties());
        NamingContext rootContext = NamingContextHelper.narrow(
                orb.resolve_initial_references("NameService"));

            // Resolves for remote object reference of HelloServer
        NameComponent name[] = {new NameComponent("HelloServer", "")};
        Hello helloRef = HelloHelper.narrow(rootContext.resolve(name));
            System.out.println("\nClient: Obtained the remote object " +
                               "reference");

            // Invokes the remote sayHello() method
            System.out.println("Client: Invoking the remote operation ...");
        System.out.println(helloRef.sayHello());
        } catch (Exception e) {
            System.err.println("\nClient: Caught exception - " + e);
            e.printStackTrace();
        }
    }

    public static void main(String [] args) {
    Client servantActivatorClient = new Client(args);
    }
}

Server.java

    import org.omg.CORBA.*;
import org.omg.PortableServer.*;
import org.omg.CosNaming.*;

public class Server {
    public Server(String[] args) {
        try {
            ORB orb = ORB.init(args, System.getProperties());
            POA rootPoa = (POA) orb.resolve_initial_references("RootPOA");
            rootPoa.the_POAManager().activate();
            System.out.println("\nServer: Obtained from ORB and activated " +
                               "the " + rootPoa.the_name());

            Policy poaPolicy[] = new Policy[2];
            poaPolicy[0] = rootPoa.create_servant_retention_policy(
                ServantRetentionPolicyValue.RETAIN);
            poaPolicy[1] = rootPoa.create_request_processing_policy(
                RequestProcessingPolicyValue.USE_SERVANT_MANAGER);
            System.out.println("Server: Set POA policy as RETAIN and " +
                               "USE_SERVANT_MANAGER");

            POA poa1 = rootPoa.create_POA("HelloPoa", null, poaPolicy);
            poa1.the_POAManager().activate();
            System.out.println("Server: Created and activated child POA " +
                               "\"" + poa1.the_name() + "\"");

            poa1.set_servant_manager(new PoaServantActivator());
            System.out.println("Server: Associated the servant manager of " +
                               "type servant activator with \"" +
                               poa1.the_name() + "\"");

            // This create_reference operation does not cause an activation,
            // the resulting object reference will be exported and passed to
            // client, so that subsequent requests on the reference will cause
            // the appropriate servant manager to be invoked
            org.omg.CORBA.Object objectRef = poa1.create_reference(
                HelloHelper.id());
            System.out.println("Server: Created a CORBA object reference " +
                               "from id \"" + HelloHelper.id() + "\"");

            NamingContext rootContext = NamingContextHelper.narrow(
                orb.resolve_initial_references("NameService"));
            NameComponent name[] = {new NameComponent("HelloServer", "")};
            rootContext.rebind(name, objectRef);
            System.out.println("Server: Exported the CORBA object reference " +
                               "to NameService");

            System.out.println("Server: Ready and waiting for requests ...");
            orb.run();
        } catch (Exception e) {
            System.err.println("\nServer: Caught exception - " + e);
            e.printStackTrace();
        }
    }

    public static void main(String [] args) {
        Server serverServantActivator = new Server(args) ;
    }
}

class PoaServantActivator extends LocalObject implements ServantActivator {
    // The incarnate operation is invoked by the POA whenever the POA receives
    // a request for an object that is not currently active, assuming the POA
    // has the RETAIN and USE_SERVANT_MANAGER policies
    public Servant incarnate(byte[] oid, POA adapter) throws ForwardRequest {
        try {
            HelloImpl servantObj = new HelloImpl();
            System.out.println("PoaServantActivator.incarnate(): Created \"" +
                               servantObj.getClass().getName() + "\" " +
                               "servant object for \"" + adapter.the_name() +
                               "\"");
            return servantObj;
        } catch (Exception e) {
            System.err.println("incarnate: Caught exception - " + e);
        }
        return null;
    }

    public void etherealize(byte[] oid, POA adapter, Servant serv,
                            boolean cleanup_in_progress,
                            boolean remaining_activations) {
    }
}

Hello.idl

    interface Hello {
    string sayHello();
};

HelloImpl.java

    public class HelloImpl extends HelloPOA {

    public String sayHello() {
        return "Hello :)";
    }

}

Makefile

    IDLJ=${JAVA_HOME}/bin/idlj
JAVAC=${JAVA_HOME}/bin/javac
JAVA=${JAVA_HOME}/bin/java

CLASSFILES=./classes_dir
IDLJFLAGS=-fall -verbose -td ${CLASSFILES}
JFLAGS=-g -d $(CLASSFILES) -classpath $(CLASSFILES)
JAVAFLAGS=-cp $(CLASSFILES) -Dorg.omg.CORBA.ORBInitialHost=localhost \
          -Dorg.omg.CORBA.ORBInitialPort=1950
ORBD_FLAGS=-port 1949 -ORBInitialHost ${SERVER_HOSTNAME} \
           -ORBInitialPort 1950 -ORBDebug
ORBD=${JAVA_HOME}/bin/orbd $(ORBD_FLAGS) orbd

client = Client.java

server = HelloImpl.java \
     Server.java

all: clean build run

clean:
    @echo ""
    @echo "*** Clean up old files and directories ***"
    -$(RM) $(CLASSFILES)
    -$(RM) ./orb.db
    -$(RM) ./kill_started_processes.sh

build: stubs client_server

stubs: Hello.idl
    @echo ""
    @echo "*** Generate stubs and helpers ***"
    @-$(MKDIR) $(CLASSFILES)
    $(IDLJ) $(IDLJFLAGS) Hello.idl

client_server: $(client) $(server)
    @echo ""
    @echo "*** Compile client, server and implementation ***"
    $(JAVAC) $(JFLAGS) $(client) $(server)

run: run_orbd run_server run_client terminate_servers

run_orbd:
    @echo ""
    @echo "*** Start the orbd ***"
    $(ORBD) & \
    echo "kill -9 $$!" > ./kill_started_processes.sh; \
    if [ $(OS) = "WinNT" ] ; then \
        tpid=`ps -o pid,ppid,comm | grep $$! | grep -v "sh" | cut -c1-6` ; \
        echo "kill -9 $$tpid" >> ./kill_started_processes.sh ; \
    fi ; \
    $(SLEEP) $(SLEEP_LONG)

run_server: run_orbd
    @echo ""
    @echo "*** Start the Server ***"
    $(JAVA) $(JAVAFLAGS) Server & \
    echo "kill -9 $$!" >> ./kill_started_processes.sh; \
    if [ $(OS) = "WinNT" ] ; then \
    tpid=`ps -o pid,ppid,comm | grep $$! | grep -v "sh" | cut -c1-6` ; \
    echo "kill -9 $$tpid" >> ./kill_started_processes.sh ; \
    fi ; \
    $(SLEEP) $(SLEEP_NORMAL)

run_client:
    @echo ""
    @echo "*** Start the Client ***"
    $(JAVA) $(JAVAFLAGS) Client

terminate_servers:
    @echo ""
    @echo "*** Terminate the Server and orbd ***"
    @$(SLEEP) $(SLEEP_SHORT)
    @if [ -f ./kill_started_processes.sh ]; then \
        $(CHMOD) u+x ./kill_started_processes.sh; \
        ./kill_started_processes.sh; \
        $(SLEEP) $(SLEEP_SHORT) ; \
    fi

runSample

    #!/bin/ksh

if [ `uname` = "SunOS" ] ; then
    OS="Solaris_sparc"
    JAVA_HOME=/path_to_your_java_installation
    SEP=:
    SLEEP=/bin/sleep
    RM="/bin/rm -rf"
    CHMOD=/bin/chmod
    MKDIR=/bin/mkdir
    SLEEP_SHORT=2
    SLEEP_NORMAL=5
    SLEEP_LONG=7
elif [ `uname` = "Windows_NT" ] ; then
    OS="WinNT"
    if [ ! -d "y:/path_to_your_java_installation" ] ; then
        echo; echo "Please map drive y: to \\\\\your_Java_drive before runSample"
        exit 1
    fi
    JAVA_HOME="y:/path_to_your_java_installation"
    SEP=";"
    SLEEP=sleep
    RM="rm -rf"
    CHMOD=chmod
    MKDIR="mkdir -p"
    SLEEP_SHORT=5
    SLEEP_NORMAL=10
    SLEEP_LONG=15
fi

while [ $# -gt 0 ] ; do
   case $1 in
   -host ) SERVER_HOSTNAME=$2 ;
           shift;;
   * ) TARGET=$* ;
       break ;;
   esac
   shift
done

DEFAULT_HOSTNAME=localhost
SERVER_HOSTNAME=${HOSTNAME-$DEFAULT_HOSTNAME}

make ${TARGET} \
   "OS=${OS}" \
   "JAVA_HOME=${JAVA_HOME}" \
   "SERVER_HOSTNAME=${SERVER_HOSTNAME}" \
   "SLEEP=${SLEEP}" \
   "RM=${RM}" \
   "CHMOD=${CHMOD}" \
   "MKDIR=${MKDIR}" \
   "SLEEP_SHORT=${SLEEP_SHORT}" \
   "SLEEP_NORMAL=${SLEEP_NORMAL}" \
   "SLEEP_LONG=${SLEEP_LONG}"

Running the Example Servant Activator Example

To run this example,

  1. Create the files using the code shown above.
  2. Run the example as shown in runSample.

You will see output generated to the terminal window similar to that below:

    *** Clean up old files and directories ***
/bin/rm -rf ./classes_dir
/bin/rm -rf ./orb.db
/bin/rm -rf ./kill_started_processes.sh

*** Generate stubs and helpers ***
/path_to_your_java_installation/bin/idlj -fall -verbose -td ./classes_dir Hello.idl
Parsing Hello.idl
done  - Hello.idl

Generating Hello
done   -   Hello

*** Compile client, server and implementation ***
/path_to_your_java_installation/bin/javac -g -d ./classes_dir -classpath
./classes_dir Client.java HelloImpl.java Server.java

*** Start the orbd ***
/path_to_your_java_installation/bin/orbd -port 1949 -ORBInitialHost localhost
-ORBInitialPort 1950 -ORBDebug orbd & \
echo "kill -9 $!" > ./kill_started_processes.sh; \
if [ Solaris_sparc = "WinNT" ] ; then \
    tpid=`ps -o pid,ppid,comm | grep $! | grep -v "sh" | cut -c1-6` ; \
    echo "kill -9 $tpid" >> ./kill_started_processes.sh ; \
fi ; \
/bin/sleep 7
ORBD begins initialization.
ORBD is ready.
ORBD serverid: 1
activation dbdir: /path_to_your_sample_file/ServantActivator/./orb.db
activation port: 1949
activation Server Polling Time: 1000 milli-seconds
activation Server Startup Delay: 1000 milli-seconds

*** Start the Server ***
/path_to_your_java_installation/bin/java -cp ./classes_dir
-Dorg.omg.CORBA.ORBInitialHost=localhost -Dorg.omg.CORBA.ORBInitialPort=1950 Server & \
echo "kill -9 $!" >> ./kill_started_processes.sh; \
if [ Solaris_sparc = "WinNT" ] ; then \
tpid=`ps -o pid,ppid,comm | grep $! | grep -v "sh" | cut -c1-6` ; \
echo "kill -9 $tpid" >> ./kill_started_processes.sh ; \
fi ; \
/bin/sleep 5

Server: Obtained from ORB and activated the RootPOA
Server: Set POA policy as RETAIN and USE_SERVANT_MANAGER
Server: Created and activated child POA "HelloPoa"
Server: Associated the servant manager of type servant activator with "HelloPoa"
Server: Created a CORBA object reference from id "IDL:Hello:1.0"
Server: Exported the CORBA object reference to NameService
Server: Ready and waiting for requests ...

*** Start the Client ***
/path_to_your_java_installation/bin/java -cp ./classes_dir
-Dorg.omg.CORBA.ORBInitialHost=localhost -Dorg.omg.CORBA.ORBInitialPort=1950 Client

Client: Obtained the remote object reference
Client: Invoking the remote operation ...
PoaServantActivator.incarnate(): Created "HelloImpl" servant object for "HelloPoa"
Hello :)

*** Terminate the Server and orbd ***

Further Information

For more information on Servant Activators, see the section on Servant Managers, in section 11.3.4 of the CORBA 2.3.1 Specification.

Java IDL Home


Using Servant Locators

What is a Servant Locator?

When creating a new POA, the application developer may declare specific policy choices for the new POA and provide a different adapter activator and servant manager (these are callback objects used by the POA to activate POAs on demand and activate servants). Creating new POAs also allows the application developer to partition the name space of objects, as Object Ids are interpreted relative to a POA. Finally, by creating new POAs, the developer can independently control request processing for multiple sets of objects.

A Servant Activator is a type of Servant Manager. Servant Managers are optional. You would use a servant manager to allow the POA to activate servants on demand when a request for an inactive object is received. If your server loads all objects when it starts up, you do not need a servant manager.

A servant manager is a callback object that the application developer can associate with a POA. The ORB will invoke operations on servant managers to activate servants on demand, and to deactivate servants. Servant managers are responsible for managing the association of an object reference (as characterized by its Object Id value) with a particular servant, and for determining whether an object reference exists or not. Each servant manager type contains two operations, the first called to find and return a servant and the second to deactivate a servant. The operations differ according to the amount of information usable for their situation.

To use servant managers, the USE_SERVANT_MANAGER policy must be set. Once set, the type of servant manager used in a particular situation depends on other policies in the POA. The two types of servant managers are:

  • ServantActivator

    When the POA has the RETAIN policy, it uses servant managers that are ServantActivators. A ServantActivator always results in an entry in the Active Object Map. The servant is then used until it is deactivated. A servant can be deactivated by destroying the POA, the POA Manager, or the ORB, or by an explicit deactivate call.

    • For an example that uses Servant Activators, see Using Servant Activators.

  • ServantLocator

    When the POA has the NON_RETAIN policy, it uses servant managers that are ServantLocators. Because the POA knows that the servant returned by this servant manager will be used only for a single request, it can supply extra information to the servant manager's operations and the servant manager's pair of operations may be able to cooperate to do something different than a ServantActivator. When the POA uses the ServantLocator interface, immediately after performing the operation invocation on the servant returned by preinvoke, the POA will invoke postinvoke on the servant manager, passing the ObjectId value and the Servant value as parameters (among others). This feature may be used to force every request for objects associated with a POA to be mediated by the servant manager.

    • This document includes an example that uses Servant Locators, see An Example Using Servant Locators.

An Example Using Servant Locators

**In progress, please check back for updates!

The following example code shows an application that uses Servant Locators to enable the POA to activate transient objects. This application builds on the "Hello World" example. The following files are included for your information:

  • Client.java
  • Server.java
  • Hello.idl
  • HelloImpl.java
  • Makefile
  • runSample

Client.java

    import org.omg.CORBA.ORB;
import org.omg.CosNaming.*;

public class Client {
    public Client(String[] args) {
        try {
            ORB orb = ORB.init(args, System.getProperties());
        NamingContext rootContext = NamingContextHelper.narrow(
                orb.resolve_initial_references("NameService"));

            // Resolves for remote object reference of HelloServer
        NameComponent name[] = {new NameComponent("HelloServer", "")};
        Hello helloRef = HelloHelper.narrow(rootContext.resolve(name));
            System.out.println("\nClient: Obtained the remote object " +
                               "reference");

            // Invokes the remote sayHello() method
            System.out.println("Client: Invoking the remote operation ...");
        System.out.println(helloRef.sayHello());
        } catch (Exception e) {
            System.err.println("\nClient: Caught exception - " + e);
            e.printStackTrace();
        }
    }

    public static void main(String [] args) {
    Client servantLocatorClient = new Client(args);
    }
}

Server.java

    import org.omg.CORBA.*;
import org.omg.PortableServer.*;
import org.omg.PortableServer.ServantLocatorPackage.*;
import org.omg.CosNaming.*;

public class Server {
    public Server(String[] args) {
        try {
            ORB orb = ORB.init(args, System.getProperties());
            POA rootPoa = (POA) orb.resolve_initial_references("RootPOA");
            rootPoa.the_POAManager().activate();
            System.out.println("\nServer: Obtained from ORB and activated " +
                               "the " + rootPoa.the_name());

            Policy poaPolicy[] = new Policy[2];
            poaPolicy[0] = rootPoa.create_servant_retention_policy(
                ServantRetentionPolicyValue.NON_RETAIN);
            poaPolicy[1] = rootPoa.create_request_processing_policy(
                RequestProcessingPolicyValue.USE_SERVANT_MANAGER);
            System.out.println("Server: Set POA policy as NON_RETAIN and " +
                               "USE_SERVANT_MANAGER");

            POA poa1 = rootPoa.create_POA("HelloPoa", null, poaPolicy);
            poa1.the_POAManager().activate();
            System.out.println("Server: Created and activated child POA " +
                               "\"" + poa1.the_name() + "\"");

            poa1.set_servant_manager(new PoaServantLocator());
            System.out.println("Server: Associated the servant manager of " +
                               "type servant locator with \"" +
                               poa1.the_name() + "\"");

            // This create_reference operation does not cause an activation,
            // the resulting object reference will be exported and passed to
            // client, so that subsequent requests on the reference will cause
            // the appropriate servant manager to be invoked
            org.omg.CORBA.Object objectRef = poa1.create_reference(
                HelloHelper.id());
            System.out.println("Server: Created a CORBA object reference " +
                               "from id \"" + HelloHelper.id() + "\"");

            NamingContext rootContext = NamingContextHelper.narrow(
                orb.resolve_initial_references("NameService"));
            NameComponent name[] = {new NameComponent("HelloServer", "")};
            rootContext.rebind(name, objectRef);
            System.out.println("Server: Exported the CORBA object reference " +
                               "to NameService");

            System.out.println("Server: Ready and waiting for requests ...");
            orb.run();
        } catch (Exception e) {
            System.err.println("\nServer: Caught exception - " + e);
            e.printStackTrace();
        }
    }

    public static void main(String [] args) {
        Server serverServantLocator = new Server(args) ;
    }
}

class PoaServantLocator extends LocalObject implements ServantLocator {
    public Servant preinvoke(byte[] oid, POA adapter,
                             String operation,
                             CookieHolder the_cookie) throws ForwardRequest {
        try {
            HelloImpl servantObj = new HelloImpl();
            System.out.println("PoaServantLocator.preinvoke(): Created \"" +
                               servantObj.getClass().getName() + "\" " +
                               "servant object for \"" + adapter.the_name() +
                               "\"");
            return servantObj;
        } catch (Exception e) {
            System.err.println("preinvoke: Caught exception - " + e);
        }
        return null;
    }

    public void postinvoke(byte[] oid, POA adapter,
                           String operation,
                           java.lang.Object the_cookie,
                           Servant the_servant) {
        try {
            System.out.println("PoaServantLocator.postinvoke(): For \"" +
                               adapter.the_name() + "\" adapter of servant " +
                               "object type \"" +
                               the_servant.getClass().getName() + "\"");
        } catch (Exception e) {
            System.err.println("postinvoke: Caught exception - " + e);
        }
    }
}

Hello.idl

    interface Hello {
    string sayHello();
};

HelloImpl.java

    public class HelloImpl extends HelloPOA {

    public String sayHello() {
        return "Hello :)";
    }

}

Makefile

    IDLJ=${JAVA_HOME}/bin/idlj
JAVAC=${JAVA_HOME}/bin/javac
JAVA=${JAVA_HOME}/bin/java

CLASSFILES=./classes_dir
IDLJFLAGS=-fall -verbose -td ${CLASSFILES}
JFLAGS=-g -d $(CLASSFILES) -classpath $(CLASSFILES)
JAVAFLAGS=-cp $(CLASSFILES) -Dorg.omg.CORBA.ORBInitialHost=localhost \
          -Dorg.omg.CORBA.ORBInitialPort=1950
ORBD_FLAGS=-port 1949 -ORBInitialHost ${SERVER_HOSTNAME} \
           -ORBInitialPort 1950 -ORBDebug
ORBD=${JAVA_HOME}/bin/orbd $(ORBD_FLAGS) orbd

client = Client.java

server = HelloImpl.java \
     Server.java

all: clean build run

clean:
    @echo ""
    @echo "*** Clean up old files and directories ***"
    -$(RM) $(CLASSFILES)
    -$(RM) ./orb.db
    -$(RM) ./kill_started_processes.sh

build: stubs client_server

stubs: Hello.idl
    @echo ""
    @echo "*** Generate stubs and helpers ***"
    @-$(MKDIR) $(CLASSFILES)
    $(IDLJ) $(IDLJFLAGS) Hello.idl

client_server: $(client) $(server)
    @echo ""
    @echo "*** Compile client, server and implementation ***"
    $(JAVAC) $(JFLAGS) $(client) $(server)

run: run_orbd run_server run_client terminate_servers

run_orbd:
    @echo ""
    @echo "*** Start the orbd ***"
    $(ORBD) & \
    echo "kill -9 $$!" > ./kill_started_processes.sh; \
    if [ $(OS) = "WinNT" ] ; then \
        tpid=`ps -o pid,ppid,comm | grep $$! | grep -v "sh" | cut -c1-6` ; \
        echo "kill -9 $$tpid" >> ./kill_started_processes.sh ; \
    fi ; \
    $(SLEEP) $(SLEEP_LONG)

run_server: run_orbd
    @echo ""
    @echo "*** Start the Server ***"
    $(JAVA) $(JAVAFLAGS) Server & \
    echo "kill -9 $$!" >> ./kill_started_processes.sh; \
    if [ $(OS) = "WinNT" ] ; then \
    tpid=`ps -o pid,ppid,comm | grep $$! | grep -v "sh" | cut -c1-6` ; \
    echo "kill -9 $$tpid" >> ./kill_started_processes.sh ; \
    fi ; \
    $(SLEEP) $(SLEEP_NORMAL)

run_client:
    @echo ""
    @echo "*** Start the Client ***"
    $(JAVA) $(JAVAFLAGS) Client

terminate_servers:
    @echo ""
    @echo "*** Terminate the Server and orbd ***"
    @$(SLEEP) $(SLEEP_SHORT)
    @if [ -f ./kill_started_processes.sh ]; then \
        $(CHMOD) u+x ./kill_started_processes.sh; \
        ./kill_started_processes.sh; \
        $(SLEEP) $(SLEEP_SHORT) ; \
    fi

runSample

    #!/bin/ksh

if [ `uname` = "SunOS" ] ; then
    OS="Solaris_sparc"
    JAVA_HOME=/path_to_your_java_installation
    SEP=:
    SLEEP=/bin/sleep
    RM="/bin/rm -rf"
    CHMOD=/bin/chmod
    MKDIR=/bin/mkdir
    SLEEP_SHORT=2
    SLEEP_NORMAL=5
    SLEEP_LONG=7
elif [ `uname` = "Windows_NT" ] ; then
    OS="WinNT"
    if [ ! -d "y:/path_to_your_java_installation" ] ; then
        echo; echo "Please map drive y: to \\\\\path_to_your_java_installation before
runSample"
        exit 1
    fi
    JAVA_HOME="y:/path_to_your_java_installation"
    SEP=";"
    SLEEP=sleep
    RM="rm -rf"
    CHMOD=chmod
    MKDIR="mkdir -p"
    SLEEP_SHORT=5
    SLEEP_NORMAL=10
    SLEEP_LONG=15
fi

while [ $# -gt 0 ] ; do
   case $1 in
   -host ) SERVER_HOSTNAME=$2 ;
           shift;;
   * ) TARGET=$* ;
       break ;;
   esac
   shift
done

DEFAULT_HOSTNAME=localhost
SERVER_HOSTNAME=${HOSTNAME-$DEFAULT_HOSTNAME}

make ${TARGET} \
   "OS=${OS}" \
   "JAVA_HOME=${JAVA_HOME}" \
   "SERVER_HOSTNAME=${SERVER_HOSTNAME}" \
   "SLEEP=${SLEEP}" \
   "RM=${RM}" \
   "CHMOD=${CHMOD}" \
   "MKDIR=${MKDIR}" \
   "SLEEP_SHORT=${SLEEP_SHORT}" \
   "SLEEP_NORMAL=${SLEEP_NORMAL}" \
   "SLEEP_LONG=${SLEEP_LONG}"

Running the Example Servant Activator Example

To run this example,

  1. Create the files using the code shown above.
  2. Run the example as shown in runSample.

You will see output generated to the terminal window similar to that below:

*** Clean up old files and directories ***
/bin/rm -rf ./classes_dir
/bin/rm -rf ./orb.db
/bin/rm -rf ./kill_started_processes.sh

*** Generate stubs and helpers ***
/path_to_your_java_installation/bin/idlj -fall -verbose -td ./classes_dir Hello.idl
Parsing Hello.idl
done  - Hello.idl

Generating Hello
done   -   Hello

*** Compile client, server and implementation ***
/path_to_your_java_installation/bin/javac -g -d ./classes_dir -classpath ./classes_dir
Client.java HelloImpl.java Server.java

*** Start the orbd ***
/path_to_your_java_installation/bin/orbd -port 1949 -ORBInitialHost localhost -ORBInitialPort
1950 -ORBDebug orbd & \
echo "kill -9 $!" > ./kill_started_processes.sh; \
if [ Solaris_sparc = "WinNT" ] ; then \
    tpid=`ps -o pid,ppid,comm | grep $! | grep -v "sh" | cut -c1-6` ; \
    echo "kill -9 $tpid" >> ./kill_started_processes.sh ; \
fi ; \
/bin/sleep 7
ORBD begins initialization.
ORBD is ready.
ORBD serverid: 1
activation dbdir: /home/dcarson1/samples/POA_samples/ServantLocator/./orb.db
activation port: 1949
activation Server Polling Time: 1000 milli-seconds
activation Server Startup Delay: 1000 milli-seconds

*** Start the Server ***
/path_to_your_java_installation/bin/java -cp ./classes_dir
-Dorg.omg.CORBA.ORBInitialHost=localhost -Dorg.omg.CORBA.ORBInitialPort=1950 Server & \
echo "kill -9 $!" >> ./kill_started_processes.sh; \
if [ Solaris_sparc = "WinNT" ] ; then \
tpid=`ps -o pid,ppid,comm | grep $! | grep -v "sh" | cut -c1-6` ; \
echo "kill -9 $tpid" >> ./kill_started_processes.sh ; \
fi ; \
/bin/sleep 5

Server: Obtained from ORB and activated the RootPOA
Server: Set POA policy as NON_RETAIN and USE_SERVANT_MANAGER
Server: Created and activated child POA "HelloPoa"
Server: Associated the servant manager of type servant locator with "HelloPoa"
Server: Created a CORBA object reference from id "IDL:Hello:1.0"
Server: Exported the CORBA object reference to NameService
Server: Ready and waiting for requests ...

*** Start the Client ***
/path_to_your_java_installation/bin/java -cp ./classes_dir
-Dorg.omg.CORBA.ORBInitialHost=localhost -Dorg.omg.CORBA.ORBInitialPort=1950 Client

Client: Obtained the remote object reference
Client: Invoking the remote operation ...
PoaServantLocator.preinvoke(): Created "HelloImpl" servant object for "HelloPoa"
PoaServantLocator.postinvoke(): For "HelloPoa" adapter of servant object type "HelloImpl"
Hello :)

*** Terminate the Server and orbd ***

Further Information

For more information on Servant Locators, see the section on Servant Managers in section 11.3.4 of the CORBA 2.3.1 Specification.

Java IDL Home


Mapping IDL to Java

Java IDL: IDL to Java Language Mapping

This release of the JavaTM 2 Platform Standard Edition 5.0, includes idlj, a compiler that reads an Object Management Group (OMG) Interface Definition Language (IDL) file and translates it, or maps it, to a Java interface. Depending on the command-line options used, the idlj compiler creates stub, skeleton, helper, holder, and other files as necessary. These .java files are generated from the IDL file according to the mapping specified in the OMG document (pdf format) OMG IDL to Java Language Mapping Specification, ptc, 00-01-08, with the revisions indicated in ptc/00-11-03, The new IDL to Java Mapping Chapter. Version 00-01-08 of the IDL to Java language mapping is aligned with CORBA version 2.3.2. For a basic summary of the IDL to Java mapping, see IDL to Java Language Mapping Overview below.

  • The CORBA technology shipped in J2SE 5.0 conforms to the mappings specified by the following document: Official Specifications for CORBA support in J2SE 5.0.

Some topics from the OMG IDL to Java Language Mapping specification that are not easily summarized are:

  • Section 1.13, Mapping for Value Type
  • Section 1.14, Value Box Types
  • Section 1.20, Server-Side Mapping
  • Section 1.21, Java ORB Portability Interfaces

IDL to Java Language Mapping Overview

CORBA objects are defined in OMG IDL (Object Management Group Interface Definition Language). The syntax and semantics of OMG IDL are defined in Chapter 3 of the CORBA/IIOP 2.3.1 Specification. The IDL-to-Java compiler, idlj, maps the IDL-defined interfaces to Java classes and interfaces as defined in OMG IDL to Java Language Mapping Specification, ptc, 00-01-08, and as supported in this version of the Java platform, as described in Official Specifications for CORBA support in J2SE 5.0.

This overview shows the correspondence between OMG IDL types and Java types. Note that OMG IDL, as its name implies, defines interfaces. Like Java interfaces, IDL interfaces contain no implementations for their operations (methods in Java). In other words, IDL interfaces define only the signature for an operation (the name of the operation, the data type of its return value, the data types of the parameters that it takes, and any exceptions that it raises). The implementations for these operations need to be supplied in Java classes written by a Java programmer.

The following table lists the main constructs of IDL and the corresponding constructs in Java.

IDL Type | Java Type
module | package
boolean | boolean
char, wchar | char
octet | byte
string, wstring | java.lang.String
short, unsigned short | short
long, unsigned long | int
long long, unsigned long long | long
float | float
double | double
fixed | java.math.BigDecimal
enum, struct, union | class
sequence, array | array
interface (non-abstract) | signature interface and an operations interface, helper class, holder class
interface (abstract) | signature interface, helper class, holder class
constant (not within an interface) | public interface
constant (within an interface) | fields in the Java signature interface for non-abstract, or the sole Java interface for abstract
exception | class
Any | org.omg.CORBA.Any
type declarations nested within interfaces | "scoped" package
typedef | helper classes
pseudo objects | pseudo interface
readonly attribute | accessor method
readwrite attribute | accessor and modifer methods
operation | method

Java IDL Home


Developing a Client Application

Getting Started with Java IDL: Developing a Client Application

This topic introduces the basics of writing a CORBA client application. Included in this lesson are:

  1. Creating HelloClient.java
  2. Understanding HelloClient.java
  3. Compiling HelloClient.java

Creating HelloClient.java

To create HelloClient.java,

  1. Start your text editor and create a file named HelloClient.java in your main project directory, Hello.

  2. Enter the following code for HelloClient.java in the text file. The following section, Understanding HelloClient.java, explains each line of code in some detail.

    HelloClient.java

    // Copyright and License

import HelloApp.*;
import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.CORBA.*;

public class HelloClient
{
  static Hello helloImpl;

  public static void main(String args[])
    {
      try{
        // create and initialize the ORB
    ORB orb = ORB.init(args, null);

        // get the root naming context
        org.omg.CORBA.Object objRef =
        orb.resolve_initial_references("NameService");
        // Use NamingContextExt instead of NamingContext. This is
        // part of the Interoperable naming Service.
        NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef);

        // resolve the Object Reference in Naming
        String name = "Hello";
        helloImpl = HelloHelper.narrow(ncRef.resolve_str(name));

        System.out.println("Obtained a handle on server object: " + helloImpl);
        System.out.println(helloImpl.sayHello());
        helloImpl.shutdown();

    } catch (Exception e) {
          System.out.println("ERROR : " + e) ;
      e.printStackTrace(System.out);
      }
    }

}

  3. Save and close HelloClient.java.

Understanding HelloClient.java

This section explains each line of HelloClient.java, describing what the code does, as well as why it is needed for this application.

Performing Basic Setup

The basic shell of a CORBA client is the same as many Java applications: You import required library packages, declare the application class, define a main method, and handle exceptions.

Importing Required Packages

First, we import the packages required for the client class:

import HelloApp.*; // the package containing our stubs
import org.omg.CosNaming.*; // HelloClient will use the Naming Service
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.CORBA.*; // All CORBA applications need these classes

Declaring the Client Class

The next step is to declare the client class:

public class HelloClient
{
  // The main() method goes here.
}

Defining a main() Method

Every Java application needs a main() method. It is declared within the scope of the HelloClient class, as follows:

  public static void main(String args[])
  {
    // The try-catch block goes here.
  }

Handling CORBA System Exceptions

Because all CORBA programs can throw CORBA system exceptions at runtime, all of the main() functionality is placed within a try-catch block. CORBA programs throw system exceptions whenever trouble occurs during any of the processes (marshaling, unmarshaling, upcall) involved in invocation.

Our exception handler simply prints the name of the exception and its stack trace to standard output so you can see what kind of thing has gone wrong.

The try-catch block is set up inside main(),

    try{

      // Add the rest of the HelloClient code here.

    } catch(Exception e) {
        System.out.println("ERROR : " + e);
        e.printStackTrace(System.out);
      }

Creating an ORB Object

A CORBA client needs a local ORB object to perform all of its marshaling and IIOP work. Every client instantiates an org.omg.CORBA.ORB object and initializes it by passing to the object certain information about itself.

The ORB variable is declared and initialized inside the try-catch block.

    ORB orb = ORB.init(args, null);

The call to the ORB's init() method passes in your application's command line arguments, allowing you to set certain properties at runtime.

Finding the Hello Server

Now that the application has an ORB, it can ask the ORB to locate the actual service it needs, in this case the Hello server. There are a number of ways for a CORBA client to get an initial object reference; our client application will use the COS Naming Service specified by OMG and provided with Java IDL. See Using Stringified Object References for information on how to get an initial object reference when there is no naming service available.

The two options for Naming Services shipped with J2SE v.1.4 are orbd, which is a daemon process containing a Bootstrap Service, a Transient Naming Service, a Persistent Naming Service, and a Server Manager, and tnameserv, a transient naming service. This example uses orbd.

Obtaining the Initial Naming Context

The first step in using the naming service is to get the initial naming context. In the try-catch block, below your ORB initialization, you call orb.resolve_initial_references() to get an object reference to the name server:

        org.omg.CORBA.Object objRef =
            orb.resolve_initial_references("NameService");

The string "NameService" is defined for all CORBA ORBs. When you pass in that string, the ORB returns the initial naming context, an object reference to the name service. The string "NameService" indicates:

  • The persistent naming service will be used when using ORBD as the naming service.
  • The transient naming service will be used when using tnameserv as the naming service.

The string "TNameService" indicates that the transient naming service will be used when ORBD is the naming service. In this example, we are using the persistent naming service that is a part of orbd.

Narrowing the Object Reference

As with all CORBA object references, objRef is a generic CORBA object. To use it as a NamingContextExt object, you must narrow it to its proper type.

        NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef);

Here we see the use of an idlj-generated helper class, similar in function to HelloHelper. The ncRef object is now an org.omg.CosNaming.NamingContextExt and you can use it to access the naming service and find other services. You will do that in the next step.

The NamingContextExt object is new to J2SE v.1.4, and is part of the Interoperable Naming Service.

Resolve the Object Reference in Naming

To publish a reference in the Naming Service to the Hello object implementing the Hello interface, you first need an identifying string for the Hello object.

      String name = "Hello";

Finally, we pass name to the naming service's resolve_str() method to get an object reference to the Hello server and narrow it to a Hello object:

        helloImpl = HelloHelper.narrow(ncRef.resolve-str(name));
        System.out.println("Obtained a handle on server object: " + helloImpl);

Here you see the HelloHelper helper class at work. The resolve-str() method returns a generic CORBA object as you saw above when locating the name service itself. Therefore, you immediately narrow it to a Hello object, which is the object reference you need to perform the rest of your work. Then, you send a message to the screen confirming that the object reference has been obtained.

Invoking the sayHello() Operation

CORBA invocations look like a method call on a local object. The complications of marshaling parameters to the wire, routing them to the server-side ORB, unmarshaling, and placing the upcall to the server method are completely transparent to the client programmer. Because so much is done for you by generated code, invocation is really the easiest part of CORBA programming.

Finally, we print the results of the invocation to standard output and explicitly shutdown the ORB:

        System.out.println(helloImpl.sayHello());
        helloImpl.shutdown();

Compiling HelloClient.java

Now we will compile HelloClient.java so that we can correct any errors before continuing with this tutorial.

Windows users note that you should substitute backslashes (\) for the slashes (/) in all paths in this document.

To compile HelloClient.java,

  1. Change to the Hello directory.

  2. Run the Java compiler on HelloClient.java:
    javac HelloClient.java HelloApp/*.java
  3. Correct any errors in your file and recompile if necessary.
  4. The HelloClient.class is generated to the Hello directory.

Running the Client Application

 Running the Hello World application is covered in Running the Hello World Application.

For More Information
Developing Clients
Covers topics of interest to CORBA client programmers
Exceptions: System Exceptions
Explains how CORBA system exceptions work and provides details on the minor codes of Java IDL's system exceptions
Initialization: System Properties
Explains what properties can be passed to the ORB at initialization
Naming Service
Covers the COS Naming Service in greater detail

Previous: Developing the Hello World Server
Next: Running the Hello World Application
Tutorial home: Getting Started with Java IDL
Java IDL Home

Copyright © 1996-2001 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.


Developing the Hello World Server

Getting Started with Java IDL:
Developing the Hello World Server

The example server consists of two classes, the servant and the server. The servant, HelloImpl, is the implementation of the Hello IDL interface; each Hello instance is implemented by a HelloImpl instance. The servant is a subclass of HelloPOA, which is generated by the idlj compiler from the example IDL.

The servant contains one method for each IDL operation, in this example, the sayHello() and shutdown() methods. Servant methods are just like ordinary Java methods; the extra code to deal with the ORB, with marshaling arguments and results, and so on, is provided by the skeleton.

The server class has the server's main() method, which:

  • Creates and initializes an ORB instance
  • Gets a reference to the root POA and activates the POAManager
  • Creates a servant instance (the implementation of one CORBA Hello object) and tells the ORB about it
  • Gets a CORBA object reference for a naming context in which to register the new CORBA object
  • Gets the root naming context
  • Registers the new object in the naming context under the name "Hello"
  • Waits for invocations of the new object from the client

This lesson introduces the basics of writing a CORBA server. For an example of the "Hello World" program with a persistent object server, see Example 2: Hello World with Persistent State. For more discussion of CORBA servers, see Developing Servers.

The steps in this lesson cover:

  1. Creating HelloServer.java
  2. Understanding HelloServer.java
  3. Compiling the Hello World Server

Creating HelloServer.java

To create HelloServer.java,

  1. Start your text editor and create a file named HelloServer.java in your main project directory, Hello.

  2. Enter the following code for HelloServer.java in the text file. The following section, Understanding HelloServer.java, explains each line of code in some detail.

    // HelloServer.java
// Copyright and License
import HelloApp.*;
import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
import org.omg.CORBA.*;
import org.omg.PortableServer.*;
import org.omg.PortableServer.POA;

import java.util.Properties;

class HelloImpl extends HelloPOA {
  private ORB orb;

  public void setORB(ORB orb_val) {
    orb = orb_val;
  }

  // implement sayHello() method
  public String sayHello() {
    return "\nHello world !!\n";
  }

  // implement shutdown() method
  public void shutdown() {
    orb.shutdown(false);
  }
}

public class HelloServer {

  public static void main(String args[]) {
    try{
      // create and initialize the ORB
      ORB orb = ORB.init(args, null);

      // get reference to rootpoa & activate the POAManager
      POA rootpoa = POAHelper.narrow(orb.resolve_initial_references("RootPOA"));
      rootpoa.the_POAManager().activate();

      // create servant and register it with the ORB
      HelloImpl helloImpl = new HelloImpl();
      helloImpl.setORB(orb);

      // get object reference from the servant
      org.omg.CORBA.Object ref = rootpoa.servant_to_reference(helloImpl);
      Hello href = HelloHelper.narrow(ref);

      // get the root naming context
      org.omg.CORBA.Object objRef =
          orb.resolve_initial_references("NameService");
      // Use NamingContextExt which is part of the Interoperable
      // Naming Service (INS) specification.
      NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef);

      // bind the Object Reference in Naming
      String name = "Hello";
      NameComponent path[] = ncRef.to_name( name );
      ncRef.rebind(path, href);

      System.out.println("HelloServer ready and waiting ...");

      // wait for invocations from clients
      orb.run();
    }

      catch (Exception e) {
        System.err.println("ERROR: " + e);
        e.printStackTrace(System.out);
      }

      System.out.println("HelloServer Exiting ...");

  }
}

  3. Save and close HelloServer.java.

Understanding HelloServer.java

This section explains each line of HelloServer.java, describing what the code does, as well as why it is needed for this application.

Performing Basic Setup

The structure of a CORBA server program is the same as most Java applications: You import required library packages, declare the server class, define a main() method, and handle exceptions.

Importing Required Packages

First, we import the packages required for the server class:

// The package containing our stubs
import HelloApp.*;

// HelloServer will use the naming service
import org.omg.CosNaming.*;

// The package containing special exceptions thrown by the name service
import org.omg.CosNaming.NamingContextPackage.*;

// All CORBA applications need these classes
import org.omg.CORBA.*;

// Classes needed for the Portable Server Inheritance Model
import org.omg.PortableServer.*;
import org.omg.PortableServer.POA;

// Properties to initiate the ORB
import java.util.Properties;

Defining the Servant Class

In this example, we are defining the class for the servant object within HelloServer.java, but outside the HelloServer class.

class HelloImpl extends HelloPOA
{
  // The sayHello() and shutdown() methods go here.
}

The servant is a subclass of HelloPOA so that it inherits the general CORBA functionality generated for it by the compiler.

First, we create a private variable, orb that is used in the setORB(ORB) method. The setORB method is a private method defined by the application developer so that they can set the ORB value with the servant. This ORB value is used to invoke shutdown() on that specific ORB in response to the shutdown() method invocation from the client.

  private ORB orb;

  public void setORB(ORB orb_val) {
    orb = orb_val;
  }

Next, we declare and implement the required sayHello() method:

  public String sayHello()
  {
    return "\nHello world!!\n";
  }

And last of all, we implement the shutdown() method in a similar way. The shutdown() method calls the org.omg.CORBA.ORB.shutdown(boolean) method for the ORB. The shutdown(false) operation indicate that the ORB should shut down immediately, without waiting for processing to complete.

  public void shutdown() {
    orb.shutdown(false);
  }

Declaring the Server Class

The next step is to declare the server class:

public class HelloServer
{
  // The main() method goes here.
}

Defining the main() Method

Every Java application needs a main method. It is declared within the scope of the HelloServer class:

  public static void main(String args[])
  {
    // The try-catch block goes here.
  }

Handling CORBA System Exceptions

Because all CORBA programs can throw CORBA system exceptions at runtime, all of the main() functionality is placed within a try-catch block. CORBA programs throw runtime exceptions whenever trouble occurs during any of the processes (marshaling, unmarshaling, upcall) involved in invocation. The exception handler simply prints the exception and its stack trace to standard output so you can see what kind of thing has gone wrong.

The try-catch block is set up inside main(), as shown:

    try{

      // The rest of the HelloServer code goes here.

    } catch(Exception e) {
        System.err.println("ERROR: " + e);
        e.printStackTrace(System.out);
      }

Creating and Initializing an ORB Object

A CORBA server needs a local ORB object, as does the CORBA client. Every server instantiates an ORB and registers its servant objects so that the ORB can find the server when it receives an invocation for it.

The ORB variable is declared and initialized inside the try-catch block.

      ORB orb = ORB.init(args, null);

The call to the ORB's init() method passes in the server's command line arguments, allowing you to set certain properties at runtime.

Get a Reference to the Root POA and Activate the POAManager

The ORB obtains the initial object references to services such as the Name Service using the method resolve_initial_references.

The reference to the root POA is retrieved and the POAManager is activated from within the try-catch block.

      POA rootpoa = POAHelper.narrow(orb.resolve_initial_references("RootPOA"));
      rootpoa.the_POAManager().activate();

The activate() operation changes the state of the POA manager to active, causing associated POAs to start processing requests. The POA manager encapsulates the processing state of the POAs with which it is associated. Each POA object has an associated POAManager object. A POA manager may be associated with one or more POA objects.

Managing the Servant Object

A server is a process that instantiates one or more servant objects. The servant inherits from the interface generated by idlj and actually performs the work of the operations on that interface. Our HelloServer needs a HelloImpl.

Instantiating the Servant Object

We instantiate the servant object inside the try-catch block, just after activating the POA manager, as shown:

      HelloImpl helloImpl = new HelloImpl();

The section of code describing the servant class was explained previously.

In the next line of code, setORB(orb) is defined on the servant so that ORB.shutdown() can be called as part of the shutdown operation. This step is required because of the shutdown() method defined in Hello.idl.

      helloImpl.setORB(orb);

There are other options for implementing the shutdown operation. In this example, the shutdown() method called on the Object takes care of shutting down an ORB. In another implementation, the shutdown method implementation could have simply set a flag, which the server could have checked and called shutdown().

The next set of code is used to get the object reference associated with the servant. The narrow() method is required to cast CORBA object references to their proper types.

      org.omg.CORBA.Object ref = rootpoa.servant_to_reference(helloImpl);
      Hello href = HelloHelper.narrow(ref);

Working with COS Naming

The HelloServer works with the Common Object Services (COS) Naming Service to make the servant object's operations available to clients. The server needs an object reference to the naming service so that it can publish the references to the objects implementing various interfaces. These object references are used by the clients for invoking methods. Another way a servant can make the objects available to clients for invocations is by stringifying the object references to a file.

The two options for Naming Services shipped with J2SE v.1.4 are:

  • orbd, which includes both a Transient Naming Service and a Persistent Naming Service, in addition to a Server Manager.
  • tnameserv - a Transient Naming Service.

This example uses orbd.

Obtaining the Initial Naming Context

In the try-catch block, below getting the object reference for the servant, we call orb.resolve_initial_references() to get an object reference to the name server:

      org.omg.CORBA.Object objRef =
          orb.resolve_initial_references("NameService");

The string "NameService" is defined for all CORBA ORBs. When you pass in that string, the ORB returns a naming context object that is an object reference for the name service. The string "NameService" indicates:

  • The naming service will be persistent when using ORBD's naming service, as we do in this example.
  • The naming service will be transient when using tnameserv.

The proprietary string "TNameService" indicates that the naming service will be transient when using ORBD's naming service.

Narrowing the Object Reference

As with all CORBA object references, objRef is a generic CORBA object. To use it as a NamingContextExt object, you must narrow it to its proper type. The call to narrow() is just below the previous statement:

      NamingContextExt ncRef = NamingContextExtHelper.narrow(objRef);

Here you see the use of an idlj-generated helper class, similar in function to HelloHelper. The ncRef object is now an org.omg.CosNaming.NamingContextExt and you can use it to access the naming service and register the server, as shown in the next topic.

The NamingContextExt object is new to J2SE v.1.4, and is part of the Interoperable Naming Service specification.

Registering the Servant with the Name Server

Just below the call to narrow(), we create a new NameComponent array. Because the path to Hello has a single element, we create the single-element array that NamingContext.resolve requires for its work:

      String name = "Hello";
      NameComponent path[] = ncRef.to_name( name );

Finally, we pass path and the servant object to the naming service, binding the servant object to the "Hello" id:

      ncRef.rebind(path, href);

Now, when the client calls resolve("Hello") on the initial naming context, the naming service returns an object reference to the Hello servant.

Waiting for Invocation

The previous sections describe the code that makes the server ready; the next section explains the code that enables it to simply wait around for a client to request its service. The following code, which is at the end of (but within) the try-catch block, shows how to accomplish this.

      orb.run();

When called by the main thread, ORB.run() enables the ORB to perform work using the main thread, waiting until an invocation comes from the ORB. Because of its placement in main(), after an invocation completes and sayHello() returns, the server will wait again. This is the reason that the HelloClient explicitly shuts down the ORB after completing its task.

Compiling the Hello World Server

Now we will compile the HelloServer.java so that we can correct any errors before continuing with this tutorial.

Windows users note that you should substitute backslashes (\) for the slashes (/) in all paths in this document.

To compile HelloServer.java,

  1. Change to the Hello directory.

  2. Run the Java compiler on HelloServer.java:
    javac HelloServer.java HelloApp/*.java
  3. Correct any errors in your file and recompile if necessary.

  4. The files HelloServer.class and HelloImpl.class are generated in the Hello directory.

Running the Hello World Server

The document Running the Hello World Application discusses running HelloServer and the rest of the application.

Understanding The Server-Side Implementation Models

CORBA supports at least two different server-side mappings for implementing an IDL interface:

  • The Inheritance Model

    Using the Inheritance Model, you implement the IDL interface using an implementation class that also extends the compiler-generated skeleton.

    Inheritance models include:

    • The OMG-standard, POA. Given an interface My defined in My.idl, the file MyPOA.java is generated by the idlj compiler. You must provide the implementation for My and it must inherit from MyPOA, a stream-based skeleton that extends org.omg.PortableServer.Servant, which serves as the base class for all POA servant implementations.

      New in J2SE v.1.4: The default server-side mapping generated when either the -fall or -fserver arguments are used conform to Chapter 11, Portable Object Adapter (POA) of the CORBA 2.3.1 Specification (formal/99-10-07). For more information on the POA, link to Portable Object Adapter.

      The advantages of using the Portable Object Adaptor (POA) are:

      • Allow programmers to construct object implementations that are portable between different ORB products.
      • Provide support for objects with persistent identities.
      • Provide support for transparent activation of objects.
      • Allow a single servant to support multiple object identities simultaneously.

    • ImplBase. Given an interface My defined in My.idl, the file _MyImplBase.java is generated. You must provide the implementation for My and it must inherit from _MyImplBase.

      NOTE: ImplBase is deprecated in favor of the POA model, but is provided to allow compatibility with servers written in J2SE 1.3 and prior. We do not recommend creating new servers using this nonstandard model.

  • The Delegation Model

    Using the Delegation Model, you implement the IDL interface using two classes:

    • An IDL-generated Tie class that inherits from the compiler-generated skeleton, but delegates all calls to an implementation class.
    • A class that implements the IDL-generated operations interface (such as HelloOperations), which defines the IDL function.

    The Delegation model is also known as the Tie model, or the Tie Delegation model. It inherits from either the POA or ImplBase compiler-generated skeleton, so the models will be described as POA/Tie or ImplBase/Tie models in this document.

This tutorial presents the POA Inheritance model for server-side implementation. For tutorials using the other server-side implementations, see the following documents:

  • Java IDL: The "Hello World" Example with the POA/Tie Server-Side Model

    You might want to use the Tie model instead of the typical Inheritance model if your implementation must inherit from some other implementation. Java allows any number of interface inheritance, but there is only one slot for class inheritance. If you use the inheritance model, that slot is used up . By using the Tie Model, that slot is freed up for your own use. The drawback is that it introduces a level of indirection: one extra method call occurs when invoking a method.

  • Java IDL: The "Hello World" Example with the ImplBase Server-Side Model

    The ImplBase server-side model is an Inheritance Model, as is the POA model. Use the idlj compiler with the -oldImplBase flag to generate server-side bindings that are compatible with older version of Java IDL (prior to J2SE 1.4).

    Note that using the -oldImplBase flag is non-standard: these APIs are being deprecated. You would use this flag ONLY for compatibility with existing servers written in J2SE 1.3 or earlier. In that case, you would need to modify an existing MAKEFILE to add the -oldImplBase flag to the idlj compiler, otherwise POA-based server-side mappings will be generated.

For More Information
Exceptions: System Exceptions
Explains how CORBA system exceptions work and provides details on the minor codes of Java IDL's system exceptions
Developing Servers
Covers topics of interest to CORBA server programmers
Java IDL Naming Service
Covers the COS Naming Service in greater detail

Previous: Writing the Interface Definition
Next: Developing a Client Application
Tutorial home
Java IDL Home

Copyright © 1996-2001 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.


Running The "Hello World" Example on Two Machines

Java IDL: The "Hello World" Example on Two Machines

To enable the Hello World Tutorial to run on two machines, follow the steps as directed in the tutorial, with the following changes. This tutorial was written for the Java (tm) 2 Platform, Standard Edition (J2Se(tm)), version 1.4. In this example, the client, stubs, and skeletons are located on the client machine, and the server and name server are located on the server machine. This scenario can be changed to meet your needs and is provided simply as an introduction to one way to distribute an application across two machines.

  1. Create (as shown in the tutorial) and compile the Hello.idl file on the client machine:

   idlj -fall Hello.idl
  2. Create HelloClient.java on the client machine. Compile the *.java files, including the stubs and skeletons (which are in the directory HelloApp):
       javac *.java HelloApp/*.java

  3. Create HelloServer.java on the server machine. Compile the .java files:
       javac *.java

  4. Start the Java Object Request Broker Daemon, orbd, which includes a Naming Service, on the server machine. To do this on Unix:
       orbd -ORBInitialPort 1050 -ORBInitialHost servermachinename&

    To do this on Windows:

       start orbd -ORBInitialPort 1050 -ORBInitialHost servermachinename

    Both -ORBInitialPort and -ORBInitialHost are required arguments on the orbd command line. This example starts the name server on port 1050, because on Solaris you must become root to start a process on a port under 1024. If you want to use a different nameserverport, replace 1050 with the correct port number throughout this example.

    When using orbd, the ORBD must be run on the same machine as the machine on which the servers will be activated. Another Naming Service, tnameserv, could be used if you prefer to run the Naming Service on a machine other than the machine on which the servers will be activated.

  5. On the server machine, start the Hello server, as follows:
       java HelloServer -ORBInitialPort 1050

    If you used a different nameserverport, replace 1050 with the correct port number. You do not need to specify the -ORBInitialHost argument because the Hello server will be running on the same host as the name server in this example. If the Name Server were running on a different machine, you would specify which machine using the -ORBInitialHost nameserverhost argument.

  6. On the client machine, run the Hello application client. From a DOS prompt or shell, type:

       java HelloClient -ORBInitialHost nameserverhost -ORBInitialPort 1050

    Note that nameserverhost is the host on which the IDL name server is running. In this case, it is the server machine.

    If you used a different nameserverport, replace 1050 with the correct port number.

  7. Kill or stop orbd when finished. The name server will continue to wait for invocations until it is explicitly stopped.

Copyright Sun Microsystems 2001


Running the Hello World Application

This topic walks you through running the server and client program that together make up the "Hello World" application.

Running the Hello World Application

Despite its simple design, the Hello World program lets you learn and experiment with all the tasks required to develop almost any CORBA program that uses static invocation.

This example requires a naming service to make the servant object's operations available to clients. The server needs an object reference to the naming service so that it can publish the references to the objects implementing various interfaces. These object references are used by the clients for invoking methods. The two options for Naming Services shipped with J2SE v.1.4 are tnameserv, a transient naming service, and orbd, which is a daemon process containing a Bootstrap Service, a Transient Naming Service, a Persistent Naming Service, and a Server Manager. This example uses orbd.

When running this example, remember that, when using Solaris software, you must become root to start a process on a port under 1024. For this reason, we recommend that you use a port number greater than or equal to 1024. The -ORBInitialPort option is used to override the default port number in this example. The following instructions assume you can use port 1050 for the Java IDL Object Request Broker Daemon, orbd. You can substitute a different port if necessary. When running these examples on a Windows machine, subtitute a backslash (\) in path names.

To run this client-server application on your development machine:

  1. Start orbd.

    To start orbd from a UNIX command shell, enter:

      orbd -ORBInitialPort 1050 -ORBInitialHost localhost&

    From an MS-DOS system prompt (Windows), enter:

      start orbd -ORBInitialPort 1050 -ORBInitialHost localhost

    Note that 1050 is the port on which you want the name server to run. -ORBInitialPort is a required command-line argument. Note that when using Solaris software, you must become root to start a process on a port under 1024. For this reason, we recommend that you use a port number greater than or equal to 1024.

    Note that -ORBInitialHost is also a required command-line argument. For this example, since both client and server on running on the development machine, we have set the host to localhost. When developing on more than one machine, you will replace this with the name of the host. For an example of how to run this program on two machines, see The Hello World Example on Two Machines.

  2. Start the Hello server.

    To start the Hello server from a UNIX command shell, enter:

      java HelloServer -ORBInitialPort 1050 -ORBInitialHost localhost&

    From an MS-DOS system prompt (Windows), enter:

      start java HelloServer -ORBInitialPort 1050 -ORBInitialHost localhost

    For this example, you can omit -ORBInitialHost localhost since the name server is running on the same host as the Hello server. If the name server is running on a different host, use -ORBInitialHost nameserverhost to specify the host on which the IDL name server is running.

    Specify the name server (orbd) port as done in the previous step, for example, -ORBInitialPort 1050.

  3. Run the client application:

      java HelloClient -ORBInitialPort 1050 -ORBInitialHost localhost

    For this example, you can omit -ORBInitialHost localhost since the name server is running on the same host as the Hello client. If the name server is running on a different host, use -ORBInitialHost nameserverhost to specify the host on which the IDL name server is running.

    Specify the name server (orbd) port as done in the previous step, for example, -ORBInitialPort 1050.

  4. The client prints the string from the server to the command line:
    Hello world!!

The name server, like many CORBA servers, runs until you explicitly stop it. To avoid having many servers running, kill the name server process after the client application returns successfully. To do this from a DOS prompt, select the window that is running the server and enter Ctrl+C to shut it down. To do this from a Unix shell, find the process, and kill it.

Previous: Developing the Server
Previous: Developing the Client Application
Next: Using Stringified Object References
Java IDL Home
Copyright © 1996-2001 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.


Using Stringified Object References

Getting Started with Java IDL: Using Stringified Object References

This document was not updated for the J2SETM release. If you downloaded this document as part of the J2SETM documentation bundle, check the Web site at http://java.sun.com/j2se/1.4.2/docs/technotes/guides/idl/tutorial/GSstring.html for updates.

To invoke an operation on a CORBA object, a client application needs a reference to the object. You can get such references in a number of ways, such as calling ORB.resolve_initial_references() or using another CORBA object (like the name service). In previous sections of this tutorial, you used both of these methods to get an initial object reference.

Often, however, there is no naming service available in the distributed environment. In that situation, CORBA clients use a stringified object reference to find their first object.

When updated, this lesson will teach you how to create a stringified object reference as a part of the server startup, and how the client gets that reference and destringifies it for use as a real object reference.

Developing the Hello World Server

Developing the Client Application
Tutorial home
Home

Copyright © 2002 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.


Writing the Interface Definition

Getting Started with Java IDL:
Writing the Interface Definition

Note: All command and troubleshooting instructions apply to the Java 2 Platform, Standard Edition, version 1.4 and its version of idlj only.

Before you start working with Java IDL, you need to install version 1.4 of J2SE. J2SE v.1.4 provides the Application Programming Interface (API) and Object Request Broker (ORB) needed to enable CORBA-based distributed object interaction, as well as the idlj compiler. The idlj compiler uses the IDL-to-Java language mapping to convert IDL interface definitions to corresponding Java interfaces, classes, and methods, which you can then use to implement your client and server code.

This section teaches you how to write a simple IDL interface definition and how to translate the IDL interface to Java. It also describes the purpose of each file generated by the idlj compiler.

These topics are included in this section:

  1. Writing Hello.idl
  2. Understanding the IDL file
  3. Mapping Hello.idl to Java
  4. Understanding the idlj Compiler Output

Writing Hello.idl

 To create the Hello.idl file,
  1. Create a new directory, named Hello, for this application.

  2. Start your favorite text editor and create a file named Hello.idl in this directory.

  3. In your file, enter the code for the interface definition, Hello.idl:

    module HelloApp
{
  interface Hello
  {
    string sayHello();
    oneway void shutdown();
  };
};
  4. Save the file.

Understanding the IDL file

OMG IDL is the language used to describe the interfaces that client objects call and object implementations provide. An interface definition written in OMG IDL completely defines the interface and fully specifies each operation's parameters. An OMG IDL interface provides the information needed to develop clients that use the interface's operations.

Clients are written in languages for which mappings from OMG IDL concepts have been defined. The mapping of an OMG IDL concept to a client language construct will depend on the facilities available in the client language. OMG specifies a mapping from IDL to several different programming languages, including C, C++, Smalltalk, COBOL, Ada, Lisp, Python, and Java. When mapped, each statement in OMG IDL is translated to a corresponding statement in the programming language of choice.

For example, you could use the tool idlj to map an IDL interface to Java and implement the client class. When you mapped the same IDL to C++ and implemented the server in that language, the Java client (through the Java ORB) and C++ server (through the C++ ORB) interoperate as though they were written in the same language.

The IDL for "Hello World" is extremely simple; its single interface has but two operations. You need perform only three steps:

  1. Declare the CORBA IDL module
  2. Declare the interface
  3. Declare the operations

Declaring the CORBA IDL Module

A CORBA module is a namespace that acts as a container for related interfaces and declarations. It corresponds closely to a Java package. Each module statement in an IDL file is mapped to a Java package statement.

The module statement looks like this:

module HelloApp
{
    // Subsequent lines of code here.
};

When you compile the IDL, the module statement will generate a package statement in the Java code.

Declaring the Interface

Like Java interfaces, CORBA interfaces declare the API contract an object has with other objects. Each interface statement in the IDL maps to a Java interface statement when mapped.

In your Hello.idl file, the interface statement looks like this:

module HelloApp
{
  interface Hello  // These lines
  {                // declare the
                   // interface
  };               // statement.
};

When you compile the IDL, this statement will generate an interface statement in the Java code.

Declaring the Operations

CORBA operations are the behavior that servers promise to perform on behalf of clients that invoke them. Each operation statement in the IDL generates a corresponding method statement in the generated Java interface.

In your Hello.idl file, the operation statement looks like this:

module HelloApp
{
  interface Hello
  {
    string sayHello();        // This line is an operation statement.
    oneway void shutdown();   // This line is another
  };
};
The interface definition for our little "Hello World" application is now complete.

Mapping Hello.idl to Java

The tool idlj reads OMG IDL files and creates the required Java files. The idlj compiler defaults to generating only the client-side bindings. If you need both client-side bindings and server-side skeletons (as you do for our "Hello World" program), you must use the -fall option when running the idlj compiler. For more information on the IDL-to-Java compiler options, follow the link.

New in J2SE v.1.4: The default server-side mapping generated when either the -fall or -fserver arguments are used conform to Chapter 11, Portable Object Adapter (POA) of the CORBA 2.3.1 Specification (formal/99-10-07). For more information on the POA, link to Portable Object Adapter.

The advantages of using the Portable Object Adaptor (POA) are:

  • Allow programmers to construct object implementations that are portable between different ORB products.
  • Provide support for objects with persistent identities.
  • Provide support for transparent activation of objects.
  • Allow a single servant to support multiple object identities simultaneously.
  1. Make sure that the jdk/bin directory (or the directory containing idlj, java, javac, and orbd) are in your path.

  2. Go to a command line prompt.

  3. Change to the directory containing your Hello.idl file.

  4. Enter the compiler command:

    idlj -fall Hello.idl

If you list the contents of the directory, you will see that a directory called HelloApp has been created and that it contains six files. Open Hello.java in your text editor. Hello.java is the signature interface and is used as the signature type in method declarations when interfaces of the specified type are used in other interfaces. It looks like this:

//Hello.java
package HelloApp;

/**
* HelloApp/Hello.java
* Generated by the IDL-to-Java compiler (portable), version "3.0"
* from Hello.idl
*/

public interface Hello extends HelloOperations, org.omg.CORBA.Object,
org.omg.CORBA.portable.IDLEntity
{
} // interface Hello

With an interface this simple, it is easy to see how the IDL statements map to the generated Java statements.

IDL Statement | Java Statement
module HelloApp | package HelloApp;
interface Hello | public interface Hello

The single surprising item is the extends statement. All CORBA objects are derived from org.omg.CORBA.Object to ensure required CORBA functionality. The required code is generated by idlj; you do not need to do any mapping yourself.

In previous versions of the idlj compiler (known as idltojava), the operations defined on the IDL interface would exist in this file as well. Starting with J2SDK v1.3.0, in conformance with the CORBA 2.3.1 Specification (formal/99-10-07), the IDL-to-Java mapping puts all of the operations defined on the IDL interface in the operations interface, HelloOperations.java. The operations interface is used in the server-side mapping and as a mechanism for providing optimized calls for co-located clients and servers. For Hello.idl, this file looks like this:

//HelloOperations.java
package HelloApp;

/**
* HelloApp/HelloOperations.java
* Generated by the IDL-to-Java compiler (portable), version "3.0"
* from Hello.idl
*/

public interface HelloOperations
{
  String sayHello ();
  void Shutdown ();
} // interface HelloOperations

Because there are only two operations defined in this interface, it is easy to see how the IDL statements map to the generated Java statements.

IDL Statement | Java Statement
string sayHello(); | String sayHello();
oneway void shutdown(); | void Shutdown ();

Understanding the idlj Compiler Output

The idlj compiler generates a number of files. The actual number of files generated depends on the options selected when the IDL file is compiled. The generated files provide standard functionality, so you can ignore them until it is time to deploy and run your program. Under J2SE v.1.4, the files generated by the idlj compiler for Hello.idl, with the -fall command line option, are:

  • HelloPOA.java

    This abstract class is the stream-based server skeleton, providing basic CORBA functionality for the server. It extends org.omg.PortableServer.Servant, and implements the InvokeHandler interface and the HelloOperations interface. The server class, HelloServant, extends HelloPOA.

  • _HelloStub.java

    This class is the client stub, providing CORBA functionality for the client. It extends org.omg.CORBA.portable.ObjectImpl and implements the Hello.java interface.

  • Hello.java

    This interface contains the Java version of our IDL interface. The Hello.java interface extends org.omg.CORBA.Object, providing standard CORBA object functionality. It also extends the HelloOperations interface and org.omg.CORBA.portable.IDLEntity.

  • HelloHelper.java

    This class provides auxiliary functionality, notably the narrow() method required to cast CORBA object references to their proper types. The Helper class is responsible for reading and writing the data type to CORBA streams, and inserting and extracting the data type from Anys. The Holder class delegates to the methods in the Helper class for reading and writing.

  • HelloHolder.java

    This final class holds a public instance member of type Hello. Whenever the IDL type is an out or an inout parameter, the Holder class is used. It provides operations for org.omg.CORBA.portable.OutputStream and org.omg.CORBA.portable.InputStream arguments, which CORBA allows, but which do not map easily to Java's semantics. The Holder class delegates to the methods in the Helper class for reading and writing. It implements org.omg.CORBA.portable.Streamable.

  • HelloOperations.java

    This interface contains the methods sayHello() and shutdown(). The IDL-to-Java mapping puts all of the operations defined on the IDL interface into this file, which is shared by both the stubs and skeletons.

When you write the IDL interface, you do all the programming required to generate all these files for your distributed application. The next steps are to implement the client and server classes. In the steps that follow, you will create the HelloClient.java client class and the HelloServer.java server class.

Troubleshooting

  • Error Message: "idlj" not found

    If you try to run idlj on the file Hello.idl and the system cannot find idlj, it is most likely not in your path. Make certain that the location of idlj (the J2SDK v.1.4 bin directory) is in your path, and try again.

For More Information
  • IDL to Java Language Mapping Overview

    Provides the basics for mapping IDL constructs to the corresponding Java statements.

  • Chapter 3 of the OMG CORBA 2.3.1 specification, formal/99-10-07

    Provides the complete specification for OMG Interface Definition Language. At this writing, the specification can be downloaded from http://cgi.omg.org/c gi-bin/doc?formal/99-10-07.

Next: Developing the Hello World Server
Previous: Getting Started with Java IDL
Java IDL Home

Copyright © 2001 Sun Microsystems, Inc., 901 San Antonio Rd., Palo Alto, CA. 94303-4900, USA., All rights reserved.


Java Image I/O Technology

Java

JavaTM Image I/O Technology

 Documentation Contents
The JavaTM Image I/O API, developed through JSR-015, provides a pluggable architecture for working with images stored in files and accessed across the network. It offers substantially more flexibility and power than the previous APIs for loading and saving images.

The API provides provides a framework for the addition of format-specific plugins. Plug-ins for several common formats are included with Java Image I/O, but third parties can use this API to create their own plugins to handle special formats.

API Specification

The Java Image I/O API Specification consists of the following packages:

  • javax.imageio - the basic classes and interfaces for describing the contents of image files, including metadata and thumbnails; controlling the image reading and writing process; performing transcoding between formats; and reporting errors.
  • javax.imageio.event - interfaces for dealing with synchronous notification of events during the reading and writing of images.
  • javax.imageio.metadata - classes and interfaces for reading and writing image metadata.
  • javax.imageio.plugins.bmp - a support class for the built-in BMP reader and writer plug-ins.
  • javax.imageio.plugins.jpeg - some support classes for the built-in JPEG reader and writer plug-ins.
  • javax.imageio.spi - service-provider interfaces for: readers, writers, transcoders; and includes a runtime registry.
  • javax.imageio.stream - classes and interfaces for low-level I/O from files and streams.

Tutorials and Programmer's Guides

  • The Java Image I/O API Guide describes the API in more detail and demonstrates how to use Java Image I/O to read and write images and write custom plug-ins.

API Enhancements

  • Java Image I/O Enhancements in J2SE TM 5.0

More Information

See the Java Software websites:
  • JSR-015 Image I/O Framework Specification
  • The Java 2D Home Page
  • Java Advanced Imaging
  • The JFC Home Page

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun
Java Software


New Java Image I/O Features in J2SE 5.0

Java

New JavaTM Image I/O Features in
J2SETM 5.0

Documentation Contents

Image I/O Support for BMP and WBMP Formats

The bug reports that correspond to this change are: 4339462 and 4339384

This change adds readers and writers for BMP and WBMP formats to the Image I/O system. As of J2SE 5.0, all implementations of javax.imageio provide support for reading and writing JPEG, PNG, BMP, and WBMP images, and for reading GIF images.

For more information, see the API documentation for the javax.imageio.plugins.bmp package and javax.imageio.plugins.bmp.BMPImageWriteParam class. Further details are in the metadata descriptions of the BMP and WBMP formats.

Improved Performance

The bug reports that correspond to this change are: 4827358, 4867874, and 4868479

These changes improve the Image I/O system's performance and memory usage when reading and writing JPEG images. The changes do not affect the Image I/O API.

Copyright © 2002-2004 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: jsr015-comments@sun.com 		Sun Microsystems, Inc
Java Software


1 - Introduction

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

1.4 Target Audience

The API is intended to be used in a variety of contexts. Client-side applications may use it to load image data from local disk files or across the network. Server-side applications may use it to generate images dynamically in response to client requests, for example by using the Servlet API. The Image I/O API may be used in conjunction with other APIs such as Java Advanced Imaging, Java3D, and the Java Media Framework in order to build sophisticated multimedia applications.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


1 - Introduction

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

CHAPTER 1

Introduction

1.1 The Java Image I/O API

The Java Image I/O API provides a pluggable architecture for working with images stored in files and accessed across the network. It offers substantially more flexibility and power than the previously available APIs for loading and saving images.

The API provides a framework for the addition of format-specific plug-ins. Plug-ins for several common formats will be included with the standard Java SDK; other plug-ins will be available from Sun and from third parties. A voting process has been established where Java developers may indicate their interest in particular formats. See:

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


1 - Introduction

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

1.5 Acknowledgements

The authors would like to thank the following members of the expert group and others who provided valuable assistance with the API design:

Bharti Agrawal, Troy Chinen, Shoji Hara, Fuji FilmSoft

David Clunie, Quintiles Intelligent Imaging

Bob Deen, NASA Jet Propulsion Laboratories

Thomas DeWeese, Eastman Kodak Corp.

Steve Levoe, NASA Jet Propulsion Laboratories

Todd Rowell, Oracle

Jeannette Hung and Ihtisham Kabir provided excellent front-line management and made it possible for the API and its implementation to be devloped with a minimum of red tape. Aastha Bhardwaj, Brian Burkhalter, Jerry Evans, Ivan Wong, and John Zimmerman provided invaluable technical assistance.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


1 - Introduction

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

1.2 About This Document

This document is a brief guide to the API and its goals, including some simple programming examples. However, this document is not intended to be a complete guide to the API. The definitive guide to the specification is the automatically-generated ("javadoc") API documentation. In all cases, the automatically-generated documentation takes precedence over the descriptive materal in this document.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


1 - Introduction

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

1.3 Platforms

The API will be a standard part of the "Merlin" release of the Java Platform Standard Edition (J2SE version 1.4). Sun will provide an implementation of the Java SE platform for the Solaris operating environment, Linux, and Microsoft Windows platforms. The availibility of a particular Java SE release on other platforms is determined by the platform vendor.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


2 - Goals

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

2.2 Non-Goals

Thread Safety
A particular instance of an ImageReader or ImageWriter is not required to support re-entrant (simultaneous) calls to its methods (with the exception of the abort method that requests current read or writes to halt). However, it must be possible for multiple instances of the same plug-in class to operate simultaneously. For the sake of brevity, we will only discuss reader plug-ins below.

Supporting full re-entrancy would require that the reader bundle all of its state information (e.g., the current input source) into a separate state object, which would allow methods in progress to continue to work with the settings that were in effect at the time they began, while allowing a separate thread to modify the state to be used by the next operation.

Rather than forcing each ImageReader to keep track of its state in this way, it is simpler to require the application to instantiate multiple instances of the same ImageReader class if it wishes to perform multithreaded processing. This means that the state of an ImageReader must be maintained using non-static instance variables only, which should not be a burden for plug-in developers.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


2 - Goals

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

CHAPTER 2

Goals

2.1 API Goals

The design of the Image I/O API was influenced by the desire to support a number of primary goals. Each goal provides the justification for a particular set of API features. These goals may be divided into those motivated mainly by the needs of client-side applications, and those motivated by the needs of server applications. Naturally, these primary goals represent only a fraction of the capabilities of the API. They are listed here in order to provide a sense of the motivations that went into the design of the API.

As a general rule of thumb, whenever a tradeoff between ease of use for application developers and plug-in developers was identified, the application developer was given a higher priority. Since relatively few users of the API are expected to write plug-ins, and even those developers who do write plug-ins will typically write no more than a handful in order to support formats of immediate use to them, it makes sense to push complexity into the plug-ins rather than into applications.

To ameliorate the complexity of plug-in development, some utility methods and implementation classes are provided that perform common functions. However, it is not possible to provide implementation classes to cover every situation, and providing an excessive number of utility classes and methods would increase the footprint for all API users even if they did not use non-standard plug-ins. We expect that plug-in developers will be able to incorporate source code from existing plug-ins and sample code into their plug-ins. While this might lead to some redundancy when using multiple, independently developed plug-ins, most users will probably use only a small number of plug-ins at a time in any case. Thus, we believe the cost of having to load code that might theoretically be shared but actually is not will tend to outweight the cost of loading some redundant code when many plug-ins are used.

2.1.1 Client-Side Application Goals

Pluggability
An application written to use the Image I/O API should be able to automatically take advantage of new plug-ins without any rewriting or recompilation. This requires that plug-ins follow, as much as possible, a set of format-neutral interfaces. However, every image format has unique properties and capabilities, which plug-ins must be able to expose to applications. This is accomplished by allowing plug-ins to extend a number of interfaces within the API. Applications that are unaware of the plug-in specific extensions may continue to make use of the normal plug-in capabilities, while aware applications may use the extended interfaces.

Both generic and plug-in specific access to metadata (non-image data) is supported by allowing plug-ins to provide access to metadata in multiple formats. These may include plug-in specific formats, a plug-in neutral format defined by the API, and industry standard formats.

Automatic and Manual Plug-in Installation and Selection
For simple applications that wish to load images without user intervention, it is important to allow a reader plug-in to be selected automatically based on file contents. However, it is desirable to avoid the loading and instantiation of complex classes unless they are needed. A plug-in must be able to determine whether it can handle a particular image without loading all of its code. In order to meet this goal, plug-ins are instantiated via a service provider interface mechanism that allows simple queries to be performed without loading the main body of plug-in code.

All of the bytecode (.class) files associated with a plug-in may be combined into a JAR file, which may be installed permanently into a Java Runtime Environment, or loaded dynamically using the application CLASSPATH mechanism.

Manual Plug-in Selection
Although automatic plug-in selection is convenient for many applications, it must be possible for more sophisticated applications to exercise greater control over the plug-in selection process. This is accomplished by means of a run-time registry of plug-ins that may be queried and manipulated by an application.

Network, Disk-based, and Direct I/O
Increasingly, applications must deal with both disk-based and network-based data. In many cases, even disk-based data must be dealt with in the form of an InputStream due to the needs of other APIs. The Image I/O API offers a set of interfaces that allow data from Files, InputStreams, or other sources to be handled in a unified manner while preserving the ability to seek backwards and forwards. The API is future-proofed to allow new I/O interfaces, including direct interfaces to image acquisition and output devices, to be used without rewriting application code.

Access to Metadata
The metadata stored alongside an image may be as important as the image data. The Java Image I/O API provides thorough yet flexible access to metadata. Since metadata may take many forms, and contain very specialized information, it is difficult to provide direct access to such metadata in a general-purpose API. Instead, the API requires plug-ins to cast their metadata into the form of an XML Document structure, possibly enhanced with Object references in addition to textual data. Once this has been done, the metadata may be accessed and edited using standard XML DOM (Document Object Model) interfaces. The syntax of the Documents will vary from plug-in to plug-in, but the structure may be traversed, displayed, and edited without specific knowledge of the plug-in being used.

Support for Advanced Applications
In order to support advanced applications, the API must provide access to features such as "thumbnail" images, multiple images stored in a file, muli-resolution imagery, and tiled imagery. It must provide the capability to decode portions of a larger image, and to perform subsampling during decoding in order to allow panning over very large images. When writing images, it must be possible to write image data piece-by-piece, without storing the entire image in memory at once.

2.1.2 Server Use Cases

Dynamic image generation
Modern web servers typically generate a large portion of their content dynamically. The Java Servlet and Java Server Pages (JSP) APIs provide portable ways to generate HTML pages in response to requests from web browsers. Just as unique, custom HTML may be generated for each user, it is possible to customize image content.

In many cases, image content must be generated dynamically. For example, consider supplying stock price charts. While it might be possible to generate and store a limited set of charts for each listed stock in advance, if the user is allowed to add customizations such as the time interval over which the price should be displayed, or a set of indices or other stocks against which the stock price should be compared, the number of possible images grows exponentially. Only a dynamic approach can possibly allow such customization.

Image Customization
Web images are typically one-size-fits-all, with the same image data being delivered regardless of the display capabilities of the receiver. The increasing use of wireless and handheld devices will require images that are customized for their limited bandwidth and display capabilities. Desktop computers have seen increases in their display resolution, causing many web images to appear too small. The lack of scalable images also causes problems for visually impaired users. Server-side image customization can be used to provide optimal images for all users, with the image resolution and color characteristics being chosen based on user preferences.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


3 - Writing Image I/O Applications

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

3.8 Handling Errors using IIOException

In the examples above, the possibility of fatal errors was not considered. Errors may result from a number of sources, including true I/O errors (e.g., file not found, file unreadable, file on corrupt media), security violations (e.g., no permission to read files from an applet), file format problems (file contents corrupted, file using a variant of the format that is not supported by the plug-in), or even bugs in the API implementation or in the plug-in.

The Image I/O API makes use of its own subclass of the standard IOException class, called IIOException. IIOExceptions are used to signal all errors encountered during the parsing of a source file (e.g., an incorrect checksum or an invalid value for a particular byte within the file), including true I/O errors that result in an IOException being thrown within the reader.

An IIOException contains a (non-localized) message describing the reason for the exception, as well as a reference to another Exception that was the cause of the IIOException, if one exists.

Thus, application code that attempts to provide graceful handling of errors will look something like:

File f = new File("c:\images\myimage.gif");
ImageInputStream iis = null;
try {
    iis = ImageIO.createImageInputStream(f);
} catch (IIOException iioe1) {
    System.out.println("Unable to create an input stream!");
    return;
}

reader.setInput(stream);
try {
    reader.read(0, param);
} catch (IIOException iioe2) {
    System.out.println("An error occurred during reading: " +
                 iioe2.getMessage());
    Throwable t = iioe2.getCause();
    if ((t != null) && (t instanceof IOException)) {
        System.out.println("Caused by IOException: " +
                           t.getMessage());
    }
}

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


3 - Writing Image I/O Applications

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

3.5 Handling Metadata

Data stored in an image file that does not represent actual pixel values is referred to as metadata. The javax.imageio.metadata package contains classes and interfaces for accessing metadata.

Metadata may contain complex, hierarchical structures. The Java XML Document Object Model (DOM) API is used to represent these structures, allowing developers to leverage their knowledge of these interfaces.

The Image I/O API differentiates between stream metadata, which is associated with all images stored in an image file, and image metadata which is associated with a single image. For image formats that contain a single image, only image metadata is used.

Metadata may be obtained by calling the ImageReader.getStreamMetadata and getImageMetadata(int imageIndex) methods. These return an object that implements the IIOMetadata interface. The actual class type of the returned object is up to the ImageReader, and will usually be a unique class used only by that reader. This object should be designed to store as much of the metadata allowed by the format as possible, as losslessly as possible. However, this fidelity to the specifications of the image format comes at a cost, as access to the metadata becomes format-specific.

In order to allow access to the metadata without the need for format-specific application code, IIOMetadata objects expose their internal information in the form of an XML DOM structure, which is essentially a tree of nodes of various types that may contain a set of attributes (String values accessed by name), and which may reference a set of child nodes.

A single plug-in may support multiple document formats, which are distinguished by a format name. Typically, at least two formats will be supported by a given plug-in. The first is a common, plug-in neutral format called com.sun.imageio_1.0, which is defined in the class comment for the IIOMetadata interface. The second will be a highly plug-in specific format that exposes all of the internal structure of the IIOMetadata object in the form of a DOM. The latter format is referred to as the native format of the plug-in; its name may be determined by calling the getNativeMetadataFormatName method of the IIOMetadata object returned by the reader (advanced users may call a method of the same name on the ImageReaderSpi object used to instantiate the reader. The latter approach is useful for selecting a plug-in based on its support for a particular format). The names of all of the supported document formats may be determined similarly by calling getMetadataFormatNames.

The contents of an IIOMetadata object may be accessed in the form of a tree of XML Node objects by calling its getAsTree method. This method takes a String argument which is the name of one of the document formats supported by the plug-in. This document may then be manipulated as a standard XML DOM tree.

As an example, to print the contents of an XML DOM tree, the following code may be used:

public void displayMetadata(Node root) {
    displayMetadata(root, 0);
}

void indent(int level) {
    for (int i = 0; i < level; i++) {
        System.out.print("  ");
    }
}

void displayMetadata(Node node, int level) {
    indent(level); // emit open tag
    System.out.print("<" + node.getNodeName());
    NamedNodeMap map = node.getAttributes();
    if (map != null) { // print attribute values
        int length = map.getLength();
        for (int i = 0; i < length; i++) {
            Node attr = map.item(i);
            System.out.print(" " + attr.getNodeName() +
                             "=\"" + attr.getNodeValue() + "\"");
        }
    }

    Node child = node.getFirstChild();
    if (child != null) {
        System.out.println(">"); // close current tag
        while (child != null) { // emit child tags recursively
            displayMetadata(child, level + 1);
            child = child.getNextSibling();
        }
        indent(level); // emit close tag
        System.out.println("</" + node.getNodeName() + ">");
    } else {
        System.out.println("/>");
    }
}
Executing displayMetadata on the metadata from the standard PNG test image http://www.schaik.com/pngsuite/ccwn2c08.png yields the output:

<com.sun.imageio.png_1.0>
  <IHDR width="32" height="32" bitDepth="8" colorType="RGB"
compressionMethod="deflate" filterMethod="adaptive" interlaceMethod="none"/>
  <cHRM whitePointX="31270" whitePointY="32900" redX="64000" redY="33000"
greenX="30000" greenY="60000" blueX="15000" blueY="6000"/>
  <gAMA value="100000"/>
</com.sun.imageio.png_1.0>
We see that the image contains IHDR, cHRM, and gAMA chunks. The interpretation of the attribute values requires an understanding of the PNG format; however, it is still possible for an application that does not understand PNG internals to display the values and allow them to be edited interactively.

3.5.1 The IIOMetadataFormat Interface

An IIOMetadataFormat object is used to describe the legal structure of a metadata document format. It constrains the types of nodes that may appear, the types of nodes that may be children of a node of a given type, the names and data types of the attributes that may appear at a node of a given type, and the audiotape of an Object value that may be stored at a node of a given type. In XML terms, the information provided by the IIOMetadataFormat interface is somewhere in between a DTD (Document Type Definition), which gives information about node types, children, and attributes, and an XML Schema, which provides detailed information about data types.

For simplicity, only a subset of legal DTD structures can be described by IIOMetadataFormat. For example, the children of a node may be defined in an IIOMetadataFormat as a sequence in which each child must appear once (a, b, c), a sequence in which each child is optional (a?, b?, c?), a choice of a single child (a | b | c), or a repetition of a single node type (a)*, whereas a DTD allows many more combinations.

A node may not contain any textual data, but may contain a reference to an arbitrary Object. The IIOMetadataFormat indicates the class type and optionally the legal enumerated values or a range of values for the Object. Arrays are supported as well.

A DTD does not allow any attribute data types other than character strings; an XML Schema allows extremely complex data types to be built up from simpler ones. IIOMetadataFormat occupies a middle ground; it allows attributes to be constrained to belong to one of a predefined set of simple data types, including integers, floating-point decimals, and dates. Lists of these data types are also allowed.

Since an IIOMetadataFormat might be used to automatically construct a user interface for displaying and editing metadata, restricted the set of legal structures greatly simplifies the mapping between formats and user interface designs.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


3 - Writing Image I/O Applications

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

3.6 Transcoding

Transcoding refers to reading an image file with a reader plug-in, and writing out the image using a writer plug-in, especially, if the writer plug-in cannot directly understand the native metadata format of the reader. In such a case, there will always be some loss of information, even if both plug-ins deal with the same file format. A transcoder plug-in is responsible for converting the stream and image metadata that have been created by a reader plug-in into a better form for use by a writer plug-in. The API does not mandate the presence of any transcoder plug-ins, but they may be installed and registered just like readers and writers.

A set of reader and writer plug-ins may be designed to interpret each other's metadata without the need for a separate transcoder. The relationships between plug-ins can be determined using the ImageReaderSpi.getImageWriterSpiNames and ImageWriterSpi.getImageReaderSpiNames methods, which indicate which plug-ins are known to work well with a given plug-in of the opposite type. If multiple plug-ins are being written by a single vendor, this mechanism will provide the best quality.

However, when working with plug-ins that have not been designed to interoperate, a transcoder plug-in may be provided by a developer who understands the metadata formats of a given pair of reader and writer plug-ins, even though each was written without knowledge of the other.

Given a particular pair of reader and writer plug-ins, the set of appropriate transcoder plug-ins may be located as follows:

ImageReader reader;
ImageWriter writer;

Iterator transcoders = ImageIO.getImageTranscoders(reader, writer);

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


3 - Writing Image I/O Applications

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

3.3 ImageReader

Rather than using the ImageIO class to perform the entire decoding operation, an application may use the ImageIO class to obtain an ImageReader object that may be used to perform the read:

Iterator readers = ImageIO.getImageReadersByFormatName("gif");
ImageReader reader = (ImageReader)readers.next();
Readers may also be retrieved based on file contents, file suffix, or MIME type. The mechanism for locating and instantiating the reader makes use of the javax.imageio.spi.ImageReaderSpi class, which allows information about a reader plug-in to be retrieved without actually instantiating the plug-in. The notion of "service provider interfaces" (SPIs) is described in detail in the following chapter.

Once a reader has been obtained, it must be supplied with an input source. Most readers are able to read from an ImageInputStream, which is a special input source that is defined by the Image I/O API. A special input source is used in order to make it simple for reader and writers to work with both file and streaming I/O.

Obtaining an ImageInputStream is straightforward. Given an input source in the form of a File or InputStream, an ImageInputStream is produced by the call:

Object source; // File or InputStream
ImageInputStream iis = ImageIO.createImageInputStream(source);
Once a source has been obtained, it may be attached to the reader by calling

reader.setInput(iis, true);
The second parameter should be set to false if the source file contains multiple images and the application is not guaranteed to read them in order. For file formats that allow only a single image to be stored in a file, it is always legal to pass in a value of true.

Once the reader has its input source set, we can use it to obtain information about the image without necessarily causing image data to be read into memory. For example, calling reader.getImageWidth(0) allows us to obtain the width of the first image stored in the file. A well-written plug-in will attempt to decode only as much of the file as is necessary to determine the image width, without reading any pixels.

To read the image, the application may call reader.read(imageIndex), where imageIndex is the index of the image within the file. This produces the same result as if it had called ImageIO.read, as shown above.

3.3.1 ImageReadParam

More control may be obtained by supplying the read method with an additional parameter of type ImageReadParam. An ImageReadParam allows the application to specify a destination image in which the decoded image data should be stored, allowing better control over memory use. It also allows a region of interest to be specified, as well as subsampling factors that may be used to obtain a scaled-down version of the image.

When a source region is set, the reader plug-in will attempt to decode only the desired region, to the extent that the file format allows partial decoding. In any case, no pixels outside the region will appear in the output. This capability makes it possible to work with extremely large images in a limited amount of memory.

For example, to decode only the upper-left quadrant of the image, the application first obtains an ImageReadParam that is suitable for use with the reader:

ImageReadParam param = reader.getDefaultReadParam();
Next, the source region of interest is set on the ImageReadParam:

import java.awt.Rectangle;
int imageIndex = 0;
int half_width = reader.getImageWidth(imageIndex)/2;
int half_height = reader.getImageHeight(imageIndex)/2;
Rectangle rect = new Rectangle(0, 0, half_width, half_height);
param.setSourceRegion(rect);
Finally, the image is read using the ImageReadParam:

BufferedImage bi = reader.read(imageIndex, param);
The result is a new BufferedImage whose width and height are equal to half those of the original image (rounding down if the image had an odd width or height).

The lower-right quadrant of the image may then be read into the same BufferedImage that was created to hold the upper-left quadrant, overwriting the previous pixel data:

param.setDestination(bi);
rect = new Rectangle(half_width, half_height, half_width, half_height);
param.setSourceRegion(rect);
BufferedImage bi2 = reader.read(0, param);
if (bi == bi2) {
    System.out.println("The same BufferedImage was used!");
} else {
    System.out.println("This can't happen!");
}
In practice, the application could simply call reader.read(0, param) without assigning the result anywhere, knowing that the pixels will be written into the existing BufferedImage bi.

As another example, to read every third pixel of the image, resulting in an image one-ninth the size of the original, subsampling factors may be set in the ImageReadParam:

param = reader.getDefaultImageParam();
param.setSourceSubsampling(3, 3, 0, 0);
BufferedImage bi3 = reader.read(0, param);

3.3.2 IIOParamController

A plug-in may optionally supply an IIOParamController object that may be used to set up an IIOReadParam (or IIOWriteParam) using a graphical user interface (GUI), or any other interface. A reader plug-in may attach an IIOParamController to any ImageReadParam objects that it creates:

ImageReadParam param = reader.getDefaultImageParam();
IIOParamController controller = param.getController();
if (controller != null) {
    controller.activate(param);
}
When the controller's activate method is called, it displays the GUI and handles user events such as slider movements and button presses. Typically the interface will contain an "OK" or "Apply" button, which when pressed will cause the activate method to return. The controller is responsible for calling methods on its associated ImageReadParam to update its state, either in response to each GUI event, or all at once prior to returning from activate.

3.3.3 Reading From Multi-Image Files

All the methods in the ImageReader class that deal with images take an imageIndex parameter. This parameter allows access to any of the images in a multi-image file.

The ImageReader.getNumImages method returns the number of images that are stored in the input file. This method takes a boolean parameter, allowSearch. Some image formats, notably GIF, do not provide any way to determine the number of images without reading the entire file. Since this may be costly, setting allowSearch to false will allow the reader to return a value of -1 instead of the actual number of images. If the parameter is true, the reader will always return the actual number of images.

Even if the number of images is not known by the application, it is still possible to call read(imageIndex); if the index is too large, the method will throw an IndexOutOfBoundsException. Thus, the application can request images with increasing indices until it receives an exception.

3.3.4 Reading "Thumbnail" Images

Some image formats allow a small preview image (or multiple previews) to be stored alongside the main image. These "thumbnail" images are useful for identifying image files quickly, without the need to decode the entire image.

Applications can determine how many thumbnail images associated with a particular image are available by calling:

reader.getNumThumbnails(imageIndex);
If a thumbnail image is present, it can be retrieved by calling:

int thumbailIndex = 0;
BufferedImage bi;
bi = reader.readThumbnail(imageIndex, thumbnailIndex);

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


3 - Writing Image I/O Applications

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

3.7 Listening for Events

As an image is being read or written, the plug-in may provide updates to the
application. The application may provide one or more classes that implement
interfaces from the javax.image.event package. Instances of these classes are then
added to the ImageReader or ImageWriter being used. For example,

class MyReadProgressListener implements IIOReadProgressListener {

    public MyReadProgressListener() {}

    public void imageStarted(ImageReader source) {
        System.out.println("Started reading!");
    }

    // Other methods from IIOReadProgressListener omitted
}

IIOReadProgressListener listener = new MyReadProgressListener();
reader.addIIOReadProgressListener(listener);
As the ImageReader.read method progresses, methods on listener will be called at various times to indicate how much of the image has been read. Because these methods are being called while ImageReader.read is active, they must not call most methods from the same ImageReader object. They may call ImageReader.abort(), which will cause ImageReader.read to return even if it is only partially complete.

3.7.1 The IIOReadProgressListener Interface

An IIOReadProgressListener may be used to provide simple status information during reading. An estimate of the percentage of completion of a read is provided, which may be used to update a Swing JProgressBar or other progress indicator, or to estimate the time remaining to read a large image.

The imageStarted method will be called at the start of the read. During the read, the imageProgress method will be called multiple times, each time with a different, increasing value for its percentageDone parameter. When the read is about to complete, the imageComplete method will be called.

Similarly, the thumbnailStarted, thumbnailProgress, and thumbnailComplete methods will be called during thumbnail reads.

Other methods exist to indicate the start and end of a sequence of image reads performed by the ImageReader.readAll method. Additionally, it is possible for an ongoing read to be aborted using the ImageReader.abort method; in this case, the listener's readAborted method will be called.

3.7.2 The IIOReadUpdateListener Interface

An IIOReadUpdateListener provides more detailed information on the progress of an image read. Some image formats allow interlaced or progressive encoding, in which a subset of the pixel data is made available quickly, so that a crude version of the image may be displayed while the remainder of the pixel data is still being received and decoded. A typical scheme might begin by sending only every fourth row, and only every fourth pixel in each of those rows, so that the initial image requires only one sixteenth of the total amount of data to be transmitted and decoded. If interlacing were not used, only the top one-sixteenth of the image would be displayed in the same amount of time. Thus, a person viewing an interlaced image will be able to get a sense of its contents much sooner than if a traditional left-to-right, top-to-bottom order were used.

By implementing the methods of the IIOReadUpdateListener interface, an application class can receive notification when groups of possibly non-contiguous pixels are ready to be displayed. These methods also receive a reference to the BufferedImage that is in the process of being filled in, which may be used to refresh the display to include the newly decoded pixels.

When decoding an interlaced or progressive image, the decoding proceeds in multiple passes. At the start of each pass, the listener's passStarted method will be called to indicate the set of pixels that may be overwritten during the following pass. This estimate is conservative; not every pixel in the region will necessarily be updated during the pass. As the pass progresses, the imageUpdate method will be called with arguments describing the region of pixels that have receive new values. This region is described by the coordinates of its upper-left corner, its width and height, and the spacing between the pixels that make up the pass (in the example above, both parameters would be equal to 4 for the initial pass). When a pass has completed, the passComplete method is called. Similar methods allow the progress of thumbnail image reads to be tracked.

3.7.3 The IIOReadWarningListener Interface

By attaching an IIOReadWarningListener to an ImageReader, information on non-fatal errors may be received. For example, a reader might detect a tag or chunk that should not be present. Even though the reader may choose to ignore the error and proceed with decoding, it may wish to inform the application that the input source was malformed, as this could indicate problems in the application that generated the images.

ImageReaders may specify a set of Locales for which they can provide localized warning messages. The set of available locales can be obtained from the reader's getAvailableLocales method. The desired locale should then be set by calling the reader's setLocale method prior to attaching the IIOReadWarningListener. Each listener will receive messages in the Locale that was in effect at the time it was attached to the reader.

3.7.4 The IIOWriteProgressListener and IIOWriteWarningListener Interfaces

The IIOWriteProgressListener and IIOWriteWarningListener interfaces function similarly to their reader counterparts.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


3 - Writing Image I/O Applications

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

CHAPTER 3

Writing Image I/O Applications

3.1 Reading and Writing Images

The javax.imageio.ImageIO class provides a set of static convenience methods that perform most simple Image I/O operations.

Reading an image that is in a standard format (GIF, PNG, or JPEG) is simple:

File f = new File("c:\images\myimage.gif");
BufferedImage bi = ImageIO.read(f);
The format of the image will be auto-detected by the API based on the contents of the file. Most image files contain a "magic number" in their first few bytes that identifies the file format. For formats that do not have a magic number, auto-detection may fail and somewhat more sophisticated application code will be needed.

Additional formats may be handled by installing JAR files containing plug-ins; the details are described in the next chapter. Once a plug-in has been installed, a new format will be understood automatically without any changes to the application code.

The set of formats available for reading can be obtained by calling ImageIO.getReaderFormatNames. This will return an array of Strings containing the names of the available formats, such as "gif" and "png."

Writing an image in a supported format is equally simple:

BufferedImage bi;
File f = new File("c:\images\myimage.png");
ImageIO.write(im, "png", f);
The list of supported formats may be obtained by calling ImageIO.getWriterFormatNames.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


3 - Writing Image I/O Applications

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

3.2 Going Further

The methods described above are sufficient for simple applications. However, the Image I/O API offers much more power for writing sophisticated applications. In order to make use of the advanced features of the API, applications will work directly with the ImageReader and ImageWriter classes that are part of the API.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


3 - Writing Image I/O Applications

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

3.4 The ImageWriter Class

Just as we obtained a list of ImageReaders for a particular format using a method from the ImageIO class, we can obtain a list of ImageWriters:

Iterator writers = ImageIO.getImageWritersByFormatName("png");
ImageWriter writer = (ImageWriter)writers.next();
Once an ImageWriter has been obtained, its destination must be set to an ImageOutputStream:

File f = new File("c:\images\myimage.png");
ImageOutputStream ios = ImageIO.createImageOutputStream(f);
writer.setOutput(ios);
Finally, the image may be written to the output stream:

BufferedImage bi;
writer.write(bi);

3.4.1 Writing Multiple Images

The IIOImage class is use to store references to an image, one or more thumbnail images, and metadata (non-image data) associated with the image. Metadata will be discussed below; for now, we will simply pass null as the value for the metadata-related parameters.

The ImageWriter class contains a write method that creates a new file from an IIOImage, and a writeInsert method that adds an IIOImage to an existing file . By calling the two in sequence a multi-image file may be written:

BufferedImage first_bi, second_bi;
IIOImage first_IIOImage = new IIOImage(first_bi, null, null);
IIOImage second_IIOImage = new IIOImage(second_bi, null, null);
writer.write(null, first_IIOImage, null);
if (writer.canInsertImage(1)) {
    writer.writeInsert(1, second_IIOImage, null);
} else {
    System.err.println("Writer can't append a second image!");
}

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


4 - Writing Image I/O Plug-ins

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

4.4 Writing Writer Plug-ins

MyFormatImageWriterSpi
The MyFormatImageWriterSpi call plays a similar role to the MyFormatImageReaderSpi class discussed in the previous section. However, instead of being responsible for determining whether a given stream can be read, it must deterine whether an image in memory can be written. Rather than inspecting the image itself, an ImageTypeSpecifier is used so that writers may be selected before an actual image is available.

package com.mycompany.imageio;

import java.io.IOException;
import java.util.Locale;
import javax.imageio.ImageWriter;
import javax.imageio.ImageTypeSpecifier;
import javax.imageio.spi.ImageWriterSpi;
import javax.imageio.stream.ImageInputStream;

public class MyFormatImageWriterSpi extends ImageWriterSpi {

    static final String vendorName = "My Company";
    static final String version = "1.0_beta33_build9467";
    static final String writerClassName =
        "com.mycompany.imageio.MyFormatImageWriter";
    static final String[] names = { "myformat" };
    static final String[] suffixes = { "myf" };
    static final String[] MIMETypes = { "image/x-myformat" };
    static final String[] readerSpiNames = {
        "com.mycompany.imageio.MyFormatImageReaderSpi" };

    static final boolean supportsStandardStreamMetadataFormat = false;
    static final String nativeStreamMetadataFormatName = null;
    static final String nativeStreamMetadataFormatClassName = null;
    static final String[] extraStreamMetadataFormatNames = null;
    static final String[] extraStreamMetadataFormatClassNames = null;
    static final boolean supportsStandardImageMetadataFormat = false;
    static final String nativeImageMetadataFormatName =
        "com.mycompany.imageio.MyFormatMetadata_1.0";
    static final String nativeImageMetadataFormatClassName =
        "com.mycompany.imageio.MyFormatMetadata";
    static final String[] extraImageMetadataFormatNames = null;
    static final String[] extraImageMetadataFormatClassNames = null;

    public MyFormatImageWriterSpi() {
        super(vendorName, version,
              names, suffixes, MIMETypes,
              writerClassName,
              STANDARD_OUTPUT_TYPE, // Write to ImageOutputStreams
              readerSpiNames,
              supportsStandardStreamMetadataFormat,
              nativeStreamMetadataFormatName,
              nativeStreamMetadataFormatClassName,
              extraStreamMetadataFormatNames,
              extraStreamMetadataFormatClassNames,
              supportsStandardImageMetadataFormat,
              nativeImageMetadataFormatName,
              nativeImageMetadataFormatClassName,
              extraImageMetadataFormatNames,
              extraImageMetadataFormatClassNames);
    }

    public boolean canEncodeImage(ImageTypeSpecifier imageType) {
        int bands = imageType.getNumBands();
        return bands == 1 || bands == 3;
    }

    public String getDescription(Locale locale) {
        // Localize as appropriate
        return "Description goes here";
    }

    public ImageWriter createWriterInstance(Object extension) {
        return new MyFormatImageWriter(this);
    }
}
MyFormatImageWriter

package com.mycompany.imageio;

import java.awt.Rectangle;
import java.awt.image.Raster;
import java.awt.image.RenderedImage;
import java.io.IOException;
import java.util.Iterator;
import javax.imageio.IIOException;
import javax.imageio.IIOImage;
import javax.imageio.ImageTypeSpecifier;
import javax.imageio.ImageWriteParam;
import javax.imageio.ImageWriter;
import javax.imageio.metadata.IIOMetadata;
import javax.imageio.spi.ImageWriterSpi;
import javax.imageio.stream.ImageOutputStream;

public class MyFormatImageWriter extends ImageWriter {

    ImageOutputStream stream = null;

    public MyFormatImageWriter(ImageWriterSpi originatingProvider) {
        super(originatingProvider);
    }

    public void setOutput(Object output) {
        super.setOutput(output);
        if (output != null) {
            if (!(output instanceof ImageOutputStream)) {
                throw new IllegalArgumentException
                    ("output not an ImageOutputStream!");
            }
            this.stream = (ImageOutputStream)output;
        } else {
            this.stream = null;
        }
    }
The ImageWriteParam returned by getDefaultWriteParam must be customized based on the writer's capabilities. Since this writer does not support tiling, progessive encoding, or compression, we pass in values of false or null as appropriate:

    // Tiling, progressive encoding, compression are disabled by default
    public ImageWriteParam getDefaultWriteParam() {
        return new ImageWriteParam(getLocale());
    }
The format only handles image metadata. The convertImageMetadata method does very little; it could be defined to interpret the metadata classes used by other plug-ins.

    public IIOMetadata getDefaultStreamMetadata(ImageWriteParam param) {
        return null;
    }

    public IIOMetadata
        getDefaultImageMetadata(ImageTypeSpecifier imageType,
                                ImageWriteParam param) {
        return new MyFormatMetadata();
    }

    public IIOMetadata convertStreamMetadata(IIOMetadata inData,
                                             ImageWriteParam param) {
        return null;
    }

    public IIOMetadata convertImageMetadata(IIOMetadata inData,
                                            ImageTypeSpecifier imageType,
                                            ImageWriteParam param) {
        // We only understand our own metadata
        if (inData instanceof MyFormatMetadata) {
            return inData;
        } else {
            return null;
        }
    }
The actual writing of the image requires first applying the source region, source bands, and subsampling factors from the ImageWriteParam. The source region and source bands may be handled by creating a child Raster. For simplicity, we extract a single Raster from the source image. If the source image is tiled, we can save memory by extracting smaller Rasters as needed.

    public void write(IIOMetadata streamMetadata,
                      IIOImage image,
                      ImageWriteParam param) throws IIOException {
        RenderedImage im = image.getRenderedImage();

        Rectangle sourceRegion =
            new Rectangle(0, 0, im.getWidth(), im.getHeight());
        int sourceXSubsampling = 1;
        int sourceYSubsampling = 1;
        int[] sourceBands = null;
        if (param != null) {
            sourceRegion =
                sourceRegion.intersection(param.getSourceRegion());
            sourceXSubsampling = param.getSourceXSubsampling();
            sourceYSubsampling = param.getSourceYSubsampling();
            sourceBands = param.getSourceBands();

            int subsampleXOffset = param.getSubsamplingXOffset();
            int subsampleYOffset = param.getSubsamplingYOffset();
            sourceRegion.x += subsampleXOffset;
            sourceRegion.y += subsampleYOffset;
            sourceRegion.width -= subsampleXOffset;
            sourceRegion.height -= subsampleYOffset;
        }

        // Grab a Raster containing the region of interest
        int width = sourceRegion.width;
        int height = sourceRegion.height;
        Raster imRas = im.getData(sourceRegion);
        int numBands = imRas.getNumBands();

        // Check that sourceBands values are in range
        if (sourceBands != null) {
            for (int i = 0; i < sourceBands.length; i++) {
                if (sourceBands[i] >= numBands) {
                    throw new IllegalArgumentException("bad band!");
                }
            }
        }

        // Translate imRas to start at (0, 0) and subset the bands
        imRas = imRas.createChild(sourceRegion.x, sourceRegion.y,
                                  width, height,
                                  0, 0,
                                  sourceBands);

        // Reduce width and height according to subsampling factors
        width = (width + sourceXSubsampling - 1)/sourceXSubsampling;
        height = (height + sourceYSubsampling - 1)/sourceYSubsampling;

        // Assume 1 band image is grayscale, 3 band image is RGB
        int colorType;
        if (numBands == 1) {
            colorType = MyFormatImageReader.COLOR_TYPE_GRAY;
        } else if (numBands == 3) {
            colorType = MyFormatImageReader.COLOR_TYPE_RGB;
        } else {
            throw new IIOException("Image must have 1 or 3 bands!");
        }
Once the image dimensions and color type of the image have been ascertained, the plug-in is ready to write the file header:

        try {
            byte[] signature = {
                (byte)'m', (byte)'y',  (byte)'f', (byte)'o',
                (byte)'r', (byte)'m',  (byte)'a', (byte)'t'
            };
            // Output header information
            stream.write(signature);
            stream.write(`\n');
            stream.writeInt(width);
            stream.writeInt(height);
            stream.writeByte(colorType);
            stream.write(`\n');
Next, the plug-in extracts the image metadata from the write method's IIOImage argument, and attempts to convert it into a MyFormatMetadata object by calling convertImageMetadata. If the result is non-null, the keywords and values are extracted from the metadata and written to the output:

            // Attempt to convert metadata, if present
            IIOMetadata imd = image.getMetadata();
            MyFormatMetadata metadata = null;
            if (imd != null) {
                ImageTypeSpecifier type =
                    ImageTypeSpecifier.createFromRenderedImage(im);
                metadata =
                    (MyFormatMetadata)convertImageMetadata(imd,
                                                           type,
                                                           null);
            }

            // Output metadata if present
            if (metadata != null) {
                Iterator keywordIter = metadata.keywords.iterator();
                Iterator valueIter = metadata.values.iterator();
                while (keywordIter.hasNext()) {
                    String keyword = (String)keywordIter.next();
                    String value = (String)valueIter.next();

                    stream.writeUTF(keyword);
                    stream.write(`\n');
                    stream.writeUTF(value);
                    stream.write(`\n');
                }
            }
            stream.writeUTF("END");
            stream.write(`\n');
Finally, the plug-in is ready to begin writing the pixel data. The image Raster is copied into an int array, one row at a time using the getPixels method. Then these values are subsampled using the horizontal subsampling factor, and copied into a byte array, which is written to the output with a single write call. The source row is then incremented by the vertical subsampling factor until the end of the source region is reached, and the output stream is flushed:

            // Output (subsampled) pixel values
            int rowLength = width*numBands;
            int xSkip = sourceXSubsampling*numBands;
            int[] rowPixels = imRas.getPixels(0, 0, width, 1,
                                              (int[])null);
            byte[] rowSamples = new byte[rowLength];

            // Output every (sourceYSubsampling)^th row
            for (int y = 0; y < height; y += sourceYSubsampling) {
                imRas.getPixels(0, y, width, 1, rowPixels);

                // Subsample horizontally and convert to bytes
                int count = 0;
                for (int x = 0; x < width; x += xSkip) {
                    if (colorType ==
                        MyFormatImageReader.COLOR_TYPE_GRAY) {
                        rowSamples[count++] = (byte)rowPixels[x];
                    } else {
                        rowSamples[count++] = (byte)rowPixels[x];
                        rowSamples[count++] =
                            (byte)rowPixels[x + 1];
                        rowSamples[count++] =
                            (byte)rowPixels[x + 2];
                    }
                }

                // Output a row's worth of bytes
                stream.write(rowSamples, 0, width*numBands);
            }
            stream.flush();
        } catch (IOException e) {
            throw new IIOException("I/O error!", e);
        }
    }
}

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


4 - Writing Image I/O Plug-ins

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

4.6 Writing Stream Plug-ins

The standard classes in the javax.imageio.stream package are able to create ImageInputStreams and ImageOutputStreams that:

  • Read from a File
  • Read from an InputStream, using a temporary File as a cache
  • Read from an InputStream, using a byte array in memory as a cache
  • Write to a File
  • Write to an OutputStream, using a temporary File as a cache
  • Write to an OutputStream, using a byte array in memory as a cache
It is possible to write new implementations of ImageInputStream and InmageOutputStream that interface with other I/O primitives (for example, databases or future fast I/O interfaces). The ImageInputStreamImpl and ImageOutputStreamImpl classes provide a base for subclassing. Only a handful of methods are required to be implemented by the subclass, although it is possible to implement more for greater efficiency:

  • int read()
  • int read(byte[] b, int off, int len)
  • write(int b)
  • write(byte[] b, int off, int len)
  • seek(long pos)

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


4 - Writing Image I/O Plug-ins

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

CHAPTER 4

Writing Image I/O Plug-ins

4.1 The Plug-in Concept

The Image I/O API is designed as a pluggable framework into which any developer may add their own "plug-ins." A plug-in is defined as a set of Java language classes which may be loaded into the API at run-time and which add functionality to the AP I. In the context of the Java Image I/O API, a plug-in may provide the ability to read image data from a new file format, to write image data in a new format, to "transcode" non-image metadata between two formats, or to read or write streaming dat a from or to a new data source or sink. A plug-in may also provide support for the same format as another plug-in, perhaps providing better performance, more features, or a different view of the data stored by the format.

In order for plug-ins to be added to a running JavaTM Virtual Machine*, they must be compiled into Java bytecode files (class files). These class files will contain the code for subclasses of various classes defined by the API. For example, a plug-in that pr ovides the capability to read images will include a new subclass of the abstract javax.imageio.ImageReader class defined by the API. The usual reversed Internet domain name convention may be used to guarantee uniqueness of class names.

Because loading and instantiating an entire plug-in may be expensive, an additional class is used as a "stand-in" to provide information about the plug-in. This class may be used, for example, to determine what formats are handled by the plug-in p rior to actually instantiating the plug-in.

The "stand-in" object is lightweight enough that it can be loaded and a single instance instantiated every time the API is used within a given invocation of the Java virtual machine. This pattern, in which a small class is used to provide informat ion about an available service, is referred to as a "service provider interface."

* As used on this web site, the terms "Java Virtual Machine" or "JVM" mean a virtual machine for the Java platform.
CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


4 - Writing Image I/O Plug-ins

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

4.3 Writing Reader Plug-Ins

A minimal reader plug-in consists of an ImageReaderSpi subclass, and an ImageReader subclass. Optionally, it may contain implementations of the IIOMetadata interface representing the stream and image metadata, and an IIOMetadataFormat object describing the structure of the metadata.

In the following sections, we will sketch out the implementation of a simple reader plug-in for a hypothetical format called "MyFormat". It will consist of the classes MyFormatImageReaderSpi, MyFormatImageReader, and MyFormatMetadata.

The format itself is defined to begin with the characters `myformat\n', followed by two four-byte integers representing the width, height, and a single byte indicating the color type of the image, which may be either gray or RGB. Next, after a newline character, metadata values may stored as alternating lines containing a keyword and a value, terminated by the special keyword `END'. The string values are stored using UTF8 encoding followed by a newline. Finally, the image samples are stored in left-to-right, top-to-bottom order as either byte grayscale values, or three bytes representing red, green, and blue.

MyFormatImageReaderSpi
The MyFormatImageReaderSpi class provides information about the plug-in, including the vendor name, plug-in version string and description, format name, file suffixes associated with the format, MIME types associated with the format, input source classes that the plug-in can handle, and the ImageWriterSpis of plug-ins that are able to interoperate specially with the reader. It also must provide an implementation of the canDecodeInput method, which is used to locate plug-ins based on the contents of a source image file.

The ImageReaderSpi class provides implementations of most of its methods. These methods mainly return the value of various protected instance variables, which the MyFormatImageReaderSpi may set directly or via the superclass constructor, as in the example below:

package com.mycompany.imageio;

import java.io.IOException;
import java.util.Locale;
import javax.imageio.ImageReader;
import javax.imageio.spi.ImageReaderSpi;
import javax.imageio.stream.ImageInputStream;

public class MyFormatImageReaderSpi extends ImageReaderSpi {

    static final String vendorName = "My Company";
    static final String version = "1.0_beta33_build9467";
    static final String readerClassName =
        "com.mycompany.imageio.MyFormatImageReader";
    static final String[] names = { "myformat" };
    static final String[] suffixes = { "myf" };
    static final String[] MIMETypes = {
        "image/x-myformat" };
    static final String[] writerSpiNames = {
        "com.mycompany.imageio.MyFormatImageWriterSpi" };

    // Metadata formats, more information below
    static final boolean supportsStandardStreamMetadataFormat = false;
    static final String nativeStreamMetadataFormatName = null
    static final String nativeStreamMetadataFormatClassName = null;
    static final String[] extraStreamMetadataFormatNames = null;
    static final String[] extraStreamMetadataFormatClassNames = null;
    static final boolean supportsStandardImageMetadataFormat = false;
    static final String nativeImageMetadataFormatName =
        "com.mycompany.imageio.MyFormatMetadata_1.0";
    static final String nativeImageMetadataFormatClassName =
        "com.mycompany.imageio.MyFormatMetadata";
    static final String[] extraImageMetadataFormatNames = null;
    static final String[] extraImageMetadataFormatClassNames = null;

    public MyFormatImageReaderSpi() {
        super(vendorName, version,
              names, suffixes, MIMETypes,
              readerClassName,
              STANDARD_INPUT_TYPE, // Accept ImageInputStreams
              writerSpiNames,
              supportsStandardStreamMetadataFormat,
              nativeStreamMetadataFormatName,
              nativeStreamMetadataFormatClassName,
              extraStreamMetadataFormatNames,
              extraStreamMetadataFormatClassNames,
              supportsStandardImageMetadataFormat,
              nativeImageMetadataFormatName,
              extraImageMetadataFormatNames,
              extraImageMetadataFormatClassNames);
        }

        public String getDescription(Locale locale) {
            // Localize as appropriate
            return "Description goes here";
        }

        public boolean canDecodeInput(Object input)
            throws IOException {
            // see below
        }

            public ImageReader createReaderInstance(Object extension) {
                return new MyFormatImageReader(this);
            }
    }
Most plug-ins need read only from ImageInputStream sources, since it is possible to "wrap" most other types of input with an appropriate ImageInputStream. However, it is possible for a plug-in to work directly with other Objects, for example an Object that provides an interface to a digital camera or scanner. This interface need not provide a "stream" view of the device at all. Rather, a plug-in that is aware of the interface may use it to drive the device directly.

The plug-in advertises which input classes it can handle via its getInputTypes method, which returns an array of Class objects. An implementation of getInputTypes is provided in the superclass, which returns the value of the inputTypes instance variable, which in turn is set by the seventh argument to the superclass constructor. The value used in the example above, STANDARD_INPUT_TYPE, is shorthand for an array containing the single element javax.imageio.stream.ImageInputStream.class, indicating that the plug-in accepts only ImageInputStreams.

The canDecodeInput method is responsible for determining two things: first, whether the input parameter is an instance of a class that the plug-in can understand, and second, whether the file contents appear to be in the format handled by the plug-in. It must leave its input in the same state as it was when it was passed in. For an ImageInputStream input source, the mark and reset methods may be used. For example, since files in the "MyFormat" format all begin with the characters `myformat', canDecodeInput may be implemented as:

public boolean canDecodeInput(Object input) {
    if (!(input instanceof ImageInputStream)) {
        return false;
    }

    ImageInputStream stream = (ImageInputStream)input;
    byte[] b = new byte[8];
    try {
        stream.mark();
        stream.readFully(b);
        stream.reset();
    } catch (IOException e) {
        return false;
    }

    // Cast unsigned character constants prior to comparison
    return (b[0] == (byte)'m' && b[1] == (byte)'y' &&
            b[2] == (byte)'f' && b[3] == (byte)'o' &&
            b[4] == (byte)'r' && b[5] == (byte)'m' &&
            b[6] == (byte)'a' && b[7] == (byte)'t');
}
MyFormatImageReader
The heart of a reader plug-in is its extension of the ImageReader class. This class is responsible for responding to queries about the images actually stored in an input file or stream, as well as the actual reading of images, thumbnails, and metadata. For simplicity, we will ignore thumbnail images in this example.

A sketch of some of the methods of a hypothetical MyFormatImageReader class is shown below:

package com.mycompany.imageio;

public class MyFormatImageReader extends ImageReader {

    ImageInputStream stream = null;
    int width, height;
    int colorType;

    // Constants enumerating the values of colorType
    static final int COLOR_TYPE_GRAY = 0;
    static final int COLOR_TYPE_RGB = 1;

    boolean gotHeader = false;

    public MyFormatImageReader(ImageReaderSpi originatingProvider) {
        super(originatingProvider);
    }

    public void setInput(Object input, boolean isStreamable) {
        super.setInput(input, isStreamable);
        if (input == null) {
            this.stream = null;
            return;
        }
        if (input instanceof ImageInputStream) {
            this.stream = (ImageInputStream)input;
        } else {
            throw new IllegalArgumentException("bad input");
        }
    }

    public int getNumImages(boolean allowSearch)
        throws IIOException {
        return 1; // format can only encode a single image
    }

    private void checkIndex(int imageIndex) {
        if (imageIndex != 0) {
            throw new IndexOutOfBoundsException("bad index");
        }
    }

    public int getWidth(int imageIndex)
        throws IIOException {
        checkIndex(imageIndex); // must throw an exception if != 0
        readHeader();
        return width;
    }

    public int getHeight(int imageIndex)
        throws IIOException {
        checkIndex(imageIndex);
        readHeader();
        return height;
    }
The getImageTypes Method
The reader is responsible for indicating what sorts of images may be used to hold the decoded output. The ImageTypeSpecifier class is used to hold a SampleModel and ColorModel indicating a legal image layout. The getImageTypes method returns an Iterator of ImageTypeSpecifiers:

    public Iterator getImageTypes(int imageIndex)
        throws IIOException {
        checkIndex(imageIndex);
        readHeader();

        ImageTypeSpecifier imageType = null;
        int datatype = DataBuffer.TYPE_BYTE;
        java.util.List l = new ArrayList();
        switch (colorType) {
        case COLOR_TYPE_GRAY:
            imageType = ImageTypeSpecifier.createGrayscale(8,
                                                           datatype,
                                                           false);
            break;

        case COLOR_TYPE_RGB:
            ColorSpace rgb =
                ColorSpace.getInstance(ColorSpace.CS_sRGB);
            int[] bandOffsets = new int[3];
            bandOffsets[0] = 0;
            bandOffsets[1] = 1;
            bandOffsets[2] = 2;
            imageType =
                ImageTypeSpecifier.createInterleaved(rgb,
                                                     bandOffsets,
                                                     datatype,
                                                     false,
                                                     false);
            break;
        }
        l.add(imageType);
        return l.iterator();
    }
Parsing the Image Header
Several of the methods above depend on a readHeader method, which is responsible for reading enough of the input stream to determine the width, height, and layout of the image. readHeader is defined so it is safe to be called multiple times (note that we are not concerned with multi-threaded access):

    public void readHeader() {
        if (gotHeader) {
            return;
        }
        gotHeader = true;

        if (stream == null) {
            throw new IllegalStateException("No input stream");
        }

        // Read `myformat\n' from the stream
        byte[] signature = new byte[9];
        try {
            stream.readFully(signature);
        } catch (IOException e) {
            throw new IIOException("Error reading signature", e);
        }
        if (signature[0] != (byte)'m' || ...) { // etc.
            throw new IIOException("Bad file signature!");
        }
        // Read width, height, color type, newline
        try {
            this.width = stream.readInt();
            this.height = stream.readInt();
            this.colorType = stream.readUnsignedByte();
            stream.readUnsignedByte(); // skip newline character
        } catch (IOException e) {
            throw new IIOException("Error reading header", e)
        }
    }
The actual reading of the image is handled by the read method:

    public BufferedImage read(int imageIndex, ImageReadParam param)
        throws IIOException {
        readMetadata(); // Stream is positioned at start of image data
Handling the ImageReadParam
The first section of the method is concerned with using a supplied ImageReadParam object to determine what region of the source image is to be read, what sort of subsampling is to be applied, the selection and rearrangement of bands, and the offset in the destination:

    // Compute initial source region, clip against destination later
    Rectangle sourceRegion = getSourceRegion(param, width, height);

    // Set everything to default values
    int sourceXSubsampling = 1;
    int sourceYSubsampling = 1;
    int[] sourceBands = null;
    int[] destinationBands = null;
    Point destinationOffset = new Point(0, 0);

    // Get values from the ImageReadParam, if any
    if (param != null) {
        sourceXSubsampling = param.getSourceXSubsampling();
        sourceYSubsampling = param.getSourceYSubsampling();
        sourceBands = param.getSourceBands();
        destinationBands = param.getDestinationBands();
        destinationOffset = param.getDestinationOffset();
    }
At this point, the region of interest, subsampling, band selection, and destination offset have been initialized. The next step is to create a suitable destination image. The ImageReader.getDestination method will return any image that was specified using ImageReadParam.setDestination, or else will create a suitable destination image using a supplied ImageTypeSpecifier, in this case determined by calling getImageTypes(0):

    // Get the specified detination image or create a new one
    BufferedImage dst = getDestination(param,
                                       getImageTypes(0),
                                       width, height);
    // Enure band settings from param are compatible with images
    int inputBands = (colorType == COLOR_TYPE_RGB) ? 3 : 1;
    checkReadParamBandSettings(param, inputBands,
                               dst.getSampleModel().getNumBands());
To reduce the amount of code we have to write, we create a Raster to hold a row's worth of data, and copy the pixels from that Raster into the actual image. In this way, band selection and the details of pixel formatting are taken care of, at the expense of an additional copy.

    int[] bandOffsets = new int[inputBands];
    for (int i = 0; i < inputBands; i++) {
        bandOffsets[i] = i;
    }
    int bytesPerRow = width*inputBands;
    DataBufferByte rowDB = new DataBufferByte(bytesPerRow);
    WritableRaster rowRas =
        Raster.createInterleavedRaster(rowDB,
                                       width, 1, bytesPerRow,
                                       inputBands, bandOffsets,
                                       new Point(0, 0));
    byte[] rowBuf = rowDB.getData();

    // Create an int[] that can a single pixel
    int[] pixel = rowRas.getPixel(0, 0, (int[])null);
Now we have a byte array, rowBuf, which can be filled in from the input data, and which is also the source of pixel data for the Raster rowRaster. We extract the (single) tile of the destination image, and determine its extent. Then we create child rasters of both the source and destination that select and order their bands according to the settings previously extracted from the ImageReadParam:

    WritableRaster imRas = dst.getWritableTile(0, 0);
    int dstMinX = imRas.getMinX();
    int dstMaxX = dstMinX + imRas.getWidth() - 1;
    int dstMinY = imRas.getMinY();
    int dstMaxY = dstMinY + imRas.getHeight() - 1;

    // Create a child raster exposing only the desired source bands
    if (sourceBands != null) {
        rowRas = rowRas.createWritableChild(0, 0,
                                            width, 1,
                                            0, 0,
                                            sourceBands);
    }

    // Create a child raster exposing only the desired dest bands
    if (destinationBands != null) {
        imRas = imRas.createWritableChild(0, 0,
                                          imRas.getWidth(),
                                          imRas.getHeight(),
                                          0, 0,
                                          destinationBands);
    }
Reading the Pixel Data
Now we are ready to begin read pixel data from the image. We will read whole rows, and perform subsampling and destination clipping as we proceed. The horizontal clipping is complicated by the need to take subsampling into account. Here we perform per-pixel clipping; a more sophisticated reader could perform horizontal clipping once:

    for (int srcY = 0; srcY < height; srcY++) {
        // Read the row
        try {
            stream.readFully(rowBuf);
        } catch (IOException e) {
            throw new IIOException("Error reading line " + srcY, e);
        }

        // Reject rows that lie outside the source region,
        // or which aren't part of the subsampling
        if ((srcY < sourceRegion.y) ||
            (srcY >= sourceRegion.y + sourceRegion.height) ||
            (((srcY - sourceRegion.y) %
              sourceYSubsampling) != 0)) {
            continue;
        }

        // Determine where the row will go in the destination
        int dstY = destinationOffset.y +
            (srcY - sourceRegion.y)/sourceYSubsampling;
        if (dstY < dstMinY) {
            continue; // The row is above imRas
        }
        if (dstY > dstMaxY) {
            break; // We're done with the image
        }

        // Copy each (subsampled) source pixel into imRas
        for (int srcX = sourceRegion.x;
             srcX < sourceRegion.x + sourceRegion.width;
             srcX++) {
            if (((srcX - sourceRegion.x) % sourceXSubsampling) != 0) {
                continue;
            }
            int dstX = destinationOffset.x +
                (srcX - sourceRegion.x)/sourceXSubsampling;
            if (dstX < dstMinX) {
                continue;  // The pixel is to the left of imRas
            }
            if (dstX > dstMaxX) {
                break; // We're done with the row
            }

            // Copy the pixel, sub-banding is done automatically
            rowRas.getPixel(srcX, 0, pixel);
            imRas.setPixel(dstX, dstY, pixel);
        }
    }
    return dst;
For performance, the case where sourceXSubsampling is equal to 1 may be broken out separately, since it is possible to copy multiple pixels at once:

    // Create an int[] that can hold a row's worth of pixels
    int[] pixels = rowRas.getPixels(0, 0, width, 1, (int[])null);

    // Clip against the left and right edges of the destination image
    int srcMinX =
        Math.max(sourceRegion.x,
                     dstMinX - destinationOffset.x + sourceRegion.x);
      int srcMaxX =
        Math.min(sourceRegion.x + sourceRegion.width - 1,
                 dstMaxX - destinationOffset.x + sourceRegion.x);
    int dstX = destinationOffset.x + (srcMinX - sourceRegion.x);
    int w = srcMaxX - srcMinX + 1;
    rowRas.getPixels(srcMinX, 0, w, 1, pixels);
    imRas.setPixels(dstX, dstY, w, 1, pixels);
There are several additional features that readers should implement, namely informing listeners of the progress of the read, and allowing the read process to be aborted from another thread.

Listeners
There are three types of listeners that may be attached to a reader: IIOReadProgressListener, IIOReadUpdateListener, and IIOReadWarningListener. Any number of each type may be attached to a reader by means of various add and remove methods that are implemented in the ImageReader superclass. ImageReader also contains various process methods that broadcast information to all of the attached listeners of a given type. For example, when the image read begins, the method processImageStarted(imageIndex) should be called to inform all attached IIOReadProgressListeners of the event.

A reader plug-in is normally responsible for calling processImageStarted and processImageComplete at the beginning and end of its read method, respectively. processImageProgress should be called at least every few scanlines with an estimate of the percentage completion of the read. It is important that this percentage never decrease during the read of a single image. If the reader supports thumbnails, the corresponsing thumbnail progress methods should be called as well. The processSequenceStarted and processSequenceComplete methods of IIOReadProgressListener only need to be called if the plug-in overrides the superclass implementation of readAll.

More advanced readers that process incoming data in multiple passes may choose to support IIOReadUpdateListeners, which receive more detauled information about which pixels have been read so far. Applications may use this information to perform selective updates of an on-screen image, for example, or to re-encode image data in a streaming fashion.

Aborting the Read Process
While one thread performs an image read, another thread may call the reader's abort method asynchronously. The reading thread should poll the reader's status periodically using the abortRequested method, and attempt to cut the decoding short. The partially decoded image should still be returned, although the reader need not make any guarantees about its contents. For example, it could contain compressed or encrypted data in its DataBuffer that does not make sense visually.

IIOReadProgressListener Example
A typical set of IIOReadProgressListener calls might look like this:

public BufferedImage read(int imageIndex, ImageReadParam param)
    throws IOException {
    // Clear any previous abort request
    boolean aborted = false;
    clearAbortRequested();

    // Inform IIOReadProgressListeners of the start of the image
    processImageStarted(imageIndex);

    // Compute xMin, yMin, xSkip, ySkip from the ImageReadParam
    // ...

    // Create a suitable image
    BufferedImage theImage = new BufferedImage(...);

    // Compute factors for use in reporting percentages
    int pixelsPerRow = (width - xMin + xSkip - 1)/xSkip;
    int rows = (height - yMin + ySkip - 1)/ySkip;
    long pixelsDecoded = 0L;
    long totalPixels = rows*pixelsPerRow;

    for (int y = yMin; y < height; y += yskip) {
        // Decode a (subsampled) scanline of the image
        // ...

        // Update the percentage estimate
        // This may be done only every few rows if desired
        pixelsDecoded += pixelsPerRow;
        processImageProgress(100.0F*pixelsDecoded/totalPixels);

        // Check for an asynchronous abort request
        if (abortRequested()) {
            aborted = true;
            break;
        }
    }

    // Handle the end of decoding
    if (aborted) {
        processImageAborted();
    } else {
        processImageComplete(imageIndex);
    }

    // If the read was aborted, we still return a partially decoded image
    return theImage;
}
Metadata
The next set of methods in MyFormatImageReader deal with metadata. Because our hypothetical format only encodes a single image, we may ignore the concept of "stream" metadata, and use "image" metadata only:

    MyFormatMetadata metadata = null; // class defined below

    public IIOMetadata getStreamMetadata()
        throws IIOException {
        return null;
    }

    public IIOMetadata getImageMetadata(int imageIndex)
        throws IIOException {
        if (imageIndex != 0) {
            throw new IndexOutOfBoundsException("imageIndex != 0!");
        }
        readMetadata();
        return metadata;
    }
The actual work is done by a format-specific method readMetadata, which for this format fills in the keyword/value pairs of the metadata object,

    public void readMetadata() throws IIOException {
        if (metadata != null) {
            return;
        }
        readHeader();
        this.metadata = new MyFormatMetadata();
        try {
            while (true) {
                String keyword = stream.readUTF();
                stream.readUnsignedByte();
                if (keyword.equals("END")) {
                    break;
                }
                String value = stream.readUTF();
                stream.readUnsignedByte();

                metadata.keywords.add(keyword);
                metadata.values.add(value);
            } catch (IIOException e) {
                throw new IIOException("Exception reading metadata",
                                       e);
            }
        }
    }
MyFormatMetadata
Finally, the various interfaces for extracting and editing metadata must be defined. We define a class called MyFormatMetadata that extends the IIOMetadata class, and additionally can store the keyword/value pairs that are allowed in the file format:

package com.mycompany.imageio;

import org.w3c.dom.*;
import javax.xml.parsers.*; // Package name may change in J2SDK 1.4

import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import javax.imageio.metadata.IIOInvalidTreeException;
import javax.imageio.metadata.IIOMetadata;
import javax.imageio.metadata.IIOMetadataFormat;
import javax.imageio.metadata.IIOMetadataNode;

public class MyFormatMetadata extends IIOMetadata {

    static final boolean standardMetadataFormatSupported = false;
    static final String nativeMetadataFormatName =
        "com.mycompany.imageio.MyFormatMetadata_1.0";
    static final String nativeMetadataFormatClassName =
        "com.mycompany.imageio.MyFormatMetadata";
    static final String[] extraMetadataFormatNames = null;
    static final String[] extraMetadataFormatClassNames = null;

    // Keyword/value pairs
    List keywords = new ArrayList();
    List values = new ArrayList();
The first set of methods are common to most IIOMetadata implementations:

    public MyFormatMetadata() {
        super(standardMetadataFormatSupported,
              nativeMetadataFormatName,
              nativeMetadataFormatClassName,
              extraMetadataFormatNames,
              extraMetadataFormatClassNames);
    }

    public IIOMetadataFormat getMetadataFormat(String formatName) {
        if (!formatName.equals(nativeMetadataFormatName)) {
            throw new IllegalArgumentException("Bad format name!");
        }
        return MyFormatMetadataFormat.getDefaultInstance();
    }
The most important method for reader plug-ins is getAsTree:

    public Node getAsTree(String formatName) {
        if (!formatName.equals(nativeMetadataFormatName)) {
            throw new IllegalArgumentException("Bad format name!");
        }

        // Create a root node
        IIOMetadataNode root =
            new IIOMetadataNode(nativeMetadataFormatName);

        // Add a child to the root node for each keyword/value pair
        Iterator keywordIter = keywords.iterator();
        Iterator valueIter = values.iterator();
        while (keywordIter.hasNext()) {
            IIOMetadataNode node =
                new IIOMetadataNode("KeywordValuePair");
            node.setAttribute("keyword", (String)keywordIter.next());
            node.setAttribute("value", (String)valueIter.next());
            root.appendChild(node);
        }

        return root;
    }
For writer plug-ins, the ability to edit metadata values is obtained by implementing the isReadOnly, reset, and mergeTree methods:

    public boolean isReadOnly() {
        return false;
    }

    public void reset() {
        this.keywords = new ArrayList();
        this.values = new ArrayList();
    }

    public void mergeTree(String formatName, Node root)
        throws IIOInvalidTreeException {
        if (!formatName.equals(nativeMetadataFormatName)) {
            throw new IllegalArgumentException("Bad format name!");
        }

        Node node = root;
        if (!node.getNodeName().equals(nativeMetadataFormatName)) {
            fatal(node, "Root must be " + nativeMetadataFormatName);
        }
        node = node.getFirstChild();
        while (node != null) {
            if (!node.getNodeName().equals("KeywordValuePair")) {
                fatal(node, "Node name not KeywordValuePair!");
            }
            NamedNodeMap attributes = node.getAttributes();
            Node keywordNode = attributes.getNamedItem("keyword");
            Node valueNode = attributes.getNamedItem("value");
            if (keywordNode == null || valueNode == null) {
                fatal(node, "Keyword or value missing!");
            }

            // Store keyword and value
            keywords.add((String)keywordNode.getNodeValue());
            values.add((String)valueNode.getNodeValue());

            // Move to the next sibling
            node = node.getNextSibling();
        }
    }

    private void fatal(Node node, String reason)
        throws IIOInvalidTreeException {
        throw new IIOInvalidTreeException(reason, node);
    }
}
MyFormatMetadataFormat
The tree structure of the metadata may be described using the IIOMetadataFormat interface. An implementation class, IIOMetadataFormatImpl, takes care of maintaining the "database" of information about elements, their attributes, and the parent-child relationships between them:

package com.mycompany.imageio;

import javax.imageio.ImageTypeSpecifier;
import javax.imageio.metadata.IIOMetadataFormatImpl;

public class MyFormatMetadataFormat extends IIOMetadataFormatImpl {

    // Create a single instance of this class (singleton pattern)
    private static MyFormatMetadataFormat defaultInstance =
        new MyFormatMetadataFormat();

    // Make constructor private to enforce the singleton pattern
    private MyFormatMetadataFormat() {
        // Set the name of the root node
        // The root node has a single child node type that may repeat
        super("com.mycompany.imageio.MyFormatMetadata_1.0",
              CHILD_POLICY_REPEAT);

        // Set up the "KeywordValuePair" node, which has no children
        addElement("KeywordValuePair",
                   "com.mycompany.imageio.MyFormatMetadata_1.0",
                   CHILD_POLICY_EMPTY);

        // Set up attribute "keyword" which is a String that is required
        // and has no default value
        addAttribute("KeywordValuePair", "keyword", DATATYPE_STRING,
                     true, null);
        // Set up attribute "value" which is a String that is required
        // and has no default value
        addAttribute("KeywordValuePair", "value", DATATYPE_STRING,
                     true, null);
    }

    // Check for legal element name
    public boolean canNodeAppear(String elementName,
                                 ImageTypeSpecifier imageType) {
        return elementName.equals("KeywordValuePair");
    }

    // Return the singleton instance
    public static MyFormatMetadataFormat getDefaultInstance() {
        return defaultInstance;
    }
}

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


4 - Writing Image I/O Plug-ins

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

4.2 Embedding Plug-ins in JAR Files

Since a plug-in consists of several classes, the JAR file mechanism is used to allow them to be combined into a single file. In addition to class files, JAR files may contain additional files used to describe their contents. In particular, a JAR file may contain a META-INF/services directory that is used to list any service providers that are contained in the file. For each service provider interface that is implemented by a class stored in the JAR file, a file whose name is the fully-qualified class name of the service provider interface is placed within the services directory. The file should contain the fully-qualified class names of the implementation classes present in the JAR file, one per line. For example, if the JAR file contains a service provider class named com.mycompany.mypackage.MyImageReaderSpi, which implements the javax.imageio.spi.ImageReaderSpi interface, there should be a file named META-INF/services/javax.imageio.spi.ImageReaderSpi containing the line com.mycompany.mypackage.MyImageReaderSpi.

The Image I/O API will automatically examine any JAR files that are found on the class path, and identify those that contain Image I/O plug-ins. For each plug-in found, a single instance of its service provider class will be instantiated and stored in a run-time registry class, javax.iamgeio.spi.IIORegistry.

JAR files on the application class path (i.e., the path set using the CLASSPATH variable), or elsewhere (e.g., available via a network URL) may be loaded by the application. They are not loaded by default in order to minimize startup time.

The javax.imageio.spi.IIORegistry class may also be used at run-time to deregister installed plug-ins and to register new ones. In particular, it is possible to use a ClassLoader to load a plug-in over the network, which may then be registered and used exactly like a locally installed plug-in.

Most applications should not need to deal directly with the registry. Instead, they may make use of convenience methods contained within the javax.imageio.ImageIO class that search for appropriate plug-ins automatically.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


4 - Writing Image I/O Plug-ins

CONTENTS | PREV | NEXT JavaTM Image I/O API Guide

4.5 Writing Transcoder Plug-ins

A transcoder plug-in consists of an ImageTranscoderSpi, which performs the same functions as do the Spi classes for other plug-ins, and an object that implements the ImageTranscoder interface:

IIOMetadata convertStreamMetadata(IIOMetadata inData,
                                  ImageWriteParam param);

IIOMetadata convertImageMetadata(IIOMetadata inData,
                                 ImageTypeSpecifier imageType,
                                 ImageWriteParam param);
The ImageTranscoder may use the standard interfaces to unpack the incoming metadata, or it may make use of interfaces that are specific to the actual object at hand. For example, it could access the keywords and values instance variables of the MyFormatMetadata class defined above; these were made public, but not documented, precisely in order to allow a transcoder plug-in developer to access them without having to go through a DOM representation.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


Java Image I/O API Guide

PREV | NEXT JavaTM Image I/O API Guide

1. Introduction
1.1 The Java Image I/O API
1.2 About This Document
1.3 Platforms
1.4 Target Audience
1.5 Acknowledgements
2. Goals
2.1 API Goals
2.1.1 Client-Side Application Goals
2.1.2 Server Use Cases
2.2 Non-Goals
3. Writing Image I/O Applications
3.1 Reading and Writing Images
3.2 Going Further
3.3 ImageReader
3.3.1 ImageReadParam
3.3.2 IIOParamController
3.3.3 Reading From Multi-Image Files
3.3.4 Reading "Thumbnail" Images
3.4 The ImageWriter Class
3.4.1 Writing Multiple Images
3.5 Handling Metadata
3.5.1 The IIOMetadataFormat Interface
3.6 Transcoding
3.7 Listening for Events
3.7.1 The IIOReadProgressListener Interface
3.7.2 The IIOReadUpdateListener Interface
3.7.3 The IIOReadWarningListener Interface
3.7.4 The IIOWriteProgressListener and IIOWriteWarningListener Interfaces
3.8 Handling Errors using IIOException
4. Writing Image I/O Plug-ins
4.1 The Plug-in Concept
4.2 Embedding Plug-ins in JAR Files
4.3 Writing Reader Plug-Ins
4.4 Writing Writer Plug-ins
4.5 Writing Transcoder Plug-ins
4.6 Writing Stream Plug-ins

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


Java Image I/O API Guide

CONTENTS | PREV | NEXT

JavaTM Image I/O API Guide

Phil Race, Dan Rice, Raúl Vera

April 2001

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


Input Method Client API Reference

The following classes are part of the input method client API:

  • java.awt.event
    • java.awt.event.InputMethodEvent
    • java.awt.event.InputMethodListener
  • java.awt.im
    • java.awt.im.InputContext
    • java.awt.im.InputMethodHighlight
    • java.awt.im.InputMethodRequests
    • java.awt.im.InputSubset

    In addition, the following classes and members in other frameworks support the input method client API:

  • java.awt
    • java.awt.AWTEvent
      • INPUT_METHOD_EVENT_MASK
    • java.awt.AWTEventMulticaster
      • add(InputMethodListener, InputMethodListener)
      • caretPositionChanged(InputMethodEvent)
      • inputMethodTextChanged(InputMethodEvent)
      • remove(InputMethodListener, InputMethodListener)
    • java.awt.Component
      • addInputMethodListener(InputMethodListener)
      • enableInputMethods(boolean)
      • getInputContext()
      • getInputMethodRequests()
      • processInputMethodEvent(InputMethodEvent)
      • removeInputMethodListener(InputMethodListener)
    • java.awt.Graphics
      • drawString(AttributedCharacterIterator, int, int)
    • java.awt.Toolkit
      • mapInputMethodHighlight
    • java.awt.Window
      • getInputContext()
  • java.awt.font
    • java.awt.font.TextAttribute
      • INPUT_METHOD_UNDERLINE
      • UNDERLINE_LOW_ONE_PIXEL
      • UNDERLINE_LOW_TWO_PIXEL
      • UNDERLINE_LOW_DOTTED
      • UNDERLINE_LOW_GRAY
      • UNDERLINE_LOW_DASHED
  • java.lang
    • java.lang.Character.Subset
  • java.text
    • java.text.Annotation
    • java.text.AttributedCharacterIterator
    • java.text.AttributedCharacterIterator.Attribute
    • java.text.AttributedString

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Contact us

Sun
Java Software


Input Method Client API Tutorial

Contents

  1. Implementing an Active Client Component
    • Handling Input Method Events
    • Handling Input Method Highlight Attributes
    • Handling Input Method Requests
    • Ending Input Operations
  2. Enhancing an Active Client Component
    • Handling Additional Text Attributes
    • Creating Private Input Contexts
    • Selecting Input Methods
    • Setting an Expected Character Subset
    • Using Engine-Specific Functionality
  3. Implementing a Non-Client
  4. Sample Code

1. Implementing an Active Client Component

The input method client API makes it possible for client components to implement integrated text input user interfaces such as on-the-spot input. The API defines events and methods that facilitate the communication between a client component and an input method. It also lets the client component request an input method for a particular language.

Since the API doesn't make any assumptions about how and where the text is drawn, it can also be used to implement other input styles such as over-the-spot editing. In this style, the composed text is drawn over surrounding text and covers it instead of being integrated and formatted with it.

Any client component class can become an active client of the input method client API and thus support an integrated text input user interface by performing the following steps:

  • Implement the InputMethodListener interface to handle incoming InputMethodEvents generated by the current input method, and register the listener.
  • Implement the InputMethodRequests interface and override getInputMethodRequests to return the request handler.
  • Store InputMethodHighlight attributes along with composed text and pass them on to the drawing routines.
  • End input operations when the user initiates an operation that requires all text to be committed.

Optionally, the client component can also use the following functionality:

  • Store other text attributes that are created by input methods, and return them when text is requested.
  • Create a private input context (instead of sharing one with other components in the same window).
  • Select input methods, for example, based on the language of the text being edited.
  • Set an expected character subset.

Client components don't need to deal with setting up input contexts, activating or deactivating contexts, or dispatching events to input methods, since all this is handled automatically by AWT.

Handling Input Method Events

The input method framework provides an event class, InputMethodEvent, to support the communication between input methods and text components. The class has two separate event kinds: text changed and caret changed. An event listener interface, InputMethodListener, supports these two events. An active client component must implement the InputMethodListener interface, register the listener, and handle both kinds of events.

InputMethodEvent instances are sent to the client component when there is a change to the user's input text, its highlighting, or to the caret location within the composed text. The event sent for caret-only changes is a simplified version of the one for text changes (it just doesn't have text information), so the following discussion assumes the text-changed event.

An event reporting a text change has a reference to an instance of AttributedCharacterIterator that represents either composed text or committed text or both together. The event's committed character count value specifies how many characters in the iterator's range are committed text; all remaining characters are composed text. Committed text always precedes composed text. If the component has no previous composed text, the committed and composed text replace any selected text or are inserted at the current insertion position of the component's text. If there is previous composed text, the entire previous composed text is replaced with the new committed and composed text. The insertion point moves to the end of the committed text. The client component is responsible for redrawing the updated text.

The event also contains information about the current caret location within the composed text (null if no caret is to be displayed), and about the part of the composed text that is most important to keep in view (null if the input method doesn't have a recommendation).

Handling Input Method Highlight Attributes

The text component generally draws the composed text as part of the text being edited, using its regular text layout and drawing functionality. However, it needs to add certain highlight style attributes to the composed text to indicate the current state of the composition. The framework defines these style attributes as abstract styles (for example, "unconverted unselected text" or "converted selected text"), and maps them internally to platform-dependent concrete styles (for example, 2-pixel gray underline).

Highlight attributes are represented by the InputMethodHighlight class. Instances of this class are used as attribute values of the AttributedCharacterIterator instances representing composed text. Text components must store these attributes with the composed text and pass them on to the drawing routines when drawing composed text. They can use either the drawString methods that accept AttributedCharacterIterator, or create a TextLayout from the iterator and use its draw method. These drawing methods interact with the input method framework to map abstract to concrete highlight styles. Text components using these methods therefore generally do not need to be concerned with the internal details of the input method highlights. If a text component uses some other mechanism to render the text, it should check the input method highlight for concrete style information, and, if none is provided, use Toolkit.mapInputMethodHighlight to map to a concrete style.

Some input methods may treat highlights as "annotations". Annotations are attributes that apply to a specified range of text, but not to subranges or the concatenation of ranges. They are represented by wrapping the InputMethodHighlight instance into an Annotation instance. Input methods may use annotation highlights to separate text segments that will be converted as separate units. On some platforms, these highlights are rendered so as to make the segments visible, for example, by using underlines with short breaks between the segments. Text components have to be able to handle input method highlights whether they are wrapped in Annotation instances or not. If a text component implements line wrapping, special care needs to be taken when the range to which a highlight annotation applies crosses a line boundary: The normal behavior (implemented, for example, in AttributedString) would be to discard the attribute because it doesn't apply to subranges. But, since in this case there's only a visual break and not a logical break, the highlight needs to be preserved - it has to be treated as if it applied to the subranges that are rendered on separate lines. One way to do this is by implementing the AttributedCharacterIterator in a way that returns highlight annotations even for subranges of the intended range.

Handling Input Method Requests

An input method needs to access component information to perform input operations. For example, an input method needs to know the location where a list of possible choices can be shown.

An active client component therefore must implement the InputMethodRequests interface, and override getInputMethodRequests to return the request handler. The interface includes methods to:

  • Perform conversions between screen coordinates and offsets within the composed text.
  • Obtain specified text of the component.
  • Cancel the latest committed text.
  • Obtain the insertion position within the component's committed text.

Ending Input Operations

Input methods typically recognize some user actions that end input operations, for example, an operation that commits all uncommitted text. However, there are also user actions that start operations for which input operations should be ended, but that an input method cannot recognize. Saving the document containing the text is one such example. In these cases, the component has to explicitly call the input context's endComposition method.

2. Enhancing an Active Client Component

Handling Additional Text Attributes

In addition to the input method highlight information, input methods may also attach other attributes to the text they send to a text component. These attributes may be useful information for the component. They may also improve the input method's performance if returned by the InputMethodRequest methods. For the latter reason, it is recommended that text components keep this attribute information around while the text is being edited, and return it with any text requested.

The AttributedCharacterIterator.Attribute class defines the following common attributes:

  • LANGUAGE - the language of the text, specified as a Locale object.
  • READING - a phonetic representation (yomi in Japanese), specified as a String object.
  • INPUT_METHOD_SEGMENT - segmentation information used by input methods.

Input methods written in the Java programming language may define additional attributes.

Creating Private Input Contexts

By default, one InputContext instance is created per Window instance, and this input context is shared by all components within the window's containment hierarchy. This reduces the number of instances created overall, and lets input methods combine information about all the text entered in this window (input methods often use information about previously entered text to improve their conversion accuracy). It means, however, that only one input operation is possible at any one time within a window, and that the text needs to be committed when moving the focus from one text component to another. If this is not desired, text components can create their own input context instances and override getInputContext to return them. A component that doesn't have its own input context uses the one used by its parent.

Selecting Input Methods

Text components can use the input context's selectInputMethod operation to select an input method for a given language or locale. This may be helpful, for example, if the user clicks in text that is written in that language, since it's likely that she wants to continue in the same language. Or, the text component may know that the application only allows text in a certain language to be entered.

Setting an Expected Character Subset

Text components can use the input context's setCharacterSubsets operation to tell input methods which characters can be meaningfully entered. For example, a database application may know that certain fields should only receive input in hiragana (one of the syllabic subscripts used in Japanese), another one only Latin characters, a third one any kind of characters. Passing on this information to input methods may allow the input methods to limit the range of characters that can be entered, or to switch to a different input mode that particularly supports the specified character subsets.

Using Engine-Specific Functionality

Some input methods may provide functionality to client components that can not be made available through the input method framework API. This is possible through input method control objects. The input method developer must publish an interface for these objects. Client components that want to take advantage of the additional functionality can then call InputContext.getInputMethodControlObject, check whether the returned object is an instance of a known control object class, and if it is, call its methods.

3. Implementing a Non-Client

By default, all components that process key events are clients of the input method framework, that is, input method support is enabled for them. In some cases, components may not want to have their input processed by input methods. For example, games may want to interpret keyboard events directly. These components should call enableInputMethods(false), so that events do not get forwarded to input methods.

4. Sample Code

This sample code shows how to implement the different kinds of input method clients that are possible with the input method framework: an active client, a passive client, a non-client, and a peered text component.

  • Applet - run this applet in a Java 2 enabled browser, and you can experiment with the different client components.
  • Javadoc
    • LWTextComponent - explains the structure of a lightweight text editing component that can be extended to an active client.
    • ActiveClient - explains the structure of an active client component.
  • Source Code
    • IMFDemo.java - the applet/application that contains the different client components.
    • LWTextComponent.java - a lightweight text editing component that doesn't know about input methods, but can be extended to an active client.
    • ActiveClient.java - extends LWTextComponent to become an active client component.
    • PeeredTextArea.java - a peered text component.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Contact us

Sun
Java Software


Input Method Engine SPI Reference

The following classes are part of the input method engine SPI:

  • java.awt.im.spi
    • Package Specification
    • java.awt.im.spi.InputMethod
    • java.awt.im.spi.InputMethodDescriptor
    • java.awt.im.spi.InputMethodContext
  • java.awt.im
    • java.awt.im.InputMethodHighlight
    • java.awt.im.InputMethodRequests
    • java.awt.im.InputSubset
  • java.awt.event
    • java.awt.event.InputMethodEvent

    In addition, the following classes and members in other frameworks support the input method engine SPI:

  • java.awt.font
    • java.awt.font.TextAttribute
      • INPUT_METHOD_UNDERLINE
      • UNDERLINE_LOW_ONE_PIXEL
      • UNDERLINE_LOW_TWO_PIXEL
      • UNDERLINE_LOW_DOTTED
      • UNDERLINE_LOW_GRAY
      • UNDERLINE_LOW_DASHED
  • java.lang
    • java.lang.Character.Subset
  • java.text
    • java.text.Annotation
    • java.text.AttributedCharacterIterator
    • java.text.AttributedCharacterIterator.Attribute
    • java.text.AttributedString

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Contact us

Sun
Java Software


Input Method Engine SPI Tutorial

Contents

  1. Introduction
  2. Describing the Input Method
  3. Communicating with the Client Component
  4. Using Input Method Windows
  5. Implementing Composition
  6. Providing Engine-Specific Functionality
  7. Packaging the Input Method
  8. Sample Code

1. Introduction

The input method engine SPI enables the development of input methods in the Java programming language that can be used with any Java 2 runtime environment. As far as the input method framework is concerned, an input method consists of two classes implementing the InputMethodDescriptor and InputMethod interfaces, packaged with some additional information as an extension and installed into a Java runtime. The specifications for the java.awt.im.spi package, and the InputMethodDescriptor and InputMethod interfaces provide the core information that's needed to implement an input method. This tutorial provides additional information that makes this task a little easier and helps avoid compatibility problems between different implementations of the Java 2 platform.

2. Describing the Input Method

Before the input method framework can start using an input method, it needs to know about its capabilities. The necessary information is provided by the input method's implementation of the InputMethodDescriptor class. This information is used in selecting input methods.

The list of available locales returned by getAvailableLocales should only return languages that the input method is really designed for. For example, a Chinese Pinyin input method that produces simplified Chinese characters should only return SIMPLIFIED_CHINESE, even if it has a mode that simply lets key events pass through and thus also makes it possible to write English or Malay. The InputMethod.setLocale method on the other hand may return true for a larger set of languages. The reason is that getAvailableLocales is used to decide whether to load and switch to an input method, which is only worthwhile if the input method handles the language well, while setLocale is used to decide whether to switch away from an input method, which is only worthwhile if the input method doesn't handle the language at all.

3. Communicating with the Client Component

When an input method instance is created, it receives an InputMethodContext instance through setInputMethodContext. This instance provides it with all the functionality that it needs to communicate with the input method framework, the client component, or the composition window. It lets the input method send information about composed and committed text using the dispatchInputMethodEvent method. And it lets the input method request information from the client component using the methods it inherits from the InputMethodRequests interface.

The input method framework provides the input method with an environment that makes it seem like it is always communicating with an active client component using the on-the-spot input style. If the actual client component is not an active client, or if a different input style is used, then the framework redirects events and requests as needed.

The input method should never try to access the client component directly, as doing so would conflict with the framework's switching and redirection functionality. Instead, the input method should always use the methods provided by its input method context.

4. Using Input Method Windows

Input methods may use a number of different windows to communicate with the user. Windows commonly used by input methods include:

  • a look-up window, which shows several possible interpretations of the user's input and lets the user choose the correct one.
  • a status window, which provides the user with information about the current state of the input method, such as the selected language or target character set.
  • a control panel (often combined with the status window), which lets the user change the input method's state, such as selecting a different language or target character set.
  • a preferences window, which lets the user tailor the input method to his or her needs.
  • a dictionary editor window, which lets the user add or correct conversions.

Note: On some other platforms, input methods may also provide a composition window, which shows the composed text. In the Java input method framework, composed text is always displayed by the client component or the input method framework, never by the input method.

It is useful to consider three groups of windows:

  • transient windows: these windows pop up for short times during a composition operation. Their functionality is tied to a specific composition. Opening, closing, positioning, and sizing are usually automatic since any user interaction with the windows themselves would distract from the composition. In particular, transient windows are always closed when the composition operation ends or is interrupted. Examples: look-up window.
  • persistent windows: these windows tend to stay around for extended periods of time, possibly for as long as the user is using the input method. Their functionality may be tied to the currently active instance of the input method, or to the input method class. Usually the user can actively open, close, position, and possibly resize these windows, although they are always automatically closed when switching to a different input method, and in some cases they're automatically positioned relative to the window containing the current client component. Examples: status window, control panel.
  • document windows: these are just regular windows. Their functionality is not tied to composition. The user fully controls opening, closing, positioning, and possibly sizing of these windows. Examples: dictionary editor window.

Here's how these window groups can be handled by input methods written for the Java 2 platform:

  • transient windows are created using InputMethodContext.createInputMethodWindow, typically with attachToInputContext set to true. They are opened either in the input method's implementation of activate, or later when needed to respond to user input. They are closed in the input method's implementations of deactivate or hideWindows, or earlier if they are no longer needed.
  • persistent windows are created using InputMethodContext.createInputMethodWindow, with attachToInputContext set to false. They are typically opened in the input method's implementation of activate and closed in the input method's implementation of hideWindows.
  • document windows are created as regular AWT windows, and opening and closing them is usually under user control.

Note that the focus behavior of a window created by createInputMethodWindow is implementation dependent. It may never get the focus, it may get the focus when initially made visible, or it may get the focus when the user clicks into it. An input method must be able to handle either case.

To position windows (such as the look-up window) automatically relative to the composed text, the input method can use the input method context's getTextLocation method. To position windows (such as a status window) automatically relative to the window containing the current client component, the input method can register for notifications about that window's location and state using the input method context's enableClientWindowNotification method; it then has to implement the notifyClientWindowChange method to receive notifications.

Input methods must call Window.dispose for all windows they create when they are no longer needed. This ensures that the JVM exits when the application terminates all non-daemon threads it started. Please refer to AWT Threading Issues for more information.

5. Implementing Composition

The main task of an input method is interpreting user actions in composing text input. The user actions may be typing on the keyboard, using the mouse, handwriting, or speaking.

The activate and deactivate methods indicate to the input method whether a client component has the focus and therefore is the target of text input. Typically input methods only process events to compose text while they're active.

When an input method is active, certain types of events are dispatched to the input method using the dispatchEvent method before they are processed by the client component. The input method decides for each event whether it wants to handle it. If it does, it marks the event as consumed so that it is not processed by the client component.

Note: For key events, input methods should use only KEY_TYPED events to obtain information about characters being entered, and use KEY_PRESSED or KEY_RELEASED events only to obtain information about function keys that don't result in KEY_TYPED events. The mapping from key-presses to characters depends on platforms, hardware, locales, and possibly other factors, and is best left to the underlying operating system.

As text is being composed and committed, the input method needs to inform the client component about all changes so that the client component can redraw the text. The input method does this by using InputMethodContext.dispatchInputMethodEvent to construct and dispatch input method events to the client component. Depending on the current event flow model, the input method framework may redirect the events to its composition window. Dispatching input method events is the only way for Java input methods to have composed text displayed.

Composed text is usually marked up with highlight styles that indicate the current state of the conversion. This is accomplished by adding attributes to the text using the TextAttribute.INPUT_METHOD_HIGHLIGHT key and instances of InputMethodHighlight as values. Normally input methods only define abstract highlights (using the state and selected properties of the input method highlight) and leave the mapping to concrete styles to the rendering system. However, if desired, input methods can add concrete style information to the highlight using the style property. It is a good idea to design the concrete styles as variations of the styles provided returned by Toolkit.mapInputMethodHighlight.

Both the client component and the input method framework may recognize situations where the current composition needs to be ended and all composed text either committed or cancelled. They inform the input method about this need using the endComposition method. Note that endComposition may be called while the input method is not active.

Client components can influence composition using several methods. The InputContext.setCharacterSubsets method lets them restrict the subset of the Unicode character set that the input method is allowed to input. Input methods should generally not create characters outside of the specified subsets, and may switch to a different input mode that particularly supports the specified character subsets. The InputContext.setCompositionEnabled and isCompositionEnabled methods let them control and examine whether the current input method is enabled for composition. The InputContext.reconvert method lets them initiate reconversion.

6. Providing Engine-Specific Functionality

Some input methods may want to provide functionality to client components that can not be made available through the input method framework API. This is possible through input method control objects. The input method developer must publish an interface for these objects, and return instances through InputMethod.getControlObject. Client components that want to take advantage of the additional functionality can then call InputContext.getInputMethodControlObject, check whether the returned object is an instance of a known control object class, and if it is, call its methods.

7. Packaging the Input Method

Input methods are packaged as installed extensions with specific content as described in the "Packaging Input Methods" section of the SPI specification. One important aspect to consider is that all extensions installed in a Java application environment share the same name space. To avoid name collisions, input methods should follow the package naming conventions as described in the Java Language Specification. Similar conventions should be applied to naming non-class files that are packaged in the input method JAR file, such as dictionaries.

8. Sample Code

City Input Method is a simple input method that shows how to use the interfaces provided by the input method engine SPI.

  • City Input Method documentation - tells you how to install and use this input method.
  • City Input Method - a jar file containing the input method. Some browsers will automatically offer to download this file; others will show its contents in a window (not a pretty sight), and you then have to use the Save command to write it into a file. See the documentation for installation instructions.
  • CityInputMethodDescriptor.java - the InputMethodDescriptor implementation for this input method.
  • CityInputMethod.java - the InputMethod implementation for this input method.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Contact us

Sun
Java Software


Input Method Framework Overview

Contents

  1. Introduction
  2. Goals
  3. Input Method Support in Other Frameworks
  4. References

1. Introduction

Input methods are software components that interpret user operations such as typing keys, speaking, or writing using a pen device to generate text input for applications. The most common input methods are the ones that let users type text in Chinese, Japanese, or Korean, languages that use thousands of different characters, on a regular-sized keyboard. The text is typed in a form that can be handled by regular-sized keyboards, for example, in a romanized form, and then converted into the form that's really intended. Typically a sequence of several characters needs to be typed and then converted in one chunk, and conversion may have to be retried because there may be several possible translations. Similarly, for hand-writing recognition, the user may write a series of characters, convert them, and select the correct text from several possible conversion results. This process is called composition, and the text that the input method is working on is called composed text. It ends when the user confirms the final conversion result and the text is committed.

During composition, the composed text logically belongs to the input method, but still needs to be displayed to the user. Input method frameworks cooperate with input methods to provide at least two ways to do this: They enable modern text editing components to display the text in the context of the document that it will eventually belong to, albeit in a style that indicates that the text still needs to be converted or confirmed by the input method. This is called on-the-spot style input. And they provide a separate window to display the text as a fall-back if a not-so-modern text editing component can't deal with the text until it's confirmed. We call this root-window style input.

The input method framework in the Java 2 platform enables the collaboration between text editing components and input methods in entering text. Its input method client API provides interfaces and classes that enable text editing components to communicate with input methods and implement a well-integrated text input user interface in the on-the-spot and below-the-spot styles; it also provides root-window style input as a fallback. Its service provider interface (SPI) for input method engines provides interfaces that enable the development of input methods in the Java programming language that can be used with any Java runtime environment; it also supports native input methods of the host platform.

2. Goals

"Write Once, Run Anywhere in the World" for Text Components

Text editing components that use the input method framework run on any Java application environment and support any text input methods available on that Java application environment without modifying or recompiling the text editing component. The framework isolates text editing components from differences in platforms and input method engines. It provides only one programming model for interacting with input methods. This lets developers write to a single API, and lets users choose whatever input method they prefer. When using native input methods, the framework maps to the platform input method APIs.

Although engine independence will be important to most developers, some high-end developers may want access to engine specific features. The framework allows this access.

"Write Once, Run Anywhere in the World" for Input Methods

Input methods written in the Java programming language and using the input method engine SPI can be installed into any Java application environment and support any text component running in that Java application environment. The framework isolates input methods from differences in platforms and text editing components. It provides only one programming model for interacting with text components. This lets developers write to a single SPI, and lets users choose whatever text editing component they prefer.

Language Independence

The input method framework is language independent in order to satisfy the needs of fully international applications. Although input methods are generally used for entering East Asian text, they may be useful for other languages as well. For example, a transliteration input method might be developed to allow Greek to be entered using Latin characters.

The framework handles input methods for different languages at the same time for truly multilingual text editing. While the choice of native input methods may be limited by the host operating system, any input method written in the Java programming language and using the input method engine SPI can be used at any time. Text created by an input method can have language attributes so that applications can perform language sensitive operations on the text.

Input Device Independence

The input method framework is designed to accommodate many possible input devices. Although keyboards are the predominant way of entering text today, other devices are gaining importance. For some platforms, pen-based input is the only way to enter text. Also, voice input is becoming more and more popular. The input method engine SPI opens the way to support these alternate devices.

Multiple Service Levels

Different programs have different needs for input method support. Tight integration with input methods provides the best user interface, but requires some additional programming. Some developers may not find that additional work worthwhile, but their applications still need to be able to receive East Asian text input. A few programs, such as games, want direct low-level keyboard input without interference from an input method. The framework lets programs choose one of the following levels of text input support.

Integrated Text Input User Interface

Modern programs intended to be used with East Asian languages usually provide a fully integrated user interface for text input operations and show the text being composed embedded in the document text. While converting text, the current candidate is highlighted, and when the user chooses a different candidate, the previous candidate text is replaced with the new one. This user interface support for input methods is known as on-the-spot style (or inline style). An alternative that Chinese-speaking users often prefer is the below-the-spot style, where composed text is shown in a separate composition window that is automatically positioned close to the insertion point where text will be inserted after being committed. The input method client API lets text editing components implement these integrated text input user interfaces.

Integration does not only mean displaying the composed text in the context of the target document. It also means that the text editing component understands "input method events", which let the input method communicate more information about the text than simple key events (for example, grammatical information), and that it can responds to requests for information from the input method that let the input method improve its functionality (for example, its accuracy).

Non-Integrated Text Input User Interface

For programs that do not want to deal with the user interface for text input operations, only final input text is sent to the application. In this case, the framework provides a user interface for input operations in a separate composition window outside the application. This is known as root-window style. It is less convenient because the user either has to manually position the window near the insertion point or to move his/her eyes between the composition window and the application window.

In this case, the application receives the input text as a sequence of key events. Therefore, there is no way to receive any information associated with the input text, such as grammatical information. Also, surrogate pairs (as defined in the Unicode Standard, version 2.0) are received as two separate key events.

No Input Method Support

Some applications, such as game software, may need only raw key input and no input method support. The framework provides a way to explicitly disable input method support.

Building Block Reuse

An important theme of object-oriented programming is reuse of program building blocks. The same building block may be used in many different applications, and several times within the same application. To make it easy to combine different text editing building blocks of possibly different capabilities, the input method framework interacts with each text editing component directly and individually.

As a consequence, many applications will not interact with the input method framework directly at all. Instead, they will use ready-made text editing components, such as the Swing text components, which will handle the interaction for them.

Close Integration with Other Frameworks

The input method framework is designed as an integral part of the Java platform. Interfaces that are necessary to exchange text between input methods and text components are designed to also support communication between other text-related frameworks, such as Java 2D and the Swing text components. Support for input method highlight drawing is integrated into Java 2D, so that text components can treat composed text just like any other text and the highlights just like any other style. Java 2D interacts with the input method framework to determine appropriate visual styles for input method highlights depending on the platform. The Swing text components use the input method framework to implement the best possible user interface with minimal additional programming.

3. Input Method Support in Other Frameworks

This chapter summarizes functionality in other Java platform frameworks that support input methods.

Text

The AttributedCharacterIterator interface provides a standard way of communicating text information with attributes between frameworks. It lets text readers access text without having to know how the text is stored in the information provider. Attribute information may include font and style attributes as well as language tags and grammatical annotations.

Abstract Window Toolkit

The Window class creates an initial input context for the window, and disposes this input context for the window when the window is disposed. Explicitly disposing input contexts allows to free up the (often substantial) resources allocated by native input methods.

The Component class has methods to handle input contexts and input method request handlers. Newly created Component instances other than windows initially share the input context of their containing window. The event handling in the Component class redirects incoming events to the input context associated with the component, and only passes them on to the component's listeners if they have not been consumed by an input method. Focus changes are communicated to the input context so it can activate or deactivate input methods.

The AWT classes that have knowledge of event or listener classes handle the InputMethodEvent and InputMethodListener classes.

The Graphics class defines a drawString method that accepts AttributedCharacterIterator instances as input. Instances of the TextLayout class can be constructed from AttributedCharacterIterator instances and used to draw text with input method highlights. Both ways of drawing text recognize input method highlights as attributes of the text and render them.

Swing

The Swing text components in the Java 2 platform are by default active clients of the input method framework. That means, applications using these text components will use on-the-spot or below-the-spot style input by default. Application developers are still responsible for ending input operations when some other operation is started that requires the text to be committed. They may also use the input method framework's methods to create a private input context, to select an input method, or to set an expected character subset.

4. References

Information about the implementation of input methods on different platforms can be found in the following literature:

  • "Programmer's Supplement for Release 6," O'Reilly & Associates, Inc. (ISBN 1-56592-089-9).
  • "Inside Macintosh: Text," Addison-Wesley (ISBN 0-201-63298-5).
  • "Developing International Software for Windows 95 and Windows NT," Microsoft Press (ISBN 1-55615-840-8).
  • "IIIMP - Platform Independent Input Method for Internet and Java," Proc. Twelfth International Unicode/ISO 10646 Conference, Unicode Consortium.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Contact us

Sun
Java Software


Input Method Framework Specification

Contents

  1. Framework Architecture
  2. Client Components
  3. Input Styles
  4. Input Method Engines and Adapters
  5. Context Management
  6. Information Flow Through the Framework

1. Framework Architecture

The following picture shows the overall structure of the framework and its clients. Parts outlined in bold are integrated with the input method framework as part of the Java 2 platform; others can be developed and distributed separately by independent software vendors.

The following context describes this graphic

The input method client API defines the classes and interfaces that text editing components can use to implement an integrated text input user interface. The AWT text components TextArea and TextField provide on-the-spot or over-the-spot composition, depending on implementation. The text components of the Swing user interface toolkit provide an integrated text input user interface. The context management manages communication paths between the text editing components and input methods. The input method engine SPI defines the interfaces that allow input method engines and adapters to be plugged into the framework. Input method engines can be implemented directly in the Java programming language using these interfaces. To use native input methods integrated with the host input method manager, an adapter translates information between the data models used by native input methods and the input method framework and provides the composition window. Adapters for other input systems, such as Java Speech or the Internet-Intranet Input Method Protocol (IIIMP), can also be implemented using this interface.

2. Client Components

Every instance of the Component class is potentially a client of the input method framework. The framework distinguishes between four kinds of components:

  • Active clients are components whose getInputMethodRequests implementations return a non-null value. The framework assumes that these components actively use the input method client API and, in particular, provide an implementation of the InputMethodListener interface. These components are expected to handle events and requests for information coming from the input method and draw composed text that is sent to them.
  • Non-clients are components that have turned off input method support using the enableInputMethods method.
  • Peered clients are peered text components (instances of the TextComponent class). Their behavior is implementation dependent, and their input method support may be limited. In Sun's Java 2 runtime environment for Windows, peered text components behave mostly like active clients. In Sun's Java 2 runtime environment for Solaris, peered text components can receive input only from host input methods, and they do not support the below-the-spot input style (see below).
  • Passive clients are all remaining components. The framework assumes that passive clients don't use the input method client API, but still need to receive text input from input methods.

All four kinds of components may coexist in the same window. The input method framework, therefore, needs to determine the capabilities of components and adjust its behavior as the focus moves from one component to another.

Client components are not responsible for drawing candidate lists or for user interface elements that control the input method's behavior. Depending on the platform, this responsibility rests with input methods, the host input method manager, or the input method framework.

Input methods are not concerned with the differences between client components. They interact with them indirectly through the input method framework, which presents an interface similar to an active client and handles the differences internally.

3. Input Styles

The input method framework supports three input styles:

  • On-the-spot input, where the client component draws the composed text in the context of the document that it will eventually belong to, but in a style that indicates that the text still needs to be converted or confirmed by the input method. This is the default input style for active clients.
  • Below-the-spot input, where the composed text is shown in a separate composition window that is automatically positioned just below the insertion point where text will be inserted after being committed. The window's location is calculated first when the window is opened, then updated whenever committed text has been dispatched to the client component. If positioning the window below the insertion point would move it partially or entirely off-screen, it is moved above the insertion point. This input style may be selected for active clients as described below.
  • Root-window input, where the composed text is shown in a separate composition window that is not automatically positioned. This input style is used for passive clients.

The framework chooses between on-the-spot and below-the-spot input for active clients based on a system property or an AWT property "java.awt.im.style". The system property can be defined from the command line (by the end user), the AWT property in a localized awt.properties file (by the localizer or a system administrator). If both are defined, the system property takes precedence. If the property's value is "below-the-spot", below-the-spot input is used, otherwise on-the-spot input.

Support for below-the-spot input with native input methods is platform dependent. In Sun's Java 2 runtime environments, it is supported on Windows, but not on Solaris. Where it is not supported, on-the-spot input is used instead.

The input style used for peered text components (instances of the TextComponent class) is implementation dependent and may not be any of the styles described above. In Sun's Java 2 runtime environment for Windows, below-the-spot input may be selected as described above, otherwise over-the-spot input is used, where composed text is drawn in a separate window covering the insertion point. In Sun's Java 2 runtime environment for Solaris, the input style depends on the input method.

No input style is associated with non-clients.

Input methods are not concerned with the differences between input styles. They interact with client components indirectly through the input method framework, which presents an interface assuming on-the-spot input and handles the differences internally.

4. Input Method Engines and Adapters

The input method engine SPI enables the development of input methods in the Java programming language. Adapters for other input systems, such as Java Speech or the Internet-Intranet Input Method Protocol, can also be implemented using this interface. For information specific to the SPI, see the SPI package specification.

The SPI is also used for host input method adapters, which connect to native input methods integrated with the host input method managers, such as the Input Method Manager on Microsoft Windows, the Text Services Manager on MacOS, and XIM on Solaris. The host input method adapter plays the role of an input method within the input method framework, and translates events and requests between the data models used by AWT and the input method framework on one side and the host's input method manager on the other side. It also cooperates with the input context in managing the composition window - for passive clients interacting host input methods, typically the root window provided by the host input method manager is used. The adapter passes on requests for particular input methods to the host, but users can also use the host's selection mechanism to select input methods.

5. Context Management

InputContext instances manage communication contexts between client components and input methods. The main task of an input context is to maintain the connection from the current client component to its current input method. It dispatches input events such as key and mouse events from the component to the current input method, and input method events from the input method to the client component. It also dispatches requests for information from the input method to the client component.

Each InputContext instance provides its own text input environment, separate from all other input contexts. This allows applications to support multiple concurrent input operations. For example, in the middle of entering text into a document, a user can open a file dialog and enter a file name, without affecting the composition state of the text being entered into the document.

By default, one InputContext instance is created per Window instance, and this input context is shared by all components within the window's containment hierarchy. If necessary, components can create private input contexts. A component that doesn't have its own input context uses the one used by its parent. An input context has at most one current client component, the component that currently has the focus. When switching to a new client component, the input context calls its endComposition method to commit or cancel composed text for the previous client component.

The input context creates an input method instance for each input method engine that its client components need to use. Separate input method instances are created for each input context instance. The instances are kept until the input context is disposed, so that the instances can keep information about the text that was entered in the window.

The input context also handles input method selection and the composition window.

Selecting Input Methods

An input context has a current input method and a current locale.

The input method framework provides two separate ways of selecting input methods and input locales:

  • The method InputContext.selectInputMethod lets applications request an input method supporting a specified locale.
  • A user interface lets the user request an input method by name, and specify the input locale. A selection made from the user interface affects the currently active input context only.

The framework does not give preference to selections made either way, so the last successful selection made either way for an input context determines the current input method for an input context (note that selectInputMethod may fail if no available input method supports the requested locale).

Before switching to a new input method, the input context calls the old input method's endComposition method. The input context retains the old input method instance and reuses it when the same input method is selected again for this input context at a later point.

InputContext.selectInputMethod looks for an input method supporting the specified locale using the results of the InputMethodDescriptor.getAvailableLocales methods of all installed input methods. If the user has previously selected an input method with the specified locale from the user interface, this input method is chosen. Otherwise it is implementation dependent which input method is chosen if multiple input methods support the specified locale.

The user interface for selecting input methods is implementation dependent. It must provide the user with a list of all available input methods and let him/her select one of them. Where an input method supports multiple locales, the user interface also lets the user select the input locale (this facility may be omitted for host adapters if the host provides an alternative facility to select the input locale). Licensees developing Java runtime environments for their own platforms are encouraged to integrate the user interface with existing user interfaces for selecting keyboards or input methods.

In Sun's Java 2 runtime environments for Windows and Solaris (with Motif-based AWT), the user interface consists of three parts: a "Select Input Method" menu item added to the Window menu in Motif or the System menu in Windows, a user-defined input method selection key, and a pop-up menu brought up by either the "Select Input Method" menu item or the input method selection key. The "Select Input Method" item is only shown if the Java runtime environment has more than one input method available or the input method supports multiple locales (the host input method adapter is treated as a single input method). The popup menu lists the available input methods, with supported locales of multi-locale input methods as submenus, and lets the user select from this list. Sun's Java 2 runtime environments for Solaris (with X-based AWT) and Linux do not provide the "Select Input Method" menu item, i.e., the pop up menu is only brought up by pressing the input method selection key. The input method selection key definition is stored persistently using two preferences, one defining the base key code value and the other defining the modifiers. The "modifiers" preference is optional. If a modifiers entry is defined without matching keyCode entry, that modifiers entry is ignored. The following table shows the contents.

key name (String) | value (int)
"keyCode" | any java.awt.event.KeyEvent.VK_* value except VK_UNDEFINED
"modifiers" | any combination of java.awt.event.InputEvent.*_MASK

The Java 2 runtime looks for these preferences first in the user's preference tree node /java/awt/im/selectionKey, then, if no definition could be found, in the system preference node with the same path.

Composition Window

For passive clients and for active clients using below-the-spot input, the input method framework provides a composition window. The window is opened when the input method starts sending composed text; it is closed when all text is committed. At most one composition window is open at any time even if multiple compositions (using separate input contexts) are currently in progress.

For below-the-spot input, the window is automatically positioned just below the insertion point where text will be inserted after being committed. The window's location is calculated first when the window is opened, then updated whenever committed text has been dispatched to the client component. If positioning the window below the insertion point would move it partially or entirely off-screen, it is moved above the insertion point.

6. Information Flow Through the Framework

The framework provides two mechanisms to communicate information between the current client component and the current input method:

  • AWT events are used to pass information about user actions to the input method, and to notify the component of changes in the input text. This provides a programming interface that's consistent with other input operations. However, InputMethodEvents are typically dispatched synchronously to the component's methods, while other AWT events are dispatched asynchronously through the event queue.
  • The InputMethodRequests interface defines methods that an input method can call to request information from the client component. This invocation is synchronous.

Both event dispatching and calling InputMethodRequests methods are done indirectly through the input context. This lets the input context redirect information to a composition window if necessary. The composition window provides a full implementation of an active client, and so the input method can always assume it is interacting with an active client.

The following sections show the flow of events through the input method framework and explain the associated handling of input method requests. Four alternatives are described, depending on the kind of client component and the selected input style. All diagrams assume an input method implemented in the Java programming language using the input method engine SPI. Event flows for peered text components or native input methods are implementation dependent, may vary substantially, and are not shown.

Active Clients With On-the-Spot Input

The following context describes this graphic

Input events such as KeyEvent and MouseEvent are sent to the current input method through the InputContext object. If the input method uses the event for text composition, it marks the event consumed and generates an input method event to the component. The client component must have registered an InputMethodListener so it can handle InputMethodEvents coming from the input method and receive composed and committed text.

InputMethodRequests calls from the input method are forwarded to the object returned by the client component's getInputMethodRequests method.

Active Clients With Below-the-Spot Input

The following context describes this graphic

Input events such as KeyEvent and MouseEvent are sent to the current input method through the InputContext object. If the input method uses the event for text composition, it marks the event consumed and generates an input method event. Since below-the-spot input is selected, the event is redirected to the composition window, which handles it. When text is committed (partially or entirely), the composition window generates a new input method event holding the committed text for the client component. The client component must have registered an InputMethodListener so it can handle InputMethodEvents, which in this case come from the composition window and only contain committed text.

InputMethodRequests calls from the input method that relate to the display of composed text (getTextLocation, getLocationOffset) are handled by the composition window; all others are forwarded to the object returned by the client component's getInputMethodRequests method. The composition window uses the client component's getTextLocation implementation to position itself.

Passive Clients

The following context describes this graphic

Input events such as KeyEvent and MouseEvent are sent to the current input method through the InputContext object. If the input method uses the event for text composition, it marks the event consumed and generates an input method event. The event is redirected to the composition window, which handles it. When text is committed, the composition window translates it into key events for the actual client's key event listener. Only KEY_TYPED events are sent.

InputMethodRequests calls from the input method are handled by the composition window. Calls hat relate to the display of composed text (getTextLocation, getLocationOffset) are handled based on information about the composed text being displayed. All other calls are handled at all times based on the assumption that composition has just started and there's no committed text, because the composition window does not have access to text in the client component.

Non-Clients

The following context describes this graphic

Events for non-clients do not go to the input context. All events go straight to the component's listeners (here, the key listener).

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Contact us

Sun
Java Software


Java Input Method Framework Technology

Java

JavaTM Input Method Framework Technology

Documentation Contents

The input method framework enables the collaboration between text editing components and input methods for entering text. 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.

The input method framework provides two layers of public interfaces:

  • The input method client API provides interfaces and classes that enable text editing components to communicate with input methods and implement a well-integrated text input user interface.
  • The input method engine SPI provides interfaces that enable the development of input methods in the JavaTM programming language that can be used with any Java runtime environment.

Overview

  • Overview - An overview of the Input Method framework.

API Specification

  • Specification
  • Input method client API reference
  • Input method engine SPI reference

Tutorials and Programmer's Guides

  • Input method client API tutorial
  • Input method engine SPI tutorial

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun
Java Software


Generated Documentation

Frame Alert

This document is designed to be viewed using the frames feature. If you see this message, you are using a non-frame-capable web client.
Link to Non-frame version.


Hierarchy

Class Tree Index
PREV NEXT FRAMES NO FRAMES

Hierarchy For All Packages

Class Hierarchy

  • class java.lang.Object
    • class java.awt.Component (implements java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable)
      • class LWTextComponent (implements java.awt.event.FocusListener, java.awt.event.KeyListener)
        • class ActiveClient (implements java.awt.event.InputMethodListener, java.awt.im.InputMethodRequests)
Class Tree Index
PREV NEXT FRAMES NO FRAMES
Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1999 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.


Index

Class Tree Index
PREV NEXT FRAMES NO FRAMES
A C F G I K L P S

A

ActiveClient - class ActiveClient.
Implements an integrated text input user interface.
ActiveClient(String) - Constructor for class ActiveClient
Constructs an ActiveClient.

C

cancelLatestCommittedText(AttributedCharacterIterator.Attribute[]) - Method in class ActiveClient
Returns null to indicate that the "Undo Commit" feature is not supported by this simple text component.
caretPositionChanged(InputMethodEvent) - Method in class ActiveClient
Handles changes to the caret within composed text.

F

focusGained(FocusEvent) - Method in class LWTextComponent
Turns on drawing of the component's thicker frame and the caret.
focusLost(FocusEvent) - Method in class LWTextComponent
Turns off drawing of the component's thicker frame and the caret.

G

getCaret() - Method in class ActiveClient
Returns a text hit info indicating the current caret (insertion point).
getCaret() - Method in class LWTextComponent
Returns a text hit info indicating the current caret (insertion point).
getCaretRectangle() - Method in class LWTextComponent
Returns a 0-width caret rectangle.
getCaretRectangle(TextHitInfo) - Method in class LWTextComponent
Returns a 0-width caret rectangle for the given text index.
getCommittedText() - Method in class LWTextComponent
Returns the text that the user has entered and committed.
getCommittedText(int, int) - Method in class LWTextComponent
Returns a subrange of the text that the user has entered and committed.
getCommittedText(int, int, AttributedCharacterIterator.Attribute[]) - Method in class ActiveClient
Gets an iterator providing access to the entire text and attributes contained in the text editing component except for uncommitted text.
getCommittedTextLength() - Method in class LWTextComponent
Returns the length of the text that the user has entered and committed.
getDisplayText() - Method in class ActiveClient
Returns the text that the user has entered.
getDisplayText() - Method in class LWTextComponent
Returns the text that the user has entered.
getInputMethodRequests() - Method in class ActiveClient
Implements getInputMethodRequests for ActiveClient by returning "this".
getInsertPositionOffset() - Method in class ActiveClient
Gets the offset of the insert position in the committed text contained in the text editing component.
getLocationOffset(int, int) - Method in class ActiveClient
Gets the offset within the composed text for the specified absolute x and y coordinates on the screen.
getSelectedText(AttributedCharacterIterator.Attribute[]) - Method in class ActiveClient
Gets the currently selected text from the text editing component.
getTextLayout() - Method in class LWTextComponent
Returns a text layout for the text that the user has entered.
getTextLocation(TextHitInfo) - Method in class ActiveClient
Gets the location of a specified offset in the current composed text, or of the selection in committed text.
getTextOrigin() - Method in class LWTextComponent
Returns the origin of the text.

I

inputMethodTextChanged(InputMethodEvent) - Method in class ActiveClient
Handles changes to the text entered through an input method.
insertCharacter(char) - Method in class LWTextComponent
Inserts the given character at the end of the text.
invalidateTextLayout() - Method in class LWTextComponent
Invalidates the cached text layout.

K

keyPressed(KeyEvent) - Method in class LWTextComponent
Ignores key pressed events.
keyReleased(KeyEvent) - Method in class LWTextComponent
Ignores key released events.
keyTyped(KeyEvent) - Method in class LWTextComponent
Handles the key typed event.

L

LWTextComponent - class LWTextComponent.
Implements a very simple lightweight text editing component.
LWTextComponent(String, boolean) - Constructor for class LWTextComponent
Constructs a LWTextComponent.

P

paint(Graphics) - Method in class LWTextComponent
Draws the component.

S

setFontSize(int) - Method in class ActiveClient
Adjusts composed text for new font size.
setFontSize(int) - Method in class LWTextComponent
A C F G I K L P S
Class Tree Index
PREV NEXT FRAMES NO FRAMES
Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1999 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.


Input Method Framework Demo

alt="Applet that shows different ways of interacting with input methods"
This applet contains four text components that show the different ways of interacting with input methods in the Java 2 platform. This applet can be run in two ways:
  • with an implementation of the Java 2 Platform Standard Edition v1.2 or higher, running on a platform/locale that uses native input methods. Examples: Japanese Windows NT, Macintosh with Chinese Language Kit, Solaris with Korean locale.
  • with an implementation of the Java 2 Platform Standard Edition v1.3 or higher, with an input method installed that's implemented in the Java programming language. The Java runtime environment may be running on a platform/locale that does not support native input methods.

The first three components are lightweight components, i.e., they handle events and render text using Java APIs. The last one is a peered component, that is, event handling and text rendering are handled by a text editing engine provided by the underlying platform. Peered components were used widely in JDK 1.0 AWT, while lightweight components were introduced in JDK 1.1 and are the basis of the Swing class library.

The lightweight components have different capabilities:

  • The active client uses the input method framework API to implement on-the-spot (also called "inline") text composition.
  • The passive client works with input methods in the simplest way - it relies on the input method framework to handle all composition and only accepts committed text.
  • The non-client refuses to work with input methods.

To test with the different components with native Japanese input methods, click into the components to focus on them, turn on an input method (Alt-` on Windows, choosing from the keyboard menu on Macintosh, Control-Space on Solaris), then type "nihongo". The behavior you should see is:

  • Active client: The word is entered in in the component directly and gets converted to four hiragana characters as you type.
  • Passive client: A separate window shows up, the word is entered in that window and gets converted to four hiragana characters as you type.
  • Non-client: The text "nihongo" is entered into the component.
  • Peered component: The behavior depends on the platform, but most likely it's similar to the active client (the text may be drawn over the pre-existing text or push it to the right).

For all components except the non-client, you can now convert the text (Space on Windows and Macintosh, Control-N or Space on Solaris) and then commit it (Enter on all three platforms - how could that happen?). Conversion should result in three kanji characters, which after committing are shown in the component without highlight.

To test with the different components with the sample input method implemented in the Java programming language, "City Input Method", install the input method's JAR file into the extensions directory of the Java runtime environment before running the applet. Then click into the components to focus on them, and select the input method. The selection mechanism is implementation dependent; on Sun's Java runtime environments choose the "Select Input Method" menu item from the system menu in the top left corner of the window, then choose the input method from the pop-up menu that comes up. Then type "TYO". The behavior you should see:

  • Active client: The text is entered in the component directly and is highlighted.
  • Passive client: A separate window shows up, the text is entered in that window and is highlighted.
  • Non-client: The text is entered into the component, but not highlighted.
  • Peered component: The behavior depends on the platform.

For all components except the non-client and, on some platforms, the peered component, you can now convert the text using the Space key. The conversion result depends on your default language - it's the name "Tokyo" in Japanese, Japanese yomi, English, German, simplified or traditional Chinese. To see all options, press Space again - this time, you'll get a look-up window showing all the possibilities. You can use Space to go through all possible selections, or type the number of the conversion you like. Pressing the Enter key will commit the selected conversion and remove the highlight.


Serialized Form

Class ActiveClient implements Serializable

Serialized Fields

caret

TextHitInfo caret

composedText

AttributedCharacterIterator composedText

composedTextString

AttributedString composedTextString

Class LWTextComponent implements Serializable

Serialized Fields

committedText

StringBuffer committedText

name

String name

nameOriginY

int nameOriginY

textOriginX

int textOriginX

textOriginY

int textOriginY

Class Tree Index
PREV NEXT FRAMES NO FRAMES
Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1999 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.


ActiveClient

Class Tree Index
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Class ActiveClient

java.lang.Object
  |
  +--java.awt.Component
        |
        +--LWTextComponent
              |
              +--ActiveClient
public class ActiveClient
extends LWTextComponent
implements InputMethodListener, InputMethodRequests

Implements an integrated text input user interface. This class is an active client of the input method framework, that is, actively uses its APIs to accomplish integration.

This class directly implements the two client interfaces of the input method framework, InputMethodListener and InputMethodRequests. This is not required. Especially in cases where the public interface matters (such as in a class library), it may be more appropriate to hide the implementations of these two interfaces in separate classes.

See Also:
Serialized Form

Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Constructor Summary
ActiveClient(String name)
Constructs an ActiveClient.
Method Summary
AttributedCharacterIterator | cancelLatestCommittedText(AttributedCharacterIterator.Attribute[] attributes) Returns null to indicate that the "Undo Commit" feature is not supported by this simple text component.
void | caretPositionChanged(InputMethodEvent event) Handles changes to the caret within composed text.
TextHitInfo | getCaret() Returns a text hit info indicating the current caret (insertion point).
AttributedCharacterIterator | getCommittedText(int beginIndex, int endIndex, AttributedCharacterIterator.Attribute[] attributes) Gets an iterator providing access to the entire text and attributes contained in the text editing component except for uncommitted text.
AttributedCharacterIterator | getDisplayText() Returns the text that the user has entered.
InputMethodRequests | getInputMethodRequests() Implements getInputMethodRequests for ActiveClient by returning "this".
int | getInsertPositionOffset() Gets the offset of the insert position in the committed text contained in the text editing component.
TextHitInfo | getLocationOffset(int x, int y) Gets the offset within the composed text for the specified absolute x and y coordinates on the screen.
AttributedCharacterIterator | getSelectedText(AttributedCharacterIterator.Attribute[] attributes) Gets the currently selected text from the text editing component.
Rectangle | getTextLocation(TextHitInfo offset) Gets the location of a specified offset in the current composed text, or of the selection in committed text.
void | inputMethodTextChanged(InputMethodEvent event) Handles changes to the text entered through an input method.
void | setFontSize(int size) Adjusts composed text for new font size.
Methods inherited from class LWTextComponent
focusGained, focusLost, getCaretRectangle, getCaretRectangle, getCommittedText, getCommittedText, getCommittedTextLength, getTextLayout, getTextOrigin, insertCharacter, invalidateTextLayout, keyPressed, keyReleased, keyTyped, paint
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, enableInputMethods, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getGraphics, getHeight, getInputContext, getLocale, getLocation, getLocation, getLocationOnScreen, getMaximumSize, getMinimumSize, getName, getParent, getPeer, getPreferredSize, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isDisplayable, isDoubleBuffered, isEnabled, isFocusTraversable, isLightweight, isOpaque, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, paramString, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, processComponentEvent, processEvent, processFocusEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, remove, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFont, setForeground, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, show, show, size, toString, transferFocus, update, validate
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ActiveClient

public ActiveClient(String name)
Constructs an ActiveClient. Input methods are always enabled for ActiveClient instances.
Parameters:
name - the component name to be displayed above the text
Method Detail

getInputMethodRequests

public InputMethodRequests getInputMethodRequests()
Implements getInputMethodRequests for ActiveClient by returning "this".
Returns:
"this"
Overrides:
getInputMethodRequests in class Component

setFontSize

public void setFontSize(int size)
Adjusts composed text for new font size.
Overrides:
setFontSize in class LWTextComponent

getDisplayText

public AttributedCharacterIterator getDisplayText()
Returns the text that the user has entered. This override returns the concatenation of committed text and composed text.
Overrides:
getDisplayText in class LWTextComponent

getCaret

public TextHitInfo getCaret()
Returns a text hit info indicating the current caret (insertion point). This override returns the caret provided by the input method while there is composed text; otherwise it returns a caret at the end of the committed text. The caret provided by the input method may be null.
Overrides:
getCaret in class LWTextComponent

inputMethodTextChanged

public void inputMethodTextChanged(InputMethodEvent event)
Handles changes to the text entered through an input method. Committed text contained in the event is appended to the committed text of the text component. Composed text contained in the event replaces any existing composed text in the text component. The caret defined in the event is saved and will be returned by getCaret if there is composed text. The component is redrawn.

In this simple component, we only keep input method highlight attributes. Smarter components may want to keep language, reading, input method segment, and other attributes as well.

Specified by:
inputMethodTextChanged in interface InputMethodListener

caretPositionChanged

public void caretPositionChanged(InputMethodEvent event)
Handles changes to the caret within composed text. The caret defined in the event is saved and will be returned by getCaret if there is composed text. The component is redrawn.
Specified by:
caretPositionChanged in interface InputMethodListener

getTextLocation

public Rectangle getTextLocation(TextHitInfo offset)
Gets the location of a specified offset in the current composed text, or of the selection in committed text.
Specified by:
getTextLocation in interface InputMethodRequests

getLocationOffset

public TextHitInfo getLocationOffset(int x,
                                     int y)
Gets the offset within the composed text for the specified absolute x and y coordinates on the screen.
Specified by:
getLocationOffset in interface InputMethodRequests

getInsertPositionOffset

public int getInsertPositionOffset()
Gets the offset of the insert position in the committed text contained in the text editing component. In this simple component, that's always at the end of the committed text.
Specified by:
getInsertPositionOffset in interface InputMethodRequests

getCommittedText

public AttributedCharacterIterator getCommittedText(int beginIndex,
                                                    int endIndex,
                                                    AttributedCharacterIterator.Attribute[] attributes)
Gets an iterator providing access to the entire text and attributes contained in the text editing component except for uncommitted text.
Specified by:
getCommittedText in interface InputMethodRequests

cancelLatestCommittedText

public AttributedCharacterIterator cancelLatestCommittedText(AttributedCharacterIterator.Attribute[] attributes)
Returns null to indicate that the "Undo Commit" feature is not supported by this simple text component.
Specified by:
cancelLatestCommittedText in interface InputMethodRequests

getSelectedText

public AttributedCharacterIterator getSelectedText(AttributedCharacterIterator.Attribute[] attributes)
Gets the currently selected text from the text editing component. Since this simple text component doesn't support selections, this is always an iterator over empty text.
Specified by:
getSelectedText in interface InputMethodRequests
Class Tree Index
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD
Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1999 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.


LWTextComponent

Class Tree Index
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Class LWTextComponent

java.lang.Object
  |
  +--java.awt.Component
        |
        +--LWTextComponent
Direct Known Subclasses:
ActiveClient
public class LWTextComponent
extends Component
implements KeyListener, FocusListener

Implements a very simple lightweight text editing component. It lets the user edit a single line of text using the keyboard. The only special character that it knows about is backspace; all other characters are added to the text. Selections are not supported, so there's only a simple caret indicating the insertion point. The component also displays a component name above the editable text line, and draws a black frame whose thickness indicates whether the component has the focus.

The component can be initialized to enable or disable input through input methods. Other than that, it doesn't do anything to support input methods, so input method interaction (if any) will occur in a separate composition window. However, the component is designed to be easily extended with full input method support. It distinguishes between "displayed text" and "committed text" - here, they're the same, but in a subclass that supports on-the-spot input, the displayed text would be the combination of committed text and composed text. The component also uses TextLayout to draw the text, so it can be easily extended to handle input method highlights.

See Also:
Serialized Form

Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
Constructor Summary
LWTextComponent(String name, boolean enableInputMethods)
Constructs a LWTextComponent.
Method Summary
void | focusGained(FocusEvent event) Turns on drawing of the component's thicker frame and the caret.
void | focusLost(FocusEvent event) Turns off drawing of the component's thicker frame and the caret.
TextHitInfo | getCaret() Returns a text hit info indicating the current caret (insertion point).
Rectangle | getCaretRectangle() Returns a 0-width caret rectangle.
Rectangle | getCaretRectangle(TextHitInfo caret) Returns a 0-width caret rectangle for the given text index.
AttributedCharacterIterator | getCommittedText() Returns the text that the user has entered and committed.
AttributedCharacterIterator | getCommittedText(int beginIndex, int endIndex) Returns a subrange of the text that the user has entered and committed.
int | getCommittedTextLength() Returns the length of the text that the user has entered and committed.
AttributedCharacterIterator | getDisplayText() Returns the text that the user has entered.
TextLayout | getTextLayout() Returns a text layout for the text that the user has entered.
Point | getTextOrigin() Returns the origin of the text.
void | insertCharacter(char c) Inserts the given character at the end of the text.
void | invalidateTextLayout() Invalidates the cached text layout.
void | keyPressed(KeyEvent event) Ignores key pressed events.
void | keyReleased(KeyEvent event) Ignores key released events.
void | keyTyped(KeyEvent event) Handles the key typed event.
void | paint(Graphics g) Draws the component.
void | setFontSize(int size)
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, enableInputMethods, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getGraphics, getHeight, getInputContext, getInputMethodRequests, getLocale, getLocation, getLocation, getLocationOnScreen, getMaximumSize, getMinimumSize, getName, getParent, getPeer, getPreferredSize, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isDisplayable, isDoubleBuffered, isEnabled, isFocusTraversable, isLightweight, isOpaque, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, paramString, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, processComponentEvent, processEvent, processFocusEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, remove, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFont, setForeground, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, show, show, size, toString, transferFocus, update, validate
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

LWTextComponent

public LWTextComponent(String name,
                       boolean enableInputMethods)
Constructs a LWTextComponent.
Parameters:
name - the component name to be displayed above the text
enableInputMethods - whether to enable input methods for this component
Method Detail

setFontSize

public void setFontSize(int size)

paint

public void paint(Graphics g)
Draws the component. The following items are drawn:
  • the component's background
  • a frame, thicker if the component has the focus
  • the component name
  • the text that the user has entered
  • the caret, if the component has the focus
Overrides:
paint in class Component

getCommittedText

public AttributedCharacterIterator getCommittedText()
Returns the text that the user has entered and committed. Since this component does not support on-the-spot input, there's no composed text, so all text that has been entered is committed.
Returns:
an AttributedCharacterIterator for the text that the user has entered and committed

getCommittedText

public AttributedCharacterIterator getCommittedText(int beginIndex,
                                                    int endIndex)
Returns a subrange of the text that the user has entered and committed. Since this component does not support on-the-spot input, there's no composed text, so all text that has been entered is committed.
Parameters:
beginIndex - the index of the first character of the subrange
endIndex - the index of the character following the subrange
Returns:
an AttributedCharacterIterator for a subrange of the text that the user has entered and committed

getCommittedTextLength

public int getCommittedTextLength()
Returns the length of the text that the user has entered and committed. Since this component does not support on-the-spot input, there's no composed text, so all text that has been entered is committed.
Returns:
the length of the text that the user has entered and committed

getDisplayText

public AttributedCharacterIterator getDisplayText()
Returns the text that the user has entered. As TextLayout requires a font to be defined for each character, the default font is applied to the entire text. A subclass that supports on-the-spot input must override this method to include composed text.
Returns:
the text that the user has entered

getTextLayout

public TextLayout getTextLayout()
Returns a text layout for the text that the user has entered. This text layout is created from the text returned by getDisplayText. The text layout is cached until invalidateTextLayout is called.
Returns:
a text layout for the text that the user has entered, or null
See Also:
invalidateTextLayout(), getDisplayText()

invalidateTextLayout

public void invalidateTextLayout()
Invalidates the cached text layout. This must be called whenever the component's text is modified.
See Also:
getTextLayout()

getTextOrigin

public Point getTextOrigin()
Returns the origin of the text. This is the leftmost point on the baseline of the text.
Returns:
the origin of the text

getCaretRectangle

public Rectangle getCaretRectangle()
Returns a 0-width caret rectangle. This rectangle is derived from the caret returned by getCaret. getCaretRectangle returns null iff getCaret does.
Returns:
the caret rectangle, or null
See Also:
getCaret()

getCaretRectangle

public Rectangle getCaretRectangle(TextHitInfo caret)
Returns a 0-width caret rectangle for the given text index. It is calculated based on the text layout returned by getTextLayout, so this method can be used for the entire displayed text.
Parameters:
caret - the text index for which to calculate a caret rectangle
Returns:
the caret rectangle

getCaret

public TextHitInfo getCaret()
Returns a text hit info indicating the current caret (insertion point). This class always returns a caret at the end of the text that the user has entered. Subclasses may return a different caret or null.
Returns:
the caret, or null

insertCharacter

public void insertCharacter(char c)
Inserts the given character at the end of the text.
Parameters:
c - the character to be inserted

keyTyped

public void keyTyped(KeyEvent event)
Handles the key typed event. If the character is backspace, the last character is removed from the text that the user has entered. Otherwise, the character is appended to the text. Then, the text is redrawn.
Specified by:
keyTyped in interface KeyListener

keyPressed

public void keyPressed(KeyEvent event)
Ignores key pressed events.
Specified by:
keyPressed in interface KeyListener

keyReleased

public void keyReleased(KeyEvent event)
Ignores key released events.
Specified by:
keyReleased in interface KeyListener

focusGained

public void focusGained(FocusEvent event)
Turns on drawing of the component's thicker frame and the caret.
Specified by:
focusGained in interface FocusListener

focusLost

public void focusLost(FocusEvent event)
Turns off drawing of the component's thicker frame and the caret.
Specified by:
focusLost in interface FocusListener
Class Tree Index
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD
Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1999 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.


City Input Method

Contents

  1. About City Input Method
  2. Installing and Selecting the Input Method
  3. Using the Input Method for the First Time
  4. Using the Input Method
  5. Controlling the Status Window
  6. Supported Cities and Locales

1. About City Input Method

City Input Method is a simple input method that lets users enter city names by just typing a three-character airport code and converting it to a corresponding city name. If the user enters more than one airport code (up to three at a time are possible), the input method creates a short phrase such as "From San Francisco to Beijing via Tokyo". For each city, the input method knows the city names and phrases in a number of different languages (or, more precisely, locales). City names and phrases in all supported languages can be freely mixed in any input operation. The input method can be used to enter text into any text component that supports input methods, such as a Swing text component.

2. Installing and Selecting the Input Method

To make the input method available to applications, its jar file must be installed into the extensions directory of a Java 2 runtime environment. After launching a Java application with a text component that supports input methods, the input method can be selected using the input method selection user interface provided by the runtime environment. First, make sure that a text component has the focus - typically, the text component indicates this by showing an insertion point. Then, for Sun's Java 2 Runtime Environment, choose the "Select Input Method" menu from the menu that can be pulled down from the top left corner of the window (the System menu on Windows, Window menu on Solaris), then choose "City Input Method" and the desired locale from the popup menu. Note that correct text display in some languages depends on the font configuration, so you may want to pick the locale of the host operating system or a language that is supported by most fonts, such as English or German.

3. Using the Input Method for the First Time

After selecting the input method, type "SFO", the code for San Francisco International Airport. You will see that the text is input into the text component, but highlighted to indicate that it is still being composed (for Sun's Java 2 Runtime Environment, the text is inverted on Solaris, underlined on Windows). Then type a Space character to start conversion. You will see that the airport code is replaced with the name of San Francisco in the language that you selected. The text is still highlighted, although the highlight may now look somewhat different. Type Space again. A lookup window opens, which shows the city name in all available languages, with the originally displayed name selected. Continue typing Space. You will see that the selection cycles through all the names, and that the selected name is also shown in the text component. Type Return. The lookup window disappears, and the most recently selected name is now shown in the text component without any highlight - it is committed.

4. Using the Input Method

Entering Raw Text

Raw text is any text that is entered through the input method, but hasn't been converted yet. From the moment you type the first character of an airport until you start conversion the input method is in raw text mode. In this mode, letters from "a" to "z" or their uppercase variants (the input method is case insensitive) are added to the raw text input. You can use backspace to delete a character, and you can click into the text using the mouse to move the insertion point.

Converting to City Names

You can start the conversion process from airport codes to city names when the raw text includes one, two, or three airport codes - that is, three, six, or nine characters. To start conversion, type Space. A single airport code is converted to just a city name. Two or three airport codes are converted to phrases such as "From San Francisco to Frankfurt" for two codes or "From San Francisco to Frankfurt via Chicago" for three codes. Each city name is considered a separate segment. One of the segments is selected, that is, it can be further converted using the lookup window. If there are multiple segments, the segment selection can be changed by clicking into a segment or by using the Arrow Right and Arrow Left keys.

Continuing Conversion Using the Lookup Window

The lookup window is a temporary window that shows the city names in all available languages for the airport code of the selected segment, and lets the user choose a different name. To show the window, select a segment, then type Space. The window opens just below or, if there's not enough space, in another location near the segment's text. The currently selected city name is outlined. To change the name selection, type Space, Arrow Down, or Arrow Up to cycle through all available names. To confirm a selected name, you usually commit as described in the next section. To select a name and close the lookup window without committing, type the number in front of the desired name.

Committing the Input

Committing the input text means to end input method processing of it, and make it a normal part of the text component's text body. All input method highlighting is removed from committed text. You can commit the entire input text at any time by typing Return. If you entered more than one airport code and have started conversion, you can also perform a partial commit: typing Control-Arrow Down commits the text up to the currently selected segment, but leaves following segments available for further conversion.

Conversion is requested using the Space character. During conversion, the input method first offers the city name in the selected language (if that name is available). If the user does not accept this selection, a second step brings up a choice window that offers all available names for the city, with the corresponding locale name.

5. Controlling the Status Window

The input method provides a little status window that shows the currently selected locale. Initially this window is positioned near the lower right corner of the screen, but it can be moved to a different location. To request that the status window automatically positions itself below the window containing the currently focussed text component, double-click into the status window's content area.

6. Supported Cities and Locales

The input method's knowledge of the world is limited - airport codes it knows include: SFO, NYC, JFK, LGA, ORD, FRA, MUC, TYO, NRT, HND, KIX, ITM, PEK, BJS, SHA, HKG, TPE. It currently supports the following languages: English, German, Japanese (normal and yomi), Simplified Chinese, Traditional Chinese.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Contact us

Sun
Java Software


Enhancements in java.lang.instrument

Java

Enhancements in JDK 6
java.lang.instrument

 Contents
The following functionality has been added to the java.lang.instrument package between its initial release in JDK 5.0 and JDK 6.
  • Support for retransformation of class files - To facilitate dynamic transformation of classes that have already been loaded, the following methods have been added.
    • Instrumentation.retransformClasses(Class...)
    • Instrumentation.addTransformer(ClassFileTransformer, boolean)
    • Instrumentation.isModifiableClass(Class)
    • Instrumentation.isRetransformClassesSupported()
    They are suited to operations such as adding instrumentation to methods whose classes have already been loaded. Support for retransformation means that access to the original class file is no longer required in order to instrument loaded classes. They enable the easy removal of applied transformations and are designed to work in multi-agent environments.

  • Support for instrumenting native methods - The following methods allow native methods to be instrumented by providing a JVM-aware mechanism for wrapping the native method.
    • Instrumentation.setNativeMethodPrefix(ClassFileTransformer, String)
    • Instrumentation.isNativeMethodPrefixSupported()

  • Support for appending to class loader search - The following methods allow instrumentation support classes to be defined in the appropriate class loader.
    • Instrumentation.appendToBootstrapClassLoaderSearch(JarFile)
    • Instrumentation.appendToSystemClassLoaderSearch(JarFile)
Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

 Sun


java.lang.instrument

Documentation Contents

The java.lang.instrument package provides a JavaTM programming language API for tools to instrument Java programming language applications -- for example, to monitor them or collect performance information. Tools use java.lang.instrument to modify the class file that defines a class -- generally, by inserting into the byte-code of methods additional byte-code which will perform the instrumentation.

java.lang.instrument was introduced at JDKTM 5.0.

API Specification

  • java.lang.instrument Package (package description)

API Enhancements

  • See the API Enhancements in JDK 6 - An annotated list of API changes between the 5.0 and 6 releases.

More Information

  • Java Virtual Machines Tool Interface - a native interface which can also perform instrumentation.
  • java.lang.management package - the monitoring and management package, often useful with instrumentation.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

 Feedback 		Sun
Java Software


Font Configuration Files

The Java Platform defines five logical font names that every implementation must support: Serif, SansSerif, Monospaced, Dialog, and DialogInput. These logical font names are mapped to physical fonts in implementation dependent ways.

Sun's Java SE Runtime Environments use font configuration files to map logical font names to physical fonts. There are several files to support different mappings depending on the host operating system version. The files are located in the lib directory within the JRE installation. Users can edit or create their own font configuration files to adjust the mappings to their particular system setup. Note however that this is a modification of the JRE, and Sun does not support modified JREs.

Font configuration files come in two formats: A properties format and a binary format. The properties format is described in detail in this document and can be used for user-defined configurations. The binary format is undocumented and used only for the JRE's predefined configurations; the corresponding files in properties format are available for reference as files with the ".properties.src" extension.

Note that font configuration files are implementation dependent. Not all implementations of the Java Platform use them, and the format and content vary between different runtime environments as well as between releases. This document describes the format used by version 6 of Sun's Java SE Runtime Environments.

  1. Loading Font Configuration Files
  2. Names Used in Font Configuration Files
  3. Properties for All Platforms
  4. Properties for Windows
  5. Properties for Solaris and Linux

Loading Font Configuration Files

To find the appropriate font configuration file for a host operating system, the following information is used:

  • JavaHome - the JRE's directory, as given by the "java.home" system property.
  • OS - a string identifying an operating system variant:
    • For Windows, "98", "2000", "Me", "XP", "2003".
    • For Solaris, empty.
    • For Linux, "Sun", "RedHat", "Turbo", "SuSE".
  • Version - a string identifying the operating system version.

The runtime uses the first of the following files it finds:

    JavaHome/lib/fontconfig.OS.Version.properties
    JavaHome/lib/fontconfig.OS.Version.bfc
    JavaHome/lib/fontconfig.OS.properties
    JavaHome/lib/fontconfig.OS.bfc
    JavaHome/lib/fontconfig.Version.properties
    JavaHome/lib/fontconfig.Version.bfc
    JavaHome/lib/fontconfig.properties
    JavaHome/lib/fontconfig.bfc

Files with a ".properties" suffix are assumed to be properties files as specified by the Properties class and are loaded through that class. Files without this suffix are assumed to be in binary format.

Names Used in Font Configuration Files

Throughout the font configuration files, a number of different names are used:

  • LogicalFontName - one of the five logical font names: serif, sansserif, monospaced, dialog, and dialoginput. In font configuration files, these names are always in lowercase.
  • StyleName - one of the four standard font styles: plain, bold, italic, and bolditalic. Again, these names are always in lowercase.
  • PlatformFontName - the name of a physical font, in a format typically used on the platform:
    • On Windows, a font face name, such as "Courier New" or "\uad74\ub9bc".
    • On Solaris and Linux, an xlfd name, such as "-monotype-times new roman-regular-r---*-%d-*-*-p-*-iso8859-1". Note that "%d" is used for the font size - the actual font size is filled in at runtime.
  • CharacterSubsetName - a name for a subset of the Unicode character set which certain component fonts can render. For Windows, the following names are predefined: alphabetic, arabic, chinese-ms936, chinese-gb18030, chinese-ms950, chinese-hkscs, cyrillic-iso8859-5, cyrillic-cp1251, cyrillic-koi8-r, devanagari, dingbats, greek, hebrew, japanese, korean, latin, symbol, thai. For Solaris and Linux, the following names are predefined: arabic, chinese-gb2312, chinese-gbk, chinese-gb18030-0, chinese-gb18030-1, chinese-cns11643-1, chinese-cns11643-2, chinese-cns11643-3, chinese-big5, chinese-hkscs, cyrillic, devanagari, dingbats, greek, hebrew, japanese-x0201, japanese-x0208, japanese-x0212, korean, korean-johab, latin-1, latin-2, latin-4, latin-5, latin-7, latin-9, symbol,thai. A font configuration file may define additional names to identify additional character subsets.
  • Encoding - the canonical name of the default encoding, as provided by java.nio.charset.Charset.defaultCharset().name().
  • Language - the language of the initial default locale.
  • Country - the country of the initial default locale.

Properties for All Platforms

Version Property

The version property identifies the font configuration format version. This document specifies version 1.

The complete property has the form:

version=1

Component Font Mappings

Component font mapping properties describe which physical font to use to render characters from a given character subset with a given logical font in a given style.

The keys have the forms:

    allfonts.CharacterSubsetName
    LogicalFontName.StyleName.CharacterSubsetName

The first form is used if the same font is used for a character subset independent of logical font and style (in this case, the font rendering engines apply algorithmic styles to the font). The second form is used if different physical fonts are used for a character subset for different logical fonts and styles. In this case, properties must be specified for each combination of logical font and style, so 20 properties for one character subset. If a property of the first form is present for a character subset, then properties of the second form for the same character subset are ignored.

The values are platform font names, as described above.

Since the character subsets supported by given fonts often overlap, separate search sequence properties are used to define in which order to try the fonts when rendering a character.

Search Sequences

The Java runtime uses sequence properties to determine search sequences for the five logical fonts. However, a font configuration file may specify properties that are specific to a combination of encoding, language, and country, and the runtime will then use a lookup to determine the search sequence property for each logical font.

The keys have the form:

    sequence.allfonts.Encoding.Language.Country
    sequence.LogicalFontName.Encoding.Language.Country
    sequence.allfonts.Encoding.Language
    sequence.LogicalFontName.Encoding.Language
    sequence.allfonts.Encoding
    sequence.LogicalFontName.Encoding
    sequence.allfonts
    sequence.LogicalFontName

The allfonts forms are used if the sequence is used for all five logical fonts. The forms specifying logical font names are used if different sequences are used for different logical fonts.

For each logical font, the Java runtime uses the property value with the first of the above keys. This property determines the primary search sequence for the logical font.

The file may also define a single fallback search sequence. The key for the fallback search sequence property is:

    sequence.fallback

The values of all search sequence properties have the form:

SearchSequenceValue:
    CharacterSubsetName
    CharacterSubsetName , SearchSequenceValue

The primary search sequence properties specify character subset names for required fonts, which are used for both AWT and 2D font rendering. The fallback search sequence property gives character subset names for optional fonts, which are used as fallbacks for all logical fonts, but only for 2D font rendering. The runtime automatically adds the Lucida Sans Regular font as a fallback font for 2D rendering if it's not already specified. If the runtime environment has a directory lib/fonts/fallback and this directory contains valid TrueType or Type 1 fonts, the runtime automatically adds these fonts as fallback fonts for 2D rendering. On Windows, if there is a system EUDC (End User Defined Characters) font registered with Windows, the runtime automatically adds this font as well as a fallback font for 2D rendering.

The sequence properties determine in which sequence component fonts are tried to render a given character. For example, given the following properties:

sequence.monospaced=japanese,alphabetic
sequence.fallback=korean
monospaced.plain.alphabetic=Arial
monospaced.plain.japanese=MSGothic
monospaced.plain.korean=Gulim

the runtime will first attempt to render a character with the MSGothic font. If that font doesn't provide a glyph for the character, it will attempt the Arial font. For 2D rendering, it will also try the Gulim and the Lucida Sans Regular font as well as any TrueType or Type 1 fonts in the runtime's lib/fonts/fallback directory. For 2D rendering on Windows, if there is a system EUDC font registered with Windows, the runtime will finally try this EUDC font.

When calculating font metrics for a logical font without reference to a string, only the required fonts are taken into consideration. For the example above, the FontMetrics.getMaxDescent method would return results based on the MSGothic and Arial fonts, but not the Gulim and Lucida Sans fonts. In this way, simple user interface elements such as buttons, which sometimes calculate their size based on font metrics, are not affected by an extended list of component fonts which their labels usually don't use. On the other hand, text components typically calculate metrics based on the text they contain and thus will obtain correct results.

The sequence properties that the runtime obtains for the five logical fonts should list the same character subsets, but may list them in different order.

Exclusion Ranges

The exclusion range properties specify Unicode character ranges which should be excluded from being rendered with the fonts corresponding to a given character subset. This is used if a font with a large character repertoire needs to be placed early in the search sequence (for example, for performance reasons), but some characters that it supports should be drawn with a different font instead. These properties are optional, so there's at most one per character subset.

The keys have the form:

    exclusion.CharacterSubsetName

The values have the form:

ExclusionRangeValue:
    Range
    Range , ExclusionRangeValue

Range:
    Char - Char

Char:
    HexDigit HexDigit HexDigit HexDigit
    HexDigit HexDigit HexDigit HexDigit HexDigit HexDigit

A Char is a Unicode character represented as a hexadecimal value.

Proportional Fonts

The proportional font properties describe the relationship between proportional and non-proportional variants of otherwise equivalent fonts. These properties are used to implement preferences specified by the GraphicsEnvironment.preferProportionalFonts method.

The keys have the form:

    proportional.PlatformFontName

Space characters in the platform font name must be replaced with underscore characters ("_").

The values have the form:

    PlatformFontName

In values, space characters are left unmodified.

Each property indicates that the font named in the value is the proportional equivalent of the font named in the key, and also that the font named in the key is the non-proportional equivalent of the font named in the value.

Font File Names

Font file name properties provide the names of the files containing the physical fonts used in the font configuration file. File names are required for all physical fonts on Windows and recommended for all physical fonts on Solaris and Linux.

The keys have the form:

    filename.PlatformFontName

Space characters in the platform font name must be replaced with underscore characters ("_").

The values are the file names of the files containing the fonts. On Windows, simple file names are used; and the runtime environment looks for each file first in its own lib/fonts directory, then in the Windows fonts directory. On Solaris and Linux, absolute path names, path names starting with "$JRE_LIB_FONTS" for the runtime environment's own lib/fonts directory, or xlfd names are used.

Appended Font Path

The Java runtime can automatically determine a number of directories that contain font files, such as its own lib/fonts directory or the Windows fonts folder. Additional directories can be specified to be appended to the font path.

The key has the form:

    appendedfontpath

The value has the form:

AppendedFontPathValue:
    Directory
    Directory PathSeparator AppendedFontPathValue

The path separator is the platform dependent value of java.io.File.pathSeparator.

Properties for Windows

There are no platform-specific properties for Windows. However, there is a special form of the character subset name used in search sequences. The name "alphabetic" can take a suffix indicating the character encoding associated with the subset:

    alphabetic
    alphabetic/default
    alphabetic/1252

This information is only used for AWT, not for 2D. The "/default" suffix restricts use of the component fonts for this character subset to the character set of the default encoding; the "/1252" suffix to the Windows-1252 character set. For accessing component font mappings and exclusion ranges, the character encoding suffix is omitted. For all other character subsets, the AWT character encoding is determined internally by the Java runtime.

Properties for Solaris and Linux

Motif Component Font Mappings

The AWT text components, which rely on Motif-based peers for text rendering, cannot always use the same platform fonts as other AWT components and 2D. When looking up component fonts for these components, additional keys are recognized. The complete set of keys looked up in this case is:

    allfonts.CharacterSubsetName.motif
    LogicalFontName.StyleName.CharacterSubsetName.motif
    allfonts.CharacterSubsetName
    LogicalFontName.StyleName.CharacterSubsetName

AWT X11 Font Path

The AWT font path properties specify platform directories which should be added to the X11 server font path. The keys have the form:

    awtfontpath.CharacterSubsetName

The values have the form:

AWTFontPathValue:
    Directory
    Directory : AWTFontPathValue

The directories must be valid X11 font directories. The Java runtime ensures that the directories for all character subsets of a primary search sequence found by the search sequence lookup are part of the X11 font path. The implementation assumes that all logical fonts use the same set of character subsets for a given environment of encoding, language, and country.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Feedback

Sun
Java Software


Internationalization Enhancements in Java SE 6

Java

Internationalization Enhancements

This page provides an overview of internationalization enhancements in Java SE Development Kit 6 (JDK):

  • Core Java Internationalization
  • Desktop Java Internationalization

Core Java Internationalization

Locale Sensitive Services SPIs

To enable plug-in of locale sensitive data (e.g., date format strings) and services (e.g., date formatters), some Service Provider Interfaces (SPIs) for locale-sensitive classes in the java.text and java.util packages have been added. These SPIs make it much easier for developers to provide support of more locales in addition to the currently available locales in Java SE. For example, your own implementation of BreakIterator for Chinese could become available through the BreakIterator.getSentenceInstance factory in the Java runtime.

Unicode Normalizer API

The new java.text.Normalizer class supports the Unicode text normalization defined in Unicode Standard Annex #15.

Internationalized Domain Names Support

The new java.net.IDN class provides Internationalized Domain Names (IDNs) support based on RFC 3490, 3491, 3454, and 3492.

Japanese Imperial Calendar Support

A new Calendar implementation has been added to support the Japanese imperial era-based year numbering, such as Heisei 17 for 2005 (Gregorian). An instance of this Japanese imperial calendar can be created through the Calendar.getInstance factory by specifying a Locale("ja", "JP", "JP"). The java.text.SimpleDateFormat class now supports calendar specific eras and date formats for non-Gregorian calendar systems. Refer to the Supported Calendars documentation for details.

ResourceBundle Enhancements

The new nested java.util.ResourceBundle.Control class has been added to give applications more control over the resource bundle loading process. The class defines a set of callback methods that are invoked by the ResourceBundle.getBundle factory during the resource bundle loading. Applications can override those callback methods to change the factory method behavior.

Additional Locales Support

The following locales are now available.

  • zh_SG - Chinese (Simplified), Singapore
  • en_MT - English, Malta
  • en_PH - English, Philippines
  • en_SG - English, Singapore
  • el_CY - Greek, Cyprus
  • id_ID - Indonesian, Indonesia
  • ga_IE - Irish, Ireland
  • ms_MY - Malay, Malaysia
  • mt_MT - Maltese, Malta
  • pt_BR - Portuguese, Brazil
  • pt_PT - Portuguese, Portugal
  • es_US - Spanish, United States

Refer to the Supported Locales documentation for details.

Desktop Java Internationalization

Key Input in non-English Locales

The keyboard related AWT code has been re-architected to fix various problems on key input in non-English locales for Solaris and Linux operating systems.

Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved.

Feedback

Sun
Java Software


Internationalization Frequently Asked Questions

The content of this page has moved to a new location.


Internationalization Overview

Contents

  • Introduction
  • Core Java Internationalization
    • Text Representation
    • Locale Identification and Localization
    • Date and Time Handling
    • Text Processing
    • Locale Sensitive Services SPIs
    • Character Encoding Conversion
  • Desktop Java Internationalization
    • Text Input

Introduction

The global Internet demands global software - that is, software that can be developed independently of the countries or languages of its users, and then localized for multiple countries or regions. The Java Platform provides a rich set of APIs for developing global applications. These internationalization APIs are based on the Unicode standard and include the ability to adapt text, numbers, dates, currency, and user-defined objects to any country's conventions.

This document summarizes the internationalization APIs and features of the Java Platform, Standard Edition. For coding examples and step-by-step instructions, see the Java Tutorial. The detailed APIs are found in the Java Platform, Standard Edition, API Specification.

For additional information, see the Java Internationalization home page.

Text Representation

The Java programming language is based on the Unicode character set, and several libraries implement the Unicode standard. Unicode is an international character set standard which supports all of the major scripts of the world, as well as common technical symbols. The original Unicode specification defined characters as fixed-width 16-bit entities, but the Unicode standard has since been changed to allow for characters whose representation requires more than 16 bits. The range of legal code points is now U+0000 to U+10FFFF. An encoding defined by the standard, UTF-16, allows to represent all Unicode code points using one or two 16-bit units.

The primitive data type char in the Java programming language is an unsigned 16-bit integer that can represent a Unicode code point in the range U+0000 to U+FFFF, or the code units of UTF-16. The various types and classes in the Java platform that represent character sequences - char[], implementations of java.lang.CharSequence (such as the String class), and implementations of java.text.CharacterIterator - are UTF-16 sequences. Most Java source code is written in ASCII, a 7-bit character encoding, or ISO-8859-1, an 8-bit character encoding, but is translated into UTF-16 before processing.

The Character class as an object wrapper for the char primitive type. The Character class also contains static methods such as isLowerCase() and isDigit() for determining the properties of a character. Since J2SE 5, these methods have overloads that accept either a char (which allows representation of Unicode code points in the range U+0000 to U+FFFF) or an int (which allows representation of all Unicode code points).

Locale Identification and Localization

Locales

On the Java platform, a locale is simply an identifier for a particular combination of language and region. It is not a collection of locale-specific attributes. Instead, each locale-sensitive class maintains its own locale-specific information. With this design, there is no difference in how user and system objects maintain their locale-specific resources. Both use the standard localization mechanism.

Java programs are not assigned a single global locale. All locale-sensitive operations may be explicitly given a locale as an argument. This greatly simplifies multilingual programs. While a global locale is not enforced, a default locale is available for programs that do not wish to manage locales explicitly. A default locale also makes it possible to affect the behavior of the entire presentation with a single choice.

Java locales act as requests for certain behavior from another object. For example, a French Canadian locale passed to a Calendar object asks that the Calendar behave correctly for the customs of Quebec. It is up to the object accepting the locale to do the right thing. If the object has not been localized for a particular locale, it will try to find a "close" match with a locale for which it has been localized. Thus if a Calendar object was not localized for French Canada, but was localized for the French language in general, it would use the French localization instead.

Locale Class

A Locale object represents a specific geographical, political, or cultural region. An operation that requires a locale to perform its task is called locale-sensitive and uses the Locale object to tailor information for the user. For example, displaying a number is a locale-sensitive operation - the number should be formatted according to the customs and conventions of the user's native country, region, or culture.

Supported Locales

On the Java platform, there does not have to be a single set of supported locales, since each class maintains its own localizations. Nevertheless, there is a consistent set of localizations supported by the classes of the Java Platform. Other implementations of the Java platform may support different locales. Those supported by Sun's Java SE Runtime Environments are summarized in the web page Supported Locales.

Localized Resources

All locale-sensitive classes must be able to access resources customized for the locales they support. To aid in the process of localization, it helps to have these resources grouped together by locale and separated from the locale-neutral parts of the program.

ResourceBundle Class

The class ResourceBundle is an abstract base class representing containers of resources. Programmers create subclasses of ResourceBundle that contain resources for a particular locale. New resources can be added to an instance of ResourceBundle, or new instances of ResourceBundle can be added to a system without affecting the code that uses them. Packaging resources as classes allows developers to take advantage of Java's class loading mechanism to find resources.

Resource bundles contain locale-specific objects. When a program needs a locale-specific resource, a String object for example, the program can load it from the resource bundle that is appropriate for the current user's locale. In this way, the programmer can write code that is largely independent of the user's locale isolating most, if not all, of the locale-specific information in resource bundles.

This allows Java programmers to write code that can:

  • be easily localized, or translated, into different languages
  • handle multiple locales at once
  • be easily modified later to support even more locales
ResourceBundle.Control Class

ResourceBundle.Control is a nested class of ResourceBundle. It defines methods to be called by the ResourceBundle.getBundle factory methods so that the resource bundle loading behavior may be changed. For example, application specific resource bundle formats, such as XML, could be supported by overriding the methods.

ListResourceBundle Class

ListResourceBundle is an abstract subclass of ResourceBundle that manages resources for a locale in a convenient and easy to use list.

PropertyResourceBundle Class

PropertyResourceBundle is a concrete subclass of ResourceBundle that manages resources for a locale using a set of static strings from a property file.

Date and Time Handling

The java.util.Date class represents a specific instant in time with millisecond precision, independent of time zones and locales.

The Date class contains several methods for the interpretation of dates as year, month, day, hour, minute, and second values, and for formatting and parsing date strings. These methods are incompatible with internationalization, and most of them therefore are deprecated. Instead of them, applications should use the Calendar class to convert between date and time fields, and the DateFormat class to format and parse date strings.

Calendar Class

The class Calendar is an abstract base class which can convert between a point in time (represented as milliseconds from 00:00:00 GMT, Jan 1, 1970) and a set of integers representing the year, month, week and so on. GregorianCalendar is a concrete subclass of Calendar that does this according to the rules of the Gregorian calendar.

Calendar and its subclasses are useful for doing various manipulations with time values. Arithmetic can be performed on a Calendar object's fields and the resulting date determined. A Calendar object can produce all the time field values needed to implement the date-time formatting for a particular language and calendar style. Refer to the web page Supported Calendars for details.

TimeZone Class

The abstract class TimeZone encapsulates a time zone offset from GMT (Greenwich Mean Time) and a possible daylight saving time offset. The TimeZone.getTimeZone factory method can be called to get a TimeZone instance for a time zone ID. The TimeZone.getDefault factory method automatically detects the platform time zone and returns a TimeZone instance that matches the platform time zone.

The Calendar class and its subclasses use the TimeZone class to convert between local time and UTC, which is the internal representation used by Date objects. Most programs will not have to deal with TimeZone objects directly.

Text Processing

Formatting

It is in formatting data for output that many cultural conventions are applied. Numbers, dates, times, and messages may all require formatting before they can be displayed. The Java platform provides a set of flexible formatting classes that can handle both the standard locale formats and programmer defined custom formats. These formatting classes are also able to parse formatted strings back into their constituent objects.

Format Class

The class Format is an abstract base class for formatting locale-sensitive information such as dates, times, messages, and numbers. Three main subclasses are provided: DateFormat, NumberFormat, and MessageFormat. These three also provide subclasses of their own.

DateFormat Class

Dates and times are stored internally in a locale-independent way, but should be formatted so that they can be displayed in a locale-sensitive manner. For example, the same date might be formatted as:

  • November 3, 1997 (English)
  • 3 novembre 1997 (French)

The class DateFormat is an abstract base class for formatting and parsing date and time values in a locale-independent manner. It has a number of static factory methods for getting standard time formats for a given locale.

The DateFormat object uses Calendar and TimeZone objects in order to interpret time values. By default, a DateFormat object for a given locale will use the appropriate Calendar object for that locale and the system's default TimeZone object. The programmer can override these choices if desired.

SimpleDateFormat Class

The class SimpleDateFormat is a concrete class for formatting and parsing dates and times in a locale-sensitive manner. It allows for formatting (milliseconds to text), parsing (text to milliseconds), and normalization.

DateFormatSymbols Class

The class DateFormatSymbols is used to encapsulate localizable date-time formatting data, such as the names of the months, the names of the days of the week, time of day, and the time zone data. The DateFormat and SimpleDateFormat classes both use the DateFormatSymbols class to encapsulate this information.

Usually, programmers will not use the DateFormatSymbols directly. Rather, they will implement formatting with the DateFormat class's factory methods.

NumberFormat Class

The class NumberFormat is an abstract base class for formatting and parsing numeric data. It contains a number of static factory methods for getting different kinds of locale-specific number formats.

The NumberFormat class helps programmers to format and parse numbers for any locale. Code using this class can be completely independent of the locale conventions for decimal points, thousands-separators, the particular decimal digits used, or whether the number format is even decimal. The application can also display a number as a normal decimal number, currency, or percentage:

  • 1,234.5 (decimal number in U.S. format)
  • $1,234.50 (U.S. currency in U.S. format)
  • 1.234,50 € (European currency in German format)
  • 123.450% (percent in German format)

DecimalFormat Class

Numbers are stored internally in a locale-independent way, but should be formatted so that they can be displayed in a locale-sensitive manner. For example, when using "#,###.00" as a pattern, the same number might be formatted as:

  • 1.234,56 (German)
  • 1,234.56 (English)

The class DecimalFormat, which is a concrete subclass of the NumberFormat class, can format decimal numbers. Programmers generally will not instantiate this class directly but will use the factory methods provided.

The DecimalFormat class has the ability to take a pattern string to specify how a number should be formatted. The pattern specifies attributes such as the precision of the number, whether leading zeros should be printed, and what currency symbols are used. The pattern string can be altered if a program needs to create a custom format.

DecimalFormatSymbols Class

The class DecimalFormatSymbols represents the set of symbols (such as the decimal separator, the grouping separator, and so on) needed by DecimalFormat to format numbers. DecimalFormat creates for itself an instance of DecimalFormatSymbols from its locale data. A programmer needing to change any of these symbols can get the DecimalFormatSymbols object from the DecimalFormat object and then modify it.

ChoiceFormat Class

The class ChoiceFormat is a concrete subclass of the NumberFormat class. The ChoiceFormat class allows the programmer to attach a format to a range of numbers. It is generally used in a MessageFormat object for handling plurals. See the "MessageFormat Class" section that follows for more information.

MessageFormat Class

Programs often need to build messages from sequences of strings, numbers and other data. For example, the text of a message displaying the number of files on a disk drive will vary:

  • The disk C contains 100 files.
  • The disk D contains 1 file.
  • The disk F contains 0 files.

If a message built from sequences of strings and numbers is hard-coded, it cannot be translated into other languages. For example, note the different positions of the parameters "3" and "G" in the following translations:

  • The disk G contains 3 files. (English)
  • Il y a 3 fichiers sur le disque G. (French)

The class MessageFormat provides a means to produce concatenated messages in language-neutral way. The MessageFormat object takes a set of objects, formats them, and then inserts the formatted strings into the pattern at the appropriate places.

ParsePosition Class

The class ParsePosition is used by the Format class and its subclasses to keep track of the current position during parsing. The parseObject() method in the Format class requires a ParsePosition object as an argument.

FieldPosition Class

The FieldPosition class is used by the Format class and its subclasses to identify fields in formatted output. One version of the format() method in the Format class requires a FieldPosition object as an argument.

Locale-Sensitive String Operations

Programs frequently need to manipulate strings. Common operations on strings include searching and sorting. Some tasks, such as collating strings or finding various boundaries in text, are surprisingly difficult to get right and are even more difficult when multiple languages must be considered. The Java Platform provides classes for handling many of these common string manipulations in a locale-sensitive manner.

Collator Class

The Collator class performs locale-sensitive string comparison. Programmers use this class to build searching and alphabetical sorting routines for natural language text. Collator is an abstract base class. Its subclasses implement specific collation strategies. One subclass, RuleBasedCollator, is currently provided with the Java Platform and is applicable to a wide set of languages. Other subclasses may be created to handle more specialized needs.

RuleBasedCollator Class

The RuleBasedCollator class, which is a concrete subclass of the Collator class, provides a simple, data-driven, table collator. Using RuleBasedCollator, a programmer can create a customized table-based collator. For example, a programmer can build a collator that will ignore (or notice) uppercase letters, accents, and Unicode combining characters.

CollationElementIterator Class

The CollationElementIterator class is used as an iterator to walk through each character of an international string. Programmers use the iterator to return the ordering priority of the positioned character. The ordering priority of a character, or key, defines how a character is collated in the given Collator object. The CollationElementIterator class is used by the compare() method of the RuleBasedCollator class.

CollationKey Class

A CollationKey object represents a string under the rules of a specific Collator object. Comparing two CollationKey objects returns the relative order of the strings they represent. Using CollationKey objects to compare strings is generally faster than using the Collator.compare() method. Thus, when the strings must be compared multiple times, for example when sorting a list of strings, it is more efficient to use CollationKey objects.

BreakIterator Class

The BreakIterator class indirectly implements methods for finding the position of the following types of boundaries in a string of text:

  • potential line break
  • sentence
  • word
  • character

The conventions on where to break lines, sentences, words, and characters vary from one language to another. Since the BreakIterator class is locale-sensitive, it can be used by programs that perform text operations. For example, consider a a word processing program that can highlight a character, cut a word, move the cursor to the next sentence, or word-wrap at a line ending. This word processing program would use break iterators to determine the logical boundaries in text, enabling it to perform text operations in a locale-sensitive manner.

StringCharacterIterator Class

The StringCharacterIterator class provides the ability to iterate over a string of Unicode characters in a bidirectional manner. This class uses a cursor to move within a range of text, and can return individual characters or their index values. The StringCharacterIterator class implements the character iterator functionality of the CharacterIterator interface.

CharacterIterator Interface

The CharacterIterator interface defines a protocol for bidirectional iteration over Unicode characters. Classes should implement this interface if they want to move about within a range of text and return individual Unicode characters or their index values. CharacterIterator is for searching is useful when performing character searches.

Normalizer Class

The Normalizer class provides methods to transform Unicode text into an equivalent composed or decomposed form. The class supports the Unicode Normalization Forms defined by the Unicode standard.

Locale Sensitive Services SPIs

Locale sensitive services provided by classes in the java.text and java.util packages can be extended by implementing Locale Sensitive Services SPIs for locales the Java runtime has not yet supported. In addition to localized symbols or names for the Currency, Locale, and TimeZone classes in the java.util package, implementations of the following classes in the java.text package can be plugged in with the SPIs.

  • BreakIterator
  • Collator
  • DateFormat
  • DateFormatSymbols
  • DecimalFormatSymbols
  • NumberFormat

Character Encoding Conversion

The Java platform uses Unicode as its native character encoding; however, many Java programs still need to handle text data in other encodings. Java therefore provides a set of classes that convert many standard character encodings to and from Unicode. Java programs that need to deal with non-Unicode text data convert that data into Unicode, process the data as Unicode, then convert the result back to the external character encoding. The InputStreamReader and OutputStreamWriter classes provide methods that can convert between other character encodings and Unicode.

Supported Encodings

The InputStreamReader, OutputStreamWriter, and String classes can convert between Unicode and the set of character encodings listed in the web page Supported Encodings.

Stream I/O

The Java Platform provides features in the java.io package to improve the handling of character data: the Reader and Writer classes, and an enhancement to the PrintStream class.

Reader and Writer Classes

The Reader and Writer class hierarchies provide the ability to perform I/O operations on character streams. These hierarchies parallel the InputStream and OutputStream class hierarchies, but operate on streams of characters rather than streams of bytes. Character streams make it easy to write programs that are not dependent upon a specific character encoding, and are therefore easier to internationalize. The Reader and Writer classes also have the ability to convert between Unicode and other character encodings. Please refer to the Character Streams document for more information about the Reader and Writer class hierarchies.

PrintStream Class

The PrintStream class produces output using the system's default character encoding and line terminator. This change allows methods such as System.out.println() to act more reasonably with non-ASCII data.

Charset Package

The java.nio.charset package provides the underpinnings for character encoding conversion. Applications can use its classes to fine-tune the behavior of built-in character converters. Developers can also create custom converters for character encodings that are not supported by built-in character converters, using the java.nio.charset.spi package.

Text Input

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 Java platform also supports input methods for other languages and the use of entirely different input mechanisms, such as handwriting or speech recognition.

The Java platform enables the use of native input methods provided by the host operating system, such as Windows or Solaris, as well as the implementation and use of input methods written in the Java programming language.

The term input methods does not refer to class methods of the Java programming language.

Input Method Support in Swing

The Swing text components provide an integrated user interface for text input using input methods. Depending on the locale, one of two input styles is used. With on-the-spot (inline) input, the style used for most locales, the input methods insert the text directly into the text component while the text is being composed. With below-the-spot input, the style used for Chinese locales, a separate composition window is used, which is positioned automatically to be near the point where the text is to be inserted after being committed.

An application using Swing text components does not have to coordinate the interaction between the text components and input methods. However, it should call InputContext.endComposition when all text must be committed, such as when a document is saved or printed.

Input Method Framework

The input method framework enables the collaboration between text editing components and input methods in entering text. Programmers who develop text editing components or input methods use this framework. Other application developers generally make only minimal use of it. For example, they should call InputContext.endComposition when all text must be committed, such as when a document is saved or printed.

The Input Method Framework web page contains links to the specifications and API documentation.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback

Sun
Java Software


Internationalization Support

Documentation Contents

Internationalization is the process of designing an application so that it can be adapted to various languages and regions without engineering changes. Sometimes the term internationalization is abbreviated as i18n, because there are 18 letters between the first "i" and the last "n."

An internationalized program has the following characteristics:

  • With the addition of localization data, the same executable can run worldwide.
  • Textual elements, such as status messages and the GUI component labels, are not hardcoded in the program. Instead they are stored outside the source code and retrieved dynamically.
  • Support for new languages does not require recompilation.
  • Culturally-dependent data, such as dates and currencies, appear in formats that conform to the end user's region and language.
  • It can be localized quickly.

Acknowledgment: Much of the design and implementation of the internationalization API is by IBM's Center for Java Technology - Silicon Valley. Java Software of Sun Microsystems is grateful for their work.

Overview

  • Internationalization Overview

Enhancements in Java SE 6

  • Internationalization Enhancements
  • Supported Locales
  • Supported Encodings
  • Supported Calendars

More Information

  • Internationalization Home Page
  • Internationalization Trail of the Java Tutorial
  • Internationalization Articles
  • Frequently Asked Questions
  • Internationalization Tools
  • Fonts
    • Fonts and Text Layout section of the Java 2D API Guide
    • Supported Fonts
    • The Font Configuration Files
  • Input Methods
    • An overview of Input Methods
    • Input Method Framework

Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved.

Feedback

Sun
Java Software


Supported Calendars

This page documents calendar systems supported in Sun's Java SE Development Kit 6 (JDK) and Java SE Runtime Environment 6 (JRE). Other implementations of the Java SE Platform may support different calendar systems.

1. Introduction

Calendar is an abstract base class for converting between a Date object and a set of integer fields such as YEAR, MONTH, DAY, HOUR, and so on. Subclasses of Calendar interpret a Date according to the rules of a specific calendar system. The platform provides one public concrete subclass of Calendar: GregorianCalendar. The factory method, Calendar.getInstance, returns the concrete calendar system implementation for the given Locale. The following are supported calendar systems:

Locale | Calendar System | Since (JRE version)
th_TH (with any variant) | Thai Buddhist calendar | 1.4
ja_JP_JP | Japanese imperial calendar | 1.6
Any except above Locales | Gregorian calendar (GregorianCalendar) | 1.1

2. Thai Buddhist Calendar

In Thailand, the Gregorian calendar system is used with the Buddhist Era-based year numbering. In Buddhist Era (à¸žà¸¸à¸—à¸˜à¸¨à¸±à¸?à¸£à¸²à¸Š) or B.E. (à¸ž.à¸¨.) for short, year 1 corresponds to BCE (BC) 543 (Julian). Therefore, Gregorian year + 543 is the B.E. year value.

The Calendar.getInstance method returns a Thai Buddhist calendar instance if a Thai locale is specified, which is determined by its language and country values. This Thai Buddhist calendar implementation supports dates accurately from B.E. 2484 (1941 Gregorian). The historical calendar system transitions are not supported by the implementation. The Calendar.ERA value for Buddhist Era is 1.

3. Japanese Imperial Calendar

In Japan, the Gregorian calendar system is used with the imperial era-based year numbering. An imperial era starts from an emperor's ascension and its year number is reset to 1 with a new era name. The first year of an imperial era is not in sync with the Gregorian year boundaries, and any day could be the first day of an imperial era. For example, the current era started from January 8, 1989 (Gregorian). However, the month and the day of month numberings are in sync with the Gregorian calendar system.

The Calendar.getInstance method returns a Japanese imperial calendar instance if ja_JP_JP locale is specified. This implementation supports the eras since Meiji with the following transition dates.

Era Name
(in Japanese)
 Era
Abbr.
 ERA
field value
 Transition date and time
(Gregorian)
- (è¥¿æš¦)
 -
 0
 -
Meiji (æ˜Žæ²»)
 M
 1
 1868-01-01 00:00:00 local time
Taisho (å¤§æ£)
 T
 2
 1912-07-30 00:00:00 local time
Showa (æ˜å’Œ)
 S
 3
 1926-12-26 00:00:00 local time
Heisei (å¹³æˆ?)
 H
 4
 1989-01-08 00:00:00 local time

Before Meiji, the Gregorian year numbering is supported. Unlike GregorianCalendar, the Japanese imperial calendar implementation doesn't support any Julian to Gregorian transition, and the year numbering before Gregorian 1 is 0, -1, -2, ..., not 1, 2, 3, ... Strictly speaking, the Gregorian calendar is in use from 1873 (Meiji 5) and other calendar systems were used before that year. However, the implementation defines the first day of Meiji as January 1, 1868, which is not historically accurate. The Japanese decrees related to calendar systems don't specify how to deal with time zones outside of Japan. The implementation assumes that era transitions occur at midnight in local time in any time zone.

In the Calendar API, some fields are in sync with the year value for the era transitions and therefore handle irregular rules in the first year of an imperial era. The following table shows those fields.

Calendar field
 Description
WEEK_OF_YEAR
         To determine the first WEEK_OF_YEAR of year 1 in each era, the same rules as determining the first week by the first day of week and minimal days in the first week values are applied. For example, if the first day of week is SUNDAY and the minimal days in the first week is 1, the WEEK_OF_YEAR value of 1926-12-19 is 52 of Taisho 15 and the value of 1926-12-26 is 1 of Showa 1.
DAY_OF_YEAR
         The DAY_OF_YEAR value of the first day of each era is 1. For example, looking at the transition between the Showa and Heisei eras, the last day of the Showa era (Showa 64.01.07, gregorian value 1989-01-07) is 7 and the next day, which is the first day of the Heisei era (Heisei 1.01.08), is 1. The getLeastMaximum method returns the minimum value of all year 1 lengths in days. As of 2005 (Gregorian), the value is 6.

4. Formatting and Parsing Non-GregorianCalendar Dates

A DateFormat instance has a Calendar instance for internal date-time conversions based on the given Locale or the default one. The same rule is applied for creating a Calendar instance. For example, if ja_JP_JP locale is specified, the DateFormat.getDateInstance method returns a DateFormat instance that handles Japanese imperial calendar dates. The following code:
DateFormat df = DateFormat.getDateInstance(DateFormat.FULL,
                                           new Locale("ja", "JP", "JP"));
System.out.println(df.format(new Date()));
will produce the output, like:
å¹³æˆ?17å¹´10æœˆ25æ—¥
Also, the DateFormat.parse method parses a date string with an imperial era. The following code:
System.out.println(df.parse("å¹³æˆ?å…ƒå¹´10æœˆ25æ—¥"));
will produce the output in the Asia/Tokyo time zone:
Wed Oct 25 00:00:00 JST 1989
Note that a Date object returned by the DateFormat.parse method represents a corresponding Gregorian date. To convert a Date to a Japanese imperial date, the Calendar.setTime method must be used with the given Date.

In SimpleDateFormat, the following rules are applied for the Thai Buddhist and Japanese imperial calendar systems.

Calendar system
         Pattern Letter
         Description
Thai Buddhist calendar
 G
         The number of pattern letters doesn't affect displayed era names.
y
         The same rule of the number of pattern letters as GregorianCalendar is applied.
Japanese imperial calendar
 G
         For formatting, if the number of pattern letters is 4 or more, the long era names (e.g., "å¹³æˆ?") are used. Otherwise, the abbreviations (e.g., "H") are used. For parsing, both the long era names and abbreviations are accepted.
y
         For formatting, if the number of pattern letters is 4 or more, the first year of an era is formatted as the locale specific representation, such as "å…ƒ" in Japanese locale. Other year values are displayed as numbers. The 2- and 4-digit rules of GregorianCalendar date formatting are not applied. For parsing, both the locale specific representation and the number representation are accepted.

If the variant element is "TH" in Thai locale, the Thai digits are used for the date-time formatting. For example, the following code:
DateFormat df = DateFormat.getDateInstance(DateFormat.FULL,
                                           new Locale("th", "TH", "TH"));
System.out.println(df.format(new Date()));
will produce the output, like:
à¸§à¸±à¸™à¸à¸±à¸‡à¸„à¸²à¸£à¸—à¸µà¹ˆ à¹’à¹• à¸•à¸¸à¸¥à¸²à¸„à¸¡ à¸ž.à¸¨. à¹’à¹•à¹”à¹˜

5. Serialization Considerations

When a Calendar object returned by the Calendar.getInstance factory method is serialized and sent to another JVM, deserialization of the object fails if the destination JVM does not support the same Calendar subclass that has been used to create the serialized Calendar object. Please make sure that the same Calendar subclasses are supported in JVMs where you would like to exchange serialized Calendar objects.

Copyright Â© 2005 Sun Microsystems, Inc. All Rights Reserved.
Contact us 		Sun Java Software


Supported Encodings

The classes java.io.InputStreamReader, java.io.OutputStreamWriter, java.lang.String, and classes in the java.nio.charset package can convert between Unicode and a number of other character encodings. The supported encodings vary between different implementations of the Java platform. The class description for java.nio.charset.Charset lists the encodings that any implementation of the Java Platform, Standard Edition 6 is required to support.

Sun's Java SE Development Kit 6 for all platforms (SolarisTM operating environment, Linux, and Microsoft Windows) and the Java SE Runtime Environment 6 for Solaris and Linux support all encodings shown on this page. Sun's Java SE Runtime Environment 6 for Windows may be installed as a complete international version or as a European languages version. The JRE installer by default installs a European languages version if it recognizes that the host operating system only supports European languages. If the installer recognizes that any other language is needed, or if the user requests support for non-European languages in a customized installation, a complete international version is installed. The European languages version only supports the encodings shown in the first table. The international version (which includes the lib/charsets.jar file) supports all encodings shown on this page.

The following tables show the encoding sets supported by Java SE 6. The canonical names used by the new java.nio APIs are in many cases not the same as those used in the java.io and java.lang APIs.

Basic Encoding Set (contained in lib/rt.jar)

Canonical Name for java.nio API | Canonical Name for java.io and java.lang API | Description
IBM00858 | Cp858 | Variant of Cp850 with Euro character
IBM437 | Cp437 | MS-DOS United States, Australia, New Zealand, South Africa
IBM775 | Cp775 | PC Baltic
IBM850 | Cp850 | MS-DOS Latin-1
IBM852 | Cp852 | MS-DOS Latin-2
IBM855 | Cp855 | IBM Cyrillic
IBM857 | Cp857 | IBM Turkish
IBM862 | Cp862 | PC Hebrew
IBM866 | Cp866 | MS-DOS Russian
ISO-8859-1 | ISO8859_1 | ISO-8859-1, Latin Alphabet No. 1
ISO-8859-2 | ISO8859_2 | Latin Alphabet No. 2
ISO-8859-4 | ISO8859_4 | Latin Alphabet No. 4
ISO-8859-5 | ISO8859_5 | Latin/Cyrillic Alphabet
ISO-8859-7 | ISO8859_7 | Latin/Greek Alphabet (ISO-8859-7:2003)
ISO-8859-9 | ISO8859_9 | Latin Alphabet No. 5
ISO-8859-13 | ISO8859_13 | Latin Alphabet No. 7
ISO-8859-15 | ISO8859_15 | Latin Alphabet No. 9
KOI8-R | KOI8_R | KOI8-R, Russian
KOI8-U | KOI8_U | KOI8-U, Ukrainian
US-ASCII | ASCII | American Standard Code for Information Interchange
UTF-8 | UTF8 | Eight-bit Unicode (or UCS) Transformation Format
UTF-16 | UTF-16 | Sixteen-bit Unicode (or UCS) Transformation Format, byte order identified by an optional byte-order mark
UTF-16BE | UnicodeBigUnmarked | Sixteen-bit Unicode (or UCS) Transformation Format, big-endian byte order
UTF-16LE | UnicodeLittleUnmarked | Sixteen-bit Unicode (or UCS) Transformation Format, little-endian byte order
UTF-32 | UTF_32 | 32-bit Unicode (or UCS) Transformation Format, byte order identified by an optional byte-order mark
UTF-32BE | UTF_32BE | 32-bit Unicode (or UCS) Transformation Format, big-endian byte order
UTF-32LE | UTF_32LE | 32-bit Unicode (or UCS) Transformation Format, little-endian byte order
x-UTF-32BE-BOM | UTF_32BE_BOM | 32-bit Unicode (or UCS) Transformation Format, big-endian byte order, with byte-order mark
x-UTF-32LE-BOM | UTF_32LE_BOM | 32-bit Unicode (or UCS) Transformation Format, little-endian byte order, with byte-order mark
windows-1250 | Cp1250 | Windows Eastern European
windows-1251 | Cp1251 | Windows Cyrillic
windows-1252 | Cp1252 | Windows Latin-1
windows-1253 | Cp1253 | Windows Greek
windows-1254 | Cp1254 | Windows Turkish
windows-1257 | Cp1257 | Windows Baltic
Not available | UnicodeBig | Sixteen-bit Unicode (or UCS) Transformation Format, big-endian byte order, with byte-order mark
x-IBM737 | Cp737 | PC Greek
x-IBM874 | Cp874 | IBM Thai
x-UTF-16LE-BOM | UnicodeLittle | Sixteen-bit Unicode (or UCS) Transformation Format, little-endian byte order, with byte-order mark

Extended Encoding Set (contained in lib/charsets.jar)

Canonical Name for java.nio API | Canonical Name for java.io and java.lang API | Description
Big5 | Big5 | Big5, Traditional Chinese
Big5-HKSCS | Big5_HKSCS | Big5 with Hong Kong extensions, Traditional Chinese (incorporating 2001 revision)
EUC-JP | EUC_JP | JISX 0201, 0208 and 0212, EUC encoding Japanese
EUC-KR | EUC_KR | KS C 5601, EUC encoding, Korean
GB18030 | GB18030 | Simplified Chinese, PRC standard
GB2312 | EUC_CN | GB2312, EUC encoding, Simplified Chinese
GBK | GBK | GBK, Simplified Chinese
IBM-Thai | Cp838 | IBM Thailand extended SBCS
IBM01140 | Cp1140 | Variant of Cp037 with Euro character
IBM01141 | Cp1141 | Variant of Cp273 with Euro character
IBM01142 | Cp1142 | Variant of Cp277 with Euro character
IBM01143 | Cp1143 | Variant of Cp278 with Euro character
IBM01144 | Cp1144 | Variant of Cp280 with Euro character
IBM01145 | Cp1145 | Variant of Cp284 with Euro character
IBM01146 | Cp1146 | Variant of Cp285 with Euro character
IBM01147 | Cp1147 | Variant of Cp297 with Euro character
IBM01148 | Cp1148 | Variant of Cp500 with Euro character
IBM01149 | Cp1149 | Variant of Cp871 with Euro character
IBM037 | Cp037 | USA, Canada (Bilingual, French), Netherlands, Portugal, Brazil, Australia
IBM1026 | Cp1026 | IBM Latin-5, Turkey
IBM1047 | Cp1047 | Latin-1 character set for EBCDIC hosts
IBM273 | Cp273 | IBM Austria, Germany
IBM277 | Cp277 | IBM Denmark, Norway
IBM278 | Cp278 | IBM Finland, Sweden
IBM280 | Cp280 | IBM Italy
IBM284 | Cp284 | IBM Catalan/Spain, Spanish Latin America
IBM285 | Cp285 | IBM United Kingdom, Ireland
IBM297 | Cp297 | IBM France
IBM420 | Cp420 | IBM Arabic
IBM424 | Cp424 | IBM Hebrew
IBM500 | Cp500 | EBCDIC 500V1
IBM860 | Cp860 | MS-DOS Portuguese
IBM861 | Cp861 | MS-DOS Icelandic
IBM863 | Cp863 | MS-DOS Canadian French
IBM864 | Cp864 | PC Arabic
IBM865 | Cp865 | MS-DOS Nordic
IBM868 | Cp868 | MS-DOS Pakistan
IBM869 | Cp869 | IBM Modern Greek
IBM870 | Cp870 | IBM Multilingual Latin-2
IBM871 | Cp871 | IBM Iceland
IBM918 | Cp918 | IBM Pakistan (Urdu)
ISO-2022-CN | ISO2022CN | GB2312 and CNS11643 in ISO 2022 CN form, Simplified and Traditional Chinese (conversion to Unicode only)
ISO-2022-JP | ISO2022JP | JIS X 0201, 0208, in ISO 2022 form, Japanese
ISO-2022-KR | ISO2022KR | ISO 2022 KR, Korean
ISO-8859-3 | ISO8859_3 | Latin Alphabet No. 3
ISO-8859-6 | ISO8859_6 | Latin/Arabic Alphabet
ISO-8859-8 | ISO8859_8 | Latin/Hebrew Alphabet
JIS_X0201 | JIS_X0201 | JIS X 0201
JIS_X0212-1990 | JIS_X0212-1990 | JIS X 0212
Shift_JIS | SJIS | Shift-JIS, Japanese
TIS-620 | TIS620 | TIS620, Thai
windows-1255 | Cp1255 | Windows Hebrew
windows-1256 | Cp1256 | Windows Arabic
windows-1258 | Cp1258 | Windows Vietnamese
windows-31j | MS932 | Windows Japanese
x-Big5_Solaris | Big5_Solaris | Big5 with seven additional Hanzi ideograph character mappings for the Solaris zh_TW.BIG5 locale
x-euc-jp-linux | EUC_JP_LINUX | JISX 0201, 0208, EUC encoding Japanese
x-EUC-TW | EUC_TW | CNS11643 (Plane 1-7,15), EUC encoding, Traditional Chinese
x-eucJP-Open | EUC_JP_Solaris | JISX 0201, 0208, 0212, EUC encoding Japanese
x-IBM1006 | Cp1006 | IBM AIX Pakistan (Urdu)
x-IBM1025 | Cp1025 | IBM Multilingual Cyrillic: Bulgaria, Bosnia, Herzegovinia, Macedonia (FYR)
x-IBM1046 | Cp1046 | IBM Arabic - Windows
x-IBM1097 | Cp1097 | IBM Iran (Farsi)/Persian
x-IBM1098 | Cp1098 | IBM Iran (Farsi)/Persian (PC)
x-IBM1112 | Cp1112 | IBM Latvia, Lithuania
x-IBM1122 | Cp1122 | IBM Estonia
x-IBM1123 | Cp1123 | IBM Ukraine
x-IBM1124 | Cp1124 | IBM AIX Ukraine
x-IBM1381 | Cp1381 | IBM OS/2, DOS People's Republic of China (PRC)
x-IBM1383 | Cp1383 | IBM AIX People's Republic of China (PRC)
x-IBM33722 | Cp33722 | IBM-eucJP - Japanese (superset of 5050)
x-IBM834 | Cp834 | IBM EBCDIC DBCS-only Korean
x-IBM856 | Cp856 | IBM Hebrew
x-IBM875 | Cp875 | IBM Greek
x-IBM921 | Cp921 | IBM Latvia, Lithuania (AIX, DOS)
x-IBM922 | Cp922 | IBM Estonia (AIX, DOS)
x-IBM930 | Cp930 | Japanese Katakana-Kanji mixed with 4370 UDC, superset of 5026
x-IBM933 | Cp933 | Korean Mixed with 1880 UDC, superset of 5029
x-IBM935 | Cp935 | Simplified Chinese Host mixed with 1880 UDC, superset of 5031
x-IBM937 | Cp937 | Traditional Chinese Host miexed with 6204 UDC, superset of 5033
x-IBM939 | Cp939 | Japanese Latin Kanji mixed with 4370 UDC, superset of 5035
x-IBM942 | Cp942 | IBM OS/2 Japanese, superset of Cp932
x-IBM942C | Cp942C | Variant of Cp942
x-IBM943 | Cp943 | IBM OS/2 Japanese, superset of Cp932 and Shift-JIS
x-IBM943C | Cp943C | Variant of Cp943
x-IBM948 | Cp948 | OS/2 Chinese (Taiwan) superset of 938
x-IBM949 | Cp949 | PC Korean
x-IBM949C | Cp949C | Variant of Cp949
x-IBM950 | Cp950 | PC Chinese (Hong Kong, Taiwan)
x-IBM964 | Cp964 | AIX Chinese (Taiwan)
x-IBM970 | Cp970 | AIX Korean
x-ISCII91 | ISCII91 | ISCII91 encoding of Indic scripts
x-ISO2022-CN-CNS | ISO2022_CN_CNS | CNS11643 in ISO 2022 CN form, Traditional Chinese (conversion from Unicode only)
x-ISO2022-CN-GB | ISO2022_CN_GB | GB2312 in ISO 2022 CN form, Simplified Chinese (conversion from Unicode only)
x-iso-8859-11 | x-iso-8859-11 | Latin/Thai Alphabet
x-JIS0208 | x-JIS0208 | JIS X 0208
x-JISAutoDetect | JISAutoDetect | Detects and converts from Shift-JIS, EUC-JP, ISO 2022 JP (conversion to Unicode only)
x-Johab | x-Johab | Korean, Johab character set
x-MacArabic | MacArabic | Macintosh Arabic
x-MacCentralEurope | MacCentralEurope | Macintosh Latin-2
x-MacCroatian | MacCroatian | Macintosh Croatian
x-MacCyrillic | MacCyrillic | Macintosh Cyrillic
x-MacDingbat | MacDingbat | Macintosh Dingbat
x-MacGreek | MacGreek | Macintosh Greek
x-MacHebrew | MacHebrew | Macintosh Hebrew
x-MacIceland | MacIceland | Macintosh Iceland
x-MacRoman | MacRoman | Macintosh Roman
x-MacRomania | MacRomania | Macintosh Romania
x-MacSymbol | MacSymbol | Macintosh Symbol
x-MacThai | MacThai | Macintosh Thai
x-MacTurkish | MacTurkish | Macintosh Turkish
x-MacUkraine | MacUkraine | Macintosh Ukraine
x-MS950-HKSCS | MS950_HKSCS | Windows Traditional Chinese with Hong Kong extensions
x-mswin-936 | MS936 | Windows Simplified Chinese
x-PCK | PCK | Solaris version of Shift_JIS
x-windows-50220 | Cp50220 | Windows Codepage 50220 (7-bit implementation)
x-windows-50221 | Cp50221 | Windows Codepage 50221 (7-bit implementation)
x-windows-874 | MS874 | Windows Thai
x-windows-949 | MS949 | Windows Korean
x-windows-950 | MS950 | Windows Traditional Chinese
x-windows-iso2022jp | x-windows-iso2022jp | Variant ISO-2022-JP (MS932 based)

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Contact us

Sun
Java Software


Supported Fonts

The set of supported fonts varies between different implementations of the Java Platform. This page documents font support in Sun's Java SE Development Kit 6 (JDK), and Java SE Runtime Environment 6 (JRE). For the terminology used, see the Font class description.

  • Support for Physical Fonts
  • Support for Logical Fonts
  • The Lucida Fonts

Support for Physical Fonts

Sun's Java SE Runtime Environment supports TrueType and PostScript Type 1 fonts.

Physical fonts need to be installed in locations known to the Java runtime environment. Sun's Java SE Runtime Environments look in two locations: the lib/fonts directory within the JRE itself, and the normal font location(s) defined by the host operating system. If fonts with the same name exist in both locations, the one in the lib/fonts directory is used.

Users can add physical fonts that use a supported font technology by installing them either in the lib/fonts directory within the JRE, or by installing them in a way supported by the host operating system (dropping them into the Fonts folder on Windows, using the pkgadd command on Solaris).

Support for Logical Fonts

Logical font names are mapped to physical fonts in implementation dependent ways. Typically one logical font name maps to several physical fonts in order to cover a large range of characters. Sun's Java SE Runtime Environments use font configuration files to define the mapping.

Users can add a physical font as a fallback font to logical fonts used in Java 2D rendering by installing it in the lib/fonts/fallback directory within the JRE.

The Lucida Fonts

Sun's Java SE Development Kit and Java SE Runtime Environments bundle several physical fonts of the "Lucida" design family. These fonts are also licensed for use in other implementations of the Java Platform. These fonts are physical fonts, but since they come with the Java SE Runtime, they don't depend on the host operating system. Using them provides the benefit of a consistent look and feel across platforms and implementations for a large set of languages.

There are three different type families: "Lucida Sans", "Lucida Sans Typewriter", and "Lucida Bright". Each family has plain, bold, italic, and bold-italic styles. Not all of these are present in all Java SE implementations. For example, the default download bundle of Sun's Java SE Runtime Environment for Windows only contains the Lucida Sans plain font (but note that application developers can include all Lucida fonts with a JRE that they redistribute with an application).

The following table shows which Unicode character blocks are covered by each font family:

Unicode Block | Lucida Sans | Lucida Sans Typewriter | Lucida Bright
Basic Latin | yes | yes | yes
Latin-1 Supplement | yes | yes | yes
Latin Extended-A | yes | yes | yes
Latin Extended-B | partial | partial | partial
IPA Extensions | partial | no | no
Spacing Modifier Letter | partial | partial | partial
Combining Diacritical Marks | partial | no | partial
Greek | yes | yes | yes
Cyrillic | partial | partial | partial
Hebrew | yes | yes | no
Arabic | partial | partial | partial
Devanagari | yes | no | no
Thai | yes | yes | no
General Punctuation | partial | partial | partial
Superscripts and Subscripts | partial | partial | partial
Currency Symbols | partial | partial | partial
Letterlike Symbols | partial | partial | partial
Number Forms | partial | partial | no
Arrows | partial | partial | partial
Mathematical Operators | yes | partial | yes
Enclosed Alphanumerics | partial | no | no
Box Drawings | partial | partial | no
Block Elements | partial | partial | no
Geometric Shapes | partial | partial | partial
Miscellaneous Symbols | partial | partial | no
Dingbats | yes | no | no
Alphabetic Presentation Forms | partial | partial | no
Arabic Presentation Forms-A | partial | partial | partial
Arabic Presentation Forms-B | yes | yes | yes

Note that of the writing systems that are generally fully supported by Sun's Java SE Runtime Environments, the Lucida fonts do not support Chinese (Simplified), Chinese (Traditional), Japanese, and Korean.

The fonts are installed in the Java SE Runtime Environment's lib/fonts directory as the following files (not all of them may be present):

LucidaSansDemiBold.ttf
LucidaSansRegular.ttf
LucidaTypewriterBold.ttf
LucidaTypewriterRegular.ttf
LucidaBrightDemiBold.ttf
LucidaBrightDemiItalic.ttf
LucidaBrightItalic.ttf
LucidaBrightRegular.ttf

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Feedback

Sun
Java Software


Supported Locales

The set of supported locales varies between different implementations of the Java Platform Standard Edition (Java SE) as well as between different areas of functionality.

This page documents locale support in Sun's Java SE Development Kit 6 (JDK) and Java SE Runtime Environment 6 (JRE) in the following areas:

  1. Enabled Locales for java.util and java.text Functionality
  2. Enabled Writing Systems for Java Foundation Classes
    1. Overview
    2. Text Input
    3. Text Rendering
    4. Drag and Drop
  3. User Interface Translation

Sun's Java SE Runtime Environment 6 for Windows may be installed as a complete international version or as a European languages version. The JRE installer by default installs a European languages version if it recognizes that the host operating system only supports European languages. If the installer recognizes that any other language is needed, or if the user requests support for non-European languages in a customized installation, a complete international version is installed. The JRE for Solaris and Linux and the JDK for any platform are always installed as complete international versions.

1. Enabled Locales for java.util and java.text Functionality

The support for locale-sensitive behavior in the java.util and java.text packages is almost entirely platform independent, so all locales are supported in the same way and simultaneously, independent of the host operating system and its localization. The only platform dependent functionality is the setting of the initial default locale and the initial default time zone based on the host operating system's locale and time zone.

Sun's Java SE Development Kit 6 and the international versions of the Java SE Runtime Environment 6 support all locales shown below. The European languages version of the Java SE Runtime Environment 6 supports all locales for the following languages: Albanian, Belarusian, Bulgarian, Catalan, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Icelandic, Indonesian, Italian, Latvian, Lithuanian, Macedonian, Malay, Maltese, Norwegian, Polish, Portuguese, Romanian, Russian, Serbian (Cyrillic), Slovak, Slovenian, Spanish, Swedish, Turkish, Ukrainian.

Supported Locales

Language | Country | Locale ID
Albanian | Albania | sq_AL
Arabic | Algeria | ar_DZ
Arabic | Bahrain | ar_BH
Arabic | Egypt | ar_EG
Arabic | Iraq | ar_IQ
Arabic | Jordan | ar_JO
Arabic | Kuwait | ar_KW
Arabic | Lebanon | ar_LB
Arabic | Libya | ar_LY
Arabic | Morocco | ar_MA
Arabic | Oman | ar_OM
Arabic | Qatar | ar_QA
Arabic | Saudi Arabia | ar_SA
Arabic | Sudan | ar_SD
Arabic | Syria | ar_SY
Arabic | Tunisia | ar_TN
Arabic | United Arab Emirates | ar_AE
Arabic | Yemen | ar_YE
Belarusian | Belarus | be_BY
Bulgarian | Bulgaria | bg_BG
Catalan | Spain | ca_ES
Chinese (Simplified) | China | zh_CN
Chinese (Simplified) | Singapore | zh_SG(*)
Chinese (Traditional) | Hong Kong | zh_HK
Chinese (Traditional) | Taiwan | zh_TW
Croatian | Croatia | hr_HR
Czech | Czech Republic | cs_CZ
Danish | Denmark | da_DK
Dutch | Belgium | nl_BE
Dutch | Netherlands | nl_NL
English | Australia | en_AU
English | Canada | en_CA
English | India | en_IN
English | Ireland | en_IE
English | Malta | en_MT(*)
English | New Zealand | en_NZ
English | Philippines | en_PH(*)
English | Singapore | en_SG(*)
English | South Africa | en_ZA
English | United Kingdom | en_GB
English | United States | en_US
Estonian | Estonia | et_EE
Finnish | Finland | fi_FI
French | Belgium | fr_BE
French | Canada | fr_CA
French | France | fr_FR
French | Luxembourg | fr_LU
French | Switzerland | fr_CH
German | Austria | de_AT
German | Germany | de_DE
German | Luxembourg | de_LU
German | Switzerland | de_CH
Greek | Cyprus | el_CY(*)
Greek | Greece | el_GR
Hebrew | Israel | iw_IL
Hindi | India | hi_IN
Hungarian | Hungary | hu_HU
Icelandic | Iceland | is_IS
Indonesian | Indonesia | in_ID(*)
Irish | Ireland | ga_IE(*)
Italian | Italy | it_IT
Italian | Switzerland | it_CH
Japanese (Gregorian calendar) | Japan | ja_JP
Japanese (Imperial calendar) | Japan | ja_JP_JP
Korean | South Korea | ko_KR
Latvian | Latvia | lv_LV
Lithuanian | Lithuania | lt_LT
Macedonian | Macedonia | mk_MK
Malay | Malaysia | ms_MY(*)
Maltese | Malta | mt_MT(*)
Norwegian (Bokmål) | Norway | no_NO
Norwegian (Nynorsk) | Norway | no_NO_NY
Polish | Poland | pl_PL
Portuguese | Brazil | pt_BR(*)
Portuguese | Portugal | pt_PT(*)
Romanian | Romania | ro_RO
Russian | Russia | ru_RU
Serbian (Cyrillic) | Bosnia and Herzegovina | sr_BA(*)
Serbian (Cyrillic) | Serbia and Montenegro | sr_CS(*)
Slovak | Slovakia | sk_SK
Slovenian | Slovenia | sl_SI
Spanish | Argentina | es_AR
Spanish | Bolivia | es_BO
Spanish | Chile | es_CL
Spanish | Colombia | es_CO
Spanish | Costa Rica | es_CR
Spanish | Dominican Republic | es_DO
Spanish | Ecuador | es_EC
Spanish | El Salvador | es_SV
Spanish | Guatemala | es_GT
Spanish | Honduras | es_HN
Spanish | Mexico | es_MX
Spanish | Nicaragua | es_NI
Spanish | Panama | es_PA
Spanish | Paraguay | es_PY
Spanish | Peru | es_PE
Spanish | Puerto Rico | es_PR
Spanish | Spain | es_ES
Spanish | United States | es_US(*)
Spanish | Uruguay | es_UY
Spanish | Venezuela | es_VE
Swedish | Sweden | sv_SE
Thai (Western digits) | Thailand | th_TH
Thai (Thai digits) | Thailand | th_TH_TH
Turkish | Turkey | tr_TR
Ukrainian | Ukraine | uk_UA
Vietnamese | Vietnam | vi_VN

(*) Data for these locales are derived from the Unicode Consortium's Common Locale Data Repository release 1.4 on an "AS-IS" basis.

2. Enabled Writing Systems for Java Foundation Classes

2.1 Overview

For the Java Foundation Classes (AWT, Swing, 2D, input method framework, drag and drop), locales can generally be characterized by just the writing system; there are no country or language specific distinctions. Writing system support in the JFC depends to some extent on the host operating system, and full support for simultaneous use of multiple languages is not always possible.

We consider a writing system supported by JFC if all functionality provided by JFC works adequately for this writing system in the following situations:

  • On Windows 98, when running on a Windows system localized for a language using that writing system.
  • On Windows 2000, XP, and 2003, when running on a Windows system with both the user locale and the system locale set to a language using that writing system.
  • On Solaris and Linux, when running on a host operating system with the locale set to one using that writing system and one of the encodings shown for that writing system in the table below.

Sun's Java SE Development Kit 6 and the international version of the Java SE Runtime Environment 6 support all writing systems shown below. The European languages version of the Java SE Runtime Environment 6 supports only the Cyrillic, Greek, and Latin writing systems. Peered AWT components are only supported for a subset of the writing systems - see the last column.

Details on various areas of functionality are provided in the sections below.

Supported Writing Systems

Writing System

Languages

Windows Encodings

Solaris Encodings

Linux Encodings

Peered AWT Components

Arabic

Arabic

1256

8859-6,
UTF-8

UTF-8(4)

unsupported

Chinese (Simplified)

Chinese

936,
GB18030

gb2312,
UTF-8,
GBK,
gb18030

GB2312(2),
GB18030(3) (5),
UTF-8(4) (5) (7)

supported

Chinese (Traditional)

Chinese

950,
HKSCS

cns11643,
UTF-8,
BIG5,
BIG5HK

Big5(2) (3),
UTF-8(4) (5)

supported

Cyrillic

Belarusian, Russian etc.

1251

8859-5,
KOI8-R,
ANSI1251,
UTF-8

unsupported

supported

Devanagari

Hindi

UTF-8

UTF-8

unsupported

unsupported

Greek

Greek

1253

8859-7

unsupported

supported

Hebrew

Hebrew

1255

8859-8

UTF-8(4)

unsupported

Japanese

Japanese

932

eucJP(1),
UTF-8,
PCK

eucJP(1) (2) (3),
UTF-8(4) (5) (7)

supported

Korean

Korean

949

5601,
UTF-8

EUC-KR(2) (3),
UTF-8(4) (5)

supported

Latin - Baltic subset

Latvian, Lithuanian

1257

8859-13

unsupported

supported

Latin - Central European subset

Czech, Hungarian, Polish, etc.

1250

8859-2,
UTF-8

unsupported

supported

Latin - Maltese subset

Maltese

UTF-8

UTF-8

unsupported

supported

Latin - Turkic subset

Turkish etc.

1254

8859-9,
UTF-8

unsupported

supported

Latin - Western European subset

English, French, German, Italian, Spanish, Swedish, etc.

1252

8859-1,
8859-15,
UTF-8

ISO-8859-1(2),
UTF-8(3) (4) (5) (6),

supported

Thai

Thai

874

TIS620.2533,
UTF-8

unsupported

unsupported

(1) eucJP on Solaris supports the JIS character sets X 0201, X 0208, and X 0212; eucJP on Linux only X 0201 and X 0208.
(2) on Red Hat Enterprise Linux AS 2.1.
(3) on Red Hat Enterprise Linux 3 AS, ES, and WS.
(4) on Red Hat Enterprise Linux 4 AS, ES, and WS.
(5) on Sun Java Desktop System Release 3.
(6) on SuSE Linux 10 and SuSE Linux Enterprise Server 9.
(7) on Turbolinux 10 Desktop.

2.2 Text Input

Support for text input consists of two parts: interpretation of keyboard layouts, and text composition using input methods. For interpretation of keyboard layouts, the Java SE relies entirely on the host operating system. For text composition using input methods, Java SE supports native input methods using the host operating system's input method manager as well as input methods developed in the Java programming language.

Locale support in input methods implemented in the Java programming language depends solely on the set of installed input methods, not on the host operating system and its localization. However, support for the use of input methods implemented in the Java programming language with peered components is implementation dependent - see below.

Support for keyboard layouts and and native input methods varies between platforms.

Windows

On Windows 98, the JRE supports use of any keyboard layout or IMM-based input method that can be installed into a particular localized version of the host operating system.

On Windows 2000, XP, and 2003, the JRE supports use of any keyboard layout or IMM-based input method.

Global IME is not supported.

Input methods implemented in the Java programming language are supported in all components on all versions of Windows.

Solaris and Linux

The JRE supports use of any keyboard layout or input method that can be used with a particular Solaris or Linux locale.

Input methods implemented in the Java programming language are supported in lightweight components (such as Swing text components), but not in peered components (such as AWT text components).

2.3 Text Rendering

Applications have two options for selecting fonts:

  • Using the logical font names Serif, SansSerif, Dialog, DialogInput, Monospaced.
  • Using a physical font, either requesting it by name or instantiating it using the Font.createFont method.

Text Rendering in Lightweight Components

When using logical font names, text in at least the writing system of the host locale and the Western European subset of the Latin writing system is supported.

When using physical fonts, we need to distinguish between simple and complex writing systems. Simple writing systems have a one-to-one mapping from characters to glyphs, and glyphs are placed on the baseline continuously from left to right. Complex writing systems may use different glyphs for the same character based on context, may form ligatures, may be written from right to left, and may reorder glyphs during line layout, or may have other rules for placing glyphs (in particular for combining marks).

The 2D text rendering system supports any combination of simple writing systems and the complex writing systems listed in the table above. Within these limitations, the range of supported writing systems is determined by the font. A single TrueType font might provide glyphs covering the entire Unicode character set and a Unicode based character-to-glyph mapping. Given such a font, 2D can support all simple writing systems as well as the complex writing systems shown in the table above. Other complex writing systems are not supported.

Text Rendering in Peered Components

When using logical font names, text in at least the writing system of the host operating system's locale is supported.

Physical fonts are not supported in peered components.

Text Rendering in Printing

There are three printing APIs:

  • The 2D printing API, using the java.awt.print.PrinterJob.getPrinterJob method.
  • The AWT printing API, using the java.awt.Toolkit.getPrintJob method.
  • The pluggable services printing API, using the javax.print package.

Text rendering using the AWT and 2D printing API works to the same extent as text rendering on the screen. Text rendering using the pluggable services printing API depends on the printing service used; the services provided by the JRE work to the same extent as text rendering on the screen.

2.4 Drag and Drop

On Windows 98, text in the writing system of the host operating system's localization can be transferred between applications.

On Windows 2000, XP, and 2003, text using the entire Unicode character set can be transferred between applications.

On Solaris and Linux, text in the character encoding of the host operating system's locale can be transferred between applications.

Applications that need to transfer arbitrary text independent of the host operating system, can do so using serialization: Create a Transferable which supports only one flavor: DataFlavor.stringFlavor. This flavor represents the serialized representation of a String. Make sure that the target supports stringFlavor as well. When the transfer occurs, the AWT will serialize out the String on one end and deserialize on the other. This is much slower than a native platform text transfer, but it will succeed where native transfers may not.

3. User Interface Translation

Java SE Runtime Environment

The user interface elements provided by the Java SE Runtime Environment 6, include Swing dialogs, messages written by the runtime environment to the standard output and standard error streams, as well as messages produced by the tools provided with the JRE. These user interface elements are localized into the following languages:

Language | Locale ID
Chinese (Simplified) | zh_CN
Chinese (Traditional) | zh_TW
English | en
French | fr
German | de
Italian | it
Japanese | ja
Korean | ko
Spanish | es
Swedish | sv

Java SE Development Kit

The user interface elements provided by the Java SE Development Kit 6, include messages produced by the tools that are only part of the JDK in addition to the elements provided by the JRE. The additional user interface elements are localized into the following languages:

Language | Locale ID
Chinese (Simplified) | zh_CN
English | en
Japanese | ja

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Feedback

Sun
Java Software


Character streams

Character streams (Introduced in JDKTM 1.1)

Version 1.1 of the JavaTM Development Kit introduced support for character streams to the java.io package.

Prior to JDK 1.1, the standard I/O facilities supported only byte streams, via the InputStream and OutputStream classes and their subclasses. Character streams are like byte streams, but they contain 16-bit Unicode characters rather than eight-bit bytes. They are implemented by the Reader and Writer classes and their subclasses. Readers and Writers support essentially the same operations as InputStreams and OutputStreams, except that where byte-stream methods operate on bytes or byte arrays, character-stream methods operate on characters, character arrays, or strings.

Most of the functionality available for byte streams is also provided for character streams. This is reflected in the name of each character-stream class, whose prefix is usually shared with the name of the corresponding byte-stream class. For example, there is a PushbackReader class that provides the same functionality for character streams that is provided by PushbackInputStream for byte streams.

Why use character streams?

The primary advantage of character streams is that they make it easy to write programs that are not dependent upon a specific character encoding, and are therefore easy to internationalize.

Java stores strings in Unicode, an international standard character encoding that is capable of representing most of the world's written languages. Typical user-readable text files, however, use encodings that are not necessarily related to Unicode, or even to ASCII, and there are many such encodings. Character streams hide the complexity of dealing with these encodings by providing two classes that serve as bridges between byte streams and character streams. The InputStreamReader class implements a character-input stream that reads bytes from a byte-input stream and converts them to characters according to a specified encoding. Similarly, the OutputStreamWriter class implements a character-output stream that converts characters into bytes according a specified encoding and writes them to a byte-output stream.

A second advantage of character streams is that they are potentially much more efficient than byte streams. The implementations of many of Java's original byte streams are oriented around byte-at-a-time read and write operations. The character-stream classes, in contrast, are oriented around buffer-at-a-time read and write operations. This difference, in combination with a more efficient locking scheme, allows the character stream classes to make up for the added overhead of encoding conversion in many cases.

API overview

The character-stream classes have been designed to parallel the existing byte-stream classes in the java.io package. As noted above, the name of each character-stream class ends in Reader or Writer, as appropriate, while its prefix is usually shared with the corresponding byte-stream class, if any. The following table summarizes the new classes; in the left column, indentation indicates subclass relationships.

Character-stream class | Description | Corresponding byte class
Reader | Abstract class for character-input streams | InputStream
BufferedReader | Buffers input, parses lines | BufferedInputStream
LineNumberReader | Keeps track of line numbers | LineNumberInputStream
CharArrayReader | Reads from a character array | ByteArrayInputStream
InputStreamReader | Translates a byte stream into a character stream | (none)
FileReader | Translates bytes from a file into a character stream | FileInputStream
FilterReader | Abstract class for filtered character input | FilterInputStream
PushbackReader | Allows characters to be pushed back | PushbackInputStream
PipedReader | Reads from a PipedWriter | PipedInputStream
StringReader | Reads from a String | StringBufferInputStream
Writer | Abstract class for character-output streams | OutputStream
BufferedWriter | Buffers output, uses platform's line separator | BufferedOutputStream
CharArrayWriter | Writes to a character array | ByteArrayOutputStream
FilterWriter | Abstract class for filtered character output | FilterOutputStream
OutputStreamWriter | Translates a character stream into a byte stream | (none)
FileWriter | Translates a character stream into a byte file | FileOutputStream
PrintWriter | Prints values and objects to a Writer | PrintStream
PipedWriter | Writes to a PipedReader | PipedOutputStream
StringWriter | Writes to a String | (none)

Related changes

PrintStream

The PrintStream class has been modified to use the platform's default character encoding and the platform's default line terminator. Thus each PrintStream incorporates an OutputStreamWriter, and it passes all characters through this writer to produce bytes for output. The println methods use the platform's default line terminator, which is defined by the system property line.separator and is not necessarily a single newline character ('\n'). Bytes and byte arrays written via the existing write methods are not passed through the writer.

The primary motivation for changing the PrintStream class is that it will make System.out and System.err more useful to people writing Java programs on platforms where the local encoding is something other than ASCII. PrintStream is, in other words, provided primarily for use in debugging and for compatibility with existing code. Code that produces textual output should use the new PrintWriter class, which allows the character encoding to be specified or the default encoding to be accepted. For convenience, the PrintWriter class provides constructors that take an OutputStream object and create an intermediate OutputStreamWriter object that uses the default encoding.

Other classes

The following constructors and methods have been deprecated because they do not properly convert between bytes and characters:

String | DataInputStream.readLine()
InputStream | Runtime.getLocalizedInputStream(InputStream)
OutputStream | Runtime.getLocalizedOutputStream(OutputStream)
 | StreamTokenizer(InputStream)
 | String(byte ascii[], int hibyte, int offset, int count)
 | String(byte ascii[], int hibyte)
void | String.getBytes(int srcBegin, int srcEnd, byte dst[], int dstBegin)

Finally, the following constructor and methods have been added:

 | StreamTokenizer(Reader)
byte[] | String.getBytes()
void | Throwable.printStackTrace(PrintWriter)

Copyright © 1997,1999 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


Enhancements in Java I/O

 Contents
  • Enhancements in Java SE 6
  • Enhancements in J2SE 5.0
  • Enhancements in J2SDK 1.4
  • Previous Enhancements

Enhancements in Java SE 6

java.io

One new class is provided:

  • Console - Contains methods to access a character-based console device. The readPassword() methods disable echoing thus they are suitable for retrieval of sensitive data such as passwords. The method System.console() returns the unique console associated with the Java Virtual Machine.

The following new methods were added to File:

  • Methods to retrieve disk usage information:
    • getTotalSpace() returns the size of the partition in bytes
    • getFreeSpace() returns the number of unallocated bytes in the partition
    • getUsableSpace() returns the number of bytes available on the partition and includes checks for write permissions and other operating system restrictions
  • Methods to set or query file permissions:
    • setWritable(boolean writable, boolean ownerOnly) and setWritable(boolean writable) set the owner's or everybody's write permission
    • setReadable(boolean readable, boolean ownerOnly) and setReadable(boolean readable) set the owner's or everybody's read permission
    • setExecutable(boolean executable, boolean ownerOnly) and setExecutable(boolean executable) set the owner's or everybody's execute permission
    • canExecute() tests the value of the execute permission

Constructors were added to the following class:

  • IOException supports exception chaining via the addition of the new constructors IOException(String, Throwable) and IOException(Throwable).

The behavior of the following method was modified:

  • The File.isFile() Windows implementation has been modified to always return false for reserved device names such as CON, NUL, AUX, LPT, etc. Previously it returned true, which customers considered a bug because it was inconsistent with behavior for devices on Unix.

java.nio

  • A new java.nio.channels.SelectorProvider implementation that is based on the Linux epoll event notification facility is included. The epoll facility is available in the Linux 2.6, and newer, kernels. The new epoll-based SelectorProvider implementation is more scalable than the traditional poll-based SelectorProvider implementation when there are thousands of SelectableChannels registered with a Selector. The new SelectorProvider implementation will be used by default when the 2.6 kernel is detected. The poll-based SelectorProvider will be used when a pre-2.6 kernel is detected.
  • The system property sun.nio.ch.disableSystemWideOverlappingFileLockCheck controls whether java.nio.channels.FileChannel.lock() checks whether regions are locked by other instances of FileChannel. Unless this system property is set to true, FileChannel.lock() will throw an OverlappingFileLockException if an application attempts to lock a region that overlaps one that is locked by another instance of FileChannel. The system property exists to provide compatibility with previous releases which do not implement the JVM-wide overlapping file lock check.

Enhancements in J2SE 5.0

java.nio

  • Class javax.net.ssl.SSLEngine was added. The existing J2SDK 1.4.0 secure communication infrastructure, javax.net.ssl.SSLSocket, was based on the I/O model of java.net.Socket. The SSLEngine class abstracts away the I/O model, and leaves developers free to secure communication pathways using alternate types of I/O. SSLEngine can be combined with the New I/O APIs to create implementations such as secure blocking or non-blocking SocketChannels. For details see the JSSE Reference Guide.

Enhancements in Java 2 SDK v1.4

java.io

  • In the FileInputStream and FileOutputStream classes, getChannel methods have been added to return the underlying FileChannel object, and the close methods have been revised to close the underlying channel.
  • Similarly, in the RandomAccessFile class, a getChannel method has been added and the close method has been revised to close the underlying channel. The RandomAccessFile constructors now support the mode characters "s" and "d" to allow the specification, at file-open time, of synchronous writes or synchronous-data writes.
  • In the InputStreamReader and OutputStreamWriter classes, constructors have been added that take a stream and a Charset object, and the getEncoding methods have been revised to return the historical name of the encoding being used. Constructors to InputStreamReader and OutputStreamWriter have been added that take existing CharsetDecoder and CharsetEncoder objects, respectively.

java.nio

  • The nio packages were added to supplement the I/O facilities provided the java.io package.
  • Three new functions were added to the Java Native Interface (JNI) to support direct buffers. For information, see JNI Enhancements in v 1.4.

Previous Enhancements

  • Features of java.io.File describes changes to the java.io.File class.
  • Other changes describes modifications made to the java.io package.
  • Character Streams discusses very early changes to the java.io class package to support character streams.
Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.
Sun


Features of java.io.File in the Java(TM) 2 Platform

Java

Features of java.io.File in the JavaTM 2 Platform

 JDKTM Contents
The File class is a true abstract representation of file and directory pathnames. This allows the File class to better support non-Unix platforms such as Windows, which has a rich pathname syntax involving drive letters, UNC share names, and multiple separator characters. The specification of class File prior to the JavaTM 2 Platform could not handle these cases because it was written in terms of simple string operations.

The following features were introduced in the File class in the Java 2 Platform, v1.2:

  • The ability to create temporary files, and a simple delete-on-exit facility (the new methods createNewFile, createTempFile, and deleteOnExit);
  • Conversion of abstract pathnames to URLs (the new method toURL);
  • Access to the list of filesystem roots (the new method listRoots);
  • Comparability (the new compareTo methods);
  • Access to additional file attributes (the new methods isHidden, setLastModified, and setReadOnly); and
  • A uniform set of methods that accept and return File objects rather than strings (the new methods getParentFile, getAbsoluteFile, getCanonicalFile, and listFiles, and the new interface FileFilter).

Copyright © 1999 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


Java I/O

Documentation Contents

Java I/O support is included in the java.io and java.nio packages. Together these packages include the following features:

  • File and device I/O
  • Object serialization
  • Buffers for data of primitive types
  • Character-set encoders and decoders
  • Channels, a new primitive I/O abstraction
  • A file interface that supports locks and memory mapping
  • A multiplexed, non-blocking I/O facility for writing scalable servers

API Specification

  • java.io (description) - Supports system input and output, object serialization, and basic access to the file system
  • java.nio (description) - Defines buffers for bulk memory operations. Buffers may be allocated in direct memory for high performance.
  • java.nio.channels (description) - Defines channels, an abstraction for devices capable of performing I/O operations; defines selectors for multiplexed, non-blocking I/O
  • java.nio.channels.spi (description) - Provides implementations for channels
  • java.nio.charset (description) - Defines charsets, decoders, and encoders, for translating between bytes and Unicode characters
  • java.nio.charset.spi (description) - Provides implementations for charsets

Examples

  • NIO Examples

Enhancements

  • Enhancements in Java SE 6
  • Enhancements in J2SE 5.0
  • Enhancements in J2SDK 1.4
  • Previous Enhancements

More Information

  • Supported Encodings
  • The Java Tutorial
  • Object Serialization
  • Troubleshooting tips

Copyright © 2002 - 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun
Java Software


Minor changes to java.io in the Java 2 Platform v1.2

Java

Minor changes to java.io in the JavaTM 2 Platform v1.2

 JDKTM Contents
The following changes to package java.io were introduced in version 1.2 of the JavaTM 2 Platform. Minor changes to this package were:
  • The out field of the PrintWriter class is now protected rather than private, so that subclasses may access it
  • The RandomAccessFile class supports a new setLength method; and
  • The StringWriter(int) constructor is now public.

In the Java 2 Platform, the following constructors check for null input parameters:

  • The constructors PrintStream(OutputStream out) and PrintStream(OutputStream out, boolean autoFlush) will throw a NullPointerException if the parameter out is null.

  • The constructors InputStreamReader(InputStream in) and InputStreamReader(InputStream in, String enc) will throw a NullPointerException if the in parameter is null.

  • The constructors OutputStreamWriter(OutputStream out) and OutputStreamWriter(OutputStream out, String enc) will throw a NullPointerException if the out parameter is null.

  • The protected constructors Reader(Object lock) and Writer(Object lock) now throw NullPointerException if the lock parameter is null.

Copyright © 1999 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


Troubleshooting

 JDKTM Contents
  • A File object represents a file name, not an actual file. Such objects are, moreover, immutable. Thus the code
        File f1 = new File("foo");
    File f2 = new File("bar");
    f1.renameTo(f2);
    will rename the file named "foo" (if it exists) to "bar". It will not change the value of the File object referred to by f1; in particular, the expression f1.getPath() will still evaluate to "foo".

  • The available method of the InputStream class and its subclasses does not necessarily return the maximum number of bytes that can be read without blocking. In particular, code of the form
        int n = in.available();
    byte buf = new byte[n];
    in.read(buf);
    is not guaranteed to read all of the remaining bytes from the given input stream. Similarly, the ready method of Reader and its subclasses may return false even if the stream is ready to be read.

  • The read(byte[]) and read(byte[], int, int) methods of InputStream and its subclasses are not guaranteed to read all available bytes. A loop may be required, for example, in order to read a large file into an array:
        for (int off = 0; off < size;) {
        int r = in.read(buf, off, buf.length - off);
        if (r == -1) break;
        off += r;
    }
    Alternatively, a BufferedInputStream may be used. Similar remarks apply to the read(char[]) and read(char[], int, int) methods of Reader and its subclasses.

  • The PrintStream and PrintWriter classes suppress all I/O errors. To see whether an error has occurred, invoke the checkError method.

  • PrintStream and PrintWriter objects do not always flush their output. To arrange for automatic flushing, use the two-argument constructors of these classes and specify true for the second argument.

Copyright © 1999 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


NIO Examples

 Documentation Contents
NIO
The examples in the following table show how to use the NIO APIs.

Source File | Description
Grep.java | Searches a list of files for lines that match a given regular-expression pattern. Demonstrates NIO mapped byte buffers, charsets, and regular expressions.
Sum.java | Computes 16-bit checksums for a list of files. Uses NIO mapped byte buffers for speed.
TimeQuery.java | Asks a list of hosts what time it is. Is a simple, blocking program that demonstrates NIO socket channels (connection and reading), buffer handling, charsets, and regular expressions.
TimeServer.java | Listens for connections and tells callers what time it is. Is a simple, blocking program that demonstrates NIO socket channels (accepting and writing), buffer handling, charsets, and regular expressions.
Ping.java | Connects to each of a list of hosts and measures the time required to complete the connection. Uses a selector and two additional threads to demonstrate non-blocking connects and the multithreaded use of a selector.
NBTimeServer.java | Implements a non-blocking Internet time server.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.
Sun
Java Software


Jar and Zip Change Summary for JDK 6

Java

Jar and Zip Enhancements
This page summarizes enhancements to the jar and zip support provided in JDK 6.

API changes

Two new compressed streams have been added:

  • java.util.zip.DeflaterInputStream: Data read from this stream is compressed.
  • java.util.zip.InflaterOutputStream: Data written to this stream is decompressed.
For example, these can be useful if a client wants to send compressed data over a network. The data can be compressed into packets with DeflaterInputStream, and those packets written over the network connection. The receiving end then reads the compressed packets from the network connection, and decompresses them by writing to an InflaterOutputStream.

Implementation changes

On all platforms, zip files can contain more than 64k entries.

On Windows, some limitations have been removed:

  • File names longer than 256 characters are now supported.
  • The limitation of just over 2,000 simultaneously open zip files has been removed.

Changes to the jar command

There are two changes to the behavior of the jar command:

  • The timestamps of extracted files are those listed in the archive, instead of the time of extraction.
  • When creating a jar, it is possible to specify the entry point for stand-alone applications bundled into an executable jar file. The 'e' option specifies the application entry point by creating or overriding the Main-Class attribute value in the jar file's manifest.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


JAR File Overview

What is JAR?

JAR stands for Java ARchive. It's a file format based on the popular ZIP file format and is used for aggregating many files into one. Although JAR can be used as a general archiving tool, the primary motivation for its development was so that Java applets and their requisite components (.class files, images and sounds) can be downloaded to a browser in a single HTTP transaction, rather than opening a new connection for each piece. This greatly improves the speed with which an applet can be loaded onto a web page and begin functioning. The JAR format also supports compression, which reduces the size of the file and improves download time still further. Additionally, individual entries in a JAR file may be digitally signed by the applet author to authenticate their origin.

JAR is:

  • the only archive format that is cross-platform
  • the only format that handles audio and image files as well as class files
  • backward-compatible with existing applet code
  • an open standard, fully extendable, and written in java
  • the preferred way to bundle the pieces of a java applet

JAR consists of a zip archive, as defined by PKWARE, containing a manifest file and potentially signature files, as defined in the JAR File Specification.

The APPLET tag

Changing the APPLET tag in your HTML page to accomodate a JAR file is simple. The JAR file on the server is identified by the ARCHIVE parameter, where the directory location of the jar file should be relative to the location of the html page:
    <applet code=Animator.class
      archive="jars/animator.jar"
      width=460 height=160>
      <param name=foo value="bar">
    </applet>
Note that the familiar CODE=myApplet.class parameter must still be present. The CODE parameter, as always, identifies the name of the applet where execution begins. However, the class file for the applet and all of its helper classes are loaded from the JAR file.

Th ARCHIVE attribute describes one or more JAR files containing classes and other resources that will be "preloaded". The classes are loaded using an instance of an AppletClassLoader with the given CODEBASE. It takes the form archive = archiveList. The archives in archiveList are separated by ",".

Once the archive file is identified, it is downloaded and separated into its components. During the execution of the applet, when a new class, image or audio clip is requested by the applet, it is searched for first in the archives associated with the applet. If the file is not found amongst the archives that were downloaded, it is searched for on the applet's server, relative to the CODEBASE (that is, it is searched for as in JDK1.0.2).

The archive tag may specify multiple JAR files. Each JAR file must be separated by "," (comma). Each file is downloaded in turn:

    <applet code=Animator.class
      archive="classes.jar ,  images.jar ,  sounds.jar"
      width=460 height=160>
      <param name=foo value="bar">
    </applet>
There can be any amount of white space between entries within the archive parameter. In addition, the archive tag itself is case-insensitive; it can be lower-case, upper-case, or any combination of lower- and upper-case letters, such as ArCHiVe.

Executable JAR Files

On Microsoft Windows systems, the Java 2 Runtime Environment's installation program will register a default association for JAR files so that double-clicking a JAR file on the desktop will automatically run it with javaw -jar. Dependent extensions bundled with the application will also be loaded automatically. This feature makes the end-user runtime environment easier to use on Microsoft Windows systems.

The Solaris 2.6 kernel has already been extended to recognize the special "magic" number that identifies a JAR file, and to invoke java -jar on such a JAR file as if it were a native Solaris executable. A application packaged in a JAR file can thus be executed directly from the command line or by clicking an icon on the CDE desktop.

Sun logo Copyright © 1996-1999 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303-4900 USA. All rights reserved.


JAR File Specification

Contents

  • Introduction
  • The META-INF directory
  • Name-Value pairs and Sections
  • JAR Manifest
    • Overview
    • Manifest Specification
    • Main Attributes
    • Per-Entry Attributes
  • Signed JAR file
    • Overview
    • Signature File
      • Signature validation
      • The Magic Attribute
    • Digital Signatures
  • Notes on Manifest and Signature Files
  • JAR Index
    • Overview
    • Index File Specification
    • Backward Compatibility
  • Service Provider
    • Overview
    • Provider Configuration File
    • Example
  • API Details
  • See Also

Introduction

JAR file is a file format based on the popular ZIP file format and is used for aggregating many files into one. A JAR file is essentially a zip file that contains an optional META-INF directory. A JAR file can be created by the command-line jar tool, or by using the java.util.jar API in the Java platform. There is no restriction on the name of a JAR file, it can be any legal file name on a particular platform.

In many cases, JAR files are not just simple archives of java classes files and/or resources. They are used as building blocks for applications and extensions. The META-INF directory, if it exists, is used to store package and extension configuration data, including security, versioning, extension and services.

The META-INF directory

The following files/directories in the META-INF directory are recognized and interpreted by the Java 2 Platform to configure applications, extensions, class loaders and services:
  • MANIFEST.MF
The manifest file that is used to define extension and package related data.
  • INDEX.LIST
This file is generated by the new "-i" option of the jar tool, which contains location information for packages defined in an application or extension. It is part of the JarIndex implementation and used by class loaders to speed up their class loading process.
  • x.SF
The signature file for the JAR file. 'x' stands for the base file name.
  • x.DSA
The signature block file associated with the signature file with the same base file name. This file stores the digital signature of the corresponding signature file.
  • services/
This directory stores all the service provider configuration files.

Name-Value pairs and Sections

Before we go to the details of the contents of the individual configuration files, some format convention needs to be defined. In most cases, information contained within the manifest file and signature files is represented as so-called "name: value" pairs inspired by the RFC822 standard. We also call these pairs headers or attributes.

Groups of name-value pairs are known as a "section". Sections are separated from other sections by empty lines.

Binary data of any form is represented as base64. Continuations are required for binary data which causes line length to exceed 72 bytes. Examples of binary data are digests and signatures.

Implementations shall support header values of up to 65535 bytes.

All the specifications in this document use the same grammar in which terminal symbols are shown in fixed width font and non-terminal symbols are shown in italic type face.

Specification:

section: *header +newline
nonempty-section: +header +newline
newline: CR LF | LF | CR (not followed by LF)
header: name : value
name: alphanum *headerchar
value: SPACE *otherchar newline *continuation
continuation: SPACE *otherchar newline
alphanum: {A-Z} | {a-z} | {0-9}
headerchar: alphanum | - | _
otherchar: any UTF-8 character except NUL, CR and LF

; Also: To prevent mangling of files sent via straight e-mail, no
; header will start with the four letters "From".

Non-terminal symbols defined in the above specification will be referenced in the following specifications.

JAR Manifest

Overview

A JAR file manifest consists of a main section followed by a list of sections for individual JAR file entries, each separated by a newline. Both the main section and individual sections follow the section syntax specified above. They each have their own specific restrictions and rules.

The main section contains security and configuration information about the JAR file itself, as well as the application or extension that this JAR file is a part of. It also defines main attributes that apply to every individual manifest entry. No attribute in this section can have its name equal to "Name". This section is terminated by an empty line.

The individual sections define various attributes for packages or files contained in this JAR file. Not all files in the JAR file need to be listed in the manifest as entries, but all files which are to be signed must be listed. The manifest file itself must not be listed. Each section must start with an attribute with the name as "Name", and the value must be a relative path to the file, or an absolute URL referencing data outside the archive.

If there are multiple individual sections for the same file entry, the attributes in these sections are merged. If a certain attribute have different values in different sections, the last one is recognized.

Attributes which are not understood are ignored. Such attributes may include implementation specific information used by applications.

Manifest Specification:

manifest-file: main-section newline *individual-section
main-section: version-info newline *main-attribute
version-info: Manifest-Version : version-number
version-number : digit+{.digit+}*
main-attribute: (any legitimate main attribute) newline
individual-section: Name : value newline *perentry-attribute
perentry-attribute: (any legitimate perentry attribute) newline
newline : CR LF | LF | CR (not followed by LF)
digit: {0-9}

In the above specification, attributes that can appear in the main section are referred to as main attributes, whereas attributes that can appear in individual sections are referred to as per-entry attributes. Certain attributes can appear both in the main section and the individual sections, in which case the per-entry attribute value overrides the main attribute value for the specified entry. The two types of attributes are defined as follows.

Main Attributes

Main attributes are the attributes that are present in the main section of the manifest. They fall into the following different groups:
  • general main attributes
    • Manifest-Version:
    • Defines the manifest file version. The value is a legitimate version number, as described in the above spec.
    • Created-By:

    • Defines the version and the vendor of the java implementation on top of which this manifest file is generated. This attribute is generated by the jar tool.
    • Signature-Version:

    • Defines the signature version of the jar file. The value should be a valid version-number string.
    • Class-Path :

    • The value of this attribute specifies the relative URLs of the extensions or libraries that this application or extension needs. URLs are separated by one or more spaces. The application or extension class loader uses the value of this attribute to construct its internal search path.
  • attribute defined for stand-alone applications
  • This attribute is used by stand-alone applications that are bundled into executable jar files which can be invoked by the java runtime directly by running "java -jar x.jar".
    • Main-Class :

    • The value of this attribute defines the relative path of the main application class which the launcher will load at startup time. The value must not have the .class extension appended to the class name.
  • attributes defined for applets
  • These attributes is used by an applet which is bundled into JAR files to define requirements, version and location information for the extensions which this applet depends on. (see Extension Versioning ).
    • Extension-List:

    • This attribute indicates the extensions that are needed by the applet. Each extension listed in this attribute will have a set of additional attributes that the applet uses to specify which version and vendor of the extension it requires.
    • <extension>-Extension-Name :

    • This attribute is the unique name of the extension. The Java Plug-in will compare the value of this attribute with the Extension-Name attribute in the manifests of installed extensions to determine if the extension is installed.
    • <extension>-Specification-Version

    • This attribute specifies the minimum extension specification version that is required by the applet. The Java Plug-in will compare the value of this attribute with the Specification-Version attribute of the installed extension to determine if the extension is up to date.
    • <extension>-Implementation-Version

    • This attritute specifies the minimum extension implementation version number that is required by the applet. The Java Plug-in will compare the value of this attribute with the Implementation-Version attribute of the installed extension to see if a more recent implementation needs to be downloaded.
    • <extension>-Implementation-Vendor-Id

    • This attribute can be used to identify the vendor of an extension implementation if the applet requires an implementation from a specific vendor. The Java Plug-in will compare the value of this attribute with the Implementation-Vendor-Id attribute of the installed extension.
    • <extension>-Implementation-URL

    • This attribute specifies a URL that can be used to obtain the most recent version of the extension if the required version is not already installed.
  • attribute defined for extension identification
  • This attribute is used by extensions to define their unique identity.
    • Extension-Name:
    • This attribute specifies a name for the extension contained in the Jar file. The name should be a unique identifier such as the name of the main package comprising the extension.
  • attributes defined for extension and package versioning and sealing information
  • These attributes define features of the extension which the JAR file is a part of. The value of these attributes apply to all the packages in the JAR file, but can be overridden by per-entry attributes.
    • Implementation-Title :
    • The value is a string that defines the title of the extension implementation.
    • Implementation-Version :

    • The value is a string that defines the version of the extension implementation.
    • Implementation-Vendor :

    • The value is a string that defines the organization that maintains the extension implementation.
    • Implementation-Vendor-Id :

    • The value is a string id that uniquely defines the organization that maintains the extension implementation.
    • Implementation-URL :

    • This attribute defines the URL from which the extension implementation can be downloaded from.
    • Specification-Title :

    • The value is a string that defines the title of the extension specification.
    • Specification-Version :

    • The value is a string that defines the version of the extension specification.
    • Specification-Vendor :

    • The value is a string that defines the organization that maintains the extension specification.
  • Sealed :

  • This attribute defines whether this JAR file is sealed or not. The value can be either "true" or "false", case is ignored. If it is set to "true", then all the packages in the JAR file are defaulted to be sealed, unless they are defined otherwise individually.

Per-Entry Attributes

Per-entry attributes apply only to the individual JAR file entry to which the manifest entry is associated with. If the same attribute also appeared in the main section, then the value of the per-entry attribute overwrites the main attribute's value. For example, if JAR file a.jar has the following manifest content:
Manifest-Version: 1.0
Created-By: 1.2 (Sun Microsystems Inc.)
Sealed: true

Name: foo/bar/
Sealed: false

It means that all the packages archived in a.jar are sealed, except that package foo.bar is not.

The per-entry attributes fall into the following groups:

  • attributes defined for file contents:
    • Content-Type :

    • This attribute can be used to specify the MIME type and subtype of data for a specific file entry in the JAR file. The value should be a string in the form of type/subtype. For example "image/bmp" is an image type with a subtype of bmp (representing bitmap). This would indicate the file entry as an image with the data stored as a bitmap. RFC 1521 and 1522 discuss and define the MIME types definition.
  • attributes defined for package versioning and sealing information:

  • These are the same set of attributes defined above as main attributes that defines the extension package versioning and sealing information. When used as per-entry attributes, these attributes overwrites the main attributes but only apply to the individual file specified by the manifest entry.

  • attribute defined for beans objects:
    • Java-Bean:

    • Defines whether the specific jar file entry is a Java Beans object or not. The value should be either "true" or "false", case is ignored.
  • attributes defined for signing:

  • These attributes are used for signing and verifying purposes. More details here.
    • x-Digest-y:

    • The name of this attribute specifies the name of the digest algorithm used to compute the digest value for the corresponding jar file entry. The value of this attribute stores the actual digest value. The prefix 'x' specifies the algorithm name and the optional suffix 'y' indicates to which language the digest value should be verified against.
    • Magic:

    • This is an optional attribute that can be used by applications to indicate how verifier should compute the digest value contained in the manifest entry. The value of this attribute is a set of comma separated context specific strings. Detailed description is here.

Signed JAR File

Overview

A JAR file can be signed by using the command line jarsigner tool or directly through the java.security API. Every file entry, including non-signature related files in the META-INF directory, will be signed if the JAR file is signed by the jarsigner tool. The signature related files are:
  • META-INF/MANIFEST.MF
  • META-INF/*.SF
  • META-INF/*.DSA
  • META-INF/*.RSA
  • META-INF/SIG-*
Note that if such files are located in META-INF subdirectories, they are not considered signature-related. Case-insensitive versions of these filenames are reserved and will also not be signed.

Subsets of a JAR file can be signed by using the java.security API. A signed JAR file is exactly the same as the original JAR file, except that its manifest is updated and two additional files are added to the META-INF directory: a signature file and a signature block file. When jarsigner is not used, the signing program has to construct both the signature file and the signature block file.

For every file entry signed in the signed JAR file, an individual manifest entry is created for it as long as it does not already exist in the manifest. Each manifest entry lists one or more digest attribute and an optional Magic attribute.

Signature File

Each signer is represented by a signature file with extension .SF. The major part of the file is similar to the manifest file. It consists of a main section which includes information supplied by the signer but not specific to any particular jar file entry. The main section entry, x-Digest-Manifest-Main-Attributes (where x is a digest algorithm), contains the digest value for the main attributes of the manifest.

The main section is followed by a list of individual entries whose names must also be present in the manifest file. Each individual entry must contain at least the digest of its corresponding entry in the manifest file.

Paths or URLs appearing in the manifest file but not in the signature file are not used in the calculation.

Signature Validation

The signature over the signature file is first verified when the manifest is first parsed. For efficiency, this verification can be remembered. Note that this verification only validates the signature directions themselves, not the actual archive files.

The manifest main attributes are also verified when verification information is available in the signature file. If an x-Digest-Manifest-Main-Attributes entry exists in the signature file, it is compared against a digest calculated against the main attributes in the manifest file. If this calculation fails, then jar validation fails. This decision can be remembered, for efficiency. If an x-Digest-Manifest-Main-Attributes entry does not exist in the signature file, its nonexistence does not affect jar validation and the manifest main attributes are not verified.

To validate a file, a digest value in the signature file is compared against a digest calculated against the corresponding entry in the manifest file. Then, a digest value in the manifest file is compared against a digest calculated against the actual data referenced in the "Name:" attribute, which specifies either a relative file path or URL.

Example manifest file:

Manifest-Version: 1.0
Created-By: 1.3 (Sun Microsystems, Inc)

Name: common/class1.class
MD5-Digest: (base64 representation of MD5 digest)

Name: common/class2.class
MD5-Digest: (base64 representation of MD5 digest)
SHA-Digest: (base64 representation of SHA digest)
The corresponding signature file would be:
Signature-Version: 1.0
MD5-Digest-Manifest-Main-Attributes: (base64 representation of MD5 digest)

Name: common/class1.class
MD5-Digest: (base64 representation of MD5 digest)

Name: common/class2.class
MD5-Digest: (base64 representation of MD5 digest)

The Magic Attribute

Another requirement to validate the signature on a given manifest entry is that the verifier understand the value or values of the Magic key-pair value in that entry's manifest entry.

The Magic attribute is optional but it is required that a parser understand the value of an entry's Magic key if it is verifying that entry's signature.

The value or values of the Magic attribute are a set of comma-separated context-specific strings. The spaces before and after the commas are ignored. Case is ignored. The exact meaning of the magic attributes is application specific. These values indicate how to compute the hash value contained in the manifest entry, and are therefore crucial to the proper verification of the signature. The keywords may be used for dynamic or embedded content, multiple hashes for multilingual documents, etc.

Here are two examples of the potential use of Magic attribute in the manifest file:

Name: http://www.scripts.com/index#script1
        SHA-Digest: (base64 representation of SHA hash)
        Magic: JavaScript, Dynamic

        Name: http://www.tourist.com/guide.html
        SHA-Digest: (base64 representation of SHA hash)
        SHA-Digest-French: (base64 representation of SHA hash)
        SHA-Digest-German: (base64 representation of SHA hash)
        Magic: Multilingual

In the first example, these Magic values may indicate that the result of an http query is the script embedded in the document, as opposed to the document itself, and also that the script is generated dynamically. These two pieces of information indicate how to compute the hash value against which to compare the manifest's digest value, thus comparing a valid signature.

In the second example, the Magic value indicates that the document retrieved may have been content-negotiated for a specific language, and that the digest to verify against is dependent on which language the document retrieved is written in.

Digital Signatures

A digital signature is a signed version of the .SF signature file. These are binary files not intended to be interpreted by humans.

Digital signature files have the same filenames as the .SF files but different extensions. The extension varies depending on the type of digital signature.

.RSA      (PKCS7 signature, MD5 + RSA)
.DSA      (PKCS7 signature, DSA)
Digital signature files for signature algorithms not listed above must reside in the META-INF directory and have the prefix "SIG-". The corresonding signature file (.SF file) must also have the same prefix.

For those formats that do not support external signed data, the file shall consist of a signed copy of the .SF file. Thus some data may be duplicated and a verifier should compare the two files.

Formats that support external data either reference the .SF file, or perform calculations on it with implicit reference.

Each .SF file may have multiple digital signatures, but those signatures should be generated by the same legal entity.

File name extensions may be 1 to 3 alphanum characters. Unrecognized extensions are ignored.

Notes on Manifest and Signature Files

Following is a list of additional restrictions and rules that apply to manifest and signature files.
  • Before parsing:

  • If the last character of the file is an EOF character (code 26), the EOF is treated as whitespace. Two newlines are appended (one for editors that don't put a newline at the end of the last line, and one so that the grammar doesn't have to special-case the last entry, which may not have a blank line after it).
  • Attributes:

  • In all cases for all sections, attributes which are not understood are ignored.

    Attribute names are case insensitive. Programs which generate manifest and signature files should use the cases shown in this specification however.

    Attribute names cannot be repeated within a section.

  • Versions:

  • Manifest-Version and Signature-Version must be first, and in exactly that case (so that they can be recognized easily as magic strings). Other than that, the order of attributes within a main section is not significant.
  • Ordering:

  • The order of individual manifest entries is not significant.

    The order of individual signature entries is not significant, except that the digests that get signed are in that order.

  • Line length:

  • No line may be longer than 72 bytes (not characters), in its UTF8-encoded form. If a value would make the initial line longer than this, it should be continued on extra lines (each starting with a single SPACE).
  • Errors:

  • If a file cannot be parsed according to this spec, a warning should be output, and none of the signatures should be trusted.
  • Limitations:

  • Because header names cannot be continued, the maximum length of a header name is 70 bytes (there must be a colon and a SPACE after the name).

    NUL, CR, and LF can't be embedded in header values, and NUL, CR, LF and ":" can't be embedded in header names.

    Implementations should support 65535-byte (not character) header values, and 65535 headers per file. They might run out of memory, but there should not be hard-coded limits below these values.

  • Signers:

  • It is technically possible that different entities may use different signing algorithms to share a single signature file. This violates the standard, and the extra signature may be ignored.
  • Algorithms:

  • No digest algorithm or signature algorithm is mandated by this standard. However, at least one of MD5 and SHA digest algorithm must be supported.

JAR Index

Overview

Since 1.3, JarIndex is introduced to optimize the class searching process of class loaders for network applications, especially applets. Originally, an applet class loader uses a simple linear search algorithm to search each element on its internal search path, which is constructed from the "ARCHIVE" tag or the "Class-Path" main attribute. The class loader downloads and opens each element in its search path, until the class or resource is found. If the class loader tries to find a nonexistent resource, then all the jar files within the application or applet will have to be downloaded. For large network applications and applets this could result in slow startup, sluggish response and wasted network bandwidth. The JarIndex mechanism collects the contents of all the jar files defined in an applet and stores the information in an index file in the first jar file on the applet's class path. After the first jar file is downloaded, the applet class loader will use the collected content information for efficient downloading of jar files.

The existing jar tool is enhanced to be able to examine a list of jar files and generate directory information as to which classes and resources reside in which jar file. This directory information is stored in a simple text file named INDEX.LIST in the META-INF directory of the root jar file. When the classloader loads the root jar file, it reads the INDEX.LIST file and uses it to construct a hash table of mappings from file and package names to lists of jar file names. In order to find a class or a resource, the class loader queries the hashtable to find the proper jar file and then downloads it if necessary.

Once the class loader finds a INDEX.LIST file in a particular jar file, it always trusts the information listed in it. If a mapping is found for a particular class, but the class loader fails to find it by following the link, an InvalidJarIndexException is thrown. When this occurs, the application developer should rerun the jar tool on the extension to get the right information into the index file.

To prevent adding too much space overhead to the application and to speed up the construction of the in-memory hash table, the INDEX.LIST file is kept as small as possible. For classes with non-null package names, mappings are recorded at the package level. Normally one package name is mapped to one jar file, but if a particular package spans more than one jar file, then the mapped value of this package will be a list of jar files. For resource files with non-empty directory prefixes, mappings are also recorded at the directory level. Only for classes with null package name, and resource files which reside in the root directory, will the mapping be recorded at the individual file level.

Index File Specification

The INDEX.LIST file contains one or more sections each separated by a single blank line. Each section defines the content of a particular jar file, with a header defining the jar file path name, followed by a list of package or file names, one per line. All the jar file paths are relative to the code base of the root jar file. These path names are resolved in the same way as the current extension mechanism does for bundled extensions.

The UTF-8 encoding is used to support non ASCII characters in file or package names in the index file.

Specification

index file : version-info blankline section*
version-info : JarIndex-Version: version-number
version-number : digit+{.digit+}*
section : body blankline
body : header name*
header : char+.jar newline
name : char+ newline
char : any valid Unicode character except NULL, CR and LF
blankline: newline newline
newline : CR LF | LF | CR (not followed by LF)
digit: {0-9}

The INDEX.LIST file is generated by running jar -i. See the jar man page for more details.

Backward Compatibility

The new class loading scheme is totally backward compatible with applications developed on top of the current extension mechanism. When the class loader loads the first jar file and an INDEX.LIST file is found in the META-INF directory, it would construct the index hash table and use the new loading scheme for the extension. Otherwise, the class loader will simply use the original linear search algorithm.

Service Provider

Overview

Files in the META-INF/services directory are service provider configuration files. A service is a well-known set of interfaces and (usually abstract) classes. A service provider is a specific implementation of a service. The classes in a provider typically implement the interfaces and subclass the classes defined in the service itself. Service providers may be installed in an implementation of the Java platform in the form of extensions, that is, jar files placed into any of the usual extension directories. Providers may also be made available by adding them to the applet or application class path or by some other platform-specific means.

A service is represented by an abstract class. A provider of a given service contains one or more concrete classes that extend this service class with data and code specific to the provider. This provider class will typically not be the entire provider itself but rather a proxy that contains enough information to decide whether the provider is able to satisfy a particular request together with code that can create the actual provider on demand. The details of provider classes tend to be highly service-specific; no single class or interface could possibly unify them, so no such class has been defined. The only requirement enforced here is that provider classes must have a zero-argument constructor so that they may be instantiated during lookup.

Provider-Configuration File

A service provider identifies itself by placing a provider-configuration file in the resource directory META-INF/services. The file's name should consist of the fully-qualified name of the abstract service class. The file should contain a newline-separated list of unique concrete provider-class names. Space and tab characters, as well as blank lines, are ignored. The comment character is '#' (0x23); on each line all characters following the first comment character are ignored. The file must be encoded in UTF-8.

Example

Suppose we have a service class named java.io.spi.CharCodec. It has two abstract methods:

public abstract CharEncoder getEncoder(String encodingName);
  public abstract CharDecoder getDecoder(String encodingName);

Each method returns an appropriate object or null if it cannot translate the given encoding. Typical CharCodec providers will support more than one encoding.

If sun.io.StandardCodec is a provider of the CharCodec service then its jar file would contain the file META-INF/services/java.io.spi.CharCodec. This file would contain the single line:

sun.io.StandardCodec    # Standard codecs for the platform

To locate an encoder for a given encoding name, the internal I/O code would do something like this:

   CharEncoder getEncoder(String encodingName)
  {
Iterator ps =
  Service.providers(CharCodec.class);
while (ps.hasNext())
  {
CharCodec cc = (CharCodec)ps.next();
CharEncoder ce = cc.getEncoder(encodingName);
if (ce != null)
return ce;
}
return null;
}

The provider-lookup mechanism always executes in the security context of the caller. Trusted system code should typically invoke the methods in this class from within a privileged security context.

API Details

Package java.util.jar

See Also

Package java.security
Package java.util.zip

Copyright © 2003 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


Java Archive (JAR) Files

 Documentation Contents
JAR (Java Archive) is a platform-independent file format that aggregates many files into one. Multiple Java applets and their requisite components (.class files, images and sounds) can be bundled in a JAR file and subsequently downloaded to a browser in a single HTTP transaction, greatly improving the download speed. The JAR format also supports compression, which reduces the file size, further improving the download time. In addition, the applet author can digitally sign individual entries in a JAR file to authenticate their origin. It is fully extensible.

Overview and Specification

  • Overview - An overview of JAR Files
  • Specification - The JAR File Specification

API Specification

  • java.util.jar Package
  • java.net.JarURLConnection

Tutorials and Programmer's Guides

  • A tutorial introduction to JAR files.

Enhancements

  • Enhancements in JDKTM 6 - An annotated list of changes between the 5.0 and 6.0 releases to APIs, the jar command, and the jar/zip implementation.

JAR Tools

  • JAR tool reference page for Solaris
  • JAR tool reference page for Windows

More Information

  • Extension Mechanism Architecture - The mechanism for extending the Java platform uses the JAR file format to package extension classes. Manifest attributes are available to support the extension mechanism and related features such as package sealing and package versioning.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


Manifest Specification

 The manifest specification has moved to the JAR File Specification.


The Java™ Programming Language Compiler, javac

 Documentation Contents
The Java programming language compiler, javac, reads source files written in the Java programming language, and compiles them into bytecode class files. Optionally, the compiler can also process annotations found in source and class files using the Pluggable Annotation Processing API. The compiler is a command line tool but can also be invoked using the Java Compiler API.
The compiler accepts source code defined by the Java Language Specification (JLS) and produces class files defined by the Java Virtual Machine Specification (JVMS).

API Specification

  • javax.annotation.processing - Annotation processing.
  • javax.lang.model - Language model used in annotation processing and Compiler Tree API
    • javax.lang.model.element - Language elements.
    • javax.lang.model.type - Types.
    • javax.lang.model.util - Language model utilities.
  • javax.tools - Java Compiler API.
  • com.sun.source.* - Compiler Tree API.

More Information

  • The javac Home Page
  • javac(1) - Manual page [ Solaris™ Operating System | Microsoft Windows ].
  • JLS - The Java Language Specification, Third Edition.
  • JVMS - The Java Virtual Machine Specification, Second Edition.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun


Doclet Overview

Java

The Standard Doclet

 Javadoc Contents

Contents

  • What the Standard Doclet Is
  • Running the Standard Doclet from the Command Line
  • Running the Standard Doclet Programmatically
  • The Source for the Standard Doclet

What the Standard Doclet Is

 The standard doclet is the doclet provided by SunTM that produces Javadoc's default HTML-formatted API output. The API documentation for the JavaTM platform in this JDK documentation is an example of the standard doclet's output. Javadoc uses the standard doclet if no other doclet is specified using Javadoc's -doclet option on the command line.

Running the Standard Doclet from the Command Line

The standard doclet is invoked by default when no other doclet is specified with the -doclet tag on the command line. For example, running
% javadoc myPackage
will use the standard doclet to produce the default-style HTML API documentation for myPackage. Running javadoc without the -doclet option is equivalent to running javadoc using the -doclet option to invoke the standard doclet. That is, the above command is equivalent to
% javadoc -docletpath /home/user/jdk1.5.0/lib/tools.jar \
  -doclet com.sun.tools.doclets.standard.Standard \
  myPackage
or
% javadoc -docletpath /home/user/jdk1.5.0/lib/tools.jar \
  -doclet com.sun.tools.doclets.formats.html.HtmlDoclet \
  myPackage
Both of these approaches are equivalent.

Running the Standard Doclet Programmatically

The Javadoc tool has a programmatic interface with public methods for invoking the Javadoc tool from another program written in the Java language. These methods are located in class com.sun.tools.javadoc.Main in lib/tools.jar. An example is given below.

The disadvantages of calling main are: (1) It can only be called once per run -- for 1.2.x or 1.3.x, use java.lang.Runtime.exec("javadoc ...") if more than one call is needed, (2) it exits using System.exit(), which exits the entire program, and (3) an exit code is not returned.

public static void main(java.lang.String[] args)
Command line interface.
Parameters:
args - The command line parameters.
The execute method overcomes all the disadvantages of main.

public static int execute(java.lang.String[] args)
Programmatic interface.
Parameters:
args - The command line parameters.
Returns:
The return code.
public static int execute(java.lang.String programName,
                          java.lang.String[] args)
Programmatic interface.
Parameters:
programName - Name of the program (for error messages).
args - The command line parameters.
Returns:
The return code.
public static int execute(java.lang.String programName,
                          java.lang.String defaultDocletClassName,
                          java.lang.String[] args)
Programmatic interface.
Parameters:
programName - Name of the program (for error messages).
defaultDocletClassName - Fully qualified class name.
args - The command line parameters.
Returns:
The return code.
public static int execute(java.lang.String programName,
                          java.io.PrintWriter errWriter,
                          java.io.PrintWriter warnWriter,
                          java.io.PrintWriter noticeWriter,
                          java.lang.String defaultDocletClassName,
                          java.lang.String[] args)
Programmatic interface.
Parameters:
programName - Name of the program (for error messages).
errWriter - PrintWriter to receive error messages.
warnWriter - PrintWriter to receive error messages.
noticeWriter - PrintWriter to receive error messages.
defaultDocletClassName - Fully qualified class name.
args - The command line parameters.
Returns:
The return code.

Example

With classpath set to lib/tools.jar in the Java SE, pass in each option and argument as a separate string:

com.sun.tools.javadoc.Main.execute(new String[] {"-d", "docs", "-sourcepath", "/home/usr/src", "p1", "p2"});

The Source for the Standard Doclet

You can download the source code for the standard doclet as part of the Java SE at:
  • Java SE Source Code Release
    (Note: There is a delay between when the JDK is first available and the source code release is available.)
The source files are located in the directory src/share/classes/com/sun/tools/doclets.

Copyright © 1995-2004 Sun Microsystems, Inc. All Rights Reserved.

Sun


Javadoc Technology

 Documentation Contents
Javadoc is a tool that parses the declarations and documentation comments in a set of source files and produces a set of HTML pages describing the classes, interfaces, constructors, methods, and fields.

You can use a Javadoc doclet to customize Javadoc output. A doclet is a program written with the Doclet API that specifies the content and format of the output to be generated by the Javadoc tool. You can write a doclet to generate any kind of text-file output, such as HTML, SGML, XML, RTF, and MIF. SunTM provides a "standard" doclet for generating HTML-format API documentation and an experimental MIF doclet for generating MIF, PDF, FrameMaker, and other formats. Doclets can also be used to perform special tasks not related to producing API documentation.

A taglet is a program that allows you to create and use custom tags that are more flexible than custom tags created with the -tag option. A custom tag is used by a doclet to format and display text from a Javadoc tag. A taglet must implement the taglet interface.

API Specification

  • Doclet API - Documentation for the com.sun.javadoc package, which comprises the Doclet API.
  • Taglet API - Documentation for the com.sun.tools.doclets.Taglet class, which comprises the Taglet API.

Tools

The following pages list all javadoc tags and command-line options for running the the Javadoc tool, with examples for Solaris and Microsoft Windows.
  • Javadoc Tool Reference Page (Solaris)
  • Javadoc Tool Reference Page (Microsoft Windows)

Tutorials and Programmer's Guides

Doclet Information:
  • Doclet Overview - Introduction to doclets with simple examples that illustrate the Doclet API.
  • Running the Standard Doclet - This doclet produces the default HTML-formatted API documentation. Javadoc uses the standard doclet if no other doclet is specified with Javadoc's -doclet option.
  • Transitioning to the 5.0 Doclet API - Tips to extend legacy doclets to support 5.0 new language features.
Taglet Information:
  • Taglet Overview - Introduction to taglets with simple examples that illustrate the Taglet API.

API Enhancements

  • What's New in Javadoc 5.0
  • What's New in Javadoc 1.4.2

More Information

Located in the JavaTM SE Documentation:
  • Deprecation in an API
Located on the Java Software website:
  • Javadoc FAQ - Important tips and workarounds for bugs.
  • Javadoc Forum - Enter into discussions with fellow developers. You must join the Java Developer Connection (free) to take part. Click on "Javadoc Tool" category. This forum is monitored only occasionally by the Javadoc team. If you want a prompt reply from the Javadoc team, use the feedback address below.
  • Javadoc announcements email group - A public one-way mailing list you can subscribe to for receiving major announcements about Javadoc tool, the standard doclet, the MIF doclet, the DocCheck doclet, the localization doclet, and others. Traffic should be light.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

 Feedback 		Sun


What's New in Javadoc 1.2

 Javadoc Enhancements

This document describes the changes made to Javadoc between versions 1.1 and 1.2. It is divided into sections for three types of users: (1) for writers of doc comments, (2) for developers wanting to write doclets (architecture and the Doclet API), and (3) for readers of the javadoc-generated HTML pages (content and format). Further details are given in the "Detailed Changes" section that follows.

SUMMARY OF CHANGES

This summary includes changes for writers of doc comments, changes to the Javadoc tool (the Doclet API) and changes to the content and format of the HTML output of Javadoc (as implemented in the Standard Doclet).

WRITING DOC COMMENTS

Changes for Writing Doc Comments

The following list summarizes in one place all features listed elsewhere that can have an impact on how you would write doc comments.
  • The first sentence of each class description should be a summary statement.
  • Package-level comments are now possible.
  • The first sentence of each package description should be a summary statement.
  • System-wide (overview) comments are now possible.
  • New Javadoc tags are available for use in doc comments.
  • Copies new "doc-files" directory for holding images and examples.
  • Hierarchical destination file structure
  • Possible incompatibilities between 1.1 and 1.2 doc comments

ARCHITECTURE

Doclet API

  • Javadoc now has a Doclet API to which you can write doclets.

CONTENT

New Tags

  • @throws is a synonym for @exception.
  • @see now accepts packages, HTML anchors and quoted strings. It can also take a label.
  • {@link apiname label} is a new tag for in-line links in text.

Provides more API information and links

  • Includes mechanisms for package-level and document-level information.
  • Incorporates one-line summaries for classes and packages like there have been for members.
  • Includes inherited API on class and interface pages.
  • Includes return types in method summaries, and field data types in field summaries.
  • Includes links to interfaces from members that implement that interface.
  • Includes list of subclasses for each class, and implementing classes for each interface.
  • Copies member descriptions from interfaces to implementing classes.
  • Includes a class hierarchy (tree) view for each package.
  • Introduces -link option for linking to external Javadoc-generated documents.
  • Includes list of deprecated API.
  • Omits the keywords native and synchronization (which are not part of the Java spec).
  • Copies new "doc-files" directory for holding images and examples.

Customizable title, header and footer

  • Introduces options for adding a unique title, header, footer, and bottom note. The bottom note is for information like a copyright notice and mailto link.

FORMAT

Image files

  • No longer relies on images for headings and bullets. Instead it uses table cells and horizontal rules to distinguish headings and API.

Style sheet

  • Add HTML style sheets for control of colors, fonts and positioning.

Improved navigation

  • Adds optional HTML frames for lists of packages and classes. You can show or hide these frames with a single click.
  • Navigation bar is now the same from screen-to-screen.
  • Renames "API Users Guide" to "Help".
  • Changes the term "index" to "summary" in headings of class pages for member summaries.
  • Better distinguishes the summary and detail sections from each other.

Index improvements

  • Option exists to break index up to one file per initial character.
  • Index is internationalized to handle Unicode characters.
  • Index now contains the classes and interfaces.

Hierarchical Destination File Structure

  • Change the destination directory from flat to hierarchical. (new in Beta4)

GENERAL

Incompatibilities

  • Describes possible incompatibilities when running Javadoc 1.2 on 1.1 comments

Other Doclets

  • Maintains the ability to generate Javadoc 1.1 HTML output, for those who want it.
  • [Future] Adds the ability to generate MIF output, for importing into FrameMaker.

Future Enhancements After 1.2

  • Allow for incremental builds contributing to a single Javadoc-generated document.

DETAILED CHANGES

These are the detailed changes made to Javadoc from 1.1 to 1.2. Features denoted as "Done" are implemented and tested in 1.2 Beta 4.

CHANGES FOR WRITING DOC COMMENTS

Javadoc 1.2 has the following new requirements and features you should be aware of when writing documentation comments:
The first sentence of each class description should be a summary statement.
Package-level comments are now possible.
The first sentence of each package description should be a summary statement.
System-wide comments are now possible.
New Javadoc tags are available for use in doc comments.
Copies new "doc-files" directory for holding images and examples.
Hierarchical destination file structure
Possible incompatibilities between 1.1 and 1.2 doc comments

ARCHITECTURE - DOCLET API

Javadoc now has a Doclet API to which you can write doclets. This is a major architectural change to Javadoc.
You can use Javadoc doclets to customize Javadoc output. Think of a doclet as a plug-in for text conversion. A doclet is written written to the doclet API to specifies the content and format of the output to be generated by the Javadoc tool. You can write a doclet to generate any kind of text-file output, such as HTML, SGML, XML, RTF, and MIF. Sun provides a "standard" doclet for generating HTML-format API documentation. Doclets can also be used to perform special tasks not related to producing API documentation. For example, a diagnostic doclet could be created to check that all members have documentation comments.

Motivation for New Architecture - The original Javadoc (in 1.0.x and 1.1.x) takes java source files as input and produces HTML as output. The format of the HTML output is hard coded in java. The disadvantage is that developers who want to customize the output are out of luck, unless they have a source license and want to hack some very arcane code. This means technical writers cannot make enhancements they might need, whether minor (such as capitalizing a word, changing color, adding bold, ...) or major (converting to a new format, such as MIF or RTF).

The requirements for the Javadoc re-architecting were:

  • Separate the mechanisms used to parse and process the input source from the specification of the output format.

  • Make the output format specification pluggable.

  • Make the output format specification as comprehensible as possible to tech writers.
New architecture: The javadoc front-end handles command line arguments and java parsing/processing, constructing a root data structure and passes this off to a java "doclet". The doclet would access this data via an API representing packages, classes, methods, fields, and comments, as well as enumerations of these objects. New doclets could be written to this API, or standard doclets could be subclassed to allow minor changes.

CONTENT - NEW TAGS

These tags are actually implemented in the javadoc API, not in the standard doclet.
New tag "@throws" is a synonym for "@exception". This is a convenience, since "throws" is a keyword in the Java language.

Existing tag "@see" now accepts packages, HTML anchors and quoted strings. It can also take a label. An @see tag can refer to a package just like it can refer to a class, method or other API. The HTML anchor is of the form <a href="xxx">XXX</a> and the quoted string is of the form "xxx". For examples, see Javadoc Reference Page. The label is optional and is of the form: "@see name label". If a label is included, it will be displayed instead of the name.

New tag "{@link apiname label}" is for in-line links in text. In previous versions of Javadoc, the only way to include links to API was to use the @see tag or to hard-code HTML. This new in-line tag uses the same algorithm that @see uses to generate the HTML link. The difference is that it places the link in-line rather than under a "See Also" heading.

CONTENT - PROVIDES MORE API INFORMATION AND LINKS

Add to source tree one file per package, named "package.html", dedicated to doc comments. The first sentence of each package description is the summary. Javadoc picks up everything between <body> and </body> and add it to the package summary page "package-summary.html" (which also contains a table of its classes and interfaces). Javadoc copies the first sentence of this to the overview page "overview.html". Therefore, you should not put a title or any other text between <body> and the first sentence.

Outline for package-level comments:

  • Introduction
  • Package Specification
  • Related Documentation

For more information, see Package Level Comments.

Old Behavior: Javadoc 1.1 has no mechanism for including comments specific to a particular package.
NOTE - The above feature requires writers to follow a new Javadoc rule: The first sentence of each package description should be a summary statement.

Add a single system-wide document "overview.html" for the set of packages. Include in it any comments that apply to the all the packages being documented. For example, you might document the following assumption on this page: "NullPointerException is thrown wherever null is passed in, except as noted."

This file belongs in your source tree and can be any filename you specify. By convention, we use the name "overview.html". Specify this filename with the -overview option on the command line when running Javadoc and the file's contents (between the <body> and </body> tags) is inserted into the initial page that appears in the right-hand frame, named overview-summary.html (which was called packages.html in Beta3 and earlier versions).

Old Behavior: Javadoc 1.1 has no mechanism for including comments that apply to all packages.

Javadoc picks up the first sentence one-line summary for each package from package.html and puts it in packages.html. This provides a brief summary of each packages in the list of all packages.
Old Behavior: Javadoc 1.1 has no such summary list.

Pick up the first sentence of each class description and include it in the class summary at package-<class>.html This provides a brief summary of all classes for a given package.
Old Behavior: Javadoc 1.1 has no such summary list.
NOTE - The above feature requires writers to follow a new Javadoc rule: The first sentence of each class description should be a summary statement.

Add inherited API to method and field summaries on class and interface pages.
Old Behavior: In Javadoc 1.1, the inherited members for a given class do not appear on the class page, necessitating following links to discover them.

Include return type and keywords "static", "protected" and "abstract" in the signature in the method summary, since they are needed by someone calling a method. Do not include public, transient, volatile, or final; those appear in the detail section further down the page. Include data type of fields.
Old Behavior: In Javadoc 1.1, method summaries don't indicate the return type. Field summaries don't indicate the field type.

Add "Specified by" for members that implement an interface.
Old Behavior: In Javadoc 1.1, members of a class that implement an interface make no such mention.

Add the list of subclasses at the top of the class page. Also add the subinterfaces and implementing classes at the top of the interface pages.
Old Behavior: Javadoc 1.1 does not list subclasses on a class page.

Copy the description automatically from the method in an interface to its implementing subclass only when the implementing method contains no text. Include a boilerplate statement that says that the text is copied from the interface. The reason for doing this, is that when implementing an interface, the method descriptions are often identical for both the interface and the class. Copying the descriptions manually seems like needless work that is difficult to maintain.
Old Behavior: Javadoc 1.1 does not copy method descriptions from an interface.

Add a tree view for each package. When you are viewing a package or class, the "Tree" link goes to that view, which then has a link to the tree for all packages.
Old Behavior: Javadoc 1.1 has no tree view (class hierarchy) of single packages. The only tree view is of all packages, which, for the JDK, is overwhelming.

Introduce -link option for linking to external Javadoc-generated documents. Default is to not link to external documentation. When someone generates docs, the -link option generates links to documentation for any API referenced by the API being documented. The links can be local or remote (on the Internet).
Old Behavior: Javadoc 1.1 makes no links to documentation outside what is being generated.

Submit bugs against default constructors that should not be documented by Javadoc. We should either deprecate them or remove them as bugs.
(Does not affect Javadoc)
Old Behavior: Javadoc includes all default constructors, whether or not an application developer would ever call them. When it documents default constructors, it leaves their descriptions blank.

Add a deprecated summary page listing all deprecated API. (Eventually we will add links to the replacement API.)
Old Behavior: Javadoc 1.1 does not generate a list of deprecated API.

Mark classes that are deprecated.
Old Behavior: In Javadoc 1.1, deprecated classes are not marked as such in the class list for a given package.

Remove "synchronized" and "native" from signatures. Javadoc generates an API specification. These two keywords do not belong in the signatures of a specification, because they are implementation-specific. The keyword "native" does not need to be documented. The keyword "synchronized" indicates thread-safe behavior that should instead be described in the method descriptions. A thread-safe method itself might not use the "synchronized" keyword but might call private methods that are.
Old Behavior: Javadoc 1.1 includes the keywords "synchronized" and "native".

Copy "doc-files" directory (one per package) for holding images and examples. Javadoc looks for a directory named "doc-files" in each package directory of the source tree and copies that directory and its contents to the destination. The files in "doc-files" are merely copied to the destination and not processed by Javadoc. This means these files cannot contain the standard navigation bar, header or footer, or be included in the index or tree. This directory can contain arbitrary files referenced by doc comments. Examples: images, HTML files, text files, example source code, HTML tables shared by more than one class.

Example: To include a reference to the image file "Button-1.gif" within the description for the java.awt.Button class:

  • In the source tree, create a directory named "doc-files" in the "java/awt/" directory.
  • Put the "Button-1.gif" file in the "doc-files" directory.
  • Add an <img> tag to your doc comment for the Button class:
       /**
    * <img src="doc-files/Button-1.gif">
    */
Java Software has adopted the naming convention starting with "-1" and incrementing for subsequent images. For more details, see Including Images.
Old Behavior: In Javadoc 1.1, running Javadoc generates files with broken links because images are not copied to the destination. (In the JDK, these images are currently mostly screen shots of AWT and Swing components.)

CONTENT - CUSTOMIZABLE TITLE/HEADER/FOOTER

Add the -title option to include a title to first page "packages.html". Example title: "Java Platform 1.2 Core API".
Old Behavior: Javadoc 1.1 has no formal way to add a title to the generated document.

Add -header, -footer, -bottom options for header/footer/bottom on every page. This enables you to put the version number of the API (such as "Java 1.2 Beta 4") on every page so that when you print out a page, you have a record of the version it came from. The "bottom" feature lets you add a copyright notice or feedback email link at the bottom of each page.
Old Behavior: In Javadoc 1.1, the version number by default does not appear on any page.

CONTENT - NO LINKS TO SOURCE FILES

For internal development, having direct links from each Javadoc-generated class page to its source code would be handy. However, we have decided not to include links in the Java API documentation to the Java source code when we generate and publish our API documentation. Hence it becamse a low priority to put that feature into the standard doclet. However, we have made available separately a doclet that generates links to the source code.

FORMAT - IMAGE FILES

Eliminate any required GIF images. Replace the GIF bullets with horizontal rules. Replace the graphic headings (e.g., "Methods", "Fields") with text inside colored table cells.
Old Behavior: Javadoc 1.1 requires GIF images for bullets and headers. These are not necessary, they slow down the display, and they need to be manually copied to the destination.

FORMAT - STYLE SHEET

Add HTML style sheets for control of colors, fonts and positioning. Style sheets are a standardized way of setting the colors, fonts and positioning of text on web pages at runtime. To modify the colors of the table cells or the font sizes in the left-hand frames, modify the file stylesheet.css that is generated by javadoc. There is also a -stylesheetfile option when running javadoc for specifying your own style sheet.

For example, you can change the background cell color of the headings from dark blue to white by editing the file stylesheet.css as follows.

From:

   #TableHeadingColor     { background: #CCCCFF } /* Dark mauve */
To:
   #TableHeadingColor     { background: #FFFFFF } /* Dark mauve */

For a formal description, see Cascading Style Sheets from W3C. For a more practical description, see CSS Reference Table from CNET. (For an introduction, click on "back to intro" from the CSS Reference Table.)

FORMAT - IMPROVED NAVIGATION

Add frames for package, class and member. (For no frames, start at "package-summary.html". For frames, start at "overview-summary.html")
Old Behavior: Javadoc 1.1 has no easy way to access any package, class or member. It requires users to backtrace.

Add "All classes" link to top of package list (upper left frame). When user clicks this, it should display list of all classes in alphabetic order in lower left-hand frame.
Old Behavior: Javadoc 1.1 has no easy way to access any class, regardless of the package it is in. It requires users to go to "Class Hierarchy". It would be nice to have a list of just classes and interfaces.

Develop a single navigation bar that works in all screens. Dim out the unused items.
Old Behavior: In Javadoc 1.1, the standard navigation bar along the top changes dramatically from page to page. There are three different navigation bars: all packages (2 items), a package (3 items), and a class (6 items).

Add another navigation bar to jump to each subsection.
Summary: Inner | Field | Constr | Method Detail: Field | Constr | Method
Old Behavior: Javadoc 1.1 requires you to scroll past the class description to get to the member summaries and detail.

Rename the "API Users Guide" link to "Help". Modify Javadoc to generate a default help file. Add an option -nohelp to omit the "Help" link from the navigation bar if desired. Add an option -helpfile to create a file
Old Behavior: Javadoc 1.1 has a link in packages.html called "API Users Guide". The file it points to is not automatically copied to the destination directory.

HTML frame for members in Javadoc 1.2. This is a feature we had considered adding to the standard doclet but decided not to. We plan to announce a third-party developer to eventually release this feature in a separate doclet.

FORMAT - WEB PAGES

Change the summaries to tables with borders and cell background color. This better distinguishes between summary and detail portions of class files.
Old Behavior: In Javadoc 1.1, both the summary and detail portions both look quite similar, it's not obvious when scrolling down the page which section you are in.

Keep "Index" as the name of the alphabetized list of API at the end of the document. Rename top portion of each package page from "Package Index" to "Package Summary", likewise for top portion of each class page rename "Method Index" to "Method Summary", "Constructor Index" to "Constructor Summary", and "Field Index" to "Field Summary".
Old Behavior: In Javadoc 1.1, the word "index" is used to identify both summaries at the top of class pages, and the alphabetic book-type list containing all the API. This is needlessly confusing.

FORMAT - INDEX IMPROVEMENTS

Add -breakindex option to break the index into a separate file for each letter of alphabet.
Old Behavior: In Javadoc 1.1, the index is a gigantic 1.4MB file for JDK; takes forever to load over Internet.

Add classes and interfaces to the index.
Old Behavior: In Javadoc 1.1, the index lists only constructors and members, not classes or interfaces.

Internationalize the index, to enable any Unicode characters.
Old Behavior: In Javadoc 1.1, the index handles only the alphabet A-Z. (Actually, only A-Y.)

FORMAT - HIERARCHICAL DESTINATION FILE STRUCTURE

Add hierarchical destination directories that replicates the source code tree of one directory per subpackage. Flat structure will no longer be supported. This has the effect of reducing the number of files in a directory by distributing them by package. A side effect is to reduce length of filenames, since package names will be directory names rather than part of the filename. This will make it easier for third parties to generate shorter names (for example, 31-character names for the Macintosh) that retain some meaning.

For example, java.awt.Button.html will now be \java\awt\Button.html Given all the 1.2 changes, the destination file structure for running Javadoc on the java.applet package would now look like file structure.

Old Behavior: Javadoc 1.1 uses a flat structure, where all HTML files sit in a single directory.

INCOMPATIBILITIES

Possible incompatibilities between 1.1 and 1.2 doc comments We have been careful to write Javadoc 1.2 to be compatible with documentation comments written for previous versions of Javadoc. However, there may be a few cases where old documentation comments may not "work" the same when compiled with Javadoc 1.2.

  • Many filenames have changed. The most important change is that the initial page of the generated documentation is now index.html (which sets up HTML frames) instead of packages.html. If you want to avoid frames, the initial page to load is overview-summary.html (which replaces packages.html in 1.1).

  • In the text of comments, writers might have hard-coded in-line links to API names. Because javadoc now generates hierarchical directories, those links would now be broken. The new {@link} tag enables proper in-line links.

OTHER DOCLETS

Maintain Javadoc 1.1 format with its own doclet. This keeps the old look and flat directory structure but with some of the new bug fixes. To access this, use the "-1.1" javadoc option
Old Behavior: - The Javadoc 1.1 format is important for those who has built parsers that operate on and rely on that HTML output.

[Future] Implement a MIF doclet. This will add the ability to generate MIF output, for importing into FrameMaker.
(Plan to do and release separately after 1.2.)
Old Behavior: Javadoc 1.1 has no MIF capability (Javadoc 1.0.2 does).

FUTURE ENHANCEMENTS - TO DO IN A RELEASE AFTER 1.2

Allow for incremental builds contributing to a single Javadoc-generated document. Would be useful to save the intermediate format from each Javadoc run and allow merging of those intermediate formats into a complete document, with fully correct index, tree, class hierarchy, subclasses list, etc.
(Not done - planned for a release after 1.2)
Old Behavior: Javadoc 1.1 does not allow incremental building of documentation.

Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


What's New in Javadoc 1.3

 Javadoc Enhancements

This document describes the changes made to the Javadoc tool between versions 1.2.2 and 1.3.

New Features

Added {@docRoot} - This is a new Javadoc tag that represents the path from any class page up to the root directory of the generated documentation hierarchy. The purpose of this tag is to allow you to make a link to a single web page from all generated pages, such as to a copyright page or corporate logo from the footers of all generated pages. (This tag was broken in 1.3 Beta) (Request #4197510)

MIF doclet. This adds the ability to generate MIF output, for importing into FrameMaker and eventual conversion to PDF, PS, RTF, Word, or WordPerfect.
IMPORTANT - The MIF doclet is not included in the Java 2 SDK. You must obtain it separately from: MIF Doclet home page

Bug Fixes

4260169: Added <code> HTML tag to "Overrides", "Specified By" and "Tags copied from".

4276757: Fixed Javadoc to document inherited public members of package-private classes.

4214932: Fixed bug where private fields/methods were documented as inherited.

4216836: The "Specified by:" link has been added for a method in an interface implementing a method from a superinterface.

4227539: We now list interfaces found walking all the way up the hierarchy tree. For interfaces, added "All superinterfaces: A, B, C". For classes, added "All implemented interfaces: A, B, C".

4233601: In inner class summary, fixed bug where Exceptions were mistakenly listed as Interfaces.

4216434: Fixed Javadoc -help option which didn't print all the options (-helpfile, -stylesheetfile).

4235271: Fixed bug where overriding method in Interface is now shown as "Specified By".

4231274: Added a missing space ahead of parenthetical phrase "(also extends...)"

4285930: Changed second argument of -linkoffline so that if supplying a relative path, you should make it relative to the destination directory (supplied with -d) rather than relative to the current directory from where javadoc is run.

Future Enhancements

To possibly do in a release after 1.3
XML Doclet - for a standardized representation of static program information of a set of packages. This might possibly allow developers to incrementally build a single document from separate Javadoc runs. By saving the intermediate representation from each Javadoc run, it would allow merging of those into a complete document, with fully updated index, tree, class hierarchy, subclasses list, etc.

Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


What's New in Javadoc 1.4

 Javadoc Tool

This document describes the changes made to the Javadoc tool between versions 1.3 and 1.4. You can also see a concise list of outstanding bugs listed at important new bugs and regressions, and can view listings from our database at Important Bug Fixes and Changes.

  • Summary of New Tags and Options
  • Possible Incompatibilities
  • Running Javadoc
  • Writing Doc Comments
  • Output Content
  • Doclet API
  • Standard Doclet Code Change
  • Javadoc Tool Front End

Summary of New Tags and Options

Here is a brief summary of the new tags and options.
New Tags
{@linkplain}, {@inheritDoc}, @serial, {@value}

New Options
-breakiterator, -docfilessubdirs -exclude, -excludedocfilessubdir -nocomment, -noqualifier, -quiet, -source, -linksource, -subpackages, -tag, -taglet

Possible Incompatibilities

The following changes can affect the way your existing doc comments are interpreted or displayed:
  • New sentence break for first sentence
  • Javadoc copies @throws comments more conservatively

Running Javadoc

Includes changes that affect command line options, errors and warnings.
Added -subpackages option to recursively traverse all subpackages by passing in a single package root. The -exclude option unconditionally exclude packages from the list of packages to document even if it would otherwise be included by some previous or later -subpackages command-line flag. For example, -subpackages java -exclude java.lang.ref would include java.io, java.util, and java.lang (among others), but not java.lang.ref. (4074234)

Added "-source 1.4" option for assertions - This option documents code that was compiled using "javac -source 1.4", necessary for code that contains assertions. (4400430)

Added public methods to invoke Javadoc tool from within Java - Added a programmatic interface to the Javadoc tool in com.sun.tools.javadoc.Main (consequently, the standard doclet was made re-entrant). For more details, see Standard Doclet. (4113483)

Warning and error messages now contain filename and line number. The line number is to the declaration line rather than to the particular line in the doc comment. Uses the SourcePosition class. (4396665)

Serialized form page enhancements - Javadoc now includes private classes in the serialized form page (without requiring the -private flag). This means the serialized form page can be properly generated in a normal Javadoc run. This was done by adding the method PackageDoc.allClasses(boolean filter) where private and package-private classes are included when filter is false. ( Information Specific to the Doclet API) The method writeReplace() is now included in the serialized form page. Javadoc also now looks at "@serial include" and "@serial exclude" tags and includes or excludes classes accordingly. For more information, see @serial tag. (4290079, 4180839, 4341304)

Documented @files to work with command line options as well as filenames This changes the documentation to conform to the implementation. The @files feature was originally documented in javadoc and javac to allow only filenames, not command line options. This expands the documentation to say that @files also allows command line options. (Also renamed @files to @argfile in the documentation to make it clear it's a file of arguments.) (4469119)

Added -quiet option to shut off non-error messages
Only the warnings and errors appear, making them easier to find. (4217345)

The standard doclet prints its version number in its output stream. Suppressed by -quiet option. (4114089)

Automatically create destination directory (-d). Since a primary function of javadoc is to create files and directories, it seems reasonable to create the root destination directory as well. (4464477)

Document only legal classes - When documenting a package, Javadoc no longer reads files whose names are not composed of legal class names. Example: When passing com.sun.foo into Javadoc, it used to parse every file in the directory com\sun\foo whose name ended with ".java", whether or not the filename, stripped of that suffix, was actually a legal class name. Now Javadoc will parse only files whose names are legal class names. This enables developers to include templates, test source files, or other .java files that will not be documented, by including, for example, a hyphen "-" in its filename. (4398440)

Fixed -linkoffline separator '/' - When running on Microsoft Windows, the -linkoffline option now properly inserts '/' instead of '\' in each link that points to an external class. This bug caused broken links to external classes when documentation that was created by Javadoc on Windows was then browsed on Unix. (4359874)

Removed transitional "-1.1" option - The "-1.1" option was introduced in version 1.2 as a doclet to provide a transition path from Javadoc 1.1 to 1.2. This transition is not necessary for moving to 1.3. The "1.1" doclet did not handle new features of the language (such as inner classes) and because of shared code with the standard doclet was an impediment to maintenance. (4312499)

Writing Doc Comments

Includes changes that affect how doc comments are written, such as new tags.
Added tag interface for custom tags
You can create and use your own custom tags -- both normal standalone tags, similar to @return, and inline tags, similar to {@link}.
  • Simple tags - These are tags with a single text argument. You choose a unique name for a tag and use the -tag option.
  • Complex tags - These are tags with more than one argument, or that need special output. This requires developing a "taglet" class that implements the tag behavior. Then specify the -taglet and -tagletclasspath options (don't use the -tag option).
In both cases, the order of the -tag and -taglet options determine the order they are output. You can mix these options with the standard tags "-tag return", "-tag param" to intersperse them.

For custom inline tags, you must create a taglet. (4282805)

Flag any unknown tags while printing custom tags. This is a part of the custom tag mechanism. When javadoc parses the doc comments, any tag encountered that is not either a standard tag or passed in with -tag or -taglet is considered unknown, and a warning is thrown. (4039014)

When omitting the leading asterisk (*), keep indentation within <PRE> tags. This enables you to paste code examples directly into a doc comment. Indentation is relative to the left margin (rather than the separator /**). (4232882)

Added -breakiterator for new way to determine end of first sentence. We plan to change the algorithm for determining the end of the first sentence in the next major feature release. The -breakiterator option gives you a preview of the new algorithm. In 1.2 and 1.3, the java.text.BreakIterator class was used to determine the end of sentence for all languages but English (4165985). English had its own algorithm, which looked for a period followed by a space. When -breakiterator is omitted, the end of the first sentence is unchanged from 1.2 and 1.3, but warnings are emitted displaying where there would be a difference. Using -breakiterator uses the new algorithm. Differences in the algorithms show up in English as follows: (4165985)

  • Old algorithm - Stops at a period followed by a space or a paragraph-level HTML tag, such as <P>.
  • New algorithm - Stops at a period, question mark or exclamation mark followed by a space if the next word starts with a capital letter. This is meant to handle most abbreviations (such as "Serial no. is valid", but won't handle "Mr. Smith"). Won't stop at HTML tags or sentences that begin with numbers or symbols.

Fixed Javadoc to no longer require method bodies. - You can now run javadoc on .java source files that are pure stub files with no method bodies. This means you can write documentation comments and run Javadoc in the earliest stages of design while creating the API, before writing the implementation. Previously, javadoc complained if you tried to do this, insisting that you add "abstract" to the methods and the classes.

Added {@linkplain}, a plain text version of {@link}. The link's label is displayed in plain text rather than code font. Useful when the label is plain text. (4429628)
Example:

        Refer to {@linkplain add() the overridden method}.

Added {@inheritDoc} tag for inheriting documentation. This tag copies the doc comment from a superclass into the current doc comment. This allows developers to write around the copied text rather than have the inherited text be the only text. Previously, text was copied only if the comment was missing. (4186639)

Javadoc tags @return, @param, and @throws are now individually inherited. In 1.3, they would be inherited only if the entire doc comment was empty. The @see tag is also inherited, but only if there are no @see tags in the overriding element. (4496270)

The @throws documentation is copied from an overridden method to a subclass only when the exception is explicitly declared in the overridden method. In 1.3, the @throws text would be copied to an overriding method, whether or not that method actually could throw that execption. This new behavior may remove some documentation that @throws was properly inheriting. You can use {@inheritDoc} to cause @throws to inherit documentation. (4317583)

Output Content

Includes output text, images, layout, formatting and links.
Includes values of static field constants - Javadoc now documents the values of constant fields. Those values appear on a separate Constant Values page, reachable from "See also: Constant Values" links by each static field. The new inline tag {@value}, when used in a static field comment, returns its value. This tag is useful for inserting the value into a doc comment. (4422788)

This change required adding to the Doclet API the methods FieldDoc.constantValue() and FieldDoc.constantValueExpression() in package com.sun.javadoc. ( Information Specific to the Doclet API) (4320557)

Added -noqualifier option to omit qualifying package name from ahead of class names in output
The previous behavior was as follows: On the page for class p.C, add the package name only to classes not belonging to package p. The argument to -noqualifier is either "all" (all package qualifiers are omitted) or a colon-separate list of packages, with wildcards, to be removed as qualifiers (such as "java.lang:java.awt:javax.*"). (4359889)

Add links to source code, using -linksource option
Creates an HTML version of each source file and adds links to them from the normal documentation. (Named -src in Beta 2. Will rename it to -linksource in the final version, to better differentiate it from -source.) (1242492)

Put current class or package name first in window title.
This enables the name to appear in the Windows task bar when a window is minimized. (Also works in Internet Explorer when frames are turned on.) (4232597)

Generate package page when passing in source filenames (*.java). The docs that are generated should not be any different when passing in package names than when passing in the source filenames for classes in those packages. (4359386)

Put exception class link in throws section in two cases:
(1) there a @throws tag but no text accompanies the tag
(2) if an exception is declared but there is no tag (4074202)

Added -nocomment to suppress description and tags, generating only declarations. Enables re-using source files originally intended for a different purpose. (4464558)

Error exit status - Fixed javadoc to use the exit status of the doclet. (4136558)

Use the -encoding option when reading package.html. (4463408)

Added "All Classes" to navigation bar for improved accessibility (4140824)

Directory doc-files is now copied when passing in .java files - When passing in source files (*.java) to Javadoc, it now copies the "doc-files" directories to the destination. (Formerly, the "doc-files" directories were not copied.) This behavior is now identical to that when passing in package names. (4340814)

Fixed doc-files directory at doc root to be copied to destination.
This enables the inclusion of overview-level documentation to be included. (4256505)

Added -docfilessubdirs to enable deep copy of doc-files - Subdirectories of the "doc-files" directory are now recursively copied to the destination when -docfilessubdirs is used. For example, doc-files/example/images and all its contents would now be copied.If you need it, this option is also available: -excludedocfilessubdir name1>:<name2>... to exclude any doc-files subdirectories with the given names. This prevents the copying of SCCS and other source-code-control subdirectories. Previously, only files directly in "doc-files" were copied. (4385048)

Fixed {@docroot} in HTML frame - The {@docroot} tag is now properly resolved when it appears in the upper left HTML frame (overview-frame.html). (4365290)

Fixed {@docroot} in @see - The {@docroot} tag is now properly resolved when it appears in the text of an @see tag. (4416364)

Fixed {@link} with {@docRoot} - The {@docRoot} tag no longer disables any {@link} tag that follows it in the same comment. (4369014)

"Implements" heading - A doc comment inherited from an abstract method now uses the proper subheading "implements" rather than "overrides". (4318787)

Fixed "Implementing Class" on interface page - Fixed bug on interface page where some classes were not showing up as "implementing class". (4378491)

Fixed display of static initializers - The initializer static {...} caused the "Methods Inherited From" table to start with a comma (,). The underlying bug was that javadoc considered static {} to be an anonymous method. It will no longer appear as a method entry in the generated docs. (4136861)

Properly document fields and methods for private inner classes. (445611)

Corrected "nested classes" terminology - Javadoc now uses the term "nested classes" rather than "inner classes" throughout its headings and subheadings. The definitions are: "A nested class is any class whose declaration occurs within the body of another class or interface." while "An inner class is a nested class that is not static." Therefore, "nested" is the more general term. (4307151)

Doclet API

Information Specific to the Doclet API Doclet API is no longer serializable. - The classes no longer extend serializable. (It would have been impossible, in general, to properly serialize them.) (4125581)

Information Specific to the Doclet API Expose filename and line number of declarations. A new class SourcePosition has been added to the Doclet API, as well as a new method position() in Doc and Tag (see 4192783). These enable the complete decomposing and recomposing of source files. (4192783, 4208989)

Information Specific to the Doclet API Added MethodDoc.overriddenMethod() for returning the list of methods that are overridden.

Information Specific to the Doclet API Improved documentation of the Doclet API.

Information Specific to the Doclet API Potential incompatibility - The Tag interface now has a position() method. Doclets that implement the 1.3 Tag interface (such as MIF Doclet 1.2 Beta 1) will not work with Javadoc 1.4.

Standard Doclet Code Change

Standard doclet code change - In the standard doclet source code, added a configuration argument to the MessageRetriever constructor signature. This may affect code that subclasses the standard doclet. New constructor is now MessageRetriever(Configuration configuration, String resourcelocation) (No bug number)

Javadoc Tool Front End

There are many changes to the Javadoc tool described in the other sections; the most notable one is mentioned here.

Complete reimplementation of the Javadoc tool and API (4400430): - Javadoc now uses the new javac compiler instead of the old.

A few changes in behavior are known. These are not bugs and will probably never be "fixed" in javadoc:

  • Private inner classes are now marked as private. The old javadoc incorrectly marked them as having package protection.
  • static class initialization blocks were reported by the old javadoc as if they were a function named <clinit>. The new javadoc correctly omits them.
  • The old javadoc incorrectly inserted a this$0 parameter to constructors for nested classes. While this agrees with the reflective view of these constructors, it is not correct from the source or the language viewpoint. The new javadoc reports the signature as it appears in the source.
  • The old javadoc sometimes reported the compiler-generated field this$0 as a serializable field. The new javadoc correctly omits mention of this$0 and other synthetic members. See java.util.logging.LogManager.LogProperties for an example.
  • The old javadoc occasionally omitted wildcard import declararations that appeared in the source. For example, in the translation unit for java.io.PipedOutputStream there is a (useless and redundant) "import java.io.*;". The new javadoc correctly includes this in the list of imports.
  • The old javadoc incorrectly reported that a private method overrides a private method with the same signature in the superclass. The new javadoc correctly reports that a private method is never overridden.
  • Some bugs remaining in the new java.io implementation prevent the correct processing of Unicode characters on output. While this is not a javadoc bug per se, it will affect any comparison of the old javadoc output with the new. For an example of the differences, see java.util.regex.Pattern.Caret. The workaround is to use a locale that supports a wider set of Unicode.

Some further known examples of incorrect behavior of the old javadoc are intentionally reproduced in the new javadoc implementation for compatibility. For example, if a class a.A has inner classes and you import them using:

        import a.A.*;
Old Javadoc would incorrectly report (through the Doclet API) an import of:
        import a.*;
There is no way of correctly expressing this import declaration with the current javadoc API.

ClassDoc instances are no longer unique - Prior to 1.4.0, every class being documented was represented by a single ClassDoc instance -- this was an undocumented implementation detail. With 1.4.0, this is no longer true -- the Javadoc tool is capable of creating two different ClassDoc instances that represent the same class. This would break any doclets that mistakenly relied on this fact. One such bug was 4496290: The -use option is severely broken.

Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


What's New in Javadoc 1.4.1

 Javadoc Tool
This document describes the changes made to the Javadoc tool between versions 1.4.0 and 1.4.1. You can also see a concise list of outstanding bugs listed at important new bugs and regressions, and can view listings from our database at Important Bug Fixes and Changes.

The changes listed below include the bug number and whether the fix was in the Javadoc tool front end ("tool") or standard doclet ("stddoclet"). The term "regression" appears for features that worked in 1.3.x, broke in 1.4.0, and have been fixed in 1.4.1.

  • New Features
  • Bug Fixes
    • Running Javadoc
    • Error/Warning Messages
    • Command Line Options
    • Tags
    • Miscellaneous

New Features

Added package and class names as keywords in <META> tags. This should improve search results for search engines that look at <META> tags. (4034096, stddoclet)

Bug Fixes:

Running Javadoc:

Regression: Fixed bug where it mistakenly documented .class files found on classpath (if they belong to packages passed in on the command line). (4548768, tool)

Regression: Fixed to handle packages named *.java. (4507380, tool)

Added better checking to accept only valid source file and package names. (4434834, tool)

Error/Warning Messages

Fixed com.sun.tools.javadoc.Main.execute to not ignore PrintWriters. (4587487, tool)

Added quotes around package name in error message when "\ " (backslash, space) passed in. (4370719, tool)

Command Line Options:

Regression: Fixed -use option, which was severely broken. (4496290, stddoclet)

Regression: Fixed -encoding option for reading source files. (4661481, stddoclet)

Regression: Fixed -link option to handle absolute paths. (4640745, stddoclet)

Fixed hang when -subpackages is passed in topmost package name. (4628237, tool)

Changed diagnostic of -help to 'Display command line options and exit'. (4501697, tool)

Tags:

Regression: Fixed to properly insert </DD> when using multiple @author tags. (4651598, stddoclet)

Regression: Fixed {@docRoot} which had been inserting an extra slash "/". (4524350, stddoclet)

Regression: Fixed @throws in implementing class to override @throws in interface. (4633969, stddoclet)

Regression: Fixed to enable @throws tags to have duplicate error class names. (4525364, stddoclet)

Regression: Fixed {@inheritDoc}, which did not work. (4618686, stddoclet)

Added warning when lowercase {@docroot} is used instead of {@docRoot}. (4662945, stddoclet)

Miscellaneous

Added interface constants to the Constant Field Values list. (4526070, stddoclet)

Corrected boolean constant fields to use true/false rather than 0/1. (4587494, tool)

Removed extra space of indentation for comments that omit leading asterisk. (4587562, tool)

Regression: Fixed StringIndexOutOfBoundsException caused by multiple <a href> tags. (4638015, stddoclet)

Changed so nothing is serializable when Serializable is not on -bootclasspath. (4644960, tool)

Removed "()" from window title when frames are off. (4530730, stddoclet)

Notes for doclet programmers:

The -use option was broken because Doc objects are no longer unique in 1.4.0. To keep track of class and package usage, the standard doclet creates Doc/List hash tables where the key is a ClassDoc or PackageDoc and the List is a list of Doc objects that use the key. This way of determining class and package usage worked fine with previous versions of the Javadoc tool, but it does not seem to work with 1.4.x. A Doc object should not be used as a key in the hash table. They are not unique -- that is, the Javadoc tool seems to be capable of creating two different ClassDoc objects that represent the same class. To fix this bug, we used the qualified name as the key in the hash table. We plan to make Doc objects unique again at some point.

Copyright © 2002 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


What's New in Javadoc 1.4.2

 Javadoc Tool

This document describes the changes made to the Javadoc tool between versions 1.4.1 and 1.4.2.

The changes listed below include the bug number and whether the fix was in the Javadoc tool front end ("tool") or standard doclet ("stddoclet"). The term "regression" appears for features that regressed at some point -- for features that worked in 1.3.x, broke in 1.4.0 or 1.4.1, and have been fixed in 1.4.2.

  • Notable New Features
  • Notable Bug Fixes
  • Notable Known Bugs
  • New Features and Bug Fixes
    • Command Line Options
    • Tags
    • Bad API Specifications
    • HTML & Javascript
    • Invalid HTML
    • Links
    • Running Javadoc
    • Error/Warning Messages
    • Accessibility
    • Doclet API

Notable New Features

  • All known bugs related to the U.S. Government's Section 508 requirements for accessibility have been fixed in this version. (4737558, stddoclet)
  • Include serialVersionUID in Serialized Form (4525039, stddoclet)
  • Can now inherit comments from source files not being documented. Your code can automatically inherit comments from interfaces and classes whose source files are on -sourcepath but are not being passed in on the command line. For example, for J2SE, You can do this by unzipping the src.zip file that ships with the SDK (which does not contain all source files, however), and add its path to -sourcepath. When javadoc runs on your code, it will load the doc comments from those source files as needed. For example, if a class in your code implements java.lang.Comparable, the compareTo(Object) method you implement will inherit the doc comment from java.lang.Comparable. This feature was actually available in 1.4.1. (No bug number, tool)
  • When using the -link (or -linkoffline) option, all @see and {@link} tags now create links to excluded classes. This fix greatly simplifies the ability to link to external classes and members. Previously, an external class needed to be either imported or fully qualified in a declaration in order for @see or {@link} to link to its documentation. Now, the only requirements are that the class be fully qualified and that its API docs appear on the path supplied by -link. (4652655, stddoclet)

    Other new features are listed below.

Notable Bug Fixes

  • Links: Fixed @link of a fully-qualified program element to link to external classes with the -link option. (4652655, tool, REGRESSION)
  • Links: Fixed missing internal links on return/parameter types when .java files are passd in (4628281, tool)
  • Execution: Fixed so duplicate classes are documented (4673477, tool, REGRESSION)
  • Serialized form: Fixed link anchors to classes in serialized form (4521661, stddoclet)
  • Javascript: Internet Explorer Javascript load error when linked by -linkoffline (4645058, stddoclet, REGRESSION)
  • HTML: Fixed so there is no diff when passing in package names or .java file names (4506980, stddoclet)

    Other bug fixes are listed below.

Notable Known Bugs

Bugs that can hang the Javadoc tool and highly noticeable bugs are listed here. You see a concise list of bugs listed at important new Javadoc bugs and regressions, and can view listings from our database at Important Bug Fixes and Changes.
  • Javadoc hangs without any useful message if {@inheritDoc} is used in a member that cannot inherit a comment. (4812240, stddoclet) For example:
    public class C {
    /** {@inheritDoc} */
    public abstract void m() {
    }
}
  • Internet Explorer displays unnecessary horizontal scroll bar in the main content pane when frames are showing. A simple workaround is described in the bug report. (4852280, stddoclet)

New Features and Bug Fixes

All new features and bug fixes in 1.4.2 follow.

Command Line Options

  • New feature: Added -packagesheader option for upper left frame (4766385, stddoclet)
  • New feature: Enable "-tag name" shortcut for "-tag name:a:name" (4695326, stddoclet)
  • New feature: Added -linksourcetab option to convert each tab to n spaces. This option is experimental and may change. (4510979, stddoclet)
  • New feature: The -tag option now allows dash (-) separator for xdoclet tags like @ejb:bean (4750173, stddoclet)
  • New feature: New -keywords option adds member names as meta keyword tags to improve API search (4764726, stddoclet)
  • New feature: Added -Xwerror flag to exit nonzero if there are warnings. (4099527, tool)
  • Bug fix: Fixed option -tag tagname:X:taghead so it no longer requires taghead (4628181, stddoclet)
  • Bug fix: Documented -quiet option to quiet only the standard doclet messages (4714350, stddoclet). Opened a new bug 4702454 to request that it quiet the javadoc tool messages as well.
  • Bug fix: Moved documentation for -source option from doclet options to javadoc tool options -- it has always been a tool option (4760924, stddoclet)
Tags
  • New feature: Javadoc now inherits @throws comments for runtime exceptions (4679573, stddoclet)
  • New feature: Javadoc now warns when first argument of @param is not parameter name (4693440, stddoclet)
  • Bug fix: Now compares fully qualified exception names when inheriting @throws text (4684827, stddoclet)
  • Bug fix: Fixed missing 'Throws' heading when followed only by auto-generated exceptions (4530727, stddoclet)
  • Bug fix: Fixed broken @inheritDoc when inheriting from abstract superclass's interface (4720974, stddoclet)
API Specifications
  • New feature: Now includes serialVersionUID in Serialized Form (4525039 stddoclet)
  • New feature: Can now inherit comments from source files not being documented. Your code can automatically inherit comments from interfaces and classes whose source files are on -sourcepath but are not being passed in on the command line. See example. (No bug number, tool)
  • Bug fix: Fixed missing inherited nested classes from summary table (4638588, stddoclet)
  • Bug fix: Fixed so javadoc no longer incorrectly lists hidden fields (4492178, stddoclet)
  • Bug fix: Added serializable superclass of non-public serializable class (4671694, stddoclet)
  • Bug fix: No longer documents override of private method, such as createBufferStrategy (4634891, stddoclet)
HTML & Javascript
  • New feature: Now includes javadoc version number and build in generated HTML comment (4749707, stddoclet)
  • Bug fix: Added "#anchor" names back to links that point to classes in serialized form page (4521661, stddoclet, REGRESSION)
  • Bug fix: Fixed Javascript IE load error when linked by -linkoffline (4645058, stddoclet, REGRESSION)
  • Bug fix: Fixed so there is no diff when passing in package names or .java file names (4506980, stddoclet)
  • Bug fix: Fixed invalid stylesheet.css file (font-size: normal) (4417174, stddoclet)
  • Bug fix: Fixed window title to not change when loading left frames (javascript, stddoclet) (4747738, stddoclet)
Invalid HTML
  • Bug fix: Added missing whitespace in DOCTYPE declaration (4625400, stddoclet)
  • Bug fix: Fixed invalid HTML in frameset DTD and extra <DL> (4275630, stddoclet)
  • Bug fix: Fixed <NOFRAMES>, which is not allowed outside <FRAMESET> element (4753048, stddoclet)
  • Bug fix: Fixed wrong !DOCTYPE in index-all.html file (4418115, stddoclet)
  • Bug fix: Fixed HTML table tags that were inserted in wrong place in package use page (4415270, stddoclet)
Links
  • Bug fix: Internal links missing from return/param types when .java files passd in (4628281, tool, REGRESSION)
  • Bug fix: Fixed @link of a fully-qualified program element to link to external classes with the -link option (4652655, tool, REGRESSION)
  • Bug fix: Fixed -link and -linkoffline to create proper relative links (4720957, stddoclet)
  • Bug fix: The -linksource option no longer produces '\' in links when run on Windows (4511110, stddoclet)
  • Bug fix: The label in {@link java.lang label} is no longer ignored when linking to a package name (4524136, stddoclet)
  • Bug fix: @link tag no longer malformed when only newline exists between first and second arguments (4739870, stddoclet)
Running Javadoc
  • Bug fix: No longer crashes when test file of unnamed package was included in source directory (4670772, tool)
  • Bug fix: Fixed so duplicate classes are once again documented (4673477, tool, REGRESSION)
  • Bug fix: Empty jarfile on classpath: Fixed so empty jarfile in classpath no longer throws an exception (4697113, stddoclet)
  • Bug fix: Files: When source and destination directories are the same, doc-files are no longer trashed (4258405, stddoclet)

Error/Warning Messages

  • Bug fix: Improve unhelpful error message "foo.jar: Body tag missing from HTML" (4691095, stddoclet)
  • Bug fix: Fixed so javadoc no longer reports errors when classpath jar files contain package.html files (4697040, stddoclet)
  • Bug fix: Fixed erroneous "Parameter foo is documented more than once." warnings. (4745855, stddoclet)
  • Bug fix: Now uses Messager printwriters inead of System.out and System.err (4644257, stddoclet)
Accessibility
  • Bug fix: Add title description to links describing italic style as "interface" (4714257, stddoclet)
  • Bug fix: Added ability to skip over nav bar for accessibility (4638136, stddoclet)
  • Bug fix: Added "summary" attribute to tables for accessibility (4637604, 4775148, stddoclet)
  • Bug fix: Added title attribute to <FRAME> tags for accessibility (4636655, stddoclet)
  • Bug fix: Put <H1>, <H2>, <H3> in proper sequence (4636667, stddoclet)
  • Bug fix: Add text equivalent of ASCII art in class tree for accessibility (4706779, stddoclet)
Doclet API
  • New feature: Extended Doclet API with holder() method in Tag interface (4706525, stddoclet)
  • Bug fix: Doc objects are once again == comparable (4731054, tool, REGRESSION)
  • Bug fix: Fixed bad ClassDoc for nested classes when built from .class files (4694497, tool)
  • Bug fix: Clarified the specification for Doc.position() (4748246, stddoclet)
  • Bug fix: Clarified the specification for RootDoc classes() method (4748234, stddoclet)
  • Bug fix: Clarified the specification for com.sun.javadoc.SeeTag (4754029, stddoclet)
  • Bug fix: Clarified the specification for PackageDoc.ordinaryClasses() needs clarification (4748244, stddoclet)
  • Bug fix: Clarified the specification for "kind" in com.sun.javadoc.Doc (4502589, stddoclet)
  • Bug fix: Clarified the specification for Doc.isClass() and all "class" references (4748245, stddoclet)
  • Bug fix: Clarified the specification for "class" further (4763596, stddoclet)
  • Bug fix: Clarified the specification for PackageDoc.allClasses() method and the term "included" (4748240, stddoclet)
  • Bug fix: Clarified the specification for ProgramElementDoc.qualifiedName() parameter list (4621267, stddoclet)
  • Bug fix: Clarified the specification for RootDoc.classes() and PackageDoc.allClasses() (4748238, stddoclet)

Copyright © 2003 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


What's New in Javadoc 5.0

 Javadoc Tool

This document describes the changes made to the Javadoc tool between versions 1.4.2 and 5.0 (formerly 1.5.0).

The changes listed below include the bug number and whether the fix was in the Javadoc tool front end ("tool") or standard doclet ("stddoclet"). The term "regression" appears for features that regressed at some point -- usually for features that worked in 1.3.x, broke in 1.4.x, and have been fixed in 5.0.

  • Notable New Features
  • Notable Bug Fixes
  • Known Bugs
  • Incompatibilities with Custom Doclets
  • New Features and Bug Fixes
    • Command Line Options
    • Tags and Taglets
    • Links
    • Generated API Specifications
    • Formatting and Invalid HTML
    • Navigation Bar
    • Accessibility
    • Running Javadoc
    • Error/Warning/Status Messages
    • Doclet API

Notable New Features

  • Generics, enums, and varargs: Added support for these new language features in the javadoc tool front-end (Doclet API) (4421066, tool) and standard doclet (4789689, stddoclet, 1 vote)
  • Annotations: Added support for annotations and annotation types in the javadoc tool front-end (Doclet API) (4904495, tool) and standard doclet (4905985, stddoclet)
  • BreakIterator: We have removed the -breakiterator warning messages from 5.0, and have left the default sentence-break algorithm unchanged from earlier releases. That is, the -breakiterator option is not the default in 5.0, nor do we expect it to become the default. This is a reversal from our former intention that the default would change in the "next major release" (5.0). This means if you have not modified your source code to eliminate the breakiterator warnings in 1.4.x, then you don't have to do anything, and the warnings will go away in 5.0. The reason for this reversal is because any benefit to having -breakiterator become the default would be outweighed by the incompatible source change it would require. We regret any extra work and confusion this has caused. (The -breakiterator option was added in 1.4.0; for English locale only, it forces the use of BreakIterator class to determine where the first sentence in a doc comment ends, as BreakIterator already does for other languages.) (4959985, tool)
    Furthermore, in a future release (hopefully 5.1) we will add new javadoc tags (feature request 4921374) to enable you to mark summaries explicitly and avoid using heuristics of any kind.
  • New tags {@literal} and {@code} The {@literal} tag denotes literal text. The enclosed text is interpreted as not containing HTML markup or nested javadoc tags. For example, the doc comment text: {@literal a<B>c} displays in the generated HTML page unchanged: a<B>c -- that is, the <B> is not interpreted as bold.
    The {@code} tag formats literal text in the code font; {@code abc} is equivalent to <code>{@literal abc}</code>.
  • Tag {@value arg}: This inline tag now accepts the name of a program element: {@value package.class#field}. This enables it to be used in any doc comment, not just in the doc comment of the constant field. (4764045, stddoclet, 2 votes)
  • package-info.java: You can now create a source file with this name to store package comments and annotations. It can be used in place of package.html (which supports only comments, not annotations). If package-info.java is present, javadoc should ignore package.html and look instead for the package doc comment immediately preceding the (possibly annotated) package declaration. The javadoc tool handles the selection and parsing of package-info.java and package.html and passes the doc comments to the doclet. See Package Comment Files.
  • @Deprecated annotation: This is a new annotation in 5.0 that should be used in addition to the @deprecated tag for deprecating program elements. The Java Language Specification now requires compilers to issue warnings when the @Deprecated annotation (but not necessarily the tag) is used. The @deprecated tag provides a place to describe what replaces the deprecated program element. See @Deprecated annotation.
  • Standard doclet reimplementation - The standard doclet and MIF doclet were re-implemented to share as much code as possible. This has made it possible to reduce the number of bugs in both doclets and raise the capabilities of the MIF doclet to that of the standard doclet. (The new MIF doclet has not yet been released -- it will probably be named version 1.4 Beta 1.) The key reason we merged these two doclets is because they both try to generate essentially the same document but in different formats (HTML and PDF). (4638723, stddoclet, 2 votes)
    We plan to publish this shared code as a doclet toolkit, as described on the Javadoc home page.

    All new features are listed below.

Notable Bug Fixes

  • Option -tag: (regression) Fixed -tag so its name can once again contain a dash "-", as it allowed in 1.4.1. (4920381, stddoclet, 59 votes)
  • Hang due to {@inheritDoc}: No longer hangs when {@inheritDoc} (1) cannot inherit or (2) inherits from super-superinterface. (4812240, stddoclet, 18 votes)
  • Tag @param: (regression) Fixed @param so the parameter name (the first argument) is printed even if incorrect, as it worked in 1.3.1. (4802275, stddoclet, 1 vote)
  • Tag {@value}: Using {@value} in a custom tag no longer generates a NullPointerException. (4821796, stddoclet, 1 vote)
  • Browser scroll bar: Internet Explorer no longer displays an unnecessary horizontal scroll bar when frames are showing. (4852280, stddoclet, 5 votes)
  • Inheriting package-private docs: When -private option is used, now properly documents methods inherited from package-private classes only in the inherited method summary table and not in the detail section. (4780441, stddoclet, 5 votes)
  • First sentence ending with {@inheritDoc}: The end of a first sentence containing {@inheritDoc} is now determined correctly. (4767038, stddoclet, 4 votes)
  • First sentence broken link with {@docRoot}: A first sentence containing a {@docRoot} link is no longer broken in the single-page index. (4760191, stddoclet, 3 votes)
  • Inherited comment link: An inherited comment now links directly to the proper member, not just to the class. (4368820, stddoclet, 1 vote)
  • Alphabetic index sorting: Index sorting is again case-independent. Only in 1.4.1 and 1.4.2 it was sorted uppercase then lowercase. (4984419, stddoclet, no votes)

    All bug fixes are listed below.

Known Bugs

Javadoc 5.0 has no known bugs that cause it to hang or crash. You can view listings from our database at Bug Parade as described at: Javadoc FAQ. The notable bugs are:
  • Six-fold performance degradation since 1.4.2 for deeply inherited classes. The slowdown is partly due to the extra processing required by generic type parameters.
    Workaround: None. (5081166)
  • @param in base class is ignored if {@inheritDoc} in main description.
    Workaround: None. (4778311)
  • Produces faulty Constant Values page if a constant contain angle bracket '<'
    Workaround: None. (5077317)
  • Malformed HTML tag throws error due to message not found in resource file.
    Error message: java.util.MissingResourceException: Can't find resource for bundle com.sun.tools.doclets.formats.html.resources.standard, key doclet.malformed_html_link_tag
    Workaround: Reduce the number of packages and classes passed into javadoc until the error goes away and you locate the source file that contains the malformed tag. Then fix the malformed tag. A malformed HTML tag is one that begins properly but is otherwise improper. For example <action> is interpreted as a malformed <a> tag. (5082928)

Incompatibilities with Custom Doclets

Custom doclets written prior to 5.0 will have compatibility problems when run on source files that use new language features in 5.0.
  • New Language Features: The Doclet API and standard doclet were revised to handle the new 5.0 language features -- generics, enums, varargs and annotations. To handle these features, custom doclets would also need to be revised.

    The Javadoc tool tries -- to the extent possible -- to present so-called "legacy" doclets with a view of the program that 1) continues to work with pre-5.0 source code, and 2) matches their expectations for 5.0 source code. So, for example, type parameters and type arguments are stripped from generic constructs, type variables and wildcard types are replaced by their erasures, and ClassDoc.fields() will return enum constants.

    But legacy support is not specified with precision. It's a compatibility mode that will suffice until the doclet gets updated to understand the language it is operating on. The only guarantee is source and binary compatibility of doclets themselves: when using the 5.0 Javadoc tool, if your doclet is based on 1.4 and the source code on which you're operating is also based on 1.4, then you can still compile the doclet and it will still operate as before (modulo bug fixes).

New Features and Bug Fixes

The following is a list of essentially all new features and bug fixes in 5.0. Only very minor changes are omitted (such as fixing broken links in the documentation for the Doclet API) and bugs introduced in early-access releases of 5.0 but fixed in the final release are omitted.

Command Line Options

  • New feature: New -keywords option adds HTML meta tags to each generated file to help with search (4776637, stddoclet)
  • New feature: New -notimestamp option suppresses hidden timestamp embedded near the top of HTML pages (4777717
  • New feature: It is now possible to create test subpackages that contain hyphens that the -subpackages option will skip over without producing warnings. That is, this option will no longer warn if it encounters a directory with an illegal Java name (which is consistent with illegal source filenames). (4773013, tool)
  • Bug fix: The -help option no longer mistakenly shows "[classnames]" in the usage. (4775743, tool)
  • Bug fix: The -group option no longer causes a duplicate warning. (4924383, stddoclet)
Tags and Taglets
  • New feature: The {@literal} tag denotes literal text. The enclosed text is interpreted as not containing HTML markup or nested javadoc tags. For example, the doc comment text: {@literal a<B>c} displays in the generated HTML page unchanged: a<B>c -- that is, the <B> is not interpreted as bold.
  • New feature: The {@code} tag formats literal text in the code font. It is equivalent to <code>{@literal}</code>.
  • New feature: The {@value} inline tag now accepts the name of a program element and label: {@value package.class#member label}. This enables it to be used in any doc comment. (4764045, stddoclet)
  • New feature: Not a Javadoc tag, the @Deprecated annotation is new in 5.0 and should be used in addition to the @deprecated tag for deprecating program elements. See @Deprecated annotation.
  • Bug fix: (regresion): Fixed @param so the parameter name (its first argument) is printed even if incorrect, as it worked in 1.3.1. (4802275, stddoclet)
  • Bug fix: (regression) Fixed -tag so its name can once again contain a dash "-", as was allowed in 1.4.1. (4920381, stddoclet)
  • Bug fix: A first sentence containing a {@docRoot} link is no longer broken in the single-page index. (4760191, stddoclet)
  • Bug fix: The end of a first sentence containing {@inheritDoc} is now determined correctly. (4767038, stddoclet, 4 votes)
  • Bug fix: Use of the {@docroot} tag in -bottom text no longer causes a broken link on the help-doc.html page. (4851991, stddoclet)
  • Bug fix: Modified taglet code to allow standalone tags to handle inline tags. (4654308, stddoclet)
  • Bug fix: Use of {@value} in a custom tag no longer generates a NullPointerException. (4821796, stddoclet)
  • Bug fix: Inline tags now allow nested braces that do not belong to inline tags. (4965490, tool)
  • Bug fix: @param, @return and some @throws tags now inherit comments properly. (4915434, stddoclet)
  • Bug fix: @throws documentation is now auto-inherited if the exception is checked. (4947455, stddoclet)
Links
  • Bug fix: An inherited comment now links directly to the proper member, not just to the class. (4368820, stddoclet)
  • Bug fix: The summary heading is no longer missing when a class has no direct members but inherits members. (4904036, stddoclet)
  • Bug fix: Relative link in <a href> in first sentence no longer generates a broken link when it appears on other pages. (4460354, stddoclet)

    For more link bug fixes, see "Tags and Taglets", associated with the {@docRoot} tag.

Documented Source files
  • New feature: package-info.java is a reserved name for a source file to store package comments and annotations. package-info.java is described above.
Generated API Specifications
  • New feature: Added support for generics, enums, and varargs in the javadoc tool front-end (Doclet API) (4421066, tool) and standard doclet (4789689, stddoclet)
  • New feature: Added support for annotations and annotation types in the javadoc tool front-end (Doclet API) (4904495, tool) and standard doclet (4905985, stddoclet)
  • New feature: For legibility, constant field values of type long are now printed with "L" rather than lowercase "l". (4869993, tool)
  • New feature: For legibility, serialVersionUID values of type long are now printed with "L" rather than lowercase "l". (4821483, stddoclet)
  • New feature: Table of contents has been added to the top of the "Deprecated" list. (4927552, stddoclet)
  • Bug fix: No longer hangs when {@inheritDoc} (1) cannot inherit or (2) inherits from super-superinterface. (4812240, stddoclet)
  • Bug fix: Inherited non-public superclass is no longer mentioned (4874845, stddoclet)
  • Bug fix: "Specified by:" and "Overrides:" comments are now inherited from externally referenced classes. (4857717, stddoclet)
  • Bug fix: Documentation is no longer inherited from members of package-private classes. (4780441, stddoclet)
  • Bug fix: Order of method descriptions can no longer change from one run to the next. (4885372, stddoclet)
  • Bug fix: When class B extends class A which implements interface I, in the documentation for I, we now document that B implements I (under "All implementing classes"). (4947464, stddoclet)
  • Bug fix: Correct return type now shows up in member summary when a method inherits documentation from an overridden method that returns a different type. (4951228, stddoclet)
  • Bug fix: Now generates doc for readObjectNoData() in serialized form page. (4770063, stddoclet)
  • Bug fix: Now generates a package summary page for the unnamed package, if present. (4774450, stddoclet)
  • Bug fix: Now prints "Unnamed" as the name of the unnamed package, rather than printing empty string. (4904075, stddoclet)
  • Bug fix: All inherited methods from multiple extended interfaces are now documented. (4933335, stddoclet)
  • Bug fix: Interface methods are no longer marked "public" (just a change -- not actually a bug). (4682448, stddoclet)
  • Bug fix: Constructor comments are now indented properly. (4904037, stddoclet)
  • Bug fix: packages.html (note the plural) file is no longer included, as it has not been used or needed since 1.1. (4475679, stddoclet)
  • Bug fix: When a type parameter in the member summary is greater than 10 characters, now add a line break to shorten it (4927167, stddoclet)
Formatting and Invalid HTML
  • Bug fix: Now outputs <NOSCRIPT> tag with each <SCRIPT> tag. (4855054, stddoclet)
  • Bug fix: Internet Explorer no longer displays an unnecessary horizontal scroll bar when frames are showing. (4852280, stddoclet)
  • Bug fix: Newlines are no longer hard-coded as "\n". (4938109, stddoclet)
  • Bug fix: Table border added around class headings in constant value summary. (4904025, stddoclet)
  • Bug fix: Now prints certain HTML source comments conditionally (4904038, stddoclet)
Navigation Bar
  • Bug fix: An extra column no longer appears in the first row of the navbar. (4664607, stddoclet, 1 vote)
  • Bug fix: Package link is now active when documenting only one package. (4689286, stddoclet)
  • Bug fix: Next/Prev Class links now iterate through all interfaces and classes in current package. (4131628, stddoclet)

Accessibility

  • Bug fix: Table headings now use rather than . (4905786, stddoclet)
  • Bug fix: Missing space added at end of alternate text for inherit.gif. (4956908, stddoclet)
Running Javadoc
  • Bug fix: No longer get InvocationTargetException when a source flie links to another source file in the wrong directory. (4835749, stddoclet)
  • Bug fix: (regression) No longer fails on internal classes, as it worked in 1.4.1. (4843578, tool)

Error/Warning/Notice Messages

  • New feature: Now warns when @return tag is present in void method. (4490068, stddoclet)
  • New feature: Now displays message when creating new destination directory (4657239, stddoclet)
  • Bug fix: BreakIterator warnings no longer appear. For more information, see above. (4959985, tool)
  • Bug fix: The "first sentence" warning is no longer split between stderr and stdout. (4753853, tool)
  • Bug fix: DocLocale.java implementation has been modified to allow for proper translation. (4780921, tool)
  • Bug fix: Now uses DocletErrorReporter to print option errors, rather than MessageRetriever. (4927928, stddoclet)
  • Bug fix: Message no longer says "error" when it's really a warning for a missing package-list file. (4625883, stddoclet)
Doclet API
  • New feature: Added support for generics, enums, and varargs in the javadoc tool front-end (Doclet API) (4421066, tool) and standard doclet (4789689, stddoclet)
  • New feature: Added support for annotations and annotation types in the javadoc tool front-end (Doclet API) (4904495, tool) and standard doclet (4905985, stddoclet)
  • New feature: Add Doclet.languageVersion method to determine which version of Java source code the doclet was written for. (4909767, tool)

Standard Doclet Implementation

  • Bug fix: Re-implemented standard doclet to maximize shared code for doclets emulating the stddoclet (4638723, stddoclet)

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


Deprecation of APIs

 Documentation Contents

A deprecated API is one that you are no longer recommended to use, due to changes in the API. While deprecated classes, methods, and fields are still implemented, they may be removed in future implementations, so you should not use them in new code, and if possible rewrite old code not to use them.

Guide

How and When to Deprecate APIs

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Sun

Java Software


How and When To Deprecate APIs

 Deprecation
Home Page
  • What "Deprecated" Means
  • When to Deprecate
  • How to Deprecate
    • Using the @Deprecated Annotation
    • Using the @deprecated Javadoc Tag

What "Deprecated" Means

You may have heard the term, "self-deprecating humor," or humor that minimizes the speaker's importance. A deprecated class or method is like that. It is no longer important. It is so unimportant, in fact, that you should no longer use it, since it has been superseded and may cease to exist in the future.

Java provides a way to express deprecation because, as a class evolves, its API (application programming interface) inevitably changes: methods are renamed for consistency, new and better methods are added, and fields change. But such changes introduce a problem. You need to keep the old API around until developers make the transition to the new one, but you don't want them to continue programming to the old API.

The ability to deprecate a class, method, or member field solves the problem. Java supports two mechanisms for deprecation: and an annotation, (supported starting with J2SE 5.0) and a Javadoc tag (supported since 1.1). Existing calls to the old API continue to work, but the annotation causes the compiler to issue a warning when it finds references to deprecated program elements. The Javadoc tag and associated comments warn users against using the deprecated item and tell them what to use instead.

When to Deprecate

When you design an API, carefully consider whether it supersedes an old API. If it does, and you wish to encourage developers (users of the API) to migrate to the new API, then deprecate the old API. Valid reasons to deprecate an API include:

  • It is insecure, buggy, or highly inefficient
  • It is going away in a future release
  • It encourages bad coding practices

Deprecation is a reasonable choice in all these cases because it preserves "backward compatibility" while encouraging developers to change to the new API. Also, the deprecation comments help developers decide when to move to the new API, and so should briefly mention the technical reasons for deprecation.

It is not necessary to deprecate individual member fields (properties) of a deprecated class, unless of course you want to explain a specific point about a property.

How to Deprecate

Starting with J2SE 5.0, you deprecate a class, method, or field by using the @Deprecated annotation. Additionally, you can use the @deprecated Javadoc tag tell developers what to use instead.

Using the annotation causes the Java compiler to generate warnings when the deprecated class, method, or field is used. The compiler suppresses deprecation warnings if a deprecated item is used within an entity which itself is deprecated or is used within the same outermost class or is used in an entity that is annotated to suppress the warning.

You are strongly recommended to use the Javadoc @deprecated tag with appropriate comments explaining how to use the new API. This ensures developers will have a workable migration path from the old API to the new API. For more information, see Using the @deprecated Javadoc Tag.

NOTE: The Java Language Specification requires compilers to issue warnings when classes, methods, or fields marked with the @Deprecated annotation are used. Compilers are not required by the Java Language Specification to issue warnings when classes, methods, or fields marked with the @deprecated Javadoc tag are accessed, although the Sun compilers currently do so. However, there is no guarantee that the Sun compiler will always issue such warnings.

Using the @Deprecated Annotation

J2SE 5.0 introduces a new language feature called annotations (also called metadata). One of the Java language's built-in annotations is the @Deprecated annotation. To use it, you simply precede the class, method, or member declaration with "@Deprecated."

Using the @Deprecated annotation to deprecate a class, method, or field ensures that all compilers will issue warnings when code uses that program element. In contrast, there is no guarantee that all compilers will always issue warnings based on the @deprecated Javadoc tag, though the Sun compilers currently do so. Other compilers may not issue such warnings. Thus, using the @Deprecated annotation to generate warnings is more portable that relying on the @deprecated Javadoc tag.

In addition, the @Deprecated annotation causes the javadoc-generated documentation to be marked "Deprecated" wherever that program element appears.

NOTE: Deprecation applies to classes and to individual methods or properties, not to their names. It is possible for a single method to have deprecated and non-deprecated overloadings. It is possible for a non-deprecated property to hide or override a deprecated one, which removes deprecation. As developer of an API, it is your responsibility to deprecate overrides of a deprecated method, if in fact they should be deprecated.

Example

The following is a simple example of using the @Deprecated annotation from java.lang.Thread:

public
class Thread implements Runnable {
...
@Deprecated
    public final void stop() {
  synchronized (this) {
...

Using the @deprecated Javadoc Tag

You can use the @deprecated tag to make Javadoc show a program element as deprecated. The @deprecated tag must be followed by a space or newline. In the paragraph following the @deprecated tag, explain why the item has been deprecated and suggest what to use instead.

Javadoc generates special HTML based on @deprecated tags: it moves the paragraph following the @deprecated tag to the front of the description, placing it in italics and preceding it with a warning, "Note: foo is deprecated", in bold. It also adds "Deprecated" in bold to any index entries mentioning the deprecated entity.

The tagged paragraph can be empty, but empty deprecation paragraphs are bad form, because they do not help the user fix the warnings that arise from the deprecation. Include paragraphs marked with @link or @see tags that refer to the new versions of the same functionality. It is usually not a good idea to mention a timetable for phase-out of the deprecated API; this is a business decision that is best communicated other ways.

For more information on using the @deprecated Javadoc tag, see Javadoc - The Java API Documentation Generator and How to Write Doc Comments for the Javadoc Tool.

Example

The following examples show how to use the @deprecated Javadoc tag. They also illustrate the @Deprecated annotation, to emphasize that the two should be used together.

Here is an example of the most common form of a deprecated method (for Javadoc 1.2 and later):

/**
 * @deprecated  As of release 1.3, replaced by {@link #getPreferredSize()}
 */
@Deprecated public Dimension preferredSize() {
return getPreferredSize();
}

If the API reorganization was more than renaming, the deprecation may be more complex. Here is an example of a method that is being retracted:

/**
 * Delete multiple items from the list.
 *
 * @deprecated  Not for public use.
 *    This method is expected to be retained only as a package
 *    private method.  Replaced by
 *    {@link #remove(int)} and {@link #removeAll()}
 */
@Deprecated public synchronized void delItems(int start, int end) {
...
}


The @deprecated Tag

"@deprecated": Mechanical Help for Abandoning Old APIs

John R. Rose
Oct 4, 1996

Problem:

Java 1.1 introduces many new APIs, some of which supersede older ones. The new and old APIs co-exist in the same packages. The superseded ones add various difficulties to the programmer's job, the chief being the need to ignore and avoid them in most cases.

Partial Solution: If we mark superseded classes, methods, and fields clearly and unambiguously as "deprecated", the programmers will know where to concentrate their attention. Also, the compiler will be able to help with this process, by bringing unintentional uses of deprecated APIs to the programmer's attention.

Details:

Within documentation comments, we define the new paragraph tag "@deprecated". (See JLS, $$184.) It can appear in both class and member documentation comments, and will apply specifically the construct its comment introduces.

The tagged paragraph can be empty. If it is not, it should tell the programmer how to avoid using the deprecated feature.

There should be "@see" tagged paragraphs which refer to the new versions of the same functionality.

As far as the compiler is concerned, the presence of the string "@deprecated" at the beginning of a documentation comment line (except for whitespace) causes it to place a "Deprecated" attribute in the output classfile for the corresponding class, field, or method.

Moreover, in parallel with the access checking logic for classes and members, the compiler looks for "Deprecated" attributes of classes and members being accessed, and issues warnings when the deprecated classes or members are used.

Note that deprecation applies to classes and to individual members, not to their names. It is possible for a single method to have deprecated and non-deprecated overloadings. It is possible for a non-deprecated member to hide or override a deprecated one, which removes deprecation. It is the responsibility of the programmer to deprecate overrides of a deprecated method, if in fact they should be deprecated.

A deprecation warning is suppressed if the compilation unit containing the deprecation is being compiled at the same time as the compilation unit using the deprecated class or member. This allows legacy APIs to be built without warnings. There currently is no other way to suppress the deprecation warnings.

A hypothetical "-strict" option to the compiler could promote all warnings, including deprecation warnings, to hard errors. This is not in 1.1.

Javadoc should somehow highlight deprecation paragraphs, and perhaps should place a characteristic glyph next to references to deprecated names.

Practice:

Here is an example of the most common form of a deprecated method:

    /**
     * @deprecated
     * @see #getPreferredSize
     */
    public Dimension preferredSize() {
    return getPreferredSize();
    }
(Notes: The "@deprecated" tag must be followed by a space or newline. The "@see" tag must be at the beginning of the line. See the JLS, chapter 18.)

If the deprecation is a simple renaming, there is no need to say something like "this method is replaced by getPreferredSize"; the "@see"-tagged paragraph points the user to the replacement.

The deprecation may be more complex if the API was reorganized by other than a renaming of features. Here is an example of a method that is being retracted:

    /**
     * Delete multiple items from the list.
     *
     * @deprecated  Not for public use in the future.
     * This method is expected to be retained only as a package
     * private method.
     * @see #remove(int)
     * @see #removeAll()
     */
    public synchronized void delItems(int start, int end) {
    ...
    }
Designers of new 1.1 APIs should carefully consider whether they are superseding old APIs. For each such API, if they wish to encourage users of the old previous API to migrate to the new API, they should add a deprecation paragraph to the documentation comment. Empty deprecation paragraphs are bad form, because they do not help the user fix the warnings that arise from the deprecation.

Valid reasons for wishing one's users to migrate to the new API include:

  • the old API is insecure, buggy, or highly inefficient
  • the old API is going away in a future release
  • the old API encourages very bad coding practices

Not all of these reasons are of equal weight, yet deprecation is a reasonable (though not mandatory) choice in all these cases. Therefore, the use of deprecated APIs can never be made a hard error by default. Also, the deprecation comments need to help the user decide when to move to the new API, and so should briefly mention the technical reasons for deprecation.

(It is probably not good to specifically mention a timetable for phase-out of the deprecated API; this is a business decision that needs to be communicated other ways.)

It is not necessary to deprecate individual members of a deprecated class, unless of course the programmer wants to explain some specific point about one member.

When a feature is deprecated, it is a good idea to notify the engineering organization of this fact, so that other engineers can respond to the change (pro or con) in a timely manner.

Other Design Options:

This is the first time the compiler is in any way cognizant of document comment contents. (Once, it made sure that they were at the right place in the parse tree, but this is no longer true.) We did not lightly choose to make the compiler's behavior dependent on the contents of a comment.

One precedent for looking into comments is "lint", which uses comments like /*PRINTFLIKE2*/ to annotate C APIs.

Note that Java documentation comments are structured, and the structure is specified in the Java Language Specification. This means that we "own" the format of this particular sort of comment, so our design is somewhat more reasonable than the less-differentiated conventions used by lint.

We considered introducing pragmas, and using them for deprecation (e.g., <*deprecated*>) but this would open the door very wide to many sorts of incompatible extensions and, possibly, to serious abuses.

However, @deprecated does work like a pragma: It belongs in the source, expresses information about it, but does not modify its semantics. Unlike many pragmas, @deprecated is intended for a human audience.

The compiler emits warnings as a friendly and helpful reminder, but does not enforce any rules. It's up to the programmer to use the contents of the deprecation paragraph. Since the human is the primary user of the data, it belongs in comments.

We considered introducing a new keyword, something like "transient". This would solve the mechanical problem, but at the cost of modifying the language itself. In particular, we would have to take away an identifier from coders that we had not previously reserved (like "var"). Moreover, since the primary audience of deprecations is humans, a keyword-based approach is insufficient, and must be augmented by comment conventions, preferably ones which integrate with javadoc. Thus, the keyword approach does not pay.

Still, the compiler has heretofore ignored and should generally ignore documentation comments. This is an admittedly irregular exception to that practice. But the other design options for deprecation involve worse sorts of irregularity.

Sun logo Copyright © 1996 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA 94043-1100 USA. All rights reserved.


Doclet Overview

Contents

  • The Basics
  • A Simple Example Doclet
  • Example - Subclassing the standard doclet
  • Example - Creating and handling custom tags
  • Example - Using custom command-line options

The Basics

Doclets are programs written in the JavaTM programming language that use the doclet API to specify the content and format of the output of the Javadoc tool. By default, the Javadoc tool uses the "standard" doclet provided by SunTM to generate API documentation in HTML form. However, you can supply your own doclets to customize the output of Javadoc as you like. You can write the doclets from scratch using the doclet API, or you can start with the standard doclet and modify it to suit your needs.

Here are the basic steps you need to follow to create and use your own doclet:

  1. Write the Java program that constitutes your doclet. Your program should import com.sun.javadoc.* in order to use the doclet API. The entry point of your program is a class with a public static boolean start method that takes a RootDoc as a parameter.
  2. Compile your doclet. You can use the compiler in the Java 2 SDK, javac.
  3. Run the javadoc tool using the -doclet startingclass option to produce the output specified by your doclet, where startingclass is the fully-qualified name of the starting class mentioned in step 1 above.
The doclet API class files are in the lib/tools.jar file in the SDK. When you compile a doclet, the tools.jar must be on the class path. You can use the -classpath option on javac for this purpose.

If you run javadoc without the -doclet command-line option, it will default to the standard doclet to produce HTML-format API documentation.

Package com.sun.javadoc consists of interfaces that define the doclet API. The lib/tools.jar file in the Java 2 SDK contains these interfaces and also a private package with classes that implement the interfaces. The tools.jar file also contains the classes implementing the standard doclet.

A Simple Example Doclet

You can get a feeling for the way doclets work by looking at this simple example doclet that consists of one short class:
import com.sun.javadoc.*;

public class ListClass {
    public static boolean start(RootDoc root) {
        ClassDoc[] classes = root.classes();
        for (int i = 0; i < classes.length; ++i) {
            System.out.println(classes[i]);
        }
        return true;
    }
}
As you might be able to guess by looking at the code, this doclet takes the classes upon which Javadoc is operating and prints their names to standard out.

This first thing to notice about the doclet is that it imports the com.sun.javadoc package in order to use the doclet APIs. As with all doclets, the entry point is the public static boolean start method. The start method takes a RootDoc as a parameter. This parameter carries information about any options specified on the command line when javadoc is run, and also about the classes and packages upon which javadoc is operating.

RootDoc defines a classes method that returns a ClassDoc array whose elements represent the classes that Javadoc parses. The for loop then prints out the names of each class in the array. (Passing a ClassDoc to println results in the printing of the name of the class that the ClassDoc represents.)

To run this doclet, you first have to compile it. You can compile it with the javac compiler. The doclet API classfiles are in the file lib/tools.jar in the Java 2 SDK which javac does not automatically load. You therefore need to include tools.jar on the compiler's classpath, as in this example:

javac -classpath C:\jdk1.3\lib\tools.jar ListClass.java
To run the ListClass doclet, you point to the compiled doclet with Javadoc's -doclet and -docletpath tags. For example, to run the doclet on a file called MyClass.java, you could use this command, assuming ListClass.class is in the current directory:
% javadoc -doclet ListClass -docletpath .  MyClass.java
The output will be the string "MyClass". Note that this command does not require tools.jar to be on the class path, as the Javdoc tool automatically loads it.

A note about command-line options: If you run javadoc -help, you'll see that the Javadoc tool has two sets of command-line options. One set is generic and will work with any doclet. The second set of options is special to the standard doclet. Options in this second set will not be available when using custom doclets. Your custom doclets can also define their own command-line options. See the example below.

To generate API documentation, a doclet will have to be considerably more complex than this simple example. If you want to customize the format of the API documentation generated by Javadoc, you may want to start with the default standard doclet and modify it as necessary rather than write your own doclet from scratch.

Example - Subclassing the Standard Doclet

To customize the output of the Javadoc tool, you need to write your own doclet that specifies the content and format of the output that you desire. If you want HTML output with roughly the same format as the default output, you can use the standard doclet as a starting point for creating your doclet. You can subclass appropriate classes in the standard doclet and then add or override methods as necessary to produce the output you want. Or you can copy the whole standard doclet and modify it. If you use a copy of the standard doclet as your starting point, you may want to remove the package statements at the beginning of each source file and replace them with the name of your own, new package.

For an example, see How can I modify the standard doclet to produce links to source code from the API documentation?

Example - Creating and handling custom tags

Suppose, for example, that you want use a custom tag, say @mytag, in your documentation comments in addition to the standard tags like @param and @return. To make use of the information in your custom tags, you need to have your doclet use instances of Tag that represent your custom tags. One of the easiest ways to do that is to use the tags(String) method of Doc or one of Doc's subclasses. This method returns an array of Tag objects representing any tags whose name matches the string argument. For example, if method is an instance of MethodDoc, then
method.tags("mytag")
would return an array of Tag objects representing any @mytag tags in the method's documentation comment. You can then access the information in your @mytag tags with Tag's text method. That method returns a string representing the content of the tag which you can parse or use as needed. For example, if a documentation comment contained one of your custom tags like this:
@mytag Some dummy text.
then the text method would return the string "Some dummy text.".

Here's a standalone doclet (not a subclass of the standard doclet) that uses these ideas to print out the text associated with all instances of a specified tag that it finds in method comments. It could be extended to find all instances of that tag in all comments.

import com.sun.javadoc.*;

public class ListTags {
    public static boolean start(RootDoc root){
        String tagName = "mytag";
        writeContents(root.classes(), tagName);
        return true;
    }

    private static void writeContents(ClassDoc[] classes, String tagName) {
        for (int i=0; i < classes.length; i++) {
            boolean classNamePrinted = false;
            MethodDoc[] methods = classes[i].methods();
            for (int j=0; j < methods.length; j++) {
                Tag[] tags = methods[j].tags(tagName);
                if (tags.length > 0) {
                    if (!classNamePrinted) {
                        System.out.println("\n" + classes[i].name() + "\n");
                        classNamePrinted = true;
                    }
                    System.out.println(methods[j].name());
                    for (int k=0; k < tags.length; k++) {
                        System.out.println("   " + tags[k].name() + ": "
                            + tags[k].text());
                    }
                }
            }
        }
    }
}
The tag for which this doclet searches is specified by the variable tagName. The value of the tagName string can be any tag name, custom or standard. This doclet writes to standard out, but its output format could be modified, for example, to write HTML output to a file.

Example - Using custom command-line options

 You can write doclets that accept custom command-line options. To see how that works, let's augment the example doclet above so that it allows you to use a command-line option to specify the tag name to search for.

Any doclet that uses custom options must have a method called optionLength(String option) that returns an int. For each custom option that you want your doclet to recognize, optionLength must return the number of separate pieces or tokens in the option. For our example, we want to be able to use the custom option of the form -tag mytag. This option has two pieces, the -tag option itself and its value, so the optionLength method in our doclet must return 2 for the -tag option. The optionsLength method should return 0 for unrecognized options.

Here's the full, augmented doclet:

import com.sun.javadoc.*;

public class ListTags {
    public static boolean start(RootDoc root){
        String tagName = readOptions(root.options());
        writeContents(root.classes(), tagName);
        return true;
    }

    private static void writeContents(ClassDoc[] classes, String tagName) {
        for (int i=0; i < classes.length; i++) {
            boolean classNamePrinted = false;
            MethodDoc[] methods = classes[i].methods();
            for (int j=0; j < methods.length; j++) {
            Tag[] tags = methods[j].tags(tagName);
            if (tags.length > 0) {
                if (!classNamePrinted) {
                    System.out.println("\n" + classes[i].name() + "\n");
                    classNamePrinted = true;
                }
                System.out.println(methods[j].name());
                for (int k=0; k < tags.length; k++) {
                    System.out.println("   " + tags[k].name() + ": " + tags[k].text());
                }
            }
        }
        }
    }

    private static String readOptions(String[][] options) {
        String tagName = null;
        for (int i = 0; i < options.length; i++) {
            String[] opt = options[i];
        if (opt[0].equals("-tag")) {
            tagName = opt[1];
        }
        }
    return tagName;
    }

    public static int optionLength(String option) {
        if(option.equals("-tag")) {
        return 2;
        }
        return 0;
    }

    public static boolean validOptions(String options[][],
                       DocErrorReporter reporter) {
    boolean foundTagOption = false;
        for (int i = 0; i < options.length; i++) {
            String[] opt = options[i];
            if (opt[0].equals("-tag")) {
            if (foundTagOption) {
                reporter.printError("Only one -tag option allowed.");
            return false;
            } else {
            foundTagOption = true;
        }
        }
    }
    if (!foundTagOption) {
        reporter.printError("Usage: javadoc -tag mytag -doclet ListTags ...");
    }
    return foundTagOption;
    }
}
In this modified doclet, the variable tagName is set with the command-line option -tag. It has a optionLength method returns two for our custom option. Note that an explicit call to optionLength isn't required.

This doclet also adds the readOptions methods that actually parses the command-line options looking for the -tag option. It makes use of the fact that the Rootdoc.options method returns a two-dimensional String array containing option information. For example, given the command

javadoc -foo this that -bar other ...
the RootDoc.options method will return
options()[0][0] = "-foo"
options()[0][1] = "this"
options()[0][2] = "that"
options()[1][0] = "-bar"
options()[1][1] = "other"
The number of elements in the array's second index is determined by the optionLength method. In this example, optionLength returns 3 for option -foo and returns 2 for option -bar.

The validOptions method is an optional method that you can use to test the validity of the usage of command-line tags. If the validOptions method is present, it is automatically invoked; you don't have to explicitly call it. It should return true if the option usage is valid, and false otherwise. You can also print appropriate error messages from validOptions when improper usages of command-line options are found. The validOptions method in this example doclet checks that the -tag option is used once and only once.

Copyright © 1995-98 Sun Microsystems, Inc. All Rights Reserved.

Sun


Transitioning to 1.5 Doclet API

Introduction Notes

It is assumed that the doclet developer has read the documentation on new 1.5 language features and is aware of the doclet changes required to support the new features. This document only assists the developer in making those changes. It does not define all the new language features in 1.5.

Indicate That Your Doclet Supports 1.5 Source

Class com.sun.javadoc.Doclet has a new method that allows doclets to indicate which version of Java Programming Language is supported:

Doclet.languageVersion()

By default, this method returns LanguageVersion.JAVA_1_1. You should override this method and return LanguageVersion.JAVA_1_5.

Ensure That Your Doclet Handles Primitives Properly

Given a Type, most doclets distinguish between classes and primitives by using the following check:
   // If true, Type must be a primitive
   Type.asClassDoc() == null
In 1.5, this no longer works because there are other non-classdoc types besides primitives. For example, the asClassDoc method would return null for annotation types as well. You should find all occurances of ?Type.asClassDoc() == null? and replace it with Type.isPrimitive().

Use ClassDoc.superclassType() Instead of ClassDoc.superclass()

ClassDoc.superclass() cannot accommodate certain generic type constructs. The superclassType() method should be used instead.

Use ClassDoc.interfaceTypes() Instead of ClassDoc.interfaces()

ClassDoc.interfaces() cannot accommodate certain generic type constructs. The interfaceTypes() method should be used instead.

Type Parameters

When processing ClassDocs and ExecutableMemberDocs, call method typeParameters() to retrieve the formal type parameters. Each parameter can be processed in a similar way that regular types are processes. The only difference is that type parameters have bounds that need to be documented. The bounds are retrieved by calling TypeVariable.bounds().

Here is the interface that represents a type variable:

com.sun.javadoc.TypeVariable

Here is the algorithm that the standard doclet uses to process type parameters:

if (type.asTypeVariable()!= null) {
    Doc owner = type.asTypeVariable().owner();
    if (owner instanceof ClassDoc) {
        // Generate Link to type Parameter
    } else {
        // No need to link method type parameters.
        // Append the name of the type parameter
    }

    Type[] bounds = type.asTypeVariable().bounds();
    if (! linkInfo.excludeTypeBounds) {
        for (int i = 0; i < bounds.length; i++) {
            // If i greater than 0, append " & ".  Otherwise, append " extends "
            // Generate a link to the bound
        }
    }
}

Param Tags For Type Parameters

A doclet retrieves @param tags from constructors and methods by calling ExecutableMemberDoc.paramTags(). Since classes, constructors and methods can have type parameters, the @param tag may be used to document these type parameters. They are distinguished by having angle brackets around the names. For example:
/**
 * @param <E> the type parameter for this class.
 */
public class Foo<E>
To retrieve these type parameter @param tags, call ClassDoc. typeParamTags() or ExecutableMemberDoc.typeParamTags().

Type parameter tags can be distinguished from regular parameter tags by calling ParamTag.isTypeParameter().

Annotation Types

An annotation type is distinguished from classes and interfaces by calling the isAnnotationType() method. Here is the interface that represents an annotation type:

com.sun.javadoc.AnnotationTypeDoc

Retrieve the annotation type elements by calling method elements(). There are two types of elements:

  • An optional element. If the user does not specify a value for this element, it is set to a specified default value.
  • A required element. The user must specify a value for this element when using the annotation.
There is no way to retrieve an exactly list of optional and required elements from the doclet API. The doclet must manually interate through the array of elements and check the default value is null. If it is null, the element is required.

Annotation Type Usage

When processing a ProgramElementDoc, the annotation() method should be called to retrieve the annotations used. Here is the interface that encapsulates annoation usage information:

com.sun.javadoc.AnnotationDesc

Iterate through the list of AnnotationDesc objects and process each one. Here is the algorithm that the standard doclet uses to process AnnotationDesc objects:

for (int i = 0; i < descList.length; i++) {
    AnnotationTypeDoc annotationDoc = descList[i].annotationType();
    if (/**annotationDoc does not have @documented annotation**/){
        // ONLY document annotations if they have @documented.
        continue;
    }
    // Generate a link to the annotation.  Start with the ?@? character>
    AnnotationDesc.ElementValuePair[] pairs =
        descList[i].elementValues();
    if (pairs.length > 0) {
        // Append '(' to indicate start of element list>
        for (int j = 0; j < pairs.length; j++) {
              if (j > 0) {
                // Append ',' to separate previous element from the next>
            }
            // Generate a link to the annotation element>
            // Append '=' to separate element name from value>
            AnnotationValue annotationValue = pairs[j].value();
            List annotationTypeValues = new ArrayList();
            if (annotationValue.value() instanceof
                     AnnotationValue[]) {
                 AnnotationValue[] annotationArray =
                 (AnnotationValue[]) annotationValue.value();
                 for (int k = 0; k < annotationArray.length; k++) {
                    annotationTypeValues.add(annotationArray[k]);
                 }
           } else {
               annotationTypeValues.add(annotationValue);
           }
           // Append '{' if this is an array of values
           for (Iterator iter =
               annotationTypeValues.iterator();
               iter.hasNext(); ) {
               // Append string representation of value
               // Append ?,? if there there is more to append
           }
           // Append '}' if this is an array of values
       }
       // Append ')' if this is an array of values
    }
}
Here is a sample of this output:

java.lang.annotation.Target

An annotation value can be any of the following:

  • Type
  • Array Type
  • Primitive
  • Nested Annotation
  • MemberDoc
  • String
Here is the algorithm that the standard doclet uses to convert an annotation to a string:
if (annotationValue.value() instanceof Type) {
    Type type = (Type) annotationValue.value();
    if (type.asClassDoc() != null) {
        LinkInfoImpl linkInfo = new LinkInfoImpl(
           LinkInfoImpl.CONTEXT_ANNOTATION, type);
        linkInfo.label = (type.asClassDoc().isIncluded() ?
            type.typeName() :
            type.qualifiedTypeName()) + type.dimension() + ".class ";
        return getLink(linkInfo);
    } else {
        return type.typeName() + type.dimension() + ".class";
    }
} else if (annotationValue.value() instanceof AnnotationDesc) {
    // Handle nested annotations using recursion.
    List list = getAnnotations(
        new AnnotationDesc[]{(AnnotationDesc) annotationValue.value()},
            false);
    StringBuffer buf = new StringBuffer();
    for (Iterator iter = list.iterator(); iter.hasNext(); ) {
        buf.append(iter.next());
    }
    return buf.toString();
} else if (annotationValue.value() instanceof MemberDoc) {
    // Simply link to the member being references in the annotation.
    return getDocLink(LinkInfoImpl.CONTEXT_ANNOTATION,
        (MemberDoc) annotationValue.value(),
        ((MemberDoc) annotationValue.value()).name(), false);
} else {
    return annotationValue.toString();
}

Enums

An enum is distinguished from classes and interfaces by calling the isEnum() method. To retrieve the list of enum constants to be documented, call the enumConstants() method. The enum constants are returned as an array of FieldDoc objects. An enum constant can be distinguished from a regular field by calling isEnumConstant().

Here is a sample of Enum documentation:

java.lang.management.MemoryType.html

Varable Arguments

When processing an ExecutableMemberDoc, call isVarArg() to determine if the last constructor/method parameter is a var arg. If it is, the last parameter requires special handling. Here is the extra code that the standard doclet executes for var args:
if (isVarArg) {
    if (type.dimension().length() > 2) {
        // Doclet API returns var args as array.
        // Strip out the first [] from the var arg.
        // Append type.dimension().substring(2)
    }
    // Append "..."
} else {
    // Append type.dimension()
}
This code should be inserted in the place where you normally document array dimensions. Please note the comment that var args are returned as arrays by the doclet API. We strip out the first ?[]? because it is just a part of the internal representation of the var arg and should not appear in the documetation.

Wild Cards

Here is the interface that represents the wild card type:

com.sun.javadoc.WildcardType

When a wild card is encountered, iterate through the lists of extends and super bounds. Process each bound the same way you would process a regular type. Here is the algorithm the standard doclet uses to process wild cards:

if (type.asWildcardType() != null) {
    WildcardType wildcardType = type.asWildcardType();
    Type[] extendsBounds = wildcardType.extendsBounds();
    for (int i = 0; i < extendsBounds.length; i++) {
        // If i greater than 0, append " , ".  Otherwise, append " extends "
        // Generate link to extendsBounds[i])
    }
    Type[] superBounds = wildcardType.superBounds();
    for (int i = 0; i < superBounds.length; i++) {
        // If i greater than 0, append " , ".  Otherwise, append " super "
        // Generate link to superBounds[i])
    }
}


Taglet Overview

Contents

  • Taglet API
  • Writing a Taglet
  • Example - A Simple Block Taglet
  • Example - A Block Taglet That Handles Inline Tags
  • Example - An Inline Taglet
  • Handling Errors and Warnings

Taglet API

Taglets are programs written in the JavaTM programming language that implement the Taglet API. Taglets support both block tags, such as @todo, and inline tags, such as {@underline}. (See block and inline tags.) The Taglet API consists of one interface and two abstract classes:
  • Taglet API - ADD LINK TO OVERVIEW - ARE THERE ANY OTHER CLASSES WE SHOULD ADD?
    Taglet Interface
    Implement when writing a block taglet that does not need to support inline tags, or when writing a general inline tag
    BaseExecutableMemberTaglet class
    Extend when writing a block taglet that supports inline tags
    BaseInlineTaglet class
    Extends when writing an inline tag that needs access to the HtmlStandardWriter and/or the doc object
A taglet can modify and format the text argument of a custom tag, and it can redirect the text to a file or other stream. A taglet can override a standard tag.

Taglets are a the foundation beneath the -tag option. When you use the -tag option, it uses a built-in taglet to generate default HTML formatting that is similar to that generated for @return.

Writing a Taglet

Choose which type of taglet you want to write, and implement the appropriate interface or extend the appropriate abstract class:
  • Block taglets
    • that support inline tags - extend BaseExecutableMemberTaglet
    • that do not support inline tags - implement Taglet
  • Inline taglets
    • general inline tags - implement Taglet
    • that need access to the HtmlStandardWriter or Doc object - extend BaseInlineTag
The BaseExecutableMemberTaglet class extends Taglet to provide the additional functionality to support inline tags. It supports both standard inline tags, such as {@link} and {@docroot}, and custom inline tags you might write.

If you write an inline tag that needs access to the HtmlStandardWriter or the Doc object, it should extend BaseInlineTag. For example, the {@value} inline tag needs the Doc object to retrieve the constant value from the field. Most tags only need the HtmlStandardWriter to report errors using the doclet error reporting methods.

Here are the basic steps you need to follow to create and use your own taglet:

  1. Write the Java program that constitutes your taglet. Include import statements appropriate to the taglet you're writing. For example, if extending BaseExecutableMemberTaglet, your program should import the following:
    import com.sun.tools.doclets.Taglet;                                        // Taglet API
import com.sun.tools.doclets.standard.tags.BaseExecutableMemberTaglet;      // For inline tags
import com.sun.tools.doclets.standard.HtmlStandardWriter;                   // For error reporting???
import com.sun.javadoc.*;                                                   // Doclet API
import java.util.Map;                                                       // Used in register(Map)
    The Tag interface used in toString(Tag) is part of the Doclet API.

  2. In addition to the requirements of the interface you are implementing or abstract class you are extending, your program must implement the following static method. Then enables the taglet to be loaded at runtime. See the example below.
        public static void register(Map tagletMap)
    Your class must also implement the requirements of the interface it extends or class it implements. The toString method is where all of the custom work is implemented to modify, format or redirect the text argument passed in to to your custom tag.
        toString(Doc, HtmlStandardWriter)

  3. Compile your doclet. Use javac compiler version 1.4.0 (or later) in the Java 2 SDK. The required class files are in the lib\tools.jar file in the SDK. For the first example below, assuming the SDK is installed at C:\Program Files\j2sdk1.4.0.
       javac -classpath "C:\Program Files\j2sdk1.4.0\lib\tools.jar"  ToDoTaglet.java

  4. Run the javadoc tool using the -taglet and -tagletpath options. For example, if your taglet class file is defined to be in package com.sun and is stored in C:\taglets\com\sun\Taglet.class, then you should set tagletpath to C:\taglets. This example calls javadoc on package com.package1, including ToDoTaglet tags:
       javadoc -taglet ToDoTaglet -tagletpath C:\taglets com.package1

The following are examples of block and inline taglets.

YET TO UPDATE BELOW HERE !!!!!!!!!!!!!!

Example - A Simple Block Taglet

The source code for an example of a block taglet implementing @todo is included at:
  • ToDoTaglet.java
The corresponding class file ToDoTaglet.class is already compiled and saved in the same directory as this source file.

To run the doclet, include the -tagletpath and -taglet options. Assuming the ToDoTaglet.class is located in /home/user/taglet, and the @todo tag is located in the Test.java file:

% javadoc -d html -tagletpath /home/user/taglet -taglet ToDoTaglet ./Test.java
If the file Test.java contains the following doc comment:
    /**
     * @todo Fix this!
     */
then the ToDo taglet formats the HTML output as follows:
To Do:
Fix this!

Implementation Description

Let's look at the source code. To name the tag and define the header text, define two private fields:
    private static final String NAME = "todo";
    private static final String HEADER = "To Do:";
To make this a block tag rather than an inline tag, you set isInlineTag to return false:
    public boolean isInlineTag() {
        return false;
    }
There are other methods inField, inMethod, inType, inPackage and inOverview that you specify true or false to indicate in which doc comments in the source code this tag can be used.

The toString(Tag) method determines how the text is inserted into the output when a single {@todo} tag is encountered. This code creates a bold heading followed by a table with a yellow background that contains the text (specified by tag.text()).

    public String toString(Tag tag) {`
        return "<DT><B>" + HEADER + "</B><DD>"
               + "<table cellpadding=2 cellspacing=0><tr><td bgcolor=\"yellow\">"
               + tag.text()
               + "</td></tr></table></DD>\n";
    }
Similarly, the toString(Tag[]) method (which takes an array of tags) determines how the text is inserted into the output when multiple {@todo} tags are encountered.

Example - A Block Taglet That Handles Inline Tags

The source code for an example of a block taglet implementing @todo is included at:
  • ToDoTagletWithInline.java
The corresponding class file ToDoTaglet.class is already compiled and saved in the same directory as this source file.

To run the doclet, include the -tagletpath and -taglet options. Assuming the ToDoTaglet.class is located in /home/user/taglet, and the @todo tag is located in the Test.java file:

% javadoc -d html -tagletpath /home/user/taglet -taglet ToDoTaglet ./Test.java
If the file Test.java contains the following doc comment:
    /**
     * @todo Fix this!
     */
then the ToDo taglet formats the HTML output as follows:
To Do:
Fix this!

Implementation Description

Let's look at the source code. To name the tag and define the header text, define two private fields:
    private static final String NAME = "todo";
    private static final String HEADER = "To Do:";
To make this a block tag rather than an inline tag, you set isInlineTag to return false:
    public boolean isInlineTag() {
        return false;
    }
There are other methods inField, inMethod, inType, inPackage and inOverview that you specify true or false to indicate in which doc comments in the source code this tag can be used.

The toString(Tag) method determines how the text is inserted into the output when a single {@todo} tag is encountered. This code creates a bold heading followed by a table with a yellow background that contains the text (specified by tag.text()).

    public String toString(Tag tag) {`
        return "<DT><B>" + HEADER + "</B><DD>"
               + "<table cellpadding=2 cellspacing=0><tr><td bgcolor=\"yellow\">"
               + tag.text()
               + "</td></tr></table></DD>\n";
    }
Similarly, the toString(Tag[]) method (which takes an array of tags) determines how the text is inserted into the output when multiple {@todo} tags are encountered.

Example - An Inline Taglet

Unline block tags, a custom inline tag can only be implemented using a taglet (rather than using the -tag option). This is because there is no default behavior for inline tags.

The source code for an example of an inline taglet implementing {@underline} is included at:

  • UnderlineTaglet.java
The corresponding class file UnderlineTaglet.class is already compiled and saved in the same directory as this source file.

This taglet formats the output for the {@underline} tag. A doc comment containing the following tag:

    /**
     * Be sure to insert the value at the {@underline start} of the array.
     */
would be output in HTML as follows:
Be sure to insert the value at the start of the array.

Implementation Description

Let's look at how this source code differs from the previous example. Of course the tag name is different (and inline tags have no heading, so none is defined):
    private String NAME = "underline";
To define this as an inline tag rather than a block tag, you set isInlineTag to return true:
    public boolean isInlineTag() {
        return true;
    }

The methods inField, inMethod, inConstructor, inType, inPackage and inOverview apply only to block tags and must all be set to false for inline tags.

The toString(Tag) method determines how the text is inserted into the output when an {@underline} tag is encountered. This code creates surrounds the text with the HTML underline tags <ul> and </ul>.

    public String toString(Tag tag) {
        return "<u>" + tag.text() + "</u>";
    }
It is not possible to have an array of inline tags to process, like it is with block tags. Therefore, the toString(Tag[]) method (which takes an array of tags) is ignored for inline tags.

Handling Errors and Warnings

Errors - A taglet can report an error and stop the Javadoc tool by simply printing the error message and then calling System.exit().

Warnings - A taglet can report a warning using a MessageRetriever given to it by the Doclet instance. The MessageRetriever is obtained from the Configuration object. The Configuration object is obtained from the doclet. For example, if the Taglet is designed to be used with the Standard doclet, the Configuration can be retrieved using Standard.configuration(), a static method. As an example, this is how the SimpleTaglet prints warnings, which is the default taglet for the -tag option.

Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.

Sun


Taglet Overview

Contents

  • Taglet API
  • Writing a Taglet
  • Example - A Block Taglet
  • Example - An Inline Taglet
  • Handling Errors and Warnings

Taglet API

Taglets are programs written in the JavaTM programming language that implement the Taglet API. Taglets can be written as either block tags, such as @todo, or inline tags, such as {@underline}. Block taglets do not currently support inline tags in their text. (See block and inline tags.) The Taglet API consists of one interface:
  • Taglet interface
A taglet can modify and format the text argument of a custom tag, and do other things, such as redirect the text to a file or other stream. A taglet can override a standard tag.

Taglets are the foundation beneath the -tag option. When you use the -tag option, it uses a built-in taglet to generate default HTML formatting that is similar to that generated for @return.

Writing a Taglet

Here are the basic steps you need to follow to create and use your own taglet:

  1. Write the Java program that constitutes your taglet. Your program should import the following:
       import com.sun.tools.doclets.Taglet;    // Taglet API
   import com.sun.javadoc.*;               // Doclet API
   import java.util.Map;                   // Used in register(Map)
    The com.sun.javadoc classes must be imported for the Tag interface used in toString(Tag).

  2. Your class must implement the requirements of the interface it extends. The toString method is where all of the custom work is implemented to modify, format or redirect the text argument passed in to to your custom tag.
        public String toString(Tag tag)
  3. In addition to the requirements of the interface you are implementing, your program must implement the following static method. Then enables the taglet to be loaded at runtime. See the source code in the example below.
        public static void register(Map tagletMap)

  4. Compile your doclet. Use javac compiler version 1.4.0 (or later) in the JDK. The required class files are in the lib\tools.jar file in the JDK. For the first example below, assuming the JDK is installed at C:\Program Files\j2sdk1.4.1.
       javac -classpath "C:\Program Files\j2sdk1.4.1\lib\tools.jar"  ToDoTaglet.java

  5. Run the javadoc tool using the -taglet and -tagletpath options. For example, if your taglet class file is defined to be in package com.sun and is stored in C:\taglets\com\sun\Taglet.class, then you should set tagletpath to C:\taglets. This example calls javadoc on package com.package1, including ToDoTaglet tags:
       javadoc -taglet ToDoTaglet -tagletpath C:\taglets com.package1

The following examples are of block and inline taglets.

Example - A Block Taglet

The source code for an example of a block taglet implementing @todo is included at:
  • ToDoTaglet.java
The corresponding class file ToDoTaglet.class is already compiled and saved in the same directory as this source file.

This taglet formats the output for the @todo tag. A doc comment containing the following tag:

    /**
     * @todo Fix this!
     */
then the ToDo taglet formats the HTML output as follows:
To Do:
Fix this!

Implementation Description

Let's look at the source code. To name the tag and define the header text, define two private fields:
    private static final String NAME = "todo";
    private static final String HEADER = "To Do:";
To make this a block tag rather than an inline tag, you set isInlineTag to return false:
    public boolean isInlineTag() {
        return false;
    }
There are other methods inField, inMethod, inType, inPackage and inOverview that you specify true or false to indicate in which doc comments in the source code this tag can be used.

The toString(Tag) method determines how the text is inserted into the output when a single {@todo} tag is encountered. This code creates a bold heading followed by a table with a yellow background that contains the text (specified by tag.text()).

    public String toString(Tag tag) {`
        return "<DT><B>" + HEADER + "</B><DD>"
               + "<table cellpadding=2 cellspacing=0><tr><td bgcolor=\"yellow\">"
               + tag.text()
               + "</td></tr></table></DD>\n";
    }
Similarly, the toString(Tag[]) method (which takes an array of tags) determines how the text is inserted into the output when multiple {@todo} tags are encountered.

The register method

    /**
     * Register this Taglet.
     * @param tagletMap  the map to register this tag to.
     */
    public static void register(Map tagletMap) {
       ToDoTaglet tag = new ToDoTaglet();
       Taglet t = (Taglet) tagletMap.get(tag.getName());
       if (t != null) {
           tagletMap.remove(tag.getName());
       }
       tagletMap.put(tag.getName(), tag);
    }

Example - An Inline Taglet

Unlike block tags, a custom inline tag can only be implemented using a taglet (rather than using the -tag option). This is because there is no default behavior for inline tags.

The source code for an example of an inline taglet implementing {@underline} is included at:

  • UnderlineTaglet.java
The corresponding class file UnderlineTaglet.class is already compiled and saved in the same directory as this source file.

This taglet formats the output for the {@underline} tag. A doc comment containing the following tag:

    /**
     * Be sure to insert the value at the {@underline start} of the array.
     */
would be output in HTML as follows:
Be sure to insert the value at the start of the array.

Implementation Description

Let's look at how this source code differs from the previous example. Of course the tag name is different (and inline tags have no heading, so none is defined):
    private String NAME = "underline";
To define this as an inline tag rather than a block tag, you set isInlineTag to return true:
    public boolean isInlineTag() {
        return true;
    }

The methods inField, inMethod, inConstructor, inType, inPackage and inOverview apply only to block tags and must all be set to false for inline tags.

The toString(Tag) method determines how the text is inserted into the output when an {@underline} tag is encountered. This code creates surrounds the text with the HTML underline tags <ul> and </ul>.

    public String toString(Tag tag) {
        return "<u>" + tag.text() + "</u>";
    }
It is not possible to have an array of inline tags to process, like it is with block tags. Therefore, the toString(Tag[]) method (which takes an array of tags) is ignored for inline tags.

Handling Errors and Warnings

Errors - A taglet can report an error and stop the Javadoc tool by simply printing the error message and then calling System.exit().

Warnings - A taglet can report a warning using a MessageRetriever given to it by the Doclet instance. The MessageRetriever is obtained from the Configuration object. The Configuration object is obtained from the doclet. For example, if the Taglet is designed to be used with the Standard doclet, the Configuration can be retrieved using Standard.configuration(), a static method. As an example, this is how the SimpleTaglet prints warnings, which is the default taglet for the -tag option.

Copyright © 2001-2002 Sun Microsystems, Inc. All Rights Reserved.

Sun


enhancements

Java Web Start enhancements in version 6

  • JNLP Specification addition of the <update> element with it's "policy" and "check" attributes.
The new <update> element with it's "policy" and "check" attributes is now supported. The update element describes the applications preferences for how Java Web Start should check for updates on the web, and what to do when it is known before launching that an update is available.
In the previous versions of Java Web Start the <offline-allowed> element was overloaded to mean two things. First, it meant that the application was allowed to run in "offline" mode. (An application can be run in offline mode either from the command line by adding the "-offline" argument, or from the Cache Viewer.) Second, it meant that attempts to check for update before launching an application (when not run in offline mode) could time out. When a check for update times out, the application would be launched from the cache wile the update check continued in the background.
With the advent of the <update> element and it's check attribute in 6.0, the <offline-allowed> element no longer has this second meaning. The default values: <update check="timeout"/>. which is the same behavior as previous versions where <offline-allowed> was specified. For the behavior that previously used whenever <offline-allowed> was omitted, you need to specify <update check="always"/>. A third value <update check="background"/> can be specified to always immediately launch from the cache while spawning a check for update in the background. The second attribute, "policy", is used to determine what to do when it is known before starting the application that there is an update available. You can either always get the update, or prompt the user. The policy attribute values can be either "always" (this is default) , "prompt-update" or "prompt-run".
  • JNLP Specification relaxation of requirements for the DownloadService API.
In the previous versions, the URLs passed as arguments to all of the APIs were restricted to be URLs to resources listed in the jnlp file(s) of the running application. This restriction is changed such that there are no restrictions for signed and trusted code, and the restriction on untrusted code is not that it be listed in the jnlp file(s), but only that it be from the same codebase.
Further, URLs to jnlp file(s) themselves are allowed, so that calling DownloadService.removeResource() can now be used to remove a whole application from the cache, and DownloadService.loadResource() can be used to import an application.
One effect of this change is that now resources not listed in any jnlp file can now be used in an application. For example, after determining the locale is set to en_xx, an application can then load resources_en_xx.jar using the DownloadService, without listing all the available resource jars in the jnlp file. (Allowing you to dynamically add support for more locales without changing the jnlp file).
  • Implementation of a SocketService
Another significant specification change is a clarification in the definition of the sandbox, that it is only the default sandbox, and that the implementation is free to prompt the user to allow actions that wouldn't be allowed by the sandbox. You already saw in 1.5.0 that this was done for printing, so that just by using the normal printing api in awt, you could expand the sandbox to allow the application to access the printer (if the user agreed). In 6.0 this is also done for socket connections, so that if an untrusted application attempts to connect to a url, the user can be prompted to allow the connection.

  • New <java> element in jnlp file to replace <j2se> element.
For jnlp files that will only be used with Java Web Start version 6.0 or later, the <java> element can be used to replace the <j2se> tag. (This is mainly because the Java Platform Standard Edition is no longer called j2se.) For backward compatibility, the <j2se> tag will continue to work. The <java> element will be identical to the <j2se> element..
  • The <association> element now may contain the <icon> and <description> sub-elements.
When creating file extension and mime type associations with you Java Web Start application, you can now specify a separate icon to be used for each association (as opposed to using the default icon for the application). You can also now specify a description.
  • Jar Indexing is now fully supported, and the JNLPClassLoader is now an instanceof the URLClassLoader.
The JNLPClassLoader was rewritten to extend URLClassLoader. This gives several powerful advantages.
First, Jar Indexing is now fully supported. If you have several jar files, and create a jar index in the main jar file that indexes all the jar files, you can then mark each additional jar as lazy, and it will not be downloaded until and unless a resource or class in it is referenced. This makes the old part and package elements unnecessary for insuring that lazy jars are not downloaded prematurely.
Second, Since the JNLPClassLoader now extends URLClassLoader, an Application can call getURLs() to get a list of the jar elements that are listed in the jnlp files (or have been downloaded using the DownloadService API, even if not listed in any jnlp file, see above).
Finally, The URL returned for calls to ClassLoader.getResource() is now the proper JAR URL of the item on the net. In previous versions, this URL returned was a jar url of the file url of the item in the cache. By extending URLClassLoader, the cached location (if it exists) is meaningless, and it allows Java Web Start to operate without caching.
  • Enhanced icon support.
Java Web Start now supports two new icon formats, ".png", and ".ico". This allows you to specify an icon that will not need to be translated into a different format depending on it's use. You can also now specify kind="shortcut", and Java Web Start will now honor the width and height hints. This means if you specify:
<icon kind="shortcut" href="menushortcut.ico" width="16" height="16"/>
<icon kind="shortcut" href="desktopshortcut.ico" width="32" height="32"/>
you can specify a separate image for any desktop and menu shortcut created. (note: for desktop shortcuts, Java Web Start will use the icon whose size is closer to 32X32, and for menu shortcuts Java Web Start will use the icon whose size is closer to 16X16 )
  • Enhanced support for Add/Remove program entries on Windows.
The Windows Add/Remove program entries for Java Web Start applications will now include the publisher, publisher websight, install date, and application icon from the information block of the jnlp file.
  • Desktop shortcut tooltips.
Desktop shortcuts created by Java Web Start will now use the <description> element in the jnlp file to create a tooltip describing the application.
  • JNLPDownloadServlet enhancements.
The JnlpDownloadServlet now contains both a $$hostname and a $$sight macro. The $$hostname macro is expanded to contain the host name. The $$site macro is expanded to contain the web site address without the WAR context portion.
  • The list of safe vm args and safe properties has been expanded.
See the developers guide for the current list of safe properties and vm args.
  • Several Command Line Interface (CLI) items have been changed or added. See the developers guide for the current Javaws CLI.

The following enhancements are in common between Java Web Start and Java Plug-in.

  • All dialogs have been redesigned to be more user friendly.
All of the dialogs and screens shown by Java Web Start and Java Plug-in have been redesigned with help from the User Experience team to be more user friendly, intuitive, and accessible.
  • DownloadEngine and cache consolidation and redesign.
The entire caching mechanism and download engine has been redesigned and consolidated between Java Web Start and Java Plug-in.
This brings several new features to Java Web Start, previously available only in Java Plug-in and vise versa.
  • Caching can now be disabled entirely via the Java Control Panel.
  • The cache max size set in the JCP is now honored in Java Web Start, and a cleanup thread may be started by Java Web Start to removed LRU items from the cache when it is approaching the max size set by the user.
  • The <no-cache> directive is now honored. If a downloaded resource contains the no-cache directive, it will not be put in the cache.
  • The expiration-date will be honored. If a downloaded resource contains an expiration date, it will not be used after that date.
note: The format of the cache is completely changed and should never be assumed. Any existing code that assumed the previous format of the cache, for either Java Web Start or Java Plug-in will no longer work. Existing applications in the Java Web Start cache will be upgraded and converted to the new cache format the first time you run a Java Web Start application, or if you launch the cache viewer using "javaws -viewer". Likewise the system cache will be upgraded and converted to the new format the first time you launch Java Web Start in system mode, or if you just launch "javaws -system".
  • The Java Console is now excluded from modality.
By using the new modality features added by AWT in Java 6, You can now interact with the Java Console even when the Application is displaying a modal Dialog.
  • New support for OCSP/CRL
Java Web Start and Java Java Plug-in now support CRL (Certificate Revocation Lists) and OCSP (Online Certificate Status Protocol) for verifying the certificates.
  • New Support for SSL/TSL
An Option has been added to the Java Control Panel to select the default SSL handshaking protocol.
The default is set to SSLv3 and SSLv2, but then user or enterprise can change it to TSL.


Enhancements to Java Web Start in J2SE 5.0

Java

Enhancements to
Java Web Start in J2SE 5.0

 Java Web Start Contents
  • Elimination of Application Manager: The J2SE 5.0 release no longer contains the Application Manager. Its major functionality is now contained in the Java Control Panel (see item 3 below) and the JNLP Cache Viewer (see item 4 below). The remaining functionality— viewing web pages containing JNLP links—is better served by a web browser.

  • Elimination of Developer Bundle: Java Web Start is now fully integrated into the JRE and the JDK. The items which were previously contained in a separate developer bundle are now contained in the JDK. The documentation which was previously contained in the developers bundle is now available online. The JDK now contains a samples directory with sample source code to four Java Web Start applications, a sample JRE installer, and the JNLP download servlet. The JDK now also contains jardiff.jar, jnlp.jar, and jnlp-servlet.jar.

  • JNLP Cache Viewer: The JNLP Cache Viewer replaces the functionality of the Application Manager's "downloaded Applications" view. Now all applications, applets, libraries and installers are shown. Available applications can be launched online or offline, removed, or restored from the web. All JNLP files are now kept in the cache (even those without href parameters).

  • System Cache: Java Web Start now contains both system and user caches. The system administrator can now pre-load applications and shared libraries into the system cache so that multiple users can share the same resources.

  • Import Facility: Java Web Start now contains an import facility. This can be used for CD installs, where code is initially loaded from one location and then updated from another. It can also be used to pre-install applications and libraries in either the user or system cache without running the applications.

  • Desktop Integration: (1) Desktop integration of applications has been extended to GNOME and enhanced to allow an application's JNLP file to specify what integration to do. The JNLP file can now suggest desktop and/or menu and specify submenu names. (2) On Windows and on Unix running GNOME 2.0 or above, Java Web Start applications can now register themselves to be the primary handler for specific MIME types and extensions on the desktop or file system (but not as links in web pages). (3) Now other related content—HTML links, native content, and related JNLP applications—can be included in the desktop integration of an application.

  • API Enhancements: The JNLP API has been extended to contain an Extended Service and a Single Instance Service. The Extended Service contains file IO APIs not available in the original spec. The Single Instance Service provides a mechanism whereby applications can insure that multiple invocations of the same application will cause new arguments to be passed to the original instance. This avoids the overhead of relaunching Java. Note that the Single Instance behavior will only be enabled after the application calls the Single Instance API in the JNLP application.

  • VM arguments: A JNLP file can now request arbitrary arguments to the virtual machine. Previous JNLP applications could only use the initial-heap-size and max-heap-size arguments to the J2SE element; now a java-vm-args argument has been added. Java Web Start will honor the requests for any normal java and -X arguments that it considers "safe". A list of all such arguments will be included with each release so that the JNLP Spec does not need to change.

  • A JNLP applications running in a sandbox can now print with full support using the Java Printing APIs: Whenever the JNLP application tries to print, Java Web Start will pop up a security dialog asking the user for permission for the application to print. This provides JNLP applications with complete printing support; previously they could only use JNLP printing APIs. This is similar to the applet printing behaviour in Java Plug-in.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

 Sun Microsystems, Inc
Java Software


Java Web Start 1.4.2 Release Notes

Java

JavaTM Web Start 1.4.2 Release Notes

 Documentation Contents

These release notes include the following sections:

  • Enhancements
    • Improved JNLP URL Support In Application Manager
    • Dynamic Download of HTTPS Certificates
    • Automatic Detection of JREs
    • Combined Control Panel Infrastructure
    • Security Audit of Java Web Start
    • First-Time Prompt for Shortcut
    • Integration with InstallShield 7
  • Bug Fixes

Enhancements

Improved JNLP URL Support In Application Manager

JNLP URLs are now directly openable from the JAWS Application Manager and can be bookmarked. Moreover, they may be .html or .jnlp files. (This is RFE 4531885.)

Dynamic Download of HTTPS Certificates

Java Web Start now dynamically imports certificates in much the same way as browsers do, making use of https much easier for users. (This is RFE 4696477.) For more information, see Dynamic Download of HTTPS Certificates in the Java Web Start 1.4.2 Developer Guide.

Automatic Detection of JREs

Every time JAWS is run, it automatically detects all "registered" JREs on the computer.

There are two types of JREs recognized by JAWS: registered and unregistered. A registered JRE is one that is recorded in the system or package registry, i.e., the system registry on Windows, the package database on Solaris, and the RPM database on Linux. An unregistered JRE is not recorded in a registry; e.g., a JRE mounted on a network drive in an unregistered JRE. (This is RFE 4474876.)

Combined Control Panel Infrastructure

There is now a combined control panel infrastructure used for the Java deployment products, including Java Plug-in and Java Web Start. If you have taken advantage of knowing certain undocumented information, such as the Java Web Start cache location or the configuration file format and location, you could be affected. (This is RFE 4723794.)

Security Audit of Java Web Start

A security audit of Java Web Start has been completed. (This is RFE 4645808.)

First-Time Prompt for Shortcut

Users are now asked if they want a desktop shorcut the first time an application is downloaded and cached. (This is RFE 4737538.)

Integration with InstallShield 7

Java Web Start is now installed via InstallShield 7 as part of the JRE. There is no longer a separate installer for Java Web Start. (This is RFE 4718282.)

Bug Fixes

Bug ID | Synopsis
4791532 | Dialogs are layed out wrong in javawebstart
4778185 | JNLPClassLoader can still return unencoded URL
4780676 | Java Web Start sometimes fails to launch applications while offline
4757170 | Typo in Jaws Pop-up window <Rename HTML Entry> "You must enter and entry name"
4777238 | Cache Location JTextField should handle enter properly
4685501 | De - Word "Console" is not translated in the titlebar of jaws Console dialog
4688776 | JaWS, JAWS 1.2 b08, Translation errors
4785128 | Exception coming if you use mantis-beta jaws with jre1.2.2 on Windows
4772298 | Proxy authentication dialog pops up twice even if username/password is correct
4772381 | System.exit not working with shutdownhook and JWS console
4784292 | Java Web Start should use cached jnlp file if possible to improve startup time
4782008 | Review webstart ActiveX control
4782000 | Need to update webstart autoinstall version tags
4785581 | JAWS on linux cannot be invoked via symbolic link
4789162 | JAWS on solaris/sparc cannot be invoked via symbolic link
4792033 | Need javaws link in /usr/bin on Solaris
4792949 | autoupdate of javaws file is not getting staged in RE area
4791695 | Help Menu Item, "Check For Update" doesn't notify of the latest 1.2 JWS version
4735750 | Fix Certificate-chain Validation
4711515 | Wrong AppContext used in RMI threads
4757168 | Jaws application not properly cached if PATH to the application contains letter N
4759001 | Exception coming (getText()),when trying to Clear Folder with the Downloaded vie
4759005 | Exception coming (synchron),when trying to Clear Folder with the Downloaded vie
4665132 | Webstart not returning ContextClassLoader consistently under jre 1.4.0
4696315 | Splash screen is not showing with large image
4699299 | Splash Screen is wierd on Linux machine
4734410 | JAVAWS is passing the property set in extension installer to main program
4739089 | Java Web Wtart does not handle signed jars correctly
4743169 | Root Certificates panel in Java WS app mgr is blank if cacerts is missing
4754648 | Advanced Preference Panel miss a key shortcut
4754763 | getResourceAsStream() fails with JNLPClassLoader
4772558 | Implement new Icons from UE group.
4772559 | Reduce access scope (phase II)
4772563 | New default splash screen, and modified customized ones
4772926 | Extra ; char on the window title
4773110 | Apps are run with the wrong JRE
4775373 | Problem checking for updates on https codebase
4379831 | Please launch new VM for -Dsun.java2d.noddraw=true
4474875 | Incremental updates fail if going from basic proto to version based.
4485537 | 'Read -1 of 2k (0%)' message still displayed in DL window
4653074 | JWS: Update Shortcuts and programs folder when app name changed in jnlp file.
4666303 | Cannot delete java.sun.com cache directory structure in Application Manager
4687256 | Jaws App_mgr did not prompt shortcut options on the second launch with j2re1.2.2
4688193 | Reduce access scope
4691541 | JWS should handle the version control of splash screen icons
4708051 | Exception coming when you try to "Clear Folder" with View/Download_App enabled
4718813 | Application Manager lost focus after first startup
4729230 | Loging to "TEMP" file does not work
4761563 | Can't set property to "" in jnlp file
4625826 | Unexpected exit when lazy-loading unsigned jar file
4775823 | Unnecessary . (dot) in Appman Shortcuts tab after "When to Create" instruction.
4685497 | De - Overlapping text in the certificates tab
4723717 | JRE1.4.0_x - JaWS component cannot be installed in non-default location.
4777764 | Cancelling import certificate will cause ca chain completely broken
4694453 | Customize splash screen would not work if no href
4720897 | Jar Diff'ing does not work if jars are packaged in a war file.
4724977 | The application panel size it too small to show the string.
4726525 | Certificate detail panel should have focus on OK button
4751780 | JWS Hanging on Jar update (Scanning entries at 100% for a LONG time)
4759104 | Clear cache function could not remove certificate
4759298 | "details" button not showing on app_mgr root certicates tab
4480656 | View Source in IE won't work after creating shortcut for Notepad Demo
4498419 | WebStart won't start if the default browser is deinstalled
4623207 | jaxp.jar
4626733 | Multi-platform support
4653036 | JarDiffHandler() should use javax.servlet.context.
4654173 | JWS litters $WINUSERHOME\Local Settings\Temp and d:\TMP
4667701 | JWS should give the name of the resource that fails
4668473 | Cannot create shortcut if title is too long
4676386 | Better user-agent value in http request header
4685505 | De - Broken border around " Choose Log File Name"
4687857 | Focus is back to wrong window after closing dialog
4699771 | JWS login prompt for secure resources is not robust.
4744945 | JWS 1.2 application cannot delete after upgrade
4775777 | "Invalid Cache Location" window incorrect behavior
4492987 | Java Web Start Installation documentation for Linux
4768914 | Javaws unsigned extension installer can call setJREInfo
4773602 | Auto proxy detection is failing when using Netscape 4.79 and 7.0
4777392 | Mantis b06:file type description for jnlp is not set to NS/IE on Win98 ja
4665251 | Preferences: Shortcut Options: When To Create := "Always" fails (always:)
4692415 | Jaws application freezing if you launching it as a root, through browser on Sol
4723790 | Web start install should use pack instead of crunch
4739415 | Jaws j2re1.4.0 installer problem
4772158 | Make web start part of JRE image on Unix platform
4776098 | Javaws JRE autodownload not working
4431364 | JRE should always be installed
4459559 | J2SE Installer can't finish the work if Installed
4463745 | WebStart can't handle Netscape automatic proxy configuration
4469455 | Proxy autoconfig script parsing has problems
4514686 | Installer can't handle adding >100th mime type to Netscape on Windows
4615288 | Build fails under Windows due to install directory not existing
4653566 | JWS is not compatible with the centralization of home directories under NT
4685474 | Message on Japanese Installer/Uninstaller does not fall within a view area
4730185 | javaws.cfg file in $USERPROFILE is not uninstalled
4763779 | Need to check javaws bootdir during control build
4764601 | Unsigned extension installer throws exception when Main.systemExit is called
4765164 | Singleton api service classes can be re-initialized
4765165 | com.sun.jnlp package needs to be protected from package addition
4775492 | Javaws app with no href in JNLP causing nonfatal exception on netscape/unix
4768903 | Javaws dev target doesn't work during dev build
4741507 | Missing signed entry JNLPException is not explicit

Copyright © 2002 Sun Microsystems, Inc. All Rights Reserved.

Please submit comments at our feedback form. 		Sun
Java Software


Java Web Start AutoInstall
Click here to download Java Web Start


Java(TM) Web Start

Java

JavaTM Web Start

 Documentation Contents

Java Web Start version 1.6.0 is included in the Java TM Platform, Standard Edition 6 JDK.

Overview

Java Web Start is an application-deployment technology that gives you the power to launch full-featured applications with a single click from your Web browser. You can now download and launch applications, such as a complete spreadsheet program or an Internet chat client, without going through complicated installation procedures.

Java Web Start includes the security features of the Java platform, so the integrity of your data and files is never compromised. In addition, Java Web Start technology enables you to use the latest Java SE technology with any browser.

With Java Web Start, you launch applications simply by clicking on a Web page link. If the application is not present on your computer, Java Web Start automatically downloads all necessary files. It then caches the files on your computer so the application is always ready to be relaunched anytime you want—either from an icon on your desktop or from the browser link. And no matter which method you use to launch the application, the most current version of the application is always presented to you.

Enhancements

  • Java Web Start Enhancements in Java SE 6.0

Documentation

  • Developer's Guide
  • FAQ
  • JNLP Specification
  • Package javax.jnlp

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Please submit comments at our feedback form. 		Sun
Java Software


Java(TM) Web Start Technology README

Java

README

JavaTM Web Start Technology

Version 1.4.2

Table of Contents

Introduction
Installation Instructions
Using Java Web Start Software
Release Notes

Introduction

JavaTM Web Start is a deployment solution for Java-technology-based applications. It is the plumbing between the computer and the Internet that allows the user to launch and manage applications right off the Web. Java Web Start provides easy, one-click activation of applications, and guarantees that you are always running the latest version of the application, eliminating complicated installation or upgrade procedures.

Distributing software across the Web in the tradition manner requires the user to find the installer on the Web, download the installer, locate the installer on the system, and then execute the installer. Once the installer is executed, it prompts for installation directories and installation options such as full, typical, or minimum. This is a time-consuming and complicated task, and one that must be repeated for each new version of the software.

By contrast, Web-deployed applications, such as your favorite HTML-based email client and calendar, auction sites, and so on, are a breeze to install and use. The Web browser has automated the entire process. There is no complicated download, setup, and configuration steps, and you are guaranteed to always be running the latest version.

Java Web Start technology provides the same benefits to full-featured applications as described above for HTML-based applications. Java Web Start technology is an application deployment solution for the Web. Using a full-featured application instead of an HTML-based client can have many benefits:

  • A highly-interactive user interface, comparable to traditional applications, such as word processors and spreadsheets.
  • Lower bandwidth requirements. An application does not necessarily have to connect back to the Web server on each click, and it can cache already-downloaded information. Thus, it can provide better interactivity on slow connections.
  • Support for off-line use.
Or course, you still have to download the application the first time you use it. An HTML-based application, thus has a first-time activation cost. Typically, a Web page is brought up in a matter of seconds. A Java TM-technology-based application will require download times in the order of minutes on a typical modem connection. The Java Web Start caches all downloaded files locally on the computer. Thus, although the first-time activation cost is higher for applications than for HTML pages, subsequent launches will be almost instantaneous because all the required resources are already available locally.

On each launch, Java Web Start checks the Web server to see if a new version of the application is available, and if so, automatically downloads and launches it. Thus, applications are automatically brought up to date. There is no complicated upgrade procedure.

Security

Java Web Start is built on top of the Java 2 platform, which provides a comprehensive security architecture. Applications launched with Java Web Start will, by default, run in a restricted environment ("sandbox") with limited access to files and network. Thus, launching applications using Java Web Start maintains system security and integrity.

An application can request unrestricted access to your system. In this case, Java Web Start will display a Security Warning dialog when the application is launched for the first time. The security warning will show information about the vendor who developed the application. If you choose to trust the vendor, then the application will be launched. The information about the origin of the application is based on digital code signing.

Installation Instructions

Java Web Start is installed with the SDK/JRE. For installation instructions, follow the standard installation instructions for the SDK/JRE you are installing.

Using Java Web Start Software

Java Web Start allows you to launch Java-technology-based applications directly from the Web. An application can be launched in three different ways:
  • From a Web browser by clicking on a link.
  • From Java Web Start's built-in Application Manager, which tracks recently used applications and provides quick access to your favorite applications.
  • From desktop icons or the Start Menu (Microsoft Windows only).
Regardless of which way is used, Java Web Start will connect back to the Web server each time an application is launched to check whether an updated version of the application is available.

Launching from a Web browser

On the Java Web Start demos page (http://java.sun.com/products/javawebstart/demos.html), there are links to a number of applications that can be launched with a single click of a mouse. Try launching the different applications by clicking on the Launch buttons. The Web browser will launch Java Web Start, which will then download, cache, and execute the given application. You will notice that the second time you launch an application, it starts much more quickly since it is already present locally and does not need to be downloaded again.

Most of the demos on the page are just downloaded and executed without any user intervention. These applications run in a restricted environment in which they are prevented from accessing the local disk and network, and can be guaranteed not to install any viruses on your computer.

Some demos require extra privileges, such as access to your local hard disk. For these applications, a security dialog will pop up with information about the origin of the application based on who digitally signed the code. The application will run only if you decide to trust the vendor.

That is really all there is to using Java Web Start, but how does it work? The HTML links that launch the applications are, in fact, standard HTML links. However, instead of pointing to another Web page, they link to a special configuration file called a JNLP file. The Web browser examines the file extension and/or the MIME type of the file, and sees that it belongs to Java Web Start. It then launches Java Web Start with the downloaded JNLP file as an argument. Java Web Start proceeds with downloading, caching, and running the application as directed by the JNLP file.

Launching from the built-in Application Manager

The Application Manager is a built-in part of the Java Web Start product. It lets you quickly and easily launch applications that have previously been launched by Java Web Start. It is a combination of a History menu and a Start/Programs menu for your Web deployed Java-technology-based applications. The Application Manager also allows you to see additional information about the applications, with links the applications' home pages.

You launch an application from the Application Manager by double clicking on the application icon or by clicking the launch button.

Another important feature of the Application Manager is the Preferences dialog which lets you examine and modify settings used by Java Web Start. For example, this includes tabs which allow you to:

  • Specify an HTTP Proxy (or tell Java Web Start to use the default browser settings).
  • Clear the cache of downloaded applications.
  • Specify the location of the different versions of Java runtime environments.
  • Select whether a Java console is to be displayed.
  • View the set of root security certificates.
The Application Manager is launched by either clicking on the Java Web Start icon on the desktop or in the Start Menu on Microsoft Windows. On the SolarisTM Operating Environment and Linux, it is launched by invoking the javaws command in the Java Web Start installation directory. The Application Manager can also be launched from a Web browser; see, for example, the demos page (http://java.sun.com/products/javawebstart/demos.html).

Launching from desktop icons and the Start Menu (Microsoft Windows only)

Java Web Start technology can automatically create shortcuts on the Microsoft Windows desktop and in the Start Menu for Web deployed Java-technology-based applications. By default, Java Web Start asks the second time an application is launched, if a shortcut should be created. This can be changed using the Preference panel.

Shortcuts can also be added and removed by using the Application Manager, using the Application/Create Shortcut, and using Application/Remove Shortcut menu item.

Using Java Web Start Software Behind a Proxy Server/Firewall

Java Web Start software must be configured with the correct proxy settings in order to launch applications from outside your firewall. Java Web Start software will automatically try to detect the proxy settings from the default browser on your system (Internet Explorer or NetscapeTM browsers on Microsoft Windows, and Netscape browsers on the Solaris Operating Environment and Linux). Java Web Start technology supports most web proxy auto-configuration scripts. It can detect proxy settings in almost all environments.

If the proxy setting cannot be automatically detected, then you will be prompted to specify the proxy settings the first time you use Java Web Start. Java Web Start will also prompt you for a user name and password required to access an authenticating proxy server. This user name and password will be stored for the current invocation of Java Web Start. However, at the time a newly invoked Java Virtual Machine, if accessing a secure web site, will prompt you for the user name and password since this information is stored within a Java Virtual Machine instance.

You can also use the Java Web Start Preferences panel to view or edit the proxy configuration. Launch the Application Manager, either by clicking on the icon on the desktop (Microsoft Windows), or type ./javaws in the Java Web Start installation directory (Solaris Operating Environment and Linux), and then select Edit/Preferences. If you are in an environment where access to the Web is through a proxy server, you are encouraged to use the Java Web Start Preferences panel to check that these are set-up correctly.

Release Notes

For a list of bug fixes, and changes and enhancements made for this release of Java Web Start, refer to Release Notes and Enhancements and Changes.
This product includes code from Nullsoft, Inc. Copyright © 2003, Sun Microsystems, Inc.
All rights reserved.


Mozilla Public License version 1.1

MOZILLA PUBLIC LICENSE
Version 1.1

1. Definitions.

    1.0.1. "Commercial Use" means distribution or otherwise making the Covered Code available to a third party.

    1.1. ''Contributor'' means each entity that creates or contributes to the creation of Modifications.

    1.2. ''Contributor Version'' means the combination of the Original Code, prior Modifications used by a Contributor, and the Modifications made by that particular Contributor.

    1.3. ''Covered Code'' means the Original Code or Modifications or the combination of the Original Code and Modifications, in each case including portions thereof.

    1.4. ''Electronic Distribution Mechanism'' means a mechanism generally accepted in the software development community for the electronic transfer of data.

    1.5. ''Executable'' means Covered Code in any form other than Source Code.

    1.6. ''Initial Developer'' means the individual or entity identified as the Initial Developer in the Source Code notice required by Exhibit A.

    1.7. ''Larger Work'' means a work which combines Covered Code or portions thereof with code not governed by the terms of this License.

    1.8. ''License'' means this document.

    1.8.1. "Licensable" means having the right to grant, to the maximum extent possible, whether at the time of the initial grant or subsequently acquired, any and all of the rights conveyed herein.

    1.9. ''Modifications'' means any addition to or deletion from the substance or structure of either the Original Code or any previous Modifications. When Covered Code is released as a series of files, a Modification is:

      A. Any addition to or deletion from the contents of a file containing Original Code or previous Modifications.

      B. Any new file that contains any part of the Original Code or previous Modifications.

    1.10. ''Original Code'' means Source Code of computer software code which is described in the Source Code notice required by Exhibit A as Original Code, and which, at the time of its release under this License is not already Covered Code governed by this License.

    1.10.1. "Patent Claims" means any patent claim(s), now owned or hereafter acquired, including without limitation, method, process, and apparatus claims, in any patent Licensable by grantor.

    1.11. ''Source Code'' means the preferred form of the Covered Code for making modifications to it, including all modules it contains, plus any associated interface definition files, scripts used to control compilation and installation of an Executable, or source code differential comparisons against either the Original Code or another well known, available Covered Code of the Contributor's choice. The Source Code can be in a compressed or archival form, provided the appropriate decompression or de-archiving software is widely available for no charge.

    1.12. "You'' (or "Your") means an individual or a legal entity exercising rights under, and complying with all of the terms of, this License or a future version of this License issued under Section 6.1. For legal entities, "You'' includes any entity which controls, is controlled by, or is under common control with You. For purposes of this definition, "control'' means (a) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (b) ownership of more than fifty percent (50%) of the outstanding shares or beneficial ownership of such entity.

2. Source Code License.
    2.1. The Initial Developer Grant.
    The Initial Developer hereby grants You a world-wide, royalty-free, non-exclusive license, subject to third party intellectual property claims:
      (a) under intellectual property rights (other than patent or trademark) Licensable by Initial Developer to use, reproduce, modify, display, perform, sublicense and distribute the Original Code (or portions thereof) with or without Modifications, and/or as part of a Larger Work; and

      (b) under Patents Claims infringed by the making, using or selling of Original Code, to make, have made, use, practice, sell, and offer for sale, and/or otherwise dispose of the Original Code (or portions thereof).

      (c) the licenses granted in this Section 2.1(a) and (b) are effective on the date Initial Developer first distributes Original Code under the terms of this License.

      (d) Notwithstanding Section 2.1(b) above, no patent license is granted: 1) for code that You delete from the Original Code; 2) separate from the Original Code; or 3) for infringements caused by: i) the modification of the Original Code or ii) the combination of the Original Code with other software or devices.

    2.2. Contributor Grant.
    Subject to third party intellectual property claims, each Contributor hereby grants You a world-wide, royalty-free, non-exclusive license

      (a) under intellectual property rights (other than patent or trademark) Licensable by Contributor, to use, reproduce, modify, display, perform, sublicense and distribute the Modifications created by such Contributor (or portions thereof) either on an unmodified basis, with other Modifications, as Covered Code and/or as part of a Larger Work; and

      (b) under Patent Claims infringed by the making, using, or selling of Modifications made by that Contributor either alone and/or in combination with its Contributor Version (or portions of such combination), to make, use, sell, offer for sale, have made, and/or otherwise dispose of: 1) Modifications made by that Contributor (or portions thereof); and 2) the combination of Modifications made by that Contributor with its Contributor Version (or portions of such combination).

      (c) the licenses granted in Sections 2.2(a) and 2.2(b) are effective on the date Contributor first makes Commercial Use of the Covered Code.

      (d) Notwithstanding Section 2.2(b) above, no patent license is granted: 1) for any code that Contributor has deleted from the Contributor Version; 2) separate from the Contributor Version; 3) for infringements caused by: i) third party modifications of Contributor Version or ii) the combination of Modifications made by that Contributor with other software (except as part of the Contributor Version) or other devices; or 4) under Patent Claims infringed by Covered Code in the absence of Modifications made by that Contributor.

3. Distribution Obligations.

    3.1. Application of License.
    The Modifications which You create or to which You contribute are governed by the terms of this License, including without limitation Section 2.2. The Source Code version of Covered Code may be distributed only under the terms of this License or a future version of this License released under Section 6.1, and You must include a copy of this License with every copy of the Source Code You distribute. You may not offer or impose any terms on any Source Code version that alters or restricts the applicable version of this License or the recipients' rights hereunder. However, You may include an additional document offering the additional rights described in Section 3.5.

    3.2. Availability of Source Code.
    Any Modification which You create or to which You contribute must be made available in Source Code form under the terms of this License either on the same media as an Executable version or via an accepted Electronic Distribution Mechanism to anyone to whom you made an Executable version available; and if made available via Electronic Distribution Mechanism, must remain available for at least twelve (12) months after the date it initially became available, or at least six (6) months after a subsequent version of that particular Modification has been made available to such recipients. You are responsible for ensuring that the Source Code version remains available even if the Electronic Distribution Mechanism is maintained by a third party.

    3.3. Description of Modifications.
    You must cause all Covered Code to which You contribute to contain a file documenting the changes You made to create that Covered Code and the date of any change. You must include a prominent statement that the Modification is derived, directly or indirectly, from Original Code provided by the Initial Developer and including the name of the Initial Developer in (a) the Source Code, and (b) in any notice in an Executable version or related documentation in which You describe the origin or ownership of the Covered Code.

    3.4. Intellectual Property Matters

      (a) Third Party Claims.
      If Contributor has knowledge that a license under a third party's intellectual property rights is required to exercise the rights granted by such Contributor under Sections 2.1 or 2.2, Contributor must include a text file with the Source Code distribution titled "LEGAL'' which describes the claim and the party making the claim in sufficient detail that a recipient will know whom to contact. If Contributor obtains such knowledge after the Modification is made available as described in Section 3.2, Contributor shall promptly modify the LEGAL file in all copies Contributor makes available thereafter and shall take other steps (such as notifying appropriate mailing lists or newsgroups) reasonably calculated to inform those who received the Covered Code that new knowledge has been obtained.

      (b) Contributor APIs.
      If Contributor's Modifications include an application programming interface and Contributor has knowledge of patent licenses which are reasonably necessary to implement that API, Contributor must also include this information in the LEGAL file.

    (c) Representations.
      Contributor represents that, except as disclosed pursuant to Section 3.4(a) above, Contributor believes that Contributor's Modifications are Contributor's original creation(s) and/or Contributor has sufficient rights to grant the rights conveyed by this License.

    3.5. Required Notices.
    You must duplicate the notice in Exhibit A in each file of the Source Code. If it is not possible to put such notice in a particular Source Code file due to its structure, then You must include such notice in a location (such as a relevant directory) where a user would be likely to look for such a notice. If You created one or more Modification(s) You may add your name as a Contributor to the notice described in Exhibit A. You must also duplicate this License in any documentation for the Source Code where You describe recipients' rights or ownership rights relating to Covered Code. You may choose to offer, and to charge a fee for, warranty, support, indemnity or liability obligations to one or more recipients of Covered Code. However, You may do so only on Your own behalf, and not on behalf of the Initial Developer or any Contributor. You must make it absolutely clear than any such warranty, support, indemnity or liability obligation is offered by You alone, and You hereby agree to indemnify the Initial Developer and every Contributor for any liability incurred by the Initial Developer or such Contributor as a result of warranty, support, indemnity or liability terms You offer.

    3.6. Distribution of Executable Versions.
    You may distribute Covered Code in Executable form only if the requirements of Section 3.1-3.5 have been met for that Covered Code, and if You include a notice stating that the Source Code version of the Covered Code is available under the terms of this License, including a description of how and where You have fulfilled the obligations of Section 3.2. The notice must be conspicuously included in any notice in an Executable version, related documentation or collateral in which You describe recipients' rights relating to the Covered Code. You may distribute the Executable version of Covered Code or ownership rights under a license of Your choice, which may contain terms different from this License, provided that You are in compliance with the terms of this License and that the license for the Executable version does not attempt to limit or alter the recipient's rights in the Source Code version from the rights set forth in this License. If You distribute the Executable version under a different license You must make it absolutely clear that any terms which differ from this License are offered by You alone, not by the Initial Developer or any Contributor. You hereby agree to indemnify the Initial Developer and every Contributor for any liability incurred by the Initial Developer or such Contributor as a result of any such terms You offer.

    3.7. Larger Works.
    You may create a Larger Work by combining Covered Code with other code not governed by the terms of this License and distribute the Larger Work as a single product. In such a case, You must make sure the requirements of this License are fulfilled for the Covered Code.

4. Inability to Comply Due to Statute or Regulation.
    If it is impossible for You to comply with any of the terms of this License with respect to some or all of the Covered Code due to statute, judicial order, or regulation then You must: (a) comply with the terms of this License to the maximum extent possible; and (b) describe the limitations and the code they affect. Such description must be included in the LEGAL file described in Section 3.4 and must be included with all distributions of the Source Code. Except to the extent prohibited by statute or regulation, such description must be sufficiently detailed for a recipient of ordinary skill to be able to understand it.
5. Application of this License.
    This License applies to code to which the Initial Developer has attached the notice in Exhibit A and to related Covered Code.
6. Versions of the License.
    6.1. New Versions.
    Netscape Communications Corporation (''Netscape'') may publish revised and/or new versions of the License from time to time. Each version will be given a distinguishing version number.

    6.2. Effect of New Versions.
    Once Covered Code has been published under a particular version of the License, You may always continue to use it under the terms of that version. You may also choose to use such Covered Code under the terms of any subsequent version of the License published by Netscape. No one other than Netscape has the right to modify the terms applicable to Covered Code created under this License.

    6.3. Derivative Works.
    If You create or use a modified version of this License (which you may only do in order to apply it to code which is not already Covered Code governed by this License), You must (a) rename Your license so that the phrases ''Mozilla'', ''MOZILLAPL'', ''MOZPL'', ''Netscape'', "MPL", ''NPL'' or any confusingly similar phrase do not appear in your license (except to note that your license differs from this License) and (b) otherwise make it clear that Your version of the license contains terms which differ from the Mozilla Public License and Netscape Public License. (Filling in the name of the Initial Developer, Original Code or Contributor in the notice described in Exhibit A shall not of themselves be deemed to be modifications of this License.)

7. DISCLAIMER OF WARRANTY.
    COVERED CODE IS PROVIDED UNDER THIS LICENSE ON AN "AS IS'' BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE COVERED CODE IS FREE OF DEFECTS, MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE COVERED CODE IS WITH YOU. SHOULD ANY COVERED CODE PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL DEVELOPER OR ANY OTHER CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY COVERED CODE IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER.
8. TERMINATION.
    8.1. This License and the rights granted hereunder will terminate automatically if You fail to comply with terms herein and fail to cure such breach within 30 days of becoming aware of the breach. All sublicenses to the Covered Code which are properly granted shall survive any termination of this License. Provisions which, by their nature, must remain in effect beyond the termination of this License shall survive.

    8.2. If You initiate litigation by asserting a patent infringement claim (excluding declatory judgment actions) against Initial Developer or a Contributor (the Initial Developer or Contributor against whom You file such action is referred to as "Participant") alleging that:

    (a) such Participant's Contributor Version directly or indirectly infringes any patent, then any and all rights granted by such Participant to You under Sections 2.1 and/or 2.2 of this License shall, upon 60 days notice from Participant terminate prospectively, unless if within 60 days after receipt of notice You either: (i) agree in writing to pay Participant a mutually agreeable reasonable royalty for Your past and future use of Modifications made by such Participant, or (ii) withdraw Your litigation claim with respect to the Contributor Version against such Participant. If within 60 days of notice, a reasonable royalty and payment arrangement are not mutually agreed upon in writing by the parties or the litigation claim is not withdrawn, the rights granted by Participant to You under Sections 2.1 and/or 2.2 automatically terminate at the expiration of the 60 day notice period specified above.

    (b) any software, hardware, or device, other than such Participant's Contributor Version, directly or indirectly infringes any patent, then any rights granted to You by such Participant under Sections 2.1(b) and 2.2(b) are revoked effective as of the date You first made, used, sold, distributed, or had made, Modifications made by that Participant.

    8.3. If You assert a patent infringement claim against Participant alleging that such Participant's Contributor Version directly or indirectly infringes any patent where such claim is resolved (such as by license or settlement) prior to the initiation of patent infringement litigation, then the reasonable value of the licenses granted by such Participant under Sections 2.1 or 2.2 shall be taken into account in determining the amount or value of any payment or license.

    8.4. In the event of termination under Sections 8.1 or 8.2 above, all end user license agreements (excluding distributors and resellers) which have been validly granted by You or any distributor hereunder prior to termination shall survive termination.

9. LIMITATION OF LIABILITY.
    UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER TORT (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL YOU, THE INITIAL DEVELOPER, ANY OTHER CONTRIBUTOR, OR ANY DISTRIBUTOR OF COVERED CODE, OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO ANY PERSON FOR ANY INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES, EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES. THIS LIMITATION OF LIABILITY SHALL NOT APPLY TO LIABILITY FOR DEATH OR PERSONAL INJURY RESULTING FROM SUCH PARTY'S NEGLIGENCE TO THE EXTENT APPLICABLE LAW PROHIBITS SUCH LIMITATION. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS EXCLUSION AND LIMITATION MAY NOT APPLY TO YOU.
10. U.S. GOVERNMENT END USERS.
    The Covered Code is a ''commercial item,'' as that term is defined in 48 C.F.R. 2.101 (Oct. 1995), consisting of ''commercial computer software'' and ''commercial computer software documentation,'' as such terms are used in 48 C.F.R. 12.212 (Sept. 1995). Consistent with 48 C.F.R. 12.212 and 48 C.F.R. 227.7202-1 through 227.7202-4 (June 1995), all U.S. Government End Users acquire Covered Code with only those rights set forth herein.
11. MISCELLANEOUS.
    This License represents the complete agreement concerning subject matter hereof. If any provision of this License is held to be unenforceable, such provision shall be reformed only to the extent necessary to make it enforceable. This License shall be governed by California law provisions (except to the extent applicable law, if any, provides otherwise), excluding its conflict-of-law provisions. With respect to disputes in which at least one party is a citizen of, or an entity chartered or registered to do business in the United States of America, any litigation relating to this License shall be subject to the jurisdiction of the Federal Courts of the Northern District of California, with venue lying in Santa Clara County, California, with the losing party responsible for costs, including without limitation, court costs and reasonable attorneys' fees and expenses. The application of the United Nations Convention on Contracts for the International Sale of Goods is expressly excluded. Any law or regulation which provides that the language of a contract shall be construed against the drafter shall not apply to this License.
12. RESPONSIBILITY FOR CLAIMS.
    As between Initial Developer and the Contributors, each party is responsible for claims and damages arising, directly or indirectly, out of its utilization of rights under this License and You agree to work with Initial Developer and Contributors to distribute such responsibility on an equitable basis. Nothing herein is intended or shall be deemed to constitute any admission of liability.
13. MULTIPLE-LICENSED CODE.
    Initial Developer may designate portions of the Covered Code as “Multiple-Licensed”. “Multiple-Licensed” means that the Initial Developer permits you to utilize portions of the Covered Code under Your choice of the MPL or the alternative licenses, if any, specified by the Initial Developer in the file described in Exhibit A.

EXHIBIT A -Mozilla Public License.

    ``The contents of this file are subject to the Mozilla Public License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
    http://www.mozilla.org/MPL/

    Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF
    ANY KIND, either express or implied. See the License for the specific language governing rights and
    limitations under the License.

    The Original Code is ______________________________________.

    The Initial Developer of the Original Code is ________________________. Portions created by
    ______________________ are Copyright (C) ______ _______________________. All Rights
    Reserved.

    Contributor(s): ______________________________________.

    Alternatively, the contents of this file may be used under the terms of the _____ license (the “[___] License”), in which case the provisions of [______] License are applicable instead of those above. If you wish to allow use of your version of this file only under the terms of the [____] License and not to allow others to use your version of this file under the MPL, indicate your decision by deleting the provisions above and replace them with the notice and other provisions required by the [___] License. If you do not delete the provisions above, a recipient may use your version of this file under either the MPL or the [___] License."

    [NOTE: The text of this Exhibit A may differ slightly from the text of the notices in the Source Code files of the Original Code. You should use the text of this Exhibit A rather than the text found in the Original Code Source Code for Your Modifications.]


Packaging JNLP Applications in a Web Archive

Java TM Web Start 1.4.2

Please send comments and feedback to Java Web Start feedback.

Table of Contents

Introduction
Examples
Servlet Configuration
Specifying Resources
Mapping Requests to Resources
Processing of JNLP Files

Introduction

Java Web Start includes a servlet in the developer's pack that can be used to package a JNLP file and its associated resources in a Web Archive (.war) file. The purpose of the servlet is to provide a simple and convenient packaging format for JNLP applications, so they can be easily deployed in a Web Container, such as Tomcat or a J2EE-compliant Application Server.

The download servlet supports the following features:

  • Automatic installation of the codebase URL into JNLP files, thus eliminating manual management of hard-coded URLs into JNLP files.
  • Explicit specification of the timestamp for a JNLP file, independent of the file-system timestamp.
  • Supports all download protocols defined in the JNLP specification v1.0.1. These include basic download protocol, version-based download protocol, and extension download protocol.
  • Version-based information is specified per file or per directory in the Web archive. Thus, no centralized file needs to be managed for the entire archive.
  • Automatic generation of JARDiff files

The packaging support consists of one servlet: JnlpDownloadServlet. The servlet is packaged into the jnlp-servlet.jar file.

Below are two examples of how to use the servlet followed by a detailed description of the functionality of the servlet.

Examples

The first example shows how an application can be packaged into a WAR file without using the version-based download. The JnlpDownloadServlet is used to insert the exact URL into the JNLP file at request time. The second example shows how to add support for version-based download as well.

WAR file without use of version-download protocol

The example1.war contains:
   /index.html
   /app/launch.jnlp
   /app/application.jar
   /app/images/icon.gif
   /WEB-INF/web.xml
   /WEB-INF/lib/jnlp-servlet.jar
   /WEB-INF/lib/<jar files for XML parser> (not needed if the servlet container is running J2SE 1.4+)
The JNLP file for the application would look like this:
   TS: 2002-04-23 19:21:05
   <?xml version="1.0" encoding="UTF-8"?>
   <jnlp codebase="$$codebase">
     <information>
         <title>Example 1</title>
         <vendor>Myself</vendor>
         <description>just an example</description>
         <icon href="images/icon.gif"/>
     </information>
     <resources>
       <j2se version="1.2+"/>
       <jar href="application.jar"/>
     </resources>
     <application-desc/>
   </jnlp>
The first line with the TS tag contains the timestamp that the servlet will return for the JNLP file. The format of the timestamp is in ISO 8601 format. If the line is omitted, the timestamp of the file in the WAR file is used. The $$codebase string is modified by the JnlpDownloadServlet to be the actual URL for the request.

The web.xml file instructs the Web container to invoke the JNLPDownloadServlet for all requests to a JNLP file.

  <web-app>
     <servlet>
        <servlet-name>JnlpDownloadServlet</servlet-name>
        <servlet-class>com.sun.javaws.servlet.JnlpDownloadServlet</servlet-class>
     </servlet>
     <servlet-mapping>
        <servlet-name>JnlpDownloadServlet</servlet-name>
        <url-pattern>*.jnlp</url-pattern>
     </servlet-mapping>
  </web-app>
The JnlpDownloadServlet requires an XML parser in order to work. If your servlet container is running J2SE 1.4+, there is already a XML parser integrated in it. Otherwise please add jar files that implement a Java XML parser to the WEB-INF/lib directory. The reference implementation of the parser can be downloaded from http://java.sun.com/xml.

WAR file with use of version-download protocol

The example2.war contains:
   /index.html
   /app/version.xml
   /app/launch.jnlp
   /app/application.jar
   /app/lib__V2.1.jar
   /app/images/icon.gif
   /WEB-INF/web.xml
   /WEB-INF/lib/jnlp-servlet.jar
   /WEB-INF/lib/<jar files for XML parser> (not needed if the servlet container is running J2SE 1.4+)
The /app directory contains two JAR resources: application.jar and lib.jar. The lib.jar uses a naming convention to associate the version-id 2.1, i.e., the version information is associated on a per-file basis. The version of the application.jar file is described in the version.xml file, i.e., on a per-directory basis. The version.xml file looks like this:
   <jnlp-versions>
      <resource>
         <pattern>
           <name>application.jar</name>
            <version-id>1.1</version-id>
         </pattern>
         <file>application.jar</file>
      </resource>
   </jnlp-versions>
The JNLP file for the application looks like this:
   TS: 2002-04-23 19:21:05
   <?xml version="1.0" encoding="UTF-8"?>
   <jnlp codebase="$$codebase" href="$$name">
     <information>
         <title>Example 2</title>
         <vendor>Myself</vendor>
         <description>just an example</description>
         <icon href="images/icon.gif"/>
     </information>
     <resources>
       <j2se version="1.2+"/>
       <jar href="application.jar" version="1.1"/>
       <jar href="lib.jar" version="2.1"/>
     </resources>
     <application-desc/>
   </jnlp>
Finally, the web.xml file configures the JnlpDownloadServlet to be invoked for all requests into the /app directory.
  <web-app>
     <servlet>
        <servlet-name>JnlpDownloadServlet</servlet-name>
        <servlet-class>com.sun.javaws.servlet.JnlpDownloadServlet</servlet-class>
     </servlet>
     <servlet-mapping>
        <servlet-name>JnlpDownloadServlet</servlet-name>
        <url-pattern>/app/*</url-pattern>
     </servlet-mapping>
  </web-app>

Servlet Configuration

This section shows how to configure a WAR file to include the JnlpDownloadServlet and also how the servlet can be configured.

Adding the Servlet to a WAR archive

First the necessary servlet code must be made available to the servlet container. This is done by populating the WEB-INF/lib directory. The servlet is added to a WAR archive by including the jnlp-servlet.jar file in the WEB-INF/lib/ directory. The servlet needs access to an XML parser. If your servlet container is running J2SE 1.4+, there is already a XML parser integrated in it. Otherwise JAR files implementing a Java XML parser must also be added. They can be downloaded from http://java.sun.com/xml.

Once the servlet code is available, the Web container must be told to invoke the servlet on the right set of JNLP and JAR files, or on a given subdirectory. This is all configured in the WEB-INF/web.xml file inside the <web-app> tag:

   <web-app>
      ...
   </web-app>
The first thing to do is to tell the Web container how to invoke the servlet. This is done by using the <servlet> tag:
   <servlet>
      <servlet-name>JnlpDownloadServlet</servlet-name>
      <servlet-class>com.sun.javaws.servlet.JnlpDownloadServlet</servlet-class>
   </servlet>
Secondly, the Web container must be told when to invoke the servlet. This can be done in several ways. It can be invoked for certain directories or for files with certain extensions. For example, to invoke it for JNLP files, add the following to the web.xml file:
   <servlet-mapping>
     <servlet-name>JnlpDownloadServlet</servlet-name>
     <url-pattern>*.jnlp</url-pattern>
   </servlet-mapping>
Or for a given subdirectory:
   <servlet-mapping>
     <servlet-name>JnlpDownloadServlet</servlet-name>
     <url-pattern>/app/*</url-pattern>
   </servlet-mapping>

See also example1 and example2 for examples on how to configure the servlet.

Logging

The servlet has built-in logging capabilities to monitor its behavior. Logging messages are generated in 4 different categories:
FATAL
A malfunction or internal error happened inside the servlet.
WARNING
An error processing some of the information in the WAR file, e.g., parsing the version.xml file.
INFORMATIONAL
Logging all requests and replies, re-scanning of directories, etc.
DEBUG
Detailed internal information about how a request is processed.
The logging output is controlled by two servlet initialization parameters, logLevel and logPath. The log level can be set to either NONE, FATAL, WARNING, INFORMATIONAL, or DEBUG. The log path specifies a file where the output will be written to. If no path is specified, logging is done to the standard log for servlets (using the ServletContext.log method). For example:
 <servlet>
    <servlet-name>
      JnlpDownloadServlet
    </servlet-name>
    <servlet-class>
      com.sun.javaws.servlet.JnlpDownloadServlet
    </servlet-class>

    <init-param>
      <param-name>
        logLevel
      </param-name>

      <param-value>
        DEBUG
      </param-value>
    </init-param>

    <init-param>
      <param-name>
        logPath
      </param-name>

      <param-value>
        /logs/jnlpdownloadservlet.log
      </param-value>
    </init-param>

  </servlet>

Configuring file extensions and MIME types

The servlet treats JNLP and JAR files specially. JNLP files will be macro-expanded as described in a section below. A version-based request for a JAR file might result in the generation for an incremental update. The servlet uses extensions to determine if a file is a JNLP or JAR file. The default extension of JNLP files is .jnlp and for JAR files is .jar. These default extensions can be overwritten by the initialization parameters: jnlp-extension and jar-extension. For example:
    <init-param>
      <param-name>
        jnlp-extension
      </param-name>

      <param-value>
        .xjnlp
      </param-value>
    </init-param>
The MIME type that is returned for a file is also based on its extension. The MIME type is looked up in the configuration files for the Web container and the WAR file. If no mapping is specified, the default MIME types are shown below:
     Extension      Default MIME type
     -------------------------------------------
       .jnlp        application/x-java-jnlp-file
       .jar         application/x-java-archive
       .jardiff     application/x-java-archive-diff
A mapping can be overwritten by using the <mime-type> element in the web.xml file. For example:
  <web-app>
     ...
     <mime-mapping>
        <extension>jnlp</extension>
        <mime-type>text/ascii</mime-type>
     </mime-mapping>
     ...
  </web-app>

Specifying Resources

Application resources such as images, JAR files, and JNLP files are stored in the WAR file. The WAR file itself is a hierarchical directory structure, and the location of a resource inside the WAR file determines what URL will be used to look it up.

Assume that the WAR file (or servlet) has been configured so it handles all URL requests that starts with http://www.mytool.com/tool/. If the following requests is made: http://www.mytool.com/tool/app/launch.jnlp. Then the JnlpDownloadServlet will look for the launch.jnlp resource in the app/ directory in the WAR file.

No version information

A resource that has no associated version information, such as a JNLP file for an application, is simply just added to the WAR file. For example, given the above example, then the WAR file should included the following file:
    /app/launch.jnlp
In general, the timestamp that will be returned for the file is the last-modified timestamp that the file has in the WAR file. The only exception is for JNLP files where it can be explicitly specified in the JNLP file (see below).

Version information and more

The version-based and extension-based download protocols in the JNLP specification allows a resource to be looked up based on version-id, operating system, system architecture, and locale. The JnlpDownloadServlet provides two mechanisms for associating this information with a resource. It can be done on a per-file basis, using a naming convention, or by a per-directory basis, using a configuration file. Both methods can be used for the same directory.

The following information can be associated with a resource:

  • A path to the resource, e.g., /app
  • A name for the resource, e.g., launch.jnlp
  • A version-id, e.g., 1.1.0
  • A list of supported operations systems, e.g., SunOS Linux
  • A list of supported architectures, e.g., x86
  • A list of supported locales, e.g., da da_DK
  • A flag indicating if the version-id is a product version or a platform version (only used for JRE downloading)

The path is specified by the location of the resource in the WAR archive. The rest of the information is either specified by the use of a naming convention or in the version.xml file.

Resource Naming

The file naming convention is used if a double underscore (__) marker is found in the filename. The filename is parsed according to the BNF notation shown below:
    file    ::= name __ options . ext
    options ::= option ( __ options ) *
    option  ::= V version-id |
                O os |
                    A arch |
                    L locale
Only one version-id can be specified per file. However, multiple os, arch, and locale fields can be specified. For example:
    application__V1.2__Len_US__Len.jar
will mean that the resource application.jar has a version-id of 1.2, and the following associated locales: en_US and en.

The version.xml file

In each directory, a version.xml file can be placed to describe the additional properties, such as a version-id, for files in that particular directory. This is an alternative to the file naming convention.

For example, placing the file application-1_2-us.jar in a directory, along with a version.xml with the following content:

       <jnlp-versions>
          <resource>
             <pattern>
                <name>application.jar</name>
                <version-id>1.2</version-id>
                <locale>en_US</locale>
                <locale>en</locale>
             </pattern>
             <file>application-1_2-us.jar</file>
         </resource>
       </jnlp-versions>
will be the same as having placed the file application__V1.2__Len_US__Len.jar in the directory.

A resource can also be specified with a platform version-id in the version.xml file. Such a resource is used to match a particular platform request for a JRE. A resource with a platform version-id is specified using the <platform> element. For example:

      <platform>
             <pattern>
                <name>JRE</name>
                <version-id>1.3</version-id>
                <locale>en_US</locale>
                <locale>en</locale>
             </pattern>
             <file>j2re-1_3.0-us.jnlp</file>
             <product-version-id>1.3.0</product-version-id>
         </platform>
Platform version requests are generated internally by Java Web Start, when an application has requested a version of the Java 2 platform that is currently not installed on the local system.

The complete document type definition (DTD) for the version.xml is shown in the following:

   <!ELEMENT jnlp-versions <resource*, platform*)>
   <!ELEMENT resource (pattern, file)>
   <!ELEMENT platform (pattern, file, product-version-id)>
   <!ELEMENT pattern (name, version-id, os*, arch*, locale*)>
   <!ELEMENT name (#PCDATA)>
   <!ELEMENT version-id (#PCDATA)>
   <!ELEMENT os (#PCDATA)>
   <!ELEMENT arch (#PCDATA)>
   <!ELEMENT locale (#PCDATA)>
   <!ELEMENT file (#PCDATA)>
   <!ELEMENT product-version-id (#PCDATA)>

Mapping Requests to Resources

The JNLP specification defines four different kinds of download requests that Java Web Start (or more generally, a JNLP Client) can make to a server when requesting a resource:
  • Basic Download Request: This is an ordinary URL request to a specific file. The Last-Modified field of the response is used to determine if an update is available on the server. The basic download request can be used for all resource types.
  • Version-based Download Request: This request type can be used for JAR files and images, i.e., the following elements will generate a version-based download request: <jar>, <nativelib>, and <icon>, when the version attribute is included.
  • Extension Download Request: This request type is an extension of the version-based request type and is generated by either the <j2se> or <extension> elements. In addition to the version information, it also contains information about operating system, system architecture, and locale.
  • Platform-version Download Request: This is simliar to the extension download request, but used to request a particular version of the Java SE Runtime Environment (JRE). This request is generated by Java Web Start, when a JNLP file has requested a particular version of the JRE that is not currently installed on the client system.

A request is initially processed by the JNLPDownloadServlet, and it extracts the following information from the request:

  • Path in WAR file,
  • Name of requested file
  • Version string (version-id parameter or platform-version-id parameter)
  • Current version-id (current-version-id parameter)
  • List of operation systems (os parameter)
  • List of architectures (arch parameter)
  • List of locales (locale parameter)

Consider example2, and assume that it is being hosted at http://www.mytool.com/tool2/. If the following requests is made: http://www.mytool.com/tool2/app/lib.jar&version-id=2.1. Then the path of the resource would be, app/, the name would be lib.jar, the version string would be 2.1, and the lists for os, architecture, and locales would be empty.

A request to a directory, e.g., http://www.mytool.com/tool2/app/, will get appended the default filename: launch.jnlp. Thus, it would be the same as http://www.mytool.com/tool2/app/launch.jnlp.

Handling a basic download request

A request for which no version-id is specified (neither version-id parameter or platform-version-id parameter is specified in the request) is handled as a basic download request.

The request is first checked to see if it contains a double underscore (__) or is a request to the version.xml file. If so, the request is rejected and a HTTP 404 error code is returned.

The JnlpDownloadServlet will then try to locate the resource with the given path and name in the WAR file, and if found return it. If the resource is not found, a HTTP 404 error code is returned for the request.

If a match is found and it is a JNLP file, then it is preprocessed as described below before returned.

Handling a version-based download request

The resource lookup for resources with a version-id is uniform across the version-based download protocol, the extension download protocol, and the platform-version download request.

First, the JnlpDownloadServlet will build a database of all the resources that are located in the WAR file directory that the URL request is accessing (based on the path in the request). The database is built by scanning the version.xml file (if present), and the list of files in the directory that is using the naming convention described above. The servlet caches the information internally. It only does a re-scan if the timestamp of the version.xml file is more recent than at the last scan. Thus, if you add a file using the naming convention, make sure to touch the version.xml file to force the servlet to do a re-scan.

Secondly, the servlet will scan through the entries in the database to find a match for the given request (the match rules are described below). For a non-platform request, first the resource entries in the version.xml file are scanned in the order they are specified, and then secondly the entries that are specified using the naming convention. For a platform-version request, the platform entries in the version.xml file is scanned in the order they are specified. If several entries matches the request, then the entry with the highest version-id is returned. If multiple matches is found with the same highest version-id, then the first one specified is returned.

The matching rules are as follows:

  1. The name of the resource must match the request
  2. The version-id of the resource must match the version string in the request
  3. For the os, arch, and locale lists the following rules are used:
    1. If an empty list is specified for the resource, then it is a match
    2. If a non-empty list is specified for the resource, then it is a match, if at least one of the values specified for the resource is a prefix of at least one of the values specified in the request.
The x-java-jnlp-version-id returned in the response is the version-id for the matching resource, except for a platform request where it is taken from the <product-version-id> field in the version.xml file.

If a match is found and it is a JNLP file, then it is preprocessed as described below before returned.

Automatic JARDiff generation

The servlet will automatically generate and return incremental updates to JAR files, if possible. If the current-version-id parameter is included in the request and the servlet can find both a match on the current-version-id and the requested version (given the above matching rules) and the request is for a JAR file (e.g., the target resource has the .jar extension), then a JARDiff file will be generated by the servlet. The JARDiff file is returned as long as its size is less than that of the requested version.

The JARDiff file is generated and stored in a temporary directory that is specific to the given Web container. The servlet locates the temporary working directory using the javax.servlet.context.tempdir context attribute.

Processing of JNLP files

The JnlpDownloadServlet will automatically macro-expand certain template values in a JNLP file and replace them with URLs that are specific to the current request. This will enable JNLP files to be written and deployed without containing hard-coded URLs.

Macro expansions

The servlet will automatically substitute certain fixed keys in the JNLP file (prefixed with $$) with URLs that are based on the current request. The keys are designed so location-independent WAR files can be created and deployed into a Web container.

The table below shows the 3 keys that the servlet will look for and substitute:

         Pattern       Value
         ----------------------------------------------------------------
         $$codebase    Complete URL for request, except name of JNLP file
     $$name        Name of the JNLP file
         $$context     Base URL for the Web Archive.
For example: Consider the example1 WAR file. Lets assume that it has been deployed at the following location: http://www.mytool.com/tool. Thus, a request to http://www.mytool.com/tool/app/launch.jnlp will return the JNLP file. The values of the macro-expanded keys would be:
      $$codebase = http://www.mytool.com/tool/app/
      $$name     = launch.jnlp
      $$context  = http://www.mytool.com/tool/

The servlet does not validate the format of the JNLP file nor that the XML is well-formed. The value substitution is purely textual.

Explicit Timestamps

An explicit timestamp can be included in a JNLP file to ensure that a consistent timestamp will be returned from the Web Server. This is especially useful if a JNLP file is replicated onto multiple Web servers that are serving the same URL in a round-robin or load-balancing fashion. Note that a similar method is not provided for JAR files. The version-based download protocol should be used instead.

An explicit timestamp is included in the JNLP if the first-line starts with TS:. If so, it is parsed accordingly to the ISO 8601 formatting of timestamps (see below). The first line is also removed from the contents.

See example1 and example2 above for sample JNLP files using the TS: element.

ISO 8601 Formatting

The general format of a timestamp is:
   YYYY-MM-DD hh:mm:ss
The dashes, colons, and seconds are optional:
   YYYYMMDDhhmm
The hh is in 24h notation. By default, the local time zone is used. A Universal Time (UTC) (also know as GMT time) can be specified by appending the capital letter Z to a time as in:
     23:59:59Z or 235959Z
The strings
     +hh:mm, +hhmm, or +hh
can be added to the time to indicate that the used local time zone is hh hours and mm minutes ahead of UTC. For time zones west of the zero meridian, which are behind UTC, the notation
     -hh:mm, -hhmm, or -hh
is used instead. For example, Central European Time (CET) is +0100 and U.S./Canadian Eastern Standard Time (EST) is -0500. The following strings all indicate the same point of time:
     12:00Z = 13:00+01:00 = 0700-0500

Copyright © 2002 Sun Microsystems, Inc. All Rights Reserved.


xbDetectBrowser.js

/* ***** BEGIN LICENSE BLOCK *****
 * Licensed under Version: MPL 1.1/GPL 2.0/LGPL 2.1
 * Full Terms at http://devedge.netscape.com/lib/js/license/mpl-tri-license.txt
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is Netscape code.
 *
 * The Initial Developer of the Original Code is
 * Netscape Corporation.
 * Portions created by the Initial Developer are Copyright (C) 2001
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s): Bob Clary
 *
 * ***** END LICENSE BLOCK ***** */

function xbDetectBrowser()
{
  var oldOnError = window.onerror;
  var element = null;

  window.onerror = null;

  // work around bug in xpcdom Mozilla 0.9.1
  window.saveNavigator = window.navigator;

  navigator.OS    = '';
  navigator.version  = parseFloat(navigator.appVersion);
  navigator.org    = '';
  navigator.family  = '';

  var platform;
  if (typeof(window.navigator.platform) != 'undefined')
  {
    platform = window.navigator.platform.toLowerCase();
    if (platform.indexOf('win') != -1)
      navigator.OS = 'win';
    else if (platform.indexOf('mac') != -1)
      navigator.OS = 'mac';
    else if (platform.indexOf('unix') != -1 || platform.indexOf('linux') != -1 || platform.indexOf('sun') != -1)
      navigator.OS = 'nix';
  }

  var i = 0;
  var ua = window.navigator.userAgent.toLowerCase();

  if (ua.indexOf('opera') != -1)
  {
    i = ua.indexOf('opera');
    navigator.family  = 'opera';
    navigator.org    = 'opera';
    navigator.version  = parseFloat('0' + ua.substr(i+6), 10);
  }
  else if ((i = ua.indexOf('msie')) != -1)
  {
    navigator.org    = 'microsoft';
    navigator.version  = parseFloat('0' + ua.substr(i+5), 10);

    if (navigator.version < 4)
      navigator.family = 'ie3';
    else
      navigator.family = 'ie4'
  }
  else if (ua.indexOf('gecko') != -1)
  {
    navigator.family = 'gecko';
    var rvStart = ua.indexOf('rv:');
    var rvEnd   = ua.indexOf(')', rvStart);
    var rv      = ua.substring(rvStart+3, rvEnd);
    var rvParts = rv.split('.');
    var rvValue = 0;
    var exp     = 1;

    for (var i = 0; i < rvParts.length; i++)
    {
      var val = parseInt(rvParts[i]);
      rvValue += val / exp;
      exp *= 100;
    }
    navigator.version = rvValue;

    if (ua.indexOf('netscape') != -1)
      navigator.org = 'netscape';
    else if (ua.indexOf('compuserve') != -1)
      navigator.org = 'compuserve';
    else
      navigator.org = 'mozilla';
  }
  else if ((ua.indexOf('mozilla') !=-1) && (ua.indexOf('spoofer')==-1) && (ua.indexOf('compatible') == -1) && (ua.indexOf('opera')==-1)&& (ua.indexOf('webtv')==-1) && (ua.indexOf('hotjava')==-1))
  {
    var is_major = parseFloat(navigator.appVersion);

    if (is_major < 4)
      navigator.version = is_major;
    else
    {
      i = ua.lastIndexOf('/')
      navigator.version = parseFloat('0' + ua.substr(i+1), 10);
    }
    navigator.org = 'netscape';
    navigator.family = 'nn' + parseInt(navigator.appVersion);
  }
  else if ((i = ua.indexOf('aol')) != -1 )
  {
    // aol
    navigator.family  = 'aol';
    navigator.org    = 'aol';
    navigator.version  = parseFloat('0' + ua.substr(i+4), 10);
  }
  else if ((i = ua.indexOf('hotjava')) != -1 )
  {
    // hotjava
    navigator.family  = 'hotjava';
    navigator.org    = 'sun';
    navigator.version  = parseFloat(navigator.appVersion);
  }

  window.onerror = oldOnError;
}

xbDetectBrowser();


Application Development Considerations

This chapter includes the following topics:

  • Introduction
  • Retrieving Resources from JAR files
  • Security and Code Signing
  • Signing JAR Files With a Test Certificate
  • How to Encode JNLP Files
  • Dynamic Download of HTTPS Certificates

Introduction

Developing applications for deployment with Java Web Start is generally the same as developing stand-alone applications for the Java(TM) Platform Standard Edition. For instance, the entry point for the application is the standard public static void main(String[] argv).

However, in order to support Web deployment—automatic download and launching of an application—and to ensure that an application can run in a secure sandbox, there are some additional considerations:

  • An application must be delivered as a set of JAR files.
  • All application resources, such as files and images must be stored in JAR files; and they must be referenced using the getResource mechanism in the Java(TM) Platform Standard Edition (see below).
  • If an application is written to run in a secure sandbox, it must follow these restrictions:
    • No access to local disk.
    • All JAR files must be downloaded from the same host.
    • Network connections are enabled only to the host from which the JAR files are downloaded.
    • No security manager can be installed.
    • No native libraries may be used.
    • Limited access to system properties. The application has read/write access to all system properties defined in the JNLP File, as well as read-only access to the same set of properties that an Applet has access to.
  • An application is allowed to use the System.exit call.
  • An application that needs unrestricted access to the system will need to be delivered in a set of signed JAR files. All entries in each JAR file must be signed.

Retrieving Resources from JAR files

Java Web Start only transfers JAR files from the Web server to the client machine. It determines where to store the JAR files on the local machine. Thus, an application cannot use disk-relative references to resources such as images and configuration files.

All application resources must be retrieved from the JAR files specified in the resources section of the JNLP file, or retrieved explicitly using an HTTP request to the Web server. Storing resources in JAR files is recommended, since they will be cached on the local machine by Java Web Start.

The following code example shows how to retrieve images from a JAR file:

   // Get current
  classloader
ClassLoader cl = this.getClass().getClassLoader();
// Create icons
Icon saveIcon  = new ImageIcon(cl.getResource("images/save.gif"));
Icon cutIcon   = new ImageIcon(cl.getResource("images/cut.gif"));
...

The example assumes that the following entries exist in one of the JAR files for the application:

images/save.gif
images/cut.gif

Security and Code Signing

Java Web Start addresses the security issues:

  • Protecting users against malicious code (intentional & unintentional) that may affect local files;
  • Protecting enterprises against code that may attempt to access or destroy data on networks.

Applications launched with Java Web Start are, by default, run in a restricted environment where they have limited access to local computing resources, such as storage devices and the local network. In this sandbox environment, Java Web Start can guarantee that a downloaded and potentially untrusted application cannot compromise the security of the local files or the network.

An additional security feature supported by Java Web Start is digital code signing. If an application being invoked is delivered in one or more signed JAR files, Java Web Start will verify that the contents of the JAR file have not been modified since they were signed. If verification of a digital signature fails, Java Web Start will not run the application, since it may have been compromised by a third-party.

The support for code signing is important for both users and for application service providers. This service makes it possible for users to verify that an application comes from a trusted source. Because the application service provider signs the code, both can be ensured that no other party can impersonate the application on the Web. A signed application that is trusted by the user can also request additional system privileges, such as access to a local disk.

Java Web Start presents a dialog displaying the application's origin, based on the signer's certificate, before the application is launched. This allows the user to make an informed decision about whether or not to grant additional privileges to the downloaded code.

By including the following settings in the JNLP file, an application can request full access to a client system if all its JAR files are signed :

<security>
   <all-permissions/>
</security>

The implementation of code signing in Java Web Start is based on the security API in the core Java(TM) Platform Standard Edition. The Java 2 SE JRE 1.4.2 supports code signing with the SHA1withDSA and MD5withRSA algorithms.

Developers sign code for use with Java Web Start in the same way as for Java Applets—by using the standard jarsigner tool from the Java(TM) Platform Standard Edition. The jarsigner tool documentation provides examples of how to sign code and create test certificates, and it discusses other issues related to signing.

Java Web Start also supports use of the Netscape signtool used with SDK/JRE 1.4.2. See the Netscape Web site for details: http://developer.netscape.com/software/signedobj/

Signing JAR Files With a Test Certificate

Here are the steps needed to sign a JAR file with a test certificate:

1. Make sure that you have an SDK 1.4.2 keytool and jarsigner in your path. These tools are located in the SDK bin directory.

2. Create a new key in a new keystore as follows:

keytool -genkey -keystore myKeystore -alias myself

You will get prompted for a information about the new key, such as password, name, etc. This will create the myKeystore file on disk.

3. Then create a self-signed test certificate as follows:

    keytool -selfcert -alias myself -keystore myKeystore

This will prompt for the password. Generating the certificate may take a few minutes.

4. Check to make sure that everything is okay. To list the contents of the keystore, use this command:

    keytool -list -keystore myKeystore

It should list something like:

Keystore type: jks
Keystore provider: SUN

Your keystore contains 1 entry:

myself, Tue Jan 23 19:29:32 PST 2001, keyEntry,
Certificate fingerprint (MD5):
C2:E9:BF:F9:D3:DF:4C:8F:3C:5F:22:9E:AF:0B:42:9D

5. Finally, sign the JAR file with the test certificate as follows:

    jarsigner -keystore myKeystore test.jar myself

Repeat this step with all of your JAR files.

Note that a self-signed test certificate should only be used for internal testing, since it does not guarantee the identity of the user and therefore cannot be trusted. A trust-worthy certificate can be obtained from a certificate authority, such as VeriSign or Thawte, and should be used when the application is put into production.

How to Encode JNLP Files

Beginning with Java Web Start version 1.2, JNLP files may be encoded in any character encoding supported by the Java(TM) Platform Standard Edition. (See the Java(TM) Platform Standard Edition documentation for a list of supported encodings.)

To encode a JNLP file, specify an encoding in the XML prolog of that file. For example, the following line indicates that the JNLP file will be encoded in UTF-16.

<?xml version="1.0" encoding="utf-16"?>

The XML prolog itself must be UTF-8-encoded.

Dynamic Download of HTTPS Certificates

Beginning with 1.4.2, Java Web Start dynamically imports certificates in much the same way as browsers do. In order to make this work, Java Web Start now sets its own https handler, using the java.protocol.handler.pkgs system properties, to initialize defaults for SSLSocketFactory and HostnameVerifier. It sets the defaults with HttpsURLConnection.setDefaultSSLSocketFactory and HttpsURLConnection.setDefaultHostnameVerifier.

If your application uses those two method, make sure they are called after the Java Web Start https handler is initialized, otherwise your custom handler will be replaced by the Java Web Start default handler. You can ensure that your own customized SSLSocketFactory and HostnameVerifiter are used by doing either of the following:

  1. Installing your own https handler, which will completely replace the Java Web Start https handler (for more information, see A New Era for Java Protocol Handlers);
  2. Calling HttpsURLConnection.setDefaultSSLSocketFactory or HttpsURLConnection.setDefaultHostnameVerifier only after the first https url object is created, which will execute the Java Web Start https handler initialization code first.

For information on creating a download servlet see the next chapter, JnlpDownloadServlet Guide.


Converting JNLP Files to Work With This Release

The JNLP file format has not changed between the 1.0 and this release.

If your JNLP file is compatible with a version of Java Web Start that is lower than 1.0, please note that the JNLP file format has changed significantly. Below is a list of the most common modifications that needs to be applied to a 0.4 JNLP file to make it compatible with Java Web Start 1.0 or higher:

  • Set spec attribute to 1.0.
  • Rename the unrestricted element to all-permissions.
  • Rename the jre element to j2se and move this element inside the resources element (i.e., make j2se a subelement of resources).

Converting JNLP files used with the 1.0-beta or 1.0-rc release only requires updating the spec attribute to "1.0".


Creating the Web Page That Lauches the Application

Creating the Web Page That Launches the Application

This chapter includes the following topics:
  • Introduction
  • Detecting if Java Web Start is installed on Netscape
  • Detecting if Java Web Start is installed on IE, and if so, the version number
  • Launching the application if Java Web Start is Installed—or providing a link for auto-install or general download page
  • Creating an auto-install page

Introduction

In order for an application to be launched from a web page via JNLP, the page must include a link to the JNLP file. E.g., to be able to launch application app.jnlp on a web site http://www.MySite.com, the page needs to include the following link:

<a href=http://www.MySite.com/app.jnlp>Launch the application</a>

It may be the case, however, that Java Web Start is not installed on the user's computer. Thus the page needs to include logic (scripts) to take account of this. In fact, the page should include logic for the following:

Detect if Java Web Start is installed

  • If so, launch the application.
  • If not, detect if user is running IE on Window.
    • If so, provide link to a page that can auto-install the JRE for Windows
    • If not, provide a link to the general download page for the JDK/JRE.

The scripts, and the HTML for the auto-install page, are discussed below.

Detecting if Java Web Start is installed on Netscape

Here is the first script that should be run on a web page for launching an application via JNLP:

<SCRIPT LANGUAGE="JavaScript">
var javawsInstalled = 0;
var javaws142Installed=0;
var javaws150Installed=0;
var javaws160Installed = 0;
isIE = "false";
if (navigator.mimeTypes && navigator.mimeTypes.length) {
   x = navigator.mimeTypes['application/x-java-jnlp-file'];
   if (x) {
      javawsInstalled = 1;
      javaws142Installed=1;
      javaws150Installed=1;
      javaws160Installed = 1;
  }
}
else {
   isIE = "true";
}
</SCRIPT>

This script looks at the navigator.mimeTypes object and the navigator.mimeTypes.length var to decide if the browser is Netscape or IE. If length is 0, it is assumed the browser is IE, as with IE the navigator.mimeTypes array is defined but always empty. If length is non-zero, then the browser is assumed to be Netscape and the JNLP MIME type is checked to see if it exists on Netscape. If so, javawsInstalled, javaws142Installed, javaws150Installed and javaws160Installed are all set to 1. With Netscape it is not possible to determine which particular version of Java Web Start is installed, so all four variables are set to 1.

Detecting if JavaWeb Start is installed on IE, and if so, the version

The above JavaScript should be followed by a VBScript that sets variables related to Internet Explorer browers:

<SCRIPT LANGUAGE="VBScript">
on error resume next
If isIE = "true" Then
  If Not(IsObject(CreateObject("JavaWebStart.isInstalled"))) Then
     javawsInstalled = 0
  Else
     javawsInstalled = 1
  End If
  If Not(IsObject(CreateObject("JavaWebStart.isInstalled.1.4.2.0"))) Then
     javaws142Installed = 0
  Else
     javaws142Installed = 1
  End If
  If Not(IsObject(CreateObject("JavaWebStart.isInstalled.1.5.0.0"))) Then
     javaws150Installed = 0
  Else
     javaws150Installed = 1
  End If
  If Not(IsObject(CreateObject("JavaWebStart.isInstalled.1.6.0.0"))) Then
     javaws160Installed = 0
  Else
     javaws160Installed = 1
  End If
End If
</SCRIPT>

This VBScript is executed if the variable isIE from the preceeding JavaScript is "true"; i.e., if the end-user's browser is Internet Explorer. This script instantiates the isInstalled COM object in JavaWebStart.dll, and this object determines four things:

  • whether the client machine has any version of Java Web Start installed;
  • whether the client machine has version 1.2 of Java Web Start installed;
  • whether the client machine has versions 1.4.2 of Java Web Start installed;
  • whether the client machine has versions 1.5.0 of Java Web Start installed.
  • whether the client machine has versions 1.6.0 of Java Web Start installed.

After the above two scripts have been executed, the variables javawsInstalled, javaws142Installed, javawsInstalled150 and javawsInstalled160 will be set to either 1 or 0, as follows:

Browser
javawsInstalled javaws142Installed javaws150Installed javaws160Installed
Internet Explorer | 1 if any version of Java Web Start is installed; 0 otherwise. | 1 if Java Web Start 1.4.2 is installed; 0 otherwise. | 1 if Java Web Start 1.5.0 is installed; 0 otherwise. | 1 if Java Web Start 1.6.0 is installed; 0 otherwise.
Netscape Navigator | 1 if any version of Java Web Start is installed; 0 otherwise. | 1 if any version of Java Web Start is installed; 0 otherwise. | 1 if any version of Java Web Start is installed; 0 otherwise. | 1 if any version of Java Web Start is installed; 0 otherwise.

Launching the application if Java Web Start is Installed—or providing a link for auto-install or general download page

An additional JavaScript can be used to decide whether to:

  • provide a link to the application's jnlp file (i.e., Java Web Start is installed);
  • initiate auto-download of JRE 6.0, which includes Java Web Start (i.e., Java Web Start is not installed and the user is running IE on Windows);
  • or provide a link to the general download page for the 6.0 JDK/JRE (i.e., Java Web Start is not installed and the user is not running IE on Windows).

The following JavaScript handles these scenarios:

<script language="JavaScript">
/* Note that the logic below always launches the JNLP application
 *if the browser is Gecko based. This is because it is not possible
 *to detect MIME type application/x-java-jnlp-file on Gecko-based browsers.
 */
if (javawsInstalled || (navigator.userAgent.indexOf("Gecko") !=-1)) {
    document.write("<a href=http://www.MySite.com/app.jnlp>Launch
        the application</a>");
} else {
    document.write("Click ");
    document.write("<a href=http://java.sun.com/PluginBrowserCheck?
        pass=http://www.MySite.com/download.html&
        fail=http://java.sun.com/javase/downloads/ea.jsp>here</a> ");
    document.write("to download and install JRE 5.0 and
        the application.");
}
</SCRIPT>

Notes:

  1. The script only uses javawsInstalled—not javaws142Installed or javaws150Installed or javaws160Installed.
  2. The line breaks following '?' and '&' are for readability purposes only; in an actual script there should be no breaks in the href string.

If javawsInstalled is 1, indicating that Java Web Start is already available on the client, then the script provides a link to the application's jnlp file. If Java Web Start is not installed on the client, the script instead provides a link to the PluginBrowserCheck program on the java.sun.com web site. PluginBrowserCheck checks whether the client uses Internet Explorer on a Microsoft Windows platform. If so, PluginBrowserCheck sends the user to the auto-install page http://www.MySite.com/download.html. (See the next section, Creating an auto-install page, for how to create an auto-install page for IE running on Windows.) If PluginBrowserCheck determines the user is not using Internet Explorer on Microsoft Windows, the user is redirected to the 6.0 JRE general download page on java.sun.com.

Creating an auto-install page

Note:

The.cab file in the codebase attribute below will not be available until the GA release of the 6.0 JDK/JRE.

For a complete list of JRE releases that can be autodownloaded via a .cab file, as mentioned below, see Autodownload Files (Windows Only).

The download.html file should be staged on the server side. It contains special OBJECT and PARAM tags that will download to the client an auto-installer for JRE 6.0 . Along with Java Web Start, an ActiveX control will be downloaded to the client. The ActiveX control will launch the application using the newly installed Java Web Start. Here is a sample download.html file:

<HTML>
<BODY>
<OBJECT codebase="http://java.sun.com/update/1.6.0/jinstall-1_6-windows-i586.cab#Version=6,0,0,0"
classid="clsid:5852F5ED-8BF4-11D4-A245-0080C6F74284" height=0 width=0>
<PARAM name="app" value="http://www.MySite.com/app.jnlp">
<PARAM name="back" value="true">
<!-- Alternate HTML for browsers which cannot instantiate the object -->
<A href="http://java.sun.com/javase/downloads/ea.jsp">
Download Java Web Start</A>
</OBJECT>
</BODY>
</HTML>

The OBJECT tag fetches a .cab file that contains an auto-installer for JRE 6.0.

The URL: http://java.sun.com/update/1.6.0/jinstall-1_6-windows-i586.cab will return the latest update release available for the Java SE 6 release.

The string: Version=6,0,0,0 will be used to compare with the wsdetect.dll version, which is registered with the CLSID above. If the local machine has the dll installed and the version is greater than or equal to the Version specified, we will just load the dll in the local machine. Otherwise it will download and install Java from the codebase specified.

The PARAM tags specify the location of the application's jnlp file so that it may be automatically launched after the JRE is installed on the client.

app: Once the Java Web Start Active-X control is installed/loaded, it will invoke Java Web Start to launch the application specified by this URL.

back: This controls the behavior of the browser after launching the application. It can remain on the current page (download.html in this case) or navigate back to the previous page.

For issues relating to application development see the next chapter, Application Development Considerations.


Java Web Start - Frequently Asked Questions

JavaTM Web Start version 6

Frequently Asked Questions (FAQ)

FAQ Update (March 2006)

  1. Where can I find the Web Start chat session transcripts from March, 2005?
  2. What are some troubleshooting hints for Web Start applications?
  3. What is the story on auto-downloading jres?
  4. How do you use the CD install feature?
  5. How do you use the new Enterprise Configuration features?

General Questions

  1. What is Java Web Start?
  2. Where do I get more information?
  3. Why should I use Java Web Start?
  4. How can I launch applications with Java Web Start?
  5. Does it matter how I launch an application?
  6. What are the system requirements for Java Web Start?
  7. What platforms does Java Web Start run on?
  8. What are the server requirements for Java Web Start?
  9. Is Java Web Start based on a standard?
  10. Can I implement my own Java Web Start?
  11. What are the supported browsers?
  12. Is there a comprehensive list of online resources for Java Web Start?
  13. Can I deploy any application with Java Web Start?
  14. Is Java Web Start a software distribution mechanism like Marimba and MS SMS?
  15. Is Java Web Start an application installer?
  16. What version of the Java platform does Java Web Start work with?
  17. How does Java Web Start relate to Java Plug-in Technology (applets)?

Technical Questions

  1. Do I need to change my application to work with Java Web Start?
  2. Is there a migration path from applets to applications?
  3. Is there a way to pass VM arguments to the Java Runtime?
  4. I don't want to rely on a server timestamp. How can I specify a versioned JAR and how can I get incremental updates of JARs?
  5. Are JAR files shared between applications?
  6. How can I provide my own splash screen?
  7. How can I save the application state on the local system?
  8. My application requires a specific version of the JRE. How do I specify this my JNLP file?
  9. Can I rely on Class-Path in the manifest file?
  10. Can I use Java Web Start even if my Application depends on or uses native code?
  11. How can I load resources within my application using Class.forName and ClassLoader.getSystemClassLoader?
  12. How can I launch Java Web Start from the command line?
  13. How do I use multiple JAR files signed by different certificates?
  14. How do I detect if Java Web Start is installed?
  15. Why does my browser shows JNLP file as plain text.
  16. Why does Java Web Start always reload JAR files from IIS server?
  17. Can I use Pack200 compression with the JnlpDownloadServlet?
  18. What is the best way to ensure only one instance of my app is run?
  19. When will properties set in the jnlp file get set?
  20. What causes the file not found message for the downloaded jnlp file?
  21. How can I use signed jars (such as JCE extensions) signed for other purposes?
  22. Why can't I use the Association feature on some linux platforms with Gnome?
  23. How do I set up my server to broadcast the jnlp mime type?
  24. How do I set up my server to use the JnlpDownloadServlet?
  25. How are Applications uniquely identified?
  26. How do I create multiple file-extension/mime-type associations with a JNLP application?
  27. Why does FindClass() sometimes fail when called from native code?

Security Questions

  1. How secure is Java Web Start?
  2. What is a secure sandbox?
  3. How is the Java Web Start secure sandbox more flexible than the applet sandbox?
  4. How can I enable my application to gain unrestricted access to the system?
  5. Is there support for encrypted download of JAR files?
  6. Can I use NTLM authentication with Java Web Start?
  7. Can I use HTTPS protocol with Java Web Start?
  8. Are there online resources to learn more about the security tools?

Known Bugs

  1. 4825415: Web Start desktop integration and security dialogs disappear in 1.4.2
  2. 4491398: Dependent DLL resource problem
  3. 5008460: Web Start fails if path contains spaces and TraceSecurity is turned on.
  4. 5074087: If related-content is specified w/o a title on Windows, application cannot start.
  5. 5074524: First jar of unsigned extension must be downloaded eagerly
  6. 5047548: Lazy downloading of parts with packages is broken
  7. 5074526: ExtenededService file APIs show security dialog even if app is signed
  8. 4925768: No support for system level shortcuts in Gnome.
  9. 5072969: Startup errors causing Web Start to appear to hang
  10. 5074530: Web Start not picking up the correct JRE.

March 2006 Updates:

Where can I find the Web Start chat session transcripts from March, 2005 ?

The chat session transcripts can be seen here.

What are some troubleshooting hints for Web Start applications?
See the notes on troubleshooting and debugging here

What is the story on auto-downloading jres?
See the notes on auto-download here

How do you use the CD install feature?
See the notes on the import feature and CD-Install here

How do you use the Enterprise Configuration features?
See the notes on enterprise configuration management here

General Questions

What is Java Web Start?

Java Web Start provides a platform-independent, secure, and robust deployment technology. It enables developers to deploy full-featured applications to end-users by making the applications available on a standard web server. With any web browser, end-users can launch the applications and be confident they always have the most-recent version.
Back to top

Where do I get more information?

Look at the online documentation for Java Web Start .

If you are a developer, go to the Developer's Guide for detailed technical information on how to deploy applications using Java Web Start.
Back to top

Why should I use Java Web Start?

It's an easy, robust, and secure way to deploy applications directly from the web. Developers can make applications readily available via the web. In addition, Java Web Start provides Java runtime environment (JRE) management capabilities, it's easy to set up, it's browser-independent, and it's an efficient way to deploy web application solutions.

Users can easily access applications much as they would a web page--without a separate installation step. From the desktop, users can access and use Java applications, using a richer and more responsive user interface than is available on a web page. And, once a Java Web Start based application is installed, users simply click to run the application whenever needed.

Users do not need to manually update applications because each time they launch an application, it is transparently updated from the web--so they always use the most recent version available.
Back to top

How can I launch applications with Java Web Start?

You initially launch a new application by clicking on a link from a web page.

If you use an application frequently, create a shortcut from your desktop or from the Start Menu by allowing Java Web Start to place an icon on your desktop. Java Web Start may ask if you would like to create
shortcuts or an entry in the Start Menu. If you say "yes," all future launches of the application can start without a browser.

Java Web Start also provides an Application Cache Viewer which you can launch from the Java Control Panel. The Cache Viewer enables you to directly launch applications you have downloaded.

You can also launch an application from a command prompt by typing “javaws <jnlp_url>” where <jnlp_url is a url to the jnlp file of the application.
Back to top

Does it matter how I launch an application?

No, applications launch in the same manner no matter which method you use: from a web page, from the shortcut on the desktop, from the Start menu, or through the Java Application Cache Viewer.

Java Web Start always checks to see if a newer version of the application is available for use and automatically downloads it if so.

If the application you are using has not been digitally signed, Java Web Start will launch it in a restricted and secure execution environment. An application that is not signed, or one that you do not trust, will never be run with unrestricted access to your local system or network.
Back to top

What are the system requirements for Java Web Start?

Any client system that supports the Java version 1.2.2 or higher can use Java Web Start. Java Web Start works with virtually all browsers.
Back to top

What platforms does Java Web Start run on?

Sun Microsystems provides versions for Windows 98/NT/2000/XP/2003, Solaris Operating Environment (SPARC and Intel editions) and Linux/i486. Apple provides a version for their OS X release.
Back to top

What are the server requirements for Java Web Start?

Java Web Start uses HTTP for communication between the client and the server. You can use a standard web server to host an application. If you require additional services, such as version-based downloading, incremental updates, or pack200 compression for your applications, the web server will need to support servlets or Java Server Pages. A sample servlet implementing these features is provided in the samples directory of the JDK.
Back to top

Is Java Web Start based on a standard?

Yes. Java Web Start 1.5.0 is the product-quality reference implementation of Java Network Launching Protocol (JNLP) technology, which was developed through the Java Community Process. JNLP is specification number JSR 056. Other platform vendors are encouraged to port Java Web Start to their platform or implement the specification.

For more information, see the JNLP specification.
Back to top

Can I implement my own Java Web Start?

The underlying technology for Java Web Start, the Java Network Launching Protocol and API is being developed through the Java Community Process, so you can implement this protocol in any product. However additional licensing and terms must be met to implement any JCP technology including the JNLP technology.
Back to top

What are the supported browsers?

Java Web Start supports primarily Internet Explorer 4 or higher and Mozilla. However any browser can launch JNLP files if you have set the MIME-type association correctly. Java Web Start uses the browser's settings and may launch a browser to show a URL; this feature may not work with unsupported browsers.
Back to top

Is there a comprehensive list of online resources for Java Web Start?

  • Java Web Start documentation page: http://java.sun.com/j2se/1.5.0/docs/guide/javaws/index.html

  • Developer's Guide: http://java.sun.com/j2se/1.5.0/docs/guide/javaws/developersguide/contents.html

  • Java Web Start Discussion Forums: http://forum.java.sun.com/forum.jsp?forum=38

  • JSR-56: http://jcp.org/en/jsr/detail?id=56

Back to top

Can I deploy any application with Java Web Start?

Java Web Start is an application launcher for Java applications that are written to be web-deployed.

An application must be delivered in a set of JAR files and all application resources, such as images, configuration files, and native libraries must be included in the JAR files. The resources must be looked up using the method ClassLoader.getResource() or an equivalent method. Java Web Start only transfers JAR files from the web server to the client.

If an application is written to run in a restricted execution environment (sandbox), then access to disk is not permitted and the application may only connect to the host on which it resides.
Back to top

Is Java Web Start a software distribution mechanism like Marimba and MS SMS?

Java Web Start is an application launcher for Java applications. It allows easy distribution of full-featured applications based on the Java platform from a web server to a client machine with minimal user interaction.

The software distribution technology is only one aspect of Java Web Start. It also provides security, updates to the applications, ease-of-use for end users, and flexibility for developers when they create the applications.
Back to top

Is Java Web Start an application installer?

Java Web Start is an application launcher for Java applications that are written to be web-deployed. Java Web Start caches resources locally on the disk, but also provides a secure execution environment and a virtually transparent updating facility for applications. The end user does not need to manually initiate a software update because the application is updated each time it is used.
Back to top

What version of the Java platform does Java Web Start work with?

Java Web Start launches only applications written for the Java platform versions 1.2.2 and higher.
Back to top

How does Java Web Start relate to Java Plug-in Technology (applets)?

The two approaches are very similar. The key difference is in the user experience. If the Java application/applet needs to interact with a web page and be tightly bound to a web browser, then applets may be the solution. On the other hand, if browser independence is important, then Java Web Start is the deployment platform of choice. There are a number of other differences, but this is the fundamental difference.

Java Plug-in technology enables users to run Java applets inside a browser.

Java Web Start enables users to download full-featured applications with any browser. Once they have downloaded and launched an application, the browser can be closed, while the application continues working. The application does not depend on an open browser to function. The browser can be shut down or you can go to a different web page and the application will continue running.
Back to top

Technical Questions

Do I need to change my application to work with Java Web Start?

If your application is written to the Java 2 platform, and is delivered as a set of JAR files, there should be no need to revise your application. Make sure that your application retrieves all its resources (such as images and resource bundles) from a JAR file, since Java Web Start launches an application by invoking the public static void main(String[] args) method.

If your application needs unrestricted access to the system, (for example, network or disk access), you will need to sign your code.
Back to top

Is there a migration path from applets to applications?

Java Web Start is primarily designed for application deployment. You specify all requirements for your application in the JNLP file, and off you go. It does provide the ability to launch applets in much the same way as the traditional AppletViewer. The built-in AppletViewer provides an easy migration path for existing applets that want to take advantage of Java Web Start. However, it is not intended to be a full implementation of the Plug-In. The Plug-In is the primary launching vehicle for applets. The built-in AppletViewer in Java Web Start has limitations, for example, you cannot specify class files as resources and it does not accept policy files.
Back to top

Is there a way to pass VM arguments to the Java Runtime?

Java Web Start allows certain JVM flags to be set with the java-vm-args attribute of the j2se element (see Developer's Guide). Allowing the complete set could compromise security as well as limit portability across different platforms and implementations. You can set the maximum and initial heap size using the initial-heap-size and max-heap-size attributes of the j2se element, for example:

<j2se version="..." max-heap-size="100M"/>

Back to top

I don't want to rely on a server timestamp. How can I specify a versioned JAR and how can I get incremental updates of JARs?

Java Web Start supports versioned JARs and incremental updates. You can specify exact versions of the JAR files you want, instead of relying on timestamp information to determine if an update is available. Using version IDs also allows you to provide incremental updates from one version to another. See the JNLP Specification or the Developer's Guide for details.
Back to top

Are JAR files shared between applications?

Each JAR file that a JNLP Client (such as Java Web Start) downloads, is uniquely identified with a URL. If two JNLP files use the same URL, then the resource will only be downloaded once and shared. This is similar to the caching implementations used by web browsers.
Back to top

How can I provide my own splash screen?

Java Web Start needs to put up the initial splash screen while Java is loading. For subsequent access, you can specify an image file to use for the splash screen in the JNLP file with the tag

<icon href="mysplash.jpg" kind="splash"/>

where mysplash.jpg is the image file for your splash screen. The first time your application runs, it will use the standard splash screen. After that, it will use the image you provide.
Back to top

How can I save the application state on the local system?

A sandboxed application can store state using the PersistenceService API. This API is similar to cookies for HTML pages. Thus, it is a secure way to store persistent information on the client computer. For more information, see:

  • JNLP Specification

  • Java Web Start Developers Guide

Back to top

My application requires a specific version of the JRE. How do I specify this my JNLP file?

The tag <j2se version="versionNum"> specifies a platform version, where versionNum is 1.2, 1.3, 1.4, or 1.5.

You can request a specific product version by including a vendor URL in the href attribute. For Sun's JREs, the URL is http://java.sun.com/products/autodl/j2se For example, the following J2SE tag will request any Sun 1.3.1 implementation:

<j2se version="1.3.1*" href="http://java.sun.com/products/autodl/j2se"/>

You can see all the versions of the installed JREs in the Java tab of the Java Control Panel.
Back to top

Can I rely on Class-Path in the manifest file?

Java Web Start does not support the Class-Path entry in the manifest file. The Class-Path attribute is entirely file-centric, whereas Java Web Start and JNLP is web-centric, i.e., based on URLs. Thus, the two models do not merge easily.

Instead of relying on the Class-Path entry, you can list multiple JAR files in the JNLP file, for example:

<resources>
 <jar href="A.jar"/>
 <jar href="B.jar"/>
</resources>

In a JNLP file, you can factor out dependencies on a set of JAR files to another JNLP file using the <extension... > element. Thus, you can achieve the same kind of re-usability and ease of maintenance as you do with the Class-Path entry. This feature is described in the specification.

JNLP also implements a just-in-time downloading mechanism, similar to applets. For each resource in a JNLP file, you can specify which parts should be eagerly or lazily downloaded. Eagerly loaded resources are loaded before the application is launched, lazily loaded resources later. Default is eager download. Furthermore, the specification includes an API for which you can programatically query Java Web Start about which resources are available and request them to be downloaded. Thus, you can write download/network aware applications.

See the JNLP specification for more information.
Back to top

Can I use Java Web Start even if my application depends on or uses native code?

You can use Java Web Start to deploy Java Technology-based applications that depend on native code such as DLLs and SOs. Use the <nativelib ...> element to specify required native libraries. See the Developer's Guide for details.
Back to top

How can I load resources within my application using Class.forName and ClassLoader.getSystemClassLoader?

Java Web Start uses a user-level classloader to load all the application resources specified in the JNLP file. This classloader implements the security model and the downloading model defined by the JNLP specification. This is no different than how the AppletViewer or the Java Plug-In works.

This has the, unfortunate, side-effect that Class.forName will not find any resources that are defined in the JNLP file. The same is true for looking up resources and classes using the system class loader (ClassLoader.getSystemClassLoader).

To find application resources in Java Web Start, use the classloader that loaded your application, for example use the following call in the in the application;s main thread:

this.getClass().getClassLoader();

You can also use:

Thread.getCurrent().getContextClassLoader();
Back to top

How can I launch Java Web Start from the command line?

You can launch Java Web Start from the command line as follows:

javaws [options] your-app-JNLP-URL

where your-app-JNLP-URL is the location of your application's JNLP file. For example:

javaws http://java.sun.com/products/demos/swingset2.jnlp

For complete command line syntax see: the Developer's Guide
Back to top

How do I use multiple JAR files signed by different certificates?

The JNLP 1.0 specification requires all JAR files used in a JNLP file to be signed by the same certificate. This restriction avoids requiring the user to accept multiple certificates from the same source, and enables Java Web Start to know if the user has accepted all certificates used for an application.

However, Java Web Start can use multiple JAR files signed by different certificates, by using the component extension mechanism and multiple JNLP files. The only requirement is that the JAR files contain code from different packages. So, instead of the following:

<jar href="myjar1.jar"/>
<jar href="jh.jar"/>

Use the following:

<jar href="myjar1.jar"/>
<extension name="Java Help" href="help.jnlp"/>

Then add a help.jnlp file with the following contents:

<?xml version="1.0" encoding="utf-8"?>
 <jnlp spec="1.0+"
codebase="http://ws503" href="Help.jnlp">
 <information>
<title>JavaHelp</title>
<vendor>Sun Microsystems, Inc.</vendor>
 </information>
<resources>
<jar href="jh.jar"/>
</resources>
 <component-desc/>
</jnlp>

Back to top

How do I detect if Java Web Start is installed?

You can write a short JavaScript or VBScript to detect if Java Web Start is installed. See the Developer's Guide for details.
Back to top

Why does my browser shows JNLP file as plain text ?

This is most likely happening because your web server is not aware of the proper MIME type for JNLP files. Java Web Start requires only one change to your web server, that is creating an association between the file extension, typically jnlp, and the MIME type, application/x-java-jnlp-file. The steps for doing this vary depending upon the web server you are using.

Furthermore, if your corporation uses a proxy server, ensure that the update versions of the files are returned, by updating the time stamp of the resources on the web server such that the proxies will update their caches.
Back to top

Why does Java Web Start always reload JAR files from IIS server?

If a timestamp of the file on the IIS server is in the future IIS returns current-time as last-modified time. This makes Java Web Start to reload the JARs since time-stamp is always newer.
Back to top

Can I use Pack200 compression with the JnlpDownloadServlet?

Yes. The JnlpDownloadServlet distributed in the samples directory of the JDK now supports Pack200. If you deploy yourfile.jar along with yourfile.jar.pack.gz the packed file will be downloaded when the client is running Java Web Start 1.5.0 or later.
 Back to top

What is the best way to ensure only one instance of my application is run?

Use the SingleInstanceService to register as a singleton as soon as your application starts up. Re-invoking your application before it is registered as a singleton will cause another Java VM to start up.

Make sure to unregister before your program exits.
 Back to top

When will properties set in the jnlp file get set?

Normally, properties in the jnlp file will not be set until the first resource listed in that jnlp file is loaded. This insures the properties are set before any of your code is run, however some properties need to be set before other packages are loaded. Some properties are considered to be “secure” by Java Web Start, and, when found in the main jnlp file, will be passed as arguments to the invoking VM (-Dname=value).

The list of “secure” properties for this version can be found in the Developer's Guide
Back to top

What causes the file not found message for the downloaded jnlp file?

You click on a jnlp file, and Internet Explorer downloads the file, then launches Java Web Start, but you get the message: “Could not load file/URL specified: C:\Documents and Settings\...\application[1].jnlp”.

This problem is specific to Internet Explorer. Although this can be caused by a full cache, or turning off the cache in IE, it is usually caused by a no-cache directive coming from either the web server or the proxy server. IE will honor this directive, and not write the jnlp file to disk, so Java Web Start cannot find it. This frequently happens when upgrading a tomcat based server. Later versions set the no-cache directive by default for any resource that is within a security-constraint in web.xml. Try taking the relevant URI out of the security constraint in web.xml.
Back to top

How can I use signed jars (such as JCE extensions) signed for other purposes?

Beginning with Java Web Start 1.5.0, you can multiply sign the jar, adding code signing certificates over another existing certificate chain. With previous versions, you would either have to run the jar as a component extension w/o all-permissions, or strip the existing certificates before adding code signing certificates. (which in many cases rendered the package inoperable.)
 Back to top

Why can't I use the Association feature on some linux platforms with Gnome?

The association feature specifically requires libgnomevsf-2.so. If this library is not present, associations are not supported.
 Back to top

How do I set up my server to broadcast the jnlp mime type?

Each web server has a specific way in which to add MIME types. For example, for the Apache web server you must add the following line to the .mime.types configuration file:

application/x-java-jnlp-file JNLP

Check the documentation for the specifics of your web server.
Back to top

How do I set up my server to use the JnlpDownloadServlet?

See the Developers Guide section on configuring the servlet. The application need not be packaged in a Web Archive.
 Back to top

How are Applications uniquely identified?

An application is normally identified by it's href (the url to it's jnlp file.) If there is no href to the jnlp file, it is identified by the href to it's main jar file. If multiple applications share the same main jar file, they must contain an href, or they will be treated as the same app.

In version 1.5.0 and beyond, the Java Application Cache Viewer, will show all applications, even those w/o an href. The Viewer can only launch an application online, if it has an href. Without an href, it can launch offline if the jnlp file allows (contains <offline-allowed>)

In previous versions, the Application Manager will only show those applications with an href.

The same thing applies to creating shortcuts. In 1.5.0 you can only create a shortcut to launch online if there is an href, and can only create an offline shortcut if <offline-allowed> is specified. In 1.4.2, you can only create shortcuts to applications with an href.
 Back to top

How do I create multiple file-extension/mime-type associations with a JNLP application?

When creating multiple file-extension/mime-type associations with your JNLP application, it's recommended that you use multiple association tags. Also, both the file-extension and mime-type must be specified for each association tag. For example:

    <association extensions="aaa" mime-type="x-application/aaa"/>
    <association extensions="bbb" mime-type="x-application/bbb"/>
Back to top

Why does FindClass() sometimes fail when called from native code?

When jni code that may be called on the EventDispatch Thread calls findClass() then it may fail. For more information, see JNI documentation.

Security Questions

How secure is Java Web Start?

Security is a key consideration of the Java Web Start design. In Java Web Start all applications are launched by default in a secure "sandbox."
Back to top

What is a secure sandbox?

Applications in the secure sandbox have restricted access to local computing resources such as the disk and network.
Back to top

How is the Java Web Start secure sandbox more flexible than the applet sandbox?

All applications, by default, are run in a sandboxed environment, similar to the applet sandbox. However, Java Web Start provides a secure API that enables an application to import and export files from the local disk under the user's control. The API includes dialog boxes for operations such as saving a file and opening a file that are actually rendered by Java Web Start, and not by the application itself.

This sandbox design is similar to what you can do with HTML. A file input field in an HTML form enables a user to pick a file from the local disk and submit the name (excluding path) and content to the web server. Similarly, most browsers support the 'Save as...' option.
Back to top

How can I enable my application to gain unrestricted access to the system?

An application requesting unrestricted system access must be digitally signed. The first time a user launches such an application, a security dialog box will appear. Before running the application, Java Web Start will prompt the user to accept the digital certificate. After the user has accepted the certificate, subsequent invocations will not show the security dialog box.
Back to top

Is there support for encrypted download of JAR files?

Support for encrypting data transferred from the server to the client is very important. This is an important point on our issue list, and we will definitely make sure that HTTPS libraries will work with applications that are launched with Java Web Start. The HTTPS support might be in an optional package that you need to specify that your application depends on.

Encrypting the JAR files transferred from the server to the client may not be necessary. The reason is, even if the class files where encrypted on the wire, they will have to be decrypted on the client side and stored to disk, so the JVM will be able to load the classes. Thus, it could be fairly simple for a cracker to get around the encryption of the JAR files.

Instead, what is important for JAR files is that they can be signed, so the user can be absolutely sure that the application is from the vendor he expect it to be from. This is already supported.
Back to top

Can I use NTLM authentication with Java Web Start?

NTLM support was added to Java 1.4.2 on Windows platforms only. You can use NTLM authentication with Java Web Start in 1.4.2 and beyond. The JAuthenticator dialog may contain some misleading text when using NTLM with Java Web Start 1.4.2, but this is fixed in Java Web Start 1.5.0.
Back to top

Can I use HTTPS protocol with Java Web Start?

HTTPS support was added to Java in version 1.4. You can use use HTTPS protocol for Java Web Start resources starting in version 1.2, but may encounter one of several problems that were addressed in Java Web Start 1.4.2. It is recommended to use at least Java Web Start 1.4.2 if using HTTPS protocol.
Back to top

Are there other online resources to learn more about the security tools?

See the following:

  • Netscape object signing tools

  • Signing JAR Files

  • Java Deployment Guide security chapter

Back to top

Known Bugs

4825415: Web Start desktop integration and security dialogs disappear in 1.4.2

In version 1.4.2 only.

This is the problem where the desktop integration dialog fights for focus with a modal dialog displayed by the application, or the dialog is lost behind another application window.

This is fixed in versions 1.4.2_06 and 1.5
Back to top

4491398: Dependent DLL resource problem

In all versions.

If you have multiple native libraries, you must load each library with System.LoadLibrary, before loading any other that references it. This may become impossible if libraries have circular dependancies.
Back to top

5008460: Web Start fails if path contains spaces and TraceSecurity is turned on.

In versions 1.2 and 1.4.2

If TraceSecurity is turned on, you may get an exception on Windows platforms if there is a space in the path to the cache directory. If you have this problem turn off the TraceSecurity debugging switch (<property name=”javaws.debug.0” name=”-TraceSecurity” />.

This is fixed in version 1.5.
Back to top

5074087: If related-content is specified w/o a title on Windows, application cannot start.

In version 1.5.0.

In the specification of the jnlp file, it is legal to specify a related-content element without a title sub-element. However if this is done on windows platforms, an exception will be thrown when the shortcut to the related content is installed, and the program cannot be run. To work around this problem, always include a title for related-content elements.
Back to top

5074524: First jar of unsigned extension must be downloaded eagerly.

In all versions.

If a component extension is used, the first jar in it will be download eagerly, even if it is marked lazy.
Back to top

5047548: Lazy downloading of parts with packages is broken.

In all versions.

If you use the part and package mechanisms to declare what packages are included in what jar files, you should be able to skip downloading of any lazy jars so declared, when accessing a non-existent resource not in any of the declared packages. This does not work, and without Jar Indexing implemented, there is no way to prevent all jars from being downloaded.
Back to top

5074526: ExtenededService file APIs show security dialog even if app is signed.

In version 1.5.0.

When using the FileOpen Service, the security dialog will only show if the application does not have file access permissions. This is not true with the new ExtendedService OpenFile, and OpenFiles methods, the security dialog shows anyway.
Back to top

4925768: No support for system level shortcuts in Gnome.

In version 1.5.0.

When importing applications into the system cache with -shortcut, or running the Cache Viewer in system mode and creating shortcuts. The shortcuts should be created for all users. This works in Windows, but not on Unix with Gnome.
Back to top

5072969: Startup errors causing Web Start to appear to hang.

In all versions.

If an Exception or other Throwable is not caught by Java Web Start. The main run method may terminate without calling System.exit(). This makes application appear to hang (sometimes with DownloadProgress window showing with no progress).

In 1.4.2 this can happen when the Application or Java Web Start throws an Error (such as a NoSuchMethodError). You may need to turn on logging to a file and run with <property name=”javaws.debug.0” value=”+TraceIgnoredExceptions” /> to see the Error.

In 1.5.0 this is only known to happen if static code in the applications main class throws an Error (such as a NoSuchMethodError).
Back to top

5074530: Web Start not picking up the correct JRE.

In all versions.

When Java Web Start finds multiple JRE's that satisfy the requirements of the j2se elements version attribute in the jnlp file, it should always use the latest matching version.

In 1.4.2 it will usually just use the first matching version found.

In 1.5.0 it will usually use the latest version, but under some specific circumstances will still use an earlier one.
Back to top


Java Web Start 1.5.0 Developer Guide

Java Web Start Guide

Note: There are two ways to navigate this guide:

  • Search the guide
  • Select from the contents below:
 Related Documents

Overview

Java Web Start Technology
Where to Find Java Web Start Technology
 Using Java Web Start Software
Requirements

Setting up the Web Site

Introduction
 Basic Steps

Creating the Web Page That Launches the Application

Introduction
Detecting if Java Web Start is installed on Netscape
 Detecting if Java Web Start is installed on IE, and if so, the version number
 Launching the application if Java Web Start is Installed—or providing a link for auto-install or general download page
 Creating an auto-install page

Application Development Considerations

Introduction
Retrieving Resources from JAR files
 Security and Code Signing
 Signing JAR Files with a Test Certificate
 How to Encode JNLP Files
 Dynamic Download of HTTPS Certificates

JnlpDownloadServlet Guide

Introduction
Examples
Servlet Configuration
Specifying Resources
Mapping Requests to Resources
Processing of JNLP Files

JNLP File Syntax

Introduction
 The jnlp Element
The information Element
The security Element
The resources Element
The application-desc Element
The applet-desc Element

JNLP API Examples

Introduction
 Using a BasicService Service
Using a ClipboardService Service
Using a DownloadService Service
Using a FileOpenService Service
Using a FileSaveService Service
Using a PrintService Service
Using a PersistenceService Service
Using FileContents
Using a JNLPRandomAccessFile
Using a SingleInstanceService Service
Using an ExtendedService Service

The javaws Command Line Interface

Appendices:

FAQ
JNLP API (JavaDoc)


JNLP API Examples

This chapter includes the following topics:

  • Introduction
  • Using a BasicService Service
  • Using a ClipboardService Service
  • Using a DownloadService Service
  • Using a FileOpenService Service
  • Using a FileSaveService Service
  • Using a PrintService Service
  • Using a PersistenceService Service
  • Using FileContents
  • Using a JNLPRandomAccessFile
  • Using a SingleInstanceService Service
  • Using a ExtendedService Service

Introduction

The JNLP API is designed to provide additional information to the application that would otherwise not be available using the standard Java(TM) Platform Standard Edition API. The following code examples show how the following services can be used: BasicService, ClipboardService, DownloadService, FileOpenService, FileSaveService, PrintService, and PersistenceService.

The public classes and interfaces in the JNLP API are included in the jnlp.jar file. This JAR file must be included in the classpath when compiling source files that use the JNLP API. For example on Windows:

javac -classpath .;jnlp.jar *.java

The jnlp.jar file is included in the JNLP Developers Pack.

Using a BasicService Service

The javax.jnlp.BasicService service provides a set of methods for querying and interacting with the environment similar to what the AppletContext provides for a Java Applet.

The showURL method uses the JNLP API to direct the default browser on the platform to show the given URL. The method returns true if the request succeeds, otherwise false.

import javax.jnlp.*;
   ...

   // Method to show a URL
boolean showURL(URL url) {
try {
// Lookup the javax.jnlp.BasicService object
BasicService
  bs = (BasicService)ServiceManager.lookup("javax.jnlp.BasicService");
// Invoke the showDocument method
return bs.showDocument(url);
} catch(UnavailableServiceException
  ue) {
// Service is not supported
return false;
}
}

Using a ClipboardService Service

The javax.jnlp.ClipboardService service provides methods for accessing the shared system-wide clipboard, even for applications that are running in the restricted execution environment.

Java Web Start will warn the user of the potential security risk of letting an untrusted application access potentially confidential information stored in the clipboard, or overwriting contents stored in the clipboard.

import javax.jnlp;
    ...

    private ClipboardService cs;

    try {
        cs = (ClipboardService)ServiceManager.lookup
                 ("javax.jnlp.ClipboardService");
    } catch (UnavailableServiceException e) {
        cs = null;
    }

    if (cs != null) {
// set
  the system clipboard contents to a string selection
StringSelection ss = new StringSelection("Java
  Web Start!");
cs.setContents(ss);
// get
  the contents of the system clipboard and print them
Transferable tr = cs.getContents();
if (tr.isDataFlavorSupported(DataFlavor.stringFlavor))
  {
try
  {
String s = (String)tr.getTransferData(DataFlavor.stringFlavor);
System.out.println("Clipboard contents: " + s);
} catch
  (Exception e) {
e.printStackTrace();
}
}
}

Using a DownloadService Service

The javax.jnlp.DownloadService service allows an application to control how its own resources are cached.

The service allows an application to determine which of its resources are cached, to force resources to be cached, and to remove resources from the cache.

import javax.jnlp.*;
    ...

    DownloadService ds;

    try {
        ds = (DownloadService)ServiceManager.lookup("javax.jnlp.DownloadService");
    } catch (UnavailableServiceException e) {
        ds = null;
    }

    if (ds != null) {

        try {
            // determine if a particular resource is cached
            URL url =
                    new URL("http://java.sun.com/products/javawebstart/lib/draw.jar");
            boolean cached = ds.isResourceCached(url, "1.0");
            // remove the resource from the cache
            if (cached) {
                ds.removeResource(url, "1.0");
            }
            // reload the resource into the cache
            DownloadServiceListener dsl = ds.getDefaultProgressWindow();
            ds.loadResource(url, "1.0", dsl);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

Using a FileOpenService Service

The javax.jnlp.FileOpenService service provides methods for importing files from the local disk, even for applications that are running in the restricted execution environment.

This interface is designed to provide the same kind of of disk access to potentially untrusted Web-deployed applications that a Web developer has when using HTML. HTML forms support the inclusion of files by displaying a file open dialog.

import javax.jnlp.*;
    ...

    FileOpenService fos;

    try {
        fos = (FileOpenService)ServiceManager.lookup("javax.jnlp.FileOpenService");
    } catch (UnavailableServiceException e) {
        fos = null;
    }

    if (fos != null) {
        try {
            // ask user to select a file through this service
            FileContents fc = fos.openFileDialog(null, null);
            // ask user to select multiple files through this service
            FileContents[] fcs = fos.openMultiFileDialog(null, null);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

Using a FileSaveService Service

The javax.jnlp.FileSaveService service provides methods for exporting files to the local disk, even for applications that are running in the restricted execution environment.

This interface is designed to provide the same level of disk access to potentially untrusted Web-deployed applications that a Web browser provides for contents that it is displaying. Most browsers provide a Save As... dialog as part of their user interface.

import javax.jnlp.*;
    ...

    FileSaveService fss;
    FileOpenService fos;

    try {
        fos = (FileOpenService)ServiceManager.lookup("javax.jnlp.FileOpenService");
        fss = (FileSaveService)ServiceManager.lookup
                                   ("javax.jnlp.FileSaveService");
    } catch (UnavailableServiceException e) {
        fss = null;
        fos = null;
    }

    if (fss != null && fos != null) {
        try {
            // get a file with FileOpenService
            FileContents fc = fos.openFileDialog(null, null);
            // one way to save a file
            FileContents newfc = fss.saveFileDialog(null, null,
            fc.getInputStream(), "newFileName.txt");
            // another way to save a file
            FileContents newfc2 = fss.saveAsFileDialog(null, null, fc);

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

Also see Using FileContents.

Using a PrintService Service

The javax.jnlp.PrintService service provides methods for access to printing, even for applications that are running in the restricted execution environment.

Using this service, an application can submit a print job. Java Web Start will then show this request to the user and, if accepted, queue the request to the printer.

In Java Web Start 5.0, you can now directly use the Java Printing APIs, and Java Web Start will pop up a security dialog asking the user to grant PrintPermission if the application is running in a sandbox. There is no need to use the JNLP Printing APIs anymore. You can have full access to the Java Printing APIs in any JNLP application.

import javax.jnlp.*;
    ...

    PrintService ps;

    try {
        ps = (PrintService)ServiceManager.lookup("javax.jnlp.PrintService");
    } catch (UnavailableServiceException e) {
        ps = null;
    }

    if (ps != null) {
        try {

            // get the default PageFormat
            PageFormat pf = ps.getDefaultPage();

            // ask the user to customize the PageFormat
            PageFormat newPf = ps.showPageFormatDialog(pf);

            // print the document with the PageFormat above
            ps.print(new DocToPrint());

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    // Code to construct the Printable Document
    class DocToPrint implements Printable {
        public int print(Graphics g, PageFormat pageformat, int PageIndex){
            // code to generate what you want to print
        }
    }

Using a PersistenceService Service

The javax.jnlp.PersistenceService service provides methods for storing data locally on the client system, even for applications that are running in the restricted execution environment.

The service is designed to be somewhat similar to that which the cookie mechanism provides to HTML-based applications. Cookies allow a small amount of data to be stored locally on the client system. That data can be securely managed by the browser and can only be retrieved by HTML pages which originate from the same URL as the page that stored the data.

import javax.jnlp.*;
    ...

    PersistenceService ps;
    BasicService bs;

    try {
        ps = (PersistenceService)ServiceManager.lookup("javax.jnlp.PersistenceService");
        bs = (BasicService)ServiceManager.lookup("javax.jnlp.BasicService");
    } catch (UnavailableServiceException e) {
        ps = null;
        bs = null;
    }

    if (ps != null && bs != null) {

        try {
            // find all the muffins for our URL
            URL codebase = bs.getCodeBase();
            String [] muffins = ps.getNames(url);

            // get the attributes (tags) for each of these muffins.
            // update the server's copy of the data if any muffins
            // are dirty
            int [] tags = new int[muffins.length];
            URL [] muffinURLs = new URL[muffins.length];
            for (int i = 0; i < muffins.length; i++) {
                muffinURLs[i] = new URL(codebase.toString() + muffins[i]);
                tags[i] = ps.getTag(muffinURLs[i]);
                // update the server if anything is tagged DIRTY
                if (tags[i] == PersistenceService.DIRTY) {
                    doUpdateServer(muffinURLs[i]);
                }
            }

            // read in the contents of a muffin and then delete it
            FileContents fc = ps.get(muffinURLs[0]);
            long maxsize = fc.getMaxLength();
            byte [] buf = new byte[fc.getLength()];
            InputStream is = fc.getInputStream();
            long pos = 0;
            while((pos = is.read(buf, pos, buf.length - pos)) > 0) {
                // just loop
            }
            is.close();

            ps.delete(muffinURLs[0]);

            // re-create the muffin and repopulate its data
            ps.create(muffinURLs[0], maxsize);
            fc = ps.get(muffinURLs[0]);
            // don't append
            OutputStream os = fc.getOutputStream(false);
            os.write(buf);
            os.close();

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

   void doUpdateServer(URL url) {
        // update the server's copy of the persistent data
        // represented by the given URL
        ...
        ps.setTag(url, PersistenceService.CACHED);
   }

Using FileContents

javax.jnlp.FileContents objects encapsulate the name and contents of a file. An object of this class is used by the FileOpenService, FileSaveService and PersistenceService. Here is an example of how an instance of a FileContents can be used to read from and write to a file:

import javax.jnlp.*;
    ...

    FileOpenService fos;

    //Initialize fos (see Using a FileOpenService Service example)
    ...

    if (fos != null) {

        try {

            // get a FileContents object to work with from the
            // FileOpenService
            FileContents fc = fos.openFileDialog(null, null);

            // get the InputStream from the file and read a few bytes
            byte [] buf = new byte[fc.getLength()];
            InputStream is = fc.getInputStream();
            int pos = 0;
            while ((pos = is.read(buf, pos, buf.length - pos)) > 0) {
                // just loop
            }
            is.close();

            // get the OutputStream and write the file back out
            if (fc.canWrite()) {
               // don't append
               OutputStream os = fc.getOutputStream(false);
               os.write(buf);
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

Using a JNLPRandomAccessFile

Instances of javax.jnlp.JNLPRandomAccessFile support both reading and writing to a random access file. A random access file behaves like a large array of bytes stored in the file system. Here is an example of how an instance of a JNLPRandomAccessFile can be used to write to a random access file:

import javax.jnlp.*;
    ...

    FileOpenService fos;

    //Initialize fos (see Using a FileOpenService Service example)
    ...

    if (fos != null) {
        try {
           // ask the user to choose a file to open
           FileContents fc = fos.openFileDialog(null, null);

           // attempt to increase the maximum file length
           long grantedLength = fc.getLength();
           if (grantedLength + 1024 > fc.getMaxLength()) {
               // attempt to increase the maximum file size defined by
               // the client
               grantedLength = fc.setMaxLength(grantedLength + 1024);
           }

           // if we were able to increase the maximum allowable file size,
           // get a JNLPRandomAccessFile representation of the file, and
           // write to it
           if (fc.getMaxSize() > fc.getLength() && fc.canWrite()) {
               JNLPRandomAccessFile raf = fc.getRandomAccessFile("rw");
               raf.seek(raf.length() - 1);
               raf.writeUTF("Java Web Start!");
               raf.close();
           }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

Using a SingleInstanceService Service

The javax.jnlp.SingleInstanceService provides a set of methods for applications to register themselves as singletons, and to register listener(s) for handling arguments passed in from different instances of applications.

import javax.jnlp.*;
    ...

    SingleInstanceService sis;

    ...

    try {
        sis =
(SingleInstanceService)ServiceManager.lookup("javax.jnlp.SingleInstanceService");
    } catch (UnavailableServiceException e) { sis=null; }

    ...

    // Register the single instance listener at the start of your application

    SISListener sisL = new SISListener();
    sis.addSingleInstanceListener(sisL);

    ...

    // Remember to remove the listener before your application exits

    sis.removeSingleInstanceListener(sisL);
    System.exit(0);

    // Implement the SingleInstanceListener for your application

    class SISListener implements SingleInstanceListener {
        public void newActivation(String[] params) {

            // your code to handle the new arguments here

            ...
        }
    }

Using an ExtendedService Service

The javax.jnlp.ExtendedService provides additional support to the current JNLP API. It allows applications to open specific file(s) in the client's file system.

import javax.jnlp.*;
    ...

    ExtendedService es;

    ...

    try {
        es =
(ExtendedService)ServiceManager.lookup("javax.jnlp.ExtendedService");
    } catch (UnavailableServiceException e) { es=null; }

    ...

    // Open a specific file in the local machine

    File a = new File("c:\somefile.txt");

    ...

    // Java Web Start will pop up a dialog asking the user to grant permission
    // to read/write the file c:\somefile.txt

    FileContents fc_a = es.openFile(a);

    // You can now use the FileContents object to read/write the file

    ...

    // Open a specific set of files in the local machine

    File[2] fArray = new File[2];

    fArray[0] = a;
    fArray[1] = new File("c:\anotherFile.txt");

    // Java Web Start will pop up a dialog asking the user to grant permission
    // to read/write files in fArray

    FileContents[] fc_Array = es.OpenFiles(fArray);

    // You can now read/write the set of files in fc_Array using the
    // FileContents objects

    }

For detailed information on using javaws, see the javaws Command Line Interface.


JNLP File Syntax

This chapter covers the following topics:

  • Introduction
  • Example
  • JNLP Elements
    • jnlp Element
    • information Element
    • security Element
    • update Element
    • resources Element
    • application-desc Element
    • applet-desc Element
    • component-desc Element
    • installer-desc Element

Introduction

The format used in this release is that specified in the Java Network Launching Protocol & API Specification (JSR-56) version 6.0. This document describes the most commonly used elements of a JNLP file. For a complete description of the format, refer to the specification.

JNLP File Contents

Element

Attributes

Description

Since

Required

jnlp

This is the main xml element for a jnlp file. Everything is contained within the jnlp element.

1.0

yes

spec

The spec attribute can be 1.0, 1.5.0, or 6.0 or can use the wildcards such as 1.0+. It denoted the minimum version of the JNLP Specification that this jnlp file can work woth.

1.0

codebase

The codebase attribute specifies the base location for all relative URLs specified in href attributes in the JNLP file.

1.0

href

The href specifies the URL of the JNLP file itself.

1.0

version

The version of the application being launched, as well as the version of the JNLP file itself.

1.0

information

The information element contains other elements that describe the application and it's source.

1.0

yes

os

Specifies the operating system for which this information element should be considered.

1.5.0

arch

Specifies the architecture for which this information element should be considered

1.5.0

platform

Specifies the platform for which this information element should be considered.

1.5.0

locale

Specifies the locale for which this information element should be considered.

1.5.0

title

The title element specifies the title of the application.

1.0

yes

vendor

The vendor element specifies the provider of the application.

1.0

yes

homepage

The homepage of the application.

1.0

href

A URL pointing to where more information on this application can be found.

1.0

yes

description

A short statement describing the application.

1.0

kind

An indicator as to what type of description this is, legal values are one-line, short, and tooltip.

1.0

icon

Describes an icon that can be used to identify the application to the user.

1.0

href

A URL pointing to the icon file, may be in one of the following formats: gif, jpg, png, ico.

1.0

yes

kind

Indicates the suggested use of the icon, can be: default, selected, disabled, rollover, splash, or shortcut.

1.0

width

Can be used to indicate the resolution of the image.

1.0

height

Can be used to indicate the resolution of the image.

1.0

depth

Can be used to indicate the resolution of the image.

1.0

offline-allowed

Indicates that this application can operate when the client system is disconnected from the network.

1.0

shortcut

The shortcut element can be used to indicate an application's preferences for desktop integration.

1.5.0

online

Can be used to describe the application's preference for creating a shortcut to run online or offline.

1.5.0

desktop

Can be used to indicate an application's preference for putting a shortcut on the users desktop.

1.5.0

menu

Can be used to indicate an application's preference for putting a menu item in the users start menus.

1.5.0

sub-menu

Can be used to indicate an application's preference for where to place the menu item.

1.5.0

association

Can be used to hint to the JNLP client that it wishes to be registered with the operating system as the primary handler of certain extensions and a certain mime-type.

1.5.0

extensions

Contains a list of file extensions (separated by spaces) that the application requests it be registered to handle.

1.5.0

mime-type

Contains the mime-type that the application requests it be registered to handle.

1.5.0

related-content

Describes an additional piece of related content that may be integrated with the application.

1.5.0

href

A URL pointing to the related content.

1.5.0

yes

update

The update element is used to indicate the preferences for how application updates should be handled by the JNLP Client.

6.0

check

Indicates the preference for when the JNLP Client should check for updates. It can be always, timeout, or background..

6.0

policy

Indicates the preference for how the JNLP Client should handle an application update when it is known an update is available before the application is launched. It can be always, prompt-update, or prompt-run.

6.0

1.0

security

This element can be used to request enhanced permissions.

1.0

all-permissions

Requests that the application be run with all permissions.

1.0

j2ee-application-client-permissions

Requests that the application be run with a permission set that meets the security specifications of the J2EE Application Client environment.

1.0

1.0

resources

Describes all the resources that are needed for an application.

1.0

yes

os

Specifies the operating system for which the resources element should be considered.

1.0

arch

Specifies the architecture for which the resources element should be considered.

1.0

locale

Specifies that the locales for which the resources element should be considered.

java (or j2se)

Specifies what version(s) of Java to run the application with.

6.0 (java)

version

Describes an ordered list of version ranges to use.

1.0

yes

href

The URL denoting the supplier of this version of java, and where it may be downloaded from.

1.0

java-vm-args

Indicates an additional set of standard and non-standard virtual machine arguments that the application would prefer the JNLP Client to use when launching Java.

1.0

initial-heap-size

Indicates the initial size of the Java heap.

1.0

max-heap-size

Indicates the maximum size of the Java heap.

1.0

jar

Specifies a JAR file that is part of the application's classpath.

1.0

yes

href

The URL of the jar file.

1.0

yes

version

The requested version of the jar file. Requires using the version-based download protocol

1.0

main

Indicates if this jar contains the class containing the main method of the application.

1.0

download

Can be used to indicate this jar may be downloaded lazily, or when needed.

1.0

size

Indicates the downloadable size of the jar file in bytes.

1.0

part

Can be used to group resources together so they will be downloaded at the same time.

1.0

nativelib

Specifies a JAR file that contains native libraries in it's root directory.

1.0

href

The URL of the jar file.

1.0

yes

version

The requested version of the jar file. Requires using the version-based download protocol

1.0

download

Can be used to indicate this jar may be downloaded lazily.

1.0

size

Indicates the downloadable size of the jar file in bytes.

1.0

part

Can be used to group resources together so they will be downloaded at the same time.

1.0

extension

Contains pointer to an additional component-desc or installer-desc to be used with this application.

1.0

href

The URL to the additional extension jnlp file.

1.0

yes

version

The version of the additional extension jnlp file.

1.0

name

The name of the additional extension jnlp file

1.0

ext-download

Can be used in an extension element to denote the parts contained in a component-extension.

1.0

ext-part

Describes the name of a part that can be expected to be found in the extension.

1.0

yes

download

Can be used to indicate this extension may be downloaded eagerly or lazily.

1.0

part

Denotes the name of a part in this jnlp file to include the extension in.

1.0

package

Can be used to indicate to the JNLP Client which packages are implemented in which JAR files.

1.0

name

Package name contained in the jar files of the given part.

1.0

yes

part

Part name containing the jar files that include the given package name.

1.0

yes

recursive

Can be used to indicated that all package names beginning with the given name, can be found in the given part.

1.0

property

Defines a system property that will be available through the System.getProperty and System.getProperties methods.

1.0

name

Name of the system property.

1.0

yes

value

Value it will be set to.

1.0

yes

1.0

Note: A jnlp file must contain one of application-desc, applet-desc, component-desc, or installer-desc

1.0

yes

applicaation-desc

Denotes this is the jnlp file for an application.

1.0

main-class

The name of the class containing the public static void main(String[]) method of the application.

1.0

yes

argument

Each argument contains (in order) an additional argument to be passed to main.

1.0

applet-desc

Denotes this is the jnlp file for an applet.

1.0

main-class

This is the name of the main Applet class.

1.0

yes

documentbase

The document base for the Applet as a URL.

1.0

name

Name of the Applet.

1.0

yes

width

The width of the applet in pixels.

1.0

yes

height

The height of the applet in pixels

1.0

yes

param

A set of parameters that can be passed into the applet.

1.0

name

The name of this parameter

1.0

yes

value

The value of this parameter

1.0

yes

component-desc

Denotes this is the jnlp file for a component extension.

1.0

installer-desc

Denotes this is the jnlp file for an installed extension.

1.0

main-class

The name of the class containing the public static void main(String[]) method of the installer.

1.0

yes

The JNLP file is an XML document. The following shows a complete example of a JNLP file.

Example

<?xml version="1.0" encoding="utf-8"?>
<!-- JNLP File for SwingSet2 Demo Application -->
<jnlp
  spec="6.0+"
  codebase="http://my_company.com/jaws/apps"
  href="swingset2.jnlp">
  <information>
    <title>SwingSet2 Demo Application</title>
    <vendor>Sun Microsystems, Inc.</vendor>
    <homepage href="docs/help.html"/>
    <description>SwingSet2 Demo Application</description>
    <description kind="short">A demo of the capabilities
    of the Swing Graphical User Interface.</description>
    <icon href="images/swingset2.jpg"/>
    <icon kind="splash" href="images/splash.gif"/>
    <offline-allowed/>
    <association>
      <mime-type="application-x/swingset2-file"/>
      <extensions="swingset2"/>
    </association>
    <shortcut online="false">
      <desktop/>
      <menu submenu="My Corporation Apps"/>
    </shortcut>
  </information>
  <information os="linux">
    <title> SwingSet2 Demo on Linux </title>
    <homepage href="docs/linuxhelp.html">
  </information>
  <security>
      <all-permissions/>
  </security>
  <resources>
    <j2se version="1.6+" java-vm-args="-esa -Xnoclassgc"/>
    <jar href="lib/SwingSet2.jar"/>
  </resources>
  <application-desc main-class="SwingSet2"/>
</jnlp>

The example shows the basic outline of the document. The root element is jnlp, which has four subelements: information, security, resources, and application-desc. In addition, Java Web Start also supports launching applets by using the applet-desc element. The elements are described in more detail below.

JNLP Elements

jnlp Element

spec attribute: This attribute must be 1.0 or higher to work with this release. The default value is "1.0+". Thus, it can typically be omited. Note that this version supports both spec version 1.0, version 1.5, and version 6.0, whereas previous versions support only 1.0 and 1.5. A jnlp file specifying spec="6.0+" will work with this version, but not previous versions of Java Web Start.

codebase attribute: All relative URLs specified in href attributes in the JNLP file are using this URL as a base.

href attribute: This is a URL pointing to the location of the JNLP file itself.

information Element

title element: The name of the application.

vendor element: The name of the vendor of the application.

homepage element: Contains a single attribute, href, which is a URL locating the home page for the Application. It is used by the Java Application Cache Viewer to point the user to a Web page where more information about the application can be found.

description element: A short statement about the application. Description elements are optional. The kind attribute defines how the description should be used. It can have one of the following values:

  • one-line: If a reference to the application is going to appear on one row in a list or a table, this description will be used.
  • short: If a reference to the application is going to be displayed in a situation where there is room for a paragraph, this description is used.
  • tooltip: If a reference to the application is going to appear in a tooltip, this description is used.

Only one description element of each kind can be specified. A description element without a kind is used as a default value. Thus, if Java Web Start needs a description of kind short, and it is not specified in the JNLP file, then the text from the description without an attribute is used.

All descriptions contain plain text. No formatting, such as with HTML tags, is supported.

icon element: Contains an HTTP URL to an image file in either GIF or JPEG format. The icons are used to represents the application

  • during launch when Java Web Start presents the application to the user;
  • in the Java Application Cache Viewer;
  • in desktop shortcuts.

A 64x64 icon is shown during download; in the Java Application Cache Viewer and in desktop shortcuts a 32x32 icon is used. Java Web Start automatically resizes an icon to the appropriate size.

Optional width and height attributes can be used to indicate the size of the images.

The optional kind="splash" attribute may be used in an icon element to indicate that the image is to be used as a "splash" screen during the launch of an application. If the JNLP file does not contain an icon element with kind="splash" attribute, Java Web Start will construct a splash screen using other items from the information Element.

If the JNLP file does not contain any icon images, the splash image will consist of the application's title and vendor, as taken from the JNLP file.

The first time an application is launched following the addition or modification of the icon element in the JNLP file, the old splash image will still be displayed. The new splash image will appear on the second and subsequent launches of the application.

offline-allowed element: The optional offline-allowed element indicates if the application can be launched offline.

If offline-allowed is specified, then the application can be launched offline by the Java Application Cache Viewer, and shortcuts can be created which launch the application offline.

If an application is launched offline, it will not check for updates and the API call BasicService.isOffline() will return true.

The offline-allowed element also controls how Java Web Start checks for an update to an application. If the element is not specified—i.e., the application is required to be online to run—Java Web Start will always check for an updated version before launching the application. And if an update is found, the new application will be downloaded and launched. Thus, it is guaranteed that the user always runs the latest version of the application. The application, however, must be run online.

If offline-allowed is specified, Java Web Start will also check to see if an update is available. However, if the application is already downloaded the check will timeout after a few seconds, in which case the cached application will be launched instead. Given a reasonably fast server connection, the latest version of the application will usually be run, but it is not guaranteed. The application, however, can be run offline.

shortcut element: The optional shortcut element can be used to indicate an application's preferences for desktop integration. The shortcut element and it's sub-elements provide hints that the JNLP Client may or may not use. The shortcut element can contain the optional online attribute, and the two optional sub-elements, desktop and menu.

association element: The optional association element is a hint to the JNLP client that it wishes to be registered with the operating system as the primary handler of certain extensions and a certain mime-type. The association element must have the extensions and mime-type attributes.

related-content element: The optional related-content element describes an additional piece of related content, such as a readme file, help pages, or links to registration pages, as a hint to a JNLP Client. The application is asking that this content be included in its desktop integration. The related-content element has a mandatory href and title attribute. It can contain any of the following two sub-elements:

  • description element: A short description of the related content.
  • icon element: The icon can be used by the JNLP Client to identify the related content to the user.

security Element

Each application is, by default, run in a restricted execution environment, similar to the Applet sandbox. The security element can be used to request unrestricted access.

If the all-permissions element is specified, the application will have full access to the client machine and local network. If an application requests full access, then all JAR files must be signed. The user will be prompted to accept the certificate the first time the application is launched.

update Element

The update element is used to indicate the preferences for how application updates should be handled by Java Web Start.

The update element can contain the following two optional attributes:

check attribute: The check attribute indicates the preference for when the JNLP Client should check for updates, and can have one of the three values: "always", "timeout", and "background"

A value of "always" means to always check for updates before launching the application.

A value of "timeout" (default) means to check for updates until timeout before launching the application. If the update check is not completed before the timeout, the application is launched, and the update check will continue in the background.

A value of "background" means to launch the application while checking for updates in the background.

policy attribute: The policy attribute indicates the preference for how the JNLP Client should handle an application update when it is known an update is available before the application is launched, and can have one of the following three values: "always", "prompt-update", and "prompt-run"

A value of "always" (default) means to always download updates without any prompt.

A value of "prompt-update" means to ask the user if he/she wants to download and run the updated version, or launch the cached version.

A value of "prompt-run" means to ask the user if he/she wants to download and run the updated version, or cancel and abort runing the application.

For example:

<update check="always" policy="prompt-update">

resources Element

The resources element is used to specify all the resources, such as Java class files, native libraries, and system properties, that are part of the application. A resource definition can be restricted to a specific operating system, architecture, or locale using the os, arch, and locale attributes.

The resources element has six different possible subelements: jar, nativelib, j2se, property, package, and extension. The package and extension elements are not discussed in this developer's guide. See the Java Network Launching Protocol & API Specification (JSR-56) version 6.0 for details.

A jar element specifies a JAR file that is part of the application's classpath. For example:

  <jar href="myjar.jar"/>

The jar file will be loaded into the JVM using a ClassLoader object. The jar file will typically contain Java classes that contain the code for the particular application, but can also contain other resources, such as icons and configuration files, that are available through the getResource mechanism.

A nativelib element specifies a JAR file that contains native libraries. For example:

<nativelib href="lib/windows/corelib.jar"/>

The JNLP client must ensure that each file entry in the root directory of the JAR file (i.e., /) can be loaded into the running process using the System.loadLibrary method. Each entry must contain a platform-dependent shared library with the correct naming convention, e.g., *.dll on Windows or lib*.so on Solaris/Linux. The application is responsible for doing the actual call to System.loadLibrary.

Native libraries would typically be included in a resources element that is geared toward a particular operating system and architecture. For example:

    <resources os="SunOS" arch="sparc">
        <nativelib href="lib/solaris/corelibs.jar"/>
    </resource>

By default, jar and nativelib resources will be downloaded eagerly, i.e., they are downloaded and available locally to the JVM running the application before the application is launched. The jar and nativelib elements also allow a resource to be specified as lazy. This means the resource does not have to be downloaded onto the client system before the application is launched.

The download attribute is used to control whether a resource is downloaded eagerly or lazily. For example:

    <jar href="sound.jar" download="lazy"/>
<nativelib href="native-sound.jar"
    download="eager"/>

The j2se element specifies what Java(TM) Platform Standard Edition Runtime Environment (JRE) versions an application is supported on, as well as standard parameters to the Java Virtual Machine. If several JREs are specified, this indicates a prioritized list of the supported JREs, with the most preferred version first. For example:

       <j2se version="1.3" initial-heap-size="64m" max-heap-size="128m"/>
<j2se version="1.4.2+"
    href="http://java.sun.com/products/autodl/j2se" java-vm-args="-esa -Xnoclassgc"/>

The version attribute refers, by default, to a platform version (specification version) of the Java(TM) Platform Standard Edition. Currently defined platform versions are 1.2, 1.3, 1.4, 1.5 and 1.6. (A platform version will not normally contain a micro version number; e.g., 1.4.2.)

Exact product versions (implementation versions) may also be specified. by including the href attribute. For example, 1.3.1_07, 1.4.2, or 1.5.0-beta2 by Sun Microsystems, Inc. For example,

<j2se version="1.4.2" href="http://java.sun.com/products/autodl/j2se"/

or

<j2se version="1.4.2_04" href="http://java.sun.com/products/autodl/j2se"/>

If a platform version is specified (i.e., no href attribute is provided), Java Web Start will not consider an installed non-FCS (i.e., milestone) JRE as a match. E.g., a request of the form

<j2se version="1.4+"/>

would not consider an installed 1.4.1-ea or 1.4.2-beta JRE as a match for the request. Starting with 1.3.0, a JRE from Sun Microsystems, Inc., is by convention a non-FCS (milestone) JRE if there is a dash (-) in the version string.

The java-vm-args attribute of the j2se element specifies a preferred set of virtual machine arguments to use when launching java.

<j2se version="1.4+" java-vm-args="-ea -Xincgc"/>

The following java-vm-args are supported by this version:

 -d32,							        /* use a 32-bit data model if available */
 -client,                      				        /* to select the client VM */
 -server,						        /* to select the server VM */
 -verbose,                    				        /* enable verbose output */
 -version,         		        		        /* print product version and exit */
 -showversion,					                /* print product version and continue */
 -help,                        					/* print this help message */
 -X,                           					/* print help on non-standard options */
 -ea,                          					/* enable assertions */
 -enableassertions,            					/* enable assertions */
 -da,                          					/* disable assertions */
 -disableassertions,           					/* disable assertions */
 -esa,                         					/* enable system assertions */
 -enablesystemassertions,      					/* enable system assertions */
 -dsa,                         					/* disable system assertione */
 -disablesystemassertions,     					/* disable system assertione */
 -Xmixed,                      					/* mixed mode execution (default) */
 -Xint,                        					/* interpreted mode execution only */
 -Xnoclassgc,                  					/* disable class garbage collection */
 -Xincgc,                      					/* enable incremental garbage collection */
 -Xbatch,                      					/* disable background compilation */
 -Xprof,                       					/* output cpu profiling data */
 -Xdebug,                      					/* enable remote debugging */
 -Xfuture,                     					/* enable strictest checks, anticipating future default */
 -Xrs,                         					/* reduce use of OS signals by Java/VM (see documentation) */
 -XX:+ForceTimeHighResolution, 					/* use high resolution timer */
 -XX:-ForceTimeHighResolution, 					/* use low resolution (default) */

Plus any argument starting with one of the following:

-ea,                          /* enable assertions for classes */
-enableassertions,            /* enable assertions for classes */
-da,                          /* disable assertions for classes */
-disableassertions,           /* disable assertions for classes */
-verbose,                     /* enable verbose output */
-Xms,                         /* set initial Java heap size */
-Xmx,                         /* set maximum Java heap size */
-Xss,                         /* set java thread stack size */
-XX:NewRatio,                 /* set Ratio of new/old gen sizes */
-XX:NewSize,                  /* set initial size of new generation */
-XX:MaxNewSize,               /* set max size of new generation */
-XX:PermSize,                 /* set initial size of permanent gen */
-XX:MaxPermSize,              /* set max size of permanent gen */
-XX:MaxHeapFreeRatio,         /* heap free percentage (default 70) */
-XX:MinHeapFreeRatio,         /* heap free percentage (default 40) */
-XX:UseSerialGC,              /* use serial garbage collection */
-XX:ThreadStackSize,          /* thread stack size (in KB) */
-XX:MaxInlineSize,            /* set max num of bytecodes to inline */
-XX:ReservedCodeCacheSize,    /* Reserved code cache size (bytes) */
-XX:MaxDirectMemorySize,

The property element defines a system property that will be available through the System.getProperty and System.setProperties methods. It has two required attributes: name and value. For example:

<property name="key" value="overwritten"/>

Properties set in the jnlp file will normally be set by Java Web Start after the VM is started but before the application is invoked. Some properties are considered "secure" properties and can be passed as -Dkey=value arguments on the java invocation command line.

The following properties are considered "secure" and will be passed to the VM in this way:

    sun.java2d.noddraw,
    javax.swing.defaultlf,
    javaws.cfg.jauthenticator,
    swing.useSystemFontSettings,
    swing.metalTheme,
    http.agent,
    http.keepAlive,
    sun.awt.noerasebackground,
    sun.java2d.opengl,
    sun.java2d.d3d,
    java.awt.syncLWRequests,
    java.awt.Window.locationByPlatform,
    sun.awt.erasebackgroundonresize,
    swing.noxp,
    swing.boldMetal,
    awt.useSystemAAFontSettings,
    sun.java2d.dpiaware,

For an untrusted application, system properties set in the JNLP file will only be set by Java Web Start if they are considered secure, or if the property name begins with "jnlp." or "javaws.".

application-desc Element

The application element indicates that the JNLP file is launching an application (as opposed to an applet). The application element has an optional attribute, main-class, which can be used to specify the name of the application's main class, i.e., the class that contains the public static void main(String argv[]) method where execution must begin.

The main-class attribute can be omitted if the first JAR file specified in the JNLP file contains a manifest file containing the main class.

Arguments can be specified to the application by including one or more nested argument elements. For example:

  <application-desc main-class="Main">
    <argument>arg1</argument>
    <argument>arg2</argument>
  </application-desc>

applet-desc Element

Java Web Start has support for launching Java applets. This support provides easy migration of existing code to Java Web Start.

An applet is launched using the applet-desc element instead of the application-desc element. For example:

  <applet-desc
      documentBase="http://..."
      name="TimePilot"
      main-class="TimePilot.TimePilotApp"
      width="527"
      height="428">
    <param name="key1" value="value1"/>
    <param name="key2" value="value2"/>
  </applet-desc>

The JAR files that make up the applet are described using the resources element as for applications. The documentBase must be provided explicitly since a JNLP file is not embedded in an HTML page. The rest of the attributes correspond to the respective HTML applet tag elements.

The main-class attribute is used instead of the code attribute. The main-class attribute is assigned the name of the Applet class (without the .class extension). This attribute can be omitted if the Applet class can be found from the Main-Class manifest entry in the main JAR file.

Note: Applets must be packaged in JAR files in order to work with Java Web Start.

component-desc Element

The component-desc element denotes that this jnlp file is not an application or an applet but an extension that can be used as a resource in an application, applet or another extension.

A component extension is typically used to factor out a set of resources that are shared between multiple applications or that have separate security needs.

installer-desc Element

The installer-desc element denotes that this jnlp file is an installer extension that defines an application that will be run only once, the first time this extension jnlp file is used in an application, applet or another extension.

An installer extension is typically used to install platform specific native code that requires a more complicated setup than simply loading a native library into the VM.


JnlpDownloadServlet Guide

Table of Contents

Introduction
Examples
Servlet Configuration
Specifying Resources
Mapping Requests to Resources
Processing of JNLP Files
Pack200 Support

Introduction

Java Web Start includes a servlet in the sample/jnlp directory of the JDK. It can be used on either a JNOP file and its associated resources packaged in a Web Archive (.war) file, or on an unarchived directory. The purpose of the servlet is to provide a simple and convenient packaging format for JNLP applications, so they can be easily deployed in a Web Container, such as Tomcat or a Java EE-compliant Application Server.

The download servlet supports the following features:

  • Automatic installation of the codebase URL into JNLP files, thus eliminating manual management of hard-coded URLs into JNLP files.
  • Explicit specification of the timestamp for a JNLP file, independent of the file-system timestamp.
  • Supports all download protocols defined in the JNLP specification v1.0.1. These include basic download protocol, version-based download protocol, and extension download protocol.
  • Version-based information is specified per file or per directory in the Web archive. Thus, no centralized file needs to be managed for the entire archive.
  • Automatic generation of JARDiff files
  • Pack200 support

The packaging support consists of one servlet: JnlpDownloadServlet. The servlet is packaged into the jnlp-servlet.jar file, which can be found in the SDK under samples/jnlp/servlet/.

Below are two examples of how to use the servlet followed by a detailed description of the functionality of the servlet.

Examples

The first example shows how an application can be packaged into a WAR file without using the version-based download. The JnlpDownloadServlet is used to insert the exact URL into the JNLP file at request time. The second example shows how to add support for version-based download as well.

WAR file without use of version-download protocol

The example1.war contains:

   /index.html
   /app/launch.jnlp
   /app/application.jar
   /app/images/icon.gif
   /WEB-INF/web.xml
   /WEB-INF/lib/jnlp-servlet.jar
   /WEB-INF/lib/<jar files for XML parser> (not needed if the servlet container is running J2SE 1.4+)

The JNLP file for the application would look like this:

   TS: 2002-04-23 19:21:05
   <?xml version="1.0" encoding="UTF-8"?>
   <jnlp codebase="$$codebase">
     <information>
         <title>Example 1</title>
         <vendor>Myself</vendor>
         <description>just an example</description>
         <icon href="images/icon.gif"/>
     </information>
     <resources>
       <j2se version="1.2+"/>
       <jar href="application.jar"/>
     </resources>
     <application-desc/>
   </jnlp>

The first line with the TS tag contains the timestamp that the servlet will return for the JNLP file. The format of the timestamp is in ISO 8601 format. If the line is omitted, the timestamp of the file in the WAR file is used. The $$codebase string is modified by the JnlpDownloadServlet to be the actual URL for the request.

The web.xml file instructs the Web container to invoke the JNLPDownloadServlet for all requests to a JNLP file.

  <web-app>
     <servlet>
        <servlet-name>JnlpDownloadServlet</servlet-name>
        <servlet-class>jnlp.sample.servlet.JnlpDownloadServlet</servlet-class>
     </servlet>
     <servlet-mapping>
        <servlet-name>JnlpDownloadServlet</servlet-name>
        <url-pattern>*.jnlp</url-pattern>
     </servlet-mapping>
  </web-app>

The JnlpDownloadServlet requires an XML parser in order to work. If your servlet container is running J2SE 1.4+, there is already a XML parser integrated in it. Otherwise please add jar files that implement a Java XML parser to the WEB-INF/lib directory. The reference implementation of the parser can be downloaded from http://java.sun.com/xml.

WAR file with use of version-download protocol

The example2.war contains:

   /index.html
   /app/version.xml
   /app/launch.jnlp
   /app/application.jar
   /app/lib__V2.1.jar
   /app/images/icon.gif
   /WEB-INF/web.xml
   /WEB-INF/lib/jnlp-servlet.jar
   /WEB-INF/lib/<jar files for XML parser> (not needed if the servlet container is running J2SE 1.4+)

The /app directory contains two JAR resources: application.jar and lib.jar. The lib.jar uses a naming convention to associate the version-id 2.1, i.e., the version information is associated on a per-file basis. The version of the application.jar file is described in the version.xml file, i.e., on a per-directory basis. The version.xml file looks like this:

   <jnlp-versions>
      <resource>
         <pattern>
           <name>application.jar</name>
            <version-id>1.1</version-id>
         </pattern>
         <file>application.jar</file>
      </resource>
   </jnlp-versions>

The JNLP file for the application looks like this:

   TS: 2002-04-23 19:21:05
   <?xml version="1.0" encoding="UTF-8"?>
   <jnlp codebase="$$codebase" href="$$name">
     <information>
         <title>Example 2</title>
         <vendor>Myself</vendor>
         <description>just an example</description>
         <icon href="images/icon.gif"/>
     </information>
     <resources>
       <j2se version="1.2+"/>
       <jar href="application.jar" version="1.1"/>
       <jar href="lib.jar" version="2.1"/>
     </resources>
     <application-desc/>
   </jnlp>

Finally, the web.xml file configures the JnlpDownloadServlet to be invoked for all requests into the /app directory.

  <web-app>
     <servlet>
        <servlet-name>JnlpDownloadServlet</servlet-name>
        <servlet-class>jnlp.sample.servlet.JnlpDownloadServlet</servlet-class>
     </servlet>
     <servlet-mapping>
        <servlet-name>JnlpDownloadServlet</servlet-name>
        <url-pattern>/app/*</url-pattern>
     </servlet-mapping>
  </web-app>

Servlet Configuration

This section shows how to configure a WAR file to include the JnlpDownloadServlet and also how the servlet can be configured.

Adding the Servlet to a WAR archive

First the necessary servlet code must be made available to the servlet container. This is done by populating the WEB-INF/lib directory. The servlet is added to a WAR archive by including the jnlp-servlet.jar file in the WEB-INF/lib/ directory. The servlet needs access to an XML parser. If your servlet container is running J2SE 1.4+, there is already a XML parser integrated in it. Otherwise JAR files implementing a Java XML parser must also be added. They can be downloaded from http://java.sun.com/xml.

Once the servlet code is available, the Web container must be told to invoke the servlet on the right set of JNLP and JAR files, or on a given subdirectory. This is all configured in the WEB-INF/web.xml file inside the <web-app> tag:

   <web-app>
      ...
   </web-app>

The first thing to do is to tell the Web container how to invoke the servlet. This is done by using the <servlet> tag:

   <servlet>
      <servlet-name>JnlpDownloadServlet</servlet-name>
      <servlet-class>jnlp.sample.servlet.JnlpDownloadServlet</servlet-class>
   </servlet>

Secondly, the Web container must be told when to invoke the servlet. This can be done in several ways. It can be invoked for certain directories or for files with certain extensions. For example, to invoke it for JNLP files, add the following to the web.xml file:

   <servlet-mapping>
     <servlet-name>JnlpDownloadServlet</servlet-name>
     <url-pattern>*.jnlp</url-pattern>
   </servlet-mapping>

Or for a given subdirectory:

   <servlet-mapping>
     <servlet-name>JnlpDownloadServlet</servlet-name>
     <url-pattern>/app/*</url-pattern>
   </servlet-mapping>

See also example1 and example2 for examples on how to configure the servlet.

Logging

The servlet has built-in logging capabilities to monitor its behavior. Logging messages are generated in 4 different categories:

FATAL
A malfunction or internal error happened inside the servlet.
WARNING
An error processing some of the information in the WAR file, e.g., parsing the version.xml file.
INFORMATIONAL
Logging all requests and replies, re-scanning of directories, etc.
DEBUG
Detailed internal information about how a request is processed.

The logging output is controlled by two servlet initialization parameters, logLevel and logPath. The log level can be set to either NONE, FATAL, WARNING, INFORMATIONAL, or DEBUG. The log path specifies a file where the output will be written to. If no path is specified, logging is done to the standard log for servlets (using the ServletContext.log method). For example:

 <servlet>
    <servlet-name>
      JnlpDownloadServlet
    </servlet-name>
    <servlet-class>
      jnlp.sample.servlet.JnlpDownloadServlet
    </servlet-class>

    <init-param>
      <param-name>
        logLevel
      </param-name>

      <param-value>
        DEBUG
      </param-value>
    </init-param>

    <init-param>
      <param-name>
        logPath
      </param-name>

      <param-value>
        /logs/jnlpdownloadservlet.log
      </param-value>
    </init-param>

  </servlet>

Configuring file extensions and MIME types

The servlet treats JNLP and JAR files specially. JNLP files will be macro-expanded as described in a section below. A version-based request for a JAR file might result in the generation for an incremental update. The servlet uses extensions to determine if a file is a JNLP or JAR file. The default extension of JNLP files is .jnlp and for JAR files is .jar. These default extensions can be overwritten by the initialization parameters: jnlp-extension and jar-extension. For example:

    <init-param>
      <param-name>
        jnlp-extension
      </param-name>

      <param-value>
        .xjnlp
      </param-value>
    </init-param>

The MIME type that is returned for a file is also based on its extension. The MIME type is looked up in the configuration files for the Web container and the WAR file. If no mapping is specified, the default MIME types are shown below:

     Extension      Default MIME type
     -------------------------------------------
       .jnlp        application/x-java-jnlp-file
       .jar         application/x-java-archive
       .jardiff     application/x-java-archive-diff

A mapping can be overwritten by using the <mime-type> element in the web.xml file. For example:

  <web-app>
     ...
     <mime-mapping>
        <extension>jnlp</extension>
        <mime-type>text/ascii</mime-type>
     </mime-mapping>
     ...
  </web-app>

Specifying Resources

Application resources such as images, JAR files, and JNLP files are stored in the WAR file. The WAR file itself is a hierarchical directory structure, and the location of a resource inside the WAR file determines what URL will be used to look it up.

Assume that the WAR file (or servlet) has been configured so it handles all URL requests that starts with http://www.mytool.com/tool/. If the following requests is made: http://www.mytool.com/tool/app/launch.jnlp. Then the JnlpDownloadServlet will look for the launch.jnlp resource in the app/ directory in the WAR file.

No version information

A resource that has no associated version information, such as a JNLP file for an application, is simply just added to the WAR file. For example, given the above example, then the WAR file should included the following file:

    /app/launch.jnlp

In general, the timestamp that will be returned for the file is the last-modified timestamp that the file has in the WAR file. The only exception is for JNLP files where it can be explicitly specified in the JNLP file (see below).

Version information and more

The version-based and extension-based download protocols in the JNLP specification allows a resource to be looked up based on version-id, operating system, system architecture, and locale. The JnlpDownloadServlet provides two mechanisms for associating this information with a resource. It can be done on a per-file basis, using a naming convention, or by a per-directory basis, using a configuration file. Both methods can be used for the same directory.

The following information can be associated with a resource:

  • A path to the resource, e.g., /app
  • A name for the resource, e.g., launch.jnlp
  • A version-id, e.g., 1.1.0
  • A list of supported operations systems, e.g., SunOS Linux
  • A list of supported architectures, e.g., x86
  • A list of supported locales, e.g., da da_DK
  • A flag indicating if the version-id is a product version or a platform version (only used for JRE downloading)

The path is specified by the location of the resource in the WAR archive. The rest of the information is either specified by the use of a naming convention or in the version.xml file.

Resource Naming

The file naming convention is used if a double underscore (__) marker is found in the filename. The filename is parsed according to the BNF notation shown below:

    file    ::= name __ options . ext
    options ::= option ( __ options ) *
    option  ::= V version-id |
                O os |
                    A arch |
                    L locale

Only one version-id can be specified per file. However, multiple os, arch, and locale fields can be specified. For example:

    application__V1.2__Len_US__Len.jar

will mean that the resource application.jar has a version-id of 1.2, and the following associated locales: en_US and en.

The version.xml file

In each directory, a version.xml file can be placed to describe the additional properties, such as a version-id, for files in that particular directory. This is an alternative to the file naming convention.

For example, placing the file application-1_2-us.jar in a directory, along with a version.xml with the following content:

       <jnlp-versions>
          <resource>
             <pattern>
                <name>application.jar</name>
                <version-id>1.2</version-id>
                <locale>en_US</locale>
                <locale>en</locale>
             </pattern>
             <file>application-1_2-us.jar</file>
         </resource>
       </jnlp-versions>

will be the same as having placed the file application__V1.2__Len_US__Len.jar in the directory.

A resource can also be specified with a platform version-id in the version.xml file. Such a resource is used to match a particular platform request for a JRE. A resource with a platform version-id is specified using the <platform> element. For example:

      <platform>
             <pattern>
                <name>JRE</name>
                <version-id>1.3</version-id>
                <locale>en_US</locale>
                <locale>en</locale>
             </pattern>
             <file>j2re-1_3.0-us.jnlp</file>
             <product-version-id>1.3.0</product-version-id>
         </platform>

Platform version requests are generated internally by Java Web Start, when an application has requested a version of the Java platform that is currently not installed on the local system.

The complete document type definition (DTD) for the version.xml is shown in the following:

   <!ELEMENT jnlp-versions <resource*, platform*)>
   <!ELEMENT resource (pattern, file)>
   <!ELEMENT platform (pattern, file, product-version-id)>
   <!ELEMENT pattern (name, version-id, os*, arch*, locale*)>
   <!ELEMENT name (#PCDATA)>
   <!ELEMENT version-id (#PCDATA)>
   <!ELEMENT os (#PCDATA)>
   <!ELEMENT arch (#PCDATA)>
   <!ELEMENT locale (#PCDATA)>
   <!ELEMENT file (#PCDATA)>
   <!ELEMENT product-version-id (#PCDATA)>

Mapping Requests to Resources

The JNLP specification defines four different kinds of download requests that Java Web Start (or more generally, a JNLP Client) can make to a server when requesting a resource:

  • Basic Download Request: This is an ordinary URL request to a specific file. The Last-Modified field of the response is used to determine if an update is available on the server. The basic download request can be used for all resource types.
  • Version-based Download Request: This request type can be used for JAR files and images, i.e., the following elements will generate a version-based download request: <jar>, <nativelib>, and <icon>, when the version attribute is included.
  • Extension Download Request: This request type is an extension of the version-based request type and is generated by either the <j2se> or <extension> elements. In addition to the version information, it also contains information about operating system, system architecture, and locale.
  • Platform-version Download Request: This is simliar to the extension download request, but used to request a particular version of the J2SE Runtime Environment (JRE). This request is generated by Java Web Start, when a JNLP file has requested a particular version of the JRE that is not currently installed on the client system.

A request is initially processed by the JNLPDownloadServlet, and it extracts the following information from the request:

  • Path in WAR file,
  • Name of requested file
  • Version string (version-id parameter or platform-version-id parameter)
  • Current version-id (current-version-id parameter)
  • List of operation systems (os parameter)
  • List of architectures (arch parameter)
  • List of locales (locale parameter)

Consider example2, and assume that it is being hosted at http://www.mytool.com/tool2/. If the following requests is made: http://www.mytool.com/tool2/app/lib.jar&version-id=2.1. Then the path of the resource would be, app/, the name would be lib.jar, the version string would be 2.1, and the lists for os, architecture, and locales would be empty.

A request to a directory, e.g., http://www.mytool.com/tool2/app/, will get appended the default filename: launch.jnlp. Thus, it would be the same as http://www.mytool.com/tool2/app/launch.jnlp.

Handling a basic download request

A request for which no version-id is specified (neither version-id parameter or platform-version-id parameter is specified in the request) is handled as a basic download request.

The request is first checked to see if it contains a double underscore (__) or is a request to the version.xml file. If so, the request is rejected and a HTTP 404 error code is returned.

The JnlpDownloadServlet will then try to locate the resource with the given path and name in the WAR file, and if found return it. If the resource is not found, a HTTP 404 error code is returned for the request.

If a match is found and it is a JNLP file, then it is preprocessed as described below before returned.

Handling a version-based download request

The resource lookup for resources with a version-id is uniform across the version-based download protocol, the extension download protocol, and the platform-version download request.

First, the JnlpDownloadServlet will build a database of all the resources that are located in the WAR file directory that the URL request is accessing (based on the path in the request). The database is built by scanning the version.xml file (if present), and the list of files in the directory that is using the naming convention described above. The servlet caches the information internally. It only does a re-scan if the timestamp of the version.xml file is more recent than at the last scan. Thus, if you add a file using the naming convention, make sure to touch the version.xml file to force the servlet to do a re-scan.

Secondly, the servlet will scan through the entries in the database to find a match for the given request (the match rules are described below). For a non-platform request, first the resource entries in the version.xml file are scanned in the order they are specified, and then secondly the entries that are specified using the naming convention. For a platform-version request, the platform entries in the version.xml file is scanned in the order they are specified. If several entries matches the request, then the entry with the highest version-id is returned. If multiple matches is found with the same highest version-id, then the first one specified is returned.

The matching rules are as follows:

  1. The name of the resource must match the request
  2. The version-id of the resource must match the version string in the request
  3. For the os, arch, and locale lists the following rules are used:
    1. If an empty list is specified for the resource, then it is a match
    2. If a non-empty list is specified for the resource, then it is a match, if at least one of the values specified for the resource is a prefix of at least one of the values specified in the request.

The x-java-jnlp-version-id returned in the response is the version-id for the matching resource, except for a platform request where it is taken from the <product-version-id> field in the version.xml file.

If a match is found and it is a JNLP file, then it is preprocessed as described below before returned.

Automatic JARDiff generation

The servlet will automatically generate and return incremental updates to JAR files, if possible. If the current-version-id parameter is included in the request and the servlet can find both a match on the current-version-id and the requested version (given the above matching rules) and the request is for a JAR file (e.g., the target resource has the .jar extension), then a JARDiff file will be generated by the servlet. The JARDiff file is returned as long as its size is less than that of the requested version.

The JARDiff file is generated and stored in a temporary directory that is specific to the given Web container. The servlet locates the temporary working directory using the javax.servlet.context.tempdir context attribute.

Processing of JNLP files

The JnlpDownloadServlet will automatically macro-expand certain template values in a JNLP file and replace them with URLs that are specific to the current request. This will enable JNLP files to be written and deployed without containing hard-coded URLs.

Macro expansions

The servlet will automatically substitute certain fixed keys in the JNLP file (prefixed with $$) with URLs that are based on the current request. The keys are designed so location-independent WAR files can be created and deployed into a Web container.

The table below shows the 4 keys that the servlet will look for and substitute:

         Pattern       Value
         ----------------------------------------------------------------
         $$codebase    Complete URL for request, except name of JNLP file
     $$name        Name of the JNLP file
         $$context     Base URL for the Web Archive
     $$site	       Web site address without the WAR context portion

For example: Consider the example1 WAR file. Lets assume that it has been deployed at the following location: http://www.mytool.com/tool. Thus, a request to http://www.mytool.com/tool/app/launch.jnlp will return the JNLP file. The values of the macro-expanded keys would be:

      $$codebase = http://www.mytool.com/tool/app/
      $$name     = launch.jnlp
      $$context  = http://www.mytool.com/tool/
      $$site     = http://www.mytool.com/

The servlet does not validate the format of the JNLP file nor that the XML is well-formed. The value substitution is purely textual.

Explicit Timestamps

An explicit timestamp can be included in a JNLP file to ensure that a consistent timestamp will be returned from the Web Server. This is especially useful if a JNLP file is replicated onto multiple Web servers that are serving the same URL in a round-robin or load-balancing fashion. Note that a similar method is not provided for JAR files. The version-based download protocol should be used instead.

An explicit timestamp is included in the JNLP if the first-line starts with TS:. If so, it is parsed accordingly to the ISO 8601 formatting of timestamps (see below). The first line is also removed from the contents.

See example1 and example2 above for sample JNLP files using the TS: element.

ISO 8601 Formatting

The general format of a timestamp is:

   YYYY-MM-DD hh:mm:ss

The dashes, colons, and seconds are optional:

   YYYYMMDDhhmm

The hh is in 24h notation. By default, the local time zone is used. A Universal Time (UTC) (also know as GMT time) can be specified by appending the capital letter Z to a time as in:

     23:59:59Z or 235959Z

The strings

     +hh:mm, +hhmm, or +hh

can be added to the time to indicate that the used local time zone is hh hours and mm minutes ahead of UTC. For time zones west of the zero meridian, which are behind UTC, the notation

     -hh:mm, -hhmm, or -hh

is used instead. For example, Central European Time (CET) is +0100 and U.S./Canadian Eastern Standard Time (EST) is -0500. The following strings all indicate the same point of time:

     12:00Z = 13:00+01:00 = 0700-0500

Pack200 Support

You can now host *.jar.pack.gz or *.jar.gz files together with your original *.jar files. If the client supports the pack200-gzip or gzip file formats, the servlet will return the compressed file if it is available on the server. Java Web Start 5.0 supports both compression formats. You must host both the original jar file and the pack file in the server, otherwise the servlet will not pick up the pack file. The pack file can be created with the pack200.exe command included in J2SE 5.0. For more information on the pack200 compression technology, please see Pack200 and Compression for Network Deployment.


Overview

Java Web Start Technology

Java Web Start is a helper application that gets associated with a Web browser. When a user clicks on a link that points to a special launch file (JNLP file), it causes the browser to launch Java Web Start, which then automatically downloads, caches, and runs the given Java Technology-based application. The entire process is typically completed without requiring any user interaction, except for the initial single click.

From a technology standpoint, Java Web Start has a number of key benefits that make it an attractive platform to use for deploying applications:

  • Java Web Start is built exclusively to launch applications written to the Java(TM) Platform Standard Edition. Thus, a single application can be made available on a Web server and then deployed on a wide variety of platforms, including Windows 98/NT/2000/ME/XP, Linux, and the SolarisTM Operating Environment. The Java platform has proven to be a very robust, productive, and expressive development platform, leading to a significant cost savings due to minimized development and testing costs.
  • Java Web Start supports multiple revisions of the Java(TM) Platform Standard Edition. Thus, an application can request a particular version of the platform it requires, such as Java SETM 1.5.0. Several applications can run at the same time on different platform revisions without causing conflicts, and Java Web Start can automatically download and install a revision of the platform if an application requests a version that is not installed on the client system.
  • Java Web Start allows applications to be launched independently of a Web browser. This can be used for off-line operation of an application, where launching through the browser is often inconvenient or impossible. The application can also be launched through desktop shortcuts, making launching the Web-deployed application similar to launching a native application.
  • Java Web Start takes advantage of the inherent security of the Java Platform. Applications are by default run in a protective environment (sandbox) with restricted access to local disk and network resources. It allows the user to safely run applications from sources that are not trusted.
  • Applications launched with Java Web Start are cached locally. Thus, an already-downloaded application is launched on par with a traditionally installed application.

The technology underlying Java Web Start is the Java TM Network Launching Protocol & API (JNLP). This technology was developed via the Java Community Process (JCP). Java Web Start is the reference implementation (RI) for the JNLP specification. The JNLP technology defines, among other things, a standard file format that describes how to launch an application called a JNLP file.

Security

Java Web Start is built on top of the Java(TM) SE platform, which provides a comprehensive security architecture. Applications launched with Java Web Start will, by default, run in a restricted environment ("sandbox") with limited access to files and network. Thus, launching applications using Java Web Start maintains system security and integrity.

An application can request unrestricted access to your system. In this case, Java Web Start will display a Security Warning dialog when the application is launched for the first time. The security warning will show information about the vendor who developed the application. If you choose to trust the vendor, then the application will be launched. The information about the origin of the application is based on digital code signing.

Where to find Java Web Start

Java Web Start is included in the Java Runtime Environment available at http://java.sun.com. The JNLP specification can be found at JSR 56: Java Network Launching Protocol and API.

Using Java Web Start Software

Java Web Start allows you to launch Java-technology-based applications directly from the Web. An application can be launched in three different ways:

  • From a Web browser by clicking on a link.
  • From desktop icons or the Start Menu.
  • From the Java Cache Viewer

Regardless of which way is used, Java Web Start will connect back to the Web server each time an application is launched to check whether an updated version of the application is available.

Launching from a Web browser

Point your web browser to a page with a link to a jnlp application, and click on that link.

Some applications require extra privileges, such as access to your local hard disk. For these applications, a security dialog will pop up with information about the origin of the application based on who digitally signed the code. The application will run only if you decide to trust the vendor.

That is really all there is to using Java Web Start, but how does it work? The HTML links that launch the applications are, in fact, standard HTML links. However, instead of pointing to another Web page, they link to a special configuration file called a JNLP file. The Web browser examines the file extension and/or the MIME type of the file, and sees that it belongs to Java Web Start. It then launches Java Web Start with the downloaded JNLP file as an argument. Java Web Start proceeds with downloading, caching, and running the application as directed by the JNLP file.

Launching from desktop icons and the Start Menu (Microsoft Windows and Unix running GNOME 2.0+)

Java Web Start technology can automatically create shortcuts for your application on the desktop and in the Start Menu for Web-deployed applications developed with Java technology. You can use the Java Control Panel to control the shortcut settings. Shortcuts can also be added by using the Java Web Start Cache Viewer, using the install shortcut menu item.

Using Java Web Start Software Behind a Proxy Server/Firewall

Java Web Start software must be configured with the correct proxy settings in order to launch applications from outside your firewall. Java Web Start software will automatically try to detect the proxy settings from the default browser on your system (Internet Explorer or NetscapeTM browsers on Microsoft Windows, and Netscape browsers on the Solaris Operating Environment and Linux). Java Web Start technology supports most web proxy auto-configuration scripts. It can detect proxy settings in almost all environments.

You can also use the Java Web Start Control Panel to view or edit the proxy configuration. Refer to the Java Control Panel for more details.

Requirements

Desktop/Client requirements:

The client machine requires support for the Java Runtime Environment (JRE), version 1.3 or later. Java Web Start is available for Windows 98/NT/2000/ME/XP, the Solaris Operating Environment, and Linux.

Server requirements:

Applications can be deployed from any standard Web server. In order to use Java Web Start, the Web server must be configured with support for a new MIME type. See Setting Up the Web Site.


Packaging an Application for Easy Deployment

The Developer's Pack contains a servlet that can be used to bundle a JNLP-deployed application in a Web Archive (WAR) file. See Packaging JNLP Applications in a Web Archive


Setting Up the Web Site

Introduction

Java Web Start leverages existing Internet technology, such as the HTTP protocol and Web servers, so existing infrastructure for deploying HTML-based contents can be reused to deploy Java Technology-based applications using Java Web Start.

In order to deploy your application to client machines, you must make sure that all files containing your application are accessible through a Web server. This typically amounts to copying one or more JAR files, along with a JNLP file, into the Web server's directories. The set-up required for enabling the Web site to support Java Web Start is very similar to deploying HTML-based contents. The only caveat is that a new MIME type needs to be configured for the Web server.

Basic Steps

1. Configure the Web server to use the Java Web Start MIME type

Configure the Web server so that all files with the .jnlp file extension are set to the application/x-java-jnlp-file MIME type.

Most Web browsers use the MIME type returned with the contents from the Web server to determine how to handle the particular content. The server must return application/x-java-jnlp-file MIME type for JNLP files in order for Java Web Start to be invoked.

Each Web server has a specific way in which to add MIME types. For example, for the Apache Web server you must add the following line to the .mime.types configuration file:

application/x-java-jnlp-file JNLP

Check the documentation for the specifics of your Web server.

2. Create a JNLP file for the application

The easiest way to create this file is to modify an existing JNLP file to your requirements.

The syntax and format for the JNLP file is described in a later section.

3. Make the application accessible on the Web server

Ensure your application's JAR files and the JNLP file are accessible at the URLs listed in the JNLP file.

4. Create the web page that launches the application

See the next chapter, Creating the Web Page that launches the Application, for details on step 4.


Deva Search

This page is designed to be viewed by a browser which supports frames.


Deva Search

Java Web Start Search Page
Tips


Deva Search - Help Page

Enter multiple terms with a space between them. The search engine searches for any instance of each term in the list.

Search terms are not case sensitive. You can enter terms in any combination of upper and lower case.

Terms may include any of the following characters: A-Z a-z 0-9 _ - . ' , $ %.

Place a plus sign (+) in front of each word that must appear in the results. For example, if you enter +printer +cartridge +maintenance, the search engine will find all pages that have all three words in them. Note that the three words may not necessarily be adjacent to each other, but they will be in the same page.

Place a minus sign (-) in front of words that you do not want to appear in the results. For example, if you enter +printer +cartridge -maintenance, the search engine will find all pages that have the words "printer" and "cartridge" but not "maintenance."

Common words (a, an, the, etc.) are excluded from the search index.


Blob

8.1 Blob Overview

A Blob object represents the Java programming language mapping of an SQL BLOB (Binary Large Object). An SQL BLOB is a built-in type that stores a Binary Large Object as a column value in a row of a database table. Methods in the interfaces ResultSet, CallableStatement, and PreparedStatement allow a programmer to access the SQL3 type BLOB in the same way that SQL92 built-in types are accessed. In other words, an application using the JDBC 2.0 API uses methods such as getBlob and setBlob for a BLOB value the same way it uses getInt and setInt for an INTEGER value or getString and setString for a CHAR or VARCHAR value.

In a standard implementation, a JDBC driver implements the Blob interface using the SQL type LOCATOR(BLOB) behind the scenes. A LOCATOR(BLOB) designates an SQL BLOB value residing on a database server, and operations on the locator achieve the same results as operations on the BLOB value itself. This means that a client can operate on a Blob instance without ever having to materialize the BLOB data on the client machine, which can improve performance significantly. Because the driver uses LOCATOR(BLOB) behind the scenes, its use is completely transparent to the programmer using a JDBC driver.

The standard behavior for a Blob instance is to remain valid until the transaction in which it was created is either committed or rolled back.

The Blob interface provides methods for getting the length of an SQL BLOB value, for materializing a BLOB value on the client, and for determining the position of a pattern of bytes within a BLOB value.

8.1.1 Creating a Blob Object

The following code fragment illustrates creating a Blob object, where stmt is a Statement object:

ResultSet rs = stmt.executeQuery("SELECT DATA FROM TABLE1");
rs.first();
Blob data = rs.getBlob("DATA");

The variable blob contains a logical pointer to the BLOB value that is stored in the column DATA in the first row of the result set rs. It does not contain the data in the BLOB value, but as far as JDBC methods are concerned, it is operated on as if it did.

8.1.2 Materializing Blob Data

Programmers can invoke methods in the JDBC API on a Blob object as if they were operating on the SQL BLOB it designates. However, if they want to operate on a Blob object as if it were an object in the Java programming language, they must first materialize it on the client. The Blob interface provides two methods for materializing a Blob object: getBinaryStream, which materializes the BLOB value as an input stream, and getBytes, which materializes all or part of the BLOB value as an array of bytes. The following code fragment materializes all of the data in the BLOB value designated by blob as an input stream:

java.io.InputStream in = blob.getBinaryStream();
byte b;
while ((in.read()) > -1) {
    b = in.read();
    System.out.println(b);
}
// prints out all the bytes in the BLOB value that blob designates

The next code fragment also materializes all of the data in the BLOB value designated by blob, but as an array of bytes instead of as an input stream.

long len = blob.length();
byte [] data = blob.getBytes(1, len);
for (int i = 0; i < len; i++) {
    byte b = data[i];
    System.out.println(b);
}
// prints out all the bytes in the BLOB value that blob designates

The variable data contains a copy of all of the bytes in the BLOB value that blob designates. This is true because the arguments passed to the method getBytes specify the entire BLOB value: the first argument tells it to return bytes starting with the first byte, and the second argument tells it to return the number of bytes in the length of the BLOB value. The following line of code illustrates materializing 1024 bytes starting with the 256th byte:

byte [] data = blob.getBytes(256, 1024);
byte b = data[0];
// data contains bytes 256 through 1280 in the BLOB value that blob
// designates; b contains the 256th byte

A point to keep in mind is that because of differences in SQL and the Java programming language, the first byte in a BLOB value is at position 1, whereas the first element of an array in the Java programming language is at index 0.

8.1.3 Storing a Blob Object

To store a Blob object in the database, it is passed as a parameter to the PreparedStatement method setBlob. For example, the following code fragment stores the Blob object stats by passing it as the first input parameter to the PreparedStatement object pstmt:

Blob stats = rs.getBlob("STATS");
PreparedStatement pstmt = con.prepareStatement(
    "UPDATE SIGHTINGS SET MEAS = ? WHERE AREA = 'NE'");
pstmt.setBlob(1, stats);
pstmt.executeUpdate();

The BLOB value designated by stats is now stored in the table SIGHTINGS in column MEAS in the row where column AREA contains NE.

8.2 Blob Interface Definition

package java.sql;
public interface Blob {
    long length() throws SQLException;
    InputStream getBinaryStream() throws SQLException;
    byte[] getBytes(long pos, int length) throws SQLException;
    long position(byte [] pattern, long start) throws SQLException;
    long position(Blob pattern, long start) throws SQLException;
}

8.3 Blob Methods

InputStream getBinaryStream() throws SQLException
Materializes the BLOB value designated by this Blob object as a stream of uninterpreted bytes.

RETURNS:

an InputStream object with the data of the BLOB value designated by this Blob object

EXAMPLE:

InputStream in = blob.getBinaryStream();
// in has the data in the BLOB value that blob designates

getBytes

byte[] getBytes(long pos, int length) throws SQLException

Materializes part or all of the BLOB value that this Blob object designates as an array of bytes. The byte array contains up to length consecutive bytes starting at position pos.

PARAMETERS:

pos the ordinal position in the BLOB value
of the first byte to be extracted; the
first byte is at position 1
length the number of consecutive bytes to be copied

RETURNS:

a byte array with up to length consecutive bytes from the BLOB value pointed to by this Blob object, starting with the byte at position pos

EXAMPLE:

byte [] part = blob.getBytes(5, 100);
// part contains the fifth through 104th bytes, inclusive, as an
// array of bytes

length

long length() throws SQLException
Returns the number of bytes in the BLOB value designated by this Blob object.

RETURNS:

the length of the BLOB value designated by this Blob object, in bytes

EXAMPLE:

Blob blob = rs.getBlob(2);
long len = blob.length();
// len contains the number of bytes in the BLOB value designated by
// blob (the BLOB value in the second column of the current row of the
// ResultSet object rs)

position

long position(byte [] pattern, long start) throws SQLException
Determines the position at which the byte array pattern begins within the BLOB value that this Blob object represents. The search for pattern begins at position start.

PARAMETERS:
pattern | the byte array for which to search
start | the position in the BLOB value at which to begin searching; the first byte is at position 1

RETURNS:

the position in the BLOB value at which the byte array pattern begins, which will be start or larger if the search, starting at position start, is successful; -1 otherwise

EXAMPLE:

byte [] part = blob.getBytes(5, 100);
long beginning = blob.position(part, 1024);
// if part is contained in the BLOB value that blob designates, from
// position 1024 on, beginning will contain the position at which
// part begins

position

long position(Blob pattern, long start) throws SQLException
Determines the byte position in the BLOB value designated by this Blob object at which pattern begins. The search begins at position start.

PARAMETERS:
pattern | the Blob object designating the BLOB value for which to search
start | the position in the BLOB value at which to begin searching; the first byte is at position 1

RETURNS:

the position at which the Blob object pattern begins, which will be start or larger if the search, starting at position start, is successful; -1 otherwise

EXAMPLE:

Blob blob2 = rs.getBlob(4);
long beginning = blob1.position(blob2, 512);
// if the BLOB value designated by blob2 is contained in the BLOB
// value designated by blob1, starting at position 512 or later,
// beginning will contain the position at which the BLOB value
// designated by blob2 begins

Copyright © 2000, Sun Microsystems, Inc. All rights reserved.


Clob

10.1 Clob Overview

A Clob object represents the Java programming language mapping of an SQL CLOB (Character Large Object). An SQL CLOB is a built-in type that stores a Character Large Object as a column value in a row of a database table. Methods in the interfaces ResultSet, CallableStatement, and PreparedStatement allow a programmer to access the SQL3 type CLOB in the same way that more basic SQL types are accessed. In other words, an application using the JDBC 2.0 API uses methods such as getClob and setClob for a CLOB value the same way it uses getInt and setInt for an INTEGER value or getString and setString for a CHAR or VARCHAR value.

The default is for a JDBC driver to implement the Clob interface using the SQL type LOCATOR(CLOB) behind the scenes. A LOCATOR(CLOB) designates an SQL CLOB residing on a database server, and operations on the locator achieve the same results as operations on the CLOB itself. This means that a client can operate on a Clob instance without ever having to materialize the CLOB data on the client machine. The driver uses LOCATOR(CLOB) behind the scenes, making its use completely transparent to the JDBC programmer.

The standard behavior for a Clob instance is to remain valid until the transaction in which it was created is either committed or rolled back.

The interface Clob provides methods for getting the length of an SQL CLOB value, for materializing the data in a CLOB value on the client, and for searching for a substring or CLOB object within a CLOB value.

10.1.1 Creating a Clob Object

The following code fragment illustrates creating a Clob object, where rs is a ResultSet object:

Clob clob = rs.getClob(1);

The variable clob can now be used to operate on the CLOB value that is stored in the first column of the result set rs.

10.1.2 Materializing Clob Data

Programmers can invoke methods in the JDBC API on a Clob object as if they were operating on the SQL CLOB value it designates. However, if they want to operate on a Clob object as an object in the Java programming language, they must first materialize the data of the CLOB object on the client. The Clob interface provides three methods for materializing a Clob object as an object in the Java programming language:

  • getAsciiStream materializes the CLOB value as a byte stream containing Ascii bytes
Clob notes = rs.getClob("NOTES");
java.io.InputStream in = notes.getAsciiStream();
byte b = in.read();
// in contains the characters in the CLOB value designated by
// notes as Ascii bytes; b contains the first character as an Ascii
// byte
  • getCharacterStream materializes the CLOB value as a stream of Unicode characters
java.io.Reader reader = notes.getCharacterStream();
int c = Reader.read();
// c contains the first character in the CLOB that notes designates
  • getSubString materializes all or part of the CLOB value as a String object
String substring = notes.getSubString(10, 5);
// substring contains five characters, starting with the tenth
// character of the CLOB value that notes designates
long len = notes.length();
String substring = notes.getSubString(1, len);
// substring contains all of the characters in the CLOB object that
// notes designates

10.1.3 Storing a Clob Object

To store a Clob object in the database, it is passed as a parameter to the PreparedStatement method setClob. For example, the following code fragment stores the Clob object notes by passing it as the first input parameter to the PreparedStatement object pstmt:

Clob notes = rs.getClob("NOTES");
PreparedStatement pstmt = con.prepareStatement(
        "UPDATE SALES_STATS SET COMMENTS = ? WHERE SALES > 500000");
pstmt.setClob(1, notes);
pstmt.executeUpdate();

The CLOB value designated by notes is now stored in the table SALES_STATS in column COMMENTS in every row where the value in the column SALES is greater than 500000.

10.2 Clob Interface Definition

package java.sql;
public interface java.sql.Clob {
    long length() throws SQLException;
    InputStream getAsciiStream() throws SQLException;
    Reader getCharacterStream() throws SQLException;
    String getSubString(long pos, int length) throws SQLException;
    long position(String searchstr, long start) throws SQLException;
    long position(Clob searchstr, long start) throws SQLException;
}

10.3 Clob Methods

getAsciiStream

InputStream getAsciiStream() throws SQLException
Materializes the CLOB value designated by this Clob object as a stream of Ascii bytes.

RETURNS:

an InputStream object with all the data in the CLOB value designated by this Clob object as Ascii bytes

EXAMPLE:

java.io.InputStream in = clob.getAsciiStream();
byte b = in.read();
// in has all of the characters in the CLOB value designated by
// clob as Ascii bytes; b designates the first character as an Ascii
// byte

getCharacterStream

Reader getCharacterStream() throws SQLException
Materializes the CLOB value designated by this Clob object as a stream of Unicode characters.

RETURNS:

a Reader object with all the data in the CLOB value designated by this Clob object as Unicode characters

EXAMPLE:

Reader read = clob.getCharacterStream();
// read has all the data in the CLOB value designated by clob
// as Unicode characters

getSubString

length getSubString(long pos, int length) throws SQLException
Returns a copy of the portion of the CLOB value represented by this Clob object that starts at position pos and has up to length consecutive characters.

PARAMETERS:
pos | the position of the first char to extract from the CLOB value designated by this Clob object; the initial position is 1
length | the number of consecutive characters to be copied

RETURNS:

a String object containing a copy of up to length consecutive characters from the CLOB value represented by this Clob object, starting with the char at position pos

EXAMPLE:

String substr = clob.getSubString(1, 100);
// substr contains the first 100 characters in the CLOB value
// designated by clob (those in positions 1 through 100, inclusive)

length

long length() throws SQLExceptions
Returns the number of characters in the CLOB value designated by this Clob object.

RETURNS:

the length in characters of the CLOB value that this Clob object represents

EXAMPLE:

Clob clob = rs.getClob(3);
long len = clob.length();
// len contains the number of characters in the CLOB value
// designated by clob

position

long position(Clob searchstr, long start) throws SQLException
Determines the character position at which the Clob object searchstr begins within the CLOB value that this Clob object represents. The search begins at position start.

PARAMETERS:
searchstr | the Clob object for which to search
start | the position at which to begin searching; the first character is at position 1

RETURNS:

the position at which the Clob object searchstr begins, which will be start or larger if the search, starting at position start, is successful; -1 otherwise

EXAMPLE:

Clob clob2 = rs.getClob(4);
long beginning = clob.position(clob2, 1024);
// if clob2 is contained in clob starting at position 1024 or later,
// beginning will contain the position at which clob2 begins

position

long position(String searchstr, long start) throws SQLException
Determines the position at which the String searchstr begins within the CLOB value that this Clob object represents. The search begins at position start.

PARAMETERS:
searchstr | the string for which to search
start | the position at which to begin searching; the first character is at position 1

RETURNS:

the position at which the String object searchstr begins, which will be start or larger if the search, starting at position start, is successful; -1 otherwise

EXAMPLE:

String searchstr= clob.getSubString(5, 100);
long beginning = clob.position(searchstr, 1024);
// if searchstr is contained in clob from position 1024 on, beginning
// will contain the position at which searchstr begins

Copyright © 2000, Sun Microsystems, Inc. All rights reserved.


JDBC Documentation

Java logo

JDBC

 Documentation Contents

The Java Database Connectivity (JDBC) API provides universal data access from the Java programming language. Using the JDBC 3.0 API, you can access virtually any data source, from relational databases to spreadsheets and flat files. JDBC technology also provides a common base on which tools and alternate interfaces can be built.

The JDBC 3.0 API is comprised of two packages:

  1. the java.sql package
  2. the javax.sql package, which adds server-side capabilities

You automatically get both packages when you download the Java Platform Standard Edition (Java SE) 6.

To use the JDBC API with a particular database management system, you need a JDBC technology-based driver to mediate between JDBC technology and the database. Depending on various factors, a driver might be written purely in the Java programming language or in a mixture of the Java programming language and Java Native Interface (JNI) native methods. The JDBC web site maintains a list of vendors with drivers currently available or under development.

The latest JDK includes a JDBC-ODBC Bridge driver that makes most Open Database Connectivity (ODBC) drivers available to programmers using the JDBC API. JDBC-ODBC Bridge Driver describes the current status of this software. Note that the bridge driver included in the Java Platform Standard Edition (Java SE) 6 is appropriate only for experimental use or when no other driver is available.

Overview

  • JDBC Technology Guide

API Specification

  • java.sql
  • javax.sql

Specification documents for all releases of the JDBC API are available from the JDBC download page.

Tutorials and Programming Guides

  • Basic Tutorial
  • Advanced Tutorial
  • Rowset Tutorial (pdf)

More Information

  • JDBC Home Page
  • Answers to Frequently-Asked Questions
  • Using Blob objects (Binary Large Objects) Chapter 8 of the JDBC Java Series book
  • Using Clob objects (Character Large Objects) Chapter 10 of the JDBC Java Series book
  • Java Series book JDBCTM API Tutorial and Reference, Third Edition
  • J2EE documentation web page

Copyright © 2002 Sun Microsystems, Inc. All Rights Reserved.

Feedback

Java Software


JDBC-ODBC Bridge Enhancements

Java logo

JDBCTM-ODBC Bridge Enhancements

 Documentation Contents
JDBC

The JDBC-ODBC Bridge allows applications written in the JavaTM programming language to use the JDBCTM API with many existing ODBC drivers. The Bridge is itself a driver based on JDBC technology ("JDBC driver") that is defined in the class sun.jdbc.odbc.JdbcOdbcDriver. The Bridge defines the JDBC sub protocol odbc.

Status of the JDBC-ODBC Bridge

The JDBC-ODBC Bridge should be considered a transitional solution. Sun Microsystems and DataDirect Technologies are working to make the Bridge more reliable and robust, but they do not consider it a supported product. With the development of pure Java JDBC drivers, the JDBC-ODBC Bridge should become unnecessary.

Why not just use ODBC?

The JDBC-ODBC Bridge offers several advantages over "naked" ODBC.
  • The ODBC API is strongly oriented toward C/C++ programmers. The JDBC-ODBC Bridge makes it unnecessary for programmers using the Java programming language to deal with non-Java language concepts.
  • The ODBC API is extremely complex and intermingles high level and low level functions. The JDBC-ODBC Bridge allows the programmer to rely on the JDBC API, which is relatively simple and easy to learn.
  • The JDBC-ODBC Bridge lets a program deal with ODBC through a standardized JDBC interface. That helps a program avoid being tied to ODBC when a better solution comes along.

Why use ODBC at all?

The ideal is "Pure Java": no native code, no platform dependent features. But you may need to begin your development effort right away, without waiting for your DBMS to offer a Java only JDBC driver. Partly native drivers, such as the JDBC-ODBC Bridge, let you create programs that easily adapt to Pure Java drivers as they become available.

What's New with the JDBC-ODBC Bridge?

  • A jdbc:odbc: connection can now have a charSet property, to specify a Character Encoding Scheme other than the client default. For possible values, see the Internationalization specification on the Java Software Web Site.

    • The following code fragment shows how to set 'Big5' as the character set for all character data.
           // Load the JDBC-ODBC bridge driver
       Class.forName(sun.jdbc.odbc.JdbcOdbcDriver) ;

       // setup the properties
       java.util.Properties prop = new java.util.Properties();
       prop.put("charSet", "Big5");
       prop.put("user", username);
       prop.put("password", password);

       // Connect to the database
       con = DriverManager.getConnection(url, prop);
  • The bridge now supports JDBC 2.0 features, which includes batch updates, scrollable cursors, and so on.
  • JDBC-ODBC bridge now offers most of the features required for a J2EE compatible JDBC driver.
  • Sample implementations of DataSource and ConnectionPoolDataSource are available with the JDBC-ODBC bridge.
  • CallableStatement OUT/INOUT parameter handling has been improved.
  • Automatic garbage collection of unclosed Statement objects has been implemented.
  • Improved support for updatable Resultset objects has been implemented.
  • Additional robustness and reliability checking as been introduced.

New DataSource Implementations in the JDBC-ODBC Bridge

Implementations of javax.sql.DataSource and javax.sql.ConnectionPoolDataSource are now available. Both are in the sun.jdbc.odbc.ee package. The following code fragment illustrates how to set DataSource properties. The last two lines use JNDI API to bind the DataSource object ds to "jdbc/OdbcDB1". Assume that the DataSource object is targeting an ODBC DSN "dsn1" connecting to an Oracle Database.
            // Establish the DataSource object instance
            sun.jdbc.odbc.ee.DataSource ds = new sun.jdbc.odbc.ee.DataSource();
            // Provide user credentials and database name
            ds.setUser("scott");
            ds.setPassword("tiger");
            ds.setDatabaseName("dsn1");
            ds.setCharSet("..."); // optional property
            ds.setLoginTimeout(100); // optional property
            // Establish initial context and bind to the datasource target
            InitialContext ic = new InitialContext();
            ic.bind("jdbc/OdbcDB1",ds);
In the preceding code, note that some properties are optional while some are required. Properties such as port number and role name are not implemented in the JDBC-ODBC bridge DataSource implementations as these properties are not applicable to ODBC paradigm.

Continuing the previous example, the following code fragment demonstrates retrieving the DataSource object by looking up the JNDI name "jdbc/OdbcDB1". With the DataSource object that is obtained, the code then activates tracing and creates two connections.

            // Get the initial context of JNDI and lookup the datasource.
            InitialContext ic = new InitialContext();
            javax.sql.DataSource ds1 = (javax.sql.DataSource) ic.lookup("jdbc/OdbcDB1");
            // Set the optional printwriter where the trace log is to be directed.
            ds1.setLogWriter(new PrintWriter(new FileOutputStream("/tmp/datasource.log")));
            Connection con1 = ds1.getConnection();
            Connection con2 = ds1.getConnection("system","manager");
The implementation of javax.sql.ConnectionPoolDataSource uses an underlying pool of JDBC-ODBC connections. A ConnectionPoolDataSource object is used to create PooledConnection objects, which are in turn used to get Connection objects. From the user's viewpoint, the Connection object is just like any other connection.

The following code fragment creates the ConnectionPoolDataSource object cpds and sets its properties. The final two lines use JNDI API to bind cpds to "jdbc/OdbcPool", which can later be supplied to the method InitialContext.lookup to retrieve cpds.

            // Establish ConnectionPoolDataSource instance
            sun.jdbc.odbc.ee.ConnectionPoolDataSource cpds =
                new sun.jdbc.odbc.ee.ConnectionPoolDataSource("jdbc/OdbcPool");
            // Provide user credentials and database name
            cpds.setUser("scott");
            cpds.setPassword("tiger");
            cpds.setDatabaseName("dsn1");
            cpds.setCharSet("...") // optional property
            cpds.setLoginTimeout(100); // optional property
            cpds.setMinPoolSize("10");
            cpds.setInitialPoolSize("15");
            cpds.setMaxPoolSize("20");
            cpds.setMaxIdleTime("300");
            cpds.setTimeoutFromPool("600");
            // Maintenance interval of the pool. A maintenance thread will remove
            // unwanted connections and cleanup the pool at the interval specified.
            // This cannot be zero.
            cpds.setMaintenanceInterval("900");
            InitialContext ic = new InitialContext();
            ic.bind("jdbc/OdbcPool",cpds);
In all cases in order get the ConnectionPoolDataSource to function as a pooled datasource, it is the responsibility of the application to configure the pool as described in the code example above. The default behavior of pooled datasource uses a zero minimum, initial and maximum pool sizes. Note that the JDBC-ODBC bridge implementation of ConnectionPoolDataSource does not yet include the pooling of Statement objects or the property propertyCycle.

The following code fragment shows how to use a ConnectionPoolDataSource object as simply a DataSource object. This is done by doing a JNDI lookup of "jdbc/OdbcPool" and casting it to a DataSource object instead of to a ConnectionPoolDataSource object.

            InitialContext ic = new InitialContext();
            javax.sql.DataSource ds1 = (javax.sql.DataSource) ic.lookup("jdbc/OdbcPool");
            // First getConnection will initializes the pool.
            Connection con1 = ds1.getConnection();
            Connection con2 = ds1.getConnection("system","manager");
            -------------
            -------------
            // An application need to close the connection explicitly. This will allow the pool to recycle the connection.
            con1.close();
            con2.close();
Using the implementation as a ConnectionPoolDataSource object is shown in the following line of code. Note that closing a PooledConnection object closes the actual physical connection, whereas closing a connection that was created from a PooledConnection object just returns it to the pool of connections.
            InitialContext ic = new InitialContext();
            javax.sql.ConnectionPoolDataSource cpds =
                (javax.sql.ConnectionPoolDataSource) ic.lookup("jdbc/OdbcPool");
            PooledConnection pc1 = cpds.getPooledConnection();
            Connection con1 = pc1.getConnection();
            PooledConnection pc2 = cpds.getPooledConnection("system","manager");
            Connection con2 = pc2.getConnection();
            -------------
            -------------
            // An application needs to close the connection explicitly. This will allow the pool to recycle the connection.
            con1.close();
            con2.close();
            Connection con3 = pc1.getConnection();
            Connection con4 = pc2.getConnection();
            -------------
            -------------
            // This will close the physical connection!
            pc1.close();
            pc2.close();
A pool of connections can be shut down in two ways. If the method shutDown is given the argument false, only those connections that are not being used will be closed. If the argument true is supplied, all connections will be closed immediately, regardless of whether they are being used or not.
            // Hot shutdown
            ((sun.jdbc.odbc.ee.ConnectionPoolDataSource) cpds).shutDown(true);
            or
            // Cold shutdown
            ((sun.jdbc.odbc.ee.ConnectionPoolDataSource) cpds).shutDown(false);

Java logo Copyright © 2002 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: jdbc-odbc@sun.com


 [Top] [Prev] [Next]

9 - JDBC-ODBC Bridge Driver

9.1 Obtaining a JDBC Driver

It is recommended that you obtain a commercial JDBC driver from a vendor such as your database vendor or your database middleware vendor. Check the list of drivers currently available.

The JDBC-ODBC Bridge driver is recommended only for experimental use or when no other alternative is available.

9.2 JDBC-ODBC Bridge

If possible, use a Pure Java JDBC driver instead of the Bridge and an ODBC driver. This completely eliminates the client configuration required by ODBC. It also eliminates the potential that the Java VM could be corrupted by an error in the native code brought in by the Bridge (that is, the Bridge native library, the ODBC driver manager library, the ODBC driver library, and the database client library).

The JDBC-ODBC Bridge driver is recommended for use in prototyping efforts and for cases where no other JDBC technology-based driver exists. If a commercial, all-Java JDBC driver is available, we recommend that it be used instead of the Bridge.

9.2.1 What Is the JDBC-ODBC Bridge?

The JDBC-ODBC Bridge is a JDBC driver that implements JDBC operations by translating them into ODBC operations. To ODBC it appears as a normal application program. The Bridge implements JDBC for any database for which an ODBC driver is available. The Bridge is implemented as the sun.jdbc.odbc Java package and contains a native library used to access ODBC. The Bridge is a joint development of Merant and Java Software.

9.2.2 ODBC Compatibility and ODBC Versions Supported

On Solaris, the JDBC 2.0 bridge must be used with an ODBC 3.x driver manager. The bridge supports both ODBC 2.x and ODBC 3.x drivers, but has been tested with only ODBC 3.x drivers.

On NT, the JDBC 2.0 bridge supports the ODBC 2.x and ODBC 3.x driver manager and drivers. The JDBC 2.0 bridge has been tested only with an ODBC 3.x driver manager and with both ODBC 2.x and 3.x drivers.

Merant recommends that the JDBC 2.0 bridge be used with version 3.5 or higher of Merant's DataDirect ODBC drivers.

9.2.3 The Bridge Implementation

The Bridge is implemented in Java and uses Java native methods to call ODBC.

9.2.4 Installation

The Bridge is installed automatically with the JDK, as package sun.jdbc.odbc. See your ODBC driver vendor for information on installing and configuring ODBC. No special configuration is required for the Bridge. See your database vendor for client installation and configuration information. On Solaris, some ODBC driver managers name their libs libodbcinst.so and libodbc.so. The Bridge expects these libraries to be named libodbcinst.so.1 and libodbc.so.1, so symbolic links for these names must be created.

9.3 Using the Bridge

The Bridge is used by opening a JDBC connection using a URL with the odbc subprotocol. See below for URL examples. Before a connection can be established, the bridge driver class, sun.jdbc.odbc.JdbcOdbcDriver, must either be added to the java.lang.System property named jdbc.drivers, or it must be explicitly loaded using the Java class loader. Explicit loading is done with the following line of code:

    Class.forName("sun.jdbc.odbc.JdbcOdbcDriver");
When loaded, the ODBC driver (like all good JDBC drivers) creates an instance of itself and registers this with the JDBC driver manager.

9.3.1 Using the Bridge from an Applet

JDBC used with a Pure Java JDBC driver works well with applets. The Bridge driver does not work well with applets.

9.3.2 Most Browsers Do Not Support the Bridge

Since the Bridge is an optional component of the JDK, it may not be provided by a browser. Even if it is provided, only trusted applets (those allowed to write to files) will be able to use the Bridge. This is required in order to preserve the security of the applet sandbox. Finally, even if the applet is trusted, ODBC and the DBMS client library must be configured on each client.

9.3.3 Tested Configurations

From Solaris, we have used the Bridge to access Oracle 8.1.5 using version 3.5 of Merant's ODBC drivers. From NT, we have used the Bridge to access SQL Server 6.x using the latest ODBC driver from Microsoft.

9.3.4 ODBC Drivers Known to Work with the Bridge

ODBC drivers are available for Oracle, Sybase, Informix, Microsoft SQL Server, and Ingres. The MERANT ODBC driver suite should be completely compatible with the JDBC-ODBC Bridge. To evaluate or purchase MERANT ODBC drivers, please contact MERANT DataDirect Sales at 1-800-547-4000 Option 2 or via the World Wide Web at http:\\www.merant.com. The MS SQL Server driver has also been used successfully on NT. Many other ODBC drivers will likely work.

9.3.5 What Is the JDBC URL Supported by the Bridge?

The Bridge driver uses the odbc subprotocol. URLs for this subprotocol are of the form:

    jdbc:odbc:<data-source-name>[<attribute-name>=<attribute-value>]*
For example:

    jdbc:odbc:sybase
    jdbc:odbc:mydb;UID=me;PWD=secret
    jdbc:odbc:ora123;Cachesize=300

9.3.6 Debugging

The Bridge provides extensive tracing when DriverManager tracing is enabled. The following line of code enables tracing and sends it to standard out:

     java.sql.DriverManager.setLogStream(java.lang.System.out);

9.4 New JDBC 2.0 API Features Supported by the Bridge

The JDBC-ODBC Bridge driver in this release supports the following new features in the JDBC 2.0 API:

  • batch updates
  • updatable result sets
  • scrollable result sets
  • the new BigDecimal methods
  • the new Date, Time, and Timestamp methods

The current release of the Bridge supports multi-threaded ODBC drivers and contains numerous bug fixes.

[Top] [Prev] [Next]

jdbc@wombat.eng.sun.com or jdbc-odbc@wombat.eng.sun.com
Copyright © 1996 - 1999 Sun Microsystems, Inc. All rights reserved.


[Top] [Prev] [Next]

Appendix B - Sample Code

    // The following code can be used as a template.  Simply
// substitute the appropriate url, login, and password, and then substitute the
// SQL statement you want to send to the database.

//----------------------------------------------------------------------------
//
// Module:	SimpleSelect.java
//
// Description:	Test program for ODBC API interface.  This java application
// will connect to a JDBC driver, issue a select statement
// and display all result columns and rows
//
// Product:	JDBC to ODBC Bridge
//
// Author:	Karl Moss
//
// Date:	February, 1996
//
// Copyright:	1990-1996 INTERSOLV, Inc.
// This software contains confidential and proprietary
// information of INTERSOLV, Inc.
//----------------------------------------------------------------------------

import java.net.URL;
import java.sql.*;

class SimpleSelect {

public static void main (String args[]) {
    String url   = "jdbc:odbc:my-dsn";
    String query = "SELECT * FROM emp";

    try {

        // Load the jdbc-odbc bridge driver

        Class.forName ("sun.jdbc.odbc.JdbcOdbcDriver");

        DriverManager.setLogStream(System.out);

        // Attempt to connect to a driver.  Each one
        // of the registered drivers will be loaded until
        // one is found that can process this URL

        Connection con = DriverManager.getConnection (
            url, "my-user", "my-passwd");

        // If we were unable to connect, an exception
        // would have been thrown.  So, if we get here,
        // we are successfully connected to the URL

        // Check for, and display and warnings generated
        // by the connect.

        checkForWarning (con.getWarnings ());

        // Get the DatabaseMetaData object and display
        // some information about the connection

        DatabaseMetaData dma = con.getMetaData ();

        System.out.println("\nConnected to " + dma.getURL());
        System.out.println("Driver       " +
            dma.getDriverName());
        System.out.println("Version      " +
            dma.getDriverVersion());
        System.out.println("");

        // Create a Statement object so we can submit
        // SQL statements to the driver

        Statement stmt = con.createStatement ();

        // Submit a query, creating a ResultSet object

        ResultSet rs = stmt.executeQuery (query);

        // Display all columns and rows from the result set

        dispResultSet (rs);

        // Close the result set

        rs.close();

        // Close the statement

        stmt.close();

        // Close the connection

        con.close();
    }
    catch (SQLException ex) {

        // A SQLException was generated.  Catch it and
        // display the error information.  Note that there
        // could be multiple error objects chained
        // together

    System.out.println ("\n*** SQLException caught ***\n");

    while (ex != null) {
        System.out.println ("SQLState: " +
                ex.getSQLState ());
        System.out.println ("Message:  " + ex.getMessage ());
        System.out.println ("Vendor:   " +
                ex.getErrorCode ());
        ex = ex.getNextException ();
        System.out.println ("");
        }
    }
    catch (java.lang.Exception ex) {

        // Got some other type of exception.  Dump it.

        ex.printStackTrace ();
    }
}

//-------------------------------------------------------------------
// checkForWarning
// Checks for and displays warnings.  Returns true if a warning
// existed
//-------------------------------------------------------------------

private static boolean checkForWarning (SQLWarning warn)
        throws SQLException  {
    boolean rc = false;

    // If a SQLWarning object was given, display the
    // warning messages.  Note that there could be
    // multiple warnings chained together

    if (warn != null) {
        System.out.println ("\n *** Warning ***\n");
        rc = true;
        while (warn != null) {
            System.out.println ("SQLState: " +
                warn.getSQLState ());
            System.out.println ("Message:  " +
                warn.getMessage ());
            System.out.println ("Vendor:   " +
                warn.getErrorCode ());
            System.out.println ("");
            warn = warn.getNextWarning ();
        }
    }
    return rc;
}

//-------------------------------------------------------------------
// dispResultSet
// Displays all columns and rows in the given result set
//-------------------------------------------------------------------

private static void dispResultSet (ResultSet rs)
    throws SQLException
{
    int i;

    // Get the ResultSetMetaData.  This will be used for
    // the column headings

    ResultSetMetaData rsmd = rs.getMetaData ();

    // Get the number of columns in the result set

    int numCols = rsmd.getColumnCount ();

    // Display column headings

    for (i=1; i<=numCols; i++) {
        if (i > 1) System.out.print(",");
        System.out.print(rsmd.getColumnLabel(i));
    }
    System.out.println("");

    // Display data, fetching until end of the result set

    boolean more = rs.next ();
    while (more) {

        // Loop through each column, getting the
        // column data and displaying

        for (i=1; i<=numCols; i++) {
            if (i > 1) System.out.print(",");
            System.out.print(rs.getString(i));
        }
        System.out.println("");

        // Fetch the next result set row

        more = rs.next ();
    }
}

}

[Top] [Prev] [Next]
jdbc@wombat.eng.sun.com or jdbc-odbc@wombat.eng.sun.com
Copyright © 1999 Sun Microsystems, Inc. All rights reserved.


 [Top] [Prev] [Next]

CallableStatement

NOTE: The material in this chapter is based on JDBCtm API Tutorial and Reference, Second Edition: Universal Data Access for the Javatm 2 Platform, published by Addison Wesley as part of the Java series, ISBN 0-201-43328-1.

7.1 CallableStatement Overview

A CallableStatement object provides a way to call stored procedures in a standard way for all RDBMSs. A stored procedure is stored in a database; the call to the stored procedure is what a CallableStatement object contains. This call is written in an escape syntax that may take one of two forms: one form with a result parameter, and the other without one. A result parameter, a kind of OUT parameter, is the return value for the stored procedure. Both forms may have a variable number of parameters used for input (IN parameters), output (OUT parameters), or both (INOUT parameters). A question mark serves as a placeholder for a parameter.

The syntax for invoking a stored procedure using the JDBC API is shown here. Note that the square brackets indicate that what is between them is optional; they are not themselves part of the syntax.

{call procedure_name[(?, ?, ...)]}

The syntax for a procedure that returns a result parameter is:

{? = call procedure_name[(?, ?, ...)]}

The syntax for a stored procedure with no parameters would look like this:

{call procedure_name}

Normally, anyone creating a CallableStatement object would already know that the DBMS being used supports stored procedures and what those procedures are. If one needed to check, however, various DatabaseMetaData methods will supply such information. For instance, the method supportsStoredProcedures will return true if the DBMS supports stored procedure calls, and the method getProcedures will return a description of the stored procedures available.

CallableStatement inherits Statement methods, which deal with SQL statements in general, and it also inherits PreparedStatement methods, which deal with IN parameters. All of the methods defined in CallableStatement deal with OUT parameters or the output aspect of INOUT parameters: registering the JDBC types of the OUT parameters, retrieving values from them, or checking whether a returned value was JDBC NULL. Whereas the getXXX methods defined in ResultSet retrieve values from a result set, the getXXX methods in CallableStatement retrieve values from the OUT parameters and/or return value of a stored procedure.

7.1.1 Creating a CallableStatement Object

CallableStatement objects are created with the Connection method prepareCall. The following example, in which con is an active JDBC Connection object, creates an instance of CallableStatement.

CallableStatement cstmt = con.prepareCall(
    "{call getTestData(?, ?)}");

The variable cstmt contains a call to the stored procedure getTestData, which has two input parameters and no result parameter. Whether the ? placeholders are IN, OUT, or INOUT parameters depends on the stored procedure getTestData. This instance of a CallableStatement object was created using JDBC 1.0 API; consequently, any query in the stored procedure called by cstmt will produce a default ResultSet object (one that is non-scrollable and non-updatable).

The JDBC 2.0 API provides the means to create CallableStatement objects that can produce ResultSet objects that are scrollable and updatable, as the following code fragment demonstrates.

String sql = "{call getTestData(?, ?)}";
CallableStatement cstmt2 = con.prepareCall(sql,
    ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_UPDATABLE);

The variable cstmt2 contains the same call to the stored procedure TestData that cstmt does, but with cstmt2, any resultSet objects that TestData produces can be updated and are scrollable (though they will not be sensitive to updates made while they are open). Explanations for the constants used to indicate scrollability and updatability are given in the chapter "ResultSet."

7.1.2 IN Parameters

Passing in any IN parameter values to a CallableStatement object is done using the setXXX methods inherited from PreparedStatement. The type of the value being passed in determines which setXXX method to use (setFloat to pass in a float value, setBoolean to pass in a boolean, and so on). Of the programs that use parameters, the vast majority use only IN parameters.

7.1.3 Making Batch Updates

The ability to make batch updates is the same for CallableStatement objects as it is for PreparedStatement objects. In fact, a CallableStatement object is restricted to the same functionality that a PreparedStatement object has. More precisely, when using the batch update facility, a CallableStatement object can call only stored procedures that take input parameters or no parameters at all. Further, the stored procedure must return an update count. The CallableStatement.executeBatch method (inherited from PreparedStatement) will throw a BatchUpdateException if the stored procedure returns anything other than an update count or takes OUT or INOUT parameters.

The following code fragment illustrates using the batch update facility to associate two sets of parameters with a CallableStatement object.

CallableStatement cstmt = con.prepareCall(
            "{call updatePrices(?, ?)}");
cstmt.setString(1, "Colombian");
cstmt.setFloat(2, 8.49f);
cstmt.addBatch();

cstmt.setString(1, "Colombian_Decaf");
cstmt.setFloat(2, 9.49f);
cstmt.addBatch();

int [] updateCounts = cstmt.executeBatch();

The variable cstmt contains a call to the stored procedure updatePrices with two sets of parameters associated with it. When cstmt is executed, two update statements will be executed together as a batch: one with the parameters Colombian and 8.49f, and a second one with the parameters Colombian_Decaf and 9.49f. An f after a number, as in 8.49f, tells the Java compiler that the value is a float; otherwise, the compiler assumes that a number with decimal digits is a double and will not allow it to be used as a float.

7.1.4 OUT Parameters

If the stored procedure returns OUT parameters, the JDBC type of each OUT parameter must be registered before the CallableStatement object can be executed. This is necessary because some DBMSs require the SQL type (which the JDBC type represents), not because JDBC requires it. JDBC types, a set of generic SQL type identifiers that represent the most commonly used SQL types, are explained fully in the chapter "Mapping SQL and Java Types" on page 85.

Registering the JDBC type is done with the method registerOutParameter. Then after the statement has been executed, CallableStatement's getXXX methods can be used to retrieve OUT parameter values. The correct CallableStatement.getXXX method to use is the type in the Java programming language that corresponds to the JDBC type registered for that parameter. (The standard mapping from JDBC types to Java types is shown in Table 8.1 on page 105.) In other words, registerOutParameter uses a JDBC type (so that it matches the data type that the database will return), and getXXX casts this to a Java type.

To illustrate, the following code registers the OUT parameters, executes the stored procedure called by cstmt, and then retrieves the values returned in the OUT parameters. The method getByte retrieves a Java byte from the first OUT parameter, and getBigDecimal retrieves a java.math.BigDecimal object (with three digits after the decimal point) from the second OUT parameter. The method executeQuery is used to execute cstmt because the stored procedure that it calls returns a result set.

CallableStatement cstmt = con.prepareCall(
    "{call getTestData(?, ?)}");
cstmt.registerOutParameter(1, java.sql.Types.TINYINT);
cstmt.registerOutParameter(2, java.sql.Types.DECIMAL, 3);
ResultSet rs = cstmt.executeQuery();
// . . . retrieve result set values with rs.getXXX methods
byte x = cstmt.getByte(1);
java.math.BigDecimal n = cstmt.getBigDecimal(2);

Unlike ResultSet, CallableStatement does not provide a special mechanism for retrieving large OUT values incrementally. More specifically, it does not have getXXX methods for streams of data, such as getAsciiStream or getBinary-Stream. However, the JDBC 2.0 API provides CallableStatement methods for retrieving SQL3 datatypes as OUT or INOUT parameters, which includes the methods getBlob and getClob for retrieving binary large objects and character large objects.

7.1.5 Numbering of Parameters

When a method takes an int specifying which parameter to act upon (setXXX, getXXX, and registerOutParameter), that int refers to ? placeholder parameters only, with numbering starting at one. The parameter number does not refer to literal parameters that might be supplied to a stored procedure call. For example, the following code fragment illustrates a stored procedure call with one literal parameter and one ? parameter:

CallableStatement cstmt = con.prepareCall(
        "{call getTestData(25, ?)}");
cstmt.registerOutParameter(1, java.sql.Types.TINYINT);

In this code, the first argument to registerOutParameter, the int 1, refers to the first ? parameter (and in this case, the only ? parameter). It does not refer to the literal 25, which is the first parameter to the stored procedure.

7.1.6 INOUT Parameters

A parameter that supplies input as well as accepts output (an INOUT parameter) requires a call to the appropriate setXXX method (inherited from PreparedStatement) in addition to a call to the method registerOutParameter. The setXXX method sets a parameter's value as an input parameter, and the method registerOutParameter registers its JDBC type as an output parameter. The setXXX method provides a Java value that the driver converts to a JDBC value before sending it to the database. The JDBC type of this IN value and the JDBC type supplied to the method registerOutParameter should be the same. Then, to retrieve the output value, a corresponding getXXX method is used. For example, a parameter whose Java type is byte should use the method setByte to assign the input value, should supply a TINYINT as the JDBC type to registerOutParameter, and should use getByte to retrieve the output value. ("Mapping SQL and Java Types" on page 85 contains tables of type mappings.)

The following example assumes that there is a stored procedure reviseTotal whose only parameter is an INOUT parameter. The method setByte sets the parameter to 25, which the driver will send to the database as a JDBC TINYINT. Next registerOutParameter registers the parameter as a JDBC TINYINT. After the stored procedure is executed, a new JDBC TINYINT value is returned, and the method getByte will retrieve this new value as a Java byte. Since the stored procedure called in this example returns an update count, the method executeUpdate is used.

CallableStatement cstmt = con.prepareCall(
        "{call reviseTotal(?)}");
cstmt.setByte(1, (byte)25);
cstmt.registerOutParameter(1, java.sql.Types.TINYINT);
cstmt.executeUpdate();
byte x = cstmt.getByte(1);

7.1.7 Retrieve OUT Parameters after Results

Because of limitations imposed by some DBMSs, it is recommended that for maximum portability, all of the results in a ResultSet object generated by the execution of a CallableStatement object should be retrieved before OUT parameters are retrieved. When all values have been retrieved from a result set, the method ResultSet.next will return false.

If a CallableStatement object returns multiple ResultSet objects (which is possible only if it is executed with a call to the method execute), all of the results should be retrieved before OUT parameters are retrieved. In this case, to be sure that all results have been accessed, the Statement methods getResultSet, getUpdateCount, and getMoreResults need to be called until there are no more results. When all results have been exhausted, the method getMoreResults returns false, and the method getUpdateCount returns -1.

After all values have been retrieved from ResultSet objects (using ResultSet.getXXX methods), and after it has been determined that there are no more update counts, values from OUT parameters can be retrieved (using CallableStatement.getXXX methods).

7.1.8 Retrieving NULL Values as OUT Parameters

The value returned to an OUT parameter may be JDBC NULL. When this happens, the JDBC NULL value will be converted so that the value returned by a getXXX method will be null, 0, or false, depending on the getXXX method type. As with ResultSet objects, the only way to know if a value of 0 or false was originally JDBC NULL is to test it with the method wasNull, which returns true if the last value read by a getXXX method was JDBC NULL, and false otherwise.

[Top] [Prev] [Next]

Copyright © 1999, Sun Microsystems, Inc. All rights reserved.


 [Top] [Prev] [Next]

Connection

NOTE: The material in this chapter is based on JDBCtm API Tutorial and Reference, Second Edition: Universal Data Access for the Javatm 2 Platform, published by Addison Wesley as part of the Java series, ISBN 0-201-43328-1.

2.1 Connection Overview

A Connection object represents a connection with a database. A connection session includes the SQL statements that are executed and the results that are returned over that connection. A single application can have one or more connections with a single database, or it can have connections with many different databases.

A user can get information about a Connection object's database by invoking the Connection.getMetaData method. This method returns a DatabaseMetaData object that contains information about the database's tables, the SQL grammar it supports, its stored procedures, the capabilities of this connection, and so on.

2.1.1 Opening a Connection

The traditional way to establish a connection with a database is to call the method DriverManager.getConnection. This method takes a string containing a URL. The DriverManager class, referred to as the JDBC management layer, attempts to locate a driver that can connect to the database represented by that URL. The DriverManager class maintains a list of registered Driver classes, and when the method getConnection is called, it checks with each driver in the list until it finds one that can connect to the database specified in the URL. The Driver method connect uses this URL to actually establish the connection.

A user can bypass the JDBC management layer and call Driver methods directly. This could be useful in the rare case that two drivers can connect to a database and the user wants to explicitly select a particular driver. Normally, however, it is much easier to just let the DriverManager class handle opening a connection.

The following code exemplifies opening a connection to a database located at the URL jdbc:odbc:wombat with a user ID of oboy and 12Java as the password:

String url = "jdbc:odbc:wombat";
Connection con = DriverManager.getConnection(url, "oboy", "12Java");

The JDBC 2.0 Standard Extension API provides the DataSource interface as an alternative to the DriverManager for establishing a connection. When a DataSource class has been implemented appropriately, a DataSource object can be used to produce Connection objects that participate in connection pooling and/or Connection objects that can participate in distributed transactions. See the chapter "DataSource" for more information and to see example code for creating a connection using a DataSource object. This chapter also explains why using a DataSource object is the preferred alternative for creating a connection.

An application uses a Connection object produced by a DataSource object in essentially the same way it uses a Connection object produced by the DriverManager. There are some differences, however. If the Connection object is a pooled connection, an application should include a finally block to assure that the connection is closed even if an exception is thrown. That way a valid connection will always be put back into the pool of available connections.

If a Connection object is part of a distributed transaction, an application should not call the methods Connection.commit or Connection.rollback, nor should it turn on the connection's auto-commit mode. These would interfere with the transaction manager's handling of the distributed transaction.

2.1.2 URLs in General Use

When an application uses the DriverManager to create a Connection object, it must supply a URL to the DriverManager.getConnection method. Since URLs often cause some confusion, we will first give a brief explanation of URLs in general and then go on to a discussion of JDBC URLs.

A URL (Uniform Resource Locator) gives information for locating a resource on the Internet. It can be thought of as an address.

The first part of a URL specifies the protocol used to access information, and it is always followed by a colon. Some common protocols are ftp, which specifies "file transfer protocol," and http, which specifies "hypertext transfer protocol." If the protocol is file, it indicates that the resource is in a local file system rather than on the Internet.

      ftp://javasoft.com/docs/JDK-1_apidocs.zip
      http://java.sun.com/products/JDK/CurrentRelease
      file:/home/haroldw/docs/tutorial.html

The rest of a URL, everything after the first colon, gives information about where the data source is located. If the protocol is file, the rest of the URL is the path for the file. For the protocols ftp and http, the rest of the URL identifies the host and may optionally give a path to a more specific site. For example, here is the URL for the Java Software home page. This URL identifies only the host:

http://www.java.sun.com

By navigating from this home page, you can go to many other pages, one of which is the JDBC home page. The URL for the JDBC home page is more specific and looks like this:

http://www.java.sun.com/products/jdbc

2.1.3 JDBC URLs

A JDBC URL provides a way of identifying a data source so that the appropriate driver will recognize it and establish a connection with it. Driver writers are the ones who actually determine what the JDBC URL that identifies a particular driver will be. Users do not need to worry about how to form a JDBC URL; they simply use the URL supplied with the drivers they are using. JDBC's role is to recommend some conventions for driver writers to follow in structuring their JDBC URLs.

Since JDBC URLs are used with various kinds of drivers, the conventions are, of necessity, very flexible. First, they allow different drivers to use different schemes for naming databases. The odbc subprotocol, for example, lets the URL contain attribute values (but does not require them).

Second, JDBC URLs allow driver writers to encode all necessary connection information within them. This makes it possible, for example, for an applet that wants to talk to a given database to open the database connection without requiring the user to do any system administration chores.

Third, JDBC URLs allow a level of indirection. This means that the JDBC URL may refer to a logical host or database name that is dynamically translated to the actual name by a network naming system. This allows system administrators to avoid specifying particular hosts as part of the JDBC name. There are a number of different network name services (such as DNS, NIS, and DCE), and there is no restriction about which ones can be used.

The standard syntax for JDBC URLs is shown here. It has three parts, which are separated by colons.

    jdbc:<subprotocol>:<subname>

The three parts of a JDBC URL are broken down as follows:

  1. jdbc-the protocol. The protocol in a JDBC URL is always jdbc.

  2.  <subprotocol>-the name of the driver or the name of a database connectivity mechanism, which may be supported by one or more drivers. A prominent example of a subprotocol name is odbc, which has been reserved for URLs that specify ODBC-style data source names. For example, to access a database through a JDBC-ODBC bridge, one might use a URL such as the following:

        jdbc:odbc:fred

In this example, the subprotocol is odbc, and the subname fred is a local ODBC data source.

    If one wants to use a network name service (so that the database name in the JDBC URL does not have to be its actual name), the naming service can be the subprotocol. So, for example, one might have a URL like:

        jdbc:dcenaming:accounts-payable

In this example, the URL specifies that the local DCE naming service should resolve the database name accounts-payable into a more specific name that can be used to connect to the real database.

  3. <subname>-a way to identify the data source. The subname can vary, depending on the subprotocol, and it can have any internal syntax the driver writer chooses, including a subsubname. The point of a subname is to give enough information to locate the data source. In the previous example, fred is enough because ODBC provides the remainder of the information. A data source on a remote server requires more information, however. If the data source is to be accessed over the Internet, for example, the network address should be included in the JDBC URL as part of the subname and should adhere to the following standard URL naming convention:

         //hostname:port/subsubname

Supposing that dbnet is a protocol for connecting to a host on the Internet, a JDBC URL might look like this:

        jdbc:dbnet://wombat:356/fred

2.1.4	 The odbc Subprotocol

The subprotocol odbc is a special case. It has been reserved for URLs that specify ODBC-style data source names and has the special feature of allowing any number of attribute values to be specified after the subname (the data source name). The full syntax for the odbc subprotocol is:

  jdbc:odbc:<data-source-name>[;<attribute-name>=<attribute-value>]*

Thus all of the following are valid jdbc:odbc names:

     jdbc:odbc:qeor7
     jdbc:odbc:wombat
     jdbc:odbc:wombat;CacheSize=20;ExtensionCase=LOWER
     jdbc:odbc:qeora;UID=kgh;PWD=fooey

2.1.5	 Registering Subprotocols

A driver developer can reserve a name to be used as the subprotocol in a JDBC URL. When the DriverManager class presents this name to its list of registered drivers, the driver for which this name is reserved should recognize it and establish a connection to the database it identifies. For example, "odbc" is reserved for the JDBC-ODBC Bridge. If there were a Miracle Corporation, it might want to register "miracle" as the subprotocol for the JDBC driver that connects to its Miracle DBMS so that no one else would use that name.

Java Software is acting as an informal registry for JDBC subprotocol names. To register a subprotocol name, send email to:

    jdbc@eng.sun.com

2.1.6	 Sending SQL Statements

Once a connection is established, it is used to pass SQL statements to its underlying database. The JDBC API does not put any restrictions on the kinds of SQL statements that can be sent; this provides a great deal of flexibility, allowing the use of database-specific statements or even non-SQL statements. It requires, however, that the user be responsible for making sure that the underlying database can process the SQL statements being sent and suffer the consequences if it cannot. For example, an application that tries to send a stored procedure call to a DBMS that does not support stored procedures will be unsuccessful and will generate an exception.

The JDBC API provides three interfaces for sending SQL statements to the database, and corresponding methods in the Connection interface create instances of them. The interfaces for sending SQL statements and the Connection methods that create them are as follows:

  1. Statement-created by the Connection.createStatement methods. A Statement object is used for sending SQL statements with no parameters.

  2. PreparedStatement-created by the Connection.prepareStatement methods. A PreparedStatement object is used for precompiled SQL statements. These can take one or more parameters as input arguments (IN parameters). PreparedStatement has a group of methods that set the value of IN parameters, which are sent to the database when the statement is executed. PreparedStatement extends Statement and therefore includes Statement methods. A PreparedStatement object has the potential to be more efficient than a Statement object because it has been precompiled and stored for future use. Therefore, in order to improve performance, a PreparedStatement object is sometimes used for an SQL statement that is executed many times.

  3. CallableStatement-created by the Connection.prepareCall methods. CallableStatement objects are used to execute SQL stored procedures-a group of SQL statements that is called by name, much like invoking a function. A CallableStatement object inherits methods for handling IN parameters from PreparedStatement; it adds methods for handling OUT and INOUT parameters.

The following list gives a quick way to determine which Connection method is appropriate for creating different types of SQL statements:

  • createStatement methods-for a simple SQL statement (no parameters)

  • prepareStatement methods-for an SQL statement that is executed frequently

  • prepareCall methods-for a call to a stored procedure

The versions of these methods that take no arguments create statements that will produce default ResultSet objects; that is, they produce result sets that are not scrollable and that cannot be updated. With the JDBC 2.0 API, it is possible to create statements that will produce result sets that are scrollable and/or updatable. This is done by using new versions of the methods createStatement, prepareStatement, and prepareCall that take additional parameters for specifying the type of result set and the concurrency level of the result set being created. In Chapter 5, "ResultSet," the section on the types of ResultSet objects on page 52 explains the different types of ResultSet objects and the constants that specify them. The section "Concurrency Types" on page  53 does the same for concurrency levels. "Creating Different Types of Result Sets" on page  55 gives examples of how to create ResultSet objects using the new versions of the Connection methods for creating statements.

2.1.7	 Transactions

A transaction consists of one or more statements that have been executed, completed, and then either committed or rolled back. When the method commit or rollback is called, the current transaction ends and another one begins.

Generally a new Connection object is in auto-commit mode by default, meaning that when a statement is completed, the method commit will be called on that statement automatically. In this case, since each statement is committed individually, a transaction consists of only one statement. If auto-commit mode has been disabled, a transaction will not terminate until the method commit or rollback is called explicitly, so it will include all the statements that have been executed since the last invocation of either commit or rollback. In this second case, all the statements in the transaction are committed or rolled back as a group.

The beginning of a transaction requires no explicit call; it is implicitly initiated after disabling auto-commit mode or after calling the methods commit or rollback. The method commit makes permanent any changes an SQL statement makes to a database, and it also releases any locks held by the transaction. The method rollback will discard those changes.

 Sometimes a user doesn't want one change to take effect unless another one does also. This can be accomplished by disabling auto-commit and grouping both updates into one transaction. If both updates are successful, then the commit method is called, making the effects of both updates permanent; if one fails or both fail, then the rollback method is called, restoring the values that existed before the updates were executed.

Most JDBC drivers will support transactions. In order to be designated JDBC Compliant, a JDBC driver must support transactions.

The JDBC 2.0 Standard Extension API makes it possible for Connection objects to be part of a distributed transaction, a transaction that involves connections to more than one DBMS server. When a Connection object is part of a distributed transaction, a transaction manager determines when the methods commit or rollback are called on it. Thus, when a Connection object is participating in a distributed transaction, an application should not do anything that affects when a connection begins or ends.

In order to be able to participate in distributed transactions, a Connection object must be produced by a DataSource object that has been implemented to work with the middle tier server's distributed transaction infrastructure. Unlike Connection objects produced by the DriverManager, a Connection object produced by such a DataSource object will have its auto-commit mode disabled by default. A standard implementation of a DataSource object, on the other hand, will produce Connection objects that are exactly the same as those produced by the DriverManager class.

2.1.8	 Transaction Isolation Levels

If a DBMS supports transaction processing, it will have some way of managing potential conflicts that can arise when two transactions are operating on a database at the same time. A user can specify a transaction isolation level to indicate what level of care the DBMS should exercise in resolving potential conflicts. For example, what happens when one transaction changes a value and a second transaction reads that value before the change has been committed or rolled back? Should that be allowed, given that the changed value read by the second transaction will be invalid if the first transaction is rolled back? A JDBC user can instruct the DBMS to allow a value to be read before it has been committed (a "dirty read") with the following code, where con is the current connection:

con.setTransactionIsolation(TRANSACTION_READ_UNCOMMITTED);

The higher the transaction isolation level, the more care is taken to avoid conflicts. The Connection interface defines five levels, with the lowest specifying that transactions are not supported at all and the highest specifying that while one transaction is operating on a database, no other transactions may make any changes to the data read by that transaction. TRANSACTION_READ_UNCOMMITTED, used in the previous example, is one level up from the lowest level. Typically, the higher the level of isolation, the slower the application executes (due to increased locking overhead and decreased concurrency between users). The developer must balance the need for performance with the need for data consistency when making a decision about what isolation level to use. Of course, the level that can actually be supported depends on the capabilities of the underlying DBMS.

When a new Connection object is created, its transaction isolation level depends on the driver, but normally it is the default for the underlying data source. A user may call the method setIsolationLevel to change the transaction isolation level, and the new level will be in effect for the rest of the connection session. To change the transaction isolation level for just one transaction, one needs to set it before executing any statements in the transaction and then reset it after the transaction terminates. Changing the transaction isolation level during a transaction is not recommended, for it will trigger an immediate call to the method commit, causing any changes up to that point to be made permanent.

2.1.9	 Freeing DBMS Resources

It is recommended that programmers explicitly close connections and statements they have created when they are no longer needed.

A programmer writing code in the Java programming language and not using any outside resources does not need to worry about memory management. The garbage collector automatically removes objects when they are no longer being used and frees the memory they were using. When memory is running low, it will recycle discarded objects, making the memory they currently occupy available for quick reuse.

However, if an application uses external resources, as it does when it accesses a DBMS with the JDBC API, the garbage collector has no way of knowing the status of those resources. It will still recycle discarded objects, but if there is lots of free memory in the Java heap, it may garbage collect infrequently, even though the (small) amount of Java garbage is holding open large amounts of expensive database resources. Therefore, it is recommended that programmers explicitly close all connections (with the method Connection.close) and statements (with the method Statement.close) as soon as they are no longer needed, thereby freeing DBMS resources as early as possible. This applies especially to applications that are intended to work with different DBMSs because of variations from one DBMS to another.

Note that the method Connection.isClosed is guaranteed to return true only when it is called after the method Connection.close has been called. As a result, a programmer cannot depend on this method to indicate whether a connection is valid or not. Instead, a typical JDBC client can determine that a connection is invalid by catching the exception that is thrown when a JDBC operation is attempted.

2.1.10	 Using Type Maps

The two new SQL3 data types that are user-defined types (UDTs), SQL structured types and DISTINCT types, can be custom mapped to a class in the Java programming language. Like all the SQL3 data types, they have standard mappings, but a programmer may create a custom mapping as well. The fact that there is a custom mapping for a particular UDT is declared in a java.util.Map object. This Map object may be the one that is associated with a connection, or it may be one that is passed to a method.

A programmer declares a custom mapping by adding an entry to a Map object. This entry must contain two things: (1) the name of the UDT to be mapped and (2) the Class object for the class in the Java programming language to which the UDT is to be mapped. The class itself, which must implement the SQLData interface, will contain the specific mappings.

Each Connection object created using a JDBC 2.0 driver that supports custom mapping will have an empty type map to which custom mappings may be added. This type map is an instance of the interface java.util.Map, which is new in the Java 2 platform and replaces java.util.Dictionary. Until custom map entries are added to this type map, all operations for STRUCT and DISTINCT values will use the standard mappings (the Struct interface for STRUCT values and the underlying type for DISTINCT values).

The following code fragment, in which con is a Connection object and ADDRESSES is an SQL structured type, demonstrates retrieving the type map associated with con and adding a new entry to it. After the type map is modified, it is set as the new type map for con.

java.util.Map map = con.getTypeMap();
map.put("SchemaName.ADDRESSES", Class.forName("Addresses"));
con.setTypeMap();

The Map object map, the type map associated with con, now contains at least one custom mapping (or more if any mappings have already been added). The programmer will have previously created the class Addresses, probably using a tool to generate it. Note that it is an error to supply a class that does not implement the interface SQLData. The class Addresses, which does implement SQLData, will have a field for each attribute in ADDRESSES, and whenever a value of type ADDRESSES is operated on by a method in the Java programming language, the default will be to map it to an instance of the class Addresses. The type map associated with a connection is the default type map in the sense that a method will use it if no other type map is explicitly passed to it.

Note that the name of the UDT should be the fully-qualified name. For some DBMSs, this will be of the form catalogName.schemaName.UDTName. Many DBMSs, however, do not use this form and, for example, use a schema name but no catalog name. The important thing is to use the form appropriate for a particular DBMS. The DatabaseMetaData methods getCatalogs, getCatalogTerm, getCatalogSeparator, getSchemas and getSchemaTerm give information about a DBMS's catalogs, schemas, preferred terms, and the separator it uses.

Instead of modifying the existing type map, an application can replace it with a completely different type map. This is done with the Connection method setTypeMap, as shown in the following code fragment. It creates a new type map, gives it two entries (each with an SQL UDT name and the class to which values of that type should be mapped), and then installs the new type map as the one associated with the Connection con.

java.util.Map newConnectionMap = new java.util.HashTable();
newConnectionMap.put(
     "SchemaName.UDTName1", Class.forName("className1"));
newConnectionMap.put(
     "SchemaName.UDTName2", Class.forName("className2"));
con.setTypeMap(newConnectionMap);

The Map object newConnectionMap now replaces the type map originally associated with the Connection con, and it will be used for custom type mappings unless it is itself replaced. Note that the example uses the default constructor for the class HashTable to create the new type map. This class is one of many implementations of java.util.Map provided in the Java 2 platform API, and one of the others could have been used as well.

In the previous examples, the type map associated with a connection was modified to contain additional mappings or set to be a different type map altogether. In either case, though, the connection's type map is the default for custom mapping JDBC types to types in the Java programming language. The next example will show how to supersede the connection's type map by supplying a method with a different type map.

Methods whose implementations may involve a custom mapping for UDTs have two versions, one that takes a type map and one that does not. If a type map is passed to one of these methods, the given type map will be used instead of the one associated with the connection. For example, the Array methods getArray and getResultSet have versions that take a type map and versions that do not. If a type map is passed to a method, it will map the array elements using the given type map. If no type map is specified, the method will use the type map associated with the connection.

The capability for supplying a type map to a method makes it possible for values of the same user-defined type to have different mappings. For example, if two applications are using the same connection and operating on the same column value, one could use the type map associated with the connection, and the other could use a different type map by supplying it as an argument to the appropriate method.

The following code fragment creates a new type map and provides it as a parameter to the Array method getArray.

java.util.Map arrayMap = new java.util.HashTable();
arrayMap.put("SchemaName.DIMENSIONS", Class.forName("Dimensions"));
Dimensions [] d = (Dimensions [])array.getArray(arrayMap);

In the second line, the new type map arrayMap is given an entry with the fully-qualified name of an SQL structured type (SchemaName.DIMENSIONS) and the Java class object (Class.forName("Dimensions")). This establishes the mapping between the Java type Dimensions and the SQL type DIMENSIONS. In the third line, arrayMap is specified as the type map to use for mapping the contents of this Array object, whose base type is SchemaName.DIMENSIONS.

The method getArray will materialize the elements of the SQL3 ARRAY value designated by array, with each element being mapped according to the mapping specified in arrayMap. In other words, each element, which is a value of type Schema.DIMENSIONS, will be translated to an instance of the class Dimensions by mapping the attributes of each DIMENSIONS value to the fields of a Dimensions object. If the base type of the array does not match the UDT named in arrayMap, the driver will convert the array's elements according to the standard mapping. If no type map is specified to the method getArray, the driver uses the mapping indicated in the connection's type map. If that type map has no entry for Schema.DIMENSIONS, the driver will instead use the standard mapping.

[Top] [Prev] [Next]

Copyright © 1999, Sun Microsystems, Inc.   All rights
reserved.


Copyright Page for Sun Microsystems, Inc.

Sun Microsystems, Inc.

Copyright 1996-1999 Sun Microsystems, Inc.
901 San Antonio Road, Palo Alto, California 94303-4900 U.S.A.

All rights reserved. Copyright in this document is owned by Sun Microsystems, Inc.

Sun Microsystems, Inc. (SUN) hereby grants to you a fully-paid, nonexclusive, nontransferable, perpetual, worldwide limited license (without the right to sublicense) under SUN's intellectual property rights that are essential to practice this specification. This license allows and is limited to the creation and distribution of clean room implementations of this specification that (i) include a complete implementation of the current version of this specification without subsetting or supersetting, (ii) implement all the interfaces and functionality of the standard java.* packages as defined by SUN, without subsetting or supersetting, (iii) do not add any additional packages, classes or methods to the java.* packages (iv) pass all test suites relating to the most recent published version of this specification that are available from SUN six (6) months prior to any beta release of the clean room implementation or upgrade thereto, (v) do not derive from SUN source code or binary materials, and (vi) do not include any SUN binary materials without an appropriate and separate license from SUN.

RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the U.S. Government is subject to restrictions of FAR 52.227-14(g)(2)(6/87) and FAR 52.227-19(6/87), or DFAR 252.227-7015(b)(6/95) and DFAR 227.7202-1(a).

This software and documentation is the confidential and proprietary information of Sun Microsystems, Inc. ("Confidential Information"). You shall not disclose such Confidential Information and shall use it only in accordance with the terms of the license agreement you entered into with Sun.

SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.

TRADEMARKS

Sun, the Sun logo, Sun Microsystems, SunNet Manager, SunCore, SunWeb, Sun Workshop, Sun Workstation, Java, the Java Coffee Cup logo, JavaSoft, JavaBeans, HotJava, HotJava Views, Java WorkShop, Visual Java, JDK and all Java-based trademarks and logos, Solaris, the Solaris sunburst design, SolarNet, Solstice, NEO, Joe, Netra, NFS, PC-NFS, ONC, ONC+, OpenWindows, SNM, The Network Is The Computer, ToolTalk, Ultra, Ultracomputing, Ultraserver, Where The Network Is Going, and XView, are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.

UNIX is a registered trademark in the United States and other countries, exclusively licensed through X/Open Company, Ltd. OPEN LOOK® is a registered trademark of Novell, Inc.

All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the United States and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc.

The OPEN LOOK® and Sun(TM) Graphical User Interfaces were developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun's licensees who implement OPEN LOOK GUIs and otherwise comply with Sun's written license agreements.

X Window System is a trademark of the X Consortium, Inc.

OpenStep is a trademark owned by NeXT and is used under license.

THIS PUBLICATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.

For further information on Intellectual Property matters, see Java Trademark Guidelines or contact Sun Legal Department:

  • Trademarks, Karrie Malouf at (650) 336-7419
  • Patents at 415-336-0069


 [Top] [Prev] [Next] [Bottom]

DataSource

NOTE: The material in this chapter is based on JDBCtm API Tutorial and Reference, Second Edition: Universal Data Access for the Javatm 2 Platform, published by Addison Wesley as part of the Java series, ISBN 0-201-43328-1.

4.1 DataSource Overview

A DataSource object is the representation of a data source in the Java programming language. In basic terms, a data source is a facility for storing data. It can be as sophisticated as a complex database for a large corporation or as simple as a file with rows and columns. A data source can reside on a remote server, or it can be on a local desktop machine. Applications access a data source using a connection, and a DataSource object can be thought of as a factory for connections to the particular data source that the DataSource instance represents. The DataSource interface provides two methods for establishing a connection with a data source.

Using a DataSource object is the preferred alternative to using the DriverManager for establishing a connection to a data source. They are similar to the extent that the DriverManager class and DataSource interface both have methods for creating a connection, methods for getting and setting a timeout limit for making a connection, and methods for getting and setting a stream for logging.

Their differences are more significant than their similarities, however. Unlike the DriverManager, a DataSource object has properties that identify and describe the data source it represents. Also, a DataSource object works with a Javatm Naming and Directory Interfacetm (JNDI) naming service and is created, deployed, and managed separately from the applications that use it. A driver vendor will provide a class that is a basic implementation of the DataSource interface as part of its JDBC 2.0 or 3.0 driver product. What a system administrator does to register a DataSource object with a JNDI naming service and what an application does to get a connection to a data source using a DataSource object registered with a JNDI naming service are described later in this chapter.

Being registered with a JNDI naming service gives a DataSource object two major advantages over the DriverManager. First, an application does not need to hardcode driver information, as it does with the DriverManager. A programmer can choose a logical name for the data source and register the logical name with a JNDI naming service. The application uses the logical name, and the JNDI naming service will supply the DataSource object associated with the logical name. The DataSource object can then be used to create a connection to the data source it represents.

The second major advantage is that the DataSource facility allows developers to implement a DataSource class to take advantage of features like connection pooling and distributed transactions. Connection pooling can increase performance dramatically by reusing connections rather than creating a new physical connection each time a connection is requested. The ability to use distributed transactions enables an application to do the heavy duty database work of large enterprises.

Although an application may use either the DriverManager or a DataSource object to get a connection, using a DataSource object offers significant advantages and is the recommended way to establish a connection.

4.1.1 Properties

A DataSource object has a set of properties that identify and describe the real world data source that it represents. These properties include information like the location of the database server, the name of the database, the network protocol to use to communicate with the server, and so on. DataSource properties follow the JavaBeans design pattern and are usually set when a DataSource object is deployed.

To encourage uniformity among DataSource implementations from different vendors, the JDBC 2.0 API specifies a standard set of properties and a standard name for each property. The following table gives the standard name, the data type, and a description for each of the standard properties. Note that a DataSource implementation does not have to support all of these properties; the table just shows the standard name that an implementation should use when it supports a property.

Table 4.1 Standard Data Source Properties
Property Name | Type | Description
databaseName property (DataSource interface)>databaseName | String | the name of a particular database on a server
dataSourceName property (DataSource interface)>dataSourceName | String | the logical name for the underlying XADataSource or ConnectionPoolDataSource object; used only when pooling of connections or distributed transactions are implemented
description property (DataSource interface)>description | String | a description of this data source
networkProtocol property (DataSource interface)>networkProtocol | String | the network protocol used to communicate with the server
password property (DataSource interface)>password | String | the user's database password
portNumber property (DataSource interface)>portNumber | int | the port number where a server is listening for requests
roleName property (DataSource interface)>roleName | String | the initial SQL rolename
serverName property (DataSource interface)>serverName | String | the database server name
user property (DataSource interface)>user | String | the user's account name

A DataSource object will, of course, have to support all of the properties that the data source it represents needs for making a connection, but the only property that all DataSource implementations are required to support is the description property. This standardizing of properties makes it possible, for instance, for a utility to be written that lists available data sources, giving a description of each along with the other property information that is available.

A DataSource object is not restricted to using only those properties specified in Table 4.1. A vendor may add its own properties, in which case it should give each new property a vendor-specific name.

If a DataSource object supports a property, it must supply getter and setter methods for it. The following code fragment illustrates the methods that a DataSource object ds would need to include if it supports, for example, the property serverName.

ds.setServerName("my_database_server");
String serverName = ds.getServerName();

Properties will most likely be set by a developer or system administrator using a GUI tool as part of the installation of the data source. Users connecting to the data source do not get or set properties. This is enforced by the fact that the DataSource interface does not include the getter and setter methods for properties; they are supplied only in a particular implementation. The effect of including getter and setter methods in the implementation but not the public interface creates some separation between the management API for DataSource objects and the API used by applications. Management tools can get at properties by using introspection.

4.1.2 Using JNDI

JNDI provides a uniform way for an application to find and access remote services over the network. The remote service may be any enterprise service, including a messaging service or an application-specific service, but, of course, a JDBC application is interested mainly in a database service. Once a DataSource object is created and registered with a JNDI naming service, an application can use the JNDI API to access that DataSource object, which can then be used to connect to the data source it represents.

4.1.3 Creating and Registering a DataSource Object

A DataSource object is usually created, deployed, and managed separately from the Java applications that use it. For example, the following code fragment creates a DataSource object, sets its properties, and registers it with a JNDI naming service. Note that a DataSource object for a particular data source is created and deployed by a developer or system administrator, not the user. The class VendorDataSource would most likely be supplied by a driver vendor. (The code example in the next section will show the code that a user would write to get a connection.) Note also that a GUI tool will probably be used to deploy a DataSource object, so the following code, shown here mainly for illustration, is what such a tool would execute.

VendorDataSource vds = new VendorDataSource();

vds.setServerName("my_database_server");
vds.setDatabaseName("my_database");
vds.setDescription("the data source for inventory and personnel");

Context ctx = new InitialContext();

ctx.bind("jdbc/AcmeDB", vds);

The first four lines represent API from a vendor's class VendorDataSource, an implementation of the javax.sql.DataSource interface. They create a DataSource object, vds, and set its serverName, databaseName, and description properties. The fifth and sixth lines use JNDI API to register vds with a JNDI naming service. The fifth line calls the default InitialContext constructor to create a Java object that references the initial JNDI naming context. System properties, which are not shown here, tell JNDI which naming service provider to use. The last line associates vds with a logical name for the data source that vds represents.

The JNDI namespace consists of an initial naming context and any number of subcontexts under it. It is hierarchical, similar to the directory/file structure in many file systems, with the initial context being analogous to the root of a file system and subcontexts being analogous to subdirectories. The root of the JNDI hierarchy is the initial context, here represented by the variable ctx. Under the initial context there may be many subcontexts, one of which is jdbc, the JNDI subcontext reserved for JDBC data sources. (The logical data source name may be in the subcontext jdbc or in a subcontext under jdbc.) The last element in the hierarchy is the object being registered, analogous to a file, which in this case is a logical name for a data source. The result of the preceding six lines of code is that the VendorDataSource object vds is associated with jdbc/AcmeDB. The following section shows how an application uses this to connect to a data source.

4.1.4 Connecting to a Data Source

In the previous section, a DataSource object, vds, was given properties and bound to the logical name AcmeDB. The following code fragment shows application code that uses this logical name to connect to the database that vds represented. The code then uses the connection to print lists with the name and title of each member of the sales and customer service departments.

Context ctx = new InitialContext();

DataSource ds = (DataSource)ctx.lookup("jdbc/AcmeDB");
Connection con = ds.getConnection("genius", "abracadabra");
con.setAutoCommit(false);
PreparedStatement pstmt = con.prepareStatement(
                            "SELECT NAME, TITLE FROM PERSONNEL WHERE DEPT = ?");
pstmt.setString(1, "SALES");
ResultSet rs = pstmt.executeQuery();

System.out.println("Sales Department:");
while (rs.next()) {
        String name = rs.getString("NAME");
        String title = rs.getString("TITLE");
        System.out.println(name + "     " + title);
}
pstmt.setString(1, "CUST_SERVICE");
ResultSet rs = pstmt.executeQuery();

System.out.println("Customer Service Department:");
while (rs.next()) {
        String name = rs.getString("NAME");
        String title = rs.getString("TITLE");
        System.out.println(name + "     " + title);
}
rs.close();
pstmt.close();

con.close();

The first two lines use JNDI API; the third line uses DataSource API. After the first line creates an instance of javax.naming.Context for the initial naming context, the second line calls the method lookup on it to get the DataSource object associated with jdbc/AcmeDB. Recall that in the previous code fragment, the last line of code associated jdbc/AcmeDB with vds, so the object returned by the lookup method refers to the same DataSource object that vds represented. However, the return value for the method lookup is a reference to a Java Object, the most generic of objects, so it must be cast to the more narrow DataSource before it can be assigned to the DataSource variable ds.

At this point ds refers to the same data source that vds referred to previously, the database my_database on the server my_database_server. Therefore, in the third line of code, calling the method DataSource.getConnection on ds and supplying it with a user name and password is enough to create a connection to my_database.

The rest of the code fragment uses a single transaction to execute two queries and print the results of each query. The DataSource implementation in this case is a basic implementation included with the JDBC driver. If the DataSource class had been implemented to work with an XADataSource class, and the preceding code example was executed in the context of a distributed transaction, the code could not have called the method Connection.commit. It also would not have set the auto-commit mode to false because that would have been unnecessary. The default for newly-created connections that can participate in distributed transactions is to have auto-commit mode turned off. The next section will discuss the three broad categories of DataSource implementations.

In addition to the version of getConnection that takes a user name and password, the DataSource interface provides a version of the method DataSource.getConnection that takes no parameters. It is available for situations where a data source does not require a user name and password because it uses a different security mechanism or where a data source does not restrict access.

4.1.5 DataSource Implementations

The DataSource interface may be implemented to provide three different kinds of connections. As a result of DataSource objects working with a JNDI service provider, all connections produced by a DataSource object offer the advantages of portability and easy maintenance, which are explained later in this chapter. Implementations of DataSource that work with implementations of the more specialized ConnectionPoolDataSource and XADataSource interfaces produce connections that are pooled or that can be used in distributed transactions. The following list summarizes the three general categories of classes that implement the DataSource interface:

  1. Basic DataSource class
    • provided by: driver vendor
    • advantages: portability, easy maintenance
  2. DataSource class implemented to provide connection pooling
    • provided by: application server vendor or driver vendor
    • works with: a ConnectionPoolDataSource class, which is always provided by a driver vendor
    • advantages: portability, easy maintenance; increased performance
  3. DataSource class implemented to provide distributed transactions
    • provided by: application server vendor such as an EJB server vendor
    • works with: an XADataSource class, which is always provided by a driver vendor
    • advantages: portability, easy maintenance; ability to participate in distributed transactions
      Note that a DataSource implementation that supports distributed transactions is almost always implemented to support connection pooling as well.

      An instance of a class that implements the DataSource interface represents one particular data source. Every connection produced by that instance will reference the same data source. In a basic DataSource implementation, a call to the method DataSource.getConnection returns a Connection object that, like the Connection object returned by the DriverManager facility, is a physical connection to the data source. Appendix A of the specification for the JDBC 2.0 Standard Extension API (available at http://java.sun.com/products/jdbc) gives a sample implementation of a basic DataSource class.

      DataSource objects that implement connection pooling likewise produce a connection to the particular data source that the DataSource class represents. The Connection object that the method DataSource.getConnection returns, however, is a handle to a PooledConnection object rather than being a physical connection. An application uses the Connection object just as it usually does and is generally unaware that it is in any way different. Connection pooling has no effect whatever on application code except that a pooled connection, as is true with all connections, should always be explicitly closed. When an application closes a connection that is pooled, the connection joins a pool of reusable connections. The next time DataSource.getConnection is called, a handle to one of these pooled connections will be returned if one is available. Because connection pooling avoids creating a new physical connection every time one is requested, it can help to make applications run significantly faster. Connection pooling is generally used, for example, by a web server that supports servlets and JavaServertm Pages.

      A DataSource class can likewise be implemented to work with a distributed transaction environment. An EJB server, for example, supports distributed transactions and requires a DataSource class that is implemented to interact with it. In this case, the DataSource.getConnection method returns a Connection object that can be used in a distributed transaction. As a rule, EJB servers provide a DataSource class that supports connection pooling as well as distributed transactions. Like connection pooling, transaction management is handled internally, so using distributed transactions is easy. The only requirement is that when a transaction is distributed (involves two or more data sources), the application cannot call the methods commit or rollback. It also cannot put the connection in auto-commit mode. The reason for these restrictions is that a transaction manager begins and ends a distributed transaction under the covers, so an application cannot do anything that would affect when a transaction begins or ends.

4.1.6 Logging and Tracing

The DataSource interface provides methods that allow a user to get and set the character stream to which tracing and error logging will be written. A user can trace a specific data source on a given stream, or multiple data sources can write log messages to the same stream provided that the stream is set for each data source. Log messages that are written to a log stream specific to a DataSource object are not written to the log stream maintained by the DriverManager.

4.1.7 Advantages of Using JNDI

There are major advantages to connecting to a data source using a DataSource object registered with a JNDI naming service rather than using the DriverManager facility. The first is that it makes code more portable. With the DriverManager, the name of a JDBC driver class, which usually identifies a particular driver vendor, is included in application code. This makes the application specific to that vendor's driver product and thus non-portable.

Another advantage is that it makes code much easier to maintain. If any of the necessary information about the data source changes, only the relevant DataSource properties need to be modified, not every application that connects to that data source. For example, if a database is moved to a different server and uses a different port number, only the DataSource object's serverName and portNumber properties need to be updated. A system administrator could keep all existing code usable with the following code fragment. In practice, a system administrator would probably use a GUI tool to set the properties, so the following code fragment illustrates the code a tool might execute internally.

Context ctx = new InitialContext()

DataSource ds = (DataSource)ctx.lookup("jdbc/AcmeDB");
ds.setServerName("my_new_database_server");

ds.setPortNumber("940");

The application programmer would not need to do anything at all to keep all of the applications using the data source running smoothly.

Yet another advantage is that applications using a DataSource object to get a connection will automatically benefit from connection pooling if the DataSource class has been implemented to support connection pooling. Likewise, an application will automatically be able to use distributed transactions if the DataSource class has been implemented to support them.

[Top] [Prev] [Next] [Bottom]

Copyright © 2001, Sun Microsystems, Inc. All rights reserved.


 [Top] [Prev] [Next]

DriverManager

NOTE: The material in this chapter is based on JDBCtm API Tutorial and Reference, Second Edition: Universal Data Access for the Javatm 2 Platform, published by Addison Wesley as part of the Java series, ISBN 0-201-43328-1.

3.1 DriverManager Overview

The DriverManager class is the traditional management layer of JDBC, working between the user and the drivers. It keeps track of the drivers that are available and handles establishing a connection between a database and the appropriate driver. In addition, the DriverManager class attends to things like driver login time limits and the printing of log and tracing messages.

Note that the javax.sql package, otherwise known as the JDBC 2.0 Standard Extension API, provides the DataSource interface as an alternate and preferred means of connecting to a data source. However, the DriverManager facility can still be used with drivers that support DataSource implementations.

For simple applications, the only method in the DriverManager class that a general programmer needs to use directly is DriverManager.getConnection. As its name implies, this method establishes a connection to a database. An application may call the DriverManager methods getDriver, getDrivers, and registerDriver as well as the Driver method connect, but in most cases it is better to let the DriverManager class manage the details of establishing a connection.

3.1.1 Keeping Track of Available Drivers

The DriverManager class maintains a list of Driver classes that have registered themselves by calling the method DriverManager.registerDriver. All Driver classes should be written with a static section (a static initializer) that creates an instance of the class and then registers it with the DriverManager class when it is loaded. Thus, a user would not normally call DriverManager.registerDriver directly; it should be called automatically by a Driver class when it is loaded. A Driver class is loaded, and therefore automatically registered with the DriverManager, in one of two ways:

  1. by calling the method Class.forName. This explicitly loads the driver class. Since it does not depend on any external setup, this way of loading a driver is the recommended one for using the DriverManager framework. The following code loads the class acme.db.Driver:
    Class.forName("acme.db.Driver");

    If acme.db.Driver has been written so that loading it causes an instance to be created and also calls DriverManager.registerDriver with that instance as the parameter (as it should do), then it is in the DriverManager's list of drivers and available for creating a connection.

  2. by adding the Driver class to the java.lang.System property jdbc.drivers. This is a list of driver classnames, separated by colons, that the DriverManager class loads. When the DriverManager class is initialized, it looks for the system property "jdbc.drivers," and if the user has entered one or more drivers, the DriverManager class attempts to load them. The following code illustrates how a programmer might enter three driver classes in ~/.hotjava/properties (HotJava loads these into the system properties list on startup):
jdbc.drivers=foo.bah.Driver:wombat.sql.Driver:bad.test.ourDriver
The first call to a DriverManager method will automatically cause these driver classes to be loaded.

Note that this second way of loading drivers requires a preset environment that is persistent. If there is any doubt about that being the case, it is safer to call the method Class.forName to explicitly load each driver. This is also the right method to use to bring in a particular driver since once the DriverManager class has been initialized, it will never recheck the jdbc.drivers property list.

In both of these cases, it is the responsibility of the newly-loaded Driver class to register itself by calling DriverManager.registerDriver. As mentioned, this should be done automatically when the class is loaded.

For security reasons, the JDBC management layer will keep track of which class loader provided which driver. Then when the DriverManager class is opening a connection, it will use only drivers that come from the local file system or from the same class loader as the code issuing the request for a connection.

3.1.2 Establishing a Connection

Once the Driver classes have been loaded and registered with the DriverManager class, they are available for establishing a connection with a database. When a request for a connection is made with a call to the DriverManager.getConnection method, the DriverManager tests each driver in turn to see if it can establish a connection.

It may sometimes be the case that more than one JDBC driver is capable of connecting to a given URL. For example, when connecting to a given remote database, it might be possible to use a JDBC-ODBC bridge driver, a JDBC-to-generic-network-protocol driver, or a driver supplied by the database vendor. In such cases, the order in which the drivers are tested is significant because the DriverManager will use the first driver it finds that can successfully connect to the given URL.

First the DriverManager tries to use each driver in the order it was registered. (The drivers listed in jdbc.drivers are always registered first.) It will skip any drivers that are untrusted code unless they have been loaded from the same source as the code that is trying to open the connection.

It tests the drivers by calling the method Driver.connect on each one in turn, passing them the URL that the user originally passed to the method DriverManager.getConnection. The first driver that recognizes the URL makes the connection.

At first glance this may seem inefficient, but it requires only a few procedure calls and string comparisons per connection since it is unlikely that dozens of drivers will be loaded concurrently.

The following code is an example of all that is normally needed to set up a connection with a driver such as a JDBC-ODBC bridge driver.

Class.forName("jdbc.odbc.JdbcOdbcDriver"); //loads the driver
String url = "jdbc:odbc:fred";
Connection con = DriverManager.getConnection(
        url, "userID", "passwd");

The variable con represents a connection to the data source "fred" that can be used to create and execute SQL statements.

With the addition of the JDBC 2.0 Standard Extension API, a DataSource object can be used to establish a connection with a data source. The DriverManager can still be used, but a DataSource object offers several advantages over the DriverManager and is the preferred alternative. Developers who are writing Enterprise JavaBeans components, however, should always use a DataSource object instead of the DriverManager. Using a properly implemented DataSource object is the only way to get connections that are pooled and that can participate in distributed transactions.

3.1.3 DriverManager Methods Are Static

All DriverManager methods are declared static, which means that they operate on the class as a whole and not on particular instances. In fact, the constructor for DriverManager is declared private to prevent users from instantiating it. Logically, there is one instance of the DriverManager class. This means that methods are called by qualifying them with DriverManager, as in the following line of code.

DriverManager.setLogWriter(out);

[Top] [Prev] [Next]

Copyright © 1999, Sun Microsystems, Inc.   All rights
reserved.


 [Top] [Prev] [Next] [Bottom]

Getting Started with the JDBC API

1 Introduction

1.1 What the JDBC 3.0 API Includes . . . . . . . . . . . . .
1.2 What Is the JDBC API?
1.2.1 What Does the JDBC API Do?
1.2.2 A Base for Other APIs
1.2.3 The JDBC API Versus ODBC and UDA
1.2.4 Two-tier and Three-tier Models
1.2.5 SQL Conformance
1.2.6 JDBC Products
1.2.7 Java Software Framework
1.2.8 JDBC Driver Types
1.2.9 Obtaining JDBC Drivers
1.2.10 Java-relational DBMSs
1.2.11 Other Products

2 Connection

2.1 Connection Overview . . . . . . . . . . . . .
2.1.1 Opening a Connection
2.1.2 URLs in General Use
2.1.3 JDBC URLs
2.1.4 The odbc Subprotocol
2.1.5 Registering Subprotocols
2.1.6 Sending SQL Statements
2.1.7 Transactions
2.1.8 Transaction Isolation Levels
2.1.9 Savepoints
2.1.10 Freeing DBMS Resources
2.1.11 Using Type Maps

3 DriverManager

3.1 DriverManager Overview . . . . . . . . . . . . .
3.1.1 Keeping Track of Available Drivers
3.1.2 Establishing a Connection
3.1.3 DriverManager Methods Are Static

4 DataSource

4.1 DataSource Overview . . . . . . . . . . . . .
4.1.1 Properties
4.1.2 Using JNDI
4.1.3 Creating and Registering a DataSource Object
4.1.4 Connecting to a Data Source
4.1.5 DataSource Implementations
4.1.6 Logging and Tracing
4.1.7 Advantages of Using JNDI

5 Statement

5.1 Statement Overview . . . . . . . . . . . . .
5.1.1 Creating Statement Objects
5.1.2 Executing Statements Using Statement Objects
5.1.3 Statement Completion
5.1.4 Retrieving Automatically Generated Keys
5.1.5 Closing Statements
5.1.6 SQL Escape Syntax in Statements
5.1.7 Sending Batch Updates
5.1.8 Giving Performance Hints
5.1.9 Executing Special Kinds of Statements

6 ResultSet

6.1 ResultSet Overview . . . . . . . . . . . . .
6.1.1 Rows and Columns
6.1.2 Cursors
6.1.3 Cursor Movement Examples
6.1.4 Determining the Number of Rows in a Result Set
6.1.5 Retrieving Column Values
6.1.6 Which getter Method to Use
6.1.7 Types of Result Sets
6.1.8 Concurrency Types
6.1.9 Holdability
6.1.10 Providing Performance Hints
6.1.11 Creating Different Types of Result Sets
6.1.12 Using a Prepared Statement to Create Result Sets
6.1.13 Requesting Features That Are Not Supported
6.1.14 Using updater Methods
6.1.15 Deleting a Row
6.1.16 Inserting Rows
6.1.17 Positioned Updates
6.1.18 Queries That Produce Updatable Result Sets
6.1.19 Using Streams for Very Large Row Values
6.1.20 NULL Result Values
6.1.21 Closing a ResultSet Object
6.1.22 JDBC Compliance

7 PreparedStatement

7.1 PreparedStatement Overview . . . . . . . . . . . . .
7.1.1 Creating PreparedStatement Objects
7.1.2 Passing IN Parameters
7.1.3 Parameter Metadata
7.1.4 Data Type Conformance on IN Parameters
7.1.5 Using setObject
7.1.6 Sending JDBC NULL as an IN parameter
7.1.7 Sending Very Large IN Parameters
7.1.8 Using PreparedStatement Objects in Batch Updates

8 CallableStatement

8.1 CallableStatement Overview . . . . . . . . . . . . .
8.1.1 Creating a CallableStatement Object
8.1.2 IN Parameters
8.1.3 Making Batch Updates
8.1.4 OUT Parameters
8.1.5 Numbering of Parameters
8.1.6 INOUT Parameters
8.1.7 Retrieve OUT Parameters after Results
8.1.8 Retrieving NULL Values as OUT Parameters

9 Mapping SQL and Java Types

9.1 Mapping Overview . . . . . . . . . . . . .
9.2 Mapping SQL Types to Java Types
9.3 Basic JDBC Types
9.3.1 CHAR, VARCHAR, and LONGVARCHAR
9.3.2 BINARY, VARBINARY, and LONGVARBINARY
9.3.3 BIT
9.3.4 BOOLEAN
9.3.5 TINYINT
9.3.6 SMALLINT
9.3.7 INTEGER
9.3.8 BIGINT
9.3.9 REAL
9.3.10 DOUBLE
9.3.11 FLOAT
9.3.12 DECIMAL and NUMERIC
9.3.13 DATE, TIME, and TIMESTAMP
9.4 Advanced JDBC Data Types
9.4.1 DATALINK
9.4.2 BLOB
9.4.3 CLOB
9.4.4 ARRAY
9.4.5 DISTINCT
9.4.6 STRUCT
9.4.7 REF
9.4.8 JAVA_OBJECT
9.5 Examples of Mapping
9.5.1 Simple SQL Statement
9.5.2 SQL Statement with IN Parameters
9.5.3 SQL Statement with INOUT Parameters
9.6 Custom Mapping
9.7 Dynamic Data Access
9.8 Storing Java Objects in a Database
9.9 Tables for Type Mapping
9.9.1 JDBC Types Mapped to Java Types
9.9.2 Java Types Mapped to JDBC Types
9.9.3 JDBC Types Mapped to Java Object Types
9.9.4 Java Object Types Mapped to JDBC Types
9.9.5 Conversions by setObject
9.9.6 Conversions by ResultSet.getter Methods
9.9.7 JDBC Types Mapped to Database-specific SQL Types

10 Rowset
10.1 Rowset Overview
10.1.1 The Event Model for Rowsets
10.1.2 Properties for a Rowset
10.1.3 Setting Parameters for the Command String
10.1.4 Traversing a RowSet Object
10.1.5 Executing a Command
10.1.6 Using a RowSet Object's Metadata
10.2 Standard Implementations
10.2.1 Implementation Basics
10.2.2 Overview of the JdbcRowSet Implementation
10.2.3 Overview of the CachedRowSet Implementation
10.2.4 Uses for a CachedRowSet Object
10.2.5 Creating a CachedRowSet Object
10.2.6 Setting a SyncProvider Object
10.2.7 Populating a CachedRowSet Object
10.2.8 Accessing Data
10.2.9 Modifying Data
10.2.10 Customizing Readers and Writers
10.2.11 Other Methods
10.2.12 Using the javax.sql.rowset.spi Package
10.2.13 CachedRowSet Summary
10.2.14 WebRowSet Implementation
10.2.15 FilteredRowSet Implementation
10.2.16 JoinRowSet Implementation

JDBC-ODBC Bridge Enhancements

Appendix A: Summary of New Features

A.1 Overview of JDBC 3.0 API Changes
A.1.1 Features Introduced in the JDBC 3.0 API
A.1.2 Features Introduced in the JDBC 2.0 Optional Package
A.2 Overview of JDBC 2.0 Core API Changes
A.3 Summary of New Functionality
A.3.1 Scrollable Result Sets
A.3.2 Batch Updates
A.3.3 Programmatic Updates
A.3.4 Other New Features
A.4 Support for Advanced Data Types
A.4.1 What Are the SQL99 Data Types?
A.4.2 Summary of Support for the SQL99 Data Types
A.4.3 Mapping of the SQL99 Types
A.4.4 SQL Locators
A.4.5 Support for Storing Java Objects

Appendix B: Sample Code

[Top] [Prev] [Next] [Bottom]

Copyright © 2001, Sun Microsystems, Inc. All rights reserved.


 [Top] [Prev] [Next]

Introduction

NOTE: The material in this chapter is based on JDBCtm API Tutorial and Reference, Second Edition: Universal Data Access for the Javatm 2 Platform, published by Addison Wesley as part of the Java series, ISBN 0-201-43328-1.

The JDBCtm API is the application programming interface that provides universal data access for the Javatm programming language. It includes the JDBC 1.0 API, which provides the basic functionality for data access. The JDBC 2.0 API supplements the basic API with more advanced features and provides a standard way to access the latest object-relational features being supported by today's relational database management systems. In addition, the new API includes features such as scrollable and updatable result sets and improved performance. It also extends JDBC technology beyond the client to the server with connection pooling and distributed transactions.

1.1 What the JDBC 2.0 API Includes

The JDBC 2.0 API includes all of the API that is part of Java SE, and also the API in the JDBC Standard Extension API. The following list defines various terms used in talking about the JDBC API.

  • JDBC 2.0 API-the complete JDBC API, including both the java.sql package (the JDBC 2.0 core API) and the javax.sql package (the JDBC Standard Extension API). The J2EE, includes the complete JDBC 2.0 API.
  • JDBC 2.0 core API-the package java.sql; the JDBC API that is part of the Java SE, which includes the JDBC 1.0 API plus the new JDBC API added in the java.sql package. Some of the new features in this package are scrollable result sets, batch updates, programmatic updates, and support for the new SQL3 data types.
  • JDBC Standard Extension API-the package javax.sql, which may be downloaded from http://java.sun.com/products/jdbc. This package makes it easier to build server-side applications using the Java platform by providing an open architecture that supports connection pooling and distributed transactions that span multiple database servers. The DataSource API plays an integral part in these capabilities and also works with the Javatm Naming and Directory Interfacetm (JNDI) to improve portability and make code maintenance easier. The javax.sql package also provides the RowSet API, which makes it easy to handle data sets from virtually any data source as JavaBeanstm components.
  • java.sql package-the JDBC 2.0 core API, which includes the JDBC 1.0 API plus the new API added in the J2SE
  • javax.sql package-the JDBC Standard Extension API

In keeping with the policy of maintaining backward compatibility, applications written using the JDBC 1.0 API will continue to run with both the Java SE, and the J2EE, just as they have always run. Having been well designed from the beginning, the JDBC 1.0 API is essentially unchanged. Applications using features added in the JDBC 2.0 API will, of course, need to be run using a driver that supports those features.

The package java.sql, being part of the core API, is automatically included when the Java SE, is downloaded. A driver vendor may bundle the package javax.sql with its driver product, but if a driver does not include the package, it can be downloaded from the JDBC website at the following URL:

http://java.sun.com/products/jdbc

It is also possible to get the javax.sql package by downloading the J2EE, which includes both the java.sql and javax.sql packages. Programmers who are not writing Enterprise JavaBeanstm (EJB) components or other server code will probably want to download the Java SE, rather than the J2EE, to limit the amount of disc space used.

1.2 What Is the JDBC API?

The JDBC API is a Java API for accessing virtually any kind of tabular data. (As a point of interest, JDBC is the trademarked name and is not an acronym; nevertheless, JDBC is often thought of as standing for "Java Database Connectivity.") The JDBC API consists of a set of classes and interfaces written in the Java programming language that provide a standard API for tool/database developers and makes it possible to write industrial strength database applications using an all-Java API.

The JDBC API makes it easy to send SQL statements to relational database systems and supports all dialects of SQL. But the JDBC 2.0 API goes beyond SQL, also making it possible to interact with other kinds of data sources, such as files containing tabular data.

The value of the JDBC API is that an application can access virtually any data source and run on any platform with a Java Virtual Machine. In other words, with the JDBC API, it isn't necessary to write one program to access a Sybase database, another program to access an Oracle database, another program to access an IBM DB2 database, and so on. One can write a single program using the JDBC API, and the program will be able to send SQL or other statements to the appropriate data source. And, with an application written in the Java programming language, one doesn't have to worry about writing different applications to run on different platforms. The combination of the Java platform and the JDBC API lets a programmer write once and run anywhere.

The Java programming language, being robust, secure, easy to use, easy to understand, and automatically downloadable on a network, is an excellent language basis for database applications. What is needed is a way for Java applications to talk to a variety of different data sources. JDBC is the mechanism for doing this.

The JDBC 2.0 API extends what can be done with the Java platform. For example, the JDBC API makes it possible to publish a web page containing an applet that uses information obtained from a remote data source. Or an enterprise can use the JDBC API to connect all its employees (even if they are using a conglomeration of Windows, Macintosh, and UNIX machines) to one or more internal databases via an intranet. With more and more programmers using the Java programming language, the need for easy and universal data access from Java is continuing to grow.

MIS managers like the combination of the Java platform and JDBC technology because it makes disseminating information easy and economical. Businesses can continue to use their installed databases and access information easily even if it is stored on different database management systems or other data sources. Development time for new applications is short. Installation and version control are greatly simplified. A programmer can write an application or an update once, put it on the server, and everybody has access to the latest version. And for businesses selling information services, the combination of the Java and JDBC technologies offers a better way of getting out information updates to external customers.

1.2.1 What Does the JDBC API Do?

In simplest terms, a JDBC technology-based driver ("JDBC driver") makes it possible to do three things:

  1. Establish a connection with a data source
  2. Send queries and update statements to the data source
  3. Process the results

    The following code fragment gives a simple example of these three steps:

Connection con = DriverManager.getConnection(

                    "jdbc:myDriver:wombat", "myLogin", "myPassword");
Statement stmt = con.createStatement();
ResultSet rs = stmt.executeQuery("SELECT a, b, c FROM Table1");
while (rs.next()) {
    int x = rs.getInt("a");
    String s = rs.getString("b");
    float f = rs.getFloat("c");

    }

1.2.2 A Base for Other APIs

The JDBC API is used to invoke (or "call") SQL commands directly. It works very well in this capacity and is easier to use than other database connectivity APIs, but it was also designed to be a base upon which to build alternate interfaces and tools. An alternate interface tries to be "user-friendly" by using a more understandable or more convenient API that is translated behind the scenes into the JDBC API. Because the JDBC API is complete and powerful enough to be used as a base, it has had various kinds of alternate APIs developed on top of it, including the following:

  1. An embedded SQL for Java. A consortium including Oracle, IBM, Sun, and others has defined the SQLJ specification to provide this. JDBC requires that SQL statements basically be passed as uninterpreted strings to Java methods. An embedded SQL preprocessor provides compile-time type checking and allows a programmer to intermix SQL statements with Java programming language statements. For example, a Java variable can be used in an SQL statement to receive or provide SQL values. The SQLJ preprocessor effectively translates this Java/SQL mix into the Java programming language with JDBC calls.
  2. A direct mapping of relational database tables to Java classes. Java Software has announced the Java Blendtm product to provide this, and others have similar products. In this "object/relational" mapping, a table becomes a class, each row of the table becomes an instance of that class, and each column value corresponds to an attribute of that instance. Programmers can then operate directly on Java objects; the required SQL calls to fetch and store data are automatically generated "beneath the covers." Java Blend also allows more sophisticated mappings, for example, where rows of multiple tables are combined in a Java class.

As interest in JDBC technology has grown, other JDBC-based tools have been developed to make building programs easier. For example, an application might present a menu of database tasks from which to choose. After a task is selected, the application presents prompts and blanks for filling in information needed to carry out the selected task. With the requested input typed in, the application then automatically invokes the necessary JDBC commands. With the help of such an application, users can perform database tasks even when they have little or no knowledge of SQL syntax.

1.2.3 The JDBC API Versus ODBC and UDA

Prior to the development of the JDBC API, Microsoft's ODBC (Open DataBase Connectivity) API was the most widely used programming interface for accessing relational databases. It offers the ability to connect to almost all databases on almost all platforms. So why not just use ODBC from Java?

The answer is that you can use ODBC from Java, but this is best done with the help of the JDBC API in the form of the JDBC-ODBC Bridge. The question now becomes, "Why do you need the JDBC API?"

There are several answers to this question.

  1. ODBC is not appropriate for direct use from the Java programming language because it uses a C interface. Calls from Java to native C code have a number of drawbacks in the security, implementation, robustness, and automatic portability of applications.
  2. A literal translation of the ODBC C API into a Java API would not be desirable. For example, Java has no pointers (address variables), and ODBC makes copious use of them, including the notoriously error-prone generic pointer void *. You can think of JDBC as ODBC translated into a high-level object-oriented interface that is natural for programmers using the Java programming language.
  3. ODBC is hard to learn. It mixes simple and advanced features together, and it has complex options even for simple queries. The JDBC API, on the other hand, was designed to keep simple things simple while allowing more advanced capabilities where required. The JDBC API is also easier to use simply because it is a Java API, which means that a programmer does not need to worry about either memory management or data byte alignment.
  4. A Java API like JDBC is needed in order to enable a "pure Java" solution, that is, a solution that uses only Java API. When ODBC is used, the ODBC driver manager and drivers must be manually installed on every client machine. When the JDBC driver is written completely in Java, however, JDBC code is automatically installable, portable, and secure on all Java platforms from network computers to mainframes.

In summary, the JDBC API is a natural Java interface for working with SQL. It builds on ODBC rather than starting from scratch, so programmers familiar with ODBC will find it very easy to learn. The JDBC API retains some of the basic design features of ODBC; in fact, both interfaces are based on the Open Group (formerly X/Open) SQL CLI (Call Level Interface). The big difference is that the JDBC API builds on and reinforces the style and virtues of Java, and it goes beyond just sending SQL statements to a relational database management system.

Microsoft has introduced new APIs beyond ODBC such as OLE (Object Linking and Embedding) DB, ADO (ActiveX Data Objects), and RDS (Remote Data Service). In many ways these APIs move in the same direction as the JDBC API. For example, OLE DB and ADO are also object-oriented interfaces to databases that can be used to execute SQL statements. However, OLE DB is a low-level interface designed for tools rather than developers. ADO is newer and more like the JDBC API, but it is not pure Java. RDS provides functionality similar to the JDBC API's RowSet facility, but RDS is also not written in the Java programming language, and it is not portable.

Most recently, Microsoft has introduced UDA (Universal Data Access) as an umbrella term that covers OLE DB, ADO, RDS, and ODBC. The JDBC 2.0 API contains all of the important functionality of UDA plus features not found in UDA, such as SQL3 support.

1.2.4 Two-tier and Three-tier Models

The JDBC API supports both two-tier and three-tier models for database access.

Figure 1.1: illustrates a two-tier architecture for data access.

The DBMS-proprietary protocol provides two-way communication between the client machine and the database server

In the two-tier model, a Java applet or application talks directly to the data source. This requires a JDBC driver that can communicate with the particular data source being accessed. A user's commands are delivered to the database or other data source, and the results of those statements are sent back to the user. The data source may be located on another machine to which the user is connected via a network. This is referred to as a client/server configuration, with the user's machine as the client, and the machine housing the data source as the server. The network can be an intranet, which, for example, connects employees within a corporation, or it can be the Internet.

In the three-tier model, commands are sent to a "middle tier" of services, which then sends the commands to the data source. The data source processes the commands and sends the results back to the middle tier, which then sends them to the user. MIS directors find the three-tier model very attractive because the middle tier makes it possible to maintain control over access and the kinds of updates that can be made to corporate data. Another advantage is that it simplifies the deployment of applications. Finally, in many cases, the three-tier architecture can provide performance advantages.

Figure 1.2: illustrates a three-tier architecture for database access.

The DBMS-proprietary protocol provides two-way communication between the database server and the server machine. HTTP, RMI, CORBA or other calls provide two way communication between the server machine and the client machine

Until recently, the middle tier has typically been written in languages such as C or C++, which offer fast performance. However, with the introduction of optimizing compilers that translate Java bytecode into efficient machine-specific code and technologies such as Enterprise JavaBeanstm, the Java platform is fast becoming the standard platform for middle-tier development. This is a big plus, making it possible to take advantage of Java's robustness, multithreading, and security features.

With enterprises increasingly using the Java programming language for writing server code, the JDBC API is being used more and more in the middle tier of a three-tier architecture. Some of the features that make JDBC a server technology are its support for connection pooling, distributed transactions, and disconnected rowsets. And, of course, the JDBC API is what allows access to a data source from a Java middle tier.

1.2.5 SQL Conformance

SQL is the standard language for accessing relational databases. Unfortunately, SQL is not yet as standard as one would like.

One area of difficulty is that data types used by different DBMSs (DataBase Management Systems) sometimes vary, and the variations can be significant. JDBC deals with this by defining a set of generic SQL type identifiers in the class java.sql.Types. Note that, as used in this material, the terms "JDBC SQL type," "JDBC type," and "SQL type" are interchangeable and refer to the generic SQL type identifiers defined in java.sql.Types. There is a more complete discussion of data type conformance in the chapter "Mapping SQL and Java Types."

Another area of difficulty with SQL conformance is that although most DBMSs use a standard form of SQL for basic functionality, they do not conform to the more recently defined standard SQL syntax or semantics for more advanced functionality. For example, not all databases support stored procedures or outer joins, and those that do are not always consistent with each other. Also, support for SQL3 features and data types varies greatly. It is hoped that the portion of SQL that is truly standard will expand to include more and more functionality. In the meantime, however, the JDBC API must support SQL as it is.

One way the JDBC API deals with this problem is to allow any query string to be passed through to an underlying DBMS driver. This means that an application is free to use as much SQL functionality as desired, but it runs the risk of receiving an error on some DBMSs. In fact, an application query may be something other than SQL, or it may be a specialized derivative of SQL designed for specific DBMSs (for document or image queries, for example).

A second way JDBC deals with problems of SQL conformance is to provide ODBC-style escape clauses. The escape syntax provides a standard JDBC syntax for several of the more common areas of SQL divergence. For example, there are escapes for date literals and for stored procedure calls.

For complex applications, JDBC deals with SQL conformance in a third way. It provides descriptive information about the DBMS by means of the interface DatabaseMetaData so that applications can adapt to the requirements and capabilities of each DBMS. Typical end users, however, need not worry about metadata.

Because the JDBC API is used as a base API for developing database access tools and other APIs, it also has to address the problem of conformance for anything built on it. A JDBC driver must support at least ANSI SQL-92 Entry Level. (ANSI SQL-92 refers to the standards adopted by the American National Standards Institute in 1992. Entry Level refers to a specific list of SQL capabilities.) Note, however, that although the JDBC 2.0 API includes support for SQL3 and SQLJ, JDBC drivers are not required to support them.

Given the wide acceptance of the JDBC API by database vendors, connectivity vendors, Internet service vendors, and application writers, it has become the standard for data access from the Java programming language.

1.2.6 JDBC Products

The JDBC API is a natural choice for developers using the Java platform because it offers easy database access for Java applications and applets.

At the time of this writing, a number of JDBC-based products have already been deployed or are in development. The status of these products changes frequently, so the reader should consult the JDBC web page for the latest information. It can be found at the following URL:

http://java.sun.com/products/jdbc

1.2.7 Java Software Framework

Java Software provides three JDBC product components:

  • the JDBC driver manager (included as part of the Java 2 Platform)
  • the JDBC driver test suite (available from the JDBC web site)
  • the JDBC-ODBC bridge (included in the Solaris and Windows versions of the Java 2 Platform)

The JDBC DriverManager class has traditionally been the backbone of the JDBC architecture. It is quite small and simple; its primary function is to connect Java applications to the correct JDBC driver and then get out of the way. With the availability of the Standard Extension packages javax.naming and javax.sql, it is now also possible to use a DataSource object registered with a Java Naming and Directory Interfacetm (JNDI) naming service to establish a connection with a data source. Both means of getting a connection can be still used, but using a DataSource object is recommended whenever possible.

The JDBC driver test suite provides some confidence that JDBC drivers will run your program. These tests are not comprehensive or exhaustive, but they do exercise many of the important features in the JDBC API.

The JDBC-ODBC bridge allows ODBC drivers to be used as JDBC drivers. It was implemented as a way to get JDBC off the ground quickly, and long term will provide a way to access some of the data sources for which there are no JDBC drivers.

1.2.8 JDBC Driver Types

Figure 1.3: shows various driver implementation possibilities.

See long description [D]

JDBC technology-based drivers generally fit into one of four categories:

  1. JDBC-ODBC bridge plus ODBC driver: The Java Software bridge product provides JDBC access via ODBC drivers. Note that ODBC binary code, and in many cases database client code, must be loaded on each client machine that uses this driver. As a result, this kind of driver is most appropriate on a corporate network where client installations are not a major problem, or for application server code written in Java in a three-tier architecture.
  2. Native-API partly-Java driver: This kind of driver converts JDBC calls into calls on the client API for Oracle, Sybase, Informix, IBM DB2, or other DBMSs. Note that, like the bridge driver, this style of driver requires that some operating system-specific binary code be loaded on each client machine.
  3. JDBC-Net pure Java driver: This driver translates JDBC calls into a DBMS-independent net protocol, which is then translated to a DBMS protocol by a server. This net server middleware is able to connect its pure Java clients to many different databases. The specific protocol used depends on the vendor. In general, this is the most flexible JDBC alternative. It is likely that all vendors of this solution will provide products suitable for intranet use. In order for these products to support Internet access as well, they must handle the additional requirements for security, access through firewalls, and so forth, that the Web imposes.
  4. Native-protocol pure Java driver: This kind of driver converts JDBC calls directly into the network protocol used by DBMSs. This allows a direct call from the client machine to the DBMS server and is an excellent solution for intranet access. Since many of these protocols are proprietary, the database vendors themselves are the primary source. Several that are now available include Oracle, Sybase, Informix, IBM DB2, Inprise InterBase, and Microsoft SQL Server.

Driver categories 3 and 4 are the preferred way to access databases using the JDBC API. Driver categories 1 and 2 are interim solutions where direct pure Java drivers are not yet available. There are possible variations on categories 1 and 2 (not shown in the following table) that require middleware, but these are generally less desirable solutions. Categories 3 and 4 offer all the advantages of Java technology, including automatic installation (for example, downloading the JDBC driver with an applet that uses it).

Table 1.1 shows the four categories and their properties. The table uses the following definitions for types of network connections:

  • Direct -a connection that a JDBC client makes directly to the DBMS server, which may be remote
  • Indirect--a connection that a JDBC client makes to a middleware process that acts as a bridge to the DBMS server

    DRIVER CATEGORY

    ALL JAVA

    NETWORK CONNECTION

    1 - JDBC-ODBC Bridge

    No

    Direct

    2 - Native API as basis

    No

    Direct

    3 - JDBC-Net

    client Yes

    server Maybe

    Indirect

    4 - Native protocol as basis

    Yes

    Direct

1.2.9 Obtaining JDBC Drivers

At the time of this writing, there are dozens of drivers in Category 1, ODBC drivers that can be used with Java Software's bridge. There are about a dozen Category 2 drivers built on top of native APIs for DBMSs. Many Category 3 drivers are available, and there are Category 4 drivers for all of the major DBMSs.

To get the latest information on drivers, check the JDBC web site at

 http://java.sun.com/products/jdbc

Java Software and Intersolv, a leading database connectivity vendor, worked together to produce the JDBC-ODBC Bridge and the JDBC Driver Test Suite.

1.2.10 Java-relational DBMSs

A new generation of DBMSs that are Java-aware is emerging. These new DBMSs, called Java-relational DBMSs, include new data types that allow an object in the Java programming language to be used as a column value in a database table. The new JDBC 2.0 features support this new generation of DBMSs, and several database vendors are creating products with Java-relational capabilities. It should be noted, however, that the 2.0 mechanisms are optional. If a DBMS does not support this feature, a JDBC 2.0 driver is not required to implement it.

1.2.11 Other Products

Various JDBC application development tools are under way. Watch the Java Software pages for updates.

[Top] [Prev] [Next]

Copyright © 1999, Sun Microsystems, Inc. All rights reserved.


JDBC-ODBC Bridge Enhancements

JDBCTM-ODBC Bridge Enhancements

 Documentation Contents
JDBC

The JDBC-ODBC Bridge allows applications written in the JavaTM programming language to use the JDBCTM API with many existing ODBC drivers. The Bridge is itself a driver based on JDBC technology ("JDBC driver") that is defined in the class sun.jdbc.odbc.JdbcOdbcDriver. The Bridge defines the JDBC sub protocol odbc.

Status of the JDBC-ODBC Bridge

The JDBC-ODBC Bridge should be considered a transitional solution. Sun Microsystems and DataDirect Technologies are working to make the Bridge more reliable and robust, but they do not consider it a supported product. With the development of pure Java JDBC drivers, the JDBC-ODBC Bridge should become unnecessary.

Why not just use ODBC?

The JDBC-ODBC Bridge offers several advantages over "naked" ODBC.
  • The ODBC API is strongly oriented toward C/C++ programmers. The JDBC-ODBC Bridge makes it unnecessary for programmers using the Java programming language to deal with non-Java language concepts.
  • The ODBC API is extremely complex and intermingles high level and low level functions. The JDBC-ODBC Bridge allows the programmer to rely on the JDBC API, which is relatively simple and easy to learn.
  • The JDBC-ODBC Bridge lets a program deal with ODBC through a standardized JDBC interface. That helps a program avoid being tied to ODBC when a better solution comes along.

Why use ODBC at all?

The ideal is "Pure Java": no native code, no platform dependent features. But you may need to begin your development effort right away, without waiting for your DBMS to offer a Java only JDBC driver. Partly native drivers, such as the JDBC-ODBC Bridge, let you create programs that easily adapt to Pure Java drivers as they become available.

What's New with the JDBC-ODBC Bridge?

  • A jdbc:odbc: connection can now have a charSet property, to specify a Character Encoding Scheme other than the client default. For possible values, see the JDK 1.1 Internationalization specification on the Java Software Web Site.

    • The following code fragment shows how to set 'Big5' as the character set for all character data.
           // Load the JDBC-ODBC bridge driver
       Class.forName(sun.jdbc.odbc.JdbcOdbcDriver) ;

       // setup the properties
       java.util.Properties prop = new java.util.Properties();
       prop.put("charSet", "Big5");
       prop.put("user", username);
       prop.put("password", password);

       // Connect to the database
       con = DriverManager.getConnection(url, prop);
  • The bridge now supports JDBC 2.0 features, which includes batch updates, scrollable cursors, and so on.
  • JDBC-ODBC bridge now offers most of the features required for a J2EE compatible JDBC driver.
  • Sample implementations of DataSource and ConnectionPoolDataSource are available with the JDBC-ODBC bridge.
  • CallableStatement OUT/INOUT parameter handling has been improved.
  • Automatic garbage collection of unclosed Statement objects has been implemented.
  • Improved support for updatable Resultset objects has been implemented.
  • Additional robustness and reliability checking as been introduced.

New DataSource Implementations in the JDBC-ODBC Bridge

Implementations of javax.sql.DataSource and javax.sql.ConnectionPoolDataSource are now available. Both are in the sun.jdbc.odbc.ee package. The following code fragment illustrates how to set DataSource properties. The last two lines use JNDI API to bind the DataSource object ds to "jdbc/OdbcDB1". Assume that the DataSource object is targeting an ODBC DSN "dsn1" connecting to an Oracle Database.
            // Establish the DataSource object instance
            sun.jdbc.odbc.ee.DataSource ds = new sun.jdbc.odbc.ee.DataSource();
            // Provide user credentials and database name
            ds.setUser("scott");
            ds.setPassword("tiger");
            ds.setDatabaseName("dsn1");
            ds.setCharSet("..."); // optional property
            ds.setLoginTimeout(100); // optional property
            // Establish initial context and bind to the datasource target
            InitialContext ic = new InitialContext();
            ic.bind("jdbc/OdbcDB1",ds);
In the preceding code, note that some properties are optional while some are required. Properties such as port number and role name are not implemented in the JDBC-ODBC bridge DataSource implementations as these properties are not applicable to ODBC paradigm.

Continuing the previous example, the following code fragment demonstrates retrieving the DataSource object by looking up the JNDI name "jdbc/OdbcDB1". With the DataSource object that is obtained, the code then activates tracing and creates two connections.

            // Get the initial context of JNDI and lookup the datasource.
            InitialContext ic = new InitialContext();
            javax.sql.DataSource ds1 = (javax.sql.DataSource) ic.lookup("jdbc/OdbcDB1");
            // Set the optional printwriter where the trace log is to be directed.
            ds1.setLogWriter(new PrintWriter(new FileOutputStream("/tmp/datasource.log")));
            Connection con1 = ds1.getConnection();
            Connection con2 = ds1.getConnection("system","manager");
The implementation of javax.sql.ConnectionPoolDataSource uses an underlying pool of JDBC-ODBC connections. A ConnectionPoolDataSource object is used to create PooledConnection objects, which are in turn used to get Connection objects. From the user's viewpoint, the Connection object is just like any other connection.

The following code fragment creates the ConnectionPoolDataSource object cpds and sets its properties. The final two lines use JNDI API to bind cpds to "jdbc/OdbcPool", which can later be supplied to the method InitialContext.lookup to retrieve cpds.

            // Establish ConnectionPoolDataSource instance
            sun.jdbc.odbc.ee.ConnectionPoolDataSource cpds =
                new sun.jdbc.odbc.ee.ConnectionPoolDataSource("jdbc/OdbcPool");
            // Provide user credentials and database name
            cpds.setUser("scott");
            cpds.setPassword("tiger");
            cpds.setDatabaseName("dsn1");
            cpds.setCharSet("...") // optional property
            cpds.setLoginTimeout(100); // optional property
            cpds.setMinPoolSize("10");
            cpds.setInitialPoolSize("15");
            cpds.setMaxPoolSize("20");
            cpds.setMaxIdleTime("300");
            cpds.setTimeoutFromPool("600");
            // Maintenance interval of the pool. A maintenance thread will remove
            // unwanted connections and cleanup the pool at the interval specified.
            // This cannot be zero.
            cpds.setMaintenanceInterval("900");
            InitialContext ic = new InitialContext();
            ic.bind("jdbc/OdbcPool",cpds);
In all cases in order get the ConnectionPoolDataSource to function as a pooled datasource, it is the responsibility of the application to configure the pool as described in the code example above. The default behavior of pooled datasource uses a zero minimum, initial and maximum pool sizes. Note that the JDBC-ODBC bridge implementation of ConnectionPoolDataSource does not yet include the pooling of Statement objects or the property propertyCycle.

The following code fragment shows how to use a ConnectionPoolDataSource object as simply a DataSource object. This is done by doing a JNDI lookup of "jdbc/OdbcPool" and casting it to a DataSource object instead of to a ConnectionPoolDataSource object.

            InitialContext ic = new InitialContext();
            javax.sql.DataSource ds1 = (javax.sql.DataSource) ic.lookup("jdbc/OdbcPool");
            // First getConnection will initializes the pool.
            Connection con1 = ds1.getConnection();
            Connection con2 = ds1.getConnection("system","manager");
            -------------
            -------------
            // An application need to close the connection explicitly. This will allow the pool to recycle the connection.
            con1.close();
            con2.close();
Using the implementation as a ConnectionPoolDataSource object is shown in the following line of code. Note that closing a PooledConnection object closes the actual physical connection, whereas closing a connection that was created from a PooledConnection object just returns it to the pool of connections.
            InitialContext ic = new InitialContext();
            javax.sql.ConnectionPoolDataSource cpds =
                (javax.sql.ConnectionPoolDataSource) ic.lookup("jdbc/OdbcPool");
            PooledConnection pc1 = cpds.getPooledConnection();
            Connection con1 = pc1.getConnection();
            PooledConnection pc2 = cpds.getPooledConnection("system","manager");
            Connection con2 = pc2.getConnection();
            -------------
            -------------
            // An application needs to close the connection explicitly. This will allow the pool to recycle the connection.
            con1.close();
            con2.close();
            Connection con3 = pc1.getConnection();
            Connection con4 = pc2.getConnection();
            -------------
            -------------
            // This will close the physical connection!
            pc1.close();
            pc2.close();
A pool of connections can be shut down in two ways. If the method shutDown is given the argument false, only those connections that are not being used will be closed. If the argument true is supplied, all connections will be closed immediately, regardless of whether they are being used or not.
            // Hot shutdown
            ((sun.jdbc.odbc.ee.ConnectionPoolDataSource) cpds).shutDown(true);
            or
            // Cold shutdown
            ((sun.jdbc.odbc.ee.ConnectionPoolDataSource) cpds).shutDown(false);

Copyright © 2002 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: jdbc-odbc@sun.com


 [Top] [Prev] [Next]

Mapping SQL and Java Types

NOTE: The material in this chapter is based on JDBCtm API Tutorial and Reference, Second Edition: Universal Data Access for the Javatm 2 Platform, published by Addison Wesley as part of the Java series, ISBN 0-201-43328-1.

8.1 Mapping Overview

Because data types in SQL and data types in the Java programming language are not identical, there needs to be some mechanism for transferring data between an application using Java types and a database using SQL types. (Note that the phrase "Java types," as used in this book, stands for "types in the Java programming language.")

In order to transfer data between a database and an application written in the Java programming language, the JDBC API provides three sets of methods:

  1. Methods on the ResultSet class for retrieving SQL SELECT results as Java types
  2. Methods on the PreparedStatement class for sending Java types as SQL statement parameters
  3. Methods on the CallableStatement class for retrieving SQL OUT parameters as Java types

This section brings together information about data types affecting various classes and interfaces and puts all the tables showing the mappings between SQL types and Java types in one place for easy reference. It also describes each of the generic SQL data types, including the SQL3 types.

8.2 Mapping SQL Types to Java Types

Unfortunately there are significant variations between the SQL types supported by different database products. Even when different databases support SQL types with the same semantics, they may give those types different names. For example, most of the major databases support an SQL data type for large binary values, but Oracle calls this type LONG RAW, Sybase calls it IMAGE, Informix calls it BYTE, and DB2 calls it LONG VARCHAR FOR BIT DATA.

Fortunately, JDBC programmers will normally not need to concern themselves with the actual SQL type names used by a target database. Most of the time JDBC programmers will be programming against existing database tables, and they need not concern themselves with the exact SQL type names that were used to create these tables.

JDBC defines a set of generic SQL type identifiers in the class java.sql.Types. These types have been designed to represent the most commonly used SQL types. In programming with the JDBC API, programmers will normally be able to use these JDBC types to reference generic SQL types, without having to be concerned about the exact SQL type name used by the target database. These JDBC types are fully described in the next section.

The one major place where programmers may need to use SQL type names is in the SQL CREATE TABLE statement when they are creating a new database table. In this case programmers must take care to use SQL type names that are supported by their target databases. The table "JDBC Types Mapped to Database-specific SQL Types" on page 111 provides some suggestions for suitable SQL type names to be used for JDBC types for some of the major databases. We recommend that you consult your database documentation if you need exact definitions of the behavior of the various SQL types on a particular database.

If you want to be able to write portable JDBC programs that can create tables on a variety of different databases, you have two main choices. First, you can restrict yourself to using only very widely accepted SQL type names such as INTEGER, NUMERIC, or VARCHAR, which are likely to work for all databases. Or second, you can use the java.sql.DatabaseMetaData.getTypeInfo method to discover which SQL types are actually supported by a given database and select a database-specific SQL type name that matches a given JDBC type.

JDBC defines a standard mapping from the JDBC database types to Java types. For example, a JDBC INTEGER is normally mapped to a Java int. This supports a simple interface for reading and writing JDBC values as simple Java types.

The Java types do not need to be exactly isomorphic to the JDBC types; they just need to be able to represent them with enough type information to correctly store and retrieve parameters and recover results from SQL statements. For example, a Java String object does not precisely match any of the JDBC CHAR types, but it gives enough type information to represent CHAR, VARCHAR, or LONGVARCHAR successfully.

8.3 Basic JDBC Types

This section describes the JDBC data types supported by both the JDBC 1.0 and 2.0 API. It also explains how they are related to standard SQL types and to types in the Java programming language. New JDBC data types introduced in the JDBC 2.0 core API are described in section 8.4 on page 94.

8.3.1 CHAR, VARCHAR, and LONGVARCHAR

The JDBC types CHAR, VARCHAR, and LONGVARCHAR are closely related. CHAR represents a small, fixed-length character string, VARCHAR represents a small, variable-length character string, and LONGVARCHAR represents a large, variable-length character string.

The SQL CHAR type corresponding to JDBC CHAR is defined in SQL-92 and is supported by all the major databases. It takes a parameter that specifies the string length. Thus CHAR(12) defines a 12-character string. All the major databases support CHAR lengths up to at least 254 characters.

The SQL VARCHAR type corresponding to JDBC VARCHAR is defined in SQL-92 and is supported by all the major databases. It takes a parameter that specifies the maximum length of the string. Thus VARCHAR(12) defines a string whose length may be up to 12 characters. All the major databases support VARCHAR lengths up to 254 characters. When a string value is assigned to a VARCHAR variable, the database remembers the length of the assigned string and on a SELECT, it will return the exact original string.

Unfortunately there is no consistent SQL mapping for the JDBC LONGVARCHAR type. All the major databases support some kind of very large variable-length string supporting up to at least a gigabyte of data, but the SQL type names vary. See the table "JDBC Types Mapped to Database-specific SQL Types" on page 111 for some examples.

Java programmers do not need to distinguish among the three types of JDBC strings, CHAR, VARCHAR, and LONGVARCHAR. Each can be expressed as a Java String, and it is possible to read and write an SQL statement correctly without knowing the exact data type that was expected.

CHAR, VARCHAR, and LONGVARCHAR could have been mapped to either String or char[], but String is more appropriate for normal use. Also, the String class makes conversions between String and char[] easy: There is a method for converting a String object to a char[] and also a constructor for turning a char[] into a String object.

One issue that had to be addressed is how to handle fixed-length SQL strings of type CHAR(n). The answer is that JDBC drivers (or the DBMS) perform appropriate padding with spaces. Thus, when a CHAR(n) field is retrieved from the database, the driver will convert it to a Java String object of length n, which may include some padding spaces at the end. Conversely, when a String object is sent to a CHAR(n) field, the driver and/or the database will add any necessary padding spaces to the end of the string to bring it up to length n.

The method ResultSet.getString, which allocates and returns a new String object, is recommended for retrieving data from CHAR, VARCHAR, and LONGVARCHAR fields. This is suitable for retrieving normal data, but can be unwieldy if the JDBC type LONGVARCHAR is being used to store multi-megabyte strings. To handle this case, two methods in the ResultSet interface allow programmers to retrieve a LONGVARCHAR value as a Java input stream from which they can subsequently read data in whatever size chunks they prefer. These methods are getAsciiStream and getCharacterStream, which deliver the data stored in a LONGVARCHAR column as a stream of ASCII or Unicode characters. Note that the method getUnicodeStream has been deprecated.

The SQL3 CLOB data type, which is described later in this chapter, provides an alternate means of representing large amounts of character data.

8.3.2 BINARY, VARBINARY, and LONGVARBINARY

The JDBC types BINARY, VARBINARY, and LONGVARBINARY are closely related. BINARY represents a small, fixed-length binary value, VARBINARY represents a small, variable-length binary value, and LONGVARBINARY represents a large, variable-length binary value.

Unfortunately, the use of these various BINARY types has not been standardized and support varies considerably among the major databases.

The SQL BINARY type corresponding to JDBC BINARY is a nonstandard SQL extension and is only implemented on some databases. It takes a parameter that specifies the number of binary bytes. Thus BINARY(12) defines a 12-byte binary type. Typically, BINARY values are limited to 254 bytes.

The SQL VARBINARY type corresponding to JDBC VARBINARY is a nonstandard SQL extension and is only implemented on some databases. It takes a parameter that specifies the maximum number of binary bytes. Thus VARBINARY(12) defines a binary type whose length may be up to 12 bytes. Typically, VARBINARY values are limited to 254 bytes. When a binary value is assigned to a VARBINARY variable, the database remembers the length of the assigned value and on a SELECT, it will return the exact original value.

Regrettably, there is no consistent SQL type name corresponding to the JDBC LONGVARBINARY type. All the major databases support some kind of very large variable length binary type supporting up to at least a gigabyte of data, but the SQL type names vary. See the table "JDBC Types Mapped to Database-specific SQL Types" on page 111 for some examples.

BINARY, VARBINARY, and LONGVARBINARY can all be expressed identically as byte arrays in the Java programming language. Since it is possible to read and write SQL statements correctly without knowing the exact BINARY data type that was expected, there is no need for programmers writing code in the Java programming language to distinguish among them.

The method recommended for retrieving BINARY and VARBINARY values is ResultSet.getBytes. If a column of type JDBC LONGVARBINARY stores a byte array that is many megabytes long, however, the method getBinaryStream is recommended. Similar to the situation with LONGVARCHAR, this method allows a programmer to retrieve a LONGVARBINARY value as a Java input stream that can be read later in smaller chunks.

The SQL3 BLOB data type, which is described later in this chapter, provides an alternate means of representing large amounts of binary data.

8.3.3 BIT

The JDBC type BIT represents a single bit value that can be zero or one.

SQL-92 defines an SQL BIT type. However, unlike the JDBC BIT type, this SQL-92 BIT type can be used as a parameterized type to define a fixed-length binary string. Fortunately, SQL-92 also permits the use of the simple non-parameterized BIT type to represent a single binary digit, and this usage corresponds to the JDBC BIT type. Unfortunately, the SQL-92 BIT type is only required in "full" SQL-92 and is currently supported by only a subset of the major databases. Portable code may therefore prefer to use the JDBC SMALLINT type, which is widely supported.

The recommended Java mapping for the JDBC BIT type is as a Java boolean.

8.3.4 TINYINT

The JDBC type TINYINT represents an 8-bit integer value between 0 and 255 that may be signed or unsigned.

The corresponding SQL type, TINYINT, is currently supported by only a subset of the major databases. Portable code may therefore prefer to use the JDBC SMALLINT type, which is widely supported.

The recommended Java mapping for the JDBC TINYINT type is as either a Java byte or a Java short. The 8-bit Java byte type represents a signed value from -128 to 127, so it may not always be appropriate for larger TINYINT values, whereas the 16-bit Java short will always be able to hold all TINYINT values.

8.3.5 SMALLINT

The JDBC type SMALLINT represents a 16-bit signed integer value between -32768 and 32767.

The corresponding SQL type, SMALLINT, is defined in SQL-92 and is supported by all the major databases. The SQL-92 standard leaves the precision of SMALLINT up to the implementation, but in practice, all the major databases support at least 16 bits.

The recommended Java mapping for the JDBC SMALLINT type is as a Java short.

8.3.6 INTEGER

The JDBC type INTEGER represents a 32-bit signed integer value ranging between -2147483648 and 2147483647.

The corresponding SQL type, INTEGER, is defined in SQL-92 and is widely supported by all the major databases. The SQL-92 standard leaves the precision of INTEGER up to the implementation, but in practice all the major databases support at least 32 bits.

The recommended Java mapping for the INTEGER type is as a Java int.

8.3.7 BIGINT

The JDBC type BIGINT represents a 64-bit signed integer value between -9223372036854775808 and 9223372036854775807.

The corresponding SQL type BIGINT is a nonstandard extension to SQL. In practice the SQL BIGINT type is not yet currently implemented by any of the major databases, and we recommend that its use be avoided in code that is intended to be portable.

The recommended Java mapping for the BIGINT type is as a Java long.

8.3.8 REAL

The JDBC type REAL represents a "single precision" floating point number that supports seven digits of mantissa.

The corresponding SQL type REAL is defined in SQL-92 and is widely, though not universally, supported by the major databases. The SQL-92 standard leaves the precision of REAL up to the implementation, but in practice all the major databases supporting REAL support a mantissa precision of at least seven digits.

The recommended Java mapping for the REAL type is as a Java float.

8.3.9 DOUBLE

The JDBC type DOUBLE represents a "double precision" floating point number that supports 15 digits of mantissa.

The corresponding SQL type is DOUBLE PRECISION, which is defined in SQL-92 and is widely supported by the major databases. The SQL-92 standard leaves the precision of DOUBLE PRECISION up to the implementation, but in practice all the major databases supporting DOUBLE PRECISION support a mantissa precision of at least 15 digits.

The recommended Java mapping for the DOUBLE type is as a Java double.

8.3.10 FLOAT

The JDBC type FLOAT is basically equivalent to the JDBC type DOUBLE. We provided both FLOAT and DOUBLE in a possibly misguided attempt at consistency with previous database APIs. FLOAT represents a "double precision" floating point number that supports 15 digits of mantissa.

The corresponding SQL type FLOAT is defined in SQL-92. The SQL-92 standard leaves the precision of FLOAT up to the implementation, but in practice all the major databases supporting FLOAT support a mantissa precision of at least 15 digits.

The recommended Java mapping for the FLOAT type is as a Java double. However, because of the potential confusion between the double precision SQL FLOAT and the single precision Java float, we recommend that JDBC programmers should normally use the JDBC DOUBLE type in preference to FLOAT.

8.3.11 DECIMAL and NUMERIC

The JDBC types DECIMAL and NUMERIC are very similar. They both represent fixed-precision decimal values. ame="1007716"> The corresponding SQL types DECIMAL and NUMERIC are defined in SQL-92 and are very widely implemented. These SQL types take precision and scale parameters. The precision is the total number of decimal digits supported, and the scale is the number of decimal digits after the decimal point. For most DBMSs, the scale is less than or equal to the precision. So for example, the value "12.345" has a precision of 5 and a scale of 3, and the value ".11" has a precision of 2 and a scale of 2. JDBC requires that all DECIMAL and NUMERIC types support both a precision and a scale of at least 15.

The sole distinction between DECIMAL and NUMERIC is that the SQL-92 specification requires that NUMERIC types be represented with exactly the specified precision, whereas for DECIMAL types, it allows an implementation to add additional precision beyond that specified when the type was created. Thus a column created with type NUMERIC(12,4) will always be represented with exactly 12 digits, whereas a column created with type DECIMAL(12,4) might be represented by some larger number of digits.

The recommended Java mapping for the DECIMAL and NUMERIC types is java.math.BigDecimal. The java.math.BigDecimal type provides math operations to allow BigDecimal types to be added, subtracted, multiplied, and divided with other BigDecimal types, with integer types, and with floating point types.

The method recommended for retrieving DECIMAL and NUMERIC values is ResultSet.getBigDecimal. JDBC also allows access to these SQL types as simple Strings or arrays of char. Thus, Java programmers can use getString to receive a DECIMAL or NUMERIC result. However, this makes the common case where DECIMAL or NUMERIC are used for currency values rather awkward, since it means that application writers have to perform math on strings. It is also possible to retrieve these SQL types as any of the Java numeric types.

8.3.12 DATE, TIME, and TIMESTAMP

There are three JDBC types relating to time:

  • The JDBC DATE type represents a date consisting of day, month, and year. The corresponding SQL DATE type is defined in SQL-92, but it is implemented by only a subset of the major databases. Some databases offer alternative SQL types that support similar semantics.
  • The JDBC TIME type represents a time consisting of hours, minutes, and seconds. The corresponding SQL TIME type is defined in SQL-92, but it is implemented by only a subset of the major databases. As with DATE, some databases offer alternative SQL types that support similar semantics.
  • The JDBC TIMESTAMP type represents DATE plus TIME plus a nanosecond field. The corresponding SQL TIMESTAMP type is defined in SQL-92, but it is implemented by only a very small number of databases.

Because the standard Java class java.util.Date does not match any of these three JDBC date/time types exactly (it includes both DATE and TIME information but has no nanoseconds), JDBC defines three subclasses of java.util.Date to correspond to the SQL types. They are:

  • java.sql.Date for SQL DATE information. The hour, minute, second, and millisecond fields of the java.util.Date base class should be set to zero. If the number of milliseconds supplied to the java.sql.Date constructor is negative, the driver will compute the date as the number of milliseconds before January 1, 1970. Otherwise, the date is computed as the specified number of milliseconds after January 1, 1970.

  • java.sql.Time for SQL TIME information. The year, month, and day fields of the java.util.Date base class are set to 1970, January, and 1. This is the "zero" date in the Java epoch.
  • java.sql.Timestamp for SQL TIMESTAMP information. This class extends java.util.Date by adding a nanoseconds field.

All three of the JDBC time-related classes are subclasses of java.util.Date, and as such, they can be used where a java.util.Date is expected. For example, internationalization methods take a java.util.Date object as an argument, so they can be passed instances of any of the JDBC time-related classes.

A JDBC Timestamp object has its parent's date and time components and also a separate nanoseconds component. If a java.sql.Timestamp object is used where a java.util.Date object is expected, the nanoseconds component is lost. However, since a java.util.Date object is stored with a precision of one millisecond, it is possible to maintain this degree of precision when converting a java.sql.Timestamp object to a java.util.Date object. This is done by converting the nanoseconds in the nanoseconds component to whole milliseconds (by dividing the number of nanoseconds by 1,000,000) and then adding the result to the java.util.Date object. Up to 999,999 nanoseconds may be lost in this conversion, but the resulting java.util.Date object will be accurate to within one millisecond.

The following code fragment is an example of converting a java.sql.Timestamp object to a java.util.Date object that is accurate to within one millisecond.

Timestamp t = new Timestamp(98724573287540L);
java.util.Date d;
d = new java.util.Date(t.getTime() + (t.getNanos() / 1000000));

New methods in the JDBC 2.0 core API make it possible for the driver to take a specified time zone into account when calculating a date, time, or timestamp. The time zone information is included in a java.util.Calendar object that is passed to new versions of the methods for getting and setting Date, Time, and Timestamp values. When no time zone is specified, the driver uses the time zone of the virtual machine running the application when it calculates a date, time, or timestamp.

8.4 Advanced JDBC Data Types

The ISO (International Organization for Standardization) and IEC (the International Electrotechnical Commission) have defined new data types that are commonly referred to as SQL3 types. Of these new SQL3 data types, BLOB, CLOB, ARRAY, and REF are predefined types, whereas the SQL structured type and the DISTINCT type are user-defined types (UDTs). These new types, with the exception of DISTINCT, are mapped to interfaces that are new in the JDBC 2.0 core API. This section describes each data type briefly; more complete information on each type can be found in the reference chapter for the corresponding interface. There is a chapter on the DISTINCT data type, but because DISTINCT types are mapped to a built-in type, there is no separate interface for it.

The new data types in the JDBC 2.0 core API represent a significant expansion in the types of data that can be used in a relational database. In general, they are more like objects; in fact, two of the new data types are UDTs that can optionally be custom mapped to classes in the Java programming language. A third UDT (JAVA_OBJECT) is itself an instance of a class defined in the Java programming language. Despite their advanced nature, all of the new data types in the JDBC 2.0 core API can be used as conveniently as the data types in the JDBC 1.0 API. For example, they can be used as column values in database tables, and they can be retrieved and stored using the appropriate getXXX and setXXX methods.

8.4.1 BLOB

The JDBC type BLOB represents an SQL3 BLOB (Binary Large Object).

A JDBC BLOB value is mapped to an instance of the Blob interface in the Java programming language. If a driver follows the standard implementation, a Blob object logically points to the BLOB value on the server rather than containing its binary data, greatly improving efficiency. The Blob interface provides methods for materializing the BLOB data on the client when that is desired.

8.4.2 CLOB

The JDBC type CLOB represents the SQL3 type CLOB (Character Large Object).

A JDBC CLOB value is mapped to an instance of the Clob interface in the Java programming language. If a driver follows the standard implementation, a Clob object logically points to the CLOB value on the server rather than containing its character data, greatly improving efficiency. Two of the methods on the Clob interface materialize the data of a CLOB object on the client.

8.4.3 ARRAY

The JDBC type ARRAY represents the SQL3 type ARRAY.

An ARRAY value is mapped to an instance of the Array interface in the Java programming language. If a driver follows the standard implementation, an Array object logically points to an ARRAY value on the server rather than containing the elements of the ARRAY object, which can greatly increase efficiency. The Array interface contains methods for materializing the elements of the ARRAY object on the client in the form of either an array or a ResultSet object.

8.4.4 DISTINCT

The JDBC type DISTINCT field (Types class)>DISTINCT represents the SQL3 type DISTINCT.

The standard mapping for a DISTINCT type is to the Java type to which the base type of a DISTINCT object would be mapped. For example, a DISTINCT type based on a CHAR would be mapped to a String object, and a DISTINCT type based on an SQL INTEGER would be mapped to an int.

The DISTINCT type may optionally have a custom mapping to a class in the Java programming language. A custom mapping consists of a class that implements the interface SQLData and an entry in a java.util.Map object.

8.4.5 STRUCT

The JDBC type STRUCT represents the SQL3 structured type. An SQL structured type, which is defined by a user with a CREATE TYPE statement, consists of one or more attributes. These attributes may be any SQL data type, built-in or user-defined.

The standard mapping for the SQL type STRUCT is to a Struct object in the Java programming language. A Struct object contains a value for each attribute of the STRUCT value it represents.

A STRUCT value may optionally be custom mapped to a class in the Java programming language, and each attribute in the STRUCT may be mapped to a field in the class. A custom mapping consists of a class that implements the interface SQLData and an entry in a java.util.Map object.

8.4.6 REF

The JDBC type REF represents an SQL3 type REF<structured type>. An SQL REF references (logically points to) an instance of an SQL structured type, which the REF persistently and uniquely identifies. In the Java programming language, the interface Ref represents an SQL REF.

If an application wants to point to an instance of an SQL structured type in the database rather than having its attribute values materialized on the client, it can use the type REF<structured type>, a reference to that SQL structured type.

A REF value is a unique identifier created specifically for a particular instance of an SQL structured type. It is persistently stored with the instance it references in a special table on the server. An application can select the REF value from its special table and use it in place of the structured type instance it identifies.

8.4.7 JAVA_OBJECT

The JDBC type JAVA_OBJECT, added in the JDBC 2.0 core API, makes it easier to use objects in the Java programming language as values in a database. JAVA_OBJECT is simply a type code for an instance of a class defined in the Java programming language that is stored as a database object. The type JAVA_OBJECT is used by a database whose type system has been extended so that it can store Java objects directly. The JAVA_OBJECT value may be stored as a serialized Java object, or it may be stored in some vendor-specific format.

The type JAVA_OBJECT is one of the possible values for the column DATA_TYPE in the ResultSet objects returned by various DatabaseMetaData methods, including getTypeInfo, getColumns, and getUDTs. The method getUDTs, part of the new JDBC 2.0 core API, will return information about the Java objects contained in a particular schema when it is given the appropriate parameters. Having this information available facilitates using a Java class as a database type.

For DBMSs that support them, values of type JAVA_OBJECT are stored in a database table using the method PreparedStatement.setObject. They are retrieved with the methods ResultSet.getObject or CallableStatement.getObject and updated with the ResultSet.updateObject method.

For example, assuming that instances of the class Engineer are stored in the column ENGINEERS in the table PERSONNEL, the following code fragment, in which stmt is a Statement object, prints out the names of all of the engineers.

ResultSet rs = stmt.executeQuery("SELECT ENGINEERS FROM PERSONNEL");
while (rs.next()) {
    Engineer eng = (Engineer)rs.getObject("ENGINEERS");
    System.out.println(eng.lastName + ", " + eng.firstName);
}

After the query returns the ResultSet object rs, which contains all of the instances of Engineer, the code retrieves each instance in turn with the method getObject. The value returned by getObject is an Object type, so it must be narrowed to the more specific type Engineer before being assigned to the variable eng.

8.5 Examples of Mapping

In any situation where a program written in the Java programming language retrieves data from a database, there has to be some form of mapping and data conversion. In most cases, programmers using the JDBC API will be programming with knowledge of their target database's schema. In other words, they know, for example, what tables the database contains and the data type for each column in those tables. They can therefore use the strongly typed access methods in the interfaces ResultSet, PreparedStatement, and CallableStatement. This section presents three different scenarios, describing the data mapping and conversion required in each case.

8.5.1 Simple SQL Statement

In the most common case, a user executes a simple SQL statement and gets back a ResultSet object with the results. Each value returned by the database and stored in a ResultSet column will have a JDBC data type. A call to a ResultSet.getXXX method will retrieve that value as a Java data type. For example, if a ResultSet column contains a JDBC FLOAT value, the method getDouble will retrieve that value as a Java double. Table 8.6 on page 110 shows which getXXX methods may be used to retrieve which JDBC types. (A user who does not know the type of a ResultSet column can get that information by calling the method ResultSet.getMetaData and then calling the method ResultSetMetaData.getColumnType.)

8.5.2 SQL Statement with IN Parameters

In another possible scenario, the user sends an SQL query that takes input parameters. In this case, the user calls the PreparedStatement.setXXX methods to assign a value to each input parameter. For example, PreparedStatement.setLong(1, 2345678) will assign the value 2345678 to the first parameter as a Java long. The driver will convert 2345678 to a JDBC BIGINT in order to send it to the database. Which JDBC type the driver sends to the database is determined by the standard mapping from Java types to JDBC types, shown in Table 8.2 on page 106.

8.5.3 SQL Statement with INOUT Parameters

In yet another scenario, a user wants to call a stored procedure, assign values to its INOUT parameters, retrieve values from a ResultSet object, and retrieve values from the parameters. This case is rather uncommon and more complicated than most, but it gives a good illustration of mapping and data conversion.

In this scenario, the first thing to do is to assign values to the INOUT parameters using PreparedStatement.setXXX methods. In addition, because the parameters will also be used for output, the programmer must register each parameter with the JDBC type of the value that the database will return to it. This is done with the method CallableStatement.registerOutParameter, which takes one of the JDBC types defined in the class Types. A programmer retrieves the values stored in the output parameters with CallableStatement.getXXX methods.

The XXX type used for CallableStatement.getXXX must map to the JDBC type registered for that parameter. For example, if the database is expected to return an output value whose type is JDBC REAL, the parameter should have been registered as java.sql.Types.REAL. Then to retrieve the JDBC REAL value, the method CallableStatement.getFloat should be called (the mapping from JDBC types to Java types is shown in Table 8.1 on page 105). The method getFloat will return the value stored in the output parameter after converting it from a JDBC REAL to a Java float. To accommodate various databases and make an application more portable, it is recommended that values be retrieved from ResultSet objects before values are retrieved from output parameters.

The following code demonstrates calling a stored procedure named getTestData, which has two parameters that are both INOUT parameters and which also returns a normal JDBC ResultSet. First the Connection object con creates the CallableStatement object cstmt. Then the method setByte sets the first parameter to 25 as a Java byte. The driver will convert 25 to a JDBC TINYINT and send it to the database. The method setBigDecimal sets the second parameter with an input value of 83.75. The driver will convert this Java BigDecimal object to a JDBC NUMERIC value. Next the two parameters are registered as OUT parameters, the first parameter as a JDBC TINYINT and the second parameter as a JDBC NUMERIC with two digits after the decimal point. After cstmt is executed, the values are retrieved from the ResultSet object using ResultSet.getXXX methods. The method getString gets the value in the first column as a Java String object, getInt gets the value in the second column as a Java int, and the second getInt retrieves the value in the third column as a Java int.

Then CallableStatement.getXXX methods retrieve the values stored in the output parameters. The method getByte retrieves the JDBC TINYINT as a Java byte, and getBigDecimal retrieves the JDBC NUMERIC as a Java BigDecimal object with two digits after the decimal point. Note that when a parameter is both an input and an output parameter, the setXXX method uses the same Java type as the getXXX method (as in setByte and getByte). The registerOutParameter method registers it to the JDBC type that is mapped from the Java type (a Java byte maps to a JDBC TINYINT, as shown in Table 8.2 on page 106).

CallableStatement cstmt = con.prepareCall(
    "{call getTestData(?, ?)}");
cstmt.setByte(1, 25);
cstmt.setBigDecimal(2, 83.75);
// register the first parameter as a JDBC TINYINT and the second
// as a JDBC NUMERIC with two digits after the decimal point
cstmt.registerOutParameter(1, java.sql.Types.TINYINT);
cstmt.registerOutParameter(2, java.sql.Types.NUMERIC, 2);
ResultSet rs = cstmt.executeQuery();
// retrieve and print values in result set
while (rs.next()) {
    String name = rs.getString(1);
    int score = rs.getInt(2);
    int percentile = rs.getInt(3);
    System.out.print("name = " + name + ", score = " + score);

    System.out.println(", percentile = " + percentile);
}
// retrieve values in output parameters
byte x = cstmt.getByte(1);
java.math.BigDecimal n = cstmt.getBigDecimal(2);

To generalize, the XXX in CallableStatement.getXXX and CallableStatement.setXXX methods is a Java type. For setXXX methods, the driver converts the Java type to a JDBC type before sending it to the database (using the standard mappings shown in Table 8.2 on page 106). For getXXX methods, the driver converts the JDBC type returned by the database to a Java type (using the standard mappings shown in Table 8.1 on page 105) before returning it to the getXXX method.

The method registerOutParameter always takes a JDBC type as an argument, and the method setObject may take a JDBC type as an argument.

Note that if a JDBC type is supplied in its optional third argument, the method setObject will cause an explicit conversion of the parameter value from a Java type to the JDBC type specified. If no target JDBC type is supplied to setObject, the parameter value will be converted to the JDBC type that is the standard mapping from the Java Object type (as shown in Table 8.4 on page 108). The driver will perform the explicit or implicit conversion before sending the parameter to the database.

8.6 Custom Mapping

The SQL3 user-defined types (UDTs), structured types and DISTINCT types, can be custom mapped to classes in the Java programming language. If a custom mapping has been set up, the driver will use that mapping instead of the standard mapping when it converts a UDT from a JDBC type to a Java type or vice versa.

UDTs are retrieved from the database with the methods ResultSet.getObject and CallableStatement.getObject; UDTs are sent back to the database with the method PreparedStatement.setObject. When an application calls a getObject method to retrieve a UDT, the driver will check to see if the type map associated with the connection has an entry for the UDT. If it does, the driver will use that type map to custom map the UDT; if there is no matching entry, the driver will use the standard mapping.

Almost all custom mapping is done using the connection's type map. It is possible, however, to have the driver use a different type map. The methods for which a custom mapping is possible have two versions, one that takes a type map and one that does not. The usual situation is not to supply a type map, in which case the driver uses the connection's type map by default. When a type map is supplied to a method, it supersedes the connection's type map, and the driver will use it instead of the type map associated with the connection to map a UDT. If the type map supplied has no entry for the UDT, the driver will use the standard mapping.

The setObject method does not take a type map as a parameter, so it operates a little differently. If setObject is passed an instance of a class that implements the SQLData interface, that is, an object that was custom mapped when it was retrieved, the driver will already have set up the mechanism for mapping it. The driver will convert the class instance, mapping the UDT back to its SQL type before sending it to the database. If the parameter to be set by the method setObject has not been custom mapped, the driver will use the standard mapping to convert it before sending it to the database.

The fact that only the methods getObject and setObject can be used to retrieve or store SQL structured types ensures that a custom mapping will be used if there is one. Four methods in the Array interface may be passed a type map so that if the ARRAY elements are UDTs, they can be custom mapped when the elements are materialized on the client. The Struct method getAttributes also has a version that takes a type map, which is used to custom map an SQL structured type's attributes before bringing them over to the client.

8.7 Dynamic Data Access

In most cases, the user wants to access results or parameters whose data types are known at compile time. However, some applications, such as generic browsers or query tools, are compiled with no knowledge of the database schema they will access. For this reason, JDBC provides support for fully dynamically typed data access in addition to static data type access.

Three methods facilitate accessing values whose data types are not known at compile time:

  • ResultSet.getObject
  • PreparedStatement.setObject
  • CallableStatement.getObject

If, for example, an application wants to be able to accept a variety of types as results in a ResultSet object, it can use the method ResultSet.getObject.

The methods ResultSet.getObject and CallableStatement.getObject retrieve a value as a Java Object. Since Object is the base class for all Java objects, an instance of any Java class can be retrieved as an instance of Object. However, the following Java types are built-in "primitive" types and are therefore not instances of the class Object: boolean, char, byte, short, int, long, float, and double. As a result, these types cannot be retrieved by getObject methods. However, each of these primitive types has a corresponding class that serves as a wrapper. Instances of these classes are objects, which means that they can be retrieved with the methods ResultSet.getObject and CallableStatement.getObject. Table 8.3 on page 107 shows the mapping from a JDBC type to a Java Object type. This table differs from the standard mapping from JDBC type to Java type in that each primitive Java type is replaced by its wrapper class, except that JDBC TINYINT and JDBC SMALLINT are mapped to the Java class Integer.

8.8 Storing Java Objects in a Database

Additions to the JDBC 2.0 core API make it easier to store Java objects in a database. The PreparedStatement.setObject method in the JDBC 1.0 API has always provided some support for persistent storage of objects defined in the Java programming language. With the new data type JAVA_OBJECT, in conjunction with the new method DatabaseMetaData.getUDTs, it is now easier to keep track of the Java objects stored in a database.

8.9 Tables for Type Mapping

This section contains the following tables relating to JDBC and Java data types:

Table 8.1-JDBC Types Mapped to Java Types

This table shows the conceptual correspondence between JDBC types and Java types. A programmer should write code with this mapping in mind. For example, if a value in the database is a SMALLINT, a short should be the data type used in a JDBC application.
All CallableStatement.getXXX methods except for getObject use this mapping. The getObject methods for both the CallableStatement and ResultSet interfaces use the mapping in "JDBC Types Mapped to Java Object Types" on page 107.

Table 8.2-Java Types Mapped to JDBC Types

This table shows the mapping a driver should use for the ResultSet.updateXXX methods and for IN parameters. PreparedStatement.setXXX methods and RowSet.setXXX methods use this table for mapping an IN parameter, which is a Java type, to the JDBC type that will be sent to the database. Note that the setObject methods for these two interfaces use the mapping shown in "Java Object Types Mapped to JDBC Types" on page 108.

Table 8.3-JDBC Types Mapped to Java Object Types

ResultSet.getObject and CallableStatement.getObject use the mapping shown in this table for standard mappings.

Table 8.4-Java Object Types Mapped to JDBC Types

PreparedStatement.setObject and RowSet.setObject use the mapping shown in this table when no parameter specifying a target JDBC type is provided.

Table 8.5-Conversions by setObject from Java Object Types to JDBC Types

This table shows which JDBC types may be specified as the target JDBC type to the methods PreparedStatement.setObject and RowSet.setObject.

Table 8.6-Type Conversions Supported by ResultSet.getXXX Methods

This table shows which JDBC types may be returned by ResultSet.getXXX methods. A bold X indicates the method recommended for retrieving a JDBC type. A plain x indicates for which JDBC types it is possible to use a getXXX method.
This table also shows the conversions used by the SQLInput.readXXX methods, except that they use only the recommended conversions.

Table 8.7-JDBC Types Mapped to Database-specific SQL Types

This table shows the names used by individual databases for their data types that most closely correspond to the JDBC types.

8.9.1 JDBC Types Mapped to Java Types
JDBC Type | Java Type
CHAR | String
VARCHAR | String
LONGVARCHAR | String
NUMERIC | java.math.BigDecimal
DECIMAL | java.math.BigDecimal
BIT | boolean
TINYINT | byte
SMALLINT | short
INTEGER | int
BIGINT | long
REAL | float
FLOAT | double
DOUBLE | double
BINARY | byte[]
VARBINARY | byte[]
LONGVARBINARY | byte[]
DATE | java.sql.Date
TIME | java.sql.Time
TIMESTAMP | java.sql.Timestamp
CLOB | Clob
BLOB | Blob
ARRAY | Array
DISTINCT | mapping of underlying type
STRUCT | Struct
REF | Ref
JAVA_OBJECT | underlying Java class

This table has two purposes. First, it illustrates the general correspondence between types in the Java programming language and the SQL types. Second, it shows the mapping used by CallableStatement.getXXX methods and SQLInput.readXXX methods. (Note that the mapping used by the CallableStatement.getObject method is shown in Table 8.3.)

8.9.2 Java Types Mapped to JDBC Types
Java Type | JDBC Type
String | CHAR, VARCHAR, or LONGVARCHAR
java.math.BigDecimal | NUMERIC
boolean | BIT
byte | TINYINT
short | SMALLINT
int | INTEGER
long | BIGINT
float | REAL
double | DOUBLE
byte[] | BINARY, VARBINARY, or LONGVARBINARY
java.sql.Date | DATE
java.sql.Time | TIME
java.sql.Timestamp | TIMESTAMP
Clob | CLOB
Blob | BLOB
Array | ARRAY
Struct | STRUCT
Ref | REF
Java class | JAVA_OBJECT

This table shows the conversions used for IN parameters before they are sent to the DBMS, used by the PreparedStatement.setXXX and RowSet.setXXX methods. These same conversions are also used by ResultSet.updateXXX methods and SQLOutput.writeXXX methods. (Note that the PreparedStatement.setObject and RowSet.setObject methods use the mapping in Table 8.4.)

The mapping for String will normally be VARCHAR but will turn into LONGVARCHAR if the given value exceeds the driver's limit on VARCHAR values. The same is true for byte[], which may be mapped to either VARBINARY or LONGVARBINARY values, depending on the driver's limit on VARBINARY values. In most cases, the choice between CHAR and VARCHAR is not significant. In any case, drivers will just make the right choice. The same is true for the choice between BINARY and VARBINARY.

8.9.3 JDBC Types Mapped to Java Object Types
JDBC Type | Java Object Type
CHAR | String
VARCHAR | String
LONGVARCHAR | String
NUMERIC | java.math.BigDecimal
DECIMAL | java.math.BigDecimal
BIT | Boolean
TINYINT | Integer
SMALLINT | Integer
INTEGER | Integer
BIGINT | Long
REAL | Float
FLOAT | Double
DOUBLE | Double
BINARY | byte[]
VARBINARY | byte[]
LONGVARBINARY | byte[]
DATE | java.sql.Date
TIME | java.sql.Time
TIMESTAMP | java.sql.Timestamp
DISTINCT | Object type of underlying type
CLOB | Clob
BLOB | Blob
ARRAY | Array
STRUCT | Struct or SQLData
REF | Ref
JAVA_OBJECT | underlying Java class

This table shows the mapping from JDBC types to Java object types that is used by the ResultSet.getObject and CallableStatement.getObject methods.

8.9.4 Java Object Types Mapped to JDBC Types
Java Object Type | JDBC Type
String | CHAR, VARCHAR, or LONGVARCHAR
java.math.BigDecimal | NUMERIC
Boolean | BIT
Integer | INTEGER
Long | BIGINT
Float | REAL
Double | DOUBLE
byte[] | BINARY, VARBINARY, or LONGVARBINARY
java.sql.Date | DATE
java.sql.Time | TIME
java.sql.Timestamp | TIMESTAMP
Clob | CLOB
Blob | BLOB
Array | ARRAY
Struct | STRUCT
Ref | REF
Java class | JAVA_OBJECT

These are the mappings used by the PreparedStatement.setObject method when no parameter specifying a target JDBC type is given. (The JDBC types that may be specified to the PreparedStatement.setObject method are shown in Table 8.5.)

Note that the mapping for String will normally be VARCHAR but will turn into LONGVARCHAR if the given value exceeds the driver's limit on VARCHAR values. The case is similar for byte[], which will be VARBINARY or LONGVARBINARY, depending on the driver's limit for VARBINARY values.

8.9.5 Conversions by setObject

Conversions by setObject [D]

An "x" means that the given Java object type may be converted to the given JDBC type. This table show the possible values for the parameter specifying a target JDBC type that is passed to the method PreparedStatement.setObject or RowSet.setObject. Note that some conversions may fail at run time if the value presented is invalid.

8.9.6 Conversions by ResultSet.getXXX Methods

Conversions by ResultSet.getXXX Methods [D]
SQLInput.readXXX methods support only the recommended conversions. An "x" means that the method can retrieve the JDBC type. An "X" means that the method is recommended for retrieving the JDBC type.

8.9.7 JDBC Types Mapped to Database-specific SQL Types

There is considerable variation among the different SQL types supported by the different databases. Table 8.7 shows the database-specific SQL types that best match the JDBC type for various major databases. The presence of a database-specific type name indicates that the given type can be used to achieve the semantics of the corresponding JDBC type, though the database-specific type may also provide additional semantics.

Notes and Lamentations:

  1. Some databases provide extra precision for some integral and floating-point types.
  2. Some databases provide a DATE or DATETIME type that can be used to contain either a DATE or a TIME or both.
  3. VARCHAR and VARCHAR2 are currently synonyms in Oracle8.
  4. For LONGVARCHAR, DB2 also supports "CLOB(n)" with a limit of 2 gigabytes.
  5. For LONGVARBINARY, DB2 also supports "BLOB(n)" with a limit of 2 gigabytes.
  6. Handling of BINARY, VARBINARY, and LONGVARBINARY literals in SQL statements varies widely among databases. We recommend using PreparedStatement.setBytes to set values in a portable way.
  7. Handling of DATE, TIME, and TIMESTAMP literals in SQL statements varies widely among databases. We recommend using the JDBC SQL escape syntax for dates and times (see "SQL Escape Syntax in Statements" on page 36) to set Date, Time, and Timestamp values in a portable way.

Types mapped to Database-specific SQL types [D]

See long description for previous image

[Top] [Prev] [Next]

Copyright © 1999, Sun Microsystems, Inc. All rights reserved.


 [Top] [Prev] [Next]

PreparedStatement

NOTE: The material in this chapter is based on JDBCtm API Tutorial and Reference, Second Edition: Universal Data Access for the Javatm 2 Platform, published by Addison Wesley as part of the Java series, ISBN 0-201-43328-1.

6.1 PreparedStatement Overview

The PreparedStatement interface inherits from Statement and differs from it in two ways:

  1. Instances of PreparedStatement contain an SQL statement that has already been compiled. This is what makes a statement "prepared."
  2. The SQL statement contained in a PreparedStatement object may have one or more IN parameters. An IN parameter is a parameter whose value is not specified when the SQL statement is created. Instead, the statement has a question mark ("?") as a placeholder for each IN parameter. The "?" is also known as a parameter marker. An application must set a value for each question mark in a prepared statement before executing the prepared statement.

Because PreparedStatement objects are precompiled, their execution can be faster than that of Statement objects. Consequently, an SQL statement that is executed many times is often created as a PreparedStatement object to increase efficiency.

Being a subclass of Statement, PreparedStatement inherits all the functionality of Statement. In addition, it adds a set of methods that are needed for setting the values to be sent to the database in place of the placeholders for IN parameters. Also, the three methods execute, executeQuery, and executeUpdate are modified so that they take no argument. The Statement forms of these methods (the forms that take an SQL statement parameter) should never be used with a PreparedStatement object.

6.1.1 Creating PreparedStatement Objects

The following code fragment, where con is a Connection object, creates a PreparedStatement object containing an SQL update statement with two placeholders for IN parameters:

PreparedStatement pstmt = con.prepareStatement(
    "UPDATE table4 SET m = ? WHERE x = ?");

The object pstmt now contains the statement "UPDATE table4 SET m = ? WHERE x = ?", which has already been sent to the DBMS and been prepared for execution.

As with Statement objects, it is possible to create a PreparedStatement object that contains a query rather than an update statement; in fact, this is often done to improve efficiency for SQL statements that are executed many times. Using the new version of the method prepareStatement included in the JDBC 2.0 core API, the PreparedStatement object can produce ResultSet objects that are scrollable and updatable. For example, the following code fragment creates a PreparedStatement object such that each time it is executed, it will produce a ResultSet object that is scrollable and updatable.

PreparedStatement pstmt2 = con.prepareStatement(
            "SELECT a, b, c FROM Table1", ResultSet.TYPE_SCROLL_SENSITIVE,
            ResultSet.CONCUR_UPDATABLE);
ResultSet rs = pstmt2.executeQuery();

The object that rs represents is a result set with all the values stored in columns a, b, and c of Table1, and rs is scrollable and can be updated. Each time pstmt2 is executed, it will produce a result set that is scrollable and updatable.

6.1.2 Passing IN Parameters

Before a PreparedStatement object is executed, the value of each ? parameter must be set. This is done by calling a setXXX method, where XXX is the appropriate type for the parameter. For example, if the parameter is of type long in the Java programming language, the method to use is setLong. The first argument to the setXXX methods is the ordinal position of the parameter to be set, with numbering starting at 1. The second argument is the value to which the parameter is to be set. For example, the following code sets the first parameter to 123456789 and the second parameter to 100000000:

pstmt.setLong(1, 123456789);
pstmt.setLong(2, 100000000);

Once a parameter value has been set for a given statement, it can be used for multiple executions of that statement until it is cleared by a call to the method clearParameters or until a new value is set.

When a connection has its auto-commit mode enabled, each statement is committed automatically when it is completed. Some database systems do not retain prepared statements across commits, so for them, the driver will have to recompile the prepared statement after each commit. This means that for these DBMSs, it may actually be less efficient to use a PreparedStatement object in place of a Statement object that is executed many times.

Using pstmt, the PreparedStatement object created above, the following code illustrates setting values for the two parameter placeholders and executing pstmt 10 times. In this example, the first parameter is set to "Hi" and remains constant. The second parameter is set to a different value each time around the for loop, starting with 0 and ending with 9.

pstmt.setString(1, "Hi");
for (int i = 0; i < 10; i++) {
    pstmt.setInt(2, i);
    int rowCount = pstmt.executeUpdate();
}

New features in the JDBC 2.0 API make it possible to set a parameter placeholder with an SQL3 data type, as shown in the following example, where statistics is a Blob object representing an SQL BLOB value, and departments is an Array object representing an SQL ARRAY value.

PreparedStatement pstmt = con.prepareStatement(
      "UPDATE Table3 SET Stats = ? WHERE Depts = ?");
pstmt.setBlob(1, statistics);
pstmt.setArray(2, departments);

6.1.3 Data Type Conformance on IN Parameters

The XXX in a setXXX method is a type in the Java programming language. It also implicitly specifies a JDBC type because the driver will map the Java type to its corresponding JDBC type (following the mapping specified in "Java Types Mapped to JDBC Types" on page 106) and send that JDBC type to the database. For example, the following code fragment sets the second parameter of the PreparedStatement object pstmt to 44, with a Java type of short:

pstmt.setShort(2, 44);

The driver will send 44 to the database as a JDBC SMALLINT, which is the standard mapping from a Java short.

It is the programmer's responsibility to make sure that the type in the Java programming language for each IN parameter maps to a JDBC type that is compatible with the JDBC data type expected by the database. Consider the case where the database expects a JDBC SMALLINT. If the method setByte is used, the driver will send a JDBC TINYINT to the database. This will probably work because many database systems convert from one related type to another, and generally a TINYINT can be used anywhere a SMALLINT is used. However, for an application to work with the most database systems possible, it is best to use types in the Java programming language that correspond to the exact JDBC types expected by the database. If the expected JDBC type is SMALLINT, using setShort instead of setByte will make an application more portable. The table "Java Types Mapped to JDBC Types" in the chapter "Mapping SQL and Java Types" can be used to determine which setXXX method to use.

6.1.4 Using setObject

A programmer can explicitly convert an input parameter to a particular JDBC type by using the method setObject. This method can take a third argument, which specifies the target JDBC type. The driver will convert the Object in the Java programming language to the specified JDBC type before sending it to the database.

If no JDBC type is given, the driver will simply map the Java Object to its default JDBC type and then send it to the database. This is similar to what happens with the regular setXXX methods; in both cases, the driver maps the Java type of the value to the appropriate JDBC type before sending it to the database. The difference is that the setXXX methods use the standard mapping, whereas the setObject method uses the mapping to object types.

The capability of the method setObject to accept any Java object allows an application to be generic and accept input for a parameter at run time. In this situation the type of the input is not known when the application is compiled. By using setObject, the application can accept any Java object type as input and convert it to the JDBC type expected by the database.

The JDBC 2.0 core API includes a new implementation of the method setObject that applies to a user-defined type (UDT) that has been custom mapped to a class in the Java programming language. The custom mapping of an SQL UDT is specified in a class that implements the SQLData interface. When a UDT instance is retrieved from the database via the method getObject, it will be mapped to an instance of the Java class that implemented SQLData for it. When that custom mapped instance is passed to the method setObject, setObject will call the SQLOutput.writeObject method that is defined in the appropriate SQLData implementation, thereby converting the instance of a Java class back to an SQL UDT.

The details of custom mapping are hidden from the user. When an application invokes the method setObject, the value being stored will automatically be custom mapped if there is a custom mapping for it. As a result, code in which the method setObject performs a custom mapping looks identical to code in which setObject uses the standard mapping. UDTs can only be stored using the setObject method, which is a way of ensuring that UDTs with a custom mapping are mapped appropriately.

In all of the cases discussed so far, the value passed to the method setObject was originally an SQL data type that was retrieved from a table column. Before returning it to the database, the driver needed to convert it back to its SQL data type. If a database is one of the new generation of Java-aware DBMSs, called a Java relational DBMS, it can store an instance of a class defined in the Java programming language as well as values defined in SQL. A class instance may be stored as a serialized Java object or in some other format defined by the DBMS.

The following example shows the use of the method setObject to store emp, an instance of the class Employee. After the salary field of emp is increased by 50 per cent, emp is sent back to the database. The column EMPLOYEE in the table PERSONNEL stores instances of Employee.

emp.salary = emp.salary * 1.5;
PreparedStatement pstmt = con.prepareStatement(
    "UPDATE PERSONNEL SET EMPLOYEE = ? WHERE EMPLOYEE_NO = 300485");
pstmt.setObject(1, emp);
pstmt.executeUpdate();

Note that the syntax in this example is the same as that in the JDBC 1.0 API and is also the same as that used to store instances of UDTs that have been custom mapped.

6.1.5 Sending JDBC NULL as an IN parameter

The setNull method allows a programmer to send a JDBC NULL (a generic SQL NULL) value to the database as an IN parameter. Note, however, that one must still specify the JDBC type of the parameter.

A JDBC NULL will also be sent to the database when a Java null value is passed to a setXXX method (if it takes Java objects as arguments). The method setObject, however, can take a null value only if the JDBC type is specified.

6.1.6 Sending Very Large IN Parameters

The methods setBytes and setString are capable of sending unlimited amounts of data. Sometimes, however, programmers prefer to pass in large blobs of data in smaller chunks. This can be accomplished by setting an IN parameter to a Java input stream. When the statement is executed, the JDBC driver will make repeated calls to this input stream, reading its contents and transmitting those contents as the actual parameter data.

The JDBC 1.0 API provides two methods for setting IN parameters to input streams: setBinaryStream for streams containing uninterpreted bytes and setAsciiStream for streams containing ASCII characters. A third method, set-UnicodeStream for streams containing Unicode characters, has been deprecated; the new JDBC 2.0 core API method setCharacterStream should be used in its place. These stream methods take one more argument than the other setXXX methods because the total length of the stream must be specified. This is necessary because some database systems need to know the total transfer size before any data is sent.

The following code illustrates using a stream to send the contents of a file as an IN parameter.

java.io.File file = new java.io.File("/tmp/data");
int fileLength = file.length();
java.io.InputStream fin = new java.io.FileInputStream(file);
java.sql.PreparedStatement pstmt = con.prepareStatement(
    "UPDATE Table5 SET stuff = ? WHERE index = 4");
pstmt.setBinaryStream (1, fin, fileLength);
pstmt.executeUpdate();

When the statement executes, the input stream fin will get called repeatedly to deliver up its data.

Another way to send large IN parameters to the database is to use SQL3 types like BLOB and CLOB. This is different from using streams in that BLOB and CLOB values are originally retrieved from the database, where they were created as SQL types. Using streams makes it possible to send the contents of a file written in the Java programming language to the database.

6.1.7 Using PreparedStatement Objects in Batch Updates

The JDBC 2.0 core API provides the ability to send multiple updates to the database for execution as a batch. The Statement method addBatch is given an SQL update statement as a parameter, and the SQL statement is added to the Statement object's list of commands to be executed in the next batch. The interface PreparedStatement has its own version of the method addBatch, which adds a set of parameters to the batch, as shown in the following code fragment.

PreparedStatement pstmt = con.prepareStatement(
         "UPDATE Table4 SET History = ? WHERE ID = ?");
pstmt.setClob(1, clob1);
pstmt.setLong(2, 350985839);
pstmt.addBatch();

pstmt.setClob(1, clob2);
pstmt.setLong(2, 350985840);
pstmt.addBatch();

int [] updateCounts = pstmt.executeBatch();

When the PreparedStatement object in pstmt is executed, it will be executed twice, once with the parameters clob1 and 350985839, and a second time with the parameters clob2 and 350985840. If either update command returns anything other than a single update count, the method executeBatch will throw an exception.

[Top] [Prev] [Next]

Copyright © 1999, Sun Microsystems, Inc. All rights reserved.


 [Top] [Prev] [Next]

ResultSet

NOTE: The material in this chapter is based on JDBCtm API Tutorial and Reference, Second Edition: Universal Data Access for the Javatm 2 Platform, published by Addison Wesley as part of the Java series, ISBN 0-201-43328-1.

5.1 ResultSet Overview

A ResultSet is a Java object that contains the results of executing an SQL query. In other words, it contains the rows that satisfy the conditions of the query. The data stored in a ResultSet object is retrieved through a set of get methods that allows access to the various columns of the current row. The ResultSet.next method is used to move to the next row of the ResultSet, making it the current row.

The general form of a result set is a table with column headings and the corresponding values returned by a query. For example, if your query is SELECT a, b, c FROM Table1, your result set will have the following form:

a           b               c
----------  ------------    -----------
12345       Cupertino       2459723.495
83472       Redmond         1.0
83492       Boston          35069473.43

The following code fragment is an example of executing an SQL statement that will return a collection of rows, with column a as an int, column b as a String, and column c as a float:

java.sql.Statement stmt = con.createStatement();
ResultSet rs = stmt.executeQuery("SELECT a, b, c FROM Table1");
while (rs.next()) {
    // retrieve and print the values for the current row
    int i = rs.getInt("a");
    String s = rs.getString("b");
    float f = rs.getFloat("c");
    System.out.println("ROW = " + i + " " + s + " " + f);
}

5.1.1 Rows and Columns

A relational database is made up of tables, with each table consisting of rows and columns. A row in a relational database table can be thought of as representing an instance of the entity that the table represents. For example, if there is a table of employees, each row will contain information about a particular employee. Each piece of data about the employee is stored in a column, so, for instance, the table of employees could have columns for an identification number, a name, a salary, and a date of hire. The columns in a row would contain the ID number, name, salary, and date of hire for a particular employee.

A result set is also a table with rows and columns, but it contains only the column values from a database table that satisfy the conditions of a query. In other words, a result set row will contain a subset of the columns in the underlying database table (unless the query selects everything in the table, in which case the result set table will include all of the column values for every row in the database table). In the past, a column value in a relational database table (and consequently in a result set table) had to be atomic; that is, it could be only one indivisible value. For instance, an array could not be a column value because an array may be made up of multiple elements. With the advent of SQL3 data types, however, the permissible content of table columns has expanded dramatically. It is now possible for an array or even a user-defined structured type to be a column value. Because this new capability allows a relational database to store instances of complex types as column values, it makes a relational database more like an object database, blurring the distinction between relational and object databases. Programmers can take advantage of these new data types if they use a JDBC 2.0 driver that supports SQL3 types.

5.1.2 Cursors

A ResultSet object maintains a cursor, which points to its current row of data. The cursor moves down one row each time the method next is called. When a ResultSet object is first created, the cursor is positioned before the first row, so the first call to the next method puts the cursor on the first row, making it the current row. ResultSet rows can be retrieved in sequence from top to bottom as the cursor moves down one row with each successive call to the method next. This ability to move its cursor only forward is the default behavior for a ResultSet and is the only cursor movement possible with drivers that implement only the JDBC 1.0 API. This kind of result set has the type ResultSet.TYPE_FORWARD_ONLY and is referred to as a forward only result set.

If a driver implements the cursor movement methods in the JDBC 2.0 core API, its result sets can be scrollable. A scrollable result set's cursor can move both forward and backward as well as to a particular row. The following methods move the cursor backward, to the first row, to the last row, to a particular row number, to a specified number of rows from the current row, and so on: previous, first, last, absolute, relative, afterLast, and beforeFirst. An explanation and example of how to make a result set scrollable will be presented in the section "Creating Different Types of Result Sets" on page 55.

When a cursor is positioned on a row in a ResultSet object (not before the first row or after the last row), that row becomes the current row. This means that any methods called while the cursor is positioned on that row will (1) operate on values in that row (methods such as getXXX and updateXXX), (2) operate on the row as a whole (such as the methods updateRow, insertRow, deleteRow, refresh-Row), or (3) use that row as a starting point for moving to other rows (such as the method relative).

A cursor remains valid until the ResultSet object or its parent Statement object is closed.

5.1.3 Cursor Movement Examples

As stated in the previous section, the standard cursor movement for forward only result sets is to use the method next to iterate through each row of a result set once from top to bottom. With scrollable result sets, it is possible to revisit a row or to iterate through the result set multiple times. This is possible because the cursor can be moved before the first row at any time (with the method beforeFirst method (ResultSet interface)>beforeFirst). The cursor can begin another iteration through the result set with the method next. The following example positions the cursor before the first row and then iterates forward through the contents of the result set. The methods getString and getFloat retrieve the column values for each row until there are no more rows, at which time the method next returns the value false.

rs.beforeFirst();
while (rs.next()) {
    System.out.println(rs.getString("EMP_NO") +
        " " + rs.getFloat("SALARY");
}

It is also possible to iterate through a result set backwards, as is shown in the next example. The cursor is first moved to the very end of the result set (with the method afterLast), and then the method previous is invoked within a while loop to iterate through the contents of the result set by moving to the previous row with each iteration. The method previous returns false when there are no more rows, so the loop ends after all the rows have been visited.

rs.afterLast();
while (rs.previous()) {
    System.out.println(rs.getString("EMP_NO") +
        " " + rs.getFloat("SALARY");
}

The interface ResultSet offers still other ways to iterate through the rows of a scrollable result set. Care should be taken, however, to avoid incorrect alternatives such as the one illustrated in the following example:

// incorrect!
while (!rs.isAfterLast()) {
  rs.relative(1);
  System.out.println(
    rs.getString("EMP_NO") + " " + rs.getFloat("SALARY"));
}

This example attempts to iterate forward through a scrollable result set and is incorrect for several reasons. One error is that if ResultSet.isAfterLast is called when the result set is empty, it will return a value of false since there is no last row. The loop body will be executed, which is not what is wanted. An additional problem occurs when the cursor is positioned before the first row of a result set that contains data. In this case, calling rs.relative(1) is erroneous because there is no current row. The method relative moves the cursor the specified number of rows from the current row, and it must be invoked only while the cursor is on the current row.

The following code fragment fixes the problems in the previous example. Here a call to the method ResultSet.first is used to distinguish the case of an empty result set from one that contains data. Because ResultSet.isAfterLast is called only when the result set is non-empty, the loop control works correctly. Since ResultSet.first method (ResultSet interface)>first initially positions the cursor on the first row, the method ResultSet.relative(1) steps through the rows of the result set as expected.

if (rs.first()) {
  while (!rs.isAfterLast()) {
    System.out.println(
         rs.getString("EMP_NO") + " " + rs.getFloat("SALARY"));
    rs.relative(1);
    }
}

5.1.4 Determining the Number of Rows in a Result Set

With the new cursor movement methods, it is easy to see how many rows a scrollable ResultSet object contains. All that is necessary is to go to the last row of the result set and get the number of that row. In the following example, rs will have one row for each employee.

ResultSet rs = stmt.executeQuery(
        "SELECT LAST_NAME, FIRST_NAME FROM EMPLOYEES");
rs.last();
int numberOfRows = rs.getRow();
System.out.println("XYZ, Inc. has " + numberOfRows + " employees");
rs.beforeFirst();
while (next()) {
    . . . // retrieve first and last names of each employee
}

Though not as convenient, it is also possible to find out how many rows a nonscrollable result set has. The following example shows one way to determine the number of rows.

ResultSet rs = stmt.executeQuery("SELECT COUNT(*) FROM EMPLOYEES");
rs.next();
int count = rs.getInt(1);
System.out.println("XYZ, Inc. has " + count + " employees");

ResultSet rs2 = stmt.executeQuery(
        "SELECT LAST_NAME, FIRST_NAME FROM EMPLOYEES");
while (rs2.next()) {
    . . . // retrieve first and last names of each employee
}

With the scrollable result set, the cursor was just repositioned to start iterating through the same result set to retrieve its data. In the preceding example, however, one query is needed to get the count, and another query is needed to get a result set with the data that is desired. Both queries must, of course, produce result sets of the same size for the count to be accurate.

A second way to determine the number of rows in a forward-only result set is to iterate through the result set, incrementing a variable with each iteration, which is shown in the following example. Because an application can iterate through a forward-only result set just once, the same query needs to be executed twice. In the iteration through the first rs, the number of rows is counted; in the iteration through the second rs, the data is retrieved.

ResultSet rs = stmt.executeQuery(
        "SELECT LAST_NAME, FIRST_NAME FROM EMPLOYEES");
int count = 0;
while (rs.next()) {
    count++;
}
System.out.println("Company XYZ has " + count " employees.");
rs = stmt.executeQuery(
        "SELECT LAST_NAME, FIRST_NAME FROM EMPLOYEES");
while (rs.next()) {
    . . . // retrieve first and last names of each employee
}

5.1.5 Retrieving Column Values

The ResultSet.getXXX methods provide the means for retrieving column values from the current row. For maximum portability with forward only result sets, values should be retrieved from left to right, and column values should be read only once. With scrollable result sets, however, there are no such restrictions.

Either the column name or the column number can be used to designate the column from which to retrieve data. For example, if the second column of a ResultSet object rs is named TITLE, and it stores values as strings, either of the following will retrieve the value stored in that column:

String s = rs.getString(2);
String s = rs.getString("TITLE");

Note that columns are numbered from left to right starting with column 1. Also, column names used as input to getXXX methods are case insensitive.

The option of using the column name was provided so that a user who specifies column names in a query can use those same names as the arguments to getXXX methods. If, on the other hand, the SELECT statement does not specify column names (as in "SELECT * FROM TABLE1" or in cases where a column is derived), column numbers should be used. In such situations, there is no way for the user to know for sure what the column names are.

In some cases, it is possible for an SQL query to return a result set that has more than one column with the same name. If a column name is used as the parameter to a getXXX method, getXXX will return the value of the first matching column name. Thus, if there are multiple columns with the same name, one needs to use a column index to be sure that the correct column value is retrieved. It may also be slightly more efficient to use column numbers.

If the name of a column is known but not its index, the method findColumn can be used to find the column number.

Information about the columns in a ResultSet is available by calling the method ResultSet.getMetaData. The ResultSetMetaData object returned gives the number, types, and properties of its ResultSet object's columns.

5.1.6 Which getXXX Method to Use

JDBC drivers support type coercion. When a getXXX method is invoked, the driver attempts to convert the underlying data to the type XXX in the Java programming language and then returns a suitable value. For example, if the getXXX method is getString, and the data type of the data in the underlying database is VARCHAR, the JDBC Compliant driver will convert the VARCHAR value to a String object in the Java programming language. That String object will be the value returned by getString.

The JDBC 2.0 API adds new ResultSet.getXXX methods for retrieving the new SQL3 data types. These methods work the same way the getXXX methods in the JDBC 1.0 API work; that is, they map the SQL3 JDBC type to a type in the Java programming language and return that type. For example, the method getClob retrieves a JDBC CLOB value from the database and returns a Clob object, which is an instance of the java.sql.Clob interface.

The method getObject will retrieve any data type. This is possible because Object, being the type from which every other object type in the Java programming language is derived, is the most generic type. This is especially useful when the underlying data type is a database-specific type or when a generic application needs to be able to accept any data type. The method getObject, as would be expected from its name, returns a Java Object that must be narrowed if it is to be used as a more specific type. In other words, it must be cast from its generic Object type to its more derived type before it can be used as that derived type. The following code fragment illustrates using the method getObject to retrieve a Struct value from the column ADDRESS in the current row of the ResultSet object rs. The Object that getObject returns is narrowed to a Struct before assigning it to the variable address.

Struct address = (Struct)rs.getObject("ADDRESS");

The method getObject is not only the one method capable of retrieving values of any data type but also the only ResultSet.getXXX method that does custom mapping. Therefore, to be custom mapped, a data type has to be retrieved with the method getObject. The two SQL data types that can be custom mapped are the user-defined types, SQL structured types and DISTINCT types. A JDBC DISTINCT value is normally retrieved with the getXXX method appropriate for its underlying type, but if it has a custom mapping, it must be retrieved by the method getObject in order to be custom mapped. A JDBC STRUCT can only be retrieved with the method getObject, guaranteeing that if there is a custom mapping for a JDBC STRUCT value, it will be used.

use of ResultSet.getXXX methods to retriee JDBC types [D]

An "x" indicates that the getXXX method may legally be used to retrieve the given JDBC type.

An "X" indicates that the getXXX method is recommended for retrieving the given JDBC type.

5.1.7 Types of Result Sets

Results sets may have different levels of functionality. For example, they may be scrollable or nonscrollable. A scrollable result set has a cursor that moves both forward and backward and can be moved to a particular row. Also, result sets may be sensitive or insensitive to changes made while they are open; that is, they may or may not reflect changes to column values that are modified in the database. A developer should always keep in mind the fact that adding capabilities to a ResultSet object incurs additional overhead, so it should be done only as necessary.

Based on the capabilities of scrollability and sensitivity to changes, there are three types of result sets available with the JDBC 2.0 core API. The following constants, defined in the ResultSet interface, are used to specify these three types of result sets:

  1. TYPE_FORWARD_ONLY
    • The result set is nonscrollable; its cursor moves forward only, from top to bottom.
    • The view of the data in the result set depends on whether the DBMS materializes results incrementally.
  2. TYPE_SCROLL_INSENSITIVE
    • The result set is scrollable: Its cursor can move forward or backward and can be moved to a particular row or to a row whose position is relative to its current position.
    • The result set generally does not show changes to the underlying database that are made while it is open. The membership, order, and column values of rows are typically fixed when the result set is created.
  3. TYPE_SCROLL_SENSITIVE
    • The result set is scrollable; its cursor can move forward or backward and can be moved to a particular row or to a row whose position is relative to its current position.
    • The result set is sensitive to changes made while it is open. If the underlying column values are modified, the new values are visible, thus providing a dynamic view of the underlying data. The membership and ordering of rows in the result set may be fixed or not, depending on the implementation.

5.1.8 Concurrency Types

A result set may have different update capabilities. As with scrollability, making a ResultSet object updatable increases overhead and should be done only when necessary. That said, it is often more convenient to make updates programmatically, and that can only be done if a result set is made updatable. The JDBC 2.0 core API offers two update capabilities, specified by the following constants in the ResultSet interface:

  1. CONCUR_READ_ONLY
    • Indicates a result set that cannot be updated programmatically
    • The one concurrency type available to drivers that implement only the JDBC 1.0 API
    • Offers the highest level of concurrency (allows the largest number of simultaneous users). When a ResultSet object with read-only concurrency needs to set a lock, it uses a read-only lock. This allow users to read data but not to change it. Because there is no limit to the number of read-only locks that may be held on data at one time, there is no limit to the number of concurrent users unless the DBMS or driver imposes one.
  2. CONCUR_UPDATABLE
    • Indicates a result set that can be updated programmatically
    • Available to drivers that implement the JDBC 2.0 core API
    • Reduces the level on concurrency. Updatable results sets may use write-only locks so that only one user at a time has access to a data item. This eliminates the possibility that two or more users might change the same data, thus ensuring database consistency. However, the price for this consistency is a reduced level of concurrency.

To allow a higher level of concurrency, an updatable result set may be implemented so that it uses an optimistic concurrency control scheme. This implementation assumes that conflicts will be rare and avoids using write-only locks, thereby permitting more users concurrent access to data. Before committing any updates, it determines whether a conflict has occurred by comparing rows either by value or by a version number. If there has been an update conflict between two transactions, one of the transactions will be aborted in order to maintain consistency. Optimistic concurrency control implementations can increase concurrency; however, if there are too many conflicts, they may actually reduce performance.

5.1.9 Providing Performance Hints

Many DBMSs and drivers are optimized to give the best performance under various circumstances, which means that generally a database programmer is best advised to use their default settings. However, for programmers who may want to fine tune database performance for a particular application, the JDBC 2.0 API provides methods that give hints to the driver for making access to result set data more efficient. These performance hints are exactly that, just hints; a JDBC Compliant driver may choose to ignore them.

The following two hints give the driver suggestions for improving performance:

  1. The number of rows that should be fetched from the database each time new rows are needed The number of rows to be fetched is called the fetch size, and it can be set by two different methods: Statement.setFetchSize and ResultSet.setFetchSize. The statement that creates a ResultSet object sets the default fetch size for that ResultSet object, using the Statement method setFetchSize. The following code fragment sets the fetch size for the ResultSet object rs to 25. Until the fetch size is changed, any result set created by the Statement object stmt will automatically have a fetch size of 25.
    Statement stmt = con.createStatement();
stmt.setFetchSize(25);
ResultSet rs = stmt.executeQuery(SELECT * FROM EMPLOYEES);
    A result set can, at any time, change its default fetch size by setting a new fetch size with the ResultSet version of the method setFetchSize. Continuing from the previous code fragment, the following line of code changes the fetch size of rs to 50:
    rs.setFetchSize(50);
    Normally the most efficient fetch size is already the default for the driver. The method setFetchSize simply allows a programmer to experiment to see if a certain fetch size is more efficient than the default for a particular application.

  2. The direction in which rows will be processed

    The interface ResultSet defines the following three constants for specifying the direction in which to process rows: FETCH_FORWARD, FETCH_REVERSE, and FETCH_UNKNOWN. As with the fetch size, there are two methods for setting the fetch direction, one in the interface Statement, and the other in the interface ResultSet. The statement that creates the result set determines the default fetch direction by using the Statement method setFetchDirection. The following code fragment sets the fetch direction for the ResultSet object rs so that it will process rows from the bottom up. Until the fetch direction is changed, any result set created by the Statement object stmt will automatically have a fetch direction of backward.

    Statement stmt = con.createStatement();
stmt.setFetchDirection(FETCH_REVERSE);
ResultSet rs = stmt.executeQuery(SELECT * FROM EMPLOYEES);
    A result set can, at any time, change its default fetch direction by setting a new fetch direction with the ResultSet method setFetchDirection. Continuing from the previous code fragment, the following line of code changes the fetch direction of rs to forward.
    rs.setFetchDirection(FETCH_FORWARD);
    The ResultSet object rs will hint that the driver process rows in a forward direction. This hint will be in effect until the method ResultSet.setFetchDirection is again called on rs to change the suggested fetch direction.

    As with the fetch size, drivers are commonly optimized to use the most efficient fetch direction, and changing the default may actually work against this optimization. The method setFetchDirection simply allows a programmer to try to fine tune an application for even better performance.

5.1.10 Creating Different Types of Result Sets

A result set is created by executing a query, and the type of result set depends on the arguments that are supplied to the Connection method createStatement (or prepareStatement or prepareCall). The following code fragment, which uses only JDBC 1.0 API, supplies no arguments to the method createStatement and thus creates a default ResultSet object, one that is forward-only and uses read-only concurrency.

Connection con = DriverManager.getConnection(
        "jdbc:my_subprotocol:my_subname");
Statement stmt = con.createStatement();
ResultSet rs = stmt.executeQuery(
    "SELECT EMP_NO, SALARY FROM EMPLOYEES");

The variable rs represents a ResultSet object that contains the values for the columns EMP_NO and SALARY from every row in the table EMPLOYEES. This result set is not scrollable, so only the method next can be used to move the cursor from the top down through the rows of the result set. The ResultSet object rs cannot be updated, and since no performance hints were given, the driver is free to do whatever it thinks will produce the best performance. The transaction isolation level was likewise not set, so rs will use the default transaction isolation level of the underlying database. (See "Transaction Isolation Levels" on page 22 for an explanation of transaction isolation levels.)

The next example uses the new JDBC 2.0 core API to create a scrollable result set that is sensitive to updates (by specifying ResultSet.TYPE_SCROLL_SENSITIVE) and that is updatable (by specifying ResultSet.CONCUR_UPDATABLE).

Connection con = DriverManager.getConnection(
        "jdbc:my_subprotocol:my_subname");

Statement stmt = con.createStatement(
        ResultSet.TYPE_SCROLL_SENSITIVE,
         ResultSet.CONCUR_UPDATABLE);
stmt.setFetchSize(25);

ResultSet rs2 = stmt.executeQuery(
        "SELECT EMP_NO, SALARY FROM EMPLOYEES");

The variable rs2 contains the same values as rs, from the previous example, but unlike rs, it is scrollable, updatable, and sensitive to changes in the underlying table's data. It also hints that the driver should fetch 25 rows from the database each time new rows are needed. Each time the Statement object stmt is executed, it will create a result set that is scrollable, is updatable, is sensitive to changes in its data, and has a fetch size of 25. The result set may change its fetch size, but it cannot change its type or concurrency.

As stated previously, there is a cost to making a result set scrollable or updatable, so it is good practice to create result sets with these features only when they are needed.

5.1.11 Using a Prepared Statement to Create Result Sets

Because PreparedStatement and CallableStatement objects inherit the methods defined in the Statement interface, they, too, can create different types of ResultSet objects.

The following code fragment creates a result set using a PreparedStatement object instead of a Statement object. The result set has the same attributes as in the previous example, except that a transaction isolation level is set for the connection.

Connection con = DriverManager.getConnection(
            "jdbc:my_subprotocol:my_subname");
con.setTransactionIsolation(TRANSACTION_READ_COMMITTED);

PreparedStatement pstmt = con.prepareStatement(
            "SELECT EMP_NO, SALARY FROM EMPLOYEES WHERE EMP_NO = ?",
            ResultSet.TYPE_SCROLL_SENSITIVE,
            ResultSet.CONCUR_UPDATABLE);
pstmt.setFetchSize(25);
pstmt.setString(1, "1000010");

ResultSet rs3 = pstmt.executeQuery();

The variable rs3 contains the values from the columns EMP_NO and SALARY for the row where the value for EMP_NO is 1000010. The ResultSet object rs3 is like rs2 in that it is scrollable, is updatable, is sensitive to changes in its data, and hints that the driver should fetch 25 rows at a time from the database. It is different in that its connection specifies that dirty reads (reading values before they are committed) will be prevented. Because no transaction isolation level was set for rs2, it will by default have the isolation level of the underlying database.

5.1.12 Requesting Features That Are Not Supported

With the addition of new functionality in the JDBC 2.0 API, it is possible for an application to request features that a DBMS or driver do not support. If the driver does not support scrollable result sets, for example, it may return a forward-only result set. Also, some queries will return a result set that cannot be updated, so requesting an updatable result set would have no effect for those queries. A general rule is that a query should include the primary key as one of the columns it selects, and it should reference only one table.

New methods in the JDBC 2.0 API let an application discover which result set features a driver supports. If there is any doubt about whether a feature is supported, it is advisable to call these methods before requesting the feature. The following DatabaseMetaData methods indicate whether a driver supports a given result set type or a given result set concurrency:

  • DatabaseMetaData.supportsResultSetType - returns a boolean indicating whether the driver supports the given result set type
  • DatabaseMetaData.supportsResultSetConcurrency - returns a boolean indicating whether the driver supports the given concurrency type in combination with the given result set type

The following ResultSet methods return the result set type and result set concurrency for the particular result set on which the method is called:

  • ResultSet.getType - returns the type of this result set
  • ResultSet.getConcurrency - returns the concurrency mode of this result set

If an application specifies a scrollable result set and the driver does not support scrolling, the driver will issue a warning on the Connection object that produced the statement and return a result set that is forward-only. Even if the driver supports scrollable result sets, it is possible for an application to request a scrollable type that the driver does not support. In such a case, the driver will issue an SQLWarning on the Connection object that produced the statement and return a scrollable result set of a type that it does support, even if it differs from the exact type requested. For example, if an application requests a TYPE_SCROLL_SENSITIVE result set and the driver does not support that type, it could return a TYPE_SCROLL_INSENSITIVE result set if it supports that type. The driver would also alert the application that it did not return the exact type requested by issuing an SQLWarning on the Connection object that produced the statement requesting the unsupported result set type.

Similarly, if an application specifies an updatable result set, a driver that does not support updatable result sets will issue an SQLWarning on the Connection object that produced the statement and return a read-only result set. If the application requests both an unsupported result set type and an unsupported concurrency type, the driver should choose the result set type first.

In some situations, a driver may need to choose an alternate result set type or concurrency type at statement execution time. For example, a SELECT statement that contains a join over multiple tables might produce a result set that is not updatable. In such a situation, the driver will issue an SQLWarning on the Statement, PreparedStatement, or CallableStatement object that tried to create the result set instead of issuing it on the Connection object. The driver will then choose an appropriate result set type and/or concurrency type according to the guidelines in the preceding two paragraphs.

5.1.13 Using updateXXX Methods

A ResultSet object may be updated (have its rows modified, inserted, or deleted) programmatically if its concurrency type is CONCUR_UPDATABLE. The JDBC 2.0 API adds updateXXX methods and various other methods to the ResultSet interface so that rows can be programmatically updated in both the ResultSet object and the database.

The new updateXXX methods make it possible to update values in a result set without using SQL commands. There is an updateXXX method for each data type, and as with the getXXX and setXXX methods, the XXX is a data type in the Java programming language. As with the setXXX methods, the driver converts this data type to an SQL data type before sending it to the database. So for example, the method updateBoolean sends a JDBC BIT value to the database, and the method updateCharacterStream sends a JDBC LONGVARCHAR value to the database.

The updateXXX methods take two parameters, the first to indicate which column is to be updated, and the second to give the value to assign to the specified column. As is true with the getXXX methods, the column can be specified by giving either its name or its index. If an application retrieved a value from a result set by using the column name, it will generally use the column name when it wants to update that value. Similarly, if the getXXX method was given a column index to retrieve a value, the corresponding updateXXX method will generally use the column index to update that value.

Note that the column index used with ResultSet methods refers to the column number in the result set, not the column number in the database table, which might well be different. (The column numbers will be the same only in the case where all of a table's columns are selected.) In both result set tables and database tables, the index for the first column is 1, the index for the second column is 2, and so on.

In the following code fragment, the value in the third column of the ResultSet object rs is retrieved using the method getInt, and the method updateInt is used to update that column value with an int value of 88:

int n = rs.getInt(3); // n contains the value in column 3 of rs
. . .
rs.updateInt(3, 88); // the value in column 3 of rs is set to 88
int n = rs.getInt(3); // n = 88

If the third column is named SCORES, the following lines of code will also update the third column of the ResultSet object rs by assigning it the int value 88:

int n = rs.getInt("SCORES");
. . .
rs.updateInt("SCORES", 88);

The updateXXX methods update a value in the current row of the result set, but they do not update the value in the underlying database table. It is the method updateRow that updates the database. It is very important that the updateRow method be called while the cursor is still on the current row (the row to be updated). In fact, if an application moves the cursor before it calls updateRow, the driver must discard the update, and neither the result set nor the database will be updated.

An application may explicitly cancel the updates to a row by calling the method cancelRowUpdates. To take effect, it must be called after the method updateXXX is called and before the method updateRow is called. If cancelRowUpdates is called at any other time, it has no effect.

The following example demonstrates updating the second and third columns in the fourth row of the ResultSet object rs. Since updates affect the current row, the cursor is first moved to the row to be updated, which in this case is the fourth row. Next the method updateString is called to change the value in the second column of rs to 321 Kasten. The method updateFloat changes the value in the third column of rs to 10101.0. Finally, the method updateRow is called to update the row in the database that contains the two modified column values.

rs.absolute(4);
rs.updateString(2, "321 Kasten");
rs.updateFloat(3, 10101.0f);
rs.updateRow();

If the second column is named ADDRESS and the third column is named AMOUNT, the following code will have exactly the same effect as the previous example.

rs.absolute(4);
rs.updateString("ADDRESS", "321 Kasten");
rs.updateFloat("AMOUNT", 10101.0f);
rs.updateRow();

In addition to making updates programmatically, the JDBC 2.0 core API provides the ability to send batch updates. The batch update facility operates through a Statement object, which is explained in the section "Sending Batch Updates" on page 39.

5.1.14 Deleting a Row

The JDBC 2.0 API provides the method deleteRow so that a row in a ResultSet object can be deleted using only methods in the Java programming language. This method deletes the current row, so before calling deleteRow, an application must position the cursor on the row it wants to delete. Unlike the updateXXX methods, which affect only a row in the result set, this method affects both the current row in the result set and the underlying row in the database. The following two lines of code remove the first row of the ResultSet object rs and also delete the underlying row from the database (which may or may not be the first row of the database table).

rs.first();
rs.deleteRow();

5.1.15 Inserting Rows

New rows may be inserted into a result set table and into the underlying database table using new methods in the JDBC 2.0 core API. To make this possible, the API defines the concept of an insert row. This is a special row, associated with the result set but not part of it, that serves as a staging area for building the row that is to be inserted. To access the insert row, an application calls the ResultSet method moveToInsertRow, which positions the cursor on the insert row. Then it calls the appropriate updateXXX methods to add column values to the insert row. When all of the columns of the row to be inserted have been set, the application calls the method insertRow. This method adds the insert row to both the result set and the underlying database simultaneously. Finally, the application needs to position the cursor on a row back in the result set.

The following code fragment demonstrates these steps for inserting a row from an application written in the Java programming language.

rs.moveToInsertRow();
rs.updateObject(1, myArray);
rs.updateInt(2, 3857);
rs.updateString(3, "Mysteries");
rs.insertRow();
rs.first();

Several details deserve attention. First, it is possible to retrieve values from the insert row using the ResultSet.getXXX methods. Until a value has been assigned to the insert row with an updateXXX method, however, its contents are undefined. Therefore, if a getXXX method is called after the moveToInsertRow method has been called but before an updateXXX method has been called, the value it returns will be undefined.

Second, calling an updateXXX method on the insert row is different from calling it on a row in the ResultSet object. When the cursor is on a row in a result set, a call to an updateXXX method changes a value in the result set. When the cursor is on the insert row, a call to an updateXXX method updates a value in the insert row but does nothing to the result set. In both cases, though, the updateXXX method has no effect on the underlying database.

Third, calling the method insertRow, which adds the insert row to both the result set and database, may throw an SQLException if the number of columns in the insert row does not match the number of columns in the database table. For example, if a column is not given a value by calling an updateXXX method, an SQLException will be thrown unless that column allows null values. Also, if the result set is missing a column, that, too, will cause an SQLException to be thrown unless the column allows null values.

Fourth, a result set keeps track of where its cursor was positioned when the cursor moved to the insert row. As a result, a call to the method ResultSet.moveToCurrentRow will return the cursor to the row that was the current row immediately before the method moveToInsertRow was called. The other cursor movement methods also work from the insert row, including those that use positioning relative to the current row.

5.1.16 Positioned Updates

Before the JDBC 2.0 API made programmatic updates available in the Java programming language, the only way to change a row that had been fetched with a result set was to use what is called a positioned update. A positioned update is done with SQL commands and requires a named cursor to indicate the result set row in which updates are to be made.

The Statement interface provides the method setCursorName, which allows an application to specify a cursor name for the cursor associated with the next result set produced by a statement. This name can then be used in SQL positioned update or delete statements to identify the current row in the ResultSet object generated by the statement. In order to enable a positioned update or delete on a result set, the query that produces it must have the following form:

SELECT . . . FROM . . . WHERE . . . FOR UPDATE . . .

Including the words "FOR UPDATE" ensures that the cursor has the proper isolation level to support an update.

After the method executeQuery has been called on the statement, the cursor name for the resulting ResultSet object can be obtained by calling the ResultSet method getCursorName. If a DBMS allows positioned updates or positioned deletes, the name of the cursor can be supplied as a parameter to the SQL command for updates or deletes. A Statement object other than the one that created the ResultSet object must be used for the positioned update. The following code fragment, in which stmt and stmt2 are two different Statement objects, demonstrates the form for naming a cursor and then using it in an SQL update statement:

stmt.setCursorName("x");
ResultSet rs = stmt.executeQuery(
        "SELECT . . . FROM . . . WHERE . . . FOR UPDATE . . .")
String cursorName = rs.getCursorName;
int updateCount = stmt2.executeUpdate(
        "UPDATE . . . WHERE CURRENT OF " + cursorName);

Note that just because the method getCursorName has been invoked on a ResultSet object does not necessarily mean that it can be updated using the ResultSet.updateXXX methods available in the JDBC 2.0 core API. In order to update a ResultSet object using the updateXXX methods, the executeQuery statement that produces the result set must include the specification CONCUR_UPDATABLE. Positioned updates, however, are possible for a result set created without this specification if all the proper steps are taken: (1) a cursor is named, (2) the SQL query that produces the result set is of the form SELECT . . . FROM . . . WHERE . . . FOR UPDATE . . ., and (3) the SQL update statement is of the form UPDATE . . . WHERE CURRENT OF <cursorName>.

Not all DBMSs support positioned updates. To verify that a DBMS supports positioned updates, an application can call the DatabaseMetaData methods supportsPositionedDelete and supportsPositionedUpdate to discover whether a particular connection supports these operations. When they are supported, the DBMS/driver must ensure that rows selected are properly locked so that positioned updates do not result in update anomalies or other concurrency problems.

5.1.17 Queries That Produce Updatable Result Sets

Some queries will produce result sets that cannot be updated no matter what the result set type. For example, a query that does not select the primary key column might generate a result set that cannot be updated. Because of differences in database implementations, the JDBC 2.0 core API does not specify an exact set of SQL queries that must yield updatable result sets. Instead it defines a set of criteria that should generally produce updatable result sets for JDBC Compliant drivers that support updatability. If queries adhere to the following guidelines, a developer can generally expect that they will produce updatable result sets:

  1. The query references only a single table in the database
  2. The query does not contain a join operation or a GROUP BY clause
  3. The query selects the primary key of the table it references

    If inserts are to be performed on the result set, an SQL query should satisfy conditions one through three plus the following three additional conditions:

  4. The user has read/write database privileges on the table
  5. The query selects all of the nonnullable columns in the underlying table
  6. The query selects all columns that do not have a default value

The fourth and fifth conditions are necessary because a row to be inserted into a table must have a value for each column in the table unless the column accepts null values or default values. If the result set on which insertion operations are to be performed does not contain every column that requires a value, the insertion will fail.

Result sets created by means other than the execution of a query, such as those returned by several methods in the DatabaseMetaData interface, are not scrollable or updatable, nor are they required to be.

5.1.18 Using Streams for Very Large Row Values

Two new interfaces in the JDBC 2.0 core API, Blob and Clob, are the mapping of the SQL3 data types BLOB (Binary Large Object) and CLOB (Character LargeObject) in the Java programming language. With the availability of these data types, databases will undoubtedly start using them to store very large binary or character objects. If this is the case, the ResultSet methods getBlob and getClob should be used to retrieve them.

Using only the JDBC 1.0 API, a ResultSet object still makes it possible to retrieve arbitrarily large LONGVARBINARY or LONGVARCHAR data. The methods getBytes and getString return data as one large chunk (up to the limits imposed by the return value of Statement.getMaxFieldSize). It is possible to retrieve this large chunk of data in smaller, fixed-size chunks. This is done by having the ResultSet class return java.io.Input streams from which data can be read in chunks. Note that these streams must be accessed immediately because they will be closed automatically when the next getXXX method is called on the ResultSet object. (This behavior is not a limitation of the JDBC API but rather a constraint on large blob access imposed by the underlying implementations in some database -systems.)

The JDBC 1.0 API has three separate methods for getting streams, each with a different return value:

  • getBinaryStream - returns a stream that simply provides the raw bytes from the database without any conversion
  • getAsciiStream - returns a stream that provides one-byte ASCII characters. This method can be more efficient for a DBMS that stores characters in ASCII format.
  • getUnicodeStream - returns a stream that provides two-byte Unicode characters. This method, though still available, has been deprecated in favor of the new method getCharacterStream. (See below.)

The following method for retrieving streams of both ASCII and Unicode characters is new in the JDBC 2.0 core API:

  • getCharacterStream - returns a java.io.Reader object that provides Unicode characters. No matter how a DBMS stores characters, the driver will return them as a stream of Unicode characters.

Note that the stream returned by getAsciiStream returns a stream of bytes in which each byte is an ASCII character. This differs from getCharacterStream, which returns a stream of two-byte Unicode characters. The method getCharacterStream can be used for both ASCII and Unicode characters because the driver will convert ASCII characters to Unicode before it returns a Reader object. If you must use getUnicodeStream because your DBMS and driver do not support the JDBC 2.0 API, note also that JDBC Unicode streams return big-endian data; that is, they expect data with the high byte first and the low byte second. This conforms to the standard endian defined by the Java programming language, which is important if a program is to be portable. Refer to The Javatm Virtual Machine Specification, by Tim Lindholm and Frank Yellin, for more detailed information about big-endian order.

The following code fragment demonstrates how to use the getAsciiStream method.

java.sql.Statement stmt = con.createStatement();
ResultSet rs = stmt.executeQuery("SELECT x FROM Table2");
// Now retrieve the column 1 results in 4 K chunks:
byte [] buff = new byte[4096];
while (rs.next()) {
    java.io.InputStream fin = rs.getAsciiStream(1);
    for (;;) {
        int size = fin.read(buff);
        if (size == -1) { // at end of stream
                    break;
        }

        // Send the newly-filled buffer to some ASCII output stream
        output.write(buff, 0, size);
    }
}

5.1.19 NULL Result Values

To determine if a given result value is JDBC NULL, one must first read the column and then use the method ResultSet.wasNull. This is true because a JDBC NULL retrieved by one of the ResultSet.getXXX methods may be converted to either null, 0, or false, depending on the type of the value.

The following list shows which values are returned by the various getXXX methods when they have retrieved a JDBC NULL.

  • null-for those getXXX methods that return objects in the Java programming language (getString, getBigDecimal, getBytes, getDate, getTime, getTime-stamp,  getAsciiStream, getCharacterStream, getUnicodeStream, getBinary-Stream, getObject, getArray, getBlob, getClob, and getRef)

  • 0 (zero)-for getByte, getShort, getInt, getLong, getFloat, and getDouble

  • false-for getBoolean

For example, if the method getInt returns 0 from a column that allows null values, an application cannot know for sure whether the value in the database was 0 or NULL until it calls the method wasNull, as shown in the following code fragment, where rs is a ResultSet object.

int n = rs.getInt(3);
boolean b = rs.wasNull();

If b is true, the value stored in the third column of the current row of rs is JDBC NULL. The method wasNull checks only the last value retrieved, so to determine whether n was NULL, wasNull had to be called before another getXXX method was invoked.

5.1.20	 Closing a ResultSet Object

Normally, nothing needs to be done to close a ResultSet object; it is automatically closed by the Statement object that generated it when that Statement object is closed, is re-executed, or is used to retrieve the next result from a sequence of multiple results. The method close is provided so that a ResultSet object can be closed explicitly, thereby immediately releasing the resources held by the ResultSet object. This could be necessary when several statements are being used and the automatic close does not occur soon enough to prevent database resource conflicts.

5.1.21	 JDBC Compliance

Drivers that are JDBC Compliant should normally support scrollable result sets, but they are not required to do so. The intent is for JDBC drivers to implement scrollable result sets using the support provided by the underlying database systems. If the DBMS does not provide support for scrollability, then the driver may omit this feature.

Making scrollability optional is not meant to encourage omitting it. It is simply meant to minimize the complexity of implementing JDBC drivers for data sources that do not support scrollability. Indeed, the recommended alternative is for a driver to implement scrollability as a layer on top of the DBMS. One way to do this is to implement a result set as a rowset. The RowSet interface, which provides methods for doing this, is part of the JDBC Standard Extension API.

[Top] [Prev] [Next]

Copyright © 1999, Sun Microsystems, Inc.   All rights
reserved.


RowSet

10.1 RowSet Overview

A RowSet object is a container for tabular data, encapsulating a set of zero or more rows that have been retrieved from a data source. In a basic implementation of the RowSet interface, the rows are retrieved from a JDBC data source, but a rowset may be customized so that its data can also be from a spreadsheet, a flat file, or any other data source with a tabular format. A RowSet object extends the ResultSet interface, which means that it can be scrollable, can be updatable, and can do anything a ResultSet object can do. The features of a RowSet object, which are summarized in this introductory section, will be explained in more detail in later sections.

A RowSet object differs from a ResultSet object in that it is a JavaBeansTM component. Thus, it has a set of JavaBeans properties and follows the JavaBeans event model. A RowSet object's properties allow it to establish its own database connection and to execute its own query in order to fill itself with data. A rowset may be disconnected, that is, function without maintaining an open connection to a data source the whole time it is in use. In addition, a rowset can be serialized, which means that it can be sent to a remote object over a network.

In general, the JDBC API can be divided into two categories, the RowSet portion and the driver portion. RowSet and its supporting interfaces are intended to be implemented using the rest of the JDBC API. In other words, a class that implements the RowSet interface is a layer of software that is said to execute "on top" of a JDBC driver. Unlike other JDBC objects, a RowSet object contains within itself the means to operate without a driver and without being connected to a data source.

The release of J2SE 5.0 introduced a third category. In addition to the RowSet API and the driver, there are five standard implementations of the RowSet interface. These implementations provide a set of interfaces that extend the basic RowSet interface plus reference implementations for each of them. There is no requirement to use these implementations, but by using them, developers can be sure that their implementations follow the JDBC API in event handling, cursor manipulation, and other operations. The standard implementations are discussed more fully in "Standard Implementations," on page 808.

The RowSet interface provides a basic set of methods common to all rowsets, which this section describes. All RowSet objects are JavaBeans components; therefore, the RowSet interface has methods for adding and removing an event listener, and it has getter amd setter methods for all of its properties. Many of these properties support setting up a connection or executing a command. A rowset uses a connection with a data source in order to execute a query and produce a result set from which it will get its data. It may also use a connection to write modified data back to the data source. In addition, the RowSet interface has methods (one for each data type) for setting the values of input parameters, if any, in a RowSet object's command string. In the JDBC RowSet Implementations specification, these basic methods, defined in the RowSet interface, are provided in the BaseRowSet abstract class, which is discussed later.

Five other interfaces and one class work together with the RowSet interface behind the scenes. The class RowSetEvent and the interface RowSetListener support the JavaBeans event model. When a RowSet object's cursor moves or its data is modified, it will invoke the RowSetListener method corresponding to the event, providing it with a RowSetEvent object that identifies itself as the source of the event. Implementations are free to write extensions that add other RowSet events if they are needed.

A component that wants to be notified of the events that occur in a RowSet object will implement the RowSetListener interface and be registered with the RowSet object. Such a component, called a listener, is typically a GUI (graphical user interface) component, such as a table or bar chart, that is displaying the RowSet object's data. Because a listener is notified every time an event occurs in the rowset, it can keep its cursor position and data consistent with that of the rowset.

The interfaces RowSetInternal, RowSetReader, and RowSetWriter support the rowset reader/writer facility. A reader, an instance of a class that implements the RowSetReader interface, reads data and inserts it into a rowset. A writer, an instance of a class that implements the RowSetWriter interface, writes modified data back to the data source from which a rowset's data was retrieved.

The RowSetInternal interface provides additional methods for a reader or writer to use to manipulate the rowset's internal state. For example, a rowset can keep track of its original values, and RowSetInternal methods allow the writer to see if the corresponding data in the data source has been changed by someone else. In addition, RowSetInternal methods make it possible to retrieve the input parameters that were set for a rowset's command string and to retrieve the connection that was passed to it, if there is one. Finally, RowSetInternal methods allow a reader to set a new RowSetMetaData object, which describes to the rowset the rows that the reader will insert into it. The name of the interface is RowSetInternal for good reason. Its methods are used internally; an application does not call these methods directly.

Rowsets may be either connected or disconnected. A connected RowSet object maintains a connection to its data source the entire time it is in use, whereas a disconnected rowset is connected to its data source only while it is reading data from the data source or writing data to it. While the rowset is disconnected, it does not need a JDBC driver or the full implementation of the JDBC API. This makes it very lean and therefore an ideal container for sending a set of data to a thin client. The client can, if it chooses, make updates to the data and send the rowset back to the application server. On the server, the disconnected RowSet object uses its reader to make a connection to the data source and write data back to it. Exactly how this is done depends on how the reader is implemented. Typically, the reader delegates making a connection and reading data to the JDBC driver.

10.1.1 The Event Model for Rowsets

The RowSet event model makes it possible for a Java object, or component, to be notified about events generated by a RowSet object. Setting up the notification mechanism involves both the component to be notified and the RowSet object itself. First, each component that wants to be notified of events must implement the RowSetListener interface. Then the RowSet object must register each component by adding it to its list of components that are to be notified of events. At this point, such a component is a listener, an instance of a class that implements the RowSetListener methods and is registered with a RowSet object.

Three kinds of events can occur in a RowSet object: its cursor can move, one of its rows can change (be inserted, deleted, or updated), or its entire contents can be changed. The RowSetListener methods cursorMoved, rowChanged, and rowSetChanged correspond to these events. When an event occurs, the rowset will create a RowSetEvent object that identifies itself as the source of the event. The appropriate RowSetListener method will be invoked on each listener, with the RowSetEvent object being passed to the method. This will inform all of the rowset's listeners about the event.

For example, if a pie chart component, pieChart, wants to display the data in the RowSet object rset, pieChart must implement the RowSetListener methods cursorMoved, rowChanged, and rowSetChanged. The implementations of these methods specify what pieChart will do in response to an event on rset. After implementing these methods, pieChart can be registered with rset. When pieChart is added as a listener to rset, it will be notified when an event occurs on rset by having the appropriate method invoked with a RowSetEvent object as its parameter. The listener pieChart can then update itself to reflect the current data and cursor position of rset. If pieChart does not need to reflect one of the events on rset, it can implement the RowSetListener method for that event so that it does nothing. For instance, if pieChart does not need to show the current cursor position in rset, it can have the method cursorMoved do nothing.

Any number of components may be listeners for a given RowSet object. If, for example, the bar graph component barGraph is also displaying the data in rset, it can become a listener by implementing the RowSetListener methods and then being registered with rset. The following lines of code register the two components pieChart and barGraph as listeners with rset.

    rset.addRowSetListener(pieChart);
    rset.addRowSetListener(barGraph);
Removing a listener is done in a similar fashion with the method RowSet.removeListener.

    rset.removeRowSetListener(pieChart);
    rset.removeRowSetListener(barGraph);
The code for setting up the listeners for a rowset is often generated by a tool, which means that an applications programmer only needs to specify a rowset and the components that are to be notified when an event occurs on that rowset. After the listeners are set up, the processing of an event is done largely behind the scenes. For example, if an application updates a row in rset, rset will internally create a RowSetEvent object and pass it to the rowChanged methods implemented by pieChart and barGraph. The listeners will know where the event occurred because the RowSetEvent object passed to rowChanged is initialized with rset, the RowSet object that is the source of the event. The components pieChart and barGraph will update their displays of the row according to their own implementations of the RowSetListener.rowChanged method.

In the following code fragment, pieChart and barGraph are registered as listeners with the RowSet object rset. After rset fills itself with new data by calling the method execute, event notification takes place behind the scenes. (The method execute will be explained in detail in the section "Executing a Command ," on page 805.) As the first step in the event notification process, the RowSetEvent object rsetEvent is created and initialized with rset. Next the pieChart and barGraph versions of the method rowSetChanged are called with rsetEvent as their arguments. This tells pieChart and barGraph that all the data in rset has changed, and each listener will carry out its own implementation of the method rowSetChanged.

rset.addRowSetListener(pieChart);
rset.addRowSetListener(barGraph);
. . .
rset.execute();

// The following methods will be invoked behind the scenes:
RowSetEvent rsetEvent = new RowSetEvent(this);
pieChart.rowSetChanged(rsetEvent);
barGraph.rowSetChanged(rsetEvent);

10.1.2 Properties for a Rowset

The RowSet interface provides a set of JavaBeans properties so that a RowSet instance can be configured to connect to a data source and retrieve a set of rows. Some properties may not be required, depending on particular implementations. For example, either a URL or a data source name is required for establishing a connection, so if one property is set, the other one is optional. If both are set, the one set more recently is used. If data for a rowset is being retrieved from a non-SQL data source that does not support commands, such as a spreadsheet, the command property does not need to be set. Setting some properties is optional if the default is already the desired property. For example, escape processing is on by default, so an application does not need to set escape processing unless it wants to disable it. (Escape processing is explained in "SQL Escape Syntax in Statements," on page 958.)

The following list gives the getter and setter methods defined on the RowSet interface for retrieving and setting a RowSet object's properties. The two exceptions are the methods getConcurrency and getType, which are inherited from the ResultSet interface rather than being defined in the RowSet interface.

getCommand | setCommand
ResultSet.getConcurrency | setConcurrency
getDataSourceName | setDataSourceName
getEscapeProcessing | setEscapeProcessing
getMaxFieldSize | setMaxFieldSize
getMaxRows | setMaxRows
getPassword | setPassword
getQueryTimeout | setQueryTimeout
getTransactionIsolation | setTransactionIsolation
ResultSet.getType | setType
getTypeMap | setTypeMap
getUrl | setUrl
getUsername | setUsername

In addition, the standard JDBC RowSet implementations may have various properties that are specific to them.

The following code fragment, in which rset is a RowSet object, sets properties that are typically required for establishing a connection with a data source using a DataSource object.

    rset.setDataSourceName("jdbc/logicalDataSourceName");
    rset.setUsername("cervantes");
    rset.setPassword("secret");
Note that jdbc/logicalDataSourceName is the name that has been registered with a JNDI (Java Naming and Directory Interface) naming service. When an application gives the naming service the logical name, it will return the DataSource object that has been bound to the logical name. "Using JNDI," on page 568, explains using DataSource objects and the JNDI API. Using a DataSource object instead of hardcoding connection information makes code more portable and makes maintaining it much easier. If the host machine or port number of a data source changes, for example, only the properties of the DataSource object entered in the JNDI naming service need to be updated, not every application that gets a connection to that data source.

A RowSet object also has methods for setting properties that affect command execution. For example, as a sampling of these methods, the following code fragment sets twenty seconds as the longest a driver will wait for a statement to execute, sets 1024 as the largest number of rows rset may contain, and specifies that rset will be allowed to read only data from committed transactions.

    rset.setQueryTimeout(20);
    rset.setMaxRows(1024);
    rset.setTransactionIsolation(Connection.TRANSACTION_READ_COMMITTED);
The type and concurrency may also be set for a RowSet object, as shown in the following lines of code.

    rset.setType(ResultSet.TYPE_SCROLL_INSENSITIVE);
    rset.setConcurrency(ResultSet.CONCUR_UPDATABLE);
The first line sets rset to be scrollable but not sensitive to the updates made while it is open. A RowSet object that maintains a continuously open connection with a data source may be TYPE_SCROLL_SENSITIVE, but one that does not is incapable of being sensitive to changes made by other objects or transactions. The second line of code sets rset to be updatable, meaning that it can modify its data.

Note that a RowSet object may be scrollable even if it uses a driver that does not support scrollable result sets. In fact, a rowset may often be used in place of a regular result set as a way of getting a scrollable result set. This is discussed in more detail in the section "Traversing a RowSet Object," on page 804.

An application fills a RowSet instance with data by executing the RowSet object's command string. This string must be a query that, when executed, will produce a result set from which the RowSet object will get its data. The method setCommand sets the String object supplied to it as the command that will be executed when the method execute is invoked. For example, the following line of code sets the command string to a query that selects the name and salary from every row in the table EMPLOYEES.

    rset.setCommand("SELECT NAME, SALARY FROM EMPLOYEES");
With the preceding command string set, after rset invokes its execute method, it will contain exactly the same data as the result set that the query produces (one row for each row in the table EMPLOYEES, with each row containing a name and a salary).

10.1.3 Setting Parameters for the Command String

The example in the previous section uses a command that has no placeholders for parameters, but the command property may also be set with a query that takes input parameters. To make this possible, the internal representation of the command string is a PreparedSatement object. Note that the parameters must be input parameters and not output parameters.

A newly created RowSet object exists but has no data until it is populated with a call to the method execute or populate. In order to use the method execute, the necessary properties must be set, and values for any placeholder parameters must be set. Parameter values can be set at run time, which, for example, allows an application to be interactive and accept user input.

The RowSet interface, like the PreparedStatement interface, has setter methods for setting the value of input parameters. There is a setter method for each data type, including the SQL99 data types. The following code fragment sets the command string and then sets its two input parameters with values. Assuming that the column DEPT stores values of type VARCHAR, the method setString is used to set both parameters because that is the appropriate method for setting VARCHAR values.

    rset.setCommand(
      "SELECT NAME, SALARY FROM EMPLOYEES WHERE DEPT = ? OR DEPT = ?");
    rset.setString(1, "SALES");
    rset.setString(2, "MARKETING");
After this command is executed, rset will contain the names and salaries of the employees in the sales and marketing departments.

Any parameters in a RowSet object's command string must be set with values before the command is executed. When a rowset is disconnected, the parameters that have been set are used by the reader's readData method, which is invoked internally by the method execute. A rowset stores these parameter values in an internal hashtable, and the readData method retrieves them with a call to the rowset's RowSetInternal.getParams method.

10.1.4 Traversing a RowSet Object

The javax.sql.RowSet interface extends the java.sql.ResultSet interface, so moving the cursor in a scrollable RowSet object is exactly the same as moving a cursor in a scrollable ResultSet object. A RowSet object inherits all of the ResultSet methods, so it is really a result set with added features that allow it to function as a JavaBeans component. Most components that use instances of RowSet are likely to treat them as ResultSet objects.

Even though the methods for moving a RowSet object's cursor are identical to those of a ResultSet object from the user's point of view, a RowSet object's implementation of these methods is different. A RowSet object needs to let the listeners registered with it know about each movement of its cursor. Consequently, the cursor movement methods for a RowSet object are implemented to trigger the internal event notification process. For example, when the method next is called, its implementation will create a RowSetEvent object and call each listener's cursorMoved method, supplying the RowSetEvent object as the parameter. The listener uses the RowSetEvent object to find out in which RowSet object the cursor has moved and then invokes its implementation of the method cursorMoved. The implementation could do nothing, or it could, for example, call the method ResultSet.getRow to get the cursor's current position and update the listener's display of that row's data.

To demonstrate that cursor movements are the same in RowSet and ResultSet, the following code fragment iterates forward through the RowSet object rset and prints out the two values retrieved from each row.

    rset.beforeFirst();
    while (rset.next()) {
      System.out.println(rset.getString(1) + " " + rset.getFloat(2));
    }
Other cursor movements are also identical to those in the ResultSet interface. .

10.1.5 Executing a Command

The RowSet interface provides the method execute, which is invoked to fill a RowSet object with data. There can be many variations in the implementation of this method, and subtypes may define additional methods for populating themselves with data. The execute method makes use of rowset properties and will throw an SQLException if the necessary properties have not been set. Standard properties have been defined; however, additional properties depend on each particular RowSet implementation, so application writers should check the documentation for the implementation they are using.

A disconnected rowset needs a reader (an object that implements the RowSetReader interface) and a writer (an object that implements the RowSetWriter interface) . In the JDBC RowSet Implementations, a reader and writer are encapsulated in the the SyncProvider class, which is part of the javax.sql.rowset.spi package. This package, known as the SPI (Service Provider Interface), is explained later. The SPI makes it much easier to implement and deploy a reader and writer. The two reference implementations, RIOptimisticProvider and RIXmlProvider, provide immediate implementations.

A disconnected rowset must also implement the RowSetInternal interface to make additional access to its internal state available to the reader and writer. With its reader/writer framework in place, a rowset's execute method is able to delegate tasks to its reader and writer components.

With the addition of the standard RowSet implementations, developers will find it much easier to implement the reader/writer facilities. They can leverage the reader/writer facilities that are already included in these standard implementations by simply incorporating them into their own implementations.

In a typical implementation, a disconnected rowset's execute method will invoke the reader's readData method to accomplish the job of reading new data into the rowset. Generally, after clearing the rowset of its current contents, the readData method will get the properties it needs and establish a connection with the data source. If there are any parameters to be set, readData retrieves them from the rowset and sets them appropriately in the rowset's command string. Then the readData method executes the command string to produce a result set. Finally, readData populates the rowset with the data from the result set and sets that data as the original values.

The reader's readData method may also be implemented to set the rowset's metadata. One of the many possible implementations is to have the readData method create a RowSetMetaData object and set it with information about the columns in the data source that is about to be read. The readData method next sets the new RowSetMetaData object to be the one associated with the rowset. The rowset can then use the RowSetMetaData object to see the format for the data that will be read into it.

When the rowset's command string is executed, all of a rowset's listeners need to be notified so that they can take the appropriate action. The execute method will invoke the rowSetChanged method on each listener, supplying rowSetChanged with a newly created RowSetEvent object that identifies the RowSet object in which the event occurred. As is true of most of what the method execute does, the notification of listeners is invisible to the application programmer using a rowset.

One more task for the execute method is that of setting the "original" values maintained by the rowset. These are the values, returned by the method RowSetInternal.getOriginal, that existed immediately before the most recent update. A RowSet object's original values may be the values it got from the data source, but this is not necessarily true. The first time a RowSet object's data is synchronized with its data source, its original values will be the same as the values it originally got from the data source. However, if some of a RowSet object's values are modified a second time, the original values will be the values that existed after the first modifications, not those from the data source. The point of keeping track of a RowSet object's original values is to be able to check whether the corresponding values in the data source have been changed.

If a SyncProvider object is implemented to check for conflicts, it compares the original values with the ones in the data source. If the rowset's original values (pre-modification values) and the underlying data source's values are not the same, there will be a conflict if the RowSet object's modified values are written to the data source. If the values are the same, however, there is no conflict. Depending on the synchronization model being used, a SyncProvider object may or may not write the new rowset values to the data source when there is a conflict.

If the SyncProvider implementation does not write new values to the underlying data source, the execute method will reset the original values back to the values currently in the rowset. Then the next time execute is called, which changes all of the values in the rowset, the SyncProvider object can retrieve these values to compare with those in the underlying data source to see if there is a conflict.

In summary, when an application invokes the execute method, many operations take place behind the scenes. When the rowset is disconnected, the following take place: the contents of the rowset are replaced with new data, any listeners using the rowset's data are notified, the rowset's metadata is updated, and the rowset's original values are set to the current data values. For a connected rowset, the execute method generally just populates the rowset with new data and notifies the listeners of the event. There is no possibility of a conflict because changes made to a connected RowSet object are also made to the data source.

10.1.6 Using a RowSet Object's Metadata

A RowSet object maintains a set of metadata about the columns it contains. Being derived from ResultSet, a RowSet object's metadata can be retrieved with ResultSetMetaData methods in the same way that a ResultSet object's metadata can. For instance, the following code fragment creates a RowSetMetaData object for the RowSet object rset and finds out how many columns rset contains. Note that the method getMetaData is a ResultSet method that returns a ResultSetMetaData object, so it must be cast to a RowSetMetaData object before it can be assigned to rsetmd.

    RowSetMetaData rsetmd = (RowSetMetaData)rset.getMetaData();
    int columnCount = rsetmd.getColumnCount();
The variable rsetmd contains information about the columns in the RowSet rset. Any of the RowSetMetaData methods can be invoked on rsetmd to retrieve the information that rsetmd contains.

The interface RowSetMetaData defines setter methods corresponding to each of the getter methods defined in ResultSetMetaData (except that there are no methods for setting the class name for a column or for setting whether the column is read-only, possibly writable, or definitely writable). The RowSetMetaData setter methods are called by a reader after it has read new data into a rowset and created a new RowSetMetaData object for describing the RowSet object's columns. The following code shows what a reader might do behind the scenes. It creates the new RowSetMetaData object rowsetmd for the RowSet object rowset, sets the information for the columns, and finally calls the RowSetInternal method setMetaData to set rowsetmd as the metadata for rowset.

    rowset.execute();
    // ... as part of its implementation, execute calls readData
    reader.readData((RowSetInternal)this);

    // ... as part of the implementation of readData, the reader for
    // the rowset would do something like the following to update the
    // metadata for the rowset
    RowSetMetaData rowsetmd = new ...; // create an instance of a class
    // that implements RowSetMetaData
    rowsetmd.setColumnCount(3);
    rowsetmd.setColumnType(1, Types.INTEGER);
    rowsetmd.setColumnType(2, Types.VARCHAR);
    rowsetmd.setColumnType(3, Types.BLOB);
    // ... set other column information
    rowset.setMetaData(rowsetmd);

10.2 Standard Implementations

The Java platform includes five standard implementations of the RowSet interface with the release of J2SE 5.0. These implementations are being provided as an aid for those who want to write their own implementations. The RowSet interface may be implemented in any number of ways to serve any number of different purposes, and anyone may implement it. The expectation is, however, that RowSet implementations will be written mostly by driver vendors, who may include their implementations as part of their JDBC products. Implementors are free to use the reference implementations just as they are, to build on them, or to write their implementations completely on their own.

The standard implementations consist of two parts, the interfaces and the reference implementations. The interfaces are in the javax.sql.rowset package; the implementations are in the com.sun.rowset package. They were developed with input from experts in the database field through the Java Community Process as JSR 114. The goal was to standardize key rowset functionality so that developers can leverage it in their own implementations. The standard RowSet implementations are:

  • JdbcRowSet

  • CachedRowSet

  • WebRowSet

  • FilteredRowSet

  • JoinRowSet

10.2.1 Implementation Basics

All of the standard RowSet implementations extend the abstract class BaseRowSet and implement the appropriate interface (JdbcRowSet, CachedRowSet, WebRowSet, FilteredRowSet, or JoinRowSet). Note that the BaseRowSet class provides a base implementation of the common functionality for all RowSet objects, which developers may choose to use or not. The BaseRowSet class includes the following:

  • Properties--fields for storing property values and methods for getting and setting property values

  • Event notification mechanism--methods for adding and deleting listeners and for notifying listeners of changes

  • Setter methods--a complete set of methods for setting the placeholder parameters in a RowSet object's command property

  • Default values--all RowSet implementations have the following default values:

    • Is scrollable and does not show changes made by others

    • Is updatable

    • Does not show rows that have been deleted

    • Has no time limit for how long a driver may take to execute the RowSet object's command

    • Has no limit for the number of bytes that columns of type BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, or LONGVARCHAR may contain

    • Does not see uncommitted data (make "dirty" reads)

    • Has escape processing is turned on

    • Has its connection's type map is set to null

    • Has an empty Hashtable object for storing the values set for the placeholder parameters in the RowSet object's command

As stated previously, RowSet objects may be connected or disconnected. The RowSet implementations fall into the following categories:

  • Connected (maintains a connection to the data source using a JDBC driver)

    • JdbcRowSet

  • Disconnected (not connected to the data source except when reading data from it or writing data to it)

    • CachedRowSet

    • JoinRowSet

    • FilteredRowSet

    • WebRowSet

The CachedRowSet interface provides the methods that a disconnected RowSet object needs. In the standard implementations, a disconnected RowSet extends the BaseRowSet class and implements the CachedRowSet interface. In addition, the JoinRowSet implementation implements the JoinRowSet interface, the FilteredRowSet implementation implements the FilteredRowSet interface, and the WebRowSet implementation implements the WebRowSet interface.

10.2.2 Overview of the JdbcRowSet Implementation

A JdbcRowSet object (an instance of the standard implementation of the JdbcRowSet interface) is, like all rowsets, a container for a set of rows. The source of these rows is always a ResultSet object because a JdbcRowSet object is a connected RowSet object. In other words, it always maintains a connection with a DBMS via a JDBC driver. Note that other implementations may use any tabular data, such as a flat file or a spreadsheet, as their source of data if their reader and writer facilities are appropriately implemented.

A JdbcRowSet object has many uses. Probably the most common use is to make a ResultSet object scrollable and thereby make better use of legacy drivers that do not support scrolling. A JdbcRowSet object's rows of data (and those in any RowSet object) are identical to those in the ResultSet object that is the result of executing the rowset's command. Therefore, if the rowset is scrollable, it is the equivalent of having a scrollable ResultSet object even if the ResultSet object itself is not scrollable.

Another common use is to make the driver or a ResultSet object a JavaBeans component. Like all RowSet objects, a JdbcRowSet object is a JavaBeans component. By being continuously connected to a driver, it serves as a wrapper for the driver, which effectively makes the driver a JavaBeans component. This means that a driver presented as a JdbcRowSet object can be one of the Beans that a tool makes available for composing an application. Being continuously connected also means that a JdbcRowSet object is able to serve as a wrapper for its ResultSet object. It can take calls invoked on it and, in turn, call them on its ResultSet object. As a consequence, the ResultSet object can be, for example, a component in a GUI application that uses Swing technology.

The following code fragment illustrates creating a JdbcRowSet object, setting its properties, and executing the command string in its command property. The JdbcRowSet implementation provides a default constructor, but being a JavaBeans component, a JdbcRowSet implementation will probably most often be created by a visual JavaBeans development tool.

    JdbcRowSet jrs = new JdbcRowSetImpl();
    jrs.setCommand("SELECT * FROM TITLES);
    jrs.setURL("jdbc:myDriver:myAttribute");
    jrs.setUsername("cervantes");
    jrs.setPassword("sancho");
    jrs.execute();
At this point, jrs contains all of the data in the table TITLES because the ResultSet object generated by jrs's command contains all of the data in the table TITLES.

From this point on, the code can simply use ResultSet methods because it is effectively operating on a ResultSet object. It can navigate the rows in jrs, retrieve column values, update column values, insert new rows, and so on. For example, the next two lines of code go to the second row and retrieve the value in the first column using ResultSet methods.

    jrs.absolute(2);
    String title = jrs.getString(1);

10.2.3 Overview of the CachedRowSet Implementation

The standard implementation of the CachedRowSet interface (CachedRowSetImpl in the package com.sun.rowset) provides a container for a set of rows that is being cached in memory outside of a data source. It is disconnected, serializable, updatable, and scrollable. Because a CachedRowSet object caches its own data, it does not need to maintain an open connection with a data source and is disconnected from its data source except when it is reading or writing data. But because it stores its rows in memory, a CachedRowSet object is not appropriate for storing extremely large data sets. However, to accommodate larger amounts of data, a CachedRowSet object may page in data, reading only a specified number of rows at a time.

A CachedRowSet object can populate itself with data from a tabular data source, and because it is updatable, it can also modify its data. As with all RowSet objects, in addition to getting data in, it can get data out, propagating its modifications back to the underlying data source.

10.2.4 Uses for a CachedRowSet Object

Being disconnected and serializable, a CachedRowSet object is especially well suited for use with a thin client. Not being continually connected to its data source, it does not require the presence of a JDBC driver and can therefore be much more lightweight than a ResultSet object or a connected RowSet object.

One of the major uses for a CachedRowSet instance is to pass tabular data between different components of a distributed application, such as EnterpriseJavaBeans TM (EJBTM) components running in an application server. The server can use the JDBC API to retrieve a set of rows from a database and then use a CachedRowSet object to send the data over the network to, for example, a thin client running in a web browser.

Another use for a CachedRowSet object is to provide scrolling and updating capabilities to a ResultSet object that does not itself have this functionality. For example, as with a JdbcRowSet object, an application can create a CachedRowSet object initialized with the data from a ResultSet object and then operate on the rowset instead of the result set. With the rowset set to be scrollable and updatable, the application can move the cursor, make updates, and then propagate the updates back to the data source.

The following code fragment populates the CachedRowSet object crset with the data from the ResultSet object rs.

    ResultSet rs = stmt.executeQuery("SELECT * FROM AUTHORS");
    CachedRowSet crset = new CachedRowSetImpl();
    crset.populate(rs);
Once the rowset is populated, an application can pass it across the network to be manipulated by distributed components, or it can operate on crset instead of rs to gain scrollability or updatability.

The CachedRowSet implementation uses the base API from the BaseRowSet abstract class and the CachedRowSet interface, which adds methods for the additional functionality it needs. For example, it needs a way to connect to a data source and read data from it. If a CachedRowSet object's data is modified while it is disconnected, it also needs a way to connect to the data source and write the new data back to it. The reader and writer facilities, based on the RowSetReader and RowSetWriter interfaces and encapsulated in a SyncProvider implementation, provide these capabilities.

A writer implementation supplies a mechanism for updating the data source with any changes it has made while it was disconnected, thus making the modified data persistent. This can get complicated if there is a conflict, that is, if another user has already modified the same data in the data source. The SyncProvider class includes mechanisms that afford varying degrees of control over how accessible data in the database is to others, and consequently, it has some control over the number of conflicts that may occur. Even more important, a SyncProvider implementation determines the level of care to be taken in synchronization.

The JDBC RowSet Implementations specification includes two different reference implementations for synchronization using two different levels of concurrency. The RIXmlProvider does not check for conflicts and simply writes its modified data to the data source. The writer defined in the RIOptimisticProvider implementation checks for conflicts, and if a conflict exists, allows an application to use a SyncResolver object to decide whether or not to write modified data on a case by case basis. Third parties can write SyncProvider implementations offering different degrees of synchronization, and a disconnected rowset may use the one that best fits its needs. The SyncProvider class and the SyncResolver interface are covered in the section "Using the javax.sql.rowset.spi Package".

The implementation of the CachedRowSet interface can be used as a basis for implementing other disconnected rowsets. For example, the implementations of the WebRowSet, FilteredRowSet, and JoinRowSet interfaces are all based on the implementation of the CachedRowSet interface. Therefore, the following discussion of the CachedRowSet interface goes into some detail about the methods it defines and what they do. The sections on the other disconnected rowset implementations discuss the capabilities they have beyond those of the CachedRowSet implementation.

10.2.5 Creating a CachedRowSet Object

Any RowSet object is a JavaBeans component, so developers will often create them using a visual JavaBeans development tool while they are assembling an application. It is also possible for an application to create an instance at run time, using a public constructor provided by a class that implements the RowSet interface. For example, the standard implementation of the CachedRowSet interface defines a public default constructor, so an instance of CachedRowSet can be created with the following line of code.

    CachedRowSet crset = new CachedRowSetImpl();
The newly created crset is a container for a set of data, and it will have the default properties of a BaseRowSet object. Because its implementation uses the BaseRowSet class, crset can use BaseRowSet methods to set new values for any of these properties or to set values for other properties as appropriate. For example, in the following code fragment, the first line sets the command string that crset will use to get its data, and the second line turns escape processing off.

    crset.setCommand("SELECT * FROM EMPLOYEES");
    crset.setEscapeProcessing(false);

10.2.6 Setting a SyncProvider Object

Every CachedRowSet object must obtain a SyncProvider object, which implements a reader and a writer, in order to get data from a data source and to write its modifications of data back to the data source. The SyncFactory creates an instance of a SyncProvider object that is registered with it when a RowSet object requests it. Because the constructor that created crset was not given any parameters, the SyncFactory provided an instance of the default, which is RIOptimisticProvider (one of the two implementations of the SyncProvider class provided with the standard RowSet implementations).

If the fully qualified class name of a SyncProvider implementation is supplied to the constructor, the SyncFactory will initialize the RowSet object with an instance of that SyncProvider implementation if it has been registered with the SyncFactory. The following line of code creates a CachedRowSet object whose synchronization provider is an instance of the given SyncProvider implementation.

    CachedRowSet crset = new CachedRowSetImpl("com.supersoftware.providers.HighAvailabilityProvider");
After its creation, a RowSet object can be set with another registered SyncProvider implementation, including third-party implementations or the other standard provider implementation, RIXmlProvider, which reads and writes a RowSet object in XML. The way to set a SyncProvider object is to use the CachedRowSet method setSyncProvider, which resets the current SyncProvider object to the one specified. For example, if the current provider for crset is an RIOptimisticProvider object, the following line of code changes the provider to a com.supersoftware.providers.HighAvailabilityProvider object.

    crset.setSyncProvider("com.supersoftware.providers.HighAvailabilityProvider");

10.2.7 Populating a CachedRowSet Object

Although a CachedRowSet object can contain data that was retrieved from a data source such as a file or spreadsheet, it will probably get its data primarily from a ResultSet object via a JDBC driver. The RowSet interface provides the method execute, which takes no parameters, and the CachedRowSet interface adds a second version of the method execute that takes a Connection object as a parameter. Both methods populate a CachedRowSet object with data from the ResultSet object that is created when the CachedRowSet object's command is executed. The CachedRowSet interface also adds the method populate, which takes a ResultSet object as a parameter.

The version of execute inherited from the RowSet interface has to establish a connection behind the scenes before it can execute the rowset's command string. The version of execute defined in the CachedRowSet interface is passed a Connection object, so it does not need to establish its own connection. The method populate does not need to establish its own connection or execute a query because it is passed the ResultSet object from which it will get its data. Thus, the method populate does not require that the properties affecting a connection be set before it is called, nor does it require that the command string be set. The following code fragment shows how the method populate might be used.

    ResultSet rs = stmt.executeQuery("SELECT NAME, SALARY FROM EMPLOYEES");

    // The code that generates rs
    . . .
    CachedRowSet crset = new CachedRowSetImpl();
    crset.populate(rs);
The new CachedRowSet object crset contains the same data that the ResultSet object rs contains.

The implementation details of the method populate may vary, of course, but because it is passed a ResultSet object, populate is in some ways quite different from the method execute. As stated previously, the populate method does not need to establish a connection. Nor does it use a reader because it can get its data directly from the given result set. By using ResultSetMetaData methods, it can get information about the format of the result set so that it is able to use the appropriate getter methods in the ResultSet interface to retrieve the ResultSet object's data.

The methods execute and populate do have some similarities. The main similarity is that both methods change the contents of the entire rowset. As a consequence, they both cause the following: notification of listeners, setting the original values equal to the current rowset values, and updating the rowset's metadata information.

The following code fragments give examples of using the two versions of the method execute. Both versions execute a query, so both require that a command string be set. When no connection has been passed to the method execute, the appropriate connection properties must be set before the command can be called. The execute method will call the rowset's reader, which will use the necessary properties to establish a connection with the data source. Once the connection is established, the reader can call the method executeQuery to execute the rowset's command string and get a result set from which to retrieve data.

    CachedRowSet crset1 = new CachedRowSetImpl();
    crset1.setCommand("SELECT NAME, SALARY FROM EMPLOYEES");
    crset1.setDataSourceName("jdbc/myDataSource");
    crset1.setUsername("paz");
    crset1.setPassword("p38c3");
    crset1.setTransactionIsolation(Connection.TRANSACTION_READ_COMMITTED);

    crset1.execute();
In the next example, the Connection object con is passed to the method execute. The CachedRowSet object crset2 will use con for executing the command string instead of having to establish a new connection behind the scenes.

    CachedRowSet crset2 = new CachedRowSetImpl();
    crset2.setCommand("SELECT NAME, SALARY FROM EMPLOYEES");
    crset2.execute(con);
Both crset1 and crset2 were connected to the data source while the command string was executed and while the resulting data was read and inserted into it. After the method execute returns, both will close their connections to their data sources.

10.2.8 Accessing Data

A CachedRowSet object, like all rowsets, uses the getter methods inherited from the ResultSet interface to access its data. Because a CachedRowSet object is implemented so that it is scrollable by default, it can also use the ResultSet methods for moving the cursor. For example, the following code fragment moves the cursor to the last row of the CachedRowSet object crset and then retrieves the String value in the first column of that row.

    crset.last();
    String note = crset.getString(1);
A CachedRowSet object is implemented such that it always has type ResultSet.TYPE_SCROLL_INSENSITIVE, so in addition to being scrollable, a CachedRowSet object is always insensitive to changes made by others. This makes sense because a CachedRowSet object is mostly disconnected, and while it is disconnected, it has no way of seeing the changes that others might make to the underlying data source from which it got its data.

10.2.9 Modifying Data

As shown in the previous section, a CachedRowSet object can have its entire contents changed with its execute and populate methods. It can have one row at a time modified with the ResultSet updater methods and the methods insertRow and deleteRow . Note that the JDBC RowSet Implementations specification does not say where an inserted row should go. In the reference implementations, inserted rows are put immediately after the current row, but there is great flexibility for deciding where rows are inserted.

An updater method modifies the value in the specified column in the current row, assigning it the value passed to it (usually as the second parameter). An updater method changes only the value in the rowset, which is cached in memory; it does not affect the value in the underlying data source. Also, it does not affect the value that the rowset keeps track of as the original value.

When an application has made all its updates to a row, it calls the method updateRow. In a CachedRowSet implementation, this method signals that the updates for the current row are complete, but, like the updater methods, it does not affect the values in the underlying data source. The updateRow method likewise does not affect the values stored as original values. After calling the updateRow method on all the rows being updated, an application needs to call the CachedRowSet method acceptChanges. This method invokes a writer component internally to propagate changes to the data source backing the rowset, and for each column value that was changed, it sets the original value to the current value.

Once it has called updateRow, an application may no longer call the method cancelRowUpdates to undo updates to the current row. If it has not yet invoked the method acceptChanges, however, it can call the method restoreOriginal, which undoes the updates to all rows by replacing the updated values in the rowset with the original values. The restoreOriginal method does not need to interact with the underlying data source.

The following code fragment updates the first two rows in the CachedRowSet object crset.

    crset.execute();
    // crset is initialized with its original and current values

    crset.first();
    crset.updateString(1, "Jane_Austen");
    crset.updateFloat(2, 150000f);
    crset.updateRow();
    // the current value of the first row has been updated

    crset.relative(1);
    crset.updateString(1, "Toni_Morrison");
    crset.updateFloat(2, 120000f);
    crset.updateRow();
    // the current value of the second row has been updated

    crset.acceptChanges();
    // the original value has been set to the current value and the
    // database has been updated

10.2.10 Customizing Readers and Writers

Disconnected RowSet implementations can take advantage of the ability to customize the retrieval and updating of data that the rowset framework provides. This applies to rowsets that are disconnected, such as CachedRowSet objects, because they require the services of a reader and a writer, which are encapsulated by a SyncProvider object.

The CachedRowSet interface defines the method setSyncProvider, which provides a CachedRowSet object with its implementation of a reader and writer. It also defines a getSyncProvider method for retrieving a rowset's SyncProvider object. A rowset's reader and writer operate completely behind the scenes, performing any number of tasks that can be customized to provide additional functionality.

The RowSetReader interface has one public method, readData, which can be customized in various ways. For example, a reader can be implemented so that it reads data straight from a file or from some other non-SQL data source rather than from a database using a JDBC driver. Such a reader might use the method RowSet.insertRow to insert new rows into the rowset. When invoked by a reader, this method could also be implemented so that it updates the original values stored by the rowset.

The RowSetWriter interface has one public method, writeData, which writes data that has been modified back to the underlying data source. This method can likewise be customized in a variety of ways. The writer establishes a connection with the data source, just as the reader does, and depending on how it is implemented, may or may not check for conflicts. The RowSetInternal methods getOriginal and getOriginalRow supply the values that existed before the current modifications, so the writer can compare them with the values read from the data source to see if the data source has been modified. How the writer decides whether or not to write data when there is a conflict again depends on how it is implemented.

A CachedRowSet object that has been configured with a custom reader and/or writer can be made available as a normal JavaBeans component. This means that developers writing applications do not have to worry about customizing readers and writers and can concentrate on the more important aspects of using rowsets effectively.

10.2.11 Other Methods

The CachedRowSet interface defines a number of other methods. For example, it defines two versions of the method toCollection. Sometimes it is more convenient to work with a rowset's data as elements in a collection, which these methods make possible by converting a rowset's data into a Java collection. Other CachedRowSet methods create a copy of the rowset. CachedRowSet.clone and CachedRowSet.createCopy create an exact copy of the rowset that is independent from the original. By contrast, the CachedRowSet.createShared method creates a rowset that shares its state with the original rowset. In other words, both the new and the original rowset share the same physical, in-memory copy of their original and current values. If an updater method is called on one shared rowset, the update affects the other rowset as well. In effect, the createShared method creates multiple cursors over a single set of rows.

10.2.12 Using the javax.sql.rowset.spi Package

The package javax.sql.rowset.spi provides the API that a developer needs to use to implement a synchronization provider. It includes the following classes and interfaces:

  • SyncFactory

  • SyncFactoryException

  • SyncProvider

  • SyncProviderException

  • SyncResolver

  • XmlReader

  • XmlWriter

  • TransactionalWriter

The following two interfaces are inherited from the package javax.sql:

  • RowSetReader

  • RowSetWriter

A CachedRowSet object or other disconnected RowSet object gets its SyncProvider object from a SyncFactory object. Being a static class, there is only one instance of SyncFactory, which means that there is only one source from which a disconnected RowSet object can obtain its SyncProvider object. A vendor can register its implementation of the SyncProvider abstract class with the SyncFactory, which then makes it available for a RowSet object to plug in. The following line of code shows one way to register a SyncProvider implementation with the SyncFactory.

    SyncFactory.registerProvider("com.supersoftware.providers.HAProvider");
Note that the argument supplied to registerProvider is the fully qualified class name of the SyncProvider implementation.

A SyncProvider implementation may also be registered by adding it to the system properties. This can be done at the command line at execution time as follows:

    -Drowset.provider.classname=com.supersoftware.providers.HAProvider
Another way to register a SyncProvider implementation is to add the fully qualified class name, the vendor, and the version number to the standard properties file. The reference implementation comes with a properties file that already has entries for the two reference implementation synchronization providers, RIOptimisticProvider and RIXmlProvider. The fourth way to register a SyncProvider implementation is to register it on a JNDI context and then register the JNDI context with the SyncFactory by supplying the fully qualified provider name to the method SyncFactory.registerJNDIContext.

When a RowSet object requests a particular SyncProvider implementation, the SyncFactory will search for it and create an instance of it and return it to the RowSet object. For example, in the following line of code, the CachedRowSet object crset requests the com.supersoftware.providers.HAProvider.

    crset.setSyncProvider("com.supersoftware.providers.HAProvider");
If the requested provider has not been registered in any of the possible ways, the SyncFactory throws a SyncFactoryException object.

A CachedRowSet object or any of its subclasses can discover which SyncProvider implementations have been registered with the SyncFactory and are thus available for its use by calling the following line of code.

    java.util.Enumeration providers = SyncFactory.getRegisteredProviders();
The core components of a SyncProvider object are the reader and writer that it implements. The implementation of the reader determines from what kind of data source (relational database, flat file, spreadsheet, and so on) it can read data and also how it reads that data. The implementation of the writer determines what level of concurrency it uses, whether it checks for conflicts, and how it handles any conflicts it encounters. The reader in the RIOptimisticProvider, an implementation of the RowSetReader interface, reads data from a relational database. The writer, an implementation of the RowSetWriter interface, checks for conflicts and does not write data to the data source if there is a conflict. The reader and writer implemented in the RIXmlProvider read and write a rowset as an XML document. For this reason, it is primarily used by a WebRowSet object. The writer does not check for conflicts and simply writes all of a RowSet object's modifications to the data source.

The TransactionalWriter interface allows a CachedRowSet object that is participating in a global or local transaction to get fine-grained control of the transactional boundaries. To get this functionality, a CachedRowSet object needs to use a SyncProvider object that implements the TransactionalWriter interface.

The reference implementation provides a means by which an application can choose to resolve conflicts on a case by case basis. After the writer finds all the conflicts, it throws a SyncProviderException object. An application can catch that exception and use it to create a SyncResolver object, a specialized kind of RowSet object. A SyncResolver object mirrors the RowSet object experiencing the conflicts, having the same number of rows and columns; however, it contains only the data that is in conflict.

The SyncResolver object retrieves each conflict value in a row, comparing the value in the data source with the value in the RowSet object. After a decision is made as to which value should persist for each conflict in the row, the SyncResolver object sets those values with the method setResolvedValue. The SyncResolver object then goes to the next conflict and repeats the process until there are no more conflicts.

10.2.13 CachedRowSet Summary

In summary, an implementation of the CachedRowSet interface, being disconnected and able to operate without a driver, is designed to work especially well with a thin client for passing data in a distributed application or for making a result set scrollable and updatable. Many other RowSet implementations can be designed for other purposes.

10.2.14 WebRowSet Implementation

The WebRowSet interface extends the CachedRowSet interface and therefore has all of the same capabilities. What it adds is the ability to read and write a rowset in XML format. A WebRowSet object uses a WebRowSetXmlReader object to read a rowset in XML format and a WebRowSetXmlWriter object to write a rowset in XML format. The XML version of a WebRowSet object contains its metadata, including its properties, in addition to its data.

The default constructor for a WebRowSet requests an RIXmlProvider implementation so that the WebRowSet object will be able to read and write a rowset as an XML document. It is also possible to set a WebRowSet object with a third-party SyncProvider implementation that provides XML capabilities.

A WebRowSet object is designed to work well in a distributed client/server application. It is similar to a CachedRowSet implementation in that both connect a thin client to an application server. Thus, they are both good for providing data to a thin client. The difference is that they use different protocols. Because a CachedRowSet object is serializable, it can be sent to another component using RMI/IIOP (Remote Method Invocation/Internet Interoperability Protocol). A WebRowSet object uses HTTP/XML (Hypertext Transfer Protocol/eXtensible Markup Language) to communicate with the middle tier, so that, for example, Web clients can talk to Java servlets that provide data access.

XML has become more and more important for Web services because of the portability of data it provides. The JDBC RowSet Implementations specification includes a standard WebRowSet XML Schema, available at http://java.sun.com/xml/ns/jdbc/webrowset.xsd, to which a standard WebRowSet object adheres. This means that if two parties have the XML schema for a WebRowSet object, they can use it to exchange rowsets in a common format even though they may store their data internally in entirely different formats. This makes a WebRowSet object a powerful tool for data exchange.

Because the Java platform provides portability of code and XML provides portability of data, they are the ideal combination for Web services. Technologies like JavaTM API for XML-based RPC, SOAP with Attachments API for JavaTM, JavaTM Architecture for XML Binding, and JavaTM API for XML Registries make developing Web services easier and easier. Plus the infrastructure that the J2EE platform provides saves developers from having to program their own "plumbing" for the management of distributed transactions, connection pooling, and security.

Being able to use a WebRowSet object for sending data adds even more to the value of using the Java platform for Web services. For example, because it uses the standard XML schema, a WebRowSet object can be part of a Web services message (generally using SOAP with Attachments API for Java technology).

The following code fragment is a simple example that creates the WebRowSet object wrs, populates it with the data of the ResultSet object rs, and then updates a column value. The final two lines output wrs in XML format.

    WebRowSet wrs = new WebRowSetImpl();
    wrs.populate(rs);

    //perform updates
    wrs.absolute(2)
    wrs.updateString(1, "newString");

    FileWriter fWriter = new FileWriter("/share/net/output.xml");
    wrs.writeXml(fWriter);
The machine that receives the XML output will do something similar to the following to read it. Once wrs has read in the data and metadata in fReader, the code operates on it just as it would on any other WebRowSet object.

    WebRowSet wrs = new WebRowsetImpl();

    FileReader fReader = new FileReader("/share/net/output.xml");
    wrs.readXml(fReader);

    wrs.absolute(2);
    String str = wrs.getString(1);

10.2.15 FilteredRowSet Implementation

A FilteredRowSet object, an extension of a CachedRowSet object, lets a programmer use a filtered subset of data from a rowset. For example, suppose a FilteredRowSet object contains a fairly large set of rows. A programmer who wants to perform operations on only a subset of those rows can specify a range of values, and the FilteredRowSet object will return only values in that range. This filtering is done by the method next, which is implemented to skip any rows that do not fall within the specified range. Without this capability, the programmer would have to make a connection to the data source, get a ResultSet object with the selected rows, and populate a rowset with those rows. Because establishing a connection is very expensive, far outweighing the cost of the memory needed to store a FilteredRowSet object, the ability to get a selected set of rows without making a new connection often results in a significant improvement in performance.

Suppose you have a FilteredRowSet object frs that contains all of the employees in Company XYZ. You have figured the average salary for the company, including everyone in the average. Now you want to get information about only the employees whose names range from Aaronson to Lee. The following code fragment causes frs to make available only the rows where the values in the column NAMES are in the range of Aaronson to Lee.

In the following code fragment, the FilteredRowSet object frs is populated with data from the ResultSet object rs. Then the code creates a Range object, specifying that the last names Aaronson through Lee, which are in the column NAME, make up the range of names that the method next can return.

    FilteredRowSet frs = new FilteredRowSetImpl();
    frs.populate(rs);

    Range names = new Range("Aaronson", "Lee", findColumn("NAME"));
    frs.setFilter(names);

    while (frs.next()) {
      String name = frs.getString("NAME");
      . . . // add each name to, for example, a mailing list
      // only names from "Aaronson" to "Lee" will be returned
    }
If some of the data in the subset stored in a FilteredRowSet object needs to be changed, it can be modified and synchronized with the data source. Only the modifications in the subset will be synchronized. If, however, the source of the data is an SQL VIEW that is not updatable, indicated by the constant SyncProvider.NONUPDATABLE_VIEW_SYNC, the modifications to the FilteredRowSet object will not be synchronized.

10.2.16 JoinRowSet Implementation

A JoinRowSet object lets a programmer combine data from two different RowSet objects. This can be especially valuable when related data is stored in different data sources. Any RowSet implementation can participate in a join, but it is typically two CachedRowSet objects that are joined. With all of the relevant data combined into one JoinRowSet object, an application can process the data just as it would for any other kind of RowSet object.

The following code fragment demonstrates how the data from two CachedRowSet objects is joined into one JoinRowSet object. In this scenario, data from the table EMPLOYEES is joined with data from the table BONUS_PLAN, thereby giving information about each employee and his or her bonus plan all in one rowset. In both of the original rowsets, the first column is the employee identification number, so that is the column used to match the data from one table with data from the other. After the join, each row in the JoinRowSet object will contain the columns from both rowsets that pertain to the same employee ID.

The first line of code creates the JoinRowSet object jrs. Next, all the columns from the table EMPLOYEES are used to populate the new CachedRowSet object empl, the first column of empl is set as the match column, and empl is added to jrs. Then, in similar fashion, all the columns from the table BONUS_PLAN are used to populate the CachedRowSet object bonus, the first column of bonus is set as the match column, and bonus is added to jrs. In both empl and bonus, the first column is EMPLOYEE_ID, which is the primary key. It is the column both rowsets have in common, and it can be used to match the information from empl about an employee with the information in bonus about the same employee. The last lines of code navigate jrs and retrieve a column value.

    JoinRowSet jrs = new JoinRowSetImpl();

    ResultSet rs1 = stmt.executeQuery("SELECT * FROM EMPLOYEES");
    CachedRowSet empl = new CachedRowSetImpl();
    empl.populate(rs1);
    empl.setMatchColumn(1); // The first column is EMPLOYEE_ID
    jrs.addRowSet(empl);

    ResultSet rs2 = stmt.executeQuery("SELECT * FROM BONUS_PLAN");
    CachedRowSet bonus = new CachedRowSetImpl();
    bonus.populate(rs2);
    bonus.setMatchColumn(1); // The first column is EMPLOYEE_ID
    jrs.addRowSet(bonus);

      // The jrs instance now joins the two rowsets. The application
      // can browse the combined data as if it were browsing one single
      // RowSet object.

    jrs.first();
    int employeeID = jrs.getInt(1);
    String employeeName = jrs.getString(2);
Similar to the case with FilteredRowSet objects, a JoinRowSet object can have its modified data synchronized providing that the source from which the data came is not a non-updatable SQL VIEW.
[Top] [ Prev] [Next]

jdbc@eng.sun.com or jdbc-business@eng.sun.com
Copyright © 1996-2004 Sun Microsystems, Inc. All rights reserved.


 [Top] [Prev] [Next]

Statement

NOTE: The material in this chapter is based on JDBCtm API Tutorial and Reference, Second Edition: Universal Data Access for the Javatm 2 Platform, published by Addison Wesley as part of the Java series, ISBN 0-201-43328-1.

4.1 Statement Overview

A Statement object is used to send SQL statements to a database. There are actually three kinds of Statement objects, all of which act as containers for executing SQL statements on a given connection: Statement, PreparedStatement, which inherits from Statement, and CallableStatement, which inherits from PreparedStatement. They are specialized for sending particular types of SQL statements; a Statement object is used to execute a simple SQL statement with no parameters, a PreparedStatement object is used to execute a precompiled SQL statement with or without IN parameters, and a CallableStatement object is used to execute a call to a database stored procedure.

The Statement interface provides basic methods for executing statements and retrieving results. The PreparedStatement interface adds methods for dealing with IN parameters; the CallableStatement interface adds methods for dealing with OUT parameters.

In the JDBC 2.0 core API, the ResultSet interface has a set of new updateXXX methods and other new related methods that make it possible to update table column values programmatically. This new API also adds methods to the Statement interface (and PreparedStatement and CallableStatement interfaces) so that update statements may be executed as a batch rather than singly.

4.1.1 Creating Statement Objects

Once a connection to a particular database is established, that connection can be used to send SQL statements. A Statement object is created with the Connection method createStatement, as in the following code fragment:

Connection con = DriverManager.getConnection(url, "sunny", "");
Statement stmt = con.createStatement();

The SQL statement that will be sent to the database is supplied as the argument to one of the execute methods on a Statement object. This is demonstrated in the following example, which uses the method executeQuery:

ResultSet rs = stmt.executeQuery("SELECT a, b, c FROM Table2");

The variable rs references a result set that cannot be updated and in which the cursor can move only forward, which is the default behavior for ResultSet objects. The JDBC 2.0 core API adds a new version of the method Connection.createStatement that makes it possible to create Statement objects that produce result sets that are scrollable and/or updatable.

4.1.2 Executing Statements Using Statement Objects

The Statement interface provides three different methods for executing SQL statements: executeQuery, executeUpdate, and execute. The correct method to use is determined by what the SQL statement produces.

The method executeQuery is designed for statements that produce a single result set, such as SELECT statements.

The method executeUpdate is used to execute INSERT, UPDATE, or DELETE statements and also SQL DDL (Data Definition Language) statements like CREATE TABLE, DROP TABLE, and ALTER TABLE. The effect of an INSERT, UPDATE, or DELETE statement is a modification of one or more columns in zero or more rows in a table. The return value of executeUpdate is an integer (referred to as the update count) that indicates the number of rows that were affected. For statements such as CREATE TABLE or DROP TABLE, which do not operate on rows, the return value of executeUpdate is always zero.

The method execute is used to execute statements that return more than one result set, more than one update count, or a combination of the two. Because it is an advanced feature that the majority of programmers will never use, it is explained in its own section later in this overview.

All of the methods for executing statements close the calling Statement object's current result set if there is one open. This means that any processing of the current ResultSet object needs to be completed before a Statement object is re-executed.

It should be noted that the PreparedStatement interface, which inherits all of the methods in the Statement interface, has its own versions of the methods executeQuery, executeUpdate and execute. Statement objects do not themselves contain an SQL statement; therefore, one must be provided as the argument to the Statement.execute methods. PreparedStatement objects do not supply an SQL statement as a parameter to these methods because they already contain a precompiled SQL statement. CallableStatement objects inherit the PreparedStatement forms of these methods. Supplying a parameter to the PreparedStatement or CallableStatement versions of these methods will cause an SQLException to be thrown.

4.1.3 Statement Completion

When a connection is in auto-commit mode, the statements being executed within it are committed or rolled back when they are completed. A statement is considered complete when it has been executed and all its results have been returned. For the method executeQuery, which returns one result set, the statement is completed when all the rows of the ResultSet object have been retrieved. For the method executeUpdate, a statement is completed when it is executed. In the rare cases where the method execute is called, however, a statement is not complete until all of the result sets or update counts it generated have been retrieved.

Some DBMSs treat each statement in a stored procedure as a separate statement; others treat the entire procedure as one compound statement. This difference becomes important when auto-commit is enabled because it affects when the method commit is called. In the first case, each statement is individually committed; in the second, all are committed together.

4.1.4 Closing Statements

Statement objects will be closed automatically by the Java garbage collector. Nevertheless, it is recommended as good programming practice that they be closed explicitly when they are no longer needed. This frees DBMS resources immediately and helps avoid potential memory problems.

4.1.5 SQL Escape Syntax in Statements

Statement objects may contain SQL statements that use SQL escape syntax. Escape syntax signals the driver that the code within it should be handled differently. When escape processing is enabled (by calling Statement.setEscapeProcessing(true) or RowSet.setEscapeProcessing(true)), the driver will scan for any escape syntax and translate it into code that the particular database understands. This makes escape syntax DBMS-independent and allows a programmer to use features that might not otherwise be available.

An escape clause is demarcated by curly braces and a key word, which indicates the kind of escape clause.

    {keyword . . . parameters . . . }

The following keywords are used to identify escape clauses:

  • escape for LIKE escape characters The percent sign percent sign (%) wildcard>(%) and underscore underbar (_) wildcard>(_) characters work like wild cards in SQL LIKE clauses (% matches zero or more characters, and _ matches exactly one character). In order to interpret them literally, they can be preceded by a backslash (\), which is a special escape character in strings. One can specify which character to use as the escape character by including the following syntax at the end of a query:
        {escape 'escape-character'}
    For example, the following query, using the backslash character as an escape character, finds identifier names that begin with an underbar.
    stmt.executeQuery("SELECT name FROM Identifiers
      WHERE Id LIKE '\_%' {escape '\'}");
  • fn for scalar functions

    Almost all DBMSs have numeric, string, time, date, system, and conversion functions on scalar values. One of these functions can be used by putting it in escape syntax with the keyword fn followed by the name of the desired function and its arguments. For example, the following code calls the function concat with two arguments to be concatenated:

        {fn concat("Hot", "Java")};
    The name of the current database user can be obtained with the following syntax:
        {fn user()};
    Scalar functions may be supported by different DBMSs with slightly different syntax, and they may not be supported by all drivers. Various DatabaseMetaData methods will list the functions that are supported. For example, the method getNumericFunctions returns a comma-separated list of the Open Group CLI names of numeric functions, the method getStringFunctions returns string functions, and so on. The driver will either map the escaped function call into the appropriate syntax or implement the function directly itself. However, a driver is required to implement only those scalar functions that the DBMS supports.

  • d, t, and ts for date and time literals DBMSs differ in the syntax they use for date, time, and timestamp literals. The JDBC API supports ISO standard format for the syntax of these literals, using an escape clause that the driver must translate to the DBMS representation. For example, a date is specified in a JDBC SQL statement with the following syntax:
        {d 'yyyy-mm-dd'}
    In this syntax, yyyy is the year, mm is the month, and dd is the day. The driver will replace the escape clause with the equivalent DBMS-specific representation. For example, the driver might replace {d 1999-02-28} with '28-FEB-99' if that is the appropriate format for the underlying database. There are analogous escape clauses for TIME and TIMESTAMP:
            {t 'hh:mm:ss'}
        {ts 'yyyy-mm-dd hh:mm:ss.f . . .'}
    The fractional seconds (.f . . .) portion of the TIMESTAMP can be omitted.

  • call or ?= call for stored procedures If a database supports stored procedures, they can be invoked from JDBC with the syntax shown below. Note that the square brackets ([ ]) indicate that what is between them is optional, and they are not part of the syntax.
        {call procedure_name[(?, ?, . . .)]}

    or, where a procedure returns a result parameter:

        {? = call procedure_name[(?, ?, . . .)]}
    Input arguments may be either literals or parameters. See the section "Numbering of Parameters" on page 81 for more information. One can call the method DatabaseMetaData.supportsStoredProcedures to see if the database supports stored procedures.

  • oj for outer joins The syntax for an outer join is:
            {oj outer-join}
    In this syntax, outer-join has the form
    table {LEFT|RIGHT|FULL} OUTER JOIN {table | outer-join}
    ON search-condition
    (Note that curly braces ({}) in the preceding line indicate that one of the items between them must be used; they are not part of the syntax.) The following SELECT statement uses the escape syntax for an outer join.
    Statement stmt = con.createStatement("SELECT * FROM {oj TABLE1
    LEFT OUTER JOIN TABLE2 ON DEPT_NO = 003420930}");
    Outer joins are an advanced feature and are not supported by all DBMSs; consult the SQL grammar for an explanation of them. JDBC provides three DatabaseMetaData methods for determining the kinds of outer joins a driver supports: supportsOuterJoins, supportsFullOuterJoins, and supportsLimitedOuterJoins.

The method Statement.setEscapeProcessing turns escape processing on or off, with the default being on. A programmer might turn it off to cut down on processing time when performance is paramount, but it would normally be turned on. It should be noted that the method setEscapeProcessing does not work for PreparedStatement objects because the statement may have already been sent to the database before it can be called. See page 69, the overview of the PreparedStatement interface, regarding precompilation.

4.1.6 Sending Batch Updates

The batch update facility provided by the JDBC 2.0 core API allows a Statement object to submit multiple update commands together as a single unit, or batch, to the underlying DBMS. This ability to submit multiple updates as a batch rather than having to send each update individually can improve performance greatly in some situations.

The following code fragment demonstrates how to send a batch update to a database. In this example, a new row is inserted into three different tables in order to add a new employee to a company database. The code fragment starts by turning off the Connection object con's auto-commit mode in order to allow multiple statements to be sent together as a transaction. After creating the Statement object stmt, it adds three SQL INSERT INTO commands to the batch with the method addBatch and then sends the batch to the database with the method executeBatch. The code looks like this:

Statement stmt = con.createStatement();
con.setAutoCommit(false);

stmt.addBatch("INSERT INTO employees VALUES (1000, 'Joe Jones')");
stmt.addBatch("INSERT INTO departments VALUES (260, 'Shoe')");
stmt.addBatch("INSERT INTO emp_dept VALUES (1000, '260')");

int [] updateCounts = stmt.executeBatch();

Because the connection's auto-commit mode is disabled, the application is free to decide whether or not to commit the transaction if an error occurs or if some of the commands in the batch fail to execute. For example, the application may not commit the changes if any of the insertions fail, thereby avoiding the situation where employee information exists in some tables but not in others.

In the JDBC 2.0 core API, a Statement object is created with an associated list of commands. This list is empty to begin with; commands are added to the list with the Statement method addBatch. The commands added to the list must all return only a simple update count. If, for example, one of the commands is a query (a SELECT statement), which will return a result set, the method executeBatch will throw a BatchUpdateException. A Statement object's list of commands can be emptied by calling the method clearBatch on it.

In the preceding example, the method executeBatch submits stmt's list of commands to the underlying DBMS for execution. The DBMS executes each command in the order in which it was added to the batch and returns an update count for each command in the batch, also in order. If one of the commands does not return an update count, its return value cannot be added to the array of update counts that the method executeBatch returns. In this case, the method executeBatch will throw a BatchUpdateException. This exception keeps track of the update counts for the commands that executed successfully before the error occurred, and the order of these update counts likewise follows the order of the commands in the batch.

In the following code fragment, an application uses a try/catch block, and if a BatchUpdateException is thrown, it retrieves the exception's array of update counts to discover which commands in a batch update executed successfully before the BatchUpdateException object was thrown.

try {
    stmt.addBatch("INSERT INTO employees VALUES (" +
                "1000, 'Joe Jones')");
    stmt.addBatch("INSERT INTO departments VALUES (260, 'Shoe')");
    stmt.addBatch("INSERT INTO emp_dept VALUES (1000, '260')");

    int [] updateCounts = stmt.executeBatch();

} catch(BatchUpdateException b) {
    System.err.println("Update counts of successful commands: ");
    int [] updateCounts = b.getUpdateCounts();
    for (int  i = 0; i < updateCounts.length; i ++) {
        System.err.print(updateCounts[i] + "  ");
    }
    System.err.println("");
}

If a printout was generated and looked similar to the following, the first two commands succeeded and the third one failed.

Update counts of successful commands:
1   1

JDBC drivers are not required to support batch updates, so a particular driver might not implement the methods addBatch, clearBatch, and executeBatch. Normally a programmer knows whether a driver that he/she is working with supports batch updates, but if an application wants to check, it can call the DatabaseMetaData method supportsBatchUpdates to find out. In the following code fragment, a batch update is used only if the driver supports batch updates; otherwise, each update is sent as a separate statement. The connection's auto-commit mode is disabled so that in either case, all the updates are included in one transaction.

con.setAutoCommit(false);
    if(dbmd.supportsBatchUpdates) {
    stmt.addBatch("INSERT INTO . . .");
    stmt.addBatch("DELETE . . .");
    stmt.addBatch("INSERT INTO . . .");
    . . .
    stmt.executeBatch();
} else {
    System.err.print("Driver does not support batch updates; ");
    System.err.println("sending updates in separate statements.");
    stmt.executeUpdate("INSERT INTO . . .");
    stmt.executeUpdate("DELETE . . .");
    stmt.executeUpdate("INSERT INTO . . .");
    . . .
con.commit();

4.1.7 Giving Performance Hints

The Statement interface contains two methods for giving performance hints to the driver: setFetchDirection and setFetchSize. These methods are also available in the ResultSet interface and do exactly the same thing. The difference is that the Statement methods set the default for all of the ResultSet objects produced by a particular Statement object, whereas the ResultSet methods can be called any time during the life of the ResultSet object to change the fetch direction or the fetch size. See the section "Providing Performance Hints" on page 54 for a full discussion of these methods.

Both the Statement and ResultSet interfaces have the corresponding get methods: getFetchDirection and getFetchSize. If Statement.getFetchDirection is called before a fetch direction has been set, the value returned is implementation-specific, that is, it is up to the driver. The same is true for the method Statement.getFetchSize.

4.1.8 Executing Special Kinds of Statements

The execute method should be used only when it is possible that a statement may return more than one ResultSet object, more than one update count, or a combination of ResultSet objects and update counts. These multiple possibilities for results, though rare, are possible when one is executing certain stored procedures or dynamically executing an unknown SQL string (that is, unknown to the application programmer at compile time). For example, a user might execute a stored procedure (using a CallableStatement object), and that stored procedure could perform an update, then a select, then an update, then a select, and so on. In more typical situations, someone using a stored procedure will already know what it returns.

[Top] [Prev] [Next]

Copyright © 1999, Sun Microsystems, Inc.   All rights
reserved.


 [Top] [Prev] [Next] [Bottom]

Summary of New Features

NOTE: Some of the material in this chapter is based on JDBCtm API Tutorial and Reference, Second Edition: Universal Data Access for the Javatm 2 Platform, published by Addison Wesley as part of the Java series, ISBN 0-201-43328-1.

This appendix summarizes the new features that have been added to the JDBC API over time. Note that in order to use a feature, you must be using a driver that supports that feature.

A.1 Overview of JDBC 3.0 API Changes

One of the major changes in the JDBC 3.0 API is that it includes the package javax.sql (the JDBC Optional Package) as well as the package java.sql. This overview is divided into two sections, the first giving new features introduced in the JDBC 3.0 API for both packages, and the second giving the features introduced in the JDBC 2.0 Optional Package. See the JDBC 3.0 API Specification for more detailed information.

A.1.1 Features Introduced in the JDBC 3.0 API

The JDBC 3.0 API introduces new material and changes in these areas:

  • Savepoint support
    Added the Savepoint interface, which contains new methods to set a savepoint, to release a savepoint, and to roll back a transaction to a designated savepoint.
  • Reuse of prepared statements by connection pools
    Added the ability for deployers to control how prepared statements are pooled and reused by connections.
  • Connection pool configuration
    Defined a number of properties for the ConnectionPoolDataSource interface. These properties can be used to describe how PooledConnection objects created by DataSource objects should be pooled.
  • Retrieval of parameter metadata
    Added the new interface ParameterMetaData, which describes the number, type, and properties of parameters to prepared statements.
  • Retrieval of auto-generated keys
    Added a means of retrieving values from columns containing automatically generated values.
  • Ability to have multiple open ResultSet objects
    Added the new method getMoreResults(int) that takes an argument that specifies whether ResultSet objects returned by a Statement should be closed before returning any subsequent ResultSet objects.
  • Passing parameters to CallableStatement objects by name
    Added methods to allow a string to identify the parameter to be set for a CallableStatement object.
  • Holdable cursor support
    Added the ability to specify whether a ResultSet object is kept open after a transaction has been committed.
  • BOOLEAN data type
    Added the data type java.sql.Types.BOOLEAN. BOOLEAN is logically equivalent to BIT.
  • Making internal updates to the data in Blob and Clob objects
    Added methods to allow the data contained in Blob and Clob objects to be altered.
  • Retrieving and updating the object referenced by a Ref object
    Added methods to retrieve the object referenced by a Ref object. Also added the ability to update a referenced object through the Ref object.
  • Updating of columns containing BLOB, CLOB, ARRAY and REF types
    Addition of the updateBlob, updateClob, updateArray, and updateRef methods to the ResultSet interface.
  • DATALINK/URL data type
    Added the data type java.sql.Types.DATALINK, allowing JDBC drivers to store and retrieve references to external data.
  • Transform groups and type mapping
    Described the effect of transform groups and how this is reflected in the metadata.
  • Relationship between the JDBC SPI (Service Provider Interface) and the Connector architecture
    Described the relationship between the JDBC SPI and the connector architecture.
  • DatabaseMetadata APIs
    Added metadata for retrieving SQL type hierarchies and various other kinds of information relating to new features.

A.1.2 Features Introduced in the JDBC 2.0 Optional Package

The following features, which were introduced in the javax.sql package, are now part of the JDBC 3.0 API and are included in the J2SE version 1.4:

  • Using a DataSource Object to Get a Connection

    Using the JNDI API and the new DataSource interface, an application does not need to specify a driver name in its code to make a connection to a data source. It can specify a logical name that has been registered with a JNDI naming service and retrieve a DataSource object that will get a connection to the desired data source. This capability makes code more portable and much easier to maintain.

  • Connection Pooling

    Connection pooling allows an application to (re)use database connections that have already been established instead of always having to create new connections. Because creating and destroying database connections is expensive, this feature is important for good performance, especially for server applications.

    The JDBC 2.0 Optional Package API provides hooks that allow connection pooling to be implemented on top of the JDBC driver layer. This makes it possible to have a single cache of connections available for all of the JDBC drivers in use.

  • Support for Distributed Transactions

    The JDBC 2.0 Optional Package API allows a JDBC driver to support the standard two-phase commit protocol defined in the Java Transaction API (JTA). This means that a transaction may be distributed over multiple servers, which lets developers write enterprise applications using Enterprise JavaBeanstm components that are transactional across multiple DBMS servers.

  • Rowsets

    RowSet objects are simply containers for tabular data that can be implemented on top of the JDBC API. Rowsets make it possible to pass rows of data across a network, so they are likely to be used extensively in distributed applications. Rowsets may be very lean by being disconnected from a data source, making it possible to display data on a thin client. They also make it possible to use scrolling when the underlying DBMS does not support scrollable result sets. A rowset is a JavaBeanstm component and consequently easy to use in building an application, especially with a development tool.

    Typically, a third party will provide a RowSet implementation, and the application programmer just uses it. The API for a RowSet implementation is generally very easy to use because most of a rowset's functionality is inherited from the ResultSet interface. The more complicated aspects of a rowset take place internally and are invisible to the application programmer. There are currently three Early Access implementations of the RowSet interface available from the Java Developer Connection (http://developer.java.sun.com/developer).

A.2 Overview of JDBC 2.0 Core API Changes

The JDBC 2.0 core API includes the JDBC 1.0 API and adds enhancements and new functionality to it. These additions put the Java programming language at the forefront of database computing, providing both universal data access and improved performance.

Applications that use earlier versions of the JDBC API can be run using the Java 2 platform with no problem, in keeping with the goal of backward compatibility. However, an application that takes advantage of the new 2.0 features must be run with a driver that implements those features.

The new features in the JDBC 2.0 core API fall into two broad categories: support for new functionality and support for the SQL99 data types.

  1. Support for new functionality
    • scrollable result sets
    • batch updates
    • programmatic inserts, deletes, and updates
    • other
      • performance hints
      • character streams for streams of internationalized Unicode characters
      • full precision for java.math.BigDecimal values
      • support for time zones in Date, Time, and Timestamp values

  2. Support for advanced data types
    • new SQL data types (SQL99 types)
    • increased support for storing persistent objects in the Java programming language

      In addition to making the retrieval, storage, and manipulation of data more convenient, the new features make JDBC applications more efficient. For example, batch updates can increase performance dramatically. The new interfaces Blob, Clob, and Array allow applications to operate on large amounts of data without having to materialize the data on the client, which can mean a significant savings in transfer time and the amount of memory needed. Also, new methods for setting the fetch size and fetch direction let a programmer fine tune an application for more efficient data retrieval and processing.

A.3 Summary of New Functionality

The JDBC 2.0 core API adds important new functionality. The following sections briefly explain each new area of functionality and summarize the supporting API.

A.3.1 Scrollable Result Sets

Scrollable result sets provide the ability to move the cursor forward and backward to a specified position or to a position relative to the current position. The following interfaces have new methods that support scrollable result sets.

  • ResultSet
    • methods for moving the cursor to a particular row or to a relative position (either forward or backward)
    • methods for ascertaining the current position of the cursor
    • constants indicating the scrollability of a result set
  • Connection
    • new versions of the methods for creating Statement, PreparedStatement, and CallableStatement objects that make the result sets they produce scrollable
  • DatabaseMetaData
    • method indicating whether the DBMS and driver support scrollable result sets

A.3.2 Batch Updates

The new batch update facility provides the ability to send multiple updates to the database to be executed as a batch rather than sending each update separately. The following interfaces add methods that support batch updates, and the exception BatchUpdateException is new.

  • Statement, PreparedStatement, and CallableStatement
    • methods for adding update statements to a batch, clearing all update statements, and executing a batch
  • DatabaseMetaData
    • method indicating whether the DBMS and driver support batch updates
  • BatchUpdateException
    • exception thrown when an error occurs in a batch update

A.3.3 Programmatic Updates

Programmatic updates provide the ability to make updates using the JDBC API rather than SQL statements. The following interfaces have new methods and constants that support programmatic updates.

  • ResultSet
    • an updater method for updating each data type
    • methods for inserting, deleting, or updating a row
    • methods indicating whether a row was inserted, deleted, or updated
    • method for cancelling a row update
    • constants indicating the updatability of a result set
  • DatabaseMetaData
    • methods indicating the visibility of changes to a result set
    • methods indicating whether a result set detects inserts, deletes, or updates
    • method indicating whether the DBMS and driver support updatable result sets

A.3.4 Other New Features

The JDBC 2.0 core API provides various other new features, which are summarized in the following list.

  • Performance enhancements-new methods that allow a programmer to fine tune the retrieval of rows from the database. These methods provide the ability to specify (1) the number of result set rows fetched from the database when more rows are needed and (2) the direction in which rows are fetched from the database.
    • ResultSet methods for getting and setting the current fetch size and fetch direction
    • Statement, PreparedStatement, and CallableStatement methods for getting and setting the default fetch size and default fetch direction that result sets generated by executing a query will have when they are first created
  • Character streams-new methods that allow character data to be retrieved or sent to the database as a stream of internationalized Unicode characters. These methods replace the deprecated getUnicodeStream and setUnicodeStream methods.
    • ResultSet.getCharacterStream
    • CallableStatement.getCharacterStream
    • PreparedStatement.setCharacterStream
  • Full precision for java.math.BigDecimal values-new versions of themethods that retrieve a java.math.BigDecimal value with full precision. Unlike the deprecated versions they replace, these new versions do not take a specified precision.
    • ResultSet.getBigDecimal
    • CallableStatement.getBigDecimal
  • Support for time zones-methods with new versions that take a Calendar object as a parameter, which allows the driver to use a specified time zone rather than the default when calculating a value for a date, time, or timestamp
    • ResultSet.getDate
    • ResultSet.getTime
    • ResultSet.getTimestamp
    • CallableStatement.getDate
    • CallableStatement.getTime
    • CallableStatement.getTimestamp
    • PreparedStatement.setDate
    • PreparedStatement.setTime
    • PreparedStatement.setTimestamp

A.4 Support for Advanced Data Types

The JDBC 2.0 core API adds support for using advanced data types, making it as easy to use them as it is to use simple data types. This support includes the ability to store, retrieve, and update even the new SQL data types that are essentially objects, blurring the distinction between object databases and relational databases. The next four sections ("What Are the SQL99 Data Types?" on page 145, "Summary of Support for the SQL99 Data Types" on page 146, "Mapping of the SQL99 Types" on page 148, and "SQL Locators" on page 149) describe how the JDBC 2.0 core API provides support for these advanced data types.

In addition to being able to store objects defined in SQL as values in a database table, programmers writing Java applications can also store objects defined in the Java programming language as values in a database table. The section "Support for Storing Java Objects" on page 149 describes this capability.

Note that a driver is not required to implement functionality that its DBMS does not support, so not all drivers necessarily implement the functionality described here. DatabaseMetaData methods such as getTypeInfo, getColumns, and getUDTs may be called to get information about which data types a driver supports.

A.4.1 What Are the SQL99 Data Types?

This section briefly describes the new SQL99 data types. Their mapping to types in the Java programming language is described in section A.4.3 on page 148.

The SQL99 data types can be categorized as follows:

  • New built-in types-types for storing large objects. These are in addition to the standard built-in data types, such as CHAR, FLOAT, DATE, and so on.
    • BLOB (Binary Large Object)
    • CLOB (Character Large Object)
  • Constructed types-types based on a given base type
    • REF(structured type)-a reference to the specified SQL structured type
    • ARRAY[n]-an array of n elements that are all one data type
  • User-defined types (UDTs)-new types created with the SQL commandþCREATE TYPE
    • Distinct type-a new type based on the representation of a single built-in type
    • Structured type-a new type containing multiple attributes, each of which may be either a built-in or a user-defined data type
  • Locator types-types that are logical pointers to data that resides on the database server
    • LOCATOR(structured type)
    • LOCATOR(array)
    • LOCATOR(blob)
    • LOCATOR(clob)

A.4.2 Summary of Support for the SQL99 Data Types

The JDBC 2.0 core API supports the SQL 99 data types by means of the following new interfaces, methods, and fields.

  • New interfaces for the new data types. The SQL99 types are mapped by the following JDBC 2.0 core API interfaces:
    • java.sql.Array
    • java.sql.Blob
    • java.sql.Clob
    • java.sql.Ref
    • java.sql.Struct
  • Interfaces that support customizing the mapping of UDTs (SQL structured and distinct types) into classes in the Java programming language
    • SQLData
    • SQLInput
    • SQLOutput
  • Methods added to existing interfaces in order to retrieve, store, and update the SQL99 types
    • new getter methods in the ResultSet interface to retrieve SQL99 type column values from a result set
    • new getter methods in the CallableStatement interface to retrieve SQL99 type values in output parameters
    • new setter methods in the PreparedStatement interface to set a SQL99 type column value
    • new updater methods in the ResultSet interface to update values programmatically
  • Methods in the DatabaseMetaData and ResultSetMetaData interfaces for getting metadata about the SQL99 data types
  • Fields (constants) added to the class java.sql.Types to support new data types and persistent storage
    • DISTINCT
    • STRUCT
    • ARRAY
    • BLOB
    • CLOB
    • REF
    • JAVA_OBJECT

A.4.3 Mapping of the SQL99 Types

The JDBC API does not try to replicate the SQL99 types exactly; rather, its goal is to map them to types in the Java programming language so that they retain their functionality and are convenient to use. For example, SQL99 has what are called locator types, which are used on a client to designate data that is stored on a database server. Locators can be very useful for dealing with data that is large because they allow the data to be manipulated without having to be materialized on the client machine. SQL99 includes locators for the types ARRAY, BLOB, CLOB and structured types. The JDBC API does not include locators for these types directly (and not at all for structured types) but rather provides interfaces that are implemented such that the driver and DBMS use the appropriate locators behind the scenes. The result is that a developer using the JDBC API to access an SQL ARRAY, BLOB, or CLOB value need not even be aware of locators.

The following SQL99 types are mapped to interfaces in the Java programming language:

  • ARRAY-mapped to java.sql.Array
  • BLOB-mapped to java.sql.Blob
  • CLOB-mapped to java.sql.Clob
  • REF-mapped to java.sql.Ref
  • an SQL structured type-mapped to java.sql.Struct

Distinct types are not mapped to an interface because they are based on a single built-in type and thus can simply be mapped to the standard mapping for that built-in type. For example, the following is an SQL statement that creates the new type MONEY.

CREATE TYPE MONEY AS NUMERIC(10, 2)

This new UDT is based on the data type NUMERIC, which maps to java.math.BigDecimal, so the type MONEY maps to java.math.BigDecimal. This means that a value of type MONEY would be retrieved with the method getBigDecimal, stored with the method setBigDecimal, and updated with the method updateBigDecimal.

A.4.4 SQL Locators

An SQL LOCATOR is a logical pointer to data that resides on a database server. It typically refers to data that is too large to materialize on the client, such as images or audio. Locators exist only in a client environment, and their existence is transient. A standard implementation will use locators internally for instances of the Blob, Clob, and Array interfaces. This means that Blob, Clob, and Array objects contain a locator that points to the data on the server rather than containing the data itself. Programmers operating on Blob, Clob, and Array instances are actually operating on the database objects they represent. This ability to operate on large database objects without bringing their data to the client is a major plus in performance.

Note that the JDBC API does not call for using the SQL LOCATOR(structured type). In a standard implementation, a Struct object contains the data of the structured type that it maps and is not implemented internally as a locator, as are Blob, Clob, and Array objects.

A.4.5 Support for Storing Java Objects

The JDBC API has always supported persistent storage of objects defined in the Java programming language through the methods getObject and setObject. But, of course, persistent storage of Java objects does not actually occur unless a DBMS also supports it. Up to this point, support was limited, but a new generation of DBMSs that recognize Java objects as a data type is emerging. In these DBMSs, termed Java relational DBMSs, an instance of a Java class can be stored as a column value in a database table.

[Top] [Prev] [Next] [Bottom]

Copyright © 2001, Sun Microsystems, Inc. All rights reserved.


 [Top] [Prev] [Next] [Bottom]

Summary of New Features

NOTE: The material in this chapter is based on JDBCtm API Tutorial and Reference, Second Edition: Universal Data Access for the Javatm 2 Platform, published by Addison Wesley as part of the Java series, ISBN 0-201-43328-1.

This appendix summarizes the new features in the JDBC 2.1 core API.

A.1 Overview of JDBC 2.1 Core API Changes

The JDBC 2.1 core API includes the JDBC 1.0 API and adds enhancements and new functionality to it. These additions put the Java programming language at the forefront of database computing, providing both universal data access and improved performance.

Applications that use earlier versions of the JDBC API can be run using the Java 2 platform with no problem, in keeping with the goal of backward compatibility. However, an application that takes advantage of the new 2.0 features must be run with a driver that implements those features.

The new features in the JDBC 2.1 core API fall into two broad categories: support for new functionality and support for the SQL3 data types.

  1. Support for new functionality
    • scrollable result sets
    • batch updates
    • programmatic inserts, deletes, and updates
    • other
      • performance hints
      • character streams for streams of internationalized Unicode characters
      • full precision for java.math.BigDecimal values
      • support for time zones in Date, Time, and Timestamp values

  2. Support for advanced data types
    • new SQL data types (SQL3 types)
    • increased support for storing persistent objects in the Java programming language

In addition to making the retrieval, storage, and manipulation of data more convenient, the new features make JDBC applications more efficient. For example, batch updates can increase performance dramatically. The new interfaces Blob, Clob, and Array allow applications to operate on large amounts of data without having to materialize the data on the client, which can mean a significant savings in transfer time and the amount of memory needed. Also, new methods for setting the fetch size and fetch direction let a programmer fine tune an application for more efficient data retrieval and processing.

A.2 Summary of New Functionality

The JDBC 2.1 core API adds important new functionality. The following sections briefly explain each new area of functionality and summarize the supporting API.

A.2.1 Scrollable Result Sets

Scrollable result sets provide the ability to move the cursor forward and backward to a specified position or to a position relative to the current position. The following interfaces have new methods that support scrollable result sets.

  • ResultSet
    • methods for moving the cursor to a particular row or to a relative position (either forward or backward)
    • methods for ascertaining the current position of the cursor
    • constants indicating the scrollability of a result set
  • Connection
    • new versions of the methods for creating Statement, PreparedStatement, and CallableStatement objects that make the result sets they produce scrollable
  • DatabaseMetaData
    • method indicating whether the DBMS and driver support scrollable result sets

A.2.2 Batch Updates

The new batch update facility provides the ability to send multiple updates to the database to be executed as a batch rather than sending each update separately. The following interfaces add methods that support batch updates, and the exception BatchUpdateException is new.

  • Statement, PreparedStatement, and CallableStatement
    • methods for adding update statements to a batch, clearing all update statements, and executing a batch
  • DatabaseMetaData
    • method indicating whether the DBMS and driver support batch updates
  • BatchUpdateException
    • exception thrown when an error occurs in a batch update

A.2.3 Programmatic Updates

Programmatic updates provide the ability to make updates using the JDBC API rather than SQL statements. The following interfaces have new methods and constants that support programmatic updates.

  • ResultSet
    • an updateXXX method for updating each data type
    • methods for inserting, deleting, or updating a row
    • methods indicating whether a row was inserted, deleted, or updated
    • method for cancelling a row update
    • constants indicating the updatability of a result set
  • DatabaseMetaData
    • methods indicating the visibility of changes to a result set
    • methods indicating whether a result set detects inserts, deletes, or updates
    • method indicating whether the DBMS and driver support updatable result sets

A.2.4 Other New Features

The JDBC 2.1 core API provides various other new features, which are summarized in the following list.

  • Performance enhancements-new methods that allow a programmer to fine tune the retrieval of rows from the database. These methods provide the ability to specify (1) the number of result set rows fetched from the database when more rows are needed and (2) the direction in which rows are fetched from the database.
    • ResultSet methods for getting and setting the current fetch size and fetch direction
    • Statement, PreparedStatement, and CallableStatement methods for getting and setting the default fetch size and default fetch direction that result sets generated by executing a query will have when they are first created
  • Character streams-new methods that allow character data to be retrieved or sent to the database as a stream of internationalized Unicode characters. These methods replace the deprecated getUnicodeStream and setUnicodeStream methods.
    • ResultSet.getCharacterStream
    • CallableStatement.getCharacterStream
    • PreparedStatement.setCharacterStream
  • Full precision for java.math.BigDecimal values-new versions of themethods that retrieve a java.math.BigDecimal value with full precision. Unlike the deprecated versions they replace, these new versions do not take a specified precision.
    • ResultSet.getBigDecimal
    • CallableStatement.getBigDecimal
  • Support for time zones-methods with new versions that take a Calendar object as a parameter, which allows the driver to use a specified time zone rather than the default when calculating a value for a date, time, or timestamp
    • ResultSet.getDate
    • ResultSet.getTime
    • ResultSet.getTimestamp
    • CallableStatement.getDate
    • CallableStatement.getTime
    • CallableStatement.getTimestamp
    • PreparedStatement.setDate
    • PreparedStatement.setTime
    • PreparedStatement.setTimestamp

A.3 Support for Advanced Data Types

The JDBC 2.1 core API adds support for using advanced data types, making it as easy to use them as it is to use simple data types. This support includes the ability to store, retrieve, and update even the new SQL data types that are essentially objects, blurring the distinction between object databases and relational databases. The next four sections ("What Are the SQL3 Data Types?" on page 120, "Summary of Support for the SQL3 Data Types" on page 121, "Mapping of the New SQL3 Types" on page 122, and "SQL Locators" on page 123) describe how the JDBC 2.0 core API provides support for these advanced data types.

In addition to being able to store objects defined in SQL as values in a database table, programmers writing Java applications can also store objects defined in the Java programming language as values in a database table. The section "Support for Storing Java Objects" on page 123 describes this capability.

Note that a driver is not required to implement functionality that its DBMS does not support, so not all drivers necessarily implement the functionality described here. DatabaseMetaData methods such as getTypeInfo, getColumns, and getUDTs may be called to get information about which data types a driver supports.

A.3.1 What Are the SQL3 Data Types?

This section briefly describes the new SQL3 data types. Their mapping to types in the Java programming language is described in section A.3.3 on page 122.

The SQL3 data types can be categorized as follows:

  • New built-in types-types for storing large objects. These are in addition to the standard built-in data types, such as CHAR, FLOAT, DATE, and so on.
    • BLOB (Binary Large Object)
    • CLOB (Character Large Object)
  • Constructed types-types based on a given base type
    • REF(structured type)-a reference to the specified SQL structured type
    • ARRAY[n]-an array of n elements that are all one data type
  • User-defined types (UDTs)-new types created with the SQL commandþCREATE TYPE
    • Distinct type-a new type based on the representation of a single built-in type
    • Structured type-a new type containing multiple attributes, each of which may be either a built-in or a user-defined data type
  • Locator types-types that are logical pointers to data that resides on the database server
    • LOCATOR(structured type)
    • LOCATOR(array)
    • LOCATOR(blob)
    • LOCATOR(clob)

A.3.2 Summary of Support for the SQL3 Data Types

The JDBC 2.1 core API supports the new SQL 3 data types by means of the following new interfaces, methods, and fields.

  • New interfaces for the new data types. The SQL3 types are mapped by the following new JDBC 2.1 core API interfaces:
    • java.sql.Array
    • java.sql.Blob
    • java.sql.Clob
    • java.sql.Ref
    • java.sql.Struct
  • New interfaces that support customizing the mapping of UDTs (SQL structured and distinct types) into classes in the Java programming language
    • SQLData
    • SQLInput
    • SQLOutput
  • New methods added to existing interfaces in order to retrieve, store, and update the new SQL3 types
    • new getXXX methods in the ResultSet interface to retrieve SQL3 type column values from a result set
    • new getXXX methods in the CallableStatement interface to retrieve SQL3 type values in output parameters
    • new setXXX methods in the PreparedStatement interface to set a SQL3 type column value
    • new updateXXX methods in the ResultSet interface to update values programmatically
  • New methods in the DatabaseMetaData and ResultSetMetaData interfaces for getting metadata about the new data types
  • New fields (constants) added to the class java.sql.Types to support the new data types and persistent storage
    • DISTINCT
    • STRUCT
    • ARRAY
    • BLOB
    • CLOB
    • REF
    • JAVA_OBJECT

A.3.3 Mapping of the New SQL3 Types

The JDBC 2.1 core API does not try to replicate the SQL3 types exactly; rather, its goal is to map them to types in the Java programming language so that they retain their functionality and are convenient to use. For example, SQL3 has what are called locator types, which are used on a client to designate data that is stored on a database server. Locators can be very useful for dealing with data that is large because they allow the data to be manipulated without having to be materialized on the client machine. SQL3 includes locators for the types ARRAY, BLOB, CLOB and structured types. The JDBC 2.1 core API does not include locators for these types directly (and not at all for structured types) but rather provides interfaces that are implemented such that the driver and DBMS use the appropriate locators behind the scenes. The result is that a developer using the JDBC API to access an SQL ARRAY, BLOB, or CLOB value need not even be aware of locators. See section A.3.4 on page 123 for more information about locators.

In the JDBC 2.1 core API, the following SQL3 types are mapped to interfaces in the Java programming language:

  • ARRAY-mapped to java.sql.Array
  • BLOB-mapped to java.sql.Blob
  • CLOB-mapped to java.sql.Clob
  • REF-mapped to java.sql.Ref
  • an SQL structured type-mapped to java.sql.Struct

Distinct types are not mapped to an interface because they are based on a single built-in type and thus can simply be mapped to the standard mapping for that built-in type. For example, the following is an SQL statement that creates the new type MONEY.

CREATE TYPE MONEY AS NUMERIC(10, 2)

This new UDT is based on the data type NUMERIC, which maps to java.math.BigDecimal, so the type MONEY maps to java.math.BigDecimal. This means that a value of type MONEY would be retrieved with the method getBigDecimal, stored with the method setBigDecimal, and updated with the method updateBigDecimal.

A.3.4 SQL Locators

An SQL LOCATOR is a logical pointer to data that resides on a database server. It typically refers to data that is too large to materialize on the client, such as images or audio. Locators exist only in a client environment, and their existence is transient. A standard implementation of the JDBC 2.1 core API will use locators internally for instances of the Blob, Clob, and Array interfaces. This means that Blob, Clob, and Array objects contain a locator that points to the data on the server rather than containing the data itself. Programmers operating on Blob, Clob, and Array instances are actually operating on the database objects they represent. This ability to operate on large database objects without bringing their data to the client is a major plus in performance.

Note that the JDBC 2.1 core API does not call for using the SQL LOCATOR(structured type). In a standard implementation, a Struct object contains the data of the structured type that it maps and is not implemented internally as a locator, as are Blob, Clob, and Array objects.

A.3.5 Support for Storing Java Objects

The JDBC API has always supported persistent storage of objects defined in the Java programming language through the methods getObject and setObject. But, of course, persistent storage of Java objects does not actually occur unless a DBMS also supports it. Up to this point, support was limited, but a new generation of DBMSs that recognize Java objects as a data type is emerging. In these DBMSs, termed Java relational DBMSs, an instance of a Java class can be stored as a column value in a database table.

[Top] [Prev] [Next] [Bottom]

Copyright © 1999, Sun Microsystems, Inc. All rights reserved.


Untitled Document

 | TINYINT | SMALLINT | INTEGER | BIGINT | REAL | FLOAT | DOUBLE | DECIMAL | NUMERIC | BIT | CHAR | VARCHAR | LONGVARCHAR | BINARY | VARBINARY | LONGVARBINARY | DATE | TIME | TIMESTAMP | CLOB | BLOB | ARRAY | REF | STRUCT | JAVA OBJECT
getByte | y | x | x | x | x | x | x | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
getShort | x | y | x | x | x | x | x | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
getInt | x | x | y | x | x | x | x | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
getLong | x | x | x | y | x | x | x | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
getFloat | x | x | x | x | y | x | x | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
getDouble | x | x | x | x | x | y | y | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
getBigDecimal | x | x | x | x | x | x | x | y | y | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
getBoolean | x | x | x | x | x | x | x | x | x | y | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
getString | x | x | x | x | x | x | x | x | x | x | y | y | x | x | x | x | x | x | x |  |  |  |  |  |
getBytes |  |  |  |  |  |  |  |  |  |  |  |  |  | y | y | x |  |  |  |  |  |  |  |  |
getDate |  |  |  |  |  |  |  |  |  |  | x | x | x |  |  |  | y |  | x |  |  |  |  |  |
getTime |  |  |  |  |  |  |  |  |  |  | x | x | x |  |  |  |  | y | x |  |  |  |  |  |
getTimestamp |  |  |  |  |  |  |  |  |  |  | x | x | x |  |  |  | x | x | y |  |  |  |  |  |
getAsciiStream |  |  |  |  |  |  |  |  |  |  | x | x | y | x | x | x |  |  |  |  |  |  |  |  |
getUnicodeStream |  |  |  |  |  |  |  |  |  |  | x | x | y | x | x | x |  |  |  |  |  |  |  |  |
getBinaryStream |  |  |  |  |  |  |  |  |  |  |  |  |  | x | x | y |  |  |  |  |  |  |  |  |
getClob |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | y |  |  |  |  |
getBlob |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | y |  |  |  |
getArray |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | y |  |  |
getRef |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | y |  |
getCharacterStream |  |  |  |  |  |  |  |  |  |  | x | x | y | x | x | x |  |  |  |  |  |  |  |  |
getObject | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | y | y


Untitled Document

 | TINYINT | SMALLINT | INTEGER | BIGINT | REAL | FLOAT | DOUBLE | DECIMAL | NUMERIC | BIT | CHAR | VARCHAR | LONGVARCHAR | BINARY | VARBINARY | LONGVARBINARY | DATE | TIME | TIMESTAMP | CLOB | BLOB | ARRAY | REF | STRUCT | JAVA OBJECT
getByte | y | x | x | x | x | x | x | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
getShort | x | y | x | x | x | x | x | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
getInt | x | x | y | x | x | x | x | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
getLong | x | x | x | y | x | x | x | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
getFloat | x | x | x | x | y | x | x | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
getDouble | x | x | x | x | x | y | y | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
getBigDecimal | x | x | x | x | x | x | x | y | y | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
getBoolean | x | x | x | x | x | x | x | x | x | y | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
getString | x | x | x | x | x | x | x | x | x | x | y | y | x | x | x | x | x | x | x |  |  |  |  |  |
getBytes |  |  |  |  |  |  |  |  |  |  |  |  |  | y | y | x |  |  |  |  |  |  |  |  |
getDate |  |  |  |  |  |  |  |  |  |  | x | x | x |  |  |  | y |  | x |  |  |  |  |  |
getTime |  |  |  |  |  |  |  |  |  |  | x | x | x |  |  |  |  | y | x |  |  |  |  |  |
getTimestamp |  |  |  |  |  |  |  |  |  |  | x | x | x |  |  |  | x | x | y |  |  |  |  |  |
getAsciiStream |  |  |  |  |  |  |  |  |  |  | x | x | y | x | x | x |  |  |  |  |  |  |  |  |
getBinaryStream |  |  |  |  |  |  |  |  |  |  |  |  |  | x | x | y |  |  |  |  |  |  |  |  |
getCharacterStream |  |  |  |  |  |  |  |  |  |  | x | x | y | x | x | x |  |  |  |  |  |  |  |  |
getClob |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | y |  |  |  |  |
getBlob |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | y |  |  |  |
getArray |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | y |  |  |
getRef |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | y |  |
getObject | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | y | y


Untitled Document

 | TINYINT | SMALLINT | INTEGER | BIGINT | REAL | FLOAT | DOUBLE | DECIMAL | NUMERIC | BIT | CHAR | VARCHAR | LONGVARCHAR | BINARY | VARBINARY | LONGVARBINARY | DATE | TIME | TIMESTAMP | ARRAY | BLOB | CLOB | STRUCT | REF | JAVA OBJECT
String | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x | x |  |  |  |  |  |
java.math.BigDecimal | x | x | x | x | x | x | x | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
Boolean | x | x | x | x | x | x | x | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
Integer | x | x | x | x | x | x | x | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
Long | x | x | x | x | x | x | x | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
Float | x | x | x | x | x | x | x | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
Double | x | x | x | x | x | x | x | x | x | x | x | x | x |  |  |  |  |  |  |  |  |  |  |  |
byte[] |  |  |  |  |  |  |  |  |  |  |  |  |  | x | x | x |  |  |  |  |  |  |  |  |
java.sql.Date |  |  |  |  |  |  |  |  |  |  | x | x | x |  |  |  | x |  | x |  |  |  |  |  |
java.sql.Time |  |  |  |  |  |  |  |  |  |  | x | x | x |  |  |  |  | x |  |  |  |  |  |  |
java.sql.Timestamp |  |  |  |  |  |  |  |  |  |  | x | x | x |  |  |  | x | x | x |  |  |  |  |  |
Array |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | x |  |  |  |  |
Blob |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | x |  |  |  |
Clob |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | x |  |  |
Struct |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | x |  |
Ref |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | x |
Java class |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | x


Untitled Document

JDBC Type Name | Oracle 8.1 | Sybase 11.9 | Informix 9.2 | IBM DB2 5.2 (Unix, NT) | Microsoft SQL Server 7.0 | Microsoft Access 7.0 | Sybase SQL Anywhere 6.0
BIT |  | BIT |  |  | BIT | BIT | BIT
TINYINT |  | TINYINT | SMALLINT |  | TINYINT | BYTE | TINYINT
SMALLINT | SMALLINT, NUMBER(38,0) | SMALLINT | SMALLINT | SMALLINT | SMALLINT | SMALLINT | SMALLINT
INTEGER | INTEGER, NUMBER(38,0) | INTEGER | INTEGER, SERIAL | INTEGER | INTEGER | INTEGER, COUNTER | INTEGER
BIGINT |  |  | INT8, SERIAL8 | BIGINT |  |  |
REAL | REAL, NUMBER | REAL | REAL | REAL | REAL | REAL | REAL
FLOAT | FLOAT, NUMBER | FLOAT | FLOAT | FLOAT | FLOAT |  | FLOAT
DOUBLE | DOUBLE PRECISION, NUMBER | DOUBLE PRECISION | DOUBLE PRECISION | FLOAT | DOUBLE PRECISION | DOUBLE | DOUBLE PRECISION
NUMERIC(p,s) | NUMERIC(p,s), NUMBER(p,s) | NUMERIC(p,s) | NUMERIC(p,s) | NUMERIC(p,s) | NUMERIC(p,s) | CURRENCY | NUMERIC(p,s)
DECIMAL(p,s) | DECIMAL(p,s), NUMBER(p,s) | DECIMAL(p,s), MONEY | DECIMAL(p,s) | DECIMAL(p,s) | DECIMAL(p,s), MONEY |  | DECIMAL(p,s)
CHAR(n) | CHAR(n) n <= 2000 | CHAR(n) n <= 255 | CHAR(n) n <= 32767 | CHAR(n) n <= 254 | CHAR(n) n <= 8000 | CHAR(n) n <= 255 | CHAR(n) n <= 32,767
VARCHAR(n) | VARCHAR(n) n <= 4000 | VARCHAR(n) n <= 255 | VARCHAR(n) n <= 255 | VARCHAR(n) n <= 4000 | VARCHAR(n) n <= 8000 | VARCHAR(n) n <= 255 | VARCHAR(n) n <= 32,767
LONGVARCHAR | LONG limit is 2 Gigabytes | TEXT limit is 2 Gigabytes | TEXT limit is 2 Gigabytes | LONG VARCHAR limit is 32,700 bytes | TEXT limit is 2 Gigabytes | LONGCHAR limit is 2.0 Gigabytes | LONG VARCHAR limit is 2 Gigabytes
BINARY(n) |  | BINARY(n) n <= 255 | BYTE | CHAR(n) FOR BIT DATA n <= 254 | BINARY(n) n <= 8000 | BINARY(n) n <= 255 | BINARY n <= 32,767
VARBINARY | RAW(n) n <= 2000 | VARBINARY(n) n <= 255 | BYTE | VARCHAR(n) FOR BIT DATA n <= 4000 | VARBINARY(n) n <= 8000 | VARBINARY(n) n <= 255 |
LONGVARBINARY | LONG RAW limit is 2 Gigabyts | IMAGE limit is 2 Gigabytes | BYTE limit is 2 Gigabytes | LONG VARCHAR FOR BIT DATA limit is 32,700 bytes | IMAGE limit is 2 Gigabytes | LONGBINARY limit is 1.0 Gigabytes | IMAGE limit is 2 Gigabytes
DATE |  |  | DATE | DATE |  |  | DATE
TIME |  |  | DATETIME HOUR TO SECOND | TIME |  |  | TIME
TIMESTAMP | DATE | DATETIME, SMALLDATETIME | DATETIME YEAR TO FRACTION(S) | TIMESTAMP | DATETIME | DATETIME | TIMESTAMP
CLOB | CLOB |  | CLOB | CLOB(n) n <= 2,147,483,647 bytes |  |  |
BLOB | BLOB, BFILE |  | BLOB | BLOB(n) n <= 15,000,000 bytes |  |  |
ARRAY | VARRAY |  | LIST, SET, MULTISET |  |  |  |
STRUCT | OBJECT |  | ROW |  |  |  |
DISTINCT |  |  | DISTINCT |  |  |  |
REF | REF |  |  |  |  |  |
JAVA_OBJECT |  |  | OPAQUE |  |  |  |


Java Management Extensions

Java (tm)

Java Management Extensions (JMX)

 Documentation Contents
The Java Management Extensions (JMX) API is a standard API for management and monitoring of resources such as applications, devices, services, and the Java virtual machine. The JMX technology was developed through the Java Community Process (JCP) as Java Specification Request (JSR) 3, Java Management Extensions, and JSR 160, JMX Remote API.

Typical uses of the JMX technology include:

  • Consulting and changing application configuration
  • Accumulating statistics about application behavior and making them available
  • Notifying of state changes and erroneous conditions.

The JMX API includes remote access, so a remote management program can interact with a running application for these purposes.

Overview

  • Overview - This overview provides an introduction to the JMX technology.

API Specification

  • API Reference - Online documentation for all JMX packages, classes and members of the agent and instrumentation RI, as generated by the Javadoc tool.

Tutorials and Programming Guides

  • Tutorial - This tutorial presents some examples of the features of the JMX technology.
  • Examples - The JMX reference implementation contains code examples for different areas of JMX operation.

In addition to the above examples, once you have installed the Java Development Kit (JDK) 6, a sample application that demonstrates a real-life implementation of the JMX API can be found in the following directory:

JDK_HOME/sample/jmx/jmx-scandir

In the path above, JDK_HOME is the directory in which the JDK software is installed. The jmx-scandir example is an advanced example, which presents advanced concepts of the JMX API in a real-world scenario.

API Enhancements

  • API Enhancements in Java SE 6 - A list of JMX API changes between the J2SE 5.0 and Java SE 6 releases.

More Information

  • JMX home page - The page for news, downloads, blogs and other information about the JMX specification.
  • JMX 1.4 Specification (PDF)
  • JMX Tracing - Traces in the JMX implementation are based on the Java SE logging capability.
  • JSR 3 - The JCP page for the JMX API.
  • JSR 160 - The JCP page for the JMX Remote API.
  • Java SE Monitoring and Management documentation
Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun


Java Management Extensions

Java (tm)

Java Management Extensions (JMX) Tracing

 Documentation Contents

Traces in the JMX implementation are based on the Java SE logging capability (provided by classes in the java.util.logging package). The JMX implementation uses a set of Loggers for sending traces. All Loggers are contained in the javax.management namespace, which corresponds to the name of the root package hosting all public JMX interfaces.

The list below shows the Logger objects used in this implementation and their corresponding category of activity.

Logger Name: Information logged
javax.management.mbeanserver | Information about the MBean Server
javax.management.mlet | Information from an MLet service
javax.management.monitor | Information from a monitor
javax.management.timer | Information from a timer
javax.management.notification | Information from the notification mechanism
javax.management.relation | Information from the Relation Service
javax.management.modelmbean | Information from the Model MBean components
javax.management.misc | Information sent from any other class.
javax.management.remote.rmi | Information from the RMI connector.
javax.management.remote.misc | Information sent from any other JMX Remote API class.

The following log levels are used in JMX:

JMX log level: Description
Level.FINEST | Used to print debugging traces (useful for diagnosing the JMX implementation)
Level.FINER | Used to print information traces
Level.SEVERE | Used to notify of error conditions

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun

Java Software


Java Management Extensions API Enhancements

Java (tm)

JMX API Enhancements

 Documentation Contents

The Java Management Extensions (JMX) technology became a part of the Java platform in the Java 2 Platform, Standard Edition (J2SE) 5.0. The most significant enhancements that have been made to the JMX API in the Java Platform, Standard Edition (Java SE) 6 are listed below.

  • The JMX API now fully supports Generics.
  • MXBeans have been added. MXBeans are MBeans that provide a convenient way to bundle related values together without requiring clients to be specially configured to handle the bundles. A defined set of MXBeans already existed in the J2SE 5.0 platform, but Java SE 6 introduces an API to allow you to program your own custom MXBeans. See Introducing MXBeans in the JMX Technology Tutorial for information.
  • MBean Descriptors have been added. Descriptors allow you to give additional information about MBeans to management clients. See MBean Descriptors in the JMX Technology Tutorial for information.
  • A new class, javax.management.JMX, has been added to house constants and static methods.
  • Improvements have been made to the JMX Monitor API to support complex types. Previously, only attributes of simple types could be monitored, but often, the value to be monitored is buried inside a more complex type. See the JMX Specification, version 1.4, for details of the behavior of monitors.
  • key=* wildcards are now supported in ObjectName. Previously, "domain:key1=value1,*" could be used to match MBeans that have key1=value1 in their name, but "domain:key1=*" could not be used to match MBeans that have key1 in their name. This is now possible.

The following is the full list of changes made to the JMX API in the Java SE 6 platform. Where relevant, links to the related bug report or request for enhancement (RFE) are included.

  • Generification
  • MXBeans
  • Descriptors
  • New class javax.management.JMX
  • NotificationBroadcaster and NotificationBroadcasterSupport
  • ObjectName
  • Standard MBeans
  • Dynamic MBeans
  • Model MBeans
  • Open MBeans
  • Monitor Service
  • Timer Service
  • MLet Service
  • Relation Service
  • Query
  • MBeanServerInvocationHandler
  • Serial forms
  • Permission checks
  • MBean RuntimeException handling
  • JMX Remote API Enhancements

Generification

Constraints due to the integration of version 1.2 of the JMX API in both J2EE 1.4 and J2SE 5.0 meant that it could not be generified in the latter. This is now rectified (4847959). Most of the generification consists of application of the generified collections API (java.util.List, and so on). So for example, where MBeanServer.queryNames previously returned just Set, it now returns Set<ObjectName>. The javax.management.openmbean.OpenType class and its subclasses have also been generified to allow type constraints to be expressed. OpenMBeanAttributeInfoSupport and OpenMBeanParameterInfoSupport acquire type constraints in their constructors such that the default or legal values must be of the correct type. The StandardMBean constructor likewise acquires a type constraint so that the resource parameter must implement the interface specified by the interface parameter.

The following classes and methods have been updated:

  • MBeanServer[Connection].queryMBeans returns Set<ObjectInstance>
  • MBeanServer[Connection].queryNames returns Set<ObjectName>.
  • AttributeChangeNotificationFilter.getEnabledAttributes returns Vector<String>
  • AttributeList extends ArrayList<Object>
  • MBeanServerFactory.findMBeanServer returns ArrayList<MBeanServer>
  • NotificationFilterSupport.getEnabledTypes returns Vector<String>
  • The ObjectName class's constructor and getInstance method that formerly took a Hashtable now take a Hashtable<String,String>
  • ObjectName.getKeyPropertyList returns Hashtable<String,String>
  • openmbean.CompositeType.keySet returns Set<String>
  • TabularType.getIndexNames returns List<String>
  • Relation.getReferencedMBeans returns Map<ObjectName,ArrayList<String>>
  • In RelationServiceMBean:
    • findAssociatedMBeans returns Map<ObjectName,ArrayList<String>>
    • findRelationsOfType returns List<String>
    • getRole returns List<ObjectName>
    • findReferencingRelations returns Map<String,ArrayList<String>>
    • getAllRelationIds returns List<String>
    • getAllRelationTypeNames returns List<String>
    • getRoleInfos returns List<RoleInfo>
    • getReferencedMBeans returns Map<ObjectName,ArrayList<String>>
    • sendRelationRemovalNotification takes List<ObjectName>
    • updateRoleMap takes List<ObjectName>
    • sendRoleUpdateNotification takes List<ObjectName>
    • sendRoleUpdateNotification takes List<ArrayList>
  • RelationType.getRoleInfos returns List<RoleInfo>
  • MBeanServerNotificationFilter.get{Enabled|Disabled}ObjectNames returns Vector<ObjectName>
  • RelationNotification:
    • constructor arg theUnregMBeanList is now List<ObjectName>
    • constructor args the{New|Old}RoleValue are now List<ObjectName>
    • getMBeansToUnregister returns List<ObjectName>
    • get{Old|New}RoleValue returns List<ObjectName>
  • RelationService methods specified by RelationServiceMBean have received the same changes as RelationServiceMBean
  • RelationSupport methods specified by Relation have received the same changes as Relation.
  • RelationTypeSupport.getRoleInfos returns List<RoleInfo>
  • Role constructor and getRoleValue use List<ObjectName>
  • RoleList extends ArrayList<Object>
  • RoleUnresolved uses List<ObjectName>
  • RoleUnresolvedList extends ArrayList<Object>
  • Timer[MBean].get[All]NotificationIDs returns Vector<Integer>

MLetMBean and MLet's getMBeansFromURL methods cannot use generics because the elements of the returned Set can be either ObjectInstance or Throwable. AttributeList, RoleList, and RoleUnresolvedList extend ArrayList<Object> rather than the more natural ArrayList<Attribute> etc., because the latter would introduce an inconsistency due to the existing add and set methods which return void rather than boolean and Object, respectively.

New methods AttributeList.asList(), RoleList.asList(), and RoleUnresolvedList.asList() produce a List view of the underlying object with the correct type parameter. A new constructor AttributeList(List<Attribute>) converts in the opposite direction (RoleList and RoleUnresolvedList already had such constructors).

A detailed generification rationale details the choices that were made during generification of the API.

MXBeans

Previously, portable modelling of complex types had to be performed using Open MBeans, which are difficult to use. A feature, MXBeans, was added in J2SE 5 to make modelling with complex types easier. In this release, MXBeans have been generalized (6175517). MXBeans are a special kind of Standard MBean that provide a non-identity mapping between types in the Java interface and types in the management interface. In the same way as for Standard MBeans, MXBeans contain attributes that are defined by getX and setX methods, and other methods are operations. With MXBeans, however, the MBean that is actually registered in the MBean Server does not have exactly the same types for its attributes and operation parameters and return values. Instead, each type that occurs in the MXBean interface is converted to a type built from the fixed set defined in javax.management.openmbean. The MBean that is actually registered in the MBean Server is an Open MBean that references these converted types. When it is accessed, it converts values between the original MXBean interface type and the converted Open MBean type.

In this way, a client can access an MXBean without needing to know any model-specific types that might be referenced in the MXBean interface. The client only needs to know the standard Open MBean types.

The complete MXBean specification appears in the documentation for the annotation @MXBean.

The introduction of MXBeans has added or affected the following classes and interfaces:

  • javax.management.StandardMBean can now be used for MXBeans as well as Standard MBeans.
  • javax.management.MBeanServerInvocationHandler: can now be used for MXBean proxies as well as Standard MBean proxies.
  • javax.management.JMX: new class, with 4 new methods.
  • javax.management.MXBean: new annotation.
  • javax.management.openmbean.CompositeDataInvocationHandler : new class, with 2 new methods.
  • javax.management.openmbean.CompositeDataView: new interface, with one new method.
  • Class StandardMBean can be used to make an MXBean. Also, this class now implements MBeanRegistration. This allows it to track the name under which an MXBean is registered, in order to handle inter-MXBean references correctly.

Descriptors

Descriptors can be used to supply additional metadata about an MBean. Previously, only Model MBeans supported Descriptors. In this release, support for Descriptors has been extended to all types of MBean (6204469). In addition to the general utility of metadata for all types of MBeans, the change removes certain gratuitous differences between various kinds of MBeans. In particular, it makes it feasible to have an MBean that is both an Open MBean and a Model MBean.

For most constructors in the classes MBean*Info (MBeanInfo, MBeanAttributeInfo, etc), a parallel constructor has been added with the same parameters plus an additional Descriptor parameter. Likewise for OpenMBean*InfoSupport.

Open MBeans return information about default and legal values from the getDefaultValue(), getLegalValues(), getMaxValue(), getMinValue() methods of OpenMBeanParameterInfo and OpenMBeanAttributeInfo. This information is now also present in the corresponding Descriptors, and other types of MBean can also return the information in their Descriptors.

A parent interface of DescriptorAccess called javax.management.DescriptorRead has been added, that contains the getDescriptor method but not the setDescriptor method. The MBean*Info classes implement DescriptorRead.

A second, immutable implementation of the Descriptor interface called javax.management.ImmutableDescriptor has also been added. This preserves the property that all MBeans except Model MBeans have immutable metadata.

A number of new conventional Descriptor items ("fields") are documented in the Descriptor specification (6254721). Some of these items must be understood by the implementation (in italics in the specification) while others are left uninterpreted. The predefined field names have corresponding string constants in the new JMX class (6282502).

A new annotation DescriptorKey can be used to add information to the Descriptors for a Standard MBean (or MXBean) via annotations in the Standard MBean (or MXBean) interface (6221321). This makes it possible for a tool that generates Standard MBeans from an existing management model to include information from the model in the generated MBean interfaces, rather than in separate files.

The method Descriptor.getFieldValues(String...) and the constructor DescriptorSupport(String...) previously took a String[] parameter. The varargs syntax makes them easier to use.

A number of other changes have been made regarding descriptors, as follows.

  • 6255956: Descriptor defines equals method and specifies how array values are compared. The Descriptor interface specifies an equals method and its two concrete implementations implement it. This means that MBeanInfo etc can continue to be compared for equality taking the Descriptors into account. So that different implementations of Descriptor can be mixed, a hashCode() method is also specified and implemented.

  • 6267824: Clarify order the returned array is sorted with when calling Descriptor.getFieldValues(null). Previously it was not specified what order the returned values were in.

  • 6273765: Descriptor.getFieldValues(non-empty-array) on an empty descriptor has no special behavior. The array returned by this method has as many elements as there are parameters, with each element being the value associated with the corresponding parameter, or null if there is no such value.

    Through an oversight or an editing error, the @returns clause of this method previously said: If the descriptor is empty, you will get an empty array. Almost certainly, what was meant was that if the list of names is empty, you will get an empty array. As specified, there was a pernicious special case: if some or all of the names in the list are missing from the Descriptor, the corresponding elements in the returned array will be null, except if the Descriptor is empty, in which case there won't be any elements in the array.

    This special case did not show up in the existing use of Descriptors for Model MBeans, because empty Descriptors were not valid in any of the places where they were used. (Every Descriptor had to have at least the "name" and "descriptorType" entries.) However, this is no longer true for the more generalized use of Descriptors. The previously-specified behavior would therefore have generated hard-to-find bugs.

  • 6273613: Specify exception wrapping for Descriptor.setField and Descriptor.setFields. These methods were previously declared to throw RuntimeOperationsException but the specification did not say what the wrapped exception was.

  • 6289244: Clarify behaviour when null Descriptor parameter to MBeanInfo etc. The specification of the constructors of MBeanInfo and related classes previously stated that a null input value for the Descriptor parameter would produce an empty Descriptor. In fact it is equivalent to an empty Descriptor input value, to which the implementation can add certain standard fields.

New class javax.management.JMX

A new class javax.management.JMX has been added to house constants and static methods.

NotificationBroadcaster and NotificationBroadcasterSupport

A number of changes concern the interface NotificationBroadcaster and its default implementation NotificationBroadcasterSupport.

  • 4506105: Previously, to specify the types of notifications that could be sent, it was necessary to subclass NotificationBroadcasterSupport and override the getNotificationInfo() method. In this release, new constructors have been added, that take a MBeanNotificationInfo... as input.

  • 4661545: Previously, the specification was very vague about whether the notification dispatch model was synchronous or asynchronous. When a thread called sendNotification, the NotificationListener.handleNotification method of each listener might be called within that thread (a synchronous model) or within some other thread (an asynchronous model), depending on the class implementation. J2SE 5 implemented the synchronous model, meaning that NotificationBroadcasterSupport used the sender thread to send the notification to all listeners. Users had to create a subclass to override the method handleNotification if they wanted an asynchronous model.

    In Java SE 6, the default model is still synchronous. A constructor has been added to the class NotificationBroadcasterSupport to take a java.util.concurrent.Executor as a parameter. The Executor is used to dispatch the notification to its listeners. This allows users to avoid creating a subclass if they want the asynchronous model.

  • A third constructor combines the functionality of the above two, with both an Executor and an MBeanNotificationInfo... as parameters.

  • 6244863: Specify what happens with NotificationBroadcasterSupport if a filter or listener throws an exception. Previously, the JMX specification did not define what happens when the listeners or filters maintained by a notification broadcaster threw an exception. This behavior has now been specified. An Exception does not prevent other listeners from being invoked. But an Error is propagated to the caller of sendNotification.

  • 6252526: A new class, javax.management.StandardEmitterMBean, has been added. StandardEmitterMBean is a subclass of javax.management.StandardMBean that is a NotificationEmitter.

ObjectName

A number of changes concern the class ObjectName.

  • 4716807: Support key=* wildcard in ObjectName. Previously, it was possible to say domain:key1=value1,* to match MBeans that have key1=value1 in their name, but not domain:key1=* to match MBeans that have key1 in their name. The ObjectName functionality has been extended in this release, so that you can put a wildcard (* and/or ?) anywhere in a value.

    Two new methods, isPropertyValuePattern() and isPropertyValuePattern(String property), allow you to discover whether an ObjectName has a wildcard in the value of some property, and if so which property it might be.

  • 4780400: Two new ObjectName constants added. Users of the JMX API very often need to refer to two ObjectName constants:

        new ObjectName("JMImplementation:type=MBeanServerDelegate")
    new ObjectName("*:*")

    The first of these is hard to remember, and if you get it wrong then your code compiles but doesn't work. Both of these suffer from the problem that the ObjectName constructors throw the checked exception MalformedObjectNameException, so you end up having to wrap your constant in a try/catch block.

    To remedy this situation, two new constants have been added in this release:

    • javax.management.MBeanServerDelegate.DELEGATE_NAME
    • javax.management.ObjectName.WILDCARD

  • 5036680: ObjectName implements Comparable<ObjectName>. By implementing Comparable we allow a SortedSet to show its contents in a reasonable order without having to define a custom Comparator. See ObjectName.compareTo(ObjectName).

  • 6392494: Specify that // is reserved in ObjectName domains. It is planned to use the string // in ObjectName domains as part of the "cascading" feature in the next version of the JMX API. A warning has been added to the specification that this string should be avoided, even though the string does not yet have any special meaning to the implementation.

Standard MBeans

The following changes have been made to the specification of Standard MBeans.

  • 4949203: Correct text about invoking getters and setters. The JMX 1.2 specification document was supposed to clarify, per the Maintenance Review change list, that getters and setters in a Standard MBean cannot be invoked through MBeanServer.invoke. But the text to this effect erroneously appeared in the section about Dynamic MBeans. It should obviously be in the section about Standard MBeans.

    Also, this text mentioned the property "jmx.invoke.getters". Since it appears in the spec, one might conclude that an implementation is required to respect this property. But that's not what was stated during the Maintenance Review and it's not what was intended. Rather, this property is a feature of the Reference Implementation to ease the transition for code that may have incorrectly relied on being able to invoke getters before. So it should appear in the Release Notes of the Reference Implementation, not in the spec.

  • 6190628: Standard MBeans support covariant return types in MBean interfaces. J2SE 5 introduced covariant return types in classes and interfaces. However, MBean servers would reject Standard MBeans created with covariant types as they would appear inconsistent. In this release, covariance is allowed for operations (methods other than getters and setters) and for read-only attributes (getters without corresponding setters).

Dynamic MBeans

The following changes have been made concerning Dynamic MBeans.

  • 6306219: Clarify MBeanServer.isInstanceOf semantics for Dynamic MBeans. The specification of this method omitted an important case where it should return true, namely where the MBean's ClassLoader can load the named class and the MBean is an instance of that class. The Reference Implementation did in fact return true in this case. It makes a difference when a DynamicMBean returns in its MBeanInfo a class name of which it is not an instance. For example, an instance of javax.management.StandardMBean (which is a DynamicMBean) could return an MBeanInfo whose getClassName() returned "javax.management.timer.TimerMBean". Under the current specification, the call mbeanServer.isInstanceOf(objectName, "javax.management.StandardMBean") would then return false, since TimerMBean is not an instance of StandardMBean. In fact, it returns true, since the actual MBean object is an instance of StandardMBean.

    With the addition of the class StandardEmitterMBean, and the existing practice of using isInstanceOf to determine whether an MBean is a NotificationBroadcaster, it becomes important to change the spec to reflect the implementation. A StandardEmitterMBean will typically return an MBeanInfo with a class name that is not an NotificationBroadcaster; however, we want isInstanceOf(..., "javax.management.NotificationBroadcaster") to return true.

Model MBeans

A large number of small changes are applied to the specification for Model MBeans.

  • 4883709: "value" and "displayName" fields in Model MBean descriptors should be in italics. This is a bug in the PDF spec. Optional fields are supposed to be in italics but these ones were not.

  • 4997033: RequiredModelMBean.setAttribute should throw exception if no setMethod and no currencyTimeLimit. This change resolves a contradiction between the PDF and Javadoc texts. The specification is clarified so that an exception is thrown only when there is no setMethod and no caching, so that the setAttribute operation would have no effect.

  • 5043245: Attribute type check is too restrictive in RequiredModelMBean.getAttribute(). The specification was unclear as to whether the returned value had to be of the exact type declared for the attribute or could be of a subtype. It is changed to allow a subtype explicitly.

  • 5046781: Spec should say role field in ModelMBeanOperationInfo descriptor is optional. The PDF spec is clarified to allow this field to be omitted, reflecting the behavior of the Reference Implementation.

  • 5046784: Value of targetType in Model MBean descriptors is case insensitive. Although the specification implied through its examples that this field is case-insensitive, it was omitted from the explicit list of case-insensitive fields.

  • 5104947: Clarify whether ModelMBeanInfoSupport.clone is deep or shallow. The specification is modified to state the existing behavior whereby the clone is shallow.

  • 6175387: Add new OnUnregister persistPolicy value to Model MBean descriptor. When persistence is supported for Model MBean data, you can define how it works using a persistPolicy value in the Descriptor for an MBean attribute. Previously, these values were Never, OnUpdate, OnTimer, NoMoreOftenThan, and Always. This release has added a new value, OnUnregister, that means that the value of the attribute is persisted when the MBean containing it is unregistered from the MBean Server. The specification of the methods that consult this field has been updated accordingly, as has the list of persistPolicy values that do not result in a store in RequiredModelMBean.store() and RequiredModelMBean.setAttribute.

  • 6236765: ModelMBeanConstructorInfo says certain fields invalid, but doesn't check. The specification of ModelMBeanConstructorInfo previously said that the persistPolicy and currencyTimeLimit fields were invalid, but the Reference Implementation did not check this. To avoid breaking existing code that might have included those fields, the specification has been changed to say that they are meaningless but are not considered invalid.

  • 6241620: DescriptorSupport(String[],Object[]) doc contradictory concerning null parameters. A contradiction in the spec is resolved to reflect the behavior of the Reference Implementation.

  • 6332962: Problem serializing DescriptorSupport containing targetObject field. A Descriptor for an attribute or operation in a Model MBean can contain a targetObject field to direct accesses to that attribute or operation towards a different resource from the one defined for the Model MBean as a whole. As such, its value is often a non-serializable object, and in any case it does not make sense to serialize it. Therefore the spec is updated to exclude it from the serialization of DescriptorSupport so that RequiredModelMBean.getMBeanInfo() returns a serializable object.

Open MBeans

Many of the changes to Open MBeans were inspired by the addition of user-defined MXBeans. Here is the complete set of changes.

  • 5045358: Allow Open MBeans to reference arrays of primitive type. Previously, the set of types that could be referenced by an Open MBean only included the primitive wrapper types such as java.lang.Integer and java.lang.Boolean. However, it did not include the primitive types such as int and boolean. Arrays of these primitives are now included. The ArrayType class has been extended so that primitive types such as an int[] can be expressed as an OpenType. This new functionality allows MXBeans to map arrays of primitive types in the MXBean interface to the corresponding OpenTypes.

    The following methods have been added to the ArrayType class:

    • javax.management.openmbean.ArrayType.getArrayType(OpenType)
    • javax.management.openmbean.ArrayType.getPrimitiveArrayType(Class)
    • javax.management.openmbean.ArrayType.isPrimitiveArray()
    • javax.management.openmbean.ArrayType(SimpleType,boolean)

    In the constructor ArrayType(int dimension, OpenType<?> elementType), the elementType parameter can now be an ArrayType instance (6252649). The ArrayType.equals and ArrayType.hashcode methods now take the new primitiveArray flag into account.

  • 5095277: CompositeDataSupport.equals compares arrays element-by-element. Previously, if two CompositeDataSupport elements each had the same CompositeType containing at least one ArrayType item, calling CompositeDataSupport.equals would only compare the identities of the arrays. Consequently, CompositeDataSupport.equals would only return true if the objects referred to the same array. Now, calling CompositeDataSupport.equals compares the the arrays element-by-element, so it will return true if the two objects refer to different arrays with the same contents. A corresponding change is made to CompositeDataSupport.hashCode.

  • 6228130: TabularDataSupport.entrySet() specifies key in the returned Set is wrapped into a List. The documentation was previously unclear about the contents of the returned Set. This is now clarified by making it a Set<Map.Entry<Object,Object>> but detailing that it is in fact a Set<Map.Entry<List<?>,CompositeData>>. For compatibility reasons, the latter declaration is not directly possible.

  • 6320104: Add ability to set to UNKNOWN the OperationInfo impact of an Open MBean. The allowed values for the impact of an MBeanOperationInfo are ACTION, INFO, ACTION_INFO and UNKNOWN. The last of these values was previously not allowed for an OpenMBeanOperationInfoSupport.

  • 5072004: Better support for schema evolution in CompositeData and CompositeType. Given a CompositeType ct, the method javax.management.openmbean.CompositeType.isValue(x) previously returned true only if x was a CompositeData and x.getCompositeType() was equal to ct. This rule has been relaxed. The type returned by x.getCompositeType() must still have the same name as ct, and it must have all the same items as ct, but it can have additional items. This change also impacts the rules for TabularType.isValue and ArrayType.isValue regarding CompositeData items contained by the TabularData or the array.

  • 6333582: OpenType should not declare public static array ALLOWED_CLASSNAMES. This field is deprecated in favour of a new field ALLOWED_CLASSNAMES_LIST.

Monitor Service

The following changes are made to the specification of the Monitor Service (package javax.management.monitor).

  • 6222961: Monitor Service supports complex types. Previously with the Monitor Service, you could only monitor an attribute of simple type. Often, the value you want to monitor is buried inside a more complex type. For example, if you are dealing with the J2EE instrumentation defined by JSR 77, then to set a monitor on a servlet's service time, you want to get the ServiceTime attribute for the servlet and monitor serviceTime.getMaxTime(). The spec is changed so that you can monitor ServiceTime.maxTime to get this effect. The detailed specification is in javax.management.monitor.

  • 6239455: Specify that monitor tasks are run within the access control context of the monitor.start() caller. When security is active, the security checks carried out to see if the caller has access to the attribute or to any security protected operation the attribute implementation might perform are based on the access control context of the monitor.start() caller and not on the access control context of the monitor creator. This is stated in the package documentation for javax.management.monitor.

Timer Service

The following changes are made to the specification of the Timer Service (package javax.management.timer).

  • 6235077: javax.management.timer.Timer doc was inconsistent about what happens for Date in the past. Prior to version 1.2 of the JMX Specification, the Timer service was defined to throw an exception if a notification was scheduled for a time in the past. Starting from version 1.2, the more logical behaviour of sending the notification immediately in this case was introduced. However, some of the documentation for javax.management.timer.Timer still reflected the old behaviour. In particular, the Notes in the class documentation included one that said that past-time notifications will be ignored, and the @throws documentation for the IllegalArgumentException said it was thrown for a past date.

  • 6387340: Remove javax.management.timer.TimerAlarmClockNotification. This class is unusable by code outside the package it is defined in, because its only visible constructor has a parameter whose type is a non-public class. If you call that constructor with a null parameter, you get an immediate exception. Therefore, exceptionally, this public class can safely be deleted from the Java SE API.

MLet Service

The following changes are made to the specification of the MLet Service (package javax.management.loading).

  • 4796780: MLetContent class should be public. In the last release, the MLet.check method was made public, but one of its parameters was of type javax.management.loading.MLetContent, and that class remained private. This introduced an inconsistency in that a publicly-visible method referenced a non-visible class. This has been corrected by making MLetContent public.

  • 6223396: MLet support for native libraries is underspecified and should be optional. The specification of MLet.findLibrary has been updated to detail the algorithm used to find native libraries inside jar files, and to add a @throws clause for implementations that do not support this functionality. The PDF specification has been updated similarly (section 8.3.2).

Relation Service

The following changes are made to the specification of the Relation Service (package javax.management.relation).

  • 4892674: Problem serializing RelationNotification. The RelationNotification constructors required their source parameter to be an instance of RelationService, relying on the MBean Server to rewrite this to the ObjectName of the RelationService before forwarding the notification to users. This is fragile, and in particular makes it hard to reconstruct a RelationNotification instance, for example from a serialized XML form. The constructor is modified to also allow the source to be an ObjectName.

  • 5053367: RelationService.addRelationType spec rejects null relation type name. RelationService.addRelationType (and RelationServiceMBean.addRelationType) are explicitly specified to throw IllegalArgumentException if the RelationType argument returns null from its getRelationTypeName(). RelationService.addRelationType (and RelationServiceMBean.addRelationType) are explicitly specified to throw IllegalArgumentException if the RelationType argument returns null from its getRelationTypeName(). The other RelationService methods that take a relation type name are all specified to reject a null name. Thus if addRelationType allowed one, you would end up with a RelationType that you could do nothing with. In particular, you couldn't even remove it again.

  • 6229880: RelationSupport javadoc was unclear. RelationSupport.setRole specified that a RoleNotFoundException is thrown if the role is not writable. In fact, a RoleNotFoundException is also thrown when there is no defined role for the given name (same condition as the getRole method).

    RelationSupport.setRoles specified that an IllegalArgumentException was thrown if the role name was null. This should be the role list.

Query

The new javax.managent.Query.isInstanceOf(StringValueExp className) method allows users to get all MBeans that are instances of a specific class (5072174).

MBeanServerInvocationHandler

The following changes are made to the specification of MBeanServerInvocationHandler:

  • 6177524: MBeanServerInvocationHandler no longer forwards Object methods to proxied MBean. Previously, MBeanServerInvocationHandler forwarded the methods hashCode(), toString(), and equals(Object) to proxied MBeans, meaning that an MBean proxy could not be used as a key in a HashMap (for example to look up a cached MBeanInfo for the proxy). MBeanServerInvocationHandler now only forwards these methods if they are explicitly mentioned in the MBean interface for which it is a handler. The javax.management.MBeanServerInvocationHandler.invoke method has been updated to examine the MBean interface to check whether it contains the methods in question.

  • 6278707: MBeanServerInvocationHandler acquires getters to retrieve its constructor parameters. These are the new methods getMBeanServerConnection(), getObjectName(), and isMXBean().

A new method JMX.newMBeanProxy provides an easier-to-remember alternative to MBeanServerInvocationHandler.newProxyInstance.

Serial forms

The specification of the serial form of the classes in the JMX API has been clarified as follows.

  • 6253903: Specification for JMX API lists serialVersionUID of all serializable classes. For implementation reasons, the Serialized Form page from the Javadoc-generated specification omits the serialVersionUID of certain classes. Independent implementations need this information for compliance, so where necessary it has been supplied in the specification of the classes themselves.

  • 6344759: Mandate more clearly the 12 javax.management.*Exp private classes. For interoperation between implementations, the value returned by the various static Query.* methods (such as Query.and) must be of a given non-public class, or at least must serialize as such. The specification of these methods is updated accordingly.

Permission checks

The JMX specification previously said that permission checks were made if and only if there is a non-null SecurityManager. This has been changed to say that an implementation is free not to make checks if there is no SecurityManager. In other words, an implementation may now choose to make checks even in the absence of a SecurityManager. (6419572)

MBean RuntimeException handling

The JMX spec was unclear as to what happens when a method implementing an attribute or an operation in an MBean throws a RuntimeException (5043152). Close reading implied that it should wrap the exception in a RuntimeMBeanException, but it was not completely clear that it could not wrap it in a RuntimeOperationsException. The spec now explicitly says that it is a RuntimeMBeanException, and that RuntimeOperationsException wraps exceptions that occur before any MBean method is invoked, e.g. getAttribute with a null attribute.

Model MBeans wrap exceptions coming from methods invoked on the ManagedResource in RuntimeOperationsException, not RuntimeMBeanException.
Although this was not clearly specified, changing it would risk breaking existing code. So the existing behaviour is specified explicitly, and also that when an MBean throws a RuntimeOperationsException it is not further wrapped.

JMX Remote API

The following changes are made to the specification of the JMX Remote API.

  • 6343209: Specify how SubjectDelegationPermission works for ConnectorServer creators. The creator of a JMXConnectorServer no longer needs to have all the permissions that connection created by the connector server will use. It can have a SubjectDelegationPermission for each remotely-authenticated identity instead. This simplifies deployment in security-conscious environments.

  • 5021246: Spec for RMI connector should say code downloading used if applicable. The RMI connector will use code downloading as specified in the article Dynamic code downloading using Java RMI if applicable. The Reference Implementation has always behaved this way, and the specification has been updated to reflect that.

  • 6375696: CORBA tie classes for JMX Remote API should be in javax.management.remote.rmi For compliance with the OMG's "IDL to Java Language Mapping Specification", the CORBA "tie classes" for the remote objects javax.management.remote.rmi.RMIServerImpl and javax.management.remote.rmi.RMIConnectionImpl should be in the javax.management.remote.rmi package.

  • 6231888: JMXConnector implements Closeable The interface java.io.Closeable defines the single method
    public void close() throws IOException; and since JMXConnector contains a method with the same signature, the JMXConnector interface can extend the Closeable interface.

  • 6234398: JMX connection provider API exception handling unclear. The interfaces JMXConnectorProvider and JMXConnectorServerProvider are clarified so that methods throw MalformedURLException if the protocol in the URL is not recognized by the provider, JMXProviderException if this is the right provider for the URL but it cannot be used for some reason, and some other IOException in other cases.

  • 6238076: Serialized form of javax.management.remote.rmi.RMIConnector included clientNotifID field. This field was inadvertently included in the serial form. Its purpose is to track the notification sequence number in JMXConnectionNotifications from the RMIConnector. An RMIConnector is typically only serialized if it is the value returned by RMIConnectorServer.toJMXConnector, in which case it will not have been connected and will have a sequence number of 0. Even if an RMIConnector is serialized in other circumstances, there is little or no interest in continuing the notification sequence numbers when it is subsequently deserialized.

  • 6238815: Add a way to get the address to which a connector client is connected. The new interface JMXAddressable can be implemented by a given connector client. When this is so, users can cast the JMXConnector instance to JMXAddressable and call getAddress() to discover the address to which the client is connected. RMI client connectors are specified to implement this interface. The JMXConnectorServer class also implements this interface, via its existing getAddress() method.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun


Java Management Extensions API Specification

Java (tm)

JavaTM Management Extensions (JMXTM)
API Specification

 JMX Contents
The Java Management Extensions (JMX) API is a standard API for management and monitoring.

The following packages of documentation generated by the Javadoc utility are provided for the JMX API:

  • javax.management
  • javax.management.loading
  • javax.management.modelmbean
  • javax.management.monitor
  • javax.management.openmbean
  • javax.management.relation
  • javax.management.remote
  • javax.management.remote.rmi
  • javax.management.timer
Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun


Java Management Extensions Examples

Java (tm)

Java Management Extensions (JMX) Examples

 Documentation Contents

The files listed below are code examples demonstrating some of the main features of JMX technology. You can use these examples to develop more complex MBeans and full-featured JMX agents to fit your management solution.

Each example consists of Java source files and a README file. The README file explains the topics covered by the example and instructions for compiling and running the classes.

You can also download a Zip file of all the JMX technology examples. For more complete descriptions of how to run the examples, see the JMX Technology Tutorial.

Note - In addition to the examples presented here, once you have installed the Java Development Kit (JDK) 6, a sample application that demonstrates a real-life implementation of the JMX API can be found in the following directory:

JDK_HOME/sample/jmx/jmx-scandir

In the path above, JDK_HOME is the directory in which the JDK software is installed. The jmx-scandir example is an advanced example, which presents advanced concepts of the JMX API in a real-world scenario.

The following JMX technology examples are provided in the examples ZIP file:

JMX Essentials

This example introduces the fundamental notion of the JMX API, namely managed beans, or MBeans.

View the README file or the source code for the Java classes used:

  • Hello
  • HelloMBean
  • Main
JMX MBean Notifications

This example implements MBean notifications.

View the README file or the source code for the Java classes used:

  • Hello
  • HelloMBean
  • Main
MXBeans

This example demonstrates the use of MXBeans.

View the README file or the source code for the Java classes used:

  • Main
  • QueueSample
  • QueueSampler
  • QueueSamplerMXBean
MBean Descriptors

This example demonstrates the use of MBean Descriptors.

View the README file or the source code for the Java classes used:

  • Author
  • DisplayName
  • Main
  • QueueSample
  • QueueSampler
  • QueueSamplerMXBean
  • Version
JMX Connectors

This example provides a sample implementation of how to connect to MBeans and perform operations on them remotely.

View the README file or the source code for the Java classes used:

  • Server
  • SimpleStandardMBean
  • SimpleStandard
  • SimpleDynamic
  • ClientListener
  • Client
Lookup Services

The JMX API defines three bindings to lookup services, using existing lookup technologies These examples provide a sample implementation of each type of lookup service.

  • Service Location Protocol (SLP) Lookup Service
    View the README file or the source code for the Java classes used:
    • Server
    • Client
  • Jini Lookup Service.
    View the README file or the source code for the Java classes used:
    • Server
    • Client
    • java.policy
    • jini.properties.template
  • Java Naming and Directory Interface (JNDI)/LDAP Lookup Service
    View the README file or the source code for the Java classes used:
    • Server
    • Client
    • jmx-schema.txt
    • 60jmx-schema.ldif
Security

The JMX API implements existing security protocols to secure your connections.

These examples provide a sample secure implementations

  • Simple Security
    View the README file or the source code for the Java classes used:
    • Server
    • Client
    • ClientListener
    • access.properties
    • keystore
    • password.properties
    • truststore
    • SimpleStandard
    • SimpleStandardMBean
  • Security with Subject Delegation
    View the README file or the source code for the Java classes used:
    • Server
    • Client
    • ClientListener
    • access.properties
    • password.properties
    • java.policy
    • SimpleStandard
    • SimpleStandardMBean
  • Fine-Grained Security
    View the README file or the source code for the Java classes used:
    • Server
    • Client
    • ClientListener
    • keystore
    • password.properties
    • truststore
    • java.policy
    • SimpleStandard
    • SimpleStandardMBean
Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun

Java Software


Contents | Previous | Next Java Management Extensions (JMX) Technology Overview

Appendix A

JMX Technology Versions

The JMX technology included in the Java 2 Platform Standard Edition (J2SE) was developed through the Java Community Process (JCP) as two closely related Java Specification Requests (JSRs). The versions of the JSRs implemented in the J2SE platform, version 5.0, are detailed in the following sections.

Java Management Extensions (JMX) Instrumentation and Agent Specification (JSR 3)

The Java SE 6 platform implements version 1.4 of the JMX Specification (Maintenance Release, October 2006). It incorporates the modifications listed in the errata provided with the download.

JMX Remote API Specification (JSR 160)

The Java SE 6 platform implements version 1.4 of the JMX Remote API Specification (Maintenance Release, October 2006).

In addition to standard RMI and RMI/IIOP connectors, JSR 160 also defines optional JMX Messaging Protocol (JMXMP) connectors based on TCP sockets. The Java SE platform does not include these optional connectors. However, you might want to use JMXMP connectors if, for example, you require a more advanced level of security.

If you want to use a JMXMP connector, download the JSR 160 Reference Implementation from the download page specified at the beginning of this section, and add the jmxremote_optional.jar file to your classpath. You will find examples of use of JMXMP connectors in the JMX Remote API Tutorial included with the JSR 160 Reference Implementation.

Contents | Previous | Next Java Management Extensions (JMX) Technology Overview
Java Management Extensions (JMX), Java Platform, Standard Edition 6

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.


Java Management Extensions (JMX) Technology Overview

Java Management Extensions (JMX)
Java Platform, Standard Edition 6

October, 2006
Contents | Previous | Next

Contents

Preface

1. Introduction to JMX Technology

What Is JMX Technology?

Why Use JMX Technology?

2. JMX Architecture

Architecture Outline

Instrumenting Resources Using MBeans

Creating a JMX Agent

Managing Resources Remotely

3. Instrumenting Your Resources for JMX Technology

Manageable Resources

Managed Beans (MBeans)

Java Virtual Machine Instrumentation

4. Using JMX Agents

MBean Server

Agent Services

Protocol Adaptors and Connectors

Protocol Adaptors

Connectors

5. Using JMX Connectors to Manage Resources Remotely

RMI Connector

Generic Connector

User-Defined Protocols

6. Discovery and Lookup Services

Getting Started With Lookup Services

Using the Service Location Protocol (SLP)

Using the Jini Network Technology

Using the Java Naming and Directory Interface (JNDI) API With an LDAP Backend

A. JMX Technology Versions

Java Management Extensions (JMX) Instrumentation and Agent Specification (JSR 3)

JMX Remote API Specification (JSR 160)

Contents | Previous | Next

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.


Contents | Previous | Next Java Management Extensions (JMX) Technology Overview

Chapter 6

Discovery and Lookup Services

The Java Management Extensions (JMX) Remote API Specification describes how you can advertise and find JMX API agents by using existing discovery and lookup infrastructures. The specification does not define any discovery and lookup APIs specific to JMX technology.

This chapter provides a brief outline of existing discovery and lookup infrastructures that you can use with JMX technology, in the following sections:

  • "Getting Started With Lookup Services"
  • "Using the Service Location Protocol (SLP)"
  • "Using the Jini Network Technology"
  • "Using the Java Naming and Directory Interface (JNDI) API With an LDAP Backend"

For more information about these infrastructures, see the “References” section of the Java Management Extensions Remote API 1.0 Specification.

Getting Started With Lookup Services

Lookup services can be used by JMX agents and JMX clients. A single Java VM can contain many JMX agents and/or JMX clients.

  • A JMX agent is a logical server application composed of the following features:
    • One MBean server
    • One or more JMX connector servers that allow remote clients to access the MBeans contained in that MBean server
  • A JMX client is a logical client application that opens a client connection with a JMX agent.

The Java Management Extensions (JMX) Technology Tutorial and its accompanying examples demonstrate how to use lookup services to advertise and find JMX agents. The procedure is similar for all three infrastructures. The main difference is that in SLP and JNDI, the agent registers addresses with the lookup service, whereas when using the Jini network technology, the agent registers a JMX connector stub with the lookup service.

Note – The use of existing discovery and lookup services is optional. Alternatively, you can encode the addresses of your JMX API agents in the form of URLs, and communicate these URLs to the manager.

Using the Service Location Protocol (SLP)

The Service Location Protocol (SLP) provides a framework that allows networking applications to discover the existence, location, and configuration of networked services in enterprise networks.

The following steps summarize the procedure defined in the JMX Remote API specification for using the SLP lookup service to advertise and find JMX agents:

  1. The agent creates one or more JMX connector servers.
  2. For each connector to expose, the agent registers the address with the SLP lookup service, possibly giving additional attributes that qualify the agent and/or the connector, and can be used as filters.
  3. The client queries the SLP lookup service, and retrieves one or more addresses that match the query.
  4. Finally, the client obtains a connector that is connected with the server identified by a retrieved address.

The JMX Remote API specification defines URL schemes which are compliant with the SLP protocol. See the Java Management Extensions (JMX) Remote API Specification. The specification also defines mandatory and optional SLP lookup attributes that are provided at registration time.

Using the Jini Network Technology

The JiniTM Network Technology is an open software architecture that enables developers to create services that are adaptable to changes in the network. The Jini specification offers a standard lookup service. A running Jini lookup service can be discovered with a simple API call.

The following steps summarize the procedure defined in the JMX Remote API specification for using the Jini lookup service to advertise and find JMX agents:

  1. The agent creates one or more JMX connector servers.
  2. For each connector to expose, the agent registers a JMX connector stub with the Jini lookup service, possibly giving additional attributes that qualify the agent and/or the connector, and can be used as filters.
  3. The client queries the Jini lookup service, and retrieves one or more connector stubs that match the query.
  4. Finally, the client connects directly to the server using the provided connector stub.

The JMX Remote API specification defines bindings with Jini technology based entries. See the Java Management Extensions (JMX) Remote API Specification. The specification also defines mandatory and optional entries to specify when registering an agent connector.

Using the Java Naming and Directory Interface (JNDI) API With an LDAP Backend

The Java Naming and Directory InterfaceTM (JNDI) API is a standard extension to the Java platform. It provides Java technology-enabled applications with a unified interface to a number of naming and directory services.

The JMX Remote API specification details how an LDAP server can be used to store and retrieve information about JMX connectors exposed by JMX agents.

The following steps summarize the procedure defined in the JMX Remote API specification for using the JNDI lookup service:

  1. The agent creates one or more JMX connector servers.
  2. For each connector to expose, the agent registers the address with the JNDI lookup service, possibly giving additional attributes that qualify the agent and/or the connector, and can be used as filters.
  3. The client queries the JNDI lookup service, and retrieves one or more addresses that match the query.
  4. Finally, the client obtains a connector that is connected to the server identified by a retrieved address.

The JMX Remote API defines an LDAP schema for registering addresses and explains how a client can discover a registered agent. See the JMX 1.4 Specification for details. The specification also defines a lease mechanism.

Contents | Previous | Next Java Management Extensions (JMX) Technology Overview
Java Management Extensions (JMX), Java Platform, Standard Edition 6

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.


Contents | Previous | Next Java Management Extensions (JMX) Technology Overview

Chapter 3

Instrumenting Your Resources for JMX Technology

This chapter outlines the concepts behind instrumenting resources for management using JMX technology, in the following sections:

  • "Manageable Resources"
  • "Managed Beans (MBeans)"
  • "Java Virtual Machine Instrumentation"

Manageable Resources

Different types of resource can be managed using JMX technology, for example an application, an implementation of a service, a device or a user. For a given resource to be managed by JMX technology, it must be developed in the Java language, or at least offer a Java language wrapper. It must also be instrumented by one or more Java objects known as managed beans (MBeans), in compliance with the JMX specification.

Developers of applications and devices are free to choose the granularity of objects that are instrumented as MBeans. An MBean might represent the smallest object in an application, or it could represent the entire application. Application components designed with their management interface in mind can typically be written as MBeans. MBeans can also be used as wrappers for legacy code without a management interface or as proxies for code with a legacy management interface.

Managed Beans (MBeans)

The Java objects that implement resources and their instrumentation are called managed beans, or MBeans. MBeans must follow the design patterns and interfaces defined in the JMX specification (JSR 3). This ensures that all MBeans provide the instrumentation of managed resources in a standardized way.

The instrumentation of a given resource is provided by one or more MBeans that are either standard or dynamic. Standard MBeans are Java objects that conform to certain design patterns derived from the JavaBeansTM component model. Dynamic MBeans conform to a specific interface that offers more flexibility at runtime. MXBeans reference only a pre-defined set of types.

The instrumentation of a resource allows it to be manageable through the agent level described in Chapter 4, "Using JMX Agents". MBeans do not require knowledge of the JMX agent with which they operate.

MBeans are designed to be flexible, simple, and easy to implement. Developers of applications, services, or devices can make their products manageable in a standard way without having to understand or invest in complex management systems. Existing objects can easily be evolved to produce standard MBeans or wrapped as dynamic MBeans, thus making existing resources manageable with minimum effort.

In addition, the instrumentation level also specifies a notification mechanism. This allows MBeans to generate and propagate notification events to components of the other levels.

The management interface of an MBean consists of:

  • Named and typed attributes that can be read and/or written
  • Named and typed operations that can be invoked
  • Typed notifications that can be emitted by the MBean

The Java class of a standard MBean exposes the resource to be managed directly through its attributes and operations. Attributes are internal entities that are exposed through getter and setter methods. Operations are the other methods of the class that are available to managers. All these methods are defined statically in the MBean interface and are visible to a JMX agent through introspection. This is the most straightforward way of making a new resource manageable.

A dynamic MBean is an MBean that defines its management interface at runtime. For example, a configuration MBean could determine the names and types of the attributes it exposes by parsing an XML file.

An MXBean is a new type of MBean that provides a simple way to code an MBean that only references a pre-defined set of types. In this way, you can be sure that your MBean will be usable by any client, including remote clients, without any requirement that the client have access to model-specific classes representing the types of your MBeans.

Java Virtual Machine Instrumentation

The Java Virtual Machine (Java VM) is highly instrumented using JMX technology. You can easily start a JMX agent to access the built-in Java VM instrumentation, and thereby monitor and manage the Java VM remotely by means of JMX technology.

To find out more about using JMX technology to monitor and manage the Java VM, see the Java SE Monitoring and Management Guide.

Contents | Previous | Next Java Management Extensions (JMX) Technology Overview
Java Management Extensions (JMX), Java Platform, Standard Edition 6

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.


Contents | Previous | Next Java Management Extensions (JMX) Technology Overview

Chapter 1

Introduction to JMX Technology

Java Management Extensions Technology became a standard part of the Java platform in the Java 2 Platform, Standard Edition (J2SE) 5.0. If you are already familiar with JMX technology, see Appendix A, "JMX Technology Versions" for version information.

JMX technology provides a simple, standard way of managing resources such as applications, devices, and services. Because JMX technology is dynamic, you can use it to monitor and manage resources as they are created, installed and implemented. You can also use JMX technology to monitor and manage the Java Virtual Machine1 (Java VM).

JMX technology was developed through the Java Community Process (JCP) as two closely related Java Specification Requests (JSRs):

  • JSR 3, Java Management Extensions Instrumentation and Agent Specification
  • JSR 160, Java Management Extensions Remote API

Each of the JSRs is defined by the API documentation generated by the Javadoc tool, in conjunction with the PDF specification documents for each JSR. The Specifications and Reference Implementations can be downloaded at:

http://java.sun.com/products/JavaManagement/download.html

As its name indicates, the JMX Remote API adds remote capabilities to the JMX specification, allowing you to monitor and manage applications, systems and networks remotely. In this document, the term “JMX technology” is used to cover both the JMX specification and the JMX Remote API.

This chapter introduces JMX technology in the following sections:

  • "What Is JMX Technology?"
  • "Why Use JMX Technology?"

What Is JMX Technology?

The JMX specification defines an architecture, the design patterns, the APIs, and the services for application and network management and monitoring in the Java programming language.

Using JMX technology, a given resource is instrumented by one or more Java objects known as Managed Beans, or MBeans. These MBeans are registered in a core managed object server, known as an MBean server, that acts as a management agent and can run on most devices enabled for the Java programming language.

The specifications define JMX agents that you use to manage resources instrumented in compliance with the specifications. A JMX agent consists of an MBean server, in which MBeans are registered, and a set of services for handling MBeans. In this way, JMX agents directly control resources and make them available to remote management applications.

The way in which resources are instrumented is completely independent from the management infrastructure. Resources can therefore be rendered manageable regardless of how their management applications are implemented.

JMX technology defines standard connectors (JMX connectors) that allow you to access JMX agents from remote management applications. JMX connectors using different protocols provide the same management interface. Hence a management application can manage resources transparently, regardless of the communication protocol used. JMX agents can also be used by systems or applications that are not compliant with the JMX specification but which support JMX agents.

Why Use JMX Technology?

JMX technology provides Java developers across all industries with a flexible means to instrument Java code, create smart Java agents, implement distributed management middleware and managers, and smoothly integrate these solutions into existing management and monitoring systems.

  • JMX technology enables Java applications to be managed without heavy investment: A JMX technology agent can run on most Java technology-enabled devices, thus Java applications can become manageable with little impact on their design. A Java application simply needs to embed a managed object server and make some of its functionality available as one or several managed beans (MBeans) registered in the object server; that is all it takes to benefit from the management infrastructure.
  • JMX technology provides a standard way to manage Java technology-based applications, systems, and networks. For example, the Java Platform, Enterprise Edition (Java EE) 5 Application Server conforms to the JMX architecture and consequently can be managed using JMX technology.
  • JMX technology can be used for out-of-the-box management of the Java VM. The Java Virtual Machine (Java VM) is highly instrumented using JMX technology. You can easily start a JMX agent to access the built-in Java VM instrumentation, and thereby monitor and manage the Java VM remotely.
  • JMX technology provides a scalable, dynamic management architecture. Every JMX agent service is an independent module that can be plugged into the management agent, depending on the requirements. This component-based approach means that JMX solutions can scale from small-footprint devices to large telecommunications switches and beyond. The JMX specification provides a set of core agent services. Additional services can be developed and dynamically loaded, unloaded, or updated in the management infrastructure.
  • JMX technology leverages existing standard Java technologies. Whenever needed, the JMX specification references existing Java specifications, for example, the Java Naming and Directory Interface (JNDI).
  • Creating JMX applications has been made easier by the creation of a JMX module for the NetBeans IDE 5.0. You can obtain the JMX module from the NetBeans Update Center.
  • JMX technology integrates easily with existing management solutions and emerging technologies. For example, JMX agents could be managed through an HTML browser. The JMX APIs are open interfaces that any management system vendor can leverage. JMX solutions can use lookup and discovery services and protocols such as JiniTM network technology and the Service Location Protocol (SLP).
1The terms “Java Virtual Machine” and “Java VM” mean a virtual machine for the Java platform.

Contents | Previous | Next Java Management Extensions (JMX) Technology Overview
Java Management Extensions (JMX), Java Platform, Standard Edition 6

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.


Contents | Previous | Next Java Management Extensions (JMX) Technology Overview

Chapter 2

JMX Architecture

JMX technology provides a standard API for management and monitoring of resources. The API includes remote access, so a remote management application can manage and monitor applications, systems, and networks. This chapter outlines JMX architecture in the following sections:

  • "Architecture Outline"
  • "Instrumenting Resources Using MBeans"
  • "Creating a JMX Agent"
  • "Managing Resources Remotely"

Architecture Outline

JMX technology is defined by two closely related specifications developed through the Java Community Process (JCP) as Java Specification Request (JSR) 3 and JSR 160:

  • JSR 3, Java Management Extensions Instrumentation and Agent Specification
  • JSR 160, Java Management Extensions Remote API

The following table shows that the management architecture can be broken down into three levels. The first two levels shown in the table, instrumentation and agent,

Java VM are defined by JSR 3. The remote management level is defined by JSR 160.

TABLE 2-1 – JMX Technology Architecture
Level | Description
Instrumentation | Resources, such as applications, devices, or services, are instrumented using Java objects called Managed Beans (MBeans). MBeans expose their management interfaces, composed of attributes and operations, through a JMX agent for remote management and monitoring.
Agent | The main component of a JMX agent is the MBean server. This is a core managed object server in which MBeans are registered. A JMX agent also includes a set of services for handling MBeans. JMX agents directly control resources and make them available to remote management agents.
Remote Management | Protocol adaptors and standard connectors make a JMX agent accessible from remote management applications outside the agent’s Java Virtual Machine (Java VM).

Instrumenting Resources Using MBeans

To manage resources using JMX technology, you must first instrument the resources in the Java programming language. You use Java objects known as MBeans to implement the access to the instrumentation of resources. MBeans must follow the design patterns and interfaces defined in the specification. This ensures that all MBeans provide the instrumentation of managed resources in a standardized way.

Once a resource has been instrumented by MBeans, it can be managed through a JMX agent. MBeans do not require knowledge of the JMX agent with which they will operate.

MBeans are designed to be flexible, simple, and easy to implement. Developers of applications, systems, and networks can make their products manageable in a standard way without having to understand or invest in complex management systems. Existing resources can be made manageable with minimum effort.

In addition, the instrumentation level specifies a notification mechanism. This allows MBeans to generate and propagate notification events to components of the other levels.

Creating a JMX Agent

A JMX agent is a standard management agent that directly controls resources and makes them available to remote management applications. JMX agents are usually located on the same machine as the resources they control, but this is not a requirement.

The core component of a JMX agent is the MBean server, a managed object server in which MBeans are registered. A JMX agent also includes a set of services to manage MBeans, and at least one communications adaptor or connector to allow access by a management application.

When you implement a JMX agent, you do not need to know the semantics or functions of the resources that it will be used to manage. In fact, a JMX agent does not even need to know which resources it will serve, because any resource instrumented in compliance with the JMX specification can use any JMX agent that offers the services it requires. Similarly, the agent does not need to know the functions of the management applications that will access it.

Managing Resources Remotely

JMX API instrumentation can be accessed in many different ways, either through existing management protocols such as the Simple Network Management Protocol (SNMP), or through proprietary protocols. The MBean server relies on protocol adaptors and connectors to make a JMX agent accessible from management applications outside the agent’s Java Virtual Machine (Java VM).

Each adaptor provides a view through a specific protocol of all MBeans registered in the MBean server. For example, an HTML adaptor could display an MBean in a Web browser.

Connectors provide a manager-side interface that handles the communication between manager and JMX agent. Each connector provides the same remote management interface though a different protocol. When a remote management application uses this interface, it can connect to a JMX agent transparently through the network, regardless of the protocol.

JMX technology provides a standard solution for exporting JMX API instrumentation to remote applications, based on Remote Method Invocation (RMI). In addition, the JMX Remote API defines an optional protocol based directly on TCP sockets, called the JMX Messaging Protocol (JMXMP). An implementation of the JMX Remote API does not have to support this optional protocol. The Java SE platform does not include the optional protocol. See Appendix A, "JMX Technology Versions" for further information.

The JMX Remote API specification describes how you can advertise and find JMX agents using existing discovery and lookup infrastructures. Examples of how to do this are provided and are described in the Java Management Extensions (JMX) Technology Tutorial. The specification does not define its own discovery and lookup service. The use of existing discovery and lookup services is optional: alternatively you can encode the addresses of your JMX API agents in the form of URLs, and communicate these URLs to the manager.

Contents | Previous | Next Java Management Extensions (JMX) Technology Overview
Java Management Extensions (JMX), Java Platform, Standard Edition 6

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.


Preface

The Java Management Extensions (JMX) Technology Overview provides an introduction to JMX technology.

Before You Read This Book

To make full use of the information in the Java Management Extensions (JMX) Technology Overview, you should have knowledge of the following technology:

  • The Java programming language and its development environment
  • The Java Platform, Standard Edition (Java SE) software

Some sections of this overview refer to the following protocols and specifications. You might want to investigate these areas further to gain a deeper insight into JMX technology:

  • The JavaBeans model
  • Remote Method Invocation (RMI)
  • Lightweight Directory Access Protocol (LDAP)
  • Service Location Protocol (SLP)
  • Jini Network Technology
  • Java Naming and Directory Interface (JNDI) API
  • Java Secure Socket Extension (JSSE)
  • Java Authentication and Authorization Service (JAAS)
  • Simple Authentication and Security Layer (SASL)

How This Book Is Organized

This document describes the JMX technology in the following chapters:

  • Chapter 1, "Introduction to JMX Technology" provides a brief outline of the JMX technology and indicates its main advantages and features.
  • Chapter 2, "JMX Architecture"
  • Chapter 3, "Instrumenting Your Resources for JMX Technology"
  • Chapter 4, "Using JMX Agents"
  • Chapter 5, "Using JMX Connectors to Manage Resources Remotely" describes the required connector defined by the JMX technology specification. It also outlines an optional generic connector. This chapter includes information on connector security features.
  • Chapter 6, "Discovery and Lookup Services" describes briefly how to use existing discovery and lookup services with the JMX technology
  • Appendix A, "JMX Technology Versions" defines the versions of the Java Specification Requests (JSRs) relating to JMX technology implemented in this version of the Java SE platform.

Typographic Conventions

Typeface | Meaning | Examples
AaBbCc123 | The names of commands, files, and directories; on-screen computer output | Edit your .login file. Use ls -a to list all files. % You have mail.
AaBbCc123 | What you type, when contrasted with on-screen computer output | % su Password:
AaBbCc123 | Book titles, new words or terms, words to be emphasized Command-line variable; replace with a real name or value | Read Chapter 6 in the User’s Guide. These are called class options. You must be superuser to do this. To delete a file, type rm filename.

Shell Prompts

Shell | Prompt
C shell | machine_name%
C shell superuser | machine_name#
Bourne shell and Korn shell | $
Bourne shell and Korn shell superuser | #

Related Documentation

  • Java Management Extensions Specification 1.4
  • Java Management Extensions Technology Tutorial

Sun Welcomes Your Comments

We are interested in improving our documentation and welcome your comments and suggestions. You can email your comments to us via the Sun Developer Network feedback page .

Accessing Sun Documentation Online

You can access Sun Documentation at the following location.

  • http://www.sun.com/documentation.

    • Contents | Previous | Next Java Management Extensions (JMX) Technology Overview
    Java Management Extensions (JMX), Java Platform, Standard Edition 6

    Copyright © 2006 Sun Microsystems, Inc. All rights reserved.


Contents | Previous | Next Java Management Extensions (JMX) Technology Overview

Chapter 4

Using JMX Agents

A Java Management Extensions (JMX) agent is a management entity that runs in a Java Virtual Machine (Java VM) and acts as the liaison between the MBeans and the management application. The various components of a JMX agent are outlined in the following sections:

  • "MBean Server"
  • "Agent Services"
  • "Protocol Adaptors and Connectors"

MBean Server

The MBean server is the core component of a JMX agent. It is a registry for objects that are exposed to management operations in an agent. Any object registered with the MBean server becomes visible to management applications. However, the MBean server only exposes the management interface of an MBean, never its direct object reference.

Any resource that you want to manage from outside the agent’s Java VM must be registered as an MBean in the server. The MBean server also provides a standardized interface for accessing MBeans within the same Java VM, giving local objects all the benefits of manipulating manageable resources. MBeans can be instantiated and registered by:

  • Another MBean
  • The agent itself
  • A remote management application

When you register an MBean, you must assign it a unique object name. A management application uses the object name to identify the object on which it is to perform a management operation. The operations available on MBeans include:

  • Discovering the management interface of MBeans
  • Reading and writing their attribute values
  • Performing operations defined by the MBeans
  • Getting notifications emitted by MBeans
  • Querying MBeans based on their object name or their attribute values

Agent Services

Agent services are objects that can perform management operations on the MBeans registered in the MBean server. By including management intelligence into the agent, JMX helps you build more powerful management solutions. Agent services are often MBeans as well, allowing them and their functionality to be controlled through the MBean server. The JMX specification defines the following agent services:

  • Dynamic class loading through the management applet (m-let) service retrieves and instantiates new classes and native libraries dynamically downloaded from the network.
  • Monitors observe the numerical or string value of MBean attributes and can notify other objects of several types of changes.
  • Timers provide a scheduling mechanism and can send notifications at predetermined intervals.
  • The relation service defines associations between MBeans and maintains the consistency of the relation.

Protocol Adaptors and Connectors

Protocol adaptors and connectors make the agent accessible from remote management applications. They provide a view through a specific protocol of the MBeans instantiated and registered in the MBean server. They enable a management application outside the Java VM to:

  • Get or set attributes of existing MBeans
  • Perform operations on existing MBeans
  • Instantiate and register new MBeans
  • Register for and receive notifications emitted by MBeans

Consequently, for a JMX agent to be manageable, it must include at least one protocol adaptor or connector. The Java SE platform includes the standard RMI connector. An agent can include any number of protocol adaptors and connectors, allowing it to be managed and monitored remotely through different protocols simultaneously.

Protocol Adaptors

Protocol adaptors provide a management view of the JMX agent through a given protocol. They adapt the operations of MBeans and the MBean server into a representation in the given protocol, and possibly into a different information model, for example SNMP. The Java SE platform does not include any protocol adaptors as standard.

Management applications that connect to a protocol adaptor are usually specific to the given protocol. This is typically the case for legacy management solutions that rely on a specific management protocol. They access the JMX agent not through a remote representation of the MBean server, but through operations that are mapped to those of the MBean server.

Connectors

Connectors are used to connect an agent with a remote management application enabled for JMX technology, namely, a management application developed using the distributed services of the JMX specification. This kind of communication involves a connector server in the agent and a connector client in the manager.

These components convey management operations transparently point-to-point over a specific protocol. The JMX Remote API provides a remote interface to the MBean server through which the management application can perform operations. A connector is specific to a given protocol, but the management application can use any connector indifferently because they have the same remote interface.

See Chapter 5, "Using JMX Connectors to Manage Resources Remotely" for more information on standard JMX connectors.

Contents | Previous | Next Java Management Extensions (JMX) Technology Overview
Java Management Extensions (JMX), Java Platform, Standard Edition 6

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.


Contents | Previous | Next Java Management Extensions (JMX) Technology Overview

Chapter 5

Using JMX Connectors to Manage Resources Remotely

The Java Management Extensions Instrument and Agent Specification defines the concept of connectors. A connector makes a Java Management Extensions (JMX) technology MBean server accessible to remote Java technology-based clients. The client end of a connector exports essentially the same interface as the MBean server.

A connector consists of a connector client and a connector server. A connector server is attached to an MBean server and listens for connection requests from clients. A connector client is responsible for establishing a connection with the connector server. A connector client will usually be in a different Java Virtual Machine (Java VM) from the connector server, and will often be running on a different machine.

Many different implementations of connectors are possible. In particular, there are many possibilities for the protocol used to communicate over a connection between client and server.

A connector server usually has an address, used to establish connections between connector clients and the connector server. Alternatively, some connectors can provide connection stubs to establish connections. The way in which connections are established depends on the discovery and lookup technology that you use (see Chapter 6, "Discovery and Lookup Services").

This chapter outlines the different types of connector defined by the JMX Remote API specification and the protocols they use, in the following sections:

  • "RMI Connector": This standard Remote Method Invocation (RMI) protocol must be supported by every implementation that conforms to the JMX Remote API standard.
  • "Generic Connector": The JMX Remote API standard also defines an optional protocol based directly on TCP sockets, called the JMX Messaging Protocol (JMXMP). An implementation of the standard can omit the JMXMP connector, but must not omit the RMI connector. The Java SE platform does not include the optional JMXMP connector.
  • "User-Defined Protocols": A connector can also implement a protocol that is not defined in the JMX technology.

RMI Connector

The JMX Remote API standard defines a standard protocol based on RMI. The RMI connector must be present in every implementation of the JMX Remote API.

RMI defines two standard transports, the Java Remote Method Protocol (JRMP) and the Internet Inter-ORB Protocol (IIOP). The RMI connector supports both transports.

The RMI connector over JRMP provides a simple mechanism for securing and authenticating the connection between a client and a server. This mechanism provides a basic level of security for environments using the RMI connector. Note that the generic JMXMP connector provides a more advanced level of security.

You can improve on the basic security mechanism of the RMI connector over JRMP by using an RMI socket factory so that the connection between client and server uses the Secure Socket Layer (SSL).

Generic Connector

An optional part of the JMX Remote API, which is not included in the Java SE platform, is a generic connector. This connector can be configured by adding pluggable modules to define the following:

  • The transport protocol used to send requests from the client to the server, and to send responses and notifications from the server to the clients
  • The object wrapping for objects that are sent from the client to the server and whose class loader can depend on the target MBean

The JMX Messaging Protocol (JMXMP) connector is a configuration of the generic connector where the transport protocol is based on TCP and the object wrapping is native Java serialization. Security is more advanced than for the RMI connector. Security is based on the Java Secure Socket Extension (JSSE), the Java Authentication and Authorization Service (JAAS), and the Simple Authentication and Security Layer (SASL).

The generic connector and its JMXMP configuration are optional, which means that they are not always included in an implementation of the JMX Remote API. The Java SE platform does not include the optional generic connector.

Note – If you want to use a JMXMP connector, download the JSR 160 Reference Implementation from http://java.sun.com/products/JavaManagement/download.html, and add the jmxremote_optional.jar file to your classpath. You will find examples of use of the JMXMP connectors in the JMX Remote API Tutorial included with the JSR 160 Reference Implementation.

User-Defined Protocols

While the RMI connector must be present in every implementation of the JMX Remote API, you can also implement a connector based on a protocol that is not defined in the JMX Remote API standard. A typical example of this is a connector based on a protocol that uses HTTP/S. Other protocols are also possible. The JMX specification describes how to implement a connector based on a user-defined protocol.

Contents | Previous | Next Java Management Extensions (JMX) Technology Overview
Java Management Extensions (JMX), Java Platform, Standard Edition 6

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.


Java Management Extensions (JMX) Technology Tutorial

Java Management Extensions (JMX)
Java Platform, Standard Edition 6

October, 2006
Contents | Previous | Next

Contents

Preface

1. Getting Started

1.1 Platform Information

1.2 Examples Directory

1.3 Working Directory

2. Essentials of the JMX API

2.1 Standard MBeans

2.1.1 MBean Interface

2.1.2 MBean Implementation

2.1.3 Managing a Resource

2.1.4 Running the Standard MBean Example

2.2 Sending Notifications

2.2.1 NotificationBroadcaster Interface

2.2.2 Running the MBean Notification Example

2.3 Introducing MXBeans

2.3.1 QueueSamplerMXBean Interface

2.3.2 QueueSampler Class

2.3.3 QueueSample Class

2.3.4 Creating and Registering the MXBean in the MBean Server

2.3.5 Running the MXBean Example

2.4 MBean Descriptors

2.4.1 DescriptorKey Annotations

2.4.2 Using MBean Descriptors

2.4.3 Running the MBean Descriptors Example

3. JMX Connectors

3.1 Accessing Standard and Dynamic MBeans via the RMI Connector

3.1.1 Analyzing the Example Classes

3.1.1.1 Server.java

3.1.1.2 SimpleStandardMBean.java

3.1.1.3 SimpleStandard.java

3.1.1.4 SimpleDynamic.java

3.1.1.5 ClientListener.java

3.1.1.6 Client.java

3.1.2 Running the MBean Example

4. Lookup Services

4.1 Initial Configuration

4.1.1 External RMI Registry

4.1.2 External CORBA Naming Service

4.1.3 External LDAP Registry

4.2 Service Location Protocol (SLP) Lookup Service

4.2.1 Analyzing the Example Classes

4.2.1.1 Server.java

4.2.1.2 Client.java

4.2.2 Running the SLP Lookup Service Example

4.2.2.1 Setting up the SLP Lookup Service Example

4.2.2.2 Running the SLP Lookup Service Example

4.3 Jini Lookup Service

4.3.1 Analyzing the Example Classes

4.3.1.1 Server.java

4.3.1.2 Client.java

4.3.1.3 java.policy

4.3.1.4 jini.properties.template

4.3.2 Running the Jini Lookup Service Example

4.3.2.1 Setting up the Jini Lookup Service Example

4.3.2.2 Running the Jini Lookup Service Example

4.4 Java Naming and Directory Interface (JNDI) / LDAP Lookup Service

4.4.1 Analyzing the Example Classes

4.4.1.1 Server.java

4.4.1.2 Client.java

4.4.1.3 jmx-schema.txt

4.4.1.4 60jmx-schema.ldif

4.4.2 Running the JNDI/LDAP Lookup Service Example

4.4.2.1 Setting up the JNDI/LDAP Lookup Service Example

4.4.2.2 Running the JNDI/LDAP Lookup Service Example With an RMI Connector

5. Security

5.1 Simple Security

5.1.1 RMI Connectors With Simple Security

5.1.1.1 Server.java

5.1.1.2 SimpleStandardMBean.java

5.1.1.3 SimpleStandard.java

5.1.1.4 ClientListener.java

5.1.1.5 Client.java

5.1.2 Running the RMI Connector Example With Simple Security

5.2 Subject Delegation

5.2.1 Secure RMI Connectors With Subject Delegation

5.2.1.1 Server.java

5.2.1.2 java.policy

5.2.1.3 SimpleStandardMBean.java

5.2.1.4 SimpleStandard.java

5.2.1.5 ClientListener.java

5.2.1.6 Client.java

5.2.2 Running the Secure RMI Connector Example With Subject Delegation

5.3 Fine-Grained Security

5.3.1 RMI Connectors With Fine-Grained Security

5.3.1.1 The files will be analyzed in the following sections.Server.java

5.3.1.2 java.policy

5.3.1.3 SimpleStandardMBean.java

5.3.1.4 SimpleStandard.java

5.3.1.5 ClientListener.java

5.3.1.6 Client.java

5.3.2 Running the RMI Connector Example With Fine-Grained Security

Contents | Previous | Next

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.


Contents | Previous | Next Java Management Extensions (JMX) Technology Tutorial

Chapter 2

Essentials of the JMX API

This chapter introduces the fundamental notion of the Java Management Extensions (JMX) API, namely managed beans, or MBeans.

An MBean is a managed Java object, similar to a JavaBeanTM, that follows the design patterns set forth in the instrumentation level of the JMX specification. An MBean can represent a device, an application, or any resource that needs to be managed. MBeans expose a management interface: a set of readable and/or writable attributes and a set of invokable operations, along with a self-description. The management interface does not change throughout the life of an MBean instance. MBeans can also emit notifications when certain defined events occur.

The JMX specification defines four types of MBean: standard MBeans, dynamic MBeans, open MBeans and model MBeans. The examples in this chapter demonstrate the simplest type of MBean, namely standard MBeans.

2.1 Standard MBeans

A standard MBean is defined by writing a Java interface called SomethingMBean and a Java class called Something that implements that interface. Every method in the interface defines either an attribute or an operation in the MBean. By default every method defines an operation. Attributes and operations are simply methods which follow certain design patterns. A standard MBean is composed of the MBean interface which lists the methods for all exposed attributes and operations, and the class which implements this interface and provides the functionality of the instrumented resource.

The following sections dissect an example standard MBean, and a simple JMX agent that manages the MBean. The code samples are taken from the directory work_dir/jmx_examples/Essential/com/example/mbeans.

2.1.1 MBean Interface

An example of a very basic MBean interface, named HelloMBean, is shown in CODE EXAMPLE 2-1.

CODE EXAMPLE 2-1 Example MBean Interface, HelloMBean

package com.example.mbeans;

public interface HelloMBean {

    public void sayHello();
    public int add(int x, int y);

    public String getName();

    public int getCacheSize();
    public void setCacheSize(int size);
}

As stated previously, by convention an MBean interface takes the name of the Java class that implements it, with the suffix MBean added. So, in this case, the interface is called HelloMBean. The Hello class that implements this interface is described in Section 2.1.2 "MBean Implementation".

According to the JMX specification, an MBean interface consists of named and typed attributes that are readable and possibly writable, and named and typed operations that can be invoked by the applications that are managed by the MBean. The HelloMBean interface shown in CODE EXAMPLE 2-1, declares two operations: the Java methods add() and sayHello().

Of the two attributes that are declared by HelloMbean, Name is a read-only string, and CacheSize is an integer that can be both read and written. Getter and setter methods are declared, to allow the managed application to access and possibly change the attribute values. As defined by the JMX specification, a getter is any public method whose name begins with get and which does not return void. A getter enables a manager to read the value of the attribute, whose type is that of the returned object. A setter is any public method whose name begins with set and which takes a single parameter. A setter enables a manager to write a new value in the attribute, whose type is the same as that of the parameter.

The implementation of these operations and attributes is shown in the following section.

2.1.2 MBean Implementation

The Hello class shown in CODE EXAMPLE 2-2 implements HelloMBean.

CODE EXAMPLE 2-2 Example MBean Implementation Class, Hello

package com.example.mbeans;

public class Hello implements HelloMBean {
    public void sayHello() {
    System.out.println("hello, world");
    }

    public int add(int x, int y) {
    return x + y;
    }

    public String getName() {
    return this.name;
    }

    public int getCacheSize() {
    return this.cacheSize;
    }

    public synchronized void setCacheSize(int size) {
    this.cacheSize = size;

    System.out.println("Cache size now " + this.cacheSize);
    }

    private final String name = "Reginald";
    private int cacheSize = DEFAULT_CACHE_SIZE;
    private static final int DEFAULT_CACHE_SIZE = 200;
}

The straightforward Java class Hello provides the definitions of the operations and attributes declared by HelloMBean. As you can see, the sayHello() and add() operations are extremely simple, but real-life operations can be as simple or as sophisticated as you like.

Methods to get the Name attribute and to get and set the cacheSize attribute are also defined. In this example, the Name attribute value never changes, but in a real scenario it might change as the managed resource runs. For example, the attribute might represent statistics such as uptime or memory usage. Here, it is merely the name “Reginald”.

Calling the setCacheSize method allows you to alter the cacheSize attribute from its declared default value of 200. In reality, changing the cacheSize attribute could require other operations to be performed, such as discarding entries or allocating new ones. This example merely prints a message to confirm that the cache size has changed, but more sophisticated operations could be defined in the place of the simple call to println().

With the simple Hello MBean and its interface thus defined, they can now be used to manage the resource they represent, as shown in the following section.

2.1.3 Managing a Resource

As presented in the Java Management Extensions (JMX) Technology Overview, once a resource has been instrumented by MBeans, the management of that resource is performed by a JMX agent.

The core component of a JMX agent is the MBean server, a managed object server in which MBeans are registered (see the API documentation for the MBeanServer interface for details of the MBean server implementation). A JMX agent also includes a set of services to manage MBeans.

CODE EXAMPLE 2-3 presents a basic JMX agent, named Main.

CODE EXAMPLE 2-3 Creating a JMX Agent

package com.example.mbeans;

import java.lang.management.*;
import javax.management.*;

public class Main {

   public static void main(String[] args) throws Exception {

      MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();

      ObjectName name = new ObjectName("com.example.mbeans:type=Hello");

      Hello mbean = new Hello();

      mbs.registerMBean(mbean, name);

      System.out.println("Waiting forever...");
      Thread.sleep(Long.MAX_VALUE);
   }
}

The JMX agent Main begins by obtaining any MBean server that is running on the platform, by calling the getPlatformMBeanServer() method of the java.lang.management.ManagementFactory class. If there is no MBean server already running on the platform, then getPlatformMBeanServer() creates one automatically by calling the JMX method MBeanServerFactory.createMBeanServer(). The MBeanServer instance obtained by Main is named mbs.

Next, Main defines an object name for the MBean instance it will create. Every JMX MBean must have an object name. The object name is an instance of the JMX class ObjectName, and must conform to the syntax defined by the JMX specification, namely it must comprise a domain, and a list of key-properties (see the API documentation for the ObjectName class for details of this syntax). In the object name defined by Main, name, the domain is com.example.mbeans (the package in which the example MBeans are contained) and the key-property declares that this object is of the type Hello.

An instance of a Hello object is created, named mbean. This Hello object is itself an instance of the MBean Hello that was defined in Section 2.1.2 "MBean Implementation".

The Hello object named mbean is then registered as an MBean in the MBean server mbs with the object name name, by passing the object and the object name into a call to the JMX method MBeanServer.registerMBean().

With the Hello MBean registered in the MBean server, Main will simply wait for management operations to be performed on Hello. In the scope of this example, these management operations are invoking sayHello(), and add(), and getting and setting the attribute values.

2.1.4 Running the Standard MBean Example

Having examined the example classes, you can now run the example. The Java Platform, Standard Edition comes with a management and monitoring console, named JConsole, that is used to interact with the MBean in this example. JConsole is located in JavaSE_HOME/bin/jconsole, in which JavaSE_HOME is the installation directory of the Java Platform, Standard Edition (Java SE platform).

To run the example, follow the steps below, or see the README file:

  1. If you have not done so already, open work_dir/jmx_examples/Essential.

    2. $ cd work_dir/jmx_examples/Essential

  2. Compile the example Java classes.

    3. $ javac com/example/mbeans/*.java

  3. Start the Main application.

    4. $ java com.example.mbeans.Main

    You will see confirmation that Main is waiting for something to happen.

  4. Start JConsole in a different terminal window on the same machine.

    5. $ jconsole

    You will see the JConsole tool open, presenting a list of running JMX agents that you can connect to.

  5. Select com.example.mbeans.Main from the list in the “New Connection” window, and click on “Connect”.

    6. You will see a summary of your platform’s current activity.

  6. Click on the “MBeans” tab.

    7. This panel shows you all the MBeans currently registered in the MBean server.

  7. In the left-hand frame, expand the com.example.mbeans node in the MBean tree.

    8. You will see the example MBean Hello, that was created and registered by Main. If you click on Hello, you will see its associated Attributes and Operations nodes in the MBean tree.

  8. Click on the Hello MBean node in the MBean tree.

    9. The Hello MBean’s metadata and its associated Descriptor will be displayed.

  9. Click on the Attributes node of the Hello MBean in the MBean tree.

    10. This displays the MBean attributes that were defined by the Hello class.

  10. Change the value of the CacheSize attribute to 150

    11. In the terminal window in which you started Main, you will see confirmation of this change of attribute.

  11. Click on the Operations node of the Hello MBean in the MBean tree.

    12. Here you will see the two operations declared by the Hello MBean, sayHello() and add().

  12. Invoke the sayHello() operation, by clicking on the sayHello button.

    13. A JConsole dialogue box will inform you that the method was invoked successfully, and you will see the message “hello, world” in the terminal window in which Main is running.

  13. Provide two integers for the add() operation to add up, and click on the add button.

    14. You will be informed of the answer in a JConsole dialogue box.

  14. Click on “Connection” and then “Exit”, to exit JConsole.

2.2 Sending Notifications

MBeans can generate notifications, for example to signal a state change, a detected event, or a problem.

For an MBean to generate notifications, it must implement the interface NotificationBroadcaster, or its subinterface NotificationEmitter. All you need to do to send a notification is to construct an instance of the class javax.management.Notification or a subclass (such as AttributeChangedNotification), and pass it to NotificationBroadcasterSupport.sendNotification.

Every notification has a source. The source is the object name of the MBean that emitted the notification.

Every notification has a sequence number. This number can be used to order notifications coming from the same source when order matters and there is a danger of the notifications being handled in the wrong order. It is all right for the sequence number to be zero, but it is better for it to increment for each notification from a given MBean.

There is an example of a standard MBean that emits notifications in the directory work_dir/jmx_examples/Notification/com/example/mbeans. This example is essentially the same as the example seen in Section 2.1 "Standard MBeans", except that the Hello MBean implements the NotificationBroadcaster interface.

2.2.1 NotificationBroadcaster Interface

As stated above, the only difference between this example and the one presented in Section 2.1 "Standard MBeans" is the fact that the MBean implementation allows for the sending of notifications.

Notifications are activated by implementing the NotificationBroadcaster interface, as shown in CODE EXAMPLE 2-4.

CODE EXAMPLE 2-4 Implementing MBean Notifications

package com.example.mbeans;

import javax.management.*;

public class Hello
        extends NotificationBroadcasterSupport implements HelloMBean {

    public void sayHello() {
        System.out.println("hello, world");
    }

    public int add(int x, int y) {
        return x + y;
    }

    public String getName() {
        return this.name;
    }

    public int getCacheSize() {
        return this.cacheSize;
    }

    public synchronized void setCacheSize(int size) {
        int oldSize = this.cacheSize;
        this.cacheSize = size;

        System.out.println("Cache size now " + this.cacheSize);

        Notification n =
            new AttributeChangeNotification(this,
                        sequenceNumber++,
                        System.currentTimeMillis(),
                        "CacheSize changed",
                        "CacheSize",
                        "int",
                        oldSize,
                        this.cacheSize);

    sendNotification(n);
    }

    @Override
    public MBeanNotificationInfo[] getNotificationInfo() {
        String[] types = new String[] {
            AttributeChangeNotification.ATTRIBUTE_CHANGE
        };
        String name = AttributeChangeNotification.class.getName();
        String description = "An attribute of this MBean has changed";
        MBeanNotificationInfo info =
            new MBeanNotificationInfo(types, name, description);
        return new MBeanNotificationInfo[] {info};
    }

    private final String name = "Reginald";
    private int cacheSize = DEFAULT_CACHE_SIZE;
    private static final int DEFAULT_CACHE_SIZE = 200;

    private long sequenceNumber = 1;
}

As you can see in CODE EXAMPLE 2-4, this Hello MBean implementation extends the NotificationBroadcasterSupport class, that itself implements the NotificationEmitter interface.

The operations and attributes are set in the same way as before, with the only exception that the cacheSize attribute’s setter method now defines a new value oldSize, which records the cacheSize attribute’s value prior to the set operation.

The notification is constructed from an instance, n, of the JMX class AttributeChangeNotification, which extends javax.management.Notification. The notification is constructed within the definition of the setCacheSize() method, from the following information, that is passed to AttributeChangeNotification as parameters:

  • The object name of the source of the notification, namely the Hello MBean, represented simply by this
  • A sequence number, which in this example is a long named sequenceNumber, that is set at 1 and that increases incrementally
  • A timestamp
  • The content of the notification message
  • The name of the attribute that has changed, in this case cacheSize
  • The type of attribute that has changed
  • The old attribute value, in this case oldSize
  • The new attribute value, in this case this.cacheSize

The notification n is then passed to the NotificationBroadcasterSupport.sendNotification() method.

Finally, the MBeanNotification is defined to describe the characteristics of the different notification instances emitted by the MBean for a given Java class of notification, which in this case is AttributeChangeNotification notifications.

The MBean interface, HelloMBean, and the JMX agent Main are identical to those used in the previous example.

2.2.2 Running the MBean Notification Example

Having examined the example classes, you can now run the example. This example again uses JConsole to interact with the Hello MBean.To run the example, follow the steps below, or see the README file:

  1. If you have not done so already, open work_dir/jmx_examples/Notification.

    2. $ cd work_dir/jmx_examples/Notification

  2. Compile the example Java classes.

    3. $ javac com/example/mbeans/*.java

  3. Start the Main application.

    4. $ java com.example.mbeans.Main

    You will see confirmation that Main is waiting for something to happen.

  4. Start JConsole in a different terminal window on the same machine.

    5. $ jconsole

    You will see the JConsole tool open, presenting a list of running JMX agents that you can connect to.

  5. Select com.example.mbeans.Main from the list in the “New Connection” window, and click on “Connect”.

    6. You will see a summary of your platform’s current activity.

  6. Click on the “MBeans” tab.

    7. This panel shows you all the MBeans currently registered in the MBean server.

  7. In the left-hand frame, expand the com.example.mbeans node in the MBean tree.

    8. You will see the example MBean Hello, that was created and registered by Main. If you click on Hello, you will see its associated Attributes, Operations and Notifications nodes in the MBean tree.

  8. Click on the Hello MBean node in the MBean tree.

    9. This displays the MBean’s metadata and its associated Descriptor.

  9. Click on the Notifications node of the Hello MBean in the MBean tree.

    10. You will see that the panel is blank.

  10. Click on the “Subscribe” button.

    11. The current number of notifications received (0), will be displayed in the Notifications node label.

  11. Click on the Attributes node of the Hello MBean in the MBean tree, and change the value of the CacheSize attribute to 150

    12. In the terminal window in which you started Main, you will see confirmation of this change of attribute. You will also see that the number of notifications received displayed in the Notifications node has changed to 1.

  12. Click on the Notifications node of the Hello MBean in the MBean tree again.

    13. You will see the details of the notification that was sent.

  13. Click on “Connection” and then “Exit”, to exit JConsole.

2.3 Introducing MXBeans

An MXBean is a new type of MBean that provides a simple way to code an MBean that only references a pre-defined set of types. In this way, you can be sure that your MBean will be usable by any client, including remote clients, without any requirement that the client have access to model-specific classes representing the types of your MBeans. MXBeans provide a convenient way to bundle related values together without requiring clients to be specially configured to handle the bundles.

In the same way as for standard MBeans, an MXBean is defined by writing a Java interface called Something MXBean and a Java class that implements that interface. However, unlike standard MBeans, MXBeans do not require the Java class to be called Something. Every method in the interface defines either an attribute or an operation in the MXBean. The annotation @MXBean can be also used to annotate the Java interface instead of requiring the interface’s name to be followed by the MXBean suffix.

MXBeans provide a convenient way to bundle related values together in an MBean without requiring clients to be specially configured to handle the bundles when interacting with that MBean. MXBeans already existed in the Java 2 Platform, Standard Edition (J2SE) 5.0, in the package java.lang.management. With the Java SE 6 platform, users can now define their own MXBeans, in addition to the standard set defined in java.lang.management.

The key idea behind MXBeans is that types such as java.lang.management.MemoryUsage that are referenced in the MXBean interface, java.lang.management.MemoryMXBean in this case, are mapped into a standard set of types, the so-called Open Types that are defined in the package javax.management.openmbean. The exact mapping rules appear in the MXBean specification, but to oversimplify we could say that simple types like int or String are unchanged, while complex types like MemoryUsage get mapped to the standard type CompositeDataSupport.

The operation of MXBeans is demonstrated by example programs that you will find in the directory work_dir/jmx_examples/MXBean/com/example/mxbeans after you have downloaded and unzipped the jmx_examples.zip file. The MXBean example contains the following files:

  • QueueSamplerMXBean interface.
  • QueueSampler class that implements the MXBean interface.
  • QueueSample Java type returned by the getQueueSample() method in the MXBean interface.
  • Main, the program that sets up and runs the example.

The MXBean example performs the following actions.

  • Defines a simple MXBean that manages a resource of type Queue<String>.
  • Declares a getter, getQueueSample, in the MXBean that takes a snapshot of the queue when invoked and returns a Java class QueueSample that bundles the following values together:
    • The time the snapshot was taken.
    • The queue size.
    • The head of the queue at that given time.
  • Registers the MXBean in an MBean server.

2.3.1 QueueSamplerMXBean Interface

CODE EXAMPLE 2-5 shows the code of the sample QueueSamplerMXBean interface.

CODE EXAMPLE 2-5 QueueSamplerMXBean interface

package com.example.mxbeans;

public interface QueueSamplerMXBean {
    public QueueSample getQueueSample();
    public void clearQueue();
}

As you can see, you declare an MXBean interface in exactly the same way as you declare a standard MBean. The QueueSamplerMXBean interface declares two operations, getQueueSample and clearQueue.

2.3.2 QueueSampler Class

The QueueSampler class implements the QueueSamplerMXBean interface, as shown in CODE EXAMPLE 2-6.

CODE EXAMPLE 2-6 QueueSampler Class
package com.example.mxbeans;

import java.util.Date;
import java.util.Queue;

public class QueueSampler implements QueueSamplerMXBean {

    private Queue<String> queue;

    public QueueSampler(Queue<String> queue) {
       this.queue = queue;
    }

    public QueueSample getQueueSample() {
        synchronized (queue) {
            return new QueueSample(new Date(), queue.size(), queue.peek());
        }
    }

    public void clearQueue() {
        synchronized (queue) {
            queue.clear();
        }
    }
}

The MXBean operations getQueueSample() and clearQueue() declared by the MXBean interface are defined in QueueSampler. The getQueueSample() operation simply returns an instance of the QueueSample Java type, created with the values returned by the java.util.Queue methods peek() and size() and an instance of java.util.Date.

2.3.3 QueueSample Class

The QueueSample instance returned by QueueSampler is defined in the QueueSample class shown in CODE EXAMPLE 2-7.

CODE EXAMPLE 2-7 QueueSample Class
package com.example.mxbeans;

import java.beans.ConstructorProperties;
import java.util.Date;

public class QueueSample {

    private final Date date;
    private final int size;
    private final String head;

    @ConstructorProperties({"date", "size", "head"})
    public QueueSample(Date date, int size, String head) {
        this.date = date;
        this.size = size;
        this.head = head;
    }

    public Date getDate() {
        return date;
    }

    public int getSize() {
        return size;
    }

    public String getHead() {
        return head;
    }
}

In QueueSample class, the MXBean framework calls all the getters in QueueSample to convert the given instance into a CompositeData and uses the @ConstructorProperties annotation to reconstruct a QueueSample instance from a CompositeData.

2.3.4 Creating and Registering the MXBean in the MBean Server

Having defined an MXBean interface and the class that implements it, as well as the Java type that is returned, the MXBean must now be created and registered in an MBean server. These actions are performed by the example class Main.

CODE EXAMPLE 2-8 MXBean example Main class
package com.example.mxbeans;

import java.lang.management.ManagementFactory;
import java.util.Queue;
import java.util.concurrent.ArrayBlockingQueue;
import javax.management.MBeanServer;
import javax.management.ObjectName;

public class Main {

    public static void main(String[] args) throws Exception {
        MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();

        ObjectName name =
                new ObjectName("com.example.mxbeans:type=QueueSampler");

        Queue<String> queue = new ArrayBlockingQueue<String>(10);
        queue.add("Request-1");
        queue.add("Request-2");
        queue.add("Request-3");
        QueueSampler mxbean = new QueueSampler(queue);

        mbs.registerMBean(mxbean, name);

        System.out.println("Waiting...");
        Thread.sleep(Long.MAX_VALUE);
    }
}

The Main class gets the platform MBean server, creates an object name for the MXBean QueueSampler, creates a Queue instance for the QueueSampler MXBean to process, and feeds this Queue instance to a newly created QueueSampler MXBean. The MXBean is then registered in the MBean server in exactly the same way as a standard MBean.

2.3.5 Running the MXBean Example

To run the example, follow the steps below, or see the README file:

  1. If you have not done so already, open work_dir/jmx_examples/MXBean.

    2. $ cd work_dir/jmx_examples/MXBean

  2. Compile the example Java classes.

    3. $ javac com/example/mxbeans/*.java

  3. Start the Main application.

    4. $ java com.example.mxbeans.Main

    You will see confirmation that Main is waiting for something to happen.

  4. Start JConsole in a different terminal window on the same machine.

    5. $ jconsole

    You will see the JConsole tool open, presenting a list of running JMX agents that you can connect to.

  5. Select com.example.mxbeans.Main from the list in the “New Connection” window, and click on “Connect”.

    6. You will see a summary of your platform’s current activity.

  6. Click on the “MBeans” tab.

    7. This panel shows you all the MBeans currently registered in the MBean server.

  7. In the left-hand frame, expand the com.example.mxbeans node in the MBean tree.

    8. You will see the example MBean QueueSampler, that was created and registered by Main. If you click on QueueSampler, you will see its associated Attributes and Operations nodes in the MBean tree.

  8. Select the Attributes node.

    9. You will see the QueueSample attribute appear in the right-hand pane, with its value of javax.management.openmbean.CompositeDataSupport.

  9. Double-click on the CompositeDataSupport value.

    10. You can see the QueueSample values date, head and size because the MXBean framework has converted the QueueSample instance into CompositeData. If you had defined QueueSampler as a Standard MBean rather than as an MXBean, JConsole would not have found the QueueSample class because it would not be in its class path. If QueueSampler had been a standard MBean, you would have received a ClassNotFoundException when retrieving the QueueSample attribute value. This demonstrates the usefulness of using MXBeans when connecting to JMX agents through generic JMX clients, like JConsole.

  10. Select the Operations node.

    11. You will see a button to invoke the clearQueue operation.

  11. Click on the clearQueue button.

    12. You will be informed that the method was invoked successfully.

  12. Select the Attributes node again and double click on the CompositeDataSupport value.

    13. The queue has been reset now.

  13. Click on “Connection” and then “Exit”, to exit JConsole.

In this example JConsole has been used as the JMX client but if you were to access your MXBean programmatically in a JMX client you write yourself, then you could do so in one of two ways:

  • Generically, using the following code.
    • CODE EXAMPLE 2-9 Accessing an MXBean directly

MBeanServer mbs = ...whatever...;
ObjectName name = new ObjectName("com.example.mxbeans:type=QueueSampler");
CompositeData queueSample = (CompositeData) mbs.getAttribute(name,
                             "QueueSample");
int size = (Integer) queueSample.get("size");
  • Via a proxy, using the following code.
CODE EXAMPLE 2-10 Accessing an MXBean via a proxy

MBeanServer mbs = ...whatever...;
ObjectName name = new ObjectName("com.example.mxbeans:type=QueueSampler");
QueueSamplerMXBean proxy = JMX.newMXBeanProxy(mbs, name,
                                              QueueSamplerMXBean.class);
QueueSample queueSample = proxy.getQueueSample();
int size = queueSample.getSize();

CODE EXAMPLE 2-10 uses the newMXBeanProxy method to create the MXBean proxy. An equivalent method, newMBeanProxy, exists to create proxies for other types of MBeans. The newMBeanProxy and newMXBeanProxy methods are used in exactly the same way.

2.4 MBean Descriptors

Descriptors allow you to give additional information about MBeans to management clients. For example, a Descriptor on an MBean attribute might say what units it is measured in, or what its minimum and maximum possible values are. As of Java SE 6, Descriptors are an integrated part of the JMX API and are available in all types of MBeans.

Descriptors give you a convenient way to attach arbitrary extra metadata to your MBeans. Descriptors have always existed in the JMX API, but until Java SE 6 they were only available in conjunction with Model MBeans.

For most constructors in the classes MBean*Info (MBeanInfo, MBeanAttributeInfo, and so on), a parallel constructor exists with the same parameters plus an additional javax.management.Descriptor parameter. The same is true for OpenMBean*InfoSupport. The MBean*Info and OpenMBean*InfoSupport classes contain a getDescriptor() method.

Open MBeans return information about default and legal values from the getDefaultValue(), getLegalValues(), getMaxValue(), getMinValue() methods of OpenMBeanParameterInfo and OpenMBeanAttributeInfo. This information is now also present in the corresponding Descriptors, and other types of MBean can also return the information in their Descriptors.

MBean Descriptors are demonstrated in the example classes you will find in the directory work_dir/jmx_examples/Descriptors/com/example/mxbeans after you have downloaded and unzipped the jmx_examples.zip file. The MBean Descriptor example contains the following files.

  • Author, an annotation the supplies the name of the author of the MBean interface.
  • DisplayName, an annotation that supplies a display name for methods in the MBean interface.
  • Main, the program that sets up and runs the example.
  • QueueSamplerMXBean interface.
  • QueueSampler class that implements the MXBean interface.
  • QueueSample Java type returned by the getQueueSample() method in the MXBean interface.
  • Version, an annotation that supplies the current version of the MBean interface.

The QueueSampler MXBean in this example basically performs the same actions as the MXBean example presented in Chapter 2, "Introducing MXBeans", except with the addition of MBean Descriptors. This example shows how the DescriptorKey meta-annotation can be used to add new descriptor items to the Descriptors for a standard MBean (or an MXBean) via annotations in the standard MBean (or MXBean) interface.

2.4.1 DescriptorKey Annotations

A new annotation DescriptorKey can be used to add information to the Descriptors for a standard MBean (or MXBean) via annotations in the Standard MBean (or MXBean) interface. This makes it possible for a tool that generates standard MBeans from an existing management model to include information from the model in the generated MBean interfaces, rather than in separate files.

CODE EXAMPLE 2-11 shows the definition of the annotation Author.

CODE EXAMPLE 2-11 Author Annotation

package com.example.mxbeans;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import javax.management.DescriptorKey;

@Documented
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface Author {
    @DescriptorKey("author")
    String value();
}

This annotation supplies the name of the creator of the MBean interface. A new field author will be added to the MBeanInfo Descriptor with the value defined by the @Author annotation. The files Version and DisplayName define annotations of those names in exactly the same way as for Author above. In each of Version and DisplayName, the @DescriptorKey value is “version” and “displayname” respectively.

In the case of Version, a new field version will be added to the MBeanInfo Descriptor with the value defined by the @Version annotation.

For DisplayName, new field displayName will be added to the MBeanAttributeInfo Descriptor or the MBeanOperationInfo Descriptor with the value defined by the @DisplayName annotation depending on whether the annotated method is a getter/setter or an operation, respectively.

2.4.2 Using MBean Descriptors

The QueueSamplerMXBean interface used in this example is slightly different from the one used in the MXBeans example, in as much as it implements MBean Descriptors to publish some of its information.

CODE EXAMPLE 2-12 QueueSamplerMXBean with Descriptors.

package com.example.mxbeans;

@Author("Mr Bean")
@Version("1.0")
public interface QueueSamplerMXBean {
    @DisplayName("GETTER: QueueSample")
    public QueueSample getQueueSample();
    @DisplayName("OPERATION: clearQueue")
    public void clearQueue();
}

Here, you see that the @Author annotation is set to Mr. Bean, the @Version annotation is set to 1.0, and the @DisplayName is set to the names either of the attribute QueueSample or the operation clearQueue.

2.4.3 Running the MBean Descriptors Example

To run the example, follow the steps below, or see the README file:

  1. If you have not done so already, open work_dir/jmx_examples/Descriptors.

    2. $ cd work_dir/jmx_examples/Descriptors

  2. Compile the example Java classes.

    3. $ javac com/example/mxbeans/*.java

  3. Start the Main application.

    4. $ java com.example.mxbeans.Main

    You will see confirmation that Main is waiting for something to happen.

  4. Start JConsole in a different terminal window on the same machine.

    5. $ jconsole

    You will see the JConsole tool open, presenting a list of running JMX agents that you can connect to.

  5. Select com.example.mxbeans.Main from the list in the “New Connection” window, and click on “Connect”.

    6. You will see a summary of your platform’s current activity.

  6. Click on the “MBeans” tab.

    7. This panel shows you all the MBeans currently registered in the MBean server.

  7. In the left-hand frame, expand the com.example.mxbeans node in the MBean tree.

    8. You will see the example MBean QueueSampler, that was created and registered by Main. If you click on QueueSampler, you will see its associated Attributes and Operations nodes in the MBean tree.You will also see the fields author and version in the MBeanInfo Descriptor table.

  8. Expand the Attributes and Operations nodes under the QueueSampler MBean node.

    9. You will see the individual Attributes and Operations.

  9. Select the QueueSample node.

    10. You will see the field displayName in the MBeanAttributeInfo Descriptor table.

  10. Select the clearQueue node.

    11. You will see the field displayName in the MBeanOperationInfo Descriptor table.

  11. Click on “Connection” and then “Exit”, to exit JConsole.

Contents | Previous | Next Java Management Extensions (JMX) Technology Tutorial
Java Management Extensions (JMX), Java Platform, Standard Edition 6

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.


Contents | Previous | Next Java Management Extensions (JMX) Technology Tutorial

Chapter 1

Getting Started

This chapter explains what you need to do to get started with the Java Management Extensions (JMX) examples. It provides instructions that apply to all the examples described in the subsequent chapters.

1.1 Platform Information

All variable assignments and commands in the examples in this tutorial were defined using UNIX Korn shell syntax. If you are running a shell other than the Korn shell on a UNIX or Linux platform, you must adapt these commands to your preferred shell environment.

If you are running a Microsoft Windows operating environment, in the majority of cases, adapting commands will simply involve replacing forward slashes (/) with backward slashes (\) and replacing colons (:) with semi-colons (;) in the paths. A specific Microsoft Windows command is given only when it differs significantly from the UNIX/Linux command provided.

1.2 Examples Directory

The examples that form the basis of this tutorial are all accessible from the JMX page in the Java Platform, Standard Edition (Java SE) documentation bundle, found in the following location:

http://java.sun.com/javase/6/docs/technotes/guides/jmx/examples.html

The code excerpts quoted in this tutorial are taken from these example programs. However, some code excerpts might be rearranged and comments might be changed. Program listings in the tutorial usually simplify comments and omit output statements, for space considerations. Some classes or sections of code that deserve special attention have been highlighted using bold text for the purposes of this tutorial.

1.3 Working Directory

To preserve untouched copies of the original example files, create a new directory in which to compile and run the examples.

  1. Create a new working directory.

    2. This working directory is referred to as work_dir throughout this tutorial.

  2. Download the examples ZIP bundle from the following URL:

    3. http://java.sun.com/javase/6/docs/technotes/guides/jmx/examples/jmx_examples.zip

  3. Unzip all the examples into work_dir.

All the examples will now be contained in work_dir/jmx_examples.

Contents | Previous | Next Java Management Extensions (JMX) Technology Tutorial
Java Management Extensions (JMX), Java Platform, Standard Edition 6

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.


Contents | Previous | Next Java Management Extensions (JMX) Technology Tutorial

Chapter 3

JMX Connectors

This chapter introduces the concepts of standard and dynamic management beans (MBeans) and also shows how to use Java Management Extensions (JMX) technology to perform operations on MBeans, both locally and remotely.

3.1 Accessing Standard and Dynamic MBeans via the RMI Connector

This example demonstrates standard and dynamic MBeans only.

As seen in Chapter 2, "Essentials of the JMX API", a standard MBean is one that statically defines its management interface through the names of the methods it contains. A dynamic MBean implements a specific Java interface and reveals its attributes and operations at run time.

The JMX technology defines a connector based on RMI. The RMI connector supports the standard RMI transports, Java Remote Method Protocol (JRMP) and the Internet Inter-Object Request Broker (ORB) Protocol (IIOP). This connector allows you to connect to an MBean in an MBean server from a remote location, and perform operations on it, exactly as if the operations were being performed locally.

The purpose of this example is to demonstrate the implementation of a standard MBean and a dynamic MBean. It also shows how to perform operations on them, both locally, and remotely through an RMI connection between a server and a remote client.

When you run this example:

  1. The server:
    1. Creates an MBean server
    2. Registers a SimpleStandard and a SimpleDynamic MBean in the local MBean server
    3. Performs local operations on the MBeans
    4. Creates an RMI connector server
  2. The client:
    1. Creates an RMI connector
    2. Registers a SimpleStandard and a SimpleDynamic MBean on the remote MBean server
    3. Performs remote operations on both MBeans

The RMI connector example is contained in the directory work_dir/jmx_examples/Basic.

  1. Open the work_dir/jmx_examples/Basic directory.

    2. Inside this directory, you will find the following files:

    • Server.java
    • SimpleStandardMBean.java
    • SimpleStandard.java
    • SimpleDynamic.java
    • ClientListener.java
    • Client.java
    • README
  2. Open each of the *.java files in a text editor.

3.1.1 Analyzing the Example Classes

The following sections analyze each of the classes used in the basic MBean example, and explain how they perform the operations described in the preceding section.

3.1.1.1 Server.java

Due to its size, the Server.java class is shown in several code excerpts.

CODE EXAMPLE 3-1 MBean Example Class Server.java (Excerpt 1)

public class Server {

 public static void main(String[] args) {
     try {

         MBeanServer mbs = MBeanServerFactory.createMBeanServer();
         waitForEnterPressed();

         String domain = mbs.getDefaultDomain();
         waitForEnterPressed();

         String mbeanClassName = "SimpleStandard";
         String mbeanObjectNameStr =
             domain + ":type=" + mbeanClassName + ",name=1";
         ObjectName mbeanObjectName =
             createSimpleMBean(mbs, mbeanClassName, mbeanObjectNameStr);
         waitForEnterPressed();

         printMBeanInfo(mbs, mbeanObjectName, mbeanClassName);
         waitForEnterPressed();

         manageSimpleMBean(mbs, mbeanObjectName, mbeanClassName);
         waitForEnterPressed();

         mbeanClassName = "SimpleDynamic";
         mbeanObjectNameStr =
             domain + ":type=" + mbeanClassName + ",name=1";
         mbeanObjectName =
             createSimpleMBean(mbs, mbeanClassName, mbeanObjectNameStr);
         waitForEnterPressed();

         printMBeanInfo(mbs, mbeanObjectName, mbeanClassName);
         waitForEnterPressed();

         manageSimpleMBean(mbs, mbeanObjectName, mbeanClassName);
         waitForEnterPressed();

         [...]

Examining this class, you can see that the following occurs:

Firstly, the Server.java class creates a new MBean server called mbs by calling the createMBeanServer() method of the MBeanServerFactory class.

Then, the default domain in which the MBean server is registered is obtained with a call to the getDefaultDomain() method of the MBeanServer interface. The domain is identified by the string domain.

The MBean class named SimpleStandard is also identified by a variable, in this case the string mbeanClassName. SimpleStandard is the name of the Java class for the Java object of which this MBean is an instance. The SimpleStandard.java object is examined in Section 3.1.1.3 "SimpleStandard.java".

Another variable, the string mbeanObjectNameStr, is defined as the combination of the domain, plus the following key=value pairs:

  • The type, which in this case is the mbeanClassName.
  • A name, to differentiate this MBean from other MBeans of the same type that might be created subsequently. In this case the name number is 1.

The purpose of mbeanObjectNameStr is to give the MBean a human-readable identifier.

A call to createSimpleMBean() creates and registers the SimpleStandard MBean in the local MBean server, with the given object name.

The operations printMBeanInfo(), and manageSimpleMBean() are then performed on the SimpleStandard MBean. Like createSimpleMBean(), these methods are defined later in the Server.java code, and are shown in CODE EXAMPLE 3-4 and CODE EXAMPLE 3-5.

In code that is not shown here, a second MBean of the type SimpleDynamic is created and registered in the MBean server in exactly the same way as the SimpleStandard MBean. As the name suggests, this MBean is an instance of the SimpleDynamic Java object, which is examined in Section 3.1.1.4 "SimpleDynamic.java".

CODE EXAMPLE 3-2 MBean Example Class Server.java (Excerpt 2)

[...]

JMXServiceURL url =
  new JMXServiceURL("service:jmx:rmi:///jndi/rmi://localhost:9999/server");
JMXConnectorServer cs =
  JMXConnectorServerFactory.newJMXConnectorServer(url, null, mbs);
cs.start();
waitForEnterPressed();
cs.stop();

[...]

In CODE EXAMPLE 3-2, an RMI connector server is created so that operations can be performed on the MBeans remotely. A call to the class JMXServiceURL creates a new service URL called url, which serves as an address for the connector server. In this example, the service URL is given in JNDI form, rather than in encoded form (see the API documentation for the javax.management.remote.rmi package for an explanation of JNDI form). This service URL defines the following:

  • The connector will use the default RMI transport, denoted by rmi.
  • The RMI registry in which the RMI connector stub will be stored will be running on port 9999 on the local host, and the server address will be registered under the name server. The port 9999 specified in the example is arbitrary; you can use any available port.

An RMI connector server named cs is created by calling the constructor JMXConnectorServerFactory, with the service URL url, a null environment map, and the MBean server mbs as parameters. The connector server cs is launched by calling the start() method of JMXConnectorServer, whereupon RMIConnectorServer exports the RMI object server to the RMI registry. The connection will remain open until the Enter key is pressed, as instructed by the simple method waitForEnterPressed, that is defined later in the Server code.

CODE EXAMPLE 3-3 MBean Example Class Server.java (Excerpt 3)

[...]

private static ObjectName createSimpleMBean(MBeanServer mbs,
                                              String mbeanClassName,
                                              String mbeanObjectNameStr) {
     echo("\n>>> Create the " + mbeanClassName +
          " MBean within the MBeanServer");
     echo("ObjectName = " + mbeanObjectNameStr);
     try {
          ObjectName mbeanObjectName =
             ObjectName.getInstance(mbeanObjectNameStr);
          mbs.createMBean(mbeanClassName, mbeanObjectName);
             return mbeanObjectName;
          } catch (Exception e) {
            echo(	"!!! Could not create the " +
                  mbeanClassName + " MBean !!!");
            e.printStackTrace();
            echo("\nEXITING...\n");
            System.exit(1);
        }
        return null;
     }

[...]

CODE EXAMPLE 3-3 shows the definition of the createSimpleMBean() method. In this method, the MBean instance with the object name mbeanObjectNameStr is passed to the getInstance() method of the ObjectName interface to create a new object name for registering the MBean inside the MBean server. The resulting object name instance is named mbeanObjectName. A call to the MBeanServer method createMBean() then instantiates an MBean defined by the combination of the Java object identified by mbeanClassName and the MBean instance mbeanObjectName and registers this MBean in the MBean server mbs.

CODE EXAMPLE 3-4 MBean Example Class Server.java (Excerpt 4)
[...]

private static void printMBeanInfo(MBeanServer mbs,
                                     ObjectName mbeanObjectName,
                                     String mbeanClassName) {
     MBeanInfo info = null;
     try {
         info = mbs.getMBeanInfo(mbeanObjectName);
     } catch (Exception e) {
         echo(	"!!! Could not get MBeanInfo object for " +
          mbeanClassName +" !!!");
         e.printStackTrace();
         return;
     }

     MBeanAttributeInfo[] attrInfo = info.getAttributes();
     if (attrInfo.length > 0) {
         for (int i = 0; i < attrInfo.length; i++) {
         echo(" ** NAME: 	" + attrInfo[i].getName());
         echo("    DESCR: 	" + attrInfo[i].getDescription());
         echo("    TYPE: 	" + attrInfo[i].getType() +
                   "READ: "+ attrInfo[i].isReadable() +
                   "WRITE: "+ attrInfo[i].isWritable());
        }
     } else echo(" ** No attributes **");

[...]

In CODE EXAMPLE 3-4 we see the definition of the method printMBeanInfo(). The printMBeanInfo() method calls the MBeanServer method getMBeanInfo() to obtain details of the attributes and operations that are exposed by the MBean mbeanObjectName. MBeanAttributeInfo defines the following methods, each of which is called in turn to obtain information about the mbeanObjectName MBean’s attributes:

  • getName, to obtain the attribute’s name.
  • getDescription, to obtain the human readable description of the attribute.
  • getType, to obtain the class name of the attribute.
  • isReadable, to determine whether or not the attribute is readable.
  • isWritable, to determine whether or not the attribute is writable.

In code that is not shown here, calls are made to obtain information about the mbeanObjectName MBean’s constructors, operations and notifications:

  • MBeanConstructorInfo, to obtain information about the MBean’s Java class.
  • MBeanOperationInfo, to learn what operations the MBean performs, and what parameters it takes.
  • MBeanNotificationInfo, to find out what notifications the MBean sends when its operations are performed.
CODE EXAMPLE 3-5 MBean Example Class Server.java (Excerpt 5)
[...]

private static void manageSimpleMBean(MBeanServer mbs,
                                        ObjectName mbeanObjectName,
                                        String mbeanClassName) {
        try {
            printSimpleAttributes(mbs, mbeanObjectName);

            Attribute stateAttribute = new Attribute("State",
                                                     "new state");
            mbs.setAttribute(mbeanObjectName, stateAttribute);

            printSimpleAttributes(mbs, mbeanObjectName);

            echo("\n    Invoking reset operation...");
            mbs.invoke(mbeanObjectName, "reset", null, null);

            printSimpleAttributes(mbs, mbeanObjectName);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    private static void printSimpleAttributes(
                                        MBeanServer mbs,
                                        ObjectName mbeanObjectName) {
        try {
            String State =
               (String) mbs.getAttribute(mbeanObjectName, "State");
            Integer NbChanges =
               (Integer) mbs.getAttribute(mbeanObjectName,
                                          "NbChanges");
        } catch (Exception e) {
            echo(	"!!! Could not read attributes !!!");
            e.printStackTrace();
        }
   }

[...]

CODE EXAMPLE 3-5 shows a method for managing a simple MBean.

The manageSimpleMBean() method first of all calls the printSimpleAttributes() method that is also defined by Server. The printSimpleAttributes() method obtains an MBean attribute called state from the MBean mbeanObjectName, as well as another MBean attribute called NbChanges. Both of these attributes are defined in the SimpleStandard class, shown in Section 3.1.1.3 "SimpleStandard.java".

The manageSimpleMBean() method then defines an attribute called stateAttribute, which is an instance of the Attribute class. The stateAttribute attribute associates a value of new state with the existing attribute state, defined by SimpleStandard. A call to the MBeanServer method setAttribute() then sets the mbeanObjectName MBean’s state to the new state defined by stateAttribute.

Finally, a call to the MBeanServer method invoke() invokes the mbeanObjectName MBean’s reset operation. The reset operation is defined in the SimpleStandard class.

3.1.1.2 SimpleStandardMBean.java

The SimpleStandardMBean.java class is shown in CODE EXAMPLE 3-6.

CODE EXAMPLE 3-6 MBean Example Class SimpleStandardMBean.java

public interface SimpleStandardMBean {

       public String getState();
       public void setState(String s);
       public int getNbChanges();
       public void reset();

}

The SimpleStandardMBean.java class is a straightforward JMX specification management interface for the MBean SimpleStandard. This interface exposes the four operations defined by SimpleStandard for management through a JMX agent.

3.1.1.3 SimpleStandard.java

The SimpleStandard.java class is shown in CODE EXAMPLE 3-7.

CODE EXAMPLE 3-7 MBean Example Class SimpleStandard.java

public class SimpleStandard
    extends NotificationBroadcasterSupport
    implements SimpleStandardMBean {
    public String getState() {
       return state;
    }
    public void setState(String s) {
       state = s;
       nbChanges++;
    }

    public int getNbChanges() {
        return nbChanges;
    }

    public void reset() {
       AttributeChangeNotification acn =
           new AttributeChangeNotification(this,
                                          0,
                                          0,
                                          "NbChanges reset",
                                          "NbChanges",
                                          "Integer",
                                          new Integer(nbChanges),
                                          new Integer(0));
       state = "initial state";
       nbChanges = 0;
       nbResets++;
       sendNotification(acn);
    }

    public int getNbResets() {
       return nbResets;
    }

    public MBeanNotificationInfo[] getNotificationInfo() {
        return new MBeanNotificationInfo[] {
      new MBeanNotificationInfo(
      new String[] {
        AttributeChangeNotification.ATTRIBUTE_CHANGE },
        AttributeChangeNotification.class.getName(),
        "This notification is emitted when the reset()
         method is called.")
    };
    }

    private String state = "initial state";
    private int nbChanges = 0;
    private int nbResets = 0;

}

The SimpleStandard class defines a straightforward JMX specification standard MBean.

The SimpleStandard MBean exposes operations and attributes for management by implementing the corresponding SimpleStandardMBean interface, shown in Section 3.1.1.2 "SimpleStandardMBean.java".

The simple operations exposed by this MBean are as follows:

  • To define a state.
  • To update this state.
  • To count the number of times the state is updated
  • To reset the values of the state and the number of changes to their original value of zero
  • To send a notification whenever the reset operation is invoked

The notification emitted by the reset operation is an instance of the class AttributeChangeNotification, which collects information about the number of changes carried out on the State attribute before calling reset. The content of the notification sent is defined by the MBeanNotificationInfo instance.

3.1.1.4 SimpleDynamic.java

The SimpleDynamic class is shown in CODE EXAMPLE 3-8.

CODE EXAMPLE 3-8 MBean Example Class SimpleDynamic.java

public class SimpleDynamic
    extends NotificationBroadcasterSupport
    implements DynamicMBean {

    public SimpleDynamic() {
        buildDynamicMBeanInfo();
    }

[...]

The SimpleDynamic dynamic MBean shows how to expose attributes and operations for management at runtime, by implementing the DynamicMBean interface. It starts by defining a method, buildDynamicMBeanInfo(), for obtaining information for the MBean dynamically. The buildDynamicMBeanInfo() method builds the MBeanInfo for the dynamic MBean.

The rest of the code of SimpleDynamic corresponds to the implementation of the DynamicMBean interface. The attributes, operations and notifications exposed are identical to those exposed by the SimpleStandard MBean.

3.1.1.5 ClientListener.java

The ClientListener.java class is shown in CODE EXAMPLE 3-9.

CODE EXAMPLE 3-9 MBean Example Class ClientListener.java

public class ClientListener implements NotificationListener {
 public void handleNotification(Notification notification, Object handback)
     {
         System.out.println("\nReceived notification: " + notification);
     }
}

The ClientListener class implements a straightforward JMX specification notification listener.

The handleNotification() method of the NotificationListener interface is called upon reception of a notification, and prints out a message to confirm that a notification has been received.

3.1.1.6 Client.java

The Client.java class is shown in CODE EXAMPLE 3-10.

CODE EXAMPLE 3-10 MBean Example Class Client.java

public class Client {

  public static void main(String[] args) {
    try {
      // Create an RMI connector client
      //
      JMXServiceURL url = new JMXServiceURL(
         "service:jmx:rmi:///jndi/rmi://localhost:9999/server");
      JMXConnector jmxc = JMXConnectorFactory.connect(url, null);
      ClientListener listener = new ClientListener();
      MBeanServerConnection mbsc = jmxc.getMBeanServerConnection();
      waitForEnterPressed();

      // Get domains from MBeanServer
      //
      String domains[] = mbsc.getDomains();
      for (int i = 0; i < domains.length; i++) {
          System.out.println("Domain[" + i + "] = " + domains[i]);
      }
      waitForEnterPressed();

      String domain = mbsc.getDefaultDomain();

      // Create SimpleStandard MBean
      ObjectName mbeanName =
             new ObjectName(domain +":type=SimpleStandard,name=2");
      mbsc.createMBean("SimpleStandard", stdMBeanName, null, null);
      waitForEnterPressed();

      // Create SimpleDynamic MBean
      ObjectName dynMBeanName =
          new ObjectName(domain +":type=SimpleDynamic,name=2");
      echo("\nCreate SimpleDynamic MBean...");
      mbsc.createMBean("SimpleDynamic", dynMBeanName, null, null);
      waitForEnterPressed();

      // Get MBean count
      echo("\nMBean count = " + mbsc.getMBeanCount());

      // Query MBean names
      echo("\nQuery MBeanServer MBeans:");
      Set names = mbsc.queryNames(null, null);
      for (Iterator i = names.iterator(); i.hasNext(); ) {
      echo(	"ObjectName = " + (ObjectName) i.next());
      }
      waitForEnterPressed();

      mbsc.setAttribute(stdMBeanName,
                        new Attribute("State", "changed state"));

      SimpleStandardMBean proxy = JMX.newMBeanProxy(
          mbsc, stdMBeanName, SimpleStandardMBean.class, true);
      echo("\nState = " + proxy.getState());

      ClientListener listener = new ClientListener();
      mbsc.addNotificationListener(stdMBeanName, listener, null, null);

      mbsc.invoke(stdMBeanName, "reset", null, null);

      mbsc.removeNotificationListener(stdMBeanName, listener);
      mbsc.unregisterMBean(stdMBeanName);

      [...]

      jmxc.close();
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}
[...]

The Client.java class creates an RMI connector client that is configured to connect to the RMI connector server created by Server.java.

As you can see, Client.java defines the same service URL url as that defined by Server.java. This allows the connector client to retrieve the RMI connector server stub named server from the RMI registry running on port 9999 of the local host, and to connect to the RMI connector server.

With the RMI registry thus identified, the connector client can be created. The connector client, jmxc, is an instance of the interface JMXConnector, created by the connect() method of JMXConnectorFactory. The connect() method is passed the parameters url and a null environment map when it is called.

The Client also creates an instance of ClientListener, to listen for notifications, as shown in Section 3.1.1.5 "ClientListener.java".

An instance of a JMX specification MBeanServerConnection, named mbsc, is then created by calling the getMBeanServerConnection() method of the JMXConnector instance jmxc.

The connector client is now connected to the MBean server created by Server.java, and can register MBeans and perform operations on them with the connection remaining completely transparent to both ends.

The client creates and registers the SimpleStandard MBean and the SimpleDynamic MBean in the MBean server with a call to the createMBean() method of MBeanServerConnection, and performs the operations defined by SimpleStandard and SimpleDynamic as if they were local JMX specification MBean operations.

MBean proxies allow you to access an MBean through a Java interface, allowing you to make calls on the proxy rather than having to write lengthy code to access a remote MBean. An MBean proxy for SimpleStandardMBean is created here by calling the method newMBeanProxy() in the javax.management.JMX class, passing it the MBean’s MBeanServerConnection, object name, the class name of the MBean interface and true, to signify that the proxy must behave as a NotificationBroadcaster. You can make proxies for MXBeans in exactly the same way as for standard MBeans, by simply calling newMXBeanProxy() instead of newMBeanProxy().

The code for the different operations performed on SimpleDynamic is not shown here, because the operations are the same as those performed on SimpleStandard.

Finally, the client unregisters the SimpleStandard MBean and closes the connection. The final removeNotificationListener is optional, as listeners registered by a remote client are removed when that client is closed.

3.1.2 Running the MBean Example

Having examined the example classes, you can now run the example. To run the example, follow the steps below, or see the README file:

  1. Compile the Java classes.

    2. $ javac *.java

  2. Start an RMI registry on port 9999 of the local host.

    3. The RMI registry will be used by the Server to register the RMI connector stub.

    $ rmiregistry 9999 &

  3. Start the Server class.

    4. $ java -classpath . Server

    You will see confirmation of the creation of the MBean server and the creation of the SimpleStandard MBean in the MBean server. You will then be prompted to press the Enter key to obtain information about, and then to perform operations on, the SimpleStandard MBean.

    Once the operations on the SimpleStandard have completed, the process will be repeated for the SimpleDynamic MBean.

    Once both the MBeans have been created and their operations performed, you see the creation of an RMI connector server, to allow operations to be performed on the MBeans from the remote Client.

  4. Start the Client class in another terminal window.

    5. $ java -classpath . Client

    You will see confirmation of the creation of the RMI connector client and of the connection with the connector server. You will also be informed of the domain name, and the creation and registration of SimpleStandard and SimpleDynamic MBeans. The client will then perform operations on SimpleStandard and SimpleDynamic MBeans, before unregistering them.

Contents | Previous | Next Java Management Extensions (JMX) Technology Tutorial
Java Management Extensions (JMX), Java Platform, Standard Edition 6

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.


Contents | Previous | Next Java Management Extensions (JMX) Technology Tutorial

Chapter 4

Lookup Services

The Java Management Extensions (JMX) specification defines three bindings to lookup services, using existing lookup technologies, as described in the following sections:

  • Section 4.1 "Initial Configuration" provides configuration information that applies to all three types of lookup service.
  • Section 4.2 "Service Location Protocol (SLP) Lookup Service" presents the SLP lookup example.
  • Section 4.3 "Jini Lookup Service" presents the Jini lookup example.
  • Section 4.4 "Java Naming and Directory Interface (JNDI) / LDAP Lookup Service" presents the JNDI/LDAP lookup example.

The lookup services allow JMX technology clients to find and connect to connector servers that have registered with the lookup services.

4.1 Initial Configuration

As shown simply in Section 3.1 "Accessing Standard and Dynamic MBeans via the RMI Connector", if you are using remote method invocation (RMI) connectors, you can choose to use an external directory to register the connector server stubs you want to look up. The following cases are presented in the lookup service examples relating to RMI connectors:

  • RMI connectors using one of the following external directories:
    • An RMI registry, for RMI connectors implementing the default Java Remote Method Protocol (JRMP) transport
    • CORBA Naming Service, for RMI connectors implementing the Internet Inter-ORB Protocol (IIOP) transport
    • Lightweight Directory Access Protocol (LDAP), for both the IIOP and JRMP transports
  • RMI connectors without an external directory

If you choose to register the RMI connector stubs in an external directory, some initial configuration is required, to set up your RMI registry, CORBA naming service or LDAP server. If you do not use an external directory, the RMI connector stub is encoded into the JMX service URL.

The following sections describe the external directories that you can use in conjunction with the lookup service examples that use RMI connectors. These external directories are referred to when running the three examples of lookup services that are given in the subsequent sections in this chapter.

4.1.1 External RMI Registry

To register the RMI connector server stubs in an external RMI registry, for use by connectors implementing the JRMP transport, perform the following actions:

  1. Start the RMI registry on port 9999 of the local host.

    2. As was the case in Chapter 3, "JMX Connectors", the RMI registry is used to store the RMI connector stubs for RMI connectors implementing the JRMP transport.

    $ rmiregistry 9999 &

  2. For your convenience when typing commands, create an environment variable for the address of the RMI registry.

    3. To shorten the commands that you will type when you run the examples, set the service URL for the RMI registry as an environment variable, jndirmi. In these examples, the service URL is given in JNDI form. See the API documentation for the javax.management.remote.rmi package for an explanation of JNDI form. If you want to run the external directories on a machine other than the local machine, you must specify that machine’s host name instead of localhost.

    $ jndirmi="rmi://localhost:9999"

4.1.2 External CORBA Naming Service

To register the RMI connector server stubs in an external CORBA naming service, for use by connectors implementing the IIOP transport, perform the following actions:

  1. Start an Object Request Broker (ORB) daemon on port 7777 of the local host.

    2. RMI connectors that implement the IIOP transport can use CORBA naming to identify the RMI connector stub.

    $ orbd -ORBInitialPort 7777 &

  2. For your convenience when typing commands, create an environment variable for the address of the CORBA naming service.

    3. To shorten the commands that you type when you run the examples, set the service URL for the CORBA naming service as an environment variable, jndiiiop. In these examples, the service URL is given in JNDI form. If you want to run the external directories on a machine other than the local machine, you must specify that machine’s host name instead of localhost.

    $ jndiiiop="iiop://localhost:7777"

4.1.3 External LDAP Registry

To register the RMI connector server stubs in an external LDAP registry, for use by connectors implementing either of the JRMP or IIOP transports, perform the following actions:

  1. Start an LDAP Server.

    2. The LDAP server you use is your choice, although the schema for representing Java objects in an LDAP directory must be known to the server. See the relevant Request For Comments (RFC) document for details:

    http://www.ietf.org/rfc/rfc2713.txt

  2. Create a domain component suffix.

    3. These examples require that you create the following domain component suffix:

    dc=Test

    See the documentation accompanying your LDAP server for details of how to configure the server and create this suffix.

  3. For your convenience, set the following LDAP parameters as environment variables.

    4. These variables are used to shorten the commands you type when starting the Server and Client classes in the lookup service examples that register RMI connector stubs in the external LDAP server.

    1. The name of the machine running your LDAP server (ldap_host)

      2. $ ldaphost=ldap_host

    2. The port the LDAP server is running on (ldap_port)

      3. $ ldapport=ldap_port

    3. The LDAP common name attribute, which in these examples is “Directory Manager”

      4. $ principal=”cn=Directory Manager”

    4. The password required by your LDAP server

      5. Supply the password for your LDAP server.

      $ credentials=your_ldap_password

    5. The address of the LDAP server

      6. In this example, the service URL for the LDAP server is given in JNDI form and is identified by the variable jndildap.

      $ jndildap="ldap://$ldaphost:$ldapport"

  4. You are now ready to run the different lookup service examples.

4.2 Service Location Protocol (SLP) Lookup Service

The JMX technology specifies how to register RMI connectors with the SLP lookup service.

The purpose of this example is to demonstrate how a JMX Remote API connector client can find and connect to a connector server that has registered with the SLP lookup service. This example performs the following operations:

  1. The agent:
    1. Creates an MBean server
    2. Gets a pointer to the SLP lookup service
    3. Creates a connector server
    4. Registers the connector address with the SLP lookup service
  2. The client:
    1. Gets a pointer to the SLP lookup service
    2. Looks for any connector servers registered in the SLP lookup service
    3. Creates a JMX Remote API connector
    4. Retrieves information about the MBeans in the MBean server
Note – This example assumes that you are already familiar with SLP technology. The code provided for this example conforms to Sun Microsystems’ implementation of SLP, as defined by RFC 2614 (see http://www.ietf.org/rfc/rfc2614.txt). Sun Microsystems’ implementation of SLP is available in the Solaris operating environment in the directory/usr/share/lib/slp. If you are not running the Solaris operating environment, you must obtain a version of SLP that is compliant with RFC 2614, section 5. You can download the OpenSLP Java implementation from http://www.openslp.org.

The SLP lookup example is contained in the directory work_dir/jmx_examples/Lookup/slp.

  1. Open work_dir/jmx_examples/Lookup/slp.

    2. Inside this directory, you will find the following files:

    • Server.java
    • Client.java
    • README
  2. Open both the *.java files in a text editor.

    3. These classes will be analyzed in the following sections.

4.2.1 Analyzing the Example Classes

The following sections analyze each of the classes used in the SLP lookup example, and explain how they perform the operations described above.

Note – If you are using an implementation of SLP other than Sun Microsystems’ implementation, you will have to modify Server.java and Client.java to import your version of the SLP Java classes instead of the com.sun.slp package. See RFC 2614, section 5.

4.2.1.1 Server.java

Due to its size, the SLP lookup service Server.java class is shown as a series of code excerpts. For explanations of the SLP code used in this example, see RFC 2614 and the API documentation for SLP.

CODE EXAMPLE 4-1 SLP Lookup Service Example Class Server.java (Excerpt 1)

public class Server {
   public final static int JMX_DEFAULT_LEASE = 300;
   public final static String JMX_SCOPE = "DEFAULT";

   private final MBeanServer mbs;
   public Server() {
       mbs = MBeanServerFactory.createMBeanServer();
   }

[...]

CODE EXAMPLE 4-1 sets the default SLP lease JMX_DEFAULT_LEASE to a default lease of 300 seconds, corresponding to the length of time the URL will be registered, and shows the initial creation of the MBean server mbs.

In code that is not shown here, you then define an SLP advertiser slpAdvertiser, and an SLP service URL url. The slpAdvertiser is used to register the service URL in the SLP lookup service. The SCOPE and the agentName are registered in SLP as lookup attributes.

CODE EXAMPLE 4-2 SLP Lookup Service Example Class Server.java (Excerpt 2)

[...]

   public static void register(JMXServiceURL jmxUrl, String name)
     throws ServiceLocationException {
     ServiceURL serviceURL =
          new ServiceURL(jmxUrl.toString(),
                         JMX_DEFAULT_LEASE);
     debug("ServiceType is: " + serviceURL.getServiceType());
     Vector attributes = new Vector();
     Vector attrValues = new Vector();
     attrValues.add(JMX_SCOPE);
     ServiceLocationAttribute attr1 =
          new ServiceLocationAttribute("SCOPE", attrValues);
     attributes.add(attr1);
     attrValues.removeAllElements();
     attrValues.add(name);
     ServiceLocationAttribute attr2 =
          new ServiceLocationAttribute("AgentName", attrValues);
     attributes.add(attr2);
     final Advertiser slpAdvertiser =
          ServiceLocationManager.getAdvertiser(Locale.US);
     slpAdvertiser.register(serviceURL, attributes);

   }

[...]

CODE EXAMPLE 4-2 shows the registration of the JMX connector server’s URL with the SLP lookup service.

The JMX service URL jmxUrl is the address of the connector server, and is obtained by a call to the getAddress() method of JMXConnectorServer when the connector server is started.

The SLP lookup attributes, namely the scope and the agent name under which the connector server address is to be registered (name), are then specified by the SLP class ServiceLocationAttribute. The AgentName attribute is mandatory, but other optional attributes, such as ProtocolType, AgentHost, and Property can also be registered in the SLP lookup service.

Finally, the JMX connector server address is registered in the SLP service with a call to the register() method of the Advertiser interface, with the serviceURL and the attributes passed in as parameters.

CODE EXAMPLE 4-3 SLP Lookup Service Example Class Server.java (Excerpt 3)

[...]

   public JMXConnectorServer rmi(String url) throws
     IOException,
     JMException,
     NamingException,
     ClassNotFoundException,
     ServiceLocationException {
     JMXServiceURL jurl = new JMXServiceURL(url);
     final HashMap env = new HashMap();
     // Environment map attributes
     [...]

     JMXConnectorServer rmis =
        JMXConnectorServerFactory.newJMXConnectorServer(jurl, env, mbs);
     final String agentName = System.getProperty("agent.name",
                                                 "DefaultAgent");
     start(rmis, agentName);

     return rmis;
  }
[...]

CODE EXAMPLE 4-3 shows the creation of an RMI connector server. The JMX service URL jurl is constructed from the string url that is included in the command used to launch the Server at the command line. An RMI connector server named rmis is then created with the system properties defined by the environment map and the address jurl.

The connector server is then started, and the RMI connector server address is registered in the SLP lookup service under the name agentName.

CODE EXAMPLE 4-4 SLP Lookup Service Example Class Server.java (Excerpt 4)

[...]

   public void start(JMXConnectorServer server, String agentName)
      throws IOException, ServiceLocationException {
      server.start();
      final JMXServiceURL address = server.getAddress();
      register(address,agentName);
   }

[...]

CODE EXAMPLE 4-4 shows the launching of the connector server server and the registration of server in the SLP lookup service with the given address address.

4.2.1.2 Client.java

The SLP lookup service Client.java class is shown in CODE EXAMPLE 4-5, CODE EXAMPLE 4-6, and CODE EXAMPLE 4-7:

CODE EXAMPLE 4-5 SLP Lookup Service Example Class Client.java (Excerpt 1)

public class Client {

    public final static String JMX_SCOPE = "DEFAULT";

    public static Locator getLocator() throws ServiceLocationException {
      final Locator slpLocator =
          ServiceLocationManager.getLocator(Locale.US);
      return slpLocator;
    }

      public static List lookup(Locator slpLocator, String name)
          throws IOException, ServiceLocationException {

          final ArrayList list = new ArrayList();
          Vector scopes = new Vector();

          scopes.add(JMX_SCOPE);
          String query =
              "(&(AgentName=" + ((name!=null)?name:"*") + "))";

          ServiceLocationEnumeration result =
              slpLocator.findServices(new ServiceType("service:jmx"),
                                      scopes, query);

          while(result.hasMoreElements()) {
                final ServiceURL surl = (ServiceURL) result.next();

             JMXServiceURL jmxUrl = new JMXServiceURL(surl.toString());
             try {
                  JMXConnector client =
                     JMXConnectorFactory.newJMXConnector(jmxUrl,null);
                  if (client != null) list.add(client);
             } catch (IOException x ) {
             [...]
             }
          }
      }
      return list;
    }

CODE EXAMPLE 4-5 first of all obtains the SLP service Locator by calling the getLocator method of the SLP class ServiceLocationManager. Client then retrieves all the connector servers registered in the SLP service under a given agent name, or under agent names that match a certain pattern. If no agent name is specified when the Client is started, all agent names will be considered.

A JMX technology service URL, jmxUrl, is generated for each of the agents retrieved by SLP, with each agent’s SLP service URL, surl, passed as a parameter into the JMXServiceURL instance. The URL jmxUrl is then passed to the newJMXConnector() method of JMXConnectorFactory, to create a new connector client named client for each agent that is registered in the SLP service.

The connector clients retrieved are stored in an array list called list.

CODE EXAMPLE 4-6 SLP Lookup Service Example Class Client.java (Excerpt 2)

public static void listMBeans(MBeanServerConnection server)
     throws IOException {

     final Set names = server.queryNames(null,null);
     for (final Iterator i=names.iterator(); i.hasNext(); ) {
          ObjectName name = (ObjectName)i.next();
          System.out.println("Got MBean: "+name);
          try {
               MBeanInfo info =
                  server.getMBeanInfo((ObjectName)name);
               MBeanAttributeInfo[] attrs = info.getAttributes();
               if (attrs == null) continue;
               for (int j=0; j<attrs.length; j++) {
                    try {
                         Object o =
                         server.getAttribute(name,attrs[j].getName());
                         System.out.println("\t\t" + attrs[j].getName() +
                         " = "+o);
                    } catch (Exception x) {
                         System.err.println("JmxClient failed to get " +
                                             attrs[j].getName() + x);
                         x.printStackTrace(System.err);
                    }
     }
}

In CODE EXAMPLE 4-6, a reference to the MBeanServerConnection is retrieved for every connector client that is created from the connector server address stored in the SLP service. A list of all the MBeans and their attributes is retrieved.

CODE EXAMPLE 4-7 SLP Lookup Service Example Class Client.java (Excerpt 3)

public static void main(String[] args) {
      try {
           final String agentName = System.getProperty("agent.name");
           final Locator slpLocator = getLocator();
           List l = lookup(slpLocator,agentName);
           int j = 1;
           for (Iterator i=l.iterator();i.hasNext();j++) {
                JMXConnector c1 = (JMXConnector) i.next();
                if (c1 != null) {
                    try {
                         c1.connect(env);
                    } catch (IOException x) {
                         System.err.println ("Connection failed: " + x);
                         x.printStackTrace(System.err);
                         continue;
                    }

                    MBeanServerConnection conn =
                         c1.getMBeanServerConnection();

                    try {
                         listMBeans(conn);
                    } catch (IOException x) {
                         x.printStackTrace(System.err);
                    }
                    try {
                         c1.close();
                    } catch (IOException x) {
                         x.printStackTrace(System.err);
                    }
                }
           }
      } catch (Exception x) {
           x.printStackTrace(System.err);
      }
}

In CODE EXAMPLE 4-7, the agent.name property is retrieved by calling the getProperty() method of the System class, and the SLP lookup service is found by calling the getLocator() method of Locator.

All the agents named agentName are then looked up, and connections are made to the agents discovered. If no agent is specified, then all agents are lookup up. Connections are made to the MBean server created by Server, and all the MBeans in it are listed, before the connection is closed down.

4.2.2 Running the SLP Lookup Service Example

In addition to the actions you performed in Section 4.1 "Initial Configuration", before you can run the lookup service examples that use the SLP, you must perform some further initial actions that are specific to this example. You can then start looking up connectors using SLP in conjunction with the two connectors supported by the JMX technology.

When you run the examples, to help you keep track of which agent has been created with which transport, the agent names include a letter suffix that is the same as the lettering of the corresponding section. For example, the agent from Section a. "RMI connector over JRMP, without an external directory" is called test-server-a.

4.2.2.1 Setting up the SLP Lookup Service Example

The following steps are required by all of the different transports you can run in this example.

  1. For convenience when compiling and running the classes, define an additional environment variable.

    2. In addition to the common environment variables that were set in Section 4.1 "Initial Configuration", you need to add the path to the SLP service. If you are using the Solaris operating environment, add the following variable:

    $ SLPLIB=/usr/share/lib/slp

    If you are using another platform, set SLPLIB appropriately for the platform you are using.

  2. Define and export the classp environment variable.

    3. This example requires a classpath that includes the Java archive (JAR) files for SLP.

    $ classp=$SLPLIB/slp.jar

  3. Compile the example Client and Server classes.

    4. Type the following command:

    $ javac -d . -classpath $classp Server.java Client.java

  4. Start the SLP daemon.

    5. If you are using the Solaris operating environment, type the following command, which requires you to know your super user password:

    $ su root -c "java -cp $SLPLIB/slpd.jar com.sun.slp.slpd &"

    Password: [type superuser password]

    If you are not running a Solaris system, start the SLP daemon according to the implementation of SLP you are using.

4.2.2.2 Running the SLP Lookup Service Example

This example demonstrates the use of the SLP lookup service to look up RMI connector servers that use RMI’s default transport, JRMP, as well as the IIOP transport. In addition, as described in Section 4.1 "Initial Configuration", different external directories are used to register the RMI connector stubs.

The combinations of transports and external directories demonstrated here are:

  • RMI connector over the JRMP transport, with:
    • No external directory
    • An RMI registry
    • An LDAP registry
  • RMI connector over the IIOP transport, with:
    • No external directory
    • A CORBA naming service
    • An LDAP registry

Perform the following steps to run the example:

  1. Start the Server.

    2. The command you use to start the Server varies according to which external directory you are using. You can start one or more of the following instances of Server with different transports and external registries before starting the Client.

    1. RMI connector over JRMP, without an external directory

      2. Start Server by typing the following command:

$ java -classpath .:$classp -Ddebug=true \
  -Dagent.name=test-server-a \
  -Durl ="service:jmx:rmi://" \
  slp.Server &

      In this command:

      • debug is set to true to provide more complete screen output when the Server runs
      • The name of the agent to be created is test-server-a
      • The service URL specifies that the chosen connector is an RMI connector, running over the RMI default transport JRMP.

      When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the SLP service.

    2. RMI connector over JRMP, using an RMI registry as an external directory.

      3. Start Server by typing the following command:

$ java -classpath .:$classp -Ddebug=true \
  -Dagent.name=test-server-b \
  -Durl="service:jmx:rmi:///jndi/${jndirmi}/server" \
  slp.Server &

      In this command:

      • The name of the agent created is test-server-b
      • The service URL specifies the chosen connector as RMI over JRMP, and the external directory in which the RMI connector stub, server, is stored is the RMI registry you identified as jndirmi in Section 4.1 "Initial Configuration".

      When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the SLP service.

    3. RMI connector over JRMP, using LDAP as the external directory.

      4. Start Server by typing the following command:

$ java -classpath .:$classp -Ddebug=true \
  -Dagent.name=test-server-c \
  -Durl="service:jmx:rmi:///jndi/${jndildap}/cn=x,dc=Test" \
  -Djava.naming.security.principal="$principal" \
  -Djava.naming.security.credentials="$credentials" \
  slp.Server &

      In this command:

      • The name of the agent created is test-server-c
      • The service URL specifies the chosen connector as RMI over JRMP, and the external directory in which the RMI connector stub is stored is the LDAP server you identified as jndildap in Section 4.1 "Initial Configuration".
      • The stub is registered in the Test domain component in the LDAP server.
      • The common name attribute principal and password credentials are given to gain access to the LDAP server.

      When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the SLP service under the agent name test-server-c.

    4. RMI connector over IIOP, without an external directory.

      5. Start Server by typing the following command:

$ java -classpath .:$classp -Ddebug=true \
  -Dagent.name=test-server-d \
  -Durl="service:jmx:iiop://" \
  slp.Server &

      In this command:

      • The name of the agent created is test-server-d
      • The service URL specifies the chosen connector as RMI connector over IIOP.

      When the Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its automatically generated URL in the SLP service.

    5. RMI connector over IIOP, using CORBA naming as the external directory.

      6. Start Server by typing the following command:

$ java -classpath .:$classp -Ddebug=true \
  -Dagent.name=test-server-e \
  -Durl="service:jmx:iiop:///jndi/${jndiiiop}/server" \
  slp.Server &

      In this command:

      • The name of the agent created is test-server-e
      • The service URL specifies the chosen connector as RMI connector over IIOP. The external directory in which the RMI connector stub server is stored is the CORBA naming service you identified as jndiiiop in Section 4.1 "Initial Configuration"

      When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the SLP service under the name test-server-e.

    6. RMI connector over IIOP, using LDAP as the external directory.

      7. Start Server by typing the following command:

$ java -classpath .:$classp -Ddebug=true \
  -Dagent.name=test-server-f \
  -Durl="service:jmx:iiop:///jndi/${jndildap}/cn=x,dc=Test" \
  -Djava.naming.security.principal="$principal" \
  -Djava.naming.security.credentials="$credentials" \
  slp.Server &

      In this command:

      • The name of the agent created is test-server-f
      • The service URL specifies the chosen connector as RMI over IIOP, and the external directory in which the RMI connector stub is stored is the LDAP server you identified as jndildap in Section 4.1 "Initial Configuration".
      • The stub is registered in the Test domain component in the LDAP server.
      • The common name attribute principal and password credentials are given to gain access to the LDAP server.

      When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the SLP service under the agent name test-server-f.

  2. Start the Client.

    3. After starting the Server using the transport and external directory of your choice, start the Client:

$ java -classpath .:$classp -Ddebug=true \
     -Djava.naming.security.principal="$principal" \
     -Djava.naming.security.credentials="$credentials" \
     slp.Client

    You will see output confirming the detection of the agents created by the Server and registered in the lookup service. You will also see the identification and confirmation of the connection made to the agents.

    To look up a specific agent, type the following command:

$ java -classpath .:$classp -Ddebug=true \
     -Djava.naming.security.principal="$principal" \
     -Djava.naming.security.credentials="$credentials" \
     -Dagent.name="agentName" \
    slp.Client

    In the command shown above, agentName is the name of the agent you want to look up. You can also specify a partial agent name by using *; for example, x* for all agent names beginning with the letter x.

4.3 Jini Lookup Service

The purpose of this example is to demonstrate how a JMX technology connector client can find and connect to a connector server that has registered with the Jini lookup service. This example performs the following operations:

  1. The agent:
    1. Creates an MBean server
    2. Creates a connector server
    3. Registers the connector address with the Jini lookup service
  2. The client:
    1. Gets a pointer to the Jini lookup service
    2. Looks for any connector servers registered in the Jini lookup service
    3. Creates a JMX Remote API connector
    4. Retrieves information about the MBeans in the MBean server

The Jini lookup service example is contained in the directory work_dir/jmx_examples/Lookup/jini.

Note –These examples assume that you are already familiar with the Jini network technology. The documentation for the Jini network technology is available at http://www.jini.org and http://jini.dev.java.net/. You can download the Jini network technology from http://starterkit.dev.java.net/downloads/index.html. This example has been implemented using the Jini Technology Starter Kit Version 1.2.1_002.
  1. Open the work_dir/jmx_examples/Lookup/jini directory.

    2. Inside this directory, you will find the following files:

    • Server.java
    • Client.java
    • java.policy
    • jini.properties.template
    • README
  2. Open each of the files in a text editor.

    3. These classes will be analyzed in the following sections.

4.3.1 Analyzing the Example Classes

The following sections analyze each of the classes used in the Jini lookup service example, and explain how they perform the operations described above.

4.3.1.1 Server.java

Due to its size, the Jini lookup service Server.java class is shown as a series of code excerpts.

CODE EXAMPLE 4-8 Jini Lookup Service Example Class Server.java (Excerpt 1)

public class Server {
   private final MBeanServer mbs;
   private static boolean debug = false;
   public Server() {
     mbs = MBeanServerFactory.createMBeanServer();
   }

[...]

CODE EXAMPLE 4-8 shows the creation of an MBean server mbs. As was the case for the SLP examples, the JMX service URL and the agent name are passed to Server when it is launched at the command line.

CODE EXAMPLE 4-9 Jini Lookup Service Example Class Server.java (Excerpt 2)

[...]

   public JMXConnectorServer rmi(String url)
      throws IOException, JMException, ClassNotFoundException {
      JMXServiceURL jurl = new JMXServiceURL(url);
      final HashMap env = new HashMap();
      // Environment map attributes
     [...]
     JMXConnectorServer rmis =
        JMXConnectorServerFactory.newJMXConnectorServer(jurl, env, mbs);

     final String agentName = System.getProperty("agent.name",
                                                 "DefaultAgent");

     start(rmis,env,agentName);

     return rmis;
   }

[...]

CODE EXAMPLE 4-9 shows the creation of an RMI connector server named rmis, using the system properties defined by the environment map env and the address jurl.

The RMI connector server rmis is started. The RMI connector server address is registered in the Jini lookup service under the name agentName.

CODE EXAMPLE 4-10 Jini Lookup Service Example Class Server.java (Excerpt 3)

[...]

   public void start(JMXConnectorServer server, Map env, String agentName)
      throws IOException, ClassNotFoundException {
      server.start();
      final ServiceRegistrar registrar=getRegistrar();
      final JMXConnector proxy = server.toJMXConnector(env);
      register(registrar,proxy,agentName);
   }

   public static ServiceRegistrar getRegistrar()
      throws IOException, ClassNotFoundException,
         MalformedURLException {
      final String jurl =
         System.getProperty("jini.lookup.url","jini://localhost");
      final LookupLocator lookup = new LookupLocator(jurl);
      final ServiceRegistrar registrar = lookup.getRegistrar();
      if (registrar instanceof Administrable)
          debug("Registry is administrable.");
      return registrar;
   }

   public static ServiceRegistration register(ServiceRegistrar registrar,
                                              JMXConnector proxy, String name)
      throws IOException {
      Entry[] serviceAttrs = new Entry[] {
              new net.jini.lookup.entry.Name(name)
                       };

      System.out.println("Registering proxy: AgentName=" + name );
      debug("" + proxy);
      ServiceItem srvcItem = new ServiceItem(null, proxy, serviceAttrs);
      ServiceRegistration srvcRegistration =
             registrar.register(srvcItem, Lease.ANY);
      debug("Registered ServiceID: " +
                              srvcRegistration.getServiceID().toString());
      return srvcRegistration;
   }

[...]

CODE EXAMPLE 4-10 shows the creation of a connector server named server with the environment map env and the service URL jurl. The connector server instance server then gets a pointer to the Jini lookup service by calling the Jini lookup service method LookupLocator.getRegistrar().

The connector server is registered in the Jini lookup service in the form of a proxy, using the Jini lookup service locator registrar and the agent name under which the connector server will be registered. The proxy is in fact a client stub for the connector server, obtained by a call to the toJMXConnector() method of JMXConnectorServer.

The registration itself is performed by a call to the register() method of the Jini lookup service class ServiceRegistrar, with an array of service items.

4.3.1.2 Client.java

The Jini lookup service example class Client.java is shown in CODE EXAMPLE 4-11.

CODE EXAMPLE 4-11 Jini Lookup Service Example Class Client.java

public class Client {

   private static boolean debug = false;
   public static ServiceRegistrar getRegistrar()
       throws IOException, ClassNotFoundException, MalformedURLException {
       final String jurl =
                  System.getProperty("jini.lookup.url","jini://localhost");
       final LookupLocator lookup = new LookupLocator(jurl);
       final ServiceRegistrar registrar = lookup.getRegistrar();
       if (registrar instanceof Administrable)
               debug("Registry is administrable.");
       return registrar;
 }

   public static List lookup(ServiceRegistrar registrar,
           String name) throws IOException {
       final ArrayList list = new ArrayList();
       final Class[] classes = new Class[] {JMXConnector.class};
       final Entry[] serviceAttrs = new Entry[] {
           new net.jini.lookup.entry.Name(name)
   };

   ServiceTemplate template =
        new ServiceTemplate(null,classes,serviceAttrs);
   ServiceMatches matches =
        registrar.lookup(template, Integer.MAX_VALUE);
   for(int i = 0; i < matches.totalMatches; i++) {
        debug("Found Service: " + matches.items[i].serviceID);
        if (debug) {
           if (matches.items[i].attributeSets != null) {
                   final Entry[] attrs = matches.items[i].attributeSets;
                   for (int j = 0; j < attrs.length ; j++) {
                       debug("Attribute["+j+"]=" + attrs[j]);
               }
           }
        }

        if(matches.items[i].service != null) {
            JMXConnector c = (JMXConnector)(matches.items[i].service);
            debug("Found a JMXConnector: " + c);
            list.add(c);
        }
   }
   return list;
}

[...]

CODE EXAMPLE 4-11 shows how the connector client obtains a pointer to the Jini lookup service with a call to lookup.getRegistrar(). The client then obtains the list of the connectors registered as entries in the Jini lookup service with the agent name name. Unlike in the SLP example, the agent name you pass to Client when it is launched must be either an exact match of an existing agent name, or null, in which case the Jini lookup service will look up all the agents.

Once the list of connectors has been obtained, in code that is not shown here, the client connects to the MBean server started by Server, and retrieves the list of all the MBeans registered in it.

4.3.1.3 java.policy

The java.policy file is a Java technology security policy file, configured for this example.

4.3.1.4 jini.properties.template

A template Jini networking technology properties file, to be configured for this example. Change @INSTALL_HOME_FOR_JINI@ and rename the file to jini.properties.

4.3.2 Running the Jini Lookup Service Example

In addition to the actions you performed in Section 4.1 "Initial Configuration", before you can run the lookup service examples that use the Jini lookup service, you must perform some further initial actions that are specific to this example. You can then start looking up connectors using the Jini network technology, in conjunction with the connector supported by the JMX technology.

When you run the examples, to help you keep track of which agent has been created with which transport, the agent names include a letter suffix that is the same as the lettering of the corresponding section. For example, the agent from Section a. "RMI connector over JRMP, without an external directory." is called test-server-a.

4.3.2.1 Setting up the Jini Lookup Service Example

The following steps are required by all of the different transports you can run in this example.

  1. For your convenience when compiling and running the example classes, define some additional environment variables.

    2. In addition to the common environment variables that you set in Section 4.1 "Initial Configuration" you can add the path to the Jini lookup service. The directory where you have installed the Jini networking technology is referred to as jini_dir.

    $ JINI_HOME=jini_dir

    $ JINILIB=$JINI_HOME/lib

  2. Define the classp environment variable.

    3. This example requires the JAR files for the Jini lookup services core and extensions.

    $ classp=$JINILIB/jini-core.jar:$JINILIB/jini-ext.jar

  3. Create a jini.properties file.

    4. A properties file for UNIX platforms is provided in the same directory as the classes for this example. If you are not running a UNIX platform, you can obtain a properties file for your platform in the following directory:

    $JINI_HOME/example/launcher/jini12_<platform>.properties

  4. Update the jini.properties file.

    5. You must complete the file to include all the necessary paths, host names and port numbers for your system. Even if you are not running a UNIX platform, you can use the template provided as a guide.

  5. Start the Jini networking technology StartService.

    6. $ java -cp $JINILIB/jini-examples.jar com.sun.jini.example.launcher.StartService &

    This will open the StartService graphical user interface.

  6. Load your jini.properties file into StartService.

    7. Click on ‘File’, ‘Open Property File’ and then select your properties file from within work_dir/jmx_examples/Lookup/jini.

  7. Start the Jini lookup services.

    8. Start the required Jini lookup services by clicking on the ‘Run’ tab and then pressing the ‘START’ button for each of the following:

    • RMID
    • WebServer
    • Reggie
    • LookupBrowser

    You will see confirmation that the services are running.

  8. Compile the Client and Server classes.

    9. Type the following command:

    $ javac -d . -classpath $classp Server.java Client.java

4.3.2.2 Running the Jini Lookup Service Example

This example demonstrates the use of the Jini lookup service to look up RMI connector servers that use RMI’s default transport, JRMP, as well as the IIOP transport. In addition, as described in Section 4.1 "Initial Configuration", different external directories are used to register the RMI connector stubs.

The combinations of transports and external directories demonstrated here are:

  • RMI connector over the JRMP transport, with:
    • No external directory
    • An RMI registry
    • An LDAP registry
  • RMI connector over the IIOP transport, with:
    • No external directory
    • A CORBA naming service
    • An LDAP registry
  1. Start the Server.

    2. The command you use to start the Server varies according to which external directory you are using. You can start one or more of the following instances of Server with different transports and external registries before starting the Client.

    1. RMI connector over JRMP, without an external directory.

      2. Start Server by typing the following command:

$ java -classpath .:$classp -Ddebug=true \
  -Dagent.name=test-server-a \
  -Durl="service:jmx:rmi://" \
  -Djava.security.policy=java.policy \
  jini.Server &

      In this command:

      • debug is set to true to provide more complete screen output when the Server runs.
      • The security policy is provided, to allow access to the Jini lookup service.
      • The name of the agent to be created is test-server-a.
      • The service URL specifies that the chosen connector is an RMI connector, running over the RMI default transport JRMP.

      When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the Jini lookup service.

    2. RMI connector over JRMP, using an RMI registry as an external directory.

      3. Start Server by typing the following command:

$ java -classpath .:$classp -Ddebug=true \
  -Dagent.name=test-server-b \
  -Durl="service:jmx:rmi:///jndi/${jndirmi}/server" \
  -Djava.security.policy=java.policy \
  jini.Server &

      In this command:

      • The security policy is provided, to allow access to the Jini lookup service.
      • The name of the agent created is test-server-b.
      • The service URL specifies the chosen connector as RMI over JRMP, and the external directory in which the RMI connector stub, server, is stored is the RMI registry you identified as jndirmi in Section 4.1 "Initial Configuration".

      When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the Jini lookup service.

    3. RMI connector over JRMP, using LDAP as the external directory.

      4. Start Server by typing the following command:

$ java -classpath .:$classp -Ddebug=true \
  -Dagent.name=test-server-c \
  -Durl="service:jmx:rmi:///jndi/${jndildap}/cn=x,dc=Test" \
  -Djava.security.policy=java.policy \
  -Djava.naming.security.principal="$principal" \
  -Djava.naming.security.credentials="$credentials" \
  jini.Server &

      In this command:

      • The security policy is provided, to allow access to the Jini lookup service.
      • The name of the agent created is test-server-c.The service URL specifies the chosen connector as RMI over JRMP, and the external directory in which the RMI connector stub is stored is the LDAP server you identified as jndildap in Section 4.1 "Initial Configuration".
      • The stub is registered in the Test domain component in the LDAP server.
      • The common name attribute principal and password credentials are given to gain access to the LDAP server.

      When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the Jini lookup service under the agent name test-server-c.

    4. RMI connector over IIOP, without an external directory.

      5. Start Server by typing the following command:

$ java -classpath .:$classp -Ddebug=true \
  -Dagent.name=test-server-d \
  -Durl="service:jmx:iiop://" \
  -Djava.security.policy=java.policy \
  jini.Server &

      In this command:

      • The security policy is provided, to allow access to the Jini lookup service
      • The name of the agent created is test-server-d
      • The service URL specifies the chosen connector as RMI connector over IIOP.

      When the Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its automatically generated URL in the Jini lookup service.

    5. RMI connector over IIOP, using CORBA naming as the external directory.

      6. Start Server by typing the following command:

$ java -classpath .:$classp -Ddebug=true \
  -Dagent.name=test-server-e \
  -Durl="service:jmx:iiop:///jndi/${jndiiiop}/server" \
  -Djava.security.policy=java.policy \
  jini.Server &

      In this command:

      • The security policy is provided, to allow access to the Jini lookup service.
      • The name of the agent created is test-server-e.
      • The service URL specifies the chosen connector as RMI connector over IIOP. The external directory in which the RMI connector stub, server, is stored is the CORBA naming service you identified as jndiiiop in Section 4.1 "Initial Configuration".

      When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the Jini lookup service under the name test-server-e.

    6. RMI connector over IIOP, using LDAP as the external directory.

      7. Start Server by typing the following command:

$ java -classpath .:$classp -Ddebug=true \
  -Dagent.name=test-server-f \
  -Durl="service:jmx:iiop:///jndi/${jndildap}/cn=x,dc=Test" \
  -Djava.security.policy=java.policy \
  -Djava.naming.security.principal="$principal" \
  -Djava.naming.security.credentials="$credentials" \
  jini.Server &

      In this command:

      • The security policy is provided, to allow access to the Jini lookup service.
      • The name of the agent created is test-server-f.
      • The service URL specifies the chosen connector as RMI over IIOP.
      • The external directory in which the RMI connector stub is stored is the LDAP server you identified as jndildap in Section 4.1 "Initial Configuration".
      • The stub is registered in the Test domain component in the LDAP server.
      • The common name attribute principal and password credentials are given to gain access to the LDAP server.

      When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the Jini lookup service under the agent name test-server-f.

  2. Start the Client.

    3. After starting the Server using the transport and external directory of your choice, start the Client:

$ java -classpath .:$classp -Ddebug=true \
  -Djava.security.policy=java.policy \
  jini.Client

    You will see output confirming the detection of the agents created by the Server and registered in the lookup service. You will also see the identification and confirmation of the connection made to the agents.

    To look up a specific agent, you can do so by typing the following command:

$ java -classpath .:$classp -Ddebug=true \
  -Djava.security.policy=java.policy \
  -Dagent.name=agentName \
  jini.Client

    In the command shown above, agentName is the name of the agent you want to look up. You can also specify a partial agent name by using *; for example, x* for all agent names beginning with the letter x.

4.4 Java Naming and Directory Interface (JNDI) / LDAP Lookup Service

JMX technology allows you to register RMI connectors with a JNDI lookup service using an LDAP registry as a back end. This example performs the following operations:

  1. The agent:
    1. Creates an MBean server
    2. Creates a connector server
    3. Registers the connector address with the LDAP server
  2. The client:
    1. Gets a pointer to the JNDI/LDAP lookup Service
    2. Looks for any connector servers registered in the JNDI/LDAP lookup service
    3. Creates a JMX Remote API connector
    4. Retrieves information about the MBeans in the MBean server

The JNDI/LDAP lookup example is contained in the directory work_dir/jmx_examples/Lookup/ldap.

  1. Open the work_dir/jmx_examples/Lookup/ldap directory.

    2. Inside this directory, you will find the following files:

    • Server.java
    • Client.java
    • jmx-schema.txt
    • 60jmx-schema.ldif
    • README
  2. Open the files in a text editor.

    3. These classes will be analyzed in the following sections.

4.4.1 Analyzing the Example Classes

The following sections analyze each of the classes used in the JNDI/LDAP lookup service example, and explain how they perform the operations described above.

4.4.1.1 Server.java

Due to its size, the JNDI/LDAP lookup service Server.java class is shown as a series of code excerpts.

CODE EXAMPLE 4-12 JNDI/LDAP Lookup Service Example Server.java (Excerpt 1)

[...]

public class Server {
   public final static int JMX_DEFAULT_LEASE = 60;
   private static boolean debug = false;
   private final MBeanServer mbs;
   public Server() {
      mbs = MBeanServerFactory.createMBeanServer();
   }

  public static DirContext getRootContext() throws NamingException {
      final Hashtable env = new Hashtable();

      final String factory =
        System.getProperty(Context.INITIAL_CONTEXT_FACTORY,
                           "com.sun.jndi.ldap.LdapCtxFactory");
      final String ldapServerUrl =
        System.getProperty(Context.PROVIDER_URL);
      final String ldapUser =
        System.getProperty(Context.SECURITY_PRINCIPAL,
                           "cn=Directory Manager");
      final String ldapPasswd =
        System.getProperty(Context.SECURITY_CREDENTIALS);
      debug(Context.PROVIDER_URL + "=" + ldapServerUrl);
      debug(Context.SECURITY_PRINCIPAL + "=" + ldapUser);
      if (debug) {
                  System.out.print(Context.SECURITY_CREDENTIALS + "=");
                  final int len = (ldapPasswd==null)?0:ldapPasswd.length();
                  for (int i=0;i<len;i++) System.out.print("*");
                  System.out.println();
      }
      env.put(Context.INITIAL_CONTEXT_FACTORY,factory);
      env.put(Context.SECURITY_PRINCIPAL, ldapUser);
      if (ldapServerUrl != null)
           env.put(Context.PROVIDER_URL, ldapServerUrl);
      if (ldapPasswd != null)
           env.put(Context.SECURITY_CREDENTIALS, ldapPasswd);
      InitialContext root = new InitialLdapContext(env,null);
      return (DirContext)(root.lookup(""));
  }

[...]

CODE EXAMPLE 4-12 shows the initial creation of an MBean server mbs, and the obtention of a pointer to the root context of the LDAP directory tree in which the connector server address is to be registered. All the relevant LDAP access variables, such as the provider URL, the LDAP user name and the security credentials, are given here and passed into the environment map env. The environment map env is then passed as a parameter into a call to InitialLdapContext, from which the initial LDAP context is obtained.

Code that is omitted from CODE EXAMPLE 4-12 retrieves the agent name under which the connector will be registered in the LDAP server.

CODE EXAMPLE 4-13 JNDI/LDAP Lookup Service Example Server.java (Excerpt 2)
[...]

public static void register(DirContext root,
                           JMXServiceURL jmxUrl,
                           String name)
   throws NamingException, IOException {

   final String mydn = System.getProperty("dn","cn="+name);

   debug("dn: " + mydn );

   Object o = null;
   try {
       o = root.lookup(mydn);
   } catch (NameNotFoundException n) {
       Attributes attrs = new BasicAttributes();
       Attribute objclass = new BasicAttribute("objectClass");
       objclass.add("top");
       objclass.add("javaContainer");
       objclass.add("jmxConnector");
       attrs.put(objclass);
       attrs.put("jmxAgentName", name);
       o = root.createSubcontext(mydn,attrs);
   }
   if (o == null) throw new NameNotFoundException();
   final Attributes attrs = root.getAttributes(mydn);
   final Attribute oc = attrs.get("objectClass");
   if (!oc.contains("jmxConnector")) {
       final String msg = "The supplied node [" + mydn +
         "] does not contain the jmxConnector objectclass";
       throw new NamingException(msg);
   }

   final Attributes newattrs = new BasicAttributes();
   newattrs.put("jmxAgentName",name);
   newattrs.put("jmxServiceURL",jmxUrl.toString());
   newattrs.put("jmxAgentHost",InetAddress.getLocalHost().getHostName());
   newattrs.put("jmxProtocolType",jmxUrl.getProtocol());
   newattrs.put("jmxExpirationDate",
                getExpirationDate(JMX_DEFAULT_LEASE));
   root.modifyAttributes(mydn,DirContext.REPLACE_ATTRIBUTE,newattrs);
}

[...]

CODE EXAMPLE 4-13 shows the registration of JMX connector server service URL in the LDAP directory. The DN where the URL will be registered can be passed on the command line through the dn System property, that is, -Ddn=mydn (see later the commands used start the server). If the dn System property is not specified, then you can use the DN: cn=name where name is the agentName. Naturally, this is not mandatory. The location where the URL is registered does not really matter, because the client code never uses that DN directly, but instead performs an LDAP search to find the nodes which have an auxiliary jmxConnector ObjectClass. What is important here is that each URL is registered in its own LDAP node. How to name these nodes is left to the LDAP administrator, who in this case is you. In this example, it is assumed that you have configured your LDAP server by creating a root context under which the node cn=name can be created, and that this root context has been passed to the LDAP initial context through the Context.PROVIDER_URL property (see CODE EXAMPLE 4-12).

The code shown in CODE EXAMPLE 4-13 checks whether the node in which you will register the server URL already exists. If it does not, you try to create it (this will fail if the parent node does not exist). Since the jmxConnector ObjectClass is a simple auxiliary class, you will use the javaContainer ObjectClass as structural class if you need to create a new context. Once again, this is completely optional. Any structural class to which the jmxConnector auxiliary class could be added would be acceptable. It then checks whether the node in which you will register the server already has the jmxConnector auxiliary class. If not, an exception is thrown.

At this point you are sure that the node in which you will register the URL exists, and has the appropriate jmxConnector auxiliary class. So you need only to replace the values of the attributes defined by JMX Remote API for LDAP lookup (see jmx-schema.txt):

  • jmxServiceUrl: contains the String form of the server URL, as obtained from server.getAddress() after the server was started
  • jmxAgentName: contains the JMX agent name
  • jmxProtocolType: contains the JMX protocol type, as returned by jmxUrl.getProtocolType()
  • jmxAgentHost: contains the name of the agent host
  • jmxExpirationDate: contains the date at which the URL will be considered obsolete.
CODE EXAMPLE 4-14 JNDI/LDAP Lookup Service Example Server.java (Excerpt 3)

[...]

   public JMXConnectorServer rmi(String url)
     throws IOException, JMException,
        NamingException, ClassNotFoundException {

     JMXServiceURL jurl = new JMXServiceURL(url);
     final HashMap env = new HashMap();
     // Prepare the environment Map

[...]

     JMXConnectorServer rmis =
        JMXConnectorServerFactory.newJMXConnectorServer(jurl, env, mbs);

     final String agentName = System.getProperty("agent.name",
                                                 "DefaultAgent");
     start(rmis,env,agentName);
     return rmis;
   }

[...]

In CODE EXAMPLE 4-14, a new RMI connector server named rmis is created with the JMX service URL jurl and the appropriate LDAP properties passed to its environment map env. The connector server rmis is launched by calling JMXConnectorServer.start() and is registered in the LDAP server.

CODE EXAMPLE 4-15 JNDI/LDAP Lookup Service Example Server.java (Excerpt 4)

[...]

    public void start(JMXConnectorServer server, Map env, String agentName)
       throws IOException, NamingException {
       server.start();
       final DirContext root=getRootContext();
       final JMXServiceURL address = server.getAddress();
       register(root,address,agentName);
    }

[...]

CODE EXAMPLE 4-15 shows the creation of a JMX connector server server, the obtention of a pointer to the LDAP server root directory root and the creation of a URL for server named address. The root directory, the URL and an agent name are passed as parameters to register() and are registered in the LDAP server.

4.4.1.2 Client.java

The JNDI/LDAP lookup service Client.java class is shown in CODE EXAMPLE 4-16.

CODE EXAMPLE 4-16 JNDI/LDAP Lookup Service Example Client.java

[...]

public class Client {

   private static boolean debug = false;

   public static void listAttributes(DirContext root, String dn)
     throws NamingException {
     final Attributes attrs = root.getAttributes(dn);
     System.out.println("dn: " + dn);
     System.out.println("attributes: " + attrs);
   }

   public static DirContext getRootContext() throws NamingException {
      final Hashtable env = new Hashtable();
      // Prepare environment map
      [...]

      InitialContext root = new InitialLdapContext(env,null);
      return (DirContext)(root.lookup(""));
   }

   // Confirm URL has not expired
  [...]

   public static List lookup(DirContext root, String protocolType,
                             String name)
      throws IOException, NamingException {
      final ArrayList list = new ArrayList();
      String queryProtocol =
         (protocolType==null)?"":"(jmxProtocolType="+protocolType+")";
      String query =
          "(&" + "(objectClass=jmxConnector) " +
          "(jmxServiceURL=*) " +
          queryProtocol +
          "(jmxAgentName=" + ((name!=null)?name:"*") + "))";

      SearchControls ctrls = new SearchControls();
      ctrls.setSearchScope(SearchControls.SUBTREE_SCOPE);
      final NamingEnumeration results = root.search("", query, ctrls);
      while (results.hasMore()) {
           final SearchResult r = (SearchResult) results.nextElement();
           debug("Found node: " + r.getName());
           final Attributes attrs = r.getAttributes();
           final Attribute attr = attrs.get("jmxServiceURL");
           if (attr == null) continue;
           final Attribute exp = attrs.get("jmxExpirationDate");
           if ((exp != null) && hasExpired((String)exp.get())) {
               System.out.print(r.getName() + ": ");
               System.out.println("URL expired since: " + exp.get());
               continue;
           }
           final String urlStr = (String)attr.get();
           if (urlStr.length() == 0) continue;

           debug("Found URL: "+ urlStr);

           final JMXServiceURL url = new JMXServiceURL(urlStr);
           final JMXConnector conn =
               JMXConnectorFactory.newJMXConnector(url,null);
           list.add(conn);
           if (debug) listAttributes(root,r.getName());
      }

      return list;

   }
}

In CODE EXAMPLE 4-16, the Client firstly returns a pointer root to the LDAP directory DirContext, then it searches through the directory for object classes of the type jmxConnector. The service URL and expiry date attributes, attr and exp respectively, for the jmxConnector object classes are obtained, exp is checked to make sure that the URL has not expired and a call is made to JMXConnectorFactory to create a new connector conn. The connector conn is added to the list of connectors and is used to access the MBeans in the MBean server created by Server.

4.4.1.3 jmx-schema.txt

The jmx-schema.txt file is the LDAP schema file for the JMX Remote API.

4.4.1.4 60jmx-schema.ldif

The 60jmx-schema.ldif file is an ldif file corresponding to the LDAP schema file, jmx-schema.txt, for JMX technology. If you are using Sun ONE Directory Server, this file can be copied directly to the config/schema directory of the Sun ONE Directory Server (see Section 4.4.2.1 "Setting up the JNDI/LDAP Lookup Service Example").

4.4.2 Running the JNDI/LDAP Lookup Service Example

In addition to the actions you performed in Section 4.1 "Initial Configuration", before you can run the lookup service examples that use the JNDI/LDAP lookup service, you must perform some further initial actions that are specific to this example. You can then start looking up connectors using the JNDI/LDAP network technology, in conjunction with the two connectors supported by the JMX technology.

When you run the examples, to help you keep track of which agent has been created with which transport, the agent names include a letter suffix that is the same as the lettering of the corresponding section. For example, the agent from Section a. "RMI connector over JRMP, without an external directory." is called test-server-a.

4.4.2.1 Setting up the JNDI/LDAP Lookup Service Example

The following steps are required by all of the different connector/transport combinations you can run in this example.

  1. Stop the LDAP server you started in Section 4.1 "Initial Configuration".

    2. Do this according to the type of LDAP server you are using.

  2. Copy the JMX technology schema into your LDAP server’s schema directory.

    3. For example, if you are using Sun ONE Directory Server 5.0, you would type:

    $ cp 60jmx-schema.ldif /var/ds5/slapd-<hostname>/config/schema

    Otherwise, do this according to the type of LDAP server you are using.

  3. Restart the LDAP server.

    4. Do this according to the type of LDAP server you are using.

  4. Define the root under which the Server will register its service URL.

    5. You must provide the Server with the path to the domain component suffix dc=Test that you created in Section 4.1 "Initial Configuration".

    $ provider="ldap://$ldaphost:$ldapport/dc=Test"

  5. Compile the Client and Server classes.

    6. $ javac -d . Server.java Client.java

4.4.2.2 Running the JNDI/LDAP Lookup Service Example With an RMI Connector

This example demonstrates the use of the JNDI/LDAP lookup service to look up RMI connector servers that use RMI’s default transport, JRMP, as well as the IIOP transport. In addition, as described in Section 4.1 "Initial Configuration", different external directories are used to register the RMI connector stubs.

The combinations of transports and external directories demonstrated here are:

  • RMI connector over the JRMP transport, with:
    • No external directory
    • An RMI registry
    • An LDAP registry
  • RMI connector over the IIOP transport, with:
    • No external directory
    • A CORBA naming service
    • An LDAP registry
  1. Start the Server.

    2. The command you use to start the Server varies according to which external directory you are using. You can start one or more of the following instances of Server with different transports and external registries before starting the Client.

    1. RMI connector over JRMP, without an external directory.

      2. Start Server by typing the following command:

$ java -classpath . -Ddebug=true \
  -Dagent.name=test-server-a \
  -Durl="service:jmx:rmi://" \
  -Djava.naming.provider.url="$provider" \
  -Djava.naming.security.principal="$principal" \
  -Djava.naming.security.credentials="$credentials" \
  jndi.Server &

      In this command:

      • debug is set to true to provide more complete screen output when the Server runs.
      • The name of the agent to be created is test-server-a.
      • The URL, provider, that points to the domain component suffix in which the agent will be registered, is given.
      • The common name attribute principal and password credentials are given to gain access to the LDAP server.
      • The service URL specifies that the chosen connector is an RMI connector, running over the RMI default transport JRMP.

      When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the JNDI/LDAP lookup service.

    2. RMI connector over JRMP, using an RMI registry as an external directory.

      3. Start Server by typing the following command:

$ java -classpath . -Ddebug=true \
  -Dagent.name=test-server-b \
  -Durl="service:jmx:rmi:///jndi/${jndirmi}/server" \
  -Djava.naming.provider.url="$provider" \
  -Djava.naming.security.principal="$principal" \
  -Djava.naming.security.credentials="$credentials" \
  jndi.Server &

      In this command:

      • The name of the agent created is test-server-b.
      • The URL, provider, that points to the domain component suffix in which the agent will be registered, is given.
      • The common name attribute principal and password credentials are given to gain access to the LDAP server.
      • The service URL specifies the chosen connector as RMI over JRMP, and the external directory in which the RMI connector stub, server, is stored is the RMI registry you identified as jndirmi in Section 4.1 "Initial Configuration".

      When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the JNDI/LDAP lookup service.

    3. RMI connector over JRMP, using LDAP as the external directory.

      4. Start Server by typing the following command:

$ java -classpath . -Ddebug=true \
  -Dagent.name=test-server-c \
  -Durl="service:jmx:rmi:///jndi/${jndildap}/cn=x,dc=Test" \
  -Djava.naming.provider.url="$provider" \
  -Djava.naming.security.principal="$principal" \
  -Djava.naming.security.credentials="$credentials" \
  jndi.Server &

      In this command:

      • The name of the agent created is test-server-c.
      • The URL, provider, that points to the domain component suffix in which the agent will be registered, is given.
      • The common name attribute principal and password credentials are given to gain access to the LDAP server.
      • The service URL specifies the chosen connector as RMI over JRMP, and the external directory in which the RMI connector stub is stored is the LDAP server you identified as jndildap in Section 4.1 "Initial Configuration".

      When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the JNDI/LDAP lookup service under the agent name test-server-c.

    4. RMI connector over IIOP, without an external directory.

      5. Start Server by typing the following command:

$ java -classpath . -Ddebug=true \
  -Dagent.name=test-server-d \
  -Durl="service:jmx:iiop://" \
  -Djava.naming.provider.url="$provider" \
  -Djava.naming.security.principal="$principal" \
  -Djava.naming.security.credentials="$credentials" \
  jndi.Server &

      In this command:

      • The name of the agent created is test-server-d.
      • The URL, provider, that points to the domain component suffix in which the agent will be registered, is given.
      • The common name attribute principal and password credentials are given to gain access to the LDAP server.
      • The service URL specifies that the chosen connector is an RMI connector, running over IIOP.

      When the Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its automatically generated URL in the JNDI/LDAP lookup service.

    5. RMI connector over IIOP, using CORBA naming as the external directory.

      6. Start Server by typing the following command:

$ java -classpath . -Ddebug=true \
  -Dagent.name=test-server-e \
  -Durl="service:jmx:iiop:///jndi/${jndiiiop}/server" \
  -Djava.naming.provider.url="$provider" \
  -Djava.naming.security.principal="$principal" \
  -Djava.naming.security.credentials="$credentials" \
  jndi.Server &

      In this command:

      • The name of the agent created is test-server-e.
      • The URL, provider, that points to the domain component suffix in which the agent will be registered, is given.
      • The common name attribute principal and password credentials are given to gain access to the LDAP server.
      • The service URL specifies the chosen connector as RMI connector over IIOP, and the external directory in which the RMI connector stub, server, is stored is the CORBA naming service you identified as jndiiiop in Section 4.1 "Initial Configuration".

      When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the JNDI/LDAP lookup service under the name test-server-e.

    6. RMI connector over IIOP, using LDAP as the external directory.

      7. Start Server by typing the following command:

$ java -classpath . -Ddebug=true \
  -Dagent.name=test-server-f \
  -Durl="service:jmx:iiop:///jndi/${jndildap}/cn=x,dc=Test" \
  -Djava.naming.provider.url="$provider" \
  -Djava.naming.security.principal="$principal" \
  -Djava.naming.security.credentials="$credentials" \
  jndi.Server &

      In this command:

      • The name of the agent created is test-server-f.
      • The URL, provider, that points to the domain component suffix in which the agent will be registered, is given.
      • The common name attribute principal and password credentials are given to gain access to the LDAP server.
      • The service URL specifies the chosen connector as RMI over IIOP, and the external directory in which the RMI connector stub is stored is the LDAP server you identified as jndildap in Section 4.1 "Initial Configuration".

      When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the JNDI/LDAP lookup service under the agent name test-server-f.

  2. Start the Client.

    3. After starting the Server using the transport and external directory of your choice, start the Client:

$ java -classpath . -Ddebug=true \
  -Djava.naming.provider.url="$provider" \
  -Djava.naming.security.principal="$principal" \
  -Djava.naming.security.credentials="$credentials" \
  jndi.Client

    You will see output confirming the detection of the agents created by the Server and registered in the lookup service. You will also see the identification and confirmation of the connection made to the agents.

    To look up a specific agent, type the following command:

$ java -classpath . -Ddebug=true \
  -Djava.naming.provider.url="$provider" \
  -Djava.naming.security.principal="$principal" \
  -Djava.naming.security.credentials="$credentials" \
  -Dagent.name=agentName \
  jndi.Client

    In the command shown above, agentName is the name of the agent you want to look up. You can also specify a partial agent name by using *; for example, x* for all agent names beginning with the letter x.

Contents | Previous | Next Java Management Extensions (JMX) Technology Tutorial
Java Management Extensions (JMX), Java Platform, Standard Edition 6

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.


Preface

The Java Management Extensions (JMX) Technology Tutorial provides examples of how to use the main features of the JMX technology that is provided with the Java Platform, Standard Edition (Java SE).

Before You Read This Book

The Java Management Extensions (JMX) Technology Tutorial demonstrates the concepts and technology that are introduced in the Java Management Extensions (JMX) Technology Overview. You should, therefore, read the overview before attempting to work through this tutorial. To make full use of the information in this tutorial, you should be familiar with the following protocols and specifications:

  • Remote Method Invocation (RMI)
  • Lightweight Directory Access Protocol (LDAP)
  • Service Location Protocol (SLP)
  • JiniTM Network Technology
  • Java Naming and Directory InterfaceTM (JNDI) API
  • Java Secure Socket Extension (JSSE)
  • Java Authentication and Authorization Service (JAAS)

How This Book Is Organized

This tutorial provides examples in broad categories, presented in the following chapters.

  • Chapter 1, "Getting Started" gives you some initial configuration information.
  • Chapter 2, "Essentials of the JMX API" introduces the core notions of the JMX specification.
  • Chapter 3, "JMX Connectors" provides examples of how to implement the standard and dynamic types of MBean, and perform operations on them both locally and remotely.
  • Chapter 4, "Lookup Services" demonstrates the lookup services that can be used in conjunction with the JMX technology.
  • Chapter 5, "Security" shows some examples of security configurations.

Related Documentation

This tutorial is accompanied by the following documents:

  • Java Management Extensions Technology Overview
  • Java Management Extensions Specification 1.4

About This Tutorial

As previously stated, this tutorial demonstrates some of the concepts that are described in the Java Management Extensions (JMX) Technology Overview. This tutorial is intended to be read in order, from beginning to end, working through the examples as you go. Actions you perform at the beginning of the tutorial might be required parts of subsequent examples. Consequently, starting mid-way through the tutorial might cause you to skip actions required by certain examples.

Where you are required to perform a task, the instructions are presented in bold text and marked with an action number; sub-tasks are marked with a lower-case letter, as shown in the following example:

  1. Perform a task.

    2. Description of how to perform that task.

    1. Perform a sub-task.

      2. Description of how to perform that sub-task.

  2. Perform another task.

    3. And so on

Typographic Conventions

Typeface | Meaning | Examples
AaBbCc123 | The names of commands, files, and directories; on-screen computer output | Edit your .login file. Use ls -a to list all files. % You have mail.
AaBbCc123 | What you type, when contrasted with on-screen computer output | % su Password:
AaBbCc123 | Book titles, new words or terms, words to be emphasized Command-line variable; replace with a real name or value | Read Chapter 6 in the User’s Guide. These are called class options. You must be superuser to do this. To delete a file, type rm filename.

Shell Prompts

Shell | Prompt
C shell | machine_name%
C shell superuser | machine_name#
Bourne shell and Korn shell | $
Bourne shell and Korn shell superuser | #

Sun Welcomes Your Comments

We are interested in improving our documentation and welcome your comments and suggestions. You can email your comments to us via the Sun Developer Network feedback page .

Accessing Sun Documentation On-line

You can access Sun Documentation at the following location.

  • http://www.sun.com/documentation.

    • Contents | Previous | Next Java Management Extensions (JMX) Technology Tutorial
    Java Management Extensions (JMX), Java Platform, Standard Edition 6

    Copyright © 2006 Sun Microsystems, Inc. All rights reserved.


Contents | Previous | Next Java Management Extensions (JMX) Technology Tutorial

Chapter 5

Security

This chapter gives examples of how to set up the JMX technology security features, as described in the following sections:

  • Section 5.1 "Simple Security" presents examples of connectors that implement straightforward security based on password authentication and file access control.
  • Section 5.2 "Subject Delegation" presents examples of connectors that use the subject delegation model to perform operations on a given authenticated connection on behalf of several different identities.
  • Section 5.3 "Fine-Grained Security" presents examples of connectors that implement more sophisticated security mechanisms, in which permission to perform individual operations is controlled.

5.1 Simple Security

The simplest type of security you can use with the JMX technology is based upon encryption, user name and password authentication, and file access control.

5.1.1 RMI Connectors With Simple Security

You can find an example of an RMI connector with simple security in the directory work_dir/jmx_examples/Security/simple.

  1. Open the work_dir/jmx_examples/Security/simple directory.

    2. Inside this directory you will find the following directories:

    • /server, containing the fileServer.java
    • /config, containing the security configuration files:
      • access.properties
      • keystore
      • password.properties
      • truststore
    • /mbeans, containing the following files:
      • SimpleStandardMBean.java
      • SimpleStandard.java
    • /client, containing the following files:
      • Client.java
      • ClientListener.java
  2. Open all the *.java and *.properties files in a text editor

    3. These files will be analyzed in the following sections.

5.1.1.1 Server.java

The Server.java class is shown in CODE EXAMPLE 5-1.

CODE EXAMPLE 5-1 RMI Connector Example (Simple Security) Class Server.java

public class Server {

  public static void main(String[] args) {
  try {
       MBeanServer mbs = MBeanServerFactory.createMBeanServer();

       HashMap env = new HashMap();

       SslRMIClientSocketFactory csf =
                  new SslRMIClientSocketFactory();
       SslRMIServerSocketFactory ssf =
                  new SslRMIServerSocketFactory();
       env.put(RMIConnectorServer.
                  RMI_CLIENT_SOCKET_FACTORY_ATTRIBUTE,csf);
       env.put(RMIConnectorServer.
                  RMI_SERVER_SOCKET_FACTORY_ATTRIBUTE,ssf);

       env.put("jmx.remote.x.password.file",
                 "config" + File.separator + "password.properties");
       env.put("jmx.remote.x.access.file",
                 "config" + File.separator + "access.properties");

       JMXServiceURL url = new JMXServiceURL(
        "service:jmx:rmi:///jndi/rmi://localhost:9999/server");
         JMXConnectorServer cs =
            JMXConnectorServerFactory.newJMXConnectorServer(url,
                                                            env,
                                                            mbs);
       cs.start();
     } catch (Exception e) {
       e.printStackTrace();
     }
  }
}

The Server class shown in CODE EXAMPLE 5-1 creates an MBean server mbs, and populates an environment map env with a secure RMI client socket factory csf, a secure RMI server socket factory ssf, and the properties files password.properties and access.properties.

The properties file password.properties contains a username and password and is accessed using the JMX Remote API interface JMXAuthenticator. Using the property jmx.remote.x.password.file is the same as creating a password-based JMXAuthenticator and passing it into the environment map through the jmx.remote.authenticator property.

The properties file access.properties contains a username and a level of access permission that can be either readwrite or readonly. This represents the level of access this user can have to MBean server operations. This file-based access control is implemented using the JMX technology interface MBeanServerForwarder, which wraps the real MBean server inside an access controller MBean server. The access controller MBean server only forwards requests to the real MBean server after performing the appropriate checks.

Server creates a JMX service URL, named url, for an RMI connector that will operate over the default JRMP transport, and register an RMI connector stub in an RMI registry on port 9999 of the local host.

The MBean server mbs, the environment map env and the service URL url are all passed to JMXConnectorServer to create a new, secure JMX connector server named cs.

5.1.1.2 SimpleStandardMBean.java

The SimpleStandardMBean class defines the same straightforward MBean interface as was used in Chapter 3, "JMX Connectors".

5.1.1.3 SimpleStandard.java

The SimpleStandard class defines the same straightforward MBean as was used in Chapter 3, "JMX Connectors".

5.1.1.4 ClientListener.java

The ClientListener class defines the same straightforward notification listener as was used in Chapter 3, "JMX Connectors".

5.1.1.5 Client.java

The Client.java class is shown in CODE EXAMPLE 5-2.

CODE EXAMPLE 5-2 RMI Connector Example (Simple Security) Class Client.java

public class Client {

  public static void main(String[] args) {
  try {
      HashMap env = new HashMap();

      String[] credentials = new String[] { "username" , "password" };
      env.put("jmx.remote.credentials", credentials);
      JMXServiceURL url = new JMXServiceURL(
         "service:jmx:rmi:///jndi/rmi://localhost:9999/server");
      JMXConnector jmxc = JMXConnectorFactory.connect(url, env);
      MBeanServerConnection mbsc = jmxc.getMBeanServerConnection();
      String domains[] = mbsc.getDomains();
      for (int i = 0; i < domains.length; i++) {
         System.out.println("Domain[" + i + "] = " + domains[i]);
      }

      ObjectName mbeanName =
          new ObjectName("MBeans:type=SimpleStandard");
      mbsc.createMBean("SimpleStandard", mbeanName, null, null);
      // Perform MBean operations
      [...]

      mbsc.removeNotificationListener(mbeanName, listener);
      mbsc.unregisterMBean(mbeanName);
      jmxc.close();
    }  catch (Exception e) {
      e.printStackTrace();
    }
  }
}

The Client class shown in CODE EXAMPLE 5-2 populates an environment map env with a set of credentials, namely the username and password expected by the Server. These credentials are then given to an instance of JMXConnector named jmxc when the service URL of the connector stub and the environment map are passed to JMXConnectorFactory.connect(). Through jmxc, the Client connects to the MBean server started by Server, and performs MBean operations.

When the connection is established, the credentials supplied in the environment map env are sent to the server. The server then calls the authenticate() method of the JMXAuthenticator interface, passing the client credentials as parameters. The authenticate() method authenticates the client and returns a subject that contains the set of principals upon which the access control checks will be performed.

5.1.2 Running the RMI Connector Example With Simple Security

To run the RMI connector example with simple security, perform the following steps:

  • $ javac
      mbeans/SimpleStandard.java \
      mbeans/SimpleStandardMBean.java \
      server/Server.java \
      client/Client.java \
      client/ClientListener.java
  • Start an RMI registry on port 9999 of the local host.
    •
$ export CLASSPATH=server ; rmiregistry 9999 &
  • Start the Server.
    •
$ java -classpath server:mbeans \
     -Djavax.net.ssl.keyStore=config/keystore \
     -Djavax.net.ssl.keyStorePassword=password \
     Server &

    You will see confirmation of the creation of the MBean server and of the RMI connector.

  • Start the Client.
    •
$java -classpath client:server:mbeans \
     -Djavax.net.ssl.trustStore=config/truststore \
     -Djavax.net.ssl.trustStorePassword=trustword \
     Client

    You will see confirmation of the creation of the connector client, the various MBean operations followed by the closure of the connection.

    As you can see, all the above appears to proceed in exactly the same manner as the basic RMI connector example shown in Chapter 3, "JMX Connectors". However, if you were to open password.properties and change the password, you would see a java.lang.SecurityException when you launched the Client, and the connection would fail.

    5.2 Subject Delegation

    If your implementation requires the client end of the connection to perform different operations on behalf of multiple users or applications, using the security mechanisms demonstrated in Section 5.1 "Simple Security", each different user would require one secure connection for every operation it performs. If you expect your connector clients to interact with numerous users, you can reduce the load on your system by implementing subject delegation. Subject delegation establishes a single secure connection for a user, and this connection can be used to perform related operations on behalf of any number of users. The connection itself is made by an authenticated user. If the authenticated user has been granted a SubjectDelegationPermission that allows it to act on behalf of another user, then operations can be performed over the connection on behalf of that user.

    5.2.1 Secure RMI Connectors With Subject Delegation

    You can find an example of a secure RMI connector that implements subject delegation in the directory work_dir/jmx_examples/Security/subject_delegation.

    1. Open the work_dir/jmx_examples/Security/subject_delegation directory

      2. Inside this directory you will find the following directories:

      • /server, containing the file Server.java:
      • /config, containing the security configuration files:
        • access.properties
        • java.policy
        • password.properties
      • /mbeans, containing the following files:
        • SimpleStandardMBean.java
        • SimpleStandard.java
      • /client, containing the following files:
        • Client.java
        • ClientListener.java
    2. Open all the *.java and *.properties files in a text editor

      3. These files will be analyzed in the following sections.

    5.2.1.1 Server.java

    The Server.java class is shown in CODE EXAMPLE 5-3:

    CODE EXAMPLE 5-3 Secure RMI Connector (Subject Delegation) Example Class Server.java

public class Server {

   public static void main(String[] args) {
     try {
          MBeanServer mbs = MBeanServerFactory.createMBeanServer();
          HashMap env = new HashMap();
          env.put("jmx.remote.x.password.file",
                  "config" + File.separator + "password.properties");
          env.put("jmx.remote.x.access.file",
                  "config" + File.separator + "access.properties");

          JMXServiceURL url = new JMXServiceURL(
             "service:jmx:rmi:///jndi/rmi://localhost:9999/server");
          JMXConnectorServer cs =
              JMXConnectorServerFactory.newJMXConnectorServer(url, env, mbs);
          cs.start();
     } catch (Exception e) {
          e.printStackTrace();
     }
   }
}

    CODE EXAMPLE 5-3 begins with the creation of an MBean server mbs, and the population of an environment map env with a password file and an access file, called password.properties and access.properties respectively:

    • The password file contains a username and password combination that is used to authenticate users that try to make connections.
    • The access file contains a user name and access level combination that is used to authorize access to the MBeans in the MBean server. The access level is either readwrite or readonly.

    The Server then creates a connector server named cs, and starts it in exactly the same way as in the previous RMI connector examples.

    5.2.1.2 java.policy

    The java.policy file grants to username a SubjectDelegationPermission so it can perform operations on behalf of the user delegate, an instance of JMXPrincipal created by the Client class. The java.policy file is required when launching the Server class.

    5.2.1.3 SimpleStandardMBean.java

    The SimpleStandardMBean class defines the same straightforward MBean interface as was used in the previous examples.

    5.2.1.4 SimpleStandard.java

    The SimpleStandard class defines the same straightforward MBean as was used in the previous examples.

    5.2.1.5 ClientListener.java

    The ClientListener class defines the same straightforward notification listener as was used in the previous examples.

    5.2.1.6 Client.java

    The Client.java class is shown in CODE EXAMPLE 5-4:

    CODE EXAMPLE 5-4 Secure RMI Connector (Subject Delegation) Example Class Client.java

public class Client {

  public static void main(String[] args) {
    try {
         HashMap env = new HashMap();
         String[] credentials = new String[] { "username" , "password" };
         env.put("jmx.remote.credentials", credentials);
         JMXServiceURL url = new JMXServiceURL(
            "service:jmx:rmi:///jndi/rmi://localhost:9999/server");
         JMXConnector jmxc = JMXConnectorFactory.connect(url, env);
         Subject delegationSubject =
            new Subject(true,
                Collections.singleton(new JMXPrincipal("delegate")),
                Collections.EMPTY_SET,
                Collections.EMPTY_SET);

         MBeanServerConnection mbsc =
            jmxc.getMBeanServerConnection(delegationSubject);
         String domains[] = mbsc.getDomains();
         ObjectName mbeanName =
            new ObjectName("MBeans:type=SimpleStandard");
         mbsc.createMBean("SimpleStandard", mbeanName, null, null);
         // Perform MBean operations
         //

[...]
         mbsc.removeNotificationListener(mbeanName, listener);
         mbsc.unregisterMBean(mbeanName);
         jmxc.close();
     } catch (Exception e) {
         e.printStackTrace();
     }
  }
}

    CODE EXAMPLE 5-4 begins with the creation of an environment map env that is populated with a user name username and a password password. These strings match the user name and password stored in the password.properties file that is held by the Server to authenticate users accessing the connector server.

    A JMX technology connector client jmxc is created in the same way as in the previous RMI connector examples, with the user name and password passed into the environment map env.

    The Client then creates an instance of Subject, called delegationSubject, with a Principal that is an instance of JMXPrincipal, named delegate.

    An MBean server connection, named mbsc, is created by calling the getMBeanServerConnection() method of JMXConnector, with delegationSubject passed in as a parameter. This MBean server connection therefore allows operations to be performed on the remote MBean server on behalf of the principals stored in the delegationSubject, which in this example is the JMXPrincipal named delegate.

    The example continues by creating and registering the SimpleStandard MBean in the MBean server, and performing operations on it, in exactly the same way as in the previous examples.

    5.2.2 Running the Secure RMI Connector Example With Subject Delegation

    To run the secure RMI connector example with subject delegation, perform the following steps:

    $ javac  mbeans/SimpleStandard.java \
  mbeans/SimpleStandardMBean.java \
  server/Server.java \
  client/Client.java \
  client/ClientListener.java
  • Start an RMI registry on port 9999 of the local host.

    • $ export CLASSPATH=server ; rmiregistry 9999 &

  • Start the Server.
    • $ java -classpath server:mbeans \
  -Djava.security.policy=config/java.policy Server &

    You will see confirmation of the creation of the MBean server, the initialization of the environment map, the creation of the RMI connector, and the registration of the connector in the MBean server.

  • Start the Client.

    • $ java -classpath client:server:mbeans Client

    You will see confirmation of the creation of the connector client, the creation of the delegation subject, the connection to the MBean server and the various MBean operations followed by the closure of the connection.

    5.3 Fine-Grained Security

    You can implement a more fine-grained level of security in your connectors by managing user access through the Java Authentication and Authorization Service (JAAS) and Java platform Standard Edition (Java SE) Security Architecture. JAAS and Java SE security is based on the use of security managers and policy files to allocate different levels of access to different users. Consequently, you can decide more precisely which users are allowed to perform which operations.

    The two examples in this section are very similar to those shown in Section 5.1 "Simple Security", with the difference being that the simple, file-based access control has been replaced by policy-based access control.

    5.3.1 RMI Connectors With Fine-Grained Security

    You can find an example of an RMI connector with fine-grained security in the directory work_dir/jmx_examples/Security/fine_grained.

    1. Open work_dir/jmx_examples/Security/fine_grained.

      2. Inside this directory you will find the following directories:

      • /server, containing the fileServer.java
      • /config, containing the security configuration files:
        • java.policy
        • keystore
        • password.properties
        • truststore
      • /mbeans, containing the following files:
        • SimpleStandard.java
        • SimpleStandardMBean.java
      • /client, containing the following files:
        • ClientListener.java
        • Client.java
    2. Open all the *.java and *.properties files in a text editor.

      3. 5.3.1.1 The files will be analyzed in the following sections.Server.java

      The Server.java class used in this example is very similar to the one used in the RMI connector example with simple security. The only difference is that there is no access.properties file to map into the environment map in the fine-grained example. Otherwise, the two classes are identical.

      5.3.1.2 java.policy

      The java.policy file grants the following permissions:

      • All permissions to the server code base, so that the connector server can create the connectors, and then perform the operations requested by remote user calls
      • MBeanTrustPermission to the mbeans code base, allowing trusted MBeans to register in the MBean server
      • Permission to perform the various MBean and MBean server operations for the user represented by a JMXPrincipal named username.

      5.3.1.3 SimpleStandardMBean.java

      The SimpleStandardMBean class defines the same straightforward MBean interface as was used in the previous examples.

      5.3.1.4 SimpleStandard.java

      The SimpleStandard class defines the same straightforward MBean as was used in the previous examples.

      5.3.1.5 ClientListener.java

      The ClientListener class defines the same straightforward notification listener as as was used in the previous examples.

      5.3.1.6 Client.java

      The Client.java class is exactly the same as the one used in the RMI connector example with simple security.

      5.3.2 Running the RMI Connector Example With Fine-Grained Security

      To run the RMI connector example with fine-grained security, perform the following steps:

      $ javac
      mbeans/SimpleStandard.java \
      mbeans/SimpleStandardMBean.java \
      server/Server.java \
      client/Client.java \
      client/ClientListener.java
    3. Start an RMI registry on port 9999 of the local host.

      4. $ export CLASSPATH=server ; rmiregistry 9999 &

    4. Start the Server.
      5. $ java -classpath server:mbeans \
     -Djavax.net.ssl.keyStore=config/keystore \
     -Djavax.net.ssl.keyStorePassword=password \
     -Djava.security.manager \
     -Djava.security.policy=config/java.policy \
     Server &

      You will see confirmation of the initialization of the environment map, the creation of the MBean server and of the RMI connector.

    5. Start the Client.
      6.
$ java -classpath client:server:mbeans \
     -Djavax.net.ssl.trustStore=config/truststore \
     -Djavax.net.ssl.trustStorePassword=trustword \
     Client

      You will see confirmation of the creation of the connector client, the connection to the RMI server and the various MBean operations followed by the closure of the connection.

    Contents | Previous | Next Java Management Extensions (JMX) Technology Tutorial
    Java Management Extensions (JMX), Java Platform, Standard Edition 6

    Copyright © 2006 Sun Microsystems, Inc. All rights reserved.


Guidelines for LDAP Service Providers

JNDI Implementor Guidelines for LDAP Service Providers

Draft 0.4.2

Please send feedback to jndi@java.sun.com

Table of Contents
1. Introduction
2. Conformance
3. Environment Properties
4. Names
5. Attributes
6. URLs
7. Java Objects
8. Schema
9. Exceptions
10. API Mapping
11. Federation
12. SASL
13. Extensions and Controls
14. Event Notification
15. SSL

1. Introduction

This document specifies guidelines that developers creating LDAP service providers and service providers that support LDAP-like features should follow. By following these guidelines, developers can produce implementations that JNDI API users can configure and use with minimal differences.

Not all of the features described in this document must be supported by an LDAP service provider. However, if a feature is supported, it should be supported in the way described by this document.

2. Conformance

An LDAP service provider that supports LDAP version 3 (LDAPv3) conforms to:
  • RFC 2251 and related specifications.
An LDAP service provider that supports LDAP version 2 (LDAPv2) conforms to:
  • RFC 1777 and related specifications.

3. Environment Properties

Environment properties are the means by which JNDI application users configure and affect the behavior of JNDI service providers. Consequently, service providers must interpret and handle environment properties in the same way.

There are four types of environment properties that affect LDAP service providers:

  • Standard JNDI environment properties
  • LDAP-specific environment properties
  • Provider-specific environment properties
  • Feature-specific environment properties

3.1 Overview

3.1.1 Initialization

When creating an initial context, environment properties can be passed as an argument to the constructor or may be initialized as specified in the JNDI documentation.

In particular, if any of the following properties is not supplied in the environment properties then it is sought from the system properties, applet parameters, and both provider and application resource files (in that order):

  • java.naming.factory.control
  • java.naming.factory.initial
  • java.naming.factory.object
  • java.naming.factory.state
  • java.naming.provider.url
In the case of the control, object and state factory properties, if more than one occurrence of the property is located, then its values are concatenated into a single list. In the case of the url property and all other properties, only the first occurrence is used.

A context's environment properties can be examined using the Context.getEnvironment method.

3.1.2 Modification

A context's environment properties may be changed using the Context.addToEnvironment and Context.removeFromEnvironment methods.

3.1.3 Scope

With the exception of the java.naming.provider.url and java.naming.factory.initial properties, changing a property using the Context.addToEnvironment or Context.removeFromEnvironment methods affects the context instance on which the method is invoked. For example, if you specify new credentials for a context to use, subsequent methods invoked on that context that require communication with the server will use those new credentials (perhaps internally by first creating a new connection to the server). These updated environment properties are inherited by context instances that are subsequently derived from the affected context instance, but do not otherwise affect other context instances that were in existence prior to the update.

3.1.4 Timeliness

When a change is made to the environment properties, there is no requirement that the change be verified and acted upon at the time the Context.addToEnvironment or Context.removeFromEnvironment method is invoked. The only requirement is that the change (or changes) be effective the next time an operation that uses that property is invoked.

3.1.5 Defaults

This specification defines defaults for the environment properties. In a few cases, the default is determined by the service provider. If a context does not have a particular environment property, it behaves as if it has that environment property with its default value.

When a property is removed from the environment properties of a context, the context assumes the default behavior specified for that property. This does not necessarily mean that the default value must be recorded as the property's value. The removal may also be indicated by the absence of the property from the context's environment properties.

3.1.6 Acceptable Values

This specification defines acceptable values for the environment properties. Some environment properties have a fixed set of acceptable values while others have values that must follow a particular syntax. If an unacceptable value is presented, a property-specific exception will be thrown (for example, ConfigurationException, IllegalArgumentException, or AuthenticationNotSupportedException). In some cases, it might be reasonable for the service provider to accept additional values than those specified, in which case, those values should be documented.

3.2 JNDI Properties

LDAP service providers should process the JNDI environment properties according to the following specifications. In the examples given, env is an instance of Hashtable that holds the environment properties used to create an initial context.

java.naming.batchsize
The value of this property is a string of decimal digits that specifies the batch size of search results returned by the server.

This property affects the blocking behaviour of the Context.list, Context.listBindings, and DirContext.search methods and the NamingEnumeration objects that they return. It does not affect how many items are returned in the enumeration; it only affects how the items are batched or read at the LDAP protocol level.

A setting of zero means that the provider should block until all results have been received. A setting of an integer n greater than zero means that the provider should block until n results have been received from the server or until the enumeration terminates, whichever produces the fewer number of results. After the application has read n results (using NamingEnumeration.next or NamingEnumeration.nextElement), the provider should read n more results from the server or until the enumeration terminates, whichever produces the fewer number of results.

If this property is not set then its default value is implementation-specific.

For example,

env.put(Context.BATCHSIZE, "24");
specifies that the provider should block until 24 entries have been read from the server or until the enumeration terminates, whichever produces the fewer number of results.
java.naming.factory.control
The value of this property is a colon-separated list of fully qualified class names of control factory classes.

The factories are responsible for narrowing the class of response controls. They create specific response controls from the generic response controls generated by the provider.

No default value is defined for this property.

For example,

env.put(LdapContext.CONTROL_FACTORIES,
        "com.sun.jndi.ldap.ctl.ResponseControlFactory");
sets the ResponseControlFactory class as the control factory to try.
java.naming.factory.initial
The value of this property is the fully qualified class name of the factory class which creates the initial context for the LDAP service provider.

It is used to select a particular LDAP service provider; it's not actually used by the provider itself. This property need not be set when the name argument to initial context methods is a URL.

No default value is defined for this property.

For example,

env.put(Context.INITIAL_CONTEXT_FACTORY,
        "com.sun.jndi.ldap.LdapCtxFactory");
selects Sun's LDAP provider.
java.naming.factory.object
The value of this property is a colon-separated list of fully qualified class names of object factory classes.

The factories are responsible for creating specific objects from the LDAP entries returned by the provider. For example, a Person object factory might generate a Person object from an LDAP entry of object class person. Object factories behave in the opposite way to state factories in that they generate objects from LDAP attributes.

No default value is defined for this property.

For example,

env.put(Context.OBJECT_FACTORIES,
        "com.sun.jndi.ldap.obj.PersonFromLDAP");
sets the PersonFromLDAP class as the object factory to try.
java.naming.factory.state
The value of this property is a colon-separated list of fully qualified class names of state factory classes.

The factories are responsible for creating an object's state (for storing) from the object itself. For example, a Person state factory might generate an LDAP entry of object class person from a Person object. State factories behave in the opposite way to object factories in that they generate LDAP attributes from objects.

No default value is defined for this property.

For example,

env.put(Context.STATE_FACTORIES,
        "com.sun.jndi.ldap.obj.PersonToLDAP");
sets the PersonToLDAP class as the state factory to try.
java.naming.language
The value of this property is a string language tag according to RFC 1766.
This property indicates a preference for a particular natural language. A provider may adjust its LDAP requests and responses according to the value of this property.

The affect of this property is implementation-specific. No default value is defined.

For example:

env.put(Context.LANGUAGE, "ja-JP");
indicates a preference for Japanese.
java.naming.provider.url
The value of this property is a list of space-separated LDAP or LDAPS URL strings, each of which specifies the hostname and port number of the LDAP server, and the root distinguished name of the naming context to use. An LDAP URL specifies the use of a plain (i.e., unprotected) connection; an LDAPS URL specifies the use of an SSL connection. If the list contains more than one URL, the provider should attempt to use each URL in turn until it is able to create a successful connection, and after creation, set the property to the successful URL.

The default hostname is localhost; the default port is 389 for plain connections and 636 for SSL connections. The default root distinguished name is the empty string. If this property is not set, or if either the hostname or port number is omitted, then the default values are used in place of the missing information. If both the hostname and port are missing but a non-empty distinguished name is present in the URL, then the provider should use the distinguished name to determine the hostname and port of the LDAP server(s) as described in the URLs section and when a connection has been established successfully, set the java.naming.provider.url property to a URL constructed using the successful hostname, port and distinguished name. See also the URLs section for information on how the provider should treat other information found in the URL.

For example:

env.put(Context.PROVIDER_URL, "ldap://secserver:636");
specifies that the LDAP server is running on a host named secserver at port 636.

NOTE: Changing this property using the Context.addToEnvironment or Context.removeFromEnvironment methods does not affect the context. It is only used by the initial context constructors.

java.naming.referral
The value of this property is a string that specifies how referrals shall be handled by the provider. The following values are defined for this property:
follow
automatically follow any referrals.
throw
throw a ReferralException for each referral.
ignore
ignore referrals if they appear in results. A PartialResultException is thrown to indicate an incomplete result. In addition, for LDAPv3 servers, the provider shall request that referrals be treated as ordinary attributes when they appear in entries. This is achieved by sending a non-critical ManageDsaIT (RFC 3296) LDAP control with each LDAP request. LDAP servers which do not support this LDAP control will simply ignore it and process the request as normal.

See the URLs section for information on how to treat multiple URLs found in a single referral entry.

If this property is not set then its default value is ignore.

For example:

env.put(Context.REFERRAL, "throw");
specifies that referrals encountered during an LDAP operation should throw a ReferralException to the application.
java.naming.security.authentication
The value of this property is a string that specifies the authentication mechanism(s) for the provider to use. The following values are defined for this property:
none
use no authentication (anonymous bind).
simple
use simple authentication (a cleartext password).
A space-separated list of one or more SASL mechanism names:
use the first available SASL mechanism in the list that conforms to the specified policy requirements

See the SASL section for information on how this property is used for SASL authentication. See RFC 2829 for information on LDAP authentication mechanisms.

If this property is not set then its default value is none, unless the java.naming.security.credentials property is set, in which case the default value is simple. If this property is set to a value that the provider does not recognize or support, it should throw AuthenticationNotSupportedException.

For example:

env.put(Context.SECURITY_AUTHENTICATION, "simple");
specifies that simple authentication be used to authenticate to the LDAP server. Or,
env.put(Context.SECURITY_AUTHENTICATION, "DIGEST-MD5 CRAM-MD5");
specifies that DIGEST-MD5 authentication be used and, if that SASL mechanism is unavailable, that CRAM-MD5 authentication be used. If neither is available then throw AuthenticationNotSupportedException.
java.naming.security.credentials
The value of this property is an object that specifies the credentials of the principal to be authenticated. Its format and handling depends on the value of the java.naming.security.authentication property.

For anonymous binds, this property is ignored - an empty string is always used for the credentials. For simple authentication and SASL authentication that requires a password, the value of this property may be supplied as a java.lang.String, a char[] or a byte[]. If it is a String or a char[] then it is encoded into a byte array using UTF-8 in the case of LDAPv3 and encoded using ISO-Latin-1 in the case of LDAPv2. If it is a byte[] then it is used as is.

See the SASL section for information on how this property is used for SASL authentication.

No default value is defined for this property.

For example:

env.put(Context.SECURITY_CREDENTIALS, "secret");
sets the credentials to be the string "secret".
java.naming.security.principal
The value of this property is a string that specifies the identity of the principal to be authenticated. Its format depends on the authentication type; see RFC 2829 for more information. The value is used as the name component in an LDAP ASN.1 BindRequest for non-SASL authentication. For SASL authentication, the value of this property is used as the authentication ID for SASL mechanisms that need an authentication ID.

The provider is not required to verify the validity of the principal name. It may, for example, just pass the string to be verified by the server. If the principal identified is not a valid principal then the provider shall throw an AuthenticationException.

No default value is defined for this property.

For example:

env.put(Context.SECURITY_PRINCIPAL, "cn=admin,o=sun,c=us");
sets the principal name to be the distinguished name "cn=admin, o=sun, c=us".
java.naming.security.protocol
The value of this property is a string that specifies the security protocol for the provider to use. The following value is defined for this property:
ssl
use Secure Sockets Layer version 3.0.

If this property is set to ssl, the provider must use SSL sockets, or throw ConfigurationException if it is unable to do so. In addition to the value listed above, a provider may support other security protocols. However, such provider-specific protocols might not be supported by all providers. If this property is set to a security protocol that the provider does not recognize or support, it should throw ConfigurationException.

If the java.naming.ldap.factory.socket property is set, then the socket factory identified by that property must create sockets that are appropriate for this protocol setting. For example, if the security protocol is set to ssl, then the socket factory must create SSL-compliant sockets.

If this property is not set then the default is to use no security protocol.

As a developer of the LDAP provider, you should be aware that using SSL to connect to a server on a port that is not listening for SSL connections causes the socket to hang. Similarly, using a plain socket to connect to a server that is listening for SSL connections also leads to hanging. This is a characteristic of the protocol that some implementations may choose to correct but is not otherwise required to do so. The provider's documentation, however, should describe this behavior to its users. See SSL for information on how to use SSL.

For example:

env.put(Context.SECURITY_PROTOCOL, "ssl");
specifies that SSL-compliant sockets be used to communicate with the server.

3.3 LDAP-specific Properties

LDAP-specific properties are environment properties that apply to LDAP service providers in general. These properties' names have the prefix "java.naming.ldap.". The following table lists LDAP-specific properties that have been defined so far. If there is a property that you feel belongs on this list, please send a description of it to jndi@java.sun.com.

java.naming.ldap.attributes.binary
The value of this property is a string of space-separated attribute names. It specifies attributes which have non-string syntax. It extends the provider's built-in list of non-string attributes (below). The value of an attribute that has non-string syntax is returned as a byte array (byte[]) instead of a String.

No default is defined. If this property is not set then only the following attributes are considered to have non-string syntax:

Attribute ID | OID | Reference
Any attribute ID with the ";binary" option. |  |
photo | 0.9.2342.19200300.100.1.7 | RFC 1274
personalSignature | 0.9.2342.19200300.100.1.53 | RFC 1274
audio | 0.9.2342.19200300.100.1.55 | RFC 1274
jpegPhoto | 0.9.2342.19200300.100.1.60 | RFC 2798
javaSerializedData | 1.3.6.1.4.1.42.2.27.4.1.7 | RFC 2713
thumbnailPhoto | 2.16.128.113533.1.1400.1 | NAC LIP Schema
thumbnailLogo | 2.16.128.113533.1.1400.2 | NAC LIP Schema
userPassword | 2.5.4.35 | RFC 2256
userCertificate | 2.5.4.36 | RFC 2256
cACertificate | 2.5.4.37 | RFC 2256
authorityRevocationList | 2.5.4.38 | RFC 2256
certificateRevocationList | 2.5.4.39 | RFC 2256
crossCertificatePair | 2.5.4.40 | RFC 2256
x500UniqueIdentifier | 2.5.4.45 | RFC 2256

For example:
env.put("java.naming.ldap.attributes.binary",
        "mpegVideo myspecialkey");
informs the provider to return values of the mpegVideo and myspecialkey attributes as byte[].

java.naming.ldap.control.connect

The value of this property is a Control[] object. It sets the connection request controls that are active on a connection. See LdapContext.

No default value is defined for this property.

For example:

env.put("java.naming.ldap.control.connect",
        new Control[]{ new ManageReferralControl(true) });
sets a critical ManageDsaIT LDAP control as the connection request control.

java.naming.ldap.deleteRDN

The value of this property is a string that specifies whether the old RDN is removed by the Context.rename method. The following values are defined for this property:
true
delete the old RDN from the entry during the rename operation.
false
retain the old RDN as an attribute value of the entry.

If this property is not set then its default value is true.

For example:

env.put("java.naming.ldap.deleteRDN", "false");
causes the old RDN to be retained as an attribute of the renamed entry.

java.naming.ldap.derefAliases
The value of this property is a string that specifies how aliases are dereferenced during search operations. The following values are defined for this property:
always
always dereference aliases.
never
never dereference aliases.
finding
dereference aliases only during name resolution (that is, while locating the target entry).
searching
dereference aliases once name resolution has completed (that is, after locating the target entry).
If this property is not set then its default value is always.

For example:

env.put("java.naming.ldap.derefAliases", "searching");
causes the provider to dereference aliases only once the target entry has been located.

NOTE: this property is unrelated to the dereference-links flag in the SearchControls object.

java.naming.ldap.factory.socket
The value of this property is a string identifying the class name of a socket factory.

This property is used to override the default socket factory. The class specified in this property must implement the javax.net.SocketFactory interface. See http://java.sun.com/j2se/1.4/docs/guide/security/jsse/JSSERefGuide.html for more information. See SSL for information on how to use SSL.

In addition, if the java.naming.security.protocol property is set, then the socket factory identified by this property must create sockets which are appropriate for that protocol setting. For example, if the security protocol is set to ssl then the socket factory must create SSL-compliant sockets.

No default is defined for this property.

For example:

env.put("java.naming.ldap.factory.socket",
        "javax.net.ssl.SSLSocketFactory");
sets the socket factory of the provider to be javax.net.ssl.SSLSocketFactory.

java.naming.ldap.ref.separator
The value of this property is a string containing the character to use when encoding a RefAddr object in the javaReferenceAddress attribute (see Java Objects).

This property is used to avoid a conflict in the case where the default separator character appears in the components of a RefAddr object.

If this property is not set then its default value is '#' (the hash character).

For example:

env.put("java.naming.ldap.ref.separator", ":");
specifies that the separator ':' (the colon character) be used when storing RefAddr instances.

java.naming.ldap.referral.limit
The value of this property is a string of decimal digits specifying the maximum number of referrals to follow in a chain of referrals. A setting of zero indicates that there is no limit.

If this property is not set then the default value is 10.

For example:

env.put("java.naming.ldap.referral.limit", "5");
specifies that the referral limit is 5.

java.naming.ldap.typesOnly
The value of this property is a string that specifies whether only attribute IDs are returned in results - attribute values are omitted. Affects the SearchResult.getAttributes and DirContext.getAttributes methods. The following values are defined for this property:
true
return only attribute IDs.
false
return both attribute IDs and attribute values.

If this property is not set then its default value is false.

For example:

env.put("java.naming.ldap.typesOnly", "true");
causes the server to return attribute IDs but not attribute values.

java.naming.ldap.version
The value of this property is a string that specifies the protocol version for the provider. The following values are defined for this property:
2
selects LDAP version 2 (LDAPv2).
3
selects LDAP version 3 (LDAPv3).

If this property is not set then the provider first attempts to bind using LDAP v3 and fails over to using LDAP v2 if a protocol error is received from the server. This failover mechanism is only used when the java.naming.security.authentication property indicates anonymous bind or simple authentication.

For example:

env.put("java.naming.ldap.version", "2");
requests the LDAP provider to communicate with the server using LDAPv2.

3.4 Feature-specific Properties

Feature-specific properties are environment properties which apply to a particular feature which is supported by a provider.

3.4.1 SASL Properties

There are two groups of SASL properties. The first group comprises those that relate to how the JNDI service provider interacts with the Java SASL API (JSR 28). These properties have the prefix "java.naming.security.sasl." The second group comprises those that affect the SASL mechanisms. These properties are specified in the Java SASL API and have the prefix "javax.security.sasl." See the SASL section and the Java SASL API for details about this second group of properties.

java.naming.security.sasl.authorizationId

The value of this property is a string that specifies the authorization ID for the SASL mechanisms.

If this property is not set, then the authorization ID passed to the SASL mechanisms is the empty string. According to SASL (RFC 2222), using an authorization ID of the empty string directs the server to derive an authorization ID from the client's authentication credentials.

For example:

env.put("java.naming.security.sasl.authorizationId",
        "dn:cn=administrators,ou=groups,o=sun,c=us");
specifies the identity to use for authorization (access control) upon successful authentication.

java.naming.security.sasl.realm

The value of this property is a string that specifies the realm information required by some SASL mechanisms such as DIGEST-MD5.

If this property is not set, then a mechanism-specific default such as that negotiated between the client and server during the authentication exchange is used.

For example:

env.put("java.naming.security.sasl.realm", "webusers");
specifies that the client wants to use the "webusers" realm for authentication.

java.naming.security.sasl.callback

The value of this property is an instance of javax.security.auth.callback.CallbackHandler. When the provider uses a SASL mechanism that requires callbacks, the SASL mechanism uses the object supplied in the property. The callback handler should satisfy a NameCallback by supplying the authentication ID.

If this property is not set, then the provider should use a default callback handler that satisfies the NameCallback using the value of the java.naming.security.principal property, satisfies the PasswordCallback using the value of the java.naming.security.credentials property, and satisfies the RealmCallback and RealmChoiceCallback (described in the Java SASL API) using the value of the java.naming.security.sasl.realm property.

For example:

env.put("java.naming.security.sasl.callback",
        new MyCallbackHandler());
supplies an instance of the callback handler for SASL mechanisms to use.

javax.security.sasl.qop
The value of this property is a ','-separated list of quality-of-protection (qop) values used to specify the client's qop preference. A qop value is one of
  • "auth" - authentication only
  • "auth-int" - authentication plus integrity protection
  • "auth-conf" - authentication plus integrity and confidentiality protection
The order of the list specifies the preference order. If this property is absent, the default qop is "auth".

javax.security.sasl.strength
The value of this property is a ','-separated list of cipher strength values used to specify the client's preference. A strength value is one of
  • "low"
  • "medium"
  • "high"
The order of the list specifies the preference order. If this property is absent, the default strength is "high,medium,low".

For privacy in DIGEST-MD5, "high" maps to "3des", "medium" to "rc4" or "des", and "low" to "rc4-56" or "rc4-40".

javax.security.sasl.maxbuffer
The value of this property is the string representation of an integer that specifies the maximum size of the receive buffer in bytes that the client is willing to receive. If this property is absent, the default size is defined by the SASL mechanism.

javax.security.sasl.server.authentication
The value of this property is either "true" or "false", specifying whether the server must authenticate to the client or not, respectively. If this property is absent, the default is "false".

javax.security.sasl.policy.forward
The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must support forward secrecy between sessions or not, respectively. If this property is absent, the default is "false".

javax.security.sasl.policy.credentials
The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must require client credentials or not, respectively. If this property is absent, the default is "false".

javax.security.sasl.policy.noplaintext
The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must not be susceptible to simple plain passive attacks or not, respectively. If this property is absent, the default is "false".

javax.security.sasl.policy.noactive
The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must not be susceptible to active (non-dictionary) attacks or not, respectively. If this property is absent, the default is "false".

javax.security.sasl.policy.nodictionary
The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must not be susceptible to dictionary attacks or not, respectively. If this property is absent, the default is "false".

javax.security.sasl.policy.noanonymous
The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must not accept anonymous logins or not, respectively. If this property is absent, the default is "false".

3.5 Provider-specific Properties

Provider-specific properties are environment properties which apply only to particular provider implementations. The names of these properties are chosen by the provider's implementor. The recommended policy for naming these properties is to use the implementor's reversed DNS domain name to prefix the provider's package name and to use that package name to prefix the property name. For example, Sun prefixes its provider-specific LDAP properties with "com.sun.jndi.ldap".

4. Names

Names are handled by the provider's context methods according to the following rules:
  1. String names supplied as parameters to the context methods are in the composite name syntax.
    2. The first component of the composite name is an LDAP distinguished name while the rest of the components are used for federation.
  2. If a Name argument is a CompositeName object then its first component is assumed to be an LDAP distinguished name and the remaining components (if any) are used for federation.
  3. If a Name argument is not a CompositeName object then all of its components are assumed to be the parsed form of an LDAP distinguished name. That is, each Name component is an LDAP relative distinguished name (RDN).
  4. Names are parsed using the name parser returned by the Context.getNameParser method. The parser accepts LDAP distinguished names as String objects and produces LDAP distinguished names as Name objects.
  5. Names returned by context operations are string composite names or string URLs.
The syntax of string LDAP distinguished names follows RFC 2253. For example:
  • CN=Steve Kille, O=Isode Limited, C=GB
  • OU=Sales+CN=J. Smith, O=Widget Inc., C=US
  • CN=L. Eagle, O=Sue\, Grabbit and Runn, C=GB
    • The name supplied to an LDAP context is always relative to that context. For example, given an LDAP context (lctx) for "dc=widget,dc=com", in order to name LDAP entries in that subtree, a name relative to "dc=widget,dc=com" must be supplied. For example, the following call obtains the attributes for the
    "cn=John Smith,dc=widget,dc=com" entry,

    Attributes attrs = lctx.getAttributes("cn=John Smith");

    Similarly, when a context is enumerated using any of the enumeration methods (Context.list, Context.listBindings, DirContext.search), the names returned are relative to the target context--the context being enumerated. When referrals are invoked, instead of a relative name, an LDAP or LDAPS URL string containing the fully qualified name is returned. (If the enumeration was performed using a plain connection, an LDAP URL string is returned; if it was done using an SSL connection, an LDAPS URL string is returned.) The format of LDAP URLs is defined in RFC 2255.

    LDAP URLs that follow RFC 2255 and LDAPS URLs may be supplied to any of the context methods. The hostname and port number are extracted from the URL and used to contact the LDAP server; the URL's scheme ("ldap" or "ldaps") is used to determine whether a plain or SSL connection is used. The java.naming.factory.initial and java.naming.provider.url properties are ignored. For example,

        DirContext ictx = new InitialDirContext();
        Attributes attrs = ictx.getAttributes(
            "ldap://wserver:389/cn=John Smith,dc=widget,dc=com");

    This code fragment contacts the LDAP server at machine wserver at port 389 using a plain connection.

    5. Attributes

    The LDAP provider expects as input and returns as output all attribute values as either String or byte[] objects. See the java.naming.ldap.attributes.binary environment property for which ones are treated as byte[] and how to extend the list.

    6. URLs

    RFC 2255 describes the syntactic format of LDAP URLs. The format contains all the elements necessary to specify an LDAP search operation, with provisions for supporting extensions:
    ldap://host:port/dn?attributes?scope?filter?extensions
    Authentication information may be specified in the extensions portion of the URL. See the RFC for a complete description of the format.

    In addition to LDAP URLs, the provider may also support the non-standard but widely used LDAPS URLs. LDAPS URLs use SSL connections instead of plain (i.e., unprotected) connections. They have a syntax similar to LDAP URLs except the schemes are different and the default port for LDAPS URLs is 636 instead of 389.

    ldaps://host:port/dn?attributes?scope?filter?extensions

    URLs play a role in several places in JNDI:

    1. Configuration of service providers.

      2. To configure an LDAP service provider, you typically supply one or more space-separated LDAP or LDAPS URLs in the java.naming.provider.url property. This is used by the LDAP service provider to configure its connection to the directory server. Only the host, port, and dn parts of the URL are relevant in this setting. Supplying other parts of the URL results in a ConfigurationException.
    2. Argument to initial context methods.

      3. If a URL string (with syntax scheme_id:rest_of_name) is passed to the methods in InitialContext, either as a String argument or as the first component of Name, the URL's scheme id is used to locate the context factory for handling that scheme. If none is found, the URL string is treated as an ordinary name and passed to the initial context specified by the java.naming.factory.initial property is used. See the java.naming.spi.NamingManager.getURLContext method for details on how URL context factories are located. Note that this support for URLs as names is only available in the initial context.

      With the exception of the search methods, when an LDAP or LDAPS URL is passed as a name to the initial context, the URL should not contain any query ('?') components. Otherwise, an InvalidNameException is thrown by the service provider. For the search methods, the query components of the URL override any corresponding components supplied as arguments. For example, if an LDAP URL containing a scope component is supplied, then that scope overrides any scope setting that may be passed in a SearchControls argument.

    3. Referrals.

      4. An LDAP referral contains a list of one or more URLs. To process an LDAP referral (either explicitly or implicitly by setting the java.naming.referral property), the service provider needs to use the information in the these URLs to create connections to LDAP servers to which they refer. When multiple URLs are present in a single referral they are treated as alternatives and each is followed until one succeeds. The complete URL (that is, including any query components) is used.
    4. Returned as a name in list and search enumerations.

      5. When the name of the entry being returned has a name that is not relative to the target context (i.e., the starting context for the list or search), the name is returned as a URL. See the NameClassPair.isRelative method for details.
    5. Argument to the getObjectInstance method of NamingManager or DirectoryManager.

      6. When an LDAP namespace is federated underneath another namespace (for example, such as DNS), the information that is stored in the superior namespace might be an LDAP or LDAPS URL. In such a scenario, a lookup/list/search operation in the superior namespace would return a Reference containing an LDAP or LDAPS URL for the LDAP namespace. The service provider for the superior namespace would pass the Reference to the getObjectInstance method to create an instance of an LDAP context.
    For items (1), (2), (3), and (5), if the URL is missing the hostname and port but has a non-empty distinguished name, the provider should use the algorithm for discovering LDAP services with DNS as described in the Internet draft draft-ietf-ldapext-locate-08.txt. If the provider does not use this algorithm, or if the DNS configuration is not available, then the provider should use localhost as the hostname, and 389 as the port for plain connections, 636 as the port for SSL connections.

    7. Java Objects

    7.1 Storing

    The LDAP provider should support the storing of Java objects into the directory. This is implemented in the following methods:
    • Context.bind()
    • Context.rebind()
    • DirContext.bind()
    • DirContext.rebind()
    The provider should support at a minimum the storage of the following types of Java objects:
    1. Instances of Reference
    2. Objects that implement the Referenceable interface
    3. Objects that implement the Serializable interface
    4. Objects that implement the DirContext interface
    It should check whether an object is in these four categories in the order listed because that is most likely to capture the intent of the client. For example, a Reference is Serializable, so if you performed the Serializable check first, no References would ever be stored in the reference format (that is, they would all be serialized).

    References, referenceable and serializable objects should be stored according to RFC 2713. DirContext objects should be stored by storing their attributes.

    When storing a reference's list of RefAddr into the javaReferenceAddress attribute, the separator to use for delimiting the address's position, type and content are controlled using the environment property java.naming.ldap.ref.separator. If this environment property is not specified, the hash character '#' should be used as the separator.

    The provider uses the DirectoryManager.getStateToBind method when storing objects in the directory. This allows objects of any type to be transformed into one of the four categories listed above so that they can be stored into the directory.

    7.2 Reading

    Objects are read from the directory using the following operations:
    • Context.lookup()
    • Context.lookupLink()
    • Binding.getObject()
    When the provider reads an entry from the directory, it will get LDAP attributes, and attributes defined in RFC 2713 if the entry has an associated Java object. If the entry contains Java object-related attributes, the provider should recreate the object using those attributes. Otherwise, the provider should return an instance of DirContext containing the attributes of the entry. For both DirContext and Java objects, the provider should then invoke DirectoryManager.getObjectInstance() on it and return the result to the caller.

    8.0 Schema

    JNDI does not specify schema-related details such as structure and contents of the schema tree, permission to modify to the contents of the schema tree, and the effect of such modifications on the directory are dependent on the underlying directory. JNDI specifies only that the root schema context--that returned by DirContext.getSchema()--contain the following bindings:
    • AttributeDefinition
    • ClassDefinition
    • SyntaxDefinition
    This document specifies the structure and content of schema trees that are derived from LDAP-based schemas. It describes how the schema tree is laid out, and the mandatory and optional attributes that you can expect to find associated with entries in different parts of this schema tree.

    Permission to modify the contents of the schema tree is determined by the directory administrator. When the schema tree is modified, the changes are made to schema stored on the directory server.

    8.1 Schema Tree Structure

    In addition to the three bindings in the root schema context listed previously, the root schema context may also contain the following four bindings:
    • MatchingRule
    • ExtensionDefinition
    • ControlDefinition
    • SASLDefinition

    Name of Binding | Description of Binding
AttributeDefinition | Root of the attribute definition tree: a flat namespace with attributes identified by their name or OID.
ClassDefinition | Root of the "objectclass" definition tree: a flat namespace with object classes identified by their name or OID.
SyntaxDefinition | Root of the syntax definition tree: a flat namespace with syntaxes identified by their OID.
MatchingRule | Root of matching rule tree: a flat namespace with matching rules identified by their name or OID.
ExtensionDefinition | Root of the extensions tree: a flat namespace with extensions identified by their OID.
ControlDefinition | Root of the controls tree: a flat namespace with controls identified by their OID.
SASLMechanism | Root of the SASL tree: a flat namespace with SASL authentication mechanisms identified by their string name.

    Any or all of these bindings may be absent if the underlying directory does not publish such schema information, or the service provider does not support retrieving them. If these names are present in the root schema context, however, they must have the binding specified in the above table.

    The attribute names and values of these entries' attributes are case-insensitive.

    8.2 Attribute Definitions

    The name "AttributeDefinition" is bound to a context containing DirContext objects representing attribute definitions in the schema. For example, if a directory supports a "commonName" attribute, the "AttributeDefinition" context would have a binding with name "commonName" that is bound to a DirContext object.

    Each object in the "AttributeDefinition" context has the following mandatory and optional attributes:

    Attribute Identifier | Attribute Value Description
NUMERICOID (mandatory) | unique identifier (OID)
NAME | attribute's name
DESC | attribute's description
OBSOLETE | "true" if obsolete, "false" or absent otherwise
SUP | name of superior attribute type from which this attribute's type is derived
EQUALITY | name or OID of matching rule if equality matching allowed, absent otherwise
ORDERING | name or OID of matching rule if ordering matching allowed, absent otherwise
SUBSTRING | name or OID of matching rule if substring matching allowed, absent otherwise
SYNTAX | numeric OID of syntax of values of this type
SINGLE-VALUE | "true" if attribute not multi-valued, "false" or absent otherwise.
COLLECTIVE | "true" if attribute is collective, "false" or absent otherwise.
NO-USER-MODIFICATION | "true" if not user-modifiable, "false" or absent otherwise.
USAGE | description of attribute usage

    These attributes have a 1-to-1 correspondence with the names defined in RFC 2252 for "AttributeTypeDescription." All the attribute values are represented by the java.lang.String class.

    You can, for example, obtain the object representing the "cn" attribute using the following code:

    DirContext schema = ctx.getSchema(""); // get schema tree
DirContext cnSchema = schema.lookup("AttributeDefinition/cn");
    If you then get the attributes of the "cnSchema" DirContext object, you would see:
    NUMERICOID      2.5.4.3
NAME            cn
SYNTAX          1.3.6.1.4.1.1466.115.121.1.15
DESC            Standard Attribute, alias for commonName
    An equivalent way of getting "cnSchema" is if you already have a "cn" attribute. The following code illustrates this alternative:
    Attributes attrs = ctx.getAttributes("cn=John", new String[]{"cn"});
Attribute cnAttr = attrs.get("cn");
DirContext cnSchema = cnAttr.getAttributeDefinition();

    8.3 Object Class Definitions

    The name "ClassDefinition" is bound to a context containing DirContext objects representing object class definitions in the schema. For example, if a directory supports a "country" object class, the "ClassDefinition" context would have a binding with name "country" that is bound to a DirContext object.

    Each object in the "ClassDefinition" context has the following mandatory and optional attributes:

    Attribute Identifier | Attribute Value Description
NUMERICOID (mandatory) | unique identifier (OID)
NAME | object class's name
DESC | object class's description
OBSOLETE | "true" if obsolete, "false" or absent otherwise
SUP | name of superior object class from which this object class is derived
ABSTRACT | "true" if object class is abstract, "false" or absent otherwise
STRUCTURAL | "true" if object class is structural, "false" or absent otherwise
AUXILIARY | "true" if object class is auxiliary, "false" or absent otherwise
MUST | a list of type names of attributes that must be present
MAY | a list of type names of attributes that may be present

    These attributes have a 1-to-1 correspondence with the names defined in RFC 2252 for "ObjectClassDescription." All the attribute values are represented by the java.lang.String class.

    You can, for example, obtain the object representing the "country" object class using the following code:

    DirContext schema = ctx.getSchema(""); // get schema tree
DirContext countrySchema = schema.lookup("ClassDefinition/country");
    If you then get the attributes of the "countrySchema" DirContext object, you would see:
    NUMERICOID      2.5.6.2
NAME            country
MAY             aci, searchguide, description
MUST            objectclass, c
DESC            Standard ObjectClass
SUP             top
    An equivalent way of getting "countrySchema" is if you already have a "country" object. The following code illustrates this alternative:
    // Read object from directory
DirContext countryObj = (DirContext)ctx.lookup("c=us", new String[]{"country"});

// Get all of object's object class definitions
DirContext objClasses = countryAttr.getSchemaClassDefinition();

// Pick out "country" object class in particular
DirContext countryClass = (DirContext)objClasses.lookup("country");

    NOTE: JNDI 1.1's specification of getSchemaClassDefinition() implies that the service provider should return any one of an object's object class definitions. This specification is inadequate because an object usually has multiple object classes and the application might require knowledge about any of those object classes depending on what it is doing. The proposal as illustrated by the example above is to return a context containing all of the object class definitions.

    8.4 Syntax Definitions

    The name "SyntaxDefinition" is bound to a context containing DirContext objects representing syntax definitions in the schema. For example, if a directory supports the "1.3.6.1.4.1.1466.115.121.1.15" syntax (Directory String) syntax, the "SyntaxDefinition" context would have a binding with name "1.3.6.1.4.1.1466.115.121.1.15" that is bound to a DirContext object.

    Each object in "SyntaxDefinition" context has the following mandatory and optional attributes:

    Attribute Identifier | Attribute Value Description
NUMERICOID (mandatory) | unique identifier (OID)
DESC | syntax's description

    These attributes have a 1-to-1 correspondence with the names defined in RFC 2252 for "SyntaxDescription." All the attribute values are represented by the java.lang.String class.

    You can, for example, obtain the object representing the "1.3.6.1.4.1.1466.115.121.1.15" syntax using the following code:

    DirContext schema = ctx.getSchema(""); // get schema tree
DirContext dirStringSchema =
    schema.lookup("SyntaxDefinition/1.3.6.1.4.1.1466.115.121.1.15");
    If you then get the attributes of the "dirStringSchema" DirContext object, you would see:
    NUMERICOID      1.3.6.1.4.1.1466.115.121.1.15
DESC            Directory String
    An equivalent way of getting "dirStringSchema" is if you already have an attribute that has that syntax (such as, the "country" attribute). The following code illustrates this alternative:
    Attributes attrs = ctx.getAttributes("c=us", new String[]{"country"});
Attribute countryAttr = attrs.get("country");
DirContext dirStringSchema = countryAttr.getSyntaxAttributeDefinition();

    8.5 Matching Rules

    The name "MatchingRule" is bound to a context containing DirContext objects representing matching rules in the schema. A "matching rule" uniquely identifies the algorithm to use when comparing attribute values. For example, a directory might support a matching rule that is based on how a string sounds and define it as the "soundAlikeMatch" matching rule. Then, the "MatchingRule" context would have a binding with name "soundAlikeMatch" that is bound to a DirContext object.

    When a matching rule is an extensible matching rule, it must also contain an "APPLIES" attribute listing the attributes to which this extensible matching rule can be applied.

    Each object in "MatchingRule" context has the following mandatory and optional attributes:

    Attribute Identifier | Attribute Value Description
NUMERICOID (mandatory) | unique identifier (OID)
NAME | name of matching rule
DESC | matching rule's description
OBSOLETE | "true" if obsolete, "false" or absent otherwise
SYNTAX | numeric oid of syntax to which this rule applies
APPLIES | a list type names of attributes to which this extensible matching rule applies

    These attributes have a 1-to-1 correspondence with the names defined in RFC 2252 for "MatchingRuleDescription" and "MatchingRuleUseDescription." All the attribute values are represented by the java.lang.String class.

    You can, for example, obtain the object representing the "soundAlikeMatch" syntax using the following code:

    DirContext schema = ctx.getSchema(""); // get schema tree
DirContext soundMatchSchema =
    schema.lookup("MatchingRule/soundAlikeMatch");
    If you then get the attributes of the "soundMatchSchema" DirContext object, you would see:
    NUMERICOID      1.2.3.4.5
NAME            soundAlikeMatch
SYNTAX          1.3.6.1.4.1.1466.115.121.1.15 (for directory string)
APPLIES         2.5.4.41, 2.5.4.15
DESC            Home-grown Phonetic match

    8.6 Extension Definitions

    The name "ExtensionDefinition" is bound to a context containing DirContext objects representing extensions supported by the server. For example, a directory might support the "Start TLS" extension ("1.3.6.1.4.1.1466.20037"). Then, the "ExtensionDefinition" context would have a binding with name "1.3.6.1.4.1.1466.20037" that is bound to a DirContext object.

    Each object in "ExtensionDefinition" context has the following mandatory and optional attributes:

    Attribute Identifier | Attribute Value Description
NUMERICOID (mandatory) | unique identifier (OID)
DESC | extension's description

    All the attribute values are represented by the java.lang.String class.

    You can, for example, obtain the object representing the Start TLS extension ("1.3.6.1.4.1.1466.20037") using the following code:

    DirContext schema = ctx.getSchema(""); // get schema tree
DirContext startTLSSchema =
    schema.lookup("ExtensionDefinition/1.3.6.1.4.1.1466.20037");
    If you then get the attributes of the "startTLSSchema" DirContext object, you would see:
    NUMERICOID      1.3.6.1.4.1.1466.20037
DESC            Start TLS (see RFC 2830)

    8.7 Control Definitions

    The name "ControlDefinition" is bound to a context containing DirContext objects representing controls supported by the server. For example, a directory might support the control for asking the server to sort the search results it returns.

    Each object in "ControlDefinition" context has the following mandatory and optional attributes:

    Attribute Identifier | Attribute Value Description
NUMERICOID (mandatory) | unique identifier (string)
DESC | control's description

    All the attribute values are represented by the java.lang.String class.

    You can, for example, obtain the object representing the server-side sorting control ("1.2.840.113556.1.4.473") using the following code:

    DirContext schema = ctx.getSchema(""); // get schema tree
DirContext svrSortSchema =
    schema.lookup("ControlDefinition/1.2.840.113556.1.4.473");
    If you then get the attributes of the "svrSortSchema" DirContext object, you would see:
    NUMERICOID      1.2.840.113556.1.4.473
DESC            server-side sorting of search results

    8.8 SASL Mechanisms

    The name "SASLMechanism" is bound to a context containing DirContext objects representing SASL authentication mechanisms supported by the server. For example, a directory might support the EXTERNAL SASL mechanism (RFC 2222) which requests that the server make use of security credentials exchanged by a lower layer.

    Each object in "SASLMechanism" context has the following mandatory and optional attributes:

    Attribute Identifier | Attribute Value Description
NAME (mandatory) | SASL mechanism's name
DESC | SASL mechanism's description

    All the attribute values are represented by the java.lang.String class.

    You can, for example, obtain the object representing the EXTERNAL SASL mechanism using the following code:

    DirContext schema = ctx.getSchema(""); // get schema tree
DirContext saslExternalSchema =
    schema.lookup("SASLMechanism/EXTERNAL");
    If you then get the attributes of the "saslExternalSchema" DirContext object, you would see:
    NAME      EXTERNAL
    DESC      EXTERNAL SASL mechanism (RFC 2222)

    9. Exceptions

    When building an LDAP provider, you need to translate LDAP error codes (see RFC 2251) into JNDI exceptions. You should use the following table when performing the translation. Furthermore, you should encode as much information as possible about the error into the exception's detailed message, "root cause" exception, resolved and remaining names. Note that resolved name and resolved object should correspond to each other's setting.
    LDAP error code | Exception or Action
success (0) | Report success.
operationsError (1) | NamingException
protocolError (2) | CommunicationException
timeLimitExceeded (3) | TimeLimitExceededException
sizeLimitExceeded (4) | SizeLimitExceededException
compareFalse (5) | Used by DirContext.search() and does not generate an exception.
compareTrue (6) | Used by DirContext.search() and does not generate an exception.
authMethodNotSupported (7) | AuthenticationNotSupportedException
strongAuthRequired (8) | AuthenticationNotSupportedException
partialResults (9) | If java.naming.referral is set to ignore, or contents of error does not contain a referral, throw PartialResultException. Otherwise, use the contents to build a referral.
referral (10) | If java.naming.referral is set to ignore then throw PartialResultException. If it is set to throw then throw ReferralException. If it is set to follow then the provider shall follow the referral. If the value for java.naming.ldap.referral.limit is exceeded while following the referral then throw LimitExceededException.
adminLimitExceeded (11) | LimitExceededException
unavailableCriticalExtension (12) | OperationNotSupportedException
confidentialityRequired (13) | AuthenticationNotSupportedException
saslBindInProgress (14) | Used internally by LDAP provider during multi-stage SASL authentication.
noSuchAttribute (16) | NoSuchAttributeException
undefinedAttributeType (17) | InvalidAttributeIdentifierException
inappropriateMatching (18) | InvalidSearchFilterException
constraintViolation (19) | InvalidAttributeValueException
attributeOrValueExists (20) | AttributeInUseException
invalidAttributeSyntax (21) | InvalidAttributeValueException
noSuchObject (32) | NameNotFoundException
aliasProblem (33) | NamingException
invalidDNSyntax (34) | InvalidNameException
isLeaf (35) | Used by provider; usually doesn't generate exception.
aliasDereferencingProblem (36) | NamingException
inappropriateAuthentication (48) | AuthenticationNotSupportedException
invalidCredentials (49) | AuthenticationException
insufficientAccessRights (50) | NoPermissionException
busy (51) | ServiceUnavailableException
unavailable (52) | ServiceUnavailableException
unwillingToPerform (53) | OperationNotSupportedException
loopDetect (54) | NamingException
namingViolation (64) | InvalidNameException
objectClassViolation (65) | SchemaViolationException
notAllowedOnNonLeaf (66) | ContextNotEmptyException
notAllowedOnRDN (67) | SchemaViolationException
entryAlreadyExists (68) | NameAlreadyBoundException
objectClassModsProhibited (69) | SchemaViolationException
affectsMultipleDSAs (71) | NamingException
other (80) | NamingException

    10. API Mapping

    The methods of the JNDI API context interfaces are mapped onto LDAP operations as follows.
    EventContext.addNamingListener
    EventDirContext.addNamingListener
    Register a listener for receiving naming events that take place in the specified subtree of LDAP entries. LDAP servers notify clients of events by means of LDAP controls attached to LDAP operation responses or by means of an LDAP unsolicited notifications. Such responses are then processed by the LDAP provider and indicated to the application in the form of NamingEvent or UnsolicitedNotificationEvent.
    Context.addToEnvironment
    Update context's environment properties. If multiple contexts share the same set of environment properties, the provider should take care to only modify the intended context's environment. Changing an environment property might require changes to the existing connection the context is using.
    Supplying null for the property value has the same effect as removing the property.

    For all environment properties, the new property is recorded even if it does not affect the context. See the Environment Properties section.

    Context.bind

    DirContext.bind
    Perform an LDAP add operation to create a new entry in the directory. The DirContext.bind method can accept null as the object to bind if it is also supplied a non-null set of attributes. Otherwise, if the method is given insufficient information (i.e., no object or attributes), no entry can be added. If an object is provided in the arguments, then it is converted into attributes and stored in the entry along with any supplied attributes, as described in the Java Objects section. The provider should use the DirectoryManager.getStateToBind method to transform the input object into a form that it can store.

    If the provider does not support binding any objects in the directory then it should throw OperationNotSupportedException. Otherwise, if it does support binding objects but does not support the supplied object then it should throw IllegalArgumentException.

    Context.close
    Release resources associated with context. For example, if the connection being used by this context is not shared with another context, the provider may abandon any outstanding requests and close the network connection to the server. Precisely which resources are released is implementation-dependent.
    Context.composeName
    If the parent context is from the same LDAP namespace, then concatenate the names according to the LDAP name syntax described in Context.getNameParser(). Otherwise, concatenate the names as composite names.
    Context.createSubcontext

    DirContext.createSubcontext
    Perform an LDAP add operation to create the named entry and its associated attributes. If no attributes are supplied then the objectClass attribute is generated with the values top and javaContainer (javaContainer is a structural class that is necessary to avoid a schema violation error).
    Context.destroySubcontext
    Perform an LDAP delete operation to remove the named entry and its associated attributes. The named entry must be a leaf entry; subtrees are not removed. If the leaf entry does not exist (but its parent exists), the operation still succeeds.
    LdapContext.extendedOperation
    Perform an LDAP extended operation.
    DirContext.getAttributes
    Perform an LDAP base-object search operation to retrieve the LDAP entry's attributes. Use "(objectclass=*)" as the filter.

    If the list of requested attributes is null or contains the special attribute identifier '*' then all the user attributes at the LDAP entry are returned. If operational attributes are required then those attribute identifiers must be present in the list of requested attributes.

    LdapContext.getConnectControls
    Retrieve the connection request controls in effect for LDAP bind operations invoked on this context.
    Context.getEnvironment
    Return the environment properties recorded at the context.

    Context.getNameInNamespace

    Return the LDAP distinguished name of the context.

    Context.getNameParser

    Return a name parser that parses LDAP names according to RFC 2253.
    LdapContext.getRequestControls
    Retrieve the request controls in effect for LDAP operations subsequently invoked on this context.
    LdapContext.getResponseControls
    Retrieve the response controls returned by the last LDAP operation invoked on this context.
    DirContext.getSchema
    See the Schema Section.
    DirContext.getSchemaClassDefinition
    See the Schema Section.
    Context.list
    Perform an LDAP one-level search operation of the named entry using the filter "(objectclass=*)" to retrieve the names of the entries immediately below the named entry.

    Ask for, at a minimum, the javaClassName attributes so that the class name of each entry can be determined. If the class name cannot be determined, return javax.naming.directory.DirContext as the class name.

    The names which are returned are either relative to the named context or they are LDAP or LDAPS URLs.

    Context.listBindings
    Perform an LDAP one-level search operation of the named entry using the filter "(objectclass=*)" to retrieve the attributes representing objects (or object references). Request the attributes for reconstructing the Java object and possibly other attributes as well. See Java Objects on how to reconstruct the object. If the object cannot be reconstructed according to RFC 2713 then return a DirContext object representing the LDAP entry. The provider should use the DirectoryManager.getObjectInstance method to satisfy calls to the Binding.getObject method.

    The names which are returned are either relative to the named context or they are LDAP or LDAPS URLs.

    Context.lookup

    Context.lookupLink
    Perform an LDAP base-object search operation of the named entry using the filter "(objectclass=*)". Request (possibly all) the attributes for reconstructing the Java object. See Java Objects on how to reconstruct the object. The provider should use the DirectoryManager.getObjectInstance method to satisfy calls to the Binding.getObject method.
    DirContext.modifyAttributes
    Perform an LDAP modify operation at the named entry using the supplied modifications. For the overloaded method that accepts an Attributes, first convert the Attributes argument into an ordered list of modifications by enumerating its contents using Attributes.getAll() and reusing the modification operation argument (mod_op).
    LdapContext.newInstance
    Initialize an new instance of this context with the specified request controls.
    Context.rebind

    DirContext.rebind
    This method may involve several different LDAP operations. First get the existing entry's attributes. If the existing entry does not exist, this method behaves the same as bind(). Otherwise, if no attributes have been supplied and the object being bound is DirContext, invoke DirContext.getAttributes() and use the result as the attributes argument (attrs). If there are still no attributes, use the original entry's attributes as attrs. Remove the existing entry using the LDAP delete operation. Convert the object provided in the arguments into attributes (as described in the Java Objects section) and store in the entry along with attrs using the LDAP add operation. The provider should use the DirectoryManager.getStateToBind method to transform the input object into a form that it can store.
    LdapContext.reconnect

    Reconnect to the LDAP server using the supplied connection request controls and the current environment properties.

    Context.removeFromEnvironment
    Remove context's environment properties. If multiple contexts share the same set of environment properties, the provider should take care to only modify the intended context's environment. Changing an environment property might require changes to the existing connection the context is using.
    For all environment properties, the new property is recorded even if it does not affect the context. Removing a property should cause the context to assume the property's default.
    EventContext.removeNamingListener
    Deregister a naming event listener so that subsequent events destined for that listener are not delivered.
    Context.rename
    Perform an LDAP modify DN operation to rename the entry. If LDAPv2 is being used then the new name and the old name must share the same immediate parent name. If the parents are not equal then throw InvalidNameException.

    Note the effect of the java.naming.ldap.deleteRDN property on the behavior of this method.

    DirContext.search
    Perform an LDAP search operation according to the specified search controls.

    If the list of requested attributes is null or contains the special attribute identifier '*' then all the user attributes at the LDAP entry are returned. If operational attributes are required then those attribute identifiers must be present in the list of requested attributes.

    If objects are requested to be returned, then the Java object-related attributes (RFC 2713) are requested in addition to any requested by the API user. If these attributes are present then they are used to assemble the original objects (see Java Objects). If the object cannot be reconstructed according to RFC 2713 then return a DirContext object representing the LDAP entry. The provider should use the DirectoryManager.getObjectInstance method to satisfy calls to the Binding.getObject method.

    The names which are returned are either relative to the named context or they are LDAP or LDAPS URLs.

    The provider may use an LDAP compare operation instead of an LDAP search when the search filter supplied is suitably constrained:

  • The filter must be of the form "(<attributeID>=<value>)"
  • The scope must be object scope
  • Zero attributes must be requested (empty returning-attributes list)

    • In the forms of search that accept a string filter as argument, the syntax of the filter follows RFC 2254 with the exception that Unicode characters are also allowed. The use of Unicode characters is preferable to the use of encoded UTF-8 octets. The service provider is responsible for translating the Unicode characters into their corresponding UTF-8 representation for transmission to the server. For example, the Greek letter alpha can be specified in the string filter either as "\u03B1" or as "\\CE\\B1".

    In the form search(Name, Attributes) and related methods, the Attributes argument is converted into a string filter by creating a conjunctive expression out of its elements. Each attribute value is treated as a literal; therefore '*' and other special characters defined in RFC 2254 that appear in the values of an attribute should be escaped according to the rules in RFC 2254. For example, an attribute value of '*' should be encoded as the string "\\2a".

    In the form search(Name, String filterExpr, Object[] filterArgs) and its String overloaded method, "{num}" expansion is done in the filter by putting in values from filterArgs. Each "{num}" component may appear in the place of "attr" or "value" in Section 4 from RFC 2254.

    The objects in filterArgs should be encoded in the following way:

  • byte arrays (byte[]) are encoded by encoding each byte as a string according to RFC 2254. For example, the array {0, 1, 10, 100} is encoded as the string "\\00\\01\\0a\\64".
  • Strings are treated as literals. In other words, '*' and other special characters defined in RFC 2254 that appear in the string are escaped according to the rules in RFC 2254. For example, a string of "*" is encoded as the string "\\2a".
  • Objects that are neither String nor byte[] are converted to their string form using Object.toString() and then the rules for String applied.
    • LdapContext.setRequestControls
    Set the request controls for LDAP operations subsequently invoked on this context.
    EventContext.targetMustExist
    Determine whether a listener can register interest in an LDAP entry that doesn't exist.
    Context.unbind
    Perform an LDAP delete operation to remove the named entry. The named entry must be a leaf entry; subtrees are not removed. If the leaf entry does not exist (but its parents exist), the operation still succeeds.

    11. Federation

    The LDAP service provider should support federation using strong separation and either or both of junctions or implicit next naming system pointer.

    12. SASL

    The provider supports SASL mechanisms by means of the Java SASL API (JSR 28). This allows SASL mechanism drivers from different vendors to be used with the LDAP provider, and also allows a SASL mechanism driver to be used with different LDAP providers and even non-LDAP protocol libraries.

    The Java SASL API depends on the Java Authentication and Authorization Service (JAAS), which provides callback support for SASL mechanisms that need to obtain or supply user/application information directly.

    12.1 SASL Configuration

    To specify that SASL authentication be used, you specify the official IANA-registered names of the SASL mechanisms in the java.naming.security.authentication property. The first SASL mechanism on the list that is both available and satisfies the optionally specified policies is used. That is, properties with the prefix "javax.security.sasl.policy." can be used to control the security characteristics of the selected SASL mechanism.

    Some SASL mechanisms require the identity of the entity being authenticated. This is known as the authentication ID. Some SASL mechanisms, like DIGEST-MD5, require the use of a password and/or a realm. By default, the provider supplies the value of java.naming.security.principal property as the authentication ID to any SASL mechanism that requires the authentication ID, the value of the java.naming.security.credentials property as the password, and the value of the java.naming.security.sasl.realm property as the realm. To override these defaults, use the java.naming.security.sasl.callback property.

    SASL mechanisms support the notion of authorization identity or authorization ID, which is the entity to which the server should grant access if the authentication succeeds. If the java.naming.security.sasl.authorizationId property has been set, then its value is used as the authorization ID. Otherwise, the empty string is used as the authorization ID, which directs the server to derive an authorization ID from the client's authentication credentials.

    See SASL properties for a description of the properties used by an LDAP service provider for supporting SASL.

    In addition to these properties, there might be properties required for specific SASL mechanisms. For example, a SASL mechanism that supports privacy and integrity needs to know the quality of protection that the client requires. Properties such as these are passed to the SASL mechanism via the environment properties. See the JNDI documentation for how to set environment properties.

    For example, if the application needs privacy, it can do so by using a call such as:

    env.put("javax.security.sasl.qop", "auth-conf");

    before passing env to the initial context constructor. See the Java SASL API for details about these properties.

    12.2 SASL Mechanism Drivers

    The Java SASL API provides a framework for dynamically plugging in SASL mechanism drivers. The LDAP provider might provide a few default drivers. See the Java SASL API for details.

    13. Extensions and Controls

    The provider supports LDAP extensions and controls using the javax.naming.ldap package. In addition, the provider supports LDAP unsolicited notifications (which are transmitted in LDAP extended operation responses) using the services of the javax.naming.event package.

    Several LDAP extensions and controls are defined by the IETF LDAPEXT working group.

    The "Start TLS" extension ("1.3.6.1.4.1.1466.20037") is supported by the StartTlsRequest and StartTlsResponse classes. The LDAP provider must provide a concrete implementation of the abstract StartTlsResponse class and make its implementation available to the LDAP provider. See the description in StartTlsRequest.createExtendedResponse. Typically, the StartTlsResponse implementation would need access to the LDAP provider's data structures.

    The LDAP service provider should perform hostname verification after Start TLS negotiation as specified in RFC 2830. If the LDAP server was discovered automatically by using information in DNS (as described in the URLs section), the provider should use the domain name derived from the distinguished name as the hostname to verify, as recommended by draft-ietf-ldapext-locate-08.txt.

    14. Event Notification

    The provider supports event notification using the javax.naming.event package.

    A JNDI application can register for events that occur in the directory, such as the addition or removal of an entry, or the modification of an entry. Applications can also register for unsolicited notifications.

    15. SSL

    The provider supports SSL according to the Java Secure Socket Extension (JSSE) specification. SSL is activated by setting the java.naming.security.protocol environment property as follows:
    env.put(Context.SECURITY_PROTOCOL, "ssl");
    and by selecting the hostname and port number of an LDAP server that supports SSL. Once an SSL connection has been established subsequent LDAP protocol exchanges take place over that secure connection.

    If, in addition, LDAP authentication is also required then the java.naming.security.authentication, java.naming.security.principal, and java.naming.security.credentials environment properties should be set, as appropriate. If LDAP authentication is required and the SSL credentials should be reused for LDAP authentication then set the java.naming.security.authentication environment property to select the SASL EXTERNAL mechanism, as follows:

    env.put(Context.SECURITY_AUTHENTICATION, "EXTERNAL");

    Copyright © 2002 Sun Microsystems, Inc. All rights reserved.


Java Naming and Directory Interface

 Documentation Contents
The Java Naming and Directory Interface (JNDI) provides naming and directory functionality to applications written in the Java programming language. It is designed to be independent of any specific naming or directory service implementation. Thus a variety of services--new, emerging, and already deployed ones--can be accessed in a common way.

The JNDI architecture consists of an API (Application Programming Interface) and an SPI (Service Provider Interface). Java applications use this API to access a variety of naming and directory services. The SPI enables a variety of naming and directory services to be plugged in transparently, allowing the Java application using the API of the JNDI technology to access their services.

Enhancements in Java SE 6
New APIs to get the InitialContext
Shorthand methods are provided for getting the InitialContext.
  • doLookup(Name name)
  • doLookup(String name)

LDAP Service Provider
  • Provided a way to specify read timeout for LDAP operations.
  • Support added for pooling of connections created when custom socket factories are used.

RMI Service Provider
  • Provided a property for specifying a socket factory for use by RMI connections.

API and SPI Specification

  • JNDI API and SPI Specification - A list of the packages included in the JNDI technology.

Tutorials

  • JNDI Tutorial - A tutorial introduction to the JNDI technology with programming examples.

API Enhancements

  • See JNDI Enhancements in Earlier Releases

More Information

  • The JNDI Home Page
  • Subscribe to the JNDI-INTEREST list
  • See a demonstration namespace browser written using JNDI and Swing
  • Related documents
  • JNDI Architecture Documents:
    • JNDI API - also available in PDF
    • JNDI SPI - also available in PDF
  • JNDI Service Providers:
    To use JNDI with a particular naming or directory service, you need a JNDI service provider, which is a module that plugs in beneath the JNDI API to access the naming or directory service. The JNDI web site maintains a list of service providers available for JNDI.

    Java 2 SDK, v 1.4 and later releases include the following service providers:

    • The LDAP Service Provider
    • The COS Naming Service Provider
    • The RMI Registry Service Provider
    • The DNS Service Provider

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun Microsystems, Inc


JNDI Enhancements in Earlier Releases

Enhancements in Version 5.0

Support for retrieving an absolute name from the NameClassPair class
This feature enables getting the LDAP Distinguished Name from the SearchResult. To support this, two new methods have been added to the javax.naming.NameClassPair class:
  • getNameInNamespace()
  • setNameInNamespace()

Support for standard LDAP controls
The necessary LDAP controls are already supported in the LDAP Booster Pack extension package which is available for the JNDI/LDAP service provider. The LDAP controls have been recently standardized in RFCs. These are made available in the javax.naming.ldap package of J2SE through the following classes.
  • ManageReferralControl (RFC 3296)
  • PagedResultsControl (RFC 2696)
  • PagedResultsResponseControl
  • SortControl (RFC 2891)
  • SortKey
  • SortResponseControl
  • BasicControl

Support for manipulation of LDAP names
This feature enables easy manipulation of LDAP Names to build distinguished names or relative distinguished names methodically, and enables formatting them into their strings representation as defined by RFC 2253. To support this, two new classes have been added to the javax.naming.ldap package.
  • LdapName
  • Rdn

Enhancements in Version 1.4.1

LDAP Service Provider
  • Support for LDAPS URLs.

Enhancements in Version 1.4.0

DNS Service Provider
  • Support for controlling timeouts when submitting UDP queries.
  • Support for automatic discovery of DNS service.

LDAP Service Provider
  • Support for connection pooling.
  • Support for automatic discovery of LDAP service via DNS.
  • Support for use of multiple URLs for configuration.

Enhancements in Version 1.3

DNS Service Provider
An Internet Domain Naming System (DNS) service provider has been added. This component enables applications to read data stored in the DNS.

Security Enhancements to the LDAP Service Provider
These enhancements bring the LDAP service provider in conformance with standard LDAP security requirements (RFC 2829) and promote better interoperability with widely deployed LDAP servers.

  • Support for the "Start TLS" (Transport Layer Security) extension (RFC 2830) and External SASL authentication mechanism. This enables applications to establish secure sessions over existing LDAP connections. This feature introduces two new classes.
    • javax.naming.ldap.StartTlsRequest
    • javax.naming.ldap.StartTlsResponse
  • Support for the GSS-API/Kerberos v5 SASL authentication mechanism (RFC 2222). This enables secure, authenticated access to the Windows 2000 and XP Active Directory servers.
  • Support for the Digest-MD5 SASL authentication mechanism (RFC 2831).

See the LDAP Service Provider documentation and the JNDI Tutorial for details and examples.

"corbaname" and "corbaloc" URL Support
The COS naming service provider supports the Interoperable Naming Service (INS) specification (99-12-03). This enables applications to use the "corbaname" URL from the initial context and to configure the provider by using the "corbaname" and "corbaloc" URLs.


JNDI/COS Naming Service Provider

COS Naming Service Provider for the
Java Naming and Directory InterfaceTM (JNDI)

Please send feedback to jndi@java.sun.com

Table of Contents

  • Introduction
  • Conformance
  • Environment Properties
  • ORB Initialization
  • Root Naming Context Initialization
  • Names and URLs
  • API Mapping
  • Converting CORBA Programs to use JNDI
  • Security Considerations

Introduction

The Common Object Services (COS) Name Server is the name server for storing Common Object Request Broker Architecture (CORBA) object references. It can be accessed from CORBA applications by using the COS Naming package (org.omg.CORBA.CosNaming).

The JNDI/COS naming service provider implements the javax.naming.Context interface on top of the COS Naming package in order to allow applications to use JNDI to access the COS Name Server. JNDI can also be used to access other naming and directory services, in addition to the COS Name Server, thereby offering the CORBA application one interface for accessing different naming and directory services.

This document describes the features of the COS naming service provider and contains details of how JNDI is mapped to the COS naming package.

Conformance

The COS naming service provider for JNDI uses JavaTM IDL, the Java programming language mapping to the industry standard Object Management Group Interface Definition Language (OMG IDL). In particular, it uses the COS Naming Service.

The complete specification for COS Naming can be obtained from OMG.

The syntax of names conforms to the Interoperable Naming Service (INS) specification (99-12-03), with backward compatibility support for the previous version of INS, OMG TC Document orbos/98-10-11. This is described in Names and URLs.

Environment Properties

The following JNDI environment properties are relevant for the COS naming service provider. See the JNDI documentation for a description of how properties are initialized using the environment properties, system properties, applet parameters, and resource files.

java.naming.factory.initial
This property is used to select the COS naming service provider; it's not actually used by the provider itself. It specifies the class name of the initial context factory for the provider.

For example:

env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.cosnaming.CNCtxFactory");

This property must be set if you are using the COS naming service as the initial context. The only exception is if you supply only URLs to the initial context, in which case, you don't need to specify this property. See Names and URLs for details.

java.naming.provider.url
This property is used to configure the root naming context and/or the Object Request Broker (ORB). Its value is the string representation of a URL.

If this property is not specified, then the ORB is initialized using the java.naming.corba.orb property, the java.naming.applet property, or other ORB initialization properties. The root naming context is obtained by invoking

orb.resolve_initial_references("NameService");

If the URL scheme is one of "IOR", "corbaname", or "corbaloc", as specified in the INS specification (99-12-03), then the root naming context is that named by the URL. The ORB is initialized using the java.naming.corba.orb property, the java.naming.applet property, or other ORB initialization properties.

If the URL scheme is either "iiop" or "iiopname", then the host and port fields of the URL are used to initialize the ORB. An "iiopname" URL must conform to the now obsolete INS specification (98-10-11). It has the form:

iiopname://[<addr_list>][/<cosnaming_name>]

The "iiop" URL scheme is supported for backward compatibility with an older version of the INS specification. It has the form:

iiop://[<host>[:<port>]][/<cosnaming_name>]

For both "iiop" and "iiopname" URLs, if <host> is not specified, then it defaults to "localhost" for an application and the applet's host for an applet. If <port> is not specified, then it defaults to 9999 for "iiopname", and 900 for "iiop". The root naming context is obtained by invoking the following method on the ORB:

orb.resolve_initial_references("NameService");

If <cosnaming_name> is nonempty, then the root naming context is the naming context named by cosnaming_name.

If the URL scheme is not one of "iiop", "iiopname", "IOR", "corbaname", or "corbaloc", then the URL must name a location that contains the stringified IOR of the root naming context. For example, if the property contains "file:/nsdir/ior", then the file /nsdir/ior must contain a stringified IOR. The URL scheme can be any for which there is a corresponding URL protocol handler ( java.net.URLStreamHandler). See the java.net.URL class for details. The stringified IOR is read from the data stream corresponding to the URL by using a character encoding of ISO Latin-1. The stringified IOR is the first line in the stream that contains the prefix "IOR:". For example, if the URL scheme is "http", then the headers in the stream are skipped and the first line that contains the prefix "IOR:" is returned as the IOR.

When the property specifies a stringified IOR or the location of one, the root naming context is that named by the the stringified IOR. The ORB is initialized using the java.naming.corba.orb property, the java.naming.applet property, or other ORB initialization properties.

java.naming.corba.orb
This property specifies the ORB that the program is using. When the JNDI COS naming service provider needs to use an ORB, for example, to look up the "NameService" initial reference or to turn a stringified IOR into an object reference, it will use this ORB.

In an application you can set this property as follows:

ORB orb = ORB.init(args, null);
Hashtable env = new Hashtable(5, 0.75f);
env.put("java.naming.corba.orb", orb);
...
In an applet, you can set it as follows:
public class MyApplet extends Applet {

    public someInitMethod() {
        ORB orb = ORB.init(this, null);
        Hashtable env = new Hashtable(5, 0.75f);
        env.put("java.naming.corba.orb", orb);
        ...
    }
...
}
If this property is not set, then the java.naming.provider.url property, the java.naming.applet property, or the ORB initialization properties are used to initialize the ORB.
java.naming.applet
This property specifies the applet that the program is using. It is used to initialize the ORB to be used by the COS naming service provider. Its parameters are used for setting JNDI-related properties; see the JNDI documentation for details.
public class MyApplet extends Applet {

    public someInitMethod() {
        Hashtable env = new Hashtable(5, 0.75f);
        env.put("java.naming.applet", this);
        ...
    }
...
}

java.naming.factory.state
A colon-separated list of the fully qualified class names of state factory classes used to get an object's state for storing given the object itself. You can use this mechanism to transform an object into forms that can be stored into a COS name server. The COS name server supports storing CORBA objects.

A state factory that transforms a java.rmi.Remote into a CORBA object is supplied by default. This factory is useful for applications that use RMI-IIOP. You can supply other factories to affect the transformation of other objects into CORBA objects for storing. See javax.naming.spi.NamingManager.getStateToBind() for details.

java.naming.factory.object
A colon-separated list of the fully qualified class names of object factory classes for transforming a CORBA object. You can use this mechanism to transform an object into forms expected by the application. For example, a specialized object factory could do the appropriate narrowing to return an object of the expected type. See javax.naming.spi.NamingManager.getObjectInstance() for details.
java.naming.batchsize
Specifies the batch size to use in CosNaming::BindingIterator.next_n when getting the results of a list()/listBindings(). The default is "100."

For example, the following sets the batch size to be 24.

env.put(Context.BATCHSIZE, "24");
ORB initialization properties
You can specify CORBA related properties such as those with the "org.omg.CORBA." prefix as properties. Properties of type String are used to initialize the ORB.

ORB Initialization

The properties that affect which ORB is used and how the ORB is initialized are:

  • java.naming.corba.orb
  • java.naming.applet
  • java.naming.provider.url
  • org.omg.CORBA.* and other ORB-specific properties of type String
The following algorithm is used to determine which ORB is used:
  1. If java.naming.corba.orb has been set, then its value (an ORB) is used.

  2. Otherwise, the provider will internally initialize and use an ORB as follows:

    a) Any org.omg.CORBA.* properties and properties of type String are extracted and used as part of the Properties argument to the ORB.init() method. You can use this mechanism to specify, for example, the ORB implementation or host to use.

    b) If java.naming.provider.url has been set and it contains a URL of scheme "iiop" or "iiopname", then the host and port number specified in the URL are used as part of the Properties argument to the ORB.init() method, overriding any org.omg.CORBA.ORBInitialHost and org.omg.CORBA.ORBInitialPort properties set up in (a).

    c) The Properties instance constructed in (a) and (b) are passed to ORB.init() along with the Applet instance in java.naming.applet property, or an empty String[] if java.naming.applet was not supplied.

If the properties employed in steps (a), (b) and (c) contain no relevant information for initializing the ORB, then the Java IDL implementation's defaults are used. Typically that means port 900 on the local host for an application, and port 900 on the applet host for an applet are used. Note that when the ORB is initialized using ORB.init(), its arguments are checked in the following order: (from org.omg.CORBA.ORB javadoc)

  1. Check in Applet parameter or application string array, if any
  2. Check in properties parameter, if any
  3. Check in the System properties (currently applications only)
  4. Fall back on a hardcoded default behavior (use the Java IDL implementation)

Root Naming Context Initialization

The root naming context is initialized either using the java.naming.provider.url property or by a resolve_initial_references() call on the ORB. If the java.naming.provider.url property is set but contains neither an "iiop" or "iiopname" URL, then it is assumed to contain a stringified IOR, a "corbaname" or "corbaloc" URL of an IOR, or a URL containing the location of a stringified IOR. The IOR is used to obtain the root naming context and must be that of a CORBA object of type CosNaming::NamingContext.

If the java.naming.provider.url has not been set, then the root naming context is obtained by invoking the following method on the ORB:

        orb.resolve_initial_references("NameService");

Names and URLs

String Names

String names accepted by the java.naming.Context methods are JNDI composite names in which each component is the stringified form of a CosNaming::NameComponent.

A CosNaming::Name contains a sequence of CosNaming::NameComponent. The stringified form of a component is the concatenation of the component's id, the kind separator character ('.'), and the component's kind. The occurrence of any meta characters ('.', '/', or '\') in either the id or kind is escaped using the escape character ('\'). The stringified form of a CosNaming::Name is defined in Section 3.5 of the INS specification (99-12-03).

The JNDI composite name syntax is very similar to, but not identical to, the INS syntax. There are minor differences with respect to the treatment of escape and quote characters. If you want to use names with the precise INS syntax, then you should use the overloads that accept a Name argument instead of a String argument. The Name argument should be a value returned by nameParser.parse(), where nameParser is a value obtained from the COS naming service provider. See the Name Parsing section.

URL String Names

The URL form of a CosNaming::Name is defined in the INS specification.

corbaname:<corbaloc_obj>["#" <cosnaming_name>]
where <corbaloc_obj> is
<corbaloc_obj> = <obj_addr_list> ["/" <key_string>]
and <obj_addr_list> is a list of addresses as defined in a "corbaloc" URL and <key_string> is a key string as defined in a "corbaloc" URL. <cosnaming_name> is the stringified form of an INS name (see Name Parsing).

For backward compatibility with older versions of the INS, the following URL schemes are also supported.

iiopname://[<addr_list>][/<cosnaming_name>]

where <addr_list> specifies a list of host/port pairs. If <port> is not specified, then it defaults to 9999. <cosnaming_name> is the stringified form of an INS name.

iiop://<host>[:<port>][/<cosnaming_name>]

If <port> is not supplied, then it defaults to 900. <cosnaming_name> is the stringified form of an INS name.

When you supply an "iiop" or "iiopname" URL to the initial context in this way, the ORB supplied to the initial context is used if its string_to_object() method supports the 99-12-03 INS specification. Otherwise, the ORB is ignored and the server and port designations in the URL are used to create an ORB. The value of the java.naming.factory.initial property is ignored for the purposes of resolving the URL.

Note that this rule is not used when you supply a "corbaname" URL to the initial context. For a "corbaname" URL, the ORB supplied to the initial context is used because the ORB is needed to resolve the "corbaname" URL. Name Objects

The Name argument to a Context method is treated as a sequence of strings, each representing a stringified CosNaming::NameComponent.

Name Parsing

The COS naming service provider supports names in the syntax specified in the INS specification. In short, the syntax is that components are left-to-right slash ('/') separated and case-sensitive. The id and kind of each component are separated by the period character ('.').

Here is a code fragment that uses the name parser from the COS naming service provider to eventually do a lookup using an INS name.

String insName = ...;
InitialContext ctx = new InitialContext(env);   // env contains init properties
NameParser parser = ctx.getNameParser("");      // parser for INS names
Name name = parser.parse(insName);              // get parsed INS name
Object obj = ctx.lookup(name);                  // do lookup

API Mapping

The COS name server supports only naming operations. The COS naming service provider maps the javax.naming.Context methods to use the appropriate COS Naming calls.

addToEnvironment()
Records change to environment property but does not reinitialize ORB.
bind()
Binds an object to the specified name.

If the object being bound is an org.omg.CosNaming.NamingContext, then CosNaming::NamingContext.bind_context is used. If it is an org.omg.CORBA.Object, then CosNaming::NamingContext.bind is used. The binding of any other type of object is not supported unless the object can be converted into an org.omg.CORBA.Object using the state factory mechanism described next.

Before the bind is performed on the naming server, the COS naming service provider uses javax.naming.spi.NamingManager.getStateToBind() to allow the object to be transformed into a org.omg.CORBA.Object. The getStateToBind() method uses the state factories available to the COS naming service provider. If the state factory accepts a java.rmi.Remote object, then it is responsible for obtaining the object's RMI-IIOP stub and connecting it to the ORB associated with the context. The connected stub is the object that will be bound in the naming server.

By default, the COS naming service provider supplies and uses a state factory that transforms an object implementing the java.rmi.Remote interface to an org.omg.CORBA.Object following the requirements described above. This factory uses the utilities in the javax.rmi.CORBA package. You can supply additional state factories to transform objects into CORBA objects.

close()
Releases any internal data structures used.
composeName()
Concatenates the supplied name to the prefix.
createSubcontext()
Uses CosNaming::NamingContext.bind_new_context to create and bind a new context.
destroySubcontext()
Uses CosNaming::NamingContext.destroy to destroy the named context. Then uses CosNaming::NamingContext.unbind to remove the binding.
getEnvironment()
Returns the environment of this context.
getNameInNamespace()
Returns the INS name of this context relative to the root of the Cos Naming namespace.
getNameParser()
Returns a name parser for parsing INS names.
lookup()
lookupLink()
Uses CosNaming::NamingContext.resolve to lookup the name. It returns a CORBA object reference except when the reference is that of a CosNaming::NamingContext, in which case a Context object is returned instead. NamingManager.getObjectInstance() is called before the object is returned in case the application or user has supplied object factories.
list()
listBindings()
Uses CosNaming::NamingContext.resolve to get the object reference for the context, and then uses CosNaming::BindingIterator and helper classes to iterate through the context. The objects bound to the names are obtained by calling CosNaming::NamingContext.resolve on them. NamingManager.getObjectInstance() is called before the object is returned in case the application or user has supplied object factories.
removeFromEnvironment()
Removes the specified property from the environment but does not otherwise update the context.
rebind()
If the object being bound is an org.omg.CosNaming.NamingContext, then CosNaming::NamingContext.rebind_context is used. If it is an org.omg.CORBA.Object, then CosNaming::NamingContext.rebind is used. See bind() for details on the use of state factories to transform the argument into an org.omg.CORBA.Object.
rename()
This method is implemented using bind() followed by unbind(). It is not atomic.
unbind()
Uses CosNaming::NamingContext.unbind to unbind the object.

Converting CORBA Programs to use JNDI

This section explains how to modify your Java IDL program to use JNDI. The explanation uses the Java IDL sample programs helloClient.java and helloServer.java.

  1. Generate the stubs from the IDL file.

    # idltojava -fclient -fserver hello.idl

    This creates the client (helloClient.java) and server (helloServer.java) skeletons, and a directory containing common code (e.g. HelloApp/*.java).

  2. Fill in the code for the client and server programs.

  3. Modify (or copy the client and server files) to use JNDI instead of COS Naming directly.

    • Replace the import to use javax.naming.*;
      Delete:
      import org.omg.CosNaming.*;
import org.omg.CosNaming.NamingContextPackage.*;
      Add:
      import javax.naming.*;
    • Replace how you get the initial reference to "NameService" with InitialContext, supplying the initial context the ORB being used by the current application.
      Delete:
      org.omg.CORBA.Object objRef =
   orb.resolve_initial_references("NameService");
NamingContext ncRef = NamingContextHelper.narrow(objRef);
      Add:
      Hashtable env = new Hashtable(5, 0.75f);
env.put("java.naming.corba.orb", orb);
Context ic = new InitialContext(env);
    • Replace the call to resolve() to use lookup().
      Delete:
      // resolve the Object Reference in Naming
NameComponent nc = new NameComponent("Hello", "");
NameComponent path[] = {nc};
hello helloRef = helloHelper.narrow(ncRef.resolve(path));
      Add:
      // resolve the Object Reference using JNDI
hello helloRef =
helloHelper.narrow((org.omg.CORBA.Object)ic.lookup("Hello"));

Security Considerations

When a security manager has been installed, you must grant to the application using JNDI and the COS naming service provider the following permissions:

permission java.net.SocketPermission "host[:port]", "connect";
For each host/port identified in the java.naming.factory.initial property, in URL string names supplied to context methods, in ORB initialization parameters and properties, and in object references.

Copyright © 1999-2001 Sun Microsystems, Inc., All Rights Reserved.


JNDI/DNS Service Provider

DNS Service Provider for the
Java Naming Directory InterfaceTM (JNDI)

Please send feedback to jndi@java.sun.com

Table of Contents

  • Introduction
  • Conformance
  • Environment Properties
  • Mapping DNS Content to JNDI
  • DNS Pseudo-URLs
  • API Mapping
  • Usage Examples
  • Security Considerations
  • Federation

Introduction

The DNS service provider allows JNDI applications to access information stored in the internet Domain Name System. The provider presents the DNS namespace as a tree of JNDI directory contexts, and DNS resource records as JNDI attributes.

This document describes the features of the DNS service provider, and contains details of how DNS is mapped onto JNDI.

Conformance

The DNS service provider supports the Domain Name System as described in RFC 1034 and RFC 1035, and as updated and clarified by RFC 1123 and RFC 2181. It currently supports the following resource record types and classes:

Type Where Specified
A | RFC 1035
NS | RFC 1035
CNAME | RFC 1035
SOA | RFC 1035
PTR | RFC 1035
MX | RFC 1035
TXT | RFC 1035
HINFO | RFC 1035
AAAA | RFC 1886
NAPTR | RFC 2915
SRV | RFC 2782
Class | Where Specified
IN | RFC 1035
HS | RFC 1035
Each lookup is initially performed using UDP. If the response is too long to be returned in a UDP packet without being truncated, the lookup is repeated using TCP.

Environment Properties

The following JNDI environment properties are relevant to the DNS service provider. See the JNDI documentation for a description of how properties are initialized using the initial context constructor, system properties, applet parameters, and resource files.

java.naming.authoritative
This property is used to specify whether all responses must be authoritative. If its value is "true", only authoritative responses are accepted from DNS servers; otherwise, all responses are accepted. If this property has not been set, the default is "false". Here is an example that specifies that all responses must be authoritative.
env.put(Context.AUTHORITATIVE, "true");
Note that some information might be made unavailable when you request that only authoritative responses be returned because the DNS protocol does not provide a way to request authoritative information. For example, the DNS service provider might have retrieved nonauthoritative data as the result of a query and is subsequently forced to discard it because only authoritative data may be returned.
java.naming.factory.initial
This property is used to select the DNS service provider as the initial context. It is not used by the provider itself. It specifies the class name of the initial context factory for the provider, and may be set as in the following example:
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.dns.DnsContextFactory");

java.naming.factory.object
This property contains a colon-separated list of the fully-qualified class names of object factories for transforming objects read from DNS. This mechanism is used to transform objects into forms more useful to the application. See DirectoryManager.getObjectInstance() for details.
java.naming.provider.url
This property specifies the host name and port of the DNS server used by the initial DNS context, as well the initial context's domain name. For details on the URL format see DNS Pseudo-URLs below.

For example:

env.put(Context.PROVIDER_URL, "dns://server1.sun.com/java.sun.com");
will cause the provider to use the DNS server at server1.sun.com, and set the initial context's domain name to java.sun.com. If this property is not set, it defaults to "dns:" (all defaults as described in the DNS Pseudo-URLs section are used).

Multiple DNS servers may be specified by setting this property to a space-separated list of URLs. Each of the servers is contacted in turn until one of them responds. Since the initial context has only a single domain name, if multiple URLs are listed then each must contain the same domain part. For example:

env.put(Context.PROVIDER_URL,
    "dns://server1.sun.com/java.sun.com dns://server2.sun.com/java.sun.com");

com.sun.jndi.dns.lookup.attr
Before JNDI invokes an object factory on a DNS context, it by default reads and passes to the factory any internet TXT attributes of the context. This property, if set, names an alternate attribute identifier to use. See Mapping DNS Content to JNDI below for information on the format of attribute identifiers.
com.sun.jndi.dns.recursion
This property is used to specify that recursion is disallowed on DNS queries. If this property has not been set or if it has been set to "true", recursion is allowed; otherwise, recursion is disallowed. Here is an example that specifies that recursion on DNS queries is to be disallowed.
env.put("com.sun.jndi.dns.recursion", "false");

com.sun.jndi.dns.timeout.initial
com.sun.jndi.dns.timeout.retries
These properties are used to alter the timeout-related defaults that the DNS provider uses when submitting UDP queries. The DNS provider submits UDP queries using the following exponential backoff algorithm. The provider submits a query to a DNS server and waits for a response to arrive within a timeout period (1 second by default). If it receives no response within the timeout period, it queries the next server, and so on. If the provider receives no response from any server, it doubles the timeout period and repeats the process of submitting the query to each server, up to a maximum number of retries (4 by default).

The "com.sun.jndi.dns.timeout.initial" property, if set, specifies the number of milliseconds to use as the initial timeout period (i.e., before any doubling). If this property has not been set, the default initial timeout is 1000 milliseconds.

The "com.sun.jndi.dns.timeout.retries" property, if set, specifies the number of times to retry each server using the exponential backoff algorithm described previously. If this property has not been set, the default number of retries is 4.

Here is an example that doubles the initial timeout period while keeping total length of all timeouts roughly unchanged.

env.put("com.sun.jndi.dns.timeout.initial", "2000");
env.put("com.sun.jndi.dns.timeout.retries", "3");

NOTE: On systems earlier than the Java 2 SDK, v 1.4.1, these two properties are ignored and the defaults always apply.

Mapping DNS Content to JNDI

The DNS service provider maps DNS names, nodes, and resource records onto JNDI data types as follows.

Names

DNS domain names are represented by JNDI compound Name objects with right-to-left, dot-separated syntax, and with backslash (\) as the escape character. Escape sequences of the form \DDD may also be used, where DDD is a three-digit decimal value. Names are case-insensitive. A fully-qualified name ending with an explicit root domain label (".") is represented by a compound Name object with an empty component in the most-significant position.

Host names are a subset of domain names. Their labels contain only US-ASCII letters, digits, and hyphens, and none may begin or end with a hyphen. While names not conforming to these rules may be valid domain names, they will not be usable by a number of DNS applications, and should in most cases be avoided.

DNS does not specify an encoding (such as UTF-8) to use for characters other than those of US-ASCII. As a consequence, no character in a DNS name will ever have a non-zero high-order byte. When work on internationalizing domain names is finalized, the DNS service provider may be updated to conform to that work.

Nodes and Resource Records

A DNS node is represented by a DirContext object. The resource records of the node are represented by attributes of the context. For example, if the DNS node sun.com contains an A record with the address 192.9.49.33 and an MX record with the data "10 sun.com", the corresponding JNDI context will have an attribute with identifier "A" and string value "192.9.49.33" and an attribute with identifier "MX" and string value "10 sun.com".

Multiple records of the same type are represented as multi-valued attributes. Records of unsupported types are represented by attributes with numeric identifiers and with byte arrays as values.

Attribute Identifiers

DNS resource record class and type names are mapped onto JNDI attribute identifiers. If a record is in the internet class, the corresponding attribute ID is simply the record's type name. If the type is an unsupported one, its integer value is used instead. If the record is not in the internet class, the class name (or integer class value) is prepended to the attribute ID, separated by a space. For example, the attribute identifier "AAAA" represents an IPv6 address record, and the attribute identifier "HS 97" represents a resource record of type 97 in the Hesiod class.

Superclass attribute identifiers are also defined. These may be useful when querying records using the DirContext.getAttributes() method. If an attribute name has "*" in place of a type name (or class name), it represents records of any type (or class). For example, the attribute identifier "IN *" may be passed to the getAttributes() method to find all internet class records. The attribute identifier "* *" represents records of any class or type.

Attribute identifiers are case-insensitive.

DNS Pseudo-URLs

A URL-like notation is used to represent a DNS server, port, and domain in the java.naming.provider.url property and in URL names passed to the initial context. The format of this pseudo-URL is:
   dns:[//host[:port]][/domain]
The host and port indicate the DNS server to use. If only a host is given, the port defaults to 53; if only a port is given, the host defaults to "localhost". If neither is given, the provider will attempt to determine and use the server(s) configured for the underlying platform, and if successful, will set the java.naming.provider.url property to a space-separated list of URLs constructed using the server(s). (For example, on Solaris or Linux, the provider will read the /etc/resolv.conf file.) If DNS has not been configured on the underlying platform, the host and port default to "localhost" and 53.

NOTE: On systems earlier than the Java 2 SDK, v 1.4.1, the provider does not attempt to use the underlying platform's DNS configuration. If neither host nor port is specified, they default to "localhost" and 53, respectively.

The domain is the DNS domain name of the context, and is not necessarily related to the domain of the server. It defaults to "." (the root domain).

API Mapping

The DNS service provider implements the DirContext interface. Methods are mapped onto DNS operations as described below. Methods not listed are not supported.
addToEnvironment()
Adds a new property to the environment, or changes an existing property.
close()
Releases internal data structures.
composeName()
Composes two names.
getAttributes()
Returns attributes representing DNS resource records.
getEnvironment()
Returns the environment properties associated with this context.
getNameInNamespace()
Returns the fully-qualified domain name of this node.
getNameParser()
Returns a name parser for DNS domain names.
lookup()
lookupLink()
Returns a DirContext that represents the named node. The DirectoryManager.getObjectInstance() method is invoked on the object before it is returned, in case the application or user has supplied object factories.
list()
listBindings()
The listing of the DNS namespace is implemented using zone transfers, so these operations are potentially compute- and network-intensive, and they may not be supported by all DNS installations. The DirectoryManager.getObjectInstance() method is invoked on an object before it is returned, in case the application or user has supplied object factories; no attributes are passed in.
removeFromEnvironment()
Removes a property from the environment.

Usage Examples

Example 1

In this example we create an initial context representing the sun.com domain, then read the IP addresses (the A records) of two hosts in that domain.
Hashtable env = new Hashtable();
env.put("java.naming.factory.initial", "com.sun.jndi.dns.DnsContextFactory");
env.put("java.naming.provider.url",    "dns://server1.sun.com/sun.com");

DirContext ictx = new InitialDirContext(env);
Attributes attrs1 = ictx.getAttributes("host1", new String[] {"A"});
Attributes attrs2 = ictx.getAttributes("host2", new String[] {"A"});

Example 2

Instead of using the properties as above, we may pass a DNS pseudo-URL to the methods of the default initial context. In this example we read the MX record of a host in the sun.com domain.
DirContext ictx = new InitialDirContext();
Attributes attrs3 = ictx.getAttributes("dns://server1.sun.com/host3.sun.com",
                                       new String[] {"MX"});

Security Considerations

When a security manager has been installed, the DNS service provider and the application using it must both be granted the following permissions:

permission java.net.SocketPermission "host[:port]", "connect,accept";
for each host/port identified in the java.naming.provider.url property, in URL string names supplied to context methods, and in object references.

Federation

The DNS service provider treats composite names as strongly separated. That is, it processes the first component of the composite name as a DNS domain name and the rest of the components as names in the next naming system(s) (nns). The implicit next naming system is determined dynamically.

For example, here is an example that lists the root of the next naming system federated beyond a DNS context, and one that looks up a name using a multi-component composite name:

// List the root of the nns.
// Note the use of a trailing slash to indicate traversal into the nns.
NamingEnumeration enum = ctx.list("java.sun.com/");

// A composite name lookup.
Object obj = ctx.lookup("sun.com/some/x/y/z");

Copyright © 2002 Sun Microsystems, Inc. All rights reserved.


JNDI/LDAP Service Provider

LDAP Naming Service Provider for the
Java Naming and Directory InterfaceTM (JNDI)

Please send feedback to jndi@java.sun.com

Table of Contents

  1. Introduction
  2. Conformance
  3. Environment Properties
  4. Names
  5. Attributes
  6. URLs
  7. Java Objects
  8. Schema
  9. Exceptions
  10. API Mapping
  11. Federation
  12. Event Notification
  13. SASL Authentication
  14. SSL and Start TLS
  15. Connection Pooling
  16. Security Considerations

1. Introduction

The Lightweight Directory Access Protocol (LDAP) is an Internet standard for accessing directory services. The JNDI/LDAP service provider provides access to servers implementing the LDAP protocols.

This document describes the features of the LDAP service provider. A major portion of the description is couched in terms of how the LDAP service provider behaves with respect to the descriptions in Guidelines for LDAP Service Providers. For examples and descriptions of how to use this provider, please see the JNDI Tutorial.

The LDAP service provider implements the basic features for LDAP access. Additional functionality, such as support for a number of popular LDAP controls, and for storing and reading RMI and CORBA objects, can be added to the basic provider by installing a booster pack, available for download at the JNDI Web site.

2. Conformance

The LDAP service provider conforms to the following standards:
Standard | Supported | Comments
LDAPv3 (RFC 2251) | Yes |
LDAPv3 Attributes (RFC 2252) | Yes |
LDAPv3 Distinguished Names (RFC 2253) | Yes |
LDAP Search Filters (RFC 2254) | Yes |
LDAP URL Format (RFC 2255) | Yes |
LDAPv3 Schema (RFC 2256) | Yes |
LDAPv2 (RFC 1777) | Yes |
LDAP Authentication (RFC 2829) | Yes |
Start TLS Extension (RFC 2830) | Yes |
DIGEST-MD5 (RFC 2831) | Yes |
Manage Referral Control (RFC 3296) | Yes |
Paged Results Control (RFC 2696) | Yes |
Sort Control (RFC 2891) | Yes |

3. Environment Properties

Descriptions of JNDI, LDAP-specific, and SASL-specific properties are found in Guidelines for LDAP Service Providers.

3.1 JNDI Properties

The LDAP service provider supports the following JNDI environment properties:
Property | Supported | Comments
java.naming.batchsize | Yes | Default value is 1.
java.naming.factory.control | Yes |
java.naming.factory.initial | Yes | Specify com.sun.jndi.ldap.LdapCtxFactory to use the LDAP service provider as the initial context.
java.naming.factory.object | Yes |
java.naming.factory.state | Yes |
java.naming.language | No | Ignored by the provider.
java.naming.provider.url | Yes | On systems earlier than the Java 2 SDK, v 1.4.1, can contain only a single URL. On systems earlier than the Java 2 SDK, v 1.4.2, cannot contain LDAPS URLs.
java.naming.referral | Yes |
java.naming.security.authentication | Yes | simple, none, list of SASL mechanisms
java.naming.security.credentials | Yes |
java.naming.security.principal | Yes |
java.naming.security.protocol | Yes | ssl

3.2 LDAP-specific Properties

The provider supports the following LDAP-specific environment properties:
Property | Supported | Comments
java.naming.ldap.attributes.binary | Yes |
java.naming.ldap.control.connect | Yes |
java.naming.ldap.deleteRDN | Yes |
java.naming.ldap.derefAliases | Yes |
java.naming.ldap.factory.socket | Yes | Default value is javax.net.ssl.SSLSocketFactory when the java.naming.security.protocol property is set to ssl. See the SSL Section for details.
java.naming.ldap.ref.separator | Yes |
java.naming.ldap.referral.limit | Yes |
java.naming.ldap.typesOnly | Yes |
java.naming.ldap.version | Yes |

3.3 SASL-specific Properties

The provider supports the following SASL-specific environment properties:
Property | Supported | Comments
java.naming.security.sasl.authorizationId | Yes |
java.naming.security.sasl.callback | Yes |
java.naming.security.sasl.realm | Yes |
javax.security.sasl.qop | Yes |
javax.security.sasl.strength | Yes | Cipher selected depends on the ciphers available from the Java Cryptography Extension (JCE) service providers in the Java platform.
javax.security.sasl.maxbuffer | Yes |
javax.security.sasl.server.authentication | Yes |
javax.security.sasl.policy.forward | Yes |
javax.security.sasl.policy.credentials | Yes |
javax.security.sasl.policy.noplaintext | Yes |
javax.security.sasl.policy.noactive | Yes |
javax.security.sasl.policy.nodictionary | Yes |
javax.security.sasl.policy.noanonymous | Yes |

3.4 Provider-specific Properties

The LDAP service provider defines the following provider-specific environment properties:
com.sun.jndi.ldap.connect.pool
This property is used to specify that a pooled connection should be used when creating the initial context instance. If its value is "true", the provider will use a pooled connection if the parameters for creating a connection (referred to as the connection request) meet the criteria set forth by the connection pool configuration. If this property has not been set, or if it has been set to any other value, or if the connection request does not meet the criteria, the provider will not use a pooled connection. See the Connection Pooling section for more information on connection pooling.

For example, the following code

env.put("com.sun.jndi.ldap.connect.pool", "true");
directs the LDAP provider to use a pooled connection when creating an initial context.

NOTE: On systems earlier than the Java 2 SDK, v 1.4.1, connection pooling is not supported and therefore, this property is ignored.

com.sun.jndi.ldap.connect.timeout
The value of this property is the string representation of an integer representing the connection timeout in milliseconds. If the LDAP provider cannot establish a connection within that period, it aborts the connection attempt. The integer should be greater than zero. An integer less than or equal to zero means to use the network protocol's (i.e., TCP's) timeout value.

If this property is not specified, the default is to wait for the connection to be established or until the underlying network times out.

For example,

env.put("com.sun.jndi.ldap.connect.timeout", "500");
causes the LDAP service provider to abort the connection attempt if a connection cannot be established in half a second.

When connection pooling has been requested for a connection, this property also determines the maximum wait time for a connection when all connections in the pool are in use and the maximum pool size has been reached. If the value of this property is less than or equal to zero under such circumstances, the provider will wait indefinitely for a connection to become available; otherwise, the provider will abort the wait when the maximum wait time has been exceeded. See the Connection Pooling section for details.

NOTE: On systems earlier than the Java 2 SDK, v 1.4, this property is ignored because there is no support in the SDK for connection timeouts.

com.sun.jndi.ldap.read.timeout
The value of this property is the string representation of an integer representing the read timeout in milliseconds for LDAP operations. If the LDAP provider cannot get a LDAP response within that period, it aborts the read attempt. The integer should be greater than zero. An integer less than or equal to zero means no read timeout is specified which is equivalent to waiting for the response infinitely until it is received.

If this property is not specified, the default is to wait for the response until it is received.

For example,

env.put("com.sun.jndi.ldap.read.timeout", "5000");
causes the LDAP service provider to abort the read attempt if the server does not respond with a reply within 5 seconds.

NOTE: On systems earlier than the Java SDK, v 6.0, this property is ignored because there is no support in the SDK for read timeouts.

com.sun.jndi.ldap.netscape.schemaBugs
The Netscape Directory Server 4.0 and earlier releases do not support schema entries that comply with RFC 2252. Specifically, contrary to RFC 2252, the Netscape server requires OIDs (such as those for SUP and SYNTAX) be delimited by single quotes and MUST/MAY lists be enclosed by parentheses. When you update the schema of the Netscape Directory Server 4.0, you need to use this property to get around these problems.

The following values are defined for this property:

true
activate the workaround.
false
do not activate the workaround.

If this property is not set then its default value is false.

For example,

env.put("com.sun.jndi.ldap.netscape.schemaBugs", "true");
activates the workaround.

NOTE 1: This property may only be passed to the initial context and becomes fixed for the provider. It is unaffected by the addToEnvironment or removeFromEnvironment methods.

NOTE 2: If you are using Netscape Directory Server 4.1, do not use this property. The 4.1 server has problems parsing object class definitions that contain MUST/MAY clauses without parentheses. If you are creating or modifying an object class definition that contains a single MUST/MAY item, work around the bug by adding a superfluous value (such as 'objectClass') to the MUST/MAY list.

com.sun.jndi.ldap.trace.ber
The value of this property is a java.io.OutputStream object into which a hexadecimal dump of the incoming and outgoing LDAP ASN.1 BER packets is written.

No default is defined for this property.

For example,

env.put("com.sun.jndi.ldap.trace.ber", System.out);
directs the LDAP protocol trace to the standard output stream.

NOTE: This property may only be passed to the initial context and becomes fixed for the provider. It is unaffected by the addToEnvironment or removeFromEnvironment methods.

4. Names

The LDAP service provider supports names in accordance with the description in Guidelines for LDAP Service Providers. It supports LDAP distinguished names in the following formats:
Distinguished Name format | Comments
String | Treat as composite name. Process the first component of the composite name as a distinguished name. Use rest of the components for federation.
Name | If instance of CompositeName, treat as composite name, which means process the first component of the composite name as a distinguished name and use the rest for federation. Otherwise, treat as parsed LDAP name, where each component of Name is a component of the LDAP name as defined in RFC 2253.
LDAP URL String | When passed to the initial context, the LDAP URL string is interpreted according to RFC 2255, and its distinguished name component interpreted according to RFC 2253.
LDAPS URL String | When passed to the initial context, the LDAPS URL string is interpreted like an LDAP URL, except that an SSL connection is used to communicate with the server. NOTE: On systems earlier than the Java 2 SDK, v 1.4.2, the LDAP service provider does not recognize LDAPS URLs.

The name parser returned by an invocation of getNameParser() returns a parser that, when given a string name, parses it into components in accordance with RFC 2253.

5. Attributes

The LDAP service provider supports attributes in accordance with the description in Guidelines for LDAP Service Providers. It supports the following formats for specifying LDAP attribute values:
Attribute value format | Supported | Comments
String values | Yes |
byte[] values | Yes |

Some LDAP servers support attribute subtyping, attribute name synonyms, and language codes for specifying language preferences for attribute values. In such cases, the attribute name returned by an LDAP server may be different from the one which was requested.

In LDAP, attribute names are case-insensitive. Therefore, when creating a collection of attributes to be passed as a parameter to JNDI operations, it is recommended to use a case-insensitive attributes class. For example,

Attributes attrs = new BasicAttributes(true); // ignoreCase=true

For all attribute values, regardless of whether they are String or byte[], you need to know the syntax and format of the attribute value. You can typically find this out by reading the schema document in which the attribute and its syntax is defined.

When attributes are supplied as arguments to JNDI calls then they must satisfy whatever schema is enforced at the LDAP directory. In particular, the objectClass attribute is normally required when creating a new LDAP entry (for example, when using Context.bind, Context.rebind or DirContext.createSubcontext).

6. URLs

6.1 Uses

The LDAP service provider supports URLs in accordance with the description in Guidelines for LDAP Service Providers. It supports both LDAP and LDAPS URLs.

It supports the following use of URLs:

URL usage | Supported | Comments
LDAP and LDAPS URLs to configure the LDAP service provider. | Yes |
URLs passed as names to the InitialDirContext methods. | Yes |
URLs in LDAP referrals | Yes | The scope component of LDAP/LDAPS URLs is supported. The attributes, filter and extensions components are ignored.
URLs returned as names in list, listBindings, and search enumerations. | Yes |
URLs linking federated namespaces. | Yes |

NOTE: On systems earlier than the Java 2 SDK, v 1.4.2, the LDAP service provider does not recognize or return LDAPS URLs.

6.2 Automatic Discovery of LDAP Service

The LDAP service provider supports the use of DNS configuration for automatically discovering the LDAP service. When an LDAP/LDAPS URL in the above usage cases is missing the hostname and port but has a non-empty distinguished name, the LDAP service provider will attempt to locate the LDAP servers to use as described in the Guidelines for LDAP Service Providers.

For example, given a URL of ldap:///dc=example,dc=com, the service provider will try to locate the DNS SRV records for _ldap._tcp.example.com. If the provider finds such records, it will then extract and use the hostnames and ports of the LDAP servers from the records. The order in which it uses these records follows the algorithm described in the Internet draft draft-ietf-ldapext-locate-08.txt.

For locating the DNS SRV records of the LDAP service, the LDAP service provider uses the DNS service configured for the underlying platform (on Solaris or Linux, for example, the DNS client configuration is read from the /etc/resolv.conf file). If DNS has not been configured for the underlying platform, the LDAP service provider will use localhost and 53 as the hostname and port of the DNS server. If no DNS service is available, or if the DNS service does not have the LDAP service's SRV records, the LDAP service provider will use localhost as the hostname, and 389 as the port for a plain connection and 636 as the port for an SSL connection.

NOTE 1: On systems earlier than the Java 2 SDK, v 1.4.1, unspecified hostname and port always default to localhost and 389, respectively; no attempt is made to use DNS.

NOTE 2: On systems earlier than the Java 2 SDK, v 1.4.2, the default port is always 389 regardless of whether SSL is being used.

7. Java Objects

The LDAP service provider supports storing and reading the following types of objects, as specified in Guidelines for LDAP Service Providers.
Storable/Readable Objects | Supported | Comments
Reference objects | Yes |
Referenceable objects | Yes |
Serializable objects | Yes |
DirContext objects | Yes |

See the JNDI Tutorial for examples.

8. Schema

The LDAP service provider supports the following schema bindings, as specified in Guidelines for LDAP Service Providers.
Schema Tree | Supported | Comments
AttributeDefinition | Yes |
ClassDefinition | Yes |
SyntaxDefinition | Yes |
MatchingRule | Yes |
ExtensionDefinition | No |
ControlDefinition | No |
SASLMechanism | No |

9. Exceptions

The LDAP service provider maps LDAP error codes to JNDI exceptions according to Guidelines for LDAP Service Providers.

10. API Mapping

The LDAP service provider maps the following JNDI API methods to LDAP according to Guidelines for LDAP Service Providers:
Mapping for Context methods | Supported | Comments
addToEnvironment | Yes |
bind | Yes |
close | Yes |
composeName | Yes |
destroySubcontext | Yes |
getEnvironment | Yes |
getNameInNamespace | Yes |
getNameParser | Yes |
list | Yes |
listBindings | Yes |
lookup | Yes | Does not process LinkRef specially.
lookupLink | Yes |
rebind | Yes |
removeFromEnvironment | Yes |
rename | Yes |
unbind | Yes |
Mapping for DirContext methods | Supported | Comments
bind | Yes |
createSubcontext | Yes |
destroySubcontext | Yes |
getAttributes | Yes |
getSchema | Yes |
getSchemaClassDefinition | Yes |
modifyAttributes | Yes |
rebind | Yes |
search | Yes |
Mapping for LdapContext methods | Supported | Comments
extendedOperation | Yes |
getRequestControls | Yes |
getResponseControls | Yes |
newInstance | Yes |
reconnect | Yes |
setRequestControls | Yes |
Mapping for EventDirContext methods | Supported | Comments
addNamingListener | Yes |
removeNamingListener | Yes |
targetMustExist | Yes |

11. Federation

The LDAP service provider supports federation in accordance with the description in Guidelines for LDAP Service Providers. It supports the following federation techniques:
Federation Technique | Supported | Comments
Junction | Yes | Except when subordinate naming system is another LDAP system
Implicit Next Naming System Pointer | Yes |

The LDAP service provider treats composite names as strongly separated. That is, it processes the first component of the composite name as a distinguished name and the rest of the components as names in the next naming system(s). For example, here are examples that lists the root of the next naming system federated beyond an LDAP context and looks up a name using a multicomponent composite name:

// List the root of the nns,
// Note use of the trailing slash to indicate traversal into the nns
NamingEnumeration enum = ctx.list("cn=objects,ou=Sales/");

// A composite name lookup
Object obj = ctx.lookup("cn=objects,ou=Sales/some/x/y/z");

12. Event Notification

The LDAP service provider supports event notification in accordance with the description in Guidelines for LDAP Service Providers. It supports the following events:
Event | Supported | Comments
Namespace change notification | Yes | Uses the persistent search control*
Object change notification | Yes | Uses the persistent search control*
Unsolicited notification | Yes |

* The persistent search control is defined in the IETF Internet-Draft draft-ietf-ldapext-psearch-03.txt.

13. SASL Authentication

The LDAP service provider supports SASL authentication in accordance with the description in Guidelines for LDAP Service Providers.

The LDAP service provider supports the following SASL mechanisms.

  • EXTERNAL (RFC 2222). This mechanism obtains authentication information from an external source (such as SSL/TLS or IPsec).
  • DIGEST-MD5 (RFC 2831) is for Digest Authentication.
  • GSSAPI (RFC 2222) is for Kerberos V5 authentication.
In addition to these mechanisms, the provider supports additional SASL mechanisms made available via the framework defined in the Java SASL API (JSR 28 Public Review Draft), with the exception that the package is named com.sun.security.sasl.preview instead of javax.security.sasl.

14. SSL and Start TLS

14.1 SSL

The LDAP service provider supports SSL in accordance with the description in Guidelines for LDAP Service Providers. It uses the default socket factory javax.net.ssl.SSLSocketFactory unless the java.naming.ldap.factory.socket property has been set to the class name of some other socket factory.

When SSL is being used and no port has been specified, 636 is used as the default port.

NOTE: On Java 2 SDK, v 1.4.1 and earlier systems, the default port is always 389, regardless of whether SSL is being used.

14.2 Start TLS

The LDAP provider supports the the "Start TLS" extension ("1.3.6.1.4.1.1466.20037") by supplying a concrete implementation of the StartTlsResponse abstract class. Hostname verification is performed as per the Guidelines for LDAP Service Providers.

15. Connection Pooling

NOTE: Connection pooling is supported only on the Java 2 SDK, v 1.4.1 and later releases.

15.1 Overview

The LDAP service provider supports connection pooling by maintaining pools of previously used connections. Whenever the LDAP provider needs a connection (and the application has requested pooling), it gets a connection from the pool. If an existing connection is available, it will be used. If no existing connection is available, a new connection is created and used. When the provider is done with the connection, the connection is marked idle and can be reused.

An application requests connection pooling by adding the property, com.sun.jndi.ldap.connect.pool, to the environment properties passed to the initial context constructor. An application can decide whether to use pooling on a per-context basis by using environment properties with and without this property. This same mechanism is used to control whether pooled connections are used for referral handling and processing of LDAP/LDAPS URLs passed to the initial context. For example, when this property is present in the environment when the provider is processing a referral, the provider will use a pooled connection for the referral.

Here is sample code that requests that connection pooling be used for a new initial context and all contexts derived from it.

Hashtable env = new Hashtable();
env.put("com.sun.jndi.ldap.connect.pool", "true");
env.put(Context.PROVIDER_URL, url);
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
DirContext ctx = new InitialDirContext(env);
...

Only the addition of the single property, com.sun.jndi.ldap.connect.pool, is required; no other changes are required to the application.

The LDAP provider keeps track of whether a connection is being used through indications from the application. It assumes that an application that is maintaining an open context handle is using the connection. Therefore, in order for the LDAP provider to properly manage the pooled connections, the application must be diligent about invoking Context.close() on contexts that it no longer needs.

Bad connections are automatically detected and removed from the pool. The probability of a context ending up with a bad connection is the same regardless of whether connection pooling is used.

15.2 When Not to Use Pooling

Pooled connections are intended to be reused. Therefore, an application that plans on performing operations on a context that might alter the underlying connection's state should not use connection pooling for the context. Specifically, if an application is planning to use the Start TLS extended operation on a context, or is planning to change security-related properties (such as java.naming.security.principal or java.naming.security.protocol) after the initial context has been created, it should not use connection pooling for that context. Using connection pooling under such circumstances might compromise the security of the application and/or create unexpected behavior.

15.3 Global Configuration

Connection pooling is configured and maintained per Java runtime. Connections are not shared across different runtimes. To use connection pooling, no configuration is required. Configuration is necessary only if you want to customize how pooling is done, such as controlling the size of the pools and which connections are pooled.

Connection pooling is configured by a number of System properties at runtime startup time. Note that these are System properties, not environment properties and that they affect all connection pooling requests.

Here is a summary of the system properties. They are described in more detail in the rest of this section.

System Property Name | Description | Default
com.sun.jndi.ldap.connect.pool.authentication | A list of space-separated authentication types of connections that may be pooled. Valid types are "none", "simple", and "DIGEST-MD5". | "none simple"
com.sun.jndi.ldap.connect.pool.debug | A string that indicates the level of debug output to produce. Valid values are "fine" (trace connection creation and removal) and "all" (all debugging information). |
com.sun.jndi.ldap.connect.pool.initsize | The string representation of an integer that represents the number of connections per connection identity to create when initially creating a connection for the identity. | 1
com.sun.jndi.ldap.connect.pool.maxsize | The string representation of an integer that represents the maximum number of connections per connection identity that can be maintained concurrently. | no maximum size
com.sun.jndi.ldap.connect.pool.prefsize | The string representation of an integer that represents the preferred number of connections per connection identity that should be maintained concurrently. | no preferred size
com.sun.jndi.ldap.connect.pool.protocol | A list of space-separated protocol types of connections that may be pooled. Valid types are "plain" and "ssl". | "plain"
com.sun.jndi.ldap.connect.pool.timeout | The string representation of an integer that represents the number of milliseconds that an idle connection may remain in the pool without being closed and removed from the pool. | no timeout

Here is an example that sets the maximum pool size to 20, the preferred pool size to 10, and the idle timeout to 5 minutes for pooled connections.

# java -Dcom.sun.jndi.ldap.connect.pool.maxsize=20 \
       -Dcom.sun.jndi.ldap.connect.pool.prefsize=10 \
       -Dcom.sun.jndi.ldap.connect.pool.timeout=300000 \
    YourProgram

15.3.1 What Gets Pooled

The LDAP provider will use a pooled connection only if the application has requested it and the request for the connection meets the pooling criteria. The application requests that a connection be pooled by using the com.sun.jndi.ldap.connect.pool environment property. The default pooling criteria is that plain (non-SSL) connections that use simple or no authentication are allowed to be pooled. The pooling criteria can be adjusted to include SSL connections and the DIGEST-MD5 authentication type by using System properties. A connection that has enabled protocol tracing (via the com.sun.jndi.ldap.trace.ber environment property) cannot be pooled. For pooling connections from a custom socket factory see Pooling Custom Socket Factory Connections

To allow SSL connections to be pooled, include the string "ssl" in the com.sun.jndi.ldap.connect.pool.protocol System property. For example, to allow both plain and SSL connections to be pooled, set this System property to the string "plain ssl".

To allow DIGEST-MD5 connections to be pooled, include the string "DIGEST-MD5" in the com.sun.jndi.ldap.connect.pool.authentication System property. For example, to allow connections of anonymous, simple and DIGEST-MD5 authentication types to be pooled, set this System property to the string "none simple DIGEST-MD5".

15.3.2 How Connections are Pooled

The LDAP provider maintains pooled connections so that they can be reused. When an application requests to use a pooled connection, the LDAP provider needs to determine whether the request can be satisfied by an existing pooled connection. It does this by assigning a connection identity to each pooled connection and checking whether the incoming request has the same connection identity as that of one of its pooled connections.

A connection identity is the set of the parameters required to create a possibly authenticated LDAP connection. Its composition depends on the authentication type of the request, as shown in the following table.

Authentication type Connection identity contents
none
  • connection controls
  • hostname, port number and scheme as specified in the java.naming.provider.url property, referral, or URL supplied to the initial context
  • the contents of the following properties:
    java.naming.security.protocol
java.naming.ldap.version
simple
  • all of the information listed for anonymous
  • the contents of following properties:
    java.naming.security.principal
java.naming.security.credentials
DIGEST-MD5
  • all of the information listed for simple
  • the contents of following properties:
    java.naming.security.sasl.authorizationId
java.naming.security.sasl.realm
javax.security.sasl.qop
javax.security.sasl.strength
javax.security.sasl.server.authentication
javax.security.sasl.maxbuffer
javax.security.sasl.policy.noplaintext
javax.security.sasl.policy.noactive
javax.security.sasl.policy.nodictionary
javax.security.sasl.policy.noanonymous
javax.security.sasl.policy.forward
javax.security.sasl.policy.credentials

15.3.3 Pooling Custom Socket Factory Connections

Pooling of connections from a custom socket factory is allowed when java.naming.ldap.factory.socket environment property is set. For the custom socket factory to be pooled the socket factory class must implement the Comparator interface. The LDAP Service Provider calls Comparator.compare() method for equality comparison of the socket factories whose connections are being checked for equality by the pooling mechanism. The socket factory comparison should ensure that the socket factory parameters that influence the connection equality are being compared. This comparison is made in addition to the connection identity comparison described in How Connections are Pooled. A custom socket factory class should have the following structure if its connections were to be pooled:

    public class CustomSocketFactory extends SocketFactory
                implements Comparator<SocketFactory> {
       :
       :
       public int compare(SocketFactory sf1, SocketFactory sf2) {
       :
       :
       // do whatever comparison that's required
       }
    }

If the socket factory class does not implement Comparator interface, the connections from that socket factory class do not get pooled. This requirement for implementing the Comparator interface is to ensure that the LDAP Service Provider does the necessary checks when comparing connections from different socket factories whose implementation is not known to the provider.

15.3.4 Pool Sizes

The LDAP provider maintains pools of connections; each pool holds connections (either in-use or idle) that have the same connection identity. There are three sizes that affect the management of each pool. These sizes are global and affect all pools.

The initial pool size is the number of connections per connection identity that the LDAP service provider creates when first creating the pool (which corresponds to when the application first requests a pooled connection for that connection identity). Authentication of each connection in the pool is performed on demand, as the connection gets used. By default, the initial pool size is 1 and can be changed by using the System property com.sun.jndi.ldap.connect.pool.initsize. It is typically used at application start-up time to prime the pool with a certain number of connections to a server.

The maximum pool size is the maximum number of connections per connection identity that can be maintained concurrently by the LDAP service provider. Both in-use and idle connections contribute to this number. When the pool size reaches this number, no new connection for the corresponding connection identity may be created until a connection in the pool has been removed (i.e., the physical connection is closed). When the pool size reaches the maximum and all of the connections in the pool are in use, the application's request for a connection from that pool is blocked until a connection in the pool either becomes idle or is removed. A maximum pool size of 0 means that there is no maximum size: A request for a pooled connection will use an existing pooled idle connection or a newly created pooled connection.

The preferred pool size is the preferred number of connections per connection identity that the LDAP service provider should maintain. Both in-use and idle connections contribute to this number. When an application requests the use of a pooled connection and the pool size is less than the preferred size, the LDAP provider will create and use a new pooled connection regardless of whether an idle connection is availble. When an application is finished with a pooled connection (by invoking Context.close() on all contexts that share the connection) and the pool size is greater than the preferred size, the LDAP provider will close and remove the pooled connection from the pool. A preferred pool size of 0 means that there is no preferred size: A request for a pooled connection will result in a newly created connection only if no idle ones are available.

Note that the maximum pool size overrides both the initial and preferred pool sizes. For example, setting the preferred pool size greater than the maximum pool size is effectively setting it to the maximum pool size.

15.3.5 Idle Connections

When the application is finished with a pooled connection (by invoking Context.close() on all contexts that share the connection), the underlying pooled connection is marked as idle, waiting to be reused. By default, idle connections remain in the pool indefinitely until they are garbage-collected. If the "com.sun.jndi.ldap.connect.pool.timeout" System property has been set, the LDAP provider will automatically close and remove pooled connections that have been idle for more than the specified period.

15.4 Per-Context Configuration

15.4.1 Enabling Pooling

To use pooling, set the com.sun.jndi.ldap.connect.pool property to "true" in the environment properties passed to the initial context constructor. The provider will apply the pooling criteria to the supplied environment properties and decide whether to use pooling for that context. If the provider determines that a connection cannot be pooled, it creates and uses an unpooled connection for the context.

If this property is omitted, the context will not use connection pooling.

15.4.2 Connection Timeout

The com.sun.jndi.ldap.connect.timeout environment property is used to specify a timeout period for establishment of the LDAP connection. This property affects the TCP timeout when opening a connection to an LDAP server. When connection pooling has been requested, this property also specifies the maximum wait time for a connection when all connections in pool are in use and the maximum pool size has been reached.

If this property has not been specified, the LDAP provider will wait indefinitely for a pooled connection to become available, and to wait for the default TCP timeout to take effect when creating a new connection.

Note that this property is different from the System property com.sun.jndi.ldap.connect.pool.timeout, which is related to the removal of idle pooled connections.

16. Security Considerations

 When a security manager has been installed, you must grant to the application using JNDI and the LDAP service provider the following permissions:

permission java.net.SocketPermission "host[:port]", "connect";
For each host/port identified in the java.naming.factory.initial property and in URL string names supplied to context methods.
permission java.net.SocketPermission "host[:port]", "connect,accept";
For each host/port named in the URL strings in References and javaCodebase attributes stored with Serializable objects.
If you are using SASL authentication and will be setting the SASL client factory programmatically, grant your application the following permission.
permission java.lang.RuntimePermission "setFactory"
If you use the "GSSAPI" SASL mechanism, you need the following additional permissions.
permission javax.security.auth.AuthPermission "createLoginContext.appClassName";
permission javax.security.auth.AuthPermission "doAsPrivileged";
For the application class that's going to be logging in and invoking the doAsPrivileged method.
permission java.net.SocketPermission "host[:port]", "connect";
For the host/port of the Kerberos Key Distribution Center (KDC).
permission javax.security.auth.kerberos.ServicePermission "krbtgt/realm@realm", "initiate";
permission javax.security.auth.kerberos.ServicePermission "ldap/fully-qualified-hostname@realm", "initiate";
For the realm and host of the LDAP service and KDC.

Copyright © 2002 Sun Microsystems, Inc. All rights reserved.


JNDI/RMI Registry Service Provider

RMI Registry Service Provider for the
Java Naming and Directory InterfaceTM (JNDI)

Please send feedback to jndi@java.sun.com

Table of Contents

  • Introduction
  • Environment Properties
  • Names
  • RMI URLs
  • RMI URL Format
  • API Mapping
  • Bindings
  • Usage Examples
  • Security Considerations

Introduction

The RMI registry service provider allows JNDI applications to access remote objects registered with the RMI registry. Given the location of a registry, the provider will create a naming context with bindings for the objects registered there. Such a context may be bound into another JNDI-accessible namespace (such as LDAP, for example). References to individual remote objects may likewise be bound into another namespace.

A key benefit of binding registry contexts into other namespaces is location-independent access to remote objects: the RMI clients do not need to know the registry's host name or port number. RMI servers can take advantage of this to advertise their services to potential clients. In addition, remote objects can be linked into the same enterprise directory that is used to access information about people, organizations, and network resources.

With this service provider installed, JNDI subsumes the functionality of the java.rmi.Naming class.

This document describes the features of the RMI registry service provider.

Environment Properties

The following JNDI environment properties are used by the RMI registry service provider. See the JNDI documentation for a description of how properties are initialized using the environment properties, system properties, applet parameters, and resource files.

java.naming.factory.initial
This property is used to select the registry service provider as the initial context. It is not used by the provider itself. It specifies the class name of the initial context factory for the provider.

For example:

env.put(Context.INITIAL_CONTEXT_FACTORY,
    "com.sun.jndi.rmi.registry.RegistryContextFactory");

This property is used in conjunction with the java.naming.provider.url property. This property must be set if you are using the registry as the initial context. The only exception is if you supply only URLs to the initial context, in which case, you don't need to specify this property. See RMI URLs for details.

java.naming.provider.url
This property specifies the location of the registry when the registry is being used as the initial context. It's value is an RMI URL with no object name component (see RMI URL Format below).

For example:

env.put(Context.PROVIDER_URL, "rmi://server:1099");

The default value of this property is "rmi:", signifying a registry running on port 1099 of the local host.

This property is used in conjunction with the java.naming.factory.initial property.

java.naming.factory.state
A colon-separated list of the fully qualified class names of state factory classes used to get an object's state for storing given the object itself. You can use this mechanism to transform an object into forms that can be stored into the registry. The RMI registry service provider supports storing java.rmi.Remote, javax.naming.Reference, and javax.naming.Referenceable objects. See javax.naming.spi.NamingManager.getStateToBind() for details.
java.naming.factory.object
A colon-separated list of the fully qualified class names of object factory classes for transforming objects read from the registry. You can use this mechanism to transform an object into forms expected by the application. See javax.naming.spi.NamingManager.getObjectInstance() for details.
com.sun.jndi.rmi.factory.socket
This property specifies the socket factory for use by the RMI runtime in order to obtain the client sockets to make RMI calls. The value specified for the socket factory must be of the type java.rmi.server.RMIClientSocketFactory. If this property is not set, the default socket factory is used by the registry.
java.naming.rmi.security.manager
This property, when set to any value, indicates that the provider should attempt to install the RMISecurityManager. See the Security Considerations section below.

Names

The RMI registry supports a flat namespace. Since there is no hierarchy, every name is atomic. Each name may be composed of any characters, and case is significant.

Names are passed as arguments to the methods of a registry context, and are returned as the results of those methods, either as Name objects or as strings. When a Name object is used, it should have a single component whose value is the atomic name that will be passed on to the registry. When a string is used as a name, it is interpreted as the string representation of a composite name. So if ctx is a registry context, for example, then the following two unbind operations are equivalent:

String name = ...
ctx.unbind(name);
ctx.unbind(new CompositeName(name));
Care must be taken with names containing any of the four meta-characters that are treated specially during the parsing of composite names: '/', '\\', '"', and '\''. These characters must be properly escaped or quoted. The atomic name X/Y, for example, may be represented as the composite name X\/Y so as not to be mistaken for a two-component name with X and Y as its components. See CompositeName for more information.

RMI URLs

JNDI provides support for resolving URLs that name objects. The registry service provider allows RMI URLs to be used as names in this manner. This provides a generalization of the java.rmi.Naming functionality, only using the more general JNDI interface.

The class com.sun.jndi.url.rmi.rmiURLContextFactory implements a URL context factory for RMI URLs. This allows an RMI URL to be passed as a name to the default JNDI initial context.

RMI URL Format

The format of an RMI URL is one of the following:

   rmi://[host][:port][/[object]]

   rmi:[/][object]
If the object name is absent, then the URL names the registry at the given host and port. Otherwise, it names the remote object registered at that registry under the name provided.

If the host is omitted, the local host is assumed. If the port is omitted, the default registry port 1099 is assumed.

API Mapping

The registry service provider implements the java.naming.Context and java.naming.Referenceable interfaces. Context and Referenceable methods are mapped onto registry operations as described below.

lookup()
lookupLink()
The java.rmi.Registry.lookup() method is called. If the returned object is a wrapper around a javax.naming.Reference, the referenced object is created using javax.naming.spi.NamingManager.getObjectInstance(). JNDI links are not currently supported.
bind()
The java.rmi.Registry.bind() method is called. State factories are first consulted through javax.naming.spi.NamingManager.getStateToBind(). The object being bound must be of type java.rmi.Remote, javax.naming.Reference, or javax.naming.Referenceable. If the object is a javax.naming.Reference or javax.naming.Referenceable, its reference is wrapped in a Remote wrapper and then bound (see Binding Objects into the Registry below).
rebind()
The java.rmi.Registry.rebind() method is called. Objects are otherwise treated as for the JNDI bind() operation.
unbind()
The java.rmi.Registry.unbind() method is called.
rename()
This method is implemented as a sequence of JNDI operations: lookup(), bind(), unbind(). The sequence is not performed atomically.
list()
The java.rmi.Registry.list() method is called. As this provides no information about the types of the bound objects, each javax.naming.NameClassPair returned has the generic java.lang.Object as its class name.
listBindings()
The java.rmi.Registry.list() method is called. As each javax.naming.Binding is read from the resulting enumeration, java.rmi.Registry.lookup() is called and passed through javax.naming.spi.NamingManager.getObjectInstance().
createSubcontext()
destroySubcontext()
These operations are not supported.
getNameParser()
Returns a name parser for case-sensitive atomic names.
getNameInNamespace()
Returns the empty string (the name of the registry).
composeName()
Returns the composition of the two names.
addToEnvironment()
The specified property is added to the context's environment. If the java.naming.rmi.security.manager property is added, the provider will attempt to install the default RMI security manager (see Security Considerations). Other properties may be added or changed in the environment, but have no additional effect on the context.
removeFromEnvironment()
The specified property is removed from the context's environment. The context is otherwise unaffected.
close()
Clears internal state used by the provider, but otherwise has no immediate effect.
getReference()
If this context was constructed from a reference, a clone of that reference is returned. Otherwise a new reference for the context is returned, providing that the host name can be determined and is not "localhost" (see Binding Registry Contexts and Remote Objects below).

Bindings

Binding Objects into the Registry

An object may be bound into a registry context if it implements the java.rmi.Remote interface. An object may also be bound if it is a JNDI Reference object, or if it implements the Referenceable interface (in which case the corresponding reference will be bound in place of the object itself).

Binding Registry Contexts and Remote Objects

Each RMI registry context implements the Referenceable interface. It may therefore be bound into any JNDI-accessible namespace that can store Referenceable objects. A reference to an individual remote object that is registered with a registry may also be constructed, allowing that object to be bound into another namespace.

The class com.sun.jndi.rmi.registry.RegistryContextFactory implements the object factory that converts registry references into the corresponding registry contexts or remote objects.

For a registry context to be constructed, the registry's URL must be determined. This URL may come from the java.naming.provider.url property, or may be passed as a name to the initial context, or may be embedded in a registry reference. If the URL contains no host name or uses the host name "localhost", then the registry context's getReference() method is unable to return a reference for the context. Such a registry context, therefore, cannot be bound into another namespace.

Registry Reference Format

A JNDI reference for an RMI registry contains a list of string addresses (class StringRefAddr), each tagged with the type "URL". Each address contains an RMI URL locating either a registry, or a remote object registered with a registry (see RMI URL Format above).

When multiple URLs appear within a single reference, each represents an alternative address for the same logical resource. The order of the addresses is not significant. Addresses not of class StringRefAddr, or not of address type "URL", are ignored.

Usage Examples

Example 1

To create an initial context that accesses a registry, set the properties java.naming.factory.initial and java.naming.provider.url as described in Environment Properties above. Then the names stored in the registry, for example, may be listed as follows:

Context ictx = new InitialContext(env);
NamingEnumeration enum = ictx.list("");

Example 2

Instead of using the properties as above, you may pass an RMI URL as a name to resolve in the default initial context:

Context registryCtx = (Context)ictx.lookup("rmi://host");

Example 3

A registry context may be bound into another JNDI-accessible namespace. To bind registryCtx (from the preceding example) into an LDAP directory, for example:

Context ldapCtx = (Context)ictx.lookup("ldap://server/o=sun,c=us");
ldapCtx.bind("cn=rmi", registryCtx);
If the names R1 and R2 are bound in this registry, then a JNDI client browsing the LDAP namespace will see R1 and R2 beneath the cn=rmi entry.

Example 4

A remote object that is registered with an RMI registry may be bound into another JNDI-accessible namespace by constructing a reference for that object. If the variable obj holds the object named R1 from the preceding examples, it may be bound into an LDAP directory as follows:

RefAddr addr = new StringRefAddr("URL", "rmi://host/R1");
Reference ref = new Reference(obj.getClass().getName(), addr);
ldapCtx.bind("cn=R1", ref);

Security Considerations

Security Manager

The usual security considerations of RMI apply. For RMI to dynamically load classes from a remote server, a security manager must first be installed. This can be done in the same way as it would for any other RMI application. See the JavaTM Remote Method Invocation Specification. Or, if the environment property java.naming.rmi.security.manager is passed to the provider, then the provider will attempt to install the RMISecurityManager itself.

Permissions

The application using JNDI and the RMI registry provider must be granted the following permissions:

permission java.net.SocketPermission "host[:port]", "connect";
For each host/port identified in the java.naming.provider.url property and in URL string names supplied to context methods.

permission java.net.SocketPermission "host[:port]", "connect,accept";
For each host/port identified in the URL strings in javax.naming.References.

permission java.lang.RuntimePermission "setSecurityManager";
If using the java.naming.rmi.security.manager environment property, which asks the RMI registry provider to install the RMISecurityManager.

Copyright © 1999-2001 Sun Microsystems, Inc., All Rights Reserved.


Outline of the JNDI API

Java

Outline of the Java Naming and Directory Interface TM (JNDI)
The JNDI consists of these packages:
  • javax.naming
      Contains classes and interfaces for accessing naming services.

  • javax.naming.directory
      Extends the core javax.naming package to provide functionality for accessing directories in addition to naming services.

  • javax.naming.event
      Contains classes and interfaces for supporting event notification in naming and directory services.

  • javax.naming.ldap
      Contains classes and interfaces for supporting LDAPv3 extended operations and controls.

  • javax.naming.spi
      Contains the classes and interfaces that allow various naming and directory service providers to be dynamically plugged in beneath the JNDI.

Copyright © 1995-2001 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: jndi@java.sun.com 		Sun
Java Software


Java Naming and Directory Interface

The Java Naming and Directory InterfaceTM technology (JNDI) provides a unified interface to multiple naming and directory services. As part of the Java enterprise API set, JNDI enables seamless connectivity to heterogeneous enterprise naming and directory services. Developers can now build powerful and portable directory-enabled Java applications using this industry-standard interface.

The JNDI specification was developed by Sun Microsystems with a number of leading industry partners, including Novell, Netscape, SCO, and BEA.

Duke icon The 1.2 version of the specification and reference implementation are now available for download at the Java Software Web site.

Technical Overview

Directory services play a vital role in Intranets and Internets by providing access to a variety of information about users, machines, networks, services, and applications. By its very nature, a directory service incorporates a naming facility for providi ng human understandable namespaces that characterize the arrangement and identification of the various entities.

The computing environment of an enterprise typically consists of several naming facilities often representing different parts of a composite namespace. For example, the Internet Domain Name System (DNS) may be used as the top-level naming facilit y for different organizations within an enterprise. The organizations themselves may use a directory service such as LDAP or NDS or NIS. From a user's perspective, there is one namespace consisting of composite names. URLs are examples of composite names because they span namespaces of multiple naming facilities. Applications which use directory services must support this user perspective.

Many Java application developers can benefit from a directory service API that is not only independent of the particular directory or naming service implementation, but also enables seamless access to directory objects through multiple naming facilities. In fact, an application can attach its own objects to the namespace. Such a facility enables any Java application to discover and retrieve objects of any type.

JNDI provides directory and naming functionality to Java applications. It is defined to be independent of any specific directory service implementation. Thus, a variety of directories, new and existing ones in the installed base, can be a ccessed in a common way.

JNDI also defines a service provider's interface which allows various directory and naming service drivers to be plugged in.

Examples

Here are two examples to briefly illustrate some of the more commonly used features of JNDI.

An application that wants to access a printer needs the corresponding printer object. This is simply done as follows:

prt = (Printer)
    building7.lookup("puffin");
prt.print(document);

where building7 is the naming context representing a physical building that provides a convenient context for referring to the printers.

JNDI does all the work of locating the information needed to construct the printer object.

As another example, an application that wants to find a person's phone numbers, which are stored in the organization's directory, can simply do:

String[] attrs = {"workPhone", "cellPhone", "faxNumber"};
bobsPhones = directory.getAttributes("cn=Bob,o=Widget,c=US", attrs);

If there may be several Bobs in the Widget organization, the application can search the organization's directory to find the right Bob as follows:

bob = directory.search("o=Widget,c=US","(cn=Bob)", controls);

Other application examples include access to security credentials stored in an enterprise-wide directory service, access to electronic mail addresses, and access to addresses of a variety of existing services such as databases, network file systems, etc.

Overview of Interfaces

The Naming Interface - javax.naming

Context is the core interface that specifies a naming context. It defines basic operations such as adding a name-to-object binding, looking up the object bound to a specified name, listing the bindings, removing a name-to-object binding, crea ting and destroying subcontexts of the same type, etc.

Context.lookup() is the most commonly used operation. The context implementation can return an object of whatever class is required by the Java application. For example, an application might use the name of a printer to look up the correspond ing Printer object, and then print to it directly:

Printer printer = (Printer)
 ctx.lookup("treekiller");
printer.print(report);

The application is not exposed to any naming service implementation. In fact, a new type of naming service can be introduced without requiring the application to be modified or even disrupted if it is running.

The Directory Interface - javax.naming.directory

Directory Objects and Attributes. The DirContext interface enables the directory capability by defining methods for examining and updating attributes associated with a directory object. Each directory object contains a set of zero or more objects of class Attribute. Each attribute is denoted by a string identifier and can have zero or more values of any type.

Directory Objects as Naming Context. The DirContext interface also behaves as a naming context by extending the Context interface. This means that any directory object can also provide a naming context. In addition to a directory object keeping a variety of information about a person, for example, it is also a natural naming context for resources associated with that person: a person's printers, file system, calendar, etc.

Searches. The DirContext interface supports content-based searching of directories. In the simplest and most common form of usage, the application specifies a set of attributes - possibly with specific values - to match. It then invo kes the DirContext.search() method on the directory object, which returns the matching directory objects along with the requested attributes.

The Event Interface - javax.naming.event

Naming Events. The NamingEvent class represents an event generated by a naming or directory service. Examples of a NamingEvent are a change to a directory entry's attribute or a rename of a directory entry.

Naming Listeners. A NamingListener is an object that registers interests in NamingEvents. Listeners register with a context to receive notification of changes in the context, its children, or its subtree.

The LDAP Interface - javax.naming.ldap

The LdapContext interface allows an application to use LDAP v3-specific features, including extensions and controls, not already covered by the more generic DirContext interface.

The Service Provider Interface - javax.naming.spi

The JNDI SPI provides the means by which different naming/directory service providers can develop and hook up their implementations so that the corresponding services are accessible from applications that use JNDI. In add ition, because JNDI allows specification of names that span multiple namespaces, if one service provider implementation needs to interact with another in order to complete an operation, the SPI provides methods that allow different provid er implementations to cooperate to complete client JNDI operations.

http://java.sun.com/jndi

Copyright © 1999, Sun Microsystems, Inc. All rights reserved.


1 Introduction

CONTENTS | PREV | NEXT JNDI API

1. Introduction

Directory services play a vital role in Intranets and Internets by providing access to a variety of information about users, machines, networks, services, and applications. By its very nature, a directory service incorporates a naming facility for providing human understandable namespaces that characterize the arrangement and identification of the various entities.

The computing environment of an enterprise typically consists of several naming facilities often representing different parts of a composite namespace. For example, the Internet Domain Name System (DNS) might be used as the top-level naming facility for different organizations within an enterprise. The organizations themselves might use a directory service such as LDAP or NDS or NIS. From a user's perspective, there is one namespace consisting of composite names. URLs are examples of composite names because they span namespaces of multiple naming facilities. Applications which use directory services must support this user perspective.

Many JavaTM application developers can benefit from a directory service API that is not only independent of the particular directory or naming service implementation, but also enables seamless access to directory objects through multiple naming facilities. In fact, any application can attach its own objects to the namespace. Such a facility enables any Java application to discover and retrieve objects of any type.

End users can benefit from logical namespaces that allow easier discovery and identification of the objects in the network.

Directory service developers can benefit from a service-provider capability that enables them to incorporate their respective implementations without requiring changes to the client.

Java Naming and Directory InterfaceTM (JNDI) is an API that provides directory and naming functionality to Java applications. It is defined to be independent of any specific directory service implementation. Thus, a variety of directories can be accessed in a common way.

Here are two examples to briefly illustrate some of the more commonly used features of JNDI.

An application that wants to access a printer needs the corresponding printer object. This is simply done as follows:

prt = (Printer) building7.lookup("puffin");
prt.print(document);

JNDI does all the work of locating the information needed to construct the printer object.

An application that wants to find a person's phone numbers, which are stored in the organization's directory, can simply do:

String[] attrs = {"workPhone", "cellPhone", "faxNumber"};
bobsPhones = directory.getAttributes("cn=Bob, o=Widget, c=US", attrs);

If there may be several Bobs in the Widget organization, the application can search the organization's directory to find the right Bob as follows:

bob = directory.search("o=Widget, c=US", "(cn=Bob)", searchctls);

This document describes the architecture and interfaces of JNDI.

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


1 Introduction

2 Goals and Design Principles

3 Overview of the Architecture

4 Fundamentals

5 Overview of the Interface

6 Configuration

7 Scenarios

8 Security Considerations

9 Design Choices


2 Goals and Design Principles

CONTENTS | PREV | NEXT JNDI API

2. Goals and Design Principles

We followed several principles and maxims in designing the API.

2.1 Keep it consistent and intuitive

Wherever possible, we have used existing components from the rest of the Java development environment. Adhering to this principle not only makes JNDI consistent with existing core classes in the Java platform but also reduces needless proliferation of classes.

The object-oriented nature of the Java programming language allows for an intuitive and simple API design, in which the directory service functionality is expressed as a natural extension to the more fundamental naming service functionality.

2.2 Pay for what you use

The API is structured in a tiered manner so that the application programmer interested in a certain directory service capability need not necessarily know about a more advanced capability. We have strived to keep the lower tiers simple and also make them represent the common case capability, relegating the more complex ones to the upper tiers.

2.3 Implementable over common directory and naming services and protocols

This goal is important for two reasons. First, it enables Java applications to take advantage of information in a variety of existing naming and directory services such as DNS, NDS, NIS (YP), X.500, and LDAP. Second, it helps limit the appearance of any implementation specific artifacts in the API.

Providing a unified interface to multiple naming and directory services does not imply that access of unique features of a particular service is precluded. The unified API which is designed to cover the common case is still beneficial to applications that have explicit knowledge of the underlying naming or directory service. Such applications still benefit from sharing the common portions that use the API. This is analogous to applications sharing commonly used classes and yet adding needed specificity via subclassing.

2.4 Seamless integration

This is important not only because of the diversity of directory service and naming services in the installed base that need to be supported, but also because new Java application and service programmers can export their own namespaces and directory objects in a uniform way.

We also wanted to make a variety of implementation choices possible without having the application pay for this freedom. For example, a "thin-client" might be better served by a proxy-style protocol in which the access to specific naming and directory services is relegated to a server. Whereas, a performance sensitive, resource rich client, might choose to use an implementation which directly allows it to access the various servers. However, the application should be insulated from these implementation choices. It should be possible to defer such choices even until runtime.

2.5 Support for leading industry standards

The Lightweight Directory Access Protocol (Internet RFC 2251) has emerged as the standard for directory access at the protocol level. All major directory vendors have products that support this protocol. An application that uses JNDI should be able to access all of the features offered by this standard. Where possible, JNDI should support conventions (such as those for specifying search queries/filters) already defined by the standard.

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


3 Overview of the Architecture

CONTENTS | PREV | NEXT JNDI API

3. Overview of the Architecture

The JNDI architecture consists of the JNDI API and the JNDI SPI. The JNDI API allows Java applications to access a variety of naming and directory services. The JNDI SPI is designed to be used by arbitrary service providers including directory service providers. This enables a variety of directory and naming services to be plugged in transparently to the Java application (which uses only the JNDI API). The JNDI Architecture figure shows the JNDI architecture and includes a few service providers of directory and naming contexts as examples.

JNDI Architecture

Graphic with the following from top to bottom: Java application, JNDI API, JNDI Naming Manager, JNDI SPI, and RMI, CORBA, LDAP and NDS on the bottom row.

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


4 Fundamentals

CONTENTS | PREV | NEXT JNDI API

4. Fundamentals

A directory service provides access to diverse kinds of information about users and resources in a network environment. It uses a naming system for the purpose of identifying and organizing directory objects to represent this information. A directory object provides an association between attributes and values. Thus, a directory service enables information to be organized in a hierarchical manner to provide a mapping between human understandable names and directory objects.

4.1 Naming -- The Foundation

A fundamental facility in any computing system is the naming service - the means by which names are associated with objects, and by which objects are found given their names. In traditional systems, the naming service is seldom a separate service. It is usually integrated with another service, such as a file system, directory service, database, desktop, mail system, spreadsheet, or calendar. For example, a file system includes a naming service for files and directories; a spreadsheet has a naming service for cells and macros.

The computing environment of an enterprise typically consists of several naming services. There are naming services that provide contexts for naming common entities in an enterprise such as organizations, physical sites, human users and computers. Naming services are also incorporated in applications offering services such as file service, mail service, printer service, and so on. From a user's perspective, there exist several natural and logical relationships between these naming services. For example, it is natural to think of naming a variety of services such as files, mail, appointment calendar, and so on, in the context of a user. It is also natural to think of a user in the context of a department, within a division of an enterprise. Meaningful names can be composed using useful arrangements of naming services reflecting these relationships.

Every name is generated by a set of syntactic rules called a naming convention. An atomic name is an indivisible component of a name, as defined by the naming convention.

A compound name represents a sequence of zero or more atomic names composed according to the naming convention.

For example, in UNIX pathnames, atomic names are ordered from left to right, and are delimited by slash (`/') characters. The UNIX pathname usr/local/bin is a compound name representing the sequence of atomic names, usr , local , and bin . In names from the Internet Domain Name System (DNS), atomic names are ordered from right to left, and are delimited by dot (`.') characters. Thus, the DNS name sales.Wiz.COM is a compound name representing the sequence of atomic names, COM , Wiz , sales .

The association of an atomic name with an object is called a binding.

A context is an object whose state is a set of bindings with distinct atomic names. Every context has an associated naming convention. A context provides a lookup (resolution) operation that returns an object, and may provide operations such as for binding names, unbinding names, listing bound names. An atomic name in one context object can be bound to another context object of the same type, called a subcontext, giving rise to compound names.

Resolution of compound names proceeds by looking up each successive atomic component in each successive context. The reader will find a familiar model in UNIX file naming, where directories serve as contexts, and pathnames may be compound names.

A naming system is a connected set of contexts of the same type (having the same naming convention) and providing the same set of operations with identical semantics.

A namespace is the set of all names in a naming system.

A composite name is a name that spans multiple naming systems. It consists of an ordered list of zero or more components. Each component is a name from the namespace of a single naming system.

For example, the name jurassic.eng:/export/home/jdoe/.signature is a composite name representation made up of a host name jurassic.eng from a host namespace, and the file name /export/home/jdoe/.signature from a UNIX file namespace. Another example is the Internet URL http://www.moon.org/public/index.html , which is a composite name representation made up of the scheme-id http from the "URL scheme-id" namespace, www.moon.org which is the DNS name of the machine on which the web server is running, and public/index.html which is a file name from a file namespace.

Every name is interpreted relative to some context, and every naming operation is performed on a context object. A client can obtain an initial context object that provides a starting point for resolution of names.

4.2 Directory Objects

The primary function of a naming system is to map names to objects. The objects can be of any type. A directory object is a particular type of object that is used to represent the variety of information in a computing environment. A directory object can have associated with it attributes. An attribute has an identifier and a set of values.

A directory object provides operations for creating attributes, adding, removing, and modifying attributes associated with the directory object. If we make a directory object also be a naming context, we can represent trees of directory information where the interior nodes not only behave like naming contexts but also contain attributes.

The Example of a Composite Namespace figure is an example used for illustrating several things.

Example of a Composite Namespace

The following context describes this graphic

    • There can be multiple naming systems that can be represented by a composite namespace. In this case, DNS is used as the global naming system; one division uses NDS, while a second division uses LDAP.
    • Each namespace has interior nodes that represent naming contexts, which may be directory objects as well. Leaf nodes can be objects of any type.
    • The InitialContext is configured to have bindings to useful starting contexts in different naming and directory systems.
    • Applications just see a composite namespace. They can access any type of object bound in any naming system in this arrangement.
    • Services can incorporate their own namespaces which appear as first-class citizens in JNDI.
    • Arbitrary directory services can be added and accessed without requiring client applications to be changed.

4.3 URLs and Composite Names

Uniform Resource Locators (URLs) are special composite names whose syntax are determined by the URL's definition. Clients of JNDI can use URLs to refer to arbitrary types of objects. For example, a client can use nfs://nfs.sun.com/export/jndi/src/README to refer to a file object that is being accessed using the Network File System (NFS) protocol. Similarly, a client can perform directory operations on a directory object in an LDAP server using the URL ldap://ldap.widget.com/cn=Jonathan,ou=marketing .

To support composite names in general, JNDI defines a composite name syntax and utilities for processing composite names. This allows clients of JNDI to refer to objects using names that span multiple namespaces.

4.4 Events

As the naming/directory service plays an increasingly important role in the computing environment, the need to provide administration and monitoring tools to help manage changes in the service also increases. For such tools and other applications, the traditional request/response style of interaction needs to be augmented with an asynchronous notification model that allows applications to register interest in changes in the service.

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


5 Overview of the Interface

CONTENTS | PREV | NEXT JNDI API

5. Overview of the Interface

The JNDI API is contained in four packages:

    • javax.naming contains classes and interfaces for accessing naming services
    • javax.naming.directory extends the core javax.naming package to provide access to directories
    • javax.naming.event contains classes and interfaces for supporting event notification in naming and directory services
    • javax.naming.ldap contains classes and interfaces for supporting LDAP v3 extensions and controls

The JNDI service provider interface is contained one package:

    • javax.naming.spi contains classes and interfaces that allow various naming and directory service providers to be dynamically plugged in beneath the JNDI API (see the JNDI SPI document for details)

The following sections provide an overview of the JNDI API. For more details on the API, see the corresponding javadoc.

5.1 The Naming Package -- javax.naming 1

The javax.naming package. The information in this graphic is available in the <a href= API documentation." WIDTH="591" HEIGHT="405" ALIGN="BOTTOM" BORDER="0" NATURALSIZEFLAG="3">

(exception classes are not shown)

5.1.1 Contexts

Context is the core interface that specifies a naming context. It defines basic operations such as adding a name-to-object binding, looking up the object bound to a specified name, listing the bindings, removing a name-to-object binding, creating and destroying subcontexts of the same type, etc.

public interface Context {
    public Object lookup(Name name) throws NamingException;
    public void bind(Name name, Object obj) throws NamingException;
    public void rebind(Name name, Object obj) throws NamingException;
    public void unbind(Name name) throws NamingException;
    public void rename(Name old, Name new) throws NamingException;
    public NamingEnumeration listBindings(Name name) throws NamingException;
    ...
    public Context createSubcontext(Name name) throws NamingException;
    public void destroySubcontext(Name name) throws NamingException;
    ...
};

Every naming method in Context takes a name as an argument. The operation defined by the method is performed on the Context object that is obtained by implicitly resolving the name. If the name is empty ("") the operation is performed directly on the context itself. The name of an object can be a composite name reflecting the arrangement of the namespaces used to refer to the object. Of course, the client is not exposed to any naming service implementation. In fact, a new type of naming service can be introduced without requiring the application to be modified or even disrupted if it is running.

5.1.2 The Initial Context

In JNDI, every name is relative to a context. There is no notion of "absolute names." An application can bootstrap by obtaining its first context of class InitialContext :

public class InitialContext implements Context {
    public InitialContext()...;
    ...
}

The initial context contains a variety of bindings that hook up the client to useful and shared contexts from one or more naming systems, such as the namespace of URLs or the root of DNS.

5.1.3 Names

The Name interface represents a generic name--an ordered sequence of components. Each Context method that takes a Name argument has a counterpart that takes the name as a String instead. The versions using Name are useful for applications that need to manipulate names: composing them, comparing components, and so on. The versions using String are likely to be more useful for simple applications, such as those that simply read in a name and look up the corresponding object. The String name parameter represents a composite name. The Name parameter can represent a composite name or a compound name .

The CompositeName class represents a sequence of names (atomic or compound) from multiple namespaces. If the Name parameter supplied to a method of the Context class is an instance of CompositeName , the name represents a composite name.

If the Name parameter supplied to a method of the Context class is not an instance of CompositeName , the name represents a compound name, which can be represented by the CompoundName class or some other implementation class. The CompoundName class represents hierarchical names from a single namespace. A context's name parser can be used to manipulate compound names in the syntax associated with that particular context:

public interface Context {
    ...
    public NameParser getNameParser(Name name) throws NamingException;
    ...
}

A namespace browser is an example of the kind of application that might need to manipulate names syntactically at this level. Most other applications will work with strings or composite names.

5.1.4 Bindings

Context.lookup() is the most commonly used operation. The context implementation can return an object of whatever class is required by the Java application. For example, a client might use the name of a printer to look up the corresponding Printer object, and then print to it directly:

Printer printer = (Printer) ctx.lookup("treekiller");
printer.print(report);

Context.listBindings() returns an enumeration of name-to-object bindings, each binding represented by an object of class Binding . A binding is a tuple containing the name of the bound object, the name of the object's class, and the object itself.

The Context.list() method is similar to listBindings() , except that it returns an enumeration of NameClassPair objects. Each NameClassPair contains an object's name and the name of the object's class. The list() method is useful for applications such as browsers that wish to discover information about the objects bound within a context, but don't need all of the actual objects. Although listBindings() provides all of the same information, it is potentially a much more expensive operation.

public class NameClassPair ... {
    public String getName() ...;
    public String getClassName() ...;
    ...
}
public class Binding extends NameClassPair {
    public Object getObject() ...;
    ...
}

5.1.5 References

Different Context implementations are able to bind different kinds of objects natively. A particularly useful object that should be supported by any general-purpose context implementation is the Reference class. A reference represents an object that exists outside of the directory. References are used to give JNDI clients the illusion that objects of arbitrary classes are able to be bound in naming or directory services--such as X.500--that do not have native support for objects in the Java programming language.

When the result of an operation such as Context.lookup() or Binding.getObject() is a Reference object, JNDI attempts to convert the reference into the object that it represents before returning it to the client. A particularly significant instance of this occurs when a reference representing a Context of one naming system is bound to a name in a different naming system. This is how multiple independent naming systems are joined together into the JNDI composite namespace. Details of how this mechanism operates are provided in the JNDI SPI document.

Objects that are able to be represented by a reference should implement the Referenceable interface. Its single method -- getReference() -- returns the object's reference. When such an object is bound to a name in any context, the context implementation might store the reference in the underlying system if the object itself cannot be stored natively.

Each reference may contain the name of the class of the object that it represents, and may also contain the location (typically a URL) where the class file for that object can be found. In addition, a reference contains a sequence of objects of class RefAddr . Each RefAddr in turn contains a "type" string and some addressing data, generally a string or a byte array.

A specialization of Reference called a LinkRef is used to add "symbolic" links into the JNDI namespace. It contains the name of a JNDI object. By default, these links are followed whenever JNDI names are resolved.

5.1.6 Referrals

Some naming/directory services support the notion of referrals for redirecting a client's request to another server. The JNDI client can request that referrals be automatically followed, be ignored, or be processed manually.

The abstract class ReferralException is used to represent a referral:

public abstract class ReferralException extends NamingException {
    public abstract Context getReferralContext() throws NamingException;
    ...
    public abstract Object getReferralInfo();
    public abstract void retryReferral();
    public abstract boolean skipReferral();
}

When a referral is encountered and the client has requested that referrals not be ignored or automatically followed, a ReferralException is thrown. The getReferralInfo() method provides information--in a format appropriate to the service provider--about where the referral leads. The application is not required to examine this information; however, it might choose to present it to a human user to help him determine whether to follow the referral or not. skipReferral() allows the application to discard a referral and continue to the next referral (if any).

To continue the operation, the application re-invokes the method on the referral context using the same arguments it supplied to the original method.

5.2 The Directory Package -- javax.naming.directory 2

The javax.naming.directory package. The information in this graphic is available in the <a href= API documentation." WIDTH="1002" HEIGHT="434" ALIGN="BOTTOM" BORDER="0" NATURALSIZEFLAG="3">

(exception classes are not shown)

5.2.1 Directory Objects

The DirContext interface enables the directory capability by defining methods for examining and updating attributes associated with a directory object.

public interface DirContext extends Context {
    public Attributes getAttributes(Name name)
         throws NamingException;
    public Attributes getAttributes(Name name, String[] attrIds)
         throws NamingException;
    ...
    public void modifyAttributes(Name name, int modOp, Attributes attrs)
         throws NamingException;
    public void modifyAttributes(Name name, ModificationItem[] mods)
         throws NamingException;
    ...
}

The getAttributes() operations on a directory return some or all of its attributes. Attributes are modified using two forms of modifyAttributes() . Both forms make use of a "modification operation," one of:

ADD_ATTRIBUTE
REPLACE_ATTRIBUTE
REMOVE_ATTRIBUTE

The ADD_ATTRIBUTE operation adds values to an attribute if that attribute already exists, while the REPLACE_ATTRIBUTE operation discards any pre-existing values. The first form of modifyAttributes() performs the specified operation on each element of a set of attributes. The second form takes an array of objects of class ModificationItem :

public class ModificationItem {
    public ModificationItem(int modOp, Attribute attr) ...;
    ...
}

Each operation is performed on its corresponding attribute in the order specified. When possible, a context implementation should perform each call to modifyAttributes() as an atomic operation.

5.2.2 Attributes

A directory object contains a set of zero or more Attribute objects. Each attribute is denoted by a string identifier and can have zero or more values of any type.

public interface Attribute ... {
    ...
    public String getID();
    public Object get(int n) throws NamingException;
    public boolean isOrdered();
    public NamingEnumeration getAll()
           throws NamingException;
    ...
}

An attribute's values can be ordered or unordered. If the values are unordered, no duplicates are allowed. If the values are ordered, duplicates are allowed.

Attributes are grouped into a collection by using the Attributes interface.

public interface Attributes ... {
    ...
    public Attribute get(String attrID);
    public NamingEnumeration getIDs();
    public NamingEnumeration getAll();
    public Attribute put(Attribute attr);
    public Attribute remove(String attrID);
    ...
}

JNDI provides implementations for these two interfaces, BasicAttribute and BasicAttributes , for convenience. Service providers and applications are free to use their own implementations.

Note that updates to Attributes and Attribute , such as adding or removing an attribute or its value, do not affect the corresponding representation in the directory. Updates to the directory can only be effected by using DirContext.modifyAttributes() .

5.2.3 Directory Objects as Naming Contexts

The DirContext interface also behaves as a naming context by extending the Context interface. This means that any directory object can also provide a naming context. In addition to a directory object keeping a variety of information about a person, for example, it is also a natural naming context for resources associated with that person: a person's printers, file system, calendar, etc.

Hybrid operations perform certain naming and directory operations in a single atomic operation:

public interface DirContext extends Context {
    ...
    public void bind(Name name, Object obj, Attributes attrs)
           throws NamingException;
    ...
}

Other hybrid operations that are provided are rebind() and createSubcontext() that accept an additional Attributes argument.

5.2.4 The Initial Context

An application that is performing directory operations can use InitialDirContext instead of javax.naming.InitialContext to create its initial context:

public class InitialDirContext
       extends InitialContext implements DirContext {
    public InitialDirContext() ...;
    ...
}

It can then invoke any method in the Context or DirContext interface on the initial context.

5.2.5 Searches

The DirContext interface supports content-based searching of directories. In the simplest and most common form of usage, the application specifies a set of attributes -- possibly with specific values -- to match. It then invokes the DirContext.search() method on the directory object, which returns the matching directory objects along with the requested attributes.

public interface DirContext extends Context {
    ...
    public NamingEnumeration search(Name name, Attributes matchingAttributes)
         throws NamingException;
    public NamingEnumeration search(Name name,
                                    Attributes matchingAttributes,
                                    String[] attributesToReturn)
         throws NamingException;
    ...
}

The results of the search are returned as a NamingEnumeration containing an enumeration of objects of class SearchResult :

public class SearchResult extends Binding {
    ...
    public Attributes getAttributes() ...;
}

In the more sophisticated case, it is possible to specify a search filter and to provide controlling information such as the scope of the search and the maximum size of the results. The search filter specifies a syntax that follows Internet RFC 2254 for LDAP. The SearchControls argument specifies such things as the scope of the search: this can include a single directory object, all of its children, or all of its descendants in the directory hierarchy.

public interface DirContext extends Context {
    ...
    public NamingEnumeration search(Name name,
                                    String filter,
                                    SearchControls ctls)
           throws NamingException;

    public NamingEnumeration search(Name name,
                                    String filter,
                                    Object[] filterArgs,
                                    SearchControls ctls)
         throws NamingException;
       ...
}

5.2.6 Schema

A schema describes the rules that define the structure of a namespace and the attributes stored within it. The granularity of the schema can range from a single schema that is associated with the entire namespace, to a per-attribute, fine-grained schema description.

Because schemas can be expressed as an information tree, it is natural to use for this purpose the naming and directory interfaces already defined in JNDI. This is powerful because the schema part of a namespace is accessible to applications in a uniform way. A browser, for example, can access information in the schema tree just as though it were accessing any other directory objects.

Applications can retrieve the schema associated with a directory object when the underlying context implementation provides the appropriate support.

DirContext.getSchema() is used to retrieve the root of the schema tree associated with a directory object. The root has children such as "ClassDefinition", "AttributeDefinition", and "SyntaxDefinition", each denoting the kind of definition being described. The schema root and its descendents are objects of type DirContext . The DirContext.getSchemaClassDefinition() method returns a DirContext that contains class descriptions about a particular directory object.

public interface DirContext extends Context {
    ...
    public DirContext getSchema(Name name)
        throws NamingException;

    public DirContext getSchemaClassDefinition(Name name)
        throws NamingException;
    ...
}

In addition, the schema associated with any attribute can be accessed using the Attribute.getAttributeDefinition() and getAttributeSyntaxDefinition() methods.

public interface Attribute ... {
    ...
    public DirContext getAttributeDefinition() throws NamingException;
    public DirContext getAttributeSyntaxDefinition()
    throws NamingException;
    ...
}

Example mapping Directory to Schema is an example showing the different associations for accessing schema information.

Example mapping Directory to Schema

Example mapping Directory to Schema

5.3 The Event Package -- javax.naming.event 3

The javax.naming.event package. The information in this graphic is available in the <a href= API documentation." WIDTH="769" HEIGHT="258" ALIGN="BOTTOM" BORDER="0" NATURALSIZEFLAG="3">

The javax.naming.event package contains classes and interfaces for supporting event notification in naming and directory services.

5.3.1 Naming Events

A NamingEvent represents an event that is generated by a naming/directory service.

public class NamingEvent extends java.util.EventObject {
    ...
    public int getType();
    public Binding getOldBinding();
    public Binding getNewBinding();
    ...
}

The event's type identifies the type of event. The NamingEvent class defines four types of events:

  1. OBJECT_ADDED
  2. OBJECT_REMOVED
  3. OBJECT_RENAMED
  4. OBJECT_CHANGED

These types can be placed into two categories:

    • Those that affect the namespace (add/remove/rename an object)
    • Those that affect an object's contents

In addition to the event's type, a NamingEvent contains other information about the change, such as information about the object before and after the change.

5.3.2 Naming Listeners

A naming listener is an object that registers for NamingEvent s. It is represented by the interface NamingListener . Each category of NamingEvent is handled by a corresponding subtype of NamingListener . The NamespaceChangeListener interface represents a listener interested in namespace changes, while the ObjectChangeListener represents a listener interested in changes to an object's contents. A listener implementation might implement one or both of these interfaces, depending on the types of events it is interested in.

5.3.3 Event Registration and Deregistration

The EventContext and EventDirContext interfaces extend the Context and DirContext interfaces, respectively, to support event registration and deregistration.

public interface EventContext extends Context {
    ...
    public void addNamingListener(Name target,
                                  int scope,
                                  NamingListener l)
           throws NamingException;
    public void removeNamingListener(NamingListener l)
           throws NamingException;
    public boolean targetMustExist()
           throws NamingException;
}

Like methods in the corresponding Context interface, addNamingListener() has an overload that accepts a String name argument. The name parameter is referred to as the target . The scope parameter specifies whether the registration is for the object named by the target, the immediate children of the context named by the target, or the entire subtree rooted at the object named by the target.

It is possible to register interest in a target that does not exist, but there might be limitations in the extent to which this can be supported by the service provider and underlying protocol/service. An application can use the method targetMustExist() to check whether an EventContext supports registration of nonexistent targets.

public interface EventDirContext extends EventContext, DirContext {
    public void addNamingListener(Name target,
                                  String filter,
                                  SearchControls ctls,
                                  NamingListener l)
                throws NamingException;
    public void addNamingListener(Name target,
                                  String filter,
                                  Object[] filterArgs,
                                  SearchControls ctls,
                                  NamingListener l)
                throws NamingException;
    ...
}

The EventDirContext interface extends the EventContext and DirContext interfaces to allow a listener to register interest in objects identified using search filters (Internet RFC 2254).

Like methods in the corresponding DirContext interface, addNamingListener() methods have overloads that accept a String name argument.

The EventContext/EventDirContext instance on which the addNamingListener() method is invoked is the event source of the events that are (potentially) generated. When the registered listener invokes getSource() or getEventContext() on a NamingEvent , the result will be this EventContext / EventDirContext instance.

For example, suppose a listener makes the following registration:

NamespaceChangeListener listener = ...;
src.addNamingListener("x", SUBTREE_SCOPE, listener);

When an object named "x/y" is subsequently deleted, the corresponding NamingEvent ( evt ) delivered to listener must contain src as its event source. The following will both be true:

evt.getEventContext() == src
evt.getOldBinding().getName().equals("x/y")

5.3.4 Exception Handling

When a listener registers for events with a context, the context might need to do some internal processing in order to collect information required to generate the events. The context, for example, might need to make a request to the server to register interest in changes on the server that will eventually be translated into events. If an error occurs that prevents information about the events from being collected, the listener will never be notified of the events. When such an error occurs, a NamingExceptionEvent is fired to notify the listener, and the listener is automatically deregistered.

The base NamingListener interface defines a namingExceptionThrown() method so that a listener can be notified of such an error.

public interface NamingListener extends java.util.EventListener {
    public void namingExceptionThrown(NamingExceptionEvent evt);
}

5.4 The LDAP Package -- javax.naming.ldap 4

The javax.naming.ldap package. The information in the graphic is available in the <a href= API documentation." WIDTH="826" HEIGHT="429" ALIGN="BOTTOM" BORDER="0" NATURALSIZEFLAG="3">

The javax.naming.ldap package contains classes and interfaces for using LDAP v3-specific features that are not already covered by the more generic javax.naming.directory package. In fact, the majority of JNDI applications that use LDAP will find the javax.naming.directory package sufficient, and will not need to use this package at all. This package is primarily for those applications that need to use extended operations, controls, or unsolicited notifications.

5.4.1 Extended Operations

In addition to specifying well-defined operations such as search and modify, the LDAP v3 protocol (Internet RFC 2251) specifies a way of transmitting yet-to-be defined operations between the LDAP client and server. These operations are referred to as extended operations . An extended operation may be defined by a standards organization such as the IETF or by a vendor.

The LdapContext interface defines a method for executing an extended operation:

public interface LdapContext extends DirContext {
    public ExtendedResponse extendedOperation(ExtendedRequest request)
           throws NamingException;
    ...
}

The ExtendedRequest interface represents the argument to an extended operation, while the ExtendedResponse interface represents the result of the extended operation. An ExtendedRequest or ExtendedResponse consists of an identifier that identifies the extended operation and a byte array containing the ASN.1 BER encoded contents of the request/response.

An application typically does not deal directly with the ExtendedRequest / ExtendedResponse interfaces. Instead, it deals with classes that implement these interfaces. The application gets these classes either as part of a repertoire of extended operations standardized through the IETF, or from directory vendors for vendor-specific extended operations. The request classes should have constructors that accept arguments in a type-safe and user-friendly manner, while the response classes should have access methods for getting the data of the response in a type-safe and user-friendly manner. Internally, the request/response classes deal with encoding and decoding BER values.

For example, suppose an LDAP server supports a "get time" extended operation. It would supply classes such as GetTimeRequest and GetTimeResponse , so that applications can use this feature. An application would use these classes as follows:

GetTimeResponse resp =
   (GetTimeResponse)lctx.extendedOperation(new GetTimeRequest());
long time = resp.getTime();

5.4.2 Controls

The LDAP v3 protocol (Internet RFC 2251) allows any request or response to be augmented by yet-to-be defined modifiers. These modifiers are referred to as controls . Controls that are sent with requests are called request controls and those that are sent with responses are called response controls . A control may be defined by a standards organization such as the IETF or by a vendor. There is not necessarily a pairing between request controls and response controls.

JNDI classifies request controls into two categories:

    • connection request controls: those that affect how a connection is created
    • context request controls: those that affect context methods

Connection request controls are used whenever a connection needs to be established or re-established with an LDAP server. Context request controls are used when all other LDAP operations are sent to the LDAP server. The reason for this distinction is because JNDI is a high-level API that does not deal directly with connections. It is the job of service providers to do any necessary connection management. Hence, a single connection might be shared by multiple context instances, and a service provider is free to use its own algorithms to conserve connection and network usage. Thus, when a method is invoked on the context instance, the service provider might need to do some connection management in addition to performing the corresponding LDAP operations. For connection management, it uses the connection request controls, while for the normal LDAP operations, it uses the context request controls.

The LdapContext interface defines methods for dealing with controls:

public interface LdapContext extends DirContext {
    public void reconnect(Control[] connCtls) throws NamingException;
    public Control[] getConnectControls() throws NamingException;
    ...
    public LdapContext newInstance(Control[] reqCtls)
           throws NamingException;
    public void setRequestControls(Control[] reqCtls)
           throws NamingException;
    public Control[] getRequestControls() throws NamingException;
    ...
    public Control[] getResponseControls() throws NamingException;
}

The Control interface represents a control. It consists of an identifier that identifies the control and a byte array containing the ASN.1 BER encoded contents of the control.

Connection request controls are initialized using the initial context constructor and are inherited by contexts that are derived from a context. reconnect() is used to change the connection request controls of a context. A context's connection request controls are retrieved using getConnectControls() .

Context request controls are initialized using newInstance() and changed using setRequestControls() . newInstance() is a convenience method for creating a new instance of a context for the purposes of multithreaded access. For example, if multiple threads want to use different context request controls, each thread may use this method to get its own copy of this context and set/get context request controls without having to synchronize with other threads.

Unlike connection request controls, context request controls are not inherited by context instances that are derived from a context. Derived context instances are initialized with no context request controls. You must set the request controls of a derived context instance explicitly using setRequestControls() . A context's context request controls are retrieved using getRequestControls() .

5.4.3 The Initial Context

An application that is performing LDAP extended operations or controls can use InitialLdapContext instead of javax.naming.InitialContext or javax.naming.directory.InitialDirContext to create its initial context:

public class InitialLdapContext extends InitialDirContext implements LdapContext {
    public InitialDirContext() ...;
    public InitialDirContext(Hashtable env, Control[] connCtls) ...;
}

It can then invoke any method in the Context , DirContext , or LdapContext interfaces on the initial context. By using the constructor that accepts a connCtls argument, the application can specify controls to be used when establishing a connection with the LDAP server.

5.4.4 Unsolicited Notifications

In addition to the normal request/response style of interaction between the client and server, the LDAP v3 protocol also specifies unsolicited notifications --messages that are sent from the server to the client asynchronously, not in response to any client request.

JNDI supports unsolicited notifications using the event model embodied in the javax.naming.event package. It defines an UnsolicitedNotificationEvent class and a corresponding UnsolicitedNotificationListener interface. An application registers to receive UnsolicitedNotificationEvent s by supplying an UnsolicitedNotificationListener to EventContext.addNamingListener() .

1. See Appendix C for legend of class diagram.

2. See Appendix C for legend of class diagram.

3. See Appendix C for legend of class diagram.

4. See Appendix C for legend of class diagram.

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


6 Configuration

CONTENTS | PREV | NEXT JNDI API

6. Configuration

6.1 Environment Properties

Some JNDI applications need a way to communicate various preferences and information that define the environment in which naming and directory services are accessed. For example, an application might need to specify the level of security for accessing a directory service. Or, when directory and naming services are distributed, the source of information is in more than one place--replicas, master, caches, etc. An application might want to access information from the authoritative source and needs to indicate this information to the JNDI system.

To address these requirements, JNDI defines a number of properties that developers and users can use to provide configuration information to the JNDI system. These are called environment properties .

There are different types of environment properties:

    • Standard JNDI environment properties. These properties are defined by JNDI and are common across all service providers. They are defined in relatively generic terms. For example, the property "java.naming.security.principal" is used to specify the security principal for authentication to the naming service. Individual service providers map these environment properties to an interpretation appropriate for their service. These properties have the prefix "java.naming.". contains a list of standard JNDI environment properties. The Context interface defines constants for most of these environment property names.
    • Service-specific environment properties. These properties are common across all service providers that implement a particular service or protocol. They have the prefix "java.naming. service. ", where service is the name of the service. For example, the prefix "java.naming.ldap." is used for LDAP-specific environment properties.
    • Feature-specific environment properties. These properties are common across all service providers that support a particular feature. They have the prefix "java.naming. feature .", where feature is the name of the feature. For example, the prefix "java.naming.security.sasl." is used for SASL-specific environment properties.
    • Provider-specific environment properties. These properties only apply to a particular service provider. They should have a prefix that reflects this uniqueness. A common practice is to use the package name of the service provider as the prefix. For example, since Sun's LDAP provider is primarily contained in the package com.sun.jndi.ldap , properties specific to Sun's LDAP provider have the prefix "com.sun.jndi.ldap.".

See Context Environment for security-related considerations when using environment properties.

Although the support for environment properties is rather extensive, it is important to note that an application typically does not need to deal with them, or only needs to set one or two properties. Most properties have reasonable defaults and only need to be adjusted when the application has special requirements.

6.2 Context Environment

A context's environment is represented as a java.util.Hashtable or any of its subclasses (e.g., java.util.Properties 1 ). It is typically specified using an argument to the InitialContext , InitialDirContext , or InitialLdapContext constructors, and augmented with data from other sources (as discussed in the rest of this section). They are inherited from the parent context as context methods proceed from one context to the next. For example, the following code creates an environment consisting of two security-related properties and creates an initial context using that environment.

Hashtable env = new Hashtable();
env.put(Context.SECURITY_PRINCIPAL, "jsmith");
env.put(Context.SECURITY_CREDENTIALS, "xxxxxxx");
Context ctx = new InitialContext(env);

Contexts that are looked up or otherwise derived from this initial context will have these two properties in their environment.

A context's environment can be examined using Context.getEnvironment() .

Not all environment properties are meaningful to all contexts. Those that are not meaningful are ignored by the context but inherited by derived contexts (because they might be meaningful, for instance, to federated contexts).

6.3 Resource Files

A JNDI resource file is a file in the properties file format (see java.util.Properties ). The file contains a list of key/value pairs. The key is the name of the property (e.g., "java.naming.factory.object") and the value is a string in the format defined for that property. Here is an example of a JNDI resource file:

java.naming.factory.object=com.wiz.jndi.AttrsToCorba:com.wiz.jndi.ToPerson
java.naming.factory.state=com.wiz.jndi.CorbaToAttrs:com.wiz.jndi.FromPerson
java.naming.factory.control=com.wiz.jndi.MyResponseControlFactory

There are two kinds of JNDI resource files: application and provider.

Application Resource Files

When an application is deployed, it will generally have several codebase directories and JARs in its classpath. Similarly, when an applet is deployed, it will have a codebase and archives specifying where to find the applet's classes. JNDI locates all application resource files named jndi.properties in the classpath. In addition, if the file $JAVA_HOME/lib/jndi.properties exists and is readable, JNDI treats it as an additional application resource file. ( $JAVA_HOME is the directory named by the java.home system property.) All of the properties contained in these files are placed into the environment of the initial context. This environment is then inherited by other contexts.

For each property found in more than one application resource file, JNDI uses the first value found or, in a few cases where it makes sense to do so, it concatenates all of the values. For example, if the java.naming.factory.object property is found in three jndi.properties resource files, the list of object factories is a concatenation of the property values from all three files. Using this scheme, each deployable component is responsible for listing the factories that it exports. JNDI automatically collects and uses all of these export lists when searching for factory classes.

Application resource files are available beginning with the Java 2 Platform, except that the file in $JAVA_HOME/lib can be used on all Java platforms.

Provider Resource Files

Each service provider has an optional resource file that contains properties specific to that provider. The name of this resource is:

[prefix/]jndiprovider.properties

where prefix is the package name of the provider's context implementation(s), with each period (".") converted to a slash ("/").

The JNDI library will consult the provider resource file when determining the values of certain properties. Properties other than these can be set in the provider resource file at the discretion of the service provider. The service provider's documentation should clearly state which properties are allowed.

6.4 Application/Applet-scope Standard JNDI Properties

Certain standard JNDI properties can alternately be set in the Java runtime's system properties, or in an applet's parameter list. These properties are:

java.naming.factory.initial
java.naming.factory.object
java.naming.factory.state
java.naming.factory.control
java.naming.factory.url.pkgs
java.naming.provider.url
java.naming.dns.url

For JNDI to access an applet's parameters, the applet code must set the java.naming.applet environment property to an instance of the applet ( java.applet.Applet ).

When these properties are set as system properties or applet parameters, they affect all of the application's/applet's contexts.

6.5 How the Environment Properties are Set

When JNDI constructs an initial context, the context's environment is initialized with properties defined in the environment parameter passed to the constructor and all application resource files. For the application/applet-scope properties, their values from the system properties and the applet parameters are also used.

JNDI passes the resulting environment to the initial context implementation. The environment is then inherited by contexts that are derived from the initial context. Since JNDI performs any necessary merging of the properties and their values, there is no need for the application or context implementation to directly consult the system properties or applet parameters.

6.6 Modifications to the Environment

A context's environment can be changed using the addToEnvironment() and removeFromEnvironment() methods:

public interface Context {
    public Object addToEnvironment(String propName, Object val)
        throws NamingException;
    public Object removeFromEnvironment(String propName)
        throws NamingException;
    ...
}

Not all environment properties are meaningful to all contexts. Changes to those that are not meaningful are still recorded and passed onto derived contexts.

Scope

Changing a property using the addToEnvironment() or removeFromEnvironment() methods affects the context instance on which the method is invoked. For example, if you specify new credentials for a context to use, subsequent methods invoked on that context that require communication with the server will use those new credentials (perhaps internally by first creating a new connection to the server). These updated environment properties are inherited by context instances that are subsequently derived from the affected context instance, but do not otherwise affect other context instances that were in existence prior to the update.

Timeliness

When a change is made to the environment properties, there is no requirement that the change be verified and acted upon at the time addToEnvironment() or removeFromEnvironment() is invoked. The only requirement is that the change (or changes) be effective the next time an operation that uses that property is invoked.

Defaults

For some environment properties, JNDI defines defaults (see Appendix A). For others, the default might be determined by the service provider or a group of service providers. If a context's environment does not have a particular property, the context behaves as if its environment has that property with its default value.

When a property is removed from a context's environment, the context assumes the default behavior specified for that property. This does not necessarily mean that the default value must be recorded as the property's value. The removal may also be indicated by the absence of the property from the context's environment.

Acceptable Values

Some environment properties have a fixed set of acceptable values while others have values that must follow a particular syntax. If an unacceptable value is presented, a property-specific exception will be thrown (for example, ConfigurationException , IllegalArgumentException , or AuthenticationNotSupportedException ). In some cases, it might be reasonable for the service provider to accept additional values than those specified, in which case, those values should be documented.

1. Note that if you use Properties, only the top-level properties are consulted--its defaults are not consulted--because Hashtable.get() is used when retrieving entries from the environment. See java.util.Properties for details.

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


7 Scenarios

CONTENTS | PREV | NEXT JNDI API

7. Scenarios

This section outlines a few application scenarios to help illustrate the capabilities enabled by JNDI.

    • The examples below are not meant to be prescriptive. There are often several ways to solve a problem, and JNDI is designed with flexibility in mind.

7.1 User authentication

In secure systems, a user must authenticate himself to the computer, network, or service that he wishes to access. For example, logging into Unix requires the user to supply a password. Similarly, use of SSL requires that the user supply his X.509 certificate. Such authentication information can be stored as attributes associated with each user in the directory. The system performing the authentication would look up the attribute (for example, "password") of the user and verify the authenticity using the information supplied by the user.

DirContext ctx = new InitialDirContext();
Attribute attr = ctx.getAttributes(userName).get("password");
String password = (String)attr.get();

7.2 Electronic Mail

A useful feature of an electronic mail system is a directory service that provides a mapping between users and email addresses. This allows mail users to search for the email address of a particular user. This is analogous to searching for an individual's telephone number in the phone book in order to dial his phone number. For example, when I want to send mail to John Smith in my department, I search for "John Smith" in the directory using a "search" widget in the mail application. The widget returns to me five entries of John Smith, from which I select the one that is in a building on my site and use the email address attribute associated with that entry.

NamingEnumeration matches = deptCtx.search("user", new BasicAttributes("name", "John Smith"));
// use matches to construct a selectable list for end-user
while (matches.hasMore()) {
    SearchResult item = (SearchResult) matches.next();
    Attributes info = item.getAttributes();
    /* display attributes */
    ...
}

The directory could also be used by users to set up personalized address books. For example, once I have located John Smith's email address, I might not want to search the directory again each time I send him mail. Instead, I can create a personal subtree in the directory in which I maintain entries that I frequently use, possibly by creating links to the existing entries.

7.3 Databases

Database applications can use the directory to locate database servers. For example, a financial application needs to get the stock quotes from a stock quote server using JDBC. This application can enable the user to select the stock quote server based on specification of some attributes (such as coverage of which markets and frequency of quote updates). The application searches the directory for quote servers that meet these attributes, and then retrieves the "location" attribute (a JDBC URL) of the selected quote server and connects to it.

NamingEnumeration matches = 	ctx.search("service/stockQuotes",
                                "(&(market=NASDAQ)(updateFreqency<=300))", searchctls);
while (matches.hasMore()) {
       SearchResult item = (SearchResult)matches.next();
       Attribute location = item.getAttributes().get("location");
   ...
}

7.4 Browsing

When using almost any kind of interactive application that asks a user to input names, the user's job is made easier if a namespace browser is available to him. The browser can either be built into the application and tailored to suit that application in particular, or it can be more general-purpose such as a typical web browser.

A very simple example of a JNDI browser allows a user to "walk" through a namespace, viewing the atomic names at each step along the way. The browser prints a "*" to highlight the name of each Context , thus telling the user where he can go next. 1

// Start at the top -- the initial context.
Context ctx = new InitialContext();
while (ctx != null) { 		// display one level
    NamingEnumeration 	items = ctx.list();
    while (items.hasMoreElements()) {
        NameClassPair item = (NameClassPair)items.next();
        if (isContext(item.getClassName())) {
            System.out.print("*");
        } else {
            System.out.print(" ");
        }
        System.out.println(" " + item.getName());
    }
    // Take the next step down into the namespace.
    String target = input.readLine();
    try {
        ctx = (Context)ctx.lookup(target);
    } catch (NamingException e) {
        // handle error
    } catch (ClassCastException e) {
        // not a context; cannot traverse
    }
}

7.5 Network Printing

An important function of a printing service is to provide a means for its human users to easily discover and select printers in the network. An application that needs to print, or the machine on which it runs, should not have to be configured each time a new printer is added to the network. The scope of network access to printers may range from a workgroup to global. The printing service can use the directory to provide this capability.

Assume that printers are represented by a Printer interface. One of the methods in it could be print() which, when given an InputStream , will read data from InputStream and print it on the printer represented by this instance of Printer.

interface Printer {
    void print(InputStream data) throws PrinterException;
    ...
}

A user selects a printer using a logical printer name, either explicitly or through default settings. For example, the user might have specified a default printer to use for all his applications, which is overridden only when he explicitly specifies another printer to use. The application that is accepting the print request takes the printer name and looks it up in the directory service. The application expects to receive as the result an object that implements the Printer interface.

void myAppPrint(String printerName, String fileName) throws IOException {
    try {
        DirContext ctx = new InitialDirContext();
        Printer prt = (Printer) ctx.lookup(printerName);
        prt.print(new FileInputStream(fileName));
    } catch (NamingException e){
        System.err.println("Could not locate printer: " + e);
    } catch (ClassCastException e) {
        System.err.println(printerName + "does not name a printer");
    }
}

7.5.1 Browsing and searching for printers

Selecting a printer by explicitly giving its name is but one way of identifying a printer. The user can also use the directory to see the different printers available (browsing), or to search for printers with particular attributes. For example the user can ask the directory to list all the printers on the second floor of building 5 in the Mountain View campus, or search for all color laser printers with 600dpi resolution. From the application's perspective, just as lookup() returned a Printer object, the list and search operations also provide the same capability of returning Printer objects that the application could use to submit print requests.

1. The isContext() method used in the example is not part of JNDI. It is a method that must be provided by the application.

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


8 Security Considerations

CONTENTS | PREV | NEXT JNDI API

8. Security Considerations

There are two main settings in which JNDI is used: with and without a security manager installed.

In the case of Java applications running with no security manager installed, the code is trusted and the application can access service providers from the local classpath. Furthermore, there is no restriction if the service providers access local files, or make network connections to naming or directory servers anywhere on the network.

In the case of an applet or application running with a security manager installed, there can be trusted code and untrusted code within the same applet or application. The Sharing Context Handles and Context Environment sections below are especially applicable in such a scenario. The ability of an applet or an application running with a security manager installed to access service providers, especially service providers that require the use of restricted resources (like the file system or network connections) may be severely limited.

8.1 JNDI Classes

The classes in the JNDI packages contain no native methods. They do not require any special installation in order to run inside an applet or an application.

JNDI uses several system properties (see Application/Applet-scope Standard JNDI Properties ). This allows applets and applications to be configured easily without much programming. However, an applet or application might have restricted access to some or all system properties as a result of the security manager installed on the platform on which it is running. Consequently, JNDI also allows these same properties to be specified as applet parameters, in resource files, or as environment properties passed to a context.

In the Java 2 Platform, the JNDI classes use doPrivileged blocks when accessing the system properties listed in Application/Applet-scope Standard JNDI Properties .

8.2 Security Model

JNDI does not define a security model or a common security interface for accessing naming and directory servers. Security-related operations, such as those required for authentication or access control to the directory service, are dealt with by individual service providers. JNDI provides the means by which an application or applet can pass such security-related information to service providers in order to establish a connection with the service, but does not itself take part in such security-related activities.

JNDI also provides the means by which security-related problems can be indicated to the client in the form of security-related exceptions.

JNDI service providers are controlled by the security manager in place when they try to gain access to protected resources such as the file system or network. Some service providers may control directory access by making use of the Java 2 Platform security architecture (for example, allowing access to special ports for administration-related applets).

8.3 Access To Servers

Naming and directory services typically have their own security system in place to protect information stored therein. For example, one directory might require that its users first "login" to the directory before reading or updating information in the directory. Some services might allow anonymous access to part of its namespace/directory.

Once a user has logged into a service, it is imperative for security reasons not to share that privilege with untrusted code.

8.4 Sharing Context Handles

In the following discussion, we refer to a context handle as a reference to a Context instance. This is analogous to how a reference to a Reader / Writer / InputStream / OutputStream instance is often referred to as a file handle .

A context handle should be treated like any other protected resource. If a piece of trusted code obtains a context handle (possibly by authenticating its access with the directory server), it should protect the use of that context against unauthorized or untrusted code. This is analogous to how application and/or applet code should protect file handles. For example, if a piece of trusted code opens a file for writing (and it was granted such privilege because of its trusted nature), it should be careful about passing that file handle to any other pieces of code, trusted or otherwise.

Similarly, giving access of a context handle to untrusted code may lead to its misuse in accessing or updating information in the directory, or accessing security-sensitive environment properties associated with the context.

8.5 Context Environment

JNDI allows the application/applet to pass preferences and information to a context in the form of an environment. The application/applet can also get the current environment from a context. See See Configuration and Appendix A for more information on a context's environment.

The nature of the information contained in a context's environment might be sensitive and need protection from untrusted access. Specifically, the environment properties java.naming.security.principal and java.naming.security.credentials contain information that should not be given out to untrusted code. Service providers might take precaution to protect against accessing these properties (see Responsibilities of Service Providers below). Client applications and applets should take care not to pass context handles with such sensitive environment properties to untrusted code.

8.6 Class Loading

JNDI allows the class files to be loaded dynamically.

When JNDI is run on the JDK 1.1.x platform, it uses the RMI class loader. The classes can only be loaded if there is a security manager installed, and if that security manager permits the class to be loaded. When such classes are loaded, they run in the security context dictated by the security manager.

When JNDI is run on the Java 2 platform, it will attempt to load such classes from the locations specified in the codebase using the java.net.URLClassLoader . In order for the class loading to succeed, you must grant the application and the JNDI and service provider classes the permissions appropriate for the URLs named in the codebase. For example, if the URL scheme is "http" or "ftp", you must grant the application the appropriate java.net.SocketPermission ; if the URL scheme is "file", you must grant the application the appropriate java.io.FilePermission .

8.7 Serializable Objects

Several of the JNDI classes are serializable. This allows the objects to be accessed in the form of a byte stream, possibly outside of the environment in which they were created. See the document at the following URL regarding security issues related to serialized objects.

http://java.sun.com/products/jdk/1.2/docs/guide/serialization/spec/security.doc.html

8.8 Responsibilities of Service Providers

8.8.1 Context Environment

When a context handle is created (either by getting the initial context or by looking it up or by creating it from the directory), some environment properties may be specified for it. Sometimes security-related properties are required for the creation of the context handle (such as user information that "logs" the user in with the directory). The service provider should take care to protect this security-sensitive information from untrusted code.

The service provider needs to protect the context's environment from being tampered or otherwise modified by untrusted code. The service provider needs to protect the security-sensitive environment properties from being read by untrusted code. It might do this by disallowing any thread whose execution context and/or trust level is different than that originally held by the thread that created the context handle to use the context handle. Or it might disallow certain operations (such as accessing security-sensitive environment properties). Or it might simply not return security-sensitive environment properties, or only return them to trusted code.

8.8.2 Network Security

Untrusted code (such as those found in untrusted applets) have limited access to the network. Untrusted applets, for example, can only create a network connection to the host from which they were downloaded. With finer-grain security models, it will be possible for the service provider itself to be trusted code, and hence be allowed to connect to hosts not allowed for untrusted applets. In such a scenario, the service provider should be careful not to compromise the security intended by the security manager. If the service provider is sure that access by an untrusted applet to the directory will cause no security problems, then it may proceed to offer such a service to untrusted code. For example, allowing untrusted code to access a directory "anonymously" would post no security problems because the directory already allows any anonymous client (written in the Java programming language or otherwise) to access the same data.

Most naming and directory services are accessed over the network. Although the data requested is protected by the server's authentication and access control mechanisms, some protocols do not protect (encrypt) the data being sent as replies. Again, this is not a problem particular to a client using JNDI but a problem for any client accessing the directory. The service provider should document the security implications associated with using the associated directory over a network.

8.8.3 Accessing Local Files

Similar to network access, untrusted code has limited access to the local file system. If the service provider has special privileges for accessing local files, it should do so with utmost precaution so as not to compromise the security policies intended by the runtime/platform.

8.8.4 Privileged Code, Native Methods

A service provider that is written completely in the Java programming language with no privileged sections is controlled by the same security policies afforded other code written in the Java programming language. All protected resources that it attempts to access go through the same security manager and access controller.

If a service provider contains privileged code sections, or if it contains native methods, then it needs to be especially careful to preserve the security policies intended by the runtime/platform.

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


9 Design Choices

CONTENTS | PREV | NEXT JNDI API

9. Design Choices

9.1 Separation of Interfaces into Context and DirContext

There are two core interfaces in JNDI: Context , and DirContext , with DirContext extending the base naming operations in Context with directory service operations. They have been separated into separate interfaces both for modularity and also in keeping with the "pay for what you use" goal of JNDI.

Naming is a basic component found in many computing services such as file systems, spreadsheets, calendar services, and directory services. By having a base Context interface for the naming operations, we enable its use by all these other services, not just for directory services.

DirContext extends Context to provide basic directory service operations, which include manipulation of attributes associated with named objects, attribute-based searches, and schema-related operations of those attributes and named objects.

9.2 Separation of JNDI into Different Functional Packages

JNDI is separated into four client packages ( javax.naming , javax.naming.directory , javax.naming.event , javax.naming.ldap ) and a service provider package ( javax.naming.spi ). The idea is that each package contains the interfaces and classes required for a particular category of applications, again in keeping with the "pay for what you use" goal. For example, an application that just wants to perform name-lookups only needs to use the javax.naming package. An application that wants to examine/modify attributes associated with an object uses the javax.naming and javax.naming.directory packages. An application that needs to use LDAP-specific controls or extended operations uses the javax.naming.ldap package. There is a step-by-step progression of what classes and interfaces each category of application writer needs to learn and use.

9.3 Separation of Client APIs and Service Provider Interfaces

JNDI separates interfaces and classes that a client application needs to use from those that are only of interest to service providers into different packages. For example, a client would use interfaces and classes from javax.naming , while a service provider that is hooking up a naming service would use both javax.naming and javax.naming.spi . The package delineation minimizes confusion for the application developer and makes clear which packages he needs to examine when writing his program.

9.4 Multiple methods for listing Context

There are two common types of applications that list contexts: browser-style applications, and applications that need to perform operations on the objects in a context en-masse. Browser-style applications typically want to display the names of the contents of a context. In addition to the names, many browsers often require type information of the objects bound to the names, so that it can display appropriate pictorial representations of the objects. The browser is usually interactive. Once a user has used a browser to display the contents of a context, he would then select one or a few of the entries displayed and request more information on it.

Some applications need to perform operations on objects within a context en-masse. For example, a backup program might want to perform "file stats" operations on all the objects in a file directory. A printer administration program might want to restart all the printers in a building. To perform such operations, these programs need to obtain all the objects bound in a context.

With these two common styles of usage in mind, the Context interface has two types of list methods: list() and listBindings() . list() returns a list of name/class-name pairs while listBindings() returns a list of name/class-name/object tuples. list() is designed for browser-style applications that want mostly just the names and types of objects bound in a context. listBindings() is for applications that want to potentially get all the objects in the context, as well as their names and types. listBindings() returns an enumeration of Binding . Both the listBindings() operation itself and invocation of methods in the Binding class (e.g. getObject() ) could be implemented lazily or eagerly. Using listBindings() simply indicates the potential that the caller might want all or many of the objects in the context so that implementations that are able can optimize for it. Using list() indicates that the caller is unlikely to want all, if any, objects in the context so implementations can optimize for that if possible.

An alternative is to have a single list operation and have the lazy or eager behavior as part of the implementation of Binding . The advantage of this is that there is a single list operation to learn. The disadvantage is that the caller has no way of indicating which piece of information he wants back from list, and subsequently, implementations cannot optimize for the eventual behavior of the program.

9.5 Support for Federation

Federation is a first-class concept in JNDI. In the client interfaces, it is supported by the use of the Name interface for specifying names that can span one or more namespaces. The caller of the methods in the client interface need not know anything else regarding federation. Resolution of names across multiple systems is handled by the SPI and does not involve any intervention on the part of the caller.

Although federation is a first-class concept, that does not mean that all callers and service providers must make use of it. If an application or service does not want to take advantage of federation, there is no requirement that Name always span multiple namespaces. Name can just name objects within a single namespace, and the SPI can handle name resolution within a single namespace as well (as a degenerate case of multiple namespace support).

9.6 DirContext versus DirObject

Instead of having DirContext extend Context , an alternative would be to not extend Context at all but to have a separate interface called DirObject that encapsulates all the directory-related methods. In that case, an object can implement both Context and DirObject if it supports both the naming and directory operations; another object might implement just DirObject .

The problem with eliminating DirContext is that DirContext contains some hybrid operations that involve both naming and directories ( bind() , createSubcontext() methods that accept attributes as arguments). To keep these operations and have DirObject at the same time would produce the need for a third interface (perhaps called DirContext ) to contain just these hybrids.

Furthermore, having DirContext instead of DirObject is somewhat more convenient in that you can perform some operations in one step instead of two. For example DirContext.getAttributes() could be used to get the attributes associated with a named object, whereas with DirObject , you would need first to resolve to the object ( Context.lookup() ) and then use DirObject.getAttributes() to get the attributes from it.

9.7 Support for Schemas

The DirContext interface contains support for schemas. For example, from a DirContext object you can obtain its schema object, which points to the directory space where the schema for this particular DirContext instance is defined. From a DirContext object, you can also obtain its schema class definition (i.e. information about what type of object this represents in the directory). There is further support for schemas in the Attribute class, which contains methods for obtaining an attribute's syntax information (i.e. what is the type of the attribute's value) and the attribute's definition (e.g. is it multivalued, syntax, constraints on its syntax). There is no requirement that any of this schema information be dynamically accessible (i.e. points to live directory spaces). Support for such schema information could be generated statically by the service provider. For example, a particular directory service might only support string attribute values, so it can hard-wire the syntax of the attributes that it returns. Another directory might support only static schemas (where information in the schema are not modifiable). Yet another directory might support fully dynamic schemas. The interfaces and classes in DirContext are flexible enough that these different levels of support for schemas can be accommodated.

9.8 Overloaded Methods in Context and DirContext

For each method in the Context and DirContext interfaces that accepts a Name argument, there is a corresponding overloaded form that accepts a String argument for specifying a name.

The motivation for having the String -based methods is that there are many applications that simply accept a string name from the end-user and perform context methods on the object named by that string name. For those applications, it is useful to have the context methods accept a string for the name directly, instead of requiring the applications to first construct a Name object using the string name.

The motivation for having the Name -based methods is that there are also many applications that manipulate names and do not want to worry about syntactic details of the names' string forms when composing and modifying names. These applications deal with the parsed form of names and hence would prefer to deal with Name objects rather than string names. For these applications, we provide the Name -based methods in the context interfaces. Not providing these methods would probably cause proliferation of Name -like interfaces/classes to support manipulation of names in their structural form in applications developed on top of JNDI.

9.9 Reference and Referenceable

There are different ways in which applications and services can use the directory to locate objects. JNDI is general enough that it accommodates several different models. For some applications, the object bound in the directory is the object itself. An application may build up a dynamic directory while the application is active, and delete the directory when the application exits. Another application might store URLs as attributes for locating objects in its namespace. Other systems might bind some reference information in the directory, which can subsequently be used to locate or access the actual object. This last case is quite common, especially for making Java applications take advantage of services in the installed base. The reference in the directory acts as a "pointer" to the real object.

JNDI defines a Reference class to provide a uniform way of representing reference information. A Reference contains information on how to access an object. It consists of a list of addresses and class information about the object to which this reference refers. When binding a name to an object that is to be represented in the directory as a reference, the desired effect is that the object's reference be extracted and bound. To allow for this behavior, the object's class must implement the Referenceable interface, which contains the method getReference() .

There is some similarity between the interfaces Serializable and Referenceable and a natural question is "why not just use Serializable instead?" The answer is that a serialized object is really a frozen version of the object, whereas the reference contains just the information needed to construct it. The serialized version may have a lot more state which may not be appropriate for storage in the directory.

9.10 Automatically Turning References into Objects

For an object that is bound as a Reference in the directory, JNDI SPI framework automatically creates and instantiates the object identified by the reference. In this way, the program can simply narrow the result of lookup() to the expected class, instead of calling a separate operation to transform the result of lookup() into an object of the expected class.

For example, if you are looking up a printer object, a successful lookup would return to you a printer object that you can directly use.

Printer prt = (Printer) ctx.lookup(somePrinterName);
prt.print(someFileName);

JNDI does this automatically, instead of requiring an explicit conversion step, because this is expected to be the common usage pattern. By having the Reference class, and a common mechanism for converting a Reference into the object identified by the Reference , JNDI encourages different applications and system providers to utilize this mechanism, rather than inventing separate mechanisms on their own.

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


B.1 Search the Directory

B.1.1 Search Using LDAP C API B.1.2 Search Using JNDI

B.1.1 Search Using LDAP C API

/*
* Copyright (c) 1996. Netscape Communications Corporation. All
* rights reserved.
*
* Search the directory for all people whose surname (last name) is
* “Jensen”. Since the “sn” attribute is a caseignorestring (cis), case
* is not significant when searching.
*
*/

#include “examples.h”

int
main( int argc, char **argv )
{
LDAP *ld;
LDAPMessage *result, *e;
BerElement *ber;
char *a, *dn;
char **vals;
int i;

/* get a handle to an LDAP connection
  */
if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {
perror( “ldap_init” );
return( 1 );
}
/* authenticate to the directory as nobody */
if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
ldap_perror( ld, “ldap_simple_bind_s” );
return( 1 );
}
/* search for all entries with surname of Jensen */
if ( ldap_search_s( ld, MY_SEARCHBASE, LDAP_SCOPE_SUBTREE,
MY_FILTER, NULL, 0, &result ) != LDAP_SUCCESS ) {
ldap_perror( ld, “ldap_search_s” );
return( 1 );
}
/* for each entry print out name + all attrs and values */
for ( e = ldap_first_entry( ld, result ); e != NULL;
e = ldap_next_entry( ld, e ) ) {
if ( (dn = ldap_get_dn( ld, e )) != NULL ) {
printf( “dn: %s\n”, dn );
ldap_memfree( dn );
}
for ( a = ldap_first_attribute( ld, e, &ber );
a != NULL; a = ldap_next_attribute( ld, e, ber ) ) {
if ((vals = ldap_get_values( ld, e, a)) != NULL ) {
for ( i = 0; vals[i] != NULL; i++ ) {
printf( “%s: %s\n”, a, vals[i] );
}
ldap_value_free( vals );
}
ldap_memfree( a );
}
if ( ber != NULL ) {
ber_free( ber, 0 );
}
printf( “\n” );
}
ldap_msgfree( result );
ldap_unbind( ld );
return( 0 );
}

B.1.2 Search Using JNDI

/*
 *
 * @(#)Search.java	1.2 99/07/26
 *
 * Copyright 1997, 1998, 1999 Sun Microsystems, Inc. All Rights
 * Reserved.
 *
 * Sun grants you ("Licensee") a non-exclusive, royalty free,
 * license to use, modify and redistribute this software in source and
 * binary code form, provided that i) this copyright notice and license
 * appear on all copies of the software; and ii) Licensee does not utilize
 * the software in a manner which is disparaging to Sun.
 *
 * This software is provided "AS IS," without a warranty of any
 * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
 * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN
 * AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY
 * LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE
 * OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
 * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
 * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
 * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF
 * OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGES.
 *
 * This software is not designed or intended for use in on-line
 * control of aircraft, air traffic, aircraft navigation or aircraft
 * communications; or in the design, construction, operation or
 * maintenance of any nuclear facility. Licensee represents and warrants
 * that it will not use or redistribute the Software for such purposes.
 */

import java.util.Hashtable;
import java.util.Enumeration;
import javax.naming.*;
import javax.naming.directory.*;
/*
 * Search the directory for all people whose surname (last name) is
 * "Jensen".  Since the "sn" attribute is a caseignorestring (cis), case
 * is not significant when searching.
 *
 * [equivalent to search.c in Netscape's SDK.]
 *
 */
class Search {
public static void main(String[] args) {
    Hashtable env = new Hashtable(5, 0.75f);
    /*
     * Specify the initial context implementation to use.
     * This could also be set by using the -D option to the java program.
     * For example,
     *   java -Djava.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory \
     *     Search
     */
    env.put(Context.INITIAL_CONTEXT_FACTORY, Env.INITCTX);
    /* Specify host and port to use for directory service */
    env.put(Context.PROVIDER_URL, Env.MY_SERVICE);
    try {
        /* get a handle to an Initial DirContext */
        DirContext ctx = new InitialDirContext(env);
        /* specify search constraints to search subtree */
        SearchControls constraints = new SearchControls();
        constraints.setSearchScope(SearchControls.SUBTREE_SCOPE);
        /* search for all entries with surname of Jensen */
        NamingEnumeration results
            = ctx.search(Env.MY_SEARCHBASE, Env.MY_FILTER, constraints);
        /* for each entry print out name + all attrs and values */
        while (results != null && results.hasMore()) {
            SearchResult si = (SearchResult)results.next();
            /* print its name */
            System.out.println("name: " + si.getName());
            Attributes attrs = si.getAttributes();
            if (attrs == null) {
                System.out.println("No attributes");
            } else {
                /* print each attribute */
                for (NamingEnumeration ae = attrs.getAll();
                     ae.hasMoreElements();) {
                    Attribute attr = (Attribute)ae.next();
                    String attrId = attr.getID();
                    /* print each value */
                    for (Enumeration vals = attr.getAll();
                         vals.hasMoreElements();
                         System.out.println(attrId + ": " + vals.nextElement()))
                            ;
                }
            }
            System.out.println();
        }
    } catch (NamingException e) {
        System.err.println("Search example failed.");
        e.printStackTrace();
    }
}
}

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


B.2 Read An Entry

B.2.1 Read Using LDAP C-API B.2.2 Read Using JNDI

B.2.1 Read Using LDAP C-API

/*
 * Copyright (c) 1996.  Netscape Communications Corporation.  All
 * rights reserved.
 *
 * Search the directory for the specific entry
 * “cn=Barbara Jensen, ou=Product Development, o=Ace Industry, c=US”.
 * Retrieve all attributes from the entry.
 *
 */
#include “examples.h”
int
main( int argc, char **argv )
{
    LDAP        *ld;
    LDAPMessage *result, *e;
    BerElement  *ber;
    char        *a, *dn;
    char        **vals;
    int         i;
    /* get a handle to an LDAP connection */
    if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {
        perror( “ldap_init” );
        return( 1 );
    }
    /* authenticate to the directory as nobody */
    if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
        ldap_perror( ld, “ldap_simple_bind_s” );
        return( 1 );
    }
    /* search for Babs’ entry */
    if ( ldap_search_s( ld, ENTRYDN, LDAP_SCOPE_SUBTREE,
            “(objectclass=*)”, NULL, 0, &result ) != LDAP_SUCCESS ) {
        ldap_perror( ld, “ldap_search_s” );
        return( 1 );
    }
    /* for each entry print out name + all attrs and values */
    for ( e = ldap_first_entry( ld, result ); e != NULL;
            e = ldap_next_entry( ld, e ) ) {
        if ( (dn = ldap_get_dn( ld, e )) != NULL ) {
            printf( “dn: %s\n”, dn );
            ldap_memfree( dn );
        }
        for ( a = ldap_first_attribute( ld, e, &ber );
                a != NULL; a = ldap_next_attribute( ld, e, ber ) ) {
            if ((vals = ldap_get_values( ld, e, a)) != NULL ) {
                for ( i = 0; vals[i] != NULL; i++ ) {
                    printf( “%s: %s\n”, a, vals[i] );
                }
                ldap_value_free( vals );
            }
            ldap_memfree( a );
        }
        if ( ber != NULL ) {
            ber_free( ber, 0 );
        }
        printf( “\n” );
    }
    ldap_msgfree( result );
    ldap_unbind( ld );
    return( 0 );
}

B.2.2 Read Using JNDI

/*
 * @(#)Rdentry.java	1.2 99/07/26
 *
 * Copyright 1997, 1998, 1999 Sun Microsystems, Inc. All Rights
 * Reserved.
 *
 * Sun grants you ("Licensee") a non-exclusive, royalty free,
 * license to use, modify and redistribute this software in source and
 * binary code form, provided that i) this copyright notice and license
 * appear on all copies of the software; and ii) Licensee does not utilize
 * the software in a manner which is disparaging to Sun.
 *
 * This software is provided "AS IS," without a warranty of any
 * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
 * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN
 * AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY
 * LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE
 * OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
 * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
 * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
 * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF
 * OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGES.
 *
 * This software is not designed or intended for use in on-line
 * control of aircraft, air traffic, aircraft navigation or aircraft
 * communications; or in the design, construction, operation or
 * maintenance of any nuclear facility. Licensee represents and warrants
 * that it will not use or redistribute the Software for such purposes.
 */
import java.util.Hashtable;

import javax.naming.*;
import javax.naming.directory.*;
/*
 * Search the directory for the specific entry
 * "cn=Barbara Jensen, ou=Product Development, o=Ace Industry, c=US".
 * Retrieve all attributes from the entry.
 *
 * [Equivalent to rdentry.c in Netscape SDK]
 */
class Rdentry {
public static void main(String[] args) {
    Hashtable env = new Hashtable(5, 0.75f);
    /*
     * Specify the initial context implementation to use.
     * This could also be set by using the -D option to the java program.
     * For example,
     *   java -Djava.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory \
     *       Rdentry
     */
    env.put(Context.INITIAL_CONTEXT_FACTORY, Env.INITCTX);
    /* Specify host and port to use for directory service */
    env.put(Context.PROVIDER_URL, Env.MY_SERVICE);
    try {
        /* get a handle to an Initial DirContext */
        DirContext ctx = new InitialDirContext(env);
        /* Read Babs' entry */
        Attributes attrs = ctx.getAttributes(Env.ENTRYDN);
        if (attrs == null) {
            System.out.println(Env.ENTRYDN + "has no attributes");
        } else {
            /* print each attribute */
            for (NamingEnumeration ae = attrs.getAll();
                 ae.hasMoreElements();) {
                Attribute attr = (Attribute)ae.next();
                String attrId = attr.getID();
                /* print each value */
                for (NamingEnumeration vals = attr.getAll();
                     vals.hasMoreElements();
                     System.out.println(attrId + ": " + vals.nextElement()))
                    ;
            }
        }
    } catch (NamingException e) {
        System.err.println("Rdentry example failed.");
        e.printStackTrace();
    }
}
}

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


B.3 Get Attributes

B.3.1 Get Attributes Using LDAP C API B.3.2 Get Attributes Using JNDI

B.3.1 Get Attributes Using LDAP C API

/*
 * Copyright (c) 1996.  Netscape Communications Corporation.  All
 * rights reserved.
 *
 * Retrieve several attributes of a particular entry.
 */
#include “examples.h”

int
main( int argc, char **argv )
{
    LDAP                *ld;
    LDAPMessage         *result, *e;
    char                **vals, *attrs[ 5 ];
    int                 i;
    /* get a handle to an LDAP connection */
    if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {
        perror( “ldap_init” );
        return( 1 );
    }
    attrs[ 0 ] = “cn”;         /* Get canonical name(s) (full name) */
    attrs[ 1 ] = “sn”;         /* Get surname(s) (last name) */
    attrs[ 2 ] = “mail”;       /* Get email address(es) */
    attrs[ 3 ] = “telephonenumber”;      /* Get telephone number(s) */
    attrs[ 4 ] = NULL;
    if ( ldap_search_s( ld, ENTRYDN, LDAP_SCOPE_BASE,
            “(objectclass=*)”, attrs, 0, &result ) != LDAP_SUCCESS ) {
        ldap_perror( ld, “ldap_search_s” );
        return( 1 );
    }
    /* print it out */
    if (( e = ldap_first_entry( ld, result )) != NULL ) {
        if (( vals = ldap_get_values( ld, e, “cn” )) != NULL ) {
            printf( “Full name:\n” );
            for ( i = 0; vals[i] != NULL; i++ ) {
                printf( “\t%s\n”, vals[i] );
            }
            ldap_value_free( vals );
        }
        if (( vals = ldap_get_values( ld, e, “sn” )) != NULL ) {
            printf( “Last name (surname):\n” );
            for ( i = 0; vals[i] != NULL; i++ ) {
                printf( “\t%s\n”, vals[i] );
            }
            ldap_value_free( vals );
        }
        if (( vals = ldap_get_values( ld, e, “mail” )) != NULL ) {
            printf( “Email address:\n” );
            for ( i = 0; vals[i] != NULL; i++ ) {
                printf( “\t%s\n”, vals[i] );
            }
            ldap_value_free( vals );
        }
        if (( vals = ldap_get_values( ld, e, “telephonenumber” )) != NULL ) {
            printf( “Telephone number:\n” );
            for ( i = 0; vals[i] != NULL; i++ ) {
                printf( “\t%s\n”, vals[i] );
            }
            ldap_value_free( vals );
        }
    }
    ldap_msgfree( result );
    ldap_unbind( ld );
    return( 0 );
}

B.3.2 Get Attributes Using JNDI

/*
 *
 * @(#)Getattrs.java	1.2 99/07/26
 *
 * Copyright 1997, 1998, 1999 Sun Microsystems, Inc. All Rights
 * Reserved.
 *
 * Sun grants you ("Licensee") a non-exclusive, royalty free,
 * license to use, modify and redistribute this software in source and
 * binary code form, provided that i) this copyright notice and license
 * appear on all copies of the software; and ii) Licensee does not utilize
 * the software in a manner which is disparaging to Sun.
 *
 * This software is provided "AS IS," without a warranty of any
 * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
 * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN
 * AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY
 * LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE
 * OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
 * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
 * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
 * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF
 * OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGES.
 *
 * This software is not designed or intended for use in on-line
 * control of aircraft, air traffic, aircraft navigation or aircraft
 * communications; or in the design, construction, operation or
 * maintenance of any nuclear facility. Licensee represents and warrants
 * that it will not use or redistribute the Software for such purposes.
 */

import java.util.Hashtable;
import java.util.Enumeration;

import javax.naming.*;
import javax.naming.directory.*;
/*
 * Retrieve several attributes of a particular entry.
 *
 * [equivalent to getattrs.c in Netscape SDK]
 */
class Getattrs {
public static void main(String[] args) {
    Hashtable env = new Hashtable(5, 0.75f);
    /*
     * Specify the initial context implementation to use.
     * For example,
     * This could also be set by using the -D option to the java program.
     *   java -Djava.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory \
     *       Getattrs
     */
    env.put(Context.INITIAL_CONTEXT_FACTORY, Env.INITCTX);
    /* Specify host and port to use for directory service */
    env.put(Context.PROVIDER_URL, Env.MY_SERVICE);
    try {
        /* get a handle to an Initial DirContext */
        DirContext ctx = new InitialDirContext(env);
        String[] attrs = new String[4];
        attrs[ 0 ] = "cn";              /* Get canonical name(s) (full name) */
        attrs[ 1 ] = "sn";              /* Get surname(s) (last name) */
        attrs[ 2 ] = "mail";            /* Get email address(es) */
        attrs[ 3 ] = "telephonenumber"; /* Get telephone number(s) */
        Attributes result = ctx.getAttributes(Env.ENTRYDN, attrs);
        if (result == null) {
            System.out.println(Env.ENTRYDN +
                               "has none of the specified attributes.");
        } else {
            /* print it out */
            Attribute attr = result.get("cn");
            if (attr != null) {
                System.out.println("Full name:" );
                for (NamingEnumeration vals = attr.getAll();
                     vals.hasMoreElements();
                     System.out.println("\t" + vals.nextElement()))
                    ;
            }
            attr = result.get("sn");
            if (attr != null) {
                System.out.println("Last name (surname):" );
                for (NamingEnumeration vals = attr.getAll();
                     vals.hasMoreElements();
                     System.out.println("\t" + vals.nextElement()))
                    ;
            }
            attr = result.get("mail");
            if (attr != null) {
                System.out.println("Email address:" );
                for (NamingEnumeration vals = attr.getAll();
                     vals.hasMoreElements();
                     System.out.println("\t" + vals.nextElement()))
                    ;
            }
            attr = result.get("telephonenumber");
            if (attr != null) {
                System.out.println("Telephone number:" );
                for (NamingEnumeration vals = attr.getAll();
                     vals.hasMoreElements();
                     System.out.println("\t" + vals.nextElement()))
                    ;
            }
        }
    } catch (NamingException e) {
        System.err.println("Getattrs example failed.");
        e.printStackTrace();
    }
}
}

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


B.4 Compare An Attribute

B.4.1 Compare Using LDAP C API B.4.2 Compare Using JNDI

B.4.1 Compare Using LDAP C API

/*
 * Copyright (c) 1996.  Netscape Communications Corporation.  All
 * rights reserved.
 *
 * Use ldap_compare() to compare values agains values contained in entry
 * “cn=Barbara Jensen, ou=Product Development, o=Ace Industry, c=US”.
 * We test to see if (1) the value “person” is one of the values in the
 * objectclass attribute (it is), and if (2) the value “xyzzy” is in the
 * objectlass attribute (it isn’t, or at least, it shouldn’t be).
 *
 */
#include “examples.h”
int
main( int main, char **argv )
{
    LDAP        *ld;
    int         rc;
    /* get a handle to an LDAP connection */
    if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {
        perror( “ldap_init” );
        return( 1 );
    }
    /* authenticate to the directory as nobody */
    if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
        ldap_perror( ld, “ldap_simple_bind_s” );
        return( 1 );
    }
    /* compare the value “person” against the objectclass attribute */
    rc = ldap_compare_s( ld, ENTRYDN, “objectclass”, “person” );
    switch ( rc ) {
    case LDAP_COMPARE_TRUE:
        printf( “The value \”person\” is contained in the objectclass “
                “attribute.\n” );
        break;
    case LDAP_COMPARE_FALSE:
        printf( “The value \”person\” is not contained in the objectclass “
                “attribute.\n” );
        break;
    default:
        ldap_perror( ld, “ldap_compare_s” );
    }
    /* compare the value “xyzzy” against the objectclass attribute */
    rc = ldap_compare_s( ld, ENTRYDN, “objectclass”, “xyzzy” );
    switch ( rc ) {
    case LDAP_COMPARE_TRUE:
        printf( “The value \”xyzzy\” is contained in the objectclass “
                “attribute.\n” );
        break;
    case LDAP_COMPARE_FALSE:
        printf( “The value \”xyzzy\” is not contained in the objectclass “
                “attribute.\n” );
        break;
    default:
        ldap_perror( ld, “ldap_compare_s” );
    }
    ldap_unbind( ld );
    return( 0 );
}

B.4.2 Compare Using JNDI

/*
 * @(#)Compare.java	1.2 99/07/26
 *
 * Copyright 1997, 1998, 1999 Sun Microsystems, Inc. All Rights
 * Reserved.
 *
 * Sun grants you ("Licensee") a non-exclusive, royalty free,
 * license to use, modify and redistribute this software in source and
 * binary code form, provided that i) this copyright notice and license
 * appear on all copies of the software; and ii) Licensee does not utilize
 * the software in a manner which is disparaging to Sun.
 *
 * This software is provided "AS IS," without a warranty of any
 * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
 * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN
 * AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY
 * LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE
 * OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
 * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
 * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
 * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF
 * OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGES.
 *
 * This software is not designed or intended for use in on-line
 * control of aircraft, air traffic, aircraft navigation or aircraft
 * communications; or in the design, construction, operation or
 * maintenance of any nuclear facility. Licensee represents and warrants
 * that it will not use or redistribute the Software for such purposes.
 */

import java.util.Hashtable;

import javax.naming.*;
import javax.naming.directory.*;
/*
 * Use search() to compare values against values contained in entry
 * "cn=Barbara Jensen, ou=Product Development, o=Ace Industry, c=US".
 * We test to see if (1) the value "person" is one of the values in the
 * objectclass attribute (it is), and if (2) the value "xyzzy" is in the
 * objectlass attribute (it isn't, or at least, it shouldn't be).
 *
 * [equivalent to compare.c in Netscape SDK]
 *
 */
class Compare {
public static void main(String[] args) {
    Hashtable env = new Hashtable(5, 0.75f);
    /*
     * Specify the initial context implementation to use.
     * This could also be set by using the -D option to the java program.
     * For example,
     *    java -Djava.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory \
     *       Compare
     */
    env.put(Context.INITIAL_CONTEXT_FACTORY, Env.INITCTX);
    /* Specify host and port to use for directory service */
    env.put(Context.PROVIDER_URL, Env.MY_SERVICE);
    DirContext ctx = null;
    SearchControls ctls = new SearchControls();
    ctls.setSearchScope(SearchControls.OBJECT_SCOPE);
    ctls.setReturningAttributes(new String[0]);  // do not return any attrs
    try {
        /* get a handle to an Initial DirContext */
        ctx = new InitialDirContext(env);
    } catch (NamingException e) {
        System.err.println("Cannot get initial context.");
        return;
    }
    try {
        NamingEnumeration results =
            ctx.search(Env.ENTRYDN, "objectclass=person", ctls);
        if (results != null && results.hasMoreElements()) {
            System.out.println(
                "The value \"person\" is contained in the objectclass attribute.");
        } else {
            System.out.println(
          "The value \"person\" is not contained in the objectclass attribute." );
        }
    } catch (NamingException e) {
        System.err.println("Comparison of value person failed.");
    }
    try {
        NamingEnumeration results =
            ctx.search(Env.ENTRYDN, "objectclass=xyzzy", ctls);

        if (results != null && results.hasMoreElements()) {
            System.out.println(
                "The value \"xyzzy\" is contained in the objectclass attribute.");
        } else {
            System.out.println(
          "The value \"xyzzy\" is not contained in the objectclass attribute." );
        }
    } catch (NamingException e) {
        System.err.println("Comparison of value xyzzy failed.");
    }
}
}

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


B.5 Modify Attributes

B.5.1 Modify Attributes Using LDAP C API B.5.2 Modify Attributes Using JNDI

B.5.1 Modify Attributes Using LDAP C API

/*
 * Copyright (c) 1996.  Netscape Communications Corporation.  All
 * rights reserved.
 *
 * Modify an entry:
 *  - replace any existing values in the “mail” attribute with “babs@ace.com”
 *  - add a new value to the “description” attribute
 */
#include “examples.h”
int
main( int argc, char **argv )
{
    LDAP        *ld;
    LDAPMod     mod0;
    LDAPMod     mod1;
    LDAPMod     *mods[ 3 ];
    char        *vals0[ 2 ];
    char        *vals1[ 2 ];
    time_t      now;
    char        buf[ 128 ];
    /* get a handle to an LDAP connection */
    if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {
        perror( “ldap_init” );
        return( 1 );
    }
    /* authenticate */
    if ( ldap_simple_bind_s( ld, ENTRYDN, ENTRYPW ) != LDAP_SUCCESS ) {
        ldap_perror( ld, “ldap_simple_bind_s” );
        return( 1 );
    }
    /* construct the list of modifications to make */
    mod0.mod_op = LDAP_MOD_REPLACE;
    mod0.mod_type = “mail”;
    vals0[0] = “babs@ace.com”;
    vals0[1] = NULL;
    mod0.mod_values = vals0;
    mod1.mod_op = LDAP_MOD_ADD;
    mod1.mod_type = “description”;
    time( &now );
    sprintf( buf, “This entry was modified with the modattrs program on %s”,
            ctime( &now ));
    /* Get rid of \n which ctime put on the end of the time string */
    if ( buf[ strlen( buf ) - 1 ] == ‘\n’ ) {
        buf[ strlen( buf ) - 1 ] = ‘\0’;
    }
    vals1[ 0 ] = buf;
    vals1[ 1 ] = NULL;
    mod1.mod_values = vals1;
    mods[ 0 ] = &mod0;
    mods[ 1 ] = &mod1;
    mods[ 2 ] = NULL;
    /* make the change */
    if ( ldap_modify_s( ld, ENTRYDN, mods )
            != LDAP_SUCCESS ) {
        ldap_perror( ld, “ldap_modify_s” );
        return( 1 );
    }
    ldap_unbind( ld );
    printf( “modification was successful\n” );
    return( 0 );
}

Modify Attributes Using JNDI

/*
 * @(#)Modattrs.java	1.2 99/07/26
 *
 * Copyright 1997, 1998, 1999 Sun Microsystems, Inc. All Rights
 * Reserved.
 *
 * Sun grants you ("Licensee") a non-exclusive, royalty free,
 * license to use, modify and redistribute this software in source and
 * binary code form, provided that i) this copyright notice and license
 * appear on all copies of the software; and ii) Licensee does not utilize
 * the software in a manner which is disparaging to Sun.
 *
 * This software is provided "AS IS," without a warranty of any
 * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
 * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN
 * AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY
 * LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE
 * OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
 * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
 * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
 * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF
 * OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGES.
 *
 * This software is not designed or intended for use in on-line
 * control of aircraft, air traffic, aircraft navigation or aircraft
 * communications; or in the design, construction, operation or
 * maintenance of any nuclear facility. Licensee represents and warrants
 * that it will not use or redistribute the Software for such purposes.
 */

import java.util.Hashtable;
import java.util.Date;

import javax.naming.*;
import javax.naming.directory.*;
/*
 * Modify an entry:
 *  - replace any existing values in the "mail" attribute with "babs@ace.com"
 *  - add a new value to the "description" attribute
 *
 * [equivalent to modattrs.c in Netscape SDK]
 */
class Modattrs {
public static void main(String[] args) {
    Hashtable env = new Hashtable(5, 0.75f);
    /*
     * Specify the initial context implementation to use.
     * This could also be set by using the -D option to the java program.
     * For example,
     *   java -Djava.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory \
     *       Modattrs
     */
    env.put(Context.INITIAL_CONTEXT_FACTORY, Env.INITCTX);
    /* Specify host and port to use for directory service */
    env.put(Context.PROVIDER_URL, Env.MY_SERVICE);
    /* specify authentication information */
    env.put(Context.SECURITY_AUTHENTICATION, "simple");
    env.put(Context.SECURITY_PRINCIPAL, Env.MGR_DN);
    env.put(Context.SECURITY_CREDENTIALS, Env.MGR_PW);
    try {
        /* get a handle to an Initial DirContext */
        DirContext ctx = new InitialDirContext(env);
        /* construct the list of modifications to make */
        ModificationItem[] mods = new ModificationItem[2];
        Attribute mod0 = new BasicAttribute("mail", "babs@eng");
        // Update mail attribute
        mods[0] = new ModificationItem(DirContext.REPLACE_ATTRIBUTE, mod0);
        // Add another value to description attribute
        Attribute mod1 =
            new BasicAttribute("description",
                          "This entry was modified with the Modattrs program on " +
                          (new Date()).toString());
        mods[1] = new ModificationItem(DirContext.ADD_ATTRIBUTE, mod1);
         /* Delete the description attribute altogether */
        /*
        Attribute mod1 =  new BasicAttribute("description");
        mods[2] = new ModificationItem(DirContext.REMOVE_ATTRIBUTE, mod1);
    */
        /* make the change */
        ctx.modifyAttributes(Env.ENTRYDN, mods);
        System.out.println( "modification was successful." );
    } catch (NamingException e) {
        System.err.println("modification failed. " + e);
    }
}
}

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


B.6 Rename An Entry

B.6.1 Rename Using LDAP C API

B.6.2 Rename Using JNDI

B.6.1 Rename Using LDAP C API

/*
 * Copyright (c) 1996.  Netscape Communications Corporation.  All
 * rights reserved.
 *
 * Modify the RDN (relative distinguished name) of an entry.  In this
 * example, we change the dn “cn=Jacques Smith, o=Ace Industry, c=US”
 * to “cn=Jacques M Smith, o=Ace Industry, c=US”.
 *
 * Since it is an error to either (1) attempt to modrdn an entry which
 * does not exist, or (2) modrdn an entry where the destination name
 * already exists, we take some steps, for this example, to make sure
 * we’ll succeed.  We (1) add “cn=Jacques Smith” (if the entry exists,
 * we just ignore the error, and (2) delete “cn=Jacques M Smith” (if the
 * entry doesn’t exist, we ignore the error).
 *
 * We pass 0 for the “deleteoldrdn” argument to ldap_modrdn2_s().  This
 * means that after we change the RDN, the server will put the value
 * “Jacques Smith” into the cn attribute of the new entry, in addition to
 * “Jacques M Smith”.
 */
#include “examples.h”
#define        NMODS        4
unsigned long        global_counter = 0;
static void free_mods( LDAPMod **mods );
int
main( int argc, char **argv )
{
    LDAP                    *ld;
    char                    *dn, *ndn, *nrdn;
    int                     i;
    int                     rc;
    LDAPMod                 **mods;
    /* Values we’ll use in creating the entry */
    char *objectclass_values[] = { “top”, “person”, “organizationalPerson”,
                                   “inetOrgPerson”, NULL };
    char *cn_values[] = { “Jacques Smith”, NULL };
    char *sn_values[] = { “Smith”, NULL };
    char *givenname_values[] = { “Jacques”, NULL };
    /* Specify the DN we’re adding */
    dn = “cn=Jacques Smith, o=Ace Industry, c=US”;
    /* the destination DN */
    ndn = “cn=Jacques M Smith, o=Ace Industry, c=US”;
    /* the new RDN */
    nrdn = “cn=Jacques M Smith”;
    /* get a handle to an LDAP connection */
    if ( (ld = ldap_init( MY_HOST, MY_PORT )) == NULL ) {
        perror( “ldap_init” );
        return( 1 );
    }
    /* authenticate to the directory as the Directory Manager */
    if ( ldap_simple_bind_s( ld, MGR_DN, MGR_PW ) != LDAP_SUCCESS ) {
        ldap_perror( ld, “ldap_simple_bind_s” );
        return( 1 );
    }
    if (( mods = ( LDAPMod ** ) malloc(( NMODS + 1 ) * sizeof( LDAPMod *)))
            == NULL ) {
        fprintf( stderr, “Cannot allocate memory for mods array\n” );
        return( 1 );
    }
    /* Construct the array of values to add */
    for ( i = 0; i < NMODS; i++ ) {
        if (( mods[ i ] = ( LDAPMod * ) malloc( sizeof( LDAPMod ))) == NULL ) {
            fprintf( stderr, “Cannot allocate memory for mods element\n” );
            return( 1 );
        }
    }
    mods[ 0 ]->mod_op = 0;
    mods[ 0 ]->mod_type = “objectclass”;
    mods[ 0 ]->mod_values = objectclass_values;
    mods[ 1 ]->mod_op = 0;
    mods[ 1 ]->mod_type = “cn”;
    mods[ 1 ]->mod_values = cn_values;
    mods[ 2 ]->mod_op = 0;
    mods[ 2 ]->mod_type = “sn”;
    mods[ 2 ]->mod_values = sn_values;
    mods[ 3 ]->mod_op = 0;
    mods[ 3 ]->mod_type = “givenname”;
    mods[ 3 ]->mod_values = givenname_values;
    mods[ 4 ] = NULL;

    /* Add the entry */
    if (( rc = ldap_add_s( ld, dn, mods )) != LDAP_SUCCESS ) {
        /* If entry exists already, fine.  Ignore this error. */
        if ( rc == LDAP_ALREADY_EXISTS ) {
            printf( “Entry \”%s is already in the directory.\n”, dn );
        } else {
            ldap_perror( ld, “ldap_add_s” );
            free_mods( mods );
            return( 1 );
        }
    } else {
        printf( “Added entry \”%s\”.\n”, dn );
    }
    free_mods( mods );
    /* Delete the destination entry, for this example */
    if (( rc = ldap_delete_s( ld, ndn )) != LDAP_SUCCESS ) {
        /* If entry does not exist, fine.  Ignore this error. */
        if ( rc == LDAP_NO_SUCH_OBJECT ) {
            printf( “Entry \”%s\” is not in the directory.  “
                    “No need to delete.\n”, ndn );
        } else {
            ldap_perror( ld, “ldap_delete_s” );
            return( 1 );
        }
    } else {
        printf( “Deleted entry \”%s\”.\n”, ndn );
    }
    /* Do the modrdn operation */
    if ( ldap_modrdn2_s( ld, dn, nrdn, 0 ) != LDAP_SUCCESS ) {
        ldap_perror( ld, “ldap_modrdn2_s” );
        return( 1 );
    }
    printf( “The modrdn operation was successful.  Entry\n”
            “\”%s\” has been changed to\n”
            “\”%s\”.\n”, dn, ndn );
    ldap_unbind( ld );
    return 0;
}

/*
 * Free a mods array.
 */
static void
free_mods( LDAPMod **mods )
{
    int i;

    for ( i = 0; i < NMODS; i++ ) {
        free( mods[ i ] );
    }
    free( mods );
}

B.6.2 Rename Using JNDI

/*
 * @(#)Modrdn.java	1.2 99/07/26
 *
 * Copyright 1997, 1998, 1999 Sun Microsystems, Inc. All Rights
 * Reserved.
 *
 * Sun grants you ("Licensee") a non-exclusive, royalty free,
 * license to use, modify and redistribute this software in source and
 * binary code form, provided that i) this copyright notice and license
 * appear on all copies of the software; and ii) Licensee does not utilize
 * the software in a manner which is disparaging to Sun.
 *
 * This software is provided "AS IS," without a warranty of any
 * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
 * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN
 * AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY
 * LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE
 * OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
 * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
 * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
 * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF
 * OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGES.
 *
 * This software is not designed or intended for use in on-line
 * control of aircraft, air traffic, aircraft navigation or aircraft
 * communications; or in the design, construction, operation or
 * maintenance of any nuclear facility. Licensee represents and warrants
 * that it will not use or redistribute the Software for such purposes.
 */

import java.util.Hashtable;
import java.util.Date;

import javax.naming.*;
import javax.naming.directory.*;
/*
 * Modify the RDN (relative distinguished name) of an entry.  In this
 * example, we change the dn "cn=Jacques Smith, o=Ace Industry, c=US"
 * to "cn=Jacques M Smith, o=Ace Industry, c=US".
 *
 * Since it is an error to either (1) attempt to modrdn an entry which
 * does not exist, or (2) modrdn an entry where the destination name
 * already exists, we take some steps, for this example, to make sure
 * we'll succeed.  We (1) add "cn=Jacques Smith" (if the entry exists,
 * we just ignore the error, and (2) delete "cn=Jacques M Smith" (if the
 * entry doesn't exist, we ignore the error).
 *
 * After renaming, we add back the attribute "Jacques Smith" into the cn
 * attribute.
 *
 * [based on modrdn.c of Netscape  SDK]
 */
class Modrdn {
public static void main(String[] args) {
    /* Values we'll use in creating the entry */
    Attribute objClasses = new BasicAttribute("objectclass");
    objClasses.add("top");
    objClasses.add("person");
    objClasses.add("organizationalPerson");
    objClasses.add("inetOrgPerson");
    Attribute cn = new BasicAttribute("cn", "Jacques Smith");
    Attribute sn = new BasicAttribute("sn", "Smith");
    Attribute givenNames = new BasicAttribute("givenname", "Jacques");
    /* Specify the DN we're adding */
    String dn = "cn=Jacques Smith, " + Env.MY_MODBASE;
    /* the destination DN */
    String ndn = "cn=Jacques M Smith, " + Env.MY_MODBASE;
    /* the new RDN */
    String nrdn = "cn=Jacques M Smith";
    Hashtable env = new Hashtable(5, 0.75f);
    /*
     * Specify the initial context implementation to use.
     * This could also be set by using the -D option to the java program.
     * For example,
     *   java -Djava.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory \
     *       Modrdn
     */
    env.put(Context.INITIAL_CONTEXT_FACTORY, Env.INITCTX);
    /* Specify host and port to use for directory service */
    env.put(Context.PROVIDER_URL, Env.MY_SERVICE);
    /* specify authentication information */
    env.put(Context.SECURITY_AUTHENTICATION, "simple");
    env.put(Context.SECURITY_PRINCIPAL, Env.MGR_DN);
    env.put(Context.SECURITY_CREDENTIALS, Env.MGR_PW);
    DirContext ctx = null;
    try {
        /* get a handle to an Initial DirContext */
        ctx = new InitialDirContext(env);
        Attributes orig = new BasicAttributes();
        orig.put(objClasses);
        orig.put(cn);
        orig.put(sn);
        orig.put(givenNames);
        /* Add the entry */
        ctx.createSubcontext(dn, orig);
        System.out.println( "Added entry " + dn + ".");
    } catch (NameAlreadyBoundException e) {
        /* If entry exists already, fine.  Ignore this error. */
        System.out.println("Entry " + dn + " already exists, no need to add");
    } catch (NamingException e) {
        System.err.println("Modrdn: problem adding entry." + e);
        System.exit(1);
    }
    try {
        /* Delete the destination entry, for this example */
        ctx.destroySubcontext(ndn);
        System.out.println( "Deleted entry " + ndn + "." );
    } catch (NameNotFoundException e) {
        /* If entry does not exist, fine.  Ignore this error. */
        System.out.println( "Entry " + ndn + " is not in the directory.  " +
                    "No need to delete.");
    } catch (NamingException e) {
        System.err.println("Modrdn: problem deleting entry." + e);
        System.exit(1);
    }

    /* Do the modrdn operation */
    try {
        ctx.rename(dn, ndn);
        System.out.println("The modrdn operation was successful.  Entry " +
                           dn + " has been changed to " + ndn + ".");
    } catch (NamingException e) {
        System.err.println("Modify operation failed." + e);
    }
}
}

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


CONTENTS | PREV | NEXT JNDI API

Appendix 1:
JNDI Standard Environment Properties

JNDI Environment Properties 1

Environment Configuration

java.naming.applet

(Context.APPLET)

An instance of java.applet.Applet whose applet parameters are used to obtain some environment properties.
See Chapter 6 for details. No default.

Program Configuration 2

java.naming.factory.initial

(Context.INITIAL_CONTEXT_FACTORY)

Class name of initial context factory to use.

See InitialContext .

No default.

java.naming.factory.object

(Context.OBJECT_FACTORIES)

Colon-separated list of class names of object factory classes to use.

See NamingManager.getObjectInstance() and DirectoryManager.getObjectInstance() .

Defaults to empty list.

java.naming.factory.state

(Context.STATE_FACTORIES)

Colon-separated list of class names of state factory classes to use.

See NamingManager.getStateToBind() and DirectoryManager.getStateToBind() .

Defaults to empty list.

java.naming.factory.control

(LdapContext.CONTROL_FACTORIES)

Colon-separated list of class names of response control factory classes to use.

See ControlFactory.getControlInstance() .

Defaults to empty list.

java.naming.factory.url.pkgs

(Context.URL_PKG_PREFIXES)

Colon-separated list of package prefixes to use when loading in URL context factories. com.sun.jndi.url is always added to end of list.

See NamingManager.getURLContext() .

Defaults to empty list.

Access Configuration 3

java.naming.provider.url

(Context.PROVIDER_URL)

Specifies configuration information for provider to use.

Defaults to provider default, using provider's own configuration or discovery protocols.

java.naming.dns.url

(Context.DNS_URL)

Specifies the DNS host and domain names.

No default.

Service-Related

java.naming.authoritative

(Context.AUTHORITATIVE)

Specifies the authoritativeness of the service requested. If "true", specifies most authoritative source is to be used (e.g., bypass any caches, or bypass replicas in some systems). Otherwise, source need not be (but can be) authoritative.

Defaults to "false".

java.naming.batchsize

(Context.BATCHSIZE)

Specifies the preferred batch size to use when returning data via the service's protocol. This is a hint to the provider to return the results of operations in batches of the specified size, so that the provider can optimize its performance and usage of resources. It does not affect the total number or size of the data returned.

Defaults to provider default.

java.naming.referral

(Context.REFERRAL)

Specifies that referrals encountered by the service provider are to be followed automatically. If "follow", follow referrals automatically. If "ignore", ignore referrals encountered. If "throw", throw ReferralException when a referral is encountered.

Defaults to provider default.

Security

java.naming.security.protocol

(Context.SECURITY_PROTOCOL)

Security protocol to use for service.

Defaults to provider default.

java.naming.security.authentication

(Context.SECURITY_AUTHENTICATION)

Takes values "none", "simple", "strong", or a provider-specific string (e.g., "CRAM-MD5 DIGEST-MD5 EXTERNAL").

Defaults to provider default.

java.naming.security.principal

(Context.SECURITY_PRINCIPAL)

Identity of principal (e.g., user) for the authentication scheme.

Defaults to provider default.

java.naming.security.credentials

(Context.SECURITY_CREDENTIALS)

Principal's credentials for the authentication scheme.

The particular type of credentials is determined by the authentication scheme chosen. Examples of different types of credentials are passwords, keys, and certificates.

Defaults to provider default.

Internationalization

java.naming.language

(Context.LANGUAGE)

Specifies a colon-separated list of preferred language to use with this service (e.g., "en-US", "fr", "fr-CH", "ja-JP-kanji").

Languages are specified using tags defined in RFC 1766.

Defaults to provider default.

1. The Context and LdapContext interfaces define constants for these property names. The names of the constants are shown in parentheses below the property's string names.

2. These properties may be set in the Java runtime's system properties or in an applet's parameter list.

3. These properties may be set in the Java runtime's system properties or in an applet's parameter list.

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


CONTENTS | PREV | NEXT JNDI API

Appendix B:

Examples for LDAP Programmers

This appendix contains sample JNDI programs intended to help a developer familiar with the LDAP C API. Starting with sample programs from the Netscape Directory SDK for accessing and updating the directory using the LDAP C API, we show the equivalent way of doing the same thing for Java applications using JNDI.

B.1 Search the Directory

B.2 Read An Entry

B.3 Get Attributes

B.4 Compare An Attribute

B.5 Modify Attributes

B.6 Rename An Entry

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


CONTENTS | PREV | NEXT JNDI API

Java Naming and Directory Interface TM
Application Programming Interface

(JNDI API)

Please send comments to:

jndi@java.sun.com.

JNDI 1.2/JavaTM 2 Platform, Standard Edition, v 1.3
July 14, 1999
CONTENTS | PREV | NEXT

Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


JNDI Change History

JNDI 1.2: Changes Since JNDI 1.1

  • Added javax.naming.event package.
  • Added javax.naming.ldap package.
  • Added support for configuration using resource files. See Chapter 6 of the JNDI API document.

API-related Changes

  • Added NamingEnumeration.close() for cancelling or terminating enumerations.
  • Added ReferralException.getReferralContext(Hashtable env) and ReferralException.retryReferral() to allow creation and retry of referral context with different environment properties.
  • Clarified how context methods that accept Name argument should deal with CompositeName and non CompositeName arguments. Specifically, instances of CompositeName are treated as composite name, while all others are treated as compound name.
  • Added Context.getNameInNamespace() for retrieving the full name of a context within its own namespace.
  • Clarified definition of the class factory location of a Reference object. Specifically, the location is a codebase, which consists of a list space-separated URLs.
  • Added support for ordered multivalued attributes to Attribute and BasicAttribute .
  • Added BasicAttributes.equals() and BasicAttributes.hashCode() .
  • Redefined semantics of DirContext.getSchemaClassDefinition() so that it returns a context that contains the DirContext objects of class definitions, rather than returning one (arbitrary) class definition.
  • Added protected InitialContext / InitialDirContext constructors to allow lazy initialization. Useful for subclass implementations.

SPI-related Changes

  • Added StateFactory / NamingManager.getStateToBind() , analogous to ObjectFactory / NamingManager.getObjectInstance() , for transforming an object's state before the object is bound in the naming/directory service.
  • Added interfaces DirObjectFactory and DirStateFactory to better support service providers that implement the DirContext interface. Added DirectoryManager.getObjectInstance() and DirectoryManager.getStateToStore() to use these interfaces.
  • Refined definition of NamingManager.getObjectInstance() to not treat URL strings specially. Instead, the URL should be wrapped inside a Reference whose RefAddr type is "URL".
  • Made ResolveResult implement Serializable .
  • Defined a special form of Reference called a next naming system (nns) reference for supporting "dynamic federation". This reference has a RefAddr type of "nns" and a content consisting of the resolved object.
  • Added the string constant NamingManager.CPE which names a property set by NamingManager.getContinuationContext() / DirectoryManager.getContinuationContext() . The value of this property is an instance of CannotProceedException . This is useful to service providers that implement federation by chaining the CPEs.
  • Defined a convention for service providers to use when naming environment properties. See Section 6.1.

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


Legend for Class Diagram

In a class diagram, we visually distinguish the different kinds of Java entities, as follows:

The interface: A rounded rectangle

  1. The class: A rectangle
  2. The abstract class: A rectangle with an empty dot
  3. The final class: A rectangle with a black dot
  4. Classes with subclasses: A rectangle with a small black triangle on the lower right corner

Most of these elements are shown below. The class or interface being described in the current chapter is shaded grey (this is not applicable for package class diagrams). A solid line represents extends , while a dotted line represents implements .

Example class diagram

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


Programmer's Guide to the Java 2D API

CONTENTS | PREV | NEXT

CONTENTS | PREV | NEXT
Copyright ©1997-1999 Sun Microsystems, Inc. All Rights Reserved.


 [Top] [Prev] [Next] [Bottom]

1 Introduction

The JNDI SPI provides the means by which developers can write different naming and directory service providers and make them available so that the corresponding services are accessible from applications that use the JNDI API. A service provider is a set of modules that together satisfy JNDI API requests. In addition, because JNDI allows the use of names that span multiple namespaces, one service provider implementation may need to interact with another in order to complete an operation. The SPI provides methods that allow different provider implementations to cooperate to complete client JNDI operations.

This document describes the components of the SPI and explains how developers can build service providers for JNDI. It is assumed that the reader is familiar with the contents of the JNDI API document.

All service provider developers should read the "Security Considerations" section of the JNDI API document. It contains important issues that all developers using JNDI, especially those writing service providers, should consider.

1.1 Document Overview

There are several types of implementations that sit beneath the JNDI API. A service provider contains at a minimum a context implementation. A context implementation implements the Context interface or any of its subinterfaces, such as DirContext, EventContext, or LdapContext. The complexity of the implementation depends primarily on the complexity of the underlying service, and secondarily on the number of JNDI features that the implementation supports. Chapter 2 describes the details of building a context implementation.

A context implementation can be accessed in different ways. The most common way is to access it from the initial context. Chapter 3 describes two ways that a context implementation can be accessed from the initial context: via an initial context factory and a URL context factory.

The JNDI architecture defines components/implementations that can be used to augment the behavior of context implementations. This allows users and applications to customize the implementation. These components are supported through factories. JNDI defines three types of factories and provides SPI methods that make use of them. These factories are described in Chapter 4.

  • Object factories-For transforming data stored in naming/directory services into Java types more natural to the Java application.
  • State factories-For transforming objects of Java types natural to the program into formats suitable for storage into naming/directory services.
  • Response control factories-For narrowing LDAP v3 response controls received from LDAP servers into more user-friendly types.

1.2 Interface1 Overview

The JNDI SPI is contained in the javax.naming.spi package. The following sections provide an overview of the SPI. For more details on the SPI, see the corresponding javadoc.

The javax.naming.spi package

The information in this graphic is available in the API documentation.

1.2.1 NamingManager and DirectoryManager

The NamingManager class contains static methods that perform provider-related operations. For example, it contains methods to create instances of objects using Reference, to obtain an instance of the initial context using the java.naming.factory.initial property, and to install ObjectFactoryBuilder and InitialContextFactoryBuilder. The DirectoryManager class provides similar static methods for DirContext related operations.

1.2.2 Initial Contexts

InitialContextFactory is the interface for creating an initial context instance. See Section 3.1 for more details.

InitialContextFactoryBuilder is the interface for creating InitialContextFactory instances. See Section 3.3 for more details.

1.2.3 Object Factories

ObjectFactory is the interface for supporting creation of objects using information stored in the namespace. DirObjectFactory is a subinterface of ObjectFactory for use by context implementations that implement the DirContext interface. See Section 4.1 for more details.

ObjectFactoryBuilder is the interface for creating object factories. See Section 4.1.4 for more details.

1.2.4 State Factories

StateFactory is the interface for supporting converting objects into storable formats supported by the naming/directory service. DirStateFactory is a subinterface of StateFactory for use by context implementations that implement the DirContext interface. DirStateFactory.Result is a class for holding a pair of java.lang.Object and Attributes that is returned by DirStateFactory.getStateToBind(). See Section 4.2 for more details.

1.2.5 Federation Support

The Resolver interface defines a method for providers to implement that allows them to participate in a federation for supporting extended interfaces to Context. See "Resolving Through to Subinterfaces of Context" on page 10 for more details.

ResolveResult is the return value of calling Resolver.resolveToClass(). It contains the object to which resolution succeeded, and the remaining name yet to be resolved.

2 Building a Context Implementation

One of the basic tasks in building a service provider is to define a class that implements the Context interface or any of its subinterfaces. This class is called a context implementation. The following guidelines should be used for developing a context implementation.

2.1 Ownership of Parameters

In general, any object passed as a parameter to methods in the Context interface (or subinterfaces) and NamingManager/DirectoryManager utility methods is owned by the caller. In many cases, the parameter eventually reaches a context implementation. Because the caller owns the object, the context implementation is prohibited from modifying the object. Furthermore, the context implementation is allowed to maintain a pointer to the object only for the duration of the operation and not beyond. If a context implementation needs to save the information contained in a parameter beyond the duration of the operation, it should maintain its own copy.

For purposes of parameter ownership, an operation on a context instance is not considered to have completed while any referrals generated by that operation are still being followed, or if the operation returns a NamingEnumeration, while the enumeration is still in use.

2.2 Reentrancy

A context instance need not be reentrant. Two threads that need to access the same context instance concurrently should synchronize amongst themselves and provide the necessary locking.

However, different context instances must be safe for concurrent multithreaded access. That is, two threads each operating concurrently on their respective context instance should not need to synchronize their access. For example, even though two contexts might share the same resources (such as the same connection), it must be possible (and safe) for two separate threads to operate on each of those contexts without the threads having to do any explicit synchronization.

For purposes of concurrency control, an operation on a context instance is not considered to have completed while any referrals generated by that operation are still being followed, or if the operation returns a NamingEnumeration, while the enumeration is still in use.

2.3 Basic Support-Implementing the Context Interface(s)

The context implementation defines implementations for each of the methods in the Context interface or subinterfaces that the implementation supports.

If a method is not supported, it should throw OperationNotSupportedException.

For methods in the Context interface or subinterfaces that accept a name argument (either as a String or a Name), an empty name denotes the current context. For example, if an empty name is supplied to lookup(), that means to return a new instance of the current context. If an empty name is supplied to list(), that means to enumerate the names in the current context. If an empty name is supplied to getAttributes(), that means to retrieve the attributes associated with this context.

Appendix A contains an example context implementation that implements a flat, in-memory namespace.

2.4 Object Support

JNDI encourages providers to supply implementations of the Context and its subinterfaces that are natural and intuitive for the Java application programmer. For example, when looking up a printer name in the namespace, it is natural for the programmer to expect to get back a printer object on which to operate.

Context ctx = new InitialContext();
Printer prt = (Printer)ctx.lookup(somePrinterName);
prt.print(someStreamOfData);

Similarly, when storing an application's object into the underlying service, it is most portable and convenient if the application does not have to know about the underlying data representation.

However, what is bound in the underlying directory or naming services typically are not objects in the Java programming language but merely reference information which can be used to locate or access the actual object. This case is quite common, especially for Java applications accessing and sharing services in an existing installed base. The reference in effect acts as a "pointer" to the real object. In the printer example, what is actually bound might be information on how to access the printer (e.g., its protocol type, its server address). To enable this easy-to-use model for the application developer, the context implementation must do the transformation of the data to/from the underlying service into the appropriate objects in the Java programming language.

There are different ways to achieve this goal. One context implementation might have access to all the implementation classes of objects that a directory can return; another context implementation might have a special class loader for locating implementation classes for its objects. JNDI provides the Reference class as a standard way of representing references. Applications and context implementations are encouraged to use this class, rather than invent separate mechanisms on their own. However, this does not preclude context implementations from using their own mechanisms for achieving the same goal.

JNDI provides utilities for context implementations to use when reading/storing objects in the Java programming language in a format-independent way to the underlying service. This section describes these utilities. These utilities interact with components called object and state factories that do the actual transformations. These factories are described in Chapter 4.

2.4.1 Reading an Object

JNDI provides the following methods that context implementations should use to transform data read from the underlying service into objects in the Java programming language:

Object NamingManager.getObjectInstance(Object refInfo,
                                       Name name,
                                       Context nameCtx,
                                       Hashtable env)
    throws Exception;
Object DirectoryManager.getObjectInstance(Object refInfo,
                                          Name name,
                                          Context nameCtx,
                                          Hashtable env,
                                          Attributes attrs)
    throws Exception;
refInfo is the data (representing the object) read from the underlying service. name is the name of the object while nameCtx is the context in which to resolve name. The name/nameCtx pair can be used to obtain more information about the object than is available from refInfo. env is the environment of the context from which getObjectInstance() is being invoked. attrs is the collection of attributes read from the directory about the object, usually in the same request that was used to get refInfo. It might not be the complete collection of attributes if such was not requested.

The method in the NamingManager class should be used by context implementations that implement the Context interface, while the method in the DirectoryManager class should be used by context implementations that implement the DirContext interface.

When constructing objects to be returned for the following methods, the context implementation should call getObjectInstance(), or its own mechanism for generating objects from the bound information, if it wants this feature to be enabled in their contexts. (String overloads not shown.)

    javax.naming.Context.lookup(Name name)
    javax.naming.Context.lookupLink(Name name)
    javax.naming.Binding.getObject()
    javax.naming.directory.SearchResult.getObject()

For Binding and SearchResult, the context implementation should either pass an object that is the result of calling getObjectInstance() or its equivalent to the constructor, or override the default implementation of Binding and SearchResult so that their getObject() implementations call getObjectInstance() or its equivalent before returning.

Here is an example. Suppose printers are represented in the namespace using References. To turn a printer Reference into a live Printer object, the context implementation would use the NamingManager.getObjectInstance() method. In this way, the underlying service need not know anything specific about printers.

Object lookup(Name name) {
    ...
    Reference ref = <some printer reference looked up from naming service>;
    return NamingManager.getObjectInstance(ref, name, this, env);
}

In another example, suppose printers are represented in the directory as a collection of attributes. To turn a printer's directory entry into a live Printer object, the context implementation would use DirectoryManager.getObjectInstance().

Object lookup(Name name) {
    ...
    Attributes attrs = <read attributes from directory>;
    Reference ref = <construct reference from attributes>;
    return DirectoryManager.getObjectInstance(ref, name, this,
        env, attrs);
}

2.4.2 Storing an Object

JNDI provides the following methods that context implementations should use to transform an object before storing it in the underlying service:

Object NamingManager.getStateToBind(
                                    Object obj,
                                    Name name,
                                    Context nameCtx,
                                    Hashtable env)
    throws NamingException;
DirStateFactory.Result DirectoryManager.getStateToBind(
                                    Object obj,
                                    Name name,
                                    Context nameCtx,
                                    Hashtable env,
                                    Attributes attrs)
    throws NamingException;

obj is the object to be stored in the underlying service. name is the name of the object while nameCtx is the context in which to resolve name. The name/nameCtx pair can be used to obtain more information about the object than is available from obj. env is the environment of the context from which getStateToBind() is being invoked. attrs is the collection of attributes that is to be bound with the object. DirStateFactory.Result is a class that contains an object and a collection of attributes.

The method in the NamingManager class should be used by context implementations that implement the Context interface, while the method in the DirectoryManager class should be used by context implementations that implement the DirContext interface.

Before storing an object supplied by the application, the context implementation should call getStateToBind(), or its own mechanism for generating information to be bound, if it wants this feature to be enabled in their contexts. (String overloads not shown.)

javax.naming.Context.bind(Name name, Object o)
javax.naming.Context.rebind(Name name, Object o)
javax.naming.DirContext.bind(Name name, Object o, Attributes attrs)
javax.naming.DirContext.rebind(Name name, Object o, Attributes attrs)

Here's an example of how a Context implementation supports Context.bind:

// First do transformation
obj = NamingManager.getStateToBind(obj, name, ctx, env);

// Check for Referenceable
if (obj instanceof Referenceable) {
    obj = ((Referenceable)obj).getReference();
}

if (obj instanceof Reference) {
    // store as ref
} else if (obj instanceof Serializable) {
    // serialize
} else {
    ...
}

Here's an example of how a DirContext implementation supports DirContext.bind:

// First do transformation
DirStateFactory.Result res = DirectoryManager.getStateToBind(
    obj, name, ctx, env, inAttrs);

obj = res.getObject();
Attributes outAttrs = res.getAttributes();

// Check for Referenceable
if (obj instanceof Referenceable) {
    obj = ((Referenceable)obj).getReference();
}
if (obj instanceof Reference) {
    // store as ref and add outAttrs
} else if (obj instanceof Serializable) {
    // serialize and add outAttrs
} else if (obj instanceof DirContext) {
    // grab attributes and merge with outAttrs
} else {
    ...
}

As shown in these examples, a context implementation might be able to store different types of objects (Reference, Serializable, and DirContext). If the context implementation cannot store Referenceable objects directly and getStateToBind() returns such an object, the context implementation should subsequently call Referenceable.getReference() and store the resulting Reference instead.

If a context implementation can store different types of objects, it should follow this order for the following common types:

  • Reference
  • Serializable
  • DirContext

This order is recommended because it is most likely to capture the intent of the caller of the bind()/rebind() method. For example, a Reference is Serializable, so if you performed the Serializable check first, no Reference objects would ever be stored in the reference format (that is, they would all be serialized).

2.5 Federation Support

2.5.1 Names

When a context is given a string name argument, the name represents a composite name that may span multiple namespaces, or it may have only a single compound name component (which in turn may be made up of one or several atomic names) that belongs to a single namespace. The context implementation must determine which part of the name is to be resolved/processed in its context and pass the rest onto the next context. This may be done syntactically by examining the name, or dynamically by resolving the name.

When a context is given a Name argument, if it is an instance of CompositeName, then it will be treated as a composite name. Otherwise, it will be treated as a compound name that is implemented by the CompoundName class or some other compound name implementation.

2.5.2 Resolving Through a Context

A context participates in a federation by performing the resolution phase of all of the context operations. The lookup() method must always be supported. Support for other methods is optional, but if the context is to participate in a federation, then the resolution implicit in all operations must be supported.

Figure 1: Example of Resolving through Intermediate Contexts to Perform a bind().

Example of resolving through intermediate contexts to perform a bind()

For example, suppose a context does not support the bind() operation. When that context is being used as an intermediate context for bind(), it must perform the resolution part of that operation to enable the operation to continue to the next context. It should only throw OperationNotSupportedException if it is being asked to create a binding in its own context. Figure 1 shows an example of how the bind() operation is passed through intermediate contexts to be performed in the target context.

2.5.3 Resolving Through to Subinterfaces of Context

To invoke a DirContext method (such as getAttributes()), the application first obtains an initial DirContext, and then perform the operation on the DirContext.

DirContext ctx = new InitialDirContext();
Attributes attrs = ctx.getAttributes(someName);
From the context implementation's perspective, in order to retrieve the attributes, getAttributes() might need to traverse multiple naming systems. Some of these naming systems only support the Context interface, not the DirContext interface. These naming systems are being used as intermediaries for resolving towards the target context. The target context must support the DirContext interface. Figure 2 shows an example of this.

Figure 2: Example of Resolving Through Intermediate non-DirContexts

Example of resolving through intermediate non-DirContexts

In order for intermediate naming systems to participate in the federation for extensions of Context, they must implement the Resolver interface. The Resolver interface is used by the JNDI framework to resolve through intermediate contexts that do not support a particular subinterface of Context. It consists of two overloaded forms of the method resolveToClass(). This method is used to partially resolve a name, stopping at the first context that is an instance of the required subinterface. By providing support for this method and the resolution phase of all methods in the Context interface, a context implementation can act as an intermediate context for extensions (subinterfaces) of Context.

public interface Resolver {
    public ResolveResult resolveToClass(Name name, Class contextType)

        throws NamingException;
    public ResolveResult resolveToClass(String name,
                                       Class contextType)

        throws NamingException;
}

2.5.4 Naming System Boundaries

The resolution of a (multicomponent) composite name proceeds from one naming system to the next, with the resolution of the components that span each naming system typically handled by a corresponding context implementation. From a context implementation's point of view, it passes the components for which it is not responsible to the (context implementation of the) next naming system.

There are several ways in which the context implementation for the next naming system may be located. It may be done explicitly through the use of a junction, where a name in one naming system is bound to a context (or a Reference to a context) in the next naming system. For example, with the composite name "cn=fs,ou=eng/lib/xyz.zip", the LDAP name "cn=fs,ou=eng" might resolve to a file system context in which the name "lib/xyz.zip" could then be resolved.

Alternately, the next naming system may be located implicitly. For example, a context implementation may choose the next naming system based upon service-specific knowledge of the object that it has resolved. For example, with the composite name "ldap.wiz.com/cn=fs,ou=eng", the DNS name ldap.wiz.com might name a DNS entry. To get the next naming system beyond DNS, the DNS context implementation might construct a context using SRV resource records found in that entry, which in this case, happens to name an LDAP context. When the next naming system is located in this fashion, JNDI composite name separator is used to denote the boundary from one naming system to the next, and is referred to as the implicit next naming system pointer.

However the next naming system is located, the context implementation must hand the next naming system the remaining portion of the composite name to resolve.

2.5.5 Continuing an Operation in a Federation

In performing an operation on a name that spans multiple namespaces, a context in an intermediate naming system needs to pass the operation onto the next naming system. The context does this by first constructing a CannotProceedException containing information pinpointing how far it has proceeded. In so doing it sets the resolved object, resolved name, remaining name, and environment parts of the exception.2 (In the case of the Context.rename() method, it also sets the "resolved newname" part.)

It then obtains a continuation context from JNDI by passing the CannotProceedException to static method NamingManager.getContinuationContext()

public class NamingManager {
    public static Context getContinuationContext(
        CannotProceedException e) throws NamingException;
    ...
}

The information in the exception is used by getContinuationContext() to create the context instance in which to continue the operation.

To obtain a continuation context for the DirContext operations, use Directory-Manager.getContinuationDirContext().

public class DirectoryManager {
    public static getContinuationDirContext(
        CannotProceedException e) throws NamingException;
    ...
}

Upon receiving the continuation context, the operation should be continued using the remainder of the name that has not been resolved.

For example, when attempting to continue a bind() operation, the code in the context implementation might look as follows:

public void bind(Name name, Object obj) throws NamingException {
    ...
    try {
        internal_bind(name, obj);
        ...
    } catch (CannotProceedException e) {
        Context cctx = 			NamingManager.getContinuationContext(e);
        cctx.bind(e.getRemainingName(), obj);
    }
}

In this example, bind() depends on an internal method, internal_bind(), to carry out the actual work of the bind and to throw a CannotProceedException when it discovers that it is going beyond this naming system. The exception is then passed to getContinuationContext() in order to continue the operation. If the operation cannot be continued, the continuation context will throw the CannotProceedException to the caller of the original bind() operation.

2.5.6 "Dynamic" Location of Next Naming System

In some federation configurations, the result of resolution in one naming system does not indicate which is the next naming system. The only conclusion that the context implementation can draw is that resolution has terminated in the current naming system and should proceed to the next naming system.

For example, suppose the composite name "lib/xyz.zip/part1/abc" consists of two parts: "lib/xyz.zip", which names a file in ZIP format, and "part1/abc", which names an entry within the ZIP file. Although the resolution of "lib/xyz.zip" results in a file object, the desired result is a context in which to resolve names of ZIP entries. Similarly, another composite name could name an entry within a file in "tar" format, and the desired result of the resolution of the file component of the composite name would be a context in which to resolve tar entries.

In effect, any type of context might be federated beneath the file system namespace depending on the format of the files. Such relationships should be symmetric: it should be possible for the ZIP file context and other similar contexts to federate beneath other, non-file system namespaces. Furthermore, developers writing the file system context implementation and those writing the context implementations for the ZIP file context, the tar file context, or a context for some yet-to-be defined format, should be able to work independently.

To support this type of federation, JNDI defines a special form of Reference called an nns reference ("nns" stands for "next naming system"). This Reference has an address with type nns. The address contents is the resolved object (in the above example, the ZIP file). Continuing with the file system example, the file system context implementation might create the nns reference as follows:

 RefAddr addr = new RefAddr("nns") {
    public Object getContent() {
         return theFile;
    }
};
Reference ref = new Reference("java.io.File", addr);

Next, the context implementation constructs a CannotProceedException (as with the junction case) by using the nns reference as the resolved object, and a resolved name consisting of the resolved file name and an empty component. The empty component is being used as an implicit next naming system pointer and indicates that the resolution has succeeded to the point of resolving the next naming system. (Notice how the values of the resolved object and resolved name are matched.) The context impementation then passes the CannotProceedException to getContinuationContext().

As with any resolved object in a CannotProceedException, getContinuationContext() searches for a context implementation that accepts this nns reference. The ZIP file context implementation, for instance, might accept an nns reference and other information provided, such as the name of the file (relative to a given context). If the context implementation determines that the file is a ZIP file, it would then construct a context for resolving names within that file.

2.5.7 More about CannotProceedException

Central to the JNDI SPI's framework for federation is the CannotProceedException. A Cannot-ProceedException contains information such as the resolved name/object and remaining name, inherited from the NamingException superclass. In addition, a CannotProceedException also contains fields for the "alt" name and "alt" name context. While the resolved name from NamingException is the full composite name (relative to the starting context of the operation), alt name is the resolved name relative to the alt name context. That is, alt name might not necessarily be the same as the resolved name. Alt name and alt name context are used as arguments to NamingManager/DirectoryManager.getObjectInstance(). They allow the factories that are called by this method to obtain more information about the resolved object (for example, it could be used to get a special attribute about the object). These factories are described in Chapter 4.

2.5.8 Contextual Information

While the emphasis of the JNDI SPI framework is on "looking forward" and trying to find the next naming system, some context implementations, once located, need to "look back" the resolution chain to obtain contextual information. For example, a particular context implementation that is federated off of a host naming system might be designed such that the only means by which it can find out host information is to ask its (possibly not immediate) superior naming system. To do that, it needs contextual information-information about how the resolution proceeded to its current point.

Summarizing earlier discussions on federation, when performing an operation on a name that spans multiple namespaces, the context implementation first constructs a CannotProceed-Exception containing information pinpointing how far it has proceeded. It then obtains a continuation context from JNDI by calling getContinuationContext(). To support the retrieval of contextual information, getContinuationContext() automatically adds the environment property java.naming.spi.CannotProceedException, with the value of the Cannot-ProceedException argument, to the continuation context's environment. This property is inherited by the continuation context and may be used by that context's implementation to inspect the fields of the exception.

2.6 Referral Support

LDAP-style directory services support the notion of referrals for redirecting a client's request to another server. A referral differs from the federation continuation mechanism described earlier in that a referral may be presented to the JNDI client, who then decides whether to follow it, whereas a CannotProceedException should be returned to the client only when no further progress is possible. Another difference is that an individual context implementation offers the capability of continuing the operation using the referral (and itself determines the mechanism for doing so). In a federation, the mechanism of continuation is beyond the scope of individual context implementations: individual context implementations benefit from the common federation mechanism provided by the JNDI SPI framework.

A context implementation that supports referrals defines a subclass of ReferralException and provides implementations for its abstract methods. getReferralContext() returns a context at which to carry on the operation, and getReferralInfo() returns information on where the referral leads to, in a format appropriate to the context implementation.

The environment property java.naming.referral specifies how the context implementation should treat referrals. If the context implementation is asked to throw an exception when a referral is encountered, or if the context implementation encounters problems following a referral, it throws a ReferralException to the application. To continue the operation, the application re-invokes the method on the referral context using the same arguments it supplied to the original method. The following code sample shows how ReferralException may be used by an application:3

while (true) {
    try {
        bindings = ctx.listBindings(name);
        while (bindings.hasMore()) {
            b = (Binding) bindings.next();
            ...
        }
        break;
    } catch (ReferralException e) {
        ctx = e.getReferralContext();
    }
}

This convention of re-invoking the method using the original arguments is a simple one for applications to follow. This places the burden on the implementation of the ReferralException to supply enough information to the implementation of the referral context for the operation to be continued. Note that this will likely render some of the arguments passed to the re-invoked operation superfluous. The referral context implementation is free to ignore any redundant or unneeded information.

It is possible for an operation to return results in addition to a referral. For example, when searching a context, the server might return several results in addition to a few referrals as to where to obtain further results. These results and referrals might be interleaved at the protocol level. If referrals require user interaction (i.e., not followed automatically), the context implementation should return the results through the search enumeration first. When the results have been returned, the referral exception can then be thrown. This allows a simple programming model to be used when presenting the user with a clear relationship between a referral and its set of results.

2.7 Schema Support

JNDI defines the Attribute interface for representing an attribute in a directory. An attribute consists of an attribute identifier (a string) and a set of attribute values, which can be any object in the Java programming language. There are also methods defined in Attribute for obtaining the attribute's definition and syntax definition from the directory's schema.

public class Attribute {
    public DirContext getAttributeDefinition() throws NamingException;
    public DirContext getAttributeSyntaxDefinition()

        throws NamingException;
    ...
}

The utility class, BasicAttribute, does not provide useful implementations for these methods. A directory context implementation that has support for such schema information should provide implementations of Attribute that implement these two methods based on its schema mechanisms, perhaps by subclassing BasicAttribute and overriding these two methods. The context implementation should then return instances of these subclasses when asked to return instances of Attribute. The context implementation, when it receives an Attribute instance that do not have meaningful implementations of these two methods, should use reasonable defaults to determine the attribute's definition and syntax, using information such as the attribute values' class names or conventions used for the attribute identifier.

The DirContext interface contains schema-related methods:

public class DirContext {
    ...
    public DirContext getSchema(Name name) throws NamingException;
    public DirContext getSchema(String name) throws NamingException;

    public DirContext getSchemaClassDefinition(Name name)
        throws NamingException;
    public DirContext getSchemaClassDefinition(String name)
        throws NamingException;

}

getSchema() returns the schema tree for the named object, while getSchemaClassDefinition() returns a context containing schema class definitions for the named object. Some systems have just one global schema and, regardless of the value of the name argument, will return the same schema tree. Others support finer grained schema definitions, and may return different schema trees depending on which context is being examined.

2.8 Event Support

A context implementation supports event notification by providing implementation for the methods in the EventContext/EventDirContext interfaces. The event model advocated by these interfaces can be readily supported using a multithreaded model. When an application uses addNamingListener() to register a listener with a context, the context records the requests and takes action to collect information required to generate the events. When the context eventually receives information to generate the events, it fires the events to the listener. The thread that does the registration is typically different from the thread that runs the listener. The context implementation typically uses a thread that it has created and manages to run the listener method. When one event is dispatched to multiple listeners, the context implementation may choose to (and is generally encouraged) to execute the listener methods concurrently in separate threads.

The addNamingListener() methods accept an instance of NamingListener. The instance might implement one or more subinterfaces of NamingListener. If the listener implements more than one subinterface, the context implementation should try to conserve resources required to satisfy the registration. For example, an implementation might be able to submit a single request to the server that captures all of the requests of the subinterfaces.

Where possible, the context implementation should fire a NamingExceptionEvent to a listener if the context will be unable to fire further events and then automatically deregister the listener. For example, if the connection to the server is broken subsequent to the registration of the listener and no information will be available to fire events, the context should fire a NamingExceptionEvent to the listener.

2.9 Context Environment Support

Each instance of Context (or its subinterfaces) can have associated with it an environment which contains preferences expressed by the application of how it would like to access the services offered by the context. Examples of information found in an environment are security-related information that specify the user's credentials and desired level of security (none, simple, strong), and configuration information, such as the server to use. See Chapter 6 and Appendix A of the JNDI API document for more details about environment properties.

Environment properties are defined generically in order to ensure maximum portability. Individual service providers should map these generic properties to characteristics appropriate for their service. Properties that are not relevant to a provider should be recorded and silently ignored. The environment may also be used for storing service provider-specific properties or preferences, in which case their applicability across different providers is limited.

2.9.1 Property Naming Convention

See Section 6.1 in the JNDI API document for a description of how environment properties are named. Service provider-specific properties should have a prefix that reflects their uniqueness to the provider. A common practice is to use the package name of the service provider as the prefix. For example, since Sun's LDAP provider is primarily contained in the package com.sun.jndi.ldap, properties specific to Sun's LDAP provider have the prefix "com.sun.jndi.ldap.".

2.9.2 Initializing a Context's Environment

When creating an initial context (either using the constructors from InitialContext or its subclasses), the application can supply an environment as a parameter. The parameter is represented as a Hashtable or any of its subclasses (e.g., Properties). The JNDI class library augments the data from this parameter with data from other sources (see Chapter 6 in the JNDI API document) and passes this to the context implementation.

Like all other parameters, the environment parameter received by a context implementation is owned by the caller. The context implementation should make a copy of the environment parameter it gets or otherwise take steps to ensure that changes by the caller to the parameter would not affect what the context implementation sees and vice versa. Note also that if the environment parameter is a Properties instance, enumeration and Hashtable.get() on the parameter only examine the top-level properties (not any nested defaults). This is the expected behavior. The context implementation is not expected to retrieve or enumerate values in the Properties instance's nested defaults.

The JNDI library is responsible for merging properties from different sources, such as the environment parameter to the initial context, resource files, and, where appropriate, system properties and applet parameters (see the JNDI API document, Chapter 6). The context implementation typically just reads the property it needs from the environment which it was supplied. There is seldom a need for a context implementation to consult other sources.

2.9.3 Inheritance

The environment is inherited from parent to child as the context methods proceed from one context to the next. The entire environment of a context instance is inherited by the child context instances, regardless of whether certain properties within the environment are ignored by a particular context.

A context implementation must pass on the environment from one context instance to the next in order to implement this "inheritance" trait of environments. Within one context implementation it can do so by passing the environment as an argument to the Context constructor, or to the NamingManager/DirectoryManager.getObjectInstance() method for creating Context instances.

Across context implementations in a federation, this is supported by passing the environment as part of the CannotProceedException parameter of NamingManager.getContinuationContext()/DirectoryManager.getContinuationDirContext(), which in turn will use this environment when creating an instance of the context in which to continue the operation.

Inheritance can be implemented in any way as long as it preserves the semantics that each context has its own view of its environment. For example, a copy-on-write implementation could be used to defer copying of the environment until it is absolutely necessary.

2.9.4 Updates to the Environment

The environment of a context can be updated via the use of the addToEnvironment() and removeFromEnvironment() methods in the Context interface.

public interface Context {
    ...
    public Object addToEnvironment(String propName, Object propVal)
        throws NamingException;

    public Object removeFromEnvironment(String propName)
        throws NamingException;
}

These methods update the environment of this instance of Context. An environment property that is not relevant to the context implementation is silently ignored but maintained as part of the environment. The updated environment affects this instance of Context, and will be inherited by any new child Context instances, but does not affect any Context instances already in existence. A lookup of the empty name on a Context will return a new Context instance with an environment inherited as with any other child.

See Section 6.6 in the JNDI API document for details.

2.9.5 Provider Resource Files

Each service provider has an optional resource file that contains properties specific to that provider. The name of this resource is:

[prefix/]jndiprovider.properties
where prefix is the package name of the provider's context implementation(s), with each period (".") converted to a slash ("/"). For example, suppose a service provider defines a context implementation with class name com.sun.jndi.ldap.LdapCtx. The provider resource for this provider is named com/sun/jndi/ldap/jndiprovider.properties.

The JNDI class library will consult this file when it needs to determine the value of a property, as described in Section 6.5.2 in the JNDI API document.

When the service provider needs to determine the value of a property, it will generally take that value directly from the environment. The service provider may define provider-specific properties to be placed in its own provider resource file. In that case it needs to read them from its property resource file and merge them in a way consistent with the algorithm described in Section 6.5.2 in the JNDI API document.

2.10 Connection Management

For a context implementation that uses a client/server protocol, there is not necessarily a one-to-one mapping between a context and a connection between the client and the server. JNDI is a high-level API that does not deal directly with connections. It is the job of the context implementation to do any necessary connection management. Hence, a single connection may be shared by multiple context instances, and a context implementation is free to use its own algorithms to conserve connection and network usage. Thus, when a method is invoked on the context instance, the context implementation might need to do some connection management in addition to performing the requested operation.

The Context.close() and NamingEnumeration.close() methods can be used by applications to provide hints to the context implementation as to when to free connection-related resources. A context implementation may choose to (and is generally encouraged to) take other measures to garbage-collect and conserve its connection-related resources.

Some environment properties affect a context's connection. For example, if the application changes the security-related properties, the context implementation might need to modify or create a new connection using those updated properties. If the connection was being shared by other contexts prior to the change, the connection change should not affect contexts whose properties have not been updated.

3 The Initial Context

Since all naming methods are performed relative to a context, an application needs a starting context in order to invoke them. This starting context is referred to as the initial context. The bindings in the initial context are determined by policies set forth by the initial context implementation, perhaps using standard policies for naming global and enterprise-wide namespaces. For example, the initial context might contain a binding to the Internet DNS namespace, a binding to the enterprise-wide namespace, and a binding to a personal directory belonging to the user who is running the application.

An application obtains an initial context by making the following call:

Context ctx = new InitialContext();
An alternate constructor allows an environment to be passed as an argument. This allows the application to pass in preferences or security information to be used in the construction of the initial context.

Hashtable env = new Hashtable();4
env.put(Context.SECURITY_PRINCIPAL, "jsmith");
env.put(Context.SECURITY_CREDENTIALS, "xxxxxxx");
Context ctx = new InitialContext(env);

Subsequent to getting an initial context, the application can invoke Context methods.

Object obj = ctx.lookup("this/is/a/test");

The InitialContext class (and subclasses) selects an implementation using a default algorithm that can be overridden by installing an initial context factory builder (described below).

The InitialDirContext is an extension of InitialContext. It is used for performing directory operations using the initial context. The InitialLdapContext class is an extension of InitialDirContext. It is used for performing special LDAP v3 operations using the initial context. The algorithms and policies described in this section also apply to InitialDirContext and InitialLdapContext. Places where DirContext/LdapContext is required instead of Context have been noted.

3.1 The Initial Context Factory

An initial context factory is a class that creates an instance of a context that has been implemented following the guidelines outlined in Chapter 2. The factory is used by the InitialContext class (or subclass) constructor.

Given an environment, the factory returns an instance of Context (or its subinterfaces).

public interface InitialContextFactory {
    public Context getInitialContext(Hashtable env)

        throws NamingException;
}

Appendix A contains an example of an InitialContextFactory.

Once the context instance has been created, when a method is invoked on InitialContext by using a non-URL name (see below), the method is forwarded and invoked on that context instance.

JNDI selects the initial context implementation to use by using the property java.naming.factory.initial. This property contains the fully-qualified class name of an initial context factory. The class must implement the InitialContextFactory interface and have a public constructor that does not take any arguments. JNDI will load the initial context factory class and then invoke getInitialContext() on it to obtain a Context instance to be used as the initial context.

An application that wants to use a particular initial context must supply the java.naming.factory.initial property in the environment passed to the InitialContext (or subclass) constructors, or via resource files, system properties, or applet parameters.

3.1.1 Exceptions

When the property java.naming.factory.initial is set to a non-null value, the InitialContext (and subclass) constructors will try to load and instantiate an initial context factory, which will then create a context instance. If the factory or context cannot be created, for example as a result of an authentication problem, the initial context factory can throw an exception to indicate this problem. Note however that it is up to the context implementation when it verifies and indicates to users of the initial context any environment property- or connection- related problems. It can do so lazily-delaying until an operation is performed on the context, or eagerly, at the time the context is created.

If the property java.naming.factory.initial is not set, no attempt will be made to create an underlying context for the initial context. The initial context is still useful, for instance, for processing URL names, as described next.

3.2 URL Support

If a URL5 string is passed to the initial context, it will be resolved using the corresponding URL context implementation. This feature is supported by the InitialContext class (and subclasses) and is independent of the setting of the java.naming.factory.initial environment property.

This feature allows applications to use the initial context to reach any namespace for which a URL context implementation has been made available. For example, the following code lists an LDAP namespace from the initial context:

new InitialContext().list("ldap://lserver/ou=eng,o=wiz,c=us");

3.2.1 URL Context

A URL string has the following format:

scheme_id:opaque_string

For example, an LDAP URL string has the scheme id "ldap"; a file URL has the scheme id "file".

A URL context implementation is a class that implements the Context interface (and possibly some subinterfaces) and accepts name arguments that are URL strings of the scheme that it supports. For example, an LDAP URL context accepts "ldap" URL strings.

When a URL string name is passed to a URL context, the context methods that accept String treat the name as a URL with the syntax defined by the URL scheme. When a Name object in which the first component is a URL string name is passed to a URL context, the first component is treated as a URL string, and the rest is used for federation (that is, resolution of the first component will indicate which naming system to use to resolve the rest). The Name instance should be a CompositeName; otherwise, an InvalidNameException should be thrown.

Name arguments that are not URL strings, and URL strings with an inappropriate scheme id should be rejected with an InvalidNameException.

3.2.2 URL Context Factory

A URL context factory is a class (actually a special type object factory (see Section 4.1)) that creates an instance of a URL context for URLs of one or more schemes.

When the InitialContext class receives a URL string as a name argument, it will look for a URL context factory by using the following algorithm. The environment property java.naming.factory.url.pkgs contains a colon-separated list of package prefixes. The factory's class name is constructed by using the following rule:

package_prefix + "." + scheme_id + "." + scheme_id URLContextFactory

for each package prefix listed in the property. The default package prefix com.sun.jndi.url is appended to the end of the list.

For example, if the URL is "ldap://somehost:389" and java.naming.factory.url.pkgs contains "com.widget:com.wiz.jndi", the InitialContext class will attempt to locate the corresponding factory class by loading the following classes until one is successfully instantiated:

com.widget.ldap.ldapURLContextFactory
com.wiz.jndi.ldap.ldapURLContextFactory
com.sun.jndi.url.ldap.ldapURLContextFactory
The factory class implements the ObjectFactory interface (see "URL Context Factory" on page 31) and has a public constructor that takes no arguments. The InitialContext class passes the scheme id as the resolved object to the factory's getObjectInstance() method, which in turn creates a URL context for the URL scheme. The URL context will then be used to carry out the originally intended Context or DirContext operation on the URL supplied to InitialContext.

3.2.3 Service Provider's Responsibility

There is no requirement that a service provider supply a URL context factory and URL context implementation. It only does so if it wants to allow URL string names with its URL scheme to be accepted by the InitialContext class. A service provider, for instance, might just provide an initial context factory and a context implementation that is accessed through that factory.

3.3 Overriding the Default Behavior

The policy of creating an initial context factory using the java.naming.factory.initial environment property and URL support is built into the InitialContext class. There are two ways an application can override some or all of this policy.

3.3.1 Removing URL Support

If an application does not want URL strings to be treated specially, it can use the method NamingManager.getInitialContext(), which creates a context instance using the factory named in the java.naming.factory.initial environment property.

This method is also useful if the application needs to access interfaces implemented by the context created by the initial context factory, but which are not one of Context, DirContext, or LdapContext. Here is a code fragment that gets a context using NamingManager.getInitialContext() and then casts it to a subclass:

FooContext ctx = (FooContext) NamingManager.getInitialContext(env);
...
Object obj = ctx.lookup(name);
ctx.fooMethod1(...);
Note that installing an initial context factory builder (discussed next) affects the result of NamingManager.getInitialContext().

3.3.2 Removing All Policy

An initial context factory builder is a class that creates instances of initial context factories.

An application can install an initial context factory builder to define its own policy of how to locate and construct initial context implementations. When a builder has been installed, it is solely responsible for creating the initial context factories. None of the default policies (java.naming.factory.initial property or URL support) normally used by JNDI are employed.

An implementation of an initial context factory builder must implement the InitialContext-FactoryBuilder interface. Its createInitialContextFactory() method creates instances of InitialContextFactory.

After a builder has been installed. the application can get the initial context by either using the InitialContext/InitialDirContext/InitialLdapContext constructors, or by using NamingManager.getInitialContext(). When one of the constructors is used, its class is basically a wrapper around the underlying context implementation returned by NamingManager.getInitialContext().

3.4 Implementing a Subclass of InitialContext

When there is a need to provide an initial context that supports an interface that extends from Context, DirContext, or LdapContext, the service provider should supply a subclass of InitialContext (or InitialDirContext/InitialLdapContext).

3.4.1 URL Support

To add support for URLs in the same way InitialContext and InitialDirContext do, the subclass should use the protected methods available in InitialContext as follows. This only makes sense for interfaces that have methods that accept name argument.

For example, suppose FooContext is a subinterface of DirContext. Its initial context implementation would define getURLOrDefaultInitFooCtx() methods (for both Name and String parameters) that retrieve the real initial context to use.

public class InitialFooContext extends InitialDirContext {
    ...
    protected FooContext getURLOrDefaultInitFooCtx(Name name)
        throws NamingException {
        Context answer = getURLOrDefaultInitCtx(name);
        if (!(answer instanceof FooContext)) {
            throw new NoInitialContextException("Not a FooContext");
        }
        return (FooContext)answer;
    }
    // similar code for getURLOrDefaultInitFooCtx(String name)
}
When providing implementations for the new methods in the FooContext interface that accept a name argument, getURLOrDefaultInitFooCtx() is used in the following way.

    public Object FooMethod1(Name name, ...) throws NamingException {
        return getURLOrDefaultInitFooCtx(name).FooMethod1(name, ...);
    }

3.4.2 New Method Support

When providing implementations for the new methods in the FooContext interface that do not have a name argument, or for which URL support is not required, use InitialContext.getDefaultInitCtx().

protected FooContext getDefaultInitFooCtx() throws NamingException {
    Context answer = getDefaultInitCtx();
    if (!(answer instanceof FooContext)) {
        throw new NoInitialContextException("Not an FooContext");
    }
    return (FooContext)answer;
}
public Object FooMethod2(Args args) throws NamingException {
    return getDefaultInitFooCtx().FooMethod2(args);
}

3.4.3 Constructors

The implementation should provide appropriate constructors for the class. The constructor should call the appropriate constructor of the superclass. If the environment needs to be modified or examined prior to the superclass's constructor being called, it should use the protected constructor that accepts a boolean flag to control the initialization of the initial context, and then use the init() method to initialize the context. Here is an example:

public InitialFooContext(Hashtable environment, Object otherArg)
        throws NamingException {
    super(true); // don't initialize yet

    // Clone environment and adjust
    Hashtable env = (environment == null) ? new Hashtable(11) :
        (Hashtable)environment.clone();
    ...
    init(env);
}
Client programs that use this new initial context would look as follows.
import com.widget.jndi.InitialFooContext;
...
FooContext ctx = new InitialFooContext(env);
Object obj = ctx.lookup(name);
ctx.FooMethod1(name, ...);

4 Customizing A Context Implementation

JNDI allows a context implementation to be customized-by the application, the application's deployer or user, or the service provider-in how it reads and stores objects in the naming/directory service. A similar facility is also available for narrowing LDAP v3 control classes.

You can think of these facilities as modules that plug into a context implementation.

4.1 Reading Objects: Object Factories

JNDI provides a generic way of creating objects (including instances of Context) using information stored in the namespace. That information may be of arbitrary type (java.lang.Object). For example, it may be a Reference, or a URL, or any other data required to create the object. Turning such information stored in the namespace into an object is supported through the use of object factories. An object factory is a class that implements the ObjectFactory interface (or the DirObjectFactory subinterface):

    public interface ObjectFactory {
        public Object getObjectInstance(Object refObj,
                        Name name,
                        Context nameCtx,
                        Hashtable env)
            throws Exception;
    }
    public interface DirObjectFactory extends ObjectFactory {
        public Object getObjectInstance(Object refObj,
                        Name name,
                        Context nameCtx,
                        Hashtable env,
                        Attributes attrs)
            throws Exception;
    }

Given some reference information (refObj) about an object, optional information about the name of the object and where it is bound, and optionally some additional environment information (for example, some identity or authentication information about the user creating the object), the factory attempts to create an object represented by the reference information. For example, given reference information about a printer, a printer object factory might return an instance of Printer. In the case of an object factory that is to be used with a DirContext implementation, the factory is also given some attributes about the object. If the factory requires more attributes or information, it can obtain them directly from the naming/directory service by using the name/nameCtx arguments.

If the factory cannot created an object using the arguments supplied, it should return null. For example, when a printer object factory is given data about a disk drive, it should return null. The factory should only thrown an exception if no other object factories should be tried. Therefore, the factory should be careful about runtime exceptions that might be thrown from its implementation. For example, if a printer object factory is given data about a printer but the data is malformed in some way, it should throw an exception.

Object factories are used in several places in JNDI, basically to turn any reference information into an object. They are used in federation, URL processing in the initial context, and, as illustrated by the printer example, turning data into a form expected by the application.

4.1.1 Handling Structured References

A Reference contains methods for returning the class name and location of the object factory. The following methods are found in Reference.

public class Reference {
    ...
    public String 	getClassName();
    public String getFactoryClassName();
    public String getFactoryClassLocation();
}
If the object read from the directory/naming service is an instance of Reference or Referenceable, its corresponding object factory can be located using information in Reference. The getFactoryClassName() method retrieves the name of the factory class that implements the ObjectFactory interface. This factory must implement the ObjectFactory interface and have a public constructor that takes no arguments. getFactoryClassLocation() retrieves the codebase of the class implementation for the factory, which is a list of space-separated URLs.

JNDI creates the object by invoking getObjectInstance() on the ObjectFactory instance, by using the Reference and environment as arguments. The result is an instance of a class identified by getClassName().

Note that all the classes necessary to instantiate the object returned to the application are made available using mechanisms provided by JNDI. The application doesn't have to install the classes locally.

Figure 3: Example Using Reference to Get Back an Object From the Namespace

Example Using Reference to Get Back an Object From the Namespace

Returning to the printer example, suppose Printer is an interface for representing a printer and the BSDPrinter class is an implementation of that interface. BSDPrinter implements the Referenceable interface and uses the Reference class to store information on how to construct instances of BSDPrinter and address information for communicating with the print server. The Reference contains the class name of the object ("Printer"), the class name of the printer object factory ("PrinterFactory") and a URL for loading the factory's class implementation. Using the factory class name and implementation location, JNDI first loads the implementation of PrinterFactory and creates an instance of PrinterFactory. It then invokes getObjectInstance() on the factory to create an instance of Printer using the reference. For example, one address in the reference may have an address of type "bsd", and contains the print server's host name ("lobby-printserver"). The PrinterFactory instance uses the address type ("bsd") to decide to create a BSDPrinter instance and passes the address contents ("lobby-printserver") to its constructor. The resulting BSDPrinter object is returned as the result of lookup().

From the context implementation's point of view, all of this is done automatically by its invocation of NamingManager/DirectoryManager.getObjectInstance().

When the application invokes print() on the BSDPrinter instance returned by lookup(), the data is sent to the print server on the machine "lobby-printserver" for printing. The application need not know the details of the Reference stored in the namespace, the protocol used to perform the job, or whether the BSDPrinter class was defined locally or loaded over the network. The transformation of the information stored in the underlying service into an object that implements the Printer interface is done transparently through the cooperation of the service provider (which stores bindings of printer names to printer address information), the printer service provider (which provides the PrinterFactory and BSDPrinter classes), and the JNDI SPI framework (which ties the two together to return an object that the application can use directly).

A service provider for such an object must do the following:

  1. Define the class for the object (e.g., BSDPrinter) that implements Referenceable or is a subclass of Reference.
  2. Define the Reference and its reference addresses for the object.
  3. Define a factory class that implements ObjectFactory (e.g., PrinterFactory). This class's getObjectInstance() method will create an instance of the class from step 1 (e.g., BSDPrinter) when given the Reference from step 2.

4.1.2 Handling URL References

If a Reference contains an address of type "URL" but not the factory class name and location, or if the reference is an array of strings containing URLs, JNDI will use the URL context factory support described in Section 3.2 to locate the factory, and then pass the URL string in the address to the factory's getObjectInstance() method. See Section 4.1.6 for a description of how JNDI expects a URL context factory implementation to behave.

A service provider for such an object must do the following:

  1. Define the class for the object (e.g., BSDPrinter).
  2. Define the URL scheme for the object.
  3. Define a URL context factory class that implements ObjectFactory. This class's getObjectInstance() method will create an instance of the class from step 1 (e.g., BSDPrinter) when given the URL from step 2.

4.1.3 Handling Arbitrary References: The java.naming.factory.object Property

In addition to extracting factory information from References, or using URLs, JNDI also looks for object factories specified in the java.naming.factory.object property, which can be in the environment or the provider resource file (see Section 2.9.5). The property contains a colon-separated list of fully-qualified class names of object factories. Each class must implement the ObjectFactory interface and have a public constructor that takes no arguments. For each class in the list, JNDI attempts to load and instantiate the factory class, and to invoke the ObjectFactory/DirObjectFactory.getObjectInstance() method on it using the object and environment arguments supplied. If the creation is successful, the resulting object is returned; otherwise, JNDI uses the same procedure on the next class in the list until the list is exhausted or a factory returns a non-null result.

Figure 4: Example using java.naming.factory.object to Get Back an Object from the Namespace

Example using java.naming.factory.object to Get Back an Object from the Namespace

For the printer example, instead of using a Reference to represent a printer in the namespace, some other information is stored. When that information is later retrieved, the object factories specified java.naming.factory.object are tried in turn to attempt to turn that information into a Printer instance.

A service provider for such an object must do the following:

  1. Define the class for the object (e.g., BSDPrinter).
  2. Define the class for reference information for the object. This is the object that will be bound in the namespace. This need not be Reference. It can be anything that will be understood by its corresponding object factory (e.g., some string containing the server name "printer type=bsd; host=lobby-printserver").
  3. Define a factory class that implements ObjectFactory (e.g., PrinterFactory). This class's getObjectInstance() method will create an instance of the class from step 1 (e.g., BSDPrinter) when given an instance of the class from step 2 (e.g., "printer type=bsd; host=lobby-printserver").

The service provider should automatically convert between the actual object (e.g., BSDPrinter) and the reference information (step 2, e.g., "printer type=bsd; host=lobby-printserver") when binding or looking up the object.

An application that wants to use a particular factory for generating objects must include the factory's class name in its java.naming.factory.object environment property and make the factory's classes and object classes available.

4.1.4 Overriding the Default Behavior

An object factory builder is a class that creates instances of object factories.

An application can install an object factory builder to defining its own policy of how to locate and construct object factory implementations. When a builder has been installed, it is solely responsible for creating the object factories. None of the default policies (Reference, URL string, or java.naming.factory.object property) normally used by JNDI are employed.

Figure 5: Example using an Object Factory Builder to Get Back an Object from the Namespece

Example using an Object Factory Builder to Get Back an Object from the Namespece

A service provider for an object factory builder must do the following:

  1. Define object factories that implement ObjectFactory.
  2. Define a class that implements ObjectFactoryBuilder. This class's createObjectFactory() method will use the constructors for the ObjectFactory classes in step 1.

An application that wants to use this factory builder must first install it.

    NamingManager.setObjectFactoryBuilder(builder);

4.1.5 Context Factory

A context factory is an object factory that creates instances of Context. The implementation of these contexts for a particular naming or directory service is referred to as a context implementation. Context implementations are described in Chapter 2. Like any other object factory, a context factory can be obtained by using any of the three mechanisms described above: from a Reference, a URL scheme id, or listed in the java.naming.factory.object property.

4.1.6 URL Context Factory

A URL context factory is a special kind of context factory. It follows these rules when implementing ObjectFactory.getObjectInstance().

  • If refObj is null, create a context for resolving URLs of the scheme associated with this factory. The resulting context is not tied to a specific URL. For example, invoking
getObjectInstance(null, null, null, env)
    on an "ldap" URL context factory returns a context that can resolve LDAP URLs (e.g., "ldap://ldap.wiz.com/o=wiz,c=us" or "ldap://ldap.umich.edu/", ...).
  • If refObj is a URL string, create the object identified by the URL. For example, invoking
getObjectInstance("ldap://ldap.wiz.com/o=wiz,c=us", null, null, env);
    on an "ldap" URL context factory would return the object named by "o=wiz,c=us" on the LDAP server ldap.wiz.com. If this happens to name a context, it can then be used for resolving (relative) LDAP names (e.g., "cn=Jane Smith").
  • If refObj is an array of URL strings, the assumption is that the URLs are equivalent in terms of the context to which they refer. Verification of whether the URLs are, or need to be, equivalent is up to the context factory. The order of the URLs in the array is not significant. The object returned by getObjectInstance() is the same as that for the single URL case-it is an object (perhaps a context) named by the URLs.
  • If refObj is any other type, the behavior of getObjectInstance() is determined by the implementation.

    URL context factories are used by the InitialContext class when it is passed a URL to resolve. URL context factories are also used for creating objects in the Java programming language from URLs stored in the namespace (see Section 4.1.2).

4.2 Storing Objects: State Factories

JNDI provides a mechanism to transform an object into a form storable by the underlying context implementation. That form may be any arbitrary type acceptable to the underlying context implementation. For example, it may be a Reference, a URL, a Serializable object, or a set of attributes, or any other data acceptable by the underlying context implementation. Turning an arbitrary object into data that can be stored in the namespace is supported through the use of state factories. A state factory is a class that implements the StateFactory interface (or the DirStateFactory subinterface):

    public interface StateFactory {
        public Object getStateToBind(Object obj,
                         Name name,
                         Context nameCtx,
                         Hashtable env)
            throws NamingException;
    }

    public interface DirStateFactory {
        public DirStateFactory.Result getStateToBind(Object obj,
                                 Name name,
                                 Context nameCtx,
                                 Hashtable env,
                                 Attributes attrs)
            throws NamingException;
    }

Given an object (obj), optional information about the name of the object and where it is bound, and optionally some additional environment information (for example, some identity or authentication information about the user accessing the namespace), the factory attempts to create an object suitable for binding. Typically, the state factory is knowledgeable about the target naming/directory service and/or context implementation, and knows which data formats are acceptable. In the case of a state factory that is to be used with a DirContext implementation, the factory is also given some attributes that are to be stored with the object. If the factory require more information about the object, it can obtain them directly from the naming/directory service by using the name/nameCtx arguments. For example, a printer state factory for an LDAP directory might return a set of attributes that represent the printer.

If the factory cannot return any data using the arguments supplied, it should return null. For example, when a printer state factory is given a disk object, it should return null. The factory should only thrown an exception if no other state factories should be tried. Therefore, the factory should be careful about exceptions that might be thrown from its implementation. For example, if a printer state factory is given a printer object but perhaps contradictory attributes, it might throw an exception.

4.2.1 Input/Output Options

Ultimately, a factory's output formats are determined by the underlying naming/directory service. A context implementation for the CORBA Object Services (COS) naming service, for example, can only store CORBA object references into the service; a context implementation for LDAP can only store attributes, although there is a lot of flexibility in how to encode information within those attributes.

A service provider typically supplies a factory for each (common) type of input that it expects, and the application can augment that set with state factories of its own. For example, a service provider for COS naming might have a state factory for converting a Java Remote Method Invocation (RMI) object into a CORBA object reference. A user of that provider might add a state factory for converting a Microsoft COM object reference into a CORBA object reference.

4.2.2 Locating State Factories: The java.naming.factory.state Property

JNDI looks for state factories specified in the java.naming.factory.state property, which can be in the environment or the provider resource file (see Section 2.9.5). The property contains a colon-separated list of fully-qualified class names of state factories. Each class must implement the StateFactory interface and have a public constructor that takes no arguments. For each class in the list, JNDI attempts to load and instantiate the factory class, and to invoke the StateFactory/DirStateFactory.getStateToBind() method on it using the object, name, context, environment, and attributes arguments supplied. If the factory produces a non-null result, the result is returned; otherwise, JNDI uses the same procedure on the next class in the list until the list is exhausted or a factory returns a non-null result.

4.3 Narrowing LDAP v3 Controls: Response Control Factories

The LDAP v3 protocol allows response controls to accompany any response sent by the server. The control consists of an OID string identifier and a sequence of ASN.1 BER encoded bytes. In the absence of any external information or assistance, the context implementation can only return a plain implementation of the Control interface that returns the OID and bytes.

JNDI provides the following abstract class for dealing with response controls:

    public abstract javax.naming.ldap.ControlFactory {
    ...
    public static Control getControlInstance(Control ctl,
                        Context ctx,
                        Hashtable env)
        throws NamingException;
    public abstract Control getControlInstance(Control ctl)
        throws NamingException;
}
When a context implementation receives a response control, it invokes the static getControl-Instance() method to find a control factory that can narrow the control to one that has more user-friendly access methods. Such a control, for instance, can decode the ASN.1 BER bytes and provide access methods that return the information as Java types. If no such control factory can be found, the original response control is returned. Here is an example of a hypothetical Time-ResponseControl which decodes the time of day.

public class TimeResponseControl implements Control {
    long time;
    // Constructor used by ControlFactory
    public TimeResponseControl(String OID, byte[] berVal)
        throws NamingException {
        // check validity of OID
        time = // extract time from berVal
    };

    // Type-safe and User-friendly method
    public long getTime() {
        return time;
    }
    // Low-level methods
    public String getID() {
        return TIME_OID;
    }
    public byte[] getEncodedValue() {
        return // original berVal
    }
     ...
}
A control factory may be responsible for one or more controls. If the factory cannot return a control using the arguments supplied, it should return null. Typically, this involves just matching the control's OID against the list of OIDs supported by the factory. The factory should only thrown an exception if no other control factories should be tried. Therefore, the factory should be careful about exceptions that might be thrown from its implementation. For example, if a control factory is given a control with an OID that it supports, but the byte array has an encoding error, it should throw an exception.

Here is an example of a control factory:

public class VendorXControlFactory extends ControlFactory {
    public VendorXControlFactory () {
    }
    public Control getControlInstance(Control orig)
        throws NamingException {
        if (isOneOfMyControls(orig.getID())) {
             ...
            // determine which of ours it is and call its constructor
            return new TimeResponseControl(orig.getID(),
                                orig.getEncodedValue());
        }
        return null;  // not one of ours
    }
}

4.3.1 Locating Response Control Factories: The java.naming.factory.control Property

JNDI looks for response control factories specified in the java.naming.factory.control property, which can be in the environment or the provider resource file (see Section 2.9.5). The property contains a colon-separated list of fully-qualified class names of control factories. Each class must implement the ControlFactory interface and have a public constructor that takes no arguments. For each class in the list, JNDI attempts to load and instantiate the factory class, and to invoke the ControlFactory.getControlInstance() instance method on it using the control, context, and environment arguments supplied. If the factory produces a non-null result, the result is returned; otherwise, JNDI uses the same procedure on the next class in the list until the list is exhausted or a factory returns a non-null result.

4.4 Ownership of Parameters

Any object passed as a parameter to a method in a factory is owned by the caller. Therefore, the factory is prohibited from maintaining a pointer to the object beyond the duration of the operation or modifying the object. If the factory needs to save the information contained in a parameter beyond the duration of the operation, it should maintain its own copy.

4.5 Reentrancy

A factory instance should be reentrant. That is, it should be possible for multiple threads to invoke methods on a single instance of a factory concurrently.

[Top] [Prev] [Next] [Bottom]

1 See Appendix B for legend of class diagram.

2 The CannotProceedException may well have been thrown by one of the context's internal methods when it discovered that the name being processed is beyond the scope of its naming system. The process by which the exception is produced is dependent on the implementation of the context.

3 Note that this is code in the application. In "Continuing an Operation in a Federation", the code sample presented is code in the context implementation.

4 You can also use a subclass of Hashtable (e.g. Properties) for this.

5 The mention of "URL" in this document refers to a URL string as defined by RFC 1738 and its related RFCs. It is any string that conforms to the syntax described therein, and may not always have corresponding support in the java.net.URL class or Web browsers. The URL string is either passed as the String name parameter, or as the first component of the Name parameter.

jndi@java.sun.com
Copyright © 1999, Sun Microsystems, Inc. All rights reserved.


 [Top] [Prev] [Next] [Bottom]

Java Naming and Directory Interface TM
Service Provider Interface
(JNDI SPI)

Please send technical comments to

jndi@java.sun.com

Please send product and business questions to

jndi-business@java.sun.com.

JNDI 1.2/JavaTM 2 Platform, Standard Edition, v 1.3
July 14, 1999

[Top] [Prev] [Next] [Bottom]

Copyright © 1999, Sun Microsystems, Inc. All rights reserved.


 [Top] [Prev] [Next] [Bottom]

Appendix C: JNDI Change History

JNDI 1.2: JNDI Changes Since JNDI 1.1

  • Added javax.naming.event package.
  • Added javax.naming.ldap package.
  • Added support for configuration using resource files. See Chapter 6 of the JNDI API document.

API-related Changes

  • Added NamingEnumeration.close() for cancelling or terminating enumerations.
  • Added ReferralException.getReferralContext(Hashtable env) and ReferralException.retryReferral() to allow creation and retry of referral context with different environment properties.
  • Clarified how context methods that accept Name argument should deal with CompositeName and nonCompositeName arguments. Specifically, instances of CompositeName are treated as composite name, while al l others are treated as compound name.
  • Added Context.getNameInNamespace() for retrieving the full name of a context within its own namespace.
  • Clarified definition of the class factory location of a Reference object. Specifically, the location is a codebase, which consists of a list space-separated URLs.
  • Added support for ordered multivalued attributes to Attribute and BasicAttribute.
  • Added BasicAttributes.equals() and BasicAttributes.hashCode().
  • Redefined semantics of DirContext.getSchemaClassDefinition() so that it returns a context that contains the DirContext objects of class definitions, rather than returning one (arbitrary) class definition.
  • Added protected InitialContext/InitialDirContext constructors to allow lazy initialization. Useful for subclass implementations.

SPI-related Changes

  • Added StateFactory/NamingManager.getStateToBind(), analogous to ObjectFactory/NamingManager.getObjectInstance(), for transforming an object's state before the object is bound in the naming/directory service.
  • Added interfaces DirObjectFactory and DirStateFactory to better support service providers that implement the DirContext interface. Added DirectoryManager.getObjectInstance() and DirectoryManager.getStateToStore() to use these interfaces.
  • Refined definition of NamingManager.getObjectInstance() to not treat URL strings specially. Instead, the URL should be wrapped inside a Reference whose RefAddr type is "URL".
  • Made ResolveResult implement Serializable.
  • Defined a special form of Reference called a next naming system (nns) reference for supporting "dynamic federation". This reference has a RefAddr type of "nns" and a content consisting of the resolved object.
  • Added the string constant NamingManager.CPE which names a property set by NamingManager.getContinuationContext()/DirectoryManager.getContinuationContext(). The value of this property is an instance of CannotProceedException. This is useful to service providers that implement federation by chaining the CPEs.
  • Defined a convention for service providers to use when naming environment properties. See Section 6.1.

[Top] [Prev] [Next] [Bottom]

jndi@java.sun.com
Copyright © 1999, Sun Microsystems, Inc. All rights reserved.


 [Top] [Prev] [Next] [Bottom]

Appendix B: Legend for Class Diagram

In a class diagram, we visually distinguish the different kinds of Java entities, as follows:

  1. The interface: A rounded rectangle
  2. The class: A rectangle
  3. The abstract class: A rectangle with an empty dot
  4. The final class: A rectangle with a black dot
  5. Classes with subclasses: A rectangle with a small black triangle on the lower right corner

    Most of these elements are shown below. The class or interface being described in the current chapter is shaded grey (this is not applicable for package class diagrams). A solid line represents extends, while a dotted line represents implements.

    Example class diagram

[Top] [Prev] [Next] [Bottom]

jndi@java.sun.com
Copyright © 1999, Sun Microsystems, Inc. All rights reserved.


 [Top] [Prev] [Next] [Bottom]

Appendix A: Service Provider Example

This appendix contains a simple service provider. It implements a flat namespace (with no federation support). It shows how to produce a context implementation by providing all the methods in the Context interface.

An instance of this context is bound directly as the initial context. This example provides the corresponding InitialContextFactory definition.

A.1 Simple Flat Context

A.1.1 Context Implementation

/*
 * @(#)FlatCtx.java	1.3 99/07/26
 *
 * Copyright 1997, 1998, 1999 Sun Microsystems, Inc. All Rights
 * Reserved.
 *
 * Sun grants you ("Licensee") a non-exclusive, royalty free,
 * license to use, modify and redistribute this software in source and
 * binary code form, provided that i) this copyright notice and license
 * appear on all copies of the software; and ii) Licensee does not
 * utilize the software in a manner which is disparaging to Sun.
 *
 * This software is provided "AS IS," without a warranty of any
 * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
 * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE
 * HEREBY EXCLUDED.  SUN AND ITS LICENSORS SHALL NOT BE LIABLE
 * FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING,
 * MODIFYING OR DISTRIBUTING THE SOFTWARE OR ITS DERIVATIVES. IN
 * NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST
 * REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
 * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER
 * CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT
 * OF THE USE OF OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS
 * BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
 *
 * This software is not designed or intended for use in on-line
 * control of aircraft, air traffic, aircraft navigation or aircraft
 * communications; or in the design, construction, operation or
 * maintenance of any nuclear facility. Licensee represents and warrants
 * that it will not use or redistribute the Software for such purposes.
 */
package examples.spi.flat;

import javax.naming.*;
import java.util.*;

/**
 * A sample service provider that implements a flat namespace in memory.
 */

class FlatCtx implements Context {
    Hashtable myEnv;
    private Hashtable bindings = new Hashtable(11);
    static NameParser myParser = new FlatNameParser();

    FlatCtx(Hashtable environment) {
        myEnv = (environment != null)
        ? (Hashtable)(environment.clone())
        : null;
    }

    public Object lookup(String name) throws NamingException {
        if (name.equals("")) {
            // Asking to look up this context itself.  Create and return
            // a new instance with its own independent environment.
            return (new FlatCtx(myEnv));
        }
        Object answer = bindings.get(name);
        if (answer == null) {
            throw new NameNotFoundException(name + " not found");
        }
        return answer;
    }

    public Object lookup(Name name) throws NamingException {
        // Flat namespace; no federation; just call string version
        return lookup(name.toString());
    }

    public void bind(String name, Object obj) throws NamingException {
        if (name.equals("")) {
            throw new InvalidNameException("Cannot bind empty name");
        }
        if (bindings.get(name) != null) {
            throw new NameAlreadyBoundException(
                    "Use rebind to override");
        }
        bindings.put(name, obj);
    }

    public void bind(Name name, Object obj) throws NamingException {
        // Flat namespace; no federation; just call string version
        bind(name.toString(), obj);
    }

    public void rebind(String name, Object obj) throws NamingException {
        if (name.equals("")) {
            throw new InvalidNameException("Cannot bind empty name");
        }
        bindings.put(name, obj);
    }

    public void rebind(Name name, Object obj) throws NamingException {
        // Flat namespace; no federation; just call string version
        rebind(name.toString(), obj);
    }

    public void unbind(String name) throws NamingException {
        if (name.equals("")) {
            throw new InvalidNameException("Cannot unbind empty name");
        }
        bindings.remove(name);
    }

    public void unbind(Name name) throws NamingException {
        // Flat namespace; no federation; just call string version
        unbind(name.toString());
    }

    public void rename(String oldname, String newname)
            throws NamingException {
        if (oldname.equals("") || newname.equals("")) {
            throw new InvalidNameException("Cannot rename empty name");
        }

        // Check if new name exists
        if (bindings.get(newname) != null) {
            throw new NameAlreadyBoundException(newname +
                                                " is already bound");
        }

        // Check if old name is bound
        Object oldBinding = bindings.remove(oldname);
        if (oldBinding == null) {
            throw new NameNotFoundException(oldname + " not bound");
        }

        bindings.put(newname, oldBinding);
    }

    public void rename(Name oldname, Name newname)
            throws NamingException {
        // Flat namespace; no federation; just call string version
        rename(oldname.toString(), newname.toString());
    }

    public NamingEnumeration list(String name)
            throws NamingException {
        if (name.equals("")) {
            // listing this context
            return new FlatNames(bindings.keys());
        }

        // Perhaps `name' names a context
        Object target = lookup(name);
        if (target instanceof Context) {
            return ((Context)target).list("");
        }
        throw new NotContextException(name + " cannot be listed");
    }

    public NamingEnumeration list(Name name)
            throws NamingException {
        // Flat namespace; no federation; just call string version
        return list(name.toString());
    }

    public NamingEnumeration listBindings(String name)
            throws NamingException {
        if (name.equals("")) {
            // listing this context
            return new FlatBindings(bindings.keys());
        }

        // Perhaps `name' names a context
        Object target = lookup(name);
        if (target instanceof Context) {
            return ((Context)target).listBindings("");
        }
        throw new NotContextException(name + " cannot be listed");
    }

    public NamingEnumeration listBindings(Name name)
            throws NamingException {
        // Flat namespace; no federation; just call string version
        return listBindings(name.toString());
    }

    public void destroySubcontext(String name) throws NamingException {
        throw new OperationNotSupportedException(
                "FlatCtx does not support subcontexts");
    }

    public void destroySubcontext(Name name) throws NamingException {
        // Flat namespace; no federation; just call string version
        destroySubcontext(name.toString());
    }

    public Context createSubcontext(String name)
            throws NamingException {
        throw new OperationNotSupportedException(
                "FlatCtx does not support subcontexts");
    }

    public Context createSubcontext(Name name) throws NamingException {
        // Flat namespace; no federation; just call string version
        return createSubcontext(name.toString());
    }

    public Object lookupLink(String name) throws NamingException {
        // This flat context does not treat links specially
        return lookup(name);
    }

    public Object lookupLink(Name name) throws NamingException {
        // Flat namespace; no federation; just call string version
        return lookupLink(name.toString());
    }

    public NameParser getNameParser(String name)
            throws NamingException {
        return myParser;
    }

    public NameParser getNameParser(Name name) throws NamingException {
        // Flat namespace; no federation; just call string version
        return getNameParser(name.toString());
    }

    public String composeName(String name, String prefix)
            throws NamingException {
        Name result = composeName(new CompositeName(name),
                                  new CompositeName(prefix));
        return result.toString();
    }

    public Name composeName(Name name, Name prefix)
            throws NamingException {
        Name result = (Name)(prefix.clone());
        result.addAll(name);
        return result;
    }

    public Object addToEnvironment(String propName, Object propVal)
            throws NamingException {
        if (myEnv == null) {
            myEnv = new Hashtable(5, 0.75f);
    }
    return myEnv.put(propName, propVal);
    }

    public Object removeFromEnvironment(String propName)
            throws NamingException {
        if (myEnv == null)
            return null;

    return myEnv.remove(propName);
    }

    public Hashtable getEnvironment() throws NamingException {
    if (myEnv == null) {
        // Must return non-null
        return new Hashtable(3, 0.75f);
    } else {
            return (Hashtable)myEnv.clone();
    }
    }

    public String getNameInNamespace() throws NamingException {
    return "";
    }

    public void close() throws NamingException {
    myEnv = null;
    bindings = null;
    }

    // Class for enumerating name/class pairs
    class FlatNames implements NamingEnumeration {
        Enumeration names;

        FlatNames (Enumeration names) {
            this.names = names;
        }

        public boolean hasMoreElements() {
            return names.hasMoreElements();
        }

        public boolean hasMore() throws NamingException {
            return hasMoreElements();
        }

        public Object nextElement() {
            String name = (String)names.nextElement();
            String className = bindings.get(name).getClass().getName();
            return new NameClassPair(name, className);
        }

        public Object next() throws NamingException {
            return nextElement();
        }
    public void close() {
    }
    }

    // Class for enumerating bindings
    class FlatBindings implements NamingEnumeration {
        Enumeration names;

        FlatBindings (Enumeration names) {
            this.names = names;
        }

        public boolean hasMoreElements() {
            return names.hasMoreElements();
        }

        public boolean hasMore() throws NamingException {
            return hasMoreElements();
        }

        public Object nextElement() {
            String name = (String)names.nextElement();
            return new Binding(name, bindings.get(name));
        }

        public Object next() throws NamingException {
            return nextElement();
        }
    public void close() {
    }
    }
};

A.1.2 Name Parser

/*
 * @(#)FlatNameParser.java	1.3 99/07/26
 *
 * Copyright 1997, 1998, 1999 Sun Microsystems, Inc. All Rights
 * Reserved.
 *
 * Sun grants you ("Licensee") a non-exclusive, royalty free,
 * license to use, modify and redistribute this software in source and
 * binary code form, provided that i) this copyright notice and license
 * appear on all copies of the software; and ii) Licensee does not
 * utilize the software in a manner which is disparaging to Sun.
 *
 * This software is provided "AS IS," without a warranty of any
 * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
 * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE
 * HEREBY EXCLUDED.  SUN AND ITS LICENSORS SHALL NOT BE LIABLE
 * FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING,
 * MODIFYING OR DISTRIBUTING THE SOFTWARE OR ITS DERIVATIVES. IN
 * NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST
 * REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
 * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER
 * CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT
 * OF THE USE OF OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS
 * BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
 *
 * This software is not designed or intended for use in on-line
 * control of aircraft, air traffic, aircraft navigation or aircraft
 * communications; or in the design, construction, operation or
 * maintenance of any nuclear facility. Licensee represents and warrants
 * that it will not use or redistribute the Software for such purposes.
 */
package examples.spi.flat;

import javax.naming.NameParser;
import javax.naming.Name;
import javax.naming.CompoundName;
import javax.naming.NamingException;
import java.util.Properties;

class FlatNameParser implements NameParser {

    static Properties syntax = new Properties();
    static {
        syntax.put("jndi.syntax.direction", "flat");
        syntax.put("jndi.syntax.ignorecase", "false");
    }
    public Name parse(String name) throws NamingException {
        return new CompoundName(name, syntax);
    }
}

A.1.3 Initial Context Factory

/*
 * @(#)FlatInitCtxFactory.java	1.3 99/07/26
 *
 * Copyright 1997, 1998, 1999 Sun Microsystems, Inc. All Rights
 * Reserved.
 *
 * Sun grants you ("Licensee") a non-exclusive, royalty free,
 * license to use, modify and redistribute this software in source and
 * binary code form, provided that i) this copyright notice and license
 * appear on all copies of the software; and ii) Licensee does not
 * utilize the software in a manner which is disparaging to Sun.
 *
 * This software is provided "AS IS," without a warranty of any
 * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
 * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE
 * HEREBY EXCLUDED.  SUN AND ITS LICENSORS SHALL NOT BE LIABLE
 * FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING,
 * MODIFYING OR DISTRIBUTING THE SOFTWARE OR ITS DERIVATIVES. IN
 * NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST
 * REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
 * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER
 * CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT
 * OF THE USE OF OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS
 * BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
 *
 * This software is not designed or intended for use in on-line
 * control of aircraft, air traffic, aircraft navigation or aircraft
 * communications; or in the design, construction, operation or
 * maintenance of any nuclear facility. Licensee represents and warrants
 * that it will not use or redistribute the Software for such purposes.
 */
package examples.spi.flat;

import java.util.Hashtable;
import javax.naming.Context;
import javax.naming.spi.InitialContextFactory;

public class FlatInitCtxFactory implements InitialContextFactory {

    public Context getInitialContext(Hashtable env) {
        return new FlatCtx(env);
    }
}

[Top] [Prev] [Next] [Bottom]

jndi@java.sun.com
Copyright © 1999, Sun Microsystems, Inc. All rights reserved.


JNI - Java Native Interface

Java

Java Native Interface

 Documentation Contents
JavaTM Native Interface (JNI) is a standard programming interface for writing Java native methods and embedding the JavaTM virtual machine* into native applications. The primary goal is binary compatibility of native method libraries across all Java virtual machine implementations on a given platform.

JNI 6.0 API Specification

  • Java Native Interface 6.0 Specification

    This brief specification describes how the AWT package is designed to use JNI mechanisms to display objects on Solaris, Linux and Windows platforms.

JNI API Enhancements

  • JNI FAQ
  • A shared stub is a single JNI native method that can dispatch to many C functions. You can download the complete example from here:
    • For Windows, download jnistb10.zip (38K)
    • For Solaris, download either jnistb10.tar.Z (60K) or jnistb10.tar.gz (27K).

    More Information

    • For JNI FAQs and information about the book The Java Native Interface: Programmer's Guide and Specification, see this document on the Java Software website: Java Native Interface Tips

    *As used on this web site, the terms "Java virtual machine" or "JVM" refers to a virtual machine for the Java platform.

    Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

    Please send comments to: jni@java.sun.com     		Sun


JNI Enhancements in the Java 2 SDK

Java

JNI Enhancements
Introduced in Version 1.4
of the JavaTM 2 SDK

 JNI Documentation

JNI has been enhanced in v 1.4 with support for the java.nio package as well as a new entry point in the JNI Invocation Interface. Also, the JNI version number has been incremented and the description of JNI_OnLoad updated accordingly.

The new Invocation Interface routine allows native code to attach a daemon thread to the Java virtual machine (JVM); this is useful when the JVM should not wait for this thread to exit upon shutdown.

  • AttachCurrentThreadAsDaemon

The NIO-related entry points allow native code to access java.nio direct buffers. The contents of a direct buffer can, potentially, reside in native memory outside of the ordinary garbage-collected heap. For information about direct buffers, please see New I/O APIs and the specification of the java.nio.ByteBuffer class.

Three new functions allow JNI code to create, examine, and manipulate direct buffers:
  • NewDirectByteBuffer
  • GetDirectBufferAddress
  • GetDirectBufferCapacity

Every implementation of the Java virtual machine must support these functions, but not every implementation is required to support JNI access to direct buffers. If a JVM does not support such access then the NewDirectByteBuffer and GetDirectBufferAddress functions must always return NULL, and the GetDirectBufferCapacity function must always return -1. If a JVM does support such access then these three functions must be implemented to return the appropriate values.

Incremented Version Number

The JNI version number has been incremented. The include file jni.h defines the new constant:

    #define JNI_VERSION_1_4 0x00010004

The GetVersion procedure now returns this value, and the specification of the JNI_OnLoad procedure has been revised:

    jint JNI_OnLoad(JavaVM *vm, void *reserved);

      The VM calls JNI_OnLoad when the native library is loaded (for example,
      through System.loadLibrary).  JNI_OnLoad must return the JNI version
      needed by the native library.

      In order to use the JNI functions introduced in J2SE release 1.2 in
      addition to those that were available in JDK 1.1, a native library must
      export a JNI_OnLoad function that returns JNI_VERSION_1_2.

      In order to use the JNI functions introduced in J2SE release 1.4 in
      addition to those that were available in release 1.2, a native library
      must export a JNI_OnLoad function that returns JNI_VERSION_1_4.

      If the native library does not export a JNI_OnLoad function, the VM
      assumes that the library only requires JNI version JNI_VERSION_1_1.  If
      the VM does not recognize the version number returned by JNI_OnLoad, the
      native library cannot be loaded.

Additions to the JNI Invocation Interface

AttachCurrentThreadAsDaemon

jint AttachCurrentThreadAsDaemon(JavaVM* vm, void** penv, void* args);

Same semantics as AttachCurrentThread, but the newly-created java.lang.Thread instance is a daemon.

If the thread has already been attached via either AttachCurrentThread or AttachCurrentThreadAsDaemon, this routine simply sets the value pointed to by penv to the JNIEnv of the current thread. In this case neither AttachCurrentThread nor this routine have any effect on the daemon status of the thread.

LINKAGE

Index 7 in the JavaVM interface function table.

PARAMETERS

vm: the virtual machine instance to which the current thread will be attached.

penv: a pointer to the location in which the JNIEnv interface pointer for the current thread will be placed.

args: a pointer to a JavaVMAttachArgs structure.

RETURNS

Returns zero on success; otherwise, returns a negative number.

EXCEPTIONS

None.

Additions to the JNI Interface

NewDirectByteBuffer

jobject NewDirectByteBuffer(JNIEnv* env, void* address, jlong capacity);

Allocates and returns a direct java.nio.ByteBuffer referring to the block of memory starting at the memory address address and extending capacity bytes.

Native code that calls this function and returns the resulting byte-buffer object to Java-level code should ensure that the buffer refers to a valid region of memory that is accessible for reading and, if appropriate, writing. An attempt to access an invalid memory location from Java code will either return an arbitrary value, have no visible effect, or cause an unspecified exception to be thrown.

LINKAGE

Index 229 in the JNIEnv interface function table.

PARAMETERS

env: the JNIEnv interface pointer

address: the starting address of the memory region (must not be NULL)

capacity: the size in bytes of the memory region (must be positive)

RETURNS

Returns a local reference to the newly-instantiated java.nio.ByteBuffer object. Returns NULL if an exception occurs, or if JNI access to direct buffers is not supported by this virtual machine.

EXCEPTIONS

OutOfMemoryError: if allocation of the ByteBuffer object fails

GetDirectBufferAddress

void* GetDirectBufferAddress(JNIEnv* env, jobject buf);

Fetches and returns the starting address of the memory region referenced by the given direct java.nio.Buffer.

This function allows native code to access the same memory region that is accessible to Java code via the buffer object.

LINKAGE

Index 230 in the JNIEnv interface function table.

PARAMETERS

env: the JNIEnv interface pointer

buf: a direct java.nio.Buffer object (must not be NULL)

RETURNS

Returns the starting address of the memory region referenced by the buffer. Returns NULL if the memory region is undefined, if the given object is not a direct java.nio.Buffer, or if JNI access to direct buffers is not supported by this virtual machine.

GetDirectBufferCapacity

jlong GetDirectBufferCapacity(JNIEnv* env, jobject buf);

Fetches and returns the capacity in bytes of the memory region referenced by the given direct java.nio.Buffer.

LINKAGE

Index 231 in the JNIEnv interface function table.

PARAMETERS

env: the JNIEnv interface pointer

buf: a direct java.nio.Buffer object (must not be NULL)

RETURNS

Returns the capacity in bytes of the memory region associated with the buffer. Returns -1 if the given object is not a direct java.nio.Buffer, or if JNI access to direct buffers is not supported by this virtual machine.

Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: jni@java.sun.com 		Sun


JNI Enhancements in the JDK

Java

JNI Enhancements
Introduced in version 1.2 of the JavaTM 2 SDK

 JNI Documentation

JNI has been enhanced in the Java 2 SDK to:

  • incorporate new features in the evolving Java platform,
  • ensure an efficient and stable interface for Java/native code integration.

Changes to the JNI are made based on feedback from users . Please continue to send your comments, suggestions, and concerns to jni@java.sun.com.

New Constants

#define JNI_VERSION_1_1 0x00010001
#define JNI_VERSION_1_2 0x00010002

/* Error codes */
#define JNI_EDETACHED    (-2)              /* thread detached from the VM */
#define JNI_EVERSION     (-3)              /* JNI version error */

Enhancements to the Existing API

  • Class Operations
    • FindClass
  • Invocation API
    • JNI_CreateJavaVM
    • AttachCurrentThread
    • DetachCurrentThread
    • DestroyJavaVM

New Functions

  • Library and Version Management
    • JNI_OnLoad
    • JNI_OnUnload
  • Local Reference Management
    • EnsureLocalCapacity
    • PushLocalFrame
    • PopLocalFrame
    • NewLocalRef
  • Exceptions
    • ExceptionCheck
  • Weak Global References
    • NewWeakGlobalRef
    • DeleteWeakGlobalRef
  • Array Operations
    • GetPrimitiveArrayCritical
    • ReleasePrimitiveArrayCritical
  • String Operations
    • GetStringRegion
    • GetStringUTFRegion
    • GetStringCritical
    • ReleaseStringCritical
  • Reflection Support
    • FromReflectedMethod
    • FromReflectedField
    • ToReflectedMethod
    • ToReflectedField
  • Invocation API
    • GetEnv

Class Operations

In the enhanced Java security model, non-system classes can load native code. The JNI function FindClass has been extended so that it finds classes loaded with a class loader.

jclass FindClass(JNIEnv *env, const char *name);

In JDK 1.1, FindClass searched only local classes in CLASSPATH. The resulting classes did not have a class loader.

The Java security model has been extended to allow non-system classes to load and call native methods. In the Java 2 Platform, FindClass locates the class loader associated with the current native method. If the native code belongs to a system class, no class loader will be involved. Otherwise, the proper class loader will be invoked to load and link the named class.

When FindClass is called through the Invocation Interface, there is no current native method or its associated class loader. In that case, the result of ClassLoader.getBaseClassLoader is used. This is the class loader the virtual machine creates for applications, and is able to locate classes listed in the java.class.path property.

Library and Version Management

In JDK 1.1, once a native library is loaded, it is visible from all class loaders. Therefore two classes in different class loaders may link with the same native method. This leads to two problems:
  • A class may mistakenly link with native libraries loaded by a class with the same name in a different class loader.
  • Native methods can easily mix classes from different class loaders. This breaks the name space separation offered by class loaders, and leads to type safety problems.

In the Java 2 SDK, each class loader manages its own set of native libraries. The same JNI native library cannot be loaded into more than one class loader. Doing so causes UnsatisfiedLinkError to be thrown. For example, System.loadLibrary throws an UnsatisfiedLinkError when used to load a native library into two class loaders. The benefits of the new approach are:

  • Name space separation based on class loaders is preserved in native libraries. A native library cannot easily mix classes from different class loaders.
  • In addition, native libraries can be unloaded when their corresponding class loaders are garbage collected.

To facilitate versioning control and resource management, JNI libraries in the Java 2 Platform may optionally export the following two functions:

jint JNI_OnLoad(JavaVM *vm, void *reserved);

The VM calls JNI_OnLoad when the native library is loaded (for example, through System.loadLibrary). JNI_OnLoad must return the JNI version needed by the native library.

In order to use any of the new JNI functions, a native library must export a JNI_OnLoad function that returns JNI_VERSION_1_2. If the native library does not export a JNI_OnLoad function, the VM assumes that the library only requires JNI version JNI_VERSION_1_1. If the VM does not recognize the version number returned by JNI_OnLoad, the native library cannot be loaded.

void JNI_OnUnload(JavaVM *vm, void *reserved);

The VM calls JNI_OnUnload when the class loader containing the native library is garbage collected. This function can be used to perform cleanup operations. Because this function is called in an unknown context (such as from a finalizer), the programmer should be conservative on using Java VM services, and refrain from arbitrary Java call-backs.

Note that JNI_OnLoad and JNI_OnUnload are two functions optionally supplied by JNI libraries, not exported from the VM.

Local Reference Management

Local references are valid for the duration of a native method call. They are freed automatically after the native method returns. Each local reference costs some amount of Java Virtual Machine resource. Programmers need to make sure that native methods do not excessively allocate local references. Although local references are automatically freed after the native method returns to Java, excessive allocation of local references may cause the VM to run out of memory during the execution of a native method.

JDK 1.1 provides a DeleteLocalRef function so that programmers can manually delete local references. For example, if native code iterates through a potentially large array of objects and uses one element in each iteration, it is a good practice to delete the local reference to the no-longer-used array element before a new local reference is created in the next iteration.

The Java 2 SDK provides an additional set of functions for local reference lifetime management.

jint EnsureLocalCapacity(JNIEnv *env, jint capacity);

Ensures that at least a given number of local references can be created in the current thread. Returns 0 on success; otherwise returns a negative number and throws an OutOfMemoryError.

Before it enters a native method, the VM automatically ensures that at least 16 local references can be created.

For backward compatibility, the VM allocates local references beyond the ensured capacity. (As a debugging support, the VM may give the user warnings that too many local references are being created. In the Java 2 SDK, the programmer can supply the -verbose:jni command line option to turn on these messages.) The VM calls FatalError if no more local references can be created beyond the ensured capacity.

jint PushLocalFrame(JNIEnv *env, jint capacity);

Creates a new local reference frame, in which at least a given number of local references can be created. Returns 0 on success, a negative number and a pending OutOfMemoryError on failure.

Note that local references already created in previous local frames are still valid in the current local frame.

jobject PopLocalFrame(JNIEnv *env, jobject result);

Pops off the current local reference frame, frees all the local references, and returns a local reference in the previous local reference frame for the given result object.

Pass NULL as result if you do not need to return a reference to the previous frame.

jobject NewLocalRef(JNIEnv *env, jobject ref);

Creates a new local reference that refers to the same object as ref. The given ref may be a global or local reference. Returns NULL if ref refers to null.

Exceptions

We introduce a convenience function to check for pending exceptions without creating a local reference to the exception object.

jboolean ExceptionCheck(JNIEnv *env);

Returns JNI_TRUE when there is a pending exception; otherwise, returns JNI_FALSE.

Weak Global References

Weak global references are a special kind of global reference. Unlike normal global references, a weak global reference allows the underlying Java object to be garbage collected. Weak global references may be used in any situation where global or local references are used. When the garbage collector runs, it frees the underlying object if the object is only referred to by weak references. A weak global reference pointing to a freed object is functionally equivalent to NULL. Programmers can detect whether a weak global reference points to a freed object by using IsSameObject to compare the weak reference against NULL.

Weak global references in JNI are a simplified version of the Java Weak References, available as part of the Java 2 Platform API ( java.lang.ref package and its classes).

Clarification (added June 2001)

Since garbage collection may occur while native methods are running, objects referred to by weak global references can be freed at any time. While weak global references can be used where global references are used, it is generally inappropriate to do so, as they may become functionally equivalent to NULL without notice.

While IsSameObject can be used to determine whether a weak global reference refers to a freed object, it does not prevent the object from being freed immediately thereafter. Consequently, programmers may not rely on this check to determine whether a weak global reference may used (as a non-NULL reference) in any future JNI function call.

To overcome this inherent limitation, it is recommended that a standard (strong) local or global reference to the same object be acquired using the JNI functions NewLocalRef or NewGlobalRef, and that this strong reference be used to access the intended object. These functions will return NULL if the object has been freed, and otherwise will return a strong reference (which will prevent the object from being freed). The new reference should be explicitly deleted when immediate access to the object is no longer required, allowing the object to be freed.

The weak global reference is weaker than other types of weak references (Java objects of the SoftReference or WeakReference classes). A weak global reference to a specific object will not become functionally equivalent to NULL until after SoftReference or WeakReference objects referring to that same specific object have had their references cleared.

The weak global reference is weaker than Java's internal references to objects requiring finalization. A weak global reference will not become functionally equivalent to NULL until after the completion of the the finalizer for the referenced object, if present.

Interactions between weak global references and PhantomReferences are undefined. In particular, implementations of a Java VM may (or may not) process weak global references after PhantomReferences, and it may (or may not) be possible to use weak global references to hold on to objects which are also referred to by PhantomReference objects. This undefined use of weak global references should be avoided.

jweak NewWeakGlobalRef(JNIEnv *env, jobject obj);

Creates a new weak global reference. Returns NULL if obj refers to null, or if the VM runs out of memory. If the VM runs out of memory, an OutOfMemoryError will be thrown.

void DeleteWeakGlobalRef(JNIEnv *env, jweak obj);

Delete the VM resources needed for the given weak global reference.

Array Operations

In JDK 1.1, programmers can use Get/ReleaseArrayElements functions to obtain a pointer to primitive array elements. If the VM supports pinning, the pointer to the original data is returned; otherwise, a copy is made.

New functions allow native code to obtain a direct pointer to array elements even if the VM does not support pinning.

void * GetPrimitiveArrayCritical(JNIEnv *env, jarray array, jboolean *isCopy);
void ReleasePrimitiveArrayCritical(JNIEnv *env, jarray array, void *carray, jint mode);

The semantics of these two functions are very similar to the existing Get/ReleaseArrayElements functions. If possible, the VM returns a pointer to the primitive array; otherwise, a copy is made. However, there are significant restrictions on how these functions can be used.

After calling GetPrimitiveArrayCritical, the native code should not run for an extended period of time before it calls ReleasePrimitiveArrayCritical. We must treat the code inside this pair of functions as running in a "critical region." Inside a critical region, native code must not call other JNI functions, or any system call that may cause the current thread to block and wait for another Java thread. (For example, the current thread must not call read on a stream being written by another Java thread.)

These restrictions make it more likely that the native code will obtain an uncopied version of the array, even if the VM does not support pinning. For example, a VM may temporarily disable garbage collection when the native code is holding a pointer to an array obtained via GetPrimitiveArrayCritical.

Multiple pairs of GetPrimtiveArrayCritical and ReleasePrimitiveArrayCritical may be nested. For example:

  jint len = (*env)->GetArrayLength(env, arr1);
  jbyte *a1 = (*env)->GetPrimitiveArrayCritical(env, arr1, 0);
  jbyte *a2 = (*env)->GetPrimitiveArrayCritical(env, arr2, 0);
  /* We need to check in case the VM tried to make a copy. */
  if (a1 == NULL || a2 == NULL) {
    ... /* out of memory exception thrown */
  }
  memcpy(a1, a2, len);
  (*env)->ReleasePrimitiveArrayCritical(env, arr2, a2, 0);
  (*env)->ReleasePrimitiveArrayCritical(env, arr1, a1, 0);

Note that GetPrimitiveArrayCritical might still make a copy of the array if the VM internally represents arrays in a different format. Therefore we need to check its return value against NULL for possible out of memory situations.

String Operations

In JDK 1.1, programmers can get primitive array elements in a user-supplied buffer. The Java 2 SDK allows native code to obtain Unicode or UTF-8 characters in a user-supplied buffer.

void GetStringRegion(JNIEnv *env, jstring str, jsize start, jsize len, jchar *buf);

Copies len number of Unicode characters beginning at offset start to the given buffer buf.

Throws StringIndexOutOfBoundsException on index overflow.

<void GetStringUTFRegion(JNIEnv *env, jstring str, jsize start, jsize len, char *buf);

Translates len number of Unicode characters beginning at offset start into UTF-8 format and place the result in the given buffer buf.

Throws StringIndexOutOfBoundsException on index overflow.

const jchar * GetStringCritical(JNIEnv *env, jstring string, jboolean *isCopy);
void ReleaseStringCritical(JNIEnv *env, jstring string, const jchar *carray);

The semantics of these two functions are similar to the existing Get/ReleaseStringChars functions. If possible, the VM returns a pointer to string elements; otherwise, a copy is made. However, there are significant restrictions on how these functions can be used. In a code segment enclosed by Get/ReleaseStringCritical calls, the native code must not issue arbitrary JNI calls, or cause the current thread to block.

The restrictions on Get/ReleaseStringCritical are similar to those on Get/ReleasePrimitiveArrayCritical.

Reflection Support

Programmers can use the JNI to call Java methods or access Java fields if they know the name and type of the methods or fields. The Java Core Reflection API allows programmers to introspect Java classes at runtime. JNI provides a set of conversion functions between field and method IDs used in the JNI to field and method objects used in the Java Core Reflection API.

jmethodID FromReflectedMethod(JNIEnv *env, jobject method);

Converts a java.lang.reflect.Method or java.lang.reflect.Constructor object to a method ID.

jfieldID FromReflectedField(JNIEnv *env, jobject field);

Converts a java.lang.reflect.Field to a field ID.

jobject ToReflectedMethod(JNIEnv *env, jclass cls,
   jmethodID methodID);

Converts a method ID derived from cls to a java.lang.reflect.Method or java.lang.reflect.Constructor object.

Throws OutOfMemoryError and returns 0 if fails.

jobject ToReflectedField(JNIEnv *env, jclass cls,
   jfieldID fieldID);

Converts a field ID derived from cls to a java.lang.reflect.Field object.

Throws OutOfMemoryError and returns 0 if fails.

Invocation API

jint JNI_CreateJavaVM(JavaVM **pvm, void **penv, void *args);

In JDK 1.1, the second argument to JNI_CreateJavaVM is always a pointer to JNIEnv *. The third argument is a pointer to a JDK 1.1 specific structure (JDK1_1InitArgs). The JDK1_1InitArgs structure is clearly not designed to be portable on all VMs.

In the Java 2 SDK, we introduce a standard VM initialization structure. Backward compatibility is preserved. If the VM initialization argument points to a JDK1_1InitArgs structure, JNI_CreateJavaVM still returns the 1.1 version of JNI interface pointer. The VM returns the 1.2 version of JNI interface pointer if the third argument points to a JavaVMInitArgs structure. Unlike JDK1_1InitArgs, which contains a fixed set of options, JavaVMInitArgs uses option strings to encode arbitrary VM start up options.

typedef struct JavaVMInitArgs {
    jint version;

    jint nOptions;
    JavaVMOption *options;
    jboolean ignoreUnrecognized;
} JavaVMInitArgs;
The version field must be set to JNI_VERSION_1_2. (In contrast, the version field in JDK1_1InitArgs must be set to JNI_VERSION_1_1.) The options field is an array of the following type:
typedef struct JavaVMOption {
    char *optionString;
    void *extraInfo;
} JavaVMOption;
The size of the array is denoted by the nOptions field in JavaVMInitArgs. If ignoreUnrecognized is JNI_TRUE, JNI_CreateJavaVM ignore all unrecognized option strings that begin with "-X" or "_". If ignoreUnrecognized is JNI_FALSE, JNI_CreateJavaVM returns JNI_ERR as soon as it encounters any unrecognized option strings. All Java VMs must recognize the following set of standard options:

optionString | meaning
-D<name>=<value> | Set a system property
-verbose[:class|gc|jni] | Enable verbose output. The options can be followed by a comma-separated list of names indicating what kind of messages will be printed by the VM. For example, "-verbose:gc,class" instructs the VM to print GC and class loading related messages. Standard names include: gc, class, and jni. All nonstandard (VM-specific) names must begin with "X".
vfprintf | extraInfo is a pointer to the vfprintf hook.
exit | extraInfo is a pointer to the exit hook.
abort | extraInfo is a pointer to the abort hook.

In addition, each VM implementation may support its own set of non-standard option strings. Non-standard option names must begin with "-X" or an underscore ("_"). For example, the Java 2 SDK supports -Xms and -Xmx options to allow programmers specify the initial and maximum heap size. Options that begin with "-X" are accessible from the "java" command line.

Here is the example code that creates a Java VM in the Java 2 SDK:

JavaVMInitArgs vm_args;
JavaVMOption options[4];

options[0].optionString = "-Djava.compiler=NONE";           /* disable JIT */
options[1].optionString = "-Djava.class.path=c:\myclasses"; /* user classes */
options[2].optionString = "-Djava.library.path=c:\mylibs";  /* set native library path */
options[3].optionString = "-verbose:jni";                   /* print JNI-related messages */

vm_args.version = JNI_VERSION_1_2;
vm_args.options = options;
vm_args.nOptions = 4;
vm_args.ignoreUnrecognized = TRUE;

/* Note that in the Java 2 SDK, there is no longer any need to call
 * JNI_GetDefaultJavaVMInitArgs.
 */
res = JNI_CreateJavaVM(&vm, (void **)&env, &vm_args);
if (res < 0) ...

The Java 2 SDK still supports JDK1_1InitArgs in exactly the same way as JDK 1.1.

jint AttachCurrentThread(JavaVM *vm, void **penv, void *args);

In JDK 1.1, the second argument to AttachCurrentThread is always a pointer to JNIEnv. The third argument to AttachCurrentThread was reserved, and should be set to NULL.

In the Java 2 SDK, you pass NULL as the third argument for 1.1 behavior, or pass a pointer to the following structure to specify additional information:

typedef struct JavaVMAttachArgs {
    jint version;  /* must be JNI_VERSION_1_2 */
    char *name;    /* the name of the thread, or NULL */
    jobject group; /* global ref of a ThreadGroup object, or NULL */
} JavaVMAttachArgs;

jint DetachCurrentThread(JavaVM *vm);

In JDK 1.1, the main thread cannot be detached from the VM. It must call DestroyJavaVM to unload the entire VM.

In the Java 2 SDK, the main thread can be detached from the VM.

jint DestroyJavaVM(JavaVM *vm);

The support for DestroyJavaVM was not complete in 1.1. Only the main thread may call DestroyJavaVM. In the Java 2 SDK, any thread, whether attached or not, can call this function. If the current thread is attached, the VM waits until the current thread is the only user-level Java thread. If the current thread is not attached, the VM attaches the current thread and then waits until the current thread is the only user-level thread. The Java 2 SDK still does not support VM unloading, however. DestroyJavaVM always returns an error code.

jint GetEnv(JavaVM *vm, void **env, jint version);

If the current thread is not attached to the VM, sets *env to NULL, and returns JNI_EDETACHED. If the specified version is not supported, sets *env to NULL, and returns JNI_EVERSION. Otherwise, sets *env to the appropriate interface, and returns JNI_OK.
Copyright © 1995-99 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: jni@java.sun.com 		Sun


Acknowledgments

The Java Native Interface (JNI) specification was formed as a result of a series of discussions among JavaSoft and Java licensees. The goal is to achieve a native interface standard.

Sheng Liang at JavaSoft is responsible for the JNI design and specification. JNI is partly evolved from Netscape’s Java Runtime Interface (JRI), which was designed by Warren Harris. Warren Harris also helped to improve the JNI design. Simon Nash at IBM and Patrick Beard at Apple provided extensive feedbacks that shaped the JNI design in many ways.

In addition, the JNI benefited greatly from JavaSoft internal design reviews. These design reviews were conducted by James Gosling, Peter Kessler, Tim Lindholm, Mark Reinhold, Derek White, and Frank Yellin.

We also want to acknowledge the helpful comments and suggestions we received from numerous people on various drafts of the specification.

Lastly, Beth Stearns improved the presentation of this document.

Contents | Previous | Next

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


Contents

Java Native Interface Specification—Contents

Contents | Previous | Next

1. Introduction

Java Native Interface Overview
 Background

JDK 1.0 Native Method Interface
 Java Runtime Interface
Raw Native Interface and Java/COM Interface

Objectives
 Java Native Interface Approach
Programming to the JNI
 Changes in JDK 1.1.2

2. Design Overview

JNI Interface Functions and Pointers
 Loading and Linking Native Methods

Resolving Native Method Names
 Native Method Arguments

Referencing Java Objects

Global and Local References
 Implementing Local References

Accessing Java Objects

Accessing Primitive Arrays
 Accessing Fields and Methods

Reporting Programming Errors
 Java Exceptions

Exceptions and Error Codes
 Asynchronous Exceptions
 Exception Handling

3. JNI Types and Data Structures

Primitive Types
Reference Types
Field and Method IDs
The Value Type
Type Signatures
Modified UTF-8 Strings

4. JNI Functions

Interface Function Table
Version Information

GetVersion

Class Operations

DefineClass
 FindClass
 GetSuperclass
 IsAssignableFrom

Exceptions

Throw
 ThrowNew
ExceptionOccurred
 ExceptionDescribe
ExceptionClear
 FatalError
 ExceptionCheck

Global and Local References

NewGlobalRef
 DeleteGlobalRef
DeleteLocalRef
 EnsureLocalCapacity
 PushLocalFrame
 PopLocalFrame
 NewLocalRef

Weak Global References

NewWeakGlobalRef
 DeleteWeakGlobalRef

Object Operations

AllocObject
 NewObject, NewObjectA, and NewObjectV
GetObjectClass
GetObjectRefType
IsInstanceOf
IsSameObj ect

Accessing Fields of Objects

GetFieldID
 Get<type>Field Routines
Set<type>Field Routines

Calling Instance Methods

GetMethodID
 Call<type>Method Routines, Call<type>MethodA Routines, and Call<type>MethodV Routines
CallNonvirtual<type>Method Routines, CallNonvirtual<type>MethodA Routines, and CallNonvirtual<type>MethodV Routines

Accessing Static Fields

GetStaticFieldID
 GetStatic<type>Field Routines
SetStatic<type>Field Routines

Calling Static Methods

GetStaticMethodID
 CallStatic<type>Method Routines, CallStatic<type>MethodA Routines, and CallStatic<type>MethodV Routines

String Operations

NewString
 GetStringLength
GetStringChars
 ReleaseStringChars
NewStringUTF
 GetStringUTFLength
GetStringUTFChars
 ReleaseStringUTFChars
 GetStringRegion
 GetStringUTFRegion
 GetStringCritical
 Release StringCritical

Array Operations

GetArrayLength
 NewObjectArray
GetObjectArrayElement
 SetObjectArrayElement
New<PrimitiveType>Array Routines
 Get<PrimitiveType>ArrayElements Routines
Release<PrimitiveType>ArrayElements Routines
 Get<PrimitiveType>ArrayRegion Routines
Set<PrimitiveType>ArrayRegion Routines
 GetPrimitiveArrayCritical
 ReleasePrimitiveArrayCritical

Registering Native Methods

RegisterNatives
 UnregisterNatives

Monitor Operations

MonitorEnter
 MonitorExit

NIO Support

NewDirectByteBuffer
 GetDirectBufferAddress
 GetDirectBufferCapacity

Reflection Support

FromReflectedMethod
 FromReflectedField
 ToReflectedMethod
 ToReflectedField

Java VM Interface

GetJavaVM

5. The Invocation API

Overview

Creating the VM
 Attaching to the VM
Unloading the VM

Library and Version Management

JNI_OnLoad
 JNI_OnUnload

Invocation API Functions

JNI_GetDefaultJavaVMInitArgs
 JNI_GetCreatedJavaVMs
JNI_CreateJavaVM
 DestroyJavaVM
AttachCurrentThread
 AttachCurrentThreadAsDaemon
 DetachCurrentThread
 GetEnv

Contents | Previous | Next

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


Design Overview

Chapter 2

This chapter focuses on major design issues in the JNI. Most design issues in this section are related to native methods. The design of the Invocation API is covered in Chapter 5.

JNI Interface Functions and Pointers

Native code accesses Java VM features by calling JNI functions. JNI functions are available through an interface pointer. An interface pointer is a pointer to a pointer. This pointer points to an array of pointers, each of which points to an interface function. Every interface function is at a predefined offset inside the array. Figure 2-1 illustrates the organization of an interface pointer.

The previous context describes this image.

Figure 2-1 Interface Pointer

The JNI interface is organized like a C++ virtual function table or a COM interface. The advantage to using an interface table, rather than hard-wired function entries, is that the JNI name space becomes separate from the native code. A VM can easily provide multiple versions of JNI function tables. For example, the VM may support two JNI function tables:

  • one performs thorough illegal argument checks, and is suitable for debugging;
  • the other performs the minimal amount of checking required by the JNI specification, and is therefore more efficient.

The JNI interface pointer is only valid in the current thread. A native method, therefore, must not pass the interface pointer from one thread to another. A VM implementing the JNI may allocate and store thread-local data in the area pointed to by the JNI interface pointer.

Native methods receive the JNI interface pointer as an argument. The VM is guaranteed to pass the same interface pointer to a native method when it makes multiple calls to the native method from the same Java thread. However, a native method can be called from different Java threads, and therefore may receive different JNI interface pointers.

Loading and Linking Native Methods

Native methods are loaded with the System.loadLibrary method. In the following example, the class initialization method loads a platform-specific native library in which the native method f is defined:

package pkg;

class Cls {

     native double f(int i, String s);

     static {

         System.loadLibrary(“pkg_Cls”);

     }

}

The argument to System.loadLibrary is a library name chosen arbitrarily by the programmer. The system follows a standard, but platform-specific, approach to convert the library name to a native library name. For example, a Solaris system converts the name pkg_Cls to libpkg_Cls.so, while a Win32 system converts the same pkg_Cls name to pkg_Cls.dll.

The programmer may use a single library to store all the native methods needed by any number of classes, as long as these classes are to be loaded with the same class loader. The VM internally maintains a list of loaded native libraries for each class loader. Vendors should choose native library names that minimize the chance of name clashes.

If the underlying operating system does not support dynamic linking, all native methods must be prelinked with the VM. In this case, the VM completes the System.loadLibrary call without actually loading the library.

The programmer can also call the JNI function RegisterNatives() to register the native methods associated with a class. The RegisterNatives() function is particularly useful with statically linked functions.

Resolving Native Method Names

Dynamic linkers resolve entries based on their names. A native method name is concatenated from the following components:

  • the prefix Java_
  • a mangled fully-qualified class name
  • an underscore (“_”) separator
  • a mangled method name
  • for overloaded native methods, two underscores (“__”) followed by the mangled argument signature

The VM checks for a method name match for methods that reside in the native library. The VM looks first for the short name; that is, the name without the argument signature. It then looks for the long name, which is the name with the argument signature. Programmers need to use the long name only when a native method is overloaded with another native method. However, this is not a problem if the native method has the same name as a nonnative method. A nonnative method (a Java method) does not reside in the native library.

In the following example, the native method g does not have to be linked using the long name because the other method g is not a native method, and thus is not in the native library.

class Cls1 {

  int g(int i);

  native int g(double d);

}

We adopted a simple name-mangling scheme to ensure that all Unicode characters translate into valid C function names. We use the underscore (“_”) character as the substitute for the slash (“/”) in fully qualified class names. Since a name or type descriptor never begins with a number, we can use _0, ..., _9 for escape sequences, as Table 2-1 illustrates:

Table 2-1 Unicode Character Translation
Escape Sequence | Denotes
_0XXXX | a Unicode character XXXX. Note that lower case is used to represent non-ASCII Unicode characters, e.g., _0abcd as opposed to _0ABCD.
_1 | the character “_”
_2 | the character “;” in signatures
_3 | the character “[“ in signatures

Both the native methods and the interface APIs follow the standard library-calling convention on a given platform. For example, UNIX systems use the C calling convention, while Win32 systems use __stdcall.

Native Method Arguments

The JNI interface pointer is the first argument to native methods. The JNI interface pointer is of type JNIEnv. The second argument differs depending on whether the native method is static or nonstatic. The second argument to a nonstatic native method is a reference to the object. The second argument to a static native method is a reference to its Java class.

The remaining arguments correspond to regular Java method arguments. The native method call passes its result back to the calling routine via the return value. Chapter 3 describes the mapping between Java and C types.

Code Example 2-1 illustrates using a C function to implement the native method f. The native method f is declared as follows:

package pkg;

class Cls {

     native double f(int i, String s);

     ...

}

The C function with the long mangled name Java_pkg_Cls_f_ILjava_lang_String_2 implements native method f:

Code Example 2-1 Implementing a Native Method Using C

jdouble Java_pkg_Cls_f__ILjava_lang_String_2 (

     JNIEnv *env,        /* interface pointer */

     jobject obj,        /* "this" pointer */

     jint i,             /* argument #1 */

     jstring s)          /* argument #2 */

{

     /* Obtain a C-copy of the Java string */

     const char *str = (*env)->GetStringUTFChars(env, s, 0);

     /* process the string */

     ...

     /* Now we are done with str */

     (*env)->ReleaseStringUTFChars(env, s, str);

     return ...

}

Note that we always manipulate Java objects using the interface pointer env . Using C++, you can write a slightly cleaner version of the code, as shown in Code Example 2-2:

Code Example 2-2 Implementing a Native Method Using C++

extern "C" /* specify the C calling convention */

jdouble Java_pkg_Cls_f__ILjava_lang_String_2 (

     JNIEnv *env,        /* interface pointer */

     jobject obj,        /* "this" pointer */

     jint i,             /* argument #1 */

     jstring s)          /* argument #2 */

{

     const char *str = env->GetStringUTFChars(s, 0);

     ...

     env->ReleaseStringUTFChars(s, str);

     return ...

}

With C++, the extra level of indirection and the interface pointer argument disappear from the source code. However, the underlying mechanism is exactly the same as with C. In C++, JNI functions are defined as inline member functions that expand to their C counterparts.

Referencing Java Objects

Primitive types, such as integers, characters, and so on, are copied between Java and native code. Arbitrary Java objects, on the other hand, are passed by reference. The VM must keep track of all objects that have been passed to the native code, so that these objects are not freed by the garbage collector. The native code, in turn, must have a way to inform the VM that it no longer needs the objects. In addition, the garbage collector must be able to move an object referred to by the native code.

Global and Local References

The JNI divides object references used by the native code into two categories: local and global references. Local references are valid for the duration of a native method call, and are automatically freed after the native method returns. Global references remain valid until they are explicitly freed.

Objects are passed to native methods as local references. All Java objects returned by JNI functions are local references. The JNI allows the programmer to create global references from local references. JNI functions that expect Java objects accept both global and local references. A native method may return a local or global reference to the VM as its result.

In most cases, the programmer should rely on the VM to free all local references after the native method returns. However, there are times when the programmer should explicitly free a local reference. Consider, for example, the following situations:

  • A native method accesses a large Java object, thereby creating a local reference to the Java object. The native method then performs additional computation before returning to the caller. The local reference to the large Java object will prevent the object from being garbage collected, even if the object is no longer used in the remainder of the computation.
  • A native method creates a large number of local references, although not all of them are used at the same time. Since the VM needs a certain amount of space to keep track of a local reference, creating too many local references may cause the system to run out of memory. For example, a native method loops through a large array of objects, retrieves the elements as local references, and operates on one element at each iteration. After each iteration, the programmer no longer needs the local reference to the array element.

The JNI allows the programmer to manually delete local references at any point within a native method. To ensure that programmers can manually free local references, JNI functions are not allowed to create extra local references, except for references they return as the result.

Local references are only valid in the thread in which they are created. The native code must not pass local references from one thread to another.

Implementing Local References

To implement local references, the Java VM creates a registry for each transition of control from Java to a native method. A registry maps nonmovable local references to Java objects, and keeps the objects from being garbage collected. All Java objects passed to the native method (including those that are returned as the results of JNI function calls) are automatically added to the registry. The registry is deleted after the native method returns, allowing all of its entries to be garbage collected.

There are different ways to implement a registry, such as using a table, a linked list, or a hash table. Although reference counting may be used to avoid duplicated entries in the registry, a JNI implementation is not obliged to detect and collapse duplicate entries.

Note that local references cannot be faithfully implemented by conservatively scanning the native stack. The native code may store local references into global or heap data structures.

Accessing Java Objects

The JNI provides a rich set of accessor functions on global and local references. This means that the same native method implementation works no matter how the VM represents Java objects internally. This is a crucial reason why the JNI can be supported by a wide variety of VM implementations.

The overhead of using accessor functions through opaque references is higher than that of direct access to C data structures. We believe that, in most cases, Java programmers use native methods to perform nontrivial tasks that overshadow the overhead of this interface.

Accessing Primitive Arrays

This overhead is not acceptable for large Java objects containing many primitive data types, such as integer arrays and strings. (Consider native methods that are used to perform vector and matrix calculations.) It would be grossly inefficient to iterate through a Java array and retrieve every element with a function call.

One solution introduces a notion of “pinning” so that the native method can ask the VM to pin down the contents of an array. The native method then receives a direct pointer to the elements. This approach, however, has two implications:

  • The garbage collector must support pinning.
  • The VM must lay out primitive arrays contiguously in memory. Although this is the most natural implementation for most primitive arrays, boolean arrays can be implemented as packed or unpacked. Therefore, native code that relies on the exact layout of boolean arrays will not be portable.

We adopt a compromise that overcomes both of the above problems.

First, we provide a set of functions to copy primitive array elements between a segment of a Java array and a native memory buffer. Use these functions if a native method needs access to only a small number of elements in a large array.

Second, programmers can use another set of functions to retrieve a pinned-down version of array elements. Keep in mind that these functions may require the Java VM to perform storage allocation and copying. Whether these functions in fact copy the array depends on the VM implementation, as follows:

  • If the garbage collector supports pinning, and the layout of the array is the same as expected by the native method, then no copying is needed.
  • Otherwise, the array is copied to a nonmovable memory block (for example, in the C heap) and the necessary format conversion is performed. A pointer to the copy is returned.

Lastly, the interface provides functions to inform the VM that the native code no longer needs to access the array elements. When you call these functions, the system either unpins the array, or it reconciles the original array with its non-movable copy and frees the copy.

Our approach provides flexibility. A garbage collector algorithm can make separate decisions about copying or pinning for each given array. For example, the garbage collector may copy small objects, but pin the larger objects.

A JNI implementation must ensure that native methods running in multiple threads can simultaneously access the same array. For example, the JNI may keep an internal counter for each pinned array so that one thread does not unpin an array that is also pinned by another thread. Note that the JNI does not need to lock primitive arrays for exclusive access by a native method. Simultaneously updating a Java array from different threads leads to nondeterministic results.

Accessing Fields and Methods

The JNI allows native code to access the fields and to call the methods of Java objects. The JNI identifies methods and fields by their symbolic names and type signatures. A two-step process factors out the cost of locating the field or method from its name and signature. For example, to call the method f in class cls, the native code first obtains a method ID, as follows:

jmethodID mid =      env->GetMethodID(cls, “f”, “(ILjava/lang/String;)D”);

The native code can then use the method ID repeatedly without the cost of method lookup, as follows:

jdouble result = env->CallDoubleMethod(obj, mid, 10, str);

A field or method ID does not prevent the VM from unloading the class from which the ID has been derived. After the class is unloaded, the method or field ID becomes invalid. The native code, therefore, must make sure to:

  • keep a live reference to the underlying class, or
  • recompute the method or field ID

if it intends to use a method or field ID for an extended period of time.

The JNI does not impose any restrictions on how field and method IDs are implemented internally.

Reporting Programming Errors

The JNI does not check for programming errors such as passing in NULL pointers or illegal argument types. Illegal argument types includes such things as using a normal Java object instead of a Java class object. The JNI does not check for these programming errors for the following reasons:

  • Forcing JNI functions to check for all possible error conditions degrades the performance of normal (correct) native methods.
  • In many cases, there is not enough runtime type information to perform such checking.

Most C library functions do not guard against programming errors. The printf() function, for example, usually causes a runtime error, rather than returning an error code, when it receives an invalid address. Forcing C library functions to check for all possible error conditions would likely result in such checks to be duplicated--once in the user code, and then again in the library.

The programmer must not pass illegal pointers or arguments of the wrong type to JNI functions. Doing so could result in arbitrary consequences, including a corrupted system state or VM crash.

Java Exceptions

The JNI allows native methods to raise arbitrary Java exceptions. The native code may also handle outstanding Java exceptions. The Java exceptions left unhandled are propagated back to the VM.

Exceptions and Error Codes

Certain JNI functions use the Java exception mechanism to report error conditions. In most cases, JNI functions report error conditions by returning an error code and throwing a Java exception. The error code is usually a special return value (such as NULL) that is outside of the range of normal return values. Therefore, the programmer can:

  • quickly check the return value of the last JNI call to determine if an error has occurred, and
  • call a function, ExceptionOccurred(), to obtain the exception object that contains a more detailed description of the error condition.

There are two cases where the programmer needs to check for exceptions without being able to first check an error code:

  • The JNI functions that invoke a Java method return the result of the Java method. The programmer must call ExceptionOccurred() to check for possible exceptions that occurred during the execution of the Java method.
  • Some of the JNI array access functions do not return an error code, but may throw an ArrayIndexOutOfBoundsException or ArrayStoreException.

In all other cases, a non-error return value guarantees that no exceptions have been thrown.

Asynchronous Exceptions

In cases of multiple threads, threads other than the current thread may post an asynchronous exception. An asynchronous exception does not immediately affect the execution of the native code in the current thread, until:

  • the native code calls one of the JNI functions that could raise synchronous exceptions, or
  • the native code uses ExceptionOccurred() to explicitly check for synchronous and asynchronous exceptions.

Note that only those JNI function that could potentially raise synchronous exceptions check for asynchronous exceptions.

Native methods should insert ExceptionOccurred()checks in necessary places (such as in a tight loop without other exception checks) to ensure that the current thread responds to asynchronous exceptions in a reasonable amount of time.

Exception Handling

There are two ways to handle an exception in native code:

  • The native method can choose to return immediately, causing the exception to be thrown in the Java code that initiated the native method call.
  • The native code can clear the exception by calling ExceptionClear(), and then execute its own exception-handling code.

After an exception has been raised, the native code must first clear the exception before making other JNI calls. When there is a pending exception, the JNI functions that are safe to call are:

  ExceptionOccurred()
  ExceptionDescribe()
  ExceptionClear()
  ExceptionCheck()
  ReleaseStringChars()
  ReleaseStringUTFChars()
  ReleaseStringCritical()
  Release<Type>ArrayElements()
  ReleasePrimitiveArrayCritical()
  DeleteLocalRef()
  DeleteGlobalRef()
  DeleteWeakGlobalRef()
  MonitorExit()
  PushLocalFrame()
  PopLocalFrame()

Contents | Previous | Next

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


Introduction

Chapter 1

This chapter introduces the Java Native Interface (JNI). The JNI is a native programming interface. It allows Java code that runs inside a Java Virtual Machine (VM) to interoperate with applications and libraries written in other programming languages, such as C, C++, and assembly.

The most important benefit of the JNI is that it imposes no restrictions on the implementation of the underlying Java VM. Therefore, Java VM vendors can add support for the JNI without affecting other parts of the VM. Programmers can write one version of a native application or library and expect it to work with all Java VMs supporting the JNI.

This chapter covers the following topics:

  • Java Native Interface Overview
  • Background
  • Objectives
  • Java Native Interface Approach
  • Programming to the JNI
  • Changes

Java Native Interface Overview

While you can write applications entirely in Java, there are situations where Java alone does not meet the needs of your application. Programmers use the JNI to write Java native methods to handle those situations when an application cannot be written entirely in Java.

The following examples illustrate when you need to use Java native methods:

  • The standard Java class library does not support the platform-dependent features needed by the application.
  • You already have a library written in another language, and wish to make it accessible to Java code through the JNI.
  • You want to implement a small portion of time-critical code in a lower-level language such as assembly.

By programming through the JNI, you can use native methods to:

  • Create, inspect, and update Java objects (including arrays and strings).
  • Call Java methods.
  • Catch and throw exceptions.
  • Load classes and obtain class information.
  • Perform runtime type checking.

You can also use the JNI with the Invocation API to enable an arbitrary native application to embed the Java VM. This allows programmers to easily make their existing applications Java-enabled without having to link with the VM source code.

Historical Background

VMs from different vendors offer different native method interfaces. These different interfaces force programmers to produce, maintain, and distribute multiple versions of native method libraries on a given platform.

We briefly examine some of the native method interfaces, such as:

  • JDK 1.0 native method interface
  • Netscape’s Java Runtime Interface
  • Microsoft’s Raw Native Interface and Java/COM interface

JDK 1.0 Native Method Interface

JDK 1.0 was shipped with a native method interface. Unfortunately, there were two major reasons that this interface was unsuitable for adoption by other Java VMs.

First, the native code accessed fields in Java objects as members of C structures. However, the Java Language Specification does not define how objects are laid out in memory. If a Java VM lays out objects differently in memory, then the programmer would have to recompile the native method libraries.

Second, JDK 1.0’s native method interface relied on a conservative garbage collector. The unrestricted use of the unhand macro, for example, made it necessary to conservatively scan the native stack.

Java Runtime Interface

Netscape had proposed the Java Runtime Interface (JRI), a general interface for services provided in the Java virtual machine. JRI was designed with portability in mind---it makes few assumptions about the implementation details in the underlying Java VM. The JRI addressed a wide range of issues, including native methods, debugging, reflection, embedding (invocation), and so on.

Raw Native Interface and Java/COM Interface

The Microsoft Java VM supports two native method interfaces. At the low level, it provides an efficient Raw Native Interface (RNI). The RNI offers a high degree of source-level backward compatibility with the JDK’s native method interface, although it has one major difference. Instead of relying on conservative garbage collection, the native code must use RNI functions to interact explicitly with the garbage collector.

At a higher level, Microsoft's Java/COM interface offers a language-independent standard binary interface to the Java VM. Java code can use a COM object as if it were a Java object. A Java class can also be exposed to the rest of the system as a COM class.

Objectives

We believe that a uniform, well-thought-out standard interface offers the following benefits for everyone:

  • Each VM vendor can support a larger body of native code.
  • Tool builders will not have to maintain different kinds of native method interfaces.
  • Application programmers will be able to write one version of their native code and this version will run on different VMs.

The best way to achieve a standard native method interface is to involve all parties with an interest in Java VMs. Therefore we organized a series of discussions among the Java licensees on the design of a uniform native method interface. It is clear from the discussions that the standard native method interface must satisfy the following requirements:

  • Binary compatibility - The primary goal is binary compatibility of native method libraries across all Java VM implementations on a given platform. Programmers should maintain only one version of their native method libraries for a given platform.
  • Efficiency - To support time-critical code, the native method interface must impose little overhead. All known techniques to ensure VM-independence (and thus binary compatibility) carry a certain amount of overhead. We must somehow strike a compromise between efficiency and VM-independence.
  • Functionality - The interface must expose enough Java VM internals to allow native methods to accomplish useful tasks.

Java Native Interface Approach

We hoped to adopt one of the existing approaches as the standard interface, because this would have imposed the least burden on programmers who had to learn multiple interfaces in different VMs. Unfortunately, no existing solutions are completely satisfactory in achieving our goals.

Netscape’s JRI is the closest to what we envision as a portable native method interface, and was used as the starting point of our design. Readers familiar with the JRI will notice the similarities in the API naming convention, the use of method and field IDs, the use of local and global references, and so on. Despite our best efforts, however, the JNI is not binary-compatible with the JRI, although a VM can support both the JRI and the JNI.

Microsoft’s RNI was an improvement over JDK 1.0 because it solved the problem of native methods working with a nonconservative garbage collector. The RNI, however, was not suitable as a VM-independent native method interface. Like the JDK, RNI native methods access Java objects as C structures, leading to two problems:

  • RNI exposed the layout of internal Java objects to native code.
  • Direct access of Java objects as C structures makes it impossible to efficiently incorporate “write barriers,” which are necessary in advanced garbage collection algorithms.

As a binary standard, COM ensures complete binary compatibility across different VMs. Invoking a COM method requires only an indirect call, which carries little overhead. In addition, COM objects are a great improvement over dynamic-link libraries in solving versioning problems.

The use of COM as the standard Java native method interface, however, is hampered by a few factors:

  • First, the Java/COM interface lacks certain desired functions, such as accessing private fields and raising general exceptions.
  • Second, the Java/COM interface automatically provides the standard IUnknown and IDispatch COM interfaces for Java objects, so that native code can access public methods and fields. Unfortunately, the IDispatch interface does not deal with overloaded Java methods and is case-insensitive in matching method names. Furthermore, all Java methods exposed through the IDispatch interface are wrapped to perform dynamic type checking and coercion. This is because the IDispatch interface is designed with weakly-typed languages (such as Basic) in mind.
  • Third, instead of dealing with individual low-level functions, COM is designed to allow software components (including full-fledged applications) to work together. We believe that it is not appropriate to treat all Java classes or low-level native methods as software components.
  • Fourth, the immediate adoption of COM is hampered by the lack of its support on UNIX platforms.

Although Java objects are not exposed to the native code as COM objects, the JNI interface itself is binary-compatible with COM. JNI uses the same jump table structure and calling convention that COM does. This means that, as soon as cross-platform support for COM is available, the JNI can become a COM interface to the Java VM.

JNI is not believed to be the only native method interface supported by a given Java VM. A standard interface benefits programmers, who would like to load their native code libraries into different Java VMs. In some cases, the programmer may have to use a lower-level, VM-specific interface to achieve top efficiency. In other cases, the programmer might use a higher-level interface to build software components. Indeed, as the Java environment and component software technologies become more mature, native methods will gradually lose their significance.

Programming to the JNI

Native method programmers should program to the JNI. Programming to the JNI insulates you from unknowns, such as the vendor’s VM that the end user might be running. By conforming to the JNI standard, you will give a native library the best chance to run in a given Java VM.

If you are implementing a Java VM, you should implement the JNI. JNI has been time tested and ensured to not impose any overhead or restrictions on your VM implementation, including object representation, garbage collection scheme, and so on. Please send us your feedback if you run into any problems we may have overlooked.

Changes

As of Java SE 6.0, the deprecated structures JDK1_1InitArgs and JDK1_1AttachArgs have been removed, instead JavaVMInitArgs and JavaVMAttachArgs are to be used.

Contents | Previous | Next

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


JNI Functions

Chapter 4

This chapter serves as the reference section for the JNI functions. It provides a complete listing of all the JNI functions. It also presents the exact layout of the JNI function table.

Note the use of the term “must” to describe restrictions on JNI programmers. For example, when you see that a certain JNI function must receive a non-NULL object, it is your responsibility to ensure that NULL is not passed to that JNI function. As a result, a JNI implementation does not need to perform NULL pointer checks in that JNI function.

A portion of this chapter is adapted from Netscape’s JRI documentation.

The reference material groups functions by their usage. The reference section is organized by the following functional areas:

  • Version Information
  • Class Operations
  • Exceptions
  • Global and Local References
  • Weak Global References
  • Object Operations
  • Accessing Fields of Objects
  • Calling Instance Methods
  • Accessing Static Fields
  • Calling Static Methods
  • String Operations
  • Array Operations
  • Registering Native Methods
  • Monitor Operations
  • NIO Support
  • Reflection Support
  • Java VM Interface

Interface Function Table

Each function is accessible at a fixed offset through the JNIEnv argument. The JNIEnv type is a pointer to a structure storing all JNI function pointers. It is defined as follows:

typedef const struct JNINativeInterface *JNIEnv;

The VM initializes the function table, as shown by Code Example 4-1. Note that the first three entries are reserved for future compatibility with COM. In addition, we reserve a number of additional NULL entries near the beginning of the function table, so that, for example, a future class-related JNI operation can be added after FindClass, rather than at the end of the table.

Note that the function table can be shared among all JNI interface pointers.

Code Example 4-1
const struct JNINativeInterface ... = {

    NULL,
    NULL,
    NULL,
    NULL,
    GetVersion,

    DefineClass,
    FindClass,

    FromReflectedMethod,
    FromReflectedField,
    ToReflectedMethod,

    GetSuperclass,
    IsAssignableFrom,

    ToReflectedField,

    Throw,
    ThrowNew,
    ExceptionOccurred,
    ExceptionDescribe,
    ExceptionClear,
    FatalError,

    PushLocalFrame,
    PopLocalFrame,

    NewGlobalRef,
    DeleteGlobalRef,
    DeleteLocalRef,
    IsSameObject,
    NewLocalRef,
    EnsureLocalCapacity,

    AllocObject,
    NewObject,
    NewObjectV,
    NewObjectA,

    GetObjectClass,
    IsInstanceOf,

    GetMethodID,

    CallObjectMethod,
    CallObjectMethodV,
    CallObjectMethodA,
    CallBooleanMethod,
    CallBooleanMethodV,
    CallBooleanMethodA,
    CallByteMethod,
    CallByteMethodV,
    CallByteMethodA,
    CallCharMethod,
    CallCharMethodV,
    CallCharMethodA,
    CallShortMethod,
    CallShortMethodV,
    CallShortMethodA,
    CallIntMethod,
    CallIntMethodV,
    CallIntMethodA,
    CallLongMethod,
    CallLongMethodV,
    CallLongMethodA,
    CallFloatMethod,
    CallFloatMethodV,
    CallFloatMethodA,
    CallDoubleMethod,
    CallDoubleMethodV,
    CallDoubleMethodA,
    CallVoidMethod,
    CallVoidMethodV,
    CallVoidMethodA,

    CallNonvirtualObjectMethod,
    CallNonvirtualObjectMethodV,
    CallNonvirtualObjectMethodA,
    CallNonvirtualBooleanMethod,
    CallNonvirtualBooleanMethodV,
    CallNonvirtualBooleanMethodA,
    CallNonvirtualByteMethod,
    CallNonvirtualByteMethodV,
    CallNonvirtualByteMethodA,
    CallNonvirtualCharMethod,
    CallNonvirtualCharMethodV,
    CallNonvirtualCharMethodA,
    CallNonvirtualShortMethod,
    CallNonvirtualShortMethodV,
    CallNonvirtualShortMethodA,
    CallNonvirtualIntMethod,
    CallNonvirtualIntMethodV,
    CallNonvirtualIntMethodA,
    CallNonvirtualLongMethod,
    CallNonvirtualLongMethodV,
    CallNonvirtualLongMethodA,
    CallNonvirtualFloatMethod,
    CallNonvirtualFloatMethodV,
    CallNonvirtualFloatMethodA,
    CallNonvirtualDoubleMethod,
    CallNonvirtualDoubleMethodV,
    CallNonvirtualDoubleMethodA,
    CallNonvirtualVoidMethod,
    CallNonvirtualVoidMethodV,
    CallNonvirtualVoidMethodA,

    GetFieldID,

    GetObjectField,
    GetBooleanField,
    GetByteField,
    GetCharField,
    GetShortField,
    GetIntField,
    GetLongField,
    GetFloatField,
    GetDoubleField,
    SetObjectField,
    SetBooleanField,
    SetByteField,
    SetCharField,
    SetShortField,
    SetIntField,
    SetLongField,
    SetFloatField,
    SetDoubleField,

    GetStaticMethodID,

    CallStaticObjectMethod,
    CallStaticObjectMethodV,
    CallStaticObjectMethodA,
    CallStaticBooleanMethod,
    CallStaticBooleanMethodV,
    CallStaticBooleanMethodA,
    CallStaticByteMethod,
    CallStaticByteMethodV,
    CallStaticByteMethodA,
    CallStaticCharMethod,
    CallStaticCharMethodV,
    CallStaticCharMethodA,
    CallStaticShortMethod,
    CallStaticShortMethodV,
    CallStaticShortMethodA,
    CallStaticIntMethod,
    CallStaticIntMethodV,
    CallStaticIntMethodA,
    CallStaticLongMethod,
    CallStaticLongMethodV,
    CallStaticLongMethodA,
    CallStaticFloatMethod,
    CallStaticFloatMethodV,
    CallStaticFloatMethodA,
    CallStaticDoubleMethod,
    CallStaticDoubleMethodV,
    CallStaticDoubleMethodA,
    CallStaticVoidMethod,
    CallStaticVoidMethodV,
    CallStaticVoidMethodA,

    GetStaticFieldID,

    GetStaticObjectField,
    GetStaticBooleanField,
    GetStaticByteField,
    GetStaticCharField,
    GetStaticShortField,
    GetStaticIntField,
    GetStaticLongField,
    GetStaticFloatField,
    GetStaticDoubleField,

    SetStaticObjectField,
    SetStaticBooleanField,
    SetStaticByteField,
    SetStaticCharField,
    SetStaticShortField,
    SetStaticIntField,
    SetStaticLongField,
    SetStaticFloatField,
    SetStaticDoubleField,

    NewString,

    GetStringLength,
    GetStringChars,
    ReleaseStringChars,

    NewStringUTF,
    GetStringUTFLength,
    GetStringUTFChars,
    ReleaseStringUTFChars,

    GetArrayLength,

    NewObjectArray,
    GetObjectArrayElement,
    SetObjectArrayElement,

    NewBooleanArray,
    NewByteArray,
    NewCharArray,
    NewShortArray,
    NewIntArray,
    NewLongArray,
    NewFloatArray,
    NewDoubleArray,

    GetBooleanArrayElements,
    GetByteArrayElements,
    GetCharArrayElements,
    GetShortArrayElements,
    GetIntArrayElements,
    GetLongArrayElements,
    GetFloatArrayElements,
    GetDoubleArrayElements,

    ReleaseBooleanArrayElements,
    ReleaseByteArrayElements,
    ReleaseCharArrayElements,
    ReleaseShortArrayElements,
    ReleaseIntArrayElements,
    ReleaseLongArrayElements,
    ReleaseFloatArrayElements,
    ReleaseDoubleArrayElements,

    GetBooleanArrayRegion,
    GetByteArrayRegion,
    GetCharArrayRegion,
    GetShortArrayRegion,
    GetIntArrayRegion,
    GetLongArrayRegion,
    GetFloatArrayRegion,
    GetDoubleArrayRegion,
    SetBooleanArrayRegion,
    SetByteArrayRegion,
    SetCharArrayRegion,
    SetShortArrayRegion,
    SetIntArrayRegion,
    SetLongArrayRegion,
    SetFloatArrayRegion,
    SetDoubleArrayRegion,

    RegisterNatives,
    UnregisterNatives,

    MonitorEnter,
    MonitorExit,

    GetJavaVM,

    GetStringRegion,
    GetStringUTFRegion,

    GetPrimitiveArrayCritical,
    ReleasePrimitiveArrayCritical,

    GetStringCritical,
    ReleaseStringCritical,

    NewWeakGlobalRef,
    DeleteWeakGlobalRef,

    ExceptionCheck,

    NewDirectByteBuffer,
    GetDirectBufferAddress,
    GetDirectBufferCapacity,

    GetObjectRefType
  };

Version Information

GetVersion

jint GetVersion(JNIEnv *env);

Returns the version of the native method interface.

LINKAGE:

Index 4 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

RETURNS:

Returns the major version number in the higher 16 bits and the minor version number in the lower 16 bits.

In JDK/JRE 1.1, GetVersion() returns 0x00010001.

In JDK/JRE 1.2, GetVersion() returns 0x00010002.

In JDK/JRE 1.4, GetVersion() returns 0x00010004.

In JDK/JRE 1.6, GetVersion() returns 0x00010006.

Constants

SINCE JDK/JRE 1.2:
#define JNI_VERSION_1_1 0x00010001
#define JNI_VERSION_1_2 0x00010002

/* Error codes */
#define JNI_EDETACHED    (-2)              /* thread detached from the VM */
#define JNI_EVERSION     (-3)              /* JNI version error
SINCE JDK/JRE 1.4:
    #define JNI_VERSION_1_4 0x00010004
SINCE JDK/JRE 1.6:
    #define JNI_VERSION_1_6 0x00010006

Class Operations

DefineClass

jclass DefineClass(JNIEnv *env, const char *name, jobject loader,
const jbyte *buf, jsize bufLen);

Loads a class from a buffer of raw class data. The buffer containing the raw class data is not referenced by the VM after the DefineClass call returns, and it may be discarded if desired.

LINKAGE:

Index 5 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

name: the name of the class or interface to be defined. The string is encoded in modified UTF-8.

loader: a class loader assigned to the defined class.

buf: buffer containing the .class file data.

bufLen: buffer length.

RETURNS:

Returns a Java class object or NULL if an error occurs.

THROWS:

ClassFormatError: if the class data does not specify a valid class.

ClassCircularityError: if a class or interface would be its own superclass or superinterface.

OutOfMemoryError: if the system runs out of memory.

FindClass

jclass FindClass(JNIEnv *env, const char *name);

In JDK release 1.1, this function loads a locally-defined class. It searches the directories and zip files specified by the CLASSPATH environment variable for the class with the specified name.

Since Java 2 SDK release 1.2, the Java security model allows non-system classes to load and call native methods. FindClass locates the class loader associated with the current native method; that is, the class loader of the class that declared the native method. If the native method belongs to a system class, no class loader will be involved. Otherwise, the proper class loader will be invoked to load and link the named class.

Since Java 2 SDK release 1.2, when FindClass is called through the Invocation Interface, there is no current native method or its associated class loader. In that case, the result of ClassLoader.getSystemClassLoader is used. This is the class loader the virtual machine creates for applications, and is able to locate classes listed in the java.class.path property.

The name argument is a fully-qualified class name or an array type signature . For example, the fully-qualified class name for the java.lang.String class is:

                   "java/lang/String"

The array type signature of the array class java.lang.Object[] is:

                   "[Ljava/lang/Object;"

LINKAGE:

Index 6 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

name: a fully-qualified class name (that is, a package name, delimited by “/”, followed by the class name). If the name begins with “[“ (the array signature character), it returns an array class. The string is encoded in modified UTF-8.

RETURNS:

Returns a class object from a fully-qualified name, or NULL if the class cannot be found.

THROWS:

ClassFormatError: if the class data does not specify a valid class.

ClassCircularityError: if a class or interface would be its own superclass or superinterface.

NoClassDefFoundError: if no definition for a requested class or interface can be found.

OutOfMemoryError: if the system runs out of memory.

GetSuperclass

jclass GetSuperclass(JNIEnv *env, jclass clazz);

If clazz represents any class other than the class Object, then this function returns the object that represents the superclass of the class specified by clazz.

If clazz specifies the class Object, or clazz represents an interface, this function returns NULL.

LINKAGE:

Index 10 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

RETURNS:

Returns the superclass of the class represented by clazz, or NULL.

IsAssignableFrom

jboolean IsAssignableFrom(JNIEnv *env, jclass clazz1,
jclass clazz2);

Determines whether an object of clazz1 can be safely cast to clazz2.

LINKAGE:

Index 11 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz1: the first class argument.

clazz2: the second class argument.

RETURNS:

Returns JNI_TRUE if either of the following is true:

  • The first and second class arguments refer to the same Java class.
  • The first class is a subclass of the second class.
  • The first class has the second class as one of its interfaces.

Exceptions

Throw

jint Throw(JNIEnv *env, jthrowable obj);

Causes a java.lang.Throwable object to be thrown.

LINKAGE:

Index 13 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

obj: a java.lang.Throwable object.

RETURNS:

Returns 0 on success; a negative value on failure.

THROWS:

the java.lang.Throwable object obj.

ThrowNew

jint ThrowNew(JNIEnv *env, jclass clazz,
const char *message);

Constructs an exception object from the specified class with the message specified by message and causes that exception to be thrown.

LINKAGE:

Index 14 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz: a subclass of java.lang.Throwable.

message: the message used to construct the java.lang.Throwable object. The string is encoded in modified UTF-8.

RETURNS:

Returns 0 on success; a negative value on failure.

THROWS:

the newly constructed java.lang.Throwable object.

ExceptionOccurred

jthrowable ExceptionOccurred(JNIEnv *env);

Determines if an exception is being thrown. The exception stays being thrown until either the native code calls ExceptionClear(), or the Java code handles the exception.

LINKAGE:

Index 15 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

RETURNS:

Returns the exception object that is currently in the process of being thrown, or NULL if no exception is currently being thrown.

ExceptionDescribe

void ExceptionDescribe(JNIEnv *env);

Prints an exception and a backtrace of the stack to a system error-reporting channel, such as stderr. This is a convenience routine provided for debugging.

LINKAGE:

Index 16 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

ExceptionClear

void ExceptionClear(JNIEnv *env);

Clears any exception that is currently being thrown. If no exception is currently being thrown, this routine has no effect.

LINKAGE:

Index 17 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

FatalError

void FatalError(JNIEnv *env, const char *msg);

Raises a fatal error and does not expect the VM to recover. This function does not return.

LINKAGE:

Index 18 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

msg: an error message. The string is encoded in modified UTF-8.

ExceptionCheck

We introduce a convenience function to check for pending exceptions without creating a local reference to the exception object.

jboolean ExceptionCheck(JNIEnv *env);

Returns JNI_TRUE when there is a pending exception; otherwise, returns JNI_FALSE.

LINKAGE:
Index 228 in the JNIEnv interface function table.
SINCE:

JDK/JRE 1.2

Global and Local References

Global References

NewGlobalRef

jobject NewGlobalRef(JNIEnv *env, jobject obj);

Creates a new global reference to the object referred to by the obj argument. The obj argument may be a global or local reference. Global references must be explicitly disposed of by calling DeleteGlobalRef().

LINKAGE:

Index 21 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

obj: a global or local reference.

RETURNS:

Returns a global reference, or NULL if the system runs out of memory.

DeleteGlobalRef

void DeleteGlobalRef(JNIEnv *env, jobject globalRef);

Deletes the global reference pointed to by globalRef.

LINKAGE:

Index 22 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

globalRef: a global reference.

Local References

Local references are valid for the duration of a native method call. They are freed automatically after the native method returns. Each local reference costs some amount of Java Virtual Machine resource. Programmers need to make sure that native methods do not excessively allocate local references. Although local references are automatically freed after the native method returns to Java, excessive allocation of local references may cause the VM to run out of memory during the execution of a native method.

DeleteLocalRef

void DeleteLocalRef(JNIEnv *env, jobject localRef);

Deletes the local reference pointed to by localRef.

LINKAGE:

Index 23 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

localRef: a local reference.

Note

JDK/JRE 1.1 provides the DeleteLocalRef function above so that programmers can manually delete local references. For example, if native code iterates through a potentially large array of objects and uses one element in each iteration, it is a good practice to delete the local reference to the no-longer-used array element before a new local reference is created in the next iteration.

As of JDK/JRE 1.2 an additional set of functions are provided for local reference lifetime management. They are the four functions listed below.

EnsureLocalCapacity

jint EnsureLocalCapacity(JNIEnv *env, jint capacity);

Ensures that at least a given number of local references can be created in the current thread. Returns 0 on success; otherwise returns a negative number and throws an OutOfMemoryError.

Before it enters a native method, the VM automatically ensures that at least 16 local references can be created.

For backward compatibility, the VM allocates local references beyond the ensured capacity. (As a debugging support, the VM may give the user warnings that too many local references are being created. In the JDK, the programmer can supply the -verbose:jni command line option to turn on these messages.) The VM calls FatalError if no more local references can be created beyond the ensured capacity.

LINKAGE:
Index 26 in the JNIEnv interface function table.
SINCE:

JDK/JRE 1.2

PushLocalFrame

jint PushLocalFrame(JNIEnv *env, jint capacity);

Creates a new local reference frame, in which at least a given number of local references can be created. Returns 0 on success, a negative number and a pending OutOfMemoryError on failure.

Note that local references already created in previous local frames are still valid in the current local frame.

LINKAGE:
Index 19 in the JNIEnv interface function table.
SINCE:

JDK/JRE 1.2

PopLocalFrame

jobject PopLocalFrame(JNIEnv *env, jobject result);

Pops off the current local reference frame, frees all the local references, and returns a local reference in the previous local reference frame for the given result object.

Pass NULL as result if you do not need to return a reference to the previous frame.

LINKAGE:
Index 20 in the JNIEnv interface function table.
SINCE:

JDK/JRE 1.2

NewLocalRef

jobject NewLocalRef(JNIEnv *env, jobject ref);

Creates a new local reference that refers to the same object as ref. The given ref may be a global or local reference. Returns NULL if ref refers to null.

LINKAGE:
Index 25 in the JNIEnv interface function table.
SINCE:

JDK/JRE 1.2

Weak Global References

Weak global references are a special kind of global reference. Unlike normal global references, a weak global reference allows the underlying Java object to be garbage collected. Weak global references may be used in any situation where global or local references are used. When the garbage collector runs, it frees the underlying object if the object is only referred to by weak references. A weak global reference pointing to a freed object is functionally equivalent to NULL. Programmers can detect whether a weak global reference points to a freed object by using IsSameObject to compare the weak reference against NULL.

Weak global references in JNI are a simplified version of the Java Weak References, available as part of the Java 2 Platform API ( java.lang.ref package and its classes).

Clarification (added June 2001)

Since garbage collection may occur while native methods are running, objects referred to by weak global references can be freed at any time. While weak global references can be used where global references are used, it is generally inappropriate to do so, as they may become functionally equivalent to NULL without notice.

While IsSameObject can be used to determine whether a weak global reference refers to a freed object, it does not prevent the object from being freed immediately thereafter. Consequently, programmers may not rely on this check to determine whether a weak global reference may used (as a non-NULL reference) in any future JNI function call.

To overcome this inherent limitation, it is recommended that a standard (strong) local or global reference to the same object be acquired using the JNI functions NewLocalRef or NewGlobalRef, and that this strong reference be used to access the intended object. These functions will return NULL if the object has been freed, and otherwise will return a strong reference (which will prevent the object from being freed). The new reference should be explicitly deleted when immediate access to the object is no longer required, allowing the object to be freed.

The weak global reference is weaker than other types of weak references (Java objects of the SoftReference or WeakReference classes). A weak global reference to a specific object will not become functionally equivalent to NULL until after SoftReference or WeakReference objects referring to that same specific object have had their references cleared.

The weak global reference is weaker than Java's internal references to objects requiring finalization. A weak global reference will not become functionally equivalent to NULL until after the completion of the the finalizer for the referenced object, if present.

Interactions between weak global references and PhantomReferences are undefined. In particular, implementations of a Java VM may (or may not) process weak global references after PhantomReferences, and it may (or may not) be possible to use weak global references to hold on to objects which are also referred to by PhantomReference objects. This undefined use of weak global references should be avoided.

NewWeakGlobalRef

jweak NewWeakGlobalRef(JNIEnv *env, jobject obj);

Creates a new weak global reference. Returns NULL if obj refers to null, or if the VM runs out of memory. If the VM runs out of memory, an OutOfMemoryError will be thrown.

LINKAGE:
Index 226 in the JNIEnv interface function table.
SINCE:

JDK/JRE 1.2

DeleteWeakGlobalRef

void DeleteWeakGlobalRef(JNIEnv *env, jweak obj);

Delete the VM resources needed for the given weak global reference.

LINKAGE:
Index 227 in the JNIEnv interface function table.
SINCE:

JDK/JRE 1.2

Object Operations

AllocObject

jobject AllocObject(JNIEnv *env, jclass clazz);

Allocates a new Java object without invoking any of the constructors for the object. Returns a reference to the object.

The clazz argument must not refer to an array class.

LINKAGE:

Index 27 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

RETURNS:

Returns a Java object, or NULL if the object cannot be constructed.

THROWS:

InstantiationException: if the class is an interface or an abstract class.

OutOfMemoryError: if the system runs out of memory.

NewObject
NewObjectA
NewObjectV

jobject NewObject(JNIEnv *env, jclass clazz,
jmethodID methodID, ...);

jobject NewObjectA(JNIEnv *env, jclass clazz,
jmethodID methodID, jvalue *args);

jobject NewObjectV(JNIEnv *env, jclass clazz,
jmethodID methodID, va_list args);

Constructs a new Java object. The method ID indicates which constructor method to invoke. This ID must be obtained by calling GetMethodID() with <init> as the method name and void (V) as the return type.

The clazz argument must not refer to an array class.

NewObject

Programmers place all arguments that are to be passed to the constructor immediately following the methodID argument. NewObject() accepts these arguments and passes them to the Java method that the programmer wishes to invoke.

LINKAGE:

Index 28 in the JNIEnv interface function table.

NewObjectA

Programmers place all arguments that are to be passed to the constructor in an args array of jvalues that immediately follows the methodID argument. NewObjectA() accepts the arguments in this array, and, in turn, passes them to the Java method that the programmer wishes to invoke.

LINKAGE:

Index 30 in the JNIEnv interface function table.

NewObjectV

Programmers place all arguments that are to be passed to the constructor in an args argument of type va_list that immediately follows the methodID argument. NewObjectV() accepts these arguments, and, in turn, passes them to the Java method that the programmer wishes to invoke.

LINKAGE:

Index 29 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

methodID: the method ID of the constructor.

Additional Parameter for NewObject:

arguments to the constructor.

Additional Parameter for NewObjectA:

args: an array of arguments to the constructor.

Additional Parameter for NewObjectV:

args: a va_list of arguments to the constructor.

RETURNS:

Returns a Java object, or NULL if the object cannot be constructed.

THROWS:

InstantiationException: if the class is an interface or an abstract class.

OutOfMemoryError: if the system runs out of memory.

Any exceptions thrown by the constructor.

GetObjectClass

jclass GetObjectClass(JNIEnv *env, jobject obj);

Returns the class of an object.

LINKAGE:

Index 31 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

obj: a Java object (must not be NULL).

RETURNS:

Returns a Java class object.

GetObjectRefType

jobjectRefType GetObjectRefType(JNIEnv* env, jobject obj);

Returns the type of the object referred to by the obj argument. The argument obj can either be a local, global or weak global reference.

LINKAGE:

Index 232 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

obj: a local, global or weak global reference.

vm: the virtual machine instance from which the interface will be retrieved.

env: pointer to the location where the JNI interface pointer for the current thread will be placed.

version: the requested JNI version.

RETURNS:

The function GetObjectRefType returns one of the following enumerated values defined as a jobjectRefType:

JNIInvalidRefType = 0,
JNILocalRefType = 1,
JNIGlobalRefType = 2,
JNIWeakGlobalRefType = 3

If the argument obj is a weak global reference type, the return will be JNIWeakGlobalRefType.

If the argument obj is a global reference type, the return value will be JNIGlobalRefType.

If the argument obj is a local reference type, the return will be JNILocalRefType.

If the obj argument is not a valid reference, the return value for this function will be JNIInvalidRefType.

An invalid reference is a reference which is not a valid handle. That is, the obj pointer address does not point to a location in memory which has been allocated from one of the Ref creation functions or returned from a JNI function.

As such, NULL would be an invalid reference and GetObjectRefType(env,NULL) would return JNIInvalidRefType.

On the other hand, a null reference, which is a reference that points to a null, would return the type of reference that the null reference was originally created as.

GetObjectRefType cannot be used on deleted references.

Since references are typically implemented as pointers to memory data structures that can potentially be reused by any of the reference allocation services in the VM, once deleted, it is not specified what value the GetObjectRefType will return.

SINCE:

JDK/JRE 1.6

IsInstanceOf

jboolean IsInstanceOf(JNIEnv *env, jobject obj,
jclass clazz);

Tests whether an object is an instance of a class.

LINKAGE:

Index 32 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

obj: a Java object.

clazz: a Java class object.

RETURNS:

Returns JNI_TRUE if obj can be cast to clazz; otherwise, returns JNI_FALSE. A NULL object can be cast to any class.

IsSameObject

jboolean IsSameObject(JNIEnv *env, jobject ref1,
jobject ref2);

Tests whether two references refer to the same Java object.

LINKAGE:

Index 24 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

ref1: a Java object.

ref2: a Java object.

RETURNS:

Returns JNI_TRUE if ref1 and ref2 refer to the same Java object, or are both NULL; otherwise, returns JNI_FALSE.

Accessing Fields of Objects

GetFieldID

jfieldID GetFieldID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

Returns the field ID for an instance (nonstatic) field of a class. The field is specified by its name and signature. The Get<type>Field and Set<type>Field families of accessor functions use field IDs to retrieve object fields.

GetFieldID() causes an uninitialized class to be initialized.

GetFieldID() cannot be used to obtain the length field of an array. Use GetArrayLength() instead.

LINKAGE:

Index 94 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

name: the field name in a 0-terminated modified UTF-8 string.

sig: the field signature in a 0-terminated modified UTF-8 string.

RETURNS:

Returns a field ID, or NULL if the operation fails.

THROWS:

NoSuchFieldError: if the specified field cannot be found.

ExceptionInInitializerError: if the class initializer fails due to an exception.

OutOfMemoryError: if the system runs out of memory.

Get<type>Field Routines

NativeType Get<type>Field(JNIEnv *env, jobject obj,
jfieldID fieldID);

This family of accessor routines returns the value of an instance (nonstatic) field of an object. The field to access is specified by a field ID obtained by calling GetFieldID().

The following table describes the Get<type>Field routine name and result type. You should replace type in Get<type>Field with the Java type of the field, or use one of the actual routine names from the table, and replace NativeType with the corresponding native type for that routine.

Table 4-1a Get<type>Field Family of Accessor Routines
Get<type>Field Routine Name | Native Type
GetObjectField() | jobject
GetBooleanField() | jboolean
GetByteField() | jbyte
GetCharField() | jchar
GetShortField() | jshort
GetIntField() | jint
GetLongField() | jlong
GetFloatField() | jfloat
GetDoubleField() | jdouble

LINKAGE:
Indices in the JNIEnv interface function table:

Table 4-1b Get<type>Field Family of Accessor Routines
Get<type>Field Routine Name | Index
GetObjectField() | 95
GetBooleanField() | 96
GetByteField() | 97
GetCharField() | 98
GetShortField() | 99
GetIntField() | 100
GetLongField() | 101
GetFloatField() | 102
GetDoubleField() | 103

PARAMETERS:

env: the JNI interface pointer.

obj: a Java object (must not be NULL).

fieldID: a valid field ID.

RETURNS:

Returns the content of the field.

Set<type>Field Routines

void Set<type>Field(JNIEnv *env, jobject obj, jfieldID fieldID,
NativeType value);

This family of accessor routines sets the value of an instance (nonstatic) field of an object. The field to access is specified by a field ID obtained by calling GetFieldID().

The following table describes the Set<type>Field routine name and value type. You should replace type in Set<type>Field with the Java type of the field, or use one of the actual routine names from the table, and replace NativeType with the corresponding native type for that routine.

Table 4-2a Set<type>Field Family of Accessor Routines
Set<type>Field Routine | Native Type
SetObjectField() | jobject
SetBooleanField() | jboolean
SetByteField() | jbyte
SetCharField() | jchar
SetShortField() | jshort
SetIntField() | jint
SetLongField() | jlong
SetFloatField() | jfloat
SetDoubleField() | jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-2b Set<type>Field Family of Accessor Routines
Set<type>Field Routine | Index
SetObjectField() | 104
SetBooleanField() | 105
SetByteField() | 106
SetCharField() | 107
SetShortField() | 108
SetIntField() | 109
SetLongField() | 110
SetFloatField() | 111
SetDoubleField() | 112
PARAMETERS:

env: the JNI interface pointer.

obj: a Java object (must not be NULL).

fieldID: a valid field ID.

value: the new value of the field.

Calling Instance Methods

GetMethodID

jmethodID GetMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

Returns the method ID for an instance (nonstatic) method of a class or interface. The method may be defined in one of the clazz’s superclasses and inherited by clazz. The method is determined by its name and signature.

GetMethodID() causes an uninitialized class to be initialized.

To obtain the method ID of a constructor, supply <init> as the method name and void (V) as the return type.

LINKAGE:

Index 33 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

name: the method name in a 0-terminated modified UTF-8 string.

sig: the method signature in 0-terminated modified UTF-8 string.

RETURNS:

Returns a method ID, or NULL if the specified method cannot be found.

THROWS:

NoSuchMethodError: if the specified method cannot be found.

ExceptionInInitializerError: if the class initializer fails due to an exception.

OutOfMemoryError: if the system runs out of memory.

Call<type>Method Routines
Call<type>MethodA Routines
Call<type>MethodV Routines

NativeType Call<type>Method(JNIEnv *env, jobject obj,
jmethodID methodID, ...);

NativeType Call<type>MethodA(JNIEnv *env, jobject obj,
jmethodID methodID, jvalue *args);

NativeType Call<type>MethodV(JNIEnv *env, jobject obj,
jmethodID methodID, va_list args);

Methods from these three families of operations are used to call a Java instance method from a native method.They only differ in their mechanism for passing parameters to the methods that they call.

These families of operations invoke an instance (nonstatic) method on a Java object, according to the specified method ID. The methodID argument must be obtained by calling GetMethodID().

When these functions are used to call private methods and constructors, the method ID must be derived from the real class of obj, not from one of its superclasses.

Call<type>Method Routines

Programmers place all arguments that are to be passed to the method immediately following the methodID argument. The Call<type>Method routine accepts these arguments and passes them to the Java method that the programmer wishes to invoke.

Call<type>MethodA Routines

Programmers place all arguments to the method in an args array of jvalues that immediately follows the methodID argument. The Call<type>MethodA routine accepts the arguments in this array, and, in turn, passes them to the Java method that the programmer wishes to invoke.

Call<type>MethodV Routines

Programmers place all arguments to the method in an args argument of type va_list that immediately follows the methodID argument. The Call<type>MethodV routine accepts the arguments, and, in turn, passes them to the Java method that the programmer wishes to invoke.

The following table describes each of the method calling routines according to their result type. You should replace type in Call<type>Method with the Java type of the method you are calling (or use one of the actual method calling routine names from the table) and replace NativeType with the corresponding native type for that routine.

Table 4-3a Instance Method Calling Routines
Call<type>Method Routine Name | Native Type
CallVoidMethod() CallVoidMethodA() CallVoidMethodV() | void
CallObjectMethod() CallObjectMethodA() CallObjectMethodV() | jobject
CallBooleanMethod() CallBooleanMethodA() CallBooleanMethodV() | jboolean
CallByteMethod() CallByteMethodA() CallByteMethodV() | jbyte
CallCharMethod() CallCharMethodA() CallCharMethodV() | jchar
CallShortMethod() CallShortMethodA() CallShortMethodV() | jshort
CallIntMethod() CallIntMethodA() CallIntMethodV() | jint
CallLongMethod() CallLongMethodA() CallLongMethodV() | jlong
CallFloatMethod() CallFloatMethodA() CallFloatMethodV() | jfloat
CallDoubleMethod() CallDoubleMethodA() CallDoubleMethodV() | jdouble

LINKAGE:

Indices in the JNIEnv interface function table:

Table 4-3b Instance Method Calling Routines
Call<type>Method Routine Name | Index
CallVoidMethod() CallVoidMethodA() CallVoidMethodV() | 61 63 62
CallObjectMethod() CallObjectMethodA() CallObjectMethodV() | 34 36 35
CallBooleanMethod() CallBooleanMethodA() CallBooleanMethodV() | 37 39 38
CallByteMethod() CallByteMethodA() CallByteMethodV() | 40 42 41
CallCharMethod() CallCharMethodA() CallCharMethodV() | 43 45 44
CallShortMethod() CallShortMethodA() CallShortMethodV() | 46 48 47
CallIntMethod() CallIntMethodA() CallIntMethodV() | 49 51 50
CallLongMethod() CallLongMethodA() CallLongMethodV() | 52 54 53
CallFloatMethod() CallFloatMethodA() CallFloatMethodV() | 55 57 56
CallDoubleMethod() CallDoubleMethodA() CallDoubleMethodV() | 58 60 59
PARAMETERS:

env: the JNI interface pointer.

obj: a Java object.

methodID: a method ID.

Additional Parameter for Call<type>Method Routines:

arguments to the Java method.

Additional Parameter for Call<type>MethodA Routines:

args: an array of arguments.

Additional Parameter for Call<type>MethodV Routines:

args: a va_list of arguments.

RETURNS:

Returns the result of calling the Java method.

THROWS:

Exceptions raised during the execution of the Java method.

CallNonvirtual<type>Method Routines
CallNonvirtual<type>MethodA Routines
CallNonvirtual<type>MethodV Routines

NativeType CallNonvirtual<type>Method(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, ...);

NativeType CallNonvirtual<type>MethodA(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, jvalue *args);

NativeType CallNonvirtual<type>MethodV(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, va_list args);

These families of operations invoke an instance (nonstatic) method on a Java object, according to the specified class and method ID. The methodID argument must be obtained by calling GetMethodID() on the class clazz.

The CallNonvirtual<type>Method families of routines and the Call<type>Method families of routines are different. Call<type>Method routines invoke the method based on the class of the object, while CallNonvirtual<type>Method routines invoke the method based on the class, designated by the clazz parameter, from which the method ID is obtained. The method ID must be obtained from the real class of the object or from one of its superclasses.

CallNonvirtual<type>Method Routines

Programmers place all arguments that are to be passed to the method immediately following the methodID argument. The CallNonvirtual<type>Method routine accepts these arguments and passes them to the Java method that the programmer wishes to invoke.

CallNonvirtual<type>MethodA Routines

Programmers place all arguments to the method in an args array of jvalues that immediately follows the methodID argument. The CallNonvirtual<type>MethodA routine accepts the arguments in this array, and, in turn, passes them to the Java method that the programmer wishes to invoke.

CallNonvirtual<type>MethodV Routines

Programmers place all arguments to the method in an args argument of type va_list that immediately follows the methodID argument. The CallNonvirtualMethodV routine accepts the arguments, and, in turn, passes them to the Java method that the programmer wishes to invoke.

The following table describes each of the method calling routines according to their result type. You should replace type in CallNonvirtual<type>Method with the Java type of the method, or use one of the actual method calling routine names from the table, and replace NativeType with the corresponding native type for that routine.

Table 4-4a CallNonvirtual<type>Method Routines
CallNonvirtual<type>Method Routine Name | Native Type
CallNonvirtualVoidMethod() CallNonvirtualVoidMethodA() CallNonvirtualVoidMethodV() | void
CallNonvirtualObjectMethod() CallNonvirtualObjectMethodA() CallNonvirtualObjectMethodV() | jobject
CallNonvirtualBooleanMethod() CallNonvirtualBooleanMethodA() CallNonvirtualBooleanMethodV() | jboolean
CallNonvirtualByteMethod() CallNonvirtualByteMethodA() CallNonvirtualByteMethodV() | jbyte
CallNonvirtualCharMethod() CallNonvirtualCharMethodA() CallNonvirtualCharMethodV() | jchar
CallNonvirtualShortMethod() CallNonvirtualShortMethodA() CallNonvirtualShortMethodV() | jshort
CallNonvirtualIntMethod() CallNonvirtualIntMethodA() CallNonvirtualIntMethodV() | jint
CallNonvirtualLongMethod() CallNonvirtualLongMethodA() CallNonvirtualLongMethodV() | jlong
CallNonvirtualFloatMethod() CallNonvirtualFloatMethodA() CallNonvirtualFloatMethodV() | jfloat
CallNonvirtualDoubleMethod() CallNonvirtualDoubleMethodA() CallNonvirtualDoubleMethodV() | jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-4b CallNonvirtual<type>Method Routines
CallNonvirtual<type>Method Routine Name | Index
CallNonvirtualVoidMethod() CallNonvirtualVoidMethodA() CallNonvirtualVoidMethodV() | 91 93 92
CallNonvirtualObjectMethod() CallNonvirtualObjectMethodA() CallNonvirtualObjectMethodV() | 64 66 65
CallNonvirtualBooleanMethod() CallNonvirtualBooleanMethodA() CallNonvirtualBooleanMethodV() | 67 69 68
CallNonvirtualByteMethod() CallNonvirtualByteMethodA() CallNonvirtualByteMethodV() | 70 72 71
CallNonvirtualCharMethod() CallNonvirtualCharMethodA() CallNonvirtualCharMethodV() | 73 75 74
CallNonvirtualShortMethod() CallNonvirtualShortMethodA() CallNonvirtualShortMethodV() | 76 78 77
CallNonvirtualIntMethod() CallNonvirtualIntMethodA() CallNonvirtualIntMethodV() | 79 81 80
CallNonvirtualLongMethod() CallNonvirtualLongMethodA() CallNonvirtualLongMethodV() | 82 84 83
CallNonvirtualFloatMethod() CallNonvirtualFloatMethodA() CallNonvirtualFloatMethodV() | 85 87 86
CallNonvirtualDoubleMethod() CallNonvirtualDoubleMethodA() CallNonvirtualDoubleMethodV() | 88 90 89
PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class.

obj: a Java object.

methodID: a method ID.

Additional Parameter for CallNonvirtual<type>Method Routines:

arguments to the Java method.

Additional Parameter for CallNonvirtual<type>MethodA Routines:

args: an array of arguments.

Additional Parameter for CallNonvirtual<type>MethodV Routines:

args: a va_list of arguments.

RETURNS:

Returns the result of calling the Java method.

THROWS:

Exceptions raised during the execution of the Java method.

Accessing Static Fields

GetStaticFieldID

jfieldID GetStaticFieldID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

Returns the field ID for a static field of a class. The field is specified by its name and signature. The GetStatic<type>Field and SetStatic<type>Field families of accessor functions use field IDs to retrieve static fields.

GetStaticFieldID() causes an uninitialized class to be initialized.

LINKAGE:

Index 144 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

name: the static field name in a 0-terminated modified UTF-8 string.

sig: the field signature in a 0-terminated modified UTF-8 string.

RETURNS:

Returns a field ID, or NULL if the specified static field cannot be found.

THROWS:

NoSuchFieldError: if the specified static field cannot be found.

ExceptionInInitializerError: if the class initializer fails due to an exception.

OutOfMemoryError: if the system runs out of memory.

GetStatic<type>Field Routines

NativeType GetStatic<type>Field(JNIEnv *env, jclass clazz,
jfieldID fieldID);

This family of accessor routines returns the value of a static field of an object. The field to access is specified by a field ID, which is obtained by calling GetStaticFieldID().

The following table describes the family of get routine names and result types. You should replace type in GetStatic<type>Field with the Java type of the field, or one of the actual static field accessor routine names from the table, and replace NativeType with the corresponding native type for that routine.

Table 4-5a GetStatic<type>Field Family of Accessor Routines
GetStatic<type>Field Routine Name | Native Type
GetStaticObjectField() | jobject
GetStaticBooleanField() | jboolean
GetStaticByteField() | jbyte
GetStaticCharField() | jchar
GetStaticShortField() | jshort
GetStaticIntField() | jint
GetStaticLongField() | jlong
GetStaticFloatField() | jfloat
GetStaticDoubleField() | jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-5b GetStatic<type>Field Family of Accessor Routines
GetStatic<type>Field Routine Name | Index
GetStaticObjectField() | 145
GetStaticBooleanField() | 146
GetStaticByteField() | 147
GetStaticCharField() | 148
GetStaticShortField() | 149
GetStaticIntField() | 150
GetStaticLongField() | 151
GetStaticFloatField() | 152
GetStaticDoubleField() | 153
PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

fieldID: a static field ID.

RETURNS:

Returns the content of the static field.

SetStatic<type>Field Routines

void SetStatic<type>Field(JNIEnv *env, jclass clazz,
jfieldID fieldID, NativeType value);

This family of accessor routines sets the value of a static field of an object. The field to access is specified by a field ID, which is obtained by calling GetStaticFieldID().

The following table describes the set routine name and value types. You should replace type in SetStatic<type>Field with the Java type of the field, or one of the actual set static field routine names from the table, and replace NativeType with the corresponding native type for that routine.

Table 4-6a SetStatic<type>Field Family of Accessor Routines
SetStatic<type>Field Routine Name | NativeType
SetStaticObjectField() | jobject
SetStaticBooleanField() | jboolean
SetStaticByteField() | jbyte
SetStaticCharField() | jchar
SetStaticShortField() | jshort
SetStaticIntField() | jint
SetStaticLongField() | jlong
SetStaticFloatField() | jfloat
SetStaticDoubleField() | jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-6b SetStatic<type>Field Family of Accessor Routines
SetStatic<type>Field Routine Name | Index
SetStaticObjectField() | 154
SetStaticBooleanField() | 155
SetStaticByteField() | 156
SetStaticCharField() | 157
SetStaticShortField() | 158
SetStaticIntField() | 159
SetStaticLongField() | 160
SetStaticFloatField() | 161
SetStaticDoubleField() | 162
PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

fieldID: a static field ID.

value: the new value of the field.

Calling Static Methods

GetStaticMethodID

jmethodID GetStaticMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

Returns the method ID for a static method of a class. The method is specified by its name and signature.

GetStaticMethodID() causes an uninitialized class to be initialized.

LINKAGE:
Index 113 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

name: the static method name in a 0-terminated modified UTF-8 string.

sig: the method signature in a 0-terminated modified UTF-8 string.

RETURNS:

Returns a method ID, or NULL if the operation fails.

THROWS:

NoSuchMethodError: if the specified static method cannot be found.

ExceptionInInitializerError: if the class initializer fails due to an exception.

OutOfMemoryError: if the system runs out of memory.

CallStatic<type>Method Routines
CallStatic<type>MethodA Routines
CallStatic<type>MethodV Routines

NativeType CallStatic<type>Method(JNIEnv *env, jclass clazz,
jmethodID methodID, ...);

NativeType CallStatic<type>MethodA(JNIEnv *env, jclass clazz,
jmethodID methodID, jvalue *args);

NativeType CallStatic<type>MethodV(JNIEnv *env, jclass clazz,
jmethodID methodID, va_list args);

This family of operations invokes a static method on a Java object, according to the specified method ID. The methodID argument must be obtained by calling GetStaticMethodID().

The method ID must be derived from clazz, not from one of its superclasses.

CallStatic<type>Method Routines

Programmers should place all arguments that are to be passed to the method immediately following the methodID argument. The CallStatic<type>Method routine accepts these arguments and passes them to the Java method that the programmer wishes to invoke.

CallStatic<type>MethodA Routines

Programmers should place all arguments to the method in an args array of jvalues that immediately follows the methodID argument. The CallStaticMethodA routine accepts the arguments in this array, and, in turn, passes them to the Java method that the programmer wishes to invoke.

CallStatic<type>MethodV Routines

Programmers should place all arguments to the method in an args argument of type va_list that immediately follows the methodID argument. The CallStaticMethodV routine accepts the arguments, and, in turn, passes them to the Java method that the programmer wishes to invoke.

The following table describes each of the method calling routines according to their result types. You should replace type in CallStatic<type>Method with the Java type of the method, or one of the actual method calling routine names from the table, and replace NativeType with the corresponding native type for that routine.

Table 4-7a CallStatic<type>Method Calling Routines
CallStatic<type>Method Routine Name | Native Type
CallStaticVoidMethod() CallStaticVoidMethodA() CallStaticVoidMethodV() | void
CallStaticObjectMethod() CallStaticObjectMethodA() CallStaticObjectMethodV() | jobject
CallStaticBooleanMethod() CallStaticBooleanMethodA() CallStaticBooleanMethodV() | jboolean
CallStaticByteMethod() CallStaticByteMethodA() CallStaticByteMethodV() | jbyte
CallStaticCharMethod() CallStaticCharMethodA() CallStaticCharMethodV() | jchar
CallStaticShortMethod() CallStaticShortMethodA() CallStaticShortMethodV() | jshort
CallStaticIntMethod() CallStaticIntMethodA() CallStaticIntMethodV() | jint
CallStaticLongMethod() CallStaticLongMethodA() CallStaticLongMethodV() | jlong
CallStaticFloatMethod() CallStaticFloatMethodA() CallStaticFloatMethodV() | jfloat
CallStaticDoubleMethod() CallStaticDoubleMethodA() CallStaticDoubleMethodV() | jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-7b CallStatic<type>Method Calling Routines
CallStatic<type>Method Routine Name | Index
CallStaticVoidMethod() CallStaticVoidMethodA() CallStaticVoidMethodV() | 141 143 142
CallStaticObjectMethod() CallStaticObjectMethodA() CallStaticObjectMethodV() | 114 116 115
CallStaticBooleanMethod() CallStaticBooleanMethodA() CallStaticBooleanMethodV() | 117 119 118
CallStaticByteMethod() CallStaticByteMethodA() CallStaticByteMethodV() | 120 122 121
CallStaticCharMethod() CallStaticCharMethodA() CallStaticCharMethodV() | 123 125 124
CallStaticShortMethod() CallStaticShortMethodA() CallStaticShortMethodV() | 126 128 127
CallStaticIntMethod() CallStaticIntMethodA() CallStaticIntMethodV() | 129 131 130
CallStaticLongMethod() CallStaticLongMethodA() CallStaticLongMethodV() | 132 134 133
CallStaticFloatMethod() CallStaticFloatMethodA() CallStaticFloatMethodV() | 135 137 136
CallStaticDoubleMethod() CallStaticDoubleMethodA() CallStaticDoubleMethodV() | 138 140 139
PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

methodID: a static method ID.

Additional Parameter for CallStatic<type>Method Routines:

arguments to the static method.

Additional Parameter for CallStatic<type>MethodA Routines:

args: an array of arguments.

Additional Parameter for CallStatic<type>MethodV Routines:

args: a va_list of arguments.

RETURNS:

Returns the result of calling the static Java method.

THROWS:

Exceptions raised during the execution of the Java method.

String Operations

NewString

jstring NewString(JNIEnv *env, const jchar *unicodeChars,
jsize len);

Constructs a new java.lang.String object from an array of Unicode characters.

LINKAGE:
Index 163 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

unicodeChars: pointer to a Unicode string.

len: length of the Unicode string.

RETURNS:

Returns a Java string object, or NULL if the string cannot be constructed.

THROWS:

OutOfMemoryError: if the system runs out of memory.

GetStringLength

jsize GetStringLength(JNIEnv *env, jstring string);

Returns the length (the count of Unicode characters) of a Java string.

LINKAGE:
Index 164 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

string: a Java string object.

RETURNS:

Returns the length of the Java string.

GetStringChars

const jchar * GetStringChars(JNIEnv *env, jstring string,
jboolean *isCopy);

Returns a pointer to the array of Unicode characters of the string. This pointer is valid until ReleaseStringchars() is called.

If isCopy is not NULL, then *isCopy is set to JNI_TRUE if a copy is made; or it is set to JNI_FALSE if no copy is made.

LINKAGE:
Index 165 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

string: a Java string object.

isCopy: a pointer to a boolean.

RETURNS:

Returns a pointer to a Unicode string, or NULL if the operation fails.

ReleaseStringChars

void ReleaseStringChars(JNIEnv *env, jstring string,
const jchar *chars);

Informs the VM that the native code no longer needs access to chars. The chars argument is a pointer obtained from string using GetStringChars().

LINKAGE:
Index 166 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

string: a Java string object.

chars: a pointer to a Unicode string.

NewStringUTF

jstring NewStringUTF(JNIEnv *env, const char *bytes);

Constructs a new java.lang.String object from an array of characters in modified UTF-8 encoding.

LINKAGE:
Index 167 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

bytes: the pointer to a modified UTF-8 string.

RETURNS:

Returns a Java string object, or NULL if the string cannot be constructed.

THROWS:

OutOfMemoryError: if the system runs out of memory.

GetStringUTFLength

jsize GetStringUTFLength(JNIEnv *env, jstring string);

Returns the length in bytes of the modified UTF-8 representation of a string.

LINKAGE:
Index 168 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

string: a Java string object.

RETURNS:

Returns the UTF-8 length of the string.

GetStringUTFChars

const jbyte* GetStringUTFChars(JNIEnv *env, jstring string,
jboolean *isCopy);

Returns a pointer to an array of bytes representing the string in modified UTF-8 encoding. This array is valid until it is released by ReleaseStringUTFChars().

If isCopy is not NULL, then *isCopy is set to JNI_TRUE if a copy is made; or it is set to JNI_FALSE if no copy is made.

LINKAGE:
Index 169 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

string: a Java string object.

isCopy: a pointer to a boolean.

RETURNS:

Returns a pointer to a modified UTF-8 string, or NULL if the operation fails.

ReleaseStringUTFChars

void ReleaseStringUTFChars(JNIEnv *env, jstring string,
const char *utf);

Informs the VM that the native code no longer needs access to utf. The utf argument is a pointer derived from string using GetStringUTFChars().

LINKAGE:
Index 170 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

string: a Java string object.

utf: a pointer to a modified UTF-8 string.

Note

In JDK/JRE 1.1, programmers can get primitive array elements in a user-supplied buffer. As of JDK/JRE 1.2 additional set of functions are provided allowing native code to obtain characters in Unicode (UTF-16) or modified UTF-8 encoding in a user-supplied buffer. See the functions below.

GetStringRegion

void GetStringRegion(JNIEnv *env, jstring str, jsize start, jsize len, jchar *buf);

Copies len number of Unicode characters beginning at offset start to the given buffer buf.

Throws StringIndexOutOfBoundsException on index overflow.

LINKAGE:
Index 220 in the JNIEnv interface function table.
SINCE:

JDK/JRE 1.2

GetStringUTFRegion

< void GetStringUTFRegion(JNIEnv *env, jstring str, jsize start, jsize len, char *buf);

Translates len number of Unicode characters beginning at offset start into modified UTF-8 encoding and place the result in the given buffer buf.

Throws StringIndexOutOfBoundsException on index overflow.

LINKAGE:
Index 221 in the JNIEnv interface function table.
SINCE:

JDK/JRE 1.2

GetStringCritical
ReleaseStringCritical

const jchar * GetStringCritical(JNIEnv *env, jstring string, jboolean *isCopy);
void ReleaseStringCritical(JNIEnv *env, jstring string, const jchar *carray);

The semantics of these two functions are similar to the existing Get/ReleaseStringChars functions. If possible, the VM returns a pointer to string elements; otherwise, a copy is made. However, there are significant restrictions on how these functions can be used. In a code segment enclosed by Get/ReleaseStringCritical calls, the native code must not issue arbitrary JNI calls, or cause the current thread to block.

The restrictions on Get/ReleaseStringCritical are similar to those on Get/ReleasePrimitiveArrayCritical.

LINKAGE (GetStringCritical):
Index 224 in the JNIEnv interface function table.
LINKAGE (ReleaseStingCritical):
Index 225 in the JNIEnv interface function table.
SINCE:

JDK/JRE 1.2

Array Operations

GetArrayLength

jsize GetArrayLength(JNIEnv *env, jarray array);

Returns the number of elements in the array.

LINKAGE:
Index 171 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

array: a Java array object.

RETURNS:

Returns the length of the array.

NewObjectArray

jobjectArray NewObjectArray(JNIEnv *env, jsize length,
jclass elementClass, jobject initialElement);

Constructs a new array holding objects in class elementClass. All elements are initially set to initialElement.

LINKAGE:
Index 172 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

length: array size.

elementClass: array element class.

initialElement: initialization value.

RETURNS:

Returns a Java array object, or NULL if the array cannot be constructed.

THROWS:

OutOfMemoryError: if the system runs out of memory.

GetObjectArrayElement

jobject GetObjectArrayElement(JNIEnv *env,
jobjectArray array, jsize index);

Returns an element of an Object array.

LINKAGE:
Index 173 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

array: a Java array.

index: array index.

RETURNS:

Returns a Java object.

THROWS:

ArrayIndexOutOfBoundsException: if index does not specify a valid index in the array.

SetObjectArrayElement

void SetObjectArrayElement(JNIEnv *env, jobjectArray array,
jsize index, jobject value);

Sets an element of an Object array.

LINKAGE:
Index 174 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

array: a Java array.

index: array index.

value: the new value.

THROWS:

ArrayIndexOutOfBoundsException: if index does not specify a valid index in the array.

ArrayStoreException: if the class of value is not a subclass of the element class of the array.

New<PrimitiveType>Array Routines

ArrayType New<PrimitiveType>Array(JNIEnv *env, jsize length);

A family of operations used to construct a new primitive array object. Table 4-8 describes the specific primitive array constructors. You should replace New<PrimitiveType>Array with one of the actual primitive array constructor routine names from the following table, and replace ArrayType with the corresponding array type for that routine.

Table 4-8a New<PrimitiveType>Array Family of Array Constructors
New<PrimitiveType>Array Routines | Array Type
NewBooleanArray() | jbooleanArray
NewByteArray() | jbyteArray
NewCharArray() | jcharArray
NewShortArray() | jshortArray
NewIntArray() | jintArray
NewLongArray() | jlongArray
NewFloatArray() | jfloatArray
NewDoubleArray() | jdoubleArray

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-8b New<PrimitiveType>Array Family of Array Constructors
New<PrimitiveType>Array Routines | Index
NewBooleanArray() | 175
NewByteArray() | 176
NewCharArray() | 177
NewShortArray() | 178
NewIntArray() | 179
NewLongArray() | 180
NewFloatArray() | 181
NewDoubleArray() | 182
PARAMETERS:

env: the JNI interface pointer.

length: the array length.

RETURNS:

Returns a Java array, or NULL if the array cannot be constructed.

Get<PrimitiveType>ArrayElements Routines

NativeType *Get<PrimitiveType>ArrayElements(JNIEnv *env,
ArrayType array, jboolean *isCopy);

A family of functions that returns the body of the primitive array. The result is valid until the corresponding Release<PrimitiveType>ArrayElements() function is called. Since the returned array may be a copy of the Java array, changes made to the returned array will not necessarily be reflected in the original array until Release<PrimitiveType>ArrayElements() is called.

If isCopy is not NULL, then *isCopy is set to JNI_TRUE if a copy is made; or it is set to JNI_FALSE if no copy is made.

The following table describes the specific primitive array element accessors. You should make the following substitutions:

  • Replace Get<PrimitiveType>ArrayElements with one of the actual primitive element accessor routine names from the table.
  • Replace ArrayType with the corresponding array type.
  • Replace NativeType with the corresponding native type for that routine.

Regardless of how boolean arrays are represented in the Java VM, GetBooleanArrayElements() always returns a pointer to jbooleans, with each byte denoting an element (the unpacked representation). All arrays of other types are guaranteed to be contiguous in memory.

Table 4-9a Get<PrimitiveType>ArrayElements Family of Accessor Routines
Get<PrimitiveType>ArrayElements Routines | Array Type | Native Type
GetBooleanArrayElements() | jbooleanArray | jboolean
GetByteArrayElements() | jbyteArray | jbyte
GetCharArrayElements() | jcharArray | jchar
GetShortArrayElements() | jshortArray | jshort
GetIntArrayElements() | jintArray | jint
GetLongArrayElements() | jlongArray | jlong
GetFloatArrayElements() | jfloatArray | jfloat
GetDoubleArrayElements() | jdoubleArray | jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-9b Get<PrimitiveType>ArrayElements Family of Accessor Routines
Get<PrimitiveType>ArrayElements Routines | Index
GetBooleanArrayElements() | 183
GetByteArrayElements() | 184
GetCharArrayElements() | 185
GetShortArrayElements() | 186
GetIntArrayElements() | 187
GetLongArrayElements() | 188
GetFloatArrayElements() | 189
GetDoubleArrayElements() | 190
PARAMETERS:

env: the JNI interface pointer.

array: a Java string object.

isCopy: a pointer to a boolean.

RETURNS:

Returns a pointer to the array elements, or NULL if the operation fails.

Release<PrimitiveType>ArrayElements Routines

void Release<PrimitiveType>ArrayElements(JNIEnv *env,
ArrayType array, NativeType *elems, jint mode);

A family of functions that informs the VM that the native code no longer needs access to elems. The elems argument is a pointer derived from array using the corresponding Get<PrimitiveType>ArrayElements() function. If necessary, this function copies back all changes made to elems to the original array.

The mode argument provides information on how the array buffer should be released. mode has no effect if elems is not a copy of the elements in array. Otherwise, mode has the following impact, as shown in the following table:

Table 4-10 Primitive Array Release Modes
mode | actions
0 | copy back the content and free the elems buffer
JNI_COMMIT | copy back the content but do not free the elems buffer
JNI_ABORT | free the buffer without copying back the possible changes

In most cases, programmers pass “0” to the mode argument to ensure consistent behavior for both pinned and copied arrays. The other options give the programmer more control over memory management and should be used with extreme care.

The next table describes the specific routines that comprise the family of primitive array disposers. You should make the following substitutions:

  • Replace Release<PrimitiveType>ArrayElements with one of the actual primitive array disposer routine names from Table 4-11.
  • Replace ArrayType with the corresponding array type.
  • Replace NativeType with the corresponding native type for that routine.

Table 4-11a Release<PrimitiveType>ArrayElements Family of Array Routines
Release<PrimitiveType>ArrayElements Routines | Array Type | Native Type
ReleaseBooleanArrayElements() | jbooleanArray | jboolean
ReleaseByteArrayElements() | jbyteArray | jbyte
ReleaseCharArrayElements() | jcharArray | jchar
ReleaseShortArrayElements() | jshortArray | jshort
ReleaseIntArrayElements() | jintArray | jint
ReleaseLongArrayElements() | jlongArray | jlong
ReleaseFloatArrayElements() | jfloatArray | jfloat
ReleaseDoubleArrayElements() | jdoubleArray | jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-11b Release<PrimitiveType>ArrayElements Family of Array Routines
Release<PrimitiveType>ArrayElements Routines | Index
ReleaseBooleanArrayElements() | 191
ReleaseByteArrayElements() | 192
ReleaseCharArrayElements() | 193
ReleaseShortArrayElements() | 194
ReleaseIntArrayElements() | 195
ReleaseLongArrayElements() | 196
ReleaseFloatArrayElements() | 197
ReleaseDoubleArrayElements() | 198
PARAMETERS:

env: the JNI interface pointer.

array: a Java array object.

elems: a pointer to array elements.

mode: the release mode.

Get<PrimitiveType>ArrayRegion Routines

void Get<PrimitiveType>ArrayRegion(JNIEnv *env, ArrayType array,
jsize start, jsize len, NativeType *buf);

A family of functions that copies a region of a primitive array into a buffer.

The following table describes the specific primitive array element accessors. You should do the following substitutions:

  • Replace Get<PrimitiveType>ArrayRegion with one of the actual primitive element accessor routine names from Table 4-12.
  • Replace ArrayType with the corresponding array type.
  • Replace NativeType with the corresponding native type for that routine.

Table 4-12a Get<PrimitiveType>ArrayRegion Family of Array Accessor Routines
Get<PrimitiveType>ArrayRegion Routine | Array Type | Native Type
GetBooleanArrayRegion() | jbooleanArray | jboolean
GetByteArrayRegion() | jbyteArray | jbyte
GetCharArrayRegion() | jcharArray | jchar
GetShortArrayRegion() | jshortArray | jhort
GetIntArrayRegion() | jintArray | jint
GetLongArrayRegion() | jlongArray | jlong
GetFloatArrayRegion() | jfloatArray | jloat
GetDoubleArrayRegion() | jdoubleArray | jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-12b Get<PrimitiveType>ArrayRegion Family of Array Accessor Routines
Get<PrimitiveType>ArrayRegion Routine | Index
GetBooleanArrayRegion() | 199
GetByteArrayRegion() | 200
GetCharArrayRegion() | 201
GetShortArrayRegion() | 202
GetIntArrayRegion() | 203
GetLongArrayRegion() | 204
GetFloatArrayRegion() | 205
GetDoubleArrayRegion() | 206
PARAMETERS:

env: the JNI interface pointer.

array: a Java array.

start: the starting index.

len: the number of elements to be copied.

buf: the destination buffer.

THROWS:

ArrayIndexOutOfBoundsException: if one of the indexes in the region is not valid.

Set<PrimitiveType>ArrayRegion Routines

void Set<PrimitiveType>ArrayRegion(JNIEnv *env, ArrayType array,
jsize start, jsize len, NativeType *buf);

A family of functions that copies back a region of a primitive array from a buffer.

The following table describes the specific primitive array element accessors. You should make the following replacements:

  • Replace Set<PrimitiveType>ArrayRegion with one of the actual primitive element accessor routine names from the table.
  • Replace ArrayType with the corresponding array type.
  • Replace NativeType with the corresponding native type for that routine.
    Table 4-13a Set<PrimitiveType>ArrayRegion Family of Array Accessor Routines
    Set<PrimitiveType>ArrayRegion Routine
    Array Type
    Native Type
    SetBooleanArrayRegion()
    jbooleanArray
    jboolean
    SetByteArrayRegion()
    jbyteArray
    jbyte
    SetCharArrayRegion()
    jcharArray
    jchar
    SetShortArrayRegion()
    jshortArray
    jshort
    SetIntArrayRegion()
    jintArray
    jint
    SetLongArrayRegion()
    jlongArray
    jlong
    SetFloatArrayRegion()
    jfloatArray
    jfloat
    SetDoubleArrayRegion()
    jdoubleArray
    jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-13b Set<PrimitiveType>ArrayRegion Family of Array Accessor Routines
Set<PrimitiveType>ArrayRegion Routine | Index
SetBooleanArrayRegion() | 207
SetByteArrayRegion() | 208
SetCharArrayRegion() | 209
SetShortArrayRegion() | 210
SetIntArrayRegion() | 211
SetLongArrayRegion() | 212
SetFloatArrayRegion() | 213
SetDoubleArrayRegion() | 214

PARAMETERS:

env: the JNI interface pointer.

array: a Java array.

start: the starting index.

len: the number of elements to be copied.

buf: the source buffer.

THROWS:

ArrayIndexOutOfBoundsException: if one of the indexes in the region is not valid.

Note

As of JDK/JRE 1.1, programmers can use Get/ReleaseArrayElements functions to obtain a pointer to primitive array elements. If the VM supports pinning, the pointer to the original data is returned; otherwise, a copy is made.

New functions introduced as of JDK/JRE 1.3 allow native code to obtain a direct pointer to array elements even if the VM does not support pinning.

GetPrimitiveArrayCritical
ReleasePrimitiveArrayCritical

void * GetPrimitiveArrayCritical(JNIEnv *env, jarray array, jboolean *isCopy);
void ReleasePrimitiveArrayCritical(JNIEnv *env, jarray array, void *carray, jint mode);

The semantics of these two functions are very similar to the existing Get/ReleaseArrayElements functions. If possible, the VM returns a pointer to the primitive array; otherwise, a copy is made. However, there are significant restrictions on how these functions can be used.

After calling GetPrimitiveArrayCritical, the native code should not run for an extended period of time before it calls ReleasePrimitiveArrayCritical. We must treat the code inside this pair of functions as running in a "critical region." Inside a critical region, native code must not call other JNI functions, or any system call that may cause the current thread to block and wait for another Java thread. (For example, the current thread must not call read on a stream being written by another Java thread.)

These restrictions make it more likely that the native code will obtain an uncopied version of the array, even if the VM does not support pinning. For example, a VM may temporarily disable garbage collection when the native code is holding a pointer to an array obtained via GetPrimitiveArrayCritical.

Multiple pairs of GetPrimtiveArrayCritical and ReleasePrimitiveArrayCritical may be nested. For example:

  jint len = (*env)->GetArrayLength(env, arr1);
  jbyte *a1 = (*env)->GetPrimitiveArrayCritical(env, arr1, 0);
  jbyte *a2 = (*env)->GetPrimitiveArrayCritical(env, arr2, 0);
  /* We need to check in case the VM tried to make a copy. */
  if (a1 == NULL || a2 == NULL) {
    ... /* out of memory exception thrown */
  }
  memcpy(a1, a2, len);
  (*env)->ReleasePrimitiveArrayCritical(env, arr2, a2, 0);
  (*env)->ReleasePrimitiveArrayCritical(env, arr1, a1, 0);

Note that GetPrimitiveArrayCritical might still make a copy of the array if the VM internally represents arrays in a different format. Therefore we need to check its return value against NULL for possible out of memory situations.

LINKAGE (GetPrimitiveArrayCritical):

Linkage Index 222 in the JNIEnv interface function table.

LINKAGE (ReleasePrimitiveArrayCritical):

Linkage Index 223 in the JNIEnv interface function table.

SINCE:

JDK/JRE 1.2

Registering Native Methods

RegisterNatives

jint RegisterNatives(JNIEnv *env, jclass clazz,
const JNINativeMethod *methods, jint nMethods);

Registers native methods with the class specified by the clazz argument. The methods parameter specifies an array of JNINativeMethod structures that contain the names, signatures, and function pointers of the native methods. The name and signature fields of the JNINativeMethod structure are pointers to modified UTF-8 strings. The nMethods parameter specifies the number of native methods in the array. The JNINativeMethod structure is defined as follows:

typedef struct {

    char *name;

    char *signature;

    void *fnPtr;

} JNINativeMethod;

The function pointers nominally must have the following signature:

ReturnType (*fnPtr)(JNIEnv *env, jobject objectOrClass, ...);

LINKAGE:

Index 215 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

methods: the native methods in the class.

nMethods: the number of native methods in the class.

RETURNS:

Returns “0” on success; returns a negative value on failure.

THROWS:

NoSuchMethodError: if a specified method cannot be found or if the method is not native.

UnregisterNatives

jint UnregisterNatives(JNIEnv *env, jclass clazz);

Unregisters native methods of a class. The class goes back to the state before it was linked or registered with its native method functions.

This function should not be used in normal native code. Instead, it provides special programs a way to reload and relink native libraries.

LINKAGE:
Index 216 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

RETURNS:

Returns “0” on success; returns a negative value on failure.

Monitor Operations

MonitorEnter

jint MonitorEnter(JNIEnv *env, jobject obj);

Enters the monitor associated with the underlying Java object referred to by obj.

Enters the monitor associated with the object referred to by obj. The obj reference must not be NULL.

Each Java object has a monitor associated with it. If the current thread already owns the monitor associated with obj, it increments a counter in the monitor indicating the number of times this thread has entered the monitor. If the monitor associated with obj is not owned by any thread, the current thread becomes the owner of the monitor, setting the entry count of this monitor to 1. If another thread already owns the monitor associated with obj, the current thread waits until the monitor is released, then tries again to gain ownership.

A monitor entered through a MonitorEnter JNI function call cannot be exited using the monitorexit Java virtual machine instruction or a synchronized method return. A MonitorEnter JNI function call and a monitorenter Java virtual machine instruction may race to enter the monitor associated with the same object.

To avoid deadlocks, a monitor entered through a MonitorEnter JNI function call must be exited using the MonitorExit JNI call, unless the DetachCurrentThread call is used to implicitly release JNI monitors.

LINKAGE:
Index 217 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

obj: a normal Java object or class object.

RETURNS:

Returns “0” on success; returns a negative value on failure.

MonitorExit

jint MonitorExit(JNIEnv *env, jobject obj);

The current thread must be the owner of the monitor associated with the underlying Java object referred to by obj. The thread decrements the counter indicating the number of times it has entered this monitor. If the value of the counter becomes zero, the current thread releases the monitor.

Native code must not use MonitorExit to exit a monitor entered through a synchronized method or a monitorenter Java virtual machine instruction.

LINKAGE:
Index 218 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

obj: a normal Java object or class object.

RETURNS:

Returns “0” on success; returns a negative value on failure.

EXCEPTIONS:

IllegalMonitorStateException: if the current thread does not own the monitor.

NIO Support

The NIO-related entry points allow native code to access java.nio direct buffers. The contents of a direct buffer can, potentially, reside in native memory outside of the ordinary garbage-collected heap. For information about direct buffers, please see New I/O APIs and the specification of the java.nio.ByteBuffer class.

Three new functions introduced in JDK/JRE 1.4 allow JNI code to create, examine, and manipulate direct buffers:
  • NewDirectByteBuffer
  • GetDirectBufferAddress
  • GetDirectBufferCapacity

Every implementation of the Java virtual machine must support these functions, but not every implementation is required to support JNI access to direct buffers. If a JVM does not support such access then the NewDirectByteBuffer and GetDirectBufferAddress functions must always return NULL, and the GetDirectBufferCapacity function must always return -1. If a JVM does support such access then these three functions must be implemented to return the appropriate values.

NewDirectByteBuffer

jobject NewDirectByteBuffer(JNIEnv* env, void* address, jlong capacity);

Allocates and returns a direct java.nio.ByteBuffer referring to the block of memory starting at the memory address address and extending capacity bytes.

Native code that calls this function and returns the resulting byte-buffer object to Java-level code should ensure that the buffer refers to a valid region of memory that is accessible for reading and, if appropriate, writing. An attempt to access an invalid memory location from Java code will either return an arbitrary value, have no visible effect, or cause an unspecified exception to be thrown.

LINKAGE:

Index 229 in the JNIEnv interface function table.

PARAMETERS:

env: the JNIEnv interface pointer

address: the starting address of the memory region (must not be NULL)

capacity: the size in bytes of the memory region (must be positive)

RETURNS:

Returns a local reference to the newly-instantiated java.nio.ByteBuffer object. Returns NULL if an exception occurs, or if JNI access to direct buffers is not supported by this virtual machine.

EXCEPTIONS:

OutOfMemoryError: if allocation of the ByteBuffer object fails

SINCE:

JDK/JRE 1.4

GetDirectBufferAddress

void* GetDirectBufferAddress(JNIEnv* env, jobject buf);

Fetches and returns the starting address of the memory region referenced by the given direct java.nio.Buffer.

This function allows native code to access the same memory region that is accessible to Java code via the buffer object.

LINKAGE:

Index 230 in the JNIEnv interface function table.

PARAMETERS:

env: the JNIEnv interface pointer

buf: a direct java.nio.Buffer object (must not be NULL)

RETURNS:

Returns the starting address of the memory region referenced by the buffer. Returns NULL if the memory region is undefined, if the given object is not a direct java.nio.Buffer, or if JNI access to direct buffers is not supported by this virtual machine.

SINCE:

JDK/JRE 1.4

GetDirectBufferCapacity

jlong GetDirectBufferCapacity(JNIEnv* env, jobject buf);

Fetches and returns the capacity in bytes of the memory region referenced by the given direct java.nio.Buffer.

LINKAGE:

Index 231 in the JNIEnv interface function table.

PARAMETERS:

env: the JNIEnv interface pointer

buf: a direct java.nio.Buffer object (must not be NULL)

RETURNS:

Returns the capacity in bytes of the memory region associated with the buffer. Returns -1 if the given object is not a direct java.nio.Buffer, if the object is an unaligned view buffer and the processor architecture does not support unaligned access, or if JNI access to direct buffers is not supported by this virtual machine.

SINCE:

JDK/JRE 1.4

Reflection Support

Programmers can use the JNI to call Java methods or access Java fields if they know the name and type of the methods or fields. The Java Core Reflection API allows programmers to introspect Java classes at runtime. JNI provides a set of conversion functions between field and method IDs used in the JNI to field and method objects used in the Java Core Reflection API.

FromReflectedMethod

jmethodID FromReflectedMethod(JNIEnv *env, jobject method);

Converts a java.lang.reflect.Method or java.lang.reflect.Constructor object to a method ID.

LINKAGE:

Index 7 in the JNIEnv interface function table.

SINCE:

JDK/JRE 1.2

FromReflectedField

jfieldID FromReflectedField(JNIEnv *env, jobject field);

Converts a java.lang.reflect.Field to a field ID.

LINKAGE:
Index 8 in the JNIEnv interface function table.
SINCE:

JDK/JRE 1.2

ToReflectedMethod

jobject ToReflectedMethod(JNIEnv *env, jclass cls,
   jmethodID methodID);

Converts a method ID derived from cls to a java.lang.reflect.Method or java.lang.reflect.Constructor object.

Throws OutOfMemoryError and returns 0 if fails.

LINKAGE:

Index 9 in the JNIEnv interface function table.

SINCE:

JDK/JRE 1.2

ToReflectedField

jobject ToReflectedField(JNIEnv *env, jclass cls,
   jfieldID fieldID);

Converts a field ID derived from cls to a java.lang.reflect.Field object.

Throws OutOfMemoryError and returns 0 if fails.

LINKAGE:

Index 12 in the JNIEnv interface function table.

SINCE:

JDK/JRE 1.2

Java VM Interface

GetJavaVM

jint GetJavaVM(JNIEnv *env, JavaVM **vm);

Returns the Java VM interface (used in the Invocation API) associated with the current thread. The result is placed at the location pointed to by the second argument, vm.

LINKAGE:

Index 219 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

vm: a pointer to where the result should be placed.

RETURNS:

Returns “0” on success; returns a negative value on failure.

Contents | Previous | Next

Copyright © 2005 Sun Microsystems, Inc. All rights reserved.


JNI Types and Data Structures

Chapter 3

This chapter discusses how the JNI maps Java types to native C types.

Primitive Types

Table 3-1 describes Java primitive types and their machine-dependent native equivalents.

Table 3-1 Primitive Types and Native Equivalents
Java Type | Native Type | Description
boolean | jboolean | unsigned 8 bits
byte | jbyte | signed 8 bits
char | jchar | unsigned 16 bits
short | jshort | signed 16 bits
int | jint | signed 32 bits
long | jlong | signed 64 bits
float | jfloat | 32 bits
double | jdouble | 64 bits
void | void | N/A

The following definition is provided for convenience.

#define JNI_FALSE  0
#define JNI_TRUE   1

The jsize integer type is used to describe cardinal indices and sizes:

typedef jint jsize;

Reference Types

The JNI includes a number of reference types that correspond to different kinds of Java objects. JNI reference types are organized in the hierarchy shown in Figure 3-1.

The top of the heirarchy is jobject. Subclasses of jobject are jclass, jstring, jarray and jthrowable. Subclasses of jarray are jobjectArray, jbooleanArray, jbyteArray, jcharArray, jshortArray, jintArray, jlongArray, jfloatArray, jdoubleArray.

Figure 3-1 Reference Type Hierarchy

In C, all other JNI reference types are defined to be the same as jobject. For example:

typedef jobject jclass;

In C++, JNI introduces a set of dummy classes to enforce the subtyping relationship. For example:

class _jobject {};
class _jclass : public _jobject {};
...
typedef _jobject *jobject;
typedef _jclass *jclass;

Field and Method IDs

Method and field IDs are regular C pointer types:

struct _jfieldID;              /* opaque structure */
typedef struct _jfieldID *jfieldID;   /* field IDs */

struct _jmethodID;              /* opaque structure */
typedef struct _jmethodID *jmethodID; /* method IDs */

The Value Type

The jvalue union type is used as the element type in argument arrays. It is declared as follows:

typedef union jvalue {
    jboolean z;
    jbyte    b;
    jchar    c;
    jshort   s;
    jint     i;
    jlong    j;
    jfloat   f;
    jdouble  d;
    jobject  l;
} jvalue;

Type Signatures

The JNI uses the Java VM’s representation of type signatures. Table 3-2 shows these type signatures.

Table 3-2 Java VM Type Signatures
Type Signature | Java Type
Z | boolean
B | byte
C | char
S | short
I | int
J | long
F | float
D | double
L fully-qualified-class ; | fully-qualified-class
[ type | type[]
( arg-types ) ret-type | method type

For example, the Java method:

long f (int n, String s, int[] arr);

has the following type signature:

(ILjava/lang/String;[I)J

Modified UTF-8 Strings

The JNI uses modified UTF-8 strings to represent various string types. Modified UTF-8 strings are the same as those used by the Java VM. Modified UTF-8 strings are encoded so that character sequences that contain only non-null ASCII characters can be represented using only one byte per character, but all Unicode characters can be represented.

All characters in the range \u0001 to \u007F are represented by a single byte, as follows:

0

bits 6-0

The seven bits of data in the byte give the value of the character represented.

The null character ('\u0000') and characters in the range '\u0080' to '\u07FF' are represented by a pair of bytes x and y:

x:

1

1

0

bits 10-6
y:

1

0

bits 5-0

The bytes represent the character with the value ((x & 0x1f) << 6) + (y & 0x3f).

Characters in the range '\u0800' to '\uFFFF' are represented by 3 bytes x, y, and z:

x:

1

1

1

0

bits 15-12
y:

1

0

bits 11-6
z:

1

0

bits 5-0

The character with the value ((x & 0xf) << 12) + ((y & 0x3f) << 6) + (z & 0x3f) is represented by the bytes.

Characters with code points above U+FFFF (so-called supplementary characters) are represented by separately encoding the two surrogate code units of their UTF-16 representation. Each of the surrogate code units is represented by three bytes. This means, supplementary characters are represented by six bytes, u, v, w, x, y, and z:

u:

1

1

1

0

1

1

0

1
v:

1

0

1

0

(bits 20-16) - 1
w:

1

0

bits 15-10
x:

1

1

1

0

1

1

0

1
y:

1

0

1

1

bits 9-6
z:

1

0

bits 5-0

The character with the value 0x10000+((v&0x0f)<<16)+((w&0x3f)<<10)+(y&0x0f)<<6)+(z&0x3f) is represented by the six bytes.

The bytes of multibyte characters are stored in the class file in big-endian (high byte first) order.

There are two differences between this format and the standard UTF-8 format. First, the null character (char)0 is encoded using the two-byte format rather than the one-byte format. This means that modified UTF-8 strings never have embedded nulls. Second, only the one-byte, two-byte, and three-byte formats of standard UTF-8 are used. The Java VM does not recognize the four-byte format of standard UTF-8; it uses its own two-times-three-byte format instead.

For more information regarding the standard UTF-8 format, see section 3.9 Unicode Encoding Forms of The Unicode Standard, Version 4.0.

Contents | Previous | Next

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


The Invocation API

Chapter 5

The Invocation API allows software vendors to load the Java VM into an arbitrary native application. Vendors can deliver Java-enabled applications without having to link with the Java VM source code.

This chapter begins with an overview of the Invocation API. This is followed by reference pages for all Invocation API functions.

Overview

The following code example illustrates how to use functions in the Invocation API. In this example, the C++ code creates a Java VM and invokes a static method, called Main.test. For clarity, we omit error checking.

    #include <jni.h>       /* where everything is defined */
    ...
    JavaVM *jvm;       /* denotes a Java VM */
    JNIEnv *env;       /* pointer to native method interface */
    JavaVMInitArgs vm_args; /* JDK/JRE 6 VM initialization arguments */
    JavaVMOption* options = new JavaVMOption[1];
    options[0].optionString = "-Djava.class.path=/usr/lib/java";
    vm_args.version = JNI_VERSION_1_6;
    vm_args.nOptions = 1;
    vm_args.options = options;
    vm_args.ignoreUnrecognized = false;
    /* load and initialize a Java VM, return a JNI interface
     * pointer in env */
    JNI_CreateJavaVM(&jvm, &env, &vm_args);
    delete options;
    /* invoke the Main.test method using the JNI */
    jclass cls = env->FindClass("Main");
    jmethodID mid = env->GetStaticMethodID(cls, "test", "(I)V");
    env->CallStaticVoidMethod(cls, mid, 100);
    /* We are done. */
    jvm->DestroyJavaVM();

This example uses three functions in the API. The Invocation API allows a native application to use the JNI interface pointer to access VM features. The design is similar to Netscape’s JRI Embedding Interface.

Creating the VM

The JNI_CreateJavaVM() function loads and initializes a Java VM and returns a pointer to the JNI interface pointer. The thread that called JNI_CreateJavaVM() is considered to be the main thread.

Attaching to the VM

The JNI interface pointer (JNIEnv) is valid only in the current thread. Should another thread need to access the Java VM, it must first call AttachCurrentThread() to attach itself to the VM and obtain a JNI interface pointer. Once attached to the VM, a native thread works just like an ordinary Java thread running inside a native method. The native thread remains attached to the VM until it calls DetachCurrentThread() to detach itself.

The attached thread should have enough stack space to perform a reasonable amount of work. The allocation of stack space per thread is operating system-specific. For example, using pthreads, the stack size can be specified in the pthread_attr_t argument to pthread_create.

Detaching from the VM

A native thread attached to the VM must call DetachCurrentThread() to detach itself before exiting. A thread cannot detach itself if there are Java methods on the call stack.

Unloading the VM

The JNI_DestroyJavaVM() function unloads a Java VM. As of JDK/JRE 1.1, only the main thread could unload the VM, by calling DestroyJavaVM. As of JDK/JRE 1.2, the restriction was removed, and any thread may call DestroyJavaVM to unload the VM.

The VM waits until the current thread is the only non-daemon user thread before it actually unloads. User threads include both Java threads and attached native threads. This restriction exists because a Java thread or attached native thread may be holding system resources, such as locks, windows, and so on. The VM cannot automatically free these resources. By restricting the current thread to be the only running thread when the VM is unloaded, the burden of releasing system resources held by arbitrary threads is on the programmer.

Library and Version Management

As of JDK/JRE 1.1, once a native library is loaded, it is visible from all class loaders. Therefore two classes in different class loaders may link with the same native method. This leads to two problems:
  • A class may mistakenly link with native libraries loaded by a class with the same name in a different class loader.
  • Native methods can easily mix classes from different class loaders. This breaks the name space separation offered by class loaders, and leads to type safety problems.

As of JDK/JRE 1.2, each class loader manages its own set of native libraries. The same JNI native library cannot be loaded into more than one class loader. Doing so causes UnsatisfiedLinkError to be thrown. For example, System.loadLibrary throws an UnsatisfiedLinkError when used to load a native library into two class loaders. The benefits of the new approach are:

  • Name space separation based on class loaders is preserved in native libraries. A native library cannot easily mix classes from different class loaders.
  • In addition, native libraries can be unloaded when their corresponding class loaders are garbage collected.

To facilitate version control and resource management, JNI libraries as of JDK/JRE 1.2 optionally export the following two functions:

JNI_OnLoad

jint JNI_OnLoad(JavaVM *vm, void *reserved);

The VM calls JNI_OnLoad when the native library is loaded (for example, through System.loadLibrary). JNI_OnLoad must return the JNI version needed by the native library.

In order to use any of the new JNI functions, a native library must export a JNI_OnLoad function that returns JNI_VERSION_1_2. If the native library does not export a JNI_OnLoad function, the VM assumes that the library only requires JNI version JNI_VERSION_1_1. If the VM does not recognize the version number returned by JNI_OnLoad, the native library cannot be loaded.

LINKAGE:

Exported from native libraries that contain native method implementation.

SINCE:

JDK/JRE 1.4

In order to use the JNI functions introduced in J2SE release 1.2, in addition to those that were available in JDK/JRE 1.1, a native library must export a JNI_OnLoad function that returns JNI_VERSION_1_2.

In order to use the JNI functions introduced in J2SE release 1.4, in addition to those that were available in release 1.2, a native library must export a JNI_OnLoad function that returns JNI_VERSION_1_4.

If the native library does not export a JNI_OnLoad function, the VM assumes that the library only requires JNI version JNI_VERSION_1_1. If the VM does not recognize the version number returned by JNI_OnLoad, the native library cannot be loaded.

JNI_OnUnload

void JNI_OnUnload(JavaVM *vm, void *reserved);

The VM calls JNI_OnUnload when the class loader containing the native library is garbage collected. This function can be used to perform cleanup operations. Because this function is called in an unknown context (such as from a finalizer), the programmer should be conservative on using Java VM services, and refrain from arbitrary Java call-backs.

Note that JNI_OnLoad and JNI_OnUnload are two functions optionally supplied by JNI libraries, not exported from the VM.

LINKAGE:
Exported from native libraries that contain native method implementation.

Invocation API Functions

The JavaVM type is a pointer to the Invocation API function table. The following code example shows this function table.

typedef const struct JNIInvokeInterface *JavaVM;

const struct JNIInvokeInterface ... = {
    NULL,
    NULL,
    NULL,

    DestroyJavaVM,
    AttachCurrentThread,
    DetachCurrentThread,

    GetEnv,

    AttachCurrentThreadAsDaemon
};

Note that three Invocation API functions, JNI_GetDefaultJavaVMInitArgs(), JNI_GetCreatedJavaVMs(), and JNI_CreateJavaVM(), are not part of the JavaVM function table. These functions can be used without a preexisting JavaVM structure.

JNI_GetDefaultJavaVMInitArgs

jint JNI_GetDefaultJavaVMInitArgs(void *vm_args);

Returns a default configuration for the Java VM. Before calling this function, native code must set the vm_args->version field to the JNI version it expects the VM to support. After this function returns, vm_args->version will be set to the actual JNI version the VM supports.

LINKAGE:

Exported from the native library that implements the Java virtual machine.

PARAMETERS:

vm_args: a pointer to a JavaVMInitArgs structure in to which the default arguments are filled.

RETURNS:

Returns JNI_OK if the requested version is supported; returns a JNI error code (a negative number) if the requested version is not supported.

JNI_GetCreatedJavaVMs

jint JNI_GetCreatedJavaVMs(JavaVM **vmBuf, jsize bufLen, jsize *nVMs);

Returns all Java VMs that have been created. Pointers to VMs are written in the buffer vmBuf in the order they are created. At most bufLen number of entries will be written. The total number of created VMs is returned in *nVMs.

As of JDK/JRE 1.2, creation of multiple VMs in a single process is not supported.

LINKAGE:

Exported from the native library that implements the Java virtual machine.

PARAMETERS:

vmBuf: pointer to the buffer where the VM structures will be placed.

bufLen: the length of the buffer.

nVMs: a pointer to an integer.

RETURNS:

Returns JNI_OK on success; returns a suitable JNI error code (a negative number) on failure.

JNI_CreateJavaVM

jint JNI_CreateJavaVM(JavaVM **p_vm, JNIEnv **p_env, void *vm_args);

Loads and initializes a Java VM. The current thread becomes the main thread. Sets the env argument to the JNI interface pointer of the main thread.

As of JDK/JRE 1.2 , creation of multiple VMs in a single process is not supported.

The second argument to JNI_CreateJavaVM is always a pointer to JNIEnv *, while the third argument is a pointer to a JavaVMInitArgs structure which uses option strings to encode arbitrary VM start up options:

typedef struct JavaVMInitArgs {
    jint version;

    jint nOptions;
    JavaVMOption *options;
    jboolean ignoreUnrecognized;
} JavaVMInitArgs;

The version field must be set to at least JNI_VERSION_1_2. The options field is an array of the following type:

typedef struct JavaVMOption {
    char *optionString;  /* the option as a string in the default platform encoding */
    void *extraInfo;
} JavaVMOption;

The size of the array is denoted by the nOptions field in JavaVMInitArgs. If ignoreUnrecognized is JNI_TRUE, JNI_CreateJavaVM ignore all unrecognized option strings that begin with "-X" or "_". If ignoreUnrecognized is JNI_FALSE, JNI_CreateJavaVM returns JNI_ERR as soon as it encounters any unrecognized option strings. All Java VMs must recognize the following set of standard options:

optionString | meaning
-D<name>=<value> | Set a system property
-verbose[:class|gc|jni] | Enable verbose output. The options can be followed by a comma-separated list of names indicating what kind of messages will be printed by the VM. For example, "-verbose:gc,class" instructs the VM to print GC and class loading related messages. Standard names include: gc, class, and jni. All nonstandard (VM-specific) names must begin with "X".
vfprintf | extraInfo is a pointer to the vfprintf hook.
exit | extraInfo is a pointer to the exit hook.
abort | extraInfo is a pointer to the abort hook.

In addition, each VM implementation may support its own set of non-standard option strings. Non-standard option names must begin with "-X" or an underscore ("_"). For example, the JDK/JRE supports -Xms and -Xmx options to allow programmers specify the initial and maximum heap size. Options that begin with "-X" are accessible from the "java" command line.

Here is the example code that creates a Java VM in the JDK/JRE:

JavaVMInitArgs vm_args;
JavaVMOption options[4];

options[0].optionString = "-Djava.compiler=NONE";           /* disable JIT */
options[1].optionString = "-Djava.class.path=c:\myclasses"; /* user classes */
options[2].optionString = "-Djava.library.path=c:\mylibs";  /* set native library path */
options[3].optionString = "-verbose:jni";                   /* print JNI-related messages */

vm_args.version = JNI_VERSION_1_2;
vm_args.options = options;
vm_args.nOptions = 4;
vm_args.ignoreUnrecognized = TRUE;

/* Note that in the JDK/JRE, there is no longer any need to call
 * JNI_GetDefaultJavaVMInitArgs.
 */
res = JNI_CreateJavaVM(&vm, (void **)&env, &vm_args);
if (res < 0) ...
LINKAGE:

Exported from the native library that implements the Java virtual machine.

PARAMETERS:

p_vm: pointer to the location where the resulting VM structure will be placed.

p_env: pointer to the location where the JNI interface pointer for the main thread will be placed.

vm_args: Java VM initialization arguments.

RETURNS:

Returns JNI_OK on success; returns a suitable JNI error code (a negative number) on failure.

DestroyJavaVM

jint DestroyJavaVM(JavaVM *vm);

Unloads a Java VM and reclaims its resources.

The support for DestroyJavaVM was not complete in JDK/JRE 1.1. As of JDK/JRE 1.1 Only the main thread may call DestroyJavaVM. Since JDK/JRE 1.2, any thread, whether attached or not, can call this function. If the current thread is attached, the VM waits until the current thread is the only non-daemon user-level Java thread. If the current thread is not attached, the VM attaches the current thread and then waits until the current thread is the only non-daemon user-level thread. The JDK/JRE still does not support VM unloading, however.

LINKAGE:

Index 3 in the JavaVM interface function table.

PARAMETERS:

vm: the Java VM that will be destroyed.

RETURNS:

Returns JNI_OK on success; returns a suitable JNI error code (a negative number) on failure.

As of JDK/JRE 1.1.2 unloading of the VM is not supported.

AttachCurrentThread

jint AttachCurrentThread(JavaVM *vm, JNIEnv **p_env, void *thr_args);

Attaches the current thread to a Java VM. Returns a JNI interface pointer in the JNIEnv argument.

Trying to attach a thread that is already attached is a no-op.

A native thread cannot be attached simultaneously to two Java VMs.

When a thread is attached to the VM, the context class loader is the bootstrap loader.

LINKAGE:

Index 4 in the JavaVM interface function table.

PARAMETERS:

vm: the VM to which the current thread will be attached.

p_env: pointer to the location where the JNI interface pointer of the current thread will be placed.

thr_args: can be NULL or a pointer to a JavaVMAttachArgs structure to specify additional information:

As of JDK/JRE 1.1, the second argument to AttachCurrentThread is always a pointer to JNIEnv. The third argument to AttachCurrentThread was reserved, and should be set to NULL.

As of JDK/JRE 1.2, you pass NULL as the third argument for 1.1 behavior, or pass a pointer to the following structure to specify additional information:

typedef struct JavaVMAttachArgs {
    jint version;  /* must be at least JNI_VERSION_1_2 */
    char *name;    /* the name of the thread as a modified UTF-8 string, or NULL */
    jobject group; /* global ref of a ThreadGroup object, or NULL */
} JavaVMAttachArgs
RETURNS:

Returns JNI_OK on success; returns a suitable JNI error code (a negative number) on failure.

AttachCurrentThreadAsDaemon

jint AttachCurrentThreadAsDaemon(JavaVM* vm, void** penv, void* args);

Same semantics as AttachCurrentThread, but the newly-created java.lang.Thread instance is a daemon.

If the thread has already been attached via either AttachCurrentThread or AttachCurrentThreadAsDaemon, this routine simply sets the value pointed to by penv to the JNIEnv of the current thread. In this case neither AttachCurrentThread nor this routine have any effect on the daemon status of the thread.

LINKAGE:

Index 7 in the JavaVM interface function table.

PARAMETERS:

vm: the virtual machine instance to which the current thread will be attached.

penv: a pointer to the location in which the JNIEnv interface pointer for the current thread will be placed.

args: a pointer to a JavaVMAttachArgs structure.

RETURNS

Returns JNI_OK on success; returns a suitable JNI error code (a negative number) on failure.

EXCEPTIONS

None.

SINCE:

JDK/JRE 1.4

DetachCurrentThread

jint DetachCurrentThread(JavaVM *vm);

Detaches the current thread from a Java VM. All Java monitors held by this thread are released. All Java threads waiting for this thread to die are notified.

As of JDK/JRE 1.2 , the main thread can be detached from the VM.

LINKAGE:

Index 5 in the JavaVM interface function table.

PARAMETERS:

vm: the VM from which the current thread will be detached.

RETURNS:

Returns JNI_OK on success; returns a suitable JNI error code (a negative number) on failure.

GetEnv

jint GetEnv(JavaVM *vm, void **env, jint version);

LINKAGE:

Index 6 in the JavaVM interface function table.

PARAMETERS:
vm: The virtual machine instance from which the interface will be retrieved.
env: pointer to the location where the JNI interface pointer for the current thread will be placed.
version: The requested JNI version.

RETURNS:

If the current thread is not attached to the VM, sets *env to NULL, and returns JNI_EDETACHED. If the specified version is not supported, sets *env to NULL, and returns JNI_EVERSION. Otherwise, sets *env to the appropriate interface, and returns JNI_OK.

SINCE:

JDK/JRE 1.2

Contents | Previous

Copyright © 2005 Sun Microsystems, Inc. All rights reserved.


Contents

Java Native Interface Specification—Contents

Contents | Previous | Next

1. Introduction

Java Native Interface Overview
 Background

JDK 1.0 Native Method Interface
 Java Runtime Interface
Raw Native Interface and Java/COM Interface

Objectives
 Java Native Interface Approach
Programming to the JNI
 Changes in JDK 1.1.2

2. Design Overview

JNI Interface Functions and Pointers
 Loading and Linking Native Methods

Resolving Native Method Names
 Native Method Arguments

Referencing Java Objects

Global and Local References
 Implementing Local References

Accessing Java Objects

Accessing Primitive Arrays
 Accessing Fields and Methods

Reporting Programming Errors
 Java Exceptions

Exceptions and Error Codes
 Asynchronous Exceptions
 Exception Handling

3. JNI Types and Data Structures

Primitive Types
Reference Types
Field and Method IDs
The Value Type
Type Signatures
UTF-8 Strings

4. JNI Functions

Interface Function Table
Version Information

GetVersion

Class Operations

DefineClass
 FindClass
 GetSuperclass
 IsAssignableFrom

Exceptions

Throw
 ThrowNew
ExceptionOccurred
 ExceptionDescribe
ExceptionClear
 FatalError
 ExceptionCheck

Global and Local References

NewGlobalRef
 DeleteGlobalRef
DeleteLocalRef
 EnsureLocalCapacity
 PushLocalFrame
 PopLocalFrame
 NewLocalRef

Weak Global References

NewWeakGlobalRef
 DeleteWeakGlobalRef

Object Operations

AllocObject
 NewObject, NewObjectA, and NewObjectV
GetObjectClass
 GetObjectRefType
IsInstanceOf
IsSameObj ect

Accessing Fields of Objects

GetFieldID
 Get<type>Field Routines
Set<type>Field Routines

Calling Instance Methods

GetMethodID
 Call<type>Method Routines, Call<type>MethodA Routines, and Call<type>MethodV Routines
CallNonvirtual<type>Method Routines, CallNonvirtual<type>MethodA Routines, and CallNonvirtual<type>MethodV Routines

Accessing Static Fields

GetStaticFieldID
 GetStatic<type>Field Routines
SetStatic<type>Field Routines

Calling Static Methods

GetStaticMethodID
 CallStatic<type>Method Routines, CallStatic<type>MethodA Routines, and CallStatic<type>MethodV Routines

String Operations

NewString
 GetStringLength
GetStringChars
 ReleaseStringChars
NewStringUTF
 GetStringUTFLength
GetStringUTFChars
 ReleaseStringUTFChars
 GetStringRegion
 GetStringUTFRegion
 GetStringCritical
 Release StringCritical

Array Operations

GetArrayLength
 NewObjectArray
GetObjectArrayElement
 SetObjectArrayElement
New<PrimitiveType>Array Routines
 Get<PrimitiveType>ArrayElements Routines
Release<PrimitiveType>ArrayElements Routines
 Get<PrimitiveType>ArrayRegion Routines
Set<PrimitiveType>ArrayRegion Routines
 GetPrimitiveArrayCritical
 ReleasePrimitiveArrayCritical

Registering Native Methods

RegisterNatives
 UnregisterNatives

Monitor Operations

MonitorEnter
 MonitorExit

NIO Support

NewDirectByteBuffer
 GetDirectBufferAddress
 GetDirectBufferCapacity

Reflection Support

FromReflectedMethod
 FromReflectedField
 ToReflectedMethod
 ToReflectedField

Java VM Interface

GetJavaVM

5. The Invocation API

Overview

Creating the VM
 Attaching to the VM
Unloading the VM

Initialization Structures Library and Version Management

JNI_OnLoad
 JNI_OnUnload

Invocation API Functions

JNI_GetDefaultJavaVMInitArgs
 JNI_GetCreatedJavaVMs
JNI_CreateJavaVM
 DestroyJavaVM
AttachCurrentThread
 AttachCurrentThreadAsDaemon
 DetachCurrentThread
 GetEnv

Contents | Previous | Next

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


Design Overview

Chapter 2

This chapter focuses on major design issues in the JNI. Most design issues in this section are related to native methods. The design of the Invocation API is covered in Chapter 5.

JNI Interface Functions and Pointers

Native code accesses Java VM features by calling JNI functions. JNI functions are available through an interface pointer. An interface pointer is a pointer to a pointer. This pointer points to an array of pointers, each of which points to an interface function. Every interface function is at a predefined offset inside the array. Figure 2-1 illustrates the organization of an interface pointer.

The previous context describes this image.

Figure 2-1 Interface Pointer

The JNI interface is organized like a C++ virtual function table or a COM interface. The advantage to using an interface table, rather than hard-wired function entries, is that the JNI name space becomes separate from the native code. A VM can easily provide multiple versions of JNI function tables. For example, the VM may support two JNI function tables:

  • one performs thorough illegal argument checks, and is suitable for debugging;
  • the other performs the minimal amount of checking required by the JNI specification, and is therefore more efficient.

The JNI interface pointer is only valid in the current thread. A native method, therefore, must not pass the interface pointer from one thread to another. A VM implementing the JNI may allocate and store thread-local data in the area pointed to by the JNI interface pointer.

Native methods receive the JNI interface pointer as an argument. The VM is guaranteed to pass the same interface pointer to a native method when it makes multiple calls to the native method from the same Java thread. However, a native method can be called from different Java threads, and therefore may receive different JNI interface pointers.

Loading and Linking Native Methods

Native methods are loaded with the System.loadLibrary method. In the following example, the class initialization method loads a platform-specific native library in which the native method f is defined:

package pkg;

class Cls {

     native double f(int i, String s);

     static {

         System.loadLibrary(“pkg_Cls”);

     }

}

The argument to System.loadLibrary is a library name chosen arbitrarily by the programmer. The system follows a standard, but platform-specific, approach to convert the library name to a native library name. For example, a Solaris system converts the name pkg_Cls to libpkg_Cls.so, while a Win32 system converts the same pkg_Cls name to pkg_Cls.dll.

The programmer may use a single library to store all the native methods needed by any number of classes, as long as these classes are to be loaded with the same class loader. The VM internally maintains a list of loaded native libraries for each class loader. Vendors should choose native library names that minimize the chance of name clashes.

If the underlying operating system does not support dynamic linking, all native methods must be prelinked with the VM. In this case, the VM completes the System.loadLibrary call without actually loading the library.

The programmer can also call the JNI function RegisterNatives() to register the native methods associated with a class. The RegisterNatives() function is particularly useful with statically linked functions.

Resolving Native Method Names

Dynamic linkers resolve entries based on their names. A native method name is concatenated from the following components:

  • the prefix Java_
  • a mangled fully-qualified class name
  • an underscore (“_”) separator
  • a mangled method name
  • for overloaded native methods, two underscores (“__”) followed by the mangled argument signature

The VM checks for a method name match for methods that reside in the native library. The VM looks first for the short name; that is, the name without the argument signature. It then looks for the long name, which is the name with the argument signature. Programmers need to use the long name only when a native method is overloaded with another native method. However, this is not a problem if the native method has the same name as a nonnative method. A nonnative method (a Java method) does not reside in the native library.

In the following example, the native method g does not have to be linked using the long name because the other method g is not a native method, and thus is not in the native library.

class Cls1 {

  int g(int i);

  native int g(double d);

}

We adopted a simple name-mangling scheme to ensure that all Unicode characters translate into valid C function names. We use the underscore (“_”) character as the substitute for the slash (“/”) in fully qualified class names. Since a name or type descriptor never begins with a number, we can use _0, ..., _9 for escape sequences, as Table 2-1 illustrates:

Table 2-1 Unicode Character Translation
Escape Sequence | Denotes
_0XXXX | a Unicode character XXXX. Note that lower case is used to represent non-ASCII Unicode characters, e.g., _0abcd as opposed to _0ABCD.
_1 | the character “_”
_2 | the character “;” in signatures
_3 | the character “[“ in signatures

Both the native methods and the interface APIs follow the standard library-calling convention on a given platform. For example, UNIX systems use the C calling convention, while Win32 systems use __stdcall.

Native Method Arguments

The JNI interface pointer is the first argument to native methods. The JNI interface pointer is of type JNIEnv. The second argument differs depending on whether the native method is static or nonstatic. The second argument to a nonstatic native method is a reference to the object. The second argument to a static native method is a reference to its Java class.

The remaining arguments correspond to regular Java method arguments. The native method call passes its result back to the calling routine via the return value. Chapter 3 describes the mapping between Java and C types.

Code Example 2-1 illustrates using a C function to implement the native method f. The native method f is declared as follows:

package pkg;

class Cls {

     native double f(int i, String s);

     ...

}

The C function with the long mangled name Java_pkg_Cls_f_ILjava_lang_String_2 implements native method f:

Code Example 2-1 Implementing a Native Method Using C

jdouble Java_pkg_Cls_f__ILjava_lang_String_2 (

     JNIEnv *env,        /* interface pointer */

     jobject obj,        /* "this" pointer */

     jint i,             /* argument #1 */

     jstring s)          /* argument #2 */

{

     /* Obtain a C-copy of the Java string */

     const char *str = (*env)->GetStringUTFChars(env, s, 0);

     /* process the string */

     ...

     /* Now we are done with str */

     (*env)->ReleaseStringUTFChars(env, s, str);

     return ...

}

Note that we always manipulate Java objects using the interface pointer env . Using C++, you can write a slightly cleaner version of the code, as shown in Code Example 2-2:

Code Example 2-2 Implementing a Native Method Using C++

extern "C" /* specify the C calling convention */

jdouble Java_pkg_Cls_f__ILjava_lang_String_2 (

     JNIEnv *env,        /* interface pointer */

     jobject obj,        /* "this" pointer */

     jint i,             /* argument #1 */

     jstring s)          /* argument #2 */

{

     const char *str = env->GetStringUTFChars(s, 0);

     ...

     env->ReleaseStringUTFChars(s, str);

     return ...

}

With C++, the extra level of indirection and the interface pointer argument disappear from the source code. However, the underlying mechanism is exactly the same as with C. In C++, JNI functions are defined as inline member functions that expand to their C counterparts.

Referencing Java Objects

Primitive types, such as integers, characters, and so on, are copied between Java and native code. Arbitrary Java objects, on the other hand, are passed by reference. The VM must keep track of all objects that have been passed to the native code, so that these objects are not freed by the garbage collector. The native code, in turn, must have a way to inform the VM that it no longer needs the objects. In addition, the garbage collector must be able to move an object referred to by the native code.

Global and Local References

The JNI divides object references used by the native code into two categories: local and global references. Local references are valid for the duration of a native method call, and are automatically freed after the native method returns. Global references remain valid until they are explicitly freed.

Objects are passed to native methods as local references. All Java objects returned by JNI functions are local references. The JNI allows the programmer to create global references from local references. JNI functions that expect Java objects accept both global and local references. A native method may return a local or global reference to the VM as its result.

In most cases, the programmer should rely on the VM to free all local references after the native method returns. However, there are times when the programmer should explicitly free a local reference. Consider, for example, the following situations:

  • A native method accesses a large Java object, thereby creating a local reference to the Java object. The native method then performs additional computation before returning to the caller. The local reference to the large Java object will prevent the object from being garbage collected, even if the object is no longer used in the remainder of the computation.
  • A native method creates a large number of local references, although not all of them are used at the same time. Since the VM needs a certain amount of space to keep track of a local reference, creating too many local references may cause the system to run out of memory. For example, a native method loops through a large array of objects, retrieves the elements as local references, and operates on one element at each iteration. After each iteration, the programmer no longer needs the local reference to the array element.

The JNI allows the programmer to manually delete local references at any point within a native method. To ensure that programmers can manually free local references, JNI functions are not allowed to create extra local references, except for references they return as the result.

Local references are only valid in the thread in which they are created. The native code must not pass local references from one thread to another.

Implementing Local References

To implement local references, the Java VM creates a registry for each transition of control from Java to a native method. A registry maps nonmovable local references to Java objects, and keeps the objects from being garbage collected. All Java objects passed to the native method (including those that are returned as the results of JNI function calls) are automatically added to the registry. The registry is deleted after the native method returns, allowing all of its entries to be garbage collected.

There are different ways to implement a registry, such as using a table, a linked list, or a hash table. Although reference counting may be used to avoid duplicated entries in the registry, a JNI implementation is not obliged to detect and collapse duplicate entries.

Note that local references cannot be faithfully implemented by conservatively scanning the native stack. The native code may store local references into global or heap data structures.

Accessing Java Objects

The JNI provides a rich set of accessor functions on global and local references. This means that the same native method implementation works no matter how the VM represents Java objects internally. This is a crucial reason why the JNI can be supported by a wide variety of VM implementations.

The overhead of using accessor functions through opaque references is higher than that of direct access to C data structures. We believe that, in most cases, Java programmers use native methods to perform nontrivial tasks that overshadow the overhead of this interface.

Accessing Primitive Arrays

This overhead is not acceptable for large Java objects containing many primitive data types, such as integer arrays and strings. (Consider native methods that are used to perform vector and matrix calculations.) It would be grossly inefficient to iterate through a Java array and retrieve every element with a function call.

One solution introduces a notion of “pinning” so that the native method can ask the VM to pin down the contents of an array. The native method then receives a direct pointer to the elements. This approach, however, has two implications:

  • The garbage collector must support pinning.
  • The VM must lay out primitive arrays contiguously in memory. Although this is the most natural implementation for most primitive arrays, boolean arrays can be implemented as packed or unpacked. Therefore, native code that relies on the exact layout of boolean arrays will not be portable.

We adopt a compromise that overcomes both of the above problems.

First, we provide a set of functions to copy primitive array elements between a segment of a Java array and a native memory buffer. Use these functions if a native method needs access to only a small number of elements in a large array.

Second, programmers can use another set of functions to retrieve a pinned-down version of array elements. Keep in mind that these functions may require the Java VM to perform storage allocation and copying. Whether these functions in fact copy the array depends on the VM implementation, as follows:

  • If the garbage collector supports pinning, and the layout of the array is the same as expected by the native method, then no copying is needed.
  • Otherwise, the array is copied to a nonmovable memory block (for example, in the C heap) and the necessary format conversion is performed. A pointer to the copy is returned.

Lastly, the interface provides functions to inform the VM that the native code no longer needs to access the array elements. When you call these functions, the system either unpins the array, or it reconciles the original array with its non-movable copy and frees the copy.

Our approach provides flexibility. A garbage collector algorithm can make separate decisions about copying or pinning for each given array. For example, the garbage collector may copy small objects, but pin the larger objects.

A JNI implementation must ensure that native methods running in multiple threads can simultaneously access the same array. For example, the JNI may keep an internal counter for each pinned array so that one thread does not unpin an array that is also pinned by another thread. Note that the JNI does not need to lock primitive arrays for exclusive access by a native method. Simultaneously updating a Java array from different threads leads to nondeterministic results.

Accessing Fields and Methods

The JNI allows native code to access the fields and to call the methods of Java objects. The JNI identifies methods and fields by their symbolic names and type signatures. A two-step process factors out the cost of locating the field or method from its name and signature. For example, to call the method f in class cls, the native code first obtains a method ID, as follows:

jmethodID mid =      env->GetMethodID(cls, “f”, “(ILjava/lang/String;)D”);

The native code can then use the method ID repeatedly without the cost of method lookup, as follows:

jdouble result = env->CallDoubleMethod(obj, mid, 10, str);

A field or method ID does not prevent the VM from unloading the class from which the ID has been derived. After the class is unloaded, the method or field ID becomes invalid. The native code, therefore, must make sure to:

  • keep a live reference to the underlying class, or
  • recompute the method or field ID

if it intends to use a method or field ID for an extended period of time.

The JNI does not impose any restrictions on how field and method IDs are implemented internally.

Reporting Programming Errors

The JNI does not check for programming errors such as passing in NULL pointers or illegal argument types. Illegal argument types includes such things as using a normal Java object instead of a Java class object. The JNI does not check for these programming errors for the following reasons:

  • Forcing JNI functions to check for all possible error conditions degrades the performance of normal (correct) native methods.
  • In many cases, there is not enough runtime type information to perform such checking.

Most C library functions do not guard against programming errors. The printf() function, for example, usually causes a runtime error, rather than returning an error code, when it receives an invalid address. Forcing C library functions to check for all possible error conditions would likely result in such checks to be duplicated--once in the user code, and then again in the library.

The programmer must not pass illegal pointers or arguments of the wrong type to JNI functions. Doing so could result in arbitrary consequences, including a corrupted system state or VM crash.

Java Exceptions

The JNI allows native methods to raise arbitrary Java exceptions. The native code may also handle outstanding Java exceptions. The Java exceptions left unhandled are propagated back to the VM.

Exceptions and Error Codes

Certain JNI functions use the Java exception mechanism to report error conditions. In most cases, JNI functions report error conditions by returning an error code and throwing a Java exception. The error code is usually a special return value (such as NULL) that is outside of the range of normal return values. Therefore, the programmer can:

  • quickly check the return value of the last JNI call to determine if an error has occurred, and
  • call a function, ExceptionOccurred(), to obtain the exception object that contains a more detailed description of the error condition.

There are two cases where the programmer needs to check for exceptions without being able to first check an error code:

  • The JNI functions that invoke a Java method return the result of the Java method. The programmer must call ExceptionOccurred() to check for possible exceptions that occurred during the execution of the Java method.
  • Some of the JNI array access functions do not return an error code, but may throw an ArrayIndexOutOfBoundsException or ArrayStoreException.

In all other cases, a non-error return value guarantees that no exceptions have been thrown.

Asynchronous Exceptions

In cases of multiple threads, threads other than the current thread may post an asynchronous exception. An asynchronous exception does not immediately affect the execution of the native code in the current thread, until:

  • the native code calls one of the JNI functions that could raise synchronous exceptions, or
  • the native code uses ExceptionOccurred() to explicitly check for synchronous and asynchronous exceptions.

Note that only those JNI function that could potentially raise synchronous exceptions check for asynchronous exceptions.

Native methods should insert ExceptionOccurred()checks in necessary places (such as in a tight loop without other exception checks) to ensure that the current thread responds to asynchronous exceptions in a reasonable amount of time.

Exception Handling

There are two ways to handle an exception in native code:

  • The native method can choose to return immediately, causing the exception to be thrown in the Java code that initiated the native method call.
  • The native code can clear the exception by calling ExceptionClear(), and then execute its own exception-handling code.

After an exception has been raised, the native code must first clear the exception before making other JNI calls. When there is a pending exception, the only JNI functions that are safe to call are ExceptionOccurred(), ExceptionDescribe(), and ExceptionClear(). The ExceptionDescribe() function prints a debugging message about the pending exception.

Contents | Previous | Next

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


Introduction

Chapter 1

This chapter introduces the Java Native Interface (JNI). The JNI is a native programming interface. It allows Java code that runs inside a Java Virtual Machine (VM) to interoperate with applications and libraries written in other programming languages, such as C, C++, and assembly.

The most important benefit of the JNI is that it imposes no restrictions on the implementation of the underlying Java VM. Therefore, Java VM vendors can add support for the JNI without affecting other parts of the VM. Programmers can write one version of a native application or library and expect it to work with all Java VMs supporting the JNI.

This chapter covers the following topics:

  • Java Native Interface Overview
  • Background
  • Objectives
  • Java Native Interface Approach
  • Programming to the JNI
  • Changes in JDK 1.1.2

Java Native Interface Overview

While you can write applications entirely in Java, there are situations where Java alone does not meet the needs of your application. Programmers use the JNI to write Java native methods to handle those situations when an application cannot be written entirely in Java.

The following examples illustrate when you need to use Java native methods:

  • The standard Java class library does not support the platform-dependent features needed by the application.
  • You already have a library written in another language, and wish to make it accessible to Java code through the JNI.
  • You want to implement a small portion of time-critical code in a lower-level language such as assembly.

By programming through the JNI, you can use native methods to:

  • Create, inspect, and update Java objects (including arrays and strings).
  • Call Java methods.
  • Catch and throw exceptions.
  • Load classes and obtain class information.
  • Perform runtime type checking.

You can also use the JNI with the Invocation API to enable an arbitrary native application to embed the Java VM. This allows programmers to easily make their existing applications Java-enabled without having to link with the VM source code.

Background

Currently, VMs from different vendors offer different native method interfaces. These different interfaces force programmers to produce, maintain, and distribute multiple versions of native method libraries on a given platform.

We briefly examine some of the existing native method interfaces, such as:

  • JDK 1.0 native method interface
  • Netscape’s Java Runtime Interface
  • Microsoft’s Raw Native Interface and Java/COM interface

JDK 1.0 Native Method Interface

JDK 1.0 shipped with a native method interface. Unfortunately, there are two major reasons that this interface is unsuitable for adoption by other Java VMs.

First, the native code accesses fields in Java objects as members of C structures. However, the Java Language Specification does not define how objects are laid out in memory. If a Java VM lays out objects differently in memory, then the programmer would have to recompile the native method libraries.

Second, JDK 1.0’s native method interface relies on a conservative garbage collector. The unrestricted use of the unhand macro, for example, makes it necessary to conservatively scan the native stack.

Java Runtime Interface

Netscape proposed the Java Runtime Interface (JRI), a general interface for services provided in the Java virtual machine. JRI is designed with portability in mind---it makes few assumptions about the implementation details in the underlying Java VM. The JRI addresses a wide range of issues, including native methods, debugging, reflection, embedding (invocation), and so on.

Raw Native Interface and Java/COM Interface

The Microsoft Java VM supports two native method interfaces. At the low level, it provides an efficient Raw Native Interface (RNI). The RNI offers a high degree of source-level backward compatibility with the JDK’s native method interface, although it has one major difference. Instead of relying on conservative garbage collection, the native code must use RNI functions to interact explicitly with the garbage collector.

At a higher level, Microsoft's Java/COM interface offers a language-independent standard binary interface to the Java VM. Java code can use a COM object as if it were a Java object. A Java class can also be exposed to the rest of the system as a COM class.

Objectives

We believe that a uniform, well-thought-out standard interface offers the following benefits for everyone:

  • Each VM vendor can support a larger body of native code.
  • Tool builders will not have to maintain different kinds of native method interfaces.
  • Application programmers will be able to write one version of their native code and this version will run on different VMs.

The best way to achieve a standard native method interface is to involve all parties with an interest in Java VMs. Therefore we organized a series of discussions among the Java licensees on the design of a uniform native method interface. It is clear from the discussions that the standard native method interface must satisfy the following requirements:

  • Binary compatibility - The primary goal is binary compatibility of native method libraries across all Java VM implementations on a given platform. Programmers should maintain only one version of their native method libraries for a given platform.
  • Efficiency - To support time-critical code, the native method interface must impose little overhead. All known techniques to ensure VM-independence (and thus binary compatibility) carry a certain amount of overhead. We must somehow strike a compromise between efficiency and VM-independence.
  • Functionality - The interface must expose enough Java VM internals to allow native methods to accomplish useful tasks.

Java Native Interface Approach

We hoped to adopt one of the existing approaches as the standard interface, because this would have imposed the least burden on programmers who had to learn multiple interfaces in different VMs. Unfortunately, no existing solutions are completely satisfactory in achieving our goals.

Netscape’s JRI is the closest to what we envision as a portable native method interface, and was used as the starting point of our design. Readers familiar with the JRI will notice the similarities in the API naming convention, the use of method and field IDs, the use of local and global references, and so on. Despite our best efforts, however, the JNI is not binary-compatible with the JRI, although a VM can support both the JRI and the JNI.

Microsoft’s RNI is an improvement over JDK 1.0 because it solves the problem of native methods working with a nonconservative garbage collector. The RNI, however, is not suitable as a VM-independent native method interface. Like the JDK, RNI native methods access Java objects as C structures. This leads to two problems:

  • RNI exposes the layout of internal Java objects to native code.
  • Direct access of Java objects as C structures makes it impossible to efficiently incorporate “write barriers,” which are necessary in advanced garbage collection algorithms.

As a binary standard, COM ensures complete binary compatibility across different VMs. Invoking a COM method requires only an indirect call, which carries little overhead. In addition, COM objects are a great improvement over dynamic-link libraries in solving versioning problems.

The use of COM as the standard Java native method interface, however, is hampered by a few factors:

  • First, the Java/COM interface lacks certain desired functions, such as accessing private fields and raising general exceptions.
  • Second, the Java/COM interface automatically provides the standard IUnknown and IDispatch COM interfaces for Java objects, so that native code can access public methods and fields. Unfortunately, the IDispatch interface does not deal with overloaded Java methods and is case-insensitive in matching method names. Furthermore, all Java methods exposed through the IDispatch interface are wrapped to perform dynamic type checking and coercion. This is because the IDispatch interface is designed with weakly-typed languages (such as Basic) in mind.
  • Third, instead of dealing with individual low-level functions, COM is designed to allow software components (including full-fledged applications) to work together. We believe that it is not appropriate to treat all Java classes or low-level native methods as software components.
  • Fourth, the immediate adoption of COM is hampered by the lack of its support on UNIX platforms.

Although we do not expose Java objects to the native code as COM objects, the JNI interface itself is binary-compatible with COM. We use the same jump table structure and calling convention that COM does. This means that, as soon as cross-platform support for COM is available, the JNI can become a COM interface to the Java VM.

We do not believe that the JNI should be the only native method interface supported by a given Java VM. A standard interface benefits programmers who would like to load their native code libraries into different Java VMs. In some cases, the programmer may have to use a lower-level, VM-specific interface to achieve top efficiency. In other cases, the programmer might use a higher-level interface to build software components. Indeed, we hope that, as the Java environment and component software technologies become more mature, native methods will gradually lose their significance.

Programming to the JNI

Native method programmers should start programming to the JNI. Programming to the JNI insulates you from unknowns, such as the vendor’s VM that the end user might be running. By conforming to the JNI standard, you will give a native library the best chance to run in a given Java VM. For example, although JDK 1.1 will continue to support the old-style native method interface that was implemented in JDK 1.0, it is certain that future versions of the JDK will stop supporting the old-style native method interface. Native methods relying on the old-style interface will have to be rewritten.

If you are implementing a Java VM, you should implement the JNI. We (Javasoft and the licensees) have tried our best to ensure that the JNI does not impose any overhead or restrictions on your VM implementation, including object representation, garbage collection scheme, and so on. Please let us know if you run into any problems we might have overlooked.

Changes in JDK 1.1.2

To better support the Java Runtime Environment (JRE), the Invocation API has been extended in JDK 1.1.2 in a few minor ways. The changes do not break any existing code. The JNI Native Method Interface has not been changed.

  • The reserved0 field in the JDK1_1InitArgs structure has been renamed to version. The JDK1_1InitArgs structure holds the initialization arguments to JNI_CreateJavaVM. Callers of JNI_GetDefaultJavaVMInitArgs and JNI_CreateJavaVM must set the version field to 0x00010001. JNI_GetDefaultJavaVMInitArgs has been changed to return a jint indicating whether the requested version is supported.
  • The reserved1 field in the JDK1_1InitArgs structure has been renamed to properties. This is a NULL-terminated array of strings. Each string has the format:
    • name=value

    indicating a system property. (This facility corresponds to the -D option in the java command line.)

  • In JDK 1.1.1, the thread calling DestroyJavaVM must be the only user thread in the VM. JDK 1.1.2 has lifted this restriction. If DestroyJavaVM is called when there is more than one user thread, the VM waits until the current thread is the only user thread, and then tries to destroy itself.

Contents | Previous | Next

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


JNI Functions

Chapter 4

This chapter serves as the reference section for the JNI functions. It provides a complete listing of all the JNI functions. It also presents the exact layout of the JNI function table.

Note the use of the term “must” to describe restrictions on JNI programmers. For example, when you see that a certain JNI function must receive a non-NULL object, it is your responsibility to ensure that NULL is not passed to that JNI function. As a result, a JNI implementation does not need to perform NULL pointer checks in that JNI function.

A portion of this chapter is adapted from Netscape’s JRI documentation.

The reference material groups functions by their usage. The reference section is organized by the following functional areas:

  • Version Information
  • Class Operations
  • Exceptions
  • Global and Local References
  • Weak Global References
  • Object Operations
  • Accessing Fields of Objects
  • Calling Instance Methods
  • Accessing Static Fields
  • Calling Static Methods
  • String Operations
  • Array Operations
  • Registering Native Methods
  • Monitor Operations
  • NIO Support
  • Reflection Support
  • Java VM Interface

Interface Function Table

Each function is accessible at a fixed offset through the JNIEnv argument. The JNIEnv type is a pointer to a structure storing all JNI function pointers. It is defined as follows:

typedef const struct JNINativeInterface *JNIEnv;

The VM initializes the function table, as shown by Code Example 4-1. Note that the first three entries are reserved for future compatibility with COM. In addition, we reserve a number of additional NULL entries near the beginning of the function table, so that, for example, a future class-related JNI operation can be added after FindClass, rather than at the end of the table.

Note that the function table can be shared among all JNI interface pointers.

Code Example 4-1
const struct JNINativeInterface ... = {

    NULL,
    NULL,
    NULL,
    NULL,
    GetVersion,

    DefineClass,
    FindClass,

    FromReflectedMethod,
    FromReflectedField,
    ToReflectedMethod,

    GetSuperclass,
    IsAssignableFrom,

    ToReflectedField,

    Throw,
    ThrowNew,
    ExceptionOccurred,
    ExceptionDescribe,
    ExceptionClear,
    FatalError,

    PushLocalFrame,
    PopLocalFrame,

    NewGlobalRef,
    DeleteGlobalRef,
    DeleteLocalRef,
    IsSameObject,
    NewLocalRef,
    EnsureLocalCapacity,

    AllocObject,
    NewObject,
    NewObjectV,
    NewObjectA,

    GetObjectClass,
    IsInstanceOf,

    GetMethodID,

    CallObjectMethod,
    CallObjectMethodV,
    CallObjectMethodA,
    CallBooleanMethod,
    CallBooleanMethodV,
    CallBooleanMethodA,
    CallByteMethod,
    CallByteMethodV,
    CallByteMethodA,
    CallCharMethod,
    CallCharMethodV,
    CallCharMethodA,
    CallShortMethod,
    CallShortMethodV,
    CallShortMethodA,
    CallIntMethod,
    CallIntMethodV,
    CallIntMethodA,
    CallLongMethod,
    CallLongMethodV,
    CallLongMethodA,
    CallFloatMethod,
    CallFloatMethodV,
    CallFloatMethodA,
    CallDoubleMethod,
    CallDoubleMethodV,
    CallDoubleMethodA,
    CallVoidMethod,
    CallVoidMethodV,
    CallVoidMethodA,

    CallNonvirtualObjectMethod,
    CallNonvirtualObjectMethodV,
    CallNonvirtualObjectMethodA,
    CallNonvirtualBooleanMethod,
    CallNonvirtualBooleanMethodV,
    CallNonvirtualBooleanMethodA,
    CallNonvirtualByteMethod,
    CallNonvirtualByteMethodV,
    CallNonvirtualByteMethodA,
    CallNonvirtualCharMethod,
    CallNonvirtualCharMethodV,
    CallNonvirtualCharMethodA,
    CallNonvirtualShortMethod,
    CallNonvirtualShortMethodV,
    CallNonvirtualShortMethodA,
    CallNonvirtualIntMethod,
    CallNonvirtualIntMethodV,
    CallNonvirtualIntMethodA,
    CallNonvirtualLongMethod,
    CallNonvirtualLongMethodV,
    CallNonvirtualLongMethodA,
    CallNonvirtualFloatMethod,
    CallNonvirtualFloatMethodV,
    CallNonvirtualFloatMethodA,
    CallNonvirtualDoubleMethod,
    CallNonvirtualDoubleMethodV,
    CallNonvirtualDoubleMethodA,
    CallNonvirtualVoidMethod,
    CallNonvirtualVoidMethodV,
    CallNonvirtualVoidMethodA,

    GetFieldID,

    GetObjectField,
    GetBooleanField,
    GetByteField,
    GetCharField,
    GetShortField,
    GetIntField,
    GetLongField,
    GetFloatField,
    GetDoubleField,
    SetObjectField,
    SetBooleanField,
    SetByteField,
    SetCharField,
    SetShortField,
    SetIntField,
    SetLongField,
    SetFloatField,
    SetDoubleField,

    GetStaticMethodID,

    CallStaticObjectMethod,
    CallStaticObjectMethodV,
    CallStaticObjectMethodA,
    CallStaticBooleanMethod,
    CallStaticBooleanMethodV,
    CallStaticBooleanMethodA,
    CallStaticByteMethod,
    CallStaticByteMethodV,
    CallStaticByteMethodA,
    CallStaticCharMethod,
    CallStaticCharMethodV,
    CallStaticCharMethodA,
    CallStaticShortMethod,
    CallStaticShortMethodV,
    CallStaticShortMethodA,
    CallStaticIntMethod,
    CallStaticIntMethodV,
    CallStaticIntMethodA,
    CallStaticLongMethod,
    CallStaticLongMethodV,
    CallStaticLongMethodA,
    CallStaticFloatMethod,
    CallStaticFloatMethodV,
    CallStaticFloatMethodA,
    CallStaticDoubleMethod,
    CallStaticDoubleMethodV,
    CallStaticDoubleMethodA,
    CallStaticVoidMethod,
    CallStaticVoidMethodV,
    CallStaticVoidMethodA,

    GetStaticFieldID,

    GetStaticObjectField,
    GetStaticBooleanField,
    GetStaticByteField,
    GetStaticCharField,
    GetStaticShortField,
    GetStaticIntField,
    GetStaticLongField,
    GetStaticFloatField,
    GetStaticDoubleField,

    SetStaticObjectField,
    SetStaticBooleanField,
    SetStaticByteField,
    SetStaticCharField,
    SetStaticShortField,
    SetStaticIntField,
    SetStaticLongField,
    SetStaticFloatField,
    SetStaticDoubleField,

    NewString,

    GetStringLength,
    GetStringChars,
    ReleaseStringChars,

    NewStringUTF,
    GetStringUTFLength,
    GetStringUTFChars,
    ReleaseStringUTFChars,

    GetArrayLength,

    NewObjectArray,
    GetObjectArrayElement,
    SetObjectArrayElement,

    NewBooleanArray,
    NewByteArray,
    NewCharArray,
    NewShortArray,
    NewIntArray,
    NewLongArray,
    NewFloatArray,
    NewDoubleArray,

    GetBooleanArrayElements,
    GetByteArrayElements,
    GetCharArrayElements,
    GetShortArrayElements,
    GetIntArrayElements,
    GetLongArrayElements,
    GetFloatArrayElements,
    GetDoubleArrayElements,

    ReleaseBooleanArrayElements,
    ReleaseByteArrayElements,
    ReleaseCharArrayElements,
    ReleaseShortArrayElements,
    ReleaseIntArrayElements,
    ReleaseLongArrayElements,
    ReleaseFloatArrayElements,
    ReleaseDoubleArrayElements,

    GetBooleanArrayRegion,
    GetByteArrayRegion,
    GetCharArrayRegion,
    GetShortArrayRegion,
    GetIntArrayRegion,
    GetLongArrayRegion,
    GetFloatArrayRegion,
    GetDoubleArrayRegion,
    SetBooleanArrayRegion,
    SetByteArrayRegion,
    SetCharArrayRegion,
    SetShortArrayRegion,
    SetIntArrayRegion,
    SetLongArrayRegion,
    SetFloatArrayRegion,
    SetDoubleArrayRegion,

    RegisterNatives,
    UnregisterNatives,

    MonitorEnter,
    MonitorExit,

    GetJavaVM,

    GetStringRegion,
    GetStringUTFRegion,

    GetPrimitiveArrayCritical,
    ReleasePrimitiveArrayCritical,

    GetStringCritical,
    ReleaseStringCritical,

    NewWeakGlobalRef,
    DeleteWeakGlobalRef,

    ExceptionCheck,

    NewDirectByteBuffer,
    GetDirectBufferAddress,
    GetDirectBufferCapacity

    GetObjectRefType
};

Version Information

GetVersion

jint GetVersion(JNIEnv *env);

Returns the version of the native method interface.

LINKAGE:

Index 4 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

RETURNS:

Returns the major version number in the higher 16 bits and the minor version number in the lower 16 bits.

In SDK/JRE 1.1, GetVersion() returns 0x00010001.

In SDK/JRE 1.2, GetVersion() returns 0x00010002.

In SDK/JRE 1.4, GetVersion() returns 0x00010004.

In SDK/JRE 1.6, GetVersion() returns 0x00010006.

Constants

SINCE SDK/JRE 1.2:
#define JNI_VERSION_1_1 0x00010001
#define JNI_VERSION_1_2 0x00010002

/* Error codes */
#define JNI_EDETACHED    (-2)              /* thread detached from the VM */
#define JNI_EVERSION     (-3)              /* JNI version error
SINCE SDK/JRE 1.4:
    #define JNI_VERSION_1_4 0x00010004
SINCE SDK/JRE 1.6:
    #define JNI_VERSION_1_6 0x00010006

Class Operations

DefineClass

jclass DefineClass(JNIEnv *env, jobject loader,
const jbyte *buf, jsize bufLen);

Loads a class from a buffer of raw class data. The buffer containing the raw class data is not referenced by the VM after the DefineClass call returns, and it may be discarded if desired.

LINKAGE:

Index 5 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

loader: a class loader assigned to the defined class.

buf: buffer containing the .class file data.

bufLen: buffer length.

RETURNS:

Returns a Java class object or NULL if an error occurs.

THROWS:

ClassFormatError: if the class data does not specify a valid class.

ClassCircularityError: if a class or interface would be its own superclass or superinterface.

OutOfMemoryError: if the system runs out of memory.

FindClass

jclass FindClass(JNIEnv *env, const char *name);

This function loads a locally-defined class. It searches the directories and zip files specified by the CLASSPATH environment variable for the class with the specified name.

LINKAGE:

Index 6 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

name: a fully-qualified class name (that is, a package name, delimited by “/”, followed by the class name). If the name begins with “[“ (the array signature character), it returns an array class.

RETURNS:

Returns a class object from a fully-qualified name, or NULL if the class cannot be found.

THROWS:

ClassFormatError: if the class data does not specify a valid class.

ClassCircularityError: if a class or interface would be its own superclass or superinterface.

NoClassDefFoundError: if no definition for a requested class or interface can be found.

OutOfMemoryError: if the system runs out of memory.

SINCE SDK/JRE 1.2:

In JDK 1.1, FindClass searched only local classes in CLASSPATH. The resulting classes did not have a class loader.

The Java security model has been extended to allow non-system classes to load and call native methods. In the Java 2 Platform, FindClass locates the class loader associated with the current native method. If the native code belongs to a system class, no class loader will be involved. Otherwise, the proper class loader will be invoked to load and link the named class.

When FindClass is called through the Invocation Interface, there is no current native method or its associated class loader. In that case, the result of ClassLoader.getBaseClassLoader is used. This is the class loader the virtual machine creates for applications, and is able to locate classes listed in the java.class.path property.

GetSuperclass

jclass GetSuperclass(JNIEnv *env, jclass clazz);

If clazz represents any class other than the class Object, then this function returns the object that represents the superclass of the class specified by clazz.

If clazz specifies the class Object, or clazz represents an interface, this function returns NULL.

LINKAGE:

Index 10 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

RETURNS:

Returns the superclass of the class represented by clazz, or NULL.

IsAssignableFrom

jboolean IsAssignableFrom(JNIEnv *env, jclass clazz1,
jclass clazz2);

Determines whether an object of clazz1 can be safely cast to clazz2.

LINKAGE:

Index 11 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz1: the first class argument.

clazz2: the second class argument.

RETURNS:

Returns JNI_TRUE if either of the following is true:

  • The first and second class arguments refer to the same Java class.
  • The first class is a subclass of the second class.
  • The first class has the second class as one of its interfaces.

Exceptions

Throw

jint Throw(JNIEnv *env, jthrowable obj);

Causes a java.lang.Throwable object to be thrown.

LINKAGE:

Index 13 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

obj: a java.lang.Throwable object.

RETURNS:

Returns 0 on success; a negative value on failure.

THROWS:

the java.lang.Throwable object obj.

ThrowNew

jint ThrowNew(JNIEnv *env, jclass clazz,
const char *message);

Constructs an exception object from the specified class with the message specified by message and causes that exception to be thrown.

LINKAGE:

Index 14 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz: a subclass of java.lang.Throwable.

message: the message used to construct the java.lang.Throwable object.

RETURNS:

Returns 0 on success; a negative value on failure.

THROWS:

the newly constructed java.lang.Throwable object.

ExceptionOccurred

jthrowable ExceptionOccurred(JNIEnv *env);

Determines if an exception is being thrown. The exception stays being thrown until either the native code calls ExceptionClear(), or the Java code handles the exception.

LINKAGE:

Index 15 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

RETURNS:

Returns the exception object that is currently in the process of being thrown, or NULL if no exception is currently being thrown.

ExceptionDescribe

void ExceptionDescribe(JNIEnv *env);

Prints an exception and a backtrace of the stack to a system error-reporting channel, such as stderr. This is a convenience routine provided for debugging.

LINKAGE:

Index 16 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

ExceptionClear

void ExceptionClear(JNIEnv *env);

Clears any exception that is currently being thrown. If no exception is currently being thrown, this routine has no effect.

LINKAGE:

Index 17 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

FatalError

void FatalError(JNIEnv *env, const char *msg);

Raises a fatal error and does not expect the VM to recover. This function does not return.

LINKAGE:

Index 18 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

msg: an error message.

ExceptionCheck

We introduce a convenience function to check for pending exceptions without creating a local reference to the exception object.

jboolean ExceptionCheck(JNIEnv *env);

Returns JNI_TRUE when there is a pending exception; otherwise, returns JNI_FALSE.

LINKAGE:
Index 228 in the JNIEnv interface function table.
SINCE:

SDK/JRE 1.2

Global and Local References

Global References

NewGlobalRef

jobject NewGlobalRef(JNIEnv *env, jobject obj);

Creates a new global reference to the object referred to by the obj argument. The obj argument may be a global or local reference. Global references must be explicitly disposed of by calling DeleteGlobalRef().

LINKAGE:

Index 21 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

obj: a global or local reference.

RETURNS:

Returns a global reference, or NULL if the system runs out of memory.

DeleteGlobalRef

void DeleteGlobalRef(JNIEnv *env, jobject globalRef);

Deletes the global reference pointed to by globalRef.

LINKAGE:

Index 22 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

globalRef: a global reference.

Local References

Local references are valid for the duration of a native method call. They are freed automatically after the native method returns. Each local reference costs some amount of Java Virtual Machine resource. Programmers need to make sure that native methods do not excessively allocate local references. Although local references are automatically freed after the native method returns to Java, excessive allocation of local references may cause the VM to run out of memory during the execution of a native method.

DeleteLocalRef

void DeleteLocalRef(JNIEnv *env, jobject localRef);

Deletes the local reference pointed to by localRef.

LINKAGE:

Index 23 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

localRef: a local reference.

Note

SDK/JRE 1.1 provides the DeleteLocalRef function above so that programmers can manually delete local references. For example, if native code iterates through a potentially large array of objects and uses one element in each iteration, it is a good practice to delete the local reference to the no-longer-used array element before a new local reference is created in the next iteration.

The Java 2 SDK/JRE 1.2 and higher versions provide an additional set of functions for local reference lifetime management. They are the four functions listed below.

EnsureLocalCapacity

jint EnsureLocalCapacity(JNIEnv *env, jint capacity);

Ensures that at least a given number of local references can be created in the current thread. Returns 0 on success; otherwise returns a negative number and throws an OutOfMemoryError.

Before it enters a native method, the VM automatically ensures that at least 16 local references can be created.

For backward compatibility, the VM allocates local references beyond the ensured capacity. (As a debugging support, the VM may give the user warnings that too many local references are being created. In the Java 2 SDK, the programmer can supply the -verbose:jni command line option to turn on these messages.) The VM calls FatalError if no more local references can be created beyond the ensured capacity.

LINKAGE:
Index 26 in the JNIEnv interface function table.
SINCE:

SDK/JRE 1.2

PushLocalFrame

jint PushLocalFrame(JNIEnv *env, jint capacity);

Creates a new local reference frame, in which at least a given number of local references can be created. Returns 0 on success, a negative number and a pending OutOfMemoryError on failure.

Note that local references already created in previous local frames are still valid in the current local frame.

LINKAGE:
Index 19 in the JNIEnv interface function table.
SINCE:

SDK/JRE 1.2

PopLocalFrame

jobject PopLocalFrame(JNIEnv *env, jobject result);

Pops off the current local reference frame, frees all the local references, and returns a local reference in the previous local reference frame for the given result object.

Pass NULL as result if you do not need to return a reference to the previous frame.

LINKAGE:
Index 20 in the JNIEnv interface function table.
SINCE:

SDK/JRE 1.2

NewLocalRef

jobject NewLocalRef(JNIEnv *env, jobject ref);

Creates a new local reference that refers to the same object as ref. The given ref may be a global or local reference. Returns NULL if ref refers to null.

LINKAGE:
Index 25 in the JNIEnv interface function table.
SINCE:

SDK/JRE 1.2

Weak Global References

Weak global references are a special kind of global reference. Unlike normal global references, a weak global reference allows the underlying Java object to be garbage collected. Weak global references may be used in any situation where global or local references are used. When the garbage collector runs, it frees the underlying object if the object is only referred to by weak references. A weak global reference pointing to a freed object is functionally equivalent to NULL. Programmers can detect whether a weak global reference points to a freed object by using IsSameObject to compare the weak reference against NULL.

Weak global references in JNI are a simplified version of the Java Weak References, available as part of the Java 2 Platform API ( java.lang.ref package and its classes).

Clarification (added June 2001)

Since garbage collection may occur while native methods are running, objects referred to by weak global references can be freed at any time. While weak global references can be used where global references are used, it is generally inappropriate to do so, as they may become functionally equivalent to NULL without notice.

While IsSameObject can be used to determine whether a weak global reference refers to a freed object, it does not prevent the object from being freed immediately thereafter. Consequently, programmers may not rely on this check to determine whether a weak global reference may used (as a non-NULL reference) in any future JNI function call.

To overcome this inherent limitation, it is recommended that a standard (strong) local or global reference to the same object be acquired using the JNI functions NewLocalRef or NewGlobalRef, and that this strong reference be used to access the intended object. These functions will return NULL if the object has been freed, and otherwise will return a strong reference (which will prevent the object from being freed). The new reference should be explicitly deleted when immediate access to the object is no longer required, allowing the object to be freed.

The weak global reference is weaker than other types of weak references (Java objects of the SoftReference or WeakReference classes). A weak global reference to a specific object will not become functionally equivalent to NULL until after SoftReference or WeakReference objects referring to that same specific object have had their references cleared.

The weak global reference is weaker than Java's internal references to objects requiring finalization. A weak global reference will not become functionally equivalent to NULL until after the completion of the the finalizer for the referenced object, if present.

Interactions between weak global references and PhantomReferences are undefined. In particular, implementations of a Java VM may (or may not) process weak global references after PhantomReferences, and it may (or may not) be possible to use weak global references to hold on to objects which are also referred to by PhantomReference objects. This undefined use of weak global references should be avoided.

NewWeakGlobalRef

jweak NewWeakGlobalRef(JNIEnv *env, jobject obj);

Creates a new weak global reference. Returns NULL if obj refers to null, or if the VM runs out of memory. If the VM runs out of memory, an OutOfMemoryError will be thrown.

LINKAGE:
Index 226 in the JNIEnv interface function table.
SINCE:

SDK/JRE 1.2

DeleteWeakGlobalRef

void DeleteWeakGlobalRef(JNIEnv *env, jweak obj);

Delete the VM resources needed for the given weak global reference.

LINKAGE:
Index 227 in the JNIEnv interface function table.
SINCE:

SDK/JRE 1.2

Object Operations

AllocObject

jobject AllocObject(JNIEnv *env, jclass clazz);

Allocates a new Java object without invoking any of the constructors for the object. Returns a reference to the object.

The clazz argument must not refer to an array class.

LINKAGE:

Index 27 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

RETURNS:

Returns a Java object, or NULL if the object cannot be constructed.

THROWS:

InstantiationException: if the class is an interface or an abstract class.

OutOfMemoryError: if the system runs out of memory.

NewObject
NewObjectA
NewObjectV

jobject NewObject(JNIEnv *env, jclass clazz,
jmethodID methodID, ...);

jobject NewObjectA(JNIEnv *env, jclass clazz,
jmethodID methodID, jvalue *args);

jobject NewObjectV(JNIEnv *env, jclass clazz,
jmethodID methodID, va_list args);

Constructs a new Java object. The method ID indicates which constructor method to invoke. This ID must be obtained by calling GetMethodID() with <init> as the method name and void (V) as the return type.

The clazz argument must not refer to an array class.

NewObject

Programmers place all arguments that are to be passed to the constructor immediately following the methodID argument. NewObject() accepts these arguments and passes them to the Java method that the programmer wishes to invoke.

LINKAGE:

Index 28 in the JNIEnv interface function table.

NewObjectA

Programmers place all arguments that are to be passed to the constructor in an args array of jvalues that immediately follows the methodID argument. NewObjectA() accepts the arguments in this array, and, in turn, passes them to the Java method that the programmer wishes to invoke.

LINKAGE:

Index 30 in the JNIEnv interface function table.

NewObjectV

Programmers place all arguments that are to be passed to the constructor in an args argument of type va_list that immediately follows the methodID argument. NewObjectV() accepts these arguments, and, in turn, passes them to the Java method that the programmer wishes to invoke.

LINKAGE:

Index 29 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

methodID: the method ID of the constructor.

Additional Parameter for NewObject:

arguments to the constructor.

Additional Parameter for NewObjectA:

args: an array of arguments to the constructor.

Additional Parameter for NewObjectV:

args: a va_list of arguments to the constructor.

RETURNS:

Returns a Java object, or NULL if the object cannot be constructed.

THROWS:

InstantiationException: if the class is an interface or an abstract class.

OutOfMemoryError: if the system runs out of memory.

Any exceptions thrown by the constructor.

GetObjectClass

jclass GetObjectClass(JNIEnv *env, jobject obj);

Returns the class of an object.

LINKAGE:

Index 31 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

obj: a Java object (must not be NULL).

RETURNS:

Returns a Java class object.

GetObjectRefType

jobjectRefType GetObjectRefType(JNIEnv* env, jobject obj);

Returns the type of the object referred to by the obj argument. The argument obj can either be a local, global or weak global reference.

LINKAGE:

Index 232 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

obj: a local, global or weak global reference.

vm: the virtual machine instance from which the interface will be retrieved.

env: pointer to the location where the JNI interface pointer for the current thread will be placed.

version: the requested JNI version.

RETURNS:

The function GetObjectRefType returns one of the following enumerated values defined as a jobjectRefType:

JNIInvalidRefType = 0,
JNILocalRefType = 1,
JNIGlobalRefType = 2,
JNIWeakGlobalRefType = 3

If the argument obj is a weak global reference type, the return will be JNIWeakGlobalRefType.

If the argument obj is a global reference type, the return value will be JNIGlobalRefType.

If the argument obj is a local reference type, the return will be JNILocalRefType.

If the obj argument is not a valid reference, the return value for this function will be JNIInvalidRefType.

An invalid reference is a reference which is not a valid handle. That is, the obj pointer address does not point to a location in memory which has been allocated from one of the Ref creation functions or returned from a JNI function.

As such, NULL would be an invalid reference and GetObjectRefType(env,NULL) would return JNIInvalidRefType.

On the other hand, a null reference, which is a reference that points to a null, would return the type of reference that the null reference was originally created as.

GetObjectRefType cannot be used on deleted references.

Since references are typically implemented as pointers to memory data structures that can potentially be reused by any of the reference allocation services in the VM, once deleted, it is not specified what value the GetObjectRefType will return.

IsInstanceOf

jboolean IsInstanceOf(JNIEnv *env, jobject obj,
jclass clazz);

Tests whether an object is an instance of a class.

LINKAGE:

Index 32 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

obj: a Java object.

clazz: a Java class object.

RETURNS:

Returns JNI_TRUE if obj can be cast to clazz; otherwise, returns JNI_FALSE. A NULL object can be cast to any class.

IsSameObject

jboolean IsSameObject(JNIEnv *env, jobject ref1,
jobject ref2);

Tests whether two references refer to the same Java object.

LINKAGE:

Index 24 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

ref1: a Java object.

ref2: a Java object.

RETURNS:

Returns JNI_TRUE if ref1 and ref2 refer to the same Java object, or are both NULL; otherwise, returns JNI_FALSE.

Accessing Fields of Objects

GetFieldID

jfieldID GetFieldID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

Returns the field ID for an instance (nonstatic) field of a class. The field is specified by its name and signature. The Get<type>Field and Set<type>Field families of accessor functions use field IDs to retrieve object fields.

GetFieldID() causes an uninitialized class to be initialized.

GetFieldID() cannot be used to obtain the length field of an array. Use GetArrayLength() instead.

LINKAGE:

Index 94 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

name: the field name in a 0-terminated UTF-8 string.

sig: the field signature in a 0-terminated UTF-8 string.

RETURNS:

Returns a field ID, or NULL if the operation fails.

THROWS:

NoSuchFieldError: if the specified field cannot be found.

ExceptionInInitializerError: if the class initializer fails due to an exception.

OutOfMemoryError: if the system runs out of memory.

Get<type>Field Routines

NativeType Get<type>Field(JNIEnv *env, jobject obj,
jfieldID fieldID);

This family of accessor routines returns the value of an instance (nonstatic) field of an object. The field to access is specified by a field ID obtained by calling GetFieldID().

The following table describes the Get<type>Field routine name and result type. You should replace type in Get<type>Field with the Java type of the field, or use one of the actual routine names from the table, and replace NativeType with the corresponding native type for that routine.

Table 4-1a Get<type>Field Family of Accessor Routines
Get<type>Field Routine Name | Native Type
GetObjectField() | jobject
GetBooleanField() | jboolean
GetByteField() | jbyte
GetCharField() | jchar
GetShortField() | jshort
GetIntField() | jint
GetLongField() | jlong
GetFloatField() | jfloat
GetDoubleField() | jdouble

LINKAGE:
Indices in the JNIEnv interface function table:

Table 4-1b Get<type>Field Family of Accessor Routines
Get<type>Field Routine Name | Index
GetObjectField() | 95
GetBooleanField() | 96
GetByteField() | 97
GetCharField() | 98
GetShortField() | 99
GetIntField() | 100
GetLongField() | 101
GetFloatField() | 102
GetDoubleField() | 103

PARAMETERS:

env: the JNI interface pointer.

obj: a Java object (must not be NULL).

fieldID: a valid field ID.

RETURNS:

Returns the content of the field.

Set<type>Field Routines

void Set<type>Field(JNIEnv *env, jobject obj, jfieldID fieldID,
NativeType value);

This family of accessor routines sets the value of an instance (nonstatic) field of an object. The field to access is specified by a field ID obtained by calling GetFieldID().

The following table describes the Set<type>Field routine name and value type. You should replace type in Set<type>Field with the Java type of the field, or use one of the actual routine names from the table, and replace NativeType with the corresponding native type for that routine.

Table 4-2a Set<type>Field Family of Accessor Routines
Set<type>Field Routine | Native Type
SetObjectField() | jobject
SetBooleanField() | jboolean
SetByteField() | jbyte
SetCharField() | jchar
SetShortField() | jshort
SetIntField() | jint
SetLongField() | jlong
SetFloatField() | jfloat
SetDoubleField() | jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-2b Set<type>Field Family of Accessor Routines
Set<type>Field Routine | Index
SetObjectField() | 104
SetBooleanField() | 105
SetByteField() | 106
SetCharField() | 107
SetShortField() | 108
SetIntField() | 109
SetLongField() | 110
SetFloatField() | 111
SetDoubleField() | 112
PARAMETERS:

env: the JNI interface pointer.

obj: a Java object (must not be NULL).

fieldID: a valid field ID.

value: the new value of the field.

Calling Instance Methods

GetMethodID

jmethodID GetMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

Returns the method ID for an instance (nonstatic) method of a class or interface. The method may be defined in one of the clazz’s superclasses and inherited by clazz. The method is determined by its name and signature.

GetMethodID() causes an uninitialized class to be initialized.

To obtain the method ID of a constructor, supply <init> as the method name and void (V) as the return type.

LINKAGE:

Index 33 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

name: the method name in a 0-terminated UTF-8 string.

sig: the method signature in 0-terminated UTF-8 string.

RETURNS:

Returns a method ID, or NULL if the specified method cannot be found.

THROWS:

NoSuchMethodError: if the specified method cannot be found.

ExceptionInInitializerError: if the class initializer fails due to an exception.

OutOfMemoryError: if the system runs out of memory.

Call<type>Method Routines
Call<type>MethodA Routines
Call<type>MethodV Routines

NativeType Call<type>Method(JNIEnv *env, jobject obj,
jmethodID methodID, ...);

NativeType Call<type>MethodA(JNIEnv *env, jobject obj,
jmethodID methodID, jvalue *args);

NativeType Call<type>MethodV(JNIEnv *env, jobject obj,
jmethodID methodID, va_list args);

Methods from these three families of operations are used to call a Java instance method from a native method.They only differ in their mechanism for passing parameters to the methods that they call.

These families of operations invoke an instance (nonstatic) method on a Java object, according to the specified method ID. The methodID argument must be obtained by calling GetMethodID().

When these functions are used to call private methods and constructors, the method ID must be derived from the real class of obj, not from one of its superclasses.

Call<type>Method Routines

Programmers place all arguments that are to be passed to the method immediately following the methodID argument. The Call<type>Method routine accepts these arguments and passes them to the Java method that the programmer wishes to invoke.

Call<type>MethodA Routines

Programmers place all arguments to the method in an args array of jvalues that immediately follows the methodID argument. The Call<type>MethodA routine accepts the arguments in this array, and, in turn, passes them to the Java method that the programmer wishes to invoke.

Call<type>MethodV Routines

Programmers place all arguments to the method in an args argument of type va_list that immediately follows the methodID argument. The Call<type>MethodV routine accepts the arguments, and, in turn, passes them to the Java method that the programmer wishes to invoke.

The following table describes each of the method calling routines according to their result type. You should replace type in Call<type>Method with the Java type of the method you are calling (or use one of the actual method calling routine names from the table) and replace NativeType with the corresponding native type for that routine.

Table 4-3a Instance Method Calling Routines
Call<type>Method Routine Name | Native Type
CallVoidMethod() CallVoidMethodA() CallVoidMethodV() | void
CallObjectMethod() CallObjectMethodA() CallObjectMethodV() | jobject
CallBooleanMethod() CallBooleanMethodA() CallBooleanMethodV() | jboolean
CallByteMethod() CallByteMethodA() CallByteMethodV() | jbyte
CallCharMethod() CallCharMethodA() CallCharMethodV() | jchar
CallShortMethod() CallShortMethodA() CallShortMethodV() | jshort
CallIntMethod() CallIntMethodA() CallIntMethodV() | jint
CallLongMethod() CallLongMethodA() CallLongMethodV() | jlong
CallFloatMethod() CallFloatMethodA() CallFloatMethodV() | jfloat
CallDoubleMethod() CallDoubleMethodA() CallDoubleMethodV() | jdouble

LINKAGE:

Indices in the JNIEnv interface function table:

Table 4-3b Instance Method Calling Routines
Call<type>Method Routine Name | Index
CallVoidMethod() CallVoidMethodA() CallVoidMethodV() | 61 63 62
CallObjectMethod() CallObjectMethodA() CallObjectMethodV() | 34 36 35
CallBooleanMethod() CallBooleanMethodA() CallBooleanMethodV() | 37 39 38
CallByteMethod() CallByteMethodA() CallByteMethodV() | 40 42 41
CallCharMethod() CallCharMethodA() CallCharMethodV() | 43 45 44
CallShortMethod() CallShortMethodA() CallShortMethodV() | 46 48 47
CallIntMethod() CallIntMethodA() CallIntMethodV() | 49 51 50
CallLongMethod() CallLongMethodA() CallLongMethodV() | 52 54 53
CallFloatMethod() CallFloatMethodA() CallFloatMethodV() | 55 57 56
CallDoubleMethod() CallDoubleMethodA() CallDoubleMethodV() | 58 60 59
PARAMETERS:

env: the JNI interface pointer.

obj: a Java object.

methodID: a method ID.

Additional Parameter for Call<type>Method Routines:

arguments to the Java method.

Additional Parameter for Call<type>MethodA Routines:

args: an array of arguments.

Additional Parameter for Call<type>MethodV Routines:

args: a va_list of arguments.

RETURNS:

Returns the result of calling the Java method.

THROWS:

Exceptions raised during the execution of the Java method.

CallNonvirtual<type>Method Routines
CallNonvirtual<type>MethodA Routines
CallNonvirtual<type>MethodV Routines

NativeType CallNonvirtual<type>Method(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, ...);

NativeType CallNonvirtual<type>MethodA(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, jvalue *args);

NativeType CallNonvirtual<type>MethodV(JNIEnv *env, jobject obj,
jclass clazz, jmethodID methodID, va_list args);

These families of operations invoke an instance (nonstatic) method on a Java object, according to the specified class and method ID. The methodID argument must be obtained by calling GetMethodID() on the class clazz.

The CallNonvirtual<type>Method families of routines and the Call<type>Method families of routines are different. Call<type>Method routines invoke the method based on the class of the object, while CallNonvirtual<type>Method routines invoke the method based on the class, designated by the clazz parameter, from which the method ID is obtained. The method ID must be obtained from the real class of the object or from one of its superclasses.

CallNonvirtual<type>Method Routines

Programmers place all arguments that are to be passed to the method immediately following the methodID argument. The CallNonvirtual<type>Method routine accepts these arguments and passes them to the Java method that the programmer wishes to invoke.

CallNonvirtual<type>MethodA Routines

Programmers place all arguments to the method in an args array of jvalues that immediately follows the methodID argument. The CallNonvirtual<type>MethodA routine accepts the arguments in this array, and, in turn, passes them to the Java method that the programmer wishes to invoke.

CallNonvirtual<type>MethodV Routines

Programmers place all arguments to the method in an args argument of type va_list that immediately follows the methodID argument. The CallNonvirtualMethodV routine accepts the arguments, and, in turn, passes them to the Java method that the programmer wishes to invoke.

The following table describes each of the method calling routines according to their result type. You should replace type in CallNonvirtual<type>Method with the Java type of the method, or use one of the actual method calling routine names from the table, and replace NativeType with the corresponding native type for that routine.

Table 4-4a CallNonvirtual<type>Method Routines
CallNonvirtual<type>Method Routine Name | Native Type
CallNonvirtualVoidMethod() CallNonvirtualVoidMethodA() CallNonvirtualVoidMethodV() | void
CallNonvirtualObjectMethod() CallNonvirtualObjectMethodA() CallNonvirtualObjectMethodV() | jobject
CallNonvirtualBooleanMethod() CallNonvirtualBooleanMethodA() CallNonvirtualBooleanMethodV() | jboolean
CallNonvirtualByteMethod() CallNonvirtualByteMethodA() CallNonvirtualByteMethodV() | jbyte
CallNonvirtualCharMethod() CallNonvirtualCharMethodA() CallNonvirtualCharMethodV() | jchar
CallNonvirtualShortMethod() CallNonvirtualShortMethodA() CallNonvirtualShortMethodV() | jshort
CallNonvirtualIntMethod() CallNonvirtualIntMethodA() CallNonvirtualIntMethodV() | jint
CallNonvirtualLongMethod() CallNonvirtualLongMethodA() CallNonvirtualLongMethodV() | jlong
CallNonvirtualFloatMethod() CallNonvirtualFloatMethodA() CallNonvirtualFloatMethodV() | jfloat
CallNonvirtualDoubleMethod() CallNonvirtualDoubleMethodA() CallNonvirtualDoubleMethodV() | jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-4b CallNonvirtual<type>Method Routines
CallNonvirtual<type>Method Routine Name | Index
CallNonvirtualVoidMethod() CallNonvirtualVoidMethodA() CallNonvirtualVoidMethodV() | 91 93 92
CallNonvirtualObjectMethod() CallNonvirtualObjectMethodA() CallNonvirtualObjectMethodV() | 64 66 65
CallNonvirtualBooleanMethod() CallNonvirtualBooleanMethodA() CallNonvirtualBooleanMethodV() | 67 69 68
CallNonvirtualByteMethod() CallNonvirtualByteMethodA() CallNonvirtualByteMethodV() | 70 72 71
CallNonvirtualCharMethod() CallNonvirtualCharMethodA() CallNonvirtualCharMethodV() | 73 75 74
CallNonvirtualShortMethod() CallNonvirtualShortMethodA() CallNonvirtualShortMethodV() | 76 78 77
CallNonvirtualIntMethod() CallNonvirtualIntMethodA() CallNonvirtualIntMethodV() | 79 81 80
CallNonvirtualLongMethod() CallNonvirtualLongMethodA() CallNonvirtualLongMethodV() | 82 84 83
CallNonvirtualFloatMethod() CallNonvirtualFloatMethodA() CallNonvirtualFloatMethodV() | 85 87 86
CallNonvirtualDoubleMethod() CallNonvirtualDoubleMethodA() CallNonvirtualDoubleMethodV() | 88 90 89
PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class.

obj: a Java object.

methodID: a method ID.

Additional Parameter for CallNonvirtual<type>Method Routines:

arguments to the Java method.

Additional Parameter for CallNonvirtual<type>MethodA Routines:

args: an array of arguments.

Additional Parameter for CallNonvirtual<type>MethodV Routines:

args: a va_list of arguments.

RETURNS:

Returns the result of calling the Java method.

THROWS:

Exceptions raised during the execution of the Java method.

Accessing Static Fields

GetStaticFieldID

jfieldID GetStaticFieldID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

Returns the field ID for a static field of a class. The field is specified by its name and signature. The GetStatic<type>Field and SetStatic<type>Field families of accessor functions use field IDs to retrieve static fields.

GetStaticFieldID() causes an uninitialized class to be initialized.

LINKAGE:

Index 144 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

name: the static field name in a 0-terminated UTF-8 string.

sig: the field signature in a 0-terminated UTF-8 string.

RETURNS:

Returns a field ID, or NULL if the specified static field cannot be found.

THROWS:

NoSuchFieldError: if the specified static field cannot be found.

ExceptionInInitializerError: if the class initializer fails due to an exception.

OutOfMemoryError: if the system runs out of memory.

GetStatic<type>Field Routines

NativeType GetStatic<type>Field(JNIEnv *env, jclass clazz,
jfieldID fieldID);

This family of accessor routines returns the value of a static field of an object. The field to access is specified by a field ID, which is obtained by calling GetStaticFieldID().

The following table describes the family of get routine names and result types. You should replace type in GetStatic<type>Field with the Java type of the field, or one of the actual static field accessor routine names from the table, and replace NativeType with the corresponding native type for that routine.

Table 4-5a GetStatic<type>Field Family of Accessor Routines
GetStatic<type>Field Routine Name | Native Type
GetStaticObjectField() | jobject
GetStaticBooleanField() | jboolean
GetStaticByteField() | jbyte
GetStaticCharField() | jchar
GetStaticShortField() | jshort
GetStaticIntField() | jint
GetStaticLongField() | jlong
GetStaticFloatField() | jfloat
GetStaticDoubleField() | jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-5b GetStatic<type>Field Family of Accessor Routines
GetStatic<type>Field Routine Name | Index
GetStaticObjectField() | 145
GetStaticBooleanField() | 146
GetStaticByteField() | 147
GetStaticCharField() | 148
GetStaticShortField() | 149
GetStaticIntField() | 150
GetStaticLongField() | 151
GetStaticFloatField() | 152
GetStaticDoubleField() | 153
PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

fieldID: a static field ID.

RETURNS:

Returns the content of the static field.

SetStatic<type>Field Routines

void SetStatic<type>Field(JNIEnv *env, jclass clazz,
jfieldID fieldID, NativeType value);

This family of accessor routines sets the value of a static field of an object. The field to access is specified by a field ID, which is obtained by calling GetStaticFieldID().

The following table describes the set routine name and value types. You should replace type in SetStatic<type>Field with the Java type of the field, or one of the actual set static field routine names from the table, and replace NativeType with the corresponding native type for that routine.

Table 4-6a SetStatic<type>Field Family of Accessor Routines
SetStatic<type>Field Routine Name | NativeType
SetStaticObjectField() | jobject
SetStaticBooleanField() | jboolean
SetStaticByteField() | jbyte
SetStaticCharField() | jchar
SetStaticShortField() | jshort
SetStaticIntField() | jint
SetStaticLongField() | jlong
SetStaticFloatField() | jfloat
SetStaticDoubleField() | jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-6b SetStatic<type>Field Family of Accessor Routines
SetStatic<type>Field Routine Name | Index
SetStaticObjectField() | 154
SetStaticBooleanField() | 155
SetStaticByteField() | 156
SetStaticCharField() | 157
SetStaticShortField() | 158
SetStaticIntField() | 159
SetStaticLongField() | 160
SetStaticFloatField() | 161
SetStaticDoubleField() | 162
PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

fieldID: a static field ID.

value: the new value of the field.

Calling Static Methods

GetStaticMethodID

jmethodID GetStaticMethodID(JNIEnv *env, jclass clazz,
const char *name, const char *sig);

Returns the method ID for a static method of a class. The method is specified by its name and signature.

GetStaticMethodID() causes an uninitialized class to be initialized.

LINKAGE:
Index 113 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

name: the static method name in a 0-terminated UTF-8 string.

sig: the method signature in a 0-terminated UTF-8 string.

RETURNS:

Returns a method ID, or NULL if the operation fails.

THROWS:

NoSuchMethodError: if the specified static method cannot be found.

ExceptionInInitializerError: if the class initializer fails due to an exception.

OutOfMemoryError: if the system runs out of memory.

CallStatic<type>Method Routines
CallStatic<type>MethodA Routines
CallStatic<type>MethodV Routines

NativeType CallStatic<type>Method(JNIEnv *env, jclass clazz,
jmethodID methodID, ...);

NativeType CallStatic<type>MethodA(JNIEnv *env, jclass clazz,
jmethodID methodID, jvalue *args);

NativeType CallStatic<type>MethodV(JNIEnv *env, jclass clazz,
jmethodID methodID, va_list args);

This family of operations invokes a static method on a Java object, according to the specified method ID. The methodID argument must be obtained by calling GetStaticMethodID().

The method ID must be derived from clazz, not from one of its superclasses.

CallStatic<type>Method Routines

Programmers should place all arguments that are to be passed to the method immediately following the methodID argument. The CallStatic<type>Method routine accepts these arguments and passes them to the Java method that the programmer wishes to invoke.

CallStatic<type>MethodA Routines

Programmers should place all arguments to the method in an args array of jvalues that immediately follows the methodID argument. The CallStaticMethodA routine accepts the arguments in this array, and, in turn, passes them to the Java method that the programmer wishes to invoke.

CallStatic<type>MethodV Routines

Programmers should place all arguments to the method in an args argument of type va_list that immediately follows the methodID argument. The CallStaticMethodV routine accepts the arguments, and, in turn, passes them to the Java method that the programmer wishes to invoke.

The following table describes each of the method calling routines according to their result types. You should replace type in CallStatic<type>Method with the Java type of the method, or one of the actual method calling routine names from the table, and replace NativeType with the corresponding native type for that routine.

Table 4-7a CallStatic<type>Method Calling Routines
CallStatic<type>Method Routine Name | Native Type
CallStaticVoidMethod() CallStaticVoidMethodA() CallStaticVoidMethodV() | void
CallStaticObjectMethod() CallStaticObjectMethodA() CallStaticObjectMethodV() | jobject
CallStaticBooleanMethod() CallStaticBooleanMethodA() CallStaticBooleanMethodV() | jboolean
CallStaticByteMethod() CallStaticByteMethodA() CallStaticByteMethodV() | jbyte
CallStaticCharMethod() CallStaticCharMethodA() CallStaticCharMethodV() | jchar
CallStaticShortMethod() CallStaticShortMethodA() CallStaticShortMethodV() | jshort
CallStaticIntMethod() CallStaticIntMethodA() CallStaticIntMethodV() | jint
CallStaticLongMethod() CallStaticLongMethodA() CallStaticLongMethodV() | jlong
CallStaticFloatMethod() CallStaticFloatMethodA() CallStaticFloatMethodV() | jfloat
CallStaticDoubleMethod() CallStaticDoubleMethodA() CallStaticDoubleMethodV() | jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-7b CallStatic<type>Method Calling Routines
CallStatic<type>Method Routine Name | Index
CallStaticVoidMethod() CallStaticVoidMethodA() CallStaticVoidMethodV() | 141 143 142
CallStaticObjectMethod() CallStaticObjectMethodA() CallStaticObjectMethodV() | 114 116 115
CallStaticBooleanMethod() CallStaticBooleanMethodA() CallStaticBooleanMethodV() | 117 119 118
CallStaticByteMethod() CallStaticByteMethodA() CallStaticByteMethodV() | 120 122 121
CallStaticCharMethod() CallStaticCharMethodA() CallStaticCharMethodV() | 123 125 124
CallStaticShortMethod() CallStaticShortMethodA() CallStaticShortMethodV() | 126 128 127
CallStaticIntMethod() CallStaticIntMethodA() CallStaticIntMethodV() | 129 131 130
CallStaticLongMethod() CallStaticLongMethodA() CallStaticLongMethodV() | 132 134 133
CallStaticFloatMethod() CallStaticFloatMethodA() CallStaticFloatMethodV() | 135 137 136
CallStaticDoubleMethod() CallStaticDoubleMethodA() CallStaticDoubleMethodV() | 138 140 139
PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

methodID: a static method ID.

Additional Parameter for CallStatic<type>Method Routines:

arguments to the static method.

Additional Parameter for CallStatic<type>MethodA Routines:

args: an array of arguments.

Additional Parameter for CallStatic<type>MethodV Routines:

args: a va_list of arguments.

RETURNS:

Returns the result of calling the static Java method.

THROWS:

Exceptions raised during the execution of the Java method.

String Operations

NewString

jstring NewString(JNIEnv *env, const jchar *unicodeChars,
jsize len);

Constructs a new java.lang.String object from an array of Unicode characters.

LINKAGE:
Index 163 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

unicodeChars: pointer to a Unicode string.

len: length of the Unicode string.

RETURNS:

Returns a Java string object, or NULL if the string cannot be constructed.

THROWS:

OutOfMemoryError: if the system runs out of memory.

GetStringLength

jsize GetStringLength(JNIEnv *env, jstring string);

Returns the length (the count of Unicode characters) of a Java string.

LINKAGE:
Index 164 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

string: a Java string object.

RETURNS:

Returns the length of the Java string.

GetStringChars

const jchar * GetStringChars(JNIEnv *env, jstring string,
jboolean *isCopy);

Returns a pointer to the array of Unicode characters of the string. This pointer is valid until ReleaseStringchars() is called.

If isCopy is not NULL, then *isCopy is set to JNI_TRUE if a copy is made; or it is set to JNI_FALSE if no copy is made.

LINKAGE:
Index 165 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

string: a Java string object.

isCopy: a pointer to a boolean.

RETURNS:

Returns a pointer to a Unicode string, or NULL if the operation fails.

ReleaseStringChars

void ReleaseStringChars(JNIEnv *env, jstring string,
const jchar *chars);

Informs the VM that the native code no longer needs access to chars. The chars argument is a pointer obtained from string using GetStringChars().

LINKAGE:
Index 166 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

string: a Java string object.

chars: a pointer to a Unicode string.

NewStringUTF

jstring NewStringUTF(JNIEnv *env, const char *bytes);

Constructs a new java.lang.String object from an array of UTF-8 characters.

LINKAGE:
Index 167 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

bytes: the pointer to a UTF-8 string.

RETURNS:

Returns a Java string object, or NULL if the string cannot be constructed.

THROWS:

OutOfMemoryError: if the system runs out of memory.

GetStringUTFLength

jsize GetStringUTFLength(JNIEnv *env, jstring string);

Returns the UTF-8 length in bytes of a string.

LINKAGE:
Index 168 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

string: a Java string object.

RETURNS:

Returns the UTF-8 length of the string.

GetStringUTFChars

const jbyte* GetStringUTFChars(JNIEnv *env, jstring string,
jboolean *isCopy);

Returns a pointer to an array of UTF-8 characters of the string. This array is valid until it is released by ReleaseStringUTFChars().

If isCopy is not NULL, then *isCopy is set to JNI_TRUE if a copy is made; or it is set to JNI_FALSE if no copy is made.

LINKAGE:
Index 169 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

string: a Java string object.

isCopy: a pointer to a boolean.

RETURNS:

Returns a pointer to a UTF-8 string, or NULL if the operation fails.

ReleaseStringUTFChars

void ReleaseStringUTFChars(JNIEnv *env, jstring string,
const char *utf);

Informs the VM that the native code no longer needs access to utf. The utf argument is a pointer derived from string using GetStringUTFChars().

LINKAGE:
Index 170 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

string: a Java string object.

utf: a pointer to a UTF-8 string.

Note

In SKD/JRE 1.1, programmers can get primitive array elements in a user-supplied buffer. Java 2 SDK/JRE 1.2 and higher versions allow native code to obtain Unicode or UTF-8 characters in a user-supplied buffer. See the functions below.

GetStringRegion

void GetStringRegion(JNIEnv *env, jstring str, jsize start, jsize len, jchar *buf);

Copies len number of Unicode characters beginning at offset start to the given buffer buf.

Throws StringIndexOutOfBoundsException on index overflow.

LINKAGE:
Index 220 in the JNIEnv interface function table.
SINCE:

SDK/JRE 1.2

GetStringUTFRegion

< void GetStringUTFRegion(JNIEnv *env, jstring str, jsize start, jsize len, char *buf);

Translates len number of Unicode characters beginning at offset start into UTF-8 format and place the result in the given buffer buf.

Throws StringIndexOutOfBoundsException on index overflow.

LINKAGE:
Index 221 in the JNIEnv interface function table.
SINCE:

SDK/JRE 1.2

GetStringCritical
ReleaseStringCritical

const jchar * GetStringCritical(JNIEnv *env, jstring string, jboolean *isCopy);
void ReleaseStringCritical(JNIEnv *env, jstring string, const jchar *carray);

The semantics of these two functions are similar to the existing Get/ReleaseStringChars functions. If possible, the VM returns a pointer to string elements; otherwise, a copy is made. However, there are significant restrictions on how these functions can be used. In a code segment enclosed by Get/ReleaseStringCritical calls, the native code must not issue arbitrary JNI calls, or cause the current thread to block.

The restrictions on Get/ReleaseStringCritical are similar to those on Get/ReleasePrimitiveArrayCritical.

LINKAGE (GetStringCritical):
Index 224 in the JNIEnv interface function table.
LINKAGE (ReleaseStingCritical):
Index 225 in the JNIEnv interface function table.
SINCE:

SDK/JRE 1.2

Array Operations

GetArrayLength

jsize GetArrayLength(JNIEnv *env, jarray array);

Returns the number of elements in the array.

LINKAGE:
Index 171 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

array: a Java array object.

RETURNS:

Returns the length of the array.

NewObjectArray

jobjectArray NewObjectArray(JNIEnv *env, jsize length,
jclass elementClass, jobject initialElement);

Constructs a new array holding objects in class elementClass. All elements are initially set to initialElement.

LINKAGE:
Index 172 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

length: array size.

elementClass: array element class.

initialElement: initialization value.

RETURNS:

Returns a Java array object, or NULL if the array cannot be constructed.

THROWS:

OutOfMemoryError: if the system runs out of memory.

GetObjectArrayElement

jobject GetObjectArrayElement(JNIEnv *env,
jobjectArray array, jsize index);

Returns an element of an Object array.

LINKAGE:
Index 173 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

array: a Java array.

index: array index.

RETURNS:

Returns a Java object.

THROWS:

ArrayIndexOutOfBoundsException: if index does not specify a valid index in the array.

SetObjectArrayElement

void SetObjectArrayElement(JNIEnv *env, jobjectArray array,
jsize index, jobject value);

Sets an element of an Object array.

LINKAGE:
Index 174 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

array: a Java array.

index: array index.

value: the new value.

THROWS:

ArrayIndexOutOfBoundsException: if index does not specify a valid index in the array.

ArrayStoreException: if the class of value is not a subclass of the element class of the array.

New<PrimitiveType>Array Routines

ArrayType New<PrimitiveType>Array(JNIEnv *env, jsize length);

A family of operations used to construct a new primitive array object. Table 4-8 describes the specific primitive array constructors. You should replace New<PrimitiveType>Array with one of the actual primitive array constructor routine names from the following table, and replace ArrayType with the corresponding array type for that routine.

Table 4-8a New<PrimitiveType>Array Family of Array Constructors
New<PrimitiveType>Array Routines | Array Type
NewBooleanArray() | jbooleanArray
NewByteArray() | jbyteArray
NewCharArray() | jcharArray
NewShortArray() | jshortArray
NewIntArray() | jintArray
NewLongArray() | jlongArray
NewFloatArray() | jfloatArray
NewDoubleArray() | jdoubleArray

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-8b New<PrimitiveType>Array Family of Array Constructors
New<PrimitiveType>Array Routines | Index
NewBooleanArray() | 175
NewByteArray() | 176
NewCharArray() | 177
NewShortArray() | 178
NewIntArray() | 179
NewLongArray() | 180
NewFloatArray() | 181
NewDoubleArray() | 182
PARAMETERS:

env: the JNI interface pointer.

length: the array length.

RETURNS:

Returns a Java array, or NULL if the array cannot be constructed.

Get<PrimitiveType>ArrayElements Routines

NativeType *Get<PrimitiveType>ArrayElements(JNIEnv *env,
ArrayType array, jboolean *isCopy);

A family of functions that returns the body of the primitive array. The result is valid until the corresponding Release<PrimitiveType>ArrayElements() function is called. Since the returned array may be a copy of the Java array, changes made to the returned array will not necessarily be reflected in the original array until Release<PrimitiveType>ArrayElements() is called.

If isCopy is not NULL, then *isCopy is set to JNI_TRUE if a copy is made; or it is set to JNI_FALSE if no copy is made.

The following table describes the specific primitive array element accessors. You should make the following substitutions:

  • Replace Get<PrimitiveType>ArrayElements with one of the actual primitive element accessor routine names from the table.
  • Replace ArrayType with the corresponding array type.
  • Replace NativeType with the corresponding native type for that routine.

Regardless of how boolean arrays are represented in the Java VM, GetBooleanArrayElements() always returns a pointer to jbooleans, with each byte denoting an element (the unpacked representation). All arrays of other types are guaranteed to be contiguous in memory.

Table 4-9a Get<PrimitiveType>ArrayElements Family of Accessor Routines
Get<PrimitiveType>ArrayElements Routines | Array Type | Native Type
GetBooleanArrayElements() | jbooleanArray | jboolean
GetByteArrayElements() | jbyteArray | jbyte
GetCharArrayElements() | jcharArray | jchar
GetShortArrayElements() | jshortArray | jshort
GetIntArrayElements() | jintArray | jint
GetLongArrayElements() | jlongArray | jlong
GetFloatArrayElements() | jfloatArray | jfloat
GetDoubleArrayElements() | jdoubleArray | jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-9b Get<PrimitiveType>ArrayElements Family of Accessor Routines
Get<PrimitiveType>ArrayElements Routines | Index
GetBooleanArrayElements() | 183
GetByteArrayElements() | 184
GetCharArrayElements() | 185
GetShortArrayElements() | 186
GetIntArrayElements() | 187
GetLongArrayElements() | 188
GetFloatArrayElements() | 189
GetDoubleArrayElements() | 190
PARAMETERS:

env: the JNI interface pointer.

array: a Java string object.

isCopy: a pointer to a boolean.

RETURNS:

Returns a pointer to the array elements, or NULL if the operation fails.

Release<PrimitiveType>ArrayElements Routines

void Release<PrimitiveType>ArrayElements(JNIEnv *env,
ArrayType array, NativeType *elems, jint mode);

A family of functions that informs the VM that the native code no longer needs access to elems. The elems argument is a pointer derived from array using the corresponding Get<PrimitiveType>ArrayElements() function. If necessary, this function copies back all changes made to elems to the original array.

The mode argument provides information on how the array buffer should be released. mode has no effect if elems is not a copy of the elements in array. Otherwise, mode has the following impact, as shown in the following table:

Table 4-10 Primitive Array Release Modes
mode | actions
0 | copy back the content and free the elems buffer
JNI_COMMIT | copy back the content but do not free the elems buffer
JNI_ABORT | free the buffer without copying back the possible changes

In most cases, programmers pass “0” to the mode argument to ensure consistent behavior for both pinned and copied arrays. The other options give the programmer more control over memory management and should be used with extreme care.

The next table describes the specific routines that comprise the family of primitive array disposers. You should make the following substitutions:

  • Replace Release<PrimitiveType>ArrayElements with one of the actual primitive array disposer routine names from Table 4-11.
  • Replace ArrayType with the corresponding array type.
  • Replace NativeType with the corresponding native type for that routine.

Table 4-11a Release<PrimitiveType>ArrayElements Family of Array Routines
Release<PrimitiveType>ArrayElements Routines | Array Type | Native Type
ReleaseBooleanArrayElements() | jbooleanArray | jboolean
ReleaseByteArrayElements() | jbyteArray | jbyte
ReleaseCharArrayElements() | jcharArray | jchar
ReleaseShortArrayElements() | jshortArray | jshort
ReleaseIntArrayElements() | jintArray | jint
ReleaseLongArrayElements() | jlongArray | jlong
ReleaseFloatArrayElements() | jfloatArray | jfloat
ReleaseDoubleArrayElements() | jdoubleArray | jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-11b Release<PrimitiveType>ArrayElements Family of Array Routines
Release<PrimitiveType>ArrayElements Routines | Index
ReleaseBooleanArrayElements() | 191
ReleaseByteArrayElements() | 192
ReleaseCharArrayElements() | 193
ReleaseShortArrayElements() | 194
ReleaseIntArrayElements() | 195
ReleaseLongArrayElements() | 196
ReleaseFloatArrayElements() | 197
ReleaseDoubleArrayElements() | 198
PARAMETERS:

env: the JNI interface pointer.

array: a Java array object.

elems: a pointer to array elements.

mode: the release mode.

Get<PrimitiveType>ArrayRegion Routines

void Get<PrimitiveType>ArrayRegion(JNIEnv *env, ArrayType array,
jsize start, jsize len, NativeType *buf);

A family of functions that copies a region of a primitive array into a buffer.

The following table describes the specific primitive array element accessors. You should do the following substitutions:

  • Replace Get<PrimitiveType>ArrayRegion with one of the actual primitive element accessor routine names from Table 4-12.
  • Replace ArrayType with the corresponding array type.
  • Replace NativeType with the corresponding native type for that routine.

Table 4-12a Get<PrimitiveType>ArrayRegion Family of Array Accessor Routines
Get<PrimitiveType>ArrayRegion Routine | Array Type | Native Type
GetBooleanArrayRegion() | jbooleanArray | jboolean
GetByteArrayRegion() | jbyteArray | jbyte
GetCharArrayRegion() | jcharArray | jchar
GetShortArrayRegion() | jshortArray | jhort
GetIntArrayRegion() | jintArray | jint
GetLongArrayRegion() | jlongArray | jlong
GetFloatArrayRegion() | jfloatArray | jloat
GetDoubleArrayRegion() | jdoubleArray | jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-12b Get<PrimitiveType>ArrayRegion Family of Array Accessor Routines
Get<PrimitiveType>ArrayRegion Routine | Index
GetBooleanArrayRegion() | 199
GetByteArrayRegion() | 200
GetCharArrayRegion() | 201
GetShortArrayRegion() | 202
GetIntArrayRegion() | 203
GetLongArrayRegion() | 204
GetFloatArrayRegion() | 205
GetDoubleArrayRegion() | 206
PARAMETERS:

env: the JNI interface pointer.

array: a Java array.

start: the starting index.

len: the number of elements to be copied.

buf: the destination buffer.

THROWS:

ArrayIndexOutOfBoundsException: if one of the indexes in the region is not valid.

Set<PrimitiveType>ArrayRegion Routines

void Set<PrimitiveType>ArrayRegion(JNIEnv *env, ArrayType array,
jsize start, jsize len, NativeType *buf);

A family of functions that copies back a region of a primitive array from a buffer.

The following table describes the specific primitive array element accessors. You should make the following replacements:

  • Replace Set<PrimitiveType>ArrayRegion with one of the actual primitive element accessor routine names from the table.
  • Replace ArrayType with the corresponding array type.
  • Replace NativeType with the corresponding native type for that routine.
    Table 4-13a Set<PrimitiveType>ArrayRegion Family of Array Accessor Routines
    Set<PrimitiveType>ArrayRegion Routine
    Array Type
    Native Type
    SetBooleanArrayRegion()
    jbooleanArray
    jboolean
    SetByteArrayRegion()
    jbyteArray
    jbyte
    SetCharArrayRegion()
    jcharArray
    jchar
    SetShortArrayRegion()
    jshortArray
    jshort
    SetIntArrayRegion()
    jintArray
    jint
    SetLongArrayRegion()
    jlongArray
    jlong
    SetFloatArrayRegion()
    jfloatArray
    jfloat
    SetDoubleArrayRegion()
    jdoubleArray
    jdouble

LINKAGE:

Indices in the JNIEnv interface function table.

Table 4-13b Set<PrimitiveType>ArrayRegion Family of Array Accessor Routines
Set<PrimitiveType>ArrayRegion Routine | Index
SetBooleanArrayRegion() | 207
SetByteArrayRegion() | 208
SetCharArrayRegion() | 209
SetShortArrayRegion() | 210
SetIntArrayRegion() | 211
SetLongArrayRegion() | 212
SetFloatArrayRegion() | 213
SetDoubleArrayRegion() | 214

PARAMETERS:

env: the JNI interface pointer.

array: a Java array.

start: the starting index.

len: the number of elements to be copied.

buf: the source buffer.

THROWS:

ArrayIndexOutOfBoundsException: if one of the indexes in the region is not valid.

Note

In SDK/JRE 1.1, programmers can use Get/ReleaseArrayElements functions to obtain a pointer to primitive array elements. If the VM supports pinning, the pointer to the original data is returned; otherwise, a copy is made.

New functions introduced in SDK/JRE 1.3 allow native code to obtain a direct pointer to array elements even if the VM does not support pinning.

GetPrimitiveArrayCritical
ReleasePrimitiveArrayCritical

void * GetPrimitiveArrayCritical(JNIEnv *env, jarray array, jboolean *isCopy);
void ReleasePrimitiveArrayCritical(JNIEnv *env, jarray array, void *carray, jint mode);

The semantics of these two functions are very similar to the existing Get/ReleaseArrayElements functions. If possible, the VM returns a pointer to the primitive array; otherwise, a copy is made. However, there are significant restrictions on how these functions can be used.

After calling GetPrimitiveArrayCritical, the native code should not run for an extended period of time before it calls ReleasePrimitiveArrayCritical. We must treat the code inside this pair of functions as running in a "critical region." Inside a critical region, native code must not call other JNI functions, or any system call that may cause the current thread to block and wait for another Java thread. (For example, the current thread must not call read on a stream being written by another Java thread.)

These restrictions make it more likely that the native code will obtain an uncopied version of the array, even if the VM does not support pinning. For example, a VM may temporarily disable garbage collection when the native code is holding a pointer to an array obtained via GetPrimitiveArrayCritical.

Multiple pairs of GetPrimtiveArrayCritical and ReleasePrimitiveArrayCritical may be nested. For example:

  jint len = (*env)->GetArrayLength(env, arr1);
  jbyte *a1 = (*env)->GetPrimitiveArrayCritical(env, arr1, 0);
  jbyte *a2 = (*env)->GetPrimitiveArrayCritical(env, arr2, 0);
  /* We need to check in case the VM tried to make a copy. */
  if (a1 == NULL || a2 == NULL) {
    ... /* out of memory exception thrown */
  }
  memcpy(a1, a2, len);
  (*env)->ReleasePrimitiveArrayCritical(env, arr2, a2, 0);
  (*env)->ReleasePrimitiveArrayCritical(env, arr1, a1, 0);

Note that GetPrimitiveArrayCritical might still make a copy of the array if the VM internally represents arrays in a different format. Therefore we need to check its return value against NULL for possible out of memory situations.

LINKAGE (GetPrimitiveArrayCritical):

Linkage Index 222 in the JNIEnv interface function table.

LINKAGE (ReleasePrimitiveArrayCritical):

Linkage Index 223 in the JNIEnv interface function table.

SINCE:

SDK/JRE 1.2

Registering Native Methods

RegisterNatives

jint RegisterNatives(JNIEnv *env, jclass clazz,
const JNINativeMethod *methods, jint nMethods);

Registers native methods with the class specified by the clazz argument. The methods parameter specifies an array of JNINativeMethod structures that contain the names, signatures, and function pointers of the native methods. The nMethods parameter specifies the number of native methods in the array. The JNINativeMethod structure is defined as follows:

typedef struct {

    char *name;

    char *signature;

    void *fnPtr;

} JNINativeMethod;

The function pointers nominally must have the following signature:

ReturnType (*fnPtr)(JNIEnv *env, jobject objectOrClass, ...);

LINKAGE:

Index 215 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

methods: the native methods in the class.

nMethods: the number of native methods in the class.

RETURNS:

Returns “0” on success; returns a negative value on failure.

THROWS:

NoSuchMethodError: if a specified method cannot be found or if the method is not native.

UnregisterNatives

jint UnregisterNatives(JNIEnv *env, jclass clazz);

Unregisters native methods of a class. The class goes back to the state before it was linked or registered with its native method functions.

This function should not be used in normal native code. Instead, it provides special programs a way to reload and relink native libraries.

LINKAGE:
Index 216 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

clazz: a Java class object.

RETURNS:

Returns “0” on success; returns a negative value on failure.

Monitor Operations

MonitorEnter

jint MonitorEnter(JNIEnv *env, jobject obj);

Enters the monitor associated with the underlying Java object referred to by obj.

Each Java object has a monitor associated with it. If the current thread already owns the monitor associated with obj, it increments a counter in the monitor indicating the number of times this thread has entered the monitor. If the monitor associated with obj is not owned by any thread, the current thread becomes the owner of the monitor, setting the entry count of this monitor to 1. If another thread already owns the monitor associated with obj, the current thread waits until the monitor is released, then tries again to gain ownership.

LINKAGE:
Index 217 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

obj: a normal Java object or class object.

RETURNS:

Returns “0” on success; returns a negative value on failure.

MonitorExit

jint MonitorExit(JNIEnv *env, jobject obj);

The current thread must be the owner of the monitor associated with the underlying Java object referred to by obj. The thread decrements the counter indicating the number of times it has entered this monitor. If the value of the counter becomes zero, the current thread releases the monitor.

LINKAGE:
Index 218 in the JNIEnv interface function table.
PARAMETERS:

env: the JNI interface pointer.

obj: a normal Java object or class object.

RETURNS:

Returns “0” on success; returns a negative value on failure.

NIO Support

The NIO-related entry points allow native code to access java.nio direct buffers. The contents of a direct buffer can, potentially, reside in native memory outside of the ordinary garbage-collected heap. For information about direct buffers, please see New I/O APIs and the specification of the java.nio.ByteBuffer class.

Three new functions introduced in SDK/JRE 1.4 allow JNI code to create, examine, and manipulate direct buffers:
  • NewDirectByteBuffer
  • GetDirectBufferAddress
  • GetDirectBufferCapacity

Every implementation of the Java virtual machine must support these functions, but not every implementation is required to support JNI access to direct buffers. If a JVM does not support such access then the NewDirectByteBuffer and GetDirectBufferAddress functions must always return NULL, and the GetDirectBufferCapacity function must always return -1. If a JVM does support such access then these three functions must be implemented to return the appropriate values.

NewDirectByteBuffer

jobject NewDirectByteBuffer(JNIEnv* env, void* address, jlong capacity);

Allocates and returns a direct java.nio.ByteBuffer referring to the block of memory starting at the memory address address and extending capacity bytes.

Native code that calls this function and returns the resulting byte-buffer object to Java-level code should ensure that the buffer refers to a valid region of memory that is accessible for reading and, if appropriate, writing. An attempt to access an invalid memory location from Java code will either return an arbitrary value, have no visible effect, or cause an unspecified exception to be thrown.

LINKAGE:

Index 229 in the JNIEnv interface function table.

PARAMETERS:

env: the JNIEnv interface pointer

address: the starting address of the memory region (must not be NULL)

capacity: the size in bytes of the memory region (must be positive)

RETURNS:

Returns a local reference to the newly-instantiated java.nio.ByteBuffer object. Returns NULL if an exception occurs, or if JNI access to direct buffers is not supported by this virtual machine.

EXCEPTIONS:

OutOfMemoryError: if allocation of the ByteBuffer object fails

SINCE:

SDK/JRE 1.4

GetDirectBufferAddress

void* GetDirectBufferAddress(JNIEnv* env, jobject buf);

Fetches and returns the starting address of the memory region referenced by the given direct java.nio.Buffer.

This function allows native code to access the same memory region that is accessible to Java code via the buffer object.

LINKAGE:

Index 230 in the JNIEnv interface function table.

PARAMETERS:

env: the JNIEnv interface pointer

buf: a direct java.nio.Buffer object (must not be NULL)

RETURNS:

Returns the starting address of the memory region referenced by the buffer. Returns NULL if the memory region is undefined, if the given object is not a direct java.nio.Buffer, or if JNI access to direct buffers is not supported by this virtual machine.

SINCE:

SDK/JRE 1.4

GetDirectBufferCapacity

jlong GetDirectBufferCapacity(JNIEnv* env, jobject buf);

Fetches and returns the capacity in bytes of the memory region referenced by the given direct java.nio.Buffer.

LINKAGE:

Index 231 in the JNIEnv interface function table.

PARAMETERS:

env: the JNIEnv interface pointer

buf: a direct java.nio.Buffer object (must not be NULL)

RETURNS:

Returns the capacity in bytes of the memory region associated with the buffer. Returns -1 if the given object is not a direct java.nio.Buffer, or if JNI access to direct buffers is not supported by this virtual machine.

SINCE:

SDK/JRE 1.4

Reflection Support

Programmers can use the JNI to call Java methods or access Java fields if they know the name and type of the methods or fields. The Java Core Reflection API allows programmers to introspect Java classes at runtime. JNI provides a set of conversion functions between field and method IDs used in the JNI to field and method objects used in the Java Core Reflection API.

FromReflectedMethod

jmethodID FromReflectedMethod(JNIEnv *env, jobject method);

Converts a java.lang.reflect.Method or java.lang.reflect.Constructor object to a method ID.

LINKAGE:

Index 7 in the JNIEnv interface function table.

SINCE:

SDK/JRE 1.2

FromReflectedField

jfieldID FromReflectedField(JNIEnv *env, jobject field);

Converts a java.lang.reflect.Field to a field ID.

LINKAGE:
Index 8 in the JNIEnv interface function table.
SINCE:

SDK/JRE 1.2

ToReflectedMethod

jobject ToReflectedMethod(JNIEnv *env, jclass cls,
   jmethodID methodID);

Converts a method ID derived from cls to a java.lang.reflect.Method or java.lang.reflect.Constructor object.

Throws OutOfMemoryError and returns 0 if fails.

LINKAGE:

Index 9 in the JNIEnv interface function table.

SINCE:

SDK/JRE 1.2

ToReflectedField

jobject ToReflectedField(JNIEnv *env, jclass cls,
   jfieldID fieldID);

Converts a field ID derived from cls to a java.lang.reflect.Field object.

Throws OutOfMemoryError and returns 0 if fails.

LINKAGE:

Index 12 in the JNIEnv interface function table.

SINCE:

SDK/JRE 1.2

Java VM Interface

GetJavaVM

jint GetJavaVM(JNIEnv *env, JavaVM **vm);

Returns the Java VM interface (used in the Invocation API) associated with the current thread. The result is placed at the location pointed to by the second argument, vm.

LINKAGE:

Index 219 in the JNIEnv interface function table.

PARAMETERS:

env: the JNI interface pointer.

vm: a pointer to where the result should be placed.

RETURNS:

Returns “0” on success; returns a negative value on failure.

Contents | Previous | Next

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


JNI Types and Data Structures

Chapter 3

This chapter discusses how the JNI maps Java types to native C types.

Primitive Types

Table 3-1 describes Java primitive types and their machine-dependent native equivalents.

Table 3-1 Primitive Types and Native Equivalents
Java Type | Native Type | Description
boolean | jboolean | unsigned 8 bits
byte | jbyte | signed 8 bits
char | jchar | unsigned 16 bits
short | jshort | signed 16 bits
int | jint | signed 32 bits
long | jlong | signed 64 bits
float | jfloat | 32 bits
double | jdouble | 64 bits
void | void | N/A

The following definition is provided for convenience.

#define JNI_FALSE  0
#define JNI_TRUE   1

The jsize integer type is used to describe cardinal indices and sizes:

typedef jint jsize;

Reference Types

The JNI includes a number of reference types that correspond to different kinds of Java objects. JNI reference types are organized in the hierarchy shown in Figure 3-1.

The top of the heirarchy is jobject. Subclasses of jobject are jclass, jstring, jarray and jthrowable. Subclasses of jarray are jobjectArray, jbooleanArray, jbyteArray, jcharArray, jshortArray, jintArray, jlongArray, jfloatArray, jdoubleArray.

Figure 3-1 Reference Type Hierarchy

In C, all other JNI reference types are defined to be the same as jobject. For example:

typedef jobject jclass;

In C++, JNI introduces a set of dummy classes to enforce the subtyping relationship. For example:

class _jobject {};
class _jclass : public _jobject {};
...
typedef _jobject *jobject;
typedef _jclass *jclass;

Field and Method IDs

Method and field IDs are regular C pointer types:

struct _jfieldID;              /* opaque structure */
typedef struct _jfieldID *jfieldID;   /* field IDs */

struct _jmethodID;              /* opaque structure */
typedef struct _jmethodID *jmethodID; /* method IDs */

The Value Type

The jvalue union type is used as the element type in argument arrays. It is declared as follows:

typedef union jvalue {
    jboolean z;
    jbyte    b;
    jchar    c;
    jshort   s;
    jint     i;
    jlong    j;
    jfloat   f;
    jdouble  d;
    jobject  l;
} jvalue;

Type Signatures

The JNI uses the Java VM’s representation of type signatures. Table 3-2 shows these type signatures.

Table 3-2 Java VM Type Signatures
Type Signature | Java Type
Z | boolean
B | byte
C | char
S | short
I | int
J | long
F | float
D | double
L fully-qualified-class ; | fully-qualified-class
[ type | type[]
( arg-types ) ret-type | method type

For example, the Java method:

long f (int n, String s, int[] arr);

has the following type signature:

(ILjava/lang/String;[I)J

UTF-8 Strings

The JNI uses UTF-8 strings to represent various string types. UTF-8 strings are the same as those used by the Java VM. UTF-8 strings are encoded so that character sequences that contain only nonnull ASCII characters can be represented using only one byte per character, but characters of up to 16 bits can be represented. All characters in the range \u0001 to \u007F are represented by a single byte, as follows:

Byte consisting of 0 in the first position followed by bits 0 through 6 of the bits representing the value of the character.

The seven bits of data in the byte give the value of the character that is represented. The null character (\u000) and characters in the range \u0080 to \u07FF are represented by a pair of bytes, x and y, as follows:

The x byte with 110 in the first 3 positions followed by bits 6 through 10 of the bits representing the value of the character. The y byte with 10 in the first 2 positions followed by bits 0 through 5 representing the value of the character.

The bytes represent the character with the value ((x&0x1f)<<6)+(y&0x3f).

Characters in the range \u0800 to \uFFFF are represented by three bytes, x, y, and z:

The x byte with 1110 followed by bits 12 through 15 of the bits representing the character. The y byte with 10 followed by bits 6 through 11. The z byte with 10 followed by bits 0 through 5.

The character with the value ((x&0xf)<<12)+(y&0x3f)<<6)+(z&0x3f) is represented by the three bytes.

There are two differences between this format and the “standard” UTF-8 format. First, the null byte (byte)0 is encoded using the two-byte format rather than the one-byte format. This means that Java VM UTF-8 strings never have embedded nulls. Second, only the one-byte, two-byte, and three-byte formats are used. The Java VM does not recognize the longer UTF-8 formats.

Contents | Previous | Next

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


The Invocation API

Chapter 5

The Invocation API allows software vendors to load the Java VM into an arbitrary native application. Vendors can deliver Java-enabled applications without having to link with the Java VM source code.

This chapter begins with an overview of the Invocation API. This is followed by reference pages for all Invocation API functions.

To enhance the embeddability of the Java VM, the Invocation API is extended in JDK 1.1.2 in a few minor ways.

Overview

The following code example illustrates how to use functions in the Invocation API. In this example, the C++ code creates a Java VM and invokes a static method, called Main.test. For clarity, we omit error checking.

    #include <jni.h>       /* where everything is defined */
    ...
    JavaVM *jvm;       /* denotes a Java VM */
    JNIEnv *env;       /* pointer to native method interface */
    JDK1_1InitArgs vm_args; /* JDK 1.1 VM initialization arguments */
    vm_args.version = 0x00010001; /* New in 1.1.2: VM version */
    /* Get the default initialization arguments and set the class
     * path */
    JNI_GetDefaultJavaVMInitArgs(&vm_args);
    vm_args.classpath = ...;
    /* load and initialize a Java VM, return a JNI interface
     * pointer in env */
    JNI_CreateJavaVM(&jvm, &env, &vm_args);
    /* invoke the Main.test method using the JNI */
    jclass cls = env->FindClass("Main");
    jmethodID mid = env->GetStaticMethodID(cls, "test", "(I)V");
    env->CallStaticVoidMethod(cls, mid, 100);
    /* We are done. */
    jvm->DestroyJavaVM();

This example uses three functions in the API. The Invocation API allows a native application to use the JNI interface pointer to access VM features. The design is similar to Netscape’s JRI Embedding Interface.

Creating the VM

The JNI_CreateJavaVM() function loads and initializes a Java VM and returns a pointer to the JNI interface pointer. The thread that called JNI_CreateJavaVM() is considered to be the main thread.

Attaching to the VM

The JNI interface pointer (JNIEnv) is valid only in the current thread. Should another thread need to access the Java VM, it must first call AttachCurrentThread() to attach itself to the VM and obtain a JNI interface pointer. Once attached to the VM, a native thread works just like an ordinary Java thread running inside a native method. The native thread remains attached to the VM until it calls DetachCurrentThread() to detach itself.

The attached thread should have enough stack space to perform a reaonable amount of work. The allocation of stack space per thread is operating system-specific. For example, using pthreads, the stack size can be specified in the pthread_attr_t argument to pthread_create.

Unloading the VM

The main thread cannot detach itself from the VM. Instead, it must call DestroyJavaVM() to unload the entire VM.

The VM waits until the main thread is the only user thread before it actually unloads. User threads include both Java threads and attached native threads. This restriction exists because a Java thread or attached native thread may be holding system resources, such as locks, windows, and so on. The VM cannot automatically free these resources. By restricting the main thread to be the only running thread when the VM is unloaded, the burden of releasing system resources held by arbitrary threads is on the programmer.

Initialization Structures

Different Java VM implementation will likely require different initialization arguments. It is difficult to come up with a standard initialization structure suitable for all present and future Java VMs. As a compromise, we reserve the first field (version) to identify the content of the initialization structure. Native applications embedding JDK 1.1.2 must set the version field to 0x00010001. VM implementations are encouraged to use the same initialization structure as JDK, although other implementations may choose to ignore some of the initialization arguments supported by JDK.

Version numbers 0x80000000 to 0xFFFFFFFF are reserved, and should not be recognized by any VM implementation.

The following code shows the structure used to initialize the Java VM in JDK 1.1.2.

typedef struct JDK1_1InitArgs {
   /* The first two fields were reserved in JDK 1.1, and
      formally introduced in JDK 1.1.2. */
   /* Java VM version */
    jint version;
   /* System properties. */
    char **properties;
   /* whether to check the Java source files are newer than
    * compiled class files. */
    jint checkSource;
   /* maximum native stack size of Java-created threads. */
    jint nativeStackSize;
   /* maximum Java stack size. */
    jint javaStackSize;
   /* initial heap size. */
    jint minHeapSize;
   /* maximum heap size. */
    jint maxHeapSize;
   /* controls whether Java byte code should be verified:
    * 0 -- none, 1 -- remotely loaded code, 2 -- all code. */
    jint verifyMode;
   /* the local directory path for class loading. */
    const char *classpath;
   /* a hook for a function that redirects all VM messages. */
    jint (*vfprintf)(FILE *fp, const char *format,
                     va_list args);
   /* a VM exit hook. */
    void (*exit)(jint code);
   /* a VM abort hook. */
    void (*abort)();
   /* whether to enable class GC. */
    jint enableClassGC;
   /* whether GC messages will appear. */
    jint enableVerboseGC;
   /* whether asynchronous GC is allowed. */
    jint disableAsyncGC;
   /* Three reserved fields. */
    jint reserved0;
    jint reserved1;
    jint reserved2;
} JDK1_1InitArgs;

In JDK 1.1.2, the initialization structure provides hooks so that a native application can redirect VM messages and obtain control when the VM terminates.

The structure below is passed as an argument when a native thread attaches to a Java VM in JDK 1.1.2. In actuality, no arguments are required for a native thread to attach to the JDK 1.1.2. The JDK1_1AttachArgs structure consists only of a padding slot for those C compilers that do not permit empty structures.

typedef struct JDK1_1AttachArgs {
   /*
    * JDK 1.1 does not need any arguments to attach a
    * native thread. The padding is here to satisfy the C
    * compiler which does not permit empty structures.
    */
    void *__padding;
} JDK1_1AttachArgs;

Library and Version Management

In JDK 1.1, once a native library is loaded, it is visible from all class loaders. Therefore two classes in different class loaders may link with the same native method. This leads to two problems:
  • A class may mistakenly link with native libraries loaded by a class with the same name in a different class loader.
  • Native methods can easily mix classes from different class loaders. This breaks the name space separation offered by class loaders, and leads to type safety problems.

In the Java 2 SDK, each class loader manages its own set of native libraries. The same JNI native library cannot be loaded into more than one class loader. Doing so causes UnsatisfiedLinkError to be thrown. For example, System.loadLibrary throws an UnsatisfiedLinkError when used to load a native library into two class loaders. The benefits of the new approach are:

  • Name space separation based on class loaders is preserved in native libraries. A native library cannot easily mix classes from different class loaders.
  • In addition, native libraries can be unloaded when their corresponding class loaders are garbage collected.

To facilitate versioning control and resource management, JNI libraries in the Java 2 Platform may optionally export the following two functions:

JNI_OnLoad

jint JNI_OnLoad(JavaVM *vm, void *reserved);

The VM calls JNI_OnLoad when the native library is loaded (for example, through System.loadLibrary). JNI_OnLoad must return the JNI version needed by the native library.

In order to use any of the new JNI functions, a native library must export a JNI_OnLoad function that returns JNI_VERSION_1_2. If the native library does not export a JNI_OnLoad function, the VM assumes that the library only requires JNI version JNI_VERSION_1_1. If the VM does not recognize the version number returned by JNI_OnLoad, the native library cannot be loaded.

LINKAGE:

Exported from native libraries that contain native method implementation.

SINCE SDK/JRE 1.4:

In order to use the JNI functions introduced in J2SE release 1.2, in addition to those that were available in JDK 1.1, a native library must export a JNI_OnLoad function that returns JNI_VERSION_1_2.

In order to use the JNI functions introduced in J2SE release 1.4, in addition to those that were available in release 1.2, a native library must export a JNI_OnLoad function that returns JNI_VERSION_1_4.

If the native library does not export a JNI_OnLoad function, the VM assumes that the library only requires JNI version JNI_VERSION_1_1. If the VM does not recognize the version number returned by JNI_OnLoad, the native library cannot be loaded.

JNI_OnUnload

void JNI_OnUnload(JavaVM *vm, void *reserved);

The VM calls JNI_OnUnload when the class loader containing the native library is garbage collected. This function can be used to perform cleanup operations. Because this function is called in an unknown context (such as from a finalizer), the programmer should be conservative on using Java VM services, and refrain from arbitrary Java call-backs.

Note that JNI_OnLoad and JNI_OnUnload are two functions optionally supplied by JNI libraries, not exported from the VM.

LINKAGE:
Exported from native libraries that contain native method implementation.

Invocation API Functions

The JavaVM type is a pointer to the Invocation API function table. The following code example shows this function table.

typedef const struct JNIInvokeInterface *JavaVM;

const struct JNIInvokeInterface ... = {
    NULL,
    NULL,
    NULL,

    DestroyJavaVM,
    AttachCurrentThread,
    DetachCurrentThread,

    GetEnv,

    AttachCurrentThreadAsDaemon
};

Note that three Invocation API functions, JNI_GetDefaultJavaVMInitArgs(), JNI_GetCreatedJavaVMs(), and JNI_CreateJavaVM(), are not part of the JavaVM function table. These functions can be used without a preexisting JavaVM structure.

JNI_GetDefaultJavaVMInitArgs

jint JNI_GetDefaultJavaVMInitArgs(void *vm_args);

Returns a default configuration for the Java VM. Before calling this function, native code must1 set the vm_args->version field to the JNI version it expects the VM to support. In JDK 1.1.2, vm_args->version must be set to 0x00010001. After this function returns, vm_args->version will be set to the actual JNI version the VM supports.

LINKAGE:

Exported from the native library that implements the Java virtual machine.

PARAMETERS:

vm_args: a pointer to a VM-specific initialization structure in to which the default arguments are filled.

RETURNS:

Returns “0” if the requested version is supported; returns a negative number if the requested version is not supported.

JNI_GetCreatedJavaVMs

jint JNI_GetCreatedJavaVMs(JavaVM **vmBuf, jsize bufLen,
jsize *nVMs);

Returns all Java VMs that have been created. Pointers to VMs are written in the buffer vmBuf in the order they are created. At most bufLen number of entries will be written. The total number of created VMs is returned in *nVMs.

JDK 1.1.2 does not support creating more than one VM in a single process.

LINKAGE:

Exported from the native library that implements the Java virtual machine.

PARAMETERS:

vmBuf: pointer to the buffer where the VM structures will be placed.

bufLen: the length of the buffer.

nVMs: a pointer to an integer.

RETURNS:

Returns “0” on success; returns a negative number on failure.

JNI_CreateJavaVM

jint JNI_CreateJavaVM(JavaVM **p_vm, JNIEnv **p_env, void *vm_args);

Loads and initializes a Java VM. The current thread becomes the main thread. Sets the env argument to the JNI interface pointer of the main thread.

JDK 1.1 does not support creating more than one VM in a single process. The version field in vm_args must2 be set to 0x00010001.

In JDK 1.1, the second argument to JNI_CreateJavaVM is always a pointer to JNIEnv *. The third argument is a pointer to a JDK 1.1 specific structure (JDK1_1InitArgs). The JDK1_1InitArgs structure is clearly not designed to be portable on all VMs.

In the Java 2 SDK, we introduce a standard VM initialization structure. Backward compatibility is preserved. If the VM initialization argument points to a JDK1_1InitArgs structure, JNI_CreateJavaVM still returns the 1.1 version of JNI interface pointer. The VM returns the 1.2 version of JNI interface pointer if the third argument points to a JavaVMInitArgs structure. Unlike JDK1_1InitArgs, which contains a fixed set of options, JavaVMInitArgs uses option strings to encode arbitrary VM start up options.

typedef struct JavaVMInitArgs {
    jint version;

    jint nOptions;
    JavaVMOption *options;
    jboolean ignoreUnrecognized;
} JavaVMInitArgs;

The version field must be set to JNI_VERSION_1_2. (In contrast, the version field in JDK1_1InitArgs must be set to JNI_VERSION_1_1.) The options field is an array of the following type:

typedef struct JavaVMOption {
    char *optionString;
    void *extraInfo;
} JavaVMOption;

The size of the array is denoted by the nOptions field in JavaVMInitArgs. If ignoreUnrecognized is JNI_TRUE, JNI_CreateJavaVM ignore all unrecognized option strings that begin with "-X" or "_". If ignoreUnrecognized is JNI_FALSE, JNI_CreateJavaVM returns JNI_ERR as soon as it encounters any unrecognized option strings. All Java VMs must recognize the following set of standard options:

optionString | meaning
-D<name>=<value> | Set a system property
-verbose[:class|gc|jni] | Enable verbose output. The options can be followed by a comma-separated list of names indicating what kind of messages will be printed by the VM. For example, "-verbose:gc,class" instructs the VM to print GC and class loading related messages. Standard names include: gc, class, and jni. All nonstandard (VM-specific) names must begin with "X".
vfprintf | extraInfo is a pointer to the vfprintf hook.
exit | extraInfo is a pointer to the exit hook.
abort | extraInfo is a pointer to the abort hook.

In addition, each VM implementation may support its own set of non-standard option strings. Non-standard option names must begin with "-X" or an underscore ("_"). For example, the Java 2 SDK supports -Xms and -Xmx options to allow programmers specify the initial and maximum heap size. Options that begin with "-X" are accessible from the "java" command line.

Here is the example code that creates a Java VM in the Java 2 SDK:

JavaVMInitArgs vm_args;
JavaVMOption options[4];

options[0].optionString = "-Djava.compiler=NONE";           /* disable JIT */
options[1].optionString = "-Djava.class.path=c:\myclasses"; /* user classes */
options[2].optionString = "-Djava.library.path=c:\mylibs";  /* set native library path */
options[3].optionString = "-verbose:jni";                   /* print JNI-related messages */

vm_args.version = JNI_VERSION_1_2;
vm_args.options = options;
vm_args.nOptions = 4;
vm_args.ignoreUnrecognized = TRUE;

/* Note that in the Java 2 SDK, there is no longer any need to call
 * JNI_GetDefaultJavaVMInitArgs.
 */
res = JNI_CreateJavaVM(&vm, (void **)&env, &vm_args);
if (res < 0) ...

The Java 2 SDK still supports JDK1_1InitArgs in exactly the same way as JDK 1.1.

LINKAGE:

Exported from the native library that implements the Java virtual machine.

PARAMETERS:

p_vm: pointer to the location where the resulting VM structure will be placed.

p_env: pointer to the location where the JNI interface pointer for the main thread will be placed.

vm_args: Java VM initialization arguments.

RETURNS:

Returns “0” on success; returns a negative number on failure.

DestroyJavaVM

jint DestroyJavaVM(JavaVM *vm);

Unloads a Java VM and reclaims its resources. Only the main thread can unload the VM. The system waits until the main thread is only remaining user thread before it destroys the VM.

The support for DestroyJavaVM was not complete in 1.1. Only the main thread may call DestroyJavaVM. In the Java 2 SDK, any thread, whether attached or not, can call this function. If the current thread is attached, the VM waits until the current thread is the only user-level Java thread. If the current thread is not attached, the VM attaches the current thread and then waits until the current thread is the only user-level thread. The Java 2 SDK still does not support VM unloading, however. DestroyJavaVM always returns an error code.

LINKAGE:

Index 3 in the JavaVM interface function table.

PARAMETERS:

vm: the Java VM that will be destroyed.

RETURNS:

Returns “0” on success; returns a negative number on failure.

JDK 1.1.2 does not support unloading the VM.

AttachCurrentThread

jint AttachCurrentThread(JavaVM *vm, JNIEnv **p_env, void *thr_args);

Attaches the current thread to a Java VM. Returns a JNI interface pointer in the JNIEnv argument.

Trying to attach a thread that is already attached is a no-op.

A native thread cannot be attached simultaneously to two Java VMs.

When a thread is attached to the VM, the context class loader is the bootstrap loader.

LINKAGE:

Index 4 in the JavaVM interface function table.

PARAMETERS:

vm: the VM to which the current thread will be attached.

p_env: pointer to the location where the JNI interface pointer of the current thread will be placed.

thr_args: VM-specific thread attachment arguments.

In JDK 1.1, the second argument to AttachCurrentThread is always a pointer to JNIEnv. The third argument to AttachCurrentThread was reserved, and should be set to NULL.

In the Java 2 SDK, you pass NULL as the third argument for 1.1 behavior, or pass a pointer to the following structure to specify additional information:

typedef struct JavaVMAttachArgs {
    jint version;  /* must be JNI_VERSION_1_2 */
    char *name;    /* the name of the thread, or NULL */
    jobject group; /* global ref of a ThreadGroup object, or NULL */
} JavaVMAttachArgs
RETURNS:

Returns “0” on success; returns a negative number on failure.

AttachCurrentThreadAsDaemon

jint AttachCurrentThreadAsDaemon(JavaVM* vm, void** penv, void* args);

Same semantics as AttachCurrentThread, but the newly-created java.lang.Thread instance is a daemon.

If the thread has already been attached via either AttachCurrentThread or AttachCurrentThreadAsDaemon, this routine simply sets the value pointed to by penv to the JNIEnv of the current thread. In this case neither AttachCurrentThread nor this routine have any effect on the daemon status of the thread.

LINKAGE:

Index 7 in the JavaVM interface function table.

PARAMETERS:

vm: the virtual machine instance to which the current thread will be attached.

penv: a pointer to the location in which the JNIEnv interface pointer for the current thread will be placed.

args: a pointer to a JavaVMAttachArgs structure.

RETURNS

Returns zero on success; otherwise, returns a negative number.

EXCEPTIONS

None.

SINCE:

SDK/JRE 1.4

DetachCurrentThread

jint DetachCurrentThread(JavaVM *vm);

Detaches the current thread from a Java VM. All Java monitors held by this thread are released. All Java threads waiting for this thread to die are notified.

In JDK 1.1, the main thread cannot be detached from the VM. It must call DestroyJavaVM to unload the entire VM.

In the Java 2 SDK, the main thread can be detached from the VM.

The main thread, which is the thread that created the Java VM, cannot be detached from the VM. Instead, the main thread must call JNI_DestroyJavaVM() to unload the entire VM.

LINKAGE:

Index 5 in the JavaVM interface function table.

PARAMETERS:

vm: the VM from which the current thread will be detached.

RETURNS:

Returns “0” on success; returns a negative number on failure.

GetEnv

jint GetEnv(JavaVM *vm, void **env, jint version);

LINKAGE:

Index 6 in the JavaVM interface function table.

RETURNS:

If the current thread is not attached to the VM, sets *env to NULL, and returns JNI_EDETACHED. If the specified version is not supported, sets *env to NULL, and returns JNI_EVERSION. Otherwise, sets *env to the appropriate interface, and returns JNI_OK.

PARAMETERS:

vm: The virtual machine instance from which the interface will be retrieved.
env: pointer to the location where the JNI interface pointer for the current thread will be placed.
version: The requested JNI version.

_________________________

1. JDK 1.1 did not require the native code to set the version field. For backward compatibility, JDK 1.1.2 assumes that the requested version is 0x00010001 if the version field is not set. Future versions of JDK will require the version field to be set to an appropriate value.

2. See footnote 1.

Contents | Previous

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.


Java

JavaTM Debug Wire Protocol Transport Interface (jdwpTransport)

Documentation Contents

A transport is implemented as a series of functions in a dynamic library (sometimes called a DLL, or shared library). The library exports an onload function that is invoked by the JDWP (or other) agent at startup-time.

Like JVMTI, jdwpTransport functions are accessed through an interface pointer called the environment pointer. An environment pointer is a pointer to an environment and has type jdwpTransportEnv*. The environment pointer is returned to the JDWP (or other) agent from the onload function.

A transport may support a single environment or it may support multiple environments. In other words, a transport may be used by only one, or multiple agents at the same time. If a transport supports multiple environments then each call to the onload function will return a new environment pointer. If a transport only supports a single environment then second, and subsequent calls to the onload function will return an error.

A transport is thread-safe and jdwpTransport functions can be used by multiple concurrent threads. For example, one thread may be blocked in the jdwpTransport ReadPacket function waiting for a packet while another thread invokes WritePacket function to write a packet.

In most cases jdwpTransport functions return a jdwpTransportError value indicating return status. Some functions return additional values through pointers provided by the calling function. In cases where the return values are allocated by a jdwpTransport function then the function will use the memory allocation routine specified by the agent. The memory allocation routines are specified to the transport, at start-up, via the onload function.

In the event of an error (that is, one of the jdwpTransport functions returns a value other than JDWPTRANSPORT_ERROR_NONE) then a string representing the error can be subsequently obtained through a call to the jdwpTransport function GetLastError. Errors are recorded on a per-thread basis. The GetLastError function will return a string represetning the last error that was encountered by the current thread only.

Developing a Transport implementation

A transport library can be developed in any native language that supports C language calling conventions and C or C++ definitions.

The function, data type, and constant definitions needed for using the jdwpTransport interface are defined in the include file jdwpTransport.h. To use these definitions add the Java SE include directory to your include path :-

#include "jdwpTransport.h"

Transport Start-Up

The transport library must export an onload function with the following prototype :-

JNIEXPORT jint JNICALL
jdwpTransport_OnLoad(JavaVM *jvm,
                     jdwpTransportCallback *callback,
                     jint version,
                     jdwpTransportEnv** env);

This function will be called by the JDWP (or other agent) when the library is loaded.

The jvm argument is the JNI invocation interface obtained by agent by invoking JNI's GetJavaVM function.

The callback argument is a pointer to a function table of memory management routines that the transport must use to allocate the memory for return values that are allocated by the transport implementation :-

typedef struct jdwpTransportCallback {
    void* (*alloc)(jint numBytes);
    void (*free)(void *buffer);
} jdwpTransportCallback;

The lifespan of the callback argument is the onload function and therefore the transport must take a copy of the function table in the jdwpTransport_OnLoad function.

The function table has two entries. The alloc function allocates an area of memory. It has a single argument to specify the number of bytes to allocate. It returns a pointer to the begining of the allocated memory, or NULL if the memory request cannot be honored. If the number of bytes requested is zero then NULL is returned. The free function deallocates an area of memory that was previously allocated using the alloc function.

The memory management functions provided by the agent are thread safe and the transport implementation is not required to synchronize calls to the these functions. The implementation of the memory management functions are guaranteed not to call any jdwpTransport function.

version is the version of the transport interface that the agent expects. This must be specified as JDWPTRANSPORT_VERSION_1_0.

env is a pointer to the environment pointer returned by the function.

The jdwpTransport_OnLoad function returns JNI_OK if the transport initializes successfully. If initialization fails then one of the following errors is returned :-

JNI_ENOMEM
JNI_EVERSION
JNI_EEXIST

JNI_ENOMEM is returned if there is insufficient memory to complete initialization.

JNI_EVERSION is returned if the version in the version argument is not JDWPTRANSPORT_VERSION_1_0.

JNI_EEXIST is returned if the transport only supports a single environment, and the environment pointer was previously returned by the first call to the onload function.

Functions

The jdwpTransport functions fall into these categories:

  • Connection Management
    • Attach
    • StartListening
    • StopListening
    • Accept
    • IsOpen
    • Close
  • I/O Functions
    • ReadPacket
    • WritePacket
  • Miscellaneous Functions
    • GetLastError
    • Get Capabilities

Connection Management

The connection management functions are used to establish and close the connection to the debugger. A connection provides a reliable flow of JDWP packets to and from the debugger. Packets written to a connection are read, by the debugger, in exactly the order in which they were written. Similarly, any packets written to the connection by the debugger are read in the order in which they were written.

Connections are established either actively or passively. Establishing the connection actively means that the jdwpTransport's Attach function is called to initiate the connection the debugger. Establishing the connection passively means that the jdwpTransport's StartListening function is used to put the transport into listen mode so that it listens for a connection from a debugger. Once in listen mode the Accept function is used to accept the connection. Irrespective of how the connection is established the Close function is used to close the connection, and IsOpen is used to test if a connection is open to the debugger.

Attach

jdwpTransportError
Attach(jdwpTransportEnv* env, const char* address,
       jlong attachTimeout, jlong handshakeTimeout)

Attaches to the debugger. Attaching to the debugger involves two steps. First, a connection is established to the specified address. Once a connection is established a handshake is performed to ensure that the connection is indeed established to a debugger. Handshaking involves the exchange of ASCII string JDWP-Handshake as specified in the Java Debug Wire Protocol specification.

The address argument is a pointer to a string representing the address of the debugger. The exact format is specific to the transport (In the case of a TCP/IP based transport the address may include the hostname and port number of the debugger. In the case of a transport that supports connections through a serial port it might be the device name of the serial port).

The attachTimeout argument specifies a timeout to use when attaching. If the transport supports an attach timeout (see GetCapabilities) and if the attachTimeout is positive then it specifies the timeout, in milliseconds (more or less), to use when attaching to the debugger. If the transport does not support an attach timeout, or if attachTimeout is specified as zero then a timeout is not used when attaching.

The handshakeTimeout argument specifies a timeout to use when handshaking with the debugger. If the transport supports a handshake timeout (see GetCapabilities) and if the handshakeTimeout is positive then it specifies the timeout, in milliseconds (more or less), to use when handshaking with the debugger. The exact usage of the handshake timeout is specific to the transport - for example one implementation may use the timeout as an inter-character timeout while waiting for the JDWP-Handshake message from the debugger. Another implementation may use the timeout to indicate the total duration allowed for the handshake exchange. In general the purpose of the handshake timeout is to allow for error handling in the event that the transport connects to something other than a valid debugger. If the transport does not support a handshake timeout, or if the handshakeTimeout is specified as zero then a timeout is not used when handshaking.

This function returns a universal error or one of the following errors:

JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT
JDWPTRANSPORT_ERROR_ILLEGAL_STATE
JDWPTRANSPORT_ERROR_IO_ERROR
JDWPTRANSPORT_ERROR_TIMEOUT

JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT is returned if address is invalid or timeout is negative.

JDWPTRANSPORT_ERROR_ILLEGAL_STATE is returned if the transport is currently in listen mode (see StartListening), or there is already an open connection to the debugger (see IsOpen).

JDWPTRANSPORT_ERROR_IO_ERROR is returned if there is an error (other than an attach timeout) attaching to the debugger. Note that errors during the start-up handshake (including a handshake timeout) are considered I/O errors. I/O errors are specific to the transport. GetLastError can be used to obtain a string representation of the error.

JDWPTRANSPORT_ERROR_TIMEOUT is returned if the transport supports an attach timeout, and if the attachTimeout value is positive, and if the connection to the debugger cannot be established within that attachTimeout period.

StartListening

jdwpTransportError
StartListening(jdwpTransportEnv* env, const char* address, char** actualAddress);

Puts the transport into listen mode to listen for a connection from a debugger.

The address argument is a pointer to a string representing the local address that the transport should listen on. The exact format is specific to the transport (In the case of a TCP/IP based transport the address might a local TCP port number. In the case of a transport that supports connections through a serial port it might be the device name of a serial port). The address argument can be specified as NULL or as an empty string (first character is \0). In that case the transport listens on a default address that is specific to the transport.

If actualAddress is not NULL then it is set to the address of a string returned by the StartListening function. The returned string will contain the string representation of the address that the transport is listening on. This may, or may not, differ from the address provided in the address argument. The string is allocated using the allocation callback provided to the transport when the jdwpTransport_OnLoad function was called. The caller is responsible for freeing the returned string.

This function returns a universal error or one of the following errors:

JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT
JDWPTRANSPORT_ERROR_ILLEGAL_STATE
JDWPTRANSPORT_ERROR_IO_ERROR

JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT is returned if address is invalid.

JDWPTRANSPORT_ERROR_ILLEGAL_STATE is returned if there is already an open connection to a debugger (see IsOpen), or the transport is already in listen mode.

JDWPTRANSPORT_ERROR_IO_ERROR is returned if there is an error putting the transport into listen mode. The nature of the error is specific to the transport. GetLastError can be used to obtain a string representing the error.

StopListening

jdwpTransportError
StopListening(jdwpTransportEnv* env)

Takes the transport out of listen mode so that it's no longer listening for connections from a debugger.

If the transport is in listen mode then it will be taken out of this mode. If there is an open (see IsOpen) connection to a debugger then it is unaffected by this function. In other words, StopListening does not close a connection to the debugger. If the transport is not in listen mode then this function does nothing and no error is returned.

This function returns a universal error or one of the following errors:

JDWPTRANSPORT_ERROR_IO_ERROR

JDWPTRANSPORT_ERROR_IO_ERROR is returned if there is an error taking the transport out of listen mode. The nature of the error is specific to the transport. GetLastError can be used to obtain a string representing the error.

Accept

jdwpTransportError
Accept(jdwpTransportEnv* env, jlong acceptTimeout, jlong handshakeTimeout)

Accepts a connection from a debugger. Accepting a connection from a debugger involves two steps. Firstly, a connection is established by the debugger. Once a connection is established a handshake is performed to ensure that the connection was indeed established by a debugger. Handshaking involves the exchange of ASCII string JDWP-Handshake as specified in the Java Debug Wire Protocol specification.

The acceptTimeout argument specifies the timeout to use while waiting for the debugger to connect. If the transport supports an accept timeout (see GetCapabilities) and if the acceptTimeout is positive then it specifies the timeout, in milliseconds (more or less), to use when waiting for a connection from a debugger. If the transport does not support an accept timeout, or if timeout is specified as zero then block indefinitely waiting for a connection.

The handshakeTimeout argument specifies a timeout to use when handshaking with the debugger. If the transport supports a handshake timeout (see GetCapabilities) and if the handshakeTimeout is positive then it specifies the timeout, in milliseconds (more or less), to use when handshaking with the debugger. The exact usage of the handshake timeout is specific to the transport - for example one implementation may use the timeout as an inter-character timeout while waiting for the JDWP-Handshake message from the debugger. Another implementation may use the timeout to indicate the total duration allowed for the handshake exchange. In general the purpose of the handshake timeout is to allow for error handling in the event that something other than a debugger establishes a connection to the debuggee. If the transport does not support a handshake timeout, or if the handshakeTimeout is specified as zero then a timeout is not used when handshaking.

This function returns a universal error or one of the following errors:

JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT
JDWPTRANSPORT_ERROR_ILLEGAL_STATE
JDWPTRANSPORT_ERROR_IO_ERROR
JDWPTRANSPORT_ERROR_TIMEOUT

JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT is returned if attachTimeout or handshakeTimeout is negative.

JDWPTRANSPORT_ERROR_ILLEGAL_STATE is returned if there is already an open connection to a debugger (see IsOpen), or if the transport is not in listen mode (see StartListening).

JDWPTRANSPORT_ERROR_IO_ERROR is returned if there is an error (other than an accept timeout) while accepting a connection from a debugger. Note that errors during the start-up handshake (including a handshake timeout) are considered I/O errors. The nature of the error is specific to the transport. GetLastError can be used to obtain a string representing the error.

JDWPTRANSPORT_ERROR_TIMEOUT is returned if the transport supports an accept timeout, and if the acceptTimeout value is positive, and if the connection to the debugger cannot be established within that timeout period.

Note: A thread that is blocked in Accept waiting for a connection from a debugger can be interrupted by another thread calling StopListening. In that case the thread that called Accept will return JDWPTRANSPORT_ERROR_IO_ERROR indicating an I/O error has occurred. If a thread blocked in Accept has accepted a connection and is in the process of handshaking with the debugger then StopListening will not interrupt the connection.

IsOpen

jboolean
isOpen(jdwpTransportEnv* env)

Tells whether or not there is a connection open to a debugger.

Returns JNI_TRUE if, and only if, there is an open connection to a debugger. Otherwise it returns JNI_FALSE.

Close

jdwpTransportError
Close(jdwpTransportEnv* env)

Closes an open connection to a debugger.

If there isn't an open connection to a debugger (see IsOpen) then this function does nothing and no error is returned.

If there are threads blocked in any I/O functions (namely, ReadPacket and WritePacket), then these I/O functions will be interrupted by the close and will return an JDWPTRANSPORT_ERROR_IO_ERROR indicating an I/O error has occurred.

This function returns a universal error or one of the following errors:

JDWPTRANSPORT_ERROR_IO_ERROR

JDWPTRANSPORT_ERROR_IO_ERROR is returned if there is an error closing the connection. The nature of the error is specific to the transport. GetLastError can be used to obtain a string representing the error.

I/O Functions

The I/O functions are used for reading and writing JDWP packets from and to the debugger.

ReadPacket

typedef struct {
    jint len;
    jint id;
    jbyte flags;
    jbyte cmdSet;
    jbyte cmd;
    jbyte *data;
} jdwpCmdPacket;

typedef struct {
    jint len;
    jint id;
    jbyte flags;
    jshort errorCode;
    jbyte *data;
} jdwpReplyPacket;

typedef struct jdwpPacket {
    union {
        jdwpCmdPacket cmd;
        jdwpReplyPacket reply;
    } type;
} jdwpPacket;

jdwpTransportError
ReadPacket(jdwpTransportEnv* env, jdwpPacket* packet)

Reads a JDWP packet from an open connection to a debugger.

This function does a blocking read on an open connection. It blocks indefinitely until a complete JDWP packet can be returned, or in the case of a transport based on a stream-oriented protocol, end-of-stream is encountered.

The packet argument is the address of a jdwpPacket structure that is populated by this function. The packet.type.cmd.len or packet.type.reply.len field (depending on if the packet is a command or reply packet) is populated with the length of the packet. If end of stream is encountered the length field will be set to 0 and all other fields in the packet will be undefined. If end of stream is encountered after reading some, but not all, bytes of a packet it is considered an I/O error and JDWPTRANSPORT_ERROR_IO_ERROR will be returned. In that case the length field will not be populated. When an entire packet is read then all fields in the packet are populated with values in host order. This may, or may not, differ from the big endian order require when transmitting JDWP packets.

The packet.type.cmd.data or packet.type.reply.data field (depending on if the packet is a command or reply packet) will be populated with NULL or a pointer to the packet data allocated by this function. Packet data is allocated using the allocation callback provided to the transport when the jdwpTransport_OnLoad function was called. The caller is responsible to free it. The layout of the packet data (that is the data following the header, if any) is returned to the caller in the byte ordering in which it was received.

The ReadPacket function does not do any integrity checking on the returned packet except checking that the length of the packet (as indicated by the first 4 bytes) is >= 11 bytes. If the length field is less than 11 bytes then JDWPTRANSPORT_ERROR_IO_ERROR is returned.

This function returns a universal error or one of the following errors:

JDWPTRANSPORT_ERROR_IO_ERROR
JDWPTRANSPORT_ERROR_ILLEGAL_STATE
JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT

JDWPTRANSPORT_ERROR_IO_ERROR is returned if an I/O error occurs when reading, the connection is closed asynchronously by another thread calling the Close function, or a badly formed packet (length field less than 11 bytes) is received. I/O errors are specific to the transport. GetLastError can be used to obtain a string representing the error.

JDWPTRANSPORT_ERROR_ILLEGAL_STATE is returned if there isn't an open connection to a debugger (see IsOpen).

JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT is returned if packet is NULL

WritePacket

jdwpTransportError
WritePacket(jdwpTransportEnv* env, const jdwpPacket* packet)

Writes a JDWP packet to an open connection.

The packet argument is a pointer to a jdwpPacket structure. All fields in the packet header must be stored in host order. The packet data field (packet.type.cmd.data or packet.type.reply.data) must be NULL, or a pointer to a location containing packet data that immediately follows the header. The packet data is must be in network order (big endian) ready for transmission.

This function returns a universal error or one of the following errors:

JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT
JDWPTRANSPORT_ERROR_IO_ERROR
JDWPTRANSPORT_ERROR_ILLEGAL_STATE

JDWPTRANSPORT_ERROR_ILLEGAL_ARGUMENT if packet is NULL, or if the packet length field (packet.type.cmd.len or packet.type.reply.len) is less than 11, or it is greater than 11 but the packet data field (packet.type.cmd.data or packet.type.reply.data) is NULL.

JDWPTRANSPORT_ERROR_IO_ERROR is returned if an I/O error occurs when writing, or the connection is closed asynchronously by another thread calling the Close function. I/O errors are specific to the transport. GetLastError can be used to obtain a string representing the error.

JDWPTRANSPORT_ERROR_ILLEGAL_STATE is returned if there isn't an open connection to a debugger (see IsOpen).

Miscellaneous Functions

GetLastError

jdwpTransportError
GetLastError(jdwpTransportEnv* env, char** msg);

Returns the string representation of the last error.

When an error occurs it is recorded on a per-thread basis. A subsequent call to GetLastError returns the string representation of the last I/O error.

The msg argument is a pointer to a null-terminated string returned by this function. The string is allocated using the allocation callback provided to the transport when the jdwpTransport_OnLoad function was called. The caller is responsible to free the returned string.

This function returns a universal error or one of the following errors:

JDWPTRANSPORT_ERROR_MSG_NOT_AVAILABLE

JDWPTRANSPORT_ERROR_MSG_NOT_AVAILABLE is returned if this thread has not encountered an I/O error or there isn't a string representation of the last error available.

GetCapabilities

typedef struct {
    unsigned int can_timeout_attach	:1;
    unsigned int can_timeout_accept	:1;
    unsigned int can_timeout_handshake  :1;
    unsigned int reserved3		:1;
    unsigned int reserved4		:1;
    unsigned int reserved5		:1;
    unsigned int reserved6		:1;
    unsigned int reserved7		:1;
    unsigned int reserved8		:1;
    unsigned int reserved9		:1;
    unsigned int reserved10		:1;
    unsigned int reserved11		:1;
    unsigned int reserved12		:1;
    unsigned int reserved13		:1;
    unsigned int reserved14		:1;
    unsigned int reserved15		:1;
} JDWPTransportCapabilities;

jdwpTransportError
GetCapabilities(jdwpTransportEnv* env, JDWPTransportCapabilities* capabilitiesPtr)

Returns via capabilitiesPtr the optional jdwpTransport features supported by this transport. The capabilities structure contains a number of boolean flags indicating whether the named feature is supported. The current set of flags is:

can_timeout_attach | Indicates if the transport supports attaching with a timeout
can_timeout_accept | Indicates if the transport supports an accept timeout
can_timeout_handshake | Indicates if the transport supports a timeout when performing the initial handshake with the debugger when the connection is established

This function does not return any errors.

Universal Errors

JDWPTRANSPORT_ERROR_NONE | No error has occurred. This is the error code that is returned on successful completion of the function.
JDWPTRANSPORT_ERROR_OUT_OF_MEMORY | The function needed to allocate memory and no more memory was available for allocation.
JDWPTRANSPORT_ERROR_INTERNAL | An unexpected internal error has occurred.

Copyright© 2004 Sun Microsystems, Inc. All Rights Reserved.

Feedback

Sun


Java Platform Debugger Architecture

Release notes for the javadt debugger

As a demonstration of the Java Debug Interface (JDI), we are providing source code for a simple GUI debugging tool - javadt. It is included as an example and demonstration of JDI. It is not a finished or polished debugger and is missing many features of importance for real debugging work.

Invoking javadt

javadt can be run by executing:

   java gui.GUI <options>.. <class-name>

where <class-name> is the name you would normally place on the java command line. Note: the paths to the JDI Library and to the compiled javadt class files must be on the class path used to invoke gui.GUI. Be sure that the Java 2 SDK's lib/tools.jar file on your class path.

For example, you can invoke the javadt debugger as follows:

   javadt gui.GUI -classpath . Hello
Note: this -classpath option controls the class path for the Hello application. Once the window appears, you can issue the 'run' command to begin execution immediately. It is also possible to give the class name in the 'run' command, in which case it may be omitted when invoking the debugger from the shell.

The classpath may also be set from within the debugger, using the 'classpath' command. Currently, other arguments to the VM must be given on the shell command line when the debugger is initially invoked. The most recently mentioned classpath, VM arguments, main class name, and program arguments are retained as defaults for later 'run' and 'load' commands. (Unfortunately, at present, the debugger will likely crash if you attempt to begin another debugging session with another debuggee process from within the same invocation of the debugger. You should exit to the shell and start a new debugger process.)

Using javadt

The javadt normally displays context related to the "current thread", that is, the thread that most recently encountered a breakpoint, threw an uncaught exception, or was single-stepped by the user. When program execution is suspended on account of one of these events, a current thread exists, and the javadt displays the following information about it:

  • A stack backtrace.
  • The source code surrounding the line corresponding to the instruction counter for the thread, if the source code is available.

In addition, a tabbed pane allows the user to view one of three additional views:

  • A tree of all source files available on the source path.
  • A tree of all loaded class files, organized hierarchically by package.
  • A tree of all active threads, organized hierarchically by thread group.

By clicking on the name of a source file, the source view can be directed to display it. Likewise, clicking on a thread will make that thread the current thread. These features are normally used while the program is suspended, e.g, at a breakpoint. Upon resumption and encountering another breakpoint, for example, the current thread will be automatically reset and the views will be updated. The views tile the javadt display, and are adjustable in size.

The javadt functionality is rather basic, thus a command-line interaction window is also provided that allows access to functions that are not yet exposed in the javadt. In particular, it is necessary to use the command line in order to set breakpoints and examine variables. The javadt debugger command interpreter implements roughly a subset of the jdb functionality, but adds a few commands of its own. The 'help' command lists the complete set of commands and their function. Shortcuts for a set of the most common commands is provided on a button-bar at the top of the display.

The program to be debugged may be started either as a child of the debugger, or the debugger can be attached to an existing process, provided that its VM is prepared to accept the connection. If the debuggee is started by the debugger as a child, a line-oriented interface to its standard input, output, and error streams is provided in an application interaction pane.

The debugger expects to find the program source code on its sourcepath, set with the 'use' or 'sourcepath' command. If you find that sources are not being displayed because the sourcepath is incorrect, you may change it at that time, and the source view will be immediately updated.

The message "No current thread" is often encountered when stepping through a program. This message does not mean that the thread or the VM has died, merely that a current thread is undefined. This situation can easily occur unexpectedly when the program being stepped is waiting, eg., for input. The VM appears to be stopped, as it would be after the successful completion of a step, but it is considered to be "running", not "interrupted". The prompt in the command interaction pane indicates the state by changing to a thread name and frame number when the VM is interrupted. When it is running, the prompt "Command:" is displayed.

Source for javadt

Full source code for javadt is included in the com/sun/tools/example/debug directory of examples.jar. Note: this directory also includes the source for jdb. Source code of these example applications is included to provide concrete examples for debugger developers. Example code may be used, modified and redistributed by debugger developers providing they adhere to the terms in the copyright notice.

javadt uses the following packages (found in the com/sun/tools/example/debug directory of examples.jar):

gui
User interface code
bdi
Debugger core code
events
Event Set code
expr
Expression processing code

Building javadt

To build the javadt classes from the provided source files in the debuggers directory, you need only to compile them. No special options are required, aside from those which set your classpath to include the JDI Library. However, if want to modify the expression parser in the file Expr.jj, you will need the JavaCC parser generator.


Java Platform Debugger Architecture

As a demonstration of the Java Debug Interface (JDI), we are providing source code for the jdb debugger.

jdb man pages

jdb man pages for Windows

jdb man pages for Solaris

Invoking jdb

The jdb sample can be run by executing:

   java tty.TTY <options>.. <class-name>
where <class-name> is the name you would normally place on the java command line. The -help option provides information on options. Note: Be sure that the Java 2 SDK's lib/tools.jar file is on the class path used to invoke tty.TTY. The tools.jar file includes the JDI Library and to the compiled jdb class files.

For more information on invoking and connecting see Connection and Invocation Details section of the JPDA documentation, particularly the section on jdb.

Source for jdb

Full source code for jdb is included as part of the example code in the Java 2 SDK's lib/jpda directory, in examples.jar. (Use jar xvf examples.jar to extract the contents of examples.jar.) Note: this file also includes the source for javadt. Source code of these example application is included to provide concrete examples for debugger developers. Example code may be used, modified and redistributed by debugger developers providing they adhere to the terms in the copyright notice.

jdb uses the following packages (found in the examples.jar file):

tty
Application code
expr
Expression processing code

Building jdb

To completely rebuild the jdb classes from the provided source files, you need only to compile them. No special options are required, aside from those which set your classpath to include the JDI Library. However, if want to modify the expression parser in the file Expr.jj, you will need the JavaCC parser generator.


Java Platform Debugger Architecture

Trace runs the Java language program passed as an argument and generates a trace of its execution. Trace is a simple command line tool that uses the Java Debug Interface (JDI). Programs need not be compiled for debugging since this information is not used.

Trace can be invoked as follows:

        java Trace options class args
Your classpath must include the Java 2 SDK's lib/tools.jar file which contains the JDI Library (see set-up), the path to the compiled trace class files, and the path for the application being traced.

Available options are:
  -output filename
        Set destination for output trace. By default output
        goes to the terminal.

  -all
        Include system classes in output.  By default
        java.*, javax.*, sun.* and com.sun.* events are
        not diplayed.

  -fields
        Also show assignments into fields.

  -help
        Print a help message

class is the program to trace. args are the arguments to class.

Source for trace

Full source code for trace is included in the trace directory of examples.jar. Source code of these example application is included to provide concrete examples for debugger developers. Example code may be used, modified and redistributed by debugger developers providing they adhere to the terms in the copyright notice.

Building trace

To completely rebuild the trace classes from the provided source files in the trace directory, you need only to compile them. No special options are required, aside from those which set your classpath to include the JDI Library in lib/tools.jar.


Java Platform Debugger Architecture - Example JDI Applications

For v1.3.0 and later releases, the Java 2 SDK's demo/jpda directory contains source code and documentation for three applications written using the Java Debug Interface (JDI) of the Java Platform Debugger Architecture (JPDA). They are provided as educational tools and as starting points for debugger development.

In increasing order of complexity:

  • Trace displays traces of program execution. It is very simple (less than 600 lines) yet uses most of the basic JDI functionality. It is a good starting point.
  • Jdb is the command line debugger distributed with the J2SE SDK v1.3 and later releases.
  • Javadt is the beginnings of a GUI debugger.

Trace is in the trace directory. Jdb and Javadt share a package, and are in the debuggers directory.

Required Set-up

Your classpath must include the JDI Library code, which is in lib/tools.jar directory of the Java 2 SDK. (Note that tools.jar is not in the Java Runtime Environment; it is only in the Java 2 SDK.) This is needed for both compiling the example code and executing it. For information on how to set the classpath, see the Java SE tools documentation.


Java(tm) Debug Wire Protocol

Java

JavaTM Debug Wire Protocol

 JPDA

Protocol details

Overview

The JavaTM Debug Wire Protocol (JDWP) is the protocol used for communication between a debugger and the Java virtual machine (VM) which it debugs (hereafter called the target VM). JDWP is optional; it might not be available in some implementations of the Java(TM) 2 SDK. The existence of JDWP can allow the same debugger to work

  • in a different process on the same computer, or
  • on a remote computer,

The JDWP differs from many protocol specifications in that it only details format and layout, not transport. A JDWP implementation can be designed to accept different transport mechanisms through a simple API. A particular transport does not necessarily support each of the debugger/target VM combinations listed above.

The JDWP is designed to be simple enough for easy implementation, yet it is flexible enough for future growth.

Currently, the JDWP does not specify any mechanism for transport rendezvous or any directory services. This may be changed in the future, but it may be addressed in a separate document.

JDWP is one layer within the Java Platform Debugger Architecture (JPDA). This architecture also contains the higher-level Java Debug Interface (JDI). The JDWP is designed to facilitate efficient use by the JDI; many of its abilities are tailored to that end. The JDI is more appropriate than JDWP for many debugger tools, particularly those written in the Java programming language. For more information on the Java Platform Debugger Architecture, see the Java Platform Debugger Architecture documentation for this release.

JDWP Start Up

After the transport connection is established and before any packets are sent, a handshake occurs between the two sides of the connection:

The handshake process has the following steps:

  • The debugger side sends 14 bytes to the VM side, consisting of the 14 ASCII characters of the string "JDWP-Handshake".
  • The VM side replies with the same 14 bytes: JDWP-Handshake

JDWP Packets

The JDWP is packet based and is not stateful. There are two basic packet types: command packets and reply packets.

Command packets may be sent by either the debugger or the target VM. They are used by the debugger to request information from the target VM, or to control program execution. Command packets are sent by the target VM to notify the debugger of some event in the target VM such as a breakpoint or exception.

A reply packet is sent only in response to a command packet and always provides information success or failure of the command. Reply packets may also carry data requested in the command (for example, the value of a field or variable). Currently, events sent from the target VM do not require a response packet from the debugger.

The JDWP is asynchronous; multiple command packets may be sent before the first reply packet is received.

Command and reply packet headers are equal in size; this is to make transports easier to implement and abstract. The layout of each packet looks like this:

Command Packet
  • Header
    • length (4 bytes)
    • id (4 bytes)
    • flags (1 byte)
    • command set (1 byte)
    • command (1 byte)
  • data (Variable)
Reply Packet
  • Header
    • length (4 bytes)
    • id (4 bytes)
    • flags (1 byte)
    • error code (2 bytes)
  • data (Variable)

All fields and data sent via JDWP should be in big-endian format. (See the Java Virtual Machine Specification for the definition of big-endian.) The first three fields are identical in both packet types.

Command and Reply Packet Fields

Shared Header Fields
length
The length field is the size, in bytes, of the entire packet, including the length field. The header size is 11 bytes, so a packet with no data would set this field to 11.
id
The id field is used to uniquely identify each packet command/reply pair. A reply packet has the same id as the command packet to which it replies. This allows asynchronous commands and replies to be matched. The id field must be unique among all outstanding commands sent from one source. (Outstanding commands originating from the debugger may use the same id as outstanding commands originating from the target VM.) Other than that, there are no requirements on the allocation of id's.

A simple monotonic counter should be adequate for most implementations. It will allow 2^32 unique outstanding packets and is the simplest implementation alternative.

flags
Flags are used to alter how any command is queued and processed and to tag command packets that originate from the target VM. There is currently one flag bits defined; future versions of the protocol may define additional flags.

0x80
Reply packet

The reply bit, when set, indicates that this packet is a reply.

Command Packet Header Fields
command set
This field is useful as a means for grouping commands in a meaningful way. The Sun defined command sets are used to group commands by the interfaces they support in the JDI. For example, all commands that support the JDI VirtualMachine interface are grouped in a VirtualMachine command set.

The command set space is roughly divided as follows:

0 - 63
Sets of commands sent to the target VM
64 - 127
Sets of commands sent to the debugger
128 - 256
Vendor-defined commands and extensions.
command
This field identifies a particular command in a command set. This field, together with the command set field, is used to indicate how the command packet should be processed. More succinctly, they tell the receiver what to do. Specific commands are presented later in this document.
Reply Packet Header Fields
error code
This field is used to indicate if the command packet that is being replied too was successfully processed. A value of zero indicates success, a non-zero value indicates an error. The error code returned may be specific to each command set/command, but it is often mapped to a JVM TI error code.
Data
The data field is unique to each command set/command. It is also different between command and reply packet pairs. For example, a command packet that requests a field value will contain references to the object and field id's for the desired value in its data field. The reply packet's data field will contain the value of the field.

Detailed Command Information

In general, the data field of a command or reply packet is an abstraction of a group of multiple fields that define the command or reply data. Each subfield of a data field is encoded in big endian (Java) format. The detailed composition of data fields for each command and its reply are described in this section.

There is a small set of common data types that are common to many of the different JDWP commands and replies. They are described below.

Name | Size | Description
byte | 1 byte | A byte value.
boolean | 1 byte | A boolean value, encoded as 0 for false and non-zero for true.
int | 4 bytes | An four-byte integer value. The integer is signed unless explicitly stated to be unsigned.
long | 8 bytes | An eight-byte integer value. The value is signed unless explicitly stated to be unsigned.
objectID Target VM-specific, up to 8 bytes (see below) Uniquely identifies an object in the target VM. A particular object will be identified by exactly one objectID in JDWP commands and replies throughout its lifetime (or until the objectID is explicitly disposed). An ObjectID is not reused to identify a different object unless it has been explicitly disposed, regardless of whether the referenced object has been garbage collected. An objectID of 0 represents a null object.

Note that the existence of an object ID does not prevent the garbage collection of the object. Any attempt to access a a garbage collected object with its object ID will result in the INVALID_OBJECT error code. Garbage collection can be disabled with the DisableCollection command, but it is not usually necessary to do so.

tagged-objectID | size of objectID plus one byte | The first byte is a signature byte which is used to identify the object's type. See JDWP.Tag for the possible values of this byte (note that only object tags, not primitive tags, may be used). It is followed immediately by the objectID itself.
threadID | same as objectID | Uniquely identifies an object in the target VM that is known to be a thread
threadGroupID | same as objectID | Uniquely identifies an object in the target VM that is known to be a thread group
stringID | same as objectID | Uniquely identifies an object in the target VM that is known to be a string object. Note: this is very different from string, which is a value.
classLoaderID | same as objectID | Uniquely identifies an object in the target VM that is known to be a class loader object
classObjectID | same as objectID | Uniquely identifies an object in the target VM that is known to be a class object.
arrayID | same as objectID | Uniquely identifies an object in the target VM that is known to be an array.
referenceTypeID | same as objectID | Uniquely identifies a reference type in the target VM. It should not be assumed that for a particular class, the classObjectID and the referenceTypeID are the same. A particular reference type will be identified by exactly one ID in JDWP commands and replies throughout its lifetime A referenceTypeID is not reused to identify a different reference type, regardless of whether the referenced class has been unloaded.
classID | same as referenceTypeID | Uniquely identifies a reference type in the target VM that is known to be a class type.
interfaceID | same as referenceTypeID | Uniquely identifies a reference type in the target VM that is known to be an interface type.
arrayTypeID | same as referenceTypeID | Uniquely identifies a reference type in the target VM that is known to be an array type.
methodID | Target VM-specific, up to 8 bytes (see below) | Uniquely identifies a method in some class in the target VM. The methodID must uniquely identify the method within its class/interface or any of its subclasses/subinterfaces/implementors. A methodID is not necessarily unique on its own; it is always paired with a referenceTypeID to uniquely identify one method. The referenceTypeID can identify either the declaring type of the method or a subtype.
fieldID | Target VM-specific, up to 8 bytes (see below) | Uniquely identifies a field in some class in the target VM. The fieldID must uniquely identify the field within its class/interface or any of its subclasses/subinterfaces/implementors. A fieldID is not necessarily unique on its own; it is always paired with a referenceTypeID to uniquely identify one field. The referenceTypeID can identify either the declaring type of the field or a subtype.
frameID | Target VM-specific, up to 8 bytes (see below) | Uniquely identifies a frame in the target VM. The frameID must uniquely identify the frame within the entire VM (not only within a given thread). The frameID need only be valid during the time its thread is suspended.
location Target VM specific An executable location. The location is identified by one byte type tag followed by a a classID followed by a methodID followed by an unsigned eight-byte index, which identifies the location within the method. Index values are restricted as follows:
  • The index of the start location for the method is less than all other locations in the method.
  • The index of the end location for the method is greater than all other locations in the method.
  • If a line number table exists for a method, locations that belong to a particular line must fall between the line's location index and the location index of the next line in the table.
Index values within a method are monotonically increasing from the first executable point in the method to the last. For many implementations, each byte-code instruction in the method has its own index, but this is not required.

The type tag is necessary to identify whether location's classID identifies a class or an interface. Almost all locations are within classes, but it is possible to have executable code in the static initializer of an interface.

string | Variable | A UTF-8 encoded string, not zero terminated, preceded by a four-byte integer length.
value | Variable | A value retrieved from the target VM. The first byte is a signature byte which is used to identify the type. See JDWP.Tag for the possible values of this byte. It is followed immediately by the value itself. This value can be an objectID (see Get ID Sizes) or a primitive value (1 to 8 bytes). More details about each value type can be found in the next table.
untagged-value | Variable | A value as described above without the signature byte. This form is used when the signature information can be determined from context.
arrayregion | Variable | A compact representation of values used with some array operations. The first byte is a signature byte which is used to identify the type. See JDWP.Tag for the possible values of this byte. Next is a four-byte integer indicating the number of values in the sequence. This is followed by the values themselves: Primitive values are encoded as a sequence of untagged-values; Object values are encoded as a sequence of values.

Object ids, reference type ids, field ids, method ids, and frame ids may be sized differently in different target VM implementations. Typically, their sizes correspond to size of the native identifiers used for these items in JNI and JVMDI calls. The maximum size of any of these types is 8 bytes. The "idSizes" command in the VirtualMachine command set is used by the debugger to determine the size of each of these types.

If a debuggee receives a Command Packet with a non-implemented or non-recognized command set or command then it returns a Reply Packet with the error code field set to NOT_IMPLEMENTED (see Error Constants).

Protocol details

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Feedback

 Sun


Java(tm) Platform Debugger Architecture

Java

JavaTM Platform Debugger Architecture (JPDA)

 Documentation Contents
The Java Platform Debugger Architecture (JPDA) consists of three interfaces designed for use by debuggers in development environments for desktop systems. The Java Virtual Machine Tools Interface (JVM TI) defines the services a VM must provide for debugging (JVM TI is a replacement for the Java Virtual Machine Debug Interface (JVMDI) which has been removed). The Java Debug Wire Protocol (JDWP) defines the format of information and requests transferred between the process being debugged and the debugger front end, which implements the Java Debug Interface (JDI). The Java Debug Interface defines information and requests at the user code level.

Enhancements

  • JPDA Enhancements in Java SE 6
  • JPDA Enhancements in J2SE 5.0
  • JPDA Enhancements in J2SE 1.4

Design

  • JPDA Overview
    • Modularity
    • Walk-through
    • Porting
  • Architecture Structure
    • Structure Overview
    • Components
    • Debugger Interfaces
      • Java Virtual Machine Tool Interface
      • Java Debugger Wire Protocol
      • Java Debug Interface

Interface Reference

  • Java Virtual Machine Tool Interface (JVM TI)

      • NOTE: JVMPI, the experimental Java Virtual Machine Profiling Interface has removed. It has been replaced by JVM TI.

    • Specification

  • Java Virtual Machine Debug Interface (JVMDI)

      • JVMDI has been removed. It has been replaced by JVM TI. See the JVMDI specification in the JDK 5.0 documentation.

  • Java Debug Wire Protocol (JDWP)

    • Specification

  • Java Debug Wire Protocol Interface

    • Specification

  • Java Debug Interface (JDI)

    • Specification

Implementation

  • Connection and Invocation Details

More Information

  • The JPDA Home Page

Examples

  • Example JDI Applications
The demo/jpda/examples.jar file in the JDK software contains JPDA examples, including source code for the jdb Java Debugger and the prototype javadt GUI debugger.
Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun
Java Software


Java(tm) Platform Debugger Architecture

Java

Java Platform Debugger Architecture

Back to Home Page

Structure Overview

The JavaTM Platform Debugger Architecture is structured as follows:
             Components                         Debugger Interfaces

                /    |--------------|
               /     |     VM       |
 debuggee ----(      |--------------|  <------- JVM TI - Java VM Tool Interface
               \     |   back-end   |
                \    |--------------|
                /           |
 comm channel -(            |  <--------------- JDWP - Java Debug Wire Protocol
                \           |
                     |--------------|
                     | front-end    |
                     |--------------|  <------- JDI - Java Debug Interface
                     |      UI      |
                     |--------------|

What is the Java Platform Debugger Architecture (JPDA)?

JPDA is a multi-tiered debugging architecture that allows tools developers to easily create debugger applications which run portably across platforms, virtual machine (VM) implementations and JDK versions.

JPDA consists of three layers:

JVM TI - Java VM Tool Interface
JVM TI is a new interface introduced in J2SE 5.0 which replaces JVMDI. It defines the debugging services a VM provides.
JDWP - Java Debug Wire Protocol
Defines the communication between debuggee and debugger processes.
JDI - Java Debug Interface
Defines a high-level Java language interface which tool developers can easily use to write remote debugger applications.

Reference implementation

In addition to the specification of these interfaces, Sun Microsystems also provides a reference implementation, which consists of:
  • JVM TI implementations on multiple Sun VMs (see VM documentation).
  • A back-end which uses JVM TI to implement the debuggee side of JDWP.
  • A front-end which uses the debugger side of JDWP to implement JDI.
  • Two simple example debugger applications which are built on JDI.
This provides a layered implementation in which any layer may be substituted.

Using JPDA

A debugger developer may hook into JPDA at any layer. Since the JDI is the highest level and easiest to use we encourage developers to use this interface. Suppose a company develops a debugger using JDI. They can use it with the reference implementation and it will automatically work with the VMs and platforms Sun supports. It can also work, for example, with the reference implementation front-end and a debuggee running another company's VM that implements JDWP (which might use or by-pass JVM TI).

Some debuggers are built on top of lower layers, JDWP (for example if the front-end is not written in the Java language) or JVM TI (for specialized debuggers which need low-level functionality).

Components

debuggee

    The debuggee is the process being debugged, it consists of the application being debugged (not shown), the VM running the application and the back-end of the debugger.

Java Virtual Machine (VM)

    This refers to the VM running the application being debugged.

    The debugger architecture is being designed for use in wide spectrum of VM implementations.

    The VM implements the Java Virtual Machine Debug Interface (JVM TI).

back-end

    The back-end of the debugger is responsible for communicating requests from the debugger front-end to the debuggee VM and for communicating the response to these requests (including desired events) to the front-end. The back-end communicates with the front-end over a communications channel using the Java Debug Wire Protocol (JDWP). The back-end communicates with the debuggee VM using the Java Virtual Machine Debug Interface (JVM TI).

    It is clear from experience that debugger support code, running on the debuggee and written in Java, contends with the debuggee in ways that cause hangs and other undesired behavior. Thus, the back-end is native code. This, in turn, implies that the JVM TI be a pure native interface.

communications channel

The communications channel is the link between the front and back ends of the debugger. It can be thought of as consisting of two mechanisms:

  1. A connector. A connector is a JDI object that is the means by which a connection is established between the front and back-ends.

    JPDA defines three types of connectors:

    • listening connectors: The front-end listens for an incoming connection from the back-end
    • attaching connectors: The front-end attaches to an already running back-end.
    • launching connectors: The front-end actually launches the java process that will run the debuggee code and the back-end.

  2. A transport. A transport is the underlying mechanism used to move bits between the front-end and the back-end.

    The transport mechanism used is unspecified; possible mechanisms include: sockets, serial lines, and shared memory. However, the format and semantics of the serialized bit-stream flowing over the channel is specified by the Java Debug Wire Protocol (JDWP).
Starting with J2SE 5.0, JPDA includes service provider interfaces to allow the development and deployment of connector and transport implementations. These service provider interfaces allow debugger and other tool vendors to develop new connector implementations and provide addition transport mechanisms over and beyond the socket and shared memory transport provided by Sun. The service provider interfaces in JDI are specified in the com.sun.jdi.connect.spi package.

In addition to the service provider interfaces in JDI, JPDA also defines a transport library interface called the Java TMDebug Wire Protocol Transport Interface. A transport library is loaded by the JDWP agent in the target VM and is used to establish a connection to the debugger and to transport JDWP packets between the debugger and the VM.

See JavaTM Platform Debugger Architecture - Service Provider Interfaces for more information on using these SPIs.

front-end

    The debugger front-end implements the high-level Java Debug Interface (JDI). The front-end uses the information from the low-level Java Debug Wire Protocol (JDWP).

User Interface (UI)

    The user interface to the debugger is not specified; the intent is that tool vendors will provide value added implementations. We provide an example simple graphical user interface (GUI) which serves as test harness and as a starting point for the development of more complex GUIs. A version of JDB is also available as an example.

    The example UIs are clients of the Java Debug Interface (JDI).

Debugger Interfaces

Java Virtual Machine Tool Interface (JVM TI)
    A native interface implemented by the VM.

    Defines the services a VM must provide for debugging. Includes requests for information (for example, current stack frame), actions (for example, set a breakpoint), and notification (for example, when a breakpoint has been hit). A debugger may make use of VM information other than this (for example, Java Native Interface (JNI)), but this is the source of all debugger specific information.

    Specifying the VM Interface allows any VM implementor to plug easily into the debugging architecture. It also allows alternate communication channel implementations. VM implementations which do not adhere to this interface can still provide access via the Java Debug Wire Protocol (JDWP).

    See also:

      JVM TI Specification

Java Debug Wire Protocol (JDWP)
    Defines the format of information and requests transferred between the debuggee process and the debugger front-end. It does not define the transport mechanism (socket, serial line, shared memory, ...).

    The specification of the protocol allows the debuggee and debugger front-end to run under separate VM implementations and/or on separate platforms. It also allows the front-end to be written in a language other than Java, or the debuggee to be non-native (e.g. Java).

    Information and requests are roughly at the level of the Java Virtual Machine Debug Interface (JVM TI), but will include additional information and requests necessitated by bandwidth issues, examples include information filtering and batching.

    See also:

      JDWP Specification
      JDWP Transport Specification

Java Debug Interface (JDI)
    A 100% Java interface implemented by the front-end.

    Defines information and requests at a user code level.

    While debugger implementors could directly use the Java Debug Wire Protocol (JDWP) or Java Virtual Machine Debug Interface (JVM TI), this interface greatly facilitates the integration of debugging capabilities into development environments. We recommend the JDI layer for all debugger development.

    See also:

      JDI Specification

Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun
Java Software


Java(tm) Platform Debugger Architecture - Service provider interfaces

Java

JavaTM Platform Debugger Architecture -
Service Provider Interfaces

Documentation Contents

J2SE 5.0 adds new service provider interfaces to the Java Debug Interface (JDI) so that Connector and TransportService implementations can be developed and deployed. TransportService is a new class in 5.0. It represents the underlying transport service used by a Connector and is used to establish connections and transport Java Debug Wire Protocol (JDWP) packets between a debugger and a target VM.

In addition to new service provider interfaces in JDI, J2SE 5.0 also includes a new transport library interface called the JavaTM Debug Wire Protocol Transport Interface (jdwpTransport). This is a native (C/C++) interface to allow the development and deployment of transport libraries. A transport library is loaded by the debuggee-side JDWP agent and is used to establish a connection to the debugger and to transport JDWP packets between the debugger and the VM.

This page describes a number of scenarios where the new interfaces may be used. It also provides an overview of the tasks involved in developing and deploying new Connectors and transport implementations.

  • Example Scenarios
  • Developing a Connector
  • Deploying a Connector
  • Developing a TransportService
  • Deploying a TransportService

Example Scenarios

The service provider interfaces and the native transport interface are expected to be used by the following classes of users:

  • Debugger and tool vendors that need to develop new LaunchingConnector implementations or wish to provide additional transport options for remote debugging over-and-beyond the TCP/IP and shared memory transports provided by Sun.

  • Embedded device, operating system, or virtual machine vendors that require remote debugging using transports that than TCP/IP.

Given the above class of user the following describes a number of scenarios where the new interfaces might be used.

  • In many environments, particularly embedded devices, the debugger may be required to connect to a target VM using a transport other than TCP/IP. In this type of environment the new service provider interfaces can be used to develop and support debugging over an alternative transport.

    On the debuggee-side a transport library for the new transport can be developed by implementing the jdwpTransport interface. For the debugger, a TransportService implementation can be developed. When the TransportService implementation is deployed, the JDI VirtualMachineManager implementation will automatically create an AttachingConnector and a ListeningConnector to allow remote debugging to the target VM.

  • In some environments the debugger may be required to connect to a target VM using a mechanism other than a transport. For example, the debugger may be used to attach, in a read-only manner, to a crash dump or to a hung process.

    For these examples, an AttachingConnector implementation can be developed. The AttachingConnector implementation extends com.sun.jdi.connect.AttachingConnectors and when deployed it will appear on the list of attaching connectors returned by the VirtualMachineManager's attachingConnectors() method.

  • In many environments the target VM will be launched in a very proprietary way. In such environments the Connector arguments or launch mechanism used by the Sun-provided com.sun.jdi.CommandLineLaunch LaunchingConnector may not be sufficient. In such cases the operating system or virtual machine vendor may decide to develop their own LaunchingConnector that is capable of launching the target VM. This new LaunchingConnector would have appropriate Connector arguments which would be used to configure the target VM for debugging. Once deployed it will appear on the list of Connectors returned by the VirtualMachineManager's launchingConnectors() method.

  • Another example arises in enterprise environments where an Integrated Development Environment (IDE) implementer wishes to support debugging over a non-Sun provided transport. For example an IDE may wish to provide the option of debugging over a secure connection using TLS/SSL.

    In this example the IDE implementer develops a transport library using the jdwpTransport interface. This allows the debuggee to use the new transport. On the debugger-side the IDE implementer has a choice. One option is to develop and deploy a TransportService implementation. This option would allow the new transport to be used for remote debugging.

    Alternatively, the IDE implementer may decide to create a Connector implementation that encapsulates the transport. This option is appropriate when the IDE implementer wishes to add new Connector arguments. For example, with a secure transport the IDE implementer may wish to have a Connector that has Connector arguments to specify keystore, pass phrase, or other options needed to configure the secure connection. If a new Connector is appropriate then the IDE implementer develops a transport library for the debuggee-side and a Connector for the debugger-side. The type of Connector is the choice of the implementer - one example is a LaunchingConnector that launches the debuggee and establishes a secure connection between the debugger and debuggee.

Developing a Connector

Developing a Connector involves creating a concrete implementation of a LaunchingConnector, AttachingConnector, or ListeningConnector.

Every Connector implementation must have a public no-arg constructor in addition to implementing all the Connector methods. The constructor will be called by the VirtualMachineManager during initialization. The constructor may be a no-op or it may perform initialization tasks such as loading a transport service. The constructor does not throw any checked exceptions so any problems during initialization should be thrown as Errors or other unchecked exceptions.

Connectors are not required to use a TransportService. Some Connectors may connect to the target VM using a mechanism other than a transport (in the Example Scenarios section we list the examples of AttachingConnectors that attach to crash dumps or hung processes). For Connectors that use a TransportService implementation the Connector can either reference the TransportService implementation directly or it can load the implementation at runtime. Connectors that wish to make use of Sun provided transports should load the transport service using code such as following:

try {
    Class c = Class.forName("com.sun.tools.jdi.SocketTransportService");
    ts = (TransportService)c.newInstance();
} catch (Exception x) {
    throw new Error(x);
}

Java SE implementations are not required to include Sun's socket or shared memory transport service implementations so in the above example an Error will be thrown if the transport service does not exist.

Assuming that the type of Connector is known then the following items should be noted when developing the implementation:

  • The list of Connector.Arguments should be carefully considered. For some Connector implementations the default argument construction and parsing may be the bulk of the code in the implementation.

  • A Connector is required to name the transport that it uses. If an implementation uses an existing TransportService then the recommended transport name is the name of the underlying TransportService. That is, the Connector's transport() implementation returns a Transport for which the name() method returns a java.lang.String representing the name of the transport.

  • Most Connector implementations will establish a Connection to a target VM. Once established the Connector's launch, attach, or accept method will return a VirtualMachine instance to the debugger. To facilitate the creation of a VirtualMachine mirror the VirtualMachineManager has a new method in 5.0 to create a VirtualMachine. The following code fragment shows an example usage of this method:
    VirtualMachine vm = Bootstrap.virtualMachineManager().createVirtualMachine(conn);

    VirtualMachineManager also involves another form of the createVirtualMachine for use by LaunchingConnectors. The other form allows the LaunchingConnector to specify the java.lang.Process that represents the debuggee. See the specification for com.sun.jdi.VirtualMachineManager for further details.

The source code for an example LaunchingConnector can be found here. The Connector has a single Connector.Argument called class which specifies the class name of class to run in the target VM. The example demonstrates all of the above points including Connector.Argument, transport naming, and the use of the createVirtualMachine method.

Deploying a Connector

To deploy a Connector requires packaging the classes for the Connector implementation into a jar file along with a service configuration file that lists the fully-qualified class name of the Connector. The jar file is then deployed in a location that is visible to the system class loader.

The service configuration file that must be included in the jar file is named META-INF/services/com.sun.jdi.connect.Connector. The file simply lists the full-qualified class names of the Connector included in the jar file. Multiple Connector implementations may be included in the same jar file and in that case the class name for each Connector is listed on a separate line.

Suppose we wish to deploy a launching connector named SimpleLaunchingConnector. In order to deploy this we create a file META-INF/services/com.sun.jdi.connect.Connector similar to the following:

# Our very simple launching connector
SimpleLaunchingConnector

This service configuration file is then packaged into a jar file along with the classes that comprise the implementation of the Connector:

jar cf SimpleLaunchingConnector.jar \
    META-INF/services/com.sun.jdi.connect.Connector \
    SimpleLaunchingConnector.class

The jar file is then copied into a location that is visible to the system class loader.

Once deployed the Connector will be located by the debugger when the debugger is restarted. That is, SimpleLaunchingConnector will be included in the list of Connectors returned by VirtualMachineManager's allConnectors() method. In addition, as this is a launching connector, it will also appear on the list of launching connectors returned by the launchingConnectors() method.

Developing a TransportService

Developing a transport service requires developing two components :-

  • A concrete implementation of com.sun.jdi.connect.spi.TransportService.
  • A debuggee-side shared library that implements the jdwpTransport interface.

The development of a transport service requires a high degree of familiarity with the transport and the underlying communication protocol. A transport service essentially binds JDWP to an underlying communication protocol. The service that it provides is reliable and JDWP packets are exchanged between the debugger and debuggee without duplication or data loss. Given that packets must be exchanged in a reliable manner might mean that additional protocol support be included in the transport service over and beyond that provided by the underlying communication protocol. For example, if debugging over a raw and unreliable serial connection is required, then the transport service implementer may be required to build in error detection and recovery in the implementation to ensure that JDWP packets can be reliably transported between the debugger and the debuggee.

Assuming the details of the transport and underlying communication protocol are understood then the next step is to consider the following:

  • The TransportService's capabilities() method returns a TransportService.Capabilities to indicate the transport service's capabilities. The transport service implementer thus needs to consider:
    • Can the transport can support multiple concurrent connections to a single listener address?
    • Can timeouts be feasibly implemented when connecting, handshaking, or waiting for a connection to be established?

  • The native transport library may be used by only one, or multiple JDWP (or other) agents at the same time. If a transport supports multiple environments then each call to the jdwpTransport_OnLoad function will return a new environment pointer. If a transport only supports a single environment then second and subsequent calls to jdwpTransport_OnLoad will return an error. The transport library implementer must therefore decide if the library implementation will support one or multiple environments.

  • Addresses, or connection-endpoints, are represented by Strings. The implementer must therefore design an address scheme so that all the components of an address can be encoded into a String. For example the address and configuration of a serial port might be encoded as something like:
    /dev/ttya;9600,1

  • Design an appropriate ListenKey implementation. As a TransportService may be used to listen on multiple, yet different, addresses at the same time the listen key is used to uniquely identify each "listener".

  • Decide on an appropriate name and description for the TransportService. At start-up the VirtualMachineManager will create an Attaching and Listening Connector to encapsulate the transport service. The name and description of these Connectors will be based on the name and description of the transport service - for example, if the TransportService's name() method returns "Serial" then the Connectors created by the VirtualMachineManager will be named "SerialAttach" and "SerialListen".

Once the above have been resolved then creating a TransportService involves extending com.sun.jdi.connect.spi.TransportService and providing an implementation. The attach and accept methods return an instance of com.sun.jdi.connect.spi.Connection so an implementation of Connection is required so that the debugger can exchange JDWP packets with the debuggee.

As an example of a TransportService implementation the source code for Sun's socket transport can be found here. This is provided for reference purposes only.

To develop a native transport library requires implementing each of the functions listed in the jdwpTransport specification. The function prototypes and definitions are defined in ${java_home}/include/jdwpTransport.h.

The transport library implementer compiles and links the function implementations into a dynamic library (or equivalent). The library exports a function jdwpTransport_OnLoad function which the JDWP agent will call when the transport library is loaded. Some embedded environments don't support dynamic linking and in such environments the transport library may need to be statically linked. In that case there isn't any library loading but the jdwpTransport_OnLoad function will still be called to initialize the transport library and obtain the environment pointer.

As an example of a jdwpTransport implementation the source code for Sun's socket transport library (dt_socket) can be found here. This is provided for references purposes only.

Deploying a TransportService

A TransportService is deployed in a similar manner to a Connector. To deploy a TransportService requires packaging the classes for the TransportService implementation into a jar file along with a service configuration file that lists the fully-qualified class name of the TransportService. The jar file is then deployed in a location that is visible to the system class loader.

The service configuration file that must be included in the jar file is named META-INF/services/com.sun.jdi.connect.spi.TransportService. As per Connector deployment the configuration file may list the classes names of multiple transport service implementations in the event that the jar file includes multiple implementations.

In the case of a transport service com.sun.SerialTransportService then the service configuration file will be similar to the following :-

# Serial line transport
com.foo.SerialTransportService

This service configuration file is then packaged into a jar file along with the classes that comprise the implementation. For this example we will assume that the implementation involves a number of classes :-

jar cf SerialTransportService.jar \
    META-INF/services/com.sun.jdi.connect.spi.TransportService \
    com/foo/SerialTransportService.class \
    com/foo/SerialConnection.class \
    com/foo/SerialCapabilities.clas \
    com/foo/SerialIO.class \
    com/foo/SerialProtocol.class

As per the deployment of Connectors, the jar file is then copied into a location that is visible to the system class loader.

A TransportService may have native methods or rely on other APIs that require a native library. In that case the native library must be location that allows it be loaded using System.loadLibrary.

A native transport library is loaded by the JDWP agent. In must be located on the normal runtime library search path for the operating systems. For example, on Solaris or Linux systems it must be on search path specified by the LD_LIBRARY_PATH environment variable.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: Debugging Feedback

Sun


JPDA Connection and Invocation

Java

Connection and Invocation Details

Contents

Transports
Connectors
Sun VM Invocation Options
Debugging Plug-in Applets
Connecting with JDB
Service Provider Interfaces

Transports

A JPDA Transport is a method of communication between a debugger and the virtual machine that is being debugged (hereafter the target VM). The communication is connection oriented - one side acts as a server, listening for a connection. The other side acts as a client and connects to the server. JPDA allows either the debugger application or the target VM to act as the server. Transport implementations can allow communications between processes running on a single machine, on different machines, or either. When establishing a connection a transport addresses is used to identify the end-point of the connection. The format of a transport address depends on the type of transport.

Within JPDA the debugger application uses the Java Debug Interface (JDI) interface and the Connector abstraction to establish a connection to the target VM. The Connector used by the debugger application encapsulates the transport. On the target VM an agent supporting the JavaTM Debug Wire Protocol is used to communicate with the debugger. This agent (which may be built into the target VM or loaded from a runtime library) encapsulates the transport to communicate with the debugger.

Sun ships two transport implementations with the reference implementation: A socket transport based on TCP/IP, and a shared memory transport. The specifications do not require any specific transport implementation to exist. In addition to transports provided with the implementation the architecture includes service provider interfaces to allow additional transports be developed and deployed.

Socket Transport

The JPDA reference implementation provides a socket transport for the Solaris, Linux, and Microsoft Windows platforms. The socket transport uses a TCP/IP connection between the debugger application and the target VM. With the socket transport, the debugger application and target VM can reside either on the same machine or on different machines.

The socket transport is identified through a unique string, dt_socket. This name can be used to select the socket transport when invoking the target VM. Within the debugger application a corresponding Connector is used which encapsulates the socket transport.

In contexts where a client is attaching to a server, socket transport addresses have the format "<name>:<port>" where <name> is the host name and <port> is the socket port number at which it attaches or listens. In contexts where a server is waiting for a client to attach, the address consists of the port number alone (the host name is implicit).

Shared Memory Transport

In addition to the socket transport, the JPDA reference implementation provides a shared memory transport on the Microsoft Windows platform. The shared memory transport uses a shared memory region to exchange JDWP packets between the debugger application and the target VM. With the shared memory transport, the debugger application and target VM must reside on the same machine.

The shared memory transport is identified through a unique string, dt_shmem. This name can be used to select the socket transport when invoking the target VM. Within the debugger application a corresponding Connector is used which encapsulates the shared memory transport.

Shared memory transport addresses are simply names that can be used as Microsoft Windows file-mapping object names. The name string can consist of any combination of characters, excluding the backslash.

Connectors

A connector is a JDI abstraction that is used in establishing a connection between a debugger application (written to the JDI) and a target VM. Different JDI implementations are free to provide different connector implementations to match the transports and VMs they support. The connector interfaces are very general, to allow JDI to be used with varying connector implementations. Connectors are configured through a set of name/value pairs. Specific connectors accept different name/value pairs.

A good JDI client application will allow users to choose and configure any connector that may be present, but it can be beneficial to incorporate knowledge of specific connectors into the debugger to make their configuration a more pleasant user experience. The example JDB implementation provided with the JPDA illustrates this approach.

The JDI reference implementations provides several connectors which map to the available transport types and the modes of connection (launching, listening, and attaching). These connectors are described in the following sections. A List containing these connectors is returned by JDI method VirtualMachineManager.allConnectors(). In addition, each attaching, listening, and launching connector is contained in the lists returned by the corresponding VirtualMachineManager methods attachingConnectors(), listeningConnectors(), and launchingConnectors().

Sun Command Line Launching Connector

This connector can be used by a debugger application to launch a Sun VM or any other VM which supports the same invocation options with respect to debugging. The details of launching the VM and specifying the necessary debug options are handled by the connector. The underlying transport used by this connector depends on the platform. On Microsoft Windows, the shared memory transport is used. On Solaris and Linux the socket transport is used.

This connector is uniquely identified by the name "com.sun.jdi.CommandLineLaunch".

Sun Command Line Launching Connector Arguments
name | required? | default value | description
home | no | current java.home property value | Location of the Java 2 Runtime Environment used to invoke the Target VM.
options | no | "" | Options, in addition to the standard debugging options, with which to invoke the VM.
main | yes | "" | The debugged application's main class and command line arguments.
suspend | no | true | True if the target VM is to be suspended immediately before the main class is loaded; false otherwise.
quote | yes | "\"" | The character used to combine space-delimited text on the command line.
vmexec | yes | "java" | The VM launcher executable. This can be changed to javaw or to java_g for debugging, if that launcher is available.

Raw Command Line Launching Connector

This connector can be used by a debugger application to launch any VM. The entire command line must be specified and it is not edited in any way. The details of launching the VM with the given command line are handled by the connector. The underlying transport used by this connector depends on the platform. On Microsoft Windows, the shared memory transport is used. On the Solaris operating environment, the socket transport is used.

This connector is uniquely identified by the name "com.sun.jdi.RawCommandLineLaunch".

Raw Command Line Launching Connector Arguments
name | required? | default value | description
command | yes | "" | Full command line to invoke the target VM with the application to be debugged..
address | yes | "" | Transport address at which to listen for the newly launched target VM to connect. This value is typically part of the raw command argument as well, but this is not required if the target VM has some other means of determining the transport address to which it should connect.
quote | yes | "\"" | The character used to combine space-delimited text on the command line.

Socket Attaching Connector

This connector can be used by a debugger application to attach to a currently running target VM through the socket transport.. The target VM must have been invoked with options consistent with this connector's arguments described in the table below. For Sun VMs, the necessary options are described below.

This connector is uniquely identified by the name "com.sun.jdi.SocketAttach".

Socket Attaching Connector Arguments
name | required? | default value | description
hostname | no | local host name | Name of host machine to connect to.
port | yes | "" | Port number on the host machine to connect to.
timeout | no | "" | The timeout, in milliseconds, to use when attaching to the target VM.

Shared Memory Attaching Connector

This connector can be used by a debugger application to attach to a currently running target VM through the shared memory transport. It is available only on the Microsoft Windows platform. The target VM must have been invoked with options consistent with this connectors arguments described in the table below. For Sun VMs, the necessary options are described below.

This connector is uniquely identified by the name "com.sun.jdi.SharedMemoryAttach".

Shared Memory Attaching Connector Arguments
name | required? | default value | description
name | yes | "" | The shared memory transport address at which the target VM is listening..
timeout | no | "" | The timeout, in milliseconds, to use when attaching to the target VM

Socket Listening Connector

This connector can be used by a debugger application to accept a connection from a separately invoked target VM through the socket transport.. The target VM must be invoked with options consistent with this connector's arguments described in the table below. For Sun VMs, the necessary options are described below.

This connector can accept connections from multiple target VMs.

This connector is uniquely identified by the name "com.sun.jdi.SocketListen".

Socket Listening Connector Arguments
name | required? | default value | description
port | no | Ephemeral port number (port assigned by the TCP/IP stack) | Port number at which to listen for a connection..
localAddress | no | All addresses assigned to the host | An IP address assigned to the host
timeout | no | "" | The timeout, in milliseconds, to use while waiting for the target VM to connect

Shared Memory Listening Connector

This connector can be used by a debugger application to accept a connection from a separately invoked target VM through the shared memory transport. It is available only on the Microsoft Windows platform. The target VM must be invoked with options consistent with this connector's arguments described in the table below. For Sun VMs, the necessary options are described below.

This connector can accept connections from multiple target VMs.

This connector is uniquely identified by the name "com.sun.jdi.SharedMemoryListen".

Shared Memory Listening Connector Arguments
name | required? | default value | description
name | yes | "" | A shared memory transport address at which to listen for the target VM connection.
timeout | no | "" | The timeout, in milliseconds, to use while waiting for the target VM to connect

Process Attaching Connector

This connector can be used by a debugger application to attach to a currently running target VM that was started with the "server=y" debugging sub-option described below. The target VM must be Java SE 6 or newer.

The Process Attaching Connector does not have an associated transport. Instead, the transport is determined dynamically when an attach actually occurs. Because of this, the transport().name() method for this connector returns "local".

This connector is uniquely identified by the name "com.sun.jdi.ProcessAttach".

Process Attaching Connector Arguments
name | required? | default value | description
pid | yes | "" | The Process ID of a process to be debugged.
timeout | no | "" | The timeout, in milliseconds, to use when attaching to the target VM.

SA Core Attaching Connector

This connector can be used by a debugger application to debug a core file. It is not available on the Microsoft Windows platforms nor on the Linux Itanium platform. It is possible that the core file is corrupted to the extent that not all available debugging operations can be performed on it.

The VirtualMachine object returned by this connector's attach() method is 'read-only'. This means that the method:
vm.canBeModified()
will return false, and that the JDI client should not call any JDI methods that are defined to throw a VMCannotBeModifiedException in this case. The word size (i.e. 32 bit/64 bit) and version (e.g. 5.0, 5.1) of the debugger's Virtual Machine must be the same as that of the Virtual Machine of the process from which the core file was produced.
This connector allows multiple debugging sessions on the same core file.

This connector is uniquely identified by the name "sun.jvm.hotspot.jdi.SACoreAttachingConnector".

SA Core Attaching Connector Arguments
name | required? | default value | description
core | no | core | Pathname of the core file to debug
javaExecutable | yes | "" | Pathname of the Java executable that produced the core file.

SA PID Attaching Connector

This connector can be used by a debugger application to debug a process. It is not available on the Microsoft Windows platforms nor on the Linux Itanium platform. It is possible that the process is corrupted to the extent that not all available debugging operations can be performed on it.

The VirtualMachine object returned by this connector's attach() method is 'read-only'. This means that the method:
vm.canBeModified()
will return false, and that the JDI client should not call any JDI methods that are defined to throw a VMCannotBeModifiedException in this case.

The process to be debugged need not have been started in debug mode(ie, with -agentlib:jdwp or -Xrunjdwp). It is permissable for the process to be hung. The word size (i.e. 32 bit/64 bit) and version (e.g. 5.0, 5.1) of the debugger and debuggee must be the same. The process is suspended when this connector attaches and resumed when this connector detaches. More than one SAPIDAttachingConnector can not attach to a single process simultaneously.

This connector is uniquely identified by the name "sun.jvm.hotspot.jdi.SAPIDAttachingConnector".

SA PID Attaching Connector Arguments
name | required? | default value | description
pid | yes | "" | The Process ID of a process to be debugged.

SA Debug Server Attaching Connector

This connector can be used by a debugger application to debug a process or core file on a machine other than the machine upon which the debugger is running. It is not available on the Microsoft Windows platforms nor on the Linux Itanium platform. It is possible that the remote process/core file is corrupted to the extent that not all available debugging operations can be performed on it.

The VirtualMachine object returned by this connector's attach() method is 'read-only'. This means that the method:
vm.canBeModified()
will return false, and that the JDI client should not call any JDI methods that are defined to throw a VMCannotBeModifiedException in this case.

This connector uses RMI to communicate with a 'debug server' running on the remote machine.
Before the attach() method on this connector is called, the debug server must be started on the remote machine
and told what process or corefile is to be debugged. The following must be done on the remote machine:
  • start the RMI registry with sa-jdi.jar in the classpath:
${JAVA_HOME}/bin/rmiregistry \
-J-Xbootclasspath/p:${JAVA_HOME}/lib/sa-jdi.jar
  • start the 'debug-server' on the remote machine, specifying the process or corefile to be debugged:
${JAVA_HOME}/bin/java \
-classpath ${JAVA_HOME}/lib/sa-jdi.jar \
sun.jvm.hotspot.jdi.SADebugServer \
<pid> \
[uniqueID]

or

${JAVA_HOME}/bin/java \
-classpath ${JAVA_HOME}/lib/sa-jdi.jar \
sun.jvm.hotspot.jdi.SADebugServer \
<pathname to the java executable that produced the core file> \
<pathname of the corefile to debug> \
[uniqueID]

An alternative to the above two steps is to use the jsadebugd command to start the RMI registry and debug-server on the remote machine.

'uniqueID' is an optional string. If more than one debug server is to run at the same time on the same machine,
then each must have a different 'uniqueID' string.

In the above, JAVA_HOME must contain the pathname of a Java installation that is the same bit size (i.e. 32 bit/64 bit) and the same version (e.g. 5.0, 5.1) as the version used by the debuggee. However the debugger does not have to be the same bit size and version.

A process to be debugged need not have been started in debug mode(ie, with -agentlib:jdwp or -Xrunjdwp). It is permissable for the process to be hung. The process is suspended when the debug server attaches to it. When a debug server attached to a process is killed (by ^C or other means), the debuggee process will be resumed. Attaching more than one debug server to a corefile is permitted, but only one debug server can be attached to a process.
This connector allows multiple debugging sessions connected to the same debug server.

This connector is uniquely identified by the name "sun.jvm.hotspot.jdi.SADebugServerAttachingConnector".

SA DebugServer Attaching Connector Arguments
name | required? | default value | description
debugServerName | yes | "" | The IP address or name of the machine upon which the debug server is running. If the machine contains multiple debug servers, this name must be of the form uniqueID@IPAddress or uniqueID@hostname where 'uniqueID' is the string used to start the corresponding debug server.

Sun VM Invocation Options

This section describes the options necessary to invoke Sun VMs for debugging.

Sun's VM implementations require command line options to load the JDWP agent for debugging. From 5.0 onwards the -agentlib:jdwp option is used to load and specify options to the JDWP agent. For releases prior to 5.0, the -Xdebug and -Xrunjdwp options are used (the 5.0 implementation also supports the -Xdebug and -Xrunjdwp options but the newer -agentlib:jdwp option is preferable as the JDWP agent in 5.0 uses the JVM TI interface to the VM rather than the older JVMDI interface).

If your debugger application uses the JDI Sun Command Line Launching Connector, the connector will use the -Xdebug and -Xrunjdwp options as the Connector may be used to connect to a pre-5.0 target VM.

If the target VM is 5.0 or newer the -agentlib:jdwp option is specified as follows:

-agentlib:jdwp=<sub-options>
Loads the JPDA reference implementation of JDWP. This library resides in the target VM and uses JVM TI and JNI to interact with it. It uses a transport and the JDWP protocol to communicate with a separate debugger application. Specific sub-options are described below.

For releases prior to 5.0 the -Xdebug and -Xrunjdwp options are used:

-Xdebug
Enables debugging

-Xrunjdwp:<sub-options>
Loads the JPDA reference implementation of JDWP. This library resides in the target VM and uses JVMDI and JNI to interact with it. It uses a transport and the JDWP protocol to communicate with a separate debugger application. Specific sub-options are described below.

-agentlib:jdwp and -Xrunjdwp sub-options

The -agentlib:jdwp and -Xrunjdwp option can be further qualified with sub-options. The sub-options are specified as follows:

    -agentlib:jdwp=<name1>[=<value1>],<name2>[=<value2>]...

or

    -Xrunjdwp:<name1>[=<value1>],<name2>[=<value2>]...

The table below describes the options that can be used:

-Xrunjdwp Sub-options
name | required? | default value | description
help | no | N/A | Prints a brief help message and exits the VM.
transport | yes | none | Name of the transport to use in connecting to debugger application.
server no "n" If "y", listen for a debugger application to attach; otherwise, attach to the debugger application at the specified address.

If "y" and no address is specified, choose a transport address at which to listen for a debugger application, and print the address to the standard output stream.
address yes, if server=n
no, otherwise 		"" Transport address for the connection. If server=n, attempt to attach to debugger application at this address. If server=y, listen for a connection at this address.
timeout no "" If server=y specifies the timeout, in milliseconds, to wait for the debugger to attach. If server=n specifies the timeout, in milliseconds, to use when attaching to the debugger. Note that the timeout option may be ignored by some transport implementations.
launch no none At completion of JDWP initialization, launch the process given in this string. This option is used in combination with onthrow and/or onuncaught to provide "Just-In-Time debugging" in which a debugger process is launched when a particular event occurs in this VM.

Note that the launched process is not started in its own window. In most cases the launched process should be a small application which in turns launches the debugger application in its own window.

The following strings are appended to the string given in this argument (space-delimited). They can aid the launched debugger in establishing a connection with this VM. The resulting string is executed.

  • The value of the transport sub-option.
  • The value of the address sub-option (or the generated address if one is not given)
onthrow | no | none | Delay initialization of the JDWP library until an exception of the given class is thrown in this VM. The exception class name must be package-qualified.Connection establishment is included in JDWP initialization, so it will not begin until the exception is thrown.
onuncaught | no | "n" | If "y", delay initialization of the JDWP library until an uncaught exception is thrown in this VM. Connection establishment is included in JDWP initialization, so it will not begin until the exception is thrown. See the JDI specification for com.sun.jdi.ExceptionEvent for a definition of uncaught exceptions.
suspend | no | "y" | If "y", VMStartEvent has a suspendPolicy of SUSPEND_ALL. If "n", VMStartEvent has a suspendPolicy of SUSPEND_NONE.

Examples

-agentlib:jdwp=transport=dt_socket,server=y,address=8000
Listen for a socket connection on port 8000. Suspend this VM before main class loads (suspend=y by default). Once the debugger application connects, it can send a JDWP command to resume the VM.

-agentlib:jdwp=transport=dt_socket,server=y,address=localhost:8000,timeout=5000
Listen for a socket connection on port 8000 on the loopback address only. Terminate if the debugger does not attach within 5 seconds. Suspend this VM before main class loads (suspend=y by default). Once the debugger application connects, it can send a JDWP command to resume the VM.

-agentlib:jdwp=transport=dt_shmem,server=y,suspend=n
Choose an available shared memory transport address and print it to stdout. Listen for a shared memory connection at that address. Allow the VM to begin executing before the debugger application attaches.

-agentlib:jdwp=transport=dt_socket,address=myhost:8000
Attach to a running debugger application via socket on host myhost at port 8000. Suspend this VM before the main class loads.

-agentlib:jdwp=transport=dt_shmem,address=mysharedmemory
Attach to a running debugger application via shared memory at transport address "mysharedmemory". Suspend this VM before the main class loads.

-agentlib:jdwp=transport=dt_socket,server=y,address=8000,onthrow=java.io.IOException,launch=/usr/local/bin/debugstub
Wait for an instance of java.io.IOException to be thrown in this VM. Suspend the VM (suspend=y by default). Listen for a socket connection on port 8000. Execute the following: "/usr/local/bin/debugstub dt_socket myhost:8000".This program can launch a debugger process in a separate window which will attach to this VM and begin debugging it.

-agentlib:jdwp=transport=dt_shmem,server=y,onuncaught=y,launch=d:\bin\debugstub.exe
Wait for an uncaught exception to be thrown in this VM. Suspend the VM. Select a shared memory transport address and listen for a connection at that address. Execute the following: "d:\bin\debugstub.exe dt_shmem <address>", where <address> is the selected shared memory address. This program can launch a debugger process in a separate window which will attach to this VM and begin debugging it.

Debugging Plug-in Applets

Beginning with version 1.2.2 of the Java Plug-in, applets running under the Plug-in can be debugged. The required VM options described above can be specified in the Plug-In control panel, under the "Basic" tab, in the "Java Run-Time Parameters". The debug options under the "Advanced" tab should not be used as they will enable the old sun.tools.debug debug support. In future versions of the Plug-in, these debug options will be changed to use JPDA.

JDI launching connectors cannot be used to debug Plug-in applets.

Connecting with JDB

The example implementation of JDB provided with the JPDA, provides an illustration of the usage of JDI connectors. There are "shortcut" options to JDB which assume the use of connectors known to it (that is, connectors present in the reference implementation). It also provides a way to establish a general connection using any connector. While JDB is hardly an example of a good debugger interface, it does provide a simple example of connectors in use.

In JDB, the -attach option provides access to one of the attaching connectors in the reference implementation (shared memory on Microsoft Windows, sockets on the Solaris and Linux platforms). The -listen option provides access to one of the listening connectors in the reference implementation (shared memory on Microsoft Windows, sockets on the Solaris and Linux platforms). A class name and arguments specified directly on the command line provide access to the Sun command line launching connector.

For example:

jdb -attach myhost:8000

is an easy way to attach to a target VM with the Socket Attaching Connector (on the Solaris operating environment), and

jdb Hello 1 2 3

is an easy way to launch a target VM with the Sun Command Line Launching Connector.

However, the -connect option is also provided by JDB to handle any connector by taking an connector name and a set of arbitrary name/value argument pairs. For example the command lines above have the following equivalents.

jdb -connect com.sun.jdi.SocketAttach:hostname=myhost,port=8000
jdb -connect "com.sun.jdi.CommandLineLaunch:main=Hello 1 2 3"

These command lines are more cumbersome than the ones above, but the -connect option can be used with any connector. This kind of operation is a primitive example of how a JDI debugger can deal with any kind of connector while providing a simplified interface for dealing with common, well-known connectors.

Service Provider Interfaces

JPDA includes service provider interfaces to allow the development and deployment of connector and transport implementations. These service provider interfaces allow debugger and other tool vendors develop new connector implementations and provide addition transport mechanisms over and beyond the socket and shared memory transport provided by Sun. The service provider interfaces in JDI are specified in the com.sun.jdi.connect.spi package.

In addition to the service provider interfaces in JDI the Sun implementation also includes a transport library interface called the Java TMDebug Wire Protocol Transport Interface. A transport library is loaded by the JDWP agent in the target VM and is used to establish a connection to the debugger and to transport JDWP packets between the debugger and the VM.

Further information on the service provider interfaces can be in the document JavaTM Platform Debugger Architecture - Service Provider Interfaces.

Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: Debugging Feedback

Sun


JPDA Enhancements

Java

JavaTM Platform Debugger Architecture

Back to Home Page

Enhancements

Following is a short summary of the enhancements to JPDA that have been added in Java SE 6. The documentation for these features is available in the JDI Specification.

Not shown here are the equivalent commands in JDWP. The documentation for these features is available in the JDWP Specification.

   - JVMDI has been deleted. See its replacement, JVM TI

   - heap walking
       5024119 Add ReferenceType.getAllInstances () method to JDI.
       5089849 Add support for backtracking reference graph.

       New methods:
         VirtualMachine:
           boolean boolean canGetInstanceInfo();
           long[] instanceCounts(List refTypes);

         ReferenceType:
           ListObjectReference> instances(long maxInstances);

         ObjectReference:
           List referringObjects(long maxReferrers);

   - 5024104 Allow access to Constant Pool in ClassType
       New methods:
         VirtualMachine:
           boolean canGetClassFileVersion();
           boolean canGetConstantPool();

         ReferenceType:
           int majorVersion();
           int minorVersion();
           int constantPoolCount();
           byte[] constantPool();

   - 4836939 JDI add addSourceFileFilter to ClassPrepareRequestb
        New methods:
          VirtualMachine:
            boolean canUseSourceNameFilters();

          ClassPrepareRequest:
            void addSourceNameFilter(String sourceNamePattern);

   - 4490824 JDI: provide arguments when no debug attributes present
       New methods:

         StackFrame:
           List getArgumentValues();

   - 4195445 JDWP, JDI: Add return value to Method Exit Event
       New methods:
         VirtualMachine:
           boolean canGetMethodReturnValues();

         MethodExitEvent:
           Value returnValue();

   - 6175634 Allow early return from method
       New methods:
         VirtualMachine:
           boolean canForceEarlyReturn();

         ThreadReference:
           void forceEarlyReturn(Value value) throws InvalidTypeException,
                                              ClassNotLoadedException,
                                              IncompatibleThreadStateException;

   - 4401399 Request for breakpoints for monitor acquisitions and releases
       New methods:
         VirtualMachine
           boolean canRequestMonitorEvents();

         EventRequestManager:
           List monitorContendedEnterRequests();
           List monitorContendedEnteredRequests();
           List monitorWaitRequests();
           List monitorWaitedRequests();

       New classes:
         public interface MonitorContendedEnterRequest extends EventRequest
         public interface MonitorContendedEnteredRequest extends EventRequest
         public interface MonitorWaitRequest extends EventRequest
         public interface MonitorWaitedRequest extends EventRequest

         public interface MonitorContendedEnterEvent extends LocatableEvent
         public interface MonitorContendedEnteredEvent extends LocatableEvent
         public interface MonitorWaitEvent extends LocatableEvent
         public interface MonitorWaitedEvent extends LocatableEvent

   - 6230699  Need to be able to get the location at which a monitor was acquired
       New methods:
         VirtualMachine
           boolean canGetMonitorFrameInfo();

         ThreadReference
           List ownedMonitorsAndFrames()
                           throws IncompatibleThreadStateException;

       New classes:
         public interface MonitorInfo extends Mirror

   - 4527279: Need a better way to find out the port number on which JPDA is listening

        New Connector:
            com.sun.tools.jdi.ProcessAttach, with arguments pid and timeout
            This allows a debugger to attach to a debuggee started in
            debug mode via process id instead of transport address.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback

Sun
Java Software


JPDA Overview

Java

Java Platform Debugger Architecture

Back to Home Page

Overview

The Java Platform Debugger Architecture (JPDA) consists of two interfaces (JVM TI and JDI), a protocol (JDWP) and two software components which tie them together (back-end and front-end). JVM TI is a new interface introduced in J2SE 5.0 which replaces JVMDI. The intent is multi-fold:
  • To provide standard interfaces (for the sake of simplicity we will refer to JDWP as an interface) which allow Java programming language debugging tools to be easily written without regard to platform specifics such hardware, operating system and virtual machine implementation.
  • To describe a complete architecture for implementing these interfaces, including remote and cross-platform debugging.
  • To provide a reference implementation of this architecture.
  • To provide a highly modular architecture where the implementation and/or client of an interface can be different than the reference implementation or different from the JPDA component.

Background

See Java Platform Debugger Architecture.

Modularity

Details of the modular structure of JPDA are discussed below. In each case the standard JPDA usage is described. The reference implementation is described and alternative implementations and clients of the interface are discussed.

JVM TI Modularity

The Java Virtual Machine Tool Interface (JVM TI) describes the functionality provided by a virtual machine (VM) in order to allow debugging of Java programming language applications running under this VM. In JPDA, JVM TI is implemented by a VM and the client is the JPDA back-end. In the reference implementation of JPDA, JVM TI is implemented by the Java HotSpot VM and the client is the reference implementation of the back-end, supplied as a native shared library (jdwp.so, jdwp.dll, ...), which is shipped with the JDK.

Many VMs other than the Java HotSpot VM implement JVM TI. The reference implementation of the back-end has been ported to other platforms. And there are JVM TI clients other than the back-end, most notably agents for applications that allow debugging of both native and Java programming language code, and thus need native level control and information. We are aware of no clean-room implementations of the back-end, although this is possible - and a lot of work.

JDWP Modularity

The Java Debug Wire Protocol (JDWP) describes the format of debugging information and requests between a debuggee and a debugger. In JPDA, there is a communication channel between the front-end (in the debugger process) and the back-end (in the debuggee process) - the format of data flowing on this channel is described by JDWP. In the reference implementation of JPDA, the reference implementation of the back-end (above) provides the debuggee side of this channel, and the reference implementation of the front-end (a Java programming language component of the JDK, located in tools.jar) provides the debugger side.

JVM TI is problematic to implement in some VMs. JDWP is implemented directly in such VMs. On the client side, an application written in a language other than the Java programming language may not be an optimal candidate for using JDI. Some have chosen to be clients of JDWP.

JDI Modularity

The Java Debug Interface (JDI) provides a pure Java programming language interface for debugging Java programming language applications. In JPDA, the JDI is a remote view in the debugger process of a virtual machine in the debuggee process. It is implemented by the front-end (above) while a debugger-like application (IDE, debugger, tracer, monitoring tool, ...) is the client.

The JDI could be implemented by a system with a static view of an application. It could be implemented by a system with a mechanism utterly different than JDWP/front-end for collecting information or controlling a VM.

Walk-through

The various ways that the interfaces can be used is discussed above. This section will examine how the standard full JPDA works. The examples go into detail about specific calls and codes. It is not important to understand these -- they are present only to make the examples more concrete.

Across each interface there are two classes of activity: requests and events. Requests originate on the debugger side and include queries for information, setting of state changes in the remote VM/application, and setting of debugging state. Events originate on the debuggee side and denote changes of state in the remote VM/application.

Let's walk through an example. A user clicks on a local variable in a stack view in an IDE, requesting its value. The IDE uses the JDI to get the value, in particular it calls the getValue method, for example:

    theStackFrame.getValue(theLocalVariable)
Where theStackFrame is a com.sun.jdi.StackFrame and theLocalVariable is a com.sun.jdi.LocalVariable.

The front-end then sends this query over a communications channel (let's say a socket) to the back-end running in the debuggee process. It sends it by formatting it into a byte stream in accordance with the JDWP. In particular, it sends a GetValues command (byte value: 1) in the StackFrame command set (byte value: 16), followed by the thread ID, frame ID, etc.

The back-end deciphers the byte-stream and sends the query off to the VM through the JVM TI. In particular, let's say the requested value is an integer, the following JVM TI function call is made:

    error = jvmti->GetLocalInt(frame, slot, &intValue);
The back-end sends back across the socket, a response packet, which will include the value of intValue, and which will be formatted according to JDWP. The front-end deciphers the response packet and returns the value as the value of the getValue method call. The IDE then displays the value.

Requests to change debugging state are processed in a similar manner. For example, a request to set a breakpoint goes through the same steps -- although, of course, the JDI methods called, the JDWP commands sent, and the JVM TI functions called are different. Additionally, the front-end and back-end do more than shove data back and forth, they track and schedule activity and convert, filter, and cache information, so a breakpoint request will be processed quite differently than a get value query - but the communication sequence will be the same.

What happens when the application being debugged finally hits this breakpoint? This is where events come into play. The virtual machine sends an event across the JVM TI interface. In particular, it calls the event handling function passing the breakpoint:

The back-end has set the event handling function to be:

static void Breakpoint(jvmtiEnv *jvmti_env, JNIEnv* jni_env, jthread thread, jmethodID method, jlocation location) { ...
This back-end function starts a chain of activity which filters the event to see if it is interesting, queues it, and sends it across the socket in the JDWP format defined for breakpoint events. The front-end decodes and processes the event, eventually generating a JDI event. In particular, the JDI event is exposing it as a com.sun.tools.jdi.event.BreakpointEvent. The IDE then gets the event by removing it from the event queue:
    theEventQueue.remove()
where theEventQueue is a com.sun.jdi.event.EventQueue. The IDE will probably update its displays by making many query calls across the JDI.

Porting

Each virtual machine implementation needs its own JVM TI implementation -- a JVM TI implementation must dig deeply into VM data structures and must set hooks into the VM implementation in order to get events. Adding JVMDT to a VM without JVM TI support is a significant undertaking. Depending on the complexity of the VM and the amount of optional JVM TI implemented, it might be a three to twelve month project. Porting a VM which has JVM TI support to a new platform is primarily the work of porting the non-JVM TI portions of the VM -- JVM TI adds a comparatively small amount of work.

The reference implementation of the back-end can usually be moved to a new platform with little (a few lines) or no change to the source and then recompiled. To use a new VM on the same platform, the binary of the back-end should generally work -- although, it's not Java programming language code so you never know. Note that licensing issues are not covered by this document.

The front-end implementation is written in the Java programming language and will run on any platform or VM. However, the connector code has functionality that may need to be extended for some systems. For example, the reference implementation of the front-end includes a launcher which assumes virtual machines are launched using Java SE conventions. A user of the JDI can configure any launcher syntax he or she wants, but generally a debugger application would prefer to leave this to the JDI implementation. If a different type of communication channel is desired (serial, for example) this too would need to be added using the Service Provider Interface introduced in JDK 5.0.

Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun
Java Software


Java Print Service

 Documentation Contents
The Java Print Service API, introduced in v1.4, allows printing on all Java platforms including those requiring a small footprint, such as a J2ME profile, but also supports the java.awt.print.PrinterJob API introduced in J2SE v1.2. The Java Print Service API includes an extensible print attribute set based on the standard attributes specified in the Internet Printing Protocol (IPP) 1.1 from the IETF. With the attributes, client and server applications can discover and select printers that have the capabilities specified by the attributes. In addition to the included StreamPrintService, which allows applications to transcode data to different formats, third parties can dynamically install their own print services through the Service Provider Interface.

API Specification

The Java Print Service API consists of these four packages:

javax.print:
Provides the principal classes and interfaces for the Java Print Service API.

javax.print.attribute:
Provides classes and interfaces that describe the types of Java Print Service attributes and how they can be collected into attribute sets.

javax.print.attribute.standard:
Contains classes defining specific printing attributes.

javax.print.event:
Contains event classes and listener interfaces for monitoring print services and the progress of a specific print job.

Tutorials and Programmer's Guides

The Java Print Service User Guide ( HTML | PDF ) describes the Java Print Service in more detail and demonstrates how to use the Java Print Service API to:
  • Discover and select print services based on their capabilities
  • Specify the format of print data
  • Submit print jobs to services that support the document type to be printed.

More Information

See the Java Software websites:
  • Printing on the Java Platform
  • JSR-006: Unified Printing API
  • The Java 2D Home Page
  • The JFC Home Page

Copyright © 2002-2004 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun Microsystems, Inc
Java Software


1 - Introduction

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

CHAPTER 1

Introduction

The JavaTM Print Service (JPS) is a new Java Print API that is designed to support printing on all Java platforms, including platforms requiring a small footprint, but also supports the current JavaTM 2 Print API. This unified Java Print API includes extensible print attributes based on the standard attributes specified in the Internet Printing Protocol (IPP) 1.1 from the IETF Specification, RFC 2911. With the attributes, client and server applications can discover and select printers that have the capabilities specified by the attributes. In addition to the included StreamPrintService, which allows applications to transcode print data to different formats, a third party can dynamically install their own print services through the Service Provider Interface.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


1 - Introduction

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

History of Printing on the Java Platform

Basic printing support for the Java platform was first introduced in the Java Development Kit, version 1.1 in 1997. The JDK 1.1 printing API provided developers with a basic framework for printing the user-interface content from client applications. JDK 1.1 printing, also called the AWT Printing API, was designed around the java.awt.PrintJob class, which encapsulates a printing request. The PrintJob class creates a subclass of Graphics, which implements the rendering calls to image the page.

In 1998, the JDK 1.2 advanced printing on the Java platform with the java.awt.print package by allowing applications to print all Java 2D graphics, which includes 2D graphics, text, and images.

For the JDK version 1.3, the JobAttributes and PageAttributes classes were introduced to AWT printing so that client applications could specify the properties of a print job and the attributes of a page.

The two APIs primarily support page imaging, which is the rendering and formatting of a page and is one component of a printing subsystem. Although a client can choose a printer from a print dialog and can specify printing attributes using JobAttributes and PageAttributes, neither the AWT nor Java 2D printing APIs support discovery of printers based on their capabilities, which is another key component of any printing subsystem. For more details on the history of printing on the Java platform refer to Printing on the Java Platform.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


1 - Introduction

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

How Applications Use the Java Print Service

A typical application using the Java Print Service API performs these steps to process a print request:

  1. Obtain a suitable DocFlavor, which is a class that defines the format of the print data.
  2. Create and populate an AttributeSet, which encapsulates a set of attributes that describe the desired print service capabilities, such as the ability to print five copies, stapled, and double-sided.
  3. Lookup a print service that can handle the print request as specified by the DocFlavor and the attribute set.
  4. Create a print job from the print service.
  5. Call the print job's print method.
The application performs these steps differently depending on what and how it intends to print. The application can either send print data to a printer or to an output stream. The print data can either be a document in the form of text or images, or a Jav a object encapsulating 2D Graphics. If the print data is 2D graphics , the print job can be represented by either a DocPrintJob or a PrinterJob. If the print data is a document then a DocPrintJob must be used.

The combinations of printing methods and print data formats yield a choice of six printing mechanisms:

  • Print a document to a printer by using a DocPrintJob and an implementation of PrintService
  • Stream a document to an output stream by using a DocPrintJob and a StreamPrintService
  • Print 2D graphics to a printer by using a DocPrintJob and an implementation of PrintService
  • Stream 2D graphics to an output stream by using a DocPrintJob and a StreamPrintService
  • Print 2D graphics to a PrintService using java.awt.print.PrinterJob
  • Stream 2D graphics to a StreamPrintService using java.awt.print.PrinterJob
The Attributes chapter and the Specifying Document Types chapter describe how to create an attribute set and specify document types for use with any of the print mechanisms. The Printing and Streaming Documents chapter discusses printing and streaming documents using DocPrintJob. The Printing and Streaming 2D Graphics chapter explains printing and streaming 2D graphics using both DocPrintJob and PrinterJob.

A Basic Example

Most applications using the Java Print Service API will probably send a document directly to a printer, which the following code sample demonstrates:

// Input the file
FileInputStream textStream;
try {
    textstream = new FileInputStream("file.TXT");
} catch (FileNotFoundException ffne) {
}
if (textstream == null) {
    return;
}
// Set the document type
DocFlavor myFormat = DocFlavor.INPUT_STREAM.TEXT_PLAIN_ASCII;
// Create a Doc
Doc myDoc = new SimpleDoc(texttream, myFormat, null);
// Build a set of attributes
PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
aset.add(new Copies(5));
aset.add(MediaSize.ISO_A4);
aset.add(Sides.DUPLEX);
// discover the printers that can print the format according to the
// instructions in the attribute set
PrintService[] services =
    PrintServiceLookup.lookupPrintServices(myFormat, aset);
// Create a print job from one of the print services
if (services.length > 0) {
    DocPrintJob job = services[0].createPrintJob();
    try {
        job.print(myDoc, aset);
    } catch (PrintException pe) {}
}
Although this sample only demonstrates one of the six ways to print, the other printing mechanisms work in a similar way. The rest of this guide discusses each piece of the printing process and all the printing mechanisms in more detail

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


1 - Introduction

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

What the Java Print Service API Offers

The Java Print Service API unifies and extends printing on the Java platform by addressing many of the common printing needs of both client and server applications that are not met by the current Java printing APIs.

In addition to supporting the current Java 2D printing features, the Java Print Service offers many improvements, including:

  • Both client and server applications can discover and select printers based on their capabilities and specify the properties of a print job. Thus, the JPS provides the missing component in a printing subsystem: programmatic printer discovery.
  • Implementations of standard IPP attributes are included in the JPS API as first-class objects.
  • Applications can extend the attributes included with the JPS API.
  • Third parties can plug in their own print services with the Service Provider Interface.

    • CONTENTS | PREV | NEXT
    Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


1 - Introduction

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

Java Print Service Architecture

The Java Print Service API consists of four packages: javax.print, javax.print.attribute, javax.print.attribute.standard, and javax.print.event.

The javax.print Package

The javax.print package is the main package of the API. It contains classes and interfaces that you use to:

  • Discover Print Services
  • Specify the print data format
  • Create print jobs from a print service
  • Send the print data to a printer or a stream

Discover Print Services

An application invokes the static methods of the abstract class PrintServiceLookup to locate print services that have the capabilities to satisfy the application's print request. For example, to print a double-sided document, the application first needs to find printers that have the double-sided printing capability.

An implementation of the PrintService interface represents an actual printer that might be returned from an implementation of PrintServiceLookup. The PrintService can be queried to determine its capabilities by invoking one of the many methods that return the print service's supported attributes. The Locating Services section of the Printing and Streaming Documents chapter discusses using PrintService and PrintServiceLookup.

The JDK includes PrintServiceLookup implementations that can locate the standard platform printers. To locate other types of printers, such as IPP printers or JINI printers, a print-service provider can write implementations of PrintServiceLookup. The print-service provider can dynamically install these PrintServiceLookup implementations using the SPI JAR file specification.

Rather than sending data to a printer, an application can also print the data to an output stream using a StreamPrintService, which allows the application to convert the data to different formats. To obtain a StreamPrintService, an application uses the lookup methods of the StreamPrintServiceFactory abstract class. This class is similar to that of the PrintServiceLookup class in that it also discovers print services. The chapter Printing and Streaming Documents describes using StreamPrintServiceFactory and StreamPrintService. A StreamPrintService can also be used to send 2D graphics to an output stream. See Printing and Streaming 2D Graphics for more details.

Specify the Print Data Format

The DocFlavor class represents the print data format, such as JPEG or PostScript. A DocFlavor object consists of a MIME type describing the format, and a representation class name, such as java.io.InputStream, that indicates how the document will be delivered to the service. As a convenience, the JPS API also includes pre-defined DocFlavor objects representing common data formats. The Specifying Document Types chapter describes in more detail how to use DocFlavor objects.

Create Print Jobs

When an appropriate print service is found, an application creates a print job from it. The print job is represented by the DocPrintJob class, which provides the actual print method. Before calling print, the application creates a Doc object to encapsulate the print data and the print request attributes, which are defined in the javax.print.attribute and javax.print.attribute.standard packages. The chapter Printing and Streaming Documents discusses using Doc and DocPrintJob. An application that is using the Java Print Service to print 2D Graphics can use either the PrinterJob class or the DocPrintJob class. The chapter Printing and Streaming 2D Graphics discusses using the Java Print Service to print 2D Graphics.

The Attribute Packages

The javax.print.attribute and javax.print.attribute.standard packages define print attributes, which describe a capability of a print service, a charactaristic of a document, an instruction for processing a document or an entire print job, or the state of a print job or printer.

The javax.print.attribute package describes the types of attributes and how they can be collected into sets. The Attribute interface is the superinterface for all attributes. The javax.print.attribute package includes classes and interfaces defining the five different kinds of attributes, each of which describes the capabilities of one piece of the printing process. For example, the PrintRequestAttribute interface defines attributes that clients use to describe the characteristics of a print job, which might include the number of copies to print.

The javax.print.attribute.standard package enumerates all of the standard attributes supported by the API, most of which are implementations of attributes specified in the IPP specification. The Attributes chapter discusses the attribute API in more detail.

The javax.print.event Package

The javax.print.event package contains classes that allow applications to register for events on print jobs and print services. Read the Registering for Events section for more information on registering for print job events.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


2 - Attributes

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

Standard Attributes

The javax.print.attribute.standard package enumerates all of the standard attributes in the Java Print Service API. Most of these standard attributes are taken from the attributes defined in the IETF Internet Printing Protocol (IPP) 1.1 specification. This means that each IPP-compliant attribute class(category) defined in package javax.print.attribute.standard corresponds to an IPP attribute category, and the name (as returned by getName) is the actual IPP name for the category. The class names also usually reflect the IPP name as closely as the coding conventions of the Java programming language permit. Furthermore the values defined for a category are the same as the IPP values. IPP compatibility of each attribute category is documented in the API specification.

This section describes the attributes that developers will probably use most frequently. The more commonly-used attributes, including the ones listed here, implement PrintRequestAttribute because printing applications will usually specify how an entire print job should be printed, which is the role of a PrintRequestAttribute.

OrientationRequested

The OrientationRequested attribute category allows you to specify the orientation of the imaging on the paper. The possible attribute values are: PORTRAIT, LANDSCAPE, REVERSE_PORTRAIT, and REVERSE_LANDSCAPE. OrientationRequested.PORTRAIT is usually the default value. This code snippet demonstrates adding an OrientationRequested attribute to a set:

aset.add(OrientationRequested.REVERSE_PORTRAIT);
The OrientationRequested object is a type-safe enumeration encapsulating String values, which correspond to the possible orientations. These values are the actual IPP keywords.

Some pre-formatted document types, such as "Postscript", might not be able to support this attribute category because pre-formatted document types embed printer language commands that are interpreted by the printer, and these commands take precedence over a client request.

Clients can discover the supported orientation values for a particular print service by calling:

PrintService.getSupportedAttributeValues(OrientationRequested.class, ...).
This method returns an array of type OrientationRequested enumerating the supported values.

Copies

The Copies attribute category allows you to specify the number of copies to print. The Copies class encapsulates an integer representing the number of copies requested. This code snippet demonstrates adding a Copies attribute, set to five copies, to an attribute set:

aset.add(Copies(5));
Clients can discover the range of copies that a print service supports by calling :

PrintService.getSupportedAttributeValues(Copies.class, ...)
This method returns a CopiesSupported object, which encapsulates a range of integer values representing the range of copies that the service can handle. Calling getSupportedAttributeValues with CopiesSupported instead of Copies always returns null because the CopiesSupported object does not implement the PrintRequestAttribute interface, and so a client cannot specify a CopiesSupported attribute in a print request.

This code sample demonstrates discovering if a print service supports printing 5 copies and adding a Copies attribute with a value of 5 copies to an attribute set:

CopiesSupported copSupp =
    (CopiesSupported) service.getSupportedAttributeValues(Copies.class, null,
                                        null);
if (copSupp != null && copSupp.contains(5)) {
    requestAttrSet.add(new Copies(5));
} else { ...
}

Media

Media is the IPP attribute that identifies the medium on which to print. The Media attribute is an important attribute to understand, butis relatively complex.

The Java Print Service API defines three subclasses of the abstract class Media to reflect the overloaded Media attribute in the IPP specification: MediaSizeName, MediaName and MediaTray. All the Media subclasses have the Media category, for which each subclass defines different standard attribute values. For example, a MediaTray object can specify a value of MANUAL for the Media attribute to indicate that the document must be printed on paper from the printer's manual tray. This code snippet demonstrates adding a Media attribute to a set:

aset.add(MediaTray.MANUAL);

The value of the Media attribute is always a String, but because the attribute is overloaded, its value determines the type of media to which the attribute refers. For example, the IPP pre-defined set of attribute values include the values "a4" and "top-tray". If Media is set to the value "a4" then the Media attribute refers to the size of paper, but if Media is set to "top-tray" then the Media attribute refers to the paper source. Because the String attribute value can refer to such diverse types of media, an application can extend the attribute set to include values such as "company-letterhead" or "yellow letter paper". Of course, to extend the Media attribute in this way, an application must discover a print service that is configured to print with this media.

In most cases, applications will use either MediaSizeName or MediaTray. The MediaSizeName class enumerates the media by size. The MediaTray class enumerates the paper trays on a printer, which usually include a main tray and a manual feed tray. The IPP 1.1 specification does not provide for specifying both the media size and the media tray at the same time, which means, for example, that an application cannot request size A4 paper from the manual tray. A future revision of the IPP specification might provide for a way to request more than one type of media at a time, in which case the JPS API will most likely be enhanced to implement this change.

The JPS API also includes two additional media-related Attribute classes that are not IPP attributes: MediaSize and MediaPrintableArea.

MediaSize

MediaSize is not a request attribute; it is an enumeration of paper dimensions and a mapping to MediaSizeName instances. Each MediaSizeName instance usually has a MediaSize object associated with it so that clients can obtain the dimensions of the paper that the MediaSizeName instance defines. To determine the dimensions of the MediaSizeName instance, call:

MediaSize size = MediaSizeName.getMediaSizeForName(paper);

MediaPrintableArea

MediaPrintableArea is used in a print request in conjunction with a compatible Media to specify the area of the paper on which to print. Printer hardware usually defines the printable area of a page, which is rarely the entire page. For this reason, an application needs to determine what printable area a printer defines for a particular size media to ensure that the print data can fit within this area.

For example, to determine the supported printable area for 5" x 7" paper, the application needs to choose a media size attribute value that corresponds to this size paper and then query the print service with the media size:

PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
aset.add(MediaSizeName.NA_5X7);
MediaPrintableArea printableArea =
(MediaPrintableArea)service.
    getSupportedAttributeValues(MediaPrintableArea.class, null, aset);
The returned value indicates the largest printable area that can be supported by that printer for that paper size.

Destination

The Destination attribute allows you to redirect your print data to a file rather than sending it to a printer device. The "print-to-file" option is very common in user dialogs, but the spooled data is not always usable because it might be a device-specific raster that can only be interpreted by the device from which it was redirected. For this reason, the Java Print Service API requires that the client query the print service to determine if it can redirect the output to a file. The service might not support the category at all, or it might support only particular values. For example, since the JPS API can be used in an network environment, in which the formatting of print data does not occur on the host computer, specifying a local file for output might not be possible because the service formatting the data might not have access to the local filesystems of the client. The Destination attribute takes a URL as the value of the destination, which allows a network printer to use a protocol such as ftp to upload formatted print data. However, most printers that support this attribute will run as part of a local environment and can accept the "file:" protocol URL. This code snippet redirects the output to a file called out.prn on the c: drive:

aset.add(new Destination("file:c:\out.prn"));

SheetCollate

The SheetCollate attribute allows you to specify whether or not your print job is collated when you are printing more than one copy of a multi-page document. For example, the pages of a 3-page, 2-copy collated job will print as (1,2,3,1,2,3), but the pages of the same document submitted in a 2-copy uncollated job will be printed as (1,1,2,2,3,3). This attribute is not in version 1.1 of the IPP specification, but it is very useful and most printers support it. This code snippet demonstrates specifying a collated job:

aset.add(SheetCollate.COLLATED);

Sides

Some printers, particularly high-end printers, can print on both sides of the paper. The Sides attribute allows applications to specify two-sided printing instead of the usual default of single-sided printing. Two-sided printing is sometimes referred to as "duplex" or "tumble" printing. These two values are differentiated by the orientation of the output. The Java Print Service API refers to duplex as "two sided long edge" and tumble as "two sided short edge". Read the API specification for Sides for further explanation. This code snippet specifiesthat a job print the documents two-sided:

aset.add(Sides.DUPLEX);

Fidelity

The Fidelity attribute is an IPP boolean attribute that represents whether or not a print job should be rejected if the print service does not support any attribute specified in the print request. Fidelity is not an attribute many developers will need to consider, but it is an important attribute in the context of the JPS API. The default value is FIDELITY_FALSE, which indicates that a print job should not be rejected if the print service does not support an attribute specified in the print request. For example, if an application specifies an orientation of reverse landscape, but the printer does not support reverse landscape, the job is rejected if fidelity is true, but if fidelity is false then the printer might substitute a reasonable alternative, such as the landscape orientation. The Fidelity attribute allows applications to decide whether to only print the document exactly as specified or to print it even though the printer might not support all attributes. This code snippet specifies that a job should be rejected if the printer does not support the requested attributes:

aset.add(Fidelity.FIDELITY_TRUE);
For the cases in which fidelity is important, the Java Print Service API provides many tools for applications to query exactly what can be supported for a particular print request. See the various query methods on the PrintService interface.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


2 - Attributes

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

Attribute Roles

When submitting a print job to a printer, the client provides the attributes describing the characteristics of the print data, such as the document name, and how the print data should be printed, such as double-sided, five copies. If a print job consists of multiple pieces of print data, different pieces might have different processing instructions, such as 8 x 11 inch media for the first document, and 11 x 17 inch media for another document.

Once the printer starts processing the print job, additional information about the job becomes available, which might include: the job state (such as completed or queued) and the number of pages printed so far. These pieces of information are also attributes. Attributes can also describe the printer itself, such as: the printer name, the printer location, and the number of jobs queued.

The Java Print Service API defines these different kinds of attribute roles with five subinterfaces of Attribute:

  • PrintRequestAttribute is used by an application to represents a setting applied to an entire print job and to specify how the entire print job should be printed.
  • DocAttribute is used by an application to specify a characteristic of a single document and the print job settings to be applied to the document.
  • PrintJobAttribute is used by a print service to report how a job is being printed. These values will usually be identical the requested attribute values. However, if the printer does not support the value of a print request attribute then the corresponding print job attribute contains a different value that is supported by the printer
  • PrintServiceAttribute is used by a print service to report the status of the print service.
  • SupportedValuesAttribute is used by a print service o indicate the range of values supported for a request attribute. For example, a printer might support only a certain range of copies. When a print service is queried for the supported range of copies, it returns this information in a CopiesSupported object, which implements SupportedValuesAttribute.
Many attributes can be members of more than one role. For example, the Media attribute belongs to the doc, print job, and print request roles because the Media attribute can describe the paper size, the paper tray, or paper type. In fact, most doc attributes are also request attributes, and all request attributes are also job attributes.

The next section describes how to collect attributes together into attribute sets, which also have roles.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


2 - Attributes

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

CHAPTER 2

Attributes

When sending print data to a printer, a client also provides instructions on how to print the data, such as: what media (paper) to use and how many copies to print. The client specifies these processing instructions using the attribute definitions of the JavaTM Print Service API.

The Java Print Service API includes two packages that define attributes: javax.print.attribute and javax.print.attribute.standard. The javax.print.attribute package contains the interfaces and classes that describe the types of attributes and how they are collected into sets. The javax.print.attribute.standard package enumerates all of the standard attributes in the API. Most of the attribute definitions in the JPS API are implementations of the standard and extensible attributes defined by the Internet Printing Protocol (IPP) Specification from the IETF.

This chapter describes the attribute definitions of the JPS API in more detail.The Attribute Categories and Values section explains what an attribute is according to the JPS. The Attribute Roles section describes the type of attributes. The Attribute Sets section describes how the attributes are collected into sets. The Standard Attributes section describes some of the more-commonly used attributes defined in the javax.attribute.standard package.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


2 - Attributes

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

Attribute Sets

A client usually needs to provide more than one processing instruction when submitting a print job. For example, the client might need to specify an A4 media and a landscape orientation. To send more than one processing instruction to the printer, the client collects the attributes representing the instructions into an attribute set, which the Java Print Service API represents with the AttributeSet interface.

The AttributeSet interface is similar to the java.util.Map interface: it provides a map of keys to values, in which each key is unique and can contain no more than one value. However, the AttributeSet interface is designed to specifically support the needs of the Java Print Service API. An AttributeSet requires that:

  • Each key in an AttributeSet corresponds to a category, and the value of the key can only be one of the attribute values that belong to the category represented by the key. Thus, unlike a Map, an AttributeSet restricts the possible values of a key: an attribute category cannot be set to an attribute value that does not belong to that category.
  • Only attributes implementing the Attribute interface can be added to the attribute set.
  • Only one attribute from a particular category can exist in an AttributeSet. For example, if an attribute set already contains a Media attribute, adding another Media attribute overwrites the first one.
Like a single attribute, an attribute set has a role. The roles are defined by the AttributeSet subinterfaces, which parallel the Attribute subinterfaces mentioned in the Attribute Roles section. The AttributeSet subinterfaces are: PrintRequestAttributeSet, PrintJobAttributeSet, DocAttributeSet, and PrintServiceAttributeSet. The role of the attribute set determines what kind of attributes it contains: a print request attribute set can contain only print request attributes.

The Java Print Service API includes HashAttributeSet as a concrete implementation of the AttributeSet interface, but developers can provide their own implementation. Rather than using HashAttributeSet directly, applications will more often use one of the subclasses of HashAttributeSet, which are: HashPrintRequestAttributeSet, HashPrintJobAttributeSet, HashDocumentAttributeSet, and HashPrintServiceAttributeSet. These subclasses implement the corresponding AttributeSet subinterfaces. For example PrintRequestAttributeSet extends AttributeSet, and HashPrintRequestAttributeSet is the concrete implementation of PrintRequestAttributeSet. An attribute set created with HashPrintRequestAttributeSet or any implementation of PrintRequestAttributeSet can contain only request attributes.

Unlike its subclasses, a HashAttributeSet can contain any kind of attribute. An application uses a HashAttributeSet directly when it needs a set to contain more than one kind of attribute. One example is the set returned by the getUnsupportedAttributes method of PrintService. The unsupported attributes returned might belong to more than one attribute role.

As with single attributes, applications will more often create request attribute sets because specifying print requests is the printing application's primary function. To create a request attribute set, use one of the constructors from the HashPrintRequestAttributeSet class:

PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
The next section describes some of the more commonly-used attributes that you can add to a set.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


2 - Attributes

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

Attribute Categories and Values

Every printer has a set of capabilities, such as the ability to print on different paper sizes or the ability to print more than one copy. Each of the capabilities has a range of values. For example, a printer's orientation capability might have this range of values: [landscape, portrait]. For each print request, the capability is set to one of these possible values. The Java Print Service API uses the term attribute category to refer to a printer capability, such as orientation, and the term attribute value to refer to the value of the capability, such as landscape.

In the Java Print Service API, an attribute category is represented by a Java class implementing the Attribute interface, and attribute values are instances of such a class or one of its subclasses. For example, to print 5 copies of a job, an application constructs an instance of the Copies class with the value of 5 and uses the Copies instance to specify the print job. The Copies class represents the attribute category, and the Copies instance represents the attribute value. Because the attribute value is encapsulated as a Java object, the attribute value implies its attribute category, and so an attribute value is usually referred to simply as an attribute. The category and value constitute a key-value pair, which you can add to a set along with other attributes. See Attribute Sets for more information

The Attribute interface defines just two methods: getName and getCategory. The getName method returns a String name for the attribute category. The getCategory method returns the class that first implements that category. To ensure that all implementations of a particular category report the same name and class, subclasses should not override the getName or getCategory methods.

To determine what attribute categories and values are supported by a printer, use the query methods defined in the PrintService interface. A print request does not need to specify attribute values for all of the target printer's supported attribute categories: each supported attribute category has a default value. For example, a printer might support printing up to 999 copies of a job, but if a print request does not specify the number of copies, the printer almost always prints a default of just 1 copy.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


2 - Attributes

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

How to Specify Attributes

Whether you are printing or streaming data, you specify attributes in the same way. You will usually use PrintRequestAttribute more often than the other kinds of attributes because print request attributes specify the settings for an entire print job. Bec ause you will most likely want to specify more than one attribute for a particular job, you need to create an attribute set. This sample demonstrates creating a PrintRequestAttributeSet that instructs the service to use A4 media to print five copies of th e job using both sides of the paper:

PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
aset.add(new Copies(5));
aset.add(MediaSize.ISO_A4);
aset.add(Sides.DUPLEX);
After creating an attribute set, you will pass it to the print job's print method, along with the DocFlavor. The Specifying Document Types discusses using DocFlavor. The Printing and Streaming Documents chapter discusses how to print. The next section explains some of the more commonly-used attributes in more detail.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


2 - Attributes

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

Uses of JPS Attributes

Unlike attributes of previous Java printing APIs, the Java Print Service attributes can be used in both the program and from the user dialog. Applications can specify as little as needed about how a job should be printed and can inspect the selections made by end users in user dialogs.

The JPS attributes are designed to be extensible. An AttributeSet can contain anything that properly implements the Attribute interfaces, which means that the set of standard attributes can evolve and still be compatible with future JDK versions, and implementors of services can extend attributes in two ways:

  • Using their own subclasses of a standard attribute category to support additional values of that category.
  • Creating new attribute categories.
Demonstrating attribute usage from the user dialog requires providing a user interface, which is beyond the scope of this user guide. Likewise, extending JPS attributes is a task for service providers, and is not included as an example in this version of the user guide. However, the Printing a Document chapter explains a simple printing application, which covers the basics of using the JPS attributes as described in this chapter.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


3 - Specifying Document Types

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

How to Use DocFlavor

These steps illustrate the role of the DocFlavor in a typical application:

  1. A client determines the format of the print data and decides how to present the data to the printer. The client then creates or obtains a DocFlavorrepresenting the format:DocFlavor flavor = DocFlavor.INPUT_STREAM.GIF;
  2. The client uses the DocFlavor to find printers that can understand the format specified by the DocFlavor and has the capabilities specified in the client's attribute set:PrintService[] services = PrintServiceLookup.lookupPrintServices(flavor, aset);
  3. From a print service, the client creates a print job, represented by a DocPrintJob object:DocPrintJob printJob = services[0].createPrintJob();
  4. The client creates a Doc representing the document to be printed:Doc doc = new InputStreamDoc("duke.gif", flavor);
  5. The client prints the document by calling the print method of the DocPrintJob object:printJob.print(doc, aset);When the client passes the Doc object to the print method, the DocPrintJob object obtains the print data from the Doc object and determines the doc flavor that the client can supply. The doc flavor's representation class is a conduit for the DocPrintJob to obtain a sequence of characters or bytes from the client.
The Printing and Streaming Documents chapter demonstrates a complete printing application.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


3 - Specifying Document Types

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

Importance of Character Encoding

If a MIME type for byte print data does not include a charset parameter, indicating the encoding, the Java Print Service assumes a character set of US-ASCII. This behavior is different than that of the Java runtime, which always assumes the default encodi ng for the user's locale on the underlying operating system, which might be different than US-ASCII.

Every instance of the JavaTM Virtual Machine* has a default character encoding determined during virtual-machine startup that usually depends upon the locale and charset used by the underlying operating system. In a distributed environment, two JVM's might n ot share the same default encoding. Thus clients who want to stream platform-encoded text data from the host platform to a Java Print Service instance must explicitly declare the charset and not rely on defaults.

For these reasons, applications that stream text data should always specify the charset in the MIME type. To specify a MIME type, an application needs to determine the host platform's encoding, which it does by calling the DocFlavor.hostEncoding metho d. The MIME type returned from this method is guaranteed to be understood by the current JVM.

See character encodings for more information on the character encodings supported on the Java platform.

*As used on this web site, the terms "Java Virtual Machine" or "JVM" mean a virtual machine for the Java platform.
CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


3 - Specifying Document Types

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

CHAPTER 3

Specifying Document Types

From the user's perspective, a document can take many different forms, including: a PDF file, an image from a digital camera, an email, a word processor document, or a web page. Before printing a document of a particular format, the client needs to ensure that the printer can understand the format. Sometimes a printer can directly print documents of a given format: photo printers can directly print images of various formats, and PostScriptTM printers can directly print a PostScriptTM document. However, there are few printers that can directly print a wide range of formats; most printers require some higher-level software support to translate the source document into a format they can print.

A printing API needs to provide a way to describe document types so that:

  • The printer can report what formats it can print.
  • The client can describe the format of the data it wants to print.
  • The client can describe the encoding of text data.
The JavaTM Print Service API describes document types using the DocFlavor class. A DocFlavor is comprised of:

  • A MIME type that tells the printer how to interpret the data.
  • A representation class name indicating the Java class that describes how the data is sent to the printer.
To describe an HTML page to a print service, a client might choose to use a DocFlavor with a MIME type string of "text/html; charset=utf-16" and a representation class name of "java.io.InputStream". The client can obtain this DocFlavor in one of two ways:

  • Construct a DocFlavor:DocFlavor htmlStreamFlavor = new DocFlavor("text/html; charset=utf-16", "java.io.InputStream");
  • Use the pre-defined instance that represents this type of DocFlavor:DocFlavor.INPUT_STREAM TEXT_HTML_UTF_16 . The Java Print Service API provides a set of pre-defined instances for common doc flavors as a convenience.
Because the HTML page contains text data, the MIME type String includes the text encoding, which is charset=utf-16 in this example. The client is responsible for accurately describing the print data to the print service. The section, Client-Formatted Print Data, explains how to properly construct a DocFlavor to accomplish this. If the text encoding is not included in the MIME type, unexpected results can occur, as explained in the section, Importance of Character Encoding. The client can allow the service to determine the format of data that the client supplies as a Java object. The Service-Formatted Print Data section describes using a DocFlavor to represent service-formatted print data.

Keep in mand that, just because the DocFlavor API has a pre-declared doc flavor, this doesn't mean that an implementation of the particular flavor is available. For example, even if you use the pre-defined DocFlavor representing HTML text in UTF-16, you won't be able to print the HTML unless you have a print service that supports printing HTML. Again, it is the user's responsibility to ensure that a printer supports a particular format.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


3 - Specifying Document Types

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

Service-Formatted Print Data

Rather than the client describing the print data format with a MIME type, the client can supply a Java object from which a print service determines the print data format. For example, the Java object can encapsulate a PostScriptTM document. Instead of the client explicitly describing the document as PostScriptTM with a MIME type, the client can wrap a reference to the document in a Java object, which the print service inspects to determine that the format is PostScriptTM. Because the print data is delivered to the print service through the Java object, the class that the Java object implements is the representation class.

The DocFlavor class has an inner class called DocFlavor.SERVICE_FORMATTED that contains DocFlavor object constants representing service-formatted print data. Each of these constants has a MIME type of "application/x-java-jvm-local-objectref", which indicates that the client will supply a reference to a Java object implementing the interface named as the representation class.

The three DocFlavor object constants contained in DocFlavor.SERVICE_FORMATTED each represent a common representation class name used with service-formatted print data:

  • DocFlavor.SERVICE_FORMATTED.PAGEABLE:The client supplies an object that implements thejava.awt.print.Pageable interface, which represents a set of pages to be printed. The printer calls methods in that interface to obtain the pages to be printed, one by one. For each page, the printer supplies a graphics context and prints whatever the client draws in that graphics context.
  • DocFlavor.SERVICE_FORMATTED.PRINTABLE:The client supplies an object that implements the java.awt.print.Printable interface, which is responsible for drawing the contents of each page. The printer calls methods in that interface to obtain the pages to be printed, one by one. For each page, the printer supplies a graphics context and prints whatever the client draws in that graphics context.
  • DocFlavor.SERVICE_FORMATTED.RENDERABLE_IMAGE:The client supplies an object that implements interface java.awt.image.renderable.RenderableImage, which represents an image that can be manipulated in a rendering-independent manner and can be rendered to various contexts, such as a printer, without compromising quality. The printer calls methods in the interface to obtain the image to be printed.
    • As stated in the Introduction, applications that wrap 2D graphics into a Java object can use the service-formatted print data DocFlavor constants. See Printing and Streaming 2D Graphics for more information.

    CONTENTS | PREV | NEXT
    Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


3 - Specifying Document Types

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

Client-Formatted Print Data

The client uses the DocFlavor to describe the print data format and to indicate how the data will be delivered to the print service. The MIME type specifies the data format. The representation class name specifies how the data will be delivered to the printer.

The DocFlavor class has an inner class for each of the common representation class names. Each inner class contains a set of DocFlavor object constants representing formats that can be delivered using the representation class. For example, an input stream can stream many different kinds of print data formats, including GIF, represented by DocFlavor.INPUT_STREAM.GIF, and PostScriptTM, represented by DocFlavor.INPUT_STREAM.POSTSCRIPT. If one of the DocFlavor object constants accurately describes the format of a given piece of print data, the client can use this constant instead of constructing a DocFlavor.

If the appropriate DocFlavor is not already defined in the JPS API, a client can create it with the DocFlavor constructor. The client can use the MIME types and representation class names explained in the next two sections to construct the DocFlavor.

MIME Types for Preformatted Data

The four most common types of preformatted data are: text data, page description language documents, image data, and autosense print data. This section describes each one of these data types and lists their corresponding MIME types.

Text Data

Preformatted text data is usually provided in a character-oriented representation class, such as a character array, String, or Reader, or in a byte-oriented representation class, such as a byte array, input stream, or URL. Plain text and HTML are two common forms of preformatted text data. You can use these MIME type strings to represent the format of the data when constructing a DocFlavor:

MIME type Format of data

"text/plain"

Plain text in the default character set US-ASCII

"text/plain;charset=xxx"

Plain text in character set xxx

"text/html"

HyperText Markup Languge in the default character set (US-ASCII)

"text/html;charset=xxx"

HyperText Markup Languge in the character set xxx

Page Description Language Documents

Preformatted page description language (PDL) documents are usually provided in a byte-oriented representation class, such as byte array, InputStream, or URL. You can use these MIME type strings to represent the format of the data when constructing a DocFlavor:

MIME type Format of data

"application/pdf"

Portable Document Format document

"application/postscript"

PostScriptTM document

"application/vnd.hp-PCL"

Printer Control Language document

Image Data

Preformatted image data is provided in a byte-oriented representation class: byte array, InputStream, or URL. You can use these MIME type strings to represent the format of the data when constructing a DocFlavor:

MIME type Format of data
"image/gif"

Graphics Interchange Format image

"image/jpeg"

Joint Photographic Experts Group image

"image/png"

Portable Network Graphics image

Autosense Print Data

Preformatted autosense print data allows the printer to decide how to interpret the print data. This type of data is usually provided in a byte-oriented representation class. You can use this MIME type string to represent the format of the data when constructing a DocFlavor:

"application/octet-stream"

Representation Classes

For client-formatted print data, the print data representation class is usually one of the following:

Print data representation class Description

Character array (char[])

The print data consists of the Unicode characters in the array. This representation class can provide text data and PDL data.

java.lang.String

The print data consists of the Unicode characters in the string. This representation class can provide text data.

A Character stream represented by java.io.Reader

The print data consists of the Unicode characters read from the stream up to the end-of-stream. This representation class can provide text data.

Byte array (byte[])

The print data consists of the bytes in the array. The bytes are encoded in the character set specified by the doc flavor's MIME type. If the MIME type does not specify a character set, the default character set is US-ASCII. This representation class can provide text data, PDL documents, and image data.

A Byte stream represented by java.io.InputStream

The print data consists of the bytes read from the stream up to the end-of-stream. The bytes are encoded in the character set specified by the doc flavor's MIME type. If the MIME type does not specify a character set, the default character set is US-ASCII. This representation class can provide text data, PDL documents, and image data.

Uniform Resource Locator, java.net.URL

The print data consists of the bytes read from the URL location. The bytes are encoded in the character set specified by the doc flavor's MIME type. If the MIME type does not specify a character set, the default character set is US-ASCII. This representation class can provide text data, PDL documents, and image data. To print documents to a network print service that might not have access to the URL, open an input stream on the URL and use an input stream data flavor instead.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


4 - Printing and Streaming Documents

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

Locating Services

An application locates a print service in a slightly differently way from locating a stream print service. The Discovering Print Services section explains locating print services. The Discovering Stream Prin t Services section explains locating stream print services.

Discovering Print Services

Before sending a print job to a printer, the application needs to find printers that have the capabilities to handle the print job. To print a double-sided document, the application first needs to find printers that have the double-sided printing capabili ty.

The javax.print.PrintServiceLookup class included in the Java Print Service API provides static methods that applications use to locate printers.

An application invokes the lookupPrintServices method of PrintServiceLookup with a DocFlavor and an AttrbuteSet:

DocFlavor flavor = DocFlavor.INPUT_STREAM.POSTSCRIPT;
PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
aset.add(MediaSizeName.ISO_A4);
aset.add(new Copies(2));
PrintService[] service =
    PrintServiceLookup.lookupPrintServices(flavor,
            aset);
This method returns an array of print services representing printers that have the capabilities specified in the attribute set and can print the data format specified in the doc flavor. See the Attributes c hapter and the Specifying Document Types chapter for more help in choosing a DocFlavor and creating an AttributeSet.

The base set of printers returned from the lookupPrintServices method are the same as the set of printers returned by the platform. For example, when using Windows NT, the set of returned printers is the same as the set of printers visible in the Windows Printer Control Panel. Likewise, when using Solaris, the returned printers are the same as those enumerated by the System V Unix "lpstat" command. However, since third parties can augment these sets, additional printers, such as JINI printers, can be retu rned.

After obtaining a suitable PrintService, the application can access its many query methods to determine what values are supported for attribute categories. The Obtaining a Print Job section explains how to g et a print job from the PrintService.

Discovering Stream Print Services

An application uses stream print services to convert print data to different formats. This is useful, for example, if you do not have a printer that can print the format of a particular piece of print data. This section demonstrates how to convert a GIF d ocument into Postscript using a StreamPrintService.

The StreamPrintServiceFactory class has a lookupStreamPrintServiceFactories method for locating stream print services. This method, like the lookupPrintServices method in PrintServiceLookup, takes a DocFlavor that represents the type of the input document --in this case, DocFlavor.INPUT_STREAM.GIF. Unlike lookupPrintServices, this method also takes a MIME type. This MIME type represents the format of the output. Since this example converts GIF to postscript, the MIME type is "application/postscript" ;. The DocFlavor class has the getMimeType method for returning the MIME type from a DocFlavor. The lookupStreamPrintServicesFactories method returns an array of StreamPrintServiceFactory objects, which are factories for StreamPrintService instances. This code sample demonstrates obtaining an array of StreamPrintServiceFactory objects that can return StreamPrintService objects able to convert a GIF image into PostScript:

DocFlavor flavor = DocFlavor.INPUT_STREAM.GIF;
String psMimeType = DocFlavor.BYTE_ARRAY.POSTSCRIPT.getMimeType();
StreamPrintServiceFactory[] psfactories =
    StreamPrintServiceFactory.lookupStreamPrintServiceFactories(
        flavor, psMimeType);
The StreamPrintServiceFactory object has an instance method called getPrintService that takes an OutputStream parameter and creates a StreamPrintService instance that writes to that stream:

FileOutputStream fos = new FileOutputStream(filename);
StreamPrintService psService = psfactories[0].getPrintService(fos);
The JDK V1.4 includes one stream print service that can export Postscript from graphics calls, such as through the Pageable and Printable interfaces. To verify the availability of this service, use the StreamPrintServiceFactory class to try to l ocate it. The Printing and Streaming 2D Graphics chapter discusses streaming 2D graphics.

StreamPrintService implements PrintService, which means you can use a StreamPrintService wherever you can use a PrintService. The application is responsible for closing the output stream after a job has printed to the stream. Once the stream is closed, th e StreamPrintService instance can no longer be used.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


4 - Printing and Streaming Documents

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

Registering for Events

The Java Print Service API allows services to report two types of events to applications: printer status updates and print job progress updates. The events API, which includes the javax.print.event package and methods to register listeners on a service and DocPrintJob, follows the familiar listener model used in AWT.

Print Service Events

Print Service event listeners monitor a service's changes in status and report events as changes in the values of print service attributes. An application can monitor events on a print service by implementing the javax.print.event.PrintServiceAttributeListener interface and installing itself as a listener on a PrintService as shown in this example:

public class PrintPS implements PrintServiceAttributeListener {
    ...
    pservices[0].addPrintServiceAttributeListener(this);
    ...
    public void attributeUpdate(PrintServiceAttributeEvent e){
        // Do something if an attribute is updated
    }
...
The PrintServiceAttributeListener.attributeUpdate() method is called when print service attributes change. The service uses the PrintServiceAttributeListener interface to decide which events it supports.

An application can discover which print service attributes a service supports by using the same query methods it uses to discover which request attributes a service supports. For example, to discover if the service supports the QueuedJobCount attribute an application calls:

service.isAttributeCategorySupported(QueuedJobCount.class);
The service determines how frequently it reports updates on attributes. If many attributes are supported, the service might batch events, which means an application isn't guaranteed to receive a particular event. The delivered event contains only attributes that have changed in value, which means that static service attributes, such as the printer model, will never be reported in an event.

Print Job Events

Most printing clients are more interested in monitoring a print job than monitoring a service's status. A client can install two different kinds of listeners on a DocPrintJob: PrintJobAttributeListener and PrintJobListener.

PrintJobAttributeListener

PrintJobAttributeListener is similar to the service attribute listener: the job reports changes in attributes that implement the PrintJobAttribute interface. Usually these attributes are also print request attributes and are fixed over the lifetime of a print job. Only a few attributes, such as JobMediaSheetsCompleted, are likely to change. Since few clients are interested in this granularity of detail, and even fewer services support this capability, clients will most likely use PrintJobListener to monitor a job's progress.

PrintJobListener

PrintJobListener is easier to use than PrintJobAttributeListener because it delivers simple messages, such as printJobCompleted or printJobFailed. The interface has only six methods, each of which reports a significant but simple piece of information as an event. As a convenience, the adapter class, PrintJobAdapter, provides default implementations of these six methods.

One message in particular: printJobNoMoreEvents is unusual but useful. A client is often interested in knowing if a job has finished or failed. If possible, a service should deliver such "terminal" events, but sometimes the service cannot be sure if the job finished or failed, and a "completed" message is misleading in this case. For example, a job might be spooled to a network print service that has a queue that's not visible. In this case, the "no more events" message is not sufficient to say that the job has succeeded, but the client can at least infer that it is not known to have failed. The following example demonstrates adding a listener that monitors printJobNoMoreEvents messages:

public class PrintPS extends PrintJobAdapter{
    ...
    pj.addPrintJobListener(this);
    ...
    public void printJobNoMoreEvents(PrintJobEvent e){
        // Do something here
    }
...

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


4 - Printing and Streaming Documents

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

CHAPTER 4

Printing and Streaming Documents

Before submitting a print job, an application needs to locate print services that have the capability to handle the print data. Once the appropriate service is located, the application obtains a print job from it and submits the print job to the service.

This chapter demonstrates how to print and stream documents by:

  • Locating appropriate services using the elements presented in the two previous chapters: Attributes and Document Flavors
  • Creating a print job
  • Submitting the print job to the printer or service
  • Registering for events on the print job or service.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


4 - Printing and Streaming Documents

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

Submitting the Print Job

Once you have the Doc and DocPrintJob, you can call the DocPrintJob object's print method to submit the document to the service. The Submitting the Print Job to the Printer section completes the printin g example. The Submitting the Print Job to the Stream section completes the streaming example.

Submitting the Print Job to the Printer

This section completes the printing application explained in this chapter. This example prints five copies of a PostScript document, double-sided on A4 paper, and stapled.

    DocFlavor psFlavor = DocFlavor.INPUT_STREAM.POSTSCRIPT;
    PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
    aset.add(new Copies(2));
    aset.add(MediaSizeName.ISO_A4);
    aset.add(Sides.TWO_SIDED_LONG_EDGE);
    aset.add(Finishings.STAPLE);
    PrintService[] pservices = PrintServiceLookup.lookupPrintServices(psFlavor,
                            aset);
    if (services.length > 0) {
        DocPrintJob pj = pservices[0].createPrintJob();
        try {
            FileInputStream fis = new FileInputStream("example.ps");
            Doc doc = new SimpleDoc(fis, psFlavor, null);
            pj.print(doc, aset);
        } catch (IOException e) {
            System.err.println(e);
        } catch (PrintException e) {
            System.err.println(e);
        }
    }
See Example: PrintPS.java for the complete application.

Submitting the Print Job to the Stream

This section completes the streaming example explained in this chapter. This example converts a GIF document to PostScript and embeds the specified printing attributes into the PostScript document.

    DocFlavor flavor = DocFlavor.INPUT_STREAM.GIF;
    String psMimeType = DocFlavor.BYTE_ARRAY.POSTSCRIPT.getMimeType();
    PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
    aset.add(new Copies(2));
    aset.add(MediaSizeName.ISO_A4);
    aset.add(Sides.TWO_SIDED_LONG_EDGE);
    aset.add(Finishings.STAPLE);
    StreamPrintServiceFactory[] factories =
        StreamPrintServiceFactory.lookupStreamPrintServiceFactories(
                flavor, psMimeType);
    if(factories.length==0) {
        System.err.println("No suitable factories");
        System.exit(0);
    }
    try {
        FileInputStream fis = new FileInputStream("java2dlogo.gif");
        String filename = "newfile.ps";
        FileOutputStream fos = new FileOutputSteam(filename);
        StreamPrintService sps= factories[0].getPrintService(fos);
        DocPrintJob pj = sps.createPrintJob();
        Doc doc = new SimpleDoc(fos, psFlavor, aset);
        pj.print(doc, aset);
    } catch (IOException e) {
        System.err.println(e);
    } catch (PrintException e) {
        System.err.println(e);
    }
}
See Example: PrintGIFtoStream.java for the complete application.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


4 - Printing and Streaming Documents

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

StreamPrintService Versus PrintService

The JavaTM Print Service API includes a PrintService class and a StreamPrintService class. A StreamPrintService extends PrintService, and so a StreamPrintService can be used anywhere a PrintService can be used. However, PrintService and StreamPrintService are used for different purposes. APrintService is used to direct output to a printer; a StreamPrintService is used to export formatted print data to a stream, usually to a different format. When locating a StreamPrintService, you specify the required output format in the form of a MIME type argument and provide an OutputStream to receive the data. You do not provide a representation class when locating a StreamPrintService, as you do when locating a PrintService, because the output is always delivered to an OutputStream.

After locating a service, you obtain a print job and submit the print job to the service in the same way whether you are using a PrintService or a StreamPrintServie. The major differences between StreamPrintService and PrintService are in the way they are located. The next section discusses locating both print services and stream print services.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


4 - Printing and Streaming Documents

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

Print Service Providers

Print Service Providers are third parties that write an implementation of the abstract class PrintServiceLookup and install it according to the SPI JAR file specification.

This class provides a standardized API for looking up instances of print services. For example an IPP print service provider, a JINI lookup service, or a JNDI-based directory service may each be implementations of this class which can return PrintServices.

The API is reasonably simple and generally requires implementation of the PrintServiceLookup class, and the PrintService interface, and DocPrintJob. The PrintService should also support the events defined by the Java Print Service API.

How much more code there is depends on the document types that are supported. If a printer wants to be able to print a JPEG image and the printer already has such capability in hardware, its little more than a case of properly spooling the data. However, to print 2D graphics, a class that can turn the graphics calls into a printer-formatted raster is a significant body of work.

 CONTENTS | PREV
 | NEXT

Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


4 - Printing and Streaming Documents

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

Obtaining a Print Job

A print job is a submitted print request and includes one or more pieces of print data and a set of processing instructions. The Java Print Service represents a print job with the DocPrintJob object. Whether you are sending print data to a stream or to a printer, you create a print job in the same way: by calling createPrintJob on the service:

    DocPrintJob pj = pservices[0].createPrintJob();
An application obtains a print job from a service because the service only creates print jobs that are capable of handling data that the particular service can accept.

The DocPrintJob interface provides the print method, which takes a PrintRequestAttributeSet parameter and a Doc encapsulating the print data and the doc flavor:

    pj.print(doc, aset);
The next section discusses creating a Doc.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


4 - Printing and Streaming Documents

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

Creating a Doc

To create a Doc you must provide an implementation of the Doc interface. The Java Print Service API provides a convenient implementation of Doc called SimpleDoc. An application is not required to use the SimpleDoc implementation, but to ensure compliance with Doc, any Doc implementation must observe the same required semantics that SimpleDoc implements, which are:

  • Every Doc implemenation must implement all five methods of the Doc interface.
  • The Doc implementation must allow multiple threads to access the Doc object.
  • Every time a Doc method is called, it returns the same object. This means you do not return a new stream. Since there is only one input stream there can only be one consumer of the Doc.
  • The Doc returns a stream for the service if requested
  • The Doc checks if the data type matches the doc flavor
  • The attributes returned from getAttributes always override those passed in the print method.
Before creating a Doc, you need to load your document from the file. The representation class of the DocFlavor determines how you load the document from the file. In this case, the representation class is an InputStream:

    FileInputStream fis = new FileInputStream("java2dlogo.gif");
Once you have the stream, pass it to SimpleDoc with the DocFlavor and a DocAttributeSet, ifi you have one. If you don't have a DocAttributeSet, pass in null instead:

    Doc doc = new SimpleDoc(fis, flavor, null);
See Example: PrintGIF.java for an example of a custom Doc implementation.

The next section demonstrates how to register for events on your print job or service.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


5 - Printing and Streaming 2D Graphics

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

Using Service-Formatted Data

You can print or stream 2D graphics encapsulated in a Pageable or Printable object using a DocPrintJob and a service-formatted DocFlavor. A DocFlavor can represent any kind of data, including Java objects. An implementation of the Pageable or Printable interface is a Java object. As discussed in the Specifying Document Types chapter, the Java Print Service API includes pre-defined DocFlavor object constants for print data in the form of a Java object. An application can look up print services or stream print services supporting this type of data, encapsulate the object in a Doc implemetation and submit it to the service in a DocPrintJob. The Printing the Service-Formatted Data section demonstrates printing the data. The Streaming Service-Formatted Print Data section demonstrates streaming the data. Registering for events on 2D graphics printing applications using DocPrintJob is done the same way as for document printing applications using DocPrintJob. See Registering for Events for more information.

Printing the Service-Formatted Data

To locate print services that can handle the service-formatted data, pass the appropriate service-formatted DocFlavor object constant to the lookupPrintServices method:

PrintService []services =
    PrintServiceLookup.lookupPrintServices(DocFlavor.SERVICE_FORMATTED.PRINTABLE,
                            null);
The printing application implements the Printable interface. To create the Doc, use SimpleDoc, passing this in for the printData, the service-formatted DocFlavor constant for the DocFlavor, and an optional attribute set:

Doc  doc = new SimpleDoc(this, DocFlavor.SERVICE_FORMATTED.PRINTABLE, null);
Create the DocPrintJob, and submit it to the service:

DocPrintJob pj = service[0].createPrintJob();
pj.print(doc);
See Example: Print2DGraphics.java for the complete application.

Streaming Service-Formatted Print Data

A stream print service can be used to export 2D graphics encapsulated in a Java object to another format. This example exports graphics in a Printable to Postscript:

DocFlavor flavor = DocFlavor.SERVICE_FORMATTED.PRINTABLE
StreamPrintServiceFactory []factories =
    StreamPrintServiceFactory.lookupStreamPrintServiceFactories(flavor,
                            "application/postscript"));
if (factories.length == 0) {
    System.err.println("No suitable factories");
    System.exit(0);
}
try{
    FileOutputStream fos = new FileOutputStream("out.ps");
    StreamPrintService sps = factories[0].getPrintService(fos);
}
Doc  doc = new SimpleDoc(this, flavor, null);
sps.createPrintJob().print(doc);
See Example: Print2DtoStream.java for the complete application

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


5 - Printing and Streaming 2D Graphics

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

Using PrinterJob to Print or Stream Graphics

The new API injava.awt.print consists of these new PrinterJob methods:

  • Static convenience methods to look up print services that can image 2D graphics, which are returned as an array of PrintService or StreamPrintServiceFactory objects depending on the method.
  • Methods to set and get a PrintService on a PrinterJob.
  • A pageDialog method that takes a PrintRequestAttributeSet parameter.
  • A printDialog method that takes a PrintRequestAttributeSet parameter.
  • A print method that takes a PrintRequestAttributeSet parameter.
Because the new printDialog and pageDialog methods take an attribute set, users can edit the initail attribute settings from the dialogs.

Applications can use PrinterJob to print 2D graphics to a printer or to an output stream. The lookupPrintServices method returns an array of PrintService objects, each of which represents a printer that can print 2D graphics. The lookupStreamPrintServices method returns an array of StreamPrintServiceFactory objects, each of which can return a StreamPrintService. An application uses the StreamPrintService to send print data to an output stream. As with printing documents, applications can use a StreamPrintService to transcode 2D graphics to other formats. This section discusses using PrinterJob to submit 2D graphics to a printer and to an output stream.

Printing 2D Graphics

The new pageDialog, printDialog, and print methods allow an application to initialize print settings and pass these settings to a dialog so that a user can update the settings before submitting the print request, as demonstrated by this code sample:

// Step 1: Set up initial print settings.
PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
// Step 2: Obtain a print job.
PrinterJob pj = PrinterJob.getPrinterJob();
// Step 3: Find print services.
PrintService []services = PrinterJob.lookupPrintServices();
if (services.length > 0) {
    System.out.println("selected printer: " + services[0]);
    try {
    pj.setPrintService(service[0]);
    // Step 2: Pass the settings to a page dialog and print dialog.
    pj.pageDialog(aset);
    if (pj.printDialog(aset)) {
        // Step 4: Update the settings made by the user in the dialogs.
        // Step 5: Pass the final settings into the print request.
        pj.print(aset);
    }
    } catch (PrinterException(pe)) {
        System.err.println(pe):
    }
}
See Example: Print2DPrinterJob.java for the complete application.

Note that Step 4 in this code sample does not seem to correspond to any particular line of code. In fact, the user updates the print settings in the dialogs, and the updated settings are saved in the PrintRequestAttributeSet, aset.

One problem with using Java 2D and the Java Print Service together is that some attributes, such as number of copies, are defined in both APIs. If such an attribute is specified in a PrintRequestAttributeSet, it takes precedence over the same attribute specified in the PrinterJob. Note that if a user updates the number of copies in a print dialog, the PrinterJob is automatically updated to reflect that, which reconfirms the existing behavior.

The PageFormat specification also overlaps with the Java Print Service Media, MediaPrintableArea, and OrientationRequested attributes. If an application uses the Printable interface and the print(PrintRequestAttributeSet) method, the media, orientation, and imageable area attributes contained in the attribute set are added to a new PageFormat, which is passed to the print method of the Printable object. If an application uses the Pageable interface, the PageFormat does not change.

Streaming 2D Graphics

An application can also use a PrinterJob and a StreamPrintService to send print data to an output stream. This example is similar to the example in the previous section, except a StreamPrintService is used in place of a PrintService:

PrinterJob job = PrinterJob.getPrinterJob();
String psMimeType = "application/postscript";
FileOutputStream outstream;
StreamPrintService psPrinter;
StreamPrintServiceFactory []spsFactories =
    PrinterJob.lookupStreamPrintServices(psMimeType);
if (factories.length > 0) {
    try {
        outstream = new File("out.ps");
        psPrinter = factories[0].getPrintService(fos);
        // psPrinter can now be set as the service on a PrinterJob
    } catch (FileNotFoundException e) { }
}
job.setPrintService(service[0]); // if app wants to specify this printer.
PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
aset.add(new Copies(2));
job.print(aset);
}

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


5 - Printing and Streaming 2D Graphics

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

CHAPTER 5

Printing and Streaming 2D Graphics

The Java 2DTM printing API is the java.awt.print package that is part of the JavaTM 2 SE, version 1.2 and later. The Java 2D printing API provides for creating a PrinterJob, displaying a printer dialog to the user, and printing paginated graphics using the same java.awt.Graphics and java.awt.Graphics2D classes that are used to draw to the screen.

Many of the features that are new in the Java Print Service, such as printer discovery and specification of printing attributes, are also very important to users of the Java 2D printing API. To make these features available to users of Java 2D printing, the java.awt.print package has been updated for version 1.4 of the JavaTM 2 SE to allow access to the JavaTM Print Service from the Java 2D printing API.

Developers of Java 2D printing applications have four ways of using the Java Print Service with the Java 2D API:

  • Print 2D graphics using PrinterJob.
  • Stream 2D graphics using PrinterJob
  • Print 2D graphics using using DocPrintJob and a service-formatted DocFlavor
  • Stream 2D graphics using DocPrintJob and a service-formatted DocFlavor
The Using PrinterJob to Print or Stream Graphics section explains the first two methods. The Using Service-Formatted Data section explains the other two methods.

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


Contents

CONTENTS | PREV | NEXT

JavaTM Print Service API User Guide

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


Print2DGraphics.java

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

APPENDIX D

Example: Print2DGraphics.java

import java.io.*;
import java.awt.*;
import java.net.*;
import java.awt.image.*;
import java.awt.print.*;
import javax.print.*;
import javax.print.attribute.*;
import javax.print.attribute.standard.*;

public class Print2DGraphics implements Printable {

    public Print2DGraphics() {

        /* Construct the print request specification.
        * The print data is a Printable object.
        * the request additonally specifies a job name, 2 copies, and
        * landscape orientation of the media.
        */
        DocFlavor flavor = DocFlavor.SERVICE_FORMATTED.PRINTABLE;
        PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
        aset.add(OrientationRequested.LANDSCAPE);
        aset.add(new Copies(2));
        aset.add(new JobName("My job", null));

        /* locate a print service that can handle the request */
        PrintService[] services =
            PrintServiceLookup.lookupPrintServices(flavor, aset);

        if (services.length > 0) {
            System.out.println("selected printer " + services[0].getName());

            /* create a print job for the chosen service */
            DocPrintJob pj = services[0].createPrintJob();

            try {
                /*
                * Create a Doc object to hold the print data.
                */
                Doc doc = new SimpleDoc(this, flavor, null);

                /* print the doc as specified */
                pj.print(doc, aset);

                /*
                * Do not explicitly call System.exit() when print returns.
                * Printing can be asynchronous so may be executing in a
                * separate thread.
                * If you want to explicitly exit the VM, use a print job
                * listener to be notified when it is safe to do so.
                */

            } catch (PrintException e) {
                System.err.println(e);
            }
        }
    }

    public int print(Graphics g,PageFormat pf,int pageIndex) {

        if (pageIndex == 0) {
            Graphics2D g2d= (Graphics2D)g;
            g2d.translate(pf.getImageableX(), pf.getImageableY());
            g2d.setColor(Color.black);
            g2d.drawString("example string", 250, 250);
            g2d.fillRect(0, 0, 200, 200);
            return Printable.PAGE_EXISTS;
        } else {
            return Printable.NO_SUCH_PAGE;
        }
    }

    public static void main(String arg[]) {
        Print2DGraphics sp = new Print2DGraphics();
    }
}

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


Print2DPrinterJob.java

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

APPENDIX C

Example: Print2DPrinterJob.java

import java.io.*;
import java.awt.*;
import java.net.*;
import java.awt.image.*;
import java.awt.print.*;
import javax.print.*;
import javax.print.attribute.*;
import javax.print.attribute.standard.*;

public class Print2DPrinterJob implements Printable {

    public Print2DPrinterJob() {

        /* Construct the print request specification.
        * The print data is a Printable object.
        * the request additonally specifies a job name, 2 copies, and
        * landscape orientation of the media.
        */
        PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
        aset.add(OrientationRequested.LANDSCAPE);
        aset.add(new Copies(2));
        aset.add(new JobName("My job", null));

        /* Create a print job */
        PrinterJob pj = PrinterJob.getPrinterJob();
        pj.setPrintable(this);
        /* locate a print service that can handle the request */
        PrintService[] services =
            PrinterJob.lookupPrintServices();

        if (services.length > 0) {
            System.out.println("selected printer " + services[0].getName());
            try {
                pj.setPrintService(services[0]);
                pj.pageDialog(aset);
                if(pj.printDialog(aset)) {
                    pj.print(aset);
                }
            } catch (PrinterException pe) {
                System.err.println(pe);
            }
        }
    }

    public int print(Graphics g,PageFormat pf,int pageIndex) {

        if (pageIndex == 0) {
            Graphics2D g2d= (Graphics2D)g;
            g2d.translate(pf.getImageableX(), pf.getImageableY());
            g2d.setColor(Color.black);
            g2d.drawString("example string", 250, 250);
            g2d.fillRect(0, 0, 200, 200);
            return Printable.PAGE_EXISTS;
        } else {
            return Printable.NO_SUCH_PAGE;
        }
    }

    public static void main(String arg[]) {

        Print2DPrinterJob sp = new Print2DPrinterJob();
    }
}

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


Print2DtoStream.java

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

APPENDIX E

Example: Print2DtoStream.java

/*
 * Copyright 2001 Sun Microsystems, Inc. All Rights Reserved.
 *
 * This software is the proprietary information of Sun Microsystems, Inc.
 * Use is subject to license terms.
 *
 */

import java.io.*;
import java.awt.*;
import java.awt.print.*;
import javax.print.*;
import javax.print.attribute.*;
import javax.print.attribute.standard.*;

/*
 * Use the Java(TM) Print Service API to locate a service which can export
 * 2D graphics to a stream as Postscript. This may be spooled to a
 * Postscript printer, or used in a postscript viewer.
 */
public class Print2DtoStream implements Printable{

    public Print2DtoStream() {

        /* Use the pre-defined flavor for a Printable from an InputStream */
        DocFlavor flavor = DocFlavor.SERVICE_FORMATTED.PRINTABLE;

         /* Specify the type of the output stream */
        String psMimeType = DocFlavor.BYTE_ARRAY.POSTSCRIPT.getMimeType();

        /* Locate factory which can export a GIF image stream as Postscript */
        StreamPrintServiceFactory[] factories =
        StreamPrintServiceFactory.lookupStreamPrintServiceFactories(
                    flavor, psMimeType);
        if (factories.length == 0) {
            System.err.println("No suitable factories");
            System.exit(0);
        }

        try {
            /* Create a file for the exported postscript */
            FileOutputStream fos = new FileOutputStream("out.ps");

            /* Create a Stream printer for Postscript */
            StreamPrintService sps = factories[0].getPrintService(fos);

            /* Create and call a Print Job */
            DocPrintJob pj = sps.createPrintJob();
            PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();

            Doc doc = new SimpleDoc(this, flavor, null);

            pj.print(doc, aset);
            fos.close();

        } catch (PrintException pe) {
            System.err.println(pe);
        } catch (IOException ie) {
            System.err.println(ie);
        }
    }

    public int print(Graphics g,PageFormat pf,int pageIndex) {

        if (pageIndex == 0) {
            Graphics2D g2d= (Graphics2D)g;
            g2d.translate(pf.getImageableX(), pf.getImageableY());
            g2d.setColor(Color.black);
            g2d.drawString("example string", 250, 250);
            g2d.fillRect(0, 0, 200, 200);
            return Printable.PAGE_EXISTS;
        } else {
            return Printable.NO_SUCH_PAGE;
        }
    }

    public static void main(String args[]) {
           Print2DtoStream sp = new Print2DtoStream();
    }
}

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


PrintGIF.java

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

APPENDIX F

Example: PrintGIF.java

/*
* Copyright 2001 Sun Microsystems, Inc. All Rights Reserved.
*
* This software is the proprietary information of Sun Microsystems, Inc.
* Use is subject to license terms.
*
*/

import java.io.*;
import javax.print.*;
import javax.print.attribute.*;
import javax.print.attribute.standard.*;

/*
*  Use the Java(TM) Print Service API to locate a print service which
*  can print a GIF-encoded image. A GIF image is printed according to
*  a job template specified as a set of printing attributes.
*/
public class PrintGIF {

    public static void main(String args[]) {

        /* Use the pre-defined flavor for a GIF from an InputStream */
        DocFlavor flavor = DocFlavor.INPUT_STREAM.GIF;

        /* Create a set which specifies how the job is to be printed */
        PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
        aset.add(MediaSizeName.NA_LETTER);
        aset.add(new Copies(1));

        /* Locate print services which can print a GIF in the manner specified */
        PrintService[] pservices =
            PrintServiceLookup.lookupPrintServices(flavor, aset);

        if (pservices.length > 0) {
            /* Create a Print Job */
            DocPrintJob printJob = pservices[0].createPrintJob();

            /* Create a Doc implementation to pass the print data */
            Doc doc = new InputStreamDoc("java2dlogo.gif", flavor);

            /* Print the doc as specified */
            try {
                printJob.print(doc, aset);
            } catch (PrintException e) {
                System.err.println(e);
            }
        } else {
            System.err.println("No suitable printers");
        }
    }
}

class InputStreamDoc implements Doc {
    private String filename;
    private DocFlavor docFlavor;
    private InputStream stream;

    public InputStreamDoc(String name, DocFlavor flavor) {
        filename = name;
        docFlavor = flavor;
    }

    public DocFlavor getDocFlavor() {
        return docFlavor;
    }

    /* No attributes attached to this Doc - mainly useful for MultiDoc */
    public DocAttributeSet getAttributes() {
        return null;
    }

    /* Since the data is to be supplied as an InputStream delegate to
    * getStreamForBytes().
    */
    public Object getPrintData() throws IOException {
        return getStreamForBytes();
    }

    /* Not possible to return a GIF as text */
    public Reader getReaderForText()
        throws UnsupportedEncodingException, IOException {
       return null;
    }

    /* Return the print data as an InputStream.
    * Always return the same instance.
    */
    public InputStream getStreamForBytes() throws IOException {
        synchronized(this) {
            if (stream == null) {
                stream = new FileInputStream(filename);
            }
            return stream;
        }
    }
}

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


PrintGIFtoStream.java

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

APPENDIX B

Example: PrintGIFtoStream.java

/*
* Copyright 2001 Sun Microsystems, Inc. All Rights Reserved.
*
* This software is the proprietary information of Sun Microsystems, Inc.
* Use is subject to license terms.
*
*/

import java.io.*;
import javax.print.*;
import javax.print.attribute.*;
import javax.print.attribute.standard.*;

/*
* Use the Java(TM) Print Service API to locate a service which can export
* a GIF-encoded image to a stream as Postscript. This may be spooled to a
* Postscript printer, or used in a postscript viewer.
*/
public class PrintGIFtoStream {

    public static void main(String args[]) {

        /* Use the pre-defined flavor for a GIF from an InputStream */
        DocFlavor flavor = DocFlavor.INPUT_STREAM.GIF;

        /* Specify the type of the output stream */
        String psMimeType = DocFlavor.BYTE_ARRAY.POSTSCRIPT.getMimeType();

        /* Locate factory which can export a GIF image stream as Postscript */
        StreamPrintServiceFactory[] factories =
            StreamPrintServiceFactory.lookupStreamPrintServiceFactories(
                    flavor, psMimeType);
        if (factories.length == 0) {
            System.err.println("No suitable factories");
            System.exit(0);
        }

        try {
            /* Load the file */
            FileInputStream fis = new FileInputStream("java2dlogo.gif");
            /* Create a file for the exported postscript */
            String filename = "newfile.ps";
            FileOutputStream fos = new FileOutputStream(filename);

            /* Create a Stream printer for Postscript */
            StreamPrintService sps = factories[0].getPrintService(fos);

            /* Create and call a Print Job for the GIF image */
            DocPrintJob pj = sps.createPrintJob();
            PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
            aset.add(new Copies(2));
            aset.add(MediaSizeName.ISO_A4);
            aset.add(Sides.TWO_SIDED_LONG_EDGE);
            aset.add(Finishings.STAPLE);

            Doc doc = new SimpleDoc(fis, flavor, null);

            pj.print(doc, aset);
            fos.close();

        } catch (PrintException pe) {
            System.err.println(pe);
        } catch (IOException ie) {
            System.err.println(ie);
        }
    }
}

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


PrintPS.java

CONTENTS | PREV | NEXT JavaTM Print Service API User Guide

APPENDIX A

Example: PrintPS.java

import java.io.*;
import javax.print.*;
import javax.print.attribute.*;
import javax.print.attribute.standard.*;
import javax.print.event.*;

public class PrintPS {

    public static void main(String args[]) {
        PrintPS ps = new PrintPS();
    }
    public PrintPS() {
        /* Construct the print request specification.
         * The print data is Postscript which will be
          * supplied as a stream.  The media size
          * required is A4, and 2 copies are to be printed
         */
        DocFlavor flavor = DocFlavor.INPUT_STREAM.POSTSCRIPT;
        PrintRequestAttributeSet aset =
            new HashPrintRequestAttributeSet();
        aset.add(MediaSizeName.ISO_A4);
        aset.add(new Copies(2));
        aset.add(Sides.TWO_SIDED_LONG_EDGE);
        aset.add(Finishings.STAPLE);

        /* locate a print service that can handle it */
        PrintService[] pservices =
            PrintServiceLookup.lookupPrintServices(flavor, aset);
        if (pservices.length > 0) {
            System.out.println("selected printer " + pservices[0].getName());

            /* create a print job for the chosen service */
            DocPrintJob pj = pservices[0].createPrintJob();
            try {
                /*
                * Create a Doc object to hold the print data.
                * Since the data is postscript located in a disk file,
                * an input stream needs to be obtained
                * BasicDoc is a useful implementation that will if requested
                * close the stream when printing is completed.
                */
                FileInputStream fis = new FileInputStream("example.ps");
                Doc doc = new SimpleDoc(fis, flavor, null);

                /* print the doc as specified */
                pj.print(doc, aset);

                /*
                * Do not explicitly call System.exit() when print returns.
                * Printing can be asynchronous so may be executing in a
                * separate thread.
                * If you want to explicitly exit the VM, use a print job
                * listener to be notified when it is safe to do so.
                */

            } catch (IOException ie) {
                System.err.println(ie);
            } catch (PrintException e) {
                System.err.println(e);
            }
        }
    }
}

CONTENTS | PREV | NEXT
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.


Enhancements in JVM TI

Java

Enhancements in JDK 6
JavaTM Virtual Machine Tool Interface (JVM TI)

 Contents
The following functionality has been added to the JVMTM tool interface (JVM TI) between its initial release in JDK 5.0 and JDK 6.
  • Support for transformation of class files - To facilitate dynamic transformation of classes which have already been loaded, the RetransformClasses function has been added. It is suited to operations such as adding instrumentation to methods. Support for retransformation means that access to the original class file is no longer required in order to instrument loaded classes. It can easily remove the applied transformation and it is designed to work in a multi-agent environment.

  • Enhanced heap walking support - More powerful and flexible heap functionality has been added. The new functionality:
    • allows access to primitive values (the value of Strings, arrays, and primitive fields)
    • allows the tag of the referrer to be set, thus enabling more efficient localized reference graph building
    • provides more extensive filtering abilities
    • is extensible, allowing abilities to grow in future versions of JVM TI
    The FollowReferences and IterateThroughHeap functions have been added along with supporting types and constants. The previous functionality is still supported but its use is discouraged.

  • More class information - The new GetConstantPool, GetClassVersionNumbers and IsModifiableClass functions provide additional information about a class.

  • Support for instrumenting native methods - The new SetNativeMethodPrefix and SetNativeMethodPrefixes functions allow native methods to be instrumented by providing a JVM-aware mechanism for wrapping the native method.

  • Enhanced support for instrumentation under the system class loader - The new AddToSystemClassLoaderSearch function allows instrumentation support classes to be defined by the system class loader.

  • Support for early return from a method - The new force early return functions allow debugger-like tools to force a method to return from any point in its execution.

  • Monitor stack depth information - The new GetOwnedMonitorStackDepthInfo function provides information about the monitors owned by the specified thread and the depth of the stack frame which locked them.

  • Support for resource exhaustion notification - The new ResourceExhausted event notifies the JVM when a critical resource (such as the JavaTM platform heap) has been exhausted.

Other changes between JDK 5.0 and JDK 6 include new error codes, a revised definition for field index, allowing AddToBootstrapClassLoaderSearch to be called in the live phase, and considerable specification clean-up and clarification. For detailed information about the changes, see the Change History.
Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

 Sun


Java Virtual Machine Tool Interface

Java (tm)

JavaTM Virtual Machine Tool Interface (JVM TI)

Documentation Contents

The JVMTM tool interface (JVM TI) is a native programming interface for use by tools. It provides both a way to inspect the state and to control the execution of applications running in the JavaTM virtual machine (JVM). JVM TI supports the full breadth of tools that need access to JVM state, including but not limited to: profiling, debugging, monitoring, thread analysis, and coverage analysis tools.

Note: JVM TI was introduced at JDKTM 5.0. JVM TI replaces the Java Virtual Machine Profiler Interface (JVMPI) and the Java Virtual Machine Debug Interface (JVMDI) which, as of JDK 6, are no longer provided.

JVM TI Reference

  • See the JVM TI Reference for overview, API reference, and usage information.

API Enhancements

  • See the API Enhancements in JDK 6 - An annotated list of API changes between the 5.0 and 6 releases.

More Information

  • Java Virtual Machines - features, command-line options, and additional information.
  • Java Native Interface - the interface which JVM TI extends.
  • java.lang.instrument package - a Java programming language alternate to JVM TI if only the instrumentation functionality of JVM TI is used.

* As used on this web site, the terms "Java Virtual Machine" or "JVM" mean a virtual machine for the Java platform.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

 Feedback 		Sun
Java Software


Accessing Resources

Location-Independent Access to Resources

  • Overview
  • Resources, names, and contexts
  • System Resources
  • Non-System Resources
  • Resource Names
  • Usimg Methods of java.lang.Class
  • Using Methods of java.lang.ClassLoader
  • Security
  • Examples
  • References

Overview

A resource is data (images, audio, text, and so on) that a program needs to access in a way that is independent of the location of the program code. Java programs can use two mechanisms to access resources: Applets use Applet.getCodeBase() to get the base URL for the applet code and then extend the base URL with a relative path to load the desired resource, for example with Applet.getAudioClip(url). Applications use "well known locations" such as System.getProperty("user.home") or System.getProperty("java.home"), then add "/lib/resource", and open that file.

Methods in the classes Class and ClassLoader provide a location-independent way to locate resources. For example, they enable locating resources for:

  • An applet loaded from the Internet using multiple HTTP connections.
  • An applet loaded using JAR files.
  • A Java Bean loaded or installed in the CLASSPATH.
  • A "library" installed in the CLASSPATH.

These methods do not provide specific support for locating localized resources. Localized resources are supported by the internationalization facilities.

Resources, names, and contexts

A resource is identified by a string consisting of a sequence of substrings, delimited by slashes (/), followed by a resource name. Each substring must be a valid Java identifier. The resource name is of the form shortName or shortName.extension. Both shortName and extension must be Java identifiers.

The name of a resource is independent of the Java implementation; in particular, the path separator is always a slash (/). However, the Java implementation controls the details of how the contents of the resource are mapped into a file, database, or other object containing the actual resource.

The interpretation of a resource name is relative to a class loader instance. Methods implemented by the ClassLoader class do this interpretation.

System Resources

A system resource is a resource that is either built-in to the system, or kept by the host implementation in, for example, a local file system. Programs access system resources through the ClassLoader methods getSystemResource and getSystemResourceAsStream.

For example, in a particular implementation, locating a system resource may involve searching the entries in the CLASSPATH. The ClassLoader methods search each directory, ZIP file, or JAR file entry in the CLASSPATH for the resource file, and, if found, returns either an InputStream, or the resource name. If not found, the methods return null. A resource may be found in a different entry in the CLASSPATH than the location where the class file was loaded.

Non-System Resources

The implementation of getResource on a class loader depends on the details of the ClassLoader class. For example, AppletClassLoader:

  • First tries to locate the resource as a system resource; then, if not found,
  • Searches through the resources in archives (JAR files) already loaded in this CODEBASE; then, if not found,
  • Uses CODEBASE and attempts to locate the resource (which may involve contacting a remote site).

All class loaders will search for a resource first as a system resource, in a manner analogous to searcing for class files. This search rule permits overwriting locally any resource. Clients should choose a resource name that will be unique (using the company or package name as a prefix, for instance).

Resource Names

A common convention for the name of a resource used by a class is to use the fully qualified name of the package of the class, but convert all periods (.) to slashes (/), and add a resource name of the form name.extension. To support this, and to simplify handling the details of system classes (for which getClassLoader returns null), the class Class provides two convenience methods that call the appropriate methods in ClassLoader.

The resource name given to a Class method may have an initial starting "/" that identifies it as an "absolute" name. Resource names that do not start with a "/" are "relative".

Absolute names are stripped of their starting "/" and are passed, without any further modification, to the appropriate ClassLoader method to locate the resource. Relative names are modified according to the convention described previously and then are passed to a ClassLoader method.

Using Methods of java.lang.Class

The Class class implements several methods for loading resources.

The method getResource() returns a URL for the resource. The URL (and its representation) is specific to the implementation and the JVM (that is, the URL obtained in one runtime instance may not work in another). Its protocol is usually specific to the ClassLoader loading the resource. If the resource does not exist or is not visible due to security considerations, the methods return null.

If the client code wants to read the contents of the resource as an InputStream, it can apply the openStream() method on the URL. This is common enough to justify adding getResourceAsStream() to Class and ClassLoader. getResourceAsStream() the same as calling getResource().openStream(), except that getResourceAsStream() catches IO exceptions returns a null InputStream.

Client code code can also request the contents of the resource as an object by applying the java.net.URL.getContent() method on the URL. This is useful when the resource contains the data for an image, for instance. In the case of an image, the result is an awt.image.ImageProducer object, not an Image object.

The getResource and getResourceAsStream methods find a resource with a given name. They return null if they do not find a resource with the specified name. The rules for searching for resources associated with a given class are implemented by the class's ClassLoader. The Class methods delegate to ClassLoader methods, after applying a naming convention: if the resource name starts with "/", it is used as is. Otherwise, the name of the package is prepended, after converting all periods (.) to slashes (/).

public InputStream getResourceAsStream(String name) {
  name = resolveName(name);
  ClassLoader cl = getClassLoader();
  if (cl==null) {
    return ClassLoader.getSystemResourceAsStream(name); // A system class.
  }
  return cl.getResourceAsStream(name);
}

public java.net.URL getResource(String name) {
  name = resolveName(name);
  ClassLoader cl = getClassLoader();
  if (cl==null) {
    return ClassLoader.getSystemResource(name);  // A system class.
  }
  return cl.getResource(name);
}

The resolveName method adds a package name prefix if the name is not absolute, and removes any leading "/" if the name is absolute. It is possible, though uncommon, to have classes in diffent packages sharing the same resource.

private String resolveName(String name) {
  if (name == null) {
    return name;
  }
  if (!name.startsWith("/")) {
    Class c = this;
    while (c.isArray()) {
      c = c.getComponentType();
    }
    String baseName = c.getName();
    int index = baseName.lastIndexOf('.');
    if (index != -1) {
      name = baseName.substring(0, index).replace('.', '/') + "/" + name;
    }
  } else {
    name = name.substring(1);
  }
  return name;
}

Using Methods of java.lang.ClassLoader

The ClassLoader class has two sets of methods to access resources. One set returns an InputStream for the resource. The other set returns a URL. The methods that return an InputStream are easier to use and will satisfy many needs, while the methods that return URLs provide access to more complex information, such as an Image and an AudioClip.

The ClassLoadermanges resources similarly to the way it manages classes. A ClassLoader controls how to map the name of a resource to its content. ClassLoader also provides methods for accessing system resources, analogous to the system classes. The Class class provides some convenience methods that delegate functionality to the ClassLoader methods.

Many Java programs will access these methods indirectly through the I18N (localization) APIs. Others will access it through methods in Class. A few will directly invoke the ClassLoader methods.

The methods in ClassLoader use the given String as the name of the resource without applying any absolute/relative transformation (see the methods in Class). The name should not have a leading "/".

System resources are those that are handled by the host implemenation directly. For example, they may be located in the CLASSPATH.

The name of a resource is a "/"-separated sequence of identifiers. The Class class provides convenience methods for accessing resources; the methods implement a convention where the package name is prefixed to the short name of the resource.

Resources can be accessed as an InputStream, or a URL.

The getSystemResourceAsStream method returns an InputStream for the specified system resource or null if it does not find the resource. The resource name may be any system resource.

The getSystemResource method finds a system resource with the specified name. It returns a URL to the resource or null if it does not find the resource. Calling java.net.URL.getContent() with the URL will return an object such as ImageProducer, AudioClip, or InputStream.

The getResourceAsStream method returns an InputStream for the specified resource or null if it does not find the resource.

The getResource method finds a resource with the specified name. It returns a URL to the resource or null if it does not find the resource. Calling java.net.URL.getContent() with the URL will return an object such as ImageProducer, AudioClip, or InputStream.

Security

Since getResource() provides access to information, it must have well-defined and well-founded security rules. If security considerations do not allow a resource to be visible in some security context, the getResource() method will fail (return null) as if the resource were not present at all, this addresses existence attacks.

Class loaders may not provide access to the contents of a .class file for both security and performance reasons. Whether it is possible to obtain a URL for a .class file depends on the specifics, as shown below.

There are no specified security issues or restrictions regarding resources that are found by a non-system class loader. AppletClassLoader provides access to information that is loaded from a source location, either individually, or in a group through a JAR file; thus AppletClassLoader should apply the same checkConnect() rules when dealing with URLs through getResource().

The system ClassLoader provides access to information in the CLASSPATH. A CLASSPATH may contain directories and JAR files. Since a JAR file is created intentionally, it has a different significance than a directory where things may end up in a more casual manner. In particular, we are more strict on getting information out of a directory than out from a JAR file.

If a resource is in a directory:

  • getResource() invocations will use File.exists() to determine whether to make the corresponding file visible to the user. Recall that File.exists() uses the checkRead() method in the security manager.
  • the same applies to getResourceAsStream().

If the resource is in a JAR file:

  • getResource() invocations will succeed for all files, regardless of whether the invocation is done from within a system or a non-system class.
  • getResourceAsStream() invocations will succeed for non .class resources, and so will for java.net.URL.getContent() on corresponding URLs.

Examples

This section provides two examples of client code. The first example uses "absolute resource" names and traditional mechanisms to get a Class object.

package pkg;

import java.io.IOException;
import java.io.InputStream;
import java.io.PrintStream;

class Test {

  private static final String absName = "/pkg/mumble.baf";

  public static void test1() {
    Class c=null;
    try {
      c = Class.forName("pkg.Test");
    } catch (Exception ex) {
      // This should not happen.
    }
    InputStream s = c.getResourceAsStream(absName);
    // do something with it.
  }

  public void test2() {
    InputStream s = this.getClass().getResourceAsStream(absName);
  // do something with it.
  }
}

This example uses "relative resource" names and the mechanism available from the compiler through the -experimental flag, to get a Class object.

package pkg;

import java.io.IOException;
import java.io.InputStream;
import java.io.PrintStream;

class Test {
  private static final String relName = "mumble.baf";
  public static void test1() {
  InputStream s = Test.class.getResourceAsStream(relName);
  // do something with it.
}

  public void test2() {
    InputStream s = Test.class.getResourceAsStream(relName);
    // do something with it.
  }

API References

  • java.lang.Class
  • java.lang.ClassLoader
  • java.net.URLClassLoader
  • java.util.ResourceBundle
  • java.lang.SecurityManager
  • java.security

Copyright © 1996-98 Sun Microsystems, Inc. All Rights Reserved. Sun Microsystems, Inc
Java Software


Chained Exception Facility

 Documentation Contents

It is common for Java code to catch one exception and throw another:

try {
    ...
} catch(YourException e) {
    throw new MyException();
}

Unfortunately, the information contained in the "causative exception" (YourException in the example above) is generally lost, which greatly complicates debugging. Recognizing this problem, developers sometimes build ad hoc mechanisms to allow certain "wrapped exceptions" to contain a second exception. An accessor is generally provided to extract the contained exception. Such mechanisms are sometimes known as "exception chaining facilities", as they allow arbitrary chains of exceptions to be constructed when contained exceptions are, themselves, wrapped exceptions.

There are many advantages to unifying all of these facilities. Chief among them are: (1) We guarantee that anyone who wants to record the fact that one exception caused another can do so, regardless of what the exceptions are. (2) By providing a common API to record the fact that one exception caused another, we ease this task, making it more likely that programmers will take the trouble to do it. (3) By providing a common API to access causative exceptions, we greatly increase the likelihood that this information will be made available to those who need it. In fact, the proposed mechanism prints entire "causal chain" as part of the standard stack backtrace, ensuring that preexisting programs will provide this information with no additional effort on the part of their authors.

To address these issues, we have added two new methods to Throwable, getCause() and initCause(Throwable), and two new constructors, Throwable(Throwable) and Throwable(String, Throwable). Other "general purpose" exception classes (like Exception, RunTimeException and Error) have been similarly outfitted with (Throwable) and (String, Throwable) constructors. However, even exceptions without such constructors will be usable as "wrapped exceptions" via the initCause method.

The implementation of Throwable.printStackTrace has been modified to display backtraces for the entire causal chain of exceptions. New method getStackTrace provides programmatic access to the stack trace information provided by printStackTrace.

All of the platform's wrapped exceptions will be retrofitted to support the new facility (in addition to their legacy APIs).

Copyright © 2002-2006 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


Design of Shutdown Hooks API

Java

Design of the Shutdown Hooks API

 Documentation Contents
The following Q&A addresses some of the design issues of the Shutdown Hooks API.

Isn't this what runFinalizersOnExit is for?

You can use the Runtime.runFinalizersOnExit method, or the equivalent method in the System class, to schedule actions to take place when the VM shuts down due to exit. This technique does not, however, work for termination-triggered shutdowns. It is also is inherently unsafe, and in fact these methods were deprecated in version 1.2 of the JavaTM 2 Platform.

Why don't you provide information as to why the VM is shutting down?

On some platforms a native process can't distinguish a shutdown due to exit from a shutdown due to termination. Other platforms provide much richer capabilities, in some cases including notification of system suspension and restart or of imminent power failure. In short, it's impossible to generalize such information in a portable way.

Will shutdown hooks be run if the VM crashes?

If the VM crashes due to an error in native code then no guarantee can be made about whether or not the hooks will be run.

Why are shutdown hooks run concurrently? Wouldn't it make more sense to run them in reverse order of registration?

Invoking shutdown hooks in their reverse order of registration is certainly intuitive, and is in fact how the C runtime library's atexit procedure works. This technique really only makes sense, however, in a single-threaded system. In a multi-threaded system such as Java platform the order in which hooks are registered is in general undetermined and therefore implies nothing about which hooks ought to be run before which other hooks. Invoking hooks in any particular sequential order also increases the possibility of deadlocks. Note that if a particular subsystem needs to invoke shutdown actions in a particular order then it is free to synchronize them internally.

Why are hooks just threads, and unstarted ones at that? Wouldn't it be simpler to use Runnable objects, or Beans-style event and listener patterns?

The approach taken here has two advantages over the more obvious, and more frequently suggested, callback-oriented designs based upon Runnable objects or Beans-style event listeners.

First, it gives the user complete control over the thread upon which a shutdown action is executed. The thread can be created in the proper thread group, given the correct priority, context, and privileges, and so forth.

Second, it simplifies both the specification and the implementation by isolating the VM from the hooks themselves. If shutdown actions were executed as callbacks then a robust implementation would wind up having to create a separate thread for each hook anyway in order for them to run concurrently. The specification would also have to include explicit language about how the threads that execute the callbacks are created.

Aren't threads pretty expensive things to keep around, especially if they won't be started until the VM shuts down?

Most implementations of the Java platform don't actually allocate resources to a thread until it's started, so maintaining a set of unstarted threads is actually very cheap. If you look at the internals of java.lang.Thread you can see that its various constructors just do security checks and initialize private fields. The native start() method does the real work of allocating a thread stack, etc., to get things going.

What about Personal and Embedded Java? Won't starting threads during shutdown be too expensive on those platforms?

This API may not be suitable for the smaller Java platforms. Threads in the Java 2 Platform carry more information than threads in JDK 1.1 and p/eJava. A thread has a class loader, it may have some inherited thread-local variables, and, in the case of GUI apps, it may be associated with a specific application context. Threads will come to carry even more information as the platform evolves; for example, the security team is planning to introduce a notion of per-thread user identity in their upcoming authentication framework.

Because of all this contextual information, shutdown hooks would be harder to write and maintain if they were just Runnable objects or Beans-style event listeners. Suppose that a Runnable shutdown hook, or an equivalent event listener, needed a specific bit of thread-contextual information in order to carry out its operations. Such information could be saved in some shared location before the hook is registered. While this is merely awkward, suppose further that threads acquire some new type of contextual information in a future release. If an operation invoked by the hook also evolves to need that information then the code that registers the hook would have to be amended to save that information as well. Making hooks be threads instead of Runnables or event listeners insulates them from this sort of future change.

Okay, but won't I have to write a lot of code just to register a simple shutdown hook?

No. Simple shutdown hooks can often be written as anonymous inner classes, as in this example:
Runtime.getRuntime().addShutdownHook(new Thread() {
    public void run() { database.close(); }
});
This idiom is fine as long as you'll never need to cancel the hook, in which case you'd need to save a reference to the hook when you create it.

What about security? Can an untrusted applet register a shutdown hook?

If there is a security manager installed then the addShutdownHook and removeShutdownHook methods check that the caller's security context permits RuntimePermission("shutdownHooks"). An untrusted applet will not have this permission, and will therefore not be able to register or de-register a shutdown hook.

What happens if a shutdown hook throws an exception and the exception is not caught?

Uncaught exceptions are handled in shutdown hooks just as in any other thread, by invoking the uncaughtException method of the thread's ThreadGroup object. The default implementation of this method prints the exception's stack trace to System.err and terminates the thread. Note that uncaught exceptions do not cause the VM to exit; this happens only when all non-daemon threads have finished or when the Runtime.exit method is invoked.

Why did you add the Runtime.halt method? Isn't it pretty dangerous?

The new halt method is certainly powerful, and it should be used with the utmost caution. It's provided so that applications can insulate themselves from shutdown hooks that deadlock or run for inordinate amounts of time. It also allows applications to force a quick exit in situations where that is necessary.

What happens if finalization-on-exit is enabled? Will finalizers be run before, during, or after shutdown hooks?

Finalization-on-exit processing is done after all shutdown hooks have finished. Otherwise a hook may fail if some live objects are finalized prematurely.

Copyright © 1999 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


Enhancements in java.lang and java.util.*

Java

Enhancements in
Packages java.lang.* and java.util.*

 Contents
  • Enhancements in Java SE 6
  • Enhancements in J2SE 5.0
  • Enhancements in J2SDK 1.4
  • Enhancements in J2SDK 1.3

Enhancements in Java SE 6

java.util

  • ServiceLoader - A facility to load a specific implementation of a service.
  • Collections Framework Enhancements - There are many enhancements to the Collections framework.

Enhancements in J2SE 5.0

java.lang

  • ProcessBuilder - The new ProcessBuilder class provides a more convenient way to invoke subprocesses than does Runtime.exec. In particular, ProcessBuilder makes it easy to start a subprocess with a modified process environment (that is, one based on the parent's process environment, but with a few changes).
  • Threads - The java.lang.Thread class has the following enhancements:
    • Thread priority handling has changed.
    • Thread.State enum class and the new getState() API are provided for querying the execution state of a thread.
    • The new thread dump API - The getStackTrace and getAllStackTraces methods in the Thread class - provides a programmatic way to obtain the stack trace of a thread or all threads.
    • The uncaughtExceptionHandler mechanism, previously available only through the ThreadGroup class, is now available directly through the Thread class.
    • A new form of the sleep() method is provided which allows for sleep times smaller than one millisecond.

java.lang.instrument

  • Instrumentation - The new java.lang.instrument package provides services that allow Java programming agents to instrument programs running on the Java virtual machine by modifying methods' bytecodes at runtime.

java.util

  • Formatter - An interpreter for printf-style format strings, the Formatter class provides support for layout justification and alignment, common formats for numeric, string, and date/time data, and locale-specific output. Common Java types such as byte, java.math.BigDecimal , and java.util.Calendar are supported. Limited formatting customization for arbitrary user types is provided through the java.util.Formattable interface.
  • Scanner - The java.util.Scanner class can be used to convert text into primitives or Strings. Since it is based on the java.util.regex package, it also offers a way to conduct regular expression based searches on streams, file data, strings, or implementors of the Readable interface.
  • Collections Framework Enhancements - There are many enhancements to the Collections framework.

Enhancements in Java 2 SDK v1.4

java.lang

  • Chained Exception Facility - This is a new facility that provides a common API to record the fact that one exception caused another, to access causative exceptions, and to acess the entire "causal chain" as part of the standard stack backtrace, ensuring that preexisting programs will provide this information with no additional effort on the part of their authors.
  • String - Two split methods are new. The subSequence method has been added, as required by the CharSequence interface that String now implements. Three additional methods have been added: matches, replaceAll, and replaceFirst.
  • StringBuffer - The subSequence method has been added, as required by the CharSequence interface that StringBuffer now implements.
  • Thread - The interrupt method has been revised to interrupt threads blocked in channel-I/O operations.

java.util.logging

  • Logging API - The Java Logging API facilitates software servicing and maintenance at customer sites by producing log reports suitable for analysis by end users, system administrators, field service engineers, and software development teams. The Logging APIs capture information such as security failures, configuration errors, performance bottlenecks, and/or bugs in the application or platform. The core package includes support for delivering plain text or XML formatted log records to memory, output streams, consoles, files, and sockets. In addition, the logging APIs are capable of interacting with logging services that already exist on the host operating system.

java.util.prefs

  • Preferences API - The preferences API, implemented by package java.util.prefs, allows applications to store and retrieve user and system preference and configuration data. This data is stored persistently in an implementation-dependent backing store. The Preferences API is intended to replace most common uses of class java.util.Properties, rectifying many of its deficiencies, while retaining its light weight.

Enhancements in Java 2 SDK 1.3

java.lang

  • java.lang.Math and java.lang.StrictMath - Two new classes which provide APIs for performing general numeric operations.
    • java.lang.StrictMath - Class java.lang.StrictMath has the same API as old class java.lang.Math, which was present in previous versions of the Java platform. Unlike class Math, however, StrictMath is defined to return bit-for-bit reproducible results in all implementations.
    • java.lang.Math - Class java.lang.Math provides the same set of API as does class StrictMath. However, unlike some of the numeric functions of class StrictMath, all implementations of the equivalent functions of class Math are not defined to return the bit-for-bit same results, but can vary within specified constraints. This permits better-performing implementations where strict reproducibility is not required.
  • Timer API - Two new classes to provide an API for a timer facility which can be used for purposes such as animations, human interaction timeouts, on-screen clocks and calendars, work-scheduling routines, reminder facilities, and more.
    • java.util.Timer
    • java.util.TimerTask
    Countdown.java is a simple demo application that uses the Timer API.
  • Virtual Machine Shutdown Hooks Sophisticated applications often require the ability to perform specific actions when the virtual machine shuts down, whether due to voluntary exit or involuntary termination. Typical actions include cleanly closing down network connections, saving session state, and deleting temporary files. Every major operating system provides the means for native applications to do this, though of course the details vary from platform to platform. Three methods have been added to java.lang.Runtime to provide a simple and portable interface to these facitilies. The new methods are:
    • addShutdownHook
    • removeShutdownHook
    • halt
    In addition, the Runtime.exit method has been revised. For more information, see Design of the Shutdown Hooks API.

java.util

  • Enhanced Collections Framework - The Collections Framework has these new convenience APIs:
    • Added Collections.singletonList and Collections.singletonMap. Previously, there was a convenience implementation for singleton Set, but no corresponding implementation for List and Map. Both of these implementations proved desirable in practice.
    • Added Collections.EMPTY_MAP. Previously, there were constant convenience implementations for the empty Set and List, but no corresponding implementation for Map.
    The following special-purpose implementation has also been added:
    • Added Map constuctor for WeakHashMap. The Map interface dictates that most Map implementations should have a "copy constructor" that takes a Map argument. WeakHashMap lacked such a constructor in the 1.2 release.

java.util.jar
java.util.zip

  • New URL JAR File Caching - The API of classes java.util.zip and java.util.jar have been enhanced with the addition of the following:
    • java.util.zip.OPEN_READ
    • java.util.zip.OPEN_DELETE
    • java.util.zip.ZipFile(File file, int mode)
    • java.util.jar.JarFile(File file, boolean verify, int mode)
    The previous implementation of caching downloaded Jar files created problems for long-running server application and for RMI. Each open JarURLConnection creates a temporary local file that holds Jar-file date, and a JarFile object is created on top of the temporary file. Because the open file handle/descriptor on each temporary file was never closed, the files could quickly take up disk space for long-running server applications. The new API provides a solution for this problem by supporting a new "delete-on-close" mode for opening Zip and Jar files.
Copyright © 1999-2006 Sun Microsystems, Inc. All Rights Reserved.
Sun


java.lang.* and java.util.* Packages

 Documentation Contents
  • java.lang - Provides classes that are fundamental to the design of the Java programming language.
  • java.lang.annotation - Provides library support for the Java programming language annotation facility.
  • java.lang.instrument - Provides services that allow Java programming language agents to instrument programs running on the JVM.
  • java.lang.management - Provides the management interface for monitoring and management of the Java virtual machine as well as the operating system on which the Java virtual machine is running.
  • java.lang.ref - Provides reference-object classes, which support a limited degree of interaction with the garbage collector.
  • java.lang.reflect - Provides classes and interfaces for obtaining reflective information about classes and objects.
  • java.util - Contains the collectsions framework, legacy collection classes, event model, date and time facilities, internationalization, and miscellaneous utility classes (a string tokenizer, a random-number generator, and a bit array).
  • java.util.concurrent - Utility classes commonly useful in concurrent programming.
  • java.util.concurrent.atomic - A small toolkit of classes that support lock-free thread-safe programming on single variables.
  • java.util.concurrent.locks - Interfaces and classes providing a framework for locking and waiting for conditions that is distinct from built-in synchronization and monitors.
  • java.util.jar - Provides classes for reading and writing the JAR (Java ARchive) file format, which is based on the standard ZIP file format with an optional manifest file.
  • java.util.logging - Provides the classes and interfaces of the Java 2 platform's core logging facilities.
  • java.util.regex - Classes for matching character sequences against patterns specified by regular expressions.
  • java.util.prefs - This package allows applications to store and retrieve user and system preference and configuration data.
  • java.util.spi - Service provider classes for the classes in the java.util package.
  • java.util.zip - Provides classes for reading and writing the standard ZIP and GZIP file formats.


The java.lang.* and java.util.* Packages

 Documentation Contents

The java.lang and java.util packages provide basic functionality that is used by almost all applications. Other packages with names that begin with java.lang and java.util provide supplemental APIs for specific features.

Package List

Package Enhancements More Information
java.lang
Provides classes that are fundamental to the design of the Java programming language such as String, Math, and basic runtime support for threads and processes.

J2SE 5.0,
J2SDK 1.4, and
J2SDK 1.3
  • Package Version Identification
  • Location-Independent Access to Resources
  • Chained Exception Facility
java.lang.annotation
Provides library support for the Java programming language annotation facility.

New in J2SE 5.0
  • Using Annotations
java.lang.instrument
Provides services that allow Java programming language agents to instrument programs running on the JVM.

Java SE 6 and
J2SE 5.0
  • Instrumenting Applications
java.lang.management
Provides the management interface for monitoring and management of the JVM as well as the operating system on which the JVM is running.

Java SE 6
  • Monitoring and Management
java.lang.ref
Provides reference-object classes, which support a limited degree of interaction with the garbage collector.
New in J2SDK 1.3
java.lang.reflect
Provides classes and interfaces for obtaining reflective information about classes and objects.

Java SE 6,
J2SE 5.0, and
J2SDK 1.4
  • Reflection APIs
java.util
Provides the collections framework, formatted printing and scanning, array manipulation utilities, event model, date and time facilities, internationalization, and miscellaneous utility classes.

Java SE 6,
J2SE 5.0, and
J2SDK 1.3
  • Collections Framework
java.util.concurrent
java.util.concurrent.atomic
java.util.concurrent.locks
Provides utility classes used in concurrent programming, including support for atomic updates of single variables and a locking framework which supplements language-level synchronization.

New in J2SE 5.0
  • Concurrency Utilities
java.util.jar
java.util.zip
Provides classes for reading and writing the standard ZIP and GZIP file formats as well as the JAR (Java ARchive) file format, which is based on the standard ZIP file format with an optional manifest file.

Java SE 6 and
J2SDK 1.3
  • Java Archive (JAR) Files
java.util.logging
Provides support to maintain and service software at customer sites.

J2SE 5.0 and
J2SDK 1.4
  • Java Logging APIs
java.util.regex
Provides classes for matching character sequences against patterns specified by regular expressions.

New in J2SDK 1.4
  • Regular Expressions Tutorial
java.util.prefs
Provides classes to store and retrieve user and system preference and configuration data.

J2SDK 1.4
  • Preferences API
java.util.spi
Service provider classes for the java.util package.

New in Java SE 6

Tutorials and Programmer's Guides

  • The Java Tutorial

API Enhancements

  • Enhancements in Java SE 6
  • Enhancements in J2SE 5.0
  • Enhancements in J2SDK 1.4
  • Enhancements in J2SDK 1.3
Copyright © 2005-2006 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


Annotations

 Language Contents

Many APIs require a fair amount of boilerplate code. For example, in order to write a JAX-RPC web service, you must provide a paired interface and implementation. This boilerplate could be generated automatically by a tool if the program were “decorated” with annotations indicating which methods were remotely accessible.

Other APIs require “side files” to be maintained in parallel with programs. For example JavaBeans requires a BeanInfo class to be maintained in parallel with a bean, and Enterprise JavaBeans (EJB) requires a deployment descriptor. It would be more convenient and less error-prone if the information in these side files were maintained as annotations in the program itself.

The Java platform has always had various ad hoc annotation mechanisms. For example the transient modifier is an ad hoc annotation indicating that a field should be ignored by the serialization subsystem, and the @deprecated javadoc tag is an ad hoc annotation indicating that the method should no longer be used. As of release 5.0, the platform has a general purpose annotation (also known as metadata) facility that permits you to define and use your own annotation types. The facility consists of a syntax for declaring annotation types, a syntax for annotating declarations, APIs for reading annotations, a class file representation for annotations, and an annotation processing tool.

Annotations do not directly affect program semantics, but they do affect the way programs are treated by tools and libraries, which can in turn affect the semantics of the running program. Annotations can be read from source files, class files, or reflectively at run time.

Annotations complement javadoc tags. In general, if the markup is intended to affect or produce documentation, it should probably be a javadoc tag; otherwise, it should be an annotation.

Typical application programmers will never have to define an annotation type, but it is not hard to do so. Annotation type declarations are similar to normal interface declarations. An at-sign (@) precedes the interface keyword. Each method declaration defines an element of the annotation type. Method declarations must not have any parameters or a throws clause. Return types are restricted to primitives, String, Class, enums, annotations, and arrays of the preceding types. Methods can have default values. Here is an example annotation type declaration:

/**
 * Describes the Request-For-Enhancement(RFE) that led
 * to the presence of the annotated API element.
 */
public @interface RequestForEnhancement {
    int    id();
    String synopsis();
    String engineer() default "[unassigned]";
    String date()    default "[unimplemented]";
}

Once an annotation type is defined, you can use it to annotate declarations. An annotation is a special kind of modifier, and can be used anywhere that other modifiers (such as public, static, or final) can be used. By convention, annotations precede other modifiers. Annotations consist of an at-sign (@) followed by an annotation type and a parenthesized list of element-value pairs. The values must be compile-time constants. Here is a method declaration with an annotation corresponding to the annotation type declared above:

@RequestForEnhancement(
    id       = 2868724,
    synopsis = "Enable time-travel",
    engineer = "Mr. Peabody",
    date     = "4/1/3007"
)
public static void travelThroughTime(Date destination) { ... }
An annotation type with no elements is termed a marker annotation type, for example:
/**
 * Indicates that the specification of the annotated API element
 * is preliminary and subject to change.
 */
public @interface Preliminary { }
It is permissible to omit the parentheses in marker annotations, as shown below:
@Preliminary public class TimeTravel { ... }
In annotations with a single element, the element should be named value, as shown below:
/**
 * Associates a copyright notice with the annotated API element.
 */
public @interface Copyright {
    String value();
}
It is permissible to omit the element name and equals sign (=) in a single-element annotation whose element name is value, as shown below:
@Copyright("2002 Yoyodyne Propulsion Systems")
public class OscillationOverthruster { ... }
To tie it all together, we'll build a simple annotation-based test framework. First we need a marker annotation type to indicate that a method is a test method, and should be run by the testing tool:
import java.lang.annotation.*;

/**
 * Indicates that the annotated method is a test method.
 * This annotation should be used only on parameterless static methods.
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Test { }
Note that the annotation type declaration is itself annotated. Such annotations are called meta-annotations. The first (@Retention(RetentionPolicy.RUNTIME)) indicates that annotations with this type are to be retained by the VM so they can be read reflectively at run-time. The second (@Target(ElementType.METHOD)) indicates that this annotation type can be used to annotate only method declarations.

Here is a sample program, some of whose methods are annotated with the above interface:

public class Foo {
    @Test public static void m1() { }
    public static void m2() { }
    @Test public static void m3() {
        throw new RuntimeException("Boom");
    }
    public static void m4() { }
    @Test public static void m5() { }
    public static void m6() { }
    @Test public static void m7() {
        throw new RuntimeException("Crash");
    }
    public static void m8() { }
}
Here is the testing tool:
import java.lang.reflect.*;

public class RunTests {
   public static void main(String[] args) throws Exception {
      int passed = 0, failed = 0;
      for (Method m : Class.forName(args[0]).getMethods()) {
         if (m.isAnnotationPresent(Test.class)) {
            try {
               m.invoke(null);
               passed++;
            } catch (Throwable ex) {
               System.out.printf("Test %s failed: %s %n", m, ex.getCause());
               failed++;
            }
         }
      }
      System.out.printf("Passed: %d, Failed %d%n", passed, failed);
   }
}
The tool takes a class name as a command line argument and iterates over all the methods of the named class attempting to invoke each method that is annotated with the Test annotation type (defined above). The reflective query to find out if a method has a Test annotation is highlighted in green. If a test method invocation throws an exception, the test is deemed to have failed, and a failure report is printed. Finally, a summary is printed showing the number of tests that passed and failed. Here is how it looks when you run the testing tool on the Foo program (above):
$ java RunTests Foo
Test public static void Foo.m3() failed: java.lang.RuntimeException: Boom
Test public static void Foo.m7() failed: java.lang.RuntimeException: Crash
Passed: 2, Failed 2
While this testing tool is clearly a toy, it demonstrates the power of annotations and could easily be extended to overcome its limitations.
Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved. Sun

Java Software


Autoboxing

 Language Contents

As any Java programmer knows, you can’t put an int (or other primitive value) into a collection. Collections can only hold object references, so you have to box primitive values into the appropriate wrapper class (which is Integer in the case of int). When you take the object out of the collection, you get the Integer that you put in; if you need an int, you must unbox the Integer using the intValue method. All of this boxing and unboxing is a pain, and clutters up your code. The autoboxing and unboxing feature automates the process, eliminating the pain and the clutter.

The following example illustrates autoboxing and unboxing, along with generics and the for-each loop. In a mere ten lines of code, it computes and prints an alphabetized frequency table of the words appearing on the command line.

import java.util.*;

// Prints a frequency table of the words on the command line
public class Frequency {
   public static void main(String[] args) {
      Map<String, Integer> m = new TreeMap<String, Integer>();
      for (String word : args) {
          Integer freq = m.get(word);
          m.put(word, (freq == null ? 1 : freq + 1));
      }
      System.out.println(m);
   }
}

java Frequency if it is to be it is up to me to do the watusi
{be=1, do=1, if=1, is=2, it=2, me=1, the=1, to=3, up=1, watusi=1}

The program first declares a map from String to Integer, associating the number of times a word occurs on the command line with the word. Then it iterates over each word on the command line. For each word, it looks up the word in the map. Then it puts a revised entry for the word into the map. The line that does this (highlighted in green) contains both autoboxing and unboxing. To compute the new value to associate with the word, first it looks at the current value (freq). If it is null, this is the first occurrence of the word, so it puts 1 into the map. Otherwise, it adds 1 to the number of prior occurrences and puts that value into the map. But of course you cannot put an int into a map, nor can you add one to an Integer. What is really happening is this: In order to add 1 to freq, it is automatically unboxed, resulting in an expression of type int. Since both of the alternative expressions in the conditional expression are of type int, so too is the conditional expression itself. In order to put this int value into the map, it is automatically boxed into an Integer.

The result of all this magic is that you can largely ignore the distinction between int and Integer, with a few caveats. An Integer expression can have a null value. If your program tries to autounbox null, it will throw a NullPointerException. The == operator performs reference identity comparisons on Integer expressions and value equality comparisons on int expressions. Finally, there are performance costs associated with boxing and unboxing, even if it is done automatically.

Here is another sample program featuring autoboxing and unboxing. It is a static factory that takes an int array and returns a List of Integer backed by the array. In a mere ten lines of code this method provides the full richness of the List interface atop an int array. All changes to the list write through to the array and vice-versa. The lines that use autoboxing or unboxing are highlighted in green:

// List adapter for primitive int array
public static List<Integer> asList(final int[] a) {
    return new AbstractList<Integer>() {
        public Integer get(int i) { return a[i]; }
        // Throws NullPointerException if val == null
        public Integer set(int i, Integer val) {
            Integer oldVal = a[i];
            a[i] = val;
            return oldVal;
        }
        public int size() { return a.length; }
    };
}

The performance of the resulting list is likely to be poor, as it boxes or unboxes on every get or set operation. It is plenty fast enough for occasional use, but it would be folly to use it in a performance critical inner loop.

So when should you use autoboxing and unboxing? Use them only when there is an “impedance mismatch” between reference types and primitives, for example, when you have to put numerical values into a collection. It is not appropriate to use autoboxing and unboxing for scientific computing, or other performance-sensitive numerical code. An Integer is not a substitute for an int; autoboxing and unboxing blur the distinction between primitive types and reference types, but they do not eliminate it.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved. Sun

Java Software


Enums

 Language Contents

In prior releases, the standard way to represent an enumerated type was the int Enum pattern:
// int Enum Pattern - has severe problems!
public static final int SEASON_WINTER = 0;
public static final int SEASON_SPRING = 1;
public static final int SEASON_SUMMER = 2;
public static final int SEASON_FALL   = 3;
This pattern has many problems, such as:
  • Not typesafe - Since a season is just an int you can pass in any other int value where a season is required, or add two seasons together (which makes no sense).
  • No namespace - You must prefix constants of an int enum with a string (in this case SEASON_) to avoid collisions with other int enum types.
  • Brittleness - Because int enums are compile-time constants, they are compiled into clients that use them. If a new constant is added between two existing constants or the order is changed, clients must be recompiled. If they are not, they will still run, but their behavior will be undefined.
  • Printed values are uninformative - Because they are just ints, if you print one out all you get is a number, which tells you nothing about what it represents, or even what type it is.
It is possible to get around these problems by using the Typesafe Enum pattern (see Effective Java Item 21), but this pattern has its own problems: It is quite verbose, hence error prone, and its enum constants cannot be used in switch statements.

In 5.0, the Java™ programming language gets linguistic support for enumerated types. In their simplest form, these enums look just like their C, C++, and C# counterparts:

enum Season { WINTER, SPRING, SUMMER, FALL }

But appearances can be deceiving. Java programming language enums are far more powerful than their counterparts in other languages, which are little more than glorified integers. The new enum declaration defines a full-fledged class (dubbed an enum type). In addition to solving all the problems mentioned above, it allows you to add arbitrary methods and fields to an enum type, to implement arbitrary interfaces, and more. Enum types provide high-quality implementations of all the Object methods. They are Comparable and Serializable, and the serial form is designed to withstand arbitrary changes in the enum type.

Here is an example of a playing card class built atop a couple of simple enum types. The Card class is immutable, and only one instance of each Card is created, so it need not override equals or hashCode:

import java.util.*;

public class Card {
    public enum Rank { DEUCE, THREE, FOUR, FIVE, SIX,
        SEVEN, EIGHT, NINE, TEN, JACK, QUEEN, KING, ACE }

    public enum Suit { CLUBS, DIAMONDS, HEARTS, SPADES }

    private final Rank rank;
    private final Suit suit;
    private Card(Rank rank, Suit suit) {
        this.rank = rank;
        this.suit = suit;
    }

    public Rank rank() { return rank; }
    public Suit suit() { return suit; }
    public String toString() { return rank + " of " + suit; }

    private static final List<Card> protoDeck = new ArrayList<Card>();

    // Initialize prototype deck
    static {
        for (Suit suit : Suit.values())
            for (Rank rank : Rank.values())
                protoDeck.add(new Card(rank, suit));
    }

    public static ArrayList<Card> newDeck() {
        return new ArrayList<Card>(protoDeck); // Return copy of prototype deck
    }
}
The toString method for Card takes advantage of the toString methods for Rank and Suit. Note that the Card class is short (about 25 lines of code). If the typesafe enums (Rank and Suit) had been built by hand, each of them would have been significantly longer than the entire Card class.

The (private) constructor of Card takes two parameters, a Rank and a Suit. If you accidentally invoke the constructor with the parameters reversed, the compiler will politely inform you of your error. Contrast this to the int enum pattern, in which the program would fail at run time.

Note that each enum type has a static values method that returns an array containing all of the values of the enum type in the order they are declared. This method is commonly used in combination with the for-each loop to iterate over the values of an enumerated type.

The following example is a simple program called Deal that exercises Card. It reads two numbers from the command line, representing the number of hands to deal and the number of cards per hand. Then it creates a new deck of cards, shuffles it, and deals and prints the requested hands.

import java.util.*;

public class Deal {
    public static void main(String args[]) {
        int numHands = Integer.parseInt(args[0]);
        int cardsPerHand = Integer.parseInt(args[1]);
        List<Card> deck  = Card.newDeck();
        Collections.shuffle(deck);
        for (int i=0; i < numHands; i++)
            System.out.println(deal(deck, cardsPerHand));
    }

    public static ArrayList<Card> deal(List<Card> deck, int n) {
         int deckSize = deck.size();
         List<Card> handView = deck.subList(deckSize-n, deckSize);
         ArrayList<Card> hand = new ArrayList<Card>(handView);
         handView.clear();
         return hand;
     }
}

$ java Deal 4 5
[FOUR of HEARTS, NINE of DIAMONDS, QUEEN of SPADES, ACE of SPADES, NINE of SPADES]
[DEUCE of HEARTS, EIGHT of SPADES, JACK of DIAMONDS, TEN of CLUBS, SEVEN of SPADES]
[FIVE of HEARTS, FOUR of DIAMONDS, SIX of DIAMONDS, NINE of CLUBS, JACK of CLUBS]
[SEVEN of HEARTS, SIX of CLUBS, DEUCE of DIAMONDS, THREE of SPADES, EIGHT of CLUBS]

Suppose you want to add data and behavior to an enum. For example consider the planets of the solar system. Each planet knows its mass and radius, and can calculate its surface gravity and the weight of an object on the planet. Here is how it looks:

public enum Planet {
    MERCURY (3.303e+23, 2.4397e6),
    VENUS   (4.869e+24, 6.0518e6),
    EARTH   (5.976e+24, 6.37814e6),
    MARS    (6.421e+23, 3.3972e6),
    JUPITER (1.9e+27,   7.1492e7),
    SATURN  (5.688e+26, 6.0268e7),
    URANUS  (8.686e+25, 2.5559e7),
    NEPTUNE (1.024e+26, 2.4746e7),
    PLUTO   (1.27e+22,  1.137e6);

    private final double mass;   // in kilograms
    private final double radius; // in meters
    Planet(double mass, double radius) {
        this.mass = mass;
        this.radius = radius;
    }
    public double mass()   { return mass; }
    public double radius() { return radius; }

    // universal gravitational constant  (m3 kg-1 s-2)
    public static final double G = 6.67300E-11;

    public double surfaceGravity() {
        return G * mass / (radius * radius);
    }
    public double surfaceWeight(double otherMass) {
        return otherMass * surfaceGravity();
    }
}

The enum type Planet contains a constructor, and each enum constant is declared with parameters to be passed to the constructor when it is created.

Here is a sample program that takes your weight on earth (in any unit) and calculates and prints your weight on all of the planets (in the same unit):

    public static void main(String[] args) {
        double earthWeight = Double.parseDouble(args[0]);
        double mass = earthWeight/EARTH.surfaceGravity();
        for (Planet p : Planet.values())
           System.out.printf("Your weight on %s is %f%n",
                             p, p.surfaceWeight(mass));
    }

$ java Planet 175
Your weight on MERCURY is 66.107583
Your weight on VENUS is 158.374842
Your weight on EARTH is 175.000000
Your weight on MARS is 66.279007
Your weight on JUPITER is 442.847567
Your weight on SATURN is 186.552719
Your weight on URANUS is 158.397260
Your weight on NEPTUNE is 199.207413
Your weight on PLUTO is 11.703031

The idea of adding behavior to enum constants can be taken one step further. You can give each enum constant a different behavior for some method. One way to do this by switching on the enumeration constant. Here is an example with an enum whose constants represent the four basic arithmetic operations, and whose eval method performs the operation:

public enum Operation {
    PLUS, MINUS, TIMES, DIVIDE;

    // Do arithmetic op represented by this constant
    double eval(double x, double y){
        switch(this) {
            case PLUS:   return x + y;
            case MINUS:  return x - y;
            case TIMES:  return x * y;
            case DIVIDE: return x / y;
        }
        throw new AssertionError("Unknown op: " + this);
    }
}
This works fine, but it will not compile without the throw statement, which is not terribly pretty. Worse, you must remember to add a new case to the switch statement each time you add a new constant to Operation. If you forget, the eval method with fail, executing the aforementioned throw statement

There is another way give each enum constant a different behavior for some method that avoids these problems. You can declare the method abstract in the enum type and override it with a concrete method in each constant. Such methods are known as constant-specific methods. Here is the previous example redone using this technique:

public enum Operation {
  PLUS   { double eval(double x, double y) { return x + y; } },
  MINUS  { double eval(double x, double y) { return x - y; } },
  TIMES  { double eval(double x, double y) { return x * y; } },
  DIVIDE { double eval(double x, double y) { return x / y; } };

  // Do arithmetic op represented by this constant
  abstract double eval(double x, double y);
}

Here is a sample program that exercises the Operation class. It takes two operands from the command line, iterates over all the operations, and for each operation, performs the operation and prints the resulting equation:

    public static void main(String args[]) {
        double x = Double.parseDouble(args[0]);
        double y = Double.parseDouble(args[1]);
        for (Operation op : Operation.values())
            System.out.printf("%f %s %f = %f%n", x, op, y, op.eval(x, y));
    }

$ java Operation 4 2
4.000000 PLUS 2.000000 = 6.000000
4.000000 MINUS 2.000000 = 2.000000
4.000000 TIMES 2.000000 = 8.000000
4.000000 DIVIDE 2.000000 = 2.000000
Constant-specific methods are reasonably sophisticated, and many programmers will never need to use them, but it is nice to know that they are there if you need them.

Two classes have been added to java.util in support of enums: special-purpose Set and Map implementations called EnumSet and EnumMap. EnumSet is a high-performance Set implementation for enums. All of the members of an enum set must be of the same enum type. Internally, it is represented by a bit-vector, typically a single long. Enum sets support iteration over ranges of enum types. For example given the following enum declaration:

    enum Day { SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY }
you can iterate over the weekdays. The EnumSet class provides a static factory that makes it easy:
    for (Day d : EnumSet.range(Day.MONDAY, Day.FRIDAY))
        System.out.println(d);
Enum sets also provide a rich, typesafe replacement for traditional bit flags:
    EnumSet.of(Style.BOLD, Style.ITALIC)

Similarly, EnumMap is a high-performance Map implementation for use with enum keys, internally implemented as an array. Enum maps combine the richness and safety of the Map interface with speed approaching that of an array. If you want to map an enum to a value, you should always use an EnumMap in preference to an array.

The Card class, above, contains a static factory that returns a deck, but there is no way to get an individual card from its rank and suit. Merely exposing the constructor would destroy the singleton property (that only a single instance of each card is allowed to exist). Here is how to write a static factory that preserves the singleton property, using a nested EnumMap:

private static Map<Suit, Map<Rank, Card>> table =
    new EnumMap<Suit, Map<Rank, Card>>(Suit.class);
static {
    for (Suit suit : Suit.values()) {
        Map<Rank, Card> suitTable = new EnumMap<Rank, Card>(Rank.class);
        for (Rank rank : Rank.values())
            suitTable.put(rank, new Card(rank, suit));
        table.put(suit, suitTable);
    }
}

public static Card valueOf(Rank rank, Suit suit) {
    return table.get(suit).get(rank);
}
The EnumMap (table) maps each suit to an EnumMap that maps each rank to a card. The lookup performed by the valueOf method is internally implemented as two array accesses, but the code is much clearer and safer. In order to preserve the singleton property, it is imperative that the constructor invocation in the prototype deck initialization in Card be replaced by a call to the new static factory:
    // Initialize prototype deck
    static {
        for (Suit suit : Suit.values())
            for (Rank rank : Rank.values())
                protoDeck.add(Card.valueOf(rank, suit));
    }
It is also imperative that the initialization of table be placed above the initialization of protoDeck, as the latter depends on the former.

So when should you use enums? Any time you need a fixed set of constants. That includes natural enumerated types (like the planets, days of the week, and suits in a card deck) as well as other sets where you know all possible values at compile time, such as choices on a menu, rounding modes, command line flags, and the like. It is not necessary that the set of constants in an enum type stay fixed for all time. The feature was specifically designed to allow for binary compatible evolution of enum types.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved. Sun

Java Software


Generics

 Language Contents

When you take an element out of a Collection, you must cast it to the type of element that is stored in the collection. Besides being inconvenient, this is unsafe. The compiler does not check that your cast is the same as the collection's type, so the cast can fail at run time.

Generics provides a way for you to communicate the type of a collection to the compiler, so that it can be checked. Once the compiler knows the element type of the collection, the compiler can check that you have used the collection consistently and can insert the correct casts on values being taken out of the collection.

Here is a simple example taken from the existing Collections tutorial:

// Removes 4-letter words from c. Elements must be strings
static void expurgate(Collection c) {
    for (Iterator i = c.iterator(); i.hasNext(); )
      if (((String) i.next()).length() == 4)
        i.remove();
}

Here is the same example modified to use generics:

// Removes the 4-letter words from c
static void expurgate(Collection<String> c) {
    for (Iterator<String> i = c.iterator(); i.hasNext(); )
      if (i.next().length() == 4)
        i.remove();
}

When you see the code <Type>, read it as “of Type”; the declaration above reads as “Collection of String c.” The code using generics is clearer and safer. We have eliminated an unsafe cast and a number of extra parentheses. More importantly, we have moved part of the specification of the method from a comment to its signature, so the compiler can verify at compile time that the type constraints are not violated at run time. Because the program compiles without warnings, we can state with certainty that it will not throw a ClassCastException at run time. The net effect of using generics, especially in large programs, is improved readability and robustness.

To paraphrase Generics Specification Lead Gilad Bracha, when we declare c to be of type Collection<String>, this tells us something about the variable c that holds true wherever and whenever it is used, and the compiler guarantees it (assuming the program compiles without warnings). A cast, on the other hand, tells us something the programmer thinks is true at a single point in the code, and the VM checks whether the programmer is right only at run time.

While the primary use of generics is collections, there are many other uses. “Holder classes,” such as WeakReference and ThreadLocal, have all been generified, that is, they have been retrofitted to make use of generics. More surprisingly, class Class has been generified. Class literals now function as type tokens, providing both run-time and compile-time type information. This enables a style of static factories exemplified by the getAnnotation method in the new AnnotatedElement interface:

    <T extends Annotation> T getAnnotation(Class<T> annotationType);
This is a generic method. It infers the value of its type parameter T from its argument, and returns an appropriate instance of T, as illustrated by the following snippet:
    Author a = Othello.class.getAnnotation(Author.class);
Prior to generics, you would have had to cast the result to Author. Also you would have had no way to make the compiler check that the actual parameter represented a subclass of Annotation.

Generics are implemented by type erasure: generic type information is present only at compile time, after which it is erased by the compiler. The main advantage of this approach is that it provides total interoperability between generic code and legacy code that uses non-parameterized types (which are technically known as raw types). The main disadvantages are that parameter type information is not available at run time, and that automatically generated casts may fail when interoperating with ill-behaved legacy code. There is, however, a way to achieve guaranteed run-time type safety for generic collections even when interoperating with ill-behaved legacy code.

The java.util.Collections class has been outfitted with wrapper classes that provide guaranteed run-time type safety. They are similar in structure to the synchronized and unmodifiable wrappers. These “checked collection wrappers” are very useful for debugging. Suppose you have a set of strings, s, into which some legacy code is mysteriously inserting an integer. Without the wrapper, you will not find out about the problem until you read the problem element from the set, and an automatically generated cast to String fails. At this point, it is too late to determine the source of the problem. If, however, you replace the declaration:

    Set<String> s = new HashSet<String>();
with this declaration:
    Set<String> s = Collections.checkedSet(new HashSet<String>(), String.class);
the collection will throw a ClassCastException at the point where the legacy code attempts to insert the integer. The resulting stack trace will allow you to diagnose and repair the problem.

You should use generics everywhere you can. The extra effort in generifying code is well worth the gains in clarity and type safety. It is straightforward to use a generic library, but it requires some expertise to write a generic library, or to generify an existing library. There is one caveat: You may not use generics (or any other Tiger features) if you intend to deploy the compiled code on a pre-5.0 virtual machine.

If you are familiar with C++'s template mechanism, you might think that generics are similar, but the similarity is superficial. Generics do not generate a new class for each specialization, nor do they permit “template metaprogramming.”

There is much more to learn about generics. See the Generics Tutorial.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved. Sun

Java Software


Java Programming Language

 Documentation Contents
The Java Programming Language is a general-purpose, concurrent, strongly typed, class-based object-oriented language. It is normally compiled to the bytecode instruction set and binary format defined in the Java Virtual Machine Specification.

Tutorials and Programmer's Guides

  • The Java Tutorial

API Enhancements

  • Enhancements in JDK 5
  • Enhancements in JDK v1.4

More Information

  • Java Language Specification
  • Generics by Gilad Bracha.

Copyright © 2005 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


Java Programming Language Enhancements

 Documentation Contents

Enhancements in JDK 5

  • Generics - This long-awaited enhancement to the type system allows a type or method to operate on objects of various types while providing compile-time type safety. It adds compile-time type safety to the Collections Framework and eliminates the drudgery of casting. See the Generics Tutorial. (JSR 14)
  • Enhanced for Loop - This new language construct eliminates the drudgery and error-proneness of iterators and index variables when iterating over collections and arrays. (JSR 201)
  • Autoboxing/Unboxing - This facility eliminates the drudgery of manual conversion between primitive types (such as int) and wrapper types (such as Integer). (JSR 201)
  • Typesafe Enums - This flexible object-oriented enumerated type facility allows you to create enumerated types with arbitrary methods and fields. It provides all the benefits of the Typesafe Enum pattern ("Effective Java," Item 21) without the verbosity and the error-proneness. (JSR 201)
  • Varargs - This facility eliminates the need for manually boxing up argument lists into an array when invoking methods that accept variable-length argument lists.
  • Static Import - This facility lets you avoid qualifying static members with class names without the shortcomings of the "Constant Interface antipattern." (JSR 201)
  • Annotations (Metadata) - This language feature lets you avoid writing boilerplate code under many circumstances by enabling tools to generate it from annotations in the source code. This leads to a "declarative" programming style where the programmer says what should be done and tools emit the code to do it. Also it eliminates the need for maintaining "side files" that must be kept up to date with changes in source files. Instead the information can be maintained in the source file. (JSR 175)
    NOTE: The @Deprecated annotation provides a way to deprecate program elements. See How and When To Deprecate APIs.
Generics papers

  • JSR14: Adding Generic Types to the Java Programming Language
    • Generics Tutorial (PDF) Bracha
    • Latest JSR14 draft specification which includes an older prototype release of javac
    • Earlier public review draft specification from Java Community Process
  • Making the Future Safe for the Past: Adding Genericity to the Java Programming Language (PDF)
    Bracha, Odersky, Stoutamire, and Wadler. OOPSLA 98, Vancouver, October 1998. ( other formats)
  • GJ: Extending the Java Programming Language with Type Parameters (PDF)
    Bracha, Odersky, Stoutamire, and Wadler. A tutorial on GJ. August 1998. ( other formats)
  • Adding Generics to the Java Programming Language (PDF)
    Bracha. Slides from JavaOne 2003 presentation.
  • Adding Wildcards to the Java Programming Language (PDF)
    Torgersen, Hansen, Ernst, Ahe, Bracha and Gafter. An ACM paper, 2004.
General papers
  • New Language Features for Ease of Development in J2SE 5.0: A Conversation with Joshua Bloch
  • Forthcoming Java Programming Language Features (PDF)

Enhancements in JDK v1.4

  • Assertion Facility - Assertions are boolean expressions that the programmer believes to be true concerning the state of a computer program. For example, after sorting a list, the programmer might assert that the list is in ascending order. Evaluating assertions at runtime to confirm their validity is one of the most powerful tools for improving code quality, as it quickly uncovers the programmer's misconceptions concerning a program's behavior.


Programming With Assertions

 Documentation Contents

An assertion is a statement in the JavaTM programming language that enables you to test your assumptions about your program. For example, if you write a method that calculates the speed of a particle, you might assert that the calculated speed is less than the speed of light.

Each assertion contains a boolean expression that you believe will be true when the assertion executes. If it is not true, the system will throw an error. By verifying that the boolean expression is indeed true, the assertion confirms your assumptions about the behavior of your program, increasing your confidence that the program is free of errors.

Experience has shown that writing assertions while programming is one of the quickest and most effective ways to detect and correct bugs. As an added benefit, assertions serve to document the inner workings of your program, enhancing maintainability.

This document shows you how to program with assertions. It covers the topics:

  • Introduction
  • Putting Assertions Into Your Code
  • Compiling Files That Use Assertions
  • Enabling and Disabling Assertions
  • Compatibility With Existing Programs
  • Design FAQ

Introduction

The assertion statement has two forms. The first, simpler form is:

assert Expression1 ;

where Expression1 is a boolean expression. When the system runs the assertion, it evaluates Expression1 and if it is false throws an AssertionError with no detail message.

The second form of the assertion statement is:

assert Expression1 : Expression2 ;

where:

  • Expression1 is a boolean expression.
  • Expression2 is an expression that has a value. (It cannot be an invocation of a method that is declared void.)

Use this version of the assert statement to provide a detail message for the AssertionError. The system passes the value of Expression2 to the appropriate AssertionError constructor, which uses the string representation of the value as the error's detail message.

The purpose of the detail message is to capture and communicate the details of the assertion failure. The message should allow you to diagnose and ultimately fix the error that led the assertion to fail. Note that the detail message is not a user-level error message, so it is generally unnecessary to make these messages understandable in isolation, or to internationalize them. The detail message is meant to be interpreted in the context of a full stack trace, in conjunction with the source code containing the failed assertion.

Like all uncaught exceptions, assertion failures are generally labeled in the stack trace with the file and line number from which they were thrown. The second form of the assertion statement should be used in preference to the first only when the program has some additional information that might help diagnose the failure. For example, if Expression1 involves the relationship between two variables x and y, the second form should be used. Under these circumstances, a reasonable candidate for Expression2 would be "x: " + x + ", y: " + y.

In some cases Expression1 may be expensive to evaluate. For example, suppose you write a method to find the minimum element in an unsorted list, and you add an assertion to verify that the selected element is indeed the minimum. The work done by the assert will be at least as expensive as the work done by the method itself. To ensure that assertions are not a performance liability in deployed applications, assertions can be enabled or disabled when the program is started, and are disabled by default. Disabling assertions eliminates their performance penalty entirely. Once disabled, they are essentially equivalent to empty statements in semantics and performance. See Enabling and Disabling Assertions for more information.

The addition of the assert keyword to the Java programming language has implications for existing code. See Compatibility With Existing Programs for more information.

Putting Assertions Into Your Code

There are many situations where it is good to use assertions, including:

  • Internal Invariants
  • Control-Flow Invariants
  • Preconditions, Postconditions, and Class Invariants

There are also situations where you should not use them:

  • Do not use assertions for argument checking in public methods.

    Argument checking is typically part of the published specifications (or contract) of a method, and these specifications must be obeyed whether assertions are enabled or disabled. Another problem with using assertions for argument checking is that erroneous arguments should result in an appropriate runtime exception (such as IllegalArgumentException, IndexOutOfBoundsException, or NullPointerException). An assertion failure will not throw an appropriate exception.

  • Do not use assertions to do any work that your application requires for correct operation.

    Because assertions may be disabled, programs must not assume that the boolean expression contained in an assertion will be evaluated. Violating this rule has dire consequences. For example, suppose you wanted to remove all of the null elements from a list names, and knew that the list contained one or more nulls. It would be wrong to do this:

    // Broken! - action is contained in assertion
assert names.remove(null);

    The program would work fine when asserts were enabled, but would fail when they were disabled, as it would no longer remove the null elements from the list. The correct idiom is to perform the action before the assertion and then assert that the action succeeded:

    // Fixed - action precedes assertion
boolean nullsRemoved = names.remove(null);
assert nullsRemoved;  // Runs whether or not asserts are enabled

    As a rule, the expressions contained in assertions should be free of side effects: evaluating the expression should not affect any state that is visible after the evaluation is complete. One exception to this rule is that assertions can modify state that is used only from within other assertions. An idiom that makes use of this exception is presented later in this document.

Internal Invariants

Before assertions were available, many programmers used comments to indicate their assumptions concerning a program's behavior. For example, you might have written something like this to explain your assumption about an else clause in a multiway if-statement:

if (i % 3 == 0) {
    ...
} else if (i % 3 == 1) {
    ...
} else { // We know (i % 3 == 2)
    ...
}

You should now use an assertion whenever you would have written a comment that asserts an invariant. For example, you should rewrite the previous if-statement like this:

if (i % 3 == 0) {
   ...
} else if (i % 3 == 1) {
    ...
} else {
    assert i % 3 == 2 : i;
    ...
}

Note, incidentally, that the assertion in the above example may fail if i is negative, as the % operator is not a true modulus operator, but computes the remainder, which may be negative.

Another good candidate for an assertion is a switch statement with no default case. The absence of a default case typically indicates that a programmer believes that one of the cases will always be executed. The assumption that a particular variable will have one of a small number of values is an invariant that should be checked with an assertion. For example, suppose the following switch statement appears in a program that handles playing cards:

switch(suit) {
  case Suit.CLUBS:
    ...
  break;

  case Suit.DIAMONDS:
    ...
  break;

  case Suit.HEARTS:
    ...
    break;

  case Suit.SPADES:
      ...
}

It probably indicates an assumption that the suit variable will have one of only four values. To test this assumption, you should add the following default case:

default:
    assert false : suit;

If the suit variable takes on another value and assertions are enabled, the assert will fail and an AssertionError will be thrown.

An acceptable alternative is:

default:
    throw new AssertionError(suit);

This alternative offers protection even if assertions are disabled, but the extra protection adds no cost: the throw statement won't execute unless the program has failed. Moreover, the alternative is legal under some circumstances where the assert statement is not. If the enclosing method returns a value, each case in the switch statement contains a return statement, and no return statement follows the switch statement, then it would cause a syntax error to add a default case with an assertion. (The method would return without a value if no case matched and assertions were disabled.)

Control-Flow Invariants

The previous example not only tests an invariant, it also checks an assumption about the application's flow of control. The author of the original switch statement probably assumed not only that the suit variable would always have one of four values, but also that one of the four cases would always be executed. It points out another general area where you should use assertions: place an assertion at any location you assume will not be reached. The assertions statement to use is:

assert false;

For example, suppose you have a method that looks like this:

void foo() {
    for (...) {
      if (...)
        return;
    }
    // Execution should never reach this point!!!
}

Replace the final comment so that the code now reads:

void foo() {
    for (...) {
      if (...)
        return;
    }
    assert false; // Execution should never reach this point!
}

Note: Use this technique with discretion. If a statement is unreachable as defined in the Java Language Specification ( JLS 14.20), you will get a compile time error if you try to assert that it is not reached. Again, an acceptable alternative is simply to throw an AssertionError.

Preconditions, Postconditions, and Class Invariants

While the assert construct is not a full-blown design-by-contract facility, it can help support an informal design-by-contract style of programming. This section shows you how to use asserts for:

  • Preconditions — what must be true when a method is invoked.
    • Lock-Status Preconditions — preconditions concerning whether or not a given lock is held.
  • Postconditions — what must be true after a method completes successfully.
  • Class invariants — what must be true about each instance of a class.

Preconditions

By convention, preconditions on public methods are enforced by explicit checks that throw particular, specified exceptions. For example:

/**
  * Sets the refresh rate.
  *
  * @param  rate refresh rate, in frames per second.
  * @throws IllegalArgumentException if rate <= 0 or
  * rate > MAX_REFRESH_RATE.
*/
public void setRefreshRate(int rate) {
  // Enforce specified precondition in public method
  if (rate <= 0 || rate > MAX_REFRESH_RATE)
    throw new IllegalArgumentException("Illegal rate: " + rate);
    setRefreshInterval(1000/rate);
  }

This convention is unaffected by the addition of the assert construct. Do not use assertions to check the parameters of a public method. An assert is inappropriate because the method guarantees that it will always enforce the argument checks. It must check its arguments whether or not assertions are enabled. Further, the assert construct does not throw an exception of the specified type. It can throw only an AssertionError.

You can, however, use an assertion to test a nonpublic method's precondition that you believe will be true no matter what a client does with the class. For example, an assertion is appropriate in the following "helper method" that is invoked by the previous method:

/**
 * Sets the refresh interval (which must correspond to a legal frame rate).
 *
 * @param  interval refresh interval in milliseconds.
*/
 private void setRefreshInterval(int interval) {
  // Confirm adherence to precondition in nonpublic method
  assert interval > 0 && interval <= 1000/MAX_REFRESH_RATE : interval;

  ... // Set the refresh interval
 }

Note, the above assertion will fail if MAX_REFRESH_RATE is greater than 1000 and the client selects a refresh rate greater than 1000. This would, in fact, indicate a bug in the library!

Lock-Status Preconditions

Classes designed for multithreaded use often have non-public methods with preconditions relating to whether or not some lock is held. For example, it is not uncommon to see something like this:

private Object[] a;
public synchronized int find(Object key) {
  return find(key, a, 0, a.length);
}

// Recursive helper method - always called with a lock on this object
private int find(Object key, Object[] arr, int start, int len) {
 ...
}

A static method called holdsLock has been added to the Thread class to test whether the current thread holds the lock on a specified object. This method can be used in combination with an assert statement to supplement a comment describing a lock-status precondition, as shown in the following example:

// Recursive helper method - always called with a lock on this.
private int find(Object key, Object[] arr, int start, int len) {
  assert Thread.holdsLock(this); // lock-status assertion
  ...
}

Note that it is also possible to write a lock-status assertion asserting that a given lock isn't held.

Postconditions

You can test postcondition with assertions in both public and nonpublic methods. For example, the following public method uses an assert statement to check a post condition:

 /**
  * Returns a BigInteger whose value is (this-1 mod m).
  *
  * @param  m the modulus.
  * @return this-1 mod m.
  * @throws ArithmeticException  m <= 0, or this BigInteger
  *has no multiplicative inverse mod m (that is, this BigInteger
  *is not relatively prime to m).
  */
public BigInteger modInverse(BigInteger m) {
  if (m.signum <= 0)
    throw new ArithmeticException("Modulus not positive: " + m);
  ... // Do the computation
  assert this.multiply(result).mod(m).equals(ONE) : this;
  return result;
}

Occasionally it is necessary to save some data prior to performing a computation in order to check a postcondition. You can do this with two assert statements and a simple inner class that saves the state of one or more variables so they can be checked (or rechecked) after the computation. For example, suppose you have a piece of code that looks like this:

 void foo(int[] array) {
  // Manipulate array
  ...

  // At this point, array will contain exactly the ints that it did
  // prior to manipulation, in the same order.
 }

Here is how you could modify the above method to turn the textual assertion of a postcondition into a functional one:

 void foo(final int[] array) {

  // Inner class that saves state and performs final consistency check
  class DataCopy {
private int[] arrayCopy;

DataCopy() { arrayCopy = (int[]) array.clone(); }

boolean isConsistent() { return Arrays.equals(array, arrayCopy); }
  }

  DataCopy copy = null;

  // Always succeeds; has side effect of saving a copy of array
  assert ((copy = new DataCopy()) != null);

  ... // Manipulate array

  // Ensure array has same ints in same order as before manipulation.
  assert copy.isConsistent();
  }

You can easily generalize this idiom to save more than one data field, and to test arbitrarily complex assertions concerning pre-computation and post-computation values.

You might be tempted to replace the first assert statement (which is executed solely for its side-effect) by the following, more expressive statement:

 copy = new DataCopy();

Don't make this replacement. The statement above would copy the array whether or not asserts were enabled, violating the principle that assertions should have no cost when disabled.

Class Invariants

A class invariant is a type of internal invariant that applies to every instance of a class at all times, except when an instance is in transition from one consistent state to another. A class invariant can specify the relationships among multiple attributes, and should be true before and after any method completes. For example, suppose you implement a balanced tree data structure of some sort. A class invariant might be that the tree is balanced and properly ordered.

The assertion mechanism does not enforce any particular style for checking invariants. It is sometimes convenient, though, to combine the expressions that check required constraints into a single internal method that can be called by assertions. Continuing the balanced tree example, it might be appropriate to implement a private method that checked that the tree was indeed balanced as per the dictates of the data structure:

 // Returns true if this tree is properly balanced
 private boolean balanced() {
  ...
 }

Because this method checks a constraint that should be true before and after any method completes, each public method and constructor should contain the following line immediately prior to its return:

 assert balanced();

It is generally unnecessary to place similar checks at the head of each public method unless the data structure is implemented by native methods. In this case, it is possible that a memory corruption bug could corrupt a "native peer" data structure in between method invocations. A failure of the assertion at the head of such a method would indicate that such memory corruption had occurred. Similarly, it may be advisable to include class invariant checks at the heads of methods in classes whose state is modifiable by other classes. (Better yet, design classes so that their state is not directly visible to other classes!)

Advanced Uses

The following sections discuss topics that apply only to resource-constrained devices and to systems where asserts must not be disabled in the field. If you have no interest in these topics, skip to the next section, "Compiling Files that Use Assertions".

Removing all Trace of Assertions from Class Files

Programmers developing applications for resource-constrained devices may wish to strip assertions out of class files entirely. While this makes it impossible to enable assertions in the field, it also reduces class file size, possibly leading to improved class loading performance. In the absence of a high quality JIT, it could lead to decreased footprint and improved runtime performance.

The assertion facility offers no direct support for stripping assertions out of class files. The assert statement may, however, be used in conjunction with the "conditional compilation" idiom described in JLS 14.20, enabling the compiler to eliminate all traces of these asserts from the class files that it generates:

 static final boolean asserts = ... ; // false to eliminate asserts

 if (asserts)
  assert <expr> ;

Requiring that Assertions are Enabled

Programmers of certain critical systems might wish to ensure that assertions are not disabled in the field. The following static initialization idiom prevents a class from being initialized if its assertions have been disabled:

 static {
  boolean assertsEnabled = false;
  assert assertsEnabled = true; // Intentional side effect!!!
  if (!assertsEnabled)
throw new RuntimeException("Asserts must be enabled!!!");
 }

Put this static-initializer at the top of your class.

Compiling Files That Use Assertions

In order for the javac compiler to accept code containing assertions, you must use the -source 1.4 command-line option as in this example:

 javac -source 1.4 MyClass.java

This flag is necessary so as not to cause source compatibility problems.

Enabling and Disabling Assertions

By default, assertions are disabled at runtime. Two command-line switches allow you to selectively enable or disable assertions.

To enable assertions at various granularities, use the -enableassertions, or -ea, switch. To disable assertions at various granularities, use the -disableassertions, or -da, switch. You specify the granularity with the arguments that you provide to the switch:

  • no arguments
    Enables or disables assertions in all classes except system classes.
  • packageName...
    Enables or disables assertions in the named package and any subpackages.
  • ...
    Enables or disables assertions in the unnamed package in the current working directory.
  • className
    Enables or disables assertions in the named class

For example, the following command runs a program, BatTutor, with assertions enabled in only package com.wombat.fruitbat and its subpackages:

 java -ea:com.wombat.fruitbat... BatTutor

If a single command line contains multiple instances of these switches, they are processed in order before loading any classes. For example, the following command runs the BatTutor program with assertions enabled in package com.wombat.fruitbat but disabled in class com.wombat.fruitbat.Brickbat:

 java -ea:com.wombat.fruitbat... -da:com.wombat.fruitbat.Brickbat BatTutor

The above switches apply to all class loaders. With one exception, they also apply to system classes (which do not have an explicit class loader). The exception concerns the switches with no arguments, which (as indicated above) do not apply to system classes.This behavior makes it easy to enable asserts in all classes except for system classes, which is commonly desirable.

To enable assertions in all system classes, use a different switch: -enablesystemassertions, or -esa. Similarly, to disable assertions in system classes, use -disablesystemassertions, or -dsa.

For example, the following command runs the BatTutor program with assertions enabled in system classes, as well as in the com.wombat.fruitbat package and its subpackages:

 java -esa -ea:com.wombat.fruitbat...

The assertion status of a class (enabled or disabled) is set at the time it is initialized, and does not change. There is, however, one corner case that demands special treatment. It is possible, though generally not desirable, to execute methods or constructors prior to initialization. This can happen when a class hierarchy contains a circularity in its static initialization.

If an assert statement executes before its class is initialized, the execution must behave as if assertions were enabled in the class. This topic is discussed in detail in the assertions specification.

Compatibility With Existing Programs

The addition of the assert keyword to the Java programming language does not cause any problems with preexisting binaries (.class files). If you try to compile an application that uses assert as an identifier, however, you will receive a warning or error message. In order to ease the transition from a world where assert is a legal identifier to one where it isn't, the compiler supports two modes of operation in this release:

  • source mode 1.3 (default) — the compiler accepts programs that use assert as an identifier, but issues warnings. In this mode, programs are not permitted to use the assert statement.
  • source mode 1.4 — the compiler generates an error message if the program uses assert as an identifier. In this mode, programs are permitted to use the assert statement.

Unless you specifically request source mode 1.4 with the -source 1.4 flag, the compiler operates in source mode 1.3. If you forget to use this this flag, programs that use the new assert statement will not compile. Having the compiler use the old semantics as its default behavior (that is, allowing assert to be used as an identifier) was done for maximal source compatibility. Source mode 1.3 is likely to be phased out over time.

Design FAQ

Here is a collection of frequently asked questions concerning the design of the assertion facility.

  • General Questions
  • Compatibility
  • Syntax and Semantics
  • The AssertionError Class
  • Enabling and Disabling Assertions

General Questions
  • Why provide an assertion facility, given that one can program assertions atop the Java programming language with no special support?

    Although ad hoc implementations are possible, they are of necessity either ugly (requiring an if statement for each assertion) or inefficient (evaluating the condition even if assertions are disabled). Further, each ad hoc implementation has its own means of enabling and disabling assertions, which lessens the utility of these implementations, especially for debugging in the field. As a result of these shortcomings, assertions have never become a part of the culture among engineers using the Java programming language. Adding assertion support to the platform stands a good chance of rectifying this situation.

  • Why does this facility justify a language change, as opposed to a library solution?

    We recognize that a language change is a serious effort, not to be undertaken lightly. The library approach was considered. It was, however, deemed essential that the runtime cost of assertions be negligible if they are disabled. In order to achieve this with a library, the programmer is forced to hard-code each assertion as an if statement. Many programmers would not do this. Either they would omit the if statement and performance would suffer, or they would ignore the facility entirely. Note also that assertions were contained in James Gosling's original specification for the Java programming language. Assertions were removed from the Oak specification because time constraints prevented a satisfactory design and implementation.

  • Why not provide a full-fledged design-by-contract facility with preconditions, postconditions and class invariants, like the one in the Eiffel programming language?

    We considered providing such a facility, but were unable to convince ourselves that it is possible to graft it onto the Java programming language without massive changes to the Java platform libraries, and massive inconsistencies between old and new libraries. Further, we were not convinced that such a facility would preserve the simplicity that is the hallmark of the Java programming language. On balance, we came to the conclusion that a simple boolean assertion facility was a fairly straight-forward solution and far less risky. It's worth noting that adding a boolean assertion facility to the language doesn't preclude adding a full-fledged design-by-contract facility at some time in the future.

    The simple assertion facility does enable a limited form of design-by-contract style programming. The assert statement is appropriate for nonpublic precondition, postcondition and class invariant checking. Public precondition checking should still be performed by checks inside methods that result in particular, documented exceptions, such as IllegalArgumentException and IllegalStateException.

  • In addition to boolean assertions, why not provide an assert-like construct to suppress the execution of an entire block of code if assertions are disabled?

    Providing such a construct would encourage programmers to put complex assertions inline, when they are better relegated to separate methods.

Compatibility
  • Won't the new keyword cause compatibility problems with existing programs that use assert as an identifier?

    Yes, for source files. (Binaries for classes that use assert as an identifier will continue to work fine.) To ease the transition, we implemented a strategy whereby developers can continue using assert as an identifier during a transitional period.

  • Doesn't this facility produce class files that cannot be run against older JREs?

    Yes. Class files will contain calls to the new ClassLoader and Class methods, such as desiredAssertionStatus. If a class file containing calls to these methods is run against an older JRE (whose ClassLoader class doesn't define the methods), the program will fail at run time, throwing a NoSuchMethodError. It is generally the case that programs using new facilities are not compatible with older releases.

Syntax and Semantics
  • Why allow primitive types in Expression2?

    There is no compelling reason to restrict the type of this expression. Allowing arbitrary types provides convenience for developers who, for example, want to associate a unique integer code with each assertion. Further, it makes this expression feel like the argument of System.out.println(...), which is seen as desirable.

The AssertionError Class
  • When an AssertionError is generated by an assert statement in which Expression2 is absent, why isn't the program text of the asserted condition used as the detail message (for example, "height < maxHeight")?

    While doing so might improve out-of-the-box usefulness of assertions in some cases, the benefit doesn't justify the cost of adding all those string constants to .class files and runtime images.

  • Why doesn't an AssertionError allow access to the object that generated it? Similarly, why not pass an arbitrary object from the assertion to the AssertionError constructor in place of a detail message?

    Access to these objects would encourage programmers to attempt to recover from assertion failures, which defeats the purpose of the facility.

  • Why not provide context accessors (like getFile, getline, getMethod) on AssertionError?

    This facility is best provided on Throwable, so it may be used for all throwables, not just just assertion errors. We enhanced Throwable with the getStackTrace method to provide this functionality.

  • Why is AssertionError a subclass of Error rather than RuntimeException?

    This issue was controversial. The expert group discussed it at at length, and came to the conclusion that Error was more appropriate to discourage programmers from attempting to recover from assertion failures. It is, in general, difficult or impossible to localize the source of an assertion failure. Such a failure indicates that the program is operating "outside of known space," and attempts to continue execution are likely to be harmful. Further, convention dictates that methods specify most runtime exceptions they may throw (with @throws doc comments). It makes little sense to include in a method's specification the circumstances under which it may generate an assertion failure. Such information may be regarded as an implementation detail, which can change from implementation to implementation and release to release.

Enabling and Disabling Assertions
  • Why not provide a compiler flag to completely eliminate assertions from object files?

    It is a firm requirement that it be possible to enable assertions in the field, for enhanced serviceability. It would have been possible to also permit developers to eliminate assertions from object files at compile time. Assertions can contain side effects, though they should not, and such a flag could therefore alter the behavior of a program in significant ways. It is viewed as good thing that there is only one semantics associated with each valid Java program. Also, we want to encourage users to leave asserts in object files so they can be enabled in the field. Finally, the spec demands that assertions behave as if enabled when a class runs before it is initialized. It would be impossible to offer these semantics if assertions were stripped from the class file. Note, however, that the standard "conditional compilation idiom" described in JLS 14.20 can be used to achieve this effect for developers who really want it.

  • Why do the commands that enable and disable assertions use package-tree semantics instead of the more traditional package semantics?

    Hierarchical control is useful, as programmers really do use package hierarchies to organize their code. For example, package-tree semantics allow assertions to be enabled or disabled in all of Swing at one time.

  • Why does setClassAssertionStatus return a boolean instead of throwing an exception if it is invoked when it's too late to set the assertion status (that is, if the named class has already been initialized)?

    No action (other than perhaps a warning message) is necessary or desirable if it's too late to set the assertion status. An exception seems unduly heavyweight.

  • Why not overload a single method name to take the place of setDefaultAssertionStatus and setAssertionStatus?

    Clarity in method naming is for the greater good. Overloading tends to cause confusion.

  • Why not tweak the semantics of desiredAssertionStatus to make it more "programmer friendly" by returning the actual assertion status if a class is already initialized?

    It's not clear that there would be any use for the resulting method. The method isn't designed for application programmer use, and it seems inadvisable to make it slower and more complex than necessary.

  • Why is there no RuntimePermission to prevent applets from enabling/disabling assertions?

    While applets have no reason to call any of the ClassLoader methods for modifying assertion status, allowing them to do so seems harmless. At worst, an applet can mount a weak denial-of-service attack by enabling assertions in classes that have yet to be initialized. Moreover, applets can only affect the assert status of classes that are to be loaded by class loaders that the applets can access. There already exists a RuntimePermission to prevent untrusted code from gaining access to class loaders (getClassLoader).

  • Why not provide a construct to query the assert status of the containing class?

    Such a construct would encourage people to inline complex assertion code, which we view as a bad thing. Further, it is straightforward to query the assert status atop the current API, if you feel you must:

    boolean assertsEnabled = false;
assert assertsEnabled = true;  // Intentional side-effect!!!
// Now assertsEnabled is set to the correct value
  • Why does an assert statement that executes before its class is initialized behave as if assertions were enabled in the class?

    • Few programmers are aware of the fact that a class's constructors and methods can run prior to its initialization. When this happens, it is quite likely that the class's invariants have not yet been established, which can cause serious and subtle bugs. Any assertion that executes in this state is likely to fail, alerting the programmer to the problem. Thus, it is generally helpful to the programmer to execute all assertions encountered while in this state.

Sun
Java Software

Copyright © 2002 Sun Microsystems, Inc. All Rights Reserved.


Static Import

 Language Contents

In order to access static members, it is necessary to qualify references with the class they came from. For example, one must say:
double r = Math.cos(Math.PI * theta);
In order to get around this, people sometimes put static members into an interface and inherit from that interface. This is a bad idea. In fact, it's such a bad idea that there's a name for it: the Constant Interface Antipattern (see Effective Java Item 17). The problem is that a class's use of the static members of another class is a mere implementation detail. When a class implements an interface, it becomes part of the class's public API. Implementation details should not leak into public APIs.

The static import construct allows unqualified access to static members without inheriting from the type containing the static members. Instead, the program imports the members, either individually:

import static java.lang.Math.PI;
or en masse:
import static java.lang.Math.*;
Once the static members have been imported, they may be used without qualification:
double r = cos(PI * theta);
The static import declaration is analogous to the normal import declaration. Where the normal import declaration imports classes from packages, allowing them to be used without package qualification, the static import declaration imports static members from classes, allowing them to be used without class qualification.

So when should you use static import? Very sparingly! Only use it when you'd otherwise be tempted to declare local copies of constants, or to abuse inheritance (the Constant Interface Antipattern). In other words, use it when you require frequent access to static members from one or two classes. If you overuse the static import feature, it can make your program unreadable and unmaintainable, polluting its namespace with all the static members you import. Readers of your code (including you, a few months after you wrote it) will not know which class a static member comes from. Importing all of the static members from a class can be particularly harmful to readability; if you need only one or two members, import them individually. Used appropriately, static import can make your program more readable, by removing the boilerplate of repetition of class names.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved. Sun

Java Software


The For-Each Loop

 Language Contents

Iterating over a collection is uglier than it needs to be. Consider the following method, which takes a collection of timer tasks and cancels them:
void cancelAll(Collection<TimerTask> c) {
    for (Iterator<TimerTask> i = c.iterator(); i.hasNext(); )
        i.next().cancel();
}

The iterator is just clutter. Furthermore, it is an opportunity for error. The iterator variable occurs three times in each loop: that is two chances to get it wrong. The for-each construct gets rid of the clutter and the opportunity for error. Here is how the example looks with the for-each construct:

void cancelAll(Collection<TimerTask> c) {
    for (TimerTask t : c)
        t.cancel();
}

When you see the colon (:) read it as “in.” The loop above reads as “for each TimerTask t in c.” As you can see, the for-each construct combines beautifully with generics. It preserves all of the type safety, while removing the remaining clutter. Because you don't have to declare the iterator, you don't have to provide a generic declaration for it. (The compiler does this for you behind your back, but you need not concern yourself with it.)

Here is a common mistake people make when they are trying to do nested iteration over two collections:

List suits = ...;
List ranks = ...;
List sortedDeck = new ArrayList();

// BROKEN - throws NoSuchElementException!
for (Iterator i = suits.iterator(); i.hasNext(); )
    for (Iterator j = ranks.iterator(); j.hasNext(); )
        sortedDeck.add(new Card(i.next(), j.next()));

Can you spot the bug? Don't feel bad if you can't. Many expert programmers have made this mistake at one time or another. The problem is that the next method is being called too many times on the “outer” collection (suits). It is being called in the inner loop for both the outer and inner collections, which is wrong. In order to fix it, you have to add a variable in the scope of the outer loop to hold the suit:

// Fixed, though a bit ugly
for (Iterator i = suits.iterator(); i.hasNext(); ) {
    Suit suit = (Suit) i.next();
    for (Iterator j = ranks.iterator(); j.hasNext(); )
        sortedDeck.add(new Card(suit, j.next()));
}

So what does all this have to do with the for-each construct? It is tailor-made for nested iteration! Feast your eyes:

for (Suit suit : suits)
    for (Rank rank : ranks)
        sortedDeck.add(new Card(suit, rank));

The for-each construct is also applicable to arrays, where it hides the index variable rather than the iterator. The following method returns the sum of the values in an int array:

// Returns the sum of the elements of a
int sum(int[] a) {
    int result = 0;
    for (int i : a)
        result += i;
    return result;
}

So when should you use the for-each loop? Any time you can. It really beautifies your code. Unfortunately, you cannot use it everywhere. Consider, for example, the expurgate method. The program needs access to the iterator in order to remove the current element. The for-each loop hides the iterator, so you cannot call remove. Therefore, the for-each loop is not usable for filtering. Similarly it is not usable for loops where you need to replace elements in a list or array as you traverse it. Finally, it is not usable for loops that must iterate over multiple collections in parallel. These shortcomings were known by the designers, who made a conscious decision to go with a clean, simple construct that would cover the great majority of cases.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved. Sun

Java Software


Varargs

 Language Contents

In past releases, a method that took an arbitrary number of values required you to create an array and put the values into the array prior to invoking the method. For example, here is how one used the MessageFormat class to format a message:
Object[] arguments = {
    new Integer(7),
    new Date(),
    "a disturbance in the Force"
};

String result = MessageFormat.format(
    "At {1,time} on {1,date}, there was {2} on planet "
     + "{0,number,integer}.", arguments);

It is still true that multiple arguments must be passed in an array, but the varargs feature automates and hides the process. Furthermore, it is upward compatible with preexisting APIs. So, for example, the MessageFormat.format method now has this declaration:

    public static String format(String pattern,
                                Object... arguments);

The three periods after the final parameter's type indicate that the final argument may be passed as an array or as a sequence of arguments. Varargs can be used only in the final argument position. Given the new varargs declaration for MessageFormat.format, the above invocation may be replaced by the following shorter and sweeter invocation:

String result = MessageFormat.format(
    "At {1,time} on {1,date}, there was {2} on planet "
    + "{0,number,integer}.",
    7, new Date(), "a disturbance in the Force");

There is a strong synergy between autoboxing and varargs, which is illustrated in the following program using reflection:

// Simple test framework
public class Test {
    public static void main(String[] args) {
        int passed = 0;
        int failed = 0;
        for (String className : args) {
            try {
                Class c = Class.forName(className);
                c.getMethod("test").invoke(c.newInstance());
                passed++;
            } catch (Exception ex) {
                System.out.printf("%s failed: %s%n", className, ex);
                failed++;
            }
        }
        System.out.printf("passed=%d; failed=%d%n", passed, failed);
    }
}

This little program is a complete, if minimal, test framework. It takes a list of class names on the command line. For each class name, it instantiates the class using its parameterless constructor and invokes a parameterless method called test. If the instantiation or invocation throws an exception, the test is deemed to have failed. The program prints each failure, followed by a summary of the test results. The reflective instantiation and invocation no longer require explicit array creation, because the getMethod and invoke methods accept a variable argument list. The program also uses the new printf facility, which relies on varargs. The program reads much more naturally than it would without varargs.

So when should you use varargs? As a client, you should take advantage of them whenever the API offers them. Important uses in core APIs include reflection, message formatting, and the new printf facility. As an API designer, you should use them sparingly, only when the benefit is truly compelling. Generally speaking, you should not overload a varargs method, or it will be difficult for programmers to figure out which overloading gets called.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved. Sun

Java Software


Java Logging Technology

Java

JavaTM Logging Technology

Documentation Contents

The JavaTM Logging APIs, introduced in package java.util.logging, facilitate software servicing and maintenance at customer sites by producing log reports suitable for analysis by end users, system administrators, field service engineers, and software development teams. The Logging APIs capture information such as security failures, configuration errors, performance bottlenecks, and/or bugs in the application or platform. The core package includes support for delivering plain text or XML-formatted log records to memory, output streams, consoles, files, and sockets. In addition, the logging APIs are capable of interacting with logging services that already exist on the host operating system.
Overview
  • Overview of key emements.
API Specification
  • java.util.logging reference
API Enhancements
  • Enhancements and Changes in J2SE 5.0

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun
Java Software


Java TM Logging Overview

Java

JavaTM Logging Overview

Last update Nov 26 2001
Documentation Contents

1.0 Java Logging Overview
1.1 Overview of Control Flow
1.2 Log Levels
1.3 Loggers
1.4 Logging Methods
1.5 Handlers
1.6 Formatters
1.7 The LogManager
1.8 Configuration File
1.9 Default Configuration
1.10 Dynamic Configuration Updates
1.11 Native Methods
1.12 XML DTD
1.13 Unique Message IDs
1.14 Security
1.15 Configuration Management
1.16 Packaging
1.17 Localization
1.18 Remote Access and Serialization
2.0 Examples
2.1 Simple Use
2.2 Changing the Configuration
2.3 Simple Use, Ignoring Global Configuration
2.4 Sample XML Output
3.0 Appendix A: DTD for XMLFormatter Output

1.0 JavaTM Logging Overview

The logging APIs are described in detail in the Java SE API Specification. The goal of this document is to provide an overview of key elements.

1.1 Overview of Control Flow

Applications make logging calls on Logger objects. Loggers are organized in a hierarchical namespace and child Loggers may inherit some logging properties from their parents in the namespace.

Applications make logging calls on Logger objects. These Logger objects allocate LogRecord objects which are passed to Handler objects for publication. Both Loggers and Handlers may use logging Levels and (optionally) Filters to decide if they are interested in a particular LogRecord. When it is necessary to publish a LogRecord externally, a Handler can (optionally) use a Formatter to localize and format the message before publishing it to an I/O stream.

The previous context describes this graphic

Each Logger keeps track of a set of output Handlers. By default all Loggers also send their output to their parent Logger. But Loggers may also be configured to ignore Handlers higher up the tree.

Some Handlers may direct output to other Handlers. For example, the MemoryHandler maintains an internal ring buffer of LogRecords and on trigger events it publishes its LogRecords through a target Handler. In such cases, any formatting is done by the last Handler in the chain.

The previous context describes this graphic

The APIs are structured so that calls on the Logger APIs can be cheap when logging is disabled. If logging is disabled for a given log level, then the Logger can make a cheap comparison test and return. If logging is enabled for a given log level, the Logger is still careful to minimize costs before passing the LogRecord into the Handlers. In particular, localization and formatting (which are relatively expensive) are deferred until the Handler requests them. For example, a MemoryHandler can maintain a circular buffer of LogRecords without having to pay formatting costs.

1.2 Log Levels

Each log message has an associated log Level. The Level gives a rough guide to the importance and urgency of a log message. Log level objects encapsulate an integer value, with higher values indicating higher priorities.

The Level class defines seven standard log levels, ranging from FINEST (the lowest priority, with the lowest value) to SEVERE (the highest priority, with the highest value).

1.3 Loggers

As stated earlier, client code sends log requests to Logger objects. Each logger keeps track of a log level that it is interested in, and discards log requests that are below this level.

Loggers are normally named entities, using dot-separated names such as "java.awt". The namespace is hierarchical and is managed by the LogManager. The namespace should typically be aligned with the Java packaging namespace, but is not required to follow it slavishly. For example, a Logger called "java.awt" might handle logging requests for classes in the java.awt package, but it might also handle logging for classes in sun.awt that support the client-visible abstractions defined in the java.awt package.

In addition to named Loggers, it is also possible to create anonymous Loggers that don't appear in the shared namespace. See section 1.14.

Loggers keep track of their parent loggers in the logging namespace. A logger's parent is its nearest extant ancestor in the logging namespace. The root Logger (named "") has no parent. Anonymous loggers are all given the root logger as their parent. Loggers may inherit various attributes from their parents in the logger namespace. In particular, a logger may inherit:

  • Logging level. If a Logger's level is set to be null then the Logger will use an effective Level that will be obtained by walking up the parent tree and using the first non-null Level.
  • Handlers. By default a Logger will log any output messages to its parent's handlers, and so on recursively up the tree.
  • Resource bundle names. If a logger has a null resource bundle name, then it will inherit any resource bundle name defined for its parent, and so on recursively up the tree.

1.4 Logging Methods

The Logger class provides a large set of convenience methods for generating log messages. For convenience, there are methods for each logging level, named after the logging level name. Thus rather than calling "logger.log(Constants.WARNING,..." a developer can simply call the convenience method "logger.warning(..."

There are two different styles of logging methods, to meet the needs of different communities of users.

First, there are methods that take an explicit source class name and source method name. These methods are intended for developers who want to be able to quickly locate the source of any given logging message. An example of this style is:

void warning(String sourceClass, String sourceMethod, String msg);

Second, there are a set of methods that do not take explicit source class or source method names. These are intended for developers who want easy-to-use logging and do not require detailed source information.

void warning(String msg);

For this second set of methods, the Logging framework will make a "best effort" to determine which class and method called into the logging framework and will add this information into the LogRecord. However, it is important to realize that this automatically inferred information may only be approximate. The latest generation of virtual machines perform extensive optimizations when JITing and may entirely remove stack frames, making it impossible to reliably locate the calling class and method.

1.5 Handlers

Java SE provides the following Handlers:

  • StreamHandler: A simple handler for writing formatted records to an OutputStream.
  • ConsoleHandler: A simple handler for writing formatted records to System.err
  • FileHandler: A handler that writes formatted log records either to a single file, or to a set of rotating log files.
  • SocketHandler: A handler that writes formatted log records to remote TCP ports.
  • MemoryHandler: A handler that buffers log records in memory.

It is fairly straightforward to develop new Handlers. Developers requiring specific functionality can either develop a Handler from scratch or subclass one of the provided Handlers.

1.6 Formatters

Java SE also includes two standard Formatters:
  • SimpleFormatter: Writes brief "human-readable" summaries of log records.
  • XMLFormatter: Writes detailed XML-structured information.

As with Handlers, it is fairly straightforward to develop new Formatters.

1.7 The LogManager

There is a global LogManager object that keeps track of global logging information. This includes:
  • A hierarchical namespace of named Loggers.
  • A set of logging control properties read from the configuration file. See section 1.8.

There is a single LogManager object that can be retrieved using the static LogManager.getLogManager method. This is created during LogManager initialization, based on a system property. This property allows container applications (such as EJB containers) to substitute their own subclass of LogManager in place of the default class.

1.8 Configuration File

The logging configuration can be initialized using a logging configuration file that will be read at startup. This logging configuration file is in standard java.util.Properties format.

Alternatively, the logging configuration can be initialized by specifying a class that can be used for reading initialization properties. This mechanism allows configuration data to be read from arbitrary sources, such as LDAP. JDBC, etc. See the LogManager API Specification for details.

There is a small set of global configuration information. This is specified in the description of the LogManager class and includes a list of root-level Handlers to install during startup.

The initial configuration may specify levels for particular loggers. These levels are applied to the named logger and any loggers below it in the naming hierarchy. The levels are applied in the order they are defined in the configuration file.

The initial configuration may contain arbitrary properties for use by Handlers or by subsystems doing logging. By convention these properties should use names starting with the name of the handler class or the name of the main Logger for the subsystem.

For example, the MemoryHandler uses a property "java.util.logging.MemoryHandler.size" to determine the default size for its ring buffer.

1.9 Default Configuration

The default logging configuration that ships with the JRE is only a default, and can be overridden by ISVs, system admins, and end users.

The default configuration makes only limited use of disk space. It doesn't flood the user with information, but does make sure to always capture key failure information.

The default configuration establishes a single handler on the rootr logger for sending output to the console.

1.10 Dynamic Configuration Updates

Programmers can update the logging configuration at run time in a variety of ways:
  • FileHandlers, MemoryHandlers, and PrintHandlers can all be created with various attributes.
  • New Handlers can be added and old ones removed.
  • New Loggers can be created and can be supplied with specific Handlers.
  • Levels can be set on target Handlers.

1.11 Native Methods

There are no native APIs for logging.

Native code that wishes to use the Java Logging mechanisms should make normal JNI calls into the Java Logging APIs.

1.12 XML DTD

The XML DTD used by the XMLFormatter in specified in Appendix A.

The DTD is designed with a "<log>" element as the top-level document. Individual log records are then written as "<record>" elements.

Note that in the event of JVM crashes it may not be possible to cleanly terminate an XMLFormatter stream with the appropriate closing </log>. Therefore tools that are analyzing log records should be prepared to cope with un-terminated streams.

1.13 Unique Message IDs

The Java Logging APIs do not provide any direct support for unique message IDs. Those applications or subsystems requiring unique message IDs should define their own conventions and include the unique IDs in the message strings as appropriate.

1.14 Security

The principal security requirement is that untrusted code should not be able to change the logging configuration. Specifically, if the logging configuration has been set up to log a particular category of information to a particular Handler, then untrusted code should not be able to prevent or disrupt that logging.

A new security permission LoggingPermission is defined to control updates to the logging configuration.

Trusted applications are given the appropriate LoggingPermission so they can call any of the logging configuration APIs. Untrusted applets are a different story. Untrusted applets can create and use named Loggers in the normal way, but they are not allowed to change logging control settings, such as adding or removing handlers, or changing log levels. However, untrusted applets are able to create and use their own "anonymous" loggers, using Logger.getAnonymousLogger. These anonymous Loggers are not registered in the global namespace and their methods are not access-checked, allowing even untrusted code to change their logging control settings.

The logging framework does not attempt to prevent spoofing. The sources of logging calls cannot be determined reliably, so when a LogRecord is published that claims to be from a particular source class and source method, it may be a fabrication. Similarly, formatters such as the XMLFormatter do not attempt to protect themselves against nested log messages inside message strings. This, a spoof LogRecord might contain a spoof set of XML inside its message string to make it look as if there was an additional XML record in the output.

In addition, the logging framework does not attempt to protect itself against denial of service attacks. Any given logging client can flood the logging framework with meaningless messages in an attempt to conceal some important log message.

1.15 Configuration Management

The APIs are structured so that an initial set of configuration information is read as properties from a configuration file. The configuration information may then be changed programatically by calls on the various logging classes and objects.

In addition, there are methods on LogManager that allow the configuration file to be re-read. When this happens, the configuration file values will override any changes that have been made programatically.

1.16 Packaging

All of the logging class are in the java.* part of the namespace, in the java.util.logging package.

1.17 Localization

Log messages may need to be localized.

Each Logger may have a Resource Bundle name associated with it. The corresponding Resource Bundle can be used to map between raw message strings and localized message strings.

Normally localization will be performed by Formatters. As a convenience, the formatter class provides a formatMessage method that provides some basic localization and formatting support.

1.18 Remote Access and Serialization

As with most Java platform APIs, the logging APIs are designed for use inside a single address space. All calls are intended to be local. However, it is expected that some Handlers will want to forward their output to other systems. There are a variety of ways of doing this:

Some Handlers (such as the SocketHandler) may write data to other systems using the XMLFormatter. This provides a simple, standard, inter-change format that can be parsed and processed on a variety of systems.

Some Handlers may wish to pass LogRecord objects over RMI. The LogRecord class is therefore serializable. However there is a problem in how to deal with the LogRecord parameters. Some parameters may not be serializable and other parameters may have been designed to serialize much more state than is required for logging. To avoid these problems the LogRecord class has a custom writeObject method that converts the parameters to strings (using Object.toString()) before writing them out. See the LogRecord API Specification for details.

Most of the logging classes are not intended to be serializable. Both Loggers and Handlers are stateful classes that are tied into a specific virtual machine. In this respect they are analogous to the java.io classes, which are also not serializable.

2.0 Examples

2.1 Simple Use

The following is a small program that performs logging using the default configuration.

This program relies on the root handlers that were established by the LogManager based on the configuration file. It creates its own Logger object and then makes calls to that Logger object to report various events.

package com.wombat;

public class Nose{
    // Obtain a suitable logger.
    private static Logger logger = Logger.getLogger("com.wombat.nose");
    public static void main(String argv[]) {
        // Log a FINE tracing message
        logger.fine("doing stuff");
        try{
            Wombat.sneeze();
        } catch (Exception ex) {
            // Log the exception
            logger.log(Level.WARNING, "trouble sneezing", ex);
        }
        logger.fine("done");
    }
}

2.2 Changing the Configuration

Here's a small program that dynamically adjusts the logging configuration to send output to a specific file and to get lots of information on wombats. The pattern "%t" means the system temporary directory.

public static void main(String[] args) {
    Handler fh = new FileHandler("%t/wombat.log");
    Logger.getLogger("").addHandler(fh);
    Logger.getLogger("com.wombat").setLevel("com.wombat", Level.FINEST);
    ...
}

2.3 Simple Use, Ignoring Global Configuration

Here's a small program that sets up it own logging Handler and ignores the global configuration.

package com.wombat;

import java.util.logging.*;

public class Nose {
    private static Logger logger = Logger.getLogger("com.wombat.nose");
    private static FileHandler fh = new FileHandler("mylog.txt");
    public static void main(String argv[]) {
        // Send logger output to our FileHandler.
        logger.addHandler(fh);
        // Request that every detail gets logged.
        logger.setLevel(Level.ALL);
        // Log a simple INFO message.
        logger.info("doing stuff");
        try {
            Wombat.sneeze();
        } catch (Exception ex) {
            logger.log(Level.WARNING, "trouble sneezing", ex);
        }
        logger.fine("done");
    }
}

2.4 Sample XML Output

Here's a small sample of what some XMLFormatter XML output looks like:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE log SYSTEM "logger.dtd">
<log>
<record>
  <date>2000-08-23 19:21:05</date>
  <millis>967083665789</millis>
  <sequence>1256</sequence>
  <logger>kgh.test.fred</logger>
  <level>INFO</level>
  <class>kgh.test.XMLTest</class>
  <method>writeLog</method>
  <thread>10</thread>
  <message>Hello world!</message>
</record>
</log>

3.0 Appendix A: DTD for XMLFormatter Output

<!-- DTD used by the java.util.logging.XMLFormatter -->
<!-- This provides an XML formatted log message. -->

<!-- The document type is "log" which consists of a sequence
of record elements -->
<!ELEMENT log (record*)>

<!-- Each logging call is described by a record element. -->
<!ELEMENT record (date, millis, sequence, logger?, level,
class?, method?, thread?, message, key?, catalog?, param*, exception?)>

<!-- Date and time when LogRecord was created in ISO 8601 format -->
<!ELEMENT date (#PCDATA)>

<!-- Time when LogRecord was created in milliseconds since
midnight January 1st, 1970, UTC. -->
<!ELEMENT millis (#PCDATA)>

<!-- Unique sequence number within source VM. -->
<!ELEMENT sequence (#PCDATA)>

<!-- Name of source Logger object. -->
<!ELEMENT logger (#PCDATA)>

<!-- Logging level, may be either one of the constant
names from java.util.logging.Constants (such as "SEVERE"
or "WARNING") or an integer value such as "20". -->
<!ELEMENT level (#PCDATA)>

<!-- Fully qualified name of class that issued
logging call, e.g. "javax.marsupial.Wombat". -->
<!ELEMENT class (#PCDATA)>

<!-- Name of method that issued logging call.
It may be either an unqualified method name such as
"fred" or it may include argument type information
in parenthesis, for example "fred(int,String)". -->
<!ELEMENT method (#PCDATA)>

<!-- Integer thread ID. -->
<!ELEMENT thread (#PCDATA)>

<!-- The message element contains the text string of a log message. -->
<!ELEMENT message (#PCDATA)>

<!-- If the message string was localized, the key element provides
the original localization message key. -->
<!ELEMENT key (#PCDATA)>

<!-- If the message string was localized, the catalog element provides
the logger's localization resource bundle name. -->
<!ELEMENT catalog (#PCDATA)>

<!-- If the message string was localized, each of the param elements
provides the String value (obtained using Object.toString())
of the corresponding LogRecord parameter. -->
<!ELEMENT param (#PCDATA)>

<!-- An exception consists of an optional message string followed
by a series of StackFrames. Exception elements are used
for Java exceptions and other java Throwables. -->
<!ELEMENT exception (message?, frame+)>

<!-- A frame describes one line in a Throwable backtrace. -->
<!ELEMENT frame (class, method, line?)>

<!-- an integer line number within a class's source file. -->
<!ELEMENT line (#PCDATA)>

Copyright ©2002 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


Logging APIs Changes and New Features

Java

Logging APIs
Changes and New Features

Documentation Contents

Changes and New Features in J2SE 5.0

  • The management interface for the logging facility is implemented. Refer to Monitoring and Management API for the Logging Facility.

  • Handlers can now be added to Loggers using the logging configuration file. See the .handlers property in java.util.logging.LogManager. See 4635817.

Copyright © 2004 Sun Microsystems, Inc. All Righst Reserved.

 Sun
Java Software


1. Overview of Java SE Monitoring and Management

Home Page
Products
Downloads
Service & Solutions
Support
Training
Research
Java SE Monitoring and Management Guide

Previous Previous Contents Next Next
Chapter 1

Overview of Java SE Monitoring and Management

This chapter introduces the features and utilities that provide monitoring and management services to the Java Platform, Standard Edition (Java SE platform). The features introduced here will be expanded upon in the following chapters of this guide.

Key Monitoring and Management Features

The Java SE platform includes significant monitoring and management features. These features fall into four broad categories.

  • Instrumentation for the Java Virtual Machine (Java VM).

  • Monitoring and Management application programming interfaces (API).

  • Monitoring and Management tools.

  • The Java Management Extensions (JMX) technology.

These categories of monitoring and management features are introduced further in the next sections.

Java VM Instrumentation

The Java VM is instrumented for monitoring and management, enabling built-in (or out-of-the-box) management capabilities that can be accessed both remotely and locally. For more information, see Chapter 2, Monitoring and Management Using JMX Technology and Chapter 5, SNMP Monitoring and Management.

The Java VM includes a platform MBean server and platform MBeans for use by management applications that conform to the JMX specification. These are implementations of the monitoring and management API described in the next section. Platform MXBeans and MBean servers are introduced in Platform MXBeans and Platform MBean Server.

Example code is provided in the JDK_HOME/demo/management directory, where JDK_HOME is the directory in which the Java Development Kit (JDK) is installed.

Monitoring and Management API

The java.lang.management package provides the interface for monitoring and managing the Java VM. This API provides access to the following types of information.

  • Number of classes loaded and threads running.

  • Java VM uptime, system properties, and VM input arguments.

  • Thread state, thread contention statistics, and stack trace of live threads.

  • Memory consumption.

  • Garbage collection statistics.

  • Low memory detection.

  • On-demand deadlock detection.

  • Operating system information.

In addition to the java.lang.management API, the java.util.logging.LoggingMXBean API provides allows you to perform monitoring and management of logging.

Monitoring and Management Tools

The Java SE platform provides a graphical monitoring tool called JConsole. JConsole implements the JMX API and enables you to monitor the performance of a Java VM and any instrumented applications, by providing information to help you optimize performance. Introduced in the J2SE platform 5.0, JConsole became an officially supported feature of the platform in the Java SE platform, version 6.

Some of the enhancements that have been made to JConsole between these two releases of the Java SE platform are as follows.

  • JConsole Plug-in support, that allows you to build your own plug-ins to run with JConsole, for example, to add a custom tab for accessing your applications' MBeans.

  • Dynamic attach capability, allowing you to connect JConsole to any application that supports the Attach API, that was added to the Java SE platform, version 6.

  • Enhanced user interface, that makes data more easily accessible.

  • New Overview and VM Summary tabs, for a better presentation of general information about your Java VM.

  • The HotSpot Diagnostic MBean, which provides an API to request heap dump at runtime and also change the setting of certain VM options.

  • Improved presentation of MBeans, to make it easier to access your MBeans' operations and attributes.

JConsole is presented in full in Chapter 3, Using JConsole.

Other command-line tools are also supplied with the Java SE platform. See the Monitoring Tools section of the JDK Development Tools document for more information.

Java Management Extensions (JMX) Technology

The Java SE platform, version 6 includes the JMX specification, version 1.4. The JMX API allows you to instrument applications for monitoring and management. An RMI connector allows this instrumentation to be remotely accessible, for example by JConsole.

For more information, see the JMX technology documentation for the Java SE platform. A very brief introduction to the main components of the JMX API is included in the next sections.

What are MBeans?

JMX technology MBeans are managed beans, namely Java objects that represent resources to be managed. An MBean has a management interface consisting of the following.

  • Named and typed attributes that can be read and written.

  • Named and typed operations that can be invoked.

  • Typed notifications that can be emitted by the MBean.

For example, an MBean representing an application's configuration could have attributes representing different configuration parameters, such as a cache size. Reading the CacheSize attribute would return the current size of the cache. Writing CacheSize would update the size of the cache, potentially changing the behavior of the running application. An operation such as save could store the current configuration persistently. The MBean could send a notification such as ConfigurationChangedNotification when the configuration changes.

MBeans can be standard or dynamic. Standard MBeans are Java objects that conform to design patterns derived from the JavaBeans component model. Dynamic MBeans define their management interface at runtime. More recently, an additional type of MBean called an MXBean has also been added to the Java platform.

  • A standard MBean exposes the resource to be managed directly through its attributes and operations. Attributes are exposed through "getter" and "setter" methods. Operations are the other methods of the class that are available to managers. All these methods are defined statically in the MBean interface and are visible to a JMX agent through introspection. This is the most straightforward way of making a new resource manageable.

  • A dynamic MBean is an MBean that defines its management interface at runtime. For example, a configuration MBean could determine the names and types of the attributes it exposes by parsing an XML file.

  • An MXBean is a new type of MBean that provides a simple way to code an MBean that only references a predefined set of types. In this way, you can be sure that your MBean will be usable by any client, including remote clients, without any requirement that the client have access to model-specific classes representing the types of your MBeans. The platform MBeans introduced below are all MXBeans.

MBean Server

To be useful, an MBean must be registered in an MBean server. An MBean Server is a repository of MBeans. Each MBean is registered with a unique name within the MBean server. Usually the only access to the MBeans is through the MBean server. In other words, code does not access an MBean directly, but rather accesses the MBean by name through the MBean server.

The Java SE platform includes a built-in platform MBean server. For more information, see Chapter 4, Using the Platform MBean Server and Platform MXBeans.

Creating and Registering MBeans

There are two ways to create an MBean. One is to construct a Java object that will be the MBean, then use the registerMBean method to register it in the MBean Server. The other is to create and register the MBean in a single operation using one of the createMBean methods.

The registerMBean method is simpler for local use, but cannot be used remotely. The createMBean method can be used remotely, but sometimes requires attention to class loading issues. An MBean can perform actions when it is registered in or unregistered from an MBean Server if it implements the MBeanRegistration interface.

Instrumenting Applications

General instructions on how to instrument your applications for management by the JMX API is beyond the scope of this document. See the documentation for the Java Management Extensions (JMX) Technology for information.

Platform MXBeans

A platform MXBean is an MBean for monitoring and managing the Java VM and other components of the Java Runtime Environment (JRE). Each MXBean encapsulates a part of VM functionality such as the class loading system, just-in-time (JIT) compilation system, garbage collector, and so on.

Table 1-1 lists all the platform MXBeans and the aspect of the VM that they manage. Each platform MXBean has a unique javax.management.ObjectName for registration in the platform MBean server. A Java VM may have zero, one, or more than one instance of each MXBean, depending on its function, as shown in the table.

Table 1-1 Platform MXBeans

Interface | Part of VM Managed | Object Name | Instances per VM
ClassLoadingMXBean | Class loading system | java.lang:type= ClassLoading | One
CompilationMXBean | Compilation system | java.lang:type= Compilation | Zero or one
GarbageCollectorMXBean | Garbage collector | java.lang:type= GarbageCollector, name=collectorName | One or more
LoggingMXBean | Logging system | java.util.logging:type =Logging | One
MemoryManagerMXBean (sub-interface of GarbageCollectorMXBean) | Memory pool | java.lang: typeMemoryManager, name=managerName | One or more
MemoryPoolMXBean | Memory | java.lang: type= MemoryPool, name=poolName | One or more
MemoryMXBean | Memory system | java.lang:type= Memory | One
OperatingSystemMXBean | Underlying operating system | java.lang:type= OperatingSystem | One
RuntimeMXBean | Runtime system | java.lang:type= Runtime | One
ThreadMXBean | Thread system | java.lang:type= Threading | One

See the package description in the API reference for the java.lang.management package for details of the platform MXBeans (apart from LoggingMXBean). See the API reference for java.util.logging for details of the LoggingMXBean.

Platform MBean Server

The platform MBean Server can be shared by different managed components running within the same Java VM. You can access the platform MBean Server with the method ManagementFactory.getPlatformMBeanServer(). The first call to this method, creates the platform MBean server and registers the platform MXBeans using their unique object names. Subsequently, it returns the initially created platform MBeanServer instance.

MXBeans that are created and destroyed dynamically (for example, memory pools and managers) will automatically be registered and unregistered in the platform MBean server. If the system property javax.management.builder.initial is set, the platform MBean server will be created by the specified MBeanServerBuilder.

You can use the platform MBean server to register other MBeans besides the platform MXBeans. This enables all MBeans to be published through the same MBean server and makes network publishing and discovery easier.

Previous Previous Contents Next Next
Company Info Contact Terms of Use Privacy Copyright 1994-2006 Sun Microsystems, Inc.


2. Monitoring and Management Using JMX Technology

Home Page
Products
Downloads
Service & Solutions
Support
Training
Research
Java SE Monitoring and Management Guide

Previous Previous Contents Next Next
Chapter 2

Monitoring and Management Using JMX Technology

The Java virtual machine (Java VM ) has built-in instrumentation that enables you to monitor and manage it using the Java Management Extensions (JMX) technology. These built-in management utilities are often referred to as out-of-the-box management tools for the Java VM. You can also monitor any appropriately instrumented applications using the JMX API.

Setting System Properties

To enable and configure the out-of-the-box JMX agent so that it can monitor and manage the Java VM, you must set certain system properties when you start the Java VM. You set a system property on the command-line as follows.

java -Dproperty=value ...

You can set any number of system properties in this way. If you do not specify a value for a management property, then the property is set with its default value. The full set of out-of-the-box management properties is described in Table 2-1 at the end of this chapter. You can also set system properties in a configuration file, as described in Out-of-the-Box Monitoring and Management Properties.

Note - To run the Java VM from the command line, you must add JRE_HOME/bin to your path, where JRE_HOME is the directory containing the Java Runtime Environment (JRE) implementation. Alternatively, you can enter the full path when you type the command.

The following documents describe the syntax and the full set of command-line options supported by the Java HotSpot VMs.

  • Java application launcher for Microsoft Windows

  • Java application launcher for Solaris Operating Environment

  • Java application launcher for Linux

Enabling the Out-of-the-Box Management

To monitor a Java platform using the JMX API, you must do the following.

  1. Enable the JMX agent (another name for the platform MBean server) when you start the Java VM. You can enable the JMX agent for:

    • Local monitoring, for a client management application running on the local system.

    • Remote monitoring, for a client management application running on a remote system.

  2. Monitor the Java VM with a tool that complies to the JMX specification, such as JConsole. See Chapter 3, Using JConsole for more information about Console.

These steps are described in the next sections.

Local Monitoring and Management

Under previous releases of the Java SE platform, to allow the JMX client access to a local Java VM, you had to set the following system property when you started the Java VM or Java application.

com.sun.management.jmxremote

Setting this property registered the Java VM platform's MBeans and published the Remote Method Invocation (RMI) connector via a private interface to allow JMX client applications to monitor a local Java platform, that is, a Java VM running on the same machine as the JMX client.

In the Java SE 6 platform, it is no longer necessary to set this system property. Any application that is started on the Java SE 6 platform will support the Attach API, and so will automatically be made available for local monitoring and management when needed.

For example, previously, to enable the JMX agent for the Java SE sample application Notepad, you would have to run the following commands.

% cd JDK_HOME/demo/jfc/Notepad
% java -Dcom.sun.management.jmxremote -jar Notepad.jar

In the above command, JDK_HOME is the directory in which the Java Development Kit (JDK) is installed. In the Java SE 6 platform, you would simply have to run the following command to start Notepad.

% java -jar Notepad.jar

Once Notepad has been started, a JMX client using the Attach API can then enable the out-of-the-box management agent to monitor and manage the Notepad application.

Note - On Windows platforms, for security reasons, local monitoring and management is only supported if your default temporary directory is on a file system that allows the setting of permissions on files and directories (for example, on a New Technology File System (NTFS) file system). It is not supported on a File Allocation Table (FAT) file system, which provides insufficient access controls.

Local Monitoring and Management Using JConsole

Local monitoring with JConsole is useful for development and creating prototypes. Using JConsole locally is not recommended for production environments, because JConsole itself consumes significant system resources. Rather, you should use JConsole on a remote system to isolate it from the platform being monitored.

However, if you do wish to perform local monitoring using JConsole, you start the tool by typing jconsole in a command shell. When you start jconsole without any arguments, it will automatically detect all local Java applications, and display a dialog box that enables you to select the application you want to monitor. Both JConsole and the application must by executed by the same user, since the monitoring and monitoring system uses the operating system's file permissions.

Note - To run JConsole from the command line, you must add JDK_HOME/bin to your path. Alternatively, you can enter the full path when you type the command.

For more information, see Chapter 3, Using JConsole.

Remote Monitoring and Management

To enable monitoring and management from remote systems, you must set the following system property when you start the Java VM.

com.sun.management.jmxremote.port=portNum

In the property above, portNum is the port number through which you want to enable JMX RMI connections. Be sure to specify an unused port number. In addition to publishing an RMI connector for local access, setting this property publishes an additional RMI connector in a private read-only registry at the specified port using a well known name, "jmxrmi".

Note - You must set the above system property in addition to any properties you might set for security, as described in Using Password Authentication and the sections that follow it.

Remote monitoring and management requires security, to ensure that unauthorized persons cannot control or monitor your application. Password authentication over the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) is enabled by default. You can disable password authentication and SSL separately, as described in the next sections.

After you have enabled the JMX agent for remote use, you can monitor your application using JConsole, as described in Remote Monitoring with JConsole. How to connect to the management agent programmatically is described in Connecting to the JMX Agent Programmatically.

Using Password Authentication

By default, when you enable the JMX agent for remote monitoring, it uses password authentication. However, the way you set it up depends on whether you are in a single-user environment or a multiple-user environment.

Since passwords are stored in clear-text in the password file, it is not advisable to use your regular user name and password for monitoring. Instead, use the user names specified in the password file such as monitorRole and controlRole. For more information, see Using Password and Access Files.

Procedure To Set up a Single-User Environment

You set up the password file in the JRE_HOME/lib/management directory as follows.

  1. Copy the password template file, jmxremote.password.template, to jmxremote.password.

  2. Set file permissions so that only the owner can read and write the password file.

  3. Add passwords for roles such as monitorRole and controlRole.

Procedure To Set up a Multiple-User Environment

You set up the password file in the JRE_HOME/lib/management directory as follows.

  1. Copy the password template file, jmxremote.password.template, to your home directory and rename it to jmxremote.password.

  2. Set file permissions so that only you can read and write the password file.

  3. Add passwords for the roles such as monitorRole and controlRole.

  4. Set the following system property when you start the Java VM.

    com.sun.management.jmxremote.password.file=pwFilePath

    In the above property, pwFilePath is the path to the password file.

    Caution Caution - A potential security issue has been identified with password authentication for remote connectors when the client obtains the remote connector from an insecure RMI registry (the default). If an attacker starts a bogus RMI registry on the target server before the legitimate registry is started, then the attacker can steal clients' passwords. This scenario includes the case where you launch a Java VM with remote management enabled, using the system property com.sun.management.jmxremote.port=portNum, even when SSL is enabled. Although such attacks are likely to be noticed, it is nevertheless a vulnerability.

    To avoid this problem, use SSL client certificates for authentication instead of passwords, or ensure that the client obtains the remote connector object securely, for example through a secure LDAP server or a file in a shared secure filesystem.

Disabling Password Authentication

Password authentication for remote monitoring is enabled by default. To disable it, set the following system property when you start the Java VM.

com.sun.management.jmxremote.authenticate=false

Caution Caution - This configuration is insecure. Any remote user who knows (or guesses) your JMX port number and host name will be able to monitor and control your Java application and platform. While it may be acceptable for development, it is not recommended for production systems.

When you disable password authentication, you can also disable SSL, as described in Disabling Security. You may also want to disable passwords, but use SSL client authentication, as described in Enabling SSL Client Authentication.

Using SSL

SSL is enabled by default when you enable remote monitoring and management. To use SSL, you need to set up a digital certificate on the system where the JMX agent (the MBean server) is running and then configure SSL properly. You use the command-line utility keytool to work with certificates. The general procedure is as follows.

Procedure To Set up SSL

  1. If you do not already have a key pair and certificate set up on the server:

    • Generate a key pair with the keytool -genkey command.

    • Request a signed certificate from a certificate authority (CA) with the keytool -certreq command.

    • Import the certificate into your keystore with the keytool -import command. See Importing Certificates in the keytool documentation.

      For more information and examples, see keytool - Key and Certificate Management Tool (Solaris and Linux) or (Windows platforms).

  2. Configure SSL on the server system.

    A full explanation of configuring and customizing SSL is beyond the scope of this document, but you generally need to set the system properties described in the list below.

    System Property

    Description

    javax.net.ssl.keyStore

    Keystore location.

    javax.net.ssl.keyStoreType

    Default keystore type.

    javax.net.ssl.keyStorePassword

    Default keystore password.

    javax.net.ssl.trustStore

    Truststore location.

    javax.net.ssl.trustStoreType

    Default truststore type.

    javax.net.ssl.trustStorePassword

    Default truststore password.

    For more information about setting system properties, see Setting System Properties above, or consult the following documents.

    • keytool - Key and Certificate Management Tool (Solaris and Linux platforms)

    • keytool - Key and Certificate Management Tool (Windows platforms)

    • The section Customizing the Default Key and Trust Stores, Store Types, and Store Passwordsin the JSSE Guide.

Enabling RMI Registry Authentication

When setting up connections for monitoring remote applications, you can optionally bind the RMI connector stub to an RMI registry that is protected by SSL. This allows clients with the appropriate SSL certificates to get the connector stub that is registered in the RMI registry. To protect the RMI registry using SSL, you must set the following system property.

com.sun.management.jmxremote.registry.ssl=true

When this property is set to true, an RMI registry protected by SSL will be created and configured by the out-of-the-box management agent when the Java VM is started. The default value of this property is false. If this property is set to true, in order to have full security then SSL client authentication must also be enabled, as described in the next section.

Enabling SSL Client Authentication

To enable SSL client authentication, set the following system property when you start the Java VM.

com.sun.management.jmxremote.ssl.need.client.auth=true

SSL must be enabled (the default), to use client SSL authentication. This configuration requires the client system to have a valid digital certificate. You must install a certificate and configure SSL on the client system, as described in Using SSL. As stated in the previous section, if RMI registry SSL protection is enabled, then client SSL authentication must be set to true.

Disabling SSL

To disable SSL when monitoring remotely, you must set the following system property when you start the Java VM.

com.sun.management.jmxremote.ssl=false

Password authentication will still be required unless you disable it, as specified in Disabling Password Authentication.

Disabling Security

To disable both password authentication and SSL (namely to disable all security), you should set the following system properties when you start the Java VM.

com.sun.management.jmxremote.authenticate=false
com.sun.management.jmxremote.ssl=false

Caution Caution - This configuration is insecure: any remote user who knows (or guesses) your port number and host name will be able to monitor and control your Java applications and platform. Furthermore, possible harm is not limited to the operations you define in your MBeans. A remote client could create a javax.management.loading.MLet MBean and use it to create new MBeans from arbitrary URLs, at least if there is no security manager. In other words, a rogue remote client could make your Java application execute arbitrary code.

Consequently, while disabling security might be acceptable for development, it is strongly recommended that you do not disable security for production systems.

Remote Monitoring with JConsole

You can remotely monitor an application using JConsole, with or without security enabled.

Remote Monitoring with JConsole with SSL Disabled

To monitor a remote application with SSL disabled, you would start JConsole with the following command.

% jconsole hostName:portNum

You can also omit the host name and port number, and enter them in the dialog box that JConsole provides.

Remote Monitoring with JConsole with SSL Enabled

To monitor a remote application with SSL enabled, you need to set up the truststore on the system where JConsole is running and configure SSL properly. For example, you can create a keystore as described in the JSSE Guide and start your application (called Server in this example) with the following commands.

% java -Djavax.net.ssl.keyStore=keystore \
  -Djavax.net.ssl.keyStorePassword=password Server

If you created the keystore and started Server as shown above, then you would have to start JConsole as follows.

% jconsole -J-Djavax.net.ssl.trustStore=truststore \
  -J-Djavax.net.ssl.trustStorePassword=trustword

The above configuration authenticates the server only. If SSL client authentication is set up, you will need to provide a similar keystore for JConsole's keys, and an appropriate truststore for the application.

See Customizing the Default Key and Trust Stores, Store Types, and Store Passwords in the JSSE Guide for information.

For more information on using JConsole, see Chapter 3, Using JConsole.

Using Password and Access Files

The password and access files control security for remote monitoring and management. These files are located by default in JRE_HOME/lib/management and are in the standard Java properties file format. For more information on the format, see the API reference for the java.util.Properties package.

Password Files

The password file defines the different roles and their passwords. The access control file (jmxremote.access by default) defines the permitted access for each role. To be functional, a role must have an entry in both the password and the access files.

The JRE implementation contains a password file template named jmxremote.password.template. Copy this file to JRE_HOME/lib/management/jmxremote.password or to your home directory, and add the passwords for the roles defined in the access file.

You must ensure that only the owner has read and write permissions on this file, since it contains the passwords in clear text. For security reasons, the system checks that the file is only readable by the owner and exits with an error if it is not. Thus in a multiple-user environment, you should store the password file in private location such as your home directory.

Property names are roles, and the associated value is the role's password. For example, the following are sample entries in the password file.

Example 2-1 An Example Password File

# The "monitorRole" role has password "QED".
# The "controlRole" role has password "R&D".
monitorRole QED
controlRole R&D

On Solaris and Linux systems, you can set the file permissions for the password file by running the following command.

chmod 600 jmxremote.password

For instructions on how to set file permissions on Windows platforms, see Appendix A, Additional Security Information For Microsoft Windows.

Access Files

By default, the access file is named jmxremote.access. Property names are identities from the same space as the password file. The associated value must be either readonly or readwrite.

The access file defines roles and their access levels. By default, the access file defines the two following primary roles.

  • monitorRole, which grants read-only access for monitoring.

  • controlRole, which grants read-write access for monitoring and management.

An access control entry consists of a role name and an associated access level. The role name cannot contain spaces or tabs and must correspond to an entry in the password file. The access level can be either one of the following.

  • readonly, which grants access to read an MBean's attributes. For monitoring, this means that a remote client in this role can read measurements but cannot perform any action that changes the environment of the running program. The remote client can also listen to MBean notifications.

  • readwrite, which grants access to read and write an MBean's attributes, to invoke operations on them, and to create or remove them. This access should be granted to only trusted clients, since they can potentially interfere with the operation of an application.

A role should have only one entry in the access file. If a role has no entry, it has no access. If a role has multiple entries, then the last entry takes precedence. Typical predefined roles in the access file resemble the following.

Example 2-2 An Example Access File

# The "monitorRole" role has readonly access.
# The "controlRole" role has readwrite access.
monitorRole readonly
controlRole readwrite

Out-of-the-Box Monitoring and Management Properties

You can set out-of-the-box monitoring and management properties in a configuration file or on the command line. Properties specified on the command line override properties in a configuration file. The default location for the configuration file is JRE_HOME/lib/management/management.properties. The Java VM reads this file if either of the command-line properties com.sun.management.jmxremote or com.sun.management.jmxremote.port are set. Management via the Simple Network Management Protocol (SNMP) uses the same configuration file. For more information about SNMP monitoring, see Chapter 5, SNMP Monitoring and Management.

You can specify a different location for the configuration file with the following command-line option.

com.sun.management.config.file=ConfigFilePath

In the property above, ConfigFilePath is the path to the configuration file.

Table 2-1 describes all the out-of-the-box monitoring and management properties.

Table 2-1 Out-of-the-Box Monitoring and Management Properties

Property | Description | Values
com.sun.management.jmxremote | Enables the JMX remote agent and local monitoring via a JMX connector published on a private interface used by JConsole and any other local JMX clients that use the Attach API. JConsole can use this connector if it is started by the same user as the user that started the agent. No password or access files are checked for requests coming via this connector. | true / false. Default is true.
com.sun.management.jmxremote. port | Enables the JMX remote agent and creates a remote JMX connector to listen through the specified port. By default, the SSL, password, and access file properties are used for this connector. It also enables local monitoring as described for the com.sun.management.jmxremote property. | Port number. No default.
com.sun.management.jmxremote. registry.ssl | Binds the RMI connector stub to an RMI registry protected by SSL. | true / false. Default is false.
com.sun.management.jmxremote. ssl | Enables secure monitoring via SSL. If false, then SSL is not used. | true / false. Default is true.
com.sun.management.jmxremote. ssl.enabled.protocols | A comma-delimited list of SSL/TLS protocol versions to enable. Used in conjunction with com.sun.management.jmxremote.ssl. | Default SSL/TLS protocol version.
com.sun.management.jmxremote. ssl.enabled.cipher.suites | A comma-delimited list of SSL/TLS cipher suites to enable. Used in conjunction with com.sun.management.jmxremote.ssl. | Default SSL/TLS cipher suites.
com.sun.management.jmxremote. ssl.need.client.auth | If this property is true and the property com.sun.management.jmxremote.ssl is also true, then client authentication will be performed. | true / false. Default is true.
com.sun.management.jmxremote. authenticate | If this property is false then JMX does not use passwords or access files: all users are allowed all access. | true / false. Default is true.
com.sun.management.jmxremote. password.file | Specifies location for password file. If com.sun.management.jmxremote.authenticate is false, then this property and the password and access files are ignored. Otherwise, the password file must exist and be in the valid format. If the password file is empty or nonexistent, then no access is allowed. | JRE_HOME/lib/management/ jmxremote.password
com.sun.management.jmxremote. access.file | Specifies location for the access file. If com.sun.management.jmxremote.authenticate is false, then this property and the password and access files are ignored. Otherwise, the access file must exist and be in the valid format. If the access file is empty or nonexistent, then no access is allowed. | JRE_HOME/lib/management/ jmxremote.access
com.sun.management.jmxremote. login.config | Specifies the name of a Java Authentication and Authorization Service (JAAS) login configuration entry to use when the JMX agent authenticates users. When using this property to override the default login configuration, the named configuration entry must be in a file that is loaded by JAAS. In addition, the login modules specified in the configuration should use the name and password callbacks to acquire the user's credentials. For more information, see the API documentation for javax.security.auth.callback.NameCallback and javax.security.auth.callback.PasswordCallback. | Default login configuration is a file-based password authentication.

Configuration Errors

If any errors occur during start up of the MBean server, the RMI registry, or the connector, the Java VM will throw an exception and exit. Configuration errors include the following.

  • Failure to bind to the port number.

  • Invalid password file.

  • Invalid access file.

  • Password file is readable by users other than the owner.

If your application runs a security manager, then additional permissions are required in the security permissions file.

Connecting to the JMX Agent Programmatically

Once you have enabled the JMX agent, a client can use the following URL to access the monitoring service.

service:jmx:rmi:///jndi/rmi://hostName:portNum/jmxrmi

A client can create a connector for the agent by instantiating a javax.management.remote.JMXServiceURL object using the URL, and then creating a connection using the JMXConnectorFactory.connect method, shown in Example 2-3.

Example 2-3 Creating a Connection Using JMXConnectorFactory.connect

MXServiceURL u = new JMXServiceURL(
  "service:jmx:rmi:///jndi/rmi://" + hostName + ":" + portNum +  "/jmxrmi");
  JMXConnector c = JMXConnectorFactory.connect(u);

Setting up Monitoring and Management Programmatically

As stated previously, in the Java SE platform version 6, you can create a JMX client that uses the Attach API to enable out-of-the-box monitoring and management of any applications that are started on the Java SE 6 platform, without having to configure the applications for monitoring when you launch them. The Attach API provides a way for tools to attach to and start agents in the target application. Once an agent is running, JMX clients (and other tools) are able to obtain the JMX connector address for that agent via a property list that is maintained by the Java VM on behalf of the agents. The properties in the list are accessible from tools that use the Attach API. So, if an agent is started in an application, and if the agent creates a property to represent a piece of configuration information, then that configuration information is available to tools that attach to the application.

The JMX agent creates a property with the address of the local JMX connector server. This allows JMX tools to attach to and get the connector address of an agent, if it is running.

Example 2-4 shows code that could be used in a JMX tool to attach to a target VM, get the connector address of the JMX agent and connect to it.

Example 2-4 Attaching a JMX tool to a connector and getting the agent's address

static final String CONNECTOR_ADDRESS =
 "com.sun.management.jmxremote.localConnectorAddress";

// attach to the target application
VirtualMachine vm = VirtualMachine.attach(id);

// get the connector address
String connectorAddress =
    vm.getAgentProperties().getProperty(CONNECTOR_ADDRESS);

// no connector address, so we start the JMX agent
if (connectorAddress == null) {
   String agent = vm.getSystemProperties().getProperty("java.home") +
       File.separator + "lib" + File.separator + "management-agent.jar";
   vm.loadAgent(agent);

   // agent is started, get the connector address
   connectorAddress =
       vm.getAgentProperties().getProperty(CONNECTOR_ADDRESS);
}

// establish connection to connector server
JMXServiceURL url = new JMXServiceURL(connectorAddress);
JMXConnector = JMXConnectorFactory.connect(url);

Example 2-4 uses the com.sun.tools.attach.VirtualMachine class's attach() method to attach to a given Java VM so that it can read the properties that the target Java VM maintains on behalf of any agents running in it. If an agent is already running, then the VirtualMachine class's getAgentProperties() method is called to obtain the agent's address. The getAgentProperties() method returns a string property for the local connector address com.sun.management.jmxremote.localConnectorAddress, that you can use to connect to the local JMX agent.

If no agent is running already, then one is loaded by the VirtualMachine from JRE_HOME/lib/management-agent.jar, and its connector address is obtained by getAgentProperties().

A connection to the agent is then established by calling JMXConnectorFactory.connect on a JMX service URL that has been constructed from this connector address.

Mimicking Out-of-the-Box Management Using the JMX Remote API

As explained above, remote access to the out-of-the-box management agent is protected by authentication and authorization, and by SSL encryption, and all configuration is performed by setting system properties or by defining a management.properties file. In most cases, using the out-of-the-box management agent and configuring it through the management.properties file is more than sufficient to provide secure management of remote Java VMs. However, in some cases greater levels of security are required and in other cases certain system configurations do not allow the use of a management.properties file. Such cases might involve exporting the RMI server's remote objects over a certain port to allow passage through a firewall, or exporting the RMI server's remote objects using a specific network interface in multi-homed systems. For such cases, the behavior of the out-of-the-box management agent can be mimicked by using the JMX Remote API directly to create, configure and deploy the management agent programmatically.

Example of Mimicking Out-of-the-Box Management

This section provides an example of how to implement a JMX agent that identically mimics an out-of-the-box management agent. In exactly the same way as the out-of-the-box management agent, the agent created in Example 2-5 will run on port 3000, will have a password file named password.properties, an access file named access.properties and it will implement the default configuration for SSL/TLS-based RMI Socket Factories, requiring server authentication only. This example assumes a keystore has already been created, as described in Using SSL. Information about how to set up the SSL configuration can be found in the JSSE Reference Guide.

To enable monitoring and management on an application named com.example.MyApp using the out-of-the-box JMX agent with the configuration described above, you would run com.example.MyApp with the following command.

% java -Dcom.sun.management.jmxremote.port=3000 \
     -Dcom.sun.management.jmxremote.password.file=password.properties \
     -Dcom.sun.management.jmxremote.access.file=access.properties \
     -Djavax.net.ssl.keyStore=keystore \
     -Djavax.net.ssl.keyStorePassword=password \
     com.example.MyApp

Note - The com.sun.management.jmxremote.* properties could have been specified in a management.properties file instead of passing them at the command line. In that case, the system property -Dcom.sun.management.config.file=management.properties would be required to specify the location of the management.properties file.

Example 2-5 shows the code you would need to write to create programmatically a JMX agent that will allow exactly the same monitoring and management on com.example.MyApp as would be possible using the command above.

Example 2-5 Mimicking an Out-of-the-Box JMX Agent Programmatically

package com.example;

import java.lang.management.*;
import java.rmi.registry.*;
import java.util.*;
import javax.management.*;
import javax.management.remote.*;
import javax.management.remote.rmi.*;
import javax.rmi.ssl.*;

public class MyApp {

    public static void main(String[] args) throws Exception {

        // Ensure cryptographically strong random number generator used
        // to choose the object number - see java.rmi.server.ObjID
        //
        System.setProperty("java.rmi.server.randomIDs", "true");

        // Start an RMI registry on port 3000.
        //
        System.out.println("Create RMI registry on port 3000");
        LocateRegistry.createRegistry(3000);

        // Retrieve the PlatformMBeanServer.
        //
        System.out.println("Get the platform's MBean server");
        MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();

        // Environment map.
        //
        System.out.println("Initialize the environment map");
        HashMap<String,Object> env = new HashMap<String,Object>();

        // Provide SSL-based RMI socket factories.
        //
        // The protocol and cipher suites to be enabled will be the ones
        // defined by the default JSSE implementation and only server
        // authentication will be required.
        //
        SslRMIClientSocketFactory csf = new SslRMIClientSocketFactory();
        SslRMIServerSocketFactory ssf = new SslRMIServerSocketFactory();
        env.put(RMIConnectorServer.RMI_CLIENT_SOCKET_FACTORY_ATTRIBUTE, csf);
        env.put(RMIConnectorServer.RMI_SERVER_SOCKET_FACTORY_ATTRIBUTE, ssf);

        // Provide the password file used by the connector server to
        // perform user authentication. The password file is a properties
        // based text file specifying username/password pairs.
        //
        env.put("jmx.remote.x.password.file", "password.properties");

        // Provide the access level file used by the connector server to
        // perform user authorization. The access level file is a properties
        // based text file specifying username/access level pairs where
        // access level is either "readonly" or "readwrite" access to the
        // MBeanServer operations.
        //
        env.put("jmx.remote.x.access.file", "access.properties");

        // Create an RMI connector server.
        //
        // As specified in the JMXServiceURL the RMIServer stub will be
        // registered in the RMI registry running in the local host on
        // port 3000 with the name "jmxrmi". This is the same name the
        // out-of-the-box management agent uses to register the RMIServer
        // stub too.
        //
        System.out.println("Create an RMI connector server");
        JMXServiceURL url =
            new JMXServiceURL("service:jmx:rmi:///jndi/rmi://:3000/jmxrmi");
        JMXConnectorServer cs =
            JMXConnectorServerFactory.newJMXConnectorServer(url, env, mbs);

        // Start the RMI connector server.
        //
        System.out.println("Start the RMI connector server");
        cs.start();
    }
}

Start this application with the following command.

java -Djavax.net.ssl.keyStore=keystore \
     -Djavax.net.ssl.keyStorePassword=password \
     com.example.MyApp

The com.example.MyApp application will enable the JMX agent and will be able to be monitored and managed in exactly the same way as if the Java platform's out-of-the-box management agent had been used. However, there is one slight but important difference between the RMI registry used by the out-of-the-box management agent and the one used by a management agent that mimics it. The RMI registry used by the out-of-the-box management agent is read-only, namely a single entry can be bound to it and once bound this entry cannot be unbound. This is not true of the RMI registry created in Example 2-5.

Furthermore, both RMI registries are insecure as they do not use SSL/TLS. The RMI registries should be created using SSL/TLS-based RMI socket factories which require client authentication. This will prevent a client from sending its credentials to a rogue RMI server and will also prevent the RMI registry from giving access to the RMI server stub to a non-trusted client.

RMI registries which implement SSL/TLS RMI socket factories can be created by adding the following properties to your management.properties file.

com.sun.management.jmxremote.registry.ssl=true
com.sun.management.jmxremote.ssl.need.client.auth=true

Example 2-5 mimics the main behavior of the out-of-the-box JMX agent, but does not replicate all the existing properties in the management.properties file. However, you could add other properties by modifying com.example.MyApp appropriately.

Monitoring Applications through a Firewall

As stated above, the code in Example 2-5 can be used to monitor applications through a firewall, which might not be possible if you use the out-of-the-box monitoring solution. The com.sun.management.jmxremote.port management property specifies the port where the RMI Registry can be reached but the ports where the RMIServer and RMIConnection remote objects are exported is chosen by the RMI stack. To export the remote objects (RMIServer and RMIConnection) to a given port you need to create your own RMI connector server programmatically, as described in Example 2-5. However, you must specify the JMXServiceURL as follows:

JMXServiceURL url = new JMXServiceURL("service:jmx:rmi://localhost:" +
      port1  + "/jndi/rmi://localhost:" + port2 + "/jmxrmi");

In the URL above, port1 is the port number on which the RMIServer and RMIConnection remote objects are exported and port2 is the port number of the RMI Registry.

Using an Agent Class to Instrument an Application

The Java SE platform provides services that allow Java programming language agents to instrument programs running on the Java VM. Creating an instrumentation agent means you do not have to add any new code to your application in order to allow it to be monitored. Instead of implementing monitoring and management in your application's static main method you implement it in a separate agent class, and start your application with the -javaagent option specified. See the API reference documentation for the java.lang.instrument package for full details about how to create an agent class to instrument your applications.

The following procedure shows how you can adapt the code of com.example.MyApp to make an agent to instrument any other application for monitoring and management.

Procedure Creating an Agent Class to Instrument an Application

  1. Create a com.example.MyAgent class.

    Create a class called com.example.MyAgent, declaring a premain method rather than a main method.

    package com.example;

[...]

public class MyAgent {

    public static void premain(String args) throws Exception {

    [...]

    The rest of the code for the com.example.MyAgent class can be exactly the same as the com.example.MyApp class shown in Example 2-5.

  2. Compile the com.example.MyAgent class.

  3. Create a manifest file, MANIFEST.MF, with a Premain-Class entry.

    An agent is deployed as a Java archive (JAR) file. An attribute in the JAR file manifest specifies the agent class which will be loaded to start the agent. Create a file called MANIFEST.MF, containing the following line.

    Premain-Class: com.example.MyAgent

  4. Create a JAR file, MyAgent.jar.

    The JAR file should contain the following files.

    • META-INF/MANIFEST.MF

    • com/example/MyAgent.class

  5. Start an application, specifying the agent to provide monitoring and management services.

    You can use com.example.MyAgent to instrument any application for monitoring and management. This example uses the Notepad application.

    % java -javaagent:MyAgent.jar -Djavax.net.ssl.keyStore=keystore \
      -Djavax.net.ssl.keyStorePassword=password -jar Notepad.jar

    The com.example.MyAgent agent is specified using the -javaagent option when you start Notepad. Also, if your com.example.MyAgent application replicates the same code as the com.example.MyApp application shown in Example 2-5, then you will need to provide the keystore and password because the RMI connector server is protected by SSL.

Previous Previous Contents Next Next
Company Info Contact Terms of Use Privacy Copyright 1994-2006 Sun Microsystems, Inc.


3. Using JConsole

Home Page
Products
Downloads
Service & Solutions
Support
Training
Research
Java SE Monitoring and Management Guide

Previous Previous Contents Next Next
Chapter 3

Using JConsole

The JConsole graphical user interface is a monitoring tool that complies to the Java Management Extensions (JMX) specification. JConsole uses the extensive instrumentation of the Java Virtual Machine (Java VM) to provide information about the performance and resource consumption of applications running on the Java platform.

In the Java Platform, Standard Edition (Java SE platform) 6, JConsole has been updated to present the look and feel of the Windows and GNOME desktops (other platforms will present the standard Java graphical look and feel). The screen captures presented in this document were taken from an instance of the interface running on Windows XP.

Starting JConsole

The jconsole executable can be found in JDK_HOME/bin, where JDK_HOME is the directory in which the Java Development Kit (JDK) is installed. If this directory is in your system path, you can start JConsole by simply typing jconsole in a command (shell) prompt. Otherwise, you have to type the full path to the executable file.

Command Syntax

You can use JConsole to monitor both local applications, namely those running on the same system as JConsole, as well as remote applications, namely those running on other systems.

Note - Using JConsole to monitor a local application is useful for development and for creating prototypes, but is not recommended for production environments, because JConsole itself consumes significant system resources. Remote monitoring is recommended to isolate the JConsole application from the platform being monitored.

For a complete reference on the syntax of the jconsole command, see the manual page for the jconsole command: Java Monitoring and Management Console.

Setting up Local Monitoring

You start JConsole by typing the following command at the command line.

% jconsole

When JConsole starts, you will be given a choice of all the Java applications that are running locally that JConsole can connect to.

If you want to monitor a specific application, and you know that application's process ID, then you can also start JConsole so that it connects to that application. This application must be running with the same user ID as JConsole. The command syntax to start JConsole for local monitoring of a specific application is the following.

% jconsole processID

In the command above processID is the application's process ID (PID). You can determine an application's PID in the following ways:

  • On UNIX or Linux systems, you can use the ps command to find the PID of the java instance that is running.

  • On Windows systems, you can use the Task Manager to find the PID of java or javaw.

  • You can also use the jps command-line utility to determine PIDs. See the manual page for the Java Virtual Machine Process Status Tool.

For example, if you determined that the process ID of the Notepad application is 2956, then you would start JConsole with the following command.

% jconsole 2956

Both JConsole and the application must by executed by the same user. The management and monitoring system uses the operating system's file permissions. If you do not specify a process ID, JConsole will automatically detect all local Java applications, and display a dialog box that lets you select which one you want to monitor (see Connecting to a JMX Agent).

For more information, see Local Monitoring and Management.

Setting up Remote Monitoring

To start JConsole for remote monitoring, you use the following command syntax.

% jconsole hostName:portNum

In the command above, hostName is the name of the system running the application and portNum is the port number you specified when you enabled the JMX agent when you started the Java VM. For more information, see Remote Monitoring and Management.

If you do not specify a host name/port number combination, then JConsole will display a connection dialog box (Connecting to a JMX Agent) to enable you to enter a host name and port number.

Setting up Secure Remote Monitoring

You can also start JConsole so that monitoring will be performed over a connection that is secured using Secure Sockets Layer (SSL). The command to start JConsole with a secure connection is given in Remote Monitoring with JConsole with SSL Enabled in Chapter 2, Monitoring and Management Using JMX Technology.

Connecting to a JMX Agent

If you start JConsole with arguments specifying a JMX agent to connect to, it will automatically start monitoring the specified Java VM. You can connect to a different host at any time by choosing Connection | New Connection and entering the necessary information.

Otherwise, if you do not provide any arguments when you start JConsole, the first thing you see is the connection dialog box. This dialog box has two options, allowing connections to either Local or Remote processes.

Dynamic Attach

Under previous releases of the Java SE platform, applications that you wanted to monitor with JConsole needed to be started with the following option.

% -Dcom.sun.management.jmxremote

However, the version of JConsole provided with the Java SE 6 platform can attach to any application that supports the Attach API. In other words, any application that is started in the Java SE 6 HotSpot VM is detected automatically by JConsole, and does not need to be started using the above command-line option.

Connecting JConsole to a Local Process

If you start JConsole without providing a specific JMX agent to connect to, you will see the following dialog window.

Figure 3-1 Creating a Connection to a Local Process

The dialog window for creating connections to local processes

The Local Process option lists any Java VMs running on the local system that were started with the same user ID as JConsole, along with their process ID and their class and/or argument information. To connect JConsole to your application, select the application you want to monitor, then click the Connect button. The list of local processes includes applications running in the following types of Java VM.

  • Applications with the management agent enabled. These include applications on the Java SE 6 platform or on the J2SE 5.0 platform that were started with the -Dcom.sun.management.jmxremote option or with the -Dcom.sun.management.jmxremote.port option specified. In addition, the list also includes any applications that were started on the Java SE 6 platform without any management properties but which are later attached to by JConsole, which enables the management agent at runtime.

  • Applications that are attachable, with the management agent disabled. An attachable application supports loading the management agent at runtime. Attachable applications include applications that are started on the Java SE 6 platform that support the Attach API. Applications which support dynamic attach do not require the management agent to be started by specifying the com.sun.management.jmxremote or com.sun.management.jmxremote.port options at the command line, and JConsole does not need to connect to the management agent before the application is started. If you select this application, you will be informed in a note onscreen that the management agent will be enabled when the connection is made. In the example connection dialog shown in Figure 3-1, the NetBeans IDE and JConsole itself were both started within a Java SE 6 platform VM. Both appear in normal text, meaning that JConsole can connect to them. In Figure 3-1, JConsole is selected, and the note is visible.

  • Applications that are not attachable, with the management agent disabled. These include applications started on a J2SE 1.4.2 platform or started on a J2SE 5.0 platform without the -Dcom.sun.management.jmxremote or com.sun.management.jmxremote.port options. These applications appear grayed-out in the table and JConsole cannot connect to them. In the example connection dialog shown in Figure 3-1, the Anagrams application was started with a J2SE 5.0 platform VM without any of the management properties to enable the JMX agent, and consequently shows up in gray and cannot be selected.

Figure 3-2 Attempting to Connect to an Application without the Management Agent Enabled

Attempting to connect to a local process without the management agent enabled. JConsole cannot connect to this application.

In the example connection dialog shown in Figure 3-2, you can see that the Anagrams application has been selected by clicking on it, but the Connect button remains grayed-out and a note has appeared informing you that the management agent is not enabled for this process. JConsole cannot connect to Anagrams because it was not started with the correct Java VM or with the correct options.

Connecting JConsole to a Remote Process

When the connection dialog opens, you are also given the option of connecting to a remote process.

Figure 3-3 Creating a Connection to a Remote Process

The dialog window for creating connections to remote processes

To monitor a process running on a remote Java VM, you must provide the following information.

  • Host name: name of the machine on which the Java VM is running.

  • Port number: the JMX agent port number you specified when you started the Java VM.

  • User name and password: the user name and password to use (required only if monitoring a Java VM through a JMX agent that requires password authentication).

For information about setting the port number of the JMX agent, see Enabling the Out-of-the-Box Management. For information about user names and passwords, see Using Password and Access Files.

To monitor the Java VM that is running JConsole, simply click Connect, using host localhost and the port 0.

Connecting Using a JMX Service URL

You can also use the Remote Process option to connect to other JMX agents by specifying their JMX service URL, and the user name and password. The syntax of a JMX service URL requires that you provide the transport protocol used to make the connection, as well as a service access point. The full syntax for a JMX service URL is described in the API documentation for javax.management.remote.JMXServiceURL.

Figure 3-4 Connecting to a JMX Agent Using the JMX Service URL

Connecting to a JMX Agent Using the JMX Service URL

If the JMX agent uses a connector which is not included in the Java platform, you need to add the connector classes to the class path when you run the jconsole command, as follows.

% jconsole -J-Djava.class.path=JAVA_HOME/lib/jconsole.jar:JAVA_HOME/lib/tools.jar:connector-path

In the command above, connector-path is the directory or the Java archive (Jar) file containing the connector classes that are not included in the JDK, that are to be used by JConsole.

Presenting the JConsole Tabs

Once you have connected JConsole to an application, JConsole is composed of six tabs.

  • Overview: Displays overview information about the Java VM and monitored values.

  • Memory: Displays information about memory use.

  • Threads: Displays information about thread use.

  • Classes: Displays information about class loading.

  • VM: Displays information about the Java VM.

  • MBeans: Displays information about MBeans.

You can use the green connection status icon in the upper right-hand corner of JConsole at any time, to disconnect from or reconnect to a running Java VM. You can connect to any number of running Java VMs at a time by selecting Connection then New Connection from the drop-down menu.

Viewing Overview Information

The Overview tab displays graphical monitoring information about CPU usage, memory usage, thread counts, and the classes loaded in the Java VM, all in a single screen.

Figure 3-5 Overview Tab

The JConsole Overview tab

The Overview tab provides an easy way to correlate information that was previously only available by switching between multiple tabs.

Saving Chart Data

JConsole allows you to save the data presented in the charts in a Comma Separated Values (CSV) file. To save data from a chart, simply right-click on any chart, select Save data as..., and then specify the file in which the data will be saved. You can save the data from any of the charts displayed in any of JConsole's different tabs in this way.

The CSV format is commonly used for data exchange between spreadsheet applications. The CSV file can be imported into spreadsheet applications and can be used to create diagrams in these applications. The data is presented as two or more named columns, where the first column represents the time stamps. After importing the file into a spreadsheet application, you will usually need to select the first column and change its format to be "date" or "date/time" as appropriate.

Monitoring Memory Consumption

The Memory tab provides information about memory consumption and memory pools.

Figure 3-6 Memory Tab

The JConsole Memory tab.

The Memory tab features a "Perform GC" button that you can click to perform garbage collection whenever you want. The chart shows the memory use of the Java VM over time, for heap and non-heap memory, as well as for specific memory pools. The memory pools available depend on which version of the Java VM is being used. For the HotSpot Java VM, the memory pools for serial garbage collection are the following.

  • Eden Space (heap): The pool from which memory is initially allocated for most objects.

  • Survivor Space (heap): The pool containing objects that have survived the garbage collection of the Eden space.

  • Tenured Generation (heap): The pool containing objects that have existed for some time in the survivor space.

  • Permanent Generation (non-heap): The pool containing all the reflective data of the virtual machine itself, such as class and method objects. With Java VMs that use class data sharing, this generation is divided into read-only and read-write areas.

  • Code Cache (non-heap): The HotSpot Java VM also includes a code cache, containing memory that is used for compilation and storage of native code.

You can display different charts for charting the consumption of these memory pools by choosing from the options in the Chart drop-down menu. Also, clicking on either of the Heap or Non-Heap bar charts in the bottom right-hand corner will switch the chart displayed. Finally, you can specify the time range over which you track memory usage by selecting from the options in the Time Range drop-down menu.

For more information about these memory pools, see Garbage Collection below.

The Details area shows several current memory metrics:

  • Used: the amount of memory currently used, including the memory occupied by all objects, both reachable and unreachable.

  • Committed: the amount of memory guaranteed to be available for use by the Java VM. The amount of committed memory may change over time. The Java virtual machine may release memory to the system and the amount of committed memory could be less than the amount of memory initially allocated at start up. The amount of committed memory will always be greater than or equal to the amount of used memory.

  • Max: the maximum amount of memory that can be used for memory management. Its value may change or be undefined. A memory allocation may fail if the Java VM attempts to increase the used memory to be greater than committed memory, even if the amount used is less than or equal to max (for example, when the system is low on virtual memory).

  • GC time: the cumulative time spent on garbage collection and the total number of invocations. It may have multiple rows, each of which represents one garbage collector algorithm used in the Java VM.

The bar chart on the lower right-hand side shows the memory consumed by the memory pools in heap and non-heap memory. The bar will turn red when the memory used exceeds the memory usage threshold. You can set the memory usage threshold through an attribute of the MemoryMXBean.

Heap and Non-Heap Memory

The Java VM manages two kinds of memory: heap and non-heap memory, both of which are created when the Java VM starts.

  • Heap memory is the runtime data area from which the Java VM allocates memory for all class instances and arrays. The heap may be of a fixed or variable size. The garbage collector is an automatic memory management system that reclaims heap memory for objects.

  • Non-heap memory includes a method area shared among all threads and memory required for the internal processing or optimization for the Java VM. It stores per-class structures such as a runtime constant pool, field and method data, and the code for methods and constructors. The method area is logically part of the heap but, depending on the implementation, a Java VM may not garbage collect or compact it. Like the heap memory, the method area may be of a fixed or variable size. The memory for the method area does not need to be contiguous.

In addition to the method area, a Java VM may require memory for internal processing or optimization which also belongs to non-heap memory. For example, the Just-In-Time (JIT) compiler requires memory for storing the native machine code translated from the Java VM code for high performance.

Memory Pools and Memory Managers

Memory pools and memory managers are key aspects of the Java VM's memory system.

  • A memory pool represents a memory area that the Java VM manages. The Java VM has at least one memory pool and it may create or remove memory pools during execution. A memory pool can belong either to heap or to non-heap memory.

  • A memory manager manages one or more memory pools. The garbage collector is a type of memory manager responsible for reclaiming memory used by unreachable objects. A Java VM may have one or more memory managers. It may add or remove memory managers during execution. A memory pool can be managed by more than one memory manager.

Garbage Collection

Garbage collection (GC) is how the Java VM frees memory occupied by objects that are no longer referenced. It is common to think of objects that have active references as being "alive" and non-referenced (or unreachable) objects as "dead." Garbage collection is the process of releasing memory used by the dead objects. The algorithms and parameters used by GC can have dramatic effects on performance.

The Java HotSpot VM garbage collector uses generational GC. Generational GC takes advantage of the observation that most programs conform to the following generalizations.

  • They create many objects that have short lives, for example, iterators and local variables.

  • They create some objects that have very long lives, for example, high level persistent objects.

Generational GC divides memory into several generations, and assigns one or more memory pools to each. When a generation uses up its allotted memory, the VM performs a partial GC (also called a minor collection) on that memory pool to reclaim memory used by dead objects. This partial GC is usually much faster than a full GC.

The Java HotSpot VM defines two generations: the young generation (sometimes called the "nursery") and the old generation. The young generation consists of an "Eden space" and two "survivor spaces." The VM initially assigns all objects to the Eden space, and most objects die there. When it performs a minor GC, the VM moves any remaining objects from the Eden space to one of the survivor spaces. The VM moves objects that live long enough in the survivor spaces to the "tenured" space in the old generation. When the tenured generation fills up, there is a full GC that is often much slower because it involves all live objects. The permanent generation holds all the reflective data of the virtual machine itself, such as class and method objects.

The default arrangement of generations looks something like Figure 3-7.

Figure 3-7 Generations of Data in Garbage Collection

The different generations of data defined by the Garbage Collector

If the garbage collector has become a bottleneck, you can improve performance by customizing the generation sizes. Using JConsole, you can investigate the sensitivity of your performance metric by experimenting with the garbage collector parameters. For more information, see Tuning Garbage Collection with the 5.0 HotSpot VM.

Monitoring Thread Use

The Threads tab provides information about thread use.

Figure 3-8 Threads Tab

The JConsole Threads tab.

The Threads list in the lower left corner lists all the active threads. If you enter a string in the Filter field, the Threads list will show only those threads whose name contains the string you enter. Click on the name of a thread in the Threads list to display information about that thread to the right, including the thread name, state, and stack trace.

The chart shows the number of live threads over time. Two lines are shown.

  • Red: peak number of threads

  • Blue: number of live threads.

The Threading MXBean provides several other useful operations that are not covered by the Threads tab.

  • findMonitorDeadlockedThreads: Detects if any threads are deadlocked on the object monitor locks. This operation returns an array of deadlocked thread IDs.

  • getThreadInfo: Returns the thread information. This includes the name, stack trace, and the monitor lock that the thread is currently blocked on, if any, and which thread is holding that lock, as well as thread contention statistics.

  • getThreadCpuTime: Returns the CPU time consumed by a given thread

You can access these additional features via the MBeans tab by selecting the Threading MXBean in the MBeans tree. This MXBean lists all the attributes and operations for accessing threading information in the Java VM being monitored. See Monitoring and Managing MBeans.

Detecting Deadlocked Threads

To check if your application has run into a deadlock (for example, your application seems to be hanging), deadlocked threads can be detected by clicking on the "Detect Deadlock" button. If any deadlocked threads are detected, these are displayed in a new tab that appears next to the "Threads" tab, as shown in Figure 3-9.

Figure 3-9 Deadlocked Threads

Deadlocked threads detected by JConsole.

The Detect Deadlock button will detect deadlock cycles involving object monitors and java.util.concurrent ownable synchronizers (see the API specification documentation for java.lang.management.LockInfo). Monitoring support for java.util.concurrent locks has been added in Java SE 6. If JConsole connects to a J2SE 5.0 VM, the Detect Deadlock mechanism will only find deadlocks related to object monitors. JConsole will not show any deadlocks related to ownable synchronizers.

See the API documentation for java.lang.Thread for more information about threads and daemon threads.

Monitoring Class Loading

The Classes tab displays information about class loading.

Figure 3-10 Classes Tab

The chart plots the number of classes loaded over time.

  • The red line is the total number of classes loaded (including those subsequently unloaded).

  • The blue line is the current number of classes loaded.

The Details section at the bottom of the tab displays the total number of classes loaded since the Java VM started, the number currently loaded and the number unloaded. You can set the tracing of class loading to verbose output by checking the checkbox in the top right-hand corner.

Viewing VM Information

The VM Summary tab provides information about the Java VM.

Figure 3-11 VM Summary Tab

The JConsole VM Summary tab.

The information presented in this tab includes the following.

  • Summary

    • Uptime: Total amount of time since the Java VM was started.

    • Process CPU Time: Total amount of CPU time that the Java VM has consumed since it was started.

    • Total Compile Time: Total accumulated time spent in JIT compilation. The Java VM determines when JIT compilation occurs. The Hotspot VM uses adaptive compilation, in which the VM launches an application using a standard interpreter, but then analyzes the code as it runs to detect performance bottlenecks, or "hot spots".

  • Threads

    • Live threads: Current number of live daemon threads plus non-daemon threads.

    • Peak: Highest number of live threads since Java VM started.

    • Daemon threads: Current number of live daemon threads.

    • Total threads started: Total number of threads started since Java VM started, including daemon, non-daemon, and terminated threads.

  • Classes

    • Current classes loaded: Number of classes currently loaded into memory.

    • Total classes loaded: Total number of classes loaded into memory since the Java VM started, including those that have subsequently been unloaded.

    • Total classes unloaded: Number of classes unloaded from memory since the Java VM started.

  • Memory

    • Current heap size: Number of kilobytes currently occupied by the heap.

    • Committed memory: Total amount of memory allocated for use by the heap.

    • Maximum heap size: Maximum number of kilobytes occupied by the heap.

    • Objects pending for finalization: Number of objects pending for finalization.

    • Garbage collector: Information about garbage collection, including the garbage collector names, number of collections performed, and total time spent performing GC.

  • Operating System

    • Total physical memory: Amount of random-access memory (RAM) the operating system has.

    • Free physical memory: Amount of free RAM available to the operating system.

    • Committed virtual memory: Amount of virtual memory guaranteed to be available to the running process.

  • Other Information

    • VM arguments: The input arguments the application passed to the Java VM, not including the arguments to the main method.

    • Class path: The class path that is used by the system class loader to search for class files.

    • Library path: The list of paths to search when loading libraries.

    • Boot class path: The boot class path is used by the bootstrap class loader to search for class files.

Monitoring and Managing MBeans

The MBeans tab displays information about all the MBeans registered with the platform MBean server in a generic way. The MBeans tab allows you to access the full set of the platform MXBean instrumentation, including that which is not visible in the other tabs. In addition, you can monitor and manage your application's MBeans using the MBeans tab.

Figure 3-12 MBeans Tab

The JConsole MBeans tab.

The tree on the left shows all the MBeans currently running. When you select an MBean in the tree, its MBeanInfo and its MBean Descriptor are both displayed on the right, and any attributes, operations or notifications appear in the tree below it.

All the platform MXBeans and their various operations and attributes are accessible via JConsole's MBeans tab.

Constructing the MBean Tree

By default, the MBeans are displayed in the tree based on their object names. The order of key properties specified when the object names are created is preserved by JConsole when it adds MBeans to the MBean tree. The exact key property list that JConsole will use to build the MBean tree will be the one returned by the method ObjectName.getKeyPropertyListString(), with type as the first key, and j2eeType, if present, as the second key.

However, relying on the default order of the ObjectName key properties can sometimes lead to unexpected behavior when JConsole renders the MBean tree. For example, if two object names have similar keys but their key order differs, then the corresponding MBeans will not be created under the same node in the MBean tree.

For example, suppose you create Triangle MBean objects with the following names.

com.sun.example:type=Triangle,side=isosceles,name=1
com.sun.example:type=Triangle,name=2,side=isosceles
com.sun.example:type=Triangle,side=isosceles,name=3

As far as the JMX technology is concerned, these objects will be treated in exactly the same way. The order of the keys in the object name makes no difference to the JMX technology. However, if JConsole connects to these MBeans and the default MBean tree rendering is used, then the object com.sun.example:type=Triangle,name=2,side=isosceles will end up being created under the Triangle node, in a node called 2, which in turn will contain a sub-node called isosceles. The other two isosceles triangles, name=1 and name=3, will be grouped together under Triangle in a different node called isosceles, as shown in Figure 3-13.

Figure 3-13 Example of Unexpected MBean Tree Rendering

Example of Unexpected MBean Tree Rendering

To avoid this problem, you can specify the order in which the MBeans are displayed in the tree by supplying an ordered key property list when you start JConsole at the command line. This is achieved by setting the system property com.sun.tools.jconsole.mbeans.keyPropertyList, as shown in the following command.

% jconsole -J-Dcom.sun.tools.jconsole.mbeans.keyPropertyList=key[,key]*

The key property list system property takes a comma-separated list of keys, in the order of your choosing, where key must be a string representing an object name key or an empty string. If a key specified in the list does not apply to a particular MBean, then that key will be discarded. If an MBean has more keys than the ones specified in the key property list, then the key order defined by the value returned by ObjectName.getKeyPropertyListString() will be used to complete the key order defined by keyPropertyList. Therefore, specifying an empty list of keys simply means that JConsole will display keys in the order they appear in the MBean's ObjectName.

So, returning to the example of the Triangle MBeans cited above, you could choose to start JConsole specifying the keyPropertyList system property, so that all your MBeans will be grouped according to their side key property first, and their name key property second. To do this, you would start JConsole with the following command.

% jconsole -J-Dcom.sun.tools.jconsole.mbeans.keyPropertyList=side,name

Starting JConsole with this system property specified would produce the MBean tree shown in Figure 3-14.

Figure 3-14 Example of MBean Tree Constructed Using keyPropertyList

Example of MBean Tree Constructed Using keyPropertyList

In Figure 3-14, the side key comes first, followed by the name key. The type key comes at the end because it was not specified in the key property list, so the MBean tree algorithm applied the original key order for the remaining keys. Consequently, the type key is appended at the end, after the keys which were defined by the keyPropertyList system property.

According to the object name convention defined by the JMX Best Practices Guidelines, the type key should always come first. So, to respect this convention you should start JConsole with the following system property.

% jconsole -J-Dcom.sun.tools.jconsole.mbeans.keyPropertyList=type,side,name

The above command will cause JConsole to render the MBean tree for the Triangle MBeans as shown in Figure 3-15.

Figure 3-15 Example of MBean Tree Constructed Respecting JMX Best Practices

Example of MBean Tree Constructed Respecting JMX Best Practices

This is obviously much more comprehensible than the MBean trees shown in Figure 3-13 and Figure 3-14.

MBean Attributes

Selecting the Attributes node displays all the attributes of an MBean. Figure 3-16 shows all the attributes of the Threading platform MXBean.

Figure 3-16 Viewing All MBean Attributes

Viewing the attributes of the Threading MBean.

Selecting an individual MBean attribute from the tree then displays the attribute's value, its MBeanAttributeInfo, and the associated Descriptor in the right pane, as you can see in Figure 3-17.

Figure 3-17 Viewing an Individual MBean Attribute

Viewing MBean attributes in the MBeans tab.

You can display additional information about an attribute by double-clicking on the attribute value, if it appears in bold text. For example, if you click on the value of the HeapMemoryUsage attribute of the java.lang.Memory MBean, you will see a chart that looks something like Figure 3-18.

Figure 3-18 Displaying Attribute Values

Viewing the values of MBean attributes.

Double-clicking on numeric attribute values will display a chart that plots changes in that numeric value. For example, double-clicking on the CollectionTime attribute of the Garbage Collector MBean PS Marksweep will plot the time spent performing garbage collection.

You can also use JConsole to set the values of writable attributes. The value of a writable attribute is displayed in blue. Here you can see the Memory MBean's Verbose attribute.

Figure 3-19 Setting Writable Attribute Values

Setting an MBean's writable attribute value.

You can set attributes by clicking on them and then editing them. For example, to enable or disable the verbose tracing of the garbage collector in JConsole, select the Memory MXBean in the MBeans tab and set the Verbose attribute to true or false. Similarly, the class loading MXBean also has the Verbose attribute, which can be set to enable or disable class loading verbose tracing.

MBean Operations

Selecting the Operations node displays all the operations of an MBean. The MBean operations appear as buttons, that you can click to invoke the operation.Figure 3-20 shows all the operations of the Threading platform MXBean.

Figure 3-20 Viewing All MBean Operations

Viewing the Threading platform MXBean's operations.

Selecting an individual MBean operation in the tree displays the button for invoking the MBean operation, and the operation's MBeanOperationInfo and its Descriptor, as shown in Figure 3-21.

Figure 3-21 Viewing Individual MBean Operations

Invoking an MBean's operations.

MBean Notifications

You can subscribe to receive notifications by selecting the Notifications node in the left-hand tree, and clicking the Subscribe button that appears on the right. The number of notifications received is displayed in square brackets, and the Notifications node itself will appear in bold text when new notifications are received. The notifications of the Memory platform MXBean are shown in Figure 3-22.

Figure 3-22 Viewing MBean Notifications

Viewing an MBean's notifications.

Selecting an individual MBean notification displays the MBeanNotificationInfo in the right pane, as shown in Figure 3-23.

Figure 3-23 Viewing Individual MBean Notifications

Subscribing to receive MBean Notifications.

HotSpot Diagnostic MXBean

JConsole's MBeans tab also allows you to tell the HotSpot VM to perform a heap dump, and to get or set a VM option via the HotSpotDiagnostic MXBean.

Figure 3-24 Viewing the HotSpot Diagnostic MBean

Performing heap dumps using the HotSpot VM Diagnostic MBean.

You can perform a heap dump manually by invoking the com.sun.management.HotSpotDiagnostic MXBean's dumpHeap operation. In addition, you can specify the HeapDumpOnOutOfMemoryError Java VM option using the setVMOption operation, so that the VM performs a heap dump automatically whenever it receives an OutOfMemoryError.

Creating Custom Tabs

In addition to the existing standard tabs, you can add your own custom tabs to JConsole, to perform your own monitoring activities. The JConsole plug-in API provides a mechanism by which you can, for example, add a tab to access your own application's MBeans. The JConsole plug-in API defines the com.sun.tools.jconsole.JConsolePlugin abstract class that you can extend to build your custom plug-in.

As stated above, your plug-in must extend JConsolePlugin, and implement the JConsolePlugin getTabs and newSwingWorker methods. The getTabs method returns either the list of tabs to be added to JConsole, or an empty list. The newSwingWorker method returns the SwingWorker to be responsible for the plug-in's GUI update.

Your plug-in must be provided in a Java archive (JAR) file that contains a file named META-INF/services/com.sun.tools.jconsole.JConsolePlugin. This JConsolePlugin file itself contains a list of all the fully-qualified class names of the plug-ins you want to add as new JConsole tabs. JConsole uses the service-provider loading facility to look up and load the plug-ins. You can have multiple plug-ins, with one entry per plug-in in the JConsolePlugin.

To load the new custom plug-ins into JConsole, start JConsole with the following command:

%  jconsole -pluginpath plugin-path

In the above command, plugin-path specifies the paths to the JConsole plug-ins to be looked up. These paths can either be to directory names or to JAR files, and multiple paths can be specified, using your platform's standard separator character.

An example JConsole plug-in is provided with the Java SE 6 platform. The JTop application is a JDK demonstration that shows the CPU usage of all threads running in the application. This demo is useful for identifying threads that have high CPU consumption, and it has been updated to be used as a JConsole plug-in as well as a standalone GUI. JTop is bundled with the Java SE 6 platform, as a demo application. You can run JConsole with the JTop plug-in by running the following command:

% JDK_HOME/bin/jconsole -pluginpath JDK_HOME/demo/management/JTop/JTop.jar

If you connect to this instance of JConsole, you will see that the JTop tab has been added, showing CPU usage of the various threads running.

Figure 3-25 Viewing a Custom Plug-in Tab

A custom tab showing connected to the JTop example program.
Previous Previous Contents Next Next
Company Info Contact Terms of Use Privacy Copyright 1994-2006 Sun Microsystems, Inc.


4. Using the Platform MBean Server and Platform MXBeans

Home Page
Products
Downloads
Service & Solutions
Support
Training
Research
Java SE Monitoring and Management Guide

Previous Previous Contents Next Next
Chapter 4

Using the Platform MBean Server and Platform MXBeans

This chapter introduces the MBean server and the MXBeans that are provided as part of the Java Platform, Standard Edition (Java SE platform), which can be used for monitoring and management purposes. Java Management Extensions (JMX) technology MBeans and MBean servers were introduced briefly in Chapter 1, Overview of Java SE Monitoring and Management. More information about the JMX technology can be found in the JMX Technology documentation for the Java SE platform.

Using the Platform MBean Server

An MBean server is a repository of MBeans that provides management applications access to MBeans. Applications do not access MBeans directly, but instead access them through the MBean server via their unique ObjectName. An MBean server implements the interface javax.management.MBeanServer.

The platform MBean server was introduced in the Java 2 Platform, Standard Edition 5.0, and is an MBean server that is built into the Java Virtual Machine (Java VM). The platform MBean server can be shared by all managed components that are running in the Java VM. You access the platform MBean server using the java.lang.management.ManagementFactory method getPlatformMBeanServer. Of course, you can also create your own MBean server using the javax.management.MBeanServerFactory class. However, there is generally no need for more than one MBean server, so using the platform MBean server is recommended.

Accessing Platform MXBeans

A platform MXBean, is an MBean for monitoring and managing the Java VM. Each MXBean encapsulates a part of the VM functionality. A full list of the MXBeans that are provided with the platform is provided in Table 1-1 in Chapter 1, Overview of Java SE Monitoring and Management.

A management application can access platform MXBeans in three different ways.

  • Direct access, via the ManagementFactory class.

  • Direct access, via an MXBean proxy.

  • Indirect access, via the MBeanServerConnection class.

These three ways of accessing the platform MXBeans are described in the next three sections.

Accessing Platform MXBeans via the ManagementFactory Class

An application can make direct calls to the methods of a platform MXBean that is running in the same Java VM as itself. To make direct calls, you can use the static methods of the ManagementFactory class. ManagementFactory has accessor methods for each of the different platform MXBeans, such as, getClassLoadingMXBean(), getGarbageCollectorMXBeans(), getRuntimeMXBean(), and so on. In cases where there are more than one platform MXBean, the method returns a list of the platform MXBeans found.

For example, Example 4-1 uses the static method of ManagementFactory to get the platform MXBean RuntimeMXBean, and then gets the vendor name from the platform MXBean.

Example 4-1 Accessing a Platform MXBean via the ManagementFactory Class

RuntimeMXBean mxbean = ManagementFactory.getRuntimeMXBean();
String vendor = mxbean.getVmVendor();

Accessing Platform MXBeans via an MXBean Proxy

An application can also call platform MXBean methods via an MXBean proxy. To do so, you must construct an MXBean proxy instance that forwards the method calls to a given MBean server by calling the static method ManagementFactory.newPlatformMXBeanProxy(). An application typically constructs a proxy to obtain remote access to a platform MXBean of another Java VM.

For example, Example 4-2 performs exactly the same operation as Example 4-1, but this time uses an MXBean proxy.

Example 4-2 Accessing a Platform MXBean via an MXBean Proxy

MBeanServerConnection mbs;
...
// Get a MBean proxy for RuntimeMXBean interface
RuntimeMXBean proxy =
    ManagementFactory.newPlatformMXBeanProxy(mbs,
                                             ManagementFactory.RUNTIME_MXBEAN_NAME,
                                             RuntimeMXBean.class);
// Get standard attribute "VmVendor"
String vendor = proxy.getVmVendor();

Accessing Platform MXBeans via the MBeanServerConnection Class

An application can indirectly call platform MXBean methods through an MBeanServerConnection that connects to the platform MBean server of another running Java VM. You use the MBeanServerConnection class's getAttribute() method to get an attribute of a platform MXBean, providing the MBean's ObjectName and the attribute name as parameters.

For example, Example 4-3 performs the same job as Example 4-1 and Example 4-2, but uses an indirect call through MBeanServerConnection.

Example 4-3 Accessing a Platform MXBean via the MBeanServerConnection Class

MBeanServerConnection mbs;
...
try {
  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
  ...
}

Using Sun Microsystems' Platform Extension

Java VMs can extend the management interface by defining interfaces for platform-specific measurements and management operations. The static factory methods in the ManagementFactory class will return the MBeans with the platform extension.

The com.sun.management package contains Sun Microsystems' platform extensions. The following sections provide examples of how to access a platform-specific attribute from Sun Microsystems' implementation of the OperatingSystemMXBean.

Accessing MXBean Attributes Directly

Example 4-4 illustrates direct access to one of Sun Microsystems' MXBean interfaces.

Example 4-4 Accessing an MXBean Attribute Directly

com.sun.management.OperatingSystemMXBean mxbean =
  (com.sun.management.OperatingSystemMXBean) ManagementFactory.getOperatingSystemMXBean();

// Get the number of processors
int numProcessors = mxbean.getAvailableProcessors();

// Get the Sun-specific attribute Process CPU time
long cpuTime = mxbean.getProcessCpuTime();

Accessing MXBean Attributes via MBeanServerConnection

Example 4-5 illustrates access to one of Sun Microsystems' MXBean interfaces via the MBeanServerConnection class.

Example 4-5 Accessing an MXBean Attribute via MBeanServerConnection

MBeanServerConnection mbs;

// Connect to a running Java VM (or itself) and get MBeanServerConnection
// that has the MXBeans registered in it
...

try {
    // Assuming the OperatingSystem MXBean has been registered in mbs
    ObjectName oname = new ObjectName(ManagementFactory.OPERATING_SYSTEM_MXBEAN_NAME);

    // Get standard attribute "Name"
    String vendor = (String) mbs.getAttribute(oname, "Name");

    // Check if this MXBean contains Sun Microsystems' extension
    if (mbs.isInstanceOf(oname, "com.sun.management.OperatingSystemMXBean")) {
        // Get platform-specific attribute "ProcessCpuTime"
        long cpuTime = (Long) mbs.getAttribute(oname, "ProcessCpuTime");
    }
} catch (....) {
    // Catch the exceptions thrown by ObjectName constructor
    // and MBeanServer methods
    ...
}

Monitoring Thread Contention and CPU Time

The ThreadMXBean platform MXBean provides support for monitoring thread contention and thread Central Processing Unit (CPU) time.

The Sun HotSpot VM supports thread contention monitoring. You use the ThreadMXBean.isThreadContentionMonitoringSupported() method to determine if a Java VM supports thread contention monitoring. Thread contention monitoring is disabled by default. Use the setThreadContentionMonitoringEnabled() method to enable it.

The Sun HotSpot VM supports the measurement of thread CPU time on most platforms. The CPU time provided by this interface has nanosecond precision but not necessarily nanosecond accuracy.

You use the isThreadCpuTimeSupported() method to determine if a Java VM supports the measurement of the CPU time for any thread. You use isCurrentThreadCpuTimeSupported() to determine if a Java VM supports the measurement of the CPU time for the current thread. A Java VM that supports CPU time measurement for any thread will also support that for the current thread.

A Java VM can disable thread CPU time measurement. You use the isThreadCpuTimeEnabled() method to determine if thread CPU time measurement is enabled . You use the setThreadCpuTimeEnabled() method to enable or disable the measurement of thread CPU time.

Managing the Operating System

The OperatingSystem platform MXBean allows you to access certain operating system resource information, such as the following.

  • Process CPU time.

  • Amount of total and free physical memory.

  • Amount of committed virtual memory (that is, the amount of virtual memory guaranteed to be available to the running process).

  • Amount of total and free swap space.

  • Number of open file descriptors (only for UNIX platforms).

When the Operating System MXBean in the MBeans tab is selected in JConsole, you see all the attributes and operations including the platform extension. You can monitor the changes of a numerical attribute over time by double-clicking the value field of the attribute.

Logging Management

The Java SE platform provides a special MXBean for logging purposes, the LoggingMXBean interface.

The LoggingMXBean enables you to perform the following tasks.

  • Get the name of the log level associated with the specified logger.

  • Get the list of currently registered loggers.

  • Get the name of the parent for the specified logger.

  • Set the specified logger to the specified new level.

The unique ObjectName of the LoggingMXBean is java.util.logging:type=Logging. This object name is stored in LogManager.LOGGING_MXBEAN_NAME.

There is a single global instance of the LoggingMXBean, which you can get by calling LogManager.getLoggingMXBean().

The Logging MXBean defines a LoggerNames attribute describing the list of logger names. To find the list of loggers in your application, you can select the Logging MXBean under the java.util.logging domain in the MBeans tab, and double-click on the value field of the LoggerNames attribute. The Logging MXBean also supports two operations.

  • getLoggerLevel: Returns the log level of a given logger.

  • setLoggerLevel: Sets the log level of a given logger to a new level.

These operations take a logger name as the first parameter. To change the level of a logger, enter the logger name in the first parameter and the name of the level it should be set to in the second parameter of the setLoggerLevel operation.

Detecting Low Memory

Memory use is an important attribute of the memory system. It can be indicative of the following problems.

  • Excessive memory consumption by an application.

  • An excessive workload imposed on the automatic memory management system.

  • Potential memory leakages.

There are two kinds of memory thresholds you can use to detect low memory conditions: a usage threshold and a collection usage threshold. You can detect low memory conditions using either of these thresholds with polling or threshold notification. All these concepts are described in the next sections.

Memory Thresholds

A memory pool can have two kinds of memory thresholds: a usage threshold and a collection usage threshold. Either one of these thresholds may not be supported by a particular memory pool. The values for the usage threshold and collection usage threshold can both be set using the MBeans tab in JConsole.

Usage Threshold

The usage threshold is a manageable attribute of some memory pools. It enables you to monitor memory use with a low overhead. Setting the threshold to a positive value enables a memory pool to perform usage threshold checking. Setting the usage threshold to zero disables usage threshold checking. The default value is supplied by the Java VM.

A Java VM performs usage threshold checking on a memory pool at the most appropriate time, typically during garbage collection. Each memory pool increments a usage threshold count whenever the usage crosses the threshold.

You use the isUsageThresholdSupported() method to determine whether a memory pool supports a usage threshold, since a usage threshold is not appropriate for some memory pools. For example, in a generational garbage collector (such as the one in the HotSpot VM; see Garbage Collection in Chapter 3, Using JConsole), most of the objects are allocated in the young generation, from the Eden memory pool. The Eden pool is designed to be filled up. Garbage collecting the Eden memory pool will free most of its memory space since it is expected to contain mostly short-lived objects that are unreachable at garbage collection time. So, it is not appropriate for the Eden memory pool to support a usage threshold.

Collection Usage Threshold

The collection usage threshold is a manageable attribute of some garbage-collected memory pools. After a Java VM has performed garbage collection on a memory pool, some memory in the pool will still be in use. The collection usage threshold allows you to set a value for this memory. You use the isCollectionUsageThresholdSupported() method of MemoryPoolMXBean to determine if the pool supports a collection usage threshold.

A Java VM may check the collection usage threshold on a memory pool when it performs garbage collection. Set the collection usage threshold to a positive value to enable checking. Set the collection usage threshold to zero (the default) to disable checking.

The usage threshold and collection usage threshold can be set in the MBeans tab of JConsole.

Memory MXBean

The various memory thresholds can be managed via the platform MemoryMXBean. The MemoryMXBean defines the following four attributes.

  • HeapMemoryUsage: A read-only attribute describing the current heap memory usage.

  • NonHeapMemoryUsage: A read-only attribute describing non-heap memory usage.

  • ObjectPendingFinalizationCount: A read-only attribute describing the number of objects pending for finalization.

  • Verbose: A boolean attribute describing the Garbage Collection (GC) verbose tracing setting. This can be set dynamically. The GC verbose traces will be displayed at the location specified when you start the Java VM. The default location for GC verbose output of the Hotspot VM is stdout.

The Memory MXBean supports one operation, gc, for explicit garbage collection requests.

Details of the Memory MXBean interface are defined in the java.lang.management.MemoryMXBean specification.

Memory Pool MXBean

The MemoryPoolMXBean platform MXBean defines a set of operations to manage memory thresholds.

  • getUsageThreshold()

  • setUsageThreshold(long threshold)

  • isUsageThresholdExceeded()

  • isUsageThresholdSupported()

  • getCollectionUsageThreshold()

  • setCollectionUsageThreshold(long threshold)

  • isCollectionUsageThresholdSupported()

  • isCollectionUsageThresholdExceeded()

Each memory pool may have two kinds of memory thresholds for low memory detection support: a usage threshold and a collection usage threshold. Either one of these thresholds might not be supported by a particular memory pool. For more information, see the API reference documentation for the MemoryPoolMXBean class.

Polling

An application can continuously monitor its memory usage by calling either the getUsage() method for all memory pools or the isUsageThresholdExceeded() method for memory pools that support a usage threshold.

Example 4-6 has a thread dedicated to task distribution and processing. At every interval, it determines whether it should receive and process new tasks based on its memory usage. If the memory usage exceeds its usage threshold, it redistributes outstanding tasks to other VMs and stops receiving new tasks until the memory usage returns below the threshold.

Example 4-6 Using Polling

pool.setUsageThreshold(myThreshold);
....
boolean lowMemory = false;
while (true) {
  if (pool.isUsageThresholdExceeded()) {
    lowMemory = true;
    redistributeTasks();  // redistribute tasks to other VMs
    stopReceivingTasks();  // stop receiving new tasks
  } else {
    if (lowMemory) { // resume receiving tasks
      lowMemory = false;
      resumeReceivingTasks();
    }
    // processing outstanding task
    ...
  }
  // sleep for sometime
  try {
    Thread.sleep(sometime);
  } catch (InterruptedException e) {
    ...
  }
}

Example 4-6 does not differentiate the case in which the memory usage has temporarily dropped below the usage threshold from the case in which the memory usage remains above the threshold between two iterations. You can use the usage threshold count returned by getUsageThresholdCount() to determine if the memory usage has returned below the threshold between two polls.

To test the collection usage threshold instead, you use the isCollectionUsageThresholdSupported(), isCollectionThresholdExceeded() and getCollectionUsageThreshold() methods in the same way as above.

Threshold Notifications

When the MemoryMXBean detects that a memory pool has reached or exceeded its usage threshold, it emits a usage threshold exceeded notification. The MemoryMXBean will not issue another usage threshold exceeded notification until the usage has fallen below the threshold and then exceeded it again. Similarly, when the memory usage after garbage collection exceeds the collection usage threshold, the MemoryMXBean emits a collection usage threshold exceeded notification.

Example 4-7 implements the same logic as Example 4-6, but uses usage threshold notification to detect low memory conditions. Upon receiving a notification, the listener notifies another thread to perform actions such as redistributing outstanding tasks, refusing to accept new tasks, or allowing new tasks to be accepted again.

In general, you should design the handleNotification method to do a minimal amount of work, to avoid causing delay in delivering subsequent notifications. You should perform time-consuming actions in a separate thread. Since multiple threads can concurrently invoke the notification listener, the listener should synchronize the tasks it performs properly.

Example 4-7 Using Threshold Notifications

class MyListener implements javax.management.NotificationListener {
  public void handleNotification(Notification notification, Object handback)  {
    String notifType = notification.getType();
    if (notifType.equals(MemoryNotificationInfo.MEMORY_THRESHOLD_EXCEEDED)) {
      // potential low memory, redistribute tasks to other VMs & stop receiving new tasks.
      lowMemory = true;
      notifyAnotherThread(lowMemory);
    }
  }
}

// Register MyListener with MemoryMXBean
MemoryMXBean mbean = ManagementFactory.getMemoryMXBean();
NotificationEmitter emitter = (NotificationEmitter) mbean;
MyListener listener = new MyListener();
emitter.addNotificationListener(listener, null, null);

Assuming this memory pool supports a usage threshold, you can set the threshold to some value (representing a number of bytes), above which the application will not accept new tasks.

pool.setUsageThreshold(myThreshold);

After this point, usage threshold detection is enabled and MyListener will handle notification.

Previous Previous Contents Next Next
Company Info Contact Terms of Use Privacy Copyright 1994-2006 Sun Microsystems, Inc.


5. SNMP Monitoring and Management

Home Page
Products
Downloads
Service & Solutions
Support
Training
Research
Java SE Monitoring and Management Guide

Previous Previous Contents Next Next
Chapter 5

SNMP Monitoring and Management

The Simple Network Management Protocol (SNMP) is an industry standard for network management. Objects managed by SNMP are arranged in management information bases (MIBs). The SNMP agent publishes the standard MIB for the Java virtual machine (Java VM) instrumentation. The standard MIB for monitoring and management of the Java VM is available for download at http://java.sun.com/javase/6/docs/jre/api/management/JVM-MANAGEMENT-MIB.mib.

Enabling the SNMP Agent

To monitor a Java VM with SNMP you must first enable an SNMP agent when you start the Java VM. You can enable the SNMP agent for either a single-user environment or a multiple-user environment. Then, you can monitor the Java VM with an SNMP-compliant tool.

For general information on setting system properties when you start the Java VM, see Setting System Properties in Chapter 2, Monitoring and Management Using JMX Technology. How to enable the SNMP agent in single and multiple-user environments is described below. The process is the same for both environments, but the actions performed are slightly different.

Access Control List File

An Access Control List (ACL) template file is provided with the Java Platform, Standard Edition (Java SE platform) in JRE_HOME/lib/management/snmp.acl.template, where JRE_HOME is the directory in which the Java Runtime Environment (JRE) implementation is installed. You will copy this file to either JRE_HOME/lib/management/snmp.acl or to your home directory, depending on whether you are operating in a single or a multiple-user environment. Ensure that only you have read permissions, since the file contains non-encrypted SNMP community strings. For security reasons, the system checks that only the owner has read permissions on the file and exits with an error if this is not the case. Thus, in a multiple-user environment, you should put this file in private location, such as your home directory.

Example 5-1 shows some possible entries in an ACL file.

Example 5-1 Sample ACL Entries

#The communities public and private are allowed access from the local host.
acl = {
        {
          communities = public, private
          access = read-only
          managers = localhost
        }
      }
# Traps are sent to localhost only
trap = {
          {
            trap-community = public
            hosts = localhost
          }
        }

Procedure To Enable the SNMP Agent in a Single-user Environment

  1. Set the following system property when you start the Java VM.

    com.sun.management.snmp.port=portNum

    In the property above, portNum is the port number to use for monitoring. Setting this property starts an SNMP agent that listens on the specified port number for incoming SNMP requests.

  2. Create an ACL File.

    Copy the ACL template file from JRE_HOME/lib/management/snmp.acl.template to JRE_HOME/lib/management/snmp.acl.

  3. Set the permissions on the ACL file.

    Make sure the ACL file is readable by only the owner, and add community strings as needed.

Procedure To Enable the SNMP Agent in a Multiple-user Environment

  1. Set the following system properties when you start the Java VM.

    com.sun.management.snmp.port=portNum
com.sun.management.snmp.acl.file=ACLFilePath

    Where ACLFilePath is the path to the ACL file.

  2. Create an ACL File.

    Copy the ACL template file from JRE_HOME/lib/management/snmp.acl.template to a file named snmp.acl in your home directory.

  3. Set the permissions on the ACL file.

    Make sure the ACL file is readable by only the owner, and add community strings as needed.

SNMP Monitoring and Management Properties

You can set SNMP monitoring and management properties in a configuration file or on the command line. Properties specified on the command line override properties in a configuration file. The default location for the configuration file is JRE_HOME/lib/management/management.properties. The Java VM reads this file if the command-line property com.sun.management.snmp.port is set.

You can specify a different location for the configuration file with the following command-line option.

com.sun.management.config.file=ConfigFilePath

In the property above, ConfigFilePath is the path to the configuration file.

You must specify all system properties when you start the Java VM. After the Java VM has started, any changes to system properties (for example, via the setProperty method), to the password file, to the ACL file, or to the configuration file will have no effect.

Table 5-1 describes all the SNMP management properties.

Table 5-1 SNMP monitoring and management Properties

Property Name | Description | Default
com.sun.management.snmp.trap | Remote port to which the SNMP agent sends traps. | 162
com.sun.management.snmp. interface | Optional. The local host InetAddress, to force the SNMP agent to bind to the given InetAddress. This is for multi-home hosts if one wants to listen to a specific subnet only. | Not applicable
com.sun.management.snmp.acl | Enables or disables SNMP ACL checks. | true
com.sun.management.snmp. acl.file | Path to a valid ACL file. After the Java VM has started, modifying the ACL file has no effect. | JRE_HOME/lib/management/snmp.acl

Configuration Errors

If any errors occur during start up of the SNMP agent, the Java VM will throw an exception and exit. Configuration errors include the following.

  • Failure to bind to the port number.

  • The password file is readable by anyone other than the owner.

  • Invalid SNMP ACL file.

If your application runs a security manager, then additional permissions are required in the security permissions file.

Previous Previous Contents Next Next
Company Info Contact Terms of Use Privacy Copyright 1994-2006 Sun Microsystems, Inc.


A. Additional Security Information For Microsoft Windows

Home Page
Products
Downloads
Service & Solutions
Support
Training
Research
Java SE Monitoring and Management Guide

Previous Previous Contents
Appendix A

Additional Security Information For Microsoft Windows

How to Secure a Password File on Microsoft Windows Systems

For remote monitoring and management, password and access files are used to control security. How to set the file permissions for a password file is described for Solaris and Linux platforms in Using Password and Access Files in Chapter 2, Monitoring and Management Using JMX Technology.

This appendix describes how to set the file permissions of the password file on a Windows system using a New Technology File System (NTFS) so that only the owner has read and write permissions on this file. If the file system is a File Allocation Table (FAT) 32 system, then security is not supported for this file system and the password file cannot be secured.

Securing a password file is done differently in the different versions of Windows XP. Solutions for both Windows XP Professional Edition and Windows XP Home Edition are provided in this appendix.

Procedure To Secure a Password File on Windows XP Professional Edition

The procedure given below will not work if you are running Windows XP Home Edition, which does not allow you to change file permissions graphically. A solution is given in To Secure a Password File on Windows XP Home Edition below.

Note - The solution using the cacls command described in To Secure a Password File on Windows XP Home Edition can also be used on Windows XP Professional Edition, as a command-line alternative to using the graphical interfaces.

  1. In Windows Explorer, navigate to the directory containing the jmxremote.password file.

  2. Right-click on the jmxremote.password file and select the Properties option.

    Displaying the jmxremote.password file properties

  3. Select the Security tab

    Displaying the jmxremote.password file's security properties

    If you are using Windows XP Professional Edition and the computer is not part of a domain, then the Security tab will not be automatically visible. To reveal the Security tab, you must perform the following steps.

    1. Open Windows Explorer, and choose Folder Options from the Tools menu.

    2. Select the View tab and scroll to the bottom of the Advanced Settings and clear the Use Simple File Sharing check box.

      Displaying the Security tab in Windows XP.

    3. Click OK to apply the change.

    4. Restart Windows Explorer.

      The Security tab will now be visible

  4. Select the Advanced button in the Security tab.

    Displaying advanced security properties.

  5. Select the Owner tab to check if the file owner matches the user under which the Java VM is running.

    Checking who owns the password file.

  6. Select the Permissions tab to set the permissions.

    If there are permission entries inherited from a parent directory that allow users or groups other than the owner access to the file, then clear the "Inherit from parent the permission entries that apply to child objects" checkbox.

    Blocking inheritance of file permissions from parent objects.

  7. A dialog box will ask if the inherited permissions should be copied from the parent or removed. Press the Copy button.

    Copying permissions from the parent.

  8. Remove all permission entries that grant access to users or groups other than the file owner.

    Do this by clicking the user or group and pressing the Remove button for all users and groups except the file owner.

    Removing permissions from all users but the owner.

    Now there should be a single permission entry which grants Full Control to the owner.

  9. Press OK to apply the file security change.

    The password file is now secure and can only be accessed by the owner.

  10. Press OK in the jmxremote.password Properties dialog.

Procedure To Secure a Password File on Windows XP Home Edition

As stated above, Windows XP Home Edition does not allow you to set file permissions graphically. However, you can set permissions using the cacls command.

  1. Open a command prompt window.

  2. Run the following command

    C:\MyPasswordFile>cacls jmxremote.password

    This command displays the access control list (ACL) of the jmxremote.password file.

  3. Set the access rights so that only your username has read access.

    When no users have been configured on the machine the default username is usually Owner, or a localized translation of Owner.

    C:\MyPasswordFile>cacls jmxremote.password /P Owner:R

    This command grants access to the user Owner with read-only permission, where Owner is the owner of the jmxremote.password file.

  4. Display the ACL again.

    C:\MyPasswordFile>cacls jmxremote.password

    This time, you will see that only the Owner has access to the password file.

    Changing file permissions in Windows XP.
Previous Previous Contents
Company Info Contact Terms of Use Privacy Copyright 1994-2006 Sun Microsystems, Inc.


Frequently Asked Questions
JConsole and Remote Management

JConsole and JMX Remote Management

  1. I run JConsole on Windows. Why does the Local tab in Connect dialog not list any Java processes?
  2. JDK 5 jconsole and jps commands do not work if your username contains '_' (underscore) on Windows. JConsole is unable to find your Java processes.
  3. How to secure the password file on Windows systems?
  4. JConsole fails to connect to an application remotely or locally running on the same machine using the Remote Tab. However, it works when connecting to it using the Local Tab on the same machine.
  5. I am having problem using JConsole to connect to a JVM running on Linux. Connecting to JVM running on Windows and Solaris works fine.
  6. My application has remote management enabled with SSL. How to setup JConsole to connect to my application?
  7. Can I use JConsole to monitor an application through a firewall?

SNMP Based Management

  1. Where is the standard MIB for SNMP management of the Java virtual machine? What version of SNMP protocol does it require?
  2. I'm not able to see all objects the JVM MIB tree. For example, the jvmMemoryHeapUsed OID is missing. Is it a known problem?

JConsole and JMX Remote Management

  1. I run JConsole on Windows. Why does the Local tab in Connect dialog not list any Java process?

    The problem is most likely that your default Windows temporary directory is on a FAT file system. If your TMP file system is NTFS and JConsole does not show your processes, check your username as described in FAQ #2.

    For security reasons, local monitoring and management is only supported if your default Windows temporary directory is on a file system that supports setting permissions on files and directories (for example, on an NTFS file system). It is not supported on a FAT file system that provide insufficient access controls.

    A potential workaround for this issue:
    Set the TMP environment variable to refer to a directory on an NTFS file system, or any file system that supports setting permissions on files and directories before you run your application with local or remote management enabled. Note that this file system should be local to the machine. Setting this option for target applications is application specific. To set this variable in a command prompt or in a batch script, simply enter the following:

    set TMP=path

    The environment variable can be set globally by adding it to the list of environment variables in the System Properties (Control Panel->System, select the "Advanced" tab and click on the "Environment Variables" button). Through this interface, you can choose to set the variable for all processes run by the current user or globally as a system variable for all processes run by the system.

  2. JDK 5 jconsole and jps commands do not work if your username contains '_' (underscore) on Windows. JConsole is unable to find your Java processes.

    It is a known problem in JDK 5 that jconsole and jps commands do not work on Windows if your username contains '_' (underscore). Bug 6301562 will be fixed in a future release.

  3. How to secure the password file on Windows systems?

    Please see the "How to secure a password file on Windows systems" document for details.

  4. JConsole fails to connect to an application remotely or locally running on the same machine using the Remote Tab. However, it works when connecting to it using the Local Tab on the same machine.

    It is most likely a configuration problem. First, make sure your application was started with remote management enabled. (See details from the "Monitoring and Management using JMX" document.) Second, check if SSL is enabled in the management properties to enable remote management and if it is configured properly.

    SSL is enabled by default when the remote management is enabled. You can disable SSL by setting com.sun.management.jmxremote.ssl property to false. If your application is not set up with SSL properly but SSL is enabled for remote management, JConsole will fail to connect to the application. Please see "Using SSL" section in the "Monitoring and Management Using JMX" document for information about using SSL for remote management.

    If the connection failure problem occurs only when your application runs on Linux, please see FAQ #5.

  5. I am having problem using JConsole to connect to a JVM running on Linux. Connecting to JVM running on Windows and Solaris works fine.

    This is most likely a configuration problem on the Linux machine or the management properties specified to run the application. Please also see FAQ #4 about using SSL.

    You should check the following:

    • Check if the hostname correctly resolves to the host address.

      Run "hostname -i" command. If it reports 127.0.0.1, JConsole would not be able to connect to the JVM running on that Linux machine. To fix this issue, edit /etc/hosts so that the hostname resolves to the host address.

    • Check if the Linux machine is configured to accept packets from the host where JConsole runs on to connect to the application.

      Packet filtering is built in the Linux kernel. You can run "/sbin/iptables --list" to determine if an external client is allowed to connect to the JMX agent created for remote management. You can use the following command to add a rule to allow an external client such as JConsole to connect:

      /usr/sbin/iptables -I INPUT -s jconsole-host -p tcp --destination-port jmxremote-port -j ACCEPT

      where jconsole-host is either the hostname or the host address on which JConsole runs on and jmxremote-port is the port number set for com.sun.management.jmxremote.port for remote management.

  6. My application has remote management enabled with SSL. How to setup JConsole to connect to my application?

    When you enable the application for remote management with SSL, you have set up a digital certificate on the system where the JMX agent (MBean server) is running and configured SSL properly.

    Assuming you created a keystore as described in the JSSE Guide and started your application (Server) as follows:

    % java -Djavax.net.ssl.keyStore=keystore \
      -Djavax.net.ssl.keyStorePassword=password Server

    To connect to this application, you need to run jconsole as follows:

    % jconsole -J-Djavax.net.ssl.trustStore=truststore \
      -J-Djavax.net.ssl.trustStorePassword=trustword
    The above configuration authenticates the server only. If client authentication is set up, you will need to provide a similar keystore for the JConsole's keys, and an appropriate truststore for the application.

  7. Can I use JConsole to monitor an application through a firewall?

    The com.sun.management.jmxremote.port management property specifies the port where the RMI Registry can be reached but the ports where the RMIServer and RMIConnection remote objects are exported is chosen by the RMI stack. To export the remote objects (RMIServer and RMIConnection) on a given port you need to create your own RMI connector server programmatically, as described in the section Mimicking Out-of-the-Box Management Using the JMX Remote API in the Java SE Monitoring and Management Guide. You must specify the JMXServiceURL as follows:

    JMXServiceURL url = new JMXServiceURL("service:jmx:rmi://localhost:" + port1 + "/jndi/rmi://localhost:" + port2 + "/jmxrmi");
    In the command above, port1 is the port number on which the RMIServer and RMIConnection remote objects are exported and port2 is the port number of the RMI Registry.

SNMP Based Management

  1. Where can I find the standard MIB for SNMP management of the Java virtual machine? What version of SNMP protocol does it require?

    The standard MIB for the Java virtual machine can be found at: http://java.sun.com/j2se/1.5.0/docs/guide/management/JVM-MANAGEMENT-MIB.mib. Some objects exposed in the JVM MIB are 64-bit quantities. To see these objects, you need to use the SNMP v2 protocol. If you can walk the JVM MIB using SNMP v1 protocol, the 64-bit objects are skipped.

  2. I'm not able to see all objects the JVM MIB tree. For example, the jvmMemoryHeapUsed OID is missing. Is it a known problem?

    The JVM MIB includes 64-bit objects which require to use the SNMP v2 protocol. All the 64-bit objects are skipped if you walk the JVM MIB using SNMP v1.


Java SE 6 Monitoring and Management Enhancements

 Documentation Contents

Monitoring and Management API Enhancements

The Java Platform, Standard Edition (Java SE) provides an API to allow you to monitor and manage the Java Virtual Machine (Java VM) and other applications, in the package java.lang.management.

The Java SE 6 platform includes the following enhancements to this API.

  • Support for java.util.concurrent locks has been added.

    The ThreadMXBean.getThreadInfo methods have been enhanced to report the java.util.concurrent.locks.AbstractOwnableSynchronizer that a thread is waiting to acquire. The Java 2 Platform, Standard Edition (J2SE) 5.0 only reported an object monitor that a thread was blocked from entering or waiting to acquire.

    In addition, the following new methods have been added in the ThreadMXBean interface:

    • isObjectMonitorUsageSupported()
    • isSynchronizerUsageSupported()
    • findDeadlockedThreads()
  • New classes and methods for obtaining the list of locks owned by a thread and to report which stack frame locked a monitor have been added to the java.lang.management package.
    • New LockInfo class.
    • New MonitorInfo class.
    • New ThreadInfo methods getLockInfo(), getLockedMonitors() and getLockedSynchronizers().
    • New ThreadMXBean methods dumpAllThreads() and getThreadInfo(long[] ids, boolean lockedMonitor, boolean lockedSynchronizers)
  • A new method, getSystemLoadAverage(), has been added to OperatingSystemMXBean to return the system load average.

JConsole Enhancements

The Java SE platform provides a graphical monitoring tool called JConsole. The JConsole tool implements the Java Management Extensions (JMX) API and enables you to monitor the performance of a Java VM and any instrumented applications. Introduced in J2SE 5.0, JConsole became an officially supported feature of Java SE 6.

Some of the enhancements that have been made to the JConsole tool between these two releases are as follows.

  • JConsole Plugin support, that allows you to build your own plug-ins to run with JConsole, for example, to add a custom tab for accessing your applications' MBeans.
  • Dynamic attach capability, allowing you to connect JConsole to any application that supports the dynamic Attach API, that was also added in Java SE 6.
  • Enhanced user interface that makes data more easily accessible.
  • New Overview and VM Summary tabs, for a better presentation of general information about your Java VM.
  • The HotSpot Diagnostic MBean, which provides an API to request heap dump at runtime and also change the setting of certain VM options.
  • Improved presentation of MBeans, to make it easier to access your MBeans' operations and attributes.

Out-of-the-Box Remote Management Enhancements

The Java Java VM has built-in instrumentation that enables you to monitor and manage it using the JMX technology. These built-in management utilities are often referred to as out-of-the-box management tools for the Java VM. The following enhancement has been made to the out-of-the-box management utilities in this release.

  • The remote method invocation (RMI) registry has been secured using the secure sockets layer (SSL). A new management property, com.sun.management.jmxremote.registry.ssl, has been added to enable the use of a SSL-enabled RMI registry so that only legimate clients with the appropriate SSL certificates can obtain the connector stub.
Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun


Java SE Monitoring and Management Guide

Home Page
Products
Downloads
Service & Solutions
Support
Training
Research
Java SE Monitoring and Management Guide

  • Copyright
  • + Preface
  • + 1. Overview of Java SE Monitoring and Management
  • + 2. Monitoring and Management Using JMX Technology
  • + 3. Using JConsole
  • + 4. Using the Platform MBean Server and Platform MXBeans
  • + 5. SNMP Monitoring and Management
  • - A. Additional Security Information For Microsoft Windows
    • How to Secure a Password File on Microsoft Windows Systems
      • Procedure To Secure a Password File on Windows XP Professional Edition
      • Procedure To Secure a Password File on Windows XP Home Edition
Company Info Contact Terms of Use Privacy Copyright 1994-2006 Sun Microsystems, Inc.


Java SE Monitoring and Management Guide

Home Page
Products
Downloads
Service & Solutions
Support
Training
Research
Java SE Monitoring and Management Guide

  • Copyright
  • + Preface
  • + 1. Overview of Java SE Monitoring and Management
  • - 2. Monitoring and Management Using JMX Technology
    • Setting System Properties
    • Enabling the Out-of-the-Box Management
      • Local Monitoring and Management
        • Remote Monitoring and Management
        • Using Password and Access Files
          • Password Files
          • Access Files
        • Out-of-the-Box Monitoring and Management Properties
          • Configuration Errors
        • Connecting to the JMX Agent Programmatically
          • Setting up Monitoring and Management Programmatically
        • Mimicking Out-of-the-Box Management Using the JMX Remote API
          • Example of Mimicking Out-of-the-Box Management
        • + 3. Using JConsole
        • + 4. Using the Platform MBean Server and Platform MXBeans
        • + 5. SNMP Monitoring and Management
        • + A. Additional Security Information For Microsoft Windows
        Company Info Contact Terms of Use Privacy Copyright 1994-2006 Sun Microsystems, Inc.


Java SE Monitoring and Management Guide

Home Page
Products
Downloads
Service & Solutions
Support
Training
Research
Java SE Monitoring and Management Guide

  • Copyright
  • + Preface
  • + 1. Overview of Java SE Monitoring and Management
  • + 2. Monitoring and Management Using JMX Technology
  • - 3. Using JConsole
    • Starting JConsole
      • Command Syntax
        • Connecting to a JMX Agent
        • Presenting the JConsole Tabs
          • Viewing Overview Information
            • Monitoring Memory Consumption
              • Monitoring Thread Use
                • Monitoring Class Loading
                • Viewing VM Information
                • Monitoring and Managing MBeans
                  • Creating Custom Tabs
              • + 4. Using the Platform MBean Server and Platform MXBeans
              • + 5. SNMP Monitoring and Management
              • + A. Additional Security Information For Microsoft Windows
              Company Info Contact Terms of Use Privacy Copyright 1994-2006 Sun Microsystems, Inc.


Java SE Monitoring and Management Guide

Home Page
Products
Downloads
Service & Solutions
Support
Training
Research
Java SE Monitoring and Management Guide

  • Copyright
  • + Preface
  • + 1. Overview of Java SE Monitoring and Management
  • + 2. Monitoring and Management Using JMX Technology
  • + 3. Using JConsole
  • + 4. Using the Platform MBean Server and Platform MXBeans
  • + 5. SNMP Monitoring and Management
  • + A. Additional Security Information For Microsoft Windows
Company Info Contact Terms of Use Privacy Copyright 1994-2006 Sun Microsystems, Inc.


Java SE Monitoring and Management Guide

Home Page
Products
Downloads
Service & Solutions
Support
Training
Research
Java SE Monitoring and Management Guide

  • Copyright
  • - Preface
  • + 1. Overview of Java SE Monitoring and Management
  • + 2. Monitoring and Management Using JMX Technology
  • + 3. Using JConsole
  • + 4. Using the Platform MBean Server and Platform MXBeans
  • + 5. SNMP Monitoring and Management
  • + A. Additional Security Information For Microsoft Windows
Company Info Contact Terms of Use Privacy Copyright 1994-2006 Sun Microsystems, Inc.


Java SE Monitoring and Management Guide

Home Page
Products
Downloads
Service & Solutions
Support
Training
Research
Java SE Monitoring and Management Guide

  • Copyright
  • + Preface
  • + 1. Overview of Java SE Monitoring and Management
  • + 2. Monitoring and Management Using JMX Technology
  • + 3. Using JConsole
  • - 4. Using the Platform MBean Server and Platform MXBeans
    • Using the Platform MBean Server
    • Accessing Platform MXBeans
      • Accessing Platform MXBeans via the ManagementFactory Class
      • Accessing Platform MXBeans via an MXBean Proxy
      • Accessing Platform MXBeans via the MBeanServerConnection Class
    • Using Sun Microsystems' Platform Extension
      • Accessing MXBean Attributes Directly
      • Accessing MXBean Attributes via MBeanServerConnection
    • Monitoring Thread Contention and CPU Time
    • Managing the Operating System
    • Logging Management
    • Detecting Low Memory
      • Memory Thresholds
        • Polling
        • Threshold Notifications
    • + 5. SNMP Monitoring and Management
    • + A. Additional Security Information For Microsoft Windows
    Company Info Contact Terms of Use Privacy Copyright 1994-2006 Sun Microsystems, Inc.


Java SE Monitoring and Management Guide

Home Page
Products
Downloads
Service & Solutions
Support
Training
Research

Contents

Part No: N/A

October 2006

Sun Microsystems, Inc.

4150 Network Circle
Santa Clara, CA 95054
U.S.A.

Copyright 2006, Sun Microsystems, Inc

Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more U.S. patents or pending patent applications in the U.S. and in other countries.

U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements.

This distribution may include materials developed by third parties.

Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd.

Sun, Sun Microsystems, the Sun logo, the Solaris logo, the Java Coffee Cup logo, docs.sun.com, Java, and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc.

The OPEN LOOK and Sun™ Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun's licensees who implement OPEN LOOK GUIs and otherwise comply with Sun's written license agreements.

Products covered by and information contained in this publication are controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical or biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited.

DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

Sun Microsystems, Inc. détient les droits de propriété intellectuelle relatifs à la technologie incorporée dans le produit qui est décrit dans ce document. En particulier, et ce sans limitation, ces droits de propriété intellectuelle peuvent inclure un ou plusieurs brevets américains ou des applications de brevet en attente aux Etats-Unis et dans d'autres pays.

Cette distribution peut comprendre des composants développés par des tierces personnes.

Certaines composants de ce produit peuvent être dérivées du logiciel Berkeley BSD, licenciés par l'Université de Californie. UNIX est une marque déposée aux Etats-Unis et dans d'autres pays; elle est licenciée exclusivement par X/Open Company, Ltd.

Sun, Sun Microsystems, le logo Sun, le logo Solaris, le logo Java Coffee Cup, docs.sun.com, Java et Solaris sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc. aux Etats-Unis et dans d'autres pays. Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC International, Inc. aux Etats-Unis et dans d'autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc.

L'interface d'utilisation graphique OPEN LOOK et Sun a été développée par Sun Microsystems, Inc. pour ses utilisateurs et licenciés. Sun reconnaît les efforts de pionniers de Xerox pour la recherche et le développement du concept des interfaces d'utilisation visuelle ou graphique pour l'industrie de l'informatique. Sun détient une licence non exclusive de Xerox sur l'interface d'utilisation graphique Xerox, cette licence couvrant également les licenciés de Sun qui mettent en place l'interface d'utilisation graphique OPEN LOOK et qui, en outre, se conforment aux licences écrites de Sun.

Les produits qui font l'objet de cette publication et les informations qu'il contient sont régis par la legislation américaine en matière de contrôle des exportations et peuvent être soumis au droit d'autres pays dans le domaine des exportations et importations. Les utilisations finales, ou utilisateurs finaux, pour des armes nucléaires, des missiles, des armes chimiques ou biologiques ou pour le nucléaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou réexportations vers des pays sous embargo des Etats-Unis, ou vers des entités figurant sur les listes d'exclusion d'exportation américaines, y compris, mais de manière non exclusive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une façon directe ou indirecte, aux exportations des produits ou des services qui sont régis par la legislation américaine en matière de contrôle des exportations et la liste de ressortissants spécifiquement designés, sont rigoureusement interdites.

LA DOCUMENTATION EST FOURNIE "EN L'ETAT" ET TOUTES AUTRES CONDITIONS, DECLARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES, DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE, Y COMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L'APTITUDE A UNE UTILISATION PARTICULIERE OU A L'ABSENCE DE CONTREFACON.

Contents
Company Info Contact Terms of Use Privacy Copyright 1994-2006 Sun Microsystems, Inc.


Java SE Monitoring and Management Guide

Home Page
Products
Downloads
Service & Solutions
Support
Training
Research
Java SE Monitoring and Management Guide

  • Copyright
  • + Preface
  • + 1. Overview of Java SE Monitoring and Management
  • + 2. Monitoring and Management Using JMX Technology
  • + 3. Using JConsole
  • + 4. Using the Platform MBean Server and Platform MXBeans
  • - 5. SNMP Monitoring and Management
    • Enabling the SNMP Agent
      • Access Control List File
      • Procedure To Enable the SNMP Agent in a Single-user Environment
      • Procedure To Enable the SNMP Agent in a Multiple-user Environment
    • SNMP Monitoring and Management Properties
      • Configuration Errors
  • + A. Additional Security Information For Microsoft Windows
Company Info Contact Terms of Use Privacy Copyright 1994-2006 Sun Microsystems, Inc.


Java SE Monitoring and Management Guide

Home Page
Products
Downloads
Service & Solutions
Support
Training
Research
Java SE Monitoring and Management Guide

  • Copyright
  • + Preface
  • - 1. Overview of Java SE Monitoring and Management
    • Key Monitoring and Management Features
      • Java VM Instrumentation
      • Monitoring and Management API
      • Monitoring and Management Tools
      • Java Management Extensions (JMX) Technology
      • Platform MXBeans
      • Platform MBean Server
    • + 2. Monitoring and Management Using JMX Technology
    • + 3. Using JConsole
    • + 4. Using the Platform MBean Server and Platform MXBeans
    • + 5. SNMP Monitoring and Management
    • + A. Additional Security Information For Microsoft Windows
    Company Info Contact Terms of Use Privacy Copyright 1994-2006 Sun Microsystems, Inc.


Monitoring and Management for the Java Platform

Java

Monitoring and Management
for the Java Platform

 Documentation Contents

The Java Platform Standard Edition (Java SE) 6 provides comprehensive monitoring and management support for the Java platform.

API Specifications

Java SE 6 includes the following APIs for monitoring and management:

  • java.lang.management - Enables monitoring and managing the Java virtual machine and the underlying operating system. The API enables applications to monitor themselves and enables JMX-compliant tools to monitor and manage a virtual machine locally and remotely.

  • com.sun.management - Sun Microsystems' platform extension to the java.lang.management API and the management interface for some other components of the platform.

  • java.util.logging.LoggingMXBean - Enables you to retrieve and set logging information.

  • The Java Management Extensions (JMX) APIs - Defines the architecture, design patterns, interfaces, and services for application and network management and monitoring in Java. For more information, see the JMX documentation.

  • The Attach API - Sun Microsystems' platform extension that allows a management agent to be dynamically loaded into a virtual machine.

  • The JConsole API - Sun Microsystems' platform extension that provides a programmatic interface to access JConsole such as adding a JConsole plugin. JTop is an example JConsole plugin available at the JDK_HOME/demo/management/JTop directory.

Tutorials and Programmer's Guides

  • Java SE Monitoring and Management Guide, containing the following chapters:
    • Overview of Java SE Monitoring and Management
    • Monitoring and Management Using the JMX API
    • Using JConsole
    • Using the Platform MBean Server and Platform MXBeans
    • SNMP Monitoring and Management
    • Appendix: Additional Security Information For Microsoft Windows

    The Java SE Monitoring and Management Guide is also available in printable PDF format.

  • JMX Technology Tutorial, providing an introduction to the JMX technology, via examples demonstrating key functions of the JMX API.
  • Frequently Asked Questions about JConsole and Remote Management of the Java platform.
  • Example code for monitoring and management is provided in the JDK_HOME/demo/management directory following installation of the Java SE platform.

Tools

  • Java Monitoring and Management Console (JConsole)
  • Monitoring Tools - Including jps, jstat, jstatd.

Enhancements

  • Enhancements in Java SE 6 - A list of monitoring and management enhancements introduced in the Java SE 6 platform.

More Information

  • Monitoring and Management Home Page
  • JMX Technology documentation
  • Java HotSpot Technology
Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback. 		Sun

Java Software


Preface

Home Page
Products
Downloads
Service & Solutions
Support
Training
Research

Contents Next Next

Java SE Monitoring and Management Guide

Preface

The Java Platform, Standard Edition (Java SE platform) 6 features utilities that allow you to monitor and manage the performance of a Java Virtual Machine (Java VM) and the Java applications that are running in it. The Java SE Monitoring and Management Guide describes those monitoring and management utilities.

Who Should Use This Book

The Java SE Monitoring and Management Guide is intended for experienced users of the Java language, such as systems administrators and software developers, for whom the performance of the Java platform and their applications is of vital importance.

Before You Read This Book

It is recommended that users are familiar with several other features of the Java SE platform. The following documentation might be of use.

  • Java Management Extensions (JMX) Technology

  • Java HotSpot Technology

  • Java Virtual Machine Technology

  • Performance Documentation for the Java HotSpot VM

How This Book Is Organized

This book covers the following topics.

  • Chapter 1, Overview of Java SE Monitoring and Management introduces the monitoring and management utilities provides with the Java SE platform.

  • Chapter 2, Monitoring and Management Using JMX Technology describes how to configure your platform to allow monitoring and management using the JMX API.

  • Chapter 3, Using JConsole introduces the JConsole graphical user interface.

  • Chapter 4, Using the Platform MBean Server and Platform MXBeans presents the MBeans that are provided with the Java SE platform for monitoring and management purposes.

  • Chapter 5, SNMP Monitoring and Management explains how to perform monitoring and management using the Simple Network Management Protocol (SNMP).

  • Appendix A, Additional Security Information For Microsoft Windows provides security configuration information specific to Windows platforms.

Related Third-Party Web Site References

Third-party URLs are referenced in this document and provide additional, related information.

Note - Sun is not responsible for the availability of third-party web sites mentioned in this document. Sun does not endorse and is not responsible or liable for any content, advertising, products, or other materials that are available on or through such sites or resources. Sun will not be responsible or liable for any actual or alleged damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through such sites or resources.

Documentation, Support, and Training

The Sun web site provides information about the following additional resources:

  • Documentation

  • Support

  • Training

Typographic Conventions

The following table describes the typographic conventions that are used in this book.

Table P-1 Typographic Conventions

Typeface | Meaning | Example
AaBbCc123 | The names of commands, files, and directories, and onscreen computer output | Edit your .login file. Use ls -a to list all files. machine_name% you have mail.
AaBbCc123 | What you type, contrasted with onscreen computer output | machine_name% su Password:
aabbcc123 | Placeholder: replace with a real name or value | The command to remove a file is rm filename.
AaBbCc123 | Book titles, new terms, and terms to be emphasized | Read Chapter 6 in the User's Guide. A cache is a copy that is stored locally. Do not save the file. Note: Some emphasized items appear bold online.

Shell Prompts in Command Examples

The following table shows the default UNIX® system prompt and superuser prompt for the C shell, Bourne shell, and Korn shell.

Table P-2 Shell Prompts

Shell | Prompt
C shell | machine_name%
C shell for superuser | machine_name#
Bourne shell and Korn shell | $
Bourne shell and Korn shell for superuser | #
Contents Next Next
Company Info Contact Terms of Use Privacy Copyright 1994-2006 Sun Microsystems, Inc.


Enhancements to java.math

 Math Contents

JDK 5.0

  • The BigDecimal class has added support for fixed-precision floating-point computation. Refer to JSR 13.

  • The Math and StrictMath libraries include hyperbolic transcendental functions (sinh, cosh, tanh), cube root, base 10 logarithm, etc.

  • Hexadecimal floating-point support - To allow precise and predictable specification of particular floating-point values, hexadecimal notation can be used for floating-point literals and for string to floating-point conversion methods in Float and Double.

Java 2 SDK 1.4

  • Performance enhancements for prime generation in BigInteger
    New static method probablePrime has been added to class BigInteger for generating prime numbers. Previously, the sole means of generating a prime BigInteger required the caller to provide a 'certainty' (the log of the probability of compositeness that the caller was willing to tolerate). However, providing an unreasonable value for the certainty could lead to poor performance (if the certainty was too high) or serious bugs (if it was too low). The new prime-generation method provides an efficient algorithm for generating primes using an automatically determined, appropriate value for the certainty based on a draft ANSI specification (X9-80).

Java 2 SDK 1.3

  • Performance enhancements in BigInteger
    Class java.math.BigInteger has been reimplemented in pure Java programming-language code. Previously, BigInteger's implementation was based on an underlying C library. On a high-quality VM, the new implementation performs all operations faster than the old implementation. The speed-up can be as much as 5x or more, depending on the operation being performed and the length of the operands.

  • More robust BigDecimal(String) constructor
    The BigDecimal(String) constructor has been enhanced to allow signed strings (for example, "+2.71828") and exponential notation (for example, "1.23E-23") as input.

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


Math Functionality

 Documentation Contents
Math functionality includes floating point libraries (java.lang.Math and java.lang.StrictMath) and arbitrary-precision math (java.math package).

API Specification

Floating Point Libraries

  • java.lang.Math
  • java.lang.StrictMath

Arbitrary-Precision Math

  • java.math Package

Enhancements

  • Enhancements to java.math

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.
Feedback

Sun Microsystems, Inc
Java Software


Cookie Management

Introduction

The HTTP state management mechanism specifies a way to create a stateful session with HTTP requests and responses. The specification for it can be found in RFC 2965: HTTP State Management Mechanism at http://www.ietf.org/rfc/rfc2965.txt?number=2965.

Pre-Tiger support

Prior to Tiger, it was possible to add Cookie management to applications. But the supporting API was somewhat rudimentary. There was no single point of hook up with cookie management. Each application had to handle cookies for each HTTP request/response separately by using the following two methods from java.net.URLConnection class:

setRequestProperty()
getHeaderFields()

The first method should be called before sending out a HTTP request in order to set the appropriate cookies for the current URL in the HTTP headers. The second method should be used to retrieve the cookies from the response headers sent by the HTTP server.

Although doable, adding Cookie support in this way results in fragmented code, which is error prone and incurs high maintenance.

What's new in Tiger?

We have introduced a new callback mechanism via an abstract class to hook up a HTTP state management policy implementation into the HTTP protocol handler. Applications and web containers can introduce Cookie management by providing a concrete subclass of the new API.

The new abstract class is called java.net.CookieHandler. It provides a mechanism to register and retrieve the current CookieHandler for the JVM, as well as methods to retrieve and record relevant cookies for a specific URI.

There are two static methods in CookieHandler getDefault() and setDefault() for retrieving and registering the default CookieHandler in the VM. As well as two instance methods get() and put() for returning a list of cookies based on a URL and stores a list of cookies from the response headers, respectively.

Cookies are represented as Map<String,List<String>>, a Map from the header field name for cookies to a list of cookies represented by Strings. There are two state management headers defined so far, "Set-Cookie2" and "Cookie". The former is used for returning cookies in response headers; while the latter is for setting cookies in HTTP request headers.

Here is an example from RFC2965:

1. User Agent -> Server

POST /acme/login HTTP/1.1
[form data]

2. Server -> User Agent

HTTP/1.1 200 OK
Set-Cookie2: Customer="WILE_E_COYOTE"; Version="1"; Path="/acme"

3. User Agent -> Server

POST /acme/pickitem HTTP/1.1
Cookie: $Version="1"; Customer="WILE_E_COYOTE"; $Path="/acme"
[form data]

A simple Example

Here's a simple example of a CookieHandler implementation. Basically there are two methods to implement, given a request URI and request headers (except the cookie headers), retrieve all the relevant cookies from your cookie cache; and record the applicable cookies to your cookie cache given the request URI and the response headers.

class MyCookieHandler extends CookieHandler {
    public Map<String, List<String>>
        get(URI uri, Map<String, List<String>> requestHeaders)
        throws IOException {
        // the cookies will be included in request
        Map<String, List<String>> map = new HashMap<String, List<String>>();
        List<String> l = retrieveCookies(uri, rqstHdrs);
        map.put("Cookie",l);
        return Collections.unmodifiableMap(map);
    }

    public void
        put(URI uri, Map responseHeaders)
        throws IOException {
        // check response has cookies[1]
        List l = (List)responseHeaders.get("Set-Cookie2");
        if (l != null) {
            // save the cookies in a cookie cache
         storeCookies(uri, l);
        }
    }
}

The methods retrieveCookies() and storeCookies() are "magic" functions for interacting with a backend cookie management facility, which is omitted in this example.

Once it is registered with the VM, it will take effect when you issue HTTP transactions.

public static void main(String args[]) throws Exception {
    ......
    CookieHandler.setDefault(new MyCookieHandler());
    HttpURLConnection http = (HttpURLConnection)url.openConnection();

    int respCode = http.getResponseCode();
    http.disconnect();
    ......
}

There is no default implementation of a cookie manager in J2SE. However, this may change in the future. Java Plugin and Java WebStart provides a default CookieHandler in their environment.


Extending Sockets in JDK 1.1

Duke icon Extending Sockets in JDK 1.1

Some of the improvements to the java.net classes in JDK 1.1 allow sockets (Socket/ServerSocket) to be non-final, extendable classes. The basic goal is to allow extended sockets to be used whereever a base class Socket is used without rewriting application code. So for example an already-existing email client could be handed a subclass of Socket that does peer authentication or encryption, which the Socket subclass would handle transparently. Other examples include sockets that transparently use compression, or which add functionality such as mirroring traffic to multiple servers (e.g. using reliable ordered multicast).

This document has the following sections:

  • JDK 1.0: SocketImpl
  • JDK 1.1: Non-Final Socket and ServerSocket Classes
  • Socket: How to extend Socket
  • ServerSocket: How to extend ServerSocket

JDK 1.0: SocketImpl and SocketImplFactory

JDK 1.0 allows licensees to extend socket functionality in one very particular way: they can subclass java.net.SocketImpl , and provide an enhanced java.net.SocketImplFactory() which returns such classes as needed.

The SocketImpl/SocketImplFactory scheme is useful for, and was designed for, java apps/applications to be portable across environments that use different transport mechanisms. A client application that uses a java.net.Socket can work in the general case (where the runtime uses a PlainSocketImpl), as well as in environments where network connections must do something particular. For example, a java program should be able to work behind a firewall where connections to the Internet must be done through a proxy protocol, like SOCKS, assuming the right kind of SocketImpl is set for the java runtime in that environment.

Though the SocketImpl is useful for things like transparently providing proxy support to java apps, its utility is limited as a way to provide added functionality of network transport, or for layering other protocols on top of TCP. Additionally, it's only possible to have a single type of SocketImpl installed for a java runtime, which limits large-scale applications. It's cleaner and more intuitive to make ServerSocket and Socket extendable.

Note that the SocketImpl mechanism is designed to be orthogonal to the functionality provided by a subclass of Socket: for example, a subclass of Socket that is capable of doing compression on its streams would still want to use the system-default SocketImpl to get proxy support behind certain kinds of firewalls. The system-default SocketImpl can be thought of as an extension of the transport layer that applications needn't be aware of, and subclasses of Socket/ServerSocket provide richer functionality at the application layer.

Change in JDK 1.1

In JDK 1.1, Socket and ServerSocket are made non-final, which is a pretty simple change. The one basic caveat is that subclasses do not have direct access to the underlying SocketImpl in the base classes, primarily for security reasons. But other than that, subclasses of Socket/ServerSocket inherit and can override methods from their superclass.

The JDK changed by:

  • Removing the final modifier from the Socket and ServerSocket classes.
  • Reattaching that final modifier only to methods where it is needed to avoid bypassing security manager calls.
  • Defining a new method in ServerSocket with signature: protected final void implAccept(Socket client) to use when initializing a newly accepted socket.
  • Exposing a default Socket constructor so that Socket subclasses could initialize their superclass without doing an actual connection in the superclass. This is also required so that a ServerSocket subclasses can return the correct Socket subclass from accept() (e.g., FooServerSocket.accept() returns a FooSocket)

Changes to Socket

The public constructors to Socket of the general form:

    Socket(String host, int port) {
      ...
    }
can be used by subclasses to initialize the superclass, but they will also create a system-default SocketImpl and connect it to the specified host, port. Socket also has two protected constructors to intialize the superclass without connecting the Socket:
    protected Socket() {
      /* install system-default SocketImpl */
      ...
    }

    protected Socket(SocketImpl impl) {
      this.impl = impl;
    }
The first constructor installs a system-default SocketImpl (either from the factory or a PlainSocketImpl). The second allows for a subclass of Socket to install its own impl if need be. If the Socket subclass doesn't need the default SocketImpl, it's perfectly valid to use the second constructor and pass it null. (But in this case the subclass should of course override all the base class methods, since they all rely on the underlying SocketImpl).

Changes to ServerSocket

Subclasses of ServerSocket also have a protected constructor exposed to them that creates a default SocketImpl in the base class, but doesn't otherwise initialize it (e.g., doesn't call impl.create(), impl.bind() or impl.listen()). The public constructors of ServerSocket will initialize the underlying SocketImpl.

    protected ServerSocket() {
      /* install system-default SocketImpl */
      ...
    }
The only other thing about extending ServerSocket that should be explained is how to override accept() when the underlying SocketImpl for Socket/ServerSocket isn't accesible to subclasses. Since the base class can do this, ServerSocket has a method to make the necessary calls on the underlying SocketImpl's on behalf of subclasses:
public class ServerSocket {
    ...
    protected final void implAccept(Socket s) throws IOException {
       ...
       // on return from this call s will be connected to a client
    }
    ...
Note that subclasses of Socket/ServerSocket that don't use a SocketImpl needn't use this method. As an example of how this works, here's what some SSL code might look like.

class SSLServerSocket extends ServerSocket {
    ...
    public Socket accept () throws IOException
    {
    SSLSocket s = new SSLSocket (certChain, privateKey);
    // create an unconnected client SSLSocket, that we'll
    // return from accept

    implAccept (s);
    s.handshake ();
    return s;
    }
    ...
}

class SSLSocket extends java.net.Socket {
    ...
    public SSLSocket(CertChain c, PrivateKey k) {
    super();
    ...
    }
    ...
}

Last Modified: 21 August, 1996
David Brownell
David Brown


Http Authentication

 Documentation Contents

Overview

The HTTP protocol handler implements a number of authentication schemes. Sun's implementation of Java SE Version 6 supports the following:
  • HTTP Basic authentication (RFC2617)
  • HTTP Digest authentication (RFC2617)
  • NTLM (defined by Microsoft)
  • Http SPNEGO Negotiate (defined by Microsoft), with the following underlying mechanisms:
    • Kerberos
    • NTLM
Each of these schemes is described in more detail below, but they are typically used by application code in much the same way. The java.net.Authenticator class is used to enable authentication and to provide access to a store of usernames and passwords which are then used in the respective authentication schemes.

Generally, all authentication schemes work with both proxies and servers. Some (basic and digest) can be used simultaneously with proxies and servers. See below for how to distinguish between proxy and server authentication.

How to use the Authenticator class

Authenticator is an abstract class which is extended by applications and once installed, is invoked to obtain usernames and passwords for authentication interactions.

Extending java.net.Authenticator

Application code must override the getPasswordAuthentication() method. Note, the method is not abstract, and the default implementation does nothing. The following is a minimal example:

    class MyAuthenticator extends Authenticator {

        public PasswordAuthentication getPasswordAuthentication () {
            return new PasswordAuthentication ("user", "pass1".toCharArray());
        }
    }

This simple example returns the username "user" and the password "pass1" for every HTTP authentication interaction. A more realistic example would use the other methods of java.net.Authenticator to get more information about the HTTP request that needs to be authenticated. Any of the following methods may be called by the implementation of getPasswordAuthentication() in order to decide how to handle each request for credentials.

  • getRequestingHost()
  • getRequestingPort()
  • getRequestingPrompt()
  • getRequestingProtocol()
  • getRequestingScheme()
  • getRequestingURL()
  • getRequestingSite()
  • getRequestorType(). Returns whether requestor is a proxy or server.

Enabling authentication

Having defined a suitable authenticator implementation class, authentication is enabled by calling

    Authenticator.setDefault (authinstance);

where authinstance is an instance of the declared implementation class. If this is not called, then authentication is disabled, and server authentication errors will be returned to user code via IOException objects. Once installed, the http implementation will try to authenticate automatically where possible (via cached credentials, or credentials that can be acquired from the system). If the correct credentials are not available then the user's authenticator is invoked to provide them.

Controlling which authentication scheme is used

When a server needs a client to authenticate, it may propose a number of schemes to the client (for example digest and ntlm) and the client may choose from among them. Normally, applications do not care which scheme is used to and the implementation automatically chooses the strongest (most secure) protocol transparently.

If the user needs to ensure that a particular scheme is used, then the following system property can be set to modify the default behavior.

    -Dhttp.auth.preference="scheme"

-D is specified if the property is being set on the command line. "http.auth.preference" is the property name, and scheme is the name of the scheme to use. If the server does not include this scheme in its list of proposed schemes, then the default choice is made.

Details of each authentication scheme

Http Basic

Basic authentication is a simple and not very secure authentication scheme which is defined in RFC 2317. The username and password are encoded in base 64 and are therefore easily obtainable by anyone who has access to the packet data. The security of basic authentication can be improved when used with HTTPS, thus encrypting the request and response.

The getRequestingPrompt() method returns the Basic authentication realm as provided by the server.

Http digest

Digest is a relatively secure scheme based on cryptographic hashes of the username and password, using the MD5 hash algorithm. Digest also provides the ability for the server to prove to the client that it also knows the shared secret (password). This behavior is normally disabled, because not all servers support it. This can be switched on with the following system properties:

    -Dhttp.auth.digest.validateServer="true"
    -Dhttp.auth.digest.validateProxy="true"

The getRequestingPrompt() method returns the Digest authentication realm as provided by the server.

NTLM

NTLM is a scheme defined by Microsoft. It is more secure scheme than Basic, but less secure than Digest. NTLM can be used with proxies or servers, but not with both at the same time. If a proxy is being used, then it cannot be used for server authentication. This is because the protocol actually authenticates the TCP connection rather than the individual HTTP interactions.

On Microsoft Windows platforms, NTLM authentication attempts to acquire the user credentials from the system without prompting the user's authenticator object. If these credentials are not accepted by the server then the user's authenticator will be called.

Because the Authenticator class was defined prior to NTLM being supported, it was not possible to add support in the API for the NTLM domain field. There are three options for specifying the domain:

  1. Do not specify it. In some environments, the domain is not actually required and the application need not specify it.
  2. 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, so long as users are made aware that this notation must be used.
  3. If a domain name is not specified as in method 2) and the system property "http.auth.ntlm.domain" is defined, then the value of this property will be used as the domain name.

Http Negotiate (SPNEGO)

Negotiate is a scheme which potentially allows any GSS authentication mechanism to be used as a HTTP authentication protocol. Currently, the scheme only supports Kerberos and NTLM. NTLM has already been described above, so this section only describes how to set up Kerberos for Http authentication.

Kerberos 5 Configuration

Since the SPNEGO mechanism will call JGSS, which in turns calls the Kerberos V5 login module to do real works. Kerberos 5 configurations are needed. which includes:

  • Some way to provide Kerberos configurations. This can be achieved with the Java system property java.security.krb5.conf. For example:
            java -Djava.security.krb5.conf=krb5.conf \
                 -Djavax.security.auth.useSubjectCredsOnly=false \
                 ClassName

  • A JAAS config file denoting what login module to use. HTTP SPNEGO codes will look for the standard entry named com.sun.security.jgss.krb5.initiate.

For example, you can provide a file spnegoLogin.conf:

          com.sun.security.jgss.krb5.initiate {
              com.sun.security.auth.module.Krb5LoginModule
                  required useTicketCache=true;
          };
and run java with:
            java -Djava.security.krb5.conf=krb5.conf \
                 -Djava.security.auth.login.config=spnegoLogin.conf \
                 -Djavax.security.auth.useSubjectCredsOnly=false \
                 ClassName

Username and Password Retrieval

Just like any other HTTP authentication scheme, the client can provide a customized java.net.Authenticator to feed username and password to the HTTP SPNEGO module if they are needed (i.e. there is no credential cache available). The only authentication information needed to be checked in your Authenticator is the scheme which can be retrieved with getRequestingScheme(). The value should be "Negotiate".

This means your Authenticator implementation will look like:

    class MyAuthenticator extends Authenticator {

        public PasswordAuthentication getPasswordAuthentication () {
            if (getRequestingScheme().equalsIgnoreCase("negotiate")) {
                String krb5user;
                char[] krb5pass;
                // get krb5user and krb5pass in your own way
                ....
                return (new PasswordAuthentication (krb5user,
                            krb5pass));
            } else {
                ....
            }
        }
    }

Attention : According to the specification of java.net.Authenticator, it's designed to get the username and password at the same time, so do not specify principal=xxx in the JAAS config file.

Scheme Preference

The client can still provide system property http.auth.preference to denote that a certain scheme should always be used as long as the server request for it. You can use "SPNEGO" or "Kerberos" for this system property. "SPNEGO" means you prefer to response the Negotiate scheme using the GSS/SPNEGO mechanism; "Kerberos" means you prefer to response the Negotiate scheme using the GSS/Kerberos mechanism. Normally, when authenticating against a Microsoft product, you can use "SPNEGO". The value "Kerberos" also works for Microsoft servers. It's only needed when you encounter a server which knows Negotiate but doesn't know about SPNEGO.

If http.auth.preference is not set, the internal order choosen is:

  • GSS/SPNEGO -> Digest -> NTLM -> Basic

Noticed that Kerberos does not appear in this list, since whenever Negotiate is supported, GSS/SPNEGO is always chosen.

Fallback

If the server has provided more than one authentication schemes (including Negotiate), according to the processing order mentioned in the last section, Java will try to challenge the Negotiate scheme. However, if the protocol cannot be established successfully (e.g. The kerberos configuration is not correct, or the server's hostname is not recorded in the KDC principal DB, or the username and password provided by Authenticator is wrong), then the 2nd strongest scheme will be automatically used.

Attention : If http.auth.preference is set to SPNEGO or Kerberos, then we assume you only want to try the Negotiate scheme even if it fails. we won't fallback to any other scheme and your program will result in throwing an IOException saying it receives a 401 or 407 error from the HTTP response.

Example

Suppose you have an IIS Server running on a Windows Server within an Active Directory. A web page on this server is configured to be protected by Integrated Windows Authentication. This means the server will prompt for both Negotiate and NTLM authentication.

You need to prepare these files to get the protected file:

Code listing for RunHttpSpnego.java

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.Authenticator;
import java.net.PasswordAuthentication;
import java.net.URL;

public class RunHttpSpnego {

    static final String kuser = "username"; // your account name
    static final String kpass = "password"; // your password for the account

    static class MyAuthenticator extends Authenticator {
        public PasswordAuthentication getPasswordAuthentication() {
            // I haven't checked getRequestingScheme() here, since for NTLM
            // and Negotiate, the usrname and password are all the same.
            System.err.println("Feeding username and password for " + getRequestingScheme());
            return (new PasswordAuthentication(kuser, kpass.toCharArray()));
        }
    }

    public static void main(String[] args) throws Exception {
        Authenticator.setDefault(new MyAuthenticator());
        URL url = new URL(args[0]);
        InputStream ins = url.openConnection().getInputStream();
        BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
        String str;
        while((str = reader.readLine()) != null)
            System.out.println(str);
    }
}

Code listing for krb5.conf

[libdefaults]
    default_realm = AD.LOCAL
[realms]
    AD.LOCAL = {
        kdc = kdc.ad.local
    }

Code listing for login.conf

com.sun.security.jgss.krb5.initiate {
  com.sun.security.auth.module.Krb5LoginModule required doNotPrompt=false useTicketCache=true;
};

Then, compile RunHttpSpnego.java and run:

java -Djava.security.krb5.conf=krb5.conf \
    -Djava.security.auth.login.config=login.conf \
    -Djavax.security.auth.useSubjectCredsOnly=false \
    RunHttpSpnego \
    http://www.ad.local/hello/hello.html

You will see:

Feeding username and password for Negotiate
<h1>Hello, You got me!</h1>

In fact, if you are running on a Windows machine as a domain user, or, you are running on a Linux or Solaris machine that has already issued the kinit command and got the credential cache. The class MyAuthenticator will be completely ignored, and the output will be simply

<h1>Hello, You got me!</h1>

which shows the username and password are not consulted. This is the so-called Single Sign-On.

Also, You can just run

java RunHttpSpnego \
    http://www.ad.local/hello/hello.html

to see how the fallback is done, in which case you will see

Feeding username and password for ntlm
<h1>Hello, You got me!</h1>

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.
Feedback

Sun Microsystems, Inc
Java Software


HTTP Persistent Connections

Persistent Connections

What is HTTP Persistent Connections?

HTTP persistent connections, also called HTTP keep-alive, or HTTP connection reuse, is the idea of using the same TCP connection to send and receive multiple HTTP requests/responses, as opposed to opening a new one for every single request/response pair. Using persistent connections is very important for improving HTTP performance.

There are several advantages of using persistent connections, including:

  • Network friendly. Less network traffic due to fewer setting up and tearing down of TCP connections.
  • Reduced latency on subsequent request. Due to avoidance of initial TCP handshake
  • Long lasting connections allowing TCP sufficient time to determine the congestion state of the network, thus to react appropriately.

The advantages are even more obvious with HTTPS or HTTP over SSL/TLS. There, persistent connections may reduce the number of costly SSL/TLS handshake to establish security associations, in addition to the initial TCP connection set up.

In HTTP/1.1, persistent connections are the default behavior of any connection. That is, unless otherwise indicated, the client SHOULD assume that the server will maintain a persistent connection, even after error responses from the server. However, the protocol provides means for a client and a server to signal the closing of a TCP connection.

What makes a connection reusable?

Since TCP by its nature is a stream based protocol, in order to reuse an existing connection, the HTTP protocol has to have a way to indicate the end of the previous response and the beginning of the next one. Thus, it is required that all messages on the connection MUST have a self-defined message length (i.e., one not defined by closure of the connection). Self demarcation is achieved by either setting the Content-Length header, or in the case of chunked transfer encoded entity body, each chunk starts with a size, and the response body ends with a special last chunk.

What happens if there are proxy servers in between?

Since persistent connections applies to only one transport link, it is important that proxy servers correctly signal persistent/or-non-persistent connections separately with its clients and the origin servers (or to other proxy servers). From a HTTP client or server's perspective, as far as persistence connection is concerned, the presence or absence of proxy servers is transparent.

What does the current JDK do for Keep-Alive?

The JDK supports both HTTP/1.1 and HTTP/1.0 persistent connections.

When the application finishes reading the response body or when the application calls close() on the InputStream returned by URLConnection.getInputStream(), the JDK's HTTP protocol handler will try to clean up the connection and if successful, put the connection into a connection cache for reuse by future HTTP requests.

The support for HTTP keep-Alive is done transparently. However, it can be controlled by system properties http.keepAlive, and http.maxConnections, as well as by HTTP/1.1 specified request and response headers.

The system properties that control the behavior of Keep-Alive are:

http.keepAlive=<boolean>
default: true

Indicates if keep alive (persistent) connections should be supported.

http.maxConnections=<int>
default: 5

Indicates the maximum number of connections per destination to be kept alive at any given time

HTTP header that influences connection persistence is:

Connection: close

If the "Connection" header is specified with the value "close" in either the request or the response header fields, it indicates that the connection should not be considered 'persistent' after the current request/response is complete.

The current implementation doesn't buffer the response body. Which means that the application has to finish reading the response body or call close() to abandon the rest of the response body, in order for that connection to be reused. Furthermore, current implementation will not try block-reading when cleaning up the connection, meaning if the whole response body is not available, the connection will not be reused.

What's new in Tiger?

When the application encounters a HTTP 400 or 500 response, it may ignore the IOException and then may issue another HTTP request. In this case, the underlying TCP connection won't be Kept-Alive because the response body is still there to be consumed, so the socket connection is not cleared, therefore not available for reuse. What the application needs to do is call HttpURLConnection.getErrorStream() after catching the IOException , read the response body, then close the stream. However, some existing applications are not doing this. As a result, they do not benefit from persistent connections. To address this problem, we have introduced a workaround.

The workaround involves buffering the response body if the response is >=400, up to a certain amount and within a time limit, thus freeing up the underlying socket connection for reuse. The rationale behind this is that when the server responds with a >=400 error (client error or server error. One example is "404: File Not Found" error), the server usually sends a small response body to explain whom to contact and what to do to recover.

Several new Sun implementation specific properties are introduced to help clean up the connections after error response from the server.

The major one is:

sun.net.http.errorstream.enableBuffering=<boolean>
default: false

With the above system property set to true (default is false), when the response code is >=400, the HTTP handler will try to buffer the response body. Thus freeing up the underlying socket connection for reuse. Thus, even if the application doesn't call getErrorStream(), read the response body, and then call close(), the underlying socket connection may still be kept-alive and reused.

The following two system properties provide further control to the error stream buffering behavior:

sun.net.http.errorstream.timeout=<int> in millisecond
default: 300 millisecond

sun.net.http.errorstream.bufferSize=<int> in bytes
default: 4096 bytes

What can you do to help with Keep-Alive?

Do not abandon a connection by ignoring the response body. Doing so may results in idle TCP connections. That needs to be garbage collected when they are no longer referenced.

If getInputStream() successfully returns, read the entire response body.

When calling getInputStream() from HttpURLConnection, if an IOException occurs, catch the exception and call getErrorStream() to get the response body (if there is any).

Reading the response body cleans up the connection even if you are not interested in the response content itself. But if the response body is long and you are not interested in the rest of it after seeing the beginning, you can close the InputStream. But you need to be aware that more data could be on its way. Thus the connection may not be cleared for reuse.

Here's a code example that complies to the above recommendation:

try {
    URL a = new URL(args[0]);
    URLConnection urlc = a.openConnection();
    is = conn.getInputStream();
    int ret = 0;
    while ((ret = is.read(buf)) > 0) {
      processBuf(buf);
    }
    // close the inputstream
    is.close();
} catch (IOException e) {
    try {
        respCode = ((HttpURLConnection)conn).getResponseCode();
        es = ((HttpURLConnection)conn).getErrorStream();
        int ret = 0;
        // read the response body
        while ((ret = es.read(buf)) > 0) {
            processBuf(buf);
        }
        // close the errorstream
        es.close();
    } catch(IOException ex) {
        // deal with the exception
    }
}

If you know ahead of time that you won't be interested in the response body, you should issue a HEAD request instead of a GET request. For example when you are only interested in the meta info of the web resource or when testing for its validity, accessibility and recent modification. Here's a code snippet:

URL a = new URL(args[0]);
URLConnection urlc = a.openConnection();
HttpURLConnection httpc = (HttpURLConnection)urlc;
// only interested in the length of the resource
httpc.setRequestMethod("HEAD");
int len = httpc.getContentLength();

Changes in Java SE 6

Prior to Java SE 6, if an application closes a HTTP InputStream when more than a small amount of data remains to be read, then the connection had to be closed, rather than being cached. Now in Java SE 6, the behavior is to read up to 512 Kbytes off the connection in a background thread, thus allowing the connection to be reused. The exact amount of data which may be read is configurable through the http.KeepAlive.remainingData system property.


Java Networking and Proxies

1) Introduction

In today's networking environments, particularly corporate ones, application developers have to deal with proxies almost as often as system administrators. In some cases the application should use the system default settings, in other cases it will we want to have a very tight control over what goes through which proxy, and, somewhere in the middle, most applications will be happy to delegate the decision to their users by providing them with a GUI to set the proxy settings, as is the case in most browsers.

In any case, a development platform, like Java, should provide mechanisms to deal with these proxies that are both powerful and flexible. Unfortunately, until recently, the Java platform wasn't very flexible in that department. But all that changed in J2SE 5.0 as new API have been introduced to address this shortcoming, and the purpose of this paper is to provide an in-depth explanation of all these APIs and mechanisms, the old ones, which are still valid, as well as the new ones.

2) System Properties

Up until J2SE 1.4 system properties were the only way to set proxy servers within the Java networking API for any of the protocol handlers. To make matters more complicated, the names of these properties have changed from one release to another and some of them are now obsolete even if they are still supported for compatibility's sake.

The major limitation of using system properties is that they are an “all or nothing” switch. Meaning that once a proxy has been set for a particular protocol, it will affect all connections for that protocol. It's a VM wide behavior.

There are 2 main ways to set system properties:

  • As a command line option when invoking the VM
  • Using the System.setProperty(String, String) method, assuming, of course that you have permission to do so.

Now, let's take a look, protocol by protocol, at the properties you can use to set proxies. All proxies are defined by a host name and a port number. The later is optional as, if it is not specified, a standard default port will be used.

2.1) HTTP

There are 3 properties you can set to specify the proxy that will be used by the http protocol handler:

  • http.proxyHost: the host name of the proxy server
  • http.proxyPort: the port number, the default value being 80.
  • http.nonProxyHosts: a list of hosts that should be reached directly, bypassing the proxy. This is a list of regular expressions separated by '|'. Any host matching one of these regular expressions will be reached through a direct connection instead of through a proxy.

Let's look at a few examples assuming we're trying to execute the main method of the GetURL class:

$ java -Dhttp.proxyHost=webcache.mydomain.com GetURL

All http connections will go through the proxy server at webcache.mydomain.com listening on port 80 (we didn't specify any port, so the default one is used).

$ java -Dhttp.proxyHost=webcache.mydomain.com -Dhttp.proxyPort=8080
-Dhttp.noProxyHosts=”localhost|host.mydomain.com” GetURL

In that second example, the proxy server will still be at webcache.mydomain.com, but this time listening on port 8080. Also, the proxy won't be used when connecting to either localhost or host.mydonain.com.

As mentioned earlier, these settings affect all http connections during the entire lifetime of the VM invoked with these options. However it is possible, using the System.setProperty() method, to have a slightly more dynamic behavior.

Here is a code excerpt showing how this can be done:

//Set the http proxy to webcache.mydomain.com:8080

System.setProperty("http.proxyHost", "webcache.mydomain.com");
System.setPropery("http.proxyPort", "8080");

// Next connection will be through proxy.
URL url = new URL("http://java.sun.com/");
InputStream in = url.openStream();

// Now, let's 'unset' the proxy.
System.setProperty("http.proxyHost", null);

// From now on http connections will be done directly.

Now,this works reasonably well, even if a bit cumbersome, but it can get tricky if your application is multi-threaded. Remember, system properties are “VM wide” settings, so all threads are affected. Which means that the code in one thread could, as a side effect, render the code in an other thread inoperative.

2.2) HTTPS

The https (http over SSL) protocol handler has its own set of properties:

  • htttps.proxyHost
  • https.proxyPort

As you probably guessed these work in the exact same manner as their http counterparts, so we won't go into much detail except to mention that the default port number, this time, is 443 and that for the "non proxy hosts" list, the HTTPS protocol handler will use the same as the http handler (i.e. http.nonProxyHosts).

2.3) FTP

Settings for the FTP protocol handler follow the same rules as for http, the only difference is that each property name is now prefixed with 'ftp.' instead of 'http.'

Therefore the system properties are:

  • ftp.proxHost
  • ftp.proxyPort
  • ftp.nonProxyHosts

Note that, this time, there is a separate property for the "non proxy hosts" list. Also, as for http, the default port number value is 80. It should be noted that when going through a proxy, the FTP protocol handler will actually use HTTP to issue commands to the proxy server, which explains why this is the same default port number.

Let's examine a quick example:

$ java -Dhttp.proxyHost=webcache.mydomain.com
-Dhttp.proxyPort=8080 -Dftp.proxyHost=webcache.mydomain.com -Dftp.proxyPort=8080 GetURL

Here, both the HTTP and the FTP protocol handlers will use the same proxy server at webcache.mydomain.com:8080.

2.4) SOCKS

The SOCKS protocol, as defined in RFC 1928, provides a framework for client server applications to safely traverse a firewall both at the TCP and UDP level. In that sense it is a lot more generic than higher level proxies (like HTTP or FTP specific proxies). J2SE 5.0 provides SOCKS support for client TCP sockets.

There are 2 system properties related to SOCKS:

  • socksProxyHost for the host name of the SOCKS proxy server
  • socksProxyPort for the port number, the default value being 1080

Note that there is no dot ('.') after the prefix this time. This is for historical reasons and to ensure backward compatibility. Once a SOCKS proxy is specified in this manner, all TCP connections will be attempted through the proxy.

Example:

$ java -DsocksProxyHost=socks.mydomain.com GetURL

Here, during the execution of the code, every outgoing TCP socket will go through the SOCKS proxy server at socks.mydomain.com:1080.

Now, what happens when both a SOCKS proxy and a HTTP proxy are defined? Well the rule is that settings for higher level protocols, like HTTP or FTP, take precedence over SOCKS settings. So, in that particular case, when establishing a HTTP connection, the SOCKS proxy settings will be ignored and the HTTP proxy will be contacted. Let's look at an example:

$ java -Dhttp.proxyHost=webcache.mydomain.com -Dhttp.proxyPort=8080
-DsocksProxyHost=socks.mydomain.com GetURL

Here, an http URL will go through webcache.mydomain.com:8080 because the http settings take precedence. But what about an ftp URL? Since no specific proxy settings were assigned for FTP, and since FTP is on top of TCP, then FTP connections will be attempted through the SOCKS proxy server at socks.mydomsain.com:1080. If an FTP proxy had been specified, then that proxy would have been used instead.

3) Proxy class

As we have seen, the system properties are powerful, but not flexible. The "all or nothing" behavior was justly deemed too severe a limitation by most developers. That's why it was decided to introduce a new, more flexible, API in J2SE 5.0 so that it would be possible to have connection based proxy settings.

The core of this new API is the Proxy class which represents a proxy definition, typically a type (http, socks) and a socket address. There are, as of J2SE 5.0, 3 possible types:

  • DIRECT which represents a direct connection, or absence of proxy.
  • HTTP which represents a proxy using the HTTP protocol.
  • SOCKS which represents proxy using either SOCKS v4 or v5.

So, in order to create an HTTP proxy object you would call:

SocketAddress addr = new
InetSocketAddress("webcache.mydomain.com", 8080);
Proxy proxy = new Proxy(Proxy.Type.HTTP, addr);

Remember, this new proxy object represents a proxy definition, nothing more. How do we use such an object? A new openConnection() method has been added to the URL class and takes a Proxy as an argument, it works the same way as openConnection() with no arguments, except it forces the connection to be established through the specified proxy, ignoring all other settings, including the system properties mentioned above.

So completing the previous example, we can now add:

URL url = new URL("http://java.sun.com/");
URConnection conn = url.openConnection(proxy);

Simple, isn't it?

The same mechanism can be used to specify that a particular URL has to be reached directly, because it's on the intranet for example. That's where the DIRECT type comes into play. But, you don't need to create a proxy instance with the DIRECT type, all you have to do is use the NO_PROXY static member:

URL url2 = new URL("http://infos.mydomain.com/");
URLConnection conn2 = url2.openConnection(Proxy.NO_PROXY);

Now, this guarantees you that this specific URL will be retrieved though a direct connection bypassing any other proxy settings, which can be convenient.

Note that you can force a URLConnection to go through a SOCKS proxy as well:

SocketAddress addr = new InetSocketAddress("socks.mydomain.com", 1080);
Proxy proxy = new Proxy(Proxy.Type.SOCKS, addr);
URL url = new URL("ftp://ftp.gnu.org/README");
URLConnection conn = url.openConnection(proxy);

That particular FTP connection will be attempted though the specified SOCKS proxy. As you can see, it's pretty straightforward.

Last, but not least, you can also specify a proxy for individual TCP sockets by using the newly introduced socket constructor:

SocketAddress addr = new InetSocketAddress("socks.mydomain.com", 1080);
Proxy proxy = new Proxy(Proxy.Type.SOCKS, addr);
Socket socket = new Socket(proxy);
InetSocketAddress dest = new InetSocketAddress("server.foo.com", 1234);
socket.connect(dest);

Here the socket will try to connect to its destination address (server.foo.com:1234) through the specified SOCKS proxy.

As for URLs, the same mechanism can be used to ensure that a direct (i.e. not through any proxy) connection should be attempted no matter what the global settings are:

Socket socket = new Socket(Proxy.NO_PROXY);
socket.connect(new InetAddress("localhost", 1234));

Note that this new constructor, as of J2SE 5.0, accepts only 2 types of proxy: SOCKS or DIRECT (i.e. the NO_PROXY instance).

4) ProxySelector

As you can see, with J2SE 5.0, the developer gains quite a bit of control and flexibility when it comes to proxies. Still, there are situations where one would like to decide which proxy to use dynamically, for instance to do some load balancing between proxies, or depending on the destination, in which case the API described so far would be quite cumbersome. That's where the ProxySelector comes into play.

In a nutshell the ProxySelector is a piece of code that will tell the protocol handlers which proxy to use, if any, for any given URL. For example, consider the following code:

URL url = new URL("http://java.sun.com/index.html");
URLConnection conn = url.openConnection();
InputStream in = conn.getInputStream();

At that point the HTTP protocol handler is invoked and it will query the proxySelector. The dialog might go something like that:

Handler: Hey dude, I'm trying to reach java.sun.com, should I use a proxy?
ProxySelector: Which protocol do you intend to use?
Handler: http, of course!
ProxySelector: On the default port?
Handler: Let me check.... Yes, default port.
ProxySelector: I see. Then you shall use webcache.mydomain.com on port 8080 as a proxy.
Handler: Thanks. <pause> Dude, webcache.mydomain.com:8080 doesn't seem to be responding! Any other option?
ProxySelector: Dang! OK, try webcache2.mydomain.com, on port 8080 as well.
Handler: Sure. Seems to be working. Thanks.
ProxySelector: No sweat. Bye.

Of course I'm embellishing a bit, but you get the idea.

The best thing about the ProxySelector is that it is plugable! Which means that if you have needs that are not covered by the default one, you can write a replacement for it and plug it in!

So what is a ProxySelector? Let's take a look at the class definition:

public abstract class ProxySelector {
    public static ProxySelector getDefault();
    public static void setDefault(ProxySelector ps);
    public abstract List<Proxy> select(URI uri);
    public abstract void connectFailed(URI uri,
        SocketAddress sa, IOException ioe);
}

As we can see, ProxySelector is an abstract class with 2 static methods to set, or get, the default implementation, and 2 instance methods that will be used by the protocol handlers to determine which proxy to use or to notify that a proxy seems to be unreachable. If you want to provide your own ProxySelector, all you have to do is extend this class, provide an implementation for these 2 instance methods then call ProxySelector.setDefault() passing an instance of your new class as an argument. At this point the protocol handlers, like http or ftp, will query the new ProxySelector when trying to decide what proxy to use.

Before we see in details how to write such a ProxySelector, let's talk about the default one. J2SE 5.0 provides a default implementation which enforces backward compatibility. In other terms, the default ProxySelector will check the system properties described earlier to determine which proxy to use. However, there is a new, optional feature: On recent Windows systems and on Gnome 2.x platforms it is possible to tell the default ProxySelector to use the system proxy settings (both recent versions of Windows and Gnome 2.x let you set proxies globally through their user interface). If the system property java.net.useSystemProxies is set to true (by default it is set to false for compatibility sake), then the default ProxySelector will try to use these settings. You can set that system property on the command line, or you can edit the JRE installation file lib/net.properties, that way you have to change it only once on a given system.

Now let's examine how to write, and install, a new ProxySelector.

Here is what we want to achieve: We're pretty happy with the default ProxySelector behavior, except when it comes to http and https. On our network we have more than one possible proxy for these protocols and we we'd like our application to try them in sequence (i.e.: if the 1st one doesn't respond, then try the second one and so on). Even more, if one of them fails too many time, we'll remove it from the list in order to optimize things a bit.

All we need to do is subclass java.net.ProxySelector and provide implementations for both the select() and connectFailed() methods.

The select() method is called by the protocol handlers before trying to connect to a destination. The argument passed is a URI describing the resource (protocol, host and port number). The method will then return a List of Proxies. For instance the following code:

URL url = new URL("http://java.sun.com/index.html");
InputStream in = url.openStream();

will trigger the following pseudo-call in the protocol handler:

List<Proxy> l = ProxySelector.getDefault().select(new URI("http://java.sun.com/"));

In our implementation, all we'll have to do is check that the protocol from the URI is indeed http (or https), in which case we will return the list of proxies, otherwise we just delegate to the default one. To do that, we'll need, in the constructor, to store a reference to the old default, because ours will become the default.

So it is starting to look like this:

public class MyProxySelector extends ProxySelector {
    ProxySelector defsel = null;
    MyProxySelector(ProxySelector def) {
        defsel = def;
    }

    public java.util.List<Proxy> select(URI uri) {
        if (uri == null) {
            throw new IllegalArgumentException("URI can't be null.");
        }
        String protocol = uri.getScheme();
        if ("http".equalsIgnoreCase(protocol) ||
            "https".equalsIgnoreCase(protocol)) {
            ArrayList<Proxy> l = new ArrayList<Proxy>();
            // Populate the ArrayList with proxies
            return l;
        }
        if (defsel != null) {
            return defsel.select(uri);
        } else {
            ArrayList<Proxy> l = new ArrayList<Proxy>();
            l.add(Proxy.NO_PROXY);
            return l;
        }
    }
}

First note the constructor that keeps a reference to the old default selector. Second, notice the check for illegal argument in the select() method in order to respect the specifications. Finally, notice how the code defers to the old default, if there was one, when necessary. Of course, in this example, I didn't detail how to populate the ArrayList, as it not of particular interest, but the complete code is available in the appendix if you're curious.

As it is, the class is incomplete since we didn't provide an implementation for the connectFailed() method. That's our very next step.

The connectFailed() method is called by the protocol handler whenever it failed to connect to one of the proxies returned by the select() method. 3 arguments are passed: the URI the handler was trying to reach, which should be the one used when select() was called, the SocketAddress of the proxy that the handler was trying to contact and the IOException that was thrown when trying to connect to the proxy. With that information, we'll just do the following: If the proxy is in our list, and it failed 3 times or more, we'll just remove it from our list, making sure it won't be used again in the future. So the code is now:

public void connectFailed(URI uri, SocketAddress sa, IOException ioe) {
    if (uri == null || sa == null || ioe == null) {
        throw new IllegalArgumentException("Arguments can't be null.");
    }
    InnerProxy p = proxies.get(sa);
    if (p != null) {
        if (p.failed() >= 3)
            proxies.remove(sa);
    } else {
        if (defsel != null)
            defsel.connectFailed(uri, sa, ioe);
    }
}

Pretty straightforward isn't it. Again we have to check the validity of the arguments (specifications again). The only thing we do take into account here is the SocketAddress, if it's one of the proxies in our list, then we do deal with it, otherwise we defer, again, to the default selector.

Now that our implementation is, mostly, complete, all we have to do in the application is to register it and we're done:

public static void main(String[] args) {
    MyProxySelector ps = new MyProxySelector(ProxySelector.getDefault());
    ProxySelector.setDefault(ps);
    // rest of the application
}

Of course, I simplified things a bit for the sake of clarity, in particular you've probably noticed I didn't do much Exception catching, but I'm confident you can fill in the blanks.

It should be noted that both Java Plugin and Java Webstart do replace the default ProxySelector with a custom one to integrate better with the underlying platform or container (like the web browser). So keep in mind, when dealing with ProxySelector, that the default one is typically specific to the underlying platform and to the JVM implementation. That's why it is a good idea, when providing a custom one, to keep a reference to the older one, as we've done in the above example, and use it when necessary.

5) Conclusion

As we have now established J2SE 5.0 provides quite a number of ways to deal with proxies. From the very simple (using the system proxy settings) to the very flexible (changing the ProxySelector, albeit for experienced developers only), including the per connection selection courtesy of the Proxy class.

Appendix

Here is the full source of the ProxySelector we developed in this paper. Keep in mind that this was written for educational purposes only, and was therefore kept pretty simple on purpose.

import java.net.*;
import java.util.List;
import java.util.ArrayList;
import java.util.HashMap;
import java.io.IOException;

public class MyProxySelector extends ProxySelector {
    // Keep a reference on the previous default
    ProxySelector defsel = null;

    /*
     * Inner class representing a Proxy and a few extra data
     */
    class InnerProxy {
        Proxy proxy;
        SocketAddress addr;
        // How many times did we fail to reach this proxy?
        int failedCount = 0;

        InnerProxy(InetSocketAddress a) {
            addr = a;
            proxy = new Proxy(Proxy.Type.HTTP, a);
        }

        SocketAddress address() {
            return addr;
        }

        Proxy toProxy() {
            return proxy;
        }

        int failed() {
            return ++failedCount;
        }
    }

    /*
     * A list of proxies, indexed by their address.
     */
    HashMap<SocketAddress, InnerProxy> proxies = new HashMap<SocketAddress, InnerProxy>();

    MyProxySelector(ProxySelector def) {
      // Save the previous default
      defsel = def;

      // Populate the HashMap (List of proxies)
      InnerProxy i = new InnerProxy(new InetSocketAddress("webcache1.mydomain.com", 8080));
      proxies.put(i.address(), i);
      i = new InnerProxy(new InetSocketAddress("webcache2.mydomain.com", 8080));
      proxies.put(i.address(), i);
      i = new InnerProxy(new InetSocketAddress("webcache3.mydomain.com", 8080));
      proxies.put(i.address(), i);
      }

      /*
       * This is the method that the handlers will call.
       * Returns a List of proxy.
       */
      public java.util.List<Proxy> select(URI uri) {
        // Let's stick to the specs.
        if (uri == null) {
            throw new IllegalArgumentException("URI can't be null.");
        }

        /*
         * If it's a http (or https) URL, then we use our own
         * list.
         */
        String protocol = uri.getScheme();
        if ("http".equalsIgnoreCase(protocol) ||
            "https".equalsIgnoreCase(protocol)) {
            ArrayList<Proxy> l = new ArrayList<Proxy>();
            for (InnerProxy p : proxies.values()) {
              l.add(p.toProxy());
            }
            return l;
        }

        /*
         * Not HTTP or HTTPS (could be SOCKS or FTP)
         * defer to the default selector.
         */
        if (defsel != null) {
            return defsel.select(uri);
        } else {
            ArrayList<Proxy> l = new ArrayList<Proxy>();
            l.add(Proxy.NO_PROXY);
            return l;
        }
    }

    /*
     * Method called by the handlers when it failed to connect
     * to one of the proxies returned by select().
     */
    public void connectFailed(URI uri, SocketAddress sa, IOException ioe) {
        // Let's stick to the specs again.
        if (uri == null || sa == null || ioe == null) {
            throw new IllegalArgumentException("Arguments can't be null.");
        }

        /*
         * Let's lookup for the proxy
         */
        InnerProxy p = proxies.get(sa);
            if (p != null) {
                /*
                 * It's one of ours, if it failed more than 3 times
                 * let's remove it from the list.
                 */
                if (p.failed() >= 3)
                    proxies.remove(sa);
            } else {
                /*
                 * Not one of ours, let's delegate to the default.
                 */
                if (defsel != null)
                  defsel.connectFailed(uri, sa, ioe);
            }
     }
}

Feedback to:jean-christophe.collet@sun.com


Java Networking Features

 Documentation Contents

API Specification

  • java.net Package
  • javax.net Package
  • javax.net.ssl
  • com.sun.net.httpserver Package
  • com.sun.net.httpserver.spi Package

API Enhancements

  • Changes and Enhancements in version 6
  • Changes and Enhancements in version 5.0
  • New Features and Enhancements in version 1.4
  • Networking Release Notes for version 1.4.2

More Information

  • Networking Overview (also available in PDF)
    Overview of networking facilities in java.net, including Addressing, Making TCP Connections, Sending/Receiving Datagram Packets via UDP, Locating/Identifying Network Resources, and Security.

  • HTTP client API. The following articles describe features of the HTTP client API. (See java.net.HttpURLConnection for an overview).

    • URLConnection Caching API
      Detailed overview, with code samples, of the new cache management API.

    • Cookie Management
      Overview of how to deal with cookies, often used as an HTTP state management mechanism, in J2SE 5.0.

    • Http authentication
      Overview of how to use HTTP authentication, which schemes and protocols are supported, and the system properties that affect its behavior.

    • Persistent Connections
      Overview of the HTTP persistent connections (aka keep alive mechanisms), and the means to control them.

  • Java Networking and Proxies
    In depth exploration, with code samples, of proxy management Java networking APIs including the newly introduced ProxySelector mechanism.

  • IPv6 Support (also available in PDF)
    IPv6 support, including special IPv6 address types and dual-stack node.

  • Networking Properties
    Descriptions of properties used by networking.

  • Orderly Versus Abortive Connection Release in Java
    How to ensure orderly or graceful release of TCP connections in Networking applications.

  • Extendable Socket and ServerSocket
    The design, rationale, and how to do it.

  • Socket Options
    Support for popular BSD-style options in the java base classes.

  • Socket Exceptions
    Subclasses of SocketException for finer granularity of handling network errors.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.
Feedback

Sun Microsystems, Inc
Java Software


Miscellaneous changes to java.net

Miscellaneous changes to java.net worth mentioning:

Noteworthy bug fixes:

  • InetAddress
    A bug existed in JDK1.0.2 where one could not create an InetAddress out of a IP address String (e.g., "206.26.48.100") if a corresponding host name (e.g., "java.sun.com") could not be found. This resulted in an UnknownHostException. The bug is fixed in JDK1.1. Additionally, when an InetAddress is created from an IP address, the corresponding hostname is not looked up until specifically requested (via InetAddress.getHostName()), as a performance enhancement.
  • ServerSocket/DatagramSocket close()
    A bug existed in JDK1.0.2 where the close() method of ServerSocket and DatagramSocket were synchronized. The result was that if one thread were blocked indefinitely in DatagramSocket.receive() or ServerSocket.accept(), another thread couldn't break the blocking thread out by calling close(). This is fixed in JDK1.1 by making the close() methods unsynchronized.
  • URLConnection
    There was a bug in JDK1.0.2 where the methods on URLConnection:
    • setRequestProperty()
    • getRequestProperty()
    • getHeaderField()
    • getHeaderFieldInt()
    • getContentLength()
    • getDate()
    etc, did not work. These are fixed in JDK1.1.

Binding to local port/address:

  • Socket, ServerSocket, DatagramSocket
    These classes has overloaded constructors for binding to a specific local address and port. This is useful and necessary for applications like proxy servers that operate on multi-homed machines, and need particular control over which network interfaces are used.

MulticastSocket:

  • The MulticastSocket class was moved from package sun.net into the core API of java.net.

HttpURLConnection:

  • JDK1.1 introduces a new class, HttpURLConnection which extends URLConnection, and provides additional functionality specific to HTTP:
  • Ability to use all of the request methods with HTTP/1.1, like:
    • GET
    • POST
    • PUT
    • HEAD
    • TRACE
    • DELETE
    • OPTIONS
  • Control over whether to follow HTTP redirects.
David Brown
Last modified: Thu Dec 5 15:09:54 PST


Networking Enhancments for J2SE 5.0

  • Complete support for IPv6 on Windows XP (SP1) and 2003 server has been provided in this release. (4608529)
  • The networking API now provides a way of setting timeouts on connect and read operations for protocol handlers. This will benefit any HTTP client application that must behave robustly in the event of server failure. (4700777)
  • A new API provides a mean for Java applications, which includes RMI applications, to be launched via inetd. (4295885, 4673940)
  • The InetAddress class now provides an API to allow testing for the reachability of a host. This features provides a ping-like capability in Java. (4639861)
  • Cookie support has been improved. Applications and web containers can provide Cookie management by implementing the new CookieHandler API. (4696506)
  • Proxy server configuration has been improved. It can now be dynamic and controlable by web containers and applications through the ProxySelector API, which can also handle failures to connect to the proxy. (4696512)
  • A new framework provides a way for protocol handlers to access a file caching mechanism implemented by the platform or by a third party. (4837267)
  • The specification of the URL class now mandates a minimum set of URL protocol handlers that are guaranteed to be present in J2SE. They are http, https, file, jar and ftp. (4180636)
  • There have been a number of enhancements for JSSE (SSL/TLS). For more information, please see: J2SE 5 Security Enhancements


Networking Features

Java

Networking

 Documentation Contents
Networking Enhancements for JavaTM 2 SDK, Standard Edition, v 1.3

New Classes/Interfaces

  • java.net.DatagramSocketImplFactory

    New interface java.net.DatagramSocketImplFactory is used by DatagramSocket to create actual socket implementations. This addition makes DatagramSocket consistent with the other socket types, by allowing the user to set the DatagramSocketImplFactory through a public API.

Modified Classes/Interfaces

  • java.net.HttpURLConnection

    The following constants were added to java.net.HttpURLConnection to make the HTTP status codes match the HTTP 1.1 RFC:

    • public static final int HTTP_INTERNAL_ERROR = 500;
    • public static final int HTTP_NOT_IMPLEMENTED = 501;

    Two new methods were added to support following HTTP redirects (requests with response code 3xx) on a per-instance basis. The default is to use the class setting.

    • public boolean getInstanceFollowRedirects()
    • public void setInstanceFollowRedirects(boolean followRedirects)

  • java.net.Socket and java.net.SocketImpl

    Two new methods have been added to java.net.Socket. Java sockets now support the keepalive option.

    • public boolean getKeepAlive(boolean)
    • public void setKeepAlive(boolean on)

    Two new methods have been added to java.net.Socket and java.net.SocketImpl. This change is to support TCP half-closed sockets:

    • public void shutdownInput()
    • public void shutdownOutput()

  • java.net.URL,java.net.URLConnection, and java.net.ContentHandler

    Several access methods have been added to make java.net.URL consistent with the fields of a URL as described in the latest IETF specification, RFC2396.

    • public String getAuthority()
    • public String getPath()
    • public String getQuery()
    • public String getUserInfo()
    • public set(String protocol, String host, int port, String authority, String userInfo, String path, String query, String ref)

    An overloaded getContent() method was added to java.net.URL, java.net.URLConnection, and java.net.ContentHandler to allow requesting that the returned content object support one of an ordered list of Java types. This allows mapping of MIME types to more than one possible Java type, and improves system flexibility.

    • varied implementation, see javadocs for each class.

    Static methods java.net.URLConnection.setDefaultRequestProperty() and java.net.URLConnection.getDefaultRequestProperty() are now deprecated.

  • java.net.URLDecoder

    The method java.net.URLDecoder.decode(String) no longer throws an exception.

  • java.net.URLStreamHandler

    Several new methods have been added to java.net.URLStreamHandler.

    These additions expose the concept of a handler's default port number and allow URL handlers to override aspects of URL equality and hashcode comparisons in URL protocol-specific ways. These changes enable cleaner access to the parsed component parts of a URL and enhance the ability of the various URL handlers to share common parsing code.

    • protected boolean equals(URL u1, URL u2)
    • protected getDefaultPort()
    • protected InetAddress getHostAddress(URL u)
    • protected int hashCode(URL u)
    • protected boolean hostsEqual(URL u1, URL u2)
    • protected boolean sameFile(URL u1, URL u2)
    • protected void setURL(URL u, String protocol, String host, int port, String authority, String userInfo, String path, String query, String ref)

  • java.util.jar.JarFile and java.util.zip.ZipFile

    There is a new open mode for java.util.zip.ZipFile and java.util.jar.JarFile, which automatically deletes temporary (cached) files associated with each JarURLConnection when the Zip/Jar file opened in this mode is closed and the process exits. This is useful when downloading temporary jar files onto a local disk.

Miscellaneous Information

  • Added HTTP 1.1 client-side support and enhancements, such as http keepalives.
  • The SDK now does a better job of URL parsing by following RFC 2396 much more closely.

Copyright © 1996-99 Sun Microsystems, Inc. All Rights Reserved.

 Sun Microsystems, Inc
Java Software


Networking Features

Java

Networking features and enhancements
in Java SE version 6.0

 Documentation Contents

Enhancement to NetworkInterface

Provides a number of new methods for accessing state and configuration information relating to a system's network adapters. This includes information such as the broadcast address, subnet mask, MAC addresses, and MTU size. See java.net.NetworkInterface

The new class java.net.InterfaceAddress encapsulates all information about a NetworkInterface's IP addresses, including the broadcast address, and subnet prefix length (subnet mask)

Support for Internationalized Domain Names

RFCs 3490, 3491, 3492, 3454 define a mechanism where domain names comprised of characters in alphabets other than US ASCII can be stored in the DNS. An algorithm is defined which provides a conversion from arbitrary Unicode strings to and from a "mangled" ASCII form. This feature provides a new class java.net.IDN, which allows applications to do this conversion so that IDNs can be looked up via java.net.InetAddress.

HTTP Negotiate authentication

This adds support for the "Negotiate" HTTP authentication scheme defined by Microsoft. Negotiate allows multiple underlying authentication mechanisms to be supported, and in each instance, one of these mechanisms is chosen for use. Currently, Kerberos is the only supported mechanism. This feature is described in more detail in the guide to Http Authentication.

Cross platform NTLM

Previously, the Microsoft defined NTLM authentication protocol for HTTP was only supported on Windows. Now, this protocol is supported on all platforms.

Default CookieManager implementation

The CookieHandler class was added in 1.5, but no implementation was provided in java.net. This feature provides a simple extensible implementation which separates the storage of cookies from the policy surrounding their acceptance. The default manager provides a number of standard policies and a simple in-memory storage mechanism. User defined policies and storage mechanisms can be used with this implementation. The following are the new classes related to this feature:
  • java.net.CookieManager
  • java.net.CookiePolicy
  • java.net.CookieStore
  • java.net.HttpCookie

Light-weight HTTP server

This provides a simple set of classes and interfaces for building light-weight HTTP server applications. The feature defines two new packages com.sun.net.httpserver and com.sun.net.httpserver.spi. The server supports HTTP and HTTPS.


Networking Features

Java

Networking
New Features and Enhancements

 Documentation Contents

IPv6 (Internet Protocol version 6)

J2SETM 1.4 supports IPv6 in TCP and UDP-based applications, including multicast, and will support most end-user applications in use today. See the IPv6 User Guide.

HTTP Digest Authentication

The HTTP digest authentication implementation has been updated to support proxies as well as origin servers, and has also been updated to provide all capabilities defined in RFC2617, except for the auth-int mode.

A number of system properties have been added which modify the behavior of the digest authentication mechanism. These are identified in the Networking Properties document.

Unconnected/Unbound Socket Support

Allows more flexible socket creation, binding, and connection. Enables manipulation of socket options before establishing or accepting connections. In addition a timeout can be specified when establishing a connection.

New class javax.net.ssl.SSLSocket is a subclass of java.net.Socket that provides security through encryption. The mechanism is called the Java Secure Socket Extension (JSSE), and it provides encryption for data sent via sockets. See the JSSE Reference Guide for further information.

Connected UDP Socket Support

The DatagramSocket.connect method now establishes the address association at native level. Where supported, this allows an application to have visibility of ICMP port unreachable messages as an indication that the remote application is unavailable.

Uniform Resource Indentifier (URI)

Class java.net.URI is new in J2SE 1.4. It allows URI construction and parsing without the presence of a protocol handler, which is not possible with the URL class. The URI class is compliant with RFC 2396 and RFC 2732.

FTP Protocol Handler

Significant overhaul to make the functionality conform as much as possible to the current standards (RFC 1738 & 959). This enhancement fixes several bugs associated with FTP functionality. For example, passive mode for FTP works in J2SE 1.4.

JNDI DNS SP Support in InetAddress

This enhancement in class java.net.InetAddress enables applications to configure a pure Java name service provider by using a DNS name service provider through JNDI. See JNDI DNS service provider settings in the Network Properties document for information on enabling this support.

URLEncoder and URLDecoder Improvements

Methods URLEncoder.encode(String s, String enc) and URLDecoder.decode(String s, String enc) have been added to enable applications to use other character encoding/decoding schemes.

TCP Out-of-Band Data

Two new methods in class java.net.Socket, sendUrgentData() and getOOBInline(), provide limited support for TCP urgent data for support certain legacy applications. Urgent data may be sent on any TCP socket. However, only partial support for receiving urgent data is provided.

SOCKS

Full V5 (RFC 1928) & V4 TCP support with autonegociation with the proxy of which version to use. See the SOCKS protocol support settings in the Network Properties document for information about using properties to specify the SOCKS proxy server.

NetworkInterface

Class java.net.NetworkInterface is new in J2SE 1.4. It allows enumeration of interfaces and addresses. This new class should be useful to applications deployed on multihomed and machines with multiple network interfaces.

Other Major Improvements

J2SE 1.4 also offers the following.
  • Improved Http streaming performance.
  • Request and response headers processing functionality in the form of these new methods in class java.net.URLConnection"
    addRequestProperty
    getRequestProperties
    getHeaderFields
  • Improved error handling implementation for method HttpURLConnection.getErrorStream().

New Classes

Here are links to the API specifications for the new classes and exceptions in the java.net package.
  • Inet4Address
  • Inet6Address
  • InetSocketAddress
  • NetworkInterface
  • SocketAddress
  • URI
  • PortUnreachableException
  • SocketTimeoutException
  • URISyntaxException

Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.

 Sun Microsystems, Inc
Java Software


Networking Properties

 Documentation Contents

Java Properties

java.net.preferIPv4Stack (default: false)
If IPv6 is available on the operating system the underlying native socket will be an IPv6 socket. This allows Java(tm) applications to connect too, and accept connections from, both IPv4 and IPv6 hosts.

If an application has a preference to only use IPv4 sockets then this property can be set to true. The implication is that the application will not be able to communicate with IPv6 hosts.

java.net.preferIPv6Addresses (default: false)
If IPv6 is available on the operating system the default preference is to prefer an IPv4-mapped address over an IPv6 address. This is for backward compatibility reasons - for example applications that depend on access to an IPv4 only service or applications that depend on the %d.%d.%d.%d representation of an IP address. This property can be set to try to change the preferences to use IPv6 addresses over IPv4 addresses. This allows applications to be tested and deployed in environments where the application is expected to connect to IPv6 services.

networkaddress.cache.ttl
Specified in java.security to indicate the caching policy for successful name lookups from the name service.. The value is specified as as integer to indicate the number of seconds to cache the successful lookup.

A value of -1 indicates "cache forever". The default behavior is to cache forever when a security manager is installed, and to cache for an implementation specific period of time, when a security manager is not installed.

networkaddress.cache.negative.ttl (default: 10)
Specified in java.security to indicate the caching policy for un-successful name lookups from the name service.. The value is specified as as integer to indicate the number of seconds to cache the failure for un-successful lookups.

A value of 0 indicates "never cache". A value of -1 indicates "cache forever".

http.proxyHost (default: <none>)
http.proxyPort (default: 80 if http.proxyHost specified)
http.nonProxyHosts (default: <none>

ftp.proxyHost (default: <none>)
ftp.proxyPort (default: 80 if ftp.proxyHost specified)
ftp.nonProxyHosts (default: <none>)

http.proxyHost and http.proxyPort indicate the proxy server and port that the http protocol handler will use.

http.nonProxyHosts indicates the hosts which should be connected too directly and not through the proxy server. The value can be a list of hosts, each seperated by a |, and in addition a wildcard character (*) can be used for matching. For example: -Dhttp.nonProxyHosts="*.foo.com|localhost".

ftp.proxyHost and ftp.proxyPort indicate the proxy server and port that the ftp protocol handler will use. ftp.nonProxyHosts is similiar to http.nonProxyHosts and indicates the hosts that should be connected too directly and not through the proxy server.

http.agent (default: Java1.4.0)

Indicates the User-Agent request header sent in http requests.

http.auth.digest.validateServer (default: false)
http.auth.digest.validateProxy (default: false)
http.auth.digest.cnonceRepeat (default: 5)
These system 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 (ie. by proving that it knows the users password). However, not all servers support this capability and by default the check is switched off. The first two properties above can be set to true, to enforce this check, for either authentication with an origin, or a proxy server respectively.

It is not normally necessary to set the third property (http.auth.digest.cnonceRepeat). This determines how many times a cnonce value is reused. This can be useful when the MD5-sess algorithm is being used. Increasing the value reduces the computational overhead on both the client and the server by reducing the amount of material that has to be hashed for each HTTP request.

http.auth.ntlm.domain:
Similar to other HTTP authentication schemes, NTLM 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 three options for specifying the domain:

  1. Do not specify it. In some environments, the domain is not actually required and the application need not specify it.
  2. 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, so long as users are made aware that this notation must be used.
  3. If a domain name is not specified as in method 2) and the system property "http.auth.ntlm.domain" is defined, then the value of this property will be used as the domain name.

http.keepAlive (default: true)
Indicates if keep alive (persistent) connections should be supported. Persistent connections improve performance by allowing the underlying socket connection be reused for multiple http requests.

The default is true and thus persistent connections will be used with http 1.1 servers. Set to 'false' to disable the use of persistent connections.

http.maxConnections (default: 5)
If HTTP keep-alive is enabled, this value is the number of idle connections that will be simultaneously kept alive, per-destination.

SOCKS protocol support settings
The SOCKS username and password are acquired in the following way. First, if the application has registered a java.net.Authenticator default instance, then this will be queried with the protocol set to the string "SOCKS5", and the prompt set to to the string "SOCKS authentication". If the authenticator does not return a username/password or if no authenticator is registered then the system checks for the user preferences "java.net.socks.username" and "java.net.socks.password". If these preferences do not exist, then the system property "user.name" is checked for a username. In this case, no password is supplied.
socksProxyHost
socksProxyPort (default: 1080)
Indicates the name of the SOCKS proxy server and the port number that will be used by the SOCKS protocol layer. If socksProxyHost is specified then all TCP sockets will use the SOCKS proxy server to establish a connection or accept one. The SOCKS proxy server can either be a SOCKS v4 or v5 server and it has to allow for unauthenticated connections.

Sun implementation-specific properties

These properties may not be supported in future releases.
sun.net.inetaddr.ttl
This is a sun private system property which corresponds to networkaddress.cache.ttl. It takes the same value and has the same meaning, but can be set as a command-line option. However, the preferred way is to use the security property mentioned above.

sun.net.inetaddr.negative.ttl
This is a sun private system property which corresponds to networkaddress.cache.negative.ttl. It takes the same value and has the same meaning, but can be set as a command-line option. However, the preferred way is to use the security property mentioned above.

sun.net.client.defaultConnectTimeout (default: -1)
sun.net.client.defaultReadTimeout (default: -1)
These properties specify the default connect and read timeout (resp.) for the protocol handler used by java.net.URLConnection.

sun.net.client.defaultConnectTimeout specifies the timeout (in milliseconds) to establish the connection to the host. For example for http connections it is the timeout when establishing the connection to the http server. For ftp connection it is the timeout when establishing the connection to ftp servers.

sun.net.client.defaultReadTimeout specifies the timeout (in milliseconds) when reading from input stream when a connection is established to a resource.

sun.net.http.retryPost (default: true)
It determines if an unsuccessful HTTP POST request will be automatically resent to the server. Unsuccessful in this case means the server did not send a valid HTTP response or an IOException occurred.

JNDI DNS service provider settings
These properties may not be supported in future releases.
sun.net.spi.nameservice.provider.<n>=<default|dns,sun|...>
Specifies the name service provider that you can use. By default, Java will use the system configured name lookup mechanism, such as file, nis, etc. You can specify your own by setting this option. takes the value of a positive number, it indicates the precedence order with a small number takes higher precendence over a bigger number. In J2SETM 1.4, we have provided one DNS name service provider through JNDI, which is called "dns,sun".

sun.net.spi.nameservice.nameservers=<server1_ipaddr,server2_ipaddr ...>
You can specify a comma separated list of IP addresses that point to the DNS servers you want to use. If the sun.net.spi.nameservice.nameservers property is not defined, then the provider will use any name servers already configured in the platform DNS configuration.

sun.net.spi.nameservice.domain=<domainname>
This property specifies the default DNS domain name, for instance, eng.sun.com. If the sun.net.spi.nameservice.domain property is not defined then the provider will use any domain or domain search list configured in the platform DNS configuration.

Copyright © 2002 Sun Microsystems, Inc. All Rights Reserved.

 Sun Microsystems, Inc


Networking Release Notes
The following are known bugs and other networking issues for JavaTM 2 SDK, Standard Edition, v1.4.2.
  • In releases prior to 1.4.2, it was possible to create an invalid URL instance such as the following: new URL ("http://www.foo.com:-1/index.html"). Specifying a port number of -1 is not valid. However, in previous releases the -1 was stripped off when sending such URLS with HTTP commands. In 1.4.2, the -1 is left in the URL and this may cause problems for some HTTP servers or proxies. Applications should not create URL instances with a -1 port number. Assuming the -1 refers to the default port in this example, the correct way to create this URL is new URL ("http://www.foo.com/index.html"). This note only applies to the single argument URL constructor.
  • On Microsoft Windows 98/ME, a read timeout set using Socket.setSoTimeout or an accept timeout set using ServerSocket.setSoTimeout may result in a timeout that is 500ms later than expected. This issue is observable with all J2SE releases and stems from a Microsoft Windows 98/ME bug. A patch for Microsoft Windows 98/ME is obtainable through the following page on the Microsoft website: http://support.microsoft.com/default.aspx?scid=KB;EN-US;Q257821&
  • Prior to J2SE 1.4.1 the java.net.InetAddress.getLocalHost() would cache the lookup of the IP address of the local machine for the entire session of the application. This behaviour poses a problem for applications running on machines that are connected to the internet via a dial-up connection or machines that acquired their addresses through DHCP. This has been corrected in 1.4.1 so that the local IP address is no longer cached. InetAddress.getLocalHost() will return the correct IP address for dial-up connections as well as for DHCP. See bug 4211819.
  • Prior to J2SE 1.4.1, the http/https protocol handlers would not redirect correctly from a http URL to a https URL (and vice versa). In particular, the redirect was attempted using the original URL scheme. This has been fixed in 1.4.1. by returning the server responses for such redirects (from http to https or https to http) to the application. Therefore, it is the applications responsibility to check the response code and recognize it as a redirect. The Location header field value can be checked for the redirect information, and then the application must decide whether or not to follow the redirect using the new protocol. See bug 4620571.
  • Prior to J2SE 1.4 the java.net.URLConnection class would handle errors from http servers inconsistently. In particular the getInputStream or other methods would throw a FileNotFoundException if the http server returned a response code >= 400 and the request was for a resource of a known file type.

    This has been corrected in 1.4 so that an IOException is thrown for any http error from the server and a specific exception of FileNotFoundExeption when the resource is not found (ie: 404 or 410 response codes). The exception is thrown irrespective of the file type.

    Applications that assumed an exception would not be thrown when an http error is returned from the server need to be aware of this change in 1.4 - see 4160499.

    Related to this issue is that HttpURLConnection.getErrorStream() method can now been used to read the error page from the http server when a http error is returned from the server. Previously getErrorStream() always returned null.

  • Prior to J2SE 1.4 the InetAddress.toString() would perform a lookup via the name service if the hostname wasn't previously resolved. This is no longer the case in 1.4 and toString will return immediately. If the hostname is not resolved the returned string will contain the dotted IP address only.

    Applications that depend on toString() returning a string with the resolved hostname should be aware of this correction in 1.4 - see 4239141.

  • Prior to J2SE 1.4 if InetAddress.getByName if a lookup to the name service failed then all subsequent lookups of that hostname would fail for the lifetime of the virtual machine. This arose because negative lookups were always cached. This has changed in 1.4 so that by default if a lookup fails it's possible for a subsequent lookup to succeed. This is particularly important in dial-up environments or environments where the name service is not reliable.

    Applications that depend on behaviour where subsequent lookups always failed need to be aware of this issue - see 4256129. In addition the caching of negative lookups can be controlled by the networkaddress.cache.negative.ttl property in the java.security file.

  • Java 2 Platform, Standard Edition, v1.4 introduces a new exception java.net.PortUnreachableException. This exception may be thrown by DatagramSocket.send or DatagramSocket.receive if the DatagramSocket is connected (via the connect method) and an ICMP port unreachable is received to indicate that the remote application is not running. The PortUnreachableException serves as a useful indication for some UDP based protocols.

    The following lists the known issues with PortUnreachableException :-

    1. On Solaris 8 if IPv6 is enabled then ICMP port unreachable packets from IPv4 hosts will appear to be discarded. This is a Solaris 8 bug and is tracked as bug 4422658.
    2. On some Microsoft Windows releases (specifically Windows 98 and Windows NT) ICMP port unreachable packets are incorrectly discarded by the operating system and thus the PortUnreachableException is not thrown. As this time we are not aware of any Windows Sockets updates from Microsoft to fix this issue.
    3. On Linux if UDP packets are sent to the loopback address and no UDP applicatiob to bound to the destination port no ICMP port unreachable indication is received and thus no PortUnreachableException is thrown. This is a Linux kernel issue and we are not aware of a patch at this time.
  • On many Linux installations InetAddress.getLocalHost() may return an InetAddress representing the loopback address (127.0.0.1). This stems from many Linux installations configuring /etc/hosts to map the hostname to the loopback address. If the host has a static IP address then the /etc/hosts file should be corrected to map the hostname to the host address.

    If DHCP is used in conjunction with dynamic DNS then there are two options (i) change the name service search order in /etc/nsswitch.conf to use dns before the hosts file (ie: "hosts: dns files"), or (ii) configure InetAddress to use the DNS name service provider instead of the default provider (-Dsun.net.spi.nameservice.provider.1=dns,sun). This issue is being tracked in 4665037.

Copyright © 2002 Sun Microsystems, Inc. All Rights Reserved.

 Sun


New SocketExceptions in JDK1.1

Duke icon New SocketExceptions in JDK1.1

Previously, all network errors in java raised a SocketException, which didn't provide enough information to decipher what went wrong. Was the connection refused by the remote machine (no one listening on that port)? Or was the host unreachable (connect attempt timed out)? JDK 1.1 adds three new classes that provide a finer granularity of reported errors:

  • java.net.BindException

    The local port is in use, or the requested bind address couldn't be assigned locally.
         public class BindException extends SocketException {
    ...
    }

  • java.net.ConnectException

    This exception is raised when a connection is refused at the remote host (i.e., no process is listening on that port).
         public class ConnectException extends SocketException {
    ...
    }

  • java.net.NoRouteToHostException

    The connect attempt timed out, or the remote host is otherwise unreachable.
         public class NoRouteToHostException extends SocketException {
    ...
    }

Simple Usage Examples:

  • On the Client Side:
    import java.net.*;
    ...
    Socket s = null;
    try {
       s = new Socket("foo.org", 80);
    } catch (UnknownHostException e) {
       // check spelling of hostname
    } catch (ConnectException e) {
       // connection refused - is server down? Try another port.
    } catch (NoRouteToHostException e) {
       // The connect attempt timed out.  Try connecting through a proxy
    } catch (IOException e) {
       // another error occurred
    }
  • On the Server Side:
    import java.net.*;
     ...
    ServerSocket ss = null;
    try {
        /* try to bind to local address 129.144.175.156 */
        InetAddress in = InetAddress.getByName("129.144.175.156");
        int port = 8000;
        int backlog = 5;
        ss = new ServerSocket(port, backlog, in);
    } catch (BindException e) {
        // port 8000 in use, or can't bind to 129.144.175.156 as a local address
    } catch (SocketException e) {
        // another error occurred
    }

    David Brown


Socket Options in Java

The C way

Programming in C, one sets options by using a system call along the lines of:
    setsockopt(int fd, int level, int optval, void *optdata,
           int optdatalen);

    fd = already opened (possibly connected) socket fd;
    level = level in the protocol stack (IP, UDP, TCP) where
            the option applies;
    optval = the option, a CONSTANT;
    optdata = ptr to option dependent struct of parameters relevant
             only to a particular option;

In java

The C way of setting options lacks the type-safety of object-oriented programming. The option one wishes to set/get is identified by an int, and the value to set/get into is an opaque void*. It is all too easy to pass the wrong option identifier, the wrong type object in the void* parameter, or the wrong for that parameter. Worse still, the code for these errors will typically compile, and the error will only be manifested at runtime.

Java now provides a type-safe way to set options. Each socket class has a get/set method for each option it supports, taking and returning the appropriate type. The options supported, for which socket classes and their meaning in brief:

  • TCP_NODELAY
    • Disable Nagle's algorithm.
    • Valid for (client) Sockets.
  • SO_LINGER
    • Specify a linger-on-close timeout.
    • Valid for (client) Sockets.
  • SO_TIMEOUT
    • Specify a timeout on blocking socket operations. (Don't block forever!
    • Valid for all sockets: Socket, ServerSocket, DatagramSocket.
  • SO_BINDADDR
    • Fetch the local address binding of a socket.
    • Valid for Socket, ServerSocket, DatagramSocket.
  • SO_REUSEADDR
    • Enable reuse address for a socket.
    • Valid for Socket, ServerSocket, DatagramSocket.
  • SO_BROADCAST
    • Enables a socket to send broadcast messages.
    • Valid for DatagramSocket.
  • SO_SNDBUF
    • Set a hint the size of the underlying buffers for outgoing network I/O.
    • Valid for all sockets: Socket, ServerSocket, DatagramSocket.
  • SO_RCVBUF
    • Get the size of the buffer actually used by the platform when receiving in data on this socket.
    • Valid for all sockets: Socket, ServerSocket, DatagramSocket.
  • SO_KEEPALIVE
    • Turn on socket keepalive.
    • Valid for Socket.
  • SO_OOBINLINE
    • Enable inline reception of TCP urgent data.
    • Valid for Socket.
  • IP_MULTICAST_IF
    • Specify the outgoing interface for multicast packets (on multihomed hosts).
    • Valid for MulticastSockets.
  • IP_MULTICAST_LOOP
    • Enables or disables local loopback of multicast datagrams.
    • Valid for MulticastSocket.
  • IP_TOS
    • Sets the type-of-service or traffic class field in the IP header for a TCP or UDP socket.
    • Valid for Socket, DatagramSocket

Fell by the wayside...

Some possible BSD options that are not supported in java:
  • RAW/ICMP SOCKETS:
    The main argument in favor of this one seemed to be so people could write "ping" in java. Security nightmare. Must be root on UNIX machines.

The implementation details...

...that you don't need to know, unless you subclass SocketImpl/DatagramSocketImpl. Every *Socket object has an underlying SocketImpl/DatagramSocketImpl that interfaces to native code. The Impl classes implement two methods to support options:
    void setOption(int optID, Object val) throws SocketException;
    Object getOption(int optID) throws SocketException;
that look much like C. These methods act as glue to the native methods, and ensure type safety before native methods are invoked.


URLConnection caching API

HTTP is typically used for distributed information systems, where performance can be improved by the use of response caches. While HTTP proxy servers normally caches recently visited web resources, it is sometimes also desirable to have a local cache. Examples are browser caches.

In Tiger, a new framework provides a way for protocol handlers to access a response caching mechanism implemented by the platform or by a third party.

Here is the API:

We have introduced three abstract classes in the java.net package. They are:

  • ResponseCache
  • CacheRequest
  • CacheResponse

A concrete subclass of ResponseCache represents the URLConnection cache itself. An instance of such a class can be registered with the system by calling ResponseCache.setDefault(), and the system will call this object in order to:

  • store resource data which has been retrieved from an external source into the cache;
  • try to fetch a requested resource that may have been stored in the cache.

ResponseCache has two methods: get() returns a CacheResponse based on URI and request headers; and put() allows cache to decide if resource should be cached, returns a CacheRequest.

A concrete subclass of CacheRequest is used to write an entry in the ResponseCache. Instances of such a class provide an OutputStream object which is called by protocol handlers to store the resource data into the cache, and also an abort() method which allows a cache store operation to be interrupted and abandoned.

CacheRequest class has two methods: getBody() returns a stream for writing the request body into cache; and abort() abandons a cache write.

A concrete subclass of CacheResponse returns an entry from the ResponseCache. Instances of such a class provide an InputStream that returns the entity body, and also a getHeaders() method which returns the associated response headers.

CacheResponse class has two methods: getBody() returns a stream for reading the request body from cache; and getHeaders() returns the headers stored.

The following example shows a simple file based caching. However, it is equally viable to use other mechanisms such as a database for caching.

MyCacheResponse class is an implementation of CacheResponse. What it does is to take a file name and retrieve the HTTP response headers and body from it.

class MyCacheResponse extends CacheResponse {
FileInputStream fis;
Map<String, List<String>> headers;
public MyCacheResponse(String filename) {
    try {
     fis = new FileInputStream(new File(filename));
     ObjectInputStream ois = new ObjectInputStream (fis);
     headers = (Map<String, List<String>>)  ois.readObject();
   } catch (IOException ex) {
    // handle exception
   }
}

public InputStream getBody() throws IOException {
   return fis;
}

 public Map getHeaders() throws IOException {
   return headers;
 }
}

MyCacheRequest is an implementation of the CacheRequest. It takes a filename and the response headers and stores the headers in the file and also returns an outputstream directed to the same file so that any response body can be cached there.

class MyCacheRequest extends CacheRequest {
FileOutputStream fos;
public MyCacheRequest(String filename,
   Map<String, List<String>> rspHeaders) {
   try {
    File file = new File(filename);
    fos = new FileOutputStream(file);
    ObjectOutputStream oos = new ObjectOutputStream(fos);
    oos.writeObject(rspHeaders);
   } catch (Exception ex) {
    throw new RuntimeException(ex.getMessage());
   }
}
public OutputStream getBody() throws IOException {
   return fos;
}

public void abort() {
   // we abandon the cache by close the stream,
   // and delete the file
   fos.close();
   file.delete();
 }
}

Finally, we can tie it altogether with our implementation of the ResponseCache, it checks the URI for the network resource that is being retrieved or to be cached and returns the appropriate instantiations of our implementations of CacheResponse or CacheRequest. In this example, we only handles the case when the URI is equal to uri1 for retrieving from the cache, and for URI equals uri2 for storing to the cache. But it is easily expanded to handle a more complicated file based cache.

class MyResponseCache extends ResponseCache {
 public CacheResponse
 get(URI uri, String rqstMethod, Map rqstHeaders)
   throws IOException {
   // get the response from a cached file if available
   if (uri.equals(ParseUtil.toURI(uri1))) {
      return new MyCacheResponse(FNPrefix+"file1.cache");
   }
   return null;

public CacheRequest put(URI uri, URLConnection conn)
   throws IOException {
   // save cache to a file
   // 1. serialize headers into file2.cache
   // 2. write data to file2.cache
   if (uri.equals(ParseUtil.toURI(uri2))) {
       return new MyCacheRequest(OutFNPrefix+"file2.cache",
    conn.getHeaderFields());
   }
   return null;
 }
}

Once we have developed our own ResponseCache implementation, all left to be done is to register it and the JVM will use it.

public static void main(String args[]) throws Exception {
    ......
    ResponseCache.setDefault(new MyResponseCache());
    HttpURLConnection http = (HttpURLConnection)url1.openConnection();
    InputStream is = null;
    ......
}

There is no default implementation of URLConnection caching in the Java 2 Standard Edition. However, Java Plugin and Java WebStart do provide one out of the box.


Orderly (and Abortive) Connection Release in Java

Orderly Versus Abortive Connection Release in Java

This article covers the following topics:

  • Overview
  • Description of the Problem
  • How to Avoid the Problem

Overview

To ensure orderly or graceful release of TCP connections is a challenge with TCP networking applications. Abortive or ungraceful release may result if special care is not taken. In Java, an unexpected abortive release can manifest itself by the application receiving a java.net.SocketException when reading or writing to the socket. read() and write() normally return a numeric value indicating, respectively, the number of bytes received or sent. If an exception is received instead, this indicates the connection has been aborted and also that data may have been lost or discarded. This article explains what causes socket connections to be aborted and provides tips for avoiding the situation, except for the case where an application intends to abort the connection.

Description of the Problem

First, we need to distinguish the differences between an abortive and an orderly connection release. To understand this distinction we need to look at what happens at the TCP protocol level. It is helpful to imagine an established TCP connection as actually two separate, semi-independent streams of data. If the two peers are A and B, then one stream delivers data from A to B, and the other stream from B to A. An orderly release occurs in two stages. First one side (say A) decides to stop sending data and sends a FIN message across to B. When the TCP stack at B's side receives the FIN it knows that no more data is coming from A, and whenever B reads all preceding data off the socket, further reads will return the value -1 to indicate end-of-file. This procedure is known as the TCP half-close, because only one half of the connection is closed. Not surprisingly, the procedure for the other half is exactly the same. B sends a FIN message to A, who eventually receives a -1 after reading all preceding data sent by A off the socket.

By contrast, an abortive close uses the RST (Reset) message. If either side issues an RST, this means the entire connection is aborted and the TCP stack can throw away any queued data which has not been sent or received by either application.

So, how do Java applications perform orderly and abortive releases? Let's consider abortive releases first. A convention that has existed since the days of the original BSD sockets is that the "linger" socket option can be used to force an abortive connection release. Either application can call Socket.setLinger (true, 0) to tell the TCP stack that when this socket is closed, the abortive (RST) procedure is to be used. Setting the linger option has no immediate effect, except that when Socket.close() is called subsequently, the connection is aborted with an RST message. As we will see shortly, there are other ways that may cause a connection to be aborted, but this is the simplest way to make it happen.

The close() method is also used to perform orderly release, as well as abortive. So, at its simplest, the difference between an orderly release and an abortive release could be as little as not setting the linger(0) option, described above, prior to calling Socket.close(). Take the example of two connected peers A and B: If A calls Socket.close(), a FIN message is sent from A to B; and when B calls Socket.close(), a FIN is sent from B to A. In fact, the default setting for the linger option is to not use abortive close; so if two applications terminate their connection just by using Socket.close(), then the outcome should be an orderly release. So what, then, is the problem?

The problem is a slight mismatch between the semantics of Socket.close() and the TCP FIN message. Sending a TCP FIN message means "I am finished sending", whereas Socket.close() means "I am finished sending and receiving." When you call Socket.close(), clearly it is no longer possible to send data; nor, however, is it possible to receive data. So what happens, for example, when A attempts an orderly release by closing the socket, but B continues to send data? This is perfectly allowable in the TCP specification, because as far as TCP is concerned only one half of the connection has been closed. But since A's socket is closed there is nobody to read data if B should continue sending. In this situation A's TCP stack must send an RST to forcibly terminate the connection.

Another common scenario, which may result in an unintended SocketException, is the following: Say A has sent data to B, but B closes the socket without reading all the data. In this situation, B's TCP stack knows that some data is effectively lost and it will forcibly terminate with RST rather than use the orderly FIN procedure. A will get a SocketException if it then tries to send or receive data from the socket.

How to avoid the problem

There are a number of simple ways to avoid being surprised by this problem.

  1. Structure data with a higher-level protocol. Protocols such as HTTP, which are built on top of TCP, deal with the issue by making it clear to both sides when it is safe to close the socket.
  2. Always consume data from a socket before closing it. This will help avoid the second scenario described above.
  3. Use shutdownOutput(). This method has the same effect as close() in that a FIN is sent to indicate that this peer has finished sending, but it is still possible to read from the socket until such time as the remote peer sends a FIN and end-of-file is read from the stream. Then the socket can be closed with Socket.close().


Networking IPv6 User Guide

Networking IPv6 User Guide for JDK/JRE 5.0

This document covers the following topics:

  • Overview
  • Supported Operating Systems
  • Using IPv6 in Java
  • Details on IPv6 Support in Java
    • Special IPv6 Address Types
    • IPv6-Related System Properties
    • Dual-Stack Node
    • Java Application Impact
    • IPv6 Networking Properties

Overview

Within the past few years IPv6 has gained much greater acceptance in the industry, especially in certain regions of the world, i.e., Europe and the Asian Pacific. Extensibility, mobility, quality of service, larger address space, auto-configuration, security, multi- homing, anycast and multicast, and renumbering—these are some of the features of IPv6 that make it desirable.

With the release of J2SE 1.4 in February 2002, Java began supporting IPv6 on Solaris and Linux. Support for IPv6 on Windows was added with J2SE 1.5. While other languages, such as C and C++ can support IPv6, there are some major advantages to Java:

  • With Java you invest in a single code base that is both IPv4- and IPv6-ready.
  • Your existing Java applications are already IPv6-enabled.
  • Migration to IPv6 is easy

We will prove these statements with code examples below and provide additional details on IPv6 support.

Supported Operating Systems

The following operating systems are now supported by the J2SE reference implementation:

  • Solaris 8 and higher
  • Linux kernel 2.1.2 and higher (kernel 2.4.0 and higher recommended for better IPv6 support)
  • Windows XP SP1 and Windows 2003

Using IPv6 in Java

Using IPv6 in Java is easy; it is transparent and automatic. Unlike in many other languages, no porting is necessary. In fact, there is no need to even recompile the source files.

Consider an example from The Java Tutorial:

Socket echoSocket = null;
   PrintWriter out = null;
   BufferedReader in = null;

   try {
      echoSocket = new Socket("taranis", 7);
      out = new PrintWriter(echoSocket.getOutputStream(), true);
      in = new BufferedReader(new InputStreamReader(
         echoSocket.getInputStream()));
   } catch (UnknownHostException e) {
      System.err.println("Don't know about host: taranis.");
      System.exit(1);
   } catch (IOException e) {
      System.err.println("Couldn't get I/O for "
         + "the connection to: taranis.");
      System.exit(1);
   }
// ... code omitted here
communicateWithEchoServer(out, in);

out.close();
in.close();
stdIn.close();
echoSocket.close();

You can run the same bytecode for this example in IPv6 mode if both your local host machine and the destination machine (taranis) are IPv6-enabled.

In contrast, if you wanted the corresponding C program to run in IPv6 mode, you would first need to port it. Here's what would need to happen:

Excerpt of original C code:

struct sockaddr_in sin;
struct hostent *hp;
int sock;

/* Open socket. */
sock = socket(AF_INET, SOCK_STREAM, 0);
if (sock == -1) {
   perror("socket");
   return (-1);
}

/* Get host address */
hp = gethostbyname(hostname);
if (hp == NULL || hp->h_addrtype != AF_INET || hp->h_length != 4) {
   (void) fprintf(stderr, "Unknown host '%s'\n", hostname);
   (void) close(sock);
   return (-1);
}

sin.sin_family = AF_INET;
sin.sin_port = htons(port);
(void) memcpy((void *) &sin.sin_addr, (void *)hp->h_addr, hp->h_length);

/* Connect to the host */
if (connect(sock, (struct sockaddr *)&sin, sizeof(sin)) == -1) {
   perror("connect");
   (void) close(sock);
   return (-1);
}

Modified IPv6-aware C code:

struct addrinfo *res, *aip;
struct addrinfo hints;
int sock = -1;
int error;

/* Get host address. Any type of address will do. */
bzero(&hints, sizeof(hints));
hints.ai_flags = AI_ALL|AI_ADDRCONFIG;
hints.ai_socktype = SOCK_STREAM;

error = getaddrinfo(hostname, servicename, &hints, &res);
if (error != 0) {
   (void) fprintf(stderr,
      "getaddrinfo: %s for host %s service %s\n",
      gai_strerror(error), hostname, servicename);
   return (-1);
}
/* Try all returned addresses until one works */
for (aip = res; aip != NULL; aip = aip->ai_next) {
   /*
   * Open socket. The address type depends on what
   * getaddrinfo() gave us.
   */
   sock = socket(aip->ai_family, aip->ai_socktype, aip->ai_protocol);
   if (sock == -1) {
      perror("socket");
      freeaddrinfo(res);
      return (-1);
   }

/* Connect to the host. */
if (connect(sock, aip->ai_addr, aip->ai_addrlen) == -1) {
   perror("connect");
   (void) close(sock);
   sock = -1;
   continue;
}
break;
}
   freeaddrinfo(res);

Note that for new applications, if you write address-family-agnostic data structures, there is no need for porting.

However, when it comes to server-side programming in C/C++, there is an additional wrinkle. Namely, depending on whether your application is written for a dual-stack platform, such as Solaris or Linux, or a single-stack platform, such as Windows, you would need to structure the code differently. For server-side programming, Java shows a big advantage. You still write the same code as before:

ServerSocket server = new ServerSocket(port);
Socket s;
while (true) {
   s = server.accept();
   doClientStuff(s);
}

Now, however, if you run the code on an IPv6-enabled machine, you immediately have an IPv6-enabled service.

Here's the corresponding server C code for a dual-stack platform:

int ServSock, csock;
struct sockaddr addr, from;
...
ServSock = socket(AF_INET6, SOCK_STREAM, PF_INET6);
bind(ServSock, &addr, sizeof(addr));
do {
   csock = accept(ServSocket, &from, sizeof(from));
   doClientStuff(csock);
} while (!finished);

Notice that on a dual-stack machine, since one socket, the IPv6 socket, will be able to access both IPv4 and IPv6 protocol stacks, you only need to create one socket. Thus this server can potentially support both IPv4 and IPv6 clients.

Here's the C code for the same server for a single-stack platform:

SOCKET ServSock[FD_SETSIZE];
ADDRINFO AI0, AI1;
ServSock[0] = socket(AF_INET6, SOCK_STREAM, PF_INET6);
ServSock[1] = socket(AF_INET, SOCK_STREAM, PF_INET);
 ...
bind(ServSock[0], AI0->ai_addr, AI0->ai_addrlen);
bind(ServSock[1], AI1->ai_addr, AI1->ai_addrlen);
 ...
select(2, &SockSet, 0, 0, 0);
if (FD_ISSET(ServSocket[0], &SockSet)) {
   // IPv6 connection csock = accept(ServSocket[0], (LPSOCKADDR)&From, FromLen);
    ...
}
if (FD_ISSET(ServSocket[1], &SockSet))
   // IPv4 connection csock = accept(ServSocket[1], (LPSOCKADDR)&From, FromLen);
    ...
}

Here you need to create two server sockets, one for IPv6 stack and one for IPv4 stack. You also need to multiplex on the two sockets to listen to connections from either IPv4 or IPv6 clients.

With Java you can run any Java applications, client or server, on an IPv6-enabled platform using J2SE 1.4 or later, and that application will automagically become IPv6-enabled.

Contrasting this with legacy, native-language applications, if you wanted any C/C++ applications to be IPv6-enabled, you would need to port and recompile them.

How IPv6 Works on a Java Platform

The Java networking stack will first check whether IPv6 is supported on the underlying OS. If IPv6 is supported, it will try to use the IPv6 stack. More specifically, on dual-stack systems it will create an IPv6 socket. On separate-stack systems things are much more complicated. Java will create two sockets, one for IPv4 and one for IPv6 communication. For client-side TCP applications, once the socket is connected, the internet-protocol family type will be fixed, and the extra socket can be closed. For server-side TCP applications, since there is no way to tell from which IP family type the next client request will come, two sockets need to be
maintained. For UDP applications, both sockets will be needed for the lifetime of the communication.

Java gets the IP address from a name service.

Details on IPv6 support in Java

You don't need to know the following in order to use IPv6 in Java. But if you are curious and what to know what happens under various circumstances, the remainder of this document should provide answers.

Special IPv6 Address Types

Unspecified address (:: corresponding to 0.0.0.0 in IPv4)

This is also called anylocal or wildcard address. If a socket is bound to an IPv6 anylocal address on a dual-stack machine, it can accept both IPv6 and IPv4 traffic; if it is bound to an IPv4 (IPv4-mapped) anylocal address, it can only accept IPv4 traffic. We always try to bind to IPv6 anylocal address on a dual-stack machine unless a related system property is set to use IPv4 Stack.

When bound to ::, method ServerSocket.accept will accept connections from both IPv6 or IPv4 hosts. The Java platform API currently has no way to specify to accept connections only from IPv6 hosts.

Applications can enumerate the interfaces using NetworkInterface and bind a ServerSocketChannel to each IPv6 address, and then use a selector from the New I/O API to accept connections from these sockets.

Note: The option discussed below is introduced in Draft-ietf-ipngwg-rfc2553bis-03.txt. It will be supported in the Java 2 platform when it becomes a standard.

However, there is a new socket option that changes the above behaviour. Draft-ietf-ipngwg-rfc2553bis-03.txt has introduced a new IP level socket option, IPV6_V6ONLY. This socket option restricts AF_INET6 sockets to IPv6 communications only. Normally, AF_INET6 sockets may be used for both IPv4 and IPv6 communications. Some applications may want to restrict their use of an AF_INET6 socket to IPv6 communications only. For these applications the IPV6_V6ONLY socket option is defined. When this option is turned on, the socket can be used to send and receive IPv6 packets only. By default this option is turned off.

Loopback address (::1 corresponding to 127.0.0.1 in IPv4)

Packets with the loopback address must never be sent on a link or forwarded by an IPv6 router. There are two separate loopback addresses for IPv4 and IPv6 and they are treated as such.

IPv4 and IPv6 addresses are separate address spaces except when it comes to "::".

Compatibility address ::w.x.y.z

This is used for hosts and routers to dynamically tunnel IPv6 packets over IPv4 routing infrastructure. It is meaningful for OS kernel and routers. Java provides a utility method to test it.

IPv4-mapped address ::ffff:w.x.y.z

This is an IPv6 address that is used to represent an IPv4 address. It allows the native program to use the same address data structure and also the same socket when communicating with both IPv4 and IPv6 nodes. Thus, on a dual-stack node with IPv4-mapped address support, an IPv6 application can talk to both IPv4 and IPv6 peer. The OS will do the underlying plumbing required to send or receive an IPv4 datagram and to hand it to an IPv6 destination socket, and it will synthesize an IPv4-mapped IPv6 address when needed.

For Java, it is used for internal representation; it has no functional role. Java will never return an IPv4-mapped address. It understands IPv4-mapped address syntax, both in byte array and text representation. However, it will be converted into an IPv4 address.

IPv6-Related System Properties

On dual stack machines, system properties are provided for setting the preferred protocol stack—IPv4 or IPv6—as well as the preferred
address family types—inet4 or inet6.

IPv6 stack is preferred by default, since on a dual-stack machine IPv6 socket can talk to both IPv4 and IPv6 peers.

This setting can be changed through the java.net.preferIPv4Stack=<true|false> system property.

By default, we would prefer IPv4 addresses over IPv6 addresses, i.e., when querying the name service (e.g., DNS service), we would return Ipv4 addresses ahead of IPv6 addresses. There are two reasons for this choice:

  1. There are some applications that expect an IPv4 address textual format, i.e. "%d.%d.%d.%d". Using an IPv4 address minimizes the surprises;
  2. Using IPv4 address, we can use one call (with an IPv6 socket) to reach either a legacy IPv4-only service, or an IPv6 service (unless the IPv6 service is on a Ipv6 only node).

This setting can be changed through the system property java.net.preferIPv6Addresses=<true|false>

Dual-Stack Node

For many years, if not forever, there will be a mix of IPv6 and IPv4 nodes on the Internet. Thus compatibility with the large installed base of IPv4 nodes is crucial for the success of the transition from IPv4 to IPv6. Dual stack, defined in RFC 1933, is one of the main mechanisms for guaranteeing a smooth transition. The other mechanism is IPv6 packet tunneling, which is relevant to the JDK only through the IPv4-compatible address. The former is the most relevant piece to the JDK. A dual stack includes implementations of both versions of the Internet Protocol, IPv4 and IPv6.

A general property of a dual-stack node is that an IPv6 socket can communicate both with an IPv4 and IPv6 peer at the transport layer (TCP or UDP) . At the native level, the IPv6 socket communicates with an IPv4 peer through an IPv4-mapped IPv6 address. However, unless a socket checks for the peers address type, it won't know whether it is talking to an IPv4 or an IPv6 peer. All the internal plumbing and conversion of address types is done by the dual-protocol stack.

Note: IPv4-mapped address has significance only at the implementation of a dual-protocol stack. It is used to fake (i.e., appear in the same format as) an Ipv6 address to be handed over to an IPv6 socket. At the conceptual level it has no role; its role is limited at the Java API level. Parsing of an IPv4-mapped address is supported, but an IPv4-mapped address is never returned.

Java Application Impact

  1. There should be no change in Java application code if everything has been done appropriately. I.e., there are no direct references to IPv4 literal addresses; instead, hostnames are used.
  2. All the address or socket type information is encapsulated in the Java networking API.
  3. Through setting system properties, address type and/or socket type preferences can be set.
  4. For new applications Ipv6-specific new classes and APIs can be used.

communication scenarios:

(Nodes) | V4 Only | V4/V6 | V6 Only
V4 Only | x | x
V4/V6 | x | x | x
V6 Only | x | x

Top row and left column represent various node types attempting to communicate. An x indicates that these nodes can communicate with each other.

UDP
scenario 1:

Either host1 or host2 can be a native application.

host1 is server, host2 is client

If host2 wants to talk to host1, it will create a V6 socket. It then looks up the IP address for host1. Since host1 only has a v4 protocol stack, it will only have IPv4 records in the name lookup service. So host2 will try to reach host1 using an IPv4-mapped address. An IPv4 packet will be sent by host2, and host1 will think it is communicating with a v4 client.

host1 is client, host2 is server

If host2 is the server, it will first create a v6-type socket (by default), then it will wait for connections. Since host1 supports v4 only, it creates a v4-type socket. They resolves the name for host2. It only gets v4 address for host2, since it doesn't understand IPv6 address. So it connects to host2 using v4 address. A v4 packet will be sent on the wire. On host2, the dual stack will convert the v4 packet into a v6 packet with a v4-mapped address in it and hand it over to the v6 socket. The server application will handle it as if it is a connection from a v6 node.

Class Changes

InetAddress

This class represents an IP address. It provides address storage, name-address translation methods, address conversion methods, as well as address testing methods. In J2SE 1.4, this class is extended to support both IPv4 and IPv6 addresses. Utility methods are added to check address types and scopes. The two types of addresses, IPv4 and IPv6, can be distinguished by the Java type Inet4Address and Inet6Address.

Two new subclasses of InetAddress are created: Inet4Address and Inet6Address. V4- and V6-specific state and behaviors are implemented in these two subclasses. Due to Java's object-oriented nature, an application normally only needs to deal with InetAddress class—through polymorphism it will get the correct behavior. Only when it needs to access protocol-family-specific behaviors, such as in calling an IPv6-only method, or when it cares to know the class types of the IP address, will it ever become aware of Inet4Address and Inet6Address.

The new methods introduced are:

InetAddress:
isAnyLocalAddress
isLoopbackAddress
isLinkLocalAddress
isSiteLocalAddress
isMCGlobal
isMCNodeLocal
isMCLinkLocal
isMCSiteLocal
isMCOrgLocal
getCanonicalHostName
getByAddr

Inet6Address:
isIPv4CompatibleAddress

InetAddress and Different Naming services

Prior to 1.4, InetAddress utilized the system configured name service to resolve host names. In 1.4, we have added a Java DNS provider through JNDI for alternative name lookups. You can tell the JDK to use this provider by setting up a few system properties. These system properties are documented in the Java system properties section. In the future, we plan to provide a generic service provider framework so that you can write your own name service providers.

A Word on Serialization

All IPv4 addresses are represented in Java as Inet4Address objects. They are serialized as InetAddress objects, and deserialized from InetAddress to Inet4Address to keep backward compatibility. IPv6 addresses are represented as Inet6Address and are serialized as such.

Socket, ServerSocket, and DatagramSocket

Due to the object-oriented nature of Java, the address types and storage structures are not exposed at the socket API level, so no new APIs are needed. The existing socket APIs handle both IPv4 and IPv6 traffic.

The selection of which stack to use depends upon the following:

  1. The underlying OS support;
  2. The user's stack preference property setting.

All supported Ipv6 socket options have a IPv4 counterparts. Thus no new APIs were added to support IPv6 socket options. Instead, the old APIs are overloaded to support both V4 and V6 socket options.

MulticastSocket

Again all the socket options APIs are overloaded to support IPv6 multicast socket options.

We have added two new APIs to set/get network interfaces in addition to the existing MulticastSocket.setInterface/MulticastSocket.getInterface that takes/returns an InetAddress instance. The two existing methods are used to set or retrieve the network interface used by the current MulticastSocket to send multicast packets (i.e., equivalent to IP_MULTICAST_IF in native socket option). For IPv4, the interface was indicated by an IP address. Thus we can use the equivalent InetAddress in Java. They will continue to work with IPv6 multicast socket. However, in IPv6, according to RFC 2553, the interface should be indicated using an interface index. To better support the concept of a network interface, we introduced a new class, NetworkInterface. It encapsulate the data representing the state of the network interface, including name and IP addresses and some basic manipulation methods. Thus we have introduced two new methods for setting the outgoing interface for multicast socket: setNetworkInterface and getNetworkInterface. They take or return a NetworkInterface object. These new methods can be used with both v4 and v6 multicast.

Methods have also been added for joining and leaving a multicast group on a network interface. This was previously unavailable in the Java API.

MulticastSocket:
NetworkInterface getNetworkInterface()
setNetworkInterface(NetworkInterface netIf)
joinGroup(SocketAddress mcastaddr,NetworkInterface netIf)
leaveGroup(SocketAddress mcastaddr,NetworkInterface netIf)

URL, URI parsers

Literal IP addresses can be used in URL/URIs. However, since colon (:) is used in existing URL/URI specifications to separate host from port, using literal IPv6 representation in URL/URIs without modification will fail in parsing. Thus for specifying literal IPv6 addresses in URL/URIs, RFC 2732 was created. The parsing of URL/URI has been updated to be compliant with RFC 2732.

SocketPermission

Since SocketPermission utilizes URLs, its implementation has been updated to be compliant with RFC 2732.

codebase, used in defining a permission, is a variant of URL. As such, it should follow URL formats and conventions. RFC 2732 format is used for URL and codebase; RFC 2373 format is used everywhere else.

IPv6 Networking Properties

java.net.preferIPv4Stack (default: false)

If IPv6 is available on the operating system, the underlying native socket will be an IPv6 socket. This allows Java(tm) applications to connect too, and accept connections from, both IPv4 andIPv6 hosts.

If an application has a preference to only use IPv4 sockets, then this property can be set to true. The implication is that the application will not be able to communicate with IPv6 hosts.

java.net.preferIPv6Addresses (default: false)

If IPv6 is available on the operating system, the default preference is to prefer an IPv4-mapped address over an IPv6 address. This is for backward compatibility reasons—for example, applications that depend on access to an IPv4-only service, or applications that depend on the %d.%d.%d.%d representation of an IP address.
This property can be set to try to change the preferences to use IPv6 addresses over IPv4 addresses. This allows applications to be tested and deployed in environments where the application is expected to connect to IPv6 services.

JNDI DNS service provider settings:

sun.net.spi.nameservice.provider.<n>=<default|dns,sun|...>

Specifies the name service provider that you can use. By default, Java will use the system-configured, name-lookup mechanism, such as file, nis, etc. You can specify your own by setting this option. <n> takes the value of a positive number and it indicates the precedence order: a small number takes higher precendence over a bigger number. In 1.4 , we have provided one DNS name service provider through JNDI, which is called dns,sun.

sun.net.spi.nameservice.nameservers=<server1_ipaddr,server2_ipaddr ...>

You can specify a comma separated list of IP addresses that point to the DNS servers you want to use.

sun.net.spi.nameservice.domain=<domainname>

This property specifies the default DNS domain name, e.g., eng.sun.com.


Networking Overview

Java Networking Overview

The Java Networking API (java.net) provides the interfaces/classes for the following functions:

  • Addressing
  • Making TCP connections
  • Sending/Receiving Datagram Packets via UDP
  • Locating/Identifying Network Resources
  • Security
    • Authentication
    • Permissions

The goal of this document is to provide a high-level overview of the facilities the java.net package provides. For details about interfaces, classes, or factories, see the networking API. For basic networking concepts, see Trail: Custom Networking in the Java Tutorial.

Addressing

java.net provides the following addressing-related classes:

  • InetAddress
  • Inet4Address
  • Inet6Address
  • SocketAddress
  • InetSocketAddress

For IP addressing, three classes are provided: InetAddress, Inet4Address, and Inet6Address. InetAddress represents an IP address, which is either a 32- or 128-bit unsigned number used by IP, the lower-level protocol on which protocols like TCP and UDP are built. To represent 32-bit IPv4 address, Inet4Address is provided. (An IPv4 address has the familiar form nnn.nnn.nnn.nnn, where n is an integer; e.g., 129.250.35.250). It is a subclass of InetAddress. To represent 128-bit IPv6 addresses, Inet6Address is provided. It is also a subclass of InetAddress.

Flow chart showing the logic flows from InetAddress to Inet4Address and Inet6Address

For socket addressing, two classes are provided: SocketAddress and InetSocketAddress. SocketAddress is an abstract socket address, independent of a specific protocol. It is intended for subclassing for a specific protocol. InetSocketAddress below is an example. InetSocketAddress is a subclass of SocketAddress; it represents an IP socket address. It can include an IP address (e.g., 129.250.35.250) and port (e.g., 80); a hostname (e.g., coastnews.com) and port (e.g., 1000); or port only (e.g., 1010). In the latter case, a wildcard IP address is assumed.

Diagram showing the logic flows between SocketAddress and InetSocketAddress

Making TCP Connections

These classes are related to making normal TCP connections:

  • ServerSocket
  • Socket

For simple connections between a client and a server, ServerSocket and Socket are all that you will probably need.

ServerSocket represents the socket on a server that waits and listens for requests for service from a client. Socket represents the endpoints for communication between a server and a client. When a server gets a request for service, it creates a Socket for communication with the client and continues to listen for other requests on the ServerSocket. The client also creates a Socket for communication with the server. The sequence is shown below:

See long description [D]

Once the connection is established, getInputStream() and getOutputSteam() may be used in communication between the sockets

Sending/Receiving Datagram Packets via UDP

The following are related to sending and receiving datagram packets via UDP.

  • DatagramPacket
  • DatagramSocket

DatagramPacket represents a datagram packet. Datagram packets are used for connectionless delivery and normally include destination address and port information. DatagramSocket is a socket used for sending and receiving datagram packets over a network via UDP. A DatagramPacket is sent from a DatagramSocket by calling the send(...) method of DatagramSocket with DatagramPacket as the argument: send(DatagramPacket dp). receive(DatagramPacket dp) is use for receiving a DatagramPacket. (The MulticastSocket class may be used for sending/receiving a DatagramPacket to a mulitcast group. It is a subclass of DatagramSocket that adds functionality for multicasting.)

See long description [D]

Locating/Identifying Network Resources

These classes are related to locating or identifying network resources:

  • URI
  • URL
  • URLClassLoader
  • URLConnection
  • URLStreamHandler
  • HttpURLConnection
  • JarURLConnection

The most commonly used classes are URI, URL, URLConnection, and HttpURLConnection.

URI represents a Uniform Resource Identifier for a resource; it is an identifier for a resource but not necessarily a locator for that resource. URL represents a Uniform Resource Locator for a resource. URLs are a subset of URIs, though the class URL is not a subclass of the URI class. In short, a URL tells how to access the resource, while a URI may or may not. The Uniform Resource Name (URN) is another subset of URI. No Java class exists for it.

Diagram showing URL and URN as subclasses of URI.

URLConnection is the abstract superclass of all classes that represent a connection between an application and a network resource identified by a URL. Given a URL and hence a protocol, URL.openConnection() returns an instance of the appropriate implementation of URLConnection for the protocol. (The protocol is known from the URL.) The instance provides the means—URLConnection.connect()—to actually open the connection and access the URL.

See long description [D]

HttpURLConnection is the most commonly used implementation of URLConnection. It is for http protocol, the protocol used for accessing content on web servers. In the above diagram, if the access protocol for the URL were http, then an instance of HttpURLConnection would be returned by the openConnection() method.

Security

Security includes authentication- and permissions-related classes. Authentication relates to user authentication and involves username and password checking. Authentication of a user may be required in a number of situations, such as when a user tries to access a URL. Permissions relate to what actions may be performed; e.g., unless the NetPermission object "setDefaultAuthenticator" exists, then invoking the method Authenticator.setDefault(Authenticator a) will cause a security exception.

Authentication

Some proxies and origin servers require authentication information, using authentication schemes such as BASIC and DIGEST. For instance, when connecting with http via a proxy and the proxy requires authentication, we call the Authenticator class to obtain usernames, passwords, and other items needed to authenticate. The following classes relate to authentication:

  • Authenticator
  • PasswordAuthentication

In addition to methods for user authentication, the abstract class Authenticator also has methods for querying about the authentication being requested (see getRequestingXXX()). It is typically subclassed and an instance of the subclass is registered with the system by calling setDefault(Authenticator a). (Note that if there is a security manager, it checks to see that the security policy permits the NetPermission "setDefaultAthenticator".) Then, when the system requires authentication, it will call a method such as requestPasswordAuthentication().

PasswordAuthentication is simply a data holder for a user name and a password.

Permissions

  • SocketPermission
  • NetPermission

A SocketPermission consists of a host, with optional port range, and a set of actions that may be performed on that host—connect, accept, listen and/or resolve. It includes methods to determine if one SocketPermission is equal to another or implies another Permission. A SocketPermission may be included in a PermissionCollection for easy checking if a permission exists.

NetPermission is a class for various named network permissions. Currently there are three: setDefaultAuthenticator, as mentioned above; requestPasswordAuthentication; and specifyStreamHandler. A NetPermission may be included in a PermissionCollection for easy checking if a permission exists.

For more information about permissions, see http://java.sun.com/j2se/1.5.0/docs/guide/security/permissions.html.


Packed Class Archive Specification

Pack200: A Packed Class Deployment Format For Javatm Applications

JSR-200 Public Draft Specification

Contents

  • 1. Introduction
  • 2. Archive Inputs
  • 3. Archive File Structure Summary
  • 4. Introduction to Integer Encodings
    • 4.1. Integer Encoding Schema
  • 5. Band Definitions
    • 5.1. Archive Segmentation
    • 5.2. Archive Header
      • 5.2.1. Archive Options and File Properties
      • 5.2.2. Archive Entity Counts and Class Format
    • 5.3. Constant Pools
      • 5.3.1. Scalar Constants
      • 5.3.2. Utf8 Constants
      • 5.3.3. Type Signatures
      • 5.3.4. Tuple Constants
    • 5.4. File Attributes
    • 5.5. Flags and Attributes
      • 5.5.1. Assignment of Flag Bits to Attributes
      • 5.5.2. Attribute Layout Definitions
      • 5.5.3. Recursive Layouts
      • 5.5.4. Default Attribute Layouts
      • 5.5.5. Stack Map Layouts
      • 5.5.6. Metadata Layouts
      • 5.5.7. Unusual Layout Usages
    • 5.6. Source File Abbreviation
    • 5.7. Nested Classes
    • 5.8. Class Schema
    • 5.9. Attribute Bands
      • 5.9.1. Metadata Transmission
    • 5.10. Bytecode Instructions
  • 6. Specification of Band Coding
    • 6.1. Encoding of Small Whole Numbers
      • 6.1.1. Scheme of Multiple Codings
      • 6.1.2. Definition of Encoding Byte Sequences
      • 6.1.3. Definition of Decoded Whole Number Values
    • 6.2. Encoding of Signed Integers
      • 6.2.1. Further Discussion of Sign Conversion
    • 6.3. Attributes of Codings
    • 6.4. Encoding of Correlated Sequences
    • 6.5. Encodings of Uncorrelated Values
      • 6.5.1. Table of Favorites
      • 6.5.2. Sequence of Tokens
      • 6.5.3. Sequence of Unfavored Values
    • 6.6. Adaptive Encodings
    • 6.7. Meta-Coding
      • 6.7.1. Coding Specifier Structure
      • 6.7.2. Coding Specifier Semantics
      • 6.7.3. Coding Specifier Meta-Encoding
      • 6.7.4. Canonical BHSD Codings
  • 7. Stability of Decompressor Output
    • 7.1. Ordering of Attribute Lists
    • 7.2. Ordering of Constant Pools
  • 8. Appendixes
    • 8.1. Appendix: List of Bands
    • 8.2. Appendix: Pseudo-Code Illustrations
      • 8.2.1. Representation of cp_Utf8 Constant Pool
      • 8.2.2. Representation of cp_Signature Constant Pool
      • 8.2.3. Representation of Byte Offsets
      • 8.2.4. Representation of Predictable Nested Class Names
    • 8.3. Appendix: Design FAQ
      • 8.3.1. General Questions

1. Introduction

This document specifies an archive format called "Pack200". It is optimized for applications written in the Javatm programming language. Such applications are usually delivered as collections of classes, sometimes with associated resource files.

This format allows any number (from one to hundreds of thousands) of Java classes to be encoded by a compressor, transmitted compactly in a single block of bytes, and decoded by a decompressor into equivalent Java class files. Because it can also represent class resources and other "side files", it can serve as an alternative to the JAR archive for some deployment tasks, notably downloading Java applications.

The Pack200 format can decrease the size of a Java application by a factor of seven to nine, compared with an equivalent JAR containing uncompressed ("stored") class files. By contrast, using the zip DEFLATE algorithm integral to JAR and ZIP archives gains a factor of two. The undocumented "crunch" mechanism, used to deploy SDK downloads in the past, gains a corresponding factor of five to six. Note that all these figures assume and incorporate the effects of a post-pass with DEFLATE or a similar off-the-shelf compression algorithm. (DEFLATE is documented here.)

The main motivation for this format is to decrease disk and bandwidth requirements for Java application packaging, transmission, and delivery. An earlier version has been used to package the downloads for Java 2 Standard Edition release 1.4.1 and 1.4.2 (code names "Hopper" and "Mantis").

This format is not intended for fast loading into a virtual machine, and does not attempt to improve start-up speed or memory footprint in running Java applications. The heavy engineering requirements on a directly loadable file format would make optimal compression impossible. The decompressor of an aggressively compressed file will have a complex job to do, and must be allowed memory and CPU time to do this job. We assume that Pack200 archives will be unpacked on the same classes of machine that run Java SE and J2EE applications.

This format is batch-oriented, optimized for packaging and transmission of Java classes. It does not support random access of individually stored classes. In order to emphasize the sequential nature of this archive format, we will use the verb transmit, rather than store, to refer to the formatting of data produced by a compressor and accepted by a decompressor.

This format does not attempt to duplicate work performed by DEFLATE or other byte-oriented compression algorithms. Typically, tools using Pack200 will further compress archives by storing them in ZIP files or using some other compression technique. The presence of such a post-pass compressor is an assumption made by the design of Pack200.

This specification is complex, and may seen to some readers needlessly complex. The design decisions reflected here have been motivated by extensive testing and experimentation with actual Java class files found in real products. An attempt to remove complexity from this specification is likely also to remove measurably significant compression efficiency.

2. Archive Inputs

A Pack200 archive, like a JAR file, carries images of class files and other ("resource") files arranged in a hierarchical directory structure.

No special compression or transformation is performed on any file other than class files, other than (possibly) reordering them by file type. The post-pass compressor is assumed to provide adequate compression on those spans of the archive which carry images of non-class files.

Classes are represented in a form which suppresses their individual constant pools, in favor of a large constant pool that serves the entire archive. Thus, when a class file is extracted from a Pack200 archive, a new constant pool will be created for it, and all constant pool references adjusted. This does not change the semantics of the class, but it will generally modify the bitwise image of the file, and perhaps even its size, as unused constant pool entries are deleted.

Note that every class file must be fully parsed by the compressor, so that all constant pool indexes may be found and (later) renumbered. This requirement applies to any class, field, method, or code attribute which refers to the constant. The Pack200 format supports a moderate range of attributes. A modest variety of new attribute layouts may be declared to the compressor, and the Pack200 format provides a place to transmit such layouts for use by decompressors.

3. Archive File Structure Summary

The archive file consists of a short archive header, followed by a number of independent file sections called bands. (There are about 100 of them; this number can vary.) Each band transmits an array of small integers, called the elements of the band. After the archive header, the archive consists only of bands.

Logically, a band is an implicitly sized array of 32-bit unsigned integers. However, it is rare for a band to physically require more than one or two bytes per element, since element encodings are chosen to transmit the actual band values more compactly.

A band has no fixed header, not even an indication of its size. The count of band elements is deduced by the decompressor from the contents of previous bands, or (ultimately) from the archive header.

The elements of any given band have a common meaning and role. For example, the names of all transmitted classes are in a single band, while all the class field counts are in a different band. Each band is transmitted as a contiguous segment of bytes within the archive. This contiguity is the main reason that a Pack200 archive, while compact to begin with, is very compressible by utilities like zip.

In some bands, each element helps describe one object. For example, each class is associated with a count of fields, which is given in the archive as a corresponding value in the class_field_count band. In other bands, one object may be described by a run of zero or more elements in a band. For example, the interfaces implemented by a class are given in the archive as a corresponding run of zero or more values in the class_interface band; each such value is an index referring to a single class.

A very few bands (less than 10) contain non-homogeneous bytes, such as the images of resource files. These few are called byte bands. Many of the bands contain references into the constant pool. Some contain access modifier flags and related bits. One band, called the char band, contains string characters in a specially chosen encoding called "CHAR3" (somewhat akin to UTF8, but not identical). The rest of the bands transmit integers with a variety of other interpretations.

One of the integer bands (cp_Utf8_big_chars) carries the characters of a single CONSTANT_Utf8 string selected for special treatment. Uniquely, this band is repeated zero or more times, depending on how many strings are selected for this special treatment. (These specially-transmitted "big strings" are explained later in this document.)

Most bands have an easily understood function, such as transmitting the number of methods in a class, or the name of a field, or the operand of a "getfield" bytecode instruction.

Except for the special case of byte bands, a band is never considered as a sized span of bytes, but rather as a counted series of elements which are encoded integers. Since integer encodings are typically variable-sized (when regarded as byte sequences), there is no firm rule for deriving a band's byte size from its element count. Indeed, finding the end of a band requires that it be parsed byte-by-byte.

4. Introduction to Integer Encodings

Each band uses one or more coding tactics to encode its elements as sequences of bytes. (The post-pass compressor is expected to turn these bytes into bit sequences, but its actions are not specified by this document.) The Pack200 compressor is free to choose and vary encoding tactics used by a band. The encoding tactics used in one band are independent of those used in other bands. The space of supported encoding tactics is an important part of the Pack200 specification. The present section introduces these encodings, which are defined in detail later in this document.

As one might expect, byte bands (which encode bytewise data such as the resource file images) encode their integers as unsigned 8-bit bytes. This encoding is named BYTE1 in this specification. (Compare the type "u1" in the class file definition.)

Other bands have values with a much larger dynamic range, including (in a few cases) negative numbers, and/or values all the way up to the 32-bit unsigned maximum. Most of these encodings are variable-length, in the expectation that the typical band element will be relatively small in magnitude, even though some elements may be large and require more bytes to represent. Some bands that are expected to exhibit strong correlations in their element sequences are encoded as successive differences (delta encoding) rather than absolute numeric values.

Each band is associated with a primary encoding which the compressor and decompressor agree to use when transmitting elements of that band. Except in the byte bands, the compressor can optionally specify a secondary encoding to use instead of the primary encoding. In essence, the band's encoding defaults to the primary, unless there is an explicitly declared secondary. This allows the Pack200 format to adapt more closely to the actual statistics of band elements.

For example, most bands, such as those holding counts and sizes, have a primary encoding called UNSIGNED5. This is a general-purpose unsigned encoding which represents values in the range [0..191] as a single byte, and scales up to a maximum size of five bytes for numbers larger than about fifty million. However, if a band contains only numbers in the range [0,255], the BYTE1 encoding is more compact, and the compressor is allowed to instruct the decompressor to use this instead.

When the compressor specifies a secondary encoding, it must emit an optional band coding specifier, which is described elsewhere. A customized encoding method often saves many bytes, if it matches more precisely the actual dynamic range of the band's element values.

4.1. Integer Encoding Schema

The Pack200 format is based on a schema of integer encoding systems, parameterized by four numbers (B,H,S,D). From this infinite set, about 10 selected encodings serve as primary encodings for bands, and about 100 more serve as optional encodings. The system of (B,H,S,D) encodings is explained at length in a later section. For the present purposes, a brief introduction will suffice.

The parameter B (1<=B<=5) is="is" the="the" maximum="maximum" length="length" in="in" bytes="bytes" of="of" the="the" encoding="encoding" of="of" a="a" single="single" integer.="integer." Less="Less" significant="significant" bits="bits" are="are" always="always" encoded="encoded" in="in" earlier="earlier" bytes.="bytes." The parameter H (1<=H<=256) is="is" the="the" radix="radix" of="of" the="the" encoding.="encoding." it="it" also="also" determines="determines" the="the" conditions="conditions" under="under" which="which" the="the" encoding's="encoding's" byte="byte" sequences="sequences" terminate.="terminate." The="The" co-parameter="co-parameter" L="L" (0<="L<=255)" is="is" defined="defined" as="as" (256-H).="(256-H)." Encoded="Encoded" byte="byte" sequences="sequences" are="are" allowed="allowed" to="to" contain="contain" only="only" one="one" byte="byte" with="with" a="a" value="value" less="less" than="than" L,="L," and="and" that="that" byte="byte" must="must" be="be" the="the" last="last" in="in" the="the" sequence.="sequence." Thus,="Thus," larger="larger" H="H" values="values" make="make" for="for" longer="longer" average="average" encoding="encoding" lengths.="lengths." If="If" H="H" is="is" 256="256" and="and" L="L" is="is" zero,="zero," then="then" the="the" encoding="encoding" method="method" is="is" fixed-length,="fixed-length," because="because" all="all" encodings="encodings" must="must" be="be" exactly="exactly" B="B" bytes="bytes" long.="long." The parameter S (0<=S<=2) determines="determines" whether="whether" and="and" how="how" the="the" encoding="encoding" represents="represents" signed="signed" numbers.="numbers." (More="(More" precisely,="precisely," since="since" band="band" elements="elements" are="are" conventionally="conventionally" regarded="regarded" as="as" unsigned="unsigned" 32-bit="32-bit" integers,="integers," S="S" determines="determines" the="the" coding="coding" of="of" band="band" elements="elements" larger="larger" than="than" the="the" largest="largest" 31-bit="31-bit" unsigned="unsigned" number,="number," 2147483647.="2147483647." But="But" we="we" shall="shall" continue="continue" to="to" refer="refer" to="to" such="such" numbers="numbers" as="as" negative,="negative," where="where" the="the" distinction="distinction" is="is" irrelevant.)="irrelevant.)" S="S" denotes="denotes" the="the" number="number" of="of" least-significant="least-significant" bits="bits" which="which" serve="serve" as="as" a="a" sign="sign" bit.="bit." If="If" S="S" is="is" zero,="zero," the="the" numbers="numbers" are="are" unsigned.="unsigned." If="If" S="S" is="is" one,="one," the="the" LSB="LSB" of="of" the="the" unsigned="unsigned" number="number" is="is" exclusive-ored="exclusive-ored" into="into" the="the" right-shifted="right-shifted" remainder="remainder" of="of" the="the" unsigned="unsigned" number="number" to="to" produce="produce" a="a" corresponding="corresponding" signed="signed" number.="number." If="If" S="S" is="is" more="more" than="than" one,="one," the="the" signed="signed" number="number" produced="produced" is="is" negative="negative" only="only" if="if" all="all" S="S" least-significant="least-significant" bits="bits" are="are" set,="set," and="and" otherwise="otherwise" these="these" low="low" bits="bits" contribute="contribute" to="to" the="the" positive="positive" magnitude="magnitude" of="of" the="the" integer.="integer." This="This" representation="representation" is="is" efficient="efficient" for="for" bands="bands" containing="containing" mostly-positive="mostly-positive" numbers,="numbers," such="such" as="as" bytecode="bytecode" branch="branch" offsets.="offsets." The="The" interpretation="interpretation" of="of" sign="sign" bits="bits" is="is" more="more" precisely="precisely" described="described" elsewhere.

The parameter D (0<=D<=1) determines="determines" whether="whether" the="the" band="band" transmits="transmits" its="its" data="data" via="via" successive="successive" differences="differences" (i.e.,="(i.e.," delta="delta" encoding).="encoding)." In="In" writing="writing" these="these" encodings,="encodings," the="the" parameters="parameters" S="S" and="and" D="D" may="may" be="be" omitted="omitted" if="if" both="both" are="are" zero,="zero," and="and" D="D" may="may" be="be" omitted="omitted" if="if" zero.="zero." Thus, the encoding (1,256,0,0), also written as (1,256), represents numbers as unsigned bytes, while (4,256) represents numbers as unsigned little-endian 32-bit integers. The encoding (1,256,1) maps single bytes to numbers in the range [-128,127]. The encoding (1,256,1,1) expresses any sequence of numbers whose successive differences are in the range [-128,127] (and whose first number is in that range).

The very common encoding UNSIGNED5 can represent the full unsigned range of 32-bit integers. A byte sequence in this encoding consists either of four bytes less than 192 followed by an arbitrary byte, or else from zero to three bytes less than 192 followed by a byte greater than or equal to 192. The unsigned value is formed by scaling each succeeding byte by successive powers of the radix 64, and adding all the scaled byte values together.
value | byte 0 | byte 1 | byte 2 | byte 3 | byte 4
1 | 1
191 | 191
192 | 192 | 0
193 | 193 | 0
255 | 255 | 0
256 | 192 | 1
512 | 192 | 5
1024 | 192 | 13
2048 | 192 | 29
12479 | 255 | 191
12480 | 192 | 192 | 0
798911 | 255 | 255 | 191
798912 | 192 | 192 | 192 | 0
51130559 | 255 | 255 | 255 | 191
51130560 | 192 | 192 | 192 | 192 | 0
0xFFFFFFFF | 255 | 252 | 252 | 252 | 252

Here is the set of primary encodings used by at least one band:
Type | Name | Purpose
(1,256) | BYTE1 | bytes
(3,128) | CHAR3 | Java characters
(5,4) | BCI5 | bytecode positions
(5,4,2) | BRANCH5 | bytecode branch offsets
(5,64) | UNSIGNED5 | general unsigned ints
(5,64,1) | SIGNED5 | general signed ints
(5,64,0,1) | UDELTA5 | monotonic sequences
(5,64,1,1) | DELTA5 | autocorrelated sequences
(5,64,2,1) | MDELTA5 | mostly monotonic sequences

5. Band Definitions

The file as a whole consists of about 200 bands in four major groups. After a header, the constant pool contents come first, followed by most of the class schema, followed by a consolidation of all attribute information (for classes, fields, methods, codes, and the archive as a whole), and ending with bytecodes for all methods.

Rather than describe the bands in a long and dull sequence, we use a simple, non-recursive grammar to present them in an organized fashion. This grammar roughly parallels the grammar of a class file:

  pack200_segment:
        segment_header
        *band_headers :BYTE1
        cp_bands
        attr_definition_bands
        ic_bands
        class_bands
        bc_bands
        file_bands

The terminals of this grammar are scalars and bands. To make the terminals easier to recognize, scalar names begin with pound sign "#" and band names begin with a star "*". A scalar is an encoded integer (or a small fixed number of them) which appears within the header of the archive file. When a scalar is mentioned in the grammar, it is followed by a colon and the encoding and bracketed count of the scalar value(s). Whenever a band is mentioned, it is followed by a colon and its primary encoding, followed by a comment in square brackets indicating its length. If the band encodes references into some other data structure, such as a constant pool, that structure is mentioned as a comment in parentheses. If the references are allowed to be null, that fact is mentioned also.

Here is an example:

  example_non_terminal:
        other_non_terminal
        #single_scalar_integer :UNSIGNED5[1]
        #four_byte_scalar :BYTE1[4]
        *band_of_integers :UNSIGNED5 [#integer_count]
        *band_of_method_references :UNSIGNED5 [SUM(*ref_counts)] (cp_Method)
        *band_of_strings_and_nulls :UNSIGNED5 [...] (null or cp_String)

Many of the band lengths are simply references to previous scalars (such as [#class_count]) or sums of previous bands which transmit counts (e.g., [SUM(*class_method_count)]). These bracketed lengths must be regarded as comments in the grammar, since the text of the specification defines band lengths verbally. Band counts which cannot be briefly summarized as sometimes specified in a partial expression which contains an ellipsis.

Occasionally we use additional grammatical notations. We use the ordinary regular expression operators (X | Y) means a match for either X or Y, (X)* means any number of matches for X, (X)+ means one or more matches for X, and (X)? means either a match for X or nothing. In one case, where a band may have several instances, the expression (band1) ** length(band2) means that there are as many instances of band1 as there are elements in band2. Likewise, in three cases, the expression (band1) ** #scalar indicates that there are zero or one instances of band1 according to the value (zero or one, respectively) of the boolean scalar value.

5.1. Archive Segmentation

The entire Pack200 archive format may be repeated one or more times in a transmission to the decompressor. In this case, each complete set of transmitted bands bands is viewed as a segment of the whole transmission. The decompressor is required to accept multiple segments, and to process each segment independently in order. The output files resulting from each segment are accumulated in order. If the decompressor is producing a JAR file, multiple segments must be accumulated into one output JAR file, whose elements are made up of the respective elements transmitted in each segment, in order.
  pack200_archive:
        (pack200_segment)+
Note that each segment begins anew with the Pack200 magic number and version numbers.

(With one caveat, this means that Pack200 archives may be concatenated with the natural meaning of combining the archives they represent. As will be seen below, if the #archive_size field is not present in each segment header, it must be inserted before another segment is appended, so that the decompressor can find the end of each segment. The segment header format is such that this adjustment can be made easily.)

When combined with a streaming transport layer, segmentation provides a way for a compressor to decrease latency or to decrease the decompressor's memory requirements, at a cost in compressor efficiency.

Segmentation can also help solve a scaling problem with very large archives (of many tens of megabytes), in which the width of indexes into the combined global constant pools can grow beyond the benefits of global constant sharing. By starting a new segment, the compressor resets the decompressor's constant pools, clearing out useless constants, at the cost of restating constants that are still in use. (The trade-offs are similar in flavor to the design of copying garbage collectors.)

5.2. Archive Header

The header consists of a magic number and version information, in a format exactly parallel to the Java class file format. However, besides the magic number, there are no other big-endian integers in the Pack200 format. All integer encodings in bands present arithmetically less-significant bits first.

Only the archive magic numbers (the first four bytes of the segment header) are fixed in size. All other archive structures are variable in size and must therefore be parsed sequentially. Generally speaking, decompressors must perform two passes over each segment of the archive, one to size and parse the bands, and one to sequentially extract information from the bands into each JAR element in the output.

  segment_header:
        archive_magic archive_header

  archive_magic:
        #archive_magic_word :BYTE1[4]

  archive_header:
        #archive_minver :UNSIGNED5[1]
        #archive_majver :UNSIGNED5[1]
        #archive_options :UNSIGNED5[1]
        (archive_file_counts) ** (#have_file_headers)
        (archive_special_counts) ** (#have_special_formats)
        cp_counts
        class_counts

  archive_file_counts:
        #archive_size_hi :UNSIGNED5[1]
        #archive_size_lo :UNSIGNED5[1]
        #archive_next_count :UNSIGNED5[1]
        #archive_modtime :UNSIGNED5[1]
        #file_count :UNSIGNED5[1]

The archive_magic_word consists of the four bytes 0xCA, 0xFE, 0xD0, 0x0D. The #archive_minver must be the number 1. The #archive_majver must be the number 160. Both of the latter two values may be incremented in the future to reflect small revisions in this file format. Note that in a previous version of this standard, the minor and major version numbers were 7 and 150.

The header also contains initial counts of constant pool entries and other "top-level" entities. All of these counts are given in UNSIGNED5 format. Some of these counts are conditionally present, controlled by bits in the #archive_options word. The rule for a missing header value (and for missing values in general unless otherwise specified) is that the decompressor must behave as if it had received an explicit zero value.

5.2.1. Archive Options and File Properties
The #archive_options word is interpreted bitwise. Certain bits are given symbolic names as follows, where the LSB is numbered as bit zero:
Bit | Name | Meaning if set in #archive_options
0 | have_special_formats | archive_special_counts contains counts
1 | have_cp_numbers | cp_number_counts contains counts
2 | have_all_code_flags | code_flags_lo contains an element for every code
3 |  | (unused, must be zero)
4 | have_file_headers | archive_file_counts contains counts
5 | deflate_hint | request compressed JAR file for all elements
6 | have_file_modtime | file_modtime contains modtimes
7 | have_file_options | file_options contains option bits
8 | have_file_size_hi | file_size_hi contains high-order size words
9 | have_class_flags_hi | class_flags_hi contains extra attribute flags
10 | have_field_flags_hi | field_flags_hi contains extra attribute flags
11 | have_method_flags_hi | method_flags_hi contains extra attribute flags
12 | have_code_flags_hi | code_flags_hi contains extra attribute flags
13 |  | (unused, must be zero)
... |  | (unused, must be zero)
31 |  | (unused, must be zero)

If have_special_formats (the LSB) is set, the band archive_special_counts will have two elements, as specified in the grammar. Otherwise this band will have zero elements. Similarly, if have_cp_numbers is set, the band cp_number_counts will have four elements, as specified in the grammar. Otherwise this band will have zero elements. If have_all_code_flags is set, the band code_flags must contain one element for every Code attribute. Otherwise this band may have fewer elements. (This option is useful when Code attributes are rich in sub-attributes, perhaps because the JAR contains large amounts of debugging information.) If have_file_headers is set, the band archive_file_counts will have five elements, as specified in the grammar. Otherwise this band will have zero elements. If deflate_hint is set, the decompressor is requested (but not required) to reduce the size of its output. For example, if it produces a JAR file, it may deflate the JAR elements. If the option have_file_modtime (or have_file_options, have_file_size_hi, have_class_flags_hi, have_field_flags_hi, have_method_flags_hi, have_code_flags_hi, respectively) is set, the corresponding band file_modtime (or file_options, file_size_hi, class_flags_hi, field_flags_hi, method_flags_hi, code_flags_hi, respectively) may be non-empty, as specified below. Otherwise that band will have zero elements. Other bits in the archive options must be zero and are reserved for future use.

Immediately after the #archive_options word is a pair of 32-bit numbers which together form a 64-bit length that helps decompressors easily buffer incoming data up to the end of the archive segment without reading beyond the segment. The value #archive_size is the unsigned 64-bit value composed of the unsigned 32-bit words #archive_size_lo and #archive_size_hi, where the former value is the low-order 32-bit word and the latter value is the high-order 32-bit word. The value #archive_size is either zero or declares the number of bytes in the archive segment, starting immediately after #archive_size_lo and before #archive_next_count and ending with the last band, the *file_bits band. (That is, a non-zero size includes the size of #archive_next_count, *file_bits, and everything in between.) This value is redundant, but if non-zero must be correctly supplied by any compressor. If the archive segment is transmitted as part of a stream, and if other data (such as additional segments) follow the archive, the #archive_size value must not be zero. Although it may be completely ignored by the decompressor, this value may help some decompressors to buffer their inputs more efficiently.

Immediately after #archive_size is another value #archive_next_count which estimates the number of archive segments immediately following the current one. This number need not be correct, and may always be zero. It is intended to provide decompressors with a hint as to the amount of remaining decompression work to do. (Such hints are routinely displayed in progress bars.)

If the #archive_modtime value is non-zero, the decompressor is requested (but not required) to adjust the system-specific modification time for its output. For example, if the decompressor produces a JAR file, it may set the modification date of each JAR element, or of the JAR file itself, to that date, in the absence of any more specific directive, such a non-zero file_modtime value. The #archive_modtime value is interpreted as the number of seconds since the epoch used by System.currentTimeMillis, which is 1/1/1970, 00:00:00 GMT. However, the special value zero is reserved to indicate the absence of any modification time for the archive as a whole. A decompressor may supply an arbitrary value in place of a missing archive modification time. If this is done, and if file_modtime values are present, those values are interpreted relative to modification time supplied for #archive_modtime by the compressor.

The #file_count value gives the number of files which are described in detail by the archive. Note that a class file which is simple enough (as described below) does not need to be described as a file, because it is enough that the class itself is transmitted. Therefore, #file_count may be less than the number of transmitted classes. (This latter number is called #class_count.) On the other hand, transmitted files do not need to contain classes, so that #file_count can also be greater than the number of classes.

5.2.2. Archive Entity Counts and Class Format
The archive file specifies twelve sets of constants called "constant pools". (These structures are analogous, but not identical, to a similarly named structure in class files.) These constant pools are described in detail in the next section.

The cardinality of each constant pool is given in UNSIGNED5 format in the cp_counts structure of the archive header:

  cp_counts:
        #cp_Utf8_count :UNSIGNED5[1]
        (cp_number_counts) ** (#have_cp_numbers)
        #cp_String_count :UNSIGNED5[1]
        #cp_Class_count :UNSIGNED5[1]
        #cp_Signature_count :UNSIGNED5[1]
        #cp_Descr_count :UNSIGNED5[1]
        #cp_Field_count :UNSIGNED5[1]
        #cp_Method_count :UNSIGNED5[1]
        #cp_Imethod_count :UNSIGNED5[1]

  cp_number_counts:
        #cp_Int_count :UNSIGNED5[1]
        #cp_Float_count :UNSIGNED5[1]
        #cp_Long_count :UNSIGNED5[1]
        #cp_Double_count :UNSIGNED5[1]

  archive_special_counts:
        #band_headers_size :UNSIGNED5[1]
        #attr_definition_count :UNSIGNED5[1]

  class_counts:
        #ic_count :UNSIGNED5[1]
        #default_class_minver :UNSIGNED5[1]
        #default_class_majver :UNSIGNED5[1]
        #class_count :UNSIGNED5[1]
The order in which these counts occur parallels the order in which the constant pools themselves are transmitted in the archive. This order is called the definition order of the constant pools.

The four numeric constant pools are sized by cp_number_counts. They specify numbers used occasionally by ldc bytecodes. Because a minority of classes actually use such bytecodes, the sizes are optional, under the control of #have_cp_numbers.

Every class file has a header that includes magic number and a minor and major version numbers. The magic number (0xCAFEBABE), being a fixed constant, is not transmitted in the Pack200 archive. However, the version numbers, which can vary somewhat, must be recorded.

In the expectation that particular version numbers will be prevalent, the archive header transmits default major and minor version numbers. Both of these numbers are given in UNSIGNED5 format.

Individual classes in the archive (as noted below) may optionally specify their own version numbers in a pseudo-attribute which overrides the #default_class_minver and #default_class_majver given in the archive header.

The count #band_headers_size gives the size in bytes of band_headers. The format of these bytes, which help define band coding specifiers for secondary codings, will be discussed much later, in the section on meta-coding.

The archive header also specifies the number of attribute types (#attr_definition_count), class definitions (#class_count), nested class declarations (#ic_count). These numbers are used to size various other bands, as noted in the definition of those bands.

The arithmetic sum of all 12 constant pool counts must be less than the value 536870912 (2^29). A compressor is forbidden to transmit an archive for which the sum reaches or exceeds this limit. This constraint is intended to allow decompressors to use, internally, a unified numbering of constants, even if certain constants (such as demangled inner class names or implicit SourceFile names) must be added on the fly during decompression to the constant pool.

Note on implementation: Because cp_counts transmits as many as 12 numbers, there are as many as 26 32-bit integers transmitted in the archive header. The segment header contains three optional sub-bands, containing two, five, and four values. The minimum size of the segment_header is therefore 19 bytes and its hypothetical maximum is 134 bytes. Moreover, a decompressor which wished to avoid any spurious read-ahead could read and buffer an initial block of 19 bytes, which would be certain to contain the #archive_size fields. (This assumes that the version numbers are small, as they are.) It could then immediately parse enough information to determine how many additional bytes of buffer storage would be required to scan the rest of the archive, at least up to the resource file images. By the time the resource file images in *file_bits must be parsed, the decompressor will have already read the *file_size bands, and will be able to remove any uncertainty originally present in #archive_size. (If the #archive_size fields are zero, the decompressor may be forced to read blindly up to the end of all data on the input channel in order to parse the archive.)

5.3. Constant Pools

There are twelve independent constant pools, eleven of which correspond directly to eleven types of constants in the Java class file format. In the Pack200 archive format, they are organized in a fixed logical ordering called their definition order. This order determines their presentation in the archive's band structure, and also the construction of certain constant numberings.

The constant pools consolidate the information in the constant pools of all input class files. Each constant pool contains a single type of constant value. Each of the eleven constant pool types found in class files is placed in its own constant pool. A twelfth pool holds signatures, which in class files are UTF8 strings that represent method and field types, but in Pack200 archives are a separately compressed data type.

The following table gives the twelve constant pools in their definition order. It also defines their correspondence with the constant types found in the Java class file format.
Name | class file element | class file tag | Purpose
cp_Utf8 | ConstantPool.cpUtf8 | CONSTANT_Utf8 | basic string data
cp_Int | ConstantPool.cpInteger | CONSTANT_Integer | int constant
cp_Float | ConstantPool.cpFloat | CONSTANT_Float | float constant
cp_Long | ConstantPool.cpLong | CONSTANT_Long | long constant
cp_Double | ConstantPool.cpDouble | CONSTANT_Double | double constant
cp_String | ConstantPool.cpString | CONSTANT_String | String constant
cp_Class | ConstantPool.cpClass | CONSTANT_Class | class reference
cp_Signature | (see below) | (none) | method, field, or variable type
cp_Descr | ConstantPool.cpNameAndType | CONSTANT_NameAndType | pair of (name, type)
cp_Field | ConstantPool.cpFieldref | CONSTANT_Fieldref | field reference
cp_Method | ConstantPool.cpMethodref | CONSTANT_Methodref | method call
cp_Imethod | ConstantPool.cpInterfaceMethodref | CONSTANT_InterfaceMethodref | interface call
(none) |  | CONSTANT_Unicode | unused type

Each constant pool is logically a set of symbolic or numeric values, all of one type. In the Pack200 archive, it is structured as a sequence of such values, each with a unique index within the sequence. Elsewhere in the archive, whenever a constant must be mentioned, its index within the appropriate constant pool (or within a subset of a pool) is given. (Pool subsets will be described in passing along with the bands that contain references into them.)

Unlike the class file format, constant pool indexing in the Pack200 archive format starts at zero. In the rare places where null references are expected, the possibility is documented, and the null references themselves are encoded by a zero index, while all other index values are incremented by one. Where null references are not expected, they may still be encoded by the 32-bit index value -1.

Also unlike class files, there are no "gaps" or unused indexes associated with long or double values. Occasionally, we will refer formally to an element of a constant pool by using array notation. For example, the first three integers in the cp_Int constant pool are cp_Int[0], cp_Int[1], and cp_Int[2], and the last integer is cp_Int[cp_Int_count-1]. Note that both bands and constant pools are treated in this specification as arrays with zero origin.

It is illegal for a compressor to transmit the same constant twice. That is, all constant pool entries must be unique.

In a class file, with a few exceptions, constant pool references are strongly typed, in that every reference either is null or refers to a constant pool entry of a fixed tag associated with the context of the reference. The exceptions are ConstantValue attributes and operand fields of the ldc, ldc_w, and ldc2_w instructions.

However, because constant pools in a Pack200 archive are separately indexed, all constant references must be strongly typed, so that there is only one constant pool (or subset of a pool) into which any given index applies. This is accomplished either by deducing the constant type from context (in the case of ConstantValue attributes) or adding extra information to the context of the reference. (Within the bytecode stream, ldc is split out by constant type into distinct instructions aldc, ildc, etc.)

The layout of constant pool bands in the archive follows the definition order of the constant pools themselves. Each constant pool is represented in its turn by a sequence of one or more bands. The sequence of constant pool bands is therefore structured as follows:

  cp_bands:
        cp_Utf8
        *cp_Int :UDELTA5 [#cp_Int_count]
        *cp_Float :UDELTA5 [#cp_Float_count]
        cp_Long
        cp_Double
        *cp_String :UDELTA5 [#cp_String_count] (cp_Utf8)
        *cp_Class :UDELTA5 [#cp_Class_count] (cp_Utf8)
        cp_Signature
        cp_Descr
        cp_Field
        cp_Method
        cp_Imethod

As can be seen here, constant pools whose entries can be derived from a single 32-bit integer or a single reference are represented as single bands. The other constant pools are represented as groups of bands. Each constant pool gives its name to a corresponding grammar element. This production of cp_bands declares the order of each band or group of bands that transmits the constants in the eponymous constant pool.

Note the use of UDELTA5 as primary encodings for several bands. Although the Pack200 file format does not require any particular ordering of values in constant pools, it is generally advantageous to order them so that the encoded values in bands using UDELTA5 are monotonically increasing. (Negative deltas can be encoded, although expensively, by UDELTA5. Also, a signed secondary encoding may be chosen by the compressor instead of UDELTA5.) The choice of primary encodings in this specification reflects an expectation that high-quality compressors, when presented with a choice of output orderings, will make choices that result in good use of primary band encodings.

5.3.1. Scalar Constants
The encoding of the cp_Utf8 constant pool will be described shortly. First we will describe the coding of the numeric, string, and class constant pools.

The values in the cp_Int constant pool are directly represented by the values encoded in its band. The values in the cp_Float constant pool are obtained as if by applying java.lang.Float.intBitsToFloat to the 32-bit values encoded in its band.

The 64-bit values of the cp_Long band are obtained by adjoining, as high and low words, corresponding 32-bit values from the two bands cp_Long_hi and cp_Long_lo. (They contain the high and low words, respectively.) Likewise, the values of the cp_Double band are obtained by first adjoining high and low words from two other bands, and then retyping the resulting 64-bit integers as if by applying java.lang.Double.longBitsToDouble. The high and low words are in the bands cp_Double_hi and cp_Double_lo, respectively.

  cp_Long:
        *cp_Long_hi :UDELTA5 [#cp_Long_count]
        *cp_Long_lo :DELTA5 [#cp_Long_count]

  cp_Double:
        *cp_Double_hi :UDELTA5 [#cp_Double_count]
        *cp_Double_lo :DELTA5 [#cp_Double_count]

When floating point values are eventually written to class files, their bits must be accurately stored, as if they were processed by java.lang.Float.floatToRawIntBits or java.lang.Double.doubleToRawLongBits. In this way "NaN" values are transmitted faithfully, without normalization.

(Note: Although it would be possible to extend the band-coding techniques of Pack200 to encode 64-bit values directly, this file format always transmits 64-bit values as pairs of 32-bit values, transmitted in pairs of bands. This simplifies implementations, allowing them to process band data with 32-bit data paths.)

Each string in a cp_String constant pool is represented in its band by a reference to the string's spelling, as a cp_Utf8 constant.

Likewise, each class in a cp_Class constant pool is represented in its band by a reference to the class's spelling, as a cp_Utf8 constant. (As in the class file and the VM, the spelling uses the slash character to delimit package prefix components.)

5.3.2. Utf8 Constants
Each value in the cp_Utf8 constant pool is an array of zero or more 16-bit Java characters. (The name "Utf8" is an anachronism, referring only to the basic character string type in Java class files. No part of the Pack200 file format uses any UTF encoding, but the term "Utf8" is retained to emphasize the connection with class files.) As in the class file format, all character string data is transmitted in this one kind of constant pool entry. When the context is clear enough, we loosely refer to these arrays as "strings", even though they are distinct from the Java constants in the cp_String constant pool.

If cp_Utf8 is not empty, its first value is always the empty string. Thus, the empty string is always given an index of zero. No band values are transmitted to represent this empty string. (Values in the bands cp_Utf8_prefix and cp_Utf8_suffix pertain to strings after the empty string in cp_Utf8.) Because constants cannot be duplicated, all other elements of cp_Utf8 contain at least one character.

Each string in the cp_Utf8 constant pool is represented in the archive file in two parts, a prefix and a suffix. The suffix is represented both by a count and a sequence of character codes. The prefix is represented only by a count; the characters of the prefix are duplicated from the previous string. This technique allows the compressor (if it chooses) to represent strings by means of their successive differences. The first suffix value and the first two prefix values are suppressed in the transmitted archive. The values, if transmitted, would always be zero, since the first cp_Utf8 string is always empty, and the second string can never share a non-empty prefix with the first string.

Each suffix is transmitted in exactly one of two ways, as a small suffix or a big suffix. Small suffixes are transmitted contiguously in one large band. Big suffixes are rare; they are intended as a way to compactly transmit strings with unusual statistics, such as strings which are really tables of numeric data. Each big suffix is transmitted in its own band. This allows the compressor the option to choose an efficiently customized secondary coding for the characters in each large, unusual string.

  cp_Utf8:
        *cp_Utf8_prefix :DELTA5      [MAX(0,#cp_Utf8_count-2)]
        *cp_Utf8_suffix :UNSIGNED5   [MAX(0,#cp_Utf8_count-1)]
        *cp_Utf8_chars :CHAR3        [SUM( *cp_Utf8_suffix )]
        *cp_Utf8_big_suffix :DELTA5  [COUNT(0, *cp_Utf8_suffix )]
        (*cp_Utf8_big_chars :DELTA5)
          ** length(cp_Utf8_big_suffix)  [SUM( *cp_Utf8_big_suffix )]
(Note: It is helpful, but not required by this specification, to order the strings lexicographically and find maximal common prefixes between adjacent strings. It is permissible to ignore the prefix sharing feature and declare all prefixes to be zero.)

The band cp_Utf8_suffix contains one less than #cp_Utf8_count elements. It specifies, in order, the small suffix length of each constant pool string (except the implicit first string, which is empty). The band cp_Utf8_prefix contains two less than #cp_Utf8_count elements. It specifies, in order, the prefix length of each constant pool string (except the first two strings, which always have zero prefix lengths). The prefix length encodes the length of a prefix substring shared by both cp_Utf8[i-1] and cp_Utf8[i]. If there are fewer than three strings in cp_Utf8, then cp_Utf8_prefix is empty. The prefix length is typically a large proportion (sometimes half) of the total length.

Each value in the band cp_Utf8_chars is a 16-bit number expressing a Java character. This band contains the characters of all small suffixes, in order. For each successive string, cp_Utf8_chars contains an additional run of values encoding the characters of its small suffix, if any. Therefore, the total length of this band is the sum of all values in the cp_Utf8_suffix band.

Whenever a small suffix length for a constant pool entry is zero, the string has no small suffix, but a big suffix instead. The length of each big suffix is given by an element of the cp_Utf8_big_suffix band. (Therefore, the length of this band is precisely the count of zero values in the cp_Utf8_suffix band.) Each big suffix is transmitted as a separate band of 16-bit character values, one band element per character. There is one such band per big suffix. These bands immediately follow the cp_Utf8_big_suffix band, and are collectively called the cp_Utf8_big_chars bands. Although normally data of the same type are collected into a single band, these strings are placed in separate bands so that they may be independently encoded. These strings typically encode arrays of binary data, rather than true Java characters.

A big suffix can have a length of zero, which means that the constant pool entry is a non-empty prefix of the previous string. In such a case, the corresponding suffix band will occupy no space in the archive file, since bands of zero length occupy no bytes at all.

Please see the Appendix section for pseudo-code explaining this concept.

5.3.3. Type Signatures
Each cp_Signature constant pool entry represents a type string, exactly as field and method types are declared in the class file format. Although the class file format uses simple Utf8 constant pool entries for such strings, the Pack200 file format allocates a separate constant pool for them, in order to use more compact representation than for general strings.

Signature constants are special in that they can contain embedded references to cp_Class constants. The signature constant is equivalent to a Utf8 constant, once the embedded class references are expanded into their spellings. Signature constants are flexible enough to represent arbitrary strings, but are intended for strings that often contain class names following the capital letter ell 'L'. These include field, method, and local variables types, and generic Signature attributes.

Each signature string is decomposed into a form and a sequence of zero or more class references. The class references are obtained by locating in the original signature string all sequences that match the pattern "L classname", removing the classname part, and treating it as a reference into the cp_Class constant pool. The form is defined as the residue after the class names have been removed from the original string.

The form is not allowed to contain any occurrences of the letter ell ('L'), other than those which mark removed class names.

Thus, the form will contain the character 'L' wherever the original type string refers to a class. By counting the number of these characters in a form, the decompressor may deduce the number of classes to which the original type string refers. This number is called the class length of the form.

Note that cp_Class constants are not required to refer to existing classes, nor are they even required to have valid class name spellings. Therefore, the compressor has considerable latitude in choosing which class names (if any) it will extract from signature strings. In an extreme case, the compressor can make each form identical to its corresponding signature string, and simply satisfy its class length by emitting references to a fictitious class with an empty name. (This class length would have to include any occurrences of 'L' in the class names themselves.)

Note also that these encoding rules do not require a class name to be followed by any particular character, although it will generally be a semicolon, or perhaps a left-angle bracket, in the case of an instance of a generic type in a Signature attribute.

The rules also allow the compressor to decide, arbitrarily, how many characters (if any) after each letter ell 'L' will be transmitted as part of a class name. Therefore, a given signature string may be representable by several forms, any of which the decompressor must be prepared to process.

Here are some examples:
Type Signature String | Form | Class Len. | Class...
F | F | 0
[Z | [Z | 0
[[[LLL; | [[[L; | 1 | LL
[[[LLL; | [[[LLL; | 3 | (empty), (empty), (empty)
([Ljava/lang/String;)V | ([L;)V | 1 | java/lang/String
Ljava/util/List<Lpkg/Item;>; | L<L;>; | 2 | java/util/List, pkg/Item
(Ljava/lang/String;II)Lpkg/Item; | (L;II)L; | 2 | java/lang/String, pkg/Item
Ljava/util/List<Ljava/lang/Byte;>; | L<L;>; | 2 | java/util/List, java/lang/Byte
<ELEM:>(Ljava/util/List<TELEM;>;)TELEM; | <EL:>(L<TEL;>;)TEL; | 1 | EM, java/util/List, EM, EM
ALLOWABLE | ALLOWABLE | 3 | (empty), (empty), (empty)
ALLOWABLE | AL | 1 | LOWABLE
ALLOWABLE | ALABL | 2 | LOW, E

The forms of all strings in the cp_Signature constant pool are given in order in the cp_Signature_form band, as one cp_Utf8 reference per signature string. For each form, the class-length sequence of classes required to reconstitute the signature string is transmitted as a run of cp_Class references in the cp_Signature_classes band. As a consequence of these definitions, the length of the cp_Signature_classes band is the total number of letter ell 'L' occurrences in the sequence of spellings of forms mentioned in cp_Signature_form.

  cp_Signature:
        *cp_Signature_form :DELTA5 [#cp_Signature_count](cp_Utf8)
        *cp_Signature_classes :UDELTA5 [COUNT('L',...)] (cp_Class)

Please see the Appendix section for pseudo-code explaining this concept.

5.3.4. Tuple Constants
The remaining constant pools contain ordered pairs of various kinds of values (types, names, strings, or classes). Each cp_Descr constant is an ordered pair of a name (represented as a cp_Utf8 reference) and a type (represented as a cp_Signature reference). These references are transmitted in corresponding elements of the cp_Descr_name and cp_Descr_type bands.

Likewise, each cp_Field, cp_Method, or cp_Imethod constant is an ordered pair of a class (represented as a cp_Class reference) and a name-and-type descriptor (represented as a cp_Descr reference). Again, these references are transmitted in corresponding elements of the associated bands.

  cp_Descr:
        *cp_Descr_name :DELTA5 [#cp_Descr_count] (cp_Utf8)
        *cp_Descr_type :UDELTA5 [#cp_Descr_count] (cp_Signature)
  cp_Field:
        *cp_Field_class :DELTA5 [#cp_Field_count] (cp_Class)
        *cp_Field_desc :UDELTA5 [#cp_Field_count] (cp_Descr)
  cp_Method:
        *cp_Method_class :DELTA5 [#cp_Method_count] (cp_Class)
        *cp_Method_desc :UDELTA5 [#cp_Method_count] (cp_Descr)
  cp_Imethod:
        *cp_Imethod_class :DELTA5 [#cp_Imethod_count] (cp_Class)
        *cp_Imethod_desc :UDELTA5 [#cp_Imethod_count] (cp_Descr)

5.4. File Attributes

Since a JAR archive consists of a sequence of files, each with contents and a few other attributes, the Pack200 archive can also represent a sequence of files with their attributes. Of course, the contents of class files are specially transmitted, but whether a file (i.e., a JAR archive element) contains a class or another resource, the Pack200 archive is able to transmit the following attributes:
  • name of file (optional for classes)
  • contents of file (optional for classes)
  • modification time of file (optional)
  • deflation hint for file (optional)
  • order of file in archive (optional for classes)

A class file whose contents are compressed by Pack200 is marked as a "stub" with a special option bit. A class stub file must be declared to have a length of zero. It may be declared to have the empty string for its name. If there are not enough class stub files transmitted to match with the number of classes transmitted, the decompressor must act as if the compressor had transmitted an additional series of trivial stubs, with no name or contents, and modification time and deflation hint copied from the archive header.

Each resource file is transmitted in the Pack200 archive as a simple bytewise image, under a relative pathname using slash '/' as a directory separator. (This is the same pathname convention as is used in ZIP archives.) Each file (both resource files and class files) can optionally be associated with a deflation hint and a modification date.

  file_bands:
        *file_name :UNSIGNED5 [#file_count] (cp_Utf8)
        *file_size_hi :UNSIGNED5 [#file_count*(#have_file_size_hi)]
        *file_size_lo :UNSIGNED5 [#file_count]
        *file_modtime :DELTA5 [#file_count*(#have_file_modtime)]
        *file_options :UNSIGNED5 [#file_count*(#have_file_options)]
        *file_bits :BYTE1 [SUM(*file_size)]

There are no additional file attributes, such as comments, extra attributes, or CRC values. An application which requires such attributes on some files may encode those files into an appropriate archive file format (such as ZIP), and transmit those archives as resource files in a Pack200 archive.

Each file name is transmitted as an element of the file_name band, and each length (in bytes) is transmitted in the corresponding elements of the file_size_lo band and (if present) the file_size_hi band. All three bands are of length #file_count, except that file_size_hi has zero elements if the have_file_size_hi bit in the #archive_options is clear.

The length in bytes of each file is the corresponding unsigned 32-bit value taken from the file_size_lo band, if the file_size_hi band is empty. Otherwise, the file length is the unsigned 64-bit value composed of the corresonding unsigned 32-bit elements of the file_size_lo and file_size_hi bands, where the former value is the low-order 32-bit word and the latter value is the high-order 32-bit word.

The bytes of all non-class (i.e., resource) files follow immediately in the file_bits band. Each file is given as a corresponding run of byte values.

The optional band file_modtime, if not empty, supplies a modification time for each resource file (and potentially for class files, if class file stubs are present). Each integer value gives a difference (in seconds) from the #archive_modtime value. (Therefore, if the #archive_modtime value is zero, the individual file times must be interpreted as absolute values.) The order of transmission of file_modtime is consistent with file_name. This band is empty if the have_file_modtime bit in the #archive_options is clear.

The optional band file_options, if not empty, supplies flag bits for each resource file (and potentially for class files, if class file stubs are present). This band is empty if the have_file_options bit in the #archive_options is clear. Each file_options word is interpreted bitwise. Certain bits are given symbolic names as follows, where the LSB is numbered as bit zero:
Bit | Name | Purpose
0 | deflate_hint | request compressed JAR file element
1 | is_class_stub | this file contains class bytecodes
If deflate_hint (the LSB) is set, the decompressor is requested (but not required) to reduce the size of its output. For example, if it produces a JAR file, it may deflate the JAR elements. Since the deflate_hint bit in the #archive_options word has the same effect, the two bits are in effect combined with a logical OR for each file. If is_class_stub (the second LSB) is set, this resource file description is actually a stub, and the file contents are defined as the bytecodes of one of the classes defined in the Pack200 archive. Other bits in the file options must be zero and are reserved for future use.

If a transmitted file is marked as a class stub, its contents must be transmitted as if the file were empty. (That is, file_size_hi and file_size_lo must both be zero, and there may not be any corresponding bytes in file_bits.) The decompressor is required to supply contents for the resource file by reconstituting the contents of a class file for a class transmitted in class_this, etc. Like any other resource file, the class stub is allowed to have a name, a modification time and a deflate_hint.

The class stubs and classes correspond in order. Define the derived parameter #class_stub_count as the number of files marked as class stubs. (It is also the count of is_class_stub bits set in file_options.) Then #class_stub_count must be no larger than #class_count. The first class stub defines a file which receives bytecodes for the first class, and so on. Although a class stub has a name (transmitted in file_name), this name may be the empty string. In this case, the decompressor is required to use the standard name for the class file, which is created from the class's bytecode name (using slash '/' for a package separator) by appending the string ".class". (Thus, a classfile can have an arbitrary non-standard name, but the compression works best if its name is derived from its class in the usual way.)

If #class_count is larger than #class_stub_count, then the decompressor must behave as if a sufficient number of trivial extra class stubs were transmitted after the last explicit file. These trivial stubs have an empty name string and a zero deflate_hint or file_modtime.

Thus, in the simple case where there are no class stubs at all (perhaps because have_file_options is zero), the decompressor must produce its files in their transmission order, followed by the transmission order of the classes. Each class file must have its standard name, and a modification time and deflation hint inherited from #archive_modtime and the deflate_hint bit in #archive_options. But at the cost of extra transmission size, the compressor can direct the decompressor to present the resources and class files in any fixed order, with arbitrary names, modification times, and deflation hints for each output file. The decompressor must honor this ordering, if its output is in a form (such as a JAR archive) where order is significant.

Compressors are free, unless otherwise directed, to choose any ordering of files. It is often advantageous to place files with similar statistics next to each other, so that the post-pass compressor (if any) may process their contents together (in the same window, in the case of the DEFLATE algorithm). It is likely that a compressor which is able to reorder its input files for efficient transmission will have a command option which forces it to retain the order in which input files were presented, because this order is significant to some (but not all) deployment applications.

Compressors are free to transmit class files as if they were resource files. This provides a way to transmit class files which must be preserved bit-for-bit, or which compressors cannot transmit compressed with sufficient accuracy. Decompressors are required to accept class files transmitted "bitwise" as resource files.

Note: The bands controlling files and their attributes are transmitted last in the archive, in order to ease decompressor implementation slightly, since the last thing a decompressor does is to assemble output files. In particular, resource files can be of arbitrary size, and placing their bits at the end of the archive allows the decompressor to avoid allocating temporary storage for them.

5.5. Flags and Attributes

The Pack200 file format directly supports up to 16 modifier bits in all output flags fields, as defined by the class file format. It also directly supports certain predefined attributes, such as Code, InnerClasses, and ConstantValue It is also possible for the compressor to define additional attributes, passing enough information to the decompressor to properly extract their data from bands and reconstitute them in class files. The presence or absence of all attributes is controlled by the setting of certain bits in flag bands.

Five sets of flag bands carry modifier bits and/or attribute control bits. The ic_flags band carries modifier bits for nested classes. Also, modifier and attribute control bits are carried by class_flags_lo, field_flags_lo, method_flags_lo, and code_flags_lo, and the four corresponding optional high word bands, class_flags_hi, field_flags_hi, method_flags_hi, and code_flags_hi. (There is no high word for ic_flags.) Each value in these bands is interpreted as an unsigned 32-bit binary number. Each bit in these bands independently specifies the presence of a Java access modifier (such as ACC_PRIVATE), or of a class, field, method, or code attribute (such as Deprecated or SourceFile), or of some other necessary control information (such as whether a class file has a non-default version number).

Every class (resp. field, method, Code attribute) has a corresponding flags value of up to 63 bits transmitted in class_flags_lo (resp., field_flags_lo, method_flags_lo, code_flags_lo) and optionally in class_flags_hi (resp., field_flags_hi, method_flags_hi, code_flags_hi). These flags values, assembled into 64-bit numbers, are named class_flags (resp., field_flags, method_flags, code_flags). Except for Code attributes, each of the low sixteen flag bits may be used to transmit access flags. The high sixteen bits (or forty-seven, if the optional high word is transmitted) are used to indicate the presence of attributes, either predefined or compressor-defined. The sixty-fourth bit position of a flags value (if transmitted) is reserved and must be zero.

The flags value for a Code attribute is optional and taken to be zero if missing. A Code attribute has a corresponding flags value transmitted if and only if either the have_all_code_flags bit in the #archive_options is set, or else the element of code_headers corresponding to the Code attribute has the special value zero. (See the discussion of code headers below.)

For classes, nested classes, fields, and methods, the assignment of flag bit positions to modifiers is the same as that in the class file format. (For example, the LSB always represents ACC_PUBLIC, in both Pack200 archive and class file formats.) An overflow attribute is an attribute whose presence is not indicated directly via a flag bit, and but is instead indicated by a occurrence of its index in a separate band. For classes, fields, methods, and codes, bit 16 (as set in the mask 0x0001000) indicates the presence of overflow attributes. For nested classes, flag bit 16 indicates the presence of explicit outer class and name fields, as explained below.
Bit | Meaning
0 | ACC_PUBLIC
1 | ACC_PRIVATE
2 | ACC_PROTECTED
3 | ACC_STATIC
4 | ACC_FINAL
5 | ACC_SYNCHRONIZED (ACC_SUPER)
6 | ACC_VOLATILE (ACC_BRIDGE*)
7 | ACC_TRANSIENT (ACC_VARARGS*)
8 | ACC_NATIVE
9 | ACC_INTERFACE
10 | ACC_ABSTRACT
11 | ACC_STRICT
12 | ACC_SYNTHETIC*
13 | ACC_ANNOTATION*
14 | ACC_ENUM*
16 | overflow (more band data elsewhere)
The modifiers marked with a star (*) are new to recent versions of Java. They are present here for information only, and are not part of the Pack200 specification.

5.5.1. Assignment of Flag Bits to Attributes
The assignment of flag bit positions to attributes is done at the option of the compressor, and is independently specified by the compressor for the four kinds of flag words that have to do with attribute-carrying objects (in classes, fields, methods, and codes). When a flag bit position is assigned to an attribute, if that bit is visible in the class file, it must be forced clear before the decompressor writes it to the class file. Therefore, if the compressor expects the decompressor to reproduce a particular non-zero flag bit as output, the compressor must refrain from assigning that bit position to attributes.

In particular, the low-order 16 bits of class, field, and method flags are visible in the class file, and can thus carry modifier bits. None of the bits of a code flags word is visible in the class file; these flag bits are used only for code sub-attributes.

By contrast, the low-order 16 bits of nested class records are used solely for modifiers, since nested class records do not contain attributes. In the rest of this section on attributes, we will disregard the flag words associated with nested class records.

Any of the 63 bit positions in a flags value can be assigned by the compressor to indicate to the decompressor the presence of some particular attribute. The compressor may "take over" a modifier bit by assigning it an attribute definition. (This is done by emitting a definition for the attribute, which mentions that bit position.)

If the compressor "takes over" a bit (modifier or not) that is being used by default for another purpose, the bit loses its previous meaning. However, the compressor may not emit an explicit definition for the same bit twice (in the same context).

Each kind of attribute is defined by four pieces of information: the entity to which it applies (class, field, method, or code), the bit position, if any, to which it is assigned, the name of the attribute (as it appears in the class file), and the layout of the attribute (which allows the decompressor to properly format occurrences of the attribute in the class file). It is an error for the compressor to specify the same name and layout twice in the same context. It is not an error to repeat a name with a different layout, or a layout with a different name.

The first two items are bit-encoded into a single-byte "header", and transmitted in the attr_definition_headers band. The last two items are transmitted as cp_Utf8 references in corresponding elements of the attr_definition_name and attr_definition_layout. Thus there are three bands by which the compressor declares attribute types to the decompressor, and each band is of length #attr_definition_count.

  attr_definition_bands:
        *attr_definition_headers :BYTE1 [#attr_definition_count]
        *attr_definition_name :UNSIGNED5 [#attr_definition_count] (cp_Utf8)
        *attr_definition_layout :UNSIGNED5 [#attr_definition_count] (cp_Utf8)

The least significant two bits of an attribute definition header byte are treated as an unsigned field, and give the attribute's context type, which is type of entity to which the attribute applies:
(h & 0x03) | Context Type
0 | attribute applies to classes
1 | attribute applies to fields
2 | attribute applies to methods
3 | attribute applies to Code attributes

The most significant six bits of an attribute definition header byte are treated as an unsigned field, and give the optional bit position to which the attribute is assigned in the flags word.
(h >> 2) | Flag Bit Assignment
0 | overflow attribute, not assigned to any bit
1 | attribute assigned to bit 0 (LSB of lo word)
2 | attribute assigned to bit 1
3 | attribute assigned to bit 2
...
32 | attribute assigned to bit 31 (MSB of lo word)
33 | attribute assigned to bit 32 (LSB of hi word)
...
63 | attribute assigned to bit 62
(no value) | bit 63 must be zero (MSB of hi word)

Every class attribute, whether predefined in this specification or explicitly defined by the compressor, has a unique number called its attribute index. If the attribute is assigned a flag bit, then its attribute index is identical to the flag bit's position (a number in [0..62]). (All predefined attributes are assigned a flag bit by default.)

If a class attribute is not assigned a flag bit, it is an overflow attribute, and its index is assigned sequentially in the order in which class attributes are defined (i.e., transmitted). The first index to be assigned sequentially in this way is 32 if #have_class_flags_hi is clear, and 63 if it is set. These indexes are used within the archive to declare attribute occurrences for individual classes.

Likewise, field, method, and code attributes are assigned their own attribute indexes, independently of class attributes and of each other. Therefore, an attribute (i.e., a name and layout pair) is uniquely specified within the archive by its context type and attribute index. The field and method attributes may be assigned to flag bits, or else they are overflow attributes with indexes of 32 or larger. Like other attributes, code attributes may be assigned explicit numbers or implicitly assigned indexes starting with 32. (As with class attributes, if the high flag word bands are selected by the appropriate bit of #archive_options, then field, method, or code overflow attributes have indexes of 63 or larger.)

Some attributes are predefined, and do not require the compressor to emit definitions for them. They have implicitly defined layouts and flag bit assignments (i.e., indexes).

Attribute indexes less than 63 are usable in all cases, but they may conflict with those assigned to predefined attributes, including predefined attributes defined (in the range 16 to 62) in future expansions of the Pack200 format. In the present version, all predefined attributes have indexes in the range [17..31], so that modifier flags are not taken over by default, and high flag words do not need to be used routinely.

Here are the names and index assignments of the predefined attributes. (The predefined layouts are given below.)
Index | Context Type | Name
16 | C,F,M | (overflow attributes)
17 | Class | SourceFile
18 | Class | EnclosingMethod
19 | C,F,M | Signature
20 | C,F,M | Deprecated
21 | C,F,M | RuntimeVisibleAnnotations
22 | C,F,M | RuntimeInvisibleAnnotations
23 | Class | InnerClasses
24 | Class | "class-file version"
17 | Field | ConstantValue
17 | Method | Code
18 | Method | Exceptions
23 | Method | RuntimeVisibleParameterAnnotations
24 | Method | RuntimeInvisibleParameterAnnotations
25 | Method | AnnotationDefault
0 | Code | StackMapTable
1 | Code | LineNumberTable
2 | Code | LocalVariableTable
3 | Code | LocalVariableTypeTable
16 | Code | (overflow attributes)

Bit 16 is predefined as an indicator of the presence of overflow attributes for classes, fields, methods, and codes. If an entity has overflow attributes, it will possess a corresponding count in an "attr_count" band, and each overflow attribute will be part of a run of values in an "attr_indexes" band, which specifies the layouts of the overflow attributes. This processing of overflow attributes is described more fully below.

These predefined attribute indexes determine not only which bit positions are used to select those attributes, but also the fixed band order in which the attribute data are transmitted, as described below.

Certain bits are predefined to support the five types of metadata attributes on classes, fields, and methods, RuntimeVisibleAnnotations, RuntimeInvisibleAnnotations, RuntimeVisibleParameterAnnotations, RuntimeInvisibleParameterAnnotations, and AnnotationDefault. (The last three types apply only to methods.) The meaning and format of these attributes is defined by JSR 175.

It is permissible for a compressor to refrain from setting bits in any flag words except for bit 16, and transmit all attribute layout indexes explicitly in class_attr_indexes or a similar band. Decompressors are required to process either kind of occurrence of an attribute index. (It is also permissible, though useless, for an attribute count to be an explicitly transmitted as zero.) Compressors are encouraged to make clever choices and clear bit 16 and set other assigned flag bits when possible.

Note that none of the predefined bits interfere with any present or future flag bits in the 16-bit flag values stored in the class file format. However, compressors are free to reuse one of the low-order 16 bits of the flags word, by binding them to other attributes, if no file actually sets them.

The InnerClasses attribute is treated specially, as documented elsewhere, and it is an error for the compressor to emit an attribute definition for it in the class context. The Code attribute is also treated specially. It is an error to emit an attribute definition for it in the method context.

This specification does not define how a compressor is informed of the existence or format of attributes which are not predefined. It simply assumes that compressors are informed of such attributes, and it requires that compressors properly transmit this information to decompressors. As a special case, it is reasonable for any compressor to transmit an attribute containing no bytes (i.e., of zero length) as if its layout were known to be the empty string.

5.5.2. Attribute Layout Definitions
Attribute layouts govern the compressor as it parses attribute bodies from class files into collections of scalar values. Layouts also govern the decompressor as it decodes transmitted bands of those scalar values, and stores them, correctly formatted, into class files. For example, when a class file stores an unsigned integer in two bytes (in big-endian order) in an attribute, the decompressor uses a layout declaration to this effect, so that it can take a band element (which is a 32-bit integer that in this case happens to be less than 65536) and store it correctly into a class file. The transmission of such an integer is very different from the transmission of a constant pool reference, even though they appear as undifferentiated bytes in the class file format.

In what follows, we say that some given element of an attribute layout governs a scalar value stored in a class file attribute, if the decompressor must use that element to reconstitute, into a class file, the representation of that scalar value. We also say that the given layout element governs the band in which the scalar value is transmitted.

An attribute layout is defined by a string in a "little language". The string must be parsed by the decompressor into a sequence of layout elements, each of which governs the transmission and storage of attribute values. In particular, the layout declares the locations of all constant pool references, allowing their values to be transmitted with appropriate representations, either as constant pool indexes or else some other sort of number.

The simplest usable attribute layout would be a sequence of constant pool reference declarations, intermixed with one-byte declarations to govern everything else, and compressors are free to use such layouts to describe attributes. However, more specific attribute layouts lead to better compression.

Attributes typically contain constant pool references and small integers. They often contain integers which control the replication of subsequent patterns. Constant pool references are strongly typed where possible, and the encoding provision for null references must be declared also. Small integers which encode flag bits or bytecode indexes are also declared as such, so that special encoding techniques may be used on them.

Layout declarations are UTF8 strings formed according to the following grammar. (This grammar is independent of the grammar which describes band structure, or any other grammar appearing in other parts of this specification.)

  attribute_layout:
        ( layout_element )* | ( callable )+
  layout_element:
        ( integral | replication | union | call | reference )

  callable:
        '[' body ']'
  body:
        ( layout_element )+

  integral:
        ( unsigned_int | signed_int | bc_index | bc_offset | flag )
  unsigned_int:
        uint_type
  signed_int:
        'S' uint_type
  any_int:
        ( unsigned_int | signed_int )
  bc_index:
        ( 'P' uint_type | 'PO' uint_type )
  bc_offset:
        'O' any_int
  flag:
        'F' uint_type
  uint_type:
        ( 'B' | 'H' | 'I' | 'V' )

  replication:
        'N' uint_type '[' body ']'

  union:
        'T' any_int (union_case)* '(' ')' '[' (body)? ']'
  union_case:
        '(' union_case_tag (',' union_case_tag)* ')' '[' (body)? ']'
  union_case_tag:
        ( numeral | numeral '-' numeral )
  call:
        '(' numeral ')'

  reference:
        reference_type ( 'N' )? uint_type
  reference_type:
        ( constant_ref | schema_ref | utf8_ref | untyped_ref )
  constant_ref:
        ( 'KI' | 'KJ' | 'KF' | 'KD' | 'KS' | 'KQ' )
  schema_ref:
        ( 'RC' | 'RS' | 'RD' | 'RF' | 'RM' | 'RI' )
  utf8_ref:
        'RU'
  untyped_ref:
        'RQ'

  numeral:
        '(' ('-')? (digit)+ ')'
  digit:
        ( '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' )

Each occurrence of an attribute in a class file is associated (by the compressor) with a corresponding layout definition which describes accurately the meaning of that attribute's bytes. The compressor must assign each format element its own band for transmitting successive values of that format element. In the case of the predefined attributes, the bands assigned to their layout elements are defined by name in this specification.

Each value governed by an attribute layout element is converted by the compressor into a 32-bit value and transmitted as an element of a band uniquely created for and governed by that layout element. For integral layout elements, the conversion simply represents the number stored in the class file under the given type, while reference elements convert a local constant pool reference (local to the class file, that is) into a global, typed reference within the archive.

Multiple occurrences of the same kind of layout element are regarded as distinct layout elements. Also, bands are never shared by layouts. Therefore, every new layout definition transmitted by the compressor implicitly defines its own set of bands. Reassigning an previously defined attribute layout to a new index creates a new set of bands; it does not reuse the previously defined sets of bands.

If the compressor defines new attributes, it must also create the bands they govern. It must transmit these bands, immediately after the place reserved in the band grammar for predefined attributes (at the end of class_attr_bands, field_attr_bands, method_attr_bands, or code_attr_bands). The ordering of these bands must correspond to the definition order of the attribute layout elements that govern them. In this way, the decompressor will be able to find those attribute values.

The definition order of two layout elements in the same attribute layout string corresponds to their order of occurrence within that string. The definition order of two layout elements not in the same attribute layout string corresponds to the index order of their layout definitions in the attr_definition_layout band. (That is, bands for layouts with lower indexes precede bands for layouts of the same context type but with higher indexes. This is true even if the lower-indexed layout happens to be defined later in the attr_definition_layout band.) Note that the bands governed by predefined attributes appear to follow such an ordering also. However, the bands of predefined class attributes precede all the other class attribute bands, and likewise for fields, methods, and code attributes.

Integer values stored in attributes are sized as 1, 2, or 4 bytes, depending on the use of the format character 'B', 'H', or 'I', respectively. A integer type is normally unsigned but prefixed with 'S' becomes signed. This signing governs the lengthening of 1-byte and 2-byte types to 32-bit values (either sign extension or zero filling). It also determines the primary encoding used to transmit the 32-bit values. Because all integers stored in class files are "big-endian", all integral format elements refer to integers coded with higher-order bits in earlier bytes.

Integral layouts (i.e., those elements under the integral nonterminal) govern signed or unsigned integer values. Integral layouts whose declarations include the 'P' or 'O' characters use special primary encodings (BCI5 or BRANCH5) as described below. Any other integral layouts whose declarations include the 'S' character govern bands with a primary encoding of SIGNED5. Unsigned integer and flag layout elements govern bands with a primary encoding of UNSIGNED5, except that the integer layout 'B' (unsigned byte) governs a band with a primary encoding of BYTE1.

(Note that there is no special encoding for signed bytes. If an attribute contains a signed byte field, it may be just as well to treat that field as if it were unsigned, and give it a plain 'B' layout element. Besides completeness, the 'SB' layout is intended to allow small-magnitude one-byte integers to be transmitted using a byte alphabet in which sign bits are rare. This is desirable when the post-pass compressor uses Huffman coding to represent bytes; such codings perform best when a consistent byte alphabet is presented to the compressor.)

A stored bytecode index is declared with the layout prefix 'P'. This layout element may only be used on methods or codes. Any number may be stored in a bytecode index. However, before the stored numbers are transmitted as band elements, they are renumbered in the expectation that byte positions not on instruction boundaries will be rare.

The BCI renumbering compactly indexes instruction boundaries, and also provides a coding (somewhat less compact) for all other 32-bit integers, such as the addresses of bytes inside instructions or outside the bounds of the bytecodes. In particular, the first byte of the first instruction is numbered zero, the first byte of the second instruction is numbered one, and so on through all instructions. The byte position one past the last instruction is numbered with the next number (the number of instructions). The second byte of the first multibyte instruction is numbered with the next number, which is one more than the number of all instructions. All remaining unnumbered bytes are assigned subsequent numbers, without any further disturbances of ordering. For large enough positive numbers, and for negative numbers, the renumbering is the identity function.

For purposes of locating instruction boundaries for BCI renumbering, the _wide bytecode (0xc4) is taken to be part of the following instruction, whose format it helps determine. If the compressor transmits byte_escape (254) or ref_escape (253) pseudo-instructions, the decompressor must accept the bytecode sequences produced by each of these instructions as integral instructions, when computing BCI renumberings. Thus, there will be an instruction boundary for each byte in bc_codes (except _wide bytecodes), plus an extra boundary for each "aload_0_xxx" variation (such as "aload_0_getstatic_this"), because these pseudo-opcodes expand to pairs of bytecode instructions.

Please see the Appendix section for pseudo-code explaining this concept.

If the layout element is prefixed by 'P' and not 'PO', then the renumbered bytecode index is transmitted. This renumbering is called the bytecode index renumbering. The primary encoding for bands containing bytecode indexes is BCI5.

Here is an example of how this works. Imagine a method with 20 bytes of bytecode data and five instructions, at the following positions: { 0, 4, 6, 10, 17 }. BCI renumbering translates these particular numbers compactly to [0..4]. More completely, BCI renumbering translates [0..20] to the numbers { 0, 6, 7, 8, 1, 9, 2, 10, 11, 12, 3, 13, 14, 15, 16, 17, 18, 4, 19, 20, 5 }, and anything outside the range [0..20] stays the same after BCI renumbering. If a attribute of this method has a 'P' layout element, and has the number 6 stored in the class file, the number 2 will be transmitted, since 6 is the offset of the third instruction.

If the layout prefix is 'PO', the previous layout element must also have been a bytecode index of layout type 'P' or 'PO'. (There must not be intervening structure, such as brackets '[' or ']'.) In this case, the value transmitted in the band governed by the 'PO' element is the difference between the renumbered bytecode index governed by the current 'PO' element, and the renumbered bytecode index governed by the previous 'P' or 'PO' element. (In the case of a previous 'P' element, this is in fact the value transmitted at the corresponding position in the previous band.)

The 'PO' layout elements govern the same kind of attribute data as 'P' elements, but they use an encoding which expects that adjacent bytecode indexes are correlated. This renumbering, including a difference with the previous element, is called the bytecode offset renumbering The primary encoding for bands containing bytecode offsets is BRANCH5. This encoding is used even if the layout element contains the 'S' or the 'B' character.

A bytecode offset is declared with the layout prefix 'O'. This layout element must immediately follow a previous bytecode index element (with prefix 'P' and not 'PO'). Any value governed by this layout element is regarded as an offset, which when applied to the corresponding previously stored bytecode index, produces another bytecode index. That is, both the previous value and the sum of the previous value and the current value are expected to refer to instruction boundaries. As with the 'PO' layout, the value transmitted is the difference of the two renumbered bytecode indexes. Bands governed by 'PO' layouts contain bytecode offsets, and use the BRANCH5 primary encoding. Unlike the 'PO' layout, the stored value governed by an 'O' layout is the difference between two bytecode indexes.

Thus, bands governed by both 'O' and 'PO' layouts contain bytecode offsets, and use BRANCH5 to encode those offsets. But attribute values governed by both 'P' and 'PO' layouts store absolute bytecode indexes; only 'O' layouts govern stored bytecode offsets. The stored offsets are treated as unsigned fields in the class file unless the 'S' character is present. By contrast, stored indexes are always treated as unsigned fields.

If the preceding example attribute for a 20-byte method also has a 'PO' layout element following its 'P' element, and the number 20 is stored in the class file, the number to be transmitted is found by renumbering 20 to 5, and then subtracting the previous transmitted number (5-2). The number 3 will therefore be transmitted. If instead the stored number is 7 (a BCI inside the instruction at position 6), the transmitted number will be (10-2) or 8. The same transmitted values (3, 8), if governed by an 'O' layout element instead of 'PO', would correspond to stored values of 14 (20-6) and 1 (7-6), instead of 20 and 7.

A flag element (with prefix 'F') encodes integer values which are expected to encode short array of bits, rather than arithmetic values. The bits are not required to be interpreted as access modifiers. The primary encoding for bands transmitting flag layout elements is UNSIGNED5, except that 'FB' layouts use a primary encoding of BYTE1.

Integral values transmitted under the 'V' format character instead of 'B', 'H', or 'I' occupy no bytes at all in the class file attribute. These layout elements allow the decompressor to use counts or tags to control transmission without having them appear directly in class file attributes. For example, consider an attribute which is an array of bytes that is not self-sizing but expands to fill the byte-count mentioned in the attribute header in the class file. Such an attribute might have a layout specification of 'NV[B]'. The compressor would be responsible to decide which values to transmit for a 'V' layout element. (Such decisions would have to make use of detailed information about attribute formats that is not part of this specification.) In all cases, the decompressor must respect these values (when used as counts or tags) but must not store them in the class file.

A replication is introduced by a prefix 'N', which is followed by an integer element called the replication count, and by then a series of elements, called the replication body, enclosed in square brackets. The attribute data governed by this layout consists of a replication count followed by an array of data counted by the replication count. Each array element is governed by the layouts in the replication body.

A replication count layout element governs a band transmitting the replication counts, which has a primary encoding of UNSIGNED5 (or BYTE1, if the layout starts with 'NB'). The bands governed by the corresponding replication body may be sized by summing the values transmitted in the band containing the counts.

A union is introduced by a prefix 'T', which is followed by an integer element called the union tag, and by then a series of labeled, bracketed groups of elements, called the union cases. (The numerals can have any number of digits, but their arithmetic values are truncated to 32-bit integers before being compared with band values, which also are 32 bits in size.) Each label but the last consists of one or more parenthesized, possibly signed decimal numerals, called union tags. The last label (which is the default case) must be an empty pair of parentheses. (No union may contain two occurrences of the same case tag.) The attribute data governed by this layout consists of an integral tag value followed by data whose format is determined by the tag. The data following the tag is governed by the (unique) union case whose label matches the tag's value, or else the default case. The bands governed by each union case may be sized by counting the number of values in the band governed by the tag's layout. As with plain integral bands, the primary encoding of union tag band is SIGNED5, BYTE1, or UNSIGNED5, depending on whether the layout contains an 'S' character, is 'TB', or otherwise.

In a union tag, two numerals separated by a hyphen specify an inclusive range. The second number must be greater than the first. This is an abbreviation for the list of all numerals from the first to the second, inclusive. The layout is treated exactly as if the abbreviation were replaced by the complete list.

Constant pool references in an attribute may be typed strongly, and transmitted as indexes into one of the archive's constant pools. The layout types beginning with 'KI', 'KJ', 'KF', 'KD', and 'KS' must govern stored indexes in the local constant pool to constants of type integer, long, float, double, and string. Likewise, the layout types beginning with 'RC', 'RS', 'RD', 'RF', 'RM', 'RI', and 'RU' must govern stored indexes in the local constant pool to symbols of type class, signature, descriptor (pair of name and type), field reference, method reference, interface method reference, and UTF8 string. All these references are transmitted as 32-bit indexes into the corresponding global constant pools, in bands with primary encoding of UNSIGNED5. (This is true even of layouts which contain 'B'.) See table below.

Note that signature references (layout 'RS') are identical to Utf8 references (layout 'RU') within a class file, but lead to different coding tactics in the archive file, since the cp_Utf8 and cp_Signature constant pools have independent indexes and are transmitted differently.

The layout elements beginning 'KQ' may only occur in attributes on fields. They refer to constants in a constant pool whose identity is determined by the field's signature. (This layout element is probably useful only for ConstantValue attributes, which are predefined.) The following table gives field signatures legal for use with 'KQ' layouts, and the corresponding constant pools in which the corresponding stored references must be found.
Field Signature | 'KQ' Constant Pool
B | cp_Int
S | cp_Int
C | cp_Int
Z | cp_Int
I | cp_Int
J | cp_Long
F | cp_Float
D | cp_Double
Ljava/lang/String; | cp_String
Ljava/lang/Class; | cp_Class

If a constant pool reference cannot be strongly typed, the compressor must use an untyped_ref ('RQ'). The encoding of such an untyped reference is an index into all the pools, renumbered in the order they occur within the Pack200 archive. The sequence of all constants, in this natural order of occurrence, is called cp_All. For example, all the elements of the cp_Utf8 pool are numbered the same in the 'RQ' and 'RU' layouts. But the first element (element zero) of the cp_Int pool is numbered, for untyped references, as cp_Utf8_count, and the first element of the cp_Float pool is numbered, for untyped references, as cp_Utf8_count+cp_Int_count.

If a compressor is faced with an attribute which contains a constant pool index of an unexpected type, it may either refuse to transmit the attribute, or elect to transmit the attribute under a relaxed layout definition using 'RQN' elements instead of more strongly-typed elements. Decompressors are required to honor all legal layout definitions transmitted by compressors, even if they might produce illegally formatted class files. (In an extreme case, a compressor may elect to transmit a class file as if it were a resource file, obtaining no class-specific compression, but preserving unusually formatted attributes with bit-for-bit accuracy.)

If a reference layout type includes the character 'N', all band values encoding constant pool entries are incremented by one, and the null value is encoded as zero. Otherwise, the null value is encoded as negative one (-1).

The effect on primary band encodings of the rules given above may be summarized as a list of prioritized rules for layout elements, where the first applicable rule determines the encoding:

  • If the layout contains 'O', use BRANCH5.
  • Otherwise, if the layout contains 'P', use BCI5.
  • Otherwise, if the layout contains 'S' but not 'KS' or 'RS', use SIGNED5.
  • Otherwise, if the layout contains 'B', use BYTE1.
  • For all other layouts use UNSIGNED5.

    Here is a table summarizing bands and encodings for various layout elements. (Not all possible combinations of types and integer sizes are shown.)
    Layout
    Element     		Stored
    Value     		Transmitted
    Value     		Primary
    Encoding
    B | u1 | x | BYTE1
    FB | u1 | x | BYTE1
    SB | u1 | (byte)x | SIGNED5
    H | u2 | x | UNSIGNED5
    FH | u2 | x | UNSIGNED5
    SH | u2 | (short)x | SIGNED5
    I | u4 | x | UNSIGNED5
    FI | u4 | x | UNSIGNED5
    SI | u4 | x | SIGNED5
    PH | u2 | renumber_bci(x) | BCI5
    POH | u2 | renumber_bci(x) - renumber_bci(x0) | BRANCH5
    OH | u2 | renumber_bci(x0+x) - renumber_bci(x0) | BRANCH5
    NB[...] | u1 | x (also serves as size count) | BYTE1
    NH[...] | u2 | x (also serves as size count) | UNSIGNED5
    NI[...] | u4 | x (also serves as size count) | UNSIGNED5
    TB... | u1 | x | BYTE1
    TSB... | u1 | (byte)x | SIGNED5
    TH... | u2 | x | UNSIGNED5
    TSH... | u2 | (short)x | SIGNED5
    KIB | u1 | indexOf(lcp[x], cp_Int) | UNSIGNED5
    KIH | u2 | indexOf(lcp[x], cp_Int) | UNSIGNED5
    KII | u4 | indexOf(lcp[x], cp_Int) | UNSIGNED5
    KINH | u2 | 1+indexOf(lcp[x], cp_Int) | UNSIGNED5
    KJH | u2 | indexOf(lcp[x], cp_Long) | UNSIGNED5
    KFH | u2 | indexOf(lcp[x], cp_Float) | UNSIGNED5
    KDH | u2 | indexOf(lcp[x], cp_Double) | UNSIGNED5
    KSH | u2 | indexOf(lcp[x], cp_String) | UNSIGNED5
    KQH | u2 | indexOf(lcp[x], cp_fieldSpecific) | UNSIGNED5
    RCH | u2 | indexOf(lcp[x], cp_Class) | UNSIGNED5
    RSH | u2 | indexOf(lcp[x], cp_Signature) | UNSIGNED5
    RDH | u2 | indexOf(lcp[x], cp_Descr) | UNSIGNED5
    RFH | u2 | indexOf(lcp[x], cp_Field) | UNSIGNED5
    RMH | u2 | indexOf(lcp[x], cp_Method) | UNSIGNED5
    RIH | u2 | indexOf(lcp[x], cp_Imethod) | UNSIGNED5
    RUH | u2 | indexOf(lcp[x], cp_Utf8) | UNSIGNED5
    RQH | u2 | indexOf(lcp[x], cp_All) | UNSIGNED5
    RQNH | u2 | 1+indexOf(lcp[x], cp_All) | UNSIGNED5
    RQNI | u4 | 1+indexOf(lcp[x], cp_All) | UNSIGNED5

    Here, the variable X names a value stored in the attribute, governed by the layout element. The variable X0 names the stored value governed by the immediately previous layout element, which must have begun with 'P'. The expression renumber_bci(I) denotes the renumbering of a bytecode index I to shorten references to instruction boundaries, as described above. The expression lcp[I] denotes a local constant pool reference, with index I, or a distinct null value if I is zero.

    The expression indexOf(lcp[I], cp) denotes the index (zero-based) in a Pack200 global constant pool cp of the constant lcp[I], which is assumed to be of a type appropriate to cp. This expression has the value -1 if lcp[I] has the distinct null value.

    Note that a null reference can always be transmitted in a band containing references, by transmitting the value zero (if the band is specified to accept nulls) or by transmitting the value -1 (otherwise). The UNSIGNED5 encoding can represent -1 in five bytes.

    The name cp_All refers to a combined array created (as described above) by concatenating all Pack200 global constant pools in their order of transmission. The name cp_fieldSpecific refers to a global constant pool selected by the enclosing field's signature, as described above.

    5.5.3. Recursive Layouts
    The top-level structure of a layout specification may be a series of bodies which are independently callable layouts. In such a case, the attribute data governed by the whole layout specification is governed by the first body in the sequence of callables. The other callables can govern data, but they only do this if they are actually called. The effect is to define a mutually recursive set of layout specifications, and give control to the first. Note that callables may not be nested inside any other syntax. This feature is useful for supporting recursively structured class file attributes, such as metadata.

    A call layout element is a parenthesized signed decimal numeral N. It refers to the Nth callable in the top-level structure of the layout specification, relative to the callable in which the call appears. (It is illegal for calls to appear outside of callables.) We will refer to this callable as the call's callee.

    (For example, the layout element '(2)' calls the second callable layout after the one in which the call appears. There must be a matching callee for every callable. A call spelled '(1)' must not appear in the last callable of a layout, and likewise a call spelled '(-1)' must not occur in the first callable. Note that the self-call spelled '(0)' is always legal.)

    A call layout element indirectly governs the attribute data more directly governed by the callable that the layout element calls. As far as class file format is concerned, the effect is the same as if the text within the callable's body were substituted instead of the call.

    However, this substitution semantics does not describe the effect of a call layout element on band structure. A call layout element does not directly govern any bands, but rather specifies that the data it indirectly governs is to be transmitted in the bands governed more directly by the callee.

    If a call's callee begins textually later than the call itself, the call is a forward call. The effect of a forward call is simply to make the bands of the callee sharable by the call and any other forward calls to the same callee. For example, the following layout specification has two bands, the latter of which transmits data indirectly governed by either of the union cases. (The default union case governs no bands, so that a tag byte other than ASCII 'A' or 'B' has no following bytes. Whitespace has been added to the layout for ease of reading.)

            [TB
          (65) [(1)]
          (66) [(1)]
          (  ) []
          ]
        [H]

    A call's callee can also begin textually earlier than the call itself. Such a call, which must have a spelling of the form '(0)' or '(-N)', is referred to as a backward call. Its callee is referred to as a backward callable. (Callables which are the target of no calls or only of forward calls are not backward callables; all others are.) Backward calls and callables introduce the possibility of recursion and looping. Here is an example of an N-ary tree whose leaves are Utf8 strings preceded by a zero-byte, and whose internal nodes are counted arrays of tree nodes preceded by a one-byte: In this example, the callee encloses the call, for a direct recursion. The layout governs three bands, under the elements 'TB', 'NH', and 'RUH'.

            [TB
          (1) [NH[ (0) ]]
          (0) [RUH]
        ]

    The sizing of bands governed by such mutually-recursive layouts is assisted by explicit counts of backward calls, transmitted before any of the layout's attribute bands, in class_attr_calls and three similar bands, which are described later.

    5.5.4. Default Attribute Layouts
    The layout definitions of the predefined attributes are as follows:
    Context Type | Name | Layout Definition
    Class | "class-file version" | (empty) *(see note)
    Class | InnerClasses | (empty) *(see note)
    Class | EnclosingMethod | RCHRDNH
    Class | SourceFile | RUNH *(see note)
    Class | Signature | RSH
    Class | (metadata) | (see below)
    Class | Deprecated | (empty)
    Field | ConstantValue | KQH
    Field | Signature | RSH
    Field | (metadata) | (see below)
    Field | Deprecated | (empty)
    Method | Code | (empty) *(see note)
    Method | Exceptions | NH[RCH]
    Method | Signature | RSH
    Method | (metadata) | (see below)
    Method | Deprecated | (empty)
    Code | StackMapTable | (see below)
    Code | LineNumberTable | NH[PHH]
    Code | LocalVariableTable | NH[PHOHRUHRSHH]
    Code | LocalVariableTypeTable | NH[PHOHRUHRSHH]

    The star '*' in the layout definitions of "class-file version", InnerClasses, SourceFile, and Code reflects the fact that these attributes are given special processing. For a class, the "class-file version" pseudo-attribute is transmitted as if using the format VV, but the decompressor does not store the result in a class file attribute, but rather in the class file header. (See the discussion below.) For a class, the InnerClasses attribute is partially transmitted as if using the format NV[RCVTV[(0)[]()[RCNVRUNV]]], but the decompressor processes the received values further before (possibly) emitting an InnerClasses attribute. (See the discussion below.) When a SourceFile attribute is transmitted using the predefined layout, a special rule allows it to default to the obvious standard string. Finally, for a method, the Code attribute is transmitted under the code_bands.

    5.5.5. Stack Map Layouts
    There is a predefined attribute layout for the StackMapTable attribute of a Code attribute. With some whitespace and abbreviation added for readability, it is as follows:

  [NH[(1)]]
  [TB
    (64-127)  [(2)]
    (247)     [(1)(2)]
    (248-251) [(1)]
    (252)     [(1)(2)]
    (253)     [(1)(2)(2)]
    (254)     [(1)(2)(2)(2)]
    (255)     [(1)NH[(2)]NH[(2)]]
    ()        []
    ]
  [H]
  [TB
    (7) [RCH]
    (8) [PH]
    ()  []
    ]
    The following observations may be deduced by comparing this layout specification with the class file format specification which defines the StackMapTable attribute. The second callable describes a stack_map_frame structure from the class file format specification. Within the union in the second callable, the cases stand for the following stack_map_frame union members, respectively: same_locals_1_stack_item_frame, same_locals_1_stack_item_extended, chop_frame (and also same_frame_extended), append_frame (for three layout union cases), full_frame, and (in the default layout union case) same_frame. The third and fourth callables describe an offset_delta value and a verification_type_info structure from the class file format specification.
    5.5.6. Metadata Layouts
    The predefined attribute layouts for non-parameter metadata annotations are the same in all three contexts. With some whitespace added for readability, the layout is as follows:

  [NH[(1)]]
  [RSH NH[RUH(1)]]
  [TB
    (66,67,73,83,90) [KIH]
    (68)  [KDH]
    (70)  [KFH]
    (74)  [KJH]
    (99)  [RSH]
    (101) [RSH RUH]
    (115) [RUH]
    (91)  [NH[(0)]]
    (64)  [RSH [RUH(0)]]
    ()    []
    ]
    Both visible and invisible annotations use this layout. The second callable describes an annotation structure from the metadata specification. The third callable describes a member_value structure from the metadata specification. This last callable, all by itself, is used for the AnnotationDefault attribute on methods. Method parameter annotations (both visible and invisible) are also predefined using this layout, with a prepended callable to count the number of parameters:

  [NB[(1)]]
  [NH[(1)]]
  [RSH NH[RUH(1)]]
  [TB...]
    5.5.7. Unusual Layout Usages
    It is possible for the compressor to emit any number of definitions for the same attribute name. These definitions are assigned different attribute indexes (and perhaps flag bits), and are treated as distinct attributes, despite having the same name. If an attribute is too complex to define in the layout language, each occurrence of that attribute can be given a separate definition by the compressor. The minimum requirement is that each layout accurately declare the size of the corresponding attribute occurrence, and locate all constant pool references within that occurrence.

    5.6. Source File Abbreviation

    When a null reference is transmitted in the band governed by the predefined SourceFile attribute, the decompressor is required to replace it by a reference to a Utf8 string whose spelling consists of the associated class name string, with the following modifications made, in order:
    • Every character up to and including the last slash or dot ('/' or '.') is removed. (This removes any package prefix.)
    • If there is a character of code 0x2D or lower in the remaining string, the first such and all following characters are removed. (This removes any nested class name mangling.)
    • The suffix characters ".java" are appended.

    This rule matches the historical behavior of many Java compilers, and allows the compressor to avoid allocating Utf8 strings for "obvious" derived SourceFile names. (If a compressor needs to transmit an irregular SourceFile attribute with a true null reference, it must use a non-standard layout.) Here is a table of examples of class names and the corresponding derived SourceFile names.
    Class | SourceFile
    foo | foo.java
    foo/bar | bar.java
    foo/bar$baz | bar.java
    foo/bar#baz#1 | bar.java
    foo.bar.baz#1 | baz.java

    5.7. Nested Classes

    A nested class record is a four-tuple specifying two classes, a name, and some flags, as documented for the InnerClasses attribute of class files. It is primarily represented in the Pack200 archive by four bands, whose contents are applied equally to all class files in the archive.
      ic_bands:
        *ic_this_class :UDELTA5 [#ic_count] (cp_Class)
        *ic_flags :UNSIGNED5 [#ic_count]
        *ic_outer_class :DELTA5 [COUNT(1<<16,...)]  (null or cp_Class)
        *ic_name :DELTA5 [LENGTH(*ic_outer_class)] (null or cp_Utf8)
    These four-tuples are shared globally, like constant pool entries. In this specification, they are conventionally written <C,F,C2,N>, even though they are stored in a different order in the class file format. As a set, these globally defined four-tuples are called ic_All. There is usually no explicit linkage from individual classes in the archive to nested class records. Instead, when extracting a class file from a Pack200 archive, an subset of nested class records may be selected which is sufficient to describe all nested classes actually mentioned in the extracted class file's constant pool. For any class file X to be extracted, this subset will be called ic_Relevant(X), the relevant subset for X of ic_All. The algorithm for selecting the relevant subset is described later. Optionally, the compressor can specify, for any given class, an adjustment to its relevant subset, by transmitting a local InnerClasses attribute. This also is described in a later section on class attributes.

    The ic_this_class and ic_flags bands are both of length #ic_count, and the corresponding elements of these bands specify, for each tuple, the nested class identity (represented as a cp_Class reference) and the flags bitmask.

    The nested class flag bit at position 16 (as set in the mask 0x00010000) is inside the archive file to indicate if there are corresponding entries for the tuple in the ic_outer_class and ic_name bands. Thus, the length of both of these bands is the sum of all flag bits at position 16. Typically, only a few percent of nested classes need to set this bit and specify outer and name fields explicitly.

    If a tuple has an entry in the ic_outer_class and ic_name bands, these specify its outer class and simple name. (They are represented respectively as a possibly null cp_Class reference and a possibly null cp_Utf8 reference.) Otherwise, the tuple's outer class and name are said to be predicted. In this case, they must be correctly predictable from the name of the nested class itself, by parsing its spelling.

    A nested class has a bytecode name which names the class within class files. The spelling of this name, sometimes called a "mangled name", has extra punctuation signs and perhaps digits as well as the name of a containing class. If the bytecode name can be parsed into an outer class and a class name, and this class and name are identical with the true outer class and class name of the nested class, then we say the outer class and class name are predictable.

    The extraction of the predictable outer class and class name must follow the following grammar for class bytecode names, as applied to the spelling of the nested class name. (This grammar is independent of the grammar governing band structure, or any other grammar appearing in other parts of this specification.) The terminal DOLLAR refers to any character (such as '$' or '#') whose code is 0x2D or lower. The terminals SLASH refers to the slash or dot characters '/' or '.', which have the codes 0x2E and 0x2F. The terminal DIGIT refers to an ASCII decimal digit, one of the ten character codes from 0x30 to 0x39 inclusive. The terminal LETTER refers to any other character. That is, it refers to any character whose code is 0x3A or higher.

      bcn:
        (bcnCase1 | bcnCase2 | bcnCase3 | bcnCase4)
  bcnCase1:
        packageQual (namePart)? DOLLAR number
  bcnCase2:
        packageQual (namePart)? DOLLAR number DOLLAR predictableICName
  bcnCase3:
        predictableOuter DOLLAR predictableICName
  bcnCase4:
        packageQual (namePart)?

  predictableOuter:
        packageQual namePart
  predictableICName:
        LETTER (LETTER | DIGIT)*

  namePart:
        (LETTER | DIGIT | DOLLAR)+
  number:
        (DIGIT)+
  packageQual:
        (namePart SLASH)*

    This grammar ambiguously divides an arbitrary class name into several parts, which may include an optional predictedOuter prefix, an optional predictedICName suffix, and a optional numeric suffix. Any ambiguity must be resolved by preferring the alternative cases for bcn nonterminal in the order given. E.g., if bcnCase1 matches, it is used, even though either or both other cases may match also.

    The predictable nested class name is the string corresponding to the predictableICName nonterminal, if it was parsed. Otherwise the predictable nested class name is taken to be null.

    If a predictableOuter outer nonterminal is parsed, the corresponding string is the predictable outer class name. Otherwise the predictable outer class reference is taken to be null. Note that if a number nonterminal is parsed, no predictableOuter can be parsed. Here are some examples of prediction, nonprediction, and misprediction:
    nested class: member named Entry of java/util/Map
    mangled name: java/util/Map$Entry
    outer, name: java/util/Map, Entry
    predictable? | yes (since Map.Entry is a member of Map)
    nested class: anonymous
    mangled name: java/util/AbstractList$1
    outer, name: (none), (none)
    predictable? | yes (since the ic_name is null)
    nested class: non-member, named Local
    mangled name: java/util/AbstractList$2$Local
    outer, name: (none), Local
    predictable? | yes (since the ic_name is Local)
    nested class: non-member, named Local
    mangled name: java/util/AbstractList#2#Local
    outer, name: (none), Local
    predictable? | yes (since the ic_name is Local)
    nested class: member named $2$Local of Foo
    mangled name: Foo$$2$Local
    outer, name: (none), Local
    predictable? | no (outer name missing, ic_name mispredicted)
    nested class: class named Red$Herring
    mangled name: Red$Herring
    outer, name: Red, Herring
    predictable? | no (the predicted ic_name Herring)
    nested class: member named Q of X$1
    mangled name: X$1$Q
    outer, name: (none), Q
    predictable? | no (since Q is a member of X$1)
    nested class: member named Z of X$Y
    mangled name: X$Y$Z
    outer, name: X$Y, Z
    predictable? | yes (since X$Y.Z is a member of X$Y)
    nested class: member named Y$Z of X
    mangled name: X$Y$Z
    outer, name: X$Y, Z
    predictable? | no (outer name and ic_name are mispredicted)

    When a decompressor is processing a nested class name marked "predictable", it must parse the nested class's bytecode name into an enclosing class, an optional number, and an optional name. (The compressor might choose to always specify outer classes and names explicitly, in which case the decompressor would not be required to parse the nested class names at all. However, decompressors must always be prepared to perform this parsing.)

    If the compressor did not transmit an entry in cp_Utf8 or cp_Class for a predicted name or outer class, the decompressor must create such a constant internally. It will be referred to as a cp_Utf8 or cp_Class entry, even though it is not in the constant transmission sequence cp_All. However, if the compressor did transmit a constant with the same spelling as the predicted name or outer class, the decompressor must use that constant rather than creating a new one. The creation of such internal constants within the decompressor is detectable in an output file because they are inserted in a special order in the output file's constant pool. (See discussion of the output ordering rules below.)

    Please see the Appendix section for pseudo-code explaining this concept.

    When the decompressor receives the ic_this_class, ic_flags, ic_name, and ic_outer_class bands, and performs any required name parsing, it creates the set ic_All of four-tuples. This set is the primary source of InnerClasses attributes synthesized for individual class files by the decompressor.

    5.8. Class Schema

    The purpose of the Pack200 archive is to transmit a set of classes in a form which a decompressor can later use to reconstruct class files. As a rule, each separate kind of data stored in class files is transmitted in a band dedicated to all values of that kind. Here is the band structure for all class-specific information except bytecodes:
      class_bands:
        *class_this :DELTA5 [#class_count] (cp_Class)
        *class_super :DELTA5 [#class_count] (cp_Class)
        *class_interface_count [#class_count] :DELTA5
        *class_interface :DELTA5 [SUM(*class_interface_count)] (cp_Class)
        *class_field_count :DELTA5 [#class_count]
        *class_method_count :DELTA5 [#class_count]

        *field_descr :DELTA5 [SUM(*class_field_count)] (cp_Descr)
        field_attr_bands

        *method_descr :MDELTA5 [SUM(*class_method_count)] (cp_Descr)
        method_attr_bands

        class_attr_bands
        code_bands

    The class_this, class_super, class_flags_lo, class_flags_hi (if present), class_interface_count, class_field_count, and class_method_count bands are all of length #class_count, and the corresponding elements of these bands transmit in turn each class's name and super-class, and the number of implemented interfaces, declared fields, and declared methods. (The access modifier bits in each class's flags word are mixed with attribute indicators, and are transmitted in class_flags_lo, as defined above.)

    The class_interface band contains runs of class interface declarations, one run for each element of class_interface_count, and applying to the corresponding class.

    Each element of class_this, class_super, and class_interface is a reference (in fact, a non-null reference) to the constant pool cp_Class.

    In the unique case of java/lang/Object, the stored super-class must be a null reference. Rather than disturbing the transmission of all other elements of the class_super band, we use the convention that a compressor, when it encounters a null super-class reference, must transmit in its place a duplicate of the current class's reference. (Since it is illegal for a class to inherit from itself, this renumbering of null references is unambiguous.)

    The field_descr bands contain one run of elements for each element of class_field_count, and apply to successive fields in the corresponding class. The method_descr bands contain one run of elements for each element of class_method_count, and apply to successive methods in the corresponding class.

    (Unlike the class file format, field and method descriptors are stored as single references to a "name-and-type" constant pool, rather than as pairs of name references and type references.)

    The method_descr band has a primary encoding which performs best if the method references are mostly sorted. Compressors may elect to take advantage of this fact by sorting the methods in each class. (Note: It is generally acceptable for compressors to reorder methods for best compression, but fields must not be reordered, since their order is apparent through reflection and significant to some facilities, such as serialization.)

    Attribute bands are placed in the positions indicated by the grammar. They are described below. The attribute bands include flags bands, which carry both access modifiers and attribute indicators for the corresponding classes, fields, and methods.

    The Pack200 archive ends with bands devoted to method code blocks and the bytecodes themselves. If a method has a code attribute, the compressor must mention it in the flags bit (the 6th LSB) to which it is assigned, or as an overflow attribute (with an index of 6). The fields of a Code attribute are transmitted in the bands organized under the code_bands nonterminal.

    The specification of each Code attribute begins with three key parameters, which declare the number of stack and local slots, and the number of handlers. #Stack is the number of stack slots used by the code. #NALocal is the number of non-argument locals used by the code. (The actual number of locals declared in the class file will be #NALocal plus the number of locals required by method parameters, as determined by the method's signature.) #Handler is the number of exception handlers.

    . The code_headers band contains a series of bytes, each of which tersely encodes the first three key parameters of a code attribute: Each of the 255 non-zero byte values encodes a unique triple of #NALocal, #Stack, and #Handler. There is (of course) one code header for each Code attribute transmitted.

    The special code header byte zero (0x00) indicates that the code attribute's three parameters are to be found, instead, in the code_max_stack, code_max_na_locals, and code_handler_count bands. If the code header byte is non-zero, these three bands do not transmit entries for the corresponding Code attribute.

    The code_flags_lo band transmits an entry for a corresponding Code attribute if and only if one or both of the following is true: the Code attribute's code header byte is zero, or the have_all_code_flags bit is set in the #archive_options word. If a Code attribute does not have a transmitted code_flags_lo value, its flags word is taken to be zero, and it has no sub-attributes. The code_flags_hi band transmits a corresponding entry if and only if the code_flags_lo value was transmitted as just described, and also #have_code_flags_hi is set.

    Non-zero code header bytes denote code attribute parameters according to the following scheme:
    Header Range | #Stack | #NALocal | #Handler
    1 <= x="x" <="144 | (x-1) % 12 | (x-1) / 12 | 0
    145 <= x="x" <="208 | (x-145) % 8 | (x-145) / 8 | 1
    209 <= x="x" <="255 | (x-209) % 7 | (x-209) / 7 | 2
    x = 0 | code_max_stack | code_max_na_locals | code_handler_count
    This scheme allows a single byte to describe a Code attribute in about 95% of all cases. (Note: If debugging attributes are not stripped, the compressor should probably set the have_all_code_flags bit, so that the presence of these attributes will not force the use of the special zero code header byte.)

    Regardless of whether the exception handler count is encoded in the one-byte code header, or whether it is an explicit element of code_handler_count, for each code attribute there is a run of values in code_handler_start_P, code_handler_end_PO, code_handler_catch_PO, and code_handler_class_RCN, one for each handler, as if those bands were governed by an attribute layout 'NV[PHPOHPOHRCNH]' (there is no band governed by the 'NV' layout element itself; it is the handler count).

    That is, each triplet of Handler.start, Handler.end, and Handler.catch values are transmitted as renumbered (by renumber_bci). Also, Handler.end is transmitted as a difference of its renumbering with that of Handler.start in the same triplet, and Handler.catch is transmitted as a difference of its renumbering with that of Handler.end in the same triplet. Finally, code_handler_class_RCN is transmitted as an incremented reference into cp_Class, or zero if the handler class reference is null.

      code_bands:
        *code_headers :BYTE1 [COUNT(Code,...)]

        *code_max_stack :UNSIGNED5 [COUNT(0,*code_headers)]
        *code_max_na_locals :UNSIGNED5 [COUNT(0,*code_headers)]

        *code_handler_count :UNSIGNED5 [COUNT(0,*code_headers)]
        *code_handler_start_P :BCI5 [SUM(*code_handler_count)]
        *code_handler_end_PO :BRANCH5 [SUM(*code_handler_count)]
        *code_handler_catch_PO :BRANCH5 [SUM(*code_handler_count)]
        *code_handler_class_RCN :UNSIGNED5 [SUM(*code_handler_count)] (null or cp_Class)

        code_attr_bands

    5.9. Attribute Bands

    Here, collected in one place, are the bands which transmit attributes. If the compressor sets bits in the flags word of a class, field, or method, and those bits are assigned (by the compressor) to attributes, then the compressor must also retrieve the stored values governed by each selected attribute layout and transmit them in the bands governed by that layout.

    If the compressor marks a class (resp. field, method, or code) as having overflow attributes, it must transmit a corresponding element in the class_attr_count band (resp. field_attr_count, method_attr_count, or code_attr_count band). This count, in turn, specifies the size of a run in class_attr_indexes (resp. field_attr_indexes, method_attr_indexes, or code_attr_indexes) of indexes of attribute layouts governing attributes of the class (resp. field, method, or code). The compressor must transmit a attribute layout definition index for each overflow attribute.

    For each attribute layout selected by a bit in an element of class_flags or by an element of class_attr_indexes, the compressor must retrieve data governed by the layout elements from the class attribute and transmit elements encoding this data in the bands governed by the layout. Similar conditions apply for field, method, and code attributes.

    For each attribute layout that transmits data and contains backward calls, the compressor must transmit the number of times each backward callable will be the subject of a backward call as the decompressor works its way through attribute layouts. These call counts are transmitted in the class_attr_calls, field_attr_calls, method_attr_calls, and code_attr_calls bands, according to the context type of the layouts they apply to. The call counts are transmitted, one per backward callable, in the definition order of the callables. (See above.) Call counts are only transmitted for backward callables which occur within layouts that are used at least once. Call counts do not count entries to any callable because of a forward call, nor do they count the initial call to a callable which initiates attribute processing. A call count might be zero if a backward callable occurs in a layout that is used, but which does not happen to reach the backward callable. These call counts are needed to break a circularity inherent in the sizing of bands for mutually-recursive layouts. They provide the minimum information necessary for the decompressor to locate all the bands in the archive, prior to distributing the band values to the various output classes. For this reason, the call counts are supplied one per layout, summed over all attribute occurrences of that each layout.

    The decompressor is responsible for processing any explicit attribute layout definitions transmitted by the compressor. It must prepare to receive the additional bands governed by those layouts. When it reads layout definition indexes, it must prepare to read in the correct number of values transmitted in each of those additional bands.

    The grammar of bands defined in this specification includes bands governed by all predefined attribute layouts. For clarity, some band names mention a part of the layout element that created them. Note that the Deprecated attributes have no bands, because their layouts are empty.

    Attributes named "Synthetic", although part of the standard class file format in earlier versions of Java, are not directly supported in this specification, because that attribute has been replaced by a new flag bit (ACC_SYNTHETIC, 0x1000) in more recent versions of Java. However, compressors are encouraged to process Synthetic attributes, and any other zero-length attributes not predefined here, by assigning them unused flag bits, and emitting explicit zero-length layout definitions for decompressors to follow.

    If the compressor elects to define new layouts, the bands governed by those layouts are added immediately after the bands for the predefined layouts. (The order and structure of the predefined attribute bands reflects the predefined layout definitions in a regular way, as if the compressor had in fact defined them explicitly.)

      class_attr_bands:
        *class_flags_hi :UNSIGNED5 [#class_count*#have_class_flags_hi]
        *class_flags_lo :UNSIGNED5 [#class_count]
        *class_attr_count :UNSIGNED5 [COUNT(1<<16,...)]
        *class_attr_indexes :UNSIGNED5 [SUM(*class_attr_count)]
        *class_attr_calls :UNSIGNED5 [...]
        *class_SourceFile_RUN :UNSIGNED5 [COUNT(SourceFile,...)] (null or cp_Utf8)
        *class_EnclosingMethod_RC :UNSIGNED5 [COUNT(EnclosingMethod,...)] (cp_Class)
        *class_EnclosingMethod_RDN :UNSIGNED5 [COUNT(EnclosingMethod,...)] (null or cp_Descr)
        *class_Signature_RS :UNSIGNED5 [COUNT(Signature,..)] (cp_Signature)
        class_metadata_bands
        ic_local_bands
        *class_file_version_minor_H :UNSIGNED5 [COUNT(version,...)]
        *class_file_version_major_H :UNSIGNED5 [COUNT(version,...)]

  field_attr_bands:
        *field_flags_hi :UNSIGNED5 [SUM(*class_field_count)*#have_field_flags_hi]
        *field_flags_lo :UNSIGNED5 [SUM(*class_field_count)]
        *field_attr_count :UNSIGNED5 [COUNT(1<<16,...)]
        *field_attr_indexes :UNSIGNED5 [SUM(*field_attr_count)]
        *field_attr_calls :UNSIGNED5 [...]
        *field_ConstantValue_KQ :UNSIGNED5 [COUNT(ConstantValue,...)] (cp_Int, etc.; see note)
        *field_Signature_RS :UNSIGNED5 [COUNT(Signature,...)] (cp_Signature)
        field_metadata_bands

  method_attr_bands:
        *method_flags_hi :UNSIGNED5 [SUM(*class_method_count)*#have_method_flags_hi]
        *method_flags_lo :UNSIGNED5 [SUM(*class_method_count)]
        *method_attr_count :UNSIGNED5 [COUNT(1<<16,...)]
        *method_attr_indexes :UNSIGNED5 [SUM(*method_attr_count)]
        *method_attr_calls :UNSIGNED5 [...]
        *method_Exceptions_N :UNSIGNED5 [COUNT(Exceptions,...)]
        *method_Exceptions_RC :UNSIGNED5 [SUM(*method_Exceptions_N)] (cp_Class)
        *method_Signature_RS :UNSIGNED5 [COUNT(Signature,...)] (cp_Signature)
        method_metadata_bands

  code_attr_bands:
        *code_flags_hi :UNSIGNED5 [...*#have_code_flags_hi]
        *code_flags_lo :UNSIGNED5 [...]
        *code_attr_count :UNSIGNED5 [COUNT(1<<16,...)]
        *code_attr_indexes :UNSIGNED5 [SUM(*code_attr_count)]
        *code_attr_calls :UNSIGNED5 [...]
        *code_StackMapTable_N :UNSIGNED5 [COUNT(StackMapTable,...)]
        *code_StackMapTable_frame_T :BYTE1 [SUM(*code_StackMapTable_N)]
        *code_StackMapTable_local_N :UNSIGNED5 [COUNT(255,*code_StackMapTable_frame_T)]
        *code_StackMapTable_stack_N :UNSIGNED5 [COUNT(255,*code_StackMapTable_frame_T)]
        *code_StackMapTable_offset :UNSIGNED5 [...]
        *code_StackMapTable_T :BYTE1 [...]
        *code_StackMapTable_RC :UNSIGNED5 [COUNT(7,*code_StackMapTable_T)]
        *code_StackMapTable_P :BCI5 [COUNT(8,*code_StackMapTable_T)]
        *code_LineNumberTable_N :UNSIGNED5 [...]
        *code_LineNumberTable_bci_P :BCI5 [...]
        *code_LineNumberTable_line :UNSIGNED5 [...]
        *code_LocalVariableTable_N :UNSIGNED5 [...]
        *code_LocalVariableTable_bci_P :BCI5 [...]
        *code_LocalVariableTable_span_O :BRANCH5 [...]
        *code_LocalVariableTable_name_RU :UNSIGNED5 [...] (cp_Utf8)
        *code_LocalVariableTable_type_RS :UNSIGNED5 [...] (cp_Signature)
        *code_LocalVariableTable_slot :UNSIGNED5 [...]
        *code_LocalVariableTypeTable_N :UNSIGNED5 [...]
        *code_LocalVariableTypeTable_bci_P :BCI5 [...]
        *code_LocalVariableTypeTable_span_O :BRANCH5 [...]
        *code_LocalVariableTypeTable_name_RU :UNSIGNED5 [...] (cp_Utf8)
        *code_LocalVariableTypeTable_type_RS :UNSIGNED5 [...] (cp_Signature)
        *code_LocalVariableTypeTable_slot :UNSIGNED5 [...]

    A class possesses a "class-file version" pseudo-attribute if its class file's minor or major version differs from the #default_class_minver or #default_class_majver, respectively. This pseudo-attribute is a pair of 16-bit integers giving the major and minor version numbers of the class's file. These integers are stored in the header of the class's file, rather than in an attribute record. As is the convention with classfiles, the minor version number comes first. Thus minor version numbers are transmitted in the band class_file_version_minor_H, and major version numbers in class_file_version_major_H. Decompressors are not required to process archives with greater minor or major version numbers than those of the specification they were engineered to process. Decompressors are required to to process archives with the same major and smaller or equal minor version numbers.

    Local InnerClasses Attributes
    A transmitted class may possess a local InnerClasses attribute, which is taken to be an adjustment to that class file's eventually written InnerClasses attribute. Specifically, the local InnerClasses attribute specifes a set of four-tuples which must be combined with a corresponding relevant subset drawn from ic_All. The algorithm for doing this is described fully later, but it amounts to starting with the subset of four-tuples from ic_All which pertain to CONSTANT_Class entries of the output constant pool (barring CONSTANT_Class entries required only by the InnerClasses attribute itself), and then forming the set symmetric difference between that relevant set and the local InnerClasses attribute.

    The four-tuples of all local InnerClasses attributes are transmitted in five bands:

      ic_local_bands:
        *class_InnerClasses_N :UNSIGNED5 [COUNT(InnerClasses,...)]
        *class_InnerClasses_RC :UNSIGNED5 [SUM(*class_InnerClasses_N)] (cp_Class)
        *class_InnerClasses_F :UNSIGNED5 [SUM(*class_InnerClasses_N)]
        *class_InnerClasses_outer_RCN :UNSIGNED5 [COUNT(!=0,*class_InnerClasses_F)]  (null or cp_Class)
        *class_InnerClasses_name_RUN :UNSIGNED5 [COUNT(!=0,*class_InnerClasses_F)] (null or cp_Utf8)

    Each four-tuple <C,F,C2,N> transmitted in these attribute bands is called a local IC tuple. (Note that the class file format stores the elements of these four-tuples in a different order, (C,C2,N,F).) For a given class file X, the sequence of local IC tuples is called ic_Local(X).

    For each local IC tuple, the compressor transmits, at minimum, a C value and an F value. If a transmitted flags value F is not zero, there are also corresponding transmitted constant pool references C2 and N. As a whole, the transmitted local tuple may or may not be equivalent to a global tuple from ic_All.

    As an abbreviation, the compressor may transmit only a C and a flags value of zero, if the local IC tuple to be transmitted is equivalent to a member of ic_All, and no other member of ic_All defines the same class C. In this case the decompressor must behave exactly as if all four tuple components had been explicitly transmitted.

    (If all four components of a local tuple are transmitted, and the flags value to be transmitted is in fact zero, the value 0x00010000 must be transmitted instead of zero for the flags.)

    Frequently, the compressor will not need to transmit any local IC tuples at all, since the set of four-tuples to be stored in the class's InnerClasses attribute will be exactly ic_Relevant(X), with no adjustment required. If extraneous four-tuples (beyond those required by a minimized constant pool) are found in the input class file, then some local IC tuples will be needed (with zero flags), to provide local "roots" for the extra InnerClasses entries. This can occur if a compiler requires an InnerClasses entry for a class mentioned only in a signature. Compressors are required to predict which classes require such extra local roots, and transmit only the unexpected four-tuples.

    5.9.1. Metadata Transmission
    There are nine groups of bands governed by the metadata layouts. They are summarized here.
      class_metadata_bands:
        class_RVA_bands
        class_RIA_bands

  field_metadata_bands:
        field_RVA_bands
        field_RIA_bands

  method_metadata_bands:
        method_RVA_bands
        method_RIA_bands
        method_RVPA_bands
        method_RIPA_bands
        method_AD_bands

  class_RVA_bands:
        *class_RVA_anno_N :UNSIGNED5 [...]
        *class_RVA_type_RS :UNSIGNED5 [...] (cp_Signature)
        *class_RVA_pair_N :UNSIGNED5 [...]
        *class_RVA_name_RU :UNSIGNED5 [...] (cp_Utf8)
        *class_RVA_T :BYTE1 [...]
        *class_RVA_caseI_KI :UNSIGNED5 [...] (cp_Int)
        *class_RVA_caseD_KD :UNSIGNED5 [...] (cp_Double)
        *class_RVA_caseF_KF :UNSIGNED5 [...] (cp_Float)
        *class_RVA_caseJ_KJ :UNSIGNED5 [...] (cp_Long)
        *class_RVA_casec_RS :UNSIGNED5 [...] (cp_Signature)
        *class_RVA_caseet_RS :UNSIGNED5 [...] (cp_Signature)
        *class_RVA_caseec_RU :UNSIGNED5 [...] (cp_Utf8)
        *class_RVA_cases_RU :UNSIGNED5 [...] (cp_Utf8)
        *class_RVA_casearray_N :UNSIGNED5 [...]
        *class_RVA_nesttype_RS :UNSIGNED5 [...] (cp_Signature)
        *class_RVA_nestpair_N :UNSIGNED5 [...]
        *class_RVA_nestname_RU :UNSIGNED5 [...] (cp_Utf8)

  class_RIA_bands:
        *class_RIA_anno_N :UNSIGNED5 [...]
        (analogous to class_RVA_bands)

  field_RVA_bands:
        *field_RVA_anno_N :UNSIGNED5 [...]
        (analogous to class_RVA_bands)

  field_RIA_bands:
        *field_RIA_anno_N :UNSIGNED5 [...]
        (analogous to field_RVA_bands)

  method_RVA_bands:
        *method_RVA_anno_N :UNSIGNED5 [...]
        (analogous to class_RVA_bands)

  method_RIA_bands:
        *method_RIA_anno_N :UNSIGNED5 [...]
        (analogous to method_RIA_bands)

  method_RVPA_bands:
        *method_RVPA_param_NB :BYTE1 [...]
        *method_RVPA_anno_N :UNSIGNED5 [...]
        (analogous to method_RVA_bands)

  method_RIPA_bands:
        *method_RIPA_param_NB :BYTE1 [...]
        *method_RIPA_anno_N :UNSIGNED5 [...]
        (analogous to method_RVPA_bands)

  method_AD_bands
        *method_AD_T :BYTE1 [...]
        *method_AD_caseI_KI :UNSIGNED5 [...] (cp_Int)
        *method_AD_caseD_KD :UNSIGNED5 [...] (cp_Double)
        *method_AD_caseF_KF :UNSIGNED5 [...] (cp_Float)
        *method_AD_caseJ_KJ :UNSIGNED5 [...] (cp_Long)
        *method_AD_casec_RS :UNSIGNED5 [...] (cp_Signature)
        *method_AD_caseet_RS :UNSIGNED5 [...] (cp_Signature)
        *method_AD_caseec_RU :UNSIGNED5 [...] (cp_Utf8)
        *method_AD_cases_RU :UNSIGNED5 [...] (cp_Utf8)
        *method_AD_casearray_N :UNSIGNED5 [...]
        *method_AD_nesttype_RS :UNSIGNED5 [...] (cp_Signature)
        *method_AD_nestpair_N :UNSIGNED5 [...]
        *method_AD_nestname_RU :UNSIGNED5 [...] (cp_Utf8)

    As an aid to understanding the metadata layout, here is a brief description of each of the method metadata bands, as used by classfiles which comply with JSR 175. The class and field metadata bands function in a similar way.

    Note that JSR 175 does not allow embedded references to CONSTANT_Class entries, even where a reference to a class is required. Instead, JSR 175 requires that references to classes be encoded as field signatures. (Their names are bracketed by 'L' and ';'.) The Pack200 archive transmits all such values as references into cp_Signature, not cp_Class.

    For each use of a parameter annotation attribute, the method_RVPA_param_NB band or method_RIPA_param_NB band (for invisible annotations) transmits an unsigned byte indicating the parameter count. For each use of a non-parameter annotation attribute, the method_RVA_anno_N band or method_RIA_anno_N band (for invisible annotations) transmits an annotation count. Likewise, for each annotated parameter, the method_RVPA_anno_N band or method_RIPA_anno_N band (for invisible annotations) transmits an annotation count.

    For each visible non-parameter annotation, the method_RVA_type_RS band transmits an annotation's type, and the method_RVA_pair_N band transmits the number of that annotation's member-value pairs. Analogous values for invisible annotations and parameter annotations are transmitted in the bands method_RIA_type_RS, method_RIA_pair_N, method_RVPA_type_RS, method_RVPA_pair_N, method_RIPA_type_RS, and method_RIPA_pair_N. For each member-value pair transmitted as a direct part of a visible non-parameter annotation, the method_RVA_name_RU band transmits the member name. Analogous values for invisible annotations and parameter annotations are transmitted in the bands method_RIA_name_RU, method_RVPA_name_RU, and method_RIPA_name_RU.

    For each value transmitted with a visible non-parameter annotation, whether directly, or indirectly via a nested value or annotation, the method_RVA_T band transmits a byte which selects the format of the annotation value, and analogous values are transmitted in the bands method_RIA_T, method_RVPA_T, method_RIPA_T, and (for annotation defaults) method_AD_T, Direct uses of these value tag bands are counted by summing the values of the corresponding preceding pair-count band (method_RVA_pair_N, etc.). This count also includes the sum of the corresponding following nested pair-count band (method_RVA_nestpair_N, etc.) and nested array length bands (method_RVA_casearray_N, etc.).

    Since those latter sums come from backward calls in the attribute layout, they cannot be directly computed by the decompressor, but their sum is reported by the compressor as an element of method_attr_calls. (Note that the last callable in each metadata layout is the target of two backward calls from inside itself.) That band contains these backward call counts for method_RVA_T, method_RIA_T method_RVPA_T, method_RIPA_T method_AD_T, in that order. If there are no occurrences of a method metadata attribute, then the corresponding backward call is omitted. (Thus, there are up to five backward call counts transmitted for method metadata.) If there are compressor-defined recursive layouts used in the archive, their backward call counts follow the counts for metadata in method_attr_calls.

    For each value tag of 'B', 'C', 'I', 'S', or 'Z', there is a corresponding element transmitted in method_RVA_caseI_KI which supplies the value as a cp_Int reference. Analogous integer references within invisible and parameter annotations and annotation defaults are transmitted in the bands method_RIA_caseI_KI, method_RVPA_caseI_KI, method_RIPA_caseI_KI, and method_AD_caseI_KI. For each value tag of 'e', the bands method_RVA_caseet_RS and method_RVA_caseec_RU transmit the signature of the class and name of the member of an enumeration constant, as references into cp_Signature and cp_Utf8. For each value tag of '[', the band method_RVA_casearray_N transmits the length of a nested value array. For each value tag of '@', the bands method_RVA_nesttype_RS and method_RVA_nestpair_N transmit the class signtaure of a nested annotation and the number of its pairs. For each pair in such a nested annotation, the band method_RVA_nestname_RU transmits the name of the pair.

    The bands in the following table transmit appropriately-typed constant pool references for each occurence of specific tag characters.
    Tag(s) | Band | Reference
    'B','C','I','S','Z' | method_RVA_caseI_KI | cp_Int
    'D' | method_RVA_caseD_KD | cp_Double
    'F' | method_RVA_caseF_KF | cp_Float
    'J' | method_RVA_caseJ_KJ | cp_Long
    'c' | method_RVA_casec_RS | cp_Signature
    'e' method_RVA_caseet_RS
    method_RVA_caseec_RU     		cp_Signature
    cp_Utf8
    's' | method_RVA_cases_RU | cp_Utf8

    Analogous groups of bands transmit values within the other four method annotation types, and within the visible and invisible annotations of classes and fields.

    5.10. Bytecode Instructions

    The last part of the Pack200 archive is a series of bands transmitting the bytecodes themselves. The bytecodes of each method code are parsed into instructions and operands transmitted in their own bands. Each method code corresponds to a run of bytecodes which ends with the distinguished code value 0xFF (255), which serves as an end marker. (Note that it is unusual for band data to be delimited by an end marker: Usually it is sized by a count in a previous band.)

    Here are the bands which transmit bytecode instructions:

      bc_bands:
        *bc_codes :BYTE1 [...]
        *bc_case_count :UNSIGNED5 [COUNT(switch,*bc_codes)]
        *bc_case_value :DELTA5 [...]
        *bc_byte :BYTE1 [...]
        *bc_short :DELTA5 [...]
        *bc_local :UNSIGNED5 [...]
        *bc_label :BRANCH5 [...]
        *bc_intref :DELTA5 [...] (cp_Int)
        *bc_floatref :DELTA5 [...] (cp_Float)
        *bc_longref :DELTA5 [...] (cp_Long)
        *bc_doubleref :DELTA5 [...] (cp_Double)
        *bc_stringref :DELTA5 [...] (cp_String)
        *bc_classref :UNSIGNED5 [...] (current class or cp_Class)
        *bc_fieldref :DELTA5 [...] (cp_Field)
        *bc_methodref :UNSIGNED5 [...] (cp_Method)
        *bc_imethodref :DELTA5 [...] (cp_Imethod)
        *bc_thisfield :UNSIGNED5 [...] (cp_Field, only for current class)
        *bc_superfield :UNSIGNED5 [...] (cp_Field, only for current super)
        *bc_thismethod :UNSIGNED5 [...] (cp_Method, only for current class)
        *bc_supermethod :UNSIGNED5 [...] (cp_Method, only for current super)
        *bc_initref :UNSIGNED5 [...] (cp_Field, only for most recent new)
        *bc_escref :UNSIGNED5 [...] (cp_All)
        *bc_escrefsize :UNSIGNED5 [...]
        *bc_escsize :UNSIGNED5 [...]
        *bc_escbyte :BYTE1 [...]

    In order to transmit bytecode instructions more efficiently, some instructions may be rewritten into a transmission form. The ldc, ldc_w, and ldc2_w bytecodes must be rewritten by the compressor into strongly-typed operations; see below. Some getstatic, putstatic, getfield, putfield, invokevirtual, invokespecial, and invokestatic bytecodes may (at the compressor's option) be rewritten into more specialized and compact forms which, because they are context sensitive, select their operands from a smaller set of possibilities.

    In all cases, the first byte of each instruction (perhaps rewritten) is determined by a byte transmitted in bc_codes. All operand bytes are decoded into operands and transmitted in separate bands according to the type of operand encoded. The padding bytes of switch instructions and the last two bytes of invokeinterface instructions are discarded, because they can be reconstructed by the decompressor.

    A "wide" prefix bytecode is transmitted in bc_codes. The instruction following the prefix is decoded in its wide format, but (except in the case of iinc) it is transmitted in the same way, and using the same bands, as the normal (non-wide) format. The wide format of the iinc instruction uses bc_short instead of bc_byte to transmit its second operand.

    Every branch instruction transmits its target (or targets, in the case of the switches) in the bc_label band, encoded as the difference between the renumbered BCI of the branch target and the renumbered BCI of the branch itself. (The renumbering, as described above, numbers the first instruction as zero, the second as one, and so forth.) Differences between renumbered BCIs are very compact; the primary encoding of BRANCH5 also takes advantage of the fact that most such differences are positive, because most branches are forward branches.

    The bc_classref band carries incremented indexes into the cp_Class constant pool. The incrementing (by unity) reserves the code zero, which always refers to the current class. (This provides a a compact form for the most common class reference, which is a self-reference.)

    The bc_byte and bc_short bands carry fixed-sized operands. These operands are not transmitted as general 32-bit integers because their instructions, as originally defined, already serve as specially compressed transmission formats. Integer values of these bands are treated as unsigned, even when they are semantically signed as operands. The bc_byte band is used for the last operands of multianewarray and non-wide iinc instructions, and for the operands of bipush and newarray instructions. The bc_short band is used for the last operands of wide iinc instructions, and for the operands of sipush instructions.

    The bands bc_intref, bc_floatref, bc_longref, bc_doubleref, bc_stringref, bc_fieldref, bc_methodref, and bc_imethodref transmit ordinary indexes into the constant pools cp_Int, cp_Float, cp_Long, cp_Double, cp_String, cp_Field, cp_Method, and cp_Imethod, respectively.

    For every lookupswitch or tableswitch instruction, the number of cases is transmitted in bc_case_count, and the default label is transmitted in bc_label. Each case value and case target of a lookupswitch is transmitted in bc_case_value and bc_label, respectively. The initial case value of a tableswitch is transmitted in bc_case_value, and each of its case targets is transmitted in bc_label.

    If the the first byte of an instruction has a code in the range [202..255], or if an instruction's operands cannot be parsed according to the requirements of this specification, it is a non-standard instruction. Every byte of a non-standard instruction must be transmitted in a special envelope in order to warn the decompressor to accept it literally. The envelope consists of a series of "byte_escape" and "ref_escape" opcodes in the bc_code band, corresponding sizes in bc_escsize and bc_escrefsize, bytes in bc_escbyte, and constant pool references in bc_escref. Every constant pool reference in a non-standard instruction must be escaped and transmitted in the bc_escref band. Each ref_escape wraps one such constant pool reference, of size up to four bytes. The transmitted reference is an index into cp_All, such that zero refers to the first CONSTANT_Utf8 constant, and so on.
    Escape
    Opcode     		Size
    Operand     		Operand
    Size     		Size
    Band     		Data
    Band     		Opcode
    Value
    byte_escape | N<=255 | N bytes | bc_escsize | bc_escbyte | 254
    ref_escape | N<=2 | N bytes | bc_escrefsize | bc_escref | 253

    There is no need for special transmission of any other operand type within non-standard instructions, because the Pack200 format exactly preserves all instruction bytes except for constant pool references. This specification does not address the means by which compressors adapt to the presence and format of non-standard instructions. It simply requires decompressors to decode them correctly.

    Here is a table of the specially rewritten transmission forms for instructions:
    Original
    Instruction     		Operand Transmission
    Instruction     		Rewrite
    Required?     		Opcode
    ldc | cp_String[i] | aldc | yes | 18 (=ldc)
    ldc | cp_Class[i] | cldc | yes | 233
    ldc | cp_Int[i] | ildc | yes | 234
    ldc | cp_Float[i] | fldc | yes | 235
    ldc_w | cp_String[i] | aldc_w | yes | 19 (=ldc_w)
    ldc_w | cp_Class[i] | cldc_w | yes | 236
    ldc_w | cp_Int[i] | ildc_w | yes | 237
    ldc_w | cp_Float[i] | fldc_w | yes | 238
    ldc2_w | cp_Long[i] | lldc2_w | yes | 20 (=ldc2_w)
    ldc2_w | cp_Double[i] | dldc2_w | yes | 239
    getstatic | (this class member) | getstatic_this | no | 202
    putstatic | (this class member) | putstatic_this | no | 203
    getfield | (this class member) | getfield_this | no | 204
    putfield | (this class member) | putfield_this | no | 205
    invokevirtual | (this class member) | invokevirtual_this | no | 206
    invokespecial | (this class member) | invokespecial_this | no | 207
    invokestatic | (this class member) | invokestatic_this | no | 208
    aload_0; getstatic | (this class member) | aload_0_getstatic_this | no | 209
    aload_0; putstatic | (this class member) | aload_0_putstatic_this | no | 210
    aload_0; getfield | (this class member) | aload_0_getfield_this | no | 211
    aload_0; putfield | (this class member) | aload_0_putfield_this | no | 212
    aload_0; invokevirtual | (this class member) | aload_0_invokevirtual_this | no | 213
    aload_0; invokespecial | (this class member) | aload_0_invokespecial_this | no | 214
    aload_0; invokestatic | (this class member) | aload_0_invokestatic_this | no | 215
    getstatic | (super class member) | getstatic_super | no | 216
    putstatic | (super class member) | putstatic_super | no | 217
    getfield | (super class member) | getfield_super | no | 218
    putfield | (super class member) | putfield_super | no | 219
    invokevirtual | (super class member) | invokevirtual_super | no | 220
    invokespecial | (super class member) | invokespecial_super | no | 221
    invokestatic | (super class member) | invokestatic_super | no | 222
    aload_0; getstatic | (super class member) | aload_0_getstatic_super | no | 223
    aload_0; putstatic | (super class member) | aload_0_putstatic_super | no | 224
    aload_0; getfield | (super class member) | aload_0_getfield_super | no | 225
    aload_0; putfield | (super class member) | aload_0_putfield_super | no | 226
    aload_0; invokevirtual | (super class member) | aload_0_invokevirtual_super | no | 227
    aload_0; invokespecial | (super class member) | aload_0_invokespecial_super | no | 228
    aload_0; invokestatic | (super class member) | aload_0_invokestatic_super | no | 229
    invokespecial | (this class <init>) | invokespecial_this_init | no | 230
    invokespecial | (super class <init>) | invokespecial_super_init | no | 231
    invokespecial | (new class <init>) | invokespecial_new_init | no | 232

    Every bytecode instruction is contained by a class, called the current class. The superclass (if any) of the current class is the current super class. The operand of the textually most recent "new" instruction (in the same method) is called the current new class.

    If an instruction refers to a field or method in the current class, it may (at the compressor's option) be rewritten for transmission as a corresponding opcode spelled with "_this". Likewise, an instruction referring to a field or method in the current super class may be rewritten as a corresponding opcode spelled with "_super". In either case, if the immediately preceding instruction is aload_0 (opcode 42), the transmission of that instruction may be suppressed by the compressor, and the corresponding opcode spelled with "aload_0_" selected instead; otherwise the "aload_0_" variant may not be selected.

    If an invokespecial instruction refers to a method named <init> in the current class, the current super class, or the current new class, the compressor may choose to rewrite it as an invokespecial_this_init, invokespecial_super_init, or invokespecial_new_init, respectively.

    Field (resp. method) operands of rewritten instructions spelled with "_this" (but not "_init") are transmitted in the special band bc_thisfield (resp. bc_thismethod). The numbering of these operands is defined by taking the sequence of symbols in cp_Field (resp. cp_Method) and selecting only members of the current class. The resulting subset, without changing its order, is renumbered starting with zero. This provides a compact mapping of small integers to members of the current class.

    Likewise, operands of rewritten instructions spelled with "_super" (but not "_init") are transmitted in the bc_superfield or bc_supermethod band, and renumbered as a subset of cp_Field or cp_Method, selecting only members of the current super class.

    Finally, operands of the rewritten instructions spelled with "_init" are transmitted in the band bc_initref, and renumbered as a subset of cp_Method, selected according to the appropriate class (current, current super, or current new), and also selected to have the name <init>. (The index transmitted is usually very small; in effect it selects only the signature of the invoked method, and most classes possess only a few constructors.)

    Here is a table summarizing the transmission of instructions of more than one byte.
    Instruction Operand Transmitted
    Value     		Band
    bipush | (byte) x | x & 0xFF | bc_byte
    sipush | (short) x | x & 0xFFFF | bc_short
    ildc | cp_Int[i] | i | bc_intref
    fldc | cp_Float[i] | i | bc_floatref
    aldc | cp_String[i] | i | bc_stringref
    cldc | current class | 0 | bc_classref
    cldc | cp_Class[i] | i+1 | bc_classref
    ildc_w | cp_Int[i] | i | bc_intref
    fldc_w | cp_Float[i] | i | bc_floatref
    aldc_w | cp_String[i] | i | bc_stringref
    cldc_w | current class | 0 | bc_classref
    cldc_w | cp_Class[i] | i+1 | bc_classref
    lldc2_w | cp_Long[i] | i | bc_long
    dldc2_w | cp_Double[i] | i | bc_double
    *load | locals[i] | i | bc_local
    *store | locals[i] | i | bc_local
    ret | locals[i] | i | bc_local
    iinc | locals[i] | i | bc_local
    iinc (not wide) | (byte) x | x & 0xFF | bc_byte
    iinc (wide) | (short) x | x & 0xFFFF | bc_short
    if** | pc | (delta/renumbered) | bc_label
    if_** | pc | (delta/renumbered) | bc_label
    goto | pc | (delta/renumbered) | bc_label
    jsr | pc | (delta/renumbered) | bc_label
    goto_w | pc | (delta/renumbered) | bc_label
    jsr_w | pc | (delta/renumbered) | bc_label
    tableswitch | case count | count | bc_case_count
    tableswitch | default pc | (delta/renumbered) | bc_label
    tableswitch | first case value | value | bc_case_value
    tableswitch | each case pc | (delta/renumbered) | bc_label
    lookupswitch | case count | count | bc_case_count
    lookupswitch | default pc | (delta/renumbered) | bc_label
    lookupswitch | each case value | value | bc_case_value
    lookupswitch | each case pc | (delta/renumbered) | bc_label
    new | current class | 0 | bc_classref
    new | cp_Class[i] | 1+i | bc_classref
    newarray | type code | value | bc_byte
    anewarray | current class | 0 | bc_classref
    anewarray | cp_Class[i] | 1+i | bc_classref
    checkcast | current class | 0 | bc_classref
    checkcast | cp_Class[i] | 1+i | bc_classref
    instanceof | current class | 0 | bc_classref
    instanceof | cp_Class[i] | 1+i | bc_classref
    multianewarray | cp_Class[i] | 1+i | bc_classref
    multianewarray | rank | rank & 0xFF | bc_byte
    getstatic | cp_Field[i] | i | bc_fieldref
    putstatic | cp_Field[i] | i | bc_fieldref
    getfield | cp_Field[i] | i | bc_fieldref
    putfield | cp_Field[i] | i | bc_fieldref
    invokevirtual | cp_Method[i] | i | bc_methodref
    invokespecial | cp_Method[i] | i | bc_methodref
    invokestatic | cp_Method[i] | i | bc_methodref
    invokeinterface | cp_Imethod[i] | i | bc_imethodref
    **_this | this_fields[i] | i | bc_thisfield
    **_this | this_methods[i] | i | bc_thismethod
    **_super | super_fields[i] | i | bc_superfield
    **_super | super_methods[i] | i | bc_supermethod
    invokespecial_this_init | this_constructors[i] | i | bc_initref
    invokespecial_super_init | super_constructors[i] | i | bc_initref
    invokespecial_new_init | new_constructors[i] | i | bc_initref

    6. Specification of Band Coding

    A Pack200 band consists of a sequence of small integers, each of which is representable in 32 bits. Depending on the intended use of these numbers, they may be interpreted to possess a twos-complement sign.

    Each integer is coded for transmission as a byte sequence, using between one and five bytes, according to a previously determined encoding. The encoding may by a primary encoding for the current band as specified as part of this Pack200 archive format specification, or the encoding may depend on information transmitted before the occurrence of the encoded integer.

    (Note: In this account of encodings, bytes are indivisible octets which express unsigned values in [0,255].)

    6.1. Encoding of Small Whole Numbers

    There is a small but flexible set of possible encodings allowed by the archive. They are all based on a two-parameter scheme of codings for small unsigned integers, which is further parameterized by options for sign representation and delta encoding, and by special modes for slowly varying encodings, and for the compact renaming of frequent values.
    6.1.1. Scheme of Multiple Codings
    The encoding of a small whole number depends on two independent parameters B and H, and a derived parameter L:
    Name | Range | Meaning
    B | [1..5] | maximum byte length
    H | [1..256] | number of high byte values
    L | [0..255] | number of low byte values, defined as (256-H)

    Given any two values B and H, there is a coding (B,H) which establishes a one-to-one correspondence between an initial sequence of non-negative integers, and an "encoding sets" of short sequences of bytes.

    Moreover, no byte sequence in the encoding set is a proper prefix of another byte sequence in the same set. prefix. This means, informally, that encodings are self-sizing, or "parseable".

    Also, the encoding set is as full as possible, so that every long-enough sequence of bytes begins with a unique prefix of bytes drawn from the encoding set. In particular, every sequence of B bytes has a (unique) prefix in the encoding set for the (B,H) coding.

    6.1.2. Definition of Encoding Byte Sequences
    Relative to a given (B,H) coding, we say that a byte is "high" if its value is in the range [256-H..255]. We also say that a byte is "low" if L is positive and the byte's value is in the range [0..L-1]

    Given a (B,H) coding, a sequence of bytes is in its encoding set if and only if all of the following are true:

    • the sequence contains at least one and no more than B bytes
    • all bytes except the last are "high"
    • either the last byte is "low", or else the sequence has B bytes

    As a consequence of this definition, the encoding set be regarded as satisfying this regular expression, in terms of high and low bytes:

      encoding_set = (high* low) | (high)^B

    (Note: In this specification the up-caret sign '^' denotes exponentiation, either of regular expressions as above, or of numbers.)

    If n is less than B then the number of (B,H) encodings of length exactly n is (H^(n-1) * L). The number of (B,H) encodings of length exactly B is (H^(B-1) * (L+H)). The sum of these values for all n in [1..B] is the total size of the encoding set for a (B,H) coding. It is called Card(B,H) and is therefore defined as:

      Card(B,H) = (L * (1-H^B)/(1-H)) + H^B
    if H>1, or else
  Card(B,1) = B*255+1

    If H is 256, there are no low bytes, and the encoding set consists of all possible sequences of exactly B bytes, and Card(B,H) is 256^B.

    Otherwise, the encoding set consists of sequences of various lengths, from 1 to B inclusive. In particular, there are L one-byte sequences. We will use these elsewhere to encode the "favored" integers of the highest frequency. Note that the encoding rules specified elsewhere in this document are designed to produce smaller integers more frequently than larger ones.

    Note that L can be viewed as a "sharpness" parameter, expressing the sharpness of the distribution about zero of the expected values to be encoded. The larger L is, the more the encoding favors distributions of values which are close to zero, and rarely far from it. Larger H values favor "flatter" distributions, up to H=256, L=0, which favorably encodes completely random data within the range of the coding.

    6.1.3. Definition of Decoded Whole Number Values
    The range of a (B,H) coding is the integers in [0..Card(B,H)-1]. (Note that this range applies only to the unsigned codings introduced so far in this section.)

    Given the sequence of N byte values b[0] .. b[N-1], the sorting-based definition given above implies that the decoded integer value of this byte sequence is the little-endian base-H scaled sum of the bytes, and is called Decode(B,H; b):

      Decode(B,H; b[*]) = Sum[0<=i<N]( b[i] * H^i )

    As a consequence of this definition, each byte sequence in the encoding set corresponds uniquely to an arithmetic integer value in that range. This correspondence may be observed by ordering the byte sequences first by length, and second according to their antilexicographic (little-endian) order. Each element in resulting sequence decodes into its own zero-based index within the sequence.

    Note that the number zero is always encoded by a sequence of B zero bytes (if H is 256) or else by single zero byte.

    The largest encoded arithmetic value is always encoded by a sequence of B bytes of value 255.

    Note that the (B,H) encodings (1,256), (2,256), and (4,256) are identical with the conventional little-endian representations of unsigned bytes, unsigned 16-bit integers, and unsigned 32-bit integers.

    Note that some may represent arithmetic values greater than 2^31-1 or even 2^32-1. This is a feature of the (B,H) coding scheme. (But sometimes intermediate 64-bit values are required when multiple sign bits are being used, as described below. The rules given below for signed values require the compressor to emit the simplest encoding that will suffice to transmit the required 32-bit integer, even if more complex sequences would produce the same 32-bit value, after truncation.)

    Note that implementations are not always free to truncate intermediate values when computing (B,H) coding values. However, the final decoded values (after restoration of signs) will always fit in 32 bits, as described in the next section.

    6.2. Encoding of Signed Integers

    In order to encode signed 32-bit numbers we add another parameter to the (B,H) coding scheme.
    Name | Range | Meaning
    B | [1..5] | maximum byte length
    H | [1..256] | number of high byte values
    L | [0..255] | number of low byte values, defined as (256-H)
    S | [0..2] | number of sign bits

    The whole number U obtained from a (B,H) coding is converted to a signed 32-bit value X in a manner which depends on the parameter S. This process is called sign conversion.

    Informally, sign conversion is performed by 32-bit truncation if S=0. Otherwise, the low-order bits of U are collectively treated as a sign bit, so that X will be negative only if all sign bits are set. The two conversions from U to positive X and U to negative X are independently dense and monotonic in opposite directions, as defined below.

    Unlike the (B,H) coding, a (B,H,S) coding represents only numbers in a specifically defined range, which is never larger than [-2^31..2^31-1].

    In what follows, for each (B,H,S) coding, we define Range(B,H,S), and the method used to represent 32-bit signed values with that coding.

    A (B,H) encoding byte sequence is not a legal input to a corresponding (B,H,S) coding if it represents a whole number U which does not convert into the range of the (B,H,S) coding. Also, if there are two byte sequences encoding values U1 and U2 which both map into the same point X in the signed range, only the byte sequence for the smaller of U1 and U2 is legal.

    Thus, a (B,H,S) coding may have a smaller cardinality than the corresponding (B,H) coding, due to illegal encoding byte sequences.

    The range of a (B,H,S) coding contains all 32-bit signed integers [-2^31..2^31-1] if Card(B,H) is 2^32 or more. (Negative values are represented by 31-bit unsigned overflow.) If the coding encodes fewer unsigned values, the top of its range is clipped to 2^31-1, and the bottom of its range is clipped to -2^31.

    More precisely, the range of a (B,H,S) coding is called Range(B,H,S) and is defined (partially, for S=0) as:

      Range(B,H,S) = [-2^31..2^31-1]
    if S=0, Card(B,H) >= 2^32, or
  Range(B,H,S) = [0..2^31-1]
    if S=0, 2^31 < Card(B,H) < 2^32, or else
  Range(B,H,S) = [0..Card(B,H)-1]
    if S=0, Card(B,H) <= 2^31
    A compressor is not allowed to emit a byte sequence which, when interpreted according to the current coding, decodes to a value outside of that coding's range.

    (Note that decompressors can produce arbitrary answers for out-of-range codings, since compressors are not allowed to emit them. This allows decompressors to use 32-bit arithmetic for most calculations, ignoring the possibility of undesired wraparond.)

    If S>0, the decoding of a byte sequence is performed first by decoding it as a (B,H) coding, and then by converting the decoded whole number into a signed 32-bit number. This sign conversion depends only on the arithmetic value U obtained from the (B,H) coding, and on the value of S. The arithmetic value must be preserved beyond 32 bits of precision, if the sign conversion will produce a value within the range of the coding. If the cardinality of the (B,H) coding is 2^32 or more, the (B,H,S) coding produces all possible signed 32-bit negative values, by 32-bit truncation of the intermediate unsigned whole number. The intermediate unsigned arithmetic can be carried out (with some care) using 32-bit unsigned numbers, or it can be carried out on 64-bit signed or unsigned numbers.

    More precisely, the sign conversion operation SignConvert(S;U) is defined as:

      SignConvert(S; U) = Cast32(U)
    if S==0; or
  SignConvert(S; U) = U - Floor(U / 2^S)
    if S>0, (U % 2^S) < 2^S-1, Card(B,H) < 2^32
  SignConvert(S; U) = Cast32(U - Floor(U / 2^S))
    if S>0, (U % 2^S) < 2^S-1, Card(B,H) >= 2^32
  SignConvert(S; U) = -Floor(U / 2^S)-1
    if S>0, (U % 2^S) == 2^S-1
    The conversion from a large unsigned number of a negative 32-bit number via wraparound is simply the familiar down-cast to a signed 32-bit int. It may be defined mathematically as:
      Cast32(U) = ((U + 2^31) mod 2^32) - 2^31
    6.2.1. Further Discussion of Sign Conversion
    Note that sign conversion always maps zero to zero. The reader may also verify that, if S>0, the range of SignConvert includes [-1..1], and that it is dense and monotonic in any wholly positive or wholly negative sub-range.

    As a consequence of the definition of SignConvert(S;U), the S low-order bits of U function as a sign bit. In effect, U is partitioned into a sign field U0 (consisting of the S low-order bits) and a significand U1 (consisting of all other bits of U).

    In this alternative view of the definition of SignConvert, if all S bits of U0 are set, then the decoded signed value is the ones complement of U1. (Since this includes the indefinite number of zero high-order bits of U, the resulting value is arithmetically negative.)

    Otherwise, if some of the S bits of U0 are clear, then the significand U1 is scaled by the number of possible values of U0 (i.e., (2^2)-1 if S is 2) and U0 is added back in.

    This provides a one-to-one correspondence between some portion of the arithmetic interval [0..Card(B,H)-1] and Range(B,H,S).

    The integers "favored" by this encoding are those of small magnitude, but they can have either sign. If S is one, the encoding has a balanced number of positive and negative favored values. If S is two (or more), the encoding is skewed toward positive numbers, but also favors a few negative numbers. We use such codings elsewhere to encode values, such as branch displacements or deltas of mostly-sorted data, which are usually positive but sometimes negative.

    Note that if S=1, this definition of sign conversion is equivalent to an unsigned right shift followed by an exclusive-or of the sign bit with all remaining bits:

      SignConvert(1; U) = (U >>> 1) ^ -(U & 1)

    For S>0, Range(B,H,S) is simply defined as the intersection of the 32-bit signed range [-2^31..2^31-1] with the set SignConvert(S; [0..Card(B,H)-1]), obtained by element-wise application of sign conversion to every arithmetically representable value of (B,H). Therefore, we can complete the definition of Range as follows:

      Range(B,H,S) = [-2^31..2^31-1]
    if Card(B,H) >= 2^32, or
  Range(B,H,S) = [0..2^31-1]
    if S=0, 2^31 < Card(B,H) < 2^32, or else
  Range(B,H,S) = [0..Card(B,H)-1]
    if S=0, Card(B,H) <= 2^31

  Range(B,H,S) = [max(  -2^31, min SignConvert(S; Range(B,H,0)) )
               .. min( 2^31-1, max SignConvert(S; Range(B,H,0)) )]

    (Note: When computing the bounds of a signed encoding (B,H,S), it is useful to start with the largest unsigned value M of (B,H,0) and perform sign-conversion on M, M-1, M-2, etc., noting the first positive and the first negative value to be encountered. These will be the inclusive bounds of the signed encoding's range.)

    6.3. Attributes of Codings

    The cardinality of a (B,H) coding was defined above:
      Card(B,H) = (L * (1-H^B)/(1-H)) + H^B

    The cardinality of a (B,H,S) coding is determined by that of its range:

      Card(B,H,S) = Card Range(B,H,S) <= Card(B,H)

    As defined, the range of any coding (B,H,S) is dense about zero and can therefore be expressed as a closed interval:

      Range(B,H,S) = [Min(B,H,S)..Max(B,H,S)]
  -2^31 <= Min(B,H,S) <= 0
  0     <  Max(B,H,S) <= 2^31-1

    Certain additional attributes can be predicated of codings. A coding can either be signed or not, and it can be a full-range coding, or a sub-range coding (or neither).

    A (B,H,S) coding is signed if it can encode at least one negative value. This is true if and only if S is non-zero or S is zero and Card(B,H) is 2^32 or more.

    A (B,H,S) coding is full-range if Range(B,H,S) is [-2^31..2^31-1].

    A sub-range coding delivers less than 2^31 distinct values. More precisely, a coding (B,H,S) is sub-range if Card(B,H,S) <= 2^31-1. (Some codings are neither full-range nor sub-range codings.)

    As a consequence of these definitions, any coding for which B<=3 is a sub-range coding. Longer codings can also be sub-ranges if they are "sharp" enough. Some examples are (4,192,0), (5,32,0), and (5,32,1).

    Also, the unsigned coding (4,256,0) is full-range, as is the signed version (4,256,1), but not the doubly-signed version (4,256,2).

    The coding (4,255,0) is neither a sub-range nor a full-range coding, since its cardinality is 2^31. It represents only non-negative 32-bit integers, but its cardinality cannot be so represented.

    6.4. Encoding of Correlated Sequences

    Every single integer in the archive format is encoded according to some coding in the scheme of (B,H,S) codings. In addition, special attention is paid to sequences of integers (in the "bands" described elsewhere) which show statistical regularity. In particular, if a sequence of integers is found to exhibit a pattern of small, regular first-order differences, those differences may be encoded in place of the values themselves. This is described by a fourth coding parameter added to the (B,H,S) scheme.
    Name | Range | Meaning
    B | [1..5] | maximum byte length
    H | [1..256] | number of high byte values
    L | [0..255] | number of low byte values, defined as (256-H)
    S | [0..2] | number of sign bits
    D | [0..1] | delta encoding order

    If D is zero, no differencing is performed, and the (B,H,S,0) coding is in all ways identical to the corresponding (B,H,S) coding. If D is one, the values are encoded in terms of their successive differences.

    (Note: Sequences which are mostly monotonically ascending will often be favorably encoded using unsigned delta codings of the form (5,H,0,1).)

    Suppose a sequence of values X[i] is given, for some range of i in [0..N-1]. This sequence will be representable by a (B,H,S,1) coding only if the (B,H,S) coding is a sub-range or a full-range coding. (If it is neither, there is no legal (B,H,S,1) coding.)

    The sequence X[i] will be representable, only if there is a series of "delta values" D[i] whose partial sums Sum[j<=i](D[j])< /tt="/tt"> can represent the values X[i].

    Each (B,H,S,1) coding has a range, in which all X[i] values must lie. This range is defined as Range(B,H,S,1) = Range(B,H,0). The range of a delta coding (B,H,S,1) contains negative numbers only if it is based on a full-range coding (B,H,S). Otherwise, the delta coding can only represent non-negative numbers. In practice, this is not a severe restriction, since in practice very few band elements are negative.

    The partial sums Sum[j<=i](D[j]) are="are" allowed="allowed" to="to" leave="leave" the="the" range,="range," but="but" the="the" final="final" X[i]="X[i]" values="values" are="are" always="always" brought="brought" back="back" into="into" range="range" by="by" adding="adding" or="or" subtracting="subtracting" a="a" multiple="multiple" of="of" Card="Card" Range(B,H,0).="Range(B,H,0)." More precisely:

      X[i] = Sum[j<=i](D[j]) mod Card(B,H,0)
    if (B,H,S) is sub-range
  X[i] = (int32) Sum[j<=i](D[j])
    if (B,H,S) is full-range
    (Here, the cast to int32 denotes truncation to 32 bits.)

    Note that implementations can simply ignore 32-bit wraparound when computing partial sums, if the coding is full-range. Otherwise, more care must be taken to bring partial sums back into range by subtracting or adding multiples of the range cardinality. Also, 32-bit wraparound may be a hazard for ranges of size 2^30 or more. It is possible to implement this using only 32-bit signed arithmetic.

    6.5. Encodings of Uncorrelated Values

    The coding methods described so far are designed to favor values which, on average, tend to be near zero or near the preceding value. Some data sets have marked statistical patterns in which values have only weak arithmetic relations (to zero or to each other), but which show strong repetitive patterns, especially in their first-order statistics.

    The compressor may elect to use a population-based coding transformation in such cases. This transformation takes a sequence S of N arithmetic values and converts it into three value sequences:

    • F a table (arbitrary length K+1 << N) of favored values
    • T a sequence (length N) of value tokens
    • U a sequence (length << N, depends on T) of unfavored values

    Each of these sequences (F, T, and U) is in turn treated as a sub-band, and transmitted with an independent encoding. Each non-zero value in T indexes a value from F, while each zero value in T selects (in order) a value from U:

      S[i] = F[T[i]-1]
    if T[i] != 0
  U = { S[i] such that T[i] == 0 }
    6.5.1. Table of Favorites
    The table F contains any number of integer values. There is no restriction on their number or identity, except that no value in F may be repeated, except the last, and F must not contain unused values. The last value in F must be a repetition of an earlier occurrence of a "sentinel value" of F. This sentinel marks the end of the table F, allowing the decompressor to prepare to read T and U.

    The "central value" X of F is defined as that element of F which is arithmetically closest to zero. If F contains both a positive X and a negative -X of minimal absolute value, then -X is defined as the central value. (I.e., a negative sign is the tie-breaker. The central value is chosen so as to have a favorable encoding.)

    (Note that implementations may compare values for centrality by using the 32-bit signed int expression (X>>31)^(X<<1) as an unsigned comparison key.)

    A valid sentinel value is either the central value of F, or the last value of F. Thus, while parsing F, the decompressor must look for a repetition of either the central value (so far) or of the immediately previous value.

    Let K be the number of values in F, ignoring the repetition of the sentinel value. In the next band, values in [1..K] will refer (as 1-origin indexes) to corresponding elements of F.

    6.5.2. Sequence of Tokens
    The sequence T follows the table F, and encodes the input of the population transformation in a direct, element-by-element manner.

    Each element of T is a token for either a favored or an unfavored value, encoded in the arithmetic range [0..K]. Each non-zero value corresponds in order to an element of F, and produces that favored value. Each zero value in T is a placeholder for an "unfavored" value, which is still unknown.

    As mentioned above, each element of F must be referred to by at least one element of T. That is, the following two sets must be the same:

      { F[T[i]-1] such that T[i] != 0 }
  { F[j] }

    The statistics of the sequence T are quite favorable for compact encoding in a suitable (B,H) scheme, assuming that the coder made good choices for the contents of F. Generally speaking, the most commonly occurring input values should be given early positions in F.

    A greedy algorithm could sort the input values by number of occurrences and place the most common values at the front of F. This would be likely to produce an improved encoding for the input. Such techniques are neither mandated nor discouraged by this specification.

    6.5.3. Sequence of Unfavored Values
    The third subsequence consists of values which were not representable by indexes into the table F. Let Z be the number of zeroes encountered in T. There is a ordered, one-to-one correspondence between the Z zeroes in T and all the Z values of U.

    Taken together, the elements of F and U selected by the elements of T must be identical in value and order to the input of the population transformation.

    The decompressor can then read F into memory, read T into memory, and then make a second pass over T, translating token values, either referring to F or reading from U as necessary.

    6.6. Adaptive Encodings

    Sometimes, in a very long sequence of values, the statistics will change slowly, making an initially suitable coding tactic become unsuitable.

    An adaptive coding method handles this situation by allowing value sequences to be partitioned (effectively into sub-bands), with an independent coding used locally in each part.

    An adaptive coding method is specified by a count K, a coding method A which will be used to encode K values, and another coding method B which will handle the rest of the values.

    Since bands are sized by context, when an adaptive coding method is applied to the bytes of an encoded band, the method will be provided in advance with the count N of values to decode. Thus, after the method A has decoded K values, the method B will be used to decode the rest of the (N-K) values in the band.

    6.7. Meta-Coding

    Every band in the Pack200 archive format whose primary encoding is not BYTE1 is optionally preceded by a series of bytes called a band coding specifier which specify a secondary coding or codings used in that band, instead of the primary coding. The decompressor must parse this coding specifier and save it away before it reads any of the band elements. In a few extra bytes of information, the coding specifier determines exactly how the subsequent bytes are to be decoded into band values.

    Any compressor may elect not to provide a band coding specifier, in which case the band's primary encoding governs the transmission of elements. If the encoding of the first band element under the primary encoding accidentally appears to be a band coding specifier, the compressor is obligated to transmit an explicit band coding specifier that reaffirms the band's primary encoding. This is rare, because (as noted below) band coding specifiers present themselves as negative numbers in the primary encoding, and negative numbers are rare in most bands.

    6.7.1. Coding Specifier Structure
    The symbolic structure of a band coding specifier is determined by the following grammar. (This grammar is independent of the grammar governing band structure, or any other grammar appearing in other parts of this specification.)
      BandCodingSpecifier:
        (Default | BHSDCode | RunCode | PopCode)
  BHSDCode:
        CanonicalBHSDCode | ArbitraryBHSDCode
  CanonicalBHSDCode:
        ( '(1,256,0)' | '(1,256,1)' | ... )
  ArbitraryBHSDCode:
        'arb' ( B H S D )
  B, H, S, D:
        Integer
  RunCode:
        'run' K ACode BCode
  K:
        Integer
  ACode:
        (Default | BHSDCode | PopCode)
  BCode:
        (Default | BHSDCode | RunCode | PopCode)
  PopCode:
        'pop' ( FCode TCode UCode )
  FCode:
        (Default | BHSDCode | RunCode)
  TCode:
        (Default | BHSDCode | RunCode)
  UCode:
        (Default | BHSDCode | RunCode)
  Integer:
        ( '0' | '1' | ... )
  Default:
        'default'
    Note that adaptive coding methods ("RunCode" nonterminals) can be chained via the "BCode" nonterminal, but cannot be nested directly via the "ACode" nonterminal. (As the grammar shows, they may be nested indirectly via the "PopCode" nonterminal.)

    Also, population coding methods can contain adaptive coding methods, and vice versa. However, although the grammar does not show this fact, population coding methods must not be nested, even indirectly.

    Not all possible integer values of K and L are equally well expressible. The intended values of K are commensurate with compressor windows, and the intended values of L are sharpness parameters for BHS encodings.

    6.7.2. Coding Specifier Semantics
    At any point, band contents are decoded under the control of three pieces of information:
    • N, an expected number of band values to decode, or "infinity"
    • D, a default BHSD coding
    • S, a coding specifier

    We denote the application of S in the context of N and D as "S(N,D)". This application decodes up to N elements of transmitted band data.

    Just before a band is received, the decompressor knows an expected band length N and a default coding method D, specified statically as the band's primary encoding. The decompressor then reads zero or more bytes which constitute a band encoding specifier, and decodes N elements of band data based on the band encoding specifier.

    When the coding specifier is 'default', N values are decoded using the default coding D, which is the band's primary encoding. (This rule is necessary if the band's first element appears to introduce a non-empty coding specifier. Such a default coding specifier is the only kind that a compressor is obligated to emit; the rest are all optional.)

    When the coding specifier is another BHSDCode, N values are decoded using that coding. The ambient default D is ignored.

    When the coding specifier is a 'run' of K, ACode, BCode, two steps are taken. First, the specifier ACode is given control, as ACode(K,D). That is, N is temporarily set to K. Second, the specifier BCode is given control as BCode(N-K,D). (Note: If N is infinity, N-K will also be infinity.) In both steps, D remains unchanged, so that occurrences of 'default' for ACode or BCode cause D to be used.

    It is illegal for a 'run' coding specifier to specify a K of zero, or for it to be used to decode a run of K or fewer values.

    When the coding specifier is a 'pop' of FCode, TCode, UCode, three steps are taken. First, FCode is applied as FCode(infinity, D). The decoding of the F values stops when the first duplicate value is encountered. (As specified in the section above on population coding, that duplicate value acts as a sentinel, and must be either the most "central" value read, or else the value immediately previous to the sentinel value.) Let K be the number of unique decoded values.

    During the decoding of the F values by FCode, every 'run' specifier in FCode must exhaust its count 'K' without decoding the sentinel value. That is, the sentinel must be decoded by the last simple BHSD coding in FCode.

    In the second step, a different coding TCode is used, since the T values are expected to be a dense encoding. TCode is applied as TCode(N,D), and the tokens are read which determine the band values to be delivered. (Note that a 'pop' coding method can only be applied if the N value supplied is finite. This will be true, since the only bands which are read with an infinite N are byte bands such as bc_codes.) Let Z be the number of zeroes decoded using TCode.

    The third step is to use UCode to decode Z values, using the original default encoding D. UCode is applied as U(Z,D). The resulting band is produced from the T sequence, as documented above, by replacing zeroes in the T sequence by successive U values, and replacing other elements of the T sequence by those indexed in the F sequence.

    It is illegal for a 'pop' coding specifier to be used to decode a run of no values, or of an infinite number of values. If Z (the number of unfavored values) is zero, it is illegal for UCode to be anything other than 'default'.

    6.7.3. Coding Specifier Meta-Encoding
    The compressor uses a tense, byte-oriented encoding to transmit the band encoding specifier. Although the "little language" above allows a wide range of encodings, in practice many of them are similar in performance and applicability. It is not necessary or desirable to allow the compressor complete freedom to specify any conceivable band encoding specifier. Instead, the meta-encoding described in this section allows the compressor to select from a limited but useful set of secondary encodings. It is up to the compressor to make a choice that improves compression; the heuristic or algorithm that controls such a selection is beyond the scope of this specification.

    The common band coding specifier of 'default' is encoded in a way that often requires no extra bytes. If the band has no elements, no parsing at all is done. Otherwise, if the band's default encoding is of variable length, the decompressor is obligated to decode one value X from the initial bytes of the band using the band's default coding D. If possible, the value X is converted into an unsigned byte value XB, which is taken to be the first byte of a band coding specifier, and X will be discarded. Otherwise, the band coding specifier is taken to be 'default', and so D is applied to the entire band, including the bytes which produced the initial value X.

    D must be of the form (B,H,S) or (B,H,S,D), where B>1 and H<256. The="The" value="value" is="is" D="D" is="is" irrelevant="irrelevant" to="to" the="the" decoding="decoding" of="of" the="the" first="first" value,="value," and="and" the="the" decoding="decoding" of="of" X="X" is="is" done="done" using="using" (B,H,S,0).="(B,H,S,0)." If="If" S="S" is="is" not="not" zero,="zero," and="and" if="if" the="the" value="value" X="X" is="is" in="in" the="the" range="range" [-256..-1],="[-256..-1]," the="the" coding="coding" specifier="specifier" byte="byte" XB="XB" is="is" defined="defined" as="as" XB = (-1-X), and X is discarded. Otherwise, if S is zero, and if the value of X is in the range [(256-H)..(511-H)], the coding specifier byte XB is defined as XB = (X-(256-H)), and X is discarded. Otherwise, there is not a coding specifier byte XB, and X is the first band value, as described above.

    The value XB, if produced, is taken to be the initial byte of a coding specifier preceding the actual band data. This specifier is parsed, starting with XB, and continuing (if necessary) with bytes bytes taken from band_headers. The parsed specifier is then used to control decoding, starting at the next byte, of all band elements.

    If the band really does start with an element X1 in a range ([-256..-1] or [L,L+255]) that requires the production of a band specififer byte XB, but the compressor wishes to use the default encoding, the compressor is required to specify a band header, lest X1 mislead the decompressor. If the compressor wishes to keep the default coding, it must in such cases specify an explicit coding specifier of 'default', using an XB value of zero (as specified below). This zero XB is transmitted, depending on the default encoding, as an X value of -1 (usually the byte 1) or of L (usually the bytes 192,0).

    (An immediate consequence of this design is that byte bands can never have non-default encodings, but all other bands can, since all the other bands have default encodigns which are variable length and have a large dynamic range. The "escape" values chosen for X are rare in practice, so they are not usually confused with real band data. Adding an extra zero value to reaffirm the default will always cost one extra byte before the actual band data, and no extra bytes in the band_headers band. In general, the encoding of explicit X values will always require two bytes if S is zero, and at most two bytes if S is not zero.)

    The band band_headers transmits the non-initial band header bytes (if any) of each band that has a band header. The order of transmission is consistent with the overall order of all bands in the archive, as given in the present specification's band grammar. The length of band_headers is independently specified (as #band_headers_size) in the archive header. (It should be clear that the decompressor needs to find the end of band_headers before it can read any further bands.)

    Thus, the encoding of a coding specifier consists of a sequence of bytes: an initial byte XB, and zero or more non-initial bytes taken from band_headers. The encodings of the little language specified in the previous section are as follows. The encoding 'default' is a zero byte. Of all the possible BHSDCode encodings, a sequence of 115 canonical encodings (defined below) is selected to cover the expected range of uses. A BHSDCode is represented as a single byte whose value is the index (1-based) of the selected canonical coding.

      Enc{default}  = (0)
  Enc{CanonicalBHSDCode} = value in [1..115]

    The special value 116 introduces an arbitrary, possibly non-canonical BHSD code, described in the following byte.

      Enc{ arb ( B H S D ) } =
      116
    & (D:[0..1] + 2*S[0..2] + 8*(B:[1..5]-1))
    & (H[1..256]-1):
    The B value must be in the range [1..5]. The S value must be in the range [0..2]. The H value must be in the range [1..256]. The D value must be in the range [0..1]. (These ranges are inclusive.) In addition, if B is 1, H must be 256, and if H is 256, B must not be 5.

    The 'run' construct encodings begin with a byte in [117..140], and may be followed by an optional byte KB and then by one or two encoding specifiers ACode and BCode. The offset from 117 represents bitwise the following data:

    • a two-bit field KX
    • a bit KBFlag
    • a bit ADef (ABDef == 1)
    • a bit BDef (ABDef == 2)
    The last two bits are jointly encoded in the value ABDef. They are never both true.
      Enc{ run ( K ACode BCode ) } =
      (117 + (KX:[0..3]) + 4*(KBFlag:[0..1]) + 8*(ABDef:[0..2]))
    & KB: one of [0..255] if KBFlag=1
    & Enc{ ACode } if ADef=0  (ABDef != 1)
    & Enc{ BCode } if BDef=0  (ABDef != 2)

    After the leading byte is parsed, a byte KB is expected if the KBFlag is set, otherwise KB is implicitly given the value 3.

    The K value for the 'run' construct can take a range of values, and is determined as follows:

      K = (KB+1) * 16^KX

    The ACode coding is understood to be 'default' if the ADef bit is set. Otherwise, the representation of ACode is parsed next. Finally, the BCode coding is understood to be 'default' if the BDef bit is set. Otherwise, the representation of BCode is parsed last. Both ADef and BDef may be clear, but both may not be set.

    The 'pop' construct encodings begin with a byte in [141..188], and may be followed by one, two, or three encoding specifiers, FCode, UCode, and TCode. The offset from 141 bitwise encodes the following data:

    • a bit FDef
    • a bit UDef
    • a bit TDef (TDefL > 0)
    • a value L in [1..11] if TDef=1
    The last two values are jointly encoded in the value TDefL.
      Enc{ pop ( FCode TCode UCode ) }
    = (141 + (FDef:[0..1]) + 2*UDef:[0..1] + 4*(TDefL:[0..11]))
    & Enc{ FCode } if FDef=0
    & Enc{ TCode } if TDef=0  (TDefL==0)
    & Enc{ UCode } if UDef=0

    If TDef is zero, an explicit encoding specifier determines TCode, and the L parameter is not present. If TDef is one, the L parameter is present and is derived from TDefL, according to the following table:
    TDefL | L
    1 | 4
    2 | 8
    3 | 16
    4 | 32
    5 | 64
    6 | 128
    7 | 192
    8 | 224
    9 | 240
    10 | 248
    11 | 252

    If the L parameter is present, the TCode is derived from the K and L values. If K < 256, then TCode is BYTE1 (1,255,0), and L is ignored. Otherwise, TCode is the (B,H,S) coding where S=0, H=(256-L), and B is the smallest value such that [0..K] is contained in Range(B,H,S). (It is illegal to specify an L so large that Range(5,256-L,0) does not contain K.)

    The FCode coding is understood to be 'default' if the FDef bit is set. Otherwise, the representation of FCode is parsed immediately after the initial byte. The TCode coding is understood to be derived from K and L if the TDef bit is set. Otherwise, the representation of TCode is parsed next. Finally, the UCode coding is understood to be 'default' if the UDef bit is set. Otherwise, the representation of UCode is parsed last.

    6.7.4. Canonical BHSD Codings
    Here is the list of all the canonical BHSD codings. These codings are designed to match a diverse variety of band value ranges and statistics.
    index | BHSD Coding
    1 | (1,256,0)
    2 | (1,256,1)
    3 | (1,256,0,1)
    4 | (1,256,1,1)
    5 | (2,256,0)
    6 | (2,256,1)
    7 | (2,256,0,1)
    8 | (2,256,1,1)
    9 | (3,256,0)
    10 | (3,256,1)
    11 | (3,256,0,1)
    12 | (3,256,1,1)
    13 | (4,256,0)
    14 | (4,256,1)
    15 | (4,256,0,1)
    16 | (4,256,1,1)
    17 | (5, 4,0)
    18 | (5, 4,1)
    19 | (5, 4,2)
    20 | (5, 16,0)
    21 | (5, 16,1)
    22 | (5, 16,2)
    23 | (5, 32,0)
    24 | (5, 32,1)
    25 | (5, 32,2)
    26 | (5, 64,0)
    27 | (5, 64,1)
    28 | (5, 64,2)
    29 | (5,128,0)
    index | BHSD Coding
    30 | (5,128,1)
    31 | (5,128,2)
    32 | (5, 4,0,1)
    33 | (5, 4,1,1)
    34 | (5, 4,2,1)
    35 | (5, 16,0,1)
    36 | (5, 16,1,1)
    37 | (5, 16,2,1)
    38 | (5, 32,0,1)
    39 | (5, 32,1,1)
    40 | (5, 32,2,1)
    41 | (5, 64,0,1)
    42 | (5, 64,1,1)
    43 | (5, 64,2,1)
    44 | (5,128,0,1)
    45 | (5,128,1,1)
    46 | (5,128,2,1)
    47 | (2,192,0)
    48 | (2,224,0)
    49 | (2,240,0)
    50 | (2,248,0)
    51 | (2,252,0)
    52 | (2, 8,0,1)
    53 | (2, 8,1,1)
    54 | (2, 16,0,1)
    55 | (2, 16,1,1)
    56 | (2, 32,0,1)
    57 | (2, 32,1,1)
    58 | (2, 64,0,1)
    index | BHSD Coding
    59 | (2, 64,1,1)
    60 | (2,128,0,1)
    61 | (2,128,1,1)
    62 | (2,192,0,1)
    63 | (2,192,1,1)
    64 | (2,224,0,1)
    65 | (2,224,1,1)
    66 | (2,240,0,1)
    67 | (2,240,1,1)
    68 | (2,248,0,1)
    69 | (2,248,1,1)
    70 | (3,192,0)
    71 | (3,224,0)
    72 | (3,240,0)
    73 | (3,248,0)
    74 | (3,252,0)
    75 | (3, 8,0,1)
    76 | (3, 8,1,1)
    77 | (3, 16,0,1)
    78 | (3, 16,1,1)
    79 | (3, 32,0,1)
    80 | (3, 32,1,1)
    81 | (3, 64,0,1)
    82 | (3, 64,1,1)
    83 | (3,128,0,1)
    84 | (3,128,1,1)
    85 | (3,192,0,1)
    86 | (3,192,1,1)
    87 | (3,224,0,1)
    index | BHSD Coding
    88 | (3,224,1,1)
    89 | (3,240,0,1)
    90 | (3,240,1,1)
    91 | (3,248,0,1)
    92 | (3,248,1,1)
    93 | (4,192,0)
    94 | (4,224,0)
    95 | (4,240,0)
    96 | (4,248,0)
    97 | (4,252,0)
    98 | (4, 8,0,1)
    99 | (4, 8,1,1)
    100 | (4, 16,0,1)
    101 | (4, 16,1,1)
    102 | (4, 32,0,1)
    103 | (4, 32,1,1)
    104 | (4, 64,0,1)
    105 | (4, 64,1,1)
    106 | (4,128,0,1)
    107 | (4,128,1,1)
    108 | (4,192,0,1)
    109 | (4,192,1,1)
    110 | (4,224,0,1)
    111 | (4,224,1,1)
    112 | (4,240,0,1)
    113 | (4,240,1,1)
    114 | (4,248,0,1)
    115 | (4,248,1,1)

    7. Stability of Decompressor Output

    From what has been said so far, it may appear that a decompressor has considerable free choice in its arrangement of class file contents. In the class file format, there are numerous degrees of freedom which have no effect on the meaning of the file. For example, constant pool entries, attribute lists, and class methods are presented in no significant order, and could be shuffled at will by the decompressor without changing the meaning of the Java application.

    However, for any given Pack200 archive, every decompressor is required to produce a particular byte-wise image for each class file transmitted. This requirement is placed on decompressors in order to make it possible for compressors to transmit information, such as message digests, which relates to the eventual byte-wise contents of transmitted class files. This section describes the restrictions placed on every decompressor that makes the byte-wise contents of its output files a well-defined function of its input.

    In general, the order of elements in a decompressed class file must be consistent with the transmission order in the Pack200 archive. For example, the order of a class's fields declared in the class file must correspond to the order in which that class's field descriptors were transmitted in the field_descr band. (This also happens to correspond to the order in the field_flags bands.) This table gives all of the required correspondences of class file order with archive transmission order:
    element in
    class file     		band which
    determines order
    implemented interfaces | class_interface
    declared fields | field_descr
    declared methods | method_descr
    code handler list | code_handler_start_P
    class attribute list | class_flags, class_attr_indexes
    field attribute list | field_flags, field_attr_indexes
    method attribute list | method_flags, method_attr_indexes
    code attribute list | code_attr_indexes
    constant pool entries | cp_Utf8, etc. (see below)

    Together, these required correspondences of order determine the exact contents of the decompressed class file. The ordering of interfaces, fields, methods, and exception handlers is directly determined by the ordering of the bands that transmit them.

    7.1. Ordering of Attribute Lists

    Attribute lists for classes, fields, and methods must begin with all attributes transmitted because of set flag bits. The order must be index order (from LSB to MSB in the flag word). After any possible flag-caused attributes, the list must then contain any overflow attributes. Any attribute list with overflow attributes will present them in the same order as their layouts were transmitted in the corresponding series of values from class_attr_indexes, field_attr_indexes, method_attr_indexes, or code_attr_indexes. Note that an attribute layout whose index is less than 32 can be specified zero or one times via a flag bit. Independently, it can also be specified zero or more times via occurrences in a band transmitting overflow attribute layouts.

    If an InnerClasses attribute must be added to a class, under the rules given in the next section, that attribute must come last in the class's attribute list.

    7.2. Ordering of Constant Pools

    The constant pool cp(X) of a decompressed class file X is defined as if by a post-processing of X and cp_All after the decompressor has already produced most of X. Specifically, suppose that the contents of X are determined, except that:
    • cp(X) is not yet defined,
    • there is no InnerClasses attribute in X (even if was an ic_Local(X) transmitted), and
    • the locations of constant references within X are noted but not initialized with numbers.

    Then cp(X) is defined as if by the following steps, which populate it from the global constant pool cp_All, and also potentially produce an InnerClasses attribute for X.

    • cp(X) is initially empty.
    • Every constant referenced from X is added to cp(X).
    • In the next step, any constant from cp_Signature must be treated as making no additional references, despite its transmitted structure.
    • Every constant referenced from cp(X) is added to cp(X), if it is not already there. (For example, a constant from cp_Method refers to constants from cp_Class and cp_Descr.)
    • The previous step is iterated until no further changes occur. (There will be at most two more of these steps.)

    At this point the constant pool cp(X) is well enough defined to allow the decompressor to compute the set of relevant nested classes, called ic_Relevant(X).

    • ic_Relevant(X) is initially empty.
    • Every four-tuple from ic_All which mentions the current class (defined by X) as an outer class is added to ic_Relevant(X).
    • For every class constant K referenced from both ic_this_class and cp(X), the corresponding four-tuple from ic_All is selected, and added to ic_Relevant(X), if not already there.
    • The previous step is repeated until closure. (That is, until ic_Relevant(X) no longer changes.)
    • The set ic_Relevant(X) is ordered into a sequence, so that its order is consistent with ic_All. (I.e., it is a subsequence of ic_All.)

    With ic_Relevant(X) and an optionally transmitted ic_Local(X) in hand, the decompressor must next decide whether to store an InnerClasses attribute ic_Stored(X) for X, using these steps.

    • If ic_Local(X) is present and empty, no InnerClasses attribute will be stored for X, and none of the following steps will be taken.
    • Also, if ic_Local(X) is not present and ic_Relevant(X) is empty, no InnerClasses attribute will be stored for X.
    • Otherwise, ic_Stored(X) is set to be the elements in ic_Local(X) followed by the elements of ic_Relevant(X) (both in transmission order).
    • Next, any elements in both ic_Local(X) and ic_Relevant(X) are removed from ic_Stored(X), thus forming a symmetric difference.
    • The resulting sequence ic_Stored(X), even if empty, is added to the decompressor's output as an InnerClasses attribute.
    • All cp_Class and cp_Utf8 entries directly or indirectly required by ic_Stored(X), as well as the fixed cp_Utf8 entry spelled "InnerClasses", are added to cp(X) if not already there.

    With the last contributions from nested class records, the decompressor finishes the constant pool using these steps:

    • Every cp_Signature entry in cp(X) is "flattened" into a cp_Utf8 entry with the same spelling.
    • If any cp_Utf8 entry E in cp(X) was not transmitted in cp_All but had an equivalently spelled signature S transmitted, then E is replaced by S in cp(X).
    • The elements of cp(X) which are also in cp_All are sorted into the same order as their occurrences in cp_All.
    • All cp_Utf8 constants in cp(X) not also in cp_All are moved to the end of cp(X), and are sorted in the order defined by String.compareTo.
    • Next, any cp_Class constants in cp(X) not also in cp_All are moved to the end of cp(X), in the order defined by String.compareTo on their class names.
    • (At this point, the decompressor has uniquely determined a position for every element of cp(X).)
    • All elements of cp(X) which are referred to via a one-byte index (i.e., a ldc bytecode) are moved in mass to the beginning of cp(X), without changing their relative order.
    • All elements of cp(X) are transformed into their equivalent class file constant types, with signatures being "flattened" into equivalently spelled CONSTANT_Utf8 constants.
    • The resulting sequence of class file constants, cp(X), is stored as the constant pool of X.

    After this process, the stored constant pool of X has referential integrity, and all constant references can be coded as indexes into cp(X), which has a definite order derived from cp_All. In particular, if a constant in cp(X) needs to refer to another constant, that constant must already have been inserted into cp(X), during the closure steps.

    Note that the ordering of cp(X) is consistent with that of cp_All, except that some signature references are redirected to equivalent pre-existing elements of cp_Utf8, and all operands of ldc bytecodes are forced to the front of the constant pool.

    When assigning local indexes to elements of cp(X), the decompressor must of course respect the reservation of empty constant pool slots for index zero, and for CONSTANT_Long and CONSTANT_Double constants, as required by the class file format. Together with these rules, the construction and ordering of cp(X) completely determines the assignment of concrete indexes to constant references within X.

    8. Appendixes

    8.1. Appendix: List of Bands

    Here is a list of all bands in the order they must occur in the archive. This list is not part of the Pack200 specification, but it is presented to help clarify the meaning of the grammar in the specification proper which defines the names and ordering of the bands. Four occurrences of ellipsis ... refer to insertion points where the compressor may insert variable numbers of extra bands to help transmit unusual strings or non-standard attributes. The other ellipses refer to repetitions of metadata bands which it would be too tedious to include.
    Band Default
    coding     		Length Constant pool
    referred to
    archive_magic | BYTE1 | [4]
    archive_header | UNSIGNED5 | [26]
    band_headers BYTE1 [...]
    cp_Utf8_prefix | DELTA5 | [MAX(0,#cp_Utf8_count-2)]
    cp_Utf8_suffix | UNSIGNED5 | [MAX(0,#cp_Utf8_count-1)]
    cp_Utf8_chars | CHAR3 | [SUM(*cp_Utf8_suffix)]
    cp_Utf8_big_suffix | DELTA5 | [COUNT(0,*cp_Utf8_suffix)]
    {cp_Utf8_big_chars...} | DELTA5 | [*cp_Utf8_big_suffix[i]]
    cp_Int | UDELTA5 | [#cp_Int_count]
    cp_Float | UDELTA5 | [#cp_Float_count]
    cp_Long_hi | UDELTA5 | [#cp_Long_count]
    cp_Long_lo | DELTA5 | [#cp_Long_count]
    cp_Double_hi | UDELTA5 | [#cp_Double_count]
    cp_Double_lo | DELTA5 | [#cp_Double_count]
    cp_String | UDELTA5 | [#cp_String_count] | cp_Utf8
    cp_Class | UDELTA5 | [#cp_Class_count] | cp_Utf8
    cp_Signature_form | DELTA5 | [#cp_Signature_count] | cp_Utf8
    cp_Signature_classes | UDELTA5 | [COUNT('L',...)] | cp_Class
    cp_Descr_name | DELTA5 | [#cp_Descr_count] | cp_Utf8
    cp_Descr_type | UDELTA5 | [#cp_Descr_count] | cp_Signature
    cp_Field_class | DELTA5 | [#cp_Field_count] | cp_Class
    cp_Field_desc | UDELTA5 | [#cp_Field_count] | cp_Descr
    cp_Method_class | DELTA5 | [#cp_Method_count] | cp_Class
    cp_Method_desc | UDELTA5 | [#cp_Method_count] | cp_Descr
    cp_Imethod_class | DELTA5 | [#cp_Imethod_count] | cp_Class
    cp_Imethod_desc | UDELTA5 | [#cp_Imethod_count] | cp_Descr
    attr_definition_headers | BYTE1 | [#attr_definition_count]
    attr_definition_name | UNSIGNED5 | [#attr_definition_count] | cp_Utf8
    attr_definition_layout | UNSIGNED5 | [#attr_definition_count] | cp_Utf8
    ic_this_class | UDELTA5 | [#ic_count] | cp_Class
    ic_flags | UNSIGNED5 | [#ic_count]
    ic_outer_class | DELTA5 | [COUNT(1<<16,...)] | cp_Class
    ic_name | DELTA5 | [COUNT(1<<16,...)] | cp_Utf8
    class_this | DELTA5 | [#class_count] | cp_Class
    class_super | DELTA5 | [#class_count] | cp_Class
    class_interface_count | DELTA5 | [#class_count]
    class_interface | DELTA5 | [SUM(*class_interface_count)] | cp_Class
    class_field_count | DELTA5 | [#class_count]
    class_method_count | DELTA5 | [#class_count]
    field_descr | DELTA5 | [SUM(*class_field_count)] | cp_Descr
    field_flags_hi | UNSIGNED5 | [SUM(*class_field_count)*#have_field_flags_hi]
    field_flags_lo | UNSIGNED5 | [SUM(*class_field_count)]
    field_attr_count | UNSIGNED5 | [COUNT(1<<16,...)]
    field_attr_indexes | UNSIGNED5 | [SUM(*field_attr_count)]
    field_attr_calls UNSIGNED5 [...]
    field_ConstantValue_KQ | UNSIGNED5 | [COUNT(ConstantValue,...)] | cp_Int, cp_Float, etc.
    field_Signature_RS | UNSIGNED5 | [COUNT(Signature,...)] | cp_Signature
    field_RVA_anno_N UNSIGNED5 [...]
    field_RVA_type_RS UNSIGNED5 [...] cp_Signature
    field_RVA_pair_N UNSIGNED5 [...]
    field_RVA_name_RU UNSIGNED5 [...] cp_Utf8
    field_RVA_T BYTE1 [...]
    field_RVA_caseI_KI UNSIGNED5 [...] cp_Int
    field_RVA_caseD_KD UNSIGNED5 [...] cp_Double
    field_RVA_caseF_KF UNSIGNED5 [...] cp_Float
    field_RVA_caseJ_KJ UNSIGNED5 [...] cp_Long
    field_RVA_casec_RS UNSIGNED5 [...] cp_Signature
    field_RVA_caseet_RS UNSIGNED5 [...] cp_Signature
    field_RVA_caseec_RU UNSIGNED5 [...] cp_Utf8
    field_RVA_cases_RU UNSIGNED5 [...] cp_Utf8
    field_RVA_casearray_N UNSIGNED5 [...]
    field_RVA_nesttype_RS UNSIGNED5 [...] cp_Signature
    field_RVA_nestpair_N UNSIGNED5 [...]
    field_RVA_nestname_RU UNSIGNED5 [...] cp_Utf8
    field_RIA_anno_N UNSIGNED5 [...]
    {field_RIA_...}
    field_RIA_nestname_RU UNSIGNED5 [...] cp_Utf8
    {field_attr_bands...} (various) [...] (various)
    method_descr | MDELTA5 | [SUM(*class_method_count)] | cp_Descr
    method_flags_hi | UNSIGNED5 | [SUM(*class_method_count)*#have_method_flags_hi]
    method_flags_lo | UNSIGNED5 | [SUM(*class_method_count)]
    method_attr_count | UNSIGNED5 | [COUNT(1<<16,...)]
    method_attr_indexes | UNSIGNED5 | [SUM(*method_attr_count)]
    method_attr_calls UNSIGNED5 [...]
    method_Exceptions_N | UNSIGNED5 | [COUNT(Exceptions,...)]
    method_Exceptions_RC | UNSIGNED5 | [SUM(*method_Exceptions_N)] | cp_Class
    method_Signature_RS | UNSIGNED5 | [COUNT(Signature,...)] | cp_Signature
    method_RVA_anno_N UNSIGNED5 [...]
    method_RVA_type_RS UNSIGNED5 [...] cp_Signature
    method_RVA_pair_N UNSIGNED5 [...]
    method_RVA_name_RU UNSIGNED5 [...] cp_Utf8
    method_RVA_T BYTE1 [...]
    method_RVA_caseI_KI UNSIGNED5 [...] cp_Int
    method_RVA_caseD_KD UNSIGNED5 [...] cp_Double
    method_RVA_caseF_KF UNSIGNED5 [...] cp_Float
    method_RVA_caseJ_KJ UNSIGNED5 [...] cp_Long
    method_RVA_casec_RS UNSIGNED5 [...] cp_Signature
    method_RVA_caseet_RS UNSIGNED5 [...] cp_Signature
    method_RVA_caseec_RU UNSIGNED5 [...] cp_Utf8
    method_RVA_cases_RU UNSIGNED5 [...] cp_Utf8
    method_RVA_casearray_N UNSIGNED5 [...]
    method_RVA_nesttype_RS UNSIGNED5 [...] cp_Signature
    method_RVA_nestpair_N UNSIGNED5 [...]
    method_RVA_nestname_RU UNSIGNED5 [...] cp_Utf8
    method_RIA_anno_N UNSIGNED5 [...]
    {method_RIA_...}
    method_RIA_nestname_RU UNSIGNED5 [...] cp_Utf8
    method_RVPA_param_NB BYTE1 [...]
    method_RVPA_anno_N UNSIGNED5 [...]
    {method_RVPA_...}
    method_RVPA_nestname_RU UNSIGNED5 [...] cp_Utf8
    method_RIPA_param_NB BYTE1 [...]
    method_RIPA_anno_N UNSIGNED5 [...]
    {method_RIPA_...}
    method_RIPA_nestname_RU UNSIGNED5 [...] cp_Utf8
    method_AD_T BYTE1 [...]
    method_AD_caseI_KI UNSIGNED5 [...] cp_Int
    method_AD_caseD_KD UNSIGNED5 [...] cp_Double
    method_AD_caseF_KF UNSIGNED5 [...] cp_Float
    method_AD_caseJ_KJ UNSIGNED5 [...] cp_Long
    method_AD_casec_RS UNSIGNED5 [...] cp_Signature
    method_AD_caseet_RS UNSIGNED5 [...] cp_Signature
    method_AD_caseec_RU UNSIGNED5 [...] cp_Utf8
    method_AD_cases_RU UNSIGNED5 [...] cp_Utf8
    method_AD_casearray_N UNSIGNED5 [...]
    method_AD_nesttype_RS UNSIGNED5 [...] cp_Signature
    method_AD_nestpair_N UNSIGNED5 [...]
    method_AD_nestname_RU UNSIGNED5 [...] cp_Utf8
    {method_attr_bands...} (various) [...] (various)
    class_flags_hi | UNSIGNED5 | [#class_count*#have_class_flags_hi]
    class_flags_lo | UNSIGNED5 | [#class_count]
    class_attr_count | UNSIGNED5 | [COUNT(1<<16,...)]
    class_attr_indexes | UNSIGNED5 | [SUM(*class_attr_count)]
    class_attr_calls UNSIGNED5 [...]
    class_SourceFile_RUN | UNSIGNED5 | [COUNT(SourceFile,...)] | null|cp_Utf8
    class_EnclosingMethod_RC | UNSIGNED5 | [COUNT(EnclosingMethod,...)] | cp_Class
    class_EnclosingMethod_RDN | UNSIGNED5 | [COUNT(EnclosingMethod,...)] | null|cp_Descr
    class_Signature_RS | UNSIGNED5 | [COUNT(Signature,...)] | cp_Signature
    class_RVA_anno_N UNSIGNED5 [...]
    class_RVA_type_RS UNSIGNED5 [...] cp_Signature
    class_RVA_pair_N UNSIGNED5 [...]
    class_RVA_name_RU UNSIGNED5 [...] cp_Utf8
    class_RVA_T BYTE1 [...]
    class_RVA_caseI_KI UNSIGNED5 [...] cp_Int
    class_RVA_caseD_KD UNSIGNED5 [...] cp_Double
    class_RVA_caseF_KF UNSIGNED5 [...] cp_Float
    class_RVA_caseJ_KJ UNSIGNED5 [...] cp_Long
    class_RVA_casec_RS UNSIGNED5 [...] cp_Signature
    class_RVA_caseet_RS UNSIGNED5 [...] cp_Signature
    class_RVA_caseec_RU UNSIGNED5 [...] cp_Utf8
    class_RVA_cases_RU UNSIGNED5 [...] cp_Utf8
    class_RVA_casearray_N UNSIGNED5 [...]
    class_RVA_nesttype_RS UNSIGNED5 [...] cp_Signature
    class_RVA_nestpair_N UNSIGNED5 [...]
    class_RVA_nestname_RU UNSIGNED5 [...] cp_Utf8
    class_RIA_anno_N UNSIGNED5 [...]
    {class_RIA_...}
    class_RIA_nestname_RU UNSIGNED5 [...] cp_Utf8
    class_InnerClasses_N | UNSIGNED5 | [COUNT(InnerClasses,...)]
    class_InnerClasses_RC | UNSIGNED5 | [SUM(*class_InnerClasses_N)] | cp_Class
    class_InnerClasses_F | UNSIGNED5 | [SUM(*class_InnerClasses_N)]
    class_InnerClasses_outer_RCN | UNSIGNED5 | [COUNT(!=0,*class_InnerClasses_F)] | null|cp_Class
    class_InnerClasses_name_RUN | UNSIGNED5 | [COUNT(!=0,*class_InnerClasses_F)] | null|cp_Utf8
    class_file_version_minor_H | UNSIGNED5 | [COUNT(version,...)]
    class_file_version_major_H | UNSIGNED5 | [COUNT(version,...)]
    {class_attr_bands...} (various) [...] (various)
    code_headers | BYTE1 | [COUNT(Code,...)]
    code_max_stack | UNSIGNED5 | [COUNT(0,*code_headers)]
    code_max_na_locals | UNSIGNED5 | [COUNT(0,*code_headers)]
    code_handler_count | UNSIGNED5 | [COUNT(0,*code_headers)]
    code_handler_start_P | BCI5 | [SUM(*code_header_count)]
    code_handler_end_PO | BRANCH5 | [SUM(*code_header_count)]
    code_handler_catch_PO | BRANCH5 | [SUM(*code_header_count)]
    code_handler_class_RCN | UNSIGNED5 | [SUM(*code_header_count)] | null|cp_Class
    code_flags_hi | UNSIGNED5 | [...*#have_code_flags_hi]
    code_flags_lo UNSIGNED5 [...]
    code_attr_count | UNSIGNED5 | [COUNT(1<<16,...)]
    code_attr_indexes | UNSIGNED5 | [SUM(*code_attr_count)]
    code_attr_calls UNSIGNED5 [...]
    code_StackMapTable_N | UNSIGNED5 | [COUNT(StackMapTable,...)]
    code_StackMapTable_frame_T | BYTE1 | [SUM(*code_StackMapTable_N)]
    code_StackMapTable_local_N | UNSIGNED5 | [COUNT(255,*code_StackMapTable_frame_T)]
    code_StackMapTable_stack_N | UNSIGNED5 | [COUNT(255,*code_StackMapTable_frame_T)]
    code_StackMapTable_offset UNSIGNED5 [...]
    code_StackMapTable_T BYTE1 [...]
    code_StackMapTable_RC | UNSIGNED5 | [COUNT(7,*code_StackMapTable_T)]
    code_StackMapTable_P | BCI5 | [COUNT(8,*code_StackMapTable_T)]
    code_LineNumberTable_N UNSIGNED5 [...]
    code_LineNumberTable_bci_P BCI5 [...]
    code_LineNumberTable_line UNSIGNED5 [...]
    code_LocalVariableTable_N UNSIGNED5 [...]
    code_LocalVariableTable_bci_P BCI5 [...]
    code_LocalVariableTable_span_O BRANCH5 [...]
    code_LocalVariableTable_name_RU UNSIGNED5 [...] cp_Utf8
    code_LocalVariableTable_type_RS UNSIGNED5 [...] cp_Signature
    code_LocalVariableTable_slot UNSIGNED5 [...]
    code_LocalVariableTypeTable_N UNSIGNED5 [...]
    code_LocalVariableTypeTable_bci_P BCI5 [...]
    code_LocalVariableTypeTable_span_O BRANCH5 [...]
    code_LocalVariableTypeTable_name_RU UNSIGNED5 [...] cp_Utf8
    code_LocalVariableTypeTable_type_RS UNSIGNED5 [...] cp_Signature
    code_LocalVariableTypeTable_slot UNSIGNED5 [...]
    {code_attr_bands...} (various) [...] (various)
    bc_codes BYTE1 [...]
    bc_case_count | UNSIGNED5 | [COUNT(switch,*bc_codes)]
    bc_case_value DELTA5 [...]
    bc_byte BYTE1 [...]
    bc_short DELTA5 [...]
    bc_local UNSIGNED5 [...]
    bc_label BRANCH5 [...]
    bc_intref DELTA5 [...] cp_Int
    bc_floatref DELTA5 [...] cp_Float
    bc_longref DELTA5 [...] cp_Long
    bc_doubleref DELTA5 [...] cp_Double
    bc_stringref DELTA5 [...] cp_String
    bc_classref UNSIGNED5 [...] cp_Class
    bc_fieldref DELTA5 [...] cp_Field
    bc_methodref UNSIGNED5 [...] cp_Method
    bc_imethodref DELTA5 [...] cp_Imethod
    bc_thisfield UNSIGNED5 [...] cp_Field subsequence
    bc_superfield UNSIGNED5 [...] cp_Field subsequence
    bc_thismethod UNSIGNED5 [...] cp_Method subsequence
    bc_supermethod UNSIGNED5 [...] cp_Method subsequence
    bc_initref UNSIGNED5 [...] cp_Method subsequence
    bc_escref UNSIGNED5 [...] cp_All
    bc_escrefsize UNSIGNED5 [...]
    bc_escsize UNSIGNED5 [...]
    bc_escbyte BYTE1 [...]
    file_name | UNSIGNED5 | [#file_count] | cp_Utf8
    file_size_hi | UNSIGNED5 | [#file_count*(#have_file_size_hi)]
    file_size_lo | UNSIGNED5 | [#file_count]
    file_modtime | DELTA5 | [#file_count*(#have_file_modtime)]
    file_options | UNSIGNED5 | [#file_count*(#have_file_options)]
    file_bits | BYTE1 | [SUM(*file_size)]

    8.2. Appendix: Pseudo-Code Illustrations

    8.2.1. Representation of cp_Utf8 Constant Pool

    The following pseudo-code asserts the relations, as described above, between the band lengths and contents, and cp_Utf8 constant pool elements. (This code merely comments on the specification given above; it does not itself add new information to the specification.)
      assert(cp_Utf8[0].equals(""));
  int cursor = 0;
  int big_cursor = 0;
  for (int i = 1; i < cp_Utf8_count; i++) {
    String thisString = cp_Utf8[i];

    int prefix = (i == 1)? 0: cp_Utf8_prefix[i-2];
    int suffix = thisString.length() - prefix;
    String prevString = cp_Utf8[i-1];
    String prevPrefix = prevString.substring(0, prefix);
    String thisPrefix = thisString.substring(0, prefix);
    assert(prevPrefix.equals(thisPrefix));

    int small_suffix = cp_Utf8_suffix[i-1];
    char[] suffix_chars;
    int offset;
    if (small_suffix != 0) {
      assert(suffix == small_suffix);
      suffix_chars = cp_Utf8_chars;
      offset = cursor;
      cursor += suffix;
    } else {
      assert(suffix == cp_Utf8_big_suffix[big_cursor]);
      suffix_chars = cp_Utf8_big_chars[big_cursor];
      offset = 0;
      assert(suffix == suffix_chars.length);
      big_cursor += 1;
    }
    String thisSuffix = thisString.substring(prefix);
    String theseChars = new String(suffix_chars, offset, suffix);
    assert(thisSuffix.equals(theseChars));
  }
  assert(cp_Utf8_prefix.length == Math.max(0, cp_Utf8_count-2));
  assert(cp_Utf8_suffix.length == Math.max(0, cp_Utf8_count-1));
  assert(cp_Utf8_chars.length == cursor);
  assert(cp_Utf8_big_suffix.length == big_cursor);
  assert(cp_Utf8_big_chars.length == big_cursor);

    8.2.2. Representation of cp_Signature Constant Pool

    The following pseudo-code asserts the relations, as described above, between the band lengths and contents, and cp_Signature constant pool elements. (This code merely comments on the specification given above; it does not itself add new information to the specification.)
      int cursor = 0;
  for (int i = 0; i < cp_Signature_count; i++) {
    String sign = cp_Signature[i];
    String form = cp_Signature_form[i];
    int form_ptr = 0;
    int sign_ptr = 0;
    for (; form_ptr < form.length(); form_ptr++) {
      assert(form.charAt(form_ptr) == sign.charAt(sign_ptr));
      sign_ptr += 1;
      if (form.charAt(form_ptr) == 'L') {
        String cls = cp_Class[cursor];
        assert(sign.startsWith(cls, sign_ptr));
        cursor += 1;
        sign_ptr += cls.length();
      }
    }
    assert(sign_ptr == sign.length());
  }
  assert(cp_Signature_form.length == cp_Signature_count);
  assert(cp_Signature_classes.length == cursor);

    8.2.3. Representation of Byte Offsets

    The following pseudo-code asserts the relations, as described above, between a byte offset and its encoding in a band governed by a bc_index layout element. (This code merely comments on the specification given above; it does not itself add new information to the specification.)
      // ins_pos is a display of all instruction boundaries
  int[] ins_pos;
  ...
  Arrays.sort(ins_pos);
  assert(ins_pos[0] == 0);
  assert(ins_pos[ins_pos.length-1] == bytecodes.length);
  int regulars = ins_pos.length; //  # instruction boundaries
  ...
  int renumber_bci(int bci) {
    int i = Arrays.binarySearch(ins_pos, bci);
    return (i >= 0) ? i : (i == -1) ? bci : ins_pos.length + bci - (-i-1);
  }
  ...
  for (int bci = -100; bci <= bytecodes.length+100; bci++) {
    int bci_numbering_for_band = renumber_bci(bci);
    int i = Arrays.binarySearch(ins_pos, bci);
    if (i >= 0) {
      assert(ins_pos[i] == bci);
      assert(bci_numbering_for_band < regulars);
      assert(bci_numbering_for_band == i);
    } else if (0 < bci && bci < bytecodes.length) {
      int nexti = (-i-1);  // index of next instruction
      assert(ins_pos[nexti-1] < bci && bci < ins_pos[nexti]);
      int prevRegulars = nexti;
      int prevAll = bci;
      int prevIrregulars = prevAll - prevRegulars;
      assert(bci_numbering_for_band >= regulars);
      assert(bci_numbering_for_band == regulars + prevIrregulars);
    } else {
      // other (random) numbers are unchanged by renumbering
      assert(bci_numbering_for_band >= bytecodes.length ||
         bci_numbering_for_band < 0);
      assert(bci_numbering_for_band == bci);
    }
  }

    8.2.4. Representation of Predictable Nested Class Names

    The following pseudo-code asserts the relations, as described above, between the nested class's mangled name and the predictable outer and simple names. Note that searches for the literal characters '/' and '$' must be replaced in real implementations by searches for the character ranges associated with the SLASH and DOLLAR nonterminals. (This code merely comments on the specification given above; it does not itself add new information to the specification.)
      String bcn, predictableOuter, predictableICName;
  ...
  String name = bcn.substring(bcn.lastIndexOf('/')+1);
  int dollar2 = name.lastIndexOf('$');
  assert(predictableICName == null ||
         (predictableICName.charAt(0) > '9' &&
          predictableICName.indexOf('$') < 0));
  if (predictableICName == null) {
    // bcnCase1 or bcnCase4
    assert(predictableOuter == null);
    assert(dollar2 == -1 ||
           dollar2+1 == name.length() ||
           isDigit(name.charAt(dollar2+1)));
  } else if (predictableOuter == null) {
    // bcnCase2
    assert(name.endsWith("$"+predictableICName));
    int dollar1 = name.substring(0, dollar2).lastIndexOf('$');
    assert(dollar1 >= 0 && dollar1+1 < dollar2);
    assert(isDigitString(name.substring(dollar1+1, dollar2)));
  } else {
    // bcnCase3
    assert(bcn.equals(predictableOuter+"$"+predictableICName));
  }

    8.3. Appendix: Design FAQ

    Please mail questions to jsr-200-comments@Sun.COM This collection of frequently asked questions concerning the Pack200 archive format is meant to serve as a design rationale.

    8.3.1. General Questions

    1. Why not use an existing generic compression mechanism, such as .jar, .zip, or .tar.gz files? First, it is better to know the structure of a thing compressed. Second, a zip or jar archive is compressed element-wise not globally. This means that any symbol shared by several classes must be mentioned independently once in each class file. Third, the structure of an individual class file is really an interleaving of many different kind of data, each with their own statistics, which limits the effectiveness of a single-stream compressor such as gzip. The specific benefit of reordering the data into bands is about a factor of two, independently of the quality of the off-the-shelf compressor used as a post-pass. There are also significant marginal benefits from the various type-specific recoding techniques. The net result is to improve a compression factor from 2-4X to 7-9X.

    2. Why is this specification so complex? The techniques described here are the result of much experimentation over several years. Each feature of this specification is thought to contribute measurably to the overall compression ratio achieved by this technology. The authors would be happy to be shown, by benchmarks, that some given feature can be omitted without significant loss of compression performance.

      (A compression performance multiplier of 1.002 or more for some particular technique is significant, because such multipliers accumulate readily into performance that end-users notice. A multiplier of less than 1.0005 is insignificant.)

    3. The Pack200 transmission format is closely tied to the current class file format. Won't it go out of date as soon as the class file format evolves further? Further developments are likely to take the form of new attributes or perhaps new bytecodes. The layout language defined by Pack200 supports a very wide range of attribute formats, including arbitrary mixes of bytes and constant pool references. Likewise, the bytecode representation includes escape operators which can represent arbitrary mixes of data and constant pool references. Although such constructs will not compress as optimally as the features for which this specification is directly designed, it appears that reasonable future extensions will continue to be transmittable, without disturbing the compression of current features, and without requiring decompressors to be updated.

    4. Since Pack200 is a lossy compression algorithm, won't it break signed JAR files? Signed JAR files contain secure hashes over the bytewise contents of individual class files. Any change to the bits of a class file will change its hash code, making the innocuous changes of Pack200 indistinguishable from attacks on the application code.

      Pack200, like many other compression algorithms, allows the compressor many degrees of freedom in choosing the contents of the compressed archive, but no degrees of freedom in choosing the contents of the decompressed JAR file. Given a compressed archive, all compliant Pack200 decompressors must produce the same class file bytes, for each transmitted class file. This stability of output persists for class files even if a resource file (such as the manifest) changes its contents. Thus, for any given class file, compression may be lossy, but the decompression of each class file must be exact, in a useful way defined by the Pack200 specification.

      This means that a compressor with the right stability properties can be used to produce a signed, packed JAR using these steps:

      1. Pack the original signed JAR file.
      2. Unpack it, producing perturbed class files.
      3. Re-sign it, ensuring that only the manifest changes.
      4. Re-pack it, using the updated manifest.

      (Note: If this specification allows two compliant decompressors to produce different JAR archive elements for the same compressed archive input, it is a bug in the specification. The specification is thought to be free of such bugs, but if you find one please report it.)

    5. What is the relationship between file names in Pack200 archives and file names in JAR (or ZIP) archives or disk files? Pack200 specifies that file names are transmitted as Utf8 strings. Since these strings are intended to function as names of JAR elements in functioning Java applications, the strings must also conform to Java usage, which also represents pathnames as Utf8 strings in JAR files and 16-bit Unicode in memory. Also, in JAR files, pathname components are separated by the forward slash character ('/'), and not by any system-specific character. This allows class loaders to easily convert the internal representation of the class names (e.g., "java/lang/Object") to pathnames (e.g., "java/lang/Object.class").

      The Pack200 specification does not dictate the interpretation of file name strings with respect to any other tool or operating system. However, the natural mapping would be as coherent as possible with Java's usages.

    6. What is the relationship between file dates in JAR (or ZIP) archives or disk files? Pack200 specifies that file dates are transmitted as 32-bit counts of seconds relative to Java's time base (i.e., System.currentTimeMillis divided by one thousand). This provides absolute times relative to UTC, at a one-second granularity. If an operating system provides more accurate file times, they must be adjusted to a nearby whole second before transmission in a Pack200 archive.

      JAR and ZIP store dates in local format (i.e., "YYYY/MM/DD HH:MM:SS") with no timezone specification. This means that conversion to and from Java's UTC-based times requires a guess at the timezone under which the compressor was operating. (This problem is not unique to Pack200. It is a problem with all uses of ZIP and JAR archives.) For many purposes, the standard guess is that the decompressor and compressor were operating in the same timezone and during the same yearly daylight savings time regime. However, in order to provide more stability in the times transmitted in Pack200 archives, it is expected that most compressors and decompressors will agree to use UTC as the timezone when interpreting ZIP-style local times.

    7. Doesn't the JEFFtm file format also oprovide a class-specific compression algorithm? Yes, the JEFF Working Group has defined a standard file format (ISO/IEC 20970) which allows class files to be compressed about 50% and also loaded directly into memory for interpretive execution. As compression performance, it is comparable with the DEFLATE algorithm used within JAR archives. Pack200 provides much greater compression. However, Pack200 archives are not designed for direct execution by any virtual machine. The greater compression level of Pack200 is won at a cost of complexity in the unpacker, a complexity incompatible with any requirement of direct loading or execution.

    8. Why doesn't Pack200 use Huffman encoding? (Same question for LZW, or BWT, or move-to-front, or any other standard compression technique.) As a matter of simplicity and division of labor, Pack200 intentionally focuses on finding and removing large-scale redundancies specific to class files. Pack200 produces a byte-oriented output, hopefully with clear patterns and a simple alphabet statistics. It relies on on a post-pass compressor to encode these bytes in some more efficient string-sharing, bit-sliced representation.

      The following considerations support this design:

      • Repeating similar compression tactics in two places in a pipeline of transformations can actually degrade overall compression. For example, doing move-to-front in Pack200 band transmission would make it harder for the DEFLATE algorithm to detect repeated patterns, because they would have varying spellings in the tokens DEFLATE would observe. (Delta encoding also has this risk, which is why it's optional in Pack200. But, off-the-shelf back ends don't generally do delta encoding.)
      • Relying on an off-the-shelf backend for final compression simplifies the Pack200 design.
      • It also lets Pack200 leverage the latest byte-oriented compression tools.
      • Such factoring also simplifies engineering of packer heuristics.
      • The job of Pack200 is to find redundancies and patterns at class and package scales. It seems cleaner to avoid messing with byte-level scales.
      • Some specific standard compression techniques may still be encumbered by patents, even on simple, self-evident techniques. Avoiding such patents is a significant cost in engineering a compressor. We would rather avoid this cost by using a standard tool.

    9. How does this specification cope with archive format changes? The major and minor version numbers of a Pack200 archive advertise which version of this standard has been generated by a packer. As of 2005 there are two versions, 160.1 for Java 6 and 150.7 for Java 5. Because of the flexibility of attribute layouts, packers can sometimes represent new classfile formats in old archive formats, but newer archive formats may be required for reasons of functionality or performance.

      Unpacker implementations are strongly encouraged to support each standard version of the archive format, since there is not always a strong alignment between packer and unpacker versions at either end of a deployment channel. Packer implementations are encouraged to preserve the ability to emit older archive formats, to maintain maximum compatibility with unpackers.

      The reference implementation chooses to maintain backward compatibility by producing a 1.5 pack format if the input JAR archive contains 1.5 (or lower) classfiles. Otherwise it will produce a 1.6 pack file. The reference implementation unpacker is compatible with all previous standard versions.


Improvements to Program Execution Speed

 Documentation Contents

Enhancements in JDK 6

Descriptions of the many performance enhancements in JDK 6 can be found on the performance web site in the Java SE 6 Performance Whitepaper .

Enhancements in JDK 5.0

The following are some of the enhancements made for improved program execution speed in JDK 5.0.
  • Garbage collection ergonomics - Provides for the automatic detection and choice of the client or server runtime compiler, which enhances performance on server-class machines. See "Server-Class Machine Detection" and "Garbage Collection Ergonomics" at Java Virtual Machines for more information.

  • StringBuilder class - The addition of a new class StringBuilder that works essentially as an unsynchronized StringBuffer for performance enhancement. You should replace all StringBuffer uses with StringBuilder unless you need the synchronization (which you almost certainly don't). StringBuilder is almost always faster than StringBuffer.

  • Java 2DTM technology - These Java 2D performance enhancements have spin-off performance benefits in other areas of functionality such as Swing/JFC. Examples include improved acceleration for BufferedImage objects, support for hardware-accelerated rendering using OpenGL, and improved text-rendering performance. See New Java 2D Features for more information.

  • Image I/O - Performance and memory usage improvements have been made when reading and writing JPEG images. See "Improved Performance" at Image I/O Features.

Enhancements in J2SDK 1.4

The following are some of the enhancements made for improved program execution speed in J2SDK 1.4.
  • Java 2DTM technology - These Java 2D performance enhancements have spin-off performance benefits in other areas of functionality such as Swing/JFC. One example of performance improvement in J2SDK 1.4 is that remote X display on Solaris is greatly improved. See New Java 2D Features for more information on Java 2D enhancements, including performance enhancements.

  • java.nio - The New I/O API provides for improved performance in the areas of buffer management, scalable network and file I/O, character-set support, and regular-expression matching. The New I/O APIs supplement the I/O facilities in the java.io package. For more information, see I/O APIs.

  • Reflection - Beginning with J2SDK 1.4.0, certain reflective operations, specifically java.lang.reflect.Field, java.lang.reflect.Method.invoke(), java.lang.reflect.Constructor.newInstance(), and Class.newInstance(), have been rewritten for higher performance. Reflective invocations and instantiations are several times faster than in previous releases.

  • Networking - The networking functionality in J2SDK 1.4 has improved performance for Http streaming.

  • java.math - New static method probablePrime has been added to class BigInteger for generating prime numbers. Previously, the sole means of generating a prime BigInteger required the caller to provide a 'certainty' (the log of the probability of compositeness that the caller was willing to tolerate). However, providing an unreasonable value for the certainty could lead to poor performance (if the certainty was too high) or serious bugs (if it was too low). The new prime-generation method provides an efficient algorithm for generating primes using an automatically determined, appropriate value for the certainty based on a draft ANSI specification (X9-80).

  • Hotspot - The Java HotSpot[TM] virtual machine now uses "full-speed debugging". In the previous version of HotSpot, when debugging was enabled, the program executed using only the interpreter. Now, the full performance advantage of HotSpot Technology is available to programs running with debugging enabled. The improved performance allows long running programs to be more easily debugged. It also allows testing to proceed at full speed and the launch of a debugger to occur on an exception.

Enhancements in J2SDK 1.3

The following are some of the changes made to improve the program execution speed and general runtime performance in previous release J2SDK 1.3. These enhancements have been carried forward into J2SDK 1.4.

Links to relevant bug reports on the BugParade web site are provided were applicable for further information.

  • Improved Performance for readUTF and writeUTF - The implementations of the readUTF and writeUTF methods of DataInputStream and DataInputStream have been modified to improve performance. This is a fix for bug number 4219771 on the BugParade web site.

  • Improved Performance of JScrollPane Painting - The implementation of JScrollPane has been improved so that it does not cause excessive painting and screen flashing when double buffering is not used.

  • Improved JTable Performance - The performance of the JTable's column-handling functionality has been improved. Previously, the performance of the operations of adding columns or recalculating column widths did not scale well as the number of columns became large. The implementation has been changed to improve scalability. This is a fix for bug number 4223642 on the BugParade web site.

  • Paint Coalescing - Painting performance has been enhanced through the implementation of an improved paint coalescing algorithm. Areas that require repainting are coalesced into a single, non-rectangular repaint area as they are posted to the event queue. This has the effect batching repaints, executing multiple repaints simultaneously in a manner more efficient than in previous releases.

  • Frame Resizing - Resizing of top-level frames has been improved.

  • Internal Frame Blitting - By using Graphics.copyArea calls, Swing's DefaultDesktopManager now needs to redraw far less when frames are dragged.

  • Performance Enhancements in BigIntenger - Class java.math.BigInteger has been reimplemented in pure Java programming-language code. Previously, BigInteger's implementation was based on the Plumb C library. The new implementation performs all standard operations much faster than the old implementation. The speed-up realized in the new implemenation can be as much as 5x or more, depending on the operation being performed.

  • Provision for Better-Performing Numeric Operations - The Java 2 Platform now contains two classes which provide API for performing general numeric operations.
    • java.lang.StrictMath - Class java.lang.StrictMath is a renaming of class java.lang.Math from previous versions of the Java platform, but otherwise retains the previous specification of Math. In particular, it is defined to return bit-for-bit reproducible results in all implementations.
    • java.lang.Math - Class java.lang.Math provides the same set of API as does class StrictMath. However, unlike some of the numeric functions of class StrictMath, all implementations of the equivalent functions of class Math are not defined to return the bit-for-bit same results, but can vary within specified constraints. This relaxation permits better-performing implementations where strict reproducibility is not required.

Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved.

 Sun


Performance Enhancements

 Documentation Contents
The most significant performance enhancements to the Java Platform are detailed below.
Performance Enhancements
  • Improvements to Program Execution Speed

More Information

  • Performance Documentation for the Java Platforms
  • Performance and Scalability Guide (J2SE 1.4)
  • Java HotSpot Performance FAQ
  • Java HotSpot VM Options (on the java.sun.com web site)

* As used on this web site, the terms "Java Virtual Machine" or "JVM" mean a virtual machine for the Java platform.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun


Java(TM) Plug-in

Java

The JavaTM Plug-in

 Documentation Contents
JavaTM Plug-in enables applets written to the Java SE Platform 6 specification to be run in Mozilla and Internet Explorer web browsers. Java Plug-in comes with the 6 JRE/JDK.
Java Plug-in Developer Guide
The Java Plug-in Developer Guide provides documentation in the following areas:
  • Java Plug-in Basics
  • Deployment Schemes
  • Security
  • Debugging Support
  • Advanced Topics
Common DOM API
Applet developers can use the Common DOM (Document Object Model) API when writing applets intended to run with Java Plug-in. The Common DOM API enables developers to traverse the DOM from within their applets. The Common DOM API is supported only in applets that run with 1.4, 5.0 or 6 versions of Java Plug-in.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: java-plugin-feedback@sun.com 		Sun
Java Software


Applet Caching and Installation in Java Plug-in

Applet Caching

This section covers the following topics:

  • Caching Option
    • cache_archive
    • cache_version
    • cache_archive_ex
    • Cache Update Algorithm
  • Security
  • Known Issues

Caching Option

When an applet is cached, it no longer needs to be downloaded when referenced again. This reduces applet startup time. All file types used by Java Plug-in applets are now cached.

An alternative form of applet caching is provided which allows an applet deployer to decide if an applet should be sticky A sticky applet is placed in a disk cache created and controlled by Java Plug-in which the browser cannot overwrite. The only time a sticky applet gets downloaded after caching is when it is updated on the server. Otherwise the applet is always available for fast loading. Applets providing core business applications should be made sticky to improve startup performance.

This new feature is activated by including the new cache_archive, cache_version , and cache_archive_ex values in the OBJECT/EMBED tag as described below.

Note

.jar files specified with the archive attribute also get cached in this sticky cache.

cache_archive

The cache_archive attribute contains a list of the files to be cached:

<PARAM NAME="cache_archive" VALUE="a.jar,b.jar,c.jar">

Like the archive attribute in the APPLET tag, the list of .jar files in the cache_archive attribute do not contain the full URL, but are always downloaded from the codebase .

cache_version

The cache_version is an optional attribute. If used, it contains a list of file versions to be cached:

<PARAM NAME="cache_version" VALUE="1.2.0.1, 2.1.1.2, 1.1.2.7">

Each version number is in the form xxxx.xxxx.xxxx.xxxx, where x is a hexadecimal number. Each version number corresponds to a respective .jar file in the cache_archive.

cache_archive_ex

In order to allow pre-loading of .jar files, the HTML parameter cache_archive_ex can be used. This parameter allows you to specify whether the .jar file needs to be pre-loaded; optionally the version of the .jar file can also be specified. VALUE for cache_archive_ex has the following format:

VALUE="<jar_file_name>;<preload(optional)>;<jar_file_version(optional)>,<jar_file_name>; <preload(optional)>;<jar_file_version(optional)>, ..."

The optional tags preload and jar_file_version can appear after the jar_file_name in any order separated by the delimiter ";". "," separates multiple entries.

The following shows how these tags might be used in an HTML page:

<OBJECT .... >
<PARAM NAME="archive" VALUE="a.jar">
<PARAM NAME="cache_archive" VALUE="b.jar, c.jar, d.jar">
<PARAM NAME="cache_version" VALUE="0.0.0.1, 0.0.2A.1, 0.3D.22.FFFE">
<PARAM NAME="cache_archive_ex" VALUE="applet.jar;preload, util.jar;preload;0.9.0.AC1, tools.jar;0.9.8.7F">
</OBJECT>

In the above example, a.jar is specified in archive, whereas b.jar, c.jar and d.jar are specified in cache_archive. The versions are also specified for b.jar, c.jar, and d.jar as 0.0.0.1, 0.0.2A.1, and 0.3D.22.FFFE, respectively. In cache_archive_ex, applet.jar is specified to be pre-loaded. util.jar is also specified to be pre-loaded but along with the version. For tools.jar, only version is specified.

Java Plug-In doesn't compare the versions if they are not specified for all the .jar files specified in HTML parameter cache_archive. If cache_archive is used without cache_version, the .jar files specified in cache_archive are treated no differently than the .jar files specified in HTML parameter archive. Similar treatment is given to .jar files specified in cache_archive_ex when preload and version options are not provided.

Class files and resources will be searched in the following order from the .jar files specified by the HTML parameters

  1. cache_archive_ex
  2. cache_archive
  3. archive

Applet Caching Update Algorithm

By default, without the cache_version attribute, applet caching will be updated if:

  • The cache_archive has not been cached before, or
  • The "Last-Modified" value of the cache_archive on the web server is newer than the one stored locally in the applet cache, or
  • The "Content-Length" of the cache_archive on the web server is different from the one stored locally in the applet cache.

However, in some situations, the "Last-Modified" value returned from the web server through HTTP/HTTPS may not reflect the actual version of the applets. For example, if the web server crashes and all the files are restored, the cache_archive may have a different modification date on the server. Even if the cache_archive has not been updated, it will still force all the Java Plug-in clients to download the cache_archive again.

To strongly enforce the version update, it is recommended that the applet deployer use the cache_version attribute.

If cache_version is used, applet caching will be updated if the cache_version for the cache_archive is larger than the one stored locally in the applet cache. Note that the version number is used for triggering an update; there is no actual version number attached to the .jar file on the web server. In fact, unless version is used to trigger an update, it is possible the applet on the web server could be updated without the applet in cache_archive.

Using cache_version eliminates the need to connect to the web server to obtain "Modification-Date" and "Content-Length" of the cache_archive. In most cases this will speed up performance.

Security

Although sticky applets are cached locally, they will still conform to the security policy defined by their original codebase and signer.

Versioning Support

Java Plug-in 6 applets can use the JNLP Version Download protocol for launching JAR resources listed in the HTML file. Versioning also supports JarDiff. To use versioning support use the archive_x tag where x specifies a number. The following is the syntax of the archive_x tag.

  • First value must be the jar filename
  • Each value must be separated by comma
  • Use preload to indicate preloading of the jar file
  • version= is used to specify the version string for the jar file request

The following are the various ways in which the archive_x tag can be used.

<PARAM NAME="archive_1" VALUE="a.jar, preload, version=2.0+">

  • The + sign after the version indicates the Java Plug-in to request for a jar file whose version is equal to or higher than the specified version
<PARAM NAME="archive_1" VALUE="a.jar, preload, version=2.0*">
  • The * sign after the version indicates the Java Plug-in to request for a jar file whose version begins with 2.0, e.g 2.0.1 or 2.0.2
<PARAM NAME="archive_2" VALUE="b.jar, version=0.0.0.3">
  • This allows Java Plug-in to request for a jar file whose version is exactly 0.0.0.3

Note

The archive_x tag is ignored if it found within the cache_archive, cache_version and cache_archive_ex tag.

Applets using JNLP style version support should use the JNLPDownloadServlet to host the applet resources. More information about JNLP Version Download protocol and JNLPDownloadServlet is available in the JNLP Guide.

Known Issues

  • Caching of the .jar files specified in the manifest's Class-Path variable using Java Plug-in's cache is currently not supported.
  • The path specified in the cache_archive must be a relative URL to the applet's codebase. Full URLs are not supported in cache_archive.
  • The "java.io.IOException: Caching not supported for ..." is thrown because Java Plug-in could not get the expiration and last-modification dates for a given JAR file from the web server. If the Java Plug-in cannot get the date information, the JAR file is downloaded every time it is used.


Applet Persistence API

Beginning with JDK 1.4, two new methods have been added to interface java.Applet.AppletContext to allow applet persistence across browser sessions. These methods are:

  • setStream(String key, InputStream stream)
  • getStream(String key)

These new methods enable the applet developer to stream data and objects from one browser session so that they can be reused in subsequent browser sessions. This provides applet persistence and makes it unnecessary to use static objects in applets for this same purpose.

setStream(key, stream) maps a key to a stream. getStream(key) returns the stream mapped to the key. If the AppletContext already has a stream mapped to the key when setStream(key, stream) is invoked, the mapping is updated.

See the API specification for more information


Cookie Support

See Cookie Support in the Java Deployment Guide.


Deploying Java Extensions

Note: Java Extensions are also referred to as optional packages, standard extensions, or simply extensions.

This section covers the following topics:

  • Overview
  • Manifest of the applet JAR file
  • Manifest of each extension JAR file
  • Manifest of the Implementation-URL JAR file
    • Installing Java Extensions Using Raw installation
    • Installing Java Extensions Using Java Installer
    • Installing Java Extensions Using Native Installer
  • Security
  • Detailed Instructions
  • Known Limitations and Other Notes

Java applets may use Java extensions to provide extra functionality to users. Java Plug-in enables applets to trigger installation of various Java extensions (e.g., JavaHelp, Java 3D, Java Media Framework ...) in the Java Runtime Environment. This document describes the basic steps for deploying installed Java extensions (versus bundled Java extensions) with Java Plug-in. For details about how Java Extensions work, see the The Java Extensions Mechanism.

Overview

An applet that uses extensions is packaged as a signed JAR file including manifest. When an applet is downloaded and run with Java Plug-in, Java Plug-in checks the manifest of the applet JAR file. The manifest will contain a list of all extensions that the applet requires. An extension consists of one or more JAR files to be installed into the <jre>/lib/ext directory.

In general, for each extension the applet manifest will list name, vendor, and version information of the extension JARs; it will also list URLs from which the JARs, or an installer for them, may be obtained if the JARs are not already installed <jre>/lib/ext or are out of date. A URL may directly specify one of the extension JARs, or it may specify an installer, native or Java, that will install the extension JARs. The rules for deciding that an update is required are described in Optional Package Versioning.

To use Java Plug-in for deploying Java Extensions, information about the extensions must be specified in three different manifest files:

  1. Manifest of the applet JAR file

  2. Manifest of each extension JAR

  3. Manifest of the Implementation-URL JAR file

Each of these types of manifest files is described in detail below.

Manifest of the applet JAR file

To deploy Java extensions with an applet, the applet must be packaged as a JAR file. Moreover, the manifest file of the applet JAR must define the list of extensions it requires and specify the URLs from which the extensions can be downloaded, along with other information about the extensions, according to the Optional Package Versioning. For example, below is the manifest file for two extensions:

Extension-List: RectangleArea RectanglePerimeter
RectangleArea-Extension-Name: com.mycompany.RectangleArea
RectangleArea-Specification-Version: 1.2
RectangleArea-Implementation-Version: 1.2
RectangleArea-Implementation-Vendor-Id: com.mycompany
RectangleArea-Implementation-URL: http://mycompany.com/RectangleArea.jar
RectanglePerimeter-Extension-Name: com.mycompany.RectanglePerimeter
RectanglePerimeter-Specification-Version: 1.2
RectanglePerimeter-Implementation-Version: 1.2
RectanglePerimeter-Implementation-Vendor-Id: com.mycompany
RectanglePerimeter-Implementation-URL: http://mycompany.com/RectanglePerimeter.jar

In this example, two extensions are deployed with the applet—RectangleArea and RectanglePerimeter. Each has a single JAR file. If they have not been installed or if updated versions are needed, the proper versions will be downloaded from the Implementation-URL specifications. Notice that an Implementation-URL must point to a JAR file that:

  • is the desired extension JAR itself (for raw installation) or
  • contains a Java installer that will install the extension or
  • contains a native installer that will install the extension.

This will be explained in detail in the section below called The manifest of the Implementation-URL JAR file.

Extension-List names and attribute prefixes

There are two basic scenarios here: An extension may have a single JAR file, or it may have multiple JAR files. Extension-List names and attribute prefixes are discussed below for these two scenarios:

Extension with single JAR file

For an extension with a single JAR file (as in the example above), the name in the Extension-List, and the prefix of the related manifest attributes, should be the name of the extension JAR file.

Extension with multiple JAR files

Some extensions consist of multiple JAR files. For example, the Java 3D extension consists of the following JAR files: j3daudio.jar, j3dcore.jar, j3dutils.jar, and vecmath.jar. There are two scenarios that need to be considered: (1) The JARs are installed by a native or Java installer or (2) no installer is used (i.e., raw installation of the extension JARs).

If a native or Java installer is used to install an extension, then only one of the JAR file names should be used in the Extension-List, and only one set of attributes, using that name as the prefix, should appear. Usually an extension has a main JAR file; if so, you should use its name in the Extension-List and as the prefix for the related manifest attributes. If there is no main JAR file, you can use the name of any JAR file in the optional package.

Here is an example of the applet manifest for the Java 3D extension. j3dcore.jar is the main JAR file.

Extension-List: j3dcore
j3dcore-Extension-Name: javax.media.j3d
j3dcore-Specification-Version: 1.2
j3dcore-Specification-Vendor: Sun Microsystems, Inc
j3dcore-Implementation-Version: 1.2.1_03
j3dcore-Implementation-Vendor-Id: com.sun
j3dcore-Implementation-URL: http://<myserver>/native/java3d-win.jar

For a raw installation with multiple JAR files, the story is different: You must treat each JAR file as though it were a separate extension and list each according to its name in the Extension-List. Each one listed then must have its own set of manifest attributes, where the prefix for an attribute set is the name of the related JAR file.

Note on JAR Extension Identification:

Note that Java Plug-in checks four manifest attributes of an installed extension JAR file:

  • Extension-Name
  • Specification-Version
  • Implementation-Version
  • Implementation-Vendor-Id

Extension-Name and Implementation-Vendor-Id must match exactly the values specified in the applet manifest file.

  • See Optional Package Versioning for how Java Plug-in evaluates the version attributes of an installed extension to decide if a newer extension needs to be downloaded.
  • See Appendix 6: Sun-Supported Specification-Version and Implemenation-Version Formats for rules about the format of Specification-Version and Implemenation-Version.

Manifest of each extension JAR file

Here we are talking about the JAR files that Plug-in can obtain from the URLs specified by Implemenation-URL. The URL-obtainable extension JARs may be directly obtained (raw installation) or they may be obtained via a Java or native installer. In either case they are installed into <jre>/lib/ext.

The extensions that the applet requires are listed in the applet manifest. This allows Plug-in to examine the JAR files present in the <jre>/lib/ext directory when an applet is launched and to decide if it needs to install missing or out-of-date extensions.

In general, the manifest of an extension JAR obtained via an Implementation-URL needs to include various name, version, and vendor information. Thus, when such an extension JAR is installed, it will be possible in the future for Java Plug-in to compare this information to the information about an extension that an applet requests; and Plug-in will be able to determine if an extension needs to be installed/upgraded. Prior to any applet ever requesting an extension, it is more than likely that no extension is installed in <jre>/lib/ext, or that no or incomplete manifest information is present in the installed extension JAR.

For an extension with a single JAR file, the JAR file must be signed and include a manifest file with the following attributes:

  • Extension-Name
  • Specification-Vendor
  • Specification-Version
  • Implementation-Vendor-Id
  • Implementation-Vendor
  • Implemenation-Version

Example

Extension-Name: javax.help
Specification-Vendor: Sun Microsystems, Inc
Specification-Version: 1.0
Implementation-Vendor-Id: com.sun
Implementation-Vendor: Sun Microsystems, Inc
Implementation-Version: 1.1.3

If an extension consists of more than one JAR file and the extension is installed with a native/Java installer, then only the JAR file whose name is listed in the Extension-List of the applet manifest needs to have extension information (i.e., Extension-Name, Specification-Version, etc.). If no installer is used, then all JAR files must include extension information.

See Optional Package Versioning for more information about these attributes.

Manifest of the Implementation-URL JAR file

This is the JAR file which the applet refers to with the Implementation-URL attribute in its manifest. It is the URL from which the extension can be obtained if no extension is installed in <jre>/lib/ext, or an extension is installed but it is out of date.

If the Implementation-URL JAR is a native or Java installer, this is indicated in the manifest via two special attributes: Main-Class indicates a Java installer; Extension-Installation indicates native installer. Note that if no installer is indicated, then the Implementation-URL JAR file is simply the extension JAR file itself. There are three ways that extensions can be installed by Java Plug-in. They are:

  • Using Raw Installation
  • Using Java Installer
  • Using Native Installer

Each method is discussed below:

Installing Java Extensions Using Raw Installation

With raw installation of an extension, each extension JAR is installed by Java Plug-in into the <jre>/lib/ext directory without an installer (Java or native); i.e., Java Plug-in is the "installer" for each JAR. If an extension has a single JAR file, then the URL of that JAR is shown as the Implementation-URL in the applet JAR manifest; and Java Plug-in knows it is a raw extension because the manifest of the extension JAR file includes neither Main-Class nor Extension-Installation attribute.

Suppose we have an extension called javax.mediax with a single JAR, mediax.jar. Then the applet and extension JAR might be as shown below:

Example: Applet JAR manifest

Extension-List: mediax
mediax-Extension-Name: javax.mediax
mediax-Specification-Version: 1.1
mediax-Implementation-Version: 1.1.2
mediax-Implementation-Vendor-Id: com.sun
mediax-Implementation-URL: http://java.sun.com/products/plugin/extensions/examples/media/mediax.jar

Example: Extension JAR manifest

Extension-Name: javax.mediax
Specification-Vendor: Sun Microsystems, Inc
Specification-Version: 1.1
Implementation-Vendor-Id: com.sun
Implementation-Vendor: Sun Microsystems, Inc
Implementation-Version: 1.1.2
Now suppose we have another version, javax.mediax-2, that has two JARs: mediax_core.jar and mediax_codec.jar. Then we must treat the two JAR files as though they were separate extensions and list each in the applet JAR manifest.

Example: Applet JAR manifest

Extension-List: mediax_core mediax_codec
mediax_core-Extension-Name: javax.mediax_core
mediax_core-Specification-Version: 1.1
mediax_core-Implementation-Version: 1.1.2
mediax_core-Implementation-Vendor-Id: com.sun
mediax_core-Implementation-URL: http://java.sun.com/products/plugin/extensions/examples/media/mediax_core.jar
mediax_codec-Extension-Name: javax.mediax_codec
mediax_codec-Specification-Version: 1.1
mediax_codec-Implementation-Version: 1.1.2
mediax_codec-Implementation-Vendor-Id: com.sun
mediax_codec-Implementation-URL: http://java.sun.com/products/plugin/extensions/examples/media/mediax_codec.jar

Example: Extension JAR manifests

Extension-Name: javax.mediax_core
Specification-Vendor: Sun Microsystems, Inc
Specification-Version: 1.1
Implementation-Vendor-Id: com.sun
Implementation-Vendor: Sun Microsystems, Inc
Implementation-Version: 1.1.2
Extension-Name: javax.mediax_codec
Specification-Vendor: Sun Microsystems, Inc
Specification-Version: 1.1
Implementation-Vendor-Id: com.sun
Implementation-Vendor: Sun Microsystems, Inc
Implementation-Version: 1.1.2

Installing Java Extensions Using Java Installer

An extension can be installed through a Java installer. The Java installer must be bundled as a JAR file, and the resulting JAR file must be specified as Implementation-URL in the applet JAR manifest file. During installation the JAR file will be downloaded and verified, and the Main-Class of the Java installer inside the JAR file will be executed to start the installer. It is the job of the Java installer to copy the extension JAR files, normally bundled with the installer, into the right location of the Java Runtime (i.e., <jre>/lib/ext).

Though we are now dealing with an application JAR file, the attributes in its manifest should be the same as those shown for the extension JAR whose name is listed in the Extension-List of the applet manifest—with the addition of the Main-Class attribute.

Example: Java Installer JAR manifest

Extension-Name: javax.help
Specification-Vendor: Sun Microsystems, Inc
Specification-Version: 1.1
Implementation-Vendor-Id: com.sun
Implementation-Vendor: Sun Microsystems, Inc
Implementation-Version: 1.1.3
Main-Class: com.sun.javahelp.installer
In this case, because Main-Class is present in the manifest, the JAR will be treated as a Java Installer, and Main-class will be invoked. It is the job of the Java installer to copy the extensions JAR files into the <jre>/lib/ext directory. Note that each extension JAR file must contain proper versioning information.

Installing Java Extensions Using Native Installer

An extension can also be installed through a native installer. The native installer must be bundled as a JAR file, and the resulting JAR file must be specified as the Implementation-URL in the applet JAR manifest file. During installation the JAR file will be downloaded and verified, and the native installer will be started. It is the job of the native installer to copy the extension JAR files, normally bundled with the installer, into the right location of the Java Runtime (i.e., <jre>/lib/ext).

Though we are now dealing with an application JAR file, the attributes in its manifest should be the same as those shown for the extension JAR whose name is listed in the Extension-List of the applet manifest—with the addition of the Extension-Installation attribute.

Example: Native Installer Jar Manifest

Extension-Name: javax.media.jmf
Specification-Vendor: Sun Microsystems, Inc
Specification-Version: 2.1
Implementation-Vendor-Id: com.sun
Implementation-Vendor: Sun Microsystems, Inc
Implementation-Version: 2.1.1
Extension-Installation: jmf-2_1_1-win.exe

In this case, because Extension-Installation is present in the manifest, the JAR will be treated as a native installer; and the installer itself will be launched. It is the job of the native installer to copy the Java extensions into the <jre>/lib/ext directory. Note that each Java extension JAR file must contain proper versioning information.

Security

When an installed extension needs to be updated, the extension will be downloaded and verified to ensure that it is correctly signed. If it is valid, the Plug-in may pop-up a security dialog providing user with an option to continue with extension installation or cancel the installation.

Once the user selects the option from the security dialog, the extensions installation will be executed in the corresponding security context. The applet will not be started until the extensions are properly installed.

Because Java extensions are downloaded and installed into the Java Runtime <jre>/lib/ext directory, each must be signed. Once the extensions are installed, they will have the permissions granted to Java extensions through the policy file.

Detailed Instructions

Follow these steps to set up extensions for use with Java Plug-in:

I. Create/obtain the extensions that your applet needs.

Each extension will consist of one or more JAR files, each of which must include a manifest file with version information as described above in Manifest of each extension JAR file, and each must be signed. (See exception to this with mulitple JARs installed with native/Java installer.)

To create a JAR file from any set of files, use this command:

% jar cmf my_manifest my_jar input_files

For more information about the jar tool, see the Tools and Utilities documentation for your platform.

To sign the JAR file is going to take some trouble. In outline form, this is what you can do:

  1. Use the keytool -genkey option to generate a key pair.
  2. Use the keytool -certreq to generate a certificate request for a Certificate Authority (CA), such as VeriSign and Thawte. Email the request to the CA. After the CA has confirmed your identity, it will respond with a certificate chain via email. Copy the certificate chain to a file.
  3. You can then use the keytool -import option to import the chain to the keystore.
  4. You can now use the jarsigner tool to sign the JAR and the -verify option to check that it is signed.

For more information about keytool and jarsigner, see the Tools and Utilities documentation for your platform.

More information on this topic, along with examples, is given in the chapter called How to Sign Applets Using RSA-Signed Certificates. Although that chapter discusses how to sign an applet JAR file, the process is identical to signing an extension JAR file.

II. Create/obtain the Implementation-URL JAR files

If no installer is to be used:

The extension JAR files described in step I are the Implementation-URL JARs.

If an installer is to be used:

  1. Create/obtain the installer.
  2. Create the manifest for the JAR of the installer and any bundled extensions that need to go into it.
    • For a Java installer include the Main-Class attribute in the manifest;
    • for a native installer include the Extension-Installation attribute.
  3. JAR the installer, the manifest, and any bundled extensions that need to be included and sign the JAR. (The steps for JARing and signing are the same as described in step I above.)

Example

Suppose we have an applet that requires Sun's Java Advanced Imaging as an installed extension. You can download this here:

http://java.sun.com/products/java-media/jai/downloads/download.html

Suppose you select the "Windows JRE Install" version. The following file will be downloaded:

jai-1_1_1_01-lib-windows-i586-jre.exe

This installer bundles the following JAR files, which it will install into the <jre>/lib/ext directory:

  • jai_codec.jar
  • jai_core.jar
  • mlibwrapper_jai.core

You need to create the manifest for a JAR file that contains the .exe installer above, and you need to sign the JAR file.

The manifest would look like this:

Extension-Name: javax.media.jai
Specification-Vendor: Sun Microsystems, Inc
Specification-Version: 1.1
Implementation-Vendor-Id: com.sun
Implementation-Vendor: Sun Microsystems, Inc
Implementation-Version: 1.1.1_01
Extension-Installation: jai-1_1_1-01-windows-i586-jre.exe

Now JAR up the installer as jai_win.jar, together with the manifest file. You don't need to include the extension JAR files, as they are bundled with the .exe installer in this case. Be sure to include the .jar extension in the JAR file name.

Now sign jai_win.jar.

III. Create the applet JAR

1. Create a manifest file for the applet. Below is a manifest file for the jai example using a native installer:

Extension-List: jai_core
jai_core-Extension-Name: javax.media.jai
jai_core-Specification-Version: 1.1
jai_core-Implementation-Version: 1.1.1_01
jai_core-Implementation-Vendor-Id: com.sun
jai_core-Implementation-URL: http://myserver.com/jai_win.jar

Some optional packages come packaged in different JAR files for different operating systems. If you want your applet to work on different OSs, you can use the $(os-name)$ construction in the Implementation-URL manifest attribute. The $(os-name)$ will translate to the target OS that the applet is being run on—i.e., SunOS, Linux, Windows-98, Windows-NT, Windows-2000, Windows-Me.

optpkg-Implementation-URL: http://.../optpkg-$(os-name)$.jar

2. JAR up the *.class files, and any other supporting files the applet needs, together with the applet's manifest file, and sign the JAR. (The procedure for JARing your files and signing the JAR is the same as discussed previously.) Be sure to include the .jar extension in the JAR file name.

IV. Generate the HTML to launch the applet

Create the HTML page for the applet. You can do this manually or you can use the HtmlConverter that comes with the JDK. It is recommended that you use the HtmlConverter. But if you want to do it manually, see Using OBJECT, EMBED and APPLET Tags in Java Plug-in for information on how to do it. Note that the applet JAR file should go in the archive attribute.

Suppose your applet is called JaiApplet, the JAR file you created for it is called JaiApplet.jar, and the main class is JaiApplet.class.

Assume the original applet looks like this:

<html>
<head>
<title>JaiApplet</title>
</head>
<body>
<APPLET code="JaiApplet.class" archive="JaiApplet.jar" align="absmiddle" WIDTH="400"HEIGHT="300"> </APPLET>
</body>
</html>

Then if we use the HtmlConverter to convert it for dynamic versioning, we will have this:

<html>
<head>
<title>JaiApplet</title>
</head>
<body>
<!--"CONVERTED_APPLET"-->
<!-- HTML CONVERTER -->
<OBJECT
    classid = "clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
    codebase = "http://java.sun.com/update/1.6.0/jinstall-6-windows-i586.cab#Version=6,0,0,99"
    WIDTH = "400" HEIGHT = "300" ALIGN = "absmiddle" >
    <PARAM NAME = CODE VALUE = "JaiApplet.class" >
    <PARAM NAME = ARCHIVE VALUE = "JaiApplet.jar" >
    <PARAM NAME = "type" VALUE = "application/x-java-applet;version=1.6">
    <PARAM NAME = "scriptable" VALUE = "false">
    <COMMENT>
    <EMBED
            type = "application/x-java-applet;version=1.6"
            CODE = "JaiApplet.class"
            ARCHIVE = "JaiApplet.jar"
            WIDTH = "400"
            HEIGHT = "300"
            ALIGN = "absmiddle"
        scriptable = false
        pluginspage = "http://java.sun.com/products/plugin/index.html#download">
        <NOEMBED>
            </NOEMBED>
    </EMBED>
    </COMMENT>
</OBJECT>
<!--
<APPLET CODE = "JaiApplet.class" ARCHIVE = "JaiApplet.jar" WIDTH = "400" HEIGHT = "300" ALIGN = "absmiddle">
</APPLET>
-->
<!--"END_CONVERTED_APPLET"-->
</body>
</html>

When you run the applet, Java Plug-in will display a Java Security Warning if the extension is not already installed, informing you the applet requires installation of extension javax.media.jai from http://myserver.com/jai_win.jar. If you grant permission to install the extension, the installer will install the JAR files in the <jre>/lib/ext directory. Once the installation is complete your applet will run.

See Appendix 5: Complete Example—Deploying Java Media Framework as Java Extension for a complete, working example showing how to deploy the Java Media Framework as a Java Extension.

Known Limitations and Other Notes

  • If an Implementation-URL JAR file is not signed properly, Java Plug-in will fail silently.
  • For any extension be sure that a newer version of the extension contains at least the same set of JAR file names as the older version. Otherwise, installing a newer extensions may not overwrite all the older extensions JARs, and there will be a mix of different versions of an extension in <jre>/lib/ext. The results will be unpredictable.
  • If Java Installer is used, make sure the program does not exit the Main-class until the installation is done. In some cases, Java Installer may create an AWT window and switch control to a different thread and return immediately from the Main-class. Returning control from the Main-class will force the applets to be loaded and started immediately, even if the Java Installer is still in the process of installation. This will cause the applet to fail to load because the extension is not installed yet.


How RSA Signed Applet Verification Works in Java Plug-in

Verification of RSA Signed Applets in Java Plug-in

This section covers the following topics:

  • Introduction
  • Support for RSA Verification
  • Support for Dynamic Trust Management
  • usePolicy Permission

Introduction

This page provides an overview of how verification of RSA signed applets is implemented in Java Plug-in. For an overview of how to use RSA signed applets, see How to Deploy RSA-Signed Applets in Java Plug-in.

Support for RSA Verification

To enable verification of RSA signatures in a browser-independent way, Java Plug-in includes a Cryptographic Service Provider (CSP). The CSP supports the "MD2withRSA", "MD5withRSA", and "SHA1withRSA" digital signature algorithms. It is automatically registered with the Java Cryptographic Architecture framework as part of the static initializer of the PluginClassLoader.

Support for Dynamic Trust Management

Java SE has a fine-grained access control based on "codesource" and "protection domain". Every class that is loaded from a JAR file has a codesource, which encapsulates two pieces of information:

  • The location (URL) where the class came from. In addition, every class that is loaded by a classloader belongs to one and only one protection domain, based on its codesource (i.e., based on where the class came from and who signed it). Every protection domain has a set of permissions associated with it, based on the configured security policy. The protection domain encapsulates the codesource and the set of permissions granted to it
  • The list of principals who signed it (its certificates). Each signer principal in the codesource is represented by its X.509 public-key certificate and supporting certificate chain.

A certificate chain is a list of hierarchically ordered public-key certificates, starting at the signer's public-key certificate and ending at the certificate of a Root Certification Authority ("Root CA"). The public key of one certificate in the chain is used to verify the signature on the previous certificate in the chain. The Root CA certificate is self-signed. The assumption is that the Root CA is trusted because it is well known and widely published.

The PluginClassLoader checks the configured security policy to determine which permissions to grant to a given codesource. The codesource and the set of permissions granted to it then form a protection domain. This behavior is common to all secure classloaders (i.e., instances of java.security.SecureClassLoader).

The sun.plugin.security.PluginClassLoader extends sun.applet.AppletClassLoader, which is a subclass of java.net.URLClassLoader, which in turn extends java.security.SecureClassLoader. The PluginClassLoader does additional work: If the applet is signed, and the permissions granted to it do not include the special usePolicy permission, the PluginClassLoader extracts the signers (and their supporting certificate chains) from the applet's codesource and attempts to verify them.

If Plug-in can verify the certificate chain all the way up to its Root CA certificate, it checks if that Root CA certificate is contained in the database of trusted Root CA certificates. If so, Plug-in will display the certificate chain of the authenticated signer and ask the user whether or not to grant AllPermission to code signed by that principal. Java code that is assigned the AllPermission permission is treated the same as system code, meaning it has all the privileges that system code has. The user can then choose whether or not to grant AllPermission to code signed by that principal, and whether such permission should be granted to any code signed by that principal for all subsequent sessions or for the current session only.

For the case of unsigned applets, or signed applets whose permissions include the usePolicy, see Overview—Applet Security Basics.

usePolicy Permission

A permission named usePolicy allows system administrators to turn off the PluginClassLoader behavior. If the usePolicy permission is granted to the codesource by the configured security policy, no user prompting will take place. Only the permissions specified in the security policy will be granted to the codesource.


How to Deploy RSA-Signed Applets in Java Plug-in

Deploying RSA-Signed Applets in Java Plug-in

This section covers the following topics:

  • How to deploy RSA Signed Applets
  • Certificate Management
  • Disabling RSA signed applet support

How to Deploy RSA Signed Applets

To deploy RSA signed applets:

  1. Reference the JAR from the HTML page using archive, cache_archive, or cache_archive_ex format. See Applet Caching.
  2. Place the JAR file and HTML page on the web server.

When users of Java Plug-in encounter an RSA signed applet, the Plug-in will verify whether:

  1. The applet is correctly signed
  2. The RSA certificate chain and root CA are valid

If the applet is correctly signed and the RSA certificate chain and root CA are valid, the Plug-in will pop-up a security dialog telling the user and providing four options:

  1. Grant always: If selected, the applet will be granted the AllPermission permission. Any applet signed with the same certificate will be trusted automatically in the future, and no security dialog will pop up when the certificate is encountered again. This option selection can be changed from the Java Control Panel.
  2. Grant this session: If selected, the applet will be granted the AllPermission permission. Any applet signed with the same certificate will be trusted automatically within the same browser session.
  3. Deny: If selected, the applet will be treated as untrusted.
  4. View Issuer: If selected, the user can examine the attributes of each certificate in the certificate chain in the JAR file.

Once the user selects the options from the security dialog, the applet will be run in the corresponding security context. Note that all options are selected on the fly; no preconfiguration is required.

Certificate Management

The Java Control Panel provides a Certificates Panel for managing RSA signed applets. This panel contains a list of certificates that received "Grant always" permission when the Java Plug-in security dialog (pop-up) ran. Users can remove any certificate from the list, and if an applet signed by a removed certificates is encountered again, a security dialog pop-up will appear asking for permission. Users can also export and view certificates through the Java Control Panel.

Disabling RSA Signed Applet Support

RSA signed applets can be entirely disabled in Java Plug-in by specifying the usePolicy permission in the policy file. If the usePolicy permission is among the permissions granted to the given codesource (by the configured security policy), user prompting will not take place, and only permissions specified in the security policy will be granted to the codesource. By default, RSA signed applets are enabled in the Java Plug-in.


HTML Converter

Using the HTML Converter to Convert Applet Tags for Java Plug-in

The Java Plug-in HTML Converter is a utility for converting an HTML page (file) containing applets to a format for Java Plug-in. The conversion process is as follows:

First, HTML that is not part of an applet is transferred from the source file to a temporary file. Then, when an <APPLET> tag is reached, the converter parses the applet to the first </APPLET> tag (not contained in quotes) and merges the applet data with the template. (See Details about templates in the section called More About HTML Converter for more information.) If this completes without error, the original HTML file is moved to the backup folder and the temporary file is then renamed as the original file's name.

The converter effectively converts the files in place. Thus, once the converter runs, files are setup for Java Plug-in.

For detailed information about installing and using the HTML Converter, see More About HTML Converter.


Installation for Conventional Applets

Installation for Conventional Applets (Microsoft Window Only)

This section covers the following topics:

  • Enabling APPLET Tag Support
  • Silent Installation Options

Enabling APPLET Tag Support

Developers should be aware that end users of Java Plug-in can choose to enable or disable APPLET tag support during installation or at any time after installation.

As part of the installation process, the user will see the following panel:

Sample Select Browser window

This panel allows the user to select JRE/Java Plug-in to be the default runtime environment for handling APPLET tags in Microsoft Internet Explorer browsers and/or Mozilla family browsers. The installer will use the Windows registry to determine whether the user's machine has these browsers installed and will check by default the box corresponding to any installed browser(s).

The user can enable or disable APPLET tag support after installation through the Browser panel of the Java Plug-in Control Panel.

On Microsoft Internet Explorer, users also can use the Advanced tab in the Internet Options window to enable/disable Java Plug-in's APPLET tag support. (Tools>Internet Options > Advanced tab.)

sample Advanced tab

Silent Installation Options

Java Plug-in supports silent installation as an alternative to the standard installation wizard. Silent installation might be used, for example, for large-scale deployment. For general information on silent installation of Java Plug-in, see Silent Installation.

Unlike the installation using the wizard, silent installation will not enable APPLET tag support by default for any browsers on the end user's machine. To enable APPLET tag support during silent installation, you must use one or both of the following command-line options:

IEXPLORER=1
If this flag is passed to the installer, APPLET tag support will be enabled for Microsoft Internet Explorer browsers.
MOZILLA=1

If this flag is passed to the installer, APPLET tag support will be enabled for Mozilla family browsers.


Internet

Internet Deployment

Deploying Java Plug-in with Internet Explorer

With Internet Explorer it is recommended that you use the APPLET tag for internet deployment. However, you could use the OBJECT tag in certain cases; e.g., if you want users to use a particular version of Java Plug-in. In the case that the you chose to use the OBJECT tag, the following is recommended.

Recommendations

The following is recommeded for long-term reliability:

  • For the codebase attribute in the OBJECT tag, it is recommended that you use the .exe version, rather than the .cab version, on java.sun.com. That .cab version on java.sun.com may point to an updated version that you do not want to use for your deployment.
  • It is also recommend that you create your own download site for the versions you need so that you do not rely on java.sun.com. Downloads on java.sun.com frequently change.

These are the same recommendations as for the intranet environment.

Deploying Java Plug-in with Mozilla

With supported Mozilla browsers it is recommended that you use the APPLET tag for internet deployment.


Intranet

Intranet With OBJECT/EMBED Tag

This section includes the following topics:

  • Introduction
  • Deploying Java Plug-in with Internet Explorer
  • Deploying Java Plug-in with Mozilla Browsers

Introduction

The intranet is a more controlled environment than the internet, and you can decide whether you want to deploy your applets via the APPLET, OBJECT, or EMBED tags. This chapter deals with deployment using the OBJECT or EMBED tags.

Java Plug-in can be deployed in an intranet environment so that users can download and install it without leaving the firewall. Deployment details for Internet Explorer and supported Mozilla browsers are described below.

Note

You need to understand the Java Plug-in tagging structure to understand the discussion below. The tagging structure is explained in Using OBJECT, EMBED and APPLET Tags in Java Plug-in.)

Deploying Java Plug-in with Internet Explorer (IE)

To deploy Java Plug-in in intranet environments with IE, you need to download and store the Java Plug-in binary file on a web server. Then you need to modify the codebase attribute inside the <OBJECT> tag in the HTML file to point to the binary. For example, if you want to use the Java Plug-in binary file in http://my_company.com/plugin/, then you should specify the codebase attribute as

"http://my_company.com/plugin/jre-6-rc-windows-i586.exe#Version=6,0,0,99"

(For Internet deployment the above might use a .cab file rather than .exe. The .cab file points to an .exe and provides a download progress bar.)

Note the version number in the above URL. For Java Plug-in 6, the version number is 6,0,0,99. This version number changes for each release, and you must change the version number inside the <OBJECT> tag if you want to specify the newest release of Java Plug-in.

The filejre-6-rc-windows-i586.exe#Version=6,0,0,99 is the same binary that can be download directly from the Java Software web site. It is digitally signed with a VeriSign digital signature signed by Sun Microsystems, Inc. If you are using the Java Plug-in HTML Converter, you can simply change the conversion template file to specify the latest Plug-in version (the CabFileLocation variable) before the conversion. For information about modifying the conversion template, consult the README file in the Java Plug-in HTML Converter. Note that CabFileLocation can be the location of the .cab file or the .exe.

Once you have implemented these changes, when a machine that does not have Java Plug-in installed browses an HTML page with IE, IE will look into your predefined location (http://my_company.com/plugin in the example) and download Java Plug-in. Notice that there is no need to download Java Plug-in over the firewall if the web server is inside the intranet.

Note: Recommendations

The following is recommeded for long-term reliability:

  • For the codebase attribute in the OBJECT tag, it is recommended that you use the .exe version, rather than the .cab version, on java.sun.com. That .cab version on java.sun.com may point to an updated version that you do not want to use for your deployment.
  • It is also recommend that you create your own download site for the versions you need so that you do not rely on java.sun.com. Downloads on java.sun.com frequently change.

Deploying Java Plug-in with Mozilla Browsers

For supported Mozilla browsers you must use the APPLET tag.

To deploy Java Plug-in in intranet environments with Mozilla, you need to download and store the Java Plug-in binary file on one of your web servers. Then you need to set up a Java Plug-in Download page and modify the pluginspage attribute in the EMBED tag to refer to this page. For example, if you have set up the Java Plug-in Download page at "http://my_company.com/plugin/" and the page is called plugin-install.html, you can specify the pluginspage as "http://my_company.com/plugin/plugin-install.html". The Download page should have options to download different versions of Java Plug-in, such as for Windows and Solaris.

When a machine that does not have Java Plug-in installed acceses a web page, a missing-plugin icon is displayed on the HTML page. When the user clicks on this icon, Mozilla browser directs the user to your predefined Java Plug-in Download Page (http://my_company.com/plugin/plugin-install.html in this example). Notice that there is no need to download Java Plug-in over the firewall if the web server is inside the intranet.

Deploying Java Plug-in with Unix/Linux with Mozilla

There are two ways that Java Plug-in might be installed in the Intranet environment with Unix or Linux:

  • It might be installed on a per-user-account basis on individual machines, as it is installed in the Window environment.
  • It might be installed by a system administrator on a shared NSF drive for shared installation.

In either case, for supported Mozilla browsers the environmental variable NPX_PLUGIN_PATH must be set to point to the Java Plug-in. When Java Plug-in is installed on the local machine, then the user needs to set this variable to point to the Java Plug-in in the JRE on the local machine. For a shared installation, the system administrator needs to determine the shared location of the Java Plug-in in the shared JRE on the NSF drive and set the user profile for every machine to point to this via NPX_PLUGIN_PATH.


Jar Indexing

In the case that an applet uses multiple .jar files, more efficient downloading can be achieved by indexing the .jar files. By indexing, only required .jar files are downloaded. For more information on Jar Indexing, see Java Archive (JAR) Features.


Java Console

See Java Console in the Java Deployment Guide.


Java Control Panel

Using the Java Control Panel to Set Plug-in Options

See Java Control Panel in the Java Deployment Guide.


Java Debugger Support

Debugging Support

This section covers the following topics:

  • How to Debug Applets in Java Plug-in
  • Java Console
  • Java Plug-in Trace File
  • javaplugin.trace property
  • java.security.debug property
  • Documentation
  • Isolating Bugs
  • Submitting Bug Reports
  • Submitting Feature Requests
  • Java Plug-in Feedback Alias

The purpose of this document is to simplify the debugging of applets. It provides techniques and suggestions for developing applets in Java Plug-in and describes some common errors encountered in applet development.

How to Debug Applets in Java Plug-in

Applets should be debugged using the java debugger utility jdb. Also make sure to compile your .java files with -g option with javac. To begin debugging your applet:

  1. Open Java Control Panel. Click Java > View. Specify the following parameters in the Java Runtime Parameters with each parameter separated by a comma as follows:
    -agentlib:jdwp=transport=dt_shmem,address=jdbconn,server=y,suspend=n

    See JPDA Connection and Invocation for the details on the possible runtime parameters for debugging.

  2. Start Internet Explorer or Mozilla browser and load the page which contains the applet to be debugged. Make sure the applet code has been compiled with -g option of javac.
  3. Run the command jdb -attach <address> in a DOS command prompt. <address> is the name mentioned in the step. For example, if <address> is jdbconn, you will run the command as
              jdb -attach jdbconn
    To learn more about the Java Debugger (jdb), see The Java Debugger.
  4. Once the jdb is attached to the VM, you can set up breakpoints in the applet.
  5. When the applet in the browser reaches the breakpoint, it will stop executing, and you will see the debugger waiting for your input to continue debugging.

When debugging applets in Java Plug-in, make sure that only one instance of the browser is being used for debugging using the same connection address at the same time. Otherwise, it will result in a conflict, since the Java Runtime for each instance of the browser will try to gain exclusive access to the connection address. To debug applets in both Internet Explorer and supported Mozilla browsers, run either Internet Explorer or supported Mozilla browsers with Java Plug-in—but not both at the same time.

Debugging applets in Java Plug-in with Active Desktop is discouraged because an instance of Internet Explorer will always be running in the desktop process during the lifetime of the user session.

You can use other debuggers from IDEs like Borlands JBuilder or Symantec's VisualCafe, instead of jdb. To use these debuggers, you will need to change the project option in these IDEs to attach Java Plug-in in the browser process on the same machine or remote machine. Different Java Runtime Parameters may also be required in the Java Control Panel. For more information, refer Java debugger or IDE manuals.

Java Console

Java Console is a simple console window for redirecting all the System.out and System.err messages. The console window is disabled by default. It can be enabled from the Java Control Panel or the task bar. If the console is enabled, you will see the console window appear when Java Plug-in is used in the browser. For more information on Java Console see Java Console documentation.

For information on Java Console see the Java Console section of the Deployment Guide.

Java Plug-in Trace File

The Java Plug-in trace file records all the debug, System.out, and System.err messages. The trace file is disabled by default but is automatically enabled when the Java Console is enabled. The trace file is located by default at C:\Documents and Settings\<username>\Application Data\Sun\Java\Deployment\log in the user.dir. The trace file has the naming convention .plugin<version>.trace where <version> indicates the version of Java installed on the system.

The user.dir directory contains various log and trace files. In Windows 2000 and Windows XP this file is located at the following location:
C:\Documents and Settings\<username>\Application Data\Sun\Java\Deployment.

The Application Data folder and its contents are hidden by default in Windows.

javaplugin.trace property

This property controls whether Java Plug-in prints its trace messages during execution. This is useful to applet developers to determine what is occuring within Java Plug-in. To enable tracing follow the steps given below:

  • Open Java Control Panel
  • Click Advanced > Debugging
  • Select Enable Tracing checkbox .

java.security.debug property

This property controls whether the security system of the Java Runtime Environment prints its trace messages during execution. This is usful when a security exception is thrown in an applet or when a signed applet is not working. The following options are supported:

  • access — print all checkPermission results
  • jar — print jar verification information
  • policy — print policy information
  • scl — print permissions SecureClassLoader assigns

The following options can be used with access:

  • stack — include stack trace
  • domain — dumps all domains in context
  • failure — before throwing exception, dump the stack and domain that didn't have permission

For example, to print all checkPermission results and dump all domains in context, perform the following actions:

  • Open Java Control Panel
  • Click Java > View. The Java Runtime Settings dialog box is displayed.
  • Type -Djava.security.debug=access:stack in the Java Runtime Parameters field.

Documentation

Java Plug-in provides a rich set of documentation to help developers use the various features of Java Plug-in. The documentation includes a FAQ, which includes some of the most frequently asked questions by developers. Make sure you read and understand these documents before applet development, as it may save you hundreds of hours in debugging.

Isolating Bugs

Although Java Plug-in provides the Java 2 Runtime Environment within Internet Explorer and supported Mozilla browsers, most of the facilities are provided by the Java 2 Runtime itself, rather than by Java Plug-in. Therefore, if a problem occurs in Java Plug-in, it may be either a problem in Java Plug-in, the Java 2 Runtime itself or a user error. It is extremely important to determine where bugs originate, as it will affect the speed of bug evaluation and fixing. Here are some suggestions for isolating bugs:

  1. Run the applets in both Internet Explorer and supported Mozilla browsers through Java Plug-in.
  2. Run the applets in appletviewer. Java Plug-in is mainly derived from appletviewer and has inherited problems from appletviewer as well. This step should be performed only if the applet doesn't require specific browser facilities that Java Plug-in provides, like HTTPS or RSA signing.
  3. If the applet fails in appletviewer, it is likely the problem is in the Java 2 Runtime Environment—and not in Java Plug-in.
  4. If the applet fails in only one of the browsers, IE or supported Mozilla browsers, it is likely a Java Plug-in problem.
  5. If the applet fails in both browsers but not appletviewer, it could be either a Java Plug-in problem or user error. Please examine the applet code to see if it makes any assumptions about the execution environment. For example, in appletviewer the current directory is set to the current directory in the shell when appletviewer is launched, whereas the current directory in Java Plug-in may be set to the browser's directory. Therefore, loading resources from the current directory may work in appletviewer but not in Java Plug-in.
  6. Try to reproduce the problem on other machines or platforms. In some cases, the root of the problem may be in the machine configuration, e.g., an improper DNS setup.
  7. If you have identified the problems in the Java 2 Runtime Environment or Java Plug-in, please follow the instructions in the next section to submit a bug report to the appropriate product categories.

Submitting Bug Reports

To submit a bug report, go to the Java Development Connection's Bug Database . Before submitting a bug, search the BugParade to determine if the bug has already been reported. In some cases, a workaround may also have been suggested. If the bug is not already reported, submit a new bug report to the Java Plug-in team. In the bug report, include the following information:

  • Complete description of the problem and step-by-step instructions for reproducing it;
  • Error messages captured by Java Console or trace file;
  • Proxy configuration information, e.g., auto proxy configuration with proxy configuration file attached;
  • Browser and platform information, e.g., supported Mozilla browsers on Win 2000;
  • A test case demonstrating the problem;
  • Specify whether the problem occurs in other browsers and appletviewer;
  • Specify any workaround available;
  • Specify personal information—your name and email address—so you may be contacted if additional information is required.

Submitting Feature Requests

To submit a feature request, do so through the Report A Bug or Request a Feature page.In the feature request, please make sure the following information is included:

  • Complete description of the requested feature;
  • How this feature will improve the quality of your product or Java Plug-in in general.

Java Plug-in Feedback Alias

The purpose of the Java Plug-in Feedback alias, java-plugin-feedback@sun.com, is for customers to provide feedback on product features and the product in general. This alias is not intended for bug report submission. To submit a bug report, please follow the instructions given above.


Java Media Framework as Java Extension

Appendix 3: Complete Example—Deploying Java Media Framework as Java Extension

This section covers the following topics:

  • Introduction
  • Creating the jar File to Be Installed
  • Creating the Applet jar File
  • Creating the HTML for the Applet
  • Testing the Example

Introduction

This is a complete, working example showing how to deploy a single jar file from Java Media Framework (JMF) as a Java Extension. The example uses SimplePlayerApplet.java and jmf.jar to play an .avi media file. It uses the raw installation method for installating a repackaged and signed version of jmf.jar called s_my_jmf.jar. Normally there are other jar files that are installed with JMF, but for SimplePlayerApplet.java only the functionality in jmf.jar is required.

For simplicity sake, this example makes the following assumptions:

  • You are working on a Microsoft Windows system.
  • You have intalled the 1.6 JDK in the following location on your computer: C:\"Program Files"\Java\jdk1.6.0
  • For signing purposes you have set up a keystore in the following directory: C:\plugin\keystores
  • The keystore name is thawte.p12
  • The storepass and the keypass are the same: mypass
  • The keystore alias is "Sun Microsystems Inc.'s Thawte Consulting cc ID"

Creating the jar File to Be Installed

In this case there is no installer. All you need to do is obtain the required jar file, jmf.jar, that needs to be downloaded and copied into <jre_location>/lib/ext. Plug-in, in conjunction with the extension mechanism in the JRE, handles the installation (downloading and copying of the file) for you.

You can get jmf.jar by downloading the cross-platform installation zip file jmf-2_1_1e-alljava.zip from http://java.sun.com/products/java-media/jmf/2.1.1/download.html. Along with other jar files, the zip file contains jmf.jar, which you can extract from the zip.

Once you have obtained jmf.jar, you will want to extract jmf.jar itself into some directory, say C:\plugin\extensions\workspace1. Here you will want to delete the META-INF directory if it exists, as the manifest.mf file contains signing information that you do not want.

Next you need to create your own manifest file for the new jar file to be based on jmf.jar. The manifest file that we create we call jmf_manifest. It will be provided as input to the jar tool. Here is what is used in this example:

Extension-Name: javax.media.s_my_jmf
Specification-Vendor: Sun Microsystems, Inc
Specification-Version: 2.1
Implementation-Vendor-Id: com.sun
Implementation-Vendor: Sun Microsystems, Inc
Implementation-Version: 2.1.1

First we will jar the files in jmf.jar and rename the result my_jmf.jar. Then we will sign the result and call it s_my_jmf.jar.

In order to jar the files in workspace1 with our new manifest file jmf_manifest, we cd to the location of workspace1, then we use the jar tool in the JDK as follows:

C:\plugin\extensions\workspace1>C:\"Program Files"\Java\jdk1.6.0\bin\jar cmf jmf_manifest my_jmf.jar *.class codecLib com javax jmapps

Note that codecLib, com, javax, and jmapps are subdirectories that must be jar'd as well as *.class.

If you have a Thawte keystore called thawte.p12 located in C:\plugin\keystores with the same password, mypass, for both storepass and keypass, and storetype "pkcs12" and keystore alias "Sun Microsystems Inc.'s Thawte Consulting cc ID", then you can skip the next step and proceed to signing of my_jmf.jar and creating a signed jar file called s_my_jmf.jar.

You can create a keystore called thawte.p12 with the same password, mypass, for both storepass and keypass and keystore alias "Sun Microsystems Inc.'s Thawte Consulting cc ID" by running the following command:

C:\plugin\keystores>C:\"Program Files"\Java\jdk1.6.0\bin\keytool -genkey -alias "Sun Microsystems Inc.'s Thawte Consulting cc ID" -keypass mypass -keystore thawte.p12 -storetype pkcs12 -storepass mypass

In this example we use the jarsigner tool to sign the new jar file. Use

C:\plugin\extensions\workspace1>C:\"Program Files"\Java\jdk1.6.0\bin\jarsigner -keystore C:\plugin\keystores\thawte.p12 -storepass mypass -keypass mypass -storetype "pkcs12" -signedjar s_my_jmf.jar my_jmf.jar "Sun Microsystems Inc.'s Thawte Consulting cc ID"

We can verify the new signed jar file as follows:

C:\plugin\extensions\workspace1>C:\"Program Files"\Java\jdk1.6.0\bin\jarsigner -verify s_my_jmf.jar

We now have a signed jar file with the proper manifest.mf file for raw installation.

Next we need to create the applet jar file.

Creating the Applet jar file

The applet consists of a single file, SimplePlayerApplet.class, that can be used to playback a media file. The source code for the applet can be viewed here. What we need to do is create a manifest file called for the the applet, which we will call applet_manifest, jar the applet with the manifest, then sign the result..

The applet applet_manifest is as follows:

Extension-List: s_my_jmf
s_my_jmf-Extension-Name: javax.media.s_my_jmf
s_my_jmf-Specification-Version: 2.1
s_my_jmf-Implementation-Version: 2.1.1
s_my_jmf-Implementation-Vendor-Id: com.sun
s_my_jmf-Implementation-URL: http://java.sun.com/products/plugin/extensions/examples/jmf/s_my_jmf.jar

Note that the above manifest says that the extension jar, s_my_jmf.jar, can be downloaded from the java.sun.com web server at http://java.sun.com/products/plugin/extensions/examples/jmf

If the SimplePlayerApplet.class and applet_manifest are located in C:\plugin\extensions\workspace2, we can jar the applet with the manifest with the following command:

C:\plugin\extensions\workspace2>C:\"Program Files"\Java\jdk1.6.0\bin\jar cmf applet_manifest my_SimplePlayerApplet.jar *.class

Again, we use jarsigner to sign the jar file:

C:\plugin\extensions\workspace2>C:\"Program Files"\Java\jdk1.6.0\bin\jarsigner -keystore C:\plugin\keystores\thawte.p12 -storepass mypass -keypass mypass -storetype "pkcs12" -signedjar s_my_SimplePlayerApplet.jar my_SimplePlayerApplet.jar "Sun Microsystems Inc.'s Thawte Consulting cc ID"

and we verify it as follows:

C:\plugin\extensions\workspace2>C:\"Program Files"\Java\jdk1.6.0\bin\jarsigner -verify s_my_SimplePlayerApplet.jar

We now have our signed applet jar file called s_my_SimplePlayerApplet.jar, whose manifest contains the correct information to trigger the installation of the required extension jar file, s_my_jmf.jar if no such file or an older version is found in <jre_location>/lib/ext.

Next we need to create the HTML for the applet.

Creating the HTML for the Applet

We have several choices. We can use the conventional APPLET tag and assume those who visit the page have Java Plug-in version 1.3.1_01 or later installed on their systems. (To use Java Plug-in to launch an applet with the conventional applet tag requires 1.3.1_01 or later.) We can also use the HTML Converter, located in the JDK in the bin directory (<sdk_location>/bin/HtmlConverter.exe) to convert the applet to various forms. Here we use the conventional applet form shown below:

SimplePlayerApplet-1.html

<html>
<head>
<title>SimplePlayerApplet</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<applet code="SimplePlayerApplet.class" archive="s_my_SimplePlayerApplet.jar" width=320 height=300>
<param name="file" value="0720crt1.avi">
</applet>
</body>
</html>

Note that the media file is 0720crt1.avi.

For this example the following files have been placed on the java.sun.com web server at http://java.sun.com/products/plugin/extensions/examples/jmf:

  • 0720crt1.avi
  • s_my_jmf.jar
  • s_mySiplePlayerApplet.jar
  • SimplePlayerApplet-1.html

Testing the Example

You can test the setup by pushing the button below:

When you point your browser at the URL, the applet jar will first be downloaded and cached; and, if the extension has not already been installed, you will see a Java Request Download dialog that says: 'The applet requires installation of optional package. Do you want to continue?'. You will have the options to continue or cancel. If you continue installation by pressing OK button, you will see the Security Warning dialog for the extension jar file. You can proceed with package installation by pressing Run button. The extension will be installed in <jre_location>/lib/ext and the applet will run.


Java Plug-in 6 Developer Guide Home

Java Plug-in Developer Guide for Java SE 6


Java Plug-in 6.0 Developer Guide Contents

Java Plugin Guide

Note: There are two ways to navigate this guide:

  • Search the guide
  • Select from the contents below:
 Related Documents

Part I: Java Plug-in Basics
Overview—What Is Java Plug-in? What Does It Support?
Using OBJECT, EMBED and APPLET Tags in Java Plug-in
Proxy Configuration
Protocol Support: HTTP, HTTPS, FTP, GOPHER, SOCKS, and NTLM
Cookie Support
Applet Caching
Using the Java Control Panel to Set Plug-in Behavior/Options
Part II: Deployment Schemes
Installation for Conventional Applets (Microsoft Windows Only)
Intranet With OBJECT/EMBED Tag
Internet Deployment
Silent Installation
Jar Indexing
Java Server Pages
Part III: Security
Overview—Applet Security Basics
Verification of RSA Signed Applets in Java Plug-in
Signing Applets Using RSA Certificates
Deploying RSA-Signed Applets in Java Plug-in
Part IV: Debugging Support
Debugging Support
Java Plug-in Console
Tracing and Logging
Part V: Advanced Topics
Supporting Multiple Versions of JRE/Java Plug-in
 Java-to-JavaScript Communication
JavaScript-to-Java Communication (Scripting)
Deploying Java Extensions
Applet Persistence API
Special Applet Attributes
Appendices
Appendix 1: Frequently Asked Questions (FAQ)
  • Basic Information FAQ
  • Developer Information FAQ
  • Troubleshooting FAQ
  • About Applet Tag Support in Java Plug-in
Appendix 2: Microsoft VM and Java Applet Compatibility Issues
Appendix 3: Complete Example—Deploying Java Media Framework as Java Extension
Appendix 4: Sun-Supported Specification-Version and Implemenation-Version Formats


Java-to-Javascript Communication

This section includes the following topics:

  • Introduction
  • JSObject
    • How JSObject Works
    • Enabling JSObject support in Java Plug-in
  • Common DOM API

Introduction

Java Plug-in offers two ways to access the DOM: Through JSObject and through the Common DOM API. Each method is described below, along with security considerations.

JSObject

Java applets may need to perform Java-to-JavaScript communication to access the Document Object Model (DOM) or to call JavaScript functions on an HTML page. Browsers allow communication between Java and JavaScript through the Java wrapper class netscape.javascript.JSObject. For more information, see Java Packages for LiveConnect.

Because the JavaScript rendering engine is implemented differently between browsers, Java Plug-in provides different degrees of support for JSObject in Internet Explorer and Navigator. This document specifies how JSObject support works in different browser environments.

How JSObject Works

JSObject provides an easy way to access the DOM of an HTML page. But because different browsers implement the DOM differently, using JSObject in a Java applet may yield different behaviors in Java Plug-in. For details about the DOM implementation in a particular browser, consult the developer guide for that browser.

In general, applets access JSObject as follows:

import netscape.javascript.*;
import java.applet.*;
import java.awt.*;
class MyApplet extends Applet {
     public void init() {
         JSObject win = JSObject.getWindow(this);
         JSObject doc = (JSObject) win.getMember("document");
         JSObject loc = (JSObject) doc.getMember("location");

         String s = (String) loc.getMember("href");  // document.location.href
         win.call("f", null);                      // Call f() in HTML page
     }
}

The starting point is the static method

public static JSObject getWindow(Applet a)

which returns a JSObject representing the Window that contains the given applet. Since this method takes only java.applet.Applet as parameter, JSObject can be accessed from an applet, but not from a bean unless the bean is also an applet.

Once the Window object is obtained, the applet can navigate the DOM of the HTML page using the following methods:

  • public Object call(String methodName, Object args[])
  • public Object eval(String s)
  • public Object getMember(String name)
  • public Object getSlot(int index)
  • public void removeMember(String name)
  • public void setMember(String name, Object value)
  • public void setSlot(int index, Object value)
  • public String toString()
  • public boolean equals(Object obj)

We recommend using only getWindow(), call(), eval(), setMember() and getMember() in Java Plug-in. The implementations of getSlot(), setSlot(), removeMember() and toString() are browser-dependent; i.e., the result of execution may vary depending on the version and platform of the browser in which Java Plug-in is running.

For more information about using JSObject, please read the section called "Java to JavaScript Communication" on the LiveConnect page.

To compile Java code to take advantage of JSObject, you must have the package netscape.javascript in the CLASSPATH. Since 1.4.2 Java Plug-In ships netscape.javascript in a JAR file called plugin.jar. To compile an applet which uses JSObject, add plugin.jar in the CLASSPATH before compilation.

Note that although JSObject is supported in Java Plug-in, it is not supported in AppletViewer in the Java SE platform. As a result, applets using JSObject may not run in AppletViewer or result in exceptions.

Enabling JSObject Support in Java Plug-in

Due to security reasons, JSObject support is not enabled in Java Plug-in by default. To enable JSObject support in Java Plug-in, a new attribute called MAYSCRIPT needs to be present in the EMBED/OBJECT tag as follows:

Original APPLET tag:

<APPLET code="XYZApp.class" codebase="html/" align="baseline"
     width="200" height="200" MAYSCRIPT>
<PARAM NAME="model" VALUE="models/HyaluronicAcid.xyz">
     No JDK 1.3 support for APPLET!!
</APPLET>

New OBJECT tag:

<OBJECT classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
     width="200" height="200" align="baseline"
     codebase="http://java.sun.com/products/plugin/1.3/jinstall-13-win32.cab#Version=1,3,0,0">
     <PARAM NAME="code" VALUE="XYZApp.class">
     <PARAM NAME="codebase" VALUE="html/">
     <PARAM NAME="type" VALUE="application/x-java-applet;version=1.3">
     <PARAM NAME="MAYSCRIPT" VALUE="true">
     <PARAM NAME="model" VALUE="models/HyaluronicAcid.xyz">
        No JDK 1.3 support for APPLET!!
</OBJECT>

New EMBED tag:

<EMBED type="application/x-java-applet;version=1.3" width="200"
   height="200" align="baseline" code="XYZApp.class"
   codebase="html/" model="models/HyaluronicAcid.xyz" MAYSCRIPT=true
   pluginspage="http://java.sun.com/products/plugin/1.3/plugin-install.html">
<NOEMBED>
   No JDK 1.3 support for APPLET!!
</NOEMBED>
</EMBED>

If MAYSCRIPT is specified as false, or if MAYSCRIPT is absent, JSObject is disabled. For more information about the MAYSCRIPT attribute in the EMBED/OBJECT tag, see Using OBJECT, EMBED and APPLET Tags in Java Plug-in.

JavaScript and LiveConnect are technologies from Netscape Communications Corporation. Due to the differences in the Javascript engine implemented by Mozilla and Microsoft, data marshalling between Java and JavaScript via LiveConnect may result in different datatypes for different browsers. The main differences in JavaScript implementations from vendors are in JavaScript datatype support, mapping of datatypes between Java and JavaScript, and DOM element implementation.

Note

The original JavaScript specification is available at http://devedge-temp.mozilla.org/library/manuals/2000/javascript/1.3/guide/index.html.

The original LiveConnect specification is available at http://devedge-temp.mozilla.org/library/manuals/2000/javascript/1.3/guide/lc.html#1037078.

Common DOM API

Overview

This section discusses the Common DOM API in Java Plug-in 6. It provides a standard API for accessing the DOM in the browser for browsers from different browser vendors running on various platforms.

Note

Full support is provided with Internet Explorer 6 and supported Mozilla browsers. Support is limited with other browsers.

This API is built upon the Document Object Model (DOM) Level 2 recommendation. (See http://www.w3.org/DOM/ for various w3c recommendations.) The Document Object Model (DOM) is a set of interfaces defined using Interface Definition Language (IDL) and including Java Language bindings.

The Common DOM API includes the following w3c-defined interface packages:

  • org.w3c.dom.*
  • org.w3c.dom.css.*
  • org.w3c.dom.events.*
  • org.w3c.dom.html.*
  • org.w3c.dom.stylesheets.*
  • org.w3c.dom.views.*

DOMService

The Common DOM classes allow an application to access the underlying DOM of the browser through the APIs in the org.w3c.dom and org.w3c.dom.html packages.

Each DOM represents the underlying representation of a single XML/HTML document within the browser, and each browser may display more than one XML/HTML document in multiple browser frames/windows. Thus, when an application requests to access the DOM through the Common DOM classes, it is important to return the DOM associated with the application. In order to obtain the proper DOM associated with the application, a Java object will be passed to DOMService.getService(). DOMService will return the proper DOMService implementations associated with the object, or an exception will be thrown. Ordinarily the Java object is an applet or JavaBeans component. However, this specification doesn't preclude other Java object types from being used, if the DOMServiceProvider can handle it.

To perform an action on the DOM, an object that implements DOMAction will need to be passed to DOMService.invokeAndWait() or DOMService.invokeLater(). DOMAction.run() will then be executed on the DOM access dispatch thread.

Here is a simple example of obtaining the title of the Document object:

DOMService service = null;

try
{
    service = DOMService.getService(MyApplet);
    String title = (String) service.invokeAndWait(new DOMAction()
                            {
                                public Object run(DOMAccessor accessor)
                                {
                                     HTMLDocument doc = (HTMLDocument) accessor.getDocument(MyApplet);
                                     return doc.getTitle();
                                }
                            });
}
catch (DOMUnsupportedException e1)
{
}
catch (DOMAccessException e2)
{
}

DOMService Plugability

Since there may be more than one DOMServiceProvider, it is important to allow third parties to plug their DOMServiceProvider implementations into the Common DOM classes. To achieve that, a new Java property, com.sun.browser.dom.DOMServiceProvider, is defined.

If this property is defined, it should contain a list of class names of the DOMServiceProvider implementations, each separated by a character "|".

When DOMService.getService() is called, DOMServiceProvider implementations specified by the com.sun.browser.dom.DOMServiceProvider will be called one-by-one to determine if the provide can determine the DOM association of the object, according to the order that is specified in the property. In case two DOMServiceProvider implementations may be able to handle the same object, the provider that is specified first in the property will be used.

Thread Safety

Because the DOM of each browser is implemented differently, DOM access is not expected to be thread safe. Accessing implementation of DOM objects in this specification must be restricted on the DOM access dispatch thread only, so thread safely can be ensured. To accomplish that, code accessing the DOM objects must be scoped within the DOMAction.run() block. To invoke the action, either DOMService.invokeAndWait() or DOMService.invokeLater() should be used, so that DOMAction.run() will be executed in the DOM access dispatch thread.

Although implementations of DOM objects should not be called outside the DOMAction.run() block, the application may cache these DOM objects around as instance member of a class, or pass these DOM objects between threads. However, caching the DOM objects as static members of any object is prohibited, since static members tend to stay around much longer than the lifecycle of the underlying DOM object.

The only object in the Common DOM classes that can be called from any thread is DOMService. Access to other objects in the Common DOM classes is restricted within the DOMAction.run() block; otherwise, an exception will be thrown.

Security

The browser DOM provides access to every service in the browser, so it is important to ensure that security is checked properly during each call into the DOM. When DOMService.invokeAndWait() or DOMService.invokeLater() is called, the security context of the caller will be captured. Later, when the corresponding DOMAction.run() is executed on the DOM access dispatch thread, the caller's security context will be passed to the browser DOM when implementations of the DOM objects are called. DOMAccessException will be thrown if the original caller doesn't have the required privileges to access the DOM.

Security policy of DOM access in each browser is different. As a result, even if a Java application is signed and fully trusted, accessing the DOM objects in the browser may still result in DOMAccessException.

DOM Object Lifetime

Implementation of the DOM objects represents the real underlying objects in the browser DOM. As the XML/HTML document is changed on-the-fly, DOM objects in Java may no longer be valid. Accessing an invalid DOM object will result in org.w3c.dom.DOMException, according to the W3C DOM Level 2 Specification. Developers who write code to access DOM objects in DOMAction.run() should not assume the validity of the DOM objects at any given moment.

Conformance Requirements

Third parties implementing this specification must provide implementations of the Common DOM classes in the com.sun.browser.dom package. Implementations of the W3C DOM Level 2 APIs must also conformance to the W3C DOM Level 2 Specification. However, because each browser may implement a different subset of the W3C DOM APIs, third parties are not required to provide implementations of all org.w3c.dom and org.w3c.dom.html classes.

Package com.sun.browser.dom

This section defines the API of the com.sun.browser.dom package.

public abstract class DOMService

The DOMService defines a service API that enables applications to access a document object representing the underlying DOM of the browser window that embeds the applications.

public abstract class DOMService
{
        /**
         * Returns new instance of a DOMService. The implementation
         * of the DOMService returns depending on the setting of the
         * javax.browser.dom.DOMServiceProvider property or, if the
         * property is not set, a platform-specific default.
         *
         * Throws DOMUnsupportedException if the DOMService is not
         * available to the obj.
         *
         * @param obj Object to leverage the DOMService
         */
        public static DOMService getService(Object obj) throws DOMUnsupportedException;

        /**
         * An empty constructor is provided. Implementations of this
         * abstract class must provide a protected no-argument constructor
         * in order for the static getService() method to work correctly.
         * Application programmers should not be able to directly
         * construct implementation subclasses of this abstract subclass.
         */
        protected DOMService();

        /**
         * Causes action.run() to be executed synchronously on the
         * DOM action dispatching thread. This call will block until all
         * pending DOM actions have been processed and (then)
         * action.run() returns. This method should be used when an
         * application thread needs to access the browser's DOM.
         * It should not be called from the DOMActionDispatchThread.
         *
         * Note that if the DOMAction.run() method throws an uncaught
         * exception (on the DOM action dispatching thread), it's caught
         * and re-thrown as an DOMAccessException on the caller's thread.
         *
         * @param action DOMAction.
         */
        public abstract Object invokeAndWait(DOMAction action) throws DOMAccessException;

        /**
         * Causes action.run() to be executed asynchronously on the
         * DOM action dispatching thread. This method should be used
         * when an application thread needs to access the browser's
         * DOM. It should not be called from the DOMActionDispatchThread.
         *
         * Note that if the DOMAction.run() method throws an uncaught
         * exception (on the DOM action dispatching thread),  it will not be
         * caught and re-thrown on the caller's thread.
         *
         * @param action DOMAction.
         */
        public abstract void invokeLater(DOMAction action);
}

Note that Object obj in the getService(Object obj) method above is the applet or the bean.

public abstract class DOMServiceProvider

Implementation instances of the public abstract class DOMServiceProvider enable access to the underlying browser DOM for a given Java object. Instances of DOMServiceProvider should not be obtained by the application directly.

public abstract class DOMServiceProvider
{
        /**
         * An empty constructor is provided. Implementations should
         * provide a protected constructor so that the DOMService
         * can instantiate instances of the implementation class.
         * Application programmers should not be able to directly
         * construct implementation subclasses of this abstract subclass.
         * The only way an application should be able to obtain a
         * reference to a DOMServiceProvider implementation
         * instance is by using the appropriate methods of the
         * DOMService.
         */
        protected DOMServiceProvider();

        /**
         * Returns true if the DOMService can determine the association
         * between the obj and the underlying DOM in the browser.
         */
        public abstract boolean canHandle(Object obj);

        /**
         * Returns the Document object of the DOM.
         */
        public abstract org.w3c.dom.Document getDocument(Object obj) throws DOMUnsupportedException;

        /**
         * Returns the DOMImplemenation object of the DOM.
         */
        public abstract org.w3c.dom.DOMImplementation getDOMImplementation();
}

Note that Object obj in the canHandle(Object obj) and getDocument(Object obj) methods above is the applet or the bean.

public interface DOMAccessor

DOMAccessor represents the interface that can be used within DOMAction.run() to access the entry point of the browser DOM.

public interface DOMAccessor
{
        /**
         * Returns the Document object of the DOM.
         */
        public org.w3c.dom.Document getDocument(Object obj) throws org.w3c.dom.DOMException;

        /**
         * Returns a DOMImplementation object.
         */
        public org.w3c.dom.DOMImplementation getDOMImplementation();
}

Note that Object obj in the getDocument(Object obj) method above is the applet or the bean.

public interface DOMAction

DOMAction encapsulates all the actions of the applications that will be performed on the browser's DOM.

public interface DOMAction
{
        /**
         * When an object implementing interface DOMAction is passed
         * to DOMService.invokeAndWait() or DOMService.invokeLater(),
         * the run method is called in the DOM access dispatch thread.
         *
         * accessor is used for the DOMAction to access the entry point of
         * the browser's DOM, if necessary.
         *
         * @param accessor DOMAccessor
         */
        public Object run(DOMAccessor accessor);
}

public class DOMUnsupportedException

This exception is thrown from DOMService.getService() and DOMServiceProvider.getDocument() if the association between the Java object and the DOM cannot be found.

public class DOMUnsupportedException extends Exception
{
        /**
         * Constructs a new DOMUnsupportedException with no detail message.
         */
        public DOMUnsupportedException();

        /**
         * Constructs a new DOMUnsupportedException with the given detail message.
         *
         * @param msg Detail message.
         */
        public DOMUnsupportedException(String msg);

        /**
         * Constructs a new DOMUnsupportedException with the given exception as a root clause.
         *
         * @param e Exception.
         */
        public DOMUnsupportedException(Exception e);

        /**
         * Constructs a new DOMUnsupportedException with the given exception as a root clause and the given          * detail message.
         *
         * @param e Exception.
         * @param msg Detail message.
         */
        public DOMUnsupportedException(Exception e, String msg);

        /**
         * Returns the detail message of the error or null if there is no detail message.
         */
        public String getMessage();

        /**
         * Returns the root cause of the error or null if there is none.
         */
        public Exception getException();
}

public class DOMAccessException

This exception is thrown from DOMService.accessAndWait() if any DOM objects throws any exception when it is accessed within DOMAction.run().

public class DOMAccessException  extends Exception
{
        /**
         * Constructs a new DOMAccessException with no detail message.
         */
        public DOMAccessException();

        /**
         * Constructs a new DOMAccessException with the given detail message.
         *
         * @param msg Detail message.
         */
        public DOMAccessException(String msg);

        /**
         * Constructs a new DOMAccessException with the given exception as a root clause.
         *
         * @param e Exception.
         */
        public DOMAccessException(Exception e);

        /**
         * Constructs a new DOMAccessException with the given exception as a root clause and the given          * detail message.
         *
         * @param e Exception.
         * @param msg Detail message.
         */
        public DOMAccessException(Exception e, String msg);

        /**
         * Returns the detail message of the error or null if there is no detail message.
         */
        public String getMessage();

        /**
         * Returns the root cause of the error or null if there is none.
         */
        public Exception getException();
}


JavaScript to Java

JavaScript to Java Communication (Scripting)

This section includes the following topics:

  • How to Script Applets
  • Using Scripts to Invoke a Method

How to Script Applets

This chapter requires understanding the specific HTML tags required for Java Plug-in. For information about these tags, refer to Using OBJECT, EMBED, and APPLET Tags in Java Plug-in. You also should be familiar with JavaScript.

With scripting you have the capability to call applet methods from within an HTML page. In addition to invoking methods, you can use scripts to:

  • Get and set properties in applets
  • Run Java objects that have been built for scripting

Using Scripts to Invoke a Method

You often want to use scripts to invoke methods on an applet. For example, you might have an HTML button that, when clicked, starts an animation sequence. You do this through a combination of HTML tags and scripting in the HTML file, plus the actual code in the applet itself.

You need to include the following in your applet's HTML page:

  • Within the OBJECT tag, an ID parameter that specifies the name of the applet
  • Tags specifying a scripting language and scripting method associated with a particular action
  • A SCRIPT tag for the scripting method that the action will invoke

These tags are explained in the following sections.

Specify the Applet

You must designate an ID parameter within the OBJECT tag for your HTML page. Recall that the OBJECT tag includes such parameters as classid, width, height, and so on.

The ID parameter is the symbolic name of the applet. Once you establish a symbolic name for an applet through the ID parameter, you can reuse this name later in the scripts to refer to this applet.

For example, suppose you have an applet called Fractal. You add the ID parameter to the OBJECT tag and set ID to the symbolic name of the applet. You might set the tag as follows:

ID="Fractal"

Now, you can use the name Fractal within scripts to refer to the Fractal applet.

Using the same Fractal applet example, your HTML page would begin with a FORM tag, followed by an OBJECT tag, that together might look as follows:

<form name="Form1">
<OBJECT ID="Fractal" WIDTH=500 HEIGHT=120
CLASSID="CLSID:8AD9C840-044E-11d1-B3E9-00805F499D93"
<PARAM NAME="code" value="CLSFractal.class">
<PARAM NAME="codebase" value="1.0.2">
<PARAM NAME="level" value="5">
...
</OBJECT>

Associate the Action to the Script

The HTML page defines components that are intended to invoke actions triggered by the user. You use the INPUT tag to define these components. You specify the TYPE of the component, such as button, its NAME, and VALUE. To have the button or other component actually invoke the intended action, you need to add tags that specify:

  • What the user does to trigger the action, such as onClick for when the user clicks on the button
  • The name of the script method that the HTML page will invoke when the specified trigger action occurs
  • The language in which the script method is written

For example, suppose your HTML page creates a button that, when clicked, starts a particular animation sequence. Your HTML tag creates the button and gives that button a name and a value (label).

To do this you want to add two tags. One tag indicates that on a certain action, such as onclick, a corresponding script method should be called. You might have the tag onClick="method name". The method name is a script method within the same HTML page.

Thus, you might have the following in your HTML page:

<input type="button" name="Button1" value="Start"
onClick="startJSFractal" language="JavaScript">

This INPUT tag creates a button, names the button "Button1", and gives it the value "Start" (the label that appears on the button). It also specifies the scripting method that will be called when a user clicks the button, and the scripting method's language. In this example, the scripting method is startJSFractal, and the scripting language is JavaScript. When the user clicks this button, the HTML page branches to the script method startJSFractal, which is written in JavaScriptscript.

The Script Tag and Method

You must include a SCRIPT tag for the method (function) that the onClick tag specifies. The SCRIPT tag must have the same name as the name used in the onClick tag. It also has a parameter that specifies the script language. More importantly, the script method calls the Java applet method. It identifies the method by using the name of the applet as specified by the ID tag, followed by the actual method name as implemented in the applet code.

For example, the same HTML page might have the following SCRIPT tag:

<SCRIPT language="JavaScript">
function startJSFractal() {
        document.Form1.Fractal.startFractal()
}
</SCRIPT>

In this example, the SCRIPT tag begins by specifying that the scripting language is JavaScript. This is followed by the JavaScript function statement, which starts the definition of a scripting method. The function statement supplies a label or name for the scripting method, calling it startJSFractal. This name must match the method name given for the input component's action parameter.

For this example, both the onClick parameter and the function statement specify the identical scripting method. The scripting method startJSFractal merely calls the actual method, startFractal(), implemented in the applet code. It qualifies the method name by using the document form name , then the applet name (OBJECT ID), then the method name itself, as follows:

document.Form1.Fractal.startFractal()


JavaServer Pages

This chapter includes the following topics:

  • JSP Java Plug-in Action Element: <jsp:plugin>
  • Deploying Java Plug-in through JSP

JavaServer Pages (JSP) is a technology for generating dynamic web-page content from a web/application server. JSP provides support for Java Plug-in HTML elements. This document tells how to use the JSP Plug-in action element for deploying applets with Java Plug-in.

JSP Java Plug-in Action Element: <jsp:plugin>

The <jsp:plugin> action element enables a JSP page author to generate HTML for downloading the Java Plug-in, if it is not installed, and executing an applet. Specifically the action generates the OBJECT element for Internet Explorer or the EMBED element for Netscape Navigator.

When the JSP is executed, the <jsp:plugin> action element is replaced by either an <OBJECT> or <EMBED> HTML tag, depending on the browser.

For example, an applet may be specified as follows in JSP:

<jsp:plugin type=applet code="Molecule" codebase="/html" >
<jsp:params>
    <jsp:param name="molecule" value="molecules/benzene.mol"/>
</jsp:params>
<jsp:fallback>
       <p> Unable to start Plug-in. </p>
</jsp:fallback>
</jsp:plugin>

In the above example, the attributes of the <jsp:plugin> element provide configuration data for the applet itself. The <jsp:param> elements specify the parameters to the applet. The <jsp:fallback> element specifies content for the browser if Java Plug-in fails to start.

Depending on the User Agent requesting the JSP page, the web server will generate either an EMBED or OBJECT tag.

For example, if Netscape Navigator is the User Agent requesting the JSP page, the following EMBED tag will be produced by the server:

<EMBED type="application/x-java-applet"
        code="Molecule" codebase="/html" molecule="molecules/benzene.mol">
<NOEMBED>
<p> Unable to start plug-in </p>
</NOEMBED>

Note

The above works for Netscape 4, as it supports the EMBED tag, but it does not work for Netscape 6.x, as it currently does not support the EMBED tag.

For more information about the <jsp:plugin> element, see Java Server Pages Specification.

Deploying Java Plug-in through JSP

JSP provides an alternative way to deploy applets through Java Plug-in. Because of the dynamic nature of JSP, developers will be able to generate HTML pages on-the-fly that take advantage of Java Plug-in much more easily than before.

Although <jsp:plugin> tag support is part of the JSP specification, various web or application server vendors may provide different implementations and different levels of controls over this feature. For more information, contact your server vendor.


Microsoft VM and Java Applet Compatibility Issues

Appendix 2: Microsoft VM and Java Applet Compatibility Issues

See Java Upgrade Guide in the Java Deployment Guide.


More About HTML Converter

This section includes the following topics:

  • Running the GUI Version of the HTML Converter
    • Choosing files within folders to convert
    • Choosing a backup folder
    • Generating a log file
    • Choosing a conversion template
    • Choosing version scheme
    • Converting
    • Exit or convert more files
    • Details about templates
  • Running the converter from the command line

Notes:

  1. Backup all files before converting them with this tool.
  2. Cancelling a conversion will not rollback the changes.
  3. Comments within the APPLET tag are ignored.

Running the GUI version of the HTML Converter

The HTML Converter is contained in the JDK, not the JRE. The HtmlConverter.exe file located in the bin directory of JDK installation. For example, if you installed the JDK on Windows C drive, then cd to C:\Program Files\Java\jdk1.6.0\bin.

To launch the converter use the htmlconverter.jar contained in the lib directory of the JDK installation. For example if you installed JDK on Windows C drive then cd to C:\Program Files\Java\jdk1.6.0\lib and launch the HTML converter as follows:

C:\Program Files\Java\jdk1.6.0\lib>..\bin\java -jar htmlconverter.jar -gui

Launching the converter on UNIX/Linux is analogous.

Windows Alternative

To launch the converter using Window Explorer, navigate to the following directory:

C:\Program Files\Java\jdk1.6.0\bin

(or to <sdk_location>\bin if it is not located in the directory shown above) then double-click on the HtmlConverter.exe application.

Unix/Linux Alternative

cd to <sdk_location>/bin—for example /home/jones/jdk1.6.0/bin—then enter:

HtmlConverter -gui

The HTML Converter window will appear:

sample converter window

Choosing files within folders to convert:

To convert a single file withing a folder, you may specify the path to the file and include the file name; you may also browse to the file a select it. To convert all files within a folder, you may type in the path to the folder, or choose the browse button to select a folder from a dialog. Once you have chosen a path, you may supply any number of file specifiers in "Matching File Names". Each specifier must be separated by a comma. You may use * as a wildcard. Finally, if you would like all files in nested folders matching the file name to be converted, select the checkbox "Include Subfolders".

Choosing a backup folder:

Windows

The default backup folder path is the source path with an "_BAK" appended to the name; e.g., if the source path is c:/html, then the backup path would be c:/html_BAK. The backup path may be changed by entering a path in the field labeled "Backup Files to Folder:", or by browsing for a folder.

Unix (Solaris):

The default backup folder path is the source path with an "_BAK" appended to the name; e.g., if the source path is /home/user1/html, then the backup path would be /home/user1/html_BAK. The backup path may be changed by typing a path in the field labeled "Backup Files to Folder:", or by browsing for a folder.

Generating a log file:

If you would like a log file to be generated, go to the Advanced Options screen (Edit>Options) and check "Generate Log File". Enter a path in the text field, including the name of the log file; or use the browse button to set the path (including log file). The log file may be an existing one or a new one. The log file contains basic information related to the conversion process.

Choosing a conversion template:

A default template will be used if none is chosen. This template will produce converted html files that will work with IE and Netscape. If you would like to use a different template, you may choose it from the menu on the main screen. If you choose "Other Template ..." from the menu, you will be allowed to choose a file to be used as the template. If you choose a file, be sure that it is a template.

Choosing a version scheme

Note: The specified version mentioned below is the version of the JRE you use to launch the converter; e.g., 1.6.0. The first two numbers in the version indicate the family; e.g., 1.6.0 is in the 1.6 family. For an explanation of product version numbers, see explanation of version numbers in the section called Using OBJECT, EMBED and APPLET Tags in Java Plug-in.

There are two choices here:

  1. You can choose to have conversion tags that will require the specified version of Java Plug-in to run your applets. If the specified version is not installed, then the client will be asked if he/she wants to install and download it.
  2. You can choose conversion tags that will allow any installed version of Java Plug-in in the family, equal to or higher than the specified version, to run your applets. If there is no installed version of Java Plug-in, or no installed version in the family equal to or higher than the specified version, then the client will be asked if he/she wants to install and run the latest version of Java Plug-in in the family.

Converting:

Click the "Convert..." button to begin the conversion process. A dialog will show the files being processed, the number of files processed, the number of applets found, and number of errors.

Exit or Convert More Files:

When the conversion is complete, the button in the process dialog will change from "Cancel" to "Done". You may choose "Done" to close the dialog. You can then exit the Java Plug-in HTML Converter program, or select another set of files to convert.

Details about templates:

The template file is the basis behind converting applets. It is simply a text file containing tags that represent parts of the original applet. By
adding/removing/moving the tags in a template file, you can alter the output of the converted file.

Supported Tags:

$OriginalApplet$ | This tag is substituted with the complete text of the original applet.
$AppletAttributes$ | This tag is substituted with all of the applets attributes (code, codebase, width, height, etc.).
$ObjectAttributes$ | This tag is substituted with all the attributes required by the object tag.
$EmbedAttributes$ | This tag is substituted with all the attributes required by the embed tag.
$AppletParams$ | This tag is substituted with all the applet's <param ...> tags
$ObjectParams$ | This tag is substituted with all the <param...> tags required by the object tag.
$EmbedParams$ | This tag is substituted with all the <param...> tags required by the embed tag in the form name=value
$AlternateHTML$ | This tag is substituted with the text in the no-support-for-applets area of the original applet
$CabFileLocation$ | This is the URL of the cab file that should be used in each template that targets IE.
$NSFileLocation$ | This is the URL of the Netscape plugin to be used in each template that targets Netscape.
$SmartUpdate$ | This is the URL of the Netscape SmartUpdate to be used in each template that targets Netscape Navigator 4.0 or later.
$MimeType$ | This is the MIME type of the Java object.

Below are four templates that come with the HTML Converter. You can make up others and put them in the template folder to use them.

default.tpl— the default template for the converter. The converted page can be used in IE and Navigator on Windows to invoke Java Plug-in. This template can also be used with Netscape on Unix (Solaris)

<!-- HTML CONVERTER -->
<OBJECT classid="clsid:E19F9330-3110-11d4-991C-005004D3B3DB"
$ObjectAttributes$ codebase="$CabFileLocation$">
$ObjectParams$
<PARAM NAME="type" VALUE="$MimeType$">
<PARAM NAME="scriptable" VALUE="false">
$AppletParams$
<COMMENT>
<EMBED type="$MimeType$" $EmbedAttributes$
$EmbedParams$ scriptable=false pluginspage="$NSFileLocation$"><NOEMBED>
</COMMENT>
$AlternateHTML$
 </NOEMBED></EMBED>
</OBJECT>

<!--
$ORIGINALAPPLET$
-->

ieonly.tpl — the converted page can be used to invoke Java Plug-in in IE on Windows only.

<!-- HTML CONVERTER -->
<OBJECT classid="clsid:E19F9330-3110-11d4-991C-005004D3B3DB"
$ObjectAttributes$ codebase="$CabFileLocation$">
$ObjectParams$
<PARAM NAME="type" VALUE="$MimeType$">
<PARAM NAME="scriptable" VALUE="false">
$AppletParams$
$AlternateHTML$
</OBJECT>

<!--
$ORIGINALAPPLET$
-->

nsonly.tpl — the converted page can be used to invoke Java Plug-in in Navigator on Windows and Solaris.

<!-- HTML CONVERTER -->
<EMBED type="$MimeType$" $EmbedAttributes$
$EmbedParams$ scriptable=false pluginspage="$NSFileLocation$"><NOEMBED>
$AlternateHTML$
</NOEMBED></EMBED>

<!--
$ORIGINALAPPLET$
-->

extend.tpl — the converted page can be used in any browser and any platform. If the browser is IE or Navigator on Windows, or Navigator on Solaris, Java(TM) Plug-in will be invoked. Otherwise, the browser's default JVM is used.

<!-- HTML CONVERTER -->
<SCRIPT LANGUAGE="JavaScript"><!--
var _info = navigator.userAgent; var _ns = false; var _ns6 = false;
var _ie = (_info.indexOf("MSIE") > 0 && _info.indexOf("Win") > 0 &&
_info.indexOf("Windows 3.1") < 0);
//--></SCRIPT>
<COMMENT><SCRIPT LANGUAGE="JavaScript1.1"><!--
var _ns = (navigator.appName.indexOf("Netscape") >= 0 &&
((_info.indexOf("Win") > 0 && _info.indexOf("Win16") < 0 &&
java.lang.System.getProperty("os.version").indexOf("3.5") < 0) ||
_info.indexOf("Sun") > 0));
var _ns6 = ((_ns == true) && (_info.indexOf("Mozilla/5") >= 0));
//--></SCRIPT></COMMENT>

<SCRIPT LANGUAGE="JavaScript"><!--
if (_ie == true) document.writeln('<OBJECT
classid="clsid:E19F9330-3110-11d4-991C-005004D3B3DB" $ObjectAttributes$
codebase="$CabFileLocation$"><NOEMBED><XMP>');
else if (_ns == true && _ns6 == false) document.writeln('<EMBED
type="$MimeType$" $EmbedAttributes$
$EmbedParams$ scriptable=false
pluginspage="$NSFileLocation$"><NOEMBED><XMP>');
//--></SCRIPT>
<APPLET $AppletAttributes$></XMP>
$ObjectParams$
<PARAM NAME="type" VALUE="$MimeType$">
<PARAM NAME="scriptable" VALUE="false">
$AppletParams$
$AlternateHTML$
</APPLET>
</NOEMBED></EMBED></OBJECT>

<!--
$ORIGINALAPPLET$
-->

Running the converter from the command line:

Format:

java -jar htmlconverter.jar [-options1 value1 [-option2 value2 [...]]] [-simulate] [filespecs]

If only "java -jar htmlconverter.jar -gui" is specified (only -gui option with no filespecs), the GUI version of the converter will be launched. Otherwise, the GUI will be suppressed.

filespecs:
space-delimited list of file specifications which may include wildcard (*), e.g. *.html, file*.html).

-simulate:
Set to preview a conversion without actually doing the conversion. Use this option if you are unsure about a conversion. You will be shown detail information about the conversion had it been done.

Options: | Description
-source | Path to files; e.g., c:\htmldocs in Windows, /home/user1/htmldocs in Unix. Default is <userdir> If the path is relative, it is assumed to be relative to the directory from which the HTMLConverter was launched.
-dest | Path to converter file location. Default: <usrdir>
-backup | Path to the directory where you want backup files to be stored. Default: <source>_BAK If the path is relative, it is assumed to be relative to the directory from which the HTMLConverter was launched.
-f | Force overwritting of backup files.
-subdirs | Sets whether files in subdirectories should be converted or not. Default: false
-template | Name of template file to use for conversion. Default: Standard (IE & Navigator) for Windows & Solaris Only. Note: Use the default if you are unsure.
-log | Path and filename for the log. If not provided, no log file is written.
-progress | Set to display standard out progress during conversion. Default: true
-latest | Use the latest JRE supporting the MIME type.
-gui | Display the graphical user interface for the converter.


Multi-Version Support

This chapter includes the following topics:

  • Unique CLSID
  • Unique MIME Type and dll
  • Unique Java Plug-in Registry Key
  • Unique Java Plug-in Property File
  • Unique Java Plug-in Trace and Log Files
  • Unique Java Control Panel
  • Unique Registry Keys for JRE/JDK
  • Multi-version Support in Browser Sessions

Every new or patch release of Java Plug-in uniquely identifies registry keys, CLSID, MIME type and other resources.This allows multiple JRE versions to be deployed in the same environment.

Unique CLSID

There is a unique CLSID for every new or patch version of Java Plug-in. (CLSID is used in the OBJECT tag with Internet Explorer running on Windows.) If you want a minimum version of Java Plug-in to be used, then specify this unique CLSID in the OBJECT tag. The CLSID is stored in the registry in:

HKEY_CLASSES_ROOT\CLSID\

In general the CLSID looks as follows:

CAFEEFAC-<major version>-<minor version>-<patch version>-ABCDEFFEDCBA

where major version, minor version and patch version are all 4-digit hexadecimal numbers.

Examples:

For example, the CLSID for Java Plug-in 6 is as follows:

clsid:CAFEEFAC-0016-0000-0000-ABCDEFFEDCBA

and you would find this in the registry:

HKEY_CLASSES_ROOT\CLSID\CAFEEFAC-0016-0000-0000-ABCDEFFEDCBA

Note that CLSID is also stored in:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Code Store Database\Distribution Units\

Unique MIME Type and dll

There is a unique MIME type and NP*.dll for every new or patch version of Java Plug-in. MIME type identifies the type or version of the Java executable to be loaded and initialized by Java Plug-in. It is specified with the element type in the EMBED tag with supported Mozilla browsers and with <PARAM name="type"> in the OBJECT tag for Internet Explorer. If you want to use a minimum version of Java Plug-in with supported Mozilla browsers, specify the unique MIME type in the EMBED tag.

Note

MIME type will be supported by an NP*.dll with a unique name for every new or patch version. Thus, installing different version of Java Plug-in does not overwrite other .dll files in supported Mozilla browsers Plugins directory.

In general MIME types look like this:

application/x-java-applet;jpi-version=<version>

where version includes the major, minor and patch version numbers.

MIME types are supported in the file

NPJPI<modified version number>.dll

Example:

For Java Plug-in 1.6.0, the unique MIME type would be:

application/x-java-applet;jpi-version=1.6.0

and it would be supported in the file:

NPJPI160.dll

in supported Mozillas Plugins directory.

Unique Java Plug-in Registry Key

There is a unique Java Plug-in registry key for every new or patch version of Java Plug-in. The main Java Plug-in registry key is as follows:

HKEY_LOCAL_MACHINE\Software\JavaSoft\Java Plug-in\<version number>

where the <version number> includes the major, minor and the patch version numbers.

Example:

For Java Plug-in 1.6.0 you will find the following in your registry:

HKEY_LOCAL_MACHINE\Software\JavaSoft\Java Plug-in\1.6.0

Unique Java Plug-in Property File

The property file is now named deployment.properties. It is located in the following directory:

<User Application Data Folder>\Sun\Java\Deployment

where <User Application Data Folder> is an application data folder specific to the user.

As an example, for a user testuser on a Windows XP system, the value of <User Application Data Folder> would be C:\Documents and Settings\testuser\Application Data

The deployment.properties file is used by version 1.6.0. The value of <User Application Data Folder> is obtained from the Win32 API function call SHGetFolderPath() with CSIDL_APPDATA.

Unique Java Plug-in Trace and Log Files

The default location for trace and log files is <User Application Data Folder>\Sun\Java\Deployment\log

where <User Application Data Folder> is as defined above.

The property javaplugin.outputfiles.path can be used to override the default location for the trace and log files. For more information refer to the tracing and logging section in the Deployment Guide .

Unique Java Control Panel

There is a unique Java Control Panel for every new or patch release. In 1.6.0, the filename for the Control Panel is javacpl.exe.

Only the latest installed version of the Java Control Panel is available from the Windows Control Panel.

Unique Registry Keys for JRE/JDK

There are unique registry keys for every new or patch release of the JRE/JDK. These registry keys are located as follows:

HKEY_LOCAL_MACHINE\Software\JavaSoft\Java Runtime Environment\<version number>
HKEY_LOCAL_MACHINE\Software\JavaSoft\Java Development Kit\<version number>

where the <version number> includes the major, minor and the patch version numbers; e.g., 1.6.0

These keys allow Java Plug-in to locate the proper version of the JRE.

Multi Version Support in Browser Sessions

Mutliple JRE versions can be installed on Windows platform. With multiple JRE's applets using MIME type jpi-version will work with Mozilla browsers only if you enable the following options:

  • To enable the Mozilla Family option for JRE 6, open Java Control Panel and click Advanced > Default Java for browsers > Mozilla family
  • To enable the Mozilla and Netscape option for JRE 1.5.0 or earlier, open Java Control Panel and click Advanced > <Applet> tag support > Mozilla and Netscape

To invoke Java Control Panel for a specific version of the JRE browse to the <JRE_HOME>/bin directory of that version and run javacpl.exe.

Note

Multiple versions of the JRE can be run in different browser sessions. However, multiple versions cannot be run in the same browser session. Should this be attempted, the user is warned and the attempt will fail.


Netscape 6

This section describes the primary features of the Java runtime in Netscape 6, which is enabled by Java Plug-in. It includes the following topics:

  • APPLET , EMBED AND OBJECT Tag Support
  • Java-JavaScript Bi-directional Communication
  • RSA Signed Applet Verification
  • Display of Java Console
  • Enable/Disable Java
  • Applet Lifecycle Change
  • Proxy and Cookie Support
  • HTTPS
  • Automatic Download
  • Backward Compatibility Issue

APPLET Tag Support

Applets are loaded by Java Plug-in if the conventional APPLET tag is used.

Note:

Currently the OBJECT and element does not work with Netscape 6 with Java Plug-in. You must use the APPLET or EMBED element with Netscape 6.

Java-JavaScript Bi-directional Communication

JavaScript can access the methods of applets, and applets can access the Document Object Model (DOM) through JavaScript.

See Java-to-JavaScript Communication and JavaScript-to-Java Communication. Be sure to read the sections on security.

RSA Signed Applet Verification

RSA signed applet verification is supported.

Display of Java Console

You may display the Java Console through the Netscape 6 browser menu: Tasks>Tools>Java Console.

Enable/Disable Java

You may enable/disable Java through the Netscape 6 browser menu: Edit>Preferences>Advanced. Note that to take effect, the browser must be restarted.

Applet Lifecycle Change

Whenever a page is visited, the init() and start() methods of the applet are called; and whenever the page is left, the stop() and destroy() methods may be called.

Proxy and Cookie Support

Java Plug-in previously handled proxy and cookie support alone. In Netscape 6 this support is moved to the browser.

HTTPS

HTTPS is supported through Java Secure Socket Extension (JSSE) in J2SE.

Automatic Download

Via its XPInstall mechanism, Netscape 6 will support automatic download of Java Plug-in (JRE) if it is not present.

Backward Compatibility Issue

Although Sun has tried to ensure backward compatibility as much as possible between Java 2 and the Netscape VM, it may not be 100%. Some applets may run as is; other may only need recompilation; others, however, may need to be ported to Java 2.


Overview - What Is Java Plug-in

Overview—What Is Java Plug-in? What Does It Support?

This chapter includes the following topics:

  • What Is Java Plug-in?
  • Supported Operating Systems and Browsers

What Is Java Plug-in?

Java Plug-in extends the functionality of a web browser, allowing applets or Java Beans to be run under Sun's Java Runtime Environment (JRE) rather than the Java Runtime Environment that comes with the web browser. Java Plug-in is part of Sun's JRE . It is installed with the JRE on users computer. It works with supported Mozilla browsers and Internet Explorer.

Browsers can run applets by invoking the Java Plug-in in two different ways:

  1. By using the conventional APPLET tag in a web page.
  2. By replacing the APPLET tag with the OBJECT tag for Internet Explorer; by replacing the APPLET tag with the EMBED tag for supported Mozilla browsers. Note, however, that the OBJECT and EMBED tags must conform to a special format as described in the next chapter, Using OBJECT, EMBED and APPLET Tags in Java Plug-in.

OBJECT and EMBED tags can be manually updated in web pages.

While the above constitutes the heart of Java Plug-in, there are many other related topics that you may want to understand. For instance, you may want to know how proxy configuration works in Java Plug-in, you may want to know what protocols Java Plug-in supports, or you may want to know about cookie support and caching. Such topics are included in Part I: Java Plug-in Basics.

You can determine some of the behavior of Java Plug-in and set options via the Java Control Panel. How you do this is also discussed in Part I in the chapter called Using the Java Control Panel to Set Plug-in Behavior/Options.

Java Plug-in may be deployed in various ways—on the Internet, within an intranet, via Java Server Pages, etc. The various types and methods of deployments are discussed in the Part II: Deployment Schemes.

Applets must be run in a secure environment, and various security topics are discussed in the Part III: Security, including RSA signed applet verification. As signing applets can be a difficult topic for novice applet developers, this guide provides step-by-step instructions for signing applets in the chapter called Signing Applets Using RSA-Signed Certificates.

Java Plug-in provides various kinds of debugging support for applets, and Part IV: Debugging Support describes them. Java Debugger support is discussed. So is the Java Plug-in Console, which includes various options that may be set for debugging, including ones for tracing and logging.

Part V: Advanced Topics discusses more esoteric matters such as supporting multiple JREs in the same environment, Java-toJavaScript communication, how to persist applets across browser sessions, special applet attributes for changing the applet window background color, etc.

Appendices provide information about supported Mozilla browsers, an FAQ, information about the HTML Converter, and Microsoft VM versus Java SE compatibility issues.

Supported Operating Systems and Browsers

For supported operating system and browsers, see Supported System Configurations.


Overview -- Applet Security Basics

Overview—Applet Security Basics

Applet Security Basics

Below are the basic facts regarding applet security and Java Plug-in. More details can be found in the next chapter, Verification of RSA Signed Applets in Java Plug-in.

  • All unsigned applets are run under the standard applet security model.
  • If usePolicy is not defined in the java.policy file, then a signed applet has the AllPermission permission only if Java Plug-in can verify the signers, and the user agrees to granting the AllPermission permission when prompted.
  • If usePolicy is defined, then a signed applet has only the permissions defined in java.policy and no prompting occurs.

Moreover, note that Java Plug-in now handles certificate management; i.e., the certificate verification task is no longer passed on to the browser.

Running Signed Applets on Windows Vista

Signed applets on Windows Vista have less privileges compared to the applets running on other Windows operating systems such as Windows XP Home or Windows XP Professional. This is due to the fact that browser process has low level of integrity. Low level integrity implies lesser privileges than an Administrator. This causes the signed applet not to write and delete files in specific medium and high integrity level directories.

If you run a signed applet in Windows Vista, a dialog box with a security warning appears. Click Run, to allow the applet to run with all permissions except write or delete permissions for files on local drive.

Secure Versioning

Java applets using Java SE 5.0 Update 6 or earlier versions could specify the exact version of the JRE on which they can be run. This allowed Java applets to run with a JRE that might not have the latest security fixes.

Java SE 6 allows all the applets to be executed with the latest installed JRE version.This is a new enhancement that provides additional security.


Protocol Support

This chapter includes the following topics:

  • HTTP, FTP, and GOPHER
  • HTTPS
  • Socks
  • NTLM Authentication

HTTP, FTP, and GOPHER

Java Plug-in supports HTTP, FTP, and GOPHER protocols, including built-in proxy configuration support.

HTTPS

Introduction

HTTPS is supported in Java Plug-in through Java Secure Socket Extension (JSEE), which provides a Java implementation of SSL and HTTPS for the Java platform.

Error handling support

When accessing an HTTPS server, errors may occur. Java Plug-in has hooked into JSSE to provide the following types of error handling:

  • Hostname mismatch: If the HTTPS server host name does not match the name on the server certificate, a warning dialog will appear.
  • Untrusted server certificate: If the server certificate can not be verified during the SSL handshaking, a warning dialog will appear.
  • Untrusted client certificate: In case client authentication is required by the server and the client certificate cannot be verified, a warning dialog will be appear.
  • Server authentication: If the client accesses a protected directory on the HTTPS server, the users will be prompted for a username and password. Note: Only basic authentication is currently supported.

Potential issues with HTTPS through JSSE

Although support of HTTPS through JSSE eliminates many browser-specific problems, there are several issues that developers should be aware of:

  • Untrusted server certificate: When SSL handshaking takes place in establishing an HTTPS connection, the server certificate is verified against the root CA store in Java SE. However, Java SE supports fewer root CA certificates than does the browser. As a result, you may have problems with untrusted server certificates.
  • Client authentication: Java Plugin supports browser keystore in JRE 1.5 or later. With browser keystore client authentication of HTTPS server is performed differently for Internet Explorer and Mozilla family browsers. For Internet Explorer the certificate is not imported into the JRE keystore. For Mozilla family browsers, a JSS package should be installed to read the certificate from the Mozilla keystore. By default browser keystore support is turned on.
  • Level of error handling: Java Plug-in currently handles the types of error listed in the previous section. However, if there are additional types of error that Java Plug-in doesn't recognize, the Java applet code may break.

Socks

Java Plug-in currently supports SOCKS version 4.

Note: For HTTP/HTTPS, a SOCKS proxy server may be used with a web proxy server to add caching. The behavior, however, may differ from that observed when running a similar configuration in a browser without Java Plug-in.

NTLM Authentication

Java Plug-in supports NTLM authentication protocol for HTTP/HTTPS. When attempting to access a server requiring NTLM authentication, the following dialog is displayed:

NTLM Authentication required. Provide your username, password and domain name

To authenticate enter User Name, Password and the Domain in the respective fields.


Proxy Configuration

See Proxy Configuration in the Java Deployment Guide.


Signing Applets Using RSA Signed Certificates

Signing Applets Using RSA Certificates

This chapter covers the following topics:

  • Introduction
  • Signing Tools
  • Getting RSA Certificates
    • Getting Certificates With Jarsigner
    • Getting Certificates With Netscape Signing Tool
  • Bundling Java Applets as JAR Files
  • Signing Java Applets
    • Signing Applets Using jarsigner
    • Signing Applets Using Netscape Signing Tool
  • Converting Old Netscape-Signed Applets
  • Microsoft Authenticode
  • Common Problems

Introduction

RSA-signed applets are supported to make deployment of signed applets easier. However, signing applets through RSA is still difficult for most novice applet developers and prevents them from taking full advantage of this Java Plug-in feature. This document provides step-by-step instructions for signing applets using RSA certificates, allowing novice applet developers to sign their applets without having to wade through the many complex security issues involved.

Signing applets requires the following :

  1. Signing tools
  2. An RSA keypair and a certificate chain for the public keys
  3. The applet and all its class files, bundled as JAR files

Signing Tools

Java Plug-in supports the format of the following tools for signing applets using RSA:

  1. jarsigner—Signing tool shipped as part of the Java SDK
  2. signtool—Signing tool provided by Netscape for signing applets in Navigator/Communicator. For more details on the sign tool and downloading it read the page at http://www.mozilla.org/projects/security/pki/nss/tools.

Getting RSA Certificates

RSA certificates may be purchased from a Certificate Authority (CA) that supports RSA, such as VeriSign and Thawte. Some CAs, such as VeriSign, implement different protocols for issuing certificates, depending on the particular signing tool you are using.

Getting Certificates With Jarsigner

Jarsigner is known to work with VeriSign and Thawte certificates and may work with Certificate Authorties. To use Jarsigner to sign applets using RSA certificates, obtain the Sun Java Signing certificate from VeriSign or the Java Code Signing certificate from Thawte—or similar certificates from other CAs. During the process of certificate enrollment, you will be asked to provide the certificate signing request (CSR). To generate the CSR, follow these steps:

  1. Use keytool to generate an RSA keypair (using the "-genkey -keyalg rsa" options). Make sure your distinguished name contains all the components mandated by VeriSign/Thawte. E.g.,
    C:\Program Files\Java\jdk1.6.0\bin\keytool -genkey -keyalg rsa -alias MyCert
Enter keystore password: *********
What is your first and last name?
[Unknown]: XXXXXXX YYY
What is the name of your organizational unit?
[Unknown]: Java Software
What is the name of your organization?
[Unknown]: Sun Microsystems
What is the name of your City or Locality?
[Unknown]: Cupertino
What is the name of your State or Province?
[Unknown]: CA
What is the two-letter country code for this unit?
[Unknown]: US
Is <CN=XXXXXXX YYY, OU=Java Software, O=Sun Microsystems,
                L=Cupertino, ST=CA, C=US> correct?
[no]: yes

Enter key password for <MyCert>
(RETURN if same as keystore password): *********
  2. Use "keytool -certreq" to generate a certification signing request. Copy the result and paste it into the VeriSign/Thawte webform. For example,
    C:\Program Files\Java\jdk1.6.0\bin\keytool -certreq -alias MyCert

Enter keystore password:  *********
-----BEGIN NEW CERTIFICATE REQUEST-----
MIIBtjCCAR8CAQAwdjELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMRIwE
AYDVQQHEwlDdXBlcnRpbm8xGTAXBgNVBAoTEFN1biBNaWNyb3N5c3RlbX
MxFjAUBgNVBAsTDUphdmEgU29mdHdhcmUxEzARBgNVBAMTClN0YW5sZXk
gSG8wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBALTgU8PovA4y59eb
oPjY65BwCSc/zPqtOZKJlaW4WP+UhmebE+T2Mho7P5zXjGf7elo3tV5uI
3vzgGfnhgpf73EoMow8EJhly4w/YsXKqeJEqqvNogzAD+qUv7Ld6dLOv0
CO5qvpmBAO6mfaI1XAgx/4xU/6009jVQe0TgIoocB5AgMBAAGgADANBgk
qhkiG9w0BAQQFAAOBgQAWmLrkifKiUYtd4ykhBtPWSwW/IKkgyfIuNMML
dF1DH8neSnXf3ZLI32f2yXvs7u3/xn6chnTXh4HYCJoGYOAbB3WNbAoQR
i6u6TLLOvgv9pMNUo6v1qB0xly1faizjimVYBwLhOenkA3Bw7S8UIVfdv
84cO9dFUGcr/Pfrl3GtQ==
-----END NEW CERTIFICATE REQUEST-----
  3. The CA (e.g., VeriSign/Thawte) will send you a certificate reply (chain) by email. Copy the chain and store it in a file. Use "keytool -import" to import the chain into your keystore. E.g.,
    C:\Program Files\Java\jdk1.6.0\bin\keytool -import -alias MyCert -file VSSStanleyNew.cer
  4. Your RSA certificate and its supporting chain have been validated and imported into your keystore. You are now ready to use jarsigner to sign your JAR file.

Note

You must use the same alias name for all the above steps—or no alias name, in which case the alias name defaults to "mykey".

Getting Certificates With Netscape Signing Tool

Most CAs (e.g., VeriSign/Thawte) support Netscape Signing Tool. To use the Netscape Signing Tool to sign applets using RSA certificates, obtain the Netscape Object Signing certificate from Verisign or the Netscape Object Signing certificate from Thawte—or similar certificates from other CAs. During the process of enrollment, you will be asked for personal/company information, since the CA will need to verify your identity before issuing a certificate. This process may take from several hours to several days.

Once the RSA certificate is issued, it usually consists of three files:

  • cert7.db
  • key3.db
  • secmod.db

Depending on the CA, the certificate may be issued and stored on a floppy diskette, or it may be stored directly in the security modules of Netscape Navigator/Communicator. Once you have the certificate, you are ready to use the Netscape Signing Tool to sign your JAR file.

Bundling Java Applets as JAR Files

To use Jarsigner to sign applets with RSA certificates, the applets must be bundled as JAR files. The Jar tool (command jar ...), which comes wiht the Java SE SDK, can be used for that purpose. E.g.,

C:\Program Files\Java\jdk1.6.0\bin\jar cvf C:\TestApplet.jar .
added manifest
adding: TestApplet.class (in = 94208) (out= 20103)(deflated 78%)
adding: TestHelper.class (in = 16384) (out= 779)(deflated 95%)
This example creates a JAR file C:\TestApplet.jar, and it contains all the files under the current directory and its sub-directories.

After the JAR file is created, you should verify its content using the jar tool again, e.g.,

C:\Program Files\Java\jdk1.6.0\bin\jar tvf TestApplet.jar
     0 Mon Mar 06 18:02:54 PST 2000 META-INF/
    68 Mon Mar 06 18:02:54 PST 2000 META-INF/MANIFEST.MF
 94208 Wed Mar 10 11:48:52 PST 2000 TestApplet.class
 16384 Wed Mar 10 11:48:52 PST 2000 TestHelper.class
This ensures that the class files are stored with the proper path within the JAR file.

To sign an applet with an RSA certificate using the Netscape Signing Tool, the applet must be placed in a directory, e.g., C:\signdir. The Netscape Signing Tool will bundle it as JAR file after the signing process.

Signing Java Applets

Once you have the RSA certificates, the signing tool and the applet's JAR files, you are ready to sign the applets.

Signing Applets Using jarsigner

To sign applets using jarsigner, follow these steps:

  1. Use jarsigner to sign the JAR file, using the RSA credentials in your keystore that were generated in the previous steps. Make sure the same alias name is specified. E.g.,
    C:\Program Files\Java\jdk1.6.0\bin\jarsigner C:\TestApplet.jar MyCert
Enter Passphrase for keystore: ********
  2. Use "jarsigner -verify -verbose -certs" to verify the jar files
    C:\Program Files\Java\jdk1.6.0\bin\jarsigner -verify -verbose
                -certs d:\TestApplet.jar

         245 Wed Mar 10 11:48:52 PST 2000 META-INF/manifest.mf
         187 Wed Mar 10 11:48:52 PST 2000 META-INF/MYCERT.SF
         968 Wed Mar 10 11:48:52 PST 2000 META-INF/MYCERT.RSA
smk      943 Wed Mar 10 11:48:52 PST 2000 TestApplet.class
smk      163 Wed Mar 10 11:48:52 PST 2000 TestHelper.class

      X.509, CN=XXXXXXX YYY, OU=Java Software,
                O=Sun Microsystems, L=Cupertino,
                ST=CA, C=US (mycert)
      X.509, CN=Sun Microsystems, OU=Java Plug-in QA,
                O=Sun Microsystems, L=Cupertino, ST=CA, C=US
      X.509, EmailAddress=server-certs@thawte.com,
                CN=Thawte Server CA, OU=Certification
                Services Division, O=Thawte Consulting cc,
                L=Cape Town, ST=Western Cape, C=ZA

  s = signature was verified
  m = entry is listed in manifest
  k = at least one certificate was found in keystore
  i = at least one certificate was found in identity scope

jar verified.
  3. Your applet has been signed properly. You are now ready to deploy your RSA signed applet.

Signing Applets Using Netscape Signing Tool

To sign applets using signtool, follow these steps:

  1. Use "signtool -L" to determine the certificate nickname that should be used in signing. E.g.,
    C:\signtool13WINNT40\signtool -L -d a:\cert
using certificate directory: a:\cert

S Certificates
- ------------
  AT&T Certificate Services
  Thawte Personal Premium CA
  GTE CyberTrust Secure Server CA
  Verisign/RSA Commercial CA
  AT&T Directory Services
  BelSign Secure Server CA
  BelSign Class 1 CA
  GTIS/PWGSC, Canada Gov. Web CA
  Thawte Personal Freemail CA
  Thawte Server CA
  GTIS/PWGSC, Canada Gov. Secure CA
  MCI Mall CA
  VeriSign Class 3 Primary CA
  VeriSign Class 4 Primary CA
  KEYWITNESS, Canada CA
  BelSign Class 2 CA
  BelSign Object Publishing CA
* Sun Microsystems, Inc.
  VeriSign Class 3 CA - Commercial Content/Software
                        Publisher - VeriSign, Inc.
  Verisign/RSA Secure Server CA
  VeriSign Class 1 Primary CA
  BBN Certificate Services CA Root 1
  Thawte Personal Basic CA
* Sun Microsystems, Inc.'s VeriSign, Inc. ID
  CertiSign BR
  VeriSign Class 2 Primary CA
  Canada Post Corporation CA
  Integrion CA
  IBM World Registry CA
  BelSign Class 3 CA
  Uptime Group Plc. Class 1 CA
  Uptime Group Plc. Class 2 CA
  Thawte Premium Server CA
  Uptime Group Plc. Class 3 CA
  GTE CyberTrust Root CA
  Uptime Group Plc. Class 4 CA
- ------------

Certificates that can be used to sign objects
have *'s to their left.
  2. Create an empty directory. E.g.,
    mkdir signdir
  3. Put all the applet class files into it.

  4. Use "signtool -Z" to sign the applet. E.g.,
    C:\signtool13>signtool -k "Sun Microsystems, Inc.'s VeriSign, Inc. ID"
        -d a:\cert -Z c:\TestApplet.jar c:\signdir
using certificate directory: a:\cert
Generating c:\signdir/META-INF/manifest.mf file..
--> TestApplet.class
adding c:\signdir/TestApplet.class to c:\TestApplet.jar...
        (deflated 57%)
--> TestHelper.class
adding c:\signdir/TestHelper.class to c:\TestApplet.jar...
        (deflated 43%)
Generating zigbert.sf file..
adding c:\signdir/META-INF/manifest.mf to c:\TestApplet.jar...
        (deflated 44%)
adding c:\signdir/META-INF/zigbert.sf to c:\TestApplet.jar...
        (deflated 46%)
adding c:\signdir/META-INF/zigbert.rsa to c:\TestApplet.jar...
        (deflated 40%)
tree "c:\signdir" signed successfully
  5. Use "signtool -w" to verify the archive. E.g.,
    C:\signtool13>signtool -w c:\TestApplet.jar -d a:\cert
using certificate directory: a:\cert

Signer information:

nickname: Sun Microsystems, Inc.'s VeriSign, Inc. ID
subject name: C=US, ST=CA, L=Palo Alto, OU=Java Software,
        CN=Sun Microsystems, OU=Digital ID Class 3 - Netscape
Object Signing, OU="www.verisign.com/repository/RPA Incorp.
        by Ref.,LIAB.LTD(c)99", OU=VeriSign Trust Network,
        O="VeriSign, Inc."
issuer name: CN=VeriSign Class 3 CA - Commercial Content/Software
        Publisher, OU="www.verisign.com/repository/RPA Incorp.
        by Ref.,LIAB.LTD(c)98", OU=VeriSign Trust Network,
        O="VeriSign, Inc."

Your applet has been signed properly. You are now ready to deploy your RSA signed applet. See How to Deploy RSA Signed Applets for deployment information.

Converting Old Netscape-Signed Applets

Existing RSA signed applets designed for Netscape may use Netscape-specific security APIs. These Netscape-specific APIs are not supported in Java Plug-in. Instead, the Plug-in supports the standard Java security APIs in both Netscape Navigator and Internet Explorer.

To migrate Netscape-signed applets using the Netscape security APIs to run in Java Plug-in:

  1. Comment or remove all netscape.security.* related statements from the Java applet.
  2. Compile and archive the applet as a JAR file.
  3. Re-sign the JAR file using Object Signing.

This ensures that an RSA signed applet will run in both Netscape Navigator and Internet Explorer with Java Plug-in.

Microsoft Authenticode

Authenticode is a proprietary signing technology used in Microsoft Internet Explorer on Win32 for supporting signed applets in IE's JVM. Authenticode is not supported in Java Plug-in. Instead, the Java Plug-in supports use of RSA signed applets in both IE and Netscape.

Common Problems

  • If the JAR file is not signed properly, if the RSA certificate has expired, or if the RSA certificate is a self-generated, self-signed certificate, Java Plug-in may fail silently and not pop up the security dialog. The applet will be treated as unsigned.
  • The Netscape Signing Tool is very particular about JAR file format. In Netscape Signing Tool, it expects the MANIFEST file to be at the end of the JAR file, whereas Jarsigner puts it at the beginning. The standard does not mandate where the MANIFEST file should be in the JAR file. Therefore, if you create a JAR file using Jar tool, the Netscape Signing Tool may complain about "Invalid Jar File Format". On the other hand, Jarsigner is not picky; it can verify a JAR file regardless of whether its MANIFEST file is located at the beginning or the end. To avoid this problem when using Netscape Signing Tool, you should both generate and sign the JAR file through the Netscape Signing Tool.


Silent Installation

See Silent Installation in the Java Deployment Guide.


SimplePlayerApplet.java Source Code

/*
 * @(#)SimplePlayerApplet.java  1.2 01/03/13

 *
 * Copyright (c) 1996-2001 Sun Microsystems, Inc. All Rights Reserved.
 *
 * Sun grants you ("Licensee") a non-exclusive, royalty free, license to use,
 * modify and redistribute this software in source and binary code form,
 * provided that i) this copyright notice and license appear on all copies of
 * the software; and ii) Licensee does not utilize the software in a manner
 * which is disparaging to Sun.
 *
 * This software is provided "AS IS," without a warranty of any kind. ALL
 * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY
 * IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR
 * NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN AND ITS LICENSORS SHALL NOT BE
 * LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING
 * OR DISTRIBUTING THE SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS
 * LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT,
 * INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER
 * CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF
 * OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGES.
 *
 * This software is not designed or intended for use in on-line control of
 * aircraft, air traffic, aircraft navigation or aircraft communications; or in
 * the design, construction, operation or maintenance of any nuclear
 * facility. Licensee represents and warrants that it will not use or
 * redistribute the Software for such purposes.
 */

import java.applet.Applet;
import java.awt.*;
import java.awt.event.*;
import java.lang.String;
import java.net.URL;
import java.net.MalformedURLException;
import java.io.IOException;
import java.util.Properties;
import javax.media.*;
//import com.sun.media.util.JMFSecurity;

/**
  * This is a Java Applet that demonstrates how to create a simple
  * media player with a media event listener. It will play the
  * media clip right away and continuously loop.
  *
  *<!-- Sample HTML
  * <applet code=SimplePlayerApplet width=320 height=300>
  * <param name=file value="sun.avi">
  * </applet>
  * -->
  */
public class SimplePlayerApplet extends Applet implements ControllerListener {

    // media Player
    Player player = null;
    // component in which video is playing
    Component visualComponent = null;
    // controls gain, position, start, stop
    Component controlComponent = null;
    // displays progress during download
    Component progressBar = null;
    boolean firstTime = true;
    long CachingSize = 0L;
    Panel panel = null;
    int controlPanelHeight = 0;
    int videoWidth = 0;
    int videoHeight = 0;

    /**
     * Read the applet file parameter and create the media
     * player.
     */
    public void init() {
        //$ System.out.println("Applet.init() is called");
        setLayout(null);
        setBackground(Color.white);
        panel = new Panel();
        panel.setLayout( null );
        add(panel);
        panel.setBounds(0, 0, 320, 240);

        // input file name from html param
        String mediaFile = null;
        // URL for our media file
        MediaLocator mrl = null;
        URL url = null;

        // Get the media filename info.
        // The applet tag should contain the path to the
        // source media file, relative to the html page.

        if ((mediaFile = getParameter("FILE")) == null)
            Fatal("Invalid media file parameter");

        try {
            url = new URL(getDocumentBase(), mediaFile);
            mediaFile = url.toExternalForm();
        } catch (MalformedURLException mue) {
        }

        try {
            // Create a media locator from the file name
            if ((mrl = new MediaLocator(mediaFile)) == null)
                Fatal("Can't build URL for " + mediaFile);

            /*
            try {
                JMFSecurity.enablePrivilege.invoke(JMFSecurity.privilegeManager,
                                                   JMFSecurity.writePropArgs);
                JMFSecurity.enablePrivilege.invoke(JMFSecurity.privilegeManager,
                                                   JMFSecurity.readPropArgs);
                JMFSecurity.enablePrivilege.invoke(JMFSecurity.privilegeManager,
                                                   JMFSecurity.connectArgs);
            } catch (Exception e) {}
            */

            // Create an instance of a player for this media
            try {
                player = Manager.createPlayer(mrl);
            } catch (NoPlayerException e) {
                System.out.println(e);
                Fatal("Could not create player for " + mrl);
            }

            // Add ourselves as a listener for a player's events
            player.addControllerListener(this);

        } catch (MalformedURLException e) {
            Fatal("Invalid media file URL!");
        } catch (IOException e) {
            Fatal("IO exception creating player for " + mrl);
        }

        // This applet assumes that its start() calls
        // player.start(). This causes the player to become
        // realized. Once realized, the applet will get
        // the visual and control panel components and add
        // them to the Applet. These components are not added
        // during init() because they are long operations that
        // would make us appear unresposive to the user.
    }

    /**
     * Start media file playback. This function is called the
     * first time that the Applet runs and every
     * time the user re-enters the page.
     */

    public void start() {
        //$ System.out.println("Applet.start() is called");
        // Call start() to prefetch and start the player.
        if (player != null)
            player.start();
    }

    /**
     * Stop media file playback and release resource before
     * leaving the page.
     */
    public void stop() {
        //$ System.out.println("Applet.stop() is called");
        if (player != null) {
            player.stop();
            player.deallocate();
        }
    }

    public void destroy() {
        //$ System.out.println("Applet.destroy() is called");
        player.close();
    }

    /**
     * This controllerUpdate function must be defined in order to
     * implement a ControllerListener interface. This
     * function will be called whenever there is a media event
     */
    public synchronized void controllerUpdate(ControllerEvent event) {
        // If we're getting messages from a dead player,
        // just leave
        if (player == null)
            return;

        // When the player is Realized, get the visual
        // and control components and add them to the Applet
        if (event instanceof RealizeCompleteEvent) {
            if (progressBar != null) {
                panel.remove(progressBar);
                progressBar = null;
            }

            int width = 320;
            int height = 0;
            if (controlComponent == null)
                if (( controlComponent =
                      player.getControlPanelComponent()) != null) {

                    controlPanelHeight = controlComponent.getPreferredSize().height;
                    panel.add(controlComponent);
                    height += controlPanelHeight;
                }
            if (visualComponent == null)
                if (( visualComponent =
                      player.getVisualComponent())!= null) {
                    panel.add(visualComponent);
                    Dimension videoSize = visualComponent.getPreferredSize();
                    videoWidth = videoSize.width;
                    videoHeight = videoSize.height;
                    width = videoWidth;
                    height += videoHeight;
                    visualComponent.setBounds(0, 0, videoWidth, videoHeight);
                }

            panel.setBounds(0, 0, width, height);
            if (controlComponent != null) {
                controlComponent.setBounds(0, videoHeight,
                                           width, controlPanelHeight);
                controlComponent.invalidate();
            }

        } else if (event instanceof CachingControlEvent) {
            if (player.getState() > Controller.Realizing)
                return;
            // Put a progress bar up when downloading starts,
            // take it down when downloading ends.
            CachingControlEvent e = (CachingControlEvent) event;
            CachingControl cc = e.getCachingControl();

            // Add the bar if not already there ...
            if (progressBar == null) {
                if ((progressBar = cc.getControlComponent()) != null) {
                    panel.add(progressBar);
                    panel.setSize(progressBar.getPreferredSize());
                    validate();
                }
            }
        } else if (event instanceof EndOfMediaEvent) {
            // We've reached the end of the media; rewind and
            // start over
            player.setMediaTime(new Time(0));
            player.start();
        } else if (event instanceof ControllerErrorEvent) {
            // Tell TypicalPlayerApplet.start() to call it a day
            player = null;
            Fatal(((ControllerErrorEvent)event).getMessage());
        } else if (event instanceof ControllerClosedEvent) {
            panel.removeAll();
        }
    }

    void Fatal (String s) {
        // Applications will make various choices about what
        // to do here. We print a message
        System.err.println("FATAL ERROR: " + s);
        throw new Error(s); // Invoke the uncaught exception
                            // handler System.exit() is another
                            // choice.

    }
}


Special Applet Attributes

Applets have default attributes associated with them. Special attributes like image and boxmessage can be associated with applets and used for customizing the applet window during downloading of an applet. JavaBeans component can also be customized using these special attributes. This section discusses the following :

  • Default Appearance of Applets
  • Special Attributes of Applets
  • Applet Attribute Precedence
  • Troubleshooting Scenario

Default Appearance of Applets

The def ault appearence of a Applet when no special attributes are used is as follows:

  • The Java logo is centered in the applet's space.
  • There is a white glow (circle with hazy edge) encircling the Java brand.
  • The rotating burst animation shows that activity is occuring.
  • The progress bar is located below the bottom edge of the Java brand graphic to show the progress as the applet is downloaded.
  • Depending on the size of the applet's viewing area the default appearance will vary.
  • The design of animation will scale to accomodate different "width-by-height" combinations.
  • When the mouse is moved over the applet's area during the loading period, the cursor changes to the normal hypertext cursor indicating that this element is an interactive part of the web page.
  • Clicking/selecting anywhere within the Gray Box will spawn a new browser window pointing to the www.java.com web page.

Special Attributes of Applets

image

The image attribute allows you to replace the default animation with a custom graphic. The format with the standard APPLET element is:

<APPLET ...>
<PARAM name="image" value="my_image.gif">
</APPLET>

See Using OBJECT, EMBED and APPLET Tags in Java Plug-in for how this would be mapped to the OBJECT or the EMBED tags.

If a custom graphic is specified, it should be the same size as the area of the applet window. If these sizes do not match, the graphic will be placed in the upper left corner of the area specified for applet. If it is larger than the applet window, part of it will get chopped off. If it is smaller than the applet window, white, or whatever color is specified for boxbgcolor, will appear around it.

The image can be either a GIF or JPEG, and it should reside in the same directory where other resources for the applet reside; i.e., if the applet uses the codebase attribute, then this image should be in the codebase directory.

Note: The image file should not be in a packaged jar file with other applet resources, since the image needs to be displayed while downloading resources.

The status bar of the browser will display "Loading Java Applet ..." when the mouse is pointed at the applet window.

boxmessage

With the boxmessage attribute you can customize the text displayed in the status bar of the browser. This attribute will be in effect when image attribute is used. The format for using this with the standard APPLET element is:

<APPLET ...>
<PARAM name="boxmessage" value="<your custom message goes here>">
</APPLET>

boxbgcolor, boxfgcolor

These attributes can be used to customize colors in the applet window.

These attributes will be in effect when the image attribute is used. Custom colors cannot be specified for the default appearance of the applet viewing area.

By default the applet window background color is white. The attribute boxbgcolor can be used to specify a different background color. The format for use with the standard APPLET element is:

<APPLET ...>
<PARAM name="boxbgcolor" value="<value>">
</APPLET>

where <value> may be:

  • any Color from java.awt.Color;
  • r,g,b where r, g, and b are integers in the range of 0-255 that would render an opaque standard RGB (sRGB) color in the Color constructor Color(int r, int g, int b);
  • standard HTML colors: silver, green, maroon, purple, navy, teal, and olive; or
  • hexadecimal color format

Examples of each item above: value="cyan", value="111,222,145", value="silver", value="#33FF33"

By default the applet window foreground color is black. The attribute boxfgcolor can be used to specify a different foreground color. The color values are the same as described above. The format for use with the standard APPLET element is:

<APPLET ...>
<PARAM name="boxfgcolor" value="<value>">
</APPLET>

Applet Attribute Precedence

The order of precedence for these attributes in applets is as follows:

1) If no parameters are provided, the default appearance described above is used.
2) If a custom graphic is specified via the image attribute, then the custom graphic will appear as described above under image.
3) If custom text is provided via the boxmessage attribute, then custom text will be displayed as described above under boxmessage.

With any combination of image and boxmessage attributes, custom colors can always be provided via the boxbgcolor and boxfgcolor attributes.

Troubleshooting Scenario

If an applet fails to load the following actions are performed:

  • The applet window displays error information.
  • The applet window has a single pixel border using white for the foreground color, and a small "broken" graphic will occupy the upper left corner.

The user can click in the applet window to get a popup menu to open one of the following options:

    • Open the Java Console
    • Open a window with information about the Java VM and Java Plug-in.


Tracing and Logging

See Tracing and Logging in the Java Deployment Guide.


Using applet, object and embed Tags

This chapter includes the following topics:

  • Introduction
  • General Considerations
  • Using the applet tag
  • Using the object tag
  • Using the embed tag
  • Deploying Applets in a Mixed-Browser Environment

Introduction

This chapter explains to HTML authors how and when to use the applet, object, and embed tags to add Java applets to Web pages. In addition, this chapter provides guidelines for deploying applets on the Internet and Intranets, and for use with different browsers.

General Considerations

How you deploy an applet depends on whether users access the Web page through the Internet or an Intranet, and the type of browser they use. Note this information about your users, then follow the general guidelines below.

Deploying Applets on the Internet Versus an Intranet

When deploying applets:

  • Use the applet tag if the Web page is accessed through the Internet.

  • Use the object or embed tag if the Web page is accessed through an Intranet.

Deploying Applets for Specific Browsers

When deploying applets:

  • For Internet Explorer only, use the object tag.

  • For the Mozilla family of browsers only, use the embed tag.

If you must deploy an applet in a mixed-browser environment, follow the guidelines in the section Deploying Applets in a Mixed-Browser Environment.

Using the applet tag

You use the applet tag to deploy applets to a multi-browser environment.

For complete details on the applet tag, read the W3 HTML specification.

Note: The HTML specification states that the applet tag is deprecated, and that you should use the object tag instead. However, the specification is vague about how browsers should implement the object tag to support Java applets, and browser support is currently inconsistent. Sun therefore recommends that you continue to use the applet tag as a consistent way to deploy Java applets across browsers on all platforms.

Following is an example of the applet tag:

    <applet code=Applet1.class width="200" height="200">
    Your browser does not support the <code>applet</code> tag.
    </applet>

For both Internet Explorer and the Mozilla family of browsers, if Java Plug-in is installed (version 1.3.1_01a or later) then the highest installed version of Java Plug-in is invoked to run the applet.

Note

You cannot use the applet tag to automatically download a JRE if one is not installed locally.

Using the object tag

You use the object tag to deploy applets that are to be used only with Internet Explorer. For complete details on the object tag, read the W3 HTML specification. Following is an example of the object tag:

<OBJECT
  classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
  width="200" height="200">
  <PARAM name="code" value="Applet1.class">
</OBJECT>

The classid Attribute

The classid attribute identifies which minimum version of Java Plug-in to use.

The example shown below is the most commonly used form of the classid attribute. This example instructs Internet Explorer to use the highest installed version of Java Plug-in.

classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"

Following is an alternative form of the classid attribute:

classid="clsid:CAFEEFAC-xxxx-yyyy-zzzz-ABCDEFFEDCBA"

In this form, "xxxx", "yyyy", and "zzzz" are four-digit numbers that identify the minimum version of Java Plug-in to be used. For example, to use Java Plug-in version 1.6.0, you specify:

classid="clsid:CAFEEFAC-0016-0000-0000-ABCDEFFEDCBA"

The codebase Attribute

You use the optional codebase attribute to specify if and how to download the JRE.

The codebase attribute has two forms:

  • codebase=<URL>

    With this form, if the JRE specified by the classid attribute is not installed locally, then the user is prompted to download the JRE from the URL specified.
  • codebase=<URL>#Version=major,minor,micro,update

    With this form, if the version of the JRE specified in the codebase attribute is greater than the version of the JRE specified by the classid attribute, then the user is prompted to download the JRE from the URL specified.

Following is an example of how to use the codebase attribute to set up automatic downloads from the Sun Java Web site:

<object
  classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
  width="200" height="200"
  codebase="http://java.sun.com/products/plugin/autodl/
jinstall-1_5_0-windows-i586.cab#Version=1,5,0,0">
  <param name="code" value="Applet1.class">
</object>

Note: In this example the codebase=http://java.sun.com ... line is broken for readability. In the actual HTML file it would be one long line.

Sun has packaged each version of the JRE installer in Microsoft cabinet (.cab) file format. You can view a list of these releases and the corresponding .cab file names.

Using the embed tag

You use the embed tag to deploy applets that are to be used only with the Mozilla family of browsers.

Following is an example of the embed tag:

<embed code="Applet1.class"
  width="200" height="200"
  type="application/x-java-applet;version=1.6.0"
  pluginspage="http://java.sun.com/javase/downloads/ea.jsp"/>

The type attribute can have one of two forms:

  • type="application/x-java-applet;version=1.6.0"

    With this form, the highest installed JRE that supports the MIME type i.e. application/x-java-applet;version=1.6.0 is invoked to run the applet. If a JRE with a version number equal to or greater than the version number specified is installed locally, then that JRE is invoked. Otherwise the user is directed to the URL specified as the value of the pluginspage attribute.
  • type="application/x-java-applet;jpi-version=1.5.0_07

    With this form, a JRE with at least the specified update version given by the the value of jpi-version (in this example, 1.5.0_07) is invoked to run the applet. Otherwise the user is directed to the URL specified as the value of the pluginspage attribute.

Deploying Applets in a Mixed-Browser Environment

You can deploy applets for users of both Internet Explorer and the Mozilla family of browsers in one of two ways:

  • Using pure HTML

  • Using JavaScript

Deploying Applets Using Pure HTML

When using a pure HTML approach to deploy applets in a mixed-browser environment, note the following:

  • Internet Explorer

    • Recognizes the object tag
    • Ignores the contents of the comment tag
  • Mozilla browsers
    • Ignore an object tag with the classid attribute
    • Interpret the contents of the comment tag

Consider the following example code from an HTML page:

<object
  classid="clsid:CAFEEFAC-0016-0000-0000-ABCDEFFEDCBA"
  <param name="code" value="Applet1.class">
    <comment>
      <embed code="Applet1.class"
        type="application/x-java-applet;jpi-version=1.6.0">
        <noembed>
          No Java Support.
        </noembed>
      </embed>
    </comment>
  </object>

Deploying Applets Using JavaScript

Instead of using the pure HTML approach described above, you can use JavaScript to deploy applets in a mixed-browser environment.

Through JavaScript, you:

  1. Detect the user's browser through the appName variable.

  2. Use the document.write() method to write a tag based on the value of the appName variable:

    1. If the browser name equals "Mozilla", write the embed tag.

    2. If the browser name equals "Microsoft Internet Explorer", write the object tag.

In the following example, the document.write() method outputs either an embed or object tag for each user “on the fly”:

<html>
<script language="Javascript">

  var _app = navigator.appName;

  if (_app == 'Mozilla') {
    document.write('<embed code="Applet1.class"',
                   'width="200"',
                   'height="200"',
                   'type="application/x-java-applet;version=1.5.0">');
    }
  else if (_app == 'Microsoft Internet Explorer') {
    document.write('<OBJECT ',
                   'classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"',
                   'width="200"',
                   'height="200">',
                   '<PARAM name="code" value="Applet1.class">',
                   '</OBJECT>');
    }
  else {
    document.write('<p>Sorry, unsupported browser.</p>');
    }

</script>
</html>


Using OBJECT, EMBED and APPLET Tags in Java Plug-in

This chapter includes the following topics:

  • Introduction
  • JavaTM Plug-in in IE on Windows
  • Java Plug-in in NavigatorTM on Windows or SolarisTM operating environments
  • Java Plug-in in IE and Navigator
  • Java Plug-in Anywhere
  • Summary

Introduction

This document explains the tagging structure, involving OBJECT and EMBED tags, required by Java Plug-in. It is intended for web authors who want to manually insert Java Plug-in tags in their HTML pages.

Notes

  1. There is a Java Plug-in HTML Converter, available free-of-charge from Sun Microsystems, that can automatically generate the tagging structure. It is highly recommended that most web authors use it.
  2. This converter can convert pages into any of the formats described below.
  3. For a complete list of JRE releases that can be autodownloaded via .cab files, as mentioned below, see Autodownload Files (Windows Only).

Applets are normally specified in an HTML file as follows:

<APPLET code="XYZApp.class" codebase="html/" align="baseline"
    width="200" height="200">
<PARAM name="model" value="models/HyaluronicAcid.xyz">
    No Java 2 SDK, Standard Edition v 1.4.2 support for APPLET!!
</APPLET>

And normally the APPLET tag specifies information about the applet, while the <PARAM> tags, located between the <APPLET> and </APPLET> tags, store per-instance applet information.

However, an APPLET is rendered by the browser and there is no easy way to interrupt the browser and force it to use Sun's Java Runtime Environment (JRE) to run the applet. To force the browser to do so, however, you may use a special Java Plug-in tagging structure—involving the OBJECT or EMBED tag or both, as described below—in place of the usual APPLET tag in an your HTML pages. This will cause the browser to launch Java Plug-in, which will then run the applet using Sun's JRE.

For various combinations of browsers and platforms, the following sections tell you exactly what you need to do

Note on Version Numbers

Product version numbers are of the form:

n1.n2.n3_n4n5

where n1.n2 is the major version number, the n3 is the minor version number (also referred to as the maintenance version number), and n4n5 is the patch version number (also referred to as the update version number).

The version numbers used in the examples below refer to the 1.4 major release with minor release number of 2 and, at times, hypothetical patch number of mn. Do not put hypothetical values into actual HTML for web pages.

Java Plug-in in IE on Windows

To use Java Plug-in in IE on Windows, use the OBJECT tag. The following is an example of mapping an APPLET tag to a Java Plug-in tag:

Original APPLET tag:

<APPLET code="XYZApp.class" codebase="html/" align="baseline"
    width="200" height="200">
<PARAM name="model" value="models/HyaluronicAcid.xyz">
    No Java 2 SDK, Standard Edition v 1.4.2 support for APPLET!!
</APPLET>

New OBJECT tag:

<OBJECT classid="clsid:CAFEEFAC-0014-0002-0000-ABCDEFFEDCBA"
    width="200" height="200" align="baseline"
    codebase="http://java.sun.com/products/plugin/autodl/jinstall-1_4_2-windows-i586.cab#Version=1,4,2,0">
    <PARAM name="code" value="XYZApp.class">
    <PARAM name="codebase" value="html/">
    <PARAM name="type" value="application/x-java-applet;jpi-version=1.4.2">
    <PARAM name="model" value="models/HyaluronicAcid.xyz">
    <PARAM name="scriptable" value="true">
        No Java 2 SDK, Standard Edition v 1.4.2 support for APPLET!!
</OBJECT>

Note

For static versioning, set codebase equal to:

http://java.sun.com/products/plugin/autodl/<.cab file for the version you want>

For example, for static versioning for the 1.4.2 release (which uses classid of clsid:CAFEEFAC-0014-0002-0000-ABCDEFFEDCBA), set codebase to:

http://java.sun.com/products/plugin/autodl/jinstall-1_4_2-win.cab

For a complete list of JRE releases that can be autodownloaded via .cab files, see Autodownload Files (Windows Only).

For dynamic versioning (which uses classid of clsid:8AD9C840-044E-11D1-B3E9-00805F499D93), set codebase equal to:

http://java.sun.com/products/plugin/autodl/jinstall-<major version of family in underscore format>-windows-i586.cab#Version=<full version number for lowest version in family in comma-separated format>

If no version of Java is installed, or a version less than the major version of the family is installed, then this will cause automatic redirection to the latest .cab for the latest version in the family.

For example, for the 1.4.2 release you would set codebase as follows:

http://java.sun.com/products/plugin/autodl/jinstall-1_4-windows-i586.cab#Version=1,4,0,0

If the user had version 1.3.1 installed, then the latest version in the 1.4 family would be downloaded and installed. But if any version in the 1.4 family were installed, then it would be used and no download would take place.

Note that the autodownload .cab files can change as patch releases are released. See below for more about the interpretation of codebase.

Note that the OBJECT tag contains similar information to the APPLET tag. It is sufficient to launch Java Plug-in in IE. The classid in the OBJECT tag is the class identifier for Java Plug-in itself. When IE renders this class identifier in the OBJECT tag, it will try to load Java Plug-in into the browser. See classid attribute below for information about versioning.

There are several attributes in the OBJECT tag, such as width, height and align, that are mapped directly from the corresponding attributes in the APPLET tag. These contain formatting information that IE will use to position Java Plug-in. Since this information is mapped directly without changes, the position and appearance of the applets using Java Plug-in should be the same as those applets using the APPLET tag.

Not all attributes in the APPLET tag can be mapped to the OBJECT tag attributes. For example, the attributes code and codebase in the APPLET tag are not mapped into the OBJECT tag attribute. Instead, the attribute code is mapped into the PARAM code because, according to the w3c.org HTML specification, the attribute code does not exist in the OBJECT tag. There are other attributes that do not correspond in the OBJECT tag attributes. These attributes, with one exception, should be mapped to PARAM tags.

Note

Duplicate parameter names should never be used with the OBJECT tag in Java Plug-in.

The one exception is the codebase attribute. In the APPLET tag, the codebase attribute represents the location from which to download additional class and jar files. However, in the OBJECT tag, the codebase attribute represents the location from which to download Java Plug-in when it is not found on the local machine. Because the codebase attribute has two different meanings in the APPLET and OBJECT tags, the codebase attribute in the APPLET tag is mapped into a PARAM codebase in the OBJECT tag to resolve the conflict.

In the above example, the code and codebase attributes in the APPLET tag are mapped into the OBJECT tag parameters. The PARAM code identifies the applet, and its value should be the same as the code attribute in the APPLET tag. The PARAM codebase identifies the codebase of the applet. Java Plug-in knows where to download the applet or JavaBeans component because it can read this information from the parameters. The parameter type is not mapped from the APPLET tag, but it is required in the OBJECT tag. It identifies the type of the Java executable, such as an applet or a JavaBean, so that Java Plug-in knows how to initialize the Java executable. These three PARAM tags (code, codebase, and type) in the above example are specified for Java Plug-in. They do not exist in the PARAM of the original APPLET tag. Note that the model parameter within the OBJECT tag is identical to the model parameter inside the APPLET tag. Except for these first three parameters specified for Java Plug-in, the remainder of the parameters are the same as those inside the APPLET tag.

A new addition for Java Plug-in 1.3 (and valid in 1.4.x) was the PARAM scriptable. This was added to improve performance of applets that do not require the use of JavaScript or VBScript. The value should be true if the applet requires scripting support and false if it does not. The value is false by default.

Please note that PARAM scriptable is not the same as the PARAM mayscript. mayscript provides support for communication from Java applets to JavaScript only, while scriptable allows communication from JavaScript to Java applets in Internet Explorer only.

The text "No Java 2 SDK, Standard Edition v 1.4.2 support for APPLET!!" in the APPLET tag is mapped inside the <OBJECT> and </OBJECT> tags. Originally, this text is displayed only if the browser does not have Java support. By mapping it inside the OBJECT tag, this text will be displayed if the browser does not support the OBJECT tag.

The APPLET-to-OBJECT tag attributes mapping is as follows:

Attribute Name | APPLET Tag Support | OBJECT Tag Support | Attribute Mapping to OBJECT Tag
align | X | X | OBJECT attribute align
alt | X
archive | X | PARAM element archive
code | X | X | PARAM element code
codebase | X | X | PARAM element codebase
height | X | X | OBJECT attribute height
hspace | X | X | OBJECT attribute hspace
name X X

OBJECT attribute name, PARAM element name

This case is an exception. The name attribute in the orginal APPLET element must be mapped both to the name attribute in the OBJECT element and to a nested PARAM. If the original applet were as follows:

<APPLET name="clock" ...>
</APPLET>

Then the mapping would be:

<OBJECT name="clock" ...>
<PARAM name="name" value="clock">
</OBJECT>
object | X | PARAM element object
title | X | X | OBJECT attribute title
vspace | X | X | OBJECT attribute vspace
width | X | X | OBJECT attribute width
mayscript | X | PARAM element mayscript

Some OBJECT attributes and nested PARAM elements are special to the OBJECT tag. They are the following:

Attribute/PARAM | Meaning in OBJECT tag
Attribute classid

It should always have the same value for dynamic version support, i.e. clsid:8AD9C840-044E-11D1-B3E9-00805F499D93. For static version support it will have a unique value for the version, e.g., clsid:CAFEEFAC-0014-0002-0000-ABCDEFFEDCBA.

For more information about static vs. dynamic versioning, see Encountering OBJECT, EMBED, and APPLET Tags With Different Plug-in Versions and Browsers.

Note: The example above uses static versioning.

Attribute codebase

It should be a full URL pointing to a .cab file somewhere on the network. It's purpose is to allow downloading and installation of Plug-in if either no version of Plug-in is installed on a user's computer or if no appropriate version of Plug-in is installed. The URL should, by default, point to a page on the Java Software website.

Examples:

In the above example, codebase is:

codebase="http://java.sun.com/products/plugin/autodl/jinstall-1_4_2-windows-i586.cab#Version=1,4,2,0"

Note that this was for static versioning and that the version number appended to the .cab file indicates that 1.4.2 version of Plug-in needs to be installed on the user's computer, otherwise an attempt will be made to download and install it.

For dynamic versioning, codebase would be as follows:

codebase="http://java.sun.com/products/plugin/autodl/jinstall-1_4-windows-i586.cab#Version=1,4,0,0"

The appended version number indicates that if the user has version 1.4.0 or higher of the Plug-in installed on the computer, no download will occur. In other words, if the installed Plug-in is in the 1.4 family (major version 1.4), then it will run. If the installed version is lower, however, then an attempt will be made to download and install a newer version via the .cab file.
PARAM element type

The value for parameter type should be as follows:

"application/x-java-<object_type>;<version_type>=<implementation_version>"

where

object_type is applet or bean;

version_type is jpi-version for static versioning or version for dynamic versioning;

implementation_version is Implementation-Version as defined in Appendix 6: Sun-Supported Specification-Version and Implemenation-Version Formats.

For more information about static vs. dynamic versioning, see Encountering OBJECT, EMBED, and APPLET Tags With Different Plug-in Versions and Browsers.

Examples:

For an applet deployed for static versioning with Plug-in version 1.4.1 patch release 02, value for type would be as follows:

"application/x-java-applet;jpi-version=1.4.1_02"

For a bean deployed for dynamic versioning with Plug-in version 1.4.1 patch release 03, value for type would be:

"application/x-java-bean;version=1.4"

This is because for dynamic versioning only the major version number is checked; i.e., if the installed Plug-in is in the major version family, no download is required.
PARAM element codebase | Specifies the base URL of the applet. The URL can be relative or absolute but it should be in the domain of the current document. This PARAM element is required only if the applet is not located in the same directory as the document.
PARAM element code | Specifies the name of the Java applet or JavaBeans component. It cannot be used with PARAM element object nested inside the same OBJECT tag.
PARAM element scriptable | Specifies whether the applet is scriptable from the HTML page using JavaScript or VBScript. The value can be either true or false. This attribute is new in Java Plug-in 1.4.
PARAM element object | Specifies the name of the serialized Java applet or JavaBeans component. It cannot be used with PARAM element code nested inside the same OBJECT tag. This attribute is optional.
PARAM element archive | Specifies the name of the Java archive. This attribute is optional.
PARAM element mayscript | Specifies whether the applet is allowed to access netscape.javascript.JSObject. The value can be either true or false. This attribute is optional.

If the original APPLET element uses attributes type, codebase, code, object or archive, and also has nested PARAM element attributes type, codebase, code, object or archive, there will be a problem with the direct mapping of the APPELET attributes to PARAM attributes , as there will then be PARAM elements with duplicate name attributes, e.g.,

If the orginal applet were as follows:

<APPLET codebase = "a/b/c ...>
<PARAM name="codebase" value="my.jar">
</APPLET>

Then the direct mapping would be:

<OBJECT ...>
<PARAM name="codebase" value="a/b/c">
<PARAM name="codebase" value="my.jar">
</OBJECT>

To avoid this problem, any APPLET attribute that has a corresponding PARAM element in the orignal applet should be mapped as shown below.

Original attribute in the APPLET element | New PARAM attribute with OBJECT element
code | java_code
codebase | java_codebase
archive | java_archive
object | java_object
type | java_type

These new PARAM element attribute names should be used only when necessary. If both the new and original PARAM names exist in the same OBJECT tag, the values associated with the new PARAM element names are used by Java Plug-in to load the applet or JavaBean.

Example

Suppose the orginal applet was as follows:

<APPLET codebase = "a/b/c ...>
<PARAM name="codebase" value="my.jar">
</APPLET>

Then the mapping should be as shown below:

<OBJECT ...>
<PARAM name="java_codebase" value="a/b/c">
<PARAM name="codebase" value="my.jar">
</OBJECT>

Java Plug-in in Netscape Navigator on Windows or SolarisTM operating environments

To use Java Plug-in with Netscape Navigator 4.x on Windows or Solaris operating environments, you must use the EMBED tag. The following example shows the mapping of a traditional APPLET tag to a Java Plug-in EMBED tag:

Original APPLET tag:

<APPLET code="XYZApp.class" codebase="html/" align="baseline"
    width="200" height="200">
<PARAM name="model" value="models/HyaluronicAcid.xyz">
    No Java 2 SDK, Standard Edition v 1.4.1 support for APPLET!!
</APPLET>

New EMBED tag:

<EMBED type="application/x-java-applet;jpi-version=1.4.1" width="200"
   height="200" align="baseline" code="XYZApp.class"
   codebase="html/" model="models/HyaluronicAcid.xyz"
   pluginspage="http://java.sun.com/j2se/1.4.1/download.html">
<NOEMBED>
   No Java 2 SDK, Standard Edition v 1.4.1 support for APPLET!!
</NOEMBED>
</EMBED>

Note that the EMBED tag contains similar information to the APPLET tag.It is sufficient to launch Java Plug-in in Navigator. The attribute type in the EMBED tag is used to identify the type of the Java executable, such as an applet or a bean. When Navigator renders this attribute in the EMBED tag, it will try to load Java Plug-in into the browser. Note that a version number is also appended. It is used for comparing the version installed on a user's computer and deciding if another version needs to be installed. The second table below describes this in greater detail.

In the above example, several attributes in the EMBED tag, such as width, height and align, map directly from the corresponding attributes in the APPLET tag. These contain formatting information that Navigator uses to position Java Plug-in. Since this information is mapped directly without changes, the position and appearance of the applets using Java Plug-in should be the same as those applets using the APPLET tag.

Unlike the OBJECT tag, all information must be stored inside the <EMBED> tag. No PARAM elements are used with the EMBED tag. Therefore, all APPLET attributes and related PARAM elements must be mapped as attribute name="value" pairs inside the EMBED tag.

In the above example, the code and codebase attributes in the APPLET tag are mapped into the EMBED tag attributes. Attribute code identifies the applet. Its value should be the same as the code attribute in the APPLET tag. Attribute codebase identifies the codebase of the applet. Java Plug-in knows where to download the applet or JavaBeans component because it can read this information from the attributes. Also notice that the model attribute within the EMBED tag is mapped from the nested PARAM element model inside the APPLET tag.

Like the codebase attribute in the OBJECT tag, attribute pluginspage in the EMBED tag is used by Navigator if Java Plug-in is not installed on the user's computer, or if the wrong version of Java Plug-in is installed. It should point to the Java Plug-in Download Page on the Java Software website; or, for intranet deployment, to a page on the intranet from which Java Plug-in may be downloaded.

The text "No Java 2 SDK, Standard Edition v 1.4.1 support for APPLET!!" in the APPLET tag is mapped inside the <NOEMBED> and </NOEMBED> tags. With the traditional APPLET tag this text is displayed only if the browser does not have internal support for Java. By mapping it inside the NOEMBED tag, this text will be displayed if the browser does not support the EMBED tag, or if Navigator fails to start the Java Plug-in.

The APPLET-to-EMBED tag attributes mapping is as follows:

Attributes | APPLET tag support | EMBED tag support | Attribute map to EMBED tag
align | X | X | Attribute align
alt | X | X | Attribute alt
archive | X |  | Attribute archive
code | X |  | Attribute code
codebase | X |  | Attribute codebase
height | X | X | Attribute height
hspace | X | X | Attribute hspace
name | X | X | Attribute name
object | X |  | Attribute object
title | X | X | Attribute title
vspace | X | X | Attribute vspace
width | X | X | Attribute width
mayscript | X |  | Attribute mayscript

Some attributes are special to the EMBED tag. These attributes are:

Attribute
Meaning in EMBED tag
Attribute type

type should be as follows:

"application/x-java-<object_type>;<version_type>=<implementation_version>"

where

object_type is applet or bean;

version_type is jpi-version for static versioning or version for dynamic versioning;

implementation_version is Implementation-Version as defined in Appendix 6: Sun-Supported Specification-Version and Implemenation-Version Formats.

For more information about static vs. dynamic versioning, see Encountering OBJECT, EMBED, and APPLET Tags With Different Plug-in Versions and Browsers.

Examples:

For an applet deployed for static versioning with Plug-in version 1.4.1 patch release 02, type would be as follows:

"application/x-java-applet;jpi-version=1.4.1_02"

For a bean deployed for dynamic versioning with Plug-in version 1.4.1 patch release 03, type would be:

"application/x-java-bean;version=1.4"

This is because for dynamic versioning only the major version number is checked; i.e., if the installed Plug-in is in the major version family, no download is required).
Attribute codebase | Specifies the base URL of the applet or JavaBeans component. The URL can be relative or absolute but it should be in the domain of the current document. This attribute is required only if the applet is not located in the same directory as the document.
Attribute code | Specifies the name of the Java applet or JavaBeans component. It cannot be used with param object inside the same EMBED tag.
Attribute object | Specifies the name of the serialized Java applet or JavaBeans component. It cannot be used with the code attribute inside the same EMBED tag. This attribute is optional.
Attribute archive | Specifies the name of the Java archive. This attribute is optional.
Attribute pluginspage | It should be a full URL pointing to an HTML page from which Java Plug-in can be downloaded. If there is no Plug-in installed on a user's computer, or if the version of the Plug-in is not the one specified via the the type attribute, then this page will be presented to the user.
Attribute mayscript | Specifies whether the applet is allowed to access netscape.javascript.JSObject. The value can be either true or false. This attribute is optional.

Similar to the case of the OBJECT tag, if the original APPLET tag has PARAM element type, codebase, code, object, or archive, mapping it to the EMBED tag attribute will cause a problem. To avoid this, Java Plug-in also supports the same new set of attribute names for the EMBED tag, as specified below:

Similar to the case of the OBJECT element, if the original APPLET element uses attributes type, codebase, code, object or archive, and also has nested PARAM element attributes type, codebase, code, object or archive, there will be a problem with the direct mapping of the APPELET attributes to EMBED attributes. To avoid this problem, Java Plug-in also supports the same new set of attribute names for the EMBED tag, as specified below:

Original Attribute Names | New Attribute Names
code | java_code
codebase | java_codebase
archive | java_archive
object | java_object
type | java_type

These new attribute names should be used only when necessary. If both new and original attribute names exist in the same EMBED tag, the value associated with the new attribute name is used by Java Plug-in to load the applet or bean.

Java Plug-in in IE and Navigator

The new OBJECT element scheme described above allows a web page with an applet to use Java Plug-in with Internet Explorer, and the new EMBED element scheme allows a web page with an applet to use Java Plug-in with Netscape. However, changes are a web page will be browsed by both browsers. Hence, there needs to be a way to use the OBJECT scheme when a page is browser by Internet Explorer, and the EMBED scheme when the page is browsed by Netscape. Such a scheme is described below.

Original APPLET element:

<APPLET code="XYZApp.class" codebase="html/" align="baseline"
    width="200" height="200">
<PARAM NAME="model" VALUE="models/HyaluronicAcid.xyz">
    No Java 2 SDK, Standard Editoin v 1.4 support for APPLET!!
</APPLET>

New OBJECT element with nested EMBED element:

<OBJECT classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
    width="200" height="200" align="baseline"
    codebase="http://java.sun.com/products/plugin/1.4/jinstall-14-win32.cab#Version=1,4,0,mn">
    <PARAM NAME="code" VALUE="XYZApp.class">
    <PARAM NAME="codebase" VALUE="html/">
    <PARAM NAME="type" VALUE="application/x-java-applet;jpi-version=1.4">
    <PARAM NAME="model" VALUE="models/HyaluronicAcid.xyz">
    <PARAM NAME="scriptable" VALUE="true">
    <COMMENT>
        <EMBED type="application/x-java-applet;jpi-version=1.4" width="200"
           height="200" align="baseline" code="XYZApp.class"
           codebase="html/" model="models/HyaluronicAcid.xyz"
           pluginspage="http://java.sun.com/products/plugin/1.4/plugin-install.html">
            <NOEMBED>
                No Java 2 SDK, Standard Edition v 1.4 support for APPLET!!
            </NOEMBED>
        </EMBED>
    </COMMENT>
</OBJECT>

Because IE understands the <OBJECT> tag, it will try to launch Java Plug-in. Notice that the <COMMENT> tag is a special HTML tag understood only by IE. IE ignores text between the <COMMENT> and </COMMENT> tags. In effect, the above tags actually become:

Note that the <COMMENT> element is unique to IE. IE ignores text between the <COMMENT> and </COMMENT> elements. For IE, then, the above structure of elements looks like this:

<OBJECT classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
    width="200" height="200" align="baseline"
    codebase="http://java.sun.com/products/plugin/1.4/jinstall-14-win32.cab#Version=1,4,0,mn">
    <PARAM NAME="code" VALUE="XYZApp.class">
    <PARAM NAME="codebase" VALUE="html/">
    <PARAM NAME="type" VALUE="application/x-java-applet;jpi-version=1.4">
    <PARAM NAME="model" VALUE="models/HyaluronicAcid.xyz">
    <PARAM NAME="scriptable" VALUE="true">
</OBJECT>

This is identical to the new OBJECT tag example described above.

Now because Navigator understands neither the OBJECT nor the COMMENT elements, Navigator 4 views the above structure as follows:

<EMBED type="application/x-java-applet;jpi-version=1.4" width="200"
   height="200" align="baseline" code="XYZApp.class"
   codebase="html/" model="models/HyaluronicAcid.xyz"
   pluginspage="http://java.sun.com/products/plugin/1.4/plugin-install.html">
    <NOEMBED>
        No Java 2 SDK, Standard Edition v 1.4 support for APPLET!!
    </NOEMBED>
</EMBED>

This is identical to the new EMBED element example described above.

Thus you can use the new element structure—OBJECT element with nested EMBED element—to invoke Java Plug-in when either IE or Netcape encounters a page with an applet. The is the recommeded format to use.

Java Plug-in Anywhere

Warning!

The material in this section is out of date. It will be updated in the future. The description of the script below corresponds to the Extended option with the HtmlConverter. It is recommended that you do not use this option at this time. The Standard option is the recommended option.

In most environments, Internet or intranet, an HTML page is likely to be viewed on different browsers on different platforms. Ideally, then, you should activate Java Plug-in only on the right browser-platform combination. Otherwise, an applet should use the browser's default JVM. You can achieve this using the following Java Plug-in format:

Original APPLET element:

<APPLET code="XYZApp.class" codebase="html/" align="baseline"
    width="200" height="200">
<PARAM NAME="model" VALUE="models/HyaluronicAcid.xyz">
    No Java 2 SDK, Standard Edition v 1.4 support for APPLET!!
</APPLET>

New-style format:

The following is an example of an equivalent Java Plug-in format. (The example includes comments.)

<!-- The following code is specified at the beginning of the <BODY> tag. -->
<SCRIPT LANGUAGE="JavaScript"><!--
    var _info = navigator.userAgent;
    var _ns = false;
    var _ie = (_info.indexOf("MSIE") > 0 && _info.indexOf("Win") > 0
        && _info.indexOf("Windows 3.1") < 0);
//--></SCRIPT>
<COMMENT><SCRIPT LANGUAGE="JavaScript1.1"><!--
    var _ns = (navigator.appName.indexOf("Netscape") >= 0
        && ((_info.indexOf("Win") > 0 && _info.indexOf("Win16") < 0
        && java.lang.System.getProperty("os.version").indexOf("3.5") < 0)
        || _info.indexOf("Sun") > 0));
//--></SCRIPT></COMMENT>

<!-- The following code is repeated for each APPLET tag -->
<SCRIPT LANGUAGE="JavaScript"><!--
    if (_ie == true) document.writeln('
<OBJECT
    classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
    width="200" height="200" align="baseline"
codebase="http://java.sun.com/products/plugin/1.4/jinstall-14-win32.cab#Version=1,4,0,mn">
    <NOEMBED><XMP>');
    else if (_ns == true) document.writeln('
<EMBED
    type="application/x-java-applet;jpi-version=1.4" width="200" height="200"
    align="baseline" code="XYZApp.class" codebase="html/"
    model="models/HyaluronicAcid.xyz"
    pluginspage="http://java.sun.com/products/plugin/1.4/plugin-install.html">
    <NOEMBED><XMP>');
//--></SCRIPT>
   <APPLET code="XYZApp.class" codebase="html/" align="baseline"
        width="200" height="200">
</XMP>
    <PARAM NAME="java_code" VALUE="XYZApp.class">
    <PARAM NAME="java_codebase" VALUE="html/">
    <PARAM NAME="java_type" VALUE="application/x-java-applet;jpi-version=1.4">
    <PARAM NAME="model" VALUE="models/HyaluronicAcid.xyz">
    <PARAM NAME="scriptable" VALUE="true">
    No Java 2 SDK, Standard Edition v 1.4 support for APPLET!!
</APPLET></NOEMBED></EMBED>
</OBJECT>

<!--
    <APPLET code="XYZApp.class" codebase="html/" align="baseline"
        width="200" height="200">
    <PARAM NAME="model" VALUE="models/HyaluronicAcid.xyz">
    No Java 2 SDK, Standard Edition v 1.4 support for APPLET!!
    </APPLET>
-->

Although this tag seems complicated compared to the old APPLET tag, it is not. Most of the Java Plug-in tag is the same regardless of the applet used. For the majority of cases, a webmaster can copy and paste the Java Plug-in tag.

The first block of the script extracts the browser and platform. You must determine the browser and platform on which the applet is running. You do this by using JavaScriptTM to extract first the browser name, then the platform. This is done once per HTML document.

The second block of the script replaces the APPLET tag. You must replace each APPLET tag with a similar block of code. The script replaces the APPLET tag with either an EMBED tag or OBJECT tag, depending on the browser. You use the OBJECT tag for IE and the EMBED tag for Netscape Navigator. Finally, the original APPLET tag is included as a comment at the end. It is always a good idea to keep the original APPLET tag in case you want to remove the Java Plug-in invocation.

The first JavaScript establishes the browser and the platform on which the browser is running. You must do this because, currently, Java Plug-in supports only Windows 95, Windows 98, Windows NT 4.0, and Solaris. Note that Windows NT 3.51 is the only Win32 platform that Java Plug-in does not support. Java Plug-in should be invoked only on the supported browser and platform. The script sets the variable _ie to true if the browser is Internet Explorer. It sets the variable _ns to true if the browser is Navigator. (Note that all variable names in the JavaScript start with "_". This is done to avoid conflicting with other JavaScript variables in the same page.)

To detect the right browser, the JavaScript evaluates three strings that are within the JavaScript's Navigator object: userAgent, appVersion, and appName. These strings contain information about the browser and the platform. By looking at some examples of the string userAgent, you can see how to evaluate userAgent and use it to determine the browser. The following are some examples of the userAgent string for different platforms as it appears in Internet Explorer.

Platform and Browser | JavaScript's Navigator.userAgent string
Windows 2000 w/IE 5.0 | "Mozilla/4.0 (compatible; MSIE 5.01; Window NT5.0)
Windows NT 4.0 w/IE 4.0 | "Mozilla/4.0 (compatible; MSIE 4.0; Windows NT)"
Windows NT 4.0 w/IE 3.02 | "Mozilla/2.0 (compatible; MSIE 3.02; Windows NT)"
Windows 95 w/IE 4.0 | "Mozilla/4.0 (compatible; MSIE 4.0; Windows 95)"
Windows 95 w/IE 3.02 | "Mozilla/2.0 (compatible; MSIE 3.02; Windows 95)"
Windows NT 3.51 w/IE 4.0 | "Mozilla/4.0 (compatible; MSIE 4.0; Windows 3.1)"
Windows 3.1 w/IE 4.0 | "Mozilla/4.0 (compatible; MSIE 4.0; Windows 3.1)"
Windows NT 4.0 w/Navigator 4.04 | "Mozilla/4.04 [en] (WinNT; I)"
Windows NT 4.0 w/Navigator 3.04 | "Mozilla/3.04 (WinNT; I)"
Windows NT 3.51 w/Navigator 4.04 | "Mozilla/4.04 [en] (WinNT; I)"
Windows NT 3.51 w/Navigator 3.04 | "Mozilla/3.04 (WinNT; I)"
Windows 95 w/Navigator 4.03 | "Mozilla/4.03 [en] (Win95; I)"
Windows 95 w/Navigator 3.03 | "Mozilla/3.03 (Win95; I)"
Solaris 2.6 w/Navigator 4.02 | "Mozilla/4.02 [en] (X11; l; SunOS 5.6 sun4u)

Note that in each case the substring "MSIE" is always in the userAgent string in Internet Explorer. Also, the userAgent string in IE under Windows 3.1 and Windows 3.51 would contain the substring "Windows 3.1" because IE in these platforms is 16-bit. While IE 4 is also available on Solaris and Mac, in these versions the userAgent string does not contain the substring "Win". In addition, IE on Windows CE does not support JavaScript. This can be summarized as follows:

userAgent string / Browsers | Windows 3.1 w/ IE 3/4 | Windows NT 3.51 w/ IE 3/4 | Windows 95 w/ IE 3/4 | Windows NT 4.0 w/ IE 3/4 | Windows CE w/ IE | Mac w/ IE | UNIX w/ IE | Other browsers on any platform
contains "MSIE" | X | X | X | X |  | X | X |
contains "Win" | X | X | X | X |  |  |  |
does not contain "Windows 3.1" |  |  | X | X |  | X | X | X

The above table shows that only Windows 95 and Windows NT 4.0 with IE can pass the Java Plug-in browser and platform requirements. However, this logic makes no assumptions about future releases of IE or future releases of Windows with IE. As long as the userAgent string contains "MSIE" and "Win", the above code should work in future releases of IE on Win32.

The above logic summarizes into the following:

<SCRIPT LANGUAGE="JavaScript"><!--
    var _info = navigator.userAgent;
    var _ie = (_info.indexOf("MSIE") > 0 && _info.indexOf("Win") > 0
            && _info.indexOf("Windows 3.1") < 0);
//--></SCRIPT>

It is harder to detect Navigator on the right platform. Using just JavaScript, there is no way to determine if the browser is running on the Windows NT 3.51 or Windows NT 4.0 operating platform. (Refer to the above table and examine the userAgent string. Notice that the userAgent strings in Windows NT 3.51 and Windows NT 4.0 operating platforms are the same in Navigator.) It is important to make this distinction because Java Plug-in supports only the Windows NT 4.0 operating platform. To run Java Plug-in on the right platform, you must use LiveConnect in Navigator to determine the OS version number. This can be summarized as follows:

Testing logic / Browsers | Windows 3.1 w/ NS 3/4 | Windows NT 3.51 w/ NS 3/4 | Windows 95 w/ NS 3/4 | Windows NT 4.0 w/ NS 3/4 | NS on Solaris | IE on Solaris | NS on other platform | IE on other platform | Other browsers on any platform
appName contains "Netscape" | X | X | X | X | X |  | X |  |
userAgent contains "Win" | X | X | X | X |  |  |  | X |
userAgent does not contain "Win16" |  | X | X | X |  |  | X | X |
os.version does not contain 3.5 | X |  | X | X |  |  | Depends on OS |  |
userAgent contains "Sun" |  |  |  |  | X | X |  |  |

The above logic translates into the following code:

<SCRIPT LANGUAGE="JavaScript"><!--
    var _info = navigator.userAgent; var _ns = false;
//--></SCRIPT>
<COMMENT><SCRIPT LANGUAGE="JavaScript1.1"><!--
     var _ns = (navigator.appName.indexOf("Netscape") >= 0
            && ((_info.indexOf("Win") > 0  && _info.indexOf("Win16") < 0
            && java.lang.System.getProperty("os.version").indexOf("3.5") < 0)
            || _info.indexOf("Sun") > 0));
//--></SCRIPT></COMMENT>

Referring to the previous table, note that only Windows 95, Windows NT 4.0, and Solaris operating environments with Navigator pass all the tests. Because LiveConnect is used to get the OS version number and only Navigator supports LiveConnect, a JavaScript that accesses LiveConnect will not be understood by IE. To prevent this from causing a problem, you block out this piece of the script using the COMMENT tag since COMMENT is an IE-specific comment tag. The text between the COMMENT tag is ignored by IE but not by Navigator. In addition, you must specify the script language as JavaScript1.1 to block this out if the browser is Navigator 2.

At this point, the above logic for IE and Navigator summarizes to a script that should look as follows:

<!-- The following code is specified at the beginning of the <BODY> tag. -->
<SCRIPT LANGUAGE="JavaScript"><!--
    var _info = navigator.userAgent; var _ns = false;
    var _ie = (_info.indexOf("MSIE") > 0 && _info.indexOf("Win") > 0
            && _info.indexOf("Windows 3.1") < 0);
//--></SCRIPT>
<COMMENT><SCRIPT LANGUAGE="JavaScript1.1"><!--
    var _ns = (navigator.appName.indexOf("Netscape") >= 0
           && ((_info.indexOf("Win") > 0 && _info.indexOf("Win16") < 0
           && java.lang.System.getProperty("os.version").indexOf("3.5") < 0)
           || _info.indexOf("Sun") > 0));
//--></SCRIPT></COMMENT>

Remember that this block of JavaScript should be put at the top of the <BODY> of the HTML file. It is put at the top so that other JavaScripts can reference the variables _ie and _ns. This JavaScript is the same in all HTML files, and it is only needed once for each HTML body.

The second block of HTML tags are actually the corresponding OBJECT and EMBED tags that are mapped from the data in the APPLET tag. Note that JavaScript outputs the OBJECT tag when the browser is IE running on the Windows 95, Windows 98 or Windows NT 4.0 operating environments. If the browser is Navigator 3/4 on Windows 95, Windows 98, Windows NT 4.0, or Solaris operating environments, then JavaScript also outputs the EMBED tag, though with a slightly different syntax. Recall that the mechanism for detecting the browser and the platform has been described in the above section. (Tags <!-- and --> are used for comments in HTML.)

Original APPLET tag:

<APPLET code="XYZApp.class" codebase="html/" align="baseline"
    width="200" height="200">
<PARAM NAME="model" VALUE="models/HyaluronicAcid.xyz">
    No Java 2 SDK, Standard Edition v 1.4 support for APPLET!!
</APPLET>

New style tag:

<SCRIPT LANGUAGE="JavaScript"><!--
    if (_ie == true) document.writeln('<OBJECT
    classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
    width="200" height="200" align="baseline"
codebase="http://java.sun.com/products/plugin/1.4/jinstall-14-win32.cab#Version=1,4,0,mn">
    <NOEMBED><XMP>');
    else if (_ns == true) document.writeln('<EMBED
    type="application/x-java-applet;jpi-version=1.4" width="200" height="200"
    align="baseline" code="XYZApp.class" codebase="html/"
    model="models/HyaluronicAcid.xyz"
    pluginspage="http://java.sun.com/products/plugin/1.4/plugin-install.html">
    <NOEMBED><XMP>');
//--></SCRIPT>
    <APPLET code="XYZApp.class" codebase="html/" align="baseline"
        width="200" height="200"></XMP>
    <PARAM NAME="java_code" VALUE="XYZApp.class">
    <PARAM NAME="java_codebase" VALUE="html/">
    <PARAM NAME="java_type" VALUE="application/x-java-applet;jpi-version=1.4">
    <PARAM NAME="model" VALUE="models/HyaluronicAcid.xyz">LUE="models/HyaluronicAcid.xyz">
    <PARAM NAME="scriptable" VALUE="true">
        No Java 2 SDK, Standard Edition v 1.4 support for APPLET!!
    </APPLET></NOEMBED></EMBED></OBJECT>

Note that the original APPLET tag is also mapped in the new Java Plug-in tag. This is done because Java Plug-in is intended to be used only on supported platforms. Leaving the APPLET tag in the script ensures that browsers that do not support Java Plug-in, or browsers that do not support JavaScript can gracefully handle the applet using the default JVM. HotJava Browser, IE, and Navigator on non-Java Plug-in supported platforms, or browsers without JavaScript support, read the above tags as follows:

<APPLET code="XYZApp.class" codebase="html/" align="baseline"
    width="200" height="200"></XMP>
<PARAM NAME="java_code" VALUE="XYZApp.class">
<PARAM NAME="java_codebase" VALUE="html/">
<PARAM NAME="java_type" VALUE="application/x-java-applet;jpi-version=1.4">
<PARAM NAME="model" VALUE="models/HyaluronicAcid.xyz">
<PARAM NAME="scriptable" VALUE="true">
   No Java 2 SDK, Standard Edition v 1.4 support for APPLET!!
</APPLET></NOEMBED></EMBED></OBJECT>

These browsers ignore the tags </XMP>, </OBJECT>, </EMBED>, and </NOEMBED> as well because there is no corresponding <XMP>, <OBJECT>, <EMBED>, and <NOEMBED> tags. Because Java Plug-in is targeted for features in the Java 2 SDK, Standard Edition v 1.4 or future releases, those browsers without full Java 2 SDK 1.4 support and who do not support Java Plug-in will display the message "No Java 2 SDK, Standard Edition v 1.4 support for APPLET".

Unlike the previous examples, the mapped PARAM names contain java_code, java_codebase, and java_type instead of code, codebase, and type. This is necessary because specifying code and codebase in the <PARAM> inside the <APPLET> and </APPLET> tag causes problems in some browsers.

IE on Windows reads the tags as follows:

<OBJECT classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
    width="200" height="200" align="baseline"
codebase="http://java.sun.com/products/plugin/1.4/jinstall-14-win32.cab#Version=1,4,0,mn">
    <NOEMBED><XMP>
    <APPLET code="XYZApp.class" codebase="html/" align="baseline"
        width="200" height="200"></XMP>
    <PARAM NAME="java_code" VALUE="XYZApp.class">
    <PARAM NAME="java_codebase" VALUE="html/">
    <PARAM NAME="java_type" VALUE="application/x-java-applet;jpi-version=1.4">
    <PARAM NAME="model" VALUE="models/HyaluronicAcid.xyz">
    <PARAM NAME="scriptable" VALUE="true">
        No Java 2 SDK, Standard Edition v 1.4 support for APPLET!!
    </APPLET></NOEMBED></EMBED>
</OBJECT>

Be careful when you use the <XMP> tag. Because IE renders the <OBJECT> tag, you must disable the <APPLET> tag. If not disabled, two applets will simultaneously show up in the browser—one applet will be running in Microsoft's JVM, and the other will be running in Sun's JVM using Java Plug-in. The <XMP> tag provides a solution. The <XMP> and </XMP> tags basically transform any HTML tag that occurs between them into a stream of static text. In the above example, the <XMP> and </XMP> tags cause the browser to treat the <APPLET> tag as static text instead of an HTML tag. Because the browser ignores any static text between the <OBJECT> tag and the <PARAM> tag, the above tags actually become:

<OBJECT classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
    width="200" height="200" align="baseline"
codebase="http://java.sun.com/products/plugin/1.4/jinstall-14-win32.cab#Version=1,4,0,mn">
    <PARAM NAME="java_code" VALUE="XYZApp.class">
    <PARAM NAME="java_codebase" VALUE="html/">
    <PARAM NAME="java_type" VALUE="application/x-java-applet;jpi-version=1.4">
    <PARAM NAME="model" VALUE="models/HyaluronicAcid.xyz">
    <PARAM NAME="scriptable" VALUE="true">
        No Java 2 SDK, Standard Edition v 1.4 support for APPLET!!
</OBJECT>

This is identical to the OBJECT tag example outlined above. Note that the <OBJECT> tag ignores the <NOEMBED>, </NOEMBED>, and </EMBED> tags.

Navigator on Windows operating environments reads tags as follows:

<EMBED type="application/x-java-applet;jpi-version=1.4" width="200" height="200"
    align="baseline" code="XYZApp.class" codebase="html/"
    model="models/HyaluronicAcid.xyz"
    pluginspage="http://java.sun.com/products/plugin/1.4/plugin-install.html">
<NOEMBED><XMP>
    <APPLET code="XYZApp.class" codebase="html/" align="baseline"
        width="200" height="200"></XMP>
    <PARAM NAME="java_code" VALUE="XYZApp.class">
    <PARAM NAME="java_codebase" VALUE="html/">
    <PARAM NAME="java_type" VALUE="application/x-java-applet;jpi-version=1.4">
    <PARAM NAME="model" VALUE="models/HyaluronicAcid.xyz">
    <PARAM NAME="scriptable" VALUE="true">
        No Java 2 SDK, Standard Edition v 1.4 support for APPLET!!
    </APPLET></NOEMBED></EMBED></OBJECT>

Note that the <XMP> tag is used again in the <EMBED> tag to also disable the <APPLET> tag. The <EMBED> tag ignores the <PARAM> and </OBJECT> tags as well. In effect, the above tags actually become:

<EMBED type="application/x-java-applet;jpi-version=1.4" width="200" height="200"
    align="baseline" code="XYZApp.class" codebase="html/"
    model="models/HyaluronicAcid.xyz"
    pluginspage="http://java.sun.com/products/plugin/1.4/plugin-install.html">
<NOEMBED>
        No Java 2 SDK, Standard Edition v 1.4 support for APPLET!!
</NOEMBED>
</EMBED>

This is identical to the EMBED tag example outlined above.

You can use the combined OBJECT-EMBED-JavaScript tag to activate Java Plug-in in the right browser on the right platform. This combined tag is complicated and it should be used only if your HTML page is browsed by users in a heterogenous environment.

Summary

This document describes the OBJECT tag and EMBED tag styles used by Java Plug-in. It focuses on the conversion from an APPLET tag to the OBJECT and EMBED tags. Currently, HTML 4.0 suggests that the OBJECT tag is the best way to insert Java applets and JavaBeans components into a HTML page. This document will be updated in the near future should there be a need to convert the OBJECT tag to the Java Plug-in tag style. Information disclosed in this document is intended to assist ISVs for writing HTML migration tools and to assist webmasters with Java Plug-in migration. The tag style described in this document is subject to change in the future.

Note that the use of Java Plug-in is not limited to the tag styles described in this document. In fact, webmasters are encouraged to modify the tag style or mix the tag with JavaScript to fit their needs. As long as the described OBJECT tag is used in IE and EMBED tag is used in Navigator, there should be no problems running Java Plug-in. Currently, there are several conversion templates shipped with the Java Plug-in HTML converter. Webmasters may find one template better than others for their needs, and are encouraged to modify these templates themselves if necessary.


Using the Conventional APPLET Tag

This section includes the following topics:

  • Support for the APPLET Tag
  • Compatibility with the OBJECT Tag
  • Updating Old Class Files
  • Other Enhancements

Support for the APPLET Tag

JavaTM Plug-in now supports the HTML APPLET tag for launching applets. Users may configure their browsers so that Sun's JRE is the default runtime environment for handling APPLET tags.

Notes

  1. The use of the APPLET tag is supported on all supported operating systems and browser (see Supported System Configurations) with the exception of Netscape 4.7x, which is only supported on Solaris.
  2. Even though Java Plug-in now supports the APPLET tag, it does not support applets that make use of proprietary technologies. Examples of such technologies are:
    • CAB files
    • Authenticode signing
    • Java Moniker
  3. With the conventional applet format, use of an attribute named object with a PARAM element will cause an exception with the Sun VM: 'Either "code" or "object" should be specified, but not both.'. With the Microsoft VM, no exception will be thrown. This is a compatibility issue. To avoid the exception with the Sun VM, do not use an attribute named object with a PARAM element in an applet.

Compatibility with the OBJECT Tag (Internet Explorer on Windows Platform)

This release of Java Plug-in supports the use of APPLET tags for launching applets. However, it is also fully backward compatible with previous Java Plug-in releases in its support of the OBJECT tag for launching applets in Internet Explorer running on the Windows platform. As before, developers have the option of using the HTML Converter to set up their applet web pages to use the OBJECT tag.

For more information about using OBJECT tags to launch applets on Java Plug-in, see Using OBJECT, EMBED and APPLET Tags in Java Plug-in and Using the HTML Converter to Convert Applet Tags for Java Plug-in.

Updating Old Class Files

In some cases, the new Java Runtime Environment associated with this Java Plug-in release will not run class files that were generated with old compilers. The usual symptom is a java.lang.ClassFormatError that the virtual machine throws when it attempts to load such a class file. This failure has nothing specifically to do with the changes in this release. Rather, old bytecode compilers did not strictly adhere to proper class-file format in all situations when generating class files. Recent virtual machines are implemented to be strict in enforcing proper class file format, and this can lead to errors when they attempt to load old, improperly formatted class files. Some typical problems in some older class files are (this list is not exhaustive):

  • There are extra bytes at the end of the class file;
  • The class file contains method or field names that do not begin with a letter;
  • The class attempts to access private members of another class;
  • The class file has other format errors, including illegal constant pool indices and illegal UTF-8 strings;
  • Some early (third-party) bytecode obfuscators produced class files that violated proper class-file format.

You can avoid this type of problem by recompiling your classes with the Javac bytecode compiler from the current JDK. If you choose to use a third-party obfuscator, be sure to use one that produces class files that respect proper class-file format.

For additional information, see the Java Upgrade Guide in the Java Deployment Guide.

Other Enhancements

In addition to the support for the APPLET tag described above, the Java Plug-in has many performance and architecture enhancements that will make it more suitable for widespread use on consumer client machines that typically are not as powerful as client platforms in an enterprise environment. Some of these enhancements are summarized below.

Memory management

  • Dynamic maximum heap size is scaled down from 128 MB to 96MB to avoid unnecessary paging on the system.
  • Classloader implementation has been tuned to allow memory to be reclaimed more often by the garbage collector.
  • Potential memory leak issue is addressed by using JNI/COM smart pointers in implementation.

Performance

  • Applet download time is significant reduced by relying on browser caching when possible. No connection will be opened on the server side unless it is absolutely necessary.
  • Applet lifecycle is controlled asynchronously to allow very fast page switch.
  • Sped up classloader object reclaim by removing its finalize() method.
  • HTTPS read has been made significantly faster by increasing buffer size.
  • HTTPS calls are significant faster by statically linking Microsoft's Wininet instead of dynamic function lookup every time.
  • JavaScript performance is greatly enhanced by eliminating BeanInfo lookup over the network.
  • Java Console performance is enhanced by using the Console Writer thread to avoid blocking System.out and System.err when possible.

Design

  • Default JavaScript/Java interaction is changed from "not-scriptable" to "scriptable", allowing any applets running through the APPLET tag to be used from JavaScript without modification.

JDK 1.1 compatibility

  • Java Plug-in can now access the sun.audio package.
  • Some applets are compiled with compilers that don't generate proper class file format which conforms to the class-file specification. Such appletss may result in a ClassFormatError when Java Plug-in attempts to load them. To help address this problem, PluginClassLoader provides a bytecode scanner to transform bad class files to conforming on-the-fly to allow the applets to run. Currently, only bad class files with the following errors may be transformed
    • Local variable name has bad constant pool index
    • Extra bytes at the end of the class file
    • Code segment has wrong length
    • Illegal Field/Method name
    • Illegal field/method modifiers
    • Invalid start_pc/length in local var table

See also Updating Old Class Files above and Java Upgrade Guide in the Java Deployment Guide.


Versions Formats

Appendix 4: Sun-Supported Specification-Version and Implemenation-Version Formats

Specification-Version and Implementation-Version follow these rules for Sun products, and third-party products must follow the same rules for Java Plug-in to make reliable decisions about whether an extension is up-to-date or not:

The Specification-Version string will be of the form:

n1.n2[.n3]

where n1, n2, and n3 are integers, n1.n2 is the major version number, and optional n3 is the minor version number (also referred to as the maintenance version number).

The Implementation-Version will be of the same form initially but may:

  • append with a preceding underscore("_") n4n5 to indicate a patch version number (also referred to as the update version number)
  • or append with a hyphen ("-") a milestone name (ea , alpha, beta, rc ...), which may also include a trailing integer number (ea1, beta2, rc1 ...).

Both patch version number and milestone name may not be used together in the Implemenation-Version string.

The general form is as follows:

n1.n2[.n3][_<patch_number>|-<milestone_name>]

Integers (n1,n2, n3 ...), letters, dots, hyphens, and underscores , may be used in the version format as described above; no other characters ("*", "+" ...) are allowed.

Note that the Specification-Version and Implementation-Version numbers are in theory independent, though in practice they are often in sync with each other.

Examples:

Specification-Version examples: 1.3, 1.4

Implementation-Version examples: 1.3.1, 1.4.0_02, 1.4.0-beta3

While these are the rules, it is always a good idea when using a third-party extension JAR to examine its MANIFEST.MF file to see what actual values are in it. If it does not follow these rules, you may need to change your applet JAR MANIFEST.MF accordingly or alter the extension JAR.


Deva Search

Java Plug-in Search Page
Tips


About Applet Tag Support in Java Plug-in

About APPLET Tag Support in JavaTM Plug-in

Note

For more information about compatibility issues between the Microsoft VM and Sun's, see Appendix 4: Microsoft VM and Java Applet Compatibility Issues.

Q: Why should I encourage people to use the Java Platform?

A: The Java Platform is richer than its predecessors in functionality, performance, and security options. As a developer, you want the users of your software to have the most feature-complete Java platform possible so that the full range of APIs and libraries are available for your applications. If your customers are using the Java Platform, you can write more powerful, robust, and full-featured applications and applets. And with the Java Platform the performance of your code will be better too.

By using the latest Java Plug-in with APPLET tag support, you can help to ensure that clients running your applets will have the latest Java Platform.

Q: Can I continue to use OBJECT tags to call my applets?

A: Yes. Even though the Java Plug-in has been enhanced to support APPLET tags, it is fully backward compatible with existing web pages that use OBJECT tags to launch applets.

Q: Are there compatibility issues with using the Java Platform?

A: In the large majority of cases, there are no compatibility issues to be concerned about when moving from JDK 1.1 to the Java Platform. The documentation for a given Java Platform release describes all known incompatibilities, most of which are in the category of "corner cases." For example, known compatibility issues in version 1.4 of the Java Platform are described at http://java.sun.com/j2se/1.4/compatibility.html.

Some old class files generated by early bytecode compilers do not strictly conform to the proper class-file format, and the Java Runtime Environment may not load such classes.

In addition to compatibility issues between different releases of the Java platform, there is the question of incompatibilities between Sun's Java runtime environment and other Java runtime environments; e.g., the one included with some Internet Explorer browsers. Sun has made a great effort to minimize such incompatibilities. Among the steps that Sun as taken in this JRE/Java Plug-in are the following:

  • The classloader sharing policy in Java Plug-in has been changed to minimize incompatible behavior in applets that depend explicitly on the classloader sharing policy of the Microsoft VM.
  • The image and sound resource lookup sequence in Java Plug-in has been changed to give resources specified with the HTML archive paramater priority over those on the codebase URL. This change was made to minimize incompatible behavior for applets that rely explicitly on the resource lookup sequence employed by the Microsoft VM.
  • The implementation of AppletgetParameter() has been modified to strip off leading and trailing whitespace from parameters before they are returned to the applet. This is the behavior of the Microsoft VM in some Internet Explorer browsers, and this change was made to eliminate possible incompatibile behavior in applets that rely explicitly on that behavior.

Q: What security model does Java Plug-in use?

A: JRE/Java Plug-in is a product in the Java Platform family, and it uses the new Java Platform's security model. This security model is more flexible and configurable than the security model used by JDK 1.1. For more information, see the Java Platform's security documentation at http://java.sun.com/j2se/1.4/docs/guide/security/index.html.

Note that applets that rely explicitly on proprietary technology in the security model of the Microsoft VM may not work with Java Plug-in.

Q: My applet fails with a ClassFormatError. What's wrong?

A: This problem may be caused by bytecode generated by old compilers. Such bytecode may not conform to the virtual machine specification, which is more strictly enforced by recent releases of the JRE.

Q: Why doesn't Java Plug-in load my applet's cab file?

A: The Java Plug-in supports applet packaging in .jar files. It does not support the Microsoft proprietary .cab file format. Therefore any applets packaged in Microsoft's .cab file format will not load in JRE/Java Plug-in.

Q: Will my Authenticode-signed applet work with Sun's JRE/Java Plug-in?

A: No. The Sun JRE/Java Plug-in does not support Microsoft proprietary technology such as Authenicode signing and .cab file formats. Signed applets that rely on Microsoft's Authenticode technology will not load in JRE/Java Plug-in.

Q: My applet uses J/Direct, AFC, and WFC, etc. Will it work in Sun's JRE/Java Plug-in?

A: No. Libraries for these and other proprietary Microsoft technologies are not included with JRE/Java Plug-in. Applets that rely on these Microsoft proprietary technologies will not work properly when run on JRE/Java Plug-in.

Q: Why does my applet throw a NullPointerException from the AWT Dispatch Event thread?

A: The events that occur during applet startup and shutdown may differ between the Microsoft and Sun implementation of the Java platform. For example, the logic in an applet may rely on the applet being visible when Applet.start()/Applet.stop() is called. That condition may be true when the applet is run on Microsoft's implementation but may not be true on Sun's impelementation.

Applets that rely on specific events that occur during startup and shutdown on Microsoft's implementation of the Java platform may not work properly with JRE/Java Plug-in. The most common symptom of this type of problem is a NullPointerException from the AWT Dispatch Event thread.

Q: Why does my applet throw a ClassCastException from the AWT Dispatch Event thread?

A: The number of containers between the applet and the encompassing frame are different in the Microsoft and Sun implementations. Therefore, an applet that relies on the frame being at some particular level of containment in the Microsoft VM, without navigating the entire AWT hierarchical component tree, is likely to fail when run on Sun's JRE/Java Plug-in. The most common symptom of this problem is a ClassCastException from the AWT Dispatch Event thread.

Q: Does Java Plug-in support Java-JavaScript communication?

A: Yes, Java Plug-in supports basic, bidirectional Java-JavaScript communication. The following, however, is a known incompatibility.

In the Microsoft implementation, applet methods and properties exposed in JavaScript are exactly the same as the methods and fields in the applet object. In Java Plug-in, an applet's methods and properties are exposed in JavaScript through JavaBeansTM introspection, which treats the applet's fields in a different manner than the Microsoft VM. Therefore, JavaScript accessing fields in an applet object may not work the same when run on JRE/Java Plug-in.


Basics

Basic Information

This section covers the following topics:

  • Basic Information
  • Supported Features
  • Version Information

Basic Information

Q: What is Java Plug-in Software?

A: Java Plug-in Software is a software product from Sun Microsystems, Inc., that allows enterprise web managers to direct Java applets and JavaBeansTM components on their intranet web pages to run using Sun's Java Runtime Environment (JRE). With the 1.4 release of Java Plug-in, it is also allows the conventional APPLET tag to direct Java applets to use Sun's JRE. This is especially useful in browser, such Internet Explorer 6, that do not support Java.

Q: For whom is Java Plug-in Software intended?

A: Java Plug-in Software is designed for enterprise customers who want to deploy Java SDK, Standard Edition based applets on their intranet web pages, and support Microsoft Windows-, Solaris-, and Linux-based browsers in their enterprise. With the 1.4 release, it is also designed for the consumer who wants to run Java applets on a web page.

Q: Is there documentation available for Java Plug-in Software?

A: To assist in your deployment of Java Plug-in Software, Sun has made available a variety of technical documentation. Documentation regarding the HTML specifications, using Java Plug-in Software in intranet environments, how proxy configuration works, how to script applets, and much more are available from the Java Plug-in Software documentation page. For the consumer-oriented product that uses conventional APPLET tag support, you may also want to visit the Get Java Technology page and see the documentation available there.

Q: What features does Java Plug-in Software offer?

A: Java Plug-in Software delivers several key capabilities to for users of Internet Explorer or Netscape's Navigator:

  • Full Java SDK, Standard Edition
  • Full Java CompatibleTM support
  • Future-ready architecture
  • Free public download and easy install
  • Free Java Plug-in Software

Q: What is the advantage of downloading and using Java Plug-in Software rather than the browser's default JavaTM virtual machine?

A: Using Java Plug-in Software allows enterprises and consumers to:

  1. Take full advantage of Java SDK, Standard Edition functionality such as JavaBeans, JNITM, and RMI today.
  2. Develop and deploy 100% Pure JavaSM applets on Internet Explorer and Netscape Navigator browsers, and be assured that they will run reliably and consistently in both browsers.
  3. Be assured that they will receive support for the latest releases of Sun's Java platform --including the high-performance Java HotSpotTM virtual machine--in Internet Explorer and Navigator as soon as Sun releases them.
  4. Run applets in web browsers that no longer support Java.

Q: Is Java Plug-in Software included in the Java Software Development Kit (SDK), Standard Edition?

A: Yes.

Q: Does Java Plug-in Software work on platforms other than Microsoft Windows or Solaris (for example, Mac OS, AIX, Linux, HP-UX, etc.) versions of IE or Navigator?

A: Sun has made Java Plug-in Software available for porting to all operating system providers. For information about support for Java Plug-in Software on other operating systems, contact the operating system provider.

Q: What information should I provide when reporting a bug to http://java.sun.com/cgi-bin/bugreport.cgi

A: When reporting bugs against Java Plug-in Software, always include the following information:

  1. Operating system, including version number
  2. Web browser, including version number
  3. Complete output of the JavaTM Console window
  4. Network configuration information—proxy, special intranet environment, etc.
  5. Complete description of the failure/problem encountered. Include the steps required to reproduce the problem.

Supported Features

Q: Does Java Plug-in Software offer support for all the features in Java SDK, Standard Edition?

A: Yes. Java Plug-in Software uses the same JRE that users can download from Sun's web site today (see http://java.sun.com/j2se/).

Q: Is Java Plug-in Software fully compliant with the JCK (Java Compatibility Kit) test suite for Java SDK, Standard Edition?

A: Java Plug-in Software is fully compliant with the JCK test suite for Java SDK, Standard Edition.

Q: What browsers and operating systems does Java Plug-in support?

A: See Supported Operating Systems and Browsers.

Q: Does Java Plug-in Software support scripting?

A: Java Plug-in Software supports scripting of applets in Internet Explorer and Netscape 6. However, scripting is not available when using Java Plug-in Software in Navigator 4.

Q: Does Java Plug-in Software support signed applets?

A: Yes, Java Plug-in Software supports standard Java SDK, Standard Edition signed JARs and applets signed using Netscape signing tools. See the How to Sign Applets Using RSA-Signed Certificates for more details.

Q: Does Java Plug-in Software automatically recognize and use the proxy server configuration that the browser was using?

A: It can. There are in fact three options beginning with the 1.4 release. See Proxy Configuration for details.

Q: What protocol does Java Plug-in Software support over the proxy?

A: HTTP, HTTPS, FTP, Gopher, and SOCKS are supported.

Q: Does Java Plug-in Software support SSL?

A: Yes, SSL is supported through Java Secure Socket Extension (JSSE).

Q: Is there a way to pre-load Java Plug-in Software during the browser startup?

A: Internet Explorer and Netscape Navigator do not have mechanisms to support pre-loading Java Plug-in Software during startup. You can work around this limitation by providing your own startup page that launches a dummy applet using Java Plug-in Software.

Q: Can I set up Java Plug-in Software to download from an intranet web server (behind a firewall) rather than from Sun's web site?

A: Yes. For more information, see Intranet With OBJECT/EMBED Tag under Part II: Deployment Schemes.

Q: How can I open the Java Plug-in Control Panel on Microsoft Windows?

A: On the Start menu, choose Start>Settings>Control Panel, then double-click on the steaming Java cup icon labeled Java Plug-in.

Version Information

Q: How can I tell what version of Java Plug-in Software has been installed?

A: There are a couple of ways:

  • Check the version number in C:\Windows\Downloaded Program Files\Java Runtime Environment or C:\WINNT\Downloaded Program Files\
  • Open Netscape Navigator. Go to the Help>About Plugins. Check the MIME types listed under Java Plug-in. If the following exist:

    application/x-java-applet;version=1.4, you are using Java Plug-in Software 1.4

    application/x-java-applet;version=1.3, you are using Java Plug-in Software 1.3

    application/x-java-applet;version=1.2, you are using Java Plug-in Software 1.2

    application/x-java-applet;version=1.1.2, you are using Java Plug-in Software 1.1.2

    application/x-java-applet;version=1.1.1, you are using Java Plug-in Software 1.1.1

    application/x-java-applet;version=1.1, you are using Java Plug-in Software 1.1

    Note: You may see more than one if you have multiple versions of Java Plug-in installed.

Q: Can different versions of Java Plug-in Software co-exist on the same system?

A: Yes, it can be done through multi-version support. See Supporting Multiple Versions of JRE/Java Plug-in.


Developer Information

This section includes the following topics:

  • Information for Web-Page Authors
  • Information for Applet Developers
  • Information for System Administrators

Information for Web Page Authors

Q: As a web page author, how do I use Java Plug-in Software?

A: To utilize all of the features and capabilities of Java Standard Edition, web page authors must modify the page's HTML to specify the use of Sun's JRE via Java Plug-in. Sun provides a specification—Using OBJECT, EMBED and APPLET Tags in Java Plug-in—to guide web page authors on how to make these changes. In addition, Sun provides the Java Plug-in free of charge.

Q: For Windows, the above specification mentions JRE releases that can be autodownloaded via .cab files. Where do I find a complete list of such JRE releases?

A: See Autodownload Files (Windows Only).

Q: How do I specify a JAR file as part of an OBJECT or EMBED tag?

A: You can specify one or more JAR files by defining an archive, cache_archive, or cache_archive_ex parameter in the OBJECT or EMBED tag.

The archive parameter with the OBJECT tag this looks like:

<PARAM NAME="archive" VALUE="demo.jar,fred.jar">

For more information on the cache_archive and cache_archive_ex parameters, see Applet Caching.

With the EMBED tag this looks like:

<EMBED ... archive="demo.jar,fred.jar" ... >

Q: Does Java Plug-in Software support multiple JAR files in the archive attribute in the APPLET tag? If so, why can't I get this to work?

A: The archive attribute is supported in both the EMBED and OBJECT tags. The most common mistake is to put the JAR files in the wrong order. For example, if you use the Swing set with Java Plug-in and specify archive="Myjar.jar,swing.jar,...", Java Plug-in will fail to load the applet because when Myjar.jar is loaded and Java Plug-in tries to initialize the applet, swing.jar is not yet loaded. The JAR files in the archive should be in the order of dependency; since Myjar.jar depends on other JARs, it should be put at the end of the list. The other common mistake is to put spaces or paths with the JAR file lists.

Information for Applet Developers

Q: Do developers need to modify their applets in order to support Java Plug-in?

A: No. Any Java SDK, Standard Edition, 100% Pure Java applets should run unmodified using the Java Plug-in.

Q: What is the applet lifecycle in Java Plug-in Software?

A: When an applet is encountered on an HTML page, the applet will be initialized and started. When the HTML page is closed, or the back button is pushed, the applet with be stopped and destroyed immediately.

When the same HTML page is encountered again, the applet will be initialized and started again.

Q: Does Java Plug-in Software support Drag and Drop between applets and the native environment? If so, why can't I get it to work?

A: Yes, Java Plug-in Software does support Drag and Drop. You must make sure to grant the applet the correct socket permissions using policytool to use this feature. Please see the SocketPermission class documentation for more information.

Q: How can I speed up applet download time?

A: There are several ways:

  • JAR files—bundle your applets as JAR files.
  • JAR indexing—optimize the class loading process. See the JAR File Specification for details.
  • Applet caching—cache your applets in a permanent cache (see Applet Caching).

Q: How do I prevent the warning banner from covering my GUI state?

A: You should use the getInsets() method to find the size of your frame's decorative border. This includes the warning banner. For example, if you create a Frame with size 100x100, you might find it has insets [top=42,left=5,bottom=5,right=6] giving you a drawable area of 89x53. You need to position your work within the drawable area.

If you need to create a drawable area of a particular size:

  1. create and show the Frame
  2. use getInsets to find the insets' sizes
  3. figure out the desired frame size by adding your desired size to the insets
  4. then use frame.setSize() to set your frame to that size.

Q: Why does InetAddress.getLocalHost().getHostName() return localhost?

A: This is a deliberate security feature in the Java platform. Untrusted applets will not be given the real host name. Trusted applets (such as signed applets) will be given the real host name.

Information for System Administrators

Q: I would like to change the Java Plug-in setting in thousands of machines through system management tools. What should I do?

A: Java Plug-in stores user specific settings under <user.home>/.java/properties<version>. Therefore, if administrators would like to change the Java Plug-in settting globally, they may use system managment tools to update the file in all machines.

Q: Does Java Plug-in Software replace Microsoft's or Netscape's Java runtime with Sun's JRE?

A: No. Java Plug-in Software does not replace the browser's underlying virtual machine if it has one. (Netscape 6 and later versions of Internet Explorere 6 do not have a Java virtual machine.) Rather, Java Plug-in Software simply enables web-page authors to specify that Sun's JRE be used instead of the default Java runtime.

Q: We are trying to deploy Java Plug-in Software within our intranet environment. The chapter called Using OBJECT, EMBED and APPLET Tags in Java Plug-in and other documents say we should set up an installation page within our intranet for Netscape users to install Java Plug-in. What does this page do and how should we set it up?

A: The purpose of this installation page is to act as an entry point for Netscape users to install Java Plug-in Software. If a user encounters an HTML page that requires Java Plug-in, the user will get redirected to this installation page according to the pluginspage attribute in the EMBED tag. At that point, the users should be able to download and install the correct version of Java Plug-in Software for their platform. Thus, the installation page should have links to download the Java Plug-in binary.

An simple example page would look like:

<HTML>
<HEAD>
<TITLE>Java Plug-in Software Download Page</TITLE>
</HEAD>
<BODY>
<P><A HREF="ftp://myhost.com/public/jre14-win32.exe">
    Java Plug-in Software for Microsoft Windows</A>
</P>
<P><A HREF="ftp://myhost.com/public/plugin-14-solaris.bin">
        Java Plug-in Software for Solaris</A>
</P>
</BODY>
</HTML>
Depending on how your webserver is configured, you may want to consider using CGI scripting instead of FTP for the download. Contact your webmaster for more information.

Q: Why is the experience of downloading and installing Netscape Navigator different from Internet Explorer?

A: The releases of Netscape Navigator supported by Java Plug-in Software do not provide mechanisms that allow for the automatic download and installation of Java Plug-in, as in Internet Explorer. The first time Netscape Navigator comes across a web page that is enabled for Java Plug-in (the activated page), it redirects the user to another web page to download and install Java Plug-in Software on the user's system. The user must then return to the activated page to render the applet using Java Plug-in Software. From that point on, the browser automatically invokes Java Plug-in whenever it encounters an activated page.


Frequently Asked Questions

Frequently Asked Questions (FAQ)

Basic Information FAQ

Questions and answers for people unfamiliar with Java Plug-in Software. Includes information about availability, versioning and supported features.

Developer Information FAQ

Information for system administrators and people developing applets or webpages that use Java Plug-in Software.

Troubleshooting FAQ

Answers to common problems using Java Plug-in Software. Includes installation, debugging, and security information.

About Applet Tag Support in Java Plug-in

Answers questions about support for conventional applet tage support in Java Plug-in.


Troubleshooting

This section includes the following topics:

  • General Troubleshooting Issues
  • Troubleshooting Installation Issues
  • Troubleshooting Security Issues

General Troubleshooting Issues

Q. Why do I get a javax.net.ssl.SSLException (or hang or disconnect) when accessing an applet from an HTTPS site.

A. In some SSL/TLS servers you will encounter this problem if a client message is received in a format it doesn't understand or with a protocol version number that it doesn't support. The problem is on the server side. There may be several aspects of the SSL/TLS protocol that are not implemented correctly. If the server only speaks SSLv3, when a client sends a TLSv1 (aka SSLv3.1) hello the server is supposed to respond with a SSLv3 server hello (aka SSLv3.0). But the server is not doing so; hence, you get the exception (SSLException).

In Java Plug-in 1.3.x the browser's implementation of SSL was used. Netscape 4.x and Internet Explorer provide only an SSLv3.0 implementation. The problem will not be seen because in this version of Plug-in only SSLv3.0 is used.

In Java Plug-in 1.4.0 the JSSE implementation of TLS/SSL was used. By default, JSSE enables the TLSv1, SSLv3, and SSLv2Hello protocols. In this version of Plug-in TLSv1 will be used, and this problem may be seen on servers with incorrect protocol implementations.

Below are some ways to work around this problem. Turn off the TLSv1 protocol and use only SSLv3.

1. In the Java Plug-in Control Panel (Advanced tab) specify:

-Dhttps.protocols="SSLv3,SSLv2Hello"

2. Set the system property:

System.setProperty("https.protocols", "SSLv3");

3. If you have access to the socket, you can do this:

socket.setEnabledProtocols("SSLv3");

In Java Plug-in 1.4.1 the SSLv3 and SSLv2Hello protocols are used by default. Because most browsers use SSLv3 by default and most web servers support it—and to avoid seeing the above problem—the change was made to this version of the Plug-in. Users that need to use TLSv1 should set the https.protocols settings.

Q: Is there a way, other than restarting the browser, to force the JVM to check the server for modified JAR files for a page with an applet?

A: Modified jar files will be downloaded from the server when a page with an applet is refreshed or revisited if you first do this: type "x" in the Java Console to clear the Classloader cache.

Q: When trying to play a game on http://games.yahoo.com I get a ControlAccessException. What is the problem and is there a workaround?

A: The problem is that the game applet needs permission to connect to one or more servers, and it is being denied permission for security reasons. The workaround is this: Add the following to your java.policy file:

grant codeBase "http://download.yahoo.com/games/clients/" {
      permission java.net.SocketPermission "*","connect";};

java.policy is located in <JRE installation directory>/Java/j2re1.4.0/lib/security/.

Q: How do I get Nescape to find my plugin when I've downloaded and installed the Java SE, which includes Java Plug-in?

A: Set the NPX_PLUGIN_PATH envirronement variable to the location of the Java Plug-in (the directory in which the javaplugin.so file is located):

NPX_PLUGIN_PATH=$JAVAHOME/jre/plugin/sparc/ns4 for Netscape 4
NPX_PLUGIN_PATH=$JAVAHOME/jre/plugin/sparc/ns6 for Netscape 6

Q: I can't get Java Plug-in software to install in an intranet environment when I place it on our Netscape Enterprise 3.0 SuiteSpot web server. Why not?

A: We have reports that the Netscape Enterprise 3.0 SuiteSpot Webserver is unable, at least in some circumstances, to serve up .exe files. One apparent workaround has been to configure the HTML so that the Java Plug-in product is installed by a Visigenic Orb Gatekeeper, which also functions as a web server.

Q: I'm having trouble debugging with Java Plug-in Software. Do you have any tips?

A: In some circumstances, Java Plug-in Software will use a different debug connection address than expected. This occurs when Java Plug-in Software is loaded into the Explorer.exe process running in one of the following configurations:

  • Windows 95/NT running Active Desktop with IE4 or later
  • Windows 98/ME/2000

Java Plug-in Software is loaded into the Explorer.exe process when an HTML page containing the OBJECT tag is viewed in the following ways:

  • via preview in an Explorer folder, if the desktop settings allow web content to be viewed in folders (in other words, if the View->As Web Page menu option is checked)
  • via Internet Explorer, if the Microsoft Internet settings for "Launch browser windows in a separate process" or "Browse in a new process" are not set
  • via a web page shown on the Active Desktop

This can cause problems when debugging Java applets, since no two processes should use the same debug connection address. (See How to Debug Applets in Java Plug-in in Debugging Support regarding setting of the connection address.). If the Explorer.exe process has already claimed the debug connection address, and the Netscape.exe or Iexplorer.exe tries to use it, debugging problems may result.

Java Plug-in Software avoids this complication when loaded into the Explorer.exe process by prepending the debug connection address specified in the Control Panel with the string Explorer.

For example, if the default connection address set at the time of Java Plug-in Software installation is 2502, when running under Explorer.exe it is actually set to Explorer:2502.

When running JDB from the Java SDK you should specify

jdb -attach Explorer:2502

to attach to the JVM loaded into the Explorer.exe process.

Q: My applet is no longer scriptable in Internet Explorer with Java Plug-in. Why?

A: With Java Plug-in Software 1.3 a scriptable tag must be included and given a value of "true" in order for an applet to be scriptable. See the Using OBJECT, EMBED and APPLET Tags in Java Plug-in for more information.

Q: Why am I having problems using some standard extensions/optional packages?

A: Only extensions installed in the <jre>\lib\ext directory will be added to the classpath. Extensions installed in directories pointed to by the java.ext.dirs system property will not be added.

Q: Java Plug-in used to work with my Navigator 4.0.x browser. But when I upgraded to Navigator 4.5 and re-installed Java Plug-in, it does not work with Navigator 4.5. Why?

A: It has been reported that Navigator 4.5 may not install the user profile properly during installation. As a result, Java Plug-in Software may not read the correct user profile setting. To make sure the user profile setting is correct, check the following:

  • HKEY_LOCAL_MACHINE\Software\Netscape\Netscape Navigator\Users\CurrentUser
  • HKEY_LOCAL_MACHINE\Software\Netscape\Netscape Navigator\Users\<UserName>\DirRoot
Make sure that these two registry keys exist and <DirRoot> points to an existing user profile. If any of the registry keys are missing or incomplete, use the User Profile Manager tool to recreate your profile.

Q: We are trying to use Java 3D with Java Plug-in but it doesn't work at all. Why?

A: Java 3D comes with various packages. Installing it incorrectly may inadvertently disable Java Plug-in or cause it to fail. Follow these general instructions for using Java 3D and Java Plug-in Software:

  1. Install Java Plug-in first.
  2. Install Java 3D in a new directory. Do not install it over the existing Java SDK, Standard Edition/JRE. See this page for installation instructions.
  3. Install a version of the SDK/JRE that is appropriate for Java 3D if one is not already installed on your computer.
  4. In the Java Plug-in Control Panel, select the appropriate version of the SDK/JRE..
The Java 3D demos should now run within Java Plug-in.

Q: Some web/proxy servers require users to login for authentication. When I used the browser to access this server with Java Plug-in, two login dialog boxes appeared. Why?

A: Normally Java Plug-in will download the applets using its own connection. If the web/proxy server requires login, the browser will first encounter the request and bring up a login dialog box. After the HTML page is downloaded, Java Plug-in will try to download the class or jar files for the applet. However, since Java Plug-in has no access to the login information that the browser previously obtained, it will bring up its own login dialog box.

Q: When I tried to deploy Java Plug-in in the intranet and put the binaries on the internal web server, IE doesn't download and install Java Plug-in Software when it encounters the converted page. What's going on?

A: You may want to check that the CODEBASE in the OBJECT tag actually has the correct URL for Java Plug-in. Also, turning off execute privileges on the directory in which you put the Java Plug-in Software executable may help.

Q: I am experiencing problems getting an applet to render using Java Plug-in Software. What is the cause of this?

A: While this may be due to a variety of circumstances unique to your operating environment, a frequent cause of this problem is a security exception.

    Problem: Your network does not support DNS (Domain Name Service). In order to perform certain security checks, the applet SecurityManager needs to be able to find the IP address from which your applet was downloaded. If DNS is not available, these security checks may fail.

    Workaround: When visiting the target web page, specify an IP address rather than a hostname in the URL. For example, use "http://123.45.35.128/fred.html".

Q: I changed my browser setting while Java Plug-in Software was running, but it still uses the old settings after the change. Why?

A: The browser settings are read in by Java Plug-in when it is started. These settings are valid throughout the lifetime of the browser session. To make Java Plug-in read in the new settings, restart your browser. If you are running Active Desktop with Java Plug-in, you need to restart the computer.

Q: When I loaded my applet, it said "noninit" or "applet not initialized" in the browser's status bar. How can I identify the cause of the problem?

A: Follow these steps:

  1. Look at the error message in the Java Console.
  2. If you are accessing the applet through the network, make sure the proxy info shown in the Java Console is correct.
  3. Make sure all the class/JAR files are in the right directory.
  4. Make sure the converted HTML page is correct.
  5. Try the unconverted page with AppletViewer on the same machine. If it works, check 3, 4, and 5 again.

Q: When I try to use the AppletClassLoader with Java Plug-in Software, it crashes with a null pointer exception in IE4 but works fine in Netscape. Why does this happen? Is there a way to make it work correctly in IE4?

A: Java Plug-in Software in IE4 tries to load <YourAppletName>BeanInfo.class even if your applet is not a bean. There is a bug in Java SDK, Standard Edition v 1.3 in the AppletClassLoader that occurs when trying to load nonexistent classes. To prevent this problem, create an empty <YourAppletName>BeanInfo.class.

Q: Why does Java Plug-in Software sometimes crash Internet Explorer but not Netscape Navigator?

A: In certain circumstances, bad HTML will cause the browser to crash. One example is the absence of an </XMP> tag. Please make sure your HTML is correct.

Another possibility is that the plug-in was disabled using the Control Panel before you accessed a Plug-in-enabled page. Please check your settings to make sure the Plug-in is enabled.

Q: My applet used to create a top-level frame that would remain visible through page switches. When I upgraded to Java Plug-in this no longer occurs. Why?

A: In Java Plug-in Software, applets are stopped and destroyed during page switches. All the visible components should be destroyed as well. There has been an enhancement in Java SDK that makes sure that all of the resources of the applet are properly released, including the top-level frame.

Troubleshooting Installation Issues

Q: I am trying to install the Java Plug-in on a network drive. However, it doesn't install. Why?

A: If your network drive is protected or read-only, you will not be able to install the Java Plug-in. Contact your system administrator for more details.

Q: I am trying to install Java Plug-in. However, whenever the install program tries to install the Java Plug-in for Netscape Navigator, it displays an error. My Navigator is on a network drive. Is there a way to fix this?

A: If your Navigator is installed on a network drive, you may not have permission to install the plugin DLL on the Navigator Plugins directory. Contact your system administrator for more details.

Q: I'm having trouble installing the Java Plug-in on my Microsoft Windows machine. I see the error: "An application error has occurred and an application error log is being generated. Exception: access violation ..." What might be the problem?

A: The Microsoft Window installation (using Installshield's installer) may not work if you have Quarterdeck's Cleansweep product running in the background.

Q: When I reboot after I uninstalling Java Plug-in software, I get a dialog box warning that a .cpl file has been removed. What is this?

A: If the Java Plug-in Control Panel is open while you are uninstalling the plug-in, plugincpl.cpl will not be removed as it is locked when the Control Panel folder is open.

Q: When I uninstall Java Plug-in, the Microsoft Window Plugin for Netscape seems to stay on the machine. How can I remove that?

A: Delete the NPJPI<modified version number>.dll from the Netscape Plugins directory. For example, for Java Plug-in 1.4.0, delete NPJPI140.dll from the Plugins directory.

Troubleshooting Security Issues

Q: I have some security-related issues in my applet. How do I debug it?

A: You can enable the java.security.debug property to enable trace messages from the security system. Please see java.security.debug Property in the chapter called Debugging Support for more information.

Q: When downloading applets from the Internet, an AccessControlExcpetion is thrown. However, when the applet is located on the intranet, it works. Why?

A: To prevent DNS spoofing, a security check in Java Plug-in requires the host name to be resolved into an IP address before any connection is made from the applet. However, the side-effect of this security check is to require the intranet DNS server to be able to resolve any external host name from the Internet. For some customers, this is not the way their DNS servers are setup within the enterprise, and it causes Java Plug-in to fail. To resolve this issue, there are several options:

  1. Modify the HTML page of the applet, so the codebase and document base of the applet contains IP addresses instead of host names. This will avoid Java Plug-in performing a DNS lookup for the host name.
  2. Set trustProxy to true in Java Plug-in. By setting this property, Java Plug-in will trust the proxy to perform a proper DNS lookup and return information to Java Plug-in from trusted hosts. For intranet customers whose proxy servers are setup internally and can be trusted, this property may be used. This property may be specified as -DtrustProxy=true in the Java Plug-in Control Panel.

    Note that this property should be set by administrator, as setting this property improperly with an untrusted proxy server may expose the client machines to DNS spoofing. This property is similar to the security.lower_java_network_security_by_trusting_proxies property supported by Netscape Navigator's JVM.

Q: I keep getting a ClassFormatError exception when my webpage is loaded with HTTPS in Netscape Navigator. Why?

A: This is caused by an applet specifying a nonexistent .jar or .class file in the EMBED tag. Due to limitation of what information can be returned via HTTPS in Navigator, the web server's "File Not Found" HTML page is returned instead of the appropriate status. This HTML page is treated as a .class file and that causes the exception.

Q: I tried to run an RSA signed applet with Java Plug-in, but it is being treated as an untrusted applet. What is the problem?

A: There are several possibilities:

  • Your applet is not signed properly. Use the Netscape's signtool or Sun's jarsigner to verify it.
  • Your RSA certificate and its certificate chain may have expired.
Please see our How to Sign Applets Using RSA-Signed Certificates for details.

Q: Why do I get a yellow banner across my applet frame when using Java Plug-in?

A: When an applet creates a free-standing Frame, Java Plug-in adds a yellow warning banner so users will know they are dealing with an untrusted applet window.

Q: Can I disable the yellow warning banner on frames?

A: The yellow warning banner is an important security feature. It cannot be disabled by untrusted applets.

If you use a signed applet, where the signing key is trusted by the end user, then the warning banner will not be shown.

Q: How do I prevent the warning banner from covering my GUI state?

A: See the same question in the Developer FAQ.

Q: Why does InetAddress.getLocalHost().getHostName() return "localhost"?

A: See the same question in the Developer FAQ.


Preferences API

 Documentation Contents
Applications require preference and configuration data to adapt to the needs of different users and environments. The java.util.prefs package provides a way for applications to store and retrieve user and system preference and configuration data. The data is stored persistently in an implementation-dependent backing store. There are two separate trees of preference nodes, one for user preferences and one for system preferences.

Overview

  • Overview - An overview of the Preferences API.

API Specification

  • java.util.prefs package

More Information

  • Design FAQ - Answers to frequently asked questions concerning the Preferences API.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: TBP 		Sun
Java Software


Preferences API Design FAQ

Design FAQ

Following is a collection of frequently asked questions concerning the design of the Preferences API.

  1. How does this Preferences API relate to Properties API?

    It is intended to replace most common uses of Properties, rectifying many of its deficiencies, while retaining its light weight. When using Properties, the programmer must explicitly specify a pathname for each properties file, but there is no standard location or naming convention. Properties files are "brittle", as they are hand-editable but easily corrupted by careless editing. Support for non-string data types in properties is non-existent. Properties cannot easily be used with a persistence mechanism other than the file system. In sum, the Properties facility does not scale.

  2. How does Preferences API relate to JNDI?

    Like JNDI, it provides back-end neutral access to persistent key-value data. JNDI, however, is far more powerful, and correspondingly heavyweight. JNDI is appropriate for enterprise applications that need its power. Preferences API is intended as a simple, ubiquitous, back-end neutral preferences-management facility, enabling any Java application to easily tailor its behavior to user preferences and maintain small amounts of state from run to run.

  3. Why do all of the get methods require the caller to pass in a default?

    This forces the application authors to provide reasonable default values, so that applications have a reasonable chance of running even if the repository is unavailable.

  4. How was it decided which methods should throw BackingStoreException?

    Only methods whose semantics absolutely require the ability to communicate with the backing store throw this exception. Typical applications will have no need to call these methods. As long as these methods are avoided, applications will be able to run even if the backing store is unavailable, which was an explicit design goal.

  5. Why doesn't this API provide stronger guarantees concerning concurrent access by multiple VMs? Similarly, why doesn't the API allow multiple Preferences updates to be combined into a single "transaction", with all or nothing semantics?

    While the the API does provide rudimentary persistent data storage, it is not intended as a substitute for a database. It is critical that it be possible to implement this API atop standard preference/configuration repositories, most of which do not provide database-like guarantees and functionality. Such repositories have proven adequate for the purposes for which this API is intended.

  6. Why does this API have case-sensitive keys and node-names, while other APIs playing in a similar space (such as the Microsoft Windows Registry and LDAP) do not?

    In the Java programming universe, case-sensitive String keys are ubiquitous. In particular, they are provided by the Properties class, which this API is intended to replace. It is not uncommon for people to use Properties in a fashion that demands case-sensitivity. For example, Java package names (which are case-sensitive) are sometimes used as keys. It is recognized that this design decision complicates the life of the systems programmer who implements Preferences atop a backing store with case-insensitive keys, but this is considered an acceptable price to pay, as far more programmers will use the Preferences API than will implement it.

  7. Why doesn't this API use the Java 2 Collections Framework?

    This API is designed for a very particular purpose, and is optimized for that purpose. In the absence of generic types (see JSR-14), the API would be less convenient for typical users. It would lack compile-time type safety, if forced to conform to the Map API. Also, it is not anticipated that interoperability with other Map implementations will be required (though it would be straightforward to implement an adapter class if this assumption turned out to be wrong). Preferences API is, by design, so similar to Map that programmers familiar with the latter should have no difficulties using the former.

  8. Why don't the put and remove methods return the old values?

    It is desirable that both of these methods be executable even if the backing store is unavailable. This would not be possible if they were required to return the old value. Further, it would have negative performance impact if the API were implemented atop some common back-end data stores.

  9. Why does the API permit, but not require, stored defaults?

    This functionality is required in enterprise settings for scalable, cost-effective administration of preferences across the enterprise, but would be overkill in a self-administered single-user setting.

  10. Why doesn't this API contain methods to read and write arbitrary serializable objects?

    Serialized objects are somewhat fragile: if the version of the program that reads such a property differs from the version that wrote it, the object may not deserialize properly (or at all). It is not impossible to store serialized objects using this API, but we do not encourage it, and have not provided a convenience method.

  11. Why is Preferences an abstract class rather than an interface?

    It was decided that the ability to add new methods in an upward compatible fashion outweighed the disadvantage that Preferences cannot be used as a "mixin" (That is to say, arbitrary classes cannot also be made to serve as Preferences objects.) Also, this obviates the need for a separate class for the static methods. (Interfaces cannot contain static methods.)

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: TBP 		Sun
Java Software


Preferences API Overview

Introduction

All of the methods that modify preference data are permitted to operate asynchronously. They may return immediately, and changes will eventually propagate to the persistent backing store. The flush method can be used to force updates to the backing store.

The methods in the Preferences class may be invoked concurrently by multiple threads in a single JVM without the need for external synchronization, and the results will be equivalent to some serial execution. If this class is used concurrently by multiple JVMs that store their preference data in the same backing store, the data store will not be corrupted, but no other guarantees are made concerning the consistency of the preference data.

For more details, choose from the following links:

  • Comparing Preferences API to Other Mechanisms
  • Usage Notes
  • Design FAQ

Comparing Preferences API to Other Mechanisms

Prior to the introduction of the Preferences API, developers could choose to manage preference and configuration data in an ad hoc fashion, by using the Properties API or the JNDI API as described below.

Often, preference and configuration data was stored in properties files, accessed through the java.util.Properties API. However, there are no standards as to where such files should reside on disk, or what they should be called. Using this mechanism, it is extremely difficult to backup a user's preference data, or transfer it from one machine to another. As the number of applications increases, the possibility of file name conflicts increases. Also, this mechanism is of no help on platforms that lack a local disk, or where it is desirable that the data be stored in an external data store (such as an enterprise-wide LDAP directory service).

Less frequently, developers stored user preference and configuration data in a directory service, accessed through the Java Naming and Directory Interface (JNDI) API. Unlike the Properties API, JNDI allows the use of arbitrary data stores (back-end neutrality). While JNDI is extremely powerful, it is also rather large, consisting of 5 packages and 83 classes. JNDI provides no policy as to where in the directory name space the preference data should be stored, or in which name space.

Neither Properties nor JNDI provide a simple, ubiquitous, back-end neutral preferences management facility. The Preferences API does provide such a facility, combining the simplicity of Properties with the back-end neutrality of JNDI. It provides sufficient built-in policy to prevent name clashes, foster consistency, and encourage robustness in the face of inaccessibility of the backing data store.

  • See Also: Design FAQ

Usage Notes

The material contained in this section is not part of the Preferences API specification, instead it is intended to provide some examples of how the Preferences API might be used.

  • Obtaining Preferences Objects for an Enclosing Class
  • Obtaining Preferences Objects for a Static Method
  • Atomic Updates
  • Determining Backing Store Status

Obtaining Preferences Objects for an Enclosing Class

The following examples illustrate how you might obtain the Preferences objects (system and user) pertaining to the enclosing class. These examples would work only inside instance methods.

Note that static final fields, rather than inline String literals, are used for the key names (NUM_ROWS and NUM_COLS). This reduces the likelihood of runtime bugs from typographical errors in key names.

Note also that reasonable defaults are provided for each of the preference values obtained. These defaults will be returned if no preference value has been set, or if the backing store is inaccessible.

package com.acme.widget;
import  java.util.prefs.*;

public class Gadget {
    // Preference keys for this package
    private static final String NUM_ROWS = "num_rows";
    private static final String NUM_COLS = "num_cols";

    void foo() {
        Preferences prefs = Preferences.userNodeForPackage(Gadget.class);

        int numRows = prefs.getInt(NUM_ROWS, 40);
        int numCols = prefs.getInt(NUM_COLS, 80);

        ...
    }
}

The above example obtains per-user preferences. If a single, per-system value were desired, the first line in foo would be replaced by:

        Preferences prefs = Preferences.systemNodeForPackage(Gadget.class);

Obtaining Preferences Objects for a Static Method

The examples in the prior section illustrate obtaining Preferences objects pertaining to the enclosing class, and work inside instance methods. In a static method (or static initializer), you need to explicitly provide the name of the package:

    Static String ourNodeName = "/com/acme/widget";

    static void foo() {
        Preferences prefs = Preferences.userRoot().node(ourNodeName);

        ...
    }

It is always acceptable to obtain a system preferences object once, in a static initializer, and use it whenever system preferences are required:

    static Preferences prefs =  Preferences.systemRoot().node(ourNodeName);

In general, it is acceptable to do the same thing for a user preferences object, but not if the code in question is to be used in a server, wherein multiple users will be running concurrently or serially. In such a system, userNodeForPackage and userRoot will return the appropriate node for the calling user, thus it's critical that calls to userNodeForPackage or userRoot be made from the appropriate thread at the appropriate time. If a piece of code may eventually be used in such a server environment, it is good, conservative practice to obtain user preferences objects immediately before they are used, as in the prior example.

Atomic Updates

The preferences API does not provide database like "transactions" wherein multiple preferences are modified atomically. Occasionally, it is necessary to modify two or more preferences as a unit. For example, suppose you are storing the x and y coordinates where a window is to be placed. The only way to achieve atomicity is to store both values in a single preference. Many encodings are possible. Here's a simple one:

    int x, y;
    ...
    prefs.put(POSITION, x + "," + y);

When such a "compound preference" is read, it must be decoded. For robustness, allowances should be made for a corrupt (unparseable) value:

    static int X_DEFAULT = 50, Y_DEFAULT = 25;
    void baz() {
        String position = prefs.get(POSITION, X_DEFAULT + "," + Y_DEFAULT);
        int x, y;
        try {
            int i = position.indexOf(',');
            x = Integer.parseInt(coordinates.substring(0, i));
            y = Integer.parseInt(position.substring(i + 1));
        } catch(Exception e) {
            // Value was corrupt, just use defaults
            x = X_DEFAULT;
            y = Y_DEFAULT;
        }
        ...
    }

Determining Backing Store Status

Typical application code has no need to know whether the backing store is available. It should almost always be available, but if it isn't, the code should continue to execute using default values in place of preference values from the backing store. Very rarely, some advanced program might want to vary its behavior (or simply refuse to run) if the backing store were unavailable. Following is a method that determines whether the backing store is available by attempting to modify a preference value and flush the result to the backing store.

    private static final String BACKING_STORE_AVAIL = "BackingStoreAvail";

    private static boolean backingStoreAvailable() {
        Preferences prefs = Preferences.userRoot().node("<temporary>");
        try {
            boolean oldValue = prefs.getBoolean(BACKING_STORE_AVAIL, false);
            prefs.putBoolean(BACKING_STORE_AVAIL, !oldValue);
            prefs.flush();
        } catch(BackingStoreException e) {
            return false;
        }
        return true;
    }

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: TBP 		Sun
Java Software


Dynamic Proxy Classes

 Documentation Contents

Contents

Introduction
Dynamic Proxy API
Serialization
Examples

Introduction

A dynamic proxy class is a class that implements a list of interfaces specified at runtime such that a method invocation through one of the interfaces on an instance of the class will be encoded and dispatched to another object through a uniform interface. Thus, a dynamic proxy class can be used to create a type-safe proxy object for a list of interfaces without requiring pre-generation of the proxy class, such as with compile-time tools. Method invocations on an instance of a dynamic proxy class are dispatched to a single method in the instance's invocation handler, and they are encoded with a java.lang.reflect.Method object identifying the method that was invoked and an array of type Object containing the arguments.

Dynamic proxy classes are useful to an application or library that needs to provide type-safe reflective dispatch of invocations on objects that present interface APIs. For example, an application can use a dynamic proxy class to create an object that implements multiple arbitrary event listener interfaces-- interfaces that extend java.util.EventListener-- to process a variety of events of different types in a uniform fashion, such as by logging all such events to a file.

Dynamic Proxy Class API

A dynamic proxy class (simply referred to as a proxy class below) is a class that implements a list of interfaces specified at runtime when the class is created.

A proxy interface is such an interface that is implemented by a proxy class.

A proxy instance is an instance of a proxy class.

Creating a Proxy Class

Proxy classes, as well as instances of them, are created using the static methods of the class java.lang.reflect.Proxy.

The Proxy.getProxyClass method returns the java.lang.Class object for a proxy class given a class loader and an array of interfaces. The proxy class will be defined in the specified class loader and will implement all of the supplied interfaces. If a proxy class for the same permutation of interfaces has already been defined in the class loader, then the existing proxy class will be returned; otherwise, a proxy class for those interfaces will be generated dynamically and defined in the class loader.

There are several restrictions on the parameters that may be passed to Proxy.getProxyClass:

  • All of the Class objects in the interfaces array must represent interfaces, not classes or primitive types.
  • No two elements in the interfaces array may refer to identical Class objects.
  • All of the interface types must be visible by name through the specified class loader. In other words, for class loader cl and every interface i, the following expression must be true:
        Class.forName(i.getName(), false, cl) == i
  • All non-public interfaces must be in the same package; otherwise, it would not be possible for the proxy class to implement all of the interfaces, regardless of what package it is defined in.
  • For any set of member methods of the specified interfaces that have the same signature:
    • If the return type of any of the methods is a primitive type or void, then all of the methods must have that same return type.
    • Otherwise, one of the methods must have a return type that is assignable to all of the return types of the rest of the methods.
  • The resulting proxy class must not exceed any limits imposed on classes by the virtual machine. For example, the VM may limit the number of interfaces that a class may implement to 65535; in that case, the size of the interfaces array must not exceed 65535.

If any of these restrictions are violated, Proxy.getProxyClass will throw an IllegalArgumentException. If the interfaces array argument or any of its elements are null, a NullPointerException will be thrown.

Note that the order of the specified proxy interfaces is significant: two requests for a proxy class with the same combination of interfaces but in a different order will result in two distinct proxy classes. Proxy classes are distinguished by the order of their proxy interfaces in order to provide deterministic method invocation encoding in cases where two or more of the proxy interfaces share a method with the same name and parameter signature; this reasoning is described in more detail in the section below titled Methods Duplicated in Multiple Proxy Interfaces.

So that a new proxy class does not need to be generated each time Proxy.getProxyClass is invoked with the same class loader and list of interfaces, the implementation of the dynamic proxy class API should keep a cache of generated proxy classes, keyed by their corresponding loaders and interface list. The implementation should be careful not to refer to the class loaders, interfaces, and proxy classes in such a way as to prevent class loaders, and all of their classes, from being garbage collected when appropriate.

Proxy Class Properties

A proxy class has the following properties:

  • Proxy classes are public, final, and not abstract.
  • The unqualified name of a proxy class is unspecified. The space of class names that begin with the string "$Proxy" is, however, to be reserved for proxy classes.
  • A proxy class extends java.lang.reflect.Proxy.
  • A proxy class implements exactly the interfaces specified at its creation, in the same order.
  • If a proxy class implements a non-public interface, then it will be defined in the same package as that interface. Otherwise, the package of a proxy class is also unspecified. Note that package sealing will not prevent a proxy class from being successfully defined in a particular package at runtime, and neither will classes already defined in the same class loader and the same package with particular signers.
  • Since a proxy class implements all of the interfaces specified at its creation, invoking getInterfaces on its Class object will return an array containing the same list of interfaces (in the order specified at its creation), invoking getMethods on its Class object will return an array of Method objects that include all of the methods in those interfaces, and invoking getMethod will find methods in the proxy interfaces as would be expected.
  • The Proxy.isProxyClass method will return true if it is passed a proxy class-- a class returned by Proxy.getProxyClass or the class of an object returned by Proxy.newProxyInstance-- and false otherwise. The reliability of this method is important for the ability to use it to make security decisions, so its implementation should not just test if the class in question extends java.lang.reflect.Proxy.
  • The java.security.ProtectionDomain of a proxy class is the same as that of system classes loaded by the bootstrap class loader, such as java.lang.Object, because the code for a proxy class is generated by trusted system code. This protection domain will typically be granted java.security.AllPermission.

Creating a Proxy Instance

Each proxy class has one public constructor that takes one argument, an implementation of the interface InvocationHandler.

Each proxy instance has an associated invocation handler object, the one that was passed to its constructor. Rather than having to use the reflection API to access the public constructor, a proxy instance can be also be created by calling the Proxy.newProxyInstance method, which combines the actions of calling Proxy.getProxyClass with invoking the constructor with an invocation handler. Proxy.newProxyInstance throws IllegalArgumentException for the same reasons that Proxy.getProxyClass does.

Proxy Instance Properties

A proxy instance has the following properties:

  • Given a proxy instance proxy and one of the interfaces implemented by its proxy class Foo, the following expression will return true:
        proxy instanceof Foo
    and the following cast operation will succeed (rather than throwing a ClassCastException):
        (Foo) proxy

  • The static Proxy.getInvocationHandler method will return the invocation handler associated with the proxy instance passed as its argument. If the object passed to Proxy.getInvocationHandler is not a proxy instance, then an IllegalArgumentException will be thrown.

  • An interface method invocation on a proxy instance will be encoded and dispatched to the invocation handler's invoke method as described below.

    The proxy instance itself will be passed as the first argument of invoke, which is of type Object.

    The second argument passed to invoke will be the java.lang.reflect.Method instance corresponding to the interface method invoked on the proxy instance. The declaring class of the Method object will be the interface that the method was declared in, which may be a superinterface of the proxy interface that the proxy class inherits the method through.

    The third argument passed to invoke will be an array of objects containing the values of the arguments passed in the method invocation on the proxy instance. Arguments of primitive types are wrapped in an instance of the appropriate primitive wrapper class, such as java.lang.Integer or java.lang.Boolean. The implementation of the invoke method is free to modify the contents of this array.

    The value returned by the invoke method will become the return value of the method invocation on the proxy instance. If the declared return value of the interface method is a primitive type, then the value returned by invoke must be an instance of the corresponding primitive wrapper class; otherwise, it must be a type assignable to the declared return type. If the value returned by invoke is null and the interface method's return type is primitive, then a NullPointerException will be thrown by the method invocation on the proxy instance. If the value returned by invoke is otherwise not compatible with the method's declared return type as described above, a ClassCastException will be thrown by the proxy instance.

    If an exception is thrown by the invoke method, it will be also thrown by the method invocation on the proxy instance. The exception's type must be assignable to either any of the exception types declared in the signature of the interface method or to the unchecked exception types java.lang.RuntimeException or java.lang.Error. If a checked exception is thrown by invoke that is not assignable to any of the exception types declared in the throws clause of the interface method, then an UndeclaredThrowableException will be thrown by the method invocation on the proxy instance. The UndeclaredThrowableException will be constructed with the exception that was thrown by the invoke method.

  • An invocation of the hashCode, equals, or toString methods declared in java.lang.Object on a proxy instance will be encoded and dispatched to the invocation handler's invoke method in the same manner as interface method invocations are encoded and dispatched, as described above. The declaring class of the Method object passed to invoke will be java.lang.Object. Other public methods of a proxy instance inherited from java.lang.Object are not overridden by a proxy class, so invocations of those methods behave like they do for instances of java.lang.Object.

Methods Duplicated in Multiple Proxy Interfaces

When two or more interfaces of a proxy class contain a method with the same name and parameter signature, the order of the proxy class's interfaces becomes significant. When such a duplicate method is invoked on a proxy instance, the Method object passed to the invocation handler will not necessarily be the one whose declaring class is assignable from the reference type of the interface that the proxy's method was invoked through. This limitation exists because the corresponding method implementation in the generated proxy class cannot determine which interface it was invoked through. Therefore, when a duplicate method is invoked on a proxy instance, the Method object for the method in the foremost interface that contains the method (either directly or inherited through a superinterface) in the proxy class's list of interfaces is passed to the invocation handler's invoke method, regardless of the reference type through which the method invocation occurred.

If a proxy interface contains a method with the same name and parameter signature as the hashCode, equals, or toString methods of java.lang.Object, when such a method is invoked on a proxy instance, the Method object passed to the invocation handler will have java.lang.Object as its declaring class. In other words, the public, non-final methods of java.lang.Object logically precede all of the proxy interfaces for the determination of which Method object to pass to the invocation handler.

Note also that when a duplicate method is dispatched to an invocation handler, the invoke method may only throw checked exception types that are assignable to one of the exception types in the throws clause of the method in all of the proxy interfaces that it can be invoked through. If the invoke method throws a checked exception that is not assignable to any of the exception types declared by the method in one of the the proxy interfaces that it can be invoked through, then an unchecked UndeclaredThrowableException will be thrown by the invocation on the proxy instance. This restriction means that not all of the exception types returned by invoking getExceptionTypes on the Method object passed to the invoke method can necessarily be thrown successfully by the invoke method.

Serialization

Since java.lang.reflect.Proxy implements java.io.Serializable, proxy instances can be serialized, as described in this section. If a proxy instance contains an invocation handler that is not assignable to java.io.Serializable, however, then a java.io.NotSerializableException will be thrown if such an instance is written to a java.io.ObjectOutputStream. Note that for proxy classes, implementing java.io.Externalizable has the same effect with respect to serialization as implementing java.io.Serializable: the writeExternal and readExternal methods of the Externalizable interface will never be invoked on a proxy instance (or an invocation handler) as part of its serialization process. As with all Class objects, the Class object for a proxy class is always serializable.

A proxy class has no serializable fields and a serialVersionUID of 0L. In other words, when the Class object for a proxy class is passed to the static lookup method of java.io.ObjectStreamClass, the returned ObjectStreamClass instance will have the following properties:

  • Invoking its getSerialVersionUID method will return 0L.
  • Invoking its getFields method will return an array of length zero.
  • Invoking its getField method with any String argument will return null.

The stream protocol for Object Serialization supports a type code named TC_PROXYCLASSDESC, which is a terminal symbol in the grammar for the stream format; its type and value are defined by the following constant field in the java.io.ObjectStreamConstants interface:

    final static byte TC_PROXYCLASSDESC = (byte)0x7D;

The grammar also includes the following two rules, the first being an alternate expansion of the original newClassDesc rule:

newClassDesc:
TC_PROXYCLASSDESC newHandle proxyClassDescInfo

proxyClassDescInfo:
(int)<count> proxyInterfaceName[count] classAnnotation superClassDesc

proxyInterfaceName:
(utf)

When an ObjectOutputStream serializes the class descriptor for a class that is a proxy class, as determined by passing its Class object to the Proxy.isProxyClass method, it uses the TC_PROXYCLASSDESC type code instead of TC_CLASSDESC, following the rules above. In the expansion of proxyClassDescInfo, the sequence of proxyInterfaceName items are the names of all of the interfaces implemented by the proxy class, in the order that they are returned by invoking the getInterfaces method on the Class object. The classAnnotation and superClassDesc items have the same meaning as they do in the classDescInfo rule. For a proxy class, superClassDesc is the class descriptor for its superclass, java.lang.reflect.Proxy; including this descriptor allows for the evolution of the serialized representation of the class Proxy for proxy instances.

For non-proxy classes, ObjectOutputStream calls its protected annotateClass method to allow subclasses to write custom data to the stream for a particular class. For proxy classes, instead of annotateClass, the following method in java.io.ObjectOutputStream is called with the Class object for the proxy class:

    protected void annotateProxyClass(Class cl) throws IOException;

The default implementation of annotateProxyClass in ObjectOutputStream does nothing.

When an ObjectInputStream encounters the type code TC_PROXYCLASSDESC, it deserializes the class descriptor for a proxy class from the stream, formatted as described above. Instead of calling its resolveClass method to resolve the Class object for the class descriptor, the following method in java.io.ObjectInputStream is called:

    protected Class resolveProxyClass(String[] interfaces)
    throws IOException, ClassNotFoundException;

The list of interface names that were deserialized in the proxy class descriptor are passed as the interfaces argument to resolveProxyClass.

The default implementation of resolveProxyClass in ObjectInputStream returns the results of calling Proxy.getProxyClass with the list of Class objects for the interfaces named in the interfaces parameter. The Class object used for each interface name i is the value retuned by calling

    Class.forName(i, false, loader)
where loader is the first non-null class loader up the execution stack, or null if no non-null class loaders are on the stack. This is the same class loader choice made by the default behavior of the resolveClass method. This same value of loader is also the class loader passed to Proxy.getProxyClass. If Proxy.getProxyClass throws an IllegalArgumentException, resolveClass will throw a ClassNotFoundException containing the IllegalArgumentException.

Since a proxy class never has its own serializable fields, the classdata[] in the stream representation of a proxy instance consists wholly of the instance data for its superclass, java.lang.reflect.Proxy. Proxy has one serializable field, h, which contains the invocation handler for the proxy instance.

Examples

Here is a simple example that prints out a message before and after a method invocation on an object that implements an arbitrary list of interfaces:

public interface Foo {
    Object bar(Object obj) throws BazException;
}

public class FooImpl implements Foo {
    Object bar(Object obj) throws BazException {
        // ...
    }
}

public class DebugProxy implements java.lang.reflect.InvocationHandler {

    private Object obj;

    public static Object newInstance(Object obj) {
    return java.lang.reflect.Proxy.newProxyInstance(
        obj.getClass().getClassLoader(),
        obj.getClass().getInterfaces(),
        new DebugProxy(obj));
    }

    private DebugProxy(Object obj) {
    this.obj = obj;
    }

    public Object invoke(Object proxy, Method m, Object[] args)
    throws Throwable
    {
        Object result;
    try {
        System.out.println("before method " + m.getName());
        result = m.invoke(obj, args);
        } catch (InvocationTargetException e) {
        throw e.getTargetException();
        } catch (Exception e) {
        throw new RuntimeException("unexpected invocation exception: " +
                       e.getMessage());
    } finally {
        System.out.println("after method " + m.getName());
    }
    return result;
    }
}

To construct a DebugProxy for an implementation of the Foo interface and call one of its methods:

    Foo foo = (Foo) DebugProxy.newInstance(new FooImpl());
    foo.bar(null);

Here is an example of a utility invocation handler class that provides default proxy behavior for methods inherited from java.lang.Object and implements delegation of certain proxy method invocations to distinct objects depending on the interface of the invoked method:

import java.lang.reflect.*;

public class Delegator implements InvocationHandler {

    // preloaded Method objects for the methods in java.lang.Object
    private static Method hashCodeMethod;
    private static Method equalsMethod;
    private static Method toStringMethod;
    static {
    try {
        hashCodeMethod = Object.class.getMethod("hashCode", null);
        equalsMethod =
        Object.class.getMethod("equals", new Class[] { Object.class });
        toStringMethod = Object.class.getMethod("toString", null);
        } catch (NoSuchMethodException e) {
        throw new NoSuchMethodError(e.getMessage());
    }
    }

    private Class[] interfaces;
    private Object[] delegates;

    public Delegator(Class[] interfaces, Object[] delegates) {
    this.interfaces = (Class[]) interfaces.clone();
    this.delegates = (Object[]) delegates.clone();
    }

    public Object invoke(Object proxy, Method m, Object[] args)
    throws Throwable
    {
    Class declaringClass = m.getDeclaringClass();

    if (declaringClass == Object.class) {
        if (m.equals(hashCodeMethod)) {
        return proxyHashCode(proxy);
        } else if (m.equals(equalsMethod)) {
        return proxyEquals(proxy, args[0]);
        } else if (m.equals(toStringMethod)) {
        return proxyToString(proxy);
        } else {
        throw new InternalError(
            "unexpected Object method dispatched: " + m);
        }
    } else {
        for (int i = 0; i < interfaces.length; i++) {
        if (declaringClass.isAssignableFrom(interfaces[i])) {
            try {
            return m.invoke(delegates[i], args);
            } catch (InvocationTargetException e) {
            throw e.getTargetException();
            }
        }
        }

        return invokeNotDelegated(proxy, m, args);
    }
    }

    protected Object invokeNotDelegated(Object proxy, Method m,
                        Object[] args)
    throws Throwable
    {
    throw new InternalError("unexpected method dispatched: " + m);
    }

    protected Integer proxyHashCode(Object proxy) {
    return new Integer(System.identityHashCode(proxy));
    }

    protected Boolean proxyEquals(Object proxy, Object other) {
    return (proxy == other ? Boolean.TRUE : Boolean.FALSE);
    }

    protected String proxyToString(Object proxy) {
    return proxy.getClass().getName() + '@' +
        Integer.toHexString(proxy.hashCode());
    }
}

Subclasses of Delegator can override invokeNotDelegated to implement the behavior of proxy method invocations not to be directly delegated to other objects, and they can override proxyHashCode, proxyEquals, and proxyToString to override the default behavior of the methods the proxy inherits from java.lang.Object.

To construct a Delegator for an implementation of the Foo interface:

    Class[] proxyInterfaces = new Class[] { Foo.class };
    Foo foo = (Foo) Proxy.newProxyInstance(Foo.class.getClassLoader(),
    proxyInterfaces,
    new Delegator(proxyInterfaces, new Object[] { new FooImpl() }));

Note that the implementation of the Delegator class given above is intended to be more illustrative than optimized; for example, instead of caching and comparing the Method objects for the hashCode, equals, and toString methods, it could just match them by their string names, because none of those method names are overloaded in java.lang.Object.

Copyright © 1999-2004 Sun Microsystems, Inc. All Rights Reserved. Sun

Java Software


Enhancements to Reflection

Java

Enhancements in java.lang.Class and java.lang.reflect

 Reflection
  • Enhancements in Java SE 6
  • Enhancements in J2SE 5.0
  • Enhancements in J2SDK 1.4

Enhancements in Java SE 6

  • The following methods in java.lang.Class were generified: getInterfaces(), getClasses(). getConstructors(). getMethod(String, Class...), getConstructor(Class...), getDeclaredClasses(), getDeclaredConstructors(), getDeclaredMethod(String, Class...), and getDeclaredConstructor(Class...). As a result, code which uses these methods now produces warnings during compilation.

    For example, consider the following code which invokes getDeclaredMethod():

    import java.lang.reflect.Method;

public class Warning {
    void m() {
    try {
         Warning warn = new Warning();
         Class c = warn.getClass();
        Method m = c.getDeclaredMethod("m");
    } catch (NoSuchMethodException x) {
        x.printStackTrace();
    }
    }
}

$ javac Warning.java
Note: Warning.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.
$ javac -Xlint:unchecked Warning.java
Warning.java:8: warning: [unchecked] unchecked call to getDeclaredMethod(java.lang.String,java.lang.Class<?>...) as a member of the raw type java.lang.Class
            Method m = c.getDeclaredMethod("m");
                                          ^
1 warning

    To remove the warning, the declaration of c should be modified to include an appropriate generic type. In this case, the declation should be:

    Class<?> c = warn.getClass();
  • Method.toString() and Constructor.toString() now correctly display the set of modifiers.
  • The final parameter of Array.newInstance(Class, int...) is of variable arity.

Enhancements in J2SE 5.0

 The changes in java.lang.Class and java.lang.reflect include:
  • Support for generics - In particular, the changes support structural program reflection on generic type information. In other words, they make it possible to examine a type, method, constructor or field declaration and obtain generic type information. Specifically, one can determine whether a type, method or constructor declares any type variables, and reflect those type variables to the application program (so that one may learn their names and bounds, for example). One can also obtain the non-erased form of the type of a field, a method or constructor parameter, a method return type or the throws clause of a method or constructor. The generified form of a type name is available via toGenericString(). However, note that we do not provide any support for determining which generic invocation an instance belongs to.
  • Support for annotations - This includes the ability to obtain annotations on types, methods, fields, constructors and formal parameters of methods and constructors that have been marked as available at run-time, using the getAnnotation() method. One can also determine whether an interface is an annotation type.
  • Support for enums - One can determine whether a class is an enum, and whether a field represents an enum constant.
  • Support for var args - One can determine whether a method or constructor is a of variable arity.
  • Convenience methods - for establishing whether a class is local, anonymous or a member class, and what a type's simple and cannoical names are. One can also determine whether a member is synthetic (an artifiact by the implementation).
  • The generification of class java.lang.Class - This allows the use of instances of java.lang.Class as type tokens. See section 8 of the generics tutorial for examples.

Enhancements in J2SDK 1.4

  • Performance enhancements - Certain reflective operations, specifically Field, Method.invoke(), Constructor.newInstance(), and Class.newInstance(), have been rewritten for higher performance. Reflective invocations and instantiations are several times faster than in previous releases.
Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

 Sun


Reflection

 Documentation Contents
Reflection enables Java code to discover information about the fields, methods and constructors of loaded classes, and to use reflected fields, methods, and constructors to operate on their underlying counterparts, within security restrictions. The API accommodates applications that need access to either the public members of a target object (based on its runtime class) or the members declared by a given class. It also allows programs to suppress default reflective access control.

API Specification

  • java.lang.reflect

Tutorials and Programmer's Guides

  • Dyanmic Proxy Classes

Enhancements

  • Enhancements in Java SE 6
  • Enhancements in J2SE 5.0
  • Enhancements in J2SDK 1.4

More Information

  • Using Java Reflection
  • Reflection API Code Samples

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun

Java Software


Contents | Prev | Next Java Core Reflection

Acknowledgements

The reflection API was designed by Nakul Saraiya and Bill Joy, and benefited from substantial input from John Rose. Thanks also to our colleagues at JavaSoft and our external reviewers for their valuable comments.

References

JavaTM Beans Specification, JavaSoft

JavaTM Object Serialization Specification, JavaSoft

Contents | Prev | Next
Copyright © 1996, 1997, 1998 Sun Microsystems, Inc. All rights reserved.


Java Core Reflection

Contents | Prev | Next Java Core Reflection

Overview

The Java(TM) Core Reflection API provides a small, type-safe, and secure API that supports introspection about the classes and objects in the current Java Virtual Machine*. If permitted by security policy, the API can be used to:

  • construct new class instances and new arrays

  • access and modify fields of objects and classes

  • invoke methods on objects and classes

  • access and modify elements of arrays

The Core Reflection API defines classes and methods, as follows:

  • Three classes-Field, Method, and Constructor-that reflect class and interface members and constructors. These classes provide:

    • reflective information about the underlying member or constructor

    • a type-safe means to use the member or constructor to operate on Java objects

  • Methods of class Class that provide for the construction of new instances of the Field, Method, and Constructor classes.

  • The class Array provides methods to dynamically construct and access Java arrays.

  • The utility class Modifier helps decode Java language modifier information about classes and their members.

  • The class InvocationTargetException is used to wrap exceptions thrown by reflected methods or constructors.

  • Two classes-AccessibleObject and ReflectPermission-that provide a mechanism to suppress standard Java language access control.

There are also some parts of the java.lang package that support reflection. These are:

  • Static fields that hold instances of the class Class. These represent the primitive Java types boolean, byte, char, short, int, long, float, and double, and the keyword void, at run-time.

  • An uninstantiable placeholder class-Void-to hold a reference to the Class object representing the keyword void.

Applications

The Core Reflection API accommodates two categories of applications.

One category is comprised of applications that need to discover and use all of the public members of a target object based on its run-time class. These applications require run-time access to all the public fields, methods, and constructors of an object. Examples in this category are services such as Java(TM) Beans[1], and lightweight tools, such as object inspectors. These applications use the instances of the classes Field, Method, and Constructor obtained through the methods getField, getMethod, getConstructor, getFields, getMethods, and getConstructors of class Class.

The second category consists of sophisticated applications that need to discover and use the members declared by a given class. These applications need run-time access to the implementation of a class at the level provided by a class file. Examples in this category are development tools, such as interpreters, inspectors, and class browsers, and run-time services, such as Java(TM) Object Serialization[2]. These applications use instances of the classes Field, Method, and Constructor obtained through the methods getDeclaredField, getDeclaredMethod, getDeclaredConstructor, getDeclaredFields, getDeclaredMethods, and getDeclaredConstructors of class Class.

Reflection Model

The three classes Field, Method, and Constructor are final. Only the Java Virtual Machine may create instances of these classes; these objects are used to manipulate the underlying objects; that is, to:

  • get reflective information about the underlying member or constructor

  • get and set field values

  • invoke methods on objects or classes

  • create new instances of classes

The final uninstantiable class Array provides static methods that permit creating new arrays, and getting and setting the elements of arrays.

Member Interface

The classes Field, Method and Constructor implement the Member interface. The methods of Member are used to query a reflected member for basic identifying information. Identifying information consists of the class or interface that declared the member, the name of the member itself, and the Java language modifiers (such as public, protected, abstract, synchronized, and so on) for the member.

Field Objects

A Field object represents a reflected field. The underlying field may be a class variable (a static field) or an instance variable (a non-static field). Methods of class Field are used to obtain the type of the underlying field, and to get and set the underlying field's value on objects.

Method Objects

A Method object represents a reflected method. The underlying method may be an abstract method, an instance method, or a class (static) method.

Methods of class Method are used to obtain the formal parameter types, the return type, and the checked exception types of the underlying method. In addition, the invoke method of class Method is used to invoke the underlying method on target objects. Instance and abstract method invocation uses dynamic method resolution based on the target object's run-time class and the reflected method's declaring class, name, and formal parameter types. (Thus, it is permissible to invoke a reflected interface method on an object that is an instance of a class that implements the interface.) Static method invocation uses the underlying static method of the method's declaring class.

Constructor Objects

A Constructor object represents a reflected constructor. Methods of class Constructor are used to obtain the formal parameter types and the checked exception types of the underlying constructor. In addition, the newInstance method of class Constructor is used to create and initialize a new instance of the class that declares the constructor, provided the class is instantiable.

Array and Modifier Classes

The Array class is an uninstantiable class that exports class methods to create Java arrays with primitive or class component types. Methods of class Array are also used to get and set array component values.

The Modifier class is an uninstantiable class that exports class methods to decode Java language modifiers for classes and members. The language modifiers are encoded in an integer, and use the encoding constants defined by The Java Virtual Machine Specification.

Representation of Primitive Java Types

Finally, there are nine Class objects that are used to represent the eight primitive Java types and void at run-time. (Note that these are Class objects, not classes.) The Core Reflection API uses these objects to identify the following:

  • primitive field types

  • primitive method and constructor parameter types

  • primitive method return types

The Java Virtual Machine creates these nine Class objects. They have the same names as the types that they represent. The Class objects may only be referenced via the following public final static variables:

        java.lang.Boolean.TYPE

        java.lang.Character.TYPE

        java.lang.Byte.TYPE

        java.lang.Short.TYPE

        java.lang.Integer.TYPE

        java.lang.Long.TYPE

        java.lang.Float.TYPE

        java.lang.Double.TYPE

        java.lang.Void.TYPE
In particular, these Class objects are not accessible via the forName method of class Class.

Security Model

The Java security manager controls access to the Core Reflection API on a class-by-class basis. There are two levels of checks to enforce security and safety, as follows:

  • The methods of class Class that give reflective access to a member or a set of members of a class are the only source for instances of Field, Method, and Constructor. These methods first delegate security checking to the system security manager (if installed), which throws a SecurityException should the request for reflective access be denied.

  • Once the system security manager grants initial reflective access to a member, any code may query the reflected member for its identifying information. However, standard Java language access control checks-for protected, default (package) access, and private classes and members-will normally occur when the individual reflected members are used to operate on the underlying members of objects,that is, to get or set field values, to invoke methods, or to create and initialize new objects. Unrestricted access, which overrides standard language access control rules, may be granted to privileged code using the setAccessible method. This method is inherited from AccessibleObject by the classes Field, Method, and Constructor.

The initial policy decision is centralized in two methods of class SecurityManager:

void checkMemberAccess(Class,int) throws SecurityException

The Class parameter of checkMemberAccess identifies the class or interface whose members need to be accessed. The int parameter identifies the set of members to be accessed-either Member.PUBLIC or Member.DECLARED.

void checkPackageAccess(String pkg) throws SecurityException

The policy is determined based on what permissions are granted to the caller. There are two actions of class java.lang.RuntimePermission that affect these policies. These are:

  • accessDeclaredMembers. This grants the ability to reflect on non-public members of classes.

  • accessClassInPackage{package name}. This grants access to classes in the specified package. These permissions are determined by the security manager.

If the requested access to the specified set of members of the specified class is denied, the method should throw a SecurityException. If the requested access to the set is granted, the method should return.

As stated earler, standard Java language access control will usually be enforced when a reflected member from this set is used to operate on an underlying object, that is, when:

  • a Field is used to get or set a field value

  • a Method is used to invoke a method

  • a Constructor is used to create and initialize a new instance of a class

If access is denied at that point, the reflected member will throw an IllegalAccessException. Java language access control may be suppressed for a particular reflected member by setting a flag using the setAccessible method, as explained below.

Java Language Policy

The Java language security policy for applications is that any code may gain reflective access to all the members and constructors (including non-public members and constructors) of any class it may link against. By default, application code that gains reflective access to a member or constructor may only use the reflected member or constructor with standard Java language access control.

The standard policy may be overridden by calling the reflected member's setAccessible method. The ability to call the setAccessible method is in turn controlled by the suppressAccessChecks target of the permission ReflectPermission.

Data Conversions

Certain methods in the reflection package perform automatic data conversions between values of primitive types and objects of class types. These are the generic methods for getting and setting field and array component values, and the methods for method and constructor invocation.

There are two types of automatic data conversions. Wrapping conversions convert from values of primitive types to objects of class types. Unwrapping conversions convert objects of class types to values of primitive types. The rules for these conversions are defined in "Wrapping and Unwrapping Conversions."

Additionally, field access and method invocation permit widening conversions on primitive and reference types. These conversions are documented in The Java Language Specification, section 5, and are detailed in "Widening Conversions."

Wrapping and Unwrapping Conversions

A primitive value is automatically wrapped in an object when it is retrieved via Field.get or Array.get, or when it is returned by a method invoked via Method.invoke.

Similarly, an object value is automatically unwrapped when supplied as a parameter in a context that requires a value of a primitive type. These contexts are:

  • Field.set, where the underlying field has a primitive type

  • Array.set, where the underlying array has a primitive element type

  • Method.invoke or Constructor.newInstance, where the corresponding formal parameter of the underlying method or constructor has a primitive type

The following table shows the correspondences between primitive types and class (wrapper) types:

Primitive Type | Class Type
boolean | java.lang.Boolean
char | java.lang.Character
byte | java.lang.Byte
short | java.lang.Short
int | java.lang.Integer
long | java.lang.Long
float | java.lang.Float
double | java.lang.Double

A method that is declared void returns the special reference null when it is invoked via Method.invoke.

Widening Conversions

The reflection package permits the same widening conversions at run-time as permitted in method invocation contexts at compile time. These conversions are defined in The Java Language Specification, section 5.3.

Widening conversions are performed at run-time:

  • when a value is retrieved from a field or an array via the methods of Field and Array

  • when a value is stored into a field or an array via the methods of Field and Array

  • when an unwrapped actual parameter value is converted to the type of its corresponding formal parameter during method or constructor invocation via Method.invoke or Constructor.newInstance

The permitted widening primitive conversions are:

  • From byte to short, int, long, float, or double

  • From short to int, long, float, or double

  • From char to int, long, float, or double

  • From int to long, float, or double

  • From long to float or double

  • From float to double.

The permitted widening reference conversions are:

  • From a class type S to a class type T, provided that S is a subclass of T

  • From a class type S to an interface type K, provided that S implements K

  • From an interface type J to an interface type K, provided that J is a subinterface of K

Packaging

The Core Reflection API is in a subpackage of java.lang named java.lang.reflect. This avoids compatibility problems caused by Java's default package importation rules.

*As used on this web site, the terms "Java Virtual Machine" or "JVM" mean a virtual machine for the Java platform.

Contents | Prev | Next
Copyright © 1996, 1997, 1998 Sun Microsystems, Inc. All rights reserved.


Java Core Reflection

Overview
Applications
Reflection Model
Member Interface
Field Objects
Method Objects
Constructor Objects
Array and Modifier Classes
Representation of Primitive Java Types
Security Model
Java Language Policy
JDK 1.1 Security Policy
Data Conversions
Wrapping and Unwrapping Conversions
Widening Conversions
Packaging
Acknowledgements
References

Contents | Prev | Next
Copyright © 1996, 1997, 1998 Sun Microsystems, Inc. All rights reserved.


Applying the Factory Pattern to JavaTM RMI

What is a "factory" and why would you want to use one? A factory, in this context, is a piece of software that implements one of the "factory" design patterns introduced in the book, Design Patterns, Elements of Reusable Object-Oriented Software. In general, a factory implementation is useful when you need one object to control the creation of and/or access to other objects.By using a factory in JavaTM Remote Method Invocation (Java RMI), you can reduce the number of objects that you need to register with the Java RMI registry.

Examples of Factories in the Real World:

The Bank

When you go to the bank to make a deposit to your account, you don't walk up to a vault, pull out a drawer with your name on it, drop in your money, shut the drawer and leave. Think about how you originally established, or opened, the account. You probably went to the bank, spoke with an Account Manager, and signed some papers. In return, they gave you some checks, a passbook, or a bank card so you could access your account in the future.

The Account Manager is an example of a factory. The person or Automated Teller Machine (ATM) that acts as account manager controls the creation of and/or access to individual accounts.

The Library

Let's think about how a book, compact disk, or video tape gets from the library shelf into your home. Before you can check out any material, you must first get a library card from the librarian. In this case, the librarian could be viewed as a library card factory because the librarian controls the creation of new library card instances.

Once you have a library card, you can go into the library, and without any further fuss, just walk out with all your materials, right? Of course not. Before you can walk out of the library without setting off the alarm system, you must check out the book, CD, or video tape you wish to take home. So you present your library card to, you guessed it, the librarian, who will use your card to access the library database to see if you owe any late fees, and to register these new materials as having been leased to you. In this case, the librarian could be seen as a book factory because the librarian controls your access to the books.

How Does a Factory Work in Java RMI?

Just like any other Java RMI program, there are a few basic players: a server that produces one or more remote objects, each of which implements a remote interface; a client that accesses a name server (the rmiregistry) to get a reference to one of the remote objects; and the rmiregistry, which facilitates the client's initial contact with the server.

For the picture below and the steps that follow, you may make the following assumptions:

  • There are two remote interfaces that the client understands, Factory and Product
  • The FactoryImpl implements the Factory interface and the ProductImpl implements the Product interface
Illustrates the 6 actions listed below.

  1. The FactoryImpl registers, or is registered, with the rmiregistry
  2. The client requests a reference to a Factory
  3. The rmiregistry returns a remote reference to a FactoryImpl
  4. The client invokes a remote method on the FactoryImpl to obtain a remote reference to a ProductImpl
  5. The FactoryImpl returns a remote reference to an existing ProductImpl or to one that it just created, based on the client request
  6. The client invokes a remote method on the ProductImpl

How Could the Bank and Library be Implemented in Java RMI?

The Bank

In code, AccountManager would be a remote interface with one or more remote methods. These methods would return objects that implement the Account interface. In a similar fashion, Account would be an interface that declared all of the operations a person could perform on an account instance, such as depositing or withdrawing money, getting an account balance, or listing the most recent account transactions.

In Java RMI, only the instance of the AccountManager implementation would be registered with the Java RMI registry. The AccountManager implementation would be the factory, returning remote references to (or serialized instances of) Account implementations, like your savings account.

The Library

In the library example, the Librarian would be a remote interface with one or more methods that would return objects that implement the LibraryCard interface. In addition, the Librarian interface would have methods to allow you access to books, CDs, or videotapes that implemented the Loanable interface.

In Java RMI, only the instance of the Librarian implementation would be registered with the Java RMI registry. The Librarian implementation would be the factory, returning remote references to (or serialized instances of) LibraryCard implementations and Loanable object implementations.

While the bank and library examples presented here may not be entirely complete they are not designed to be complete, but rather instructionally useful in describing the factory pattern in Java RMI.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com 		Sun
Java Software


Dynamic code downloading using Java RMI

Dynamic code downloading using JavaTM RMI
(Using the java.rmi.server.codebase Property)

This tutorial is organized as follows:

  1. Starting out
  2. What is a codebase?
  3. How does it work?
  4. Using codebase in Java RMI for more than just stub downloading
  5. Command-line examples
  6. Troubleshooting tips

1.0 Starting out

One of the most significant capabilities of the JavaTM platform is the ability to dynamically download Java software from any Uniform Resource Locator (URL) to a virtual machine (VM) running in a separate process, usually on a different physical system. The result is that a remote system can run a program, for example an applet, which has never been installed on its disk. For the first few sections of this document, codebase with regard to applets will be discussed in order to help describe codebase with regard to Java Remote Method Invocation (Java RMI).

For example, a VM running from within a web browser can download the bytecodes for subclasses of java.applet.Applet and any other classes needed by that applet. The system on which the browser is running has most likely never run this applet before, nor installed it on its disk. Once all the necessary classes have been downloaded from the server, the browser can start the execution of the applet program using the local resources of the system on which the client browser is running.

Java RMI takes advantage of this capability to download and execute classes and on systems where those classes have never been installed on disk. Using the Java RMI API any VM, not only those in browsers, can download any Java class file including specialized Java RMI stub classes, which enable the execution of method calls on a remote server using the server system's resources.

The notion of a codebase originates from the use of ClassLoaders in the Java programming language. When a Java program uses a ClassLoader, that class loader needs to know the location(s) from which it should be allowed to load classes. Usually, a class loader is used in conjunction with an HTTP server that is serving up compiled classes for the Java platform. Most likely, the first ClassLoader/codebase pairing that you came into contact with was the AppletClassLoader, and the "codebase" part of the <applet> HTML tag, so this tutorial will assume that you have some experience with Java RMI programming, as well as writing HTML files that contain applet tags. For example, the HTML source will contain something like:

<applet height=100 width=100 codebase="myclasses/" code="My.class">
    <param name="ticker">
</applet>

2.0 What is a codebase?

A codebase can be defined as a source, or a place, from which to load classes into a virtual machine. For example, if you invited a new friend over for dinner, you would need to give that friend directions to the place where you lived, so that he or she could locate your house. Similarly, you can think of a codebase as the directions that you give to a VM, so it can find your [potentially remote] classes.

You can think of your CLASSPATH as a "local codebase", because it is the list of places on disk from which you load local classes. When loading classes from a local disk-based source, your CLASSPATH variable is consulted. Your CLASSPATH can be set to take either relative or absolute path names to directories and/or archives of class files. So just as CLASSPATH is a kind of "local codebase", the codebase used by applets and remote objects can be thought of as a "remote codebase".

3.0 How does it work?

3.1 How codebase is used in applets

To interact with an applet, that applet and any classes that it needs to run must be accessible by remote clients. While applets can be accessed from "ftp://" or local "file:///" URLs, they are usually accessed from a remote HTTP server.

  1. The client browser requests an applet class that is not found in the client's CLASSPATH
  2. The class definition of the applet (and any other class(es) that it needs) is downloaded from the server to the client using HTTP
  3. The applet executes on the client
illustrates three steps above

Figure 1: Downloading applets

The applet's codebase is always relative to the URL of the HTML page in which the <applet> tag is contained.

3.2 How codebase is used in Java RMI

Using Java RMI, applications can create remote objects that accept method calls from clients in other VMs. In order for a client to call methods on a remote object, the client must have a way to communicate with the remote object. Rather than having to program the client to speak the remote object's protocol, Java RMI uses special classes called stubs that can be downloaded to the client that are used to communicate with (make method calls on) the remote object. The java.rmi.server.codebase property value represents one or more URL locations from which these stubs (and any classes needed by the stubs) can be downloaded.

Like applets, the classes needed to execute remote method calls can be downloaded from "file:///" URLs, but like applets, a "file:///" URL generally requires that the client and the server reside on the same physical host, unless the file system referred to by the URL is made available using some other protocol, such as NFS.

Generally, the classes needed to execute remote method calls should be made accessible from a network resource, such as an HTTP or FTP server.

illustrates the first 5 steps of the stub downloadling process, as listed below

Figure 2: Downloading Java RMI stubs

  1. The remote object's codebase is specified by the remote object's server by setting the java.rmi.server.codebase property. The Java RMI server registers a remote object, bound to a name, with the Java RMI registry. The codebase set on the server VM is annotated to the remote object reference in the Java RMI registry.

  2. The Java RMI client requests a reference to a named remote object. The reference (the remote object's stub instance) is what the client will use to make remote method calls to the remote object.

  3. The Java RMI registry returns a reference (the stub instance) to the requested class. If the class definition for the stub instance can be found locally in the client's CLASSPATH , which is always searched before the codebase, the client will load the class locally. However, if the definition for the stub is not found in the client's CLASSPATH, the client will attempt to retrieve the class definition from the remote object's codebase.

  4. The client requests the class definition from the codebase. The codebase the client uses is the URL that was annotated to the stub instance when the stub class was loaded by the registry. Back in step 1, the annotated stub for the exported object was then registered with the Java RMI registry bound to a name.

  5. The class definition for the stub (and any other class(es) that it needs) is downloaded to the client.
    6. Note: Steps 4 and 5 are the sames steps that the registry took to load the remote object class, when the remote object was bound to a name in (registered with) the Java RMI registry. When the registry attempted to load the remote object's stub class, it requested the class definition from the codebase associated with that remote object.
  6. Now the client has all the information that it needs to invoke remote methods on the remote object. The stub instance acts as a proxy to the remote object that exists on the server; so unlike the applet which uses a codebase to execute code in its local VM, the Java RMI client uses the remote object's codebase to execute code in another, potentially remote VM, as illustrated in Figure 3:
illustrates the final step of the above procedure

Figure 3: Java RMI client making a remote method call

4.0 Using codebase in Java RMI for more than just stub downloading

In addition to downloading stubs and their associated classes to clients, the java.rmi.server.codebase property can be used to specify a location from which any class, not only stubs, can be downloaded.

When a client makes a method call to a remote object, the method that it calls could be written to accept no arguments or a number of arguments. There are three distinct cases that may occur, based on the data type(s) of the method argument(s).

In the first case, all of the method parameters (and return value) are primitive data types, so the remote object knows how to interpret them as method parameters, and there is no need to check its CLASSPATH or any codebase.

In the second case, at least one remote method parameter or the return value is an object, for which the remote object can find the class definition locally in its CLASSPATH.

In the third case (shown as Step 6, in Figure 4), the remote method receives an object instance, for which the remote object cannot find the class definition locally in its CLASSPATH. This type of remote method call is illustrated in Figure 4. The class of the object sent by the client will be a subtype of the declared parameter type. A subtype is either:

  • An implementation of the interface that is declared as the method parameter (or return) type

  • A subclass of the class that is declared as the method parameter (or return) type
Illustrates passing an unknown subtype as a method parameter, as described above and below.

Figure 4: Java RMI client making a remote method call, passing an unknown subtype as a method parameter

7. Like the applet's codebase, the client-specified codebase is used to download Remote classes, non-remote classes, and interfaces to other VMs. If the codebase property is set on the client application, then that codebase is annotated to the subtype instance when the subtype class is loaded by the client. If the codebase is not set on the client, the remote object will mistakenly use its own codebase.

5.0 Command-line examples

In the case of an applet, the applet codebase value is embedded in an HTML page, as we saw in the HTML example in the first section of this tutorial.

In the case of Java RMI codebase, rather than having a reference to the class embedded in an HTML page, the client first contacts the Java RMI registry for a reference to the remote object. Because the remote object's codebase can refer to any URL, not just one that is relative to a known URL, the value of the Java RMI codebase must be an absolute URL to the location of the stub class and any other classes needed by the stub class. This value of the codebase property can refer to:

  • The URL of a directory in which the classes are organized in package-named sub-directories

  • The URL of a JAR file in which the classes are organized in package-named directories

  • A space-delimited string containing multiple instances of JAR files and/or directories that meet the criteria above

Note: When the codebase property value is set to the URL of a directory, the value must be terminated by a "/".

Examples

If the location of your downloadable classes is on an HTTP server named "webvector", in the directory "export" (under the web root), your codebase property setting might look like this:

    -Djava.rmi.server.codebase=http://webvector/export/

If the location of your downloadable classes is on an HTTP server named "webline", in a JAR file named "mystuff.jar", in the directory "public" (under the web root), your codebase property setting might look like this:

    -Djava.rmi.server.codebase=http://webline/public/mystuff.jar

Now let's suppose that the location of your downloadable classes has been split between two JAR files, "myStuff.jar" and "myOtherStuff.jar". If these JAR files are located on different servers (named "webfront" and "webwave"), your codebase property setting might look like this:

    -Djava.rmi.server.codebase="http://webfront/myStuff.jar http://webwave/myOtherStuff.jar"

6.0 Troubleshooting tips

Any serializable class, including Java RMI stubs, can be downloaded if your Java RMI programs are configured properly. Here are the conditions under which dynamic stub downloading will work:

  1. The stub class and any of the classes that the stub relies on are served up from a URL reachable from the client.

  2. The java.rmi.server.codebase property has been set on the server program (or in the case of activation, the "setup" program) that makes the call to bind or rebind, such that:

    • The value of the codebase property is the URL in step A

      and

    • If the URL specified as the value of the codebase property is a directory, it must end in a trailing "/"

  3. The rmiregistry cannot find the stub class or any of the classes that the stub relies on in its CLASSPATH. This is so the codebase gets annotated to the stub when the registry does its class load of the stub, as a result of calls to bind or rebind in the server or setup code.

  4. The client has installed a SecurityManager that allows the stub to be downloaded. In the Java 2 SDK, Standard Edition, v1.2 and later, this means that the client must also have a properly configured security policy file.

There are two common problems associated with the java.rmi.server.codebase property, which are discussed next.

6.1 If you encounter a problem running your Java RMI server

The first problem you might encounter is the receipt of a ClassNotFoundException when attempting to bind or rebind a remote object to a name in the registry. This exception is usually due to a malformed codebase property, resulting in the registry not being able to locate the remote object's stubs or other classes needed by the stub.

It is important to note that the remote object's stub implements all the same interfaces as the remote object itself, so those interfaces, as well as any other custom classes declared as method parameters or return values, must also be available for download from the specified codebase.

Most frequently, this exception is thrown as a result of omitting the trailing slash from the URL value of the property. Other reasons would include: the value of the property is not a URL; the path to the classes specified in the URL is incorrect or misspelled; the stub class or any other necessary classes are not all available from the specified URL.

The exception that you may encounter in such a case would look like this:

java.rmi.ServerException: RemoteException occurred in server thread; nested exception is:
    java.rmi.UnmarshalException: error unmarshalling arguments; nested exception is:
    java.lang.ClassNotFoundException: examples.callback.MessageReceiverImpl_Stub
java.rmi.UnmarshalException: error unmarshalling arguments; nested exception is:
    java.lang.ClassNotFoundException: examples.callback.MessageReceiverImpl_Stub
java.lang.ClassNotFoundException: examples.callback.MessageReceiverImpl_Stub
    at sun.rmi.transport.StreamRemoteCall.exceptionReceivedFromServer(Compiled Code)
    at sun.rmi.transport.StreamRemoteCall.executeCall(Compiled Code)
    at sun.rmi.server.UnicastRef.invoke(Compiled Code)
    at sun.rmi.registry.RegistryImpl_Stub.rebind(Compiled Code)
    at java.rmi.Naming.rebind(Compiled Code)
    at examples.callback.MessageReceiverImpl.main(Compiled Code)
RemoteException occurred in server thread; nested exception is:
    java.rmi.UnmarshalException: error unmarshalling arguments; nested exception is:
    java.lang.ClassNotFoundException: examples.callback.MessageReceiverImpl_Stub

6.2 If you encounter a problem running your Java RMI client

The second problem you could encounter is the receipt of a ClassNotFoundException when attempting to lookup a remote object in the registry. If you receive this exception in a stacktrace resulting from an attempt to run your Java RMI client code, then your problem is the CLASSPATH with which your Java RMI registry was started. See requirement C in section 6.0. Here is what the exception will look like:

java.rmi.UnmarshalException: Return value class not found; nested exception is:
    java.lang.ClassNotFoundException: MyImpl_Stub
    at sun.rmi.registry.RegistryImpl_Stub.lookup(RegistryImpl_Stub.java:109
    at java.rmi.Naming.lookup(Naming.java:60)
    at RmiClient.main(MyClient.java:28)

Other resources

If you your codebase questions are still unanswered, please take a look through the archives of the rmi-users email list first.

You may wish to subscribe to the rmi-users email list.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com 		Sun
Java Software


Frequently Asked Questions - RMI and Object Serialization

Frequently Asked Questions
JavaTM RMI and Object Serialization

 Documentation Contents

Java RMI

Very Frequent Questions

  • A.1 Why do I get an exception for an unexpected hostname and/or port number when I call Naming.lookup?
  • A.2 Do I have to install the _Stub file in the client's CLASSPATH? I thought it could be downloaded.
  • A.3 Does JavaTM Remote Method Invocation (Java RMI) require me to use an HTTP server?
  • A.4 Why am I getting a ClassNotFoundException?
  • A.5 Why does the Java RMI implementation create so many sockets when my application uses custom socket factories; or why are stubs (using a custom socket factory) that refer to the same remote object not equal; or why does the Java RMI implementation not reuse server-side ports when I use a custom server socket factory?

Debugging Java RMI programs

  • B.1 Will there be debugging mechanisms built into Java RMI?
  • B.2 I am having a problem debugging my program on Windows 95. Any suggestions?
  • B.3 Why do I get a java.lang.ClassMismatchError while running my program?
  • B.4 I am sending an array of remote objects and receive an ArrayStoreException. What's going on?
  • B.5 I have local objects that are synchronized. When I make them remote, my application hangs. What's the problem?
  • B.6 I am getting a ClassNotFoundException for my stub class when I try to register a remote object in the registry. What's happening?
  • B.7 My server died. Can I get a trace of the server activity?
  • B.8 Where can I find a list of system properties that might be useful for implementing and debugging Java RMI applications?

Networking

  • C.1 How do Java RMI clients contact remote Java RMI servers?
  • C.2 Why does my remote method or "callback" routine fail with a nested java.net.UnknownHostException?
  • C.3 My server is using a fully qualified domain name or IP address, so why do I still get an UnknownHostException?
  • C.4 I am using the latest release of the JDK and I have a host that has multiple IP addresses. Java RMI is choosing the wrong IP address for its server hostname, how do I work around this problem?
  • C.5 How does Java RMI obtain a server hostname in each of the versions of the JDK?
  • C.6 Why do Naming.bind and Naming.lookup take an extraordinarily long time on Windows?
  • C.7 How do I use Java RMI on a Windows 95 standalone machine, not connected to the network?
  • C.8 Why do I get the exception "java.net.SocketException: Address already in use" when I try to run the registry?
  • C.9 How can I use Java RMI through a firewall?
  • C.10 How can I make outgoing Java RMI calls through a local firewall?
  • C.11 How can I receive incoming Java RMI calls through a local firewall?
  • C.12 So what do I have to do to get Java RMI to operate through two firewalls?
  • C.13 Is it possible to replace the java-rmi.cgi script that comes with the JDK distribution with a servlet?

Using Java RMI to achieve X (for some X)

  • D.1 Is there a way to get automatic notification as soon as a remote virtual machine fails?
  • D.2 From within a virtual machine, can a new virtual machine be spawned on a remote machine?
  • D.3 Is it possible for a remote object to be notified when all clients disconnect?
  • D.4 Why doesn't my server program exit when all clients disconnect?
  • D.5 How does the distributed garbage collector detect a client that disconnects? Is it advisable to use System.exit for graceful client termination?
  • D.6 How can my server tell when a client crashes?
  • D.7 The unreferenced() method doesn't get called until ten minutes after I have stopped using the remote object! How can I shorten this delay?
  • D.8 Why can't I get an immediate notification when a client crashes?
  • D.9 How do I run the rmic command in a DOS batch file?
  • D.10 In a remote object implementation, how can I find the host name of the caller of a remote method?
  • D.11 Does RMI handle "out" and "inout" parameters (like CORBA)?
  • D.12 Normally in the Java programming language, it is possible to cast an interface instance to an instance of the class from which it was created and use the result. Why doesn't this work in Java RMI?

How does RMI work with X (for some X)

  • E.1 What if my browser does not support the J2SETM version I need?
  • E.2 Can I implement remote observer/observable objects in Java RMI?

Internals, resources, and performance

  • F.1 At what point is there a "live" connection between the client and the server and how are connections managed?
  • F.2 Does the Java platform replace all remote objects with their stubs during a remote method invocation?
  • F.3 Is it possible to write a new transport layer for Java RMI which does not use sockets? As a follow-up question, how about a transport layer that uses non-TCP based sockets?
  • F.4 I notice the registry continues to use CPU resources, as if it were polling rather than blocking on a select() call. Is the registry implemented by polling?
  • F.5 Is there only one socket connection between a client process and the server, no matter how many stubs exist in that client process?

Miscellaneous

  • G.1 What are the licensing issues surrounding the use of Java RMI?
  • G.2 I have a single-threaded program that waits on standard input for a user command which will initiate an Java RMI call. However, my remote object cannot service this incoming remote call as the program appears to be blocked on standard input. What's the problem?
  • G.3 I am copying array elements to my remote server and changing the values, but the incremented values are not copied back to the client. Why?
  • G.4 Am I allowed to have static fields in a remote interface?
  • G.5 I locate the registry, but then it seems that it's not there, what's happening?
  • G.6 I can't find the answer to my question here, are there any other resources?

Object Serialization

  1. Why must classes implement Serializable in order to be written to an ObjectOutputStream?
  2. Which JDK v1.1 system classes are marked serializable?
  3. I am having problems deserializing AWT components. How can I make this work?
  4. Does object serialization support encryption?
  5. The object serialization classes are stream oriented. How do I write objects to a random-access file?
  6. When a local object is serialized and passed as a parameter in a Java RMI call, are the bytecodes for the local object's methods also passed? What about object coherency, if the remote virtual machine (VM) application "keeps" the object handle?
  7. How can I create an ObjectInputStream from an ObjectOutputStream without a file in between?
  8. I create an object and then send it across the net using the writeObject method and receive it using the readObject method. If I then change the value of a field in the object and send it as before, the object that the readObject method returns appears to be the same as the first object and does not reflect the new value of the field. Should I be experiencing this behavior?
  9. Are there any plans to support the serialization of thread objects?
  10. Can I compute diff(serial(x),serial(y))?
  11. Can I compress the serial representation of my objects using my own zip and unzip methods?
  12. Can I execute methods on compressed versions of my objects, for example isempty(zip(serial(x)))?
  13. If I try to serialize a font or image object and then try to reconstitute it in a different VM, my application dies. Why?
  14. How do I serialize a tree of objects?
  15. If class A does not implement Serializable but a subclass B implements Serializable, will the fields of class A be serialized when B is serialized?

Java RMI

A.1 Why do I get an exception for an unexpected hostname and/or port number when I call Naming.lookup?

The hostname and port number you see in the exception trace represent the address on which the looked-up server believes it is listening. While the JavaTM Remote Method Invocation (Java RMI) server can theoretically be on any host, it is usually the same host as that on which the registry is running, and on a different port.

Even if the server is mistaken about its hostname or IP address (or has a hostname that simply isn't resolvable by clients), it will still export all of its objects using that mistaken hostname, but you will see an exception every time you try to receive one of those objects.

The hostname which you specified in Naming.lookup to locate the registry has no effect on the hostname which is already embedded in the remote reference to the server.

Usually, the mysterious hostname is the unqualified hostname of the server, or a private name unknown to the client's nameservice, or (in the case of Windows platforms) the server's Network->Identification->Machine Name.

The appropriate workaround is to set the system property java.rmi.server.hostname when starting the server. The value of the property should be the externally reachable hostname (or IP address) of the server -- whatever works when specified as the host-part in Naming.lookup is good enough.

For more detail, see the questions on callbacks and fully qualified domain names.

A.2 Do I have to install the _Stub file in the client's CLASSPATH? I thought it could be downloaded.

A stub class can be downloaded, if the server that is exporting the remote object annotates the marshalled stub instance with the java.rmi.server.codebase property, which indicates the location from where the stub class can be loaded. You should set the java.rmi.server.codebase property on the server exporting a remote object. While remote clients could set this property, they would then be limited to only getting remote objects from the specified codebase. You should not assume that any client VM will have specified a codebase that resolves to the location of your object.

When a remote object is marshalled by Java RMI (whether as an argument to a remote call or as a return value), the codebase for the stub class is retrieved by Java RMI and used to annotate the serialized stub. When the stub is unmarshalled, the codebase is used to load the stub classfile using the RMIClassLoader, unless the class can already be found in the CLASSPATH or by the context classloader for the receiving object, such as an applet codebase.

If the _Stub class was loaded by an RMIClassLoader, then Java RMI already knows which codebase to use for its annotation. If the _Stub class was loaded from the CLASSPATH, then there is no obvious codebase, and Java RMI consults the java.rmi.server.codebase system property to find the codebase. If the system property is not set, then the stub is marshalled with a null codebase, which means that it cannot be used unless the client has a matching copy of the _Stub classfile in the client's CLASSPATH.

It is easy to forget to specify the codebase property. One way to detect this error is to start the rmiregistry separately and without access to the application classes. This will force Naming.rebind to fail if the codebase is omitted.

For more information on the java.rmi.server.codebase property, please take a look at our tutorial, Dynamic code downloading using Java RMI (Using the java.rmi.server.codebase Property).

A.3 Does Java RMI require me to use an HTTP server?

No. You can set your java.rmi.server.codebase property to use any valid URL protocol, such as file or ftp. Using an HTTP server just makes your life simpler by providing an automated mechanism for class file downloading. If you don't have access to an HTTP server nor the inclination to set one up, you can use our small class file server found at http://java.sun.com/products/jdk/rmi/class-server.zip.

A.4 Why am I getting a ClassNotFoundException?

Most likely the java.rmi.server.codebase property has not been set (or has not been set correctly) on a VM that is exporting your remote object(s). Please take a look at our tutorial, Dynamic code downloading using Java RMI (Using the java.rmi.server.codebase Property).

A.5 Why does the Java RMI implementation create so many sockets when my application uses custom socket factories; or why are stubs (using a custom socket factory) that refer to the same remote object not equal; or why does the Java RMI implementation not reuse server-side ports when I use a custom server socket factory?

The Java RMI implementation attempts to reuse open sockets where possible for remote invocations. When a remote method is invoked on a stub that uses a custom socket factory, the Java RMI implementation will reuse an open connection (if any) as long as that socket was created by an equivalent socket factory. Since client socket factories are serialized to clients, a single client may have several distinct copies of the same logical socket factory. To ensure that the Java RMI implementation will reuse sockets created by custom socket factories, make sure your custom client socket factory classes implement the hashCode and equals methods appropriately. If the client socket factory does not implement these methods correctly, another ramification is that stubs (using the client socket factory) that refer to the same remote object will not be equal.

The Java RMI implementation attempts to reuse server-side ports as well. It will only do so if there is an existing server socket for the port created by an equivalent socket factory. Make sure the server socket factory class implements the hashCode and equals methods too.

If your socket factory has no instance state, a trivial implementation of the hashCode and equals methods are the following:

    public int hashCode() { return 57; }
    public boolean equals(Object o) { return this.getClass() == o.getClass() }

B.1 Will there be debugging mechanisms built into Java RMI?

Java RMI supports a simple call-logging facility for debugging. But there are no current plans to support a full-featured, interactive, remote debugger.

B.2 I am having a problem debugging my program on Windows 95. Any suggestions?

The javaw command throws away output to stdout and stderr, so for debugging purposes it is better to run the java command in a separate window so that you can see reported errors. To do this, execute a command like the following:
        start java EchoImpl

It is advised not to use the javaw command during development. To watch the server activity, start the server with -Djava.rmi.server.logCalls=true.

B.3 Why do I get a java.lang.ClassMismatchError while running my program?

You probably modified one or more classes that were being used by Java RMI programs while your program was running. Try restarting all Java RMI applications (including java.rmi.registry.RegistryImpl). This should clear things up.

B.4 I am sending an array of remote objects and receive an ArrayStoreException. What's going on?

Java RMI replaces the remote objects with the stub and therefore the type of the array must be that of the interface. The code would look like:
   FooRemote[] f = new FooRemote[10];
   for (int i = 0; i < f.length; i++) {
      f[i] = new FooRemoteImpl();
   }

Now Java RMI can put the stub into each cell of the array without an exception on the remote call.

B.5 I have local objects that are synchronized. When I make them remote, my application hangs. What's the problem?

What you encountered was distributed deadlock. In the local VM case, the VM can tell that the calling object "A" owns the lock and will allow the call back to "A" to proceed. In the distributed case, no such determination can be made, so the result is deadlock.

Distributed objects behave differently than local objects. If you simply reuse a local implementation without handling locking and failure, you will probably get unpredictable results.

B.6 I am getting a ClassNotFoundException for my stub class when I try to register a remote object in the registry. What's happening?

When you make a call to the registry to bind an object, the registry actually binds a reference to the stub for the remote object. In order to instantiate a stub object, the registry VM needs to be able to load its class definition. The VM (in this case the server VM) that sends the serialized forms of a stub in a remote method call to the registry is responsible for annotating the stub with the location from which its classes can be downloaded. If stubs are not annotated properly, Java RMI will throw a ClassNotFoundException when it tries to instantiate the stub.

To annotate classes properly, the server needs to set the value of the java.rmi.server.codebase property value to the location(s) of the stub classes. Java RMI will automatically annotate the serialized form of outgoing object instances with the value of the java.rmi.server.codebase property.

NOTE: It is possible (and in a small number of environments appropriate) to enable the rmiregistry to unmarshal stub objects by placing all relevant stub class files in the CLASSPATH of the rmiregistry. However, the rmiregistry does not have to download stub classes. If stub classes are available locally, it will use those classes. Using the rmiregistry's CLASSPATH for stub deployment requires that all VMs that reference a stub instance obtained from that registry have the stub's class file installed locally (in the VM's CLASSPATH).

For example, if the registry loads stub classes from its CLASSPATH, when the registry sends serialized stub objects to other VMs, those serialized objects will be annotated with the value of the registry's java.rmi.server.codebase property (which will almost always be null). If the VMs receiving serialized stub objects from the registry do not have the class files for those stubs installed locally then those VMs are likely to throw a ClassNotFoundException.

Instead, if classes are downloaded dynamically from a server VM's java.rmi.server.codebase annotation, only the server VM needs to have the stub classes in its CLASSPATH. With this approach, application deployment is simpler and it is possible to introduce new stub versions into a running distributed system.

For more information on dynamic code downloading in Java RMI, please see the tutorial, Dynamic code downloading using Java RMI (Using the java.rmi.server.codebase).

B.7 My server died. Can I get a trace of the server activity?

To get a trace of the server activity, start the server as follows:
    java -Djava.rmi.server.logCalls=true YourServerImpl
where YourServerImpl is the name of your server. If your server has hung, you can get a monitor dump and thread dump by doing a ctrl-\ on the SolarisTM Operating System (Solaris OS) and a ctrl-break on Windows platforms.

B.8 Where can I find a list of system properties that might be useful for implementing and debugging Java RMI applications?

Properties that begin with "java.rmi." are elements of the public specification and are documented in the Java RMI Specification.

Properties that begin with "sun.rmi." are only supported by certain versions of the JavaTM SE Development Kit (JDK) software from Sun Microsystems. While these "sun.rmi.*" properties can be quite useful for debugging and tuning at runtime, please note that they are not considered part of the public API, and their use is subject to change (or may be removed completely) in future versions of the implementation.

C.1 How do Java RMI clients contact remote Java RMI servers?

Illustrates the means by which Java RMI clients contact remote Java RMI servers, as discussed below.

For an Java RMI client to contact a remote Java RMI server, the client must first hold a reference to the server. The Naming.lookup method call is the most common mechanism by which clients initially obtain references to remote servers. Remote references may be obtained by other means, for example: all remote method calls can return remote references. This is what Naming.lookup does; it uses a well-known stub to make a remote method call to the rmiregistry, which sends back the remote reference to the object requested by the lookup method.

Every remote reference contains a server hostname and port number that allow clients to locate the VM that is serving a particular remote object. Once a Java RMI client has a remote reference, the client will use the hostname and port provided in the reference to open a socket connection to the remote server.

Please note that with Java RMI the terms client and server can refer to the same program. A Java program that acts as a Java RMI server contains an exported remote object. A Java RMI client is a program that invokes one or more methods on a remote object in another virtual machine. If a VM performs both of these functions, it may be referred to as an RMI client and a Java RMI server.

C.2 Why does my remote method or "callback" routine fail with a nested java.net.UnknownHostException?

In many versions of the JDK (all versions of the JDK except in v1.1 and the latest releases), Java RMI may default to using an unresolvable server hostname (for example: unqualified names, Windows Internet Naming Service (WINS) names, or unqualified DHCP names). When a Java RMI client invokes a remote method using a reference that contains an unresolvable server hostname, the client will throw an UnknownHostException.

In order to generate functional remote references, Java RMI servers must be able to supply a fully qualified hostname or IP address that is resolvable from all Java RMI clients (an example of a fully qualified hostname is foo.bar.com). If a Java RMI program provides a remote callback operation, then that program serves a Java RMI object and consequently, must be able to determine a resolvable hostname to use as its server hostname in the remote references it passes to Java RMI clients. VMs that make calls to applets that serve remote objects may throw UnknownHostExceptions because the applet has failed to provide a usable server hostname.

If your Java RMI application throws an UnknownHostException, you can look at the resulting stack trace to see if the hostname that the client is using to contact its remote server is incorrect or not fully qualified. If necessary, you can set the java.rmi.server.hostname property on the server to the correct IP address or hostname of the server machine and Java RMI will use this property's value to generate remote references to the server.

C.3 My server is using a fully qualified domain name or IP address, so why do I still get an UnknownHostException?

Depending on the configuration of your network's name service, a fully qualified hostname that is recognized on one Java RMI host may not be resolvable from another Java RMI host. Some examples where this situation may arise are:
  • Misconfigured DHCP servers may set the fully qualified domain name of Java RMI server machines to be the domain name of the resolver domain instead of the domain in which the Java RMI server actually resides. In this case, Java RMI clients outside the server's DHCP domain will be unable to contact the server, because of its incorrect domain name.
  • The server machine is on a network that is configured to use WINS. Hosts that are only registered under WINS may not be reachable by hosts that rely solely upon DNS.
  • The Java RMI client and server reside on opposite sides of a firewall. If your Java RMI client lies outside a firewall and the server resides inside it, the client will not be able to make any remote calls to the server. If the Java RMI client lies inside the firewall, you will need to configure the Java RMI client to contact the server using HTTP.

C.4 I am using the latest release of the JDK and I have a host that has multiple IP addresses. Java RMI is choosing the wrong IP address for its server hostname. How do I work around this problem?

Set the java.rmi.server.hostname property to the correct IP address of the Java RMI server machine. You can also specify that your server use a fully qualified hostname obtained from a name service by setting the property:
    java.rmi.server.useLocalHostname=true

C.5 How does Java RMI obtain a server hostname in each of the versions of the JDK?

Methods that Java RMI uses to obtain a server hostname in each of the versions of the JDK:

JDK v1.1

Java RMI relied upon java.net.InetAddress.getLocalHost() to return a fully qualified domain name. InetAddress objects initialized local hostnames in a static block of code, performing a reverse lookup on the local IP address to retrieve a local hostname. However, on machines that were not connected to the network, this behavior caused the program to hang while InetAddress looked for a hostname that could not be found.

JDK v1.1.1-1.1.6

To work around the JDK v1.1 problem on stand-alone systems, InetAddress was modified in JDK v1.1.1 to only retrieve the [potentially unqualified] hostname returned from a native system call, which did not attempt to consult a name service. Java RMI was not modified to compensate for this change since the property java.rmi.server.hostname allowed users to override incorrect hostnames provided by InetAddress. Java RMI made no attempt to consult a name service and could default to using unqualified hostnames.

Later versions

To compensate for the many problems that were generated by the v1.1.1 change in functionality of InetAddress, the following behavior has been integrated into the most recent versions of the JDK:

Java RMI will use an IP address or a fully qualified domain name to identify a machine that serves a remote object. Server hostnames are initialized to the value obtained by performing the following actions:

  1. By default, Java RMI uses the IP address of the server host as the server name for remote references.
  2. If the property java.rmi.server.hostname is set, Java RMI will use its value as the server hostname, and will not attempt to find a fully qualified domain name through any other method. This property takes precedence over all other means of finding a Java RMI server name.
  3. If the property java.rmi.server.useLocalHostname is set to true (by default, the value of this property is false), Java RMI applies the following routine to obtain a hostname for the Java RMI server:
    1. If the value returned by the InetAddress.getLocalHost().getHostName() method contains a "." character, then Java RMI will assume that this value is the server's fully qualified domain name and will use it as the server hostname.
    2. Otherwise, Java RMI will spawn a thread to query the local name service for the fully qualified domain name of the Java RMI server. If the name service takes too long to return, or the name service returns but its response does not contain a "." then Java RMI will use the server's IP address obtained from InetAddress.getLocalHost().getHostAddress().
    Users can override the default time (10 seconds or 10000 milliseconds) that Java RMI will look for a fully qualified domain name by setting the following property:
    sun.rmi.transport.tcp.localHostnameTimeOut=timeOutMillis
    where timeOutMillis is the time that Java RMI will wait in milliseconds. For example:
                java -Dsun.rmi.transport.tcp.localHostnameTimeOut=2000 MyServerApp
When using activatable remote objects, it is recommended that Java RMI servers set the value of the java.rmi.server.useLocalHostname property to true. In general, hostnames are more stable than IP addresses. Activatable remote objects tend to last longer than transient remote objects (for example, surviving a reboot). A Java RMI client will be more likely to locate a remote object over a long period of time if it uses a qualified hostname rather than an explicit IP address.

C.6 Why do Naming.bind and Naming.lookup take an extraordinarily long time on Windows platforms?

Most likely, your host's networking setup is incorrect. Java RMI uses the Java API networking classes, in particular java.net.InetAddress, which will cause TCP/IP host name lookups - both host to address mapping and address to hostname mapping (the InetAddress class does this for security reasons). On Windows platforms, the lookup functions are performed by the native socket library, so the delays are happening not in Java RMI, but in the libraries. If your host is set up to use DNS, then it is usually a problem with the DNS server not knowing about the hosts involved in communication, and what you are experiencing are DNS lookup timeouts. Try specifying all the involved hostnames/addresses in the local file \winnt\system32\drivers\etc\hosts or \windows\hosts. The format of a typical host file is:
    IPAddress     Machine Name
e.g.:
    208.2.84.61   homer
This should dramatically cut down the time it takes to make the first lookup.

C.7 How do I use Java RMI on a Windows 95 standalone machine, not connected to the network?

To get Java RMI working on a Windows 95 machine that is not on a network, TCP/IP must be configured. One way to accomplish this is to configure an unused COM port as a dedicated PPP or SLIP connection. Then disable DHCP and manually configure an IP address (e.g. 192.168.1.1). You should then find that from a DOS Shell, you can ping yourself (for example, ping mymachine). You should now be able to use Java RMI on the machine.

C.8 Why do I get the exception "java.net.SocketException: Address already in use" when I try to run the registry?

This exception means that the port that the RegistryImpl uses (by default 1099) is already in use. You may have another registry running on your machine and will need to stop it.

C.9 How can I use Java RMI through a firewall?

It depends on whether you need to traverse a firewall for outgoing calls or for incoming calls.

C.10 How can I make outgoing Java RMI calls through a local firewall?

There are three main methods: HTTP tunnelling, SOCKS, and downloaded socket factories.

HTTP tunnelling

This well-worn method is popular since it requires almost no setup, and works quite well in firewalled environments which permit you to handle HTTP through a proxy, but disallow regular outbound TCP connections.

If Java RMI fails to make a normal (or SOCKS) connection to the intended server, and it notices that a HTTP proxy server is configured, it will attempt to tunnel Java RMI requests through that proxy server, one at a time.

There are two forms of HTTP tunnelling, tried in order. The first is http-to-port; the second is http-to-cgi.

In http-to-port tunneling, Java RMI attempts a HTTP POST request to a http: URL directed at the exact hostname and port number of the target server. The HTTP request contains a single Java RMI request. If the HTTP proxy accepts this URL, it will forward the POST request to the listening Java RMI server, which will recognize the request and unwrap it. The result of the call is wrapped in a HTTP reply, which is returned through the same proxy.

Often, HTTP proxies will refuse to proxy requests to unusual port numbers. In this case, Java RMI will fall back to http-to-cgi tunneling. The Java RMI request is encapsulated in a HTTP POST request as before, but the request URL is of the form http://hostname:80/cgi-bin/java-rmi.cgi?port=n (where hostname and n are the hostname and port number of the intended server). There must be a HTTP server listening on port 80 on the server host, which will run the java-rmi.cgi script (supplied with the JDK), which will in turn forward the request to a Java RMI server listening on port n. Java RMI can unwrap a HTTP-tunneled request without help from a http server, CGI script, or any other external entity. So, if the client's HTTP proxy can connect directly to the server's port, then you don't need a java-rmi.cgi script at all.

To trigger the use of HTTP tunneling, the standard system property http.proxyHost must be set to the hostname of the local HTTP proxy. (There are reports that some Navigator versions do not set this property.)

The major disadvantage of HTTP tunneling is that it does not permit inward calls or multiplexed connections. A secondary disadvantage is that the http-to-cgi method opens a dramatic security hole on the server side, since without modification it will redirect any incoming request to any port.

SOCKS

The default implementation of sockets in the JDK will use a SOCKS server if available and configured. The system property socksProxyHost must have been set to the hostname of the SOCKS server; if the port number of the SOCKS server is not 1080, it must be specified in the socksProxyPort property.

This approach would appear to be the most generally useful solution. As yet, ServerSockets do not use SOCKS, so incoming calls must use another mechanism.

Downloaded socket factories

This is an innovation in the JDK, allowing the server to specify the socket factory that the clients must use. The clients must be running J2SE v1.2 or later. See the tutorial Using Custom Socket Factories with Java RMI for details.

The disadvantage of this approach is that the traversal of the firewall must be done by code provided by the Java RMI server side, which does not necessarily know how that traversal must be done, nor does it automatically have sufficient privilege to traverse the firewall.

C.11 How can I receive incoming Java RMI calls through a local firewall?

There are three main methods: known ports, transport-level bridges, and application-level proxies.

Known Ports

If the exported objects are all exported on a known port on a known host, then that host and port can be explicitly permitted at the firewall. Normally, Java RMI asks for port 0 (which is code for "any port"). In the JDK, there is an extra argument to the exportObject method to specify the exact port number. In JDK v1.1, the server must subclass the RMISocketFactory and intercept requests to createServerSocket(0), replacing it with a request to bind to a specific port number.

This approach has the disadvantage that it requires the assistance of the network administrator responsible for the local firewall. If the exported object is being run in a different location (because code was downloaded to that site), then the local firewall may be run by network administrators who don't know who you are.

Transport-level bridges

A transport-level bridge is a program that reads bytes from one TCP connection and writes them to another (and vice versa) without knowing or caring what the bytes represent.

The idea here is to export objects in such a way that anyone outside the firewall who wants to call remote methods on that object instead contacts a different port (perhaps on a different machine). That different port has a running program which makes a second connection to the real server and then pumps bytes each way.

The tricky part is convincing the client to connect to the bridge. A downloadable socket factory (JDK, v1.2 or later) can do this efficiently; otherwise, it is possible to set the java.rmi.server.hostname property to name the bridge host and arrange for port numbers to be the same.

Application-level proxies

This approach is quite a bit of work, but leads to a very secure arrangement. A proxy program runs on a firewall host (one which can be accessed from outside as well as inside). When an internal server intends to make an exported object available to the world, it contacts the proxy server and gives it a remote reference. The proxy server creates a proxy object (a new remote object residing in the proxy server) which implements the same remote interfaces as the original. The proxy server returns a remote reference for the new proxy object to the internal server, which communicates it to the outside world (somehow).

When an outsider makes a call on the proxy, the proxy immediately forwards the call to its original object on the internal server. The use of the proxy is transparent to the outsider (but not to the internal server, who has to decide whether to pass the original reference or the proxy reference when talking to anyone).

Needless to say, this requires considerable setup and the cooperation of the local network administrators.

C.12 So what do I have to do to get Java RMI to operate through two firewalls?

First of all, what cooperation can you expect from the client-side firewall?

In the most pessimistic case, the client-side firewall allows no direct TCP connections and has only a HTTP proxy server so that firewalled clients can "surf the web". In this case, your server host will receive connections at port 80 containing Java RMI requests embedded in HTTP requests. You can use a HTTP server with the java-rmi.cgi program, or you can run the Java RMI server directly on port 80. Either way, the server cannot use callback objects exported by the clients..

A more optimistic case is that the client can make direct connections to the server but cannot receive incoming connections from the server. In this case, callback objects are not normally possible either.

The most conservative approach, assuming no help from the client firewall administrators, is:

  • Avoid using callback objects
  • Run your servers on `public' ports such as 80, 81, 8001, or 443
  • If the servers are not running on port 80, either:
    • Put a CGI-capable HTTP server on port 80 using the java-rmi.cgi script; or
    • Run a port redirector (such as DeleGate) on port 80, which will accept connections and immediately connect to the real server port to pass bytes back and forth. This will cause getClientHost() to return misleading information, so don't make the Registry available through this method unless it's on a different host.

C.13 Is it possible to replace the java-rmi.cgi script that comes with the JDK distribution with a servlet?

We've provided an example that demonstrates how to implement the java-rmi.cgi script using a servlet. The example also explains how to run a remote object inside a servlet VM.

Note: If you do not understand the role that java-rmi.cgi plays in tunnelling remote method calls over HTTP, please see the FAQ question regarding HTTP tunnelling in Java RMI.

D.1 Is there a way to get automatic notification as soon as a remote VM fails?

Not at this time.

D.2 From within a virtual machine, can a new virtual machine be spawned on a remote machine?

The JDK includes object activation, and there are several tutorials explaining how to use it.

D.3 Is it possible for a remote object to be notified when all clients disconnect?

Yes. Your remote object will need to implement the java.rmi.server.Unreferenced interface (in addition to any other necessary interfaces). Java RMI will provide the notification by calling the unreferenced method when all clients disconnect. Your implementation of the unreferenced method will determine what action your remote object should take upon receiving such a notification. However, if there is a reference in the registry, then the Unreferenced.unreferenced method will never be called.

D.4 Why doesn't my server program exit when all clients disconnect?

In Java RMI, a server VM should exit if there are
  • No outstanding client-held references to the remote objects in VM, and
  • No non-daemon threads executing in the VM.
However, just because there are no local or remote references to a remote object does not mean the object will be garbage collected in a timely fashion. It does mean that the remote object's memory can be collected to satisfy a memory allocation that would otherwise fail (with an OutOfMemoryError).

Although the Java API does not specify the timeliness of collection anyway, there is a particular reason for the what can seem like indefinitely delayed collection of remote objects in the JDK v1.1 implementation. Under the covers, the Java RMI runtime holds a weak reference to exported remote objects in a table (to keep track of local as well as remote references to the object). The only weak reference mechanism available in the JDK v1.1 VM uses a non-aggressive, caching collection policy (well-suited for a browser), so objects that are only "weakly reachable" will not get collected until the local GC decides that it really needs that memory to satisfy another allocation. For an idle server, this could never happen. But if memory is needed, an unreferenced server object will be collected.

The Java SE platform includes a new infrastructure that Java RMI will use to reduce significantly the number of conditions under which this problem occurs.

D.5 How does the distributed garbage collector detect a client that disconnects? Is it advisable to use System.exit for graceful client termination?

When the Java RMI runtime in a client VM detects that a remote object is no longer referenced locally, it asynchronously notifies the server relatively quickly so that the server can update the object's referenced set accordingly. The distributed garbage collector uses a lease associated with each client-held remote object reference, and renews leases to remote objects while the client still holds such references. The purpose of the lease renewal mechanism is to allow the server to detect the abnormal termination of clients, so that a server does not hold on to a remote object forever because of a client that was not able to send the appropriate "unreferenced" message before it stopped running. In this context, a client invoking System.exit() is considered abnormal termination, because it does not allow the RMI runtime to send the appropriate "unreferenced" messages to the server. Executing System.runFinalizersOnExit in the client before termination is not sufficient, because not all of the necessary processing is handled in a finalizer; i.e. the "unreferenced" message will not get sent to the server. (Using "runFinalizersOnExit" is generally ill-advised and deadlock-prone anyway.)

If you need to use System.exit() to terminate a client VM, to ensure that remote references held in that VM are cleaned up in a more timely fashion, you should make sure that there are no remote references still reachable. Explicitly null any local references to make them unreachable from running threads. It also may help to run a full garbage collection and to run finalizers before exiting:

    System.gc();
    System.runFinalization();

D.6 How can my server tell when a client crashes?

If you wait for the client's lease to run out, and the unreferenced() method will then be called by the Java RMI implementation (remember that the registry is also a client for this purpose, since it holds references for all its bindings).

If a client is holding a remote reference, it also holds a lease for that reference, which must be renewed (by contacting the server and making a dirty() call). When the final lease for an exported object has expired or closed, the object is considered unreferenced, and (if it implements java.rmi.Unreferenced) its unreferenced() method will be invoked.

If two or more clients have references to the same remote object, the unreferenced() method will not be called until all of them have expired their leases on it. Consequently, if you are using this technique to track individual clients, each client must have a reference to its own Unreferenced object.

D.7 The unreferenced() method doesn't get called until ten minutes after I have stopped using the remote object! How can I shorten this delay?

The lease expiration time is specified by the server, where it can be set using a system property, java.rmi.dgc.leaseValue, whose value is in milliseconds. To set this to a shorter time (for example: 30 seconds), start the server like this:
    java -Djava.rmi.dgc.leaseValue=30000 ServerMain

The default value is 600000 milliseconds (or 10 minutes).

The client will renew each lease when it is halfway expired. If the lease interval is too short, the client will waste a lot of network bandwidth needlessly renewing its lease. If the lease interval is much too short, the client will be unable to renew the lease in time, and the exported object may be deleted as a result.

Future releases of Java RMI may invalidate remote references if they fail to renew their leases (in order to preserve referential integrity); you should not rely on being able to use stale references to remote objects.

Note that you'll only have to wait for the timeout if the client machine crashes. If the client has some control when the disconnect occurs, it can send out the DGC clean call quickly, making the use of Unreferenced quite timely. You can help this process along by nulling out any references the client may have to the remote object and then calling System.gc(). (In v1.1.x, you may have to run finalizers synchronously and then run GC again.)

D.8 Why can't I get an immediate notification when a client crashes?

Because nothing the server does can distinguish a crashed host from a network delay.

If or when the crashed client later restarts and contacts the server, the server can infer that the client has lost its state. If a TCP connection is held open between the client and the server throughout their interaction, then the server can detect the client reboot when a later attempt to write to the connection fails (including the hourly TCP keepalive packet, if enabled). However, Java RMI is designed not to require such permanent connections, as it impairs scalability and doesn't help very much.

Given that it is absolutely impossible to instantly determine when a network peer crashes or becomes otherwise unavailable, you must decide how your application should behave when a peer stops responding.

The major tools you have for this task are timeouts and resets. After a timeout, you may conclude that a peer is unreachable, but the peer must be aware of the timeout so that it gives up trying to reach you. The leasing mechanism is designed to do this semi-automatically.

A reset is a purge of existing state held for a peer. For example, a client may cause a reset when it first registers with its server, causing the server to discard any previous state held for that client (having deduced that the client has restarted without memory of the previous, dead, session).

Frequently, the aim is to have and maintain a definitive list of clients at the server, and to keep it up-to-date without error or failure. Since failure and delay can happen at any time in a networked system, some degree of error in the list must be anticipated. If a lease or other mechanism is used to enforce a timeout, then the problem of resource leakage is solved. If the problem of stale data is more serious -- that is, if it would interfere with correct operation -- then it must be explicitly purged in cases where it would otherwise have an effect.

For example, if a business object is locked for editing by a human, and the session dies, then the lock must be broken somehow. In this case, the lock would need a timeout, but if the same human logs in immediately and expects not to have to wait for the timeout to expire, the new session must either take over the lock or assert that the user holds no locks (allowing the server to safely kill the lock).

D.9 How do I run the rmic command in a DOS batch file?

In a DOS batch file, you have to insert the command call before the executable in order for control to return to the batch file. For example:
    call rmic ClientHandler
    call rmic Server
    call rmic ServerHandler
    call rmic Client

D.10 In a remote object implementation, how can I find the host name of the caller of a remote method?

The java.rmi.server.RemoteServer.getClientHost method returns the client host for the current invocation on the current thread.

D.11 Does Java RMI handle "out" and "inout" parameters (like CORBA)?

Java RMI does not support "out" or "inout" parameters, just like the rest of the core Java programming language. All remote calls are methods of a remote object. Local objects are passed by copy and remote objects are passed by reference to a stub. For more details, see Parameter Passing in Remote Method Invocation in the Java RMI Specification.

D.12 Normally in the Java programming language, it is possible to cast an interface instance to an instance of the class from which it was created and use the result. Why doesn't this work in Java RMI?

In Java RMI the client sees only a stub for the original object. The stub implements only the remote interfaces and their remote methods and cannot be cast back to the original implementation class because it's just a stub.

So, you cannot pass a remote object reference from a server to a client, and then send it back to the server and be able to cast it back to the original implementation class. You can, though, use the remote object reference on the server to make a remote call to the object.

If you need to find the implementation class again, you'll need to keep a table that maps the remote reference to the implementation class.

E.1 What if my browser does not support the JDK or Java SE version I need?

Try using the Java Plug-in for browsers that do not support the JDK or Java SE version you need.

E.2 Can I implement remote observer/observable objects in Java RMI?

What you can do is "wrap" java.util.Observable and java.util.Observer with new interfaces (you could call them RemoteObservable and RemoteObserver). In these new interfaces, make each of the methods throw java.rmi.RemoteException. Then, your remote objects can implement these interfaces.

Note that since the "wrapped" non-remote object does not extend java.rmi.server.UnicastRemoteObject, you will need to explicitly export the object using the exportObject method of UnicastRemoteObject. In doing this though, you lose the java.rmi.server.RemoteObject implementations of the equals, hashCode, and toString methods.

F.1 At what point is there a "live" connection between the client and the server and how are connections managed?

When a client does a "lookup" operation, a connection is made to the rmiregistry on the specified host. In general, a new connection may or may not be created for a remote call. Connections are cached by the Java RMI transport for future use, so if a connection is free to the right destination for a remote call, then it is used. A client cannot explicitly close a connection to a server, since connections are managed at the Java RMI transport level. Connections will time out if they are unused for a period of time.

F.2 Does the Java platform replace all remote objects with their stubs during a remote method invocation?

The JRMP and Java RMI-IIOP implementations will replace each remote object with a corresponding stub (of the same protocol), even deep inside graphs of serializable objects.

F.3 Is it possible to write a new transport layer for Java RMI which does not use sockets? As a follow-up question, how about a transport layer that uses non-TCP-based sockets?

We have designed the transport interfaces so that different implementations of these interfaces can be used by Java RMI. In earlier releases, this abstraction was used for our purposes and was not exposed for general use. Now, in the JDK, Java RMI supports client and server socket factories that can be used to make Java RMI calls over non-TCP-based sockets.

F.4 I notice the registry continues to use CPU resources, as if it were polling rather than blocking on a select() call. Is the registry implemented by polling?

Java RMI does not poll on select calls. There is a thread that wakes up every so often and polls the table of exported remote objects. This "reap" thread is used for the purposes of the distributed garbage collector.

F.5 Is there only one socket connection between a client process and the server, no matter how many stubs exist in that client process?

Java RMI reuses the socket connections between client and server whenever possible. The current implementation creates additional sockets on demand when they are needed. For example, if the existing socket is in use by a call then a new socket is created for the new call. Typically, there are at least two sockets open since the distributed garbage collector needs to make remote calls when remote objects are returned from the server. If a cached connection remains unused for a period of time, the connection is closed.

G.1 What are the licensing issues surrounding the use of Java RMI?

Java RMI is part of the Java SE platform and as such is subject to the licensing terms of J2SE.

G.2 I have a single-threaded program that waits on standard input for a user command which will initiate a Java RMI call. However, my remote object cannot service this incoming remote call as the program appears to be blocked on standard input. What's the problem?

This is a known problem, not with Java RMI, but with the thread that reads standard input. The thread does not yield on the blocking read, but instead stays running, hardly letting the listener get any cycles. We have tried two workarounds that seem successful: set the main thread (the one reading standard input) to a lower priority, or yield while bytes are not available in the stream before actually reading it.

G.3 I am copying array elements to my remote server and changing the values, but the incremented values are not copied back to the client. Why?

Non-remote objects are passed by copy, so if you want to have the new values of the array reflected in the client, you will have to send them back as a return argument.

G.4 Am I allowed to have static fields in a remote interface?

Yes. An initializer is run in each VM that loads the remote interface, creating a new static variable with the specified values. So, you have a separate copy of this static variable in each VM that loads the remote interface.

G.5 I locate the registry, but then it seems that it's not there, what's happening?

The method LocateRegistry.getRegistry(String host) does not contact the registry on the host, but rather just looks up the host to make sure it exists. So, even though this method succeeded, this does not necessarily mean that a registry is running on the specified host. It just returns a stub that can then access the registry.

G.6 I can't find the answer to my question here, are there any other resources?

A vast amount of information can be found from the hypermail archive of the RMI-USERS mailing list.

Users of both Java RMI and object serialization can discuss issues and tips with other users via the mailing list rmi-users@java.sun.com. You can subscribe by sending an email message containing the line

    subscribe RMI-USERS
to listserv@java.sun.com, and unsubscribe by sending a message containing the line
    unsubscribe RMI-USERS

Object Serialization

1. Why must classes implement Serializable in order to be written to an ObjectOutputStream?

The decision to require that classes implement the java.io.Serializable interface was not made lightly. The design called for a balance between the needs of developers and the needs of the system to be able to provide a predictable and safe mechanism. The most difficult design constraint to satisfy was the safety and security of classes for the Java programming language.

If classes were to be marked as being serializable the design team worried that a developer, either out of forgetfulness, laziness, or ignorance might not declare a class as being Serializable and then make that class useless for RMI or for purposes of persistence. We worried that the requirement would place on a developer the burden of knowing how a class was to be used by others in the future, an essentially unknowable condition. Indeed, our preliminary design, as reflected in the alpha API, concluded that the default case for a class ought to be that the objects in the class be serializable. We changed our design only after considerations of security and correctness convinced us that the default had to be that an object not be serialized.

Security restrictions

The first consideration that caused us to change the default behavior of objects had to do with security, and in particular in the privacy of fields declared to be private, package protected, or protected. The Java platform restricts access to such fields for either read or write to a subset of the objects within the runtime.

No such restriction can be made on an object once it has been serialized; the stream of bytes that is the result of object serialization can be read and altered by any object that has access to that stream. This allows any object access to the state of a serialized object, which can violate the privacy guarantees users of the language expect. Further, the bytes in the stream can be altered in arbitrary ways, allowing the reconstruction of an object that was never created within the protections of a Java platform. There are cases in which the re-creation of such an object could compromise not only the privacy guarantees expected by users of the Java platform, but the integrity of the platform itself.

These violations cannot be guarded against, since the whole idea of serialization is to allow an object to be converted into a form that can be moved outside of the Java platform (and therefore outside of the privacy and integrity guarantees of that environment) and then be brought back into the environment. Requiring objects to be declared serializable does mean that the class designer must make an active decision to allow the possibility of such a breach in privacy or integrity. A developer who does not know about serialization should not be open to compromise because of this lack of knowledge. In addition, we would hope that the developer who declares a class to be serializable does so after some thought about the possible consequences of that declaration.

Note that this sort of security problem is not one that can be dealt with by the mechanism of a security manager. Since serialization is intended to allow the transport of an object from one virtual machine to some other (either over space, as it is used in RMI, or over time, as when the stream is saved to a file), the mechanisms used for security need to be independent of the runtime environment of any particular virtual machine. We wanted to avoid as much as possible the problem of being able to serialize an object in one virtual machine and not being able to deserialize that object in some other virtual machine. Since the security manager is part of the runtime environment, using the security manager for serialization would have violated this requirement.

Forcing a conscious decision

While security concerns were the first reason for considering the design change, a reason that we feel is at least as convincing is that serialization should only be added to a class after some design consideration. It is far too easy to design a class that falls apart under serialization and re-construction. By requiring a class designer to declare support for the serialization interface, we hoped that the designer would also give some thought to the process of serializing that class.

Examples are easy to cite. Many classes deal with information that only makes sense in the context of the runtime in which the particular object exists; examples of such information include file handles, open socket connections, security information, etc. Such data can be dealt with easily by simply declaring the fields as transient, but such a declaration is only necessary if the object is going to be serialized. A novice (or forgetful, or hurried) programmer might neglect to mark fields as transient in much the same way he or she might neglect to mark the class as implementing the Serializable interface. Such a case should not lead to incorrect behavior; the way to avoid this is to not serialize objects not marked as implementing Serializable.

Another example of this sort is the "simple" object that is the root of a graph that spans a large number of objects. Serializing such an object could result in serializing lots of others, since serialization works over an entire graph. Doing something like this should be a conscious decision, not one that happens by default.

The need for this sort of thought was brought home to us in the group when we were going through the base Java API class libraries, marking the system classes as serializable (where appropriate). We had originally thought that this would be a fairly simple process, and that most of the system classes could just be marked as implementing Serializable and then use the default implementation with no other changes. What we found was that this was far less often the case than we had suspected. In a large number of the classes, careful thought had to be given to whether or not a field should be marked as transient or whether it made sense to serialize the class at all.

Of course, there is no way to guarantee that a programmer or class designer is actually going to think about these issues when marking a class as serializable. However, by requiring the class to declare itself as implementing the Serializable interface we do require that some thought be given by the programmer. Having serialization be the default state of an object would mean that lack of thought could cause bad effects in a program, something that the overall design of the Java platform has attempted to avoid.

2. Which JDK v1.1 system classes are marked serializable?

Removed. This information is readily available from the API documentation generated by the javadoc tool.

3. I am having problems deserializing JDK v1.0.2 AWT components. How can I make this work?

When you serialize AWT widgets, also serialized are the Peer objects that map the AWT functions to the local window system. When you deserialize (reconstitute) the AWT widgets, the old Peers are re-created, but they are out of date. Peers are native to the local window system and contain pointers to data structures in the local address space, and therefore cannot be moved.

As a work around, you should first remove the top-level widget from its container (so the widgets are no longer "live"). The peers are discarded at this point and you will save only the AWT widget state. When you later deserialize and read the widgets back in, add the top level widget to the frame to make the AWT widgets appear. You may need to add a show call.

In JDK v1.1 and later, AWT widgets are serializable. The java.awt.Component class implements Serializable.

4. Does object serialization support encryption?

Object serialization does not contain any encryption/decryption in itself. It writes to and reads from standard streams in the Java API, so it can be coupled with any available encryption technology. Object serialization can be used in many different ways. Other than just writing and reading to and from files, it can also be used for Java RMI to communicate between hosts.

RMI's use of serialization leaves encryption and decryption to the lower network transport. We expect that when a secure channel is needed the network connections will be made using SSL or the like (see Using RMI with SSL).

5. The object serialization classes are stream oriented. How do I write objects to a random-access file?

Currently there is no direct way to write objects to a random-access file.

You can use ByteArrayInputStream and ByteArrayOutputStream objects as intermediate places to write and read bytes to and from the random access file and create ObjectInputStreams and ObjectOutputStreams from the byte streams to transport the objects. You just have to make sure that you have the entire object in the byte stream or reading/writing the object will fail.

For example, java.io.ByteArrayOutputStream can be used to receive the bytes of ObjectOutputStream. From it you can get a result in the form of a byte array. That in turn can be used with ByteArrayInputStream as input to an ObjectInput stream.

6. When a local object is serialized and passed as a parameter in a Java RMI call, are the bytecodes for the local object's methods also passed? What about object coherency, if the remote VM application "keeps" the object handle?

The bytecodes for a local object's methods are not passed directly in the ObjectOutputStream, but the object's class may need to be loaded by the receiver if the class is not already available locally. The class files themselves are not serialized, just the names of the classes. All classes must be able to be loaded during deserialization using the normal class loading mechanisms. For applets, this means they are loaded by the AppletClassLoader.

There are no coherency guarantees for local objects passed to a remote VM since such objects are passed by copying their contents (a true pass-by-value).

7. How can I create an ObjectInputStream from an ObjectOutputStream without a file in between?

ObjectOutputStream and ObjectInputStream work to/from any stream object. You could use a ByteArrayOutputStream and then get the array and insert it into a ByteArrayInputStream. You could also use the piped stream classes as well. Any java.io class that extends the OutputStream and InputStream classes can be used.

8. I create an object and then send it across the net using the writeObject method and receive it using the readObject method. If I then change the value of a field in the object and send it as before, the object that the readObject method returns appears to be the same as the first object and does not reflect the new value of the field. Should I be experiencing this behavior?

The ObjectOutputStream class keeps track of each object it serializes and sends only the handle if that object is seen again. This is the way it deals with graphs of objects. The corresponding ObjectInputStream keeps track of all of the objects it has created and their handles so when the handle is seen again it can return the same object. Both output and input streams keep this state until they are freed.

Alternatively, the ObjectOutputStream class implements a reset method that discards the memory of having sent an object, so sending an object again will make a copy.

9. Are there any plans to support the serialization of thread objects?

Threads will NOT be serializable. In the present implementation, if you attempt to serialize and then deserialize a thread, there is NO explicit allocation of a new native thread or stack; all that happens is that the object is allocated system resources with none of the native implementation. In short, it just won't work and will fail in unpredictable ways.

The difficulty with threads is that they have so much state which is intricately tied into the virtual machine that it is difficult or impossible to re-establish the context somewhere else. For example, saving the VM call stack is insufficient because if there were native methods that had called C procedures that in turn called code for the Java platform, there would be an incredible mix of Java programming language constructs and C pointers to deal with. Also, serializing the stack would imply serializing any object reachable from any stack variable.

If a thread were resumed in the same VM, it would be sharing a lot of state with the original thread, and would therefore fail in unpredictable ways if both threads were running at once, just like two C threads trying to share a stack. When deserialized in a separate VM, it's hard to tell what might happen.

10. Can I compute diff(serial(x),serial(y))?

The diff will produce the same stream each time the same object is serialized. You will need to create a new ObjectOutputStream to serialize each object.

11. Can I compress the serial representation of my objects using my own zip and unzip methods?

ObjectOutputStream produces an OutputStream; if your zip object extends the OutputStream class there is no problem compressing it.

12. Can I execute methods on compressed versions of my objects, for example isempty(zip(serial(x)))?

This is not really viable for arbitrary objects because of the encoding of objects. For a particular object (such as a String) you can compare the resulting bit streams. The encoding is stable, in that every time the same object is encoded it is encoded to the same set of bits.

13. If I try to serialize a font or image object and then try to reconstitute it in a different VM, my application dies. Why?

Removed. Fonts are now serializable, but images are not.

14. How do I serialize a tree of objects?

Here's a brief example that shows how to serialize a tree of objects.

import java.io.*;

class tree implements java.io.Serializable {
    public tree left;
    public tree right;
    public int id;
    public int level;

    private static int count = 0;

    public tree(int depth) {
        id = count++;
        level = depth;
        if (depth > 0) {
            left = new tree(depth-1);
            right = new tree(depth-1);
        }
    }

    public void print(int levels) {
        for (int i = 0; i < level; i++)
            System.out.print("  ");
        System.out.println("node " + id);

        if (level <= levels && left != null)
            left.print(levels);

        if (level <= levels && right != null)
            right.print(levels);
    }

    public static void main (String argv[]) {

        try {
            /* Create a file to write the serialized tree to. */
            FileOutputStream ostream = new FileOutputStream("tree.tmp");
            /* Create the output stream */
            ObjectOutputStream p = new ObjectOutputStream(ostream);

            /* Create a tree with three levels. */
            tree base = new tree(3);

            p.writeObject(base); // Write the tree to the stream.
            p.flush();
            ostream.close();    // close the file.

            /* Open the file and set to read objects from it. */
            FileInputStream istream = new FileInputStream("tree.tmp");
            ObjectInputStream q = new ObjectInputStream(istream);

            /* Read a tree object, and all the subtrees */
            tree new_tree = (tree)q.readObject();

            new_tree.print(3);  // Print out the top 3 levels of the tree
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }
}

15. If class A does not implement Serializable but a subclass B implements Serializable, will the fields of class A be serialized when B is serialized?

Only the fields of Serializable objects are written out and restored. The object may be restored only if class A has a no-arg constructor that will initialize the fields of non-serializable supertypes. If the subclass has access to the state of the superclass it can implement writeObject and readObject to save and restore that state.

Talk with Java RMI developers via the mailing list RMI-USERS
To subscribe, send subscribe rmi-users to listserv@javasoft.com

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com 		Sun
Java Software


Java Remote Method Invocation

Java

Java Remote Method Invocation
(Java RMI)

 Documentation Contents

Overview

    Java Remote Method Invocation (Java RMI) enables the programmer to create distributed Java technology-based to Java technology-based applications, in which the methods of remote Java objects can be invoked from other Java virtual machines, possibly on different hosts. RMI uses object serialization to marshal and unmarshal parameters and does not truncate types, supporting true object-oriented polymorphism.

API Specification

  • java.rmi Package
  • java.rmi.dgc Package
  • java.rmi.registry Package
  • java.rmi.server Package
  • java.rmi.activation Package

Architecture and Functional Specification

  • Java RMI Specification

Tutorials

  • Getting Started
    The Getting Started Tutorial shows you the steps to follow to create a distributed version of the classic Hello World program using Java RMI. The Hello World applet makes a remote method call to the server from which it was downloaded to retrieve the message "Hello World!"
  • Using Custom Socket Factories with Java RMI
    The "Using Custom Socket Factories with Java RMI" tutorial shows you how to create a version of the distributed Hello World program in which the Java RMI runtime uses sockets of a type chosen by the programmer. This tutorial also includes a discussion of how Java RMI can be used over SSL sockets.
  • The Activation Tutorials
    • The Activation Tutorials describe how to use the Java RMI APIs to implement, to register, and to use activatable objects. Each tutorial presents a different way to implement an activatable object. All tutorials use the same parameterized setup program that registers information about an activatable object with the Java RMI Activation System Daemon (rmid).
  • Configuring inetd to Launch rmid
    • The Internet services daemon inetd, supported on the Solaris Operating System (Solaris OS), provides an alternative to starting up services at system boot time. This daemon, a server process for Internet standard services, can be configured to start services on demand.
  • Designing Services to be Launched from inetd
    • This tutorial describes how to structure a service program (employing a specially exported local registry) so that the service can be started from inetd when clients connect to the service's local registry, and how to configure inetd to launch the service program.

  • Dynamic code downloading using Java RMI (Using the java.rmi.server.codebase Property)
    One of the most significant capabilities of the Java platform is the ability to dynamically download Java software from any URL to a VM running in a separate process, usually on a different physical system. The result is that a remote system can run a program, for example an applet, which has never been installed on its disk. This tutorial describes the use of dynamic code downloading in a Java system, and how it can be used with Java RMI.

  • The Java RMI trail of The Java Tutorial Continued
    This trail provides a brief overview of the Java RMI system and then walks through a complete client/server example that uses Java RMI's unique capabilities to load and to execute user-defined tasks at runtime. The server in the example implements a generic compute engine, which the client uses to compute the value of pi.

Enhancements

  • Java RMI Release Notes
    The release notes describe enhancements and changes to the Java RMI APIs and implementation, as well to the associated tools, rmic, rmiregistry, and rmid.

More Information

  • The Java RMI Home Page

  • Java RMI Tools (rmic, rmiregistry, rmid)

  • The Java RMI and Object Serialization FAQ

  • Search the archives of the RMI-USERS list

  • Subscribe to the RMI-USERS list

  • Useful java.rmi Properties

  • Useful sun.rmi Properties

  • Java RMI Implementation Logging

  • Applying the Factory Pattern to Java RMI

  • Using Java RMI with SSL

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com 		Sun
Java Software


Java RMI Implementation Logging

Java

JavaTM RMI Implementation Logging
in JDKTM 6

 Documentation Contents

As of JavaTM SE Development Kit (JDK) v1.4, Sun's Java Remote Method Invocation (Java RMI) implementation uses the Logging APIs to provide implementation logging output. The logging configuration file and programmatic API (java.util.logging) can be used to configure Java RMI implementation logging.

The java.rmi.server.logCalls system property and the implementation-specific sun.rmi.* logging properties that were recognized by previous JDK versions still function to set the default levels for the Java RMI implementation Logger objects and to cause their output to be directed to System.err as with earlier versions.

The table below shows the names of the Logger objects used by the Java RMI implementation and how they correspond to the logging properties supported by previous versions.

Note that the Java RMI implementation supports a logging category, client-side call logging, which is analogous to the server-side call logging activated by the java.rmi.server.logCalls property. Client-side call logging is output to the Logger named sun.rmi.client.call.

System Property Name | Logger Name | Information Logged
java.rmi.server.logCalls | sun.rmi.server.call | server-side remote calls and exceptions
sun.rmi.server.logLevel | sun.rmi.server.ref | server-side remote reference activity
sun.rmi.client.logCalls (new in J2SE 1.4) | sun.rmi.client.call | client-side remote calls and exceptions
sun.rmi.client.logLevel | sun.rmi.client.ref | client-side remote reference activity
sun.rmi.dgc.logLevel | sun.rmi.dgc | distributed garbage collection activity
sun.rmi.loader.logLevel | sun.rmi.loader | activity of default RMIClassLoader provider
sun.rmi.transport.logLevel | sun.rmi.transport.misc | transport-layer activity
sun.rmi.transport.tcp.logLevel | sun.rmi.transport.tcp | TCP binding and connection activity
sun.rmi.transport.proxy.logLevel | sun.rmi.transport.proxy | HTTP tunnelling activity
(none) | sun.rmi.runtime | miscellaneous runtime activity

For both the sun.rmi.client.call and the sun.rmi.server.call Loggers, exceptions thrown from remote calls are logged at the level Level.FINE, and each remote call is logged at the level Level.FINER. Setting the java.rmi.server.logCalls or sun.rmi.client.logCalls system properties to the value "true" causes the corresponding Logger to be set to the level Level.FINER.

For the sun.rmi.* logging properties that have names ending in ".logLevel", a value of "BRIEF" causes the corresponding Logger to be set to the level Level.FINE, and a value of "VERBOSE" causes the corresponding Logger to be set to the level Level.FINER. Use of the logging configuration file is now preferred over the use of these sun.rmi.* system properties for logging.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com

Sun
Java Software


Java RMI Release Notes

Java

JavaTM RMI Release Notes
for JDKTM 6

 RMI Contents
Enhancements in JavaTM SE Development Kit (JDK) 6
java.rmi.MarshalledObject now generic
The class MarshalledObject now has a type parameter representing the type of the contained serialized object.

Bug fix: Explicit TCP ports freed after remote objects unexported (4457683)
In previous releases, after a remote object had been exported on an explicit (non-anonymous) TCP port, the RMI implementation would keep a server socket bound to that port open for the lifetime of the virtual machine, regardless of the life cycle of remote objects exported on that port. This bug has been fixed so that after all remote objects that had been exported on a given non-anonymous port have become unexported (either explicitly or through distributed garbage collection) then the associated server socket will be closed. (There is an equivalent bug for anonymous TCP ports: 6279965.)

Bug fix: Garbage collection of client socket factories (4486732)
In previous releases, after a remote invocation was made on a remote stub containing a non-null RMIClientSocketFactory in a given virtual machine, then either that factory object or an equivalent factory object would remain forever reachable in the virtual machine, preventing it (and its defining class loader) from ever being garbage collected; this bug has been fixed. (There is an equivalent bug for socket factories used to export a remote object: 6332603.)

Default GC interval lengthed to one hour (6200091)
In previous releases, the maximum interval between garbage collections of the local heap enforced by the RMI implementation (while there are live remote references or exported remote objects), which is controlled by the system properties sun.rmi.dgc.client.gcInterval and sun.rmi.dgc.server.gcInterval, was one minute by default. The default interval is now one hour, to better accommodate applications with large heap sizes without special configuration.

Enhancements and Changes in Previous Releases
Dynamic Generation of Stub Classes (since 5.0)
This release adds support for the dynamic generation of stub classes at runtime, obviating the need to use the Java Remote Method Invocation (Java RMI) stub compiler, rmic, to pregenerate stub classes for remote objects. Note that rmic must still be used to pregenerate stub classes for remote objects that need to support clients running on earlier versions.

When an application exports a remote object (using the constructors or static exportObject methods1 of the classes java.rmi.server.UnicastRemoteObject or java.rmi.activation.Activatable) and a pregenerated stub class for the remote object's class cannot be loaded, the remote object's stub will be a java.lang.reflect.Proxy instance (whose class is dynamically generated) with a java.rmi.server.RemoteObjectInvocationHandler as its invocation handler.

An existing application can be deployed to use dynamically generated stub classes unconditionally (that is, whether or not pregenerated stub classes exist) by setting the system property java.rmi.server.ignoreStubClasses to "true". If this property is set to "true", pregenerated stub classes are never used.

Notes:

  • If a remote object has pre-5.0 clients, that remote object should use a stub class pregenerated with rmic or the client will get an ClassNotFoundException deserializing the remote object's stub. Pre-5.0 clients will not be able to load an instance of a dynamically generated stub class, because such a class contains an instance of RemoteObjectInvocationHandler, which was not available prior to this release.

  • Prior to the J2SE 5.0 release, exporting a remote object would throw a java.rmi.StubNotFoundException if the pregenerated stub class for the remote object's class could not be loaded. With the added support for dynamically generated stub classes, exporting a remote object that has no pregenerated stub class will silently succeed instead. A user deploying a server application to support pre-5.0 clients must still make sure to pregenerate stub classes for the server's remote object classes, even though missing stub classes are no longer reported at export time. Such errors will instead be reported to a pre-5.0 client when it deserializes a dynamically generated stub class.

1 The static method UnicastRemoteObject.exportObject(Remote) is declared to return java.rmi.server.RemoteStub and therefore cannot be used to export a remote object to use a dynamically generated stub class for its stub. An instance of a dynamically generated stub class is a java.lang.reflect.Proxy instance which is not assignable to RemoteStub.

Standard SSL/TLS Socket Factory Classes (since 5.0)
This release adds standard Java RMI socket factory classes, javax.rmi.ssl.SslRMIClientSocketFactory and javax.rmi.ssl.SslRMIServerSocketFactory, which communicate over the Secure Sockets Layer (SSL) or Transport Layer Security (TLS) protocols using the Java Secure Socket Extension (JSSE). These socket factory classes provide a simple way to use JSSE with Java RMI, enabling enforcement of integrity, confidentiality (through encryption), server authentication, and (optionally) client authentication for remote method invocations. For more information on how to use custom socket factories with Java RMI, see the tutorial "Using Custom Socket Factories with Java RMI". For more information on JSSE (including how to configure it), see the JSSE Reference Guide.

Launching rmid or a Java RMI Server from inetd/xinetd (since 5.0)
A new feature, provided by the System.inheritedChannel method, allows an application to obtain a channel (java.nio.channels.SocketChannel or java.nio.channels.ServerSocketChannel, for example) inherited from a process that launched the virtual machine (VM). Such an inherited channel can be used to either service a single incoming connection (in the case of a SocketChannel) or accept multiple incoming connections (in the case of ServerSocketChannel). Therefore, Java networking applications launched by inetd (Solaris(tm) Operating System) or xinetd (Linux) can now obtain the SocketChannel or ServerSocketChannel inherited from inetd/xinetd.

With the addition of this feature, the Java RMI activation daemon rmid has been enhanced to support being launched from inetd/xinetd so that rmid can be started up only when it receives an incoming connection. For details on the enhancements to rmid to support this feature, see the tools page for rmid (for the Solaris Operating System). For details on how to configure inetd to launch rmid, see the tutorial "Configuring inetd to Launch rmid".

An application using Java RMI can also be designed to be launched from inetd or xinetd. For an example on how to implement this technique, see the tutorial "Designing Services to be Launched from inetd."

rmic default stub protocol version option now -v1.2 (since 5.0)
When rmic is run without an option to specify the JRMP stub protocol version to be used by the generated classes, it now behaves as if the -v1.2 option were specified, instead of the -vcompat option as in previous releases.

This change means that by default, rmic does not generate any skeleton classes and generates stub classes that only implement the 1.2 stub protocol version. If a remote implementation class needs to be built to support clients running on JDK 1.1, then the -vcompat option must now be specified explicitly. (Also, note that as described above, if a remote implementation class does not need to support clients running on any release prior to 5.0, then rmic does not need to be run at all for that class.)

See the tools documentation for rmic [Solaris and Linux] [Windows] for more information about these command line options.

rmic no longer compiles arbitrary source files in the class path (since 5.0)
In previous releases, rmic would sometimes, while processing its input class files, attempt to compile arbitrary .java source files that it encountered in the class path. In 5.0, rmic does not attempt to compile any source files other than those for the stub, skeleton, or tie classes that it generates.

The expectation is that the remote implementation classes passed to rmic, as well as all classes and interfaces that they depend on, have already been successfully compiled with javac before rmic is run. If an existing build procedure depends on the previous behavior of rmic for compiling some of its application source files, then that build procedure will need to be modified to ensure that all necessary classes are correctly compiled with javac before running rmic.

Server-side Stack Traces Now Retained in Remote Exceptions (since 1.4)
The Java RMI runtime implementation will now preserve the server-side stack trace information of an exception that is thrown from a remote call, in addition to filling in the client-side stack trace as it did in previous releases. Therefore, when such an exception becomes accessible to client code, its stack trace will now contain all of its original server-side trace data followed by the client-side trace.

This feature is made possible by the new "programmatic access to stack trace information" feature of java.lang.Throwable in J2SE 1.4, which included making a Throwable's stack trace data part of its default serialized form. What the client-side Java RMI runtime implementation now does to cooperate with this feature is to append the client-side trace to the unmarshalled server-side trace, rather than simply overwriting with the client-side trace as it did in previous releases.

Certain server applications may wish to prevent any server-side stack trace data from accompanying an exception to be marshalled as the result of a remote call (as part of the exception's default serialized form in J2SE 1.4), perhaps for reasons of performance or confidentiality. In such cases, the implementation-specific system property

sun.rmi.server.suppressStackTraces
can be set to "true" to cause the server-side Java RMI runtime implementation to clear the stack traces of all exceptions thrown from the current virtual machine as the result of remote method invocations.

Service Provider Interface for RMIClassLoader (since 1.4)
Certain static methods of java.rmi.server.RMIClassLoader now delegate their behavior to an instance of a new service provider interface, java.rmi.server.RMIClassLoaderSpi. The service provider can be configured to augment the Java RMI dynamic class loading behavior for a given application. By default, the service provider implements the standard behavior of all of the static methods in RMIClassLoader. See the class documentation of RMIClassLoader and RMIClassLoaderSpi for more details.

Dynamic Server Host Name (since 1.4)
The java.rmi.server.hostname property can now be dynamically updated to indicate that future exports should use a new host name. Therefore, the new host name value will be contained in the stub for an object that is exported after the property is updated.

HTTP Fallback Is More Configurable (since 1.4.1)
The implementation-specific system property sun.rmi.transport.proxy.eagerHttpFallback has been added to allow additional control over when the Java RMI default socket factory will fall back to HTTP tunneling. This property configures the default socket factory so that any SocketException thrown by an initial (direct) connection attempt will trigger HTTP tunneling; this more "eager" fallback strategy can be useful when dealing with firewalls which deny instead of ignore connection attempts to unauthorized ports.

java.rmi.Naming.list Method No Longer Prepends a Scheme to Names Returned (since 1.4.1)
In previous releases, the Naming.list method prepended the scheme rmi: to each name contained in the returned array of strings. The Naming.list implementation now matches the specification, returning an array of names that are URL-formatted, but without the scheme component.

java.rmi.activation.ActivationGroupDesc (since 1.3)
The getClassName method, which returns the group's class name, can now return null, indicating the system's default group implementation. Previously, the getClassName method would return the name of the internal implementation class if the default group implementation was chosen when the descriptor was constructed.

Due to this change, if an application running in a 1.3 virtual machine registers an new activatable object with the ActivationSystem, rmid must also be upgraded to run 1.3, since a pre-1.3 rmid will not be able to activate the newly registered activatable object.

The Java RMI Stub Compiler, rmic (since 1.3)
By default, rmic [Solaris and Linux] [Windows] now assumes that the destination directory for generated stubs is the package-named subdirectory of the current working directory. If the "-d" option is not specified, the result is the same as though it were specified with the current working directory "." as an argument. The "-d" may still be used to override the default destination directory.

Two new options, "-idl" and "-iiop" have been added to generate IDL and stubs for IIOP, respectively.

The Java RMI Activation Daemon, rmid (since 1.3)
By default, rmid [Solaris and Linux] [Windows] now requires a security policy file.

Serializing remote objects (since 1.2.2)
Prior to 1.2.2, an attempt to pass an unexported remote object in a RMI call would result in a java.rmi.StubNotFoundException. This exception was a result of the RMI runtime's failure to locate a stub object during an attempt to replace a remote object implementation with its corresponding stub. In 1.2.2 and later releases, an unexported remote object passed in an RMI call will no longer result in an exception, but rather the remote object will be serialized instead of its stub. If the remote object implementation is not serializable, an attempt to pass an unexported object in an RMI call will result in a java.rmi.RemoteException with the nested exception java.io.NotSerializableException.
Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com

Sun
Java Software


java.rmi Properties

Please Note: Unless otherwise stated, any output from these properties is sent to System.err.

Properties that are useful to set on virtual machines (VMs) that export remote objects

java.rmi.activation.port
This property is used to set the TCP port number on which this VM should communicate with rmid (by default, rmid listens on port 1098, but can be set to listen on a different port by using the -port option on the rmid command line). The default value of this property is 1098, so this property only needs to be set on VMs that need to communicate with an instance of rmid that is running on a port other than 1098.

java.rmi.dgc.leaseValue
The value of this property represents the lease duration (in milliseconds) granted to other VMs that hold remote references to objects which have been exported by this VM. Clients usually renew a lease when it is 50% expired, so a very short value will increase network traffic and risk late renewals in exchange for reduced latency in calls to Unreferenced.unreferenced. The default value of this property is 600000 milliseconds (10 minutes).

java.rmi.server.codebase
This property specifies the locations from which classes that are published by this VM (for example: stub classes, custom classes that implement the declared return type of a remote method call, or interfaces used by a proxy or stub class) may be downloaded. The value of this property is a string in URL format or a space-separated list of URLs that will be the codebase annotation for all classes loaded from the CLASSPATH of (and subsequently marshalled by) this VM.

Note: This property must be set correctly in order to dynamically download classes and interfaces using JavaTM Remote Method Invocation (Java RMI). If this property is not set correctly, you will likely encounter exceptions when attempting to run your server or client. For more information on this property, see Dynamic code downloading using Java RMI (Using the java.rmi.server.codebase Property).

java.rmi.server.hostname
The value of this property represents the host name string that should be associated with remote stubs for locally created remote objects, in order to allow clients to invoke methods on the remote object. The default value of this property is the IP address of the local host, in "dotted-quad" format.

java.rmi.server.logCalls
If this value is true, incoming calls and exceptions thrown from incoming calls will be logged to System.err. Setting this property to true will greatly assist you in debugging your RMI programs. See also sun.rmi.server.exceptionTrace.

java.rmi.server.randomIDs
If this value is true, object identifiers for remote objects exported by this VM will be generated by using a cryptographically secure random number generator. The default value is false.

java.rmi.server.useCodebaseOnly
If this value is true, automatic loading of classes is prohibited except from the local CLASSPATH and from the java.rmi.server.codebase property set on this VM. Use of this property prevents client VMs from dynamically downloading bytecodes from other codebases. This property is ignored in the implementations of 1.2 and 1.2.1 because of a bug.

java.rmi.server.useLocalHostname
Java RMI now uses an IP address to identify the local host when the java.rmi.server.hostname property is not specified and a fully qualified domain name for the localhost cannot be obtained. In order to force Java RMI to use the fully qualified domain name by default, you need to set the this property to true.

Properties that are useful to set on VMs that make remote method calls

java.rmi.server.codebase
This property specifies the locations from which classes that are published by this VM (for example, custom classes that implement an interface that is the declared parameter type of a remote method call) may be downloaded. The value of this property is a string in URL format (or a space-separated list of URLs in 1.2 and later) that will be the codebase annotation for all classes loaded from the CLASSPATH of (and subsequently marshalled by) this VM.

Note: Classes that exist in both the server's codebase and the client's CLASSPATH will be loaded from the client's CLASSPATH, rather than from the server's codebase as intended. For more information on this property, see Dynamic code downloading using Java RMI (Using the java.rmi.server.codebase Property).

java.rmi.server.disableHttp
If this value is true, HTTP tunneling is disabled, even when http.proxyHost is set. The default value is false. If you know that your program will never need to use HTTP tunneling, then by disabling HTTP tunneling, you should see shorter timeouts for failed connections.

java.rmi.server.useCodebaseOnly
If this value is true, automatic loading of classes is prohibited except from the local CLASSPATH and from the java.rmi.server.codebase property set on this VM. Use of this property prevents client VMs from dynamically downloading bytecodes from other codebases. This property is ignored in the implementations of 1.2 and 1.2.1 because of a bug.
Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com

Sun
Java Software


Subscribing/Unsubscribing to the RMI-USERS List

To subscribe:
  • Send email to: listserv@java.sun.com
  • In the body of the message, type: subscribe RMI-USERS

    After subscribing, you can choose to receive all of the RMI-USERS daily email batched into just just a few email messages:

    • Send email to: listserv@java.sun.com
    • In the body of the message, type: set RMI-USERS digest

    If you decide at a later time that you'd rather receive all of the email messages individually:

    • Send email to: listserv@java.sun.com
    • In the body of the message, type: set RMI-USERS nodigest
To unsubscribe:
  • Send email to: listserv@java.sun.com
  • In the body of the message, type: signoff RMI-USERS

If you'd like to check out the RMI-USERS email archives, they can be found here.

You may also want to take a look at the answers to Frequently Asked Questions about Java RMI and Object Serialization.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com 		Sun
Java Software


sun.rmi Properties

WARNING: The properties described here are not supported, can change at any time, and only exist in certain implementations of JavaTM Remote Method Invocation (Java RMI) from Sun Microsystems. These properties are not part of the Java RMI public API. To see a list of the properties that are part of the public API, please refer to the page, java.rmi Properties.

Please Note: Unless otherwise stated, any output from these properties is sent to System.err.

Each of the properties that have names ending in ".logLevel" have possible values of "SILENT", "BRIEF", and "VERBOSE". These values are case insensitive and may be abbreviated as a string containing the first n letters, where n is greater than or equal to 1. If not specified, these properties have a default value of "SILENT". A value of "BRIEF" causes the corresponding Logger to be set to the level Level.FINE, and a value of "VERBOSE" causes the corresponding Logger to be set to the level Level.FINER. Use of the logging configuration file is now preferred over the use of these sun.rmi.* system properties for logging.

Logging messages are sent to System.err. For instance, if a property is said to send output to the "transport" log, this means that logging messages are sent to a LogStream returned by java.rmi.server.LogStream.log("transport"), which sends messages to System.err, unless you've set it to something else.

Properties that can be set on rmid

sun.rmi.activation.execPolicy (1.3 and later)
The value of this property controls the policy that rmid uses to determine whether or not the information in an ActivationGroupDesc may be used to launch a virtual machine for an activation group. The possible values for the property are default, none, or the fully qualified name of a class that implements a method named checkExecCommand that is called to verify ActivationGroupDesc information. For details, see the tools documentation for rmid [Solaris and Linux] [Windows].

sun.rmi.activation.execTimeout (1.2 and later)
The value of this property represents the time (in milliseconds) that the activation system will wait for a spawned activation group to start up. Setting this property gives you the ability to shorten or lengthen the maximum time that rmid will wait for an activation group to start up. The default value is 30000 milliseconds (30 seconds).

sun.rmi.activation.groupThrottle (5.0 and later)
The value of this property represents the maximum number of activation group VMs that rmid will allow to be in the "spawning but not yet active" state simultaneously. If more VMs need to be started, they will queue up until one of the current spawn attempts either succeeds or times out. Note that this property does not limit the maximum number of active VMs; it is intended to smooth out sudden spikes of activity to avoid reaching operating system limits. While setting the value of this property to a lower number may result in a longer start-up time for rmid, and setting the value to a higher number could shorten the start-up time, setting this value too high can crash rmid, because your system may run out of resources. The default value is 3. In previous releases, this property was named sun.rmi.rmid.maxstartgroup which is no longer supported.

sun.rmi.activation.groupTimeout (5.0 and later)
The value of this property represents the time (in milliseconds) that rmid will wait after destroying an activation group's process before creating a new incarnation of the activation group. The default value is 60000 milliseconds (60 seconds).

sun.rmi.activation.snapshotInterval (1.2 and later)
This property controls the number of updates for which the activation system will wait before it serializes a snapshot of its state to the rmid log file on disk. An "update" refers to a persistent change in the state of the activation system (for example, the registration of an Activatable object) since the last snapshot was taken. Changing the value of this property can be used to make rmid re-start more quickly (by taking snapshots of the log more often) or to make rmid more efficient (by taking snapshots of the log less often). The value of this property is a positive integer value. The default value is 200.

sun.rmi.log.debug (1.2 and later)
If this value is true, details of rmid's logging activity are sent to System.err.

sun.rmi.server.activation.debugExec (1.2 and later)
If this value is true, the activation system will print out debugging information to the command line that is used for spawning activation groups. By default, the value is false, so debugging information is not printed.

Properties that are useful to set on VMs that export remote objects

sun.rmi.dgc.ackTimeout (1.4 and later)
The value of this property represents the length of time (in milliseconds) that the server-side Java RMI runtime will strongly refer to a remote object (or a reference to a remote object) that has been returned from the current virtual machine as part of the result of a remote method call, until it receives positive acknowledgment from the client that the remote reference has been fully received and processed. This timeout only applies to failure situations (in which the client fails to send the acknowledgment). Setting the value too low can increase the risk of a remote object being prematurely garbage collected when the only known reference to the remote object is the one in transit as part of the remote method call result. The maximum value is Long.MAX_VALUE. The default value is 300000 (five minutes).

sun.rmi.dgc.checkInterval (1.1 and later)
The value of this property represents (in milliseconds) how often the Java RMI runtime checks for expired DGC leases. The default value is half the value of the java.rmi.dgc.leaseValue property.

sun.rmi.dgc.logLevel (1.1 and later)
This property controls the logging of incoming and outgoing calls related to DGC lease granting, renewing, and expiration. It sends output to the "dgc" log.

sun.rmi.dgc.server.gcInterval (1.2 and later)
When it is necessary to ensure that unreachable remote objects are unexported and garbage collected in a timely fashion, the value of this property represents the maximum interval (in milliseconds) that the Java RMI runtime will allow between garbage collections of the local heap. The default value is 3600000 milliseconds (one hour).

sun.rmi.loader.logLevel (1.2 and later)
This property controls the logging of each class name and codebase, whenever the Java RMI runtime attempts to load a class as a result of unmarshalling either an argument or return value. This property sends output to the "loader" log.

sun.rmi.server.exceptionTrace (1.2 and later)
This property controls the output of server-side stack traces from exceptions and errors that are thrown by dispatched, incoming remote calls. If this value is true, exception stack traces will be printed. By default (false), exception and error stack traces are not printed.

sun.rmi.server.suppressStackTraces (1.4 and later)
If this value is true, the server-side Java RMI runtime implementation will clear the stack traces of all exceptions thrown from the current virtual machine as the result of remote calls. This property is useful for certain server applications that may wish to prevent any server-side stack trace data from accompanying an exception to be marshalled out as the result of an incoming remote call (as part of the exception's default serialized form in J2SE 1.4), perhaps for reasons of performance or confidentiality.

sun.rmi.transport.logLevel (1.1 and later)
This property controls detailed logging throughout the transport layer. It sends output to the "transport" log.

sun.rmi.transport.tcp.localHostNameTimeOut (1.1.7 and later)
The value of this property represents the time (in milliseconds) that the Java RMI runtime will wait to obtain a fully qualified domain name for the local host. The default value is 10000 milliseconds (10 seconds).

sun.rmi.transport.tcp.logLevel (1.1 and later)
This property provides detailed logging for the TCP-specific transport sub-layer. It sends output to the "tcp" log.

sun.rmi.transport.tcp.readTimeout (1.2.2 and later)
The value of this property represents the time (in milliseconds) used as an idle timeout for incoming TCP connections the Java RMI runtime uses. The value is passed to java.net.Socket.setSoTimeout. This property is used only for cases where a client has not dropped an unused connection as it should (see sun.rmi.transport.connectionTimeout). The default value is 2*3600*1000 milliseconds (two hours).

sun.rmi.transport.tcp.maxConnectionThreads (6 and later)
The value of this property controls the maximum size of the pool of threads used to handle incoming connections, and thus it places an upper bound on the number of incoming remote method invocations that can execute concurrently. Setting this property to a lower value may improve the throughput of a Java RMI server application under heavy load, but setting it too low may (depending on the nature of the application's remote invocation patterns) lead to deadlock or starvation. The default value is the maximum, Integer.MAX_VALUE, which effectively means no limit.

sun.rmi.transport.tcp.threadKeepAliveTime (6 and later)
The value of this property controls the amount of time that a thread in the pool of threads used to handle incoming connections will remain idle before terminating. The default value is 60000 milliseconds (one minute).

Properties that are useful to set on VMs that make remote method calls

sun.rmi.client.logCalls (1.4 and later)
If the value of this property is true, the sun.rmi.client.call logger will be set to the level Level.FINER. Remote calls are logged at the level Level.FINER, and exceptions from remote calls are logged at the level Level.FINE.

sun.rmi.dgc.cleanInterval (1.1 and later)
The value of this property represents the maximum length of time (in milliseconds) that the Java RMI runtime will wait before retrying a failed DGC "clean" call. The default value is 180000 milliseconds (three minutes).

sun.rmi.dgc.client.gcInterval (1.2 and later)
When it is necessary to ensure that DGC clean calls for unreachable remote references are delivered in a timely fashion, the value of this property represents the maximum interval (in milliseconds) that the Java RMI runtime will allow between garbage collections of the local heap. The default value is 3600000 milliseconds (one hour).

sun.rmi.loader.logLevel (1.2 and later)
This property controls the logging of each class name and codebase, whenever the Java RMI runtime attempts to load a class as a result of unmarshalling either an argument or return value. This property sends output to the "loader" log.

sun.rmi.server.logLevel (1.1 and later)
This property controls the logging of information related to outgoing calls, including some connection-reuse information. It sends output to the "transport" log.

sun.rmi.transport.connectionTimeout (1.1.6 and later)
The value of this property represents the period (in milliseconds) for which socket connections may reside in an "unused" state, before the Java RMI runtime will allow those connections to be freed (closed). The default value is 15000 milliseconds (15 seconds). See also sun.rmi.transport.tcp.readTimeout.

sun.rmi.transport.logLevel (1.1 and later)
This property controls detailed logging throughout the transport layer. It sends output to the "transport" log.

sun.rmi.transport.proxy.connectTimeout (1.1 and later)
The value of this property represents the maximum length of time (in milliseconds) that the Java RMI runtime will wait for a connection attempt (createSocket) to complete, before attempting to contact the server using HTTP. This property is only used when the http.proxyHost property is set and the value of java.rmi.server.disableHttp is false. The default value is 15000 milliseconds (15 seconds).

sun.rmi.transport.proxy.eagerHttpFallback (1.4.1 and later)
If this value is true and the java.rmi.server.disableHttp system property is not set, then the default global RMISocketFactory will fall back to HTTP tunneling when any java.net.SocketException is thrown from an initial (direct) connection attempt, as opposed to the default behavior of falling back to HTTP tunneling only if an initial connection attempt throws a java.net.UnknownHostException or java.net.NoRouteToHostException.

This setting can be useful when dealing with firewalls that deny (instead of ignore) connection attempts to unauthorized ports, resulting in java.net.ConnectionExceptions inside the client's default global RMISocketFactory. If this system property is not enabled, then such ConnectionExceptions will not trigger HTTP fallback, since they are neither UnknownHostExceptions nor NoRouteToHostExceptions. However, if this system property is enabled, then the ConnectionExceptions will cause HTTP fallback to occur, because ConnectionException is a subclass of SocketException.

sun.rmi.transport.proxy.logLevel (1.1 and later)
This property controls the logging of events (createSocket and createServerSocket) when the default RMISocketFactory class is used. This type of logging is likely to be useful for applications that use Java RMI over HTTP. Events in custom socket factories are not logged by this property. It sends some messages to the "proxy" log, and others to the "transport" log.

sun.rmi.transport.tcp.handshakeTimeout (1.4 and later)
The value of this property represents the length of time (in milliseconds) that the client-side Java RMI runtime will use as a socket read timeout when reading initial handshake data (protocol acknowledgment) when establishing a new JRMP connection. This property is used to configure how long the Java RMI runtime will wait before deciding that a TCP connection accepted by a remote server cannot actually be used, either because the entity listening on the remote host's port is not actually a Java RMI server, or because the server is somehow not functioning correctly. The maximum value is Integer.MAX_VALUE, and a value of zero indicates an infinite timeout. The default value is 60000 (one minute).

sun.rmi.transport.tcp.responseTimeout (1.4 and later)
The value of this property represents the length of time (in milliseconds) that the client-side Java RMI runtime will use as a socket read timeout on an established JRMP connection when reading response data for a remote method invocation. Therefore, this property can be used to impose a timeout on waiting for the results of remote invocations; if this timeout expires, the associated invocation will fail with a java.rmi.RemoteException. Setting this property should be done with due consideration, however, because it effectively places an upper bound on the allowed duration of any successful outgoing remote invocation. The maximum value is Integer.MAX_VALUE, and a value of zero indicates an infinite timeout. The default value is zero (no timeout).

sun.rmi.transport.tcp.logLevel (1.1 and later)
This property provides detailed logging for the TCP-specific transport sub-layer. It sends output to the "tcp" log.
Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com

Sun
Java Software


Extending Activatable

Using Activation: Extending Activatable

 Documentation Contents

This tutorial describes how to implement an activatable remote object by extending the class java.rmi.activation.Activatable. This tutorial uses a Setup program (described in the tutorial Using Activation: the Setup Program) that registers information about an activatable remote object with the JavaTM Remote Method Invocation (Java RMI) activation system daemon (rmid) and then binds a stub for that remote object in an rmiregistry so that clients can look it up. You may want to read that tutorial before this one.

This tutorial has the following steps:

  • Implement the activatable remote object
  • Implement the client
  • Compile the source files
  • Run the Setup program
  • Run the client

The files needed for this tutorial are:

  • MyRemoteInterface.java - a simple remote interface
  • ExtendsActivatable.java - an "activatable" implementation of the remote interface
  • Client.java - a client that uses the remote interface
  • client.policy - the security policy file for the client

Implement the activatable remote object

There are a few basic ways to implement an activatable remote object. This tutorial describes how to implement an activatable remote object by extending the class java.rmi.activation.Activatable which exports an activatable remote object during construction.

A remote object is activated when a client invokes a remote method on a stub for an activatable remote object. A stub for an activatable remote object contains the remote object's activation ID and information on how to contact the Java RMI activation system daemon (rmid) for the remote object. If the stub cannot connect to the last-known address (i.e., host/port) for the remote object, the stub will contact the remote object's activator (rmid) to activate the object. When rmid receives an activation request, it starts the remote object's activation group (or container) VM if the group is not already executing, and then rmid asks the group to make an instance of the remote object. Once the group constructs the remote object, it returns the remote object's stub to rmid which, in turn, returns the actual stub to the initiating stub so that the initiating stub can update its information on how to contact the remote object in the future.

Before any of this activation can take place, an application must register information about the activatable remote objects it needs to use. The following separate tutorial describes the information needed to activatate a remote object and how to register this information with rmid:

  • Using Activation: the Setup program

In this example, the activatable remote object implements the following remote interface examples.activation.MyRemoteInterface:

package examples.activation;

import java.rmi.*;

public interface MyRemoteInterface extends Remote {
    Object remoteMethod(Object obj) throws RemoteException;
}

The implementation class, examples.activation.ExtendsActivatable, for the activatable remote object is as follows:

package examples.activation;

import java.rmi.*;
import java.rmi.activation.*;

public class ExtendsActivatable
        extends Activatable
        implements MyRemoteInterface
{

    public ExtendsActivatable(ActivationID id, MarshalledObject data)
        throws RemoteException
    {
        super(id, 0);
    }

    public Object remoteMethod(Object obj) {
        return obj;
    }
}

The class ExtendsActivatable extends the class Activatable and implements the remote interface MyRemoteInterface.

The class ExtendsActivatable declares a special "activation" constructor that an activation group calls to construct an instance during the activation process. This special constructor takes two parameters:

  • The first parameter, ActivationID, is an identifier for the activatable remote object. When an application registers an activation descriptor with rmid, rmid assigns it an activation ID, which refers to the information associated with the descriptor. This same activation ID (also contained in the remote object's stub) is passed to this constructor when the remote object is activated.
  • The second parameter is a MarshalledObject that contains initialization data pre-registered with rmid. This initialization data may be a filename for the object's persistent state, for example. This example does not require any initialization data to construct the remote object.

The constructor simply calls a constructor in the superclass (Activatable) to export the object on an anoymous port.

Finally, the class implements the remote interface's single method, remoteMethod to return the object passed as an argument.

Implement the client

The Client program looks up a remote object's stub (one that implements the remote interface MyRemoteInterface) in the registry on the host supplied as the optional first argument, and then invokes the stub's remoteMethod method. When this client invokes a remote method on the stub acquired from the registry, the remote object will activate if not already active.

The source for the program is as follows:

package examples.activation;

import java.rmi.*;
import java.rmi.registry.*;

public class Client {

    public static void main(String args[])  throws Exception {

        String hostname = "localhost";
        if (args.length < 1) {
            System.err.println(
                "usage: java [options] examples.activation.Client <hostname>");
            System.exit(1);
        } else {
            hostname = args[0];
        }

        if (System.getSecurityManager() == null) {
            System.setSecurityManager(new SecurityManager());
        }

        String name = System.getProperty("examples.activation.name");
        Registry registry = LocateRegistry.getRegistry(hostname);
        MyRemoteInterface stub =
            (MyRemoteInterface) registry.lookup(name);
        System.err.println("Obtained stub from the registry.");

        System.err.println("Invoking remote method...");
        String result = (String) stub.remoteMethod("hello there!");
        System.err.println("Returned from remote call.");
        System.err.println("Result: " + result);
    }
}

This program should be run as follows:

java -cp clientDir                               \
     -Djava.security.policy=client.policy        \
     -Dexamples.activation.client.codebase=clientCodebase   \
     -Dexamples.activation.name=name             \
     examples.activation.Client [host]

where:

  • clientDir is the root directory for the client program (its class path),
  • client.policy is the security policy file for this program,
  • clientCodebase is the location (URL) for this program's class (used in granting permissions to this program in the client.policy file)
  • name is the name for the object's stub in the registry
  • host is the server's host

Note: rmid must be running on its default port, and rmiregistry must be running on its default port (both on the remote host) prior to running this program.

The following is an example client.policy file that grants the appropriate permissions for the activation examples:

grant codeBase "${examples.activation.client.codebase}" {

    // permissions to read system properties required by the client
    permission java.util.PropertyPermission "examples.activation.name","read";

    // permission to connect to the registry, activation system, and remote host
    permission java.net.SocketPermission "*:1024-","connect";
};

The codebase to which permissions are granted is a file URL specifying the location of the client's classes. This file URL is the value of the examples.activation.client.codebase system property, defined when the client program is run. The client needs two permissions:

  • java.util.PropertyPermission - to read the system property examples.activation.name that specifies the name for the stub in the registry
  • java.net.SocketPermission - to connect to the registry, activation system, and remote object's host

Compile the source files

The source files for this example can be compiled as follows:

javac -d implDir MyRemoteInterface.java ExtendsActivatable.java
javac -d clientDir MyRemoteInterface.java Client.java

where implDir is the destination directory to put the implementation's class files the class files in, and clientDir is the destination directory to put the client's class files in.

Run the Setup program

Once your implementation phase is complete, you need to register information about the activatable object so a client can use it. The Setup program, described by the tutorial Using Activation: the Setup Program, registers an activation descriptor for an activatable object with rmid, and then binds the remote object's stub in an rmiregistry so that clients can look it up.

To run the Setup program for this example, see the section Start rmid, rmiregistry, and the Setup program in the setup program tutorial, which describes how to start rmid, rmiregistry, and the Setup program itself.

After you run rmid and rmiregistry as instructed in the Setup tutorial, you will need to run the Setup program to register an activation descriptor for an activatable object that implements the class examples.activation.ExtendsActivatable. The following command line runs the Setup program, supplying an appropriate file URL for each codebase used:

java -cp setupDir:implDir                       \
     -Djava.security.policy=setup.policy                      \
     -Djava.rmi.server.codebase=file:/implDir/                \
     -Dexamples.activation.setup.codebase=file:/setupDir/     \
     -Dexamples.activation.impl.codebase=file:/impDir/        \
     -Dexamples.activation.name=examples.activation.MyRemoteInterface       \
     -Dexamples.activation.policy=group.policy                \
     examples.activation.Setup examples.activation.ExtendsActivatable

where:

  • setupDir is the root directory for the Setup program's class
  • implDir is the root directory for the implementation's classes
  • setup.policy is the security policy file for the Setup program
  • group.policy is the security policy file for the activation group

Note that the examples.activation.file system property does not need to be specified, because the ExtendsActivatable implementation class does not use it. Also note that each file URL above has the required trailing slash. Examples of group and setup policy files, suitable for this tutorial, are described in the setup tutorial, and are also listed below:

  • setup.policy
  • group.policy

The output from the Setup program should look like this:

Activation group descriptor registered.
Activation descriptor registered.
Stub bound in registry.

Run the client

Once you have successfully registered an activation descriptor for an ExtendsActivatable implementation, you can run the client program, which, during its first execution, will cause the activatable object to activate.

The following command line illustrates how to run the client program, specifying a file URL for the client codebase:

java -cp clientDir                                              \
     -Djava.security.policy=client.policy                       \
     -Dexamples.activation.client.codebase=file:/clientDir/     \
     -Dexamples.activation.name=examples.activation.MyRemoteInterface         \
     examples.activation.Client [host]

where:

  • clientDir is the root directory for the client program (its class path),
  • client.policy is the security policy file for this program,
  • name is the name for the object's stub in the registry
  • host is the server's host

Notes:

  • The client codebase must have a trailing slash.
  • The name must match the name supplied to the Setup program. In this example, we used the name examples.activation.MyRemoteInterface.
  • rmid and rmiregistry must be running on the server's host. If the server's host is not the local host, the host argument must specify the remote host that they are running on.

The output from the client should look like this:

Obtained stub from the registry.
Invoking remote method...
Returned from remote call.
Result: hello there!
Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com

Sun
Java Software


Not Extending Activatable

Using Activation: Not Extending Activatable

 Documentation Contents

This tutorial describes how to implement an activatable remote object, but differs from the tutorial Using Activation: Extending Activatable in that the implementation for the remote object does not extend the class java.rmi.activation.Activatable. Instead, the implementation uses a static method of the class Activatable to export an activatable remote object. This tutorial uses a Setup program (described in the tutorial Using Activation: the Setup Program) that registers information about an activatable remote object with the JavaTM Remote Method Invocation (Java RMI) activation system daemon (rmid) and then binds a stub for that remote object in an rmiregistry so that clients can look it up. You may want to read that tutorial before this one.

This tutorial has the following steps:

  • Implement the activatable remote object
  • Implement the client
  • Compile the source files
  • Run the Setup program
  • Run the client

The files needed for this tutorial are:

  • MyRemoteInterface.java - a simple remote interface
  • DoesNotExtendActivatable.java - an "activatable" implementation of the remote interface
  • Client.java - a client that uses the remote interface
  • client.policy - the security policy file for the client

Implement the activatable remote object

There are a few basic ways to implement an activatable remote object. This tutorial describes how to implement an activatable remote object by using a static method of the class java.rmi.activation.Activatable to export an activatable remote object.

A remote object is activated when a client invokes a remote method on a stub for an activatable remote object. A stub for an activatable remote object contains the remote object's activation ID and information on how to contact the Java RMI activation system daemon (rmid) for the remote object. If the stub cannot connect to the last-known address (i.e., host/port) for the remote object, the stub will contact the remote object's activator (rmid) to activate the object. When rmid receives an activation request, it starts the remote object's activation group (or container) VM if the group is not already executing, and then rmid asks the group to make an instance of the remote object. Once the group constructs the remote object, it returns the remote object's stub to rmid which, in turn, returns the actual stub to the initiating stub so that the initiating stub can update its information on how to contact the remote object in the future.

Before any of this activation can take place, an application must register information about the activatable remote objects it needs to use. The following separate tutorial describes the information needed to activatate a remote object and how to register this information with rmid:

  • Using Activation: the Setup program

In this example, the activatable remote object implements the following remote interface examples.activation.MyRemoteInterface:

package examples.activation;

import java.rmi.*;

public interface MyRemoteInterface extends Remote {
    Object remoteMethod(Object obj) throws RemoteException;
}

The implementation class, examples.activation.DoesNotExtendActivatable, for the activatable remote object is as follows:

package examples.activation;

import java.rmi.*;
import java.rmi.activation.*;

public class DoesNotExtendActivatable implements MyRemoteInterface {

    private final ActivationID id;

    public DoesNotExtendActivatable(ActivationID id, MarshalledObject data)
        throws RemoteException
    {
        this.id = id;
        Activatable.exportObject(this, id, 0);
    }

    public Object remoteMethod(Object obj) {
        return obj;
    }
}

The class DoesNotExtendActivatable implements the remote interface MyRemoteInterface, but does not extend any class.

The class DoesNotExtendActivatable declares a special "activation" constructor that an activation group calls to construct an instance during the activation process. This special constructor takes two parameters:

  • The first parameter, ActivationID, is an identifier for the activatable remote object. When an application registers an activation descriptor with rmid, rmid assigns it an activation ID, which refers to the information associated with the descriptor. This same activation ID (also contained in the remote object's stub) is passed to this constructor when the remote object is activated.
  • The second parameter is a MarshalledObject that contains initialization data pre-registered with rmid. This initialization data may be a filename for the object's persistent state, for example. This example does not require any initialization data to construct the remote object.

The constructor saves the activation ID in a private field, and then calls the static method Activatable.exportObject, passing the implementation itself (this), the activation ID, and the port number 0, indicating that the object should be exported on an anonymous TCP port. While this implementation does not actually use the activation ID it stores, this example saves the activation ID to demonstrate what a typical implementation of an activatable object might do. Such an implementation may need the activation ID in the future, in order to deactivate the object, for example.

Finally, the class implements the remote interface's single method, remoteMethod to return the object passed as an argument.

Implement the client

The Client program looks up a remote object's stub (one that implements the remote interface MyRemoteInterface) in the registry on the host supplied as the optional first argument, and then invokes the stub's remoteMethod method. The client program is the same as the one described in the tutorial Using Activation: Extending Activatable. For details, see the following section of that tutorial

  • Implement the client

Compile the source files

The source files for this example can be compiled as follows:

javac -d implDir MyRemoteInterface.java DoesNotExtendActivatable.java
javac -d clientDir MyRemoteInterface.java Client.java

where implDir is the destination directory to put the implementation's class files the class files in, and clientDir is the destination directory to put the client's class files in.

Run the Setup program

Once your implementation phase is complete, you need to register information about the activatable object so a client can use it. The Setup program, described by the tutorial Using Activation: the Setup Program, registers an activation descriptor for an activatable object with rmid, and then binds the remote object's stub in an rmiregistry so that clients can look it up.

To run the Setup program for this example, see the section Start rmid, rmiregistry, and the Setup program in the setup program tutorial, which describes how to start rmid, rmiregistry, and the Setup program itself.

After you run rmid and rmiregistry as instructed in the Setup tutorial, you will need to run the Setup program to register an activation descriptor for an activatable object that implements the class examples.activation.DoesNotExtendActivatable. The following command line runs the Setup program, supplying an appropriate file URL for each codebase used:

java -cp setupDir:implDir                       \
     -Djava.security.policy=setup.policy                      \
     -Djava.rmi.server.codebase=file:/implDir/                \
     -Dexamples.activation.setup.codebase=file:/setupDir/     \
     -Dexamples.activation.impl.codebase=file:/impDir/        \
     -Dexamples.activation.name=examples.activation.MyRemoteInterface       \
     -Dexamples.activation.policy=group.policy                \
     examples.activation.Setup examples.activation.DoesNotExtendActivatable

where:

  • setupDir is the root directory for the Setup program's class
  • implDir is the root directory for the implementation's classes
  • setup.policy is the security policy file for the Setup program
  • group.policy is the security policy file for the activation group

Note that the examples.activation.file system property does not need to be specified, because the DoesNotExtendActivatable implementation class does not use it. Also note that each file URL above has the required trailing slash. Examples of group and setup policy files, suitable for this tutorial, are described in the setup tutorial, and are also listed below:

  • setup.policy
  • group.policy

The output from the Setup program should look like this:

Activation group descriptor registered.
Activation descriptor registered.
Stub bound in registry.

Run the client

Once you have successfully registered an activation descriptor for a DoesNotExtendActivatable implementation, you can run the client program, which, during its first execution, will cause the activatable object to activate.

The client program is the same as the one described in the tutorial Using Activation: Extending Activatable. For details, see the following section of that tutorial:

  • Run the client
Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com

Sun
Java Software


Overview

Using Activation: Overview

 Documentation Contents
This set of tutorials describes how to use the JavaTM Remote Method Invocation (Java RMI) APIs to implement, to register, and to use activatable objects. Each tutorial presents a different way to implement an activatable object. All tutorials use the same parameterized setup program that registers information about an activatable object with the Java RMI Activation System Daemon (rmid).

The tutorials are as follows:

  • The Setup program

    A parameterized program for registering an activation descriptor for an activatable object with rmid, and binding a stub for that activatable object in a registry so that clients can look it up.

  • Extending Activatable

    An implementation that extends the class java.rmi.activation.Activatable, a class whose constructors export a remote object during construction.

  • Not Extending Activatable

    An implementation that does not extend the class Activatable, but instead uses its static methods to export a remote object.

  • Using Persistence

    An implementation that, during construction, uses a MarshalledObject in an object's activation descriptor to specify a file that contains the object's persistent state.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com

Sun
Java Software


Persistence

Using Activation: Persistence

 Documentation Contents

This tutorial describes how to implement an activatable remote object that uses persistent state in its implementation. This tutorial uses a Setup program (described in the tutorial Using Activation: the Setup Program) that registers information about an activatable remote object with the JavaTM Remote Method Invocation (Java RMI) activation system daemon (rmid) and then binds a stub for that remote object in an rmiregistry so that clients can look it up. You may want to read that tutorial before this one.

This tutorial has the following steps:

  • Implement the activatable remote object
  • Implement the client
  • Compile the source files
  • Run the Setup program
  • Run the client

The files needed for this tutorial are:

  • Counter.java - a remote interface for counting
  • CounterImpl.java - an "activatable" implementation of the remote interface
  • CounterClient.java - a client that uses the remote interface
  • client.policy - the security policy file for the client

Implement the activatable remote object

There are a few basic ways to implement an activatable remote object. This tutorial describes how to implement an activatable remote object that uses persistent state in its implementation.

A remote object is activated when a client invokes a remote method on a stub for an activatable remote object. A stub for an activatable remote object contains the remote object's activation ID and information on how to contact the Java RMI activation system daemon (rmid) for the remote object. If the stub cannot connect to the last-known address (i.e., host/port) for the remote object, the stub will contact the remote object's activator (rmid) to activate the object. When rmid receives an activation request, it starts the remote object's activation group (or container) virtual machine (VM) if the group is not already executing, and then rmid asks the group to make an instance of the remote object. Once the group constructs the remote object, it returns the remote object's stub to rmid which, in turn, returns the actual stub to the initiating stub so that the initiating stub can update its information on how to contact the remote object in the future.

Before any of this activation can take place, an application must register information about the activatable remote objects it needs to use. The following separate tutorial describes the information needed to activatate a remote object and how to register this information with rmid:

  • Using Activation: the Setup program

This example defines the remote interface Counter with a single operation, increment. The implementation class CounterImpl persistently stores the result of the operation increment in a file, so that the result of the increment operation will survive across an object activation/deactivation cycle or even survive a machine reboot or crash. To make all this work, a CounterImpl object, when activated, needs the name of the file it will use to read and store counter values. A user can register an activation descriptor that contains this file name (in a MarshalledObject) as the "initialization data". The object's activation group will pass this pre-registered marshalled data (the file name) to the object's constructor when the group constructs the object during activation.

The remote interface examples.activation.Counter is defined as follows:

package examples.activation;

import java.rmi.Remote;
import java.io.IOException;

public interface Counter extends Remote {

    int increment() throws IOException;
}

The implementation class, examples.activation.CounterImpl, for the activatable remote object is as follows:

package examples.activation;

import java.io.File;
import java.io.IOException;
import java.io.RandomAccessFile;
import java.rmi.MarshalledObject;
import java.rmi.activation.Activatable;
import java.rmi.activation.ActivationID;

public class CounterImpl implements Counter {
    private RandomAccessFile raf;
    private int count;
    private final Object countLock = new Object();

    public CounterImpl(ActivationID id, MarshalledObject data)
        throws Exception
    {
        if (data != null) {
            String filename = (String) data.get();
            synchronized (countLock) {
                count = openFile(filename);
            }
            System.err.println("count upon activation = " + count);
        }

        Activatable.exportObject(this, id, 0);
    }

    private int openFile(String filename) throws IOException {

        if (filename != null && !filename.equals("")) {
            File file = new File(filename);
            boolean fileExists = file.exists();
            raf = new RandomAccessFile(file, "rws");
            return (fileExists) ? raf.readInt() : writeCount(0);

        } else {
            throw new IOException("invalid filename");
        }
    }

    private int writeCount(int value) throws IOException {
        raf.setLength(0);
        raf.writeInt(value);
        return value;
    }

    public int increment() throws IOException {
        synchronized (countLock) {
            return writeCount(++count);
        }
    }
}

The class CounterImpl implements the remote interface Counter, but does not extend any class.

The class declares a special "activation" constructor that an activation group calls to construct an instance during the activation process. This special constructor takes two parameters:

  • The first parameter, ActivationID, is an identifier for the activatable remote object. When an application registers an activation descriptor with rmid, rmid assigns it an activation ID, which refers to the information associated with the descriptor. This same activation ID (also contained in the remote object's stub) is passed to this constructor when the remote object is activated.
  • The second parameter is a MarshalledObject that contains initialization data pre-registered with rmid. In this example, the marshalled data is the name of a file containing the object's persistent state which is the latest counter value.

The constructor obtains the file name contained in the MarshalledObject which was passed as the second parameter. Next, the constructor calls the local method openFile to open the file and return the current counter value. If the file exists, the openFile method reads the value last saved to the file; otherwise, it creates a new file and initializes the count to zero. The constructor then calls the static method Activatable.exportObject, passing the implementation itself (this), the activation ID, and the port number 0, indicating that the object should be exported on an anonymous TCP port. While this implementation does not use the activation ID passed as a parameter to the constructor, another implementation may wish to save the activation ID for future use, in order to deactivate the object, for example.

Finally, the class implements the remote interface's single method, increment to increment the count, save the count to the file, and return the incremented count. Note that there is a flaw in the implementation of the writeCount method. If the machine crashes between the calls to setLength and writeInt, the value of the counter will be lost. Making this implementation more robust to a crash within that small window is an exercise left to the reader.

Implement the client

The CounterClient program looks up a remote object's stub (one that implements the remote interface Counter) in the registry on the host supplied as the optional first argument, and then invokes the stub's increment method and displays the result. When this client invokes a remote method on the stub acquired from the registry, the remote object will activate if not already active.

The source for the program is as follows:

package examples.activation;

import java.rmi.registry.LocateRegistry;
import java.rmi.registry.Registry;

public class CounterClient {

    public static void main(String args[])  throws Exception {

        String hostname = "localhost";
        if (args.length < 1) {
            System.err.println(
                "usage: java [options] examples.activation.CounterClient [host]");
            System.exit(1);
        } else {
            hostname = args[0];
        }

        if (System.getSecurityManager() == null) {
            System.setSecurityManager(new SecurityManager());
        }

        String name = System.getProperty("examples.activation.name");
        Registry registry = LocateRegistry.getRegistry(hostname);
        Counter stub = (Counter) registry.lookup(name);
        System.err.println("Obtained stub from the registry.");

        System.err.println("Invoking increment method...");
        int count = stub.increment();
        System.err.println("Returned from increment remote call.");
        System.err.println("count = " + count);
    }
}

This program should be run as follows:

java -cp clientDir                               \
     -Djava.security.policy=client.policy        \
     -Dexamples.activation.client.codebase=clientCodebase   \
     -Dexamples.activation.name=name             \
     examples.activation.CounterClient [host]

where:

  • clientDir is the root directory for the client program (its class path),
  • client.policy is the security policy file for this program,
  • clientCodebase is the location (URL) for this program's class (used in granting permissions to this program in the client.policy file)
  • name is the name for the object's stub in the registry
  • host is the server's host

Note: rmid must be running on its default port, and rmiregistry must be running on its default port (both on the remote host) prior to running this program.

The following is an example client.policy file that grants the appropriate permissions for the activation examples:

grant codeBase "${examples.activation.client.codebase}" {

    // permissions to read system properties required by the client
    permission java.util.PropertyPermission "examples.activation.name","read";

    // permission to connect to the registry, activation system, and remote host
    permission java.net.SocketPermission "*:1024-","connect";
};

The codebase to which permissions are granted is a file URL specifying the location of the client's classes. This file URL is the value of the examples.activation.client.codebase system property, defined when the client program is run. The client needs two permissions:

  • java.util.PropertyPermission - to read the system property examples.activation.name that specifies the name for the stub in the registry
  • java.net.SocketPermission - to connect to the registry, activation system, and remote object's host

Compile the source files

The source files for this example can be compiled as follows:

javac -d implDir Counter.java CounterImpl.java
javac -d clientDir Counter.java CounterClient.java

where implDir is the destination directory to put the implementation's class files in, and clientDir is the destination directory to put the client's class files in.

Run the Setup program

Once your implementation phase is complete, you need to register information about the activatable object so a client can use it. The Setup program, described by the tutorial Using Activation: the Setup Program, registers an activation descriptor for an activatable object with rmid, and then binds the remote object's stub in an rmiregistry so that clients can look it up.

To run the Setup program for this example, see the section Start rmid, rmiregistry, and the Setup program in the Setup program tutorial, which describes how to start rmid, rmiregistry, and the Setup program itself.

After you run rmid and rmiregistry as instructed in the Setup tutorial, you will need to run the Setup program to register an activation descriptor for an activatable object that implements the class examples.activation.CounterImpl. The following command line runs the Setup program, supplying an appropriate file URL for each codebase used:

java -cp setupDir:implDir                       \
     -Djava.security.policy=setup.policy                      \
     -Djava.rmi.server.codebase=file:/implDir/                \
     -Dexamples.activation.setup.codebase=file:/setupDir/     \
     -Dexamples.activation.impl.codebase=file:/impDir/        \
     -Dexamples.activation.name=examples.activation.Counter                 \
     -Dexamples.activation.policy=group.policy                \
     -Dexamples.activation.file=file                          \
     examples.activation.Setup examples.activation.CounterImpl

where:

  • setupDir is the root directory for the Setup program's class
  • implDir is the root directory for the implementation's classes
  • setup.policy is the security policy file for the Setup program
  • group.policy is the security policy file for the activation group
  • file is the name of a file containing the object's persistent state which is registered as the data in the object's activation descriptor

Note that each file URL above has the required trailing slash. Examples of group and setup policy files, suitable for this tutorial, are described in the Setup tutorial, and are listed below:

  • setup.policy
  • group.policy

The output from the Setup program should look like this:

Activation group descriptor registered.
Activation descriptor registered.
Stub bound in registry.

Run the client

Once you have successfully registered an activation descriptor for a CounterImpl implementation, you can run the client program, which, during its first execution, will cause the activatable object to activate.

The following command line illustrates how to run the client program, specifying a file URL for the client codebase:

java -cp clientDir                                              \
     -Djava.security.policy=client.policy                       \
     -Dexamples.activation.client.codebase=file:/clientDir/     \
     -Dexamples.activation.name=examples.activation.Counter                   \
     examples.activation.CounterClient [host]

where:

  • clientDir is the root directory for the client program (its class path).
  • client.policy is the security policy file for this program.
  • name is the name for the object's stub in the registry.
  • host is the server's host.

Notes:

  • The client codebase must have a trailing slash.
  • The name must match the name supplied to the Setup program. In this example, we used the name examples.activation.Counter.
  • rmid and rmiregistry must be running on the server's host. If the server's host is not the local host, the host argument must specify the remote host that they are running on.

The output from the client should look like this:

Obtained stub from the registry.
Invoking increment method...
Returned from increment remote call.
count = 1
Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com

Sun
Java Software


the Setup Program

Using Activation: the Setup Program

 Documentation Contents

This tutorial describes how to write a program that registers an activation descriptor for a remote object with the JavaTM Remote Method Invocation (Java RMI) activation system daemon (rmid) and then binds a stub for that remote object in an rmiregistry so that clients can look it up.

This tutorial has the following steps:

  • Implement the Setup program
  • Compile the source file
  • Start rmid, rmiregistry, and the Setup program
The files needed for this tutorial are:
  • Setup.java - main Setup program
  • setup.policy - security policy file for the Setup program
  • rmid.policy - security policy file for rmid
  • group.policy - security policy file for the activation group

Implement the Setup program

The Setup program, implemented by the class examples.activation.Setup, registers an activation descriptor with rmid to enable future activation of the object specified by that activation descriptor. This program does not create an instance of a remote object, but instead registers a remote object's stub with an rmiregistry so that clients can look it up. This Setup program must be run prior to running any of the clients described in the other activation tutorials.

The Setup program uses a number of system properties to customize the information that is registered with rmid and rmiregistry. The program also takes a single command-line argument that specifies the package-qualified name of the implementation class for the activatable remote object being registered. The Setup program is run as follows:

java -cp classpath \
     -Djava.security.policy=setup.policy        \
     -Djava.rmi.server.codebase=codebase         \
     -Dexamples.activation.setup.codebase=setupCodebase  \
     -Dexamples.activation.impl.codebase=implCodebase \
     -Dexamples.activation.name=name             \
     [-Dexamples.activation.file=filename]       \
     [-Dexamples.activation.policy=group.policy] \
     examples.activation.Setup implClass

where:

  • classpath is a class path that includes the Setup program and the implementation classes
  • setup.policy is the security policy file for the Setup program
  • codebase is the location (URL) of the remote interface class(es)
  • setupCodebase is the location (URL) the Setup program class (used in granting permissions to the Setup program in the setup.policy file)
  • implCodebase is the location (URL) of the implementation class(es), used in the activation descriptor and also used in the group policy file as the codebase to grant permissions to
  • name is the name for the object's stub to be bound in the registry
  • file (optional) is the name of a file containing the object's persistent state which is registered as the data in the object's activation descriptor (no default)
  • group.policy (optional) is the security policy file for the activation group (defaults to group.policy), and
  • implClass is the fully-qualified name of the
    • implementation class.

The following is an example policy file for the Setup program:

  grant codeBase "${examples.activation.setup.codebase}" {

    // permissions to read system properties required by setup program
    permission java.util.PropertyPermission "examples.activation.impl.codebase","read";
    permission java.util.PropertyPermission "examples.activation.policy","read";
    permission java.util.PropertyPermission "examples.activation.file","read";
    permission java.util.PropertyPermission "examples.activation.name","read";

    // permission to connect to the activation system and the registry
    permission java.net.SocketPermission "*:1098-1099","connect";
};

The codebase to which permissions are granted is a URL specifying the location of the Setup program's implementation class(es). This URL is the value of the examples.activation.setup.codebase system property, which is defined when the Setup program is run. The Setup program needs the following permissions:

  • java.util.PropertyPermission - to read various system properties required by the Setup program
  • java.net.SocketPermission - to connect to the activation system (port 1098) to register an activation descriptor, and to connect to the registry (port 1099) to bind the activatable object's stub to a name

There are several steps to writing this Setup program:

  • Construct an activation group descriptor
  • Register the group descriptor
  • Construct an activation descriptor
  • Register the activation descriptor, and finally,
  • Bind the remote object's stub in an rmiregistry

The Setup class has a static main method that performs all of the above steps. But before doing so, the main method sets a SecurityManager and obtains the single command line argument that specifies the package-qualified name of the implementation class for the activatable remote object. The rest of the steps are described below. See Setup.java for the full source code.

Construct an activation group descriptor

Before an application registers information about a particular activatable remote object, it first needs to register information about the activation group that the object will be contained in. An activation group is a container virtual machine (VM) for a set of activatable objects. Each activation group manages the execution of one or more activatable objects. An activation group descriptor contains information that the activation system needs to start an activation group's VM. An application can register an activation group descriptor with the activation system rmid to obtain an activation group ID to use for the activatable object, or the application can use an activation group ID obtained from a previous group registration.

The activation group descriptor, an instance of the class java.rmi.activation.ActivationGroupDesc, can be constructed in several ways. This tutorial uses the two parameter constructor ActivationGroupDesc(Properties,CommandEnvironment). The Properties map contains overrides for system properties in the activation group VM. For this tutorial, an activation group VM needs the following system properties defined:

  • java.security.policy - the group's security policy file
  • java.class.path - a dummy class path to prevent an activation group from loading implementation classes from the local class path
  • examples.activation.impl.codebase - the location of the implementation classes, which the group's policy file uses to grant permissions to
  • examples.activation.file - a file containg the object's persistent state

The java.security.policy property is specified by the examples.activation.policy system property, and defaults to the file named group.policy which will, in practice, be in the working directory where rmid is run. The java.class.path property is defined as no_classpath. The examples.activation.impl.codebase and examples.activation.file properties are specified by their current values (respectively), defined when the Setup program runs.

The group descriptor is constructed as follows:

String policy =
    System.getProperty("examples.activation.policy", "group.policy");
String implCodebase =
    System.getProperty("examples.activation.impl.codebase");
String filename =
    System.getProperty("examples.activation.file", "");

Properties props = new Properties();
props.put("java.security.policy", policy);
props.put("java.class.path", "no_classpath");
props.put("examples.activation.impl.codebase", implCodebase);
if (filename != null && !filename.equals("")) {
    props.put("examples.activation.file", filename);
}

ActivationGroupDesc groupDesc = new ActivationGroupDesc(props, null);

The following is an example group.policy file that grants the appropriate permissions for the activation examples:

grant codeBase "${examples.activation.impl.codebase}" {

    // permission to read and write object's file
    permission java.io.FilePermission "${examples.activation.file}","read,write";

    // permission to listen on an anonymous port
    permission java.net.SocketPermission "*:1024-","accept";
};

The codebase to which permissions are granted is a URL specifying the location of the activatable object's implementation classes. This URL is the value of the examples.activation.impl.codebase system property, which will be defined in the activation group's VM. An activatable object in the group needs two permissions:

  • java.io.FilePermission - to read and write the file containing the activatable object's persistent state
  • java.net.SocketPermission - to export the activatable object to accept connections an anonymous port

Register the group descriptor

Next, the Setup program must register the activation group descriptor with the activation system to obtain the group's ID, an instance of the class java.rmi.activation.ActivationGroupID. The class java.rmi.activation.ActivationGroup has a static method getSystem for obtaining the stub for the activation system. The Setup program calls the activation system's remote method registerGroup, passing the group descriptor created above, to register the activation group:
ActivationGroupID groupID =
    ActivationGroup.getSystem().registerGroup(groupDesc);

Construct an activation descriptor

Once the activation group ID is obtained, the Setup program can register the activation descriptor. The activation descriptor has four basic pieces of information:

  • the activation group ID for the group that the object will be contained in
  • the implementation's class name
  • the location (URL) specifying where the implementation's classes can be loaded from
  • a marshalled object containing initialization information for the object

In this example, the activation group ID is the one obtained above; the implementation's class name is the class name, implClass, supplied as the command-line argument to the Setup program; the location (URL) is specified by the system property examples.activation.impl.codebase; and, the initialization data (which is optional) is a filename specified by the system property examples.activation.file.

The activation descriptor is constructed as follows:

MarshalledObject data = null;
if (filename != null && !filename.equals("")) {
    data = new MarshalledObject(filename);
}

ActivationDesc desc =
    new ActivationDesc(groupID, implClass, implCodebase, data);

Register the activation descriptor

Next, the Setup program must register the activation descriptor with the activation system. The class Activatable has a static convenience method, register, that registers an activation descriptor with the activation system and returns a stub for the activatable object specified by the descriptor.

Remote stub = Activatable.register(desc);

Note: The register method attempts to load a stub class for the implementation class in order to create a stub instance. If your activatable object needs to support pre-5.0 clients, you will need use rmic to pregenerate a stub class for the implementation class. If your activatable object does not need to support pre-5.0 clients, then there is no need to pregenerate a stub class for the implementation class. If the register method is unable to load a pregenerated stub class, it will use an instance of a dynamically-generated proxy class that implements all the interfaces of the implementation class. In the latter case the register method needs load the implementation class in order to determine the remote interfaces that the implementation class implements. So, the register method has a slight behavioral difference, depending on whether a pregenerated or dynamically-generated stub class is used.

Bind the remote object's stub in a rmiregistry

Finally, the remote object's stub is bound to a name in the registry running on the default port of 1099. The name is specified by the system property examples.activation.name.

String name = System.getProperty("examples.activation.name");
LocateRegistry.getRegistry().rebind(name, stub);

Compile the source file

The source file for this example can be compiled as follows:

javac -d setupDir Setup.java
where setupDir is the root destination directory to put the class files in.

Start rmid, rmiregistry, and the Setup program

To run this the Setup program, you will need to do the following:

  • Start rmid
  • Start rmiregistry
  • Run the Setup program

Start rmid

To start rmid, run the rmid command on the server's host. This command should produce no output if it is run with a security policy file as specified below. For more information, see the tools documentation for rmid [Solaris, Windows].

For example, in the Solaris Operating System:

rmid -J-Djava.security.policy=rmid.policy \
     -J-Dexamples.activation.policy=group.policy &

Or, on Windows platforms:

start rmid -J-Djava.security.policy=rmid.policy \
           -J-Dexamples.activation.policy=group.policy

where:

  • rmid.policy is the security policy file for rmid
  • group.policy is the group policy file, used in rmid's policy file

The security policy file for rmid grants permissions for rmid to execute specific commands and to use specific command-line options in starting activation group VMs. For example, a user might grant specific permissions to start an activation group VM with one or more system properties or other java command-line options. This example allows rmid to start activation group VMs that define the system properties java.security.policy, java.class.path, examples.activation.impl.codebase, and examples.activation.file. The following example security policy file grants permission to start an activation group VM with these specific properties defined:

grant {
    // allow activation groups to use certain system properties
    permission com.sun.rmi.rmid.ExecOptionPermission "-Djava.security.policy=${examples.activation.policy}";
    permission com.sun.rmi.rmid.ExecOptionPermission "-Djava.class.path=no_classpath";
    permission com.sun.rmi.rmid.ExecOptionPermission "-Dexamples.activation.impl.codebase=*";
    permission com.sun.rmi.rmid.ExecOptionPermission "-Dexamples.activation.file=*";
};

The first ExecOptionPermission permission grant restricts the java.security.policy system property to be the file specified by the system property examples.activation.policy, defined when rmid is run. The next permission grant allows a group to define the system property java.class.path as no_classpath, a dummy class path that prevents the group from having a valid class path. The next permission grant allows the group to define the system property examples.activation.impl.codebase to be any value. The final permission grant allows the examples.activation.file system property to be any value.

Start rmiregistry

To start the registry, run the rmiregistry command on the server's host. This command produces no output (when successful) and is typically run in the background. For more information, see the tools documentation for rmiregistry [Solaris, Windows].

For example, in the Solaris Operating System:

rmiregistry &

Or, on Windows platforms:

start rmiregistry

By default, the registry runs on TCP port 1099. To start a registry on a different port, specify the port number from the command line. For example, to start the registry on port 2001 on a Windows platform:

start rmiregistry 2001

Note: Make sure that rmiregistry does not have any implementation classes in its class path to prevent it from loading any classes from its local class path.

If the registry will be running on a port other than 1099, you'll need to specify the port number in the calls to LocateRegistry.getRegistry in the Setup program, as well as any clients that access this registry. For example, if the registry is running on port 2001 in this example, the call to getRegistry would be:

Registry registry = LocateRegistry.getRegistry(2001);

Also note that if you use a registry port other than 1099, you will also need to modify the Setup and client program's policy files to grant permission to connect to the registry's port.

Run the Setup program

To start the Setup program, run the Setup class using the java command as follows:

java -cp setupDir:implDir \
     -Djava.security.policy=setup.policy        \
     -Djava.rmi.server.codebase=codebase         \
     -Dexamples.activation.setup.codebase=setupCodebase       \
     -Dexamples.activation.impl.codebase=implCodebase \
     -Dexamples.activation.name=name             \
     [-Dexamples.activation.file=file]       \
     [-Dexamples.activation.policy=group.policy] \
     examples.activation.Setup implClass

where:

  • setupDir is the root directory for the Setup program's class
  • implDir is the root directory for the implementation's classes
  • setup.policy is the security policy file for the Setup program
  • codebase is the location (URL) of the remote interface class(es)
  • setupCodebase is the location (URL) the Setup program class (used in granting permissions to the Setup program in the setup.policy file)
  • implCodebase is the location (URL) of the implementation class(es), used in the activation descriptor and also used in the group policy file as the codebase to grant permissions to
  • name is the name for the object's stub to be bound in the registry
  • file (optional) is the name of a file containing the object's persistent state which is registered as the data in the object's activation descriptor (no default)
  • group.policy (optional) is the security policy file for the activation group (defaults to group.policy), and
  • implClass is the fully-qualified name of the implementation class.

Note: If you use file URLs for any of the codebases listed above, make sure that each file URL has a trailing slash, or the codebase will be invalid.

The output from the Setup program should look like this:

Activation group descriptor registered.
Activation descriptor registered.
Stub bound in registry.
Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com

Sun
Java Software


Getting Started Using Java RMI

    Getting Started Using JavaTM RMI

 Documentation Contents

This tutorial shows you the steps to follow to create a distributed version of the classic Hello World program using JavaTM Remote Method Invocation (Java RMI). While you work through this example, you will probably come up with a number of related questions. You are encouraged to look for answers in the Java RMI FAQ and the archives of the RMI-USERS mailing list. If you'd like to subscribe to the RMI-USERS mailing list, click here.

The distributed Hello World example uses a simple client to make a remote method invocation to a server which may be running on a remote host. The client receives the "Hello, world!" message from the server.

This tutorial has the following steps:

  • Define the remote interface
  • Implement the server
  • Implement the client
  • Compile the source files
  • Start the Java RMI registry, server, and client
The files needed for this tutorial are:
  • Hello.java - a remote interface
  • Server.java - a remote object implementation that implements the remote interface
  • Client.java - a simple client that invokes a method of the remote interface
Note: For the remainder of this tutorial, the terms "remote object implementation" and "implementation class" are used interchangeably to refer to the class example.hello.Server, which implements a remote interface.

Define the remote interface

A remote object is an instance of a class that implements a remote interface. A remote interface extends the interface java.rmi.Remote and declares a set of remote methods. Each remote method must declare java.rmi.RemoteException (or a superclass of RemoteException) in its throws clause, in addition to any application-specific exceptions.

Here is the interface definition for the remote interface used in this example, example.hello.Hello. It declares just one method, sayHello, which returns a string to the caller:

package example.hello;

import java.rmi.Remote;
import java.rmi.RemoteException;

public interface Hello extends Remote {
    String sayHello() throws RemoteException;
}
Remote method invocations can fail in many additional ways compared to local method invocations (such as network-related communication problems and server problems), and remote methods will report such failures by throwing a java.rmi.RemoteException. For more information about the issues of failure and recovery in distributed systems, see A Note on Distributed Computing.

Implement the server

A "server" class, in this context, is the class which has a main method that creates an instance of the remote object implementation, exports the remote object, and then binds that instance to a name in a Java RMI registry. The class that contains this main method could be the implementation class itself, or another class entirely.

In this example, the main method for the server is defined in the class Server which also implements the remote interface Hello. The server's main method does the following:

  • Create and export a remote object
  • Register the remote object with a Java RMI registry
Here is the source code for the class Server. Descriptions for writing this server class follow the source code:
package example.hello;

import java.rmi.registry.Registry;
import java.rmi.registry.LocateRegistry;
import java.rmi.RemoteException;
import java.rmi.server.UnicastRemoteObject;

public class Server implements Hello {

    public Server() {}

    public String sayHello() {
    return "Hello, world!";
    }

    public static void main(String args[]) {

    try {
        Server obj = new Server();
        Hello stub = (Hello) UnicastRemoteObject.exportObject(obj, 0);

        // Bind the remote object's stub in the registry
        Registry registry = LocateRegistry.getRegistry();
        registry.bind("Hello", stub);

        System.err.println("Server ready");
    } catch (Exception e) {
        System.err.println("Server exception: " + e.toString());
        e.printStackTrace();
    }
    }
}

The implementation class Server implements the remote interface Hello, providing an implementation for the remote method sayHello. The method sayHello does not need to declare that it throws any exception because the method implementation itself does not throw RemoteException nor does it throw any other checked exceptions.

Note: A class can define methods not specified in the remote interface, but those methods can only be invoked within the virtual machine running the service and cannot be invoked remotely.

Create and export a remote object

The main method of the server needs to create the remote object that provides the service. Additionally, the remote object must be exported to the Java RMI runtime so that it may receive incoming remote calls. This can be done as follows:
Server obj = new Server();
Hello stub = (Hello) UnicastRemoteObject.exportObject(obj, 0);
The static method UnicastRemoteObject.exportObject exports the supplied remote object to receive incoming remote method invocations on an anonymous TCP port and returns the stub for the remote object to pass to clients. As a result of the exportObject call, the runtime may begin to listen on a new server socket or may use a shared server socket to accept incoming remote calls for the remote object. The returned stub implements the same set of remote interfaces as the remote object's class and contains the host name and port over which the remote object can be contacted.

Note: As of the J2SE 5.0 release, stub classes for remote objects no longer need to be pregenerated using the rmic stub compiler, unless the remote object needs to support clients running in pre-5.0 VMs. If your application needs to support such clients, you will need to generate stub classes for the remote objects used in the application and deploy those stub classes for clients to download. For details on how to generate stub classes, see the tools documentation for rmic [Solaris, Windows]. For details on how to deploy your application along with pregenerated stub classes, see the codebase tutorial.

Register the remote object with a Java RMI registry

For a caller (client, peer, or applet) to be able to invoke a method on a remote object, that caller must first obtain a stub for the remote object. For bootstrapping, Java RMI provides a registry API for applications to bind a name to a remote object's stub and for clients to look up remote objects by name in order to obtain their stubs.

A Java RMI registry is a simplified name service that allows clients to get a reference (a stub) to a remote object. In general, a registry is used (if at all) only to locate the first remote object a client needs to use. Then, typically, that first object would in turn provide application-specific support for finding other objects. For example, the reference can be obtained as a parameter to, or a return value from, another remote method call. For a discussion on how this works, please take a look at Applying the Factory Pattern to Java RMI.

Once a remote object is registered on the server, callers can look up the object by name, obtain a remote object reference, and then invoke remote methods on the object.

The following code in the server obtains a stub for a registry on the local host and default registry port and then uses the registry stub to bind the name "Hello" to the remote object's stub in that registry:

Registry registry = LocateRegistry.getRegistry();
registry.bind("Hello", stub);
The static method LocateRegistry.getRegistry that takes no arguments returns a stub that implements the remote interface java.rmi.registry.Registry and sends invocations to the registry on server's local host on the default registry port of 1099. The bind method is then invoked on the registry stub in order to bind the remote object's stub to the name "Hello" in the registry.

Note: The call to LocateRegistry.getRegistry simply returns an appropriate stub for a registry. The call does not check to see if a registry is actually running. If no registry is running on TCP port 1099 of the local host when the bind method is invoked, the server will fail with a RemoteException.

Implement the client

The client program obtains a stub for the registry on the server's host, looks up the remote object's stub by name in the registry, and then invokes the sayHello method on the remote object using the stub.

Here is the source code for the client:

package example.hello;

import java.rmi.registry.LocateRegistry;
import java.rmi.registry.Registry;

public class Client {

    private Client() {}

    public static void main(String[] args) {

    String host = (args.length < 1) ? null : args[0];
    try {
        Registry registry = LocateRegistry.getRegistry(host);
        Hello stub = (Hello) registry.lookup("Hello");
        String response = stub.sayHello();
        System.out.println("response: " + response);
    } catch (Exception e) {
        System.err.println("Client exception: " + e.toString());
        e.printStackTrace();
    }
    }
}

This client first obtains the stub for the registry by invoking the static LocateRegistry.getRegistry method with the hostname specified on the command line. If no hostname is specified, then null is used as the hostname indicating that the local host address should be used.

Next, the client invokes the remote method lookup on the registry stub to obtain the stub for the remote object from the server's registry.

Finally, the client invokes the sayHello method on the remote object's stub, which causes the following actions to happen:

  • The client-side runtime opens a connection to the server using the host and port information in the remote object's stub and then serializes the call data.
  • The server-side runtime accepts the incoming call, dispatches the call to the remote object, and serializes the result (the reply string "Hello, world!") to the client.
  • The client-side runtime receives, deserializes, and returns the result to the caller.

The response message returned from the remote invocation on the remote object is then printed to System.out.

Compile the source files

The source files for this example can be compiled as follows:

javac -d destDir Hello.java Server.java Client.java
where destDir is the destination directory to put the class files in.

Note: If the server needs to support clients running on pre-5.0 VMs, then a stub class for the remote object implementation class needs to be pregenerated using the rmic compiler, and that stub class needs to be made available for clients to download. See the codebase tutorial for more details.

Start the Java RMI registry, server, and client

To run this example, you will need to do the following:

  • Start the Java RMI registry
  • Start the server
  • Run the client

Start the Java RMI registry

To start the registry, run the rmiregistry command on the server's host. This command produces no output (when successful) and is typically run in the background. For more information, see the tools documentation for rmiregistry [Solaris, Windows].

For example, on the Solaris(tm) Operating System:

rmiregistry &

Or, on Windows platforms:

start rmiregistry

By default, the registry runs on TCP port 1099. To start a registry on a different port, specify the port number from the command line. For example, to start the registry on port 2001 on a Windows platform:

start rmiregistry 2001

If the registry will be running on a port other than 1099, you'll need to specify the port number in the calls to LocateRegistry.getRegistry in the Server and Client classes. For example, if the registry is running on port 2001 in this example, the call to getRegistry in the server would be:

Registry registry = LocateRegistry.getRegistry(2001);

Start the server

To start the server, run the Server class using the java command as follows:

On the Solaris Operating System:

java -classpath classDir -Djava.rmi.server.codebase=file:classDir/ example.hello.Server &

On Windows platforms:

start java -classpath classDir -Djava.rmi.server.codebase=file:classDir/ example.hello.Server

where classDir is the root directory of the class file tree (see destDir in the section "Compiling the source files"). Setting the java.rmi.server.codebase system property ensures that the registry can load the remote interface definition (note that the trailing slash is important); for more information about using this property, see the codebase tutorial.

The output from the server should look like this:

Server ready

The server remains running until the process is terminated by the user (typically by killing the process).

Run the client

Once the server is ready, the client can be run as follows:

java  -classpath classDir example.hello.Client

where classDir is the root directory of the class file tree (see destDir in the section "Compiling the source files").

The output from the client is the following message:

response: Hello, world!

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com

Sun
Java Software


    Configuring inetd to Launch rmid

 Documentation Contents

On the Solaris Operating System (Solaris OS), the Internet services daemon inetd provides an alternative to starting up services at system boot time. This daemon, a server process for Internet standard services, can be configured to start services on demand. For details on the Internet services daemon, see the Solaris OS inetd(1M) man page.

As of the J2SE(tm) 5.0 release, inetd can be configured to start the Java RMI activation daemon rmid on demand. In this case, rmid does not need to be started up at boot time or started up manually. Instead, rmid will be started when a client attempts to connect to it, such as in order to activate an object.

Note: If restartable services are registered with rmid, rmid should be started at system boot type (not by inetd) so that the restartable services are always running when the system is up.

To configure inetd to launch rmid, you will need to add an entry to each of two configuration files that inetd uses, /etc/inetd.conf and /etc/services. Editing these files requires root access to the machine that rmid will run on.

After inetd has been reconfigured, you should test your configuration to make sure that it works properly.

This tutorial has the following steps:

  • Configure /etc/inetd.conf
  • Configure /etc/services
  • Force inetd to read its new configuration
  • Test your configuration

Configure /etc/inetd.conf

The /etc/inetd.conf configuration file contains entries for the services to be launched when inetd receives a request over a socket. For details on the format of this configuration file see the Solaris OS inetd.conf(4) man page.

To configure inetd to launch rmid, add the following entry to the /etc/inetd.conf configuration file (requires root access to the machine):

rmid stream tcp wait nobody jreHome/bin/rmid  \
     rmid -log logDir/rmid.log rmidOptions
where jreHome is a path to the installed JRE, logDir is the directory for the log file, and rmidOptions is any other options for rmid (for example, property initializations). When rmid is launched by inetd the -log option must be specified, and the -port option must not be specified, since the port is derived from the /etc/services configuration.

If rmid needs to be run as a user other than nobody, replace nobody above with the user ID under which rmid should run.

Configure /etc/services

Next, rmid needs to be listed as a service in the /etc/services configuration file. For details on the format of this configuration file see the Solaris OS services(4) man page.

To list rmid as a service, add the following entry to the /etc/services configuration file (requires root access to the machine):

rmid        port/tcp
where port is the port number for the ActivationSystem and the Activator remote objects that rmid exports. This port number is typically 1098, but another port number can be used as long as the clients and activatable services define the system property java.rmi.activation.port to that port.

Force inetd to read its new configuration

Now that the configuration has been modified, inetd needs to read the new configuration so that it can listen on the appropriate ports for the services that are configured.

But first, it is important to make sure that rmid is not already running. To do this, run the following command:

% ps -ef | grep rmid
If the above command does not print out the information for a running rmid process, then rmid is not running. If it does, then you will need to shut down rmid first before continuing.

Next, inetd needs to read its new configuration. To force inetd to reread its configuration, the running inetd process must be sent a hangup signal. First, find the process ID for the running inetd process by running the following command:

% ps -ef | grep inetd
which will print out something like this:
root   171     1  0   Sep 30 ?        0:02 /usr/sbin/inetd -s
In this example, the process ID for inetd is 171. Now, the inetd process can be sent a hangup signal by running the following command and supplying the process ID (requires root access):
% kill -HUP 171

Now, inetd is all set to launch rmid when a program attempts to connect to the port configured above.

Test your configuration

To test that inetd is configured properly, you can run a simple program that looks up the ActivationSystem which will, in turn, cause inetd to launch rmid if the configuration is correct.

The following is a simple program to look up the ActivationSystem on a port, supplied as the value of the java.rmi.activation.port system property:

package example.inetd;

import java.rmi.activation.ActivationSystem;
import java.rmi.activation.ActivationGroup;

public class GetActivationSystem {

    public static void main(String[] args) throws Exception {

    ActivationSystem system = ActivationGroup.getSystem();
    System.err.println("ActivationSystem = " + system);
    }
}

Compile and run this program as follows:

% javac -d classDir GetActivationSystem.java
% java -classpath classDir -Djava.rmi.activation.port=port
example.inetd.GetActivationSystem
where classDir is the class path for this example class, and port is the port for the ActivationSystem configured for rmid in the /etc/services file.

If the program prints out the ActivationSystem successfully then rmid was launched by inetd.

If the program either hangs or prints an exception trace, check the output file produced by rmid. When rmid is launched by inetd, any output written to System.err is written to a file located in the directory specified by the property java.io.tmpdir, typically /var/tmp on the Solaris OS. The output file is prefixed with "rmid-err" and has the suffix of ".tmp". The file name also contains other characters (typically numbers) in between to keep the file name unique.

If rmid starts up successfully from inetd, the output file should contain text similar to the following (with no warning or error messages):

Tue Sep 30 13:07:38 EDT 2003
rmid startup with inherited channel: sun.nio.ch.ServerSocketChannelImpl[/129.148.70.120:1098]
If the file does not exist, the above text is not in the file, or additional error output is in the file, then recheck the configuration. Upon changing the inetd configuration, remember to send inetd a hangup signal so that it rereads its altered configuration, and remember to terminate any rmid process started from the previous attempt before continuing.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com

Sun
Java Software


    Designing Services to be Launched from inetd

 Documentation Contents

On the Solaris Operating System (Solaris OS), the Internet services daemon inetd provides an alternative to starting up services at system boot time. This daemon, a server process for Internet standard services, can be configured to start services on demand. For details on the Internet services daemon, see the Solaris OS inetd(1M) man page.

Now, inetd can be configured to start JavaTM Remote Method Invocation (Java RMI) services on demand. An application, however, must use a specific technique to enable that application and its constituent services to be started from inetd. First, the service program should create a local registry, exported to use the I/O socket inherited from inetd. The service program should then bind the service's proxy in this specially exported registry so that clients can look up the service. Once the service program is complete, inetd can be configured to start this program when a client attempts to connect to the service's local registry in order to look up the service by name.

This tutorial first describes how to structure a service program (employing a specially exported local registry) so that the service can be started from inetd when clients connect to the service's local registry.

Next, the tutorial describes how to configure inetd to launch the service program. You will need to add an entry to each of two configuration files that inetd uses, /etc/inetd.conf and /etc/services. Editing these files requires root access to the machine that the service will run on.

After inetd has been reconfigured, you should test your configuration to make sure that it works properly.

This tutorial has the following steps:

  • Implement the service program
  • Configure /etc/inetd.conf
  • Configure /etc/services
  • Force inetd to read its new configuration
  • Test your configuration using a simple client

Implement the service program

The server-side implementation uses the following source files:

  • ServiceInterface.java: remote interface for the service
  • InitializeRegistry.java: utility to create/export a registry using an inherited channel
  • Server.java: service program
The interface ServiceInterface defines a remote interface with a single method sendMessage specified to take a single argument, message, and return an acknowledgment that the message was received.

The class InitializeRegistry defines a static utility method initializeWithInheritedChannel that creates and exports a registry (using an inherited channel, if any), and binds a remote service's proxy in that registry for clients to look up.

The service program Server implements the interface ServiceInterface and defines a static main method for running the service. The static main method does the following:

  • Redirects System.err output to a file, in order to prevent the error output from being lost in the case that the service program is started from inetd.
  • Parses the optional argument, which is the port number for the local registry.
  • Creates and exports the server on an anonymous port.
  • Invokes the InitializeRegistry.initializeWithInheritedChannel utility method with the service's proxy, the name for the service in the registry, and an optional port number to use if the program is run from the command line instead of being started from inetd.
  • Prints out the message ready.
  • Waits forever.

The most interesting part of the implementation is in the initializeWithInheritedChannel utility method. This method uses the System.inheritedChannel method which allows an application to obtain a channel (java.nio.channels.SocketChannel or java.nio.channels.ServerSocketChannel, for example) inherited from a process that launched the virtual machine. Such an inherited channel can be used to either service a single incoming connection (in the case of a SocketChannel), or accept multiple incoming connections (in the case of ServerSocketChannel). In this way, applications launched by inetd can obtain the SocketChannel or ServerSocketChannel inherited from inetd.

The initializeWithInheritedChannel utility method first invokes the System.inheritedChannel method to obtain the inherited channel. The inherited channel must either be null or a ServerSocketChannel or the method will throw an IOException.

If the inherited channel is null, there is no inherited channel; that is, the program was run from the command line. In this case, the initializeWithInheritedChannel method simply exports a registry on the specified port (which must be nonzero) and binds the specified service proxy in that registry.

If the inherited channel is a ServerSocketChannel instance, then the program was started from inetd. In this case, the initializeWithInheritedChannel method exports a registry with an RMIServerSocketFactory whose createServerSocket method returns a ServerSocket that delays accepting requests from the inherited ServerSocketChannel until the specified proxy is bound in the registry.

In the case that the program is started from inetd, it is important that the registry not accept any incoming connections on the inherited ServerSocket until the service's proxy is bound in the local registry. If a connection is accepted before the service is bound in the registry, a client might receive a java.rmi.NotBoundException from attempting to look up the service proxy.

For details on how to implement a ServerSocket that delays accepting requests until a service is bound in the registry, see the private nested class DelayedAcceptServerSocket defined in the InitializeRegistry class.

Compile the service program as follows:

% javac -d classDir ServiceInterface.java InitializeRegistry.java Server.java
where classDir is the class path for this example.

Note that if the service needs to be accessible to clients running on releases earlier than J2SE 5.0, you will need to use rmic to generate a stub for the remote service.

The next three sections describe how to set up inetd to start the service program.

Configure /etc/inetd.conf

The /etc/inetd.conf configuration file contains entries for the services to be launched when inetd receives a request over a socket. For details on the format of this configuration file see the Solaris OS inetd.conf(4) man page.

To configure inetd to launch the service program, add the following entry to the /etc/inetd.conf configuration file (requires root access to the machine):

example-server stream tcp wait nobody jreHome/bin/java  \
     java -classpath classpath example.inetd.Server
where jreHome is a path to the installed JRE, and classpath is the class path for the example.

If the program needs to be run as a user other than nobody, replace nobody above with the user ID under which the program should run.

Configure /etc/services

Next, the name chosen to refer to the service, example-server, needs to be listed as a service in the /etc/services configuration file. For details on the format of this configuration file see the Solaris OS services(4) man page.

To list example-server as a service, add the following entry to the /etc/services configuration file (requires root access to the machine):

example-server        port/tcp
where port is the port number for the service's local registry.

Force inetd to read its new configuration

Now that the configuration has been modified, inetd needs to read the new configuration so that it can listen on the appropriate ports for the services that are configured.

But first, it is important to make sure that the service program is not already running. To do this, run the following command:

% ps -ef | grep example.inetd.Server
If the above command does not print out the information for a running java process for the service program, then the program is not running. If it does, then you will need to terminate the program first before continuing.

Next, inetd needs to read its new configuration. To force inetd to reread its configuration, the running inetd process must be sent a hangup signal. First, find the process ID for the running inetd process by running the following command:

% ps -ef | grep inetd
which will print out something like this:
root   171     1  0   Sep 30 ?        0:02 /usr/sbin/inetd -s
In this example, the process ID for inetd is 171. Now, the inetd process can be sent a hangup signal by running the following command and supplying the process ID (requires root access):
% kill -HUP 171

Now, inetd is all set to launch the service program when a client attempts to connect to the port configured above.

Test your configuration using a simple client

To test that inetd is configured properly, you can run a simple client program that looks up the service in the registry on the port configured above, and then invokes a method on the service. Attempting to connect to the service's local registry will, in turn, cause inetd to launch the service program if the configuration is correct.

The following is a simple program to look up the service and invoke a method on the service to send it a message. The program takes three command-line arguments, the host and port of the service's local registry, and the message to send to the service:

package example.inetd;

import java.rmi.registry.LocateRegistry;
import java.rmi.registry.Registry;

public class Client {

    public static void main(String[] args) throws Exception {

    int port = 0;
    String host = "";
    String message = "";

    if (args.length > 2) {
        host = args[0];
        try {
        port = Integer.parseInt(args[1]);
        if (port == 0) {
            goodbye("nonzero port argument required", null);
        }
        } catch (NumberFormatException e) {
        goodbye("malformed port argument", e);
        }
        message = args[2];
    } else {
        usage();
    }

    Registry registry = LocateRegistry.getRegistry(host, port);
    ServiceInterface proxy =
        (ServiceInterface) registry.lookup("ServiceInterface");
    System.out.println("sending message: " + message);
    System.out.println("received message from proxy: " +
               proxy.sendMessage(message));

    System.out.println("done.");
    }

    private static void goodbye(String message, Exception e) {
    System.err.println("Client: " + message + (e != null ? ": " : ""));
    if (e != null) {
        e.printStackTrace();
    }
    System.exit(1);
    }

    private static void usage() {
    System.err.println("Client <host> <port> <message>");
    System.exit(1);
    }
}

The full source (including comments) for the client is:

  • ServiceInterface.java: remote interface for the service
  • Client.java: client program

Compile and run this program as follows:

% javac -d classDir ServiceInterface.java Client.java
% java -classpath classDir example.inetd.Client host port "message"
where classDir is the class path for this example, host is the host that the service is configured to run on, port is the port configured for the service in the /etc/services file, and message is a string to send to the service.

If the client program prints out that it sent a message to and received a message from the service, then the service program was successfully launched by inetd.

If the client program either hangs or prints an exception trace, check the output produced by the service program. The service program redirects any output written to System.err to a file located in the directory specified by the property java.io.tmpdir, typically /var/tmp on the Solaris OS. The output file is prefixed with "example-server-err" and has the suffix of ".tmp". The file name also contains other characters (typically numbers) in between to keep the file name unique.

If the service program starts up successfully from inetd, the output file should contain the text "ready" with no warning or error messages.

If the file does not exist, the "ready" message is not in the file, or additional error output is in the file, then recheck the configuration. Upon changing the inetd configuration, remember to send inetd a hangup signal so that it rereads its altered configuration, and remember to terminate any process started from the previous attempt before continuing.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com

Sun
Java Software


Using Custom Socket Factories with Java RMI

    Using Custom Socket Factories with JavaTM RMI

Documentation Contents

This tutorial shows you steps to follow to implement and use custom socket factories with JavaTM Remote Method Invocation (Java RMI). Custom socket factories can be uesd to control how remote method invocations are communicated at the network level. For example, they can be used to set socket options, control address binding, control connection establishment (such as to require authentication), and to control data encoding (such as to add encryption or compression).

When a remote object is exported, such as with the constructors or exportObject methods of java.rmi.server.UnicastRemoteObject or java.rmi.activation.Activatable, then it is possible to specify a custom client socket factory (a java.rmi.server.RMIClientSocketFactory instance) and a custom server socket factory (a java.rmi.server.RMIServerSocketFactory instance) to be be used when communicating remote invocations for that remote object.

A client socket factory controls the creation of sockets used to initiate remote invocations and thus can be used to control how connections are established and the type of socket to use. A server socket factory controls the creation of server sockets used to receive remote invocations and thus can be used to control how incoming connections are listened for and accepted as well as the type of sockets to use for incoming connections.

The remote stub for a remote object contains the client socket factory, if any, that the remote object was exported with, and thus a client socket factory must be serializable, and its code may be downloaded by clients just like the code for stub classes or any other serializable object passed over a remote invocation.

There is also a LocateRegistry.createRegistry method for exporting a registry with custom socket factories and a LocateRegistry.getRegistry method for obtaining the stub for a registry with a custom client socket factory.

(Note that there is also a global socket factory for Java RMI, which can be set with the setSocketFactory method of java.rmi.server.RMISocketFactory. This global socket factory is used for creating sockets when a remote stub does not contain a custom client socket factory and for creating server sockets when a remote object was not exported with a custom server socket factory.)

This tutorial has three parts:

  • Implementing a Custom Socket Factory.
  • Using a Custom Socket Factory in an Application.
  • Compiling and Running the Application.

The source code for this tutorial is available in the following formats:

  • sockets.zip
  • sockets.tar
  • sockets.tar.Z
Many users are interested in secure communication between Java RMI clients and servers, such as with mutual authentication and encryption. Custom socket factories provide a hook for doing this. For more information, see Using Java RMI with SSL.

Implementing a Custom Socket Factory

Below are three steps for implementing a pair of custom socket factory classes:
  1. Implement a custom ServerSocket and Socket.
  2. Implement a custom RMIClientSocketFactory.
  3. Implement a custom RMIServerSocketFactory.

Step 1:
Implement a custom ServerSocket and Socket

The type of socket to use is an application-specific decision. If your server sends or receives sensitive data, you might want a socket that encrypts the data.

In this example, the custom socket factory creates sockets that perform simple XOR encryption and decryption. Note that this kind of encryption is easily decrypted by a knowledgeable cryptanalyst and is only used here to keep the example simple.

The custom XOR socket implementation includes the following sources. XOR sockets use special input and output stream implementations to handle XOR-ing the data written to or read from the socket.

  • XorInputStream.java
  • XorOutputStream.java
  • XorServerSocket.java
  • XorSocket.java

Step 2:
Implement a custom RMIClientSocketFactory

The client-side socket factory, XorClientSocketFactory, implements the java.rmi.server.RMIClientSocketFactory interface. The client socket factory needs to implement the createSocket method to return the approriate client socket instance, an XorSocket.

The client socket factory must implement the java.io.Serializable interface so that instances can be serialized to clients as part of remote stubs. It is also essential to implement the equals and hashCode methods so that the Java RMI implementation will correctly share resources among remote stub instances with equivalent client socket factories.

package examples.rmisocfac;

import java.io.*;
import java.net.*;
import java.rmi.server.*;

public class XorClientSocketFactory
    implements RMIClientSocketFactory, Serializable {

    private byte pattern;

    public XorClientSocketFactory(byte pattern) {
    this.pattern = pattern;
    }

    public Socket createSocket(String host, int port)
    throws IOException
    {
    return new XorSocket(host, port, pattern);
    }

    public int hashCode() {
    return (int) pattern;
    }

    public boolean equals(Object obj) {
    return (getClass() == obj.getClass() &&
        pattern == ((XorClientSocketFactory) obj).pattern);
    }
}

Step 3:
Implement a custom RMIServerSocketFactory

The server-side socket factory, XorServerSocketFactory, implements the java.rmi.server.RMIServerSocketFactory interface. The server socket factory needs to implement the createServerSocket method to return the appropriate server socket instance, an XorServerSocket.

The server socket factory does not need to implement the Serializable interface because server socket factory instances are not contained in remote stubs. It is still essential for the server socket factory to implement the equals and hashcode methods so that the Java RMI implementation will correctly share resources among remote objects exported with equivalent socket factories.

package examples.rmisocfac;

import java.io.*;
import java.net.*;
import java.rmi.server.*;

public class XorServerSocketFactory
    implements RMIServerSocketFactory {

    private byte pattern;

    public XorServerSocketFactory(byte pattern) {
    this.pattern = pattern;
    }

    public ServerSocket createServerSocket(int port)
    throws IOException
    {
    return new XorServerSocket(port, pattern);
    }

    public int hashCode() {
    return (int) pattern;
    }

    public boolean equals(Object obj) {
    return (getClass() == obj.getClass() &&
        pattern == ((XorServerSocketFactory) obj).pattern);
    }

}

Using a Custom Socket Factory in an Application

There are only two more steps to complete when using a custom socket factory for a remote object:
  1. Write a server application that creates a remote object and exports it to use your custom RMIClientSocketFactory and RMIServerSocketFactory implementations. Store a reference to the remote object's stub in a Java RMI registry so that clients can look it up.

  2. Write a client application that looks up the stub for the remote object and invokes a remote method. The custom socket factories do not need to be referenced in the client application. The client-side socket factory will be downloaded to the client when the client looks up the stub for the remote object.

Step 1:
Write a server application

If communication with a remote object requires the use of custom sockets, you need to specify which custom socket factories to use when you export the remote object. When your application exports the remote object specifying custom socket factories, the Java RMI runtime will use the corresponding custom RMIServerSocketFactory to create a server socket to accept incoming calls to the remote object, and it will create a stub that contains the corresponding custom RMIClientSocketFactory. That client socket factory will be used to create connections when remote invocations are made to the remote object using the stub.

This example is similar to the example in the tutorial Getting Started Using Java RMI, but it uses custom socket factories instead of the default sockets used by the Java RMI implementation.

The application uses the following Hello remote interface:

package examples.rmisocfac;

public interface Hello extends java.rmi.Remote {
    String sayHello() throws java.rmi.RemoteException;
}
The server application creates a remote object implementing the Hello remote interface and exports the object to use custom socket factories using the java.rmi.server.UnicastRemoteObject.exportObject method that takes the custom socket factories as arguments. Next, it creates a local registry and, in that registry, it binds a reference to the remote object's stub with the name "Hello".
package examples.rmisocfac;

import java.io.*;
import java.rmi.*;
import java.rmi.server.*;
import java.rmi.registry.*;

public class HelloImpl implements Hello {

    public HelloImpl() {}

    public String sayHello() {
        return  "Hello World!";
    }

    public static void main(String args[]) {

    if (System.getSecurityManager() == null) {
        System.setSecurityManager(new SecurityManager());
    }

        byte pattern = (byte) 0xAC;
    try {
        /*
         * Create remote object and export it to use
         * custom socket factories.
         */
        HelloImpl obj = new HelloImpl();
        RMIClientSocketFactory csf = new XorClientSocketFactory(pattern);
        RMIServerSocketFactory ssf = new XorServerSocketFactory(pattern);
        Hello stub =
        (Hello) UnicastRemoteObject.exportObject(obj, 0, csf, ssf);

        /*
         * Create a registry and bind stub in registry.
         *
        LocateRegistry.createRegistry(2002);
        Registry registry = LocateRegistry.getRegistry(2002);
        registry.rebind("Hello", stub);
        System.out.println("HelloImpl bound in registry");

    } catch (Exception e) {
        System.out.println("HelloImpl exception: " + e.getMessage());
        e.printStackTrace();
    }
    }
}

Step 2:
Write a client application

The client application obtains a reference to the registry used by the server application. It then looks up the remote object's stub and invokes its remote method sayHello:

package examples.rmisocfac;

import java.rmi.*;
import java.rmi.registry.*;

public class HelloClient {

    public static void main(String args[]) {

    if (System.getSecurityManager() == null) {
        System.setSecurityManager(new SecurityManager());
    }

        try {
        Registry registry = LocateRegistry.getRegistry(2002);
            Hello obj = (Hello) registry.lookup("Hello");
            String message = obj.sayHello();
            System.out.println(message);

        } catch (Exception e) {
        System.out.println("HelloClient exception: " +
                               e.getMessage());
            e.printStackTrace();
        }
    }

}

Compiling and Running the Application

There are four steps to compile and run the application:

  1. Compile the remote interface, client, and server classes
  2. Run rmic on the implementation class (optional)
  3. Start the server
  4. Run the client

Step 1:
Compile the remote interface, client, and server classes

javac -d . XorInputStream.java
javac -d . XorOutputStream.java
javac -d . XorSocket.java
javac -d . XorServerSocket.java
javac -d . XorServerSocketFactory.java
javac -d . XorClientSocketFactory.java
javac -d . Hello.java
javac -d . HelloClient.java
javac -d . HelloImpl.java

Step 2:
Run rmic on the implementation class (optional)

Note: Running rmic to pregenerate a stub class for a remote object's class is only required if the remote object needs to support pre-5.0 clients. As of the 5.0 release, if a pregenerated stub class for a remote object's class cannot be loaded when the remote object is exported, the remote object's stub class is generated dynamically.

rmic -d . examples.rmisocfac.HelloImpl

Step 3:
Start the server

java -Djava.security.policy=policy examples.rmisocfac.HelloImpl

The server output should look like this:

      HelloImpl bound in registry

Step 4:
Run the client

In another window start the client application making sure that the application classes are in the class path:

java -Djava.security.policy=policy examples.rmisocfac.HelloClient

The client output should look like this:

      Hello World!

Note: Both the server and client applications use a security policy file that grants permissions only to files in the local class path (the current directory). The server application needs permission to accept connections, and both the server and client applications need permission to make connections. The permission java.net.SocketPermission is granted to the specified codebase URL, a "file:" URL relative to the current directory. This permission grants the ability to both accept connections from and make connections to any host on unprivileged ports (that is ports >= 1024).

grant codeBase "file:." {

    permission java.net.SocketPermission "*:1024-", "connect,accept";
};

Note that if you want to customize the communication to the registry as well, such as to secure registry communication, then that can be done by passing the appropriate custom socket factories to the LocateRegistry.createRegistry and LocateRegistry.getRegstry invocations.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com

Sun
Java Software


Using Java RMI with SSL

Using JavaTM RMI with SSL

Many have asked how a JavaTM Remote Method Invocation (Java RMI) application can make remote invocations over secure SSL connections. Below are some questions and answers about using Java RMI with SSL.

Q1: Is it possible to use Java RMI with SSL?

A1: Yes, it is possible, with the use of custom socket factories. An application can export a remote object to use custom socket factories that create sockets of a desired type (for example, SSL sockets). Using this technique, an application can use SSL socket communication instead of the default socket communication. For further details on using custom socket factories, see the tutorial: Using Custom Socket Factories with Java RMI.

Q2: Where can I find a pure Java programming language implementation of SSL?

A2: The JDK includes the Java Secure Socket Extension (JSSE) API which provides an implementation of SSL sockets. See the JSSE Reference Guide for more detailed information on the features and benefits of JSSE.

Q3: Where can I find an example using Java RMI with SSL?

A3: There is an example bundled with the JSSE code examples that illustrates how to use SSL-based connections for calls to a remote object. This is achieved by exporting a remote object to use custom socket factories that create SSL sockets. Beginning with J2SE 5.0, the JDK provides some standard SSL-based custom socket factory classes; see the javax.rmi.ssl package for more details.

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: rmi-comments@java.sun.com

Sun
Java Software


A Developer Guide

Enterprise JavaBeansTM Components and CORBA Clients: A Developer Guide

This paper discusses how to enable a client written in any language supported by CORBA to access Enterprise JavaBeansTM components ("EJBTM components"). This paper is directed at programmers with advanced knowledge of both the JavaTM 2 Platform, Enterprise Edition ("J2EETM") and CORBA (Common Object Request Broker Architecture).

J2EE technology simplifies enterprise applications by basing them on standardized, modular and re-usable components based on the Enterprise JavaBeansTM (EJBTM) architecture, providing a complete set of services to those components, and handling many details of application behavior automatically. By automating many of the time-consuming and difficult tasks of application development, J2EE technology allows enterprise developers to focus on adding value, that is, enhancing business logic, rather than building infrastructure.

The EJBTM server-side component model simplifies development of middleware components that are transactional, scalable, and portable. Enterprise JavaBeans servers reduce the complexity of developing middleware by providing automatic support for middleware services such as transactions, security, database connectivity, and more.

CORBA is an Object Management Group (OMG) standard that is an open, vendor-independent architecture and infrastructure that computer applications use to work together over networks. Using the standard Internet Inter-ORB Protocol (IIOP), a CORBA-based program from any vendor, on almost any computer, operating system, programming language, and network, can interoperate with a CORBA-based program from the same or another vendor, on almost any other computer, operating system, programming language, and network. To learn more about CORBA, visit http://www.omg.org/gettingstarted/gettingstartedindex.htm.

CORBA technology complements the Java platform by providing a distributed objects framework, services to support that framework, and interoperability with other languages. CORBA technology is an integral part of the Java 2 platform, being used in Enterprise JavaBeans components, Java Remote Method Invocation APIs running over Internet Inter-ORB Protocol ("Java RMI-IIOP"), and Java IDL APIs ("Java IDL").

OMG Interface Definition Language (IDL) is used to describe the interfaces being implemented by the remote objects. IDL is used to define the name of the interface and the names of each of the attributes and methods. Once you create the IDL file, you can use an IDL compiler to generate the client stub and the server skeleton in any language for which the OMG has defined a specification for such language mapping. To learn more about OMG IDL, visit http://www.omg.org/gettingstarted/omg_idl.htm.

Java IDL makes it possible for distributed Java applications to transparently invoke operations on remote network services using the industry standard OMG IDL and IIOP defined by the Object Management Group (http://www.omg.org). Java RMI over IIOP APIs enable the programming of CORBA servers and applications via the javax.rmi API.

Developers who program EJB components follow the Java RMI programming model for their distributed object model, where the required transport common across all application servers is Java RMI-IIOP. In heterogeneous server environments, the standard mapping of the EJB architecture to CORBA enables the following interoperability:

  • A client using an ORB from one vendor can access enterprise beans residing on a server enabled with Enterprise JavaBeans technology ("EJB server") provided by another vendor.
  • Enterprise beans in one EJB server can access enterprise beans in another EJB server.
  • A CORBA client written in a language other than the Java programming language can access any EJB component as long as there is a mapping from OMG IDL to that programming language.

The rest of this document provides an example of a CORBA client application accessing an enterprise bean object. In this document, a CORBA client means a client application written in any language supported by CORBA, including the Java programming language, C++, C, Smalltalk, COBOL, Ada, Lisp, or Python. While the Java code in this example is specific to enterprise beans, the process for developing a CORBA client that accesses a server created using the Java RMI-IIOP APIs is the same.

Links to similar example applications from other vendors who implement J2EE technology can be found in Links to similar examples.

Developing a CORBA Client that Accesses an Enterprise JavaBean Component

This is an example of how to develop a CORBA client application that accesses an EJB component. In this example, the client is written in the C++ programming language, but the client could be written in any language supported by CORBA.

The general process for developing a CORBA client so that it can access an enterprise bean is demonstrated in the following sections:

  1. Write the Enterprise JavaBean component
  2. Generate the CORBA IDL
  3. Create a CORBA client
  4. Deploy the Enterprise JavaBean component
  5. Run the client executable

This document also includes:

  • Creating a Java RMI-IIOP client application
  • Where to go from here
  • Tips for complex interfaces
  • Links to similar examples

In order to make the example simple, we have taken a few shortcuts. For information on building more advanced solutions, see Tips for complex interfaces.

    Part I: Write the Enterprise JavaBean component

    The following examples show the code for an enterprise bean that will accept simple String log messages sent to the application server from Java RMI-IIOP and CORBA clients. The enterprise bean prints them on the server along with the current server time.

  1. Create the files Logger.java , LoggerHome.java , LoggerEJB.java , and LogMessage.java in the /Java/src/ejbinterop directory.
    2.

    Logger.java

    The file Logger.java is the enterprise bean's remote interface, and as such, it extends EJBObject . A remote interface provides the remote client view of an EJB object and defines the business methods callable by a remote client.

//Code Example 1: Logger.java
package ejbinterop;

import javax.ejb.EJBObject;
import java.rmi.RemoteException;

/**
 * Accepts simple String log messages and prints
 * them on the server.
 */
public interface Logger extends EJBObject
{
    /**
     * Logs the given message on the server with
     * the current server time.
     */
    void logString(String message) throws RemoteException;
}

    LoggerHome.java

    The file LoggerHome.java extends EJBHome . The EJBHome interface must be extended by all EJB component's remote home interfaces. A home interface defines the methods that allow a remote client to create, find, and remove EJB objects, as well as home business methods that are not specific to an EJB instance.

//Code Example 2: LoggerHome.java
package ejbinterop;

import java.rmi.RemoteException;
import javax.ejb.EJBHome;
import javax.ejb.CreateException;

public interface LoggerHome extends EJBHome
{
    Logger create() throws RemoteException, CreateException;
}

    LoggerEJB.java

    The file LoggerEJB.java contains the code for a session bean. A session bean is an enterprise bean that is created by a client and that usually exists only for the duration of a single client-server session. A session bean performs operations such as calculations or accessing a database for the client. In this example, the enterprise bean accepts simple String log messages from the client and prints them on the server.

//LoggerEJB.java
package ejbinterop;

import javax.ejb.*;
import java.util.*;
import java.rmi.*;
import java.io.*;

/**
 * Accepts simple String log messages and prints
 * them on the server.
 */
public class LoggerEJB implements SessionBean {

    public LoggerEJB() {}
    public void ejbCreate() {}
    public void ejbRemove() {}
    public void ejbActivate() {}
    public void ejbPassivate() {}
    public void setSessionContext(SessionContext sc) {}

    /**
     * Logs the given message on the server with
     * the current server time.
     */
    public void logString(String message) {
        LogMessage msg = new LogMessage(message);

        System.out.println(msg);
    }
}

    LogMessage.java

    The file LogMessage.java takes the current date and time, creates a formatted String showing the message, and prints the message to the server.

    //LogMessage.java
package ejbinterop;

import java.io.Serializable;
import java.util.Date;
import java.text.*;

/**
 * Simple message class that handles pretty
 * printing of log messages.
 */
public class LogMessage implements Serializable
{
    private String message;
    private long datetime;

    /**
     * Constructor taking the message. This will
     * take the current date and time.
     */
    public LogMessage(String msg) {
        message = msg;
        datetime = (new Date()).getTime();
    }

    /**
     * Creates a formatted String showing the message.
     */
    public String toString() {
        StringBuffer sbuf = new StringBuffer();
        DateFormat dformat
            = DateFormat.getDateTimeInstance(DateFormat.MEDIUM,
    DateFormat.LONG);
        FieldPosition fpos = new
            FieldPosition(DateFormat.DATE_FIELD);
        dformat.format(new Date(datetime), sbuf, fpos);
        sbuf.append(": ");
        sbuf.append(message);
        return sbuf.toString();
    }
}

  2. Compile the files written in this section, for example,

    javac -classpath $J2EE_HOME/lib/j2ee.jar:.. *.java

    These commands create class files for all of the .java files in the current directory. This command and others in this paper assume that the J2EE_HOME environment variable has been set correctly. Using $J2EE_HOME is a convention of the Unix® operating environment. Substitute %J2EE_HOME% when working in the Microsoft Windows operating environment.

    Part II: Generate the CORBA IDL

    This sections discusses generating the Interface Definition Language (IDL) files from the Java class files generated in the previous section. In this example, we will use the rmic compiler to map the Java code to IDL. IDL provides a purely declarative, programming language-independent way of specifying an object's API.

  3. Run the rmic compiler against the Java class files generated in the previous step as follows:
    rmic -idl -noValueMethods -classpath
  $J2EE_HOME/lib/j2ee.jar:<path_to_ejbinterop_dir>
  -d <path_to_where_idl_files_should_be_generated>
  ejbinterop.Logger ejbinterop.LoggerHome

    In the preceding example, we are including the JAR file containing definitions for the javax.ejb package as well as the directory to our ejbinterop files. If you're using the JavaTM 2 Platform, Enterprise Edition (J2EETM), version 1.3 Reference Implementation (RI), the JAR files are located in $J2EE_HOME/lib/j2ee.jar .

    In the command line for rmic above, we recommend a shortcut -- using the noValueMethods option. This option tells rmic to skip any methods with parameter or return types that would be mapped to CORBA value types. The advantage is that it will prevent us from generating a lot of unnecessary IDL that we might have to implement in the C++ client. The disadvantage is that we can only use primitive data types, arrays, and Strings as parameters or return values, and not our own Java class types. Read more about this in Tips for complex interfaces

    Running the rmic compiler on the Java class files generates the following files to the directory indicated with the -d option in the rmic statement above:

    • java/lang/Ex.idl
    • java/lang/Exception.idl
    • java/lang/Object.idl
    • java/lang/Throwable.idl
    • java/lang/ThrowableEx.idl
    • javax/ejb/CreateEx.idl
    • javax/ejb/CreateException.idl
    • javax/ejb/EJBHome.idl
    • javax/ejb/EJBMetaData.idl
    • javax/ejb/EJBObject.idl
    • javax/ejb/Handle.idl
    • javax/ejb/HomeHandle.idl
    • javax/ejb/RemoveEx.idl
    • javax/ejb/RemoveException.idl
    • ejbinterop/Logger.idl
    • ejbinterop/LoggerHome.idl

    NOTE: A number of these generated files contain API that can only be used within a Java programming environment. For example, the EJBMetaData implementation is currently specific to each application server, and thus it will be difficult to develop equivalents that will continue to work over time on platforms other than the Java platform. One option is to remove these from the IDL, but if you do, you'll have to remove them from the IDL every time you change the Java interface and regenerate the IDL files from the rmic compiler.

    NOTE: Since CORBA exceptions don't support inheritance, the Java language to IDL mapping creates an Ex class that contains a CORBA value type representing the actual Java exception. In this basic example, we're not going to worry much about exception support. More information about exceptions can be found at http://java.sun.com/javase/6/docs/technotes/guides/idl/jidlExceptions.html.

  4. Compile the IDL files with your C++ vendor's "IDL to C++" compiler to generate the C++ code corresponding to the IDL. The steps for this procedure vary by vendor, so consult your product documentation for the specific steps for your vendor.

    Part III: Create a CORBA client

    The client application can be written in any language supported by CORBA. The following example provides the code for a simple C++ client that, given an Object Request Broker (ORB) and a corbaname URL for a LoggerHome object, logs a simple String message on the server. You'll have to adjust the include statements and modify the code for registering the value factories based on your C++ ORB vendor's libraries. This example was written for ORBacus for C++ 4.0.5 and some of the C++ code in this example is specific to that product.

    A corbaname URL is a human-readable URL format that enables you to access CORBA objects. It is used to resolve a stringified name from a specific naming context. This is part of the CORBA Interoperable Naming Service (INS). INS is an extension to CORBA Object Services (COS) Naming Service, which was delivered in previous releases of the J2EE platform. To read more about INS, visit http://java.sun.com/javase/6/docs/technotes/guides/idl/jidlNaming.html#INS.

    In this example, the client code does the following:

    • Creates an Object Request Broker (ORB). The ORB connects objects requesting services to the objects providing them.

    • Registers value factories.

    • Looks up the LoggerHome object in the naming context pointed to by the corbaname URL.

    • Performs a safe downcast from the object returned to a LoggerHome object.

    • Creates a LoggerEJB object reference.

    • Logs our message.

    • Tells the application server we won't use this EJB reference again.

  5. Create the client using C++ code similar to the following. The exact code may vary with your C++ implementation. This code was written for ORBacus for C++ 4.0.5 and some of the C++ code in this example may be specific to that product.

    //Code Example: Client.cpp
#include <fstream.h>

// C++ ORB Vendor specific include files
// These are from C++ ORBacus 4.0.5

#include <OB/CORBA.h>
#include <OB/OBORB.h>

// Include files generated from our IDL
#include <java/lang/Exception.h>
#include <java/lang/Throwable.h>
#include <javax/ejb/CreateException.h>
#include <javax/ejb/RemoveException.h>
#include <ejbinterop/Logger.h>
#include <ejbinterop/LoggerHome.h>

/**
 * Given an ORB and a corbaname URL for a LoggerHome
 * object, logs a simple string message on the server.
 */
void
run(CORBA::ORB_ptr orb, const char* logger_home_url)
{
  cout << "Looking for: " << logger_home_url << endl;

  // Look up the LoggerHome object in the naming context
  // pointed to by the corbaname URL
  CORBA::Object_var home_obj
    = orb->string_to_object(logger_home_url);

  // Perform a safe downcast
  ejbinterop::LoggerHome_var home
    = ejbinterop::LoggerHome::_narrow(home_obj.in());

  assert(!CORBA::is_nil(home));

  // Create a Logger EJB reference
  ejbinterop::Logger_var logger = home->create();

  CORBA::WStringValue_var msg =
    new CORBA::WStringValue((const CORBA::WChar*)L"Message
      from a C++ client");

  cout << "Logging..." << endl;

  // Log our message
  logger->logString(msg);

  // Tell the application server we won't use this
  // EJB reference any more
  logger->remove();

  cout << "Done" << endl;
}

/**
 * Simple main method that checks arguments, creates an
 * ORB, and handles exceptions.
 */
int
main(int argc, char* argv[])
{
  int exit_code = 0;
  CORBA::ORB_var orb;

  try {

  // Check the arguments
  if (argc != 2) {
    cerr << "Usage: Client <corbaname URL of LoggerHome>" << endl;
    return 1;
  }

  // Create an ORB
  orb = CORBA::ORB_init(argc, argv);

  // Register value factories

  // NOTE: This is overkill for the example since we'll never
  // get these exceptions.  Also, the _OB_id method is a
  // proprietary feature of ORBacus C++ generated code.
  CORBA::ValueFactory factory = new java::lang::Throwable_init;
  orb -> register_value_factory(java::lang::Throwable::_OB_id(),
    factory);
  factory -> _remove_ref();

  factory = new java::lang::Exception_init;
  orb -> register_value_factory(java::lang::Exception::_OB_id(),
    factory);
  factory -> _remove_ref();

  factory = new javax::ejb::CreateException_init;
  orb -> 		    register_value_factory(javax::ejb::CreateException::_OB_id(),
      factory);
  factory -> _remove_ref();

  factory = new javax::ejb::RemoveException_init;
  orb ->
    register_value_factory(javax::ejb::RemoveException::_OB_id(),
      factory);
  factory -> _remove_ref();

  // Perform the work
  run(orb, argv[1]);

} catch(const CORBA::Exception& ex) {
  // Handle any CORBA related exceptions
  cerr << ex._to_string() << endl;
  exit_code = 1;
}

  // Release any ORB resources
  if (!CORBA::is_nil(orb)) {
    try {
      orb -> destroy();
    } catch(const CORBA::Exception& ex) {
      cerr << ex._to_string() << endl;
      exit_code = 1;
    }
  }

  return exit_code;
}
  6. Use your C++ compiler to compile all of the C++ files, including the Client.cpp file, to create a Client executable. Such tools vary widely across platforms, so consult your product documentation for instructions.

    7. Part IV: Deploy the Enterprise JavaBean component

  7. Deploy the enterprise bean using your favorite application server. The following steps describe how to deploy the LoggerEJB component using the J2EE 1.3 Reference Implementation (RI).
    8.
    1. Start the RI application from a terminal window or command prompt by typing:
      2. 	$J2EE_HOME/bin/j2ee -verbose

    2. When the J2EE 1.3 RI indicates "J2EE server startup complete", run the deployment tool from another terminal window or command prompt by typing:
      3. 	$J2EE_HOME/bin/deploytool

    3. From the deployment tool, select File -> New -> Application.

    4. In the Application File Name field, enter Logger.ear to indicate in which file to create the application.

    5. In the Application Display Name field, enter Logger

    6. Select OK to save the settings and close this dialog window.

    7. From the deployment tool, select File -> New -> Enterprise Bean.

    8. Select Next if you get the Introduction screen. If not, continue.

    9. In the New EnterpriseBean Wizard, select Edit in the Contents box.

    10. Expand the Available Files list, and add the following four .class files from our ejbinterop package: Logger.class , LoggerHome.class , LoggerEJB.class , LogMessage.class . Select OK, then Next.

    11. Select Stateless Session Bean Type.

    12. Select ejbinterop.LoggerEJB for the Enterprise Bean Class .

    13. Select ejbinterop.LoggerHome for the Remote Home Interface .

    14. Select ejbinterop.Logger for the Remote Interface .

    15. Select the Next button until you get to the Security Settings page.

    16. Select the Deployment Settings button.

    17. Select Support Client Choice .

    18. Select OK to save the settings and close this dialog window.

    19. Select Finish.

    20. From the deployment tool, select, Tools -> Deploy.

    21. If running the Java RMI-IIOP client only, select Return Client JAR.

    22. Select Next.

    23. Enter ejbinterop/logger in the JNDI Name for our LoggerEJB field.

    24. Select Finish.

    25. Select File -> Exit to exit the deploytool.

    Now, the Logger application with our LoggerEJB components are deployed and ready to receive messages.

    Part V: Run the client executable

  8. Run the client executable. One way you can run the client executable is to enter the following URL in a terminal window from the directory containing the executable client file:
    9. Client corbaname:iiop:1.2@localhost:1050#ejbinterop/logger

    In this URL,

    • Client is the name of the application to run.

    • corbaname specifies that we will resolve a stringified name from a specific naming context.

    • iiop:1.2 tells the ORB to use the IIOP protocol and GIOP 1.2.

    • The host machine on which to find the reference is localhost, the local machine. To expand this example to run on two machines, enter the IP address or host name of the machine on which the server is running instead of localhost.

    • 1050 is the port on which the naming service is listening for requests. By default in the J2EE v.1.3 RI, the default port the naming service listens on is port 1050. The portion of the reference up to this point at the hash mark ( Client corbaname:iiop:1.2@localhost:1050 ) is the URL that returns the root naming context.

    • ejbinterop/logger is the name to resolve in the naming context.

    If you are using the J2EE 1.3 Reference Implementation, you should see a message similar to the following printed on the application server:

Sep 21, 2001 3:33:07 PM PDT: Message from a C++ client ejbinterop/
logger is the name to be resolved from the Naming Service.

    Part VI: Stop the J2EE Server

  9. Stop the J2EE server. To stop the server, enter this command in a terminal window or command prompt.
    10. $J2EE_HOME/bin/j2ee -stop

    Procedures for stopping running processes vary among operating systems, so if you are running a different server, consult your system documentation for details.

Creating a Java RMI-IIOP client application

Using the same example, we can easily develop a Java RMI-IIOP client that connects to an enterprise bean. The differences from the example using a C++ client are:

  • In your client CLASSPATH, you must include the location of the client JAR file created by the J2EE application server running the desired enterprise bean. That JAR file contains the necessary client stubs.

  • When deploying the application using the J2EE 1.3 RI, check the box Return Client Jar in the Deploytool on the first page of the Deploy screen.

The following code is the Java RMI-IIOP version of a client for our LoggerEJB component. Follow the same steps as those presented for the C++ client example. When running the client, use the same URL as in the C++ example.

    //Code Example: LogClient.java
package ejbinterop;

import java.rmi.RemoteException;
import javax.rmi.*;
import java.io.*;
import javax.naming.*;
import javax.ejb.*;

/**
 * Simple Java RMI-IIOP client that uses an EJB component.
 */
public class LogClient
{
    /**
     * Given a corbaname URL for a LoggerHome,
     * log a simple String message on the server.
     */
    public static void run(String loggerHomeURL)
        throws CreateException, RemoveException,
               RemoteException, NamingException
    {
        System.out.println("Looking for: " + loggerHomeURL);

        // Create an InitialContext. This will use the
        // CosNaming provider we will specify at runtime.
        InitialContext ic = new InitialContext();

        // Lookup the LoggerHome in the naming context
        // pointed to by the corbaname URL
        Object homeObj = ic.lookup(loggerHomeURL);

        // Perform a safe downcast
        LoggerHome home
            = (LoggerHome)PortableRemoteObject.narrow(homeObj,
    LoggerHome.class);

        // Create a Logger EJB reference
        Logger logger = home.create();

        System.out.println("Logging...");

        // Log our message
        logger.logString("Message from a Java RMI-IIOP client");

        // Tell the application server we won't use this
        // EJB reference anymore
        logger.remove();

        System.out.println("Done");
    }

    /**
     * Simple main method to check arguments and handle
     * exceptions.
     */
    public static void main(String args[])
    {
        try {

            if (args.length != 1) {
                System.out.println("Args: corbaname URL of LoggerHome");
                System.exit(1);
            }

            LogClient.run(args[0]);

        } catch (Throwable t) {
            t.printStackTrace();
            System.exit(1);
        }
    }
}

Running the application with the Java RMI-IIOP client

When running the example application with a Java RMI-IIOP client instead of a C++ client, follow these steps:

  1. Compile the . java files in the ejbinterop / directory with the following command:
    2. javac -classpath $J2EE_HOME/lib/j2ee.jar:<ejbinterop_directory> *.java

  2. Deploy the Enterprise JavaBean component as described in Deploy the Enterprise JavaBean component. Remember to select Return Client JAR on the Tools -> Deploy page when running a Java RMI-IIOP client application. The commands in the Deployment topic instruct you to start the J2EE RI or other application server.

  3. Run the client application using a command similar to the following:

    java -classpath $J2EE_HOME/lib/j2ee.jar:
<path to LoggerClient.jar>/LoggerClient.jar:
<directory_above_ejbinterop>:<ejbinterop_directory>
ejbinterop.LogClient
corbaname:iiop:1.2@localhost:1050#ejbinterop/logger

    In the window in which the J2EE RI is running, you will see this:

    Jan 31, 2002 2:27:47 PM PST: Message from a Java RMI-IIOP client

    In the window from where the client is run, you will see this:

    Looking for: corbaname:iiop:1.2@localhost:1050#ejbinterop/logger
Logging...
Done

  4. Stop the J2EE server.

Beyond the Basic Application

This section contains the following information:

  • Where to go from here
  • Tips for complex interfaces
  • Links to similar examples

Where to go from here

To enhance the application you could:

  • Develop the example to use valuetypes.

    • To do this, remove the -noValueMethods switch when you run rmic . Rerun your IDL to C++ language mapping compiler to verify that it supports the valuetypes that have been generated.

  • Add another method to Logger that actually takes a LogMessage .

Tips for complex interfaces

The interfaces are key to the communication between clients and servers speaking different languages. To increase the probability of success in this area, consider the following suggestions:

  • Avoid using complex Java classes, such as collections in java.util , for method parameters or return types.

    • After these types are mapped to IDL, you will be forced to implement them in your client programming language. In addition, since Java Object Serialization and RMI-IIOP APIs allow the wire format and internal representation of classes to evolve over time, your CORBA client applications may be incompatible across JavaTM 2 Platform, Standard Edition (J2SETM) implementations or versions.

  • Start with IDL.

    • You may want complex data structures in your return types or method parameters. In this case, try starting with IDL. Define data structures and even exceptions in IDL, and then use them in your EJB interfaces. This will prevent artifacts of the reverse mapping from creeping into your CORBA interfaces.

    For instance, try defining the LogMessage class in IDL initially, and then using the resulting class of a Java language to IDL compilation as a method parameter in the Logger EJB component.

  • Avoid overloading in EJB interfaces.

    • CORBA IDL does not support method overloading, and the Java language to IDL mapping specification handles this by creating IDL method definitions that combine the method name with all its IDL parameter types. This leads to very unfriendly method names for developers using languages other than the Java programming language.

  • Consider using bridges.

    • If the available options are still too limited or impact the code you wish to write, consider using a server-side bridge. You can read more about constructing such bridges from the sites listed in the links section.

Links to similar examples

Several vendors implementing J2EE technology have excellent examples and tips for integrating CORBA and Enterprise JavaBeans technology:

  • IONA - EJB-CORBA and CORBA-EJB Interoperability at http://www.iona.com/support/docs/iportal_application_server/3.0/DevelopGuide/html/intro-RMI.html#281858.
  • BEA - EJB-to-CORBA/Java Simpapp Sample Application at http://edocs.bea.com/wle/wle50/interop/ejbcorba.htm
  • Borland - Sevens steps to build a VisiBroker C++ CORBA Client for an EJB Server at http://www.borland.com/devsupport/appserver/faq/ejbcpp/ejb_cpp.html

Copyright © 2002-2004 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, California 94303, U.S.A. All rights reserved.

Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in this product. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S. and other countries.

This product is distributed under licenses restricting its use, copying distribution, and decompilation. No part of this product may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any.

Third-party software, including font technology, is copyrighted and licensed from Sun suppliers.

Sun, Sun Microsystems, the Sun logo, Java, Enterprise JavaBeans, EJB, J2EE and Java SE are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

UNIX is a registered trademark in the United States and other countries, exclusively licensed through X/Open Company, Ltd.


Getting Started Using RMI-IIOP

Tutorial: Getting Started Using RMI-IIOP

This tutorial shows you the steps to follow to create a distributed version of the classic "Hello World" program using JavaTM Remote Method Invocation (RMI) over Internet Inter-ORB Protocol (IIOP). RMI-IIOP adds CORBA (Common Object Request Broker Architecture) capability to Java RMI, providing standards-based interoperability and connectivity to many other programming languages and platforms. RMI-IIOP enables distributed Web-enabled Java applications to transparently invoke operations on remote network services using the industry standard IIOP defined by the Object Management Group. Runtime components include a Java ORB for distributed computing using IIOP communication.

RMI-IIOP is for Java programmers who want to program to the RMI interfaces, but use IIOP as the underlying transport. RMI-IIOP provides interoperability with other CORBA objects implemented in various languages - but only if all the remote interfaces are originally defined as Java RMI interfaces. It is of particular interest to programmers using Enterprise JavaBeans (EJB), since the remote object model for EJBs is RMI-based.

Other options for creating distributed applications are:

  • JavaTM Interface Definition Language (IDL)

    Java IDL is for CORBA programmers who want to program in the Java programming language based on interfaces defined in CORBA Interface Definition Language (IDL). This is "business as usual" CORBA programming, supporting Java in exactly the same way as other languages like C++ or COBOL.

  • JavaTM Remote Method Invocation (RMI).

    The Java RMI system allows an object running in one Java Virtual Machine (VM) to invoke methods on an object running in another Java VM. RMI provides for remote communication between programs written in the Java programming language via the Java Remote Method Protocol (JRMP).

Tutorial: The Hello World Application

The distributed Hello World example uses a client application to make a remote method call via IIOP to a server running on the host from which the client was downloaded. When the client runs, "Hello from MARS!" is displayed.

This tutorial is organized as follows:

  1. The steps to write the source files
  2. The steps to compile the example
  3. The steps to run the example

step icon Each step in the tutorial is indicated by this symbol.

Write or Download the Source Files

There are three tasks to complete in this section:

  1. Define the functions of the remote class as an interface written in the Java programming language
  2. Write the implementation class
  3. Write the server class
  4. Write a client program that uses the remote service
The source files used in this tutorial are:
  • HelloInterface.java - a remote interface
  • HelloImpl.java - a remote object implementation that implements HelloInterface
  • HelloServer.java - an RMI server that creates an instance of the remote object implementation and binds that instance to a name in the Naming Service
  • HelloClient.java - a client application that invokes the remote method, sayHello()

Follow the steps below to create the source files or download and unzip HelloRMIIIOP.zip.

Define the functions of the remote class as an interface written in the Java programming language

In the Java programming language, a remote object is an instance of a class that implements a Remote interface. Your remote interface will declare each of the methods that you would like to call from other machines. Remote interfaces have the following characteristics:
  • The remote interface must be declared public. Otherwise, a client will get an error when attempting to load a remote object that implements the remote interface, unless that client is in the same package as the remote interface.
  • The remote interface extends the java.rmi.Remote interface.
  • Each method must declare java.rmi.RemoteException (or a superclass of RemoteException) in its throws clause, in addition to any application-specific exceptions.
  • The data type of any remote object that is passed as an argument or return value (either directly or embedded within a local object) must be declared as the remote interface type (for example, HelloInterface) not the implementation class (HelloImpl).

For this example, create all of the source files in the same directory, for example, $HOME/mysrc/helloWorld.

step icon Create the file HelloInterface.java. The following code is the interface definition for the remote interface, HelloInterface, which contains just one method, sayHello:

//HelloInterface.java
import java.rmi.Remote;

public interface HelloInterface extends java.rmi.Remote {
   public void sayHello( String from ) throws java.rmi.RemoteException;
}
Because remote method invocations can fail in very different ways from local method invocations (due to network-related communication problems and server problems), remote methods will report communication failures by throwing a java.rmi.RemoteException. If you want more information on failure and recovery in distributed systems, you may wish to read A Note on Distributed Computing.

Write The Implementation Class

At a minimum, a remote object implementation class, HelloImpl.java must:

  • Declare that it implements at least one remote interface
  • Define the constructor for the remote object
  • Provide implementations for the methods that can be invoked remotely

step icon Create the file HelloImpl.java. The code for this file follows. An explanation of each of the preceding steps follows the source code:

    //HelloImpl.java
import javax.rmi.PortableRemoteObject;

public class HelloImpl extends PortableRemoteObject implements HelloInterface {
   public HelloImpl() throws java.rmi.RemoteException {
       super();     // invoke rmi linking and remote object initialization
   }

   public void sayHello( String from ) throws java.rmi.RemoteException {
       System.out.println( "Hello from " + from + "!!" );
       System.out.flush();
   }
}

Implement a remote interface

In the Java programming language, when a class declares that it implements an interface, a contract is formed between the class and the compiler. By entering into this contract, the class is promising that it will provide method bodies, or definitions, for each of the method signatures declared in that interface. Interface methods are implicitly public and abstract, so if the implementation class doesn't fulfill its contract, it becomes by definition an abstract class, and the compiler will point out this fact if the class was not declared abstract.

The implementation class in this example is HelloImpl. The implementation class declares which remote interface(s) it is implementing. Here is the HelloImpl class declaration:

  public class HelloImpl extends PortableRemoteObject
    implements HelloInterface{
As a convenience, the implementation class can extend a remote class, which in this example is javax.rmi.PortableRemoteObject. By extending PortableRemoteObject, the HelloImpl class can be used to create a remote object that uses IIOP-based transport for communication.

Define the constructor for the remote object

The constructor for a remote class provides the same functionality as the constructor for a non-remote class: it initializes the variables of each newly created instance of the class, and returns an instance of the class to the program which called the constructor.

In addition, the remote object instance will need to be "exported". Exporting a remote object makes it available to accept incoming remote method requests, by listening for incoming calls to the remote object on an anonymous port. When you extend javax.rmi.PortableRemoteObject, your class will be exported automatically upon creation.

Because the object export could potentially throw a java.rmi.RemoteException, you must define a constructor that throws a RemoteException, even if the constructor does nothing else. If you forget the constructor, javac will produce the following error message:

    HelloImpl.java:3: unreported exception java.rmi.RemoteException; must be
    caught or declared to be thrown.

        public class HelloImpl extends PortableRemoteObject implements HelloInterface{
               ^
        1 error
To review: The implementation class for a remote object needs to:
  • Implement a remote interface
  • Export the object so that it can accept incoming remote method calls
  • Declare its constructor(s) to throw at least a java.rmi.RemoteException
Here is the constructor for the HelloImpl class:
  public HelloImpl() throws java.rmi.RemoteException {
    super();
  }
Note the following:
  • The super method call invokes the no-argument constructor of javax.rmi.PortableRemoteObject, which exports the remote object.
  • The constructor must throw java.rmi.RemoteException, because RMI's attempt to export a remote object during construction might fail if communication resources are not available.

Although the call to the superclass's no-argument constructor, super(), occurs by default (even if omitted), it is included in this example to make clear the fact that the superclass will be constructed before the class.

Provide an implementation for each remote method

The implementation class for a remote object contains the code that implements each of the remote methods specified in the remote interface. For example, here is the implementation for the sayHello() method, which returns the string "Hello from MARS!!" to the caller:
   public void sayHello( String from ) throws java.rmi.RemoteException {
       System.out.println( "Hello from " + from + "!!");
       System.out.flush();
   }
Arguments to, or return values from, remote methods can be any data type for the Java platform, including objects, as long as those objects implement the interface java.io.Serializable. Most of the core classes in java.lang and java.util implement the Serializable interface. In RMI:
  • By default, local objects are passed by copy, which means that all data members (or fields) of an object are copied, except those marked as static or transient. Please refer to the Java Object Serialization Specification for information on how to alter the default serialization behavior.
  • Remote objects are passed by reference. A reference to a remote object is actually a reference to a stub, which is a client-side proxy for the remote object. Stubs are described fully in the Java Remote Method Invocation Specification. We'll create them later in this tutorial in the section: Use rmic to generate stubs and skeletons.

Write The Server Class

A server class is the class which has a main method that creates an instance of the remote object implementation, and binds that instance to a name in the Naming Service. The class that contains this main method could be the implementation class itself, or another class entirely.

In this example, the main method is part of HelloServer.java, which does the following:

  • Creates an instance of the servant
  • Publishes the object reference

step icon Create the file HelloServer.java. The source code for this file follows. An explanation of each of the preceding steps follows the source code:

    //HelloServer.java
import javax.naming.InitialContext;
import javax.naming.Context;

public class HelloServer {
    public static void main(String[] args) {
        try {
            // Step 1: Instantiate the Hello servant
            HelloImpl helloRef = new HelloImpl();

            // Step 2: Publish the reference in the Naming Service
            // using JNDI API
            Context initialNamingContext = new InitialContext();
            initialNamingContext.rebind("HelloService", helloRef );

            System.out.println("Hello Server: Ready...");

         } catch (Exception e) {
            System.out.println("Trouble: " + e);
            e.printStackTrace();
         }
     }
}

Create an instance of a remote object

The main method of the server needs to create an instance of the remote object implementation, or Servant. For example:
    HelloImpl helloRef = new HelloImpl();
The constructor exports the remote object, which means that once created, the remote object is ready to accept incoming calls.

Publish the object reference

For a caller (client, peer, or client application) to be able to invoke a method on a remote object, that caller must first obtain a reference to the remote object.

Once a remote object is registered on the server, callers can look up the object by name (using a naming service), obtain a remote object reference, and then remotely invoke methods on the object. In this example, we use the Naming Service that is part of the Object Request Broker Daemon (orbd).

For example, the following code binds the name "HelloService" to a reference for the remote object:

            // Step 2: Publish the reference in the Naming Service
            // using JNDI API
            Context initialNamingContext = new InitialContext();
            initialNamingContext.rebind("HelloService", helloRef );

Note the following about the arguments to the rebind method call:

  • The first argument, "HelloService", is a java.lang.String, representing the name of the remote object to bind

  • The second argument, helloRef is the object id of the remote object to bind

Write a client program that uses the remote service

The client application in this example remotely invokes the sayHello method in order to get the string "Hello from MARS!!" to display when the client application runs.

step icon Create the file HelloClient.java. Here is the source code for the client application:

    //HelloClient.java
import java.rmi.RemoteException;
import java.net.MalformedURLException;
import java.rmi.NotBoundException;
import javax.rmi.*;
import java.util.Vector;
import javax.naming.NamingException;
import javax.naming.InitialContext;
import javax.naming.Context;

public class HelloClient {

    public static void  main( String args[] ) {
        Context ic;
        Object objref;
        HelloInterface hi;

        try {
            ic = new InitialContext();

        // STEP 1: Get the Object reference from the Name Service
        // using JNDI call.
            objref = ic.lookup("HelloService");
            System.out.println("Client: Obtained a ref. to Hello server.");

        // STEP 2: Narrow the object reference to the concrete type and
        // invoke the method.
            hi = (HelloInterface) PortableRemoteObject.narrow(
                objref, HelloInterface.class);
            hi.sayHello( " MARS " );

        } catch( Exception e ) {
            System.err.println( "Exception " + e + "Caught" );
            e.printStackTrace( );
            return;
        }
    }
}

First, the client application gets a reference to the remote object implementation (advertised as "HelloService") from the Naming Service using Java Naming and Directory Interface [TM] (JNDI) calls. Like the Naming.rebind method, the Naming.lookup method takes java.lang.String value representing the name of the object to look up. You supply Naming.lookup() the name of the object you want to look up, and it returns the object bound to that name. Naming.lookup() returns the stub for the remote implementation of the Hello interface to its caller (HelloClient).

  • The client application invokes the remote sayHello() method on the server's remote object, causing the string "Hello from MARS!!" to be displayed on the command line.

    Compile the Example

    The source code for this example is now complete and the directory contains four files:
    • HelloInterface.java contains the source code for the remote interface
    • HelloImpl.java contains the source code for the remote object implementation
    • HelloServer.java contains the source code for the server
    • HelloClient.java contains the source code for the client application
    In this section, you compile the remote object implementation file, HelloImpl.java, in order to create the .class files needed to run rmic. You then run the rmic compiler to create stubs and skeletons. A stub is a client-side proxy for a remote object which forwards RMI-IIOP calls to the server-side dispatcher, which in turn forwards the call to the actual remote object implementation. The last task is to compile the remaining .java source files to create .class files.

    The following tasks will be completed in this section:

    1. Compile the remote object implementation
    2. Use rmic to generate stubs and skeletons
    3. Compile the source files

    Compile the remote object implementation

    To create stub and skeleton files, the rmic compiler must be run on the fully-qualified package names of compiled class files that contain remote object implementations. In this example, the file that contains the remote object implementations is HelloImpl.java. To generate the stubs and skeletons:

    step icon Compile HelloImpl.java, as follows:

        javac -d . -classpath . HelloImpl.java

    The "-d ." option indicates that the generated files should be placed in the directory from which you are running the compiler. The "-classpath ." option indicates that files on which HelloImpl.java is dependent can be found in this directory.

    Use rmic to generate skeletons and stubs

    To create CORBA-compatible stub and skeleton files, run the rmic compiler with the -iiop option. The rmic -iiop command takes one or more class names as an argument and produces class files of the form _HelloImpl_Tie.class and _HelloInterface_Stub.class. The remote implementation file, HelloImpl.class, is the class name to pass in this example.

    For an explanation of rmic options, you can refer to the Solaris rmic manual page or the Windows rmic manual page.

    step icon To create the stub and skeleton for the HelloImpl remote object implementation, run rmic like this:

        rmic -iiop HelloImpl

    The preceding command creates the following files:

    • _HelloInterface_Stub.class - the client stub
    • _HelloImpl_Tie.class - the server skeleton

    Compile the source files

    step icon Compile the source files as follows:

        javac -d . -classpath . HelloInterface.java HelloServer.java HelloClient.java

    This command creates the class files HelloInterface.class, HelloServer.class, and HelloClient.class. These are the remote interface, the server, and the client application respectively. For an explanation of javac options, you can refer to the Solaris javac manual page or the Windows javac manual page.

    Run the Example

    The following tasks will be completed in this section:
    1. Start the Naming Service
    2. Start the server
    3. Run the client application

    Start the Naming Service

    For this example, we will use the Object Request Broker Daemon, orbd, which includes both a Transient and a Persistent Naming Service, and is available with every download of J2SE 1.4 and higher.

    For a caller (client, peer, or client application) to be able to invoke a method on a remote object, that caller must first obtain a reference to the remote object.

    Once a remote object is registered on the server, callers can look up the object by name, obtain a remote object reference, and then remotely invoke methods on the object.

    step icon Start the Naming Service by running orbd from the command line.

    For this example, on the Solaris operating system:

        orbd -ORBInitialPort 1050&

    or, on the Windows operating system:

        start orbd -ORBInitialPort 1050

    You must specify a port on which to run orbd. For this example the port of 1050 is chosen because in the Solaris operating environment, a user must become root to start a process on a port under 1024. For more on the orbd tool, you can refer to the orbd manual page.

    You must stop and restart the server any time you modify a remote interface or use modified/additional remote interfaces in a remote object implementation. Otherwise, the type of the object reference bound in the Naming Service will not match the modified class.

    Start the server

    Open another terminal window and change to the directory containing the source files for this example. The command for running the client has been spread out below to make it easier to read, but should be typed without returns between the lines. The following command shows how to start the HelloServer server. If you used a port other than 1050 or a host other than localhost when starting the orbd tool, replace those values in the command below with the actual values used to start orbd.

    step icon Start the Hello server, as follows:

        java
      -classpath .
      -Djava.naming.factory.initial=com.sun.jndi.cosnaming.CNCtxFactory
      -Djava.naming.provider.url=iiop://localhost:1050
      HelloServer

    For an explanation of java options, you can refer to the Solaris java manual page or the Windows java manual page.

    The output should look like this:

    Hello Server: Ready ...

    Run the client application

    Once the Naming Service and server are running, the client application can be run. From a new terminal window, go to the source code directory, and run the client application from the command line, as shown below. The command for running the client has been spread out below to make it easier to read, but should be typed without returns between the lines. If you used a port other than 1050 or a host other than localhost when starting the orbd tool, replace those values in the command below with the actual values used to start orbd.

    step icon Start the client application, as follows:

        java
      -classpath .
      -Djava.naming.factory.initial=com.sun.jndi.cosnaming.CNCtxFactory
      -Djava.naming.provider.url=iiop://localhost:1050
      HelloClient
    After running the client application, you will see output similar to the following on your display in the client window:
    Client: Obtained a ref. to Hello server.

    The following message will display in the server window:

    Hello from  MARS

    ORBD and the Hello server will continue to run until they are explicitly stopped. On Solaris, you can stop these processes using the pkill orbd and pkill HelloServer commands from a terminal window. On Windows, you can type Ctrl+C in a prompt window to kill the process.

    This completes the basic RMI-IIOP tutorial. If you are ready to move on to more complicated applications, here are some sources that may help:

    • http://forum.java.sun.com/forum.jsp?forum=59, The Sun Developer's Forum for RMI-IIOP. You must register with the Java Developer Connection to access this site.

    • EJB clients interact with the J2EE EJB tier using the RMI-IIOP protocol. For more information on using RMI-IIOP in this way, see the Java 2 Platform, Enterprise Edition Blueprints or the EJB Tutorials.

    • Another RMI-IIOP tutorial includes support for the Portable Object Adapter (POA). POA support for RMI-IIOP is non-standard.

    • The Java IDL tutorial includes an example for running the client and server on different machines. The concepts of Running the Hello World Example on Two Machines apply to this example as well.

    RMI-IIOP Documentation Home


Java RMI over IIOP Documentation

Java RMI over IIOP

 Documentation Contents

Java Remote Method Invocation over Internet Inter-ORB Protocol technology ("RMI-IIOP") is part of the Java Platform, Standard Edition (Java SE). The RMI Programming Model enables the programming of CORBA servers and applications via the rmi API. You can choose to work completely within the Java programming language using the Java Remote Method Protocol (JRMP) as the transport, or work with other CORBA-compliant programming languages using the Internet InterORB Protocol (IIOP).

RMI-IIOP utilizes the Java CORBA Object Request Broker (ORB) and IIOP, so you can write all of your code in the Java programming language, and use the rmic compiler to generate the code necessary for connecting your applications via the Internet InterORB Protocol (IIOP) to others written in any CORBA-compliant language. To work with CORBA applications in other languages, IDL can be generated from Java programming language interfaces using the rmic compiler with the -idl option. To generate IIOP stubs and tie classes, use the rmic compiler with the -iiop option.

Overview

  • Overview - An overview of when you should use RMI-IIOP and the options for distributed application development.

API Specification

  • org.omg.CORBA
  • org.omg.PortableServer
  • org.omg.CosNaming
  • javax.rmi.CORBA
  • javax.rmi (with a link to class PortableRemoteObject)

Tutorials and Programmer's Guides

  • Tutorial - Getting Started Using Java RMI over IIOP.
  • Example - RMI over IIOP with a POA server-side model.
  • Java RMI-IIOP Programmer's Guide.
  • Enterprise JavaBeans Components and CORBA Clients - A Developer's Guide.
  • Java IDL and Java RMI-IIOP Technologies: Using Portable Interceptors - For advanced CORBA developers.

API Enhancements

  • API Enhancements in J2SE 5.0 - Changes in CORBA (Java IDL, RMI-IIOP) Features.

Tools

  • Java IDL and RMI-IIOP Tools

More Information

See the Java RMI over IIOP Technology Home Page.

The Java IDL technology pages include a lot of information that is useful to developers using Java RMI-IIOP technology.

The OMG is the official source of information for all CORBA and IIOP related information. The CORBA 2.3.1 Specification is available electronically from formal/99-10-07. The URLs for the CORBA specifications may change. If this link is broken, link to http://www.omg.org and search the specifications.

For more information on which specifications are implemented in this release of the Java platform, see the compliance document.

For questions, please try the user supported forum for RMI-IIOP technology, which is available at http://forum.java.sun.com.

Copyright © 2001-2004 Sun Microsystems, Inc. All Rights Reserved.
Feedback 		Sun


POA Model

Getting Started Using RMI-IIOP:
Example Using POA-based server-side model

This tutorial shows you the steps to follow to create a distributed version of the classic "Hello World" program using JavaTM Remote Method Invocation (RMI) over Internet Inter-ORB Protocol (IIOP). RMI-IIOP adds CORBA (Common Object Request Broker Architecture) capability to Java connectivity to many other programming languages and platforms. RMI-IIOP enables distributed Web-enabled Java remote Management Group. Runtime components include a Java ORB for distributed computing using IIOP communication.

RMI-IIOP is for Java programmers who want to program to the RMI interfaces, but use IIOP as the underlying transport. RMI-IIOP provides interoperability with other CORBA objects implemented in various languages - but only if all the remote interfaces are originally defined as Java RMI interfaces. It is of particular interest to programmers using Enterprise JavaBeans (EJB), since the remote object model for EJBs is RMI-based.

Another option for creating distributed applications is JavaTM IDL. Java IDL is for CORBA programmers who want to program in the Java programming language based on interfaces defined in CORBA Interface Definition Language (IDL). This is "business as usual" CORBA programming, supporting Java in exactly the same way as other languages like C++ or COBOL.

Tutorial: The Hello World Application

The distributed Hello World example uses a client application to make a remote method call via IIOP to a server, running on the host from which the client was downloaded. When the client runs, "Hello World!" is displayed.

This tutorial is organized as follows:

  1. The steps to write the source files
  2. The steps to compile the class files
  3. The steps to start the Naming Service, server, and client

Write or Download the Source Files

There are three tasks to complete in this section:

  1. Define the functions of the remote class as an interface written in the Java programming language
  2. Write the implementation class
  3. Write the server class
  4. Write a client program that uses the remote service
The source files created in this tutorial (and which can be downloaded here) are:
  • HelloInterface.java - a remote interface
  • HelloImpl.java - a remote object implementation that implements HelloInterface
  • HelloServer.java - an RMI server that creates an instance of the remote object implementation and binds that instance to a name in the Naming Service
  • HelloClient.java - a client application that invokes the remote method, sayHello()

Define the functions of the remote class as an interface written in the Java programming language

In the Java programming language, a remote object is an instance of a class that implements a Remote interface. Your remote interface will declare each of the methods that you would like to call from other machines. Remote interfaces have the following characteristics:
  • The remote interface must be declared public. Otherwise, a client will get an error when attempting to load a remote object that implements the remote interface, unless that client is in the same package as the remote interface.
  • The remote interface extends the java.rmi.Remote interface.
  • Each method must declare java.rmi.RemoteException (or a superclass of RemoteException) in its throws clause, in addition to any application-specific exceptions.
  • The data type of any remote object that is passed as an argument or return value (either directly or embedded within a local object) must be declared as the remote interface type (for example, HelloInterface) not the implementation class (HelloImpl).

For this example, create all of the source files in the same directory, for example, $HOME/mysrc/RMIHelloPOA. Here is the interface definition for the remote interface, HelloInterface. The interface contains just one method, sayHello:

    //HelloInterface.java
import java.rmi.Remote;

public interface HelloInterface extends java.rmi.Remote {
  public void sayHello() throws java.rmi.RemoteException;
}
Because remote method invocations can fail in very different ways from local method invocations (due to network-related communication problems and server problems), remote methods will report communication failures by throwing a java.rmi.RemoteException. If you want more information on failure and recovery in distributed systems, you may wish to read A Note on Distributed Computing.

Write The Implementation Class

At a minimum, a remote object implementation class, HelloImpl.java must:

  • Declare that it implements at least one remote interface
  • Define the constructor for the remote object
  • Provide implementations for the methods that can be invoked remotely
An explanation of each of the preceding steps follows the source for HelloImpl.java:
    //HelloImpl.java
import javax.rmi.PortableRemoteObject;

public class HelloImpl extends PortableRemoteObject implements HelloInterface {
  public HelloImpl() throws java.rmi.RemoteException {
    super();     // invoke rmi linking and remote object initialization
  }

  public void sayHello() throws java.rmi.RemoteException {
    System.out.println( "It works!  Hello World!!" );
  }
}

Implement a remote interface

In the Java programming language, when a class declares that it implements an interface, a contract is formed between the class and the compiler. By entering into this contract, the class is promising that it will provide method bodies, or definitions, for each of the method signatures declared in that interface. Interface methods are implicitly public and abstract, so if the implementation class doesn't fulfill its contract, it becomes by definition an abstract class, and the compiler will point out this fact if the class was not declared abstract.

The implementation class in this example is HelloImpl. The implementation class declares which remote interface(s) it is implementing. Here is the HelloImpl class declaration:

  public class HelloImpl extends PortableRemoteObject
    implements HelloInterface{
As a convenience, the implementation class can extend a remote class, which in this example is javax.rmi.PortableRemoteObject. By extending PortableRemoteObject, the HelloImpl class can be used to create a remote object that uses IIOP-based transport for communication.

Define the constructor for the remote object

The constructor for a remote class provides the same functionality as the constructor for a non-remote class: it initializes the variables of each newly created instance of the class, and returns an instance of the class to the program which called the constructor.

In addition, the remote object instance will need to be "exported". Exporting a remote object makes it available to accept incoming remote method requests, by listening for incoming calls to the remote object on an anonymous port. When you extend javax.rmi.PortableRemoteObject, your class will be exported automatically upon creation.

Because the object export could potentially throw a java.rmi.RemoteException, you must define a constructor that throws a RemoteException, even if the constructor does nothing else. If you forget the constructor, javac will produce the following error message:

    HelloImpl.java:3: unreported exception java.rmi.RemoteException; must be
    caught or declared to be thrown.

        public class HelloImpl extends PortableRemoteObject implements HelloInterface{
               ^
        1 error
To review: The implementation class for a remote object needs to:
  • Implement a remote interface
  • Export the object so that it can accept incoming remote method calls
  • Declare its constructor(s) to throw at least a java.rmi.RemoteException
Here is the constructor for the HelloImpl class:
  public HelloImpl() throws java.rmi.RemoteException {
    super();
  }
Note the following:
  • The super method call invokes the no-argument constructor of javax.rmi.PortableRemoteObject, which exports the remote object.
  • The constructor must throw java.rmi.RemoteException, because RMI's attempt to export a remote object during construction might fail if communication resources are not available.

java.rmi.RemoteException is a checked exception, not a runtime exception.

Although the call to the superclass's no-argument constructor, super(), occurs by default (even if omitted), it is included in this example to make clear the fact that the superclass will be constructed before the class.

Provide an implementation for each remote method

The implementation class for a remote object contains the code that implements each of the remote methods specified in the remote interface. For example, here is the implementation for the sayHello() method, which returns the string "It works! Hello World!!" to the caller:
  public void sayHello() throws java.rmi.RemoteException {
    System.out.println( "It works!  Hello World!!" );
  }
Arguments to, or return values from, remote methods can be any data type for the Java platform, including objects, as long as those objects implement the interface java.io.Serializable. Most of the core classes in java.lang and java.util implement the Serializable interface. In RMI:
  • By default, local objects are passed by copy, which means that all data members (or fields) of an object are copied, except those marked as static or transient.
  • Remote objects are passed by reference. A reference to a remote object is actually a reference to a stub, which is a client-side proxy for the remote object. We'll create stubs later in this tutorial in the section: Use rmic to generate stubs and skeletons.

Write The Server Class

A server class is the class which has a main method that creates an instance of the remote object implementation, and binds that instance to a name in the Naming Service. The class that contains this main method could be the implementation class itself, or another class entirely.

In this example, the main method is part of HelloServer.java, which does the following:

  • Creates a Portable Object Adapter (POA) with the appropriate policies
  • Activates the POA Managers
  • Creates an instance of the servant and activates the Tie, creates an instance of a remote object
  • Publishes the object reference
  • Prepares to accept requests from the client
An explanation of each of the preceding steps follows the source for HelloServer.java:

    //HelloServer.java
import javax.naming.InitialContext;
import javax.naming.Context;
import javax.rmi.PortableRemoteObject ;
//Please note that internal Sun APIs
//may change in future releases.
import com.sun.corba.se.internal.POA.POAORB;
import org.omg.PortableServer.*;
import java.util.*;
import org.omg.CORBA.*;
import javax.rmi.CORBA.Stub;
import javax.rmi.CORBA.Util;

public class HelloServer {
  public HelloServer(String[] args) {
    try {
      Properties p = System.getProperties();
      // add runtime properties here
      //Please note that the name of the servertool
      //class may change in future releases.
      p.put("org.omg.CORBA.ORBClass",
          "com.sun.corba.se.internal.POA.POAORB");
      p.put("org.omg.CORBA.ORBSingletonClass",
          "com.sun.corba.se.internal.corba.ORBSingleton");

      ORB orb = ORB.init( args, p );

      POA rootPOA = (POA)orb.resolve_initial_references("RootPOA");

      // STEP 1: Create a POA with the appropriate policies
      Policy[] tpolicy = new Policy[3];
      tpolicy[0] = rootPOA.create_lifespan_policy(
        LifespanPolicyValue.TRANSIENT );
      tpolicy[1] = rootPOA.create_request_processing_policy(
        RequestProcessingPolicyValue.USE_ACTIVE_OBJECT_MAP_ONLY );
      tpolicy[2] = rootPOA.create_servant_retention_policy(
        ServantRetentionPolicyValue.RETAIN);
      POA tPOA = rootPOA.create_POA("MyTransientPOA", null, tpolicy);

      // STEP 2: Activate the POA Manager, otherwise all calls to the
      // servant hang because, by default, POAManager will be in the
      // HOLD state.
      tPOA.the_POAManager().activate();

      // STEP 3: Instantiate the Servant and activate the Tie, If the
      // POA policy is USE_ACTIVE_OBJECT_MAP_ONLY
      HelloImpl helloImpl = new HelloImpl();
      _HelloImpl_Tie tie = (_HelloImpl_Tie)Util.getTie( helloImpl );
      String helloId = "hello";
      byte[] id = helloId.getBytes();
      tPOA.activate_object_with_id( id, tie );

      // STEP 4: Publish the object reference using the same object id
      // used to activate the Tie object.
      Context initialNamingContext = new InitialContext();
      initialNamingContext.rebind("HelloService",
        tPOA.create_reference_with_id(id,
          tie._all_interfaces(tPOA,id)[0]) );
      System.out.println("Hello Server: Ready...");

      // STEP 5: Get ready to accept requests from the client
      orb.run();
    }
      catch (Exception e) {
        System.out.println("Problem running HelloServer: " + e);
        e.printStackTrace();
      }
  }

  public static void main(String args[]) {
    new HelloServer( args );
  }
}

Create a Portable Object Adapter (POA) with the appropriate policies

The main method of the server first needs to create a Portable Object Adapter (POA) with the appropriate policies. For example:
      Policy[] tpolicy = new Policy[3];
      tpolicy[0] = rootPOA.create_lifespan_policy(
        LifespanPolicyValue.TRANSIENT );
      tpolicy[1] = rootPOA.create_request_processing_policy(
        RequestProcessingPolicyValue.USE_ACTIVE_OBJECT_MAP_ONLY );
      tpolicy[2] = rootPOA.create_servant_retention_policy(
        ServantRetentionPolicyValue.RETAIN);
      POA tPOA = rootPOA.create_POA("MyTransientPOA", null, tpolicy);

The Portable Object Adaptor (POA) is designed to provide an object adapter that can be used with multiple ORB implementations with a minimum of rewriting needed to deal with different vendors' implementations. POA support was introduced in J2SE version 1.4.

The POA is also intended to allow persistent objects -- at least, from the client's perspective. That is, as far as the client is concerned, these objects are always alive, and maintain data values stored in them, even though physically, the server may have been restarted many times, or the implementation may be provided by many different object implementations.

The POA allows the object implementor a lot more control. Previously, the implementation of the object was responsible only for the code that is executed in response to method requests. Now, additionally, the implementor has more control over the object's identity, state, storage, and lifecycle.

In this example, the policy values include:

  • The LifespanPolicyValue can have the following values:
    • TRANSIENT - The objects implemented in the POA cannot outlive the POA instance in which they are first created.
    • PERSISTENT - The objects implemented in the POA can outlive the process in which they are first created.

  • The RequestProcessingPolicyValue can have the following values:
    • USE_ACTIVE_OBJECT_MAP_ONLY - If the object ID is not found in the Active Object Map, an OBJECT_NOT_EXIST exception is returned to the client. The RETAIN policy is also required.
    • USE_DEFAULT_SERVANT - If the object ID is not found in the Active Object Map or the NON_RETAIN policy is present, and a default servant has been registered with the POA using the set_servant operation, the request is dispatched to the default servant.
    • USE_SERVANT_MANAGER - If the object ID is not found in the Active Object Map or the NON_RETAIN policy is present, and a servant manager has been registered with the POA using the set_servant_manager operation, the servant manager is given the opportunity to locate a servant or raise an exception.

  • The ServantRetentionPolicyValue can have the following values.
    • RETAIN - to indicate that the POA will retain active servants in its Active Object Map. If no ServantRetentionPolicy is specified at POA creation, the default is RETAIN.
    • NON_RETAIN - to indicate Servants are not retained by the POA.

For more information on POA policies, refer to Chapter 11, Portable Object Adapter of the CORBA/IIOP 2.3.1 Specification at http://www.omg.org/cgi-bin/doc?formal/99-10-07

Activate the POA Managers

Each POA object has an associated POAManager object. A POA Manager may be associated with one or more POA objects. A POA Manager encapsulates the processing state of the POAs it is associated with. In this step, the POA Manager is activated. If this step is missing, all calls to the Servant would hang because, by default, the POA Manager will be in the HOLD state.

      tPOA.the_POAManager().activate();

Create an instance of a remote object and activate the Tie

The main method of the server needs to create an instance of the remote object implementation, or Servant. For example:
    HelloImpl helloImpl = new HelloImpl();
The constructor exports the remote object, which means that once created, the remote object is ready to accept incoming calls.

When using RMI-IIOP technology, your implementations use delegation (known as the Tie model) to associate your implementation with the interface. When you create an instance of your implementation, as above, you also need to create a Tie object to associate it with a CORBA interface. The next few lines of code activate the Tie, but only if the POA policy is USE_ACTIVE_OBJECT_MAP_ONLY.

      _HelloImpl_Tie tie = (_HelloImpl_Tie)Util.getTie( helloImpl );
      String helloId = "hello";
      byte[] id = helloId.getBytes();
      tPOA.activate_object_with_id( id, tie );

Publish the object reference using the same object id used to activate the Tie object

For a caller (client, peer, or client application) to be able to invoke a method on a remote object, that caller must first obtain a reference to the remote object.

Once a remote object is registered on the server, callers can look up the object by name (using a naming service), obtain a remote object reference, and then remotely invoke methods on the object. In this example, we use the Object Request Broker Daemon (orbd), which is a daemon process containing a Bootstrap Service, a Transient Naming Service, a Persistent Naming Service, and a Server Manager.

For example, the following code binds the name "HelloService" to a reference for the remote object:

      Context initialNamingContext = new InitialContext();
      initialNamingContext.rebind("HelloService",
        tPOA.create_reference_with_id(id,
          tie._all_interfaces(tPOA,id)[0]) );
      System.out.println("Hello Server: Ready...");

Note the following about the arguments to the rebind method call:

  • The first argument, "HelloService", is a java.lang.String, representing the name of the remote object to bind

  • The second argument, tPOA.create_reference_with_id(id, tie._all_interfaces(tPOA,id)[0] is the object id of the remote object to bind

Prepare to accept requests from the client

The following line of code, when called by the main thread, enables the ORB to perform work using the main thread.

      orb.run();

Write a client program that uses the remote service

The client application in this example remotely invokes the sayHello method in order to get the string "Hello World!" to display when the client application runs. Here is the code for the client application:

    //HelloClient.java
import java.rmi.RemoteException;
import java.net.MalformedURLException;
import java.rmi.NotBoundException;
import javax.rmi.*;
import java.util.Vector;
import javax.naming.NamingException;
import javax.naming.InitialContext;
import javax.naming.Context;

public class HelloClient {

  public static void  main( String args[] ) {
    Context ic;
    Object objref;
    HelloInterface hi;

    try {
      ic = new InitialContext();
    } catch (NamingException e) {
        System.out.println("failed to obtain context" + e);
        e.printStackTrace();
        return;
    }

    // STEP 1: Get the Object reference from the Name Service
    // using JNDI call.
    try {
      objref = ic.lookup("HelloService");
      System.out.println("Client: Obtained a ref. to Hello server.");
    } catch (NamingException e) {
        System.out.println("failed to lookup object reference");
        e.printStackTrace();
        return;
    }

    // STEP 2: Narrow the object reference to the concrete type and
    // invoke the method.
    try {
      hi = (HelloInterface) PortableRemoteObject.narrow(
        objref, HelloInterface.class);
      hi.sayHello();
    } catch (ClassCastException e) {
        System.out.println("narrow failed");
        e.printStackTrace();
        return;
      } catch( Exception e ) {
            System.err.println( "Exception " + e + "Caught" );
            e.printStackTrace( );
            return;
        }
  }
}

First, the client application gets a reference to the remote object implementation (advertised as "HelloService") from the Name Service using Java Naming and Directory Interface [TM] (JNDI) calls. Like the Naming.rebind method, the Naming.lookup method takes java.lang.String value representing the name of the object to look up. You supply Naming.lookup() the name of the object you want to look up, and it returns the object bound to that name.

  • Naming.lookup() takes care of these tasks:
    • The Name Service returns the _HelloImpl_Stub instance bound to that name
    • The lookup method receives the remote object's (HelloImpl) stub instance and loads the stub class (_HelloImpl_Stub)
    • Naming.lookup returns the stub to its caller (HelloClient)

  • The client application invokes the remote sayHello() method on the server's remote object, causing the string "It works! Hello World!!" to be displayed on the command line.

Compile Class Files

The source code for this example is now complete and the directory contains four files:
  • HelloInterface.java contains the source code for the remote interface
  • HelloImpl.java contains the source code for the remote object implementation
  • HelloServer.java contains the source code for the server
  • HelloClient.java contains the source code for the client application
In this section, you compile the remote object implementation file, HelloImpl.java, in order to create the .class files needed to run rmic. You then run the rmic compiler to create stubs and skeletons. A stub is a client-side proxy for a remote object which forwards RMI-IIOP calls to the server-side dispatcher, which in turn forwards the call to the actual remote object implementation. The last task is to compile the remaining .java source files to create .class files.

The following tasks will be completed in this section:

  1. Compile the remote object implementation
  2. Use rmic to generate stubs and skeletons
  3. Compile the source files

Compile the remote object implementation

To create stub and skeleton files, the rmic compiler must be run on the fully-qualified package names of compiled class files that contain remote object implementations. In this example, the file that contains the remote object implementations is HelloImpl.java. In order to generate the stubs and skeletons, we must first compile HelloImpl.java, as follows:

    javac -d . -classpath . HelloImpl.java

The "-d ." option indicates that the generated files should be placed in the directory from which you are running the compiler. The "-classpath ." option indicates that files on which HelloImpl.java is dependent can be found in this directory.

Use rmic to generate skeletons and stubs

To create CORBA-compatible stub and skeleton files, run the rmic compiler with the -poa -iiop option. The rmic -poa -iiop command takes one or more class names as an argument and produces class files of the form _MyImpl_Tie.class and _MyInterface_Stub.class. The remote implementation file, HelloImpl.class, is the class name to pass in this example.

For an explanation of rmic options, refer to the Solaris Operating Environment rmic manual page or the Microsoft Windows rmic manual page.

To create the stub and skeleton for the HelloImpl remote object implementation, run rmic like this:

    rmic -poa -iiop HelloImpl

The preceding command creates the following files:

  • _HelloInterface_Stub.class - the client stub
  • _HelloImpl_Tie.class - the server skeleton

Compile the source files

To compile the source files, run the javac command as follows:

    javac -d . -classpath . HelloInterface.java HelloServer.java HelloClient.java

This command creates the class files HelloInterface.class, HelloServer.class, and HelloClient.class. These are the remote interface, the server, and the client application respectively. For an explanation of javac options, you can refer to the Solaris javac manual page or the Microsoft Windows javac manual page.

Start the Naming Service, server, and client application

The following tasks will be completed in this section:
  1. Start the Naming Service
  2. Start the server
  3. Run the client application

Start the Naming Service

For this example, we will use the Object Request Broker Daemon, orbd, which includes both a Transient and a Persistent Naming Service, and is available with every download of J2SE 1.4 and higher.

For a caller (client, peer, or client application) to be able to invoke a method on a remote object, that caller must first obtain a reference to the remote object.

Once a remote object is registered on the server, callers can look up the object by name, obtain a remote object reference, and then remotely invoke methods on the object.

To start the Naming Service, run orbd from the command line. This command produces no output and is typically run in the background. For more on the orbd tool, you can refer to the orbd manual page.

For this example, on the Solaris operating system:

    orbd -ORBInitialPort 1060&

or, on the Microsoft Windows operating system:

    start orbd -ORBInitialPort 1060

You must specify a port on which to run orbd. For this example the port of 1060 is chosen because in the Solaris operating environment, a user must become root to start a process on a port under 1024.

You must stop and restart the server any time you modify a remote interface or use modified/additional remote interfaces in a remote object implementation. Otherwise, the type of the object reference bound in the Naming Service will not match the modified class.

Start the server

Open another terminal window and change to the directory containing the source files for this example. The command for running the client has been spread out below to make it easier to read, but should be typed without returns between the lines. The following command shows how to start the HelloServer server. Of course, if you used a port other than 1060 or a host other than localhost when starting the orbd tool, replace those values in the command below with the actual values used to start orbd.

    java
      -classpath .
      -Djava.naming.factory.initial=com.sun.jndi.cosnaming.CNCtxFactory
      -Djava.naming.provider.url=iiop://localhost:1060
      HelloServer

For an explanation of java options, you can refer to the Solaris java manual page or the Microsoft Windows java manual page.

The output should look like this:

Hello Server: Ready ...

Run the client application

Once the Naming Service and server are running, the client application can be run. From a new terminal window, go to the source code directory, and run the client application from the command line, as shown below. The command for running the client has been spread out below to make it easier to read, but should be typed without returns between the lines. Of course, if you used a port other than 1060 or a host other than localhost when starting the orbd tool, replace those values in the command below with the actual values used to start orbd.
    java
      -classpath .
      -Djava.naming.factory.initial=com.sun.jndi.cosnaming.CNCtxFactory
      -Djava.naming.provider.url=iiop://localhost:1060
      HelloClient
After running the client application, you will see output similar to the following in your terminal window or command prompt window:
Client: Obtained a ref. to Hello server.

The server window will return the following message:

It works! Hello World!!

This completes the tutorial. If you are ready to move on to more complicated applications, here are some sources that may help:

  • http://forum.java.sun.com/forum.jsp?forum=59, The Sun Developer's Forum for RMI-IIOP. You must register with the Java Developer Connection to access this site.

  • EJB clients interact with the J2EE EJB tier using the RMI-IIOP protocol. For more information on using RMI-IIOP in this way, see the Java 2 Platform, Enterprise Edition Blueprints or the EJB Tutorials.

  • The Java IDL tutorial includes an example for running the client and server on different machines. The concepts of Running the Hello World Example on Two Machines apply to this example as well.
Copyright © 2001-2004 Sun Microsystems, Inc. All Rights Reserved. Sun


RMI-IIOP Programmer's Guide

 RMI-IIOP Documentation

This document discusses how to write Java Remote Method Invocation (RMI) programs that can access remote objects by using the Internet Inter-ORB Protocol (IIOP). By making your RMI programs conform to a small set of restrictions, your CORBA clients in any language can access RMI-IIOP servers. RMI-IIOP gives you RMI ease-of-use coupled with CORBA/IIOP language interoperability.

What is RMI-IIOP?

RMI

With RMI you can write distributed programs in the Java programming language. RMI is easy to use, you don't need to learn a separate interface definition language (IDL), and you get Java's inherent "write once, run anywhere" benefit. Clients, remote interfaces, and servers are written entirely in Java. RMI uses the Java Remote Method Protocol (JRMP) for remote Java object communication. To get a quick introduction to writing RMI programs, see the RMI Tutorial web page. That document describes writing a simple "Hello World" RMI program.

RMI lacks interoperability with other languages because it does not use CORBA-IIOP as the communication protocol.

IIOP, CORBA, and Java IDL

IIOP is CORBA's communication protocol using TCP/IP as the transport. It specifies a standard for client and server communication. CORBA is a standard distributed object architecture developed by the Object Management Group (OMG). Interfaces to remote objects are described in a platform-neutral interface definition language (IDL). Mappings from IDL to specific programming languages are implemented, binding the language to CORBA/IIOP.

The Java(TM) 2 Platform, Standard Edition (J2SE) CORBA/IIOP implementation is known as Java IDL. Along with the idlj compiler, Java IDL can be used to define, implement, and access CORBA objects from the Java programming language.

The Java IDL web page gives you a good, Java-centric view of CORBA/IIOP programming. To get a quick introduction to writing Java IDL programs, see the Getting Started: Hello World web page.

RMI-IIOP

Previously Java programmers had to choose between RMI and CORBA/IIOP (Java IDL) for distributed programming solutions. Now, by adhering to a few restrictions, RMI server objects can use the IIOP protocol and communicate with CORBA client objects written in any language. This solution is known as RMI-IIOP. RMI-IIOP combines RMI-style ease of use with CORBA cross-language interoperability.

Table of Contents

  • The rmic Compiler
  • The idlj Compiler
  • How to Make RMI Programs Use IIOP
  • Restrictions When Running RMI Programs Over IIOP
  • Other Things You Should Know

The rmic Compiler

The RMI-IIOP software comes with an rmic compiler that can generate IIOP stubs and ties, and emit IDL, in accordance with the Java Language to OMG IDL Language Mapping Specification, in accordance with the compliance statement.

Here are the primary rmic flags that support the CORBA/IIOP functionality:

-iiop -- Generates IIOP stubs/ties.
-iiop -poa -- Generates IIOP stubs/ties that work with a Portable Object Adapter (POA).
-idl -- Generates IDL.

The following options are used in conjunction with the -idl option.

-noValueMethods -- Stops generation of IDL for methods and constructors within IDL valuetypes.
-always -- Forces regeneration even when existing stubs/ties/idl are newer than the input class. Only valid when -iiop and/or -idl flags are present.
-idlModule <fromJavaPackage<.class>> <toIDLModule> -- Specifies IDLEntity package mapping. For example: -idlModule foo.bar my::real::idlmod
-idlFile <fromJavaPackage<.class>> <toIDLFile> -- Specifies IDLEntity file mapping. For example: -idlFile test.pkg.X TEST16.idl

For more detailed information on the rmic compiler, read the rmic documentation.

The -iiop Flag

Using rmic with the -iiop option generates IIOP stub and tie classes instead of Java Remote Method Protocol (JRMP) stub and skeleton classes. A stub class is a local proxy for a remote object. Stub classes are used by clients to send calls to a server. Each remote interface requires a stub class, which implements that remote interface. The client's reference to a remote object is actually a reference to a stub. Tie classes are used on the server side to process incoming calls, and dispatch the calls to the proper implementation class. Each implementation class requires a tie class.

Stub classes are also generated for abstract interfaces. An abstract interface is an interface that does not extend java.rmi.Remote, but whose methods all throw either java.rmi.RemoteException or a superclass of java.rmi.RemoteException. Interfaces that do not extend java.rmi.Remote and have no methods are also abstract interfaces.

QUESTION: I have a RMI-IIOP application which was running on J2SE 1.3. When I generate new stubs and skeletons using rmic -iiop -poa , it does not work. Why ?

ANSWER: There are 2 different ways to compile and run RMI-IIOP programs, which are listed below. We do not recommend that you combine these.

  1. The default RMI-IIOP behavior. An example of an application that uses the default RMI-IIOP behavior can be found at Tutorial: Getting Started Using RMI-IIOP.

  2. POA-based RMI-IIOP. An example of an application that uses the non-standard POA-based RMI-IIOP behavior can be found at Getting Started Using RMI-IIOP: Example Using POA-based server-side model.

The -iiop -poa Flag

New to this release of Java SE is the -iiop -poa option. Using the -iiop flag with the -poa option changes the inheritance from org.omg.CORBA_2_3.portable.ObjectImpl to org.omg.PortableServer.Servant. This type of mapping is nonstandard and is not specified by the Java Language to OMG IDL Language Mapping Specification.

The PortableServer module for the Portable Object Adapter (POA) defines the native Servant type. In the Java programming language, the Servant type is mapped to the Java org.omg.PortableServer.Servant class. It serves as the base class for all POA servant implementations and provides a number of methods that may be invoked by the application programmer, as well as methods which are invoked by the POA itself and may be overridden by the user to control aspects of servant behavior.

The -idl Flag

Using rmic with the -idl option generates OMG IDL for the classes specified and any classes referenced. You would want to use this option when you have a CORBA client in another language that wants to talk to an RMI-IIOP server.

Note: After the OMG IDL is generated using rmic -idl, use the generated IDL with an IDL-to-C++ or other language compiler, but not with the IDL-to-Java language compiler. "Round tripping" is not recommended and should not be necessary. The IDL generation facility is intended to be used with other languages such as C++. Java clients or servers can use the original RMI-IIOP types.

IDL provides a purely declarative, programming language independent means for specifying the API for an object. The IDL is used as a specification for methods and data that can be written in and invoked from any language that provides CORBA bindings. This includes Java and C++ among others. See the Java Language to IDL Mapping (OMG) document for a complete description.

Note: The generated IDL can only be compiled using an IDL compiler that supports the CORBA 2.3 extensions to IDL.

The -noValueMethods Flag

The -noValueMethods option, when used with -idl, ensures that methods and initializers are not included in valuetypes emitted during IDL Generation. These are optional for valuetypes and are otherwise omitted.

See the RMIC tool page (Solaris Version/Windows version) for a complete rmic description.

The idlj Compiler

The RMI-IIOP software includes an IDL-to-Java compiler. This compiler supports the CORBA Objects By Value feature, which is required for interoperation with RMI-IIOP. It is written in Java, and so can run on any platform. See the IDL-to-Java Compiler User's Guide for details of how to use this compiler.

How to Make RMI Programs Use IIOP

The following steps are a general guide to converting an RMI application to RMI-IIOP.
  1. If you are using the RMI registry for naming services, you need to switch to CosNaming. In the createORB() method, do not pass the org.omg.ORBClass property. Instead, use ORB.init( args, null ). You need to do the following:
    1. In both your client and server code, you need to create an InitialContext for JNDI using the following code:
      2.          import javax.naming.*;
         ...
         Context ic = new InitialContext();
    2. Modify all uses of RMI registry lookup() and bind() to use JNDI lookup() and bind()instead. For example, instead of your RMI server using:
      3.          import java.rmi.*;
         ...
         Naming.rebind("MyObject", myObj);
      use:
               import javax.naming.*;
         ...
         ic.rebind("MyObject", myObj);
    3. If the client is an applet, the client applet needs to pass this to the JNDI CosNaming plugin. Replace the above code with the following:
      4.         import java.util.*;
        import javax.naming.*;
        ...
        Hashtable env = new Hashtable();
        env.put("java.naming.applet", this);
        Context ic = new InitialContext(env);
  2. If you are not using the RMI registry for naming services, you have some other way of bootstrapping your initial remote object reference. For example, your server code may be using Java serialization to write an RMI object reference to an ObjectOutputStream and passing this to your client code for deserializing into an RMI stub.

    3. On the server side, use the PortableRemoteObject.toStub() call to obtain a stub, then use writeObject() to serialize this stub to an ObjectOutputStream. The code to do this looks something like:

    org.omg.CORBA.ORB myORB = org.omg.CORBA.ORB.init(new String[0], null);
Wombat myWombat = new WombatImpl();
javax.rmi.CORBA.Stub myStub = (javax.rmi.CORBA.Stub)PortableRemoteObject.toStub(myWombat);
myStub.connect(myORB);
// myWombat is now connected to myORB.  To connect other objects to the
// same ORB, use PortableRemoteObject.connect(nextWombat, myWombat);
FileOutputStream myFile = new FileOutputStream("t.tmp");
ObjectOutputStream myStream = new ObjectOutputStream(myFile);
myStream.writeObject(myStub);
    On the client side, use readObject() to deserialize a remote reference to the object from an ObjectInputStream, with code like:
    FileInputStream myFile = new FileInputStream("t.tmp");
ObjectInputStream myStream = new ObjectInputStream(myFile);
Wombat myWombat = (Wombat)myStream.readObject();
org.omg.CORBA.ORB myORB = org.omg.CORBA.ORB.init(new String[0], null);
((javax.rmi.CORBA.Stub)myWombat).connect(myORB);
// myWombat is now connected to myORB.  To connect other objects to the
// same ORB, use PortableRemoteObject.connect(nextWombat, myWombat);
  3. Either change your remote implementation classes to inherit from javax.rmi.PortableRemoteObject, or explicitly export implementation objects after creation by calling PortableRemoteObject.exportObject(). For more discussion on this topic, read Connecting IIOP stubs to the ORB.

  4. Change all the places in your code where there is a Java cast of a remote interface to use javax.rmi.PortableRemoteObject.narrow().

  5. Don't depend on Distributed Garbage Collection (DGC) or use any of the RMI DGC facilities. Use PortableRemoteObject.unexportObject() to unexport objects that are no longer in use.

  6. Regenerate the RMI stubs and ties using the rmic command with the -iiop option. This will produce stub and tie files with the following names:
    7.      _<implementionName>_Tie.class
     _<interfaceName>_Stub.class
  7. Before starting the server, start the CosNaming server (in its own process) using the following command:
         orbd -ORBInitialPort port#
    You must specify the port number when starting ORBD.

  8. When starting client and server applications, specify the following system properties:
    9.      java -Djava.naming.factory.initial=com.sun.jndi.cosnaming.CNCtxFactory
          -Djava.naming.provider.url=iiop://<hostname>:1050
           <appl_class>
    This example uses the name service port number of 1050. If you specified a different port in step 7, you need to use the same port number in the provider URL here. The <hostname> in the provider URL is the host name that was used to start the CosNaming server in step 7.

  9. If the client is an applet, specify the following properties in the applet tag:
    10.      java.naming.factory.initial=com.sun.jndi.cosnaming.CNCtxFactory
     java.naming.provider.url=iiop://<hostname>:1050
    This example uses the name service port number of 1050. If you specified a different port in step 7, you need to use the same port number in the provider URL here. The <hostname> in the provider URL is the host name that was used to start the CosNaming server in step 7.

For tutorials that describe creating a new RMI-IIOP application, link to Getting Started Using RMI-IIOP: Example Using POA-based server-side model or Tutorial: Getting Started Using RMI-IIOP.

Connecting IIOP stubs to the ORB

When your application uses IIOP stubs, as opposed to JRMP stubs, you need to properly connect the IIOP stubs with the ORB before invoking operations on the IIOP stubs (this is not necessary with JRMP stubs). This section discusses the extra 'connect' step required for the IIOP stub case.

The PortableRemoteObject.exportObject() call only creates a tie object and caches it for future usage. The created tie does not have a delegate or an ORB associated. This is known as explicit invocation.

The PortableRemoteObject.exportObject() happens automatically when the servant instance is created. This happens when a PortableRemoteObject constructor is called as a base class. This is known as implicit invocation.

Later, when PortableRemoteObject.toStub() is called by the application, it creates the corresponding Stub object and associates it with the cached Tie object. But since the Tie is not connected and does not have a delegate, the newly created stub also does not have a delegate or ORB.

The delegate is set for the stub only when the application calls Stub.connect(orb). Thus, any operations on the stub made before the ORB connection is made will fail.

The Java Language to IDL Mapping Specification says the following about the Stub.connect() method:

The connect method makes the stub ready for remote communication using the specified ORB object orb. Connection normally happens implicitly when the stub is received or sent as an argument on a remote method call, but it is sometimes useful to do this by making an explicit call (e.g., following deserialization). If the stub is already connected to orb (i.e., has a delegate set for orb), then connect takes no action. If the stub is connected to some other ORB, then a RemoteException is thrown. Otherwise, a delegate is created for this stub and the ORB object orb.

For servants that are not POA-activated, Stub.connect(orb) is necessary as a required setup.

Restrictions When Running RMI Programs Over IIOP

To make existing RMI programs run over IIOP, you need to observe the following restrictions.
  1. Make sure all constant definitions in remote interfaces are of primitive types or String and evaluated at compile time.
  2. Don't use Java names that conflict with IDL mangled names generated by the Java to IDL mapping rules. See section 28.3.2 of the Java Language to IDL Mapping specification for the Java to IDL name mapping rules.
  3. Don't inherit the same method name into a remote interface more than once from different base remote interfaces.
  4. Be careful when using names that differ only in case. The use of a type name and a variable of that type whose name differs from the type name only in case is supported. Most other combinations of names that differ only in case are not supported.
  5. Don't depend on runtime sharing of object references to be preserved exactly when transmitting object references across IIOP. Runtime sharing of other objects is preserved correctly.
  6. Don't use the following features of RMI:
    • RMISocketFactory
    • UnicastRemoteObject
    • Unreferenced
    • The Distributed Garbage Collection (DGC) interfaces

Other Things You Should Know

Servers Need to be Thread Safe

Since remote method invocation on the same remote object may execute concurrently, a remote object implementation needs to make sure its implementation is thread-safe.

Interoperating with Other ORBs

RMI-IIOP should interoperate with other ORBS that support the CORBA 2.3 specification. It will not interoperate with older ORBs, because these are unable to handle the IIOP encodings for Objects By Value. This support is needed to send RMI value classes (including strings) over IIOP.

NOTE: Although it is true that ORBs written in different languages should be able to talk to each other, we haven't tested the interoperability of the Java ORB with other vendor's ORBs.

When do I use UnicastRemoteObject vs PortableRemoteObject?

UnicastRemoteObject should be used as the superclass for the object implementation in RMI programming. PortableRemoteObject should be used in RMI-IIOP programming. If PortableRemoteObject is used, you can switch the transport protocol to either JRMP or IIOP during runtime.

Known Problems

  • JNDI 1.1 does not support java.naming.factory.initial=com.sun.jndi.cosnaming.CNCtxFactory as an Applet parameter. Instead, it must be explicitly passed as a property to the InitialContext constructor. This capability is supported in JNDI 1.2.

  • When running the Naming Service on Solaris, you must use a port number greater than 1024.

  • On Solaris, you may experience an "out of file descriptors" problem when running RMI-IIOP applications. This may occur if you are using too many file descriptors, which can happen because each JAR file in the classpath consumes one file descriptor and the JDK 1.1.6 setup adds numerous JAR files to the classpath. Before running applications, set the file descriptor limit to a number greater than its default value of 64. For example, set the ulimit number to 90 or higher, as follows:
    • ulimit -n 90

Background Reading

Here are some sites to get you up to speed with this technology:
  • The RMI-IIOP home page contains links to RMI-IIOP documentation, sample code, specifications, news, other related web sites, and more. Check it out!
  • The RMI-IIOP Tutorial gives a step-by-step example for creating and running a simple RMI-IIOP application.
  • The Java RMI home page contains links to RMI documentation, examples, specification, and more. Make sure you read this.
  • The RMI trail in the Java Tutorial.
  • The RMI API documentation.
  • The Java IDL web page will familiarize you with Sun's CORBA/IIOP implementation.
  • The Java IDL Tutorial is the newest version of the IDL trail from the Java Tutorial.
  • The Java Language to IDL Mapping, ptc/00-01-06 document is a detailed technical specification of RMI-IIOP. For further information on how the specification is implemented in this version of Java SE, see the compliance document.

RMI-IIOP Home


When should I use RMI-IIOP?

RMI-IIOP is for developers who program in the Java programming language and want to program to the RMI interfaces, but use IIOP as the underlying transport. RMI-IIOP provides interoperability with other CORBA objects implemented in various languages - but only if all the remote interfaces are originally defined as Java RMI interfaces. It is of particular interest to programmers using Enterprise JavaBeansTM (EJBTM), since the remote object model for EJB components is based on the RMI API.

RMI-IIOP combines the best features of Java Remote Method Invocation (RMI) with the best features of CORBA. RMI-IIOP speeds distributed application development by allowing developers to work completely in the Java programming language, writing remote interfaces in the Java programming language and implementing them simply using Java technology and the Java RMI APIs.

When using RMI-IIOP to produce technology-based distributed applications written in the Java programming language, there is no separate Interface Definition Language (IDL) or mapping to learn: the remote interfaces can be implemented in any other language that is supported by an OMG mapping and a vendor supplied ORB for that language. Similarly, clients can be written in other languages using IDL derived from the remote Java technology-based interfaces.

RMI-IIOP provides flexibility by allowing developers to pass any Java object between application components either by reference or by value.

Like CORBA, RMI-IIOP is based on open standards defined with the participation of hundreds of vendors and users in the Object Management Group. Like CORBA, RMI-IIOP uses Internet Inter-ORB Protocol (IIOP) as its communication protocol. IIOP eases legacy application and platform integration by allowing application components written in C++, Smalltalk, and other CORBA supported languages to communicate with components running on the Java platform.

What other options do I have for distributed application development?

Developers who program using the JavaTM programming language can choose several solutions for creating distributed applications programs.

  • JavaTM RMI technology - If all of your applications are written in the Java programming language, you will probably want to use Java RMI technology to enable communication between Java objects on different virtual machines and different physical machines. Using Java RMI technology without its IIOP option leverages its strengths of code portability, security, and garbage collection.

  • JavaTM IDL technology - Java IDL technology are for CORBA programmers who want to program in the Java programming language based on interfaces defined in CORBA Interface Definition Language (IDL). This is "business as usual" CORBA programming, supporting the Java platform in exactly the same way as other languages like C++ or COBOL.

  • Enterprise JavaBeansTM technology - Enterprise JavaBeansTM (EJBTM) technology is part of the Java 2 Platform, Enterprise Edition. EJB components use the Java RMI/Java IDL technology for their distributed object model, and use the Java Transaction Service (JTS) for their distributed transaction model. When Enterprise JavaBeans components are implemented using the RMI-IIOP protocol for EJB component interoperability in heterogeneous server environments, the standard mapping of the EJB architecture to CORBA enables interoperability with multivendor ORBs, other EJB servers, and CORBA clients written in programming languages other than the Java programming language. For an example application that uses an EJB server with a CORBA client, look at Enterprise JavaBeans Components and CORBA Clients.
Copyright © 2001-2004 Sun Microsystems, Inc. All Rights Reserved.

Sun


Scripting for the Java Platform

Java

Scripting for the JavaTM Platform

 Documentation Contents

Many implementations of scripting and dynamically typed languages generate Java bytecodes so that programs can be run on the Java Platform, just as are actual Java programs. Implementing a language in this way (or as a Java interpreter class for the scripting language) provides all the advantages of the Java platform - scripting implementations can take advantage of the Java platform's binary portability, security, and high performance bytecode execution.

Java SE 6 includes JSR 223: Scripting for the JavaTM Platform API. This is a framework by which Java Applications can "host" script engines. Sun's implementation of Java SE 6 includes an example script engine based on Mozilla Rhino:JavaScript for Java. The scripting framework supports third-party script engines through jar "service discovery" mechanism. It is possible to "drop" any JSR-223 compliant script engine in the CLASSPATH and access the same from your Java applications (much like JDBC drivers, JNDI implementations are accessed).

API Reference

  • javax.script Package

Programmer's Guides

  • Java Scripting Programmer's Guide - A conceptual description of the Java Scripting API, with code examples.

Tool Reference

  • jrunscript - scripting language independent command line shell

More Information

  • JSR-223 Scripting for the Java Platform
  • Mozilla Rhino:Java Script for Java

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun
Java Software


Java Scripting Programmer's Guide

Java

Java Scripting Programmer's Guide

 Documentation Contents

  • Who is the Java Scripting API For?
  • Scripting Package
  • Examples
    • "Hello, World"
    • Evaluating a Script File
    • Script Variables
    • Invoking Script Functions and Methods
    • Implementing Java Interfaces by Scripts
    • Multiple Scopes for Scripts
  • JavaScript Script Engine
  • JavaScript to Java Communication
    • Importing Java Packages, Classes
    • Creating and Using Java Arrays
    • Implementing Java Interfaces
    • Overload Resolution
  • Implementing Your Own Script Engine
  • References

Who is the Java Scripting API For?

Some useful characteristics of scripting languages are:
  • Convenience: Most scripting languages are dynamically typed. You can usually create new variables without declaring the variable type, and you can reuse variables to store objects of different types. Also, scripting languages tend to perform many type conversions automatically, for example, converting the number 10 to the text "10" as necessary.
  • Developing rapid prototypes: You can avoid the edit-compile-run cycle and just use edit-run!
  • Application extension/customization: You can "externalize" parts of your application - like configuration scripts, business logic/rules and math expressions for financial applications.
  • "Command line" shells for applications -for debugging, runtime/deploy time configuration etc. Most applications have a web-based GUI configuaration tool these days. But sysadmins/deployers frequently prefer command line tools. Instead of inventing ad-hoc scripting language for that purpose, a "standard" scripting language can be used.

The JavaTM Scripting API is a scripting language indepedent framework for using script engines from Java code. With the Java Scripting API, it is possible to write customizable/extendable applications in the Java language and leave the customization scripting language choice to the end user. The Java application developer need not choose the extension language during development. If you write your application with JSR-223 API, then your users can use any JSR-223 compliant scripting language.

top

Scripting Package

The Java Scripting functionality is in the javax.script package. This is a relatively small, simple API. The starting point of the scripting API is the ScriptEngineManager class. A ScriptEngineManager object can discover script engines through the jar file service discovery mechanism. It can also instantiate ScriptEngine objects that interpret scripts written in a specific scripting language. The simplest way to use the scripting API is as follows:

  1. Create a ScriptEngineManager object.
  2. Get a ScriptEngine object from the manager.
  3. Evaluate script using the ScriptEngine's eval methods.

Now, it is time to look at some sample code. While it is not mandatory, it may be useful to know a bit of JavaScript to read these examples.

top

Examples

"Hello, World"

From the ScriptEngineManager instance, we request a JavaScript engine instance using getEngineByName method. On the script engine, the eval method is called to execute a given String as JavaScript code! For brevity, in this as well as in subsequent examples, we have not shown exception handling. There are checked and runtime exceptions thrown from javax.script API. Needless to say, you have to handle the exceptions appropriately.

import javax.script.*;
public class EvalScript {
    public static void main(String[] args) throws Exception {
        // create a script engine manager
        ScriptEngineManager factory = new ScriptEngineManager();
        // create a JavaScript engine
        ScriptEngine engine = factory.getEngineByName("JavaScript");
        // evaluate JavaScript code from String
        engine.eval("print('Hello, World')");
    }
}
top

Evaluating a Script File

In this example, we call the eval method that accepts java.io.Reader for the input source. The script read by the given reader is executed. This way it is possible to execute scripts from files, URLs and resources by wrapping the relevant input stream objects as readers.

import javax.script.*;
public class EvalFile {
    public static void main(String[] args) throws Exception {
        // create a script engine manager
        ScriptEngineManager factory = new ScriptEngineManager();
        // create JavaScript engine
        ScriptEngine engine = factory.getEngineByName("JavaScript");
        // evaluate JavaScript code from given file - specified by first argument
        engine.eval(new java.io.FileReader(args[0]));
    }
}
Let us assume that we have the file named "test.js" with the following text:

println("This is hello from test.js");
We can run the above Java as

java EvalFile test.js
top

Script Variables

When you embed script engines and scripts with your Java application, you may want to expose your application objects as global variables to scripts. This example demonstrates how you can expose your application objects as global variables to a script. We create a java.io.File in the application and expose the same as a global variable with the name "file". The script can access the variable - for example, it can call public methods on it. Note that the syntax to access Java objects, methods and fields is dependent on the scripting language. JavaScript supports the most "natural" Java-like syntax.

public class ScriptVars {
    public static void main(String[] args) throws Exception {
        ScriptEngineManager manager = new ScriptEngineManager();
        ScriptEngine engine = manager.getEngineByName("JavaScript");

        File f = new File("test.txt");
        // expose File object as variable to script
        engine.put("file", f);

        // evaluate a script string. The script accesses "file"
        // variable and calls method on it
        engine.eval("print(file.getAbsolutePath())");
    }
}
top

Invoking Script Functions and Methods

Sometimes you may want to call a specific scripting function repeatedly - for example, your application menu functionality might be implemented by a script. In your menu's action event handler you may want to call a specific script function. The following example demonstrates invoking a specific script function from Java code.

import javax.script.*;

public class InvokeScriptFunction {
    public static void main(String[] args) throws Exception {
        ScriptEngineManager manager = new ScriptEngineManager();
        ScriptEngine engine = manager.getEngineByName("JavaScript");

        // JavaScript code in a String
        String script = "function hello(name) { print('Hello, ' + name); }";
        // evaluate script
        engine.eval(script);

        // javax.script.Invocable is an optional interface.
        // Check whether your script engine implements or not!
        // Note that the JavaScript engine implements Invocable interface.
        Invocable inv = (Invocable) engine;

        // invoke the global function named "hello"
        inv.invokeFunction("hello", "Scripting!!" );
    }
}

If your scripting language is object based (like JavaScript) or object-oriented, then you can invoke a script method on a script object.

import javax.script.*;

public class InvokeScriptMethod {
    public static void main(String[] args) throws Exception {
        ScriptEngineManager manager = new ScriptEngineManager();
        ScriptEngine engine = manager.getEngineByName("JavaScript");

        // JavaScript code in a String. This code defines a script object 'obj'
        // with one method called 'hello'.
        String script = "var obj = new Object(); obj.hello = function(name) { print('Hello, ' + name); }";
        // evaluate script
        engine.eval(script);

        // javax.script.Invocable is an optional interface.
        // Check whether your script engine implements or not!
        // Note that the JavaScript engine implements Invocable interface.
        Invocable inv = (Invocable) engine;

        // get script object on which we want to call the method
        Object obj = engine.get("obj");

        // invoke the method named "hello" on the script object "obj"
        inv.invokeMethod(obj, "hello", "Script Method !!" );
    }
}
top

Implementing Java Interfaces by Scripts

Instead of calling specific script functions from Java, sometimes it is convenient to implement a Java interface by script functions or methods. Also, by using interfaces we can avoid having to use the javax.script API in many places. We can get an interface implementor object and pass it to various Java APIs. The following example demonstrates implementing the java.lang.Runnable interface with a script.

import javax.script.*;

public class RunnableImpl {
    public static void main(String[] args) throws Exception {
        ScriptEngineManager manager = new ScriptEngineManager();
        ScriptEngine engine = manager.getEngineByName("JavaScript");

        // JavaScript code in a String
        String script = "function run() { println('run called'); }";

        // evaluate script
        engine.eval(script);

        Invocable inv = (Invocable) engine;

        // get Runnable interface object from engine. This interface methods
        // are implemented by script functions with the matching name.
        Runnable r = inv.getInterface(Runnable.class);

        // start a new thread that runs the script implemented
        // runnable interface
        Thread th = new Thread(r);
        th.start();
    }
}

If your scripting language is object-based or object-oriented, it is possible to implement a Java interface by script methods on script objects. This avoids having to call script global functions for interface methods. The script object can store the "state" associated with the interface implementor.

import javax.script.*;

public class RunnableImplObject {
    public static void main(String[] args) throws Exception {
        ScriptEngineManager manager = new ScriptEngineManager();
        ScriptEngine engine = manager.getEngineByName("JavaScript");

        // JavaScript code in a String
        String script = "var obj = new Object(); obj.run = function() { println('run method called'); }";

        // evaluate script
        engine.eval(script);

        // get script object on which we want to implement the interface with
        Object obj = engine.get("obj");

        Invocable inv = (Invocable) engine;

        // get Runnable interface object from engine. This interface methods
        // are implemented by script methods of object 'obj'
        Runnable r = inv.getInterface(obj, Runnable.class);

        // start a new thread that runs the script implemented
        // runnable interface
        Thread th = new Thread(r);
        th.start();
    }
}
top

Multiple Scopes for Scripts

In the script variables example, we saw how to expose application objects as script global variables. It is possible to expose multiple global "scopes" for scripts. A single scope is an instance of javax.script.Bindings. This interface is derived from java.util.Map<String, Object>. A scope a set of name-value pairs where name is any non-empty, non-null String. Multiple scopes are supported by javax.script.ScriptContext interface. A script context supports one or more scopes with associated Bindings for each scope. By default, every script engine has a default script context. The default script context has atleast one scope called "ENGINE_SCOPE". Various scopes supported by a script context are available through getScopes method.

import javax.script.*;

public class MultiScopes {
    public static void main(String[] args) throws Exception {
        ScriptEngineManager manager = new ScriptEngineManager();
        ScriptEngine engine = manager.getEngineByName("JavaScript");

        engine.put("x", "hello");
        // print global variable "x"
        engine.eval("println(x);");
        // the above line prints "hello"

        // Now, pass a different script context
        ScriptContext newContext = new SimpleScriptContext();
        Bindings engineScope = newContext.getBindings(ScriptContext.ENGINE_SCOPE);

        // add new variable "x" to the new engineScope
        engineScope.put("x", "world");

        // execute the same script - but this time pass a different script context
        engine.eval("println(x);", newContext);
        // the above line prints "world"
    }
}
top

JavaScript Script Engine

Sun's implementation of JDK 6 is co-bundled with the Mozilla Rhino based JavaScript script engine. This is based on Mozilla Rhino version 1.6R2. Most of the Rhino implementation is included. A few components have been excluded due to footprint and security reasons:

  1. JavaScript-to-bytecode compilation (also called "optimizer"). This feature depends on a class generation library. The removal of this feature means that JavaScript will always be interpreted. The removal of this feature does not affect script execution because the optimizer is transparent.
  2. Rhino's JavaAdapter has been removed. JavaAdapter is the feature by which a Java class can be extended by JavaScript and Java interfaces may be implemented by JavaScript. This feature also requires a class generation library. We have replaced Rhino's JavaAdapter with Sun's implementation of the JavaAdapter. In Sun implementation, only a single Java interface may be implemented by a JavaScript object. For example, the following works as expected.

       var v = new java.lang.Runnable() {
                    run: function() { print('hello'); }
               }
       v.run();
    In most cases, JavaAdapter is used to implement aa single interface with Java anonymizer class-like syntax. The uses of JavaAdapter to extend a Java class or to implement multiple interfaces are very rare.
  3. E4X (ECMAScript for XML - ECMA Standard 357) has been excluded. Use of an XML literal in JavaScript code will result in a syntax error. Note that E4X support is optional in the ECMAScript standard - a implementation can omit E4X support and still be a compliant ECMAScript implementation.
  4. The Rhino command line tools (Rhino shell, debugger etc.) are not included. But, you can use jrunscript instead.
top

JavaScript to Java Communication

For the most part, accessing Java classes, objects and methods is straightforward. In particular field and method access from JavaScript is the same as it is from Java. We highlight important aspects of JavaScript Java access here. For more details, please refer to http://www.mozilla.org/rhino/scriptjava.html. The following examples are JavaScript snippets accessing Java. This section requires knowledge of JavaScript. This section can be skipped if you are planning to use some other JSR-223 scripting language rather than JavaScript.

top

Importing Java Packages, Classes

The built-in functions importPackage and importClass can be used to import Java packages and classes.

// Import Java packages and classes
// like import package.*; in Java
importPackage(java.awt);
// like import java.awt.Frame in Java
importClass(java.awt.Frame);
// Create Java Objects by "new ClassName"
var frame = new java.awt.Frame("hello");
// Call Java public methods from script
frame.setVisible(true);
// Access "JavaBean" properties like "fields"
print(frame.title);

The Packages global variable can be used to access Java packages. Examples: Packages.java.util.Vector, Packages.javax.swing.JFrame. Please note that "java" is a shortcut for "Packages.java". There are equivalent shortcuts for javax, org, edu, com, net prefixes, so pratically all JDK platform classes can be accessed without the "Packages" prefix.

Note that java.lang is not imported by default (unlike Java) because that would result in conflicts with JavaScript's built-in Object, Boolean, Math and so on.

importPackage and importClass functions "pollute" the global variable scope of JavaScript. To avoid that, you may use JavaImporter.

// create JavaImporter with specific packages and classes to import

var SwingGui = new JavaImporter(javax.swing,
                            javax.swing.event,
                            javax.swing.border,
                            java.awt.event);
with (SwingGui) {
    // within this 'with' statement, we can access Swing and AWT
    // classes by unqualified (simple) names.

    var mybutton = new JButton("test");
    var myframe = new JFrame("test");
}
top

Creating and Using Java Arrays

While creating a Java object is the same as in Java, to create Java arrays in JavaScript we need to use Java reflection explicitly. But once created the element access or length access is the same as in Java. Also, a script array can be used when a Java method expects a Java array (auto conversion). So in most cases we don't have to create Java arrays explicitly.

// create Java String array of 5 elements
var a = java.lang.reflect.Array.newInstance(java.lang.String, 5);

// Accessing elements and length access is by usual Java syntax
a[0] = "scripting is great!";
print(a.length);
top

Implementing Java Interfaces

A Java interface can be implemented in JavaScript by using a Java anonymous class-like syntax:

var r  = new java.lang.Runnable() {
    run: function() {
        print("running...\n");
    }
};

// "r" can be passed to Java methods that expect java.lang.Runnable
var th = new java.lang.Thread(r);
th.start();

When an interface with a single method is expected, you can pass a script function directly.(auto conversion)

function func() {
     print("I am func!");
}

// pass script function for java.lang.Runnable argument
var th = new java.lang.Thread(func);
th.start();
top

Overload Resolution

Java methods can be overloaded by argument types. In Java, overload resolution occurs at compile time (performed by javac). When calling Java methods from a script, the script interpreter/compiler needs to select the appropriate method. With the JavaScript engine, you do not need to do anything special - the correct Java method overload variant is selected based on the argument types. But, sometimes you may want (or have) to explicitly select a particular overload variant.

var out = java.lang.System.out;

// select a particular println function
out["println(java.lang.Object)"]("hello");

More details on JavaScript's Java method overload resolution is at http://www.mozilla.org/js/liveconnect/lc3_method_overloading.html

top

Implementing Your Own Script Engine

We will not cover implementation of JSR-223 compliant script engines in detail. Minimally, you need to implement the javax.script.ScriptEngine and javax.script.ScriptEngineFactory interfaces. The abstract class javax.script.AbstractScriptEngine provides useful defaults for a few methods of the ScriptEngine interface.

Before starting to implement a JSR-223 engine, you may want to check http://scripting.dev.java.net project. This project maintains JSR-223 implementations for many popular open source scripting languages.

top

References

  • JSR-223 Scripting for the Java Platform
  • JavaScript Developer Connection
  • Java Method Overloading and LiveConnect 3
  • Rhino:JavaScript for Java
  • Scripting Java (from JavaScript)
  • scripting.dev.java.net project
top

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

Feedback 		Sun


Access Control Lists

Access Control Abstractions

Last Modified: 30 April 2001

java.security.acl

Introduction

An Access Control List (ACL) is a data structure that guards access to resources. The java.security.acl package provides the interface to such a data structure and the sun.security.acl package provides a default implementation of the interfaces specified in the java.security.acl package.

Note: This API is not used internally for JDK system security. It was introduced in JDK 1.1, and remains for backwards compatibility. It may undergo substantial revision and extension or even replacement in future releases. This document describes the current interfaces.

An ACL can be thought of as a data structure with multiple ACL entries. Each ACL entry, of interface type AclEntry, contains a set of permissions associated with a particular principal. (A principal represents an entity such as an individual user or a group). Additionally, each ACL entry is specified as being either positive or negative. If positive, the permissions are to be granted to the associated principal. If negative, the permissions are to be denied.

An access control list is independent of the authentication scheme used to verify the validity of the principal. It is also independent of the encryption scheme used to transmit the data across the network. The ACL is consulted after the authentication phase. After the principal is verified to be an authenticated user in the system, the principal might access resources. For each such resource, the principal might or might not be granted access depending on the permissions that are granted to the principal in the ACL that guards the resource. The ACL itself is independent of the resource that it guards. The ACL can be consulted to find the list of permissions a particular principal has or to find out whether or not a principal is granted a particular permission.

ACL structure

An ACL is an object that implements the java.security.acl.Acl interface. Each Acl is a list of AclEntry objects. Each AclEntry associates a Principal or a Group object to a list of Permission objects. (Note: Group is a subclass of Principal.) Each AclEntry can also be designated as a positive entry or a negative entry. A positive entry grants the list of permissions in the entry to the principal or group and a negative entry denies the list of permissions to the principal or group.

Calculation of granted permissions

When calculating the net permissions a principal is granted, the following rules are used.

  1. Each principal or group can have at most one positive ACL entry and one negative entry; that is, multiple positive or negative ACL entries are not allowed for any principal or group.
  2. If there is no entry for a particular principal or a group, then the principal or the group has the null permission set.
  3. The net group positive permission set for a principal is the union of all the positive permissions of each group that the principal belongs to.
  4. The net group negative permission set for a principal is the union of all the negative permissions of each group that the principal belongs to.
  5. If there is a positive entry that grants a principal or a group a particular permission and a negative entry that denies the principal or group the same permission, then that permission is removed from both the positive permissions set and the negative permissions set.
  6. Individual permissions (permissions granted or denied to a specific principal) always override the Group permissions. Specifically, individual negative permissions (specific denial of permissions) override the group's positive permissions. And individual positive permissions override the group's negative permissions.
  7. Assume that the positive permission set of all the groups that the principal belongs to is g1 and the negative permission set of all the groups that the principal belongs to is g2. Also assume that the individual positive permission set for the principal is p1 and the individual negative permission set for the principal is p2. Then the resulting permissions that the principal is granted are (p1 + (g1 - p2)) - (p2 + (g2 - p1)).

Example permission calculations

Assume that a principal P belongs to groups G1 and G2. The table below shows 5 columns using some examples of permissions given to G1, G2 and P. The resulting permissions granted to P are shown in the last column.

 | Group G1 Permissions | Group G2 Permissions | Union (G1, G2) perms | Individual Permissions | Resulting Permissions
Positive | A | B | A+B | C | A+B+C
Negative | null set | null set | null set | null set
Positive | A | B | B | C | B+C
Negative | -C | -A | -C | null set
Positive | A | B | A+B | C | B+C
Negative | null set | null set | null set | -A
Positive | A | C | A | B | B
Negative | -C | -B | -B | -A

Example usage

/* Note: This sample program is meant just as an example
 * of the types of things that can be done with an
 * implementation of the java.security.acl interfaces.
 * This example uses the implementation supplied by the
 * sun.security.acl package. Please note that sun.* classes
 * are unsupported and subject to change.
*/

import java.security.Principal;
import java.security.acl.*;
import sun.security.acl.*;
import java.util.Enumeration;

public class AclEx {

  public static void main(String argv[])
    throws Exception
  {

    Principal p1 = new PrincipalImpl("user1");
    Principal p2 = new PrincipalImpl("user2");
    Principal owner = new PrincipalImpl("owner");

    Permission read = new PermissionImpl("READ");
    Permission write = new PermissionImpl("WRITE");

    System.out.println("Creating a new group with two members: user1 and
user2");
    Group g = new GroupImpl("group1");
    g.addMember(p1);
    g.addMember(p2);

    //
    // create a new acl with the name "exampleAcl"
    //
    System.out.println("Creating a new Acl named 'exampleAcl'");
    Acl acl = new AclImpl(owner, "exampleAcl");

    //
    // Allow group all permissions
    //
    System.out.println("Creating a new Acl Entry in exampleAcl for the
group, ");
    System.out.println("  with read & write permissions");
    AclEntry entry1 = new AclEntryImpl(g);
    entry1.addPermission(read);
    entry1.addPermission(write);
    acl.addEntry(owner, entry1);

    //
    // Take away WRITE permissions for
    // user1. All others in groups still have
    // WRITE privileges.
    //
    System.out.println("Creating a new Acl Entry in exampleAcl for user1");
    System.out.println("  without write permission");
    AclEntry entry2 = new AclEntryImpl(p1);
    entry2.addPermission(write);
    entry2.setNegativePermissions();
    acl.addEntry(owner, entry2);

    //
    // This enumeration is an enumeration of
    // Permission interfaces. It should return
    // only "READ" permission.
    Enumeration e1 = acl.getPermissions(p1);
    System.out.println("Permissions for user1 are:");
    while (e1.hasMoreElements()) {
    System.out.println("  " + e1.nextElement());
    };

    //
    // This enumeration should have "READ" and"WRITE"
    // permissions.
    Enumeration e2 = acl.getPermissions(p2);
    System.out.println("Permissions for user2 are:");
    while (e2.hasMoreElements()) {
    System.out.println("  " + e2.nextElement());
    };

    // This should return false.
    boolean b1 = acl.checkPermission(p1, write);
    System.out.println("user1 has write permission: " + b1);

    // This should all return true;
    boolean b2 = acl.checkPermission(p1, read);
    boolean b3 = acl.checkPermission(p2, read);
    boolean b4 = acl.checkPermission(p2, write);
    System.out.println("user1 has read permission: " + b2);
    System.out.println("user2 has read permission: " + b3);
    System.out.println("user2 has write permission: " + b4);
  }
}

Sun logo Copyright © 1996-2001 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA 94043-1100 USA. All rights reserved.

Please send comments to: java-security@sun.com


Default Policy Implementation and Policy File Syntax

Document revision 1.6

The policy for a JavaTM programming language application environment (specifying which permissions are available for code from various sources, and executing as various principals) is represented by a Policy object. More specifically, it is represented by a Policy subclass providing an implementation of the abstract methods in the Policy class (which is in the java.security package).

The source location for the policy information utilized by the Policy object is up to the Policy implementation. The Policy reference implementation obtains its information from static policy configuration files.

The rest of this document pertains to the Policy reference implementation and the syntax that must be used in policy files it reads. For information about using the Policy Tool to create a policy file (without needing to know the required syntax), see the Policy Tool documentation (for Solaris) (for Win32).

Here is an outline for the rest of this document:

Policy Changes in the JavaTM 2 SDK, Standard Edition, v 1.4
Default Policy Implementation
Default Policy File Locations
Changing the Policy Implementation
Policy File Syntax
Policy File Examples
Property Expansion in Policy Files
General Expansion in Policy Files
Related Documentation

Policy Changes in the JavaTM 2 SDK, Standard Edition, v 1.4

With the integration of JavaTM Authentication and Authorization Service (JAAS) into the J2SDK 1.4, the java.security.Policy API handles Principal-based queries, and the default policy implementation supports Principal-based grant entries. Thus, access control can now be based not just on what code is running, but also on who is running it. See other sections of this document for further information on principal-based grant entries.

Note: Starting with this version (v 1.4), policy files used by the default policy implementation must be encoded in the UTF-8 encoding scheme. You can use the native2ascii tool to assist with this conversion.
The rest of this section is relevant only for programmers who utilize the Policy API. If you're not such a progammer, you can skip to the next sections, Default Policy Implementation and Default Policy File Locations.

Policy-related API changes made in the J2SDK 1.4 include the following:

  • java.security.ProtectionDomain
    A new constructor, ProtectionDomain(CodeSource cs, PermissionCollection perms, ClassLoader loader, Principal[] principals), was added. This new constructor creates a new ProtectionDomain qualified by the given CodeSource, Permissions, ClassLoader, and Principals.
  • java.security.Policy
    Two new methods were added:
    1. getPermissions(ProtectionDomain domain) evaluates the system policy and returns a PermissionCollection object specifying the set of permissions allowed given the characteristics of the ProtectionDomain.
    2. implies(ProtectionDomain domain, Permission permission) evaluates the system policy for the permissions granted to the ProtectionDomain and tests whether the permission is granted.

Default Policy Implementation

In the Policy reference implementation, the policy can be specified within one or more policy configuration files. The configuration file(s) specify what permissions are allowed for code from a specified code source, and executed by a specified principal. Each configuration file must be encoded in UTF-8.

A policy file can be composed via a simple text editor, or via the graphical Policy Tool utility.

There is by default a single system-wide policy file, and a single (optional) user policy file.

The Policy reference implementation is initialized the first time its getPermissions method is called, or whenever its refresh method is called. Initialization involves parsing the policy configuration file(s) (see Policy File Syntax), and then populating the Policy object.

Default Policy File Locations

As mentioned previously, there is by default a single system-wide policy file, and a single user policy file.

The system policy file is by default located at

java.home/lib/security/java.policy  (Solaris)
java.home\lib\security\java.policy  (Win32)

Note: java.home refers to the value of the system property named "java.home", which specifies the directory that houses the runtime environment -- either the jre directory in the Java 2 SDK or the top-level directory of the Java 2 Runtime Environment.

The system policy file is meant to grant system-wide code permissions. The java.policy file installed with the SDK grants all permissions to standard extensions, allows anyone to listen on un-privileged ports, and allows any code to read certain "standard" properties that are not security-sensitive, such as the "os.name" and "file.separator" properties.

The user policy file is by default located at

user.home/.java.policy  (Solaris)
user.home\.java.policy  (Win32)

Note: user.home refers to the value of the system property named "user.home", which specifies the user's home directory. On Win32 systems, given user name uName, the "user.home" property value defaults to

C:\Winnt\Profiles\uName on multi-user Windows NT systems
C:\Windows\Profiles\uName on multi-user Windows 95 systems
C:\Windows on single-user Windows 95 systems

When the Policy is initialized, the system policy is loaded in first, and then the user policy is added to it. If neither policy is present, a built-in policy is used. This built-in policy is the same as the java.policy file installed with the JRE.

Policy file locations are specified in the security properties file, which is located at

java.home/lib/security/java.security  (Solaris)
java.home\lib\security\java.security  (Win32)
As noted above, java.home indicates the directory that houses the runtime environment--either the jre directory in the Java 2 SDK or the top-level directory of the Java 2 Runtime Environment. The policy file locations are specified as the values of properties whose names are of the form
policy.url.n
where n is a number. You specify each such property value in a line of the following form:
policy.url.n=URL
Here, URL is a URL specification.

For example, the default system and user policy files are defined in the security properties file as

policy.url.1=file:${java.home}/lib/security/java.policy
policy.url.2=file:${user.home}/.java.policy

(See Property Expansion for information about specifying property values via a special syntax, such as specifying the java.home property value via ${java.home}.)

You can actually specify a number of URLs (including ones of the form "http://"), and all the designated policy files will get loaded. You can also comment out or change the second one to disable reading the default user policy file.

The algorithm starts at policy.url.1, and keeps incrementing until it does not find a URL. Thus if you have policy.url.1 and policy.url.3, policy.url.3 will never be read.

Specifying an Additional Policy File at Runtime

It is also possible to specify an additional or a different policy file when invoking execution of an application. This can be done via the "-Djava.security.policy" command line argument, which sets the value of the java.security.policy property. For example, if you use

    java -Djava.security.manager -Djava.security.policy=someURL SomeApp
where someURL is a URL specifying the location of a policy file, then the specified policy file will be loaded in addition to all the policy files that are specified in the security properties file.

Notes:

  • The URL can be any regular URL or simply the name of a policy file in the current directory, as in
        java -Djava.security.manager -Djava.security.policy=mypolicy WriteFile

  • The "-Djava.security.manager" argument ensures that the default security manager is installed, and thus the application is subject to policy checks. It is not required if the application SomeApp installs a security manager.

If you use

    java -Djava.security.manager -Djava.security.policy==someURL SomeApp
(note the double equals) then just the specified policy file will be used; all the ones indicated in the security properties file will be ignored.

If you want to pass a policy file to the appletviewer, then use a "-J-Djava.security.policy" argument as follows:

    appletviewer -J-Djava.security.policy=someURL myApplet
Note:: The "-Djava.security.policy" policy file value will be ignored (for both java and appletviewer commands) if the "policy.allowSystemProperty" property in the security properties file is set to false. The default is true.

Changing the Policy Implementation

An alternative policy class can be given to replace the Policy reference implementation class, as long as the former is a subclass of the abstract Policy class and implements the getPermissions method (and other methods as necessary).

The Policy reference implementation can be changed by editing the security properties file, which is the java.security file in the lib/security directory of the SDK.

One of the types of properties you can set in java.security is of the following form:

    policy.provider=PolicyClassName

PolicyClassName must specify the fully qualified name of the desired Policy implementation class. The default security properties file entry for this property is the following:

    policy.provider=sun.security.provider.PolicyFile

To customize, you can change the property value to specify another class, as in

   policy.provider=com.mycom.MyPolicy

Policy File Syntax

The policy configuration file(s) for an SDK installation specify what permissions (which types of system resource accesses) are allowed to code from a specified code source, and executed as a specified principal.

For an applet (or an application running under a security manager) to be allowed to perform secured actions (such as reading or writing a file), the applet (or application) must be granted permission for that particular action. In the Policy reference implementation, that permission must be granted by a grant entry in a policy configuration file. See below and the "Java Security Architecture Specification" for more information. (The only exception is that code always automatically has permission to read files from its same (URL) location, and subdirectories of that location; it does not need explicit permission to do so.)

A policy configuration file essentially contains a list of entries. It may contain a "keystore" entry, and contains zero or more "grant" entries.

Keystore Entry

A keystore is a database of private keys and their associated digital certificates such as X.509 certificate chains authenticating the corresponding public keys. The keytool utility (for Solaris) (for Win32) is used to create and administer keystores. The keystore specified in a policy configuration file is used to look up the public keys of the signers specified in the grant entries of the file. A keystore entry must appear in a policy configuration file if any grant entries specify signer aliases, or if any grant entries specify principal aliases (see below).

At this time, there can be only one keystore/keystorePasswordURL entry in the policy file (other entries following the first one are ignored). This entry can appear anywhere outside the file's grant entries. It has the following syntax:

keystore "some_keystore_url", "keystore_type", "keystore_provider";
keystorePasswordURL "some_password_url";
some_keystore_url specifies the URL location of the keystore, some_password_url specifies the URL location of the keystore password, keystore_type specifies the keystore type, and keystore_provider specifies the keystore provider. Note that the input stream from some_keystore_url is passed to the KeyStore.load method. If NONE is specified as the URL, then a null stream is passed to the KeyStore.load method. NONE should be specified if the KeyStore is not file-based, for example, if it resides on a hardware token device.

The URL is relative to the policy file location. Thus if the policy file is specified in the security properties file as:

    policy.url.1=http://foo.bar.com/fum/some.policy
and that policy file has an entry:
    keystore ".keystore";
then the keystore will be loaded from:
    http://foo.bar.com/fum/.keystore
The URL can also be absolute.

A keystore type defines the storage and data format of the keystore information, and the algorithms used to protect private keys in the keystore and the integrity of the keystore itself. The default type supported by Sun Microsystems is a proprietary keystore type named "JKS". Thus, if the keystore type is "JKS", it does not need to be specified in the keystore entry.

Grant Entries

Code being executed is always considered to come from a particular "code source" (represented by an object of type CodeSource). The code source includes not only the location (URL) where the code originated from, but also a reference to the certificate(s) containing the public key(s) corresponding to the private key(s) used to sign the code. Certificates in a code source are referenced by symbolic alias names from the user's keystore. Code is also considered to be executed as a particular principal (represented by an object of type Principal), or group of principals.

Each grant entry includes one or more "permission entries" preceded by optional codeBase, signedBy, and principal name/value pairs that specify which code you want to grant the permissions. The basic format of a grant entry is the following:

  grant signedBy "signer_names", codeBase "URL",
        principal principal_class_name "principal_name",
        principal principal_class_name "principal_name",
        ... {

      permission permission_class_name "target_name", "action",
          signedBy "signer_names";
      permission permission_class_name "target_name", "action",
          signedBy "signer_names";
      ...
  };
All non-italicized items above must appear as is (although case doesn't matter and some are optional, as noted below). Italicized items represent variable values.

A grant entry must begin with the word grant.

The SignedBy, Principal, and CodeBase Fields

The signedBy, codeBase, and principal values are optional, and the order of these fields does not matter.

A signedBy value indicates the alias for a certificate stored in the keystore. The public key within that certificate is used to verify the digital signature on the code; you grant the permission(s) to code signed by the private key corresponding to the public key in the keystore entry specified by the alias.

The signedBy value can be a comma-separated list of multiple aliases. An example is "Adam,Eve,Charles", which means "signed by Adam and Eve and Charles"; the relationship is AND, not OR. To be more exact, a statement like "Code signed by Adam" means "Code in a class file contained in a JAR which is signed using the private key corresponding to the public key certificate in the keystore whose entry is aliased by Adam".

The signedBy field is optional in that, if it is omitted, it signifies "any signer". It doesn't matter whether the code is signed or not or by whom.

A principal value specifies a class_name/principal_name pair which must be present within the executing threads principal set. The principal set is associated with the executing code by way of a Subject. The principal field is optional in that, if it is omitted, it signifies "any principals".

Note on KeyStore Alias Replacement:

If the principal class_name/principal_name pair is specified as a single quoted string, it is treated as a keystore alias. The keystore is consulted and queried (via the alias) for an X509 Certificate. If one is found, the principal class_name is automatically treated as javax.security.auth.x500.X500Principal, and the principal_name is automatically treated as the subject distinguished name from the certificate. If an X509 Certificate mapping is not found, the entire grant entry is ignored.

A codeBase value indicates the code source location; you grant the permission(s) to code from that location. An empty codeBase entry signifies "any code"; it doesn't matter where the code originates from.

Note: a codeBase value is a URL and thus should always utilize slashes (never backslashes) as the directory separator, even when the code source is actually on a Win32 system. Thus, if the source location for code on a Win32 system is actually C:\somepath\api\, then the policy codeBase entry should look like:

    grant codeBase "file:/C:/somepath/api/" {
        ...
    }
The exact meaning of a codeBase value depends on the characters at the end. A codeBase with a trailing "/" matches all class files (not JAR files) in the specified directory. A codeBase with a trailing "/*" matches all files (both class and JAR files) contained in that directory. A codeBase with a trailing "/-" matches all files (both class and JAR files) in the directory and recursively all files in subdirectories contained in that directory. The following table illustrates the different cases.

Codebase URL of Downloaded Code Codebase URL in Policy Match?
java.sun.com/people/gong/ java.sun.com/people/gong
Y
java.sun.com/people/gong/ java.sun.com/people/gong/
Y
java.sun.com/people/gong/ java.sun.com/people/gong/*
Y
java.sun.com/people/gong/ java.sun.com/people/gong/-
Y
java.sun.com/people/gong/appl.jar java.sun.com/people/gong/
N
java.sun.com/people/gong/appl.jar java.sun.com/people/gong/-
Y
java.sun.com/people/gong/appl.jar java.sun.com/people/gong/*
Y
java.sun.com/people/gong/appl.jar java.sun.com/people/-
Y
java.sun.com/people/gong/appl.jar java.sun.com/people/*
N
java.sun.com/people/gong/ java.sun.com/people/-
Y
java.sun.com/people/gong/ java.sun.com/people/*
N

The Permission Entries

A permission entry must begin with the word permission. The word permission_class_name in the template above would actually be a specific permission type, such as java.io.FilePermission or java.lang.RuntimePermission.

The "action" is required for many permission types, such as java.io.FilePermission (where it specifies what type of file access is permitted). It is not required for categories such as java.lang.RuntimePermission where it is not necessary--you either have the permission specified by the "target_name" value following the permission_class_name or you don't.

The signedBy name/value pair for a permission entry is optional. If present, it indicates a signed permission. That is, the permission class itself must be signed by the given alias(es) in order for the permission to be granted. For example, suppose you have the following grant entry:

  grant {
      permission Foo "foobar", signedBy "FooSoft";
  }

Then this permission of type Foo is granted if the Foo.class permission was placed in a JAR file and the JAR file was signed by the private key corresponding to the public key in the certificate specified by the "FooSoft" alias, or if Foo.class is a system class, since system classes are not subject to policy restrictions.

Items that appear in a permission entry must appear in the specified order (permission, permission_class_name, "target_name", "action", and signedBy "signer_names"). An entry is terminated with a semicolon.

Case is unimportant for the identifiers (permission, signedBy, codeBase, etc.) but is significant for the permission_class_name or for any string that is passed in as a value.

Note Regarding File Path Specifications on Win32 Systems

Note: When you are specifying a java.io.FilePermission, the "target_name" is a file path. On Win32 systems, whenever you directly specify a file path in a string (but not in a codeBase URL), you need to include two backslashes for each actual single backslash in the path, as in

  grant {
      permission java.io.FilePermission "C:\\users\\cathy\\foo.bat", "read";
  };
The reason this is necessary is because the strings are processed by a tokenizer (java.io.StreamTokenizer), which allows "\" to be used as an escape string (for example, "\n" to indicate a new line) and which thus requires two backslashes to indicate a single backslash. After the tokenizer has processed the above file path string, converting double backslashes to single backslashes, the end result is
    "C:\users\cathy\foo.bat"

Policy File Examples

An example of two entries in a policy configuration file is

  // If the code is signed by "Duke", grant it read/write access to all
  // files in /tmp:
  grant signedBy "Duke" {
      permission java.io.FilePermission "/tmp/*", "read,write";
  };

  // Grant everyone the following permission:
  grant {
      permission java.util.PropertyPermission "java.vendor", "read";
  };

The contents of another sample policy configuration file appear below.

  grant signedBy "sysadmin", codeBase "file:/home/sysadmin/*" {
      permission java.security.SecurityPermission "Security.insertProvider.*";
      permission java.security.SecurityPermission "Security.removeProvider.*";
      permission java.security.SecurityPermission "Security.setProperty.*";
  };
This specifies that only code that satisfies the following conditions can call methods in the Security class to add or remove providers or to set Security properties:
  • The code was loaded from a signed JAR file that is in the "/home/sysadmin/" directory on the local file system.
  • The signature can be verified using the public key referenced by the alias name "sysadmin" in the keystore.

Either component of the code source (or both) may be missing. An example where codeBase is missing is:

  grant signedBy "sysadmin" {
      permission java.security.SecurityPermission "Security.insertProvider.*";
      permission java.security.SecurityPermission "Security.removeProvider.*";
  };
If this policy is in effect, code that comes in a JAR File signed by "sysadmin" can add/remove providers, regardless of where the JAR File originated from.

An example without a signer is:

  grant codeBase "file:/home/sysadmin/-" {
      permission java.security.SecurityPermission "Security.insertProvider.*";
      permission java.security.SecurityPermission "Security.removeProvider.*";
  };
In this case, code that comes from anywhere beneath the "/home/sysadmin/" directory on the local filesystem can add/remove providers. The code does not need to be signed.

An example where neither codeBase nor signedBy is included is:

  grant {
      permission java.security.SecurityPermission "Security.insertProvider.*";
      permission java.security.SecurityPermission "Security.removeProvider.*";
  };
Here, with both code source components missing, any code (regardless of where it originated from, or whether or not it is signed, or who signed it) can add/remove providers.

The following represents a principal-based entry.

  grant principal javax.security.auth.x500.X500Principal "cn=Alice" {
      permission java.io.FilePermission "/home/Alice", "read, write";
  };
This permits any code executing as the X500Principal, "cn=Alice", permission to read and write to "/home/Alice".

The following example shows a grant statement with both codesource and principal information.

  grant codebase "http://www.games.com",
        signedBy "Duke",
        principal javax.security.auth.x500.X500Principal "cn=Alice" {
      permission java.io.FilePermission "/tmp/games", "read, write";
  };
This allows code downloaded from "www.games.com", signed by "Duke", and executed by "cn=Alice", permission to read and write into the "/tmp/games" directory.

The following example shows a grant statement with KeyStore alias replacement:

  keystore "http://foo.bar.com/blah/.keystore";

  grant principal "alice" {
      permission java.io.FilePermission "/tmp/games", "read, write";
  };
"alice" will be replaced by
javax.security.auth.x500.X500Principal "cn=Alice"
assuming the X.509 certificate associated with the keystore alias, alice, has a subject distinguished name of "cn=Alice". This allows code executed by the X500Principal "cn=Alice" permission to read and write into the "/tmp/games" directory.

Property Expansion in Policy Files

Property expansion is possible in policy files and in the security properties file.

Property expansion is similar to expanding variables in a shell. That is, when a string like

    ${some.property}
appears in a policy file, or in the security properties file, it will be expanded to the value of the system property. For example,
    permission java.io.FilePermission "${user.home}", "read";
will expand "${user.home}" to use the value of the "user.home" system property. If that property's value is "/home/cathy", then the above is equivalent to
    permission java.io.FilePermission "/home/cathy", "read";
In order to assist in platform-independent policy files, you can also use the special notation of "${/}", which is a shortcut for "${file.separator}". This allows things like
    permission java.io.FilePermission "${user.home}${/}*", "read";
If the value of the "user.home" property is /home/cathy, and you are on Solaris, the above gets converted to:
    permission java.io.FilePermission "/home/cathy/*", "read";
If on the other hand the "user.home" value is C:\users\cathy and you are on a Win32 system, the above gets converted to:
    permission java.io.FilePermission "C:\users\cathy\*", "read";
Also, as a special case, if you expand a property in a codebase, such as
    grant codeBase "file:${java.home}/lib/ext/"
then any file.separator characters will be automatically converted to /'s. Thus on a Win32 system, the above would get converted to
    grant codeBase "file:C:/jdk1.4/jre/lib/ext/"
even if "java.home" is set to C:\jdk1.4\jre. Thus you don't need to use ${/} in codebase strings (and you shouldn't).

Property expansion takes place anywhere a double quoted string is allowed in the policy file. This includes the "signer_names", "URL", "target_name", and "action" fields.

Whether or not property expansion is allowed is controlled by the value of the "policy.expandProperties" property in the security properties file. If the value of this property is true (the default), expansion is allowed.

Note: You can't use nested properties; they will not work. For example,

    "${user.${foo}}"
doesn't work, even if the "foo" property is set to "home". The reason is the property parser doesn't recognize nested properties; it simply looks for the first "${", and then keeps looking until it finds the first "}" and tries to interpret the result (in this case, "${user.$foo}") as a property, but fails if there is no such property.

Note: If a property can't be expanded in a grant entry, permission entry, or keystore entry, that entry is ignored. For example, if the system property "foo" is not defined and you have:

    grant codeBase "${foo}" {
        permission ...;
        permission ...;
    };
then all the permissions in this grant entry are ignored. If you have
    grant {
        permission Foo "${foo}";
        permission Bar "barTarget";
    };
then only the "permission Foo..." entry is ignored. And finally, if you have
    keystore "${foo}";
then the keystore entry is ignored.

Win32 Systems, File Paths, and Property Expansion

As noted above, on Win32 systems, when you directly specify a file path in a string (but not in a codeBase URL), you need to include two backslashes for each actual single backslash in the path, as in
    grant {
        permission java.io.FilePermission "C:\\users\\cathy\\foo.bat", "read";
    };
This is because the strings are processed by a tokenizer (java.io.StreamTokenizer), which allows "\" to be used as an escape string (e.g., "\n" to indicate a new line) and which thus requires two backslashes to indicate a single backslash. After the tokenizer has processed the above file path string, converting double backslashes to single backslashes, the end result is
    "C:\users\cathy\foo.bat"
Expansion of a property in a string takes place after the tokenizer has processed the string. Thus if you have the string
    "${user.home}\\foo.bat"
then first the tokenizer processes the string, converting the double backslashes to a single backslash, and the result is
    "${user.home}\foo.bat"
Then the ${user.home} property is expanded and the end result is
    "C:\users\cathy\foo.bat"
assuming the "user.home" value is C:\users\cathy. Of course, for platform independence, it would be better if the string was initially specified without any explicit slashes, i.e., using the ${/} property instead, as in
    "${user.home}${/}foo.bat"

General Expansion in Policy Files

Generalized forms of expansion are also supported in policy files. For example, permission names may contain a string of the form:
${{protocol:protocol_data}}
If such a string occurs in a permission name, then the value in protocol determines the exact type of expansion that should occur, and protocol_data is used to help perform the expansion. protocol_data may be empty, in which case the above string should simply take the form:
${{protocol}}

There are two protocols supported in the default policy file implementation:

  1. ${{self}}

    The protocol, self, denotes a replacement of the entire string, ${{self}}, with one or more principal class/name pairs. The exact replacement performed depends upon the contents of the grant clause to which the permission belongs.

    If the grant clause does not contain any principal information, the permission will be ignored (permissions containing ${{self}} in their target names are only valid in the context of a principal-based grant clause). For example, BarPermission will always be ignored in the following grant clause:

            grant codebase "www.foo.com", signedby "duke" {
        permission BarPermission "... ${{self}} ...";
        };
    If the grant clause contains principal information, ${{self}} will be replaced with that same principal information. For example, ${{self}} in BarPermission will be replaced with javax.security.auth.x500.X500Principal "cn=Duke" in the following grant clause:
    grant principal javax.security.auth.x500.X500Principal "cn=Duke" {
    permission BarPermission "... ${{self}} ...";
};
    If there is a comma-separated list of principals in the grant clause, then ${{self}} will be replaced by the same comma-separated list or principals. In the case where both the principal class and name are wildcarded in the grant clause, ${{self}} is replaced with all the principals associated with the Subject in the current AccessControlContext.

    The following example describes a scenario involving both self and KeyStore alias replacement together:

    keystore "http://foo.bar.com/blah/.keystore";

grant principal "duke" {
    permission BarPermission "... ${{self}} ...";
};
    In the above example, "duke" will first be expanded into javax.security.auth.x500.X500Principal "cn=Duke" assuming the X.509 certificate associated with the KeyStore alias, "duke", has a subject distinguished name of "cn=Duke". Next, ${{self}} will be replaced with the same principal information that was just expanded in the grant clause: javax.security.auth.x500.X500Principal "cn=Duke".

  2. ${{alias:alias_name}}

    The protocol, alias, denotes a java.security.KeyStore alias substitution. The KeyStore used is the one specified in the KeyStore entry. alias_name represents an alias into the KeyStore. ${{alias:alias_name}} is replaced with javax.security.auth.x500.X500Principal "DN", where DN represents the subject distinguished name of the certificate belonging to alias_name. For example:

    keystore "http://foo.bar.com/blah/.keystore";

grant codebase "www.foo.com" {
    permission BarPermission "... ${{alias:duke}} ...";
};
    In the above example the X.509 certificate associated with the alias, duke, is retrieved from the KeyStore, foo.bar.com/blah/.keystore. Assuming duke's certificate specifies "o=dukeOrg, cn=duke" as the subject distinguished name, then ${{alias:duke}} is replaced with javax.security.auth.x500.X500Principal "o=dukeOrg, cn=duke".

    The permission entry is ignored under the following error conditions:

    • The keystore entry is unspecified
    • The alias_name is not provided
    • The certificate for alias_name can not be retrieved
    • The certificate retrieved is not an X.509 certificate

Related Documentation

  • Permissions in Java 2 SDK

  • Policy Tool (for Solaris) (for Win32)

Copyright © 1997-2002 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: java-security@sun.com. This is not a subscription list. 		Sun
Java Software


Java ™ Cryptography Architecture
Standard Algorithm Name Documentation

for JavaTM Platform Standard Edition 6

Table of Contents

Standard Names

AlgorithmParameterGenerator Algorithms

AlgorithmParameters Algorithms

CertificateFactory Types

CertPathBuilder Algorithms

CertPath Encodings

CertPathValidator Algorithms

CertStore Types

Cipher (Encryption) Algorithms

Configuration Types

Exemption Mechanisms

GSSAPI Mechanisms

KeyAgreement Algorithms

KeyFactory Algorithms

KeyGenerator Algorithms

KeyPairGenerator Algorithms

KeyStore Types

Mac Algorithms

MessageDigest Algorithms

Policy Types

SaslClient Mechanisms

SaslServer Mechanisms

SecretKeyFactory Algorithms

SecureRandom Number Generation (RNG) Algorithms

Service Attributes

Signature Algorithms

SSLContext Algorithms

TrustManagerFactory Algorithms

XML Signature (XMLSignatureFactory/KeyInfoFactory/TransformService) Mechanisms

XML Signature Transform (TransformService) Algorithms

Additional JSSE Standard Names

Algorithms

Specification Template

Algorithm Specifications

Implementation Requirements

Note: The Sun Provider Documentation contains specific provider and algorithm information.

Standard Names

The JDK Security API requires and uses a set of standard names for algorithms, certificate and keystore types. This specification establishes the following names as standard names.

In some cases naming conventions are given for forming names that are not explicitly listed, to facilitate name consistency across provider implementations. Items in angle brackets (such as <digest> and <encryption>) are placeholders to be replaced by a specific message digest, encryption algorithm, or other name.

Note: Standard names are not case-sensitive.

This document includes corresponding lists of standard names relevant to the following security subareas:

  • Java PKI Programmer's Guide
  • JSSE Reference Guide
  • For standard name specifications, See Algorithms.
  • Cryptography Architecture
  • Single Sign-on Using Kerberos in Java
  • The Java SASL API Programming and Deployment Guide
  • The XML Digital Signature API Specification

AlgorithmParameterGenerator Algorithms

The algorithm names in this section can be specified when generating an instance of AlgorithmParameterGenerator.

Alg. Name | Description
DiffieHellman | Parameters for use with the Diffie-Hellman algorithm.
DSA | Parameters for use with the Digital Signature Algorithm.

AlgorithmParameters Algorithms

The algorithm names in this section can be specified when generating an instance of AlgorithmParameters.

Alg. Name | Description
AES | Parameters for use with the AES algorithm.
Blowfish | Parameters for use with the Blowfish algorithm.
DES | Parameters for use with the DES algorithm.
DESede | Parameters for use with the DESede algorithm.
DiffieHellman | Parameters for use with the DiffieHellman algorithm.
DSA | Parameters for use with the Digital Signature Algorithm.
OAEP | Parameters for use with the OAEP algorithm.
PBEWith<digest>And<encryption> | Parameters for use with the PBEWith<digest>And<encryption> algorithm. Examples: PBEWithMD5AndDES, and PBEWithHmacSHA1AndDESede.
PBE | Parameters for use with the PBE algorithm. This name should not be used, in preference to the more specific PBE-algorithm names above.
RC2 | Parameters for use with the RC2 algorithm.

CertificateFactory Types

The types in this section can be specified when generating an instance of CertificateFactory.

Type | Description
X.509 | The certificate type defined in X.509, also available via RFC 3280

CertPathBuilder Algorithms

The algorithms in this section can be specified when generating an instance of CertPathBuilder.

Alg. Name | Description
PKIX | The PKIX certification path validation algorithm as defined in the ValidationAlgorithm service attribute. The output of CertPathBuilder instances implementing this algorithm is a certification path validated against the PKIX validation algorithm.

CertPath Encodings

The following encodings may be passed to the getEncoded method of CertPath or the generateCertPath(InputStream inStream, String encoding) method of CertificateFactory.

Encoding | Description
PKCS7 | A PKCS#7 SignedData object, with the only significant field being certificates. In particular, the signature and the contents are ignored. If no certificates are present, a zero-length CertPath is assumed. Warning: PKCS#7 does not maintain the order of certificates in a certification path. This means that if a CertPath is converted to PKCS#7 encoded bytes and then converted back, the order of the certificates may change, potentially rendering the CertPath invalid. Users should be aware of this behavior. See RSA Security for details on PKCS7.
PkiPath an ASN.1 DER encoded sequence of certificates, defined as follows:
    PkiPath ::= SEQUENCE OF Certificate
Within the sequence, the order of certificates is such that the subject of the first certificate is the issuer of the second certificate, etc. Each certificate in PkiPath shall be unique. No certificate may appear more than once in a value of Certificate in PkiPath. The PkiPath format is defined in defect report 279 against X.509 (2000) and is incorporated into Technical Corrigendum 1 (DTC 2) for the ITU-T Recommendation X.509 (2000). See the ITU website for details.

CertPathValidator Algorithms

The algorithms in this section can be specified when generating an instance of CertPathValidator.

Alg. Name | Description
PKIX | The PKIX certification path validation algorithm as defined in the ValidationAlgorithm service attribute.

CertStore Types

The types in this section can be specified when generating an instance of CertStore.

Type | Description
Collection | A CertStore implementation that retrieves certificates and CRLs from a Collection. This type of CertStore is particularly useful in applications where certificates or CRLs are received in a bag or some sort of attachment, such as with a signed email message or in an SSL negotiation.
LDAP | A CertStore implementation that fetches certificates and CRLs from an LDAP directory using the schema defined in the LDAPSchema service attribute.

Cipher (Encryption) Algorithms

Cipher Algorithm Names

The following names can be specified as the algorithm component in a transformation when requesting an instance of Cipher.

Alg. Name | Description
AES | Advanced Encryption Standard as specified by NIST in FIPS 197. Also known as the Rijndael algorithm by Joan Daemen and Vincent Rijmen, AES is a 128-bit block cipher supporting keys of 128, 192, and 256 bits.
AESWrap | The AES key wrapping algorithm as described in RFC 3394.
ARCFOUR | A stream cipher believed to be fully interoperable with the RC4 cipher developed by Ron Rivest. For more information, see K. Kaukonen and R. Thayer, "A Stream Cipher Encryption Algorithm 'Arcfour'", Internet Draft (expired), draft-kaukonen-cipher-arcfour-03.txt.
Blowfish | The Blowfish block cipher designed by Bruce Schneier.
DES | The Digital Encryption Standard as described in FIPS PUB 46-3.
DESede | Triple DES Encryption (also known as DES-EDE, 3DES, or Triple-DES). Data is encrypted using the DES algorithm three separate times. It is first encrypted using the first subkey, then decrypted with the second subkey, and encrypted with the third subkey.
DESedeWrap | The DESede key wrapping algorithm as described in RFC 3217 .
ECIES | Elliptic Curve Integrated Encryption Scheme
PBEWith<digest>And<encryption> PBEWith<prf>And<encryption> The password-based encryption algorithm found in (PKCS5), using the specified message digest (<digest>) or pseudo-random function (<prf>) and encryption algorithm (<encryption>). Examples:
  • PBEWithMD5AndDES: The password-based encryption algorithm as defined in RSA Laboratories, "PKCS5: Password-Based Encryption Standard," version 1.5, Nov 1993. Note that this algorithm implies CBC as the cipher mode and PKCS5Padding as the padding scheme and cannot be used with any other cipher modes or padding schemes.
  • PBEWithHmacSHA1AndDESede: The password-based encryption algorithm as defined in RSA Laboratories, "PKCS5: Password-Based Cryptography Standard," version 2.0, March 1999.
RC2 | Variable-key-size encryption algorithms developed by Ron Rivest for RSA Data Security, Inc.
RC4 | Variable-key-size encryption algorithms developed by Ron Rivest for RSA Data Security, Inc. (See note above for ARCFOUR.)
RC5 | Variable-key-size encryption algorithms developed by Ron Rivest for RSA Data Security, Inc.
RSA | The RSA encryption algorithm as defined in PKCS1

Cipher Algorithm Modes

The following names can be specified as the mode component in a transformation when requesting an instance of Cipher.

Alg. Name | Description
NONE | No mode.
CBC | Cipher Block Chaining Mode, as defined in FIPS PUB 81.
CFB, CFBx | Cipher Feedback Mode, as defined in FIPS PUB 81. Using modes such as CFB and OFB, block ciphers can encrypt data in units smaller than the cipher's actual block size. When requesting such a mode, you may optionally specify the number of bits to be processed at a time by appending this number to the mode name as shown in the "DES/CFB8/NoPadding" and "DES/OFB32/PKCS5Padding" transformations. If no such number is specified, a provider-specific default is used. (For example, the SunJCE provider uses a default of 64 bits for DES.) Thus, block ciphers can be turned into byte-oriented stream ciphers by using an 8 bit mode such as CFB8 or OFB8.
CTR | A simplification of OFB, Counter mode updates the input block as a counter.
CTS | Cipher Text Stealing, as described in Bruce Schneier's book Applied Cryptography-Second Edition, John Wiley and Sons, 1996.
ECB | Electronic Codebook Mode, as defined in FIPS PUB 81.
OFB, OFBx | Output Feedback Mode, as defined in FIPS PUB 81. Using modes such as CFB and OFB, block ciphers can encrypt data in units smaller than the cipher's actual block size. When requesting such a mode, you may optionally specify the number of bits to be processed at a time by appending this number to the mode name as shown in the "DES/CFB8/NoPadding" and "DES/OFB32/PKCS5Padding" transformations. If no such number is specified, a provider-specific default is used. (For example, the SunJCE provider uses a default of 64 bits for DES.) Thus, block ciphers can be turned into byte-oriented stream ciphers by using an 8 bit mode such as CFB8 or OFB8.
PCBC | Propagating Cipher Block Chaining, as defined by Kerberos V4.

Cipher Algorithm Padding

The following names can be specified as the padding component in a transformation when requesting an instance of Cipher.

Alg. Name | Description
NoPadding | No padding.
ISO10126Padding | This padding for block ciphers is described in 5.2 Block Encryption Algorithms in the W3C's "XML Encryption Syntax and Processing" document.
OAEPPadding, OAEPWith<digest>And<mgf>Padding Optimal Asymmetric Encryption Padding scheme defined in PKCS1, where <digest> should be replaced by the message digest and <mgf> by the mask generation function. Examples: OAEPWithMD5AndMGF1Padding and OAEPWithSHA-512AndMGF1Padding.

If OAEPPadding is used, Cipher objects are initialized with a javax.crypto.spec.OAEPParameterSpec object to suppply values needed for OAEPPadding.
PKCS1Padding | The padding scheme described in PKCS1, used with the RSA algorithm.
PKCS5Padding | The padding scheme described in RSA Laboratories, "PKCS5: Password-Based Encryption Standard," version 1.5, November 1993.
SSL3Padding The padding scheme defined in the SSL Protocol Version 3.0, November 18, 1996, section 5.2.3.2 (CBC block cipher):
    block-ciphered struct {
    opaque content[SSLCompressed.length];
    opaque MAC[CipherSpec.hash_size];
    uint8 padding[
        GenericBlockCipher.padding_length];
    uint8 padding_length;
    } GenericBlockCipher;
The size of an instance of a GenericBlockCipher must be a multiple of the block cipher's block length.

The padding length, which is always present, contributes to the padding, which implies that if:
    sizeof(content) + sizeof(MAC) % block_length = 0,
padding has to be (block_length - 1) bytes long, because of the existence of padding_length.

This make the padding scheme similar (but not quite) to PKCS5Padding, where the padding length is encoded in the padding (and ranges from 1 to block_length). With the SSL scheme, the sizeof(padding) is encoded in the always present padding_length and therefore ranges from 0 to block_length-1.

Configuration Types

The types in this section can be specified when generating an instance of javax.security.auth.login.Configuration.

Type | Description
JavaLoginConfig | The default Configuration implementation from the SUN provider, as described in the ConfigFile class specification. This type accepts java.security.URIParameter as a valid Configuration.Parameter type. If this parameter is not specified, then the configuration information is loaded from the sources described in the ConfigFile class specification. If this parameter is specified, the configuration information is loaded solely from the specified URI.

Exemption Mechanisms

The following exemption mechanism names can be specified in the permission policy file that accompanies an application considered "exempt" from cryptographic restrictions:

Alg. Name | Description
KeyEscrow | An encryption system with a backup decryption capability that allows authorized persons (users, officers of an organization, and government officials), under certain prescribed conditions, to decrypt ciphertext with the help of information supplied by one or more trusted parties who hold special data recovery keys.
KeyRecovery | A method of obtaining the secret key used to lock encrypted data. One use is as a means of providing fail-safe access to a corporation's own encrypted information in times of disaster.
KeyWeakening | A method in which a part of the key can be escrowed or recovered.

GSSAPI Mechanisms

The following mechanisms can be specified when using GSSAPI. Note that Object Identifiers (OIDs) are specified instead of names to be consistent with the GSSAPI standard.

Mechanism OID | Description
1.2.840.113554.1.2.2 | The Kerberos v5 GSS-API mechanism defined in RFC 4121.
1.3.6.1.5.5.2 | The Simple and Protected GSS-API Negotiation (SPNEGO) mechanism defined in RFC 4178.

KeyAgreement Algorithms

The following algorithm names can be specified when requesting an instance of KeyAgreement.

Alg. Name | Description
DiffieHellman | Diffie-Hellman Key Agreement as defined in PKCS3: Diffie-Hellman Key-Agreement Standard, RSA Laboratories, version 1.4, November 1993.
ECDH | Elliptic Curve Diffie-Hellman as defined in ANSI X9.63 and as described in RFC 3278: "Use of Elliptic Curve Cryptography (ECC) Algorithms in Cryptographic Message Syntax (CMS)."
ECMQV | Elliptic Curve Menezes-Qu-Vanstone as defined in "Elliptic Curve Cryptography" from www.secg.org.

KeyFactory Algorithms

(Except as noted, these classes create keys for which Key.getAlgorithm() returns the standard algorithm name.)

The algorithm names in this section can be specified when generating an instance of KeyFactory.

Alg. Name | Description
DiffieHellman | Keys for the Diffie-Hellman KeyAgreement algorithm. Note: key.getAlgorithm() will return "DH" instead of "DiffieHellman".
DSA | Keys for the Digital Signature Algorithm.
RSA | Keys for the RSA algorithm (Signature/Cipher).
EC | Keys for the Elliptic Curve algorithm.

KeyGenerator Algorithms

The following algorithm names can be specified when requesting an instance of KeyGenerator.

Alg. Name | Description
AES | Key generator for use with the AES algorithm.
ARCFOUR | Key generator for use with the ARCFOUR (RC4) algorithm.
Blowfish | Key generator for use with the Blowfish algorithm.
DES | Key generator for use with the DES algorithm.
DESede | Key generator for use with the DESede (triple-DES) algorithm.
HmacMD5 | Key generator for use with the HmacMD5 algorithm.
HmacSHA1 HmacSHA256 HmacSHA384 HmacSHA512 | Keys generator for use with the various flavors of the HmacSHA algorithms.
RC2 | Key generator for use with the RC2 algorithm.

KeyPairGenerator Algorithms

(Except as noted, these classes create keys for which Key.getAlgorithm() returns the standard algorithm name.)

The algorithm names in this section can be specified when generating an instance of KeyPairGenerator.

Alg. Name | Description
DiffieHellman | Generates keypairs for the Diffie-Hellman KeyAgreement algorithm. Note: key.getAlgorithm() will return "DH" instead of "DiffieHellman".
DSA | Generates keypairs for the Digital Signature Algorithm.
RSA | Generates keypairs for the RSA algorithm (Signature/Cipher).
EC | Generates keypairs for the Elliptic Curve algorithm.

KeyStore Types

The types in this section can be specified when generating an instance of KeyStore.

Type | Description
jceks | The proprietary keystore implementation provided by the "SunJCE" provider.
jks | The proprietary keystore implementation provided by the "SUN" provider.
pkcs12 | The transfer syntax for personal identity information as defined in PKCS12.

Mac Algorithms

The following algorithm names can be specified when requesting an instance of Mac.

Alg. Name | Description
HmacMD5 | The HMAC-MD5 keyed-hashing algorithm as defined in RFC 2104 "HMAC: Keyed-Hashing for Message Authentication" (February 1997).
HmacSHA1 HmacSHA256 HmacSHA384 HmacSHA512 | The HmacSHA* algorithms as defined in RFC 2104 "HMAC: Keyed-Hashing for Message Authentication" (February 1997) with SHA-* as the message digest algorithm.
PBEWith<mac> | Mac for use with the PKCS5 v 2.0 password-based message authentication standard, where <mac> is a Message Authentication Code algorithm name. Example: PBEWithHmacSHA1.

MessageDigest Algorithms

The algorithm names in this section can be specified when generating an instance of MessageDigest.

Alg. Name | Description
MD2 | The MD2 message digest algorithm as defined in RFC 1319.
MD5 | The MD5 message digest algorithm as defined in RFC 1321.
SHA-1 SHA-256 SHA-384 SHA-512 | Hash algorithms defined in the FIPS PUB 180-2. SHA-256 is a 256-bit hash function intended to provide 128 bits of security against collision attacks, while SHA-512 is a 512-bit hash function intended to provide 256 bits of security. A 384-bit hash may be obtained by truncating the SHA-512 output.

Policy Types

The types in this section can be specified when generating an instance of Policy.

Type | Description
JavaPolicy | The default Policy implementation from the SUN provider, as described in the PolicyFile guide. This type accepts java.security.URIParameter as a valid Policy.Parameter type. If this parameter is not specified, then the policy information is loaded from the sources described in the Default Policy File Locations section of the PolicyFile guide. If this parameter is specified, the policy information is loaded solely from the specified URI.

SaslClient Mechanisms

The mechanisms in this section can be specified when generating an instance of SaslClient.

Mechanism | Description
CRAM-MD5 | See RFC 2195. This mechanism supports a hashed username/password authentication scheme.
DIGEST-MD5 | See RFC 2831. This mechanism defines how HTTP Digest Authentication can be used as a SASL mechanism.
EXTERNAL | See RFC 2222. This mechanism obtains authentication information from an external channel (such as TLS or IPsec).
GSSAPI | See RFC 2222. This mechanism uses the GSSAPI for obtaining authentication information. It supports Kerberos v5 authentication.
PLAIN | See RFC 2595. This mechanism supports cleartext username/password authentication.

SaslServer Mechanisms

The mechanisms in this section can be specified when generating an instance of SaslServer.

Mechanism | Description
CRAM-MD5 | See RFC 2195. This mechanism supports a hashed username/password authentication scheme.
DIGEST-MD5 | See RFC 2831. This mechanism defines how HTTP Digest Authentication can be used as a SASL mechanism.
GSSAPI | See RFC 2222. This mechanism uses the GSSAPI for obtaining authentication information. It supports Kerberos v5 authentication.

SecretKeyFactory Algorithms

The following algorithm names can be specified when requesting an instance of SecretKeyFactory.

Alg. Name | Description
AES | Constructs secret keys for use with the AES algorithm.
ARCFOUR | Constructs secret keys for use with the ARCFOUR algorithm.
DES | Constructs secrets keys for use with the DES algorithm.
DESede | Constructs secrets keys for use with the DESede (Triple-DES) algorithm.
PBEWith<digest>And<encryption>
PBEWith<prf>And<encryption> 		Secret-key factory for use with PKCS5 password-based encryption, where <digest> is a message digest, <prf> is a pseudo-random function, and <encryption> is an encryption algorithm.

Examples:

  • PBEWithMD5AndDES (PKCS5, v 1.5),
  • PBEWithHmacSHA1AndDESede (PKCS5, v 2.0), and
Note: These all use only the low order 8 bits of each password character.
PBKDF2WithHmacSHA1 | Constructs secret keys using the Password-Based Key Derivation Function function found in PKCS5 v2.0.

SecureRandom Number Generation (RNG) Algorithms

The algorithm names in this section can be specified when generating an instance of SecureRandom.

Alg. Name | Description
SHA1PRNG | The name of the pseudo-random number generation (PRNG) algorithm supplied by the SUN provider. This algorithm uses SHA-1 as the foundation of the PRNG. It computes the SHA-1 hash over a true-random seed value concatenated with a 64-bit counter which is incremented by 1 for each operation. From the 160-bit SHA-1 output, only 64 bits are used.

Service Attributes

A cryptographic service is always associated with a particular algorithm or type. For example, a digital signature service is always associated with a particular algorithm (e.g., DSA), and a CertificateFactory service is always associated with a particular certificate type (e.g., X.509).

The attributes in this section are for cryptographic services. The service attributes can be used as filters for selecting providers.

Both the attribute name and value are case insensitive.

Attribute | Description
KeySize | The maximum key size that the provider supports for the cryptographic service.
ImplementedIn | Whether the implementation for the cryptographic service is done by software or hardware. The value of this attribute is "software" or "hardware".
ValidationAlgorithm | The name of the specification that defines the certification path validation algorithm that an implementation of CertPathBuilder or CertPathValidator supports. RFCs should be specified as "RFC#" (ex: "RFC3280") and Internet Drafts as the name of the draft (ex: "draft-ietf-pkix-rfc2560bis-01.txt"). Values for this attribute that are specified as selection criteria to the Security.getProviders method will be compared using the String.equalsIgnoreCase method. All PKIX implementations of CertPathBuilder and CertPathValidator should provide a value for this attribute.
LDAPSchema | The name of the specification that defines the LDAP schema that an implementation of an LDAP CertStore uses to retrieve certificates and CRLs. The format and semantics of this attribute is the same as described for the ValidationAlgorithm attribute. All LDAP implementations of CertStore should provide a value for this attribute.

For example:

    map.put("KeyPairGenerator.DSA",
        "sun.security.provider.DSAKeyPairGenerator");
    map.put("KeyPairGenerator.DSA KeySize", "1024");
    map.put("KeyPairGenerator.DSA ImplementedIn", "Software");

Signature Algorithms

The algorithm names in this section can be specified when generating an instance of Signature.

Alg. Name | Description
NONEwithRSA | The RSA signature algorithm which does not use a digesting algorithm (e.g. MD5/SHA1) before performing the RSA operation. For more information about the RSA Signature algorithms, please see PKCS1.
MD2withRSA MD5withRSA | The MD2/MD5 with RSA Encryption signature algorithm which uses the MD2/MD5 digest algorithm and RSA to create and verify RSA digital signatures as defined in PKCS1.
SHA1withRSA SHA256withRSA SHA384withRSA SHA512withRSA | The signature algorithm with SHA-* and the RSA encryption algorithm as defined in the OSI Interoperability Workshop, using the padding conventions described in PKCS1.
NONEwithDSA | The Digital Signature Algorithm as defined in FIPS PUB 186-2. The data must be exactly 20 bytes in length. This algorithms is also known under the alias name of rawDSA.
SHA1withDSA | The DSA with SHA-1 signature algorithm which uses the SHA-1 digest algorithm and DSA to create and verify DSA digital signatures as defined in FIPS PUB 186.
NONEwithECDSA SHA1withECDSA SHA256withECDSA SHA384withECDSA SHA512withECDSA (ECDSA) | The ECDSA signature algorithms as defined in ANSI X9.62. Note:"ECDSA" is an ambiguous name for the "SHA1withECDSA" algorithm and should not be used. The formal name "SHA1withECDSA" should be used instead.
<digest>with<encryption> | Use this to form a name for a signature algorithm with a particular message digest (such as MD2 or MD5) and algorithm (such as RSA or DSA), just as was done for the explicitly-defined standard names in this section (MD2withRSA, etc.). For the new signature schemes defined in PKCS1 v 2.0, for which the <digest>with<encryption> form is insufficient, <digest>with<encryption>and<mgf> can be used to form a name. Here, <mgf> should be replaced by a mask generation function such as MGF1. Example: MD5withRSAandMGF1.

SSLContext Algorithms

The algorithm names in this section can be specified when generating an instance of SSLContext.

Alg. Name | Description
SSL | Supports some version of SSL; may support other versions
SSLv2 | Supports SSL version 2 or higher; may support other versions
SSLv3 | Supports SSL version 3; may support other versions
TLS | Supports some version of TLS; may support other versions
TLSv1 | Supports RFC 2246: TLS version 1.0 ; may support other versions
TLSv1.1 | Supports RFC 4346: TLS version 1.1 ; may support other versions

TrustManagerFactory Algorithms

The algorithm names in this section can be specified when generating an instance of TrustManagerFactory.

Alg. Name | Description
PKIX | A factory for X509TrustManagers which validate certificate chains according to the rules defined by the IETF PKIX working group in RFC 3280 or its successor. The TrustManagerFactory must support initialization using the class javax.net.ssl.CertPathTrustManagerParameters.

XML Signature (XMLSignatureFactory/KeyInfoFactory/TransformService) Mechanisms

The mechanisms in this section can be specified when generating an instance of XMLSignatureFactory, KeyInfoFactory, or TransformService. The mechanism identifies the XML processing mechanism that an implementation uses internally to parse and generate XML signature and KeyInfo structures. Also, note that each TransformService instance supports a specific transform algorithm in addition to a mechanism. The standard names for the transform algorithms are defined in the next section.

Mechanism | Description
DOM | The Document Object Model. See DOM Mechanism Requirements for additional requirements for DOM implementations.

XML Signature Transform (TransformService) Algorithms

The algorithms in this section can be specified when generating an instance of TransformService. Note that URIs are specified instead of names to be consistent with the XML Signature standard. API constants have been defined for each of these URIs, and these are listed in parentheses after each URI in the table below.

Algorithm URI | Description
http://www.w3.org/TR/2001/REC-xml-c14n-20010315 (CanonicalizationMethod.INCLUSIVE) | The Canonical XML (without comments) canonicalization algorithm.
http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments (CanonicalizationMethod.INCLUSIVE_WITH_COMMENTS) | The Canonical XML with comments canonicalization algorithm.
http://www.w3.org/2001/10/xml-exc-c14n# (CanonicalizationMethod.EXCLUSIVE) | The Exclusive Canonical XML (without comments) canonicalization algorithm.
http://www.w3.org/2001/10/xml-exc-c14n#WithComments (CanonicalizationMethod.EXCLUSIVE_WITH_COMMENTS) | The Exclusive Canonical XML with comments canonicalization algorithm.
http://www.w3.org/2000/09/xmldsig#base64 (Transform.BASE64) | The Base64 transform algorithm.
http://www.w3.org/2000/09/xmldsig#enveloped-signature (Transform.ENVELOPED) | The Enveloped Signature transform algorithm.
http://www.w3.org/TR/1999/REC-xpath-19991116 (Transform.XPATH) | The XPath transform algorithm.
http://www.w3.org/2002/06/xmldsig-filter2 (Transform.XPATH2) | The XPath Filter 2 transform algorithm.
http://www.w3.org/TR/1999/REC-xslt-19991116 (Transform.XSLT) | The XSLT transform algorithm.

Additional JSSE Standard Names

The keyType parameter passed to the chooseClientAlias, chooseServerAlias, getClientAliases, and getServerAliases methods of X509KeyManager specify the public key type(s). Each row of the table below lists the standard name that should be used for keyType, given the specified certificate type.

Name | Certificate Type
RSA | RSA
DSA | DSA
DH_RSA | Diffie-Hellman with RSA signature
DH_DSA | Diffie-Hellman with DSA signature
EC | Elliptic Curve
EC_EC | Elliptic Curve with ECDSA signature
EC_RSA | Elliptic Curve with RSA signature

The protocols parameter passed to the setEnabledProtocols method of SSLSocket specifies the protocol versions to be enabled for use on the connection. The table below lists the standard names that can be passed to setEnabledProtocols or that may be returned by the SSLSocket getSupportedProtocols and getEnabledProtocols methods.

Name | Protocol
SSLv2 | SSL version 2 protocol
SSLv3 | SSL version 3 protocol
TLSv1 | TLS version 1.0 protocol (defined in RFC 2246)
TLSv1.1 | TLS version 1.1 protocol (defined in RFC 4346)
SSLv2Hello Currently, the SSLv3, TLSv1, and TLSv1.1 protocols allow you to send SSLv3, TLSv1, and TLSv1.1 hellos encapsulated in an SSLv2 format hello. For more details on the reasons for allowing this compatibility in these protocols, see Appendix E in the appropriate RFCs (above).

Note that some SSL/TLS servers do not support the v2 hello format and require that client hellos conform to the SSLv3 or TLSv1 client hello formats.

The SSLv2Hello option controls the SSLv2 encapsulation. If SSLv2Hello is disabled on the client, then all outgoing messages will conform to the SSLv3/TLSv1 client hello format. If SSLv2Hello is disabled on the server, then all incoming messages must conform to the SSLv3/TLSv1 client hello format.

The authType parameter passed to the checkClientTrusted and checkServerTrusted methods of X509TrustManager indicates the authentication type. The table below specifies what standard names should be used for the client or server certificate chains.

Client or Server Certificate Chain | Authentication Type Standard Name
Client | Determined by the actual certificate used. For instance, if RSAPublicKey is used, the authType should be "RSA".
Server | The key exchange algorithm portion of the cipher suites represented as a String, such as "RSA" or "DHE_DSS". Note: For some exportable cipher suites, the key exchange algorithm is determined at run time during the handshake. For instance, for TLS_RSA_EXPORT_WITH_RC4_40_MD5, the authType should be "RSA_EXPORT" when an ephemeral RSA key is used for the key exchange, and "RSA" when the key from the server certificate is used. Or it can take the value "UNKNOWN".

Over time, various groups have added new ciphersuites definitions to the SSL/TLS namespace. Some ciphersuite names were defined before TLSv1.0 was finalized, and were therefore given the SSL_* prefix. The names mentioned in the TLS RFC prefixed with TLS_* are functionally equivalent to the JSSE ciphersuites prefixed with SSL_*.

The following table lists the standard cipher suite names:

CipherSuite
SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA
SSL_DH_DSS_WITH_DES_CBC_SHA
SSL_DH_DSS_EXPORT_WITH_DES40_CBC_SHA
SSL_DH_RSA_WITH_DES_CBC_SHA
SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA
SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA
TLS_DHE_DSS_WITH_AES_128_CBC_SHA
TLS_DHE_DSS_WITH_AES_256_CBC_SHA
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
SSL_DHE_DSS_WITH_DES_CBC_SHA
SSL_DHE_DSS_WITH_RC4_128_SHA
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
TLS_DHE_RSA_WITH_AES_128_CBC_SHA
TLS_DHE_RSA_WITH_AES_256_CBC_SHA
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
SSL_DHE_RSA_WITH_DES_CBC_SHA
SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
SSL_DHE_DSS_EXPORT1024_WITH_DES_CBC_SHA
SSL_DHE_DSS_EXPORT1024_WITH_RC4_56_SHA
TLS_DH_anon_WITH_AES_128_CBC_SHA
TLS_DH_anon_WITH_AES_256_CBC_SHA
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
SSL_DH_anon_WITH_DES_CBC_SHA
SSL_DH_anon_WITH_RC4_128_MD5
SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA
SSL_DH_anon_EXPORT_WITH_RC4_40_MD5
SSL_FORTEZZA_DMS_WITH_NULL_SHA
SSL_FORTEZZA_DMS_WITH_FORTEZZA_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_DES_CBC_SHA
SSL_RSA_WITH_IDEA_CBC_SHA
SSL_RSA_WITH_RC4_128_MD5
SSL_RSA_WITH_RC4_128_SHA
SSL_RSA_WITH_NULL_MD5
SSL_RSA_WITH_NULL_SHA
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5
SSL_RSA_EXPORT_WITH_RC4_40_MD5
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA
SSL_RSA_EXPORT1024_WITH_RC4_56_SHA
SSL_RSA_EXPORT1024_WITH_DES_CBC_SHA
SSL_RSA_FIPS_WITH_DES_CBC_SHA
SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA
TLS_KRB5_WITH_3DES_EDE_CBC_MD5
TLS_KRB5_WITH_3DES_EDE_CBC_SHA
TLS_KRB5_WITH_DES_CBC_MD5
TLS_KRB5_WITH_DES_CBC_SHA
TLS_KRB5_WITH_IDEA_CBC_SHA
TLS_KRB5_WITH_IDEA_CBC_MD5
TLS_KRB5_WITH_RC4_128_MD5
TLS_KRB5_WITH_RC4_128_SHA
TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5
TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA
TLS_KRB5_EXPORT_WITH_RC2_CBC_40_SHA
TLS_KRB5_EXPORT_WITH_RC2_CBC_40_MD5
TLS_KRB5_EXPORT_WITH_RC4_40_MD5
TLS_KRB5_EXPORT_WITH_RC4_40_SHA
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA
TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
TLS_ECDH_ECDSA_WITH_RC4_128_SHA
TLS_ECDH_ECDSA_WITH_NULL_SHA
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA
TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
TLS_ECDH_RSA_WITH_RC4_128_SHA
TLS_ECDH_RSA_WITH_NULL_SHA
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
TLS_ECDHE_ECDSA_WITH_NULL_SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
TLS_ECDHE_RSA_WITH_RC4_128_SHA
TLS_ECDHE_RSA_WITH_NULL_SHA
TLS_ECDH_anon_WITH_AES_128_CBC_SHA
TLS_ECDH_anon_WITH_AES_256_CBC_SHA
TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA
TLS_ECDH_anon_WITH_RC4_128_SHA
TLS_ECDH_anon_WITH_NULL_SHA

Algorithms

This Section specifies details concerning some of the algorithms defined in this document. Any provider supplying an implementation of the listed algorithms must comply with the specifications in this appendix.

To add a new algorithm not specified here, you should first survey other people or companies supplying provider packages to see if they have already added that algorithm, and, if so, use the definitions they published, if available. Otherwise, you should create and make available a template, similar to those found in this Section, with the specifications for the algorithm you provide.

Specification Template

The following table shows the fields of the algorithm specifications.

Field | Description
Name | The name by which the algorithm is known. This is the name passed to the getInstance method (when requesting the algorithm), and returned by the getAlgorithm method to determine the name of an existing algorithm object. These methods are in the relevant engine classes: Signature, MessageDigest, KeyPairGenerator, and AlgorithmParameterGenerator .
Type | The type of algorithm: Signature, MessageDigest, KeyPairGenerator, or ParameterGenerator.
Description | General notes about the algorithm, including any standards implemented by the algorithm, applicable patents, etc.
KeyPair Algorithm (optional) | The keypair algorithm for this algorithm.
Keysize (optional) | For a keyed algorithm or key generation algorithm: the legal keysizes.
Size (optional) | For an algorithm parameter generation algorithm: the legal "sizes" for algorithm parameter generation.
Parameter Defaults (optional) | For a key generation algorithm: the default parameter values.
Signature Format (optional) | For a Signature algorithm, the format of the signature, that is, the input and output of the verify and sign methods, respectively.

Algorithm Specifications

SHA-1 Message Digest Algorithm

Name | SHA-1
Type | MessageDigest
Description | The message digest algorithm as defined in NIST's FIPS 180-2. The output of this algorithm is a 160-bit digest.

MD2 Message Digest Algorithm

Name | MD2
Type | MessageDigest
Description | The message digest algorithm as defined in RFC 1319. The output of this algorithm is a 128-bit (16 byte) digest.

MD5 Message Digest Algorithm

Name | MD5
Type | MessageDigest
Description | The message digest algorithm as defined in RFC 1321. The output of this algorithm is a 128-bit (16 byte) digest.

The Digital Signature Algorithm

Name | SHA1withDSA
Type | Signature
Description | This algorithm is the signature algorithm described in NIST FIPS 186, using DSA with the SHA-1 message digest algorithm.
KeyPair Algorithm | DSA
Signature Format | ASN.1 sequence of two INTEGER values: r and s, in that order: SEQUENCE ::= { r INTEGER, s INTEGER }

RSA-based Signature Algorithms, with MD2, MD5 or SHA-1

Names | MD2withRSA, MD5withRSA and SHA1withRSA
Type | Signature
Description | These are the signature algorithms that use the MD2, MD5, and SHA-1 message digest algorithms (respectively) with RSA encryption.
KeyPair Algorithm | RSA
Signature Format | DER-encoded PKCS1 block as defined in RSA Laboratory's Public Key Cryptography Standards Note #1. The data encrypted is the digest of the data signed.

DSA KeyPair Generation Algorithm

Name | DSA
Type | KeyPairGenerator
Description | This algorithm is the key pair generation algorithm described in NIST FIPS 186 for DSA.
Keysize | The length, in bits, of the modulus p. This must range from 512 to 1024, and must be a multiple of 64. The default keysize is 1024.
Parameter Defaults

The following default parameter values are used for keysizes of 512, 768, and 1024 bits:

512-bit Key Parameters
SEED = b869c82b 35d70e1b 1ff91b28 e37a62ec dc34409b
counter = 123
p = fca682ce 8e12caba 26efccf7 110e526d b078b05e decbcd1e b4a208f3
    ae1617ae 01f35b91 a47e6df6 3413c5e1 2ed0899b cd132acd 50d99151
    bdc43ee7 37592e17
q = 962eddcc 369cba8e bb260ee6 b6a126d9 346e38c5

g = 678471b2 7a9cf44e e91a49c5 147db1a9 aaf244f0 5a434d64 86931d2d
    14271b9e 35030b71 fd73da17 9069b32e 2935630e 1c206235 4d0da20a
    6c416e50 be794ca4
768-bit key parameters
SEED = 77d0f8c4 dad15eb8 c4f2f8d6 726cefd9 6d5bb399
counter = 263
p = e9e64259 9d355f37 c97ffd35 67120b8e 25c9cd43 e927b3a9 670fbec5
    d8901419 22d2c3b3 ad248009 3799869d 1e846aab 49fab0ad 26d2ce6a
    22219d47 0bce7d77 7d4a21fb e9c270b5 7f607002 f3cef839 3694cf45
    ee3688c1 1a8c56ab 127a3daf
q = 9cdbd84c 9f1ac2f3 8d0f80f4 2ab952e7 338bf511
g = 30470ad5 a005fb14 ce2d9dcd 87e38bc7 d1b1c5fa cbaecbe9 5f190aa7
    a31d23c4 dbbcbe06 17454440 1a5b2c02 0965d8c2 bd2171d3 66844577
    1f74ba08 4d2029d8 3c1c1585 47f3a9f1 a2715be2 3d51ae4d 3e5a1f6a
    7064f316 933a346d 3f529252
1024-bit key parameters
SEED = 8d515589 4229d5e6 89ee01e6 018a237e 2cae64cd
counter = 92
p = fd7f5381 1d751229 52df4a9c 2eece4e7 f611b752 3cef4400 c31e3f80
    b6512669 455d4022 51fb593d 8d58fabf c5f5ba30 f6cb9b55 6cd7813b
    801d346f f26660b7 6b9950a5 a49f9fe8 047b1022 c24fbba9 d7feb7c6
    1bf83b57 e7c6a8a6 150f04fb 83f6d3c5 1ec30235 54135a16 9132f675
    f3ae2b61 d72aeff2 2203199d d14801c7
q = 9760508f 15230bcc b292b982 a2eb840b f0581cf5

g = f7e1a085 d69b3dde cbbcab5c 36b857b9 7994afbb fa3aea82 f9574c0b
    3d078267 5159578e bad4594f e6710710 8180b449 167123e8 4c281613
    b7cf0932 8cc8a6e1 3c167a8b 547c8d28 e0a3ae1e 2bb3a675 916ea37f
    0bfa2135 62f1fb62 7a01243b cca4f1be a8519089 a883dfe1 5ae59f06
    928b665e 807b5525 64014c3b fecf492a

RSA KeyPair Generation Algorithm

Names | RSA
Type | KeyPairGenerator
Description | This algorithm is the key pair generation algorithm described in PKCS1.
Strength | Any integer that is a multiple of 8, greater than or equal to 512.

DSA Parameter Generation Algorithm

Names | DSA
Type | ParameterGenerator
Description | This algorithm is the parameter generation algorithm described in NIST FIPS 186 for DSA.
Strength | The length, in bits, of the modulus p. This must range from 512 to 1024, and must be a multiple of 64. The default size is 1024.

Implementation Requirements

This section defines the security algorithm requirements for Java SE 6 implementations. These requirements are intended to improve the interoperability of Java SE 6 implementations and applications that use these algorithms.

The implementation requirements are one of two types:

  • RECOMMENDED: Each implementation of Java SE 6 should, by default (as installed), support the specified algorithm(s).
  • REQUIRED: Each implementation of Java SE 6 must, by default (as installed), support the specified algorithm(s).

Note that the requirements in this section are not a measure of the strength or security of the algorithm. For example, recent advances in cryptanalysis have found weaknesses in the strength of the MD5 MessageDigest algorithm. It is your responsibility to determine whether the algorithm meets the security requirements of your application.

If an algorithm or engine is not listed, then it is not subject to the specified requirement.

Java Cryptography and PKI Algorithms

Each implementation of Java SE 6 should, by default (as installed), support the specified algorithms (all RECOMMENDED) in the table below. For the next release of Java SE (7), the plan is that each algorithm in the table below will be changed to REQUIRED. These requirements do not apply to 3rd party providers.

RECOMMENDED
Engine | Algorithm Name(s) | Requirement
AlgorithmParameters | DSA | RECOMMENDED
CertificateFactory | X.509 | RECOMMENDED
CertPathBuilder | PKIX | RECOMMENDED
CertPathValidator | PKIX | RECOMMENDED
CertStore | Collection | RECOMMENDED
Cipher (the algorithms are specified as transformations). Implementations must support up to the key size in parentheses. | AES/CBC/NoPadding (128) AES/CBC/PKCS5Padding (128) AES/ECB/NoPadding (128) AES/ECB/PKCS5Padding (128) DES/CBC/NoPadding (56) DES/CBC/PKCS5Padding (56) DES/ECB/NoPadding (56) DES/ECB/PKCS5Padding (56) DESede/CBC/NoPadding (168) DESede/CBC/PKCS5Padding (168) DESede/ECB/NoPadding (168) DESede/ECB/PKCS5Padding (168) RSA/ECB/PKCS1Padding (2048) RSA/ECB/OAEPPadding (2048) | RECOMMENDED
KeyFactory (implementations must support up to the key size in parentheses) | DSA (1024) RSA (2048) | RECOMMENDED
KeyGenerator (implementations must support up to the key size in parentheses) | AES (128) DES (56) DESede (168) HmacMD5 (128) HmacSHA1 (160) HmacSHA256 (160) | RECOMMENDED
KeyPairGenerator (implementations must support up to the key size in parentheses) | DSA (1024) RSA (2048) | RECOMMENDED
KeyStore | jks pkcs12 | RECOMMENDED
Mac (implementations must support up to the key size in parentheses) | HmacMD5 (128) HmacSHA1 (160) HmacSHA256 (160) | RECOMMENDED
MessageDigest | MD5 SHA-1 SHA-256
SecretKeyFactory (implementations must support up to the key size in parentheses) | AES (128) DES (56) DESede (168) | RECOMMENDED
Signature | MD5withRSA SHA1withDSA SHA1withRSA SHA256withRSA | RECOMMENDED

XML Signature Algorithms

The following table lists the algorithm requirements of XML Signature (JSR 105) implementations.

Engine | Algorithm Name(s) | Requirement
TransformService | http://www.w3.org/2001/10/xml-exc-c14n# (CanonicalizationMethod.EXCLUSIVE) | REQUIRED
TransformService | http://www.w3.org/2001/10/xml-exc-c14n#WithComments (CanonicalizationMethod.EXCLUSIVE_WITH_COMMENTS) | RECOMMENDED
TransformService | http://www.w3.org/TR/2001/REC-xml-c14n-20010315 (CanonicalizationMethod.INCLUSIVE) | REQUIRED
TransformService | http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments (CanonicalizationMethod.INCLUSIVE_WITH_COMMENTS) | RECOMMENDED
TransformService | http://www.w3.org/2000/09/xmldsig#base64 (Transform.BASE64) | REQUIRED
TransformService | http://www.w3.org/2000/09/xmldsig#enveloped-signature (Transform.ENVELOPED) | REQUIRED
TransformService | http://www.w3.org/TR/1999/REC-xpath-19991116 (Transform.XPATH) | RECOMMENDED
TransformService | http://www.w3.org/2002/06/xmldsig-filter2 (Transform.XPATH2) | RECOMMENDED
XMLSignatureFactory | http://www.w3.org/2000/09/xmldsig#sha1 (DigestMethod.SHA1) | REQUIRED
XMLSignatureFactory | http://www.w3.org/2000/09/xmldsig#hmac-sha1 (SignatureMethod.HMAC_SHA1) | REQUIRED
XMLSignatureFactory | http://www.w3.org/2000/09/xmldsig#dsa-sha1 (SignatureMethod.DSA_SHA1) | REQUIRED
XMLSignatureFactory | http://www.w3.org/2000/09/xmldsig#rsa-sha1 (SignatureMethod.RSA_SHA1) | RECOMMENDED


Java Cryptography Architecture Sun Providers Documentation

Java ™ Cryptography Architecture
Sun Providers Documentation

for JavaTM Platform Standard Edition 6

Introduction
The SunPKCS11 Provider
The SUN Provider
The SunRsaSign Provider
The SunJSSE Provider
The SunJCE Provider
The SunJGSS Provider
The SunSASL Provider
The XMLDSig Provider
The SunPCSC Provider
The SunMSCAPI Provider

Note: The Standard Names Documentation contains more information about the standard names used in this document.

Introduction

The Java platform defines a set of APIs spanning major security areas, including cryptography, public key infrastructure, authentication, secure communication, and access control. These APIs allow developers to easily integrate security mechanisms into their application code. The Java Cryptography Architecture (JCA) and its Provider Architecture is a core concept of the Java Development Kit (JDK). It is assumed readers have an solid understanding of this architecture.

This document describes the technical details of the providers shipped as part of Sun's Java Environment.

Reminder: Cryptographic implementations in the Sun JDK are distributed through several different providers ("Sun", "SunJSSE", "SunJCE", "SunRsaSign") for both historical reasons and by the types of services provided. General purpose applications SHOULD NOT request cryptographic services from specific providers. That is:

    getInstance("...", "SunJCE");  // not recommended
    vs.
    getInstance("...");            // recommended

Otherwise, applications are tied to specific providers which may not be available on other Java implementations. They also might not be able to take advantage of available optimized providers (for example, hardware accelerators via PKCS11 or native OS implementations such as Microsoft's MSCAPI) that have a higher preference order than the specific requested provider.

The SunPKCS11 Provider

The Cryptographic Token Interface Standard ( PKCS#11) provides native programming interfaces to cryptographic mechanisms, such as hardware cryptographic accelerators and Smart Cards. When properly configured, the SunPKCS11 provider enables applications to use the standard JCA/JCE APIs to access native PKCS#11 libraries. The SunPKCS11 provider itself does not contain cryptographic functionality, it is simply a conduit between the Java environment and the native PKCS11 providers. The Java PKCS#11 Reference Guide has a much more detailed treatment of this provider.

The SUN Provider

JDK 1.1 introduced the Provider architecture. The first JDK provider was named SUN, and contained two types of cryptographic services (MessageDigests and Signatures). In later releases, other mechanisms were added (SecureRandom number generators, KeyPairGenerators, KeyFactorys, etc.).

United States export regulations in effect at the time placed significant restrictions on the type of cryptographic functionality that could be made available internationally in the JDK. For this reason, the SUN provider has historically contained cryptographic engines that did not directly encrypt or decrypt data.

The following algorithms are available in the SUN provider:

Engine | Algorithm Name(s)
AlgorithmParameterGenerator | DSA
AlgorithmParameters | DSA
CertificateFactory | X.509
CertPathBuilder | PKIX
CertPathValidator | PKIX
CertStore | Collection LDAP
Configuration | JavaLoginConfig
KeyFactory | DSA
KeyPairGenerator | DSA
KeyStore | JKS
MessageDigest | MD2 MD5 SHA-1 SHA-256 SHA-384 SHA-512
Policy | JavaPolicy
SecureRandom | SHA1PRNG
Signature | NONEwithDSA SHA1withDSA

Keysize Restrictions

The SUN provider uses the following default keysizes (in bits) and enforce the following restrictions:

KeyPairGenerator

Alg. Name | Default Keysize | Restrictions/Comments
DSA | 1024 | Keysize must be a multiple of 64, ranging from 512 to 1024 (inclusive).

AlgorithmParameterGenerator

Alg. Name | Default Keysize | Restrictions/Comments
DSA | 1024 | Keysize must be a multiple of 64, ranging from 512 to 1024 (inclusive).

CertificateFactory/CertPathBuilder/ CertPathValidator/CertStore implementations

Additional details on the SUN provider implementations for CertificateFactory, CertPathBuilder, CertPathValidator and CertStore are documented in Appendix B of the PKI Programmer's Guide.

The SunRsaSign Provider

The SunRsaSign provider was introduced in JDK 1.3 as an enhanced replacement for the RSA signatures in the SunJSSE provider.

The following algorithms are available in the SunRsaSign provider:

Engine | Algorithm Name(s)
KeyFactory | RSA
KeyPairGenerator | RSA
Signature | MD2withRSA MD5withRSA SHA1withRSA SHA256withRSA SHA384withRSA SHA512withRSA

Keysize Restrictions

The SunRsaSign provider uses the following default keysizes (in bits) and enforce the following restrictions:

KeyPairGenerator

Alg. Name | Default Keysize | Restrictions/Comments
RSA | 1024 | Keysize must range between 512 and 65536 bits, the former of which is unnecessarily large.

The SunJSSE Provider

The Java Secure Socket Extension (JSSE) was originally released as a separate "Optional Package" (also briefly known as a "Standard Extension"), and was available for JDK 1.2.x and 1.3.x. The SunJSSE provider was introduced as part of this release.

In earlier JDK releases, there were no RSA signature providers available in the JDK, therefore SunJSSE had to provide its own RSA implementation in order to use commonly available RSA-based certificates. JDK 5 introduced the SunRsaSign provider, which provides all the functionality (and more) of the SunJSSE provider. Applications targeted at JDK 5.0 and higher should request instances of the SunRsaSign provider instead. For backwards-compatibility, the RSA algorithms are still available through this provider, but are actually implemented in the SunRsaSign provider.

The following algorithms are available in the SunJSSE provider:

Engine | Algorithm Name(s)
KeyFactory | RSA
KeyManagerFactory | SunX509
KeyPairGenerator | RSA
KeyStore | PKCS12
Signature | MD2withRSA MD5withRSA SHA1withRSA
SSLContext | SSLv3 TLSv1
TrustManagerFactory | PKIX

The SunJSSE also supports the following protocol parameters:

Protocol
SSLv3
TLSv1
SSLv2Hello

SunJSSE supports a large number of ciphersuites. The table below shows the ciphersuites supported by SunJSSE in their default preference order and the release in which they were introduced.

Cipher Suite | Supported In Releases
<1.4.2 | 1.4.2 | J2SE 5 | Java SE 6
SSL_RSA_WITH_RC4_128_MD5 | X | X | X | X
SSL_RSA_WITH_RC4_128_SHA | X | X | X | X
TLS_RSA_WITH_AES_128_CBC_SHA | X | X | X
TLS_RSA_WITH_AES_256_CBC_SHA | X | X | X
TLS_ECDH_ECDSA_WITH_RC4_128_SHA | X
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA | X
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA | X
TLS_ECDH_RSA_WITH_RC4_128_SHA | X
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA | X
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA | X
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA | X
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA | X
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA | X
TLS_ECDHE_RSA_WITH_RC4_128_SHA | X
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA | X
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA | X
TLS_DHE_RSA_WITH_AES_128_CBC_SHA | X | X | X
TLS_DHE_RSA_WITH_AES_256_CBC_SHA | X | X | X
TLS_DHE_DSS_WITH_AES_128_CBC_SHA | X | X | X
TLS_DHE_DSS_WITH_AES_256_CBC_SHA | X | X | X
SSL_RSA_WITH_3DES_EDE_CBC_SHA | X | X | X | X
TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA | X
TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA | X
TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA | X
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA | X
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA | X | X | X
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA | X | X | X | X
SSL_RSA_WITH_DES_CBC_SHA | X | X | X | X
SSL_DHE_RSA_WITH_DES_CBC_SHA | X | X | X
SSL_DHE_DSS_WITH_DES_CBC_SHA | X | X | X | X
SSL_RSA_EXPORT_WITH_RC4_40_MD5 | X | X | X | X
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA | X | X | X
SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA | X | X | X
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA | X | X | X | X
SSL_RSA_WITH_NULL_MD5 | X | X | X | X
SSL_RSA_WITH_NULL_SHA | X | X | X | X
TLS_ECDH_ECDSA_WITH_NULL_SHA | X
TLS_ECDH_RSA_WITH_NULL_SHA | X
TLS_ECDHE_ECDSA_WITH_NULL_SHA | X
TLS_ECDHE_RSA_WITH_NULL_SHA | X
SSL_DH_anon_WITH_RC4_128_MD5 | X | X | X | X
TLS_DH_anon_WITH_AES_128_CBC_SHA | X | X | X
TLS_DH_anon_WITH_AES_256_CBC_SHA | X | X | X
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA | X | X | X | X
SSL_DH_anon_WITH_DES_CBC_SHA | X | X | X | X
TLS_ECDH_anon_WITH_RC4_128_SHA | X
TLS_ECDH_anon_WITH_AES_128_CBC_SHA | X
TLS_ECDH_anon_WITH_AES_256_CBC_SHA | X
TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA | X
SSL_DH_anon_EXPORT_WITH_RC4_40_MD5 | X | X | X | X
SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA | X | X | X | X
TLS_ECDH_anon_WITH_NULL_SHA | X
TLS_KRB5_WITH_RC4_128_SHA | X | X
TLS_KRB5_WITH_RC4_128_MD5 | X | X
TLS_KRB5_WITH_3DES_EDE_CBC_SHA | X | X
TLS_KRB5_WITH_3DES_EDE_CBC_MD5 | X | X
TLS_KRB5_WITH_DES_CBC_SHA | X | X
TLS_KRB5_WITH_DES_CBC_MD5 | X | X
TLS_KRB5_EXPORT_WITH_RC4_40_SHA | X | X
TLS_KRB5_EXPORT_WITH_RC4_40_MD5 | X | X
TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA | X | X
TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5 | X | X

Ciphersuites that use AES_256 requires installation of the JCE Unlimited Strength Jurisdiction Policy Files. See Java SE Download Page.

Ciphersuites that use Elliptic Curve Cryptography (ECDSA, ECDH, ECDHE, ECDH_anon) require that a JCE crypto provider with the following properties be installed:

  • implements ECC as defined by the classes and interfaces in the packages java.security.spec and java.security.interfaces. The getAlgorithm() method of elliptic curve key objects must return the String "EC"

  • supports the Signature algorithms SHA1withECDSA and NONEwithECDSA, the KeyAgreement algorithm ECDH, and a KeyPairGenerator and a KeyFactory for algorithm EC. If one of these algorithms is missing, SunJSSE will not allow EC ciphersuites to be used.

  • the crypto provider should support all the SECG curves referenced in RFC 4492 specification, section 5.1.1 (see also appendix A). In certificates, points should be encoded using the uncompressed form and curves should be encoded using the namedCurve choice, i.e. using an object identifier. If these requirements are not met, EC ciphersuites may not be negotiated correctly.

The SunJCE Provider

As described briefly in The SUN Provider, US export regulations at the time restricted the type of cryptographic functionality that could be made available in the JDK. A separate API and reference implementation was developed that allowed applications to encrypt/decrypt data. The Java Cryptographic Extension (JCE) was released as a separate "Optional Package" (also briefly known as a "Standard Extension"), and was available for JDK 1.2.x and 1.3.x. During the development of JDK 1.4, regulations were relaxed enough that JCE (and SunJSSE) could be bundled as part of the JDK.

The following algorithms are available in the SunJCE provider:

Engine | Algorithm Name(s)
AlgorithmParameterGenerator | DiffieHellman
AlgorithmParameters AES
Blowfish
DES
DESede
DiffieHellman
OAEP
PBEWithMD5AndDES
PBEWithMD5AndTripleDES
PBEWithSHA1AndDESede
PBEWithSHA1AndRC2_40
RC2
Cipher
Alg. Name | Modes | Paddings
AES | ECB, CBC, PCBC, CTR, CTS, CFB, CFB8..CFB128, OFB, OFB8..OFB128 | NOPADDING, PKCS5PADDING, ISO10126PADDING
AESWrap | ECB | NOPADDING
ARCFOUR | ECB | NOPADDING
Blowfish, DES, DESede, RC2 | ECB, CBC, PCBC, CTR, CTS, CFB, CFB8..CFB64, OFB, OFB8..OFB64 | NOPADDING, PKCS5PADDING, ISO10126PADDING
DESedeWrap | CBC | NOPADDING
PBEWithMD5AndDES, PBEWithMD5AndTripleDES1 PBEWithSHA1AndDESede, PBEWithSHA1AndRC2_40 | CBC | PKCS5Padding
RSA | ECB | NOPADDING, PKCS1PADDING, OAEPWITHMD5ANDMGF1PADDING, OAEPWITHSHA1ANDMGF1PADDING, OAEPWITHSHA-1ANDMGF1PADDING, OAEPWITHSHA-256ANDMGF1PADDING, OAEPWITHSHA-384ANDMGF1PADDING, OAEPWITHSHA-512ANDMGF1PADDING

Footnote 1: PBEWithMD5AndTripleDES is a proprietary algorithm that has not been standardized.

KeyAgreement | DiffieHellman
KeyFactory DiffieHellman
KeyGenerator AES
ARCFOUR
Blowfish
DES
DESede
HmacMD5
HmacSHA1
HmacSHA256
HmacSHA384
HmacSHA512
RC2
KeyPairGenerator DiffieHellman
KeyStore JCEKS
Mac HmacMD5
HmacSHA1
HmacSHA256
HmacSHA384
HmacSHA512
SecretKeyFactory DES
DESede
PBEWithMD5AndDES
PBEWithMD5AndTripleDES
PBEWithSHA1AndDESede
PBEWithSHA1AndRC2_40
PBKDF2WithHmacSHA1

Keysize Restrictions

The SunJCE provider uses the following default keysizes (in bits) and enforce the following restrictions:

KeyGenerator

Alg. Name | Default Keysize | Restrictions/Comments
AES | 128 | Keysize must be equal to 128, 192, or 256.
ARCFOUR (RC4) | 128 | Keysize must range between 40 and 1024 (inclusive).
Blowfish | 128 | Keysize must be a multiple of 8, ranging from 32 to 448 (inclusive).
DES | 56 | Keysize must be equal to 56.
DESede (Triple DES) 168 Keysize must be equal to 112 or 168.

A keysize of 112 will generate a Triple DES key with 2 intermediate keys, and a keysize of 168 will generate a Triple DES key with 3 intermediate keys.

Due to the "Meet-In-The-Middle" problem, even though 112 or 168 bits of key material are used, the effective keysize is 80 or 112 bits respectively.

HmacMD5 | 512 | No keysize restriction.
HmacSHA1 | 512 | No keysize restriction.
HmacSHA256 | 256 | No keysize restriction.
HmacSHA384 | 384 | No keysize restriction.
HmacSHA512 | 512 | No keysize restriction.
RC2 | 128 | Keysize must range between 40 and 1024 (inclusive).

NOTE: The various Password-Based Encryption (PBE) algorithms use various algorithms to generate key data, and ultimately depends on the targeted Cipher algorithm. For example, "PBEWithMD5AndDES" will always generate 56-bit keys.

KeyPairGenerator

Alg. Name | Default Keysize | Restrictions/Comments
Diffie-Hellman (DH) | 1024 | Keysize must be a multiple of 64, ranging from 512 to 1024 (inclusive).

AlgorithmParameterGenerator

Alg. Name | Default Keysize | Restrictions/Comments
Diffie-Hellman (DH) | 1024 | Keysize must be a multiple of 64, ranging from 512 to 1024 (inclusive).
DSA | 1024 | Keysize must be a multiple of 64, ranging from 512 to 1024 (inclusive).

The SunJGSS Provider

The following algorithms are available in the SunJGSS provider:

OID | Name
1.2.840.113554.1.2.2 | Kerberos v5
1.3.6.1.5.5.2 | SPNEGO

The SunSASL Provider

The following algorithms are available in the SunSASL provider:

Engine | Algorithm Name(s)
SaslClient | CRAM-MD5 DIGEST-MD5 EXTERNAL GSSAPI PLAIN
SaslServer | CRAM-MD5 DIGEST-MD5 GSSAPI

The XMLDSig Provider

The following algorithms are available in the XMLDSig provider:

Engine | Algorithm Name(s)
KeyInfoFactory | DOM
TransformService | http://www.w3.org/TR/2001/REC-xml-c14n-20010315 - (CanonicalizationMethod.INCLUSIVE) http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments - (CanonicalizationMethod.INCLUSIVE_WITH_COMMENTS) http://www.w3.org/2001/10/xml-exc-c14n# - (CanonicalizationMethod.EXCLUSIVE) http://www.w3.org/2001/10/xml-exc-c14n#WithComments - (CanonicalizationMethod.EXCLUSIVE_WITH_COMMENTS) http://www.w3.org/2000/09/xmldsig#base64 - (Transform.BASE64) http://www.w3.org/2000/09/xmldsig#enveloped-signature - (Transform.ENVELOPED) http://www.w3.org/TR/1999/REC-xpath-19991116 - (Transform.XPATH) http://www.w3.org/2002/06/xmldsig-filter2 - (Transform.XPATH2) http://www.w3.org/TR/1999/REC-xslt-19991116 - (Transform.XSLT)
XMLSignatureFactory | DOM

The SunPCSC Provider

The SunPCSC provider enables applications to use the Java Smart Card I/O API to interact with the PC/SC Smart Card stack of the underlying operating system. On some operating systems, it may be necessary to enable and configure the PC/SC stack before it is usable. Consult your operating system documentation for details.

On Solaris and Linux platforms, SunPCSC accesses the PC/SC stack via the libpcsclite.so library. It looks for this library in the directories /usr/$LIBISA and /usr/local/$LIBISA, where $LIBISA is expanded to lib on 32-bit platforms, lib/64 on 64-bit Solaris platforms, and lib64 on 64-bit Linux platforms. The system property sun.security.smartcardio.library may also be set to the full filename of an alternate libpcsclite.so implementation. On Windows platforms, SunPCSC always calls into winscard.dll and no Java-level configuration is necessary or possible.

If PC/SC is available on the host platform, the SunPCSC implementation can be obtained via TerminalFactory.getDefault() and TerminalFactory.getInstance("PC/SC"). If PC/SC is not available or not correctly configured, a getInstance() call will fail with a NoSuchAlgorithmException and getDefault() will return a JRE built-in implementation that does not support any terminals.

The following algorithms are available in the SunPCSC provider:

Engine | Algorithm Name(s)
TerminalFactory | PC/SC

The SunMSCAPI Provider

The SunMSCAPI provider enables applications to use the standard JCA/JCE APIs to access the native cryptographic libraries, certificates stores and key containers on the Microsoft Windows platform. The SunMSCAPI provider itself does not contain cryptographic functionality, it is simply a conduit between the Java environment and the native cryptographic services on Windows.

The following algorithms are available in the SunMSCAPI provider:

Engine | Algorithm Name(s)
Cipher | RSA RSA/ECB/PKCS1Padding only
KeyPairGenerator | RSA
KeyStore Windows-MY

The keystore type that identifies the native Microsoft Windows MY keystore. It contains the user's personal certificates and associated private keys.

Windows-ROOT

The keystore type that identifies the native Microsoft Windows ROOT keystore. It contains the certificates of Root certificate authorities and other self-signed trusted certificates.

SecureRandom Windows-PRNG

The name of the native pseudo-random number generation (PRNG) algorithm.

Signature MD2withRSA
MD5withRSA
SHA1withRSA

Keysize Restrictions

The SunMSCAPI provider uses the following default keysizes (in bits) and enforce the following restrictions:

KeyGenerator

Alg. Name | Default Keysize | Restrictions/Comments
RSA | 1024 | Keysize ranges from 384 bits to 16,384 bits (depending on the underlying Microsoft Windows cryptographic service provider).


Java PKCS#11 Reference Guide

JavaTM PKCS#11 Reference Guide

1.0 Introduction

2.0 Sun PKCS#11 Provider

2.1 Requirements
2.2 Configuration
2.3 Accessing Network Security Services (NSS)
3.0 Application Developers
3.1 Token Login
3.2 Token Keys
3.3 Delayed Provider Selection
3.4 JAAS KeyStoreLoginModule
3.5 Tokens as JSSE Keystores and Trust Stores
4.0 Tools
4.1 KeyTool and JarSigner
4.2 PolicyTool
5.0 Provider Developers
5.1 Provider Services
5.1.1 Instantiating Engine Classes
5.1.2 Parameter Support

Appendix A Sun PKCS#11 Provider's Supported Algorithms

Appendix B Sun PKCS#11 Provider's KeyStore Restrictions

Appendix C Example Provider

1.0 Introduction

The Java platform defines a set of programming interfaces for performing cryptographic operations. These interfaces are collectively known as the Java Cryptography Architecture (JCA) and the Java Cryptography Extension (JCE), and are specified at the Security in J2SE 5 home page.

The cryptographic interfaces are provider-based. Specifically, applications talk to Application Programming Interfaces (APIs), and the actual cryptographic operations are performed in configured providers which adhere to a set of Service Provider Interfaces (SPIs). This architecture supports different provider implementations. Some providers may perform cryptographic operations in software; others may perform the operations on a hardware token (for example, on a smartcard device or on a hardware cryptographic accelerator).

The Cryptographic Token Interface Standard, PKCS#11, is produced by RSA Security and defines native programming interfaces to cryptographic tokens, such as hardware cryptographic accelerators and Smartcards. To facilitate the integration of native PKCS#11 tokens into the Java platform, a new cryptographic provider, the Sun PKCS#11 provider, has been introduced into the J2SE 5.0 release. This new provider enables existing applications written to the JCA and JCE APIs to access native PKCS#11 tokens. No modifications to the application are required. The only requirement is the proper configuration of the provider into the Java Runtime.

Although an application can make use of most PKCS#11 features using existing APIs, some applications might need more flexibility and capabilities. For example, an application might want to deal with Smartcards being removed and inserted dynamically more easily. Or, a PKCS#11 token might require authentication for some non-key-related operations and therefore, the application must be able to log into the token without using keystore. In J2SE 5.0, the JCA was enhanced to allow applications greater flexibility in dealing with different providers.

This document describes how native PKCS#11 tokens can be configured into the Java platform for use by Java applications. It also describes the enhancements that were made to the JCA to make it easier for applications to deal with different types of providers, including PKCS#11 providers.

2.0 Sun PKCS#11 Provider

The Sun PKCS#11 provider, in contrast to most other providers, does not implement cryptographic algorithms itself. Instead, it acts as a bridge between the Java JCA and JCE APIs and the native PKCS#11 cryptographic API, translating the calls and conventions between the two. This means that Java applications calling standard JCA and JCE APIs can, without modification, take advantage of algorithms offered by the underlying PKCS#11 implementations, such as, for example,

  • Cryptographic Smartcards,
  • Hardware cryptographic accelerators, and
  • High performance software implementations.
Note that Java SE only facilitates accessing native PKCS#11 implementations, it does not itself include a native PKCS#11 implementation. However, cryptographic devices such as Smartcards and hardware accelerators often come with software that includes a PKCS#11 implementation, which you need to install and configure according to manufacturer's instructions.

2.1 Requirements

The Sun PKCS#11 provider is supported on Solaris (SPARC and x86) and Linux (x86) in both 32-bit and 64-bit Java processes. It is also supported on 32-bit Windows (x86) but not currently on 64-bit Windows platforms due to the lack of suitable PKCS#11 libraries.

The Sun PKCS#11 provider requires an implementation of PKCS#11 v2.0 or later to be installed on the system. This implementation must take the form of a shared-object library (.so on Solaris and Linux) or dynamic-link library (.dll on Windows). Please consult your vendor documentation to find out if your cryptographic device includes such a PKCS#11 implementation, how to configure it, and what the name of the library file is.

The Sun PKCS#11 provider supports a number of algorithms, provided that the underlying PKCS#11 implementation offers them. The algorithms and their corresponding PKCS#11 mechanisms are listed in the table in Appendix A.

2.2 Configuration

The Sun PKCS#11 provider is implemented by the main class sun.security.pkcs11.SunPKCS11 and accepts the full pathname of a configuration file as an argument. To use the provider, you must first install it by using the Java Cryptography Architecture (JCA). As with all JCA providers, installation of the provider can be done either statically or programmatically. To install the provider statically, add the provider to the Java Security properties file ($JAVA_HOME/lib/security/java.security). For example, here's a fragment of the java.security file that installs the Sun PKCS#11 provider with the configuration file /opt/bar/cfg/pkcs11.cfg.
# configuration for security providers 1-6 ommitted
security.provider.7=sun.security.pkcs11.SunPKCS11 /opt/bar/cfg/pkcs11.cfg
To install the provider dynamically, create an instance of the provider with the appropriate configuration filename and then install it. Here is an example.
String configName = "/opt/bar/cfg/pkcs11.cfg";
Provider p = new sun.security.pkcs11.SunPKCS11(configName);
Security.addProvider(p);

To use more than one slot per PKCS#11 implementation, or to use more than one PKCS#11 implementation, simply repeat the installation for each with the appropriate configuration file. This will result in a Sun PKCS#11 provider instance for each slot of each PKCS#11 implementation.

The configuration file is a text file that contains entries in the following format.

attribute = value
The valid values for attribute and value are described in the table in this section. The two mandatory attributes are name and library. Here is a sample configuration file.
name = FooAccelerator
library = /opt/foo/lib/libpkcs11.so
Comments are denoted by lines starting with the # (number) symbol.

Attribute | Value | Description
library | pathname of PKCS#11 implementation | This is the full pathname (including extension) of the PKCS#11 implementation; the format of the pathname is platform dependent. For example, /opt/foo/lib/libpkcs11.so might be the pathname of a PKCS#11 implementation on Solaris and Linux while C:\foo\mypkcs11.dll might be one on Windows.
name | name suffix of this provider instance | This string is concatenated with the prefix SunPKCS11- to produce this provider instance's name (that is, the the string returned by its Provider.getName() method). For example, if the name attribute is "FooAccelerator", then the provider instance's name will be "SunPKCS11-FooAccelerator".
description | description of this provider instance | This string will be returned by the provider instance's Provider.getInfo() method. If none is specified, a default description will be returned.
slot | slot id | This is the id of the slot that this provider instance is to be associated with. For example, you would use 1 for the slot with the id 1 under PKCS#11. At most one of slot or slotListIndex may be specified. If neither is specified, the default is a slotListIndex of 0.
slotListIndex | slot index | This is the slot index that this provider instance is to be associated with. It is the index into the list of all slots returned by the PKCS#11 function C_GetSlotList. For example, 0 indicates the first slot in the list. At most one of slot or slotListIndex may be specified. If neither is specified, the default is a slotListIndex of 0.
enabledMechanisms brace enclosed, whitespace-separated list of PKCS#11 mechanisms to enable This is the list PKCS#11 mechanisms that this provider instance should use, provided that they are supported by both the Sun PKCS#11 provider and PKCS#11 token. All other mechanisms will be ignored. Each entry in the list is the name of a PKCS#11 mechanism. Here is an example that lists two PKCS#11 mechanisms.
enabledMechanisms = {
  CKM_RSA_PKCS
  CKM_RSA_PKCS_KEY_PAIR_GEN
}
At most one of enabledMechanisms or disabledMechanisms may be specified. If neither is specified, the mechanisms enabled are those that are supported by both the Sun PKCS#11 provider and the PKCS#11 token.
disabledMechanisms brace enclosed, whitespace-separated list of PKCS#11 mechanisms to disable This is the list of PKCS#11 mechanism that this provider instance should ignore. Any mechanism listed will be ignored by the provider, even if they are supported by the token and the Sun PKCS#11 provider. The strings SecureRandom and KeyStore may be specified to disable those services.

At most one of enabledMechanisms or disabledMechanisms may be specified. If neither is specified, the mechanisms enabled are those that are supported by both the Sun PKCS#11 provider and the PKCS#11 token.

attributes | see below | The attributes option can be used to specify additional PKCS#11 that should be set when creating PKCS#11 key objects. This makes it possible to accomodate tokens that require particular attributes. For details, see the section below.

Attributes Configuration

The attributes option allows you to specify additional PKCS#11 attributes that should be set when creating PKCS#11 key objects. By default, the SunPKCS11 provider only specifies mandatory PKCS#11 attributes when creating objects. For example, for RSA public keys it specifies the key type and algorithm (CKA_CLASS and CKA_KEY_TYPE) and the key values for RSA public keys (CKA_MODULUS and CKA_PUBLIC_EXPONENT). The PKCS#11 library you are using will assign implementation specific default values to the other attributes of an RSA public key, for example that the key can be used to encrypt and verify messages (CKA_ENCRYPT and CKA_VERIFY = true).

The attributes option can be used if you do not like the default values your PKCS#11 implementation assigns or if your PKCS#11 implementation does not support defaults and requires a value to be specified explicitly. Note that specifying attributes that your PKCS#11 implementation does not support or that are invalid for the type of key in question may cause the operation to fail at runtime.

The option can be specified zero or more times, the options are processed in the order specified in the configuration file as described below. The attributes option has the format:

attributes(operation, keytype, keyalgorithm) = {
  name1 = value1
  [...]
}
Valid values for operation are:
  • generate, for keys generated via a KeyPairGenerator or KeyGenerator

  • import, for keys created via a KeyFactory or SecretKeyFactory. This also applies to Java software keys automatically converted to PKCS#11 key objects when they are passed to the initialization method of a cryptographic operation, for example Signature.initSign().

  • *, for keys created using either a generate or a create operation.
Valid values for keytype are CKO_PUBLIC_KEY, CKO_PRIVATE_KEY, and CKO_SECRET_KEY, for public, private, and secret keys, respectively, and * to match any type of key.

Valid values for keyalgorithm are one of the CKK_xxx constants from the PKCS#11 specification, or * to match keys of any algorithm. The algorithms currently supported by the SunPKCS11 provider are CKK_RSA, CKK_DSA, CKK_DH, CKK_AES, CKK_DES, CKK_DES3, CKK_RC4, CKK_BLOWFISH, and CKK_GENERIC.

The attribute names and values are specified as a list of one or more name-value pairs. name must be a CKA_xxx constant from the PKCS#11 specification, for example CKA_SENSITIVE. value can be one of the following:

  • a boolean value, true or false
  • an integer, in decimal form (default) or in hexadecimal form if it begins with 0x.
  • null, indicating that this attribute should not be specified when creating objects.
If the attributes option is specified multiple times, the entries are processed in the order specified with the attributes aggregated and later attributes overriding earlier ones. For example, consider the following configuration file excerpt:
attributes(*,CKO_PRIVATE_KEY,*) = {
  CKA_SIGN = true
}

attributes(*,CKO_PRIVATE_KEY,CKK_DH) = {
  CKA_SIGN = null
}

attributes(*,CKO_PRIVATE_KEY,CKK_RSA) = {
  CKA_DECRYPT = true
}
The first entry says to specify CKA_SIGN = true for all private keys. The second option overrides that with null for Diffie-Hellman private keys, so the CKA_SIGN attribute will not specified for them at all. Finally, the third option says to also specify CKA_DECRYPT = true for RSA private keys. That means RSA private keys will have both CKA_SIGN = true and CKA_DECRYPT = true set.

There is also a special form of the attributes option. You can write attributes = compatibility in the configuration file. That is a shortcut for a whole set of attribute statements. They are designed to provider maximum compatibility with existing Java applications, which may expect, for example, all key components to be accessible and secret keys to be useable for both encryption and decryption. The compatibility attributes line can be used together with other attributes lines, in which case the same aggregation and overriding rules apply as described earlier.

2.3 Accessing Network Security Services (NSS)

Network Security Services (NSS) is a set of open source security libraries used by the Mozilla/Firefox browsers, Sun's Java Enterprise System server software, and a number of other products. Its crypto APIs are based on PKCS#11 but it includes special features that are outside of the PKCS#11 standard. The Sun PKCS#11 provider includes code to interact with these NSS specific features, including several NSS specific configuration directives, which are described below.

For best results, we recommend that you use the latest version of NSS available. It should be at least version 3.11.1.

The Sun PKCS#11 provider uses NSS specific code when any of the nss configuration directives described below are used. In that case, the regular configuration commands library, slot, and slotListIndex cannot be used.

Attribute | Value | Description
nssLibraryDirectory directory containing the NSS and NSPR libraries This is the full pathname of the directory containing the NSS and NSPR libraries. It must be specified unless NSS has already been loaded and initialized by another component running in the same process as the Java VM.

Depending on your platform, you may have to set LD_LIBRARY_PATH or PATH (on Windows) to include this directory in order to allow the operating system to locate the dependent libraries.

nssSecmodDirectory | directory containing the NSS DB files | The full pathname of the directory containing the NSS configuration and key information (secmod.db, key3.db, and cert8.db). This directive must be specified unless NSS has already been initialized by another component (see above) or NSS is used without database files as described below.
nssDbMode one of readWrite, readOnly, and noDb This directives determines how the NSS database is accessed. In read-write mode, full access is possible but only one process at a time should be accessing the databases. Read-only mode disallows modifications to the files.

The noDb mode allows NSS to be used without database files purely as a cryptographic provider. It is not possible to create persistent keys using the PKCS11 KeyStore. This mode is useful because NSS includes highly optimized implementations and algorithms not currently available in Sun's bundled Java based crypto providers, for example Elliptic Curve Cryptography (ECC).

nssModule one of keystore, crypto, fips, and trustanchors NSS makes its functionality available using several different libraries and slots. This directive determines which of these modules is accessed by this instance of SunPKCS11.

The crypto module is the default in noDb mode. It supports crypto operations without login but no persistent keys.

The fips module is the default if the NSS secmod.db has been set to FIPS-140 compliant mode. In this mode, NSS restricts the available algorithms and the PKCS#11 attributes with which keys can be created.

The keystore module is the default in other configurations. It supports persistent keys using the PKCS11 KeyStore, which are stored in the NSS DB files. This module requires login.

The trustanchors module enables access to NSS trust anchor certificates via the PKCS11 KeyStore, if secmod.db has been configured to include the trust anchor library.

Example SunPKCS11 configuration files for NSS

NSS as a pure cryptography provider
name = NSScrypto
nssLibraryDirectory = /opt/tests/nss/lib
nssDbMode = noDb
attributes = compatibility

NSS as a FIPS 140 compliant crypto token:
name = NSSfips
nssLibraryDirectory = /opt/tests/nss/lib
nssSecmodDirectory = /opt/tests/nss/fipsdb
nssModule = fips

3.0 Application Developers

Java applications can use the existing JCA and JCE APIs to access PKCS#11 tokens via the Sun PKCS#11 provider. This is sufficient for many applications but it might be difficult for an application to deal with certain PKCS#11 features, such as unextractable keys and dynamically changing Smartcards. Consequently, a number of enhancements were made to the APIs to better support applications using certain PKCS#11 features. These enhancments are discussed in this section.

3.1 Token Login

Certain PKCS#11 operations, such as accessing private keys, require a login using a Personal Identification Number, or PIN, before the operations can proceed. The most common type of operations that require login are those that deal with keys on the token. In a Java application, such operations often involve first loading the keystore. When accessing the PKCS#11 token as a keystore via the java.security.KeyStore class, you can supply the PIN in the password input parameter to the load method, similar to how applications initialize a keystore prior to J2SE 5.0. The PIN will then be used by the Sun PKCS#11 provider for logging into the token. Here is an example.

char[] pin = ...;
KeyStore ks = KeyStore.getInstance("PKCS11");
ks.load(null, pin);

This is fine for an application that treats PKCS#11 tokens as static keystores. For an application that wants to accommodate PKCS#11 tokens more dynamically, such as Smartcards being inserted and removed, you can use the new KeyStore.Builder class. Here is an example of how to initialize the builder for a PKCS#11 keystore with a callback handler.

KeyStore.Builder builder = new KeyStore.Builder("PKCS11");
builder.setCallbackHandler(new MyGuiCallbackHandler());
For the Sun PKCS#11 provider, the callback handler must be able to satisfy a PasswordCallback, which is used to prompt the user for the PIN. Whenever the application needs access to the keystore, it uses the builder as follows.
KeyStore ks = builder.getKeyStore();
Key key = ks.get(alias, null);
The builder will prompt for a password as needed using the previously configured callback handler. The builder will prompt for a password only for the initial access. If the user of the application continues using the same Smartcard, the user will not be prompted again. If the user removes and inserts a different SmartCard, the builder will prompt for a password for the new card.

Depending on the PKCS#11 token, there may be non-key-related operations that also require token login. Applications that use such operations can use the newly introduced java.security.AuthProvider class. The AuthProvider class extends from java.security.Provider and defines methods to perform login and logout operations on a provider, as well as to set a callback handler for the provider to use. For the Sun PKCS#11 provider, the callback handler must be able to satisfy a PasswordCallback, which is used to prompt the user for the PIN.

Here is an example of how an application might use an AuthProvider to log into the token.

AuthProvider aprov = Security.getProvider("SunPKCS11");
aprov.login(subject, new MyGuiCallbackHandler());

3.2 Token Keys

Java Key objects may or may not contain actual key material.

  • A software Key object does contain the actual key material and allows access to that material.

  • An unextractable key on a secure token (such as a Smartcard) is represented by a Java Key object that does not contain the actual key material. The Key object only contains a reference to the actual key.

Applications and providers must use the correct interfaces to represent these different types of Key objects. Software Key objects (or any Key object that has access to the actual key material) should implement the interfaces in the java.security.interfaces and javax.crypto.interfaces packages (such as DSAPrivateKey). Key objects representing unextractable token keys should only implement the relevant generic interfaces in the java.security and javax.crypto packages (PrivateKey, PublicKey, or SecretKey). Identification of the algorithm of a key should be performed using the Key.getAlgorithm() method.

Applications should note that a Key object for an unextractable token key can only be used by the provider associated with that token.

3.3 Delayed Provider Selection

Prior to J2SE 5.0, the Java cryptography getInstance() methods, such as Cipher.getInstance("DES"), returned the implementation from the first provider that implemented the requested algorithm. This is problematic if an application attempts to use a Key object for an unextractable token key with a provider that only accepts software key objects. In such a case, the provider would throw an InvalidKeyException. This is an issue for the Cipher, KeyAgreement, Mac, and Signature classes.

J2SE 5.0, addresses this issue by delaying the selection of the provider until the relevant initialization method is called. The initialization method accepts a Key object and can determine at that point which provider can accept the specified Key object. This ensures that the selected provider can use the specified Key object. The following represents the affected initialization methods.

  • Cipher.init(..., Key key, ...)
  • KeyAgreement.init(Key key, ...)
  • Mac.init(Key key, ...)
  • Signature.initSign(PrivateKey privateKey)
Furthermore, if an application calls the initialization method multiple times (each time with a different key, for example), the proper provider for the given key is selected each time. In other words, a different provider may be selected for each initialization call.

Although this delayed provider selection is hidden from the application, it does affect the behavior of the getProvider() method for Cipher, KeyAgreement, Mac, and Signature. If getProvider() is called before the initialization operation has occurred (and therefore before provider selection has occurred), then the first provider that supports the requested algorithm is returned. This may not be the same provider as the one selected after the initialization method is called. If getProvider() is called after the initialization operation has occurred, then the actual selected provider is returned. It is recommended that applications only call getProvider() after they have called the relevant initialization method.

In addition to getProvider(), the following additional methods are similarly affected.

  • Cipher.getBlockSize
  • Cipher.getExcemptionMechanism
  • Cipher.getIV
  • Cipher.getOutputSize
  • Cipher.getParameters
  • Mac.getMacLength
  • Signature.getParameters
  • Signature.setParameter

3.4 JAAS KeyStoreLoginModule

Java SE comes with a JAAS keystore login module, KeyStoreLoginModule that allows an application to authenticate using its identity in a specified keystore. After authentication, the application would have acquire its principal and credentials information (certificate and private key) from the keystore. By using this login module and configuring it to use a PKCS#11 token as a keystore, the application can acquire this information from a PKCS#11 token.

Use the following options to configure the KeyStoreLoginModule to use a PKCS#11 token as the keystore.

  • keyStoreURL="NONE"
  • keyStoreType="PKCS11"
  • keyStorePasswordURL=some_pin_url
where some_pin_url is the location of the PIN. If the keyStorePasswordURL option is omitted, then the login module will get the PIN via the application's callback handler, supplying it with a PasswordCallback. Here is an example of a configuration file that uses a PKCS#11 token as a keystore.
other {
    com.sun.security.auth.module.KeyStoreLoginModule required
        keyStoreURL="NONE"
  keyStoreType="PKCS11"
  keyStorePasswordURL=file:/home/joe/scpin;
};

If more than one Sun PKCS#11 provider has been configured dynamically or in the java.security security properties file, you can use the keyStoreProvider option to target a specific provider instance. The argument to this option is the name of the provider. For the Sun PKCS#11 provider, the provider name is of the form SunPKCS11-TokenName, where TokenName is the name suffix that the provider instance has been configured with, as detailed in the configuration attributes table. For example, the following configuration file names the PKCS#11 provider instance with name suffix SmartCard.

other {
    com.sun.security.auth.module.KeyStoreLoginModule required
        keyStoreURL="NONE"
  keyStoreType="PKCS11"
  keyStorePasswordURL=file:/home/joe/scpin
  keyStoreProvider="SunPKCS11-SmartCard";
};

Some PKCS#11 tokens support login via a protected authentication path. For example, a Smartcard may have a dedicated PIN-pad to enter the pin. Biometric devices will also have their own means to obtain authentication information. If the PKCS#11 token has a protected authentication path, then use the protected=true option and omit the keyStorePasswordURL option. Here is an example of a configuration file for such a token.

other {
    com.sun.security.auth.module.KeyStoreLoginModule required
        keyStoreURL="NONE"
  keyStoreType="PKCS11"
  protected=true;
};

3.5 Tokens as JSSE Keystore and Trust Stores

To use PKCS#11 tokens as JSSE keystores or trust stores, the JSSE application can use the APIs described previously to instantiate a KeyStore that is backed by a PKCS#11 token and pass it to its key manager and trust manager. The JSSE application will then have access to the keys on the token.

JSSE also supports configuring the use of keystores and trust stores via system properties, as described in the JSSE Reference Guide. To use a PKCS#11 token as a keystore or trust store, set the javax.net.ssl.keyStoreType and javax.net.ssl.trustStoreType system properties, respectively, to "PKCS11", and set the javax.net.ssl.keyStore and javax.net.ssl.trustStore system properties, respectively, to NONE. To specify the use of a specific provider instance, use the javax.net.ssl.keyStoreProvider and javax.net.ssl.trustStoreProvider system properties (e.g., "SunPKCS11-SmartCard").

4.0 Tools

In J2SE 5.0, the security tools were updated to support operations using the new Sun PKCS#11 provider. The changes are discussed below.

4.1 KeyTool and JarSigner

If the Sun PKCS#11 provider has been configured in the java.security security properties file (located in the $JAVA_HOME/lib/security directory of the Java runtime), then keytool and jarsigner can be used to operate on the PKCS#11 token by specifying the following options.

  • -keystore NONE
  • -storetype PKCS11
Here an example of a command to list the contents of the configured PKCS#11 token.
keytool -keystore NONE -storetype PKCS11 -list
The PIN can be specified using the -storepass option. If none has been specified, then keytool and jarsigner will prompt for the token PIN. If the token has a protected authentication path (such as a dedicated PIN-pad or a biometric reader), then the -protected option must be specified, and no password options can be specified.

If more than one Sun PKCS#11 provider has been configured in the java.security security properties file, you can use the -providerName option to target a specific provider instance. The argument to this option is the name of the provider.

  • -providerName providerName
For the Sun PKCS#11 provider, providerName is of the form SunPKCS11-TokenName, where TokenName is the name suffix that the provider instance has been configured with, as detailed in the configuration attributes table. For example, the following command lists the contents of the PKCS#11 keystore provider instance with name suffix SmartCard.
keytool -keystore NONE -storetype PKCS11 \
        -providerName SunPKCS11-SmartCard \
        -list

If the Sun PKCS#11 provider has not been configured in the java.security security properties file, you can use the following options to instruct keytool and jarsigner to install the provider dynamically.

  • -providerClass sun.security.pkcs11.SunPKCS11
  • -providerArg ConfigFilePath
ConfigFilePath is the path to the token configuration file. Here is an example of a command to list a PKCS#11 keystore when the Sun PKCS#11 provider has not been configured in the java.security file.
keytool -keystore NONE -storetype PKCS11 \
        -providerClass sun.security.pkcs11.SunPKCS11 \
        -providerArg /foo/bar/token.config \
        -list

4.2 PolicyTool

Prior to J2SE 5.0, the keystore entry in the default policy implementation had the following syntax.

keystore "some_keystore_url", "keystore_type";
This syntax was inadequate for accessing a PKCS#11 keystore because such access usually required a PIN, and there might be multiple PKCS#11 provider instances. To accommodate these requirements, the keystore entry syntax has been updated in J2SE 5.0, to the following.
keystore "some_keystore_url", "keystore_type", "keystore_provider";
keystorePasswordURL "some_password_url";
Where keystore_provider is the keystore provider name (for example, "SunPKCS11-SmartCard"), and some_password_url is a URL pointing to the location of the token PIN. Both keystore_provider and the keystorePasswordURL line are optional. If keystore_provider has not been specified, then the first configured provider that supports the specified keystore type is used. If the keystorePasswordURL line has not been specified, then no password is used.

The following is an example keystore policy entry for a PKCS#11 token.

keystore "NONE", "PKCS11", "SunPKCS11-SmartCard";
keystorePasswordURL "file:/foo/bar/passwordFile";

5.0 Provider Developers

J2SE 5.0 introduces new facilities in the java.security.Provider class for provider implementations to more easily support PKCS#11 tokens and cryptographic services in general. These new facilities are discussed below.

See Appendix C for an example of a simple provider designed to demonstrate the new facilties.

5.1 Provider Services

As described in the above provider documentation, prior to J2SE 5.0, providers were required to create java.util.Property entries describing the services they supported. For each service implemented by the provider, there must be a property whose name is the type of service (Cipher, Signature, etc), followed by a period and the name of the algorithm to which the service applies. The property value must specify the fully qualified name of the class implementing the service. Here is an example of a provider setting KeyAgreement.DiffieHellman property to have the value com.sun.crypto.provider.DHKeyAgreement.

put("KeyAgreement.DiffieHellman",
      "com.sun.crypto.provider.DHKeyAgreement")

J2SE 5.0 introduces a new public static nested class, Provider.Service, to help better encapsulate the properties of a provider service (including its type, attributes, algorithm name, and algorithm aliases). Providers can instantiate Provider.Service objects and register them by calling the Provider.putService() method. This is equivalent to creating a Property entry and calling the Provider.put() method (as was done prior to J2SE 5.0). Note that legacy Property entries registered via Provider.put are still supported.

Here is an example of a provider creating a Service object with the KeyAgreement type, for the DiffieHellman algorithm, implemented by the class com.sun.crypto.provider.DHKeyAgreement.

Service s = new Service(this, "KeyAgreement", "DiffieHellman",
    "com.sun.crypto.provider.DHKeyAgreement", null, null);
putService(s);

Using Provider.Servicee objects instead of legacy Property entries has a couple of major benefits. One benefit is that it allows the provider to have greater flexibility when instantiating engine classes. Another benefit is that it allows the provider to test parameter validity. These features are discussed in detail next.

5.1.1 Instantiating Engine Classes

Prior to J2SE 5.0, the Java Cryptography framework looked up the provider property for a particular service and directly instantiated the engine class registered for that property. J2SE 5.0, has the same behavior by default, but allows the provider to override this behavior and instantiate the engine class for the requested service itself.

To override the default behavior, the provider overrides the Provider.Service.newInstance() method to add its customer behavior. For example, the provider might call a custom constructor, or might perform initialization using information not accessible outside the provider (or that are only known by the provider).

5.1.2 Parameter Support

The Java Cryptography framework may attempt a fast check to determine whether a provider's service implementation can use an application-specified parameter. To perform this fast check, the framework calls Provider.Service.supportsParameter().

In J2SE 5.0, the framework relies on this fast test during delayed provider selection. When an application invokes an initialization method and passes it a Key object, the framework asks an underlying provider whether it supports the object by calling its Service.supportsParameter() method. If supportsParameter() returns false, the framework can immediately remove that provider from consideration. If supportsParameter() returns true, the framework passes the Key object to that provider's initialization engine class implementation. A provider that requires software Key objects should override this method to return false when it is passed non-software keys. Likewise, a provider for a PKCS#11 token that contains unextractable keys should only return true for Key objects that it created, and which therefore correspond to the Keys on its respective token.

Note that the default implementation of supportsParameter() returns true. This allows existing providers to work without modification. However, because of this lenient default implementation, the framework must be prepared to catch exceptions thrown by providers that reject the Key object inside their initialization engine class implementations. The framework treats these cases the same as when supportsParameter() returns false.

Appendix A: Sun PKCS#11 Provider's Supported Algorithms

The following table lists the Java algorithms supported by the Sun PKCS#11 provider and corresponding PKCS#11 mechanisms needed to support them. When multiple mechanisms are listed, they are given in the order of preference and any one of them is sufficent. Note that SunPKCS11 can be instructed to ignore mechanisms by using the disabledMechanisms and enabledMechanisms configuration directives.

For Elliptic Curve mechanisms, SunPKCS11 will only use keys that use the namedCurve choice as encoding for the parameters and only allow the uncompressed point format. The Sun PKCS#11 provider assumes that a token supports all standard named domain parameters.

Java Algorithm | PKCS#11 Mechanisms
Signature.MD2withRSA | CKM_MD2_RSA_PKCS, CKM_RSA_PKCS, CKM_RSA_X_509
Signature.MD5withRSA | CKM_MD5_RSA_PKCS, CKM_RSA_PKCS, CKM_RSA_X_509
Signature.SHA1withRSA | CKM_SHA1_RSA_PKCS, CKM_RSA_PKCS, CKM_RSA_X_509
Signature.SHA256withRSA | CKM_SHA256_RSA_PKCS, CKM_RSA_PKCS, CKM_RSA_X_509
Signature.SHA384withRSA | CKM_SHA384_RSA_PKCS, CKM_RSA_PKCS, CKM_RSA_X_509
Signature.SHA512withRSA | CKM_SHA512_RSA_PKCS, CKM_RSA_PKCS, CKM_RSA_X_509
Signature.SHA1withDSA | CKM_DSA_SHA1, CKM_DSA
Signature.NONEwithDSA | CKM_DSA
Signature.SHA1withECDSA | CKM_ECDSA_SHA1, CKM_ECDSA
Signature.SHA256withECDSA | CKM_ECDSA
Signature.SHA384withECDSA | CKM_ECDSA
Signature.SHA512withECDSA | CKM_ECDSA
Signature.NONEwithECDSA | CKM_ECDSA
Cipher.RSA/ECB/PKCS1Padding | CKM_RSA_PKCS
Cipher.ARCFOUR | CKM_RC4
Cipher.DES/CBC/NoPadding | CKM_DES_CBC
Cipher.DESede/CBC/NoPadding | CKM_DES3_CBC
Cipher.AES/CBC/NoPadding | CKM_AES_CBC
Cipher.Blowfish/CBC/NoPadding | CKM_BLOWFISH_CBC
KeyAgreement.ECDH | CKM_ECDH1_DERIVE
KeyAgreement.DiffieHellman | CKM_DH_PKCS_DERIVE
KeyPairGenerator.RSA | CKM_RSA_PKCS_KEY_PAIR_GEN
KeyPairGenerator.DSA | CKM_DSA_KEY_PAIR_GEN
KeyPairGenerator.EC | CKM_EC_KEY_PAIR_GEN
KeyPairGenerator.DiffieHellman | CKM_DH_PKCS_KEY_PAIR_GEN
KeyGenerator.ARCFOUR | CKM_RC4_KEY_GEN
KeyGenerator.DES | CKM_DES_KEY_GEN
KeyGenerator.DESede | CKM_DES3_KEY_GEN
KeyGenerator.AES | CKM_AES_KEY_GEN
KeyGenerator.Blowfish | CKM_BLOWFISH_KEY_GEN
Mac.HmacMD5 | CKM_MD5_HMAC
Mac.HmacSHA1 | CKM_SHA_1_HMAC
Mac.HmacSHA256 | CKM_SHA256_HMAC
Mac.HmacSHA384 | CKM_SHA384_HMAC
Mac.HmacSHA512 | CKM_SHA512_HMAC
MessageDigest.MD2 | CKM_MD2
MessageDigest.MD5 | CKM_MD5
MessageDigest.SHA1 | CKM_SHA_1
MessageDigest.SHA-256 | CKM_SHA256
MessageDigest.SHA-384 | CKM_SHA384
MessageDigest.SHA-512 | CKM_SHA512
KeyFactory.RSA | Any supported RSA mechanism
KeyFactory.DSA | Any supported DSA mechanism
KeyFactory.EC | Any supported EC mechanism
KeyFactory.DiffieHellman | Any supported Diffie-Hellman mechanism
SecretKeyFactory.ARCFOUR | CKM_RC4
SecretKeyFactory.DES | CKM_DES_CBC
SecretKeyFactory.DESede | CKM_DES3_CBC
SecretKeyFactory.AES | CKM_AES_CBC
SecretKeyFactory.Blowfish | CKM_BLOWFISH_CBC
SecureRandom.PKCS11 | CK_TOKEN_INFO has the CKF_RNG bit set
KeyStore.PKCS11 | Always available

Appendix B: Sun PKCS#11 provider's KeyStore Requirements

The following describes the requirements placed by the Sun PKCS#11 Provider's KeyStore implementation on the underlying native PKCS#11 library. Note that changes may be made in future releases to maximize interoperability with as many existing PKCS#11 libraries as possible.

Read-Only Access

To map existing objects stored on a PKCS#11 token to KeyStore entries, the Sun PKCS#11 Provider's KeyStore implementation performs the following operations.

  1. A search for all private key objects on the token is performed by calling C_FindObjects[Init|Final]. The search template includes the following attributes:

    • CKA_TOKEN = true
    • CKA_CLASS = CKO_PRIVATE_KEY

  2. A search for all certificate objects on the token is performed by calling C_FindObjects[Init|Final]. The search template includes the following attributes:

    • CKA_TOKEN = true
    • CKA_CLASS = CKO_CERTIFICATE

  3. Each private key object is matched with its corresponding certificate by retrieving their respective CKA_ID attributes. A matching pair must share the same unique CKA_ID.

    For each matching pair, the certificate chain is built by following the issuer->subject path. From the end entity certificate, a call fo C_FindObjects[Init|Final] is made with a search template that includes the following attributes:

    • CKA_TOKEN = true
    • CKA_CLASS = CKO_CERTIFICATE
    • CKA_SUBJECT = [DN of certificate issuer]

    This search is continued until either no certificate for the issuer is found, or until a self-signed certificate is found. If more than one certificate is found the first one is used.

    Once a private key and certificate have been matched (and its certificate chain built), the information is stored in a private key entry with the CKA_LABEL value from end entity certificate as the KeyStore alias.

    If the end entity certificate has no CKA_LABEL, then the alias is derived from the CKA_ID. If the CKA_ID can be determined to consist exclusively of printable characters, then a String alias is created by decoding the CKA_ID bytes using the UTF-8 charset. Otherwise, a hex String alias is created from the CKA_ID bytes ("0xFFFF...", for example).

    If multiple certificates share the same CKA_LABEL, then the alias is derived from the CKA_LABEL plus the end entity certificate issuer and serial number ("MyCert/CN=foobar/1234", for example).

  4. Each certificate not part of a private key entry (as the end entity certificate) is checked whether it is trusted. If the CKA_TRUSTED attribute is true, then a KeyStore trusted certificate entry is created with the CKA_LABEL value as the KeyStore alias. If the certificate has no CKA_LABEL, or if multiple certificates share the same CKA_LABEL, then the alias is derived as described above.

    If the CKA_TRUSTED attribute is not supported then no trusted certificate entries are created.

  5. Any private key or certificate object not part of a private key entry or trusted certificate entry is ignored.

  6. A search for all secret key objects on the token is performed by calling C_FindObjects[Init|Final]. The search template includes the following attributes:

    • CKA_TOKEN = true
    • CKA_CLASS = CKO_SECRET_KEY

    A KeyStore secret key entry is created for each secret key object, with the CKA_LABEL value as the KeyStore alias. Each secret key object must have a unique CKA_LABEL.

Write Access

To create new KeyStore entries on a PKCS#11 token to KeyStore entries, the Sun PKCS#11 Provider's KeyStore implementation performs the following operations.

  1. When creating a KeyStore entry (during KeyStore.setEntry, for example), C_CreateObject is called with CKA_TOKEN=true to create token objects for the respective entry contents.

    Private key objects are stored with CKA_PRIVATE=true. The KeyStore alias (UTF8-encoded) is set as the CKA_ID for both the private key and the corresponding end entity certificate. The KeyStore alias is also set as the CKA_LABEL for the end entity certificate object.

    Each certificate in a private key entry's chain is also stored. The CKA_LABEL is not set for CA certificates. If a CA certificate is already in the token, a duplicate is not stored.

    Secret key objects are stored with CKA_PRIVATE=true. The KeyStore alias is set as the CKA_LABEL.

  2. If an attempt is made to convert a session object to a token object (for example, if KeyStore.setEntry is called and the private key object in the specified entry is a session ojbect), then C_CopyObject is called with CKA_TOKEN=true.

  3. If multiple certificates in the token are found to share the same CKA_LABEL, then the write capabilities to the token are disabled.

  4. Since the PKCS#11 specification does not allow regular applications to set CKA_TRUSTED=true (only token initialization applications may do so), trusted certificate entries can not be created.

Miscellaneous

In addition to the searches listed above, the following searches may be used by the Sun PKCS#11 provider's KeyStore implementation to perform internal functions. Specifically, C_FindObjects[Init|Final] may be called with any of the following attribute templates:

  •     CKA_TOKEN    true
    CKA_CLASS    CKO_CERTIFICATE
    CKA_SUBJECT  [subject DN]

  •     CKA_TOKEN    true
    CKA_CLASS    CKO_SECRET_KEY
    CKA_LABEL    [label]

  •     CKA_TOKEN    true
    CKA_CLASS    CKO_CERTIFICATE or CKO_PRIVATE_KEY
    CKA_ID       [cka_id]

Appendix C: Example Provider

package com.foo;

import java.io.*;
import java.lang.reflect.*;
import java.security.*;
import javax.crypto.*;

/**
 * Example provider that demonstrates some of the new API features.
 *
 *  . implement multiple different algorithms in a single class.
 *    Previously each algorithm needed to be implemented in a separate class
 *    (e.g. one for MD5, one for SHA-1, etc.)
 *
 *  . multiple concurrent instances of the provider frontend class each
 *    associated with a different backend.
 *
 *  . it uses "unextractable" keys and lets the framework know which key
 *    objects it can and cannot support
 *
 * Note that this is only a simple example provider designed to demonstrate
 * several of the new features.  It is not explicitly designed for efficiency.
 */
public final class ExampleProvider extends Provider {

    // reference to the crypto backend that implements all the algorithms
    final CryptoBackend cryptoBackend;

    public ExampleProvider(String name, CryptoBackend cryptoBackend) {
        super(name, 1.0, "JCA/JCE provider for " + name);
        this.cryptoBackend = cryptoBackend;
        // register the algorithms we support (MD5, SHA1, DES, and AES)
        putService(new MyService
            (this, "MessageDigest", "MD5", "com.foo.ExampleProvider$MyMessageDigest"));
        putService(new MyService
            (this, "MessageDigest", "SHA1", "com.foo.ExampleProvider$MyMessageDigest"));
        putService(new MyCipherService
            (this, "Cipher", "DES", "com.foo.ExampleProvider$MyCipher"));
        putService(new MyCipherService
            (this, "Cipher", "AES", "com.foo.ExampleProvider$MyCipher"));
    }

    // the API of our fictitious crypto backend
    static abstract class CryptoBackend {
        abstract byte[] digest(String algorithm, byte[] data);
        abstract byte[] encrypt(String algorithm, KeyHandle key, byte[] data);
        abstract byte[] decrypt(String algorithm, KeyHandle key, byte[] data);
        abstract KeyHandle createKey(String algorithm, byte[] keyData);
    }

    // the shell of the representation the crypto backend uses for keys
    private static final class KeyHandle {
        // fill in code
    }

    // we have our own ServiceDescription implementation that overrides newInstance()
    // that calls the (Provider, String) constructor instead of the no-args constructor
    private static class MyService extends Service {

        private static final Class[] paramTypes = {Provider.class, String.class};

        MyService(Provider provider, String type, String algorithm,
                String className) {
            super(provider, type, algorithm, className, null, null);
        }

        public Object newInstance(Object param) throws NoSuchAlgorithmException {
        try {
        // get the Class object for the implementation class
        Class clazz;
        Provider provider = getProvider();
        ClassLoader loader = provider.getClass().getClassLoader();
        if (loader == null) {
            clazz = Class.forName(getClassName());
        } else {
            clazz = loader.loadClass(getClassName());
        }
        // fetch the (Provider, String) constructor
        Constructor cons = clazz.getConstructor(paramTypes);
        // invoke constructor and return the SPI object
        Object obj = cons.newInstance(new Object[] {provider, getAlgorithm()});
        return obj;
        } catch (Exception e) {
        throw new NoSuchAlgorithmException("Could not instantiate service", e);
        }
        }
    }

    // custom ServiceDescription class for Cipher objects. See supportsParameter() below
    private static class MyCipherService extends MyService {
        MyCipherService(Provider provider, String type, String algorithm,
                String className) {
            super(provider, type, algorithm, className);
        }
        // we override supportsParameter() to let the framework know which
        // keys we can support. We support instances of MySecretKey, if they
        // are stored in our provider backend, plus SecretKeys with a RAW encoding.
        public boolean supportsParameter(Object obj) {
            if (obj instanceof SecretKey == false) {
                return false;
            }
            SecretKey key = (SecretKey)obj;
            if (key.getAlgorithm().equals(getAlgorithm()) == false) {
                return false;
            }
            if (key instanceof MySecretKey) {
                MySecretKey myKey = (MySecretKey)key;
                return myKey.provider == getProvider();
            } else {
                return "RAW".equals(key.getFormat());
            }
        }
    }

    // our generic MessageDigest implementation. It implements all digest
    // algorithms in a single class. We only implement the bare minimum
    // of MessageDigestSpi methods
    private static final class MyMessageDigest extends MessageDigestSpi {
        private final ExampleProvider provider;
        private final String algorithm;
        private ByteArrayOutputStream buffer;
        MyMessageDigest(Provider provider, String algorithm) {
            super();
            this.provider = (ExampleProvider)provider;
            this.algorithm = algorithm;
            engineReset();
        }
        protected void engineReset() {
            buffer = new ByteArrayOutputStream();
        }
        protected void engineUpdate(byte b) {
            buffer.write(b);
        }
        protected void engineUpdate(byte[] b, int ofs, int len) {
            buffer.write(b, ofs, len);
        }
        protected byte[] engineDigest() {
            byte[] data = buffer.toByteArray();
            byte[] digest = provider.cryptoBackend.digest(algorithm, data);
            engineReset();
            return digest;
        }
    }

    // our generic Cipher implementation, only partially complete. It implements
    // all cipher algorithms in a single class. We implement only as many of the
    // CipherSpi methods as required to show how it could work
    private static abstract class MyCipher extends CipherSpi {
        private final ExampleProvider provider;
        private final String algorithm;
        private int opmode;
        private MySecretKey myKey;
        private ByteArrayOutputStream buffer;
        MyCipher(Provider provider, String algorithm) {
            super();
            this.provider = (ExampleProvider)provider;
            this.algorithm = algorithm;
        }
        protected void engineInit(int opmode, Key key, SecureRandom random)
                throws InvalidKeyException {
            this.opmode = opmode;
            myKey = MySecretKey.getKey(provider, algorithm, key);
            if (myKey == null) {
                throw new InvalidKeyException();
            }
            buffer = new ByteArrayOutputStream();
        }
        protected byte[] engineUpdate(byte[] b, int ofs, int len) {
            buffer.write(b, ofs, len);
            return new byte[0];
        }
        protected int engineUpdate(byte[] b, int ofs, int len, byte[] out, int outOfs) {
            buffer.write(b, ofs, len);
            return 0;
        }
        protected byte[] engineDoFinal(byte[] b, int ofs, int len) {
            buffer.write(b, ofs, len);
            byte[] in = buffer.toByteArray();
            byte[] out;
            if (opmode == Cipher.ENCRYPT_MODE) {
                out = provider.cryptoBackend.encrypt(algorithm, myKey.handle, in);
            } else {
                out = provider.cryptoBackend.decrypt(algorithm, myKey.handle, in);
            }
            buffer = new ByteArrayOutputStream();
            return out;
        }
        // code for remaining CipherSpi methods goes here
    }

    // our SecretKey implementation. All our keys are stored in our crypto
    // backend, we only have an opaque handle available. There is no
    // encoded form of these keys.
    private static final class MySecretKey implements SecretKey {

        final String algorithm;
        final Provider provider;
        final KeyHandle handle;

        MySecretKey(Provider provider, String algorithm, KeyHandle handle) {
            super();
            this.provider = provider;
            this.algorithm = algorithm;
            this.handle = handle;
        }
        public String getAlgorithm() {
            return algorithm;
        }
        public String getFormat() {
            return null; // this key has no encoded form
        }
        public byte[] getEncoded() {
            return null; // this key has no encoded form
        }
        // Convert the given key to a key of the specified provider, if possible
        static MySecretKey getKey(ExampleProvider provider, String algorithm, Key key) {
            if (key instanceof SecretKey == false) {
                return null;
            }
            // algorithm name must match
            if (!key.getAlgorithm().equals(algorithm)) {
                return null;
            }
            // if key is already an instance of MySecretKey and is stored
            // on this provider, return it right away
            if (key instanceof MySecretKey) {
                MySecretKey myKey = (MySecretKey)key;
                if (myKey.provider == provider) {
                    return myKey;
                }
            }
            // otherwise, if the input key has a RAW encoding, convert it
            if (!"RAW".equals(key.getFormat())) {
                return null;
            }
            byte[] encoded = key.getEncoded();
            KeyHandle handle = provider.cryptoBackend.createKey(algorithm, encoded);
            return new MySecretKey(provider, algorithm, handle);
        }
    }
}


Java™ 6 Security Enhancements

The Java Platform has added support for the following Security functionality in version 6:

  • JSR 105, the XML Digital Signature API and implementation

    For details, see the XML Digital Signature API Specification and the XML Digital Signature API Overview and Tutorial

  • JSR 268, Smart Card I/O API

    Sun's Java SE 6 implementation bundles the Smart Card I/O API defined by JSR 268 as well as a provider called SunPCSC which uses the platform's native PC/SC Smart Card stack, if available. Note that neither the API nor the SunPCSC provider are part of the Java SE 6 platform specification and may not be present on other compliant Java SE implementations.

  • Elliptic Curve Cryptography (ECC) in SunPKCS11

    The SunPKCS11 provider now exposes ECC algorithms if the underlying PKCS#11 token supports them. This include ECDSA signing and verification, ECDH key agreement, and generation of EC keypairs. For more information about the supported mechanisms, see the supported algorithms section in the PKCS#11 reference guide.

  • Elliptic Curve CipherSuites in SunJSSE

    The SunJSSE now supports the ECC ciphersuites defined in RFC 4492, if a suitable crypto provider is available (for example, SunPKCS11 with an appropriate PKCS#11 library). For more information, see the list of supported ciphersuites and their requirements.

  • Access Network Security Services (NSS) using SunPKCS11

    The SunPKCS11 provider supports new configuration directives which allow it to access the NSS security library. This enables Java applications to read keys stored in the NSS database files, use ECC algorithms, and to use the NSS Softtoken as a FIPS 140 compliant cryptography provider. For more information see the NSS section in the PKCS#11 guide.

  • FIPS 140 compliance for SunJSSE

    The SunJSSE provider now supports an experimental FIPS 140 compliant mode. When enabled and used in combination with the SunPKCS11 provider and an appropriate FIPS 140 certified PKCS#11 token, SunJSSE is FIPS 140 compliant. For details, see the JSSE Reference Guide.

  • Pluggability restrictions have been removed from JSSE

    In earlier releases, the JSSE framework did not allow 3rd party JSSE providers that implemented non-standard ciphersuites due to export control issues.

  • Socket read timeouts are fully supported by SunJSSE SSLSockets

    In previous releases, calling setSoTimeout() would sometimes lead to unpredictable results. This has been corrected.

  • Cipher Text Stealing (CTS) mode added to SunJCE block ciphers

    CTS is described in Bruce Schneier's book "Applied Cryptography-Second Edition", John Wiley & Sons, 1996 (pg. 195-196), and is used by some Kerberos implementations.

  • New PBKDF2WithHmacSHA1 Secretkeyfactory algorithm added to SunJCE

    Constructs secret keys using the Password-Based Key Derivation Function function found in PKCS5 v2.0.

  • Removed the 2048 RSA keysize limit from local_policy.jar

    Implementations were previously restricted from obtaining RSA keys larger than 2048 bits without installing the unlimited crypto policy files.

  • New Certification Authority (CA) certificates added

    A number of new CA certificates were added to the default system lib/security/cacerts file. See the keytool docs for the complete list of CA certificates.

  • Added Two New Options to jarsigner Tool

    Options -digestalg and -sigalg have been added to the jarsigner tool to allow users to override the default signature and digest algorithms when signing a jar file

  • New Options for keytool Tool

    Options -genseckey and -importkeystore have been added to the keytool tool to allow users to generate a SecretKey inside a keystore and copy entries from one keystore to another. Options -genkey, -import and -export have been renamed to -genkeypair, -importcert and -exportcert.

  • User-Entered Passwords no longer echoed on the screen

    Security tools like keytool/jarsigner, and the JAAS login authentication modules use the new java.io.Console class so that user-entered passwords are no longer echoed on the screen.

  • Support for AES Encryption Type in Java GSS/Kerberos

    Support for AES encryption type (AES128 and AES256) in Java GSS/Kerberos is available. This improves interoperability of the Java SE Kerberos implementation with other Kerberos implementations, such as Solaris 10 and MIT Kerberos. For details, see Java GSS Security Features.

  • Support for RC4-HMAC Encryption Type in Java GSS/Kerberos

    Support for RC4-HMAC encryption type in Java GSS/Kerberos is available. This improves interoperability of the Java SE Kerberos implementation with other Kerberos implementations, such as Windows, Solaris 10 and MIT Kerberos. Windows Active Directory supports RC4-HMAC as the default Kerberos encryption type. For details, see Java GSS Security Features.

  • Support for SPNEGO in Java GSS

    Support for SPNEGO mechanism in Java GSS is now available. The Simple and Protected GSS-API Negotiation (SPNEGO) mechanism is a pseudo security mechanism that enables GSS-API peers to securely negotiate a common security mechanism to be used.

    Support for SPNEGO authentication scheme in HTTP is also available. For details, see Java GSS Security Features.

  • Support for new Pre-Authentication Mechanisms

    Java GSS/Kerberos now includes support for the new pre-authentication mechanisms as described in the latest Kerberos specification. For details, see Java GSS Security Features.

  • Native Platform GSS Integration

    This feature allows Java GSS applications to take advantage of features in the native GSS implementation available on the platform. For details, see Java GSS Security Features.

  • Access to native PKI and cryptographic services on Microsoft Windows

    Added the SunMSCAPI JCE provider which uses the Microsoft CryptoAPI (CAPI) to offer a variety of RSA cryptographic functions. It acts as a bridge between Java applications and the services offered by the default RSA cryptographic service provider available via CAPI. It provides access to X.509 certificates and RSA key pairs, it performs RSA encryption and decryption, and it creates and validates RSA signatures. It also supports a cryptographic random number generator.

  • Enhancements to the implementation of PKI Certificate Path Validation

    Added support for segmented and indirect CRLs, resulting in improved performance and improved PKIX compliance (RFC 3280).

  • JAAS-based authentication using LDAP

    Added a JAAS login module which enables users to perform authentication using credentials stored in an LDAP directory service. It provides a drop-in solution for existing JAAS-enabled applications that wish to support authentication using LDAP. See LDAPLoginModule for more information.

  • Default SSLContext

    Added the static method getDefault() and setDefault() to SSLContext. getDefault() returns the default SSLContext, which is initialized in an implementation specific fashion, for example using system properties. setDefault() allows an application to programmatically set the default context to any initialized SSLContext object.

  • SSLParameters

    The new SSLParameters class encapsulates the configuration parameters of an SSL endpoint, in particular the ciphersuites, protocol versions, and for servers the client authentication requirements. They can be applied with a single call to SSLSocket.setSSLParameters() or SSLEngine.setSSLParameters().

Copyright © 1995-2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: java-security@sun.com. This is not a subscription list. 		Sun


Permissions in the JDK

Permissions in the Java™ SE 6 Development Kit (JDK)

A permission represents access to a system resource. In order for a resource access to be allowed for an applet (or an application running with a security manager), the corresponding permission must be explicitly granted to the code attempting the access.

A permission typically has a name (often referred to as a "target name") and, in some cases, a comma-separated list of one or more actions. For example, the following code creates a FilePermission object representing read access to the file named abc in the /tmp directory:

perm = new java.io.FilePermission("/tmp/abc", "read");

In this, the target name is "/tmp/abc" and the action string is "read".

Important Note: The above statement creates a permission object. A permission object represents, but does not grant access to, a system resource. Permission objects are constructed and assigned ("granted") to code based on the policy in effect. When a permission object is assigned to some code, that code is granted the permission to access the system resource specified in the permission object, in the specified manner. A permission object may also be constructed by the current security manager when making access decisions. In this case, the (target) permission object is created based on the requested access, and checked against the permission objects granted to and held by the code making the request.

The policy for a Java application environment is represented by a Policy object. In the Policy reference implementation, the policy can be specified within one or more policy configuration files. The policy file(s) specify what permissions are allowed for code from specified code sources. A sample policy file entry granting code from the /home/sysadmin directory read access to the file /tmp/abc is

grant codeBase "file:/home/sysadmin/" {
    permission java.io.FilePermission "/tmp/abc", "read";
};

For information about policy file locations and granting permissions in policy files, see Default Policy Implementation and Policy File Syntax. For information about using the Policy Tool to specify the permissions, see the Policy Tool documentation (for Solaris) (for Windows). Using the Policy Tool saves typing and eliminates the need for you to know the required syntax of policy files.

Technically, whenever a resource access is attempted, all code traversed by the execution thread up to that point must have permission for that resource access, unless some code on the thread has been marked as "privileged." See API for Privileged Blocks for more information about "privileged" code.

This document contains tables that describe the built-in JDK permission types and discuss the risks of granting each permission. It also contains tables showing the methods that require permissions to be in effect in order to be successful, and for each lists the required permission.

The tables are the following:

Permission Descriptions and Risks
java.security.AllPermission
java.security.SecurityPermission
java.security.UnresolvedPermission
java.awt.AWTPermission
java.io.FilePermission
java.io.SerializablePermission
java.lang.reflect.ReflectPermission
java.lang.RuntimePermission
  • NIO-Related Targets
    • java.net.NetPermission
    java.net.SocketPermission
    java.sql.SQLPermission
    java.util.PropertyPermission
    java.util.logging.LoggingPermission
    javax.net.ssl.SSLPermission
    javax.security.auth.AuthPermission
    javax.security.auth.PrivateCredentialPermission
    javax.security.auth.kerberos.DelegationPermission
    javax.security.auth.kerberos.ServicePermission
    javax.sound.sampled.AudioPermission

    Methods and the Permissions They Require

    java.lang.SecurityManager Method Permission Checks

    For more information about permissions, including the superclasses java.security.Permission and java.security.BasicPermission, and examples of creating permission objects and granting permissions, see the Security Architecture Specification.

    Permission Descriptions and Risks

    The following tables describe the built-in JDK permission types and discuss the risks of granting each permission.

    AllPermission

    The java.security.AllPermission is a permission that implies all other permissions.

    Note: Granting AllPermission should be done with extreme care, as it implies all other permissions. Thus, it grants code the ability to run with security disabled. Extreme caution should be taken before granting such a permission to code. This permission should be used only during testing, or in extremely rare cases where an application or applet is completely trusted and adding the necessary permissions to the policy is prohibitively cumbersome.

    SecurityPermission

    A java.security.SecurityPermission is for security permissions. A SecurityPermission contains a name (also referred to as a "target name") but no actions list; you either have the named permission or you don't.

    The target name is the name of a security configuration parameter (see below). Currently the SecurityPermission object is used to guard access to the Policy, Security, Provider, Signer, and Identity objects.

    The following table lists all the possible SecurityPermission target names, and for each provides a description of what the permission allows and a discussion of the risks of granting code the permission.

    java.security.SecurityPermission
    Target Name     		What the Permission Allows Risks of Allowing this Permission
    createAccessControlContext | Creation of an AccessControlContext | This allows someone to instantiate an AccessControlContext with a DomainCombiner. Since DomainCombiners are given a reference to the ProtectionDomains currently on the stack, this could potentially lead to a privacy leak if the DomainCombiner is malicious.
    getDomainCombiner | Retrieval of an AccessControlContext's DomainCombiner | This allows someone to query the policy via the getPermissions call, which discloses which permissions would be granted to a given CodeSource. While revealing the policy does not compromise the security of the system, it does provide malicious code with additional information which it may use to better aim an attack. It is wise not to divulge more information than necessary.
    getPolicy | Retrieval of the system-wide security policy (specifically, of the currently-installed Policy object) | This allows someone to query the policy via the getPermissions call, which discloses which permissions would be granted to a given CodeSource. While revealing the policy does not compromise the security of the system, it does provide malicious code with additional information which it may use to better aim an attack. It is wise not to divulge more information than necessary.
    setPolicy | Setting of the system-wide security policy (specifically, the Policy object) | Granting this permission is extremely dangerous, as malicious code may grant itself all the necessary permissions it needs to successfully mount an attack on the system.
    createPolicy.{policy type} | Getting an instance of a Policy via Policy.getInstance | Granting this permission enables code to obtain a Policy object. Malicious code may query the Policy object to determine what permissions have been granted to code other than itself.
    getProperty.{key} | Retrieval of the security property with the specified key | Depending on the particular key for which access has been granted, the code may have access to the list of security providers, as well as the location of the system-wide and user security policies. while revealing this information does not compromise the security of the system, it does provide malicious code with additional information which it may use to better aim an attack.
    setProperty.{key} | Setting of the security property with the specified key | This could include setting a security provider or defining the location of the the system-wide security policy. Malicious code that has permission to set a new security provider may set a rogue provider that steals confidential information such as cryptographic private keys. In addition, malicious code with permission to set the location of the system-wide security policy may point it to a security policy that grants the attacker all the necessary permissions it requires to successfully mount an attack on the system.
    insertProvider.{provider name} | Addition of a new provider, with the specified name | This would allow somebody to introduce a possibly malicious provider (e.g., one that discloses the private keys passed to it) as the highest-priority provider. This would be possible because the Security object (which manages the installed providers) currently does not check the integrity or authenticity of a provider before attaching it.
    removeProvider.{provider name} | Removal of the specified provider | This may change the behavior or disable execution of other parts of the program. If a provider subsequently requested by the program has been removed, execution may fail. Also, if the removed provider is not explicitly requested by the rest of the program, but it would normally be the provider chosen when a cryptography service is requested (due to its previous order in the list of providers), a different provider will be chosen instead, or no suitable provider will be found, thereby resulting in program failure.
    setSystemScope | Setting of the system identity scope | This would allow an attacker to configure the system identity scope with certificates that should not be trusted, thereby granting applet or application code signed with those certificates privileges that would have been denied by the system's original identity scope
    setIdentityPublicKey | Setting of the public key for an Identity | If the identity is marked as "trusted", this allows an attacker to introduce a different public key (e.g., its own) that is not trusted by the system's identity scope, thereby granting applet or application code signed with that public key privileges that would have been denied otherwise.
    setIdentityInfo | Setting of a general information string for an Identity | This allows attackers to set the general description for an identity. This may trick applications into using a different identity than intended or may prevent applications from finding a particular identity.
    addIdentityCertificate | Addition of a certificate for an Identity | This allows attackers to set a certificate for an identity's public key. This is dangerous because it affects the trust relationship across the system. This public key suddenly becomes trusted to a wider audience than it otherwise would be.
    removeIdentityCertificate | Removal of a certificate for an Identity | This allows attackers to remove a certificate for an identity's public key. This is dangerous because it affects the trust relationship across the system. This public key suddenly becomes considered less trustworthy than it otherwise would be.
    printIdentity Viewing the name of a principal and optionally the scope in which it is used, and whether or not it is considered "trusted" in that scope. The scope that is printed out may be a filename, in which case it may convey local system information. For example, here's a sample printout of an identity named "carol", who is marked not trusted in the user's identity database:
    carol[/home/luehe/identitydb.obj][not trusted]
    clearProviderProperties.{provider name} | "Clearing" of a Provider so that it no longer contains the properties used to look up services implemented by the provider | This disables the lookup of services implemented by the provider. This may thus change the behavior or disable execution of other parts of the program that would normally utilize the Provider, as described under the "removeProvider.{provider name}" permission.
    putProviderProperty.{provider name} | Setting of properties for the specified Provider | The provider properties each specify the name and location of a particular service implemented by the provider. By granting this permission, you let code replace the service specification with another one, thereby specifying a different implementation.
    removeProviderProperty.{provider name} | Removal of properties from the specified Provider | This disables the lookup of services implemented by the provider. They are no longer accessible due to removal of the properties specifying their names and locations. This may change the behavior or disable execution of other parts of the program that would normally utilize the Provider, as described under the "removeProvider.{provider name}" permission.
    getSignerPrivateKey | Retrieval of a Signer's private key | It is very dangerous to allow access to a private key; private keys are supposed to be kept secret. Otherwise, code can use the private key to sign various files and claim the signature came from the Signer.
    setSignerKeyPair | Setting of the key pair (public key and private key) for a Signer | This would allow an attacker to replace somebody else's (the "target's") keypair with a possibly weaker keypair (e.g., a keypair of a smaller keysize). This also would allow the attacker to listen in on encrypted communication between the target and its peers. The target's peers might wrap an encryption session key under the target's "new" public key, which would allow the attacker (who possesses the corresponding private key) to unwrap the session key and decipher the communication data encrypted under that session key.

    UnresolvedPermission

    The java.security.UnresolvedPermission class is used to hold Permissions that were "unresolved" when the Policy was initialized. An unresolved permission is one whose actual Permission class does not yet exist at the time the Policy is initialized (see below).

    The policy for a Java runtime (specifying which permissions are available for code from various principals) is represented by a Policy object. Whenever a Policy is initialized or refreshed, Permission objects of appropriate classes are created for all permissions allowed by the Policy.

    Many permission class types referenced by the policy configuration are ones that exist locally (i.e., ones that can be found on CLASSPATH). Objects for such permissions can be instantiated during Policy initialization. For example, it is always possible to instantiate a java.io.FilePermission, since the FilePermission class is found on the CLASSPATH.

    Other permission classes may not yet exist during Policy initialization. For example, a referenced permission class may be in a JAR file that will later be loaded. For each such class, an UnresolvedPermission is instantiated. Thus, an UnresolvedPermission is essentially a "placeholder" containing information about the permission.

    Later, when code calls AccessController.checkPermission on a permission of a type that was previously unresolved, but whose class has since been loaded, previously-unresolved permissions of that type are "resolved". That is, for each such UnresolvedPermission, a new object of the appropriate class type is instantiated, based on the information in the UnresolvedPermission. This new object replaces the UnresolvedPermission, which is removed.

    AWTPermission

    A java.awt.AWTPermission is for AWT permissions.

    The following table lists all the possible AWTPermission target names, and for each provides a description of what the permission allows and a discussion of the risks of granting code the permission.

    java.awt.AWTPermission
    Target Name     		What the Permission Allows Risks of Allowing this Permission
    accessClipboard | Posting and retrieval of information to and from the AWT clipboard | This would allow malfeasant code to share potentially sensitive or confidential information.
    accessEventQueue | Access to the AWT event queue | After retrieving the AWT event queue, malicious code may peek at and even remove existing events from the system, as well as post bogus events which may purposefully cause the application or applet to misbehave in an insecure manner.
    createRobot | Create java.awt.Robot objects | The java.awt.Robot object allows code to generate native-level mouse and keyboard events as well as read the screen. It could allow malicious code to control the system, run other programs, read the display, and deny mouse and keyboard access to the user.
    listenToAllAWTEvents | Listen to all AWT events, system-wide | After adding an AWT event listener, malicious code may scan all AWT events dispatched in the system, allowing it to read all user input (such as passwords). Each AWT event listener is called from within the context of that event queue's EventDispatchThread, so if the accessEventQueue permission is also enabled, malicious code could modify the contents of AWT event queues system-wide, causing the application or applet to misbehave in an insecure manner.
    readDisplayPixels | Readback of pixels from the display screen | Interfaces such as the java.awt.Composite interface which allow arbitrary code to examine pixels on the display enable malicious code to snoop on the activities of the user.
    showWindowWithoutWarningBanner | Display of a window without also displaying a banner warning that the window was created by an applet | Without this warning, an applet may pop up windows without the user knowing that they belong to an applet. Since users may make security-sensitive decisions based on whether or not the window belongs to an applet (entering a username and password into a dialog box, for example), disabling this warning banner may allow applets to trick the user into entering such information.

    FilePermission

    A java.io.FilePermission represents access to a file or directory. A FilePermission consists of a pathname and a set of actions valid for that pathname.

    Pathname is the pathname of the file or directory granted the specified actions. A pathname that ends in "/*" (where "/" is the file separator character, File.separatorChar) indicates a directory and all the files contained in that directory. A pathname that ends with "/-" indicates a directory and (recursively) all files and subdirectories contained in that directory. A pathname consisting of the special token "<<ALL FILES>>" matches any file.

    A pathname consisting of a single "*" indicates all the files in the current directory, while a pathname consisting of a single "-" indicates all the files in the current directory and (recursively) all files and subdirectories contained in the current directory.

    The actions to be granted are passed to the constructor in a string containing a list of zero or more comma-separated keywords. The possible keywords are "read", "write", "execute", and "delete". Their meaning is defined as follows:

    read | Permission to read.
    write | Permission to write (which includes permission to create).
    execute | Permission to execute. Allows Runtime.exec to be called. Corresponds to SecurityManager.checkExec.
    delete | Permission to delete. Allows File.delete to be called. Corresponds to SecurityManager.checkDelete.

    The actions string is converted to lowercase before processing.

    Be careful when granting FilePermissions. Think about the implications of granting read and especially write access to various files and directories. The "<<ALL FILES>>" permission with write action is especially dangerous. This grants permission to write to the entire file system. One thing this effectively allows is replacement of the system binary, including the JVM runtime environment.

    Note: code can always read a file from the same directory it's in (or a subdirectory of that directory); it does not need explicit permission to do so.

    SerializablePermission

    A java.io.SerializablePermission is for serializable permissions. A SerializablePermission contains a name (also referred to as a "target name") but no actions list; you either have the named permission or you don't.

    The target name is the name of the Serializable permission (see below).

    The following table lists all the possible SerializablePermission target names, and for each provides a description of what the permission allows and a discussion of the risks of granting code the permission.

    java.io.SerializablePermission
    Target Name     		What the Permission Allows Risks of Allowing this Permission
    enableSubclassImplementation | Implementing a subclass of ObjectOutputStream or ObjectInputStream to override the default serialization or deserialization, respectively, of objects | Code can use this to serialize or deserialize classes in a purposefully malfeasant manner. For example, during serialization, malicious code can use this to purposefully store confidential private field data in a way easily accessible to attackers. Or, during deserializaiton it could, for example, deserialize a class with all its private fields zeroed out.
    enableSubstitution | Substitution of one object for another during serialization or deserialization | This is dangerous because malicious code can replace the actual object with one which has incorrect or malignant data.

    ReflectPermission

    A java.lang.reflect.ReflectPermission is for reflective operations. A ReflectPermission is a named permission and has no actions. The only name currently defined is suppressAccessChecks, which allows suppressing the standard language access checks -- for public, default (package) access, protected, and private members -- performed by reflected objects at their point of use.

    The following table provides a summary description of what the permission allows, and discusses the risks of granting code the permission.

    java.lang.reflect.ReflectPermission
    Target Name     		What the Permission Allows Risks of Allowing this Permission
    suppressAccessChecks Warning: Extreme caution should be taken before granting this permission to code, for it provides the ability to access fields and invoke methods in a class. This includes not only public, but protected and private fields and methods as well. This is dangerous in that information (possibly confidential) and methods normally unavailable would be accessible to malicious code.

    RuntimePermission

    A java.lang.RuntimePermission is for runtime permissions. A RuntimePermission contains a name (also referred to as a "target name") but no actions list; you either have the named permission or you don't.

    The target name is the name of the runtime permission (see below). The naming convention follows the hierarchical property naming convention. Also, an asterisk may appear at the end of the name, following a ".", or by itself, to signify a wildcard match. For example: "loadLibrary.*" or "*" is valid, "*loadLibrary" or "a*b" is not valid.

    The following table lists all the possible RuntimePermission target names, and for each provides a description of what the permission allows and a discussion of the risks of granting code the permission.

    java.lang.RuntimePermission
    Target Name     		What the Permission Allows Risks of Allowing this Permission
    createClassLoader | Creation of a class loader | This is an extremely dangerous permission to grant. Malicious applications that can instantiate their own class loaders could then load their own rogue classes into the system. These newly loaded classes could be placed into any protection domain by the class loader, thereby automatically granting the classes the permissions for that domain.
    getClassLoader | Retrieval of a class loader (e.g., the class loader for the calling class) | This would grant an attacker permission to get the class loader for a particular class. This is dangerous because having access to a class's class loader allows the attacker to load other classes available to that class loader. The attacker would typically otherwise not have access to those classes.
    setContextClassLoader | Setting of the context class loader used by a thread | The context class loader is used by system code and extensions when they need to lookup resources that might not exist in the system class loader. Granting setContextClassLoader permission would allow code to change which context class loader is used for a particular thread, including system threads.
    setSecurityManager | Setting of the security manager (possibly replacing an existing one) | The security manager is a class that allows applications to implement a security policy. Granting the setSecurityManager permission would allow code to change which security manager is used by installing a different, possibly less restrictive security manager, thereby bypassing checks that would have been enforced by the original security manager.
    createSecurityManager | Creation of a new security manager | This gives code access to protected, sensitive methods that may disclose information about other classes or the execution stack.
    exitVM.{exit status} | Halting of the Java Virtual Machine with the specified exit status | This allows an attacker to mount a denial-of-service attack by automatically forcing the virtual machine to halt.
    shutdownHooks | Registration and cancellation of virtual-machine shutdown hooks | This allows an attacker to register a malicious shutdown hook that interferes with the clean shutdown of the virtual machine.
    setFactory | Setting of the socket factory used by ServerSocket or Socket, or of the stream handler factory used by URL | This allows code to set the actual implementation for the socket, server socket, stream handler, or RMI socket factory. An attacker may set a faulty implementation which mangles the data stream.
    setIO | Setting of System.out, System.in, and System.err | This allows changing the value of the standard system streams. An attacker may change System.in to monitor and steal user input, or may set System.err to a "null" OutputSteam, which would hide any error messages sent to System.err.
    modifyThread | stop, suspend, resume, setPriority, and setName methods | This allows an attacker to start or suspend any thread in the system.
    stopThread | Stopping of threads via calls to the Thread stop method | This allows code to stop any thread in the system provided that it is already granted permission to access that thread. This poses as a threat, because that code may corrupt the system by killing existing threads.
    modifyThreadGroup | Creation or modification of thread groups (adding a thread to a thread group during thread creation or calling the ThreadGroup destroy, resume, setDaemon, setMaxPriority, stop, and suspend methods) | This allows an attacker to create threads in thread groups or to create and modify thread groups (setting their run priority, for example).
    getProtectionDomain | Retrieval of the ProtectionDomain for a class | This allows code to obtain policy information for a particular code source. While obtaining policy information does not compromise the security of the system, it does give attackers additional information, such as local file names for example, to better aim an attack.
    readFileDescriptor | Reading of file descriptors | This would allow code to read the particular file associated with the file descriptor read. This is dangerous if the file contains confidential data.
    writeFileDescriptor | Writing to file descriptors | This allows code to write to a particular file associated with the descriptor. This is dangerous because it may allow malicous code to plant viruses or at the very least, fill up your entire disk.
    loadLibrary.{library name} | Dynamic linking of the specified library | It is dangerous to allow an applet permission to load native code libraries, because the Java security architecture is not designed to and does not prevent malicious behavior at the level of native code.
    accessClassInPackage.
    {package name}         		Access to the specified package via a class loader's loadClass method when that class loader calls the SecurityManager checkPackageAcesss method This gives code access to classes in packages to which it normally does not have access. Malicious code may use these classes to help in its attempt to compromise security in the system.
    defineClassInPackage.
    {package name}         		Definition of classes in the specified package, via a class loader's defineClass method when that class loader calls the SecurityManager checkPackageDefinition method. This grants code permission to define a class in a particular package. This is dangerous because malicious code with this permission may define rogue classes in trusted packages like java.security or java.lang, for example.
    accessDeclaredMembers | Warning: Extreme caution should be taken before granting this permission to code, for it provides access to the declared members of a class. | This grants code permission to query a class for its public, protected, default (package) access, and private fields and/or methods. Although the code would have access to the private and protected field and method names, it would not have access to the private/protected field data and would not be able to invoke any private methods. Nevertheless, malicious code may use this information to better aim an attack. Additionally, it may invoke any public methods and/or access public fields in the class. This could be dangerous if the code would normally not be able to invoke those methods and/or access the fields because it can't cast the object to the class/interface with those methods and fields.
    queuePrintJob | Initiation of a print job request | This could print sensitive information to a printer, or simply waste paper.

    NIO-Related Targets

    Two NIO-related RuntimePermission targets were added in the 1.4 release of the Java 2 SDK:
    selectorProvider
charsetProvider
    These RuntimePermissions are required to be granted to classes which subclass and implement java.nio.channel.spi.SelectorProvider or java.nio.charset.spi.CharsetProvider. The permission is checked during invocation of the abstract base class constructor. These permissions ensure trust in classes which implement these security-sensitive provider mechanisms.

    See java.nio.channels.spi.SelectorProvider and java.nio.channels.spi.CharsetProvider for more information.

    NetPermission

    A java.net.NetPermission is for various network permissions. A NetPermission contains a name but no actions list; you either have the named permission or you don't.

    The following table lists all the possible NetPermission target names, and for each provides a description of what the permission allows and a discussion of the risks of granting code the permission.

    java.net.NetPermission
    Target Name     		What the Permission Allows Risks of Allowing this Permission
    setDefaultAuthenticator | The ability to set the way authentication information is retrieved when a proxy or HTTP server asks for authentication | Malicious code can set an authenticator that monitors and steals user authentication input as it retrieves the input from the user.
    requestPasswordAuthentication | The ability to ask the authenticator registered with the system for a password | Malicious code may steal this password.
    specifyStreamHandler | The ability to specify a stream handler when constructing a URL | Malicious code may create a URL with resources that it would normally not have access to (like file:/foo/fum/), specifying a stream handler that gets the actual bytes from someplace it does have access to. Thus it might be able to trick the system into creating a ProtectionDomain/CodeSource for a class even though that class really didn't come from that location.

    SocketPermission

    A java.net.SocketPermission represents access to a network via sockets. A SocketPermission consists of a host specification and a set of "actions" specifying ways to connect to that host. The host is specified as

    host = (hostname | IPaddress)[:portrange]
portrange = portnumber | -portnumber | portnumber-[portnumber]

    The host is expressed as a DNS name, as a numerical IP address, or as "localhost" (for the local machine). The wildcard "*" may be included once in a DNS name host specification. If it is included, it must be in the leftmost position, as in "*.sun.com".

    The port or portrange is optional. A port specification of the form "N-", where N is a port number, signifies all ports numbered N and above, while a specification of the form "-N" indicates all ports numbered N and below.

    The possible ways to connect to the host are

    accept
connect
listen
resolve

    The "listen" action is only meaningful when used with "localhost". The "resolve" (resolve host/ip name service lookups) action is implied when any of the other actions are present.

    As an example of the creation and meaning of SocketPermissions, note that if you have the following entry in your policy file:

    grant signedBy "mrm" {
    permission java.net.SocketPermission "puffin.eng.sun.com:7777", "connect, accept";
};

    this causes the following permission object to be generated and granted to code signed by "mrm."

    p1 = new SocketPermission("puffin.eng.sun.com:7777", "connect,accept");

    p1 represents a permission allowing connections to port 7777 on puffin.eng.sun.com, and also accepting connections on that port.

    Similarly, if you have the following entry in your policy:

    grant signedBy "paul" {
    permission java.net.SocketPermission "localhost:1024-", "accept, connect, listen";
};

    this causes the following permission object to be generated and granted to code signed by "paul."

    p2 = new SocketPermission("localhost:1024-", "accept,connect,listen");

    p2 represents a permission allowing accepting connections on, connecting to, or listening on any port between 1024 and 65535 on the local host.

    Note: Granting code permission to accept or make connections to remote hosts may be dangerous because malevolent code can then more easily transfer and share confidential data among parties who may not otherwise have access to the data.

    SQLPermission

    The permission for which the SecurityManager will check when code that is running in an applet calls one of the setLogWriter methods. These methods include those in the following list.

    • DriverManager.setLogWriter
    • DriverManager.setLogStream (deprecated)
    • javax.sql.DataSource.setLogWriter
    • javax.sql.ConnectionPoolDataSource.setLogWriter
    • javax.sql.XADataSource.setLogWriter

    If there is no SQLPermission object, this method throws a java.lang.SecurityException as a runtime exception.

    A SQLPermission object contains a name (also referred to as a "target name") but no actions list; there is either a named permission or there is not. The target name is the name of the permission (see below). The naming convention follows the hierarchical property naming convention. In addition, an asterisk may appear at the end of the name, following a ".", or by itself, to signify a wildcard match. For example: loadLibrary.* or * is valid, but *loadLibrary or a*b is not valid.

    The following table lists all the possible SQLPermission target names. Currently, the only name allowed is setLog. The table gives a description of what the permission allows and a discussion of the risks of granting code the permission.

    Permission Target Name | What the Permission Allows | Risks of Allowing this Permission
    setLog | Setting of the logging stream | This is a dangerous permission to grant. The contents of the log may contain usernames and passwords, SQL statements, and SQL data.

    The person running an applet decides what permissions to allow and will run the Policy Tool to create an SQLPermission in a policy file. A programmer does not use a constructor directly to create an instance of SQLPermission but rather uses a tool.

    PropertyPermission

    A java.util.PropertyPermission is for property permissions.

    The name is the name of the property ("java.home", "os.name", etc). The naming convention follows the hierarchical property naming convention. Also, an asterisk may appear at the end of the name, following a ".", or by itself, to signify a wildcard match. For example: "java.*" or "*" is valid, "*java" or "a*b" is not valid.

    The actions to be granted are passed to the constructor in a string containing a list of zero or more comma-separated keywords. The possible keywords are "read" and "write". Their meaning is defined as follows:

    read | Permission to read. Allows System.getProperty to be called.
    write | Permission to write. Allows System.setProperty to be called.

    The actions string is converted to lowercase before processing.

    Care should be taken before granting code permission to access certain system properties. For example, granting permission to access the "java.home" system property gives potentially malevolent code sensitive information about the system environment (the location of the runtime environment's directory). Also, granting permission to access the "user.name" and "user.home" system properties gives potentially malevolent code sensitive information about the user environment (the user's account name and home directory).

    LoggingPermission

    A SecurityManager will check the java.util.logging.LoggingPermission object when code running with a SecurityManager calls one of the logging control methods (such as Logger.setLevel).

    Currently there is only one named LoggingPermission, "control". control grants the ability to control the logging configuration; for example by adding or removing Handlers, by adding or removing Filters, or by changing logging levels.

    Normally you do not create LoggingPermission objects directly; instead they are created by the security policy code based on reading the security policy file.

    SSLPermission

    The javax.net.ssl.SSLPermission class is for various network permissions. An SSLPermission contains a name (also referred to as a "target name") but no actions list; you either have the named permission or you don't.

    The target name is the name of the network permission (see below). The naming convention follows the hierarchical property naming convention. Also, an asterisk may appear at the end of the name, following a ".", or by itself, to signify a wildcard match. For example: "foo.*" or "*" is valid, "*foo" or "a*b" is not valid.

    The following table lists all the possible SSLPermission target names, and for each provides a description of what the permission allows and a discussion of the risks of granting code the permission.

    Permission Target Name | What the Permission Allows | Risks of Allowing this Permission
    setHostnameVerifier | The ability to set a callback which can decide whether to allow a mismatch between the host being connected to by an HttpsURLConnection and the common name field in server certificate. | Malicious code can set a verifier that monitors host names visited by HttpsURLConnection requests or that allows server certificates with invalid common names.
    getSSLSessionContext | The ability to get the SSLSessionContext of an SSLSession. | Malicious code may monitor sessions which have been established with SSL peers or might invalidate sessions to slow down performance.
    setDefaultSSLContext | The ability to set the default SSL context. | When applications use default SSLContext, by setting the default SSL context, malicious code may use unproved trust material, key material and random generator, or use dangerous SSL socket factory and SSL server socket factory.

    AuthPermission

    The javax.security.auth.AuthPermission class is for authentication permissions. An AuthPermission contains a name (also referred to as a "target name") but no actions list; you either have the named permission or you don't.

    Currently the AuthPermission object is used to guard access to the Subject, SubjectDomainCombiner, LoginContext and Configuration objects.

    The following table lists all the possible AuthPermission target names, and for each provides a description of what the permission allows and a discussion of the risks of granting code the permission.

    Permission Target Name | What the Permission Allows | Risks of Allowing this Permission
    doAs | Invocation of the Subject.doAs methods | This enables an application to invoke code (Actions) under the identity of any Subject specified to the doAs method.
    doAsPrivileged | Invocation of the Subject.doAsPrivileged methods | This enables an application to invoke code (Actions) under the identity of any Subject specified to the doAsPrivileged method. Additionally, the caller may remove itself from the call stack (and hence from subsequent security decisions) if it passes null as the AccessControlContext.
    getSubject | Retrieving the Subject from the provided AccessControlContext | This permits an application to gain access to an authenticated Subject. The application can then access the Subject's authenticated Principals and public credentials.
    getSubjectFromDomainCombiner | Retrieving the Subject from a SubjectDomainCombiner | This permits an application to gain access to the authenticated Subject associated with a SubjectDomainCombiner. The application can then access the Subject's authenticated Principals and public credentials.
    setReadOnly | Setting a Subject read-only | This permits an application to set a Subject's Principal, public credential and private credential sets to be read-only. This can be potentially used as a type of denial of service attack.
    modifyPrincipals | Make modifications to a Subject's Principal set | Access control decisions are based on the Principals associated with a Subject. This permission permits an application to make any modifications to a Subject's Principal set, thereby affecting subsequent security decisions.
    modifyPublicCredentials | Make modifications to a Subject's public credential set | This permission permits an application to add or remove public credentials from a Subject. This may affect code that relies on the proper set of private credentials to exist in that Subject.
    modifyPrivateCredentials | Make modifications to a Subject's private credential set | This permission permits an application to add or remove private credentials from a Subject. This may affect code that relies on the proper set of private credentials to exist in that Subject.
    refreshCredential | Refresh a credential Object that implements the Refreshable interface | This permission permits an application to refresh a credential that is intended to expire.
    destroyCredential | Destroy a credential Object that implements the Destroyable interface | This permission permits an application to potentially destroy a credential as a denial of service attack.
    createLoginContext.{name} | Instantiate a LoginContext with the specified name | For security purposes, an administrator might not want an application to be able to authenticate to any LoginModule. This permission permits an application to authenticate to the LoginModules configured for the specified name.
    getLoginConfiguration | Retrieve the system-wide login Configuration | Allows an application to determine all the LoginModules that are configured for every application in the system.
    getLoginConfiguration | Retrieve the system-wide login Configuration | Allows an application to determine all the LoginModules that are configured for every application in the system.
    setLoginConfiguration | Set the system-wide login Configuration | Allows an application to configure the LoginModules for every application in the system.
    createLoginConfiguration.{configuration type} | Obtain a Configuration object via Configuration.getInstance | Allows an application to see all the LoginModules that are specified in the configuration.
    refreshLoginConfiguration | Refresh the system-wide login Configuration | Allows an application to refresh the login Configuration.

    PrivateCredentialPermission

    The javax.security.auth.PrivateCredentialPermission class is used to protect access to private Credentials belonging to a particular Subject. The Subject is represented by a Set of Principals.

    The target name of this Permission specifies a Credential class name, and a Set of Principals. The only valid value for this Permission's actions is, "read". The target name must abide by the following syntax:

    CredentialClass {PrincipalClass "PrincipalName"}*
    For example, the following permission grants access to the com.sun.PrivateCredential owned by Subjects which have a com.sun.Principal with the name, "duke".

    Note: Although this example, as well as all the examples below, do not contain Codebase, SignedBy, or Principal information in the grant statement (for simplicity reasons), actual policy configurations should specify that information when appropriate.

    grant {
    permission javax.security.auth.PrivateCredentialPermission
             "com.sun.PrivateCredential com.sun.Principal \"duke\"",
             "read";
};
    If CredentialClass is "*", then access is granted to all private Credentials belonging to the specified Subject. If "PrincipalName" is "*", then access is granted to the specified Credential owned by any Subject that has the specified Principal (the actual PrincipalName doesn't matter). For example, the following grants access to the a.b.Credential owned by any Subject that has an a.b.Principal.
    grant {
    permission javax.security.auth.PrivateCredentialPermission
             "a.b.Credential a.b.Principal "*"",
             "read";
};
    If both the PrincipalClass and "PrincipalName" are "*", then access is granted to the specified Credential owned by any Subject. In addition, the PrincipalClass/PrincipalName pairing may be repeated:
    grant {
    permission javax.security.auth.PrivateCredentialPermission
             "a.b.Credential a.b.Principal "duke" c.d.Principal "dukette"",
             "read";
};
    The above code grants access to the private Credential, "a.b.Credential", belonging to a Subject with at least two associated Principals: "a.b.Principal" with the name, "duke", and "c.d.Principal", with the name, "dukette".

    DelegationPermission

    The javax.security.auth.kerberos.DelegationPermission class is used to restrict the usage of the Kerberos delegation model; ie, forwardable and proxiable tickets.

    The target name of this Permission specifies a pair of kerberos service principals. The first is the subordinate service principal being entrusted to use the Ticket Granting Ticket (TGT). The second service principal designates the target service the subordinate service principal is to interact with on behalf of the initiating KerberosPrincipal. This latter service principal is specified to restrict the use of a proxiable ticket.

    For example, to specify the "host" service use of a forwardable TGT, the target permission is specified as follows:

    DelegationPermission("\"host/foo.example.com@EXAMPLE.COM\" \"krbtgt/EXAMPLE.COM@EXAMPLE.COM\"");
    To give the "backup" service a proxiable NFS service ticket, the target permission might be specified:
    DelegationPermission("\"backup/bar.example.com@EXAMPLE.COM\" \"nfs/home.EXAMPLE.COM@EXAMPLE.COM\"");

    ServicePermission

    The javax.security.auth.kerberos.ServicePermission class is used to protect Kerberos services and the credentials necessary to access those services. There is a one to one mapping of a service principal and the credentials necessary to access the service. Therefore granting access to a service principal implicitly grants access to the credential necessary to establish a security context with the service principal. This applies regardless of whether the credentials are in a cache or acquired via an exchange with the KDC. The credential can be either a ticket granting ticket, a service ticket or a secret key from a key table.

    A ServicePermission contains a service principal name and a list of actions which specify the context the credential can be used within.

    The service principal name is the canonical name of the KereberosPrincipal supplying the service, that is the KerberosPrincipal represents a Kerberos service principal. This name is treated in a case sensitive manner.

    Granting this permission implies that the caller can use a cached credential (Ticket Granting Ticket, service ticket or secret key) within the context designated by the action. In the case of the TGT, granting this permission also implies that the TGT can be obtained by an Authentication Service exchange.

    The possible actions are:

    initiate | Allows the caller to use the credential to initiate a security context with a service principal.
    accept | Allows the caller to use the credential to accept security context as a particular principal.

    For example, to specify the permission to access to the TGT to initiate a security context the permission is constructed as follows:
         ServicePermission("krbtgt/EXAMPLE.COM@EXAMPLE.COM", "initiate");
    To obtain a service ticket to initiate a context with the "host" service the permission is constructed as follows:
    ServicePermission("host/foo.example.com@EXAMPLE.COM", "initiate");
    For a Kerberized server the action is "accept". For example, the permission necessary to access and use the secret key of the Kerberized "host" service (telnet and the likes) would be constructed as follows:
    ServicePermission("host/foo.example.com@EXAMPLE.COM", "accept");

    AudioPermission

    The AudioPermission class represents access rights to the audio system resources. An AudioPermission contains a target name but no actions list; you either have the named permission or you don't.

    The target name is the name of the audio permission (see the table below). The names follow the hierarchical property-naming convention. Also, an asterisk can be used to represent all the audio permissions.

    The following table lists the possible AudioPermission target names. For each name, the table provides a description of exactly what that permission allows, as well as a discussion of the risks of granting code the permission.

    Permission Target Name | What the Permission Allows | Risks of Allowing this Permission
    play | Audio playback through the audio device or devices on the system. Allows the application to obtain and manipulate lines and mixers for audio playback (rendering). | In some cases use of this permission may affect other applications because the audio from one line may be mixed with other audio being played on the system, or because manipulation of a mixer affects the audio for all lines using that mixer.
    record | Audio recording through the audio device or devices on the system. Allows the application to obtain and manipulate lines and mixers for audio recording (capture). | In some cases use of this permission may affect other applications because manipulation of a mixer affects the audio for all lines using that mixer. This permission can enable an applet or application to eavesdrop on a user.

    Methods and the Permissions They Require

    The following table contains a list of all the methods that require permissions, and for each tells which SecurityManager method it calls and which permission is checked for by the default implementation of that SecurityManager method.

    Thus, with the default SecurityManager method implementations, a call to a method in the left-hand column can only be successful if the permission specified in the corresponding entry in the right-hand column is allowed by the policy currently in effect. For example, the following row:

    Method SecurityManager Method Called Permission
    java.awt.Toolkit
    getSystemEventQueue();
            checkAwtEventQueueAccess java.awt.AWTPermission "accessEventQueue";

    specifies that a call to the getSystemEventQueue method in the java.awt.Toolkit class results in a call to the checkAwtEventQueueAccess SecurityManager method, which can only be successful if the following permission is granted to code on the call stack:

      java.awt.AWTPermission "accessEventQueue";

    The convention of:

    Method SecurityManager Method Called Permission
     some.package.class
   public static void someMethod(String foo);
            checkXXX SomePermission "{foo}";

    means the runtime value of foo replaces the string {foo} in the permission name.

    As an example, here is one table entry:

    Method SecurityManager Method Called Permission
    java.io.FileInputStream
    FileInputStream(String name)
            checkRead(String) java.io.FilePermission "{name}", "read";

    If the FileInputStream method (in this case, a constructor) is called with "/test/MyTestFile" as the name argument, as in

      FileInputStream("/test/MyTestFile");

    then in order for the call to succeed, the following permission must be set in the current policy, allowing read access to the file "/test/MyTestFile":

      java.io.FilePermission "/test/MyTestFile", "read";

    More specifically, the permission must either be explicitly set, as above, or implied by another permission, such as the following:

      java.io.FilePermission "/test/*", "read";

    which allows read access to any files in the "/test" directory.

    In some cases, a term in braces is not exactly the same as the name of a specific method argument but is meant to represent the relevant value. Here is an example:

    Method SecurityManager Method Called Permission
    java.net.DatagramSocket
  public synchronized void
      receive(DatagramPacket p);
             checkAccept({host}, {port}) java.net.SocketPermission "{host}:{port}", "accept";

    Here, the appropriate host and port values are calculated by the receive method and passed to checkAccept.

    In most cases, just the name of the SecurityManager method called is listed. Where the method is one of multiple methods of the same name, the argument types are also listed, for example for checkRead(String) and checkRead(FileDescriptor). In other cases where arguments may be relevant, they are also listed.

    The following table is ordered by package name. That is, the methods in classes in the java.awt package are listed first, followed by methods in classes in the java.io package, and so on.

    Methods and the Permissions They Require
    Method SecurityManager Method Called Permission
    java.awt.Graphics2d
  public abstract void
    setComposite(Composite comp)
             checkPermission java.awt.AWTPermission "readDisplayPixels" if this Graphics2D context is drawing to a Component on the display screen and the Composite is a custom object rather than an instance of the AlphaComposite class. Note: The setComposite method is actually abstract and thus can't invoke security checks. Each actual implementation of the method should call the java.lang.SecurityManager checkPermission method with a java.awt.AWTPermission("readDisplayPixels") permission under the conditions noted.
    java.awt.Robot
  public Robot()
  public Robot(GraphicsDevice screen)
             checkPermission java.awt.AWTPermission "createRobot"
    java.awt.Toolkit
  public void addAWTEventListener(
          AWTEventListener listener,
          long eventMask)
  public void removeAWTEventListener(
     AWTEventListener listener)
             checkPermission java.awt.AWTPermission "listenToAllAWTEvents"
    java.awt.Toolkit
  public abstract PrintJob getPrintJob(
           Frame frame, String jobtitle,
           Properties props)
             checkPrintJobAccess

    java.lang.RuntimePermission "queuePrintJob"

    Note: The getPrintJob method is actually abstract and thus can't invoke security checks. Each actual implementation of the method should call the java.lang.SecurityManager checkPrintJobAccess method, which is successful only if the java.lang.RuntimePermission "queuePrintJob" permission is currently allowed.

    java.awt.Toolkit
  public abstract Clipboard
                    getSystemClipboard()
             checkSystemClipboardAccess

    java.awt.AWTPermission "accessClipboard"

    Note: The getSystemClipboard method is actually abstract and thus can't invoke security checks. Each actual implementation of the method should call the java.lang.SecurityManager checkSystemClipboardAccess method, which is successful only if the java.awt.AWTPermission "accessClipboard" permission is currently allowed.

    java.awt.Toolkit
  public final EventQueue
               getSystemEventQueue()
             checkAwtEventQueueAccess java.awt.AWTPermission "accessEventQueue"
    java.awt.Window
  Window()
             checkTopLevelWindow If java.awt.AWTPermission "showWindowWithoutWarningBanner" is set, the window will be displayed without a banner warning that the window was created by an applet. It it's not set, such a banner will be displayed.
    java.beans.Beans
  public static void setDesignTime(
                 boolean isDesignTime)
  public static void setGuiAvailable(
                 boolean isGuiAvailable)

java.beans.Introspector
  public static synchronized void
    setBeanInfoSearchPath(String path[])

java.beans.PropertyEditorManager
  public static void registerEditor(
                 Class targetType,
                 Class editorClass)
  public static synchronized void
    setEditorSearchPath(String path[])
             checkPropertiesAccess java.util.PropertyPermission "*", "read,write"
    java.io.File
  public boolean delete()
  public void deleteOnExit()
             checkDelete(String) java.io.FilePermission "{name}", "delete"
    java.io.FileInputStream
  FileInputStream(FileDescriptor fdObj)
             checkRead(FileDescriptor) java.lang.RuntimePermission "readFileDescriptor"
    java.io.FileInputStream
  FileInputStream(String name)
  FileInputStream(File file)

java.io.File
  public boolean exists()
  public boolean canRead()
  public boolean isFile()
  public boolean isDirectory()
  public boolean isHidden()
  public long lastModified()
  public long length()
  public String[] list()
  public String[] list(
           FilenameFilter filter)
  public File[] listFiles()
  public File[] listFiles(
           FilenameFilter filter)
  public File[] listFiles(
           FileFilter filter)

java.io.RandomAccessFile
  RandomAccessFile(String name, String mode)
  RandomAccessFile(File file, String mode)
      (where mode is "r" in both of these)
             checkRead(String) java.io.FilePermission "{name}", "read"
    java.io.FileOutputStream
  FileOutputStream(FileDescriptor fdObj)
             checkWrite(FileDescriptor) java.lang.RuntimePermission "writeFileDescriptor"
    java.io.FileOutputStream
  FileOutputStream(File file)
  FileOutputStream(String name)
  FileOutputStream(String name,
                   boolean append)

java.io.File
  public boolean canWrite()
  public boolean createNewFile()
  public static File createTempFile(
          String prefix, String suffix)
  public static File createTempFile(
          String prefix,  String suffix,
          File directory)
  public boolean mkdir()
  public boolean mkdirs()
  public boolean renameTo(File dest)
  public boolean setLastModified(long time)
  public boolean setReadOnly()
             checkWrite(String) java.io.FilePermission "{name}", "write"
    java.io.ObjectInputStream
  protected final boolean
    enableResolveObject(boolean enable);

java.io.ObjectOutputStream
  protected final boolean
    enableReplaceObject(boolean enable)
             checkPermission java.io.SerializablePermission "enableSubstitution"
    java.io.ObjectInputStream
  protected ObjectInputStream()

java.io.ObjectOutputStream
  protected ObjectOutputStream()
             checkPermission java.io.SerializablePermission "enableSubclassImplementation"
    java.io.RandomAccessFile
  RandomAccessFile(String name, String mode)
      (where mode is "rw")
             checkRead(String) and checkWrite(String) java.io.FilePermission "{name}", "read,write"
    java.lang.Class
  public static Class forName(
     String name, boolean initialize,
     ClassLoader loader)
             checkPermission If loader is null, and the caller's class loader is not null, then java.lang.RuntimePermission("getClassLoader")
    java.lang.Class
  public ClassLoader getClassLoader()
             checkPermission If the caller's class loader is null, or is the same as or an ancestor of the class loader for the class whose class loader is being requested, no permission is needed. Otherwise,
    java.lang.RuntimePermission "getClassLoader"
    is required.
    java.lang.Class
  public Class[] getDeclaredClasses()
  public Field[] getDeclaredFields()
  public Method[] getDeclaredMethods()
  public Constructor[]
    getDeclaredConstructors()
  public Field getDeclaredField(
                       String name)
  public Method getDeclaredMethod(...)
  public Constructor
    getDeclaredConstructor(...)
             checkMemberAccess(this, Member.DECLARED) and, if this class is in a package, checkPackageAccess({pkgName}) Default checkMemberAccess does not require any permissions if "this" class's classloader is the same as that of the caller. Otherwise, it requires java.lang.RuntimePermission "accessDeclaredMembers". If this class is in a package, java.lang.RuntimePermission "accessClassInPackage.{pkgName}" is also required.
    java.lang.Class
  public Class[] getClasses()
  public Field[] getFields()
  public Method[] getMethods()
  public Constructor[] getConstructors()
  public Field getField(String name)
  public Method getMethod(...)
  public Constructor getConstructor(...)
             checkMemberAccess(this, Member.PUBLIC) and, if class is in a package, checkPackageAccess({pkgName}) Default checkMemberAccess does not require any permissions when the access type is Member.PUBLIC. If this class is in a package, java.lang.RuntimePermission "accessClassInPackage.{pkgName}" is required.
    java.lang.Class
   public ProtectionDomain
            getProtectionDomain()
             checkPermission java.lang.RuntimePermission "getProtectionDomain"
    java.lang.ClassLoader
  ClassLoader()
  ClassLoader(ClassLoader parent)
             checkCreateClassLoader java.lang.RuntimePermission "createClassLoader"
    java.lang.ClassLoader
  public static ClassLoader
           getSystemClassLoader()
  public ClassLoader getParent()
             checkPermission If the caller's class loader is null, or is the same as or an ancestor of the class loader for the class whose class loader is being requested, no permission is needed. Otherwise,
    java.lang.RuntimePermission "getClassLoader"
    is required.
    java.lang.Runtime
  public Process exec(String command)
  public Process exec(String command,
                      String envp[])
  public Process exec(String cmdarray[])
  public Process exec(String cmdarray[],
                      String envp[])
             checkExec java.io.FilePermission "{command}", "execute"
    java.lang.Runtime
  public void exit(int status)
  public static void
      runFinalizersOnExit(boolean value)
java.lang.System
  public static void exit(int status)
  public static void
      runFinalizersOnExit(boolean value)
             checkExit(status) where status is 0 for runFinalizersOnExit java.lang.RuntimePermission "exitVM.{status}"
    java.lang.Runtime
  public void addShutdownHook(Thread hook)
  public boolean removeShutdownHook(Thread hook)
             checkPermission java.lang.RuntimePermission "shutdownHooks"
    java.lang.Runtime
  public void load(String lib)
  public void loadLibrary(String lib)
java.lang.System
  public static void load(String filename)
  public static void loadLibrary(
                          String libname)
             checkLink({libName}) where {libName} is the lib, filename or libname argument java.lang.RuntimePermission "loadLibrary.{libName}"
    java.lang.SecurityManager methods
             checkPermission See the next table.
    java.lang.System
  public static Properties
      getProperties()
  public static void
      setProperties(Properties props)
             checkPropertiesAccess java.util.PropertyPermission "*", "read,write"
    java.lang.System
  public static String
      getProperty(String key)
  public static String
      getProperty(String key, String def)
             checkPropertyAccess java.util.PropertyPermission "{key}", "read"
    java.lang.System
  public static void setIn(InputStream in)
  public static void setOut(PrintStream out)
  public static void setErr(PrintStream err)
             checkPermission java.lang.RuntimePermission "setIO"
    java.lang.System
  public static String
    setProperty(String key, String value)
             checkPermission java.util.PropertyPermission "{key}", "write"
    java.lang.System
  public static synchronized void
    setSecurityManager(SecurityManager s)
             checkPermission java.lang.RuntimePermission "setSecurityManager"
    java.lang.Thread
  public ClassLoader getContextClassLoader()
             checkPermission If the caller's class loader is null, or is the same as or an ancestor of the context class loader for the thread whose context class loader is being requested, no permission is needed. Otherwise,
    java.lang.RuntimePermission "getClassLoader"
    is required.
    java.lang.Thread
  public void setContextClassLoader
                      (ClassLoader cl)
             checkPermission java.lang.RuntimePermission "setContextClassLoader"
    java.lang.Thread
  public final void checkAccess()
  public void interrupt()
  public final void suspend()
  public final void resume()
  public final void setPriority
                     (int newPriority)
  public final void setName(String name)
  public final void setDaemon(boolean on)
             checkAccess(this) java.lang.RuntimePermission "modifyThread"
    java.lang.Thread
  public static int
      enumerate(Thread tarray[])
             checkAccess({threadGroup}) java.lang.RuntimePermission "modifyThreadGroup"
    java.lang.Thread
  public final void stop()
             checkAccess(this). Also checkPermission if the current thread is trying to stop a thread other than itself. java.lang.RuntimePermission "modifyThread".
    Also java.lang.RuntimePermission "stopThread" if the current thread is trying to stop a thread other than itself.
    java.lang.Thread
  public final synchronized void
                    stop(Throwable obj)
             checkAccess(this). Also checkPermission if the current thread is trying to stop a thread other than itself or obj is not an instance of ThreadDeath. java.lang.RuntimePermission "modifyThread".
    Also java.lang.RuntimePermission "stopThread" if the current thread is trying to stop a thread other than itself or obj is not an instance of ThreadDeath.
    java.lang.Thread
  Thread()
  Thread(Runnable target)
  Thread(String name)
  Thread(Runnable target, String name)

java.lang.ThreadGroup
  ThreadGroup(String name)
  ThreadGroup(ThreadGroup parent,
              String name)
             checkAccess({parentThreadGroup}) java.lang.RuntimePermission "modifyThreadGroup"
    java.lang.Thread
  Thread(ThreadGroup group, ...)

java.lang.ThreadGroup
  public final void checkAccess()
  public int enumerate(Thread list[])
  public int enumerate(Thread list[],
      boolean recurse)
  public int enumerate(ThreadGroup list[])
  public int enumerate(ThreadGroup list[],
      boolean recurse)
  public final ThreadGroup getParent()
  public final void
      setDaemon(boolean daemon)
  public final void setMaxPriority(int pri)
  public final void suspend()
  public final void resume()
  public final void destroy()
             checkAccess(this) for ThreadGroup methods, or checkAccess(group) for Thread methods java.lang.RuntimePermission "modifyThreadGroup"
    java.lang.ThreadGroup
  public final void interrupt()
             checkAccess(this) Requires java.lang.RuntimePermission "modifyThreadGroup".
    Also requires java.lang.RuntimePermission "modifyThread", since the java.lang.Thread interrupt() method is called for each thread in the thread group and in all of its subgroups. See the Thread interrupt() method.
    java.lang.ThreadGroup
  public final void stop()
             checkAccess(this) Requires java.lang.RuntimePermission "modifyThreadGroup".
    Also requires java.lang.RuntimePermission "modifyThread" and possibly java.lang.RuntimePermission "stopThread", since the java.lang.Thread stop() method is called for each thread in the thread group and in all of its subgroups. See the Thread stop() method.
    java.lang.reflect.AccessibleObject
  public static void setAccessible(...)
  public void setAccessible(...)
             checkPermission java.lang.reflect.ReflectPermission "suppressAccessChecks"
    java.net.Authenticator
  public static PasswordAuthentication
       requestPasswordAuthentication(
             InetAddress addr,
             int port,
             String protocol,
             String prompt,
             String scheme)
             checkPermission java.net.NetPermission "requestPasswordAuthentication"
    java.net.Authenticator
  public static void
      setDefault(Authenticator a)
             checkPermission java.net.NetPermission "setDefaultAuthenticator"
    java.net.MulticastSocket
  public void
      joinGroup(InetAddress mcastaddr)
  public void
      leaveGroup(InetAddress mcastaddr)
             checkMulticast(InetAddress) java.net.SocketPermission( mcastaddr.getHostAddress(), "accept,connect")
    java.net.DatagramSocket
  public void send(DatagramPacket p)
             checkMulticast(p.getAddress()) or checkConnect(
    p.getAddress().getHostAddress(), p.getPort())     		if (p.getAddress().isMulticastAddress()) {
    java.net.SocketPermission(
    (p.getAddress()).getHostAddress(), "accept,connect")
    }
    else {
    port = p.getPort();
    host = p.getAddress().getHostAddress();
    if (port == -1) java.net.SocketPermission "{host}","resolve";
    else java.net.SocketPermission "{host}:{port}","connect"
    }
    java.net.MulticastSocket
  public synchronized void
      send(DatagramPacket p, byte ttl)
             checkMulticast(p.getAddress(), ttl) or checkConnect(
    p.getAddress().getHostAddress(), p.getPort())     		if (p.getAddress().isMulticastAddress()) {
    java.net.SocketPermission(
    (p.getAddress()).getHostAddress(), "accept,connect")
    }
    else {
    port = p.getPort();
    host = p.getAddress().getHostAddress();
    if (port == -1) java.net.SocketPermission "{host}","resolve";
    else java.net.SocketPermission "{host}:{port}","connect"
    }
    java.net.InetAddress
  public String getHostName()
  public static InetAddress[]
                  getAllByName(String host)
  public static InetAddress getLocalHost()

java.net.DatagramSocket
  public InetAddress getLocalAddress()
             checkConnect({host}, -1) java.net.SocketPermission "{host}", "resolve"
    java.net.ServerSocket
  ServerSocket(...)

java.net.DatagramSocket
  DatagramSocket(...)

java.net.MulticastSocket
  MulticastSocket(...)
             checkListen({port}) if (port == 0) java.net.SocketPermission "localhost:1024-","listen";
    else java.net.SocketPermission "localhost:{port}","listen"
    java.net.ServerSocket
  public Socket accept()
  protected final void implAccept(Socket s)
             checkAccept({host}, {port}) java.net.SocketPermission "{host}:{port}", "accept"
    java.net.ServerSocket
  public static synchronized void
      setSocketFactory(...)

java.net.Socket
  public static synchronized void
      setSocketImplFactory(...)

java.net.URL
  public static synchronized void
      setURLStreamHandlerFactory(...)

 java.net.URLConnection
   public static synchronized void
      setContentHandlerFactory(...)
   public static void
      setFileNameMap(FileNameMap map)

java.net.HttpURLConnection
   public static void
       setFollowRedirects(boolean set)

java.rmi.activation.ActivationGroup
  public static synchronized
        ActivationGroup createGroup(...)
  public static synchronized void
      setSystem(ActivationSystem system)

java.rmi.server.RMISocketFactory
   public synchronized static void
      setSocketFactory(...)
             checkSetFactory java.lang.RuntimePermission "setFactory"
    java.net.Socket
  Socket(...)
             checkConnect({host}, {port}) java.net.SocketPermission "{host}:{port}", "connect"
    java.net.DatagramSocket
  public synchronized void
      receive(DatagramPacket p)
             checkAccept({host}, {port}) java.net.SocketPermission "{host}:{port}", "accept"
    java.net.URL
  URL(...)
             checkPermission java.net.NetPermission "specifyStreamHandler"
    java.net.URLClassLoader
  URLClassLoader(...)
             checkCreateClassLoader java.lang.RuntimePermission "createClassLoader"
    java.security.AccessControlContext
  public AccessControlContext(AccessControlContext acc,
                DomainCombiner combiner)
  public DomainCombiner getDomainCombiner()
             checkPermission java.security.SecurityPermission "createAccessControlContext"
    java.security.Identity
  public void addCertificate(...)
             checkSecurityAccess(
    "addIdentityCertificate")     		java.security.SecurityPermission "addIdentityCertificate"
    java.security.Identity
  public void removeCertificate(...)
             checkSecurityAccess(
    "removeIdentityCertificate")     		java.security.SecurityPermission "removeIdentityCertificate"
    java.security.Identity
  public void setInfo(String info)
             checkSecurityAccess(
    "setIdentityInfo")     		java.security.SecurityPermission "setIdentityInfo"
    java.security.Identity
  public void setPublicKey(PublicKey key)
             checkSecurityAccess(
    "setIdentityPublicKey")     		java.security.SecurityPermission "setIdentityPublicKey"
    java.security.Identity
  public String toString(...)
             checkSecurityAccess(
    "printIdentity")     		java.security.SecurityPermission "printIdentity"
    java.security.IdentityScope
  protected static void setSystemScope()
             checkSecurityAccess(
    "setSystemScope")     		java.security.SecurityPermission "setSystemScope"
    java.security.Permission
  public void checkGuard(Object object)
            checkPermission(this) this Permission object is the permission checked
    java.security.Policy
  public static Policy getPolicy()
             checkPermission java.security.SecurityPermission "getPolicy"
    java.security.Policy
  public static void
      setPolicy(Policy policy)
             checkPermission java.security.SecurityPermission "setPolicy"
    java.security.Policy
  public static Policy
      getInstance(String type, SpiParameter params)
      getInstance(String type, SpiParameter params, String provider)
      getInstance(String type, SpiParameter params, Provider provider)
            checkPermission java.security.SecurityPermission "createPolicy.{type}"
    java.security.Provider
  public synchronized void clear()
             checkSecurityAccess(
    "clearProviderProperties."+{name})     		java.security.SecurityPermission "clearProviderProperties.{name}" where name is the provider name.
    java.security.Provider
  public synchronized Object
      put(Object key, Object value)
             checkSecurityAccess(
    "putProviderProperty."+{name})     		java.security.SecurityPermission "putProviderProperty.{name}" where name is the provider name.
    java.security.Provider
  public synchronized Object
      remove(Object key)
             checkSecurityAccess(
    "removeProviderProperty."+{name})     		java.security.SecurityPermission "removeProviderProperty.{name}" where name is the provider name.
    java.security.SecureClassLoader
  SecureClassLoader(...)
             checkCreateClassLoader java.lang.RuntimePermission "createClassLoader"
    java.security.Security
  public static void getProperty(String key)
             checkPermission java.security.SecurityPermission "getProperty.{key}"
    java.security.Security
  public static int
      addProvider(Provider provider)
  public static int
      insertProviderAt(Provider provider,
                       int position);
             checkSecurityAccess(
    "insertProvider."+provider.getName())     		java.security.SecurityPermission "insertProvider.{name}"
    java.security.Security
  public static void
      removeProvider(String name)
             checkSecurityAccess(
    "removeProvider."+name)     		java.security.SecurityPermission "removeProvider.{name}"
    java.security.Security
  public static void
    setProperty(String key, String datum)
             checkSecurityAccess(
    "setProperty."+key)     		java.security.SecurityPermission "setProperty.{key}"
    java.security.Signer
  public PrivateKey getPrivateKey()
             checkSecurityAccess(
    "getSignerPrivateKey")     		java.security.SecurityPermission "getSignerPrivateKey"
    java.security.Signer
  public final void
      setKeyPair(KeyPair pair)
            checkSecurityAccess(
    "setSignerKeypair")     		java.security.SecurityPermission "setSignerKeypair"
    java.sql.DriverManager
  public static synchronized void
      setLogWriter(PrintWriter out)
            checkPermission java.sql.SQLPermission "setLog"
    java.sql.DriverManager
  public static synchronized void
      setLogStream(PrintWriter out)
            checkPermission java.sql.SQLPermission "setLog"
    java.util.Locale
  public static synchronized void
            setDefault(Locale newLocale)
             checkPermission java.util.PropertyPermission "user.language","write"
    java.util.zip.ZipFile
  ZipFile(String name)
             checkRead java.io.FilePermission "{name}","read"
    javax.security.auth.Subject
    public static Subject getSubject(final AccessControlContext acc)
             checkPermission javax.security.auth.AuthPermission "getSubject"
    javax.security.auth.Subject
    public void setReadOnly()
             checkPermission javax.security.auth.AuthPermission "setReadOnly"
    javax.security.auth.Subject
    public static Object doAs(final Subject subject,
                final PrivilegedAction action)
             checkPermission javax.security.auth.AuthPermission "doAs"
    javax.security.auth.Subject
    public static Object doAs(final Subject subject,
                final PrivilegedExceptionAction action)
    throws java.security.PrivilegedActionException
             checkPermission javax.security.auth.AuthPermission "doAs"
    javax.security.auth.Subject
    public static Object doAsPrivileged(final Subject subject,
                final PrivilegedAction action,
                final AccessControlContext acc)
             checkPermission javax.security.auth.AuthPermission "doAsPrivileged"
    javax.security.auth.Subject
    public static Object doAsPrivileged(final Subject subject,
                final PrivilegedExceptionAction action,
                final AccessControlContext acc)
    throws java.security.PrivilegedActionException
             checkPermission javax.security.auth.AuthPermission "doAsPrivileged"
    javax.security.auth.SubjectDomainCombiner
    public Subject getSubject()
             checkPermission javax.security.auth.AuthPermission "getSubjectFromDomainCombiner"
    javax.security.auth.SubjectDomainCombiner
    public Subject getSubject()
             checkPermission javax.security.auth.AuthPermission "getSubjectFromDomainCombiner"
    javax.security.auth.login.LoginContext
    public LoginContext(String name)
    throws LoginException
             checkPermission javax.security.auth.AuthPermission "createLoginContext.{name}"
    javax.security.auth.login.LoginContext
    public LoginContext(String name,
            Subject subject)
     throws LoginException
             checkPermission javax.security.auth.AuthPermission "createLoginContext.{name}"
    javax.security.auth.login.LoginContext
    public LoginContext(String name,
            CallbackHandler callbackHandler)
     throws LoginException
             checkPermission javax.security.auth.AuthPermission "createLoginContext.{name}"
    javax.security.auth.login.LoginContext
    public LoginContext(String name,
            Subject subject,
            CallbackHandler callbackHandler)
     throws LoginException
             checkPermission javax.security.auth.AuthPermission "createLoginContext.{name}"
    javax.security.auth.login.Configuration
    public static Configuration getConfiguration()
             checkPermission javax.security.auth.AuthPermission "getLoginConfiguration"
    javax.security.auth.login.Configuration
    public static void setConfiguration(Configuration configuration)
             checkPermission javax.security.auth.AuthPermission "setLoginConfiguration"
    javax.security.auth.login.Configuration
    public static void refresh()
             checkPermission javax.security.auth.AuthPermission "refreshLoginConfiguration"
    javax.security.auth.login.Configuration
  public static Configuration
      getInstance(String type, SpiParameter params)
      getInstance(String type, SpiParameter params, String provider)
      getInstance(String type, SpiParameter params, Provider provider)
            checkPermission javax.security.auth.AuthPermission "createLoginConfiguration.{type}"

    java.lang.SecurityManager Method Permission Checks

    This table shows which permissions are checked for by the default implementations of the java.lang.SecurityManager methods.

    Each of the specified check methods calls the SecurityManager checkPermission method with the specified permission, except for the checkConnect and checkRead methods that take a context argument. Those methods expect the context to be an AccessControlContext and they call the context's checkPermission method with the specified permission.

    Method | Permission
    public void checkAccept(String host, int port); | java.net.SocketPermission "{host}:{port}", "accept";
    public void checkAccess(Thread g); | java.lang.RuntimePermission "modifyThread");
    public void checkAccess(ThreadGroup g); | java.lang.RuntimePermission "modifyThreadGroup");
    public void checkAwtEventQueueAccess(); | java.awt.AWTPermission "accessEventQueue";
    public void checkConnect(String host, int port); if (port == -1) java.net.SocketPermission "{host}","resolve";
    else java.net.SocketPermission "{host}:{port}","connect";
    public void checkConnect(String host, int port, Object context); if (port == -1) java.net.SocketPermission "{host}","resolve";
    else java.net.SocketPermission "{host}:{port}","connect";
    public void checkCreateClassLoader(); | java.lang.RuntimePermission "createClassLoader";
    public void checkDelete(String file); | java.io.FilePermission "{file}", "delete";
    public void checkExec(String cmd); if cmd is an absolute path: java.io.FilePermission "{cmd}", "execute";
    else java.io.FilePermission "-", "execute";
    public void checkExit(int status); | java.lang.RuntimePermission "exitVM.{status}";
    public void checkLink(String lib); | java.lang.RuntimePermission "loadLibrary.{lib}";
    public void checkListen(int port); if (port == 0) java.net.SocketPermission "localhost:1024-","listen";
    else java.net.SocketPermission "localhost:{port}","listen";
    public void checkMemberAccess(Class clazz, int which);
    if (which != Member.PUBLIC) {
  if (currentClassLoader() != clazz.getClassLoader()) {
    checkPermission(
      new java.lang.RuntimePermission("accessDeclaredMembers"));
  }
}
    public void checkMulticast(InetAddress maddr); | java.net.SocketPermission(maddr.getHostAddress(),"accept,connect");
    public void checkMulticast(InetAddress maddr, byte ttl); | java.net.SocketPermission(maddr.getHostAddress(),"accept,connect");
    public void checkPackageAccess(String pkg); | java.lang.RuntimePermission "accessClassInPackage.{pkg}";
    public void checkPackageDefinition(String pkg); | java.lang.RuntimePermission "defineClassInPackage.{pkg}";
    public void checkPrintJobAccess(); | java.lang.RuntimePermission "queuePrintJob";
    public void checkPropertiesAccess(); | java.util.PropertyPermission "*", "read,write";
    public void checkPropertyAccess(String key); | java.util.PropertyPermission "{key}", "read,write";
    public void checkRead(FileDescriptor fd); | java.lang.RuntimePermission "readFileDescriptor";
    public void checkRead(String file); | java.io.FilePermission "{file}", "read";
    public void checkRead(String file, Object context); | java.io.FilePermission "{file}", "read";
    public void checkSecurityAccess(String action); | java.security.SecurityPermission "{action}";
    public void checkSetFactory(); | java.lang.RuntimePermission "setFactory";
    public void checkSystemClipboardAccess(); | java.awt.AWTPermission "accessClipboard";
    public boolean checkTopLevelWindow(Object window); | java.awt.AWTPermission "showWindowWithoutWarningBanner";
    public void checkWrite(FileDescriptor fd); | java.lang.RuntimePermission "writeFileDescriptor";
    public void checkWrite(String file); | java.io.FilePermission "{file}", "write";
    public SecurityManager(); | java.lang.RuntimePermission "createSecurityManager";

    Copyright © 1997-2002 Sun Microsystems, Inc. All Rights Reserved.

    Please send comments to: java-security@sun.com

            Sun
    Java Software


PKI Enhancements in J2SE 5

Public Key Infrastructure (PKI) Enhancements
for J2SE 5

1. Introduction

This document describes the PKI enhancements that have been made to J2SE 5.0 and how to use them. Please send feedback on these enhancements to java-security@sun.com.

The following PKI enhancements were made in version 5.0 of the Java 2 platform:

  • On-Line Certificate Service Protocol (OCSP)
  • API support for indirect certificate revocation lists (CRLs)
  • Clarified distinguished name usage in CertPath API
  • Passed PKIX RFC 3280 compliance test suite
  • Made java.security.cert.PolicyQualifierInfo non-final
  • Added more CA certificates
  • PKCS#11 Support
  • Enhanced PKCS#12 implementation
  • Enhanced TrustManager support

On-Line Certificate Service Protocol (OCSP)

Client-side support for the On-Line Certificate Status Protocol (OCSP) as defined in RFC 2560 has been added in this release. OCSP checking is controlled by the following five, new security properties:

Property Name | Description
ocsp.enable | This property's value is either true or false. If true, OCSP checking is enabled when doing certificate revocation checking; if false or not set, OCSP checking is disabled.
ocsp.responderURL This property's value is a URL that identifies the location of the OCSP responder. Here is an example.
ocsp.responderURL=http://ocsp.example.net:80

By default, the location of the OCSP responder is determined implicitly from the certificate being validated. The property is used when the Authority Information Access extension (defined in RFC 3280) is absent from the certificate or when it requires overriding.

ocsp.responderCertSubjectName This property's value is the subject name of the OCSP responder's certificate. Here is an example.
ocsp.responderCertSubjectName="CN=OCSP Responder, O=XYZ Corp"

By default, the certificate of the OCSP responder is that of the issuer of the certificate being validated. This property identifies the certificate of the OCSP responder when the default does not apply. Its value is a string distinguished name (defined in RFC 2253) which identifies a certificate in the set of certificates supplied during cert path validation. In cases where the subject name alone is not sufficient to uniquely identify the certificate, then both the ocsp.responderCertIssuerName and ocsp.responderCertSerialNumber properties must be used instead. When this property is set, then those two properties are ignored.

ocsp.responderCertIssuerName This property's value is the issuer name of the OCSP responder's certificate. Here is an example.
ocsp.responderCertIssuerName="CN=Enterprise CA, O=XYZ Corp"

By default, the certificate of the OCSP responder is that of the issuer of the certificate being validated. This property identifies the certificate of the OCSP responder when the default does not apply. Its value is a string distinguished name (defined in RFC 2253) which identifies a certificate in the set of certificates supplied during cert path validation. When this property is set then the ocsp.responderCertSerialNumber property must also be set. Note that this property is ignored when the ocsp.responderCertSubjectName property has been set.

ocsp.responderCertSerialNumber This property's value is the serial number of the OCSP responder's certificate Here is an example.
ocsp.responderCertSerialNumber=2A:FF:00

By default, the certificate of the OCSP responder is that of the issuer of the certificate being validated. This property identifies the certificate of the OCSP responder when the default does not apply. Its value is a string of hexadecimal digits (colon or space separators may be present) which identifies a certificate in the set of certificates supplied during cert path validation. When this property is set then the ocsp.responderCertIssuerName property must also be set. Note that this property is ignored when the ocsp.responderCertSubjectName property has been set.

These properties may be set either staticly in the Java runtime's $JAVA_HOME/jre/lib/security/java.security file, or dynamically using the java.security.Security.setProperty() method.

By default, OCSP checking is not enabled. It is enabled by setting the ocsp.enable property to "true". Use of the remaining properties is optional. Note that enabling OCSP checking only has an effect if revocation checking has also been enabled. Revocation checking is enabled via the PKIXParameters.setRevocationEnabled() method.

OCSP checking works in conjunction with Certificate Revocation Lists (CRLs) during revocation checking. Below is a summary of the interaction of OCSP and CRLs. Failover to CRLs occurs only if an OCSP problem is encountered. Failover does not occur if the OCSP responder confirms either that the certificate has been revoked or that it has not been revoked.

PKIXParameters RevocationEnabled (default=true) | ocsp.enable (default=false) | Behavior
true true Revocation checking using OCSP,
failover to using CRLs
true | false | Revocation checking using CRLs only
false | true | No revocation checking
false | false | No revocation checking

See the Java Certification Path API Programming Guide for details about revocation checking and Certificate Revocation Lists.

API Support for Indirect Certificate Revocation Lists (CRLs)

Indirect CRLs are certificate revocation lists that include entries for certificates from issuers other than the CRL issuer. In J2SE 5, two changes were made to the CertPath API to better support indirect CRLs.

The java.security.cert.X509CRL class has a method, getRevokedCertificate(BigInteger), for getting a CRL entry given a certificate's serial number. However, for an indirect CRL, the serial number does not uniquely identify a certificate. In J2SE 5, an overloaded form of getRevokedCertificate() was added for getting a CRL entry given a certificate.

Prior to J2SE 5, the java.security.cert.X509CRLEntry class did not have any method for obtaining the issuer of the certificate described by the CRL entry. In J2SE 5, a method, getCertificateIssuer(), was added to address this gap.

Clarified Distinguished Name Usage in CertPath API

The CertPath API has constructors and methods that accept byte arrays and strings to represent distinguished names. However, in some classes, it lacked similar overloaded forms that accept X500Principal to represent distinguished names. Use of X500Principal to represent a distinguished name is preferred because it is more efficient and suitably typed. The following methods were added to the CertPath API.
  • java.security.cert.TrustAnchor
    public TrustAnchor(X500Principal caPrincipal, PublicKey pubKey,
    byte[] nameConstraints);
public final X500Principal getCA();
  • java.security.cert.X509CertSelector
    public X500Principal getIssuer();
public void setIssuer(X500Principal issuer);
public X500Principal getSubject();
public void setSubject(X500Principal subject);
  • java.security.cert.X509CRLSelector
    public void setIssuers(Collection issuers);
public void addIssuer(X500Principal issuer);
public Collection getIssuers();

The methods getSubjectDN() and getIssuerDN() in the X509Certificate class and getIssuerDN() in the X509CRL class are problematic because their specifications say that they return a distinguished name without being specific about its format. Consequently, different implementations may return implementation-specific objects, resulting in applications that have poor interoperability or are non-portable. Use of these methods are strongly discouraged. Instead, applications should use the methods that return an instance of X500Principal.

  • getSubjectX500Principal()
  • getIssuerX500Principal()
  • getIssuerX500Principal().

Passed PKIX Complaince Test Suite

The CertPath implementation in the SUN provider in J2SE 5 passed the Public Key Interoperability Test Suite (PKITS).

Made java.security.cert.PolicyQualifierInfo non-final

 Prior to J2SE 5, java.security.cert.PolicyQualifierInfo was a final class. This prevented users from creating subclasses and adding methods that return fields of different types of policy qualifiers. In J2SE 5, this class was made non-final, but the following methods were made final to preserve the class' immutability contract.
public final String getPolicyQualifierId()
public final byte[] getEncoded()
public final byte[] getPolicyQualifier()

Added More CA Certificates

The following CA (Certification Authority) certificates were added to the cacerts file in the lib/security directory of the Java installation.
  Alias name: equifaxsecureebusinessca1
  Owner: CN=Equifax Secure eBusiness CA-1, O=Equifax Secure Inc., C=US

  Alias name: equifaxsecureca
  Owner: OU=Equifax Secure Certificate Authority, O=Equifax, C=US

  Alias name: geotrustglobalca
  Owner: CN=GeoTrust Global CA, O=GeoTrust Inc., C=US

  Alias name: equifaxsecureglobalebusinessca1
  Owner: CN=Equifax Secure Global eBusiness CA-1, O=Equifax Secure Inc., C=US

  Alias name: equifaxsecureebusinessca2
  Owner: OU=Equifax Secure eBusiness CA-2, O=Equifax Secure, C=US

  Alias name: verisignclass1g3ca
  Owner: CN=VeriSign Class 1 Public Primary Certification Authority - G3, OU="(c)
  1999 VeriSign, Inc. - For authorized use only", OU=VeriSign Trust Network,
  O="VeriSign, Inc.", C=US
  Issuer: CN=VeriSign Class 1 Public Primary Certification Authority - G3, OU="(c)
  1999 VeriSign, Inc.
  - For authorized use only", OU=VeriSign Trust Network, O="VeriSign, Inc.", C=US

  Alias name: verisignclass2g2ca
  Owner: OU=VeriSign Trust Network, OU="(c) 1998 VeriSign, Inc. - For authorized
  use only", OU=Class 2
  Public Primary Certification Authority - G2, O="VeriSign, Inc.", C=US
  Issuer: OU=VeriSign Trust Network, OU="(c) 1998 VeriSign, Inc. - For authorized
  use only", OU=Class 2 Public Primary Certification Authority - G2, O="VeriSign,
  Inc.", C=US

  Alias name: verisignclass3g3ca
  Owner: CN=VeriSign Class 3 Public Primary Certification Authority - G3, OU="(c)
  1999 VeriSign, Inc. - For authorized use only", OU=VeriSign Trust Network,
  O="VeriSign, Inc.", C=US
  Issuer: CN=VeriSign Class 3 Public Primary Certification Authority - G3, OU="(c)
  1999 VeriSign, Inc.
  - For authorized use only", OU=VeriSign Trust Network, O="VeriSign, Inc.", C=US

  Alias name: verisignclass1g2ca
  Owner: OU=VeriSign Trust Network, OU="(c) 1998 VeriSign, Inc. - For authorized
  use only", OU=Class 1
  Public Primary Certification Authority - G2, O="VeriSign, Inc.", C=US
  Issuer: OU=VeriSign Trust Network, OU="(c) 1998 VeriSign, Inc. - For authorized
  use only", OU=Class 1 Public Primary Certification Authority - G2, O="VeriSign,
  Inc.", C=US

  Alias name: verisignclass2g3ca
  Owner: CN=VeriSign Class 2 Public Primary Certification Authority - G3, OU="(c)
  1999 VeriSign, Inc. - For authorized use only", OU=VeriSign Trust Network,
  O="VeriSign, Inc.", C=US
  Issuer: CN=VeriSign Class 2 Public Primary Certification Authority - G3, OU="(c)
  1999 VeriSign, Inc.
  - For authorized use only", OU=VeriSign Trust Network, O="VeriSign, Inc.", C=US

  Alias name: verisignclass3g2ca
  Owner: OU=VeriSign Trust Network, OU="(c) 1998 VeriSign, Inc. - For authorized
  use only", OU=Class 3
  Public Primary Certification Authority - G2, O="VeriSign, Inc.", C=US
  Issuer: OU=VeriSign Trust Network, OU="(c) 1998 VeriSign, Inc. - For authorized
  use only", OU=Class 3 Public Primary Certification Authority - G2, O="VeriSign,
  Inc.", C=US

PKCS#11 Support

The Cryptographic Token Interface Standard, PKCS#11, is a standard that defines native programming interfaces to cryptographic tokens, such as hardware cryptographic accelerators and Smartcards. In J2SE 5, support was added for PKCS#11. This means that PKI applications can use PKCS#11 tokens (such as Smartcards) as keystores. See the PKCS#11 Guide for more information on how to use PKCS#11 tokens as keystores.

Enhanced PKCS#12 Implementation

 PKCS#12 (Personal Information Exchange Syntax Standard) specifies a portable format for storage and/or transport of a user's private keys, certificates, miscellaneous secrets, and other items. J2SE 1.4.x provided read-only support for PKCS#12 keystores, and only for a small number of protection algorithms. The enhanced PKCS#12 keystore in J2SE 5 supports more protection algorithms (such as those supported by popular browsers) and also writing/updates to the keystore. This improves interoperability of PKCS#12 keystores imported/exported by Java SE, browsers, and other security applications.

Enhanced TrustManager Support

 By default, the SunJSSE provider in J2SE 5 uses a X509 PKIX-compliant trust manager. See the What's New in the JSSE Reference Guide for details.


Policy Tool - Policy File Creation and Management Tool

Policy File Creation and Management

Creates and modifies the external policy configuration files that define your installation's Java security policy.

Table of Contents

Introduction

Policy Tool Usage
Starting Policy Tool
Creating a new Policy File
Opening a Different Policy File
Specifying the Keystore
Adding a New Policy Entry
Adding a New Principal
Editing a Principal
Removing a Principal
Adding a New Permission
Editing a Permission
Removing a Permission
Completing the Addition of a Policy Entry
Editing a Policy Entry
Removing a Policy Entry
Saving the Policy File
Exiting the Policy Tool
Viewing the Warning Log

Examples
Starting Creation of the User Policy File
Adding a Policy Entry
Specifying a Keystore
Adding a Policy Entry with a SignedBy Alias
Adding a Policy Entry with a Principal
Saving the User Policy File
Exiting Policy Tool

See Also

Introduction

The policy for a Java runtime (specifying which permissions are available for code from various sources, when executing as various principals) is represented by a Policy object. The default Policy implementation obtains its information from static ASCII policy configuration files.

A policy file can be composed via a simple text editor, or via the graphical Policy Tool utility described in this document. Using the Policy Tool saves typing and eliminates the need for you to know the required policy file syntax thus reducing errors.

The Policy Tool Usage section describes how to use the Policy Tool to create and modify policy files.

The Examples section provides detailed examples of the use of Policy Tool.

The See Also section provides links to related documentation.

Policy Tool Usage

Starting Policy Tool

To start Policy Tool, simply type the following at the command line.

  policytool

This brings up the "Policy Tool" window.

Whenever Policy Tool is started, it tries to fill in this window with policy information from what is sometimes referred to as the "user policy file". The user policy file is by default a file named .java.policy in your home directory. If Policy Tool cannot find the user policy file, it reports the situation and displays a blank "Policy Tool" window (that is, a window with headings and buttons but no data in it):

Blank Policy Tool window

You can then proceed to either open whatever policy file you want to work on or create a new policy file, by adding policy entries, optionally specifying a keystore, and saving the file).

The first time you run the Policy Tool, there will not be a user policy file (unless you created one manually).

Creating a new Policy File

To create a new policy file, start by simply selecting the New command from the File menu. This will close the currently open policy file (if any, after first prompting you to save it if needed) and bring up a new policy tool window, that is, a window with headings and buttons but no data in it.

Please Note: this is not necessary the first time you run the Policy Tool. Since the tool tries to open the user policy file and one doesn't exist yet (unless it was created manually), the tool will bring up a window without any data in it.

Once you have a new policy tool window, you can then create the policy entries, and specify the keystore (if any of the policy entries specify a keystore alias). At any point, you can save the policy file.

Opening a Different Policy File

To work on a different policy file than the one currently being worked on (if any), use the Open command in the File menu.

This will close the currently open policy file (if any, after first prompting you to save it if needed) and will present you with an Open dialog, which you can use to navigate the directory structure until you get to the directory containing the policy file you want to work on. Select that file, then select the OK button.

The "Policy Tool" window will then be filled in with information from the policy file, including the policy file name, the keystore URL (if any), and the CodeBase, SignedBy and Principal parts of each policy entry in the policy file.

Specifying the Keystore

To specify the keystore containing the key information for the aliases specified in the SignedBy parts of policy entries, select the Edit command in the Keystore menu.

This brings up a dialog box in which you specify the new keystore URL and optionally the keystore type.

As an example, to specify the keystore named "mykeystore" in the /tests/ directory, type the following file: URL into the text box labeled "New KeyStore URL".

  file:/tests/mykeystore

To also specify that the keystore type is "JKS" (the proprietary keystore type supported by Sun Microsystems), type the following into the text box labeled "New KeyStore Type".

  JKS

When you are done specifying the keystore URL and type (if any), select OK (or you can select Cancel to cancel the operation). If you didn't cancel, the text box labeled "Keystore:" is now filled in with the keystore URL and type.

Adding a New Policy Entry

To add a new policy entry, select the Add Policy Entry button in the main "Policy Tool" window.

This brings up a "Policy Entry" dialog box:

Blank Add Entry Dialog

Using this dialog box, you specify

  • an optional CodeBase entry indicating the URL location where the code originates from. For example, to indicate code from the local /JavaSoft/TESTS/ directory, type the following file URL into the CodeBase text box:
      file:/JavaSoft/TESTS/
  • an optional SignedBy entry indicating the alias name from the keystore used to reference the signer whose private key was used to sign the code. For example, to indicate the alias named "duke", simply type the following into the SignedBy text box:
      duke
  • an optional Principals entry indicating the list of principals that the code has to be executed as in order for the permission(s) to be granted. See Adding a New Principal.
  • one or more permission entries indicating which permissions are granted to the code from the source indicated by the CodeBase and SignedBy values (or to any code if no such values are specified) when running as the specified principals in the Principals list. See Adding a New Permission.

The SignedBy value is a string alias that is mapped (using the keystore) to a set of public keys that are associated with the signers. These keys are used to verify that classes from the specified code source are really signed by these signers.

The SignedBy value can be a comma-separated string containing names of multiple signers, an example of which is "Adam,Eve,Charles", which means "signed by Adam and Eve and Charles" (i.e., the relationship is AND, not OR).

The SignedBy value is optional in that, if it is omitted, it signifies "any signer," or in other words, it doesn't matter whether the code is signed or not. Similarly, if there is no CodeBase entry, then it signifies "any code"; it doesn't matter where the code originates from.

Thus, if there is no CodeBase entry, then all code signed by the specified alias(es) will be granted the specified permissions. If there is no SignedBy entry, then all code from the specified CodeBase will be granted the specified permissions, regardless of whether the code is signed or not, and by whom. If there is no CodeBase entry, and also no SignedBy entry, then all code will be granted the specified permissions.

Note: The exact meaning of a CodeBase value depends on the characters at the end. A CodeBase with a trailing "/" matches all class files (not JAR files) in the specified directory. A CodeBase with a trailing "/*" matches all files (both class and JAR files) contained in that directory. A CodeBase with a trailing "/-" matches all files (both class and JAR files) in the directory and recursively all files in subdirectories contained in that directory.

The Principals entry specifies a list of "principal values". Each principal value specifies a principal_type/principal_name pair which must be present within the executing thread's principal set. The Principals entry is optional in that, if it is omitted, it signifies "any principals".

If there is no principal_type specified and the principal_name is a quoted string, the string is treated as a keystore alias when the policy file is processed at runtime. The keystore is consulted and queried (via the alias) for an X509 Certificate. If one is found, the principal type is automatically assumed to be javax.security.auth.x500.X500Principal, and the actual principal name is assumed to be the subject distinguished name from the certificate. If an X509 Certificate mapping is not found, the entire policy entry granting permissions to the specified principal is ignored.

Adding a New Principal

To add a new principal, select the Add Principal button in the "Policy Entry" dialog box. This brings up the "Principals" dialog box:

Blank Add Principals Dialog

To add the principal:

  1. Type or select a principal type.

    The drop-down list labeled "Principal Type:" contains a list of built-in principal types. If you want such a type, select it from the list, and the complete principal type name appears in the text box to the right of the drop-down list.

    If you instead want to specify a principal type defined by you or others, type the principal type into the text box.

  2. Type a principal name.

    Type the principal name directly into the text box to the right of the "Principal Name:" text box. For example, to specify the principal named duke, type

    duke

When you are done specifying the principal information, select the OK button (or Cancel to cancel). The new principal appears in a line in the "Principals" entry.

You can then add additional principals by following the same sequence of steps. Or you can edit or remove an existing principal.

Editing a Principal

To edit an existing principal, select the line for that principal in the "Principals:" entry, then select the Edit Principal button. Alternatively, you can simply double-click the line for that principal.

This brings up the same type of "Principals" dialog box as appears when you are adding a new principal, except in this case the dialog box is filled in with the existing principal information. To change the information, either make new selections from the drop-down lists or replace the information in the text boxes.

When you are done, select the OK button (or Cancel to cancel changes). The Principals:" entry now shows the principal with your modifications.

Removing a Principal

To remove an existing principal, select the line for that principal in the "Principals:" entry, then select the Remove Principal button.

Adding a New Permission

To add a new permission, select the Add Permission button in the "Policy Entry" dialog box. This brings up the "Permissions" dialog box:

Blank Add Permissions Dialog

To add the permission:

  1. Type or select a permission type.

    The drop-down list labeled "Permission:" contains a list of built-in permission types. If you want such a type, select it from the list, and the complete permission type name appears in the text box to the right of the drop-down list.

    If you instead want to specify a permission type defined by you or others, type the permission type into the text box.

  2. Type or select a permission target name.

    If you selected a built-in permission from the "Permission:" drop-down list, and permissions of that type have specific target name values, then the drop-down list labeled "Target Name:" contains a list of those values, from which you can choose.

    In some cases, where the target name possibilities are infinite but there are some built-in target name specifications that have special meaning, such target names will appear in the drop-down list. For example, the special target name of "<<All Files>>" will appear in the list for File Permissions.

    To specify a target name not available in the drop-down list, type the target name directly into the text box to the right of the "Target Name:" drop-down list. For example, to specify the file named data in the /JavaSoft/ptTest/ directory, type

      /JavaSoft/ptTest/data
  3. Type or select one or more actions, if actions are relevant.

    Some permissions just have a target name, but no actions. For such permissions, leave the text box to the right of the "Actions:" drop-down list blank. (It will automatically be darkened and unavailable for this type of built-in permission.)

    For permissions requiring action specifications, type the comma-separated list of actions into the text box, or select them from the drop-down list. For example, to specify both read and write access to a file specified for a File Permission, first select read (or write, order doesn't matter) from the list. The word "read" appears in the text box. Then select write, and the word "write" will be appended, preceded by a comma and a space.

  4. Type a SignedBy alias into the text box to the right of the "Signed By" label, if required. The SignedBy value for a permission entry is optional. If present, it indicates a signed permission. That is, the permission class itself must be signed by the given alias(es) in order for the permission to be granted.

When you are done specifying the permission information, select the OK button (or Cancel to cancel). The new permission appears in a line in the "Policy Entry" dialog.

You can then add additional permissions by following the same sequence of steps. Or you can edit an existing permission or remove a permission.

Editing a Permission

To edit an existing permission, select the line for that permission in the "Policy Entry" dialog box, then select the Edit Permission button. Alternatively, you can simply double-click the line for that permission.

This brings up the same type of "Permissions" dialog box as appears when you are adding a new permission, except in this case the dialog box is filled in with the existing permission information. To change the information, either make new selections from the drop-down lists or replace the information in the text boxes.

When you are done, select the OK button (or Cancel to cancel changes). The "Policy Entry" dialog now shows the permission with any modifications you made.

Removing a Permission

To remove an existing permission, select the line for that permission in the "Policy Entry" dialog box, then select the Remove Permission button.

Completing the Addition of a Policy Entry

Once you are done adding a policy entry, select the Done button in the "Policy Entry" dialog, or Cancel to cancel.

If you selected Done, the "Policy Tool" window now contains a line representing the policy entry. The line contains the CodeBase, SignedBy and Principals information (if any). If none was specified in the "Policy Entry" dialog, just

  CodeBase <ALL>

appears.

Note: a warning is displayed upon closing the policy entry if it contains any SignedBy aliases that don't yet exist in your keystore. Select OK and make a note to create such an alias, or edit the policy entry to fix the alias if was wrong.

Editing a Policy Entry

To edit an existing policy entry, select the line for that entry in the main "Policy Tool" window, then select the Edit Policy Entry button. Alternatively, you can simply double-click the line for that entry.

This brings up the same type of "Policy Entry" dialog box as appears when you are adding a new policy entry, except in this case the dialog box is filled in with the existing policy entry information. To change the information, simply retype it (for the CodeBase and SignedBy values) or use the buttons (for the Principals and Permissions values).

When you are done, select the Done button (or Cancel to cancel).

Removing a Policy Entry

To delete a policy entry from the policy file, select the line for that entry in the main "Policy Tool" window, then select the Remove Policy Entry button.

The complete policy entry is displayed, and you can then either select OK to remove the entry, or Cancel to keep it.

Saving the Policy File

To save changes to an existing policy file, simply select the Save command in the File menu.

To save a new policy file you've been creating, or to copy an existing policy file to a new policy file with a different name, select the Save As command from the File menu. This brings up the Save As dialog box.

Navigate the directory structure to get to the directory in which you want to save the policy file. Type the desired file name, then select the OK button. The policy file is now saved, and its name and path are shown in the text box labeled "Policy File:"

Exiting the Policy Tool

To exit Policy Tool, select the Exit command from the File menu.

Viewing the Warning Log

If Policy Tool ever reports that warnings have been stored in the Warning Log, you can view the log by selecting the View Warning Log command in the File menu.

For example, if you have a policy file with a Keystore URL specifying a keystore that doesn't yet exist, you will get such a warning at various times, e.g., when you open the file. You can continue to work on the policy file even if warnings exist.

Examples

The following examples show how to

  • create the user policy file from scratch
  • add a policy entry
  • specify a keystore
  • add a policy entry for signed code
  • add a policy entry for authenticated code
  • save the user policy file, and
  • exit the Policy Tool

Starting Creation of the User Policy File

Initially, there is no user policy file (unless you created one manually). So to create the user policy file, first simply start Policy Tool by typing the following at the command line.

  policytool

This brings up the "Policy Tool" window.

Whenever Policy Tool is started, it tries to fill in this window with policy information from what is sometimes referred to as the "user policy file". The user policy file is by default a file named .java.policy in your home directory. If Policy Tool cannot find the user policy file, it reports the situation and displays a blank "Policy Tool" window (that is, a window with headings and buttons but no data in it):

Blank Policy Tool window

You can now create the user policy file by adding entries and saving the file.

Adding a Policy Entry

Suppose you want to grant all classes from the /tests/ directory permission to read the file named mydata in the /temp/data/ directory. To do so, first select the Add Policy Entry button in the main "Policy Tool" window.

This brings up a "Policy Entry" dialog box:

Blank Add Entry Dialog

Using this dialog box, type the file URL

  file:/tests/

into the CodeBase text box.

Leave the SignedBy text box blank, since you aren't requiring the code to be signed.

Leave the Principals list blank, since you aren't requiring the code to be authenticated.

To add the permission, select the Add Permission button. This brings up the "Permissions" dialog box:

Blank Add Permissions Dialog

To add the permission:

  1. Select "File Permission" from the "Permission:" drop-down list. The complete permission type name (java.io.FilePermission) now appears in the text box to the right of the drop-down list.
  2. Type the following in the text box to the right of the list labeled "Target Name:":
      /temp/data/mydata
  3. Specify read access by either selecting "read" from the "Actions:" drop-down list or directly typing "read" into the text box to the right of the "Actions:" drop-down list.

Now the "Permission" dialog box looks like the following:

First File Permission

When you are done specifying the permission information, select the OK button. The new permission appears in a line in the "Policy Entry" dialog.

First Policy Entry

You are now done specifying this policy entry, so select the Done button. The "Policy Tool" window now contains a line representing the policy entry. The line just contains the CodeBase value:

Policy Tool with one CodeBase

Specifying a Keystore

Suppose you also want to grant any code from the URL "http://java.sun.com/" and signed by the alias "duke" read access to all files in the /tmp/ directory. Suppose you also want to give such code permission to initiate outgoing socket connections to any hosts. You need to do two things:

  1. Specify the keystore containing the alias, and
  2. Create the policy entry granting the permissions.

To specify the keystore containing the key information for the aliases specified in any SignedBy parts of policy entries, select the Edit command in the Keystore menu of the main "Policy Tool" window.

This brings up a dialog box in which you specify the new keystore URL and optionally the keystore type.

As an example, to specify the keystore named "mykeystore" in the /tests/ directory, type the following file: URL into the text box labeled "New KeyStore URL":

  file:/tests/mykeystore

If the keystore type is the default type, as specified by the "keystore.type" property value in the security properties file, you don't need to type a "New KeyStore Type" value. The default value of that property is "JKS" (the proprietary keystore type supported by Sun Microsystems).

To specify the keystore type, type its value into the text box labeled "New KeyStore Type." For example, to indicate that the keystore type is "JKS" type

  JKS

The result is:

When you are done specifying the keystore URL and type, select OK. The text box labeled "Keystore:" is now filled in with the URL and type.

Next, you need to specify the policy entry:

Adding a Policy Entry with a SignedBy Alias

Select the Add Policy Entry button in the main "Policy Tool" window. This brings up the "Policy Entry" dialog box. Type the following into the the CodeBase text box:

  http://java.sun.com/*

The "*" indicates that both class and JAR files in the specified directory are to be considered to match this CodeBase.

Now, type the following alias into the SignedBy text box:

  duke

Leave the Principals list blank, since you aren't requiring the code to be authenticated.

To add the first permission, select the Add Permission button. This brings up the "Permissions" dialog box. Do the following

  1. Select "File Permission" from the "Permission:" drop-down list. The complete permission type name (java.io.FilePermission) now appears in the text box to the right of the drop-down list.
  2. Type the following in the text box to the right of the list labeled "Target Name:" to specify all files in the /tmp/ directory:
      /tmp/*
  3. Specify read access by selecting "read" from the "Actions:" drop-down list.

Now the "Permissions" dialog box looks like the following:

Second File Permission

Select the OK button. The new permission appears in a line in the "Policy Entry" dialog.

Now you need to add the other permission. Select the Add Permission button. In the "Permissions" dialog box, do the following

  1. Select "Socket Permission" from the "Permission:" drop-down list. The complete permission type name (java.net.SocketPermission) now appears in the text box to the right of the drop-down list.
  2. Type the following in the text box to the right of the list labeled "Target Name:" to specify all hosts:
      *
  3. Specify permission to make connections by selecting "connect" from the "Actions:" drop-down list.

Now the "Permissions" dialog box looks like the following:

Select the OK button. The new permission appears in a line in the "Policy Entry" dialog.

Policy Entry with Two Permissions

You are now done specifying this policy entry, so select the Done button in the "Policy Entry" dialog. The "Policy Tool" window now contains a line representing the policy entry, showing the CodeBase, SignedBy and Principals values.

Policy Tool with Two Entries

Adding a Policy Entry with a Principal

Suppose you want to grant the principal whose X500 name is

CN=Duke,OU=JavaSoft,O=Sun Microsystems,C=US

permission to write to the /tmp/ directory.

Select the Add Policy Entry button in the main "Policy Tool" window. This brings up the "Policy Entry" dialog box.

Leave the CodeBase text box blank since you aren't limiting where the code comes from.

Leave the SignedBy text box blank since you aren't requiring the code to be signed.

Select the Add Principal button. In the "Principals" dialog box, do the following

  1. Select "X500Principal" from the "Principal Type:" drop-down list. The complete principal type name (com.sun.security.auth.X500Principal) now appears in the text box to the right of the drop-down list.
  2. Type the following in the text box to the right of the list labeled "Principal Name:" to specify an X500 name for the X500Principal:
    CN=Duke,OU=JavaSoft,O=Sun Microsystems,C=US

Now the "Principals" dialog box looks like the following:

Select the OK button. The new principal appears in a line in the "Principals" list.

Policy Entry with One Principal

To add the permission, select the Add Permission button. This brings up the "Permissions" dialog box. Do the following

  1. Select "File Permission" from the "Permission:" drop-down list. The complete permission type name (java.io.FilePermission) now appears in the text box to the right of the drop-down list.
  2. Type the following in the text box to the right of the list labeled "Target Name:" to specify all files in the /tmp/ directory:
      /tmp/*
  3. Specify write access by first selecting "write" from the "Actions:" drop-down list.

Select the OK button. The new permission appears in a line in the "Policy Entry" dialog.

Policy Entry with One Principal and one Permission

You are now done specifying this policy entry, so select the Done button in the "Policy Entry" dialog. The "Policy Tool" window now contains a line representing the policy entry, showing the CodeBase, SignedBy and Principals values.

Policy Tool with Three Entries

Saving the User Policy File

Let's assume you want to save the policy file you've been creating with the default name (.java.policy) in the default location (your home directory).

To save the user policy file, select the Save As command from the File menu. This brings up the Save As dialog box.

Navigate the directory structure to get to your home directory. Type

  .java.policy

(note the initial period) as the file name, then select the OK button. The policy file is now saved, and its name and path are shown in the text box labeled "Policy File:".

Policy Tool with Three Entries, Keystore, and Policy File Name

Exiting Policy Tool

When you want to exit Policy Tool, do so by selecting the Exit command from the File menu.

See Also

  • Permissions in the Java ™ Development Kit
  • Default Policy Information and Policy File Syntax
  • keytool tool man page
  • Security Architecture Specification
  • The Security trail of the Java Tutorial for examples of the use of the security tools including Policy Tool

Copyright © 2006 Sun Microsystems, Inc. All Rights Reserved.

 Sun
Java Software


Privileged Block API

API for Privileged Blocks

Document revision 1.6

Overview

This document provides background information about what "privileged" code is and what it is used for, followed by illustrations of the use of the API, with special attention to issues of:
  • returning values
  • type safety
  • exception handling
  • reflection

Background: What It Means to Have "Privileged" Code

The policy for an SDK installation specifies what permissions -- which types of system resource accesses -- are allowed for code from specified code sources. A "code source" (of type CodeSource) essentially consists of the code location (URL) and a reference to the certificate(s) containing the public key(s) corresponding to the private key(s) used to sign the code (if it was signed).

The policy is represented by a Policy object. More specifically, it is represented by a Policy subclass providing an implementation of the abstract methods in the Policy class (which is in the java.security package).

The source location for the policy information utilized by the Policy object is up to the Policy implementation. The Policy reference implementation obtains its information from policy configuration files. See Default Policy Implementation and Policy File Syntax for information about the Policy reference implementation and the syntax that must be used in policy files it reads. For information about using the Policy Tool to create a policy file (without needing to know the required syntax), see the Policy Tool documentation (for Solaris) (for Windows).

A "protection domain" encompasses a CodeSource and the permissions granted to code from that CodeSource, as determined by the security policy currently in effect. Thus, classes signed by the same keys and from the same URL are placed in the same domain, and a class belongs to one and only one protection domain. Classes that have the same permissions but are from different code sources belong to different domains.

Today all code shipped as part of the SDK is considered system code and run inside the unique system domain. System code automatically has all permissions.

Each applet or application runs in its appropriate domain, determined by its code source. In order for an applet (or an application running under a security manager) to be allowed to perform a secured action (such as reading or writing a file), the applet or application must be granted permission for that particular action.

More specifically, whenever a resource access is attempted, all code traversed by the execution thread up to that point must have permission for that resource access, unless some code on the thread has been marked as "privileged". That is, suppose access control checking occurs in a thread of execution that has a chain of multiple callers. (Think of this as multiple method calls that potentially cross the protection domain boundaries.) When the AccessController checkPermission method is invoked by the most recent caller, the basic algorithm for deciding whether to allow or deny the requested access is as follows:

If the code for any caller in the call chain does not have the requested permission, AccessControlException is thrown, unless the following is true - a caller whose code is granted the said permission has been marked as "privileged" (see below) and all parties subsequently called by this caller (directly or indirectly) all have the said permission.

Marking code as "privileged" enables a piece of trusted code to temporarily enable access to more resources than are available directly to the code that called it. This is necessary in some situations. For example, an application may not be allowed direct access to files that contain fonts, but the system utility to display a document must obtain those fonts, on behalf of the user. In order to do this, the system utility becomes privileged while obtaining the fonts.

Using the doPrivileged API

The use of the "privileged" feature is described in the following sections.

No return value, no exception thrown

If you don't need to return a value from within the "privileged" block, your call to doPrivileged can look like the following:

   somemethod() {
        ...normal code here...
        AccessController.doPrivileged(new PrivilegedAction() {
            public Object run() {
                // privileged code goes here, for example:
                System.loadLibrary("awt");
                return null; // nothing to return
            }
        });
       ...normal code here...
  }

The AccessController.doPrivileged method takes an object of type java.security.PrivilegedAction and invokes its run method in privileged mode. The implementation guarantees that privileges will be revoked after the run method is executed, even if execution of doPrivileged is interrupted by an asynchronous exception.

PrivilegedAction is an interface with a single method, named run, that returns an Object. The above example shows creation of an implementation of that interface using an anonymous inner class; a concrete implementation of the run method is supplied. When the call to doPrivileged is made, an instance of the PrivilegedAction implementation is passed to it. The doPrivileged method calls the run method from the PrivilegedAction implementation after enabling privileges, and returns the run method's return value as the doPrivileged return value (which is ignored in this example).

Note that depending on what "privileged code" actually consisted of, you might have to make some changes due to the way inner classes work. For example, if "privileged code" throws an exception or attempts to access local variables then you will have to make some changes, as shown in subsequent sections of this document.

You can also call doPrivileged without using an anonymous inner class, as in:

    somemethod() {
        ...normal code here...
        MyAction mya = new MyAction();
        // become privileged:
        AccessController.doPrivileged(mya);
       ...normal code here...
    }

    class MyAction implements PrivilegedAction {
        public MyAction() {};
        public Object run() {
            // privileged code goes here, for example:
            System.loadLibrary("awt");
            return null; // nothing to return
        }
    }

Be very careful in your use of the "privileged" construct, and always remember to make the privileged code section as small as possible, that is, try and limit the code within the run method to only the code that needs to be run with privileges, and do more general things outside the run method. Also note that the call to doPrivileged should be made in the code that wants to enable its privileges. Do not be tempted to write a utility class that itself calls doPrivileged as that could lead to security holes. You can write utility classes for PrivilegedAction classes though, as shown in the example above.

Returning values

If you need to return a value, you can do something like the following:

   somemethod() {
        ...normal code here...
        String user = (String) AccessController.doPrivileged(
          new PrivilegedAction() {
            public Object run() {
                return System.getProperty("user.name");
            }
          }
        );
        ...normal code here...
  }

Note that this usage requires a dynamic cast on the value returned by doPrivileged. An alternative is to use a final local variable:

   somemethod() {
        ...normal code here...
        final String user[] = {null};
        AccessController.doPrivileged(
          new PrivilegedAction() {
            public Object run() {
                user[0] = System.getProperty("user.name");
                return null; // still need this
            }
          }
        );
        ...normal code here...
  }
Yet another alternative would be to write a non-anonymous class that safely handles types for you:
   somemethod() {
        ...normal code here...
        GetPropertyAction gpa = new GetPropertyAction("user.name");
        AccessController.doPrivileged(gpa);
        String user = gpa.getValue();
        ...normal code here...
   }

   class GetPropertyAction implements PrivilegedAction {
      private String property;
      private String value;
      public GetPropertyAction(String prop) { property = prop;}
      public Object run() {
               value = System.getProperty(property);
               return value;
      }
      public String getValue() {return value;}

   }

Note there are now no type-casts involved, although the run method still returns a value, so you could still have a "one-liner" if you wanted to:

   somemethod() {
        ...normal code here...
        String user = (String) AccessController.doPrivileged(
                                   new GetPropertyAction("user.name"));
        ...normal code here...
   }

Accessing local variables

If you are using an anonymous inner class, any local variables you access must be final. For example:

   somemethod() {
        ...normal code here...
        final String lib = "awt";
        AccessController.doPrivileged(new PrivilegedAction() {
            public Object run() {
                // privileged code goes here, for example:
                System.loadLibrary(lib);
                return null; // nothing to return
            }
        });
       ...normal code here...
  }

The variable lib must be declared final if you intend to use it within the privileged block. See the "Inner Classes" spec for more information on this topic.

If there are cases where you can't make an existing variable final (because it gets set multiple times), then you can create a new final variable right before invoking doPrivileged, and set that variable equal to the other variable. For example:

   somemethod() {
        ...normal code here...
        String lib;
        ...
        // lib gets set multiple times so we can't make it final
        ...
        // create a final String that we can use inside of the run method
        final String fLib = lib;
        AccessController.doPrivileged(new PrivilegedAction() {
            public Object run() {
                // privileged code goes here, for example:
                System.loadLibrary(fLib);
                return null; // nothing to return
            }
        });
       ...normal code here...
  }

Handling Exceptions

If the action performed in your run method could throw a "checked" exception (one that must be listed in the throws clause of a method), then you need to use the PrivilegedExceptionAction interface instead of the PrivilegedAction interface:

   somemethod() throws FileNotFoundException {
        ...normal code here...
      try {
        FileInputStream fis = (FileInputStream) AccessController.doPrivileged(
          new PrivilegedExceptionAction() {
            public Object run() throws FileNotFoundException {
                return new FileInputStream("someFile");
            }
          }
        );
      } catch (PrivilegedActionException e) {
        // e.getException() should be an instance of FileNotFoundException,
        // as only "checked" exceptions will be "wrapped" in a
        // PrivilegedActionException.
        throw (FileNotFoundException) e.getException();
      }
        ...normal code here...
  }

If a checked exception is thrown during execution of the run method, it is placed in a PrivilegedActionException "wrapper" exception that is then thrown and should be caught by your code, as illustrated in the above example..

Reflection

One subtlety that must be considered is the interaction of this API with reflection. The doPrivileged() method can be invoked reflectively using java.lang.reflect.Method.invoke(). In this case, the privileges granted in privileged mode are not those of Method.invoke() but of the non-reflective code that invoked it. Otherwise, system privileges could erroneously (or maliciously) be conferred on user code. Note that similar requirements exist when using the existing API via reflection.

Copyright © 1997-2001 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: java-security@sun.com 		Sun
Java Software


Security

 Documentation Contents

Java™ security technology includes a large set of APIs, tools, and implementations of commonly-used security algorithms, mechanisms, and protocols. The Java security APIs span a wide range of areas, including cryptography, public key infrastructure, secure communication, authentication, and access control. Java security technology provides the developer with a comprehensive security framework for writing applications, and also provides the user or administrator with a a set of tools to securely manage applications.

Enhancements

  • Java™ SE 6 Security Enhancements

Programmer's Guides

General Security

  • Java Security Overview
  • Security Architecture
  • Java Cryptography Architecture (JCA) Reference Guide
  • How to Implement a Provider for the Java Cryptography Architecture
  • Standard Algorithm Names
  • SUN Providers Documentation

  • Policy Permissions
  • Default Policy Implementation and Policy File Syntax
  • API for Privileged Blocks
  • Security Managers and the Java SE Development Kit

Java Authentication and Authorization Service (JAAS)

  • JAAS Reference Guide
  • See the JAAS Tutorials.
  • JAAS white paper
  • JAAS LoginModule Developer's Guide

Java Cryptography Extension (JCE)

(The JCE documentation has been combined with the corresponding JCA documentation. Please see:)
  • Java Cryptography Architecture (JCA) Reference Guide
  • How to Implement a Provider for the Java Cryptography Architecture

Java Generic Security Services (Java GSS-API)

  • See the Java GSS-API and JAAS Tutorials for Use with Kerberos.
  • Single Sign-on Using Kerberos in Java
  • Java GSS Security Features
  • Java GSS Advanced Security Programming

Java PKCS#11 Reference Guide

  • Java PKCS#11 Reference Guide

Java Secure Socket Extension (JSSE)

  • JSSE Reference Guide

Public Key Infrastructure (PKI)

  • Java PKI Programmer's Guide
  • X.509 Certificates and Certificate Revocation Lists

Simple Authentication and Security Layer (SASL)

  • The Java SASL API Programming and Deployment Guide

XML Digital Signature

  • The XML Digital Signature API Specification
  • The XML Digital Signature API Reference and Tutorial

API Specification

General Security

  • java.security Package
  • javax.crypto Package
  • java.security.cert Package
  • java.security.spec Package
  • javax.crypto.spec Package
  • java.security.interfaces Package
  • javax.crypto.interfaces Package

Certification Path

  • java.security.cert Package

JAAS

  • javax.security.auth Package
  • javax.security.auth.callback Package
  • javax.security.auth.kerberos Package
  • javax.security.auth.login Package
  • javax.security.auth.spi Package
  • javax.security.auth.x500 Package
  • com.sun.security.auth Package
  • com.sun.security.auth.callback Package
  • com.sun.security.auth.login Package
  • com.sun.security.auth.module Package

Java GSS-API

  • org.ietf.jgss Package
  • com.sun.security.jgss Package

JSSE

  • javax.net Package
  • javax.net.ssl Package
  • javax.security.cert Package (Denigrated, use java.security.cert instead)

Java SASL

  • javax.security.sasl Package

SSL/TLS-based RMI Socket Factories

  • javax.rmi.ssl Package

XML Digital Signature

  • javax.xml.crypto Package
  • javax.xml.crypto.dom Package
  • javax.xml.crypto.dsig Package
  • javax.xml.crypto.dsig.dom Package
  • javax.xml.crypto.dsig.keyinfo Package
  • javax.xml.crypto.dsig.spec Package

Smart Card I/O

  • javax.smartcardio Package

Tools

  • Security Tools Summary
  • keytool (for Solaris/Linux) (for Windows)
  • jarsigner (for Solaris/Linux) (for Windows)
  • policytool (for Solaris/Linux) (for Windows)
  • kinit (for Windows)
  • klist (for Windows)
  • ktab (for Windows)

Tutorials

  • The Java™ SE 6 Platform Security trail of the Java Tutorial
  • JAAS Tutorials.
  • Java GSS-API and JAAS Tutorials for Use with Kerberos.
  • Policytool User's Guide

More Information

  • The Security Home Page

Copyright © 1995-2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: java-security@sun.com. This is not a subscription list. 		Sun


Security Managers and the Java SE JDK

Document revision 1.7

Introduction
Security Model Evolution
Security Manager Evolution
Security Manager Methods
Security Managers in JDK 1.1
Security Managers in the Java SE JDK
Installing java.lang.SecurityManager as the Default Security Manager
Changes to Methods For Class Loaders And Class Loader Depth
How to Port 1.1-Style Security Managers
SecurityManager Method Changes and Override Advice

Introduction

This document describes changes made to the security manager in the JDK that allow it to be used as-is as the default security manager in applications.

Security Model Evolution

In JDK 1.1, local applications and correctly digitally signed applets were generally trusted to have full access to vital system resources, such as the file system, while unsigned applets were not trusted and could access only limited resources. A security manager was responsible for determining which resource accesses were allowed.

The Java SE JDK security architecture is policy-based, and allows for fine-grained access control. When code is loaded, it is assigned "permissions" based on the security policy currently in effect. Each permission specifies a permitted access to a particular resource, such as "read" and "write" access to a specified file or directory, or "connect" access to a given host and port. The policy, specifying which permissions are available for code from various signers/locations, can be initialized from an external configurable policy file. Unless a permission is explicitly granted to code, it cannot access the resource that is guarded by that permission. These new concepts of permission and policy enable the JDK to offer fine-grain, highly configurable, flexible, and extensible access control. Such access control can now not only be specified for applets, but also for all Java code, including applications, beans, and servlets.

For more information on the Java security architecture, please see the security documentaton.

Security Manager Evolution

Security Manager Methods

The SecurityManager class contains many methods with names that begin with the word check. Examples are checkRead and checkConnect. Various methods in the Java libraries call a check method before performing each potentially security-sensitive operation. The security manager is thereby given an opportunity to prevent completion of the operation by throwing an exception. A security manager routine simply returns if the operation is permitted, but throws a SecurityException if the operation is not permitted. The only exception to this convention is checkTopLevelWindow, which returns a boolean value.

The other main type of methods contained in the SecurityManager class are those related to class loader existence and depth:

  • currentClassLoader
  • currentLoadedClass
  • inClassLoader
  • classLoaderDepth

Security Managers in JDK 1.1

In JDK 1.1, the class java.lang.SecurityManager was an abstract class. The default implementations of the security manager check methods threw exceptions. The class loader and depth-related classes were appropriately implemented, often in native code.

Any application (such as a browser) that wanted to install a security manager had to write their own, providing appropriate concrete implementations of the methods that threw exceptions by default -- primarily the check methods.

Security managers based on the JDK 1.1 applet security manager model typically based access control decisions on two things:

  1. Whether or not a class with a class loader (i.e., an applet in JDK 1.1) was on the stack.

  2. The class loader depth -- how far down the stack was the most recent occurrence of a method from a class defined using a class loader.

These types of decisions were made by calling the SecurityManager methods related to class loader existence and depth. For example, a typical 1.1-style security manager might have a checkExit method like the following:

     public void checkExit(int status) {
       if (inClassLoader()) {
        throw new SecurityException(..);
       }
     }

Such a checkExit method would not allow Runtime.exit to be called when any class defined with a class loader (an applet) was on the stack. This is an example of the first case, checking whether or not a class with a class loader is on the stack. An example of the second case (class loader depth) would be something like:

      public void checkCreateClassLoader() {
         if (classLoaderDepth() == 2) {
            throw new SecurityException();
         }
      }

This method is saying that the class loader depth can't be 2. That is, the method that called the method that called checkCreateClassLoader must not be in a class defined with a class loader. For example, the constructor for java.lang.ClassLoader calls checkCreateClassLoader, which means the method that calls the constructor for java.lang.ClassLoader must not have a class loader. This means applets can't directly create class loaders.

Note that there is a big difference between the two methods, even though both attempt to prevent applets from performing actions. In the first case, checkExit will throw an exception if an applet is anywhere on the stack. That means even built-in JDK code can't exit the VM if it was called from an applet. In the second case, JDK code is allowed to create a class loader, even if it was called by an applet. That is because the depth of a class with a class loader is used, and not the fact that there is one.

Security Managers in the Java SE JDK

In the JDK, the class java.lang.SecurityManager had a number of changes made to it in order to allow it to be used as the default security manager for applications. In particular:

  • It is no longer an abstract class, and can thus be installed as-is.

  • Most check methods call a new checkPermission method, which by default calls the method of the same name (checkPermission) in the new AccessController class. Those methods that don't call checkPermission have reasonable defaults.

  • Methods used in JDK 1.1 to determine if a class loader is on the stack and/or to calculate class loader depth have been modified in the JDK to ignore system class loaders and security contexts that have been granted java.security.AllPermission.

Installing java.lang.SecurityManager as the Default Security Manager

Since java.lang.SecurityManager is no longer abstract, you can install and use it as the default security manager. You can do this by setting a system property when launching the VM:

    java -Djava.security.manager YourApp
Alternatively, your application can install it directly via the following line of code:
    System.setSecurityManager(new SecurityManager());
You can customize the behavior of the default security manager by modifying policy files. See the security guide on policy files for more information.

Changes to Methods For Class Loaders And Class Loader Depth

In the JDK, the SecurityManager methods related to class loaders and class loader depth are not called by any of the check methods, and they are deprecated. They should not be used by any new security managers, and it is recommended that their use be eliminated from existing security managers as well. However, they are left in for backward compatibility and they have been modified in an attempt to enable old 1.1-style security managers to still work under the JDK, without modification.

These methods are:

  • currentClassLoader
  • currentLoadedClass
  • inClassLoader
  • classLoaderDepth

Modification of Class Loader/Depth-related Methods

The class loader/depth related methods have all been modified in three ways:

  1. These methods skip system class loaders. A system class loader is defined as being a class loader that is equal to the system class loader (as returned by ClassLoader.getSystemClassLoader) or one of its ancestors.

    Since classes loaded by the system class loader include application classes (loaded off of CLASSPATH), extension classes, and the built-in JDK classes, this modification enables these methods to ignore such code.

    Note that if you run an application that installs a custom security manager, and that security manager is loaded off of CLASSPATH in the JDK, it will have a system class loader associated with it. (Application classes did not have a class loader in JDK 1.1.) If you were to call a method like classLoaderDepth from within the custom security manager, and that method were not modified to ignore classes loaded by a system class loader, it would always return 0, which would not be very useful. Similarly, if class loader methods weren't changed to skip system classes and a custom security manager was loaded off of CLASSPATH, then this might also open up security holes in cases where the security manager is making decisions based on, for example, disallowing an operation if "classLoaderDepth() == 2". (It should really be "classLoaderDepth() <= 2".)

  2. These methods stop checking after they reach a method on the stack that has been marked as "privileged." (See java.security.AccessController.doPrivileged() and API for Privileged Blocks.)

  3. These methods treat security contexts that have been granted AllPermission as if there is no class loader on the stack.

As an example of the use of the first two modifications, note that there are now places in the JDK that open files, etc., after a security manager has been installed. Some 1.1-style security managers have a checkRead method that looks like the following:

       public void checkRead(String file) {
         if (inClassLoader()) {
          throw new SecurityException(..);
         }
       }

Without JDK code modifications, such a check run in the JDK would cause a security exception to be thrown when the JDK itself tries to read a file and there is a class with a non-system class loader on the stack. With the new security model, all such JDK code that tries to perform an operation that its caller might not be allowed to do has a doPrivileged block around it. Since inClassLoader just examines the stack up to and including the frame containing the "privileged" code, and the code at the top of the stack is JDK code, which is loaded by the system class loader or one of its ancestors, the inClassLoader method will return false, allowing the read to occur.

Maintenance of Class Loader Depths

As noted previously, security managers based on the 1.1 applet security manager based some of their access control decisions on class loader depth. As an example, the checkCreateClassLoader method previously presented is repeated here:

       public void checkCreateClassLoader() {
          if (classLoaderDepth() == 2) {
             throw new SecurityException();
          }
       }
In the JDK we have attempted to maintain the stack depth as used in 1.1-style security managers. For example, the constructor for java.security.SecureClassLoader has an explicit call to SecurityManager.checkCreateClassLoader even though the constructor for its super class (ClassLoader) also does. If the check was not placed in the constructor for SecureClassLoader, then a 1.1-style security manager would allow untrusted code to extend SecureClassLoader and construct class loaders, as the class loader depth would always be greater than 2.

How to Port 1.1-Style Security Managers

First and foremost, we highly recommend analyzing all your custom security manager methods before running your security manager under the JDK. Failure to do so could result in a security hole or prevent the proper operation of the JDK. This is due to the fragile nature of 1.1-style security managers.

Where possible, you should just use the default implementation of the 1.2 SecurityManager. This helps give users and administrators consistent behavior. If this is not possible, then you should at least try to call super.checkXXX in your checkXXX method before throwing a security exception. Doing so will allow the access controller algorithm to be used, and will allow the JDK itself to function correctly.

In the JDK, any existing code that used to call any of the SecurityManager check methods continues to do so. For new code that requires a security check, calls are made to SecurityManager.checkPermission instead of adding a new SecurityManager check method. For example, the new java.lang.System.setProperty method calls checkPermission with a java.util.PropertyPermission permission.

When extending the SecurityManager class and overriding existing methods, some care should be taken. For example, if you override the checkRead(String file) method so it always throws a security exception, then the JDK itself may fail to operate properly. That is, if some JDK code needs to open a file (to read a properties file, load a JAR file, etc.) then throwing a security exception for every read attempt would cause such opens to always fail.

In general, you should only override the default methods if you intend to loosen security, not to make it stronger. If you want to tighten security, you should modify the default policy files and/or install a custom java.security.Policy object. See the security guide on policy files for more information.

In general, when overriding security manager methods you should place a call to the super.checkXXX method at the point where your overridden checkXXX method would throw an exception. For example:

      public class MySecurityManager extends SecurityManager {

        public void checkRead(String file) {
          if (someCustomSecurityCheckFails()) {
             super.checkRead(file);
          }
        }
      }
If your custom security check fails, then super.checkRead gets called. The default implementation of checkRead invokes checkPermission, which by default consults the AccessController. By invoking the AccessController, system code that has done an AccessController.doPrivileged before trying to read a file will succeed in reading that file. All other code will be subjected to the current policy in effect, and an access control exception will be thrown if access to that file has not been granted.

Note, there are some checkXXX methods in which you should not call super.checkXXX methods when overriding them. That is because the default implementation of these methods may not be as strict as the policy you are implementing in the overridden method. For example, the default checkAccess(ThreadGroup g) method only protects the system thread group. If you intend to protect threads in distinct thread groups from each other (for example applet thread groups), then you would not want to call super.checkAccess at the point you would normally throw a security exception, as that would defeat the purpose of your customized check. Instead, you could place a call to super.checkAccess as the first statement in your overridden method.

For example:

      public class AppletSecurityManager extends SecurityManager {

        public void checkAccess(ThreadGroup g) {
          // a call to super will throw an exception if someone
          // is trying to modify the system thread group
          super.checkAccess(g);
          ...
          // now perform checks based on which applet thread group
          // the current caller is in to see if they can modify thread group g.
          ...
      }

We describe how to override each method in the following section.

SecurityManager Method Changes and Override Advice

This section lists changes made to java.lang.SecurityManager methods in the JDK and provides suggestions regarding any overrides you may wish to make. Please see the Java documentation for the SecurityManager class for more information on these methods.

protected boolean inCheck

This field has been deprecated, and any uses of this field within the JDK itself have been removed. Instead of using inCheck, you should use checkPermission along with doPrivileged.

public boolean getInCheck();

This method has also been deprecated.

public SecurityManager();

The constructor has been modified to allow multiple SecurityManagers to be created, assuming the caller has the RuntimePermission("createSecurityManager") permission.

protected native Class[] getClassContext();

No changes. This call can be used to emulate the 1.1 behavior of the methods that have been changed in the JDK ( currentClassLoader, currentLoadedClass, classLoaderDepth, inClassLoader).

protected ClassLoader currentClassLoader();

The typical use of this method in JDK 1.1-style security managers was to see if there was a class loader on the stack, and if not, treat the code as "trusted" and allow it to do anything. This method has been modified in the JDK to allow trusted JDK code (actually any code granted java.security.AllPermission) that calls doPrivileged to be treated as trusted by 1.1-style security managers. It has also been modified to skip system class loaders. A system class loader is defined as being a class loader that is equal to the system class loader (as returned by ClassLoader.getSystemClassLoader) or one of its ancestors.

This method will return null in the following three cases:

  1. All methods on the execution stack are from classes defined using the system class loader or one of its ancestors.
  2. All methods on the execution stack up to the first "privileged" caller (see java.security.AccessController.doPrivileged) are from classes defined using the system class loader or one of its ancestors.
  3. A call to checkPermission with java.security.AllPermission does not result in a SecurityException.

This method has been deprecated. Use checkPermission instead.

protected Class currentLoadedClass();

This method has been modified in the same fashion as currentClassLoader, and will return null if the current security context has been granted AllPermission or all the methods on the stack (up to the first privileged caller, if any) are from classes defined using the system class loader or one of its ancestors.

This method has been deprecated. Use checkPermission instead.

protected int classDepth(String name);

No changes in behavior. This method has been deprecated. Use checkPermission instead.

protected int classLoaderDepth();

This method has been modified in the same fashion as currentClassLoader, and will return -1 if the current security context has been granted AllPermission or all the methods on the stack (up to the first privileged caller, if any) are from classes defined using the system class loader or one of its ancestors.

This method has been deprecated. Use checkPermission instead.

protected boolean inClass(String name);

No changes in behavior. This method has been deprecated. Use checkPermission instead.

protected boolean inClassLoader();

This method returns true if currentClassLoader returns a non-null class loader, so it follows the same semantics that currentClassLoader does.

This method has been deprecated. Use checkPermission instead.

public Object getSecurityContext();

This method returns a java.security.AccessControlContext object that is created with a call to java.security.AccessController.getContext. In JDK1.1 it returned null by default.

public void checkPermission(Permission perm);

This method is new in the JDK. It calls java.security.AccessController.checkPermission with the given permission. Internally, the JDK always calls SecurityManager.checkPermission instead of calling the AccessController directly. This allows people to override this method to provide additional functionality such as auditing and/or GUI dialogs.

public void checkPermission(Permission perm, Object context);

This method is new in the JDK. If context is an instance of AccessControlContext then the AccessControlContext.checkPermission method will be invoked on the given context with the specified permission.

If context is not an instance of AccessControlContext then a SecurityException is thrown.

public void checkCreateClassLoader();

This method has been modified to call checkPermission with the RuntimePermission("createClassLoader") permission.

If this method is overridden, then a call to super.checkCreateClassLoader should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkCreateClassLoader() {
      if (someCustomSecurityCheckFails()) {
        super.checkCreateClassLoader();
      }
    }
  }

public void checkAccess(Thread t);

If the thread argument is a system thread (belongs to the thread group with a null parent) then this method calls checkPermission with the RuntimePermission("modifyThread") permission.

Applications that want a stricter policy should override this method.

If this method is overridden, then super.checkAccess should be called by the first statement in the overridden method, or the equivalent security check should be placed in the overridden method.

If this method is overridden, the method that overrides it should additionally check to see if the calling thread has the RuntimePermission("modifyThread") permission, and if so, return silently. This is to ensure that code granted that permission (such as the JDK itself) is allowed to manipulate any thread.

For example:

  public class MySecurityManager extends SecurityManager {

    public void checkAccess(Thread t) {
      // a call to super will throw an exception if someone
      // is trying to modify a system thread
      super.checkAccess(t);
      ...
      if (someCustomSecurityCheckForOtherThreadsFails()) {
        // if the check fails, instead of throwing an exception,
        // call checkPermission, which will throw an exception
        // if need be
        checkPermission(new RuntimePermission("modifyThread"));
      }
      ...
    }
  }

public void checkAccess(ThreadGroup g);

If the thread group argument is the system thread group (has a null parent) then this method calls checkPermission with the RuntimePermission("modifyThreadGroup") permission.

Applications that want a stricter policy should override this method.

If this method is overridden, then super.checkAccess should be called by the first statement in the overridden method, or the equivalent security check should be placed in the overridden method.

If this method is overridden, the method that overrides it should additionally check to see if the caller has the RuntimePermission("modifyThreadGroup") permission, and if so, return silently. This is to ensure that code granted that permission (such as the JDK itself) is allowed to manipulate any thread group.

For example:

  public class MySecurityManager extends SecurityManager {

    public void checkAccess(ThreadGroup g) {
      // a call to super will throw an exception if someone
      // is trying to modify the system thread group
      super.checkAccess(g);
      ...
      if (someCustomSecurityCheckForOtherThreadGroupsFails()) {
        // if the check fails, instead of throwing an exception,
        // call checkPermission, which will throw an exception
        // if need be
        checkPermission(new RuntimePermission("modifyThreadGroup"));
      }
      ...
    }
  }

public void checkExit(int status);

This method has been modified to call checkPermission with the RuntimePermission("exitVM") permission.

If this method is overridden, then a call to super.checkExit should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkExit(int status) {
      if (someCustomSecurityCheckFails()) {
        super.checkExit(status);
      }
    }
  }

public void checkExec(String cmd);

This method has been modified to call checkPermission with a FilePermission. If the cmd is an absolute path (see java.io.File.isAbsolute) then it is passed as-is as the target for the FilePermission. If cmd is not absolute, then the special target "<<ALL FILES>>" is used. This target is used because it is difficult to determine the actual path of the command that will be executed on an individual platform due to things such as environment variables, etc.

If this method is overridden, then a call to super.checkExec should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkExec(String cmd) {
      if (someCustomSecurityCheckFails()) {
        super.checkExec(cmd);
      }
    }
  }

public void checkLink(String lib);

This method has been modified to call checkPermission with the RuntimePermission("loadLibrary."+lib) permission.

If this method is overridden, then a call to super.checkLink should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkLink(String lib) {
      if (someCustomSecurityCheckFails()) {
        super.checkLink(lib);
      }
    }
  }

public void checkRead(FileDescriptor fd);

This method has been modified to call checkPermission with the RuntimePermission("readFileDescriptor") permission.

If this method is overridden, then a call to super.checkRead should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkRead(FileDescriptor fd) {
      if (someCustomSecurityCheckFails()) {
        super.checkRead(fd);
      }
    }
  }

public void checkRead(String file);

This method has been modified to call checkPermission with the FilePermission(file,"read") permission.

If this method is overridden, then a call to super.checkRead should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkRead(String file) {
      if (someCustomSecurityCheckFails()) {
        super.checkRead(file);
      }
    }
  }

public void checkRead(String file, Object context);

This method has been modified. If context is an instance of AccessControlContext then the AccessControlContext.checkPermission method will be invoked on the given context with the FilePermission(file,"read") permission.

If context is not an instance of AccessControlContext then a SecurityException is thrown.

If this method is overridden, then a call to super.checkRead should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkRead(String file, Object context) {
      if (someCustomSecurityCheckFails()) {
        super.checkRead(file, context);
      }
    }
  }

public void checkWrite(FileDescriptor fd);

This method has been modified to call checkPermission with the RuntimePermission("writeFileDescriptor") permission.

If this method is overridden, then a call to super.checkWrite should be made at the point the overridden method would normally throw an exception. For Example:

  public class MySecurityManager extends SecurityManager {

    public void checkWrite(FileDescriptor fd) {
      if (someCustomSecurityCheckFails()) {
        super.checkWrite(fd);
      }
    }
  }

public void checkWrite(String file);

This method has been modified to call checkPermission with the FilePermission(file,"write") permission.

If this method is overridden, then a call to super.checkWrite should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkWrite(String file) {
      if (someCustomSecurityCheckFails()) {
        super.checkWrite(file);
      }
    }
  }

public void checkDelete(String file);

This method has been modified to call checkPermission with the FilePermission(file,"delete") permission.

If this method is overridden, then a call to super.checkDelete should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkDelete(String file) {
      if (someCustomSecurityCheckFails()) {
        super.checkDelete(file);
      }
    }
  }

public void checkConnect(String host, int port);

This method has been modified to call checkPermission with the SocketPermission(host+":"+port,"connect") permission if the port is not equal to -1. If the port is equal to -1, then it calls checkPermission with the SocketPermission(host,"resolve") permission.

This behavior is consistent with JDK 1.1, where a port equal to -1 indicates that an IP address lookup is being performed.

If this method is overridden, then a call to super.checkConnect should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkConnect(String host, int port) {
      if (someCustomSecurityCheckFails()) {
        super.checkConnect(host, port);
      }
    }
  }

public void checkConnect(String host, int port, Object context);

This method has been modified. If context is an instance of AccessControlContext then the AccessControlContext.checkPermission method will be invoked on the given context with the SocketPermission(host+":"+port,"connect") permission if the port is not equal to -1. If the port is equal to -1, then it calls checkPermission with the SocketPermission(host,"resolve") permission.

If context is not an instance of AccessControlContext then a SecurityException is thrown.

If this method is overridden, then a call to super.checkConnect should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkConnect(String host, int port, Object context) {
      if (someCustomSecurityCheckFails()) {
        super.checkConnect(host, port, context);
      }
    }
  }

public void checkListen(int port)

This method has been modified. If port is not 0, it calls checkPermission with the SocketPermission("localhost:"+port,"listen"). If port is zero, it calls checkPermission with SocketPermission("localhost:1024-","listen").

If this method is overridden, then a call to super.checkListen should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkListen(int port) {
      if (someCustomSecurityCheckFails()) {
        super.checkListen(port);
      }
    }
  }

public void checkAccept(String host, int port);

This method has been modified to call checkPermission with the SocketPermission(host+":"+port,"accept") permission.

If this method is overridden, then a call to super.checkAccept should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkAccept(String host, int port) {
      if (someCustomSecurityCheckFails()) {
        super.checkAccept(host, port);
      }
    }
  }

public void checkMulticast(InetAddress maddr);

This method has been modified to call checkPermission with the SocketPermission(maddr.getHostAddress(),"accept,connect") permission.

If this method is overridden, then a call to super.checkMulticast should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkMultiCast(InetAddress maddr) {
      if (someCustomSecurityCheckFails()) {
        super.checkMultiCast(maddr);
      }
    }
  }

public void checkMulticast(InetAddress maddr, byte ttl);

This method has been modified to call checkPermission with the SocketPermission(maddr.getHostAddress(),"accept,connect") permission.

If this method is overridden, then a call to super.checkMulticast should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkMultiCast(InetAddress maddr, byte ttl) {
      if (someCustomSecurityCheckFails()) {
        super.checkMultiCast(maddr, ttl);
      }
    }
  }

public void checkPropertiesAccess();

This method has been modified to call checkPermission with the PropertyPermission("*", "read,write") permission.

If this method is overridden, then a call to super.checkPropertiesAccess should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkPropertiesAccess() {
      if (someCustomSecurityCheckFails()) {
        super.checkPropertiesAccess();
      }
    }
  }

public void checkPropertyAccess(String key);

This method has been modified to call checkPermission with the PropertyPermission(key, "read") permission.

If this method is overridden, then a call to super.checkPropertyAccess should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkPropertyAccess(String key) {
      if (someCustomSecurityCheckFails()) {
        super.checkPropertiesAccess(key);
      }
    }
  }

public boolean checkTopLevelWindow(Object window);

This method has been modified to call checkPermission with the AWTPermission("showWindowWithoutWarningBanner") permission, and returns true if an SecurityException is not thrown, otherwise it returns false.

If this method is overridden, then a call to super.checkTopLevelWindow should be made at the point the overridden method would normally return false, and the value of super.checkTopLevelWindow should be returned. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkTopLevelWindow(Object window) {
      if (someCustomSecurityCheckFails()) {
        return super.checkTopLevelWindow(window);
      } else {
        return true;
      }
    }
  }

public void checkPrintJobAccess();

This method has been modified to call checkPermission with the RuntimePermission("queuePrintJob") permission.

If this method is overridden, then a call to super.checkPrintJobAccess should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkPrintJobAccess() {
      if (someCustomSecurityCheckFails()) {
        super.checkPrintJobAccess();
      }
    }
  }

public void checkSystemClipboardAccess();

This method has been modified to call checkPermission with the AWTPermission("accessClipboard") permission.

If this method is overridden, then a call to super.checkSystemClipboardAccess should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkSystemClipboardAccess() {
      if (someCustomSecurityCheckFails()) {
        super.checkSystemClipboardAccess();
      }
    }
  }

public void checkAwtEventQueueAccess();

This method has been modified to call checkPermission with the AWTPermission("accessEventQueue") permission.

If this method is overridden, then a call to super.checkAwtEventQueueAccess should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkAwtEventQueueAccess() {
      if (someCustomSecurityCheckFails()) {
        super.checkAwtEventQueueAccess();
      }
    }
  }

public void checkPackageAccess(String pkg);

This method has been modified. It first gets a list of restricted packages by obtaining a comma-separated list from a call to java.security.Security.getProperty("package.access"), and checks to see if pkg starts with or equals any of the restricted packages. If it does, then checkPermission gets called with the RuntimePermission("accessClassInPackage."+pkg) permission.

If this method is overridden, then super.checkPackageAccess should be called as the first line in the overridden method. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkPackageAccess(String pkg) {
      super.checkPackageAccess(pkg);
      ...
      someCustomSecurityCheck();
      ...
    }
  }

public void checkPackageDefinition(String pkg);

This method has been modified. It first gets a list of restricted packages by obtaining a comma-separated list from a call to java.security.Security.getProperty("package.definition"), and checks to see if pkg starts with or equals any of the restricted packages. If it does, then checkPermission gets called with the RuntimePermission("defineClassInPackage."+pkg) permission.

If this method is overridden, then super.checkPackageDefinition should be called as the first line in the overridden method. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkPackageDefinition(String pkg) {
      super.checkPackageDefinition(pkg);
      ...
      someCustomSecurityCheck();
      ...
    }
  }

public void checkSetFactory();

This method has been modified to call checkPermission with the RuntimePermission("setFactory") permission.

If this method is overridden, then a call to super.checkSetFactory should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkSetFactory() {
      if (someCustomSecurityCheckFails()) {
        super.checkSetFactory();
      }
    }
  }

public void checkMemberAccess(Class clazz, int which);

This method has been modified. The default policy is to allow access to PUBLIC members, as well as access to classes that have the same class loader as the caller. In all other cases call checkPermission with the RuntimePermission("accessDeclaredMembers") permission.

If this method is overridden, then a call to super.checkMemberAccess cannot be made, as the default implementation of checkMemberAccess relies on the code being checked being at a stack depth of 4. For example:

     someCaller[3]
     java.lang.Class.someReflectionAPI [2]
     java.lang.Class.checkMemberAccess [1]
     SecurityManager.checkMemberAccess [0]
In order to emulate this behavior, you would need to call getClassContext, and examine the class loader of the class at index 3, just as the default checkMemberAccess method does:
  if (which != Member.PUBLIC) {
    Class stack[] = getClassContext();
    /*
     * stack depth of 4 should be the caller of one of the
     * methods in java.lang.Class that invoke checkMember
     * access. The stack should look like:
     *
     * someCaller [3]
     * java.lang.Class.someReflectionAPI  [2]
     * java.lang.Class.checkMemberAccess [1]
     * MySecurityManager.checkMemberAccess [0]
     *
     */
    if ((stack.length<4) ||
      (stack[3].getClassLoader() != clazz.getClassLoader())) {
      if (checkMemberAccessPermission == null)
        checkMemberAccessPermission =
          new RuntimePermission("accessDeclaredMembers");
      checkPermission(checkMemberAccessPermission);
    }
  }

This is the only security manager method in the JDK that is still based on a caller's depth. This is to allow a caller to reflect on classes from the same class loader it came from.

public void checkSecurityAccess(String target);

This method has been modified to create a SecurityPermission object for the given permission target name and calls checkPermission with it.

If this method is overridden, then a call to super.checkSecurityAccess should be made at the point the overridden method would normally throw an exception. For example:

  public class MySecurityManager extends SecurityManager {

    public void checkSecurityAccess(String target) {
      if (someCustomSecurityCheckFails()) {
        super.checkSecurityAccess(target);
      }
    }
  }

public ThreadGroup getThreadGroup();

This method has not been changed.

Copyright © 1997-2001 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: java-security@sun.com. This is not a subscription list. 		Sun
Java Software


Signature Time Stamp Support in J2SE 5.0

Signature Timestamp Support
for J2SE 5.0

Introduction

 This document describes the enhancements that have been added in J2SE 5.0 to support signature timestamps. Please send feedback, especially those related to these new features, to java-security@sun.com.

Prior to J2SE 5.0, the signature generated by jarsigner contained no information about w hen the signature was generated. With no other information available, systems/deployers (including users of the Java Plug-in) often based their validity assessment of a signed JAR file on the validity of the signing certificate. When the signing certificate expires, systems/deployers conclude that the signature, and hence, the JAR file, has expired. Because signing certificates typically expire annually, this caused customers significant problems by forcing them to re-sign deployed JAR files annually.

Starting in J2SE 5.0, jarsigner can generate signatures that include a timestamp, thus enabling systems/deployer (including Java Plug-in) to check whether the JAR file was signed while the signing certificate was still valid. In addition, APIs were added in J2SE 5.0 to allow applications to obtain the timestamp information.

The following time-of-signing enhancements and additions are supported in version 5.0 of the Java 2 platform:

  • Jarsigner Enhancements
  • Java Plug-in Enhancements
  • API Enhancements

Jarsigner Enhancements

The jarsigner tool can now generate and store a signature timestamp when signing a JAR file. In addition, jarsigner supports alternative signing mechanisms. This behavior is optional and is controlled by the user at the time of signing through the options described below.

Jarsigner Timestamp Options

The following options were added to the jarsigner tool to support signature timestamps:

-tsa url

If "-tsa http://example.tsa.url" appears on the command line when signing a JAR file then a timestamp is generated for the signature. The URL, http://example.tsa.url, identifies the location of the Time Stamping Authority (TSA). It overrides any URL found via the -tsacert option. The -tsa option does not require the TSA's public key certificate to be present in the keystore.

To generate the timestamp, jarsigner communicates with the TSA using the Time-Stamp Protocol (TSP) defined in RFC 3161. If successful, the timestamp token returned by the TSA is stored along with the signature in the signature block file.

-tsacert alias

If "-tsacert alias" appears on the command line when signing a JAR file then a timestamp is generated for the signature. The alias identifies the TSA's public key certificate in the keystore that is currently in effect. The entry's certificate is examined for a Subject Information Access extension that contains a URL identifying the location of the TSA.

The TSA's public key certificate must be present in the keystore when using -tsacert.

Alternative Signing Options

Specifying an Alternative Signing Mechanism

-altsigner class
Specifies that an alternative signing mechanism be used. The fully-qualified class name identifies a class file that extends the com.sun.jarsigner.ContentSigner abstract class. The path to this class file is defined by the -altsignerpath option. If the -altsigner option is used, jarsigner uses the signing mechanism provided by the specified class. Otherwise, jarsigner uses its default signing mechanism.

For example, to use the signing mechanism provided by a class named com.sun.sun.jarsigner.AuthSigner, use the jarsigner option "-altsigner com.sun.jarsigner.AuthSigner"

Specifying Path to Alternative Signing Mechanism

-altsignerpath classpathlist
Specifies the path to the class file (the class file name is specified with the -altsigner option described above) and any JAR files it depends on. If the class file is in a JAR file, then this specifies the path to that JAR file, as shown in the example below.

An absolute path or a path relative to the current directory may be specified. If classpathlist contains multiple paths or JAR files, they should be separated with a colon (:) on Solaris and a semi-colon (;) on Windows. This option is not necessary if the class is already in the search path.

Example of specifying the path to a jar file that contains the class file:

-altsignerpath /home/user/lib/authsigner.jar

Note that the JAR file name is included.

Example of specifying the path to the jar file that contains the class file:

-altsignerpath /home/user/classes/com/sun/tools/jarsigner/

Note that the JAR file name is omitted.

Java Plug-in Enhancements

 In J2SE 5.0, the Java Plug-in was enhanced to check signature timestamps (if available) when validating JAR files. The Java Plug-in will no longer present a dialog when it encounters an expired or revoked certificate when validating a signed jar, provided that the signature timestamp confirms that the signature was generated prior to the expiration or revocation date.

The TSA's certificate must be available from the Plug-in's keystore or certificate stores when the Plug-in is validating a JAR file containing a signature timestamp.

The Plugin reverts to 1.4.x behavior if the signature does not contain a timestamp.

API Enhancements

The security and JAR APIs were enhanced to enable applications to access timestamp information.

Two new classes were added to the java.security package. These classes are CodeSigner, which maintains information associated with a signer, and Timestamp, which represents information associated with a signature timestamp.

New methods were added to the java.security.CodeSource class and java.util.jar.JarEntry class to allow access to this new, optional information.


Summary of Security Tools

Summary of Tools for JavaTM Platform Security

Last Modified: 28 July, 2006

Below is a summary of the following security tools, with links to the more detailed documentation: keytool, jar, jarsigner, Policy Tool, kinit, klist, and ktab. All of these tools are command-line tools with the exception of Policy Tool, which has a graphical user interface.

The Tools

keytool (Solaris or Linux) (Windows)

Use keytool to manage your keystore, for example to

  • create public/private key pairs
  • issue certificate requests (which you send to the appropriate Certification Authority)
  • import certificate replies (obtained from the Certification Authority you contacted)
  • designate public keys belonging to other parties as trusted
  • copy entries between two keystores

Keys and certificates are used to digitally sign your applications and applets (see jarsigner below). A keystore is a protected database that holds keys and certificates for an enterprise. Access to a keystore is guarded by a password (defined at the time the keystore is created, by the person who creates the keystore, and changeable only when providing the current password). In addition, each private key in a keystore can be guarded by its own password.

jar (Solaris or Linux) (Windows)

Use the jar tool to create JAR files.

The Java ARchive (JAR) file format enables you to bundle multiple files into a single archive file. Typically a JAR file will contain the class files and auxiliary resources associated with applets and applications. When you want to "digitally sign" code, you use the jar tool to place it in a JAR file and the jarsigner tool to sign the JAR file (after generating or importing appropriate keys into your keystore using keytool).

jarsigner (Solaris or Linux) (Windows)

Use the jarsigner tool to sign JAR files, or to verify signatures on signed JAR files.

The jarsigner tool accesses a keystore that is created and managed by keytool, when it needs to find the private key and its associated certificate chain to use when signing a JAR file. Since accesses to the keystore and to private keys are protected by passwords, only people who know the passwords will be able to access the key and use it to sign a JAR file. The jarsigner tool prompts for needed passwords.

Policy Tool (Solaris or Linux) (Windows)

Use the Policy Tool (invoked by using the policytool command) to create and modify the external policy configuration files that define your installation's security policy.

The policy is described in the Security Architecture Specification. Further information is provided in Default Policy Implementation and Policy File Syntax.

This tool has a graphical user interface, so you select buttons and other options rather than type in commands as for the other tools. Please read the Policy Tool Users Guide for details.

kinit (Windows)

kinit is used to obtain and cache Kerberos ticket-granting tickets. This tool is similar in functionality to the kinit tool commonly found in other Kerberos implementations, such as SEAM and MIT Reference implementations.

The user must be registered as a principal with the Key Distribution Center (KDC) prior to running kinit.

Solaris - Equivalent functionality is available for Solaris users via the kinit tool that is part of the Solaris operating environment.

Linux - Equivalent functionality is available for Linux users via the kinit tool in any Kerberos 5 installation.

klist (Windows)

klist is a command-line tool that allows the user to view entries in the local credentials cache and key table.

Solaris - Equivalent functionality is available for Solaris users via the klist tool that is part of the Solaris operating environment.

Linux - Equivalent functionality is available for Linux users via the klist tool in any Kerberos 5 installation.

ktab (Windows)

ktab is a command-line tool that allows the user to manage the principal names and service keys stored in a local key table. Principal and key pairs listed in the keytab allow services running on a host to authenticate themselves to the Key Distribution Center (KDC). Before a server can be setup to use Kerberos, the user must setup a keytab on the host running the server. Note that any updates made to the keytab using ktab do not affect the Kerberos database. If you change the keys in the keytab, you must also make the corresponding changes to the Kerberos database. Also note that the command line options are not case-sensitive.

Solaris - Equivalent functionality is available for Solaris users via the ktutil or kadmin tool that is part of Solaris operating environment.

Linux - Equivalent functionality is available for Linux users via the ktutil or kadmin tool in any Kerberos 5 installation.

Examples of Use of the Tools

Examples of the use of several of these security tools can be found in the JavaTM Platform Security trail of the Java Tutorials.

Copyright © 1997-2002 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: java-security@sun.com. This is not a subscription list. 		Sun
Java Software


X.509 certificates

X.509 Certificates and Certificate Revocation Lists (CRLs)

In One Sentence: What is a Certificate?
What Applications use Certificates?
How do I get a Certificate?
What is Inside an X.509 Certificate?
What Java API Can Be Used to Access and Manage Certificates?
What Java Tool Can Generate, Display, Import, and Export X.509 Certificates?

In One Sentence: What is a Certificate?

A public-key certificate is a digitally signed statement from one entity, saying that the public key (and some other information) of another entity has some specific value.

Let us expand on some of the key terms used in this sentence:

Public Keys
These are numbers associated with a particular entity, and are intended to be known to everyone who needs to have trusted interactions with that entity. Public keys are used to verify signatures.
Digitally Signed
If some data is digitally signed it has been stored with the "identity" of an entity, and a signature that proves that entity knows about the data. The data is rendered unforgeable by signing with the entitys' private key.
Identity
A known way of addressing an entity. In some systems the identity is the public key, in others it can be anything from a Unix UID to an Email address to an X.509 Distinguished Name.
Signature
A signature is computed over some data using the private key of an entity (the signer).
Private Keys
These are numbers, each of which is supposed to be known only to the particular entity whose private key it is (that is, it's supposed to be kept secret). Private and public keys exist in pairs in all public key cryptography systems (also referred to as "public key crypto systems"). In a typical public key crypto system, such as DSA, a private key corresponds to exactly one public key. Private keys are used to compute signatures.
Entity
An entity is a person, organization, program, computer, business, bank, or something else you are trusting to some degree.

Basically, public key cryptography requires access to users' public keys. In a large-scale networked environment it is impossible to guarantee that prior relationships between communicating entities have been established or that a trusted repository exists with all used public keys. Certificates were invented as a solution to this public key distribution problem. Now a Certification Authority (CA) can act as a Trusted Third Party. CAs are entities (e.g., businesses) that are trusted to sign (issue) certificates for other entities. It is assumed that CAs will only create valid and reliable certificates as they are bound by legal agreements. There are many public Certification Authorities, such as VeriSign, Thawte, Entrust, and so on. You can also run your own Certification Authority using products such as the Netscape/Microsoft Certificate Servers or the Entrust CA product for your organization.

What Applications use Certificates?

Probably the most widely visible application of X.509 certificates today is in web browsers (such as Mozilla Firefox and Microsoft Internet Explorer) that support the TLS protocol. TLS (Transport Layer Security) is a security protocol that provides privacy and authentication for your network traffic. These browsers can only use this protocol with web servers that support TLS.

Other technologies that rely on X.509 certificates include:

  • Various code-signing schemes, such as signed Java ARchives, and Microsoft Authenticode.
  • Various secure E-Mail standards, such as PEM and S/MIME.
  • E-Commerce protocols, such as SET.

How do I Get a Certificate?

There are two basic techniques used to get certificates:

  1. you can create one yourself (using the right tools, such as keytool), or
  2. you can ask a Certification Authority to issue you one (either directly or using a tool such as keytool to generate the request).
The main inputs to the certificate creation process are:
  • Matched public and private keys, generated using some special tools (such as keytool), or a browser. Only the public key is ever shown to anyone else. The private key is used to sign data; if someone knows your private key, they can masquerade as you ... perhaps forging legal documents attributed to you!

  • You need to provide information about the entity being certified (e.g., you). This normally includes information such as your name and organizational address. If you ask a CA to issue a certificate for you, you will normally need to provide proof to show correctness of the information.

    If you are asking a CA to issue you a certificate, you provide your public key and some information about you. You'll use a tool (such as keytool or a browser that supports Certificate Signing Request generation). to digitally sign this information, and send it to the CA. The CA will then generate the certificate and return it.

    If you're generating the certificate yourself, you'll take that same information, add a little more (dates during which the certificate is valid, a serial number), and just create the certificate using some tool (such as keytool). Not everyone will accept self-signed certificates; one part of the value provided by a CA is to serve as a neutral and trusted introduction service, based in part on their verification requirements, which are openly published in their Certification Service Practices (CSP).

    What's Inside an X.509 Certificate?

    The X.509 standard defines what information can go into a certificate, and describes how to write it down (the data format). All X.509 certificates have the following data, in addition to the signature:

    Version
    This identifies which version of the X.509 standard applies to this certificate, which affects what information can be specified in it. Thus far, three versions are defined.
    Serial Number
    The entity that created the certificate is responsible for assigning it a serial number to distinguish it from other certificates it issues. This information is used in numerous ways, for example when a certificate is revoked its serial number is placed in a Certificate Revocation List (CRL).
    Signature Algorithm Identifier
    This identifies the algorithm used by the CA to sign the certificate.
    Issuer Name
    The X.500 name of the entity that signed the certificate. This is normally a CA. Using this certificate implies trusting the entity that signed this certificate. (Note that in some cases, such as root or top-level CA certificates, the issuer signs its own certificate.)
    Validity Period
    Each certificate is valid only for a limited amount of time. This period is described by a start date and time and an end date and time, and can be as short as a few seconds or almost as long as a century. The validity period chosen depends on a number of factors, such as the strength of the private key used to sign the certificate or the amount one is willing to pay for a certificate. This is the expected period that entities can rely on the public value, if the associated private key has not been compromised.
    Subject Name
    The name of the entity whose public key the certificate identifies. This name uses the X.500 standard, so it is intended to be unique across the Internet. This is the Distinguished Name (DN) of the entity, for example,
        CN=Java Duke, OU=Java Software Division, O=Sun Microsystems Inc, C=US
    (These refer to the subject's Common Name, Organizational Unit, Organization, and Country.)
    Subject Public Key Information
    This is the public key of the entity being named, together with an algorithm identifier which specifies which public key crypto system this key belongs to and any associated key parameters.

    X.509 Version 1 has been available since 1988, is widely deployed, and is the most generic.

    X.509 Version 2 introduced the concept of subject and issuer unique identifiers to handle the possibility of reuse of subject and/or issuer names over time. Most certificate profile documents strongly recommend that names not be reused, and that certificates should not make use of unique identifiers. Version 2 certificates are not widely used.

    X.509 Version 3 is the most recent (1996) and supports the notion of extensions, whereby anyone can define an extension and include it in the certificate. Some common extensions in use today are: KeyUsage (limits the use of the keys to particular purposes such as "signing-only") and AlternativeNames (allows other identities to also be associated with this public key, e.g. DNS names, Email addresses, IP addresses). Extensions can be marked critical to indicate that the extension should be checked and enforced/used. For example, if a certificate has the KeyUsage extension marked critical and set to "keyCertSign" then if this certificate is presented during SSL communication, it should be rejected, as the certificate extension indicates that the associated private key should only be used for signing certificates and not for SSL use.

    All the data in a certificate is encoded using two related standards called ASN.1/DER. Abstract Syntax Notation 1 describes data. The Definite Encoding Rules describe a single way to store and transfer that data. People have been known to describe this combination simultaneously as "powerful and flexible" and as "cryptic and awkward".

    The IETF PKIX working group is in the process of defining standards for the Internet Public Key Infrastructure. We are closely following their work, and support the X.509 Certificate and CRL Profile, which is specified in RFC 3280.

    What Java API Can Be Used to Access and Manage Certificates?

    The Certificate API, found in the java.security.cert package, includes the following:
    • the CertificateFactory class defines the functionality of a certificate factory, which is used to generate certificate, certificate revocation list (CRL), and certification path objects from their encoding.

    • the Certificate class is an abstract class for managing a variety of certificates. It is an abstraction for certificates that have different formats but important common uses. For example, different types of certificates, such as X.509 and PGP, share general certificate functionality (like encoding and verifying) and some types of information like public key.

    • the CRL class is an abstract class for managing a variety of Certificate Revocation Lists (CRLs).

    • the X509Certificate class is an abstract class for X.509 Certificates. It provides a standard way to access all the attributes of an X.509 certificate.

    • the X509Extension interface is an interface for an X.509 extension. The extensions defined for X.509 v3 certificates and v2 CRLs (Certificate Revocation Lists) provide mechanisms for associating additional attributes with users or public keys, such as for managing the certification hierarchy, and for managing CRL distribution.

    • the X509CRL class is an abstract class for an X.509 Certificate Revocation List (CRL). A CRL is a time-stamped list identifying revoked certificates. It is signed by a Certification Authority (CA) and made freely available in a public repository.

    • the X509CRLEntry class is an abstract class for a CRL entry.
    In JDK 1.4, new classes were added to support building and validating chains of certificates, or certification paths. These classes are described in further detail in the PKI Programmer's Guide.

    What Java Tool Can Generate, Display, Import, and Export X.509 Certificates?

    There is a tool named keytool ( for Solaris ) ( for Windows ) that can be used to create public/private key pairs and self-signed X.509 v3 certificates, and to manage keystores. Keys and certificates are used to digitally sign your Java applications and applets (see the jarsigner ( for Solaris ) ( for Windows ) tool).

    A keystore is a protected database that holds keys and certificates. Access to a keystore is guarded by a password (defined at the time the keystore is created, by the person who creates the keystore, and changeable only when providing the current password). In addition, each private key in a keystore can be guarded by its own password.

    Using keytool, it is possible to display, import, and export X.509 v1, v2, and v3 certificates stored as files, and to generate new self-signed v3 certificates. For examples, see the "EXAMPLES" section of the keytool documentation ( for Solaris ) ( for Windows ).

    Copyright © 1995-2006 Sun Microsystems, Inc. All Rights Reserved. Please send comments to: java-security@sun.com

            Sun
    Java Software Division


Java(TM) PKI API Programmer's Guide

JavaTM PKI Programmer's Guide

Overview

Acknowledgments
 Who Should Read This Document
 Related Documentation
 Introduction

Core Classes and Interfaces

Basic Classes

      • The CertPath Class

      • The CertificateFactory Class

      • The CertPathParameters Interface

Certification Path Validation Classes

      • The CertPathValidator Class

      • The CertPathValidatorResult Interface

Certification Path Building Classes

      • The CertPathBuilder Class

      • The CertPathBuilderResult Interface

Certificate/CRL Storage Classes

      • The CertStore Class

      • The CertStoreParameters Interface

        • The LDAPCertStoreParameters Class

        • The CollectionCertStoreParameters Class

      • The CertSelector and CRLSelector Interfaces

        • The X509CertSelector Class

        • The X509CRLSelector Class

PKIX Classes

    • The TrustAnchor Class

    • The PKIXParameters Class

    • The PKIXCertPathValidatorResult Class

    • The PolicyNode Interface and PolicyQualifierInfo Class

    • The PKIXBuilderParameters Class

    • The PKIXCertPathBuilderResult Class

    • The PKIXCertPathChecker Class

Implementing a Service Provider

Appendix A: Standard Names

Appendix B: The "SUN" Provider

Appendix C: On-Line Certificate Status Protocol (OCSP) Support

Overview

The JavaTM Certification Path API consists of classes and interfaces for handling certification paths (also known as "certificate chains"). A certification path is an ordered list of certificates. If a certification path meets certain validation rules, it may be used to securely establish the mapping of a public key to a subject.

This API defines interfaces and abstract classes for creating, building, and validating certification paths. Implementations may be plugged in using a provider-based interface. The API is based on the Cryptographic Service Provider architecture, described in the Java Cryptography Architecture Reference Guide.

The API also includes algorithm-specific classes for building and validating X.509 certification paths according to the PKIX standards. The PKIX standards are developed by the IETF PKIX working group.

This API was originally specified using the Java Community ProcessSM program as JavaTM Specification Request (JSR) 000055. The API was included in the JavaTM SDK, starting with Java 2 Standard Edition (JDK), v 1.4. Please refer to the JSR 055 Home Page for more information on the JSR.

Acknowledgments

The author would like to thank the individuals who contributed to the Certification Path API and provided useful comments and technical advice. Special thanks to the members of the Sun Microsystems Laboratories team who designed and developed the Certification Path API which provided the basis of the work for the Java Community Process. This team includes Anne Anderson, Yassir Elley, Geoff Goodell, Steve Hanna, Sean Mullan, Radia Perlman, and Seth Proctor.

The expert group helped improve and refine the API using the Java Community Process and includes the following members:

  • Peter Hesse, CygnaCom Solutions, An Entrust Technologies Company
  • Sean Mullan, Sun Microsystems (Specification Lead)
  • Anthony Nadalin, IBM
  • Bob Naugle, Bluestone Software
  • Hemma Prafullchandra, VeriSign
  • Ming Yung, DSTC
Maxine Erlund, Steve Hanna, Phil Rosenzweig and Bob Sproull of Sun Microsystems provided leadership and vision. The members of the Java Security, Networking and Naming Group of Sun Microsystems contributed invaluable comments and support, especially Sharon Liu, Jeff Nisewanger, Gary Ellison, and Andreas Sterbenz. Helpful comments and advice were received from many in the technical community, especially Mary Dageforde, Edward Dobner, Tom Gindin, Jan Luehe, David Kuehr-McLaren, Parag Salvi, Alexei Semidetnov, and Yanni Zhang.

Who Should Read This Document

This document is intended for two classes of experienced developers:

  1. those who want to design secure applications that build or validate certification paths.

  2. those who want to write a service provider implementation for building or validating certification paths.

Related Documentation

This document assumes you have already read the following documents:

  • X.509 Certificates and Certificate Revocation Lists (CRLs)

  • Java Cryptography Architecture Reference Guide

  • How to Implement a Provider for the Java Cryptography Architecture

Introduction

Users of public key applications and systems must be confident that a subject's public key is genuine, i.e., that the associated private key is owned by the subject. Public key certificates are used to establish this trust. A public key (or identity) certificate is a binding of a public key to an identity, which is digitally signed by the private key of another entity, often called a Certification Authority (CA). We shall use the term CA to refer to an entity that signs a certificate for the remainder of this section.

If the user does not have a trusted copy of the public key of the CA that signed the subject's public key certificate, then another public key certificate vouching for the signing CA is required. This logic can be applied recursively, until a chain of certificates (or a certification path) is discovered from a trust anchor or a most-trusted CA to the target subject (commonly referred to as the end-entity). The most-trusted CA is usually specified by a certificate issued to a CA that the user directly trusts. In general, a certification path is an ordered list of certificates, usually comprised of the end-entity's public key certificate and zero or more additional certificates. A certification path typically has one or more encodings, allowing it to be safely transmitted across networks and to different operating system architectures.

Figure 1 illustrates a certification path from a most-trusted CA's public key (CA 1) to the target subject (Alice). The certification path establishes trust in Alice's public key through an intermediate CA named CA2.

The previous context describes this image
Figure 1: Certification Path

A certification path must be validated before it can be relied on to establish trust in a subject's public key. Validation can consist of various checks on the certificates contained in the certification path, such as verifying the signatures and checking that each certificate has not been revoked. The PKIX standards define an algorithm for validating certification paths consisting of X.509 certificates.

Often a user may not have a certification path from a most-trusted CA to the subject. Providing services to build or discover certification paths is an important feature of public key enabled systems. RFC 2587 defines an LDAP (Lightweight Directory Access Protocol) schema definition which facilitates the discovery of X.509 certification paths using the LDAP directory service protocol.

Building and validating certification paths is an important part of many standard security protocols such as SSL/TLS, S/MIME, and IPSEC. The JavaTM Certification Path API provides a set of classes and interfaces for developers who need to integrate this functionality into their applications. This API benefits two types of developers: those who need to write service provider implementations for a specific certification path building or validation algorithm; and those who need to access standard algorithms for creating, building, and validating certification paths in an implementation-independent manner.

Core Classes and Interfaces

The core classes of the Java Certification Path API consist of interfaces and classes that support certification path functionality in an algorithm- and implementation -independent manner. The API also includes a set of algorithm-specific classes for the PKIX standards that are discussed in the section titled PKIX Classes. The API builds on and extends the existing JavaTM Standard Edition (JDK) java.security.cert package for handling certificates. The core classes can be broken up into 4 class categories: Basic, Validation, Building, and Storage:

  • Basic Certification Path Classes

    • CertPath, CertificateFactory, CertPathParameters

  • Certification Path Validation Classes

    • CertPathValidator, CertPathValidatorResult

  • Certification Path Building Classes

    • CertPathBuilder, CertPathBuilderResult

  • Certificate/CRL Storage Classes

    • CertStore, CertStoreParameters, CertSelector, CRLSelector

The following sections describe the most commonly used methods of each class and interface. Usage examples for some of the classes are interspersed throughout the guide. The complete reference documentation for the relevant Certification Path API classes can be found in:

  • java.security.cert package summary

Most of the classes and interfaces in the CertPath API are not thread-safe. However, there are some exceptions which will be noted in this guide and the API specification. Multiple threads that need to access a single non-thread-safe object concurrently should synchronize amongst themselves and provide the necessary locking. Multiple threads each manipulating separate objects need not synchronize.

Basic Certification Path Classes

The basic certification path classes provide fundamental functionality for encoding and representing certification paths. The key basic class in the Java Certification Path API is CertPath, which encapsulates the universal aspects shared by all types of certification paths. An application uses an instance of the CertificateFactory class to create a CertPath object.

The CertPath Class

The CertPath class is an abstract class for certification paths. It defines the functionality shared by all certification path objects. Various certification path types can be implemented by subclassing the CertPath class, even though they may have different contents and ordering schemes. All CertPath objects are serializable, immutable and thread-safe and share the following characteristics:

  • A type

    This corresponds to the type of the certificates in the certification path, for example: X.509. The type of a CertPath is obtained using the method:

        public String getType()

    See Appendix A in the Java Cryptography Architecture Reference Guide for information about standard certificate types.

  • A list of certificates

    The getCertificates method returns the list of certificates in the certification path:

        public abstract List<? extends Certificate> getCertificates()
    This method returns a List of zero or more java.security.cert.Certificate objects. The returned List and the Certificates contained within it are immutable, in order to protect the contents of the CertPath object.

    The ordering of the certificates returned depends on the type. By convention, the certificates in a CertPath object of type X.509 are ordered starting with the target certificate and ending with a certificate issued by the trust anchor. That is, the issuer of one certificate is the subject of the following one. The certificate representing the TrustAnchor should not be included in the certification path. Unvalidated X.509 CertPaths may not follow this convention. PKIX CertPathValidators will detect any departure from these conventions that cause the certification path to be invalid and throw a CertPathValidatorException.

  • One or more encodings

    Each CertPath object supports one or more encodings. These are external encoded forms for the certification path, used when a standard representation of the path is needed outside the Java Virtual Machine (as when transmitting the path over a network to some other party). Each path can be encoded in a default format, the bytes of which are returned using the method:

        public abstract byte[] getEncoded()
    Alternatively, the getEncoded(String) method returns a specific supported encoding by specifying the encoding format as a String (ex: "PKCS7"). A list of standard encoding formats are defined in Appendix A.

        public abstract byte[] getEncoded(String encoding)
    Also, the getEncodings method returns an iterator over the supported encoding format Strings (the default encoding format is returned first):

        public abstract Iterator<String> getEncodings()

All CertPath objects are also Serializable. CertPath objects are resolved into an alternate CertPathRep object during serialization. This allows a CertPath object to be serialized into an equivalent representation regardless of its underlying implementation.

CertPath objects are generated from an encoded byte array or list of Certificates using a CertificateFactory. Alternatively, a CertPathBuilder may be used to try to find a CertPath from a most-trusted CA to a particular subject. Once a CertPath object has been created, it may be validated by passing it to the validate method of CertPathValidator. Each of these concepts are explained in more detail in subsequent sections.

The CertificateFactory Class

The CertificateFactory class is an engine class that defines the functionality of a certificate factory. In releases prior to JDK, v 1.4 it was used to generate Certificate and CRL objects. It was enhanced in JDK, v 1.4 to also be used to generate certification path (CertPath) objects. A CertificateFactory should not be confused with a CertPathBuilder. A CertPathBuilder (discussed later) is used to discover or find a certification path when one does not exist. In contrast, a CertificateFactory is used when a certification path has already been discovered and the caller needs to instantiate a CertPath object from its contents which exist in a different form such as an encoded byte array or an array of Certificates.

Creating a CertificateFactory Object

See the CertificateFactory section in the Java Cryptography Architecture Reference Guide for details on creating a CertificateFactory object.

Generating CertPath Objects

A CertificateFactory instance generates CertPath objects from a List of Certificate objects or from an InputStream that contains the encoded form of a CertPath. Just like a CertPath, each CertificateFactory supports a default encoding format for certification paths (ex: PKCS#7). To generate a CertPath object and initialize it with the data read from an input stream (in the default encoding format), use the generateCertPath method:

    public final CertPath generateCertPath(InputStream inStream)

or from a particular encoding format:

    public final CertPath generateCertPath(InputStream inStream,
                           String encoding)

To find out what encoding formats are supported, use the getCertPathEncodings method (the default encoding is returned first):

    public final Iterator<String> getCertPathEncodings()

To generate a certification path object from a List of Certificate objects, use the following method:

    public final CertPath generateCertPath(List<? extends Certificate> certificates)

A CertificateFactory always returns CertPath objects that consist of Certificates that are of the same type as the factory. For example, a CertificateFactory of type X.509 returns CertPath objects consisting of certificates that are an instance of java.security.cert.X509Certificate.

The following code sample illustrates generating a certification path from a PKCS#7 encoded certificate reply stored in a file:

    // open an input stream to the file
    FileInputStream fis = new FileInputStream(filename);
    // instantiate a CertificateFactory for X.509
    CertificateFactory cf = CertificateFactory.getInstance("X.509");
    // extract the certification path from
    // the PKCS7 SignedData structure
    CertPath cp = cf.generateCertPath(fis, "PKCS7");
    // print each certificate in the path
    List<Certificate> certs = cp.getCertificates();
    for (Certificate cert : certs) {
        System.out.println(cert);
    }
Here's another code sample that fetches a certificate chain from a KeyStore and converts it to a CertPath using a CertificateFactory:
    // instantiate a KeyStore with type JKS
    KeyStore ks = KeyStore.getInstance("JKS");
    // load the contents of the KeyStore
    ks.load(new FileInputStream("./keystore"),
        "password".toCharArray());
    // fetch certificate chain stored with alias "sean"
    Certificate[] certArray = ks.getCertificateChain("sean");
    // convert chain to a List
    List certList = Arrays.asList(certArray);
    // instantiate a CertificateFactory for X.509
    CertificateFactory cf = CertificateFactory.getInstance("X.509");
    // extract the certification path from
    // the List of Certificates
    CertPath cp = cf.generateCertPath(certList);

Note that there is an existing method in CertificateFactory named generateCertificates that parses a sequence of Certificates. For encodings consisting of multiple certificates, use generateCertificates when you want to parse a collection of possibly unrelated certificates. Otherwise, use generateCertPath when you want to generate a CertPath and subsequently validate it with a CertPathValidator (discussed later).

The CertPathParameters Interface

The CertPathParameters interface is a transparent representation of the set of parameters used with a particular certification path builder or validation algorithm. Its main purpose is to group (and provide type safety for) all certification path parameter specifications. The CertPathParameters interface extends the Cloneable interface and defines a clone() method that does not throw an exception. All concrete implementations of this interface should implement and override the Object.clone() method, if necessary. This allows applications to clone any CertPathParameters object.

Objects implementing the CertPathParameters interface are passed as arguments to methods of the CertPathValidator and CertPathBuilder classes. Typically, a concrete implementation of the CertPathParameters interface will hold a set of input parameters specific to a particular certification path build or validation algorithm. For example, the PKIXParameters class is an implementation of the CertPathParameters interface that holds a set of input parameters for the PKIX certification path validation algorithm. One such parameter is the set of most-trusted CAs that the caller trusts for anchoring the validation process. This parameter among others is discussed in more detail in the section discussing the PKIXParameters class.

Certification Path Validation Classes

The Java Certification Path API includes classes and interfaces for validating certification paths. An application uses an instance of the CertPathValidator class to validate a CertPath object. If successful, the result of the validation algorithm is returned in an object implementing the CertPathValidatorResult interface.

The CertPathValidator Class

The CertPathValidator class is an engine class used to validate a certification path.

Creating a CertPathValidator Object

As with all engine classes, the way to get a CertPathValidator object for a particular validation algorithm is to call one of the getInstance static factory methods on the CertPathValidator class:

    public static CertPathValidator getInstance(String algorithm)
        public static CertPathValidator getInstance(String algorithm,
                            String provider)
        public static CertPathValidator getInstance(String algorithm,
                            Provider provider)
The algorithm parameter is the name of a certification path validation algorithm (for example, "PKIX"). Standard CertPathValidator algorithm names are listed in Appendix A.

Validating a Certification Path

Once a CertPathValidator object is created, paths can be validated by calling the validate method, passing it the certification path to be validated and a set of algorithm-specific parameters:

    public final CertPathValidatorResult
            validate(CertPath certPath, CertPathParameters params)
        throws CertPathValidatorException,
               InvalidAlgorithmParameterException

If the validation algorithm is successful, the result is returned in an object implementing the CertPathValidatorResult interface. Otherwise, a CertPathValidatorException is thrown. The CertPathValidatorException contains methods that return the CertPath, and if relevant, the index of the certificate that caused the algorithm to fail and the root exception or cause of the failure.

Note that the CertPath and CertPathParameters passed to the validate method must be of a type that is supported by the validation algorithm. Otherwise, an InvalidAlgorithmParameterException is thrown. For example, a CertPathValidator instance that implements the PKIX algorithm validates CertPath objects of type X.509 and CertPathParameters that are an instance of PKIXParameters.

The CertPathValidatorResult Interface

The CertPathValidatorResult interface is a transparent representation of the successful result or output of a certification path validation algorithm. Its main purpose is to group (and provide type safety for) all validation results. Like the CertPathParameters interface, CertPathValidatorResult extends Cloneable and defines a clone() method that does not throw an exception. This allows applications to clone any CertPathValidatorResult object.

Objects implementing the CertPathValidatorResult interface are returned by the validate method of CertPathValidator (only when successful; otherwise a CertPathValidatorException is thrown with a description of the failure). Typically, a concrete implementation of the CertPathValidatorResult interface will hold a set of output parameters specific to a particular certification path validation algorithm. For example, the PKIXCertPathValidatorResult class is an implementation of the CertPathValidatorResult interface which contains methods to get the output parameters of the PKIX certification path validation algorithm. One such parameter is the valid policy tree. This parameter among others is discussed in more detail in the section discussing the PKIXCertPathValidatorResult class.

Here's a simplified code sample that illustrates how to create a CertPathValidator and use it to validate a certification path. The sample assumes that the CertPath and CertPathParameters objects which are passed to the validate method have been previously created; a more complete example will be illustrated in the section describing the PKIX classes.

    // create CertPathValidator that implements the "PKIX" algorithm
    CertPathValidator cpv = null;
    try {
        cpv = CertPathValidator.getInstance("PKIX");
    } catch (NoSuchAlgorithmException nsae) {
    System.err.println(nsae);
    System.exit(1);
    }
    // validate certification path ("cp") with specified parameters ("params")
    try {
        CertPathValidatorResult cpvResult = cpv.validate(cp, params);
    } catch (InvalidAlgorithmParameterException iape) {
    System.err.println("validation failed: " + iape);
    System.exit(1);
    } catch (CertPathValidatorException cpve) {
    System.err.println("validation failed: " + cpve);
    System.err.println("index of certificate that caused exception: "
        + cpve.getIndex());
    System.exit(1);
    }

Certification Path Building Classes

The Java Certification Path API includes classes for building (or discovering) certification paths. An application uses an instance of the CertPathBuilder class to build a CertPath object. If successful, the result of the build is returned in an object implementing the CertPathBuilderResult interface.

The CertPathBuilder Class

The CertPathBuilder class is an engine class used to build a certification path.

Creating a CertPathBuilder Object

As with all engine classes, the way to get a CertPathBuilder object for a particular build algorithm is to call one of the getInstance static factory method on the CertPathBuilder class:

    public static CertPathBuilder getInstance(String algorithm)
    public static CertPathBuilder getInstance(String algorithm,
                          String provider)
        public static CertPathBuilder getInstance(String algorithm,
                              Provider provider)
The algorithm parameter is the name of a certification path builder algorithm (for example, "PKIX"). Standard CertPathBuilder algorithm names are listed in Appendix A.

Building a Certification Path

Once a CertPathBuilder object is created, paths can be constructed by calling the build method, passing it an algorithm-specific parameter specification:

    public final CertPathBuilderResult build(CertPathParameters params)
        throws CertPathBuilderException,
               InvalidAlgorithmParameterException

If the build algorithm is successful, the result is returned in an object implementing the CertPathBuilderResult interface. Otherwise, a CertPathBuilderException is thrown containing information about the failure; for example, the underlying exception (if any) and an error message.

Note that the CertPathParameters passed to the build method must be of a type that is supported by the build algorithm. Otherwise, an InvalidAlgorithmParameterException is thrown.

The CertPathBuilderResult Interface

The CertPathBuilderResult interface is a transparent representation of the result or output of a certification path builder algorithm. This interface contains a method to return the certification path that has been successfully built:

    public CertPath getCertPath()

The purpose of the CertPathBuilderResult interface is to group (and provide type safety for) all build results. Like the CertPathValidatorResult interface, CertPathBuilderResult extends Cloneable and defines a clone() method that does not throw an exception. This allows applications to clone any CertPathBuilderResult object.

Objects implementing the CertPathBuilderResult interface are returned by the build method of CertPathBuilder.

Here's a simplified code sample that illustrates how to create a CertPathBuilder and use it to build a certification path. The sample assumes that the CertPathParameters object which is passed to the build method has been previously created; a more complete example will be illustrated in the section describing the PKIX classes.

    // create CertPathBuilder that implements the "PKIX" algorithm
    CertPathBuilder cpb = null;
    try {
        cpb = CertPathBuilder.getInstance("PKIX");
    } catch (NoSuchAlgorithmException nsae) {
    System.err.println(nsae);
    System.exit(1);
    }
    // build certification path using specified parameters ("params")
    try {
        CertPathBuilderResult cpbResult = cpb.build(params);
        CertPath cp = cpbResult.getCertPath();
        System.out.println("build passed, path contents: " + cp);
    } catch (InvalidAlgorithmParameterException iape) {
    System.err.println("build failed: " + iape);
    System.exit(1);
    } catch (CertPathBuilderException cpbe) {
    System.err.println("build failed: " + cpbe);
    System.exit(1);
    }

Certificate/CRL Storage Classes

The Java Certification Path API also includes the CertStore class for retrieving certificates and CRLs from a repository. This is useful because it allows a caller to specify the repository a CertPathValidator or CertPathBuilder implementation should use to find certificates and CRLs (see the addCertStores method of PKIXParameters for an example).

A CertPathValidator implementation may use the CertStore object that the caller specifies as a callback mechanism to fetch CRLs for performing revocation checks. Similarly, a CertPathBuilder may use the CertStore as a callback mechanism to fetch certitificates and, if performing revocation checks, CRLs.

The CertStore Class

The CertStore class is an engine class used to provide the functionality of a certificate and certificate revocation list (CRL) repository. It can be used by CertPathBuilder and CertPathValidator implementations to find certificates and CRLs or as a general purpose certificate and CRL retrieval mechanism.

Unlike the java.security.KeyStore class, which provides access to a cache of private keys and trusted certificates, a CertStore is designed to provide access to a potentially vast repository of untrusted certificates and CRLs. For example, an LDAP implementation of CertStore provides access to certificates and CRLs stored in one or more directories using the LDAP protocol.

All public methods of CertStore objects are thread-safe. That is, multiple threads may concurrently invoke these methods on a single CertStore object (or more than one) with no ill effects. This allows a CertPathBuilder to search for a CRL while simultaneously searching for further certificates, for instance.

Creating a CertStore Object

As with all engine classes, the way to get a CertStore object for a particular repository type is to call one of the getInstance static factory methods on the CertStore class:

    public static CertStore getInstance(String type,
        CertStoreParameters params)
    public static CertStore getInstance(String type,
        CertStoreParameters params, String provider)
    public static CertStore getInstance(String type,
        CertStoreParameters params, Provider provider)
The type parameter is the name of a certificate repository type (for example, "LDAP"). Standard CertStore types are listed in Appendix A.

The initialization parameters (params) are specific to the repository type. For example, the initialization parameters for a server-based repository may include the hostname and the port of the server. An InvalidAlgorithmParameterException is thrown if the parameters are invalid for this CertStore type. The getCertStoreParameters method returns the CertStoreParameters that were used to initialize a CertStore:

    public final CertStoreParameters getCertStoreParameters()

Retrieving Certificates

Once you have created a CertStore object, you can retrieve certificates from the repository using the getCertificates method. This method takes a CertSelector (discussed in more detail later) object as an argument, which specifies a set of selection criteria for determining which certificates should be returned:

    public final Collection<? extends Certificate> getCertificates(CertSelector selector)
        throws CertStoreException

This method returns a Collection of java.security.cert.Certificate objects that satisfy the selection criteria. An empty Collection is returned if there are no matches. A CertStoreException is usually thrown if an unexpected error condition is encountered, such as a communications failure with a remote repository.

For some CertStore implementations, it may not be feasible to search the entire repository for certificates or CRLs that match the specified selection criteria. In these instances, the CertStore implementation may use information that is specified in the selectors to locate certificates and CRLs. For instance, an LDAP CertStore may not search all entries in the directory. Instead, it may just search entries that are likely to contain the certificates it is looking for. If the CertSelector provided does not provide enough information for the LDAP CertStore to determine which entries it should look in, the LDAP CertStore may throw a CertStoreException.

Retrieving CRLs

You can also retrieve CRLs from the repository using the getCRLs method. This method takes a CRLSelector (discussed in more detail later) object as an argument, which specifies a set of selection criteria for determining which CRLs should be returned:

    public final Collection<? extends CRL> getCRLs(CRLSelector selector)
        throws CertStoreException

This method returns a Collection of java.security.cert.CRL objects that satisfy the selection criteria. An empty Collection is returned if there are no matches.

The CertStoreParameters Interface

The CertStoreParameters interface is a transparent representation of the set of parameters used with a particular CertStore. Its main purpose is to group (and provide type safety for) all certificate storage parameter specifications. The CertStoreParameters interface extends the Cloneable interface and defines a clone method that does not throw an exception. Implementations of this interface should implement and override the Object.clone() method, if necessary. This allows applications to clone any CertStoreParameters object.

Objects implementing the CertStoreParameters interface are passed as arguments to the getInstance method of the CertStore class. Two classes implementing the CertStoreParameters interface are defined in this API: the LDAPCertStoreParameters and the CollectionCertStoreParameters classes.

The LDAPCertStoreParameters Class

The LDAPCertStoreParameters class is an implementation of the CertStoreParameters interface and holds a set of minimal initialization parameters (host and port number of the directory server) for retrieving certificates and CRLs from a CertStore of type LDAP.

Please refer to the LDAPCertStoreParameters API documentation for more detailed information on this class.

The CollectionCertStoreParameters Class

The CollectionCertStoreParameters class is an implementation of the CertStoreParameters interface and holds a set of initialization parameters for retrieving certificates and CRLs from a CertStore of type Collection.

Please refer to the CollectionCertStoreParameters API documentation for more detailed information on this class.

The CertSelector and CRLSelector Interfaces

The CertSelector and CRLSelector interfaces are a specification of the set of criteria for selecting certificates and CRLs from a collection or large group of certificates and CRLs. The interfaces group and provide type safety for all selector specifications. Each selector interface extends Cloneable and defines a clone() method that does not throw an exception. This allows applications to clone any CertSelector or CRLSelector object.

The CertSelector and CRLSelector interfaces each define a method named match. The match method takes a Certificate or CRL object as an argument and returns true if the object satisfies the selection criteria. Otherwise, it returns false. The match method for the CertSelector interface is defined as follows:

    public boolean match(Certificate cert)

and for the CRLSelector interface:

    public boolean match(CRL crl)

Typically, objects implementing these interfaces are passed as parameters to the getCertificates and getCRLs methods of the CertStore class. These methods return a Collection of Certificates or CRLs from the CertStore repository that match the specified selection criteria. CertSelectors may also be used to specify the validation constraints on a target or end-entity certificate in a certification path (see for example, the PKIXParameters.setTargetCertConstraints method.

The X509CertSelector Class

The X509CertSelector class is an implementation of the CertSelector interface that defines a set of criteria for selecting X.509 certificates. An X509Certificate object must match all of the specified criteria to be selected by the match method. The selection criteria are designed to be used by a CertPathBuilder implementation to discover potential certificates as it builds an X.509 certification path.

For example, the setSubject method of X509CertSelector allows a PKIX CertPathBuilder to filter out X509Certificates that do not match the issuer name of the preceding X509Certificate in a partially completed chain. By setting this and other criteria in an X509CertSelector object, a CertPathBuilder is able to discard irrelevant certificates and more easily find an X.509 certification path that meets the requirements specified in the CertPathParameters object.

Please refer to http://www.ietf.org/rfc/rfc3280.txt for definitions of the X.509 certificate extensions mentioned in this section.

Creating an X509CertSelector Object

An X509CertSelector object is created by calling the default constructor:

    public X509CertSelector()

No criteria are initially set (any X509Certificate will match).

Setting Selection Criteria

The selection criteria allow a caller to match on different components of an X.509 certificate. A few of the methods for setting selection criteria are described here. Please refer to the X509CertSelector API documentation for details on the other methods.

The setIssuer methods set the issuer criterion:

    public void setIssuer(X500Principal issuer)
    public void setIssuer(String issuerDN)
    public void setIssuer(byte[] issuerDN)

The specified distinguished name (in X500Principal, RFC 2253 String or ASN.1 DER encoded form) must match the issuer distinguished name in the certificate. If null, any issuer distinguished name will do. Note that use of an X500Principal to represent a distinguished name is preferred because it is more efficient and suitably typed.

Similarly, the setSubject methods set the subject criterion:

    public void setSubject(X500Principal subject)
    public void setSubject(String subjectDN)
    public void setSubject(byte[] subjectDN)

The specified distinguished name (in X500Principal, RFC 2253 String or ASN.1 DER encoded form) must match the subject distinguished name in the certificate. If null, any subject distinguished name will do.

The setSerialNumber method sets the serialNumber criterion:

    public void setSerialNumber(BigInteger serial)

The specified serial number must match the certificate serial number in the certificate. If null, any certificate serial number will do.

The setAuthorityKeyIdentifier method sets the authorityKeyIdentifier criterion:

    public void setAuthorityKeyIdentifier(byte[] authorityKeyID)

The certificate must contain an Authority Key Identifier extension matching the specified value. If null, no check will be done on the authorityKeyIdentifier criterion.

The setCertificateValid method sets the certificateValid criterion:

    public void setCertificateValid(Date certValid)

The specified date must fall within the certificate validity period for the certificate. If null, any date is valid.

The setKeyUsage method sets the keyUsage criterion:

    public void setKeyUsage(boolean[] keyUsage)

The certificate's Key Usage Extension must allow the specified key usage values (those which are set to true). If null, no keyUsage check will be done.

Getting Selection Criteria

The current values for each of the selection criteria can be retrieved using an appropriate get method. Please refer to the X509CertSelector API documentation for further details on these methods.

Example

Here is an example of retrieving X.509 certificates from an LDAP CertStore with the X509CertSelector class.

First, we create the LDAPCertStoreParameters object that we will use to initialize the CertStore object with the hostname and port of the LDAP server:

    LDAPCertStoreParameters lcsp = new
        LDAPCertStoreParameters("ldap.sun.com", 389);

Next, create the CertStore object, and pass it the LDAPCertStoreParameters object, as in the following statement:

    CertStore cs = CertStore.getInstance("LDAP", lcsp);

This call creates a CertStore object that retrieves certificates and CRLs from an LDAP repository using the schema defined in RFC 2587.

The following block of code establishes an X509CertSelector to retrieve all unexpired (as of the current date and time) end-entity certificates issued to a particular subject with 1) a key usage that allows digital signatures, and 2) a subject alternative name with a specific email address:

    X509CertSelector xcs = new X509CertSelector();
    // select only unexpired certificates
    xcs.setCertificateValid(new Date());
    // select only certificates issued to
    // 'CN=alice, O=xyz, C=us'
    xcs.setSubject(new X500Principal("CN=alice, O=xyz, C=us"));
    // select only end-entity certificates
    xcs.setBasicConstraints(-2);
    // select only certificates with a digitalSignature
    // keyUsage bit set (set the first entry in the
    // boolean array to true)
    boolean[] keyUsage = {true};
    xcs.setKeyUsage(keyUsage);
    // select only certificates with a subjectAltName of
    // 'alice@xyz.com' (1 is the integer value of
    // an RFC822Name)
    xcs.addSubjectAlternativeName(1, "alice@xyz.com");

Then we pass the selector to the getCertificates method of our CertStore object that we previously created:

    Collection<Certificate> certs = cs.getCertificates(xcs);

A PKIX CertPathBuilder may use similar code to help discover and sort through potential certificates by discarding those that do not meet validation constraints or other criteria.

The X509CRLSelector Class

The X509CRLSelector class is an implementation of the CRLSelector interface that defines a set of criteria for selecting X.509 CRLs. An X509CRL object must match all of the specified criteria to be selected by the match method. The selection criteria are designed to be useful to a CertPathValidator or CertPathBuilder implementation that must retrieve CRLs from a repository to check the revocation status of certificates in an X.509 certification path.

For example, the setDateAndTime method of X509CRLSelector allows a PKIX CertPathValidator to filter out X509CRLs that have been issued after or expire before the time indicated. By setting this and other criteria in an X509CRLSelector object, it allows the CertPathValidator to discard irrelevant CRLs and more easily check if a certificate has been revoked.

Please refer to http://www.ietf.org/rfc/rfc3280.txt for definitions of the X.509 CRL fields and extensions mentioned in this section.

Creating an X509CRLSelector Object

An X509CRLSelector object is created by calling the default constructor:

    public X509CRLSelector()

No criteria are initially set (any X509CRL will match).

Setting Selection Criteria

The selection criteria allow a caller to match on different components of an X.509 CRL. Most of the methods for setting selection criteria are described here. Please refer to the X509CRLSelector API documentation for details on the remaining methods.

The setIssuers and setIssuerNames methods set the issuerNames criterion:

    public void setIssuers(Collection<X500Principal> issuers)
    public void setIssuerNames(Collection<?> names)

The issuer distinguished name in the CRL must match at least one of the specified distinguished names. The setIssuers method is preferred as the use of X500Principals to represent distinguished names is more efficient and suitably typed. For the setIssuerNames method, each entry of the names argument is either a String or a byte array (representing the name, in RFC 2253 or ASN.1 DER encoded form, respectively). If null, any issuer distinguished name will do.

The setMinCRLNumber and setMaxCRLNumber methods set the minCRLNumber and maxCRLNumber criterion:

    public void setMinCRLNumber(BigInteger minCRL)
    public void setMaxCRLNumber(BigInteger maxCRL)

The CRL must have a CRL Number extension whose value is greater than or equal to the specified value if the setMinCRLNumber method is called, and less than or equal to the specified value if the setMaxCRLNumber method is called. If the value passed to one of these methods is null, the corresponding check is not done.

The setDateAndTime method sets the dateAndTime criterion:

    public void setDateAndTime(Date dateAndTime)

The specified date must be equal to or later than the value of the thisUpdate component of the CRL and earlier than the value of the nextUpdate component. If null, no dateAndTime check will be done.

The setCertificateChecking method sets the certificate whose revocation status is being checked:

    public void setCertificateChecking(X509Certificate cert)

This is not a criterion. Rather, it is optional information that may help a CertStore find CRLs that would be relevant when checking revocation for the specified certificate. If null is specified, then no such optional information is provided. An application should always call this method when checking revocation for a particular certificate, as it may provide the CertStore with more information for finding the correct CRLs and filtering out irrelevant ones.

Getting Selection Criteria

The current values for each of the selection criteria can be retrieved using an appropriate get method. Please refer to the X509CRLSelector API documentation for further details on these methods.

Example

Creating an X509CRLSelector to retrieve CRLs from an LDAP repository is similar to the X509CertSelector example. Suppose we want to retrieve all current (as of the current date and time) CRLs issued by a specific CA and with a minimum CRL number. First, we create an X509CRLSelector object and call the appropriate methods to set the selection criteria:

    X509CRLSelector xcrls = new X509CRLSelector();
    // select CRLs satisfying current date and time
    xcrls.setDateAndTime(new Date());
    // select CRLs issued by 'O=xyz, C=us'
    xcrls.addIssuerName("O=xyz, C=us");
    // select only CRLs with a CRL number at least '2'
    xcrls.setMinCRLNumber(new BigInteger("2"));

Then we pass the selector to the getCRLs method of our CertStore object (created in the X509CertSelector example):

    Collection<CRL> crls = cs.getCRLs(xcrls);

PKIX Classes

The Java Certification Path API also includes a set of algorithm-specific classes modelled for use with the PKIX certification path validation algorithm defined in RFC 3280: Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile.

The TrustAnchor Class

This class represents a "most-trusted CA", which is used as a trust anchor for validating X.509 certification paths. A most-trusted CA includes the public key of the CA, the CA's name, and any constraints upon the set of paths which may be validated using this key. These parameters can be specified in the form of a trusted X509Certificate or as individual parameters.

All TrustAnchor objects are immutable and thread-safe. That is, multiple threads may concurrently invoke the methods defined in this class on a single TrustAnchor object (or more than one) with no ill effects. Requiring TrustAnchor objects to be immutable and thread-safe allows them to be passed around to various pieces of code without worrying about coordinating access.

Note that although this class is described as a PKIX class it may be used with other X.509 certification path validation algorithms.

Creating a TrustAnchor Object

To instantiate a TrustAnchor object, a caller must specify "the most-trusted CA" as a trusted X509Certificate or public key and distinguished name pair. The caller may also optionally specify name constraints that are applied to the trust anchor by the validation algorithm during initialization. Note that support for name constraints on trust anchors is not required by the PKIX algorithm, therefore a PKIX CertPathValidator or CertPathBuilder may choose not to support this parameter and instead throw an exception. Use one of the following constructors to create a TrustAnchor object:

    public TrustAnchor(X509Certificate trustedCert,
        byte[] nameConstraints)
    public TrustAnchor(X500Principal caPrincipal, PublicKey pubKey,
        byte[] nameConstraints)
    public TrustAnchor(String caName, PublicKey pubKey,
        byte[] nameConstraints)

The nameConstraints parameter is specifed as a byte array containing the ASN.1 DER encoding of a NameConstraints extension. An IllegalArgumentException is thrown if the name constraints cannot be decoded (are not formatted correctly).

Getting Parameter Values

Each of the parameters can be retrieved using a corresponding get method:

    public final X509Certificate getTrustedCert()
    public final X500Principal getCA()
    public final String getCAName()
    public final PublicKey getCAPublicKey()
    public final byte[] getNameConstraints()
Note that the getTrustedCert method returns null if the trust anchor was specified as a public key and name pair. Likewise, the getCA, getCAName and getCAPublicKey methods return null if the trust anchor was specified as an X509Certificate.

The PKIXParameters Class

This class (which implements the CertPathParameters interface) specifies the set of input parameters defined by the PKIX certification path validation algorithm. It also includes a few additional useful parameters.

An X.509 CertPath object and a PKIXParameters object are passed as arguments to the validate method of a CertPathValidator instance implementing the PKIX algorithm. The CertPathValidator uses the parameters to initialize the PKIX certification path validation algorithm.

Creating a PKIXParameters Object

To instantiate a PKIXParameters object, a caller must specify "the most-trusted CA(s)" as defined by the PKIX validation algorithm. The most-trusted CAs can be specified using one of two constructors:

    public PKIXParameters(Set<TrustAnchor> trustAnchors)
        throws InvalidAlgorithmParameterException
    public PKIXParameters(KeyStore keystore)
        throws KeyStoreException, InvalidAlgorithmParameterException

The first constructor allows the caller to specify the most-trusted CAs as a Set of TrustAnchor objects. Alternatively, a caller can use the second constructor and specify a KeyStore instance containing trusted certificate entries, each of which will be considered as a most-trusted CA.

Setting Parameter Values

Once a PKIXParameters object has been created, a caller can set (or replace the current value of) various parameters. A few of the methods for setting parameters are described here. Please refer to the PKIXParameters API documentation for details on the other methods.

The setInitialPolicies method sets the initial policy identifiers, as specified by the PKIX validation algorithm. The elements of the Set are object identifiers (OIDs) represented as a String. If the initialPolicies parameter is null or not set, any policy is acceptable:

    public void setInitialPolicies(Set<String> initialPolicies)

The setDate method sets the time for which the validity of the path should be determined. If the date parameter is not set or is null, the current date is used:

    public void setDate(Date date)

The setPolicyMappingInhibited method sets the value of the policy mapping inhibited flag. The default value for the flag, if not specified, is false:

    public void setPolicyMappingInhibited(boolean val)

The setExplicitPolicyRequired method sets the value of the explicit policy required flag. The default value for the flag, if not specified, is false:

    public void setExplicitPolicyRequired(boolean val)

The setAnyPolicyInhibited method sets the value of the any policy inhibited flag. The default value for the flag, if not specified, is false:

    public void setAnyPolicyInhibited(boolean val)

The setTargetCertConstraints method allows the caller to set constraints on the target or end-entity certificate. For example, the caller can specify that the target certificate must contain a specific subject name. The constraints are specified as a CertSelector object. If the selector parameter is null or not set, no constraints are defined on the target certificate:

    public void setTargetCertConstraints(CertSelector selector)

The setCertStores method allows a caller to specify a List of CertStore objects that will be used by a PKIX implementation of CertPathValidator to find CRLs for path validation. This provides an extensible mechanism for specifying where to locate CRLs. The setCertStores method takes a List of CertStore objects as a parameter. The first CertStores in the list may be preferred to those that appear later.

    public void setCertStores(List<CertStore> stores)

The setCertPathCheckers method allows a caller to extend the PKIX validation algorithm by creating implementation-specific certification path checkers. For example, this mechanism can be used to process private certificate extensions. The setCertPathCheckers method takes a list of PKIXCertPathChecker (discussed later) objects as a parameter:

    public void setCertPathCheckers(List<PKIXCertPathChecker> checkers)

The setRevocationEnabled method allows a caller to disable revocation checking. Revocation checking is enabled by default, since it is a required check of the PKIX validation algorithm. However, PKIX does not define how revocation should be checked. An implementation may use CRLs or OCSP, for example. This method allows the caller to disable the implementation's default revocation checking mechanism if it is not appropriate. A different revocation checking mechanism can then be specified by calling the setCertPathCheckers method, and passing it a PKIXCertPathChecker that implements the alternate mechanism.

    public void setRevocationEnabled(boolean val)

The setPolicyQualifiersRejected method allows a caller to enable or disable policy qualifier processing. When a PKIXParameters object is created, this flag is set to true. This setting reflects the most common (and simplest) strategy for processing policy qualifiers. Applications that want to use a more sophisticated policy must set this flag to false.

    public void setPolicyQualifiersRejected(boolean qualifiersRejected)

Getting Parameter Values

The current values for each of the parameters can be retrieved using an appropriate get method. Please refer to the PKIXParameters API documentation for further details on these methods.

The PKIXCertPathValidatorResult Class

This class (which implements the CertPathValidatorResult interface) represents the result of the PKIX certification path validation algorithm. It holds the valid policy tree and subject public key resulting from the validation algorithm, and includes methods (getPolicyTree() and getPublicKey()) for returning them. Instances of PKIXCertPathValidatorResult are returned by the validate method of CertPathValidator objects implementing the PKIX algorithm.

Please refer to the PKIXCertPathValidatorResult API documentation for more detailed information on this class.

The PolicyNode Interface and PolicyQualifierInfo Class

The PKIX validation algorithm defines several outputs related to certificate policy processing. Most applications will not need to use these outputs, but all providers that implement the PKIX validation or building algorithm must support them.

The PolicyNode interface represents a node of a valid policy tree resulting from a successful execution of the PKIX certification path validation. An application can obtain the root of a valid policy tree using the getPolicyTree method of PKIXCertPathValidatorResult. Policy Trees are discussed in more detail in the PKIX Certificate and CRL Profile.

The getPolicyQualifiers method of PolicyNode returns a Set of PolicyQualifierInfo objects, each of which represents a policy qualifier contained in the Certificate Policies extension of the relevant certificate that this policy applies to.

Most applications will not need to examine the valid policy tree and policy qualifiers. They can achieve their policy processing goals by setting the policy-related parameters in PKIXParameters. However, the valid policy tree is available for more sophisticated applications, especially those that process policy qualifiers.

Please refer to the PolicyNode and PolicyQualifierInfo API documentation for more detailed information on these classes.

Example of Validating a Certification Path using the PKIX algorithm

This is an example of validating a certification path with the PKIX validation algorithm. The example ignores most of the exception handling and assumes that the certification path and public key of the trust anchor have already been created.

First, create the CertPathValidator, as in the following line:

    CertPathValidator cpv = CertPathValidator.getInstance("PKIX");

The next step is to create a TrustAnchor object. This will be used as an anchor for validating the certification path. In this example, the most-trusted CA is specified as a public key and name (name constraints are not applied and are specified as null):

    TrustAnchor anchor = new TrustAnchor("O=xyz,C=us", pubkey, null);

The next step is to create a PKIXParameters object. This will be used to populate the parameters used by the PKIX algorithm. In this example, we pass to the constructor a Set containing a single element - the TrustAnchor we created in the previous step:

    PKIXParameters params = new PKIXParameters(Collections.singleton(anchor));

Next, we populate the parameters object with constraints or other parameters used by the validation algorithm. In this example, we enable the explicitPolicyRequired flag and specify a set of initial policy OIDs (the contents of the set are not shown):

    // set other PKIX parameters here
    params.setExplicitPolicyRequired(true);
    params.setInitialPolicies(policyIds);

The final step is to validate the certification path using the input parameter set we have created:

    try {
        PKIXCertPathValidatorResult result =
            (PKIXCertPathValidatorResult) cpv.validate(certPath, params);
        PolicyNode policyTree = result.getPolicyTree();
        PublicKey subjectPublicKey = result.getPublicKey();
    } catch (CertPathValidatorException cpve) {
        System.out.println("Validation failure, cert["
            + cpve.getIndex() + "] :" + cpve.getMessage());
    }

If the validation algorithm is successful, the policy tree and subject public key resulting from the validation algorithm are obtained using the getPolicyTree and getPublicKey methods of PKIXCertPathValidatorResult.

Otherwise, a CertPathValidatorException is thrown and the caller can catch the exception and print some details about the failure, such as the error message and the index of the certificate that caused the failure.

The PKIXBuilderParameters Class

This class (which extends the PKIXParameters class) specifies the set of parameters to be used with CertPathBuilders that build certification paths validated against the PKIX certification path validation algorithm.

A PKIXBuilderParameters object is passed as an argument to the build method of a CertPathBuilder instance implementing the PKIX algorithm. All PKIX CertPathBuilders must return certification paths which have been validated according to the PKIX certification path validation algorithm.

Please note that the mechanism that a PKIX CertPathBuilder uses to validate a constructed path is an implementation detail. For example, an implementation might attempt to first build a path with minimal validation and then fully validate it using an instance of a PKIX CertPathValidator, whereas a more efficient implementation may validate more of the path as it is building it, and backtrack to previous stages if it encounters validation failures or dead-ends.

Creating a PKIXBuilderParameters Object

Creating a PKIXBuilderParameters object is similar to creating a PKIXParameters object. However, a caller must specify constraints on the target or end-entity certificate when creating a PKIXBuilderParameters object. These constraints should provide the CertPathBuilder with enough information to find the target certificate. The constraints are specified as a CertSelector object. Use one of the following constructors to create a PKIXBuilderParameters object:

    public PKIXBuilderParameters(Set<TrustAnchor> trustAnchors,
        CertSelector targetConstraints)
        throws InvalidAlgorithmParameterException
    public PKIXBuilderParameters(KeyStore keystore,
        CertSelector targetConstraints)
        throws KeyStoreException, InvalidAlgorithmParameterException

Getting/Setting Parameter Values

The PKIXBuilderParameters class inherits all of the parameters that can be set in the PKIXParameters class. In addition, the setMaxPathLength method can be called to place a limit on the maximum number of certificates in a certification path:

    public void setMaxPathLength(int maxPathLength)

The maxPathLength parameter specifies the maximum number of non-self-issued intermediate certificates that may exist in a certification path. A CertPathBuilder instance implementing the PKIX algorithm must not build paths longer than the length specified. If the value is 0, the path can only contain a single certificate. If the value is -1, the path length is unconstrained (i.e., there is no maximum). The default maximum path length, if not specified, is 5. This method is useful to prevent the CertPathBuilder from spending resources and time constructing long paths that may or may not meet the caller's requirements.

If any of the CA certificates in the path contain a Basic Constraints extension, the value of the pathLenConstraint component of the extension overrides the value of the maxPathLength parameter whenever the result is a certification path of smaller length. There is also a corresponding getMaxPathLength method for retrieving this parameter:

    public int getMaxPathLength()

Also, the setCertStores method (inherited from the PKIXParameters class) is typically used by a PKIX implementation of CertPathBuilder to find Certificates for path construction as well as finding CRLs for path validation. This provides an extensible mechanism for specifying where to locate Certificates and CRLs.

The PKIXCertPathBuilderResult Class

This class (which extends the PKIXCertPathValidatorResult class and implements the CertPathBuilderResult interface) represents the successful result of the PKIX certification path construction algorithm. Instances of PKIXCertPathBuilderResult are returned by the build method of CertPathBuilder objects implementing the PKIX algorithm.

The getCertPath method of a PKIXCertPathBuilderResult instance always returns a CertPath object validated using the PKIX certification path validation algorithm. The returned CertPath object does not include the most-trusted CA certificate that may have been used to anchor the path. Instead, use the getTrustAnchor method to get the Certificate of the most-trusted CA.

Please refer to the PKIXCertPathBuilderResult API documentation for more detailed information on this class.

Example of Building a Certification Path using the PKIX algorithm

This is an example of of building a certification path validated against the PKIX algorithm. Some details have been left out, such as exception handling, and the creation of the trust anchors and certificates for populating the CertStore.

First, create the CertPathBuilder, as in the following example:

    CertPathBuilder cpb = CertPathBuilder.getInstance("PKIX");

This call creates a CertPathBuilder object that returns paths validated against the PKIX algorithm.

The next step is to create a PKIXBuilderParameters object. This will be used to populate the PKIX parameters used by the CertPathBuilder:

    // Create parameters object, passing it a Set of
    // trust anchors for anchoring the path
    // and a target subject DN.
    X509CertSelector targetConstraints = new X509CertSelector();
    targetConstraints.setSubject("CN=alice,O=xyz,C=us");
    PKIXBuilderParameters params =
        new PKIXBuilderParameters(trustAnchors, targetConstraints);

The next step is to specify the CertStore that the CertPathBuilder will use to look for certificates and CRLs. For this example, we will populate a Collection CertStore with the certificates and CRLs:

    CollectionCertStoreParameters ccsp =
    new CollectionCertStoreParameters(certsAndCrls);
    CertStore store = CertStore.getInstance("Collection", ccsp);
    params.addCertStore(store);

The next step is to build the certification path using the input parameter set we have created:

    try {
        PKIXCertPathBuilderResult result =
        (PKIXCertPathBuilderResult) cpb.build(params);
        CertPath cp = result.getCertPath();
    } catch (CertPathBuilderException cpbe) {
    System.out.println("build failed: " + cpbe.getMessage());
    }

If the CertPathBuilder cannot build a path that meets the supplied parameters it will throw a CertPathBuilderException. Otherwise, the validated certification path can be obtained from the PKIXCertPathBuilderResult using the getCertPath method.

The
PKIXCertPathChecker Class

This section
describes a powerful class that allows a user to extend a PKIX
CertPathValidator or CertPathBuilder
implementation. This is an advanced feature that most users will not
need to understand. However, anyone implementing a PKIX service
provider should read this section.

The
PKIXCertPathChecker class is an abstract class that executes
one or more checks on an X.509 certificate. Developers should create
concrete implementations of the PKIXCertPathChecker class
when it is necessary to dynamically extend a PKIX CertPathValidator
or CertPathBuilder implementation at runtime. The following
are a few examples of when a PKIXCertPathChecker
implementation is useful:

    • If the revocation mechanism
    supplied by a PKIX CertPathValidator or CertPathBuilder
    implementation is not adequate. For example, a developer might
    implement a PKIXCertPathChecker that uses OCSP (
    RFC 2560)
    to check that certificates have not been revoked.

    • If the user wants to recognize
    certificates containing a critical private extension. Since the
    extension is private, it will not be recognized by the PKIX
    CertPathValidator or CertPathBuilder
    implementation and a CertPathValidatorException will be
    thrown. In this case, a developer can implement a
    PKIXCertPathChecker that recognizes and processes the
    critical private extension.

    • If the developer wants to record
    information about each certificate processed for debugging or
    display purposes.

    • If the user wants to reject
    certificates with certain policy qualifiers.

The
setCertPathCheckers method of the PKIXParameters
class allows a user to pass a List
of PKIXCertPathChecker objects to a PKIX CertPathValidator
or CertPathBuilder implementation. Each of the
PKIXCertPathChecker objects will be called in turn, for each
certificate processed by the PKIX CertPathValidator or
CertPathBuilder implementation.

Creating and using a
PKIXCertPathChecker Object

The
PKIXCertPathChecker class does not have a public
constructor. This is intentional, since creating an instance of
PKIXCertPathChecker is an implementation-specific issue. For
example, the constructor for a PKIXCertPathChecker
implementation that uses OCSP to check a certificate's revocation
status may require the hostname and port of the OCSP server:

    PKIXCertPathChecker checker = new OCSPChecker("ocsp.sun.com", 1321);

Once the checker
has been instantiated, it can be added as a parameter using the
addCertPathChecker method of the PKIXParameters
class:

    params.addCertPathChecker(checker);

Alternatively, a
List of checkers can be added using the setCertPathCheckers
method of the PKIXParameters class.

Implementing a PKIXCertPathChecker Object

The
PKIXCertPathChecker class is abstract. It has four methods
(check, getSupportedExtensions, init, and
isForwardCheckingSupported) that all concrete subclasses
must implement.

Implementing a
PKIXCertPathChecker may be trivial or complex. A
PKIXCertPathChecker implementation can be stateless or
stateful. A stateless implementation does not maintain state between
successive calls of the check method. For example, a
PKIXCertPathChecker that checks that each certificate
contains a particular policy qualifier is stateless. In contrast, a
stateful implementation does maintain state between successive calls
of the check method. The check method of a stateful
implementation usually depends on the contents of prior certificates
in the certification path. For example, a PKIXCertPathChecker
that processes the NameConstraints extension is stateful.

Also, the order
in which the certificates processed by a service provider
implementation are presented (passed) to a PKIXCertPathChecker
is very important, especially if the implementation is stateful.
Depending on the algorithm used by the service provider, the
certificates may be presented in reverse or forward
order. A reverse ordering means that the certificates are ordered
from the most trusted CA (if present) to the target subject, whereas
a forward ordering means that the certificates are ordered from the
target subject to the most trusted CA. The order must be made known
to the PKIXCertPathChecker implementation, so that it knows
how to process consecutive certificates.

Initializing a
PKIXCertPathChecker Object

The init
method initializes the internal state of the checker:

    public abstract void init(boolean forward)

All stateful
implementations should clear or initialize any internal state in the
checker. This prevents a service provider implementation from calling
a checker that is in an uninitialized state. It also allows stateful
checkers to be reused in subsequent operations without
reinstantiating them. The forward parameter indicates the
order of the certificates presented to the PKIXCertPathChecker.
If forward is true, the certificates are presented
from target to trust anchor; if false, from trust anchor to
target.

Forward
Checking

The
isForwardCheckingSupported method returns a boolean
that indicates if the PKIXCertPathChecker supports forward
checking:

    public abstract boolean isForwardCheckingSupported()

All
PKIXCertPathChecker implementations must
support reverse checking. A PKIXCertPathChecker
implementation may
support forward checking.

Supporting forward checking improves the efficiency of
CertPathBuilders that build forward, since it allows
paths to be checked as they are built. However, some stateful
PKIXCertPathCheckers may find it difficult or impossible
to support forward checking.

Supported
Extensions

The
getSupportedExtensions method returns an immutable Set
of OID Strings for the X.509 extensions that the
PKIXCertPathChecker implementation supports (i.e.,
recognizes, is able to process):

    public abstract Set<String> getSupportedExtensions()

The method
should return null if no extensions are processed. All
implementations should return the Set of OID Strings
that the check method may process.

A CertPathBuilder can use this information to
identify certificates with unrecognized critical extensions, even
when performing a forward build with a PKIXCertPathChecker
that does not support forward checking.

Executing the
Check

The following
method executes a check on the certificate:

    public abstract void
            check(Certificate cert, Collection<String> unresolvedCritExts)
            throws CertPathValidatorException

The
unresolvedCritExts parameter contains a collection of OIDs
as Strings. These OIDs represent the set of critical
extensions in the certificate that have not yet been resolved by the
certification path validation algorithm. Concrete implementations of
the check method should remove any critical extensions that
it processes from the unresolvedCritExts parameter.

If the
certificate does not pass the check(s), a CertPathValidatorException
should be thrown.

Cloning a
PKIXCertPathChecker

The
PKIXCertPathChecker class implements the Cloneable
interface. All stateful PKIXCertPathChecker implementations
must override the clone method if necessary. The default
implementation of the clone method calls the Object.clone
method, which performs a simple clone by copying all fields of the
original object to the new object. A stateless implementation should
not override the clone method. However, all stateful
implementations must ensure that the default clone method is
correct, and override it if necessary. For example, a
PKIXCertPathChecker that stores state in an array must
override the clone method to make a copy of the array,
rather than just a reference to the array.

The reason that
PKIXCertPathChecker objects are Cloneable is to
allow a PKIX CertPathBuilder implementation to efficiently
backtrack and try another path when a potential certification path
reaches a dead end or point of failure. In this case, the
implementation is able to restore prior path validation states by
restoring the cloned objects.

Example

This is an
example of a stateless PKIXCertPathChecker implementation.
It checks if a private extension exists in a certificate and
processes it according to some rules.

    import java.security.cert.Certificate;
    import java.security.cert.X509Certificate;
    import java.util.Collection;
    import java.util.Collections;
    import java.util.Set;
    import java.security.cert.PKIXCertPathChecker;
    import java.security.cert.CertPathValidatorException;

    public class MyChecker extends PKIXCertPathChecker {
        private static Set supportedExtensions =
            Collections.singleton("2.16.840.1.113730.1.1");

        /*
          * Initialize checker
         */
        public void init(boolean forward)
        throws CertPathValidatorException {
        // nothing to initialize
        }

        public Set getSupportedExtensions() {
        return supportedExtensions;
        }

        public boolean isForwardCheckingSupported() {
        return true;
        }

        /*
         * Check certificate for presence of Netscape's
         * private extension
         * with OID "2.16.840.1.113730.1.1"
         */
        public void check(Certificate cert,
                  Collection unresolvedCritExts)
        throws CertPathValidatorException
        {
        X509Certificate xcert = (X509Certificate) cert;
            byte[] ext =
            xcert.getExtensionValue("2.16.840.1.113730.1.1");
        if (ext == null)
            return;

        //
          // process private extension according to some
        // rules - if check fails, throw a
        // CertPathValidatorException ...
        // {insert code here}

        // remove extension from collection of unresolved
        // extensions (if it exists)
        if (unresolvedCritExts != null)
            unresolvedCritExts.remove("2.16.840.1.113730.1.1");
        }
    }

How a PKIX Service Provider implementation should use a
PKIXCertPathChecker

Each
PKIXCertPathChecker object must be initialized by a service
provider implementation before commencing the build or validation
algorithm, for example:

    List<PKIXCertPathChecker> checkers = params.getCertPathCheckers();
    for (PKIXCertPathChecker checker : checkers) {
        checker.init(false);
    }

For each
certificate that it validates, the service provider implementation
must call the check method of each PKIXCertPathChecker
object in turn, passing it the certificate and any remaining
unresolved critical extensions:

    for (PKIXCertPathChecker checker : checkers) {
        checker.check(cert, unresolvedCritExts);
    }

If any of the
checks throw a CertPathValidatorException, a
CertPathValidator implementation should terminate the validation
procedure. However, a CertPathBuilder implementation may
simply log the failure and continue to search for other potential
paths. If all of the checks are successful, the service
provider implementation should check that all critical extensions
have been resolved and if not, consider the validation to have failed.
For example:

    if (unresolvedCritExts != null &&
        !unresolvedCritExts.isEmpty())
    {
            // note that a CertPathBuilder may have an enclosing
            // try block to catch the exception below and continue on error
        throw new CertPathValidatorException
        ("Unrecognized Critical Extension");
    }

As discussed in
the previous section, a CertPathBuilder implementation may
need to backtrack when a potential certification path reaches a dead
end or point of failure. Backtracking in this context implies
returning to the previous certificate in the path and checking for
other potential paths. If the CertPathBuilder implementation
is validating the path as it is building it, it will need to restore
the previous state of each PKIXCertPathChecker.
It can do this by making clones of the PKIXCertPathChecker
objects before each certificate is processed, for example:

    /* clone checkers */
    List newList = new ArrayList(checkers);
    ListIterator li = newList.listIterator();
    while (li.hasNext()) {
        PKIXCertPathChecker checker = (PKIXCertPathChecker) li.next();
        li.set(checker.clone());
    }

Implementing
a Service Provider

This section is intended for
    experienced programmers wishing to create their own provider
    packages supplying certification path service implementations. This
    section assumes you have read the document: How
    to Implement a Provider for the Java Cryptography Architecture.

The following engine classes are
    defined in the Java Certification Path API:

  • CertPathValidator
        - used to validate certification paths

  • CertPathBuilder
        - used to build certification paths

  • CertStore
        - used to retrieve certificates and CRLs from a repository

In addition, the pre-existing
    CertificateFactory engine
    class was enhanced in the JDK, v 1.4 to support generation of
    certification paths.

The application interfaces supplied
    by an engine class are implemented in terms of a "Service
    Provider Interface" (SPI). The name of each SPI class is the
    same as that of the corresponding engine class, followed by "Spi".
    For example, the SPI class corresponding to the CertPathValidator
    engine class is the CertPathValidatorSpi class. Each SPI
    class is abstract. To supply the implementation of a particular type
    of service, for a specific algorithm or type, a provider must subclass the
    corresponding SPI class and provide implementations for all the
    abstract methods. For example, the CertStore class provides
    access to the functionality of retrieving certificates and CRLs from
    a repository. The actual implementation supplied in a CertStoreSpi
    subclass would be that for a specific type of certificate
    repository, such as LDAP.

Steps to Implement and Integrate a Provider

Developers should follow the
    required steps
    listed in the How To Implement A Provider for the Java
    Cryptography Architecture document.
    Here are some additional rules to follow for certain steps:

    Step 3: Write your "Master
        Class", a subclass of Provider

    These are the properties that must
        be defined for the certification path services, where the
        algorithm name is substituted
        for algName, and certstore type for storeType:

    • CertPathValidator.algName

    • CertPathBuilder.algName

    • CertStore.storeType

    See Appendix A
        for the standard names that are defined for algName
        and storeType. The value of
        each property must be the fully qualified name of the class implementing
        the specified algorithm, or certstore type. That is, it must be the
        package name followed by the class name, where the two are separated by
        a period. For example, a provider sets the CertPathValidator.PKIX
        property to have the value "sun.security.provider.certpath.PKIXCertPathValidator"
        as follows:

                      put("CertPathValidator.PKIX", "sun.security.provider.certpath.PKIXCertPathValidator")

    In addition,
        service attributes can be defined for the certification path
        services. These attributes can be used as filters for selecting
        service providers. See Appendix A for the definition of some
        standard service attributes. For example, a provider may set the
        ValidationAlgorithm service attribute to the
        name of an RFC or specification that defines the PKIX validation
        algorithm:

                      put("CertPathValidator.PKIX ValidationAlgorithm", "RFC3280");

    Step 8: Document your Provider
        and its Supported Services

    Certification path service
        providers should document the following information for each SPI:

      Certificate Factories
      A
            provider should document what types of certification paths (and
            the version numbers of the certificates in the path, if relevant)
            can be created by the factory. A provider should describe the
            ordering of the certificates in the certification path, as well as
            the contents.

      A provider should document the
            list of encoding formats supported. This is not technically
            necessary, since the client can request them by calling the
            getCertPathEncodings method. However, the documentation
            should describe each encoding format in more detail and reference
            any standards when applicable.

      Certification Path Validators

      A provider should document any relevant information regarding the
            CertPathValidator implementation, including the types of
            certification paths that it validates. In particular, a PKIX
            CertPathValidator implementation should document the
            following information:

      • The RFC or specification it is compliant with.

      • The mechanism it uses to
                check that certificates have not been revoked.

      • Any optional certificate or
                CRL extensions that it recognizes and how it processes them.

      Certification Path Builders

      A provider should document any
            relevant information regarding the CertPathBuilder
            implementation, including the types of certification paths that it
            creates and whether or not they are validated. In particular a
            PKIX CertPathBuilder implementation should document the
            following information:

      • The RFC or specification it is compliant with.

      • The mechanism it uses to
                check that certificates have not been revoked.

      • Any optional certificate or
                CRL extensions that it recognizes and how it processes them.

      • Details on the algorithm it
                uses for finding certification paths. Ex: depth-first,
                breadth-first, forward (i.e., from target to trust anchor(s)),
                reverse (i.e., from trust anchor(s) to target).

      • The algorithm it uses to
                select and sort potential certificates. For example, given two
                certificates that are potential candidates for the next
                certificate in the path, what criteria are used to select one
                before the other? What criteria are used to reject a certificate?

      • If applicable, the algorithm
                it uses for backtracking or constructing another path (i.e., when
                potential paths do not meet constraints).

      • The types of CertStore
                implementations that have been tested. The implementation should
                be designed to work with any CertStore type, but this
                information may still be useful.

      All CertPathBuilder
            implementations should provide additional debugging support, in
            order to analyze and correct potential path building problems.
            Details on how to access this debugging information should be
            documented.

      Certificate/CRL Stores

      A provider should document what
            types of certificates and CRLs (and the version numbers, if
            relevant) are retrieved by the CertStore.

      A provider should also document
            any relevant information regarding the CertStore
            implementation (such as protocols used or formats supported).
            For example, an LDAP CertStore implementation should
            describe which versions of LDAP are supported and which standard
            attributes are used for finding certificates and CRLs. It should
            also document if the implementation caches results, and for how
            long (i.e., under what conditions are they refreshed).

      If the implementation returns the
            certificates and CRLs in a particular order, it should describe
            the sorting algorithm. An implementation should also document any
            additional or default initialization parameters.

      Finally,
            an implementation should document if and how it uses information
            in the CertSelector or CRLSelector objects to
            find certificates and CRLs.

Service Interdependencies

Here are some common types of
    algorithm interdependencies in certification path service
    implementations:

    Certification Path Validation
        and Signature Algorithms

    A CertPathValidator
        implementation often requires use of a signature algorithm to
        verify each certificate's digital signature. The setSigProvider
        method of the PKIXParameters class allows a user to
        specify a specific Signature provider.

    Certification Path Builders and
        Certificate Factories

    A CertPathBuilder
        implementation will often utilize a CertificateFactory to
        generate a certification path from a list of certificates.

    CertStores and Certificate
        Factories

    A CertStore implementation
        will often utilize a CertificateFactory to generate
        certificates and CRLs from their encodings. For example, an LDAP
        CertStore implementation may use an X.509
        CertificateFactory to generate X.509 certificates and CRLs
        from their ASN.1 encoded form.

Certification Path Parameter Specification Interfaces

The Certification Path API contains
    two interfaces representing transparent specifications of
    parameters, the CertPathParameters and CertStoreParameters
    interfaces.

Two implementations of the
    CertPathParameters interface are included, the
    PKIXParameters and PKIXBuilderParameters classes.
    If you are working with PKIX certification path validation and
    algorithm parameters, you can utilize these classes. If you need
    parameters for a different algorithm, you will need to supply your
    own CertPathParameters implementation for that algorithm.

Two implementations of the
    CertStoreParameters interface are included, the
    LDAPCertStoreParameters and the
    CollectionCertStoreParameters classes. These classes are to
    be used with LDAP and Collection CertStore implementations,
    respectively. If you need parameters for a different repository
    type, you will need to supply your own CertStoreParameters
    implementation for that type.

The CertPathParameters and
    CertStoreParameters interfaces each define a
    clone method that implementations should override. A
    typical implementation will perform a "deep" copy of the object,
    such that subsequent changes to the copy will not affect the original
        (and vice versa). However, this is not an absolute requirement for
        implementations of CertStoreParameters. A shallow copy
    implementation of clone is more appropriate for
        applications that need to hold a reference to a parameter contained
        in the CertStoreParameters. For example, since
        CertStore.getInstance makes a clone of the specified
        CertStoreParamters, a shallow copy clone
    allows an application to hold a reference to and later release the
    resources of a particular CertStore initialization
    parameter, rather than waiting for the garbage collection mechanism.
    This should be done with the utmost care, since the
    CertStore may still be in use by other threads.

Certification Path Result Specification Interfaces

The Certification Path API contains
    two interfaces representing transparent specifications of
    results, the CertPathValidatorResult and
    CertPathBuilderResult interfaces.

One implementation for each of the
    interfaces is included: the PKIXCertPathValidatorResult and
    PKIXCertPathBuilderResult classes. If you are implementing
    PKIX certification path service providers, you can utilize these
    classes. If you need certification path results for a different
    algorithm, you will need to supply your own CertPathValidatorResult
    or CertPathBuilderResult implementation for that algorithm.

A PKIX implementation of a
    CertPathValidator or a CertPathBuilder may find it
    useful to store additional information in the
    PKIXCertPathValidatorResult or PKIXCertPathBuilderResult,
    such as debugging traces. In these cases, the implementation should
    implement a subclass of the appropriate result class with methods to
    retrieve the relevant information. These classes must be shipped
    with the provider classes, for example, as part of the provider JAR
    file.

Certification Path Exception Classes

    The Certification Path API contains a set of exception classes for
    handling errors. CertPathValidatorException,
    CertPathBuilderException, and CertStoreException
    are subclasses of GeneralSecurityException.

You may
    need to extend these classes in your service provider
    implementation. For example, a CertPathBuilder
    implementation may provide additional information such as debugging
    traces when a CertPathBuilderException is thrown. The
    implementation may throw a subclass of CertPathBuilderException
    that holds this information. Likewise, a CertStore
    implementation can provide additional information when a failure
    occurs by throwing a subclass of CertStoreException. Also,
    you may want to implement a subclass of CertPathValidatorException
    to describe a particular failure mode of your CertPathValidator
    implementation.

In each case, the new exception classes must
    be shipped with the provider classes, for example, as part of the
    provider JAR file. Each provider should document the exception
    subclasses.

TrustAnchor  Class

    As previously mentioned, a PKIX CertPathValidator or
    CertPathBuilder is not required to support the
    nameConstraints parameter of the TrustAnchor
    class. Implementations should throw an
    InvalidAlgorithmParameterException if this parameter
    is not supported.

Appendix A:
Standard Names

The Java Certification Path API
requires and utilizes a set of standard names for certification path
validation algorithms, encodings and certificate storage types. The standard
names previously found here in Appendix A and in the other security
specifications (JCA/JSSE/etc.) have been combined in the
Standard Names document.
Specific provider information can be found in the Sun Provider Documentation.

Please note that a service provider may choose to define a new name for
a proprietary or non-standard algorithm that is not mentioned in the Standard
Names document. However, to prevent name collisions, it is recommended that
the name be prefixed with the reverse Internet domain name of the provider's
organization (for example: com.sun.MyCertPathValidator).

Appendix B: The "SUN" Provider

The CertPath implementation in the SUN provider as of Java SE 5 passed the
Public Key Interoperability Test Suite (PKITS).

The "SUN" provider supports the following standard algorithms, types and
encodings:

  • CertificateFactory: X.509 CertPath
type with PKCS7 and PkiPath encodings

  • CertPathValidator: PKIX algorithm

  • CertPathBuilder: PKIX algorithm

  • CertStore: LDAP and Collection
CertStore types

Each of these service provider interface implementations is discussed in
more detail below.

CertificateFactory

The "SUN" provider for the CertificateFactory
engine class has been enhanced to support generation of X.509
CertPath objects. The PKCS7 and PkiPath encodings are supported.
The PKCS#7 implementation supports a subset of
RFC 2315 (only the
SignedData ContentInfo type is supported).
The certificates in the CertPath are ordered in the forward
direction (from target to trust anchor). Each certificate in the
CertPath is of type
java.security.cert.X509Certificate, and versions
1, 2 and 3 are supported.

CertPathValidator

The "SUN" provider supplies a PKIX implementation of the
CertPathValidator engine class. The implementation validates
CertPaths of type X.509 and
implements the certification path validation algorithm defined in

RFC 3280: PKIX Certificate and CRL Profile.
This implementation sets the ValidationAlgorithm service
attribute to "RFC3280".

The PKIX Certificate and CRL Profile has many optional features.
The "SUN" provider implements support for the policy mapping,
authority information access and
CRL distribution point certificate extensions, the
issuing distribution point CRL extension, and the reason code and certificate
issuer CRL entry extensions. It does not implement support for the freshest
CRL or subject information access certificate extensions. It also does not
include support for the freshest CRL and delta CRL Indicator CRL extensions
and the invalidity date and hold instruction code CRL entry extensions.

The implementation supports a CRL revocation checking mechanism that
conforms to section 6.3 of the PKIX Certificate and CRL Profile.
OCSP (RFC 2560) is also
currently supported as a built in revocation checking mechanism. See
Appendix C for more details on the
implementation and configuration and how it works in conjunction with CRLs.

The implementation does not support the nameConstraints
parameter of the TrustAnchor class and the validate
method throws an InvalidAlgorithmParameterException if it is
specified.

CertPathBuilder

The "SUN" provider supplies a PKIX implementation of the
CertPathBuilder engine class. The implementation builds
CertPaths of type X.509. Each CertPath
is validated according to the PKIX algorithm defined in

RFC 3280: PKIX Certificate and CRL Profile.
This implementation sets the ValidationAlgorithm service
attribute to "RFC3280".

The implementation requires that the targetConstraints
parameter of a PKIXBuilderParameters object is an instance
of X509CertSelector and the subject criterion is set to
 a non-null value. Otherwise the build method
throws an InvalidAlgorithmParameterException.

The implementation builds CertPath objects in a forward
direction using a depth-first algorithm. It backtracks to previous
states and tries alternate paths when a potential path is determined to
be invalid or exceeds the PKIXBuilderParameters
maxPathLength parameter.

Validation of the path is performed in the same manner as the
CertPathValidator implementation. The implementation
validates most of the path as it is being built, in order to eliminate
invalid paths earlier in the process. Validation checks that cannot
be executed on certificates ordered in a forward direction are delayed
and executed on the path after it has been constructed (but before it
is returned to the application).

When two or more potential certificates are discovered that may
lead to finding a path that meets the specified constraints, the
implementation uses the following criteria to prioritize the certificates
(in the examples below, assume a TrustAnchor distinguished name
of "ou=D,ou=C,o=B,c=A" is specified):

  1. The issuer DN of the certificate matches the
DN of one of the specified TrustAnchors (ex: issuerDN =
"ou=D,ou=C,o=B,c=A").

  2. The issuer DN of the certificate is a descendant of the DN of one of the
TrustAnchors, ordered by proximity to the anchor (ex: issuerDN =
"ou=E,ou=D,ou=C,o=B,c=A").

  3. The issuer DN of the certificate is an ancestor of the DN of one of the
TrustAnchors, ordered by proximity to the anchor (ex: issuerDN =
"ou=C,o=B,c=A".

  4. The issuer DN of the certificate is in the same namespace of one of the
TrustAnchors, ordered by proximity to the anchor (ex: issuerDN =
"ou=G,ou=C,o=B,c=A").

  5. The issuer DN of the certificate is an ancestor of the subject DN
of the certificate, ordered by proximity to the subject.

These are followed by certificates which don't meet any of the above
criteria.

This implementation has been tested with the LDAP and Collection
CertStore implementations included in this release of the
"SUN" provider.

Debugging support can be enabled by setting the
java.security.debug property to certpath. For
example:

    java -Djava.security.debug=certpath BuildCertPath

This will print additional debugging information to standard error.

CertStore

The "SUN" provider supports two implementations of the CertStore
engine class: Collection and LDAP.

Collection CertStore

The Collection CertStore implementation can hold any objects
that are an instance of java.security.cert.Certificate
or java.security.cert.CRL.

The certificates and CRLs are not returned in any particular order
and will not contain duplicates.

LDAP CertStore

The LDAP CertStore implementation retrieves certificates
and CRLs from an LDAP directory using the LDAP schema defined in
RFC 2587. The
LDAPSchema service attribute is set to "RFC2587".

The implementation fetches certificates from different
locations, depending on the values of the subject, issuer, and
basicConstraints selection criteria specified in the
X509CertSelector. It performs as many of the following
operations as possible:

  1. Subject non-null, basicConstraints <= -1="-1" Looks for certificates in the subject DN's "userCertificate" attribute.

  2. Subject non-null, basicConstraints >= -1

    Looks for certificates in the forward element of the subject DN's
"crossCertificatePair" attribute AND in the subject's
"caCertificate" attribute.

  3. Issuer non-null, basicConstraints >= -1

    Looks for certificates in the reverse element of the issuer DN's
"crossCertificatePair" attribute AND in the issuer DN's "caCertificate"
attribute.

In each case, certificates are checked using
X509CertSelector.match() before adding them to the resulting
collection.

If none of the conditions specified above applies, then an exception is
thrown to indicate that it was impossible to fetch certificates using
the criteria supplied. Note that even if one or more of the conditions
apply, the Collection returned may still be empty if there are no
certificates in the directory.

The implementation fetches CRLs from the issuer DNs specified
in the setCertificateChecking, addIssuerName or
setIssuerNames methods of the X509CRLSelector class.
If no issuer DNs have been specified using one of these methods, the
implementation throws an exception indicating it was impossible to
fetch CRLs using the criteria supplied. Otherwise, the CRLs are searched as
follows:

The implementation first creates a list of issuer names. If a certificate
was specified in the setCertificateChecking method, it uses the
issuer of that certificate. Otherwise, it uses the issuer names specified
using the addIssuerName or setIssuerNames methods.

Next, the implementation iterates through the list of issuer names.
For each issuer name, it searches first in the issuer's
"authorityRevocationList" attribute and then, if no matching CRL was found
there, in the issuer's "certificateRevocationList" attribute.
One exception to the above is that if the issuer name was obtained from
the certificate specified in the setCertificateChecking method,
it only checks the issuer's "authorityRevocationList" attribute if the
specified certificate is a CA certificate.

All CRLs are checked using X509CRLSelector.match() before
adding them to the resulting collection.

If no CRLs satisfying the selection criteria can be found, an empty
Collection is returned.

Caching

By default each LDAP CertStore instance caches lookups for a
maximum of 30 seconds. The cache lifetime can be changed by
setting the system property
sun.security.certpath.ldap.cache.lifetime to a
value in seconds. A value of 0 disables the cache
completely. A value of -1 means unlimited lifetime.

Support for the CRL Distribution Points Extension

Support for the CRL Distribution Points extension is available.
It is disabled by default for compatibility and can be enabled by
setting the system property com.sun.security.enableCRLDP to the
value true.

Support for the Authority Information Access (AIA)
Extension

Limited support for the caIssuers access method of the Authority Information
Access extension is available. It is disabled by default for compatibility
and can be enabled by setting the system property
com.sun.security.enableAIAcaIssuers to the value
true.

If set to true, Sun's PKIX implementation of CertPathBuilder uses
the information in a certificate's AIA extension (in addition to
CertStores that are specified) to find the issuing CA certificate,
provided the following criteria are met:

  1. The URI is of type LDAP

We plan to remove the above limitation in a future release.

Note: Depending on your network and firewall setup, it may be
necessary to also configure your networking proxy servers as described
in the networking documentation.

Appendix C: On-Line Certificate Status Protocol (OCSP) Support

Client-side support for the On-Line Certificate Status Protocol (OCSP) as
defined in RFC 2560 is
supported as of JDK 5.0. OCSP checking is controlled by the following five
security properties:

Property Name
 | Description

ocsp.enable
 | This property's value is either true or false.
If true, OCSP checking is enabled when doing certificate
revocation checking; if false or not set, OCSP checking
is disabled.

ocsp.responderURL

This property's value is a URL that identifies the location of the
OCSP responder.
Here is an example.

ocsp.responderURL=http://ocsp.example.net:80

By default, the location of the OCSP responder is
determined implicitly from the certificate being validated. The
property is used when the Authority Information Access extension
(defined in RFC 3280) is absent from the certificate or when it
requires overriding.

ocsp.responderCertSubjectName

This property's value is the
subject name of the OCSP responder's certificate.
Here is an example.

ocsp.responderCertSubjectName="CN=OCSP Responder, O=XYZ Corp"

By default, the certificate of the OCSP responder is that of the issuer
of the certificate being validated. This property identifies the certificate
of the OCSP responder when the default does not apply. Its value is a string
distinguished name (defined in RFC 2253) which identifies a certificate in
the set of certificates supplied during cert path validation. In cases where
the subject name alone is not sufficient to uniquely identify the certificate,
then both the ocsp.responderCertIssuerName and
ocsp.responderCertSerialNumber properties must be used instead. When th
is
property is set, then those two properties are ignored.

ocsp.responderCertIssuerName
This property's value is the issuer name of the OCSP responder's certificate
.
Here is an example.

ocsp.responderCertIssuerName="CN=Enterprise CA, O=XYZ Corp"

By default, the certificate of the OCSP responder is that of the issuer
of the certificate being validated. This property identifies the certificate
of the OCSP responder when the default does not apply. Its value is a string
distinguished name (defined in RFC 2253) which identifies a certificate in
the set of certificates supplied during cert path validation. When this
property is set then the ocsp.responderCertSerialNumber
property must also be set.
Note that this property is ignored when
the ocsp.responderCertSubjectName property has been set.

ocsp.responderCertSerialNumber

This property's value is the serial number of the OCSP responder's certificate
Here is an example.

ocsp.responderCertSerialNumber=2A:FF:00

By default, the certificate of the OCSP responder is that of the
issuer of the certificate being validated. This property identifies
the certificate of the OCSP responder when the default does not
apply. Its value is a string of hexadecimal digits (colon or space
separators may be present) which identifies a certificate in the set
of certificates supplied during cert path validation. When this
property is set then the ocsp.responderCertIssuerName
property must also be set. Note that this property is ignored when
the ocsp.responderCertSubjectName property has been set.

These properties may be set either staticly in the Java runtime's
$JAVA_HOME/jre/lib/security/java.security file, or
dynamically using the java.security.Security.setProperty()
method.

By default, OCSP checking is not enabled. It is enabled by setting the
ocsp.enable property to "true". Use of the remaining
properties is optional. Note that enabling OCSP checking only has an
effect if revocation checking has also been enabled.
Revocation checking is enabled via the
 PKIXParameters.setRevocationEnabled()   method.

OCSP checking works in conjunction with Certificate Revocation Lists (CRLs)
during revocation checking.  Below is a summary of the interaction of
OCSP and CRLs. Failover to CRLs occurs only if an OCSP problem is
encountered. Failover does not occur if the OCSP responder confirms
either that the certificate has been revoked or that it has not been
revoked.

PKIXParameters RevocationEnabled (default=true)
 | ocsp.enable (default=false)
 | Behavior

true
true
Revocation checking using OCSP,

failover to using CRLs

true
 | false
 | Revocation checking using CRLs only

false
 | true
 | No revocation checking

false
 | false
 | No revocation checking

   Copyright © 1998-2006, Sun Microsystems, Inc.
   4150 Network Circle
   Santa Clara, California 95054
   All Rights Reserved.

   Please send comments to: java-security@sun.com. This is not a subscription list.


How to Implement a Provider
in the
Java ™ Cryptography Architecture

Introduction

Who Should Read This Document

Related Documentation

Notes on Terminology

Engine Classes and Corresponding SPI Classes

Steps to Implement and Integrate a Provider

Step 1: Write your Service Implementation Code

Step 1.1: Additional JCA Provider Requirements and Recommendations for Encryption Implementations

Step 2: Give your Provider a Name

Step 3: Write your Master Class, a subclass of Provider

Step 3.1: Additional Steps for Cipher Implementations

Step 4: Compile your Code

Step 5: Place your Provider in a Jar File

Step 6: Optional -- Sign your JAR File

Step 6.1: Get a Code-Signing Certificate

Step 6.2: Sign Your Provider

Step 7: Prepare for Testing

Step 7.1: Install the Provider

Step 7.2: Set Provider Permissions

Step 8: Write and Compile your Test Programs

Step 9: Run your Test Programs

Step 10: Apply for U.S.Government Export Approval if Required

Step 11: Document your Provider and its Supported Services

Message Digests and MACs

Step 12: Make your Class Files and Documentation Available to Clients

How a Provider Can Do Self-Integrity Checking

Notes on the Sample Code

Finding the Provider JAR File: Basics

Determining the Provider's JAR File URL

Creating a JarFile Referring to the JAR File

Verifying the Provider JAR File: Basics

Verification Setup

JAR File Signature Check

Verifying Signatures

Ensuring Signers Are Trusted

Getting the List of Certificates

Identifying Each of the Signers and Determining If One is Trusted

Notes on myJCE Sample Code

Further Implementation Details and Requirements

Alias Names

Service Interdependencies

Default Initializations

Default Key Pair Generator Parameter Requirements

The Provider.Service Class

Signature Formats

DSA Interfaces and their Required Implementations

RSA Interfaces and their Required Implementations

Diffie-Hellman Interfaces and their Required Implementations

Interfaces for Other Algorithm Types

Algorithm Parameter Specification Interfaces and Classes

Key Specification Interfaces and Classes Required by Key Factories

Secret-Key Generation

Ensuring Exportability

Appendix A: The Sun Provider Master Class

Appendix B: The SunJCE Provider Master Class

Appendix C: The java.security Properties File

Introduction

The Java platform defines a set of APIs spanning major security areas, including cryptography, public key infrastructure, authentication, secure communication, and access control. These APIs allow developers to easily integrate security into their application code. They were designed around the following principles:

  1. Implementation independence

    Applications do not need to implement security themselves. Rather, they can request security services from the Java platform. Security services are implemented in providers (see below), which are plugged into the Java platform via a standard interface. An application may rely on multiple independent providers for security functionality.
  2. Implementation interoperability

    Providers are interoperable across applications. Specifically, an application is not bound to a specific provider, and a provider is not bound to a specific application.
  3. Algorithm extensibility

    The Java platform includes a number of built-in providers that implement a basic set of security services that are widely used today. However, some applications may rely on emerging standards not yet implemented, or on proprietary services. The Java platform supports the installation of custom providers that implement such services.

A Cryptographic Service Provider (provider) refers to a package (or a set of packages) that supply a concrete implementation of a subset of the cryptography aspects of the JDK Security API.

The java.security.Provider class encapsulates the notion of a security provider in the Java platform. It specifies the provider's name and lists the security services it implements. Multiple providers may be configured at the same time, and are listed in order of preference. When a security service is requested, the highest priority provider that implements that service is selected.

Figures 1 and 2 illustrate these options for requesting an MD5 message digest implementation. Both figures show three providers that implement message digest algorithms. The providers are ordered by preference from left to right (1-3). In Figure 1, an application requests an MD5 algorithm implementation without specifying a provider name. The providers are searched in preference order and the implementation from the first provider supplying that particular algorithm, ProviderB, is returned. In Figure 2, the application requests the MD5 algorithm implementation from a specific provider, ProviderC. This time the implementation from that provider is returned, even though a provider with a higher preference order, ProviderB, also supplies an MD5 implementation.

">

Figure 1: Provider searching Figure 2: Specific provider requested

Figures 1 and 2 illustrate these options for requesting an MD5 message digest implementation. Both figures show three providers that implement message digest algorithms. The providers are ordered by preference from left to right (1-3). In Figure 1, an application requests an MD5 algorithm implementation without specifying a provider name. The providers are searched in preference order and the implementation from the first provider supplying that particular algorithm, ProviderB, is returned. In Figure 2, the application requests the MD5 algorithm implementation from a specific provider, ProviderC. This time the implementation from that provider is returned, even though a provider with a higher preference order, ProviderB, also supplies an MD5 implementation.

Each installation has one or more provider packages installed. Clients may configure their runtimes with different providers, and specify a preference order for each of them. The preference order is the order in which providers are searched for requested algorithms when no particular provider is requested.

Sun's version of the Java runtime environment comes standard with a default provider, named "SUN". Other Java runtime environments may not necessarily supply the "SUN" provider.

Who Should Read This Document

Programmers that only need to use the Java Security API to access existing cryptography algorithms and other services do not need to read this document.

This document is intended for experienced programmers wishing to create their own provider packages supplying cryptographic service implementations. It documents what you need to do in order to integrate your provider into Java so that your algorithms and other services can be found when Java Security API clients request them.

Related Documentation

This document assumes you have already read the Java Cryptography Architecture Reference Guide.

It documents the packages which contain the various classes and interfaces in the Security API.

  • java.security
  • java.security.spec
  • java.security.interfaces
  • javax.crypto
  • javax.crypto.spec
  • javax.crypto.interfaces

Notes on Terminology

  • Prior to JDK 1.4, the JCE was an unbundled product, and as such, the JCA and JCE were regularly referred to as separate, distinct components. As JCE is now bundled in JDK, the distinction is becoming less apparent. Since the JCE uses the same architecture as the JCA, the JCE should be more properly thought of as a subset of the JCA.
  • The JCA within the JDK includes two software components:
    • the framework that defines and supports cryptographic services for which providers supply implementations. This framework includes packages such as java.security, javax.crypto, javax.crypto.spec, and javax.crypto.interfaces.
    • the actual providers such as Sun, SunRsaSign, SunJCE, which contain the actual cryptographic implementations.

Throughout this document, the terms JCA by itself refers to the JCA framework. Whenever this document notes a specific JCA provider, it will be referred to explicitly by the provider name.

Engine Classes and Corresponding Service Provider Interface Classes

An engine class defines a cryptographic service in an abstract fashion (without a concrete implementation).

A cryptographic service is always associated with a particular algorithm or type. It either provides cryptographic operations (like those for digital signatures or message digests, ciphers or key agreement protocols ); generates or supplies the cryptographic material (keys or parameters) required for cryptographic operations; or generates data objects (keystores or certificates) that encapsulate cryptographic keys (which can be used in a cryptographic operation) in a secure fashion.

For example, here are four engine classes:

  • The Signature class provides access to the functionality of a digital signature algorithm.
  • A DSA KeyFactory class supplies a DSA private or public key (from its encoding or transparent specification) in a format usable by the initSign or initVerify methods, respectively, of a DSA Signature object.
  • The Cipher class provides access to the functionality of an encryption algorithm (such as DES)
  • the KeyAgreement class provides access to the functionality of a key agreement protocol (such as Diffie-Hellman)

The Java Cryptography Architecture encompasses the classes comprising the Security package that relate to cryptography, including the engine classes. Users of the API request and utilize instances of the engine classes to carry out corresponding operations. The JDK defines the following engine classes:

  • MessageDigest - used to calculate the message digest (hash) of specified data.
  • Signature - used to sign data and verify digital signatures.
  • KeyPairGenerator - used to generate a pair of public and private keys suitable for a specified algorithm.

  • KeyFactory - used to convert opaque cryptographic keys of type Key into key specifications (transparent representations of the underlying key material), and vice versa.
  • KeyStore - used to create and manage a keystore. A keystore is a database of keys. Private keys in a keystore have a certificate chain associated with them, which authenticates the corresponding public key. A keystore also contains certificates from trusted entities.
  • CertificateFactory - used to create public key certificates and Certificate Revocation Lists (CRLs).
  • AlgorithmParameters - used to manage the parameters for a particular algorithm, including parameter encoding and decoding.
  • AlgorithmParameterGenerator - used to generate a set of parameters suitable for a specified algorithm.
  • SecureRandom - used to generate random or pseudo-random numbers.
  • Cipher: used to encrypt or decrypt some specified data.
  • KeyAgreement: used to execute a key agreement (key exchange) protocol between 2 or more parties.
  • KeyGenerator: used to generate a secret (symmetric) key suitable for a specified algorithm.
  • Mac: used to compute the message authentication code of some specified data.
  • SecretKeyFactory: used to convert opaque cryptographic keys of type SecretKey into key specifications (transparent representations of the underlying key material), and vice versa.
  • ExemptionMechanism: used to provide the functionality of an exemption mechanism such as key recovery, key weakening, key escrow, or any other (custom) exemption mechanism. Applications or applets that use an exemption mechanism may be granted stronger encryption capabilities than those which don't. However, please note that cryptographic restrictions are no longer required for most countries, and thus exemption mechanisms may only be useful in those few countries whose governments mandate restrictions.

Note: A generator creates objects with brand-new contents, whereas a factory creates objects from existing material (for example, an encoding).

An engine class provides the interface to the functionality of a specific type of cryptographic service (independent of a particular cryptographic algorithm). It defines Application Programming Interface (API) methods that allow applications to access the specific type of cryptographic service it provides. The actual implementations (from one or more providers) are those for specific algorithms. For example, the Signature engine class provides access to the functionality of a digital signature algorithm. The actual implementation supplied in a SignatureSpi subclass (see next paragraph) would be that for a specific kind of signature algorithm, such as SHA1 with DSA, SHA1 with RSA, or MD5 with RSA.

The application interfaces supplied by an engine class are implemented in terms of a Service Provider Interface (SPI). That is, for each engine class, there is a corresponding abstract SPI class, which defines the Service Provider Interface methods that cryptographic service providers must implement.

An instance of an engine class, the "API object", encapsulates (as a private field) an instance of the corresponding SPI class, the "SPI object". All API methods of an API object are declared "final", and their implementations invoke the corresponding SPI methods of the encapsulated SPI object. An instance of an engine class (and of its corresponding SPI class) is created by a call to the getInstance factory method of the engine class.

The name of each SPI class is the same as that of the corresponding engine class, followed by "Spi". For example, the SPI class corresponding to the Signature engine class is the SignatureSpi class.

Each SPI class is abstract. To supply the implementation of a particular type of service and for a specific algorithm, a provider must subclass the corresponding SPI class and provide implementations for all the abstract methods.

Another example of an engine class is the MessageDigest class, which provides access to a message digest algorithm. Its implementations, in MessageDigestSpi subclasses, may be those of various message digest algorithms such as SHA-1, MD5, or MD2.

As a final example, the KeyFactory engine class supports the conversion from opaque keys to transparent key specifications, and vice versa. See Key Specification Interfaces and Classes Required by Key Factories for details. The actual implementation supplied in a KeyFactorySpi subclass would be that for a specific type of keys, e.g., DSA public and private keys.

Steps to Implement and Integrate a Provider

Follow the steps below to implement a provider and integrate it into the JCA framework:

Step 1: Write your Service Implementation Code

Step 1.1: Additional JCA Provider Requirements and Recommendations for Encryption Implementations

Step 2: Give your Provider a Name

Step 3: Write your Master Class, a subclass of Provider

Step 4: Compile your Code

Step 5: Place your Provider in a JAR file

Step 6: Optional -- Sign your JAR File

Step 6.1: Get a Code-Signing Certificate

Step 6.2: Sign your Provider

Step 7: Prepare for Testing

Step 7.1: Install the Provider

Step 7.2: Set Provider Permissions

Step 8: Write and Compile Test Programs

Step 9: Run your Test Programs

Step 10: Apply for U.S. Government Export Approval If Required

Step 11: Document your Provider and its Supported Services

Step 12: Make Your Class Files and Documentation Available to Clients

Step 1: Write your Service Implementation Code

The first thing you need to do is to write the code that provides algorithm-specific implementations of the cryptographic services you want to support.

Note that your provider may supply implementations of cryptographic services already available in one or more of the security components of the JDK.

For cryptographic services not defined in JCA (For example; signatures and message digests), please refer to Java Cryptography Architecture Reference Guide.

For each cryptographic service you wish to implement, create a subclass of the appropriate SPI class. JCA defines the following engine classes:

  • SignatureSpi
  • MessageDigestSpi
  • KeyPairGeneratorSpi
  • SecureRandomSpi
  • AlgorithmParameterGeneratorSpi
  • AlgorithmParametersSpi
  • KeyFactorySpi
  • CertificateFactorySpi
  • KeyStoreSpi
  • CipherSpi
  • KeyAgreementSpi
  • KeyGeneratorSpi
  • MacSpi
  • SecretKeyFactorySpi
  • ExemptionMechanismSpi

(See Engine Classes and Corresponding SPI Classes in this document for information on the JCA and other cryptographic classes.)

In your subclass, you need to:

  1. Supply implementations for the abstract methods, whose names usually begin with engine. See Further Implementation Details and Requirements for additional information.
  2. Ensure there is a public constructor without any arguments. Here's why: When one of your services is requested, Java Security looks up the subclass implementing that service, as specified by a property in your "master class" (see Step 3). Java Security then creates the Class object associated with your subclass, and creates an instance of your subclass by calling the newInstance method on that Class object. newInstance requires your subclass to have a public constructor without any parameters.
  3. A default constructor without arguments will automatically be generated if your subclass doesn't have any constructors. But if your subclass defines any constructors, you must explicitly define a public constructor without arguments.

Step 1a: Additional JCA Provider Requirements and Recommendations for Encryption Implementations

When instantiating a provider's implementation (class) of a Cipher, KeyAgreement, KeyGenerator, MAC or SecretKey factory, the framework will determine the provider's codebase (JAR file) and verify its signature. In this way, JCA authenticates the provider and ensures that only providers signed by a trusted entity can be plugged into JCA. Thus, one requirement for encryption providers is that they must be signed, as described in later steps.

In addition, each provider should perform self-integrity checking to ensure that the JAR file containing its code has not been manipulated in an attempt to invoke provider methods directly rather than through JCA. For further information, see How a Provider Can Do Self-Integrity Checking.

In order for provider classes to become unusable if instantiated by an application directly, bypassing JCA, providers should implement the following:

  • All SPI implementation classes in a provider package should be declared final (so that they cannot be subclassed), and their (SPI) implementation methods should be declared protected.

  • All crypto-related helper classes in a provider package should have package-private scope, so that they cannot be accessed from outside the provider package.

For providers that may be exported outside the U.S., CipherSpi implementations must include an implementation of the engineGetKeySize method which, given a Key, returns the key size. If there are restrictions on available cryptographic strength specified in jurisdiction policy files, each Cipher initialization method calls engineGetKeySize and then compares the result with the maximum allowable key size for the particular location and circumstances of the applet or application being run. If the key size is too large, the initialization method throws an exception.

Additional optional features that providers may implement are

  • the engineWrap and engineUnwrap methods of CipherSpi. Wrapping a key enables secure transfer of the key from one place to another. Information about wrapping and unwrapping keys is provided in the Wrapping and Unwrapping Keys section of the Java Cryptography Architecture Reference Guide.

  • one or more exemption mechanisms. An exemption mechanism is something such as key recovery, key escrow, or key weakening which, if implemented and enforced, may enable reduced cryptographic restrictions for an application (or applet) that uses it. For information on the requirements for apps that utilize exemption mechanisms, see How to Make Applications "Exempt" from Cryptographic Restrictions in the Java Cryptography Architecture Reference Guide.

Step 2: Give your Provider a Name

Decide on a name for your provider. This is the name to be used by client applications to refer to your provider.

Step 3: Write your Master Class, a subclass of Provider

The third step is to create a subclass of the java.security.Provider class.

Your subclass should be a final class, and its constructor should

  • call super, specifying the provider name (see Step 2), version number, and a string of information about the provider and algorithms it supports. For example:
        super("CryptoX", 1.0, "CryptoX provider v1.0, implementing " +
    "RSA encryption and key pair generation, and DES encryption.");
  • set the values of various properties that are required for the Java Security API to look up the cryptographic services implemented by the provider. For each service implemented by the provider, there must be a property whose name is the type of service (for example; Signature, MessageDigest, Cipher, KeyAgreement) Signature, MessageDigest, KeyPairGenerator, SecureRandom, KeyFactory, KeyStore, CertificateFactory, AlgorithmParameterGenerator, AlgorithmParameters, Cipher, KeyAgreement, KeyGenerator, Mac, SecretKeyFactory, or ExemptionMechanism) followed by a period and the name of the algorithm to which the service applies. The property value must specify the fully qualified name of the class implementing the service.

    The list below shows the various types of JCA services, where the actual algorithm name is substitued for algName:

    • Signature.algName
    • MessageDigest.algName
    • KeyPairGenerator.algName
    • SecureRandom.algName
    • AlgorithmParameterGenerator.algName
    • AlgorithmParameters.algName
    • KeyFactory.algName
    • CertificateFactory.algName
    • KeyStore.algName
    • Cipher.algName
    • KeyAgreement.algName
    • KeyGenerator.algName
    • Mac.algName
    • SecretKeyFactory.algName
    • ExemptionMechanism.algName

    In all of these except ExemptionMechanism and Cipher, algName, certType , or storeType is the "standard" name of the algorithm, certificate type, or keystore type. See Appendix A of the Java Cryptography Architecture Reference Guide for the standard names that should be used.)

    In the case of ExemptionMechanism, algName refers to the name of the exemption mechanism, which can be one of the following: KeyRecovery, KeyEscrow, or KeyWeakening. Case does not matter.

    In the case of Cipher, algName may actually represent a transformation, and may be composed of an algorithm name, a particular mode, and a padding scheme. See Appendix A of the Java Cryptography Architecture Reference Guide for details.

    The value of each property must be the fully qualified name of the class implementing the specified algorithm, certificate type, or keystore type. That is, it must be the package name followed by the class name, where the two are separated by a period.

    As an example, the default provider named SUN implements the Digital Signature Algorithm (whose standard name is SHA1withDSA) in a class named DSA in the sun.security.provider package. Its subclass of Provider (which is the Sun class in the sun.security.provider package) sets the Signature.SHA1withDSA property to have the value sun.security.provider.DSA via the following:

        put("Signature.SHA1withDSA", "sun.security.provider.DSA")

    The list below shows more properties that can be defined for the various types of services, where the actual algorithm name is substitued for algName, certificate type for certType, keystore type for storeType, and attribute name for attrName:

    • Signature.algName [one or more spaces] attrName
    • MessageDigest.algName [one or more spaces] attrName
    • KeyPairGenerator.algName [one or more spaces] attrName
    • SecureRandom.algName [one or more spaces] attrName
    • KeyFactory.algName [one or more spaces] attrName
    • CertificateFactory.certType [one or more spaces] attrName
    • KeyStore.storeType [one or more spaces] attrName
    • AlgorithmParameterGenerator.algName [one or more spaces] attrName
    • AlgorithmParameters.algName [one or more spaces] attrName
    • Cipher.algName [one or more spaces] attrName
    • KeyAgreement.algName [one or more spaces] attrName
    • KeyGenerator.algName [one or more spaces] attrName
    • Mac.algName [one or more spaces] attrName
    • SecretKeyFactory.algName [one or more spaces] attrName
    • ExemptionMechanism.algName [one or more spaces] attrName

In each of these, algName, certType, storeType, or attrName is the "standard" name of the algorithm, certificate type, keystore type, or attribute. (See Appendix A of the Java Cryptography Architecture Reference Guide for the standard names that should be used.)

For a property in the above format, the value of the property must be the value for the corresponding attribute. (See Appendix A of the Java Cryptography Architecture API Specification & Reference for the definition of each standard attribute.)

As an example, the default provider named "SUN" implements the SHA1withDSA Digital Signature Algorithm in software. In the master class for the provider "SUN", it sets the Signature.SHA1withDSA ImplementedIn to have the value Software via the following:

    put("Signature.SHA1withDSA ImplementedIn", "Software")

For further master class property setting examples, see Appendix A to view the current Sun.java source file or Appendix B to see the SunJCE provider. These files show how the Sun and SunJCE providers set properties.

Step 3.1: Additional Steps for Cipher Implementations

As mentioned above, in the case of a Cipher property, algName may actually represent a transformation. A transformation is a string that describes the operation (or set of operations) to be performed by a Cipher object on some given input. A transformation always includes the name of a cryptographic algorithm (e.g., DES), and may be followed by a mode and a padding scheme.

A transformation is of the form:

  • algorithm/mode/padding, or
  • algorithm

(In the latter case, provider-specific default values for the mode and padding scheme are used). For example, the following is a valid transformation:

    Cipher c = Cipher.getInstance("DES/CBC/PKCS5Padding");

When requesting a block cipher in stream cipher mode (for example; DES in CFB or OFB mode), a client may optionally specify the number of bits to be processed at a time, by appending this number to the mode name as shown in the following sample transformations:

    Cipher c1 = Cipher.getInstance("DES/CFB8/NoPadding");
    Cipher c2 = Cipher.getInstance("DES/OFB32/PKCS5Padding");

If a number does not follow a stream cipher mode, a provider-specific default is used. (For example, the SunJCE provider uses a default of 64 bits.)

A provider may supply a separate class for each combination of algorithm/mode/padding. Alternatively, a provider may decide to provide more generic classes representing sub-transformations corresponding to algorithm or algorithm/mode or algorithm//padding (note the double slashes); in this case the requested mode and/or padding are set automatically by the getInstance methods of Cipher, which invoke the engineSetMode and engineSetPadding methods of the provider's subclass of CipherSpi.

That is, a Cipher property in a provider master class may have one of the formats shown in the table below.

cff"> Cipher Property Format | cff"> Description
Cipher.algName | A provider's subclass of CipherSpi implements algName with pluggable mode and padding
Cipher.algName/mode | A provider's subclass of CipherSpi implements algName in the specified mode, with pluggable padding
Cipher.algName//padding | A provider's subclass of CipherSpi implements algName with the specified padding, with pluggable mode
Cipher.algName/mode/padding | A provider's subclass of CipherSpi implements algName with the specified mode and padding

(See Appendix A of the Java Cryptography Architecture Reference Guide for the standard algorithm names, modes, and padding schemes that should be used.)

For example, a provider may supply a subclass of CipherSpi that implements DES/ECB/PKCS5Padding, one that implements DES/CBC/PKCS5Padding, one that implements DES/CFB/PKCS5Padding, and yet another one that implements DES/OFB/PKCS5Padding. That provider would have the following Cipher properties in its master class:

  • Cipher.DES/ECB/PKCS5Padding
  • Cipher.DES/CBC/PKCS5Padding
  • Cipher.DES/CFB/PKCS5Padding
  • Cipher.DES/OFB/PKCS5Padding
    •

Another provider may implement a class for each of the above modes (i.e., one class for ECB, one for CBC, one for CFB, and one for OFB), one class for PKCS5Padding, and a generic DES class that subclasses from CipherSpi. That provider would have the following Cipher properties in its master class:

  • Cipher.DES
  • Cipher.DES SupportedModes
    Example: "ECB|CBC|CFB|OFB"
  • Cipher.DES SupportedPaddings
    Example: "NOPADDING|PKCS5Padding"

The getInstance factory method of the Cipher engine class follows these rules in order to instantiate a provider's implementation of CipherSpi for a transformation of the form "algorithm":

  1. Check if the provider has registered a subclass of CipherSpi for the specified "algorithm".

    If the answer is YES, instantiate this class, for whose mode and padding scheme default values (as supplied by the provider) are used.

    If the answer is NO, throw a NoSuchAlgorithmException exception.

The getInstance factory method of the Cipher engine class follows these rules in order to instantiate a provider's implementation of CipherSpi for a transformation of the form "algorithm/mode/padding":

  1. Check if the provider has registered a subclass of CipherSpi for the specified "algorithm/mode/padding" transformation.

    If the answer is YES, instantiate it.

    If the answer is NO, go to the next step.

  2. Check if the provider has registered a subclass of CipherSpi for the sub-transformation "algorithm/mode".

    If the answer is YES, instantiate it, and call engineSetPadding(padding) on the new instance.

    If the answer is NO, go to the next step.
  3. Check if the provider has registered a subclass of CipherSpi for the sub-transformation "algorithm//padding" (note the double slashes).

    If the answer is YES, instantiate it, and call engineSetMode(mode) on the new instance.

    If the answer is NO, go to the next step.
  4. Check if the provider has registered a subclass of CipherSpi for the sub-transformation "algorithm".

    If the answer is YES, instantiate it, and call engineSetMode(mode) and engineSetPadding(padding) on the new instance.

    If the answer is NO, throw a NoSuchAlgorithmException exception.

Step 4: Compile your Code

After you have created your implementation code (Step 1), given your provider a name (Step 2), and created the master class (Step 3), use the Java compiler to compile your files.

Step 5: Place Your Provider in a JAR File

Place your provider code in a JAR file, in preparation for signing it in the next step. For more information on the jar tool, see jar (for Solaris) (for Microsoft Windows).

    jar cvf <JAR file name> <list of classes, separated by spaces>

This command creates a JAR file with the specified name containing the specified classes.

Step 6: Optional -- Sign your JAR File

If your provider is supplying encryption algorithms through the Cipher KeyAgreement, KeyGenerator, Mac, or SecretKeyFactory classes, you will need to sign your JAR file so that the JCA can authenticate the code at runtime. For details, see Step 1a. If you are NOT providing an implementation of this type you can skip this step.

Step 6.1: Get a Code-Signing Certificate

The next step is to request a code-signing certificate so that you can use it to sign your provider prior to testing. The certificate will be good for both testing and production. It will be valid for 5 years.

Below are the steps you should use to get a code-signing certificate. For more information on the keytool tool, see keytool (for Solaris) (for Microsoft Windows).

  1. Use keytool to generate a DSA keypair, using DSA algorithm as an example:
        keytool -genkeypair -alias <alias> \
    -keyalg DSA -keysize 1024 \
    -dname "cn=<Company Name>, \
    ou=Java Software Code Signing,\
    o=Sun Microsystems Inc" \
    -keystore <keystore file name>\
    -storepass <keystore password>
    This will generate a DSA keypair (a public key and an associated private key) and store it in an entry in the specified keystore. The public key is stored in a self-signed certificate. The keystore entry can subsequently be accessed using the specified alias.

    The option values in angle brackets ("<" and ">") represent the actual values that must be supplied. For example, <alias> must be replaced with whatever alias name you wish to be used to refer to the newly-generated keystore entry in the future, and <keystore file name> must be replaced with the name of the keystore to be used. Note: Do not surround actual values with angle brackets. For example, if you want your alias to be myTestAlias, specify the -alias option as follows:

        -alias myTestAlias
    If you specify a keystore that doesn't yet exist, it will be created.

    Note: If command lines you type are not allowed to be as long as the keytool -genkeypair command you want to execute (for example, if you are typing to a Microsoft Windows DOS prompt), you can create and execute a plain-text batch file containing the command. That is, create a new text file that contains nothing but the full keytool -genkeypair command. (Remember to type it all on one line.) Save the file with a .bat extension. Then in your DOS window, type the file name (with its path, if necessary). This will cause the command in the batch file to be executed.

  2. Use keytool to generate a certificate signing request.
        keytool -certreq -alias <alias> \
    -file <csr file name> \
    -keystore <keystore file name> \
    -storepass <keystore password>
    Here, <alias> is the alias for the DSA keypair entry created in the previous step. This command generates a Certificate Signing Request (CSR), using the PKCS#10 format. It stores the CSR in the file whose name is specified in <csr file name>.
  3. Send the CSR, contact information, and other required documentation to the JCA Code Signing Certification Authority. Send, via email, the CSR and contact information (see below) to javasoft-cert-request@sun.com. Put the following in the Subject line of your email message:
        Request a Certificate for Signing a JCA Provider
    Put the contact information in the body of the message and send the CSR file as a plain text attachment to the message. If your mail tool has an option for specifying the encoding format to be used for attachments, select the "MIME" option.

    Note: The CSR file is just a plain text file, in Base 64 encoding. Only the first and last lines are human-readable.

    Include the following contact information in the body of your message:
    • Company Name
    • Street Address (Not a post office box)
    • City
    • State/Province
    • Country
    • Company Telephone Number
    • Company Fax Number
    • Requester Name
    • Requester Telephone Number
    • Requester Email Address
    • Brief description of your company (size, line of business, etc.)

    All of the above information is required.

  4. After the JCA Code Signing Certification Authority has received your email message, they will send you a request number via email. Please allow five business days for processing.

    Once you receive this request number, you should print, fill out and mail the Certification Form for CSPs. This form should be mailed to the address below. Be sure to include the request number on the form so that your hardcopy mailing can be matched to the email message containing your CSR and contact information.

    Sun Microsystems, Inc.
    International Trade Services/Export Compliance
    Attn: Encryption Export
    10 Network Circle MS: UMPK10-144 Menlo Park, CA 94025 .

    You can also fax paperwork as follows:

    Fax #: 408-668-0918

    Subject Line: CSR #___
    Attention: Encryption Export
    Sun Microsystems, Inc.
    International Trade Services/Export Compliance

    After the JCA Code Signing Certification Authority has received both your email message and the required form, they will authenticate you, the requester. Then they will create and sign a code-signing certificate valid for 5 years. You will receive an email message containing two plain-text file attachments: one file containing this code-signing certificate and another file containing its own CA certificate, which authenticates its public key. Please also allow five business days from receipt of your request for processing.

  5. Use keytool to import the certificates received from the CA.

    Once you have received the two certificates from the JCA Code Signing Certification Authority, you can use keytool to import them into your keystore.

    First import the CA's certificate as a "trusted certificate":
        keytool -import -alias <alias for the CA cert> \
    -file <CA cert file name> \
    -keystore <keystore file name> \
    -storepass <keystore password>
    Then import the code-signing certificate:
        keytool -import -alias <alias> \
    -file <code-signing cert file name> \
    -keystore <keystore file name> \
    -storepass <keystore password>
    Here, <alias> is the same alias as that which you created in step 1 where you generated a DSA keypair. This command replaces the self-signed certificate in the keystore entry specified by <alias> with the one signed by the JCA Code Signing Certification Authority.

Now that you have in your keystore a certificate from an entity trusted by JCA (the JCA Code Signing Certification Authority), you can place your provider code in a JAR file (Step 5) and then use that certificate to sign the JAR file (Step 6.2).

Step 6.2: Sign Your Provider

Sign the JAR file created step five with the code-signing certificate obtained in Step 6. For more information on the jarsigner tool, see jarsigner (for Solaris) (for Microsoft Windows).

    jarsigner -keystore <keystore file name> \
    -storepass <keystore password> \
    <JAR file name> <alias>

Here, <alias> is the alias into the keystore for the entry containing the code-signing certificate received from the JCA Code Signing Certification Authority (the same alias as that specified in the commands in Step 6.1).

You can test verification of the signature via the following:

    jarsigner -verify <JAR file name>

The text "jar verified" will be displayed if the verification was successful.

Step 7: Prepare for Testing

The next steps describe how to install and configure your new provider so that it is available via the JCA.

Step 7.1: Install the Provider

In order to prepare for testing your provider, you must install it in the same manner as will be done by clients wishing to use it. The installation enables Java Security to find your algorithm implementations when clients request them.

Installing a provider is done in two steps: installing the provider package classes, and configuring the provider.

Installing the Provider Classes

The first thing you must do is make your classes available so that they can be found when requested. You ship your provider classes as a JAR (Java ARchive) file.

There are a two possible ways to install provider classes:

  • Install the JAR file containing the provider classes as an installed or bundled extension.
  • Place the JAR file containing the provider classes in your CLASSPATH.

The provider JAR file will be considered an installed extension if it is placed in the standard place for the JAR files of an installed extension:

    <java-home>/lib/ext		[Solaris]
    <java-home>\lib\ext		[Windows]

Here <java-home> refers to the directory where the runtime software is installed, which is the top-level directory of the JavaTM 2 Runtime Environment (JRE) or the jre directory in the JavaTM SE (JDK) software. For example, if you have JDK 6 installed on Solaris in a directory named /home/user1/jdk1.6.0, or on Microsoft Windows in a directory named C:\jdk1.6.0, then you need to install the JAR file in the following directory:

    /home/user1/jdk1.6.0/jre/lib/ext	[Solaris]
    C:\jdk1.6.0\jre\lib\ext		[Windows]

Similarly, if you have JRE 6 installed on Solaris in a directory named /home/user1/jre1.6.0, or on Microsoft Windows in a directory named C:\jre1.6.0, you need to install the JAR file in the following directory:

    /home/user1/jre1.6.0/lib/ext	[Solaris]
    C:\jre1.6.0\lib\ext			[Windows]

For more information on installed extensions, see Installed Extensions.

For more information on bundled extensions, see Bundled Extensions.

Configuring the Provider

The next step is to add the provider to your list of approved providers. This is done statically by editing the security properties file

    <java-home>/lib/security/java.security	[Solaris]
    <java-home>\lib\security\java.security	[Windows]

Here <java-home> refers to the directory where the JRE was installed. For example, if you have JDK 6 installed on Solaris in a directory named /home/user1/jdk1.6.0, or on Microsoft indows in a directory named C:\jdk1.6.0, then you need to edit the following file:

    /home/user1/jdk1.6.0/jre/lib/security/java.security	[Solaris]
    C:\jdk1.6.0\jre\lib\security\java.security		[Windows]

Similarly, if you have the JRE 6 installed on Solaris in a directory named /home/user1/jre1.6.0, or on Windows in a directory named C:\jre1.6.0, then you need to edit this file:

    /home/user1/jre1.6.0/lib/security/java.security	[Solaris]
    C:\jre1.6.0\lib\security\java.security		[Windows]

For each provider, this file should have a statement of the following form:

    security.provider.n=masterClassName

This declares a provider, and specifies its preference order n. The preference order is the order in which providers are searched for requested algorithms when no specific provider is requested. The order is 1-based; 1 is the most preferred, followed by 2, and so on.

masterClassName must specify the fully qualified name of the provider's "master class", which you implemented in Step 3. This class is always a subclass of the Provider class.

Java comes standard with providers named SUN, SunRsaSign, and SunJCE which are automatically configured as a static provider in the java.security properties file, as follows:

    security.provider.2=sun.security.provider.Sun
    security.provider.3=sun.security.rsa.SunRsaSign
    security.provider.4=sun.security.provider.SunJCE

(The Sun provider's master class is the Sun class in the sun.security.provider package.)

The JCA provider SunJCE and other security-related providers shipped with the Java platform are also automatically configured as static providers.

To utilize another JCA provider, add a line registering the alternate provider, giving it a lower preference order than the SUN and SunRsaSign providers.

Suppose that your master class is the CryptoX class in the com.cryptox.provider package, and that you would like to make your provider the fourth preferred provider. To do so, edit the java.security file as seen below:

    security.provider.2=sun.security.provider.Sun
    security.provider.3=sun.security.rsa.SunRsaSign
    security.provider.4=com.cryptox.provider.CryptoX
    security.provider.5=sun.security.provider.SunJCE

Note: Providers may also be registered dynamically. To do so, a program (such as your test program, to be written in Step 8) can call either the addProvider or insertProviderAt method in the Security class. This type of registration is not persistent and can only be done by code which is granted the following permission:

    java.security.SecurityPermission "insertProvider.{name}"

where {name} is replaced by the actual provider name.

For example, if the provider name is "MyJCE" and if the provider's code is in the myjce_provider.jar file in the /localWork directory, then here is a sample policy file grant statement granting that permission:

    grant codeBase "file:/localWork/myjce_provider.jar" {
    permission java.security.SecurityPermission
        "insertProvider.MyJCE";
    };

Step 7.2: Set Provider Permissions

Whenever providers are not installed extensions, permissions must be granted for when applets or applications are run while a security manager is installed. There is typically a security manager installed whenever an applet is running, and a security manager may be installed for an application either via code in the application itself or via a command-line argument. Permissions do not need to be granted to installed extensions, since the default system policy file grants all permissions to installed extensions.

Whenever a client does not install your provider as an installed extension, your provider may need the following permissions granted to it in the client environment:

  • java.lang.RuntimePermission to get class protection domains. The provider may need to get its own protection domain in the process of doing self-integrity checking.
  • java.security.SecurityPermission to set provider properties.

To ensure your provider works when a security manager is installed and the provider is not an installed extension, you need to test such an installation and execution environment. In addition, prior to testing you need to grant appropriate permissions to your provider and to any other providers it uses. For example, a sample statement granting permissions to a provider whose name is "MyJCE" and whose code is in myjce_provider.jar appears below. Such a statement could appear in a policy file. In this example, the myjce_provider.jar file is assumed to be in the /localWork directory.

    grant codeBase "file:/localWork/myjce_provider.jar" {
    permission java.lang.RuntimePermission "getProtectionDomain";
    permission java.security.SecurityPermission
        "putProviderProperty.MyJCE";
    };

Step 8: Write and Compile your Test Programs

Write and compile one or more test programs that test your provider's incorporation into the Security API as well as the correctness of its algorithm(s). Create any supporting files needed, such as those for test data to be encrypted.

The first tests your program should perform are ones to ensure that your provider is found, and that its name, version number, and additional information is as expected. To do so, you could write code like the following, substituting your provider name for MyPro:

    import java.security.*;

    Provider p = Security.getProvider("MyPro");

    System.out.println("MyPro provider name is " + p.getName());
    System.out.println("MyPro provider version # is " + p.getVersion());
    System.out.println("MyPro provider info is " + p.getInfo());

Next, you should ensure that your services are found. For instance, if you implemented the DES encryption algorithm, you could check to ensure it's found when requested by using the following code (again substituting your provider name for "MyPro"):

    Cipher c = Cipher.getInstance("DES", "MyPro");

    System.out.println("My Cipher algorithm name is " + c.getAlgorithm());

If you don't specify a provider name in the call to getInstance, all registered providers will be searched, in preference order (see Configuring the Provider), until one implementing the algorithm is found.

If your provider implements an exemption mechanism, you should write a test applet or application that uses the exemption mechanism. Such an applet/application also needs to be signed, and needs to have a "permission policy file" bundled with it. See How to Make Applications "Exempt" from Cryptographic Restrictions in the Java Cryptography Architecture Reference Guide for complete information on creating and testing such an application.

Step 9: Run your Test Programs

Run your test program(s). Debug your code and continue testing as needed. If the Java Security API cannot seem to find one of your algorithms, review the steps above and ensure they are all completed.

Be sure to include testing of your programs using different installation options (e.g. making the provider an installed extension or placing it on the class path) and execution environments (with or without a security manager running). Installation options are discussed in Step 7.1. In particular, you need to ensure your provider works when a security manager is installed and the provider is not an installed extension -- and thus the provider must have permissions granted to it; therefore, you need to test such an installation and execution environment, after granting required permissions to your provider and to any other providers it uses, as described in Step 7.2.

If you find during testing that your code needs modification, make the changes, recompile (Step 4), place the updated provider code in a JAR file (Step 6), sign the JAR file if necessary (Step 6.2), re-install the provider (Step 7.1), if needed fix or add to the permissions (Step 7.2), and then re-test your programs. Repeat these steps as needed.

Step 10: Apply for U.S. Government Export Approval If Required

All U.S. vendors whose providers may be exported outside the U.S. should apply to the Bureau of Industry and Security in the U.S. Department of Commerce for export approval. Please consult your export counsel for more information.

Note: If your provider calls Cipher.getInstance() and the returned Cipher object needs to perform strong cryptography regardless of what cryptographic strength is allowed by the user's downloaded jurisdiction policy files, you should include a copy of the cryptoPerms permission policy file which you intend to bundle in the JAR file for your provider and which specifies an appropriate permission for the required cryptographic strength. The necessity for this file is just like the requirement that applets and applications "exempt" from cryptographic restrictions must include a cryptoPerms permission policy file in their JAR file. For more information on the creation and inclusion of such a file, see How to Make Applications "Exempt" from Cryptographic Restrictions in the Java Cryptography Architecture Reference Guide.

Here are two URLs that may be useful:

  • U.S. Department of Commerce: http://www.commerce.gov

  • Bureau of Industry and Security: http://www.bis.doc.gov

Step 11: Document your Provider and its Supported Services

The next step is to write documentation for your clients. At the minimum, you need to specify:

  • the name programs should use to refer to your provider. Note: As of this writing, provider name searches are case-sensitive. That is, if your master class specifies your provider name as "CryptoX" but a user requests "CRYPTOx", your provider will not be found. This behavior may change in the future, but for now be sure to warn your clients to use the exact case you specify.

  • the types of algorithms and other services implemented by your provider.

  • instructions for installing the provider, similar to those provided in Step 7.1, except that the information and examples should be specific to your provider.

  • the permissions your provider will require if it is not installed as an installed extension and if a security manager is run, as described in Step 7.2.

In addition, your documentation should specify anything else of interest to clients, such as any default algorithm parameters.

Message Digests and MACs

For each Message Digest and MAC algorithm, indicate whether or not your implementation is cloneable. This is not technically necessary, but it may save clients some time and coding by telling them whether or not intermediate Message Digests or MACs may be possible through cloning. Clients who do not know whether or not a MessageDigest or Mac implementation is cloneable can find out by attempting to clone the object and catching the potential exception, as illustrated by the following example:

    try {
    // try and clone it
    /* compute the MAC for i1 */
    mac.update(i1);
    byte[] i1Mac = mac.clone().doFinal();

    /* compute the MAC for i1 and i2 */
    mac.update(i2);
    byte[] i12Mac = mac.clone().doFinal();

    /* compute the MAC for i1, i2 and i3 */
    mac.update(i3);
    byte[] i123Mac = mac.doFinal();
    } catch (CloneNotSupportedException cnse) {
    // have to use an approach not involving cloning
    }

where:

  • mac is the MAC object they received when they requested one via a call to Mac.getInstance,

  • i1, i2 and i3 are input byte arrays, and

  • they want to calculate separate hashes for:
    • i1
    • i1 and i2
    • i1, i2, and i3

Key Pair Generators

For a key pair generator algorithm, in case the client does not explicitly initialize the key pair generator (via a call to an initialize method), each provider must supply and document a default initialization. For example, the Diffie-Hellman key pair generator supplied by the SunJCE provider uses a default prime modulus size (keysize) of 1024 bits.

Key Factories

A provider should document all the key specifications supported by its (secret-)key factory.

Algorithm Parameter Generators

In case the client does not explicitly initialize the algorithm parameter generator (via a call to an init method in the AlgorithmParameterGenerator engine class), each provider must supply and document a default initialization. For example, the SunJCE provider uses a default prime modulus size (keysize) of 1024 bits for the generation of Diffie-Hellman parameters, the Sun provider a default modulus prime size of 1024 bits for the generation of DSA parameters.

Signature Algorithms

If you implement a signature algorithm, you should document the format in which the signature (generated by one of the sign methods) is encoded. For example, the SHA1withDSA signature algorithm supplied by the "SUN" provider encodes the signature as a standard ASN.1 SEQUENCE of two integers, r and s.

Random Number Generation (SecureRandom) Algorithms

For a random number generation algorithm, provide information regarding how "random" the numbers generated are, and the quality of the seed when the random number generator is self-seeding. Also note what happens when a SecureRandom object (and its encapsulated SecureRandomSpi implementation object) is deserialized: If subsequent calls to the nextBytes method (which invokes the engineNextBytes method of the encapsulated SecureRandomSpi object) of the restored object yield the exact same (random) bytes as the original object would, then let users know that if this behaviour is undesirable, they should seed the restored random object by calling its setSeed method.

Certificate Factories

A provider should document what types of certificates (and their version numbers, if relevant), can be created by the factory.

Keystores

A provider should document any relevant information regarding the keystore implementation, such as its underlying data format.

Step 12: Make your Class Files and Documentation Available to Clients

After writing, configuring, testing, installing and documenting your provider software, make documentation available to your customers.

How a Provider Can Do Self-Integrity Checking

Each provider should do self-integrity checking to ensure that the JAR file containing its code has not been tampered with, for example in an attempt to invoke provider methods directly rather than through JCA. Providers that provide implementations for encryption services (Cipher, KeyAgreement, KeyGenerator, MAC or SecretKey factory) must be digitally signed and should be signed with a certificate issued by "trusted" Certification Authorities. Currently, the following two Certification Authorities are considered "trusted":

  • Sun Microsystems' JCA Code Signing CA, and
  • IBM JCA Code Signing CA.

Please refer to Step 6.2 for detailed information on how to get a code-signing certificate from Sun Microsystems' JCA Code Signing CA and the certificate of that CA.

After getting the signing certificate from above Certification Authority, provider packages should embed within themselves the bytes for its own signing certificate, for example in an array like the bytesOfProviderCert array referred to in the Identifying Each of the Signers and Determining If One is Trusted section below. At runtime, the embedded certificate will be used in determining whether or not the provider code is authentic.

The basic approach a provider can use to check its own integrity is:

  1. Determine the URL of the JAR file containing the provider code, and
  2. Verify the JAR file's digital signatures to ensure that at least one signer of each entry of the JAR file is trusted.

Each of these steps is described in the following sections:

Notes on the Sample Code

Finding the Provider JAR File: Basics

Determining the Provider's JAR File URL

Creating a JarFile Referring to the JAR File

Verifying the Provider JAR File: Basics

Verification Setup

JAR File Signature Check

Verifying Signatures

Ensuring Signers Are Trusted

Getting the List of Certificates

Identifying Each of the Signers and Determining If One is Trusted

Notes on myJCE Sample Code

Notes on the Sample Code

Note: The sample code MyJCE.java is a complete code example that implements these steps. You can download this code for your reference. The Notes on the Sample Code section traces how these concepts are implemented in the sample code.

IMPORTANT NOTE: In the unbundled version of JCE 1.2.x, (used with JDKs 1.2.x and 1.3.x), providers needed to include code to authenticate the JCA framework to assure themselves of the integrity and authenticity of the JCA that they plugged into. In JDK 6, this is no longer necessary.

One implication is that a provider written just for JCE 1.2.2 will not work in JDK 6 because the provider's JCE framework authentication check will not work; the JCE framework code is no longer where the provider expects it to be. If you want your provider to work only with the JDK 6, it should not have code to authenticate the JCE framework. On the other hand, if you want your provider to work both with JCE 1.2.2 and with the JDK 6, then add a conditional statement. This way the provider code to authenticate the JCE framework is executed only when the provider is run with JCE 1.2.2. The following is sample code:

    Class cipherCls = Class.forName("javax.crypto.Cipher");

    CodeSource cs = cipherCls.getProtectionDomain().getCodeSource();
    if (cs != null) {
    // Authenticate JCE framework

     . . .
    }

Finding the Provider JAR File: Basics

Determining the Provider's JAR File URL

The URL for the provider's JAR file can be obtained by determining the provider's CodeSource and then calling the getLocation method on the CodeSource.

    URL providerURL = (URL) AccessController.doPrivileged(
    new PrivilegedAction) {
        public Object run() {
        CodeSource cs =
            MyJCE.class.getProtectionDomain().getCodeSource();
        return cs.getLocation();
        }
    });

Creating a JarFile Referring to the JAR File

Once you have the URL for the provider's JAR file, you can create a java.util.jar.JarFile referring to the JAR file. This instance is needed in the step for verifying the Provider JAR file.

To create the JAR file, first open a connection to the specified URL by calling its openConnection method. Since the URL is a JAR URL, the type is java.net.JarURLConnection. Here's the basic code:

    // Prep the url with the appropriate protocol.
    jarURL =
    url.getProtocol().equalsIgnoreCase("jar") ? url :
        new URL("jar:" + url.toString() + "!/");

    // Retrieve the jar file using JarURLConnection
    JarFile jf = (JarFile) AccessController.doPrivileged(
    new PrivilegedExceptionAction() {
        public Object run() throws Exception {
        JarURLConnection conn =
            (JarURLConnection) jarURL.openConnection();
    ...

Now that you have a JarURLConnection, you can call its getJarFile method to get the JAR file:

    // Always get a fresh copy, so we don't have to
    // worry about the stale file handle when the
    // cached jar is closed by some other application.
    conn.setUseCaches(false);
    jf = conn.getJarFile();

Verifying the Provider JAR File: Basics

Once you have determined the URL for your provider JAR file and you have created a JarFile referring to the JAR file, as shown in the steps above, you can then verify the file.

The basic approach is:

  1. Ensure that at least one of each entry's signer's certificates is equal to the provider's own code signing certificate.
  2. Go through all the entries in the JAR file and ensure the signature on each one verifies correctly.
  3. Ensure that at least one of each entry's signer's certificates can be traced back to a trusted Certification Authority.

Sample code for each of these steps is presented and described in the following sections:

Verification Setup

JAR File Signature Check

Verifying Signatures

Ensuring Signers Are Trusted

Getting the List of Certificates

Identifying Each of the Signers and Determining If One is Trusted

Verification Setup

Our approach is to define a class JarVerifier to handle the retrieval of a JAR file from a given URL and verify whether the JAR file is signed with the specified certificate.

The constructor of JarVerifier takes the provider URL as a parameter which will be used to retrieve the JAR file later.

The actual jar verification is implemented in the verify method which takes the provider code signing certificate as a parameter.

    public void verify(X509Certificate targetCert) throws IOException {
    // variable 'jarFile' is a JarFile object created
    // from the provider's Jar URL.
    ...
    Vector entriesVec = new Vector();

Basically the verify method will go through the JAR file entries twice: the first time checking the signature on each entry and the second time verifying the signer is trusted.

Note: In our code snippets the jarFile variable is the JarFile object of the provider's jar file.

JAR File Signature Check

An authentic provider JAR file is signed. So the JAR file has been tampered with if it isn't signed:

    // Ensure the jar file is signed.
    Manifest man = jarFile.getManifest();
    if (man == null) {
    throw new SecurityException("The provider is not signed");
    }

Verifying Signatures

The next step is to go through all the entries in the JAR file and ensure the signature on each one verifies correctly. One possible way to verify the signature on a JAR file entry is to simply read the file. If a JAR file is signed, the read method itself automatically performs the signature verification. Here is sample code:

    // Ensure all the entries' signatures verify correctly
    byte[] buffer = new byte[8192];
    Enumeration entries = jarFile.entries();

    while (entries.hasMoreElements()) {
    JarEntry je = (JarEntry) entries.nextElement();

    // Skip directories.
    if (je.isDirectory())
        continue;

    entriesVec.addElement(je);
    InputStream is = jarFile.getInputStream(je);

    // Read in each jar entry. A security exception will
    // be thrown if a signature/digest check fails.
    int n;
    while ((n = is.read(buffer, 0, buffer.length)) != -1) {
        // Don't care
    }
    is.close();
    }

Ensuring Signers Are Trusted

The code in the previous section verified the signatures of all the provider JAR file entries. The fact that they all verify correctly is a requirement, but it is not sufficient to verify the authenticity of the JAR file. A final requirement is that the signatures were generated by the same entity as the one that developed this provider. To test that the signatures are trusted, we can again go through each entry in the JAR file (this time using the entriesVec built in the previous step), and for each entry that must be signed (that is, each entry that is not a directory and that is not in the META-INF directory):

  1. Get the list of signer certificates for the entry.
  2. Identify each of the certificate chains and determine whether any of the certificate chains are trusted. At least one of the certificate chains must be trusted.

The loop setup is the following:

    Enumeration e = entriesVec.elements();
    while (e.hasMoreElements()) {
    JarEntry je = (JarEntry) e.nextElement();
    ...
    }

Getting the List of Certificates

The certificates for the signers of a JAR file entry JarEntry can be obtained simply by calling the JarEntry getCertificates method:

    Certificate[] certs = je.getCertificates();

Adding this line of code to the previous loop setup code, and adding code to ignore directories and files in the META-INF directory gives us:

    while (e.hasMoreElements()) {
    JarEntry je = (JarEntry) e.nextElement();

    // Every file must be signed except files in META-INF.
    Certificate[] certs = je.getCertificates();
    if ((certs == null) || (certs.length == 0)) {
        if (!je.getName().startsWith("META-INF"))
        throw new SecurityException(
            "The provider has unsigned class files.");
        } else {
        // Check whether the file is signed by the expected
        // signer. The jar may be signed by multiple signers.
        // See if one of the signers is 'targetCert'.
        ...
        }
    ...

Identifying Each of the Signers and Determining If One is Trusted

The certificate array returned by the JarEntry getCertificates method contains one or more certificate chains. There is one chain per signer of the entry. Each chain contains one or more certificates. Each certificate in a chain authenticates the public key in the previous certificate.

The first certificate in a chain is the signer's certificate which contains the public key corresponding to the private key actually used to sign the entry. Each subsequent certificate is a certificate for the issuer of the previous certificate. Since the self-integrity check is based on whether the JAR file is signed with the provider's signing cert, the trust decision will be made upon only the first certificate, the signer's certificate.

We need to go through the array of certificate chains and check each chain and the associated signers until we find a trusted entity. For each JAR file entry, at least one of the signers must be trusted. A signer is considered "trusted" if and only if its certificate is equals to the embedded provider signing certificate.

The following sample code loops through all the certificate chains, compares the first certificate in a chain to the embedded provider signing certificate, and only returns true if a match is found.

    int startIndex = 0;
    X509Certificate[] certChain;
    boolean signedAsExpected = false;

    while ((certChain = getAChain(certs, startIndex)) != null) {
    if (certChain[0].equals(targetCert)) {
        // Stop since one trusted signer is found.
        signedAsExpected = true;
        break;
    }

    // Proceed to the next chain.
    startIndex += certChain.length;
    }

    if (!signedAsExpected) {
    throw new SecurityException(
        "The provider is not signed by a trusted signer");
    }

The getAChain method is defined as follows:

    /**
     * Extracts ONE certificate chain from the specified certificate array
     * which may contain multiple certificate chains, starting from index
     * 'startIndex'.
     */
    private static X509Certificate[] getAChain(
        Certificate[] certs, int startIndex) {

    if (startIndex > certs.length - 1)
        return null;

    int i;
    // Keep going until the next certificate is not the
    // issuer of this certificate.
    for (i = startIndex; i < certs.length - 1; i++) {
        if (!((X509Certificate)certs[i + 1]).getSubjectDN().
            equals(((X509Certificate)certs[i]).getIssuerDN())) {
        break;
        }
    }

    // Construct and return the found certificate chain.
    int certChainSize = (i-startIndex) + 1;
    X509Certificate[] ret = new X509Certificate[certChainSize];
    for (int j = 0; j < certChainSize; j++ ) {
        ret[j] = (X509Certificate) certs[startIndex + j];
    }
    return ret;
    }

Notes on the myJCE Code Sample

The sample code, MyJCE.java, is a sample provider which has a method selfIntegrityChecking which performs self-integrity checking. It first determines the URL of its own provider JAR file and then verifies that the provider JAR file is signed with the embedded code-signing certificate.

Note: The method selfIntegrityChecking should be called by all the constructors of its cryptographic engine classes to ensure that its integrity is not compromised.

Provider MyJCE performs self-integrity checking in the following steps:

  1. Determine the URL to access the provider JAR file using its own class, MyJCE.class.

  2. Instantiate a JarVerifier object with the provider URL in Step 1.

  3. Create a X509Certificate object from the embedded byte array bytesOfProviderCert.

  4. Call the JarVerifier.verify method to verify all entries in the provider JAR file are signed and are signed with the same certificate instantiated in Step 3.

Note: The class JarVerifier will retrieve the JAR file from the given URL, make sure the JAR file is signed, all entries have valid signatures, and that entries are signed with the specified X509Certificate.

A security exception is thrown by JarVerifier.verify in several cases:

  • The certificate passed to verify is null (invalid).
  • When unable to retrieve JAR file from the given URL.
  • The provider is not signed. (The jar has no manifest.)
  • The provider has unsigned class files.
  • The provider is not signed with the specified certificate.

The MyJCE.java sample code is comprised of the code snippets shown above. In addition, it includes error handling, sample code signing certificate bytes, and code for instantiating a X509Certificate object from the embedded sample code signing certificate bytes.

Regarding the use of AccessController.doPrivileged, please see API For Privileged Blocks for information on the use of doPrivileged.

Further Implementation Details and Requirements

Alias Names

For many cryptographic algorithms and types, there is a single official "standard name" defined in Appendix A of the Java Cryptography Architecture Reference Guide.

For example, "MD5" is the standard name for the RSA-MD5 Message Digest algorithm defined by RSA DSI in RFC 1321. DiffieHellman is the standard for the Diffie-Hellman key agreement algorithm defined in PKCS3.

In the JDK, there is an aliasing scheme that enables clients to use aliases when referring to algorithms or types, rather than their standard names. For example, the "SUN" provider's master class (Sun.java) defines the alias "SHA1/DSA" for the algorithm whose standard name is "SHA1withDSA". Thus, the following statements are equivalent:

    Signature sig = Signature.getInstance("SHA1withDSA", "SUN");

    Signature sig = Signature.getInstance("SHA1/DSA", "SUN");

Aliases can be defined in your "master class" (see Step 3). To define an alias, create a property named

    Alg.Alias.engineClassName.aliasName

where engineClassName is the name of an engine class (e.g., Signature), and aliasName is your alias name. The value of the property must be the standard algorithm (or type) name for the algorithm (or type) being aliased.

As an example, the "SUN" provider defines the alias "SHA1/DSA" for the signature algorithm whose standard name is "SHA1withDSA" by setting a property named Alg.Alias.Signature.SHA1/DSA to have the value SHA1withDSA via the following:

    put("Alg.Alias.Signature.SHA1/DSA", "SHA1withDSA");

Note that aliases defined by one provider are available only to that provider and not to any other providers. Thus, aliases defined by the SunJCE provider are available only to the SunJCE provider.

Service Interdependencies

Some algorithms require the use of other types of algorithms. For example, a PBE algorithm usually needs to use a message digest algorithm in order to transform a password into a key.

If you are implementing one type of algorithm that requires another, you can do one of the following:

  1. Provide your own implementations for both.
  2. Let your implementation of one algorithm use an instance of the other type of algorithm, as supplied by the default Sun provider that is included with every Java SE Platform installation. For example, if you are implementing a PBE algorithm that requires a message digest algorithm, you can obtain an instance of a class implementing the MD5 message digest algorithm by calling

        MessageDigest.getInstance("MD5", "SUN")
  3. Let your implementation of one algorithm use an instance of the other type of algorithm, as supplied by another specific provider. This is only appropriate if you are sure that all clients who will use your provider will also have the other provider installed.
  4. Let your implementation of one algorithm use an instance of the other type of algorithm, as supplied by another (unspecified) provider. That is, you can request an algorithm by name, but without specifying any particular provider, as in
        MessageDigest.getInstance("MD5")
    This is only appropriate if you are sure that there will be at least one implementation of the requested algorithm (in this case, MD5) installed on each Java platform where your provider will be used.

Here are some common types of algorithm interdependencies:

Signature and Message Digest Algorithms

A signature algorithm often requires use of a message digest algorithm. For example, the SHA1withDSA signature algorithm requires the SHA-1 message digest algorithm.

Signature and (Pseudo-)Random Number Generation Algorithms

A signature algorithm often requires use of a (pseudo-)random number generation algorithm. For example, such an algorithm is required in order to generate a DSA signature.

Key Pair Generation and Message Digest Algorithms

A key pair generation algorithm often requires use of a message digest algorithm. For example, DSA keys are generated using the SHA-1 message digest algorithm.

Algorithm Parameter Generation and Message Digest Algorithms

An algorithm parameter generator often requires use of a message digest algorithm. For example, DSA parameters are generated using the SHA-1 message digest algorithm.

KeyStores and Message Digest Algorithms

A keystore implementation will often utilize a message digest algorithm to compute keyed hashes (where the key is a user-provided password) to check the integrity of a keystore and make sure that the keystore has not been tampered with.

Key Pair Generation Algorithms and Algorithm Parameter Generators

A key pair generation algorithm sometimes needs to generate a new set of algorithm parameters. It can either generate the parameters directly, or use an algorithm parameter generator.

Key Pair Generation, Algorithm Parameter Generation, and (Pseudo-)Random Number Generation Algorithms

A key pair generation algorithm may require a source of randomness in order to generate a new key pair and possibly a new set of parameters associated with the keys. That source of randomness is represented by a SecureRandom object. The implementation of the key pair generation algorithm may generate the key parameters itself, or may use an algorithm parameter generator to generate them, in which case it may or may not initialize the algorithm parameter generator with a source of randomness.

Algorithm Parameter Generators and Algorithm Parameters

An algorithm parameter generator's engineGenerateParameters method must return an AlgorithmParameters instance.

Signature and Key Pair Generation Algorithms or Key Factories

If you are implementing a signature algorithm, your implementation's engineInitSign and engineInitVerify methods will require passed-in keys that are valid for the underlying algorithm (e.g., DSA keys for the DSS algorithm). You can do one of the following:

  1. Also create your own classes implementing appropriate interfaces (e.g. classes implementing the DSAPrivateKey and DSAPublicKey interfaces from the package java.security.interfaces), and create your own key pair generator and/or key factory returning keys of those types. Require the keys passed to engineInitSign and engineInitVerify to be the types of keys you have implemented, that is, keys generated from your key pair generator or key factory. Or you can,

  2. Accept keys from other key pair generators or other key factories, as long as they are instances of appropriate interfaces that enable your signature implementation to obtain the information it needs (such as the private and public keys and the key parameters). For example, the engineInitSign method for a DSS Signature class could accept any private keys that are instances of java.security.interfaces.DSAPrivateKey.

KeyStores and Key and Certificate Factories

A keystore implementation will often utilize a key factory to parse the keys stored in the keystore, and a certificate factory to parse the certificates stored in the keystore.

Default Initializations

In case the client does not explicitly initialize a key pair generator or an algorithm parameter generator, each provider of such a service must supply (and document) a default initialization. For example, the Sun provider uses a default modulus size (strength) of 1024 bits for the generation of DSA parameters, and the "SunJCE" provider uses a default modulus size (keysize) of 1024 bits for the generation of Diffie-Hellman parameters.

Default Key Pair Generator Parameter Requirements

If you implement a key pair generator, your implementation should supply default parameters that are used when clients don't specify parameters. The documentation you supply (Step 11) should state what the default parameters are.

For example, the DSA key pair generator in the Sun provider supplies a set of pre-computed p, q, and g default values for the generation of 512, 768, and 1024-bit key pairs. The following p, q, and g values are used as the default values for the generation of 1024-bit DSA key pairs:

p = fd7f5381 1d751229 52df4a9c 2eece4e7 f611b752 3cef4400 c31e3f80
    b6512669 455d4022 51fb593d 8d58fabf c5f5ba30 f6cb9b55 6cd7813b
    801d346f f26660b7 6b9950a5 a49f9fe8 047b1022 c24fbba9 d7feb7c6
    1bf83b57 e7c6a8a6 150f04fb 83f6d3c5 1ec30235 54135a16 9132f675
    f3ae2b61 d72aeff2 2203199d d14801c7

q = 9760508f 15230bcc b292b982 a2eb840b f0581cf5

g = f7e1a085 d69b3dde cbbcab5c 36b857b9 7994afbb fa3aea82 f9574c0b
    3d078267 5159578e bad4594f e6710710 8180b449 167123e8 4c281613
    b7cf0932 8cc8a6e1 3c167a8b 547c8d28 e0a3ae1e 2bb3a675 916ea37f
    0bfa2135 62f1fb62 7a01243b cca4f1be a8519089 a883dfe1 5ae59f06
    928b665e 807b5525 64014c3b fecf492a

(The p and q values given here were generated by the prime generation standard, using the 160-bit

SEED:  8d515589 4229d5e6 89ee01e6 018a237e 2cae64cd

With this seed, the algorithm found p and q when the counter was at 92.)

The Provider.Service Class

Since its introduction, security providers have published their service information via appropriately formatted key-value String pairs they put in their Hashtable entries. While this mechanism is simple and convenient, it limits the amount customization possible. As a result, JDK 5.0 introduced a second option, the Provider.Service class. It offers an alternative way for providers to advertise their services and supports additional features as described below. Note that this addition is fully compatible with the older method of using String valued Hashtable entries. A provider on JDK 5.0 can choose either method as it prefers, or even use both at the same time.

A Provider.Service object encapsulates all information about a service. This is the provider that offers the service, its type (e.g. MessageDigest or Signature), the algorithm name, and the name of the class that implements the service. Optionally, it also includes a list of alternate algorithm names for this service (aliases) and attributes, which are a map of (name, value) String pairs. In addition, it defines the methods newInstance() and supportsParameter(). They have default implementations, but can be overridden by providers if needed, as may be the case with providers that interface with hardware security tokens.

The newInstance() method is used by the security framework when it needs to construct new implementation instances. The default implementation uses reflection to invoke the standard constructor for the respective type of service. For all standard services except CertStore, this is the no-args constructor. The constructorParameter to newInstance() must be null in theses cases. For services of type CertStore, the constructor that takes a CertStoreParameters object is invoked, and constructorParameter must be a non-null instance of CertStoreParameters. A security provider can override the newInstance() method to implement instantiation as appropriate for that implementation. It could use direct invocation or call a constructor that passes additional information specific to the Provider instance or token. For example, if multiple Smartcard readers are present on the system, it might pass information about which reader the newly created service is to be associated with. However, despite customization all implementations must follow the conventions about constructorParameter described above.

The supportsParameter() tests whether the Service can use the specified parameter. It returns false if this service cannot use the parameter. It returns true if this service can use the parameter, if a fast test is infeasible, or if the status is unknown. It is used by the security framework with some types of services to quickly exclude non-matching implementations from consideration. It is currently only defined for the following standard services: Signature, Cipher, Mac, and KeyAgreement. The parameter must be an instance of Key in these cases. For example, for Signature services, the framework tests whether the service can use the supplied Key before instantiating the service. The default implementation examines the attributes SupportedKeyFormats and SupportedKeyClasses as described below. Again, a provider may override this methods to implement additional tests.

The SupportedKeyFormats attribute is a list of the supported formats for encoded keys (as returned by key.getFormat()) separated by the "|" (pipe) character. For example, X.509|PKCS#8. The SupportedKeyClasses attribute is a list of the names of classes of interfaces separated by the "|" character. A key object is considered to be acceptable if it is assignable to at least one of those classes or interfaces named. In other words, if the class of the key object is a subclass of one of the listed classes (or the class itself) or if it implements the listed interface. An example value is "java.security.interfaces.RSAPrivateKey|java.security.interfaces.RSAPublicKey" .

Four methods have been added to the Provider class for adding and looking up Services. As mentioned earlier, the implementation of those methods and also of the existing Properties methods have been specifically designed to ensure compatibility with existing Provider subclasses. This is achieved as follows:

If legacy Properties methods are used to add entries, the Provider class makes sure that the property strings are parsed into equivalent Service objects prior to lookup via getService(). Similarly, if the putService() method is used, equivalent property strings are placed into the provider's hashtable at the same time. If a provider implementation overrides any of the methods in the Provider class, it has to ensure that its implementation does not interfere with this conversion. To avoid problems, we recommend that implementations do not override any of the methods in the Provider class.

Signature Formats

If you implement a signature algorithm, the documentation you supply (Step 11) should specify the format in which the signature (generated by one of the sign methods) is encoded.

For example, the SHA1withDSA signature algorithm supplied by the Sun provider encodes the signature as a standard ASN.1 sequence of two ASN.1 INTEGER values: r and s, in that order:

SEQUENCE ::= {
    r INTEGER,
    s INTEGER }

DSA Interfaces and their Required Implementations

The Java Security API contains the following interfaces (in the java.security.interfaces package) for the convenience of programmers implementing DSA services:

  • DSAKey
  • DSAKeyPairGenerator
  • DSAParams
  • DSAPrivateKey
  • DSAPublicKey

The following sections discuss requirements for implementations of these interfaces.

DSAKeyPairGenerator Implementation

This interface is obsolete. It used to be needed to enable clients to provide DSA-specific parameters to be used rather than the default parameters your implementation supplies. However, in Java it is no longer necessary; a new KeyPairGenerator initialize method that takes an AlgorithmParameterSpec parameter enables clients to indicate algorithm-specific parameters.

DSAParams Implementation

If you are implementing a DSA key pair generator, you need a class implementing DSAParams for holding and returning the p, q, and g parameters.

A DSAParams implementation is also required if you implement the DSAPrivateKey and DSAPublicKey interfaces. DSAPublicKey and DSAPrivateKey both extend the DSAKey interface, which contains a getParams method that must return a DSAParams object. See DSAPrivateKey and DSAPublicKey Implementations for more information.

Note: there is a DSAParams implementation built into the JDK: the java.security.spec.DSAParameterSpec class.

DSAPrivateKey and DSAPublicKey Implementations

If you implement a DSA key pair generator or key factory, you need to create classes implementing the DSAPrivateKey and DSAPublicKey interfaces.

If you implement a DSA key pair generator, your generateKeyPair method (in your KeyPairGeneratorSpi subclass) will return instances of your implementations of those interfaces.

If you implement a DSA key factory, your engineGeneratePrivate method (in your KeyFactorySpi subclass) will return an instance of your DSAPrivateKey implementation, and your engineGeneratePublic method will return an instance of your DSAPublicKey implementation.

Also, your engineGetKeySpec and engineTranslateKey methods will expect the passed-in key to be an instance of a DSAPrivateKey or DSAPublicKey implementation. The getParams method provided by the interface implementations is useful for obtaining and extracting the parameters from the keys and then using the parameters, for example as parameters to the DSAParameterSpec constructor called to create a parameter specification from parameter values that could be used to initialize a KeyPairGenerator object for DSA.

If you implement a DSA signature algorithm, your engineInitSign method (in your SignatureSpi subclass) will expect to be passed a DSAPrivateKey and your engineInitVerify method will expect to be passed a DSAPublicKey.

Please note: The DSAPublicKey and DSAPrivateKey interfaces define a very generic, provider-independent interface to DSA public and private keys, respectively. The engineGetKeySpec and engineTranslateKey methods (in your KeyFactorySpi subclass) could additionally check if the passed-in key is actually an instance of their provider's own implementation of DSAPrivateKey or DSAPublicKey, e.g., to take advantage of provider-specific implementation details. The same is true for the DSA signature algorithm engineInitSign and engineInitVerify methods (in your SignatureSpi subclass).

To see what methods need to be implemented by classes that implement the DSAPublicKey and DSAPrivateKey interfaces, first note the following interface signatures:

In the java.security.interfaces package:

   public interface DSAPrivateKey extends DSAKey,
        java.security.PrivateKey

   public interface DSAPublicKey extends DSAKey,
        java.security.PublicKey

   public interface DSAKey

In the java.security package:

   public interface PrivateKey extends Key

   public interface PublicKey extends Key

   public interface Key extends java.io.Serializable

In order to implement the DSAPrivateKey and DSAPublicKey interfaces, you must implement the methods they define as well as those defined by interfaces they extend, directly or indirectly.

Thus, for private keys, you need to supply a class that implements

  • the getX method from the DSAPrivateKey interface.

  • the getParams method from the java.security.interfaces.DSAKey interface, since DSAPrivateKey extends DSAKey. Note: The getParams method returns a DSAParams object, so you must also have a DSAParams implementation.

  • the getAlgorithm, getEncoded, and getFormat methods from the java.security.Key interface, since DSAPrivateKey extends java.security.PrivateKey, and PrivateKey extends Key.

      Similarly, for public DSA keys, you need to supply a class that implements:

      • the getY method from the DSAPublicKey interface.

      • the getParams method from the java.security.interfaces.DSAKey interface, since DSAPublicKey extends DSAKey. Note: The getParams method returns a DSAParams object, so you must also have a DSAParams implementation.

      • the getAlgorithm, getEncoded, and getFormat methods from the java.security.Key interface, since DSAPublicKey extends java.security.PublicKey, and PublicKey extends Key.

    RSA Interfaces and their Required Implementations

    The Java Security API contains the following interfaces (in the java.security.interfaces package) for the convenience of programmers implementing RSA services:

    • RSAPrivateKey
    • RSAPrivateCrtKey
    • RSAPublicKey

    The following sections discuss requirements for implementations of these interfaces.

    RSAPrivateKey , RSAPrivateCrtKey , and RSAPublicKey Implementations

    If you implement an RSA key pair generator or key factory, you need to create classes implementing the RSAPrivateKey (and/or RSAPrivateCrtKey) and RSAPublicKey interfaces. (RSAPrivateCrtKey is the interface to an RSA private key, using the Chinese Remainder Theorem (CRT) representation.)

    If you implement an RSA key pair generator, your generateKeyPair method (in your KeyPairGeneratorSpi subclass) will return instances of your implementations of those interfaces.

    If you implement an RSA key factory, your engineGeneratePrivate method (in your KeyFactorySpi subclass) will return an instance of your RSAPrivateKey (or RSAPrivateCrtKey) implementation, and your engineGeneratePublic method will return an instance of your RSAPublicKey implementation.

    Also, your engineGetKeySpec and engineTranslateKey methods will expect the passed-in key to be an instance of an RSAPrivateKey, RSAPrivateCrtKey, or RSAPublicKey implementation.

    If you implement an RSA signature algorithm, your engineInitSign method (in your SignatureSpi subclass) will expect to be passed either an RSAPrivateKey or an RSAPrivateCrtKey, and your engineInitVerify method will expect to be passed an RSAPublicKey.

    Please note: The RSAPublicKey, RSAPrivateKey, and RSAPrivateCrtKey interfaces define a very generic, provider-independent interface to RSA public and private keys. The engineGetKeySpec and engineTranslateKey methods (in your KeyFactorySpi subclass) could additionally check if the passed-in key is actually an instance of their provider's own implementation of RSAPrivateKey, RSAPrivateCrtKey, or RSAPublicKey, e.g., to take advantage of provider-specific implementation details. The same is true for the RSA signature algorithm engineInitSign and engineInitVerify methods (in your SignatureSpi subclass).

    To see what methods need to be implemented by classes that implement the RSAPublicKey, RSAPrivateKey, and RSAPrivateCrtKey interfaces, first note the following interface signatures:

    In the java.security.interfaces package:

        public interface RSAPrivateKey extends java.security.PrivateKey

    public interface RSAPrivateCrtKey extends RSAPrivateKey

    public interface RSAPublicKey extends java.security.PublicKey

    In the java.security package:

        public interface PrivateKey extends Key

    public interface PublicKey extends Key

    public interface Key extends java.io.Serializable

    In order to implement the RSAPrivateKey, RSAPrivateCrtKey, and RSAPublicKey interfaces, you must implement the methods they define as well as those defined by interfaces they extend, directly or indirectly.

    Thus, for RSA private keys, you need to supply a class that implements:

    • the getModulus and getPrivateExponent methods from the RSAPrivateKey interface.

    • the getAlgorithm, getEncoded, and getFormat methods from the java.security.Key interface, since RSAPrivateKey extends java.security.PrivateKey, and PrivateKey extends Key.

    Similarly, for RSA private keys using the Chinese Remainder Theorem (CRT) representation, you need to supply a class that implements:

    • all the methods listed above for RSA private keys, since RSAPrivateCrtKey extends java.security.interfaces.RSAPrivateKey.

    • the getPublicExponent, getPrimeP, getPrimeQ, getPrimeExponentP, getPrimeExponentQ, and getCrtCoefficient methods from the RSAPrivateKey interface.

    For public RSA keys, you need to supply a class that implements:

    • the getModulus and getPublicExponent methods from the RSAPublicKey interface.
    • the getAlgorithm, getEncoded, and getFormat methods from the java.security.Key interface, since RSAPublicKey extends java.security.PublicKey, and PublicKey extends Key.

    JCA contains a number of AlgorithmParameterSpec implementations for the most frequently used cipher and key agreement algorithm parameters. If you are operating on algorithm parameters that should be for a different type of algorithm not provided by JCA, you will need to supply your own AlgorithmParameterSpec implementation appropriate for that type of algorithm.

    Diffie-Hellman Interfaces and their Required Implementations

    JCA contains the following interfaces (in the javax.crypto.interfaces package) for the convenience of programmers implementing Diffie-Hellman services:

    • DHKey
    • DHPrivateKey
    • DHPublicKey

    The following sections discuss requirements for implementations of these interfaces.

    DHPrivateKey and DHPublicKey Implementations

    If you implement a Diffie-Hellman key pair generator or key factory, you need to create classes implementing the DHPrivateKey and DHPublicKey interfaces.

    If you implement a Diffie-Hellman key pair generator, your generateKeyPair method (in your KeyPairGeneratorSpi subclass) will return instances of your implementations of those interfaces.

    If you implement a Diffie-Hellman key factory, your engineGeneratePrivate method (in your KeyFactorySpi subclass) will return an instance of your DHPrivateKey implementation, and your engineGeneratePublic method will return an instance of your DHPublicKey implementation.

    Also, your engineGetKeySpec and engineTranslateKey methods will expect the passed-in key to be an instance of a DHPrivateKey or DHPublicKey implementation. The getParams method provided by the interface implementations is useful for obtaining and extracting the parameters from the keys. You can then use the parameters, for example, as parameters to the DHParameterSpec constructor called to create a parameter specification from parameter values used to initialize a KeyPairGenerator object for Diffie-Hellman.

    If you implement the Diffie-Hellman key agreement algorithm, your engineInit method (in your KeyAgreementSpi subclass) will expect to be passed a DHPrivateKey and your engineDoPhase method will expect to be passed a DHPublicKey.

    Note: The DHPublicKey and DHPrivateKey interfaces define a very generic, provider-independent interface to Diffie-Hellman public and private keys, respectively. The engineGetKeySpec and engineTranslateKey methods (in your KeyFactorySpi subclass) could additionally check if the passed-in key is actually an instance of their provider's own implementation of DHPrivateKey or DHPublicKey, e.g., to take advantage of provider-specific implementation details. The same is true for the Diffie-Hellman algorithm engineInit and engineDoPhase methods (in your KeyAgreementSpi subclass).

    To see what methods need to be implemented by classes that implement the DHPublicKey and DHPrivateKey interfaces, first note the following interface signatures:

    In the javax.crypto.interfaces package:

        public interface DHPrivateKey extends DHKey, java.security.PrivateKey

    public interface DHPublicKey extends DHKey, java.security.PublicKey

    public interface DHKey

    In the java.security package:

        public interface PrivateKey extends Key

    public interface PublicKey extends Key

    public interface Key extends java.io.Serializable

    To implement the DHPrivateKey and DHPublicKey interfaces, you must implement the methods they define as well as those defined by interfaces they extend, directly or indirectly.

    Thus, for private keys, you need to supply a class that implements:

    • the getX method from the DHPrivateKey interface.
    • the getParams method from the javax.crypto.interfaces.DHKey interface, since DHPrivateKey extends DHKey.
    • the getAlgorithm, getEncoded, and getFormat methods from the java.security.Key interface, since DHPrivateKey extends java.security.PrivateKey, and PrivateKey extends Key.

    Similarly, for public Diffie-Hellman keys, you need to supply a class that implements:

    • the getY method from the DHPublicKey interface.
    • the getParams method from the javax.crypto.interfaces.DHKey interface, since DHPublicKey extends DHKey.
    • the getAlgorithm, getEncoded, and getFormat methods from the java.security.Key interface, since DHPublicKey extends java.security.PublicKey, and PublicKey extends Key.

    Interfaces for Other Algorithm Types

    As noted above, the Java Security API contains interfaces for the convenience of programmers implementing services like DSA, RSA and ECC. If there are services without API support, you need to define your own APIs.

    If you are implementing a key pair generator for a different algorithm, you should create an interface with one or more initialize methods that clients can call when they want to provide algorithm-specific parameters to be used rather than the default parameters your implementation supplies. Your subclass of KeyPairGeneratorSpi should implement this interface.

    For algorithms without direct API support, it is recommended that you create similar interfaces and provide implementation classes. Your public key interface should extend the PublicKey interface. Similarly, your private key interface should extend the PrivateKey interface.

    Algorithm Parameter Specification Interfaces and Classes

    An algorithm parameter specification is a transparent representation of the sets of parameters used with an algorithm.

    A transparent representation of parameters means that you can access each value individually, through one of the get methods defined in the corresponding specification class (e.g., DSAParameterSpec defines getP, getQ, and getG methods, to access the p, q, and g parameters, respectively).

    This is contrasted with an opaque representation, as supplied by the AlgorithmParameters engine class, in which you have no direct access to the key material values; you can only get the name of the algorithm associated with the parameter set (via getAlgorithm) and some kind of encoding for the parameter set (via getEncoded).

    If you supply an AlgorithmParametersSpi, AlgorithmParameterGeneratorSpi, or KeyPairGeneratorSpi implementation, you must utilize the AlgorithmParameterSpec interface, since each of those classes contain methods that take an AlgorithmParameterSpec parameter. Such methods need to determine which actual implementation of that interface has been passed in, and act accordingly.

    JCA contains a number of AlgorithmParameterSpec implementations for the most frequently used signature, cipher and key agreement algorithm parameters. If you are operating on algorithm parameters that should be for a different type of algorithm not provided by JCA, you will need to supply your own AlgorithmParameterSpec implementation appropriate for that type of algorithm.

    Java defines the following algorithm parameter specification interfaces and classes in the java.security.spec and javax.crypto.spec packages:

    The AlgorithmParameterSpec Interface

    AlgorithmParameterSpec is an interface to a transparent specification of cryptographic parameters.

    This interface contains no methods or constants. Its only purpose is to group (and provide type safety for) all parameter specifications. All parameter specifications must implement this interface.

    The DSAParameterSpec Class

    This class (which implements the AlgorithmParameterSpec and DSAParams interfaces) specifies the set of parameters used with the DSA algorithm. It has the following methods:

        public BigInteger getP()

    public BigInteger getQ()

    public BigInteger getG()

    These methods return the DSA algorithm parameters: the prime p, the sub-prime q, and the base g.

    Many types of DSA services will find this class useful - for example, it is utilized by the DSA signature, key pair generator, algorithm parameter generator, and algorithm parameters classes implemented by the Sun provider. As a specific example, an algorithm parameters implementation must include an implementation for the getParameterSpec method, which returns an AlgorithmParameterSpec. The DSA algorithm parameters implementation supplied by Sun returns an instance of the DSAParameterSpec class.

    The IvParameterSpec Class

    This class (which implements the AlgorithmParameterSpec interface) specifies the initialization vector (IV) used with a cipher in feedback mode.

    Method | Description
cff" colspan="2"> Method in IvParameterSpec
byte[] getIV() | Returns the initialization vector (IV).

    The OAEPParameterSpec Class

    This class (which implements the AlgorithmParameterSpec interface) specifies the initialization vector (IV) used with a cipher in feedback mode.

    Method | Description
cff" colspan="2"> Method in IvParameterSpec
byte[] getIV() | Returns the initialization vector (IV).

    The PBEParameterSpec Class

    This class (which implements the AlgorithmParameterSpec interface) specifies the set of parameters used with a password-based encryption (PBE) algorithm.

    Method | Description
cff" colspan="2"> Methods in PBEParameterSpec
int getIterationCount() | Returns the iteration count.
byte[] getSalt() | Returns the salt.

    The RC2ParameterSpec Class

    This class (which implements the AlgorithmParameterSpec interface) specifies the set of parameters used with the RC2 algorithm.

    Method | Description
cff" colspan="2"> Methods in RC2ParameterSpec
boolean equals(Object obj) | Tests for equality between the specified object and this object.
int getEffectiveKeyBits() | Returns the effective key size in bits.
byte[] getIV() | Returns the IV or null if this parameter set does not contain an IV.
int hashCode() | Calculates a hash code value for the object.

    The RC5ParameterSpec Class

    This class (which implements the AlgorithmParameterSpec interface) specifies the set of parameters used with the RC5 algorithm.

    Method | Description
cff" colspan="2"> Methods in RC5ParameterSpec
boolean equals(Object obj) | Tests for equality between the specified object and this object.
byte[] getIV() | Returns the IV or null if this parameter set does not contain an IV.
int getRounds() | Returns the number of rounds.
int getVersion() | Returns the version.
int getWordSize() | Returns the word size in bits.
int hashCode() | Calculates a hash code value for the object.

    The DHParameterSpec Class

    This class (which implements the AlgorithmParameterSpec interface) specifies the set of parameters used with the Diffie-Hellman algorithm.

    Method | Description
cff" colspan="2"> Methods in DHParameterSpec
BigInteger getG() | Returns the base generator g.
int getL() | Returns the size in bits, l, of the random exponent (private value).
BigInteger getP() | Returns the prime modulus p.

    Many types of Diffie-Hellman services will find this class useful; for example, it is used by the Diffie-Hellman key agreement, key pair generator, algorithm parameter generator, and algorithm parameters classes implemented by the "SunJCE" provider. As a specific example, an algorithm parameters implementation must include an implementation for the getParameterSpec method, which returns an AlgorithmParameterSpec. The Diffie-Hellman algorithm parameters implementation supplied by "SunJCE" returns an instance of the DHParameterSpec class.

    Key Specification Interfaces and Classes Required by Key Factories

    A key factory provides bi-directional conversions between opaque keys (of type Key) and key specifications. If you implement a key factory, you thus need to understand and utilize key specifications. In some cases, you also need to implement your own key specifications.

    Further information about key specifications, the interfaces and classes supplied in Java, and key factory requirements with respect to specifications, is provided below.

    Key specifications are transparent representations of the key material that constitutes a key. If the key is stored on a hardware device, its specification may contain information that helps identify the key on the device.

    A transparent representation of keys means that you can access each key material value individually, through one of the get methods defined in the corresponding specification class. For example, java.security.spec.DSAPrivateKeySpec defines getX, getP, getQ, and getG methods, to access the private key x, and the DSA algorithm parameters used to calculate the key: the prime p, the sub-prime q, and the base g.

    This is contrasted with an opaque representation, as defined by the Key interface, in which you have no direct access to the parameter fields. In other words, an "opaque" representation gives you limited access to the key - just the three methods defined by the Key interface: getAlgorithm, getFormat, and getEncoded.

    A key may be specified in an algorithm-specific way, or in an algorithm-independent encoding format (such as ASN.1). For example, a DSA private key may be specified by its components x, p, q, and g (see DSAPrivateKeySpec), or it may be specified using its DER encoding (see PKCS8EncodedKeySpec).

    Java defines the following key specification interfaces and classes in the java.security.spec and javax.crypto.spec packages:

    The KeySpec Interface

    This interface contains no methods or constants. Its only purpose is to group (and provide type safety for) all key specifications. All key specifications must implement this interface.

    Java supplies several classes implementing the KeySpec interface: DSAPrivateKeySpec, DSAPublicKeySpec, RSAPrivateKeySpec, RSAPublicKeySpec, EncodedKeySpec, PKCS8EncodedKeySpec, and X509EncodedKeySpec.

    If your provider uses key types (e.g., Your_PublicKey_type and Your_PrivateKey_type) for which the JDK does not already provide corresponding KeySpec classes, there are two possible scenarios, one of which requires that you implement your own key specifications:

    1. If your users will never have to access specific key material values of your key type, you will not have to provide any KeySpec classes for your key type.

      In this scenario, your users will always create Your_PublicKey_type and Your_PrivateKey_type keys through the appropriate KeyPairGenerator supplied by your provider for that key type. If they want to store the generated keys for later usage, they retrieve the keys' encodings (using the getEncoded method of the Key interface). When they want to create an Your_PublicKey_type or Your_PrivateKey_type key from the encoding (e.g., in order to initialize a Signature object for signing or verification), they create an instance of X509EncodedKeySpec or PKCS8EncodedKeySpec from the encoding, and feed it to the appropriate KeyFactory supplied by your provider for that algorithm, whose generatePublic and generatePrivate methods will return the requested PublicKey (an instance of Your_PublicKey_type) or PrivateKey (an instance of Your_PrivateKey_type) object, respectively.
    2. If you anticipate a need for users to access specific key material values of your key type, or to construct a key of your key type from key material and associated parameter values, rather than from its encoding (as in the above case), you have to specify new KeySpec classes (classes that implement the KeySpec interface) with the appropriate constructor methods and get methods for returning key material fields and associated parameter values for your key type. You will specify those classes in a similar manner as is done by the DSAPrivateKeySpec and DSAPublicKeySpec classes provided in JDK 6. You need to ship those classes along with your provider classes, for example, as part of your provider JAR file.

    The DSAPrivateKeySpec Class

    This class (which implements the KeySpec Interface) specifies a DSA private key with its associated parameters. It has the following methods:

    Method in DSAPrivateKeySpec | Description
public BigInteger getX() | Returns the private key x.
public BigInteger getP() | Returns the prime p.
public BigInteger getQ() | Returns the sub-prime q.
public BigInteger getG() | Returns the base g.

    These methods return the private key x, and the DSA algorithm parameters used to calculate the key: the prime p, the sub-prime q, and the base g.

    The DSAPublicKeySpec Class

    This class (which implements the KeySpec Interface) specifies a DSA public key with its associated parameters. It has the following methods:

    Method in DSAPublicKeySpec | Description
public BigInteger getY() | returns the public key y.
public BigInteger getP() | Returns the prime p.
public BigInteger getQ() | Returns the sub-prime q.
public BigInteger getG() | Returns the base g.

    These methods return the public key y, and the DSA algorithm parameters used to calculate the key: the prime p, the sub-prime q, and the base g.

    The RSAPrivateKeySpec Class

    This class (which implements the KeySpec Interface) specifies an RSA private key. It has the following methods:

    Method in RSAPrivateKeySpec | Description
public BigInteger getModulus() | Returns the modulus.
public BigInteger getPrivateExponent() | Returns the private exponent.

    These methods return the RSA modulus n and private exponent d values that constitute the RSA private key.

    The RSAPrivateCrtKeySpec Class

    This class (which extends the RSAPrivateKeySpec class) specifies an RSA private key, as defined in the PKCS#1 standard, using the Chinese Remainder Theorem (CRT) information values. It has the following methods (in addition to the methods inherited from its superclass RSAPrivateKeySpec ):

    Method in RSAPrivateCrtKeySpec | Description
public BigInteger getPublicExponent() | Returns the public exponent.
public BigInteger getPrimeP() | Returns the prime P.
public BigInteger getPrimeQ() | Returns the prime Q.
public BigInteger getPrimeExponentP() | Returns the primeExponentP.
public BigInteger getPrimeExponentQ() | Returns the primeExponentQ.
public BigInteger getCrtCoefficient() | Returns the crtCoefficient.

    These methods return the public exponent e and the CRT information integers: the prime factor p of the modulus n, the prime factor q of n, the exponent d mod (p-1), the exponent d mod (q-1), and the Chinese Remainder Theorem coefficient (inverse of q) mod p.

    An RSA private key logically consists of only the modulus and the private exponent. The presence of the CRT values is intended for efficiency.

    The RSAPublicKeySpec Class

    This class (which implements the KeySpec Interface) specifies an RSA public key. It has the following methods:

    Method in RSAPublicKeySpec | Description
public BigInteger getModulus() | Returns the modulus.
public BigInteger getPublicExponent() | Returns the public exponent.

    These methods return the RSA modulus n and public exponent e values that constitute the RSA public key.

    The EncodedKeySpec Class

    This abstract class (which implements the KeySpec Interface) represents a public or private key in encoded format.

    Method in EncodedKeySpec | Description
public abstract byte[] getEncoded() | Returns the encoded key.
public abstract String getFormat() | Returns the name of the encoding format.

    JDK 6 supplies two classes implementing the EncodedKeySpec interface: PKCS8EncodedKeySpec and X509EncodedKeySpec. If desired, you can supply your own EncodedKeySpec implementations for those or other types of key encodings.

    The PKCS8EncodedKeySpec Class

    This class, which is a subclass of EncodedKeySpec, represents the DER encoding of a private key, according to the format specified in the PKCS #8 standard.

    Its getEncoded method returns the key bytes, encoded according to the PKCS #8 standard. Its getFormat method returns the string "PKCS#8".

    The X509EncodedKeySpec Class

    This class, which is a subclass of EncodedKeySpec, represents the DER encoding of a public or private key, according to the format specified in the X.509 standard.

    Its getEncoded method returns the key bytes, encoded according to the X.509 standard. Its getFormat method returns the string "X.509". DHPrivateKeySpec, DHPublicKeySpec, DESKeySpec, DESedeKeySpec, PBEKeySpec, and SecretKeySpec.

    The DHPrivateKeySpec Class

    This class (which implements the KeySpec interface) specifies a Diffie-Hellman private key with its associated parameters.

    Method in DHPrivateKeySpec | Description
BigInteger getG() | Returns the base generator g.
BigInteger getP() | Returns the prime modulus p.
BigInteger getX() | Returns the private value x.

    The DHPublicKeySpec Class

    This class (which implements the KeySpec interface) specifies a Diffie-Hellman public key with its associated parameters.

    Method in DHPublicKeySpec | Description
BigInteger getG() | Returns the base generator g.
BigInteger getP() | Returns the prime modulus p.
BigInteger getY() | Returns the public value y.

    The DESKeySpec Class

    This class (which implements the KeySpec interface) specifies a DES key.

    Method in DESKeySpec | Description
byte[] getKey() | Returns the DES key bytes.
static boolean isParityAdjusted(byte[] key, int offset) | Checks if the given DES key material is parity-adjusted.
static boolean isWeak(byte[] key, int offset) | Checks if the given DES key material is weak or semi-weak.

    The DESedeKeySpec Class

    This class (which implements the KeySpec interface) specifies a DES-EDE (Triple DES) key.

    Method in DESedeKeySpec | Description
byte[] getKey() | Returns the DES-EDE key.
static boolean isParityAdjusted(byte[] key, int offset) | Checks if the given DES-EDE key is parity-adjusted.

    The PBEKeySpec Class

    This class implements the KeySpec interface. A user-chosen password can be used with password-based encryption (PBE); the password can be viewed as a type of raw key material. An encryption mechanism that uses this class can derive a cryptographic key from the raw key material.

    Method in PBEKeySpec | Description
void clearPassword | Clears the internal copy of the password.
int getIterationCount | Returns the iteration count or 0 if not specified.
int getKeyLength | Returns the to-be-derived key length or 0 if not specified.
char[] getPassword | Returns a copy of the password.
byte[] getSalt | Returns a copy of the salt or null if not specified.

    The SecretKeySpec Class

    This class implements the KeySpec interface. Since it also implements the SecretKey interface, it can be used to construct a SecretKey object in a provider-independent fashion, i.e., without having to go through a provider-based SecretKeyFactory.

    Method in SecretKeySpec | Description
boolean equals (Object obj) | Indicates whether some other object is "equal to" this one.
String getAlgorithm() | Returns the name of the algorithm associated with this secret key.
byte[] getEncoded() | Returns the key material of this secret key.
String getFormat() | Returns the name of the encoding format for this secret key.
int hashCode() | Calculates a hash code value for the object.

    Secret-Key Generation

    If you provide a secret-key generator (subclass of javax.crypto.KeyGeneratorSpi) for a particular secret-key algorithm, you may return the generated secret-key object (which must be an instance of javax.crypto.SecretKey, see engineGenerateKey) in one of the following ways:

    • You implement a class whose instances represent secret-keys of the algorithm associated with your key generator. Your key generator implementation returns instances of that class. This approach is useful if the keys generated by your key generator have provider-specific properties.
    • Your key generator returns an instance of SecretKeySpec, which already implements the javax.crypto.SecretKey interface. You pass the (raw) key bytes and the name of the secret-key algorithm associated with your key generator to the SecretKeySpec constructor. This approach is useful if the underlying (raw) key bytes can be represented as a byte array and have no key-parameters associated with them.

    Adding New Object Identifiers

    The following information applies to providers who supply an algorithm that is not listed as one of the standard algorithms in Appendix A of the Java Cryptography Architecture Reference Guide.

    Mapping from OID to Name

    Sometimes the JCA needs to instantiate a cryptographic algorithm implementation from an algorithm identifier (for example, as encoded in a certificate), which by definition includes the object identifier (OID) of the algorithm. For example, in order to verify the signature on an X.509 certificate, the JCA determines the signature algorithm from the signature algorithm identifier that is encoded in the certificate, instantiates a Signature object for that algorithm, and initializes the Signature object for verification.

    For the JCA to find your algorithm, you must provide the object identifier of your algorithm as an alias entry for your algorithm in the provider master file.

        put("Alg.Alias.<engine_type>.1.2.3.4.5.6.7.8",
    "<algorithm_alias_name>");

    Note that if your algorithm is known under more than one object identifier, you need to create an alias entry for each object identifier under which it is known.

    An example of where the JCA needs to perform this type of mapping is when your algorithm ("Foo") is a signature algorithm and users run the keytool command and specify your (signature) algorithm alias.

        % keytool -genkeypair -sigalg 1.2.3.4.5.6.7.8

    In this case, your provider master file should contain the following entries:

        put("Signature.Foo", "com.xyz.MyFooSignatureImpl");
    put("Alg.Alias.Signature.1.2.3.4.5.6.7.8", "Foo");

    Other examples of where this type of mapping is performed are (1) when your algorithm is a keytype algorithm and your program parses a certificate (using the X.509 implementation of the SUN provider) and extracts the public key from the certificate in order to initialize a Signature object for verification, and (2) when keytool users try to access a private key of your keytype (for example, to perform a digital signature) after having generated the corresponding keypair. In these cases, your provider master file should contain the following entries:

        put("KeyFactory.Foo", "com.xyz.MyFooKeyFactoryImpl");
    put("Alg.Alias.KeyFactory.1.2.3.4.5.6.7.8", "Foo");

    Mapping from Name to OID

    If the JCA needs to perform the inverse mapping (that is, from your algorithm name to its associated OID), you need to provide an alias entry of the following form for one of the OIDs under which your algorithm should be known:

        put("Alg.Alias.Signature.OID.1.2.3.4.5.6.7.8", "MySigAlg");

    If your algorithm is known under more than one object identifier, prefix the preferred one with "OID."

    An example of where the JCA needs to perform this kind of mapping is when users run keytool in any mode that takes a -sigalg option. For example, when the -genkeypair and -certreq commands are invoked, the user can specify your (signature) algorithm with the -sigalg option.

    Ensuring Exportability

    A key feature of JCA is the exportability of the JCA framework and of the provider cryptography implementations if certain conditions are met.

    Due to import control restrictions by the governments of a few countries, the jurisdiction policy files shipped with the JDK 6 from Sun Microsystems specify that "strong" but limited cryptography may be used. An "unlimited" version of these files indicating no restrictions on cryptographic strengths is available for those living in eligible countries (which is most countries). But only the "strong" version can be imported into those countries whose governments mandate restrictions. The JCA framework will enforce the restrictions specified in the installed jurisdiction policy files.

    As noted elsewhere, you can write just one version of your provider software, implementing cryptography of maximum strength. It is up to JCA, not your provider, to enforce any jurisdiction policy file-mandated restrictions regarding the cryptographic algorithms and maximum cryptographic strengths available to applets/applications in different locations.

    The conditions that must be met by your provider in order to enable it to be plugged into JCA are the following:

    • The constructor of each SPI implementation class should do self-integrity checking, as described in How a Provider Can Do Self-Integrity Checking.

    • The provider code should be written in such a way that provider classes become unusable if instantiated by an application directly, bypassing JCA. See Step 1: Write Your Service Implementation Code in the Steps to Implement and Integrate a Provider section.

    • The provider package must be signed by an entity trusted by the JCA framework. (See Step 6.1 through Step 6.2.) U.S. vendors whose providers may be exported outside the U.S. first need to apply for U.S. government export approval. (See Step 10.)

    Appendix A: The Sun Provider Master Class

    Below is an edited version of the Sun.java file, which contains a class named Sun that is the master class for the provider named Sun.

    As with all master classes, this class is a subclass of Provider. It specifies the class names and package locations of all service implementations supplied by the Sun provider. This information is used by the getInstance methods of the engine classes to look up the various algorithms and other services when they are requested.

    This code is supplied as an example of a provider master class.

    /*
 * @(#)Sun.java	1.28 99/05/27
 *
 * Copyright 1996-1998 by Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Sun Microsystems, Inc. ("Confidential Information").  You
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with Sun.
 */

package sun.security.provider;

import java.io.*;
import java.util.*;
import java.security.*;

/**
 * The SUN Security Provider.
 *
 * @author Benjamin Renaud
 *
 * @version 1.28, 05/27/99
 */

/**
 * Defines the SUN provider.
 *
 * Algorithms supported, and their names:
 *
 * - SHA is the message digest scheme described in FIPS 180-1.
 *   Aliases for SHA are SHA-1 and SHA1.
 *
 * - SHA1withDSA is the signature scheme described in FIPS 186.
 *   (SHA used in DSA is SHA-1: FIPS 186 with Change No 1.)
 *   Aliases for SHA1withDSA are DSA, DSS, SHA/DSA, SHA-1/DSA, SHA1/DSA,
 *   SHAwithDSA, DSAWithSHA1, and the object
 *   identifier strings "OID.1.3.14.3.2.13", "OID.1.3.14.3.2.27" and
 *   "OID.1.2.840.10040.4.3".
 *
 * - DSA is the key generation scheme as described in FIPS 186.
 *   Aliases for DSA include the OID strings "OID.1.3.14.3.2.12"
 *   and "OID.1.2.840.10040.4.1".
 *
 * - MD5 is the message digest scheme described in RFC 1321.
 *   There are no aliases for MD5.
 */

public final class Sun extends Provider {

    private static final String INFO = "SUN " +
    "(DSA key/parameter generation; DSA signing; " +
    "SHA-1, MD5 digests; SecureRandom; X.509 certificates; JKS keystore)";

    public Sun() {
    /* We are the SUN provider */
    super("SUN", 1.2, INFO);

    AccessController.doPrivileged(new java.security.PrivilegedAction() {
        public Object run() {

        /*
         * Signature engines
         */
        put("Signature.SHA1withDSA", "sun.security.provider.DSA");

        put("Alg.Alias.Signature.DSA", "SHA1withDSA");
        put("Alg.Alias.Signature.DSS", "SHA1withDSA");
        put("Alg.Alias.Signature.SHA/DSA", "SHA1withDSA");
        put("Alg.Alias.Signature.SHA-1/DSA", "SHA1withDSA");
        put("Alg.Alias.Signature.SHA1/DSA", "SHA1withDSA");
        put("Alg.Alias.Signature.SHAwithDSA", "SHA1withDSA");
        put("Alg.Alias.Signature.DSAWithSHA1", "SHA1withDSA");
        put("Alg.Alias.Signature.OID.1.2.840.10040.4.3",
            "SHA1withDSA");
        put("Alg.Alias.Signature.1.2.840.10040.4.3", "SHA1withDSA");
        put("Alg.Alias.Signature.1.3.14.3.2.13", "SHA1withDSA");
        put("Alg.Alias.Signature.1.3.14.3.2.27", "SHA1withDSA");

        /*
         *  Key Pair Generator engines
         */
        put("KeyPairGenerator.DSA",
            "sun.security.provider.DSAKeyPairGenerator");
        put("Alg.Alias.KeyPairGenerator.OID.1.2.840.10040.4.1", "DSA");
        put("Alg.Alias.KeyPairGenerator.1.2.840.10040.4.1", "DSA");
        put("Alg.Alias.KeyPairGenerator.1.3.14.3.2.12", "DSA");

        /*
         * Digest engines
         */
        put("MessageDigest.MD5", "sun.security.provider.MD5");
        put("MessageDigest.SHA", "sun.security.provider.SHA");

        put("Alg.Alias.MessageDigest.SHA-1", "SHA");
        put("Alg.Alias.MessageDigest.SHA1", "SHA");

        /*
         * Algorithm Parameter Generator engines
         */
        put("AlgorithmParameterGenerator.DSA",
            "sun.security.provider.DSAParameterGenerator");

        /*
         * Algorithm Parameter engines
         */
        put("AlgorithmParameters.DSA",
            "sun.security.provider.DSAParameters");
        put("Alg.Alias.AlgorithmParameters.1.3.14.3.2.12", "DSA");
        put("Alg.Alias.AlgorithmParameters.1.2.840.10040.4.1", "DSA");

        /*
         * Key factories
         */
        put("KeyFactory.DSA", "sun.security.provider.DSAKeyFactory");
        put("Alg.Alias.KeyFactory.1.3.14.3.2.12", "DSA");
        put("Alg.Alias.KeyFactory.1.2.840.10040.4.1", "DSA");

        /*
         * SecureRandom
         */
         put("SecureRandom.SHA1PRNG",
             "sun.security.provider.SecureRandom");

        /*
         * Certificates
         */
        put("CertificateFactory.X509",
            "sun.security.provider.X509Factory");
        put("Alg.Alias.CertificateFactory.X.509", "X509");

        /*
         * KeyStore
         */
        put("KeyStore.JKS", "sun.security.provider.JavaKeyStore");

        /*
         * KeySize
         */
        put("Signature.SHA1withDSA KeySize", "1024");
        put("KeyPairGenerator.DSA KeySize", "1024");
        put("AlgorithmParameterGenerator.DSA KeySize", "1024");

        /*
         * Implementation type: software or hardware
         */
        put("Signature.SHA1withDSA ImplementedIn", "Software");
        put("KeyPairGenerator.DSA ImplementedIn", "Software");
        put("MessageDigest.MD5 ImplementedIn", "Software");
        put("MessageDigest.SHA ImplementedIn", "Software");
        put("AlgorithmParameterGenerator.DSA ImplementedIn",
            "Software");
        put("AlgorithmParameters.DSA ImplementedIn", "Software");
        put("KeyFactory.DSA ImplementedIn", "Software");
        put("SecureRandom.SHA1PRNG ImplementedIn", "Software");
        put("CertificateFactory.X509 ImplementedIn", "Software");
        put("KeyStore.JKS ImplementedIn", "Software");

        return null;
        }
    });
    }
}

    Appendix B: The SunJCE Provider Master Class

    Below is an edited version of the SunJCE.java file, which contains a class named SunJCE that is the master class for the provider named SunJCE.

    As with all master classes, this class is a subclass of Provider. It specifies the class names and package locations of all the cryptographic service implementations supplied by the SunJCE provider. This information is used by the getInstance methods of the engine classes to look up the various algorithms and other services when they are requested.

    This code is supplied as an example of a provider master class.

    /*
 * @(#)SunJCE.java	1.73 05/12/13
 *
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package com.sun.crypto.provider;

import java.security.*;
import java.security.cert.*;
import java.net.URL;
import java.io.ByteArrayInputStream;

/**
 * The "SunJCE" Cryptographic Service Provider.
 *
 * @author Jan Luehe
 * @author Sharon Liu
 *
 * @version 1.73, 12/13/05
 */

/**
 * Defines the "SunJCE" provider.
 *
 * Supported algorithms and their names:
 *
 * ...edited for space...
 *
 */

public final class SunJCE extends Provider {

    private static final String info = "SunJCE Provider " +
    "(implements RSA, DES, Triple DES, AES, Blowfish, ARCFOUR, RC2, PBE, "
    + "Diffie-Hellman, HMAC)";

    private static final String OID_PKCS5_MD5_DES = "1.2.840.113549.1.5.3";
    private static final String OID_PKCS3 = "1.2.840.113549.1.3.1";

    public SunJCE() {
    /* We are the "SunJCE" provider */
    super("SunJCE", 1.6d, info);

    final String BLOCK_MODES = "ECB|CBC|PCBC|CTR|CTS|CFB|OFB" +
        "|CFB8|CFB16|CFB24|CFB32|CFB40|CFB48|CFB56|CFB64" +
        "|OFB8|OFB16|OFB24|OFB32|OFB40|OFB48|OFB56|OFB64";
    final String BLOCK_MODES128 = BLOCK_MODES +
        "|CFB72|CFB80|CFB88|CFB96|CFB104|CFB112|CFB120|CFB128" +
        "|OFB72|OFB80|OFB88|OFB96|OFB104|OFB112|OFB120|OFB128";
    final String BLOCK_PADS = "NOPADDING|PKCS5PADDING|ISO10126PADDING";

    AccessController.doPrivileged(new java.security.PrivilegedAction() {
        public Object run() {

        /*
         * Cipher engines
         */
        put("Cipher.RSA", "com.sun.crypto.provider.RSACipher");
        put("Cipher.RSA SupportedModes", "ECB");
        put("Cipher.RSA SupportedPaddings",
            "NOPADDING|PKCS1PADDING|OAEPWITHMD5ANDMGF1PADDING"
            + "|OAEPWITHSHA1ANDMGF1PADDING"
            + "|OAEPWITHSHA-1ANDMGF1PADDING"
            + "|OAEPWITHSHA-256ANDMGF1PADDING"
            + "|OAEPWITHSHA-384ANDMGF1PADDING"
            + "|OAEPWITHSHA-512ANDMGF1PADDING");
        put("Cipher.RSA SupportedKeyClasses",
            "java.security.interfaces.RSAPublicKey" +
            "|java.security.interfaces.RSAPrivateKey");

        put("Cipher.PBEWithMD5AndDES",
            "com.sun.crypto.provider.PBEWithMD5AndDESCipher");
        put("Alg.Alias.Cipher.OID."+OID_PKCS5_MD5_DES,
            "PBEWithMD5AndDES");
        put("Alg.Alias.Cipher."+OID_PKCS5_MD5_DES,
            "PBEWithMD5AndDES");

        put("Cipher.AES", "com.sun.crypto.provider.AESCipher");
        put("Alg.Alias.Cipher.Rijndael", "AES");
        put("Cipher.AES SupportedModes", BLOCK_MODES128);
        put("Cipher.AES SupportedPaddings", BLOCK_PADS);
        put("Cipher.AES SupportedKeyFormats", "RAW");

        put("Cipher.AESWrap", "com.sun.crypto.provider.AESWrapCipher");
        put("Cipher.AESWrap SupportedModes", "ECB");
        put("Cipher.AESWrap SupportedPaddings", "NOPADDING");
        put("Cipher.AESWrap SupportedKeyFormats", "RAW");

        put("Cipher.ARCFOUR",
            "com.sun.crypto.provider.ARCFOURCipher");
        put("Alg.Alias.Cipher.RC4", "ARCFOUR");
        put("Cipher.ARCFOUR SupportedModes", "ECB");
        put("Cipher.ARCFOUR SupportedPaddings", "NOPADDING");
        put("Cipher.ARCFOUR SupportedKeyFormats", "RAW");

        /*
         *  Key(pair) Generator engines
         */
        put("KeyGenerator.AES",
            "com.sun.crypto.provider.AESKeyGenerator");
        put("Alg.Alias.KeyGenerator.Rijndael", "AES");

        put("KeyGenerator.ARCFOUR",
            "com.sun.crypto.provider.KeyGeneratorCore$" +
            "ARCFOURKeyGenerator");
        put("Alg.Alias.KeyGenerator.RC4", "ARCFOUR");

        put("KeyGenerator.HmacMD5",
            "com.sun.crypto.provider.HmacMD5KeyGenerator");

        put("KeyGenerator.HmacSHA256",
            "com.sun.crypto.provider.KeyGeneratorCore$HmacSHA256KG");

        put("KeyPairGenerator.DiffieHellman",
            "com.sun.crypto.provider.DHKeyPairGenerator");
        put("Alg.Alias.KeyPairGenerator.DH", "DiffieHellman");
        put("Alg.Alias.KeyPairGenerator.OID."+OID_PKCS3,
            "DiffieHellman");
        put("Alg.Alias.KeyPairGenerator."+OID_PKCS3,
            "DiffieHellman");

        /*
         * Algorithm parameter generation engines
         */
        put("AlgorithmParameterGenerator.DiffieHellman",
            "com.sun.crypto.provider.DHParameterGenerator");
        put("Alg.Alias.AlgorithmParameterGenerator.DH",
            "DiffieHellman");
        put("Alg.Alias.AlgorithmParameterGenerator.OID."+OID_PKCS3,
            "DiffieHellman");
        put("Alg.Alias.AlgorithmParameterGenerator."+OID_PKCS3,
            "DiffieHellman");

        /*
         * Key Agreement engines
         */
        put("KeyAgreement.DiffieHellman",
            "com.sun.crypto.provider.DHKeyAgreement");
        put("Alg.Alias.KeyAgreement.DH", "DiffieHellman");
        put("Alg.Alias.KeyAgreement.OID."+OID_PKCS3, "DiffieHellman");
        put("Alg.Alias.KeyAgreement."+OID_PKCS3, "DiffieHellman");

        put("KeyAgreement.DiffieHellman SupportedKeyClasses",
            "javax.crypto.interfaces.DHPublicKey" +
            "|javax.crypto.interfaces.DHPrivateKey");

        /*
         * Algorithm Parameter engines
         */
        put("AlgorithmParameters.DiffieHellman",
            "com.sun.crypto.provider.DHParameters");
        put("Alg.Alias.AlgorithmParameters.DH", "DiffieHellman");
        put("Alg.Alias.AlgorithmParameters.OID."+OID_PKCS3,
            "DiffieHellman");
        put("Alg.Alias.AlgorithmParameters."+OID_PKCS3,
            "DiffieHellman");

        put("AlgorithmParameters.PBEWithMD5AndDES",
            "com.sun.crypto.provider.PBEParameters");
        put("Alg.Alias.AlgorithmParameters.OID."+OID_PKCS5_MD5_DES,
            "PBEWithMD5AndDES");
        put("Alg.Alias.AlgorithmParameters."+OID_PKCS5_MD5_DES,
            "PBEWithMD5AndDES");

        put("AlgorithmParameters.OAEP",
            "com.sun.crypto.provider.OAEPParameters");

        /*
         * Key factories
         */
        put("KeyFactory.DiffieHellman",
            "com.sun.crypto.provider.DHKeyFactory");
        put("Alg.Alias.KeyFactory.DH", "DiffieHellman");
        put("Alg.Alias.KeyFactory.OID."+OID_PKCS3,
            "DiffieHellman");
        put("Alg.Alias.KeyFactory."+OID_PKCS3, "DiffieHellman");

        /*
         * Secret-key factories
         */
        put("SecretKeyFactory.PBEWithMD5AndDES",
            "com.sun.crypto.provider.PBEKeyFactory$PBEWithMD5AndDES"
            );
        put("Alg.Alias.SecretKeyFactory.OID."+OID_PKCS5_MD5_DES,
            "PBEWithMD5AndDES");
        put("Alg.Alias.SecretKeyFactory."+OID_PKCS5_MD5_DES,
            "PBEWithMD5AndDES");

        /*
         * MAC
         */
        put("Mac.HmacMD5", "com.sun.crypto.provider.HmacMD5");
        put("Mac.HmacSHA256",
            "com.sun.crypto.provider.HmacCore$HmacSHA256");

        put("Mac.HmacMD5 SupportedKeyFormats", "RAW");
        put("Mac.HmacSHA256 SupportedKeyFormats", "RAW");

        /*
         * KeyStore
         */
        put("KeyStore.JCEKS", "com.sun.crypto.provider.JceKeyStore");

        return null;
        }
    });
    }
}

    Appendix C: The java.security.properties File

    Below is part of the java.security file that shows the default list of installed providers. It appears in every JRE installation. The file also contains other entries, but for brevity, we show only part of the file here. See the complete file at:

    <java-home>/lib/security/java.security	 [Solaris]
<java-home>\lib\security\java.security	 [Win32]

    Here <java-home> refers to the directory where the JRE was installed.

    See Step 5 for an example of adding information about your provider to this file.

    #
# This is the "master security properties file".
#
# In this file, various security properties are set for use by
# java.security classes. This is where users can statically register
# Cryptography Package Providers ("providers" for short). The term
# "provider" refers to a package or set of packages that supply a
# concrete implementation of a subset of the cryptography aspects of
# the Java Security API. A provider may, for example, implement one or
# more digital signature algorithms or message digest algorithms.
#
# Each provider must implement a subclass of the Provider class.
# To register a provider in this master security properties file,
# specify the Provider subclass name and priority in the format
#
#    security.provider.=
#
# This declares a provider, and specifies its preference
# order n. The preference order is the order in which providers are
# searched for requested algorithms (when no specific provider is
# requested). The order is 1-based; 1 is the most preferred, followed
# by 2, and so on.
#
# <className> must specify the subclass of the Provider class whose
# constructor sets the values of various properties that are required
# for the Java Security API to look up the algorithms or other
# facilities implemented by the provider.
#
# There must be at least one provider specification in java.security.
# There is a default provider that comes standard with the JDK. It
# is called the "SUN" provider, and its Provider subclass
# named Sun appears in the sun.security.provider package. Thus, the
# "SUN" provider is registered via the following:
#
#    security.provider.1=sun.security.provider.Sun
#
# (The number 1 is used for the default provider.)
#
# Note: Providers can be dynamically registered instead by calls to
# either the addProvider or insertProviderAt method in the Security
# class.

#
# List of providers and their preference orders (see above):
#

security.provider.1=sun.security.pkcs11.SunPKCS11 \
    ${java.home}/lib/security/sunpkcs11-solaris.cfg
security.provider.2=sun.security.provider.Sun
security.provider.3=sun.security.rsa.SunRsaSign
security.provider.4=com.sun.net.ssl.internal.ssl.Provider
security.provider.5=com.sun.crypto.provider.SunJCE
security.provider.6=sun.security.jgss.SunProvider
security.provider.7=com.sun.security.sasl.Provider
security.provider.8=org.jcp.xml.dsig.internal.dom.XMLDSigRI
security.provider.9=sun.security.smartcardio.SunPCSC

# Rest of file deleted


Java ™ Cryptography Architecture
(JCA) Reference Guide

for JavaTM Platform Standard Edition 6

Introduction

Design Principles
Architecture
JCA Concepts

Core Classes and Interfaces

The Provider Class
How Provider Implementations are Requested and Supplied
Installing Providers
The Security Class
The SecureRandom Class
The MessageDigest Class
The Signature Class
The Cipher Class
Other Cipher-based Classes
The Cipher Stream Classes
The CipherInputStream Class
The CipherOutputStream Class
The SealedObject Class
The Mac Class
Key Interfaces
The KeyPair Class
Key Specification Interfaces and Classes
The KeySpec Interface
The KeySpec Subinterfaces
The EncodedKeySpec Class
The PKCS8EncodedKeySpec Class
The X509EncodedKeySpec Class
Of Factories and Generators
The KeyFactory Class
The SecretKeyFactory Class
The KeyPairGenerator Class
The KeyGenerator Class
The KeyAgreement Class
Key Management
Keystore Location
Keystore Implementation
The KeyStore Class
Algorithm Parameters Classes
The AlgorithmParameterSpec Interface
The AlgorithmParameters Class
The AlgorithmParameterGenerator Class
The CertificateFactory Class
How the JCA Might Be Used in a SSL/TLS Implementation

How to Make Applications "Exempt" from Cryptographic Restrictions

Code Examples

Computing a MessageDigest Object
Generating a Pair of Keys
Generating and Verifying a Signature Using Generated Keys
Generating/Verifying Signatures Using Key Specifications and KeyFactory
Determining If Two Keys Are Equal
Reading Base64-Encoded Certificates
Parsing a Certificate Reply
Using Encryption
Using Password-Based Encryption
Using Key Agreement
Appendix A: Standard Names

Appendix B: Jurisdiction Policy File Format

Appendix C: Maximum Key Sizes Allowed by "Strong" Jurisdiction Policy Files

Appendix D: Sample Programs

Diffie-Hellman Key Exchange between 2 Parties
Diffie-Hellman Key Exchange between 3 Parties
Blowfish Cipher Example
HMAC-MD5 Example
Reading ASCII Passwords From an InputStream Example

Introduction

The Java platform strongly emphasizes security, including language safety, cryptography, public key infrastructure, authentication, secure communication, and access control.

The JCA is a major piece of the platform, and contains a "provider" architecture and a set of APIs for digital signatures, message digests (hashs), certificates and certificate validation, encryption (symmetric/asymmetric block/stream ciphers), key generation and management, and secure random number generation, to name a few. These APIs allow developers to easily integrate security into their application code. The architecture was designed around the following principles:

  1. Implementation independence
    Applications do not need to implement security algorithms. Rather, they can request security services from the Java platform. Security services are implemented in providers (see below), which are plugged into the Java platform via a standard interface. An application may rely on multiple independent providers for security functionality.
  2. Implementation interoperability
    Providers are interoperable across applications. Specifically, an application is not bound to a specific provider, and a provider is not bound to a specific application.
  3. Algorithm extensibility
    The Java platform includes a number of built-in providers that implement a basic set of security services that are widely used today. However, some applications may rely on emerging standards not yet implemented, or on proprietary services. The Java platform supports the installation of custom providers that implement such services.

Other cryptographic communication libraries available in the JDK use the JCA provider architecture, but are described elsewhere. The JavaTM Secure Socket Extension (JSSE) provides access to Secure Socket Layer (SSL) and Transport Layer Security (TLS) implementations. The Java Generic Security Services (JGSS) (via Kerberos) APIs, and the Simple Authentication and Security Layer (SASL) can also be used for securely exchanging messages between communicating applications.

Notes on Terminology

  • Prior to JDK 1.4, the JCE was an unbundled product, and as such, the JCA and JCE were regularly referred to as separate, distinct components. As JCE is now bundled in the JDK, the distinction is becoming less apparent. Since the JCE uses the same architecture as the JCA, the JCE should be more properly thought of as a part of the JCA.

  • The JCA within the JDK includes two software components:

    1. the framework that defines and supports cryptographic services for which providers supply implementations. This framework includes packages such as java.security, javax.crypto, javax.crypto.spec, and javax.crypto.interfaces.

    2. the actual providers such as Sun, SunRsaSign, SunJCE, which contain the actual cryptographic implementations.

    Whenever a specific JCA provider is mentioned, it will be referred to explicitly by the provider's name.

WARNING: The JCA makes it easy to incorporate security features into your application. However, this document does not cover the theory of security/cryptography beyond an elementary introduction to concepts necessary to discuss the APIs. This document also does not cover the strengths/weaknesses of specific algorithms, not does it cover protocol design. Cryptography is an advanced topic and one should consult a solid, preferably recent, reference in order to make best use of these tools.

You should always understand what you are doing and why: DO NOT simply copy random code and expect it to fully solve your usage scenario. Many applications have been deployed that contain significant security or performance problems because the wrong tool or algorithm was selected.

Design Principles

The JCA was designed around these principles:

  • implementation independence and interoperability

  • algorithm independence and extensibility

Implementation independence and algorithm independence are complementary; you can use cryptographic services, such as digital signatures and message digests, without worrying about the implementation details or even the algorithms that form the basis for these concepts. While complete algorithm-independence is not possible, the JCA provides standardized, algorithm-specific APIs. When implementation-independence is not desirable, the JCA lets developers indicate a specific implementation.

Algorithm independence is achieved by defining types of cryptographic "engines" (services), and defining classes that provide the functionality of these cryptographic engines. These classes are called engine classes, and examples are the MessageDigest, Signature, KeyFactory, KeyPairGenerator, and Cipher classes.

Implementation independence is achieved using a "provider"-based architecture. The term Cryptographic Service Provider (CSP) (used interchangeably with "provider" in this document) refers to a package or set of packages that implement one or more cryptographic services, such as digital signature algorithms, message digest algorithms, and key conversion services. A program may simply request a particular type of object (such as a Signature object) implementing a particular service (such as the DSA signature algorithm) and get an implementation from one of the installed providers. If desired, a program may instead request an implementation from a specific provider. Providers may be updated transparently to the application, for example when faster or more secure versions are available.

Implementation interoperability means that various implementations can work with each other, use each other's keys, or verify each other's signatures. This would mean, for example, that for the same algorithms, a key generated by one provider would be usable by another, and a signature generated by one provider would be verifiable by another.

Algorithm extensibility means that new algorithms that fit in one of the supported engine classes can be added easily.

Architecture

Cryptographic Service Providers

java.security.Provider is the base class for all security providers. Each CSP contains an instance of this class which contains the provider's name and lists all of the security services/algorithms it implements. When an instance of a particular algorithm is needed, the JCA framework consults the provider's database, and if a suitable match is found, the instance is created.

Providers contain a package (or a set of packages) that supply concrete implementations for the advertised cryptographic algorithms. Each JDK installation has one or more providers installed and configured by default. Additional providers may be added statically or dynamically (see the Provider and Security classes). Clients may configure their runtime environment to specify the provider preference order. The preference order is the order in which providers are searched for requested services when no specific provider is requested.

To use the JCA, an application simply requests a particular type of object (such as a MessageDigest) and a particular algorithm or service (such as the "MD5" algorithm), and gets an implementation from one of the installed providers. Alternatively, the program can request the objects from a specific provider. Each provider has a name used to refer to it.

    md = MessageDigest.getInstance("MD5");
    md = MessageDigest.getInstance("MD5", "ProviderC");

The following figure illustrates requesting an "MD5" message digest implementation. The figure show three different providers that implement various message digest algorithms ("SHA-1", "MD5", "SHA-256", and "SHA-256"). The providers are ordered by preference from left to right (1-3). In the first illustration, an application requests an MD5 algorithm implementation without specifying a provider name. The providers are searched in preference order and the implementation from the first provider supplying that particular algorithm, ProviderB, is returned. In the second figure, the application requests the MD5 algorithm implementation from a specific provider, ProviderC. This time the implementation from ProviderC is returned, even though a provider with a higher preference order, ProviderB, also supplies an MD5 implementation.

">

Cryptographic implementations in the Sun JDK are distributed via several different providers (Sun, SunJSSE, SunJCE, SunRsaSign) primarily for historical reasons, but to a lesser extent by the type of functionality and algorithms they provide. Other Java runtime environments may not necessarily contain these Sun providers, so applications should not request an provider-specific implementation unless it is known that a particular provider will be available.

The JCA offers a set of APIs that allow users to query which providers are installed and what services they support.

This architecture also makes it easy for end-users to add additional providers. Many third party provider implementations are already available. See The Provider Class for more information on how providers are written, installed, and registered.

How Providers Are Actually Implemented

As mentioned earlier, algorithm independence is achieved by defining a generic high-level Application Programming Interface (API) that all applications use to access a service type. Implementation independence is achieved by having all provider implementations conform to well-defined interfaces. Instances of engine classes are thus "backed" by implementation classes which have the same method signatures. Application calls are routed through the engine class and are delivered to the underlying backing implementation. The implementation handles the request and return the proper results.

The application API methods in each engine class are routed to the provider's implementations through classes that implement the corresponding Service Provider Interface (SPI). That is, for each engine class, there is a corresponding abstract SPI class which defines the methods that each cryptographic service provider's algorithm must implement. The name of each SPI class is the same as that of the corresponding engine class, followed by Spi. For example, the Signature engine class provides access to the functionality of a digital signature algorithm. The actual provider implementation is supplied in a subclass of SignatureSpi. Applications call the engine class' API methods, which in turn call the SPI methods in the actual implementation.

Each SPI class is abstract. To supply the implementation of a particular type of service for a specific algorithm, a provider must subclass the corresponding SPI class and provide implementations for all the abstract methods.

For each engine class in the API, implementation instances are requested and instantiated by calling the getInstance() factory method in the engine class. A factory method is a static method that returns an instance of a class. The engine classes use the framework provider selection mechanism described above to obtain the actual backing implementation (SPI), and then creates the actual engine object. Each instance of the engine class encapsulates (as a private field) the instance of the corresponding SPI class, known as the SPI object. All API methods of an API object are declared final and their implementations invoke the corresponding SPI methods of the encapsulated SPI object.

To make this clearer, review the following code and illustration:

    import javax.crypto.*;

    Cipher c = Cipher.getInstance("AES");
    c.init(ENCRYPT_MODE, key);

">

Here an application wants an "AES" javax.crypto.Cipher instance, and doesn't care which provider is used. The application calls the getInstance() factory methods of the Cipher engine class, which in turn asks the JCA framework to find the first provider instance that supports "AES". The framework consults each installed provider, and obtains the provider's instance of the Provider class. (Recall that the Provider class is a database of available algorithms.) The framework searches each provider, finally finding a suitable entry in CSP3. This database entry points to the implementation class com.foo.AESCipher which extends CipherSpi, and is thus suitable for use by the Cipher engine class. An instance of com.foo.AESCipher is created, and is encapsulated in a newly-created instance of javax.crypto.Cipher, which is returned to the application. When the application now does the init() operation on the Cipher instance, the Cipher engine class routes the request into the corresponding engineInit() backing method in the com.foo.AESCipher class.

Appendix A lists the Standard Names defined for the Java environment. Other third-party providers may define their own implementations of these services, or even additional services.

Key Management

A database called a "keystore" can be used to manage a repository of keys and certificates. Keystores are available to applications that need data for authentication, encryption, or signing purposes.

Applications can access a keystore via an implementation of the KeyStore class, which is in the java.security package. A default KeyStore implementation is provided by Sun Microsystems. It implements the keystore as a file, using a proprietary keystore type (format) named "jks". Other keystore formats are available, such as "jceks" which is an alternate proprietary keystore format with much stronger encryption than "jks", and "pkcs12", which is based on the RSA PKCS12 Personal Information Exchange Syntax Standard.

Applications can choose different keystore implementations from different providers, using the same provider mechanism described above.

See the Key Management section for more information.

JCA Concepts

This section introduces the major JCA APIs.

Engine Classes and Algorithms

An engine class provides the interface to a specific type of cryptographic service, independent of a particular cryptographic algorithm or provider. The engines either provide:

  • cryptographic operations (encryption, digital signatures, message digests, etc.),
  • generators or converters of cryptographic material (keys and algorithm parameters), or
  • objects (keystores or certificates) that encapsulate the cryptographic data and can be used at higher layers of abstraction.

The following engine classes are available:

  • SecureRandom: used to generate random or pseudo-random numbers.

  • MessageDigest: used to calculate the message digest (hash) of specified data.

  • Signature: initilialized with keys, these are used to sign data and verify digital signatures.

  • Cipher: initialized with keys, these used for encrypting/decrypting data. There are various types of algorithms: symmetric bulk encryption (e.g. AES, DES, DESede, Blowfish, IDEA), stream encryption (e.g. RC4), asymmetric encryption (e.g. RSA), and password-based encryption (PBE).

  • Message Authentication Codes (MAC): like MessageDigests, these also generate hash values, but are first initialized with keys to protect the integrity of messages.

  • KeyFactory: used to convert existing opaque cryptographic keys of type Key into key specifications (transparent representations of the underlying key material), and vice versa.

  • SecretKeyFactory: used to convert existing opaque cryptographic keys of type SecretKey into key specifications (transparent representations of the underlying key material), and vice versa. SecretKeyFactorys are specialized KeyFactorys that create secret (symmetric) keys only.

  • KeyPairGenerator: used to generate a new pair of public and private keys suitable for use with a specified algorithm.

  • KeyGenerator: used to generate new secret keys for use with a specified algorithm.

  • KeyAgreement: used by two or more parties to agree upon and establish a specific key to use for a particular cryptographic operation.

  • AlgorithmParameters: used to store the parameters for a particular algorithm, including parameter encoding and decoding.

  • AlgorithmParameterGenerator : used to generate a set of AlgorithmParameters suitable for a specified algorithm.

  • KeyStore: used to create and manage a keystore. A keystore is a database of keys. Private keys in a keystore have a certificate chain associated with them, which authenticates the corresponding public key. A keystore also contains certificates from trusted entities.

  • CertificateFactory: used to create public key certificates and Certificate Revocation Lists (CRLs).

  • CertPathBuilder: used to build certificate chains (also known as certification paths).

  • CertPathValidator: used to validate certificate chains.

  • CertStore: used to retrieve Certificates and CRLs from a repository.

NOTE: A generator creates objects with brand-new contents, whereas a factory creates objects from existing material (for example, an encoding).

Core Classes and Interfaces

This section discusses the core classes and interfaces provided in the JCA:

  • the Provider and Security classes,

  • the SecureRandom, MessageDigest, Signature, Cipher, Mac, KeyFactory, SecretKeyFactory, KeyPairGenerator, KeyGenerator, KeyAgreement, AlgorithmParameters, AlgorithmParameterGenerator , KeyStore, and CertificateFactory, engine classes,

  • the Key interfaces and classes,

  • the Algorithm Parameter Specification Interfaces and Classes and the Key Specification Interfaces and Classes, and

  • miscellaneous support and convenience interfaces and classes.

    • NOTE: For more information on the CertPathBuilder, CertPathValidator, and CertStore engine classes, please see the Java(TM) PKI Programmer's Guide.
The guide will cover the most useful high-level classes first (Provider, Security, SecureRandom, MessageDigest, Signature, Cipher, and Mac), then delve into the various support classes. For now, it is sufficient to simply say that Keys (public, private, and secret) are generated and represented by the various JCA classes, and are used by the high-level classes as part of their operation.

This section shows the signatures of the main methods in each class and interface. Examples for some of these classes (MessageDigest, Signature, KeyPairGenerator, SecureRandom, KeyFactory, and key specification classes) are supplied in the corresponding Examples sections.

The complete reference documentation for the relevant Security API packages can be found in the package summaries:
  • java.security
  • javax.crypto
  • java.security.cert
  • java.security.spec
  • javax.crypto.spec
  • java.security.interfaces
  • javax.crypto.interfaces

The Provider Class

The term "Cryptographic Service Provider" (used interchangeably with "provider" in this document) refers to a package or set of packages that supply a concrete implementation of a subset of the JDK Security API cryptography features. The Provider class is the interface to such a package or set of packages. It has methods for accessing the provider name, version number, and other information. Please note that in addition to registering implementations of cryptographic services, the Provider class can also be used to register implementations of other security services that might get defined as part of the JDK Security API or one of its extensions.

To supply implementations of cryptographic services, an entity (e.g., a development group) writes the implementation code and creates a subclass of the Provider class. The constructor of the Provider subclass sets the values of various properties; the JDK Security API uses these values to look up the services that the provider implements. In other words, the subclass specifies the names of the classes implementing the services.

">

There are several types of services that can be implemented by provider packages; for more information, see Engine Classes and Algorithms.

The different implementations may have different characteristics. Some may be software-based, while others may be hardware-based. Some may be platform-independent, while others may be platform-specific. Some provider source code may be available for review and evaluation, while some may not. The JCA lets both end-users and developers decide what their needs are.

In this section we explain how end-users install the cryptography implementations that fit their needs, and how developers request the implementations that fit theirs.

NOTE: For information about implementing a provider, see the guide How To Implement a Provider for the Java Cryptography Architecture.

How Provider Implementations Are Requested and Supplied

For each engine class in the API, a implementation instance is requested and instantiated by calling one of the getInstance methods on the engine class, specifying the name of the desired algorithm and, optionally, the name of the provider (or the Provider class) whose implementation is desired.
static EngineClassName getInstance(String algorithm)
    throws NoSuchAlgorithmException

static EngineClassName getInstance(String algorithm, String provider)
    throws NoSuchAlgorithmException, NoSuchProviderException

static EngineClassName getInstance(String algorithm, Provider provider)
    throws NoSuchAlgorithmException
where EngineClassName is the desired engine type (MessageDigest/Cipher/etc). For example:
    MessageDigest md = MessageDigest.getInstance("MD5");
    KeyAgreement ka = KeyAgreement.getInstance("DH", "SunJCE");
return an instance of the "MD5" MessageDigest and "DH" KeyAgreement objects, respectively.

Appendix A contains the list of names that have been standardized for use with the Java environment. Some providers may choose to also include alias names that also refer to the same algorithm. For example, the "SHA-1" algorithm might be referred to as "SHA1". Applications should use standard names instead of an alias, as not all providers may alias algorithm names in the same way.

NOTE: The algorithm name is not case-sensitive. For example, all the following calls are equivalent:
MessageDigest.getInstance("SHA-1")
MessageDigest.getInstance("sha-1")
MessageDigest.getInstance("sHa-1")

If no provider is specified, getInstance searches the registered providers for an implementation of the requested cryptographic service associated with the named algorithm. In any given Java Virtual Machine (JVM), providers are installed in a given preference order, the order in which the provider list is searched if a specific provider is not requested. For example, suppose there are two providers installed in a JVM, PROVIDER_1 and PROVIDER_2. Assume that:

  • PROVIDER_1 implements SHA1withDSA, SHA-1, MD5, DES, and DES3.
    PROVIDER_1 has preference order 1 (the highest priority).

  • PROVIDER_2 implements SHA1withDSA, MD5withRSA, MD2withRSA, MD2, MD5, RC4, RC5, DES, and RSA.
    PROVIDER_2 has preference order 2.
Now let's look at three scenarios:
  1. If we are looking for an MD5 implementation. Both providers supply such an implementation. The PROVIDER_1 implementation is returned since PROVIDER_1 has the highest priority and is searched first.
  2. If we are looking for an MD5withRSA signature algorithm, PROVIDER_1 is first searched for it. No implementation is found, so PROVIDER_2 is searched. Since an implementation is found, it is returned.
  3. Suppose we are looking for a SHA1withRSA signature algorithm. Since no installed provider implements it, a NoSuchAlgorithmException is thrown.

The getInstance methods that include a provider argument are for developers who want to specify which provider they want an algorithm from. A federal agency, for example, will want to use a provider implementation that has received federal certification. Let's assume that the SHA1withDSA implementation from PROVIDER_1 has not received such certification, while the DSA implementation of PROVIDER_2 has received it.

A federal agency program would then have the following call, specifying PROVIDER_2 since it has the certified implementation:

Signature dsa = Signature.getInstance("SHA1withDSA", "PROVIDER_2");

In this case, if PROVIDER_2 was not installed, a NoSuchProviderException would be thrown, even if another installed provider implements the algorithm requested.

A program also has the option of getting a list of all the installed providers (using the getProviders method in the Security class) and choosing one from the list.

NOTE: General purpose applications SHOULD NOT request cryptographic services from specific providers. Otherwise, applications are tied to specific providers which may not be available on other Java implementations. They also might not be able to take advantage of available optimized providers (for example hardware accelerators via PKCS11 or native OS implementations such as Microsoft's MSCAPI) that have a higher preference order than the specific requested provider.

Installing Providers

In order to be used, a cryptographic provider must first be installed, then registered either statically or dynamically. There are a variety of Sun providers shipped with this release (SUN, SunJCE, SunJSSE, SunRsaSign, etc.) that are already installed and registered. The following sections describe how to install and register additional providers.

Installing the Provider Classes

There are two possible ways to install the provider classes:

  1. On the normal Java classpath

    Place a zip or JAR file containing the classes anywhere in your classpath. Some algorithms types (Ciphers) require the provider be a signed Jar file.

  2. As an Installed/Bundled Extension

    The provider will be considered an installed extension if it is placed in the standard extension directory. In Sun's JDK, that would be located in:

        <java-home>/lib/ext                   [Unix]
    <java-home>\lib\ext                   [Windows]
    Here <java-home> refers to the directory where the runtime software is installed, which is the top-level directory of the JavaTM Runtime Environment (JRE) or the jre directory in the JavaTM JDK software. For example, if you have JDK 6 installed on Solaris in a directory named /home/user1/JDK1.6.0, or on Microsoft Windows in a directory named C:\Java\JDK1.6.0, then you need to install the JAR file in the following directory:

        /home/user1/JDK1.6.0/jre/lib/ext      [Unix]
    C:\JDK1.6.0\jre\lib\ext               [Windows]

    Similarly, if you have the JRE 6 installed on Solaris in a directory named /home/user1/jre1.6.0, or on Microsoft Windows in a directory named C:\jre1.6.0, you need to install the JAR file in the following directory:

          /home/user1/jre1.6.0/lib/ext          [Unix]
      C:\jre1.6.0\lib\ext                   [Windows]
    For more information on how to deploy an extension, see How is an extension deployed?

Registering the Provider

The next step is to add the provider to your list of registered providers. Providers can be registered statically by editing a security properties configuration file before running a Java application, or dynamically by calling a method at runtime. To prevent the installation of rogue providers being added to the runtime environment, applications attempting to dynamically register a provider must possess the appropriate runtime privilege.

Static Registration
The configuration file is located in the following location:

    <java-home>/lib/security/java.security     [Unix]
    <java-home>\lib\security\java.security     [Windows]
For each registered provider, this file should have a statement of the following form:

    security.provider.n=masterClassName

This declares a provider, and specifies its preference order n. The preference order is the order in which providers are searched for requested algorithms (when no specific provider is requested). The order is 1-based: 1 is the most preferred, followed by 2, and so on.

masterClassName must specify the fully qualified name of provider's master class. The provider's documentation will specify its master class. This class is always a subclass of the Provider class. The subclass constructor sets the values of various properties that are required for the Java Cryptography API to look up the algorithms or other facilities the provider implements.

The JDK comes standard with automatically installed and configured providers such as "SUN" and "SunJCE". The "SUN" provider's master class is the SUN class in the sun.security.provider package, and the corresponding java.security file entry is as follows:

    security.provider.5=sun.security.provider.Sun

To utilize another JCA provider, add a line referencing the alternate provider, specify the preference order ( making corresponding adjustments to the other providers' orders, if needed).

Suppose that the master class of CompanyX's provider is com.companyx.provider.ProviderX, and that you would like to configure this provider as the eighth most-preferred. To do so, you would add the following line to the java.security file:

    security.provider.8=com.companyx.provider.ProviderX
Dynamic Registration
To register providers dynamically, applications call either the addProvider or insertProviderAt method in the Security class. This type of registration is not persistent across VM instances, and can only be done by "trusted" programs with the appropriate privilege. See Security.

Setting Provider Permissions

Whenever encryption providers are used (that is, those that supply implementations of Cipher, KeyAgreement, KeyGenerator, Mac, or SecretKeyFactory), and the provider is not an installed extension Permissions may need to be granted for when applets or applications using JCA are run while a security manager is installed. There is typically a security manager installed whenever an applet is running, and a security manager may be installed for an application either via code in the application itself or via a command-line argument. Permissions do not need to be granted to installed extensions, since the default system policy configuration file grants all permissions to installed extensions (that is, installed in the extensions directory).

The documentation from the vendor of each provider you will be using should include information as to which permissions it requires, and how to grant such permissions. For example, the following permissions may be needed by a provider if it is not an installed extension and a security manager is installed:

  • java.lang.RuntimePermission "getProtectionDomain" to get class protection domains. The provider may need to get its own protection domain in the process of doing self-integrity checking.

  • java.security.SecurityPermission "putProviderProperty.{name}" to set provider properties, where {name} is replaced by the actual provider name.

For example, a sample statement granting permissions to a provider whose name is "MyJCE" and whose code is in myjce_provider.jar appears below. Such a statement could appear in a policy file. In this example, the myjce_provider.jar file is assumed to be in the /localWork directory.

    grant codeBase "file:/localWork/myjce_provider.jar" {
    permission java.lang.RuntimePermission "getProtectionDomain";
    permission java.security.SecurityPermission
        "putProviderProperty.MyJCE";
     };

Provider Class Methods

Each Provider class instance has a (currently case-sensitive) name, a version number, and a string description of the provider and its services. You can query the Provider instance for this information by calling the following methods:

public String getName()
public double getVersion()
public String getInfo()

The Security Class

The Security class manages installed providers and security-wide properties. It only contains static methods and is never instantiated. The methods for adding or removing providers, and for setting Security properties, can only be executed by a trusted program. Currently, a "trusted program" is either

  • a local application not running under a security manager, or

  • an applet or application with permission to execute the specified method (see below).
The determination that code is considered trusted to perform an attempted action (such as adding a provider) requires that the applet is granted the proper permission(s) for that particular action. The policy configuration file(s) for a JDK installation specify what permissions (which types of system resource accesses) are allowed by code from specified code sources. (See below and the "Default Policy Implementation and Policy File Syntax" and "Java Security Architecture Specification" files for more information.)

Code being executed is always considered to come from a particular "code source". The code source includes not only the location (URL) where the code originated from, but also a reference to any public key(s) corresponding to the private key(s) that may have been used to sign the code. Public keys in a code source are referenced by (symbolic) alias names from the user's keystore.

In a policy configuration file, a code source is represented by two components: a code base (URL), and an alias name (preceded by signedBy), where the alias name identifies the keystore entry containing the public key that must be used to verify the code's signature.

Each "grant" statement in such a file grants a specified code source a set of permissions, specifying which actions are allowed.

Here is a sample policy configuration file:

grant codeBase "file:/home/sysadmin/", signedBy "sysadmin" {
    permission java.security.SecurityPermission "insertProvider.*";
    permission java.security.SecurityPermission "removeProvider.*";
    permission java.security.SecurityPermission "putProviderProperty.*";
};
This configuration file specifies that code loaded from a signed JAR file from beneath the /home/sysadmin/ directory on the local file system can add or remove providers or set provider properties. (Note that the signature of the JAR file can be verified using the public key referenced by the alias name sysadmin in the user's keystore.)

Either component of the code source (or both) may be missing. Here's an example of a configuration file where the codeBase is omitted:

grant signedBy "sysadmin" {
    permission java.security.SecurityPermission "insertProvider.*";
    permission java.security.SecurityPermission "removeProvider.*";
};
If this policy is in effect, code that comes in a JAR File signed by sysadmin can add/remove providers--regardless of where the JAR File originated.

Here's an example without a signer:

grant codeBase "file:/home/sysadmin/" {
    permission java.security.SecurityPermission "insertProvider.*";
    permission java.security.SecurityPermission "removeProvider.*";
};
In this case, code that comes from anywhere within the /home/sysadmin/ directory on the local filesystem can add/remove providers. The code does not need to be signed.

An example where neither codeBase nor signedBy is included is:

grant {
    permission java.security.SecurityPermission "insertProvider.*";
    permission java.security.SecurityPermission "removeProvider.*";
};
Here, with both code source components missing, any code (regardless of where it originates, or whether or not it is signed, or who signed it) can add/remove providers. Obviously, this is definitely NOT recommended, as this grant could open a security hole. Untrusted code could install a Provider, thus affecting later code that is depending on a properly functioning implementation. (For example, a rogue Cipher object might capture and store the sensitive information it receives.)

Managing Providers

The following tables summarize the methods in the Security class you can use to query which Providers are installed, as well as to install or remove providers at runtime.

Quering Providers
Method | Description
static Provider[] getProviders() | Returns an array containing all the installed providers (technically, the Provider subclass for each package provider). The order of the Providers in the array is their preference order.
static Provider getProvider
(String providerName) 		Returns the Provider named providerName. It returns null if the Provider is not found.

Adding Providers
Method Description
static int
addProvider(Provider provider)
 Adds a Provider to the end of the list of installed Providers. It returns the preference position in which the Provider was added, or -1 if the Provider was not added because it was already installed.
static int insertProviderAt
(Provider provider, int position)

Adds a new Provider at a specified position. If the given provider is installed at the requested position, the provider formerly at that position and all providers with a position greater than position are shifted up one position (towards the end of the list). This method returns the preference position in which the Provider was added, or -1 if the Provider was not added because it was already installed.

Removing Providers
Method | Description
static void removeProvider(String name) | Removes the Provider with the specified name. It returns silently if the provider is not installed. When the specified provider is removed, all providers located at a position greater than where the specified provider was are shifted down one position (towards the head of the list of installed providers).

NOTE: If you want to change the preference position of a provider, you must first remove it, and then insert it back in at the new preference position.

Security Properties

The Security class maintains a list of system-wide security properties. These properties are similar to the System properties, but are security-related. These properties can be set statically or dynamically. We have already seen an example of static security properties (that is, registering a provider statically via the "security.provider.i" security property). If you want to set properties dynamically, trusted programs can use the following methods:

static String getProperty(String key)
static void setProperty(String key, String datum)
Note: the list of security providers is established during VM startup, therefore the methods described above must be used to alter the provider list.

As a reminder, the configuration file is located in the following location:

<java-home>/lib/security/java.security     [Unix]
<java-home>\lib\security\java.security     [Windows]

The SecureRandom Class

The SecureRandom class is an engine class that provides the functionality of a Random Number Generator (RNG). It differs from the Random class in that it produces cryptographically strong random numbers. If there is insufficient randomness in a generator, it makes it much easier to compromise your protection mechanisms. Random numbers are used throughout cryptography, such as generating cryptographic keys or algorithmic parameters.

">

Creating a SecureRandom Object

As with all engine classes, the way to get a SecureRandom object is to call one of the getInstance() static factory methods in the SecureRandom class.

Seeding or Re-Seeding the SecureRandom Object

The SecureRandom implementation attempts to completely randomize the internal state of the generator itself unless the caller follows the call to a getInstance method with a call to one of the setSeed methods:

synchronized public void setSeed(byte[] seed)
public void setSeed(long seed)
Once the SecureRandom object has been seeded, it will produce bits as random as the original seeds.

At any time a SecureRandom object may be re-seeded using one of the setSeed methods. The given seed supplements, rather than replaces, the existing seed; therefore, repeated calls are guaranteed never to reduce randomness.

Using a SecureRandom Object

To get random bytes, a caller simply passes an array of any length, which is then filled with random bytes:

synchronized public void nextBytes(byte[] bytes)

Generating Seed Bytes

If desired, it is possible to invoke the generateSeed method to generate a given number of seed bytes (to seed other random number generators, for example):
byte[] generateSeed(int numBytes)

The MessageDigest Class

The MessageDigest class is an engine class designed to provide the functionality of cryptographically secure message digests such as SHA-1 or MD5. A cryptographically secure message digest takes arbitrary-sized input (a byte array), and generates a fixed-size output, called a digest or hash.

" >

For example, the MD5 algorithm produces a 16 byte digest, and SHA1's is 20 bytes.

A digest has two properties:

  • It should be computationally infeasible to find two messages that hash to the same value.

  • The digest should not reveal anything about the input that was used to generate it.

Message digests are used to produce unique and reliable identifiers of data. They are sometimes called "checksums" or the "digital fingerprints" of the data. Changes to just one bit of the message should produce a different digest value.

Message digests have many uses and can determine when data has been modified, intentionally or not. Recently, there has been considerable effort to determine if there are any weaknesses in popular algorithms, with mixed results. When selecting a digest algorithm, one should always consult a recent reference to determine its status and appropriateness for the task at hand.

Creating a MessageDigest Object

The first step for computing a digest is to create a message digest instance. MessageDigest objects are obtained by using one of the getInstance() static factory methods in the MessageDigest class. The factory method returns an initialized message digest object. It thus does not need further initialization.

Updating a Message Digest Object

The next step for calculating the digest of some data is to supply the data to the initialized message digest object. It can be provided all at once, or in chunks. Pieces can be fed to the message digest by calling one of the update methods:

void update(byte input)
void update(byte[] input)
void update(byte[] input, int offset, int len)

Computing the Digest

After the data chunks have been supplied by calls to update, the digest is computed using a call to one of the digest methods:

byte[] digest()
byte[] digest(byte[] input)
int digest(byte[] buf, int offset, int len)

The first method return the computed digest. The second method does a final update(input) with the input byte array before calling digest(), which returns the digest byte array. The last method stores the computed digest in the provided buffer buf, starting at offset. len is the number of bytes in buf allotted for the digest, the method returns the number of bytes actually stored in buf. If there is not enough room in the buffer, the method will throw an exception.

Please see the Computing a MessageDigest example in the Code Examples section for more details.

The Signature Class

The Signature class is an engine class designed to provide the functionality of a cryptographic digital signature algorithm such as DSA or RSAwithMD5. A cryptographically secure signature algorithm takes arbitrary-sized input and a private key and generates a relatively short (often fixed-size) string of bytes, called the signature, with the following properties:
  • Only the owner of a private/public key pair is able to create a signature. It should be computationally infeasible for anyone having a public key to recover the private key.
  • Given the public key corresponding to the private key used to generate the signature, it should be possible to verify the authenticity and integrity of the input.

  • The signature and the public key do not reveal anything about the private key.
It can also be used to verify whether or not an alleged signature is in fact the authentic signature of the data associated with it.

">

A Signature object is initialized for signing with a Private Key and is given the data to be signed. The resulting signature bytes are typically kept with the signed data. When verification is needed, another Signature object is created and initialized for verification and given the corresponding Public Key. The data and the signature bytes are fed to the signature object, and if the data and signature match, the Signature object reports success.

Even though a signature seems similar to a message digest, they have very different purposes in the type of protection they provide. In fact, algorithms such as "SHA1WithRSA" use the message digest "SHA1" to initially "compress" the large data sets into a more manageable form, then sign the resulting 20 byte message digest with the "RSA" algorithm.

Please see the Examples section for an example of signing and verifying data.

Signature Object States

Signature objects are modal objects. This means that a Signature object is always in a given state, where it may only do one type of operation. States are represented as final integer constants defined in their respective classes.

The three states a Signature object may have are:

  • UNINITIALIZED
  • SIGN
  • VERIFY
When it is first created, a Signature object is in the UNINITIALIZED state. The Signature class defines two initialization methods, initSign and initVerify, which change the state to SIGN and VERIFY, respectively.

Creating a Signature Object

The first step for signing or verifying a signature is to create a Signature instance. Signature objects are obtained by using one of the Signature getInstance() static factory methods.

Initializing a Signature Object

A Signature object must be initialized before it is used. The initialization method depends on whether the object is going to be used for signing or for verification.

If it is going to be used for signing, the object must first be initialized with the private key of the entity whose signature is going to be generated. This initialization is done by calling the method:

final void initSign(PrivateKey privateKey)
This method puts the Signature object in the SIGN state.

If instead the Signature object is going to be used for verification, it must first be initialized with the public key of the entity whose signature is going to be verified. This initialization is done by calling either of these methods:

    final void initVerify(PublicKey publicKey)

    final void initVerify(Certificate certificate)

This method puts the Signature object in the VERIFY state.

Signing

If the Signature object has been initialized for signing (if it is in the SIGN state), the data to be signed can then be supplied to the object. This is done by making one or more calls to one of the update methods:

final void update(byte b)
final void update(byte[] data)
final void update(byte[] data, int off, int len)

Calls to the update method(s) should be made until all the data to be signed has been supplied to the Signature object.

To generate the signature, simply call one of the sign methods:

final byte[] sign()
final int sign(byte[] outbuf, int offset, int len)

The first method returns the signature result in a byte array. The second stores the signature result in the provided buffer outbuf, starting at offset. len is the number of bytes in outbuf allotted for the signature. The method returns the number of bytes actually stored.

Signature encoding is algorithm specific. See the Standard Names document for more information about the use of ASN.1 encoding in the Java Cryptography Architecture.

A call to a sign method resets the signature object to the state it was in when previously initialized for signing via a call to initSign. That is, the object is reset and available to generate another signature with the same private key, if desired, via new calls to update and sign.

Alternatively, a new call can be made to initSign specifying a different private key, or to initVerify (to initialize the Signature object to verify a signature).

Verifying

If the Signature object has been initialized for verification (if it is in the VERIFY state), it can then verify if an alleged signature is in fact the authentic signature of the data associated with it. To start the process, the data to be verified (as opposed to the signature itself) is supplied to the object. The data is passed to the object by calling one of the update methods:

final void update(byte b)
final void update(byte[] data)
final void update(byte[] data, int off, int len)

Calls to the update method(s) should be made until all the data to be verified has been supplied to the Signature object. The signature can now be verified by calling one of the verify methods:

final boolean verify(byte[] signature)

final boolean verify(byte[] signature, int offset, int length)

The argument must be a byte array containing the signature. The argument must be a byte array containing the signature. This byte array would hold the signature bytes which were returned by a previous call to one of the sign methods.

The verify method returns a boolean indicating whether or not the encoded signature is the authentic signature of the data supplied to the update method(s).

A call to the verify method resets the signature object to its state when it was initialized for verification via a call to initVerify. That is, the object is reset and available to verify another signature from the identity whose public key was specified in the call to initVerify.

Alternatively, a new call can be made to initVerify specifying a different public key (to initialize the Signature object for verifying a signature from a different entity), or to initSign (to initialize the Signature object for generating a signature).

The Cipher Class

The Cipher class provides the functionality of a cryptographic cipher used for encryption and decryption. Encryption is the process of taking data (called cleartext) and a key, and producing data (ciphertext) meaningless to a third-party who does not know the key. Decryption is the inverse process: that of taking ciphertext and a key and producing cleartext.

">

Symmetric vs. Asymmetric Cryptography

There are two major types of encryption: symmetric (also known as secret key), and asymmetric (or public key cryptography). In symmetric cryptography, the same secret key to both encrypt and decrypt the data. Keeping the key private is critical to keeping the data confidential. On the other hand, asymmetric cryptography uses a public/private key pair to encrypt data. Data encrypted with one key is decrypted with the other. A user first generates a public/private key pair, and then publishes the public key in a trusted database that anyone can access. A user who wishes to communicate securely with that user encrypts the data using the retrieved public key. Only the holder of the private key will be able to decrypt. Keeping the private key confidential is critical to this scheme.

Asymmetric algorithms (such as RSA) are generally much slower than symmetric ones. These algorithms are not designed for efficiently protecting large amounts of data. In practice, asymmetric algorithms are used to exchange smaller secret keys which are used to initialize symmetric algorithms.

Stream vs. Block Ciphers

There are two major types of ciphers: block and stream. Block ciphers process entire blocks at a time, usually many bytes in length. If there is not enough data to make a complete input block, the data must be padded: that is, before encryption, dummy bytes must be added to make a multiple of the cipher's block size. These bytes are then stripped off during the decryption phase. The padding can either be done by the application, or by initializing a cipher to use a padding type such as "PKCS5PADDING". In contrast, stream ciphers process incoming data one small unit (typically a byte or even a bit) at a time. This allows for ciphers to process an arbitrary amount of data without padding.

Modes Of Operation

When encrypting using a simple block cipher, two identical blocks of plaintext will always produce an identical block of cipher text. Cryptanalysts trying to break the ciphertext will have an easier job if they note blocks of repeating text. In order to add more complexity to the text, feedback modes use the previous block of output to alter the input blocks before applying the encryption algorithm. The first block will need an initial value, and this value is called the initialization vector (IV). Since the IV simply alters the data before any encryption, the IV should be random but does not necessarily need to be kept secret. There are a variety of modes, such as CBC (Cipher Block Chaining), CFB (Cipher Feedback Mode), and OFB (Output Feedback Mode). ECB (Electronic Cookbook Mode) is a mode with no feedback.

Some algorithms such as AES and RSA allow for keys of different lengths, but others are fixed, such as DES and 3DES. Encryption using a longer key generally implies a stronger resistance to message recovery. As usual, there is a trade off between security and time, so choose the key length appropriately.

Most algorithms use binary keys. Most humans do not have the ability to remember long sequences of binary numbers, even when represented in hexadecimal. Character passwords are much easier to recall. Because character passwords are generally chosen from a small number of characters (for example, [a-zA-Z0-9]), protocols such as "Password-Based Encryption" (PBE) have been defined which take character passwords and generate strong binary keys. In order to make the task of getting from password to key very time-consuming for an attacker (via so-called "dictionary attacks" where common dictionary word->value mappings are precomputed), most PBE implementations will mix in a random number, known as a salt, to increase the key randomness.

Creating a Cipher Object

Cipher objects are obtained by using one of the Cipher getInstance() static factory methods. Here, the algorithm name is slightly different than with other engine classes, in that it specifies not just an algorithm name, but a "transformation". A transformation is a string that describes the operation (or set of operations) to be performed on the given input to produce some output. A transformation always includes the name of a cryptographic algorithm (e.g., DES), and may be followed by a mode and padding scheme.

A transformation is of the form:

  • "algorithm/mode/padding" or
  • "algorithm"

For example, the following are valid transformations:

    "DES/CBC/PKCS5Padding"

    "DES"

If just a transformation name is specified, the system will determine if there is an implementation of the requested transformation available in the environment, and if there is more than one, returns there is a preferred one.

If both a transformation name and a package provider are specified, the system will determine if there is an implementation of the requested transformation in the package requested, and throw an exception if there is not.

If no mode or padding is specified, provider-specific default values for the mode and padding scheme are used. For example, the SunJCE provider uses ECB as the default mode, and PKCS5Padding as the default padding scheme for DES, DES-EDE and Blowfish ciphers. This means that in the case of the SunJCE provider:

    Cipher c1 = Cipher.getInstance("DES/ECB/PKCS5Padding");
and
    Cipher c1 = Cipher.getInstance("DES");
are equivalent statements.

Using modes such as CFB and OFB, block ciphers can encrypt data in units smaller than the cipher's actual block size. When requesting such a mode, you may optionally specify the number of bits to be processed at a time by appending this number to the mode name as shown in the "DES/CFB8/NoPadding" and "DES/OFB32/PKCS5Padding" transformations. If no such number is specified, a provider-specific default is used. (For example, the SunJCE provider uses a default of 64 bits for DES.) Thus, block ciphers can be turned into byte-oriented stream ciphers by using an 8 bit mode such as CFB8 or OFB8.

Appendix A of this document contains a list of standard names that can be used to specify the algorithm name, mode, and padding scheme components of a transformation.

The objects returned by factory methods are uninitialized, and must be initialized before they become usable.

Initializing a Cipher Object

A Cipher object obtained via getInstance must be initialized for one of four modes, which are defined as final integer constants in the Cipher class. The modes can be referenced by their symbolic names, which are shown below along with a description of the purpose of each mode:

ENCRYPT_MODE
Encryption of data.
DECRYPT_MODE
Decryption of data.
WRAP_MODE
Wrapping a java.security.Key into bytes so that the key can be securely transported.
UNWRAP_MODE
Unwrapping of a previously wrapped key into a java.security.Key object.

Each of the Cipher initialization methods takes an operational mode parameter (opmode), and initializes the Cipher object for that mode. Other parameters include the key (key) or certificate containing the key (certificate), algorithm parameters (params), and a source of randomness (random).

To initialize a Cipher object, call one of the following init methods:

    public void init(int opmode, Key key);

    public void init(int opmode, Certificate certificate);

    public void init(int opmode, Key key, SecureRandom random);

    public void init(int opmode, Certificate certificate,
             SecureRandom random);

    public void init(int opmode, Key key,
             AlgorithmParameterSpec params);

    public void init(int opmode, Key key,
             AlgorithmParameterSpec params, SecureRandom random);

    public void init(int opmode, Key key,
                     AlgorithmParameters params);

    public void init(int opmode, Key key,
                     AlgorithmParameters params, SecureRandom random);

If a Cipher object that requires parameters (e.g., an initialization vector) is initialized for encryption, and no parameters are supplied to the init method, the underlying cipher implementation is supposed to supply the required parameters itself, either by generating random parameters or by using a default, provider-specific set of parameters.

However, if a Cipher object that requires parameters is initialized for decryption, and no parameters are supplied to the init method, an InvalidKeyException or InvalidAlgorithmParameterException exception will be raised, depending on the init method that has been used.

See the section about Managing Algorithm Parameters for more details.

The same parameters that were used for encryption must be used for decryption.

Note that when a Cipher object is initialized, it loses all previously-acquired state. In other words, initializing a Cipher is equivalent to creating a new instance of that Cipher, and initializing it. For example, if a Cipher is first initialized for decryption with a given key, and then initialized for encryption, it will lose any state acquired while in decryption mode.

Encrypting and Decrypting Data

Data can be encrypted or decrypted in one step (single-part operation) or in multiple steps (multiple-part operation). A multiple-part operation is useful if you do not know in advance how long the data is going to be, or if the data is too long to be stored in memory all at once.

To encrypt or decrypt data in a single step, call one of the doFinal methods:

    public byte[] doFinal(byte[] input);

    public byte[] doFinal(byte[] input, int inputOffset, int inputLen);

    public int doFinal(byte[] input, int inputOffset,
               int inputLen, byte[] output);

    public int doFinal(byte[] input, int inputOffset,
               int inputLen, byte[] output, int outputOffset)

To encrypt or decrypt data in multiple steps, call one of the update methods:

    public byte[] update(byte[] input);

    public byte[] update(byte[] input, int inputOffset, int inputLen);

    public int update(byte[] input, int inputOffset, int inputLen,
              byte[] output);

    public int update(byte[] input, int inputOffset, int inputLen,
              byte[] output, int outputOffset)

A multiple-part operation must be terminated by one of the above doFinal methods (if there is still some input data left for the last step), or by one of the following doFinal methods (if there is no input data left for the last step):

    public byte[] doFinal();

    public int doFinal(byte[] output, int outputOffset);

All the doFinal methods take care of any necessary padding (or unpadding), if padding (or unpadding) has been requested as part of the specified transformation.

A call to doFinal resets the Cipher object to the state it was in when initialized via a call to init. That is, the Cipher object is reset and available to encrypt or decrypt (depending on the operation mode that was specified in the call to init) more data.

Wrapping and Unwrapping Keys

Wrapping a key enables secure transfer of the key from one place to another.

The wrap/unwrap API makes it more convenient to write code since it works with key objects directly. These methods also enable the possibility of secure transfer of hardware-based keys.

To wrap a Key, first initialize the Cipher object for WRAP_MODE, and then call the following:

    public final byte[] wrap(Key key);

If you are supplying the wrapped key bytes (the result of calling wrap) to someone else who will unwrap them, be sure to also send additional information the recipient will need in order to do the unwrap:

  1. the name of the key algorithm, and

  2. the type of the wrapped key (one of Cipher.SECRET_KEY, Cipher.PRIVATE_KEY, or Cipher.PUBLIC_KEY).

The key algorithm name can be determined by calling the getAlgorithm method from the Key interface:

    public String getAlgorithm();

To unwrap the bytes returned by a previous call to wrap, first initialize a Cipher object for UNWRAP_MODE, then call the following:

    public final Key unwrap(byte[] wrappedKey,
                String wrappedKeyAlgorithm,
                int wrappedKeyType));

Here, wrappedKey is the bytes returned from the previous call to wrap, wrappedKeyAlgorithm is the algorithm associated with the wrapped key, and wrappedKeyType is the type of the wrapped key. This must be one of Cipher.SECRET_KEY, Cipher.PRIVATE_KEY, or Cipher.PUBLIC_KEY.

Managing Algorithm Parameters

The parameters being used by the underlying Cipher implementation, which were either explicitly passed to the init method by the application or generated by the underlying implementation itself, can be retrieved from the Cipher object by calling its getParameters method, which returns the parameters as a java.security.AlgorithmParameters object (or null if no parameters are being used). If the parameter is an initialization vector (IV), it can also be retrieved by calling the getIV method.

In the following example, a Cipher object implementing password-based encryption (PBE) is initialized with just a key and no parameters. However, the selected algorithm for password-based encryption requires two parameters - a salt and an iteration count. Those will be generated by the underlying algorithm implementation itself. The application can retrieve the generated parameters from the Cipher object as follows:

    import javax.crypto.*;
    import java.security.AlgorithmParameters;

    // get cipher object for password-based encryption
    Cipher c = Cipher.getInstance("PBEWithMD5AndDES");

    // initialize cipher for encryption, without supplying
    // any parameters. Here, "myKey" is assumed to refer
    // to an already-generated key.
    c.init(Cipher.ENCRYPT_MODE, myKey);

    // encrypt some data and store away ciphertext
    // for later decryption
    byte[] cipherText = c.doFinal("This is just an example".getBytes());

    // retrieve parameters generated by underlying cipher
    // implementation
    AlgorithmParameters algParams = c.getParameters();

    // get parameter encoding and store it away
    byte[] encodedAlgParams = algParams.getEncoded();

The same parameters that were used for encryption must be used for decryption. They can be instantiated from their encoding and used to initialize the corresponding Cipher object for decryption, as follows:

    import javax.crypto.*;
    import java.security.AlgorithmParameters;

    // get parameter object for password-based encryption
    AlgorithmParameters algParams;
    algParams = AlgorithmParameters.getInstance("PBEWithMD5AndDES");

    // initialize with parameter encoding from above
    algParams.init(encodedAlgParams);

    // get cipher object for password-based encryption
    Cipher c = Cipher.getInstance("PBEWithMD5AndDES");

    // initialize cipher for decryption, using one of the
    // init() methods that takes an AlgorithmParameters
    // object, and pass it the algParams object from above
    c.init(Cipher.DECRYPT_MODE, myKey, algParams);

If you did not specify any parameters when you initialized a Cipher object, and you are not sure whether or not the underlying implementation uses any parameters, you can find out by simply calling the getParameters method of your Cipher object and checking the value returned. A return value of null indicates that no parameters were used.

The following cipher algorithms implemented by the SunJCE provider use parameters:

  • DES, DES-EDE, and Blowfish, when used in feedback (i.e., CBC, CFB, OFB, or PCBC) mode, use an initialization vector (IV). The javax.crypto.spec.IvParameterSpec class can be used to initialize a Cipher object with a given IV.

  • PBEWithMD5AndDES uses a set of parameters, comprising a salt and an iteration count. The javax.crypto.spec.PBEParameterSpec class can be used to initialize a Cipher object implementing PBEWithMD5AndDES with a given salt and iteration count.

Note that you do not have to worry about storing or transferring any algorithm parameters for use by the decryption operation if you use the SealedObject class. This class attaches the parameters used for sealing (encryption) to the encrypted object contents, and uses the same parameters for unsealing (decryption).

Cipher Output Considerations

Some of the update and doFinal methods of Cipher allow the caller to specify the output buffer into which to encrypt or decrypt the data. In these cases, it is important to pass a buffer that is large enough to hold the result of the encryption or decryption operation.

The following method in Cipher can be used to determine how big the output buffer should be:

    public int getOutputSize(int inputLen)

Other Cipher-based Classes

There are some helper classes which interally use Ciphers to provide easy access to common cipher uses.

The Cipher Stream Classes

A simple, secure, stream-based communication object can be created by combining existing InputStream/OutputStreams with Cipher objects.

The CipherInputStream Class

This class is a FilterInputStream that encrypts or decrypts the data passing through it. It is composed of an InputStream, or one of its subclasses, and a Cipher. CipherInputStream represents a secure input stream into which a Cipher object has been interposed. The read methods of CipherInputStream return data that are read from the underlying InputStream but have additionally been processed by the embedded Cipher object. The Cipher object must be fully initialized before being used by a CipherInputStream.

For example, if the embedded Cipher has been initialized for decryption, the CipherInputStream will attempt to decrypt the data it reads from the underlying InputStream before returning them to the application.

This class adheres strictly to the semantics, especially the failure semantics, of its ancestor classes java.io.FilterInputStream and java.io.InputStream. This class has exactly those methods specified in its ancestor classes, and overrides them all, so that the data are additionally processed by the embedded cipher. Moreover, this class catches all exceptions that are not thrown by its ancestor classes. In particular, the skip(long) method skips only data that has been processed by the Cipher.

It is crucial for a programmer using this class not to use methods that are not defined or overridden in this class (such as a new method or constructor that is later added to one of the super classes), because the design and implementation of those methods are unlikely to have considered security impact with regard to CipherInputStream.

As an example of its usage, suppose cipher1 has been initialized for encryption. The code below demonstrates how to use a CipherInputStream containing that cipher and a FileInputStream in order to encrypt input stream data:

    FileInputStream fis;
    FileOutputStream fos;
    CipherInputStream cis;

    fis = new FileInputStream("/tmp/a.txt");
    cis = new CipherInputStream(fis, cipher1);
    fos = new FileOutputStream("/tmp/b.txt");
    byte[] b = new byte[8];
    int i = cis.read(b);
    while (i != -1) {
    fos.write(b, 0, i);
    i = cis.read(b);
    }
    fos.close();

The above program reads and encrypts the content from the file /tmp/a.txt and then stores the result (the encrypted bytes) in /tmp/b.txt.

The following example demonstrates how to easily connect several instances of CipherInputStream and FileInputStream. In this example, assume that cipher1 and cipher2 have been initialized for encryption and decryption (with corresponding keys), respectively.

    FileInputStream fis;
    FileOutputStream fos;
    CipherInputStream cis1, cis2;

    fis = new FileInputStream("/tmp/a.txt");
    cis1 = new CipherInputStream(fis, cipher1);
    cis2 = new CipherInputStream(cis1, cipher2);
    fos = new FileOutputStream("/tmp/b.txt");
    byte[] b = new byte[8];
    int i = cis2.read(b);
    while (i != -1) {
    fos.write(b, 0, i);
    i = cis2.read(b);
    }
    fos.close();

The above program copies the content from file /tmp/a.txt to /tmp/b.txt, except that the content is first encrypted and then decrypted back when it is read from /tmp/a.txt. Of course since this program simply encrypts text and decrypts it back right away, it's actually not very useful except as a simple way of illustrating chaining of CipherInputStreams.

Note that the read methods of the CipherInputStream will block until data is returned from the underlying cipher. If a block cipher is used, a full block of cipher text will have to be obtained from the underlying InputStream.

The CipherOutputStream Class

This class is a FilterOutputStream that encrypts or decrypts the data passing through it. It is composed of an OutputStream, or one of its subclasses, and a Cipher. CipherOutputStream represents a secure output stream into which a Cipher object has been interposed. The write methods of CipherOutputStream first process the data with the embedded Cipher object before writing them out to the underlying OutputStream. The Cipher object must be fully initialized before being used by a CipherOutputStream.

For example, if the embedded Cipher has been initialized for encryption, the CipherOutputStream will encrypt its data, before writing them out to the underlying output stream.

This class adheres strictly to the semantics, especially the failure semantics, of its ancestor classes java.io.OutputStream and java.io.FilterOutputStream. This class has exactly those methods specified in its ancestor classes, and overrides them all, so that all data are additionally processed by the embedded cipher. Moreover, this class catches all exceptions that are not thrown by its ancestor classes.

It is crucial for a programmer using this class not to use methods that are not defined or overridden in this class (such as a new method or constructor that is later added to one of the super classes), because the design and implementation of those methods are unlikely to have considered security impact with regard to CipherOutputStream.

As an example of its usage, suppose cipher1 has been initialized for encryption. The code below demonstrates how to use a CipherOutputStream containing that cipher and a FileOutputStream in order to encrypt data to be written to an output stream:

    FileInputStream fis;
    FileOutputStream fos;
    CipherOutputStream cos;

    fis = new FileInputStream("/tmp/a.txt");
    fos = new FileOutputStream("/tmp/b.txt");
    cos = new CipherOutputStream(fos, cipher1);
    byte[] b = new byte[8];
    int i = fis.read(b);
    while (i != -1) {
    cos.write(b, 0, i);
    i = fis.read(b);
    }
    cos.flush();

The above program reads the content from the file /tmp/a.txt, then encrypts and stores the result (the encrypted bytes) in /tmp/b.txt.

The following example demonstrates how to easily connect several instances of CipherOutputStream and FileOutputStream. In this example, assume that cipher1 and cipher2 have been initialized for decryption and encryption (with corresponding keys), respectively:

    FileInputStream fis;
    FileOutputStream fos;
    CipherOutputStream cos1, cos2;

    fis = new FileInputStream("/tmp/a.txt");
    fos = new FileOutputStream("/tmp/b.txt");
    cos1 = new CipherOutputStream(fos, cipher1);
    cos2 = new CipherOutputStream(cos1, cipher2);
    byte[] b = new byte[8];
    int i = fis.read(b);
    while (i != -1) {
    cos2.write(b, 0, i);
    i = fis.read(b);
    }
    cos2.flush();

The above program copies the content from file /tmp/a.txt to /tmp/b.txt, except that the content is first encrypted and then decrypted back before it is written to /tmp/b.txt.

One thing to keep in mind when using block cipher algorithms is that a full block of plaintext data must be given to the CipherOutputStream before the data will be encrypted and sent to the underlying output stream.

There is one other important difference between the flush and close methods of this class, which becomes even more relevant if the encapsulated Cipher object implements a block cipher algorithm with padding turned on:

  • flush flushes the underlying OutputStream by forcing any buffered output bytes that have already been processed by the encapsulated Cipher object to be written out. Any bytes buffered by the encapsulated Cipher object and waiting to be processed by it will not be written out.

  • close closes the underlying OutputStream and releases any system resources associated with it. It invokes the doFinal method of the encapsulated Cipher object, causing any bytes buffered by it to be processed and written out to the underlying stream by calling its flush method.

The SealedObject Class

This class enables a programmer to create an object and protect its confidentiality with a cryptographic algorithm.

Given any object that implements the java.io.Serializable interface, one can create a SealedObject that encapsulates the original object, in serialized format (i.e., a "deep copy"), and seals (encrypts) its serialized contents, using a cryptographic algorithm such as DES, to protect its confidentiality. The encrypted content can later be decrypted (with the corresponding algorithm using the correct decryption key) and de-serialized, yielding the original object.

A typical usage is illustrated in the following code segment: In order to seal an object, you create a SealedObject from the object to be sealed and a fully initialized Cipher object that will encrypt the serialized object contents. In this example, the String "This is a secret" is sealed using the DES algorithm. Note that any algorithm parameters that may be used in the sealing operation are stored inside of SealedObject:

    // create Cipher object
    // NOTE: sKey is assumed to refer to an already-generated
    // secret DES key.
    Cipher c = Cipher.getInstance("DES");
    c.init(Cipher.ENCRYPT_MODE, sKey);

    // do the sealing
    SealedObject so = new SealedObject("This is a secret", c);

The original object that was sealed can be recovered in two different ways:

  • by using a Cipher object that has been initialized with the exact same algorithm, key, padding scheme, etc., that were used to seal the object:

        c.init(Cipher.DECRYPT_MODE, sKey);
    try {
    String s = (String)so.getObject(c);
    } catch (Exception e) {
    // do something
    };

    This approach has the advantage that the party who unseals the sealed object does not require knowledge of the decryption key. For example, after one party has initialized the cipher object with the required decryption key, it could hand over the cipher object to another party who then unseals the sealed object.

  • by using the appropriate decryption key (since DES is a symmetric encryption algorithm, we use the same key for sealing and unsealing):

        try {
    String s = (String)so.getObject(sKey);
    } catch (Exception e) {
    // do something
    };

    In this approach, the getObject method creates a cipher object for the appropriate decryption algorithm and initializes it with the given decryption key and the algorithm parameters (if any) that were stored in the sealed object. This approach has the advantage that the party who unseals the object does not need to keep track of the parameters (e.g., the IV) that were used to seal the object.

The Mac Class

Similar to a MessageDigest, a Message Authentication Code (MAC) provides a way to check the integrity of information transmitted over or stored in an unreliable medium, but includes a secret key in the calculation. Only someone with the proper key will be able to verify the received message. Typically, message authentication codes are used between two parties that share a secret key in order to validate information transmitted between these parties.

">

A MAC mechanism that is based on cryptographic hash functions is referred to as HMAC. HMAC can be used with any cryptographic hash function, e.g., MD5 or SHA-1, in combination with a secret shared key.

The Mac class provides the functionality of a Message Authentication Code (MAC). Please refer to the code example.

Creating a Mac Object

Mac objects are obtained by using one of the Mac getInstance() static factory methods.

Initializing a Mac Object

A Mac object is always initialized with a (secret) key and may optionally be initialized with a set of parameters, depending on the underlying MAC algorithm.

To initialize a Mac object, call one of its init methods:

    public void init(Key key);

    public void init(Key key, AlgorithmParameterSpec params);

You can initialize your Mac object with any (secret-)key object that implements the javax.crypto.SecretKey interface. This could be an object returned by javax.crypto.KeyGenerator.generateKey(), or one that is the result of a key agreement protocol, as returned by javax.crypto.KeyAgreement.generateSecret(), or an instance of javax.crypto.spec.SecretKeySpec.

With some MAC algorithms, the (secret-)key algorithm associated with the (secret-)key object used to initialize the Mac object does not matter (this is the case with the HMAC-MD5 and HMAC-SHA1 implementations of the SunJCE provider). With others, however, the (secret-)key algorithm does matter, and an InvalidKeyException is thrown if a (secret-)key object with an inappropriate (secret-)key algorithm is used.

Computing a MAC

A MAC can be computed in one step (single-part operation) or in multiple steps (multiple-part operation). A multiple-part operation is useful if you do not know in advance how long the data is going to be, or if the data is too long to be stored in memory all at once.

To compute the MAC of some data in a single step, call the following doFinal method:

    public byte[] doFinal(byte[] input);

To compute the MAC of some data in multiple steps, call one of the update methods:

    public void update(byte input);

    public void update(byte[] input);

    public void update(byte[] input, int inputOffset, int inputLen);

A multiple-part operation must be terminated by the above doFinal method (if there is still some input data left for the last step), or by one of the following doFinal methods (if there is no input data left for the last step):

    public byte[] doFinal();

    public void doFinal(byte[] output, int outOffset);

Key Interfaces

To this point, we have focused the high-level uses of the JCA without getting lost in the details of what keys are and how they are generated/represented. It is now time to turn our attention to keys.

The java.security.Key interface is the top-level interface for all opaque keys. It defines the functionality shared by all opaque key objects.

An opaque key representation is one in which you have no direct access to the key material that constitutes a key. In other words: "opaque" gives you limited access to the key--just the three methods defined by the Key interface (see below): getAlgorithm, getFormat, and getEncoded.

This is in contrast to a transparent representation, in which you can access each key material value individually, through one of the get methods defined in the corresponding specification class.

All opaque keys have three characteristics:

An Algorithm
The key algorithm for that key. The key algorithm is usually an encryption or asymmetric operation algorithm (such as AES, DSA or RSA), which will work with those algorithms and with related algorithms (such as MD5withRSA, SHA1withRSA, etc.) The name of the algorithm of a key is obtained using this method:
String getAlgorithm()
An Encoded Form
The external encoded form for the key used when a standard representation of the key is needed outside the Java Virtual Machine, as when transmitting the key to some other party. The key is encoded according to a standard format (such as X.509 or PKCS8), and is returned using the method:

byte[] getEncoded()
A Format
The name of the format of the encoded key. It is returned by the method:
String getFormat()
Keys are generally obtained through key generators such as KeyGenerator and KeyPairGenerator, certificates, key specifications (using a KeyFactory), or a KeyStore implementation accessing a keystore database used to manage keys. It is possible to parse encoded keys, in an algorithm-dependent manner, using a KeyFactory.

It is also possible to parse certificates, using a CertificateFactory.

Here is a list of interfaces which extend the Key interface in the java.security.interfaces and javax.crypto.interfaces packages:

  • SecretKey
  • PBEKey
  • PrivateKey
  • DHPrivateKey
  • DSAPrivateKey
  • ECPrivateKey
  • RSAMultiPrimePrivateCrtKey
  • RSAPrivateCrtKey
  • RSAPrivateKey
  • PublicKey
  • DHPublicKey
  • DSAPublicKey
  • ECPublicKey
  • RSAPublicKey

The PublicKey and PrivateKey Interfaces

The PublicKey and PrivateKey interfaces (which both extend the Key interface) are methodless interfaces, used for type-safety and type-identification.

The KeyPair Class

The KeyPair class is a simple holder for a key pair (a public key and a private key). It has two public methods, one for returning the private key, and the other for returning the public key:

PrivateKey getPrivate()
PublicKey getPublic()

Key Specification Interfaces and Classes

Key objects and key specifications (KeySpecs) are two different representations of key data. Ciphers use Key objects to initialize their encryption algorithms, but keys may need to be converted into a more portable format for transmission or storage.

A transparent representation of keys means that you can access each key material value individually, through one of the get methods defined in the corresponding specification class. For example, DSAPrivateKeySpec defines getX, getP, getQ, and getG methods, to access the private key x, and the DSA algorithm parameters used to calculate the key: the prime p, the sub-prime q, and the base g. If the key is stored on a hardware device, its specification may contain information that helps identify the key on the device.

This representation is contrasted with an opaque representation, as defined by the Key interface, in which you have no direct access to the key material fields. In other words, an "opaque" representation gives you limited access to the key--just the three methods defined by the Key interface: getAlgorithm, getFormat, and getEncoded.

A key may be specified in an algorithm-specific way, or in an algorithm-independent encoding format (such as ASN.1). For example, a DSA private key may be specified by its components x, p, q, and g (see DSAPrivateKeySpec), or it may be specified using its DER encoding (see PKCS8EncodedKeySpec).

The KeyFactory and SecretKeyFactory classes can be used to convert between opaque and transparent key representations (that is, between Keys and KeySpecs, assuming that the operation is possible. (For example, private keys on smart cards might not be able leave the card. Such Keys are not convertible.)

In the following sections, we discuss the key specification interfaces and classes in the java.security.spec package.

The KeySpec Interface

This interface contains no methods or constants. Its only purpose is to group and provide type safety for all key specifications. All key specifications must implement this interface.

The KeySpec Subinterfaces

Like the Key interface, there are a similar set of KeySpec interfaces.

  • SecretKeySpec
  • EncodedKeySpec
  • PKCS8EncodedKeySpec
  • X509EncodedKeySpec

  • DESKeySpec
  • DESedeKeySpec
  • PBEKeySpec
  • DHPrivateKeySpec
  • DSAPrivateKeySpec
  • ECPrivateKeySpec
  • RSAMultiPrimePrivateCrtKeySpec
  • RSAPrivateCrtKeySpec
  • RSAPrivateKeySpec
  • DHPublicKeySpec
  • DSAPublicKeySpec
  • ECPublicKeySpec
  • RSAPublicKeySpec

The EncodedKeySpec Class

This abstract class (which implements the KeySpec interface) represents a public or private key in encoded format. Its getEncoded method returns the encoded key:
abstract byte[] getEncoded();
and its getFormat method returns the name of the encoding format:
abstract String getFormat();

See the next sections for the concrete implementations PKCS8EncodedKeySpec and X509EncodedKeySpec.

The PKCS8EncodedKeySpec Class

This class, which is a subclass of EncodedKeySpec, represents the DER encoding of a private key, according to the format specified in the PKCS8 standard. Its getEncoded method returns the key bytes, encoded according to the PKCS8 standard. Its getFormat method returns the string "PKCS#8".

The X509EncodedKeySpec Class

This class, which is a subclass of EncodedKeySpec, represents the DER encoding of a public key, according to the format specified in the X.509 standard. Its getEncoded method returns the key bytes, encoded according to the X.509 standard. Its getFormat method returns the string "X.509".

Of Generators and Factories

Newcomers to Java and the JCA APIs in particular sometimes do not grasp the distinction between generators and factories.

">

Generators are used to generate brand new objects. Generators can be initialized in either an algorithm-dependent or algorithm-independent way. For example, to create a Diffie-Hellman (DH) keypair, an application could specify the necessary P and G values, or the the generator could simply be initialized with the appropriate key length, and the generator will select appropriate P and G values. In both cases, the generator will produce brand new keys based on the parameters.

On the other hand, factories are used to convert data from one existing object type to another. For example, an application might have available the components of a DH private key and can package them as a KeySpec, but needs to convert them into a PrivateKey object that can be used by a KeyAgreement object, or vice-versa. Or they might have the byte array of a certificate, but need to use a CertificateFactory to convert it into a X509Certificate object. Applications use factory objects to do the conversion.

The KeyFactory Class

The KeyFactory class is an engine class designed to perform conversions between opaque cryptographic Keys and key specifications (transparent representations of the underlying key material).

">

Key factories are bi-directional. They allow you to build an opaque key object from a given key specification (key material), or to retrieve the underlying key material of a key object in a suitable format.

Multiple compatible key specifications can exist for the same key. For example, a DSA public key may be specified by its components y, p, q, and g (see java.security.spec.DSAPublicKeySpec), or it may be specified using its DER encoding according to the X.509 standard (see X509EncodedKeySpec).

A key factory can be used to translate between compatible key specifications. Key parsing can be achieved through translation between compatible key specifications, e.g., when you translate from X509EncodedKeySpec to DSAPublicKeySpec, you basically parse the encoded key into its components. For an example, see the end of the Generating/Verifying Signatures Using Key Specifications and KeyFactory section.

Creating a KeyFactory Object

KeyFactory objects are obtained by using one of the KeyFactory getInstance() static factory methods.

Converting Between a Key Specification and a Key Object

If you have a key specification for a public key, you can obtain an opaque PublicKey object from the specification by using the generatePublic method:

PublicKey generatePublic(KeySpec keySpec)

Similarly, if you have a key specification for a private key, you can obtain an opaque PrivateKey object from the specification by using the generatePrivate method:

PrivateKey generatePrivate(KeySpec keySpec)

Converting Between a Key Object and a Key Specification

If you have a Key object, you can get a corresponding key specification object by calling the getKeySpec method:

KeySpec getKeySpec(Key key, Class keySpec)
keySpec identifies the specification class in which the key material should be returned. It could, for example, be DSAPublicKeySpec.class, to indicate that the key material should be returned in an instance of the DSAPublicKeySpec class.

Please see the Examples section for more details.

The SecretKeyFactory Class

This class represents a factory for secret keys. Unlike KeyFactory, a javax.crypto.SecretKeyFactory object operates only on secret (symmetric) keys, whereas a java.security.KeyFactory object processes the public and private key components of a key pair.

">

Key factories are used to convert Keys (opaque cryptographic keys of type java.security.Key) into key specifications (transparent representations of the underlying key material in a suitable format), and vice versa.

Objects of type java.security.Key, of which java.security.PublicKey, java.security.PrivateKey, and javax.crypto.SecretKey are subclasses, are opaque key objects, because you cannot tell how they are implemented. The underlying implementation is provider-dependent, and may be software or hardware based. Key factories allow providers to supply their own implementations of cryptographic keys.

For example, if you have a key specification for a Diffie Hellman public key, consisting of the public value y, the prime modulus p, and the base g, and you feed the same specification to Diffie-Hellman key factories from different providers, the resulting PublicKey objects will most likely have different underlying implementations.

A provider should document the key specifications supported by its secret key factory. For example, the SecretKeyFactory for DES keys supplied by the SunJCE provider supports DESKeySpec as a transparent representation of DES keys, the SecretKeyFactory for DES-EDE keys supports DESedeKeySpec as a transparent representation of DES-EDE keys, and the SecretKeyFactory for PBE supports PBEKeySpec as a transparent representation of the underlying password.

The following is an example of how to use a SecretKeyFactory to convert secret key data into a SecretKey object, which can be used for a subsequent Cipher operation:

    // Note the following bytes are not realistic secret key data
    // bytes but are simply supplied as an illustration of using data
    // bytes (key material) you already have to build a DESKeySpec.
    byte[] desKeyData = { (byte)0x01, (byte)0x02, (byte)0x03,
    (byte)0x04, (byte)0x05, (byte)0x06, (byte)0x07, (byte)0x08 };
    DESKeySpec desKeySpec = new DESKeySpec(desKeyData);
    SecretKeyFactory keyFactory = SecretKeyFactory.getInstance("DES");
    SecretKey secretKey = keyFactory.generateSecret(desKeySpec);

In this case, the underlying implementation of SecretKey is based on the provider of KeyFactory.

An alternative, provider-independent way of creating a functionally equivalent SecretKey object from the same key material is to use the javax.crypto.spec.SecretKeySpec class, which implements the javax.crypto.SecretKey interface:

    byte[] desKeyData = { (byte)0x01, (byte)0x02, ...};
    SecretKeySpec secretKey = new SecretKeySpec(desKeyData, "DES");

Creating a SecretKeyFactory Object

SecretKeyFactory objects are obtained by using one of the SecretKeyFactory getInstance() static factory methods.

Converting Between a Key Specification and a Secret Key Object

If you have a key specification for a secret key, you can obtain an opaque SecretKey object from the specification by using the generateSecret method:

SecretKey generateSecret(KeySpec keySpec)

Converting Between a Secret Key Object and a Key Specification

If you have a Secret Key object, you can get a corresponding key specification object by calling the getKeySpec method:

KeySpec getKeySpec(Key key, Class keySpec)
keySpec identifies the specification class in which the key material should be returned. It could, for example, be DESKeySpec.class, to indicate that the key material should be returned in an instance of the DESKeySpec class.

The KeyPairGenerator Class

The KeyPairGenerator class is an engine class used to generate pairs of public and private keys.

">

There are two ways to generate a key pair: in an algorithm-independent manner, and in an algorithm-specific manner. The only difference between the two is the initialization of the object.

Please see the Examples section for examples of calls to the methods documented below.

Creating a KeyPairGenerator

All key pair generation starts with a KeyPairGenerator. KeyPairGenerator objects are obtained by using one of the KeyPairGenerator getInstance() static factory methods.

Initializing a KeyPairGenerator

A key pair generator for a particular algorithm creates a public/private key pair that can be used with this algorithm. It also associates algorithm-specific parameters with each of the generated keys.

A key pair generator needs to be initialized before it can generate keys. In most cases, algorithm-independent initialization is sufficient. But in other cases, algorithm-specific initialization can be used.

Algorithm-Independent Initialization

All key pair generators share the concepts of a keysize and a source of randomness. The keysize is interpreted differently for different algorithms. For example, in the case of the DSA algorithm, the keysize corresponds to the length of the modulus. (See the Standard Names document for information about the keysizes for specific algorithms.)

An initialize method takes two universally shared types of arguments:

void initialize(int keysize, SecureRandom random)
Another initialize method takes only a keysize argument; it uses a system-provided source of randomness:
void initialize(int keysize)

Since no other parameters are specified when you call the above algorithm-independent initialize methods, it is up to the provider what to do about the algorithm-specific parameters (if any) to be associated with each of the keys.

If the algorithm is a "DSA" algorithm, and the modulus size (keysize) is 512, 768, or 1024, then the SUN provider uses a set of precomputed values for the p, q, and g parameters. If the modulus size is not one of the above values, the SUN provider creates a new set of parameters. Other providers might have precomputed parameter sets for more than just the three modulus sizes mentioned above. Still others might not have a list of precomputed parameters at all and instead always create new parameter sets.

Algorithm-Specific Initialization

For situations where a set of algorithm-specific parameters already exists (such as "community parameters" in DSA), there are two initialize methods that have an AlgorithmParameterSpec argument. One also has a SecureRandom argument, while the source of randomness is system-provided for the other:

void initialize(AlgorithmParameterSpec params,
                SecureRandom random)

void initialize(AlgorithmParameterSpec params)
See the Examples section for more details.

Generating a Key Pair

The procedure for generating a key pair is always the same, regardless of initialization (and of the algorithm). You always call the following method from KeyPairGenerator:

KeyPair generateKeyPair()
Multiple calls to generateKeyPair will yield different key pairs.

The KeyGenerator Class

A key generator is used to generate secret keys for symmetric algorithms.

">

Creating a KeyGenerator

KeyGenerator objects are obtained by using one of the KeyGenerator getInstance() static factory methods.

Initializing a KeyGenerator Object

A key generator for a particular symmetric-key algorithm creates a symmetric key that can be used with that algorithm. It also associates algorithm-specific parameters (if any) with the generated key.

There are two ways to generate a key: in an algorithm-independent manner, and in an algorithm-specific manner. The only difference between the two is the initialization of the object:

  • Algorithm-Independent Initialization

    All key generators share the concepts of a keysize and a source of randomness. There is an init method that takes these two universally shared types of arguments. There is also one that takes just a keysize argument, and uses a system-provided source of randomness, and one that takes just a source of randomness:

    public void init(SecureRandom random);

    public void init(int keysize);

    public void init(int keysize, SecureRandom random);

    Since no other parameters are specified when you call the above algorithm-independent init methods, it is up to the provider what to do about the algorithm-specific parameters (if any) to be associated with the generated key.

  • Algorithm-Specific Initialization

    For situations where a set of algorithm-specific parameters already exists, there are two init methods that have an AlgorithmParameterSpec argument. One also has a SecureRandom argument, while the source of randomness is system-provided for the other:

        public void init(AlgorithmParameterSpec params);

    public void init(AlgorithmParameterSpec params, SecureRandom random);

In case the client does not explicitly initialize the KeyGenerator (via a call to an init method), each provider must supply (and document) a default initialization.

Creating a Key

The following method generates a secret key:
    public SecretKey generateKey();

The KeyAgreement Class

Key agreement is a protocol by which 2 or more parties can establish the same cryptographic keys, without having to exchange any secret information.

">

Each party initializes their key agreement object with their private key, and then enters the public keys for each party that will participate in the communication. In most cases, there are just two parties, but algorithms such as Diffie-Hellman allow for multiple parties (3 or more) to participate. When all the public keys have been entered, each KeyAgreement object will generate (agree upon) the same key.

The KeyAgreement class provides the functionality of a key agreement protocol. The keys involved in establishing a shared secret are created by one of the key generators (KeyPairGenerator or KeyGenerator), a KeyFactory, or as a result from an intermediate phase of the key agreement protocol.

Creating a KeyAgreement Object

Each party involved in the key agreement has to create a KeyAgreement object. KeyAgreement objects are obtained by using one of the KeyAgreement getInstance() static factory methods.

Initializing a KeyAgreement Object

You initialize a KeyAgreement object with your private information. In the case of Diffie-Hellman, you initialize it with your Diffie-Hellman private key. Additional initialization information may contain a source of randomness and/or a set of algorithm parameters. Note that if the requested key agreement algorithm requires the specification of algorithm parameters, and only a key, but no parameters are provided to initialize the KeyAgreement object, the key must contain the required algorithm parameters. (For example, the Diffie-Hellman algorithm uses a prime modulus p and a base generator g as its parameters.)

To initialize a KeyAgreement object, call one of its init methods:

    public void init(Key key);

    public void init(Key key, SecureRandom random);

    public void init(Key key, AlgorithmParameterSpec params);

    public void init(Key key, AlgorithmParameterSpec params,
             SecureRandom random);

Executing a KeyAgreement Phase

Every key agreement protocol consists of a number of phases that need to be executed by each party involved in the key agreement.

To execute the next phase in the key agreement, call the doPhase method:

    public Key doPhase(Key key, boolean lastPhase);

The key parameter contains the key to be processed by that phase. In most cases, this is the public key of one of the other parties involved in the key agreement, or an intermediate key that was generated by a previous phase. doPhase may return an intermediate key that you may have to send to the other parties of this key agreement, so they can process it in a subsequent phase.

The lastPhase parameter specifies whether or not the phase to be executed is the last one in the key agreement: A value of FALSE indicates that this is not the last phase of the key agreement (there are more phases to follow), and a value of TRUE indicates that this is the last phase of the key agreement and the key agreement is completed, i.e., generateSecret can be called next.

In the example of Diffie-Hellman between two parties , you call doPhase once, with lastPhase set to TRUE. In the example of Diffie-Hellman between three parties, you call doPhase twice: the first time with lastPhase set to FALSE, the 2nd time with lastPhase set to TRUE.

Generating the Shared Secret

After each party has executed all the required key agreement phases, it can compute the shared secret by calling one of the generateSecret methods:

    public byte[] generateSecret();

    public int generateSecret(byte[] sharedSecret, int offset);

    public SecretKey generateSecret(String algorithm);

Key Management

A database called a "keystore" can be used to manage a repository of keys and certificates. (A certificate is a digitally signed statement from one entity, saying that the public key of some other entity has a particular value.)

Keystore Location

The user keystore is by default stored in a file named .keystore in the user's home directory, as determined by the "user.home" system property. On Solaris systems "user.home" defaults to the user's home directory. On Win32 systems, given user name uName, "user.home" defaults to:

  • C:\Winnt\Profiles\uName on multi-user Windows NT systems
  • C:\Windows\Profiles\uName on multi-user Windows 95/98/2000 systems
  • C:\Windows on single-user Windows 95/98/2000 systems
Of course, keystore files can be located as desired. In some environments, it may make sense for multiple keystores to exist. For example, in JSSE (SSL/TLS), one keystore might hold a user's private keys, and another might hold certificates used to establish trust relationships.

In addition to the user's keystore, the Sun JDK also maintains a system-wide keystore which is used to store trusted certificates from a variety of Certificate Authorities (CA's). These CA certificates can be used to help make trust decisions. For example, in SSL/TLS when the SunJSSE provider is presented with certificates from a remote peer, the default trustmanager will consult the:

    <java-home>/lib/ext/cacerts           [Unix], or
    <java-home>\lib\ext\cacerts           [Windows]
file to determine if the connection is to be trusted. Instead of using the system-wide cacerts keystore, applications can set up and use their own keystores, or even use the user keystore described above.

Keystore Implementation

The KeyStore class supplies well-defined interfaces to access and modify the information in a keystore. It is possible for there to be multiple different concrete implementations, where each implementation is that for a particular type of keystore.

Currently, there are two command-line tools that make use of KeyStore: keytool and jarsigner, and also a GUI-based tool named policytool. It is also used by the Policy reference implementation when it processes policy files specifying the permissions (allowed accesses to system resources) to be granted to code from various sources. Since KeyStore is publicly available, JDK users can write additional security applications that use it.

Applications can choose different types of keystore implementations from different providers, using the getInstance factory method in the KeyStore class. A keystore type defines the storage and data format of the keystore information, and the algorithms used to protect private keys in the keystore and the integrity of the keystore itself. Keystore implementations of different types are not compatible.

There is a built-in default keystore implementation type known as "jks" that is provided by Sun Microsystems. It implements the keystore as a file, utilizing a proprietary keystore type (format). It protects each private key with its own individual password, and also protects the integrity of the entire keystore with a (possibly different) password. The default is specified by the following line in the security properties file:

    keystore.type=jks

To have tools and other applications use a different default keystore implementation, you can change that line to specify a default type. If you have a provider package that supplies a keystore implementation for a keystore type called "jceks", change the line to:

    keystore.type=jceks
Some applications, such as keytool, also let you override the default keystore type (via the -storetype command-line parameter).
NOTE: Keystore type designations are not case-sensitive. For example, "jks" would be considered the same as "jks".
There are two other types of keystores that come with the Sun JDK implementation.
  1. "jceks" is an alternate proprietary keystore format to "jks" that uses much stronger encryption in the form of Password-Based Encryption with Triple-DES.

    The Sun "jceks" implementation can parse and convert a "jks" keystore file to the "jceks" format. You may upgrade your keystore of type "jks" to a keystore of type "jceks" by changing the password of a private-key entry in your keystore and specifying "-storetype jceks" as the keystore type. To apply the cryptographically strong(er) key protection supplied to a private key named "signkey" in your default keystore, use the following command, which will prompt you for the old and new key passwords:

        keytool -keypasswd -alias signkey -storetype jceks
    See Security Tools for more information about keytool and about keystores and how they are managed.

  2. "pkcs12" is another option. This is a cross platform keystore based on the RSA PKCS12 Personal Information Exchange Syntax Standard. This standard is primarily meant for storing or transporting a user's private keys, certificates, and miscellaneous secrets. As of JDK 6, standards for storing Trusted Certificates in "pkcs12" have not been established yet, and thus "jks" or "jceks" should be used for trusted certificates.

Keystore implementations are provider-based. Developers interested in writing their own KeyStore implementations should consult How to Implement a Provider for the Java Cryptography Architecture for more information on this topic.

The KeyStore Class

The KeyStore class is an engine class that supplies well-defined interfaces to access and modify the information in a keystore.

">

This class represents an in-memory collection of keys and certificates. KeyStore manages two types of entries:

Key Entry

This type of keystore entry holds very sensitive cryptographic key information, which is stored in a protected format to prevent unauthorized access. Typically, a key stored in this type of entry is a secret key, or a private key accompanied by the certificate chain authenticating the corresponding public key.

Private keys and certificate chains are used by a given entity for self-authentication using digital signatures. For example, software distribution organizations digitally sign JAR files as part of releasing and/or licensing software.

Trusted Certificate Entry

This type of entry contains a single public key certificate belonging to another party. It is called a trusted certificate because the keystore owner trusts that the public key in the certificate indeed belongs to the identity identified by the subject (owner) of the certificate.

This type of entry can be used to authenticate other parties.

Each entry in a keystore is identified by an "alias" string. In the case of private keys and their associated certificate chains, these strings distinguish among the different ways in which the entity may authenticate itself. For example, the entity may authenticate itself using different certificate authorities, or using different public key algorithms.

Whether keystores are persistent, and the mechanisms used by the keystore if it is persistent, are not specified here. This convention allows use of a variety of techniques for protecting sensitive (e.g., private or secret) keys. Smart cards or other integrated cryptographic engines (SafeKeyper) are one option, and simpler mechanisms such as files may also be used (in a variety of formats).

The main KeyStore methods are described below.

Creating a KeyStore Object

KeyStore objects are obtained by using one of the KeyStore getInstance() static factory methods.

Loading a Particular Keystore into Memory

Before a KeyStore object can be used, the actual keystore data must be loaded into memory via the load method:
final void load(InputStream stream, char[] password)
The optional password is used to check the integrity of the keystore data. If no password is supplied, no integrity check is performed.

To create an empty keystore, you pass null as the InputStream argument to the load method.

Getting a List of the Keystore Aliases

All keystore entries are accessed via unique aliases. The aliases method returns an enumeration of the alias names in the keystore:

final Enumeration aliases()

Determining Keystore Entry Types

As stated in The KeyStore Class, there are two different types of entries in a keystore.

The following methods determine whether the entry specified by the given alias is a key/certificate or a trusted certificate entry, respectively:

final boolean isKeyEntry(String alias)
final boolean isCertificateEntry(String alias)

Adding/Setting/Deleting Keystore Entries

The setCertificateEntry method assigns a certificate to a specified alias:
final void setCertificateEntry(String alias, Certificate cert)
If alias doesn't exist, a trusted certificate entry with that alias is created. If alias exists and identifies a trusted certificate entry, the certificate associated with it is replaced by cert.

The setKeyEntry methods add (if alias doesn't yet exist) or set key entries:

final void setKeyEntry(String alias,
                       Key key,
                       char[] password,
                       Certificate[] chain)

final void setKeyEntry(String alias,
                       byte[] key,
                       Certificate[] chain)
In the method with key as a byte array, it is the bytes for a key in protected format. For example, in the keystore implementation supplied by the SUN provider, the key byte array is expected to contain a protected private key, encoded as an EncryptedPrivateKeyInfo as defined in the PKCS8 standard. In the other method, the password is the password used to protect the key.

The deleteEntry method deletes an entry:

final void deleteEntry(String alias)

Getting Information from the Keystore

The getKey method returns the key associated with the given alias. The key is recovered using the given password:
final Key getKey(String alias, char[] password)
The following methods return the certificate, or certificate chain, respectively, associated with the given alias:
final Certificate getCertificate(String alias)
final Certificate[] getCertificateChain(String alias)
You can determine the name (alias) of the first entry whose certificate matches a given certificate via the following:
final String getCertificateAlias(Certificate cert)

Saving the KeyStore

The in-memory keystore can be saved via the store method:
final void store(OutputStream stream, char[] password)
The password is used to calculate an integrity checksum of the keystore data, which is appended to the keystore data.

Algorithm Parameters Classes

Like Keys and Keyspecs, an algorithm's initialization parameters are represented by either AlgorithmParameters or AlgorithmParameterSpecs. Depending on the use situation, algorithms can use the parameters directly, or the parameters might need to be converted into a more portable format for transmission or storage.

A transparent representation of a set of parameters (via AlgorithmParameterSpec) means that you can access each parameter value in the set individually. You can access these values through one of the get methods defined in the corresponding specification class (e.g., DSAParameterSpec defines getP, getQ, and getG methods, to access p, q, and g, respectively).

In contrast, the AlgorithmParameters class supplies an opaque representation, in which you have no direct access to the parameter fields. You can only get the name of the algorithm associated with the parameter set (via getAlgorithm) and some kind of encoding for the parameter set (via getEncoded).

The AlgorithmParameterSpec Interface

AlgorithmParameterSpec is an interface to a transparent specification of cryptographic parameters. This interface contains no methods or constants. Its only purpose is to group (and provide type safety for) all parameter specifications. All parameter specifications must implement this interface.

The algorithm parameter specification interfaces and classes in the java.security.spec and javax.crypto.spec packages are described in the JDK javadocs:

  • DHParameterSpec
  • DHGenParameterSpec
  • DSAParameterSpec
  • ECGenParameterSpec
  • ECParameterSpec
  • IvParameterSpec
  • MGF1ParameterSpec
  • OAEPParameterSpec
  • PBEParameterSpec
  • PSSParameterSpec
  • RC2ParameterSpec
  • RC5ParameterSpec
  • RSAKeyGenParameterSpec

The following algorithm parameter specs are used specifically for digital signatures, as part of JSR 105.

  • C14NMethodParameterSpec
  • DigestMethodParameterSpec
  • SignatureMethodParameterSpec
  • TransformParameterSpec
  • ExcC14NParameterSpec
  • HMACParameterSpec
  • XPathFilter2ParameterSpec
  • XPathFilterParameterSpec
  • XSLTTransformParameterSpec

The AlgorithmParameters Class

The AlgorithmParameters class is an engine class that provides an opaque representation of cryptographic parameters. You can initialize the AlgorithmParameters class using a specific AlgorithmParameterSpec object, or by encoding the parameters in a recognized format. You can retrieve the resulting specification with the getParameterSpec method (see the following section).

Creating an AlgorithmParameters Object

AlgorithmParameters objects are obtained by using one of the AlgorithmParameters getInstance() static factory methods.

Initializing an AlgorithmParameters Object

Once an AlgorithmParameters object is instantiated, it must be initialized via a call to init, using an appropriate parameter specification or parameter encoding:

void init(AlgorithmParameterSpec paramSpec)
void init(byte[] params)
void init(byte[] params, String format)
In these init methods, params is an array containing the encoded parameters, and format is the name of the decoding format. In the init method with a params argument but no format argument, the primary decoding format for parameters is used. The primary decoding format is ASN.1, if an ASN.1 specification for the parameters exists.
NOTE: AlgorithmParameters objects can be initialized only once. They are not reusable.

Obtaining the Encoded Parameters

A byte encoding of the parameters represented in an AlgorithmParameters object may be obtained via a call to getEncoded:

byte[] getEncoded()
This method returns the parameters in their primary encoding format. The primary encoding format for parameters is ASN.1, if an ASN.1 specification for this type of parameters exists.

If you want the parameters returned in a specified encoding format, use

byte[] getEncoded(String format)
If format is null, the primary encoding format for parameters is used, as in the other getEncoded method.
NOTE: In the default AlgorithmParameters implementation, supplied by the SUN provider, the format argument is currently ignored.

Converting an AlgorithmParameters Object to a Transparent Specification

A transparent parameter specification for the algorithm parameters may be obtained from an AlgorithmParameters object via a call to getParameterSpec:

AlgorithmParameterSpec getParameterSpec(Class paramSpec)
paramSpec identifies the specification class in which the parameters should be returned. The specification class could be, for example, DSAParameterSpec.class to indicate that the parameters should be returned in an instance of the DSAParameterSpec class. (This class is in the java.security.spec package.)

The AlgorithmParameterGenerator Class

The AlgorithmParameterGenerator class is an engine class used to generate a set of brand-new parameters suitable for a certain algorithm (the algorithm is specified when an AlgorithmParameterGenerator instance is created). This object is used when you do not have an existing set of algorithm parameters, and want to generate one from scratch.

Creating an AlgorithmParameterGenerator Object

AlgorithmParameterGenerator objects are obtained by using one of the AlgorithmParameterGenerator getInstance() static factory methods.

Initializing an AlgorithmParameterGenerator Object

The AlgorithmParameterGenerator object can be initialized in two different ways: an algorithm-independent manner or an algorithm-specific manner.

The algorithm-independent approach uses the fact that all parameter generators share the concept of a "size" and a source of randomness. The measure of size is universally shared by all algorithm parameters, though it is interpreted differently for different algorithms. For example, in the case of parameters for the DSA algorithm, "size" corresponds to the size of the prime modulus, in bits. (See the Standard Names document for information about the sizes for specific algorithms.) When using this approach, algorithm-specific parameter generation values--if any--default to some standard values. One init method that takes these two universally shared types of arguments:

void init(int size, SecureRandom random);
Another init method takes only a size argument and uses a system-provided source of randomness:
void init(int size)

A third approach initializes a parameter generator object using algorithm-specific semantics, which are represented by a set of algorithm-specific parameter generation values supplied in an AlgorithmParameterSpec object:

void init(AlgorithmParameterSpec genParamSpec,
                          SecureRandom random)

void init(AlgorithmParameterSpec genParamSpec)
To generate Diffie-Hellman system parameters, for example, the parameter generation values usually consist of the size of the prime modulus and the size of the random exponent, both specified in number of bits.

Generating Algorithm Parameters

Once you have created and initialized an AlgorithmParameterGenerator object, you can use the generateParameters method to generate the algorithm parameters:
AlgorithmParameters generateParameters()

The CertificateFactory Class

The CertificateFactory class is an engine class that defines the functionality of a certificate factory, which is used to generate certificate and certificate revocation list (CRL) objects from their encodings.

A certificate factory for X.509 must return certificates that are an instance of java.security.cert.X509Certificate, and CRLs that are an instance of java.security.cert.X509CRL.

Creating a CertificateFactory Object

CertificateFactory objects are obtained by using one of the getInstance() static factory methods.

Generating Certificate Objects

To generate a certificate object and initialize it with the data read from an input stream, use the generateCertificate method:
final Certificate generateCertificate(InputStream inStream)
To return a (possibly empty) collection view of the certificates read from a given input stream, use the generateCertificates method:
final Collection generateCertificates(InputStream inStream)

Generating CRL Objects

To generate a certificate revocation list (CRL) object and initialize it with the data read from an input stream, use the generateCRL method:
final CRL generateCRL(InputStream inStream)
To return a (possibly empty) collection view of the CRLs read from a given input stream, use the generateCRLs method:
final Collection generateCRLs(InputStream inStream)

Generating CertPath Objects

The certificate path builder and validator for PKIX is defined by the Internet X.509 Public Key Infrastructure Certificate and CRL Profile, RFC 3280.

A certificate store implementation for retrieving certificates and CRLs from Collection and LDAP directories, using the PKIX LDAP V2 Schema is also available from the IETF as RFC 2587.

To generate a CertPath object and initialize it with data read from an input stream, use one of the following generateCertPath methods (with or without specifying the encoding to be used for the data):

final CertPath generateCertPath(InputStream inStream)

final CertPath generateCertPath(InputStream inStream,
                                String encoding)
To generate a CertPath object and initialize it with a list of certificates, use the following method:
final CertPath generateCertPath(List certificates)
To retrieve a list of the CertPath encodings supported by this certificate factory, you can call the getCertPathEncodings method:
final Iterator getCertPathEncodings()
The default encoding will be listed first.

How the JCA Might Be Used in a SSL/TLS Implementation

With an understanding of the JCA classes, consider how these classes might be combined to implement an advanced network protocol like SSL/TLS. The SSL/TLS Overview section in the JSSE Reference Guide describes at a high level how the protocols work. As asymmetric (public key) cipher operations are much slower than symmetric operations (secret key), public key cryptography is used to establish secret keys which are then used to protect the actual application data. Vastly simplified, the SSL/TLS handshake involves exchanging initialization data, performing some public key operations to arrive at a secret key, and then using that key to encrypt further traffic.
NOTE: The details presented here simply show how some of the above classes might be employed. This section will not present sufficient information for building a SSL/TLS implementation. For more details, please see the JSSE Reference Guide and RFC 2246: The TLS Protocol.

Assume that this SSL/TLS implementation will be made available as a JSSE provider. A concrete implementation of the Provider class is first written that will eventually be registered in the Security class' list of providers. This provider mainly provides a mapping from algorithm names to actual implementation classes. (that is: "SSLContext.TLS"->"com.foo.TLSImpl") When an application requests an "TLS" instance (via SSLContext.getInstance("TLS"), the provider's list is consulted for the requested algorithm, and an appropriate instance is created.

Before discussing details of the actual handshake, a quick review of some of the JSSE's architecture is needed. The heart of the JSSE architecture is the SSLContext. The context eventually creates end objects (SSLSocket and SSLEngine) which actually implement the SSL/TLS protocol. SSLContexts are initialized with two callback classes, KeyManager and TrustManager, which allow applications to first select authentication material to send and second to verify credentials sent by a peer.

A JSSE KeyManager is responsible for choosing which credentials to present to a peer. Many algorithms are possible, but a common strategy is to maintain a RSA or DSA public/private key pair along with a X509Certificate in a KeyStore backed by a disk file. When a KeyStore object is initialized and loaded from the file, the file's raw bytes are converted into PublicKey and PrivateKey objects using a KeyFactory, and a certificate chain's bytes are converted using a CertificateFactory. When a credential is needed, the KeyManager simply consults this KeyStore object and determines which credentials to present.

A KeyStore's contents might have originally been created using a utility such as keytool. keytool creates a RSA or DSA KeyPairGenerator and initializes it with an appropriate keysize. This generator is then used to create a KeyPair which keytool would store along with the newly-created certificate in the KeyStore, which is eventually written to disk.

A JSSE TrustManager is responsible for verifying the credentials received from a peer. There are many ways to verify credentials: one of them is to create a CertPath object, and let the JDK's built-in Public Key Infrastructure (PKI) framework handle the validation. Internally, the CertPath implementation might create a Signature object, and use that to verify that the each of the signatures in the certificate chain.

With this basic understanding of the architecture, we can look at some of the steps in the SSL/TLS handshake. The client begins by sending a ClientHello message to the server. The server selects a ciphersuite to use, and sends that back in a ServerHello message, and begins creating JCA objects based on the suite selection. We'll use server-only authentication in the following examples.

">

In the first example, the server tries to use a RSA-based ciphersuite such as TLS_RSA_WITH_AES_128_CBC_SHA. The server's KeyManager is queried, and returns an appropriate RSA entry. The server's credentials (that is: certificate/public key) are sent in the server's Certificate message. The client's TrustManager verifies the server's certificate, and if accepted, the client generates some random bytes using a SecureRandom object. This is then encrypted using an encrypting asymmetric RSA Cipher object that has been initialized with the PublicKey found in the server's certificate. This encrypted data is sent in a Client Key Exchange message. The server would use its corresponding PrivateKey to recover the bytes using a similar Cipher in decrypt mode. These bytes are then used to establish the actual encryption keys.

In a different example, an ephemeral Diffie-Hellman key agreement algorithm along with the DSA signature algorithm is chosen, such as TLS_DHE_DSS_WITH_AES_128_CBC_SHA. The two sides must each establish a new temporary DH public/private keypair using a KeyPairGenerator. Each generator creates DH keys which can then be further converted into pieces using the KeyFactory and DHPublicKeySpec classes. Each side then creates a KeyAgreement object and initializes it with their respective DH PrivateKeys. The server sends its public key pieces in a ServerKeyExchange message (protected by the DSA signature algorithm, and the client sends its public key in a ClientKeyExchange message. When the public keys are reassembled using another KeyFactory, they are fed into the agreement objects. The KeyAgreement objects then generate agreed-upon bytes that are then used to establish the actual encryption keys.

Once the actual encryption keys have been established, the secret key is used to initialize a symmetric Cipher object, and this cipher is used to protect all data in transit. To help determine if the data has been modified, a MessageDigest is created and receives a copy of the data destined for the network. When the packet is complete, the digest (hash) is appended to data, and the entire packet is encrypted by the Cipher. If a block cipher such as AES is used, the data must be padded to make a complete block. On the remote side, the steps are simply reversed.

Header Data Digest Padding (if any)

Again, this is vastly simplied, but gives one an idea of how these classes might be combined to create a higher level protocol.

How to Make Applications "Exempt" from Cryptographic Restrictions

Note 1: This section should be ignored by most application developers. It is only for people whose applications may be exported to those few countries whose governments mandate cryptographic restrictions, if it is desired that such applications have fewer cryptographic restrictions than those mandated.

Note 2: Throughout this section, the term "application" is meant to encompass both applications and applets.]

The JCA framework includes an ability to enforce restrictions regarding the cryptographic algorithms and maximum cryptographic strengths available to applets/applications in different jurisdiction contexts (locations). Any such restrictions are specified in "jurisdiction policy files".

Due to import control restrictions by the governments of a few countries, the jurisdiction policy files shipped with the Java SE Development Kit 6 from Sun Microsystems specify that "strong" but limited cryptography may be used. An "unlimited strength" version of these files indicating no restrictions on cryptographic strengths is available for those living in eligible countries (which is most countries). But only the "strong" version can be imported into those countries whose governments mandate restrictions. The JCA framework will enforce the restrictions specified in the installed jurisdiction policy files.

It is possible that the governments of some or all such countries may allow certain applications to become exempt from some or all cryptographic restrictions. For example, they may consider certain types of applications as "special" and thus exempt. Or they may exempt any application that utilizes an "exemption mechanism," such as key recovery. Applications deemed to be exempt could get access to stronger cryptography than that allowed for non-exempt applications in such countries.

In order for an application to be recognized as "exempt" at runtime, it must meet the following conditions:

  • It must have a permission policy file bundled with it in a JAR file. The permission policy file specifies what cryptography-related permissions the application has, and under what conditions (if any).

  • The JAR file containing the application and the permission policy file must have been signed using a code-signing certificate issued after the application was accepted as exempt.

Below are sample steps required in order to make an application exempt from some or all cryptographic restrictions. This is a basic outline that includes information about what is required by JCA in order to recognize and treat applications as being exempt. You will need to know the exemption requirements of the particular country or countries in which you would like your application to be able to be run but whose governments require cryptographic restrictions. You will also need to know the requirements of a JCA framework vendor that has a process in place for handling exempt applications. Consult such a vendor for further information. (NOTE: The SunJCE provider does not supply an implementation of the ExemptionMechanismSpi class.)

  • Step 1: Write and Compile Your Application Code

  • Step 2: Create a Permission Policy File Granting Appropriate Cryptographic Permissions

  • Step 3: Prepare for Testing

  • Step 3a: Apply for Government Approval From the Government Mandating Restrictions.

  • Step 3b: Get a Code-Signing Certificate

  • Step 3c: Bundle the Application and Permission Policy File into a JAR file

  • Step 3d: Sign the JAR file

  • Step 3e: Set Up Your Environment Like That of a User in a Restricted Country

  • Step 3f: (only for apps using exemption mechanisms) Install a Provider Implementing the Exemption Mechanism Specified by the entry in the Permission Policy File

  • Step 4: Test Your Application

  • Step 5: Apply for U.S. Government Export Approval If Required

  • Step 6: Deploy Your Application

Special Code Requirements for Applications that Use Exemption Mechanisms

When an application has a permission policy file associated with it (in the same JAR file) and that permission policy file specifies an exemption mechanism, then when the Cipher getInstance method is called to instantiate a Cipher, the JCA code searches the installed providers for one that implements the specified exemption mechanism. If it finds such a provider, JCA instantiates an ExemptionMechanism API object associated with the provider's implementation, and then associates the ExemptionMechanism object with the Cipher returned by getInstance.

After instantiating a Cipher, and prior to initializing it (via a call to the Cipher init method), your code must call the following Cipher method:

    public ExemptionMechanism getExemptionMechanism()

This call returns the ExemptionMechanism object associated with the Cipher. You must then initialize the exemption mechanism implementation by calling the following method on the returned ExemptionMechanism:

    public final void init(Key key)

The argument you supply should be the same as the argument of the same types that you will subsequently supply to a Cipher init method.

Once you have initialized the ExemptionMechanism, you can proceed as usual to initialize and use the Cipher.

Permission Policy Files

In order for an application to be recognized at runtime as being "exempt" from some or all cryptographic restrictions, it must have a permission policy file bundled with it in a JAR file. The permission policy file specifies what cryptography-related permissions the application has, and under what conditions (if any).

NOTE: The permission policy file bundled with an application must be named cryptoPerms.

The format of a permission entry in a permission policy file that accompanies an exempt application is the same as the format for a jurisdiction policy file downloaded with the JDK, which is:

    permission <crypto permission class name>[ <alg_name>
        [[, <exemption mechanism name>][, <maxKeySize>
        [, <AlgorithmParameterSpec class name>,
        <parameters for constructing an AlgorithmParameterSpec object>
    ]]]];

See Appendix B for more information about the jurisdiction policy file format.

Permission Policy Files for Exempt Applications

Some applications may be allowed to be completely unrestricted. Thus, the permission policy file that accompanies such an application usually just needs to contain the following:

    grant {
        // There are no restrictions to any algorithms.
        permission javax.crypto.CryptoAllPermission;
    };

If an application just uses a single algorithm (or several specific algorithms), then the permission policy file could simply mention that algorithm (or algorithms) explicitly, rather than granting CryptoAllPermission. For example, if an application just uses the Blowfish algorithm, the permission policy file doesn't have to grant CryptoAllPermission to all algorithms. It could just specify that there is no cryptographic restriction if the Blowfish algorithm is used. In order to do this, the permission policy file would look like the following:

    grant {
        permission javax.crypto.CryptoPermission "Blowfish";
    };

Permission Policy Files for Applications Exempt Due to Exemption Mechanisms

If an application is considered "exempt" if an exemption mechanism is enforced, then the permission policy file that accompanies the application must specify one or more exemption mechanisms. At runtime, the application will be considered exempt if any of those exemption mechanisms is enforced. Each exemption mechanism must be specified in a permission entry that looks like the following:

    // No algorithm restrictions if specified
    // exemption mechanism is enforced.
    permission javax.crypto.CryptoPermission *,
    "<ExemptionMechanismName>";

where <ExemptionMechanismName> specifies the name of an exemption mechanism. The list of possible exemption mechanism names includes:

  • KeyRecovery

  • KeyEscrow

  • KeyWeakening
As an example, suppose your application is exempt if either key recovery or key escrow is enforced. Then your permission policy file should contain the following:
    grant {
    // No algorithm restrictions if KeyRecovery is enforced.
    permission javax.crypto.CryptoPermission *,
        "KeyRecovery";
    // No algorithm restrictions if KeyEscrow is enforced.
    permission javax.crypto.CryptoPermission *,
        "KeyEscrow";
    };

NOTE: Permission entries that specify exemption mechanisms should not also specify maximum key sizes. The allowed key sizes are actually determined from the installed exempt jurisdiction policy files, as described in the next section.

How Bundled Permission Policy Files Affect Cryptographic Permissions

At runtime, when an application instantiates a Cipher (via a call to its getInstance method) and that application has an associated permission policy file, JCA checks to see whether the permission policy file has an entry that applies to the algorithm specified in the getInstance call. If it does, and the entry grants CryptoAllPermission or does not specify that an exemption mechanism must be enforced, it means there is no cryptographic restriction for this particular algorithm.

If the permission policy file has an entry that applies to the algorithm specified in the getInstance call and the entry does specify that an exemption mechanism must be enforced, then the exempt jurisdiction policy file(s) are examined. If the exempt permissions include an entry for the relevant algorithm and exemption mechanism, and that entry is implied by the permissions in the permission policy file bundled with the application, and if there is an implementation of the specified exemption mechanism available from one of the registered providers, then the maximum key size and algorithm parameter values for the Cipher are determined from the exempt permission entry.

If there is no exempt permission entry implied by the relevant entry in the permission policy file bundled with the application, or if there is no implementation of the specified exemption mechanism available from any of the registered providers, then the application is only allowed the standard default cryptographic permissions.

Code Examples

Here are some short examples which illustrate use of several of the JCA mechanisms. In addition, complete working examples can be found in Appendix D.

Computing a MessageDigest Object

First create the message digest object, as in the following example:

MessageDigest sha = MessageDigest.getInstance("SHA-1");
This call assigns a properly initialized message digest object to the sha variable. The implementation implements the Secure Hash Algorithm (SHA-1), as defined in the National Institute for Standards and Technology's (NIST) FIPS 180-2 document. See Appendix A for a complete discussion of standard names and algorithms.

Next, suppose we have three byte arrays, i1, i2 and i3, which form the total input whose message digest we want to compute. This digest (or "hash") could be calculated via the following calls:

sha.update(i1);
sha.update(i2);
sha.update(i3);
byte[] hash = sha.digest();

An equivalent alternative series of calls would be:

sha.update(i1);
sha.update(i2);
byte[] hash = sha.digest(i3);
After the message digest has been calculated, the message digest object is automatically reset and ready to receive new data and calculate its digest. All former state (i.e., the data supplied to update calls) is lost.

Some hash implementations may support intermediate hashes through cloning. Suppose we want to calculate separate hashes for:

  • i1
  • i1 and i2
  • i1, i2, and i3

A way to do it is:

/* compute the hash for i1 */
sha.update(i1);
byte[] i1Hash = sha.clone().digest();

/* compute the hash for i1 and i2 */
sha.update(i2);
byte[] i12Hash = sha.clone().digest();

/* compute the hash for i1, i2 and i3 */
sha.update(i3);
byte[] i123hash = sha.digest();
This code works only if the SHA-1 implementation is cloneable. While some implementations of message digests are cloneable, others are not. To determine whether or not cloning is possible, attempt to clone the MessageDigest object and catch the potential exception as follows:
try {
    // try and clone it
    /* compute the hash for i1 */
    sha.update(i1);
    byte[] i1Hash = sha.clone().digest();
    . . .
    byte[] i123hash = sha.digest();
} catch (CloneNotSupportedException cnse) {
    // do something else, such as the code shown below
}
If a message digest is not cloneable, the other, less elegant way to compute intermediate digests is to create several digests. In this case, the number of intermediate digests to be computed must be known in advance:
MessageDigest sha1 = MessageDigest.getInstance("SHA-1");
MessageDigest sha12 = MessageDigest.getInstance("SHA-1");
MessageDigest sha123 = MessageDigest.getInstance("SHA-1");

byte[] i1Hash = sha1.digest(i1);

sha12.update(i1);
byte[] i12Hash = sha12.digest(i2);

sha123.update(i1);
sha123.update(i2);
byte[] i123Hash = sha123.digest(i3);

Generating a Pair of Keys

In this example we will generate a public-private key pair for the algorithm named "DSA" (Digital Signature Algorithm), and use this keypair in future examples. We will generate keys with a 1024-bit modulus. We don't care which provider supplies the algorithm implementation.

Creating the Key Pair Generator

The first step is to get a key pair generator object for generating keys for the DSA algorithm:

KeyPairGenerator keyGen = KeyPairGenerator.getInstance("DSA");

Initializing the Key Pair Generator

The next step is to initialize the key pair generator. In most cases, algorithm-independent initialization is sufficient, but in some cases, algorithm-specific initialization is used.
Algorithm-Independent Initialization

All key pair generators share the concepts of a keysize and a source of randomness. The KeyPairGenerator class initialization methods at a minimum needs a keysize. If the source of randomness is not explicitly provided, a SecureRandom implementation of the highest-priority installed provider will be used. Thus to generate keys with a keysize of 1024, simply call:

SecureRandom random = SecureRandom.getInstance("SHA1PRNG", "SUN");
keyGen.initialize(1024, random);
The following code illustrates how to use a specific, additionally seeded SecureRandom object:
SecureRandom random = SecureRandom.getInstance("SHA1PRNG", "SUN");
random.setSeed(userSeed);
keyGen.initialize(1024, random);
Since no other parameters are specified when you call the above algorithm-independent initialize method, it is up to the provider what to do about the algorithm-specific parameters (if any) to be associated with each of the keys. The provider may use precomputed parameter values or may generate new values.
Algorithm-Specific Initialization

For situations where a set of algorithm-specific parameters already exists (such as "community parameters" in DSA), there are two initialize methods that have an AlgorithmParameterSpec argument. Suppose your key pair generator is for the "DSA" algorithm, and you have a set of DSA-specific parameters, p, q, and g, that you would like to use to generate your key pair. You could execute the following code to initialize your key pair generator (recall that DSAParameterSpec is an AlgorithmParameterSpec):

DSAParameterSpec dsaSpec = new DSAParameterSpec(p, q, g);
SecureRandom random = SecureRandom.getInstance("SHA1PRNG", "SUN");
random.setSeed(userSeed);
keyGen.initialize(dsaSpec, random);
NOTE: The parameter named p is a prime number whose length is the modulus length ("size"). Therefore, you don't need to call any other method to specify the modulus length.

Generating the Pair of Keys

The final step is actually generating the key pair. No matter which type of initialization was used (algorithm-independent or algorithm-specific), the same code is used to generate the key pair:
KeyPair pair = keyGen.generateKeyPair();

Generating and Verifying a Signature Using Generated Keys

The following signature generation and verification examples use the KeyPair generated in the key pair example above.

Generating a Signature

We first create a signature object:

Signature dsa = Signature.getInstance("SHA1withDSA");
Next, using the key pair generated in the key pair example, we initialize the object with the private key, then sign a byte array called data.
/* Initializing the object with a private key */
PrivateKey priv = pair.getPrivate();
dsa.initSign(priv);

/* Update and sign the data */
dsa.update(data);
byte[] sig = dsa.sign();

Verifying a Signature

Verifying the signature is straightforward. (Note that here we also use the key pair generated in the key pair example.)
/* Initializing the object with the public key */
PublicKey pub = pair.getPublic();
dsa.initVerify(pub);

/* Update and verify the data */
dsa.update(data);
boolean verifies = dsa.verify(sig);
System.out.println("signature verifies: " + verifies);

Generating/Verifying Signatures Using Key Specifications and KeyFactory

Suppose that, rather than having a public/private key pair (as, for example, was generated in the key pair example above), you simply have the components of your DSA private key: x (the private key), p (the prime), q (the sub-prime), and g (the base).

Further suppose you want to use your private key to digitally sign some data, which is in a byte array named someData. You would do the following steps, which also illustrate creating a key specification and using a key factory to obtain a PrivateKey from the key specification (initSign requires a PrivateKey):

DSAPrivateKeySpec dsaPrivKeySpec = new DSAPrivateKeySpec(x, p, q, g);

KeyFactory keyFactory = KeyFactory.getInstance("DSA");
PrivateKey privKey = keyFactory.generatePrivate(dsaPrivKeySpec);

Signature sig = Signature.getInstance("SHA1withDSA");
sig.initSign(privKey);
sig.update(someData);
byte[] signature = sig.sign();
Suppose Alice wants to use the data you signed. In order for her to do so, and to verify your signature, you need to send her three things:
  1. the data,
  2. the signature, and
  3. the public key corresponding to the private key you used to sign the data.
You can store the someData bytes in one file, and the signature bytes in another, and send those to Alice.

For the public key, assume, as in the signing example above, you have the components of the DSA public key corresponding to the DSA private key used to sign the data. Then you can create a DSAPublicKeySpec from those components:

DSAPublicKeySpec dsaPubKeySpec = new DSAPublicKeySpec(y, p, q, g);
You still need to extract the key bytes so that you can put them in a file. To do so, you can first call the generatePublic method on the DSA key factory already created in the example above:
PublicKey pubKey = keyFactory.generatePublic(dsaPubKeySpec);
Then you can extract the (encoded) key bytes via the following:
byte[] encKey = pubKey.getEncoded();
You can now store these bytes in a file, and send it to Alice along with the files containing the data and the signature.

Now, assume Alice has received these files, and she copied the data bytes from the data file to a byte array named data, the signature bytes from the signature file to a byte array named signature, and the encoded public key bytes from the public key file to a byte array named encodedPubKey.

Alice can now execute the following code to verify the signature. The code also illustrates how to use a key factory in order to instantiate a DSA public key from its encoding (initVerify requires a PublicKey).

    X509EncodedKeySpec pubKeySpec = new X509EncodedKeySpec(encodedPubKey);

    KeyFactory keyFactory = KeyFactory.getInstance("DSA");
    PublicKey pubKey = keyFactory.generatePublic(pubKeySpec);

    Signature sig = Signature.getInstance("SHA1withDSA");
    sig.initVerify(pubKey);
    sig.update(data);
    sig.verify(signature);
NOTE: In the above, Alice needed to generate a PublicKey from the encoded key bits, since initVerify requires a PublicKey. Once she has a PublicKey, she could also use the KeyFactory getKeySpec method to convert it to a DSAPublicKeySpec so that she can access the components, if desired, as in:
    DSAPublicKeySpec dsaPubKeySpec =
        (DSAPublicKeySpec)keyFactory.getKeySpec(pubKey,
            DSAPublicKeySpec.class)
Now she can access the DSA public key components y, p, q, and g through the corresponding "get" methods on the DSAPublicKeySpec class (getY, getP, getQ, and getG).

Determining If Two Keys Are Equal

In many cases you would like to know if two keys are equal; however, the default method java.lang.Object.equals may not give the desired result. The most provider-independent approach is to compare the encoded keys. If this comparison isn't appropriate (for example, when comparing an RSAPrivateKey and an RSAPrivateCrtKey), you should compare each component. The following code demonstrates this idea:

static boolean keysEqual(Key key1, Key key2) {
    if (key1.equals(key2)) {
        return true;
    }

    if (Arrays.equals(key1.getEncoded(), key2.getEncoded())) {
        return true;
    }

    // More code for different types of keys here.
    // For example, the following code can check if
    // an RSAPrivateKey and an RSAPrivateCrtKey are equal:
    // if ((key1 instanceof RSAPrivateKey) &&
    //     (key2 instanceof RSAPrivateKey)) {
    //     if ((key1.getModulus().equals(key2.getModulus())) &&
    //         (key1.getPrivateExponent().equals(
    //                                      key2.getPrivateExponent()))) {
    //         return true;
    //     }
    // }

    return false;
}

Reading Base64-Encoded Certificates

The following example reads a file with Base64-encoded certificates, which are each bounded at the beginning by

-----BEGIN CERTIFICATE-----
and at the end by
-----END CERTIFICATE-----
We convert the FileInputStream (which does not support mark and reset) to a ByteArrayInputStream (which supports those methods), so that each call to generateCertificate consumes only one certificate, and the read position of the input stream is positioned to the next certificate in the file:

FileInputStream fis = new FileInputStream(filename);
BufferedInputStream bis = new BufferedInputStream(fis);

CertificateFactory cf = CertificateFactory.getInstance("X.509");

while (bis.available() > 0) {
    Certificate cert = cf.generateCertificate(bis);
    System.out.println(cert.toString());
}

Parsing a Certificate Reply

The following example parses a PKCS7-formatted certificate reply stored in a file and extracts all the certificates from it:

FileInputStream fis = new FileInputStream(filename);
CertificateFactory cf = CertificateFactory.getInstance("X.509");
Collection c = cf.generateCertificates(fis);
Iterator i = c.iterator();
while (i.hasNext()) {
   Certificate cert = (Certificate)i.next();
   System.out.println(cert);
}

Using Encryption

This section takes the user through the process of generating a key, creating and initializing a cipher object, encrypting a file, and then decrypting it. Throughout this example, we use the Advanced Encryption Standard (AES).

Generating a Key

To create an AES key, we have to instantiate a KeyGenerator for AES. We do not specify a provider, because we do not care about a particular AES key generation implementation. Since we do not initialize the KeyGenerator, a system-provided source of randomness and a default keysize will be used to create the AES key:

    KeyGenerator keygen = KeyGenerator.getInstance("AES");
    SecretKey aesKey = keygen.generateKey();

After the key has been generated, the same KeyGenerator object can be re-used to create further keys.

Creating a Cipher

The next step is to create a Cipher instance. To do this, we use one of the getInstance factory methods of the Cipher class. We must specify the name of the requested transformation, which includes the following components, separated by slashes (/):

  • the algorithm name
  • the mode (optional)
  • the padding scheme (optional)

In this example, we create an AES cipher in Electronic Codebook mode, with PKCS5-style padding. We do not specify a provider, because we do not care about a particular implementation of the requested transformation.

The standard algorithm name for AES is "AES", the standard name for the Electronic Codebook mode is "ECB", and the standard name for PKCS5-style padding is "PKCS5Padding":

    Cipher aesCipher;

    // Create the cipher
    aesCipher = Cipher.getInstance("AES/ECB/PKCS5Padding");

We use the generated aesKey from above to initialize the Cipher object for encryption:

    // Initialize the cipher for encryption
    aesCipher.init(Cipher.ENCRYPT_MODE, aesKey);

    // Our cleartext
    byte[] cleartext = "This is just an example".getBytes();

    // Encrypt the cleartext
    byte[] ciphertext = aesCipher.doFinal(cleartext);

    // Initialize the same cipher for decryption
    aesCipher.init(Cipher.DECRYPT_MODE, aesKey);

    // Decrypt the ciphertext
    byte[] cleartext1 = aesCipher.doFinal(ciphertext);

cleartext and cleartext1 are identical.

Using Password-Based Encryption

In this example, we prompt the user for a password from which we derive an encryption key.

It would seem logical to collect and store the password in an object of type java.lang.String. However, here's the caveat: Objects of type String are immutable, i.e., there are no methods defined that allow you to change (overwrite) or zero out the contents of a String after usage. This feature makes String objects unsuitable for storing security sensitive information such as user passwords. You should always collect and store security sensitive information in a char array instead.

For that reason, the javax.crypto.spec.PBEKeySpec class takes (and returns) a password as a char array. See the ReadPassword class in the sample code in Appendix D for one possible way of reading character array passwords from an input stream.

In order to use Password-Based Encryption (PBE) as defined in PKCS5, we have to specify a salt and an iteration count. The same salt and iteration count that are used for encryption must be used for decryption:

        PBEKeySpec pbeKeySpec;
        PBEParameterSpec pbeParamSpec;
        SecretKeyFactory keyFac;

        // Salt
        byte[] salt = {
        (byte)0xc7, (byte)0x73, (byte)0x21, (byte)0x8c,
        (byte)0x7e, (byte)0xc8, (byte)0xee, (byte)0x99
        };

        // Iteration count
        int count = 20;

        // Create PBE parameter set
        pbeParamSpec = new PBEParameterSpec(salt, count);

        // Prompt user for encryption password.
        // Collect user password as char array (using the
        // "readPassword" method from above), and convert
        // it into a SecretKey object, using a PBE key
        // factory.
        System.out.print("Enter encryption password:  ");
        System.out.flush();
        pbeKeySpec = new PBEKeySpec(readPassword(System.in));
        keyFac = SecretKeyFactory.getInstance("PBEWithMD5AndDES");
        SecretKey pbeKey = keyFac.generateSecret(pbeKeySpec);

        // Create PBE Cipher
        Cipher pbeCipher = Cipher.getInstance("PBEWithMD5AndDES");

        // Initialize PBE Cipher with key and parameters
        pbeCipher.init(Cipher.ENCRYPT_MODE, pbeKey, pbeParamSpec);

        // Our cleartext
        byte[] cleartext = "This is another example".getBytes();

        // Encrypt the cleartext
        byte[] ciphertext = pbeCipher.doFinal(cleartext);

Using Key Agreement

Please refer to Appendix D for sample programs exercising the Diffie-Hellman key exchange between 2 and 3 parties.

Appendix A: Standard Names

The JDK Security API requires and uses a set of standard names for algorithms, certificate and keystore types. The specification names previously found here in Appendix A and in the other security specifications (JSSE/CertPath/etc.) have been combined in the Standard Names document. This document also contains more information about the algorithm specifications. Specific provider information can be found in the Sun Provider Documentation.

Cryptographic implementations in the Sun JDK are distributed through several different providers primarily for historical reasons (Sun, SunJSSE, SunJCE, SunRsaSign). Note these providers may not be available on all JDK implementations, and therefore, truly portable applications should call getInstance() without specifying specific providers. Applications specifying a particular provider may not be able to take advantage of native providers tuned for an underlying operating environment (such as PKCS or Microsoft's CAPI).

The SunPKCS11 provider itself does not contain any cryptographic algorithms, but instead, directs requests into an underlying PKCS11 implementation. The PKCS11 Reference Guide and the underlying PKCS11 implementation should be consulted to determine if a desired algorithm will be available through the PKCS11 provider. Likewise, on Windows systems, the SunMSCAPI provider does not provide any cryptographic functionality, but instead routes requests to the underlying Operating System for handling.

Appendix B: Jurisdiction Policy File Format

JCA represents its jurisdiction policy files as Java style policy files with corresponding permission statements. As described in Default Policy Implementation and Policy File Syntax, a Java policy file specifies what permissions are allowed for code from specified code sources. A permission represents access to a system resource. In the case of JCA, the "resources" are cryptography algorithms, and code sources do not need to be specified, because the cryptographic restrictions apply to all code.

A jurisdiction policy file consists of a very basic "grant entry" containing one or more "permission entries."

grant {
    <permission entries>;
};

The format of a permission entry in a jurisdiction policy file is:

permission <crypto permission class name>[ <alg_name>
    [[, <exemption mechanism name>][, <maxKeySize>
    [, <AlgorithmParameterSpec class name>,
    <parameters for constructing an
    AlgorithmParameterSpec object>]]]];

A sample jurisdiction policy file that includes restricting the "Blowfish" algorithm to maximum key sizes of 64 bits is:

    grant {
        permission javax.crypto.CryptoPermission "Blowfish", 64;
    . . .;
    };

A permission entry must begin with the word permission. The <crypto permission class name> in the template above would actually be a specific permission class name, such as javax.crypto.CryptoPermission. A crypto permission class reflects the ability of an application/applet to use certain algorithms with certain key sizes in certain environments. There are two crypto permission classes: CryptoPermission and CryptoAllPermission. The special CryptoAllPermission class implies all cryptography-related permissions, that is, it specifies that there are no cryptography-related restrictions.

The <alg_name>, when utilized, is a quoted string specifying the standard name (see Appendix A) of a cryptography algorithm, such as "DES" or "RSA".

The <exemption mechanism name>, when specified, is a quoted string indicating an exemption mechanism which, if enforced, enables a reduction in cryptographic restrictions. Exemption mechanism names that can be used include "KeyRecovery" "KeyEscrow", and "KeyWeakening".

<maxKeySize> is an integer specifying the maximum key size (in bits) allowed for the specified algorithm.

For some algorithms it may not be sufficient to specify the algorithm strength in terms of just a key size. For example, in the case of the "RC5" algorithm, the number of rounds must also be considered. For algorithms whose strength needs to be expressed as more than a key size, the permission entry should also specify an AlgorithmParameterSpec class name (such as javax.crypto.spec.RC5ParameterSpec) and a list of parameters for constructing the specified AlgorithmParameterSpec object.

Items that appear in a permission entry must appear in the specified order. An entry is terminated with a semicolon.

Case is unimportant for the identifiers (grant, permission) but is significant for the <crypto permission class name> or for any string that is passed in as a value.

NOTE: An "*" can be used as a wildcard for any permission entry option. For example, an "*" (without the quotes) for an <alg_name> option means "all algorithms."

Appendix C: Maximum Key Sizes Allowed by "Strong" Jurisdiction Policy Files

Due to import control restrictions, the jurisdiction policy files shipped with the Java SE Development Kit 6 allow "strong" but limited cryptography to be used. Here are the maximum key sizes allowed by this "strong" version of the jurisdiction policy files:

Algorithm | Maximum Keysize
DES | 64
DESede *
RC2 | 128
RC4 | 128
RC5 | 128
RSA *
all others | 128

Appendix D: Sample Programs

  • Diffie-Hellman Key Exchange between 2 Parties

    /*
 * Copyright 1997-2001 by Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Sun Microsystems, Inc. ("Confidential Information").  You
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with Sun.
 */

import java.io.*;
import java.math.BigInteger;
import java.security.*;
import java.security.spec.*;
import java.security.interfaces.*;
import javax.crypto.*;
import javax.crypto.spec.*;
import javax.crypto.interfaces.*;
import com.sun.crypto.provider.SunJCE;

/**
 * This program executes the Diffie-Hellman key agreement protocol
 * between 2 parties: Alice and Bob.
 *
 * By default, preconfigured parameters (1024-bit prime modulus and base
 * generator used by SKIP) are used.
 * If this program is called with the "-gen" option, a new set of
 * parameters is created.
 */

public class DHKeyAgreement2 {

    private DHKeyAgreement2() {}

    public static void main(String argv[]) {
        try {
            String mode = "USE_SKIP_DH_PARAMS";

            DHKeyAgreement2 keyAgree = new DHKeyAgreement2();

            if (argv.length > 1) {
                keyAgree.usage();
                throw new Exception("Wrong number of command options");
            } else if (argv.length == 1) {
                if (!(argv[0].equals("-gen"))) {
                    keyAgree.usage();
                    throw new Exception("Unrecognized flag: " + argv[0]);
                }
                mode = "GENERATE_DH_PARAMS";
            }

            keyAgree.run(mode);
        } catch (Exception e) {
            System.err.println("Error: " + e);
            System.exit(1);
        }
    }

    private void run(String mode) throws Exception {

        DHParameterSpec dhSkipParamSpec;

        if (mode.equals("GENERATE_DH_PARAMS")) {
            // Some central authority creates new DH parameters
            System.out.println
                ("Creating Diffie-Hellman parameters (takes VERY long) ...");
            AlgorithmParameterGenerator paramGen
                = AlgorithmParameterGenerator.getInstance("DH");
            paramGen.init(512);
            AlgorithmParameters params = paramGen.generateParameters();
            dhSkipParamSpec = (DHParameterSpec)params.getParameterSpec
                (DHParameterSpec.class);
        } else {
            // use some pre-generated, default DH parameters
            System.out.println("Using SKIP Diffie-Hellman parameters");
            dhSkipParamSpec = new DHParameterSpec(skip1024Modulus,
                                                  skip1024Base);
        }

        /*
         * Alice creates her own DH key pair, using the DH parameters from
         * above
         */
        System.out.println("ALICE: Generate DH keypair ...");
        KeyPairGenerator aliceKpairGen = KeyPairGenerator.getInstance("DH");
        aliceKpairGen.initialize(dhSkipParamSpec);
        KeyPair aliceKpair = aliceKpairGen.generateKeyPair();

        // Alice creates and initializes her DH KeyAgreement object
        System.out.println("ALICE: Initialization ...");
        KeyAgreement aliceKeyAgree = KeyAgreement.getInstance("DH");
        aliceKeyAgree.init(aliceKpair.getPrivate());

        // Alice encodes her public key, and sends it over to Bob.
        byte[] alicePubKeyEnc = aliceKpair.getPublic().getEncoded();

        /*
         * Let's turn over to Bob. Bob has received Alice's public key
         * in encoded format.
         * He instantiates a DH public key from the encoded key material.
         */
        KeyFactory bobKeyFac = KeyFactory.getInstance("DH");
        X509EncodedKeySpec x509KeySpec = new X509EncodedKeySpec
            (alicePubKeyEnc);
        PublicKey alicePubKey = bobKeyFac.generatePublic(x509KeySpec);

        /*
         * Bob gets the DH parameters associated with Alice's public key.
         * He must use the same parameters when he generates his own key
         * pair.
         */
        DHParameterSpec dhParamSpec = ((DHPublicKey)alicePubKey).getParams();

        // Bob creates his own DH key pair
        System.out.println("BOB: Generate DH keypair ...");
        KeyPairGenerator bobKpairGen = KeyPairGenerator.getInstance("DH");
        bobKpairGen.initialize(dhParamSpec);
        KeyPair bobKpair = bobKpairGen.generateKeyPair();

        // Bob creates and initializes his DH KeyAgreement object
        System.out.println("BOB: Initialization ...");
        KeyAgreement bobKeyAgree = KeyAgreement.getInstance("DH");
        bobKeyAgree.init(bobKpair.getPrivate());

        // Bob encodes his public key, and sends it over to Alice.
        byte[] bobPubKeyEnc = bobKpair.getPublic().getEncoded();

        /*
         * Alice uses Bob's public key for the first (and only) phase
         * of her version of the DH
         * protocol.
         * Before she can do so, she has to instantiate a DH public key
         * from Bob's encoded key material.
         */
        KeyFactory aliceKeyFac = KeyFactory.getInstance("DH");
        x509KeySpec = new X509EncodedKeySpec(bobPubKeyEnc);
        PublicKey bobPubKey = aliceKeyFac.generatePublic(x509KeySpec);
        System.out.println("ALICE: Execute PHASE1 ...");
        aliceKeyAgree.doPhase(bobPubKey, true);

        /*
         * Bob uses Alice's public key for the first (and only) phase
         * of his version of the DH
         * protocol.
         */
        System.out.println("BOB: Execute PHASE1 ...");
        bobKeyAgree.doPhase(alicePubKey, true);

        /*
         * At this stage, both Alice and Bob have completed the DH key
         * agreement protocol.
         * Both generate the (same) shared secret.
         */
        byte[] aliceSharedSecret = aliceKeyAgree.generateSecret();
        int aliceLen = aliceSharedSecret.length;

        byte[] bobSharedSecret = new byte[aliceLen];
        int bobLen;
        try {
            // show example of what happens if you
            // provide an output buffer that is too short
            bobLen = bobKeyAgree.generateSecret(bobSharedSecret, 1);
        } catch (ShortBufferException e) {
            System.out.println(e.getMessage());
        }
        // provide output buffer of required size
        bobLen = bobKeyAgree.generateSecret(bobSharedSecret, 0);

        System.out.println("Alice secret: " +
          toHexString(aliceSharedSecret));
        System.out.println("Bob secret: " +
          toHexString(bobSharedSecret));

        if (!java.util.Arrays.equals(aliceSharedSecret, bobSharedSecret))
            throw new Exception("Shared secrets differ");
        System.out.println("Shared secrets are the same");

        /*
         * Now let's return the shared secret as a SecretKey object
         * and use it for encryption. First, we generate SecretKeys for the
         * "DES" algorithm (based on the raw shared secret data) and
         * then we use DES in ECB mode
         * as the encryption algorithm. DES in ECB mode does not require any
         * parameters.
         *
         * Then we use DES in CBC mode, which requires an initialization
         * vector (IV) parameter. In CBC mode, you need to initialize the
         * Cipher object with an IV, which can be supplied using the
         * javax.crypto.spec.IvParameterSpec class. Note that you have to use
         * the same IV for encryption and decryption: If you use a different
         * IV for decryption than you used for encryption, decryption will
         * fail.
         *
         * NOTE: If you do not specify an IV when you initialize the
         * Cipher object for encryption, the underlying implementation
         * will generate a random one, which you have to retrieve using the
         * javax.crypto.Cipher.getParameters() method, which returns an
         * instance of java.security.AlgorithmParameters. You need to transfer
         * the contents of that object (e.g., in encoded format, obtained via
         * the AlgorithmParameters.getEncoded() method) to the party who will
         * do the decryption. When initializing the Cipher for decryption,
         * the (reinstantiated) AlgorithmParameters object must be passed to
         * the Cipher.init() method.
         */
        System.out.println("Return shared secret as SecretKey object ...");
        // Bob
        // NOTE: The call to bobKeyAgree.generateSecret above reset the key
        // agreement object, so we call doPhase again prior to another
        // generateSecret call
        bobKeyAgree.doPhase(alicePubKey, true);
        SecretKey bobDesKey = bobKeyAgree.generateSecret("DES");

        // Alice
        // NOTE: The call to aliceKeyAgree.generateSecret above reset the key
        // agreement object, so we call doPhase again prior to another
        // generateSecret call
        aliceKeyAgree.doPhase(bobPubKey, true);
        SecretKey aliceDesKey = aliceKeyAgree.generateSecret("DES");

        /*
         * Bob encrypts, using DES in ECB mode
         */
        Cipher bobCipher = Cipher.getInstance("DES/ECB/PKCS5Padding");
        bobCipher.init(Cipher.ENCRYPT_MODE, bobDesKey);

        byte[] cleartext = "This is just an example".getBytes();
        byte[] ciphertext = bobCipher.doFinal(cleartext);

        /*
         * Alice decrypts, using DES in ECB mode
         */
        Cipher aliceCipher = Cipher.getInstance("DES/ECB/PKCS5Padding");
        aliceCipher.init(Cipher.DECRYPT_MODE, aliceDesKey);
        byte[] recovered = aliceCipher.doFinal(ciphertext);

        if (!java.util.Arrays.equals(cleartext, recovered))
            throw new Exception("DES in CBC mode recovered text is " +
              "different from cleartext");
        System.out.println("DES in ECB mode recovered text is " +
            "same as cleartext");

        /*
         * Bob encrypts, using DES in CBC mode
         */
        bobCipher = Cipher.getInstance("DES/CBC/PKCS5Padding");
        bobCipher.init(Cipher.ENCRYPT_MODE, bobDesKey);

        cleartext = "This is just an example".getBytes();
        ciphertext = bobCipher.doFinal(cleartext);
        // Retrieve the parameter that was used, and transfer it to Alice in
        // encoded format
        byte[] encodedParams = bobCipher.getParameters().getEncoded();

        /*
         * Alice decrypts, using DES in CBC mode
         */
        // Instantiate AlgorithmParameters object from parameter encoding
        // obtained from Bob
        AlgorithmParameters params = AlgorithmParameters.getInstance("DES");
        params.init(encodedParams);
        aliceCipher = Cipher.getInstance("DES/CBC/PKCS5Padding");
        aliceCipher.init(Cipher.DECRYPT_MODE, aliceDesKey, params);
        recovered = aliceCipher.doFinal(ciphertext);

        if (!java.util.Arrays.equals(cleartext, recovered))
            throw new Exception("DES in CBC mode recovered text is " +
              "different from cleartext");
        System.out.println("DES in CBC mode recovered text is " +
            "same as cleartext");
    }

    /*
     * Converts a byte to hex digit and writes to the supplied buffer
     */
    private void byte2hex(byte b, StringBuffer buf) {
        char[] hexChars = { '0', '1', '2', '3', '4', '5', '6', '7', '8',
                            '9', 'A', 'B', 'C', 'D', 'E', 'F' };
        int high = ((b & 0xf0) >> 4);
        int low = (b & 0x0f);
        buf.append(hexChars[high]);
        buf.append(hexChars[low]);
    }

    /*
     * Converts a byte array to hex string
     */
    private String toHexString(byte[] block) {
        StringBuffer buf = new StringBuffer();

        int len = block.length;

        for (int i = 0; i < len; i++) {
             byte2hex(block[i], buf);
             if (i < len-1) {
                 buf.append(":");
             }
        }
        return buf.toString();
    }

    /*
     * Prints the usage of this test.
     */
    private void usage() {
        System.err.print("DHKeyAgreement usage: ");
        System.err.println("[-gen]");
    }

    // The 1024 bit Diffie-Hellman modulus values used by SKIP
    private static final byte skip1024ModulusBytes[] = {
        (byte)0xF4, (byte)0x88, (byte)0xFD, (byte)0x58,
        (byte)0x4E, (byte)0x49, (byte)0xDB, (byte)0xCD,
        (byte)0x20, (byte)0xB4, (byte)0x9D, (byte)0xE4,
        (byte)0x91, (byte)0x07, (byte)0x36, (byte)0x6B,
        (byte)0x33, (byte)0x6C, (byte)0x38, (byte)0x0D,
        (byte)0x45, (byte)0x1D, (byte)0x0F, (byte)0x7C,
        (byte)0x88, (byte)0xB3, (byte)0x1C, (byte)0x7C,
        (byte)0x5B, (byte)0x2D, (byte)0x8E, (byte)0xF6,
        (byte)0xF3, (byte)0xC9, (byte)0x23, (byte)0xC0,
        (byte)0x43, (byte)0xF0, (byte)0xA5, (byte)0x5B,
        (byte)0x18, (byte)0x8D, (byte)0x8E, (byte)0xBB,
        (byte)0x55, (byte)0x8C, (byte)0xB8, (byte)0x5D,
        (byte)0x38, (byte)0xD3, (byte)0x34, (byte)0xFD,
        (byte)0x7C, (byte)0x17, (byte)0x57, (byte)0x43,
        (byte)0xA3, (byte)0x1D, (byte)0x18, (byte)0x6C,
        (byte)0xDE, (byte)0x33, (byte)0x21, (byte)0x2C,
        (byte)0xB5, (byte)0x2A, (byte)0xFF, (byte)0x3C,
        (byte)0xE1, (byte)0xB1, (byte)0x29, (byte)0x40,
        (byte)0x18, (byte)0x11, (byte)0x8D, (byte)0x7C,
        (byte)0x84, (byte)0xA7, (byte)0x0A, (byte)0x72,
        (byte)0xD6, (byte)0x86, (byte)0xC4, (byte)0x03,
        (byte)0x19, (byte)0xC8, (byte)0x07, (byte)0x29,
        (byte)0x7A, (byte)0xCA, (byte)0x95, (byte)0x0C,
        (byte)0xD9, (byte)0x96, (byte)0x9F, (byte)0xAB,
        (byte)0xD0, (byte)0x0A, (byte)0x50, (byte)0x9B,
        (byte)0x02, (byte)0x46, (byte)0xD3, (byte)0x08,
        (byte)0x3D, (byte)0x66, (byte)0xA4, (byte)0x5D,
        (byte)0x41, (byte)0x9F, (byte)0x9C, (byte)0x7C,
        (byte)0xBD, (byte)0x89, (byte)0x4B, (byte)0x22,
        (byte)0x19, (byte)0x26, (byte)0xBA, (byte)0xAB,
        (byte)0xA2, (byte)0x5E, (byte)0xC3, (byte)0x55,
        (byte)0xE9, (byte)0x2F, (byte)0x78, (byte)0xC7
    };

    // The SKIP 1024 bit modulus
    private static final BigInteger skip1024Modulus
    = new BigInteger(1, skip1024ModulusBytes);

    // The base used with the SKIP 1024 bit modulus
    private static final BigInteger skip1024Base = BigInteger.valueOf(2);
}

  • Diffie-Hellman Key Exchange between 3 Parties

    /*
 * Copyright 1997-2001 by Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Sun Microsystems, Inc. ("Confidential Information").  You
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with Sun.
 */

import java.io.*;
import java.math.BigInteger;
import java.security.*;
import java.security.spec.*;
import java.security.interfaces.*;
import javax.crypto.*;
import javax.crypto.spec.*;
import javax.crypto.interfaces.*;
import com.sun.crypto.provider.SunJCE;

/**
 * This program executes the Diffie-Hellman key agreement protocol
 * between 3 parties: Alice, Bob, and Carol.
 *
 * We use the same 1024-bit prime modulus and base generator that are
 * used by SKIP.
 */

public class DHKeyAgreement3 {

    private DHKeyAgreement3() {}

    public static void main(String argv[]) {
        try {
            DHKeyAgreement3 keyAgree = new DHKeyAgreement3();
            keyAgree.run();
        } catch (Exception e) {
            System.err.println("Error: " + e);
            System.exit(1);
        }
    }

    private void run() throws Exception {

        DHParameterSpec dhSkipParamSpec;

        System.out.println("Using SKIP Diffie-Hellman parameters");
        dhSkipParamSpec = new DHParameterSpec(skip1024Modulus, skip1024Base);

        // Alice creates her own DH key pair
        System.out.println("ALICE: Generate DH keypair ...");
        KeyPairGenerator aliceKpairGen = KeyPairGenerator.getInstance("DH");
        aliceKpairGen.initialize(dhSkipParamSpec);
        KeyPair aliceKpair = aliceKpairGen.generateKeyPair();

        // Bob creates his own DH key pair
        System.out.println("BOB: Generate DH keypair ...");
        KeyPairGenerator bobKpairGen = KeyPairGenerator.getInstance("DH");
        bobKpairGen.initialize(dhSkipParamSpec);
        KeyPair bobKpair = bobKpairGen.generateKeyPair();

        // Carol creates her own DH key pair
        System.out.println("CAROL: Generate DH keypair ...");
        KeyPairGenerator carolKpairGen = KeyPairGenerator.getInstance("DH");
        carolKpairGen.initialize(dhSkipParamSpec);
        KeyPair carolKpair = carolKpairGen.generateKeyPair();

        // Alice initialize
        System.out.println("ALICE: Initialize ...");
        KeyAgreement aliceKeyAgree = KeyAgreement.getInstance("DH");
        aliceKeyAgree.init(aliceKpair.getPrivate());

        // Bob initialize
        System.out.println("BOB: Initialize ...");
        KeyAgreement bobKeyAgree = KeyAgreement.getInstance("DH");
        bobKeyAgree.init(bobKpair.getPrivate());

        // Carol initialize
        System.out.println("CAROL: Initialize ...");
        KeyAgreement carolKeyAgree = KeyAgreement.getInstance("DH");
        carolKeyAgree.init(carolKpair.getPrivate());

        // Alice uses Carol's public key
        Key ac = aliceKeyAgree.doPhase(carolKpair.getPublic(), false);

        // Bob uses Alice's public key
        Key ba = bobKeyAgree.doPhase(aliceKpair.getPublic(), false);

        // Carol uses Bob's public key
        Key cb = carolKeyAgree.doPhase(bobKpair.getPublic(), false);

        // Alice uses Carol's result from above
        aliceKeyAgree.doPhase(cb, true);

        // Bob uses Alice's result from above
        bobKeyAgree.doPhase(ac, true);

        // Carol uses Bob's result from above
        carolKeyAgree.doPhase(ba, true);

        // Alice, Bob and Carol compute their secrets
        byte[] aliceSharedSecret = aliceKeyAgree.generateSecret();
        System.out.println("Alice secret: " + toHexString(aliceSharedSecret));

        byte[] bobSharedSecret = bobKeyAgree.generateSecret();
        System.out.println("Bob secret: " + toHexString(bobSharedSecret));

        byte[] carolSharedSecret = carolKeyAgree.generateSecret();
        System.out.println("Carol secret: " + toHexString(carolSharedSecret));

        // Compare Alice and Bob
        if (!java.util.Arrays.equals(aliceSharedSecret, bobSharedSecret))
            throw new Exception("Alice and Bob differ");
        System.out.println("Alice and Bob are the same");

        // Compare Bob and Carol
        if (!java.util.Arrays.equals(bobSharedSecret, carolSharedSecret))
            throw new Exception("Bob and Carol differ");
        System.out.println("Bob and Carol are the same");
    }

    /*
     * Converts a byte to hex digit and writes to the supplied buffer
     */
    private void byte2hex(byte b, StringBuffer buf) {
        char[] hexChars = { '0', '1', '2', '3', '4', '5', '6', '7', '8',
                            '9', 'A', 'B', 'C', 'D', 'E', 'F' };
        int high = ((b & 0xf0) >> 4);
        int low = (b & 0x0f);
        buf.append(hexChars[high]);
        buf.append(hexChars[low]);
    }

    /*
     * Converts a byte array to hex string
     */
    private String toHexString(byte[] block) {
        StringBuffer buf = new StringBuffer();

        int len = block.length;

        for (int i = 0; i < len; i++) {
             byte2hex(block[i], buf);
             if (i < len-1) {
                 buf.append(":");
             }
        }
        return buf.toString();
    }

    /*
     * Prints the usage of this test.
     */
    private void usage() {
        System.err.print("DHKeyAgreement usage: ");
        System.err.println("[-gen]");
    }

    // The 1024 bit Diffie-Hellman modulus values used by SKIP
    private static final byte skip1024ModulusBytes[] = {
        (byte)0xF4, (byte)0x88, (byte)0xFD, (byte)0x58,
        (byte)0x4E, (byte)0x49, (byte)0xDB, (byte)0xCD,
        (byte)0x20, (byte)0xB4, (byte)0x9D, (byte)0xE4,
        (byte)0x91, (byte)0x07, (byte)0x36, (byte)0x6B,
        (byte)0x33, (byte)0x6C, (byte)0x38, (byte)0x0D,
        (byte)0x45, (byte)0x1D, (byte)0x0F, (byte)0x7C,
        (byte)0x88, (byte)0xB3, (byte)0x1C, (byte)0x7C,
        (byte)0x5B, (byte)0x2D, (byte)0x8E, (byte)0xF6,
        (byte)0xF3, (byte)0xC9, (byte)0x23, (byte)0xC0,
        (byte)0x43, (byte)0xF0, (byte)0xA5, (byte)0x5B,
        (byte)0x18, (byte)0x8D, (byte)0x8E, (byte)0xBB,
        (byte)0x55, (byte)0x8C, (byte)0xB8, (byte)0x5D,
        (byte)0x38, (byte)0xD3, (byte)0x34, (byte)0xFD,
        (byte)0x7C, (byte)0x17, (byte)0x57, (byte)0x43,
        (byte)0xA3, (byte)0x1D, (byte)0x18, (byte)0x6C,
        (byte)0xDE, (byte)0x33, (byte)0x21, (byte)0x2C,
        (byte)0xB5, (byte)0x2A, (byte)0xFF, (byte)0x3C,
        (byte)0xE1, (byte)0xB1, (byte)0x29, (byte)0x40,
        (byte)0x18, (byte)0x11, (byte)0x8D, (byte)0x7C,
        (byte)0x84, (byte)0xA7, (byte)0x0A, (byte)0x72,
        (byte)0xD6, (byte)0x86, (byte)0xC4, (byte)0x03,
        (byte)0x19, (byte)0xC8, (byte)0x07, (byte)0x29,
        (byte)0x7A, (byte)0xCA, (byte)0x95, (byte)0x0C,
        (byte)0xD9, (byte)0x96, (byte)0x9F, (byte)0xAB,
        (byte)0xD0, (byte)0x0A, (byte)0x50, (byte)0x9B,
        (byte)0x02, (byte)0x46, (byte)0xD3, (byte)0x08,
        (byte)0x3D, (byte)0x66, (byte)0xA4, (byte)0x5D,
        (byte)0x41, (byte)0x9F, (byte)0x9C, (byte)0x7C,
        (byte)0xBD, (byte)0x89, (byte)0x4B, (byte)0x22,
        (byte)0x19, (byte)0x26, (byte)0xBA, (byte)0xAB,
        (byte)0xA2, (byte)0x5E, (byte)0xC3, (byte)0x55,
        (byte)0xE9, (byte)0x2F, (byte)0x78, (byte)0xC7
    };

    // The SKIP 1024 bit modulus
    private static final BigInteger skip1024Modulus
    = new BigInteger(1, skip1024ModulusBytes);

    // The base used with the SKIP 1024 bit modulus
    private static final BigInteger skip1024Base = BigInteger.valueOf(2);
}

  • Blowfish Cipher Example

    /*
 * Copyright 1997-2001 by Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Sun Microsystems, Inc. ("Confidential Information").  You
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with Sun.
 */

import java.security.*;
import javax.crypto.*;
import javax.crypto.spec.*;

/**
 * This program generates a Blowfish key, retrieves its raw bytes, and
 * then reinstantiates a Blowfish key from the key bytes.
 * The reinstantiated key is used to initialize a Blowfish cipher for
 * encryption.
 */

public class BlowfishKey {

    public static void main(String[] args) throws Exception {

        KeyGenerator kgen = KeyGenerator.getInstance("Blowfish");
        SecretKey skey = kgen.generateKey();
        byte[] raw = skey.getEncoded();
        SecretKeySpec skeySpec = new SecretKeySpec(raw, "Blowfish");

        Cipher cipher = Cipher.getInstance("Blowfish");
        cipher.init(Cipher.ENCRYPT_MODE, skeySpec);
        byte[] encrypted =
            cipher.doFinal("This is just an example".getBytes());
    }
}

  • HMAC-MD5 Example

    /*
 * Copyright 1997-2001 by Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Sun Microsystems, Inc. ("Confidential Information").  You
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with Sun.
 */

import java.security.*;
import javax.crypto.*;

/**
 * This program demonstrates how to generate a secret-key object for
 * HMAC-MD5, and initialize an HMAC-MD5 object with it.
 */

public class initMac {

    public static void main(String[] args) throws Exception {

        // Generate secret key for HMAC-MD5
        KeyGenerator kg = KeyGenerator.getInstance("HmacMD5");
        SecretKey sk = kg.generateKey();

        // Get instance of Mac object implementing HMAC-MD5, and
        // initialize it with the above secret key
        Mac mac = Mac.getInstance("HmacMD5");
        mac.init(sk);
        byte[] result = mac.doFinal("Hi There".getBytes());
    }
}

  • Reading ASCII Passwords From an InputStream Example

    /*
 * @(#)ReadPassword.java  1.1 06/06/07
 *
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

import java.util.*;
import java.io.*;
import java.security.*;

public class ReadPassword {
    /**
     * Read a password from the InputStream "in".
     * <p>
     * As Strings are immutable, passwords should be stored as an array
     * of characters, which can be blanked out when no longer needed.
     * <p>
     * If the provided InputStream is the System's Console, this method
     * uses the non-echoing readPassword() method of java.io.Console
     * (new to JDK 6).  If not, a fallback implementation is used.
     * <p>
     * NOTE:  For expository purposes, and because some applications do
     * not understand multi-byte characters, only 8-bit ASCII passwords
     * are handled here.
     * <p>
     * NOTE:  If a SecurityManager is used, the default standard
     * java.policy file found in Sun's JDK (i.e.
     * /lib/security/java.policy) allows reading the
     * line.separator property.  If your environment is different, this
     * code will need to be granted the appropriate privilege.
     *
     * @param	in
     *		the InputStream used to obtain the password.
     *
     * @return	A character array containing the password or passphrase,
     *		not including the line-termination characters,
     *		or null if an end of stream has been reached.
     *
     * @throws	IOException
     *		if an I/O problem occurs
     */
    public static final char[] readPassword(InputStream in)
        throws IOException {

    /*
     * If available, directly use the java.io.Console class to
     * avoid character echoing.
     */
    if (in == System.in && System.console() != null) {
        // readPassword returns "" if you just print ENTER,
        return System.console().readPassword();
    }

    /*
     * If a console is not available, read the InputStream
     * directly.  This approach may cause password echoing.
     *
     * Since different operating systems have different End-Of-Line
     * (EOL) sequences, this algorithm should allow for
     * platform-independent implementations.  Typical EOL sequences
     * are a single line feed ('\n'), or a carriage return/linefeed
     * combination ('\r\n').  However, some OS's use a single
     * a carriage return ('\r'), which complicates portability.
     *
     * Since we may not have the ability to push bytes back into the
     * InputStream, another approach is used here.  The javadoc for
     * java.lang.System.getProperties() specifies that
     * the set of system properties will contain a system-specific
     * value for the "line.separator".  Scan for this character
     * sequence instead of hard-coding a particular sequence.
     */

    /*
     * Enclose the getProperty in a doPrivileged block to minimize
     * the call stack permission required.
     */
    char [] EOL = AccessController.doPrivileged(
        new PrivilegedAction() {
        public char[] run() {
            String s = System.getProperty("line.separator");
            // Shouldn't happen.
            if (s == null) {
            throw new RuntimeException(
                "line.separator not defined");
            }
            return s.toCharArray();
        }
        });

    char [] buffer = new char[128];
    try {
        int len = 0;		// len of data in buffer.
        boolean done = false;	// found the EOL sequence
        int b;			// byte read

        while (!done) {
        /*
         * realloc if necessary
         */
        if (len >= buffer.length) {
            char [] newbuffer = new char[len + 128];
            System.arraycopy(buffer, 0, newbuffer, 0, len);
            Arrays.fill(buffer, ' ');
            buffer = newbuffer;
        }

        /*
         * End-of-Stream?
         */
        if ((b = in.read()) == -1) {
            // Return as much as we have, null otherwise.
            if (len == 0) {
            return null;
            }
            break;
        } else {
            /*
             * NOTE:  In the simple PBE example here,
             * only 8 bit ASCII characters are handled.
             */
            buffer[len++] = (char) b;
        }

        /*
         * check for the EOL sequence.  Do we have enough bytes?
         */
        if (len >= EOL.length) {
            int i = 0;
            for (i = 0; i < EOL.length; i++) {
            if (buffer[len - EOL.length + i] != EOL[i]) {
                break;
            }
            }
            done = (i == EOL.length);
        }
        }

        /*
         * If we found the EOL, strip the EOL chars.
         */
        char [] result = new char[done ? len - EOL.length : len];
        System.arraycopy(buffer, 0, result, 0, result.length);

        return result;
    } finally {
        /*
         * Zero out the buffer.
         */
        if (buffer != null) {
        Arrays.fill(buffer, ' ');
        }
    }
    }
}


JAAS

LoginModule Developer's Guide

JavaTM Authentication and Authorization Service (JAAS)

LoginModule Developer's Guide

Overview
Who Should Read This Document
Related Documentation
Introduction

Steps to Implement a LoginModule
Step 1: Understand the Authentication Technology
Step 2: Name the LoginModule Implementation
Step 3: Implement the Abstract LoginModule Methods
Step 4: Choose or Write a Sample Application
Step 5: Compile the LoginModule and Application
Step 6: Prepare for Testing
Step 7: Test Use of the LoginModule
Step 8: Document Your LoginModule Implementation
Step 9: Make LoginModule JAR File and Documents Available

Overview

The JavaTM Authentication and Authorization Service (JAAS) was introduced as an optional package to the JavaTM 2 SDK, Standard Edition (J2SDK), v 1.3. JAAS was integrated into the Java TM Standard Edition Development Kit starting with J2SDK 1.4.

JAAS provides subject-based authorization on authenticated identities. This document focuses on the authentication aspect of JAAS, specifically the LoginModule interface.

Who Should Read This Document

This document is intended for experienced programmers who require the ability to write a LoginModule implementing an authentication technology.

Related Documentation

This document assumes you have already read the following:

  • JAAS Reference Guide

It also discusses various classes and interfaces in the JAAS API. Please reference the javadocs for the JAAS API specification for more detailed information:

  • javax.security.auth Package
  • javax.security.auth.callback Package
  • javax.security.auth.kerberos Package
  • javax.security.auth.login Package
  • javax.security.auth.spi Package
  • javax.security.auth.x500 Package
  • com.sun.security.auth Package
  • com.sun.security.auth.callback Package
  • com.sun.security.auth.login Package
  • com.sun.security.auth.module Package

The following tutorials for JAAS authentication and authorization can be run by everyone:

  • JAAS Authentication Tutorial
  • JAAS Authorization Tutorial

Similar tutorials for JAAS authentication and authorization, but which demonstrate the use of a Kerberos LoginModule and thus which require a Kerberos installation, can be found at

  • JAAS Authentication
  • JAAS Authorization

These two tutorials are a part of the Java GSS-API and JAAS sequence of tutorials that utilize Kerberos as the underlying technology for authentication and secure communication.

Introduction

The LoginModule documentation describes the interface that must be implemented by authentication technology providers. LoginModules are plugged in under applications to provide a particular type of authentication.

While applications write to the LoginContext Application Programming Interface (API), authentication technology providers implement the LoginModule interface. A Configuration specifies the LoginModule(s) to be used with a particular login application. Different LoginModules can be plugged in under the application without requiring any modifications to the application itself.

The LoginContext is responsible for reading the Configuration and instantiating the specified LoginModules. Each LoginModule is initialized with a Subject, a CallbackHandler, shared LoginModule state, and LoginModule-specific options.

The Subject represents the user or service currently being authenticated and is updated by a LoginModule with relevant Principals and credentials if authentication succeeds. LoginModules use the CallbackHandler to communicate with users (to prompt for user names and passwords, for example), as described in the login method description. Note that the CallbackHandler may be null. A LoginModule that requires a CallbackHandler to authenticate the Subject may throw a LoginException if it was initialized with a null CallbackHandler. LoginModules optionally use the shared state to share information or data among themselves.

The LoginModule-specific options represent the options configured for this LoginModule in the login Configuration. The options are defined by the LoginModule itself and control the behavior within it. For example, a LoginModule may define options to support debugging/testing capabilities. Options are defined using a key-value syntax, such as debug=true. The LoginModule stores the options as a Map so that the values may be retrieved using the key. Note that there is no limit to the number of options a LoginModule chooses to define.

The calling application sees the authentication process as a single operation invoked via a call to the LoginContext's login method. However, the authentication process within each LoginModule proceeds in two distinct phases. In the first phase of authentication, the LoginContext's login method invokes the login method of each LoginModule specified in the Configuration. The login method for a LoginModule performs the actual authentication (prompting for and verifying a password for example) and saves its authentication status as private state information. Once finished, the LoginModule's login method returns true (if it succeeded) or false (if it should be ignored), or it throws a LoginException to specify a failure. In the failure case, the LoginModule must not retry the authentication or introduce delays. The responsibility of such tasks belongs to the application. If the application attempts to retry the authentication, each LoginModule's login method will be called again.

In the second phase, if the LoginContext's overall authentication succeeded (calls to the relevant required, requisite, sufficient and optional LoginModules' login methods succeeded), then the commit method for each LoginModule gets invoked. (For an explanation of the LoginModule flags required, requisite, sufficient and optional, please consult the javax.security.auth.login.Configuration documentation and Appendix B: Login Configuration Files in the JAAS Reference Guide.) The commit method for a LoginModule checks its privately saved state to see if its own authentication succeeded. If the overall LoginContext authentication succeeded and the LoginModule's own authentication succeeded, then the commit method associates the relevant Principals (authenticated identities) and credentials (authentication data such as cryptographic keys) with the Subject.

If the LoginContext's overall authentication failed (the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules' login methods did not succeed), then the abort method for each LoginModule gets invoked. In this case, the LoginModule removes/destroys any authentication state originally saved.

Logging out a Subject involves only one phase. The LoginContext invokes the LoginModule's logout method. The logout method for the LoginModule then performs the logout procedures, such as removing Principals or credentials from the Subject, or logging session information.

Steps to Implement a LoginModule

The steps required in order to implement and test a LoginModule are the following:

Step 1: Understand the Authentication Technology
Step 2: Name the LoginModule Implementation
Step 3: Implement the Abstract LoginModule Methods
Step 4: Choose or Write a Sample Application
Step 5: Compile the LoginModule and Application
Step 6: Prepare for Testing
Step 6a: Place Your LoginModule and Application Code in JAR Files
Step 6b: Decide Where to Store the JAR Files
Step 6c: Set LoginModule and Application JAR File Permissions
Step 6d: Create a Configuration Referencing the LoginModule
Step 7: Test Use of the LoginModule
Step 8: Document Your LoginModule Implementation
Step 9: Make LoginModule JAR File and Documents Available

The steps required to implement and test a new LoginModule follow. Please reference the SampleLoginModule and other files described in the JAAS Reference Guide for examples of what may be done for the various steps.

Step 1: Understand the Authentication Technology

The first thing you need to do is understand the authentication technology to be implemented by your new LoginModule provider, and determine its requirements.

One thing you will need to determine is whether or not your LoginModule will require some form of user interaction (retrieving a user name and password, for example). If so, you will need to become familiar with the CallbackHandler interface and the javax.security.auth.callback package. In that package you will find several possible Callback implementations to use. (Alternatively, you can create your own Callback implementations.) The LoginModule will invoke the CallbackHandler specified by the application itself and passed to the LoginModule's initialize method. The LoginModule passes the CallbackHandler an array of appropriate Callbacks. See the login method in Step 3.

Note that it is possible for LoginModule implementations not to have any end-user interactions. Such LoginModules would not need to access the callback package.

Another thing you should determine is what configuration options you want to make available to the user, who specifies configuration information in whatever form the current Configuration implementation expects (for example, in files). For each option, decide the option name and possible values. For example, if a LoginModule may be configured to consult a particular authentication server host, decide on the option's key name ("auth_server", for example), as well as the possible server hostnames valid for that option ("server_one.foo.com" and "server_two.foo.com", for example).

Step 2: Name the LoginModule Implementation

Decide on the proper package and class name for your LoginModule.

For example, a LoginModule developed by IBM might be called com.ibm.auth.Module where com.ibm.auth is the package name and Module is the name of the LoginModule class implementation.

Step 3: Implement the Abstract LoginModule Methods

The LoginModule interface specifies five abstract methods that require implementations:

  • initialize
  • login
  • commit
  • abort
  • logout
See below and the LoginModule API for more information on each method above.

In addition to these methods, a LoginModule implementation must provide a public constructor with no arguments. This allows for its proper instantiation by a LoginContext. Note that if no such constructor is provided in your LoginModule implementation, a default no-argument constructor is automatically inherited from the Object class.

public void initialize (Subject subject,
CallbackHandler handler,
Map<java.lang.String, ?> sharedState,
Map<java.lang.String, ?> options) { ... }

The initialize method is called to initialize the LoginModule with the relevant authentication and state information.

This method is called by a LoginContext immediately after this LoginModule has been instantiated, and prior to any calls to its other public methods. The method implementation should store away the provided arguments for future use.

The initialize method may additionally peruse the provided sharedState to determine what additional authentication state it was provided by other LoginModules, and may also traverse through the provided options to determine what configuration options were specified to affect the LoginModule's behavior. It may save option values in variables for future use.

Note: JAAS LoginModules may use the options defined in PAM (use_first_pass, try_first_pass, use_mapped_pass, and try_mapped_pass) to achieve single-signon. See Making Login Services Independent from Authentication Technologies for further information.

Below is a list of options commonly supported by LoginModules. Note that the following is simply a guideline. Modules are free to support a subset (or none) of the following options.

  • try_first_pass - If true, the first LoginModule in the stack saves the password entered, and subsequent LoginModules also try to use it. If authentication fails, the LoginModules prompt for a new password and retry the authentication.

  • use_first_pass - If true, the first LoginModule in the stack saves the password entered, and subsequent LoginModules also try to use it. LoginModules do not prompt for a new password if authentication fails (authentication simply fails).

  • try_mapped_pass - If true, the first LoginModule in the stack saves the password entered, and subsequent LoginModules attempt to map it into their service-specific password. If authentication fails, the LoginModules prompt for a new password and retry the authentication.

  • use_mapped_pass - If true, the first LoginModule in the stack saves the password entered, and subsequent LoginModules attempt to map it into their service-specific password. LoginModules do not prompt for a new password if authentication fails (authentication simply fails).

  • moduleBanner - If true, then when invoking the CallbackHandler, the LoginModule provides a TextOutputCallback as the first Callback, which describes the LoginModule performing the authentication.

  • debug - If true, instructs a LoginModule to output debugging information.

The initialize method may freely ignore state or options it does not understand, although it would be wise to log such an event if it does occur.

Note that the LoginContext invoking this LoginModule (and the other configured LoginModules, as well), all share the same references to the provided Subject and sharedState. Modifications to the Subject and sharedState will, therefore, be seen by all.

boolean login() throws LoginException;

The login method is called to authenticate a Subject. This is phase 1 of authentication.

This method implementation should perform the actual authentication. For example, it may cause prompting for a user name and password, and then attempt to verify the password against a password database. Another example implementation may inform the user to insert their finger into a fingerprint reader, and then match the input fingerprint against a fingerprint database.

If your LoginModule requires some form of user interaction (retrieving a user name and password, for example), it should not do so directly. That is because there are various ways of communicating with a user, and it is desirable for LoginModules to remain independent of the different types of user interaction. Rather, the LoginModule's login method should invoke the handle method of the the CallbackHandler passed to the initialize method to perform the user interaction and set appropriate results, such as the user name and password. The LoginModule passes the CallbackHandler an array of appropriate Callbacks, for example a NameCallback for the user name and a PasswordCallback for the password, and the CallbackHandler performs the requested user interaction and sets appropriate values in the Callbacks. For example, to process a NameCallback, the CallbackHandler may prompt for a name, retrieve the value from the user, and call the NameCallback's setName method to store the name.

The authentication process may also involve communication over a network. For example, if this method implementation performs the equivalent of a kinit in Kerberos, then it would need to contact the KDC. If a password database entry itself resides in a remote naming service, then that naming service needs to be contacted, perhaps via the Java Naming and Directory Interface (JNDI). Implementations might also interact with an underlying operating system. For example, if a user has already logged into an operating system like Solaris or Windows NT, this method might simply import the underlying operating system's identity information.

The login method should

  1. Determine whether or not this LoginModule should be ignored. One example of when it should be ignored is when a user attempts to authenticate under an identity irrelevant to this LoginModule (if a user attempts to authenticate as root using NIS, for example). If this LoginModule should be ignored, login should return false. Otherwise, it should do the following:

  2. Call the CallbackHandler handle method if user interaction is required.

  3. Perform the authentication.

  4. Store the authentication result (success or failure).

  5. If authentication succeeded, save any relevant state information that may be needed by the commit method.

  6. Return true if authentication succeeds, or throw a LoginException such as FailedLoginException if authentication fails.

Note that the login method implementation should not associate any new Principal or credential information with the saved Subject object. This method merely performs the authentication, and then stores away the authentication result and corresponding authentication state. This result and state will later be accessed by the commit or abort method. Note that the result and state should typically not be saved in the sharedState Map, as they are not intended to be shared with other LoginModules.

An example of where this method might find it useful to store state information in the sharedState Map is when LoginModules are configured to share passwords. In this case, the entered password would be saved as shared state. By sharing passwords, the user only enters the password once, and can still be authenticated to multiple LoginModules. The standard conventions for saving and retrieving names and passwords from the sharedState Map are the following:

  • javax.security.auth.login.name - Use this as the shared state map key for saving/retrieving a name.

  • javax.security.auth.login.password - Use this as the shared state map key for saving/retrieving a password.

If authentication fails, the login method should not retry the authentication. This is the responsibility of the application. Multiple LoginContext login method calls by an application are preferred over multiple login attempts from within LoginModule.login().

boolean commit() throws LoginException;

The commit method is called to commit the authentication process. This is phase 2 of authentication when phase 1 succeeds. It is called if the LoginContext's overall authentication succeeded (that is, if the relevant REQUIRED, REQUISITE, SUFFICIENT and OPTIONAL LoginModules succeeded.)

This method should access the authentication result and corresponding authentication state saved by the login method.

If the authentication result denotes that the login method failed, then this commit method should remove/destroy any corresponding state that was originally saved.

If the saved result instead denotes that this LoginModule's login method succeeded, then the corresponding state information should be accessed to build any relevant Principal and credential information. Such Principals and credentials should then be added to the Subject stored away by the initialize method.

After adding Principals and credentials, dispensable state fields should be destroyed expeditiously. Likely fields to destroy would be user names and passwords stored during the authentication process.

The commit method should save private state indicating whether the commit succeeded or failed.

The following chart depicts what a LoginModule's commit method should return. The different boxes represent the different situations that may occur. For example, the top-left corner box depicts what the commit method should return if both the previous call to login succeeded and the commit method itself succeeded.

     \
LOGIN \ COMMIT
       \
        \   SUCCESS          FAILURE
        +--------------+-----------------+
        |              |                 |
SUCCESS | return TRUE  | throw EXCEPTION |
        |              |                 |
        +--------------+-----------------+
        |              |                 |
FAILURE | return FALSE | return FALSE    |
        |              |                 |
        +--------------+-----------------+

boolean abort() throws LoginException;

The abort method is called to abort the authentication process. This is phase 2 of authentication when phase 1 fails. It is called if the LoginContext's overall authentication failed.

This method first accesses this LoginModule's authentication result and corresponding authentication state saved by the login (and possibly commit) methods, and then clears out and destroys the information. Sample state to destroy would be user names and passwords.

If this LoginModule's authentication attempt failed, then there shouldn't be any private state to clean up.

The following charts depict what a LoginModule's abort method should return. This first chart assumes that the previous call to login succeeded. For instance, the top-left corner box depicts what the abort method should return if both the previous call to login and commit succeeded, and the abort method itself also succeeded.

      \
COMMIT \ ABORT (assumes LOGIN method succeeded)
        \
         \   SUCCESS         FAILURE
        +--------------+-----------------+
        |              |                 |
SUCCESS | return TRUE  | throw EXCEPTION |
        |              |                 |
        +--------------+-----------------+
        |              |                 |
FAILURE | return TRUE  | throw EXCEPTION |
        |              |                 |
        +--------------+-----------------+

The second chart depicts what a LoginModule's abort method should return, assuming that the previous call to login failed. For instance, the top-left corner box depicts what the abort method should return if the previous call to login failed, the previous call to commit succeeded, and the abort method itself also succeeded.

      \
COMMIT \ ABORT (assumes LOGIN method failed)
        \
         \   SUCCESS         FAILURE
        +--------------+-----------------+
        |              |                 |
SUCCESS | return FALSE | return FALSE    |
        |              |                 |
        +--------------+-----------------+
        |              |                 |
FAILURE | return FALSE | return FALSE    |
        |              |                 |
        +--------------+-----------------+

boolean logout() throws LoginException;

The logout method is called to log out a Subject.

This method removes Principals, and removes/destroys credentials associated with the Subject during the commit operation. This method should not touch those Principals or credentials previously existing in the Subject, or those added by other LoginModules.

If the Subject has been marked read-only (the Subject's isReadOnly method returns true), then this method should only destroy credentials associated with the Subject during the commit operation (removing the credentials is not possible). If the Subject has been marked as read-only and the credentials associated with the Subject during the commit operation are not destroyable (they do not implement the Destroyable interface), then this method may throw a LoginException.

The logout method should return true if logout succeeds, or otherwise throw a LoginException.

Step 4: Choose or Write a Sample Application

Either choose an existing sample application for your testing, or write a new one. See JAAS Reference Guide for information about application requirements and a sample application you can use for your testing.

Step 5: Compile the LoginModule and Application

Compile your new LoginModule and the application you will use for testing.

Step 6: Prepare for Testing

Step 6a: Place Your LoginModule and Application Code in JAR Files

Place your LoginModule and application code in separate JAR files, in preparation for referencing the JAR files in the policy in Step 6c. Here is a sample command for creating a JAR file:

jar cvf <JAR file name> <list of classes, separated by spaces>

This command creates a JAR file with the specified name containing the specified classes.

For more information on the jar tool, see jar (for Solaris) (for Microsoft Windows).

Step 6b: Decide Where to Store the JAR Files

The application can be stored essentially anywhere you like.

Your LoginModule can also be placed anywhere you (and other clients) like. If the LoginModule is fully trusted, it can be placed in the JRE's lib/ext (standard extension) directory.

You will need to test the LoginModule being located both in the lib/ext directory and elsewhere because in one situation your LoginModule will need to explicitly be granted permissions required for any security-sensitive operations it does, while in the other case such permissions are not needed.

If your LoginModule is placed in the JRE's lib/ext directory, it will be treated as an installed extension and no permissions need to be granted, since the default system policy file grants all permissions to installed extensions.

If your LoginModule is placed anywhere else, the permissions need to be granted, for example by grant statements in a policy file.

Decide where you will store the LoginModule JAR file for testing the case where it is not an installed extension. In the next step, you grant permissions to the JAR file, in the specified location.

Step 6c: Set LoginModule and Application JAR File Permissions

If your LoginModule and/or application performs security-sensitive tasks that will trigger security checks (making network connections, reading or writing files on a local disk, etc), it will need to be granted the required permissions if it is not an installed extension (see Step 6b) and it is run while a security manager is installed.

Since LoginModules usually associate Principals and credentials with an authenticated Subject, some types of permissions a LoginModule will typically require are AuthPermissions with target names "modifyPrincipals", "modifyPublicCredentials", and "modifyPrivateCredentials".

A sample statement granting permissions to a LoginModule whose code is in MyLM.jar appears below. Such a statement could appear in a policy file. In this example, the MyLM.jar file is assumed to be in the /localWork directory.

grant codeBase "file:/localWork/MyLM.jar" {
  permission javax.security.auth.AuthPermission "modifyPrincipals";
  permission javax.security.auth.AuthPermission "modifyPublicCredentials";
  permission javax.security.auth.AuthPermission "modifyPrivateCredentials";
};

Note: Since a LoginModule is always invoked within an AccessController.doPrivileged call, it should not have to call doPrivileged itself. If it does, it may inadvertently open up a security hole. For example, a LoginModule that invokes the application-provided CallbackHandler inside a doPrivileged call opens up a security hole by permitting the application's CallbackHandler to gain access to resources it would otherwise not have been able to access.

Step 6d: Create a Configuration Referencing the LoginModule

Because JAAS supports a pluggable authentication architecture, your new LoginModule can be used without requiring modifications to existing applications. Only the login Configuration needs to be updated in order to indicate use of a new LoginModule.

The default Configuration implementation from Sun Microsystems reads configuration information from configuration files, as described in com.sun.security.auth.login.ConfigFile.html.

Create a configuration file to be used for testing. For example, to configure the previously-mentioned hypothetical IBM LoginModule for an application, the configuration file might look like this:

    AppName {
    com.ibm.auth.Module REQUIRED debug=true;
    };
where AppName should be whatever name the application uses to refer to this entry in the login configuration file. The application specifies this name as the first argument to the LoginContext constructor.

Step 7: Test Use of the LoginModule

Finally, test your application and its use of the LoginModule. When you run the application, specify the login configuration file to be used. For example, suppose your application is named MyApp, it is located in MyApp.jar, and your configuration file is test.conf. You could run the application and specify the configuration file via the following:

java -classpath MyApp.jar
 -Djava.security.auth.login.config=test.conf MyApp

Type all that on one line. Multiple lines are used here for legibility.

To specify a policy file named my.policy and run the application with a security manager installed, do the following:

java -classpath MyApp.jar -Djava.security.manager
 -Djava.security.policy=my.policy
 -Djava.security.auth.login.config=test.conf MyApp

Again, type all that on one line.

You may want to configure the LoginModule with a debug option to help ensure that it is working correctly.

Debug your code and continue testing as needed. If you have problems, review the steps above and ensure they are all completed.

Be sure to vary user input and the LoginModule options specified in the configuration file.

Be sure to also include testing using different installation options (e.g., making the LoginModule an installed extension or placing it on the class path) and execution environments (with or without a security manager running). Installation options are discussed in Step 6b. In particular, in order to ensure your LoginModule works when a security manager is installed and the LoginModule and application are not installed extensions, you need to test such an installation and execution environment, after granting required permissions, as described in Step 6c.

If you find during testing that your LoginModule or application needs modifications, make the modifications, recompile (Step 5), place the updated code in a JAR file (Step 6a), re-install the JAR file (Step 6b), if needed fix or add to the permissions (Step 6c), if needed modify the login configuration file (Step 6d), and then re-run the application and repeat these steps as needed.

Step 8: Document Your LoginModule Implementation

The next step is to write documentation for clients of your LoginModule. Example documentation you may want to include is:

  • A README or User Guide describing

    • the authentication process employed by your LoginModule implementation.

    • information on how to install the LoginModule.

    • configuration options accepted by the LoginModule. For each option, specify the option name and possible values (or types of values), as well as the behavior the option controls.

    • the permissions required by your LoginModule when it is run with a security manager (and it is not an installed extension).

  • An example Configuration file that references your new LoginModule.

  • An example policy file granting your LoginModule the required permissions.

  • API documentation. Putting javadoc comments into your source code as you write it will make the API javadocs easy to generate.

Step 9: Make LoginModule JAR File and Documents Available

The final step is to make your LoginModule JAR file and documentation available to clients.


JAAS Reference Guide

JavaTM Authentication and Authorization Service (JAAS)

Reference Guide

for the Java TM SE Development Kit 6

Introduction
Who Should Read This Document
Related Documentation

Core Classes and Interfaces
Common Classes
Subject
Principals
Credentials
Authentication Classes and Interfaces
LoginContext
LoginModule
CallbackHandler
Callback
Authorization Classes
Policy
AuthPermission
PrivateCredentialPermission

JAAS Tutorials and Sample Programs

Appendix A: JAAS Settings in the java.security Security Properties File

Appendix B: Example Login Configurations

Introduction

The JavaTM Authentication and Authorization Service (JAAS) was introduced as an optional package (extension) to the JavaTM 2 SDK, Standard Edition (J2SDK), v 1.3. JAAS was integrated into the J2SDK 1.4.

JAAS can be used for two purposes:

  • for authentication of users, to reliably and securely determine who is currently executing Java code, regardless of whether the code is running as an application, an applet, a bean, or a servlet; and

  • for authorization of users to ensure they have the access control rights (permissions) required to do the actions performed.

JAAS implements a Java version of the standard Pluggable Authentication Module (PAM) framework. See Making Login Services Independent from Authentication Technologies for further information.

Traditionally Java has provided codesource-based access controls (access controls based on where the code originated from and who signed the code). It lacked, however, the ability to additionally enforce access controls based on who runs the code. JAAS provides a framework that augments the Java security architecture with such support.

JAAS authentication is performed in a pluggable fashion. This permits applications to remain independent from underlying authentication technologies. New or updated authentication technologies can be plugged under an application without requiring modifications to the application itself. Applications enable the authentication process by instantiating a LoginContext object, which in turn references a Configuration to determine the authentication technology(ies), or LoginModule(s), to be used in performing the authentication. Typical LoginModules may prompt for and verify a username and password. Others may read and verify a voice or fingerprint sample.

Once the user or service executing the code has been authenticated, the JAAS authorization component works in conjunction with the core Java SE access control model to protect access to sensitive resources. Unlike in the J2SDK 1.3 and earlier, where access control decisions are based solely on code location and code signers (a CodeSource), in the J2SDK 1.4 access control decisions are based both on the executing code's CodeSource and on the user or service running the code, who is represented by a Subject object. The Subject is updated by a LoginModule with relevant Principals and credentials if authentication succeeds.

Who Should Read This Document

This document is intended for experienced developers who require the ability to design applications constrained by a CodeSource-based and Subject-based security model. It is also intended to be read by LoginModule developers (developers implementing an authentication technology) prior to reading the JAAS LoginModule Developer's Guide.

You may wish to first read the JAAS Authentication and JAAS Authorization tutorials to get an overview of how to use JAAS and to see sample code in action, and then return to this document for further information.

Related Documentation

This document assumes you have already read the following:

  • Java SE Security Architecture

  • JAAS white paper

  • Java SE Security Tutorial

A supplement to this guide is the JAAS LoginModule Developer's Guide, intended for experienced programmers who require the ability to write a LoginModule implementing an authentication technology.

If you wish to learn more about the standard Pluggable Authentication Module (PAM) framework (JAAS implements a Java version of PAM), see Making Login Services Independent from Authentication Technologies.

The following tutorials for JAAS authentication and authorization can be run by everyone:

  • JAAS Authentication Tutorial
  • JAAS Authorization Tutorial

Similar tutorials for JAAS authentication and authorization, but which demonstrate the use of a Kerberos LoginModule and thus which require a Kerberos installation, can be found at

  • JAAS Authentication
  • JAAS Authorization

These two tutorials are a part of the Java GSS-API and JAAS sequence of tutorials that utilize Kerberos as the underlying technology for authentication and secure communication.

Core Classes and Interfaces

The JAAS-related core classes and interfaces can be broken into three categories: Common, Authentication, and Authorization.
  • Common Classes
    • Subject, Principal, Credential (actually, any Object)
  • Authentication Classes and Interfaces
    • LoginContext, LoginModule, CallbackHandler, Callback
  • Authorization Classes
    • Policy, AuthPermission, PrivateCredentialPermission

Common Classes

Common classes are those shared by both the JAAS authentication and authorization components.

The key JAAS class is javax.security.auth.Subject, which represents a grouping of related information for a single entity such as a person. It encompasses the entity's Principals, public credentials, and private credentials.

Note that the java.security.Principal interface is used to represent a Principal. Also note that a credential, as defined by JAAS, may be any Object.

Subject

To authorize access to resources, applications first need to authenticate the source of the request. The JAAS framework defines the term subject to represent the source of a request. A subject may be any entity, such as a person or a service. Once the subject is authenticated, a javax.security.auth.Subject is populated with associated identities, or Principals. A Subject may have many Principals. For example, a person may have a name Principal ("John Doe") and a SSN Principal ("123-45-6789"), which distinguish it from other subjects.

A Subject may also own security-related attributes, which are referred to as credentials. Sensitive credentials that require special protection, such as private cryptographic keys, are stored within a private credential Set. Credentials intended to be shared, such as public key certificates, are stored within a public credential Set. Different permissions (described below) are required to access and modify the different credential Sets.

Subjects are created using these constructors:

    public Subject();

    public Subject(boolean readOnly, Set principals,
                   Set pubCredentials, Set privCredentials);
The first constructor creates a Subject with empty (non-null) Sets of Principals and credentials. The second constructor creates a Subject with the specified Sets of Principals and credentials. It also has a boolean argument which can be used to make the Subject read-only. In a read-only Subject, the Principal and credential Sets are immutable.

An application writer does not have to instantiate a Subject. If the application instantiates a LoginContext and does not pass a Subject to the LoginContext constructor, the LoginContext instantiates a new empty Subject. See the LoginContext section.

If a Subject was not instantiated to be in a read-only state, it can be set read-only by calling the following method:

    public void setReadOnly();
A javax.security.auth.AuthPermission with target "setReadOnly" is required to invoke this method. Once in a read-only state, any attempt to add or remove Principals or credentials will result in an IllegalStateException being thrown.

The following method may be called to test a Subject's read-only state:

    public boolean isReadOnly();

To retrieve the Principals associated with a Subject, two methods are available:

    public Set getPrincipals();
    public Set getPrincipals(Class c);

The first method returns all Principals contained in the Subject, while the second method only returns those Principals that are an instance of the specified Class c, or an instance of a subclass of Class c. An empty set will be returned if the Subject does not have any associated Principals.

To retrieve the public credentials associated with a Subject, these methods are available:

    public Set getPublicCredentials();
    public Set getPublicCredentials(Class c);

The behavior of these methods is similar to that for the getPrincipals methods, except in this case the public credentials are being obtained.

To access private credentials associated with a Subject, the following methods are available:

    public Set getPrivateCredentials();
    public Set getPrivateCredentials(Class c);

The behavior of these methods is similar to that for the getPrincipals and getPublicCredentials methods.

To modify or operate upon a Subject's Principal Set, public credential Set, or private credential Set, callers use the methods defined in the java.util.Set class. The following example demonstrates this:

    Subject subject;
    Principal principal;
    Object credential;

    . . .

    // add a Principal and credential to the Subject
    subject.getPrincipals().add(principal);
    subject.getPublicCredentials().add(credential);

Note: An AuthPermission with target "modifyPrincipals", "modifyPublicCredentials", or "modifyPrivateCredentials" is required to modify the respective Sets. Also note that only the sets returned via the getPrincipals(), getPublicCredentials(), and getPrivateCredentials() methods with no arguments are backed by the Subject's respective internal sets. Therefore any modification to the returned set affects the internal sets as well. The sets returned via the getPrincipals(Class c), getPublicCredentials(Class c), and getPrivateCredentials(Class c) methods are not backed by the Subject's respective internal sets. A new set is created and returned for each such method invocation. Modifications to these sets will not affect the Subject's internal sets.

In order to iterate through a Set of private credentials, you need a javax.security.auth.PrivateCredentialPermission to access each credential. See the PrivateCredentialPermission API documentation for further information.

A Subject may be associated with an AccessControlContext (see the doAs and doAsPrivileged method descriptions below). The following method returns the Subject associated with the specified AccessControlContext, or null if no Subject is associated with the specified AccessControlContext.

    public static Subject getSubject(final AccessControlContext acc);

An AuthPermission with target "getSubject" is required to call Subject.getSubject.

The Subject class also includes the following methods inherited from java.lang.Object.

    public boolean equals(Object o);
    public String toString();
    public int hashCode();

The doAs methods for performing an action as a particular Subject

The following static methods may be called to perform an action as a particular Subject:
    public static Object
        doAs(final Subject subject,
             final java.security.PrivilegedAction action);

    public static Object
        doAs(final Subject subject,
             final java.security.PrivilegedExceptionAction action)
             throws java.security.PrivilegedActionException;

Both methods first associate the specified subject with the current Thread's AccessControlContext, and then execute the action. This achieves the effect of having the action run as the subject. The first method can throw runtime exceptions but normal execution has it returning an Object from the run method of its action argument. The second method behaves similarly except that it can throw a checked exception from its PrivilegedExceptionAction run method. An AuthPermission with target "doAs" is required to call the doAs methods.

Subject.doAs Example

Here is an example utilizing the first doAs method. Assume that someone named "Bob" has been authenticated by a LoginContext (see the LoginContext section) and as a result a Subject was populated with a Principal of class com.ibm.security.Principal, and that Principal has the name "BOB". Also assume that a SecurityManager has been installed, and that the following exists in the access control policy (see the Policy section for more details on the policy file).

    // grant "BOB" permission to read the file "foo.txt"
    grant Principal com.ibm.security.Principal "BOB" {
        permission java.io.FilePermission "foo.txt", "read";
    };

Here is the sample application code:

    class ExampleAction implements java.security.PrivilegedAction {
        public Object run() {
            java.io.File f = new java.io.File("foo.txt");

            // the following call invokes a security check
            if (f.exists()) {
                System.out.println("File foo.txt exists");
            }
            return null;
        }
    }

    public class Example1 {
        public static void main(String[] args) {

            // Authenticate the subject, "BOB".
            // This process is described in the
            // LoginContext section.

            Subject bob;
            // Set bob to the Subject created during the
            // authentication process

            // perform "ExampleAction" as "BOB"
            Subject.doAs(bob, new ExampleAction());
        }
    }

During execution, ExampleAction will encounter a security check when it makes a call to f.exists(). However, since ExampleAction is running as "BOB", and the policy (above) grants the necessary FilePermission to "BOB", the ExampleAction will pass the security check. If the grant statement in the policy is altered (adding an incorrect CodeBase or changing the Principal to "MOE", for example), then a SecurityException will be thrown.

The doAsPrivileged methods

The following methods also perform an action as a particular Subject.

    public static Object doAsPrivileged(
        final Subject subject,
        final java.security.PrivilegedAction action,
        final java.security.AccessControlContext acc);

    public static Object doAsPrivileged(
        final Subject subject,
        final java.security.PrivilegedExceptionAction action,
        final java.security.AccessControlContext acc)
        throws java.security.PrivilegedActionException;

An AuthPermission with target "doAsPrivileged" is required to call the doAsPrivileged methods.

doAs vs. doAsPrivileged

The doAsPrivileged methods behave exactly the same as the doAs methods, except that instead of associating the provided Subject with the current Thread's AccessControlContext, they use the provided AccessControlContext. In this way, actions can be restricted by AccessControlContexts different from the current one.

An AccessControlContext contains information about all the code executed since the AccessControlContext was instantiated, including the code location and the permissions the code is granted by the policy. In order for an access control check to succeed, the policy must grant each code item referenced by the AccessControlContext the required permissions.

If the AccessControlContext provided to doAsPrivileged is null, then the action is not restricted by a separate AccessControlContext. One example where this may be useful is in a server environment. A server may authenticate multiple incoming requests and perform a separate doAs operation for each request. To start each doAs action "fresh," and without the restrictions of the current server AccessControlContext, the server can call doAsPrivileged and pass in a null AccessControlContext.

Principals

As mentioned previously, Principals may be associated with a Subject if authentication is successful. Principals represent Subject identities, and must implement the java.security.Principal and java.io.Serializable interfaces. The Subject section describes ways to update the Principals associated with a Subject.

Credentials

Public and private credential classes are not part of the core JAAS class library. Any class can represent a credential. Developers, however, may elect to have their credential classes implement two interfaces related to credentials: Refreshable and Destroyable.

Refreshable

The javax.security.auth.Refreshable interface provides the capability for a credential to refresh itself. For example, a credential with a particular time-restricted lifespan may implement this interface to allow callers to refresh the time period for which it is valid. The interface has two abstract methods:

    boolean isCurrent();
This method determines whether the credential is current or valid.
    void refresh() throws RefreshFailedException;
This method updates or extends the validity of the credential. The method implementation should perform an AuthPermission("refreshCredential") security check to ensure the caller has permission to refresh the credential.

Destroyable

The javax.security.auth.Destroyable interface provides the capability of destroying the contents within a credential. The interface has two abstract methods:

    boolean isDestroyed();
Determines whether the credential has been destroyed.
    void destroy() throws DestroyFailedException;
Destroys and clears the information associated with this credential. Subsequent calls to certain methods on this credential will result in an IllegalStateException being thrown. The method implementation should perform an AuthPermission("destroyCredential") security check to ensure the caller has permission to destroy the credential.

Authentication Classes and Interfaces

To authenticate a subject (user or service), the following steps are performed:
  1. An application instantiates a LoginContext.

  2. The LoginContext consults a Configuration to load all of the LoginModules configured for that application.

  3. The application invokes the LoginContext's login method.

  4. The login method invokes all of the loaded LoginModules. Each LoginModule attempts to authenticate the subject. Upon success, LoginModules associate relevant Principals and credentials with a Subject object that represents the subject being authenticated.

  5. The LoginContext returns the authentication status to the application.

  6. If authentication succeeded, the application retrieves the Subject from the LoginContext.

The authentication classes are described below.

LoginContext

The javax.security.auth.login.LoginContext class provides the basic methods used to authenticate subjects, and provides a way to develop an application independent of the underlying authentication technology. The LoginContext consults a Configuration to determine the authentication services, or LoginModule(s), configured for a particular application. Therefore, different LoginModules can be plugged in under an application without requiring any modifications to the application itself.

LoginContext offers four constructors from which to choose:

    public LoginContext(String name) throws LoginException;

    public LoginContext(String name, Subject subject) throws LoginException;

    public LoginContext(String name, CallbackHandler callbackHandler)
           throws LoginException

    public LoginContext(String name, Subject subject,
           CallbackHandler callbackHandler) throws LoginException
All of the constructors share a common parameter: name. This argument is used by the LoginContext as an index into the login Configuration to determine which LoginModules are configured for the application instantiating the LoginContext. Constructors that do not take a Subject as an input parameter instantiate a new Subject. Null inputs are disallowed for all constructors. Callers require an AuthPermission with target "createLoginContext.<name>" to instantiate a LoginContext. Here, <name> refers to the name of the login configuration entry that the application references in the name parameter for the LoginContext instantiation.

See the CallbackHandler section for information on what a CallbackHandler is and when you may need one.

Actual authentication occurs with a call to the following method:

    public void login() throws LoginException;

When login is invoked, all of the configured LoginModules are invoked to perform the authentication. If the authentication succeeded, the Subject (which may now hold Principals, public credentials, and private credentials) can be retrieved by using the following method:

     public Subject getSubject();

To logout a Subject and remove its authenticated Principals and credentials, the following method is provided:

    public void logout() throws LoginException;

The following code sample demonstrates the calls necessary to authenticate and logout a Subject:

    // let the LoginContext instantiate a new Subject
    LoginContext lc = new LoginContext("entryFoo");
    try {
        // authenticate the Subject
        lc.login();
        System.out.println("authentication successful");

        // get the authenticated Subject
        Subject subject = lc.getSubject();

        ...

        // all finished -- logout
        lc.logout();
    } catch (LoginException le) {
        System.err.println("authentication unsuccessful: " +
            le.getMessage());
    }

LoginModule

The LoginModule interface gives developers the ability to implement different kinds of authentication technologies that can be plugged in under an application. For example, one type of LoginModule may perform a username/password-based form of authentication. Other LoginModules may interface to hardware devices such as smart cards or biometric devices.

Note: If you are an application writer, you do not need to understand the workings of LoginModules. All you have to know is how to write your application and specify configuration information (such as in a login configuration file) such that the application will be able to utilize the LoginModule specified by the configuration to authenticate the user.

If, on the other hand, you are a programmer who wishes to write a LoginModule implementing an authentication technology, see the JAAS LoginModule Developer's Guide for detailed step-by-step instructions.

CallbackHandler

In some cases a LoginModule must communicate with the user to obtain authentication information. LoginModules use a javax.security.auth.callback.CallbackHandler for this purpose. Applications implement the CallbackHandler interface and pass it to the LoginContext, which forwards it directly to the underlying LoginModules. A LoginModule uses the CallbackHandler both to gather input from users (such as a password or smart card pin number) or to supply information to users (such as status information). By allowing the application to specify the CallbackHandler, underlying LoginModules can remain independent of the different ways applications interact with users. For example, the implementation of a CallbackHandler for a GUI application might display a window to solicit input from a user. On the other hand, the implementation of a CallbackHandler for a non-GUI tool might simply prompt the user for input directly from the command line.

CallbackHandler is an interface with one method to implement:
     void handle(Callback[] callbacks)
         throws java.io.IOException, UnsupportedCallbackException;

The LoginModule passes the CallbackHandler handle method an array of appropriate Callbacks, for example a NameCallback for the user name and a PasswordCallback for the password, and the CallbackHandler performs the requested user interaction and sets appropriate values in the Callbacks. For example, to process a NameCallback, the CallbackHandler may prompt for a name, retrieve the value from the user, and call the NameCallback's setName method to store the name.

The CallbackHandler documentation has a lengthy example not included in this document that readers may want to examine.

Callback

The javax.security.auth.callback package contains the Callback interface as well as several implementations. LoginModules may pass an array of Callbacks directly to the handle method of a CallbackHandler.

Please consult the various Callback APIs for more information on their use.

Authorization Classes

To make JAAS authorization take place, granting access control permissions based not just on what code is running but also on who is running it, the following is required:

  • The user must be authenticated, as described in the LoginContext section.

  • The Subject that is the result of authentication must be associated with an access control context, as described in the Subject section.

  • Principal-based entries must be configured in the security policy, as described below.

The Policy abstract class and the authorization-specific classes AuthPermission and PrivateCredentialPermission are described below.

Policy

The java.security.Policy class is an abstract class for representing the system-wide access control policy. The Policy API was upgraded in the J2SDK 1.4 to support Principal-based queries.

As a default, the J2SDK provides a file-based subclass implementation, which was upgraded to support Principal-based grant entries in policy files.

Policy files and the structure of entries within them are described in Default Policy Implementation and Policy File Syntax.

AuthPermission

The javax.security.auth.AuthPermission class encapsulates the basic permissions required for JAAS. An AuthPermission contains a name (also referred to as a "target name") but no actions list; you either have the named permission or you don't.

In addition to its inherited methods (from the java.security.Permission class), an AuthPermission has two public constructors:

    public AuthPermission(String name);
    public AuthPermission(String name, String actions);
The first constructor creates a new AuthPermission with the specified name. The second constructor also creates a new AuthPermission object with the specified name, but has an additional actions argument which is currently unused and should be null. This constructor exists solely for the Policy object to instantiate new Permission objects. For most other code, the first constructor is appropriate.

Currently the AuthPermission object is used to guard access to the Policy, Subject, LoginContext, and Configuration objects. Please refer to the AuthPermission javadocs for the list of valid names that are supported.

PrivateCredentialPermission

The javax.security.auth.PrivateCredentialPermission class protects access to a Subject's private credentials and provides one public constructor:

     public PrivateCredentialPermission(String name, String actions);
Please refer to the PrivateCredentialPermission javadocs for more detailed information on this class.

JAAS Tutorials and Sample Programs

The JAAS Authentication and JAAS Authorization tutorials contain the following samples:

  • SampleAcn.java is a sample application demonstrating JAAS authentication.

  • SampleAzn.java is a sample application used by the authorization tutorial. It demonstrates both authentication and authorization.

  • sample_jaas.config is a sample login configuration file used by both tutorials.

  • sampleacn.policy is a sample policy file granting permissions required by the code for the authentication tutorial.

  • sampleazn.policy is a sample policy file granting permissions required by the code for the authorization tutorial.

  • SampleLoginModule.java is the class specified by the tutorials' login configuration file (sample_jaas.config) as the class implementing the desired underlying authentication. SampleLoginModule's user authentication consists of simply verifying that the name and password specified by the user have specific values.

  • SamplePrincipal.java is a sample class implementing the Principal interface. It is used by SampleLoginModule.

See the tutorials for detailed information about the applications, the policy files, and the login configuration file.

Application writers do not need to understand the code for SampleLoginModule.java or SamplePrincipal.java, as explained in the tutorials. Programmers who wish to write LoginModules can learn how to do so by reading the JAAS LoginModule Developer's Guide.

Appendix A: JAAS Settings in the java.security Security Properties File

A number of JAAS-related settings can be configured in the java.security master security properties file, which is located in the lib/security directory of the Java runtime.

JAAS adds two new security properties to java.security:

  • login.configuration.provider
  • login.config.url.n

The following pre-existing properties are also relevant for JAAS users:

  • policy.provider
  • policy.url.n

Login Configuration Provider

The default JAAS login configuration implementation provided by Sun Microsystems gets its configuration information from files and expects the information to be provided in a specific format shown in the tutorials.

The default JAAS login configuration implementation can be replaced by specifying the alternative provider class implementation in the login.configuration.provider property.

For example:

  login.configuration.provider=com.foo.Config
If the Security property login.configuration.provider is not found, or is left unspecified, then it is set to the default value:
  login.configuration.provider=com.sun.security.auth.login.ConfigFile

Note that there is no means to dynamically set the login configuration provider from the command line.

Login Configuration URLs

If you are using a login configuration implementation that expects the configuration information to be specified in files (as does the default implementation from Sun Microsystems), the location of the login configuration file(s) can be statically set by specifying their respective URLs in the login.config.url.n property. 'n' is a consecutively numbered integer starting with 1. If multiple configuration files are specified (if n >= 2), they will be read and unioned into one single configuration.

For example:

  login.config.url.1=file:C:/config/.java.login.config
  login.config.url.2=file:C:/users/foo/.foo.login.config

If the location of the configuration files is not set in the java.security properties file, and also is not specified dynamically from the command line (via the -Djava.security.auth.login.config option), JAAS attempts to load a default configuration from

file:${user.home}/.java.login.config

Policy Provider

The default policy implementation can be replaced by specifying the alternative provider class implementation in the policy.provider property.

For example:

  policy.provider=com.foo.Policy
If the Security property policy.provider is not found, or is left unspecified, then the Policy is set to the default value:
  policy.provider=sun.security.provider.PolicyFile

Note that there is no means to dynamically set the policy provider from the command line.

Policy File URLs

The location of the access control policy files can be statically set by specifying their respective URLs in the auth.policy.url.n property. 'n' is a consecutively numbered integer starting with 1. If multiple policies are specified (if n >= 2), they will be read and unioned into one single policy.

For example:

  policy.url.1=file:C:/policy/.java.policy
  policy.url.2=file:C:/users/foo/.foo.policy

If the location of the policy file(s) is not set in the java.security properties file, and is not specified dynamically from the command line (via the -Djava.security.policy option), the access control policy defaults to the same policy as that of the system policy file installed with the the J2SDK. That policy file

  • grants all permissions to standard extensions

  • allows anyone to listen on un-privileged ports

  • allows any code to read certain "standard" properties that are not security-sensitive, such as the "os.name" and "file.separator" properties.

Sample Master Security Properties File

Below is a modified copy of the java.security file provided with the Java SE 6. Example settings for JAAS-related properties are shown in bold. In this example, we leave the values provided in the default java.security file for the policy.provider, policy.url.n, and login.configuration.provider properties. The default java.security file also lists a value for the login.config.url.n property, but it is commented out. In the example below, it is not commented.

#
# This is the "master security properties file".
#
# In this file, various security properties are set for use by
# java.security classes. This is where users can statically register
# Cryptography Package Providers ("providers" for short). The term
# "provider" refers to a package or set of packages that supply a
# concrete implementation of a subset of the cryptography aspects of
# the Java Security API. A provider may, for example, implement one or
# more digital signature algorithms or message digest algorithms.
#
# Each provider must implement a subclass of the Provider class.
# To register a provider in this master security properties file,
# specify the Provider subclass name and priority in the format
#
#    security.provider.<n>=<className>
#
# This declares a provider, and specifies its preference
# order <n>. The preference order is the order in which providers are
# searched for requested algorithms (when no specific provider is
# requested). The order is 1-based; 1 is the most preferred, followed
# by 2, and so on.
#
# <className> must specify the subclass of the Provider class whose
# constructor sets the values of various properties that are required
# for the Java Security API to look up the algorithms or other
# facilities implemented by the provider.
#
# There must be at least one provider specification in java.security.
# There is a default provider that comes standard with the JDK. It
# is called the "SUN" provider, and its Provider subclass
# named Sun appears in the sun.security.provider package. Thus, the
# "SUN" provider is registered via the following:
#
#    security.provider.1=sun.security.provider.Sun
#
# (The number 1 is used for the default provider.)
#
# Note: Statically registered Provider subclasses are instantiated
# when the system is initialized. Providers can be dynamically
# registered instead by calls to either the addProvider or
# insertProviderAt method in the Security class.

#
# List of providers and their preference orders (see above):
#
security.provider.1=sun.security.provider.Sun
security.provider.2=com.sun.net.ssl.internal.ssl.Provider
security.provider.3=com.sun.rsajca.Provider
security.provider.4=com.sun.crypto.provider.SunJCE
security.provider.5=sun.security.jgss.SunProvider

#
# Select the source of seed data for SecureRandom. By default it uses
# a system/thread activity algorithm. Optionally, if the platform supports
# it an entropy gathering device can be selected.
#
#securerandom.source=file:/dev/random
#
# The entropy gathering device is described as a URL and can
# also be specified with the property "java.security.egd". For example,
#   -Djava.security.egd=file:/dev/urandom
# Specifying this property will override the securerandom.source setting.

#
# Class to instantiate as the javax.security.auth.login.Configuration
# provider.
#
login.configuration.provider=com.sun.security.auth.login.ConfigFile

#
# Default login configuration file
#
login.config.url.1=file:${user.home}/.java.login.config

#
# Class to instantiate as the system Policy. This is the name of the class
# that will be used as the Policy object.
#
policy.provider=sun.security.provider.PolicyFile

# The default is to have a single system-wide policy file,
# and a policy file in the user's home directory.
policy.url.1=file:${java.home}/lib/security/java.policy
policy.url.2=file:${user.home}/.java.policy

# whether or not we expand properties in the policy file
# if this is set to false, properties (${...}) will not be expanded in policy
# files.
policy.expandProperties=true

# whether or not we allow an extra policy to be passed on the command line
# with -Djava.security.policy=somefile. Comment out this line to disable
# this feature.
policy.allowSystemProperty=true

# whether or not we look into the IdentityScope for trusted Identities
# when encountering a 1.1 signed JAR file. If the identity is found
# and is trusted, we grant it AllPermission.
policy.ignoreIdentityScope=false

#
# Default keystore type.
#
keystore.type=jks

#
# Class to instantiate as the system scope:
#
system.scope=sun.security.provider.IdentityDatabase

#
# List of comma-separated packages that start with or equal this string
# will cause a security exception to be thrown when
# passed to checkPackageAccess unless the
# corresponding RuntimePermission ("accessClassInPackage."+package) has
# been granted.
package.access=sun.

#
# List of comma-separated packages that start with or equal this string
# will cause a security exception to be thrown when
# passed to checkPackageDefinition unless the
# corresponding RuntimePermission ("defineClassInPackage."+package) has
# been granted.
#
# by default, no packages are restricted for definition, and none of
# the class loaders supplied with the JDK call checkPackageDefinition.
#
#package.definition=

#
# Determines whether this properties file can be appended to
# or overridden on the command line via -Djava.security.properties
#
security.overridePropertiesFile=true

#
# Determines the default key and trust manager factory algorithms for
# the javax.net.ssl package.
#
ssl.KeyManagerFactory.algorithm=SunX509
ssl.TrustManagerFactory.algorithm=SunX509

#
# Determines the default SSLSocketFactory and SSLServerSocketFactory
# provider implementations for the javax.net.ssl package.  If, due to
# export and/or import regulations, the providers are not allowed to be
# replaced, changing these values will produce non-functional
# SocketFactory or ServerSocketFactory implementations.
#
#ssl.SocketFactory.provider=
#ssl.ServerSocketFactory.provider=

Appendix B: Example Login Configurations

Login configurations are located using the login.config.url.n security properties found in the java.security file. For more information about this property and the location of the java.security file, see Appendix A.

The default Configuration implementation, ConfigFile, gets its configuration information from login configuration files. For details about the default login Configuration implementation provided with JAAS, please consult the javadocs for the com.sun.security.auth.login.ConfigFile class.

The following is a sample login configuration file.

    Login1 {
       sample.SampleLoginModule required debug=true;
    };

    Login2 {
       sample.SampleLoginModule required;
       com.sun.security.auth.module.NTLoginModule sufficient;
       com.foo.SmartCard requisite debug=true;
       com.foo.Kerberos optional debug=true;
    };

The application Login1 only has one configured LoginModule, SampleLoginModule. Therefore, an attempt by Login1 to authenticate a subject (user or service) will be successful if and only if the SampleLoginModule succeeds.

The authentication logic for the application Login2 is easier to explain with the table below. Note: the required, sufficient, requisite, and optional flags are described in the Configuration javadocs.

Login2 Authentication Status
SampleLoginModule | required | pass | pass | pass | pass | fail | fail | fail | fail
NTLoginModule | sufficient | pass | fail | fail | fail | pass | fail | fail | fail
SmartCard requisite * pass pass fail * pass pass fail
Kerberos optional * pass fail * * pass fail *
Overall Authentication | pass | pass | pass | fail | fail | fail | fail | fail
* = trivial value due to control returning to the application because a previous requisite module failed or a previous sufficient module succeeded.


JAAS Authentication Tutorial

The JavaTM Authentication and Authorization Service (JAAS) was introduced as an optional package to the JavaTM 2 SDK, Standard Edition (J2SDK), v 1.3. JAAS was integrated into the Java TM Standard Edition Development Kit starting with J2SDK 1.4.

JAAS can be used for two purposes:

  • for authentication of users, to reliably and securely determine who is currently executing Java code, regardless of whether the code is running as an application, an applet, a bean, or a servlet; and

  • for authorization of users to ensure they have the access control rights (permissions) required to do the actions performed.

This section provides a basic tutorial for the authentication component. The authorization component will be described in the JAAS Authorization Tutorial.

JAAS authentication is performed in a pluggable fashion. This permits Java applications to remain independent from underlying authentication technologies. New or updated technologies can be plugged in without requiring modifications to the application itself. An implementation for a particular authentication technology to be used is determined at runtime. The implementation is specified in a login configuration file. The authentication technology used for this tutorial is very basic, just ensuring that the user specifies a particular name and password.

The rest of this tutorial consists of the following sections:

  1. The Authentication Tutorial Code

  2. The Login Configuration

  3. Running the Code

  4. Running the Code with a Security Manager

If you want to first see the tutorial code in action, you can skip directly to Running the Code and then go back to the other sections to learn about coding and configuration file details.

The Authentication Tutorial Code

The code for this tutorial consists of three files:

  • SampleAcn.java contains the sample application class (SampleAcn) and another class used to handle user input (MyCallbackHandler). The code in this file is the only code you need to understand for this tutorial. Your application will only indirectly use the other source files.

  • SampleLoginModule.java is the class specified by the tutorial's login configuration file as the class implementing the desired underlying authentication. SampleLoginModule's user authentication consists of simply verifying that the name and password specified by the user have specific values.

  • SamplePrincipal.java is a sample class implementing the java.security.Principal interface. It is used by SampleLoginModule.

SampleAcn.java

Our authentication tutorial application code is contained in a single source file, SampleAcn.java. That file contains two classes:

  • The SampleAcn Class

  • The MyCallbackHandler Class

The SampleAcn Class

The main method of the SampleAcn class performs the authentication and then reports whether or not authentication succeeded.

The code for authenticating the user is very simple, consisting of just two steps:

  1. Instantiate a LoginContext.

  2. Call the LoginContext's login method.

First the basic code is shown, followed by a complete listing of the SampleAcn class, complete with the import statement it requires and error handling.

Instantiating a LoginContext

In order to authenticate a user, you first need a javax.security.auth.login.LoginContext. Here is the basic way to instantiate a LoginContext:

import javax.security.auth.login.*;
. . .
LoginContext lc =
    new LoginContext(<config file entry name>,
           <CallbackHandler to be used for user interaction>);
and here is the specific way our tutorial code does the instantiation:
import javax.security.auth.login.*;
. . .
LoginContext lc =
    new LoginContext("Sample",
          new MyCallbackHandler());

The arguments are the following:

  1. The name of an entry in the JAAS login configuration file

    This is the name for the LoginContext to use to look up an entry for this application in the JAAS login configuration file, described here. Such an entry specifies the class(es) that implement the desired underlying authentication technology(ies). The class(es) must implement the LoginModule interface, which is in the javax.security.auth.spi package.

    In our sample code, we use the SampleLoginModule supplied with this tutorial. The SampleLoginModule performs authentication by ensuring that the user types a particular name and password.

    The entry in the login configuration file we use for this tutorial (see sample_jaas.config) has the name "Sample", so that is the name we specify as the first argument to the LoginContext constructor.

  2. A CallbackHandler instance.

    When a LoginModule needs to communicate with the user, for example to ask for a user name and password, it does not do so directly. That is because there are various ways of communicating with a user, and it is desirable for LoginModules to remain independent of the different types of user interaction. Rather, the LoginModule invokes a javax.security.auth.callback.CallbackHandler to perform the user interaction and obtain the requested information, such as the user name and password.

    An instance of the particular CallbackHandler to be used is specified as the second argument to the LoginContext constructor. The LoginContext forwards that instance to the underlying LoginModule (in our case SampleLoginModule). An application typically provides its own CallbackHandler implementation. Two simple CallbackHandlers, TextCallbackHandler and DialogCallbackHandler, are provided in the com.sun.security.auth.callback package as sample implementations. For this tutorial we could use the TextCallbackHandler, which outputs information to and reads input from the command line. However, we instead demonstrate the more typical case of an application providing its own CallbackHandler implementation, described in The MyCallbackHandler Class.

Calling the LoginContext's login Method

Once we have a LoginContext lc, we can call its login method to carry out the authentication process:

lc.login();

The LoginContext instantiates a new empty javax.security.auth.Subject object (which represents the user or service being authenticated). The LoginContext constructs the configured LoginModule (in our case SampleLoginModule) and initializes it with this new Subject and MyCallbackHandler.

The LoginContext's login method then calls methods in the SampleLoginModule to perform the login and authentication. The SampleLoginModule will utilize the MyCallbackHandler to obtain the user name and password. Then the SampleLoginModule will check that the name and password are the ones it expects.

If authentication is successful, the SampleLoginModule populates the Subject with a Principal representing the user. The Principal the SampleLoginModule places in the Subject is an instance of SamplePrincipal, which is a sample class implementing the java.security.Principal interface.

See Subjects, Principals, Authentication, and Credentials for information on these terms.

The calling application can subsequently retrieve the authenticated Subject by calling the LoginContext's getSubject method, although doing so is not necessary for this tutorial.

The Complete SampleAcn Class Code

Now that you have seen the basic code required to authenticate the user, we can put it all together into the full class in SampleAcn.java, which includes relevant import statements and error handling:

package sample;

import javax.security.auth.login.*;
// . . . other import statements needed by MyCallbackHandler . . .

/**
 * This Sample application attempts to authenticate a user
 * and reports whether or not the authentication was
 * successful.
 */
public class SampleAcn {

   /**
    * Attempt to authenticate the user.
    *
    * @param args input arguments for this application.
    * These are ignored.
    */
    public static void main(String[] args) {

      // Obtain a LoginContext, needed for authentication.
      // Tell it to use the LoginModule implementation
      // specified by the entry named "Sample" in the
      // JAAS login configuration file and to also use the
      // specified CallbackHandler.
      LoginContext lc = null;
      try {
          lc = new LoginContext("Sample",
                          new MyCallbackHandler());
      } catch (LoginException le) {
          System.err.println("Cannot create LoginContext. "
              + le.getMessage());
          System.exit(-1);
      } catch (SecurityException se) {
          System.err.println("Cannot create LoginContext. "
              + se.getMessage());
          System.exit(-1);
      }

      // the user has 3 attempts to authenticate successfully
      int i;
      for (i = 0; i < 3; i++) {
          try {

              // attempt authentication
              lc.login();

              // if we return with no exception,
              // authentication succeeded
              break;

          } catch (LoginException le) {

              System.err.println("Authentication failed:");
              System.err.println("  " + le.getMessage());
              try {
                  Thread.currentThread().sleep(3000);
              } catch (Exception e) {
                  // ignore
              }

          }
      }

      // did they fail three times?
      if (i == 3) {
          System.out.println("Sorry");
          System.exit(-1);
      }

      System.out.println("Authentication succeeded!");

    }
}

The MyCallbackHandler Class

In some cases a LoginModule must communicate with the user to obtain authentication information. LoginModules use a javax.security.auth.callback.CallbackHandler for this purpose. An application can either use one of the sample implementations provided in the com.sun.security.auth.callback package or, more typically, write a CallbackHandler implementation. The application passes the CallbackHandler as an argument to the LoginContext instantiation. The LoginContext forwards the CallbackHandler directly to the underlying LoginModules.

The tutorial sample code supplies its own CallbackHandler implementation, the MyCallbackHandler class in SampleAcn.java.

CallbackHandler is an interface with one method to implement:

     void handle(Callback[] callbacks)
         throws java.io.IOException, UnsupportedCallbackException;

The LoginModule passes the CallbackHandler handle method an array of appropriate javax.security.auth.callback.Callbacks, for example a NameCallback for the user name and a PasswordCallback for the password, and the CallbackHandler performs the requested user interaction and sets appropriate values in the Callbacks.

The MyCallbackHandler handle method is structured as follows:

public void handle(Callback[] callbacks)
  throws IOException, UnsupportedCallbackException {

  for (int i = 0; i < callbacks.length; i++) {
    if (callbacks[i] instanceof TextOutputCallback) {

      // display a message according to a specified type
      . . .

    } else if (callbacks[i] instanceof NameCallback) {

      // prompt the user for a username
      . . .

    } else if (callbacks[i] instanceof PasswordCallback) {

      // prompt the user for a password
      . . .

    } else {
        throw new UnsupportedCallbackException
         (callbacks[i], "Unrecognized Callback");
    }
  }
}

A CallbackHandler handle method is passed an array of Callback instances, each of a particular type (NameCallback, PasswordCallback, etc.). It must handle each Callback, performing user interaction in a way that is appropriate for the executing application.

MyCallbackHandler handles three types of Callbacks: NameCallback to prompt the user for a user name, PasswordCallback to prompt for a password, and TextOutputCallback to report any error, warning, or other messages the SampleLoginModule wishes to send to the user.

The handle method handles a TextOutputCallback by extracting the message to be reported and then printing it to System.out, optionally preceded by additional wording that depends on the message type. The message to be reported is determined by calling the TextOutputCallback's getMessage method and the type by calling its getMessageType method. Here is the code for handling a TextOutputCallback:

if (callbacks[i] instanceof TextOutputCallback) {

  // display the message according to the specified type
  TextOutputCallback toc = (TextOutputCallback)callbacks[i];
  switch (toc.getMessageType()) {
     case TextOutputCallback.INFORMATION:
        System.out.println(toc.getMessage());
        break;
     case TextOutputCallback.ERROR:
        System.out.println("ERROR: " + toc.getMessage());
        break;
     case TextOutputCallback.WARNING:
        System.out.println("WARNING: " + toc.getMessage());
        break;
     default:
        throw new IOException("Unsupported message type: " +
            toc.getMessageType());
   }

The handle method handles a NameCallback by prompting the user for a user name. It does this by printing the prompt to System.err. It then sets the name for use by the SampleLoginModule by calling the NameCallback's setName method, passing it the name typed by the user:

} else if (callbacks[i] instanceof NameCallback) {

  // prompt the user for a username
  NameCallback nc = (NameCallback)callbacks[i];

  System.err.print(nc.getPrompt());
  System.err.flush();
  nc.setName((new BufferedReader
      (new InputStreamReader(System.in))).readLine());

Similarly, the handle method handles a PasswordCallback by printing a prompt to System.err to prompt the user for a password. It then sets the password for use by the SampleLoginModule by calling the PasswordCallback's setPassword method, passing it the password typed by the user, which it reads by calling the readPassword method (shown below):

} else if (callbacks[i] instanceof PasswordCallback) {

  // prompt the user for sensitive information
  PasswordCallback pc = (PasswordCallback)callbacks[i];

  System.err.print(pc.getPrompt());
  System.err.flush();
  pc.setPassword(readPassword(System.in));

The readPassword method is a basic method for reading a password from an InputStream:

private char[] readPassword(InputStream in) throws IOException {

    char[] lineBuffer;
    char[] buf;
    int i;

    buf = lineBuffer = new char[128];

    int room = buf.length;
    int offset = 0;
    int c;

  loop:
    while (true) {
      switch (c = in.read()) {
         case -1:
         case '\n':
            break loop;

         case '\r':
             int c2 = in.read();
             if ((c2 != '\n') && (c2 != -1)) {
                 if (!(in instanceof PushbackInputStream)) {
                     in = new PushbackInputStream(in);
                 }
                 ((PushbackInputStream)in).unread(c2);
             } else
                 break loop;

         default:
             if (--room < 0) {
                 buf = new char[offset + 128];
                 room = buf.length - offset - 1;
                 System.arraycopy(lineBuffer, 0, buf, 0, offset);
                 Arrays.fill(lineBuffer, ' ');
                 lineBuffer = buf;
             }
             buf[offset++] = (char) c;
             break;
        }
    }

    if (offset == 0) {
        return null;
    }

    char[] ret = new char[offset];
    System.arraycopy(buf, 0, ret, 0, offset);
    Arrays.fill(buf, ' ');

    return ret;
  }
}

SampleLoginModule.java and SamplePrincipal.java

SampleLoginModule.java implements the LoginModule interface. SampleLoginModule is the class specified by the tutorial's login configuration file as the class implementing the desired underlying authentication. SampleLoginModule's user authentication consists of simply verifying that the name and password specified by the user have specific values. This SampleLoginModule is specified by the tutorial's login configuration file as the LoginModule to use because (1) It performs a basic type of authentication suitable for any environment and thus is appropriate for a tutorial for all users, and (2) It provides an example LoginModule implementation for experienced programmers who require the ability to write a LoginModule implementing an authentication technology.

SamplePrincipal.java is a sample class implementing the java.security.Principal interface. If authentication is successful, the SampleLoginModule populates a Subject with a SamplePrincipal representing the user.

Important: If you are an application writer, you do not need to know how to write a LoginModule or a Principal implementation. You do not need to examine the SampleLoginModule or SamplePrincipal code. All you have to know is how to write your application and specify configuration information (such as in a login configuration file) such that the application will be able to utilize the LoginModule specified by the configuration to authenticate the user. You need to determine which LoginModule(s) you want to use and read the LoginModule's documentation to learn about what options you can specify values for (in the configuration) to control the LoginModule's behavior.

Any vendor can provide a LoginModule implementation that you can use. Some implementations are supplied with the JRE from Sun Microsystems, as listed in the JAAS Login Configuration File document.

Information for programmers who want to write a LoginModule can be found in the JAAS LoginModule Developer's Guide.

The Login Configuration

JAAS authentication is performed in a pluggable fashion, so applications can remain independent from underlying authentication technologies. A system administrator determines the authentication technologies, or LoginModules, to be used for each application and configures them in a login Configuration. The source of the configuration information (for example, a file or a database) is up to the current javax.security.auth.login.Configuration implementation. The default Configuration implementation from Sun Microsystems reads configuration information from configuration files, as described in com.sun.security.auth.login.ConfigFile.html.

See JAAS Login Configuration File for information as to what a login configuration file is, what it contains, and how to specify which login configuration file should be used.

The Login Configuration File for This Tutorial

As noted, the login configuration file we use for this tutorial, sample_jaas.config, contains just one entry, which is

Sample {
  sample.module.SampleLoginModule required debug=true;
};

This entry is named "Sample" and that is the name that our tutorial application, SampleAcn, uses to refer to this entry. The entry specifies that the LoginModule to be used to do the user authentication is the SampleLoginModule in the sample.module package and that this SampleLoginModule is required to "succeed" in order for authentication to be considered successful. The SampleLoginModule succeeds only if the name and password supplied by the user are the one it expects ("testUser" and "testPassword", respectively).

The SampleLoginModule also defines a "debug" option that can be set to true as shown. If this option is set to true, SampleLoginModule outputs extra information about the progress of authentication. A LoginModule can define as many options as it wants. The LoginModule documentation should specify the possible option names and values you can set in your configuration file.

Running the Code

To execute our JAAS authentication tutorial code, all you have to do is

  1. Place the following file into a directory:

    • the sample_jaas.config login configuration file

  2. Create a subdirectory named "sample" of that top-level directory, and place the following into it (note the SampleAcn and MyCallbackHandler classes, both in SampleAcn.java, are in a package named sample):

    • the SampleAcn.java application source file

  3. Create a subdirectory of the "sample" directory and name it "module". Place the following into it (note the SampleLoginModule class is in a package named sample.module):

    • the SampleLoginModule.java source file

  4. Create another subdirectory of the "sample" directory and name it "principal". Place the following into it (note the SamplePrincipal class is in a package named sample.principal):

    • the SamplePrincipal.java source file

  5. While in the top-level directory, compile SampleAcn.java, SampleLoginModule.java, and SamplePrincipal.java:
    javac sample/SampleAcn.java sample/module/SampleLoginModule.java
sample/principal/SamplePrincipal.java
    (Type all that on one line.)

  6. Execute the SampleAcn application, specifying

    • by -Djava.security.auth.login.config==sample_jaas.config that the login configuration file to be used is sample_jaas.config.

The full command is below.

java -Djava.security.auth.login.config==sample_jaas.config sample.SampleAcn

You will be prompted for your user name and password, and the SampleLoginModule specified in the login configuration file will check to ensure these are correct. The SampleLoginModule expects "testUser" for the user name and "testPassword" for the password.

You will see some messages output by SampleLoginModule as a result of the debug option being set to true in the login configuration file. Then, if your login is successful, you will see the following message output by SampleAcn:

Authentication succeeded!
If the login is not successful (for example, if you misspell the password), you will see
Authentication failed:
followed by a reason for the failure. For example, if you mistype the password, you may see a message like the following:
Authentication failed:
  Password Incorrect

SampleAcn gives you three chances to successfully log in.

Running the Code with a Security Manager

When a Java program is run with a security manager installed, the program is not allowed to access resources or otherwise perform security-sensitive operations unless it is explicitly granted permission to do so by the security policy in effect. In Java platforms that are compatible with J2SE v 1.2 and later, the permission must be granted by an entry in a policy file.

Most browsers install a security manager, so applets typically run under the scrutiny of a security manager. Applications, on the other hand, do not, since a security manager is not automatically installed when an application is running. Thus an application, like our SampleAcn application, by default has full access to resources.

To run an application with a security manager, simply invoke the interpreter with a -Djava.security.manager argument included on the command line.

If you try invoking SampleAcn with a security manager but without specifying any policy file, you will get the following (unless you have a default policy setup elsewhere that grants the required permissions or grants AllPermission):

% java -Djava.security.manager \
 -Djava.security.auth.login.config==sample_jaas.config sample.SampleAcn
Exception in thread "main" java.security.AccessControlException:
  access denied (
  javax.security.auth.AuthPermission createLoginContext.Sample)

As you can see, you get an AccessControlException, because we haven't created and used a policy file granting our code the permission that is required in order to be allowed to create a LoginContext.

Here are the complete steps required in order to be able to run our SampleAcn application with a security manager installed. You can skip the first five steps if you have already done them, as described in Running the Code.

  1. Place the following file into a directory:

    • the sample_jaas.config login configuration file

  2. Create a subdirectory named "sample" of that top-level directory, and place the following into it (note the SampleAcn and MyCallbackHandler classes, both in SampleAcn.java, are in a package named sample):

    • the SampleAcn.java application source file

  3. Create a subdirectory of the "sample" directory and name it "module". Place the following into it (note the SampleLoginModule class is in a package named sample.module):

    • the SampleLoginModule.java source file

  4. Create another subdirectory of the "sample" directory and name it "principal". Place the following into it (note the SamplePrincipal class is in a package named sample.principal):

    • the SamplePrincipal.java source file

  5. While in the top-level directory, compile SampleAcn.java, SampleLoginModule.java, and SamplePrincipal.java:
    javac sample/SampleAcn.java sample/module/SampleLoginModule.java
sample/principal/SamplePrincipal.java
    (Type all that on one line.)

  6. Create a JAR file containing SampleAcn.class and MyCallbackHandler.class:
    jar -cvf SampleAcn.jar sample/SampleAcn.class
sample/MyCallbackHandler.class

    (Type all that on one line.) This command creates a JAR file, SampleAcn.jar, and places the SampleAcn.class and MyCallbackHandler.class files inside it.

  7. Create a JAR file containing SampleLoginModule.class and SamplePrincipal.class:
    jar -cvf SampleLM.jar sample/module/SampleLoginModule.class
sample/principal/SamplePrincipal.class

  8. Create a policy file granting the required permissions.

    The permission that is needed by code attempting to instantiate a LoginContext is a javax.security.auth.AuthPermission with target "createLoginContext.<entry name>". Here, <entry name> refers to the name of the login configuration file entry that the application references in its instantiation of LoginContext. The name used by our SampleAcn application's LoginContext instantiation is "Sample", as you can see in the code:

    LoginContext lc =
    new LoginContext("Sample",
          new MyCallbackHandler());

    Thus, the permission that needs to be granted to SampleAcn.jar is

    permission javax.security.auth.AuthPermission
  "createLoginContext.Sample";

    The SampleLM.jar file also needs to be granted a permission. The documentation for a LoginModule should tell you what permissions it needs to be granted. In the case of SampleLoginModule, it needs a javax.security.auth.AuthPermission with target "modifyPrincipals" in order to populate a Subject with a Principal:

    permission javax.security.auth.AuthPermission
  "modifyPrincipals";

    Copy the policy file sampleacn.policy to the same directory as that in which you stored SampleAcn.java, etc. The policy file contains the following grant statement to grant SampleAcn.jar (in the current directory) its required permission:

    grant codebase "file:./SampleAcn.jar" {
   permission javax.security.auth.AuthPermission
                    "createLoginContext.Sample";
};

    The policy file also contains the following grant statement to grant SampleLM.jar (also in the current directory) its required permission:

    grant codebase "file:./SampleAcn.jar" {
   permission javax.security.auth.AuthPermission
                    "modifyPrincipals";
};

    Note: Policy files and the structure of entries within them are described in Default Policy Implementation and Policy File Syntax. Permissions are described here.

  9. Execute the SampleAcn application, specifying

    1. by an appropriate -classpath clause that classes should be searched for in the SampleAcn.jar and SampleLM.jar JAR files,

    2. by -Djava.security.manager that a security manager should be installed,

    3. by -Djava.security.policy==sampleacn.policy that the policy file to be used is sampleacn.policy, and

    4. by -Djava.security.auth.login.config==sample_jaas.config that the login configuration file to be used is sample_jaas.config.

    Below are the full commands to use for both Microsoft Windows and Unix systems. The only difference is that on Microsoft Windows systems you use semicolons to separate classpath items, while you use colons for that purpose on Unix systems.

    Here is the full command for Microsoft Windows systems:

    java -classpath SampleAcn.jar;SampleLM.jar
 -Djava.security.manager
 -Djava.security.policy==sampleacn.policy \
 -Djava.security.auth.login.config==sample_jaas.config \
 sample.SampleAcn

    Here is the full command for UNIX systems:

    java -classpath SampleAcn.jar:SampleLM.jar
 -Djava.security.manager
 -Djava.security.policy==sampleacn.policy \
 -Djava.security.auth.login.config==sample_jaas.config \
 sample.SampleAcn

    Type all that on one line. Multiple lines are used here for legibility. If the command is too long for your system, you may need to place it in a .bat file (for Microsoft Windows) or a .sh file (for UNIX) and then run that file to execute the command.

    Since the specified policy file contains an entry granting the code the required permissions, execution should proceed without any exceptions indicating a required permission was not granted. You will be prompted for a user name and password (use "testUser" and "testPassword"), and the SampleLoginModule specified in the login configuration file will check the name and password. If your login is successful, you will see the message "Authentication succeeded!" and if not, you will see "Authentication failed:" followed by a reason for the failure.


JAAS Authorization Tutorial

This tutorial expands the program and policy file developed in the JAAS Authentication tutorial to demonstrate the JAAS authorization component, which ensures the authenticated caller has the access control rights (permissions) required to do subsequent security-sensitive operations. Since the authorization component requires that the user authentication first be completed, please read the JAAS Authentication tutorial first if you have not already done so.

The rest of this tutorial consists of the following sections:

  • What is JAAS Authorization?

  • How is JAAS Authorization Performed?

    • How Do You Make Principal-Based Policy File Statements?

    • How Do You Associate a Subject with an Access Control Context?

  • The Authorization Tutorial Code

  • The Login Configuration File

  • The Policy File

  • Running the Authorization Tutorial Code

If you want to first see the tutorial code in action, you can skip directly to Running the Authorization Tutorial Code and then go back to the other sections to learn more.

What is JAAS Authorization?

JAAS authorization extends the existing Java security architecture that uses a security policy to specify what access rights are granted to executing code. That architecture, introduced in the Java 2 platform, is code-centric. That is, the permissions are granted based on code characteristics: where the code is coming from and whether it is digitally signed and if so by whom. We saw an example of this in the sampleacn.policy file used in the JAAS Authentication tutorial. That file contains the following:

grant codebase "file:./SampleAcn.jar" {

   permission javax.security.auth.AuthPermission
                    "createLoginContext.Sample";
};

This grants the code in the SampleAcn.jar file, located in the current directory, the specified permission. (No signer is specified, so it doesn't matter whether the code is signed or not.)

JAAS authorization augments the existing code-centric access controls with new user-centric access controls. Permissions can be granted based not just on what code is running but also on who is running it.

When an application uses JAAS authentication to authenticate the user (or other entity such as a service), a Subject is created as a result. The purpose of the Subject is to represent the authenticated user. A Subject is comprised of a set of Principals, where each Principal represents an identity for that user. For example, a Subject could have a name Principal ("Susan Smith") and a Social Security Number Principal ("987-65-4321"), thereby distinguishing this Subject from other Subjects.

Permissions can be granted in the policy to specific Principals. After the user has been authenticated, the application can associate the Subject with the current access control context. For each subsequent security-checked operation (a local file access, for example), the Java runtime will automatically determine whether the policy grants the required permission only to a specific Principal and if so, the operation will be allowed only if the Subject associated with the access control context contains the designated Principal.

How is JAAS Authorization Performed?

To make JAAS authorization take place, the following is required:

  • The user must be authenticated, as described in the JAAS Authentication tutorial.

  • Principal-based entries must be configured in the security policy.

  • The Subject that is the result of authentication must be associated with the current access control context.

How Do You Make Principal-Based Policy File Statements?

Policy file grant statements can now optionally include one or more Principal fields. Inclusion of a Principal field indicates that the user or other entity represented by the specified Principal, executing the specified code, has the designated permissions.

Thus, the basic format of a grant statement is now

grant <signer(s) field>, <codeBase URL>
  <Principal field(s)> {
    permission perm_class_name "target_name", "action";
    ....
    permission perm_class_name "target_name", "action";
  };
where each of the signer, codeBase and Principal fields is optional and the order between the fields doesn't matter.

A Principal field looks like the following:

Principal Principal_class "principal_name"

That is, it is the word "Principal" (where case doesn't matter) followed by the (fully qualified) name of a Principal class and a principal name.

A Principal class is a class that implements the java.security.Principal interface. All Principal objects have an associated name that can be obtained by calling their getName method. The format used for the name is dependent on each Principal implementation.

The type of Principal placed in the Subject created by the basic authentication mechanism used by this tutorial is SamplePrincipal, so that is what should be used as the Principal_class part of our grant statement's Principal designation. User names for SamplePrincipals are of the form "name", and the only user name accepted for this tutorial is "testUser", so the principal_name designation to use in the grant statement is "testUser".

It is possible to include more than one Principal field in a grant statement. If multiple Principal fields are specified, then the permissions in that grant statement are granted only if the Subject associated with the current access control context contains all of those Principals.

To grant the same set of permissions to different Principals, create multiple grant statements where each lists the permissions and contains a single Principal field designating one of the Principals.

The policy file for this tutorial includes one grant statement with a Principal field:

grant codebase "file:./SampleAction.jar",
        Principal sample.principal.SamplePrincipal "testUser" {

   permission java.util.PropertyPermission "java.home", "read";
   permission java.util.PropertyPermission "user.home", "read";
   permission java.io.FilePermission "foo.txt", "read";
};

This specifies that the indicated permissions are granted to the specified principal executing the code in SampleAction.jar. (Note: the SamplePrincipal class is in the sample.principal package.)

How Do You Associate a Subject with an Access Control Context?

To create and associate a Subject with the current access control context, you need the following:

  • The user must first be authenticated, as described in JAAS Authentication.

  • The static doAs method from the Subject class must be called, passing it an authenticated Subject and a java.security.PrivilegedAction or java.security.PrivilegedExceptionAction. (See API for Privileged Blocks for a comparison of PrivilegedAction and PrivilegedExceptionAction.) The doAs method associates the provided Subject with the current access control context and then invokes the run method from the action. The run method implementation contains all the code to be executed as the specified Subject. The action thus executes as the specified Subject.

    The static doAsPrivileged method from the Subject class may be called instead of the doAs method, as will be done for this tutorial. In addition to the parameters passed to doAs, doAsPrivileged requires a third parameter: an AccessControlContext. Unlike doAs, which associates the provided Subject with the current access control context, doAsPrivileged associates the Subject with the provided access control context or with an empty access control context if the parameter passed in is null, as is the case for this tutorial. See doAs vs. doAsPrivileged in the JAAS Reference Guide for a comparison of those methods.

The Authorization Tutorial Code

The code for this tutorial consists of four files:

  • SampleAzn.java is exactly the same as the SampleAcn.java application file from the JAAS Authentication tutorial except for the additional code needed to call Subject.doAsPrivileged.

  • SampleAction.java contains the SampleAction class. This class implements PrivilegedAction and has a run method that contains all the code we want to be executed with Principal-based authorization checks.

  • SampleLoginModule.java is the class specified by the tutorial's login configuration file as the class implementing the desired underlying authentication. SampleLoginModule's user authentication consists of simply verifying that the name and password specified by the user have specific values. This class was also used by the JAAS Authentication tutorial and will not be discussed further here.

  • SamplePrincipal.java is a sample class implementing the java.security.Principal interface. It is used by SampleLoginModule. This class was also used by the JAAS Authentication tutorial and will not be discussed further here.

The SampleLoginModule.java and SamplePrincipal.java files were also used in the JAAS Authentication tutorial, so they are not described further here. The other source files are described below.

SampleAzn.java

Like SampleAcn, the SampleAzn class instantiates a LoginContext lc and calls its login method to perform the authentication. If successful, the authenticated Subject (which includes a SamplePrincipal representing the user) is obtained by calling the LoginContext's getSubject method:

Subject mySubject = lc.getSubject();

After providing the user some information about the Subject, such as which Principals it has, the main method then calls Subject.doAsPrivileged, passing it the authenticated Subject mySubject, a PrivilegedAction (SampleAction) and a null AccessControlContext, as described in the following.

The SampleAction class is instantiated via the following:

PrivilegedAction action = new SampleAction();

The call to Subject.doAsPrivileged is performed via:

Subject.doAsPrivileged(mySubject, action, null);

The doAsPrivileged method invokes execution of the run method in the PrivilegedAction action (SampleAction) to initiate execution of the rest of the code, which is considered to be executed on behalf of the Subject mySubject.

Passing null as the AccessControlContext (third) argument to doAsPrivileged indicates that mySubject should be associated with a new empty AccessControlContext. The result is that security checks occurring during execution of SampleAction will only require permissions for the SampleAction code itself (or other code it invokes), running as mySubject. Note that the caller of doAsPrivileged (and the callers on the execution stack at the time doAsPrivileged was called) do not require any permissions while the action executes.

SampleAction.java

SampleAction.java contains the SampleAction class. This class implements java.security.PrivilegedAction and has a run method that contains all the code we want to be executed as the Subject mySubject. For this tutorial, we will perform three operations, each of which cannot be done unless code has been granted required permissions. We will:

  • Read and print the value of the java.home system property,

  • Read and print the value of the user.home system property, and

  • Determine whether or not a file named foo.txt exists in the current directory.

Here is the code:

package sample;

import java.io.File;
import java.security.PrivilegedAction;

public class SampleAction implements PrivilegedAction {

  public Object run() {

    System.out.println("\nYour java.home property value is: "
                + System.getProperty("java.home"));

    System.out.println("\nYour user.home property value is: "
                + System.getProperty("user.home"));

    File f = new File("foo.txt");
    System.out.print("\nfoo.txt does ");
    if (!f.exists())
        System.out.print("not ");
    System.out.println("exist in the current working directory.");
    return null;
  }
}

The Login Configuration File

The login configuration file used for this tutorial can be exactly the same as that used by the JAAS Authentication tutorial. Thus we can use sample_jaas.config, which contains just one entry:

Sample {
  sample.module.SampleLoginModule required debug=true;
};

This entry is named "Sample" and that is the name that both our tutorial applications SampleAcn and SampleAzn use to refer to it. The entry specifies that the LoginModule to be used to do the user authentication is the SampleLoginModule in the sample.module package and that this SampleLoginModule is required to "succeed" in order for authentication to be considered successful. The SampleLoginModule succeeds only if the name and password supplied by the user are the one it expects ("testUser" and "testPassword", respectively).

The SampleLoginModule also defines a "debug" option that can be set to true as shown. If this option is set to true, SampleLoginModule outputs extra information about the progress of authentication.

The Policy File

The application for this authorization tutorial consists of two classes, SampleAzn and SampleAction. The code in each class contains some security-sensitive operations and thus relevant permissions are required in a policy file in order for the operations to be executed.

The LoginModule used by this tutorial, SampleLoginModule, also contains an operation requiring a permission.

The permissions required by each of these classes are described below, followed by a link to the full policy file.

Permissions Required by SampleAzn

The main method of the SampleAzn class does two operations for which permissions are required. It

  • creates a LoginContext, and

  • calls the doAsPrivileged static method of the Subject class.

The LoginContext creation is exactly the same as was done in the authentication tutorial, and it thus needs the same javax.security.auth.AuthPermission permission with target "createLoginContext.Sample".

In order to call the doAsPrivileged method of the Subject class, you need to have a javax.security.auth.AuthPermission with target "doAsPrivileged".

Assuming the SampleAzn class is placed in a JAR file named SampleAzn.jar, these permissions can be granted to the SampleAzn code via the following grant statement in the policy file:

grant codebase "file:./SampleAzn.jar" {
   permission javax.security.auth.AuthPermission
                    "createLoginContext.Sample";
   permission javax.security.auth.AuthPermission "doAsPrivileged";
};

Permissions Required by SampleAction

The SampleAction code does three operations for which permissions are required. It

  • reads the value of the "java.home" system property.

  • reads the value of the "user.home" system property.

  • checks to see whether or not a file named foo.txt exists in the current directory.

The permissions required for these operations are the following:

permission java.util.PropertyPermission "java.home", "read";
permission java.util.PropertyPermission "user.home", "read";
permission java.io.FilePermission "foo.txt", "read";

We need to grant these permissions to the code in SampleAction.class, which we will place in a JAR file named SampleAction.jar. However, for this particular grant statement we want to grant the permissions not just to the code but to a specific user executing the code, to demonstrate how to restrict access to a particular user.

Thus, as explained in How Do You Make Principal-Based Policy File Statements?, our grant statement looks like the following:

grant codebase "file:./SampleAction.jar",
    Principal sample.principal.SamplePrincipal "testUser" {

   permission java.util.PropertyPermission "java.home", "read";
   permission java.util.PropertyPermission "user.home", "read";
   permission java.io.FilePermission "foo.txt", "read";
};

Permissions Required by SampleLoginModule

The SampleLoginModule code does one operation for which permissions are required. It needs a javax.security.auth.AuthPermission with target "modifyPrincipals" in order to populate a Subject with a Principal. The grant statement is the following:

grant codebase "file:./SampleLM.jar" {
    permission javax.security.auth.AuthPermission "modifyPrincipals";
};

The Full Policy File

The full policy file is sampleazn.policy.

Running the Authorization Tutorial Code

To execute our JAAS authorization tutorial code, all you have to do is

  1. Place the following files into a directory:

    • The sample_jaas.config login configuration file.
    • The sampleazn.policy policy file.

  2. Create a subdirectory named "sample" of that top-level directory, and place the following into it (note the SampleAzn and SampleAction classes are in a package named sample):

    • The SampleAzn.java source file.
    • The SampleAction.java source file.

  3. Create a subdirectory of the "sample" directory and name it "module". Place the following into it (note the SampleLoginModule class is in a package named sample.module):

    • the SampleLoginModule.java source file

  4. Create another subdirectory of the "sample" directory and name it "principal". Place the following into it (note the SamplePrincipal class is in a package named sample.principal):

    • the SamplePrincipal.java source file

  5. While in the top-level directory, compile all the source files:
    javac sample/SampleAction.java sample/SampleAzn.java
sample/module/SampleLoginModule.java sample/principal/SamplePrincipal.java
    (Type all that on one line.)

  6. Create a JAR file named SampleAzn.jar containing SampleAzn.class and MyCallbackHandler.class (Note the sources for both these classes are in SampleAzn.java):
    jar -cvf SampleAzn.jar sample/SampleAzn.class
sample/MyCallbackHandler.class

    (Type all that on one line.)

  7. Create a JAR file named SampleAction.jar containing SampleAction.class:
    jar -cvf SampleAction.jar sample/SampleAction.class
  8. Create a JAR file containing SampleLoginModule.class and SamplePrincipal.class:
    jar -cvf SampleLM.jar sample/module/SampleLoginModule.class
sample/principal/SamplePrincipal.class

  9. Execute the SampleAzn application, specifying

    1. by an appropriate -classpath clause that classes should be searched for in the SampleAzn.jar, SampleAction.jar, and SampleLM.jar JAR files,

    2. by -Djava.security.manager that a security manager should be installed,

    3. by -Djava.security.policy==sampleazn.policy that the policy file to be used is sampleazn.policy, and

    4. by -Djava.security.auth.login.config==sample_jaas.config that the login configuration file to be used is sample_jaas.config.

    Below are the full commands to use for both Microsoft Windows and Unix systems. The only difference is that on Windows systems you use semicolons to separate classpath items, while you use colons for that purpose on Unix systems.

    Here is the full command for Windows systems:

    java -classpath SampleAzn.jar;SampleAction.jar;SampleLM.jar
 -Djava.security.manager
 -Djava.security.policy==sampleazn.policy
 -Djava.security.auth.login.config==sample_jaas.config sample.SampleAzn

    Here is the full command for UNIX systems:

    java -classpath SampleAzn.jar:SampleAction.jar:SampleLM.jar
 -Djava.security.manager
 -Djava.security.policy==sampleazn.policy
 -Djava.security.auth.login.config==sample_jaas.config sample.SampleAzn

    Type the full command on one line. Multiple lines are used here for legibility. If the command is too long for your system, you may need to place it in a .bat file (for Windows) or a .sh file (for UNIX) and then run that file to execute the command.

    You will be prompted for a user name and password (use "testUser" and "testPassword"), and the SampleLoginModule specified in the login configuration file will check the name and password. If your login is successful, you will see the message "Authentication succeeded!" and if not, you will see "Authentication failed:" followed by a reason for the failure.

    Once authentication is successfully completed, the rest of the program (in SampleAction) will be executed on behalf of you, the user, requiring you to have been granted appropriate permissions. The sampleazn.policy policy file grants you the required permissions, so you will see a display of the values of your java.home and user.home system properties and a statement as to whether or not you have a file named foo.txt in the current directory.


JAAS Login Configuration File

JAAS authentication is performed in a pluggable fashion, so Java applications can remain independent from underlying authentication technologies. Configuration information such as the desired authentication technology is specified at runtime. The source of the configuration information (for example, a file or a database) is up to the current javax.security.auth.login.Configuration implementation. The default Configuration implementation from Sun Microsystems reads configuration information from configuration files, which are described in this document.

Login Configuration File Structure and Contents

A login configuration file consists of one or more entries, each specifying which underlying authentication technology should be used for a particular application or applications. The structure of each entry is the following:

<name used by application to refer to this entry> {
    <LoginModule> <flag> <LoginModule options>;
    <optional additional LoginModules, flags and options>;
    };

Thus, each login configuration file entry consists of a name followed by one or more LoginModule-specific entries, where each LoginModule-specific entry is terminated by a semicolon and the entire group of LoginModule-specific entries is enclosed in braces. Each configuration file entry is terminated by a semicolon.

As an example, the login configuration file used for the JAAS Authentication tutorial contains just one entry, which is

Sample {
   sample.module.SampleLoginModule required debug=true;
};

Here, the entry is named "Sample" and that is the name that the JAAS Authentication tutorial application (SampleAcn.java) uses to refer to this entry. The entry specifies that the LoginModule to be used to do the user authentication is the SampleLoginModule in the sample.module package and that this SampleLoginModule is required to "succeed" in order for authentication to be considered successful. The SampleLoginModule succeeds only if the name and password supplied by the user are the ones it expects ("testUser" and "testPassword", respectively).

The name for an entry in a login configuration file is the name that applications use to refer to the entry when they instantiate a LoginContext, as described in Instantiating a LoginContext in the JAAS authentication tutorial. The name can be whatever name the application developer wishes to use. Here, the term "application" refers to whatever code does the JAAS login.

The specified LoginModules (described below) are used to control the authentication process. Authentication proceeds down the list in the exact order specified, as described here.

The subparts of each LoginModule-specific entry are the following:

  • LoginModule

    This specifies a class implementing the desired authentication technology. Specifically, the class must be a subclass of the LoginModule class, which is in the javax.security.auth.spi package. A typical LoginModule may prompt for and verify a user name and password, as is done by the SampleLoginModule (in the sample.module package) used for these tutorials. Any vendor can provide a LoginModule implementation that you can use. Some implementations are supplied with the JRE from Sun Microsystems. You can view the reference documentation for the various LoginModules, all in the com.sun.security.auth package:

    • JndiLoginModule
    • KeyStoreLoginModule
    • Krb5LoginModule
    • NTLoginModule
    • UnixLoginModule

  • flag

    The flag value indicates whether success of the preceding LoginModule is "required", "requisite", "sufficient", or "optional". If there is just one LoginModule-specific entry, as there is in our tutorials, then the flag for it should be "required". The options are described in more detail here.

  • LoginModule options

    If the specified LoginModule implementation has options that can be set, you specify any desired option values here. This is a space-separated list of values which are passed directly to the underlying LoginModule. Options are defined by the LoginModule itself, and control the behavior within it. For example, a LoginModule may define options to support debugging/testing capabilities.

    The correct way to specify options in the configuration file is by using a name-value pairing, for example debug=true, where the option name (in this case, "debug") and value (in this case, "true") should be separated by an "equals" symbol.

Where to Specify Which Login Configuration File Should Be Used

The configuration file to be used can be specified in one of two ways:

  1. On the command line.

    You can use a -Djava.security.auth.login.config interpreter command line argument to specify the login configuration file that should be used. We use this approach for all the tutorials. For example, we run our SampleAcn application in the JAAS Authentication tutorial using the following command, which specifies that the configuration file is the sample_jaas.config file in the current directory:

    java -Djava.security.auth.login.config==sample_jaas.config sample.SampleAcn
  2. In the Java security properties file.

    An alternate approach to specifying the location of the login configuration file is to indicate its URL as the value of a login.config.url.n property in the security properties file. The security properties file is the java.security file located in the lib/security directory of the JRE.

    Here, n indicates a consecutively-numbered integer starting with 1. Thus, if desired, you can specify more than one login configuration file by indicating one file's URL for the login.config.url.1 property, a second file's URL for the login.config.url.2 property, and so on. If more than one login configuration file is specified (that is, if n > 1), then the files are read and concatenated into a single configuration.

    Here is an example of what would need to be added to the security properties file in order to indicate the sample_jaas.config login configuration file used by this tutorial. This example assumes the file is in the C:\AcnTest directory on a Microsoft Windows system:

    login.config.url.1=file:C:/AcnTest/sample_jaas.config
    (Note that URLs always use forward slashes, regardless of what operating system the user is running.)


JAAS Tutorials

This page links to two tutorials demonstrating various aspects of the use of JAAS (JavaTM Authentication and Authorization Service):

  1. JAAS Authentication

    Explains how an application can authenticate users using JAAS.

  2. JAAS Authorization

    Explains how to enforce user-based access controls using JAAS.

The authentication technology used for these tutorials is very basic, just ensuring that the user specifies a particular name and password. Thus, these tutorials can be run by everyone.

Related Documentation

API Specifications

  • com.sun.security.auth Package
  • com.sun.security.auth.callback Package
  • com.sun.security.auth.login Package
  • com.sun.security.auth.module Package

User Guides

  • JavaTM Authentication and Authorization Service (JAAS) Reference Guide.

Papers

  • JAAS white paper

Tutorials

  • Similar tutorials for JAAS authentication and authorization, but which demonstrate the use of a Kerberos LoginModule and thus which require a Kerberos installation, can be found at

    • JAAS Authentication
    • JAAS Authorization

    These two tutorials are a part of the Java GSS-API and JAAS sequence of tutorials that utilize Kerberos as the underlying technology for authentication and secure communication.

  • Java 2 Security Tutorial

Other Java Security Documentation

  • J2SDK 1.4 Security Documentation
Copyright © 2001-2002 Sun Microsystems, Inc. All Rights Reserved.


Subjects, Principals, Authentication, and Credentials

To authorize access to resources, applications first need to authenticate the source of the request. The JAAS framework defines the term subject to represent the source of a request. A subject may be any entity, such as a person or service. A subject is represented by the javax.security.auth.Subject class.

Authentication represents the process by which the identity of a subject is verified, and must be performed in a secure fashion; otherwise a perpetrator may impersonate others to gain access to a system. Authentication typically involves the subject demonstrating some form of evidence to prove its identity. Such evidence may be information only the subject would likely know or have (such as a password or fingerprint), or it may be information only the subject could produce (such as signed data using a private key).

Once authenticated, a Subject is populated with associated identities, or Principals (of type java.security.Principal). A Subject may have many Principals. For example, a person may have a name Principal ("John Doe") and an SSN Principal ("123-45-6789"), which distinguish it from other Subjects.

In addition to associated Principals, a Subject may own security-related attributes, which are referred to as credentials. A credential may contain information used to authenticate the subject to new services. Such credentials include passwords, Kerberos tickets, and public key certificates. Credentials might also contain data that simply enables the subject to perform certain activities. Cryptographic keys, for example, represent credentials that enable the subject to sign or encrypt data. Public and private credential classes are not part of the core JAAS class library. Any class, therefore, can represent a credential.


Java GSS/Kerberos in J2SE 5

Java Generic Security Services (Java GSS) and Kerberos
Enhancements for J2SE 5

IMPORTANT NOTE: The APIs and features described in this document are SUBJECT TO CHANGE.

The following enhancements were made to the Java GSS/Kerberos implementation in J2SE 5. Please send feedback related to these new features to java-security@sun.com.

  • Support for Triple DES encryption type.
    Prior to J2SE 5, only the DES encryption type was supported. J2SE 5 supports both DES and Triple DES encryption type. This improves interoperability of the Java SE Kerberos implementation with other Kerberos implementations, such as Solaris 10 and MIT Kerberos.

    Triple DES encryption type is specified in the Kerberos configuration file under the "libdefaults" section. It is specified as "des3-cbc-sha1" with following tags: default_tkt_enctypes, default_tgs_enctypes, permitted_enctypes. "dec3-cbc-sha1" has the following aliases:

    des3-hmac-sha1
des3-cbc-sha1-kd
des3-cbc-hmac-sha1-kd
    For example, the libdefaults section in the configuration file might include the following.
    default_tkt_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc
default_tgs_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc
permitted_enctypes   = des3-cbc-sha1 des-cbc-md5 des-cbc-crc
    default_tkt_enctypes is used to specify the encryption types to use for the session key in the ticket-granting-ticket. It is used by the client to restrict the encryption types of session keys that will be used to communicate with the KDC. The default value is "des-cbc-md5 des-cbc-crc des3-cbc-sha1"

    default_tgs_enctypes is used to specify the encryption types to use for the session key in service tickets. It is used by the client to restrict the encryption types of session keys that are shared by the client and server. The default value is "des-cbc-md5 des-cbc-crc des3-cbc-sha1".

    permitted_enctypes is used to specify the encryption types permitted to be used by a service. It is used by the server to restrict the encryption types of session keys that it will accept. The default value is "des-cbc-md5 des-cbc-crc des3-cbc-sha1".

  • TCP vs. UDP Preference Configuration
    Java SE now supports the use of the "udp_preference_limit" property in the Kerberos configuration file (krb5.conf).

    When sending a message to the KDC, the Java SE Kerberos library will use TCP if the size of the message is above udp_preference_list. If the message is smaller than udp_preference_list, then UDP will be tried at most three times. If the KDC indicates that the request is too big, the Java SE Kerberos library will use TCP.

  • IPv6 Support in Kerberos
    Java SE now supports IPv6 addresses in Kerberos tickets. Prior to J2SE 5, only IPv4 addresses were supported in tickets.

  • TGT Renewals
    The Java Authentication and Authorizaton Server (JAAS) Kerberos login module in JDK 5.0, Krb5LoginModule, now supports Ticket Granting Ticket (TGT) renewal. This allows long-running services to renew their TGT automatically without user interaction or requiring the services to restart.

    With this feature, if Krb5LoginModule obtains an expired ticket from the ticket cache, the TGT will be automatically renewed and be added to Subject of the caller who requested the ticket. If the ticket cannot be renewed for any reason, then Krb5LoginModule will use its configured callback handler to retrieve a username and password to acquire a new TGT.

    To use this feature, configure Krb5LoginModule to use the ticket cache and set the newly introduced renewTGT option to true. Here is an example of a JAAS login configuration file that requests TGT renewal.

    server {
  com.sun.security.auth.module.Krb5LoginModule required
        principal=principal@your_realm
    useTicketCache=true
    renewTGT=true;
};
    Note that if renewTGT is set to true, then useTicketCache must also be set to true; otherwise, it results in a configuration error.

  • Login Entry Names for SunJSSE
    In JDK 5.0, the SunJSSE provider has added support for the Kerberos cipher suites, as described in RFC 2712 and the What's New in JSSE in J2SE 5 in the JSSE Reference Guide. The following JAAS login configuration index names are reserved for this feature.
    com.sun.net.ssl.server
com.sun.net.ssl.client
    When a JSSE application uses the Kerberos cipher suites without explicit JAAS program, the SunJSSE provider will use these index names to find and configure the JAAS login module to acquire the necessary Kerberos credentials. For example, such an application might have the following JAAS configuration file.
     com.sun.net.ssl.server {
  com.sun.security.auth.module.Krb5LoginModule required
        principal=service_principal@your_realm
        useKeyTab=true
        keyTab=keytab_name
    storeKey=true;
};
    If the entry is not found, the default "other" index name will be used. The service name for TLS is "host". For example, a TLS service running on a machine named "raven.abc.com" in the realm named "KRBNT-OPERATIONS.ABC.COM" would have the service principal name
    host/raven.abc.com@KRBNT-OPERATIONS.ABC.COM
    There are no restrictions on the TLS client; it may use any valid Kerberos principal name.

    When a JSSE application uses the Kerberos cipher suites with explicit JAAS program, it can use any index name, including the ones listed above.


JGSS Enhancements List for Java™ 6

Java

Java Generic Security Services (Java GSS)

and Kerberos Enhancements for JavaTM 6

The following enhancements were added to the Java GSS/Kerberos implementation in Java SE 6. For details, see the JGSS Feature Enhancements List.

  • Support for AES Encryption Type

    Support for AES encryption type (AES128 and AES256) in Java GSS/Kerberos is available. This improves interoperability of the Java SE Kerberos implementation with other Kerberos implementations, such as Solaris 10 and MIT Kerberos.

  • Support for RC4-HMAC Encryption Type

    Support for RC4-HMAC encryption type in Java GSS/Kerberos is available. This improves interoperability of the Java SE Kerberos implementation with other Kerberos implementations, such as Windows, Solaris 10 and MIT Kerberos. Windows Active Directoiory supports RC4-HMAC as the default Kerberos encryption type.

  • Support for SPNEGO in Java GSS

    Support for SPNEGO mechanism in Java GSS is now available. The Simple and Protected GSS-API Negotiation (SPNEGO) mechanism is a pseudo security mechanism that enables GSS-API peers to securely negotiate a common security mechanism to be used.

    Support for SPNEGO authentication scheme in HTTP is also available.

  • Support for new Pre-Authentication Mechanisms

    Java GSS/Kerberos now includes support for the new pre-authentication mechanisms as described in the latest Kerberos specification.

  • Native Platform GSS Integration

    This feature allows Java GSS applications to take advantage of features in the native GSS implementation available on the platform.

Copyright © 1995-2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: java-security@sun.com. 		Sun
Java Software


JGSS Security Enhancement List

Java

Java Generic Security Services
(Java GSS) and Kerberos

Feature Enhancements added to JavaTM

 Security Contents

This page describes and lists security features and enhancements added to JavaTM by major version number, from v1.4 through v6.

NOTE: The APIs and features described in this document are subject to change.

Java Generic Security Services (Java GSS) and Kerberos Enhancements for JavaTM SE 6

The following enhancements were added to the Java GSS/Kerberos implementation in Java SE 6.

  • Support for AES encryption type

    J2SE 5.0 supports DES and Triple DES encryption type, with following aliases:

    des-cbc-md5
    des-cbc-crc
    des3-cbc-sha1

    Starting from Java SE 6, support for AES encryption type (AES128 and AES256) in Java GSS/Kerberos is available. This improves interoperability of the Java SE Kerberos implementation with other Kerberos implementations, such as Solaris 10 and MIT Kerberos.

    AES encryption type is specified in the Kerberos configuration file under the libdefaults section. It is specified as follows, with following tags: default_tkt_enctypes, default_tgs_enctypes, permitted_enctypes.

    (AES128 encryption type)

    aes128-cts
    aes128-cts-hmac-sha1-96

    (AES256 encryption type)

    aes256-cts
    aes256-cts-hmac-sha1-96

    NOTE: The JCE framework within JDK includes an ability to enforce restrictions regarding the cryptographic algorithms and maximum cryptographic strengths available to applications. Such restrictions are specified in "jurisdiction policy files". The jurisdiction policy files bundled in Java SE limits the maximum key length. Hence, in order to use AES256 encryption type, you will need to install the JCE crypto policy with the unlimited version to allow AES with 256-bit key.

    For example, the libdefaults section in the configuration file might include the following.

    default_tkt_enctypes = aes128-cts des3-cbc-sha1 des-cbc-md5 des-cbc-crc
    default_tgs_enctypes = aes128-cts des3-cbc-sha1 des-cbc-md5 des-cbc-crc
    permitted_enctypes = aes128-cts des3-cbc-sha1 des-cbc-md5 des-cbc-crc

    default_tkt_enctypes is used to specify the encryption types to use for the session key in the ticket-granting-ticket. It is used by the client to restrict the encryption types of session keys that will be used to communicate with the KDC. The default value is des-cbc-md5 des-cbc-crc des3-cbc-sha1 aes128-cts .

    default_tgs_enctypes is used to specify the encryption types to use for the session key in service tickets. It is used by the client to restrict the encryption types of session keys that are shared by the client and server. The default value is des-cbc-md5 des-cbc-crc des3-cbc-sha1 aes128-cts.

    permitted_enctypes is used to specify the encryption types permitted to be used by a service. It is used by the server to restrict the encryption types of session keys that it will accept. The default value is des-cbc-md5 des-cbc-crc des3-cbc-sha1 aes128-cts.

  • Support for RC4-HMAC encryption type

    J2SE 5.0 already supports DES and Triple DES encryption type, with following aliases:
    des-cbc-md5
    des-cbc-crc
    des3-cbc-sha1

    Starting from Java SE 6, support for RC4-HMAC encryption type in Java GSS/Kerberos is available. This improves interoperability of the Java SE Kerberos implementation with other Kerberos implementations, such as Windows, Solaris 10 and MIT Kerberos. Windows Active Directoiory supports RC4-HMAC as the default Kerberos encryption type.

    RC4-HMAC encryption type is specified in the Kerberos configuration file under the libdefaults section. It is specified as follows, with following tags: default_tkt_enctypes, default_tgs_enctypes, permitted_enctypes.

    rc4-hmac
    arcfour-hmac
    arcfour-hmac-md5

    For example, the libdefaults section in the configuration file might include the following.

    default_tkt_enctypes = aes128-cts des3-cbc-sha1 rc4-hmac des-cbc-md5 des-cbc-crc
    default_tgs_enctypes = aes128-cts des3-cbc-sha1 rc4-hmac des-cbc-md5 des-cbc-crc
    permitted_enctypes = aes128-cts des3-cbc-sha1 rc4-hmac des-cbc-md5 des-cbc-crc

    default_tkt_enctypes is used to specify the encryption types to use for the session key in the ticket-granting-ticket. It is used by the client to restrict the encryption types of session keys that will be used to communicate with the KDC. The default value is des-cbc-md5 des-cbc-crc rc4-hmac des3-cbc-sha1 aes128-cts

    default_tgs_enctypes is used to specify the encryption types to use for the session key in service tickets. It is used by the client to restrict the encryption types of session keys that are shared by the client and server. The default value is des-cbc-md5 des-cbc-crc rc4-hmac des3-cbc-sha1 aes128-cts.

    permitted_enctypes is used to specify the encryption types permitted to be used by a service. It is used by the server to restrict the encryption types of session keys that it will accept. The default value is des-cbc-md5 des-cbc-crc rc4-hmac des3-cbc-sha1 aes128-cts.

  • Support for SPNEGO in Java GSS

    Java SE now supports SPNEGO mechanism in Java GSS.

    Java GSS is a framework that can support multiple security mechanisms; however GSS-API does not prescribe the method by which GSS-API peers can establish whether they have a common security mechanism. The Simple and Protected GSS-API Negotiation (SPNEGO) mechanism is a pseudo security mechanism that enables GSS-API peers to securely negotiate a common security mechanism to be used. The SPNEGO protocol is used to negotiate which security mechanism should be adopted.

    Currently Java GSS applications specify a unique object identifier (OID) to select the underlying security mechanism. For e.g. Java GSS applications specify Kerberos mechanism OID "1.2.840.113554.1.2.2 to use Kerberos mechanism. Oid mechOid = new Oid("1.2.840.113554.1.2.2");

    To select SPNEGO security mechanism, Java GSS applications would need to specify the SPNEGO mechanism OID "1.3.6.1.5.5.2". Oid mechOid = new Oid("1.3.6.1.5.5.2);

    Support for SPNEGO improves interoperability with Microsoft products. SPNEGO protocol is heavily used to interoperate with Microsoft server over HTTP, to support HTTP-Based Cross-Platform Authentication via the Negotiate Protocol. Java SE now supports SPNEGO authentication scheme in HTTP as well. Please check list of new networking features for Java SE 6.

  • Support for new Pre-Authentication mechanisms

    Java SE now includes support for the new pre-authentication mechanisms.

    Kerberos is a protocol for verifying the identity of principals. The Kerberos protocol provides a mechanism called pre-authentication for proving the identity of a principal and for better protecting the long-term secret of the principal.

    Kerberos specification defines a framework for Kerberos pre-authentication mechanisms. Lastest Kerberos specification defines new pre-authentication mechanisms to notify the client which key to use, salt updates, and other additional parameters. The new pre-authentication mechanisms indicate a requirement for additional pre-authentication.

    With the support of new pre-authentication mechanisms, Java GSS/Kerberos client can now handle the salt value updates when required.

  • Native platform GSS integration

    This feature allows Java applications to take advantage of features in native GSS implementation available on the platform. To enable Java GSS to delegate to the native GSS library and its list of native mechanisms, set the system property "sun.security.jgss.native" to true. When enabled, Java GSS would look for native GSS library using the operating system specific name, e.g. Solaris: libgss.so vs Linux: libgssapi.so. If the desired GSS library has a different name or is not located under a directory for system libraries, then its full path should be specified using the system property "sun.security.jgss.lib".

    For Java SE 6, the native GSS support is limited to Solaris and Linux. Setting these system properties on platforms which native GSS integration is not supported will be ignored.

    Unlike the default Java GSS implementation which relies on JAAS KerberosLoginModule for initial credential acquisition, when using native GSS, the initial credential should be acquired beforehand, e.g. kinit, prior to calling JGSS APIs.

    In addition, when performing operations as a particular Subject, e.g. Subject.doAs(...) or Subject.doAsPrivileged(...), the to-be-used GSSCredential should be added to Subject's private credential set. Otherwise, the GSS operations will fail since no credential is found.

  • JAAS Login Entry Names Changes

    The JAAS login entry names for both SunJSSE and JGSS are unified, and can be specified separately for different mechanisms. For Kerberos 5, the names are
    com.sun.security.jgss.krb5.initiate
com.sun.security.jgss.krb5.accept

Java Generic Security Services (Java GSS) and Kerberos Enhancements for J2SE 5.0

The following enhancements were added to the Java GSS/Kerberos implementation in J2SE 5.0.

  • Support for Triple DES encryption type.
    Prior to J2SE 5.0, only the DES encryption type was supported. J2SE 5.0 supports both DES and Triple DES encryption type. This improves interoperability of the Java SE Kerberos implementation with other Kerberos implementations, such as Solaris 10 and MIT Kerberos.

    Triple DES encryption type is specified in the Kerberos configuration file under the "libdefaults" section. It is specified as "des3-cbc-sha1" with following tags: default_tkt_enctypes, default_tgs_enctypes, permitted_enctypes. "dec3-cbc-sha1" has the following aliases:

    des3-hmac-sha1
des3-cbc-sha1-kd
des3-cbc-hmac-sha1-kd
    For example, the libdefaults section in the configuration file might include the following.
    default_tkt_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc
default_tgs_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc
permitted_enctypes   = des3-cbc-sha1 des-cbc-md5 des-cbc-crc
    default_tkt_enctypes is used to specify the encryption types to use for the session key in the ticket-granting-ticket. It is used by the client to restrict the encryption types of session keys that will be used to communicate with the KDC. The default value is "des-cbc-md5 des-cbc-crc des3-cbc-sha1"

    default_tgs_enctypes is used to specify the encryption types to use for the session key in service tickets. It is used by the client to restrict the encryption types of session keys that are shared by the client and server. The default value is "des-cbc-md5 des-cbc-crc des3-cbc-sha1".

    permitted_enctypes is used to specify the encryption types permitted to be used by a service. It is used by the server to restrict the encryption types of session keys that it will accept. The default value is "des-cbc-md5 des-cbc-crc des3-cbc-sha1".

  • TCP vs. UDP Preference Configuration
    Java SE now supports the use of the "udp_preference_limit" property in the Kerberos configuration file (krb5.conf).

    When sending a message to the KDC, the Java SE Kerberos library will use TCP if the size of the message is above udp_preference_list. If the message is smaller than udp_preference_list, then UDP will be tried at most three times. If the KDC indicates that the request is too big, the Java SE Kerberos library will use TCP.

  • IPv6 Support in Kerberos
    Java SE now supports IPv6 addresses in Kerberos tickets. Prior to J2SE 5, only IPv4 addresses were supported in tickets.

  • TGT Renewals
    The Java Authentication and Authorizaton Server (JAAS) Kerberos login module in JDK 5.0, Krb5LoginModule, now supports Ticket Granting Ticket (TGT) renewal. This allows long-running services to renew their TGT automatically without user interaction or requiring the services to restart.

    With this feature, if Krb5LoginModule obtains an expired ticket from the ticket cache, the TGT will be automatically renewed and be added to Subject of the caller who requested the ticket. If the ticket cannot be renewed for any reason, then Krb5LoginModule will use its configured callback handler to retrieve a username and password to acquire a new TGT.

    To use this feature, configure Krb5LoginModule to use the ticket cache and set the newly introduced renewTGT option to true. Here is an example of a JAAS login configuration file that requests TGT renewal.

    server {
  com.sun.security.auth.module.Krb5LoginModule required
        principal=principal@your_realm
    useTicketCache=true
    renewTGT=true;
};
    Note that if renewTGT is set to true, then useTicketCache must also be set to true; otherwise, it results in a configuration error.

  • Login Entry Names for SunJSSE
    In JDK 5.0, the SunJSSE provider has added support for the Kerberos cipher suites, as described in RFC 2712 and the What's New in JSSE in J2SE 5.0 in the JSSE Reference Guide. The following JAAS login configuration index names are reserved for this feature.
    com.sun.net.ssl.server
com.sun.net.ssl.client
    When a JSSE application uses the Kerberos cipher suites without explicit JAAS program, the SunJSSE provider will use these index names to find and configure the JAAS login module to acquire the necessary Kerberos credentials. For example, such an application might have the following JAAS configuration file.
     com.sun.net.ssl.server {
  com.sun.security.auth.module.Krb5LoginModule required
        principal=service_principal@your_realm
        useKeyTab=true
        keyTab=keytab_name
    storeKey=true;
};
    If the entry is not found, the default "other" index name will be used. The service name for TLS is "host". For example, a TLS service running on a machine named "raven.abc.com" in the realm named "KRBNT-OPERATIONS.ABC.COM" would have the service principal name
    host/raven.abc.com@KRBNT-OPERATIONS.ABC.COM
    There are no restrictions on the TLS client; it may use any valid Kerberos principal name.

    When a JSSE application uses the Kerberos cipher suites with explicit JAAS program, it can use any index name, including the ones listed above.

New Features in JavaTM GSS for Java TM 2 SDK, Standard Edition, v 1.4.2

  • Configurable Kerberos Settings
    The Kerberos Key Distribution Center (KDC) name and realm settings are provided in the Kerberos configuration file or via the system properties java.security.krb5.kdc and java.security.krb5.realm. In previous releases, changes to the Kerberos configuration values would only take effect when an application was restarted.

    In the 1.4.2 release of the Java platform, a new boolean option refreshKrb5Config can be specified in the entry for Krb5LoginModule in the JAAS configuration file. If this option is set to true, the configuration values will be refreshed before the login method of the Krb5LoginModule is called.

  • Support for Slave Kerberos Key Distribution Center
    Kerberos allows the use of slave KDCs so that if the master KDC is unavailable, the slave KDCs will respond to user requests. In earlier releases of the Java SE, Sun's implementation of Kerberos tried only the master KDC and would give up if there was no response within the default KDC timeout specified in the Kerberos configuration file, or 30 seconds if no timeout had been specified.

    With this 1.4.2 release, Sun's implementation of Kerberos will retry with the slave KDC(s), if they are specified. The slave KDCs can be specified in the Kerberos configuration file or via a list of KDCs separated by a colon (:) in the system property java.security.krb5.kdc.

  • Support TCP for Kerberos Key Distribution Center Transport
    Sun's implementation of Kerberos implements Kerberos version 5 according to RFC 1510 and uses UDP transport for ticket requests. A new Internet draft updates this RFC. One of the added features is required support for TCP as a transport in addition to UDP. As a result, in cases where Kerberos tickets exceed the UDP packet size limit, the KDC would return an error code indicating that the request should be resent over TCP.

    In the current 1.4.2 release, Sun's implementation of Kerberos now supports automatic fallback to TCP. Therefore, if the Kerberos ticket request using UDP fails and the KDC returns the error code KRB_ERR_RESPONSE_TOO_BIG, TCP is automatically the default transport.

  • Kerberos Service Ticket in the Subject's Private Credentials
    The Kerberos service ticket is now stored in the Subject's private credentials. This change allows application developers access to the service ticket so that it can be used outside the JGSS (for example, in native applications or for proprietary uses). In addition, the service ticket can now be reused if the application tries to establish a security context to the same service again. The service ticket should be valid for it to be reusable.

    Previously, when using Java Generic Security Services (JGSS) over Kerberos V5, if the useSubjectCredsOnly property was set to true, the Ticket Granting Ticket (TGT) was retrieved from the Subject and used to establish a GSS Security context. The service ticket obtained was not stored in the Subject. Now the service ticket is also stored in the Subject if useSubjectCredsOnly is true.

    If a client application searches through the Subject's private credentials, in previous releases it would find only the TGT. As of this release, it also will find any Service ticket(s) obtained.

    The bug report associated with this change is 4688866.

Copyright © 1995-2006 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: java-security@sun.com. 		Sun
Java Software


Single Sign-on Using Kerberos in Java

Mayank Upadhyay
Ram Marti

Sun Microsystems, Inc.

{mayank.upadhyay, ram.marti} @sun.com

ABSTRACT

A significant enhancement to the Java security architecture is the capability to achieve single sign-on using Kerberos Version 5 in the next release of JavaTM Standard Edition (J2SE). A single sign-on solution lets users authenticate themselves just once to access information on any of several systems. This is done using JAAS for authentication and authorization and Java GSS-API to establish a secure context for communication with a peer application. Our focus is on Kerberos V5 as the underlying security mechanism for single sign-on, although other security mechanisms may be added in the future.

INTRODUCTION

With the increasing use of distributed systems users need to access resources that are often remote. Traditionally users have had to sign-on to multiple systems, each of which may involve different usernames and authentication techniques. In contrast, with single sign-on, the user needs to authenticate only once and the authenticated identity is securely carried across the network to access resources on behalf of the user.

In this paper we discuss how to use single sign-on based on the Kerberos V5 protocol. We use the Java Authentication and Authorization Service (JAAS) to authenticate a principal to Kerberos and obtain credentials that prove its identity. We show how Sun's implementation of a Kerberos login module can be made to read credentials from an existing cache on platforms that contain native Kerberos support. We then use the Java Generic Security Service API (Java GSS-API) to authenticate to a remote peer using the previously obtained Kerberos credentials. We also show how to delegate Kerberos credentials for single sign-on in a multi-tier environment.

KERBEROS V5

Kerberos V5 is a trusted third party network authentication protocol designed to provide strong authentication using secret key cryptography. When using Kerberos V5, the user's password is never sent across the network, not even in encrypted form, except during Kerberos V5 administration. Kerberos was developed in the mid-1980's as part of MIT's Project Athena. A full description of the Kerberos V5 protocol is beyond the scope of this paper. For more information on the Kerberos V5 protocol please refer to [1] and [2]

Kerberos V5 is a mature protocol and has been widely deployed. It is available on Solaris as SEAM and on Windows 2000 and several other platforms. A free reference implementation in C is available from MIT. For these reasons we have selected Kerberos V5 as the underlying technology for single sign-on in J2SE.

JAVA AUTHENTICATION AND AUTHORIZATION SERVICE (JAAS)

Until recently the Java 2 security architecture solely determined privileges by the origin of the code and the public key certificates matching the code signers. However, in a multi-user environment it is desirable to further specify privileges based on the authenticated identity of the user running the code.

JAAS supplies such a capability. JAAS is a pluggable framework and programming interface specifically targeted for authentication and access control based on the authenticated identities.

Authentication and Authorization

The JAAS framework can be divided into two components: an authentication component and an authorization component.

The JAAS authentication component provides the ability to reliably and securely determine who is currently executing Java code, regardless of whether the code is running as an application, an applet, a bean, or a servlet.

The JAAS authorization component supplements the existing Java security framework by providing the means to restrict the executing Java code from performing sensitive tasks, depending on its codesource and depending on who is executing the code.

Pluggable and Stackable Framework

JAAS authentication framework is based on Pluggable Authentication Module (PAM)[3, 4]. JAAS authentication is performed in a pluggable fashion allowing system administrators to add appropriate authentication modules. This permits Java applications to remain independent of underlying authentication technologies, and new or updated authentication technologies can be seamlessly configured without requiring modifications to the application itself.

JAAS authentication framework also supports the stacking of authentication modules. Multiple modules can be specified and they are invoked by the JAAS framework in the order they were specified. The success of the overall authentication depends on the results of the individual authentication modules.

Subject

JAAS uses the term Subject to refer to any entity that is the source of a request to access resources. A Subject may be a user or a service. Since an entity may have many names or principals JAAS uses Subject as an extra layer of abstraction that handles multiple names per entity.Thus a Subject is comprised of a set of principals. There are no restrictions on principal names.

A Subject is only populated with authenticated principals. Authentication typically involves the user providing proof of identity, such as a password.

A Subject may also have security related attributes, which are referred to as credentials. The credentials can be public or private. Sensitive credentials such as private cryptographic keys are stored in the private credentials set of the Subject.

The Subject class has methods to retrieve the principals, public credentials and private credentials associated with it.

Please note that different permissions may be required for operations on these classes. For example AuthPermission("modifyPrincipals") may be required to modify the principal set of the Subject. Similar permissions are required to modify the public credentials, private credentials and to get the current Subject.

doAs and doAsPrivileged

Java 2 enforces runtime access controls via java.lang.SecurityManager. The SecurityManager is consulted anytime sensitive operations are attempted. The SecurityManager delegates this responsibility to java.security.AccessController. The AccessController obtains a current image of the AccessControlContext and verifies that it has sufficient permission to do the operation requested.

JAAS provides two methods doAs and doAsPrivileged that can be used to associate an authenticated Subject with the AccessControlContext dynamically.

The doAs method associates the Subject with the current thread's access control context and subsequent access control checks are made on the basis of the code being executed and the Subject executing it.

public static Object doAs(final Subject subject,
                          final  PrivilegedAction action)

public static Object doAs(final Subject subject,
                          final  PrivilegedExceptionAction action)
    throws  PrivilegedActionException;

Both forms of the doAs method first associate the specified subject with the current Thread's AccessControlContext, and then execute the action. This achieves the effect of having the action run as the Subject. The first method can throw runtime exceptions but normal execution has it returning an Object from the run() method of its action argument. The second method behaves similarly except that it can throw a checked PrivilegedActionException from its run() method. An AuthPermission("doAs") is required to call the doAs methods.

The following methods also execute code as a particular Subject:

public static Object doAsPrivileged(final Subject subject,
                                    final  PrivilegedAction action,
                                    final  AccessControlContext  acc);

public static Object doAsPrivileged(final Subject subject,
                                    final PrivilegedExceptionAction action,
                                    final  AccessControlContext acc)
   throws PrivilegedActionException;

The doAsPrivileged method behaves exactly as doAs, except that it allows the caller to specify an access control context. Thus it effectively throws away the current AccessControlContext and authorization decisions will be based on the AccessControlContext passed in.

Since the AccessControlContext is set on a per thread basis, different threads within the JVM can assume different identities. The Subject associated with a specific AccessControlContext can be retrieved by using the following method:

public static Subject getSubject(final AccessControlContext acc);

LoginContext

The LoginContext class provides the basic methods used to authenticate Subjects. It also allows an application to be independent of the underlying authentication technologies. The LoginContext consults a configuration that determines the authentication services or LoginModules configured for a particular application. If the application does not have a specific entry, it defaults to the entry identified as "other".

To support the stackable nature of LoginModules, LoginContext performs authentication in two phases. In the first phase or login phase, it invokes each configured LoginModule to attempt the authentication. If all the necessary LoginModules succeed, then LoginContext enters the second phase where it invokes each LoginModule again to formally commit the authentication process. During this phase the Subject is populated with the authenticated principals and their credentials. If either of the phase fails, then the LoginContext invokes each configured module to abort the entire authentication attempt. Each LoginModule then cleans up any relevant state associated with the authentication attempt.

LoginContext has four constructors that can be used to instantiate it. All of them require the configuration entry name to be passed. In addition the Subject and/or a CallbackHandler can also be passed to the constructors.

Callbacks

The login modules invoked by JAAS must be able to garner information from the caller for authentication. For example the Kerberos login module may require users to enter their Kerberos password for authentication.

The LoginContext allows the application to specify a callbackhandler that the underlying login modules use to interact with users. There are two callback handlers available in Merlin (J2SE 1.4) - one based on the command line and another based on a GUI.

LoginModules

Sun provides an implementation of the UnixLoginModule, NTLoginModule, JNDILoginModule, KeyStoreLoginModule and Krb5LoginModule in Merlin. A smart card based JAAS login module is available from GemPlus [5].

The Kerberos Login Module

The class com.sun.security.auth.module.Krb5LoginModule is Sun's implementation of a login module for the Kerberos version 5 protocol. Upon successful authentication the Ticket Granting Ticket (TGT) is stored in the Subject's private credentials set and the Kerberos principal is stored in the Subject's principal set.

Based on certain configurable options, Krb5LoginModule can also use an existing credentials cache, such as a native cache in the operating system, to acquire the TGT and/or use a keytab file containing the secret key to implicitly authenticate a principal. Both the Solaris and Windows 2000 platforms contain a credentials cache that Krb5LoginModule can use for fetching the TGT. Solaris also contains a system wide keytab file that Krb5LoginModule can use for fetching the secret key. On all platforms, Krb5LoginModule supports options to set the file path to a ticket cache or keytab file of choice. This is useful when third-party Kerberos support is installed and Java integration is desired. Please consult the documentation for Krb5LoginModule to learn about these options. In the absence of a native cache or keytab, the user will be prompted for the password and the TGT obtained from the KDC.

Figure 1 provides a sample JAAS login configuration entry for a client application. In this example, Krb5LoginModule will use the native ticket cache to get the TGT available in it. The authenticated identity will be the identity of the Kerberos principal that the TGT belongs to.

SampleClient {
    com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true
};
             Figure 1. Sample client  configuration entry

Figure 2 provides a sample login configuration entry for a server application. With this configuration, the secret key from the keytab is used to authenticate the principal "nfs/bar.foo.com" and both the TGT obtained from the Kerberos KDC and the secret key are stored in the Subject's private credentials set. The stored key may be used later to validate a service ticket sent by a client (See the section on Java GSS-API.)

SampleServer {
     com.sun.security.auth.module.Krb5LoginModule
         required useKeyTab=true storeKey=true principal="nfs/bar.foo.com"
};

             Figure 2. Sample server configuration entry

In the client code example shown in Figure 3, the configuration entry "SampleClient" will be used by the LoginContext. The TextCallbackHandler class will be used to prompt the user for the Kerberos password. Once the user has logged in, the Subject will be populated with the Kerberos Principal name and the TGT. Thereafter the user can execute code using Subject.doAs passing in the Subject obtained from the LoginContext.

LoginContext lc = null;

try {
        lc = new LoginContext("SampleClient", new TextCallbackHandler());
        // attempt authentication
        lc.login();
} catch (LoginException le) {
    ...
}

 // Now try to execute ClientAction as the authenticated Subject

 Subject mySubject = lc.getSubject();
 PrivilegedAction action = new ClientAction();
 Subject.doAs(mySubject, action);

            Figure 3. Sample client code

ClientAction could be an action that is allowed only for authenticated Kerberos client Principals with a specific value.

Figure 4 shows server side sample code. It is similar to the client code shown in Figure 4 except for the application entry name and the PrivilegedAction.

LoginContext lc = null;

try {
        lc = new LoginContext("SampleServer", new TextCallbackHandler());
        // attempt authentication
        lc.login();
} catch (LoginException le) {
   ...
}

// Now try to execute ServerAction as the authenticated Subject

Subject mySubject = lc.getSubject();
PrivilegedAction action = new ServerAction();
Subject.doAs(mySubject, action);

            Figure 4. Sample server code

Kerberos Classes

To enable other vendors to provide their own Kerberos login module implementation that can be used with Java GSS-API, three standard Kerberos classes have been introduced in the javax.security.auth.kerberos package. These are KerberosPrincipal for Kerberos principals, KerberosKey for the long-term Kerberos secret key and KerberosTicket for Kerberos tickets. All implementations of the Kerberos login module must use these classes to store principals, keys and tickets in the Subject.

Authorization

Upon successful authentication of a Subject, access controls can be enforced based upon the principals associated with the authenticated Subject. The JAAS principal based access controls augment the CodeSource access controls of Java 2. Permissions granted to a Subject are configured in Policy, which is an abstract class for representing the system wide access control policy. Sun provides a file based implementation of the Policy class. The Policy class is provider based so that others can provide their own policy implementation.

JAVA GENERIC SECURITY SERVICE APPLICATION PROGRAM INTERFACE (Java GSS-API)

Generic Security Service API (GSS-API)

Enterprise applications often have varying security requirements and deploy a range of underlying technologies to achieve this. In such a scenario how do we develop a client-server application so that it can easily migrate from one technology to another? The GSS-API was designed in the Common Authentication Technology working group of the IETF to solve this problem by providing a uniform application programming interface for peer to peer authentication and secure communication that insulates the caller from the details of the underlying technology.

The API, described in a language independent form in RFC 2743 [6], accommodates the following security services: authentication, message confidentiality and integrity, sequencing of protected messages, replay detection, and credential delegation. The underlying security technology or "security mechanism" being used, has a choice of supporting one or more of these features beyond the essential one way authentication 1. There are mainly two standard security mechanisms that the IETF has defined: Kerberos V5 [6] and the Simple Public Key Mechanism (SPKM) [8].

The API is designed such that an implementation may support multiple mechanisms simultaneously, giving the application the ability to choose one at runtime. Mechanisms are identified by means of unique object identifier's (OID's) that are registered with the IANA. For instance, the Kerberos V5 mechanism is identified by the OID {iso(1) member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) krb5(2)}.

Another important feature of the API is that it is token based. i.e., Calls to the API generate opaque octets that the application must transport to its peer. This enables the API to be transport independent.

Figure 5. A multi-mechanism GSS-API implementation

Java GSS-API

The Java API for the Generic Security Service was also defined at the IETF and is documented in RFC 2853 [10]. Sun is pursuing the standardization of this API under the Java Community Process (JCP) [11] and plans to deliver a reference implementation with Merlin. Because the JCP is merely endorsing this externally defined API, the IETF assigned package namespace "org.ietf.jgss" will be retained in Merlin.

Sun's implementation of Java GSS-API, will initially ship with support for the Kerberos V5 mechanism only. Kerberos V5 mechanism support is mandatory for all Java GSS-API implementations in Java SE, although they are free to support additional mechanisms. In a future release, a Service Provider Interface (SPI) will be added so that new mechanisms can be configured statically or even at runtime. Even now the reference implementation in Merlin will be modular and support a private provider SPI that will be converted to public when standardized.

The Java GSS-API framework itself is quite thin, and all security related functionality is delegated to components obtained from the underlying mechanisms. The GSSManager class is aware of all mechanism providers installed and is responsible for invoking them to obtain these components.

The implementation of the default GSSManager that will ship with Java SE is obtained as follows:

GSSManager manager = GSSManager.getInstance();

The GSSManager can be used to configure new providers and to list all mechanisms already present. The GSSManager also serves as a factory class for three important interfaces: GSSName, GSSCredential, and GSSContext. These interfaces are described below with the methods to instantiate their implementations. For a complete API specification, readers are referred to [9] and [11].

Most calls to Java GSS-API throw a GSSException that encapsulate problems that occur both within the GSS-API framework, and within the mechanism providers.

The GSSName Interface

This interface represents an entity for the purposes of Java GSS-API. An implementation of this interface is instantiated as follows:

GSSName GSSManager.createName(String name, Oid nameType)
    throws GSSException

For Example:

GSSName clientName = manager.createName("duke", GSSName.NT_USER_NAME);

This call returns a GSSName that represents the user principal "duke" at a mechanism independent level. Internally, it is assumed that each supported mechanism will map the generic representation of the user to a more mechanism specific form. For instance a Kerberos V5 mechanism provider might map this name to duke@FOO.COM where FOO.COM is the local Kerberos realm. Similarly, a public key based mechanism provider might map this name to an X.509 Distinguished Name.

If we were referring to a principal that was not a user, but some sort of service, we would indicate that to the Java GSS-API call so that the mechanism knows to interpret it differently.

Example:

GSSName serverName = manager.createName("nfs@bar.foo.com",
                                         GSSName.NT_HOSTBASED_SERVICE);

The Kerberos V5 mechanism would map this name to the Kerberos specific form nfs/bar.foo.com@FOO.COM where FOO.COM is the realm of the principal. This principal represents the service nfs running on the host machine bar.foo.com.

Sun's implementation of the GSSName interface is a container class. The container class lazily asks the individual providers to perform their mapping when their mechanism is used and then stores each mapped element in a set of principals. In this respect an implementation of GSSName is similar to the principal set stored in a Subject. It may even contain the same elements that are in a Subject's principal set, but its use is restricted to the context of Java GSS-API.

The name element stored by the Sun Kerberos V5 provider is an instance of a subclass of javax.security.auth.kerberos.KerberosPrincipal.

The GSSCredential Interface

This interface encapsulates the credentials owned by one entity. Like the GSSName, this interface too is a multi-mechanism container.

Its implementation is instantiated as follows:

GSSCredential createCredential(GSSName name,
                               int lifetime,
                               Oid[] desiredMechs,
                               int usage)

    throws GSSException

Here is an example of this call on the client side:

GSSCredential clientCreds =
               manager.createCredential(clientName,
                                        8*3600,
                                        desiredMechs,
                                        GSSCredential.INITIATE_ONLY);

The GSSManager invokes the providers of the mechanisms listed in the desiredMechs for credentials that belong to the GSSName clientName. Additionally, it imposes the restriction that the credential must be the kind that can initiate outbound requests (i.e., a client credential), and requests a lifetime of 8 hours for it. The returned object contains elements from a subset of desiredMechs that had some credential available to satisfy this criteria. The element stored by the Kerberos V5 mechanism is an instance of a subclass of javax.security.auth.kerberos.KerberosTicket containing a TGT that belongs to the user.

Credential acquisition on the server side occurs as follows:

GSSCredential serverCreds =
          manager.createCredential(serverName,
                                   GSSCredential.INDEFINITE_LIFETIME,
                                   desiredMechs,
                                   GSSCredential.ACCEPT_ONLY);

The behavior is similar to the client case, except that the kind of credential requested is one that can accept incoming requests (i.e., a server credential). Moreover, servers are typically long lived and like to request a longer lifetime for the credentials such as the INDEFINITE_LIFETIME shown here. The Kerberos V5 mechanism element stored is an instance of a subclass of javax.security.auth.kerberos.KerberosKey containing the secret key of the server.

This step can be an expensive one, and applications generally acquire a reference at initialization time to all the credentials they expect to use during their lifetime.

The GSSContext Interface

The GSSContext is an interface whose implementation provides security services to the two peers.

On the client side a GSSContext implementation is obtained with the following API call:

GSSContext GSSManager.createContext(GSSName peer,
                                    Oid mech,
                                    GSSCredential clientCreds,
                                    int lifetime)
    throws GSSException

This returns an initialized security context that is aware of the peer that it must communicate with and the mechanism that it must use to do so. The client's credentials are necessary to authenticate to the peer.

On the server side the GSSContext is obtained as follows:

GSSContext GSSManager.createContext(GSSCredential serverCreds)
    throws GSSException

This returns an initialized security context on the acceptor's side. At this point it does not know the name of the peer (client) that will send a context establishment request or even the underlying mechanism that will be used. However, if the incoming request is not for service principal represented by the credentials serverCreds, or the underlying mechanism requested by the client side does not have a credential element in serverCreds, then the request will fail.

Before the GSSContext can be used for its security services it has to be established with an exchange of tokens between the two peers. Each call to the context establishment methods will generate an opaque token that the application must somehow send to its peer using a communication channel of its choice.

The client uses the following API call to establish the context:

byte[] GSSContext.initSecContext(byte[] inToken,
                                 int offset,
                                 int len)

   throws GSSException

The server uses the following call:

byte[] acceptSecContext(byte[] inToken,
                        int offset,
                        int len)

   throws GSSException

These two methods are complementary and the input accepted by one is the output generated by the other. The first token is generated when the client calls initSecContext for the first time. The arguments to this method are ignored during that call. The last token generated depends on the particulars of the security mechanism being used and the properties of the context being established.

The number of round trips of GSS-API tokens required to authenticate the peers varies from mechanism to mechanism and also varies with characteristics such as whether mutual authentication or one-way authentication is desired. Thus each side of the application must continue to call the context establishment methods in a loop until the process is complete.

In the case of the Kerberos V5 mechanism, there is no more than one round trip of tokens during context establishment. The client first sends a token generated by its initSecContext() containing the Kerberos AP-REQ message [2]. In order to generate the AP-REQ message, the Kerberos provider obtains a service ticket for the target server using the client's TGT. The service ticket is encrypted with the server's long-term secret key and is encapsulated as part of the AP-REQ message. After the server receives this token, it is passed to the acceptSecContext() method which decrypts the service ticket and authenticates the client. If mutual authentication was not requested, both the client and server side contexts would be established, and the server side acceptSecContext() would generate no output.

However, if mutual authentication were enabled, then the server's acceptSecContext() would generate an output token containing the Kerberos AP-REP [2] message. This token would need to be sent back to the client for processing by its initSecContext(), before the client side context is established.

Note that when a GSSContext is initialized on the client side, it is clear what underlying mechanism needs to be used. The Java GSS-API framework can obtain a context implementation from the appropriate mechanism provider. Thereafter, all calls made to the GSSContext object are delegated to the mechanism's context implementation. On the server side, the mechanism to use is not decided until the first token from the client side arrives.

Here is a class showing how the client side of an application would be coded. This is the ClientAction class that was executed using the doAs method in Figure 3:

class ClientAction implements PrivilegedAction {

    public Object run() {
        ...
        ...
        try {
            GSSManager manager = GSSManager.getInstance();
            GSSName clientName =
                manager.createName("duke", GSSName.NT_USER_NAME);
            GSSCredential clientCreds =
                manager.createCredential(clientName,
                                          8*3600,
                                          desiredMechs,
                                          GSSCredential.INITIATE_ONLY);
            GSSName peerName =
                manager.createName("nfs@bar.foo.com",
                                    GSSName.NT_HOSTBASED_SERVICE);
            GSSContext secContext =
                manager.createContext(peerName,
                                      krb5Oid,
                                      clientCreds,
                                      GSSContext.DEFAULT_LIFETIME);
            secContext.requestMutualAuth(true);

            // The first input token is ignored
            byte[] inToken = new byte[0];

            byte[] outToken = null;

            boolean established = false;

           // Loop while the context is still not established
           while (!established) {
               outToken =
                   secContext.initSecContext(inToken, 0, inToken.length);

               // Send a token to the peer if one was generated
               if (outToken != null)
                  sendToken(outToken);

               if (!secContext.isEstablished()) {
                  inToken = readToken();
               else
                  established = true;
            }
        } catch (GSSException e) {
             ....
        }
        ...
        ...
    }
}

        Figure 6. Sample client using Java GSS-API

The corresponding section of code on the server side running the ServerAction class from Figure 5 is as follows:

class ServerAction implelemts PrivilegedAction {

    public Object run() {
        ...
        ...
        try {
            GSSManager manager = GSSManager.getInstance();
            GSSName serverName =
                manager.createName("nfs@bar.foo.com",
                                    GSSName.NT_HOSTBASED_SERVICE);
            GSSCredential serverCreds =
             manager.createCredential(serverName,
                                       GSSCredential.INDEFINITE_LIFETIME,
                                       desiredMechs,
                                       GSSCredential.ACCEPT_ONLY);
            GSSContext secContext = manager.createContext(serverCreds);

            byte[] inToken = null;
            byte[] outToken = null;

            // Loop while the context is still not established
            while (!secContext.isEstablished()) {
                 inToken = readToken();
                 outToken =
                     secContext.acceptSecContext(inToken, 0, inToken.length);

                  // Send a token to the peer if one was generated
                  if (outToken != null)
                      sendToken(outToken);
            }
        } catch (GSSException e) {
          ...
        }
        ...
        ...
   }
}

             Figure 7. Sample server using Java GSS-API

Message Protection

Once the security context is established, it can be used for message protection. Java GSS-API provides both message integrity and message confidentiality. The two calls that enable this are as follows:

byte[] GSSContext.wrap(byte[] clearText,
                       int offset,
                       int len,
                       MessageProp properties)
    throws GSSException
and
byte[] unwrap(byte[] inToken,
              int offset,
              int len,
              MessageProp properties)
    throws GSSException

The wrap method is used to encapsulate a cleartext message in a token such that it is integrity protected. Optionally, the message can also be encrypted by requesting this through a properties object. The wrap method returns an opaque token that the caller sends to its peer. The original cleartext is returned by the peer's unwrap method when the token is passed to it. The properties object on the unwrap side returns information about whether the message was simply integrity protected or whether it was encrypted as well. It also contains sequencing and duplicate token warnings.

Credential Delegation

Java GSS-API allows the client to securely delegate its credentials to the server, such that the server can initiate other security contexts on behalf of the client. This feature is useful for single sign-on in a multi-tier environment.

Credential delegation in a multi-tier environment

Figure 8. Credential Delegation

The client requests credential delegation prior to making the first call to initSecContext():

void GSSContext.requestCredDeleg(boolean state)
    throws GSSException
by setting state to true.

The server receives the delegated credential after context establishment:

GSSCredential GSSContext.getDelegCred() throws GSSException

The server can then pass this GSSCredential to GSSManager.createContext() pretending to be the client.

In the case of the Kerberos V5 mechanism, the delegated credential is a forwarded TGT that is encapsulated as part of the first token sent from the client to the server. Using this TGT, the server can obtain a service ticket on behalf of the client for any other service.

DEFAULT CREDENTIAL ACQUISITION MODEL

Previously we discussed how an application uses the GSSManager.createCredential() method to populate a GSSCredential object with mechanism specific credentials.The next two sub-sections will focus on how Java GSS-API mechanisms obtain these credentials. The mechanisms do not themselves perform a user login. Instead, the login is performed prior to using Java GSS-API and the credentials are assumed to be stored in some cache that the mechanism provider is aware of. The GSSManager.createCredential() method merely obtains references to those credentials and returns them in a GSS-centric container, the GSSCredential.

In the Java 2 platform we impose the restriction that the credentials cache that Java GSS-API mechanism providers use to obtain these elements must exclusively be the public and private credential sets in the Subject that is on the current access control context.

This model has the advantage that credential management is simple and predictable from the application's point of view. An application, given the right permissions, can purge the credentials in the Subject or renew them using standard Java API's. If it purged the credentials, it would be sure that the Java GSS-API mechanism would fail, or if it renewed a time based credential it would be sure that the mechanism would succeed.

Here is the sequence of events relevant to credential acquisition when the Kerberos V5 mechanism is used by the client application in Figures 3 and 6:

  1. The application invokes a JAAS login, which in turn invokes the configured Krb5LoginModule

  2. Krb5LoginModule obtains a TGT (KerberosTicket) for the user either from the KDC or from an existing ticket cache, and stores this TGT in the private credentials set of a Subject

  3. The application retrieves the populated Subject, then calls Subject.doAs/doAsPrivileged which places this Subject on the access control context of the thread executing ClientAction

  4. ClientAction calls the GSSManager.createCredential method, passing it the Kerberos V5 OID in desiredMechs.

  5. GSSManager.createCredential invokes the Kerberos V5 GSS-API provider, asking for a Kerberos credential for initiating security contexts.

  6. The Kerberos provider obtains the Subject from the current access control context, and searches through its private credential set for a valid KerberosTicket that represents the TGT for the user.

  7. The KerberosTicket is returned to the GSSManager which stores it in a GSSCredential container instance to be returned to the caller.

    On the server side, when the Kerberos login is successful in step 2, Krb5LoginModule stores the KerberosKey for the server in the Subject in addition to the KerberosTicket. Later on the KerberosKey is retrieved in steps 5 through 7 and used to decrypt the service ticket that the client sends.

    EXCEPTIONS TO THE MODEL

    The default credential acquisition model for Java GSS-API requires credentials to be present in the current Subject. Typically, the credentials are placed there after a JAAS login by the application.

    There might be cases where an application wishes to use Kerberos credentials from outside the Subject. It is recommended that such credentials be read as part of the initial JAAS login, either by configuring Krb5LoginModule to read them, or by writing a custom login module that reads them. However, some applications might have constrains that either prevent them from using JAAS prior to calling Java GSS-API, or force them to use some Kerberos mechanism provider that does not retrieve credentials from the current Subject.

    In order to accommodate such cases while still retaining the standard model for others, the system property javax.security.auth.useSubjectCredsOnly was added. This system property serves as a boolean where a value of true requires that the standard credential acquisition model be followed, and a value of false permits the provider to use any cache of it choice. The default value of this property (when it is not set) will be assumed to be true.

    If there is no valid Kerberos credential in the current Subject, and this property is true, then the Kerberos mechanism throws a GSSException. Setting this property to false does not necessarily mean that the provider has to use a cache other than the current Subject, it only gives the provider the latitude to do so if it wishes.

    The Sun provider for the Kerberos V5 GSS-API mechanism always obtains credentials from a Subject. If there are no valid credentials in the current Subject, and this property is set to false, then the provider attempts to obtain new credentials from a temporary Subject by invoking a JAAS login itself. It uses the text callback handler for input/output with the user, and the JAAS configuration entry identified by"other" for the the list of modules and options to use 2. It assumes that one of these modules will be a Kerberos login module. It is possible to configure the modules listed under "other" to read a pre-existing cache so that the user is not unexpectedly prompted for a password in the middle of a Java GSS-API call. The new Subject that is populated by this login is discarded by the Kerberos GSS-API mechanism just as soon as the required credentials are retrieved from it.

    WEB-BROWSER INTEGRATION

    An important class of applications that should be able to capitalize on Java single sign-on are applets. For this discussion we assume that the browser JRE has all the required packages or the Java plugin is used with a Merlin JRE installed by the user.

    One complication in using applets arises mostly out of the fact that before an applet can use Java GSS-API, it must perform a JAAS login. The main problems with this are (a) an increase in the effort required on the part of the applet developer (b)unnecessary repeated login by the same user each time he or she starts an applet.

    A good model to solve this problem would be to have the browser (or the Java plugin) perform a JAAS login once at startup. This would provide a Subject that could always be associated with the access control context whenever any Java code was run. As a result, the applet code would not need to perform a JAAS login prior to using Java GSS-API, and the user login would occur just once.

    In the absence of this login functionality in the browser (or Java plugin), applets can still avoid having to perform a JAAS login themselves. To do so, the applets would have to set the javax.security.auth.useSubjectCredsOnly system property to false and use a GSS-API mechanism provider that is capable of obtaining credentials from sources other than current Subject. When using a Sun JRE with a Sun Kerberos GSS-API provider, expect the mechanism to perform a JAAS login to obtain new credentials as explained in the previous section. The applet deployer would only need to ensure that the appropriate modules and options are listed in the entry "other" in the JAAS configuration used by the JRE. This saves the applet developer from calling into JAAS API's directly, but it does not stop the repeated JAAS login that might happen with each applet the user runs. However, by configuring the login modules to read a pre-existing native cache, the deployer can both hide the login from the user, and minimize the overhead in the multiple logins. (See how this is done for the the JAAS configuration entry "SampleClient" in Figure 1.)

    SECURITY RISKS

    The convenience of single sign-on also introduces new risks. What happens if a malicious user gains access to your unattended desktop from where he or she can start applets as you? What happens if malicious applets sign on as you to services that they are not supposed to?

    For the former, we have no solution but to caution you against leaving your workstation unlocked! For the latter, we have many authorizations checks in place.

    To illustrate some details of the permissions model consider an example where your browser has performed a JAAS login at startup time and associated a Subject with all applets that run in it.

    The Subject is protected from rogue applets by means of the javax.security.auth.AuthPermission class. This permission is checked whenever code tries to obtain a reference to the Subject associated with any access control context.

    Even if an applet were given access to a Subject, it needs a javax.security.auth.PrivateCredentialPermission to actually read the sensitive private credentials stored in it.

    Other kinds of checks are to be done by Java GSS-API mechanism providers as they read credentials and establish security contexts on behalf of the credential's owner. In order to support the Kerberos V5 mechanism, two new permission classes have been added with the package javax.security.auth.kerberos:

    ServicePermission(String servicePrinicipal, String action)
DelegationPermission(String principals)

    As new GSS-API mechanisms are standardized for Java SE, more packages will be added that contain relevant permission classes for providers of those mechanisms.

    The Kerberos GSS-API mechanism permission checks take place at the following points in the program's execution:

    Credential Acquisition

    The GSSManager.createCredential() method obtains mechanism specific credential elements from a cache such as the current Subject and stores them in a GSSCredential container. Allowing applets to acquire GSSCredential freely, even if they cannot use them to do much, is undesirable. Doing so leaks information about the existence of user and service principals. Thus, before an application can acquire a GSSCredential with any Kerberos credential elements in it, a ServicePermission check is made.

    On the client side, a successful GSSCredential acquisition implies that a TGT has been accessed from a cache. Thus the following ServicePermission is checked:

    ServicePermission("krbtgt/FOO.COM@FOO.COM", "initiate");

    The service principal krbtgt/FOO.COM@FOO.COM represents the ticket granting service (TGS) in the Kerberos realm FOO.COM, and the action "initiate" suggests that a ticket to this service is being accessed. The TGS service principal will always be used in this permission check at the time of client side credential acquisition.

    On the server side, a successful GSSCredential acquisition implies that a secret key has been accessed from a cache. Thus the following ServicePermission is checked:

    ServicePermission("nfs/bar.foo.com@FOO.COM", "accept");

    Here the service principal nfs/bar.foo.com represents the Kerberos service principal and the action "accept" suggests that the secret key for this service is being requested.

    Context Establishment

    An applet that has permissions to contact a particular server, say the LDAP server, must not instead contact a different server such as the FTP server. Of course, the applet might be restricted from doing so with the help of SocketPermission. However, it is possible to use ServicePermission to restrict it from authenticating using your identity, even if the network connection was permitted.

    When the Kerberos mechanism provider is about to initiate context establishment it checks the ServicePermission:

    ServicePermission("ftp@FOO.COM", "initiate");

    This check prevents unauthorized code from obtaining and using a Kerberos service ticket for the principal ftp@FOO.COM.

    Providing limited access to specific service principals using this permission is still dangerous. Downloaded code is allowed to communicate back with the host it originated from. A malicious applet could send back the initial GSS-API output token that contains a KerberosTicket encrypted in the target service principal's long-term secret key, thus exposing it to an offline dictionary attack. For this reason it is not advisable to grant any "initiate" ServicePermission to code downloaded from untrusted sites.

    On the server side, the permission to use the secret key to accept incoming security context establishment requests is already checked during credential acquisition. Hence, no checks are made in the context establishment stage.

    Credential Delegation

    An applet that has permission to establish a security context with a server on your behalf also has the ability to request that your credentials be delegated to that server. But not all servers are trusted to the extent that your credentials can be delegated to them. Thus, before a Kerberos provider obtains a delegated credential to send to the peer, it checks the following permission:

    DelegationPermission(" \"ftp@FOO.COM\" \"krbtgt/FOO.COM@FOO.COM\" ");

    This permission allows the Kerberos service principal ftp@FOO.COM to receive a forwarded TGT (represented by the ticket granting service krbtgt/FOO.COM@FOO.COM)3.

    CONCLUSIONS

    In this paper we have presented a framework to enable single sign-on in Java. This requires sharing of credentials between JAAS which does the initial authentication to obtain credentials, and Java GSS-API which uses those credentials to communicate securely over the wire. We have focused on Kerberos V5 as the underlying security mechanism, but JAAS's stackable architecture and Java GSS-API's multi-mechanism nature allow us to use any number of different mechanisms simultaneously.

    The Kerberos login module for JAAS is capable of reading native caches so that users do not have to authenticate themselves beyond desktop login on platforms that support Kerberos. Moreover, the Kerberos V5 mechanism for Java GSS-API allows credentials to be delegated which enables single sign-on in multi-tier environments.

    Finally, a number of permissions checks are shown to prevent the unauthorized use of the single-sign on features provided by Kerberos.

    ACKNOWLEDGMENTS

    We thank Gary Ellison, Charlie Lai, and Jeff Nisewanger for their contribution at each stage of the Kerberos single sign-on project. JAAS 1.0 was implemented by Charlie as an optional package for Kestrel (J2SE 1.3). Gary has been instrumental in designing the permissions model for the Kerberos Java GSS-API mechanism. We are grateful to Bob Scheifler for his feedback on integrating JAAS 1.0 into Merlin and to Tim Blackman for the KeyStoreLoginModule and CallbackHandler implementations. We also thank Bruce Rich, Tony Nadalin, Thomas Owusu and Yanni Zhang for their comments and suggestions. We thank Mary Dageforde for the documentation and tutorials. Sriramulu Lakkaraju, Stuart Ke and Shital Shisode contributed tests for the projects. Maxine Erlund provided management support for the project.

    REFERENCES

    1. Neuman, Clifford and Tso, Theodore (1994). Kerberos: An Authentication Service for Computer Networks, IEEE Communications, volume 39 pages 33-38

    2. J.Kohl and C.Neuman. The Kerberos Network Authentication Service (V5) Internet Engineering Task Force, September 1993 Request for Comments 1510

    3. V. Samar and C. Lai. Making Login Services Independent from Authentication Technologies. In Proceedings of the SunSoft Developer's Conference, March 1996.

    4. X/Open Single Sign-On Service (XSSO) - Pluggable Authentication. Preliminary Specification P702, The Open Group, June 1997. http://www.opengroup.org

    5. A Smart Card Login Module for Java Authentication and Authorization Service. http://www.gemplus.com/techno/smartjaas/index.html

    6. J. Linn. Generic Security Service Application Program Interface,Version 2. Internet Engineering Task Force, January 2000 Request for Comments 2743

    7. J. Linn. The Kerberos Version 5 GSS-API Mechanism. Internet Engineering Task Force, June 1996 Request for Comments 1964

    8. C.Adams. The Simple Public-Key GSS-API Mechanism (SPKM). Internet Engineering Task Force, October 1996 Request for Comments 2025

    9. J. Kabat and M.Upadhyay. Generic Security Service API Version 2: Java Bindings. Internet Engineering Task Force, January 1997 Request for Comments 2853

    10. JSR 000072 Generic Security Services API http://java.sun.com/aboutJava/communityprocess/final-draft/jsr072/index.html

    11. JavaTM 2 Platform, Standard Edition, v 1.4 API Specification. http://java.sun.com/j2se/1.4.2/docs/api/overview-summary.html -------------------------

      1 The GSS-API Kerberos mechanism performs client authentication at the minimum.

      2 Actually it first tries to use the JAAS configuration entry"com.sun.security.jgss.initiate" for the client and "com.sun.security.jgss.accept" for the server and falls back on the entry for "other", if these entries are missing. This gives system administrators some additional control over its behavior.

      3 The use of two principal names in this permission allows for finer grained delegation such as proxy tickets for specific services unlike a carte blanche forwarded TGT. Even though the GSS-API does not allow for proxy tickets, another API such as JSSE might support this idea at some point in the future.
      Feedback
      Last modified: Wed May 2 12:54:31 PDT 2001


Advanced JGSS Security Programming

Part III : Deploying for Single Sign-On in a Kerberos Environment

Exercise 6: Deploying for Single Sign-On

Goal of this exercise:

The goal of this exercise is to learn how to configure a JAAS application that uses Kerberos for authentication to achieve single sign-on. Single sign-on means that the user needs only authenticate once to a system or a collection of services. After the initial authentication, the user can access other services in the system using the same identity as he used for the initial authentication.

Single sign-on can be used to describe different types of authentication. There are HTTP-based network single sign-on protocols. There is Kerberos-based single sign-on for network services. In this particular exercise, we show how to achieve single sign-on in Kerberos-based systems by showing how to import already-acquired Kerberos credentials from the underlying native operating system.

Background and Resources for this exercise:

  1. Single Sign-On Using Kerberos in Java

In addition, see the information provided in Exercises 2 and 4 for background information about Kerberos and Java GSS.

Steps to follow:

  1. Edit the JAAS configuration file. This is located in src/jaas-krb5.conf

This file contains two entries, one named "client" and one named "server." Add the line "useTicketCache=true" to the client entry.

Code listing for updated jaas-krb5.conf.

  1. client {
  2.     com.sun.security.auth.module.Krb5LoginModule required
  3.     useTicketCache=true
  4.     principal="test";
  5. };
  6. server {
  7.    com.sun.security.auth.module.Krb5LoginModule required
  8.     useKeyTab=true
  9.     storeKey=true
  10.     keyTab=sample.keytab
  11.     principal="host/j1hol-001";
  12. };

  2. Perform Kerberos login to the native operating system.
    To login to Kerberos, use kinit command as follows.

    % kinit test
     Then, enter changeit when prompted for the password.
  3. Run the client and server programs in Exercises 1-5 as before and you will note that the client applications no longer ask you to enter a password.
Company Info | Contact | Copyright 2006 Sun Microsystems


Advanced JGSS Security Programming

Part IV : Secure Communications using stronger encryption algorithms (Java SE 6.0)

Exercise 7: Configuring to use stronger encryption algorithms in a Kerberos environment, to secure the communication

Goal of this exercise:

The goal of this exercise is to learn how to use various Kerberos encryption algorithms to secure the communication. In J2SE 1.4, Java GSS/Kerberos provided support for only DES encryption type. The Java GSS/Kerberos provider has been enhanced in J2SE 5.0 and later releases to support stronger Kerberos encryption algorithms, and is in compliance with latest Kerberos specification RFC4120. Support for various Kerberos encryption types, such as AES256, AES128, 3DES, RC4-HMAC, and DES are now all available. J2SE 5.0 supports 3DES and DES Kerberos encryption types. Support for AES and RC4-HMAC in Kerberos is available for Java SE 6 onwards.

Here is a list of all the encryption types supported by the Java GSS/Kerberos provider in Java SE 6.0:

  1. AES256-CTS
  2. AES128-CTS
  3. RC4-HMAC
  4. DES3-CBC-SHA1
  5. DES-CBC-MD5
  6. DES-CBC-CRC

Steps to follow:

  1. Configure the Key Distribution Center (KDC) and update the Kerberos database

    At first you need to update to use the Key Distribution Center (KDC) that supports the required Kerberos encryption types, such as Solaris 10 or the latest MIT Kerberos 1.4 from MIT distribution. If you are using the Active Directory on a Windows platform, it only supports DES and RC4-HMAC encryption types.

    You will need to update the Kerberos database, to generate the new keys with stronger encryption algorithms. By default, Solaris 10 KDC will generate the keys for all the above encryption types listed. You can now create a keytab that will include all the keys for all the above encryption types.

    NOTE: If you want to use Windows 2000 KDC, you can configure to use the DES and RC4-HMAC encryption types that are available on the Windows machine.

  2. Edit the Kerberos configuration file. This is located in src/krb5.conf

    You will need to edit the Kerberos configuration file in order to select the desired encryption types used. The required parameters are listed below, that you will need to insert under the libdefaults section of the Kerberos configuration file. For the purpose of this exercise, all the required entries have been added to a sample Kerberos configuration file included with the exercise, and the entries have been commented out. To enable the desired encryption type, you only need to uncomment the required entries.

    • To enable AES256-CTS encryption type

      [libdefaults]

default_tkt_enctypes = aes256-cts
default_tgs_enctypes = aes256-cts
permitted_enctypes = aes256-cts
      NOTE: Solaris 10 does not support AES256 by default. You will need to install the following packages:-

      SUNWcry, SUNWcryr, SUNWcryptoint
      In addition, JCE in Java SE also does not support AES256 by default.

      You will need to install the JCE crypto policy with the unlimited version to allow AES with 256-bit key.

    • To enable the AES128-CTS encryption type

      [libdefaults]
      default_tkt_enctypes = aes128-cts
      default_tgs_enctypes = aes128-cts
      permitted_enctypes = aes128-cts

    • To enable RC4-HMAC
encryption type

[libdefaults]
default_tkt_enctypes = rc4-hmac
default_tgs_enctypes = rc4-hmac
permitted_enctypes = rc4-hmac
    • To enable
DES3-CBC-SHA1 encryption type

[libdefaults]
default_tkt_enctypes = des3-cbc-sha1
default_tgs_enctypes = des3-cbc-sha1
permitted_enctypes = des3-cbc-sha1

    • To enable
DES-CBC-MD5 encryption type

[libdefaults]
default_tkt_enctypes = des-cbc-md5
default_tgs_enctypes = des-cbc-md5
permitted_enctypes = des-cbc-md5

    • To enable DES-CBC-CRC encryption type

      [libdefaults]
      default_tkt_enctypes = des-cbc-crc
      default_tgs_enctypes = des-cbc-crc
      permitted_enctypes = des-cbc-crc

      NOTE: If the above parameters are not added to the Kerberos configuration file, Solaris 10 will default to use AES128 enctype. If the exportable crypto packages have been installed, it will default to use AES256 enctype.

      NOTE: Destroy any pre-existing Kerberos TGT in the ticket cache from the previous exercise.

% kdestroy

    • Launch a new window and start the server using the updated krb5.conf

      % xterm &

      % java
        -Djava.security.auth.login.config=jaas-krb5.conf \
        -Djava.security.krb5.conf=krb5.conf \
         GSSServer
    • Run the client application using the updated krb5.conf. GssClient takes two parameters: the service name and the name of the server that the service is running on. For example, if the service is host running on the machine j1hol-001, you would enter the following. When prompted for the password, enter changeit.

% java
-Djava.security.auth.login.config=jaas-krb5.conf

   -Djava.security.krb5.conf=krb5.conf \

GSSClient host j1hol-001

Summary:

In this exercise, you learned how to write a client-server application that uses Java GSS API to authenticate and communicate securely with each other, using stronger Kerberos encryption algorithms. You can enable Kerberos debugging (-Dsun.security.krb5.debug=true), to obtain information about the Kerberos encryption type used.


Advanced JGSS Security Programming

Part I : Secure Authentication using the Java Authentication and Authorization Service (JAAS)

Exercise 1 : Using the JAAS API

Goal of this exercise:

The goal of this exercise is to learn how to use the Java Authentication and Authorization (JAAS) API to perform authentication.

Background for this exercise:

JAAS provides a standard pluggable authentication framework (PAM) for the Java platform. An application uses the JAAS API to perform authentication - the process of verifying the identity of the user who is using the application and gathering his identity information into a container called a subject. The application can then use the identity information in the subject along with the JAAS API to make authorization decisions, to decide whether the authenticated user is allowed to access protected resources or perform restricted actions. This exercise demonstrates JAAS Authentication. It does not demonstrate JAAS Authorization.

Resources for this exercise:

  1. JAAS Reference Guide
  2. JAAS Tutorials
  3. JAAS javadocs: javax.security.auth, javax.security.auth.callback, javax.security.auth.kerberos, javax.security.auth.login, javax.security.auth.spi, javax.security.auth.x500
  4. JAAS white paper

Steps to follow:

  1. Read the following sample code. This is located in src/Jaas.java. The code performs the following tasks:
    1. Define a callback handler or use a predefined one. [line 2]
    2. Create a LoginContext with a name that identifies which JAAS configuration entry to use. [line 5]
    3. Perform the authentication. [line 8]
    4. Define the task that the authenticated user is to perform [line 11]
    5. Perform the action as the authenticated user [lines 14-15]
    6. Logout.

    Subject.doAs will run the code defined in MyAction as the authenticated user [lines 14-15]. This serves two purposes. First, code in MyAction that requires identity information for authentication to a service could get it from the subject. This exercise demonstrates this use. Second, if MyAction accesses any protected resources/operations, the identity information in the current subject would be used to make the corresponding access control decision. This second aspect is not covered in this exercise.

    Code listing for Jaas.java.

    1. // Create a callback handler
    2. CallbackHandler callbackHandler = new TextCallbackHandler();
    4. // Create LoginContext with a callback handler
    5. LoginContext context = new LoginContext(name, callbackHandler);
    7. // Perform authentication
    8. context.login();
    10. // Create action to perform
    11. PrivilegedAction action = new MyAction();
    13. // Perform action as authenticated user
    14. Subject subject = context.getSubject();
    15. Subject.doAs(subject, action);
    17. // Logout
    18. context.logout();
  2. Make sure that the %JAVA_HOME%/bin is in the path, and JDK pointed to by the %JAVA_HOME% variable points to Java SE 6.

  3. Compile the modified sample code.

% cd auth/src
% javac Jaas.java
    You will run this code in subsequent exercises after doing some set up. That ends this exercise.

Summary:

This exercise introduced the main classes of the JAAS APIs: LoginContext and Subject. You learned how to use LoginContext to authenticate a user and collect its identity information in a Subject. You then learned how to use the Subject to perform an action as the authenticated user.

Next Steps

  1. Proceed to Exercise 2 to learn how to configure the sample application to use Kerberos for authentication.

Exercise 2: Configuring JAAS for Kerberos Authentication

Goal of this exercise:

The goal of this exercise is to learn how to configure a JAAS application to use Kerberos for authentication.

Kerberos Background for this exercise:

Kerberos is an Internet standard protocol for trusted-third party authentication defined in RFC 4120. It is available on most modern computing platforms today, including Solaris, Windows XP, and Linux.

The Kerberos architecture is centered around a trusted authentication service called the key distribution center, or KDC. Users and services in a Kerberos environment are referred to as principals; each principal shares a secret (such as a password) with the KDC. A principal authenticates to Kerberos by proving to the KDC that it knows the shared secret. If the authentication is successful, the KDC issues a ticket-granting-ticket (TGT) to the principal. When the principal subsequently wants to authenticate to a service on the network, such as a directory service or a file service, (thereby, acting as a "client" of the service), it gives the TGT to the KDC to obtain a service ticket to communicate with the service. Not only does the service ticket indicate the identities of the client and service principals, it also contains a session key that can be used by the client and service to subsequently establish secure communication. To authenticate to the service, the client sends the service ticket to the service. When the service receives the ticket, it decodes it using the secret it shares with the KDC.

In this architecture, a principal only authenticates directly (once) to the KDC. It authenticates indirectly to all other services via the use of service tickets. Service tickets are how the KDC vouches for the identity of a principal. The ability of a principal to access multiple secure services by performing explicit authentication only once is called single sign-on.

JAAS Background for this exercise:

In JAAS, for a client principal, "logging into Kerberos" means acquiring the TGT and placing it in the Subject, so that it can be used for authentication with services that the client will access. For a service principal, "logging into Kerberos" means obtaining the secret keys that the service needs to decode incoming client authentication requests.

Resources for this exercise:

  1. JAAS LoginModule Developer's Guide
  2. The Kerberos Network Authentication Service (v5)
  3. Example Login Configurations
  4. Login module package javadocs: com.sun.security.auth.module
  5. The JAAS and Java GSS-API Tutorials

Steps to follow:

  1. Examine the JAAS configuration file. This is located in src/jaas-krb5.conf

This file contains two entries, one named "client" and one named "server." The "client" entry indicates that the LoginContext must use the com.sun.security.auth.module.Krb5LoginModule. The "server" entry indicates that the LoginContext must use the same login module, and use keys from the sample.keytab file for the principal host/machineName.

Code listing for jaas-krb5.conf.

  1. client {
  2.     com.sun.security.auth.module.Krb5LoginModule required
  3.     principal="test";
  4. };
  5. server {
  6.    com.sun.security.auth.module.Krb5LoginModule required
  7.     useKeyTab=true
  8.     storeKey=true
  9.     keyTab=sample.keytab
  10.     principal="host/machineName";
  11. };

  2. Determine the hostname of your machine by executing the hostname command.
% hostname
  3. Edit this file and change the entry for server principal to use the name of your machine. For example, if your machine name is j1hol-001, this line in the configuration file should look like this.
principal="host/j1hol-001"
  4. Perform client authentication by typing
% java -Djava.security.auth.login.config=jaas-krb5.conf\
     Jaas client

You will be prompted for a password. Enter "changeit". You should see the following output.

Output for running the JAAS example using the client entry from jaas-krb5.conf:

  1. Kerberos password for test: changeit
  2. Authenticated principal: [test@J1LABS.EXAMPLE.COM]
  3. Performing secure action...

  5. Perform server authentication by typing
% java -Djava.security.auth.login.config=jaas-krb5.conf\
     Jaas server

You should see the following output.

Output for running JAAS example using "server" entry from jaas-krb5.conf.

  1. Authenticated principal: [host/j1hol-001@J1LABS.EXAMPLE.COM]
  2. Performing secure action...

Summary:

In this exercise, you learned how to configure a JAAS application to use a Kerberos login module, both as a client principal who enters his/her username/password interactively, and as a service principal who gets its keys from a keytab file.

Next Steps

  1. Proceed to Part II to learn how to establish secure communication channels using Java security APIs.


Advanced JGSS Security Programming

Part V : Secure Authentication using SPNEGO Java GSS mechanism (Java SE 6.0)

Exercise 8: Using the Java Generic Security Services (GSS) API with SPNEGO

Goal of this exercise:

Currently the only security mechansim available with Java GSS is "Kerberos". The goal of this exercise is to learn how to use other Java GSS mechanisms, such as SPNEGO, to secure the association. This feature is available from Java SE 6 onwards.

What is SPNEGO?

Java GSS is a framework that can support multiple security mechanisms; a way to negotiate a security mechanism underneath GSS-API is needed. This is available via SPNEGO.

SPNEGO is the Simple and Protected GSS-API Negotiation Mechanism, standardized at IETF in RFC 4178. It's a pseudo-security mechanism used to negotiate an underlying security mechanism. It provides the flexibility for client and server to securely negotiate a common GSS security mechanism.

Microsoft makes heavy use of SPNEGO. SPNEGO can be used to inter-operate with Microsoft Server over HTTP, to support HTTP-based Cross-Platform authentication via the Negotiate Protocol.

What do I need do to use SPNEGO in Java GSS?

Currently when using Java GSS with Kerberos, we specify the Kerberos OID to use Kerberos.

Oid krb5Oid = new Oid("1.2.840.113554.1.2.2");

In order to use SPNEGO, you only need to specify the SPNEGO OID as follows:-

Oid spnegoOid = new Oid("1.3.6.1.5.5.2");

And henceforth use the SPNEGO OID when creating a GSSCredential, GSSContext, etc.

Steps to follow:

  1. Read the following code. This is located in src/GssSpNegoClient.java

Code listing for GssSpNegoClient.java.

  1. static class GssSpnegoClientAction implements PrivilegedExceptionAction {
  2. ...
  3.   public Object run() throws Exception {
  4.     // Create socket to server
  5.     Socket socket = new Socket(hostName, port);
  6.     DataInputStream inStream = new DataInputStream(socket.getInputStream());
  7.     DataOutputStream outStream = new DataOutputStream(socket.getOutputStream());

  9.     // Get service's principal name
  10.     GSSManager manager = GSSManager.getInstance();
  11.     Oid spnegoOid = new Oid("1.3.6.1.5.5.2");
  12.     GSSName serverName = manager.createName(serverPrinc, GSSName.NT_HOSTBASED_SERVICE, spnegoOid);

  14.     // Get the context for authentication
  15.     GSSContext context = manager.createContext(serverName, spnegoOid, null,
  16.        GSSContext.DEFAULT_LIFETIME);
  17.     context.requestMutualAuth(true); // Request mutual authentication
  18.     context.requestConf(true); // Request confidentiality

  20.     // Do the context establishment loop
  21.     byte[] token = new byte[0];
  22.     while (!context.isEstablished()) {
  23.       token = context.initSecContext(token, 0, token.length);
  24.       outStream.writeInt(token.length);
  25.       outStream.write(token);
  26.       outStream.flush();

  28.       // Check if we're done
  29.       if (!context.isEstablished()) {
  30.         token = new byte[inStream.readInt()];
  31.         inStream.readFully(token);
  32.       }
  33.     }

  35.     // Context established!

  37.     // Create MessageProp for use with unwrap (true means request confidentiality)
  38.     MessageProp prop = new MessageProp(0, true);

  40.     // Create encrypted message and send to server
  41.     byte[] reply = ...;
  42.     token = context.wrap(reply, 0, reply.length, prop);

  44.     outStream.writeInt(token.length);
  45.     outStream.write(token);
  46.     outStream.flush();

  48.     // Read token from server
  49.     token = new byte[inStream.readInt()];
  50.     inStream.readFully(token);

  52.     // Unwrap (decrypt) token sent by server
  53.     byte[] input = context.unwrap(token, 0, token.length, prop);
  54.     ...
  55.     context.dispose();
  56.     socket.close();
  57.     return null;
  58.   }
  59. }

  2. Compile the sample code.
    % javac GssSpNegoClient.java
  3. Read the following code. This is located in src/GssSpNegoServer.java

Code listing for GssSpNegoServer.java.

  1. static class GssSpNegoServerAction implements PrivilegedExceptionAction {
  2. ...
  3.   public Object run() throws Exception {
  4.     // Create server socket for accepting connections
  5.     ServerSocket ss = new ServerSocket(localPort);

  7.     // Get own Kerberos credentials for accepting connection
  8.     GSSManager manager = GSSManager.getInstance();
  9.     Oid spnegoOid = new Oid("1.3.6.1.5.5.2");
  10.     GSSCredential serverCreds = manager.createCredential(null,
  11.       GSSCredential.DEFAULT_LIFETIME, spnegoOid, GSSCredential.ACCEPT_ONLY);

  13.     while (true) {
  14.       Socket socket = ss.accept();
  15.       DataInputStream inStream = new DataInputStream(socket.getInputStream());
  16.       DataOutputStream outStream = new DataOutputStream(socket.getOutputStream());

  18.       GSSContext context = manager.createContext((GSSCredential)serverCreds);

  20.       // Do the context establishment loop
  21.       byte[] token = null;
  22.       while (!context.isEstablished()) {
  23.         // Read token
  24.         token = new byte[inStream.readInt()];
  25.         inStream.readFully(token);

  27.         // Process token
  28.         token = context.acceptSecContext(token, 0, token.length);

  30.         // Send a token to the peer if one was generated by acceptSecContext
  31.         outStream.writeInt(token.length);
  32.         outStream.write(token);
  33.         outStream.flush();
  34.       }

  36.       // Context established!

  38.       // Create MessageProp for use with unwrap (will be set upon return from unwrap)
  39.       MessageProp prop = new MessageProp(0, false);

  41.       // Read token from client
  42.       token = new byte[inStream.readInt()];
  43.       inStream.readFully(token);
  44.       // Unwrap (decrypt) token sent by client
  45.       byte[] input = context.unwrap(token, 0, token.length, prop);
  46.       ...
  47.       // Create new token and send to client
  48.       byte[] reply = ...;
  49.       token = context.wrap(reply, 0, reply.length, prop);

  51.       outStream.writeInt(token.length);
  52.       outStream.write(token);
  53.       outStream.flush();
  54.       context.dispose();
  55.       socket.close();
  56.     }
  57.   }
  58. }

  4. Compile the sample code.

    % javac GssSpNegoServer.java
  5. Launch a new window and start the server.

    % xterm &
    % java -Djava.security.auth.login.config=jaas-krb5.conf \
           GssSpNegoServer
  6. Run the client application. GssClient takes two parameters: the service name and the name of the server that the service is running on. For example, if the service is host running on the machine j1hol-001, you would enter the following. When prompted for the password, enter changeit.

    % java -Djava.security.auth.login.config=jaas-krb5.conf \
           GssSpNegoClient host j1hol-001

Output for running the GssSpNegoServer example.

  1. Authenticated principal: [host/j1hol-001@J1LABS.EXAMPLE.COM]
  2. Waiting for incoming connections...
  3. Got connection from client /129.145.128.102
  4. SPNEGO Negotiated Mechanism = 1.2.840.113554.1.2.2 Kerberos V5
  5. Context Established!
  6. Client principal is test@J1LABS.EXAMPLE.COM
  7. Server principal is host/j1hol-001@J1LABS.EXAMPLE.COM
  8. Mutual authentication took place!
  9. Received data "Hello There!" of length 12
  10. Confidentiality applied: true
  11. Sending: Hello There! Thu May 06 12:11:15 PDT 2005

Output for running the GssSpNegoClient example.

  1. Kerberos password for test: changeit
  2. Authenticated principal: [test@J1LABS.EXAMPLE.COM]
  3. Connected to address j1hol-001/129.145.128.102
  4. SPNEGO Negotiated Mechanism = 1.2.840.113554.1.2.2 Kerberos V5
  5. Context Established!
  6. Client principal is test@J1LABS.EXAMPLE.COM
  7. Server principal is host@j1hol-001
  8. Mutual authentication took place!
  9. Sending message: Hello There!
  10. Will read token of size 93
  11. Received message: Hello There! Thu May 06 12:11:15 PDT 2005

Summary:

In this exercise, you learned how to write a client-server application that uses the Java GSS API with SPNEGO to negotiate an underlying security mechanism, such as Kerberos, and communicate securely using Kerberos as the underlying authentication system.

Note: Microsoft has implemented certain variations of the SPNEGO protocol, hence to inter-operate with Microsoft, we have added an MS mode via a new system property "sun.security.spnego.msinterop". This property is enabled to "true" by default. To disable it, you need to explicitly set this property to "false". To enable SPNEGO debugging, you can set the system property "sun.security.spnego.debug=true".


Advanced JGSS Security Programming

Advanced Security Programming in Java™ SE Authentication, Secure Communication and Single Sign-On

Java SE offers a rich set of APIs and features for developing secure Java applications and services. The exercise sessions listed here can help you to use the Java SE GSS APIs to build applications that authenticate their users, to communicate securely with other applications and services, and help you to configure your applications in a Kerberos environment to achieve Single Sign-On. In addition, you will also learn how to use stronger encryption algorithms in a Kerberos environment, and how to use Java GSS mechanisms such as SPNEGO to secure the association.

Setting up your Development Environment

Please download, install and configure the software listed below:

  1. Download and unzip the exercises in jgss-sample.zip.
  2. Install and set up a Solaris 10 machine (required for exercise 7)
  3. Configure a Kerberos server on a Solaris 10 machine with accounts used by the exercises. See Appendix A.
  4. Set the %JAVA_HOME% environment variable to point to the installation directory of your Java SE JDK
    Example: /usr/jdk/jdk6.0/

Exercises

This session includes five lessons. Each part contains one or more coding exercises.

  • Secure authentication using the Java Authentication and Authorization Service (JAAS)
  • Secure communication using three different secure communication technologies in Java SE
  • Deployment of secure applications for Single Sign-On in a Kerberos environment
  • Secure Communication using stronger encryption algorithms
  • Secure Authentication using SPNEGO Java GSS mechanism
  • HTTP/SPNEGO Authentication

Things to check:

Make sure you have verified the following configuration settings before proceding to the first Exercise:

  1. Set up the Key Distribution Center (KDC) on your Solaris 10 machine and start the Kerberos server.
  2. Set up the Kerberos configuration on your client machine.
  3. Ensure that JDK 6.0 is available.
    • Set up the JAVA_HOME environment variable to point to the JDK 6.0 installation directory
    • Place %JAVA_HOME%\bin (Windows) or $JAVA_HOME/bin (Solaris/Linux) in the path variable
    • Enter the following command to confirm that JDK version 1.6.0 is available:
      % java -version

Please work through these exercises in sequence.

Part I: Secure Authentication using the Java Authentication and Authorization Service (JAAS):

  1. Using the JAAS API
  2. Configuring JAAS for Kerberos Authentication

Part II: Secure Communications using Java SE 1.5 Security APIs

  3. Using the Java Generic Security Services (GSS) API
  4. Using the Java Simple Authentication and Security Layer (SASL) API
  5. Using the Java Secure Socket Extension (JSSE) with Kerberos

Part III: Deploying for Single Sign-On in a Kerberos Environment:

  6. Deploying for Single Sign-On

Part IV: Secure Communications using stronger encryption algorithms (Java SE 6.0):

  7. Configuring to use stronger Kerberos encryption algorithms, to secure the communication

Part V: Secure Authentication using SPNEGO Java GSS mechanism (Java SE 6.0):

  8. Using the Java Generic Security Services (GSS) API with other GSS mechanisms, such as SPNEGO

Part VI: HTTP/SPNEGO authentication:

  9. Using HTTP/SPNEGO Authentication

Resources:

  • J2se 1.5 API Specification
  • Java SE 6 API Specification

Where to send questions or feedback on this exercise :

Please send your questions on this set of exercises to the following email alias:
java-security@sun.com

Appendix A: Setting up Kerberos Accounts

Kerberos accounts are set up on the Key Distribution Center (KDC). Each entry in the Kerberos database contains a Kerberos principal. You should create a host-based principal for the machine that you will be running the servers (e.g., "host/j1hol-001") and a client principal (e.g., "test") for accessing the servers.

For Solaris, please refer to following documentation on how to setup Kerberos principals.

  1. Administering Principals
  2. System Administration Guide: Security Services

For Windows, please refer to Microsoft documentation. Here are some pointers.

  1. How to Create an Active Directory Server in Windows 2000
  2. Microsoft Kerberos
  3. Interoperability with Microsoft Windows 2000 Active Directory and Kerberos Services

The exercises assume that the operating system has been configured to use the correct Kerberos server. This configuration typically requires administration privileges. If you cannot configure the operating system, then you can use a Kerberos configuration file with your java command by using the -Djava.security.krb5.conf option. Here is an example of how to invoke one of the commands from the exercises to use the krb5.conf configuration file.

 % java
  -Djava.security.auth.login.config=jaas-krb5.conf\
  -Djava.security.krb5.conf=krb5.conf\
   Jaas client


Advanced JGSS Security Programming

Part II : Secure Communications using the Java SE 6 Security API

This part shows you how to build applications that perform secure communications. The Java SE 6 platform provides three standard APIs that allow applications to perform secure communications: The Java Generic Security Service (GSS), the Java SASL API, and the Java Secure Socket Extension (JSSE). When building an application, which of these APIs should you use? The answer depends on many factors, including requirements of the protocol or service, deployment infrastructure, and integration with other security services. For example, if you are building an LDAP client library, you would need to use the Java SASL API because use of SASL is part of LDAP's protocol definition. As an other example, if the service supports SSL, then the client application attempting to access the service would need to use JSSE.

Exercise 3: Using the Java Generic Security Service (GSS) API

Goal of this exercise:

The goal of this exercise is to learn how to use the Java GSS API to perform secure authentication and communication.

Background for this exercise:

The Generic Security Service API provides a uniform C-language interface to access various security services, such as authentication, message integrity, and message confidentiality. The Java GSS API provides the corresponding interface for Java applications. It allows applications to perform authentication and establish secure communication with the peer. One of the most common security service accessed via the GSS-API and Java GSS-API is Kerberos.

Resources for this Exercise:

  1. The JAAS and Java GSS-API Tutorials
  2. Generic Security Service API Version 2: Java Bindings (RFC 2853)
  3. Java GSS javadocs: org.ietf.jgss.

Overview of this Exercise:

This exercise is a client-server application that demonstrates how to communicate securely using the Java GSS API. The client and server parts first authenticate to Kerberos, as shown in Exercise 1. This stores the credentials in the subject. The application then executes an action that performs Java GSS operations (with Kerberos as the underlying GSS mechanism) inside of a Subject.doAs using the subject. The Java GSS Kerberos mechanism, because it is executing inside the doAs, obtains the Kerberos credentials from the subject, and uses them to authenticate with the peer and to exchange messages securely.

Steps to follow:

  1. Read the following code. This is located in src/GssServer.java.

    This code fragment defines the action to execute after the service principal has authenticated to the KDC. It replaces the MyAction of line 11 of Exercise 1. Note the highlighted lines. The code first creates an instance of GSSManager [line 8], which it uses to obtain its own credentials [line 10-11] and to create an instance of GSSContext [line 18]. It uses this context to perform authentication [the loop between lines 22-34]. Upon completing authentication, it accepts encrypted input from the client and uses the established security context to decrypt the data [line 45]. It then uses the security context to encrypt a reply containing the original input and the date [line 49], and then sends it back to the client.

Code listing for GssServer.java.

  1. static class GssServerAction implements PrivilegedExceptionAction {
  2. ...
  3.   public Object run() throws Exception {
  4.     // Create server socket for accepting connections
  5.     ServerSocket ss = new ServerSocket(localPort);

  7.     // Get own Kerberos credentials for accepting connection
  8.     GSSManager manager = GSSManager.getInstance();
  9.     Oid krb5Oid = new Oid("1.2.840.113554.1.2.2");
  10.     GSSCredential serverCreds = manager.createCredential(null,
  11.       GSSCredential.DEFAULT_LIFETIME, krb5Oid, GSSCredential.ACCEPT_ONLY);

  13.     while (true) {
  14.       Socket socket = ss.accept();
  15.       DataInputStream inStream = new DataInputStream(socket.getInputStream());
  16.       DataOutputStream outStream = new DataOutputStream(socket.getOutputStream());

  18.       GSSContext context = manager.createContext((GSSCredential)serverCreds);

  20.       // Do the context establishment loop
  21.       byte[] token = null;
  22.       while (!context.isEstablished()) {
  23.         // Read token
  24.         token = new byte[inStream.readInt()];
  25.         inStream.readFully(token);

  27.         // Process token
  28.         token = context.acceptSecContext(token, 0, token.length);

  30.         // Send a token to the peer if one was generated by acceptSecContext
  31.         outStream.writeInt(token.length);
  32.         outStream.write(token);
  33.         outStream.flush();
  34.       }

  36.       // Context established!

  38.       // Create MessageProp for use with unwrap (will be set upon return from unwrap)
  39.       MessageProp prop = new MessageProp(0, false);

  41.       // Read token from client
  42.       token = new byte[inStream.readInt()];
  43.       inStream.readFully(token);
  44.       // Unwrap (decrypt) token sent by client
  45.       byte[] input = context.unwrap(token, 0, token.length, prop);
  46.       ...
  47.       // Create new token and send to client
  48.       byte[] reply = ...;
  49.       token = context.wrap(reply, 0, reply.length, prop);

  51.       outStream.writeInt(token.length);
  52.       outStream.write(token);
  53.       outStream.flush();
  54.       context.dispose();
  55.       socket.close();
  56.     }
  57.   }
  58. }

  2. Compile the sample code.

% javac GssServer.java
  3. Read the following code. This is located in src/GssClient.java.

    This code fragment defines the action to execute after the client principal has authenticated to the KDC. It replaces the MyAction of line 11 of Exercise 1. Note the highlighted lines. The code first creates an instance of GSSManager [line 10], which it uses to obtain a principal name for the service that it is going to communicate with [line 12]. It then creates an instance of GSSContext [line 15,16] to perform authentication [the loop between lines 22-33] with the service. Upon completing authentication, it uses the established security context to encrypt a message [line 42] and sends it to the server. It then reads an encrypted message from the server and decodes it using the established security context [line 53].
Code listing for GssClient.java.

  1. static class GssClientAction implements PrivilegedExceptionAction {
  2. ...
  3.   public Object run() throws Exception {
  4.     // Create socket to server
  5.     Socket socket = new Socket(hostName, port);
  6.     DataInputStream inStream = new DataInputStream(socket.getInputStream());
  7.     DataOutputStream outStream = new DataOutputStream(socket.getOutputStream());

  9.     // Get service's principal name
  10.     GSSManager manager = GSSManager.getInstance();
  11.     Oid krb5Oid = new Oid("1.2.840.113554.1.2.2");
  12.     GSSName serverName = manager.createName(serverPrinc, GSSName.NT_HOSTBASED_SERVICE);

  14.     // Get the context for authentication
  15.     GSSContext context = manager.createContext(serverName, krb5Oid, null,
  16.        GSSContext.DEFAULT_LIFETIME);
  17.     context.requestMutualAuth(true); // Request mutual authentication
  18.     context.requestConf(true); // Request confidentiality

  20.     // Do the context establishment loop
  21.     byte[] token = new byte[0];
  22.     while (!context.isEstablished()) {
  23.       token = context.initSecContext(token, 0, token.length);
  24.       outStream.writeInt(token.length);
  25.       outStream.write(token);
  26.       outStream.flush();

  28.       // Check if we're done
  29.       if (!context.isEstablished()) {
  30.         token = new byte[inStream.readInt()];
  31.         inStream.readFully(token);
  32.       }
  33.     }

  35.     // Context established!

  37.     // Create MessageProp for use with unwrap (true means request confidentiality)
  38.     MessageProp prop = new MessageProp(0, true);

  40.     // Create encrypted message and send to server
  41.     byte[] reply = ...;
  42.     token = context.wrap(reply, 0, reply.length, prop);

  44.     outStream.writeInt(token.length);
  45.     outStream.write(token);
  46.     outStream.flush();

  48.     // Read token from server
  49.     token = new byte[inStream.readInt()];
  50.     inStream.readFully(token);

  52.     // Unwrap (decrypt) token sent by server
  53.     byte[] input = context.unwrap(token, 0, token.length, prop);
  54.     ...
  55.     context.dispose();
  56.     socket.close();
  57.     return null;
  58.   }
  59. }

  4. Compile the sample code.
    % javac GssClient.java
  5. Launch a new window and start the server.
    % xterm &
% java -Djava.security.auth.login.config=jaas-krb5.conf \
       GssServer
  6. Run the client application. GssClient takes two parameters: the service name and the name of the server that the service is running on. For example, if the service is host running on the machine j1hol-001, you would enter the following. When prompted for the password, enter changeit.

% java -Djava.security.auth.login.config=jaas-krb5.conf \
       GssClient host j1hol-001
  7. Observe the following output in the client and server applications' windows.

Output for running GssServer example.

  1. Authenticated principal: [host/j1hol-001@J1LABS.EXAMPLE.COM]
  2. Waiting for incoming connections...
  3. Got connection from client /129.145.128.102
  4. Context Established!
  5. Client principal is test@J1LABS.EXAMPLE.COM
  6. Server principal is host/j1hol-001@J1LABS.EXAMPLE.COM
  7. Mutual authentication took place!
  8. Received data "Hello There!" of length 12
  9. Confidentiality applied: true
  10. Sending: Hello There! Thu May 06 12:11:15 PDT 2005

Output for running GssClient example.

  1. Kerberos password for test: changeit
  2. Authenticated principal: [test@J1LABS.EXAMPLE.COM]
  3. Connected to address j1hol-001/129.145.128.102
  4. Context Established!
  5. Client principal is test@J1LABS.EXAMPLE.COM
  6. Server principal is host@j1hol-001
  7. Mutual authentication took place!
  8. Sending message: Hello There!
  9. Will read token of size 93
  10. Received message: Hello There! Thu May 06 12:11:15 PDT 2005

Summary:

In this exercise, you learned how to write a client-server application that uses the Java GSS API to authenticate and communicate securely with each other.

Next Steps

  1. Proceed to Exercise 4 to learn how to write a client/server application that uses the Java SASL API to authenticate and communicate securely with each other.
  2. Proceed to Exercise 5 to learn how to write a client/server application that uses the JSSE to authenticate and communicate securely with each other.
  3. Proceed to Exercise 6 to learn how to configure the sample programs that you have just used to achieve single sign-on in a Kerberos environment.

Exercise 4: Using the Java SASL API

Goal of this exercise:

The goal of this exercise is to learn how to use the Java SASL API to perform secure authentication and communication.

Background for this exercise:

Simple Authentication and Security Layer (SASL) specifies a challenge-response protocol in which data is exchanged between the client and the server for the purposes of authentication and (optional) establishment of a security layer on which to carry on subsequent communications. SASL allows different mechanisms to be used; each such mechanism is identified by a profile that defines the data to be exchanged and a name. SASL is used with connection-based protocols such as LDAPv3 and IMAPv4. SASL is described in RFC 4422.

The Java SASL API defines an API for applications to use SASL in a mechanism-independent way. For example, if you are writing a library for a networking protocol that uses SASL, you can use the Java SASL API to generate the data to be exchanged with the peer. When the library is deployed, you can dynamically configure the mechanisms to use with the library.

In addition to authentication, you can use SASL to negotiate a security layer to be used after authentication. But unlike the GSS-API, the properties of the security layer (such as whether you want integrity or confidentiality) is decided at negotiation time. (the GSS-API allows confidentiality to be turned on or off per message).

Resources for this exercise:

  1. The Java SASL API Programming and Deployment Guide
  2. The Java SASL API javadocs
  3. Simple Authentication and Security Layer (SASL) (RFC 4422)

Overview of this exercise:

This exercise is a client-server application that demonstrates how to communicate securely using the Java SASL API. The client and server parts first authenticate to Kerberos using Exercise 1. This stores the credentials in the subject. The application then executes an action that performs Java SASL API operations (with Kerberos as the underlying SASL mechanism) inside of a Subject.doAs using the subject. The SASL/Kerberos mechanism, because it is executing inside the doAs, obtains the Kerberos credentials from the subject, and uses them to authenticate with the peer and to exchange messages securely.

This example uses a simple protocol implemented by the AppConnection class. This protocol exchanges authentication commands and data commands. Each command consists of a type (e.g., AppConnection.AUTH_CMD), the length of the data to follow, and the data itself. The data is a SASL buffer if it is for authentication or encrypted/integrity-protected application data; it is plain application data otherwise.

Steps to follow:

  1. Read the following code. This is located in src/SaslTestServer.java.

    This code fragment defines the action to execute after the service principal has authenticated to the KDC. It replaces the MyAction of line 11 of Exercise 1. Note the highlighted lines. The server specifies the quality-of-protections that it will support [line 9] and then creates an instance of SaslServer to perform the authentication [line 21]. The challenge-response protocol of SASL is performed in the while loop [lines 33-49], with the server sending challenges to the client and processing the responses from the client. After authentication, the identity of the authenticated client can be obtained via a call to getAuthorizedID() [line 61]. If a security layer was negotiated, the server can exchange data securely with the client [lines 66,70].

Code listing for SaslTestServer.java.

  1. static class SaslServerAction implements PrivilegedExceptionAction {
  2. ...
  3.   public Object run() throws Exception {
  4.     // Create server socket for accepting connections
  5.     ServerSocket ss = new ServerSocket(localPort);

  7.     // Support all quality-of-protection options
  8.     HashMap<String,Object> props = new HashMap<String,Object>();
  9.     props.put(Sasl.QOP, "auth-conf,auth-int,auth");

  11.     while (true) {
  12.       // Create application-level connection to handle request
  13.       Socket socket = ss.accept();
  14.       AppConnection conn = new AppConnection(socket);

  16.       // Normally, the application protocol will negotiate which
  17.       // SASL mechanism to use. In this simplified example, we
  18.       // will always use "GSSAPI" (the name of the mechanism that does Kerberos via GSS-API)

  20.       // Create SaslServer to perform authentication
  21.       SaslServer srv = Sasl.createSaslServer("GSSAPI", service, serviceName, props, cbh);

  23.       if (srv == null) {
  24.         // ... handle error
  25.       }

  27.       // Read the initial response from client
  28.       byte[] response = conn.receive(AppConnection.AUTH_CMD);
  29.       AppConnection.AppReply clientMsg;
  30.       boolean auth = false;

  32.       // Perform authentication
  33.       while (!srv.isComplete()) {
  34.         try
  35.           // Generate challenge based on response
  36.           byte[] challenge = srv.evaluateResponse(response);
  37.           if (srv.isComplete()) {
  38.             conn.send(AppConnection.SUCCESS, challenge);
  39.             auth = true;
  40.           } else {
  41.             clientMsg = conn.send(AppConnection.AUTH_IN_PROGRESS, challenge);
  42.             response = clientMsg.getBytes();
  43.           }
  44.         } catch (SaslException e) {
  45.           // Send failure notification to client
  46.           conn.send(AppConnection.FAILURE, null);
  47.           break;
  48.         }
  49.       }

  51.       // Authentication completed!

  53.       // Check status of authentication
  54.       if (srv.isCompleted() && auth) {
  55.         System.out.println("authorized client is: " + srv.getAuthorizationID());
  56.       } else {
  57.         // Report failure ...
  58.       }

  60.       // Find out whether security layer was negotiated
  61.       String qop = (String) srv.getNegotiatedProperty(Sasl.QOP);
  62.       boolean sl = (qop.equals("auth-conf") || qop.equals("auth-int"));

  64.       // Read and decrypt message from client
  65.       byte[] msg = conn.receive(AppConnection.DATA_CMD);
  66.       byte[] realMsg = (sl ? srv.unwrap(msg, 0, msg.length) : msg);
  67.       ...
  68.       // Create and encrypt message to send to client
  69.       byte[] reply = ...;
  70.       byte[] realReply = (sl ? srv.wrap(reply, 0, reply.length) : reply);
  71.       conn.send(AppConnection.SUCCESS, realReply);
  72.     }
  73.   }
  74. }

  2. Compile the sample code.
    % javac SaslTestServer.java
  3. Read the following code. This is located in src/SaslTestClient.java. This code fragment defines the action to execute after the client principal has authenticated to the KDC. It replaces the MyAction of line 11 of Exercise 1. Note the highlighted lines. The program first specifies the quality of protection that it wants (in this case, confidentiality) [line 8] and then creates an instance of SaslClient to use for authentication [lines 11-12]. It then checks whether the mechanism has an initial response and if so, gets the response by invoking evaluateChallenge() with an empty byte array [line 20]. It then sends the response to the server to begin the authentication. The challenge-response protocol of SASL is performed in the while loop [lines 24-39], with the client evaluating the challenges that it gets from the server and sending the server the corresponding responses to the challenges. After authentication, the client can proceed to communicate with the server using the negotiated security layer [lines 48,55].

Code listing for SaslTestClient.java.

  1. static class SaslClientAction implements PrivilegedExceptionAction {
  2. ...
  3.   public Object run() throws Exception {
  4.     // Create application-level connection
  5.     AppConnection conn = new AppConnection(serverName, port);

  7.     HashMap<String,Object> props = new HashMap<String,Object>();
  8.     props.put(Sasl.QOP, "auth-conf"); // Request confidentiality

  10.     // Create SaslClient to perform authentication
  11.     SaslClient clnt = Sasl.createSaslClient(
  12.       new String[]{"GSSAPI"}, null, service, serverName, props, cbh);
  13.     if (clnt == null) {
  14.       // ... handle error
  15.     }

  17.     byte[] challenge;

  19.     // Get initial response for authentication
  20.     byte[] response = clnt.hasInitialResponse() ? clnt.evaluateChallenge(EMPTY) : EMPTY;
  21.     AppConnection.AppReply reply = conn.send(AppConnection.AUTH_CMD, response);

  23.     // Repeat until authentication terminates
  24.     while (!clnt.isComplete() &&
  25.       (reply.getStatus() == AppConnection.AUTH_INPROGRESS ||
  26.        reply.getStatus() == AppConnection.SUCCESS))
  27.       // Evaluate challenge to generate response
  28.       challenge = reply.getBytes()
  29.       response = clnt.evaluateChallenge(challenge)

  31.       if (reply.getStatus() == AppConnection.SUCCESS) {
  32.         if (response != null) {
  33.           throw new Exception("Protocol error")
  34.         }
  35.         break;
  36.       }
  37.       // Send response to server and read server's next challenge
  38.       reply = conn.send(AppConnection.AUTH_CMD, response);
  39.     }
  40.     // Authentication completed!
  41.     // Find out whether security layer was negotiated
  42.     String qop = (String) srv.getNegotiatedProperty(Sasl.QOP);
  43.     boolean sl = (qop.equals("auth-conf") || qop.equals("auth-int"));

  45.     byte[] msg = ...;

  47.     // Create and send encrypted data to server
  48.     byte[] encrypted = (sl ? clnt.wrap(msg, 0, msg.length) : msg);
  49.     reply = conn.send(AppConnection.DATA_CMD, encrypted);) {

  51.     ...

  53.     // Read and decrypt data from server
  54.     byte[] encryptedReply = reply.getBytes();
  55.     byte[] clearReply = (sl ? clnt.unwrap(encryptedReply, 0, encryptedReply.length)
  56.       : encryptedReply);
  57.     conn.close();
  58.     return null;
  59.   }
  60. }
  4. Compile the sample code.
    % javac SaslTestClient.java
  5. Launch a new window and start the server. SaslTestServer takes two parameters: the service name and the name of the server that the service is running on. For example, if the service is host running on the machine j1hol-001, you would enter the following.
    % xterm &
    % java
     -Djava.security.auth.login.config=jaas-krb5.conf \
           SaslTestServer host j1hol-001
  6. Run the client application. SaslTestClient takes two parameters: the service name and the name of the server that the service is running on. For example, if the service is host running on the machine j1hol-001, you would enter the following. When prompted for the password, enter changeit.

    % java -Djava.security.auth.login.config=jaas-krb5.conf \
           SaslTestClient host j1hol-001
  7. Observe the following output in the client and server applications' windows.

Output for running the SaslTestServer example.

  1. Authenticated principal: [host/j1hol-001@J1LABS.EXAMPLE.COM]
  2. Waiting for incoming connections...
  3. Got connection from client /129.145.128.102
  4. Client authenticated; authorized client is: test@J1LABS.EXAMPLE.COM
  5. Negotiated QOP: auth-conf
  6. Received: Hello There!
  7. Sending: Hello There! Fri May 07 15:32:37 PDT 2005
  8. Received data "Hello There!" of length 12

Output for running the SaslTestClient example.

  1. Kerberos password for test: changeit
  2. Authenticated principal: [test@J1LABS.EXAMPLE.COM]
  3. Connected to address j1hol-001/129.145.128.102
  4. Client authenticated.
  5. Negotiated QOP: auth-conf
  6. Sending: Hello There!
  7. Received: Hello There! Fri May 07 15:32:37 PDT 2005
  8. To try the program using different quality-of-protection, change line 8 in SaslTestClient. For example, replace line 8 with the following line to use integrity protection on (no confidentiality).
    props.put(Sasl.QOP, "auth-int");

Summary:

In this exercise, you learned how to write a client-server application that uses the Java SASL API to authenticate and communicate securely with each other.

Next Steps

  1. Proceed to Exercise 5 to learn how to write a client/server application that uses the JSSE to authenticate and communicate securely with each other.
  2. Proceed to Exercise 6 to learn how to configure the sample programs that you have just used to achieve single sign-on in a Kerberos environment.

Exercise 5: Using the Java Secure Socket Extension with Kerberos

Goal of this exercise:

The goal of this exercise is to learn how to use the JSSE API to perform secure authentication and communication using Kerberos cipher suites.

Background for this exercise:

Secure Socket Layer (SSL) and Transport Layer Security (TLS) are the most widely used protocols for implementing cryptography on the Internet. TLS is the Internet standard evolved from SSL. SSL/TLS provides application-level protocols (such as HTTP and LDAP) with secure authentication and communication. For example, HTTPS is the resulting protocol of using HTTP over SSL/TLS. SSL/TLS is used not only for standard protocols such as HTTP, it is also widely used when building custom applications using custom protocols that need to communicate securely.

SSL/TLS traditionally used certificate-based authentication and is commonly used for server-authentication. For example, when a Web client such as a browser accesses a secure Web site (server) on behalf of a user, the server sends its certificate to the browser so that the browser can verify the identity of the server. This ensures that the user does not divulge confidential information (such as credit card information) to a bogus server. Recently, a new standard allows the use of Kerberos with TLS. This means instead of using certificate-based authentication, an application can use Kerberos credentials and take advantage of the Kerberos infrastructure in the deployment environment. Using Kerberos cipher suites also provides automatic support for mutual authentication in which the client is also authenticated in addition to the server.

The decision of whether to use Java GSS, Java SASL, or JSSE for a particular application often depends upon several factors, including (the protocols being used by) the services with which the application interacts, the deployment environment (PKI or Kerberos-based), and the application's security requirements. JSSE provides a secure end-to-end channel that takes care of the I/O and transport, while Java GSS and Java SASL provide encryption and integrity-protection on the data, but the application is responsible for transporting the secured data to its peer. Some details about factors for deciding when to use JSSE versus Java GSS are presented in the document, When to use Java GSS vs. JSSE.

Resources for this exercise:

  1. Java Secure Socket Extension (JSSE) Reference Guide
  2. The JSSE javadocs: javax.net and javax.net.ssl
  3. The SSL Protocol version 3.0
  4. The TLS Protocol Version 1.0 (RFC 2246)
  5. Addition of Kerberos Cipher Suites to Transport Layer Security TLS (RFC 2712)
  6. When to use Java GSS vs. JSSE

Overview of this exercise:

This exercise is a client-server application that demonstrates how to communicate securely using the JSSE and Kerberos cipher suites. The client and server parts first authenticate to Kerberos using Exercise 1. This stores the credentials in the subject. The application then executes an action that performs JSSE operations (using a Kerberos cipher suite) inside of a Subject.doAs using the subject. The Kerberos cipher suite implementation, because it is executing inside the doAs, obtains the Kerberos credentials from the subject, and uses them to authenticate with the peer and to exchange messages securely. This example sends newline-terminated messages, encrypted using the negotiated cipher suite and integrity-protected, back and forth between client and server.

According to the standard (RFC 2712) all Kerberos-enabled TLS applications use the same service name, namely, "host". That is why in this exercise, you do not need to explicitly supply the Kerberos service name.

Steps to follow:

  1. Read the following code. This is located in src/JsseServer.java

    This code fragment defines the action to execute after the service principal has authenticated to the KDC. It replaces the MyAction of line 11 of Exercise 1. Note the highlighted lines. The server first creates an SSLServerSocket [lines 5-8]. This is analogous to an application creating a plain ServerSocket except an SSLServerSocket will provide automatic authentication, encryption and decryption, as needed. The server then sets the cipher suites that it wants to use [lines 11-12]. The server then runs in a loop, accepting connections from SSL clients [line 17], and reads and writes from the SSL socket [lines 23, 28]. The server can find out the identities of the owners of socket by invoking the getLocalPrincipal() and getPeerPrincipal() methods [lines 32-33].

Code listing for JsseServer.java.

  1. static class JsseServerAction implements PrivilegedExceptionAction {
  2. ...
  3.   public Object run() throws Exception {
  4.     // Create TLS socket for accepting connections
  5.     SSLServerSocketFactory sslssf =
  6.       (SSLServerSocketFactory) SSLServerSocketFactory.getDefault();
  7.     SSLServerSocket sslServerSocket =
  8.       (SSLServerSocket) sslssf.createServerSocket(localPort);

  10.     // Enable only a Kerberos cipher suite
  11.     String enabledSuites[] = { "TLS_KRB5_WITH_3DES_EDE_CBC_SHA" };
  12.     sslServerSocket.setEnabledCipherSuites(enabledSuites);
  13.     // Should handle exception if enabledSuites is not supported

  15.     while (true) {
  16.       // Create socket to handle request
  17.       SSLSocket sslSocket = (SSLSocket) sslServerSocket.accept();
  18.       BufferedReader in = new BufferedReader(new InputStreamReader(
  19.         sslSocket.getInputStream()));
  20.       BufferedWriter out = new BufferedWriter(new OutputStreamWriter(
  21.         sslSocket.getOutputStream()));

  23.       String inStr = in.readLine();
  24.       // ... use inStr

  26.       // Compose and send reply
  27.       String outStr = inStr + " " + new Date().toString() + "\n";
  28.       out.write(outStr);
  29.       out.flush();

  31.       // Get names of principal at both ends of secure connection
  32.       Principal self = sslSocket.getSession().getLocalPrincipal();
  33.       Principal peer = sslSocket.getSession().getPeerPrincipal();

  35.       sslSocket.close();
  36.     }
  37.   }
  38. }

  2. Compile the sample code.

    % javac JsseServer.java
  3. Read the following code. This is located in src/JsseClient.java. This code fragment defines the action to execute after the client principal has authenticated to the KDC. It replaces the MyAction of line 11 of Exercise 1. Note the highlighted lines. The client first creates an SSLSocket. The client then sets the cipher suites that it wants to use [lines 11-12]. The client then exchanges messages with the server using the SSLSocket by reading and writing to the socket's input/output streams. The client can find out the identities of the owners of socket by invoking the getLocalPrincipal() and getPeerPrincipal() methods [lines 26-27].

Code listing for JsseClient.java

  1. static class JsseClientAction implements PrivilegedExceptionAction {
  2. ...
  3.   public Object run() throws Exception {
  4.     // Create SSL connection
  5.     SSLSocketFactory sslsf = (SSLSocketFactory) SSLSocketFactory.getDefault();
  6.     SSLSocket sslSocket = (SSLSocket) sslsf.createSocket(server, port);

  8.     // Enable only a Kerberos cipher suite
  9.     String enabledSuites[] = { "TLS_KRB5_WITH_3DES_EDE_CBC_SHA" };
  10.     sslSocket.setEnabledCipherSuites(enabledSuites);
  11.     // Should handle exception if enabledSuites is not supported

  13.     BufferedReader in = new BufferedReader(new InputStreamReader(
  14.       sslSocket.getInputStream()));
  15.     BufferedWriter out = new BufferedWriter(new OutputStreamWriter(
  16.       sslSocket.getOutputStream()));

  18.     String outStr = ...;
  19.     out.write(outStr);
  20.     out.flush();

  22.     String inStr = in.readLine();
  23.     // ... use inStr

  25.     // Get names of principal at both ends of secure connection
  26.     Principal self = sslSocket.getSession().getLocalPrincipal();
  27.     Principal peer = sslSocket.getSession().getPeerPrincipal();

  29.     sslSocket.close();
  30.     return null;
  31.   }
  32. }

  4. Compile the sample code.
    % javac JsseClient.java
  5. Launch a new window and start the server. JsseServer takes one parameter: the name of the server that the JSSE service is running on. For example, if it is running on the machine j1hol-001, you would enter the following.
    % xterm &
    % java
     -Djava.security.auth.login.config=jaas-krb5.conf \
           JsseServer j1hol-001
  6. Run the client application. JsseClient takes one parameter: the name of the server that the JSSE service is running on. For example, if the service is running on the machine j1hol-001, you would enter the following. When prompted for a password, enter changeit.

    % java -Djava.security.auth.login.config=jaas-krb5.conf \
           JsseClient j1hol-001
  7. Observe the following output in the client and server applications' windows.

Output for running the JsseServer example.

  1. Authenticated principal: [host/j1hol-001@J1LABS.EXAMPLE.COM]
  2. Waiting for incoming connections...
  3. Got connection from client /129.145.128.102
  4. Received: Hello There!
  5. Sending: Hello There! Fri May 07 15:32:37 PDT 2005
  6. Cipher suite in use: TLS_KRB5_WITH_3DES_EDE_CBC_SHA
  7. I am: host/j1hol-001@J1LABS.EXAMPLE.COM
  8. Client is: test@J1LABS.EXAMPLE.COM

Output for running the JsseClient example.

  1. Kerberos password for test: changeit
  2. Authenticated principal: [test@J1LABS.EXAMPLE.COM]
  3. Sending: Hello There!
  4. Received: Hello There! Fri May 07 15:32:37 PDT 2005
  5. Cipher suite in use: TLS_KRB5_WITH_3DES_EDE_CBC_SHA
  6. I am: test@J1LABS.EXAMPLE.COM
  7. Server is: host/j1hol-001@J1LABS.EXAMPLE.COM

Summary:

In this exercise, you learned how to write a client-server application that uses JSSE to authenticate and communicate securely with each other, using Kerberos as the underlying authentication system.

Next Steps

  1. Proceed to Exercise 6 to learn how to configure the sample programs in Exercises 3, 4, and 5 to achieve single sign-on in a Kerberos environment.


SPEGNO Authentication

Part VI: HTTP/SPNEGO Authentication

  • Exercise 9: Using HTTP/SPNEGO Authentication

  • What is HTTP SPNEGO
    • Web Authentication
    • Proxy Authentication
  • How to use HTTP/SPNEGO Authentication
    • Kerberos 5 Configuration
    • Username and Password Retrieval
    • Scheme Preference
    • Fallback

  • Example

Exercise 9: Using HTTP/SPNEGO Authentication

What is HTTP SPNEGO

HTTP SPNEGO supports the Negotiate authentication scheme in an HTTP communication. SPNEGO supports types of authentication:

Web Authentication

The Web Server responds with

       HTTP/1.1 401 Unauthorized
       WWW-Authenticate: Negotiate

the client will need to send a header like

       Authorization: Negotiate YY.....

to authenticate itself to the server

Proxy Authentication

The Web Server responses with

       HTTP/1.1 407 Proxy Authentication Required
       Proxy-Authenticate: Negotiate

the client will need to send a header like

       Proxy-Authorization: Negotiate YY.....

to authenticate itself to the proxy server

This feature supports both types of authentication.

How to use HTTP/SPNEGO Authentication

There is no new public API function involved in the new feature, but several configurations are needed to perform a success communication:

Kerberos 5 Configuration

Since the SPNEGO mechanism will call JGSS, which in turns calls the Kerberos V5 login module to do real works. Kerberos 5 configurations are needed. This includes the following:

  • Some way to provide Kerberos configurations. This can be achieved with the Java system property java.security.krb5.conf. For example:

            java -Djava.security.krb5.conf=krb5.conf \
                 -Djavax.security.auth.useSubjectCredsOnly=false \
                 ClassName

  • A JAAS config file denoting what login module to use. HTTP SPNEGO codes will look for the standard entry named com.sun.security.jgss.krb5.initiate.

For example, you can provide a file spnegoLogin.conf:

          com.sun.security.jgss.krb5.initiate {
              com.sun.security.auth.module.Krb5LoginModule
                  required useTicketCache=true;
          };

and run java with:

            java -Djava.security.krb5.conf=krb5.conf \
                 -Djava.security.auth.login.config=spnegoLogin.conf \
                 -Djavax.security.auth.useSubjectCredsOnly=false \
                 ClassName

Username and Password Retrieval

Just like any other HTTP authentication scheme, the client can provide a customized java.net.Authenticator to feed username and password to the HTTP SPNEGO module if they are needed (i.e. there is no credential cache available). The only authentication information needed to be checked in your Authenticator is the scheme which can be retrieved with getRequestingScheme(). The value should be "Negotiate".

This means your Authenticator implementation will look like:

    class MyAuthenticator extends Authenticator {

        public PasswordAuthentication getPasswordAuthentication () {
            if (getRequestingScheme().equalsIgnoreCase("negotiate")) {
                String krb5user;
                char[] krb5pass;
                // get krb5user and krb5pass in your own way
                ....
                return (new PasswordAuthentication (krb5user,
                            krb5pass));
            } else {
                ....
            }
        }
    }

Note : According to the specification of java.net.Authenticator, it's designed to get the username and password at the same time, so do not specify principal=xxx in the JAAS config file.

Scheme Preference

The client can still provide system property http.auth.preference to denote that a certain scheme should always be used as long as the server request for it. You can use "SPNEGO" or "Kerberos" for this system property. "SPNEGO" means you prefer to response the Negotiate scheme using the GSS/SPNEGO mechanism; "Kerberos" means you prefer to response the Negotiate scheme using the GSS/Kerberos mechanism. Normally, when authenticating against a Microsoft product, you can use "SPNEGO". The value "Kerberos" also works for Microsoft servers. It's only needed when you encounter a server which knows Negotiate but doesn't know about SPNEGO.

If http.auth.preference is not set, the internal order choosen is:

  • GSS/SPNEGO -> Digest -> NTLM -> Basic

Noticed that Kerberos does not appear in this list, since whenever Negotiate is supported, GSS/SPNEGO is always chosen.

Fallback

If the server has provided more than one authentication scheme (including Negotiate), according to the processing order mentioned in the last section, Java will try to challenge the Negotiate scheme. However, if the protocol cannot be established successfully (for example; The kerberos configuration is not correct, or the server's hostname is not recorded in the KDC principal DB, or the username and password provided by Authenticator is wrong), then the second strongest scheme will be automatically used.

Note : If http.auth.preference is set to SPNEGO or Kerberos, then SPNEGO assumes you only want to try the Negotiate scheme even if it fails. SPNEGO will not fallback to any other scheme and your program will throw an IOException saying it received a 401 or 407 error from the HTTP response.

Example

Assume that you have an IIS Server running on a Windows Server within an Active Directory. A web page on this server is configured to be protected by Integrated Windows Authentication. This means the server will prompt for both Negotiate and NTLM authentication.

You need to prepare these files to get the protected file:

Code listing for RunHttpSpnego.java

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.Authenticator;
import java.net.PasswordAuthentication;
import java.net.URL;

public class RunHttpSpnego {

    static final String kuser = "username"; // your account name
    static final String kpass = "password"; // your password for the account

    static class MyAuthenticator extends Authenticator {
        public PasswordAuthentication getPasswordAuthentication() {
            // I haven't checked getRequestingScheme() here, since for NTLM
            // and Negotiate, the usrname and password are all the same.
            System.err.println("Feeding username and password for "
               + getRequestingScheme());
            return (new PasswordAuthentication(kuser, kpass.toCharArray()));
        }
    }

    public static void main(String[] args) throws Exception {
        Authenticator.setDefault(new MyAuthenticator());
        URL url = new URL(args[0]);
        InputStream ins = url.openConnection().getInputStream();
        BufferedReader reader = new BufferedReader(new InputStreamReader(ins));
        String str;
        while((str = reader.readLine()) != null)
            System.out.println(str);
    }
}

Code listing for krb.conf

[libdefaults]
    default_realm = AD.LOCAL
[realms]
    AD.LOCAL = {
        kdc = kdc.ad.local
    }

Code listing for login.conf

com.sun.security.jgss.krb5.initiate {
  com.sun.security.auth.module.Krb5LoginModule required
 doNotPrompt=false useTicketCache=true;
};

Then, compile RunHttpSpnego.java and run

java -Djava.security.krb5.conf=krb5.conf \
    -Djava.security.auth.login.config=login.conf \
    -Djavax.security.auth.useSubjectCredsOnly=false \
    RunHttpSpnego \
    http://www.ad.local/hello/hello.html

You will see:

Feeding username and password for Negotiate
<h1>Hello, You got me!</h1>

In fact, if you are running on a Windows machine as a domain user, or, you are running on a Linux or Solaris machine that has already issued the kinit command and got the credential cache. The class MyAuthenticator will be completely ignored, and the output will be simply

<h1>Hello, You got me!</h1>

which shows the username and password are not consulted. This is the so-called Single Sign-On.

Also, You can just run

java RunHttpSpnego \
    http://www.ad.local/hello/hello.html

to see how the fallback is done, in which case you will see

Feeding username and password for ntlm
<h1>Hello, You got me!</h1>


Feedback

Please e-mail Java GSS-API and JAAS tutorial comments to:

java-security@sun.com

Please specify which tutorial(s) you are referring to in your message.

Though we value your input, before sending problem reports please search the Java Security Q&A Archives:

http://archives.java.sun.com/archives/java-security.html

The above mailing list is not a subscription list or a support mechanism. It is simply a one-way channel that you can use to send comments to the Java 2 Standard Edition security team.

Please note that due to the volume of messages we receive, we may not be able to respond to every individual message.


Introduction to JAAS and Java GSS-API Tutorials

This page links to a series of tutorials demonstrating various aspects of the use of JAAS (JavaTM Authentication and Authorization Service) and JavaTM GSS-API.

JAAS can be used for two purposes:

  • for authentication of users, to reliably and securely determine who is currently executing Java code, and

  • for authorization of users to ensure they have the access control rights (permissions) required to do security-sensitive operations.

Java GSS-API is used for securely exchanging messages between communicating applications. The Java GSS-API contains the Java bindings for the Generic Security Services Application Program Interface (GSS-API) defined in RFC 2853. GSS-API offers application programmers uniform access to security services atop a variety of underlying security mechanisms, including Kerberos.

Note: JSSE is another API that can be used for secure communication. For the differences between the two, see When to use Java GSS-API vs. JSSE.

The reason both JAAS and Java GSS-API tutorials are presented together is because JAAS authentication is typically performed prior to secure communication using Java GSS-API. Thus JAAS and Java GSS-API are related and often used together. However, it is possible for applications to use JAAS without Java GSS-API, and it is also possible to use Java GSS-API without JAAS. Furthermore, JAAS itself can be used simply for authentication or for both authentication and authorization.

The following tutorials provide working examples for all of the scenarios described above.

  1. Use of JavaTM GSS-API for Secure Message Exchanges Without JAAS Programming

    Demonstrates the use of the Java GSS-API for secure message exchanges between a client application and a server application.

  2. JAAS Authentication

    Explains how an application can authenticate users using JAAS.

  3. JAAS Authorization

    Explains how to enforce user-based access controls using JAAS.

  4. Use of JAAS Login Utility

    Describes a utility program that authenticates a user using JAAS and executes any application as that user. The appropriate user-based access controls are enforced while the application executes. This utility, as a convenience, essentially performs the operations described in the JAAS Authentication and JAAS Authorization tutorials on your behalf. Therefore it is possible to skip directly to this tutorial if you do not need to know how to perform JAAS authentication and authorization directly.

  5. Use of JAAS Login Utility and Java GSS-API for Secure Message Exchanges

    The most comprehensive tutorial. The Login utility is used to authenticate a service user and to start up a server application as that user. The Login utility is also used to authenticate a client user and to start up a client application as that user. Finally the client and server applications, on behalf of their authenticated client and service users, exchange secure messages using the Java GSS-API.

  6. More Things You Can Do With Java GSS-API and JAAS

    Shows additional operations the server application in the previous tutorial can perform once communication has been established with the client application.

All applications in all tutorials in this series utilize Kerberos Version 5 as the underlying technology for authentication and secure communication. See Kerberos Requirements. The term "Kerberos" used throughout the tutorials is meant to refer to Kerberos Version 5.

Related Documentation

API Specifications

  • com.sun.security.jgss Package
  • com.sun.security.auth Package
  • com.sun.security.auth.callback Package
  • com.sun.security.auth.login Package
  • com.sun.security.auth.module Package

User Guides

  • JavaTM Authentication and Authorization Service (JAAS) Reference Guide.

Papers

  • Single Sign-on Using Kerberos in Java

  • JAAS white paper

Tutorials

  • Java Security Tutorial

Other Java Security Documentation

  • Default Policy Implementation and Policy File Syntax

  • Permissions in the JavaTM 2 SDK

  • Java 2 Security Architecture

Reference Document

  • Generic Security Service API Version 2: Java Bindings presented and requested comments on the Java bindings for GSS-API that are incorporated into Java GSS-API.

Copyright © 2001-2002 Sun Microsystems, Inc. All Rights Reserved.

Next Tutorial Feedback


JAAS Authentication

The JavaTM Authentication and Authorization Service (JAAS) was introduced as an optional package to the JavaTM 2 SDK, Standard Edition (J2SDK), v 1.3. JAAS has now been integrated into the J2SDK 1.4.

JAAS can be used for two purposes:

  • for authentication of users, to reliably and securely determine who is currently executing Java code, regardless of whether the code is running as an application, an applet, a bean, or a servlet; and

  • for authorization of users to ensure they have the access control rights (permissions) required to do the actions performed.

This section provides a basic tutorial for the authentication component. The authorization component will be described in the JAAS Authorization tutorial.

JAAS authentication is performed in a pluggable fashion. This permits Java applications to remain independent from underlying authentication technologies. New or updated technologies can be plugged in without requiring modifications to the application itself. An implementation for a particular authentication technology to be used is determined at runtime. The implementation is specified in a login configuration file. The authentication technology used for this tutorial is Kerberos. (See Kerberos Requirements.)

The rest of this tutorial consists of the following sections:

  1. The Authentication Tutorial Code

  2. The Login Configuration

  3. Running the Code

  4. Running the Code with a Security Manager

If you want to first see the tutorial code in action, you can skip directly to Running the Code and then go back to the other sections to learn about coding and configuration file details.

The Authentication Tutorial Code

Our authentication tutorial code is contained in a single source file, JaasAcn.java. This file's main method performs the authentication and then reports whether or not authentication succeeded.

The code for authenticating the user is very simple, consisting of just two steps:

  1. Instantiate a LoginContext.

  2. Call the LoginContext's login method.

First the basic code is shown, followed by a complete listing of the JaasAcn.java source file, complete with import statements and error handling.

Instantiating a LoginContext

In order to authenticate a user, you first need a javax.security.auth.login.LoginContext. Here is the basic way to instantiate a LoginContext:

import javax.security.auth.login.*;
. . .
LoginContext lc =
    new LoginContext(<config file entry name>,
           <CallbackHandler to be used for user interaction>);
and here is the specific way our tutorial code does the instantiation:
import javax.security.auth.login.*;
import com.sun.security.auth.callback.TextCallbackHandler;
. . .
LoginContext lc =
    new LoginContext("JaasSample",
          new TextCallbackHandler());

The arguments are the following:

  1. The name of an entry in the JAAS login configuration file

    This is the name for the LoginContext to use to look up an entry for this application in the JAAS login configuration file, described here. Such an entry specifies the class(es) that implement the desired underlying authentication technology(ies). The class(es) must implement the LoginModule interface, which is in the javax.security.auth.spi package.

    In our sample code, we use the Krb5LoginModule in the com.sun.security.auth.module package, which performs Kerberos authentication.

    The entry in the login configuration file we use for this tutorial (see jaas.conf) has the name "JaasSample", so that is the name we specify as the first argument to the LoginContext constructor.

  2. A CallbackHandler instance.

    When a LoginModule needs to communicate with the user, for example to ask for a user name and password, it does not do so directly. That is because there are various ways of communicating with a user, and it is desirable for LoginModules to remain independent of the different types of user interaction. Rather, the LoginModule invokes a CallbackHandler to perform the user interaction and obtain the requested information, such as the user name and password. (CallbackHandler is an interface in the javax.security.auth.callback pkg.)

    An instance of the particular CallbackHandler to be used is specified as the second argument to the LoginContext constructor. The LoginContext forwards that instance to the underlying LoginModule (in our case Krb5LoginModule). An application typically provides its own CallbackHandler implementation. Two simple CallbackHandlers, TextCallbackHandler and DialogCallbackHandler, are provided in the com.sun.security.auth.callback package as sample implementations. Our code uses the TextCallbackHandler, which outputs information to and reads input from the command line.

Calling the LoginContext's login Method

Once we have a LoginContext lc, we can call its login method to carry out the authentication process:

lc.login();

The LoginContext instantiates a new empty javax.security.auth.Subject object (which represents the user or service being authenticated). The LoginContext constructs the configured LoginModule (in our case Krb5LoginModule) and initializes it with this new Subject and TextCallbackHandler.

The LoginContext's login method then calls methods in the Krb5LoginModule to perform the login and authentication. The Krb5LoginModule will utilize the TextCallbackHandler to obtain the user name and password. Then the Krb5LoginModule will use this information to get the user credentials from the Kerberos KDC. See the Kerberos reference documentation.

If authentication is successful, the Krb5LoginModule populates the Subject with (1) a Kerberos Principal representing the user and (2) the user's credentials (TGT). See Subjects, Principals, Authentication, and Credentials for information on these terms.

The calling application can subsequently retrieve the authenticated Subject by calling the LoginContext's getSubject method, although doing so is not necessary for this tutorial.

The Complete JaasAcn.java Code

Now that you have seen the basic code required to authenticate the user, we can put it all together into the full class in JaasAcn.java, which includes relevant import statements and error handling:

import javax.security.auth.*;
import javax.security.auth.callback.*;
import javax.security.auth.login.*;
import com.sun.security.auth.callback.TextCallbackHandler;

/**
 * This JaasAcn application attempts to authenticate a user
 * and reports whether or not the authentication was successful.
 */
public class JaasAcn {

  public static void main(String[] args) {

      // Obtain a LoginContext, needed for authentication. Tell
      // it to use the LoginModule implementation specified by
      // the entry named "JaasSample" in the JAAS login
      // configuration file and to also use the specified
      // CallbackHandler.
      LoginContext lc = null;
      try {
          lc = new LoginContext("JaasSample",
                      new TextCallbackHandler());
      } catch (LoginException le) {
          System.err.println("Cannot create LoginContext. "
              + le.getMessage());
          System.exit(-1);
      } catch (SecurityException se) {
          System.err.println("Cannot create LoginContext. "
              + se.getMessage());
          System.exit(-1);
      }

      try {

          // attempt authentication
          lc.login();

      } catch (LoginException le) {

          System.err.println("Authentication failed: "
          System.err.println("  " + le.getMessage());
          System.exit(-1);

      }

      System.out.println("Authentication succeeded!");

    }
}

The Login Configuration

JAAS authentication is performed in a pluggable fashion, so applications can remain independent from underlying authentication technologies. A system administrator determines the authentication technologies, or LoginModules, to be used for each application and configures them in a login Configuration. The source of the configuration information (for example, a file or a database) is up to the current javax.security.auth.login.Configuration implementation. The default Configuration implementation from Sun Microsystems reads configuration information from configuration files, as described in com.sun.security.auth.login.ConfigFile.html.

See JAAS Login Configuration File for information as to what a login configuration file is, what it contains, and how to specify which login configuration file should be used.

The Login Configuration File for This Tutorial

As noted, the login configuration file we use for this tutorial, jaas.conf, contains just one entry, which is

JaasSample {
  com.sun.security.auth.module.Krb5LoginModule required;
};

This entry is named "JaasSample" and that is the name that our tutorial application, JaasAcn, uses to refer to this entry. The entry specifies that the LoginModule to be used to do the user authentication is the Krb5LoginModule in the com.sun.security.auth.module package and that this Krb5LoginModule is required to "succeed" in order for authentication to be considered successful. The Krb5LoginModule succeeds only if the name and password supplied by the user are successfully used to log the user into the Kerberos KDC.

For information about all the possible options that can be passed to Krb5LoginModule, see the Krb5LoginModule documentation.

Running the Code

To execute our JAAS authentication tutorial code, all you have to do is

  1. Place the JaasAcn.java application source file and the jaas.conf login configuration file into a directory.

  2. Compile JaasAcn.java:
    javac JaasAcn.java
  3. Execute the JaasAcn application, specifying

    • by -Djava.security.krb5.realm=<your_realm> that your Kerberos realm is the one specified. For example, if your realm is "KRBNT-OPERATIONS.ABC.COM" you'd put -Djava.security.krb5.realm=KRBNT-OPERATIONS.ABC.COM.

    • by -Djava.security.krb5.kdc=<your_kdc> that your Kerberos KDC is the one specified. For example, if your KDC is "samplekdc.abc.com" you'd put -Djava.security.krb5.kdc=samplekdc.abc.com.

    • by -Djava.security.auth.login.config=jaas.conf that the login configuration file to be used is jaas.conf.

The full command is below. Be sure to replace <your_realm> with your Kerberos realm, and <your_kdc> with your Kerberos KDC.

java -Djava.security.krb5.realm=<your_realm>
 -Djava.security.krb5.kdc=<your_kdc>
 -Djava.security.auth.login.config=jaas.conf JaasAcn

Type all that on one line. Multiple lines are used here for legibility.

You will be prompted for your Kerberos user name and password, and the underlying Kerberos authentication mechanism specified in the login configuration file will log you into Kerberos. If your login is successful, you will see the following message:

Authentication succeeded!
If the login is not successful (for example, if you misspell your password), you will see
Authentication failed:
followed by a reason for the failure. For example, if you mistype your user name, you may see a message like the following (where the formatting is slightly modified here to increase legibility):
Authentication failed:
  Kerberos Authentication Failed:
    javax.security.auth.login.LoginException:
      KrbException: Client not found in Kerberos database

For login troubleshooting suggestions, see Troubleshooting.

After fixing any problems, re-run the program to try again.

Running the Code with a Security Manager

When a Java program is run with a security manager installed, the program is not allowed to access resources or otherwise perform security-sensitive operations unless it is explicitly granted permission to do so by the security policy in effect. In Java platforms that are compatible with J2SE v 1.2 and later, the permission must be granted by an entry in a policy file.

Most browsers install a security manager, so applets typically run under the scrutiny of a security manager. Applications, on the other hand, do not, since a security manager is not automatically installed when an application is running. Thus an application, like our JaasAcn application, by default has full access to resources.

To run an application with a security manager, simply invoke the interpreter with a -Djava.security.manager argument included on the command line.

If you try invoking JaasAcn with a security manager but without specifying any policy file, you will get the following (unless you have a default policy setup elsewhere that grants the required permissions or grants AllPermission):

% java -Djava.security.manager \
 -Djava.security.krb5.realm=<your_realm> \
 -Djava.security.krb5.kdc=<your_kdc> \
 -Djava.security.auth.login.config=jaas.conf JaasAcn
Exception in thread "main" java.security.AccessControlException:
  access denied (
  javax.security.auth.AuthPermission createLoginContext.JaasSample)

As you can see, you get an AccessControlException, because we haven't created and used a policy file granting our code the permission that is required in order to be allowed to create a LoginContext.

Here are the complete steps required in order to be able to run our JaasAcn application with a security manager installed. You can skip the first two steps if you have already done them, as described in Running the Code.

  1. Place the JaasAcn.java application source file and the jaas.conf login configuration file into a directory.

  2. Compile JaasAcn.java:
    javac JaasAcn.java
  3. Create a JAR file containing JaasAcn.class:
    jar -cvf JaasAcn.jar JaasAcn.class

    This command creates a JAR file, JaasAcn.jar, and places the JaasAcn.class file inside it.

  4. Create a policy file granting the code in the JAR file the required permission.

    The permission that is needed by code attempting to instantiate a LoginContext is a javax.security.auth.AuthPermission with target "createLoginContext.<entry name>". Here, <entry name> refers to the name of the login configuration file entry that the application references in its instantiation of LoginContext. The name used by our JaasAcn application's LoginContext instantiation is "JaasSample", as you can see in the code:

    LoginContext lc =
    new LoginContext("JaasSample",
          new TextCallbackHandler());
    Thus, the permission that needs to be granted to JaasAcn.jar is
    permission javax.security.auth.AuthPermission
  "createLoginContext.JaasSample";
    Copy the policy file jaasacn.policy to the same directory as that in which you stored JaasAcn.java, etc. This is a text file containing the following grant statement to grant JaasAcn.jar (in the current directory) the required permission:
    grant codebase "file:./JaasAcn.jar" {
   permission javax.security.auth.AuthPermission
                    "createLoginContext.JaasSample";
};

    Note: Policy files and the structure of entries within them are described in Default Policy Implementation and Policy File Syntax. Permissions are described here.

  5. Execute the JaasAcn application, specifying

    1. by an appropriate -classpath clause that classes should be searched for in the JaasAcn.jar JAR file,

    2. by -Djava.security.manager that a security manager should be installed,

    3. by -Djava.security.krb5.realm=<your_realm> that your Kerberos realm is the one specified. For example, if your realm is "KRBNT-OPERATIONS.ABC.COM" you'd put -Djava.security.krb5.realm=KRBNT-OPERATIONS.ABC.COM.

    4. by -Djava.security.krb5.kdc=<your_kdc> that your Kerberos KDC is the one specified. For example, if your KDC is "samplekdc.abc.com" you'd put -Djava.security.krb5.kdc=samplekdc.abc.com.

    5. by -Djava.security.policy=jaasacn.policy that the policy file to be used is jaasacn.policy, and

    6. by -Djava.security.auth.login.config=jaas.conf that the login configuration file to be used is jaas.conf.

    The full command is below. Be sure to replace <your_realm> with your Kerberos realm, and <your_kdc> with your Kerberos KDC.

    java -classpath JaasAcn.jar -Djava.security.manager
 -Djava.security.krb5.realm=<your_realm>
 -Djava.security.krb5.kdc=<your_kdc>
 -Djava.security.policy=jaasacn.policy
 -Djava.security.auth.login.config=jaas.conf JaasAcn

    Type all that on one line. Multiple lines are used here for legibility. If the command is too long for your system, you may need to place it in a .bat file (for Windows) or a .sh file (for UNIX) and then run that file to execute the command.

    Since the specified policy file contains an entry granting the code the required permission, JaasAcn will be allowed to instantiate a LoginContext and continue execution. You will be prompted for your Kerberos user name and password, and the underlying Kerberos authentication mechanism specified in the login configuration file will log you into Kerberos. If your login is successful, you will see the message "Authentication succeeded!" and if not, you will see "Authentication failed:" followed by a reason for the failure.

    For login troubleshooting suggestions, see Troubleshooting.


JAAS Authorization

This tutorial expands the program and policy file developed in the JAAS Authentication tutorial to demonstrate the JAAS authorization component, which ensures the authenticated caller has the access control rights (permissions) required to do subsequent security-sensitive operations. Since the authorization component requires that the user authentication first be completed, please read the JAAS Authentication tutorial first if you have not already done so.

The rest of this tutorial consists of the following sections:

  • What is JAAS Authorization?

  • How is JAAS Authorization Performed?

    • How Do You Make Principal-Based Policy File Statements?

    • How Do You Associate a Subject with an Access Control Context?

  • The Authorization Tutorial Code

  • The Login Configuration File

  • The Policy File

  • Running the Authorization Tutorial Code

If you want to first see the tutorial code in action, you can skip directly to Running the Authorization Tutorial Code and then go back to the other sections to learn more.

What is JAAS Authorization?

JAAS authorization extends the existing Java security architecture that uses a security policy to specify what access rights are granted to executing code. That architecture, introduced in the Java 2 platform, is code-centric. That is, the permissions are granted based on code characteristics: where the code is coming from and whether it is digitally signed and if so by whom. We saw an example of this in the jaasacn.policy file used in the JAAS Authentication tutorial. That file contains the following:

grant codebase "file:./JaasAcn.jar" {
   permission javax.security.auth.AuthPermission
                    "createLoginContext.JaasSample";
};

This grants the code in the JaasAcn.jar file, located in the current directory, the specified permission. (No signer is specified, so it doesn't matter whether the code is signed or not.)

JAAS authorization augments the existing code-centric access controls with new user-centric access controls. Permissions can be granted based not just on what code is running but also on who is running it.

When an application uses JAAS authentication to authenticate the user (or other entity such as a service), a Subject is created as a result. The purpose of the Subject is to represent the authenticated user. A Subject is comprised of a set of Principals, where each Principal represents an identity for that user. For example, a Subject could have a name Principal ("Susan Smith") and a Social Security Number Principal ("987-65-4321"), thereby distinguishing this Subject from other Subjects.

Permissions can be granted in the policy to specific Principals. After the user has been authenticated, the application can associate the Subject with the current access control context. For each subsequent security-checked operation, (a local file access, for example), the Java runtime will automatically determine whether the policy grants the required permission only to a specific Principal and if so, the operation will be allowed only if the Subject associated with the access control context contains the designated Principal.

How is JAAS Authorization Performed?

To make JAAS authorization take place, the following is required:

  • The user must be authenticated, as described in the JAAS Authentication tutorial.

  • Principal-based entries must be configured in the security policy.

  • The Subject that is the result of authentication must be associated with the current access control context.

How Do You Make Principal-Based Policy File Statements?

Policy file grant statements can now optionally include one or more Principal fields. Inclusion of a Principal field indicates that the user or other entity represented by the specified Principal, executing the specified code, has the designated permissions.

Thus, the basic format of a grant statement is now

grant <signer(s) field>, <codeBase URL>
  <Principal field(s)> {
    permission perm_class_name "target_name", "action";
    ....
    permission perm_class_name "target_name", "action";
  };
where each of the signer, codeBase and Principal fields is optional and the order between the fields doesn't matter.

A Principal field looks like the following:

Principal Principal_class "principal_name"

That is, it is the word "Principal" (where case doesn't matter) followed by the (fully qualified) name of a Principal class and a principal name.

A Principal class is a class that implements the java.security.Principal interface. All Principal objects have an associated name that can be obtained by calling their getName method. The format used for the name is dependent on each Principal implementation.

The type of Principal placed in the Subject created by the Kerberos authentication mechanism used by this tutorial is javax.security.auth.kerberos.KerberosPrincipal, so that is what should be used as the Principal_class part of our grant statement's Principal designation. User names for KerberosPrincipals are of the form "name@realm". Thus, if the user name is "mjones" and the realm is "KRBNT-OPS.ABC.COM", the full principal_name designation to use in the grant statement is "mjones@KRBNT-OPS.ABC.COM".

It is possible to include more than one Principal field in a grant statement. If multiple Principal fields are specified, then the permissions in that grant statement are granted only if the Subject associated with the current access control context contains all of those Principals.

To grant the same set of permissions to different Principals, create multiple grant statements where each lists the permissions and contains a single Principal field designating one of the Principals.

The policy file for this tutorial includes one grant statement with a Principal field:

grant codebase "file:./SampleAction.jar",
    Principal javax.security.auth.kerberos.KerberosPrincipal
        "your_user_name@your_realm"  {

   permission java.util.PropertyPermission "java.home", "read";
   permission java.util.PropertyPermission "user.home", "read";
   permission java.io.FilePermission "foo.txt", "read";
};
where you substitute your Kerberos user name (complete with "@" and realm) for "your_user_name@your_realm".

This specifies that the indicated permissions are granted to the specified principal executing the code in SampleAction.jar.

How Do You Associate a Subject with an Access Control Context?

To create and associate a Subject with an access control context, you need the following:

  • The user must first be authenticated, as described in JAAS Authentication.

  • The static doAs method from the Subject class must be called, passing it an authenticated Subject and a java.security.PrivilegedAction or java.security.PrivilegedExceptionAction. (See API for Privileged Blocks for a comparison of PrivilegedAction and PrivilegedExceptionAction.) The doAs method associates the provided Subject with the current access control context and then invokes the run method from the action. The run method implementation contains all the code to be executed as the specified Subject. The action thus executes as the specified Subject.

    The static doAsPrivileged method from the Subject class may be called instead of the doAs method. In addition to the parameters passed to doAs, doAsPrivileged requires a third parameter: an AccessControlContext. Unlike doAs, which associates the provided Subject with the current access control context, doAsPrivileged associates the Subject with the provided access control context. See doAs vs. doAsPrivileged in the JAAS Reference Guide for a comparison of those methods.

The Authorization Tutorial Code

The code for this tutorial consists of two files:

  • JaasAzn.java is exactly the same as the JaasAcn.java from the JAAS Authentication tutorial except for the additional code needed to call Subject.doAsPrivileged.

  • SampleAction.java contains the SampleAction class. This class implements PrivilegedAction and has a run method that contains all the code we want to be executed with Principal-based authorization checks.

JaasAzn.java

JaasAzn.java is exactly the same as the JaasAcn.java code used in the previous tutorial except with three statements added at the end of the main method, after the authentication is done. These statements result in (1) association of a Subject representing the authenticated user with the current access control context and (2) execution of the code in the run method of SampleAction. Associating the Subject with the access control context enables security-sensitive operations in the SampleAction run method (and any code it invokes directly or indirectly) to be executed if a Principal representing the authenticated user is granted the required permissions in the current policy.

Like JaasAcn.java, JaasAzn.java instantiates a LoginContext lc and calls its login method to perform the authentication. If successful, the authenticated Subject (which includes a Principal representing the user) is obtained by calling the LoginContext's getSubject method:

Subject mySubject = lc.getSubject();

The main method then calls Subject.doAsPrivileged, passing it the authenticated Subject mySubject, a PrivilegedAction (SampleAction) and a null AccessControlContext, as described in the following.

The SampleAction class is instantiated via the following:

PrivilegedAction action = new SampleAction();

The call to Subject.doAsPrivileged is performed via:

Subject.doAsPrivileged(mySubject, action, null);

The doAsPrivileged method invokes execution of the run method in the PrivilegedAction action (SampleAction) to initiate execution of the rest of the code, which is considered to be executed on behalf of the Subject mySubject.

Passing null as the AccessControlContext (third) argument to doAsPrivileged indicates that mySubject should be associated with a new empty AccessControlContext. The result is that security checks occurring during execution of SampleAction will only require permissions for the SampleAction code itself (or other code it invokes), running as mySubject. Note that the caller of doAsPrivileged (and the callers on the execution stack at the time doAsPrivileged was called) do not require any permissions while the action executes.

SampleAction.java

SampleAction.java contains the SampleAction class. This class implements java.security.PrivilegedAction and has a run method that contains all the code we want to be executed as the Subject mySubject. For this tutorial, we will perform three operations, each of which cannot be done unless code has been granted required permissions. We will:

  • Read and print the value of the java.home system property,

  • Read and print the value of the user.home system property, and

  • Determine whether or not a file named foo.txt exists in the current directory.

Here is the code:

import java.io.File;
import java.security.PrivilegedAction;

public class SampleAction implements PrivilegedAction {

  public Object run() {

    System.out.println("\nYour java.home property value is: "
                + System.getProperty("java.home"));

    System.out.println("\nYour user.home property value is: "
                + System.getProperty("user.home"));

    File f = new File("foo.txt");
    System.out.print("\nfoo.txt does ");
    if (!f.exists())
        System.out.print("not ");
    System.out.println("exist in the current working directory.");
    return null;
  }
}

The Login Configuration File

The login configuration file used for this tutorial can be exactly the same as that used by the JAAS Authentication tutorial. Thus we can use jaas.conf, which contains just one entry:

JaasSample {
  com.sun.security.auth.module.Krb5LoginModule required;
};

This entry is named "JaasSample" and that is the name that both our tutorial applications JaasAcn and JaasAzn use to refer to it. The entry specifies that the LoginModule to be used to do the user authentication is the Krb5LoginModule in the com.sun.security.auth.module package and that this Krb5LoginModule is required to "succeed" in order for authentication to be considered successful. The Krb5LoginModule succeeds only if the name and password supplied by the user are successfully used to log the user into the Kerberos KDC.

The Policy File

This authorization tutorial contains two classes, JaasAzn and SampleAction. The code in each class contains some security-sensitive operations and thus relevant permissions are required in a policy file in order for the operations to be executed.

Permissions Required by JaasAzn

The main method of the JaasAzn class does two operations for which permissions are required. It

  • creates a LoginContext, and

  • calls the doAsPrivileged static method of the Subject class.

The LoginContext creation is exactly the same as was done in the authentication tutorial, and it thus needs the same javax.security.auth.AuthPermission permission with target "createLoginContext.JaasSample".

In order to call the doAsPrivileged method of the Subject class, you need to have a javax.security.auth.AuthPermission with target "doAsPrivileged".

Assuming the JaasAzn class is placed in a JAR file named JaasAzn.jar, these permissions can be granted to the JaasAzn code via the following grant statement in the policy file:

grant codebase "file:./JaasAzn.jar" {
   permission javax.security.auth.AuthPermission
                    "createLoginContext.JaasSample";
   permission javax.security.auth.AuthPermission "doAsPrivileged";
};

Permissions Required by SampleAction

The SampleAction code does three operations for which permissions are required. It

  • reads the value of the "java.home" system property.

  • reads the value of the "user.home" system property.

  • checks to see whether or not a file named foo.txt exists in the current directory.

The permissions required for these operations are the following:

permission java.util.PropertyPermission "java.home", "read";
permission java.util.PropertyPermission "user.home", "read";
permission java.io.FilePermission "foo.txt", "read";

We need to grant these permissions to the code in SampleAction.class, which we will place in a JAR file named SampleAction.jar. However, for this particular grant statement we want to grant the permissions not just to the code but to a specific user executing the code, to demonstrate how to restrict access to a particular user.

Thus, as explained in How Do You Make Principal-Based Policy File Statements?, our grant statement looks like the following:

grant codebase "file:./SampleAction.jar",
    Principal javax.security.auth.kerberos.KerberosPrincipal
        "your_user_name@your_realm"  {

   permission java.util.PropertyPermission "java.home", "read";
   permission java.util.PropertyPermission "user.home", "read";
   permission java.io.FilePermission "foo.txt", "read";
};
You substitute your Kerberos user name (complete with "@" and realm) for "your_user_name@your_realm". For example, if your user name is "mjones" and your realm is "KRBNT-OPERATIONS.ABC.COM", you would use "mjones@KRBNT-OPERATIONS.ABC.COM" (complete with the quotes).

The Full Policy File

The full policy file is jaasazn.policy.

Running the Authorization Tutorial Code

To execute our JAAS authorization tutorial code, all you have to do is

  1. Place the following files into a directory:

    • The JaasAzn.java source file.
    • The SampleAction.java source file.
    • The jaas.conf login configuration file.
    • The jaasazn.policy policy file.

  2. Replace "your_user_name@your_realm" in jaasazn.policy with your user name and realm.

  3. Compile SampleAction.java and JaasAzn.java:
    javac SampleAction.java JaasAzn.java
  4. Create a JAR file named JaasAzn.jar containing JaasAzn.class:
    jar -cvf JaasAzn.jar JaasAzn.class
  5. Create a JAR file named SampleAction.jar containing SampleAction.class:
    jar -cvf SampleAction.jar SampleAction.class
  6. Execute the JaasAzn application, specifying

    1. by an appropriate -classpath clause that classes should be searched for in the JaasAzn.jar and SampleAction.jar JAR files,

    2. by -Djava.security.manager that a security manager should be installed,

    3. by -Djava.security.krb5.realm=<your_realm> that your Kerberos realm is the one specified.

    4. by -Djava.security.krb5.kdc=<your_kdc> that your Kerberos KDC is the one specified.

    5. by -Djava.security.policy=jaasazn.policy that the policy file to be used is jaasazn.policy, and

    6. by -Djava.security.auth.login.config=jaas.conf that the login configuration file to be used is jaas.conf.

    Below are the full commands to use for both Microsoft Windows and Unix systems. The only difference is that on Windows systems you use semicolons to separate classpath items, while you use colons for that purpose on Unix systems. Be sure to replace <your_realm> with your Kerberos realm, and <your_kdc> with your Kerberos KDC.

    Here is the full command for Windows systems:

    java -classpath JaasAzn.jar;SampleAction.jar
 -Djava.security.manager
 -Djava.security.krb5.realm=<your_realm>
 -Djava.security.krb5.kdc=<your_kdc>
 -Djava.security.policy=jaasazn.policy
 -Djava.security.auth.login.config=jaas.conf JaasAzn

    Here is the full command for UNIX systems:

    java -classpath JaasAzn.jar:SampleAction.jar
 -Djava.security.manager
 -Djava.security.krb5.realm=<your_realm>
 -Djava.security.krb5.kdc=<your_kdc>
 -Djava.security.policy=jaasazn.policy
 -Djava.security.auth.login.config=jaas.conf JaasAzn

    Type the full command on one line. Multiple lines are used here for legibility. If the command is too long for your system, you may need to place it in a .bat file (for Windows) or a .sh file (for UNIX) and then run that file to execute the command.

    You will be prompted for your Kerberos user name and password, and the underlying Kerberos authentication mechanism specified in the login configuration file will log you into Kerberos. If your login is successful, you will see the message "Authentication succeeded!" and if not, you will see "Authentication Failed."

    For login troubleshooting suggestions, see Troubleshooting.

    Once authentication is successfully completed, the rest of the program (in SampleAction) will be executed on behalf of you, the user, requiring you to have been granted appropriate permissions. The jaasazn.policy policy file grants you the required permissions, so you will see a display of the values of your java.home and user.home system properties and a statement as to whether or not you have a file named foo.txt in the current directory.


JAAS Login Configuration File

JAAS authentication is performed in a pluggable fashion, so Java applications can remain independent from underlying authentication technologies. Configuration information such as the desired authentication technology is specified at runtime. The source of the configuration information (for example, a file or a database) is up to the current javax.security.auth.login.Configuration implementation. The default Configuration implementation from Sun Microsystems reads configuration information from configuration files, which are described in this document.

Login Configuration File Structure and Contents

A login configuration file consists of one or more entries, each specifying which underlying authentication technology should be used for a particular application or applications. The structure of each entry is the following:

<entry name> {
    <LoginModule> <flag> <LoginModule options>;
    <LoginModule> <flag> <LoginModule options>;
    . . .
    };

Thus, each login configuration file entry consists of a name followed by one or more LoginModule-specific items. Each LoginModule-specific item specifies a LoginModule, a flag value, and options to be passed to the LoginModule. (These are described futher below.) Each LoginModule-specific item is terminated by a semicolon and the entire group of items is enclosed in braces. Each configuration file entry is terminated by a semicolon.

As an example, the login configuration file used for the JAAS Authentication tutorial contains just one entry, which is

JaasSample {
  com.sun.security.auth.module.Krb5LoginModule required;
};

Here, the entry is named "JaasSample" and that is the name that the JAAS Authentication tutorial application (JaasAcn.java) uses to refer to this entry. The entry specifies that the LoginModule to be used to do the user authentication is the Krb5LoginModule in the com.sun.security.auth.module package and that this Krb5LoginModule is required to "succeed" in order for authentication to be considered successful. The Krb5LoginModule succeeds only if the name and password supplied by the user are successfully used to log the user into the Kerberos KDC.

The name for an entry in a login configuration file is the name that applications use to refer to the entry when they instantiate a LoginContext, as described in Instantiating a LoginContext in the JAAS authentication tutorial. The name can be whatever name the application developer wishes to use. Here, the term "application" refers to whatever code does the JAAS login, whether it is your application (as shown in the JAAS Authentication and JAAS Authorization tutorials) or a Login utility that does the JAAS operations for you (as shown in the Use of JAAS Login Utility and Use of Java GSS-API for Secure Message Exchanges Using JAAS Login Utility tutorials.)

The subparts of each LoginModule-specific item are described by the following. See the Configuration documentation for more information.

  • LoginModule

    This specifies the fully qualified class name for a class that implements a particular authentication technology. Specifically, the class must implement the javax.security.auth.spi.LoginModule interface. A typical LoginModule may prompt for and verify a user name and password. Any vendor can provide a LoginModule implementation that you can use. Some implementations are supplied with the JRE from Sun Microsystems. Throughout these tutorials we use the Krb5LoginModule in the com.sun.security.auth.module package. The Krb5LoginModule uses Kerberos as the underlying authentication technology. You can view the reference documentation for the various LoginModules, all in the com.sun.security.auth package:

    • JndiLoginModule
    • KeyStoreLoginModule
    • Krb5LoginModule
    • NTLoginModule
    • UnixLoginModule

  • flag

    The flag value indicates whether success of the LoginModule is "required", "requisite", "sufficient", or "optional".

  • LoginModule options

    If the specified LoginModule implementation has options that can be set, you specify any desired option values here. This is a space-separated list of values which are passed directly to the underlying LoginModule. Options are defined by the LoginModule itself, and control the behavior within it. For example, a LoginModule may define options to support debugging/testing capabilities. See the Krb5LoginModule documentation for information about the options defined for the Krb5LoginModule used for all the tutorials in this series.

    The correct way to specify options in the configuration file is by using a name-value pairing, for example debug=true, where the option name (in this case, "debug") and value (in this case, "true") should be separated by an "equals" symbol.

Where to Specify Which Login Configuration File Should Be Used

The configuration file to be used can be specified in one of two ways:

  1. On the command line.

    You can use a -Djava.security.auth.login.config command line argument to specify the login configuration file that should be used. We use this approach for all the tutorials. For example, we run our JaasAcn application in the JAAS Authentication tutorial using the following command, which specifies that the configuration file is the jaas.conf file in the current directory:

    java -Djava.security.auth.login.config=jaas.conf JaasAcn
  2. In the Java security properties file.

    An alternate approach to specifying the location of the login configuration file is to indicate its URL as the value of a login.config.url.n property in the security properties file. The security properties file is the java.security file located in the lib/security directory of the JRE.

    Here, n indicates a consecutively-numbered integer starting with 1. Thus, if desired, you can specify more than one login configuration file by indicating one file's URL for the login.config.url.1 property, a second file's URL for the login.config.url.2 property, and so on. If more than one login configuration file is specified (that is, if n > 1), then the files are read and concatenated into a single configuration.

    Here is an example of what would need to be added to the security properties file in order to indicate the jaas.conf login configuration file used by this tutorial. This example assumes the file is in the C:\AcnTest directory on a Microsoft Windows system:

    login.config.url.1=file:C:/AcnTest/jaas.conf
    (Note that URLs always use forward slashes, regardless of what operating system the user is running.)


Kerberos Requirements

Kerberos Version 5 is used for both the authentication and secure communication aspects of the client and server applications developed in this tutorial. The reader is assumed to already be familiar with Kerberos. See the Kerberos reference documentation.

The JAAS framework, and the Kerberos mechanism required by the Java GSS-API methods, are built into the version 1.4 and later JREs from all vendors. (JAAS was available as a separately-downloadable optional package starting in version 1.3.) The Kerberos LoginModule required for the JAAS authentication in this tutorial may not be available in all vendors' JREs. We will be using the LoginModule for Kerberos provided in the JRE from Sun Microsystems (versions 1.4 and later).

In order to run the sample programs, you will need access to a Kerberos installation. As described in the following sections, you may also need a krb5.conf Kerberos configuration file and an indication as to where that file is located.

As with all Kerberos installations, a Kerberos Key Distribution Center (KDC) is required. It needs to contain the user name and password you will use to be authenticated to Kerberos. Note: A KDC implementation is part of a Kerberos installation and not a part of the JRE v 1.4 and later.

As with most Kerberos installations, a Kerberos configuration file krb5.conf is consulted to determine such things as the default realm and KDC. If you are using a Kerberos implementation such as that from Microsoft for Windows 2000, which does not include a krb5.conf file, you will either need to create one or use system properties as described in Setting Properties to Indicate the Default Realm and KDC.

Setting Properties to Indicate the Default Realm and KDC

Typically, the default realm and the KDC for that realm are indicated in the Kerberos krb5.conf configuration file. However, if you like, you can instead specify these values by setting the following system properties to indicate the realm and KDC, respectively:

java.security.krb5.realm
java.security.krb5.kdc

If you set one of these properties you must set them both.

Also note that if you set these properties, then no cross-realm authentication is possible unless a krb5.conf file is also provided from which the additional information required for cross-realm authentication may be obtained.

If you set values for these properties, then they override the default realm and KDC values specified in krb5.conf (if such a file is found). The krb5.conf file is still consulted if values for items other than the default realm and KDC are needed. If no krb5.conf file is found, then the default values used for these items are implementation-specific.

Locating the krb5.conf Configuration File

The essential Kerberos configuration information is the default realm and the default KDC. As shown in Setting Properties to Indicate the Default Realm and KDC, if you set properties to indicate these values, they are not obtained from a krb5.conf configuration file.

If these properties do not have values set, or if other Kerberos configuration information is needed, an attempt is made to find the required information in a krb5.conf file. The algorithm to locate the krb5.conf file is the following:

  • If the system property java.security.krb5.conf is set, its value is assumed to specify the path and file name.

  • If that system property value is not set, then the configuration file is looked for in the directory
    <java-home>\lib\security      [Windows]
    <java-home>/lib/security      [Solaris and Linux]
    Here <java-home> refers to the directory where the JRE was installed. For example, if you have J2SE 5.0 installed on Solaris in a directory named /j2sdk1.5, the directory in which the configuration file is looked for is:
    /j2sdk1.5/jre/lib/security
  • If the file is still not found, then an attempt is made to locate it as follows:
    /etc/krb5/krb5.conf                [Solaris]
    c:\winnt\krb5.ini                  [Windows]
    /etc/krb5.conf                     [Linux]
  • If the file is still not found, and the configuration information being searched for is not the default realm and KDC, then implementation-specific defaults are used. If, on the other hand, the configuration information being searched for is the default realm and KDC because they weren't specified in system properties, and the krb5.conf file is not found either, then an exception is thrown.

Naming Conventions for Realm Names and Hostnames

By convention, all Kerberos realm names are uppercase and all DNS hostname and domain names are lowercase. On the Windows 2000 platform, domains are also Kerberos realms; however, the realm name is always the uppercase version of the domain name.

Hostnames are case insensitive and by convention they are all lowercase. They must resolve to the same hostname on the client and server by their respective naming services.

However, in the Kerberos database hostnames are case sensitive. In all host-based Kerberos service principals in the KDC, hostnames are case-sensitive. The hostnames used in the Kerberos service principal names must exactly match the hostnames returned by the naming service. For example, if the naming service returns a fully qualified lowercased DNS hostname, such as "raven.sun.com", then the administrator must use the same fully qualified lowercased DNS hostname when creating host-based principal names in the KDC: "host/raven.sun.com".

Cross-Realm Authentication

In cross-realm authentication, a principal in one realm can authenticate to principals in another realm.

In Kerberos, cross-realm authentication is implemented by sharing an encryption key between two realms. The KDCs in two different realms share a special cross-realm secret; this secret is used to prove identity when crossing the boundary between realms.

The key that is shared is the Ticket Granting Service principal's key. Here's a typical Ticket Granting Service principal for a single realm:

ktbtgt/ACME.COM@ACME.COM
In cross realm authentication, two principals are created on each participating realm. For two realms, ENG.EAST.ACME.COM and SALES.WEST.ACME.COM, these principals would be:
krbtgt/ENG.EAST.ACME.COM@SALES.WEST.ACME.COM
krbtgt/SALES.WEST.ACME.COM@ENG.EAST.ACME.COM
These principals, known as remote Ticket Granting Server principals, must be created on both realms.

On Windows 2000 KDC, the krbtgt account is created automatically when a Windows 2000 domain is created. This account cannot be deleted and renamed.

Types of Realms

When you set up multiple realms, you must decide if your realm configuration will be "hierarchical" (one realm is a superset of the other) or "direct" (the mapping between realms must be defined).

How to Set Up Cross-Realm Authentication

In transitive cross-realm authentication you can define a path of realms connected via cross-realm secrets and use this path to traverse realms until you get credentials in the desired realm.

The [capaths] section in the Kerberos configuration file defines a series of authentication paths used for transitive cross-realm authentication. Clients use [capaths] to determine the correct path for doing transitive cross-realm authentication. Application servers check the [capaths] section to determine if a cross-realm authentication path is valid.

For example, to set-up cross realm authentication between ENG.EAST.ACME.COM and SALES.WEST.ACME.COM, krb5.conf should include the following entry:

[capaths]
    ENG.EAST.ACME.COM = {
        SALES.WEST.ACME.COM = .
    }

    SALES.WEST.ACME.COM = {
         ENG.EAST.ACME.COM = .
    }
On Windows 2000, you must set up a trust relationship between the two realms. For configuration details, refer to Step-by-Step Guide to Kerberos 5 (krb5 1.0) Interoperability on Microsoft's Web site.


More Things You Can Do With Java GSS-API and JAAS

The previous tutorial, Use of JAAS Login Utility and Java GSS-API for Secure Message Exchanges, demonstrated how two applications, in particular a client and a server, could use the Java GSS-API to establish a secure context between them and then securely exchange messages.

There are additional operations the context acceptor (the server in our client/server example) can perform once the context has been established with the context initiator (the client). Basically, the server can "impersonate" the client. The level of impersonation depends upon whether or not the client has delegated credentials to the server.

  • Executing Code on Behalf of the Client User

  • Using Credentials Delegated From the Client

Executing Code on Behalf of the Client User

One possible type of client impersonation the server can do is causing code to be executed on behalf of the same entity (user) the client code is executed on behalf of. Normally, a method executed by a thread uses the access control settings for that thread itself. However, when impersonating a client in this tutorial, the server uses the client's access control settings so that the server has access to exactly those resources that the client itself has when it runs.

One major benefit of the approach used in this tutorial is that the JAAS authorization component can be used for access control. Without the JAAS authorization component, the server principal would need access to any resources accessed by the code executed on behalf of the client user, and the server code would need to include access control logic to determine whether the user was authorized to access such resources. By utilizing JAAS authorization, providing principal-based access control, the access control is handled automatically. Permissions for the security-sensitive operations in such code only need to be granted to that user and not also to the server code. See the JAAS Authorization tutorial for more information on JAAS authorization.

  • Basic Approach

  • Sample Code and Policy File

  • Running the Sample Code

Basic Approach

How does the server "impersonate" the client to execute code on behalf of the user running the client code? Essentially the same way the client code is set up to be run on behalf of that user. All the server code needs to know is the user's principal name, which it can obtain from the context established with the client.

Recall that JAAS authentication of the user executing the client code results in creation of a Subject containing a Principal with the user (principal) name. The Subject is subsequently associated with a new access control context (via a Subject.doAsPrivileged call from the Login utility) and the client code is considered to be executed on behalf of the user; subsequent access control decisions are based on whether or not that particular user, executing the client code, is granted the required permissions.

The server code is similarly handled, except in that case the Principal specified for authentication is typically a "service principal", not a user principal. Again, a Subject containing a Principal with the specified principal name is created, Subject.doAsPrivileged is called, and the server code is considered to be executed on behalf of the specified principal; subsequent access control decisions are based on whether or not that particular principal, executing the server code, is granted the required permissions.

Once the client and server have established a mutual context, the context initiator's name (the client's principal name) can be determined by the following:

GSSName clientGSSName = context.getSrcName();

The context acceptor (the server) can use this name to construct a Subject containing a Principal that represents the same entity. For example, if you are using a JRE from Sun Microsystems, you can construct such a Subject via the following:

Subject client =
  com.sun.security.jgss.GSSUtil.createSubject(clientGSSName, null);

The createSubject method creates a new Subject from the GSSName and GSSCredential specified as arguments. If the server code is just going to execute code on behalf of the user in the local JVM, the user's credentials are not required - and in fact cannot even be obtained unless the client has delegated credentials to the server, as discussed in Using Credentials Delegated From the Client. Since the credentials are not needed here, we pass a null for the GSSCredential argument.

Note: If you are not using a JRE from Sun Microsystems, an alternative way to do this is to construct a KerberosPrincipal instance as follows:
KerberosPrincipal principal =
  new KerberosPrincipal(clientGSSName.toString());

Then use this principal to construct a new Subject or populate this principal in the principal set of an existing Subject.

The code that the server would like to execute on behalf of the user should be initiated from the run method of a class that implements java.security.PrivilegedAction (or java.security.PrivilegedExceptionAction). That is, the code can either be in such a run method or invoked from such a run method.

The server code can pass the Subject, along with an instance of the PrivilegedAction (or PrivilegedExceptionAction), to Subject.doAsPrivileged to execute the subsequent code, starting with the run method in the PrivilegedAction, on behalf of the principal (user) in the specified Subject.

For example, suppose the PrivilegedAction class is called ReadFileAction and it takes as an argument a String with the principal name. You can create an instance of this class by

String clientName = clientGSSName.toString();
PrivilegedAction readFile =
    new ReadFileAction(clientName);

The call to doAsPrivileged is then

Subject.doAsPrivileged(client, readFile, null);

Sample Code and Policy File

The following sample code and policy file illustrate the server impersonating the client in order to execute code whose security-sensitive operations are only permitted to be done by the specific user executing the client.

  • SampleServerImp.java

  • ReadFileAction.java

  • serverimp.policy

SampleServerImp.java

The SampleServerImp.java file is exactly the same as the SampleServer.java file from the previous (Use of JAAS Login Utility and Java GSS-API for Secure Message Exchanges) tutorial, except that after exchanging messages with the client, it has the following code to perform a ReadFileAction as the client user:

System.out.println("Impersonating client.");

/*
 * Extract the KerberosPrincipal from the client GSSName and
 * populate it in the principal set of a new Subject. Pass in a
 * null for credentials since credentials will not be needed.
 */
GSSName clientGSSName = context.getSrcName();
System.out.println("clientGSSName: " + clientGSSName);
Subject client =
   com.sun.security.jgss.GSSUtil.createSubject(clientGSSName,
        null);

/*
* Construct an action that will read a file meant only for the
* client
*/
String clientName = clientGSSName.toString();
PrivilegedAction readFile =
   new ReadFileAction(clientName);

/*
* Invoke the action via a doAsPrivileged. This allows the
* action to be executed as the client subject, and it also
* runs that code as privileged. This means that any permission
* checking that happens beyond this point applies only to
* the code being run as the client.
*/
Subject.doAsPrivileged(client, readFile, null);

ReadFileAction.java

The ReadFileAction.java file contains the ReadFileAction class. Its constructor takes as an argument a String for the name of the client user. The client username is used to construct a file name for a file from which ReadFileAction will attempt to read. The file name will be:

./data/<name>_info.txt
where <name> is the client username without its corresponding realm. For example, if the full username is mjones@KRBNT-OPERATIONS.ABC.COM, then the file name is
./data/mjones_info.txt
Note: On Microsoft Windows systems the forward slashes will be backward slashes.

The ReadFileAction run method reads the specified file and prints its contents.

serverimp.policy

ReadFileAction attempts to read a file, which is a security-checked operation. Since ReadFileAction is considered to be executed as the client user (Principal), the appropriate permission must be granted not only to the ReadFileAction code itself, but to the client Principal as well.

Assuming the ReadFileAction class is placed in a JAR file named ReadFileAction.jar, and the user principal name is mjones@KRBNT-OPERATIONS.ABC.COM, this permission can be granted via the following in a policy file:

grant CodeBase "file:./ReadFileAction.jar"
    Principal javax.security.auth.kerberos.KerberosPrincipal
        "mjones@KRBNT-OPERATIONS.ABC.COM" {

    permission java.io.FilePermission "data/mjones_info.txt",
        "read";
};
The serverimp.policy file is exactly the same as the server.policy file from the previous (Use of JAAS Login Utility and Java GSS-API for Secure Message Exchanges) tutorial, except that it grants the SampleServer code the javax.security.auth.AuthPermission "doAsPrivileged" permission it needs in order to call the doAsPrivileged method, and it has the following placeholder for granting the FilePermission shown above:
grant CodeBase "file:./ReadFileAction.jar"
    Principal javax.security.auth.kerberos.KerberosPrincipal
        "your_user_name@your_realm" {

    permission java.io.FilePermission "data/your_user_name_info.txt",
        "read";
};

You must substitute your Kerberos realm for your_realm, and your user name for your_user_name in both your_user_name@your_realm and data/your_user_name_info.txt. If you are working on a Microsoft Windows sytem, you also replace the "/" in data/your_user_name_info.txt with a "\".

Running the Sample Code

To run the sample code illustrating the server impersonating the client, do everything listed in Running the SampleClient and SampleServer Programs in the previous tutorial, except for the following:

  • In the "Prepare SampleServer for Execution" step:

    • Use SampleServerImp.java instead of SampleServer.java. Compile it and create a JAR file named SampleServerImp.jar containing SampleServerImp.class via the following:
      javac SampleServerImp.java
jar -cvf SampleServerImp.jar SampleServerImp.class

    • Use the serverimp.policy policy file instead of server.policy.

    • Use the csImpLogin.conf login configuration file instead of cs.conf.

    • Copy ReadFileAction.java to the same directory as the other files. Compile it and place it in a JAR file via the following:
      javac ReadFileAction.java
jar -cvf ReadFileAction.jar ReadFileAction.class
    • In csImpLogin.conf, replace "service_principal@your_realm" with the Kerberos name of the service principal that represents SampleServer.

    • In serverimp.policy, replace "service_principal@your_realm" in both places it appears with the Kerberos name of the service principal that represents SampleServer. (The same name as that used in the login configuration file.) In addition, substitute your Kerberos realm for your_realm, and your user name for your_user_name in both your_user_name@your_realm and data/your_user_name_info.txt. If you are running on a Microsoft Windows system, then replace the "/" in data/your_user_name_info.txt with a "\".

    • Create a data subdirectory of your current directory and create a short text file of the specified name in that directory. For example, if your user name is mjones, the file to be placed in the data subdirectory should be named mjones_info.txt.

  • In the "Execute SampleServer" step:

    • Use the following commands instead of those specified in that section so that SampleServerImp is executed, serverimp.policy and csImpLogin.conf are used, and ReadFileAction.jar is included.

      Important: In these commands, you must replace <port_number> with an appropriate port number (a high port number such as 4444), <your_realm> with your Kerberos realm, and <your_kdc> with your Kerberos KDC.

      Here is the command for Microsoft Windows systems:

        java -classpath Login.jar;SampleServerImp.jar;ReadFileAction.jar
    -Djava.security.manager
    -Djava.security.krb5.realm=<your_realm>
    -Djava.security.krb5.kdc=<your_kdc>
    -Djava.security.policy=serverimp.policy
    -Djava.security.auth.login.config=csImpLogin.conf
    Login SampleServerImp <port_number>

      Here is the command for UNIX systems:

        java -classpath Login.jar:SampleServerImp.jar:ReadFileAction.jar
    -Djava.security.manager
    -Djava.security.krb5.realm=<your_realm>
    -Djava.security.krb5.kdc=<your_kdc>
    -Djava.security.policy=serverimp.policy
    -Djava.security.auth.login.config=csImpLogin.conf
    Login SampleServerImp <port_number>

      As usual, type the full command on one line. Multiple lines are used here for legibility. If the command is too long for your system, you may need to place it in a .bat file (for Microsoft Windows) or a .sh file (for UNIX) and then run that file to execute the command.

      As when running SampleServer, you will be prompted for the Kerberos password for the service principal under which SampleServerImp is expected to be run. The Kerberos login module specified in the login configuration file will log the service principal into Kerberos. Once authentication is successfully completed, the SampleServerImp code will be executed on behalf of the service principal. It will listen for socket connections on the specified port.

      After you follow the "Prepare SampleClient for Execution" and "Execute SampleClient" instructions as usual and perform the user login, the client code will request a socket connection with SampleServerImp. Once SampleServerImp accepts the connection, SampleClient and SampleServerImp establish a shared context and then exchange messages as described in the previous tutorial.

      After the message exchange, SampleServerImp determines the principal name of the user executing the client code, creates a new Subject containing a Principal with that name, and calls Subject.doAsPrivileged to execute the code in ReadFileAction on behalf of the specified user. ReadFileAction reads the file named your_user_name_info.txt (where your_user_name represents the actual user name) in the data subdirectory of the current directory, and prints out its contents.

      For login troubleshooting suggestions, see Troubleshooting.

Using Credentials Delegated From the Client

The most complete type of client impersonation is possible if the client delegates its credentials to the server.

Recall that prior to context establishment with the context acceptor (the server in our previous tutorial), the context initiator (the client) sets various context options. If the initiator calls the requestCredDeleg method on the context object with a true argument, as in

context.requestCredDeleg(true);
then this requests that the initiator's credentials be delegated to the acceptor during context establishment.

Delegation of credentials from the initiator to the acceptor enables the acceptor to authenticate itself as an agent or delegate of the initiator.

First, after context establishment, the acceptor must determine whether or not credential delegation actually took place. It does so by calling the getCredDelegState method:

boolean delegated = context.getCredDelegState();

If credentials were delegated, the acceptor can obtain those credentials by calling the getDelegCr method:

GSSCredential clientCr = context.getDelegCr();

The resulting GSSCredential object can then be used to initiate subsequent GSS-API contexts as a "delegate" of the initiator. For example, the server could authenticate as the client to a backend server that cares more about who the original client was than who the intermediate server is.

Acting as the client, the server can establish a connection with the backend server, establish a joint security context, and exchange messages in basically the same manner that the client and server did.

One way it could be done is that when the server calls the createContext method of a GSSManager, it could pass createContext the delegated credentials instead of passing a null.

Alternatively, the server code could first call the com.sun.security.jgss.GSSUtil createSubject method and pass it the delegated credentials. That method returns a Subject containing those credentials as the default credentials. The server could then associate this Subject with the current AccessControlContext, as described in How Do You Associate a Subject with an Access Control Context? in the JAAS Authorization tutorial. Then, when the server code calls the GSSManager createContext method, it can pass a null (indicating the credentials for the "current" Subject should be used). In other words, the server would effectively become the client. Subsequent connections to backend servers using GSS could be made exactly as described in the previous tutorials. This approach is useful if you want the code that will use the delegated credentials to be identical to the code that uses the default local credentials.

Permission Required In Order to Delegate Credentials

In order to delegate credentials, the context initiator (SampleClient in our previous tutorial) must have a javax.security.auth.kerberos.DelegationPermission. An example using placeholders in italics for actual values is the following:

permission javax.security.auth.kerberos.DelegationPermission
  "\"service_principal@your_realm\"
     \"krbtgt/your_realm@your_realm\"";

Note that DelegationPermission has a single target in quotes that contains two items, both of which are quoted. Each inner quote is escaped by a "\". Thus the first item is

"service_principal@your_realm"
and the second is
"krbtgt/your_realm@your_realm"

This basically gives the code executing on behalf of the client the permission to forward a Kerberos ticket to the specified peer (service_principal), where the Kerberos ticket is meant to avail service from krbtgt/your_realm@your_realm.

Substitute your realm for all places your_realm appears. Also substitute the service principal name for the service principal representing the server for service_principal@your_realm. (See Kerberos User and Service Principal Names in the previous tutorial.) Suppose your realm is KRBNT-OPERATIONS.ABC.COM and the service principal is "sample/raven.abc.com@KRBNT-OPERATIONS.ABC.COM". Then the permission could appear in a policy file as

permission javax.security.auth.kerberos.DelegationPermission
  "\"sample/raven.abc.com@KRBNT-OPERATIONS.ABC.COM\"
     \"krbtgt/KRBNT-OPERATIONS.ABC.COM@KRBNT-OPERATIONS.ABC.COM\"";


Subjects, Principals, Authentication, and Credentials

To authorize access to resources, applications first need to authenticate the source of the request. The JAAS framework defines the term subject to represent the source of a request. A subject may be any entity, such as a person or service. A subject is represented by the javax.security.auth.Subject class.

Authentication represents the process by which the identity of a subject is verified, and must be performed in a secure fashion; otherwise a perpetrator may impersonate others to gain access to a system. Authentication typically involves the subject demonstrating some form of evidence to prove its identity. Such evidence may be information only the subject would likely know or have (such as a password or fingerprint), or it may be information only the subject could produce (such as signed data using a private key).

Once authenticated, a Subject is populated with associated identities, or Principals (of type java.security.Principal). A Subject may have many Principals. For example, a person may have a name Principal ("John Doe") and an SSN Principal ("123-45-6789"), which distinguish it from other Subjects.

In addition to associated Principals, a Subject may own security-related attributes, which are referred to as credentials. A credential may contain information used to authenticate the subject to new services. Such credentials include passwords, Kerberos tickets, and public key certificates. Credentials might also contain data that enables the subject to perform certain activities. Cryptographic keys, for example, represent credentials that enable the subject to sign or encrypt data. Public and private credential classes are not part of the core J2SE API. Any class, therefore, can represent a credential.


Troubleshooting

Below are listed some problems that may occur when attempting a login, and suggestions for solving them.

  • Configurable Kerberos Settings:

    The Kerberos Key Distribution Center (KDC) name and realm settings are provided in the Kerberos configuration file or via the system properties java.security.krb5.kdx and java.security.krb5.realm. In previous releases, changes to the Kerberos configuration values would only take effect when an application was restarted.

    Starting from the JDK 1.4.2 release, a new boolean option refreshKrb5Config can be specified in the entry for Krb5LoginModule in the JAAS configuration file. If this option is set to true, the configuration values will be refreshed before the login method of the Krb5LoginModule is called.

    NOTE: When switching Kerberos configurations, it is REQUIRED that refreshKrb5Config should be set to true. Failure to set this value can lead to unexpected results.

  • java.lang.SecurityException at javax.security.auth.login.Configuration.getConfiguration

    Cause: There was a problem processing the JAAS login configuration file, possibly due to a syntax error in the file.

    Solution: Check the configuration file carefully for errors. See JAAS Login Configuration File for information about the syntax required in the login configuration file.

  • javax.security.auth.login.LoginException: KrbException: Pre-authentication information was invalid (24) - Preauthentication failed

    Cause 1: The password entered is incorrect.

    Solution 1: Verify the password.

    Cause 2: If you are using the keytab to get the key (e.g., by setting the useKeyTab option to true in the Krb5LoginModule entry in the JAAS login configuration file), then the key might have changed since you updated the keytab.

    Solution 2: Consult your Kerberos documentation to generate a new keytab and use that keytab.

    Cause 3: Clock skew - If the time on the KDC and on the client differ significanlty (typically 5 minutes), this error can be returned.

    Solution 3: Synchronize the clocks (or have a system administrator do so).

    Cause 4: The Kerberos realm name is not all uppercase.

    Solution 4: Make the Kerberos realm name all uppercase. Note: It is recommended to have all uppercase realm names. For details, refer to the Naming Conventions for the Realm Names and Hostnames section of this tutorial.

  • GSSException: No valid credentials provided (Mechanism level: Attempt to obtain new INITIATE credentials failed! (null)) . . . Caused by: javax.security.auth.login.LoginException: Clock skew too great

    Cause: Kerberos requires the time on the KDC and on the client to be loosely synchronized. (The default is within 5 minutes.) If that's not the case, you will get this error.

    Solution: Synchronize the clocks (or have a system administrator do so).

  • javax.security.auth.login.LoginException: KrbException: Null realm name (601) - default realm not specified

    Cause: The default realm is not specified in the Kerberos configuration file krb5.conf (if used), provided as a part of the user name, or specified via the java.security.krb5.realm system property.

    Solution: Verify that your Kerberos configuration file (if used) contains an entry specifying the default realm, or directly specify it by setting the value of the java.security.krb5.realm system property and/or including it in your user name when authenticating using Kerberos.

  • javax.security.auth.login.LoginException: java.net.SocketTimeoutException: Receive timed out

    Solution: Verify that the Kerberos KDC is up and running.

  • GSSException: No valid credentials provided (Mechanism level: Failed to find any Kerberos Ticket)

    Cause: This may occur if no valid Kerberos credentials are obtained. In particular, this occurs if you want the underlying mechanism to obtain credentials but you forgot to indicate this by setting the javax.security.auth.useSubjectCredsOnly system property value to false (for example via -Djavax.security.auth.useSubjectCredsOnly=false in your execution command).

    Solution: Be sure to set the javax.security.auth.useSubjectCredsOnly system property value to false if you want the underlying mechanism to obtain credentials, rather than your application or a wrapper program (such as the Login utility used by some of the tutorials) performing authentication using JAAS.

  • javax.security.auth.login.LoginException: Could not load configuration file <krb5.conf> (No such file or directory)

    Cause: The tutorials' sample execution commands specify the default Kerberos realm and KDC by setting values for the java.security.krb5.realm and java.security.krb5.kdc system properties. If you like, you can instead have a krb5.conf Kerberos configuration file used. Such a file includes information about what the default realm and KDC are. To use a krb5.conf file, you either set the system property java.security.krb5.conf (instead of the realm and kdc properties) to specify the location of the file or you don't set any of these properties and therefore an attempt is made to locate the krb5.conf file in a default location. You will get the error "Could not load configuration file <krb5.conf> (No such file or directory)" if the file could not be found.

    Solution: Verify that the Kerberos configuration file krb5.conf is available and readable. Check Kerberos Requirements for information about how to specify the location of the krb5.conf file and where such a file is searched for by default if you don't explicitly indicate the location.

  • javax.security.auth.login.LoginException: KrbException: KDC has no support for encryption type (14) - KDC has no support for encryption type

    Cause 1: Your KDC does not support the encryption type requested.

    Solution 1: Sun's implementation of Kerberos supports the following encryption types: des-cbc-md5, des-cbc-crc and des3-cbc-sha1.

    Applications can select the desired encryption type by specifying following tags in the Kerberos Configuration file krb5.conf:

    [libdefaults]
default_tkt_enctypes = des-cbc-md5 des-cbc-crc des3-cbc-sha1
default_tgs_enctypes = des-cbc-md5 des-cbc-crc des3-cbc-sha1
permitted_enctypes = des-cbc-md5 des-cbc-crc des3-cbc-sha1
    If not specified, the default value is:
    des-cbc-md5 des-cbc-crc des3-cbc-sha1

    Cause 2: This exception is thrown when using native ticket cache on some Windows platforms. Microsoft has added a new feature in which they no longer export the session keys for Ticket-Granting Tickets (TGTs). As a result, the native TGT obtained on Windows has an "empty" session key and null EType. The effected platforms include: Windows Server 2003, Windows 2000 Server Service Pack 4 (SP4) and Windows XP SP2.

    Solution 2: You need to update the Windows registry to disable this new feature. The registry key allowtgtsessionkey should be added--and set correctly--to allow session keys to be sent in the Kerberos Ticket-Granting Ticket.

    On the Windows Server 2003 and Windows 2000 SP4, here is the required registry setting:

    HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\Parameters
Value Name: allowtgtsessionkey
Value Type: REG_DWORD
Value: 0x01  ( default is 0 )
    By default, the value is 0; setting it to "0x01" allows a session key to be included in the TGT.

    Here is the location of the registry setting on Windows XP SP2:

    HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos\
Value Name: allowtgtsessionkey
Value Type: REG_DWORD
Value: 0x01
  • KDC reply did not match expectations

    Cause: The KDC sent a response that cannot be understood by the client.

    Solution: Verify that you have set correctly all the krb5.conf file configuration parameters and consult your KDC vendor's guide.

    • Note: A debugging mode can be enabled by setting the system property sun.security.krb5.debug to "true". This setting allows you to follow the program's execution of the Kerberos V5 protocol. If you send us feedback regarding a problem you are having, please include the complete debugging output.


Use of JAAS Login Utility

The previous two tutorials, JAAS Authentication and JAAS Authorization, show how you can use the LoginContext and Subject classes to write a program to

  • authenticate the user to verify his or her identity and

  • associate an instance of a particular class representing the user (a Subject instance) with an access control context in such a way that subsequent security-sensitive operations will be allowed if the current policy grants the user the required permissions.

This tutorial describes a Login utility that performs the above operations and then executes any specified application as the authenticated user.

Use of the Login utility with a sample application is demonstrated in this tutorial. The next tutorial, a client/server application using the Java GSS-API, also uses the Login utility.

It is not necessary to read the previous two tutorials on JAAS authentication and authorization prior to reading this one. However, you may want to refer to some sections in those tutorials to obtain further details regarding certain topics, such as how to make user-based policy file statements. You should also read JAAS Login Configuration File for information as to what a login configuration file is, since one is needed for this and all other tutorials in this series.

As with all tutorials in this series of tutorials, the underlying technology used to support authentication is Kerberos. See Kerberos Requirements.

  • What You Need to Know About the Login Utility

  • Application and Other File Requirements

  • The Sample Application Program

  • The Login Configuration File

  • The Policy File

  • Running the Sample Program with the Login Utility

If you want to first see the tutorial code in action, you can skip directly to Running the Sample Program with the Login Utility and then go back to the other sections to learn more.

What You Need to Know About the Login Utility

You do not need to understand the code contained in Login.java; you can just use it as is. However, you need to understand some facts about what it does so that your program, policy file, and login configuration file will properly work with it. Below is a summary of these facts, followed by sections with further information and examples.

The Login class does the following:

  • Assumes it is passed, as arguments, your application's top-level class name, followed by any arguments your application may require.

  • Assumes that the class name of your top-level application class is also used as the name of the entry to be looked up in your login configuration file.

  • Specifies the TextCallbackHandler class (from the com.sun.security.auth.callback package) as the class to be used when communicating with the user. This class can prompt the user for a user name and password.

  • Uses a LoginContext to authenticate the user. The LoginContext invokes the appropriate authentication technology, or LoginModule, to perform the authentication. LoginModules use a CallbackHandler (in our case, TextCallbackHandler) as needed to communicate with the user.

  • Allows the user three attempts to successfully log in.

  • Creates an instance of the MyAction class (also in Login.java), passing it the application arguments, if any.

  • Invokes Subject.doAsPrivileged, passing it a Subject representing the user, the MyAction instance, and a null AccessControlContext. The result is that the public static main method from your application is invoked and your application code is considered to be executed on behalf of the user.

Application and Other File Requirements

To utilize the Login utility to authenticate the user and execute your application, you may need a small number of additions or modifications to your login configuration file and policy file, as described in the following.

  • Application Requirements

  • Login Configuration File Requirements

  • Policy File Requirements

Application Requirements

In order to utilize the Login utility, your application code does not need anything special. All you need is for the entry point of your application to be the main method of a class you write, as usual.

The way to invoke Login such that it will authenticate the user and then instantiate MyAction to invoke your application is the following:

java <options> Login <AppName> <app arguments>
where <AppName> is your application's top-level class name and <app arguments> are any arguments required by your application. See Running the Sample Program with the Login Utility for the full command used for this tutorial.

Login Configuration File Requirements

Whenever a LoginContext is used to authenticate the user, you need a login configuration file to specify the desired login module. See the The Login Configuration File section in the JAAS authentication tutorial for more information as to what a login configuration file is and what it contains.

When you use the Login utility, the name for the login configuration file entry must be exactly the same as your top-level application class name. See The Login Configuration File in this tutorial for an example.

Policy File Requirements

Whenever you run an application with a security manager, you need a policy indicating the permissions granted to specific code, or to specific code being executed by a specific user (or users). One way of specifying the policy is by grant statements in a policy file. See The Policy File for more information.

If you use the Login utility to invoke your application, then you will need to grant it various permissions, as described in Permissions Required by the Login and MyAction Classes.

The Sample Application Program

The Sample.java application used for this tutorial performs the same actions as the SampleAction.java application did in the previous (JAAS Authorization) tutorial. It does the following:
  • Reads and prints the value of the java.home system property,

  • Reads and prints the value of the user.home system property, and

  • Determines whether or not a file named foo.txt exists in the current directory.

Here is the code:

import java.io.File;

public class Sample {

  public static void main (String[] args) throws SecurityException {

    // If there were any arguments to read, we'd do it here.

    System.out.println("\nYour java.home property value is: "
                +System.getProperty("java.home"));

    System.out.println("\nYour user.home property value is: "
                +System.getProperty("user.home"));

    File f = new File("foo.txt");
    System.out.print("\nfoo.txt does ");
    if (!f.exists())
        System.out.print("not ");
    System.out.println("exist in the current working directory.");
  }
}

The Login Configuration File

The sample.conf login configuration file for this tutorial contains a single entry, just like the login configuration file for the previous (JAAS Authorization) tutorial. The entry contents are the same since the class implementing the desired authentication technology in both cases is the Krb5LoginModule in the com.sun.security.auth.module package.

The only difference is the name used for the entry. In the previous tutorial we used the name "JaasSample", since that is the name used by the JaasAzn class to look up the entry. When you use the Login utility with your application, it expects the name for your login configuration file entry to be the same as the name of your top-level application class. That application class for this tutorial is named "Sample" so that must also be the name of the login configuration file entry. Thus the login configuration file looks like the following:

Sample {
   com.sun.security.auth.module.Krb5LoginModule required;
};

The "required" indicates that login using the Krb5LoginModule is required to "succeed" in order for authentication to be considered successful. The Krb5LoginModule succeeds only if the name and password supplied by the user are successfully used to log the user into the Kerberos KDC.

For information about all the possible options that can be passed to Krb5LoginModule, see the Krb5LoginModule documentation.

The Policy File

The Login, MyAction, and Sample classes all perform some security-sensitive operations and thus relevant permissions are required in a policy file in order for the operations to be executed.

Permissions Required by the Login and MyAction Classes

For this tutorial, you will create a Login.jar JAR file containing the Login.class and MyAction.class files. You need to grant Login.jar various permissions, specifically the ones required for invoking the security-sensitive methods the Login.jar classes call, as well as all the permissions required by your application. Otherwise, access control checks will fail.

The simplest thing to do, and what we recommend, is to grant Login.jar AllPermission. For this tutorial, the Login.jar file is assumed to be in the current directory and the policy file includes the following:

grant codebase "file:./Login.jar" {
   permission java.security.AllPermission;
};

Permissions Required by Sample

(Note: This section is essentially a modified copy of the Permissions Required by SampleAction section from the previous (JAAS Authorization) tutorial, since Sample and SampleAction perform the same operations and thus require the same permissions.)

The Sample code does three operations for which permissions are required. It

  • reads the value of the "java.home" system property.

  • reads the value of the "user.home" system property.

  • checks to see whether or not a file named foo.txt exists in the current directory.

The permissions required for these operations are the following:

permission java.util.PropertyPermission "java.home", "read";
permission java.util.PropertyPermission "user.home", "read";
permission java.io.FilePermission "foo.txt", "read";

We need to grant these permissions to the code in Sample.class, which we will place in a JAR file named Sample.jar. However, our grant statement will grant the permissions not just to the code but to a specific authenticated user executing the code. This illustrates how you can use a Principal designation in a grant statement to restrict execution of security-sensitive operations in code to a specific user rather than allowing the permissions to all users executing the code.

Thus, as explained in How Do You Make Principal-Based Policy File Statements?, our grant statement looks like the following:

grant codebase "file:./Sample.jar",
    Principal javax.security.auth.kerberos.KerberosPrincipal
        "your_user_name@your_realm"  {

   permission java.util.PropertyPermission "java.home", "read";
   permission java.util.PropertyPermission "user.home", "read";
   permission java.io.FilePermission "foo.txt", "read";
};
Important: You must substitute your Kerberos user name (complete with "@" and realm) for "your_user_name@your_realm". For example, if your user name is "mjones" and your realm is "KRBNT-OPERATIONS.ABC.COM", you would use "mjones@KRBNT-OPERATIONS.ABC.COM" (complete with the quotes).

The Full Policy File

The full policy file is sample.policy.

Running the Sample Program with the Login Utility

To execute the Sample application with the Login utility, do the following:

  1. Place the following files into a directory:

    • The Login.java source file.
    • The Sample.java source file.
    • The sample.conf login configuration file.
    • The sample.policy policy file.

  2. Replace "your_user_name@your_realm" in sample.policy with your user name and realm.

  3. Compile Login.java and Sample.java:
    javac Login.java Sample.java

    Note that Login.java contains two classes and thus compiling Login.java creates Login.class and MyAction.class.

  4. Create a JAR file named Login.jar containing Login.class and MyAction.class:
    jar -cvf Login.jar Login.class MyAction.class
  5. Create a JAR file named Sample.jar containing Sample.class:
    jar -cvf Sample.jar Sample.class
  6. Execute the Login class, specifying

    • by an appropriate -classpath clause that classes should be searched for in the Login.jar and Sample.jar JAR files,

    • by -Djava.security.manager that a security manager should be installed,

    • by -Djava.security.krb5.realm=<your_realm> that your Kerberos realm is the one specified.

    • by -Djava.security.krb5.kdc=<your_kdc> that your Kerberos KDC is the one specified.

    • by -Djava.security.policy=sample.policy that the policy file to be used is sample.policy, and

    • by -Djava.security.auth.login.config=sample.conf that the login configuration file to be used is sample.conf.

    You pass the name of your application (in this case, "Sample") as an argument to Login. You would then add as arguments any arguments required by your application, but in our case Sample does not require any.

    Below are the full commands to use for both Microsoft Windows and Unix systems. The only difference is that on Windows systems you use semicolons to separate classpath items, while you use colons for that purpose on Unix systems. Be sure to replace <your_realm> with your Kerberos realm, and <your_kdc> with your Kerberos KDC.

    Here is the full command for Windows systems:

    java -classpath Login.jar;Sample.jar
 -Djava.security.manager
 -Djava.security.krb5.realm=<your_realm>
 -Djava.security.krb5.kdc=<your_kdc>
 -Djava.security.policy=sample.policy
 -Djava.security.auth.login.config=sample.conf Login Sample

    Here is the full command for UNIX systems:

    java -classpath Login.jar:Sample.jar
 -Djava.security.manager
 -Djava.security.krb5.realm=<your_realm>
 -Djava.security.krb5.kdc=<your_kdc>
 -Djava.security.policy=sample.policy
 -Djava.security.auth.login.config=sample.conf Login Sample

    Type the full command on one line. Multiple lines are used here for legibility. If the command is too long for your system, you may need to place it in a .bat file (for Windows) or a .sh file (for UNIX) and then run that file to execute the command.

    You will be prompted for your Kerberos user name and password, and the underlying Kerberos login module specified in the login configuration file will log you into Kerberos. Once authentication is successfully completed, the Sample code will be executed on behalf of you, the user. The sample.policy policy file grants you the required permissions, so you will see a display of the values of your java.home and user.home system properties and a statement as to whether or not you have a file named foo.txt in the current directory.

    For login troubleshooting suggestions, see Troubleshooting.


Use of JAAS Login Utility and JavaTM GSS-API for Secure Message Exchanges

This tutorial presents two sample applications to demonstrate the use of the Java GSS-API. This API permits secure exchanges of messages between communicating applications. Here are the sample client and server applications you'll need for this tutorial:

  • SampleClient
  • SampleServer
Note: This tutorial uses the same client and server applications as the Use of JavaTM GSS-API for Secure Message Exchanges Without JAAS Programming tutorial. In that tutorial, JAAS (JavaTM Authentication and Authorization Service) programming is not required. Instead, you let the underlying mechanism decide how to get credentials.
This tutorial uses policy files and a more complex login configuration file. The programs are run with a security manager; as a result, security-sensitive operations are not allowed unless the required permissions were explicitly granted. This tutorial also demonstrates how JAAS authorization adds user-centric access control that applies control based on who is running the code--not just on what code is running.

Contents:

  • Before You Start: Recommended Reading

  • Overview of the Client And Server Applications

  • Kerberos User and Service Principal Names

  • The Login Configuration File

  • The Policy Files

  • Running the SampleClient and SampleServer Programs

Before You Start: Recommended Reading

In this Java GSS-API tutorial, the first step is JAAS authentication. Previous tutorials demonstrated the use of JAAS for user authentication and authorization, and presented examples of policy files and of login configuration files (specifying the underlying authentication technology to be used) that JAAS requires. Applications in the JAAS introductory tutorials, JAAS Authentication and JAAS Authorization, made direct calls to JAAS methods. The Use of JAAS Login Utility tutorial showed the use of a utility program that frees the application from having to do this. The client and server applications in the current tutorial also use the same utility program, so we recommend you read the login utility tutorial first.

As with all tutorials in this series, the underlying technology used to support authentication and secure communication for the applications in this tutorial is Kerberos. See Kerberos Requirements.

Overview of the Client and Server Applications

The applications for this tutorial are named SampleClient and SampleServer.

Each is invoked by executing the Login utility supplied with this tutorial and passing it as arguments the name of the application (SampleClient or SampleServer), followed by the arguments needed by the application. The Login utility uses a JAAS LoginContext to authenticate the user using Kerberos. Finally, the Login utility invokes the main method of the application class, in our case either SampleClient or SampleServer, and passes the application its arguments.

Here is a summary of execution of the SampleClient and SampleServer applications:

  1. Run the SampleServer application by running the Login utility and passing it as arguments the name "SampleServer" followed by the arguments for the SampleServer program. The Login utility prompts you for the password for the principal that SampleServer should run as. (See Kerberos User and Service Principal Names.) After authentication is complete, SampleServer is run it:
    1. Reads its argument, the port number that it should listen on for client connections.

    2. Creates a ServerSocket for listening for client connections on that port.

    3. Listens for a connection.

  2. Run the SampleClient application (possibly on a different machine), by running the Login utility and passing it as arguments the name "SampleClient" followed by the arguments for the SampleClient program. The Login utility prompts you for your Kerberos name and password. After authentication is complete, SampleClient is run. It

    1. Reads its arguments: (1) The name of the Kerberos principal that represents SampleServer. (See Kerberos User and Service Principal Names.), (2) the name of the host (machine) on which SampleServer is running, and (3) the port number on which SampleServer listens for client connections.

    2. Attempts a socket connection with the SampleServer, using the host and port it was passed as arguments.

  3. The socket connection is accepted by SampleServer and both applications initialize a DataInputStream and a DataOutputStream from the socket input and output streams, to be used for future data exchanges.

  4. SampleClient and SampleServer each instantiate a GSSContext and establish a shared context that will enable subsequent secure data exchanges.

  5. SampleClient and SampleServer can now securely exchange messages.

  6. When SampleClient and SampleServer are done exchanging messages, they perform clean-up operations.
Note: Refer to "The SampleClient and SampleServer Code" section of the Use of JavaTM GSS-API for Secure Message Exchanges Without JAAS Programming tutorial for a full discussion of the code used in this tutorial.

Kerberos User and Service Principal Names

Since the underlying authentication and secure communication technology used by this tutorial is Kerberos V5, we use Kerberos-style principal names wherever a user or service is called for.

For example, when you run SampleClient you are asked to provide your user name. Your Kerberos-style user name is simply the user name you were assigned for Kerberos authentication. It consists of a base user name (like "mjones") followed by an "@" and your realm (like "mjones@KRBNT-OPERATIONS.ABC.COM").

A server program like SampleServer is typically considered to offer a "service" and to be run on behalf of a particular "service principal." A service principal name for SampleServer is needed in several places:

  • When you run SampleServer you must log in as the appropriate service principal. The login configuration file for this tutorial actually specifies the service principal name (as an option to the Krb5LoginModule), so the JAAS authentication (done by the Login utility) just asks you to specify the password for that service principal. If you specify the correct password, the authentication is successful, a Subject is created containing a Principal with the service principal name, and that Subject is associated with a new access control context. The subsequently-executed code (the SampleServer code) is considered to be executed on behalf of the specified principal.

  • When you run SampleClient, one of the arguments is the service principal name. This is needed so SampleClient can initiate establishment of a security context with the appropriate service.

  • The client and server policy files each require a ServicePermission with name equal to the service principal name and action equal to "initiate" or "accept" (for initiating or accepting establishment of a security context).

Throughout this document, and in the accompanying login configuration file and policy files,

service_principal@your_realm
is used as a placeholder to be replaced by the actual name to be used in your environment. Any Kerberos principal can actually be used for the service principal name. So for the purposes of trying out this tutorial, you could use your user name as both the client user name and the service principal name.

In a production environment, system administrators typically like servers to be run as specific principals only and may assign a particular name to be used. Often the Kerberos-style service principal name assigned is of the form

service_name/machine_name@realm;

For example, an nfs service run on a machine named "raven" in the realm named "KRBNT-OPERATIONS.ABC.COM" could have the service principal name

nfs/raven@KRBNT-OPERATIONS.ABC.COM

Such multi-component names are not required, however. Single-component names, just like those of user principals, can be used. For example, an installation might use the same ftp service principal ftp@realm for all ftp servers in that realm, while another installation might have different ftp principals for different ftp servers, such as ftp/host1@realm and ftp/host2@realm on machines host1 and host2, respectively.

When the Realm is Required in Principal Names

If the realm of a user or service principal name is the default realm (see Kerberos Requirements), you can leave off the realm when you are logging into Kerberos (that is, when you are prompted for your username). Thus, for example, if your user name is "mjones@KRBNT-OPERATIONS.ABC.COM", and you run SampleClient, when it requests your user name you could just specify "mjones", leaving off the realm. The name is interpreted in the context of being a Kerberos principal name and the default realm is appended, as needed.

You can also leave off the realm if a principal name will be converted to a GSSName by a GSSManager createName method. For example, when you run SampleClient, one of the arguments is the server service principal name. You can specify the name without including the realm, because SampleClient passes the name to such a createName method, which appends the default realm as needed.

It is recommended that you always include realms when principal names are used in login configuration files and policy files, because the behavior of the parsers for such files may be implementation-dependent; they may or may not append the default realm before such names are utilized and subsequent actions may fail if there is no realm in the name.

The Login Configuration File

Whenever JAAS is used, a login configuration is required to specify the desired authentication technology. (See JAAS Login Configuration File for more information about what a login configuration file is.) Both SampleClient and SampleServer can use the same login configuration file, if that file contains two entries, one entry for the client side and one for the server side.

The csLogin.conf login configuration file used for this tutorial is the following:

SampleClient {
  com.sun.security.auth.module.Krb5LoginModule required;
};

SampleServer {
  com.sun.security.auth.module.Krb5LoginModule required storeKey=true
    principal="service_principal@your_realm";
};

Note that the name for each entry matches the respective class names for our two top-level applications, SampleClient and SampleServer. Recall that this is also the name that is passed to the Login utility that performs JAAS operations for the application. That utility expects the name of the entry to be looked up in your login configuration file to be the same as the name it is passed.

Both entries specify that Sun's Kerberos V5 LoginModule must be used to successfully authenticate the user. The Krb5LoginModule succeeds only if the attempt to log in to the Kerberos KDC as a specified entity is successful. In the case of SampleClient, the user will be prompted for their name and password. In the case of SampleServer, a name is already supplied in this login configuration file (the specified principal, as described below) and the user running SampleServer is just asked for the password for the entity specified by that name. They must specify the correct password in order for authentication to succeed.

The SampleServer entry storeKey=true indicates that a secret key should be calculated from the password provided during login and it should be stored in the private credentials of the Subject created as a result of login. This key is subsequently utilized during mutual authentication when establishing a security context between SampleClient and SampleServer.

The Krb5LoginModule has a principal option that can be used to specify that only the specified principal (entity/user) should be logged in for the given program. Here, the SampleClient entry does not specify a principal (although it could, if desired), so the user is prompted for a user name and password and anyone with a valid user name and password can run SampleClient. SampleServer, on the other hand, indicates a particular principal because system administrators usually like servers to be run as specific principals only. In this case, the user running SampleServer is prompted for that principal's password and must supply the correct one in order for authentication to succeed.

Note that you must replace "service_principal@your_realm" with the name of the service principal that represents SampleServer. (See Kerberos User and Service Principal Names.)

For information about all the possible options that can be passed to Krb5LoginModule, see the Krb5LoginModule documentation.

The Policy Files

The policy file used when running SampleClient is client.policy, and the policy file used when running SampleServer is server.policy. Their contents are described below.

The Client Policy File

Permissions Required by the Login utility Classes

A number of permissions are required by the classes in Login.java (Login and MyAction). As recommended in the previous tutorial on the use of Login, we create a Login.jar JAR file containing the Login.class and MyAction.class files and in the client.policy policy file we grant Login.jar AllPermission:

grant codebase "file:./Login.jar" {
   permission java.security.AllPermission;
};

Permissions Required by SampleClient

The SampleClient code does two types of operations for which permissions are required. It

  • opens a socket connection with the host machine running the SampleServer application.

  • initiates establishment of a security context with SampleServer.

The permission required to open a socket connection is

permission java.net.SocketPermission "*", "connect";

You may replace the "*" with the hostname or IP address of the machine that SampleServer will be running on.

The permission(s) required to initiate establishment of a security context will depend on the underlying mechanism. This tutorial uses Kerberos as the underlying mechanism, and for that two javax.security.auth.kerberos.ServicePermissions are required. A ServicePermission contains a service principal name and an action (or list of actions). To initiate establishment of a security context, you need two ServicePermissions with action "initiate", whose names specify:

  • the service principal name for the ticket granting service for your realm. Granting this permission essentially allows the use of Kerberos as a client.

  • the service principal name representing SampleServer. (See Kerberos User and Service Principal Names.) Granting this permission allows you to interact with the service, SampleServer, using Kerberos.

We want to grant the permissions to a specific authenticated user executing SampleClient, so we specify both the SampleClient code location (in SampleClient.jar) and a Principal designation indicating the user name and realm for the user (you, the person who will run SampleClient). (See How Do You Make Principal-Based Policy File Statements? in the second tutorial of this series for information on policy file grant statements that include Principal designations.)

Here is the basic form for the grant statement:

  grant CodeBase "file:./SampleClient.jar",
    Principal javax.security.auth.kerberos.KerberosPrincipal
        "your_user_name@your_realm" {

    permission java.net.SocketPermission "*", "connect";

    permission javax.security.auth.kerberos.ServicePermission
        "krbtgt/your_realm@your_realm",
        "initiate";

    permission javax.security.auth.kerberos.ServicePermission
        "service_principal@your_realm",
        "initiate";
};

You must substitute your Kerberos user name (complete with "@" and realm) for "your_user_name@your_realm". For example, if your user name is "mjones" and your realm is "KRBNT-OPERATIONS.ABC.COM", you would use "mjones@KRBNT-OPERATIONS.ABC.COM" (complete with the quotes).

You must also substitute your realm in "krbtgt/your_realm@your_realm" and the service principal name for the service principal representing the server for "service_principal@your_realm". Suppose the former is "krbtgt/KRBNT-OPERATIONS.ABC.COM@KRBNT-OPERATIONS.ABC.COM" and the latter is "sample/raven.abc.com@KRBNT-OPERATIONS.ABC.COM", and your user name is as specified in the previous paragraph. Then the grant statement would be

grant CodeBase "file:./SampleClient.jar",
    Principal javax.security.auth.kerberos.KerberosPrincipal
        "mjones@KRBNT-OPERATIONS.ABC.COM" {

    permission java.net.SocketPermission "*", "connect";

    permission javax.security.auth.kerberos.ServicePermission
        "krbtgt/KRBNT-OPERATIONS.ABC.COM@KRBNT-OPERATIONS.ABC.COM",
        "initiate";

    permission javax.security.auth.kerberos.ServicePermission
        "sample/raven.abc.com@KRBNT-OPERATIONS.ABC.COM",
        "initiate";
};

The Server Policy File

Permissions Required by the Login Utility Classes

The grant statement in the server policy file for the Login classes is exactly the same as the one in the client policy file, as described in Permissions Required by the Login Utility Classes:

grant codebase "file:./Login.jar" {
   permission java.security.AllPermission;
};

Permissions Required by SampleServer

The SampleServer code does two types of operations for which permissions are required. It

  • accepts socket connections.

  • accepts establishment of a security context, that is, it is the "acceptor" for security context establishment.

The permission required to accept socket connections is

permission java.net.SocketPermission "*", "accept";

You may replace the "*" with the hostname or IP address of the machine that SampleClient will be running on.

The permission required to accept establishment of a security context is

permission javax.security.auth.kerberos.ServicePermission
    "service_principal@your_realm",
    "accept";
where "service_principal@your_realm" is the Kerberos name of the service principal that represents SampleServer.

We want to grant the permissions to a specific authenticated user executing SampleServer (the service principal considered to represent SampleServer), so we specify both the SampleServer code location (in SampleServer.jar) and a Principal designation indicating the service principal. Suppose this name is "sample/raven.abc.com@KRBNT-OPERATIONS.ABC.COM". Then the grant statement would be

  grant CodeBase "file:./SampleServer.jar"
    Principal javax.security.auth.kerberos.KerberosPrincipal
        "sample/raven.abc.com@KRBNT-OPERATIONS.ABC.COM" {

    permission java.net.SocketPermission "*", "accept";

    permission javax.security.auth.kerberos.ServicePermission
        "sample/raven.abc.com@KRBNT-OPERATIONS.ABC.COM", "accept";
};

Running the SampleClient and SampleServer Programs

To execute the SampleClient and SampleServer programs, do the following:

  • Prepare SampleServer for Execution

  • Prepare SampleClient for Execution

  • Execute SampleServer

  • Execute SampleClient

Prepare SampleServer for Execution

To prepare SampleServer for execution, do the following:

  1. Copy the following files into a directory accessible by the machine on which you will run SampleServer:

    • The Login.java source file.
    • The SampleServer.java source file.
    • The csLogin.conf login configuration file.
    • The server.policy policy file.

  2. Replace "service_principal@your_realm" in csLogin.conf with the name of the service principal representing SampleServer.

  3. In both places it appears, replace "service_principal@your_realm" in server.policy with the Kerberos name of the service principal that represents SampleServer. (The same name as that used in the login configuration file.)

  4. Compile Login.java and SampleServer.java:
    javac Login.java SampleServer.java

    Note that Login.java contains two classes and thus compiling Login.java creates Login.class and MyAction.class.

  5. Create a JAR file named Login.jar containing Login.class and MyAction.class:
    jar -cvf Login.jar Login.class MyAction.class
  6. Create a JAR file named SampleServer.jar containing SampleServer.class:
    jar -cvf SampleServer.jar SampleServer.class

Prepare SampleClient for Execution

To prepare SampleClient for execution, do the following:

  1. Copy the following files into a directory accessible by the machine on which you will run SampleClient:

    • The Login.java source file.
    • The SampleClient.java source file.
    • The csLogin.conf login configuration file.
    • The client.policy policy file.

  2. Replace parts of client.policy:

    • replace "your_user_name@your_realm" with your user name and realm.

    • replace your_realm in "krbtgt/your_realm@your_realm" with your realm.

    • replace "service_principal@your_realm" with the Kerberos name of the service principal that represents SampleServer.

  3. Compile Login.java and SampleClient.java:
    javac Login.java SampleClient.java
  4. Create a JAR file named Login.jar containing Login.class and MyAction.class:
    jar -cvf Login.jar Login.class MyAction.class
  5. Create a JAR file named SampleClient.jar containing SampleClient.class:
    jar -cvf SampleClient.jar SampleClient.class

Execute SampleServer

It is important to execute SampleServer before SampleClient because SampleClient will try to make a socket connection to SampleServer and that will fail if SampleServer is not yet running and accepting socket connections.

To execute SampleServer, be sure to run it on the machine it is expected to be run on. This machine name (host name) is specified as an argument to SampleClient. The service principal name appears in several places, including the login configuration file and the policy files.

Go to the directory in which you have prepared SampleServer for execution. Execute the Login class, specifying

  • by an appropriate -classpath clause that classes should be searched for in the Login.jar and SampleServer.jar JAR files,

  • by -Djava.security.manager that a security manager should be installed,

  • by -Djava.security.krb5.realm=<your_realm> that your Kerberos realm is the one specified. For example, if your realm is "KRBNT-OPERATIONS.ABC.COM" you'd put -Djava.security.krb5.realm=KRBNT-OPERATIONS.ABC.COM.

  • by -Djava.security.krb5.kdc=<your_kdc> that your Kerberos KDC is the one specified. For example, if your KDC is "samplekdc.abc.com" you'd put -Djava.security.krb5.kdc=samplekdc.abc.com.

  • by -Djava.security.policy=server.policy that the policy file to be used is server.policy, and

  • by -Djava.security.auth.login.config=csLogin.conf that the login configuration file to be used is csLogin.conf.

You pass the name of your application (in this case, "SampleServer") as an argument to Login. You then add as arguments any arguments required by your application, which in the case of SampleServer is a single argument specifying the port number to be used for listening for client connections. Choose a high port number unlikely to be used for anything else. An example would be something like 4444.

Below are the full commands to use for both Microsoft Windows and Unix systems. The only difference is that on Microsoft Windows systems you use semicolons to separate classpath items, while you use colons for that purpose on Unix systems.

Important: In these commands, you must replace <port_number> with an appropriate port number, <your_realm> with your Kerberos realm, and <your_kdc> with your Kerberos KDC.

Here is the command for Microsoft Windows systems:

java -classpath Login.jar;SampleServer.jar
 -Djava.security.manager
 -Djava.security.krb5.realm=<your_realm>
 -Djava.security.krb5.kdc=<your_kdc>
 -Djava.security.policy=server.policy
 -Djava.security.auth.login.config=csLogin.conf
 Login SampleServer <port_number>

Here is the command for UNIX systems:

java -classpath Login.jar:SampleServer.jar
 -Djava.security.manager
 -Djava.security.krb5.realm=<your_realm>
 -Djava.security.krb5.kdc=<your_kdc>
 -Djava.security.policy=server.policy
 -Djava.security.auth.login.config=csLogin.conf
 Login SampleServer <port_number>

Type the full command on one line. Multiple lines are used here for legibility. If the command is too long for your system, you may need to place it in a .bat file (for Microsoft Windows) or a .sh file (for UNIX) and then run that file to execute the command.

You will be prompted for the Kerberos password for the service principal. The underlying Kerberos authentication mechanism specified in the login configuration file will log the service principal into Kerberos. Once authentication is successfully completed, the SampleServer code will be executed on behalf of the service principal. It will listen for socket connections on the specified port.

For login troubleshooting suggestions, see Troubleshooting.

Execute SampleClient

To execute SampleClient, go to the directory in which you have prepared SampleClient for execution. Then execute the Login class, specifying

  • by an appropriate -classpath clause that classes should be searched for in the Login.jar and SampleClient.jar JAR files,

  • by -Djava.security.manager that a security manager should be installed,

  • by -Djava.security.krb5.realm=<your_realm> that your Kerberos realm is the one specified.

  • by -Djava.security.krb5.kdc=<your_kdc> that your Kerberos KDC is the one specified.

  • by -Djava.security.policy=client.policy that the policy file to be used is client.policy, and

  • by -Djava.security.auth.login.config=csLogin.conf that the login configuration file to be used is csLogin.conf.

Pass to Login the name of your application ("SampleClient") followed by the arguments required by SampleClient. The SampleClient arguments are (1) the Kerberos name of the service principal that represents SampleServer, (2) the name of the host (machine) on which SampleServer is running, and (3) the port number on which SampleServer is listening for client connections.

Below are the full commands to use for both Microsoft Windows and Unix systems.

Important: In these commands, you must replace <service_principal>, <host>, <port_number>, <your_realm>, and <your_kdc> with appropriate values (and note that the port number must be the same as the port number passed as an argument to SampleServer). These values need not be placed in quotes.

Here is the command for Microsoft Windows systems:

java -classpath Login.jar;SampleClient.jar
 -Djava.security.manager
 -Djava.security.krb5.realm=<your_realm>
 -Djava.security.krb5.kdc=<your_kdc>
 -Djava.security.policy=client.policy
 -Djava.security.auth.login.config=csLogin.conf
 Login SampleClient <service_principal> <host> <port_number>

Here is the command for UNIX systems:

java -classpath Login.jar:SampleClient.jar
 -Djava.security.manager
 -Djava.security.krb5.realm=<your_realm>
 -Djava.security.krb5.kdc=<your_kdc>
 -Djava.security.policy=client.policy
 -Djava.security.auth.login.config=csLogin.conf
 Login SampleClient <service_principal> <host> <port_number>

Type the full command on one line. Multiple lines are used here for legibility. As with the command for executing SampleServer, if the command is too long to type directly into your command window, place it in a .bat file (Microsoft Windows) or a .sh file (UNIX) and then execute that file.

When prompted, type your Kerberos user name and password. The underlying Kerberos authentication mechanism specified in the login configuration file will log you into Kerberos. Once authentication is successfully completed, the SampleClient code will be executed on behalf of you. It will request a socket connection with SampleServer. Once SampleServer accepts the connection, SampleClient and SampleServer establish a shared context and then exchange messages as described in this tutorial.

For login troubleshooting suggestions, see Troubleshooting.


Use of JavaTM GSS-API for Secure Message Exchanges Without JAAS Programming

This tutorial presents two sample applications demonstrating the use of the Java GSS-API for secure exchanges of messages between communicating applications, in this case a client application and a server application.

Java GSS-API uses what is called a "security mechanism" to provide these services. The GSS-API implementation available with the Java 2 Standard Edition platform contains support for the Kerberos V5 mechanism in addition to any other vendor-specific choices. We use the Kerberos V5 mechanism for this tutorial.

In order to perform authentication between the client and server and to establish cryptographic keys for secure communication, a GSS-API mechanism needs access to certain credentials for the local entity on each side of the connection. In our case, the credential used on the client side consists of a Kerberos ticket, and on the server side, it consists of a long-term Kerberos secret key. Kerberos tickets can optionally include the host address and IPv4 and IPv6 host addresses are both supported. Java GSS-API requires that the mechanism obtain these credentials from the Subject associated with the thread's access control context.

To populate a Subject with such credentials, client and server applications typically will first perform JAAS authentication using a Kerberos module. The JAAS Authentication tutorial demonstrates how to do this. The JAAS Authorization tutorial then demonstrates how to associate the authenticated Subject with the thread's access control context. A utility has also been written as a convenience to automatically perform those operations on your behalf. The Use of JAAS Login Utility tutorial demonstrates how to use the Login utility.

For this tutorial, we will not have the client and server perform JAAS authentication, nor will we have them use the Login utility. Instead, we will rely on setting the system property javax.security.auth.useSubjectCredsOnly to false, which allows us to relax the restriction of requiring a GSS mechanism to obtain necessary credentials from an existing Subject, set up by JAAS. See The useSubjectCredsOnly System Property.

Note: This is a simplified introductory tutorial. For example, we do not include any policy files or run the sample code using a security manager. In real life, code using Java GSS-API should be run with a security manager, so that security-sensitive operations would not be allowed unless the required permissions were explicitly granted.

There is another tutorial, Use of JAAS Login Utility and Java GSS-API for Secure Message Exchanges, that is just like the tutorial you are reading except that it utilizes the Login utility, policy files, and a more complex login configuration file (A login configuration file, required whenever JAAS authentication is done, specifies the desired authentication module).

As with all tutorials in this series, the underlying technology used to support authentication and secure communication for the applications in this tutorial is Kerberos V5. See Kerberos Requirements.

  • Overview of the Client And Server Applications

  • The SampleClient and SampleServer Code

  • Kerberos User and Service Principal Names

  • The Login Configuration File

  • The useSubjectCredsOnly System Property

  • Running the SampleClient and SampleServer Programs

If you want to first see the tutorial code in action, you can skip directly to Running the SampleClient and SampleServer Programs and then go back to the other sections to learn more.

Overview of the Client And Server Applications

The applications for this tutorial are named SampleClient and SampleServer.

Here is a summary of execution of the SampleClient and SampleServer applications:

  1. Run the SampleServer application. SampleServer

    1. Reads its argument, the port number that it should listen on for client connections.

    2. Creates a ServerSocket for listening for client connections on that port.

    3. Listens for a connection.

  2. Run the SampleClient application (possibly on a different machine). SampleClient

    1. Reads its arguments: (1) The name of the Kerberos principal that represents SampleServer. (See Kerberos User and Service Principal Names.), (2) the name of the host (machine) on which SampleServer is running, and (3) the port number on which SampleServer listens for client connections.

    2. Attempts a socket connection with the SampleServer, using the host and port it was passed as arguments.

  3. The socket connection is accepted by SampleServer and both applications initialize a DataInputStream and a DataOutputStream from the socket input and output streams, to be used for future data exchanges.

  4. SampleClient and SampleServer each instantiate a GSSContext and follow a protocol for establishing a shared context that will enable subsequent secure data exchanges.

  5. SampleClient and SampleServer can now securely exchange messages.

  6. When SampleClient and SampleServer are done exchanging messages, they perform clean-up operations.

The actual code and further details are presented in the following sections.

The SampleClient and SampleServer Code

The entire code for both the SampleClient and SampleServer programs resides in their main methods and can be broken down into the following subparts:

  1. Obtain the Command-Line Arguments

  2. Establish a Socket Connection for Transfers Between SampleClient and SampleServer

  3. Establish a Security Context

  4. Securely Exchange Messages

  5. Clean Up

Note: The Java GSS-API classes utilized by these programs (GSSManager, GSSContext, GSSName, GSSCredential, MessageProp, and Oid) are found in the org.ietf.jgss package.

Obtaining the Command-Line Arguments

The first thing both our client and server main methods do is read the command-line arguments.

Arguments Read By SampleClient

SampleClient expects three arguments:

  1. A service principal name -- The name of the Kerberos principal that represents SampleServer. (See Kerberos User and Service Principal Names.)

  2. A host name -- The machine on which SampleServer is running.

  3. A port number -- The port number of the port on which SampleServer listens for connections.

Here is the code for reading the command-line arguments:

if (args.length < 3) {
    System.out.println("Usage: java <options> Login SampleClient "
       + " <servicePrincipal> <hostName> <port>");
    System.exit(-1);
}

String server = args[0];
String hostName = args[1];
int port = Integer.parseInt(args[2]);

Argument Read By SampleServer

SampleServer expects just one argument:

  • A local port number -- The port number used by SampleServer for listening for connections with clients. This number should be the same as the port number specified when running the SampleClient program.

Here is the code for reading the command-line argument:

if (args.length != 1) {
    System.out.println(
        "Usage: java <options> Login SampleServer <localPort>");
    System.exit(-1);
}

int localPort = Integer.parseInt(args[0]);

Establishing a Socket Connection for Message Exchanges

Java GSS-API provides methods for creating and interpreting tokens (opaque byte data). The tokens contain messages to be securely exchanged between two peers, but the method of actual token transfer is up to the peers. For our SampleClient and SampleServer applications, we establish a socket connection between the client and server and exchange data using the socket input and output streams.

SampleClient Code For Socket Connection

SampleClient was passed as arguments the name of the host machine SampleServer is running on, as well as the port number on which SampleServer will be listening for connections, so SampleClient has all it needs to establish a socket connection with SampleServer. It uses the following code to set up the connection and initialize a DataInputStream and a DataOutputStream for future data exchanges:

Socket socket = new Socket(hostName, port);

DataInputStream inStream =
  new DataInputStream(socket.getInputStream());
DataOutputStream outStream =
  new DataOutputStream(socket.getOutputStream());

System.out.println("Connected to server "
   + socket.getInetAddress());

SampleServer Code For Socket Connection

The SampleServer application was passed as an argument the port number to be used for listening for connections from clients. It creates a ServerSocket for listening on that port:

ServerSocket ss = new ServerSocket(localPort);

The ServerSocket can then wait for and accept a connection from a client, and then initialize a DataInputStream and a DataOutputStream for future data exchanges with the client :

Socket socket = ss.accept();

DataInputStream inStream =
    new DataInputStream(socket.getInputStream());
DataOutputStream outStream =
    new DataOutputStream(socket.getOutputStream());

System.out.println("Got connection from client "
    + socket.getInetAddress());

The accept method waits until a client (in our case, SampleClient) requests a connection on the host and port of the SampleServer, which SampleClient does via

Socket socket = new Socket(hostName, port);

When the connection is requested and established, the accept method returns a new Socket object bound to a new port. The server can communicate with the client over this new socket and continue to listen for other client connection requests on the ServerSocket bound to the original port. Thus, a server program typically has a loop which can handle multiple connection requests.

The basic loop structure for our SampleServer is the following:

while (true) {

    Socket socket = ss.accept();

    <Establish input and output streams for the connection>
    <Establish a context with the client>
    <Exchange messages with the client>;
    <Clean up>;
}

Client connections are queued at the original port, so with this program structure used by SampleServer, the interaction with the first client making a connection has to complete before the next connection can be accepted. The server could actually service multiple clients simultaneously through the use of threads - one thread per client connection, as in

while (true) {
    <accept a connection>;
    <create a thread to handle the client>;
}

Establishing a Security Context

Before two applications can use Java GSS-API to securely exchange messages between them, they must establish a joint security context using their credentials. (Note: In the case of SampleClient, the credentials were established when the Login utility authenticated the user on whose behalf the SampleClient was run, and similarly for SampleServer.) The security context encapsulates shared state information that might include, for example, cryptographic keys. One use of such keys might be to encrypt messages to be exchanged, if encryption is requested.

As part of the security context establishment, the context initiator (in our case, SampleClient) is authenticated to the acceptor (SampleServer), and may require that the acceptor also be authenticated back to the initiator, in which case we say that "mutual authentication" took place.

Both applications create and use a GSSContext object to establish and maintain the shared information that makes up the security context.

The instantiation of the context object is done differently by the context initiator and the context acceptor. After the initiator instantiates a GSSContext, it may choose to set various context options that will determine the characteristics of the desired security context, for example, specifying whether or not mutual authentication should take place. After all the desired characteristics have been set, the initiator calls the initSecContext method, which produces a token required by the acceptor's acceptSecContext method.

While Java GSS-API methods exist for preparing tokens to be exchanged between applications, it is the responsibility of the applications to actually transfer the tokens between them. So after the initiator has received a token from its call to initSecContext, it sends that token to the acceptor. The acceptor calls acceptSecContext, passing it the token. The acceptSecContext method may in turn return a token. If it does, the acceptor should send that token to the initiator, which should then call initSecContext again and pass it this token. Each time initSecContext or acceptSecContext returns a token, the application that called the method should send the token to its peer and that peer should pass the token to its appropriate method (acceptSecContext or initSecContext). This continues until the context is fully established (which is the case when the context's isEstablished method returns true).

The context establishment code for our sample applications is described in the following:

  • Context Establishment by SampleClient

  • Context Establishment by SampleServer

Context Establishment by SampleClient

In our client/server scenario, SampleClient is the context initiator. Here are the basic steps it takes to establish a security context. It

  1. Instantiates a GSSContext.

  2. Sets the desired optional features on the context.

  3. Loops while the context is not yet established, each time calling initSecContext, sending any returned token to SampleServer, and receiving a token (if any) from SampleServer.

SampleClient GSSContext Instantiation

A GSSContext is created by instantiating a GSSManager and then calling one of its createContext methods. The GSSManager class serves as a factory for other important GSS API classes. It can create instances of classes implementing the GSSContext, GSSCredential, and GSSName interfaces.

SampleClient obtains an instance of the default GSSManager subclass by calling the GSSManager static method getInstance:

GSSManager manager = GSSManager.getInstance();

The default GSSManager subclass is one whose create* methods (createContext, etc.) return classes whose implementations support Kerberos as the underlying technology.

The GSSManager factory method for creating a context on the initiator's side has the following signature:

GSSContext createContext(GSSName peer, Oid mech,
            GSSCredential myCred, int lifetime);

The arguments are described below, followed by the complete call to createContext.

The GSSName peer Argument

The peer in our client/server paradigm is the server. For the peer argument, we need a GSSName for the service principal representing the server. (See Kerberos User and Service Principal Names.) A String for the service principal name is passed as the first argument to SampleClient, which places the argument into its local String variable named server. The GSSManager manager is used to instantiate a GSSName by calling one of its createName methods. SampleClient calls the createName method with the following signature:

GSSName createName(String nameStr, Oid nameType);

SampleClient passes the server String for the nameStr argument.

The second argument is an Oid. An Oid represents a Universal Object Identifier. Oids are hierarchically globally-interpretable identifiers used within the GSS-API framework to identify mechanisms and name types. The structure and encoding of Oids is defined in the ISOIEC-8824 and ISOIEC-8825 standards. The Oid passed to the createName method is specifically a name type Oid (not a mechanism Oid).

In GSS-API, string names are often mapped from a mechanism-independent format into a mechanism-specific format. Usually, an Oid specifies what name format the string is in so that the mechanism knows how to do this mapping. Passing in a null Oid indicates that the name is already in a native format that the mechanism uses. This is the case for the server String; it is in the appropriate format for a Kerberos Version 5 name. Thus, SampleClient passes a null for the Oid. Here is the call:

GSSName serverName = manager.createName(server, null);

The Oid mech Argument

The second argument to the GSSManager createContext method is an Oid representing the mechanism to be used for the authentication between the client and the server during context establishment and for subsequent secure communication between them.

Our tutorial will use Kerberos V5 as the security mechanism. The Oid for the Kerberos V5 mechanism is defined in RFC 1964 as "1.2.840.113554.1.2.2" so we create such an Oid:

Oid krb5Oid = new Oid("1.2.840.113554.1.2.2");

SampleClient passes krb5Oid as the second argument to createContext.

The GSSCredential myCred Argument

The third argument to the GSSManager createContext method is a GSSCredential representing the caller's credentials. If you pass null for this argument, as SampleClient does, the default credentials are used.

The int lifetime Argument

The final argument to the GSSManager createContext method is an int specifying the desired lifetime, in seconds, for the context that is created. SampleClient passes GSSContext.DEFAULT_LIFETIME to request a default lifetime.

The Complete createContext Call

Now that we have all the required arguments, here is the call SampleClient makes to create a GSSContext:

GSSContext context =
    manager.createContext(serverName,
                          krb5Oid,
                          null,
                          GSSContext.DEFAULT_LIFETIME);

SampleClient Setting of Desired Options

After instantiating a context, and prior to actually establishing the context with the context acceptor, the context initiator may choose to set various options that determine the desired security context characteristics. Each such option is set by calling a request method on the instantiated context. Most request methods take a boolean argument for indicating whether or not the feature is requested. It is not always possible for a request to be satisfied, so whether or not it was can be determined after context establishment by calling one of the get methods.

SampleClient requests the following:

  1. Mutual authentication. The context initiator is always authenticated to the acceptor. If the initiator requests mutual authentication, then the acceptor is also authenticated to the initiator.

  2. Confidentiality. Requesting confidentiality means that you request the enabling of encryption for the context method named wrap. Encryption is actually used only if the MessageProp object passed to the wrap method requests privacy.

  3. Integrity. This requests integrity for the wrap and getMIC methods. When integrity is requested, a cryptographic tag known as a Message Integrity Code (MIC) will be generated when calling those methods. When getMIC is called, the generated MIC appears in the returned token. When wrap is called, the MIC is packaged together with the message (the original message or the result of encrypting the message, depending on whether confidentiality was applied) all as part of one token. You can subsequently verify the MIC against the message to ensure that the message has not been modified in transit.

The SampleClient code for making these requests on the GSSException context is the following:

context.requestMutualAuth(true);  // Mutual authentication
context.requestConf(true);  // Will use encryption later
context.requestInteg(true); // Will use integrity later

Note: When using the default GSSManager implementation and the Kerberos mechanism, these requests will always be granted.

SampleClient Context Establishment Loop

After SampleClient has instantiated a GSSContext and specified the desired context options, it can actually establish the security context with SampleServer. To do so, SampleClient has a loop. Each loop iteration

  1. Calls the context's initSecContext method. If this is the first call, the method is passed a null token. Otherwise, it is passed the token most recently sent to SampleClient by SampleServer (a token generated by a SampleServer call to acceptSecContext).

  2. Sends the token returned by initSecContext (if any) to SampleServer. The first call to initSecContext always produces a token. The last call might not return a token.

  3. Checks to see if the context is established. If not, SampleClient receives another token from SampleServer and then starts the next loop iteration.

The tokens returned by initSecContext or received from SampleServer are placed in a byte array. Tokens should be treated by SampleClient and SampleServer as opaque data to be passed between them and interpreted by Java GSS-API methods.

The initSecContext arguments are a byte array containing a token, the starting offset into that array of where the token begins, and the token length. For the first call, SampleClient passes a null token, since no token has yet been received from SampleServer.

To exchange tokens with SampleServer, SampleClient uses the DataInputStream inStream and DataOutputStream outStream it previously set up using the input and output streams for the socket connection made with SampleServer. Note that whenever a token is written, the number of bytes in the token is written first, followed by the token itself. The reasons are discussed in the introduction to the The SampleClient and SampleServer Message Exchanges section.

Here is the SampleClient context establishment loop, followed by code displaying information about who the client and server are and whether or not mutual authentication actually took place:

byte[] token = new byte[0];

while (!context.isEstablished()) {

    // token is ignored on the first call
    token = context.initSecContext(token, 0, token.length);

    // Send a token to the server if one was generated by
    // initSecContext
    if (token != null) {
        System.out.println("Will send token of size "
                   + token.length + " from initSecContext.");
        outStream.writeInt(token.length);
        outStream.write(token);
        outStream.flush();
    }

    // If the client is done with context establishment
    // then there will be no more tokens to read in this loop
    if (!context.isEstablished()) {
        token = new byte[inStream.readInt()];
        System.out.println("Will read input token of size "
                   + token.length
                   + " for processing by initSecContext");
        inStream.readFully(token);
    }
}

System.out.println("Context Established! ");
System.out.println("Client is " + context.getSrcName());
System.out.println("Server is " + context.getTargName());
if (context.getMutualAuthState())
    System.out.println("Mutual authentication took place!");

Context Establishment by SampleServer

In our client/server scenario, SampleServer is the context acceptor. Here are the basic steps it takes to establish a security context. It

  1. Instantiates a GSSContext.

  2. Loops while the context is not yet established, each time receiving a token from SampleClient, calling acceptSecContext and passing it the token, and sending any returned token to SampleClient.

SampleServer GSSContext Instantiation

As described in SampleClient GSSContext Instantiation, a GSSContext is created by instantiating a GSSManager and then calling one of its createContext methods.

Like SampleClient, SampleServer obtains an instance of the default GSSManager subclass by calling the GSSManager static method getInstance:

GSSManager manager = GSSManager.getInstance();

The GSSManager factory method for creating a context on the acceptor's side has the following signature:

GSSContext createContext(GSSCredential myCred);

If you pass null for the GSSCredential argument, as SampleServer does, the default credentials are used. The context is instantiated via the following:

  GSSContext context = manager.createContext((GSSCredential)null);

SampleServer Context Establishment Loop

After SampleServer has instantiated a GSSContext, it can establish the security context with SampleClient. To do so, SampleServer has a loop that continues until the context is established. Each loop iteration does the following:

  1. Receives a token from SampleClient. This token is the result of a SampleClient initSecContext call.

  2. Calls the context's acceptSecContext method, passing it the token just received.

  3. If acceptSecContext returns a token, then SampleServer sends this token to SampleClient and then starts the next loop iteration if the context is not yet established.

The tokens returned by acceptSecContext or received from SampleClient are placed in a byte array.

The acceptSecContext arguments are a byte array containing a token, the starting offset into that array of where the token begins, and the token length.

To exchange tokens with SampleClient, SampleServer uses the DataInputStream inStream and DataOutputStream outStream it previously set up using the input and output streams for the socket connection made with SampleClient.

Here is the SampleServer context establishment loop:

byte[] token = null;

while (!context.isEstablished()) {

    token = new byte[inStream.readInt()];
    System.out.println("Will read input token of size "
       + token.length
       + " for processing by acceptSecContext");
    inStream.readFully(token);

    token = context.acceptSecContext(token, 0, token.length);

    // Send a token to the peer if one was generated by
    // acceptSecContext
    if (token != null) {
        System.out.println("Will send token of size "
           + token.length
           + " from acceptSecContext.");
        outStream.writeInt(token.length);
        outStream.write(token);
        outStream.flush();
    }
}

System.out.print("Context Established! ");
System.out.println("Client is " + context.getSrcName());
System.out.println("Server is " + context.getTargName());
if (context.getMutualAuthState())
    System.out.println("Mutual authentication took place!");

Exchanging Messages Securely

Once a security context has been established between SampleClient and SampleServer, they can use the context to securely exchange messages.

  • GSSContext Methods for Message Exchange

  • The SampleClient and SampleServer Message Exchanges

GSSContext Methods for Message Exchange

Two types of methods exist for preparing messages for secure exchange: wrap and getMIC. There are actually two wrap methods (and two getMIC methods), where the differences between the two are the indication of where the input message is (a byte array or an input stream) and where the output should go (to a byte array return value or to an output stream).

These methods for preparing messages for exchange, and the corresponding methods for interpretation by the peer of the resulting tokens, are described below.

wrap

The wrap method is the primary method for message exchanges.

The signature for the wrap method called by SampleClient is the following:

byte[] wrap (byte[] inBuf, int offset, interface len,
                MessageProp msgProp)

You pass wrap a message (in inBuf), the offset into inBuf where the message begins (offset), and the length of the message (len). You also pass a MessageProp, which is used to indicate the desired QOP (Quality-of-Protection) and to specify whether or not privacy (encryption) is desired. A QOP value selects the cryptographic integrity and encryption (if requested) algorithm(s) to be used. The algorithms corresponding to various QOP values are specified by the provider of the underlying mechanism. For example, the values for Kerberos V5 are defined in RFC 1964 in section 4.2. It is common to specify 0 as the QOP value to request the default QOP.

The wrap method returns a token containing the message and a cryptographic Message Integrity Code (MIC) over it. The message placed in the token will be encrypted if the MessageProp indicates privacy is desired. You do not need to know the format of the returned token; it should be treated as opaque data. You send the returned token to your peer application, which calls the unwrap method to "unwrap" the token to get the original message and to verify its integrity.

getMIC

If you simply want to get a token containing a cryptographic Message Integrity Code (MIC) for a supplied message, you call getMIC. A sample reason you might want to do this is to confirm with your peer that you both have the same data, by just transporting a MIC for that data without incurring the cost of transporting the data itself to each other.

The signature for the getMIC method called by SampleServer is the following:

byte[] getMIC (byte[] inMsg, int offset, int len,
            MessageProp msgProp)

You pass getMIC a message (in inMsg), the offset into inMsg where the message begins (offset), and the length of the message (len). You also pass a MessageProp, which is used to indicate the desired QOP (Quality-of-Protection). It is common to specify 0 as the QOP value to request the default QOP.

If you have a token created by getMIC and the message used to calculate the MIC (or a message purported to be the message on which the MIC was calculated), you can call the verifyMIC method to verify the MIC for the message. If the verification is successful (that is, if a GSSException is not thrown), it proves that the message is exactly the same as it was when the MIC was calculated. A peer receiving a message from an application typically expects a MIC as well, so that they can verify the MIC and be assured the message has not been modified or corrupted in transit. Note: If you know ahead of time that you will want the MIC as well as the message then it is more convenient to use the wrap and unwrap methods. But there could be situations where the message and the MIC are received separately.

The signature for the verifyMIC corresponding to the getMIC shown above is

void verifyMIC (byte[] inToken, int tokOffset, int tokLen,
        byte[] inMsg, int msgOffset, int msgLen,
        MessageProp msgProp);

This verifies the MIC contained in the inToken (of length tokLen, starting at offset tokOffset) over the message contained in inMsg (of length msgLen, starting at offset msgOffset). The MessageProp is used by the underlying mechanism to return information to the caller, such as the QOP indicating the strength of protection that was applied to the message.

The SampleClient and SampleServer Message Exchanges

The message exchanges between SampleClient and SampleServer are summarized below, followed by the coding details.

These steps are the "standard" steps used for verifying a GSS-API client and server. A group at MIT has written a GSS-API client and a GSS-API server that have become fairly popular test programs for checking interoperability between different implementations of the GSS-API library. (These GSS-API sample applications can be downloaded as a part of the Kerberos distribution available from MIT at http://web.mit.edu/kerberos.) This client and server from MIT follow the protocol that once the context is established, the client sends a message across and it expects back the MIC on that message. If you implement a GSS-API library, it is common practice to test it by running either the client or server using your library implementation against a corresponding peer server or client that uses another GSS-API library implementation. If both library implementations conform to the standards, then the two peers will be able to communicate successfully.

One implication of testing your client or server against ones written in C (like the MIT ones) is the way tokens must be exchanged. C implementations of GSS-API do not include stream-based methods. In the absence of stream-based methods on your peer, when you write a token you must first write the number of bytes and then write the token. Similarly, when you are reading a token, you first read the number of bytes and then read the token. This is what SampleClient and SampleServer do.

Here is the summary of the SampleClient and SampleServer message exchanges:

  1. SampleClient calls wrap to encrypt and calculate a MIC for a message.

  2. SampleClient sends the token returned from wrap to SampleServer.

  3. SampleServer calls unwrap to obtain the original message and verify its integrity.

  4. SampleServer calls getMIC to calculate a MIC on the decrypted message.

  5. SampleServer sends the token returned by getMIC (which contains the MIC) to SampleClient.

  6. SampleClient calls verifyMIC to verify that the MIC sent by SampleServer is a valid MIC for the original message.

SampleClient Code to Encrypt the Message and Send It

The SampleClient code for encrypting a message, calculating a MIC for it, and sending the result to SampleServer is the following:

byte[] messageBytes = "Hello There!\0".getBytes();

/*
 * The first MessageProp argument is 0 to request
 * the default Quality-of-Protection.
 * The second argument is true to request
 * privacy (encryption of the message).
 */
MessageProp prop =  new MessageProp(0, true);

/*
 * Encrypt the data and send it across. Integrity protection
 * is always applied, irrespective of encryption.
 */
token = context.wrap(messageBytes, 0, messageBytes.length,
    prop);
System.out.println("Will send wrap token of size "
    + token.length);
outStream.writeInt(token.length);
outStream.write(token);
outStream.flush();

SampleServer Code to Unwrap Token, Calculate MIC, and Send It

The following SampleServer code reads the wrapped token sent by SampleClient and "unwraps" it to obtain the original message and have its integrity verified. The unwrapping in this case includes decryption since the message was encrypted.

Note: Here the integrity check is expected to succeed. But note that in general if an integrity check fails it signifies that the message was changed in transit. If the unwrap method encounters an integrity check failure, it throws a GSSException with major error code GSSException.BAD_MIC.

/*
 * Create a MessageProp which unwrap will use to return
 * information such as the Quality-of-Protection that was
 * applied to the wrapped token, whether or not it was
 * encrypted, etc. Since the initial MessageProp values
 * are ignored, it doesn't matter what they are set to.
 */
MessageProp prop = new MessageProp(0, false);

/*
 * Read the token. This uses the same token byte array
 * as that used during context establishment.
 */
token = new byte[inStream.readInt()];
System.out.println("Will read token of size "
    + token.length);
inStream.readFully(token);

byte[] bytes = context.unwrap(token, 0, token.length, prop);
String str = new String(bytes);
System.out.println("Received data \""
    + str + "\" of length " + str.length());
System.out.println("Encryption applied: "
    + prop.getPrivacy());

Next, SampleServer generates a MIC for the decrypted message and sends it to SampleClient. This is not really necessary but simply illustrates generating a MIC on the decrypted message, which should be exactly the same as the original message SampleClient wrapped and sent to SampleServer. When SampleServer generates this and sends it to SampleClient, and SampleClient verifies it, this proves to SampleClient that the decrypted message SampleServer has is in fact exactly the same as the original message from SampleClient.

/*
 * First reset the QOP of the MessageProp to 0
 * to ensure the default Quality-of-Protection
 * is applied.
 */
prop.setQOP(0);

token = context.getMIC(bytes, 0, bytes.length, prop);

System.out.println("Will send MIC token of size "
                   + token.length);
outStream.writeInt(token.length);
outStream.write(token);
outStream.flush();

SampleClient Code to Verify the MIC

The following SampleClient code reads the MIC calculated by SampleServer on the decrypted message and then verifies that the MIC is a MIC for the original message, proving that the decrypted message SampleServer has is the same as the original message:

token = new byte[inStream.readInt()];
System.out.println("Will read token of size " + token.length);
inStream.readFully(token);

/*
 * Recall messageBytes is the byte array containing
 * the original message and prop is the MessageProp
 * already instantiated by SampleClient.
 */
context.verifyMIC(token, 0, token.length,
          messageBytes, 0, messageBytes.length,
          prop);

System.out.println("Verified received MIC for message.");

Clean Up

When SampleClient and SampleServer have finished exchanging messages, they need to perform cleanup operations. Both contain the following code to
  • close the socket connection and

  • release system resources and cryptographic information stored in the context object and then invalidate the context.
socket.close();
context.dispose();

Kerberos User and Service Principal Names

Since the underlying authentication and secure communication technology used by this tutorial is Kerberos V5, we use Kerberos-style principal names wherever a user or service is called for.

For example, when you run SampleClient you are asked to provide your user name. Your Kerberos-style user name is simply the user name you were assigned for Kerberos authentication. It consists of a base user name (like "mjones") followed by an "@" and your realm (like "mjones@KRBNT-OPERATIONS.ABC.COM").

A server program like SampleServer is typically considered to offer a "service" and to be run on behalf of a particular "service principal." A service principal name for SampleServer is needed in several places:

  • When you run SampleServer, and SampleClient attempts a connection to it, the underlying Kerberos mechanism will attempt to authenticate to the Kerberos KDC. It prompts you to log in. You should log in as the appropriate service principal.

  • When you run SampleClient, one of the arguments is the service principal name. This is needed so SampleClient can initiate establishment of a security context with the appropriate service.

  • If the SampleClient and SampleServer programs were run with a security manager (they're not for this tutorial), the client and server policy files would each require a ServicePermission with name equal to the service principal name and action equal to "initiate" or "accept" (for initiating or accepting establishment of a security context).

Throughout this document, and in the accompanying login configuration file,

service_principal@your_realm
is used as a placeholder to be replaced by the actual name to be used in your environment. Any Kerberos principal can actually be used for the service principal name. So for the purposes of trying out this tutorial, you could use your user name as both the client user name and the service principal name.

In a production environment, system administrators typically like servers to be run as specific principals only and may assign a particular name to be used. Often the Kerberos-style service principal name assigned is of the form

service_name/machine_name@realm;

For example, an nfs service run on a machine named "raven" in the realm named "KRBNT-OPERATIONS.ABC.COM" could have the service principal name

nfs/raven@KRBNT-OPERATIONS.ABC.COM

Such multi-component names are not required, however. Single-component names, just like those of user principals, can be used. For example, an installation might use the same ftp service principal ftp@realm for all ftp servers in that realm, while another installation might have different ftp principals for different ftp servers, such as ftp/host1@realm and ftp/host2@realm on machines host1 and host2, respectively.

When the Realm is Required in Principal Names

If the realm of a user or service principal name is the default realm (see Kerberos Requirements), you can leave off the realm when you are logging into Kerberos (that is, when you are prompted for your username). Thus, for example, if your user name is "mjones@KRBNT-OPERATIONS.ABC.COM", and you run SampleClient, when it requests your user name you could just specify "mjones", leaving off the realm. The name is interpreted in the context of being a Kerberos principal name and the default realm is appended, as needed.

You can also leave off the realm if a principal name will be converted to a GSSName by a GSSManager createName method. For example, when you run SampleClient, one of the arguments is the server service principal name. You can specify the name without including the realm, because SampleClient passes the name to such a createName method, which appends the default realm as needed.

It is recommended that you always include realms when principal names are used in login configuration files and policy files, because the behavior of the parsers for such files may be implementation-dependent; they may or may not append the default realm before such names are utilized and subsequent actions may fail if there is no realm in the name.

The Login Configuration File

For this tutorial, we are letting the underlying Kerberos mechanism obtain credentials of the users running SampleClient and SampleServer, rather than invoking JAAS methods directly (as in the JAAS Authentication and JAAS Authorization tutorials) or indirectly (for example, via the Login utility described in the Use of JAAS Login Utility tutorial and in the Use of JAAS Login Utility and Java GSS-API for Secure Message Exchanges tutorial).

The default Kerberos mechanism implementation supplied by Sun Microsystems actually prompts for a Kerberos name and password and authenticates the specified user (or service) to the Kerberos KDC. The mechanism relies on JAAS to perform this authentication.

JAAS supports a pluggable authentication framework, meaning that any type of authentication module can be plugged under a calling application. A login configuration specifies the login module to be used for a particular application. The default JAAS implementation from Sun Microsystems requires that the login configuration information be specified in a file. (Note: Some other vendors might not have file-based implementations.) See JAAS Login Configuration File for information as to what a login configuration file is, what it contains, and how to specify which login configuration file should be used.

For this tutorial, the Kerberos login module com.sun.security.auth.module.Krb5LoginModule is specified in the configuration file. This login module prompts for a Kerberos name and password and attempts to authenticate to the Kerberos KDC.

Both SampleClient and SampleServer can use the same login configuration file, if that file contains two entries, one entry for the client side and one for the server side.

The bcsLogin.conf login configuration file used for this tutorial is the following:

com.sun.security.jgss.initiate  {
  com.sun.security.auth.module.Krb5LoginModule required;
};

com.sun.security.jgss.accept  {
  com.sun.security.auth.module.Krb5LoginModule required storeKey=true
};

Entries with these two names (com.sun.security.jgss.initiate and com.sun.security.jgss.accept) are used by Sun implementations of GSS-API mechanisms when they need new credentials. Since the mechanism used in this tutorial is the Kerberos V5 mechanism, a Kerberos login module will need to be invoked in order to obtain these credentials. Thus we list Krb5LoginModule as a required module in these entries. The com.sun.security.jgss.initiate entry specifies the configuration for the client side and the com.sun.security.jgss.accept entry for the server side.

The Krb5LoginModule succeeds only if the attempt to log in to the Kerberos KDC as a specified entity is successful. When running SampleClient or SampleServer, the user will be prompted for a name and password.

The SampleServer entry storeKey=true indicates that a secret key should be calculated from the password provided during login and it should be stored in the private credentials of the Subject created as a result of login. This key is subsequently utilized during mutual authentication when establishing a security context between SampleClient and SampleServer.

For information about all the possible options that can be passed to Krb5LoginModule, see the Krb5LoginModule documentation.

The useSubjectCredsOnly System Property

For this tutorial, we set the system property javax.security.auth.useSubjectCredsOnly to false, which allows us to relax the usual restriction of requiring a GSS mechanism to obtain necessary credentials from an existing Subject, set up by JAAS. When this restriction is relaxed, it allows the mechanism to obtain credentials from some vendor-specific location. For example, some vendors might choose to use the operating system's cache if one exists, while others might choose to read from a protected file on disk.

When this restriction is relaxed, Sun Microsystem's Kerberos mechanism still looks for the credentials in the Subject associated with the thread's access control context, but if it doesn't find any there, it performs JAAS authentication using a Kerberos module to obtain new ones. The Kerberos module prompts you for a Kerberos principal name and password. Note that Kerberos mechanism implementations from other vendors may behave differently when this property is set to false. Consult their documentation to determine their implementation's behavior.

Running the SampleClient and SampleServer Programs

To execute the SampleClient and SampleServer programs, do the following:

  • Prepare SampleServer for Execution

  • Prepare SampleClient for Execution

  • Execute SampleServer

  • Execute SampleClient

Prepare SampleServer for Execution

To prepare SampleServer for execution, do the following:

  1. Copy the following files into a directory accessible by the machine on which you will run SampleServer:

    • The SampleServer.java source file.
    • The bcsLogin.conf login configuration file.

  2. Compile SampleServer.java:
    javac SampleServer.java

Prepare SampleClient for Execution

To prepare SampleClient for execution, do the following:

  1. Copy the following files into a directory accessible by the machine on which you will run SampleClient:

    • The SampleClient.java source file.
    • The bcsLogin.conf login configuration file.

  2. Compile SampleClient.java:
    javac SampleClient.java

Execute SampleServer

It is important to execute SampleServer before SampleClient because SampleClient will try to make a socket connection to SampleServer and that will fail if SampleServer is not yet running and accepting socket connections.

To execute SampleServer, be sure to run it on the machine it is expected to be run on. This machine name (host name) is specified as an argument to SampleClient. The service principal name appears in several places, including the login configuration file and the policy files.

Go to the directory in which you have prepared SampleServer for execution. Execute SampleServer, specifying

  • by -Djava.security.krb5.realm=<your_realm> that your Kerberos realm is the one specified. For example, if your realm is "KRBNT-OPERATIONS.ABC.COM" you'd put -Djava.security.krb5.realm=KRBNT-OPERATIONS.ABC.COM.

  • by -Djava.security.krb5.kdc=<your_kdc> that your Kerberos KDC is the one specified. For example, if your KDC is "samplekdc.abc.com" you'd put -Djava.security.krb5.kdc=samplekdc.abc.com.

  • by -Djavax.security.auth.useSubjectCredsOnly=false that the underlying mechanism can decide how to get credentials. See The useSubjectCredsOnly System Property.

  • by -Djava.security.auth.login.config=bcsLogin.conf that the login configuration file to be used is bcsLogin.conf.

The only argument required by SampleServer is one specifying the port number to be used for listening for client connections. Choose a high port number unlikely to be used for anything else. An example would be something like 4444.

Below is the full command to use for both Microsoft Windows and Unix systems.

Important: In this command, you must replace <port_number> with an appropriate port number, <your_realm> with your Kerberos realm, and <your_kdc> with your Kerberos KDC.

Here is the command:

java -Djava.security.krb5.realm=<your_realm>
 -Djava.security.krb5.kdc=<your_kdc>
 -Djavax.security.auth.useSubjectCredsOnly=false
 -Djava.security.auth.login.config=bcsLogin.conf
 SampleServer <port_number>

The full command should appear on one line (or, on UNIX systems, on multiple lines where each line but the last is terminated with " \" indicating that there is more to come). Multiple lines are used here just for legibility. Since this command is very long, you may need to place it in a .bat file (for Windows) or a .sh file (for UNIX) and then run that file to execute the command.

The SampleServer code will listen for socket connections on the specified port. When prompted, type the Kerberos name and password for the service principal. The underlying Kerberos authentication mechanism specified in the login configuration file will log the service principal into Kerberos.

For login troubleshooting suggestions, see Troubleshooting.

Execute SampleClient

To execute SampleClient, first go to the directory in which you have prepared SampleClient for execution. Execute SampleClient, specifying

  • by -Djava.security.krb5.realm=<your_realm> that your Kerberos realm is the one specified.

  • by -Djava.security.krb5.kdc=<your_kdc> that your Kerberos KDC is the one specified.

  • by -Djavax.security.auth.useSubjectCredsOnly=false that the underlying mechanism can decide how to get credentials.

  • by -Djava.security.auth.login.config=bcsLogin.conf that the login configuration file to be used is bcsLogin.conf.

The SampleClient arguments are (1) the Kerberos name of the service principal that represents SampleServer, (2) the name of the host (machine) on which SampleServer is running, and (3) the port number on which SampleServer is listening for client connections.

Below is the full command to use for both Windows and Unix systems.

Important: In this command, you must replace <service_principal>, <host>, <port_number>, <your_realm>, and <your_kdc> with appropriate values (and note that the port number must be the same as the port number passed as an argument to SampleServer). These values need not be placed in quotes.

Here is the command:

java -Djava.security.krb5.realm=<your_realm>
 -Djava.security.krb5.kdc=<your_kdc>
 -Djavax.security.auth.useSubjectCredsOnly=false
 -Djava.security.auth.login.config=bcsLogin.conf
 SampleClient <service_principal> <host> <port_number>

Type the full command on one line. Multiple lines are used here for legibility. As with the command for executing SampleServer, if the command is too long to type directly into your command window, place it in a .bat file (Windows) or a .sh file (UNIX) and then execute that file.

When prompted, type your Kerberos user name and password. The underlying Kerberos authentication mechanism specified in the login configuration file will log you into Kerberos. The SampleClient code requests a socket connection with SampleServer. Once SampleServer accepts the connection, SampleClient and SampleServer establish a shared context and then exchange messages as described in this tutorial.

For login troubleshooting suggestions, see Troubleshooting.


When to use Java GSS-API vs. JSSE

Java GSS-API and JSSE provide you with the same basic set of security features:

  1. Client-server authentication

  2. Encryption and integrity protection of transmitted data

However, there are some key difference between the two. This document lists some of them to help you decide which might be more appropriate in your environment:

  1. Kerberos Single Sign-On Support

    In the Java 2 Standard Edition, GSS-API contains support for Kerberos as a mandatory security mechanism. This means that if your desktop has Kerberos support, you can write Java GSS-API based applications that never prompt the user for a password.

    At present JSSE does not support cipher suites to use Kerberos-based authentication. Support for such a cipher suite is dependent on its standarization in the TLS protocol at the Internet Engineering Task Force (IETF).

  2. Communications API

    JSSE supports a socket-based API. JSSE sockets extend the socket classes found in java.net and JSSE socket factories extend the socket factories found in javax.net. Thus, if your application is written such that its security needs to be configured via a socket factory, then JSSE might be more appropriate for you. JSSE sockets need to use some reliable transport. Typically, implementations use TCP.

    Java GSS-API, on the other hand, is a token-based API that relies on the application to do the communication. This means that the application can use TCP sockets, UDP datagrams, or any other channel that will allow it to transport Java GSS-API generated tokens. If your application has varying communication protocol needs, then Java GSS-API might be more appropriate for you. Java GSS-API can read and write its tokens using input and output streams. However, you will need to set up the streams yourself.

  3. Credential Delegation

    Java GSS-API allows the client to delegate its credentials to the server when using Kerberos. If your application will be deployed in a multi-tier environment where intermediaries need to impersonate clients when talking to backend layers, Java GSS-API might be more appropriate for you.

  4. Selective Encryption

    Because Java GSS-API is token-based, you can choose to selectively encrypt certain messages but not all. If your application needs to intersperse plaintext and ciphertext messages, Java GSS-API might be more appropriate for you.

  5. Protocol Requirements

    JSSE provides an implementation of the TLS protocol defined in RFC 2246. Java GSS-API provides an implementation of the GSS-API framework defined in RFC 2853, as well as an implementation of the Kerberos Version 5 mechanism defined in RFC 1964. (On Microsoft Windows platforms, this may be known as SSPI with Kerberos.) Some servers such as HTTPS servers will require you to use TLS, in which case JSSE will be appropriate for you. Other servers such as LDAP servers using SASL might need GSS-API with Kerberos, in which case Java GSS-API will be appropriate for you.


Debugging SSL/TLS Connections

Understanding SSL/TLS connection problems can sometimes be difficult, especially when it is not clear what messages are actually being sent and received. The SunJSSE has a built-in debug facility and is activated by the System property javax.net.debug.

What follows is a brief example how to read the debug output. Please be aware that the output is non-standard, and may change from release to release. We are using the default SunJSSE X509KeyManager and X509TrustManager which prints debug information.

This example assumes a basic understanding of the SSL/TLS protocol. Please see the The SSL Protocol Overview section of the JSSE Reference Guide for more information on the protocols (handshake messages, etc.).

In this example, we connect using the SSLSocketClientWithClientAuth sample application to a simple HTTPS server that requires client authentication, then send a HTTPS request and receive the reply.

    java  -Djavax.net.debug=all  \
    -Djavax.net.ssl.trustStore=trustStore
    SSLSocketClientWithClientAuth bongos 2001 /index.html
First, the X509KeyManager is initialized and discovers there is one keyEntry in the supplied KeyStore for a subject called "duke". If a server requests a client to authenticate itself, the X509KeyManager will search its list of keyEntries for an appropriate credential.
***
found key for : duke
chain [0] = [
[
  Version: V1
  Subject: CN=Duke, OU=Java Software, O="Sun Microsystems, Inc.",
  L=Cupertino, ST=CA, C=US
  Signature Algorithm: MD5withRSA, OID = 1.2.840.113549.1.1.4

  Key:  Sun RSA public key, 1024 bits
  modulus: 134968166047563266914058280571444028986498087544923991226919517
  667593269213420979048109900052353578998293280426361122296881234393722020
  704208851688212064483570055963805034839797994154526862998272017486468599
  962268346037652120279791547218281230795146025359480589335682217749874703
  510467348902637769973696151441
  public exponent: 65537
  Validity: [From: Tue May 22 16:46:46 PDT 2001,
               To: Sun May 22 16:46:46 PDT 2011]
  Issuer: CN=Duke, OU=Java Software, O="Sun Microsystems, Inc.",
  L=Cupertino, ST=CA, C=US
  SerialNumber: [    3b0afa66]

]
  Algorithm: [MD5withRSA]
  Signature:
0000: 5F B5 62 E9 A0 26 1D 8E   A2 7E 7C 02 08 36 3A 3E  _.b..&.......6:>
0010: C9 C2 45 03 DD F9 BC 06   FC 25 CF 30 92 91 B1 4E  ..E......%.0...N
0020: 62 17 08 48 14 68 80 CF   DD 89 11 EA 92 7F CE DD  b..H.h..........
0030: B4 FD 12 A8 71 C7 9E D7   C3 D0 E3 BD BB DE 20 92  ....q......... .
0040: C2 3B C8 DE CB 25 23 C0   8B B6 92 B9 0B 64 80 63  .;...%#......d.c
0050: D9 09 25 2D 7A CF 0A 31   B6 E9 CA C1 37 93 BC 0D  ..%-z..1....7...
0060: 4E 74 95 4F 58 31 DA AC   DF D8 BD 89 BD AF EC C8  Nt.OX1..........
0070: 2D 18 A2 BC B2 15 4F B7   28 6F D3 00 E1 72 9B 6C  -.....O.(o...r.l

]
***
The X509TrustManager is next initialized, and finds a certificate for a Certificate Authority (CA) named "JSSE Test CA". Any server presenting valid credentials signed by this CA will be trusted.
trustStore is: trustkeys
trustStore type is : jks
trustStore provider is :
init truststore
adding as trusted cert:
  Subject: CN=JSSE Test CA, OU=JWS, O=Sun,
      L=Santa Clara, ST=CA, C=US
  Issuer:  CN=JSSE Test CA, OU=JWS, O=Sun,
      L=Santa Clara, ST=CA, C=US
  Algorithm: RSA; Serial number: 0x0
  Valid from Mon Jul 19 13:30:15 PDT 2004 until Fri Dec 05 12:30:15 PST 2031
We finish some additional initialization code, and after this, we are now finally ready to make the connection to the server.
trigger seeding of SecureRandom
done seeding SecureRandom
export control - checking the cipher suites
export control - no cached value available...
export control - storing legal entry into cache...
%% No cached client session
The connection to the server is made, and we see the initial ClientHello message, which contains:
  • random information to initialize the cryptographic routines,
  • the SessionID, which if non-null, would be used in reestablishing a previous session,
  • the list of ciphersuites that the client requests,
  • and no compression algorithms.
This is followed by the output of various filters, such as encapsulating the TLSv1 header into the SSLv2Hello header format (See setEnabledProtocols()).
*** ClientHello, TLSv1
RandomCookie:  GMT: 1073239164 bytes = { 10, 80, 71, 86, 124, 135, 104,
151, 72, 153, 70, 28, 97, 232, 160, 217, 146, 178, 87, 255, 122, 147, 83,
197, 60, 187, 227, 76 }
Session ID:  {}
Cipher Suites: [SSL_RSA_WITH_RC4_128_MD5, SSL_RSA_WITH_RC4_128_SHA,
TLS_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_128_CBC_SHA,
TLS_DHE_DSS_WITH_AES_128_CBC_SHA, SSL_RSA_WITH_3DES_EDE_CBC_SHA,
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA, SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA,
SSL_RSA_WITH_DES_CBC_SHA, SSL_DHE_RSA_WITH_DES_CBC_SHA,
SSL_DHE_DSS_WITH_DES_CBC_SHA, SSL_RSA_EXPORT_WITH_RC4_40_MD5,
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA, SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA,
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA]
Compression Methods:  { 0 }
***
[write] MD5 and SHA1 hashes:  len = 73
0000: 01 00 00 45 03 01 40 F8   54 7C 0A 50 47 56 7C 87  ...E..@.T..PGV..
0010: 68 97 48 99 46 1C 61 E8   A0 D9 92 B2 57 FF 7A 93  h.H.F.a.....W.z.
0020: 53 C5 3C BB E3 4C 00 00   1E 00 04 00 05 00 2F 00  S.<..L........ /.="/." 0030:="0030:" 33="33" 00="00" 32="32" 00="00" 0A="0A" 00="00" 16="16" 00="00" 13="13" 00="00" 09="09" 00="00" 15="15" 00="00" 12="12" 00="00" 3.2.............="3.2............." 0040:="0040:" 03="03" 00="00" 08="08" 00="00" 14="14" 00="00" 11="11" 01="01" 00="00" .........="........." main,="main," WRITE:="WRITE:" TLSv1="TLSv1" Handshake,="Handshake," length="73" [write]="[write]" MD5="MD5" and="and" SHA1="SHA1" hashes:="hashes:" len="98" 0000:="0000:" 01="01" 03="03" 01="01" 00="00" 39="39" 00="00" 00="00" 00="00" 20="20" 00="00" 00="00" 04="04" 01="01" 00="00" 80="80" 00="00" ....9...="....9..." .......="......." 0010:="0010:" 00="00" 05="05" 00="00" 00="00" 2F="2F" 00="00" 00="00" 33="33" 00="00" 00="00" 32="32" 00="00" 00="00" 0A="0A" 07="07" 00="00" ..../..3..2.....="..../..3..2....." 0020:="0020:" C0="C0" 00="00" 00="00" 16="16" 00="00" 00="00" 13="13" 00="00" 00="00" 09="09" 06="06" 00="00" 40="40" 00="00" 00="00" 15="15" ............@...="............@..." 0030:="0030:" 00="00" 00="00" 12="12" 00="00" 00="00" 03="03" 02="02" 00="00" 80="80" 00="00" 00="00" 08="08" 00="00" 00="00" 14="14" 00="00" ................="................" 0040:="0040:" 00="00" 11="11" 40="40" F8="F8" 54="54" 7C="7C" 0A="0A" 50="50" 47="47" 56="56" 7C="7C" 87="87" 68="68" 97="97" 48="48" 99="99" ..@.T..PGV..h.H.="..@.T..PGV..h.H." 0050:="0050:" 46="46" 1C="1C" 61="61" E8="E8" A0="A0" D9="D9" 92="92" B2="B2" 57="57" FF="FF" 7A="7A" 93="93" 53="53" C5="C5" 3C="3C" BB="BB" F.a.....W.z.S.<.="F.a.....W.z.S.<." 0060:="0060:" E3="E3" 4C="4C" .L=".L" main, WRITE: SSLv2 client hello message, length = 98
Section labeled "[Raw write]" represent the actual data sent to the raw output object (in this case, an OutputStream).
[Raw write]: length = 100
0000: 80 62 01 03 01 00 39 00   00 00 20 00 00 04 01 00  .b....9... .....
0010: 80 00 00 05 00 00 2F 00   00 33 00 00 32 00 00 0A  ....../..3..2...
0020: 07 00 C0 00 00 16 00 00   13 00 00 09 06 00 40 00  ..............@.
0030: 00 15 00 00 12 00 00 03   02 00 80 00 00 08 00 00  ................
0040: 14 00 00 11 40 F8 54 7C   0A 50 47 56 7C 87 68 97  ....@.T..PGV..h.
0050: 48 99 46 1C 61 E8 A0 D9   92 B2 57 FF 7A 93 53 C5  H.F.a.....W.z.S.
0060: 3C BB E3 4C                                        <..L
After sending the initial ClientHello, we wait for the server's response, a ServerHello. "[Raw read]" displays the raw data read from the input device (InputStream), before any processing has been performed.
[Raw read]: length = 5
0000: 16 03 01 06 F0                                     .....
[Raw read]: length = 1776
0000: 02 00 00 46 03 01 40 FC   31 10 79 AB 17 66 FA 8B  ...F..@.1.y..f..
0010: 3F AA FD 5E 48 23 FA 90   31 D8 3C B9 A3 2C 8C F5  ?..^H#..1.<..,.. 0020:="0020:" E9="E9" 81="81" 9B="9B" A2="A2" 63="63" 6C="6C" 20="20" 40="40" FC="FC" 31="31" 10="10" BD="BD" 8D="8D" A5="A5" 91="91" 06="06" ....cl="....cl" @.1......="@.1......" 0030:="0030:" 8B="8B" E1="E1" E6="E6" 80="80" C6="C6" 5A="5A" 5C="5C" D9="D9" 8D="8D" 0A="0A" AE="AE" CA="CA" 58="58" 4A="4A" BA="BA" 36="36" .....Z\.....XJ.6=".....Z\.....XJ.6" 0040:="0040:" B1="B1" 3D="3D" 04="04" 8D="8D" 82="82" 21="21" B4="B4" 00="00" 04="04" 00="00" 0B="0B" 00="00" 06="06" 1B="1B" 00="00" 06="06" .="...!.........." 0050:="0050:" 18="18" 00="00" 03="03" 11="11" 30="30" 82="82" 03="03" 0D="0D" 30="30" 82="82" 02="02" 76="76" A0="A0" 03="03" 02="02" 01="01" ....0...0..v....="....0...0..v...." 0060:="0060:" 02="02" 02="02" 01="01" 01="01" 30="30" 0D="0D" 06="06" 09="09" 2A="2A" 86="86" 48="48" 86="86" F7="F7" 0D="0D" 01="01" 01="01" ....0...*.H.....="....0...*.H....." 0070:="0070:" 04="04" 05="05" 00="00" 30="30" 63="63" 31="31" 0B="0B" 30="30" 09="09" 06="06" 03="03" 55="55" 04="04" 06="06" 13="13" 02="02" ...0c1.0...U....="...0c1.0...U...." 0080:="0080:" 55="55" 53="53" 31="31" 0B="0B" 30="30" 09="09" 06="06" 03="03" 55="55" 04="04" 08="08" 13="13" 02="02" 43="43" 41="41" 31="31" US1.0...U....CA1="US1.0...U....CA1" 0090:="0090:" 14="14" 30="30" 12="12" 06="06" 03="03" 55="55" 04="04" 07="07" 13="13" 0B="0B" 53="53" 61="61" 6E="6E" 74="74" 61="61" 20="20" .0...U....Santa=".0...U....Santa" 00A0:="00A0:" 43="43" 6C="6C" 61="61" 72="72" 61="61" 31="31" 0C="0C" 30="30" 0A="0A" 06="06" 03="03" 55="55" 04="04" 0A="0A" 13="13" 03="03" Clara1.0...U....="Clara1.0...U...." 00B0:="00B0:" 53="53" 75="75" 6E="6E" 31="31" 0C="0C" 30="30" 0A="0A" 06="06" 03="03" 55="55" 04="04" 0B="0B" 13="13" 03="03" 4A="4A" 57="57" Sun1.0...U....JW="Sun1.0...U....JW" 00C0:="00C0:" 53="53" 31="31" 15="15" 30="30" 13="13" 06="06" 03="03" 55="55" 04="04" 03="03" 13="13" 0C="0C" 4A="4A" 53="53" 53="53" 45="45" S1.0...U....JSSE="S1.0...U....JSSE" 00D0:="00D0:" 20="20" 54="54" 65="65" 73="73" 74="74" 20="20" 43="43" 41="41" 30="30" 1E="1E" 17="17" 0D="0D" 30="30" 34="34" 30="30" 37="37" Test="Test" CA0...0407="CA0...0407" 00E0:="00E0:" 31="31" 39="39" 32="32" 30="30" 33="33" 30="30" 35="35" 31="31" 5A="5A" 17="17" 0D="0D" 33="33" 31="31" 31="31" 32="32" 30="30" 19203051Z..31120="19203051Z..31120" 00F0:="00F0:" 35="35" 32="32" 30="30" 33="33" 30="30" 35="35" 31="31" 5A="5A" 30="30" 48="48" 31="31" 0B="0B" 30="30" 09="09" 06="06" 03="03" 5203051Z0H1.0...="5203051Z0H1.0..." 0100:="0100:" 55="55" 04="04" 06="06" 13="13" 02="02" 55="55" 53="53" 31="31" 0B="0B" 30="30" 09="09" 06="06" 03="03" 55="55" 04="04" 08="08" U....US1.0...U..="U....US1.0...U.." 0110:="0110:" 13="13" 02="02" 43="43" 41="41" 31="31" 0C="0C" 30="30" 0A="0A" 06="06" 03="03" 55="55" 04="04" 0A="0A" 13="13" 03="03" 53="53" ..CA1.0...U....S="..CA1.0...U....S" 0120:="0120:" 75="75" 6E="6E" 31="31" 0D="0D" 30="30" 0B="0B" 06="06" 03="03" 55="55" 04="04" 0B="0B" 13="13" 04="04" 4A="4A" 61="61" 76="76" un1.0...U....Jav="un1.0...U....Jav" 0130:="0130:" 61="61" 31="31" 0F="0F" 30="30" 0D="0D" 06="06" 03="03" 55="55" 04="04" 03="03" 13="13" 06="06" 62="62" 6F="6F" 6E="6E" 67="67" a1.0...U....bong="a1.0...U....bong" 0140:="0140:" 6F="6F" 73="73" 30="30" 81="81" 9F="9F" 30="30" 0D="0D" 06="06" 09="09" 2A="2A" 86="86" 48="48" 86="86" F7="F7" 0D="0D" 01="01" os0..0...*.H....="os0..0...*.H...." 0150:="0150:" 01="01" 01="01" 05="05" 00="00" 03="03" 81="81" 8D="8D" 00="00" 30="30" 81="81" 89="89" 02="02" 81="81" 81="81" 00="00" CC="CC" ........0.......="........0......." 0160:="0160:" 09="09" 74="74" CB="CB" 43="43" AB="AB" 6D="6D" ED="ED" F6="F6" 35="35" AA="AA" 0E="0E" 49="49" 29="29" D9="D9" E0="E0" F0="F0" .t.C.m..5..I)...=".t.C.m..5..I)..." 0170:="0170:" A1="A1" D5="D5" E2="E2" 3E="3E" 8F="8F" 5E="5E" C5="C5" CE="CE" F4="F4" DE="DE" C1="C1" A4="A4" F3="F3" CB="CB" 8C="8C" 45="45" ...="...">.^.........E
0180: 0B 0F 6E 21 E1 00 65 CB   3C D1 5C EF 6A FB 5D 96  ..n!..e.<.\.j.]. 0190:="0190:" 93="93" F4="F4" 71="71" 41="41" 41="41" 45="45" FF="FF" 37="37" 86="86" 4C="4C" AB="AB" F9="F9" EA="EA" 9A="9A" 3F="3F" A5="A5" ..qAAE.7.L....?.="..qAAE.7.L....?." 01A0:="01A0:" 82="82" 60="60" BF="BF" 0A="0A" 81="81" 84="84" C9="C9" 3E="3E" AC="AC" 0F="0F" 3D="3D" 20="20" 3D="3D" AC="AC" A0="A0" 69="69" .`.....=".`.....">..= =..i
01B0: EF CA 4A A7 94 AD C8 A5   CE 37 66 52 D1 25 43 CB  ..J......7fR.%C.
01C0: 10 44 07 1E 93 74 D9 68   01 D7 06 48 C9 0D 52 2D  .D...t.h...H..R-
01D0: D5 6A 2E A6 48 4C 59 E2   5C C6 C1 5C C8 4C 1B 02  .j..HLY.\..\.L..
01E0: 03 01 00 01 A3 81 EB 30   81 E8 30 09 06 03 55 1D  .......0..0...U.
01F0: 13 04 02 30 00 30 2C 06   09 60 86 48 01 86 F8 42  ...0.0,..`.H...B
0200: 01 0D 04 1F 16 1D 4F 70   65 6E 53 53 4C 20 47 65  ......OpenSSL Ge
0210: 6E 65 72 61 74 65 64 20   43 65 72 74 69 66 69 63  nerated Certific
0220: 61 74 65 30 1D 06 03 55   1D 0E 04 16 04 14 58 D7  ate0...U......X.
0230: 3A A9 37 AA 3E 14 27 FC   EC CC 45 08 04 8E 2A 8B  :.7.>.'...E...*.
0240: 77 28 30 81 8D 06 03 55   1D 23 04 81 85 30 81 82  w(0....U.#...0..
0250: 80 14 08 A3 7E 35 96 15   FA B0 F5 1B 5F CD 4F 54  .....5......_.OT
0260: EF 31 33 70 E4 A7 A1 67   A4 65 30 63 31 0B 30 09  .13p...g.e0c1.0.
0270: 06 03 55 04 06 13 02 55   53 31 0B 30 09 06 03 55  ..U....US1.0...U
0280: 04 08 13 02 43 41 31 14   30 12 06 03 55 04 07 13  ....CA1.0...U...
0290: 0B 53 61 6E 74 61 20 43   6C 61 72 61 31 0C 30 0A  .Santa Clara1.0.
02A0: 06 03 55 04 0A 13 03 53   75 6E 31 0C 30 0A 06 03  ..U....Sun1.0...
02B0: 55 04 0B 13 03 4A 57 53   31 15 30 13 06 03 55 04  U....JWS1.0...U.
02C0: 03 13 0C 4A 53 53 45 20   54 65 73 74 20 43 41 82  ...JSSE Test CA.
02D0: 01 00 30 0D 06 09 2A 86   48 86 F7 0D 01 01 04 05  ..0...*.H.......
02E0: 00 03 81 81 00 05 3E 17   DA F2 05 CB 4E 9E BF 12  ......>.....N...
02F0: CE 13 76 FF B2 FB 7F 9C   3D 45 28 43 6C 98 28 E3  ..v.....=E(Cl.(.
0300: 92 17 C2 C6 F1 62 CA 60   C2 B0 EC E6 7E 4C 2F C2  .....b.`.....L/.
0310: 40 FE 06 CB 34 60 B1 F4   26 1C E8 46 39 24 E1 8A  @...4`..&..F9$..
0320: 71 F2 13 90 A4 0A 7B 0B   13 AB 51 68 53 D9 7A 31  q.........QhS.z1
0330: 5A C1 7E 3C 44 2C 49 70   57 25 F9 18 FE 5D A5 42  Z..a.).1F....'y@v
0350: 97 B6 25 19 BE 6C 6A 92   DC EF 11 BE E7 4A FF 2A  ..%..lj......J.*
0360: E6 D6 AC 39 31 00 03 01   30 82 02 FD 30 82 02 66  ...91...0...0..f
0370: A0 03 02 01 02 02 01 00   30 0D 06 09 2A 86 48 86  ........0...*.H.
0380: F7 0D 01 01 04 05 00 30   63 31 0B 30 09 06 03 55  .......0c1.0...U
0390: 04 06 13 02 55 53 31 0B   30 09 06 03 55 04 08 13  ....US1.0...U...
03A0: 02 43 41 31 14 30 12 06   03 55 04 07 13 0B 53 61  .CA1.0...U....Sa
03B0: 6E 74 61 20 43 6C 61 72   61 31 0C 30 0A 06 03 55  nta Clara1.0...U
03C0: 04 0A 13 03 53 75 6E 31   0C 30 0A 06 03 55 04 0B  ....Sun1.0...U..
03D0: 13 03 4A 57 53 31 15 30   13 06 03 55 04 03 13 0C  ..JWS1.0...U....
03E0: 4A 53 53 45 20 54 65 73   74 20 43 41 30 1E 17 0D  JSSE Test CA0...
03F0: 30 34 30 37 31 39 32 30   33 30 31 35 5A 17 0D 33  040719203015Z..3
0400: 31 31 32 30 35 32 30 33   30 31 35 5A 30 63 31 0B  11205203015Z0c1.
0410: 30 09 06 03 55 04 06 13   02 55 53 31 0B 30 09 06  0...U....US1.0..
0420: 03 55 04 08 13 02 43 41   31 14 30 12 06 03 55 04  .U....CA1.0...U.
0430: 07 13 0B 53 61 6E 74 61   20 43 6C 61 72 61 31 0C  ...Santa Clara1.
0440: 30 0A 06 03 55 04 0A 13   03 53 75 6E 31 0C 30 0A  0...U....Sun1.0.
0450: 06 03 55 04 0B 13 03 4A   57 53 31 15 30 13 06 03  ..U....JWS1.0...
0460: 55 04 03 13 0C 4A 53 53   45 20 54 65 73 74 20 43  U....JSSE Test C
0470: 41 30 81 9F 30 0D 06 09   2A 86 48 86 F7 0D 01 01  A0..0...*.H.....
0480: 01 05 00 03 81 8D 00 30   81 89 02 81 81 00 9A 0A  .......0........
0490: B6 45 66 D5 DE 4A D9 3C   8C AC A6 B5 A5 88 B4 CF  .Ef..J.<........ 04A0:="04A0:" 14="14" E1="E1" A6="A6" 1B="1B" 25="25" 25="25" 4F="4F" 44="44" C9="C9" 1F="1F" 22="22" 38="38" 32="32" 29="29" CF="CF" A1="A1" ....%%OD.."82)..="....%%OD.."82).." 04B0:="04B0:" 7C="7C" 18="18" 30="30" 93="93" DC="DC" 2B="2B" EC="EC" 2B="2B" 67="67" EE="EE" 2E="2E" 08="08" 66="66" 2D="2D" 0F="0F" 47="47" ..0..+.+g...f-.G="..0..+.+g...f-.G" 04C0:="04C0:" E0="E0" 12="12" 3A="3A" DC="DC" E0="E0" 03="03" E9="E9" 65="65" 16="16" F6="F6" 18="18" C6="C6" 16="16" 14="14" 56="56" 24="24" ..:....e......V$="..:....e......V$" 04D0:="04D0:" 55="55" 7D="7D" 32="32" 3E="3E" F9="F9" 66="66" A2="A2" DD="DD" 55="55" EB="EB" 4D="4D" 0A="0A" 67="67" C7="C7" 5D="5D" 21="21" U.2="U.2">.f..U.M.g.]!
04E0: 9B 29 EA 2E 51 C5 83 A3   55 FF 35 CA A6 99 8F 46  .)..Q...U.5....F
04F0: F8 8E 56 BB A2 B1 39 83   D8 61 42 79 E0 95 78 FA  ..V...9..aBy..x.
0500: C6 E3 65 B0 FD 74 2D 64   51 71 04 F2 A1 91 02 03  ..e..t-dQq......
0510: 01 00 01 A3 81 C0 30 81   BD 30 1D 06 03 55 1D 0E  ......0..0...U..
0520: 04 16 04 14 08 A3 7E 35   96 15 FA B0 F5 1B 5F CD  .......5......_.
0530: 4F 54 EF 31 33 70 E4 A7   30 81 8D 06 03 55 1D 23  OT.13p..0....U.#
0540: 04 81 85 30 81 82 80 14   08 A3 7E 35 96 15 FA B0  ...0.......5....
0550: F5 1B 5F CD 4F 54 EF 31   33 70 E4 A7 A1 67 A4 65  .._.OT.13p...g.e
0560: 30 63 31 0B 30 09 06 03   55 04 06 13 02 55 53 31  0c1.0...U....US1
0570: 0B 30 09 06 03 55 04 08   13 02 43 41 31 14 30 12  .0...U....CA1.0.
0580: 06 03 55 04 07 13 0B 53   61 6E 74 61 20 43 6C 61  ..U....Santa Cla
0590: 72 61 31 0C 30 0A 06 03   55 04 0A 13 03 53 75 6E  ra1.0...U....Sun
05A0: 31 0C 30 0A 06 03 55 04   0B 13 03 4A 57 53 31 15  1.0...U....JWS1.
05B0: 30 13 06 03 55 04 03 13   0C 4A 53 53 45 20 54 65  0...U....JSSE Te
05C0: 73 74 20 43 41 82 01 00   30 0C 06 03 55 1D 13 04  st CA...0...U...
05D0: 05 30 03 01 01 FF 30 0D   06 09 2A 86 48 86 F7 0D  .0....0...*.H...
05E0: 01 01 04 05 00 03 81 81   00 73 6A 46 A2 05 E3 D8  .........sjF....
05F0: 6E 5C F4 18 A2 74 BC CF   EB 0C 5B FF 81 1C 28 85  n\...t....[...(.
0600: C7 FA E4 ED 5C 4F 71 22   FB 26 E3 01 3D 0C 10 AA  ....\Oq".&..=...
0610: BB 3E 90 ED 0E 1F 0C 9B   B1 8C 49 6A 51 E4 C3 52  .>........IjQ..R
0620: D6 FB 42 6C B4 A9 A9 57   A5 84 00 42 6D 37 37 6D  ..Bl...W...Bm77m
0630: C7 6C 23 BC DC 60 D1 9D   6F B3 75 47 3A 15 33 1A  .l#..`..o.uG:.3.
0640: EC 90 09 9D F9 EB BD 88   96 E7 1D 41 BC 01 8D CA  ...........A....
0650: 88 D9 5B 04 09 8F 3E EA   C8 15 A0 AA 4E 85 95 AE  ..[...>.....N...
0660: 2F 0E 31 92 AC 3C FB 2F   C4 0D 00 00 7F 02 01 02  /.1..<. /........="/........" 0670:="0670:" 00="00" 7A="7A" 00="00" 78="78" 30="30" 76="76" 31="31" 0B="0B" 30="30" 09="09" 06="06" 03="03" 55="55" 04="04" 06="06" 13="13" .z.x0v1.0...U...=".z.x0v1.0...U..." 0680:="0680:" 02="02" 55="55" 53="53" 31="31" 0B="0B" 30="30" 09="09" 06="06" 03="03" 55="55" 04="04" 08="08" 13="13" 02="02" 43="43" 41="41" .US1.0...U....CA=".US1.0...U....CA" 0690:="0690:" 31="31" 12="12" 30="30" 10="10" 06="06" 03="03" 55="55" 04="04" 07="07" 13="13" 09="09" 43="43" 75="75" 70="70" 65="65" 72="72" 1.0...U....Cuper="1.0...U....Cuper" 06A0:="06A0:" 74="74" 69="69" 6E="6E" 6F="6F" 31="31" 1F="1F" 30="30" 1D="1D" 06="06" 03="03" 55="55" 04="04" 0A="0A" 13="13" 16="16" 53="53" tino1.0...U....S="tino1.0...U....S" 06B0:="06B0:" 75="75" 6E="6E" 20="20" 4D="4D" 69="69" 63="63" 72="72" 6F="6F" 73="73" 79="79" 73="73" 74="74" 65="65" 6D="6D" 73="73" 2C="2C" un="un" Microsystems,="Microsystems," 06C0:="06C0:" 20="20" 49="49" 6E="6E" 63="63" 2E="2E" 31="31" 16="16" 30="30" 14="14" 06="06" 03="03" 55="55" 04="04" 0B="0B" 13="13" 0D="0D" Inc.1.0...U....="Inc.1.0...U...." 06D0:="06D0:" 4A="4A" 61="61" 76="76" 61="61" 20="20" 53="53" 6F="6F" 66="66" 74="74" 77="77" 61="61" 72="72" 65="65" 31="31" 0D="0D" 30="30" Java="Java" Software1.0="Software1.0" 06E0:="06E0:" 0B="0B" 06="06" 03="03" 55="55" 04="04" 03="03" 13="13" 04="04" 44="44" 75="75" 6B="6B" 65="65" 0E="0E" 00="00" 00="00" 00="00" ...U....Duke....="...U....Duke...." main,="main," READ:="READ:" TLSv1="TLSv1" Handshake,="Handshake," length="1776"
The data is unpackaged, and if the message is in the SSL/TLS format, it is parsed into a ServerHello. If you connected to a non-SSL/TLS socket (plaintext?), the received data will not be in SSL/TLS format, and you'll have problems connecting.

The ServerHello specifies several things:

  • The server's random data, also used to initialize the cryptographic algorithms,
  • the identifier of this session (if the client wants to try to rejoin this session using a different connection, it can send this ID in its ClientHello. If the client session ID equals the server session ID, an abbreviated handshake takes place, and the previously established parameters are used),
  • the selected cipher suite,
  • and the compression method (none in this case).
Lastly note that the ServerHello has specified that the connection should use "TLSv1", rather than "SSLv3."

*** ServerHello, TLSv1
RandomCookie:  GMT: 1073492240 bytes = { 121, 171, 23, 102, 250, 139, 63,
170, 253, 94, 72, 35, 250, 144, 49, 216, 60, 185, 163, 44, 140, 245, 233,
129, 155, 162, 99, 108 }
Session ID:  {64, 252, 49, 16, 189, 141, 165, 145, 6, 139, 225, 230, 128,
198, 90, 92, 217, 141, 10, 174, 202, 88, 74, 186, 54, 177, 61, 4, 141, 130,
33, 180}
Cipher Suite: SSL_RSA_WITH_RC4_128_MD5
Compression Method: 0
***
%% Created:  [Session-1, SSL_RSA_WITH_RC4_128_MD5]
** SSL_RSA_WITH_RC4_128_MD5
[read] MD5 and SHA1 hashes:  len = 74
0000: 02 00 00 46 03 01 40 FC   31 10 79 AB 17 66 FA 8B  ...F..@.1.y..f..
0010: 3F AA FD 5E 48 23 FA 90   31 D8 3C B9 A3 2C 8C F5  ?..^H#..1.<..,.. 0020:="0020:" E9="E9" 81="81" 9B="9B" A2="A2" 63="63" 6C="6C" 20="20" 40="40" FC="FC" 31="31" 10="10" BD="BD" 8D="8D" A5="A5" 91="91" 06="06" ....cl="....cl" @.1......="@.1......" 0030:="0030:" 8B="8B" E1="E1" E6="E6" 80="80" C6="C6" 5A="5A" 5C="5C" D9="D9" 8D="8D" 0A="0A" AE="AE" CA="CA" 58="58" 4A="4A" BA="BA" 36="36" .....Z\.....XJ.6=".....Z\.....XJ.6" 0040:="0040:" B1="B1" 3D="3D" 04="04" 8D="8D" 82="82" 21="21" B4="B4" 00="00" 04="04" 00="00" .="...!...."
The server next identifies itself to the client by passing a Certificate chain. In this example, we have a certificate for the subject "bongos", signed by the issuer "JSSE Test CA". We know that "JSSE Test CA" is a trusted CA, so if the certificate chain verifies correctly by our X509TrustManager, we can accept this connection.

There are many different ways of establishing trust, so if the default X509TrustManager is not doing the types of trust management you need, you can supply your own X509TrustManager to the SSLContext.

*** Certificate chain
chain [0] = [
[
  Version: V3
  Subject:
  CN=bongos, OU=Java, O=Sun, ST=CA, C=US
  Signature Algorithm: MD5withRSA, OID = 1.2.840.113549.1.1.4

  Key:  Sun RSA public key, 1024 bits
  modulus: 143279610700427050704216702734995283650706638118826657356308087
  682552751165540126665070195006746918193702313900836063802045448392771274
  463088345157808670190122017153821642985630288017629294930800445939721128
  735250668515619736933648548512047941708018130926985936894512063397816602
  623867976474763783110866258971
  public exponent: 65537
  Validity: [From: Mon Jul 19 13:30:51 PDT 2004,
               To: Fri Dec 05 12:30:51 PST 2031]
  Issuer: CN=JSSE Test CA, OU=JWS, O=Sun,
      L=Santa Clara, ST=CA, C=US
  SerialNumber: [    01]

Certificate Extensions: 3

[1]: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 58 D7 3A A9 37 AA 3E 14   27 FC EC CC 45 08 04 8E  X.:.7.>.'...E...
0010: 2A 8B 77 28                                        *.w(
]
]

[2]: ObjectId: 2.5.29.35 Criticality=false
AuthorityKeyIdentifier [
KeyIdentifier [
0000: 08 A3 7E 35 96 15 FA B0   F5 1B 5F CD 4F 54 EF 31  ...5......_.OT.1
0010: 33 70 E4 A7                                        3p..
]

[CN=JSSE Test CA, OU=JWS, O=Sun, L=Santa Clara, ST=CA, C=US]
SerialNumber: [    00]
]

[3]: ObjectId: 2.5.29.19 Criticality=false
BasicConstraints:[
CA:false
PathLen: undefined
]

]
  Algorithm: [MD5withRSA]
  Signature:
0000: 05 3E 17 DA F2 05 CB 4E   9E BF 12 CE 13 76 FF B2  .>.....N.....v..
0010: FB 7F 9C 3D 45 28 43 6C   98 28 E3 92 17 C2 C6 F1  ...=E(Cl.(......
0020: 62 CA 60 C2 B0 EC E6 7E   4C 2F C2 40 FE 06 CB 34  b.`.....L/.@...4
0030: 60 B1 F4 26 1C E8 46 39   24 E1 8A 71 F2 13 90 A4  `..&..F9$..q....
0040: 0A 7B 0B 13 AB 51 68 53   D9 7A 31 5A C1 7E 3C 44  .....QhS.z1Z..a.)
0060: A3 31 46 02 C6 D2 8C 27   79 40 76 97 B6 25 19 BE  .1F....'y@v..%..
0070: 6C 6A 92 DC EF 11 BE E7   4A FF 2A E6 D6 AC 39 31  lj......J.*...91

]
chain [1] = [
[
  Version: V3
  Subject: CN=JSSE Test CA, OU=JWS, O=Sun,
      L=Santa Clara, ST=CA, C=US
  Signature Algorithm: MD5withRSA, OID = 1.2.840.113549.1.1.4

  Key:  Sun RSA public key, 1024 bits
  modulus: 108171861314934294923646852258201093253619460299818135230481040
  615923025149195168140458238629251726950220398889722590740552079782864577
  976838691751841449679901644183317203824143803940037883199193775839934767
  304560313841716869284745769157293013188246601563271959824290073095150730
  505329011956986145636520993169
  public exponent: 65537
  Validity: [From: Mon Jul 19 13:30:15 PDT 2004,
               To: Fri Dec 05 12:30:15 PST 2031]
  Issuer: CN=JSSE Test CA, OU=JWS, O=Sun,
      L=Santa Clara, ST=CA, C=US
  SerialNumber: [    00]

Certificate Extensions: 3
[1]: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 08 A3 7E 35 96 15 FA B0   F5 1B 5F CD 4F 54 EF 31  ...5......_.OT.1
0010: 33 70 E4 A7                                        3p..
]
]

[2]: ObjectId: 2.5.29.35 Criticality=false
AuthorityKeyIdentifier [
KeyIdentifier [
0000: 08 A3 7E 35 96 15 FA B0   F5 1B 5F CD 4F 54 EF 31  ...5......_.OT.1
0010: 33 70 E4 A7                                        3p..
]

[CN=JSSE Test CA, OU=JWS, O=Sun, L=Santa Clara, ST=CA, C=US]
SerialNumber: [    00]
]

[3]: ObjectId: 2.5.29.19 Criticality=false
BasicConstraints:[
CA:true
PathLen:2147483647
]

]
  Algorithm: [MD5withRSA]
  Signature:
0000: 73 6A 46 A2 05 E3 D8 6E   5C F4 18 A2 74 BC CF EB  sjF....n\...t...
0010: 0C 5B FF 81 1C 28 85 C7   FA E4 ED 5C 4F 71 22 FB  .[...(.....\Oq".
0020: 26 E3 01 3D 0C 10 AA BB   3E 90 ED 0E 1F 0C 9B B1  &..=....>.......
0030: 8C 49 6A 51 E4 C3 52 D6   FB 42 6C B4 A9 A9 57 A5  .IjQ..R..Bl...W.
0040: 84 00 42 6D 37 37 6D C7   6C 23 BC DC 60 D1 9D 6F  ..Bm77m.l#..`..o
0050: B3 75 47 3A 15 33 1A EC   90 09 9D F9 EB BD 88 96  .uG:.3..........
0060: E7 1D 41 BC 01 8D CA 88   D9 5B 04 09 8F 3E EA C8  ..A......[...>..
0070: 15 A0 AA 4E 85 95 AE 2F   0E 31 92 AC 3C FB 2F C4  ...N.../.1..<. /.="/." ]="]"
We recoginise this cert! We can trust it, and continue on with the handshake.
***
Found trusted certificate:
[
[
  Version: V3
  Subject: CN=JSSE Test CA, OU=JWS, O=Sun, L=Santa Clara, ST=CA, C=US
  Signature Algorithm: MD5withRSA, OID = 1.2.840.113549.1.1.4

  Key:  Sun RSA public key, 1024 bits
  modulus: 108171861314934294923646852258201093253619460299818135230481040
  615923025149195168140458238629251726950220398889722590740552079782864577
  976838691751841449679901644183317203824143803940037883199193775839934767
  304560313841716869284745769157293013188246601563271959824290073095150730
  505329011956986145636520993169
  public exponent: 65537
  Validity: [From: Mon Jul 19 13:30:15 PDT 2004,
               To: Fri Dec 05 12:30:15 PST 2031]
  Issuer: CN=JSSE Test CA, OU=JWS, O=Sun, L=Santa Clara, ST=CA, C=US
  SerialNumber: [    00]

Certificate Extensions: 3
[1]: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 08 A3 7E 35 96 15 FA B0   F5 1B 5F CD 4F 54 EF 31  ...5......_.OT.1
0010: 33 70 E4 A7                                        3p..
]
]

[2]: ObjectId: 2.5.29.35 Criticality=false
AuthorityKeyIdentifier [
KeyIdentifier [
0000: 08 A3 7E 35 96 15 FA B0   F5 1B 5F CD 4F 54 EF 31  ...5......_.OT.1
0010: 33 70 E4 A7                                        3p..
]

[CN=JSSE Test CA, OU=JWS, O=Sun, L=Santa Clara, ST=CA, C=US]
SerialNumber: [    00]
]

[3]: ObjectId: 2.5.29.19 Criticality=false
BasicConstraints:[
CA:true
PathLen:2147483647
]

]
  Algorithm: [MD5withRSA]
  Signature:
0000: 73 6A 46 A2 05 E3 D8 6E   5C F4 18 A2 74 BC CF EB  sjF....n\...t...
0010: 0C 5B FF 81 1C 28 85 C7   FA E4 ED 5C 4F 71 22 FB  .[...(.....\Oq".
0020: 26 E3 01 3D 0C 10 AA BB   3E 90 ED 0E 1F 0C 9B B1  &..=....>.......
0030: 8C 49 6A 51 E4 C3 52 D6   FB 42 6C B4 A9 A9 57 A5  .IjQ..R..Bl...W.
0040: 84 00 42 6D 37 37 6D C7   6C 23 BC DC 60 D1 9D 6F  ..Bm77m.l#..`..o
0050: B3 75 47 3A 15 33 1A EC   90 09 9D F9 EB BD 88 96  .uG:.3..........
0060: E7 1D 41 BC 01 8D CA 88   D9 5B 04 09 8F 3E EA C8  ..A......[...>..
0070: 15 A0 AA 4E 85 95 AE 2F   0E 31 92 AC 3C FB 2F C4  ...N.../.1..<. /.="/." ]="]"
We read the next few bytes of the handshake...
[read] MD5 and SHA1 hashes:  len = 1567
0000: 0B 00 06 1B 00 06 18 00   03 11 30 82 03 0D 30 82  ..........0...0.
0010: 02 76 A0 03 02 01 02 02   01 01 30 0D 06 09 2A 86  .v........0...*.
0020: 48 86 F7 0D 01 01 04 05   00 30 63 31 0B 30 09 06  H........0c1.0..
0030: 03 55 04 06 13 02 55 53   31 0B 30 09 06 03 55 04  .U....US1.0...U.
0040: 08 13 02 43 41 31 14 30   12 06 03 55 04 07 13 0B  ...CA1.0...U....
0050: 53 61 6E 74 61 20 43 6C   61 72 61 31 0C 30 0A 06  Santa Clara1.0..
0060: 03 55 04 0A 13 03 53 75   6E 31 0C 30 0A 06 03 55  .U....Sun1.0...U
0070: 04 0B 13 03 4A 57 53 31   15 30 13 06 03 55 04 03  ....JWS1.0...U..
0080: 13 0C 4A 53 53 45 20 54   65 73 74 20 43 41 30 1E  ..JSSE Test CA0.
0090: 17 0D 30 34 30 37 31 39   32 30 33 30 35 31 5A 17  ..040719203051Z.
00A0: 0D 33 31 31 32 30 35 32   30 33 30 35 31 5A 30 48  .311205203051Z0H
00B0: 31 0B 30 09 06 03 55 04   06 13 02 55 53 31 0B 30  1.0...U....US1.0
00C0: 09 06 03 55 04 08 13 02   43 41 31 0C 30 0A 06 03  ...U....CA1.0...
00D0: 55 04 0A 13 03 53 75 6E   31 0D 30 0B 06 03 55 04  U....Sun1.0...U.
00E0: 0B 13 04 4A 61 76 61 31   0F 30 0D 06 03 55 04 03  ...Java1.0...U..
00F0: 13 06 62 6F 6E 67 6F 73   30 81 9F 30 0D 06 09 2A  ..bongos0..0...*
0100: 86 48 86 F7 0D 01 01 01   05 00 03 81 8D 00 30 81  .H............0.
0110: 89 02 81 81 00 CC 09 74   CB 43 AB 6D ED F6 35 AA  .......t.C.m..5.
0120: 0E 49 29 D9 E0 F0 A1 D5   E2 3E 8F 5E C5 CE F4 DE  .I)......>.^....
0130: C1 A4 F3 CB 8C 45 0B 0F   6E 21 E1 00 65 CB 3C D1  .....E..n!..e.<. 0140:="0140:" 5C="5C" EF="EF" 6A="6A" FB="FB" 5D="5D" 96="96" 93="93" F4="F4" 71="71" 41="41" 41="41" 45="45" FF="FF" 37="37" 86="86" 4C="4C" \.j.]...qAAE.7.L="\.j.]...qAAE.7.L" 0150:="0150:" AB="AB" F9="F9" EA="EA" 9A="9A" 3F="3F" A5="A5" 82="82" 60="60" BF="BF" 0A="0A" 81="81" 84="84" C9="C9" 3E="3E" AC="AC" 0F="0F" ....?..`.....="....?..`.....">..
0160: 3D 20 3D AC A0 69 EF CA   4A A7 94 AD C8 A5 CE 37  = =..i..J......7
0170: 66 52 D1 25 43 CB 10 44   07 1E 93 74 D9 68 01 D7  fR.%C..D...t.h..
0180: 06 48 C9 0D 52 2D D5 6A   2E A6 48 4C 59 E2 5C C6  .H..R-.j..HLY.\.
0190: C1 5C C8 4C 1B 02 03 01   00 01 A3 81 EB 30 81 E8  .\.L.........0..
01A0: 30 09 06 03 55 1D 13 04   02 30 00 30 2C 06 09 60  0...U....0.0,..`
01B0: 86 48 01 86 F8 42 01 0D   04 1F 16 1D 4F 70 65 6E  .H...B......Open
01C0: 53 53 4C 20 47 65 6E 65   72 61 74 65 64 20 43 65  SSL Generated Ce
01D0: 72 74 69 66 69 63 61 74   65 30 1D 06 03 55 1D 0E  rtificate0...U..
01E0: 04 16 04 14 58 D7 3A A9   37 AA 3E 14 27 FC EC CC  ....X.:.7.>.'...
01F0: 45 08 04 8E 2A 8B 77 28   30 81 8D 06 03 55 1D 23  E...*.w(0....U.#
0200: 04 81 85 30 81 82 80 14   08 A3 7E 35 96 15 FA B0  ...0.......5....
0210: F5 1B 5F CD 4F 54 EF 31   33 70 E4 A7 A1 67 A4 65  .._.OT.13p...g.e
0220: 30 63 31 0B 30 09 06 03   55 04 06 13 02 55 53 31  0c1.0...U....US1
0230: 0B 30 09 06 03 55 04 08   13 02 43 41 31 14 30 12  .0...U....CA1.0.
0240: 06 03 55 04 07 13 0B 53   61 6E 74 61 20 43 6C 61  ..U....Santa Cla
0250: 72 61 31 0C 30 0A 06 03   55 04 0A 13 03 53 75 6E  ra1.0...U....Sun
0260: 31 0C 30 0A 06 03 55 04   0B 13 03 4A 57 53 31 15  1.0...U....JWS1.
0270: 30 13 06 03 55 04 03 13   0C 4A 53 53 45 20 54 65  0...U....JSSE Te
0280: 73 74 20 43 41 82 01 00   30 0D 06 09 2A 86 48 86  st CA...0...*.H.
0290: F7 0D 01 01 04 05 00 03   81 81 00 05 3E 17 DA F2  ............>...
02A0: 05 CB 4E 9E BF 12 CE 13   76 FF B2 FB 7F 9C 3D 45  ..N.....v.....=E
02B0: 28 43 6C 98 28 E3 92 17   C2 C6 F1 62 CA 60 C2 B0  (Cl.(......b.`..
02C0: EC E6 7E 4C 2F C2 40 FE   06 CB 34 60 B1 F4 26 1C  ...L/.@...4`..&.
02D0: E8 46 39 24 E1 8A 71 F2   13 90 A4 0A 7B 0B 13 AB  .F9$..q.........
02E0: 51 68 53 D9 7A 31 5A C1   7E 3C 44 2C 49 70 57 25  QhS.z1Z..a.).1F..
0300: D2 8C 27 79 40 76 97 B6   25 19 BE 6C 6A 92 DC EF  ..'y@v..%..lj...
0310: 11 BE E7 4A FF 2A E6 D6   AC 39 31 00 03 01 30 82  ...J.*...91...0.
0320: 02 FD 30 82 02 66 A0 03   02 01 02 02 01 00 30 0D  ..0..f........0.
0330: 06 09 2A 86 48 86 F7 0D   01 01 04 05 00 30 63 31  ..*.H........0c1
0340: 0B 30 09 06 03 55 04 06   13 02 55 53 31 0B 30 09  .0...U....US1.0.
0350: 06 03 55 04 08 13 02 43   41 31 14 30 12 06 03 55  ..U....CA1.0...U
0360: 04 07 13 0B 53 61 6E 74   61 20 43 6C 61 72 61 31  ....Santa Clara1
0370: 0C 30 0A 06 03 55 04 0A   13 03 53 75 6E 31 0C 30  .0...U....Sun1.0
0380: 0A 06 03 55 04 0B 13 03   4A 57 53 31 15 30 13 06  ...U....JWS1.0..
0390: 03 55 04 03 13 0C 4A 53   53 45 20 54 65 73 74 20  .U....JSSE Test
03A0: 43 41 30 1E 17 0D 30 34   30 37 31 39 32 30 33 30  CA0...0407192030
03B0: 31 35 5A 17 0D 33 31 31   32 30 35 32 30 33 30 31  15Z..31120520301
03C0: 35 5A 30 63 31 0B 30 09   06 03 55 04 06 13 02 55  5Z0c1.0...U....U
03D0: 53 31 0B 30 09 06 03 55   04 08 13 02 43 41 31 14  S1.0...U....CA1.
03E0: 30 12 06 03 55 04 07 13   0B 53 61 6E 74 61 20 43  0...U....Santa C
03F0: 6C 61 72 61 31 0C 30 0A   06 03 55 04 0A 13 03 53  lara1.0...U....S
0400: 75 6E 31 0C 30 0A 06 03   55 04 0B 13 03 4A 57 53  un1.0...U....JWS
0410: 31 15 30 13 06 03 55 04   03 13 0C 4A 53 53 45 20  1.0...U....JSSE
0420: 54 65 73 74 20 43 41 30   81 9F 30 0D 06 09 2A 86  Test CA0..0...*.
0430: 48 86 F7 0D 01 01 01 05   00 03 81 8D 00 30 81 89  H............0..
0440: 02 81 81 00 9A 0A B6 45   66 D5 DE 4A D9 3C 8C AC  .......Ef..J.<.. 0450:="0450:" A6="A6" B5="B5" A5="A5" 88="88" B4="B4" CF="CF" 14="14" E1="E1" A6="A6" 1B="1B" 25="25" 25="25" 4F="4F" 44="44" C9="C9" 1F="1F" ..........%%OD..="..........%%OD.." 0460:="0460:" 22="22" 38="38" 32="32" 29="29" CF="CF" A1="A1" 7C="7C" 18="18" 30="30" 93="93" DC="DC" 2B="2B" EC="EC" 2B="2B" 67="67" EE="EE">.f..U.
0490: 4D 0A 67 C7 5D 21 9B 29   EA 2E 51 C5 83 A3 55 FF  M.g.]!.)..Q...U.
04A0: 35 CA A6 99 8F 46 F8 8E   56 BB A2 B1 39 83 D8 61  5....F..V...9..a
04B0: 42 79 E0 95 78 FA C6 E3   65 B0 FD 74 2D 64 51 71  By..x...e..t-dQq
04C0: 04 F2 A1 91 02 03 01 00   01 A3 81 C0 30 81 BD 30  ............0..0
04D0: 1D 06 03 55 1D 0E 04 16   04 14 08 A3 7E 35 96 15  ...U.........5..
04E0: FA B0 F5 1B 5F CD 4F 54   EF 31 33 70 E4 A7 30 81  ...._.OT.13p..0.
04F0: 8D 06 03 55 1D 23 04 81   85 30 81 82 80 14 08 A3  ...U.#...0......
0500: 7E 35 96 15 FA B0 F5 1B   5F CD 4F 54 EF 31 33 70  .5......_.OT.13p
0510: E4 A7 A1 67 A4 65 30 63   31 0B 30 09 06 03 55 04  ...g.e0c1.0...U.
0520: 06 13 02 55 53 31 0B 30   09 06 03 55 04 08 13 02  ...US1.0...U....
0530: 43 41 31 14 30 12 06 03   55 04 07 13 0B 53 61 6E  CA1.0...U....San
0540: 74 61 20 43 6C 61 72 61   31 0C 30 0A 06 03 55 04  ta Clara1.0...U.
0550: 0A 13 03 53 75 6E 31 0C   30 0A 06 03 55 04 0B 13  ...Sun1.0...U...
0560: 03 4A 57 53 31 15 30 13   06 03 55 04 03 13 0C 4A  .JWS1.0...U....J
0570: 53 53 45 20 54 65 73 74   20 43 41 82 01 00 30 0C  SSE Test CA...0.
0580: 06 03 55 1D 13 04 05 30   03 01 01 FF 30 0D 06 09  ..U....0....0...
0590: 2A 86 48 86 F7 0D 01 01   04 05 00 03 81 81 00 73  *.H............s
05A0: 6A 46 A2 05 E3 D8 6E 5C   F4 18 A2 74 BC CF EB 0C  jF....n\...t....
05B0: 5B FF 81 1C 28 85 C7 FA   E4 ED 5C 4F 71 22 FB 26  [...(.....\Oq".&
05C0: E3 01 3D 0C 10 AA BB 3E   90 ED 0E 1F 0C 9B B1 8C  ..=....>........
05D0: 49 6A 51 E4 C3 52 D6 FB   42 6C B4 A9 A9 57 A5 84  IjQ..R..Bl...W..
05E0: 00 42 6D 37 37 6D C7 6C   23 BC DC 60 D1 9D 6F B3  .Bm77m.l#..`..o.
05F0: 75 47 3A 15 33 1A EC 90   09 9D F9 EB BD 88 96 E7  uG:.3...........
0600: 1D 41 BC 01 8D CA 88 D9   5B 04 09 8F 3E EA C8 15  .A......[...>...
0610: A0 AA 4E 85 95 AE 2F 0E   31 92 AC 3C FB 2F C4     ..N.../.1..<. /.="/."
...and parse it to find that it's a CertificateRequest message.

The server is asking the client to identify itself with a X509 certificate subject having the common name (CN=) "Duke". The server's X509TrustManager has the option of rejecting any credentials provided by the client (or lack thereof). In a real-world situation, you'd probably use a certificate signed by a CA, and the list of trusted CA's would be included in this message instead.

Lastly, we receive the ServerHelloDone message, which signals to the client that the server has finished sending its part of the handshake.

*** CertificateRequest
Cert Types: RSA, DSS,
Cert Authorities:
CN=Duke, OU=Java Software, O="Sun Microsystems, Inc.",
L=Cupertino, ST=CA, C=US>
[read] MD5 and SHA1 hashes:  len = 131
0000: 0D 00 00 7F 02 01 02 00   7A 00 78 30 76 31 0B 30  ........z.x0v1.0
0010: 09 06 03 55 04 06 13 02   55 53 31 0B 30 09 06 03  ...U....US1.0...
0020: 55 04 08 13 02 43 41 31   12 30 10 06 03 55 04 07  U....CA1.0...U..
0030: 13 09 43 75 70 65 72 74   69 6E 6F 31 1F 30 1D 06  ..Cupertino1.0..
0040: 03 55 04 0A 13 16 53 75   6E 20 4D 69 63 72 6F 73  .U....Sun Micros
0050: 79 73 74 65 6D 73 2C 20   49 6E 63 2E 31 16 30 14  ystems, Inc.1.0.
0060: 06 03 55 04 0B 13 0D 4A   61 76 61 20 53 6F 66 74  ..U....Java Soft
0070: 77 61 72 65 31 0D 30 0B   06 03 55 04 03 13 04 44  ware1.0...U....D
0080: 75 6B 65                                           uke
*** ServerHelloDone
[read] MD5 and SHA1 hashes:  len = 4
0000: 0E 00 00 00                                        ....
We need to send client credentials back to the server, so the client's X509KeyManager is now consulted. We look for a match between the list of accepted issuers (above), and the certificates we have in our KeyStore. In this case (luckily?), there is a match: we have credentials for "duke". It's now up to the server's X509TrustManager to decide whether to accept these credentials.
matching alias: duke
*** Certificate chain
chain [0] = [
[
  Version: V1
  Subject: CN=Duke, OU=Java Software, O="Sun Microsystems, Inc.",
  L=Cupertino, ST=CA, C=US
  Signature Algorithm: MD5withRSA, OID = 1.2.840.113549.1.1.4

  Key:  Sun RSA public key, 1024 bits
  modulus: 134968166047563266914058280571444028986498087544923991226919517
  667593269213420979048109900052353578998293280426361122296881234393722020
  704208851688212064483570055963805034839797994154526862998272017486468599
  962268346037652120279791547218281230795146025359480589335682217749874703
  510467348902637769973696151441
  public exponent: 65537
  Validity: [From: Tue May 22 16:46:46 PDT 2001,
               To: Sun May 22 16:46:46 PDT 2011]
  Issuer: CN=Duke, OU=Java Software, O="Sun Microsystems, Inc.",
  L=Cupertino, ST=CA, C=US
  SerialNumber: [    3b0afa66]

]
  Algorithm: [MD5withRSA]
  Signature:
0000: 5F B5 62 E9 A0 26 1D 8E   A2 7E 7C 02 08 36 3A 3E  _.b..&.......6:>
0010: C9 C2 45 03 DD F9 BC 06   FC 25 CF 30 92 91 B1 4E  ..E......%.0...N
0020: 62 17 08 48 14 68 80 CF   DD 89 11 EA 92 7F CE DD  b..H.h..........
0030: B4 FD 12 A8 71 C7 9E D7   C3 D0 E3 BD BB DE 20 92  ....q......... .
0040: C2 3B C8 DE CB 25 23 C0   8B B6 92 B9 0B 64 80 63  .;...%#......d.c
0050: D9 09 25 2D 7A CF 0A 31   B6 E9 CA C1 37 93 BC 0D  ..%-z..1....7...
0060: 4E 74 95 4F 58 31 DA AC   DF D8 BD 89 BD AF EC C8  Nt.OX1..........
0070: 2D 18 A2 BC B2 15 4F B7   28 6F D3 00 E1 72 9B 6C  -.....O.(o...r.l

]
***
In the case of this particular cipher suite, we must now pass a message called a ClientKeyExchange, which helps establish a shared secret between the two parties.

All of this data is eventually collected and written to the raw device.

*** ClientKeyExchange, RSA PreMasterSecret, TLSv1
Random Secret:  { 3, 1, 132, 84, 245, 214, 235, 245, 168, 8, 186, 250,
122, 34, 97, 45, 117, 220, 64, 232, 152, 249, 14, 178, 135, 128, 184,
26, 143, 104, 37, 184, 81, 208, 84, 69, 97, 138, 80, 201, 187, 14, 57,
83, 69, 120, 190, 121 }
[write] MD5 and SHA1 hashes:  len = 754
0000: 0B 00 02 68 00 02 65 00   02 62 30 82 02 5E 30 82  ...h..e..b0..^0.
0010: 01 C7 02 04 3B 0A FA 66   30 0D 06 09 2A 86 48 86  ....;..f0...*.H.
0020: F7 0D 01 01 04 05 00 30   76 31 0B 30 09 06 03 55  .......0v1.0...U
0030: 04 06 13 02 55 53 31 0B   30 09 06 03 55 04 08 13  ....US1.0...U...
0040: 02 43 41 31 12 30 10 06   03 55 04 07 13 09 43 75  .CA1.0...U....Cu
0050: 70 65 72 74 69 6E 6F 31   1F 30 1D 06 03 55 04 0A  pertino1.0...U..
0060: 13 16 53 75 6E 20 4D 69   63 72 6F 73 79 73 74 65  ..Sun Microsyste
0070: 6D 73 2C 20 49 6E 63 2E   31 16 30 14 06 03 55 04  ms, Inc.1.0...U.
0080: 0B 13 0D 4A 61 76 61 20   53 6F 66 74 77 61 72 65  ...Java Software
0090: 31 0D 30 0B 06 03 55 04   03 13 04 44 75 6B 65 30  1.0...U....Duke0
00A0: 1E 17 0D 30 31 30 35 32   32 32 33 34 36 34 36 5A  ...010522234646Z
00B0: 17 0D 31 31 30 35 32 32   32 33 34 36 34 36 5A 30  ..110522234646Z0
00C0: 76 31 0B 30 09 06 03 55   04 06 13 02 55 53 31 0B  v1.0...U....US1.
00D0: 30 09 06 03 55 04 08 13   02 43 41 31 12 30 10 06  0...U....CA1.0..
00E0: 03 55 04 07 13 09 43 75   70 65 72 74 69 6E 6F 31  .U....Cupertino1
00F0: 1F 30 1D 06 03 55 04 0A   13 16 53 75 6E 20 4D 69  .0...U....Sun Mi
0100: 63 72 6F 73 79 73 74 65   6D 73 2C 20 49 6E 63 2E  crosystems, Inc.
0110: 31 16 30 14 06 03 55 04   0B 13 0D 4A 61 76 61 20  1.0...U....Java
0120: 53 6F 66 74 77 61 72 65   31 0D 30 0B 06 03 55 04  Software1.0...U.
0130: 03 13 04 44 75 6B 65 30   81 9F 30 0D 06 09 2A 86  ...Duke0..0...*.
0140: 48 86 F7 0D 01 01 01 05   00 03 81 8D 00 30 81 89  H............0..
0150: 02 81 81 00 C0 33 77 E7   1F D0 CE CE BD 43 2F 8D  .....3w......C/.
0160: EB C6 D3 07 A9 00 F5 75   4D C8 4B 04 52 42 EE 69  .......uM.K.RB.i
0170: F3 30 E9 A0 C6 07 B7 C8   55 2D B9 5B 57 7A 4C AD  .0......U-.[WzL.
0180: 1A 30 63 5C 7D 6D 16 BF   ED 54 13 49 8A 1B E6 29  .0c\.m...T.I...)
0190: 26 20 85 F9 5E 2B 2F A7   12 9C 98 2D 83 F6 EE B1  & ..^+/....-....
01A0: 85 68 DA B5 8E 4C 1D 2D   8E 21 97 B0 30 C8 3A 57  .h...L.-.!..0.:W
01B0: F4 E1 18 9E F6 98 B2 D5   3D 8E D5 2B 09 E2 E1 A0  ........=..+....
01C0: 49 C1 A6 43 CE EA 57 7F   3B 5C 3A C9 BA DB B7 F0  I..C..W.;\:.....
01D0: 89 69 BF 91 02 03 01 00   01 30 0D 06 09 2A 86 48  .i.......0...*.H
01E0: 86 F7 0D 01 01 04 05 00   03 81 81 00 5F B5 62 E9  ............_.b.
01F0: A0 26 1D 8E A2 7E 7C 02   08 36 3A 3E C9 C2 45 03  .&.......6:>..E.
0200: DD F9 BC 06 FC 25 CF 30   92 91 B1 4E 62 17 08 48  .....%.0...Nb..H
0210: 14 68 80 CF DD 89 11 EA   92 7F CE DD B4 FD 12 A8  .h..............
0220: 71 C7 9E D7 C3 D0 E3 BD   BB DE 20 92 C2 3B C8 DE  q......... ..;..
0230: CB 25 23 C0 8B B6 92 B9   0B 64 80 63 D9 09 25 2D  .%#......d.c..%-
0240: 7A CF 0A 31 B6 E9 CA C1   37 93 BC 0D 4E 74 95 4F  z..1....7...Nt.O
0250: 58 31 DA AC DF D8 BD 89   BD AF EC C8 2D 18 A2 BC  X1..........-...
0260: B2 15 4F B7 28 6F D3 00   E1 72 9B 6C 10 00 00 82  ..O.(o...r.l....
0270: 00 80 4E DD E7 77 F1 91   6B 31 4E FA D6 61 D9 69  ..N..w..k1N..a.i
0280: 82 BD 22 40 83 FD 76 E6   FF A7 18 95 A0 04 28 0D  .."@..v.......(.
0290: 0D F7 44 6F 0C 42 4F 17   77 A0 99 56 2A 13 77 28  ..Do.BO.w..V*.w(
02A0: 0B 09 48 C1 B9 8C 09 ED   9F C6 2E 32 18 DB BD ED  ..H........2....
02B0: AF C3 AB E7 AD 8F DF 9E   AB 07 43 B4 50 EF 74 98  ..........C.P.t.
02C0: EA FC E8 4D C9 DA FC B0   B2 C7 D4 83 50 B5 84 B8  ...M........P...
02D0: 44 86 7B 5D 8A C2 F8 04   80 06 E6 84 42 33 B2 EE  D..]........B3..
02E0: 05 E6 D3 48 0E 23 E5 1F   63 4C 53 98 B8 8C 45 BA  ...H.#..cLS...E.
02F0: C8 19                                              ..
main, WRITE: TLSv1 Handshake, length = 754
[Raw write]: length = 759
0000: 16 03 01 02 F2 0B 00 02   68 00 02 65 00 02 62 30  ........h..e..b0
0010: 82 02 5E 30 82 01 C7 02   04 3B 0A FA 66 30 0D 06  ..^0.....;..f0..
0020: 09 2A 86 48 86 F7 0D 01   01 04 05 00 30 76 31 0B  .*.H........0v1.
0030: 30 09 06 03 55 04 06 13   02 55 53 31 0B 30 09 06  0...U....US1.0..
0040: 03 55 04 08 13 02 43 41   31 12 30 10 06 03 55 04  .U....CA1.0...U.
0050: 07 13 09 43 75 70 65 72   74 69 6E 6F 31 1F 30 1D  ...Cupertino1.0.
0060: 06 03 55 04 0A 13 16 53   75 6E 20 4D 69 63 72 6F  ..U....Sun Micro
0070: 73 79 73 74 65 6D 73 2C   20 49 6E 63 2E 31 16 30  systems, Inc.1.0
0080: 14 06 03 55 04 0B 13 0D   4A 61 76 61 20 53 6F 66  ...U....Java Sof
0090: 74 77 61 72 65 31 0D 30   0B 06 03 55 04 03 13 04  tware1.0...U....
00A0: 44 75 6B 65 30 1E 17 0D   30 31 30 35 32 32 32 33  Duke0...01052223
00B0: 34 36 34 36 5A 17 0D 31   31 30 35 32 32 32 33 34  4646Z..110522234
00C0: 36 34 36 5A 30 76 31 0B   30 09 06 03 55 04 06 13  646Z0v1.0...U...
00D0: 02 55 53 31 0B 30 09 06   03 55 04 08 13 02 43 41  .US1.0...U....CA
00E0: 31 12 30 10 06 03 55 04   07 13 09 43 75 70 65 72  1.0...U....Cuper
00F0: 74 69 6E 6F 31 1F 30 1D   06 03 55 04 0A 13 16 53  tino1.0...U....S
0100: 75 6E 20 4D 69 63 72 6F   73 79 73 74 65 6D 73 2C  un Microsystems,
0110: 20 49 6E 63 2E 31 16 30   14 06 03 55 04 0B 13 0D   Inc.1.0...U....
0120: 4A 61 76 61 20 53 6F 66   74 77 61 72 65 31 0D 30  Java Software1.0
0130: 0B 06 03 55 04 03 13 04   44 75 6B 65 30 81 9F 30  ...U....Duke0..0
0140: 0D 06 09 2A 86 48 86 F7   0D 01 01 01 05 00 03 81  ...*.H..........
0150: 8D 00 30 81 89 02 81 81   00 C0 33 77 E7 1F D0 CE  ..0.......3w....
0160: CE BD 43 2F 8D EB C6 D3   07 A9 00 F5 75 4D C8 4B  ..C/........uM.K
0170: 04 52 42 EE 69 F3 30 E9   A0 C6 07 B7 C8 55 2D B9  .RB.i.0......U-.
0180: 5B 57 7A 4C AD 1A 30 63   5C 7D 6D 16 BF ED 54 13  [WzL..0c\.m...T.
0190: 49 8A 1B E6 29 26 20 85   F9 5E 2B 2F A7 12 9C 98  I...)& ..^+/....
01A0: 2D 83 F6 EE B1 85 68 DA   B5 8E 4C 1D 2D 8E 21 97  -.....h...L.-.!.
01B0: B0 30 C8 3A 57 F4 E1 18   9E F6 98 B2 D5 3D 8E D5  .0.:W........=..
01C0: 2B 09 E2 E1 A0 49 C1 A6   43 CE EA 57 7F 3B 5C 3A  +....I..C..W.;\:
01D0: C9 BA DB B7 F0 89 69 BF   91 02 03 01 00 01 30 0D  ......i.......0.
01E0: 06 09 2A 86 48 86 F7 0D   01 01 04 05 00 03 81 81  ..*.H...........
01F0: 00 5F B5 62 E9 A0 26 1D   8E A2 7E 7C 02 08 36 3A  ._.b..&.......6:
0200: 3E C9 C2 45 03 DD F9 BC   06 FC 25 CF 30 92 91 B1  >..E......%.0...
0210: 4E 62 17 08 48 14 68 80   CF DD 89 11 EA 92 7F CE  Nb..H.h.........
0220: DD B4 FD 12 A8 71 C7 9E   D7 C3 D0 E3 BD BB DE 20  .....q.........
0230: 92 C2 3B C8 DE CB 25 23   C0 8B B6 92 B9 0B 64 80  ..;...%#......d.
0240: 63 D9 09 25 2D 7A CF 0A   31 B6 E9 CA C1 37 93 BC  c..%-z..1....7..
0250: 0D 4E 74 95 4F 58 31 DA   AC DF D8 BD 89 BD AF EC  .Nt.OX1.........
0260: C8 2D 18 A2 BC B2 15 4F   B7 28 6F D3 00 E1 72 9B  .-.....O.(o...r.
0270: 6C 10 00 00 82 00 80 4E   DD E7 77 F1 91 6B 31 4E  l......N..w..k1N
0280: FA D6 61 D9 69 82 BD 22   40 83 FD 76 E6 FF A7 18  ..a.i.."@..v....
0290: 95 A0 04 28 0D 0D F7 44   6F 0C 42 4F 17 77 A0 99  ...(...Do.BO.w..
02A0: 56 2A 13 77 28 0B 09 48   C1 B9 8C 09 ED 9F C6 2E  V*.w(..H........
02B0: 32 18 DB BD ED AF C3 AB   E7 AD 8F DF 9E AB 07 43  2..............C
02C0: B4 50 EF 74 98 EA FC E8   4D C9 DA FC B0 B2 C7 D4  .P.t....M.......
02D0: 83 50 B5 84 B8 44 86 7B   5D 8A C2 F8 04 80 06 E6  .P...D..].......
02E0: 84 42 33 B2 EE 05 E6 D3   48 0E 23 E5 1F 63 4C 53  .B3.....H.#..cLS
02F0: 98 B8 8C 45 BA C8 19                               ...E...
At this point, we have everything we need to generate the actual secrets.
SESSION KEYGEN:
PreMaster Secret:
0000: 03 01 84 54 F5 D6 EB F5   A8 08 BA FA 7A 22 61 2D  ...T........z"a-
0010: 75 DC 40 E8 98 F9 0E B2   87 80 B8 1A 8F 68 25 B8  u.@..........h%.
0020: 51 D0 54 45 61 8A 50 C9   BB 0E 39 53 45 78 BE 79  Q.TEa.P...9SEx.y
CONNECTION KEYGEN:
Client Nonce:
0000: 40 FC 30 AE 2D 63 84 BB   C5 4B 27 FD 58 21 CA 90  @.0.-c...K'.X!..
0010: 05 F6 A7 7B 37 BB 72 E1   FC 1D 1B 6A F5 1C C8 9F  ....7.r....j....
Server Nonce:
0000: 40 FC 31 10 79 AB 17 66   FA 8B 3F AA FD 5E 48 23  @.1.y..f..?..^H#
0010: FA 90 31 D8 3C B9 A3 2C   8C F5 E9 81 9B A2 63 6C  ..1.<..,......cl Master Secret:
0000: B0 00 22 34 59 03 16 B7   7A 6C 56 9B 89 D2 7A CC  .."4Y...zlV...z.
0010: F3 85 55 59 3A 14 76 3D   54 BF EB 3F E0 2F B1 4B  ..UY:.v=T..?./.K
0020: 79 8C 75 A9 78 55 6C 8E   A2 14 60 B7 45 EB 77 B2  y.u.xUl...`.E.w.
Client MAC write Secret:
0000: 85 F0 56 F8 07 1D B1 89   89 D0 E1 33 3C CA 63 F9  ..V........3<.c. Server="Server" MAC="MAC" write="write" Secret:="Secret:" 0000:="0000:" 1E="1E" 4D="4D" D1="D1" D3="D3" 0A="0A" 78="78" EE="EE" B7="B7" 4F="4F" EC="EC" 15="15" 79="79" B2="B2" 59="59" 18="18" 40="40" .M...x..O..y.Y.@=".M...x..O..y.Y.@" Client="Client" write="write" key:="key:" 0000:="0000:" 10="10" D0="D0" D6="D6" C2="C2" D9="D9" B7="B7" 62="62" CB="CB" 2C="2C" 74="74" BF="BF" 5F="5F" 85="85" 3C="3C" 6F="6F" E7="E7" ......b.,t._.
Send a quick confirmation to the server verifying that we know the private key corresponding to the client certificate we just sent.
*** CertificateVerify
[write] MD5 and SHA1 hashes:  len = 134
0000: 0F 00 00 82 00 80 45 41   43 4B 47 1D F0 EE D1 14  ......EACKG.....
0010: AE F9 B3 2C 1F B9 FE 7B   3E 91 50 C5 0F F1 57 4F  ...,....>.P...WO
0020: 55 F1 4B C3 79 16 A8 F1   72 6B 10 CA CC 83 02 FC  U.K.y...rk......
0030: 97 3D 04 29 44 4C 58 74   84 94 19 63 BB 8A 2C 78  .=.)DLXt...c..,x
0040: 43 A0 DD 5E 54 52 AA 97   15 92 1C 39 6B 10 2E BF  C..^TR.....9k...
0050: F2 DA AE 2D 8F FB 50 44   9E E2 1F 7D C9 C5 CB A0  ...-..PD........
0060: 31 A0 F9 AA 93 2D 1B 07   1B FA E0 EE 95 E7 88 D7  1....-..........
0070: AD 4A 3A 40 DC FB DF 9E   EB 75 04 14 E2 F2 BB DC  .J:@.....u......
0080: 1B 7E 6E D5 8C 62                                  ..n..b
main, WRITE: TLSv1 Handshake, length = 134
[Raw write]: length = 139
0000: 16 03 01 00 86 0F 00 00   82 00 80 45 41 43 4B 47  ...........EACKG
0010: 1D F0 EE D1 14 AE F9 B3   2C 1F B9 FE 7B 3E 91 50  ........,....>.P
0020: C5 0F F1 57 4F 55 F1 4B   C3 79 16 A8 F1 72 6B 10  ...WOU.K.y...rk.
0030: CA CC 83 02 FC 97 3D 04   29 44 4C 58 74 84 94 19  ......=.)DLXt...
0040: 63 BB 8A 2C 78 43 A0 DD   5E 54 52 AA 97 15 92 1C  c..,xC..^TR.....
0050: 39 6B 10 2E BF F2 DA AE   2D 8F FB 50 44 9E E2 1F  9k......-..PD...
0060: 7D C9 C5 CB A0 31 A0 F9   AA 93 2D 1B 07 1B FA E0  .....1....-.....
0070: EE 95 E7 88 D7 AD 4A 3A   40 DC FB DF 9E EB 75 04  ......J:@.....u.
0080: 14 E2 F2 BB DC 1B 7E 6E   D5 8C 62                 .......n..b
Almost finished! Tell the server we're changing to the newly established cipher suite. All further messages will be encrypted using the parameters we just established. We send an encrypted Finished message to verify everything worked.
main, WRITE: TLSv1 Change Cipher Spec, length = 1
[Raw write]: length = 6
0000: 14 03 01 00 01 01                                  ......
*** Finished
verify_data:  { 242, 98, 66, 170, 124, 124, 204, 231, 73, 15, 237, 172 }
***
[write] MD5 and SHA1 hashes:  len = 16
0000: 14 00 00 0C F2 62 42 AA   7C 7C CC E7 49 0F ED AC  .....bB.....I...
Padded plaintext before ENCRYPTION:  len = 32
0000: 14 00 00 0C F2 62 42 AA   7C 7C CC E7 49 0F ED AC  .....bB.....I...
0010: FA 06 3C 9F 8C 41 1D ED   2B 06 D0 5A ED 31 F2 80  ..<..A..+..Z.1.. main,="main," WRITE:="WRITE:" TLSv1="TLSv1" Handshake,="Handshake," length="32"
Note next that when the message above is actually written to the raw output device (following the 5 bytes of header information), the message is now encrypted.
[Raw write]: length = 37
0000: 16 03 01 00 20 15 8C 25   BA 4E 73 F5 27 79 49 B1  .... ..%.Ns.'yI.
0010: E9 F5 7E C8 48 A7 D3 A6   9B BD 6F 8E A5 8E 2B B7  ....H.....o...+.
0020: EE DC BD F4 D7                                     .....
We now wait for the server to send the same (Change Cipher Spec/Finshed), so we can know it completed negotiations successfully.
[Raw read]: length = 5
0000: 14 03 01 00 01                                     .....
[Raw read]: length = 1
0000: 01                                                 .
main, READ: TLSv1 Change Cipher Spec, length = 1
[Raw read]: length = 5
0000: 16 03 01 00 20                                     ....
[Raw read]: length = 32
0000: 1F F5 FA C8 79 20 CE 91   AA 68 7F 6C F3 5A DB 7B  ....y ...h.l.Z..
0010: A5 1C 31 1F 6F 41 50 C5   C6 25 25 8D 48 50 3F F1  ..1.oAP..%%.HP?.
main, READ: TLSv1 Handshake, length = 32
Padded plaintext after DECRYPTION:  len = 32
0000: 14 00 00 0C 07 38 46 5F   62 AD 41 B3 DC 79 30 FD  .....8F_b.A..y0.
0010: 34 F2 3B 54 1C D4 68 0E   92 0B 9C 7E ED 47 9F 3B  4.;T..h......G.;
*** Finished
verify_data:  { 7, 56, 70, 95, 98, 173, 65, 179, 220, 121, 48, 253 }
***
[read] MD5 and SHA1 hashes:  len = 16
0000: 14 00 00 0C 07 38 46 5F   62 AD 41 B3 DC 79 30 FD  .....8F_b.A..y0.
Everything completed successfully! Let's cache the established session in case we want to reestablish this session after this connection is dropped.

At this point, a SSL/TLS client should examine the credentials of the peer to make sure that it is communicating with the expected server. A HttpsURLConnection would check the hostname and call HostnameVerifier if there was a problem, but the raw SSLSocket doesn't. This verification should be done by hand, but we're ignoring this for now.

So, after all that, we're finally ready to exchange application data. We send a "GET /index.html HTTP1.1" command.

%% Cached client session: [Session-1, SSL_RSA_WITH_RC4_128_MD5]
Padded plaintext before ENCRYPTION:  len = 42
0000: 47 45 54 20 2F 69 6E 64   65 78 2E 68 74 6D 6C 20  GET /index.html
0010: 48 54 54 50 2F 31 2E 31   0A 0A CA CB D1 10 9D 0E  HTTP/1.1........
0020: 13 3C D9 66 6B 9E 36 87   ED 9B                    .<.fk.6... main,="main," WRITE:="WRITE:" TLSv1="TLSv1" Application="Application" Data,="Data," length="42"
Note again the data over the wire is encrypted (skipping the 5 header bytes).
[Raw write]: length = 47
0000: 17 03 01 00 2A 8A E9 EC   2C 8D 19 B6 E2 50 C1 E2  ....*...,....P..
0010: 22 1A C0 97 95 23 99 E1   20 DD F3 2A B4 DC 14 57  "....#.. ..*...W
0020: 32 71 58 98 01 BE 70 11   A3 FC 8E 3A 7C 8D BF     2qX...p....:...
We get the application data back. First the HTTPS header, then the actual data.
[Raw read]: length = 5
0000: 17 03 01 00 50                                     ....P
[Raw read]: length = 80
0000: 70 10 0D D6 FA ED 51 FC   C2 7E CE 24 2E F1 2F F7  p.....Q....$../.
0010: E7 CD A5 D6 2D 1B 10 FD   48 56 9C 1B B5 EC 8F 1E  ....-...HV......
0020: DB DA F9 83 62 52 15 38   70 4B C1 85 13 EF CA 17  ....bR.8pK......
0030: 89 37 D3 45 C0 88 BB 92   63 F6 9C DE 69 E6 60 3E  .7.E....c...i.`>
0040: 1F F7 4D C1 56 61 79 01   49 55 FB 38 6B 16 81 BC  ..M.Vay.IU.8k...
main, READ: TLSv1 Application Data, length = 80
Padded plaintext after DECRYPTION:  len = 80
0000: 48 54 54 50 2F 31 2E 30   20 32 30 30 20 4F 4B 0D  HTTP/1.0 200 OK.
0010: 0A 43 6F 6E 74 65 6E 74   2D 4C 65 6E 67 74 68 3A  .Content-Length:
0020: 20 35 38 0D 0A 43 6F 6E   74 65 6E 74 2D 54 79 70   58..Content-Typ
0030: 65 3A 20 74 65 78 74 2F   68 74 6D 6C 0D 0A 0D 0A  e: text/html....
0040: 40 18 A1 FF 1D 5A D4 55   98 DB E3 95 01 A0 91 AF  @....Z.U........
HTTP/1.0 200 OK
Content-Length: 58
Content-Type: text/html
[Raw read]: length = 5
0000: 17 03 01 00 4A                                     ....J
[Raw read]: length = 74
0000: 75 DA F2 58 C3 5E 58 DE   14 AD FE 71 A3 78 07 58  u..X.^X....q.x.X
0010: EB E9 2B A2 D7 82 5C 6E   C9 9C 58 84 D7 A8 C6 F8  ..+...\n..X.....
0020: DE C6 5B BA 10 59 DF CC   11 AE 35 F7 C7 0F F6 C2  ..[..Y....5.....
0030: 3E 67 4E 95 30 AA 91 0B   E4 4F 5C C7 BF 50 AC 61  >gN.0....O\..P.a
0040: 87 B7 80 75 F0 81 F1 00   63 C9                    ...u....c.
main, READ: TLSv1 Application Data, length = 74
Padded plaintext after DECRYPTION:  len = 74
0000: 3C 48 54 4D 4C 3E 0A 3C   48 31 3E 48 65 6C 6C 6F  <HTML>.<H1>Hello
0010: 20 57 6F 72 6C 64 3C 2F   48 31 3E 0A 54 68 65 20   World</H1>.The
0020: 74 65 73 74 20 69 73 20   63 6F 6D 70 6C 65 74 65  test is complete
0030: 21 0A 3C 2F 48 54 4D 4C   3E 0A 38 2E 68 72 F1 47  !.</HTML>.8.hr.G
0040: E8 56 D1 EA A6 FC 3C 30   6F F3                    .V....<0o.  <HTML>
<H1>Hello World<H1>
The test is complete!
<HTML>
Read from the socket again to see if there is any more data. We get a close_notify message, which means this connection is shutting down properly. We send our own in turn, then close the socket.
[Raw read]: length = 5
0000: 15 03 01 00 12                                     .....
[Raw read]: length = 18
0000: 09 AB 95 00 43 8D C8 7C   83 18 EB C4 8C 99 43 A6  ....C.........C.
0010: 76 49                                              vI
main, READ: TLSv1 Alert, length = 18
Padded plaintext after DECRYPTION:  len = 18
0000: 01 00 FA 44 D5 57 71 5C   CC C7 D9 D0 04 23 10 D8  ...D.Wq\.....#..
0010: 21 7B                                              !.
main, RECV TLSv1 ALERT:  warning, close_notify
main, called closeInternal(false)
main, SEND TLSv1 ALERT:  warning, description = close_notify
Padded plaintext before ENCRYPTION:  len = 18
0000: 01 00 8A 2C A2 36 9C 88   22 50 6E BC 95 3B B2 C4  ...,.6.."Pn..;..
0010: FE F2                                              ..
main, WRITE: TLSv1 Alert, length = 18
[Raw write]: length = 23
0000: 15 03 01 00 12 19 BE 10   8D FA F1 CA DD AB CC 91  ................
0010: 2E 49 08 71 2B C1 05                               .I.q+..
main, called close()
main, called closeInternal(true)
main, called close()
main, called closeInternal(true)
main, called close()
main, called closeInternal(true)